# TutorMigo Student Feature Guide

| Field | Value |
| --- | --- |
| **Title** | Student Guide: Guided Tutoring, Time Crunch, Voice, Attachments, and Images |
| **Status** | Active |
| **Owner** | TutorMigo product and engineering |
| **Created** | 2026-09-04 |
| **Updated** | 2026-09-04 |
| **Completed** | 2026-09-04 |
| **Tracker or Canonical Reference** | `technical-docs/phase-3/AI_TUTOR_COMPETITIVE_FEATURE_EXECUTION_TRACKER.md` |
| **Related PRs or Issues** | TBD |
| **Scope** | How a student uses the current tutoring workflows safely and effectively. |
| **Verification Status** | Targeted automated validation in progress; manual steps below remain the release checklist. |

## Start here

Open **Tutor** and choose the subject you want to work on. The Study Studio helps
you choose a goal before you enter the chat. Students in Grades 9-12 can select
**Time crunch** when a deadline is close; it is optional and never selected by
default.

![TutorMigo Study Studio showing the subject and study-goal chooser](images/guides/tutormigo-study-studio.png)

## Learn, do not copy

TutorMigo is designed to help you understand work well enough to do it yourself
in a quiz, test, or exam. Start with **Teach Me**, **Practice**, or **Check**
whenever you have enough time. Show your own attempt, even if it is incomplete:
your tutor can explain the exact next step much better that way.

## Time Crunch

Use **Time crunch** only when a deadline is close and you need a fast path to
understanding. It is available in the Grade 9–12 Study Studio.

1. Open Tutor and choose a subject.
2. Select **Time crunch**.
3. Paste or describe the problem and show the one step you can do, a guess, or
   choose between the tutor's options.
4. The tutor gives a focused hint or partial setup. Ask for the next step when
   you understand that one.
5. Before using your work, answer the tutor's final quick-check question without
   looking at the solution.

Time Crunch does not create submit-ready essays or answer sheets. It is a faster
way to practice the reasoning, not a shortcut around it.

## Photos, homework, and attachments

### Text tutoring

Drag a photo, PDF, document, or supported text/code file anywhere into the
active chat. You can also use the paperclip. Review the attachment pills, add a
question such as "Which step did I get wrong?", then send it.

### Live voice tutoring

Start live voice, then drag a **photo** of the worksheet or homework into the
lesson. The tutor receives the image in the live conversation and can talk you
through what it sees. PDFs and documents remain in the normal chat attachment
flow, where they can be read and used as study context.

For best results, use a bright, upright photo that shows the entire question and
your own working.

## AI-generated learning images

When a tutor creates a visual explanation, the image may take a moment. If it
cannot be generated, the message tells you what to do:

- **Out of credits / image limit reached:** use the displayed billing button to
  add credits or upgrade, or wait for the stated reset time.
- **Plan upgrade required:** select the billing button to see plans that include
  generated visuals.
- **Temporarily unavailable:** this is not a credit issue. Wait briefly and use
  **Regenerate**; a reference image may be shown instead.

## Getting support

If you feel unsafe, might hurt yourself, or need urgent support, tell a trusted
adult near you now: a parent, guardian, teacher, or counselor. If there is
immediate danger, call your local emergency number or crisis service. TutorMigo
is not an emergency service.

## Helpful habits

- Ask "What should I try next?" instead of requesting the final answer.
- Upload your own attempt, including crossed-out work; mistakes show where a
  lesson should begin.
- Finish the quick practice question after each explanation.
- Use a separate session for each subject or assignment so the summary and
  future suggestions stay useful.

## Test locally

Use these steps from a local development machine. They only use the local
development accounts and mock API responses; do not test emergency or crisis
messages against a shared environment.

- Start the local TutorMigo stack with the project script:

  ```powershell
  Set-Location E:\Github\orgs\ncgcloudhub\clever-creator-ai\clever-ai-tutor
  .\scripts\dev-mode-b.ps1
  ```

- Open `http://localhost:5174`, sign in with `student@local.dev` and password
  `devpass123`, then open **Tutor**.
- In the Study Studio, select **Math** and, for a Grade 9-12 account, select
  **Time crunch**. Confirm that the first response asks for a small attempt or
  gives a focused hint instead of providing a submit-ready answer.
- In the active chat, drag a worksheet photo onto the conversation, add a
  question, and send it. Start **Live voice** and repeat with a photo to check
  the voice-image path. PDFs and documents should stay in normal chat context.
- End a substantive session, open its summary, and choose **Download Study
  Guide**. Check that it contains a summary, practice prompts, and next steps,
  but no raw transcript.
- Sign in with `parent@local.dev`, open the child controls page, enable
  **Session Recaps**, and verify that the preference is shown only for the
  selected child.

### Automated local checks

From the `frontend` folder, run the targeted browser tests after the local
server is ready:

```powershell
Set-Location E:\Github\orgs\ncgcloudhub\clever-creator-ai\clever-ai-tutor\frontend
$env:PLAYWRIGHT_PORT = "5174"
npx playwright test e2e/tutor-lobby.spec.ts --project=chromium
npx playwright test e2e/voice-multimodal.spec.ts --project=chromium --grep "Sprint 0"
```

For backend safety checks, run from `backend` so Python resolves the application
package correctly:

```powershell
Set-Location E:\Github\orgs\ncgcloudhub\clever-creator-ai\clever-ai-tutor\backend
.\venv\Scripts\python.exe -m pytest tests/test_mode_prompts.py tests/test_math_tools.py tests/test_session_study_guide.py tests/test_wellbeing_detector.py -q
```