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

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: "From nothing to a first staff member's first finished run, in the portal."
 sidebar_order: 1
 ---
 
@@ -10,125 +10,179 @@ 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. The page that opens is the setup screen, and it is the whole of
+setup. Every step below is also a command, listed at the end; they do the same work on the same
+files.
 
-**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.
+**How long it takes:** about an hour and a half to two hours to a first staff member's first
+finished run. Most of that is writing: what the business is, and the staff member's charter,
+each a conversation of twenty to thirty minutes with your own AI. The rest is about a dozen
+clicks and waiting for the run. Those two files are what make the staff worth running, so that
+hour is the part not to rush.
 
-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.
+## Before you start
 
-You need `gh` authenticated, and a credential for whichever [coding agent](agents.md) you want
-to run.
+- **`gh`, [signed in](https://cli.github.com)**, as someone who owns the organisation. roster
+  does everything through your own `gh` and holds no token of its own.
+- **A GitHub organisation.** GitHub has no API for creating one, so if you need one, make it on
+  github.com first. Brains are private repos; on GitHub Free that works, with one difference in
+  step 5.
+- **A credential for your [coding agent](agents.md).** For Claude Code, run
+  `claude setup-token` and keep the token it prints for step 5.
 
----
+You only need [the six things in Concepts](concepts.md#the-six-things-you-need-to-know) to follow
+this. Everything else can wait.
 
-The rest of this page is the same setup from a terminal. Everything the portal does, these do;
-nothing writes without `--apply`.
+## 1. Say which organisation, then read the plan
 
-## 1. Stand up the org
+![The setup screen, asking which organisation and who runs it](images/setup-org.jpg)
 
-```bash
-roster init --org acme --name "Acme Robotics"
-```
+Pick the organisation, say what the business is called and which coding agent runs a session.
+If the organisation already runs roster, the page offers to check it out here instead, which is
+how a second person joins.
 
-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
-```
+**Show me the plan** lists every file and repo it would make; *Create it* is a separate button.
+That is the pattern everywhere in roster: the plan first, then the apply.
 
-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.
+Creating it makes `<org>/roster-ops` and **sets its Actions access** so every repo in the org
+can call its workflow. Without that every run fails with "workflow not found". If GitHub refuses
+(it needs admin on the repo), the page says why and links to the setting to click instead.
 
-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.
+The rest of the steps stay on the same page. Reload it and the portal opens on **Getting
+started**, which keeps them in the sidebar until they are done, with hiring first.
 
 ## 2. Say what the business is
 
-Open `roster-ops/org/business.md`. It ships as questions. Answer them, or:
-
-```bash
-roster brief discover        # paste into whatever agent you use
-```
+`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.
 
-Or, in Claude Code, `cd roster-ops && claude` then `/discover`. Both print the same brief:
-`roster init` generates the slash command from it.
+**Copy the prompt** puts a brief on your clipboard with every file it refers to inside it. Paste
+it into Claude, ChatGPT or anything else; it interviews you and hands back the file. Paste the
+reply into the box and you get a diff and a save button. See
+[the portal](portal.md#copy-a-prompt-paste-the-answer-back).
 
-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.
+Then `org/priorities.md`: what matters this month, ranked, and what is out of scope. A few
+lines, only you can write it, so it opens in place on the setup screen and saves the same way.
+See [concepts](concepts.md#priorities).
 
 ## 3. Hire someone
 
-```bash
-roster hire cto --name "Chief Technology Officer" --dir technology
-```
+![The Staff screen, with a card per staff member and Hire someone underneath](images/staff.jpg)
 
-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`.
+**Staff**, then pick a role: CTO, CMO, Support, or **Something else** with a name and a sentence
+about what they do. With nobody hired yet the Staff screen opens on the picker. The role fills
+in the handle, name and repo; they are under **Advanced** if you want to change them.
 
-For the first hire in a new org there is nobody to copy an identity from, so name them:
+The role opens a numbered list: hire, create their GitHub App, write their charter, add your
+agent credential, run once now. The steps after the hire say *Hire first* until it is done.
 
-```bash
-roster hire cto --name "Chief Technology Officer" --dir technology \
-  --app acme-cto --public-app acme-robot --apply
-```
+Step 1 says in one sentence what the hire creates and when they run. **Show details** has the
+full plan: the repo, the schedule and why, and the commits it will make **as you** in repos that
+already exist: each peer's `staff.yaml`, and `org.yaml`. Nothing is left uncommitted on disk.
 
-Later hires infer both from whoever is already there.
+For the first hire there is nobody to copy an App name from, so **Advanced** also has two:
+this staff member's App, and the shared public App, filled in as `<org>-<handle>` and
+`<org>-robot`. Names are unique across GitHub, so keep the org prefix. The public one only
+matters if a product repo is public.
 
-## 4. Give them an identity
+Product repos come from `org.yaml`. Mark one on the setup screen, or later with **Org → Add a
+product repo**.
 
-```bash
-roster app cto
-```
+After **Hire** the list stays on the same staff member, now on step 2. Leave and come back later
+with **Finish setting up** on their card.
+
+## 4. Create the App, and confirm the install
 
-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.
+**Create the App**, in step 2. GitHub has no API that creates an App, so a tab opens and you
+confirm. The App's id and private key go straight into the repo's secrets and never touch disk.
+The public App is offered too when a product repo is public.
 
-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 **Install it**. The install page opens with the organisation and every repo this staff
+member needs already ticked: its brain, the trackers of its peers, and the product repos. Check
+the list and confirm. That confirmation is yours by design: installing grants access, and GitHub
+asks a person.
 
 ## 5. Write the charter
 
-```bash
-roster brief charter cto     # paste into whatever agent you use
-```
+Step 3. **Let an AI interview you** is the same copy-a-prompt loop as step 2 of this guide, aimed
+at `CHARTER.md`, carrying the org layer, the peers' charters and, where the role matches one, a
+[worked example](writing-a-charter.md#worked-examples) to model the shape on. **Start from the
+template** opens that example in an editor with your business's name in it; edit it so it fits
+before saving. **Edit the file** is the file as it is. roster never generates a charter, because
+a generated one makes exactly the generic agent this whole arrangement exists to avoid.
 
-Or, in Claude Code, `cd technology && claude` then `/charter`. Same brief either way.
+## 6. Store the agent credential, once
 
-This is the file that decides everything else. [Writing a charter](writing-a-charter.md).
+Step 4, shown only while no credential is stored. It is also on the card and on the setup
+screen. Paste the token from `claude setup-token` (or your agent's key; the box says where to
+get one). It is stored as one organisation secret, shared with the brain repos, and each later
+hire is added to it. It is not asked for again.
 
-## 6. Check, then run one by hand
+On GitHub Free an org secret does not reach private repos, so there it goes on each brain repo
+instead, and the page says so. It is still one paste now; a later hire needs it once more.
 
-```bash
-roster doctor cto
-```
+## 7. Run it once
+
+**Run once now**, step 5, also on the card and on **Health**. It starts the daily workflow, follows it, and
+tells you how it ended, with the log.
+
+**A workflow that has never run has proved nothing**: not that the App is installed on the right
+repos, not that the secrets are right. Doctor reports it as `unproven` until one run has
+finished, and this is that run. If it fails, the result names the step, and
+[troubleshooting](troubleshooting.md) has what each failure usually means.
+
+Health is `roster doctor` on the page. Every finding carries the sentence that fixes it.
+
+## 8. Now look at what you built
 
-Fix what it says. Then trigger the daily workflow once from the Actions tab and read the log.
+![A staff member's brain: memory sections, the facts in them, and the files](images/brain.jpg)
 
-**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.
+**Brain** is that staff member's memory and files together. **Prompt** is the text they are
+actually sent, with every layer it was made of and which repo each came from.
 
-## 7. Look at it
+![The Prompt screen: the composed text, and the layers behind it](images/prompt.jpg)
+
+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.
+
+![The Org screen, with org.yaml and every layer every staff member inherits](images/org.jpg)
+
+**Org** is the layer everybody inherits. Change `org/voice.md` once and it reaches every staff
+member on their next run.
+
+## From a terminal
+
+The same road, command by command. Each prints its plan and changes nothing without `--apply`.
+
+`roster` below means `npx @nanocollective/roster@latest`, unless you have installed it with
+`npm install -g @nanocollective/roster`.
 
 ```bash
-roster portal
+roster init --org acme --apply        # the ops repo, and its Actions access
+roster brief discover                 # a brief for org/business.md
+roster brief priorities               # a brief for org/priorities.md
+roster hire cto --apply               # the brain, the wiring, the commits as you
+roster app cto --apply                # the App, its secrets, and a pre-ticked install link
+roster credential --apply             # the agent credential, once for the org
+roster brief charter cto              # the charter brief, with the CTO example
+roster run cto --apply                # one run, followed to the end
 ```
 
-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.
+## What is still yours to do
+
+Five things, each because GitHub or the job itself needs a person: creating the organisation,
+confirming the App, confirming its install, getting the agent credential, and writing
+`business.md`, `priorities.md` and each charter. [Manual steps](manual-steps.md) has why for
+each.
 
 ## 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 GitHub App, the charter and one run. The
+  credential is already there.
+- **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).
+- **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

@@ -1,163 +1,157 @@
 ---
 title: "Manual steps"
-description: "Every human action, why it cannot be automated, and what breaks if you skip it."
+description: "What only a person can do, why, and what breaks if it is skipped."
 sidebar_order: 2
 ---
 
 # Manual steps
 
-Everything a human has to do, why it cannot be automated, and what it looks like when you skip
-it. This page exists because every item on it has cost somebody real time.
+What roster cannot do for you, why, and what it looks like when one is skipped. The
+[getting started](getting-started.md) path walks through each of these in order; this page is
+what to read when one of them bites.
 
-**The portal walks you through most of this now.** `roster` with no arguments opens a setup screen
-that deep-links item 1, runs items 2 and 3 for you as far as GitHub allows, and hands you a prompt
-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.
+**Health**, or `roster doctor`, checks each one it can, and every finding carries the sentence
+that fixes it.
 
-`roster doctor` checks most of these. Run it after each one.
+---
+
+## 1. Create the organisation
+
+**Do:** make it on github.com, if you do not have one.
+
+**Why not automated:** GitHub has no API for creating an organisation.
 
 ---
 
-## 1. Allow the ops repo's workflow to be called
+## 2. Confirm the GitHub App
 
-**Do:** `<org>/roster-ops` -> Settings -> Actions -> General -> *Access* -> **Accessible from
-repositories in the organisation**. The setup screen links straight to that page.
+**Do:** press **GitHub App** on a staff card, or run `roster app <handle> --apply`. A tab
+opens; confirm on GitHub. The App's id and private key go straight into the brain repo's
+secrets.
 
-**Why not automated:** it is an organisation permission on a repository, and the API for it
-needs admin rights that a token created for a different purpose should not have. roster reads
-it and tells you, but setting it is one click and it is yours.
+**Why not automated:** there is no API that creates a GitHub App. The only route is the App
+Manifest flow, where a person confirms on a GitHub page. roster does everything either side of
+that.
 
-**If you skip it:** every caller fails with **"workflow not found"**. That reads like a typo in
-a path, or a missing file, or a bad branch reference. You will check all three. It is none of
-them, it is this.
+**If you skip it:** the run fails at the token-minting step, saying the App does not exist.
 
-**Check:** `roster doctor` reports `roster-ops is callable from the whole org`.
+The private key is handed to `gh` on standard input. It is never written to a file, never on a
+command line, and never in the process table. If the secret write fails after the App is
+created, the key is gone: generate a new one from the App's settings page and set the secret by
+hand. roster says so if it happens.
 
 ---
 
-## 2. Create the GitHub App
+## 3. Confirm the App's install
 
-**Do:** the **GitHub App** button on a staff card in the portal, or `roster app <handle>` in a
-terminal. Either opens a browser, GitHub asks you to confirm, and you come back. Credentials go
-straight into the repository's secrets.
+**Do:** press **Install it** in the portal, or open the link `roster app` prints. The page opens
+with the organisation and the repos this staff member needs already selected: its brain, the
+ops repo (every run checks it out first), each peer's tracker, and the product repos. Check the
+list and confirm. Choosing **All repositories** instead also works.
 
-**Why not fully automated:** there is no API that creates a GitHub App. The only route is the
-App Manifest flow: POST a manifest to a settings page, a human confirms, GitHub returns a
-one-time code. roster does everything either side of that confirmation.
+**Why not automated:** installing is a grant of access to specific repositories, and GitHub asks
+a person to confirm it. That is correct and should not be worked around.
 
-**If you skip it:** the run fails at the token-minting step with a message about the app not
-existing.
+The pre-selection uses `suggested_target_id` and `repository_ids[]` on the install page. GitHub's
+own links use them, but they are not in GitHub's documentation. If the ids cannot be read, or
+GitHub stops honouring them, the link is the plain install page and you tick the repos yourself;
+the portal and `roster app` both list which.
 
-**Note:** the private key is handed to `gh` on standard input. It is never written to a file,
-never passed on a command line, and never appears in the process table. If the secret write
-fails after the App is created, the key is gone: generate a new one from the App's settings
-page and set the secret by hand. roster tells you this if it happens.
+**If you under-grant it:** this is the trap that costs the most time, because the API reports an
+App's **declaration** separately from an installation's **grant**. `GET /apps/<slug>` will say
+the App exists and has `contents: write` without saying whether it is installed on the repo you
+care about. So **do not verify an installation by reading the API**. Run it once (item 5).
 
 ---
 
-## 3. Install the App, and grant it the right repositories
+## 4. Get the agent's credential
 
-**Do:** open the URL the portal shows, or that `roster app` prints. Choose repositories.
+**Do:** get a credential for your coding agent (`claude setup-token` for Claude Code; the others
+are in [choosing a coding agent](agents.md#1-the-credential-exists-and-you-have-it)) and paste it
+into **Agent credential**, or pipe it to `roster credential --apply`. It is stored once, as an
+organisation secret shared with the brain repos, and each hire adds its repo to it.
 
-**Why not automated:** installing is a grant of access to specific repositories, and GitHub
-requires a human to choose them. This is the correct behaviour and should not be worked around.
-
-**Grant it on every tracker the staff member writes to**, not just their own. The token is
-minted organisation-wide, and a peer's board is where a brief lands. Both the portal and
-`roster app` say so.
-
-**If you skip it, or under-grant it:** this is the trap that costs the most time, because of
-how it fails.
+**Why not automated:** it is your account's credential and roster has no way to obtain one.
 
-> The API reports an App's **declaration** separately from an installation's **grant**.
-> `GET /apps/<slug>` will happily tell you the App exists and has `contents: write`. That says
-> nothing about whether it has been installed on the repository you care about. Two of our
-> Apps declare permissions they were never granted.
+Where an org secret would not arrive, it goes on each brain repo instead and says why. On GitHub
+Free, org secrets do not reach private repos, and only an org owner can set one. Setting an org
+secret also needs the `admin:org` scope on your `gh` token; if it is missing, the credential goes
+on each repo and the output gives the command that adds the scope.
 
-So: **do not verify an installation by reading the API.** The only thing that proves the whole
-chain (App created, installed, granted, secrets right, workflow reachable) is a run that
-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.
+**If you skip it:** the run fails immediately with `the caller passed no agent credential`.
 
-**Check:** `roster doctor <handle>`, then trigger one run and look again.
+**Check:** Health, or `roster doctor`, lists the secrets each caller references and whether they
+exist, on the repo or shared from the org.
 
 ---
 
-## 4. Set the agent's credential
-
-**Do:** put the coding agent's credential on each brain repo as a secret. The name follows the
-credential: `CLAUDE_CODE_OAUTH_TOKEN`, `CODEX_API_KEY`, and so on. See
-[choosing a coding agent](agents.md).
+## 5. Watch the first run
 
-**Why not automated:** it is your account's credential and roster has no way to obtain one.
+**Do:** **Run once now** on the staff card or on Health, or `roster run <handle> --apply`. It
+starts the daily workflow, follows it, and reports how it ended, with the log.
 
-**If you skip it:** the run fails immediately with `the caller passed no agent credential`.
-That check exists so it fails there rather than forty lines later inside the agent, after the
-checkouts have already happened.
+**Why it is yours:** it is a real run. It does a day's work and costs what one does, so it is a
+button you press rather than something setup does behind your back.
 
-**Check:** `roster doctor` lists the secrets each caller references and whether they exist.
+**Why it matters:** the only thing that proves the whole chain (App created, installed, granted,
+secrets right, ops repo callable) is a run that finished. `roster doctor` reports a workflow
+that has never run as **unproven** rather than fine, and one finished run clears it.
 
 ---
 
-## 5. Write `org/business.md`
+## 6. Write `org/business.md` and `org/priorities.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:** on the setup screen, **Copy the prompt** puts a brief on your clipboard with every file
+it refers to inside it; paste the reply back and you get a diff and a save button. `roster brief
+discover` prints the same brief. Then write `org/priorities.md`: a few ranked lines on what
+matters this month.
 
-`roster doctor` reports `business.stub` while it is still the questions.
+Health reports `business.stub` and `priorities.stub` while either is still the stub.
 
 **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
-composed into the top of every prompt, every run.
+and generic. That is worse than no work, because it takes longer to notice.
 
-**If you skip it:** nothing errors. That is the problem. You get competent-looking output about
-a business that does not exist.
+**If you skip it:** nothing errors. That is the problem.
 
 ---
 
-## 6. Write each staff member's `CHARTER.md`
+## 7. 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, the same round trip as item 6. The
+brief carries the org layer, `business.md`, the peers' charters, and where the role matches one,
+a [worked example](writing-a-charter.md#worked-examples) to model the shape on. `roster brief
+charter <handle>` prints the same brief.
 
-**Why not automated:** same reason, one level down. The charter is what makes a staff member
-different from the others.
+**Why not automated:** the charter is what makes a staff member different from the others, and
+a generated one is the generic agent this arrangement exists to avoid.
 
-**If you skip it:** `charter` reports it as present, because the stub is a file. `charter.stub`
-is the finding that says nobody has answered it. The agent has no personality and produces
-whatever the shared layer implies.
+**If you skip it:** `charter.stub` says nobody has answered it, and the agent produces whatever
+the shared layer implies.
 
 ---
 
-## 7. Commit and push what roster wrote into other repos
+## 8. Commit what `roster upgrade` wrote
 
-**Do:** `roster hire` and `roster upgrade` write into brain repos on disk. Review, commit, push.
+**Do:** review, commit and push what `roster upgrade --apply` changed in the brain repos.
 
-**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
-repository**, which is a GitHub restriction and not a configuration mistake. That is also why
-agents can never update their own workflows, and why upgrades are human-run by design.
+**Why not automated:** **App tokens cannot push a change under `.github/workflows/`**, in any
+repository. That is a GitHub restriction, and it is why agents never update their own workflows
+and upgrades are run by a person. Hiring commits its own changes as you, and lists them first.
 
-**If you skip it:** the change exists locally and nowhere else. `roster upgrade` will report it
-as still pending next time, which is the intended behaviour.
+**If you skip it:** the change exists locally and nowhere else, and `roster upgrade` reports it as
+pending next time.
 
 ---
 
-## Order
-
-For a new organisation:
-
-In the portal, this order is the screen you are looking at. From a terminal:
+## What roster does for you
 
-```
-roster init --org <org> --apply          # 1 applies here
-roster hire <handle> --apply             # then 7
-roster app <handle>                      # 2, then 3
-# 4, 5, 6
-roster doctor <handle>
-```
+Each of these is a step of a command, listed in its plan before it happens, and each falls back
+to telling you exactly what to click if GitHub refuses.
 
-Then trigger one run by hand before trusting the schedule. A workflow that has never run has
-proved nothing.
+| | |
+|---|---|
+| The ops repo's Actions access | `roster init --apply`, or **Set it for me** on the setup screen. Needs admin on the ops repo. Skipped, every caller fails with "workflow not found". |
+| Committing peer wiring | `roster hire --apply` commits and pushes each peer's `staff.yaml` and `org.yaml` as you. A push that fails is reported and left for you. |
+| Giving each new brain the credential | `roster hire --apply` adds the repo to the org secret. |
+| Choosing repos on the install page | pre-selected, as above. |
+| The review gate on product repos | `roster hire --apply` adds it where there is none. See [security](security.md#the-review-gate). |