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

package/docs/memory.md

@@ -16,8 +16,8 @@ memory/INDEX.md      one line per fact. Read in full at every boot.
 memory/notes/*.md    the argument behind a fact. Read only when that fact is in play.
 ```
 
-That split is the whole design. Boot context here went from about 52,000 words to about 6,000
-by making it, and the saving repeats on every run forever.
+That split is the whole design. Boot context here went from about 52,000 words to about 10,000
+today by making it, and the saving repeats on every run forever.
 
 ## The grammar
 
@@ -48,10 +48,27 @@ rumour.
 Rule 5 is the one that gets skipped and the one that matters. Everything else degrades slowly;
 this one degrades the boot cost of every future run.
 
+## Budgets
+
+Prose is advice, and an index nobody prunes grows past what a run can usefully read. So
+`roster lint` warns past three budgets:
+
+| Budget | Default | Rule |
+|---|---|---|
+| One fact's line | 400 characters | `too-long`, naming the fact |
+| `memory/INDEX.md` | 24KB | `index-too-big`, naming the three longest facts |
+| `log/decisions.md` | 24KB | `decisions-too-big`: roll older entries into `log/decisions/<YYYY-MM>.md` |
+
+Change them under `memory:` in [org.yaml](org-yaml.md#memory), or per staff member in
+[staff.yaml](staff-yaml.md#memory). The daily prompt tells a staff member to check its sizes at
+hand-off and make pruning that run's job when it is over.
+
 ## What does not go in memory
 
 - **Why something was decided.** That is `log/decisions.md`, and it is not boot context.
 - **How a thing works.** That is a draft or a strategy document.
+- **An idea not yet acted on.** That is one line in `strategy/ideas.md`, and it becomes an issue
+  only when it needs a ruling.
 - **What is outstanding.** That is the pinned status issue.
 
 Nothing is copied between them. Four places, four jobs, and a fact that appears in two of them
@@ -59,13 +76,17 @@ will disagree with itself within a month.
 
 ## Checking it
 
+**Health**, per staff member, has a **Memory problems** section. Each finding has a button that
+opens an issue in that staff member's own repository asking them to fix it, which is usually the
+right move: they wrote it, and an issue on their tracker is a thing that wakes them.
+
+It catches: a missing `So:`, a duplicate slug, a note nothing links to, a link to a note that
+does not exist, an over-long line, a `[measured]` fact with no `n`, an "updated:" chain, and an
+index or decision log over its budget.
+
+The same checks, for a terminal or for CI:
+
 ```bash
 roster lint          # everyone
 roster lint cto      # one staff member
 ```
-
-Lint catches: a missing `So:`, a duplicate slug, a note nothing links to, a link to a note that
-does not exist, an over-long line, a `[measured]` fact with no `n`, and an "updated:" chain.
-
-The portal's **Health** screen shows the same findings and will open an issue in the staff
-member's own repository asking them to fix it, which is usually the right move: they wrote it.

package/docs/org-yaml.md

@@ -31,11 +31,15 @@ experiment_private: true
 
 agent:
   id: claude-code-action
+  permissions: full
 
 defaults:
-  model: claude-opus-5
-  timeout_minutes: 60
-  allowed_tools: [Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch]
+  model: claude-opus-5-5
+  timeout_minutes: 90
+  mention_timeout_minutes: 90
+
+budget: 300
+review_gate: true
 
 staff:
   - { handle: cto, dir: technology, name: Chief Technology Officer, schedule: "0 7 * * 1-5" }
@@ -57,18 +61,40 @@ repos:
 | `name` | yes | What the business is called, in prose. Appears in prompts. |
 | `ops_dir` | no | Directory name of the ops repo in the runner checkout. Defaults to `roster-ops`. |
 | `experiment_private` | no | Whether the fact that this org is agent-run is itself private. Read by the guardrails fragment. |
+| `budget` | no | USD over any trailing 30 days, for the whole org. See [below](#budget). |
+| `review_gate` | no | `true` to have GitHub require a reviewed pull request before anything merges into a product repo. Off by default, because private repos need a paid plan for it. See [security](security.md#the-review-gate). |
+
+### `human` and `humans`
 
-### `human`
+Who the staff answer to. One person is a `human` map; more than one is a `humans` list:
 
-Who the staff answer to. There is exactly one.
+```yaml
+humans:
+  - { name: Will, github: will-lamerton, marker: will, role: founder }
+  - { name: Sam, github: sam-x, marker: sam, role: operations }
+```
 
 | Field | Required | Means |
 |---|---|---|
-| `github` | yes | Login. **The mention callers gate on this**, so without it nothing can wake an agent. |
+| `github` | yes | Login. **The mention callers gate on these**, so without one nothing can wake an agent. |
 | `name` | no | What to call them in prose. Defaults to the login. |
-| `marker` | no | Provenance tag on a fact they ruled on, as in `[will]`. Also used as a label. |
+| `marker` | no | Provenance tag on a fact they ruled on, as in `[will]`. Also used as a label. Defaults to the first part of the name, lowercased. |
 | `role` | no | Prose only. |
 
+Both keys are read, and the singular is not deprecated: an org with one human should keep
+writing `human`. When both are present, anyone in `human` who is not already in the list is
+appended rather than dropped.
+
+**The first entry is the primary.** Prompts are prose addressed to somebody ("*Will* is not
+here"), and a list of two cannot go in that sentence, so the first one goes there, their
+`marker` is what `%%HUMAN_MARKER%%` renders, and the rest are named by
+`{{humans_extra}}` in the identity fragment. Everything that *gates* on identity reads all of
+them: the mention caller's `if:` is `contains(fromJSON('["will-lamerton","sam-x"]'), …)`.
+
+Adding a human changes every generated caller workflow, so it takes a `roster upgrade` to reach
+the brain repos. Until that lands, the new person can open issues and read everything, and
+mentioning a staff member does nothing.
+
 ### `agent`
 
 Which coding agent runs a session. Either a string, or a map. See
@@ -81,10 +107,16 @@ Which coding agent runs a session. Either a string, or a map. See
 | `run` | if `id` is unknown | Shell command that runs it, reading `$AGENT_PROMPT_FILE`. |
 | `token_env` | if `id` is unknown | Environment variable its credential goes in. |
 | `model` | no | Default model for this agent. A staff member's own `model` wins. |
+| `permissions` | no | `full`, `workspace` or `read-only`. Defaults to `full`. One word, translated into each agent's own vocabulary: a tool list for Claude, a sandbox and an approval policy for Codex, a development mode for nanocoder. A staff member can set their own, and be trusted less than the org. |
+| `options` | no | A map, in that agent's own vocabulary, spelled onto its command line untranslated. The escape hatch for anything roster does not model. |
 
 Any field given overrides the preset's, so a preset that is right except for one flag needs
 one line.
 
+An agent that needs a config file of its own gets one written when `roster init` chooses it,
+with the parts only a person can supply left as `FILL IN` blanks. `roster doctor` fails while
+any of them are still there.
+
 ### `defaults`
 
 Fallbacks for staff members who do not set their own.
@@ -92,8 +124,23 @@ Fallbacks for staff members who do not set their own.
 | Field | Means |
 |---|---|
 | `model` | Model id passed to the agent. |
-| `timeout_minutes` | Ceiling on a daily session. |
-| `allowed_tools` | Tool permission string. Meaningful to agents that take one, ignored by those that do not. |
+| `timeout_minutes` | Ceiling on a daily session. `90` if unset. |
+| `mention_timeout_minutes` | Ceiling on a mention run. Falls back to `timeout_minutes`, then `90`. |
+| `allowed_tools` | Claude's own spelling of a permission level, kept because it predates `agent.permissions` and still wins for the agents that take a tool list. Nothing translates it for the others: a list written for one agent is not a permission level for another. Prefer [`agent.permissions`](agents.md#permissions), which every agent understands. |
+
+### `memory`
+
+Budgets `roster lint` holds every staff member's memory to. All optional; a staff member's own
+[`memory:`](staff-yaml.md#memory) overrides these.
+
+```yaml
+memory:
+  max_fact_chars: 400     # one fact's line in memory/INDEX.md
+  max_index_kb: 24        # the whole index, read in full at every boot
+  max_decisions_kb: 24    # log/decisions.md
+```
+
+Over budget is a warning naming what to cut, never an error. See [memory](memory.md#budgets).
 
 ### `staff`
 
@@ -106,10 +153,26 @@ lives in their own `staff.yaml`.
 | `dir` | no | Directory and repo name. Defaults to the handle. |
 | `name` | no | Role name in prose. |
 | `schedule` | no | Cron. Informational here; the caller workflow is what actually schedules. |
+| `budget` | no | USD over any trailing 30 days, for this staff member alone. |
 
 `roster hire` appends to this list. An empty list (`staff: []`) is valid and is what a fresh
 org has.
 
+### `budget`
+
+A number of dollars, on the org, on a staff entry, or both:
+
+```yaml
+budget: 300
+staff:
+  - { handle: cto, dir: technology, name: Chief Technology Officer, budget: 200 }
+```
+
+Spend over the trailing 30 days is added up from each run's record. Past a budget, `roster
+doctor` warns and the portal's Runs screen marks the total. **Nothing stops a run.** A cap that
+ends a session fails it after the work is done and committed, which is a false red rather than a
+saved penny; `timeout_minutes` is the real bound. See [cost](cost.md#budgets).
+
 ### `repos`
 
 Every repository the org owns, and what it is for.
@@ -127,11 +190,13 @@ Every repository the org owns, and what it is for.
 
 | Reader | Uses |
 |---|---|
-| `compose.mjs` | `org`, `name`, `human`, `ops_dir`, `staff` |
+| `compose.mjs` | `org`, `name`, `human`, `humans`, `ops_dir`, `staff` |
 | `runner-plan.mjs` | `org`, `staff`, and each manifest's `works_in` and `peers` |
 | `agents.mjs` | `agent`, `staff` |
 | `roster hire` | all of it, plus every existing manifest |
-| `roster doctor` | all of it |
+| `roster doctor` | all of it, including `budget` |
+| `roster lint` | `staff`, `memory` |
+| `roster portal` | all of it; the Runs screen reads `budget` |
 
 ## Editing it
 

package/docs/portal.md

@@ -16,6 +16,21 @@ 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
+
+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
+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
@@ -37,13 +52,31 @@ 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
 
@@ -62,7 +95,37 @@ 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. 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
+  `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,32 +142,168 @@ 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.** 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.
+
+### 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). 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
+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.
+
+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` 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.
+
+**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,
+⌘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).
 
-## Staff
+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.
 
-Everyone on the roster, and the four things you could previously only do from a terminal.
+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.
 
-**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.
+## Staff
+
+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,
@@ -114,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
@@ -152,11 +359,11 @@ 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`, `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 +379,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 +475,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 +495,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