Does screen-decomposition work?

I mapped the owner's screens (the phone and desktop app) and the operator's commands into one tree, since both come from the same project. Forms are taken from the docs and file names in the dump. Two gaps: the dump has no in-app route names beyond `/onboarding`, so in-app screens are named by path, and the `ops/` listing is truncated, so some referenced scripts are unconfirmed. The questions at the end are the decisions I could not make for you.

```json
{"screens": [
{"path": [], "sentence": "The top of CodeBot: open the app, then pick an area. Operator areas are at the bottom.", "rows": [
{"name": "Open CodeBot", "form": "https://liel.tail18e69e.ts.net/", "what": "The private web app on phone or desktop; needs Tailscale on."},
{"name": "Local address", "form": "http://127.0.0.1:3505", "what": "The same app, reachable only from this computer."},
{"name": "Bots", "form": "screen bots", "what": "Your durable coding teammates, their chats, and which one needs you."},
{"name": "Terminal", "form": "screen terminal", "what": "A shell per Bot on this computer; off until the terminal broker runs."},
{"name": "Gmail", "form": "screen gmail", "what": "Connect Google, approve Bot email actions, see what Bots did."},
{"name": "Notifications", "form": "screen notifications", "what": "Turn alerts on for this device and check they arrive."},
{"name": "Account and sign-in", "form": "screen account", "what": "Sign-in, installing the phone app, onboarding, the entrance key."},
{"name": "This computer", "form": "screen host", "what": "Service status, logs, backup, restore, and address change."},
{"name": "Other people", "form": "screen people", "what": "Family CodeBots and the guest account on this machine."},
{"name": "Publish an update", "form": "screen update", "what": "Build, push, restart, and verify the running service."},
{"name": "Developer checks", "form": "screen check", "what": "Typecheck, tests, reviews, and the component playground."},
{"name": "Experiments", "form": "screen experiments", "what": "The V2, V3, V4 side apps, which live in their own repos."},
{"name": "What's new", "form": "notice shown once after an update (apps/web/src/whatsNew.ts)", "what": "What changed in the latest update, in the owner's words."}
]},
{"path": ["bots"], "sentence": "Every Bot with its provider, folder and state, and whether it is waiting for you.", "rows": [
{"name": "Create a Bot", "form": "screen bots/new", "what": "Start a new Bot with its name, provider, model, and folder."},
{"name": "Open a Bot", "form": "screen bots/<bot>", "what": "Its conversation, queue, and what it is doing right now."}
]},
{"path": ["bots", "new"], "sentence": "The form for a new Bot. Defaults come from the automatic model policy.", "rows": [
{"name": "Name and role", "form": "fields in the Bot form (BotForm.tsx)", "what": "What the Bot is called and what work it does."},
{"name": "Provider and model", "form": "fields in the Bot form", "what": "Claude, Codex, or OpenCode; an empty model uses the automatic policy."},
{"name": "Primary folder", "form": "field in the Bot form", "what": "Where the Bot works; must sit under CODEBOT_PROJECT_ROOTS."}
]},
{"path": ["bots", "<bot>"], "sentence": "One Bot's conversation: what it is doing, the composer, the queue, and any question it asked you.", "rows": [
{"name": "Send a message", "form": "the composer", "what": "Starts the next turn, or joins the queue if a reply is running."},
{"name": "Send queued messages now", "form": "POST /bots/:id/queue/send-now", "what": "Hands the queue to the running reply at once."},
{"name": "Take queued messages back", "form": "POST /bots/:id/queue/take", "what": "Returns queued messages to the composer to edit."},
{"name": "Stop", "form": "Esc or the Stop button", "what": "Interrupts the reply and keeps the queue."},
{"name": "Answer a question", "form": "the bot-question card in the conversation", "what": "Answer what the Bot asked before it continues."},
{"name": "Attach a file", "form": "the attachment picker", "what": "Adds files to the next message."},
{"name": "Pinned files and recordings", "form": "the resource panel (PinnedFiles.tsx, RecordingPlayer.tsx)", "what": "Files kept at hand, and Vision recordings to play back."},
{"name": "Chats", "form": "screen bots/<bot>/chats", "what": "Earlier chats, each one a separate provider session."},
{"name": "Widgets", "form": "screen bots/<bot>/widgets", "what": "Live panels for this Bot: Vision, screenshots, contract, git."},
{"name": "Settings", "form": "screen bots/<bot>/settings", "what": "Everything about this Bot, behind the cog button at top right."}
]},
{"path": ["bots", "<bot>", "chats"], "sentence": "The chats this Bot has had, each with its label and kind of work.", "rows": [
{"name": "Jump to a chat", "form": "the chat's divider in the conversation", "what": "Opens the point where that chat began."},
{"name": "Earlier chat text", "form": "chats/ folder in the Bot's home", "what": "Plain-text copy of each finished chat; the Bot reads the newest when you refer back."}
]},
{"path": ["bots", "<bot>", "widgets"], "sentence": "The live panels this Bot can show. There is at most one of each kind.", "rows": [
{"name": "Vision", "form": "kind vision", "what": "Live view of the browser the Bot drives, with recording."},
{"name": "Screenshot gallery", "form": "kind screenshot_gallery", "what": "Captured screenshots in capture order."},
{"name": "Feature contract", "form": "kind feature_contract", "what": "The Bot's current contract and its revisions."},
{"name": "Git quick info", "form": "kind git_quick_info", "what": "Repository status and quick git actions."},
{"name": "Gmail card", "form": "GmailWidget.tsx", "what": "This Bot's Gmail summary."},
{"name": "Arrange widgets", "form": "WidgetArrangement.tsx and WidgetBrowser.tsx", "what": "Choose and order which panels show."}
]},
{"path": ["bots", "<bot>", "settings"], "sentence": "Settings for one Bot, opened from the cog. Changes apply on its next turn.", "rows": [
{"name": "Provider and model", "form": "fields in the Bot form", "what": "Changes which provider and model the Bot uses."},
{"name": "Primary folder", "form": "field in the Bot form", "what": "Where the Bot works."},
{"name": "Skills and automatic actions", "form": "fields in the Bot form", "what": "Attached skills and what the Bot may do without asking."},
{"name": "Notifications for this Bot", "form": "switch", "what": "Alerts for replies, approval requests, and failures."},
{"name": "Enable this device", "form": "button; browser permission prompt", "what": "Subscribes this device to alerts from this Bot."},
{"name": "Send test", "form": "button", "what": "Checks the selected device gets alerts; a queued test is not proof."},
{"name": "Reconnect this device", "form": "button", "what": "Repairs an expired or rejected subscription."},
{"name": "Other devices", "form": "list", "what": "Remove old devices; up to 16 are kept."},
{"name": "Avatar", "form": "AvatarStudio.tsx and AvatarPicker.tsx", "what": "Change how the Bot looks."},
{"name": "Schedules", "form": "route not in the dump", "what": "Timed wakeups for this Bot."}
]},
{"path": ["terminal"], "sentence": "A shell per Bot on this computer. It works only while the per-user broker runs; otherwise it stays off.", "rows": [
{"name": "Turn the broker on", "form": "systemctl --user enable --now codebot-terminal-broker.service", "what": "Starts the separate broker; set the self-hosted options first."},
{"name": "Broker status", "form": "systemctl --user status codebot-terminal-broker.service --no-pager", "what": "Shows whether the broker is running."},
{"name": "Terminal tabs", "form": "TerminalPage.tsx and TerminalTab.tsx", "what": "Open a shell tab for a Bot."}
]},
{"path": ["gmail"], "sentence": "Gmail for Bots: whether Google is connected, what waits for your approval, and what Bots did.", "rows": [
{"name": "Connect Google", "form": "CODEBOT_GOOGLE_CLIENT_ID and CODEBOT_GOOGLE_CLIENT_SECRET in service.env", "what": "Lets Bots use Gmail; each person brings their own Google app unless the account service relays."},
{"name": "Approvals", "form": "screen gmail/approvals", "what": "Email actions waiting for your yes or no."},
{"name": "Activity", "form": "screen gmail/activity", "what": "The log of Gmail actions Bots took."},
{"name": "Daily summary", "form": "card on this screen (GmailDaily.tsx)", "what": "Today's Gmail summary."},
{"name": "Gmail reference", "form": "docs/automation/gmail.md", "what": "Guide for supervising Bots' Gmail use."}
]},
{"path": ["gmail", "approvals"], "sentence": "Gmail actions a Bot asked to take, waiting for a decision.", "rows": [
{"name": "Approve or decline", "form": "approval card on this screen", "what": "Decides one action; the Bot continues or stops."},
{"name": "Open the Bot that asked", "form": "screen bots/<bot>", "what": "See the conversation behind the request."}
]},
{"path": ["gmail", "activity"], "sentence": "A log of the Gmail actions Bots took.", "rows": [
{"name": "Open the Bot", "form": "screen bots/<bot>", "what": "See the conversation behind an action."}
]},
{"path": ["notifications"], "sentence": "Whether this device gets alerts from Bots, and whether they reach it.", "rows": [
{"name": "Enable this device", "form": "a Bot's settings, then the browser prompt", "what": "Subscribes this device to alerts."},
{"name": "Send test", "form": "a Bot's settings", "what": "Sends a test to the chosen device."},
{"name": "Notifications diagnostics", "form": "/api/notifications/diagnostics (signed-in owner)", "what": "Queue, timer, and active sends."},
{"name": "Recovery hold", "form": "CODEBOT_RECOVERY_HOLD=1 in service.env", "what": "Pauses automatic alerts and test sends."},
{"name": "iPhone and iPad", "form": "the installed Home Screen app", "what": "Alerts work only from the installed app there."}
]},
{"path": ["account"], "sentence": "How you sign in, how the phone app is installed, and how each person is onboarded.", "rows": [
{"name": "Sign-in entry", "form": "https://liel.tail18e69e.ts.net/onboarding", "what": "Where people sign in and are sent to their own host."},
{"name": "Entrance key", "form": "~/.local/share/codebot/owner-key", "what": "Key for new devices; read it locally and never paste it."},
{"name": "Install the phone app", "form": "browser Add to Home Screen", "what": "Installs CodeBot as an app on the phone."},
{"name": "Onboarding", "form": "screen account/onboarding", "what": "Replay or reset a person's first-use tour."},
{"name": "Account service", "form": "Supabase project wbgrjvqbupgdclaztuou", "what": "Central sign-in, redirect list, and progress rows."},
{"name": "Operator setup", "form": "npm run setup-account", "what": "Sets up the account for this server."}
]},
{"path": ["account", "onboarding"], "sentence": "Ways to show someone onboarding again. Each one changes data, and the last one deletes it.", "rows": [
{"name": "Replay the first-use tour", "form": "SQL on public.codebot_account_progress, then restart the host", "what": "Only when the person's host has no Bots."},
{"name": "Restart onboarding with a fresh CodeBot", "form": "wipe the host data except identity files, then the SQL", "what": "Their Bots go; the account and folders stay."},
{"name": "Full reset", "form": "delete the user in Supabase, then the host data folder", "what": "Everything goes, including conversations and recordings."}
]},
{"path": ["host"], "sentence": "This computer's CodeBot service: whether it runs, what it did, and how to back it up or move it.", "rows": [
{"name": "Service status", "form": "systemctl --user status codebot.service --no-pager", "what": "Running or stopped."},
{"name": "Recent logs", "form": "journalctl --user -u codebot.service -n 80 --no-pager", "what": "The last 80 log lines."},
{"name": "Host diagnostics", "form": "/api/diagnostics/host (signed-in app)", "what": "Counters, migrations, queued turns, recovery hold."},
{"name": "Restart", "form": "systemctl --user restart codebot.service", "what": "Only after active turns and recordings finish."},
{"name": "Emergency stop", "form": "systemctl --user stop --no-block codebot.service, then kill the service group", "what": "Interrupts Bot turns; uncommitted media may be lost."},
{"name": "Data folder", "form": "~/.local/share/codebot", "what": "Application data, separate from the checkout."},
{"name": "Back up", "form": "screen host/backup", "what": "A checked copy of the whole stopped installation."},
{"name": "Restore", "form": "screen host/restore", "what": "Restore beside the live copy and test it first."},
{"name": "Change address", "form": "screen host/address", "what": "Steps when the machine's Tailscale name changes."}
]},
{"path": ["host", "backup"], "sentence": "A copy of the whole stopped installation, with checksums. It holds secrets, so keep it private.", "rows": [
{"name": "Make a backup", "form": "stop the service, tar state and source, then start it, into ~/.local/share/codebot-backups/<UTC time>/", "what": "A consistent copy of data, source, and config."},
{"name": "Verify", "form": "sha256sum -c SHA256SUMS inside the backup folder", "what": "Confirms the copy is intact."},
{"name": "Keep it private", "form": "mode 0700, outside project roots", "what": "The copy includes owner sessions, the entrance key, and provider profiles."}
]},
{"path": ["host", "restore"], "sentence": "Restore a backup beside the live copy, check it, run it on a spare port, then promote it.", "rows": [
{"name": "Check checksums", "form": "sha256sum -c SHA256SUMS", "what": "Confirms the backup before extracting."},
{"name": "Extract to a new folder", "form": "~/.local/share/codebot-restore-staging", "what": "Keeps the original installation intact."},
{"name": "Check the database", "form": "integrity check in ops/OPERATIONS.md", "what": "Confirms the restored database is sound."},
{"name": "Inspect on a spare port", "form": "http://127.0.0.1:3508 with CODEBOT_RECOVERY_HOLD=1", "what": "Look without automatic work starting."},
{"name": "Promote", "form": "stop the original, point CODEBOT_DATA_DIR at the restore, start in hold", "what": "Never run two hosts from copies of the same queued state."}
]},
{"path": ["host", "address"], "sentence": "CodeBot's address is the machine's Tailscale name. Renaming it breaks sign-in until every place below is updated.", "rows": [
{"name": "Current name", "form": "tailscale status --json (Self.DNSName)", "what": "The new name, to compare with the old one."},
{"name": "Sign-in allow list", "form": "Supabase URL configuration", "what": "Add the new /onboarding first; keep the old one until the end."},
{"name": "Owner config", "form": "service.env CODEBOT_ACCOUNT_ENTRY_URL and apps/web/.env.local, then npm run build and restart", "what": "Points the owner's host at the new name."},
{"name": "Guest config", "form": "/home/codebot-guest/.config/codebot/service.env, then ops/guest-update.sh", "what": "Points the guest host at the new name."},
{"name": "Account addresses", "form": "SQL update on public.codebot_account_progress", "what": "Sends each person to the new address at sign-in."},
{"name": "Phone apps", "form": "reinstall from the new address", "what": "An installed app belongs to the address it came from."},
{"name": "Domain forward", "form": "codebot.lielbenor.com redirect at the registrar", "what": "Sends people who start at the fixed address."}
]},
{"path": ["people"], "sentence": "Other people's CodeBots on this machine: family on the home Wi-Fi, and the guest account.", "rows": [
{"name": "Family CodeBots", "form": "screen people/family", "what": "One CodeBot per family Google account, at most six."},
{"name": "Guest account", "form": "screen people/guest", "what": "A second CodeBot under its own Linux user."}
]},
{"path": ["people", "family"], "sentence": "Family members each get a CodeBot of their own, signed in with their Google account.", "rows": [
{"name": "Family address", "form": "https://family.codebot.lielbenor.com:10100+N", "what": "Works at home directly; away from home, for invited people with the route approved."},
{"name": "Add a family CodeBot", "form": "sudo codebot-family add N", "what": "Creates CodeBot number N for a new Google account."},
{"name": "Remove one", "form": "sudo codebot-family remove N", "what": "Deletes that CodeBot and frees its number; the Google account stays linked."},
{"name": "Status", "form": "sudo codebot-family status", "what": "Whether each one runs and whether Gmail can connect."},
{"name": "Stop or start all", "form": "sudo codebot-family stop-all, or start-all", "what": "Pauses or resumes every family CodeBot."},
{"name": "Install once", "form": "sudo ops/family-install.sh", "what": "Sets up the front door, helper, services, and nginx."},
{"name": "Update", "form": "ops/family-update.sh", "what": "Rebuilds and restarts all family CodeBots; no password needed."},
{"name": "Service logs", "form": "journalctl -u codebot-family-lobby -u 'codebot-family@*'", "what": "Logs for the front door and each family CodeBot."}
]},
{"path": ["people", "guest"], "sentence": "A second CodeBot on this machine under its own Linux user, reached at port 10000.", "rows": [
{"name": "Invite link", "form": "sudo -u codebot-guest /opt/codebot-guest/invite", "what": "One-use Google link, valid ten minutes."},
{"name": "Guest address", "form": "https://liel.tail18e69e.ts.net:10000", "what": "The guest's CodeBot on this machine."},
{"name": "Install once", "form": "sudo ops/guest-install.sh", "what": "Creates the user, service, settings, and sudo rules."},
{"name": "Update", "form": "ops/guest-update.sh", "what": "Builds, replaces the program, and restarts; no password needed."},
{"name": "Status and logs", "form": "systemctl status codebot-guest; journalctl -u codebot-guest", "what": "Whether it runs and what it logged."},
{"name": "Disk use", "form": "sudo du -sh /home/codebot-guest", "what": "How much space the guest uses."},
{"name": "Remove", "form": "sudo systemctl disable --now codebot-guest, then userdel -r codebot-guest", "what": "Deletes the guest's data and account."}
]},
{"path": ["update"], "sentence": "Publish code and frontend changes to the running service.", "rows": [
{"name": "Build", "form": "npm run build", "what": "Typechecks and builds a new release; the served one stays if this fails."},
{"name": "Deploy", "form": "sh ops/deploy.sh", "what": "Commits, pushes, waits for Bots, restarts, and verifies; refuses while a Bot works."},
{"name": "Restart by hand", "form": "systemctl --user restart codebot.service", "what": "Only after active turns and recordings finish."},
{"name": "Verify", "form": "curl http://127.0.0.1:3505/api/session, and a new ExecMainStartTimestamp", "what": "Confirms the new process is serving."},
{"name": "Tell the owner", "form": "apps/web/src/whatsNew.ts", "what": "The note shown once after an update."}
]},
{"path": ["check"], "sentence": "Developer checks: typecheck, tests, reviews, and the component playground.", "rows": [
{"name": "Install", "form": "npm ci", "what": "Installs the pinned dependencies."},
{"name": "Run locally", "form": "npm run dev", "what": "Runs the service with reload on port 3505."},
{"name": "Typecheck", "form": "npm run typecheck", "what": "Compiles without emitting; says little about Bot behaviour."},
{"name": "Tests", "form": "npm test", "what": "Gmail automation tests against a fake Google."},
{"name": "Typecheck and tests", "form": "npm run check", "what": "Both at once."},
{"name": "Integration build", "form": "npm run build:integration", "what": "Builds the QA instance on port 3506."},
{"name": "Gmail reference", "form": "npm run docs:gmail", "what": "Regenerates docs/automation/gmail-reference.md."},
{"name": "Gmail review", "form": "npm run review:gmail", "what": "Checks the Gmail flow in a real browser."},
{"name": "Schedules review", "form": "npm run review:schedules", "what": "Checks the schedules flow."},
{"name": "Component playground", "form": "npm run playground", "what": "Side-by-side screen variants at 127.0.0.1."},
{"name": "Sync agent notes", "form": "npm run sync:agents", "what": "Regenerates AGENTS.md from CLAUDE.md."}
]},
{"path": ["experiments"], "sentence": "Three experimental apps in their own repos, each on its own port. They reuse CodeBot's server.", "rows": [
{"name": "V2 Terminal chat", "form": "http://127.0.0.1:3512 from ~/projects/codebot-v2-terminal-chat", "what": "CodeBot's look; a Bot's chat is the Claude Code terminal."},
{"name": "V3 Claude Code mod", "form": "http://127.0.0.1:3513 from ~/projects/codebot-v3-claude-mod", "what": "Claude Code first; a mod draws the Bot list above the prompt."},
{"name": "V4 Launcher menu", "form": "http://127.0.0.1:3514 from ~/projects/codebot-v4-launcher-menu", "what": "A simple menu whose buttons start Claude Code sessions."},
{"name": "Start one", "form": "sh ops/app-run.sh dev, in that folder, in its own terminal", "what": "Runs one app with its own broker."},
{"name": "Stop one", "form": "ss -ltnp | grep :3513, then stop that process id", "what": "Stops only that app; never stop by name pattern."}
]}
],
"questions": [
"Two help trees or one? Recommendation: one owner tree (bots, terminal, gmail, notifications, account) and a separate ops tree (host, people, update, check, experiments), since the owner's path should not need operator work.",
"Should destructive operations appear in help: the full reset, restart onboarding, emergency stop, and removing a family or guest CodeBot? Recommendation: leave them out of top-level help and reach them only through the ops tree, each behind an explicit confirmation step.",
"Include the V2, V3, V4 experiments? They live in private repos outside CodeBot. Recommendation: keep them out of the main help and show the experiments screen only when those folders exist.",
"In-app screen names: the dump gives no web routes beyond /onboarding and the API paths. Recommendation: confirm the real route list from the web app's router before the help text links to it; until then the screens stay named by path.",
"Where do schedules live? docs/objectives/schedules.md exists, but no screen file in the dump is clearly schedules. I placed them under Bot settings as a guess. Please confirm.",
"Terminal when the broker is not installed: show the screen as off with the enable command, or hide it? Recommendation: show it as off with the command, so the owner can see why it is missing.",
"Should the CLI print the entrance key? Recommendation: no; show only its path, since it is a secret.",
"Confirm these referenced files exist: ops/deploy.sh, ops/app-run.sh, ops/guest-install.sh, ops/guest-update.sh, ops/family-install.sh, ops/family-update.sh, ops/setup-account.ts, ops/terminal-broker.ts. The ops listing in the dump is truncated, so I could not verify them. Also, README.md mentions cli/codebot.py, which is not in the file list; confirm whether it exists and what it should cover."
]}
```

## Scenario (reasoning from experience)

The owner runs this machine's CodeBot from a desktop terminal, usually after a change, to see whether the host is up, read its log, or back up before something risky. Less often they invite a guest, add a family member, or rotate the address. The CLI should answer "where is it, what does it do, and what's the one command I need" without the runbook open.

## Judgment calls

- **Top level has nine groups**, each named in the owner's words (`run`, `deploy`, `data`, `guest`, `family`, `account`, `experiments`, `docs`, `check`). That keeps the first screen short.
- **Experiments V2 to V4 each get a screen.** Each has its own port, folder and stop procedure.
- **Destructive or high-stakes steps are runbook links, not commands**: restore, full reset, forced kill, removing a guest, changing the address. The map points to the section in `ops/OPERATIONS.md`.
- **Secrets are opened, never printed.** `service.env` and `owner-key` appear as "opens the file" rows only.
- **Three columns are enough.** A fourth "needs sudo" column would add noise, so sudo is written into the command.
- **Some files are named in the README but are not in the dump** (`PRODUCT-SPEC.md`, `IMPLEMENTATION-STATUS.md`, `DEFERRED-WORK.md`). They are mapped on the assumption they exist at the repo root. Verify before building.
- **The Supabase dashboard URL is derived** from the project ref in the runbook, not copied from a link in the dump.

The open decisions are in `questions` at the end of the JSON. The two that block building are the command name and whether commands run or only print.

```json
{"screens": [
{"path": [], "sentence": "The command line for CodeBot on this machine: the owner's CodeBot, the guest and family copies, and where their files, docs and accounts live.", "rows": [
{"name": "Owner's CodeBot", "form": "codebot run", "what": "Prints the owner's CodeBot screen: starting, stopping and checking the host on port 3505."},
{"name": "Deploy", "form": "codebot deploy", "what": "Prints the deploy screen: building, restarting and verifying a new version of the owner's CodeBot."},
{"name": "Checks", "form": "codebot check", "what": "Prints the check screen: type checks, tests and review scripts."},
{"name": "Data", "form": "codebot data", "what": "Prints the data screen: where the owner's data lives, and the steps to back it up, restore it or reset someone's onboarding."},
{"name": "Guest CodeBot", "form": "codebot guest", "what": "Prints the guest screen: the second CodeBot on this machine for another person."},
{"name": "Family CodeBots", "form": "codebot family", "what": "Prints the family screen: the sign-in front door and one CodeBot for each family member."},
{"name": "Account service", "form": "codebot account", "what": "Prints the account screen: the shared sign-in service and its deploy steps."},
{"name": "Experiments", "form": "codebot experiments", "what": "Prints the experiments screen: three experimental apps that reuse CodeBot's server."},
{"name": "Docs", "form": "codebot docs", "what": "Prints the docs screen: the guides, plans and behaviour records, each opened from its file."}
]},
{"path": ["run"], "sentence": "The owner's CodeBot on this machine: its state, its log, and the addresses it answers on.", "rows": [
{"name": "Start the owner's CodeBot", "form": "systemctl --user start codebot.service", "what": "Starts the owner's host on port 3505, the one you sign in to."},
{"name": "Stop the owner's CodeBot", "form": "systemctl --user stop codebot.service", "what": "Stops the host cleanly, ending running turns and closing browser work."},
{"name": "Owner's CodeBot status", "form": "systemctl --user status codebot.service --no-pager", "what": "Prints whether the host is running and when it last started."},
{"name": "Owner's CodeBot log", "form": "journalctl --user -u codebot.service -n 80 --no-pager", "what": "Prints the last 80 log lines of the host."},
{"name": "Host answers check", "form": "curl --fail --silent http://127.0.0.1:3505/api/session", "what": "Checks that the host on port 3505 answers, and prints its session state."},
{"name": "Owner's CodeBot in the browser", "form": "https://liel.tail18e69e.ts.net/", "what": "Opens the owner's CodeBot at its private address."},
{"name": "Host diagnostics", "form": "https://liel.tail18e69e.ts.net/api/diagnostics/host", "what": "Opens the host's counters and lifecycle state; sign-in is required."},
{"name": "Private address mapping", "form": "tailscale serve status --json", "what": "Prints which private address reaches the host through Tailscale."},
{"name": "Start the QA copy", "form": "systemctl --user start codebot-integration.service", "what": "Starts the disposable QA copy on port 3506, for trying changes before they reach the owner."},
{"name": "Development server", "form": "npm run dev", "what": "Runs the host from this checkout and restarts it on every code change."},
{"name": "Terminal broker status", "form": "systemctl --user status codebot-terminal-broker.service", "what": "Prints whether the per-user terminal broker is running."}
]},
{"path": ["deploy"], "sentence": "Putting a change into the owner's CodeBot: the steps from code to a running host.", "rows": [
{"name": "Deploy the checkout", "form": "sh ops/deploy.sh", "what": "Deploys the current code: builds, commits, pushes, restarts the host and verifies it, waiting while a Bot works."},
{"name": "Build a release", "form": "npm run build", "what": "Builds a new release and swaps it in only when the build succeeds."},
{"name": "Install dependencies", "form": "npm ci", "what": "Installs the exact locked dependencies before a build."},
{"name": "Restart the owner's CodeBot", "form": "systemctl --user restart codebot.service", "what": "Restarts the host to load a new build, after active turns and recordings finish."},
{"name": "Kept releases", "form": "dist/releases/", "what": "Opens the kept releases: the current one and the two before it."},
{"name": "Deploy guard", "form": "ops/deploy-guard.sh", "what": "Blocks finishing a turn while code is unpushed, newer than the running service, or newer than the served build."},
{"name": "Install and update steps", "form": "ops/OPERATIONS.md (section: Install or update the host)", "what": "Opens the install and update steps."},
{"name": "Service unit", "form": "ops/codebot.service", "what": "Opens the systemd unit that runs the host."}
]},
{"path": ["check"], "sentence": "The checks and review scripts for this project, run from the checkout.", "rows": [
{"name": "Typecheck", "form": "npm run typecheck", "what": "Compiles the code with the TypeScript checker, writing no files."},
{"name": "Tests", "form": "npm test", "what": "Runs the Gmail automation tests against a fake Google server."},
{"name": "Typecheck and tests", "form": "npm run check", "what": "Runs the typecheck, then the service tests."},
{"name": "Build the QA copy", "form": "npm run build:integration", "what": "Typechecks, then builds the bundle for the QA copy."},
{"name": "Review Gmail", "form": "npm run review:gmail", "what": "Runs the Gmail review script."},
{"name": "Review schedules", "form": "npm run review:schedules", "what": "Runs the schedules review script."},
{"name": "Regenerate Gmail reference", "form": "npm run docs:gmail", "what": "Regenerates the Gmail reference document from the code."},
{"name": "Sync agent instructions", "form": "npm run sync:agents", "what": "Regenerates AGENTS.md from CLAUDE.md."},
{"name": "Design playground", "form": "npm run playground", "what": "Starts the design playground on 127.0.0.1 and opens the Gmail sample."},
{"name": "Behaviour test steps", "form": ".bdd/steps/", "what": "Opens the behaviour test steps; no runner script is listed in package.json yet."}
]},
{"path": ["data"], "sentence": "The owner's data on this machine: where it lives, and the steps to back it up, restore it or reset someone's onboarding.", "rows": [
{"name": "Data folder", "form": "~/.local/share/codebot", "what": "Opens the data folder: the database, sessions and media."},
{"name": "Database", "form": "~/.local/share/codebot/codebot.sqlite", "what": "Opens the owner's database file."},
{"name": "Entrance key", "form": "~/.local/share/codebot/owner-key", "what": "Opens the key a new device needs to connect; its value is never printed."},
{"name": "Settings file", "form": "~/.config/codebot/service.env", "what": "Opens the private settings file; its values are never printed."},
{"name": "Project folders", "form": "~/projects", "what": "Opens the folders Bots may reach, set by CODEBOT_PROJECT_ROOTS."},
{"name": "Backups folder", "form": "~/.local/share/codebot-backups", "what": "Opens the folder of backups."},
{"name": "Make a backup", "form": "ops/OPERATIONS.md (section: Back up a consistent installation)", "what": "Opens the steps that stop the host and copy its data."},
{"name": "Restore a backup", "form": "ops/OPERATIONS.md (section: Restore into a separate directory first)", "what": "Opens the steps that restore into a separate folder first."},
{"name": "Emergency stop and rollback", "form": "ops/OPERATIONS.md (section: Emergency stop and rollback)", "what": "Opens the steps for stopping the host at once or rolling back."},
{"name": "Reset someone's onboarding", "form": "ops/OPERATIONS.md (section: Reset someone's onboarding)", "what": "Opens the steps for showing one person the onboarding again."}
]},
{"path": ["guest"], "sentence": "The guest CodeBot: a second CodeBot on this machine for another person, run as its own Linux user.", "rows": [
{"name": "Guest status", "form": "systemctl status codebot-guest", "what": "Prints whether the guest's CodeBot is running."},
{"name": "Guest log", "form": "journalctl -u codebot-guest", "what": "Prints the guest's CodeBot log."},
{"name": "Guest disk use", "form": "sudo du -sh /home/codebot-guest", "what": "Prints how much disk the guest's CodeBot uses."},
{"name": "Guest CodeBot in the browser", "form": "https://liel.tail18e69e.ts.net:10000", "what": "Opens the guest's CodeBot at its private address."},
{"name": "Packaged guest copy", "form": "/opt/codebot-guest", "what": "Opens the packaged copy the guest service runs."},
{"name": "Update the guest", "form": "ops/guest-update.sh", "what": "Builds the current version, replaces the guest copy and restarts it; needs no password."},
{"name": "Invite someone", "form": "sudo -u codebot-guest /opt/codebot-guest/invite", "what": "Makes a one-use Google invite link, valid for ten minutes."},
{"name": "Install the guest (once)", "form": "sudo ops/guest-install.sh", "what": "Sets up the guest user, service, settings, sudo rules and Tailscale port 10000."},
{"name": "Remove the guest", "form": "ops/OPERATIONS.md (section: Host a guest on this machine)", "what": "Opens the removal steps; they are not run from here."}
]},
{"path": ["family"], "sentence": "The family CodeBots: the sign-in front door and one CodeBot for each family member, on the home Wi-Fi.", "rows": [
{"name": "Family status", "form": "sudo codebot-family status", "what": "Prints which family CodeBots are running, and whether each can connect Gmail."},
{"name": "Family log", "form": "journalctl -u codebot-family-lobby -u 'codebot-family@*'", "what": "Prints the front door's and the family CodeBots' log."},
{"name": "Family sign-in page", "form": "https://family.codebot.lielbenor.com", "what": "Opens the family sign-in page."},
{"name": "Add a family CodeBot", "form": "sudo codebot-family add N", "what": "Creates a CodeBot for family member N, up to six."},
{"name": "Remove a family CodeBot", "form": "sudo codebot-family remove N", "what": "Deletes that CodeBot and frees its number; the Google account stays linked for good."},
{"name": "Stop all family CodeBots", "form": "sudo codebot-family stop-all", "what": "Stops every family CodeBot."},
{"name": "Start all family CodeBots", "form": "sudo codebot-family start-all", "what": "Starts every family CodeBot."},
{"name": "Update the family", "form": "ops/family-update.sh", "what": "Builds, replaces the family copy and restarts all of them; needs no password."},
{"name": "Install the family (once)", "form": "sudo ops/family-install.sh", "what": "Sets up the front door, helper, services, sudo rules and nginx."},
{"name": "Root helper", "form": "/usr/local/sbin/codebot-family", "what": "Opens the root helper script that adds, removes and reports on family CodeBots."},
{"name": "Family settings", "form": "/etc/codebot-family.conf", "what": "Opens the settings file the helper reads."},
{"name": "Family runbook", "form": "ops/OPERATIONS.md (section: Home Wi-Fi address)", "what": "Opens the family setup, address and removal steps."}
]},
{"path": ["account"], "sentence": "The shared account service that handles sign-in and the host handshake, and the steps that depend on this machine's address.", "rows": [
{"name": "Account service dashboard", "form": "https://supabase.com/dashboard/project/wbgrjvqbupgdclaztuou", "what": "Opens the account service project in Supabase."},
{"name": "Command-line token", "form": "~/.config/supabase-codebot-token", "what": "Opens the token file the Supabase command line uses; its value is never printed."},
{"name": "Deploy host-access", "form": "SUPABASE_ACCESS_TOKEN=\"$(cat ~/.config/supabase-codebot-token)\" npx supabase functions deploy host-access --project-ref wbgrjvqbupgdclaztuou", "what": "Deploys the host-access function; redeploy whenever a contract it parses changes."},
{"name": "Account service functions", "form": "supabase/functions/", "what": "Opens the gmail-relay and host-access functions."},
{"name": "Database migrations", "form": "supabase/migrations/", "what": "Opens the database migrations in order."},
{"name": "Change this machine's address", "form": "ops/OPERATIONS.md (section: Change this machine's address)", "what": "Opens the checklist of every place that holds the address, and the order to change them."}
]},
{"path": ["experiments"], "sentence": "Three experimental apps that reuse CodeBot's server. Each is in its own private repo and runs on this computer only.", "rows": [
{"name": "V2 Terminal chat", "form": "codebot experiments v2", "what": "Prints the V2 screen: CodeBot's look, where a Bot's chat is the Claude Code terminal, on port 3512."},
{"name": "V3 Claude Code mod", "form": "codebot experiments v3", "what": "Prints the V3 screen: Claude Code first, with a mod drawing the Bot list above the prompt, on port 3513."},
{"name": "V4 Launcher menu", "form": "codebot experiments v4", "what": "Prints the V4 screen: a simple main menu whose buttons set up Claude Code sessions, on port 3514."}
]},
{"path": ["experiments", "v2"], "sentence": "The V2 Terminal chat app: CodeBot's look and Bot list, where a Bot's chat is the Claude Code terminal.", "rows": [
{"name": "Start V2", "form": "cd ~/projects/codebot-v2-terminal-chat && sh ops/app-run.sh dev", "what": "Starts V2 on port 3512; run it in its own terminal."},
{"name": "V2 in Chrome", "form": "http://127.0.0.1:3512", "what": "Opens V2 in the browser."},
{"name": "V2 folder", "form": "~/projects/codebot-v2-terminal-chat", "what": "Opens the V2 project folder."},
{"name": "Process holding port 3512", "form": "ss -ltnp | grep :3512", "what": "Prints the process that holds the port, which is the one to stop."},
{"name": "V2 notes", "form": "~/projects/codebot-v2-terminal-chat/docs/experiment/", "what": "Opens the owner's vision, decision log and report for V2."}
]},
{"path": ["experiments", "v3"], "sentence": "The V3 Claude Code mod app: Claude Code first, with a mod drawing the Bot list above the prompt.", "rows": [
{"name": "Start V3", "form": "cd ~/projects/codebot-v3-claude-mod && sh ops/app-run.sh dev", "what": "Starts V3 on port 3513; run it in its own terminal."},
{"name": "V3 in Chrome", "form": "http://127.0.0.1:3513", "what": "Opens V3 in the browser."},
{"name": "V3 folder", "form": "~/projects/codebot-v3-claude-mod", "what": "Opens the V3 project folder."},
{"name": "Process holding port 3513", "form": "ss -ltnp | grep :3513", "what": "Prints the process that holds the port, which is the one to stop."},
{"name": "List background sessions", "form": "claude agents", "what": "Prints the ids of V3's background Claude Code sessions."},
{"name": "Stop an old test Bot", "form": "claude stop <id>", "what": "Stops one background Claude Code session by its id."},
{"name": "V3 notes", "form": "~/projects/codebot-v3-claude-mod/docs/experiment/", "what": "Opens the owner's vision, decision log and report for V3."}
]},
{"path": ["experiments", "v4"], "sentence": "The V4 Launcher menu app: a simple main menu whose buttons set up the Claude Code sessions.", "rows": [
{"name": "Start V4", "form": "cd ~/projects/codebot-v4-launcher-menu && sh ops/app-run.sh dev", "what": "Starts V4 on port 3514; run it in its own terminal."},
{"name": "V4 in Chrome", "form": "http://127.0.0.1:3514", "what": "Opens V4 in the browser."},
{"name": "V4 folder", "form": "~/projects/codebot-v4-launcher-menu", "what": "Opens the V4 project folder."},
{"name": "Process holding port 3514", "form": "ss -ltnp | grep :3514", "what": "Prints the process that holds the port, which is the one to stop."},
{"name": "V4 notes", "form": "~/projects/codebot-v4-launcher-menu/docs/experiment/", "what": "Opens the owner's vision, decision log and report for V4."}
]},
{"path": ["docs"], "sentence": "The guides, records and plans for this project, each opened from its file.", "rows": [
{"name": "Overview", "form": "README.md", "what": "Opens the README: what CodeBot is, how it runs and how it is verified."},
{"name": "Behaviour contract", "form": "PRODUCT-SPEC.md", "what": "Opens the behaviour contract."},
{"name": "Architecture", "form": "ARCHITECTURE.md", "what": "Opens how CodeBot is built and where its boundaries lie."},
{"name": "Open work", "form": "DEFERRED-WORK.md", "what": "Opens the remaining checklist and the safe restart state."},
{"name": "Implementation status", "form": "IMPLEMENTATION-STATUS.md", "what": "Opens what has been built so far."},
{"name": "Standing rules", "form": "CLAUDE.md", "what": "Opens the fundamentals every task assumes; AGENTS.md is generated from it."},
{"name": "Operations runbook", "form": "ops/OPERATIONS.md", "what": "Opens the runbook for running, backing up and recovering the host."},
{"name": "Gmail for Bots", "form": "docs/automation/gmail.md", "what": "Opens the Gmail setup and supervisor guide."},
{"name": "Gmail reference", "form": "docs/automation/gmail-reference.md", "what": "Opens the generated Gmail reference."},
{"name": "Design method", "form": "docs/design-method.md", "what": "Opens the method for designing screens."},
{"name": "Design rulings", "form": "docs/design-taste.md", "what": "Opens the owner's design rulings and rejections."},
{"name": "Plans", "form": "docs/plans/", "what": "Opens the plan documents, one per piece of work."},
{"name": "Objectives", "form": "docs/objectives/README.md", "what": "Opens the product objectives."},
{"name": "Verification records", "form": "docs/verification/", "what": "Opens the recorded evidence that work was checked."},
{"name": "Module intents", "form": ".idd/modules/", "what": "Opens the intent record of each module: its constraints and tests."},
{"name": "Behaviour features", "form": ".bdd/features/", "what": "Opens the Given, When, Then behaviour features."},
{"name": "QA findings and resolutions", "form": ".bdd/qa/", "what": "Opens the QA findings and how each was resolved."},
{"name": "Housekeeping skill", "form": "skills/codebot-housekeeping/SKILL.md", "what": "Opens the housekeeping skill."}
]}
],
"questions": [
"Name and alias. Recommend the top command is 'codebot' with 'cb' as the short alias, if whence and type show no clash. The README mentions a cli/codebot.py that is not in the file list; if it is planned, its commands should be folded into this map.",
"Run or print? Recommend that the CLI runs only safe, reversible commands (status, logs, build, checks) and prints the rest (stop, restart, deploy, sudo commands, anything touching the guest or family copies) for the owner to run. Deploy commits and pushes, so it should not run unasked.",
"npm run dev binds the default port 3505, the same port as the systemd host, so the two cannot run together. Recommend keeping the row with that warning, or dropping it from the CLI.",
"Experiments V2 to V4 live in other private repos. Recommend keeping them as one group under this CLI because the README launches them from here. The alternative is a separate CLI for them.",
"The Supabase dashboard link is derived from the project ref in the runbook. Confirm it opens. The runbook also names gmail-relay as a function but gives no deploy command for it; confirm whether to list one.",
"The docs screen has 18 rows. Recommend one screen for now, and a split into 'docs' and 'docs, design' (design method, design rulings, playground) once it passes about 15 rows. Say yes to split now, or keep it.",
"The behaviour test steps in .bdd/steps have no npm script. Which command runs them? Until one is named, the row points at the folder."
]}
```

**Scenario** (from `CLAUDE.md`, `ops/OPERATIONS.md`, reasoning from experience): the owner opens CodeBot on a phone to see which Bot needs them, read its chat, and steer it. The operator, at the workstation, checks the service, deploys, backs up, and recovers when something breaks.

**Inventory:** every item on the screens below. Its form is a file, command, URL, or the screen itself. I read only the dump, so I could not run anything or confirm files outside it. `OPERATIONS.md` was cut at 32,000 characters and `ARCHITECTURE.md` at 14,000, so some runbook detail may be missing.

**Judgment calls**
- Owner screens come first, since the owner is phone-first. Operator screens sit under `host` and `scripts`.
- Where the component file for a screen was not in the dump (chat, Vision, screenshots, Git, schedules), its form is the screen path, not a guessed file.
- Runbook steps stay in `OPERATIONS.md`, and the map links to their section instead of retyping them (one source).
- `owner-key` is listed by path only. The runbook says not to print it, so its row says it prints the key.
- `deploy.sh` and `npm run build` are both listed, since deploy runs the build.

**Questions for you**
1. **Split the Bot screen?** It has 14 rows. *Recommendation:* yes. Move Vision, Screenshots, Contract, Git, and the Gmail widget behind a `widgets` screen under Bot. The app's `WidgetBrowser` already groups them that way.
2. **Should the operator screens (`host`, `scripts`) appear in the app, or only in the terminal help?** *Recommendation:* terminal only. The owner never needs them from a phone.
3. **Is there a `cli/codebot.py`?** The README refers to it, but it is not in the tree. `PRODUCT-SPEC.md`, `IMPLEMENTATION-STATUS.md`, and `MASTER-PLAN.md` are also cited but not in the dump, so I left them out. *Recommendation:* tell me if they exist and I'll add their rows.

```json
{"screens": [
{"path": [], "sentence": "The top of CodeBot: the Bots you steer, this CodeBot's settings, and the operator's places for the running host, the scripts and the docs.", "rows": [
{"name": "Bots", "form": "screen: bots (apps/web/src/App.tsx)", "what": "Opens the list of Bots, each with what it is doing and whether it needs you."},
{"name": "Settings", "form": "screen: settings (apps/web/src/ui/Settings.tsx)", "what": "Opens this CodeBot's notification, Gmail and update settings."},
{"name": "Host", "form": "screen: host (ops/OPERATIONS.md)", "what": "Opens the operator's places for the running service, its data, guests, family and address."},
{"name": "Scripts", "form": "screen: scripts (package.json)", "what": "Opens the npm scripts that run, check, build and review the checkout."},
{"name": "Docs", "form": "screen: docs (README.md, docs/)", "what": "Opens the written docs: layout, architecture, runbook, open work and recorded evidence."}
]},
{"path": ["bots"], "sentence": "The Bots you have, each with what it is doing and whether it needs you.", "rows": [
{"name": "A Bot", "form": "screen: bots > Bot (apps/web/src/workspace/)", "what": "Opens one Bot's conversation, files, widgets and settings."},
{"name": "New Bot", "form": "apps/web/src/workspace/BotForm.tsx", "what": "Creates a Bot from a name, a role, a provider and a home folder."},
{"name": "First-use tour", "form": "apps/web/src/onboarding/Onboarding.tsx", "what": "Shows the tour that creates a first Bot for a new account."}
]},
{"path": ["bots", "Bot"], "sentence": "The conversation with one Bot, with its files, widgets and settings.", "rows": [
{"name": "Chat", "form": "screen: bots > Bot > chat", "what": "Shows the conversation and the queue of messages waiting for this Bot."},
{"name": "Terminal", "form": "apps/web/src/TerminalTab.tsx", "what": "Opens this Bot's terminal, the shell it works in on this host."},
{"name": "Pinned files", "form": "apps/web/src/resources/PinnedFiles.tsx", "what": "Lists the files pinned to this Bot and opens each one."},
{"name": "Attach a file", "form": "apps/web/src/resources/AttachmentPicker.tsx", "what": "Attaches a file to the next message."},
{"name": "Recordings", "form": "apps/web/src/resources/RecordingPlayer.tsx", "what": "Plays a recording of this Bot's browser work."},
{"name": "Vision", "form": "screen: bots > Bot > vision", "what": "Shows the live Chromium page this Bot is using."},
{"name": "Screenshots", "form": "screen: bots > Bot > screenshots", "what": "Shows the screenshots this Bot has captured, newest first."},
{"name": "Feature contract", "form": "apps/web/src/contracts/ContractCatalog.tsx", "what": "Opens this Bot's feature contract: its catalog, files, history and conflicts."},
{"name": "Git", "form": "screen: bots > Bot > git", "what": "Shows the repository's status and its quick git actions."},
{"name": "Gmail widget", "form": "apps/web/src/widgets/GmailWidget.tsx", "what": "Shows the Gmail items this Bot needs approved or has handled."},
{"name": "Widgets", "form": "apps/web/src/widgets/WidgetBrowser.tsx", "what": "Adds, removes or rearranges the widgets on this Bot's surface."},
{"name": "Avatar", "form": "apps/web/src/workspace/AvatarStudio.tsx", "what": "Designs this Bot's avatar."},
{"name": "Schedules", "form": "screen: bots > Bot > schedules (docs/objectives/schedules.md)", "what": "Lists the wakeups scheduled for this Bot."},
{"name": "Bot settings", "form": "apps/web/src/workspace/BotForm.tsx", "what": "Edits this Bot's name, role, provider, model, folder and notifications."}
]},
{"path": ["settings"], "sentence": "This CodeBot's own settings: notifications on this device, Gmail, and updates.", "rows": [
{"name": "Notifications", "form": "apps/web/src/pwa/DeviceNotifications.tsx", "what": "Enables notifications on this device, sends it a test, and removes old devices."},
{"name": "Gmail access", "form": "apps/web/src/gmail/GmailAccess.tsx", "what": "Connects the Google account the Bots use for Gmail."},
{"name": "Gmail activity", "form": "apps/web/src/gmail/GmailActivity.tsx", "what": "Shows what Bots did with Gmail and the day's summary."},
{"name": "Update notice", "form": "apps/web/src/pwa/UpdateNotice.tsx", "what": "Shows what changed after an update, from apps/web/src/whatsNew.ts."},
{"name": "Install on phone", "form": "docs/OPERATIONS.md (Private access and PWA installation)", "what": "Adds CodeBot to the phone's Home Screen from the private HTTPS address."}
]},
{"path": ["host"], "sentence": "The operator's place for the service running on this machine: its status, logs, deployment and sub-areas.", "rows": [
{"name": "Service status", "form": "systemctl --user status codebot.service --no-pager", "what": "Prints whether codebot.service runs and its last state."},
{"name": "Service log", "form": "journalctl --user -u codebot.service -n 80 --no-pager", "what": "Prints the service's last 80 log lines."},
{"name": "Restart", "form": "systemctl --user restart codebot.service", "what": "Restarts the service once active turns and recordings finish."},
{"name": "Deploy", "form": "sh ops/deploy.sh", "what": "Builds, pushes, waits its turn, restarts the service and verifies it."},
{"name": "Build", "form": "npm run build", "what": "Type-checks and builds a new web release, keeping the served one if the build fails."},
{"name": "Host diagnostics", "form": "/api/diagnostics/host (from an authenticated browser)", "what": "Shows the host's migration, queued turns and recovery hold."},
{"name": "Owner key", "form": "~/.local/share/codebot/owner-key", "what": "Prints the entrance key used to connect a new device; keep it private."},
{"name": "Data", "form": "screen: host > data", "what": "Opens backup, restore, onboarding reset and emergency stop."},
{"name": "Terminal broker", "form": "screen: host > terminal", "what": "Opens the per-user terminal broker, the unit that holds the shell."},
{"name": "Devices", "form": "screen: host > devices", "what": "Opens how a phone or desktop reaches CodeBot over the private address."},
{"name": "Guest", "form": "screen: host > guest", "what": "Opens the second account on this machine for another person."},
{"name": "Family", "form": "screen: host > family", "what": "Opens the family CodeBots on the home Wi-Fi address and their helper."},
{"name": "Address", "form": "screen: host > address", "what": "Opens the steps to move CodeBot to a new Tailscale name."},
{"name": "Account service", "form": "screen: host > account", "what": "Opens the Supabase account service: sign-in, the host handshake and the Gmail relay."}
]},
{"path": ["host", "data"], "sentence": "Backing up, restoring and resetting this host's data.", "rows": [
{"name": "Back up", "form": "ops/OPERATIONS.md (Back up a consistent installation)", "what": "Stops the service and copies its data and settings into a private folder."},
{"name": "Verify a restore", "form": "ops/OPERATIONS.md (Restore into a separate directory first)", "what": "Restores a backup into a new folder and checks it before promotion."},
{"name": "Replay the tour", "form": "ops/OPERATIONS.md (Replay only the first-use tour)", "what": "Starts a person's first-use tour again, on a host with no Bots."},
{"name": "Fresh CodeBot", "form": "ops/OPERATIONS.md (Restart onboarding with a fresh CodeBot)", "what": "Wipes a guest's Bots and conversations and keeps the account."},
{"name": "Full reset", "form": "ops/OPERATIONS.md (Full reset: the person starts as new)", "what": "Deletes a person's account, Bots and data so they start as new."},
{"name": "Emergency stop", "form": "ops/OPERATIONS.md (Emergency stop and rollback)", "what": "Stops the service at once and kills it if a normal stop is not enough."}
]},
{"path": ["host", "guest"], "sentence": "The second account on this machine for another person, using the owner's subscriptions.", "rows": [
{"name": "Install", "form": "sudo ops/guest-install.sh", "what": "Creates the guest user, its service, settings and sudo rules, once."},
{"name": "Update", "form": "ops/guest-update.sh", "what": "Builds the guest's program and restarts its service, with no password."},
{"name": "Invite", "form": "sudo -u codebot-guest /opt/codebot-guest/invite", "what": "Prints a one-use Google invite link, valid for ten minutes."},
{"name": "Status", "form": "systemctl status codebot-guest", "what": "Prints whether the guest service runs."},
{"name": "Remove", "form": "ops/OPERATIONS.md (Host a guest on this machine)", "what": "Removes the guest's service, user, program and sharing."}
]},
{"path": ["host", "family"], "sentence": "The family CodeBots on the home Wi-Fi address, one per Google account, and their helper.", "rows": [
{"name": "Install", "form": "sudo ops/family-install.sh", "what": "Sets up the front door, helper, services, sudo rules and nginx, once."},
{"name": "Update", "form": "ops/family-update.sh", "what": "Builds the family program and restarts every family CodeBot."},
{"name": "Status", "form": "sudo codebot-family status", "what": "Prints whether each family CodeBot runs and whether its Gmail can connect."},
{"name": "Add a person", "form": "sudo codebot-family add N", "what": "Creates family CodeBot N for a new Google account."},
{"name": "Remove a person", "form": "sudo codebot-family remove N", "what": "Deletes family CodeBot N and frees its number."},
{"name": "Stop or start all", "form": "sudo codebot-family stop-all | start-all", "what": "Stops every family CodeBot, or starts them all again."}
]},
{"path": ["host", "address"], "sentence": "The steps to move CodeBot to a new Tailscale name, in order.", "rows": [
{"name": "Places to change", "form": "ops/OPERATIONS.md (Change this machine's address)", "what": "Lists the places that hold the address and why each must change."},
{"name": "Steps", "form": "ops/OPERATIONS.md (Change this machine's address, steps 1 to 7)", "what": "Walks the change in order, from Supabase to the domain forward."},
{"name": "Current name", "form": "tailscale status --json", "what": "Prints this machine's Tailscale name, which becomes the new address."}
]},
{"path": ["host", "devices"], "sentence": "How a phone or desktop reaches CodeBot over the private Tailscale address.", "rows": [
{"name": "Serve status", "form": "tailscale serve status --json", "what": "Prints the current private HTTPS mapping, to check before changing it."},
{"name": "Serve map", "form": "tailscale serve --bg http://127.0.0.1:3505", "what": "Maps the private HTTPS address to the service on a new machine."},
{"name": "Connect a device", "form": "ops/OPERATIONS.md (Connect a device)", "what": "Adds CodeBot to a phone's Home Screen from the private HTTPS address."},
{"name": "Device notifications", "form": "ops/OPERATIONS.md (Background notifications)", "what": "Turns on notifications for one device and sends it a test."}
]},
{"path": ["host", "terminal"], "sentence": "The per-user terminal broker: a separate unit that holds the shell the terminal uses.", "rows": [
{"name": "Enable", "form": "systemctl --user enable --now codebot-terminal-broker.service", "what": "Starts the terminal broker and keeps it running across web-service restarts."},
{"name": "Broker status", "form": "systemctl --user status codebot-terminal-broker.service --no-pager", "what": "Prints whether the broker runs and its listener state."},
{"name": "Lingering", "form": "loginctl show-user \"$USER\" -p Linger", "what": "Prints whether the user service runs without a desktop login."}
]},
{"path": ["host", "account"], "sentence": "The Supabase account service: sign-in, the host handshake and the Gmail relay.", "rows": [
{"name": "Deploy host-access", "form": "npx supabase functions deploy host-access --project-ref wbgrjvqbupgdclaztuou", "what": "Redeploys the host-access function after a contract it parses changes."},
{"name": "Access token", "form": "~/.config/supabase-codebot-token", "what": "Supplies the access token that the deploy command reads."},
{"name": "Gmail relay", "form": "supabase/functions/gmail-relay/index.ts", "what": "Forwards Google's sign-in return to the user's own server."},
{"name": "Migrations", "form": "supabase/migrations/", "what": "Creates the account tables and rules, applied through Supabase."}
]},
{"path": ["scripts"], "sentence": "The npm scripts that run, check, build and review the checkout.", "rows": [
{"name": "dev", "form": "npm run dev", "what": "Starts the service with reload on each change, for development."},
{"name": "start", "form": "npm run start", "what": "Starts the service in production mode."},
{"name": "typecheck", "form": "npm run typecheck", "what": "Type-checks the code without building it."},
{"name": "build", "form": "npm run build", "what": "Type-checks, then builds the web app into a new release."},
{"name": "test", "form": "npm run test", "what": "Runs the Gmail tests against a fake Google server."},
{"name": "check", "form": "npm run check", "what": "Type-checks, then runs the tests."},
{"name": "setup-account", "form": "npm run setup-account", "what": "Runs ops/setup-account.ts, the account setup."},
{"name": "docs:gmail", "form": "npm run docs:gmail", "what": "Regenerates docs/automation/gmail-reference.md."},
{"name": "review:gmail", "form": "npm run review:gmail", "what": "Runs the Gmail review in ops/review/gmail-review.mjs."},
{"name": "review:schedules", "form": "npm run review:schedules", "what": "Runs the schedules review in ops/review/schedules-review.mjs."},
{"name": "playground", "form": "npm run playground", "what": "Starts Vite and opens the Gmail playground to compare design variants."},
{"name": "sync:agents", "form": "npm run sync:agents", "what": "Regenerates AGENTS.md from CLAUDE.md."},
{"name": "build:integration", "form": "npm run build:integration", "what": "Type-checks, then builds the integration bundle with ops/build-integration.mjs."}
]},
{"path": ["docs"], "sentence": "The written docs: how CodeBot is built and run, and what was verified.", "rows": [
{"name": "README", "form": "README.md", "what": "Opens the layout, how to run it and the commands."},
{"name": "Architecture", "form": "ARCHITECTURE.md", "what": "Opens how the pieces are built and what each boundary owns."},
{"name": "Working rules", "form": "CLAUDE.md", "what": "Opens the rules for working with the owner and designing screens."},
{"name": "Runbook", "form": "ops/OPERATIONS.md", "what": "Opens the runbook for installing, running, backing up and recovering."},
{"name": "Open work", "form": "DEFERRED-WORK.md", "what": "Opens the open work and the safe restart state."},
{"name": "Design taste", "form": "docs/design-taste.md", "what": "Opens the owner's rulings on design."},
{"name": "Design method", "form": "docs/design-method.md", "what": "Opens the method for designing and checking screens."},
{"name": "Gmail guide", "form": "docs/automation/gmail.md", "what": "Opens the guide to how Bots use Gmail."},
{"name": "Plans", "form": "docs/plans/", "what": "Opens the dated plans for past and current work."},
{"name": "Verification", "form": "docs/verification/", "what": "Opens the recorded test evidence."}
]}
],
"questions": [
"Split the Bot screen? It has 14 rows. Recommend moving Vision, Screenshots, Feature contract, Git and Gmail widget behind a widgets screen under Bot, since WidgetBrowser already groups them.",
"Should the operator screens (host, scripts) appear in the app, or only in the terminal help? Recommend terminal only; the owner works from a phone.",
"Is there a cli/codebot.py, and do PRODUCT-SPEC.md, IMPLEMENTATION-STATUS.md and MASTER-PLAN.md exist? They are cited in the docs but are not in the dump, so I left them out. If they exist, I will add their rows.",
"Should the owner-key row show only the path, not offer a command that prints the key? Recommend the path only, since the runbook says not to print it."
]}
```

**Scenario (reasoned from the README and `ops/OPERATIONS.md`, not observed):** the owner, usually from a phone, wants to reach their CodeBot. Sometimes they sit at the workstation. They ask things like "where do I restart the host?", "how do I back it up?", "how do I connect a new phone?", and "how do I add a family member?"

**Judgment calls:**
- **Left off the map:** the V2/V3/V4 experiments, which the README says live in separate private repos and are "not part of CodeBot." Also `codebot-preview.service`, which `OPERATIONS.md` says was transient and has been replaced.
- **Not mapped:** the README mentions `cli/codebot.py`, but it is not in the file list, so I could not confirm it exists. The `apps/service/src` internals and the truncated `workspace` components are not user-reached, so I did not map them.
- **Unverified references:** `PRODUCT-SPEC.md`, `IMPLEMENTATION-STATUS.md` and `DEFERRED-WORK.md` are named by the README but are not in the dump. They are kept, marked as unconfirmed.
- **Forms:** the app's real URL routes are unknown, so app rows point at their source folders.
- **Destructive steps** (remove a guest or family member, force-kill, reset onboarding, delete a person) are shown as readable steps, not runnable commands.
- **Splits:** `service` is split into `run` and `dev`, `access` into `device` and `account`, `family` into `guest` and `members`, and `docs` into `records`. The top screen keeps six groups.

```json
{"screens": [
 {"path": [], "sentence": "Everything CodeBot has: the app, the service that runs it, access, backups, family hosts and the docs.", "rows": [
  {"name": "app", "form": "codebot app", "what": "Opens the app's screens: Bots, Contracts, Gmail, Terminal, Widgets, Onboarding, Settings."},
  {"name": "service", "form": "codebot service", "what": "Opens the service's screens: running it, and the commands that build, test and review it."},
  {"name": "access", "form": "codebot access", "what": "Opens the sign-in and device screens, and the account service screen."},
  {"name": "backups", "form": "codebot backups", "what": "Opens the backup and restore steps, and the folder that holds every backup."},
  {"name": "family", "form": "codebot family", "what": "Opens the guest host and the family CodeBots that run on this computer for other people."},
  {"name": "docs", "form": "codebot docs", "what": "Opens the written references: the runbook, the README, the architecture, and the records."}
 ]},
 {"path": ["app"], "sentence": "The app's screens, where you read and steer Bots from a phone, tablet or desktop.", "rows": [
  {"name": "Private address", "form": "https://liel.tail18e69e.ts.net", "what": "Opens the app at its private Tailscale address; on a phone, choose Install app or Add to Home Screen to install it."},
  {"name": "Bots", "form": "apps/web/src/workspace/", "what": "Opens the Bot list, the Bot form and the avatar studio, where each Bot's conversation is read and steered."},
  {"name": "Contracts", "form": "apps/web/src/contracts/", "what": "Opens a Bot's FeatureContract: catalog, files, history, diffs and conflicts."},
  {"name": "Gmail", "form": "apps/web/src/gmail/", "what": "Opens Gmail for Bots: access, approvals, activity, cards and the daily summary."},
  {"name": "Terminal", "form": "apps/web/src/TerminalPage.tsx", "what": "Opens the terminal tabs on this computer, when the terminal is turned on."},
  {"name": "Widgets", "form": "apps/web/src/widgets/", "what": "Opens the widgets a Bot shows, arranged by the owner."},
  {"name": "Onboarding", "form": "apps/web/src/onboarding/", "what": "Opens the first-use steps: device arrival, connection, family setup and the first Bot."},
  {"name": "Settings", "form": "apps/web/src/ui/Settings.tsx", "what": "Opens Settings, which each widget's cog button leads to."},
  {"name": "Update notice", "form": "apps/web/src/pwa/UpdateNotice.tsx", "what": "Shows what changed since the last update, from apps/web/src/whatsNew.ts."},
  {"name": "Design playground", "form": "npm run playground", "what": "Starts the playground that compares Gmail design variants on the dev server."}
 ]},
 {"path": ["service"], "sentence": "The service on this computer, and the commands that run, build and test it.", "rows": [
  {"name": "run", "form": "codebot service run", "what": "Opens the running screens: start and stop, status and logs, settings, data and deploy."},
  {"name": "dev", "form": "codebot service dev", "what": "Opens the commands that build, typecheck, test and review the code."},
  {"name": "Loopback address", "form": "http://127.0.0.1:3505", "what": "Opens the service on this computer only, on port 3505."}
 ]},
 {"path": ["service", "run"], "sentence": "The service's running state, its private settings and its data.", "rows": [
  {"name": "Start", "form": "systemctl --user start codebot.service", "what": "Starts the service on 127.0.0.1:3505."},
  {"name": "Stop", "form": "systemctl --user stop codebot.service", "what": "Stops the service, interrupting Bot turns and finalizing recordings."},
  {"name": "Restart", "form": "systemctl --user restart codebot.service", "what": "Restarts the service after active turns and recordings finish; run it after an update."},
  {"name": "Status", "form": "systemctl --user status codebot.service --no-pager", "what": "Prints whether the service is running and its recent state."},
  {"name": "Logs", "form": "journalctl --user -u codebot.service -n 80 --no-pager", "what": "Prints the last 80 lines of the service's log."},
  {"name": "Health check", "form": "curl --fail http://127.0.0.1:3505/api/session", "what": "Prints the session answer; an unsigned answer still proves the service is ready."},
  {"name": "Terminal broker", "form": "systemctl --user start codebot-terminal-broker.service", "what": "Starts the per-user terminal broker, a separate unit the terminal needs."},
  {"name": "Deploy", "form": "sh ops/deploy.sh", "what": "Builds, commits, pushes, waits for active work, restarts and verifies the service."},
  {"name": "Emergency stop", "form": "systemctl --user kill --kill-whom=all --signal=SIGKILL codebot.service", "what": "Kills every service process at once, losing unsaved media; use only when a normal stop fails (ops/OPERATIONS.md)."},
  {"name": "Settings file", "form": "~/.config/codebot/service.env", "what": "Opens the private settings: port, data folder, project roots, provider credentials. Mode 0600; never print it."},
  {"name": "Data folder", "form": "~/.local/share/codebot", "what": "Opens the data folder: the database, transcripts, artifacts and recordings."},
  {"name": "Project folders", "form": "CODEBOT_PROJECT_ROOTS (/home/liel/projects)", "what": "Opens the project folders Bots may reach; widening them grants real file access."}
 ]},
 {"path": ["service", "dev"], "sentence": "The commands that build, typecheck, test and review CodeBot's code.", "rows": [
  {"name": "Dev service", "form": "npm run dev", "what": "Starts the service in watch mode from the source, for development."},
  {"name": "Build", "form": "npm run build", "what": "Typechecks, then builds the app into a new release under dist/releases."},
  {"name": "Build integration", "form": "npm run build:integration", "what": "Builds the copy that the QA instance on port 3506 runs."},
  {"name": "Typecheck", "form": "npm run typecheck", "what": "Checks the code compiles and prints any type errors."},
  {"name": "Test", "form": "npm test", "what": "Runs the Gmail automation tests against a fake Google server."},
  {"name": "Check", "form": "npm run check", "what": "Typechecks, then runs the tests."},
  {"name": "Gmail review", "form": "npm run review:gmail", "what": "Runs ops/review/gmail-review.mjs against the real service and browser."},
  {"name": "Schedules review", "form": "npm run review:schedules", "what": "Runs ops/review/schedules-review.mjs."},
  {"name": "Sync agents", "form": "npm run sync:agents", "what": "Regenerates AGENTS.md from CLAUDE.md; edit CLAUDE.md, not AGENTS.md."},
  {"name": "Gmail reference", "form": "npm run docs:gmail", "what": "Regenerates docs/automation/gmail-reference.md."}
 ]},
 {"path": ["access"], "sentence": "How people sign in to this computer's CodeBot, and the account service behind sign-in.", "rows": [
  {"name": "device", "form": "codebot access device", "what": "Opens the device screen: connecting a phone, tablet or desktop."},
  {"name": "account", "form": "codebot access account", "what": "Opens the account screen: the central sign-in service and each person's onboarding."}
 ]},
 {"path": ["access", "device"], "sentence": "The devices that reach this computer's CodeBot, and how each one is connected.", "rows": [
  {"name": "Sign-in entry", "form": "https://liel.tail18e69e.ts.net/onboarding", "what": "Opens the owner's sign-in entry, where a person signs in and is sent to their own host."},
  {"name": "Entrance key", "form": "~/.local/share/codebot/owner-key", "what": "Opens the file holding the key a new device signs in with; read it only at this computer and never paste it."},
  {"name": "Serve mapping", "form": "tailscale serve status --json", "what": "Prints the private HTTPS mapping that exposes the service; the root handler should be 127.0.0.1:3505 on port 443."},
  {"name": "Map a new machine", "form": "tailscale serve --bg http://127.0.0.1:3505", "what": "Maps the service to private HTTPS on a machine with no root mapping; never reset an existing mapping."},
  {"name": "Device notifications", "form": "apps/web/src/pwa/DeviceNotifications.tsx", "what": "Opens the notification setup for this device: enable, reconnect, other devices and send test."}
 ]},
 {"path": ["access", "account"], "sentence": "The central account service, the sign-in records behind it, and the steps when an address or onboarding changes.", "rows": [
  {"name": "Account service", "form": "https://supabase.com/dashboard/project/wbgrjvqbupgdclaztuou", "what": "Opens the central account service's dashboard, in the mobile-coder login rather than the Lebnor login."},
  {"name": "Account token", "form": "~/.config/supabase-codebot-token", "what": "Opens the token file used for CLI deploys (mode 600); read it, never print it."},
  {"name": "Account setup", "form": "npm run setup-account", "what": "Runs ops/setup-account.ts to set up the account service."},
  {"name": "Deploy host-access", "form": "npx supabase functions deploy host-access --project-ref wbgrjvqbupgdclaztuou", "what": "Deploys the host-access function; run it again whenever a contract it parses changes."},
  {"name": "Gmail relay", "form": "supabase/functions/gmail-relay/index.ts", "what": "Forwards Google sign-in back to the person's own server."},
  {"name": "Account record", "form": "public.codebot_account_progress (Supabase)", "what": "Opens the onboarding record for each account: draft, first Bot and server address."},
  {"name": "Change address", "form": "ops/OPERATIONS.md, 'Change this machine's address'", "what": "Reads the seven steps and the nine places that hold this machine's address."},
  {"name": "Reset onboarding", "form": "ops/OPERATIONS.md, 'Reset someone's onboarding'", "what": "Reads how to replay the first-use tour or restart onboarding for a person; these steps delete data."}
 ]},
 {"path": ["backups"], "sentence": "Whole-data backups of this computer's CodeBot, and how to restore one into a separate folder first.", "rows": [
  {"name": "Back up", "form": "ops/OPERATIONS.md, 'Back up a consistent installation'", "what": "Stops the service, copies its whole data folder, service.env and unit to a new backup folder, then restarts it."},
  {"name": "Backup folder", "form": "~/.local/share/codebot-backups/", "what": "Opens the folder holding every backup, each with state.tar, source.tar, service.env and SHA256SUMS."},
  {"name": "Verify backup", "form": "sha256sum -c SHA256SUMS (inside a backup folder)", "what": "Checks a backup's files against their checksums before any restore."},
  {"name": "Restore", "form": "ops/OPERATIONS.md, 'Restore into a separate directory first'", "what": "Extracts a backup into an empty staging folder, never over the running copy, and gives the steps to promote it."},
  {"name": "Check restored database", "form": "ops/OPERATIONS.md (PRAGMA integrity_check script)", "what": "Checks the restored database's integrity and references, read-only."},
  {"name": "Inspect restored copy", "form": "http://127.0.0.1:3508", "what": "Opens the restored copy on port 3508 with recovery hold on, so nothing runs automatically."}
 ]},
 {"path": ["family"], "sentence": "Guest and family CodeBots that run on this computer for other people, each under its own Linux user.", "rows": [
  {"name": "guest", "form": "codebot family guest", "what": "Opens the guest host: one person, its own Linux user, port 10000."},
  {"name": "members", "form": "codebot family members", "what": "Opens the family front door and the family CodeBots, up to six, on the home Wi-Fi address."}
 ]},
 {"path": ["family", "guest"], "sentence": "The guest host on this computer: its install, update, invite and status.", "rows": [
  {"name": "Install guest", "form": "sudo ops/guest-install.sh", "what": "Sets up the guest user, service, settings, sudo rules and Tailscale on port 10000; run once."},
  {"name": "Update guest", "form": "ops/guest-update.sh", "what": "Builds, replaces /opt/codebot-guest and restarts the guest host; needs no password."},
  {"name": "Invite", "form": "sudo -u codebot-guest /opt/codebot-guest/invite", "what": "Prints a one-use Google invite link, valid for ten minutes."},
  {"name": "Status", "form": "systemctl status codebot-guest", "what": "Prints whether the guest host is running."},
  {"name": "Logs", "form": "journalctl -u codebot-guest", "what": "Prints the guest host's log."},
  {"name": "Guest home", "form": "/home/codebot-guest", "what": "Opens the guest's home folder, where its data and projects are kept."},
  {"name": "Remove guest", "form": "ops/OPERATIONS.md, 'Host a guest on this machine'", "what": "Reads the steps that remove the guest host; they delete its user and data, so they stay as steps, not a command."}
 ]},
 {"path": ["family", "members"], "sentence": "The family front door and the family CodeBots on the home Wi-Fi address, one per Google account.", "rows": [
  {"name": "Family address", "form": "https://family.codebot.lielbenor.com", "what": "Opens the front door on the home Wi-Fi address, where a family member signs in with Google."},
  {"name": "Install family", "form": "sudo ops/family-install.sh", "what": "Sets up the front door user, the helper, services, sudo rules and nginx; run once."},
  {"name": "Update family", "form": "ops/family-update.sh", "what": "Builds, replaces /opt/codebot-family and restarts every family CodeBot; needs no password."},
  {"name": "Status", "form": "sudo codebot-family status", "what": "Prints each family CodeBot: whether it runs, and whether Gmail can connect."},
  {"name": "Add member", "form": "sudo codebot-family add N", "what": "Adds family CodeBot N for a new Google account; the front door runs this itself on a new sign-in."},
  {"name": "Remove member", "form": "sudo codebot-family remove N", "what": "Deletes family CodeBot N and frees its number; the same Google account cannot be linked again without editing the account database."},
  {"name": "Stop all", "form": "sudo codebot-family stop-all", "what": "Stops every family CodeBot."},
  {"name": "Start all", "form": "sudo codebot-family start-all", "what": "Starts every family CodeBot."},
  {"name": "Family logs", "form": "journalctl -u codebot-family-lobby -u 'codebot-family@*'", "what": "Prints the front door's and the family CodeBots' logs."},
  {"name": "Family settings", "form": "/etc/codebot-family.conf", "what": "Opens the settings every family CodeBot receives, including the Google app secret; keep it private."}
 ]},
 {"path": ["docs"], "sentence": "The written references: how to run CodeBot, what it is, and what is still open.", "rows": [
  {"name": "Runbook", "form": "ops/OPERATIONS.md", "what": "Opens the runbook: running, connecting, backing up, restoring, resetting and recovering CodeBot."},
  {"name": "Bot model selection", "form": "ops/OPERATIONS.md, 'Bot model selection'", "what": "Reads which model a Bot uses for ordinary messages and for /goal."},
  {"name": "README", "form": "README.md", "what": "Opens the overview: what CodeBot is, how its pieces fit and which checks it runs."},
  {"name": "Architecture", "form": "ARCHITECTURE.md", "what": "Opens the technical boundaries, invariants and persistence design."},
  {"name": "Product spec", "form": "PRODUCT-SPEC.md (named by the README; not in the file list)", "what": "Opens the behavior contract."},
  {"name": "Status and open work", "form": "IMPLEMENTATION-STATUS.md and DEFERRED-WORK.md (named by the README; not in the file list)", "what": "Opens what was built and the remaining checklist."},
  {"name": "Agent rules", "form": "CLAUDE.md", "what": "Opens the rules every agent follows; AGENTS.md is generated from it."},
  {"name": "Gmail guide", "form": "docs/automation/gmail.md", "what": "Opens the supervisor guide for Gmail automation."},
  {"name": "Design", "form": "docs/design-method.md and docs/design-taste.md", "what": "Opens the design method and the owner's design rulings."},
  {"name": "Objectives", "form": "docs/objectives/", "what": "Lists the objectives: chat current session, Gmail widget, schedules and terminal tabs."},
  {"name": "Records", "form": "codebot docs records", "what": "Opens the plans, verification evidence, task reports, intents and QA records."}
 ]},
 {"path": ["docs", "records"], "sentence": "The records of past work: plans, verification evidence, task reports, intents, feature tests and QA findings.", "rows": [
  {"name": "Plans", "form": "docs/plans/ and .plans/", "what": "Lists the plan documents for past and planned work."},
  {"name": "Verification", "form": "docs/verification/", "what": "Opens the recorded verification evidence, including the onboarding proof."},
  {"name": "Tasks", "form": "docs/tasks/ and docs/superpowers/plans/", "what": "Lists the task reports and dated work plans."},
  {"name": "Intents", "form": ".idd/modules/", "what": "Lists each module's INTENT.md: its constraints and its Given / When / Then table."},
  {"name": "Feature tests", "form": ".bdd/features/ and .bdd/steps/", "what": "Lists the feature files and the step files that run them."},
  {"name": "QA findings", "form": ".bdd/qa/findings/ and .bdd/qa/resolutions/", "what": "Lists the QA findings and how each one was resolved."},
  {"name": "Design critiques", "form": ".impeccable/critique/", "what": "Lists the design critiques of app screens."}
 ]}
],
"questions": [
 "Facade name: should the command be `codebot` (so `codebot help` is the map)? Recommendation: yes, with no short alias yet; add `cb` only after `whence -a cb` shows no clash.",
 "Top group name: 'service' or 'host'? The docs use both. Recommendation: 'service', because the unit is codebot.service and the README calls it the local service.",
 "Destructive or sudo steps (remove guest, remove member, emergency stop, reset onboarding, delete a person): should the CLI run them, or only print the steps? Recommendation: only print the steps, so nothing irreversible runs from a single typed command.",
 "Should the app screens (Bots, Contracts, Gmail, Terminal and so on) appear in the CLI, or should the CLI only open the private address? Recommendation: list them, with source folders as forms; the CLI does not drive the UI.",
 "Should the family and guest hosting stay on the owner's CLI, or be operator-only docs? Recommendation: keep them under 'family', with destructive steps as read-only steps.",
 "Three referenced files (PRODUCT-SPEC.md, IMPLEMENTATION-STATUS.md, DEFERRED-WORK.md) and cli/codebot.py are not in the file list. Do they exist in the repo? Recommendation: confirm before the CLI links to them."
]}
```

I planned the map from the dump. Most screens come from file names in `apps/web/src` and the docs, so the forms are inferred rather than checked against the router. The dump also cuts off partway through `OPERATIONS.md` and `ARCHITECTURE.md`, so anything after those cuts is missing. The owner's screens sit at the top level. Operator, developer and experimental commands sit under their own nouns. Features that don't exist yet are left out and raised as questions.

```json
{"screens": [
{"path": [], "sentence": "Your Bots, each with its current state and whether it needs you, plus the entry points to everything else.", "rows": [
{"name": "Open a Bot", "form": "the Bot screen, chosen from the list", "what": "Reach one Bot's conversation and tools."},
{"name": "Create a Bot", "form": "new-bot screen", "what": "Start a new Bot with a name, role, provider and folder."},
{"name": "Gmail", "form": "gmail screen", "what": "See Gmail activity, approvals and access for your Bots."},
{"name": "Avatar", "form": "avatar screen", "what": "Pick or design a Bot's avatar."},
{"name": "Terminal", "form": "terminal screen", "what": "Shells and Claude sessions on this computer."},
{"name": "Settings", "form": "settings screen (cog, top right)", "what": "This device's theme, notifications, computer and install."},
{"name": "What's new", "form": "whats-new screen", "what": "Read the changes since your last update."},
{"name": "Onboarding", "form": "onboarding screen (/onboarding)", "what": "First-time setup until the first Bot exists."},
{"name": "Experiments", "form": "experiments screen", "what": "Local experimental apps on ports 3512 to 3514."},
{"name": "Operations", "form": "ops screen", "what": "Operator tasks for the computer's CodeBot."},
{"name": "Development", "form": "dev screen", "what": "Project commands for building, testing and reviewing."}
]},
{"path": ["bot"], "sentence": "One Bot's conversation: what it is doing now, the messages waiting for it, and what it needs from you.", "rows": [
{"name": "Send a message", "form": "composer at the bottom of the Bot screen", "what": "Send, queue behind a running reply, or send now. Attach files here too."},
{"name": "Queued messages", "form": "queue bar above the composer", "what": "See, edit, take back or send now the messages waiting for the Bot."},
{"name": "Stop", "form": "Stop button beside the composer (Esc)", "what": "Interrupt the current turn; the queue is kept."},
{"name": "Transcript", "form": "the conversation itself, divided by chat markers", "what": "Read every message as it was sent."},
{"name": "Chats", "form": "bot/chats screen", "what": "Browse this Bot's topics."},
{"name": "Questions and approvals", "form": "bot/questions screen", "what": "Answer what the Bot asked and approve or deny its requests."},
{"name": "Files", "form": "bot/files screen", "what": "Pinned files, resources and attachments."},
{"name": "Browser and screenshots", "form": "bot/vision screen", "what": "Watch or take over the Bot's browser."},
{"name": "Contract", "form": "bot/contract screen", "what": "The Bot's feature contract."},
{"name": "Git", "form": "bot/git screen", "what": "Repository status and quick git actions."},
{"name": "Schedules", "form": "bot/schedules screen", "what": "Timed wakeups for this Bot."},
{"name": "Widgets", "form": "bot/widgets screen", "what": "Choose and arrange the widgets on this Bot's screen."},
{"name": "Bot settings", "form": "bot/settings screen (cog)", "what": "Identity, provider, folder, notifications and skills."}
]},
{"path": ["bot", "chats"], "sentence": "The topics this Bot has had, each with its label and kind of work, newest first.", "rows": [
{"name": "Open a chat", "form": "chat divider in the transcript", "what": "Read one topic's turns; the original messages stay unchanged."},
{"name": "Earlier work", "form": "chats/ folder in the Bot's home", "what": "The saved transcript the Bot reads when you refer to earlier work."}
]},
{"path": ["bot", "questions"], "sentence": "Questions the Bot is waiting on, and requests that need a yes or no.", "rows": [
{"name": "Answer a question", "form": "question card", "what": "Reply so the Bot can continue."},
{"name": "Approve or deny a file link", "form": "approval card (ApproveFileLink)", "what": "Let the Bot share or open a file, or refuse."}
]},
{"path": ["bot", "files"], "sentence": "Files this Bot has pinned, produced or been given.", "rows": [
{"name": "Pinned files", "form": "pinned files panel", "what": "Keep the files you return to."},
{"name": "Open a resource", "form": "resource viewer", "what": "Preview a file, image, markdown or recording."},
{"name": "Attach a file", "form": "attachment picker (+ on the composer)", "what": "Give the Bot a file in your next message."}
]},
{"path": ["bot", "vision"], "sentence": "The Bot's browser: what the page shows now, past recordings and the screenshot gallery.", "rows": [
{"name": "Live browser", "form": "vision view", "what": "Watch the Bot's Chromium page."},
{"name": "Take control", "form": "control handoff button", "what": "Pause the Bot's automation and drive the browser yourself."},
{"name": "Recordings", "form": "recording player", "what": "Replay a finished recording."},
{"name": "Screenshots", "form": "screenshot gallery", "what": "Browse the Bot's captured screenshots in order."}
]},
{"path": ["bot", "contract"], "sentence": "The Bot's feature contract: the items it covers, their files, and how they have changed.", "rows": [
{"name": "Catalog", "form": "contract catalog view", "what": "The contract's items and their status."},
{"name": "Files", "form": "contract files view", "what": "Files the contract covers."},
{"name": "History", "form": "contract history view (opens diffs)", "what": "Each revision, and what changed in it."},
{"name": "Conflicts", "form": "contract conflict view", "what": "Places where the contract disagrees and needs a decision."},
{"name": "Relationships", "form": "component relationships view", "what": "How the contract's components depend on each other."}
]},
{"path": ["bot", "git"], "sentence": "The repository this Bot works in: its status and the actions you can take on it.", "rows": [
{"name": "Repository status", "form": "git status panel", "what": "Current branch, changes and revision."},
{"name": "Quick actions", "form": "git quick-action buttons", "what": "Typed git actions; each shows its outcome."}
]},
{"path": ["bot", "schedules"], "sentence": "Timed wakeups that start this Bot's work without a message from you.", "rows": [
{"name": "Add or change a wakeup", "form": "schedule editor", "what": "Set when the Bot wakes and what it should do."},
{"name": "Pause a wakeup", "form": "schedule row controls", "what": "Stop a wakeup from firing."}
]},
{"path": ["bot", "widgets"], "sentence": "The widgets on this Bot's screen and the ones you can add.", "rows": [
{"name": "Widget browser", "form": "widget browser", "what": "Add a widget to this Bot's screen."},
{"name": "Arrange", "form": "widget arrangement", "what": "Change the order of the widgets."}
]},
{"path": ["bot", "settings"], "sentence": "This Bot's identity and behaviour, and how this device gets its notifications.", "rows": [
{"name": "Name and role", "form": "form field on Bot settings", "what": "Rename the Bot or change its role."},
{"name": "Provider and model", "form": "form field on Bot settings", "what": "Claude, Codex or OpenCode; an empty model uses the automatic policy."},
{"name": "Primary folder", "form": "form field on Bot settings", "what": "The folder the Bot works in; must sit inside an allowed project root."},
{"name": "Avatar", "form": "avatar screen", "what": "Change the Bot's picture."},
{"name": "Automatic actions and skills", "form": "policy options and skills fields", "what": "What the Bot may do without asking, and which skills it has."},
{"name": "Notifications for this Bot", "form": "switch on Bot settings", "what": "Send replies, approval requests and failures to your devices."},
{"name": "Enable this device", "form": "browser notification prompt", "what": "Turn on alerts on this device."},
{"name": "Reconnect this device", "form": "button on Bot settings", "what": "Repair an expired or rejected notification subscription."},
{"name": "Other devices", "form": "device list", "what": "Remove old devices; up to 16 are kept."},
{"name": "Send test", "form": "button on Bot settings", "what": "Check the selected device; a sent test does not prove it displayed."}
]},
{"path": ["new-bot"], "sentence": "Create a new Bot.", "rows": [
{"name": "Name, role, provider, folder", "form": "form on new-bot", "what": "Set up the Bot before its first message."},
{"name": "Create", "form": "button; opens the Bot screen", "what": "Make the Bot and go to it."}
]},
{"path": ["gmail"], "sentence": "Gmail for your Bots: whether it is connected, what Bots did lately, and what waits for a decision.", "rows": [
{"name": "Connect Gmail", "form": "Google sign-in via the account service's gmail-relay", "what": "Link a Google account. Self-hosted needs its own Google client ID and secret."},
{"name": "Approvals", "form": "gmail/approvals screen", "what": "Gmail actions waiting for your yes or no."},
{"name": "Activity", "form": "gmail/activity screen", "what": "What Bots did in Gmail, as cards, with the daily summary."},
{"name": "Access", "form": "gmail/access screen", "what": "Which Bots may read or send, and disconnecting."}
]},
{"path": ["gmail", "approvals"], "sentence": "Gmail actions a Bot has asked to take, waiting for your decision.", "rows": [
{"name": "Approve", "form": "approval card button", "what": "Let the action go ahead."},
{"name": "Deny", "form": "approval card button", "what": "Stop the action."}
]},
{"path": ["gmail", "activity"], "sentence": "What Bots have done in Gmail, newest first, and the daily summary.", "rows": [
{"name": "Open a card", "form": "Gmail card", "what": "See one message or action in detail."},
{"name": "Daily summary", "form": "daily summary panel", "what": "Today's Gmail work in one view."}
]},
{"path": ["gmail", "access"], "sentence": "Which Bots may use Gmail, and the connected Google account.", "rows": [
{"name": "Bot access", "form": "access toggle per Bot", "what": "Allow or stop a Bot reading or sending mail."},
{"name": "Disconnect Gmail", "form": "button, asks to confirm", "what": "Remove the link to the Google account; linking again needs sign-in."}
]},
{"path": ["avatar"], "sentence": "Pick or design a Bot's avatar.", "rows": [
{"name": "Pick an avatar", "form": "avatar picker", "what": "Choose a ready-made avatar."},
{"name": "Design with parts", "form": "avatar studio", "what": "Build a face from body, eyes, accessories and colours."}
]},
{"path": ["settings"], "sentence": "This device's settings and the computer it connects to.", "rows": [
{"name": "Theme", "form": "theme control", "what": "Light or dark."},
{"name": "Notifications on this device", "form": "settings/notifications screen", "what": "Enable, reconnect and test alerts for this device."},
{"name": "Account", "form": "central sign-in at /onboarding", "what": "Sign in through the central account service; it returns you to this computer."},
{"name": "This computer", "form": "read-only panel (address and server ID from /api/onboarding/identity)", "what": "Which computer this app is served by."},
{"name": "Diagnostics", "form": "settings/diagnostics screen", "what": "Host, scheduler, vision and notification counters."},
{"name": "Terminal access", "form": "status line in this panel", "what": "Whether the terminal is turned on for this computer."},
{"name": "Install the app", "form": "browser Install app / Add to Home Screen command", "what": "Install CodeBot on a phone or desktop."}
]},
{"path": ["settings", "notifications"], "sentence": "Alerts for this device, and the devices that receive them.", "rows": [
{"name": "Enable this device", "form": "browser notification prompt", "what": "Allow alerts here."},
{"name": "Reconnect this device", "form": "button", "what": "Repair an expired subscription."},
{"name": "Other devices", "form": "device list", "what": "Remove old devices."},
{"name": "Send test", "form": "button", "what": "Check this device; a sent test is not proof it showed the alert."},
{"name": "Notification queue", "form": "/api/notifications/diagnostics", "what": "Pending alerts and the send timer, for diagnosis."}
]},
{"path": ["settings", "diagnostics"], "sentence": "Counters and state for the host, the scheduler, vision and notifications. No provider credentials appear here.", "rows": [
{"name": "Host", "form": "/api/diagnostics/host", "what": "Migration, queued and running turns, recovery hold."},
{"name": "Scheduler", "form": "/api/diagnostics/scheduler", "what": "Timers and wakeup state."},
{"name": "Vision", "form": "/api/diagnostics/vision", "what": "Browser capture state."},
{"name": "Session", "form": "/api/session", "what": "Whether the app is signed in to this computer."}
]},
{"path": ["whats-new"], "sentence": "What changed in CodeBot, in plain words, with where to find it.", "rows": [
{"name": "Latest changes", "form": "entries from apps/web/src/whatsNew.ts", "what": "Shown once after each update."}
]},
{"path": ["onboarding"], "sentence": "First-time setup: connect this device, meet your Bots and create the first one.", "rows": [
{"name": "Connect a device", "form": "DeviceConnection screen", "what": "Sign this device in to the computer."},
{"name": "Meet your Bots", "form": "FirstBotIntroduction screen", "what": "Learn what a Bot is for."},
{"name": "Create your first Bot", "form": "FirstBotCreation screen", "what": "Make the first Bot."}
]},
{"path": ["terminal"], "sentence": "Shell and Claude Code sessions on this computer, one per tab.", "rows": [
{"name": "New tab", "form": "terminal new-tab control", "what": "Open a shell in an allowed project folder."},
{"name": "Tab", "form": "terminal tab", "what": "Attach to a session that keeps running if the web service restarts."},
{"name": "Claude sessions", "form": "Claude session list", "what": "Find background Claude Code sessions to attach to."}
]},
{"path": ["experiments"], "sentence": "Experimental apps that run next to CodeBot on this computer. Each has its own folder, port and data; they are not part of CodeBot.", "rows": [
{"name": "V2 Terminal chat", "form": "http://127.0.0.1:3512 (run from ~/projects/codebot-v2-terminal-chat)", "what": "CodeBot's look; a Bot's chat is the Claude Code terminal."},
{"name": "V3 Claude Code mod", "form": "http://127.0.0.1:3513 (run from ~/projects/codebot-v3-claude-mod)", "what": "Claude Code first; a mod draws the Bot list above the prompt."},
{"name": "V4 Launcher menu", "form": "http://127.0.0.1:3514 (run from ~/projects/codebot-v4-launcher-menu)", "what": "A main menu whose buttons set up Claude Code sessions."}
]},
{"path": ["ops"], "sentence": "Operator work on the computer that runs CodeBot. It is not part of the owner's path.", "rows": [
{"name": "Deploy an update", "form": "sh ops/deploy.sh", "what": "Build, push and restart; refuses while a Bot is working."},
{"name": "Build", "form": "npm run build", "what": "Typecheck and publish a new release."},
{"name": "Restart the host", "form": "systemctl --user restart codebot.service", "what": "Restart after active turns finish, then check /api/session."},
{"name": "Stop the host", "form": "systemctl --user stop codebot.service", "what": "Normal stop; interrupts Bot turns and stops scheduling."},
{"name": "Status and logs", "form": "systemctl --user status codebot.service; journalctl --user -u codebot.service -n 80", "what": "Find out why the host is down."},
{"name": "Terminal broker", "form": "systemctl --user enable --now codebot-terminal-broker.service", "what": "Turn on terminal access for this computer."},
{"name": "Backup and restore", "form": "ops/backup screen", "what": "Stop, copy and verify the whole data folder."},
{"name": "Hosted people", "form": "ops/hosting screen", "what": "The guest and family CodeBots on this machine."},
{"name": "Change the address", "form": "ops/address screen", "what": "Move sign-in when the computer's Tailscale name changes."},
{"name": "Reset onboarding", "form": "ops/reset-onboarding screen", "what": "Show someone the first-use setup again."},
{"name": "Account service", "form": "Supabase project wbgrjvqbupgdclaztuou", "what": "Central sign-in data and functions."}
]},
{"path": ["ops", "backup"], "sentence": "Take a consistent copy of the data folder, or restore one into a separate folder first.", "rows": [
{"name": "Back up", "form": "stop the service, tar ~/.local/share/codebot, verify SHA256SUMS, start", "what": "A copy that includes owner sessions and keys; keep it private."},
{"name": "Restore into staging", "form": "extract into an empty private folder; run on port 3508 with CODEBOT_RECOVERY_HOLD=1", "what": "Check the copy before it replaces anything."},
{"name": "Promote a restore", "form": "point CODEBOT_DATA_DIR at the verified copy in service.env", "what": "Make the restored copy live; keep the old data as rollback."}
]},
{"path": ["ops", "hosting"], "sentence": "Other people's CodeBots on this machine: the guest account and the family CodeBots.", "rows": [
{"name": "Guest host", "form": "sudo ops/guest-install.sh; ops/guest-update.sh; sudo -u codebot-guest /opt/codebot-guest/invite", "what": "A second account for one person, with its own Google sign-in."},
{"name": "Family CodeBots", "form": "sudo ops/family-install.sh; ops/family-update.sh; sudo codebot-family add N", "what": "One CodeBot per family member, up to six, behind the family address."},
{"name": "Status", "form": "systemctl status codebot-guest; systemctl status 'codebot-family@*'", "what": "Check whether each is running."}
]},
{"path": ["ops", "address"], "sentence": "The places that must change when this computer's Tailscale name changes.", "rows": [
{"name": "Full list", "form": "OPERATIONS.md, section Change this machine's address", "what": "Nine places, from the domain forward to the installed phone apps."},
{"name": "Check", "form": "sign in as each account", "what": "Confirm each account lands on its own host."}
]},
{"path": ["ops", "reset-onboarding"], "sentence": "Show a person the first-use setup again: replay only the tour, or start with a fresh CodeBot.", "rows": [
{"name": "Replay the tour", "form": "Supabase statement and a first_use_receipts delete", "what": "Only works when the host has no Bots."},
{"name": "Fresh CodeBot, same account", "form": "wipe data except server-id, server-signing-key and owner-key; then the Supabase statement", "what": "Their Bots and conversations go; their Google account and folders stay."},
{"name": "Full reset", "form": "delete the data folder and the auth user, then re-invite", "what": "Destroys the account, its Bots, conversations and attachments."}
]},
{"path": ["dev"], "sentence": "Project commands for development and checking.", "rows": [
{"name": "Run the service", "form": "npm run dev", "what": "Start the local service with reload."},
{"name": "Typecheck and test", "form": "npm run check", "what": "Typecheck and run the service tests."},
{"name": "Gmail reference", "form": "npm run docs:gmail", "what": "Regenerate the Gmail reference."},
{"name": "Gmail review", "form": "npm run review:gmail", "what": "Check the Gmail flow in the real app."},
{"name": "Schedule review", "form": "npm run review:schedules", "what": "Check schedules in the real app."},
{"name": "Playground", "form": "npm run playground", "what": "Compare screen variants in apps/web/playground."},
{"name": "Host account setup", "form": "npm run setup-account", "what": "Set up the host's account binding."}
]}
],
"questions": [
"Should operator and developer commands (ops, dev, experiments) share one help tree with the owner's screens, or be a separate command set? Recommendation: a separate set, because CLAUDE.md keeps operator work out of the owner's path.",
"Is there a command-line tool? The README line about cli/codebot.py is garbled, and no cli/ folder is in the file list. Recommendation: confirm before writing help for a codebot command. Until then, the ops and dev rows show only npm and systemctl commands.",
"Should the map include a delete-Bot row? OPERATIONS.md says CodeBot has no delete-Bot feature. Recommendation: leave it out until the feature exists.",
"Bot config export and import have plans in docs/plans but appear nowhere in the map. Recommendation: add them to Bot settings only when they ship.",
"Should Terminal stay in the owner's tree while the terminal broker is off? Recommendation: keep it, with a status line that says it is disabled, so the owner knows why it is empty.",
"Are the forms for app screens (for example gmail/approvals, bot/vision) real URLs or in-app views? The dump lists component files, not routes. Recommendation: confirm the router before the forms are final.",
"Should Connect Gmail appear for cloud users, given that cloud can offer Gmail only to a small early group? Recommendation: show it with a status line that says who it is available to.",
"Are the guest and family flows for the owner or for family members? Recommendation: keep hosting under ops only; family members see their own app, not this map."
]}
```