@nanocollective/roster 0.1.0-alpha.3 → 0.1.0-alpha.4

package/docs/README.md

@@ -11,7 +11,7 @@ An agent-run organisation, powered by GitHub.
 A staff member is a private repository. The repo *is* the brain: what it knows, what it is
 working on, what it has decided. A scheduled workflow wakes it each morning, hands it a prompt
 composed from the org's shared rules plus its own charter, and it does a day's work and hands
-off. You read the result on GitHub, or in a local portal.
+off. You read the result in a local portal, or on GitHub.
 
 roster is the thing that sets that up and keeps it consistent.
 
@@ -22,18 +22,18 @@ Read in this order.
 | | |
 |---|---|
 | [Getting started](getting-started.md) | One command, in a browser: stand up an org, or join one that exists. |
+| [The portal](portal.md) | Where the work happens: setup, every screen, every action. |
 | [Manual steps](manual-steps.md) | Every human action, why it cannot be automated, and what breaks if you skip it. **Read this one.** |
 | [Concepts](concepts.md) | What a charter, a manifest, a surface and the ops repo are. |
 | [Choosing a coding agent](agents.md) | Claude, Codex, Nanocoder, or anything with a command line. |
 | [Writing a charter](writing-a-charter.md) | The one file nothing can generate for you. |
 | [Extending it](extending.md) | The four seams, and which one to reach for. |
 | [Memory](memory.md) | The grammar, and why deleting is the maintenance. |
-| [Commands](commands.md) | Every CLI command and flag. |
-| [The portal](portal.md) | Setup, every view, and every action. |
 | [Upgrading](upgrading.md) | How framework changes reach a tenant without eating your edits. |
 | [Troubleshooting](troubleshooting.md) | Every trap we have actually hit, and what it looks like. |
 | [Hosting the portal](hosting.md) | Local is the default, and why. |
 | [Cost](cost.md) | What this spends, and on what. |
+| [Commands](commands.md) | Every CLI command and flag, for when you want the terminal. |
 
 ## Reference
 
@@ -45,7 +45,6 @@ Look things up.
 | [`staff.yaml`](staff-yaml.md) | Every field in a staff member's manifest. |
 | [Prompts](prompts.md) | The template syntax, the context, and what to guard. |
 | [The session workflow](session-workflow.md) | Inputs, secrets, and what runs in what order. |
-| [The portal](portal.md) | Every view and every action. |
 | [`roster export`](export.md) | The JSON shape. |
 | [doctor codes](doctor-codes.md) | Every finding, what it means, what to do. |
 
@@ -81,7 +80,7 @@ Nano-Collective/roster          the framework. Never a runtime dependency of any
   ├── staff.yaml                the machine-readable half of the charter
   ├── memory/INDEX.md           one line per fact, read at every boot
   ├── memory/notes/             the argument behind a fact, read on demand
-  └── .github/workflows/        three callers, about forty lines each
+  └── .github/workflows/        two callers, about forty lines each
 ```
 
 **The framework never runs anything.** It writes templates out; a tenant runs its own copies.
@@ -97,3 +96,9 @@ deleted, and an air-gapped install is a supported case rather than a special one
 - **Write `org/business.md`.** Everything the staff say is downstream of it.
 - **Install a GitHub App.** Installing grants access to specific repositories and GitHub asks a
   human which. See [manual steps](manual-steps.md).
+
+None of those is a dead end. roster holds no model credential, so for the first two the portal
+does both halves of the round trip instead: it copies a brief that carries every file it refers
+to, and turns the reply you paste back into a file with a diff and a save button. For the third
+it runs everything either side of the confirmation GitHub insists a human gives, and tells you
+exactly which repositories to grant.

package/docs/agents.md

@@ -21,19 +21,56 @@ That is the whole interface. Everything else is a convenience.
 
 ## Picking one
 
-In `org.yaml`:
+In `org.yaml`. This block is the whole surface: choose an agent, say how much freedom it gets,
+and pass anything else through in that agent's own words.
 
 ```yaml
 agent:
   id: codex
+  permissions: full        # full | workspace | read-only
+  options:                 # optional, and in codex's vocabulary rather than roster's
+    model_reasoning_effort: high
 ```
 
-Or the short form, which is the same thing:
+The short form is the same thing with the defaults:
 
 ```yaml
 agent: codex
 ```
 
+### `permissions`
+
+One word here, because "how much may this thing do without asking" is a question about your
+org rather than about a vendor. Each agent hears it in its own vocabulary:
+
+| | `read-only` | `workspace` | `full` |
+|---|---|---|---|
+| **claude** | `--allowedTools Read,Glob,Grep,WebFetch,WebSearch` | the same plus `Bash,Write,Edit` | plus `WebFetch,WebSearch` |
+| **codex** | `--sandbox read-only` | `--sandbox workspace-write` | `--sandbox danger-full-access` |
+| **nanocoder** | `--mode plan` | `--mode auto-accept` | `--mode yolo` |
+
+`full` is the default and is what a daily session needs: the whole point of a run is that it
+edits the checkout, commits and pushes. `workspace` keeps it off the network. `read-only` is
+for a staff member you are not ready to trust yet, and it is genuinely read-only in all three:
+nanocoder's `plan` mode reasons and proposes and edits nothing.
+
+Codex also gets `approval_policy="never"` at every level. A sandbox that permits writes still
+stops to ask by default, and a run that stops to ask at 07:00 is a run that times out having
+done nothing.
+
+A staff member can be trusted less than the org:
+
+```yaml
+# marketing/staff.yaml
+permissions: workspace
+```
+
+### `options`
+
+Anything roster does not model, in the agent's own words, spelled onto its command line by the
+preset: `-c key=value` for codex, `--key value` for the others. It is the escape hatch that
+means a flag roster has never heard of is still reachable without waiting for us.
+
 A staff member can override it in their own `staff.yaml`, which is worth doing when roles
 differ in kind. A research role on a long-context model and an engineering role on a coding
 model is a reasonable thing to want:
@@ -61,7 +98,15 @@ agent: claude-code-action
 
 - credential: `CLAUDE_CODE_OAUTH_TOKEN`
 - default model: `claude-opus-5`
-- tool permissions come from `allowed_tools` on the caller
+- tool permissions come from `allowed_tools` on the caller, which roster renders from
+  `defaults.allowed_tools` in org.yaml
+
+That allowlist is Claude's own vocabulary, and it is the one setting on this page that does not
+translate. Codex takes a sandbox mode rather than a tool list; nanocoder takes a development
+mode. Both presets therefore ignore `$AGENT_TOOLS` entirely, and neither is any less restricted
+for it: what bounds them is the sandbox flag in their own `run` command. If you switch agents,
+`allowed_tools` stops being the thing that governs what the agent may touch, and the `run`
+command becomes it.
 
 It is the only preset that is a GitHub Action rather than a CLI. `uses:` in a workflow cannot
 be an expression, so an Action-based runner has to be written into `session.yaml` literally.
@@ -97,7 +142,8 @@ produces a run that succeeds having done nothing. If you would rather keep it na
 
 ```
 install:   npm install -g @nanocollective/nanocoder
-run:       nanocoder --model "$AGENT_MODEL" --mode yolo --trust-directory --plain run "$(cat "$AGENT_PROMPT_FILE")"
+run:       NANOCODER_PROVIDERS_FILE="${NANOCODER_PROVIDERS_FILE:-roster-ops/agents.config.json}" \
+             nanocoder --model "$AGENT_MODEL" --mode yolo --trust-directory --plain run "$(cat "$AGENT_PROMPT_FILE")"
 token_env: NANOCODER_API_KEY
 ```
 
@@ -105,8 +151,234 @@ Three flags matter for unattended use. `run` is its non-interactive mode. `--tru
 skips the first-run directory trust prompt, which would otherwise hang the runner until it
 times out. `--plain` avoids the TUI, which has nothing to draw to in CI.
 
-Nanocoder resolves a provider from `agents.config.json` in the working directory, so you will
-want that file in the brain repo, and the provider's own key in `token_env`.
+**Nanocoder needs one thing the other two do not: a provider.** It is a client rather than a
+model, so `NANOCODER_API_KEY` on its own tells it nothing about where to send anything. That is
+what the config file is for, and it is the part of this that catches people out. It has its own
+section: [wiring up nanocoder](#wiring-up-nanocoder).
+
+## Setting one up, end to end
+
+The preset only says how to invoke the agent. Three more things have to be true before a run
+works, and Health, or `roster doctor`, checks all three.
+
+### 1. The credential exists, and you have it
+
+| Agent | Where the credential comes from |
+|---|---|
+| `claude-code-action`, `claude` | `claude setup-token` in a terminal where Claude Code is signed in. It prints a long-lived OAuth token. A plain Anthropic API key also works if you would rather bill that way. |
+| `codex` | an API key from the OpenAI platform console. `codex login` is for interactive use and does not produce something a runner can hold. |
+| `nanocoder` | whatever the provider you point it at wants. Nanocoder is a client, not a model: the key belongs to the provider in `agents.config.json`. |
+
+### 2. It is a secret on every brain repo, under the right name
+
+Each staff member's caller workflow reads the secret **from their own repo**, so the credential
+goes on each brain, not on the ops repo:
+
+```bash
+gh secret set CODEX_API_KEY --repo playpip/technology --body "$KEY"
+gh secret set CODEX_API_KEY --repo playpip/marketing  --body "$KEY"
+```
+
+The name is the preset's `token_env`, and it is the same name the caller references. If you
+override `token_env`, the callers have to be regenerated so they reference the new name:
+`roster upgrade --apply`.
+
+Inside the run it arrives twice: as `AGENT_TOKEN`, which is what the caller passes, and under
+the agent's own `token_env`, which is what the agent reads. That indirection is why a preset
+change does not require touching `session.yaml`.
+
+### 3. The agent's own config, if it has one
+
+`claude` and `codex` need none: they are a model and a client in one thing, and the model comes
+from `$AGENT_MODEL`. `nanocoder` needs a providers file, below.
+
+### Then prove it
+
+```bash
+roster doctor                    # secrets present, callers reachable, prompts compose
+gh workflow run cto-daily.yaml --repo playpip/technology
+```
+
+Read the log of that first run rather than waiting for the schedule. What goes wrong is
+specific to the agent and obvious in the log: an unknown flag, a sandbox that refuses to write,
+a model id the provider does not recognise, a first-run prompt waiting for a keypress that will
+never come.
+
+## Three worked examples
+
+An org called `acme` with two staff members, `cto` in `acme/technology` and `cmo` in
+`acme/marketing`. Every file each one touches, in full.
+
+### Claude, through the Action
+
+```yaml
+# roster-ops/org.yaml
+org: acme
+agent:
+  id: claude-code-action      # the default; the whole block can be left out
+
+defaults:
+  model: claude-opus-5
+```
+
+```bash
+claude setup-token            # prints a long-lived token
+gh secret set CLAUDE_CODE_OAUTH_TOKEN --repo acme/technology --body "$TOKEN"
+gh secret set CLAUDE_CODE_OAUTH_TOKEN --repo acme/marketing  --body "$TOKEN"
+```
+
+Nothing else. No file in the brain repos, no per-staff config.
+
+### Codex
+
+```yaml
+# roster-ops/org.yaml
+agent:
+  id: codex
+  permissions: full           # --sandbox danger-full-access, approval_policy never
+
+defaults:
+  model: gpt-5-codex          # what $AGENT_MODEL becomes
+```
+
+```bash
+gh secret set CODEX_API_KEY --repo acme/technology --body "$OPENAI_KEY"
+gh secret set CODEX_API_KEY --repo acme/marketing  --body "$OPENAI_KEY"
+roster upgrade --apply        # repoints the callers at the new secret name
+```
+
+Commit and push the regenerated callers. The secret name changed from
+`CLAUDE_CODE_OAUTH_TOKEN` to `CODEX_API_KEY`, and that name is written into each caller.
+
+### Nanocoder
+
+Two files rather than one, because a provider has to be named.
+
+```yaml
+# roster-ops/org.yaml
+agent:
+  id: nanocoder
+  permissions: full           # --mode yolo
+
+defaults:
+  model: qwen/qwen3-coder     # must be one of the models listed below
+```
+
+`roster init --agent nanocoder` writes this file for you, with the blanks marked. Fill them in:
+
+```json
+// roster-ops/agents.config.json
+{
+  "nanocoder": {
+    "providers": [
+      {
+        "name": "openrouter",
+        "baseUrl": "https://openrouter.ai/api/v1",
+        "apiKey": "${NANOCODER_API_KEY}",
+        "models": ["qwen/qwen3-coder"]
+      }
+    ]
+  }
+}
+```
+
+```bash
+gh secret set NANOCODER_API_KEY --repo acme/technology --body "$OPENROUTER_KEY"
+gh secret set NANOCODER_API_KEY --repo acme/marketing  --body "$OPENROUTER_KEY"
+roster upgrade --apply
+```
+
+Commit `agents.config.json` and the regenerated callers. **The key is not in the file.**
+`${NANOCODER_API_KEY}` is expanded from the environment when nanocoder reads it, and the
+environment is where roster puts the secret.
+
+## Wiring up nanocoder
+
+The other two presets are one thing. Nanocoder is a harness you point at a model, so it needs
+to be told which model, from whom, at what URL, with which key. That is `agents.config.json`.
+
+### Where it looks
+
+In order, and the first hit wins:
+
+1. `$NANOCODER_PROVIDERS`: the JSON itself, in an environment variable.
+2. `$NANOCODER_PROVIDERS_FILE`: a path to the JSON. Ignored if the file is not there.
+3. `agents.config.json` in the **working directory**.
+4. `agents.config.json` in the user config directory (`~/.config/nanocoder/` on Linux,
+   `~/Library/Preferences/nanocoder/` on macOS).
+
+Options 3 and 4 are what you use at your own desk, and neither of them works in a session. The
+working directory of a run is the **workspace root**: the directory the repos are checked out
+*into*, one level above `technology/` and `roster-ops/`. It belongs to no repository, so there
+is nothing there to commit a config into. And the user config directory on a fresh GitHub
+runner is empty.
+
+That is why roster's preset sets option 2 for you:
+
+```
+NANOCODER_PROVIDERS_FILE="${NANOCODER_PROVIDERS_FILE:-roster-ops/agents.config.json}"
+```
+
+The ops repo is checked out at a known path on every run, and it is the one repo every staff
+member has. So the org's providers live in one version-controlled file, and each staff member
+picks a model from it with `model:` in their own `staff.yaml`.
+
+### The shape
+
+Either of these; the wrapper is what nanocoder writes itself, the bare form is accepted too.
+
+```json
+{ "nanocoder": { "providers": [ … ] } }
+{ "providers": [ … ] }
+```
+
+A provider is:
+
+| Field | |
+|---|---|
+| `name` | what `--provider` and the model list refer to. Any string. |
+| `baseUrl` | the OpenAI-compatible endpoint. Omit for a provider the SDK already knows. |
+| `apiKey` | the credential. Use `${VAR}`, never a literal, in a file you are committing. |
+| `models` | the models this provider offers. **If it is non-empty, `$AGENT_MODEL` must be one of them**, or the run fails with "Model not available for provider". |
+| `sdkProvider` | `openai-compatible` (default), `anthropic`, `google`, `chatgpt-codex`, `github-copilot`. |
+
+`${VAR}` and `$VAR` are both expanded, anywhere in the file, with `${VAR:-fallback}` for a
+default. That is what lets a committed config carry no secrets.
+
+### A local model
+
+Nothing says the provider has to be remote. Ollama on a self-hosted runner needs no key at all:
+
+```json
+{
+  "providers": [
+    {
+      "name": "ollama",
+      "baseUrl": "http://localhost:11434/v1",
+      "models": ["qwen2.5-coder:32b"]
+    }
+  ]
+}
+```
+
+`token_env` still has to name a variable, because the session refuses to start an agent with no
+credential at all. Point it at something harmless and set it to any non-empty string:
+
+```yaml
+agent:
+  id: nanocoder
+  token_env: NANOCODER_API_KEY   # set it to "unused" on the brain repos
+```
+
+### When it goes wrong
+
+| In the log | What it means |
+|---|---|
+| `No agents.config.json found` | the file is not where nanocoder looked. Check it is committed to the ops repo at `agents.config.json`, and that `roster upgrade --apply` has been run so the caller carries the current preset. |
+| `No providers configured` | the file is there but `providers` is empty, or spelled as an object instead of an array. |
+| `Provider 'x' not found` | `--provider` names something the file does not define. |
+| `Model 'y' not available for provider` | `model:` in `org.yaml` or `staff.yaml` is not in that provider's `models` list. This is the common one: the roster default is a Claude model, and nanocoder is strict about the list. |
+| a run that hangs and then times out | a first-run prompt. The preset passes `--trust-directory` and `--plain` to avoid both known ones. |
 
 ## Writing your own
 
@@ -120,6 +392,19 @@ agent:
   token_env: MY_AGENT_TOKEN
 ```
 
+Five questions decide the `run` command, and they are the same five for every tool:
+
+1. **What is its non-interactive mode?** Most have one, and it is rarely the default:
+   `-p` for Claude, `exec` for Codex, `run` for nanocoder.
+2. **How does it take a long prompt?** Stdin (`< "$AGENT_PROMPT_FILE"`) if it accepts it, an
+   argument (`"$(cat "$AGENT_PROMPT_FILE")"`) if it does not. Never a literal.
+3. **What does it do with no TTY?** Anything that draws a full-screen interface needs the flag
+   that turns it off, or CI gets a run full of escape codes and no work.
+4. **Does it ask anything on first run?** Trust prompts, telemetry consent, a config wizard.
+   Each one hangs an unattended run until the job times out. Find the flag that skips it.
+5. **Is it allowed to write?** A sandbox that forbids edits produces a run that reports success
+   having done nothing, which is the worst failure this arrangement has.
+
 You can also override a single field of a preset, which is the common case when a flag changes:
 
 ```yaml
@@ -130,13 +415,34 @@ agent:
 
 The rest of the preset still applies.
 
+### Per staff member
+
+Anything the org sets, a staff member can override in their own `staff.yaml`. Roles that differ
+in kind are worth splitting: a research role on a long-context model, an engineering role on a
+coding one.
+
+```yaml
+# marketing/staff.yaml
+agent: nanocoder
+model: qwen/qwen3-coder
+```
+
+```yaml
+# technology/staff.yaml
+model: claude-opus-5    # keeps the org's agent, changes only the model
+```
+
+Two staff members on two different agents need both credentials present, each on its own brain
+repo, under each agent's own `token_env`. `roster doctor` reads the callers and tells you which
+secret each repo is missing.
+
 ## What the runner gets
 
 | Variable | |
 |---|---|
 | `$AGENT_PROMPT_FILE` | absolute path to the composed prompt |
 | `$AGENT_MODEL` | the staff member's model, or the agent's default |
-| `$AGENT_TOOLS` | the `allowed_tools` string from the caller |
+| `$AGENT_TOOLS` | the `allowed_tools` string from the caller, which comes from `defaults.allowed_tools` in org.yaml |
 | `$GH_TOKEN` | a token for the private trackers, already authenticated |
 | `$PUBLIC_TOKEN` | a token for the public product repo, if there is one |
 | *`token_env`* | the agent's credential, under whatever name it wants |
@@ -154,10 +460,15 @@ that only edits files and cannot run commands will produce a run that changes no
 ## Changing agent on a live org
 
 1. Set `agent:` in `org.yaml`.
-2. Put the new credential on each brain repo, named as `token_env`.
-3. `roster upgrade --apply`, then commit and push the regenerated callers.
+2. Put the new credential on each brain repo, named as `token_env`
+   (`gh secret set CODEX_API_KEY --repo <org>/<brain> --body "$KEY"`).
+3. `roster upgrade --apply`, then commit and push the regenerated callers. This is what
+   repoints them at the new secret name; skipping it leaves every run reaching for the old one.
 4. Trigger one run by hand and read the log before trusting the schedule.
 
+The old secret can stay where it is until the new agent has had a clean run. Nothing reads it
+once the callers have been regenerated, and it is the fastest way back if the first run is bad.
+
 Step 4 is not optional. Prompts are written against a model's habits as much as its
 capabilities, and the first run on a new agent is where you find out which parts of your
 charter were load-bearing.

package/docs/commands.md

@@ -48,7 +48,7 @@ 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,7 +58,6 @@ 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
@@ -144,7 +143,7 @@ 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
 --ops <dir>
 ```
@@ -177,14 +176,14 @@ 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>
 ```
 
-`mention` and `pr-mention` need trigger context:
+`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
 ```
 

package/docs/concepts.md

@@ -11,9 +11,10 @@ sidebar_order: 3
 `<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.
+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.
 
 **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
@@ -34,12 +35,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
@@ -67,7 +68,9 @@ org/operating.md + org/guardrails.md + org/voice.md + org/business.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 +86,25 @@ 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.
+
+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
+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).
 
 ## Identities
 

package/docs/cost.md

@@ -22,7 +22,8 @@ words to about 6,000 by moving from a narrative status file to one line per fact
 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.
 
 ## GitHub Actions minutes
 
@@ -57,5 +58,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/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,9 +25,12 @@ 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). |
@@ -54,7 +60,7 @@ ran at all.
 | `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 +69,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 |