tinybeeai 0.0.0-stage → 0.16.1

package/docs/tinybee/OPEN-QUESTIONS.md

@@ -0,0 +1,26 @@
+# TinyBeeAI — Open questions
+
+Questions the coding agent could not settle from the docs. Each one names what was assumed meanwhile. Resolved items move to the bottom with the decision and the date.
+
+## Open
+
+1. **DNS for `dots.testllms.com`.** The Railway services exist in project `localdost` (resolved below), but the custom domain is not on service `localdost` yet and the Cloudflare zone `testllms.com` has no record for it. Needed: `railway domain -s localdost dots.testllms.com` (prints the CNAME target), then a proxied CNAME in Cloudflare. Who holds the Cloudflare zone? Until then staging is reached at the Railway domain. *2026-10-25:* the Hive service has the custom domain `localdost.testllms.com` (proxied CNAME in the zone, ACTIVE), so the zone is reachable from the Hive side; `dots.testllms.com` on `localdost` is still to be added the same way.
+2. **Cloudflare API token** (Tunnel:Edit, DNS:Edit on zone `testllms.com`) for the real tunnel provider in Phase 3, set with `railway variable set CF_API_TOKEN --stdin --service hive`. Also `CF_ACCOUNT_ID`, `CF_ZONE_ID` on `hive`, plus `HIVE_ADMIN_TOKEN` (any long random string) for the nightly cleanup. Until then the `mock` provider is used on staging. *Phase 3 added:* the provider and the Bee tunnel manager are written and unit-tested against a fake API; nothing has run against Cloudflare yet. *2026-10-25:* `CF_ACCOUNT_ID`, `CF_ZONE_ID` and `CF_API_TOKEN` are set on `hive` (token derived from the account's `cloudflared` certificate, Tunnel and DNS on the zone). Still missing: `HIVE_ADMIN_TOKEN` on `hive`, and the Workers/KV token of item 6.
+3. **Google OAuth client** for "Continue with Google" (Phase 1). Email OTP ships first; the Hive already checks Google id tokens against `HIVE_GOOGLE_CLIENT_ID` (web client id only, no secret needed for the id-token flow), and the sign-up shows the Google button only when it is set. Which Google Cloud project owns it, and which origins should the client allow (`https://dots.testllms.com`, `http://localhost:4319`)?
+4. **Email sender for OTP** (Phase 1): Resend, SES, or SMTP? *Assumed meanwhile:* `HIVE_MAIL_PROVIDER=console` (the default) writes the code to the Hive log in local and staging; a prod Hive refuses to start sign-in with it. Local servers also return the code in the API response (`devCode`) so the PWA and Playwright can finish the flow.
+5. **Bee data dir on macOS.** `03-local-agent.md` puts data under `/Library/Application Support/TinyBee` (system-wide, needs admin). A per-user LaunchAgent and `~/Library/Application Support/TinyBee` need no admin password at install. Which one?
+6. **Edge Worker deploy.** `infra/cf-worker` is ready for `wrangler deploy`. Needed on the GitHub repo: secrets `CLOUDFLARE_API_TOKEN` (Workers Scripts:Edit, Workers KV:Edit, Workers Routes:Edit on `testllms.com`) and `CLOUDFLARE_ACCOUNT_ID`, and a KV namespace id for `wrangler.toml` (optional; the Worker caches in memory without it). Also `STAGING_HIVE_ADMIN_TOKEN` for the nightly cleanup workflow. *Assumed meanwhile:* the route `dots-*.testllms.com/*` and that every tenant host is a proxied CNAME created by the Hive.
+7. **Superapp admin ingest.** Superapp's console has a `tinybee` tenant (`POST admin.testllms.com/api/_ingest/tinybee`). Should Hive send sign-up and pairing events there, and from which phase?
+8. **Offline chat queue.** `05 §10` says messages typed while the Bee is offline are queued locally for up to 24 h. *Assumed meanwhile (Phase 4):* the composer stays on while the Bee is offline and the message goes to the Bee's own queue through the tunnel as soon as it answers; only a phone without internet disables the composer. A client-side queue needs a decision on where the 24 h clock lives (phone or Hive) and what happens to a message that expires.
+9. **Troubleshoot page.** The offline status card links to the docs index; `05` names a Troubleshoot target but no content exists. Which steps belong there (sleep settings, Wi-Fi, `cloudflared`, open `/setup`)?
+10. **Payment gateway and relay key** (Phase 6). Which gateway for VND (VNPay, MoMo, Stripe in USD)? The Hive has a `PaymentProvider` interface (`src/hive/billing.ts`) with one implementation, the test-mode `mock`, which a prod Hive never offers; a real provider needs its keys on `hive` and a webhook route that calls `settleInvoice()`. *Also needed on `hive`:* `HIVE_RELAY_ANTHROPIC_KEY` (the Hive's own model for app-side features; since Phase A a laptop never needs it: host work runs on the CLI, key, Ollama, LM Studio or endpoint the user set up there) and `HIVE_ADMIN_TOKEN` for `GET /api/hive/admin/metrics`. Set with `railway variable set NAME -s hive --stdin`.
+11. **Apple, Google and release signing material** (Phase 7). The native shell, the store workflow and the macOS package are written but have never run against real accounts. Needed: an Apple Developer team (team id for `TINYBEE_IOS_APP_ID` and `APNS_TEAM_ID`, a Developer ID Application + Installer identity and a notarization profile for `build-pkg.sh`, a distribution certificate and provisioning profile for the iOS job, an APNs auth key `.p8` for `hive`), a Google Play developer account with an upload keystore (`ANDROID_KEYSTORE_B64`, passwords) and a Firebase project for FCM (`google-services.json` for the Android job, a service account JSON for `FCM_SERVICE_ACCOUNT_JSON` on `hive`), and the SHA-256 of the signing certificate for `TINYBEE_ANDROID_CERT_SHA256`. Also: who holds the Bee update release key (generated with `node scripts/tinybee-sign-manifest.mjs --generate`; the public id goes to `HIVE_BEE_UPDATE_PUBKEY` on `hive` and into the pkg as `TINYBEE_UPDATE_PUBKEY`, the private PEM only into a GitHub secret), where the `.pkg` files are hosted (the manifest's `pkg` URL), and the privacy-policy and support URLs the stores require (`packaging/store/README.md`).
+
+## Resolved
+
+- **Railway project** (2026-10-24): the existing project `localdost` hosts both services (`localdost`, `hive`); the stray `localdost`/`hive` services that had been created in `superapp` were removed. `.railway/railway.ts` names `localdost`.
+
+- **Hive URL** (2026-10-24): no `hive.testllms.com`. Hive is reached at `dots.testllms.com/api/hive/*` through the Bee origin's proxy; the Hive service stays private on Railway.
+- **Tenant hostnames** (2026-10-24): `dots-<slug>.testllms.com` on staging (one level under the zone, same pattern as `admin.testllms.com`), `<slug>.tinybee.app` in prod. Env `TINYBEE_TENANT_HOST=dots-{slug}.testllms.com`.
+- **Service name** (2026-10-24): the existing Railway service stays `localdost`; the docs' `bee-dev` is its role, not its name.
+- **Windows** (2026-10-24): not supported. macOS is the only Bee platform in the docs.

package/docs/tinybee/PROGRESS.md

@@ -0,0 +1,134 @@
+# TinyBeeAI — Progress
+
+One entry per coding-agent session, newest first, at most 15 lines each.
+
+## 2026-10-25 — cloudflared downloaded by the install (local)
+
+- `src/bee/cloudflared.ts`: pinned release 2026.10.3 with SHA256 per platform (darwin arm64/x64, linux x64/arm64, win32 x64), downloaded into `TINYBEE_HOME/bin` by `ensureCloudflared` when PATH has none; a `.version` stamp makes a new pin replace the file. The tunnel manager falls back to that path (`TINYBEE_HOME` is set by `applyTinybeeEnv`).
+- Checked for real on this Mac with brew off PATH: 19 MB download, binary runs and reports 2026.10.3. The release notes' digests for the two macOS tarballs differ from the assets as served; the pinned values are from two identical downloads.
+- Tests: `test/bee/cloudflared.test.ts` (5), tunnel-manager and CLI tests updated. Version 0.16.1 (0.16.0 is on npm).
+
+## 2026-10-25 — Phase 8: no address step, `npx tinybeeai install` (local)
+
+- Sign-up is Sign in → Install. `src/hive/tenants.ts`: `slugFromEmail` and `ensureTenant` make the tenant at sign-in (`withTenant` in `auth.ts`, OTP and Google, never on refresh); `tenants.slugChosenAt` (null = automatic) is the one new column. `POST /tenants` on an automatic slug picks it (201) and 409s only a chosen one; the first `PATCH /tenants/me` of an automatic slug does not count as the rename. `TenantView.slugChosen` tells the client.
+- Client: `AddressStep` is gone; the Install step shows `https://<hostname>` with Change it (`RenameAddress`: live availability, suggestions, Use this address). The install command reads `npx tinybeeai install`. The Install step polls `pairPending` every 3 s and goes to `#/add-laptop` when the laptop has typed the code.
+- npm: package renamed `tinybeeai` (public, `prepublishOnly` builds; `tinybee` on npm is taken), new `bin/tinybeeai.js` → `src/cli/tinybee.ts` (`install [CODE]`, `start`, `--dir`, `--hive`, `--port`, `--replace`). Defaults: `~/.tinybee/data`, `TINYBEE_ENV=staging`, `TINYBEE_HIVE_URL=https://dots.testllms.com`, `PORT=4319`, `LOG_LEVEL=warn`; the shell wins. It boots `src/index.ts`, waits for `initBee`, calls `submitInstallCode`, prints the stages from `onBeeChange`. `files` drops `docs/demos`, `docs/images` and `dist/web/**/*.map` (3.2 MB packed).
+- Google OAuth web client is set on staging (`HIVE_GOOGLE_CLIENT_ID` on the `hive` service); the pasted client secret is not used anywhere and should be reset.
+- Tests: `test/hive/identity.test.ts` (12, incl. `slugFromEmail`/`ensureTenant`), `test/bee/tinybee-cli.test.ts` (3), `test/bee/pairing.test.ts` and `test/tinybee/workflow-routes.test.ts` now expect `wrong_tenant` for a fresh sign-in (every session carries a tenant); e2e `tinybee-signup` + `tinybee-pair` 12/12. Client 1908 tests, typecheck and lint clean (eslint now ignores `native/android|ios|build-out`). Pre-existing failures unrelated to this work in `test/aivision-local`, `test/connect-routes`, `test/lead-ask` (also fail at `771dd21`).
+- Not done: `npm publish --access public` needs the owner's `npm login`; the staging `hive` and `qadots` services need a redeploy for the new tenant flow; no run of `npx tinybeeai install` against staging with a real `cloudflared` yet.
+
+## 2026-10-25 — Continue with Google on sign-up (local)
+
+- The OTP step is painful on staging (the mail provider is console, so codes only reach the Hive logs). The sign-up page now shows a Google button when `GET /api/hive/auth/providers` carries `googleClientId` (the Hive adds it from `HIVE_GOOGLE_CLIENT_ID`). `client/src/features/tinybee/googleSignIn.ts` loads Google Identity Services once; the id token goes to `POST /api/hive/auth/google` and the result is the same session as the email code, so the address step follows.
+- Branding: `client/public` icons (192, 512, maskable, apple-touch, favicon) are generated from the tinybee.ai bee; the brand mark in `AppShell` is that image instead of the pip mascot. The sign-up steps bar shows phases (Sign in, Address, Install), since Google sign-in has no code step.
+- Still to do on staging: create the OAuth web client in Google Cloud (project tinybee-dev, JavaScript origin `https://dots.testllms.com`), set `HIVE_GOOGLE_CLIENT_ID` on the `hive` Railway service, redeploy.
+- Checks: client join + pages 54 tests, server identity 11 tests, typecheck and eslint clean.
+
+## 2026-10-25 — Login first on a hosted Hive (local)
+
+- The live app at dots.testllms.com showed the admin Join (token) screen to every visitor. A hosted Hive (TINYBEE_ENV staging or prod, read from the public `GET /api/hive/health`) now sends a turned-away browser to `#/signup`; `client/src/features/join/joinFlow.ts` (`useLoginFirst`) decides, `App.tsx` navigates and shows only a skeleton meanwhile.
+- `#/join` (with or without a code) keeps the Join screen, so invite links still work; the sign-up page links there for a teammate with a code. A laptop that embeds Hive (local) behaves as before.
+- A browser with a Hive session is a TinyBee user: the Join gate no longer covers it, and the empty address opens `#/home`.
+- Checks: client 118 files / 1908 tests, e2e tinybee-signup + tinybee-home 16/16.
+
+## 2026-10-25 — Rename: QA Dots becomes localdost (local)
+
+- The product, package, CLI, PWA, docs and env vars now read `localdost` (lowercase, like `localhost`; QA is one workflow, not the product). `bin/localdost.js` replaces `bin/qadots.js`; `qadots` stays as a CLI alias.
+- Compat (`src/legacy-names.ts`): `QADOTS_*` env fills `LOCALDOST_*` at startup; parsed env files map old keys; `.env.qadots`, `.qadots/` and `qadots.db` are read when the new names are missing; connect-store rows `QADOTS_*` re-encrypt under `LOCALDOST_*` once; the PWA moves `qadots:*` localStorage keys to `localdost:*`.
+- Markers write `localdost:` but match `qadots:` too (sticky PR comment, review, bot marker, hidden markers in the client); defect label `localdost` with legacy `qa-dots` still searched; `/qadots review` still triggers.
+- Icon: white dot + cursor bar on coral (`client/scripts/export-mascots.ts`), all PNG sizes regenerated.
+- Unchanged on purpose: Railway service/volume names and keys, Docker user `qadots` and image tags, CI runner label, `duonghaijoe/localdost` history links, HMAC key `qadots:bot-marker:v1`, CHANGELOG history.
+- Checks: typecheck, server and client suites green; e2e tinybee specs rerun. Next: Phase 7 follow-ups continue on this branch; GitHub repo is `duonghaijoe/localdost`.
+
+## 2026-10-25 — Phase B: the phone app after impeccable (local)
+
+- Craft floor (pbakaus/impeccable, Operate mode): no eyebrow above headings, no emoji as icons, sentence-case section titles, cards at radius 12–16 with elevation declared once by a hairline, state-only motion on `--ease`. Tokens: `--radius-xl`, `--ease-out`, `--dur-slow`; Inter self-hosted (`@fontsource-variable/inter`), caret and scrollbar follow the accent.
+- Home (`pages/TinyBeeHome.tsx`): one status card with a dot and a 4 px ring per state, the laptop's name and address said once, `seen HH:MM` on the right; the first-run nudge "No AI on the laptop yet" (`home-ai-nudge`) shows when the shared `MODELS_KEY` scan has no active backend and points at `#/ai`; quick actions are pills.
+- Shell (`shell/AppShell.tsx`, `styles/shell.css`): in TinyBee mode the localdost setup and sandbox strips and the Demo badges stay hidden; the More sheet is grouped "Your Bee" (AI on your laptop, Skills, Plan & billing, Settings) then "localdost" (Dots, Inbox, Activity) with `more-ai` / `more-skills` / `more-plan` test ids.
+- Workflows: a labeled pill FAB "New workflow" above the tab bar (`.btn.workflows__fab`), rows with a 40 px tile. AI screen: the active card says the model and "in use on this laptop" under the name; a row's detail wraps inside the button; the picked row uses `--surface-selected`.
+- Plan: the usage card now says the bundle covers the app's own features and links `#/ai` for host work (was "Add it in Setup"); `TinyBeePlan.test.tsx` follows.
+- Checks: typecheck, vitest 1902, e2e tinybee-{home,workflows,ai,billing,pair,signup} in both projects (34).
+
+## 2026-10-25 — Phase A: local AI backends, the app only picks (local)
+
+- Rule (02 section 7): Dots ships no AI for host work. The Bee scans the laptop and the phone picks; the Hive's model serves app-side features only. The engine's bundle gate and the relay backend are gone from `src/agent/llm.ts`.
+- Bee: `src/bee/models.ts` (`scanModels()`: `claude` / `codex` CLIs and their sign-in, Anthropic / OpenAI / Gemini keys, Ollama and LM Studio on loopback with their model lists, the custom endpoint; `applyModelChange()` with a 409 and rollback when the pick is not ready; `llmForTier()` from `TINYBEE_MODEL_TIERS`), `src/agent/llm-openai.ts` (presets with `PRESET_KEYS`, default server addresses), `src/tinybee/models-routes.ts` (`GET|PUT /api/v1/models`, errors `model_pick` / `model_error`).
+- Client: `#/ai` "AI on your laptop" (`pages/TinyBeeAi.tsx`, `features/tinybee/modelsApi.ts`, `brandMarks.tsx`): the active card, one row per backend with what it needs, a sheet per backend (install / sign-in help, write-only key, server address, model, custom base URL and extra body), the tier map editor. More menu entry; the Connections budget card points here.
+- Tests: `test/bee/models.test.ts` (11: scan with nothing set up, CLIs, Ollama / LM Studio listing, pick, not-ready rollback, keys never returned, custom endpoint, env override, parse and route errors), `test/tinybee/workflows.test.ts` (the bundle never gates host work), `e2e/tinybee-ai.spec.ts` (the screen under the e2e server's `LOCALDOST_LLM=mock` override: rows, read-only pick, a custom endpoint saved and cleared, the key never shown).
+- Open: no backend set up means no workflow runs; a first-run nudge on Home is Phase B's.
+
+## 2026-10-25 — Phase 7: native packaging (local)
+
+- Hive: `native-push.ts` (FCM v1 with a service-account JWT, APNs HTTP/2 with a p8 token; `POST|DELETE /push/device`; `pushToUser()` fans out to web and native and drops rejected tokens), `updates.ts` (`GET /updates/bee/:channel`, `/summary`; admin `PUT /admin/updates/bee/:channel` checks the manifest signature against `HIVE_BEE_UPDATE_PUBKEY` and keeps it under `HIVE_BEE_UPDATES_DIR`), `src/tinybee/update-manifest.ts` (canonical JSON, Ed25519 sign / verify, `scripts/tinybee-sign-manifest.mjs`).
+- Bee: `updater.ts` (fetch, verify, download, sha256, stage, apply request when no workflow runs, `result.json` read at boot, `updateStatus()` current / available / staged / installing / failed / blocked by `minVersion`), `GET /api/bee/menubar/status` (loopback, `x-tinybee-menubar: 1`), `/setup` shows the update card; `src/tinybee/workflows/activity.ts` holds the running set so `status.ts` no longer imports the engine (import cycle).
+- Server: `src/tinybee/well-known.ts` (`assetlinks.json`, `apple-app-site-association` from `TINYBEE_ANDROID_PACKAGE`, `TINYBEE_ANDROID_CERT_SHA256`, `TINYBEE_IOS_APP_ID`; 404 when unset).
+- Client: `client/src/native/` (`capacitor.ts` reads `window.Capacitor` only, `nativePush.ts` registers the device token with the Hive and routes push taps, `deepLinks.ts` turns `/workflows/…` App Links into hash routes); `enableHivePush()` prefers native push inside the shell; `main.tsx` installs both.
+- Packaging: `native/` (Capacitor 7 config, `ai.tinybee.app`), `.github/workflows/native-release.yml` (web → Android `.aab` → iOS `.ipa` on `v*` tags, gated by repo variables), `packaging/macos/` (`build-pkg.sh`: payload under `/Library/TinyBeeAI`, `_tinybee` user, three launchd plists, `Distribution.xml` with the power-settings choice, signing and notarization when the identities are set; `apply-update.sh` with install, restart, health wait, rollback; `MenuBar/main.swift`; `uninstall.sh`), `packaging/store/` (listings en-US / vi-VN, privacy).
+- Tests: `test/hive/native-push.test.ts` (FCM and APNs against fake endpoints, device routes, token drop), `test/bee/updater.test.ts` (8: manifest signature, stale key, download and stage, apply when idle, result at boot, minVersion block, admin upload), `test/tinybee/apply-update.test.ts` (6: the shell script against a fake installer / launchctl / health, rollback, sha256 and path checks), `test/tinybee/well-known.test.ts` (3), vitest `client/src/native/*.test.ts` (9).
+- Deviations: nothing has been built on a real Apple or Google account (OPEN-QUESTIONS 11): no signing identity, keystore, Firebase project, APNs key or release key exists yet, so the workflows and `build-pkg.sh` are unexercised in CI; the Bee data dir is `/Library/TinyBeeAI/data` (system-wide, OPEN-QUESTIONS 5 assumed); the menu bar app polls the loopback API instead of an XPC link; the updater channel `beta` has no manifest.
+- Next: real accounts and a first signed build; then the staging Playwright gate of `06 §4`.
+
+## 2026-10-25 — Phase 6: plan, relay and metering (local)
+
+- Hive: `billing.ts` (`PLANS` trial 200k / standard 500k, 99,000 VND / pro 3M, 249,000 VND; `TOPUP` 500k, 49,000 VND; 30-day periods; `budgetOf()` ok / low at 80% / exhausted; `relayAllowance()`; `recordRelayUsage()`; a minute sweeper suspends tenants whose period ended (`trial_ended`, `unpaid`) with one push "Your trial has ended" → `#/plan`, and drops usage rows older than 90 days; `checkout()` and `settleInvoice()` behind a `PaymentProvider` interface whose only implementation is the test-mode mock, never offered in prod), `relay.ts` (`POST /relay/anthropic/v1/messages`, `GET /relay/anthropic/budget`; relay token `tbrl.` per tenant, minted at pairing and handed over on the pair poll; the Hive key is added, `x-tinybee-source` is stripped and the body goes through byte for byte; JSON and SSE token counts metered only when the provider answered < 400; 402 with `x-tinybee-refusal`, 503 `relay_unconfigured`, 502 `relay_upstream`; no prompt is stored or logged). Routes: `GET /billing`, `GET /invoices`, `POST /billing/checkout`, `POST /billing/mock/complete` (not prod), local-only `POST /dev/billing`, admin `GET /admin/metrics`. A suspended tenant gets `plan.tunnel: off` on the heartbeat and `pushToUser()` skips it; `GET /me` and `GET /bee` carry the plan, status and reason.
+- Bee: `relay-client.ts` (fetch with the relay token, reads the refusal header), `status.ts` (`beePlan()`, `budgetNow()`, `bundledModelAllowed()`), `llm.ts` picks the relay when paired and no own key is set (`ANTHROPIC_API_KEY` / `LOCALDOST_LLM` bypass it), `pairing.ts` stops or starts `cloudflared` from `plan.tunnel` and shows the plan notice on `/setup`; the workflow engine pauses a workflow that reads sources before it starts when the bundle is used up ("Paused: budget") and lets plain reminders run.
+- Client: `#/plan` (`TinyBeePlan.tsx`: plan card and period, usage meter with the breakdown by source, Upgrade / Go Pro / Top up sheets, test-mode pay, payments list, `?pick=topup` opens the sheet), `beeStatus()` turns a suspended tenant into "Local only · Trial ended · remote access paused" even while the tunnel still reports connected, the budget banner links to Top up. AppShell: the More sheet no longer reopens when you come back to the route it was opened on.
+- Tests: `test/hive/billing.test.ts` (5: plan view, trial end → suspended → upgrade in test mode → back on; relay forwarding, metering, SSE, 529 passthrough, 402, top-up, 502; 503 unconfigured + retention sweep; dev route and admin metrics), Bee pairing test extended (relay backend, 402 budget, suspension on heartbeat, reset), engine budget pause, vitest `beeStatus.test.ts`, `TinyBeePlan.test.tsx` (7), `e2e/tinybee-billing.spec.ts` (trial ends → Local only with the reason → Upgrade pays in test mode → Online, then a top-up).
+- Deviations: no real payment gateway (OPEN-QUESTIONS 10): the only provider is the test-mode mock; prices are VND with a USD hint; the relay covers Anthropic only (`HIVE_RELAY_OPENAI_KEY` of `06` is not wired); paid plans do not renew automatically, the tenant is suspended `unpaid` at the end of the month until a new checkout; the "within 5 minutes" of the handoff is a 60 s sweep plus the next heartbeat.
+- Next: Phase 7 (native packaging) — done, see above.
+
+## 2026-10-25 — Phase 5: workflows, editor and skills (local)
+
+- Bee (`src/tinybee/workflows/`): `types.ts` (the YAML schema of `03 §6.1`, `rulesOf()` maps `permissions` auto/ask/deny onto the dot rule gate), `yaml.ts` (parse, validate with field paths, print), `cron.ts` (five-field cron, next runs, human sentence), `from-text.ts` (a sentence → draft + summary, no model call), `skills.ts` (7 skills in 5 groups; `roleSkills()` adds the localdost role presets), `store.ts` (a workflow is a watch of kind `workflow` on the tenant dot; runs are ordinary `runs` rows; `tb_seen`, `tb_digest`, `tb_notes` hold the seen keys, digest entries and hand-off notes), `engine.ts` (read inputs through the existing Gmail/Sheets/Drive/URL connections, model only when something is new, outputs through `gate()`; `ask` → approval card, `deny` → hand-off note), `scheduler.ts` (minute tick, `CATCH_UP_MINUTES=60`), `routes.ts` (`/api/v1/workflows*`, `/runs*`, `/digest`, `/skills*`; tenant JWT or any localdost caller). Hive: `POST /presence/notify` (laptop-signed) relays a workflow push to the owner's phone.
+- Client: `features/tinybee/beeApi.ts` (typed client, `BeeApiError` with `code`/`field`), `schedule.ts` (cron ↔ the editor's When picker, `savedSentence`), `workflowUi.tsx` (shared rows, dots, run sheet). Pages `#/workflows` (tabs, switch, add sheet: describe / skill / YAML, read-only while the Bee cannot act or the budget is out), `#/skills` (cards by group, sheet, Use this skill), `#/workflows/new` (guided editor, field errors land on the field, Test runs once and shows the steps), `#/workflows/:id` (detail, runs, Run now, Duplicate, Delete). Chat offers "Make this a workflow" under the chips once you have sent a message, pre-filling the editor with it.
+- Tests: `test/tinybee/workflows.test.ts` + `workflow-routes.test.ts` (19: YAML round trip and errors, cron, from-text, engine with ask/deny, scheduler catch-up, every route), vitest `schedule.test.ts` (7), `TinyBeeWorkflows.test.tsx` (5), `TinyBeeSkills.test.tsx` (2), `TinyBeeWorkflowEditor.test.tsx` (4), `e2e/tinybee-workflows.spec.ts` (4 on mobile: describe → edit → save → pause → run → run sheet → YAML → duplicate → delete; skill → Test; read-only without a laptop; YAML import with a bad cron). Shared e2e helpers moved to `e2e/tinybee-helpers.ts`.
+- Found by the e2e: a Hive session minted before the tenant exists carries `tenant_id: null`, and the Bee answers 403 `no_tenant`; the app and the helpers refresh the session after sign-up. `prettier --check` had drifted on 29 earlier TinyBee files; formatted.
+- Deviations: workflows count toward the dot totals in the existing UI (they are watches); an `ask` output approved later runs on the laptop but the result is not relayed to the Hive as an event; catch-up after sleep is capped at 60 minutes (the localdost nightly run allows 6 hours); `ask` pushes reuse the standard approval notice; the "< 2 minutes on staging" check of the handoff waits for the staging deploy (OPEN-QUESTIONS 1, 2).
+- Next: Phase 6 (billing, relay, metering).
+
+## 2026-10-24 — Phase 4: mobile core, presence and the degraded states (local)
+
+- Hive (`src/hive/presence.ts`, `push.ts`): `OFFLINE_AFTER_SEC=300` sweeper (every 30 s) sets `offlineSince`/`offlineNotifiedAt`, pushes "<name> is offline" once and "still offline" daily (`REMIND_AFTER_SEC`); a heartbeat clears both and pushes "back online". `GET /push/vapid`, `POST|DELETE /push/subscribe` (session-bound, 410/404 drops the row); keys from `HIVE_VAPID_*` or `hive-vapid.json` (0600). `beeView` carries `online`, `offlineSince`, `hc.tunnel`. Dev (local only): `POST /dev/bee {offlineForSec|tunnel|thaw}` (freezes heartbeats for 10 min so the embedded Bee cannot undo the fake; `thaw` lets the next one through; `{}` restores), `GET|DELETE /dev/pushes`.
+- Bee (`src/bee/status.ts`, `health.ts`): `GET /api/health.tinybee` = `{budget, connections, update, apiVersion, minClientApiVersion}` (real values are stubs until Phases 5–6: budget ok, no connections, update current). Dev: `POST /api/bee/dev/fake` (loopback + `x-setup-token`) overrides any part, `POST /api/bee/dev/heartbeat` sends one now.
+- Client (`client/src/features/tinybee/`): `beeStatus.ts` (pure: `beeStatus()` → online/local/offline/unpaired/provisioning/phoneOffline; `degradedNotices()` → budget/connection/update/apiVersion banners, a blocking one alone), `useTinyBee.ts` (session via `useSyncExternalStore`, 30 s Bee poll while visible, `navigator.onLine`), `TinyBeeShell.tsx` (pill, banners, tab bar), `hivePush.ts` (subscribe the service worker to Hive push). `AppShell` swaps the brand link, sidebar, pill, banners and tab bar when a Hive session exists. Pages: `#/home` (`TinyBeeHome.tsx`: status card with the §10 actions, Needs you = pending approvals with inline `ApprovalCard`, Today digest from runs, quick actions that pre-fill Chat, recent activity), `#/workflows` (read-only banner + "Describe one in Chat"), `#/connections?fix=` (budget card, integrations with Reconnect, highlighted row). Chat gets a Bee strip and a disabled composer with the reason when the phone is offline.
+- Tests: `test/hive/presence.test.ts` (3: push subscribe, sweep → push → remind → back online, dev route + thaw), `test/bee/pairing.test.ts` (+1: health block + dev fake), vitest `beeStatus.test.ts` (6) + `TinyBeeShell.test.tsx` (5), `e2e/tinybee-home.spec.ts` (5 on mobile + desktop: every §10 row through the dev routes, phone offline via `context.setOffline`, and approve-from-phone recorded to `.build/recordings/tinybee/approve-from-phone.webm`).
+- Fix found by the e2e: `readHiveSession()` returned a fresh object per call and React looped (#185) under `useSyncExternalStore`; the parsed session is cached by its raw value now.
+- Deviations: the demo video shows approve-from-phone on the local demo server (embedded Hive + Bee), not through a Cloudflare tunnel (OPEN-QUESTIONS 1, 2); "Top up" is disabled until Phase 6; the 24-hour offline chat queue of §10 is not built (OPEN-QUESTIONS 8); Troubleshoot links to the docs index until a TinyBee troubleshooting page exists; the web-push service worker handler is the existing localdost one, so a Hive push opens its `url`.
+- Next: Phase 5 (workflow editor and skills).
+
+## 2026-10-24 — Phase 3: Cloudflare tunnel, edge auth and staging hygiene (local)
+
+- Hive (`src/hive/tunnel/cloudflare.ts`): real provider on the Cloudflare v4 API: `provision` finds or creates the tunnel `tinybee-<tenant>`, sets its ingress to `http://localhost:<TINYBEE_BEE_PORT>`, upserts a proxied CNAME to `<tunnel-id>.cfargotunnel.com` (fixes a stale one), returns the token; `revoke` deletes DNS, connections and the tunnel (cascade); `rotate` and `count` too. `CloudflareApiError` carries the Cloudflare error list. Picked when the three `CF_*` vars are set.
+- Hive admin (`src/hive/admin.ts`): `HIVE_ADMIN_TOKEN` guards (404 when unset, 401 otherwise, constant-time compare) `DELETE /admin/tenants?prefix=&dryRun=1` (prefix ≥ 4 chars, revokes the tunnel first and keeps the tenant when that fails, then deletes nonces, install codes, bees, tenant, refresh tokens and the orphaned user in one transaction) and `GET /admin/tunnels` (`count`, `cap`, `warnAt`, `ok`). `GET /edge/tenants/:slug` (public, 60 s cache) is what the Worker calls.
+- Bee (`src/bee/tunnel-manager.ts`): spawns `cloudflared tunnel --no-autoupdate --protocol quic run` with `TUNNEL_TOKEN` in the env, reads "Registered tunnel connection" / "Unregistered" / invalid-token lines, states off/starting/connected/reconnecting/no_cloudflared/stopped, backoff 2 s doubling to 5 min, HTTP/2 after three QUIC runs shorter than 60 s, SIGTERM then SIGKILL on stop. `pairing.ts` starts it once paired (never for `mock.` tokens or `TINYBEE_TUNNEL=off`), stops it on unpair/replace; `/setup` done screen and `GET /api/v1/health` show the state.
+- Edge (`infra/cf-worker`): Worker for `dots-*.testllms.com/*` (slug from Host via `TENANT_HOST`), RS256 check with Web Crypto against the Hive JWKS (5 min cache), tenant lookup (10 min cache, KV optional), error codes session_required/malformed/bad_signature/bad_issuer/expired/unknown_key/no_tenant/wrong_tenant/tenant_not_found/not_a_tenant/hive_unreachable, OPTIONS passes, forwards with `x-tinybee-edge: 1`. `wrangler.toml` staging + `[env.prod]`; `.github/workflows/edge-worker.yml` deploys on push to main.
+- Hygiene: `scripts/tinybee-staging-cleanup.mjs` (`--prefix test-,e2e-,pw-`, `--dry-run`, exit 2 above `warnAt`) and `.github/workflows/staging-cleanup.yml` (nightly 19:17 UTC). `TINYBEE_TUNNEL_CAP`, `TINYBEE_TUNNEL`, `TINYBEE_BEE_PORT`, `HIVE_ADMIN_TOKEN` documented in `.env.example`; the secrets are kept out of runner envs.
+- Tests: `test/hive/cloudflare.test.ts` (in-memory Cloudflare API, 6 cases), `test/hive/admin.test.ts` (3), `test/hive/edge-worker.test.ts` (real signed tokens through the Worker's `gate`, 6), `test/bee/tunnel-manager.test.ts` (fake child process, 6). `npm run typecheck` also checks the Worker (`infra/cf-worker/tsconfig.json`).
+- Not done: the Worker is not deployed (needs `CLOUDFLARE_API_TOKEN`/`CLOUDFLARE_ACCOUNT_ID` repo secrets and a KV id); staging Hive still runs the `mock` provider (OPEN-QUESTIONS 2); `dots.testllms.com` CNAME pending (OPEN-QUESTIONS 1); no end-to-end run with a real `cloudflared` yet. Next: Phase 4 (mobile core).
+
+## 2026-10-24 — Phase 2: pairing with the mock tunnel (local)
+
+- Hive (`src/hive/pairing.ts`, `tunnel.ts` mock): `pair_nonces` and `bees` tables; `POST /pair/offer` (Bee-signed, Ed25519 over the payload), `POST /pair/claim` (install code), `GET /pair/status?nonce` (the Bee polls; the tunnel token travels once, in `delivery`), `POST /pair/complete {nonce, replace?}` (409 `bee_exists` with the current Bee until `replace: true`), `GET /pair/pending`, `GET /bee`, `POST /presence/heartbeat` (`bee_unknown` tells a replaced laptop). Nonce TTL 10 min; one live Bee per tenant.
+- Bee (`src/bee/`): `identity.ts` (device key, 0600), `health.ts` (memory, disk, power, LLM key), `pairing.ts` (stages off/idle/showing/claimed/paired/replaced; QR renew, 2 s poll, 30 s heartbeat, state file `TINYBEE_STATE_PATH`), `setup-page.ts` (inline HTML/CSS/JS, en/vi, no external assets, strict CSP), `routes.ts` (`/setup` and `/api/bee/*` on loopback only with an `x-setup-token`; `GET /api/v1/health` checks the tenant JWT against Hive's JWKS, 403 `no_tenant`/`wrong_tenant`). `src/index.ts` starts it when TinyBee is on.
+- Client: `#/add-laptop` (`client/src/pages/TinyBeeAddLaptop.tsx`): BarcodeDetector scanner or paste box, pending install-code claim, confirm with health list, replace prompt, provisioning poll, online card; deep link `?d=`; `hiveApi.pairComplete/pairPending/bee`; `@pair-payload` alias shares the payload codec with the server.
+- Tests: `test/hive/pairing.test.ts` + `test/bee/pairing.test.ts` (37 cases hive+bee: signature and TTL failures per the 02 §4.5 table, replace, restart, unpair, loopback and token refusals, JWKS verification); `e2e/tinybee-pair.spec.ts` (3 cases on mobile + desktop: paste → confirm → online → reload, deep link + replace, foreign Host refused). Test hygiene: the restore-check table scan skips `src/hive` (own database file); `TINYBEE_DEVICE_KEY_PATH` is held back from runner envs.
+- Deviations: `/setup` is served by the localdost port (4319 default), not a separate 7331; the e2e pairs the demo server with itself (embedded Hive + Bee in one process) since no staging Bee exists yet.
+- Railway: project `localdost` (services `localdost`, `hive`), `.railway/railway.ts` renamed; deploy health and `dots.testllms.com` DNS still unverified (OPEN-QUESTIONS 1).
+- Not done: the staging "done when" (phone scans a QR from a cloud Bee at `dots-dev.testllms.com`) waits on DNS; the camera path is untested in Playwright (no BarcodeDetector in headless). Next: Phase 3 (Cloudflare tunnel provider, edge auth Worker, Bee tunnel manager, tenant cleanup).
+
+## 2026-10-24 — Phase 1: identity, tenants and the sign-up PWA route (local)
+
+- `src/hive/`: `db.ts` (SQLite: users, otp_codes, refresh_tokens, tenants, install_codes), `auth.ts` (email OTP start/verify with try, expiry and rate limits), `jwt.ts` (RS256 access tokens, rotating refresh with reuse detection), `google.ts` (id-token check against Google JWKS, `HIVE_GOOGLE_CLIENT_ID`), `tenants.ts` (slug rules, reserved list, availability with 3 suggestions, one rename, install codes), `mail.ts` (`console` sender only; refused in prod), `errors.ts`, `session.ts`; routes under `/api/hive/auth/*`, `/api/hive/me`, `/api/hive/tenants*`.
+- Client: `#/signup` (`client/src/pages/TinyBeeSignup.tsx`, `features/tinybee/hiveApi.ts` with its own session store and refresh) — email → code → address → "Now install TinyBee on your laptop" with the 6-char code and countdown; open route in the join gate. Named `signup` because `onboarding` is the KAT-257 welcome flow.
+- Tests: `test/hive/identity.test.ts` (11 cases: OTP, tries, expiry by injected clock, rate limit, refresh rotation and reuse, `/me` errors, slug rules, taken slug, one tenant per user, rename lock, Google, prod mailer refusal); `e2e/tinybee-signup.spec.ts` (happy path, taken slug, wrong and spent code; 6/6 on mobile + desktop). Deviation: the expired-OTP case lives in node:test with an injected clock; Playwright covers a spent code instead of waiting 10 minutes.
+- `playwright.config.ts` boots the e2e server with `TINYBEE_ENV=local`.
+- Not done: Google in the UI is wired but untested against a real client id; no real mail sender; staging still blocked (OPEN-QUESTIONS 1). Next: Phase 2 pairing (Bee device key, QR, `/setup`, Hive `/pair/*`, mock tunnel).
+
+## 2026-10-24 — Phase 0: Hive scaffold (local)
+
+- Added `src/hive/`: config, RS256 signing key + JWKS, `TunnelProvider` (mock + Cloudflare stub), routes, standalone server (`npm run hive`, port 4330), and `embed.ts` (embedded in local mode, proxied through `/api/hive` when `TINYBEE_HIVE_URL` is set, absent otherwise).
+- `src/server.ts` mounts Hive and lets `/api/hive/*` through the localdost auth hook only when TinyBee is on.
+- `.railway/railway.ts`: new private `hive` service with its own volume; `localdost` service gets `TINYBEE_ENV=staging` and `TINYBEE_HIVE_URL`.
+- Decisions recorded in `06` and `OPEN-QUESTIONS.md`: Hive behind the Bee origin, tenants `dots-<slug>.testllms.com`, hosting like Superapp (custom domains on Railway, Cloudflare CNAME).
+- Tests: `test/hive/health.test.ts` (9 cases: health, JWKS, key persistence, env key, mock provider, embedded, proxy + 502, off mode).
+- Not done: staging deploy (no Railway project or DNS yet, see OPEN-QUESTIONS 1). Next: Phase 1 (Hive SQLite, email OTP, JWT issue/refresh, tenants + slugs, `/onboarding` PWA route).

package/package.json

@@ -1,6 +1,113 @@
 {
   "name": "tinybeeai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.16.1",
+  "description": "TinyBee: an always-on QA agent on your laptop, paired with your phone. Also the self-hosted localdost server.",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "homepage": "https://tinybee.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/duonghaijoe/localdost.git"
+  },
+  "bin": {
+    "tinybeeai": "bin/tinybeeai.js",
+    "localdost": "bin/localdost.js",
+    "qadots": "bin/localdost.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "!dist/web/**/*.map",
+    "demo/",
+    "docs/",
+    "!docs/demos/",
+    "!docs/images/",
+    "AGENTS.md",
+    "README.md",
+    "Dockerfile",
+    "compose.yml",
+    ".railway/"
+  ],
+  "scripts": {
+    "init": "node bin/localdost.js init",
+    "doctor": "node bin/localdost.js doctor",
+    "dev": "node scripts/dev.mjs",
+    "dev:server": "tsx watch src/index.ts",
+    "dev:web": "vite",
+    "build": "tsc -p tsconfig.json && node scripts/copy-assets.mjs && tsc -p tsconfig.client.json && vite build",
+    "prepublishOnly": "npm run build",
+    "build:web": "vite build",
+    "start": "node dist/index.js",
+    "hive": "tsx src/hive/index.ts",
+    "start:hive": "node dist/hive/index.js",
+    "demo": "vite build && LOCALDOST_DEMO=1 tsx src/index.ts",
+    "test": "npm run test:server && npm run test:client",
+    "test:server": "LOCALDOST_AIVISION_DEFAULT_PORT=5999 LOCALDOST_TEST_DEBOUNCE_DEFAULT_SEC=0 node scripts/with-tmp.mjs tsx --test test/*.test.ts test/hive/*.test.ts test/bee/*.test.ts",
+    "test:client": "node scripts/with-tmp.mjs vitest run --config vite.config.ts",
+    "test:e2e": "node scripts/with-tmp.mjs node scripts/e2e.mjs",
+    "lint": "eslint . --max-warnings=50",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "changelog:check": "node scripts/check-changelog.mjs",
+    "release": "node scripts/release.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc -p tsconfig.client.json && tsc -p .railway/tsconfig.json && tsc -p infra/cf-worker/tsconfig.json",
+    "seed": "tsx src/cli/seed.ts",
+    "dogfood": "tsx src/cli/dogfood.ts",
+    "eval:qa-review": "tsx src/cli/eval-qa-review.ts",
+    "eval:designer": "tsx src/cli/eval-designer.ts",
+    "golden:export": "tsx src/cli/golden-export.ts",
+    "scan": "tsx src/cli/scan-repo.ts",
+    "eval:chat": "tsx src/cli/eval-chat.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.131.0",
+    "@fastify/static": "^10.1.5",
+    "@fontsource-variable/inter": "^5.3.0",
+    "@katalon/playwright-reporter": "0.0.3",
+    "@linear/sdk": "^97.0.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@octokit/auth-app": "^8.3.1",
+    "@octokit/rest": "^22.0.1",
+    "@playwright/test": "^1.63.0",
+    "@slack/bolt": "^5.1.0",
+    "@tiptap/extension-list": "^3.31.4",
+    "@tiptap/extension-table": "^3.31.4",
+    "@tiptap/pm": "^3.31.4",
+    "@tiptap/react": "^3.31.4",
+    "@tiptap/starter-kit": "^3.31.4",
+    "dockerode": "^5.0.1",
+    "fastify": "^5.12.5",
+    "marked": "^18.1.0",
+    "playwright": "^1.63.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tiptap-markdown": "^0.9.0",
+    "uqr": "0.1.3",
+    "web-push": "^3.6.7"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@types/dockerode": "^4.0.1",
+    "@types/node": "^24.19.1",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@types/web-push": "^3.6.4",
+    "@vitejs/plugin-react": "^6.1.2",
+    "eslint": "^10.12.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "jsdom": "^30.1.2",
+    "prettier": "^3.9.9",
+    "railway": "3.13.1",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.71.1",
+    "vite": "^8.3.3",
+    "vitest": "^5.0.3"
+  }
+}