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

package/docs/manual-steps.md

@@ -1,186 +1,156 @@
 ---
 title: "Manual steps"
-description: "Every human action, why it cannot be automated, and what breaks if you skip it."
+description: "What only a person can do, why, and what breaks if it is skipped."
 sidebar_order: 2
 ---
 
 # Manual steps
 
-Everything a human has to do, why it cannot be automated, and what it looks like when you skip
-it. This page exists because every item on it has cost somebody real time.
+What roster cannot do for you, why, and what it looks like when one is skipped. The
+[getting started](getting-started.md) path walks through each of these in order; this page is
+what to read when one of them bites.
 
-**The portal walks you through most of this now.** `roster` with no arguments opens a setup screen
-that deep-links item 1, runs items 2 and 3 for you as far as GitHub allows, and hands you a prompt
-for items 5 and 6. This page is still the *why*: it is what to read when one of them bites, and
-what to check when the page says something is not done.
-
-The portal's **Health** screen checks most of these, per staff member and for the org, with
-every finding carrying the sentence that fixes it. `roster doctor` prints the same from a
-terminal. Look after each step.
+**Health**, or `roster doctor`, checks each one it can, and every finding carries the sentence
+that fixes it.
 
 ---
 
-## 1. Allow the ops repo's workflow to be called
-
-**Do:** `<org>/roster-ops` -> Settings -> Actions -> General -> *Access* -> **Accessible from
-repositories in the organisation**. The setup screen links straight to that page.
+## 1. Create the organisation
 
-**Why not automated:** it is an organisation permission on a repository, and the API for it
-needs admin rights that a token created for a different purpose should not have. roster reads
-it and tells you, but setting it is one click and it is yours.
+**Do:** make it on github.com, if you do not have one.
 
-**If you skip it:** every caller fails with **"workflow not found"**. That reads like a typo in
-a path, or a missing file, or a bad branch reference. You will check all three. It is none of
-them, it is this.
-
-**Check:** Health, or `roster doctor`, reports `roster-ops is callable from the whole org`.
+**Why not automated:** GitHub has no API for creating an organisation.
 
 ---
 
-## 2. Create the GitHub App
+## 2. Confirm the GitHub App
 
-**Do:** the **GitHub App** button on a staff card in the portal, or `roster app <handle>` in a
-terminal. Either opens a browser, GitHub asks you to confirm, and you come back. Credentials go
-straight into the repository's secrets.
+**Do:** press **GitHub App** on a staff card, or run `roster app <handle> --apply`. A tab
+opens; confirm on GitHub. The App's id and private key go straight into the brain repo's
+secrets.
 
-**Why not fully automated:** there is no API that creates a GitHub App. The only route is the
-App Manifest flow: POST a manifest to a settings page, a human confirms, GitHub returns a
-one-time code. roster does everything either side of that confirmation.
+**Why not automated:** there is no API that creates a GitHub App. The only route is the App
+Manifest flow, where a person confirms on a GitHub page. roster does everything either side of
+that.
 
-**If you skip it:** the run fails at the token-minting step with a message about the app not
-existing.
+**If you skip it:** the run fails at the token-minting step, saying the App does not exist.
 
-**Note:** the private key is handed to `gh` on standard input. It is never written to a file,
-never passed on a command line, and never appears in the process table. If the secret write
-fails after the App is created, the key is gone: generate a new one from the App's settings
-page and set the secret by hand. roster tells you this if it happens.
+The private key is handed to `gh` on standard input. It is never written to a file, never on a
+command line, and never in the process table. If the secret write fails after the App is
+created, the key is gone: generate a new one from the App's settings page and set the secret by
+hand. roster says so if it happens.
 
 ---
 
-## 3. Install the App, and grant it the right repositories
-
-**Do:** open the URL the portal shows, or that `roster app` prints. Choose repositories.
+## 3. Confirm the App's install
 
-**Why not automated:** installing is a grant of access to specific repositories, and GitHub
-requires a human to choose them. This is the correct behaviour and should not be worked around.
+**Do:** press **Install it** in the portal, or open the link `roster app` prints. The page opens
+with the organisation and the repos this staff member needs already selected: its brain, each
+peer's tracker, and the product repos. Check the list and confirm.
 
-**Grant it on every tracker the staff member writes to**, not just their own. The token is
-minted organisation-wide, and a peer's board is where a brief lands. Both the portal and
-`roster app` say so.
+**Why not automated:** installing is a grant of access to specific repositories, and GitHub asks
+a person to confirm it. That is correct and should not be worked around.
 
-**If you skip it, or under-grant it:** this is the trap that costs the most time, because of
-how it fails.
+The pre-selection uses `suggested_target_id` and `repository_ids[]` on the install page. GitHub's
+own links use them, but they are not in GitHub's documentation. If the ids cannot be read, or
+GitHub stops honouring them, the link is the plain install page and you tick the repos yourself;
+the portal and `roster app` both list which.
 
-> The API reports an App's **declaration** separately from an installation's **grant**.
-> `GET /apps/<slug>` will happily tell you the App exists and has `contents: write`. That says
-> nothing about whether it has been installed on the repository you care about. Two of our
-> Apps declare permissions they were never granted.
-
-So: **do not verify an installation by reading the API.** The only thing that proves the whole
-chain (App created, installed, granted, secrets right, workflow reachable) is a run that
-finished. `roster doctor` reads a window of recent runs for exactly this reason, and reports a
-workflow that has never run as **unproven** rather than as fine.
-
-**Check:** that staff member's Health screen, or `roster doctor <handle>`. Then trigger one run
-and look again.
+**If you under-grant it:** this is the trap that costs the most time, because the API reports an
+App's **declaration** separately from an installation's **grant**. `GET /apps/<slug>` will say
+the App exists and has `contents: write` without saying whether it is installed on the repo you
+care about. So **do not verify an installation by reading the API**. Run it once (item 5).
 
 ---
 
-## 4. Set the agent's credential
+## 4. Get the agent's credential
 
-**Do:** put the coding agent's credential on each brain repo as a secret. The name follows the
-credential: `CLAUDE_CODE_OAUTH_TOKEN`, `CODEX_API_KEY`, and so on. See
-[choosing a coding agent](agents.md).
+**Do:** get a credential for your coding agent (`claude setup-token` for Claude Code; the others
+are in [choosing a coding agent](agents.md#1-the-credential-exists-and-you-have-it)) and paste it
+into **Agent credential**, or pipe it to `roster credential --apply`. It is stored once, as an
+organisation secret shared with the brain repos, and each hire adds its repo to it.
 
 **Why not automated:** it is your account's credential and roster has no way to obtain one.
 
+Where an org secret would not arrive, it goes on each brain repo instead and says why. On GitHub
+Free, org secrets do not reach private repos, and only an org owner can set one. Setting an org
+secret also needs the `admin:org` scope on your `gh` token; if it is missing, the credential goes
+on each repo and the output gives the command that adds the scope.
+
 **If you skip it:** the run fails immediately with `the caller passed no agent credential`.
-That check exists so it fails there rather than forty lines later inside the agent, after the
-checkouts have already happened.
 
-**Check:** Health, or `roster doctor`, lists the secrets each caller references and whether
-they exist.
+**Check:** Health, or `roster doctor`, lists the secrets each caller references and whether they
+exist, on the repo or shared from the org.
 
 ---
 
-## 5. Write `org/business.md`
+## 5. Watch the first run
 
-**Do:** the setup screen does both halves of this. **Copy the prompt** puts a brief on your
-clipboard with every file it refers to inlined, so a chat window with no filesystem is as useful
-as an agent standing in the repo; the box beneath it takes the reply, shows you a diff, and
-saves only when you press the button. `roster brief discover` prints the same brief for a
-terminal, and you can always just answer the questions in the file by hand.
+**Do:** **Run once now** on the staff card or on Health, or `roster run <handle> --apply`. It
+starts the daily workflow, follows it, and reports how it ended, with the log.
 
-Health reports `business.stub` while it is still the questions.
+**Why it is yours:** it is a real run. It does a day's work and costs what one does, so it is a
+button you press rather than something setup does behind your back.
 
-**Why not automated:** an agent that does not know the business writes work that is plausible
-and generic. That is worse than no work, because it takes longer to notice. This file is
-composed into the top of every prompt, every run.
-
-**If you skip it:** nothing errors. That is the problem. You get competent-looking output about
-a business that does not exist.
+**Why it matters:** the only thing that proves the whole chain (App created, installed, granted,
+secrets right, ops repo callable) is a run that finished. `roster doctor` reports a workflow
+that has never run as **unproven** rather than fine, and one finished run clears it.
 
 ---
 
-## 6. Write each staff member's `CHARTER.md`
+## 6. Write `org/business.md` and `org/priorities.md`
 
-**Do:** **Write the charter** on that staff member's card, which is the same copy-a-prompt,
-paste-the-answer-back round trip as item 5, aimed at `CHARTER.md`. The brief it copies carries
-the org layer, `business.md` and **the peers' charters**, because without those the model writes
-a second copy of whoever it was shown. `roster brief charter <handle>` prints the same brief, and
-[writing a charter](writing-a-charter.md) has the shape if you would rather write it yourself.
+**Do:** on the setup screen, **Copy the prompt** puts a brief on your clipboard with every file
+it refers to inside it; paste the reply back and you get a diff and a save button. `roster brief
+discover` prints the same brief. Then write `org/priorities.md`: a few ranked lines on what
+matters this month.
 
-**Why not automated:** same reason, one level down. The charter is what makes a staff member
-different from the others.
+Health reports `business.stub` and `priorities.stub` while either is still the stub.
 
-**If you skip it:** `charter` reports it as present, because the stub is a file. `charter.stub`
-is the finding that says nobody has answered it. The agent has no personality and produces
-whatever the shared layer implies.
+**Why not automated:** an agent that does not know the business writes work that is plausible
+and generic. That is worse than no work, because it takes longer to notice.
 
----
+**If you skip it:** nothing errors. That is the problem.
 
-## 7. Commit and push what roster wrote into other repos
+---
 
-**Do:** hiring writes a whole brain repo and pushes it, so this is mostly about `roster
-upgrade`, which writes into repos on disk and leaves them for you. Review, commit, push.
+## 7. Write each staff member's `CHARTER.md`
 
-Hiring from the Staff screen still edits the *other* staff members' manifests on disk to wire the
-peers both ways, and those are yours to commit.
+**Do:** **Write the charter** on that staff member's card, the same round trip as item 6. The
+brief carries the org layer, `business.md`, the peers' charters, and where the role matches one,
+a [worked example](writing-a-charter.md#worked-examples) to model the shape on. `roster brief
+charter <handle>` prints the same brief.
 
-**Why not automated:** roster does not commit on your behalf into repositories it did not
-create in that command. And **App tokens cannot push a change under `.github/workflows/` in any
-repository**, which is a GitHub restriction and not a configuration mistake. That is also why
-agents can never update their own workflows, and why upgrades are human-run by design.
+**Why not automated:** the charter is what makes a staff member different from the others, and
+a generated one is the generic agent this arrangement exists to avoid.
 
-**If you skip it:** the change exists locally and nowhere else. `roster upgrade` will report it
-as still pending next time, which is the intended behaviour.
+**If you skip it:** `charter.stub` says nobody has answered it, and the agent produces whatever
+the shared layer implies.
 
 ---
 
-## Order
+## 8. Commit what `roster upgrade` wrote
+
+**Do:** review, commit and push what `roster upgrade --apply` changed in the brain repos.
 
-For a new organisation:
+**Why not automated:** **App tokens cannot push a change under `.github/workflows/`**, in any
+repository. That is a GitHub restriction, and it is why agents never update their own workflows
+and upgrades are run by a person. Hiring commits its own changes as you, and lists them first.
 
-In the portal it is the screen you are looking at, in this order:
+**If you skip it:** the change exists locally and nowhere else, and `roster upgrade` reports it as
+pending next time.
 
-```
-the setup screen                         1 is deep-linked from it, and 5 is on it
-Staff -> Hire someone                    then 7
-GitHub App, on the new staff card        2, then 3
-Write the charter, on the same card      6
-                                         4 is yours: a secret on the brain repo
-Health                                   until the ids are gone
-```
+---
 
-From a terminal:
+## What roster does for you
 
-```
-roster init --org <org> --apply          # 1 applies here
-roster hire <handle> --apply             # then 7
-roster app <handle>                      # 2, then 3
-# 4, 5, 6
-roster doctor <handle>
-```
+Each of these is a step of a command, listed in its plan before it happens, and each falls back
+to telling you exactly what to click if GitHub refuses.
 
-Then trigger one run by hand before trusting the schedule. A workflow that has never run has
-proved nothing.
+| | |
+|---|---|
+| The ops repo's Actions access | `roster init --apply`, or **Set it for me** on the setup screen. Needs admin on the ops repo. Skipped, every caller fails with "workflow not found". |
+| Committing peer wiring | `roster hire --apply` commits and pushes each peer's `staff.yaml` and `org.yaml` as you. A push that fails is reported and left for you. |
+| Giving each new brain the credential | `roster hire --apply` adds the repo to the org secret. |
+| Choosing repos on the install page | pre-selected, as above. |
+| The review gate on product repos | `roster hire --apply` adds it where there is none. See [security](security.md#the-review-gate). |

package/docs/memory.md

@@ -16,8 +16,8 @@ memory/INDEX.md      one line per fact. Read in full at every boot.
 memory/notes/*.md    the argument behind a fact. Read only when that fact is in play.
 ```
 
-That split is the whole design. Boot context here went from about 52,000 words to about 6,000
-by making it, and the saving repeats on every run forever.
+That split is the whole design. Boot context here went from about 52,000 words to about 10,000
+today by making it, and the saving repeats on every run forever.
 
 ## The grammar
 
@@ -48,10 +48,27 @@ rumour.
 Rule 5 is the one that gets skipped and the one that matters. Everything else degrades slowly;
 this one degrades the boot cost of every future run.
 
+## Budgets
+
+Prose is advice, and an index nobody prunes grows past what a run can usefully read. So
+`roster lint` warns past three budgets:
+
+| Budget | Default | Rule |
+|---|---|---|
+| One fact's line | 400 characters | `too-long`, naming the fact |
+| `memory/INDEX.md` | 24KB | `index-too-big`, naming the three longest facts |
+| `log/decisions.md` | 24KB | `decisions-too-big`: roll older entries into `log/decisions/<YYYY-MM>.md` |
+
+Change them under `memory:` in [org.yaml](org-yaml.md#memory), or per staff member in
+[staff.yaml](staff-yaml.md#memory). The daily prompt tells a staff member to check its sizes at
+hand-off and make pruning that run's job when it is over.
+
 ## What does not go in memory
 
 - **Why something was decided.** That is `log/decisions.md`, and it is not boot context.
 - **How a thing works.** That is a draft or a strategy document.
+- **An idea not yet acted on.** That is one line in `strategy/ideas.md`, and it becomes an issue
+  only when it needs a ruling.
 - **What is outstanding.** That is the pinned status issue.
 
 Nothing is copied between them. Four places, four jobs, and a fact that appears in two of them
@@ -64,7 +81,8 @@ opens an issue in that staff member's own repository asking them to fix it, whic
 right move: they wrote it, and an issue on their tracker is a thing that wakes them.
 
 It catches: a missing `So:`, a duplicate slug, a note nothing links to, a link to a note that
-does not exist, an over-long line, a `[measured]` fact with no `n`, and an "updated:" chain.
+does not exist, an over-long line, a `[measured]` fact with no `n`, an "updated:" chain, and an
+index or decision log over its budget.
 
 The same checks, for a terminal or for CI:
 

package/docs/org-yaml.md

@@ -34,10 +34,12 @@ agent:
   permissions: full
 
 defaults:
-  model: claude-opus-5
+  model: claude-opus-5-5
   timeout_minutes: 90
   mention_timeout_minutes: 90
 
+budget: 300
+
 staff:
   - { handle: cto, dir: technology, name: Chief Technology Officer, schedule: "0 7 * * 1-5" }
   - { handle: cmo, dir: marketing, name: Chief Marketing Officer, schedule: "40 7 * * 1-5" }
@@ -58,6 +60,7 @@ repos:
 | `name` | yes | What the business is called, in prose. Appears in prompts. |
 | `ops_dir` | no | Directory name of the ops repo in the runner checkout. Defaults to `roster-ops`. |
 | `experiment_private` | no | Whether the fact that this org is agent-run is itself private. Read by the guardrails fragment. |
+| `budget` | no | USD over any trailing 30 days, for the whole org. See [below](#budget). |
 
 ### `human` and `humans`
 
@@ -123,6 +126,20 @@ Fallbacks for staff members who do not set their own.
 | `mention_timeout_minutes` | Ceiling on a mention run. Falls back to `timeout_minutes`, then `90`. |
 | `allowed_tools` | Claude's own spelling of a permission level, kept because it predates `agent.permissions` and still wins for the agents that take a tool list. Nothing translates it for the others: a list written for one agent is not a permission level for another. Prefer [`agent.permissions`](agents.md#permissions), which every agent understands. |
 
+### `memory`
+
+Budgets `roster lint` holds every staff member's memory to. All optional; a staff member's own
+[`memory:`](staff-yaml.md#memory) overrides these.
+
+```yaml
+memory:
+  max_fact_chars: 400     # one fact's line in memory/INDEX.md
+  max_index_kb: 24        # the whole index, read in full at every boot
+  max_decisions_kb: 24    # log/decisions.md
+```
+
+Over budget is a warning naming what to cut, never an error. See [memory](memory.md#budgets).
+
 ### `staff`
 
 The registry. One inline map per staff member. **This is the org's view of them**; the rest
@@ -134,10 +151,26 @@ lives in their own `staff.yaml`.
 | `dir` | no | Directory and repo name. Defaults to the handle. |
 | `name` | no | Role name in prose. |
 | `schedule` | no | Cron. Informational here; the caller workflow is what actually schedules. |
+| `budget` | no | USD over any trailing 30 days, for this staff member alone. |
 
 `roster hire` appends to this list. An empty list (`staff: []`) is valid and is what a fresh
 org has.
 
+### `budget`
+
+A number of dollars, on the org, on a staff entry, or both:
+
+```yaml
+budget: 300
+staff:
+  - { handle: cto, dir: technology, name: Chief Technology Officer, budget: 200 }
+```
+
+Spend over the trailing 30 days is added up from each run's record. Past a budget, `roster
+doctor` warns and the portal's Runs screen marks the total. **Nothing stops a run.** A cap that
+ends a session fails it after the work is done and committed, which is a false red rather than a
+saved penny; `timeout_minutes` is the real bound. See [cost](cost.md#budgets).
+
 ### `repos`
 
 Every repository the org owns, and what it is for.
@@ -159,7 +192,9 @@ Every repository the org owns, and what it is for.
 | `runner-plan.mjs` | `org`, `staff`, and each manifest's `works_in` and `peers` |
 | `agents.mjs` | `agent`, `staff` |
 | `roster hire` | all of it, plus every existing manifest |
-| `roster doctor` | all of it |
+| `roster doctor` | all of it, including `budget` |
+| `roster lint` | `staff`, `memory` |
+| `roster portal` | all of it; the Runs screen reads `budget` |
 
 ## Editing it
 

package/docs/portal.md

@@ -18,10 +18,9 @@ Keep the repos checked out beside each other, in the same shape the runner uses.
 
 ## The sidebar
 
-**The counts are right on load.** The badges beside Inbox and Pending work used to fill in only
-once something caused a render with an inbox already loaded, which in practice meant "after you
-visit the Inbox". A sidebar that says nothing until you look at it is not a sidebar. The page
-now asks once at boot, and the Inbox screen shares that request rather than making a second one.
+**The counts are right on load.** The badges beside Inbox and Pending work are fetched once at
+boot, and the Inbox screen shares that request rather than making a second one. A sidebar that
+says nothing until you look at it is not a sidebar.
 
 While the first answer is outstanding the badge is a placeholder rather than blank, because an
 empty badge reads as zero and zero is a different claim from "still counting". The screens
@@ -50,9 +49,15 @@ It asks GitHub which of two things this is:
   nothing is written until you apply. Same `initFiles` the CLI runs, so the browser and the
   terminal cannot disagree about what a new tenant contains.
 
-Then: the Actions setting, deep-linked to the exact page with the failure it causes if skipped;
-which repos the staff work in, as a picker over what your `gh` can see minus what `org.yaml`
-already has; and a prompt for writing `org/business.md`.
+Then what is left. **The Actions setting**, read on arrival: if it is not set, *Set it for me*
+asks GitHub to set it, and a refusal comes back with GitHub's reason and a link to the page to
+click. **The agent credential**: a paste box, a line on where your agent's credential comes from,
+and where it will be stored (one org secret shared with the brains, or each brain where an org
+secret would not arrive, with the reason). The value goes to the local server in a POST and from
+there to `gh` on standard input; it is never written to disk or echoed back. Until somebody is
+hired the box says so, because nothing would read it. Then which repos the staff work in, as a
+picker over what your `gh` can see minus what `org.yaml` already has, and a prompt for writing
+`org/business.md`.
 
 Nothing here stores which step you are on. Setup takes days rather than minutes: an App has to be
 installed, a credential set, a first run finished. So the page derives its state from `roster
@@ -80,9 +85,8 @@ down with the list, so opening a thread is a render rather than a request.
   silently doing nothing.
 - **A new issue asks one question: who is it for.** One dropdown, over the staff. It goes to
   that person's brain repo and their `@handle` is written into the body for you, because those
-  are the two things that make an issue reach an agent rather than sit there. It used to ask
-  for a staff member *and* a repo, which let you set the pair to a combination that woke
-  nobody. To file in a product repo instead, use GitHub: this form is for asking the staff for
+  are the two things that make an issue reach an agent rather than sit there. Asking for a
+  repo as well would let you pick a pair that wakes nobody. To file in a product repo instead, use GitHub: this form is for asking the staff for
   something.
 - **Labels are the repo's own, as toggles.** They are the labels that exist on the recipient's
   repository, fetched from GitHub and cached. A text box was a spelling test: `from-cmo` and
@@ -149,8 +153,7 @@ of every repo to show one of them is the wrong trade.
 second decision and not this button's to make. It runs `gh pr merge` as you, so a protected
 branch, a failing required check or a merge queue behaves exactly as it would on the site.
 
-**It does not ask how.** There used to be a squash / merge commit / rebase dropdown beside it.
-That is a question about git rather than about the pull request in front of you, the repository
+**It does not ask how.** Squash, merge commit or rebase is a question about git rather than about the pull request in front of you, the repository
 has already answered it in its own settings, and on any given repository most of the answers are
 wrong. So the repository is asked instead: squash where it is allowed, then a merge commit, then
 rebase.
@@ -160,8 +163,8 @@ rebase.
 **`@cto` on a pull request wakes nobody.** A staff member's caller workflow lives in their own
 brain repo and gates on their handle appearing *there*; on a product repo the same mention
 posts, renders as a chip, and does nothing. That is deliberate, for the reasons in
-[security](security.md#trust-in-a-prompt), and it used to be silent, which is worse than the
-restriction itself.
+[security](security.md#trust-in-a-prompt). Saying so out loud is the portal's job, because a
+silent no-op is worse than the restriction itself.
 
 **Reply is the one box, and it handles this.** Name somebody in a reply where a comment will
 not reach them and the offer appears under the box, ticked: *open it on their tracker too*. One
@@ -183,16 +186,30 @@ On the **Files** tab each file's heading has its own Reply, which opens the same
 one file. "This bit is wrong" is what you want to say while looking at a diff, and the
 alternative is describing in prose which of thirty files you meant.
 
-There was briefly a second button up here called *Ask a staff member*. It did almost the same
-thing as Reply, differing mainly in making you pick a name from a dropdown rather than typing
-it, and nothing on the page said which one you wanted. Two ways to do one thing is worse than
-either of them.
-
 Both writes go through your own `gh`, as you. Nothing is dispatched between repositories and no
 credential is put on a public repo. The tracker issue goes first, because it is the half that
 reaches anybody; if the copy on the pull request then fails you are told, rather than being
 shown an error that invites you to ask the same person the same thing twice.
 
+## Runs
+
+What each staff member ran in the last 30 days: when, daily or mention, how it ended, how long
+it took, turns and cost where known, and a link to the log. Above the tables, the 30-day total
+for the org, and each staff member's own in their heading.
+
+Runs are not in any repo, so this is the one screen that is only ever on GitHub. It reads the
+run lists through your own `gh`, the same way the inbox does, and offline it says so rather
+than drawing an empty table that reads as "nothing ran".
+
+Cost comes from the record each run leaves behind (see [cost](cost.md#what-each-run-cost)). A
+run from before records existed, or from an agent that does not report cost, shows a dash, and
+a total says how many runs it could price. Each record is downloaded once and kept for as long
+as the portal runs, so the first visit is the slow one.
+
+A skipped mention is not a run and is not listed. A `setup-failure` is a run that failed before
+the agent started, usually a token or a checkout. Past a [`budget`](org-yaml.md#budget), the
+total turns amber.
+
 ## Org
 
 The layer every staff member inherits, in one place: `org.yaml`, every `org/*.md`, and the
@@ -200,9 +217,8 @@ prompt files in `prompts/`, each with a line saying what it is for, because a fi
 you nothing about which to open. Anything roster does not ship falls back to its own first
 heading.
 
-**The list comes off disk**, not out of the page. It used to be five paths written into the
-portal, so a tenant that added `org/pricing.md` could not open it at all and one that had not
-written `org/business.md` yet got "not found" with nothing to do about it. Only files the
+**The list comes off disk**, not out of the page, so a tenant that adds `org/pricing.md` can
+open it like any other. Only files the
 portal may actually write are listed: an editor that offers a file it cannot save is a trap.
 
 Every one of them is editable from the screen it is read on: an **Edit** button on the file,
@@ -225,18 +241,20 @@ have more than one human, and a card that names one of two reads as the only one
 
 ## Staff
 
-Everyone on the roster, and the four things you could previously only do from a terminal.
+Everyone on the roster, and the things you would otherwise do from a terminal.
 
 **Hiring** runs the same `buildPlan` and `applyPlan` that `roster hire` does, on the server.
 Only the handle is required; everything else is copied from whoever is already here. You see
-the plan first, listing every file, every label, the schedule it chose and why, and the manual
-steps it cannot do for you. Nothing happens until you apply. What the terminal would have
-printed is shown when it finishes.
+the plan first, listing every file, every label, the schedule it chose and why, the commits it
+will make as you in repos that already exist (each peer's `staff.yaml`, `org.yaml`), whether the
+new brain joins the credential's org secret, and what is left for you. Nothing happens until you
+apply. What the terminal would have printed is shown when it finishes.
 
 **Writing the charter** is the copy-a-prompt loop below, aimed at `CHARTER.md`. `hire`
 deliberately does not write it, because a generated charter produces exactly the generic agent
-this whole arrangement exists to avoid. So this is the route that was previously `roster brief
-charter <handle>` and a terminal.
+this whole arrangement exists to avoid. It is the same brief as `roster brief charter
+<handle>`, with somewhere to put the answer, and a picker for the worked example it carries as a
+model: matched to the role, or another, or none.
 
 **The GitHub App** is `roster app`, on this server rather than a second one. There is no API that
 creates an App: the only route is the manifest flow, where you post a manifest to a settings page,
@@ -246,9 +264,17 @@ one origin. The private key is still held in memory and written straight to a re
 
 GitHub redirects the tab *it* opened, not the one you clicked from, so the original polls for the
 result. 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 and should not be worked around. The panel
-says so loudly, and says to grant every tracker the staff member writes to rather than only their
-own.
+and GitHub asks a person to confirm it, which is correct and should not be worked around. So the
+panel's **Install it** opens the install page with the org and the repos already selected: the
+brain, every peer tracker it writes to, and the product repos. Any whose id could not be read are
+listed for you to tick.
+
+**Agent credential** is the setup screen's paste box, reachable from each card, because the
+moment you look for it is while setting somebody up. It is once for the org.
+
+**Run once now** starts the daily workflow, follows it, and shows how it ended with the log's
+link and, on a failure, the step it failed at. It asks first, because it is a real run. A success
+is what turns doctor's *unproven* into proven. Health has the same button.
 
 **Retiring** is `roster retire`, and it is deliberately not deletion. A brain repo is that
 agent's entire memory and there is no undo, so retiring disables the workflows, unwires them
@@ -284,8 +310,8 @@ rather than going nowhere.
 
 ## Prompt
 
-**What this staff member is actually sent**, which was previously only reachable through
-`roster prompt <handle> --kind daily` in a terminal. Composed on the server by the tenant's own
+**What this staff member is actually sent**, the same as `roster prompt <handle> --kind daily`.
+Composed on the server by the tenant's own
 `compose.mjs`, so there is no second implementation to drift.
 
 Pick the kind: `daily` or `mention`. A mention prompt is written for the comment