@nanocollective/roster 0.1.0-alpha.2 → 0.1.0-alpha.21

package/docs/prompts.md

@@ -8,7 +8,13 @@ sidebar_order: 15
 
 What a staff member is actually sent, and how to change it.
 
-See it for yourself before changing anything:
+**Look at it before changing anything.** The portal's [Prompt screen](portal.md#prompt) is the
+composed text and, beneath it, every file it was made of: which are inlined and in what order,
+which are only named, and which repo each came from. That last column is the one that matters,
+because a change to `roster-ops/org/voice.md` reaches every staff member and a change to a
+brain's own `prompts/work.md` reaches one.
+
+From a terminal, the same text:
 
 ```bash
 roster prompt cto --kind daily
@@ -35,16 +41,30 @@ does not control.
 |---|---|---|
 | `daily` | cron | no |
 | `mention` | `@handle` in a comment, or in a new issue body | yes |
-| `pr-mention` | a review comment on the product repo, forwarded in | yes |
 
-`mention` and `pr-mention` refuse to compose without context, because they are written for the
-comment that woke them. That is correct behaviour. To see one locally:
+A `mention` refuses to compose without context, because it is written for the comment that woke
+it. That is correct behaviour rather than a bug.
+
+The Prompt screen's kind picker handles that for you: pick **Mention** and it fills in
+obviously-fake trigger context so there is something to look at. From a terminal you supply it
+yourself:
 
 ```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
 ```
 
+**There are two routes in, and the prompt is not the same on both.** A comment carries a
+`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 would be a `gh api .../issues/comments/`
+call with no id on the end, which 404s.
+
+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
 
 Four forms, and nothing else.
@@ -71,23 +91,54 @@ than a hang.
 |---|---|
 | `org` | the whole of `org.yaml` |
 | `org.name`, `org.org` | the business name, the GitHub org |
-| `human` | the `human` block from `org.yaml` |
+| `human` | the primary human: the first of `humans`, or the singular `human` block |
 | `human.name`, `human.github`, `human.marker` | |
+| `humans` | everyone the staff answer to, in order. See [org.yaml](org-yaml.md#human-and-humans) |
+| `human_list` | all of them as a sentence: "Will (@will-lamerton) and Sam (@sam-x)" |
+| `humans_extra` | the same, minus the primary. **Empty when there is only one**, which is what makes `{{#if humans_extra}}` the way to mention the others |
 | `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 |
 | `peer` | the first peer, or null |
 | `peer_list` | peers pre-rendered as a markdown list |
-| `kind` | `daily`, `mention` or `pr-mention` |
+| `kind` | `daily` or `mention` |
 | `event` | trigger context, from `ROSTER_CONTEXT` |
-| `event.issue_number`, `event.comment_id`, `event.pr_number`, `event.repo`, `event.actor` | |
+| `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
@@ -105,6 +156,9 @@ This is not hypothetical. The shipped prompts referred to `{{staff.product.repo}
 which nobody noticed because every existing staff member had one. The first staff member of any
 new org could not compose a prompt at all.
 
+[Health](portal.md#health) checks for exactly this ("a placeholder never resolved"), per staff
+member, which is the only way to catch it before 07:00 rather than in a run nobody watched.
+
 ## Overriding a fragment for one staff member
 
 ```
@@ -120,7 +174,17 @@ else's. `daily.md` already carries this hook.
 `prompts/` is `seeded` class: yours to edit, and `roster upgrade` gives you a real three-way
 merge. Changes reach every staff member on their next run.
 
-Before pushing a prompt change to a live org, diff the composed result:
+**Edit them where you read them.** Every layer on the Prompt screen has an Edit button; saving
+writes that one file, commits it and pushes, and the confirmation names the repository and who
+picks it up. The org's own layers (`org/*.md`, `<ops>/prompts/*.md`) are the same edit on the
+[Org screen](portal.md#org). Not everything is writable: `compose.mjs`, `staff.yaml`, the
+workflows and `memory/INDEX.md` are readable and not editable, because a wrong one of those
+stops every prompt composing or overwrites what the next run is about to write.
+
+**The thing to check is what the edit did to the composed prompt, not to the file.** Those are
+different questions: a line added to one fragment can land three times or not at all. Saving
+from the Prompt screen shows you the first. From a terminal, the same check is two composes and
+a diff:
 
 ```bash
 roster prompt cto --kind daily > before.txt
@@ -129,5 +193,7 @@ roster prompt cto --kind daily > after.txt
 diff before.txt after.txt
 ```
 
-That is the only test there is for a prompt change. A change that composes fine and reads
-differently is not caught by anything else.
+Either way, that is the only test there is for a prompt change. One that composes fine and
+reads differently is not caught by anything else. [Health](portal.md#health) runs a prompt audit
+over all the kinds at once, but everything it checks is something a machine can be sure about,
+which never includes whether the prose is any good.

package/docs/security.md

@@ -42,7 +42,41 @@ workflows that constrain them.
 misconfiguration and it fails at run time. Over-granting is the risk: an App installed on the
 whole organisation can reach anything in it.
 
-Install narrowly. `roster app` prints the list it actually needs.
+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
 
@@ -86,6 +120,8 @@ constrained rather than sanitised:
 - `/api/file` resolves the path and refuses anything outside the workspace root.
 - `/api/diff` requires the directory to be a known staff repo and the sha to look like a sha.
 - `/api/doc` requires the page to be one the listing offered.
+- `/api/docasset` requires the screenshot to be one sitting in `docs/images/`, matched by name
+  against that listing. `..` is not a case to get wrong; it is simply a name not on it.
 
 `--host` overrides the bind address and prints a warning. It exists for people who know what
 they are doing on a network they control. See [hosting the portal](hosting.md).
@@ -96,12 +132,20 @@ Everything composed into a prompt is content you or your agents wrote: `org/`, t
 memory index. A `mention` run additionally carries the text of a comment.
 
 **On a private tracker that is you.** On the public product repo it is not, which is exactly
-why the product lane is split: a mention on a public PR is caught by a forwarder in that repo
-which does no work of its own, and dispatches to the private lane. The run that prints a
-charter and a chain of reasoning happens where the logs are not world-readable.
-
-The forwarder has an author gate, and it is load-bearing: anyone can comment on a public PR,
-and a run started from a comment executes with repository secrets. Do not relax it.
+why **nothing in a product repo wakes an agent at all**. There is no caller workflow there, by
+design: anyone can comment on a public pull request, a run started from a comment executes with
+repository secrets, and a run that prints a charter and a chain of reasoning would print it
+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 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.
+
+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
@@ -26,14 +26,13 @@ repositories in this organisation**. Without it, callers fail with "workflow not
 | Input | Type | Default | Means |
 |---|---|---|---|
 | `staff` | string | required | Handle, as in `org.yaml`. |
-| `kind` | string | `daily` | `daily`, `mention` or `pr-mention`. |
+| `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. |
-| `timeout_minutes` | number | `60` | Job ceiling. |
+| `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. |
 | `comment_id` | string | `""` | Trigger context. |
-| `pr_number` | string | `""` | Trigger context. |
 
 ## Secrets
 
@@ -52,24 +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. **Check out the PR branch**, on a `pr-mention`.
-10. **Set up Node and pnpm**, if the plan found a `package.json`.
-11. **Compose the prompt**, to a step output and to `.roster-prompt.txt`.
-12. **Check the agent has a credential.**
-13. **Work out which agent runs this**, by running `agents.mjs`.
-14. **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).
-15. **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
 
@@ -94,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,14 +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: 30
-pr_mention_timeout_minutes: 60
+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:
@@ -69,9 +68,8 @@ labels:
 |---|---|---|
 | `schedule` | none | Cron for the daily run. Rendered into the caller. |
 | `model` | org default | Model id. |
-| `timeout_minutes` | 60 | Ceiling on the daily session. |
-| `mention_timeout_minutes` | 30 | Ceiling on a mention run. |
-| `pr_mention_timeout_minutes` | 60 | Ceiling on a PR-amendment run. |
+| `timeout_minutes` | 90 | Ceiling on the daily session. |
+| `mention_timeout_minutes` | 90 | Ceiling on a mention run. |
 
 The three ceilings are separate on purpose. Raising the daily one because sessions have grown
 should not double the budget for a PR amendment. A job killed by a ceiling is reported by
@@ -156,6 +154,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

@@ -9,8 +9,10 @@ sidebar_order: 10
 Every trap on this page has actually been hit. Most of them fail in a way that points somewhere
 else, which is why they are worth writing down.
 
-Start with `roster doctor`. It groups by staff member and every finding that is not `ok` says
-what to do about it.
+Start with the portal's [Health](portal.md#health) screen. It groups by staff member, every
+finding that is not `ok` says what to do about it, and a button turns the lot into one brief for
+a coding agent, split into what an agent can fix and what only a person can. `roster doctor` and
+`roster fix` are the same two things from a terminal.
 
 ---
 
@@ -20,8 +22,10 @@ what to do about it.
 
 **Is:** the ops repo's Actions access is not set to organisation-wide.
 
-Settings -> Actions -> General on `roster-ops`. `roster doctor` checks this explicitly, and the
-portal's setup screen links straight to the page.
+`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.
 
 ---
 
@@ -31,7 +35,7 @@ portal's setup screen links straight to the page.
 `timeout-minutes` as `cancelled`, which reads as though somebody pressed a button.
 
 Tell them apart by duration. Several cancelled runs all stopping at the same minute is a
-ceiling, not a coincidence. `roster doctor` does this for you and names the number:
+ceiling, not a coincidence. Health does this for you and names the number:
 
 ```
 ✗ cto-daily.yaml: 5 of the last 10 ran to a 60m ceiling and were killed
@@ -49,8 +53,8 @@ so old timeouts keep being reported as timeouts.
 gated run still appears in the list with conclusion `skipped`. Most of a mention workflow's
 history is skipped runs.
 
-`roster doctor` ignores them. A workflow whose runs are *all* skipped is reported differently,
-because nothing has exercised the credentials.
+Health ignores them. A workflow whose runs are *all* skipped is reported differently, because
+nothing has exercised the credentials.
 
 ---
 
@@ -63,11 +67,12 @@ been **installed** on the repository in question, or which repositories the inst
 granted. The two are reported separately and they disagree exactly when you care.
 
 Do not verify an installation by reading the API. The only proof of the whole chain is a run
-that finished. `roster doctor` reads recent runs for this reason and calls a workflow that has
-never run **unproven** rather than fine.
+that finished. Health reads recent runs for this reason and calls a workflow that has never run
+**unproven** rather than fine.
 
 Fix: open the App's installation settings and check the repository list includes every tracker
-the staff member writes to, not just its own. `roster app` prints that list.
+the staff member writes to, not just its own. The **GitHub App** panel on that staff member's
+card says so loudly, and prints the list.
 
 ---
 
@@ -87,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.
 
 ---
 
@@ -107,8 +110,9 @@ first entry in `works_in`, and a staff member who contributes to no other reposi
 The shipped prompts guard these. A prompt fragment you have written yourself needs
 `{{#if staff.product}}` around anything that assumes one. Conditionals do not nest.
 
-Similarly `{{staff.status_issue}}` is empty until `roster hire --apply` has opened the pinned
-issue.
+Similarly `{{staff.status_issue}}` is empty until hiring has actually been applied and opened
+the pinned issue. Health's prompt audit has this check ("a placeholder never resolved"), and the
+[Prompt screen](portal.md#prompt) shows you the composed text with the braces still in it.
 
 ---
 
@@ -119,8 +123,7 @@ seconds. If it does not:
 
 - The reaction is `continue-on-error`. A missing reaction never costs the answer, so check
   whether the run itself started at all.
-- It is scoped to `kind == 'mention'`. A pr-mention is acknowledged by the forwarder in the
-  public repo instead, so that it gets one reaction rather than two.
+- It is scoped to `kind == 'mention'`. A daily run has nothing to react to.
 - On the `issues` route (a mention typed into a new issue body) the eyes go on the issue, not
   on a comment, because that payload has no comment.
 
@@ -178,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

@@ -15,26 +15,34 @@ particular, which takes longer to notice than no work at all.
 
 ## Write it with your own AI
 
-```bash
-roster brief charter <handle>
-```
+**Write the charter**, on that staff member's card on the [Staff screen](portal.md#staff), does
+the whole round trip. It copies a brief with every file it refers to already inside it, so a chat
+window with no filesystem is as useful as an agent standing in the repo. Paste the reply back
+into the box and you get a diff and a save button, never a silent write.
+
+It runs about 19,000 characters, on purpose: one paste into a large-context model beats six
+rounds of it asking for files it will never get.
+
+**The peers' charters are in there**, along with `org/business.md` and the shared operating
+layer. That is the part that matters most, because without them the model writes a second copy
+of whoever it was shown. The brief then interviews you, drafts from your answers, and tells you
+what it cut and why.
 
-That prints a self-contained brief. Paste it into whatever agent you use, or pipe it:
-`roster brief charter cto | pbcopy`. In Claude Code, `cd <staff-dir> && claude` then
-`/charter` runs the same text, because `roster hire` generates the slash command from it.
+**So is a worked example, when one fits.** A staff member whose handle or role reads as a CTO, a
+CMO or support 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 cto|cmo|support|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.
 
-**Or do the whole round trip in the portal.** *Write the charter* on that staff member's card
-copies the same brief with every file it refers to already inside it, including the peers'
-charters, so a chat window with no filesystem can do it. Paste the reply back and you get a diff
-and a save. See [the portal](portal.md).
+From a terminal, the same brief:
 
-The brief tells the agent to read `org/business.md`, the shared operating
-layer, and every peer's charter, then interviews you and drafts from your answers. It also tells
-you what it cut and why.
+```bash
+roster brief charter <handle>            # or: roster brief charter cto | pbcopy
+```
 
-There is nothing agent-specific in it. Claude Code gets a slash command because it is the
-reference runner and the shape happens to fit; everything else gets the same words from
-`roster brief`.
+In Claude Code, `cd <staff-dir> && claude` then `/charter` runs the same text, because `roster
+hire` generates the slash command from it. There is nothing agent-specific in any of it.
 
 ## What goes in it, and what does not
 
@@ -62,6 +70,14 @@ 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
+
+Three, for an invented company called Acme: a [CTO](charters/cto.md), a [CMO](charters/cmo.md)
+and a [Head of Support](charters/support.md). 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
@@ -73,7 +89,7 @@ status issue, and the surfaces the manifest declares.
 
 ## Keep it agreeing with the manifest
 
-`roster lint` fails if the charter and `staff.yaml` disagree. The manifest is the
+Health, and `roster lint`, fail if the charter and `staff.yaml` disagree. The manifest is the
 machine-readable half of the same document: handle, schedule, peers, surfaces, identities. If
 the charter says it reviews pull requests on the product repo, `works_in` had better include it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanocollective/roster",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.21",
   "description": "An agent-run org, powered by GitHub. Scaffold AI staff members whose brain is a repo.",
   "type": "module",
   "bin": {

package/templates/brain/.github/workflows/%%STAFF%%-daily.yaml

@@ -18,6 +18,12 @@ concurrency:
 
 jobs:
   session:
+    # The ceiling on what session.yaml's job token may do: reading the checkout, and the one
+    # comment that says a run failed when the App that would normally say so is what broke.
+    # A called workflow cannot raise these, so they have to be granted here.
+    permissions:
+      contents: read
+      issues: write
     uses: %%OPS_REPO%%/.github/workflows/session.yaml@main
     with:
       staff: %%STAFF%%
@@ -25,6 +31,7 @@ jobs:
       ops_repo: %%OPS_REPO%%
       model: %%MODEL%%
       timeout_minutes: %%TIMEOUT%%
+      allowed_tools: "%%ALLOWED_TOOLS%%"
     secrets:
       APP_ID: ${{ secrets.%%SECRET_PREFIX%%_APP_ID }}
       APP_PRIVATE_KEY: ${{ secrets.%%SECRET_PREFIX%%_APP_PRIVATE_KEY }}