@nanocollective/roster 0.1.0-alpha.1

package/docs/getting-started.md

@@ -0,0 +1,134 @@
+---
+title: "Getting started"
+description: "Stand up an org and a first staff member, in seven steps."
+sidebar_order: 1
+---
+
+# Getting started
+
+```bash
+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.
+
+**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.
+
+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.
+
+You need `gh` authenticated, and a credential for whichever [coding agent](agents.md) you want
+to run.
+
+---
+
+The rest of this page is the same setup from a terminal. Everything the portal does, these do;
+nothing writes without `--apply`.
+
+## 1. Stand up the org
+
+```bash
+roster init --org acme --name "Acme Robotics"
+```
+
+That prints the plan. Read it, then:
+
+```bash
+roster init --org acme --name "Acme Robotics" --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.
+
+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.
+
+## 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
+```
+
+Or, in Claude Code, `cd roster-ops && claude` then `/discover`. Both print the same brief:
+`roster init` generates the slash command from it.
+
+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.
+
+## 3. Hire someone
+
+```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`.
+
+For the first hire in a new org there is nobody to copy an identity from, so name them:
+
+```bash
+roster hire cto --name "Chief Technology Officer" --dir technology \
+  --app acme-cto --public-app acme-robot --apply
+```
+
+Later hires infer both from whoever is already there.
+
+## 4. Give them an identity
+
+```bash
+roster app cto
+```
+
+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.
+
+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).
+
+## 5. Write the charter
+
+```bash
+roster brief charter cto     # paste into whatever agent you use
+```
+
+Or, in Claude Code, `cd technology && claude` then `/charter`. Same brief either way.
+
+This is the file that decides everything else. [Writing a charter](writing-a-charter.md).
+
+## 6. Check, then run one by hand
+
+```bash
+roster doctor cto
+```
+
+Fix what it says. Then trigger the daily workflow once from the Actions tab and read the log.
+
+**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.
+
+## 7. Look at it
+
+```bash
+roster portal
+```
+
+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.
+
+## 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).

package/docs/hosting.md

@@ -0,0 +1,72 @@
+---
+title: "Hosting the portal"
+description: "Local is the default, and the honest options if you want it elsewhere."
+sidebar_order: 11
+---
+
+# Hosting the portal
+
+`roster portal` is local-first and that is the intended way to run it. It reads the checked-out
+repositories from disk, needs no authentication, hits no API rate limits, and works offline.
+
+```bash
+roster portal              # http://localhost:4300
+roster portal --port 4400
+```
+
+## Why local is the default
+
+**Setup is local only.** The screen that stands up a tenant also creates GitHub Apps and writes
+repository secrets, and none of that belongs behind a tunnel or an access proxy. Everything below
+is about a portal over an org that already exists.
+
+The portal can write. It replies to issues, closes them, reopens them and opens new ones,
+acting as you through your own `gh`. That is the point: it is where a person answers their
+agents. It also means it is not a thing to leave listening on a network.
+
+Three things guard it, and they only work locally:
+
+- it binds to `127.0.0.1`
+- a write needs a `POST` with an `x-roster` header, which forces a CORS preflight that fails
+  from any other origin
+- an `Origin` header, if present, must be localhost
+
+`--host` overrides the bind address and prints a warning. Do not use it to "just have a look
+from my phone".
+
+## Reading it from elsewhere
+
+The honest options, in order of how much you should like them.
+
+**A tunnel, briefly.** `ssh -L 4300:localhost:4300 you@yourmachine`, or Tailscale, or
+`cloudflared tunnel --url http://localhost:4300`. Your machine stays the only thing running it
+and the write path stays behind your own network identity. Turn it off afterwards.
+
+**A read-only static build.** `roster export` produces the whole org as one JSON document, and
+the portal's rendering is decoupled from its parsing precisely so this is possible:
+
+```bash
+roster export --out org.json
+```
+
+Serve that plus the portal HTML from anything static (Cloudflare Pages, S3, a directory). You
+get memory, the graph, the brain and what-changed. You do not get the inbox or any write
+action, because both need `gh`.
+
+Put access control in front of it. Cloudflare Access with a one-person policy is the least
+work. **This is private business content and a map of what your agents know**, so an
+unauthenticated URL is not an option even if nobody knows it.
+
+**A hosted instance with write access.** Not documented, and not recommended. It would need a
+GitHub App of its own, a session layer, and a credible answer to "what can this thing do if
+someone reaches it". None of that exists, and the local server plus a tunnel gets you the same
+outcome with none of it.
+
+## Keeping it current
+
+The portal reads your working tree, so a stale checkout shows stale data. `/api/sync` fetches
+and fast-forwards every repository on each refresh. It refuses to pull one that is dirty or has
+diverged, and says which in a banner rather than guessing.
+
+If you host a static export, the export is a point in time. Regenerate it on a schedule, or
+accept that it is yesterday's.

package/docs/manual-steps.md

@@ -0,0 +1,163 @@
+---
+title: "Manual steps"
+description: "Every human action, why it cannot be automated, and what breaks if you skip it."
+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.
+
+**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.
+
+`roster doctor` checks most of these. Run it after each one.
+
+---
+
+## 1. Allow the ops repo's workflow to be called
+
+**Do:** `<org>/roster-ops` -> Settings -> Actions -> General -> *Access* -> **Accessible from
+repositories in the organisation**. The setup screen links straight to that page.
+
+**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.
+
+**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.
+
+**Check:** `roster doctor` reports `roster-ops is callable from the whole org`.
+
+---
+
+## 2. Create the GitHub App
+
+**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.
+
+**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.
+
+**If you skip it:** the run fails at the token-minting step with a message about the app not
+existing.
+
+**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.
+
+---
+
+## 3. Install the App, and grant it the right repositories
+
+**Do:** open the URL the portal shows, or that `roster app` prints. Choose repositories.
+
+**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.
+
+> 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.
+
+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.
+
+**Check:** `roster doctor <handle>`, then trigger one run and look again.
+
+---
+
+## 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).
+
+**Why not automated:** it is your account's credential and roster has no way to obtain one.
+
+**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.
+
+**Check:** `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.
+
+`roster doctor` 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
+composed into the top of every prompt, every run.
+
+**If you skip it:** nothing errors. That is the problem. You get competent-looking output about
+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.
+
+**Why not automated:** same reason, one level down. The charter is what makes a staff member
+different from the others.
+
+**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.
+
+---
+
+## 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.
+
+**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.
+
+**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.
+
+---
+
+## Order
+
+For a new organisation:
+
+In the portal, this order is the screen you are looking at. From a terminal:
+
+```
+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>
+```
+
+Then trigger one run by hand before trusting the schedule. A workflow that has never run has
+proved nothing.

package/docs/memory.md

@@ -0,0 +1,71 @@
+---
+title: "Memory"
+description: "The grammar, the five rules, and why deleting is the maintenance."
+sidebar_order: 7
+---
+
+# Memory
+
+A staff member's memory is markdown in its own repository. There is no database, deliberately:
+an agent writes markdown well and writes to a schema badly.
+
+## The two files
+
+```
+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.
+
+## The grammar
+
+```
+- **`<slug>`** · [<will|measured|derived>] <the fact, one line>. **So:** <what it changes>. · [note](notes/<slug>.md)
+```
+
+`roster lint` enforces it, and the portal parses it. Provenance and the note link are optional.
+The slug, the fact and the `So:` are not.
+
+**Provenance** is one of three things: a human ruled it, it was measured, or it was derived.
+A `[measured]` fact without an `n` fails lint, because a number without a sample size is a
+rumour.
+
+## The five rules
+
+1. **One line per fact.** If it needs more, the extra goes in `notes/<slug>.md` and the line
+   stays one line.
+2. **Correct in place. Never append "updated:".** An update chain is how one fact becomes six
+   paragraphs that contradict each other.
+3. **Every fact says what it changes.** If you cannot write the `So:`, it is not memory. Do not
+   add it.
+4. **Measurements carry `n` and a date. Constraints do not expire; measurements do.** Anything
+   with a `review:` date is re-read or deleted on that date.
+5. **Deleting is the maintenance.** Cut every line that no longer changes a decision, and log
+   the cut. A memory that only grows is a memory nobody reads.
+
+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.
+
+## 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.
+- **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
+will disagree with itself within a month.
+
+## Checking it
+
+```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

@@ -0,0 +1,143 @@
+---
+title: "org.yaml reference"
+description: "Every field in the org manifest, and what reads it."
+sidebar_order: 13
+---
+
+# `org.yaml` reference
+
+The org manifest. Lives at the root of the ops repo, and is read at the top of every composed
+prompt, by `runner-plan.mjs`, by `agents.mjs`, and by every CLI command.
+
+Parsed by `parseYaml` in `compose.mjs`, which reads a deliberately small, strict subset of
+YAML: scalars, nested maps, block lists, and inline maps in a list. It does not do anchors,
+multi-line scalars, or flow maps at the top level. **A manifest that needs more than that has
+outgrown being a manifest**, and the parser refuses to guess rather than misparsing.
+
+## A complete example
+
+```yaml
+org: acme
+name: Acme Robotics
+ops_dir: roster-ops
+
+human:
+  name: Will
+  github: you
+  marker: will
+  role: founder
+
+experiment_private: true
+
+agent:
+  id: claude-code-action
+
+defaults:
+  model: claude-opus-5
+  timeout_minutes: 60
+  allowed_tools: [Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch]
+
+staff:
+  - { handle: cto, dir: technology, name: Chief Technology Officer, schedule: "0 7 * * 1-5" }
+  - { handle: cmo, dir: marketing, name: Chief Marketing Officer, schedule: "40 7 * * 1-5" }
+
+repos:
+  - { name: acme-web, visibility: public, role: product }
+  - { name: technology, visibility: private, role: brain }
+  - { name: roster-ops, visibility: private, role: ops }
+```
+
+## Fields
+
+### Top level
+
+| Field | Required | Means |
+|---|---|---|
+| `org` | yes | The GitHub organisation. Every repo name is resolved against it. |
+| `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. |
+
+### `human`
+
+Who the staff answer to. There is exactly one.
+
+| Field | Required | Means |
+|---|---|---|
+| `github` | yes | Login. **The mention callers gate on this**, so without it 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. |
+| `role` | no | Prose only. |
+
+### `agent`
+
+Which coding agent runs a session. Either a string, or a map. See
+[choosing a coding agent](agents.md).
+
+| Field | Required | Means |
+|---|---|---|
+| `id` | no | A preset name, or your own label. Defaults to `claude-code-action`. |
+| `install` | if `id` is unknown | Shell command that installs the agent on the runner. |
+| `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. |
+
+Any field given overrides the preset's, so a preset that is right except for one flag needs
+one line.
+
+### `defaults`
+
+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. |
+
+### `staff`
+
+The registry. One inline map per staff member. **This is the org's view of them**; the rest
+lives in their own `staff.yaml`.
+
+| Field | Required | Means |
+|---|---|---|
+| `handle` | yes | Short identifier. Must match the handle in their manifest. |
+| `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. |
+
+`roster hire` appends to this list. An empty list (`staff: []`) is valid and is what a fresh
+org has.
+
+### `repos`
+
+Every repository the org owns, and what it is for.
+
+| Field | Means |
+|---|---|
+| `name` | Repo name, resolved against `org`. |
+| `visibility` | `public` or `private`. `roster doctor` warns when this disagrees with reality. |
+| `role` | `brain`, `product` or `ops`. |
+
+`role: product` is load-bearing: `roster hire` uses it to fill a new staff member's
+`works_in`, and the prompts refer to the product repo by name.
+
+## What reads what
+
+| Reader | Uses |
+|---|---|
+| `compose.mjs` | `org`, `name`, `human`, `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 |
+
+## Editing it
+
+It is yours. `roster upgrade` never touches it: it has no template, because a tenant's registry
+is not something a framework can have an opinion about.
+
+The exception is `roster hire --apply`, which appends a `staff` entry and a `repos` entry.
+Those are inserted textually under the existing keys rather than by re-serialising the file,
+so your comments and formatting survive.