tinybeeai 0.0.0-stage → 0.16.1

package/docs/tinybee/04-local-setup-ui.md

@@ -0,0 +1,128 @@
+# TinyBeeAI — Local Setup UI (Laptop) Specification
+
+**Version:** 0.1 (draft) · **Date:** 2026-10-24
+**Companion to:** `03-local-agent.md`, `05-mobile-app-ux.md`
+
+---
+
+## 1. Purpose and philosophy
+
+The laptop UI exists for exactly three moments: **install → pair**, **something is red**, and **recovery**. Everything else lives on the phone. Therefore:
+
+- It is a single local web page at `http://localhost:7331/setup`, opened by the installer and the menu bar icon. No native window framework; works in any default browser.
+- One screen at a time, one primary action per screen, large type (a user may be reading it from across the desk while holding their phone).
+- Bilingual toggle (VI/EN) top-right; language follows OS locale by default.
+- Never shows anything the user must copy by hand except the 6-char fallback code.
+
+Visual language: warm cream background, dark text, one accent (honey yellow) for the primary action, green/amber/red strictly for status. Generous spacing, 18 px base font, QR ≥ 280 px.
+
+## 2. Screen flow
+
+```
+[0 Welcome] → [1 Health check] → [2 Pair (QR)] → [3 Connecting…] → [4 Done]
+                      ↑                                               ↓
+               [H Health & Fix] ◄──────────────────────────── [S Status (steady state)]
+                                                                      ↓
+                                                        [R Recovery / Advanced]
+```
+
+## 3. Screens
+
+### Screen 0 — Welcome (auto-advances after 2 s unless user hovers)
+- Logo + "Setting up your Bee on **DESKTOP-LAN-01**".
+- Sub: "This takes about a minute. Keep your phone nearby."
+- Button: **Start**. Link: "I don't have the app yet" → shows store QR + short URL.
+
+### Screen 1 — Health check
+- Title: "Checking this laptop…"
+- Animated list; each item resolves to ✓ / ! / ✕ with one-line message.
+
+  | Item | Copy (pass) | Copy (issue) + action |
+  |---|---|---|
+  | Internet | "Connected" | "No internet — connect to Wi-Fi and retry" [Retry] |
+  | TinyBee cloud | "Reachable" | "Can't reach TinyBee. A firewall or VPN may be blocking it." [Learn more] |
+  | Memory & disk | "8 GB RAM · 112 GB free" | "Only 3.2 GB RAM — your Bee will work but run slowly." |
+  | Power settings | "Laptop stays awake when plugged in" | "Laptop will sleep when lid closes" [Fix this for me] |
+  | Plugged in | "On AC power" | "Running on battery — plug in for 24/7 use" |
+  | Time & date | "Clock is accurate" | "Clock is off by 6 minutes — this breaks secure login" [Sync now] |
+  | AI providers | "Ready (TinyBee relay)" + "Local AI found: Ollama (2 models)" | "No AI provider reachable" |
+
+- Footer: **Continue** (enabled if no ✕ blockers), or **Continue anyway** when only ! items remain, with warning text.
+- Detail chevron on each row reveals technical detail and "Copy diagnostics" for support.
+
+### Screen 2 — Pair with your phone
+- Large QR (regenerates every 10 min; subtle countdown ring; "Refresh" link).
+- Headline: "Scan with the TinyBee app"
+- Three tiny steps under the QR: "Open the app → tap **Add my laptop** → scan".
+- Divider: "No camera? Enter this code in the app:" — **K7M2PQ** (monospace, large) with [Copy].
+- Laptop name field (pre-filled, editable): "Name this Bee: `Office laptop`".
+- Status strip at bottom: "Waiting for scan…" (pulsing dot). On scan detected → transitions immediately.
+- Edge text: "Nothing is sent until you confirm on your phone."
+
+### Screen 3 — Connecting…
+- Stepper with live states, each ≤ 10 s typical:
+  1. "Phone confirmed ✓"
+  2. "Creating your address · hong.tinybee.app" (spinner → ✓)
+  3. "Opening secure tunnel" (spinner → ✓)
+  4. "Saying hello to your phone" (spinner → ✓)
+- If a step exceeds 30 s: inline helper "Taking longer than usual… [Retry] [Get help]". Never a raw error string on the main line; technical detail under a chevron.
+
+### Screen 4 — Done
+- Big ✓ "Your Bee is online"
+- "Address: **hong.tinybee.app** (only you can open it)"
+- "You can close this window. Your Bee runs in the background — look for the 🐝 icon in the menu bar."
+- Secondary: "Keep this laptop plugged in and don't shut it down. Closing the lid is fine." (shown only if power fix applied; otherwise the warning variant.)
+- Button: **Finish** (closes tab). Small link: "Open status page".
+
+### Screen S — Status (steady state; what the menu bar app opens after pairing)
+Card layout, read-only, auto-refreshing:
+- **Header**: 🟢 Online · hong.tinybee.app · Bee v1.2.0 · Uptime 6d 4h
+- **Card: Health** — last check 2 h ago · 7/7 OK · [Run check]
+- **Card: Activity** — "Last run: Parent tuition emails · 3 min ago · OK" · "Runs today: 48 · Approvals waiting: 1 (open the app)"
+- **Card: Connection** — Tunnel: connected (QUIC) · Phone last seen: 10 min ago
+- **Card: Power** — On AC · Stay-awake: enabled
+- Footer links: "Pause all workflows", "Logs folder", "Advanced", "Unpair this laptop".
+
+States of the header:
+- 🟢 Online — tunnel up, Hive reachable.
+- 🟡 Local only — workflows running, but tunnel down or plan suspended. Shows reason: "Trial ended — your Bee still works here, but remote access is paused. Upgrade in the app." or "Reconnecting tunnel… (attempt 6)".
+- 🔴 Problem — service degraded; shows top failing check and its fix button.
+- ⚪ Not paired — shows Screen 2.
+
+### Screen H — Health & Fix
+Same table as Screen 1 but persistent, with per-row [Fix] / [Retry] and "Copy diagnostics" / "Send to support (opt-in)" at the bottom.
+
+### Screen R — Recovery / Advanced (behind a "Show advanced" toggle)
+- Re-pair (shows new QR; warns it replaces phone link).
+- Restart service · Check for updates · Roll back to previous version (shows version & date).
+- Data: folder location · retention · [Export workflows YAML] · [Delete all data].
+- Network: protocol (auto/QUIC/HTTP2) · proxy detected · [Test tunnel].
+- Developer: enable local LAN access to API (off) · log level · open logs.
+- Everything here has a one-line explanation of consequences before confirming.
+
+## 4. Menu bar icon states and menu
+
+| Icon | State | Tooltip |
+|---|---|---|
+| 🐝 (yellow) | Online | "TinyBee · Online · hong.tinybee.app" |
+| 🐝 (grey) | Local only | "TinyBee · Running locally · remote access paused" |
+| 🐝 (red dot) | Problem | "TinyBee · Needs attention: <top issue>" |
+| 🐝 (outline) | Not paired | "TinyBee · Scan to connect" |
+
+Menu: Open status · Pause/Resume workflows · Run health check · Check for updates · Open logs · Quit menu bar app (daemon keeps running).
+
+macOS notifications: "Paired with your phone ✓", "Bee is running locally only (tunnel down for 5 min)", "Update installed: v1.2.1", "An approval is waiting in the app".
+
+## 5. Copy guidelines
+
+- Say "your Bee", never "the daemon/service/agent".
+- Never show "Cloudflare", "tunnel token", "JWT", "Keychain" on a primary line. Technical words only under "Details".
+- Errors: what happened → what it means for you → one thing to do. Example: "Can't reach TinyBee cloud. Your workflows still run here, but your phone can't connect. Check if a VPN is on, then Retry."
+- Vietnamese copy is written natively, not translated literally; tone is friendly-professional ("Bee của bạn đã sẵn sàng").
+
+## 6. Accessibility & technical
+
+- Keyboard navigable; focus rings; all status conveyed by icon + text + colour (never colour alone).
+- Works on Retina and non-Retina displays, 100–200% scaling.
+- Page served only on `127.0.0.1`; CSRF token on every action; actions require the local socket secret the menu bar app passes in the URL on open (prevents another local user/browser tab from driving it).
+- No external assets (fonts/CSS inline) so the page works fully offline.

package/docs/tinybee/05-mobile-app-ux.md

@@ -0,0 +1,199 @@
+# TinyBeeAI — Mobile App UI/UX Specification
+
+**Version:** 0.1 (draft) · **Date:** 2026-10-24
+**Platforms:** iOS 16+, Android 10+ (single codebase recommended: Flutter or React Native)
+**Companion to:** `01-PRD.md`, `02-architecture-pairing.md`, `03-local-agent.md`
+
+---
+
+## 1. Experience principles
+
+1. **The phone is the remote control, the laptop is the engine.** Every screen reflects the Bee's real state; nothing is "stored in the app" except session and preferences.
+2. **Glanceable first, deep second.** Home answers "is it running, what happened, what needs me" in under 3 seconds. Depth is one tap away.
+3. **Plain language over automation jargon.** No "triggers/nodes/webhooks" in primary UI. Users describe what they want; the app shows what the Bee understood.
+4. **Nothing happens behind the user's back.** Sends and writes default to approval. The Activity log is complete and readable.
+5. **Degrade gracefully.** Offline Bee, expired trial, lost connection — all have designed states with a next step, never a blank error.
+
+## 2. Information architecture
+
+```
+Tab bar (5):
+  🏠 Home        — status, digest, approvals, quick actions
+  💬 Chat        — threads with the Bee
+  ⚡ Workflows   — list, skills library, editor, run history
+  🔗 Connections — third-party accounts
+  ⚙️ More        — Bee & laptop, notifications, plan & billing, account, help
+
+Global:
+  • Status pill in top bar on every screen (🟢 Online / 🟡 Local only / 🔴 Offline)
+  • Approval badge on Home tab
+  • Pull-to-refresh everywhere → live `/events` WS when foregrounded
+```
+
+## 3. Onboarding & pairing
+
+### 3.1 Flow (target ≤ 8 taps)
+```
+Splash → Value carousel (3 cards, skippable)
+ → Sign up (Email OTP | Google | Apple)
+ → Choose your address  ("hong" .tinybee.app, availability check, suggestions)
+ → Quick profile (chips, multi-select): I use… [Gmail] [Google Drive/Sheets] [Zalo OA] [Facebook Page] [Other]
+                                        I am… [Business owner] [Freelancer] [Student/Researcher] [Just exploring]
+ → "Now install TinyBee on your laptop"  (short URL, 6-char code, "I've installed it → Scan QR")
+ → Scanner (camera) | Enter code
+ → Confirm laptop: "Office laptop (DESKTOP-LAN-01)" + health summary chips → [Connect]
+ → Provisioning (3 steps, animated) → "🟢 Your Bee is online!"
+ → Starter skills (3 cards tailored to chips) → pick one → Connect account → Done → Home
+```
+
+### 3.2 Screen details
+
+**Value carousel** — 3 cards: "Runs 24/7 on your own laptop", "Your data stays with you", "Set up in 2 minutes". Each with a simple illustration (bee + laptop + phone). "Skip" top-right.
+
+**Choose your address** — Big input with suffix `.tinybee.app`, live availability (✓ / taken → 3 suggestions), rule hint "letters, numbers, hyphen · 3–20 chars". Note: "You can change this once later."
+
+**Install prompt** — Illustration of laptop screen with QR. Text: "On the laptop you want to use, open **tinybee.app/get** and install. When you see a QR code, come back here." Code card: `K7M2PQ` with timer "expires in 9:41 · Refresh". Primary: **Scan QR code**. Secondary: **Enter code instead**. Tertiary: "I'll do this later" → Home in *not-paired* state.
+
+**Scanner** — Full-screen camera, framed guide, torch toggle, "Enter code" link. On decode: haptic + immediate transition (no extra tap).
+
+**Confirm laptop** — Card: laptop name (editable), OS, RAM, disk, power ✓/!. Warnings as amber chips with "Fix on laptop" hint. If tenant already has a Bee: red card "This will replace 'Old laptop'". Primary: **Connect**.
+
+**Provisioning** — Three rows animate: "Creating hong.tinybee.app", "Opening secure tunnel", "Connecting to your laptop". Each ✓ with timing. Over 30 s → "Taking longer than usual…" with Retry; over 90 s → troubleshooting sheet (laptop online? internet?).
+
+**Starter skills** — 3 cards chosen by profile chips, e.g. for [Gmail]+[Business owner]: "Flag urgent customer emails", "Morning inbox digest", "Watch a Sheet for missing entries". Each card: name, one-sentence outcome, accounts needed, "~1 min setup". Pick → goes straight to that skill's guided setup (§6.3). "Skip for now" available.
+
+## 4. Home
+
+### Layout (top → bottom)
+1. **Bee status card** — Bee name, status pill, "Last run 3 min ago · 48 runs today", tiny sparkline of runs/hour. Tapping opens *Bee & laptop*. In degraded states this card expands with cause + action (see §10).
+2. **Needs you** (only if any) — approval cards: avatar/icon, "Bee wants to **send a reply** to Nguyễn Văn A", preview 2 lines, buttons **Approve** · **Edit** · **Deny**; swipe right = approve, left = deny (with undo toast 5 s). Counter "2 more".
+3. **Today's digest** — collapsible sections per workflow: "Parent tuition emails — 3 new, 1 urgent", bullet summaries, each bullet deep-links to the source item in Chat context ("Ask about this"). "Generated 07:00 · Regenerate".
+4. **Quick actions** — horizontal chips: "Ask Bee", "Run a check", "Add workflow", "Connect account".
+5. **Recent activity** — last 5 runs with status dots; "See all" → Activity.
+
+Empty state (paired, no workflows): illustration + "Your Bee is ready and bored. Give it something to watch." → [Browse skills] [Describe it in chat].
+
+## 5. Chat
+
+- Thread list: "New chat" + recent threads (titles auto-generated). Pinned thread "Bee" for general conversation.
+- Message view: streaming responses; markdown; tables render natively; tool activity shown inline as collapsible "🔍 Searched Gmail (3 results)" rows so the user sees what the Bee did.
+- Composer: text, mic (speech-to-text), attach (photo, file, share-sheet from other apps → "Ask Bee about this").
+- Quick replies after a Bee message when relevant: "Draft reply", "Make this a workflow", "Remind me tomorrow".
+- "Make this a workflow": Bee proposes a workflow card (name, trigger, what it checks, actions, permissions) → user edits in guided editor → save. This is the primary creation path for non-technical users.
+- Actions proposed in chat (send, write) always render as an **action card** with Approve/Edit/Deny — identical component to Home approvals.
+- Model picker per thread (Quick / Smart / Local) with a one-line cost hint; default Smart for chat.
+
+## 6. Workflows
+
+### 6.1 List
+- Segmented control: **Active** · **Paused** · **All**.
+- Row: icon by category, name, trigger summary ("Every 10 min, 7:00–21:00"), last run status dot + relative time, toggle switch.
+- Swipe: Run now · Pause · Duplicate · Delete.
+- FAB: **+ Add** → sheet: "Describe what you want" (chat) | "Start from a skill" | "Advanced: import YAML".
+
+### 6.2 Skills library
+- Grid of cards grouped: Inbox & messages · Sheets & documents · Reports & digests · Reminders · Website & monitoring.
+- Card → detail: what it does (3 bullets), example output screenshot, accounts needed, default schedule, "Used by 1.2k Bees" (anonymous counter), **Use this skill**.
+
+### 6.3 Guided editor (one screen, sections as cards)
+1. **Name** — editable, emoji picker.
+2. **When** — segmented: *On a schedule* (friendly picker: every N minutes/hours, time window, days; shows next 3 run times) · *When something happens* (events available for connected accounts) · *Only when I ask*.
+3. **Watch** — account + natural filter ("emails mentioning tuition or fee from parents"); the Bee shows the technical query it derived under "Details" (editable).
+4. **Do** — instruction text (what to look for, how to summarise), language of output, output actions as toggles: Notify me (push) · Add to digest · Label/Move · Write to Sheet · Draft reply · Send reply.
+5. **Permissions** — per action: Auto · Ask me · Off, with default badge. Sends default to **Ask me**.
+6. **Limits** — model tier (Quick/Smart/Local), max run time, token budget per run (plain-language estimate: "≈ 0.4₫… / run" or "uses ~1% of monthly budget").
+7. **Test** — **Run a test now** → shows a live run (§6.4) without sending anything (dry-run flag).
+8. Save → toggled Active with confirmation toast "Running every 10 min. Next: 14:50".
+
+### 6.4 Run detail
+- Header: workflow, status (OK / Warning / Failed / Needs approval / Cancelled), started, duration, cost (tokens → money estimate).
+- Timeline: Input fetched (count) → Bee reasoning summary (one paragraph, not raw chain-of-thought) → Tool calls (collapsible rows with request summary and result count) → Outputs (push sent, digest appended, sheet updated — each tappable to the artifact) → Approvals (if any).
+- Buttons: **Run again**, **Open workflow**, **Report a problem** (attaches run id only, content excluded unless user opts in).
+
+## 7. Connections
+
+- List: provider icon, account identifier (e.g. `hong@gmail.com`), status (Connected / Needs re-login / Limited scopes), used by N workflows.
+- Add: provider grid (Gmail · Google Drive/Sheets · Google Calendar · Zalo OA · Facebook Page · Custom API key) → scope explainer sheet: "TinyBee on your laptop will be able to: read your emails, apply labels. It will NOT be able to: send email (unless you enable it later), delete anything." → **Continue to Google** (system browser) → return → ✓ with "stored on your laptop only" note.
+- Detail: scopes, last used, token health, "Test connection", "Remove" (lists affected workflows first).
+
+## 8. Activity (reached from Home → See all, and from More)
+
+- Filter chips: All · Needs approval · Failed · Sent/wrote something · Workflow picker · Date.
+- Rows grouped by day; tap → Run detail.
+- Search across summaries.
+- Export (CSV) for the selected range; generated by the Bee and downloaded through the tunnel.
+
+## 9. More
+
+### Bee & laptop
+- Bee name, address, version (update available → **Update now** / auto at night toggle), uptime, laptop name, OS, power status.
+- **Health** — same table as laptop UI; remote **Run check**; fixable items show "Fix on laptop" with instructions (can't change power settings remotely; can trigger time sync and protocol switch).
+- Actions: Pause all workflows · Restart Bee · Roll back update · Re-pair (new laptop) · **Kill switch** (stops all outbound actions immediately; red, confirm) · Unpair.
+- Data & retention: logs 30/60/90 days, chat retention, cache size, **Export workflows (YAML)**, **Wipe laptop data**.
+
+### Notifications
+- Master toggle; categories: Approvals (always on unless kill), Urgent findings, Digest (time picker), Bee offline, Updates, Billing.
+- Quiet hours (default 22:00–07:00, approvals still delivered as silent badge).
+- Per-workflow override link.
+
+### Plan & billing
+- Plan card: Trial — "17 days left" progress; Standard/Pro with renewal date.
+- Usage meter: bundled tokens used / cap with per-workflow breakdown ("Parent tuition emails 41%"); BYOK shows "Using your own key — no bundled usage".
+- Upgrade sheet: plan compare, local payment methods first (MoMo, ZaloPay, bank QR), card.
+- Clear copy of the rule: "If your plan ends, your Bee keeps running on your laptop. Only remote access and notifications pause."
+- Invoices list.
+
+### Account
+- Email, sign-in methods, 2FA, language (VI/EN), change address (once), **Delete account** (3-step: export offered → consequences → type address to confirm).
+
+### Help
+- Guided troubleshooting ("Bee is offline", "Can't pair", "Gmail disconnected"), FAQ, contact (in-app chat to support; diagnostics attached only with consent), What's new.
+
+## 10. Degraded and edge states (designed, not accidental)
+
+| State | Home status card | Behaviour elsewhere |
+|---|---|---|
+| **Bee offline** (no heartbeat 5 min) | 🔴 "Offline since 14:02 · Laptop may be asleep or without internet" → [Troubleshoot] [Notify me when back] | Workflows read-only; chat shows last messages with banner "Your Bee is offline — messages will send when it's back" (queued locally up to 24 h) |
+| **Local only** (plan suspended / tunnel down) | 🟡 "Running locally · remote access paused" + reason + [Upgrade] or [Retry] | Everything read-only from cache; approvals can't be acted on |
+| **Not paired** | ⚪ "No laptop connected" → [Set up a laptop] | Workflows/Connections tabs show explainer |
+| **Bundled tokens exhausted** | 🟡 banner "Monthly AI budget used · workflows paused" → [Top up] [Add my own key] | Run detail shows "Paused: budget" |
+| **Connection needs re-login** | amber card "Gmail needs you to sign in again" → [Reconnect] | Affected workflows show warning badge |
+| **Update available / failed** | info chip / 🔴 with [Roll back] | — |
+| **Phone offline** | top bar "No internet"; cached data with timestamps | Composer disabled with explanation |
+| **Mismatched versions** | "Update the app to use new features" (soft) or hard block if API incompatible | — |
+
+## 11. Notification design
+
+- Approval: "Bee wants to send a reply to Nguyễn Văn A" — actions **Approve** / **View** (Android actionable; iOS category). Collapse key per approval.
+- Urgent finding: "🔴 Urgent: tuition email from Trần Thị B — 'con em nghỉ…'" → deep link to digest item.
+- Digest: "Your 7:00 report is ready — 3 items, 1 needs you".
+- Offline: one at 5 min; one daily while offline; "Back online ✓" once.
+- Payloads carry no sensitive body text beyond a short summary the Bee chose to include; full content loads from the Bee.
+
+## 12. Visual & interaction design
+
+- **Palette**: cream background `#FFF8E7`, ink `#1F1B16`, honey accent `#F5B700`, status green `#2E9E5B`, amber `#E0A100`, red `#D64545`. Dark mode: charcoal `#15130F` with same accent.
+- **Type**: system fonts (SF / Roboto) with Dynamic Type; headings 24–28, body 16–17, meta 13.
+- **Components**: one shared *Action card* (approval) used in Home, Chat, Runs; *Status pill*; *Health row*; *Workflow row*; *Run timeline*.
+- **Motion**: subtle; bee icon pulses when Bee is "thinking" during chat; provisioning steps slide-check.
+- **Haptics**: success on pair, approval; warning on deny.
+- **Illustrations**: friendly geometric bee, laptop, phone; no stock photos.
+
+## 13. Accessibility & localization
+
+- WCAG 2.1 AA contrast; all icons labelled; VoiceOver/TalkBack order follows visual order; approvals operable via buttons, not only swipes.
+- Dynamic type up to 200% without truncating critical text.
+- vi-VN and en-US; numbers, currency (₫/$), dates localized; Vietnamese copy reviewed natively.
+- Right-to-left not required for v1.
+
+## 14. Analytics events (privacy-safe)
+
+`signup_complete`, `slug_chosen`, `install_prompt_shown`, `qr_scanned`, `pair_success` (+duration), `pair_fail` (+reason code), `first_workflow_created` (+source: chat/skill/yaml), `approval_decided` (+decision), `offline_push_sent`, `trial_upgrade_shown`, `upgrade_complete`, `connection_added` (+provider). No content, no identifiers beyond tenant id hash.
+
+## 15. Open UX questions
+
+1. Should approvals be editable inline (text field in the card) or always open an editor? Lean: inline for ≤ 3 lines, editor otherwise.
+2. Digest time: one global time, or per-workflow? Lean: global default 07:00 with per-workflow opt-out.
+3. Do we show cost in money or in tokens/percent? Lean: percent of monthly budget with ₫ estimate on tap.
+4. How much "Bee reasoning" to show in run detail — summary only (default) vs. "Show thinking" toggle for Persona C.
+5. Widget/Live Activity (iOS) for Bee status and pending approvals — v1 or v1.5?

package/docs/tinybee/06-environments-and-delivery.md

@@ -0,0 +1,148 @@
+# TinyBeeAI — Environments, Build & Delivery
+
+**Version:** 0.1 (draft) · **Date:** 2026-10-24
+**Companion to:** `01-PRD.md`, `02-architecture-pairing.md`, `07-coding-agent-handoff.md`
+**Reuses:** localdost `docs/DEPLOY.md` (Railway recipe, env vars), `.railway/railway.ts`, `client/` (existing PWA with `manifest.webmanifest` and VAPID web push)
+
+---
+
+## 1. Environments
+
+| Env | Where | URL | Purpose |
+|---|---|---|---|
+| **local** | developer / coding-agent machine | `http://localhost:4319` (server + Vite client) | Unit, e2e, demo mode (`LOCALDOST_DEMO=1`, mock LLM) |
+| **dev/staging** | Railway, project `localdost`, one service per component | `https://dots.testllms.com` | Shared build-and-test target. The PWA is served and tested here. Treated as **staging**: may break, data is disposable. |
+| **prod** | Railway (later: separate project) | `https://app.tinybee.app` + `*.tinybee.app` tenants | Not provisioned yet. Nothing in these docs assumes prod exists. |
+
+Rule: **every change is verified on `dots.testllms.com` as a PWA before any APK/IPA is cut.** Store builds are a packaging step, not a test step.
+
+### 1.1 What runs on Railway at dots.testllms.com
+
+Because the laptop Bee is not always available during development, staging hosts **both** halves so the mobile client can be tested end-to-end without a laptop:
+
+| Railway service | Role | Notes |
+|---|---|---|
+| `hive` | Hive control plane: auth (email OTP / Google), tenants, pairing, Cloudflare provisioning, push relay, metering, plan state | New service. Node + SQLite (or Postgres plugin once tenants > 1k). Public at `dots.testllms.com/api/hive/*` or its own subdomain `hive.testllms.com` — pick one and record it in `.railway/railway.ts`. |
+| `bee-dev` | A **cloud-hosted Bee**: the localdost server itself, running as if it were tenant `dev`'s laptop | Existing localdost image. Lets the mobile app exercise workflows, chat, approvals, Inbox before the macOS packaging exists. Reached at `dots-dev.testllms.com` via Cloudflare tunnel **or** directly via Railway domain during early dev. |
+| `web` | Serves the mobile client as a PWA (`client/` build) | Can be the same process as `bee-dev` (localdost already serves its client) during early dev; split out once the Hive-aware client diverges from the localdost admin UI. |
+
+Decision (2026-10-24): Hive has no subdomain of its own. It is reached through the Bee origin at `dots.testllms.com/api/hive/*` (the `localdost`/`bee-dev` service proxies `/api/hive/*` to the private `hive` service when `TINYBEE_HIVE_URL` is set), so the PWA, the Bee API and Hive share one origin and one cookie jar. `.railway/railway.ts` records this.
+
+DNS: `dots.testllms.com` → Cloudflare zone `testllms.com`. Tenant hostnames are **one level under the zone**, `dots-<slug>.testllms.com` in staging (`dots-dev.testllms.com`, `dots-hong.testllms.com`) and `<slug>.tinybee.app` in prod, configured as a pattern in `TINYBEE_TENANT_HOST` (`dots-{slug}.testllms.com`). One level keeps every tenant under Cloudflare's zone certificate (`*.testllms.com`); a second level (`hong.dots.testllms.com`) would need Advanced Certificate Manager.
+
+#### Hosting pattern: the same as Superapp
+
+Superapp (`~/workspaces/superapp`) is the model: one Railway project in the same workspace, one `web` service, and every public name (`superapp.testllms.com`, `admin.testllms.com`, `testllms.com`) is a **custom domain on that Railway service** with a proxied CNAME in the Cloudflare zone pointing at the Railway domain. The process tells the names apart by the `Host` header (Fastify host constraints; `ADMIN_HOST`). Deploys run from GitHub Actions on push to `main` (`railway up --ci --service web` with a project token in `RAILWAY_TOKEN`), followed by a health check loop on the public URL. TinyBee staging follows that recipe:
+
+- Railway project `localdost` (workspace "Huy Dao's Projects", next to `superapp`; decided 2026-10-24, the existing project is reused instead of a new `localdost` one), declared in `.railway/railway.ts`: service `localdost` (the Bee origin, serves the PWA, proxies `/api/hive`; Railway domain `localdost-production.up.railway.app`) and service `hive` (private, `hive.railway.internal:4330`, own volume; `LOCALDOST_ROLE=hive` turns the shared image into the Hive).
+- Custom domain `dots.testllms.com` on service `localdost`; Cloudflare CNAME, proxied. Tenant names `dots-<slug>.testllms.com` are **not** Railway domains: Hive creates them as Cloudflare Tunnel public hostnames (CNAME to `<tunnel>.cfargotunnel.com`), the mock provider only names them.
+- Superapp's admin console already has a `tinybee` tenant that takes events at `POST https://admin.testllms.com/api/_ingest/tinybee` (key in Superapp's `ADMIN_INGEST_KEYS`). Hive can report sign-ups and pairings there later; nothing in Phase 0 to 2 depends on it.
+- `.github/workflows/deploy.yml` (to add once the project exists) mirrors Superapp's: `railway up --ci --service localdost` and `--service hive`, then `curl https://dots.testllms.com/api/hive/health`.
+
+### 1.2 Environment variables (additions to localdost `.env.example`)
+
+| Var | Service | Meaning |
+|---|---|---|
+| `TINYBEE_ENV` | all | `local` · `staging` · `prod` |
+| `TINYBEE_HIVE_URL` | bee, web | Base URL of a separate Hive. On Railway the private address `http://hive.railway.internal:4330`; the Bee proxies `/api/hive/*` there. Unset with `TINYBEE_ENV=local`: Hive runs inside the localdost process. |
+| `TINYBEE_HOME` | bee | Where `npx tinybeeai install` keeps the Bee's data (default `~/.tinybee`; `--dir` on the command line wins) and, under `bin/`, the cloudflared it downloads when PATH has none (pinned in `src/bee/cloudflared.ts`, SHA256-checked). The command also fills `TINYBEE_ENV=staging`, `TINYBEE_HIVE_URL=https://dots.testllms.com`, `PORT=4319` and `LOG_LEVEL=warn` when the shell leaves them unset. |
+| `TINYBEE_TENANT_HOST` | hive | Tenant hostname pattern with `{slug}`: `dots-{slug}.testllms.com` (staging) / `{slug}.tinybee.app` (prod). `TINYBEE_TENANT_DOMAIN=<domain>` is the short form `{slug}.<domain>`. |
+| `TINYBEE_TUNNEL_PROVIDER` | hive | `cloudflare` or `mock`. Unset: `cloudflare` when the three `CF_*` vars are set, else `mock`. |
+| `HIVE_PORT`, `HIVE_DATA_DIR`, `HIVE_DB` | hive | Standalone Hive port (4330) and storage (`hive.db` in the data dir) |
+| `CF_ACCOUNT_ID`, `CF_ZONE_ID`, `CF_API_TOKEN` | hive | Cloudflare API (token scoped: Tunnel:Edit, DNS:Edit, Access:Edit on the one zone) Set on the Railway `hive` service since 2026-10-25; the service also answers at `localdost.testllms.com` (proxied CNAME) for direct checks. |
+| `HIVE_JWT_PRIVATE_KEY`, `HIVE_JWT_KID` | hive | RS256 signing key for tenant JWTs; JWKS served at `/.well-known/jwks.json` |
+| `HIVE_MAIL_PROVIDER` | hive | How sign-in codes are sent. `console` (default; writes the code to the Hive log, refused when `TINYBEE_ENV=prod`). A real sender is OPEN-QUESTIONS item 4. |
+| `HIVE_GOOGLE_CLIENT_ID` | hive | Google OAuth web client id for "Continue with Google". Unset: the sign-up offers email codes only. |
+| `HIVE_RELAY_ANTHROPIC_KEY`, `HIVE_RELAY_ANTHROPIC_URL` | hive | Provider key for the Hive's own model (Phase 6 relay; never shipped to the Bee) and the provider base URL (default `https://api.anthropic.com`). App-side features only: since Phase A the Bee never routes host work through it (02 section 7). Unset key: the relay answers 503 `relay_unconfigured`. |
+| `HIVE_VAPID_PUBLIC_KEY`, `HIVE_VAPID_PRIVATE_KEY`, `HIVE_VAPID_SUBJECT` | hive | Web push from the Hive (offline / back online, Phase 4). Unset: a key pair is generated into `hive-vapid.json` in the data dir (0600) and kept across restarts. Set them on Railway so a volume reset does not orphan the phones' subscriptions. |
+| `FCM_SERVICE_ACCOUNT_JSON` | hive | Firebase service-account JSON (the whole document) for FCM v1 native push to Android (Phase 7). Unset: Android device tokens are accepted but nothing is sent. |
+| `APNS_KEY_P8`, `APNS_KEY_ID`, `APNS_TEAM_ID`, `APNS_BUNDLE_ID`, `APNS_ENV` | hive | APNs auth key (PEM text), its key id and team id, the app bundle id (default `ai.tinybee.app`) and `production` or `sandbox` (Phase 7). |
+| `HIVE_BEE_UPDATE_PUBKEY`, `HIVE_BEE_UPDATES_DIR` | hive | Public id of the Bee release key (`ed25519:…`); `PUT /api/hive/admin/updates/bee/:channel` refuses a manifest not signed by it. Manifests are kept under the dir (default `<data dir>/updates`). |
+| `TINYBEE_UPDATE_PUBKEY`, `TINYBEE_UPDATE_URL`, `TINYBEE_UPDATE_CHANNEL`, `TINYBEE_UPDATE_APPLY` | bee | The Bee updater: release key (unset: updater off; the pkg postinstall writes it from `release.pub`), manifest URL (default `<hive>/api/hive/updates/bee/<channel>`), `stable` or `beta`, and `auto` (write the apply request when idle; the pkg default) or `off` (stage only, the default elsewhere). |
+| `TINYBEE_ANDROID_PACKAGE`, `TINYBEE_ANDROID_CERT_SHA256`, `TINYBEE_IOS_APP_ID` | web | App Links / Universal Links: `/.well-known/assetlinks.json` needs the package name and the signing certificate fingerprints (comma-separated, `AA:BB:…`), `/.well-known/apple-app-site-association` needs `TEAMID.bundle`. Unset: the files answer 404. |
+| `TINYBEE_DEVICE_KEY_PATH` | bee | Where the Bee stores its Ed25519 key (macOS: encrypted with Keychain-held key; Railway bee-dev: `/data/device.key`) |
+| `TINYBEE_TUNNEL` | bee | `off` never starts `cloudflared` (local dev, tests). Mock tokens (`mock.`) never start it either. |
+| `TINYBEE_BEE_PORT` | hive | Port the tunnel ingress points at on the laptop (default: the localdost port, 4319). |
+| `TINYBEE_TUNNEL_CAP` | hive | Tunnel cap reported by `GET /api/hive/admin/tunnels` (default 50; `ok` turns false above 40). |
+| `HIVE_ADMIN_TOKEN` | hive | Bearer for `/api/hive/admin/*`. Unset: those routes answer 404. Long random string; set per environment. |
+| `TINYBEE_PAIRED` | bee-dev only | `1` pre-pairs the cloud Bee to tenant `dev` at boot so staging never shows a QR |
+
+Secrets go in via `railway variable set … --stdin` exactly as `docs/DEPLOY.md` prescribes. Never commit them, never paste them in chat or PR descriptions.
+
+## 2. Mobile client: one codebase, three packages
+
+The mobile app is **the existing localdost `client/` (Vite + PWA) evolved**, not a second app. Build targets:
+
+| Target | How | Used for |
+|---|---|---|
+| **PWA** | `vite build` → served by `web`/`bee-dev` at `dots.testllms.com`; `manifest.webmanifest` + service worker already present | **Primary test surface.** Installable on Android (Chrome) and iOS 16.4+ (Safari "Add to Home Screen"). Web push works on both when installed. |
+| **APK** | Capacitor wrapping the same `dist/` (`npx cap add android`, `npx cap sync`, Gradle `assembleRelease`) | Play Store / sideload testing. Native camera (QR), FCM push, deep link `tinybee://pair`. |
+| **IPA** | Capacitor iOS project (`npx cap add ios`), Xcode archive, TestFlight | App Store / TestFlight. APNs push, Universal Links for `https://dots.testllms.com/pair/*`. |
+
+Why Capacitor: it reuses `dist/` byte-for-byte, so a feature verified on the PWA behaves the same in APK/IPA; only plugin shims differ (camera, push, secure storage). Decision is reversible; React Native/Flutter would mean a second client.
+
+### 2.1 Capability shims
+
+| Capability | PWA | Capacitor (APK/IPA) |
+|---|---|---|
+| QR scan | `BarcodeDetector` API where available, fallback `jsQR` on `getUserMedia` frames | `@capacitor/barcode-scanner` (or `@capacitor-mlkit/barcode-scanning`) |
+| Push | Web Push / VAPID (existing localdost `src/notify`, `data/vapid.json`) | FCM (Android) / APNs (iOS) via `@capacitor/push-notifications`; Hive sends to whichever token type the device registered |
+| Deep link `tinybee://pair?d=…` | `https://dots.testllms.com/pair?d=…` web route (same payload) | Custom scheme + App Links / Universal Links to the same route |
+| Secure session storage | `localStorage` + httpOnly refresh cookie | `@capacitor/preferences` + Keychain/Keystore via `capacitor-secure-storage-plugin` |
+| Biometric unlock (v1.5) | — | `@capacitor-community/biometric-auth` |
+
+The client must feature-detect and never hard-fail when a native plugin is absent (it is always absent in the PWA).
+
+### 2.2 Versioning
+Single `version` in `package.json` drives: PWA `manifest.webmanifest` version, Capacitor `versionName`/`CFBundleShortVersionString`, and `GET /api/health.version` on the Bee. Build number = CI run number. The Bee advertises `api_versions: ["v1"]`; the client refuses to talk to a Bee whose `api_versions` does not include its own.
+
+## 3. Build & release pipeline (GitHub Actions)
+
+```
+on push to main / PR:
+  lint → test:server → test:client → build → test:e2e (Playwright vs local demo server)
+on push to main:
+  deploy staging:  railway up --service hive ; railway up --service bee-dev   (web served by bee-dev)
+  smoke:           curl https://dots.testllms.com/api/health ; Playwright smoke suite against staging PWA
+on tag v*:
+  android:         cap sync android → gradle bundleRelease → upload AAB/APK artifact → Play internal track
+  ios:             cap sync ios → xcodebuild archive → TestFlight (fastlane pilot)
+  bee-macos:       package macOS Bee (see 03-local-agent.md §3) → signed + notarized universal .pkg
+```
+
+Store signing keys (Android keystore, Apple certs/profiles via fastlane match) live in GitHub Actions secrets only.
+
+## 4. Test strategy
+
+| Layer | Tool | Scope |
+|---|---|---|
+| Unit (server) | `node --test` (existing `test/*.test.ts`) | Hive pairing logic, JWT validation, tunnel provider mock, metering |
+| Unit (client) | Vitest (existing) | Pairing payload parsing, degraded-state reducers, feature detection shims |
+| E2E local | Playwright (existing `scripts/e2e.mjs`) against `LOCALDOST_DEMO=1` + a mocked Hive | Install→QR→pair→first workflow flow, approvals, offline states |
+| **Staging PWA** | Playwright (mobile viewport, iPhone 14 / Pixel 7 emulation) against `https://dots.testllms.com` | The release gate. Same flows as above with real Hive and real Cloudflare provisioning in a `staging-*` tenant namespace that a nightly job deletes. |
+| Manual device | Real Android + iPhone with the installed PWA, then APK/IPA | QR scanning with a real camera, push delivery, background/foreground transitions, Add-to-Home-Screen |
+| Laptop Bee | Manual, one Apple Silicon Mac + one Intel Mac | Installer, pmset/power settings, menu bar app, tunnel reconnect after Wi-Fi change, FileVault/login-screen behaviour |
+
+Acceptance for a PR touching pairing or auth: the staging Playwright suite must pass **and** a human must complete one real pair on a phone. Record it in the PR.
+
+## 5. Staging hygiene
+
+- Tenants created by tests use slugs `test-<run-id>` (also `e2e-`, `pw-`); `.github/workflows/staging-cleanup.yml` runs `scripts/tinybee-staging-cleanup.mjs` nightly, which calls `DELETE /api/hive/admin/tenants?prefix=<p>` for each prefix (the Hive revokes the Cloudflare tunnel and DNS record first, and keeps a tenant whose tunnel could not be revoked so the next run retries). Run it by hand with `HIVE_URL=… HIVE_ADMIN_TOKEN=… node scripts/tinybee-staging-cleanup.mjs --dry-run`.
+- Cloudflare staging tunnels are capped at 50 (`TINYBEE_TUNNEL_CAP`); the cleanup job ends with exit code 2 when `GET /api/hive/admin/tunnels` reports more than 40.
+- The edge Worker (`infra/cf-worker`, see its README) is deployed by `.github/workflows/edge-worker.yml` on pushes to `main` that touch it, or by hand with `wrangler deploy` / `wrangler deploy --env prod`.
+- `bee-dev` data (`/data` volume) may be reset at any time; seed data comes from `LOCALDOST_DEMO=1`.
+- No real Gmail/Drive accounts in staging. Use a dedicated Google Cloud project in *testing* publishing status with allow-listed test users.
+
+### 5.1 Native shells, the macOS package and updates (Phase 7)
+
+- `native/` is the Capacitor 7 shell (`ai.tinybee.app`, `webDir` the built PWA); `android/` and `ios/` are generated by `cap add` in CI and are not committed. `.github/workflows/native-release.yml` runs on `v*` tags: `web` builds the PWA, `android` (when repo variable `ANDROID_RELEASE=true`) signs an `.aab` with the keystore secrets, `ios` (when `IOS_RELEASE=true`) archives and exports with the certificate and profile secrets. The signing material is OPEN-QUESTIONS 11.
+- The client's native layer (`client/src/native/`) reads `window.Capacitor` and never imports the SDK, so the PWA build is unchanged; inside the shell, Hive push goes through the device token (`POST /api/hive/push/device`) and App Links / Universal Links land on the hash router.
+- `packaging/macos/build-pkg.sh` builds `TinyBee-<version>.pkg`: the server build, a Node runtime and `cloudflared` under `/Library/TinyBeeAI`, the `_tinybee` user, the `ai.tinybee.bee` LaunchDaemon on port 7331 with its env file (`TINYBEE_HIVE_URL`, update channel and key), the `ai.tinybee.updater` daemon and the `ai.tinybee.menubar` agent, `/Applications/TinyBee.app` (menu bar) and the optional "keep the laptop awake" choice. `SIGN_APP`, `SIGN_INSTALLER` and `NOTARY_PROFILE` sign and notarize; without them the package is unsigned for local use.
+- Updates: `node scripts/tinybee-sign-manifest.mjs --key - --channel stable --version <v> --pkg <url> --file <pkg>` writes the signed manifest, which CI uploads with `PUT /api/hive/admin/updates/bee/stable` (admin token). Bees verify it with `TINYBEE_UPDATE_PUBKEY`, stage the package and ask the updater daemon to install it when no workflow is running; the daemon rolls back when `/api/health` stays red. `minVersion` in the manifest blocks older Bees (they report "blocked" instead of updating).
+
+## 6. Observability
+
+- Health: `GET /api/health` on every service (already exists on localdost); Railway health check path set to it.
+- Logs: structured JSON (`LOG_LEVEL`), Railway log drain → provider of choice. Hive logs contain tenant id and request id, never prompt content.
+- Metrics (staging): pairing success rate, median pair time, tunnel connects/disconnects per tenant, relay tokens per tenant/day, push delivery success by channel (web/FCM/APNs). A simple `/api/hive/metrics` JSON page is enough before a real dashboard.
+- Alerts: Railway deploy failure → Slack; staging `/api/health` failing 3× → Slack; Cloudflare tunnel count threshold → Slack.

package/docs/tinybee/07-coding-agent-handoff.md

@@ -0,0 +1,116 @@
+# TinyBeeAI — Coding Agent Handoff
+
+**Audience:** the coding agent (Claude Code or similar) implementing TinyBeeAI inside this repository.
+**Author role:** the human owner writes docs and guidance; the coding agent writes code, tests and PRs.
+**Date:** 2026-10-24
+
+---
+
+## 0. Read in this order, before writing code
+
+1. `AGENTS.md` (repo conventions — binding)
+2. `SPEC.md`, `docs/DATA-MODEL.md`, `docs/CONNECTIONS.md`, `docs/DEPLOY.md`, `docs/SETUP.md` (what localdost already is)
+3. `docs/tinybee/00-README.md` → `01-PRD.md` → `02-architecture-pairing.md` → `03-local-agent.md` → `06-environments-and-delivery.md`
+4. `04-local-setup-ui.md` and `05-mobile-app-ux.md` when you reach UI work
+
+Then run `npm install && npm run demo` and click through the existing app on `http://localhost:4319`. Do not propose a rewrite of localdost; TinyBee is a layer on top of it (see the term map in `00-README.md`).
+
+## 1. Ground rules
+
+- **Docs are the spec.** If code must deviate, open a PR that edits the relevant `docs/tinybee/*.md` first (or in the same PR) and explain why in the PR body. Undocumented behaviour is a bug.
+- **Small PRs, one concern each**, every PR green on `npm run lint && npm test`, and e2e when it touches flows. Use conventional commit prefixes (`feat(hive):`, `feat(client):`, `fix(bee):`, `docs(tinybee):`).
+- **Secrets never touch the repo, logs, PR text or chat.** Follow `docs/DEPLOY.md`: Railway secrets via `--stdin`.
+- **Verify on staging PWA (`https://dots.testllms.com`) before marking a feature done.** Attach the Playwright run link and, for pairing/auth changes, a note that a real-phone pair was completed.
+- **No user content in Hive.** Any PR that makes Hive persist workflow bodies, third-party tokens or message content is rejected by design.
+- **Feature flags over branches.** New TinyBee surfaces ship behind `TINYBEE_ENV`/`TINYBEE_FEATURES` flags so the existing localdost behaviour keeps working for current users.
+- **Ask when the docs are silent or contradictory**; do not invent product behaviour. Put the question in the PR or in `docs/tinybee/OPEN-QUESTIONS.md` (create it) and pick the most conservative interpretation meanwhile.
+
+## 2. Repository layout to add
+
+```
+src/hive/                 Hive service (separate entrypoint `src/hive/index.ts`, same toolchain as src/)
+  auth/                   OTP, Google sign-in, JWT issue/refresh, JWKS
+  tenants/                tenant CRUD, slug rules, plan state
+  pairing/                /pair/init, /pair/complete, /pair/claim, /pair/status
+  tunnel/                 TunnelProvider interface + cloudflare.ts + mock.ts
+  relay/                  model relay + metering
+  push/                   web-push (reuse src/notify), fcm.ts, apns.ts
+  presence/               heartbeat ingest, offline detection
+  admin/                  internal endpoints (tenant list, cleanup)
+src/bee/                  TinyBee additions to the localdost server
+  identity.ts             Ed25519 device key, storage abstraction (Keychain-wrapped on macOS, plain file on Linux/Railway)
+  hive-client.ts          heartbeat, long-poll channel, push requests, relay client
+  tunnel-manager.ts       cloudflared child process supervision
+  pairing.ts              QR payload, local pairing state machine
+  health/                 health checks (03-local-agent.md §4)
+  api/v1/                 the mobile-facing API surface (03-local-agent.md §8), mapped onto existing localdost routes where they already exist
+client/src/tinybee/       mobile client surfaces (onboarding, pairing, Home, degraded states) — reuse existing components
+client/src/platform/      capability shims: qr.ts, push.ts, storage.ts (web vs capacitor)
+capacitor/                Capacitor config and native projects (generated; commit config, not build outputs)
+bee-installer/            macOS packaging (.pkg, launchd, menu bar)
+test/hive/*.test.ts, test/bee/*.test.ts, e2e/tinybee/*.spec.ts
+```
+
+## 3. Delivery phases and acceptance criteria
+
+Work strictly in order; each phase ends with a staging deploy and a short demo recording (GIF or 30-s video) in the PR.
+
+### Phase 0 — Scaffolding (1 PR)
+- `src/hive/index.ts` boots, serves `/api/hive/health` and `/.well-known/jwks.json`.
+- `TunnelProvider` interface + `mock.ts`; `cloudflare.ts` stubbed with TODOs.
+- Railway service `hive` declared in `.railway/railway.ts`; deployed to staging.
+- **Done when:** `curl https://dots.testllms.com/api/hive/health` returns version + env.
+
+### Phase 1 — Identity & tenants
+- Email OTP sign-up/sign-in; Google sign-in; JWT (RS256) issue/refresh; tenant create with slug validation and availability check.
+- Client: Splash → sign-up → choose address screens (05 §3) as a PWA route `/onboarding`.
+- **Done when:** a new user can sign up on the staging PWA and sees "Install TinyBee on your laptop" with a 6-char code; Playwright covers happy path + taken slug + expired OTP.
+
+### Phase 2 — Pairing with mock tunnel
+- Bee side: device key, QR payload (`02 §4.3`), `/setup` page screens 0–4 (04 §3) served by the localdost server at `localhost:7331/setup` (make port configurable; keep 4319 default for localdost).
+- Hive side: `/pair/*` endpoints, nonce/code TTLs, replace-existing-Bee flow.
+- Client: scanner (PWA `BarcodeDetector`/jsQR), enter-code fallback, confirm-laptop, provisioning screens.
+- Use **mock** tunnel provider: Hive returns a fake hostname that maps straight to `bee-dev` on Railway.
+- **Done when:** on staging, phone scans a QR rendered by `bee-dev`'s `/setup` page (opened in a desktop browser) and reaches "Your Bee is online"; `GET https://dots-dev.testllms.com/api/v1/health` succeeds with the tenant JWT; failure table in `02 §4.5` has a test per row.
+
+### Phase 3 — Real Cloudflare tunnel + edge auth
+- `cloudflare.ts`: create tunnel, configure ingress, DNS CNAME, revoke; idempotent by name.
+- Edge auth Worker (in `infra/cf-worker/`) validating JWT + slug↔tenant; deploy via Wrangler from CI.
+- Bee `tunnel-manager.ts` runs bundled `cloudflared` with the token; reconnect/backoff; status in health.
+- Staging tenant cleanup job (06 §5).
+- **Done when:** a fresh `test-<id>` tenant gets `dots-test-<id>.testllms.com`, unauthenticated request → 401 at edge, authenticated → Bee; nightly cleanup removes it.
+
+### Phase 4 — Mobile core on the existing localdost capabilities
+- Home (status card, Needs-you approvals mapped to localdost Inbox, digest, recent activity), Chat (existing chat with action cards), Workflows list mapping dots/Watches, Connections mapping existing integrations, degraded states (05 §10).
+- Presence: heartbeat + offline push.
+- **Done when:** every row of `05 §10` is reachable in Playwright by faking Bee state; a demo video shows approve-from-phone of a localdost Inbox item through the tunnel.
+
+### Phase 5 — Guided workflow editor & skills
+- `POST /workflows/from-text` producing the YAML in `03 §6.1`; guided editor (05 §6.3); skills library seeded with 5 role presets from localdost plus 3 consumer skills (Gmail digest, Sheet watch, URL monitor).
+- Permission scopes `auto|ask|deny` mapped onto the existing rule gate.
+- **Done when:** a non-technical tester creates a working workflow from the phone in < 2 minutes on staging.
+
+### Phase 6 — Billing, relay, metering
+- Plan state, 30-day trial, token metering through relay, soft stop, BYOK bypass, "local only" suspension behaviour (Bee keeps running).
+- Payment gateway in **test mode only** on staging.
+- **Done when:** trial expiry on a test tenant flips the Bee to 🟡 Local only within 5 minutes and upgrade in test mode restores it.
+
+### Phase 7 — Native packaging
+- Capacitor Android/iOS projects; FCM/APNs push path in Hive; deep links; store metadata.
+- macOS Bee installer (signed + notarized `.pkg`), LaunchDaemon plist, menu bar app, pmset step, auto-update manifest (03 §3, §12).
+- **Done when:** APK and TestFlight builds pass the same Playwright-equivalent manual checklist; a Mac pairs with a real phone over mobile data, and survives lid-close on AC and a reboot.
+
+## 4. Definition of Done (every PR)
+
+- [ ] Lint, unit, e2e pass in CI.
+- [ ] Staging deploy succeeded and `/api/hive/health` + `/api/health` are green.
+- [ ] Feature verified on the **staging PWA**; link to Playwright run in PR.
+- [ ] Docs updated (`docs/tinybee/*` and localdost docs if behaviour changed).
+- [ ] No secrets, no user content in Hive, no new network egress from the Bee beyond Hive, Cloudflare, configured providers.
+- [ ] `CHANGELOG.md` entry under *Unreleased*.
+
+## 5. How to report back
+
+End every work session with a short note in the PR or in `docs/tinybee/PROGRESS.md` (create it):
+- what was completed (link PRs), what is verified on staging, what is blocked and why, which open question needs the owner's decision.
+Keep it under 15 lines. The owner reads this, not the diff.