@nanocollective/roster 0.1.0-alpha.6 → 0.1.0-alpha.7

package/docs/concepts.md

@@ -6,24 +6,64 @@ sidebar_order: 3
 
 # Concepts
 
+## The six things you need to know
+
+Enough to set up an org and read what it does. Everything after this section is detail you
+can learn when you need it.
+
+1. **The org layer.** One private repo, `<org>/roster-ops`, holds what every staff member
+   shares: what the business is (`org/business.md`), what matters this month
+   (`org/priorities.md`), the house voice and the guardrails. Change it once and every staff
+   member has it on their next run. [More](#the-ops-repo).
+2. **A staff member is a repo.** Each one has a private repo, its *brain*: what it knows, what
+   it is working on, and what it has decided. There is no database and no server; the portal
+   reads the repos. [More](#the-brain).
+3. **The charter.** `CHARTER.md` in the brain says who this staff member is and what it
+   decides alone. You write it, with a brief that interviews you; roster never generates one,
+   because a generated charter makes a generic agent. [More](#charter-and-manifest).
+4. **Memory.** `memory/INDEX.md` is one line per fact, read at the start of every run. The
+   agent writes it and deletes from it; you can read and correct it in the portal. That is how
+   a staff member remembers yesterday. [More](memory.md).
+5. **The daily run.** A scheduled GitHub Actions workflow in each brain wakes the staff member,
+   hands it a prompt built from the org layer plus its charter and memory, and it does one piece
+   of work and writes down what happened. [More](#kinds-of-run).
+6. **Mentions.** Write `@handle` in an issue or comment on a staff member's own tracker and it
+   runs to answer that, between daily runs. Nothing on a product repo wakes anybody; you ask
+   them on their tracker. [More](#kinds-of-run).
+
+Everything below, and the rest of the docs, is detail: identities, peers, surfaces, the
+prompt's layers, upgrading. None of it is needed to get a first run.
+
 ## The ops repo
 
 `<org>/roster-ops` holds two different kinds of thing, and the split matters.
 
-**`org/` is yours.** `business.md`, `voice.md`, `guardrails.md`, `operating.md`. This is the
-business truth and the shared half of every staff member's instructions. Edit it freely: the
+**`org/` is yours.** `business.md`, `priorities.md`, `voice.md`, `guardrails.md`,
+`operating.md`. This is the business truth and the shared half of every staff member's
+instructions. Edit it freely: the
 [Org screen](portal.md#org) lists every one of these off disk with an Edit button, and saving
 commits and pushes. A change here reaches everybody on their next run, which is the point: a
-concision rule that used to mean editing twelve files is now one file.
+rule every staff member should follow is one edit, not one per repo.
 
 **Everything else is machinery** and belongs to the framework: `compose.mjs`, `agents.mjs`,
-`runner-plan.mjs`, `.github/workflows/session.yaml`. Editing these works right up until the
+`runner-plan.mjs`, `inflight.mjs`, `run-record.mjs`, `.github/workflows/session.yaml`. Editing these works right up until the
 framework changes the same file, at which point your change is a conflict at best and silently
 reverted at worst. Fix machinery in the framework, then `roster upgrade`.
 
 `roster upgrade` enforces this distinction. It reports an edit to a framework-owned file even
 when nothing has collided yet, because "not broken yet" is the state a lost fix sits in.
 
+## Priorities
+
+`org/priorities.md` is the one direction every staff member shares: what matters this month,
+ranked, and what is out of scope. It is composed into every daily run, a run picks work that
+serves it, and a PR names the priority it serves. Keep it to three priorities or fewer, and
+rewrite it when the month turns.
+
+Without it each staff member picks its own work from its own charter, and they drift. `roster
+init` writes a stub; `roster doctor` warns while it is missing or still the stub. An org that
+predates it just adds the file.
+
 ## The brain
 
 A staff member's repository *is* their memory. There is no database.
@@ -65,7 +105,7 @@ exports declares `gallery` and `table`; nothing in the portal knows what a CMO i
 
 ```
 org/operating.md + org/guardrails.md + org/voice.md + org/business.md
-                 + <staff>/CHARTER.md + prompts/<kind>.md
+                 + org/priorities.md + <staff>/CHARTER.md + prompts/<kind>.md
 ```
 
 Built at run time by `compose.mjs` in the tenant's own repo. See it for yourself on the
@@ -90,21 +130,15 @@ control.
 A `mention` prompt refuses to compose without trigger context, because it is written for the
 comment that woke it. That is correct behaviour, not a bug.
 
-There used to be a third, `pr-mention`: a review comment on the public product repo, forwarded
-into the brain by a workflow in that repo. It was removed. Two repos, a dispatch, a forwarder
-with its own author gate and a second reaction path bought one thing: asking for a change
-without leaving the diff. It cost more than that was worth, in explaining and in debugging.
-
-What replaced it is the reply box. A pull request is on the product repo, and **nothing in a
-product repo wakes anybody**: a staff member's caller workflow is in their own brain repo and
+**Nothing in a product repo wakes anybody.** A pull request is on the product repo, and a staff member's caller workflow is in their own brain repo and
 gates on their `@handle` appearing *there*. So naming somebody in a reply where a comment will
 not reach them offers, under the box, to open the request on their tracker as well. One press
 posts your words on the thread and sends them the pull request, the branch, the hunk you were
 looking at if you started from a file, and an instruction to answer on the pull request rather
 than in the tracker it arrived in.
 
-It is two `gh` calls as you, rather than a workflow, a dispatch and a second gate, which is the
-difference that got the forwarder deleted. See [the portal](portal.md#asking-for-a-change).
+It is two `gh` calls as you, rather than a workflow in the product repo with its own gate and
+its own credential. See [the portal](portal.md#asking-for-a-change).
 
 ## Identities
 

package/docs/cost.md

@@ -12,19 +12,54 @@ Three separate bills, and they behave differently.
 
 The largest by far, and the one that scales with how much work you ask for.
 
+On a Claude subscription, through a Claude Code OAuth token, it is a flat subscription rather
+than spend per token, and what grows with a session is how much of its usage you take. That is
+how Pip's staff run.
+
 A session's cost is roughly its length. Ours run 11 to 55 minutes of wall clock, and a longer
 session is a bigger bill as well as a slower one. The lever that matters is not the model
 setting, it is how much you ask a staff member to do each morning and how much context it has
 to read to start.
 
 That is why the memory system is shaped the way it is. Boot context here went from about 52,000
-words to about 6,000 by moving from a narrative status file to one line per fact. That is a
+words to about 10,000 today by moving from a narrative status file to one line per fact. That is a
 direct, repeated saving on every run of every staff member.
 
 **Watch for sessions growing into their ceiling.** A run that gets killed at
 `timeout_minutes` has been paid for and produced nothing. Health, and `roster doctor`, report
 the ratio.
 
+## What each run cost
+
+Every session writes down what it was, after the agent finishes or fails: staff, kind, outcome,
+duration, and turns, cost and tokens where the agent reports them. It goes in the job summary,
+and into an artifact called `roster-run` holding one `run.json`.
+
+Which agents report what:
+
+| Agent | Turns, cost, tokens |
+|---|---|
+| `claude-code-action` | yes, from the Action's execution file |
+| `claude` | yes, from `--output-format json` |
+| anything else | only if its `run` writes the agent's result JSON to `$AGENT_RESULT_FILE` |
+
+What is not reported is recorded as unknown, never as zero. A total built from guesses is worse
+than none, so every total says how many runs it could price. The cost is the agent's own figure:
+on a subscription it is what the tokens would have cost, not what you were billed.
+
+The portal's [Runs](portal.md#runs) screen lists them per staff member, with a link to each log
+and a 30-day total.
+
+## Budgets
+
+An optional [`budget`](org-yaml.md#budget) in `org.yaml`, in dollars over any trailing 30 days,
+for the org or for one staff member. Past it, `roster doctor` warns (`budget`) and the Runs
+screen marks the total.
+
+It is a warning and never a cap. Stopping a session mid-run fails it after the work is done and
+committed, which is also why there is no `--max-turns`. Use the warning to go and
+look at which runs cost most and why; the levers are below.
+
 ## GitHub Actions minutes
 
 Real on private repositories, and easy to forget because it is metered per minute of runner

package/docs/developing.md

@@ -34,10 +34,8 @@ test/                  one file per area
 module per screen under `js/views/`. `roster portal` serves them from `/assets`, reading each
 file per request. Editing a stylesheet and reloading the page is the whole edit loop.
 
-It was one 2,100-line HTML file until the CSS and the seven screens grew past the point where
-any of them could be found in it. Splitting it needed no bundler, because the browser resolves
-the module graph itself, and a bundler would have been a build step in a tool whose selling
-point is that it does not have one.
+No bundler, because the browser resolves the module graph itself, and a bundler would be a
+build step in a tool whose selling point is that it does not have one.
 
 ```
 templates/portal/
@@ -64,13 +62,12 @@ registers into at boot.
 
 ## The rule that matters
 
-**Never fix a generated file in a tenant.** `compose.mjs`, `agents.mjs`, `runner-plan.mjs` and
-`session.yaml` live in `templates/ops/`. Fix them there and run `roster upgrade`.
+**Never fix a generated file in a tenant.** `compose.mjs`, `agents.mjs`, `runner-plan.mjs`,
+`inflight.mjs`, `run-record.mjs` and `session.yaml` live in `templates/ops/`. Fix them there and run `roster upgrade`.
 
-This has gone wrong once already. A fix went into `roster-ops/.github/workflows/session.yaml`
-instead of the template and nothing noticed, because the framework had not touched that file
-yet. `roster upgrade` now reports an edit to a framework-owned file whether or not anything has
-collided, and `roster upgrade --check` fails on it.
+A fix made in the tenant's copy goes unnoticed until the framework next touches that file, and
+then it is a conflict. So `roster upgrade` reports an edit to a framework-owned file whether or
+not anything has collided, and `roster upgrade --check` fails on it.
 
 ## Template classes
 
@@ -101,21 +98,19 @@ marker, or the leftover line is stranded.
 
 ## How the tests are meant to work
 
-Three habits, each of which came from a test that was passing vacuously.
+Three habits, each of which guards against a test that passes without testing anything.
 
-**Test the harness, not just the code.** The portal tests set a property on a dead object for
-several rounds, because the state they were driving was a top-level `let` in a classic script
-and not reachable as a global. The state is now an exported object, so the tests import the
-real modules under a DOM shim and there is nothing to get wrong.
+**Test the harness, not just the code.** The portal's state is an exported object, so the tests
+import the real modules under a DOM shim and drive the same state the page does. A test that
+sets a property on something the code never reads cannot fail.
 
-**Run it against reality.** The portal and doctor tests build from the live workspace rather
-than a fixture, so they break when real data grows a shape the code cannot handle. That is how
-the brain-comparison bug was found: every live workflow reported as absent, because filenames
-are templated and the comparison did not render them.
+**Run it against reality when you can.** The suite builds a temporary tenant by default, so it
+runs for anybody who clones the repo. Set `ROSTER_TEST_WORKSPACE=<dir>` to run the portal and
+doctor tests against a real workspace instead, which is how you catch real data growing a shape
+the code cannot handle: templated filenames, for instance, that a comparison forgot to render.
 
 **Mutation-test the invariants.** For anything asserting "this behaviour must not regress",
-break it deliberately and check the test fails. The workflow-template tests were verified this
-way, one mutation each.
+break it deliberately and check the test fails. If it does not, the assertion is decoration.
 
 ## Adding a command
 

package/docs/doctor-codes.md

@@ -33,7 +33,13 @@ ran at all.
 | `agent.config` | **fail.** The agent needs a config file of its own and it is missing, or still has a `FILL IN` in it. Nanocoder is the one preset that does: it is a client rather than a model, so without a provider it starts, finds nothing to call, and exits. |
 | `business` | **fail** if `org/business.md` is missing. Every prompt is composed on top of it. |
 | `business.stub` | `org/business.md` is still the questions it shipped with. Nothing errors; the agents just write competent work about a business that does not exist. |
-| `actions-access` | **fail** unless the ops repo is callable from the whole organisation. This is the "workflow not found" trap. See [manual steps](manual-steps.md#1-allow-the-ops-repos-workflow-to-be-called). |
+| `priorities` | No `org/priorities.md`. Nothing breaks; each staff member just picks its own direction. See [concepts](concepts.md#priorities). |
+| `priorities.stub` | `org/priorities.md` is still the stub `roster init` wrote. |
+| `actions-access` | **fail** unless the ops repo is callable from the whole organisation. This is the "workflow not found" trap. See [manual steps](manual-steps.md#what-roster-does-for-you). |
+| `workflows` | No workflow in the repo is failing run after run. Reported for the ops repo here, and for each brain repo under its staff member. |
+| `workflows.failing` | **fail.** A workflow that is not one of roster's callers has failed at least its last two runs, with the date it started. Skipped and cancelled runs are stepped over. This is the canary that goes red and stays red, because whatever would have said so broke with it. |
+| `budget` | Trailing 30-day spend against a `budget` in `org.yaml`, for the org here and for a staff member under their name. A warning when it is past, never a failure, and only read when a budget is set. Cost comes from each run's record, so it says how many runs it could price. See [cost](cost.md#budgets). |
+| `review-gate` | One per product repo. **fail** when nothing requires a pull request on its default branch, or a staff App can bypass the rule; a warning when a PR is required with no approving review, or the settings cannot be read. See [security](security.md#the-review-gate). |
 | `upgrade` | The tenant is in sync with the framework. |
 | `upgrade.stale` | Generated files are behind. `roster upgrade --apply`. |
 | `upgrade.owned` | **fail.** A framework-owned file was edited in the tenant. Move the change upstream or the next upgrade reverts it. |
@@ -55,7 +61,7 @@ ran at all.
 | `callers.uses` | **fail.** A caller references no reusable workflow, or one in a different organisation. A private reusable workflow is only callable inside its own org. |
 | `callers.target` | **fail.** A caller points at a workflow file that is not in the ops repo. Fails at run time as "workflow not found". |
 | `surfaces` | A surface declared in `staff.yaml` is not on disk. The portal renders nothing for it. |
-| `secrets` | Every secret the callers reference exists on the brain repo. Derived from the callers themselves, not a fixed list. |
+| `secrets` | Every secret the callers reference exists on the brain repo, or is an organisation secret shared with it. Derived from the callers themselves, not a fixed list. |
 | `labels` | Every label declared in `staff.yaml` exists. An agent applying a label that does not exist gets an API error mid-run. |
 | `peer-labels` | The `from-<handle>` label exists on the *peer's* tracker, which is where this staff member's asks land. |
 | `status-issue` | The declared status issue is actually pinned. If not, the place you look is not the place the agent maintains. |

package/docs/extending.md

@@ -24,8 +24,8 @@ there too.
 | `guardrails.md` | non-negotiables. What nobody may do, regardless of charter. |
 | `operating.md` | the autonomy contract: the boot ritual, the hand-off, decision rights. |
 
-This is the seam that pays. A concision rule here used to mean editing twelve files across two
-repositories; now it is one file, and the next morning everybody has it.
+This is the seam that pays. A rule written here is one file, and the next morning everybody
+has it.
 
 Keep the split honest. If a rule would be true of every staff member you will ever hire, it
 belongs here. If it is about one role, it belongs in that role's charter.

package/docs/getting-started.md

@@ -1,6 +1,6 @@
 ---
 title: "Getting started"
-description: "Stand up an org and a first staff member, from the portal."
+description: "From nothing to a first staff member's first finished run, in the portal."
 sidebar_order: 1
 ---
 
@@ -10,113 +10,115 @@ sidebar_order: 1
 npx @nanocollective/roster
 ```
 
-Run that in an empty directory. There is nothing else to install and nothing to configure
-first: the page that opens is the setup screen, and it is the whole of setup.
+Run that in an empty directory. The page that opens is the setup screen, and it is the whole of
+setup. Every step below is also a command, listed at the end; they do the same work on the same
+files.
 
-You need two things before you start. `gh` [authenticated](https://cli.github.com), and a
-credential for whichever [coding agent](agents.md) you want to run. A GitHub organisation too,
-if you do not already have one: GitHub has no API for creating one, so that part happens on
-github.com.
+**How long it takes:** about an hour and a half to two hours to a first staff member's first
+finished run. Most of that is writing: what the business is, and the staff member's charter,
+each a conversation of twenty to thirty minutes with your own AI. The rest is about a dozen
+clicks and waiting for the run. Those two files are what make the staff worth running, so that
+hour is the part not to rush.
 
-Everything below is also a command, and the commands are in [the CLI
-reference](commands.md). They do the same work on the same files. This page is the portal
-because that is the shorter road, not because the terminal is second class.
+## Before you start
 
-## 1. Say which organisation
+- **`gh`, [signed in](https://cli.github.com)**, as someone who owns the organisation. roster
+  does everything through your own `gh` and holds no token of its own.
+- **A GitHub organisation.** GitHub has no API for creating one, so if you need one, make it on
+  github.com first. Brains are private repos; on GitHub Free that works, with one difference in
+  step 5.
+- **A credential for your [coding agent](agents.md).** For Claude Code, run
+  `claude setup-token` and keep the token it prints for step 5.
 
-![The setup screen, asking which organisation and who runs it](images/setup-org.jpg)
+You only need [the six things in Concepts](concepts.md#the-six-things-you-need-to-know) to follow
+this. Everything else can wait.
 
-**It works out which of two things this is, and you do not have to know.** An organisation
-that does not run roster yet gets one stood up. One that already does gets *checked out* here
-instead, ops repo and every staff repo side by side, which is the shape the CI runner uses.
-That second case is how somebody joins an org a colleague set up, and offering both is how an
-org ends up with two `roster-ops` repos.
+## 1. Say which organisation, then read the plan
 
-The rest of the card is three answers: what the business is called, which GitHub login the
-agents answer to, and which coding agent runs a session. The agent is the one that is awkward
-to change later, because it decides which credential the repos need.
+![The setup screen, asking which organisation and who runs it](images/setup-org.jpg)
 
-## 2. Read the plan before anything exists
+Pick the organisation, say what the business is called and which coding agent runs a session.
+If the organisation already runs roster, the page offers to check it out here instead, which is
+how a second person joins.
 
 ![The plan: sixteen files and one private repo, listed before anything is written](images/setup-plan.jpg)
 
-Nothing has been created yet. **Show me the plan** lists every file and every repo it would
-make, and *Create it* is a separate button. This is the pattern everywhere in roster: the plan
-first, then the apply, and the same `initFiles` behind both the browser and the terminal so
-they cannot disagree about what a new tenant contains.
+**Show me the plan** lists every file and repo it would make; *Create it* is a separate button.
+That is the pattern everywhere in roster: the plan first, then the apply.
 
-After it applies you have `acme/roster-ops`: the org layer, the runner machinery, and a
-recorded merge base so later [upgrades](upgrading.md) are merges rather than copies.
+Creating it makes `<org>/roster-ops` and **sets its Actions access** so every repo in the org
+can call its workflow. Without that every run fails with "workflow not found". If GitHub refuses
+(it needs admin on the repo), the page says why and links to the setting to click instead.
 
-## 3. The Actions setting
+## 2. Say what the business is
 
-The page asks for this next and deep-links to the exact settings page, because it is the one
-step whose failure is unrecognisable.
+`org/business.md` ships as questions, and it is composed into the top of every prompt. An agent
+that cannot answer them writes plausible work about a business that does not exist.
 
-**Settings → Actions → General on `roster-ops`, set access to "accessible from repositories in
-the organisation".** Skip it and every workflow later fails with "workflow not found", which
-reads like a typo and is not one.
+**Copy the prompt** puts a brief on your clipboard with every file it refers to inside it. Paste
+it into Claude, ChatGPT or anything else; it interviews you and hands back the file. Paste the
+reply into the box and you get a diff and a save button. See
+[the portal](portal.md#copy-a-prompt-paste-the-answer-back).
 
-It is on [manual steps](manual-steps.md) with the others roster cannot do for you, and
-[Health](#7-health-then-one-run-by-hand) keeps asking until it is done.
+Then `org/priorities.md`: what matters this month, ranked, and what is out of scope. A few
+lines, only you can write it. See [concepts](concepts.md#priorities).
 
-## 4. Say what the business is
+## 3. Hire someone
 
-`org/business.md` ships as questions, and it is composed into the top of every prompt. An agent
-that cannot answer them writes plausible work about a business that does not exist, so this
-comes before hiring anybody.
+![The Staff screen, with a card per staff member and Hire someone underneath](images/staff.jpg)
 
-roster holds no model credential and cannot write it for you. What the portal does instead is
-both halves of the round trip: **Copy the prompt** puts a self-contained brief on your
-clipboard, and **paste the answer back** turns the reply into a file, with a diff and a button
-rather than a silent save. See [the portal](portal.md#copy-a-prompt-paste-the-answer-back).
+**Staff → Hire someone.** Only the handle is required. The plan shows the repo it creates, the
+schedule it chose, and the commits it will make **as you** in repos that already exist: each
+peer's `staff.yaml`, and `org.yaml`. Nothing is left uncommitted on disk.
 
-## 5. Hire someone
+For the first hire there is nobody to copy an App name from, so it asks.
 
-![The Staff screen, with a card per staff member and Hire someone underneath](images/staff.jpg)
+## 4. Create the App, and confirm the install
+
+**GitHub App**, on the new card. GitHub has no API that creates an App, so a tab opens and you
+confirm. The App's id and private key go straight into the repo's secrets and never touch disk.
 
-**Staff → Hire someone.** Only the handle is required; everything else is copied from whoever
-is already here. You get the plan first: every file, every label, the schedule it chose and
-why, the peer wiring in both directions, and the steps it cannot do for you.
+Then **Install it**. The install page opens with the organisation and every repo this staff
+member needs already ticked: its brain, the trackers of its peers, and the product repos. Check
+the list and confirm. That confirmation is yours by design: installing grants access, and GitHub
+asks a person.
 
-For the first hire in a new org there is nobody to copy an identity from, so the App names are
-asked for rather than guessed at. Later hires infer both.
+## 5. Store the agent credential, once
 
-## 6. Give them an identity, and install it
+**Agent credential**, on the card or on the setup screen. Paste the token from `claude
+setup-token` (or your agent's key; the box says where to get one). It is stored as one
+organisation secret, shared with the brain repos, and each later hire is added to it. It is not
+asked for again.
 
-**GitHub App**, on the same card. There is no API that creates a GitHub App, so this runs the
-manifest flow: a manifest is posted to a settings page, you confirm, and GitHub hands back a
-one-time code. The private key is held in memory and written straight to a repository secret
-without ever touching disk.
+On GitHub Free an org secret does not reach private repos, so there it goes on each brain repo
+instead, and the page says so. It is still one paste now; a later hire needs it once more.
 
-**What it cannot do is install the App.** That is a grant of access to specific repositories
-and GitHub asks a human to choose them, which is correct. Grant it every tracker the staff
-member writes to, not only their own. This is the step that most often looks done and is not.
+## 6. Write the charter
 
-Then **Write the charter**, which is the same copy-a-prompt loop as `business.md`, aimed at
-`CHARTER.md`. `hire` deliberately does not generate one: a generated charter produces exactly
-the generic agent this whole arrangement exists to avoid. It is the file that decides
-everything else, so it is worth the time. [Writing a charter](writing-a-charter.md).
+**Write the charter**, on the card. The same copy-a-prompt loop as step 2, aimed at
+`CHARTER.md`, carrying the org layer, the peers' charters and, where the role matches one, a
+[worked example](writing-a-charter.md#worked-examples) to model the shape on. The brief
+interviews you; the charter is yours. roster never generates one, because a generated charter
+makes exactly the generic agent this whole arrangement exists to avoid.
 
-## 7. Health, then one run by hand
+## 7. Run it once
 
-**Health** is `roster doctor` on the page, every finding carrying the sentence that fixes it,
-split into what an agent can do and what only a person can. Work through it until the ids are
-gone.
+**Run once now**, on the card or on **Health**. It starts the daily workflow, follows it, and
+tells you how it ended, with the log.
 
-Then trigger the daily workflow once from the Actions tab and read the log.
+**A workflow that has never run has proved nothing**: not that the App is installed on the right
+repos, not that the secrets are right. Doctor reports it as `unproven` until one run has
+finished, and this is that run. If it fails, the result names the step, and
+[troubleshooting](troubleshooting.md) has what each failure usually means.
 
-**A workflow that has never run has proved nothing.** Not that the App is installed, not that
-the grant took, not that the secrets are right. `doctor` says `unproven` rather than `fine` for
-exactly this reason.
+Health is `roster doctor` on the page. Every finding carries the sentence that fixes it.
 
 ## 8. Now look at what you built
 
 ![A staff member's brain: memory sections, the facts in them, and the files](images/brain.jpg)
 
-**Brain** is that staff member's memory and files together, because they were always the same
-thing. **Prompt** is the text they are actually sent, composed by your own `compose.mjs`, with
-every layer it was made of and which repo each came from.
+**Brain** is that staff member's memory and files together. **Prompt** is the text they are
+actually sent, with every layer it was made of and which repo each came from.
 
 ![The Prompt screen: the composed text, and the layers behind it](images/prompt.jpg)
 
@@ -126,14 +128,35 @@ that*. The answer is always in one of those files.
 ![The Org screen, with org.yaml and every layer every staff member inherits](images/org.jpg)
 
 **Org** is the layer everybody inherits. Change `org/voice.md` once and it reaches every staff
-member on their next run, without regenerating anything.
+member on their next run.
+
+## From a terminal
+
+The same road, command by command. Each prints its plan and changes nothing without `--apply`.
+
+```bash
+roster init --org acme --apply        # the ops repo, and its Actions access
+roster brief discover                 # a brief for org/business.md; write priorities.md too
+roster hire cto --apply               # the brain, the wiring, the commits as you
+roster app cto --apply                # the App, its secrets, and a pre-ticked install link
+roster credential --apply             # the agent credential, once for the org
+roster brief charter cto              # the charter brief, with the CTO example
+roster run cto --apply                # one run, followed to the end
+```
+
+## What is still yours to do
+
+Five things, each because GitHub or the job itself needs a person: creating the organisation,
+confirming the App, confirming its install, getting the agent credential, and writing
+`business.md`, `priorities.md` and each charter. [Manual steps](manual-steps.md) has why for
+each.
 
 ## Where things go from here
 
-- **A second staff member**: Staff → Hire someone, then the App. Peer wiring happens both ways.
+- **A second staff member**: Staff → Hire someone, then GitHub App, the charter and one run. The
+  credential is already there.
 - **Answering your agents**: [the Inbox](portal.md#inbox) is everything open across the org, and
-  the reply goes out as you. Work they finished sits in [Pending work](portal.md#pending-work);
-  asking for a change to it is [one button](portal.md#asking-for-a-change).
+  the reply goes out as you. Work they finished sits in [Pending work](portal.md#pending-work).
 - **A framework update**: `roster upgrade`, or the same from the portal. See
   [upgrading](upgrading.md).
 - **The whole portal**, screen by screen: [the portal](portal.md).