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

package/docs/portal.md

@@ -16,6 +16,19 @@ authentication and no API quota, and works offline. It can write to GitHub throu
 
 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.
+
+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
+themselves wait the same way: the inbox draws rows and the thread pane draws a page, in
+placeholder shapes, for the seconds GitHub takes. Anything you start writing in that pane
+survives the answer landing under it.
+
 ## Setup
 
 **With no tenant where you started it, the portal is the setup screen instead.** That is not an
@@ -62,7 +75,38 @@ down with the list, so opening a thread is a render rather than a request.
   a shorter timeline than open work because it is there to be read rather than triaged. A
   closed row is dimmed and marked; the sidebar badge keeps counting only what is open.
 - **Reply, close, reopen, open an issue.** All as you, through your own `gh`, so they are
-  indistinguishable from doing it on the site. Closing asks for confirmation.
+  indistinguishable from doing it on the site. Closing asks for confirmation. A half-written
+  reply survives a repaint, and pressing Comment with an empty box says so rather than
+  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
+  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
+  `from-CMO` are different labels and only one of them exists.
+- **Typing `@` offers the org.** A mention is the mechanism, not decoration: a staff member's
+  workflow gates on their handle, so a misspelled one is a message nobody is woken by. The list
+  is the staff and the humans, and nothing else. The Apps are deliberately absent: `@acme-cto`
+  is a login rather than an inbox, GitHub delivers nothing for mentioning one, and an agent
+  wakes on its own handle and not on the identity it posts as, so offering them is offering
+  entries that do nothing. Each row says which it is, the list appears under the caret, arrow
+  keys and Enter pick, Escape dismisses the list rather than the dialog around it, and an email
+  address is not a mention.
+- **Attachments.** Drop a file on the box, pick one, or paste one. Paste is the one that
+  matters, because a screenshot is on the clipboard and never on disk. GitHub's own drag-and-drop
+  attachments are minted by its web app and cannot be made with `gh`, so the file is committed
+  to `attachments/<date>-<name>` in the repo the issue lives in and pushed. The body gets the
+  link for you and the repo-relative path for the agent, which reads it off its own checkout
+  rather than needing a token for a private repo. 25MB a file; a failed push is reported rather
+  than hidden.
+- **Reactions.** The 👀 an agent leaves when it picks something up, under the comment it is on,
+  with who left it. Without it you post a comment, see nothing change, and have to open GitHub
+  to find out it landed.
+- **How much conversation** is on each row, which is most of what tells a live thread from
+  something filed and never answered.
 - Issue and PR references in a body become chips you can click through, and `@handle`
   mentions become chips too. A mention of somebody on this roster goes to their repository
   rather than to a GitHub profile of that name, which for `@cto` is a stranger.
@@ -79,17 +123,105 @@ down with the list, so opening a thread is a render rather than a request.
   disclosure. An item a cross-reference points at opens in the portal when the inbox already
   holds it, and on GitHub when it does not.
 
+## Pending work
+
+The same screen, scoped to pull requests, in its own place in the sidebar. An inbox is what is
+waiting on you; a pull request is work that is finished and waiting on a merge, and the count
+that matters is not how many are open but how many are green and still sitting there.
+
+It is called **Pending work** rather than "Pull requests" because that is what is behind it: a
+piece of work a staff member finished and cannot land alone. A pull request is how it arrives,
+not what it is.
+
+A pull request's thread has three tabs.
+
+- **Conversation** is the thread: body, timeline, reactions, reply box, same as an issue.
+- **Commits**, with subject, author and sha, each linking to GitHub.
+- **Files**: the full patch, rendered as a diff with line numbers, the same renderer *What
+  changed* uses. A file with no patch is binary or too large for the API to send one, and says
+  so rather than showing nothing.
+
+Both are fetched when you open the tab, not carried by the inbox. A diff is the biggest thing
+on this screen by an order of magnitude, and paying for every open PR's diff on every refresh
+of every repo to show one of them is the wrong trade.
+
+**Merge** sits beside Close and asks before it goes. It never deletes the branch: that is a
+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
+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.
+
+### Asking for a change
+
+**`@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.
+
+**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
+press of Comment posts your words on the thread and opens the request on their tracker, which
+carries
+
+- the pull request, its link and its branch
+- their `@handle`, which is what actually wakes them
+- an instruction to **answer on the pull request**, because `prompts/mention.md` otherwise tells
+  them to answer where the request came from, which here is the tracker, leaving the diff silent
+  and you watching the wrong page
+- the diff for the file you asked from, if you started from one, clipped: it is there to say
+  *which part*, not to be a copy of the diff that goes stale on the next push
+
+Untick it and the reply is just a comment. Who gets asked comes off the text you actually sent,
+so a handle you typed and then deleted is not asked.
+
+On the **Files** tab each file's heading has its own Reply, which opens the same box about that
+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.
+
 ## Org
 
-The layer every staff member inherits, in one place: `org.yaml` and the four org documents,
-each with a line saying what it is for, because five filenames tell you nothing about which to
-open. All five are editable, and saving commits and pushes.
+The layer every staff member inherits, in one place: `org.yaml`, every `org/*.md`, and the
+prompt files in `prompts/`, each with a line saying what it is for, because a filename tells
+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
+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,
+⌘S to save, and saving commits and pushes. Only `org.yaml` asks for confirmation first; a
+prose edit is one commit to revert, and asking every time teaches people to click through the
+question.
 
 `org.yaml` is the exception to the write allowlist. It belongs to the person rather than the
 agent, so it is writable. But it is the one file here that stops every prompt composing when
 it is wrong, so the server parses it with the tenant's own `compose.mjs` first and refuses
-anything that is not YAML it can read, or that has lost `org`, `name`, or a handle on a staff
-entry.
+anything that is not YAML it can read, or that has lost `org`, `name`, a handle on a staff
+entry, or a github login on an entry in [`humans`](org-yaml.md#human-and-humans).
+
+YAML is coloured, here and anywhere else the portal shows it: comments, keys, strings, numbers
+and the three keywords. `org.yaml` and `staff.yaml` are the two files anybody reads closely,
+and finding a key in a flat grey wall means reading every line.
+
+The card at the top names **everyone** the staff answer to, not the first of them. An org can
+have more than one human, and a card that names one of two reads as the only one who counts.
 
 ## Staff
 
@@ -156,7 +288,7 @@ rather than going nowhere.
 `roster prompt <handle> --kind daily` in a terminal. Composed on the server by the tenant's own
 `compose.mjs`, so there is no second implementation to drift.
 
-Pick the kind: `daily`, `mention` or `pr-mention`. A mention prompt is written for the comment
+Pick the kind: `daily` or `mention`. A mention prompt is written for the comment
 that woke it, so a preview fills in obviously-fake context.
 
 Beneath the composed text, the files it was made of, in two groups.
@@ -172,25 +304,9 @@ tells the agent to open these; it does not contain them. Editing a charter chang
 agent does without changing a byte of the composed prompt, and that distinction is easy to
 miss.
 
-### Problems
-
-The audit, beside the layers. Nothing here judges prose: every check is something a machine
-can be sure about, because a linter you stop believing is worse than no linter.
-
-| Check | Why it matters |
-|---|---|
-| a file is still the scaffold | `org/business.md` is composed into every run. Leaving it as questions is invisible: the run works and the output is just generic |
-| a placeholder never resolved | `{{staff.product.repo}}` is null for a staff member who contributes to no other repo, and the agent reads the braces literally |
-| the same line in two layers | the layers are inherited, so a rule a charter repeats from `org/` is duplication nobody reading either file can see |
-| the prompt is long | it is read in full on every run, forever |
-| it names a file that is not there | an instruction to read something absent is a quiet no-op inside a run nobody watches |
-| an included layer is empty | it contributes nothing and costs a line of includes |
-
-**Every finding carries the fix.** "Copy a prompt to fix this" builds a brief containing the
-finding, the composed prompt, and every layer, and puts it on your clipboard. Paste it into
-whatever agent you use. Knowing there is a problem is the hard part; writing the paragraph is
-not. The box comes pre-filled with what the finding worked out, so you can add to it rather
-than retype it.
+What is *wrong* with any of this is on [Health](#health). This screen answers "what is sent";
+whether what is sent is any good is a different question, and a tree that was half prompt and
+half complaints answered neither well.
 
 ### Getting help changing it
 
@@ -284,7 +400,11 @@ opening the diff that did it: one block per file, coloured, with line numbers.
 
 ## Health
 
-Three parts.
+Four parts: the rig, the org, the prompts and the memory. The rig is about this staff member,
+so it is first; the rest widens out from there.
+
+**The rig**: schedule in words, workflows present, last commit, last commit touching `memory/`,
+index and notes size, charter, status issue, missing surfaces.
 
 **The org, from `roster doctor`.** Every finding that is not `ok`, with what to do about it, and
 a button that turns the lot into one brief for a coding agent. That is `roster fix`: `doctor`,
@@ -300,20 +420,66 @@ an agent that has started editing has stopped reading.
 
 Paste it into whatever edits files here, then press *Check again*. The ids should be gone.
 
-**Memory problems**, and **the rig**.
+**Prompt problems.** The audit, over all three kinds of run at once. Nothing here judges prose:
+every check is something a machine can be sure about, because a linter you stop believing is
+worse than no linter. A finding true of more than one prompt is one row, and it says which.
 
-Memory problems are the same checks `roster lint` runs. Each one has a button that opens an
+| Check | Why it matters |
+|---|---|
+| a file is still the scaffold | `org/business.md` is composed into every run. Leaving it as questions is invisible: the run works and the output is just generic |
+| a placeholder never resolved | `{{staff.product.repo}}` is null for a staff member who contributes to no other repo, and the agent reads the braces literally |
+| the same line in two layers | the layers are inherited, so a rule a charter repeats from `org/` is duplication nobody reading either file can see |
+| the prompt is long | it is read in full on every run, forever |
+| it names a file that is not there | an instruction to read something absent is a quiet no-op inside a run nobody watches |
+| an included layer is empty | it contributes nothing and costs a line of includes |
+
+**Every finding carries the fix.** "Copy a prompt to fix this" builds a brief containing the
+finding, the composed prompt, and every layer, and puts it on your clipboard. Paste it into
+whatever agent you use. Knowing there is a problem is the hard part; writing the paragraph is
+not. The box comes pre-filled with what the finding worked out, so you can add to it rather
+than retype it. "Open the file" takes you to that layer on the Prompt screen.
+
+**Memory problems** are the same checks `roster lint` runs. Each one has a button that opens an
 issue in that staff member's own repo asking them to fix it, which is usually right, because
 they wrote it.
 
-**The rig**: schedule in words, workflows present, last commit, last commit touching `memory/`,
-index and notes size, charter, status issue, missing surfaces.
+## Any image opens
+
+**Click a picture and it opens over the page, fitted to the window.** Bottom right there is a
+`-`, the current zoom, and a `+`. The percentage is a button too: it refits. Scrolling zooms,
+dragging moves, clicking the picture goes between fitted and actual size, and `+`, `-`, `0` and
+Escape do the same from the keyboard. Zooming is anchored on the pointer, so the thing you
+aimed at stays where you aimed.
+
+The percentage is of **actual size**, not of fitted, so 100% means one image pixel per screen
+pixel. How far in it will go depends on the picture: a scaled image is a composited layer and
+the browser allocates it at the rendered size, so the ceiling is whatever keeps that within
+budget. Actual size is always reachable, however large the original is.
+
+This is every image the portal renders as content: a screenshot on a doc page, a picture inside
+a brain document, a file open in the Brain screen's viewer. A screenshot laid out for the column
+it sits in is unreadable exactly when it matters, which is when it is a picture of an interface
+and the part you need is the small print.
+
+Gallery tiles are the exception, and deliberately: their click already means "open this file",
+and the file's own view is one of the things that does open.
+
+Fitted, the picture is inset from the window edges and framed. That is not decoration. Most of
+these are screenshots *of this interface*, and one fitted edge to edge reads as the app having
+navigated rather than as a picture of it.
 
 ## Docs
 
 The framework's own documentation, rendered where you already are. Links between pages navigate
 the portal.
 
+**Search reads the pages, not their titles.** Twenty-odd pages is too many to scan by eye and
+few enough for the server to read in full on every keystroke, and what you are looking for
+("which page explains the mention gate") is a sentence in a paragraph rather than a word in a
+heading. A page has to contain every word you typed; results rank a title hit over a heading
+hit over sheer frequency, carry the lines the words were found in, and the first one opens as
+you type. The query is in the URL, so a search is a link.
+
 ## After upgrading roster
 
 **Restart the portal.** Its stylesheets and modules are read per request, so editing one and

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 was 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.
+
 ## Syntax
 
 Four forms, and nothing else.
@@ -71,8 +91,11 @@ 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 |
@@ -81,9 +104,10 @@ than a hang.
 | `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 |
 
 Anything else in a manifest is reachable under `staff.`, so `staff.status_issue` and
 `staff.public_token_env` work without being listed here.
@@ -105,6 +129,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 +147,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 +166,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,8 @@ 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`.
 
 ## Permissions a new App asks for
 
@@ -86,6 +87,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 +99,21 @@ 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 **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
+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
+load-bearing. Do not relax it.
 
 ## The loop guard
 

package/docs/session-workflow.md

@@ -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. |
+| `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
 
@@ -62,14 +61,13 @@ authentication error forty lines into a log.
 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
+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
     CLI one. See [choosing a coding agent](agents.md).
-15. **Say so if the run did not finish.**
+14. **Say so if the run did not finish.**
 
 ## What `runner-plan.mjs` emits
 

package/docs/staff-yaml.md

@@ -24,8 +24,7 @@ status_issue: 15
 schedule: "0 7 * * 1-5"
 model: claude-opus-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]
@@ -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

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,8 @@ 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.
+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.
 
 ---
 
@@ -31,7 +33,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 +51,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 +65,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.
 
 ---
 
@@ -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.