@nanocollective/roster 0.1.0-alpha.1 → 0.1.0-alpha.11

package/docs/charters/support.md

@@ -0,0 +1,60 @@
+# Charter — Acme's Head of Support
+
+> **An example to adapt, not a template.** Acme is invented: a small company whose product is an
+> open-source scheduling app, `acme/acme-web`, run by one founder, Sam. Replace every specific
+> with your own. The shape is what has worked; the words have to be yours.
+
+*Who I am and what only I do. The shared half lives in `roster-ops/org/`. This file is the
+difference between me and the rest of the staff, and nothing else.*
+
+---
+
+## Who I am
+
+Acme's Head of Support. I make sure nobody who asks for help is left waiting, and that what
+people ask about reaches the staff who can fix the cause.
+
+## The mission
+
+**Every question answered, and every repeated question made unnecessary.** An answer fixes one
+person's day; a fixed doc or a filed bug fixes it for everyone after them.
+
+## How I work, that others here do not
+
+- **Oldest first.** Every run starts with the support queue, the `question` issues on
+  `acme/acme-web`, oldest unanswered at the top. Nothing sits past two working days without a
+  reply, even if the reply is "not yet, here is why".
+- **I draft replies; Sam sends them.** Each is a `reply` issue on my tracker with the exact text
+  and a link to the thread. He sends it or edits it.
+- **Three of the same question is a bug.** I file it on the CTO's tracker, labelled
+  `from-support`, with the three links. One-off questions do not become issues.
+- **Docs are mine to fix.** A wrong or missing answer in `acme-web/docs/` gets a PR from a branch.
+- **Weekly, one line per theme** in `strategy/themes.md`: what people asked about, how often. The
+  CMO reads it for copy; the CTO for priorities.
+
+## Decision rights
+
+| I do freely | I file an issue, then carry on |
+|---|---|
+| Drafting replies, and labelling support issues | Sending anything to a customer: a `reply` issue |
+| PRs to the docs | Refunds, credits, anything touching money |
+| Filing bugs for the CTO, and themes for the CMO | Anything involving a customer's personal data |
+| Closing my own issues when the thread is answered | Promising a fix or a date |
+
+## Guardrails on top of the org's
+
+1. **Never ask a customer for a password, a card number, or anything they would not post in
+   public.** Point them at the account page instead.
+2. **Never promise.** "The team is looking at it" is true; "fixed next week" is a commitment only
+   Sam makes.
+3. **Personal data stays out of my repo.** A theme is written without names or emails.
+
+## Where the rest of it lives
+
+| | |
+|---|---|
+| How I operate | `roster-ops/org/operating.md` |
+| What matters this month | `roster-ops/org/priorities.md` |
+| What people ask about | `strategy/themes.md` |
+| What I know | `memory/INDEX.md` |
+| What is outstanding | the pinned status issue |

package/docs/commands.md

@@ -6,8 +6,10 @@ sidebar_order: 8
 
 # Commands
 
-Every command prints a plan and changes nothing unless you pass `--apply`, except `lint`,
-`prompt`, `export` and `portal`, which never change anything at all.
+Every command that changes anything prints a plan and changes nothing unless you pass
+`--apply`. `lint`, `prompt`, `export`, `brief`, `doctor` and `fix` never change anything.
+`portal` is the exception: it is interactive, and each change there is a button you press after
+seeing what it will do.
 
 ## `roster fix`
 
@@ -44,11 +46,15 @@ Stand up a new tenant: the ops repo, the org layer, and the recorded merge base.
 --apply
 ```
 
+With `--apply` it also sets the ops repo's Actions access to "accessible from repositories in
+the organisation", which is what lets every brain call its workflow. If GitHub refuses (it needs
+admin on the repo), it prints the reason and the settings page to click instead.
+
 Will not write `org/business.md`. That is yours.
 
 ## `roster hire <handle>`
 
-Scaffold a staff member: repo, three callers, manifest, memory index, charter stub, labels,
+Scaffold a staff member: repo, two callers, manifest, memory index, charter stub, labels,
 pinned status issue, and peer wiring in both directions.
 
 ```
@@ -58,13 +64,23 @@ pinned status issue, and peer wiring in both directions.
 --model <id>
 --timeout <n>          daily ceiling, minutes
 --mention-timeout <n>
---pr-timeout <n>
 --secret-prefix <X>    secrets become <X>_APP_ID and <X>_APP_PRIVATE_KEY
 --app <slug>           defaults to the pattern the peers use
 --public-app <slug>    the shared public identity
+--no-review-gate       leave the product repos' branch rules alone
 --apply
 ```
 
+With `--apply` it also:
+
+- commits and pushes, as you, what it changed in repos that already exist: each peer's
+  `staff.yaml`, `org.yaml`, and the new `staff.yaml` once the status issue has a number. The
+  plan lists each commit first, and a push that fails is reported and left for you.
+- adds the new brain to the agent credential's org secret, if there is one, so the credential is
+  never asked for again. See [`roster credential`](#roster-credential).
+- adds a review-before-merge ruleset to each product repo that does not already require an
+  approving review. See [security](security.md#the-review-gate).
+
 ## `roster app <handle>`
 
 Create the GitHub App and put its credentials in the brain repo's secrets.
@@ -73,9 +89,55 @@ Create the GitHub App and put its credentials in the brain repo's secrets.
 --public       create the shared public identity instead
 --port <n>     localhost port for the hand-off. Default 4310.
 --no-open      print the URL rather than opening a browser
+--apply        actually create it; without it, prints the App name, secrets and repos
+```
+
+Cannot install the App: GitHub asks a person to confirm which repos it reaches. It prints a link
+to the install page with the org and every repo the staff member needs already selected (its
+brain, its peers' trackers, the product repos), so confirming is one click. The pre-selection uses
+`suggested_target_id` and `repository_ids[]`, which GitHub's own links use but does not document;
+when the ids cannot be read the link is the plain install page. See
+[manual steps](manual-steps.md).
+
+## `roster credential`
+
+Store the coding agent's credential once for the org.
+
+```
+--repo-secrets   a secret on each brain repo, even where an org secret would work
+--apply          read the credential and store it
+```
+
+By default it is one organisation secret, named after the agent's `token_env`, shared with every
+brain repo; `roster hire` adds each new brain to it. It uses a secret on each brain instead, and
+the plan says why, when an org secret would not arrive: on GitHub Free an org secret does not
+reach a private repo, and only an org owner can set one. Setting an org secret also needs the
+`admin:org` scope on your gh token (`gh auth refresh -h github.com -s admin:org`); if it is
+refused, the credential goes on each repo and the output says so.
+
+The value comes from standard input, or a prompt that does not echo, and goes to `gh` on its
+standard input. It is never on a command line and never on disk.
+
+```bash
+claude setup-token          # Claude Code; see docs/agents.md for the others
+roster credential --apply
 ```
 
-Cannot install the App. See [manual steps](manual-steps.md).
+## `roster run <handle>`
+
+Start one daily run now and follow it to the end.
+
+```
+--no-wait   start it and print the link, without following it
+--apply     start the run
+```
+
+Runs `gh workflow run <handle>-daily.yaml`, finds the run it started, and polls it until it
+finishes. It prints the outcome, the step it failed at if it did, and the log's link. A success
+is what `roster doctor` counts as proof that the App, its grant, the secrets and the callers all
+work, so its "unproven" warning goes away. It is a real run and spends what a scheduled one
+would, which is why it needs `--apply`. The staff card and Health have the same as
+**Run once now**.
 
 ## `roster retire <handle>`
 
@@ -125,7 +187,8 @@ Carry framework changes into the tenant. See [upgrading](upgrading.md).
 
 ## `roster lint [handle]`
 
-Check memory against the grammar. See [memory](memory.md).
+Check memory against the grammar, and warn when a fact, the index or the decision log is over
+its [budget](memory.md#budgets). See [memory](memory.md).
 
 ```
 --quiet   print only problems
@@ -144,8 +207,9 @@ amend <who>     change what a staff member is told, with the whole prompt attach
 ```
 
 ```
---kind <k>      for amend: daily | mention | pr-mention  (default: daily)
+--kind <k>      for amend: daily | mention  (default: daily)
 --want <text>   for amend: what you want changed
+--example <e>   for charter: cto, cmo, support or none (default: matched to the role)
 --ops <dir>
 ```
 
@@ -156,6 +220,11 @@ roster brief charter cto | pbcopy
 roster brief voice > /tmp/brief.md
 ```
 
+`charter` carries one of the [worked examples](writing-a-charter.md#worked-examples) as a
+model to adapt, matched to the role by handle or name. It is a model for the shape, not content
+to copy, and the brief still interviews you first. `--example` picks another; `--example none`
+leaves it out. The portal's copy-a-prompt has the same choice.
+
 `amend` is the different one. It carries the composed prompt and every file it is assembled
 from, so the agent you paste it into does not have to ask for any of them. The portal's Prompt
 screen builds the same thing, and offers it per audit finding.
@@ -177,14 +246,19 @@ roster brief discover > roster-ops/.claude/commands/discover.md
 Compose and print what a staff member is actually sent.
 
 ```
---kind daily|mention|pr-mention
+--kind daily|mention
 --diff <workflow.yaml>
+--inflight
 ```
 
-`mention` and `pr-mention` need trigger context:
+A run also carries the pull requests people have open on the product repos. `--inflight` reads
+them through your own `gh` and includes them; without it that section is left out, so the output
+does not move with somebody else's branch.
+
+`mention` needs trigger context:
 
 ```bash
-ROSTER_CONTEXT='{"issue_number":"1","comment_id":"1","pr_number":"1","repo":"o/r"}' \
+ROSTER_CONTEXT='{"issue_number":"1","comment_id":"1","repo":"o/r"}' \
   roster prompt cto --kind mention
 ```
 
@@ -197,8 +271,12 @@ which is the shortest way in.
 --port <n>    default 4300
 --host <a>    default 127.0.0.1. Anything else exposes write actions to the network.
 --dir <path>  where a tenant would be created or checked out. Default: here.
+--no-open     don't open a browser
 ```
 
+It opens the page in your browser when it starts. It stays closed in CI, over SSH, when output
+is not a terminal, or with `BROWSER=none`.
+
 **With no tenant where you started it, this is the setup screen**: it stands up a new org, or
 checks out one that already runs roster. Local only. See [the portal](portal.md).
 
@@ -206,7 +284,8 @@ Views: Inbox, Org, Staff, Docs, and per staff member Brain, Prompt, Graph, What
 
 It can act as you through your own `gh`: reply, close, reopen and open issues; hire and retire;
 edit and commit the org layer, prompt fragments and charters; create a staff member's GitHub App;
-and copy a prompt for authoring the two files nothing can generate.
+store the agent credential; set the ops repo's Actions access; start one run and follow it; and
+copy a prompt for authoring the two files nothing can generate.
 
 ## `roster export`
 

package/docs/concepts.md

@@ -6,23 +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. 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.
+**`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
+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.
@@ -34,12 +75,12 @@ A staff member's repository *is* their memory. There is no database.
 | `memory/INDEX.md` | one line per fact, read in full at every boot |
 | `memory/notes/` | the argument behind a fact, read only when that fact is in play |
 | `log/decisions.md` | why things were decided. Not boot context. |
-| `.github/workflows/` | three callers, about forty lines each |
+| `.github/workflows/` | two callers, about forty lines each |
 
 ## Charter and manifest
 
 Two halves of one thing. The charter is prose for the agent; the manifest is fields for the
-machinery. `roster lint` fails if they disagree.
+machinery. [Health](portal.md#health), and `roster lint`, fail if they disagree.
 
 The charter is the only file roster refuses to generate. A generated charter produces a generic
 agent, and a generic agent produces work that is plausible, competent-looking and about nothing
@@ -64,10 +105,12 @@ 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:
+Built at run time by `compose.mjs` in the tenant's own repo. See it for yourself on the
+[Prompt screen](portal.md#prompt), which shows the composed text and every layer that went into
+it, or from a terminal:
 
 ```bash
 roster prompt cto --kind daily
@@ -83,10 +126,19 @@ control.
 |---|---|
 | `daily` | the scheduled session. Boot, work, hand off. |
 | `mention` | `@handle` in a comment or a new issue body. A task, not a session. |
-| `pr-mention` | a review comment on the public product repo, forwarded in. |
 
-`mention` and `pr-mention` prompts refuse to compose without trigger context, because they are
-written for the comment that woke them. That is correct behaviour, not a bug.
+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.
+
+**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 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,17 +12,53 @@ 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. `roster doctor` reports the ratio.
+`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
 
@@ -57,5 +93,5 @@ on your machine when you ask it to, and the machinery is vendored into the tenan
   being raised is a session that has stopped fitting its job.
 - **Give a mention workflow a shorter ceiling than a daily one.** A focused task that runs for
   an hour has gone wrong, and the ceiling is the only thing that stops it.
-- **Check the ratio, not the last run.** `roster doctor` reports how many of the last ten runs
+- **Check the ratio, not the last run.** Health reports how many of the last ten runs
   succeeded. One bad run is noise; four is a bill.

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

@@ -6,6 +6,9 @@ sidebar_order: 19
 
 # doctor codes
 
+The portal's [Health](portal.md#health) screen shows these same findings, each with its fix, and
+turns the ones an agent could fix into a single brief. This page is the reference behind both.
+
 Every finding `roster doctor` can emit. Each carries a stable `id`, which is what
 `--json` reports and what to quote in an issue.
 
@@ -22,12 +25,21 @@ ran at all.
 |---|---|
 | `gh` | Whether `gh` is installed and authenticated. A warning here means every network check was skipped, not that anything is wrong. |
 | `org.yaml` | The org manifest parsed, and how much it declares. |
-| `human` | **fail.** `org.yaml` has no `human.github`. The mention callers gate on that login, so nothing can wake an agent. |
+| `human` | **fail.** `org.yaml` names nobody with a `github` login, in either `human` or `humans`. The mention callers gate on those logins, so nothing can wake an agent. |
+| `human.login` | One of the people in `humans` has a name but no `github` login. They read as somebody the staff answer to and are not: the gate can never match them. |
 | `repo` | Every repo in `org.yaml` is reachable. A failure means it does not exist or your `gh` cannot see it. |
 | `repo.visibility` | A repo's real visibility disagrees with what `org.yaml` records. Cosmetic, but the posture it records is then fiction. |
+| `agent` | Which runner this org uses, resolved from the tenant's own `agents.mjs`. **fail** if `org.yaml` names one it does not know. |
+| `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. |
@@ -49,12 +61,12 @@ 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. |
 | `runs` | A window of recent runs. See below. |
-| `runs.timeout` | **fail.** Runs were killed at a ceiling. |
+| `runs.timeout` | **fail.** Runs were killed at a ceiling. Drops to `ok` once the ceiling has been raised *and* a run has finished since the last kill: the fix is made and proved, and the old runs are history rather than a problem. |
 | `runs.cancelled` | Runs were cancelled short of any ceiling, with their durations. |
 
 ## Reading `runs`
@@ -63,8 +75,11 @@ This is the only check that proves the whole chain works, so it is worth underst
 
 - **"has never run"** is a warning, not an `ok`. Nothing has exercised the App grant or the
   secrets, so nothing is known.
-- **"all gated out before doing anything"** means every recent trigger was `skipped`. That is
-  normal for a mention workflow, but it means the credentials are still unproven.
+- **"all gated out"** means every recent trigger was `skipped`, which is a mention workflow's
+  normal state: every comment on the tracker fires it and the gate drops all but the real ones.
+  It is only a warning when *nothing* in that repo has finished a run, because the App grant
+  belongs to the repository rather than to the workflow, so one finished run proves it for all
+  of them.
 - **"ran to a Nm ceiling and were killed"** is a timeout. GitHub reports those as `cancelled`,
   so doctor identifies them by duration. If the ceiling it names differs from the one the
   caller sets today, it says so: those runs happened under the old setting.

package/docs/export.md

@@ -22,7 +22,8 @@ that reads it gets the same view without reimplementing the memory grammar.
 | `org` | the GitHub organisation |
 | `name` | the business name |
 | `opsName` | the ops repo's directory, so a consumer can address `org.yaml` and `org/*.md` by path |
-| `human` | the `human` block from `org.yaml` |
+| `human` | the first human, normalised: `{ github, name, marker, role }`. Kept for consumers written when an org had exactly one |
+| `humans[]` | everyone the staff answer to, in order, read from `humans` or the singular `human`. `human` is `humans[0]` |
 | `generatedAt` | ISO timestamp |
 | `staff[]` | one entry per staff member |
 

package/docs/extending.md

@@ -12,6 +12,11 @@ Four seams, in the order you are likely to reach for them.
 
 Edit `org/*.md` in the ops repo. It reaches every staff member on their next run.
 
+The [Org screen](portal.md#org) is exactly this seam: every one of these files listed off disk
+with a line saying what it is for, an Edit button, and a save that commits and pushes. The list
+comes off disk rather than being written into the page, so a file you add yourself is editable
+there too.
+
 | File | For |
 |---|---|
 | `business.md` | what the business is. The one everything else is downstream of. |
@@ -19,8 +24,8 @@ Edit `org/*.md` in the ops repo. It reaches every staff member on their next run
 | `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.
@@ -34,7 +39,6 @@ _identity.md    who you are posting as, and where
 _paths.md       where things are in the runner checkout
 daily.md        the scheduled session
 mention.md      a focused task from a comment
-pr-mention.md   a review comment forwarded from the product repo
 ```
 
 The syntax is small on purpose: `{{ path.to.value }}`, `{{> partial.md }}`,
@@ -54,7 +58,12 @@ A staff member can override a fragment for themselves. `{{>? staff:prompts/work.
 `daily.md` renders `prompts/work.md` from their own brain repo if it exists, and nothing if it
 does not. That is how one role gets a different working ritual without changing anybody else's.
 
-See what you actually built:
+See what you actually built on the [Prompt screen](portal.md#prompt), which walks the includes
+rather than listing them from memory, so a fragment you just added shows up on it, marked with
+the repo it came from. An optional fragment a role does not have is shown as absent rather than
+hidden. The layers are editable there too, subject to the writable list on that page.
+
+From a terminal:
 
 ```bash
 roster prompt cto --kind daily