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

package/docs/portal.md

@@ -18,10 +18,12 @@ 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.
+Anything that asks before it acts (a merge, a push, a hire, a retire, a paid run) asks in the
+page's own dialog, never the browser's `confirm()`, which blocks the whole tab.
+
+**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,26 +52,44 @@ 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, recorded with the
+visibility GitHub reports. Then the two files only you can write: a prompt for writing
+`org/business.md`, and `org/priorities.md` opened in place, stub and all, to replace with what
+matters this month. Each says whether it is written yet.
 
 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
-doctor` every time it is drawn. A stored step counter would disagree with the world within an hour.
+doctor` every time it is drawn, and runs the check again after anything on it is saved. A stored
+step counter would disagree with the world within an hour.
+
+### Getting started
+
+**Once the org exists, the same steps stay in the sidebar as *Getting started*** for as long as
+anything is left: nobody hired, or `org/business.md` or `org/priorities.md` still the stub. An
+org nobody has been hired into opens on it rather than on an empty Inbox, with *Hire your first
+staff member* first, then the Actions setting, the credential, the repo picker, both files, and
+what doctor still says. A link to another screen still wins. When the list is empty the entry
+goes away; the repo picker lives on under [Org](#org).
 
 ## Inbox
 
 Everything open across the org, from one GraphQL call per repo. Bodies and full timelines come
 down with the list, so opening a thread is a render rather than a request.
 
-- **Filter by staff member.** An item belongs to somebody if it is in their brain repo, their
-  own App wrote it, a peer addressed it to them with a `from-<handle>` label, or it is assigned
-  to them. The shared public identity cannot name one staff member, so an item it wrote counts
-  for anyone who works in that repo. Items authored by humans belong to nobody, which is
-  correct.
-- **Scope** to everything, what is assigned to you, decisions, or open PRs.
-- **Open, recently closed, or both.** Open by default: an inbox is what is waiting on
+- **The links under Inbox in the sidebar filter it.** All; Unread; each staff member, which
+  lists the issues on their own tracker whoever filed them; and Issues, the product repos.
+- **Unread comes from your GitHub notifications.** A thread with activity you have not read has
+  a bar on the left and a bold title, and Unread lists only those, with a count. Opening one
+  marks it read on GitHub too, and reading it on GitHub clears it here. GitHub only notifies you
+  about repos you watch and threads you are part of.
+- **Open or closed.** Open by default: an inbox is what is waiting on
   somebody, and months of finished work mixed into that answers a different question. Closed
   work reaches back 45 days, up to 30 issues and 30 pull requests per repository, and carries
   a shorter timeline than open work because it is there to be read rather than triaged. A
@@ -80,9 +100,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 +168,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 +178,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 +201,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 +232,12 @@ 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
+**Add a product repo** opens the same picker setup uses, so a repo created later does not mean
+typing `role: product` into `org.yaml` by hand. Adding one commits `org.yaml` and pushes. A new
+hire picks it up; somebody already hired keeps the `works_in` in their own `staff.yaml`.
+
+**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 +260,50 @@ 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.
-
-**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.
+Everyone on the roster, and the things you would otherwise do from a terminal.
+
+**Hiring** starts from a role. With nobody hired the Staff screen opens on the role picker;
+after that it is behind **Hire someone**. The cards are CTO, CMO and Support, each with a line
+on what they do, and **Something else**, which asks for the role's name and a sentence about it.
+A role that is already hired is not offered. Picking one fills in the handle, name and repo
+(`cto`, `cmo`, `support`, or a handle made from the name) and leaves the schedule empty, so the
+server picks a free slot. All four are under **Advanced**, still editable. The first hire has
+nobody to copy App names from, so Advanced also holds the App's name and the shared public
+App's, which are `--app` and `--public-app`, filled in as `<org>-<handle>` and `<org>-robot`.
+The public one only matters when a product repo is public; on private ones the session uses the
+staff member's own App.
+
+The role opens a numbered list on the same screen:
+
+1. **Hire.** One sentence from the plan: the repo it creates and when it runs. **Show details**
+   has the full plan, from the same `buildPlan` and `applyPlan` that `roster hire` runs on the
+   server: every file, every label, the schedule and why, the commits it makes as you in repos
+   that already exist (each peer's `staff.yaml`, `org.yaml`), and whether the new brain joins
+   the credential's org secret. **Hire** asks before it acts.
+2. **Create their GitHub App.** The private App, and the shared public one only when a product
+   repo in `org.yaml` is public (or has no visibility written, which hire treats as public).
+3. **Write their charter.** Three tabs: an AI interview (the default), the matching worked
+   example with your business's name in place of Acme's, and the file itself. A role that
+   matches no example has no template tab.
+4. **Add your agent credential.** Only while none is stored.
+5. **Run once now.**
+
+Steps 2 to 5 say *Hire first* until the hire is done. Each step's Done comes from real data:
+the hire from the staff member appearing in `org.yaml`, the charter from `CHARTER.md` no longer
+being the stub (the same test as doctor's `charter.stub`), the App from its `_APP_ID` secret on
+the brain repo, the credential from the org secret, and the run from a successful daily run.
+After **Hire** the screen reloads the org and stays on the same staff member, on step 2.
+
+A card whose setup is not finished (a stub charter, no App secrets, or no successful run yet)
+shows **Finish setting up**, which opens the same list for them. The App secrets and the run
+are read from GitHub, so offline only the charter counts.
 
 **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. For a role added with **Something else**, the
+sentence you typed goes into the brief.
 
 **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 +313,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 +359,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

package/docs/prompts.md

@@ -58,12 +58,12 @@ ROSTER_CONTEXT='{"issue_number":"1","comment_id":"1","repo":"o/r"}' \
 `comment_id`; a mention typed into the body of a *new* issue does not, and there is no comment
 for the agent to fetch. So `compose.mjs` derives `event.no_comment` from the absence, and
 `prompts/mention.md` branches on it: one side points at the comment, the other at the issue
-body. Without that, the first instruction in the prompt was a `gh api .../issues/comments/`
+body. Without that, the first instruction in the prompt would be a `gh api .../issues/comments/`
 call with no id on the end, which 404s.
 
-The second route is the busier one now. It is what the portal's [Ask a staff
-member](portal.md#asking-for-a-change) produces, and those issues often carry a pull request
-that lives somewhere else and say to answer there instead.
+The second route is the busier one. It is what the portal produces when you [ask for a
+change](portal.md#asking-for-a-change), and those issues often carry a pull request that lives
+somewhere else and say to answer there instead.
 
 ## Syntax
 
@@ -99,6 +99,12 @@ than a hang.
 | `ops.dir` | ops repo directory in the checkout |
 | `staff` | the whole of this staff member's `staff.yaml` |
 | `staff.dir` | where their brain lands in the checkout |
+| `staff.handle`, `staff.name` | their handle (`cto`) and role name (`Chief Technology Officer`) |
+| `staff.brain` | their brain repo, `owner/name` |
+| `staff.bot` | the login they post as on private repos, e.g. `acme-cto[bot]` |
+| `staff.public_bot` | the login they post as on public repos |
+| `staff.public_token_env` | the environment variable holding the public repo token during a run |
+| `staff.status_issue` | the number of their pinned status issue |
 | `staff.product` | **first entry of `works_in`, or null** |
 | `staff.product.repo` | that repo's `owner/name` |
 | `peers` | list of the other staff members |
@@ -108,10 +114,31 @@ than a hang.
 | `event` | trigger context, from `ROSTER_CONTEXT` |
 | `event.issue_number`, `event.comment_id`, `event.repo`, `event.actor` | |
 | `event.no_comment` | true when the ask is the issue body rather than a comment. There is no `{{#unless}}`, so the absence is a value |
+| `inflight` | the pull requests people have open on the product repos, as a markdown list. **Empty outside a run**, and when there are none. See below |
 
 Anything else in a manifest is reachable under `staff.`, so `staff.status_issue` and
 `staff.public_token_env` work without being listed here.
 
+## Human work in flight
+
+Before composing, a run looks at the staff member's product repos (their `works_in`, or every
+`role: product` repo) for open pull requests opened by people rather than by any App. Each one
+goes in as a line: title, author, age, branch, and the files it touches, capped at twenty with
+the top directories named when there are more.
+
+`prompts/_inflight.md` carries that list under a short instruction, inside `{{#if inflight}}`,
+and both kinds include it: do not open competing work on files a human branch is changing, and
+raise anything about it on that pull request instead.
+
+It exists because nothing else tells them. Without it, a person's long-running branch is
+invisible, and the staff open pull requests and issues chasing the same files, which the branch
+then overtakes.
+
+The list is a value, never a template. Titles are a person's words, and a `{{` in one must not
+be able to break composition, so `compose.mjs` reads `.roster-run/inflight.md` and substitutes it
+as it stands. Locally there is no such file, so `roster prompt` leaves the section out; pass
+`--inflight` to fetch the real list through your own `gh`.
+
 ## Guarding
 
 `{{staff.product}}` is null for a staff member with an empty `works_in`, and an unresolved

package/docs/security.md

@@ -45,6 +45,39 @@ whole organisation can reach anything in it.
 Install narrowly. The Staff card's **GitHub App** panel prints the list it actually needs, and
 so does `roster app`.
 
+## The review gate
+
+"Nothing goes out unread" is enforced by GitHub, not by the prompt. An App with
+`contents: write` on a product repo can push to its default branch, and with
+`pull_requests: write` it can merge its own PR, unless a rule on the branch says otherwise.
+
+The rule: **the default branch of every product repo requires a pull request with at least one
+approving review, and no staff App is on the list of who may bypass it.** A ruleset or classic
+branch protection both count.
+
+**It is off unless you turn it on**, with `review_gate: true` in `org.yaml`. Without it, staff
+are told to leave merging to you, and on Pip they always have, but GitHub does not stop them.
+Most orgs keep product repos private on the Free plan, where GitHub cannot enforce the rule.
+
+With it on, `roster doctor` reads it for every `role: product` repo in `org.yaml` and every repo a staff
+member `works_in`, as `review-gate`. It fails when nothing requires a PR or a staff App can
+bypass the rule, and warns when a PR is required with no approval, since then whoever opened
+it can merge it.
+
+With it on, `roster hire --apply` adds a ruleset named `roster: review before merge` to each product repo
+that does not already require an approving review, and leaves anything stricter alone. Pass
+`--no-review-gate` to skip it. The ruleset lets repository admins bypass it only by merging a
+pull request, so your own merge is still the approval (GitHub will not let you approve your
+own PR) and an App, which is never an admin, cannot merge at all.
+
+**On GitHub Free, private repos can't have this rule.** GitHub only enforces rulesets and
+branch protection on private repos for paid plans. To use the gate there, make the product repo
+public or move the org to GitHub Team.
+
+To set it by hand: repo **Settings -> Rules -> Rulesets -> New branch ruleset**, target the
+default branch, tick **Require a pull request before merging** with one required approval, and
+keep the staff Apps off the bypass list.
+
 ## Permissions a new App asks for
 
 ```
@@ -106,13 +139,12 @@ into a world-readable log.
 
 So a mention on a public pull request is decoration. It posts, it renders as a chip, and
 nothing happens, which is safe and also invisible. The portal is what makes it visible and what
-gets you out of it: replying with an `@handle` where nothing listens says so, and **Ask a staff
-member** opens the request on that person's own private tracker instead, carrying the pull
-request and the hunk. It writes through your own `gh`, as you, so no credential lives on the
+gets you out of it: replying with an `@handle` where nothing listens says so, and offers to
+open the request on that person's own private tracker as well, carrying the pull request and
+the hunk. It writes through your own `gh`, as you, so no credential lives on the
 public repo and nothing is dispatched across a boundary.
 
-There was once a forwarder in the product repo that bridged this automatically. It was removed;
-see [concepts](concepts.md#kinds-of-run). If you reinstate one, its author gate is
+If you add a workflow to a product repo that bridges this automatically, its author gate is
 load-bearing. Do not relax it.
 
 ## The loop guard

package/docs/session-workflow.md

@@ -14,8 +14,8 @@ A caller is about forty lines and does nothing but pass arguments.
 ## Why it lives in the tenant
 
 A reusable workflow in a **private** repo can only be called from inside its own organisation.
-A tenant therefore cannot call the framework's copy. That constraint is what forced the whole
-design, and it turned out better: the framework is never a runtime dependency, so nothing
+A tenant therefore cannot call the framework's copy. That constraint shapes the whole
+design, and it is the better one anyway: the framework is never a runtime dependency, so nothing
 breaks if it moves, goes private, or is deleted.
 
 This is also why `roster-ops` needs **Settings -> Actions -> General -> accessible from
@@ -28,7 +28,7 @@ repositories in this organisation**. Without it, callers fail with "workflow not
 | `staff` | string | required | Handle, as in `org.yaml`. |
 | `kind` | string | `daily` | `daily` or `mention`. |
 | `ops_repo` | string | required | `owner/name` of the ops repo. |
-| `model` | string | `claude-opus-5` | Passed to the agent, unless the agent resolves its own. |
+| `model` | string | `claude-opus-5-5` | Passed to the agent, unless the agent resolves its own. |
 | `timeout_minutes` | number | `90` | Job ceiling. |
 | `allowed_tools` | string | `Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch` | Tool permissions, for agents that take them. |
 | `issue_number` | string | `""` | Trigger context. |
@@ -51,23 +51,54 @@ authentication error forty lines into a log.
 
 ## What it does, in order
 
-1. **Mint the private-tracker token** from the staff member's App.
-2. **Mint the public-repo token**, if a public App was passed.
-3. **React to the request** with eyes, on a `mention` only. Before any checkout, so it lands in
+1. **Start the clock**, for the run record.
+2. **Mint the private-tracker token** from the staff member's App.
+3. **Mint the public-repo token**, if a public App was passed.
+4. **React to the request** with eyes, on a `mention` only. Before any checkout, so it lands in
    seconds. `continue-on-error`: a missing reaction must never cost the answer.
-4. **Check out the ops repo.** It is the only thing that can be cloned without having read a
+5. **Check out the ops repo.** It is the only thing that can be cloned without having read a
    manifest, so it goes first and then says what else to clone.
-5. **Work out what to check out**, by running `runner-plan.mjs`.
-6. **Check out the brain**, full history. The agent reads its own past.
-7. **Check out peers and product repos**, per the plan.
-8. **Set git identity** to the App.
-9. **Set up Node and pnpm**, if the plan found a `package.json`.
-10. **Compose the prompt**, to a step output and to `.roster-prompt.txt`.
-11. **Check the agent has a credential.**
-12. **Work out which agent runs this**, by running `agents.mjs`.
-13. **Run the session**, by one of two steps: the Action-based reference runner, or the generic
+6. **Work out what to check out**, by running `runner-plan.mjs`.
+7. **Check out the brain**, full history. The agent reads its own past.
+8. **Check out peers and product repos**, per the plan.
+9. **Gather human work in flight**: open pull requests people have on the product repos, via
+   `inflight.mjs`, for the prompt. Never fatal. See [prompts](prompts.md#human-work-in-flight).
+10. **Set git identity** to the App.
+11. **Set up Node and pnpm**, if the plan found a `package.json`.
+12. **Compose the prompt**, to a step output and to `.roster-prompt.txt`.
+13. **Check the agent has a credential.**
+14. **Work out which agent runs this**, by running `agents.mjs`.
+15. **Run the session**, by one of two steps: the Action-based reference runner, or the generic
     CLI one. See [choosing a coding agent](agents.md).
-14. **Say so if the run did not finish.**
+16. **Write down the run**, whatever happened: staff, kind, outcome, duration, and turns, cost
+    and tokens where the agent reports them. Into the job summary, and kept as an artifact
+    called `roster-run`. Never fatal. See [cost](cost.md#what-each-run-cost).
+17. **Say so if the run did not finish.** A comment on the status issue, or on the issue that
+    woke a mention, linking the run.
+
+## When the failure is the token
+
+The failure notice cannot rely on anything that might be what failed. A renamed repo, a rotated
+key or an uninstalled App breaks the App token first, and an alert that posts with that token
+says nothing at exactly the moment it is needed. So the notice uses the App token when there is
+one, and falls back to the job's own `github.token` when there is not or it is refused. It then
+posts as `github-actions`, and says to check the App.
+
+That needs `issues: write` on the job token. `session.yaml` asks for it, but a called workflow
+can only narrow what its caller grants, so both callers grant it too:
+
+```yaml
+jobs:
+  session:
+    permissions:
+      contents: read
+      issues: write
+    uses: acme/roster-ops/.github/workflows/session.yaml@main
+```
+
+Callers generated before this lack it, and their fallback cannot post. `roster upgrade --apply`
+regenerates them. `roster doctor` separately reports any other workflow in the ops or brain
+repos that has failed run after run, as `workflows.failing`.
 
 ## What `runner-plan.mjs` emits
 
@@ -92,6 +123,7 @@ Consumed by later steps as `steps.plan.outputs.*`.
 | `GH_TOKEN` | private-tracker token, already authenticated |
 | `PUBLIC_TOKEN` | public product repo token |
 | `AGENT_PROMPT_FILE` | absolute path to the composed prompt |
+| `AGENT_RESULT_FILE` | where to write the agent's own result JSON, if it has one. Optional; it is how cost gets into the run record |
 | `AGENT_MODEL` | resolved model |
 | `AGENT_TOOLS` | the `allowed_tools` string |
 | *the agent's own* | its credential, under whatever name it declares |

package/docs/staff-yaml.md

@@ -22,13 +22,13 @@ brain: acme/technology
 status_issue: 15
 
 schedule: "0 7 * * 1-5"
-model: claude-opus-5
+model: claude-opus-5-5
 timeout_minutes: 90
 mention_timeout_minutes: 90
 
 bot: acme-cto[bot]
 public_bot: acme-robot[bot]
-public_token_env: PIPWEB_TOKEN
+public_token_env: PUBLIC_TOKEN
 agent_secret: CLAUDE_CODE_OAUTH_TOKEN
 
 identities:
@@ -59,6 +59,7 @@ labels:
 | `handle` | yes | Must match `org.yaml`. The composer looks them up by the `org.yaml` one, so a mismatch composes the wrong brain. |
 | `name` | yes | Role name in prose. |
 | `mention` | yes | What wakes them, as in `@cto`. The caller's condition tests for this string. |
+| `icon` | no | The icon the portal shows for them: `code`, `megaphone`, `life-buoy`, `compass`, `brush`, `bug`, `server`, `book-open`, `bar-chart`, `users` or `person`. Unset, it is picked from the role. |
 | `brain` | yes | `owner/name` of this repo. Without it nothing can check secrets, labels or runs. |
 | `status_issue` | yes in practice | Number of the pinned status issue. The prompts reference it, so a run cannot compose without it. `roster hire --apply` writes it. |
 
@@ -154,6 +155,17 @@ Labels this staff member expects to exist on its own tracker, grouped for readab
 value across every group is checked by `roster doctor`. An agent applying a label that does not
 exist gets an API error mid-run.
 
+## `memory`
+
+This staff member's own memory budgets, overriding the org's. Same three fields as
+[`memory` in org.yaml](org-yaml.md#memory); any left out fall back to the org, then to the
+defaults.
+
+```yaml
+memory:
+  max_index_kb: 32
+```
+
 ## What `roster upgrade` does to this file
 
 Nothing. It is `scaffold` class: written once by `roster hire`, and yours from that moment.

package/docs/troubleshooting.md

@@ -22,8 +22,10 @@ a coding agent, split into what an agent can fix and what only a person can. `ro
 
 **Is:** the ops repo's Actions access is not set to organisation-wide.
 
-Settings -> Actions -> General on `roster-ops`. The setup screen deep-links that exact page,
-which is the fastest way to fix it; Health and `roster doctor` both check it explicitly.
+`roster init --apply` sets it, and so does *Set it for me* on the setup screen. If GitHub
+refused (it needs admin on the ops repo), set it by hand: Settings -> Actions -> General ->
+Access on `roster-ops`, "accessible from repositories in the organisation". Health and `roster
+doctor` both check it explicitly.
 
 ---
 
@@ -90,11 +92,9 @@ constrains it is not a thing anybody wants.
 **Is:** you edited a framework-owned file. `compose.mjs`, `agents.mjs`, `runner-plan.mjs` and
 `session.yaml` are generated. The next `roster upgrade` reconciles them against the template.
 
-This happened here: a fix went into `roster-ops/.github/workflows/session.yaml` instead of
-`templates/ops/...`, 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. Move the change upstream.
+Nothing notices until the framework next touches that file. `roster upgrade` reports an edit
+to a framework-owned file whether or not anything has collided, and `roster upgrade --check`
+fails on it. Move the change upstream.
 
 ---
 
@@ -181,7 +181,7 @@ landed on GitHub thirty seconds ago and the checkout is behind, that is what you
 
 ## `roster upgrade` says a file has no base
 
-A tenant created before the merge base was recorded has nothing to merge against. Reconstruct
+A tenant with no recorded merge base has nothing to merge against. Reconstruct
 one from the framework's history:
 
 ```bash

package/docs/upgrading.md

@@ -10,9 +10,9 @@ The framework writes templates out. A tenant runs its own copies. So the two dri
 `roster upgrade` is what reconciles them without eating your edits.
 
 ```bash
-roster upgrade                 # what would change
-roster upgrade --apply         # do it
-roster upgrade --check         # exit non-zero if anything is pending (for CI)
+npx @nanocollective/roster@latest upgrade           # what would change
+npx @nanocollective/roster@latest upgrade --apply   # do it
+npx @nanocollective/roster@latest upgrade --check   # exit non-zero if anything is pending (for CI)
 ```
 
 ## How it decides
@@ -53,6 +53,12 @@ The diff is printed either way, so nothing goes quietly.
 If you want a caller to differ, change the thing it is generated from. Timeouts, schedule,
 model and identities all live in `staff.yaml`.
 
+**A caller the framework no longer generates is removed.** It would still dispatch into
+`session.yaml` with a kind that no longer composes, and fail at run time. The plan lists it.
+The one that has gone so far is `<handle>-pr-mention.yaml`; if your tenant is old enough to
+have one, a forwarding workflow in the product repo went with it, and that one is yours to
+delete, because `roster upgrade` never writes into product repos.
+
 ## Conflicts
 
 A conflict is never written into a live file. Agents read `org/voice.md` at every boot, and

package/docs/writing-a-charter.md

@@ -28,6 +28,13 @@ layer. That is the part that matters most, because without them the model writes
 of whoever it was shown. The brief then interviews you, drafts from your answers, and tells you
 what it cut and why.
 
+**So is a worked example, when one fits.** A staff member whose handle or role reads as one of
+the ten roles below gets the matching [example](#worked-examples) inside the brief, labelled as a
+model for the shape and not content to copy. The copy-a-prompt panel has a picker to choose
+another or none; in a terminal it is `--example <handle>` or `--example none`. It is still a brief you
+answer: the interview comes first, and nothing in the charter should come from the example
+rather than from you.
+
 From a terminal, the same brief:
 
 ```bash
@@ -63,6 +70,27 @@ touches. Be specific. A vague boundary is one that gets crossed at 07:00 with no
 **Where the rest of it lives.** Point at `memory/INDEX.md`, `log/decisions.md`, the pinned
 status issue, and the surfaces the manifest declares.
 
+## Worked examples
+
+Ten, for an invented company called Acme. The handle in brackets is the one `--example` takes.
+
+| Example | What they do |
+|---|---|
+| [CTO](charters/cto.md) (`cto`) | Builds the product: fixes, features and tests, as pull requests. |
+| [CMO](charters/cmo.md) (`cmo`) | Posts, SEO, copy and launch plans, as drafts to approve. |
+| [Head of Support](charters/support.md) (`support`) | Answers issues, writes help docs, and turns user reports into bugs. |
+| [Product Manager](charters/pm.md) (`pm`) | Turns ideas and user feedback into clear specs and a ranked backlog. |
+| [Designer](charters/designer.md) (`designer`) | Improves the product's look and usability, with accessibility fixes, as pull requests. |
+| [QA Engineer](charters/qa.md) (`qa`) | Tests the product, finds bugs, and writes clear reproductions and tests. |
+| [DevOps Engineer](charters/devops.md) (`devops`) | Keeps CI, deploys and dependencies healthy, and patches security updates. |
+| [Technical Writer](charters/writer.md) (`writer`) | Writes and keeps up the docs, guides and changelog. |
+| [Data Analyst](charters/analyst.md) (`analyst`) | Reads the numbers and writes a short weekly report on what changed. |
+| [Community Manager](charters/community.md) (`community`) | Answers discussions, welcomes contributors, and drafts release announcements. |
+
+They are examples to adapt, not templates to fill in. Read them for what a finished charter covers and how specific it gets, then write your own
+about your business. A charter copied from one of these describes Acme. The brief carries the matching one for
+you; these links are for reading them first.
+
 ## Things worth being concrete about
 
 - **Escalation.** Name the label and the mechanism, not the sentiment. "Open an issue labelled