# TutorClaw Phone and Alerts Plan

## Purpose

TutorClaw should eventually support simple phone-based interaction and helpful alerts so users can reach TutorClaw outside the normal computer chat window.

This file defines the intended direction before any code is written.

The goal is not to make TutorClaw complicated. The goal is to make TutorClaw easier to use in real life.

TutorClaw should support practical communication methods such as:

* Phone chat through a messaging bridge
* Phone notifications
* Computer alerts
* Reminder-style messages
* Setup guidance for non-technical users
* Safe boundaries around what TutorClaw can and cannot do

---

## Core Product Idea

TutorClaw should become reachable in the places ordinary users already look:

* Their computer
* Their phone
* A simple chat app
* A notification or alert window

The user should not need to understand servers, APIs, tokens, ports, tunnels, or background processes.

A good user experience should feel like:

> “TutorClaw can talk with me on my computer, and when set up, it can also send simple helpful messages to my phone.”

---

## Why This Matters

Phone chat and alerts support TutorClaw’s main promise:

> TutorClaw helps users take one practical next step.

Many users will not sit at a computer all day. They may want to:

* Ask a quick question from the phone
* Get a reminder
* Receive a setup alert
* Know when something needs attention
* Continue a conversation away from the computer
* Use TutorClaw as a practical personal assistant

This feature should help TutorClaw feel more useful without making it feel intrusive.

---

## Beginner-Friendly Explanation

TutorClaw should explain phone and alerts in plain language.

Suggested explanation:

> TutorClaw can run on your computer, but some optional features may let you talk with it from your phone or receive simple alerts. These features need setup because TutorClaw must be connected safely to a phone messaging service or notification method.

Avoid saying:

* “Configure the bridge daemon”
* “Expose a webhook”
* “Authorize the bot token”
* “Bind the polling process”
* “Deploy the notifier service”

Use beginner wording instead:

* “Connect your phone chat”
* “Set up phone messages”
* “Turn on alerts”
* “Check that messages are working”
* “Stop alerts”
* “Restart phone chat”

---

## Planned Communication Modes

### 1. Computer Chat

This is the default TutorClaw experience.

The user opens TutorClaw on the computer and chats normally.

Computer chat should remain the safest baseline because it does not require phone setup.

TutorClaw should say:

> You can use TutorClaw normally from your computer without setting up phone chat.

### 2. Phone Chat

Phone chat means the user can send a message from a phone app and receive a TutorClaw response.

Possible implementation path:

* Telegram-style bot chat
* Local bridge script
* Approved user ID only
* Local `.env` settings
* Clear setup helper
* Safe restart option
* Simple status checker

Phone chat should be optional.

TutorClaw should not imply every user has it unless the feature is installed and configured.

Safe wording:

> If phone chat is installed and connected, you can send TutorClaw a message from your phone. If it is not connected yet, I can help you set it up step by step.

### 3. Phone Alerts

Phone alerts are short notifications sent to the user’s phone.

Possible uses:

* Reminder messages
* Setup success or failure messages
* “TutorClaw is running” confirmation
* “TutorClaw needs attention” notice
* Optional scheduled check-ins
* Optional lesson reminders

Phone alerts should not spam users.

The user should be able to turn alerts off.

TutorClaw should say:

> Phone alerts should be useful, rare, and under your control.

### 4. Computer Alerts

Computer alerts are local messages shown on the user’s computer.

Possible uses:

* Startup success
* Setup completed
* Missing API key
* Phone bridge disconnected
* Reminder message
* Lesson reminder
* Error that needs user attention

Computer alerts should use plain language.

Bad alert:

> Bridge process failed with exit code 1.

Better alert:

> TutorClaw phone chat stopped. You can restart it from the Start Phone Chat shortcut.

---

## What TutorClaw Should Be Able To Explain

TutorClaw should be able to answer:

* What is phone chat?
* Do I have to use phone chat?
* Can I use TutorClaw without my phone?
* Can TutorClaw text me?
* Can TutorClaw send alerts?
* Can TutorClaw remind me?
* Why do I need Telegram or another phone app?
* Why do I need a bot token?
* What is a user ID?
* Is this private?
* Can other people message my TutorClaw?
* How do I turn alerts off?
* How do I restart phone chat?
* What should I do if phone chat stops?

---

## Setup Philosophy

Phone and alert setup must be beginner-friendly.

The preferred user flow is:

1. User double-clicks a setup shortcut.
2. Setup explains what it will do.
3. User is asked for only the minimum needed information.
4. Setup checks the information.
5. Setup writes configuration safely.
6. Setup tests the connection.
7. Setup gives a plain-language result.
8. Setup provides a restart shortcut.
9. Setup provides a stop/disable option.

The user should not be expected to manually edit `.env` files.

The user should not be expected to paste commands into PowerShell unless absolutely necessary.

The user should not be expected to understand internal file paths.

---

## Important Safety Requirements

Phone chat and alerts must be safe by default.

Required safety principles:

* Phone chat must be optional.
* Only approved users should be allowed to message the assistant.
* Bot tokens must not be printed in logs.
* API keys must not be printed in logs.
* User IDs should be handled carefully.
* The assistant should not accept messages from unknown users.
* Alerts should not reveal sensitive private information by default.
* Users should be able to disable phone chat.
* Users should be able to disable alerts.
* Setup should clearly explain what information is being stored.

---

## Privacy Guidance

TutorClaw should explain that phone chat may involve a third-party messaging service.

Safe wording:

> If you use phone chat, your messages may pass through the phone messaging service before reaching TutorClaw. Do not send passwords, private financial information, medical records, or anything highly sensitive unless you understand where it is going.

TutorClaw should not promise:

* Perfect privacy
* That phone messages never leave the phone
* That Telegram or any other messaging provider is fully private
* That messages cannot be stored by outside services
* That alerts are secure enough for sensitive details

---

## Alerts Content Rules

Alerts should be short and practical.

Good alerts:

* “TutorClaw is ready.”
* “Phone chat is connected.”
* “Phone chat stopped. Restart it from Start Phone Chat.”
* “Reminder: review your lesson today.”
* “Your setup needs attention. Open TutorClaw on your computer.”

Avoid alerts that include:

* Full conversation history
* Passwords
* API keys
* Payment details
* Private medical details
* Long personal messages
* Sensitive account information

---

## Beginner-Friendly Commands and Shortcuts

TutorClaw provides simple Windows shortcut batch files in the project root to manage the connection:

*   **Check Phone Chat Status.bat:** Use Check Phone Chat Status.bat to see whether phone chat appears configured. (This performs local checks only and does not contact Telegram).
*   **Test Phone Chat.bat:** Use Test Phone Chat.bat to send one safe test message to your approved phone account. (This sends only a fixed, hardcoded message to verify the connection; it does not send conversation history, edit your configuration, or launch the background bridge).
*   **Start Phone Chat.bat:** Use Start Phone Chat.bat to start the phone chat listener.
*   **Restart Phone Chat.bat:** Use Restart Phone Chat.bat if phone chat seems stuck. Close any old phone chat window first. (This restarter does not kill processes automatically; it simply prompts you to close any duplicate windows manually before launching the new session).

**Stop Guidance:** There is not yet a separate safe Stop Phone Chat.bat. For now, stop phone chat by closing the Phone Chat window or pressing **Ctrl+C** inside that window. Do not tell users to kill Python processes.

---

## What TutorClaw Should Not Claim

TutorClaw should not claim:

* Phone chat is available before it is installed.
* Alerts are available before they are installed.
* It can call the user by voice unless voice calling exists.
* It can send SMS text messages unless SMS is actually implemented.
* It can access contacts unless contacts are connected.
* It can read phone notifications unless that feature exists.
* It can send emergency alerts.
* It can guarantee message delivery.
* It can keep all phone messages private from the messaging provider.
* It can run forever without the computer, server, or bridge staying online.

---

## Safe Response Templates

### User asks: “Can I use TutorClaw on my phone?”

Suggested response:

> Yes. This installed version of TutorClaw can connect to your phone through Telegram. WhatsApp is not the supported phone-chat method in this version.

### User asks: “How do I use my installed WhatsApp to talk to TutorClaw?”

Suggested response:

> This installed TutorClaw does not use WhatsApp for phone chat. It uses Telegram. To use TutorClaw on your phone, install Telegram, then run Start Phone Chat.bat on your computer and follow the setup steps.

### User asks: “How do I use Telegram with TutorClaw?”

Suggested response:

> To use Telegram with TutorClaw, you will need to set up a private Telegram bot. Make sure Telegram is installed on your phone. Then, run the **Start Phone Chat.bat** file in your TutorClaw folder on your computer. It will walk you through the setup steps, including creating a bot via Telegram's official @BotFather and whitelisting your Telegram account ID for safety.

### User asks: “Is TutorClaw part of Panaversity?”

Suggested response:

> This installed TutorClaw.Live version is not affiliated with Panaversity.

### User asks: “Can TutorClaw text me?”

Suggested response:

> TutorClaw may be able to send phone alerts if that feature is installed. It may use a phone chat app or messaging bridge rather than regular SMS. We should check which alert method is installed before assuming it can text you.

### User asks: “Can TutorClaw remind me?”

Suggested response:

> TutorClaw can help you create reminder text and, if alerts are installed, may be able to send reminder-style messages. If alerts are not installed yet, I can still help you make the reminder plan or checklist.

### User asks: “Is phone chat private?”

Suggested response:

> Phone chat may involve an outside messaging service, so it should not be treated as perfectly private. Avoid sending passwords, financial details, medical records, or highly sensitive information through phone chat.

### User asks: “Why do I need a bot token?”

Suggested response:

> A bot token is like the connection key that lets TutorClaw talk to the messaging service. It should be kept private. TutorClaw should help store it safely and should not print it in logs or share it.

### User asks: “What is a user ID?”

Suggested response:

> A user ID helps TutorClaw know which phone account is allowed to talk to it. This is important so strangers cannot message your TutorClaw.

---

## Recommended First Build Version

The first version should stay simple.

Recommended v1 scope:

* Optional phone chat through one supported messaging method
* Approved user only
* Setup helper
* Start shortcut
* Stop or disable shortcut
* Test message
* Basic phone alert
* Basic computer alert
* Plain-language troubleshooting
* No voice calling
* No SMS unless deliberately added later
* No automatic sensitive alerts
* No multi-user support unless intentionally designed

---

## Future Possibilities

Possible later upgrades:

* Lesson reminders
* Daily check-in messages
* Calendar-aware reminders if calendar is connected
* Email summary alerts if email is connected
* Voice input
* Voice responses
* Family/caregiver shared alerts
* Business workflow alerts
* Membership-related account alerts
* Mobile-friendly web dashboard

These should not be promised in the first version.

---

## Default Rule

TutorClaw should always distinguish between:

1. What is available now
2. What can be set up
3. What may be possible later

Suggested wording:

> I can help with that if the phone or alert feature is installed. If it is not installed yet, I can help you set it up or explain what would be needed.

---

## Final Design Standard

Phone chat and alerts should make TutorClaw easier to use, not harder.

The feature is successful when a beginner can understand:

* What phone chat does
* Whether they need it
* What information is required
* How to test it
* How to stop it
* What privacy limits apply
* What to do when it breaks

The goal is simple:

> Help the user stay connected to TutorClaw without creating confusion, false promises, or unsafe access.
