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

package/docs/extending.md

@@ -12,6 +12,11 @@ Four seams, in the order you are likely to reach for them.
 
 Edit `org/*.md` in the ops repo. It reaches every staff member on their next run.
 
+The [Org screen](portal.md#org) is exactly this seam: every one of these files listed off disk
+with a line saying what it is for, an Edit button, and a save that commits and pushes. The list
+comes off disk rather than being written into the page, so a file you add yourself is editable
+there too.
+
 | File | For |
 |---|---|
 | `business.md` | what the business is. The one everything else is downstream of. |
@@ -34,7 +39,6 @@ _identity.md    who you are posting as, and where
 _paths.md       where things are in the runner checkout
 daily.md        the scheduled session
 mention.md      a focused task from a comment
-pr-mention.md   a review comment forwarded from the product repo
 ```
 
 The syntax is small on purpose: `{{ path.to.value }}`, `{{> partial.md }}`,
@@ -54,7 +58,12 @@ A staff member can override a fragment for themselves. `{{>? staff:prompts/work.
 `daily.md` renders `prompts/work.md` from their own brain repo if it exists, and nothing if it
 does not. That is how one role gets a different working ritual without changing anybody else's.
 
-See what you actually built:
+See what you actually built on the [Prompt screen](portal.md#prompt), which walks the includes
+rather than listing them from memory, so a fragment you just added shows up on it, marked with
+the repo it came from. An optional fragment a role does not have is shown as absent rather than
+hidden. The layers are editable there too, subject to the writable list on that page.
+
+From a terminal:
 
 ```bash
 roster prompt cto --kind daily

package/docs/getting-started.md

@@ -1,6 +1,6 @@
 ---
 title: "Getting started"
-description: "Stand up an org and a first staff member, in seven steps."
+description: "Stand up an org and a first staff member, from the portal."
 sidebar_order: 1
 ---
 
@@ -10,125 +10,130 @@ sidebar_order: 1
 npx @nanocollective/roster
 ```
 
-Run that in an empty directory. It opens a portal in your browser and walks the whole setup:
-it checks `gh`, lists the organisations you can see, and asks which one.
+Run that in an empty directory. There is nothing else to install and nothing to configure
+first: the page that opens is the setup screen, and it is the whole of setup.
 
-**Two answers, and it works out which you need.** An organisation that does not run roster yet
-gets one stood up. One that already does gets checked out here instead, ops repo and every
-staff repo side by side, which is the shape the CI runner uses. That is how a second person on
-a team joins an org somebody else set up.
+You need two things before you start. `gh` [authenticated](https://cli.github.com), and a
+credential for whichever [coding agent](agents.md) you want to run. A GitHub organisation too,
+if you do not already have one: GitHub has no API for creating one, so that part happens on
+github.com.
 
-From there the page carries the rest: the Actions setting that has to be clicked, the repos
-your staff work in, hiring, each GitHub App, and a prompt you paste into your own AI to write
-`org/business.md` and the charters.
+Everything below is also a command, and the commands are in [the CLI
+reference](commands.md). They do the same work on the same files. This page is the portal
+because that is the shorter road, not because the terminal is second class.
 
-You need `gh` authenticated, and a credential for whichever [coding agent](agents.md) you want
-to run.
+## 1. Say which organisation
 
----
+![The setup screen, asking which organisation and who runs it](images/setup-org.jpg)
 
-The rest of this page is the same setup from a terminal. Everything the portal does, these do;
-nothing writes without `--apply`.
+**It works out which of two things this is, and you do not have to know.** An organisation
+that does not run roster yet gets one stood up. One that already does gets *checked out* here
+instead, ops repo and every staff repo side by side, which is the shape the CI runner uses.
+That second case is how somebody joins an org a colleague set up, and offering both is how an
+org ends up with two `roster-ops` repos.
 
-## 1. Stand up the org
+The rest of the card is three answers: what the business is called, which GitHub login the
+agents answer to, and which coding agent runs a session. The agent is the one that is awkward
+to change later, because it decides which credential the repos need.
 
-```bash
-roster init --org acme --name "Acme Robotics"
-```
+## 2. Read the plan before anything exists
 
-That prints the plan. Read it, then:
+![The plan: sixteen files and one private repo, listed before anything is written](images/setup-plan.jpg)
 
-```bash
-roster init --org acme --name "Acme Robotics" --apply
-```
+Nothing has been created yet. **Show me the plan** lists every file and every repo it would
+make, and *Create it* is a separate button. This is the pattern everywhere in roster: the plan
+first, then the apply, and the same `initFiles` behind both the browser and the terminal so
+they cannot disagree about what a new tenant contains.
 
-You now have `acme/roster-ops`: the org layer, the runner machinery, and a recorded merge base
-so later upgrades are merges rather than copies.
+After it applies you have `acme/roster-ops`: the org layer, the runner machinery, and a
+recorded merge base so later [upgrades](upgrading.md) are merges rather than copies.
 
-Then do the one thing that cannot wait: **Settings -> Actions -> General on `roster-ops`, set
-access to "accessible from repositories in the organisation".** Skip it and every workflow
-later fails with "workflow not found", which reads like a typo and is not one.
+## 3. The Actions setting
 
-## 2. Say what the business is
+The page asks for this next and deep-links to the exact settings page, because it is the one
+step whose failure is unrecognisable.
 
-Open `roster-ops/org/business.md`. It ships as questions. Answer them, or:
+**Settings → Actions → General on `roster-ops`, set access to "accessible from repositories in
+the organisation".** Skip it and every workflow later fails with "workflow not found", which
+reads like a typo and is not one.
 
-```bash
-roster brief discover        # paste into whatever agent you use
-```
+It is on [manual steps](manual-steps.md) with the others roster cannot do for you, and
+[Health](#7-health-then-one-run-by-hand) keeps asking until it is done.
 
-Or, in Claude Code, `cd roster-ops && claude` then `/discover`. Both print the same brief:
-`roster init` generates the slash command from it.
+## 4. Say what the business is
 
-Do this before hiring anyone. It is composed into the top of every prompt, and an agent that
-cannot answer these questions writes plausible work about a business that does not exist.
+`org/business.md` ships as questions, and it is composed into the top of every prompt. An agent
+that cannot answer them writes plausible work about a business that does not exist, so this
+comes before hiring anybody.
 
-## 3. Hire someone
+roster holds no model credential and cannot write it for you. What the portal does instead is
+both halves of the round trip: **Copy the prompt** puts a self-contained brief on your
+clipboard, and **paste the answer back** turns the reply into a file, with a diff and a button
+rather than a silent save. See [the portal](portal.md#copy-a-prompt-paste-the-answer-back).
 
-```bash
-roster hire cto --name "Chief Technology Officer" --dir technology
-```
-
-Read the plan. It lists every file, every label, the peer wiring in both directions, and the
-things it cannot do for you. Then `--apply`.
+## 5. Hire someone
 
-For the first hire in a new org there is nobody to copy an identity from, so name them:
+![The Staff screen, with a card per staff member and Hire someone underneath](images/staff.jpg)
 
-```bash
-roster hire cto --name "Chief Technology Officer" --dir technology \
-  --app acme-cto --public-app acme-robot --apply
-```
+**Staff → Hire someone.** Only the handle is required; everything else is copied from whoever
+is already here. You get the plan first: every file, every label, the schedule it chose and
+why, the peer wiring in both directions, and the steps it cannot do for you.
 
-Later hires infer both from whoever is already there.
+For the first hire in a new org there is nobody to copy an identity from, so the App names are
+asked for rather than guessed at. Later hires infer both.
 
-## 4. Give them an identity
+## 6. Give them an identity, and install it
 
-```bash
-roster app cto
-```
+**GitHub App**, on the same card. There is no API that creates a GitHub App, so this runs the
+manifest flow: a manifest is posted to a settings page, you confirm, and GitHub hands back a
+one-time code. The private key is held in memory and written straight to a repository secret
+without ever touching disk.
 
-A browser opens, GitHub asks you to confirm, and the App's id and private key go straight into
-the repository's secrets. The key never touches disk.
+**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. Grant it every tracker the staff
+member writes to, not only their own. This is the step that most often looks done and is not.
 
-Then **install it**, using the URL that command prints, granting it every tracker the staff
-member writes to. This is the step that most often looks done and is not. See
-[manual steps](manual-steps.md#3-install-the-app-and-grant-it-the-right-repositories).
+Then **Write the charter**, which is the same copy-a-prompt loop as `business.md`, aimed at
+`CHARTER.md`. `hire` deliberately does not generate one: a generated charter produces exactly
+the generic agent this whole arrangement exists to avoid. It is the file that decides
+everything else, so it is worth the time. [Writing a charter](writing-a-charter.md).
 
-## 5. Write the charter
+## 7. Health, then one run by hand
 
-```bash
-roster brief charter cto     # paste into whatever agent you use
-```
+**Health** is `roster doctor` on the page, every finding carrying the sentence that fixes it,
+split into what an agent can do and what only a person can. Work through it until the ids are
+gone.
 
-Or, in Claude Code, `cd technology && claude` then `/charter`. Same brief either way.
+Then trigger the daily workflow once from the Actions tab and read the log.
 
-This is the file that decides everything else. [Writing a charter](writing-a-charter.md).
+**A workflow that has never run has proved nothing.** Not that the App is installed, not that
+the grant took, not that the secrets are right. `doctor` says `unproven` rather than `fine` for
+exactly this reason.
 
-## 6. Check, then run one by hand
+## 8. Now look at what you built
 
-```bash
-roster doctor cto
-```
+![A staff member's brain: memory sections, the facts in them, and the files](images/brain.jpg)
 
-Fix what it says. Then trigger the daily workflow once from the Actions tab and read the log.
+**Brain** is that staff member's memory and files together, because they were always the same
+thing. **Prompt** is the text they are actually sent, composed by your own `compose.mjs`, with
+every layer it was made of and which repo each came from.
 
-**A workflow that has never run has proved nothing.** Not that the App is installed, not that
-the grant took, not that the secrets are right. `doctor` says `unproven` rather than `fine` for
-exactly this reason.
+![The Prompt screen: the composed text, and the layers behind it](images/prompt.jpg)
 
-## 7. Look at it
+Those two answer the question people ask hardest in the first week, which is *why did it do
+that*. The answer is always in one of those files.
 
-```bash
-roster portal
-```
+![The Org screen, with org.yaml and every layer every staff member inherits](images/org.jpg)
 
-Everything open across the org, every staff member's memory, what changed since yesterday, and
-whether anything is unhealthy. Reads the repositories on disk, so keep them checked out
-alongside each other.
+**Org** is the layer everybody inherits. Change `org/voice.md` once and it reaches every staff
+member on their next run, without regenerating anything.
 
 ## Where things go from here
 
-- A second staff member: `roster hire`, then `roster app`. Peer wiring happens both ways.
-- A change to how everyone writes: edit `org/voice.md` once. It reaches everybody on their next
-  run.
-- A framework update: `roster upgrade`. See [upgrading](upgrading.md).
+- **A second staff member**: Staff → Hire someone, then the App. Peer wiring happens both ways.
+- **Answering your agents**: [the Inbox](portal.md#inbox) is everything open across the org, and
+  the reply goes out as you. Work they finished sits in [Pending work](portal.md#pending-work);
+  asking for a change to it is [one button](portal.md#asking-for-a-change).
+- **A framework update**: `roster upgrade`, or the same from the portal. See
+  [upgrading](upgrading.md).
+- **The whole portal**, screen by screen: [the portal](portal.md).

package/docs/manual-steps.md

@@ -14,7 +14,9 @@ that deep-links item 1, runs items 2 and 3 for you as far as GitHub allows, and
 for items 5 and 6. This page is still the *why*: it is what to read when one of them bites, and
 what to check when the page says something is not done.
 
-`roster doctor` checks most of these. Run it after each one.
+The portal's **Health** screen checks most of these, per staff member and for the org, with
+every finding carrying the sentence that fixes it. `roster doctor` prints the same from a
+terminal. Look after each step.
 
 ---
 
@@ -31,7 +33,7 @@ it and tells you, but setting it is one click and it is yours.
 a path, or a missing file, or a bad branch reference. You will check all three. It is none of
 them, it is this.
 
-**Check:** `roster doctor` reports `roster-ops is callable from the whole org`.
+**Check:** Health, or `roster doctor`, reports `roster-ops is callable from the whole org`.
 
 ---
 
@@ -79,7 +81,8 @@ chain (App created, installed, granted, secrets right, workflow reachable) is a
 finished. `roster doctor` reads a window of recent runs for exactly this reason, and reports a
 workflow that has never run as **unproven** rather than as fine.
 
-**Check:** `roster doctor <handle>`, then trigger one run and look again.
+**Check:** that staff member's Health screen, or `roster doctor <handle>`. Then trigger one run
+and look again.
 
 ---
 
@@ -95,17 +98,20 @@ credential: `CLAUDE_CODE_OAUTH_TOKEN`, `CODEX_API_KEY`, and so on. See
 That check exists so it fails there rather than forty lines later inside the agent, after the
 checkouts have already happened.
 
-**Check:** `roster doctor` lists the secrets each caller references and whether they exist.
+**Check:** Health, or `roster doctor`, lists the secrets each caller references and whether
+they exist.
 
 ---
 
 ## 5. Write `org/business.md`
 
-**Do:** answer the questions `roster init` leaves in it. The setup screen has a **Copy the
-prompt** button that carries every file it refers to, and a box to paste the answer back into;
-`roster brief discover` prints the same brief for a terminal.
+**Do:** the setup screen does both halves of this. **Copy the prompt** puts a brief on your
+clipboard with every file it refers to inlined, so a chat window with no filesystem is as useful
+as an agent standing in the repo; the box beneath it takes the reply, shows you a diff, and
+saves only when you press the button. `roster brief discover` prints the same brief for a
+terminal, and you can always just answer the questions in the file by hand.
 
-`roster doctor` reports `business.stub` while it is still the questions.
+Health reports `business.stub` while it is still the questions.
 
 **Why not automated:** an agent that does not know the business writes work that is plausible
 and generic. That is worse than no work, because it takes longer to notice. This file is
@@ -118,9 +124,11 @@ a business that does not exist.
 
 ## 6. Write each staff member's `CHARTER.md`
 
-**Do:** **Write the charter** on that staff member's card in the portal, or
-`roster brief charter <handle>` and paste it into your agent. Or write it by hand;
-[writing a charter](writing-a-charter.md) has the shape.
+**Do:** **Write the charter** on that staff member's card, which is the same copy-a-prompt,
+paste-the-answer-back round trip as item 5, aimed at `CHARTER.md`. The brief it copies carries
+the org layer, `business.md` and **the peers' charters**, because without those the model writes
+a second copy of whoever it was shown. `roster brief charter <handle>` prints the same brief, and
+[writing a charter](writing-a-charter.md) has the shape if you would rather write it yourself.
 
 **Why not automated:** same reason, one level down. The charter is what makes a staff member
 different from the others.
@@ -133,7 +141,11 @@ whatever the shared layer implies.
 
 ## 7. Commit and push what roster wrote into other repos
 
-**Do:** `roster hire` and `roster upgrade` write into brain repos on disk. Review, commit, push.
+**Do:** hiring writes a whole brain repo and pushes it, so this is mostly about `roster
+upgrade`, which writes into repos on disk and leaves them for you. Review, commit, push.
+
+Hiring from the Staff screen still edits the *other* staff members' manifests on disk to wire the
+peers both ways, and those are yours to commit.
 
 **Why not automated:** roster does not commit on your behalf into repositories it did not
 create in that command. And **App tokens cannot push a change under `.github/workflows/` in any
@@ -149,7 +161,18 @@ as still pending next time, which is the intended behaviour.
 
 For a new organisation:
 
-In the portal, this order is the screen you are looking at. From a terminal:
+In the portal it is the screen you are looking at, in this order:
+
+```
+the setup screen                         1 is deep-linked from it, and 5 is on it
+Staff -> Hire someone                    then 7
+GitHub App, on the new staff card        2, then 3
+Write the charter, on the same card      6
+                                         4 is yours: a secret on the brain repo
+Health                                   until the ids are gone
+```
+
+From a terminal:
 
 ```
 roster init --org <org> --apply          # 1 applies here

package/docs/memory.md

@@ -59,13 +59,16 @@ 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`, and an "updated:" chain.
+
+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,12 @@ 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]
+  timeout_minutes: 90
+  mention_timeout_minutes: 90
 
 staff:
   - { handle: cto, dir: technology, name: Chief Technology Officer, schedule: "0 7 * * 1-5" }
@@ -58,17 +59,37 @@ repos:
 | `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. |
 
-### `human`
+### `human` and `humans`
 
-Who the staff answer to. There is exactly one.
+Who the staff answer to. One person is a `human` map; more than one is a `humans` list:
+
+```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 +102,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 +119,9 @@ 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. |
 
 ### `staff`
 
@@ -127,7 +155,7 @@ 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 |