YouOS Usage Guide

First-time setup

./scripts/install.sh      # creates .venv, installs YouOS (+ MLX on Apple Silicon), runs the doctor
source .venv/bin/activate
youos doctor              # verify Python, Google backend, MLX, disk space
youos setup               # or open http://127.0.0.1:8765/welcome in the browser

The setup wizard configures your identity (and personalizes the app's name from your first name — e.g. Baher → BaherOS), your Google ingestion backend, ingests your sent history, and analyzes your writing style.

Drafting replies

Drafts run on your fine-tuned local model by default (Qwen + your LoRA, served warm). The cloud is only a cold-start before your model is trained, or an explicit fallback. A readiness gate shows a soft "preparing your voice model" banner until your model is trained and benchmarked — drafting still works meanwhile.

Via CLI

youos draft "paste the inbound email here"
youos draft --sender john@company.com --mode work "email text"

Via Web UI

1. Run youos serve to start the server
2. Open http://127.0.0.1:8765/feedback
3. Paste the inbound email, click Generate Draft (a per-draft badge shows which model ran)
4. Edit the draft as needed, then Submit Feedback

Inside Gmail (browser extension)

1. Install the YouOS extension from the repo's extension/ folder — the web UI's Gmail page (/bookmarklet) has one-click "Load unpacked" steps
2. Open an email → click the teal ✉ launcher → the panel opens
3. Sender + message auto-detected; add an instruction or pick a tone, click Generate
4. Insert into Gmail drops the draft in the reply box; rate 1–5 and Submit feedback

A bookmarklet remains as a no-install fallback (it can break when Gmail changes its markup).

Review Queue

The Review Queue shows real emails from your corpus with auto-generated drafts. Edit and rate each draft to train the model:

1. Open the web UI, click "Review Queue" tab
2. Review each draft — edit to match what you'd actually send
3. Rate 1-5 stars and submit
4. After 10 reviews, the system triggers autoresearch optimization

Which model sounds most like you?

# Drafts your held-out replies under each backend and scores them against what you
# actually wrote (voice-match), so you can verify the local model beats the cloud.
youos compare-models --limit 30 --semantic

Commands

Command	Description
youos setup	Run setup wizard
youos doctor	Check system requirements (Python, Google backend, MLX, disk)
youos status	Show system status
youos draft "text"	Generate a draft reply
youos triage [--window 3d] [--limit 8] [--dry-run]	Sweep unread inbox, filter, draft survivors; persists to agent_pending_drafts (view at /triage). Background loop opt-in via agent.enabled.
youos digest [--days 1] [--format text\|html\|json]	Print an agent-activity summary for the last --days days. Pipe to mail via cron for a daily email when you're away from /triage. See docs/REMOTE_ACCESS.md.
youos sync-labels [--label YouOS/skip]	Process Gmail-label dismissals: apply the label to a thread from any Gmail client to dismiss the queued row as noise. Auto-removes the label after processing. Also runs at the start of every triage sweep.
youos serve	Start the web server
youos ui	Open the web UI in your browser
youos service install	Run the server as a background service (starts at login)
youos stats	Print corpus statistics
youos corpus	Full corpus health report (pairs, quality, top senders)
youos improve [--verbose]	Run nightly pipeline manually
youos ingest	Ingest new emails (--whatsapp <export> for a chat export)
youos finetune	Run LoRA fine-tuning
youos eval [--golden]	Run benchmark evaluation
youos compare-models	Rank backends by how closely each sounds like you
youos model show / model set	Show / choose the drafting backend
youos model server status	Warm local-model server (loads the model once)
youos config list / get / set	View or change feature flags
youos note <email> "text"	Add a sender relationship note
youos feedback ...	Submit a feedback pair from the terminal