agent-office-studio 0.0.0-stage → 0.2.0

package/docs/guides/troubleshooting.md

@@ -0,0 +1,99 @@
+# Troubleshooting
+
+Find the message you're seeing, or the symptom.
+
+## The office won't start
+
+**`Error: listen EADDRINUSE: address already in use 127.0.0.1:4317`**
+Something is already on that port — usually another office. Find it with
+`lsof -i :4317`, or start this one elsewhere: `PORT=4400 npm start`.
+
+**The page says "No build yet."**
+The server is running but `dist/` is empty. Run `npm run build`, or use
+`npm start`, which builds first.
+
+**The page loads but the office is blank.**
+Open the browser console. The office needs WebGL; if it's disabled (some
+remote desktops and VMs), the 3D view can't draw.
+
+## Jobs don't run
+
+**A job fails with "Could not start claude: spawn claude ENOENT".**
+Claude Code isn't on the `PATH` the office was started with. Check
+`which claude` in the same terminal. If it lives somewhere unusual, point the
+office at it: `CLAUDE_BIN=/path/to/claude npm start`.
+
+**Jobs fail straight away with an authentication error.**
+On the **Claude Code login**: run `claude` in a terminal and sign in, then
+retry. On an **API key**: open the key button beside Appearance and check
+which key is in use; paste a new one if it was revoked.
+
+**"That project folder is gone."**
+The project was moved or renamed after the job was created. Projects are the
+folders directly inside `OFFICE_ROOT`; see
+[Getting started](../getting-started.md#where-your-projects-are).
+
+**A project doesn't show up.**
+It must be a folder directly inside `OFFICE_ROOT` — not nested deeper. The
+server prints `OFFICE_ROOT` when it starts: *"projects in …"*.
+
+**A job keeps getting blocked.**
+Its clearance doesn't allow what it's trying to do — *Edit files* refuses
+shell commands. Grant more from the job's drawer, or give the next job
+*Full autonomy* if it needs to run tests or builds.
+
+**No "What changed" card.**
+The project isn't a git repository. Run `git init` in it.
+
+## The plan meters
+
+**"Sign in to Claude Code to see usage."**
+No Claude Code login was found on this machine. Run `claude` and sign in.
+
+**"Claude Code login expired."**
+Run `claude` once; it refreshes the login.
+
+**"Usage unavailable (429)."**
+The usage endpoint is rate-limiting. The office backs off and tries again on
+its own; jobs aren't affected.
+
+**The meters are gone.**
+Claude access is set to *API key*. There's no plan to measure; usage is in
+your Anthropic Console.
+
+## Voice
+
+**The microphone does nothing, or "No speech model installed."**
+Install the listening side: `brew install ffmpeg whisper-cpp`, then
+`npm run voice:model`. See [Talking out loud](../voice.md).
+
+**"Piper is not installed" or "Piper has no voices downloaded."**
+Run `npm run voice:piper` (needs Python 3). Until then, replies use the
+browser's built-in voices.
+
+**The browser won't allow the microphone.**
+Browsers only allow it on `localhost` or HTTPS. Open the office at
+`http://localhost:4317`, not an IP address.
+
+## The terminal won't open
+
+**There's no terminal button, or it says the terminal is off.**
+It's off by default. Start the office with `OFFICE_TERMINAL=1 npm start`.
+
+**"node-pty is not installed."**
+It's a native module and needs build tools. On macOS:
+`xcode-select --install`, then `npm install`. On Linux: install
+`build-essential` and `python3`, then `npm install`.
+
+## On a phone
+
+**"Local only." (HTTP 403)**
+The office only accepts its own hostnames. Add the one you're using:
+`OFFICE_ALLOWED_HOSTS=my-mac.tail1234.ts.net npm start`. See
+[On your phone](../phone.md).
+
+## Still stuck?
+
+Search the [issues](https://github.com/onuohasilver/agent-office/issues), or
+open one with the server output and the browser console. Please remove keys,
+tokens and private paths first.

package/docs/guides/updating.md

@@ -0,0 +1,36 @@
+# Updating
+
+Your office's state — jobs, chat, channels, XP, team profiles, Claude access —
+lives in `data/`, which updates never touch.
+
+## From a git clone
+
+```bash
+cd agent-office
+git pull
+npm install
+npm run build
+```
+
+Then stop the office (Ctrl-C in its terminal) and start it again with
+`npm start`. Running jobs are stopped cleanly and resume when it comes back.
+
+Read [CHANGELOG.md](../../CHANGELOG.md) for what changed, and anything you
+need to do.
+
+## Pinning a version
+
+To stay on a release rather than the latest code:
+
+```bash
+git fetch --tags
+git checkout v0.1.0
+npm install && npm run build
+```
+
+## If something breaks
+
+- `npm install` failing on `node-pty` is harmless: it's optional, and only
+  the terminal needs it. See [Troubleshooting](troubleshooting.md#the-terminal-wont-open).
+- To keep a way back, copy `data/` before updating. Going back is then: stop
+  the office, check out the previous tag, restore `data/`, build and start.

package/docs/guides/working-with-the-team.md

@@ -0,0 +1,56 @@
+# Working with the team
+
+Habits that get better work out of the office for less.
+
+## Write briefs like you would for a colleague
+
+The agent starts knowing nothing but the project folder and what you wrote.
+
+- **Say what done looks like.** *"Make the tests pass"* is clearer than
+  *"look at the tests"*.
+- **Point at the place.** A file, a route, an error message. Paste the error
+  or drop a screenshot on the composer — the chief can read screenshots.
+- **Say what not to touch** if it matters: *"don't change the public API"*.
+- **One job, one outcome.** Three unrelated fixes are three jobs; they can run
+  at the same time with three agents.
+
+## Pick the clearance for the job, not the agent
+
+| Job | Clearance |
+|---|---|
+| "How does X work?", "plan the migration" | **Plan only** — nothing changes |
+| Most code changes | **Edit files** — no commands |
+| Needs tests, builds, git, installs | **Full autonomy** |
+
+You don't have to guess right. An *Edit files* job that needs a command stops
+and asks, and you can grant it then. A *Plan only* job ends with a plan you
+can approve and have built.
+
+## Let the chief pick the model
+
+**Chief picks** sends small mechanical work to Haiku, ordinary work to Sonnet
+and hard work to Opus, and steps up a rung on its own when a job fails.
+Choose a model yourself only when you know better — and then it won't change.
+
+## Use channels for strands of work
+
+Everything said in a channel stays in it, and the chief only reads that
+channel's history when working out what you mean. A `#billing` channel for a
+week of billing work keeps the context tight and the chief's answers sharp.
+
+## Follow up in the thread
+
+Replying in a job's thread resumes the same agent's session, so they keep
+everything they already read. A new message in the main chat may go to
+someone else, who starts from scratch.
+
+## Keep an eye on cost
+
+- The bar at the top shows what's working, queued, shipped and spent.
+- On the Claude Code login, the **Session** and **Week** meters show how much
+  of your plan is used. They turn amber at 70% and red at 90%.
+- Each job's drawer shows its model and how much context its last turn
+  carried. A long-running session gets expensive; a fresh job with a good
+  brief is often cheaper than one more follow-up.
+- Break-room talk uses a small model at most once every two minutes. Turn it
+  off with `BANTER=off` if you'd rather it didn't.

package/docs/guides/your-first-job.md

@@ -0,0 +1,65 @@
+# Your first job
+
+Ten minutes from a fresh install to a change you've reviewed. This assumes
+the office is running — if not, start with [Getting started](../getting-started.md).
+
+## 1. Pick something small
+
+The first job should be easy to check by eye: fix a typo, add a test case,
+rename something, tidy a README. You'll learn how the office works without
+wondering whether the agent got something subtle right.
+
+## 2. Check the pickers under the composer
+
+- **Clearance** — leave it on **Edit files**. The agent can read and change
+  files but not run commands, which is the right amount of trust for a first
+  job. ([What each one allows](../jobs.md#clearance).)
+- **Model** — leave it on **Chief picks**. A small job will go to Haiku or
+  Sonnet.
+
+## 3. Ask
+
+In `#general`, tag a project with `#` and say what you want, as you'd say it
+to a colleague:
+
+```
+#storefront the checkout button says "Procede" — fix the spelling
+```
+
+You can tag someone with `@` too (`@Ada #storefront …`). Without a tag, the
+chief of staff picks whoever is free and replies with who and why.
+
+## 4. Watch
+
+The agent gets up and goes to work. Where they walk tells you what they're
+doing: the **library** to read code, their **desk** to write, the **server
+room** to run commands, the **whiteboard** to plan. Their updates collect in a
+thread under your message; open it, or click the agent, to follow along.
+
+## 5. Review what changed
+
+When they're done, the result lands in the chat with a chime. Open the job
+(the **Jobs** tab, or the link in the reply) and look at **What changed**:
+every file the job touched, with lines added and removed. Click a file to see
+its patch.
+
+The change is in your working tree, not committed. Review it the way you
+would any change — `git diff`, your editor, your tests — and commit it
+yourself when you're happy.
+
+## 6. Follow up
+
+Not quite right? Reply in the job's thread: *"also fix it on the receipt
+page"*. The same agent picks it up in the same session, with everything they
+learned the first time. If the chief chose the model and the work was wrong,
+saying so sends it back one model up.
+
+If the agent got **blocked** — it tried to run a command its clearance
+doesn't allow — the job's drawer shows what was refused, with a button to
+grant more and carry on.
+
+## Next
+
+- [Working with the team](working-with-the-team.md) — briefs that work,
+  channels, and keeping costs down.
+- [Jobs](../jobs.md) — clearance, models and what changed in detail.

package/docs/how-it-works.md

@@ -0,0 +1,80 @@
+# How the office works
+
+## Jobs are `claude` processes
+
+Every job is one headless `claude` process whose stdin stays open, so new
+messages can reach it mid-task. What they do on screen is
+driven by the tool calls in its stream:
+
+| Work | Where they go |
+|---|---|
+| Read, Grep, Glob | Library |
+| Bash | Server room |
+| WebSearch, WebFetch, MCP tools | Research window |
+| Plans, todos, sub-agents | Whiteboard |
+| Edits and writing | Their desk |
+
+The server (`server/index.js`) keeps the office state, routes chat through the
+chief of staff, starts and supervises those processes, and pushes everything
+to the browser over one websocket. The browser draws the office with three.js
+and moves each agent to wherever their latest tool call says they are.
+
+The chief of staff, standup and break-room talk are short `claude -p` calls
+too, with no tools, a JSON schema for the answer and no session kept.
+
+## Agents talk to each other
+
+Every agent gets three office tools (a small MCP server, `server/office-mcp.js`):
+
+- `office_roster`: who's around and what they're on.
+- `message_colleague`: reaches a working colleague mid-task. With
+  `wait_for_reply`, the sender's session pauses until the answer comes (10
+  minute limit).
+- `hand_off`: gives work in any project to a free colleague. Their result goes
+  back to the sender, who waits for it by default.
+
+Hand-offs only go to someone free right now, so two agents can never wait on
+each other. A job can be handed down at most twice. The sender walks over to
+the colleague, and the exchange shows in the chat as "Ada → Tunde".
+
+When someone ships you hear a chime, and if the tab is in the background you
+get a desktop notification. The speaker in the top right mutes it.
+
+If the server restarts mid-job, jobs with a session resume where they left off.
+
+## Where things are kept
+
+| Path | What |
+|---|---|
+| `data/state.json` | jobs, chat, channels, XP, team profiles |
+| `data/activity.json` | per-day jobs, tokens and agent time |
+| `data/leaderboard.json` | leaderboard handle and secret, if you joined (mode 0600) |
+| `data/auth.json` | how Claude is signed in to, and the API key if you gave one (mode `0600`) |
+| `data/uploads/` | attachments and voice notes |
+| `data/whisper/`, `data/piper/` | speech models, if you installed them |
+| `data/terminal.log` | when terminal sessions opened and closed |
+
+`data/` is git-ignored. State is written shortly after every change, and the server stops its jobs cleanly on Ctrl-C so they can resume.
+
+## Source layout
+
+| Path | What |
+|---|---|
+| `server/index.js` | HTTP + websocket server, jobs, chat, chief, standup, break room |
+| `server/office-mcp.js` | the MCP server that gives agents the office tools |
+| `server/chief.js` | the chief of staff's routing call |
+| `server/standup.js`, `server/banter.js` | standup write-up, break-room small talk |
+| `server/auth.js` | Claude access: login or API key |
+| `server/usage.js` | plan usage meters |
+| `server/leaderboard.js` | the activity ledger and the optional leaderboard |
+| `leaderboard/` | the leaderboard service (a Cloudflare Worker) |
+| `server/changes.js` | the "what changed" snapshots and diffs |
+| `server/voice.js` | whisper.cpp transcription and Piper voices |
+| `server/terminal.js` | the in-app terminal |
+| `server/procstat.js` | agents' CPU and memory |
+| `web/src/main.js` | browser entry: socket, state, wiring |
+| `web/src/office.js`, `figure.js`, `agent.js` | the 3D office and the people in it |
+| `web/src/hud.js` | sidebar, chat, job drawer |
+| `web/src/breakroom.js`, `pool.js`, `pool-sim.js` | break-room talk and eight-ball |
+| `web/public/` | PWA manifest, service worker, icons |
+| `shared/` | code used by both sides |

package/docs/jobs.md

@@ -0,0 +1,54 @@
+# Jobs
+
+A job is one piece of work given to one agent in one project folder. You start
+one by asking in the chat; the agent posts its result back there, and the
+job's drawer (click the job, or the agent) shows everything it did.
+
+## Clearance
+
+**Clearance** decides what a job may do: *Plan only* changes nothing, *Edit
+files* can edit but shell commands get blocked, *Full autonomy* runs anything.
+When a job gets blocked, its drawer offers to grant clearance and continue the
+same session. A finished plan can be approved and built the same way.
+
+## Sizing the work
+
+Most jobs don't need the most capable model, so the chief picks one when the
+model picker is left on **Chief picks**: *Haiku* for small mechanical changes,
+*Sonnet* for ordinary work, *Opus* for genuinely hard work. The rung it chose
+is shown beside its reply in the chat, and in the job's drawer.
+
+A job that **fails** on a model the chief picked goes back in the queue one
+rung up — Haiku to Sonnet to Opus — and the chat says so. So does a finished
+job you send back as wrong or incomplete. Escalation stops at Opus, and a job
+that failed before the model ever got a turn (a missing folder, a binary that
+won't start) stays where it is: a dearer model would fail the same way.
+
+The retry starts a fresh session carrying the brief and a summary of what the
+last attempt reported, rather than resuming it. The prompt cache belongs to
+the model that filled it, so resuming would have the dearer model read the
+whole failed transcript at full price. A job you picked the model for yourself
+never moves on its own.
+
+The drawer shows each job's model and how much context its last turn carried,
+so a session that has grown expensive is visible rather than guessed at.
+
+## What changed
+
+When a job starts, the office snapshots the project's working tree; when it
+finishes, it snapshots it again and diffs the two. The drawer shows the result
+as one line — files changed, lines added and removed — that opens into the
+file list, and any file opens into its patch.
+
+The snapshots are git tree objects built from a throwaway index, so nothing in
+the repo's own index, stash or history is touched, and untracked files are
+included (ignored ones aren't). A job resumed with a reply keeps its first
+snapshot, so the card covers the whole job. Projects that aren't git
+repositories don't get a card.
+
+## When the server restarts
+
+Jobs with a session resume where they left off. A restart asked for from
+inside the office (`/restart`, or an agent's `restart_office`) waits for
+everyone to finish their turn first; see
+[Development](development.md#shipping-a-server-change).

package/docs/leaderboard.md

@@ -0,0 +1,65 @@
+# The leaderboard
+
+An optional board where offices compare how much they got done. It is off
+until you join, and it needs a leaderboard service somebody hosts (see
+[`leaderboard/`](../leaderboard/README.md)).
+
+## What is ranked
+
+Three boards, each for this week (Monday to Sunday, UTC) or all time:
+
+- **Jobs**: jobs finished. Failed and stopped jobs don't count.
+- **Tokens**: input plus output tokens your agents used. Cached context is left
+  out, since it is the same tokens read again.
+- **Time**: agent time, the time agents spent working on turns, added up. Two
+  agents working side by side for an hour is two hours. Waiting on a colleague
+  or on you isn't counted.
+
+Tokens and time reward using the office more, not doing better work, so treat
+the board as a bit of fun. Counts are reported by each office and can't be
+verified.
+
+## Your own counters
+
+The office keeps the day-by-day counters in `data/activity.json` whether or not
+you join, so they survive clearing the job list. They are three numbers per UTC
+day. Nothing leaves your machine until you join.
+
+## Joining
+
+1. Open the trophy button in the sidebar header.
+2. Pick a handle (3 to 20 letters, numbers, `-` or `_`). Handles are first come,
+   first served, and not case-sensitive.
+3. The office makes a random secret, claims the handle with it, and starts
+   sharing.
+
+Joining shares the last 14 days of your counters, then each change a minute or
+so after it happens. A day's numbers are set, not added, so a retry never
+counts twice.
+
+## What is shared
+
+Per UTC day: jobs finished, tokens, seconds of agent time. Plus the handle.
+That is all: no prompts, project or file names, chat, cost, plan usage, or
+anything that identifies you beyond the handle you picked.
+
+The service stores a hash of your secret (never the secret), your handle, and
+those day counters. Boards list handles and totals.
+
+## Leaving
+
+"Leave and delete my data" asks the service to delete your handle and counters,
+then forgets the secret here. If the service can't be reached, nothing changes
+and you can try again. Your local `data/activity.json` stays; delete it if you
+want that gone too.
+
+## Setting it up
+
+Set the address of your service and restart the office:
+
+```
+OFFICE_LEADERBOARD_URL=https://your-service.example npm start
+```
+
+It must be `https` (plain `http` works only for `localhost`). Without it the
+panel says no leaderboard is set up and nothing is ever sent.

package/docs/packaging.md

@@ -0,0 +1,49 @@
+# Packaging roadmap
+
+How the office gets from "clone the repo" to something people install. This is
+a plan, not shipped work.
+
+## Where it stands
+
+The office is a single-user tool that runs locally: one Node server, a web
+build in `dist/`, and the user's own `claude` CLI doing the work. Everyone who
+can use it already has a terminal and Claude Code, which decides the shape of
+the package.
+
+## Options
+
+| Option | Fit | Cost | Main problem |
+|---|---|---|---|
+| **npm CLI** (`npx agent-office`) | Best: the audience already has Node and Claude Code | ~1 week | data and project root must move out of the package |
+| **Homebrew tap** | Good extra for Mac users | ~1 day on top of npm | another channel to release to |
+| **Desktop app** (Electron) | Friendlier, but still needs the `claude` CLI | 3–5 weeks | signing and notarisation, auto-update, `node-pty` rebuilds |
+| **Docker** | Poor for a local tool | ~1 week | agents edit *host* repos: bind mounts, file ownership, git/SSH keys, login inside the container |
+| **Hosted** | A different product | months | accounts, a sandbox per user, repos via GitHub, a database, API billing; the local-only security model goes |
+
+**Plan:** ship the npm CLI first, with the PWA ([On your phone](phone.md))
+standing in for a desktop window; add Homebrew next; build a desktop app only
+if users ask for one; leave hosted until the local version has users.
+
+## Steps
+
+- [x] **Claude access:** users choose the Claude Code login or an API key
+      ([Claude access](claude-access.md)).
+- [x] **Licence:** MIT ([`LICENSE`](../LICENSE)).
+- [ ] **npm name:** confirm `agent-office` is free, or pick another.
+- [ ] **Data directory:** `~/.agent-office` (or `$XDG_DATA_HOME`) with an
+      `OFFICE_DATA` override, migrating an existing `<app>/data` on first run.
+- [ ] **Project root:** default to the current directory, `--root <dir>`,
+      remembered after the first run.
+- [ ] **`bin/agent-office.js`:** `--port`, `--root`, `--open`, `--terminal`;
+      pick another port if 4317 is taken; open the browser.
+- [ ] **Preflight:** `claude` on `PATH`, recent enough, and signed in or given a
+      key — one clear fix for each problem.
+- [ ] **Package:** publish a prebuilt `dist/`; move the web-only dependencies
+      (`three`, `marked`, `xterm`, fonts) to devDependencies so the runtime
+      needs only `ws`.
+- [ ] **Terminal:** a `node-pty` build with prebuilt binaries, still optional.
+- [ ] **Voice:** `agent-office voice setup` in place of the two npm scripts.
+- [ ] **Plan meters:** hide quietly if the usage endpoint goes away.
+- [ ] **Platforms:** CI on clean macOS and Ubuntu; Windows via WSL.
+- [ ] **Releases:** on a tag, a smoke test against a stub `claude`, then
+      `npm publish --provenance` and a Homebrew bump; a CHANGELOG.

package/docs/phone.md

@@ -0,0 +1,28 @@
+# On your phone
+
+The office is a progressive web app: open it in a phone browser and use
+**Add to Home Screen** (Safari) or **Install app** (Chrome) and it opens
+full-screen with its own icon. The same works on a desktop, in Chrome or Edge,
+for an office in its own window.
+
+The app shell is cached so it opens when the connection drops; live office
+state never is, because a stale office is worse than none.
+
+## Reaching your machine
+
+The server only listens on `127.0.0.1`, so a phone can't reach it directly.
+The supported way is [Tailscale](https://tailscale.com): put the office behind
+`tailscale serve` on this machine, then tell the office to accept that name.
+
+```bash
+tailscale serve --bg 4317
+OFFICE_ALLOWED_HOSTS=my-mac.tail1234.ts.net npm start
+```
+
+`OFFICE_ALLOWED_HOSTS` takes exact hostnames, comma-separated. Every other
+host and origin is still refused.
+
+**Read this first.** Whoever can open that address can run Claude in your
+projects with full autonomy, and — if `OFFICE_TERMINAL=1` — get a shell on
+this machine. Only expose it on a tailnet that is just you. Never put it on
+the open internet. See [Security](security.md).

package/docs/security.md

@@ -0,0 +1,48 @@
+# Security
+
+The office starts Claude in your projects, can give it full autonomy, and can
+hand out a shell. It is built to be used by one person, on their own machine.
+
+## Who can reach it
+
+- The server listens on `127.0.0.1` only.
+- Every request's `Host` and `Origin` must be local (or a name in
+  `OFFICE_ALLOWED_HOSTS`), which keeps other websites and DNS-rebinding
+  attacks out of it.
+- Agents call back into the office (the roster, messages, hand-offs) with a
+  per-job token that dies with the job.
+
+Don't put it behind a public URL. If you reach it from your phone, do it over
+a private network that is only you — see [On your phone](phone.md).
+
+## What jobs may do
+
+Each job runs with the clearance you picked — *Plan only*, *Edit files* or
+*Full autonomy* — enforced by Claude Code's own permission modes, and leaves a
+full log in its drawer. Full autonomy means what it says: the agent can run any
+command you could.
+
+## Claude credentials
+
+- With the **Claude Code login**, the office never sees your credentials; the
+  `claude` it starts reads them. The plan meters read the login's access token
+  to ask for usage, and nothing else.
+- With an **API key**, the key is checked with Anthropic, stored in
+  `data/auth.json` with mode `0600`, passed only to the `claude` processes the
+  office starts, and never sent to the browser, which sees the last four
+  characters.
+- `data/` is git-ignored.
+
+## The leaderboard
+
+Off until you join, and then the only thing besides Claude that the office
+talks to. It sends a handle and three counters per day (jobs, tokens, agent
+time) to the service named by `OFFICE_LEADERBOARD_URL`, signed with a random
+secret kept in `data/leaderboard.json` (mode `0600`). Never prompts, projects,
+files, chat or cost. Details in [The leaderboard](leaderboard.md).
+
+## The terminal
+
+Off unless `OFFICE_TERMINAL=1`. A session needs a single-use ticket from the
+origin-checked API, no agent can open one, and keystrokes are never logged. It
+is not a sandbox. Details in [The terminal](terminal.md).

package/docs/terminal.md

@@ -0,0 +1,46 @@
+# The terminal
+
+There is a real shell in the drawer under the office: `⌃``, or the terminal
+button in the top right. Tabs across the top, `+` opens another, and the picker
+beside it chooses which project folder the next one starts in. Drag the top
+edge to resize — the office makes room rather than hiding behind it. It is a
+proper pty, so `vim`, `top`, `git add -p`, colours and your own prompt all work
+the way they do in a terminal app.
+
+It is off until you ask for it:
+
+```bash
+OFFICE_TERMINAL=1 npm start
+```
+
+That switch exists because shell access is the one door in the building that
+doesn't care about clearance. A job runs with the mode you picked and leaves a
+log; a shell is you, with everything you can do, and no record of what it did.
+So:
+
+- **Off by default.** No flag, no terminal — the socket won't even open.
+- **This machine's browser only.** The server already refuses any request whose
+  host or origin isn't local. On top of that, a session needs a single-use
+  ticket that expires in ten seconds, and tickets are only handed out on that
+  origin-checked route — the socket accepts nothing else.
+- **Not for the staff.** No agent can open one. There's no office tool and no
+  `/api/agent` route that reaches it, and a shell never inherits the job
+  credentials the office gives its own children.
+- **Nothing is kept.** Not in `data/state.json`, not in the chat, not on the
+  main socket. Scrollback lives in the tab and dies with it. `data/terminal.log`
+  records when sessions opened and closed and in which folder — never
+  keystrokes, because a log of what you typed into a shell is a file full of
+  passwords.
+- **It tidies up.** Closing a tab hangs up the shell, a session with nothing
+  happening closes itself after 30 minutes, and there's a cap on how many can
+  be open at once.
+
+What it is *not* is a sandbox. The shell runs as you and `cd ..` walks out of
+whichever folder it started in; picking the folder is a convenience, not a
+boundary. Leave it off on any machine where "whoever has the browser" isn't
+just you.
+
+The terminal needs [`node-pty`](https://github.com/microsoft/node-pty), which
+builds natively — it's an optional dependency, so `npm install` on a machine
+without build tools still gets you the whole office, just without this. On
+macOS: `xcode-select --install`, then `npm install`.