@nanocollective/roster 0.1.0-beta.2 → 0.1.0-beta.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/README.md +8 -0
  2. package/dist/agents-POITEZRI.js +232 -0
  3. package/dist/chunk-FF2WBNNW.js +370 -0
  4. package/dist/chunk-GDAJPOHK.js +562 -0
  5. package/dist/cli.js +3187 -1105
  6. package/dist/compose-5DBEHSEV.js +17 -0
  7. package/dist/connectors-5E5ZMGZV.js +23 -0
  8. package/dist/worker/assets/assets/css/base.css +21 -2
  9. package/dist/worker/assets/assets/css/brain.css +20 -0
  10. package/dist/worker/assets/assets/css/connectors.css +50 -0
  11. package/dist/worker/assets/assets/css/home.css +141 -54
  12. package/dist/worker/assets/assets/css/inbox.css +11 -0
  13. package/dist/worker/assets/assets/css/layout.css +6 -0
  14. package/dist/worker/assets/assets/css/markdown.css +21 -0
  15. package/dist/worker/assets/assets/css/routines.css +40 -0
  16. package/dist/worker/assets/assets/js/api.js +33 -0
  17. package/dist/worker/assets/assets/js/app.js +47 -3
  18. package/dist/worker/assets/assets/js/homesort.js +28 -21
  19. package/dist/worker/assets/assets/js/icons.js +4 -0
  20. package/dist/worker/assets/assets/js/md.js +7 -2
  21. package/dist/worker/assets/assets/js/refcard.js +216 -0
  22. package/dist/worker/assets/assets/js/refresh.js +4 -2
  23. package/dist/worker/assets/assets/js/report.js +51 -0
  24. package/dist/worker/assets/assets/js/state.js +14 -1
  25. package/dist/worker/assets/assets/js/views/connectors.js +290 -0
  26. package/dist/worker/assets/assets/js/views/home.js +368 -152
  27. package/dist/worker/assets/assets/js/views/inbox.js +68 -16
  28. package/dist/worker/assets/assets/js/views/org.js +2 -0
  29. package/dist/worker/assets/assets/js/views/people.js +103 -0
  30. package/dist/worker/assets/assets/js/views/routines.js +378 -0
  31. package/dist/worker/assets/index.html +8 -0
  32. package/dist/worker/index.js +3972 -963
  33. package/docs/README.md +2 -0
  34. package/docs/architecture.md +23 -4
  35. package/docs/commands.md +111 -9
  36. package/docs/concepts.md +2 -1
  37. package/docs/connectors.md +157 -0
  38. package/docs/cost.md +1 -1
  39. package/docs/developing.md +3 -3
  40. package/docs/doctor-codes.md +8 -2
  41. package/docs/export.md +4 -3
  42. package/docs/extending.md +1 -1
  43. package/docs/getting-started.md +19 -2
  44. package/docs/hosting.md +42 -3
  45. package/docs/memory.md +3 -2
  46. package/docs/org-yaml.md +58 -5
  47. package/docs/portal.md +37 -6
  48. package/docs/prompts.md +3 -2
  49. package/docs/routines.md +65 -0
  50. package/docs/security.md +35 -4
  51. package/docs/session-workflow.md +31 -8
  52. package/docs/staff-yaml.md +7 -3
  53. package/docs/troubleshooting.md +1 -1
  54. package/docs/upgrading.md +1 -1
  55. package/docs/writing-a-charter.md +1 -1
  56. package/package.json +2 -1
  57. package/templates/brain/.gitattributes +3 -0
  58. package/templates/brain/.github/workflows/%%STAFF%%-daily.yaml +24 -15
  59. package/templates/brain/.github/workflows/%%STAFF%%-mention.yaml +12 -10
  60. package/templates/brain/CHARTER.md +2 -2
  61. package/templates/brain/STATE.md +16 -0
  62. package/templates/brain/memory/INDEX.md +1 -1
  63. package/templates/brain/staff.yaml +3 -0
  64. package/templates/ops/.gitattributes +3 -0
  65. package/templates/ops/.github/workflows/session.yaml +74 -13
  66. package/templates/ops/agents.mjs +38 -11
  67. package/templates/ops/compose.mjs +60 -2
  68. package/templates/ops/connectors.mjs +722 -0
  69. package/templates/ops/org/operating.md +10 -0
  70. package/templates/ops/org/voice.md +21 -3
  71. package/templates/ops/prompts/_identity.md +20 -0
  72. package/templates/ops/prompts/daily.md +70 -19
  73. package/templates/ops/prompts/mention.md +7 -2
  74. package/templates/ops/status-week.mjs +169 -0
  75. package/templates/portal/css/base.css +21 -2
  76. package/templates/portal/css/brain.css +20 -0
  77. package/templates/portal/css/connectors.css +50 -0
  78. package/templates/portal/css/home.css +141 -54
  79. package/templates/portal/css/inbox.css +11 -0
  80. package/templates/portal/css/layout.css +6 -0
  81. package/templates/portal/css/markdown.css +21 -0
  82. package/templates/portal/css/routines.css +40 -0
  83. package/templates/portal/index.html +8 -0
  84. package/templates/portal/js/api.js +33 -0
  85. package/templates/portal/js/app.js +47 -3
  86. package/templates/portal/js/homesort.js +28 -21
  87. package/templates/portal/js/icons.js +4 -0
  88. package/templates/portal/js/md.js +7 -2
  89. package/templates/portal/js/refcard.js +216 -0
  90. package/templates/portal/js/refresh.js +4 -2
  91. package/templates/portal/js/report.js +51 -0
  92. package/templates/portal/js/state.js +14 -1
  93. package/templates/portal/js/views/connectors.js +290 -0
  94. package/templates/portal/js/views/home.js +368 -152
  95. package/templates/portal/js/views/inbox.js +68 -16
  96. package/templates/portal/js/views/org.js +2 -0
  97. package/templates/portal/js/views/people.js +103 -0
  98. package/templates/portal/js/views/routines.js +378 -0
  99. package/templates/skill/SKILL.md +115 -0
package/docs/README.md CHANGED
@@ -28,6 +28,8 @@ Read in this order.
28
28
  | [Manual steps](manual-steps.md) | What only a person can do, why, and what breaks if it is skipped. |
29
29
  | [Concepts](concepts.md) | The three things you need to know, then the detail. |
30
30
  | [Choosing a coding agent](agents.md) | Claude, Codex, Nanocoder, or anything with a command line. |
31
+ | [Connectors](connectors.md) | Give staff outside services: Sentry, Linear, Stripe and more. |
32
+ | [Routines](routines.md) | More times staff wake beyond the daily round, each with its own job. |
31
33
  | [Writing a charter](writing-a-charter.md) | The one file nothing can generate for you. |
32
34
  | [Extending it](extending.md) | The four seams, and which one to reach for. |
33
35
  | [Memory](memory.md) | The grammar, and why deleting is the maintenance. |
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Architecture"
3
3
  description: "What happens during a run, and the constraint that decided the design."
4
- sidebar_order: 20
4
+ sidebar_order: 21
5
5
  ---
6
6
 
7
7
  # Architecture
@@ -51,12 +51,15 @@ directory copy:
51
51
  clone: the brain with full history, each peer's brain, each product repo.
52
52
  5. `inflight.mjs` lists open pull requests people have on the product repos, so the run
53
53
  does not open competing work on the same files.
54
+ On a daily run, `status-week.mjs` opens this week's status issue if the one in `staff.yaml`
55
+ is from an earlier week. See [the week's status issue](#the-weeks-status-issue).
54
56
  6. `compose.mjs` assembles the prompt from the org layer (`operating`, `guardrails`, `voice`,
55
57
  `business`, and `priorities` when written), the charter, the work in flight, and the
56
58
  fragment for this kind of run.
57
59
  7. `agents.mjs` resolves which coding agent to run and how.
58
60
  8. The agent runs with a shell, `gh` already authenticated, and the whole checkout.
59
- 9. It works, commits, pushes, opens issues, comments, and rewrites its pinned status issue.
61
+ 9. It works, commits, pushes, opens issues, comments, and rewrites `STATE.md` and the body of
62
+ its status issue, which is its report.
60
63
  **The workflow does not commit on its behalf**; the prompt tells it to and it does.
61
64
  10. `run-record.mjs` writes down what the run was: outcome, duration, and turns and cost where
62
65
  the agent reports them. It goes in the job summary and a `roster-run` artifact, which is
@@ -70,7 +73,7 @@ Nothing is stored outside the repos. There is no database and no service.
70
73
  The prompt imposes a shape, and the shape is what makes an unattended run useful.
71
74
 
72
75
  **Boot** is reconstituting a self that has no memory of yesterday. It reads `memory/INDEX.md`
73
- in full, the pinned status issue, and its own charter. That is deliberately all: notes are read
76
+ in full, `STATE.md` (the last run's handover), and its own charter. That is deliberately all: notes are read
74
77
  only when a fact is in play, and the decision log is not boot context at all.
75
78
 
76
79
  This is why memory is one line per fact. Boot context here went from about 52,000 words to
@@ -79,6 +82,22 @@ forever.
79
82
 
80
83
  **Work** is one thing done properly rather than four things started.
81
84
 
85
+ ## The week's status issue
86
+
87
+ Each staff member has one status issue a week, pinned on their tracker. Its body is their
88
+ report, written for you and rewritten by every run: when it was updated, where each priority
89
+ stands, what is on you, what they do next. Nobody comments on it, so there is never a thread to
90
+ scroll; it is one report of where things are.
91
+
92
+ The first daily run of a week (Monday, UTC) opens the new one before the prompt is composed:
93
+ `status-week.mjs` opens it with last week's body, pins it, unpins the old one, takes `keep-open`
94
+ off it, and moves `status_issue:` in `staff.yaml` on and commits that. The run then rewrites last
95
+ week's body as the week in five lines, and closes it. A week whose summary never got written is offered to
96
+ the next run again. The closed issues, labelled `status`, are the history.
97
+
98
+ What the next run needs from this one lives in `STATE.md` in the brain, not in the issue, so
99
+ the issue never has to carry notes the agent wrote to itself.
100
+
82
101
  **Hand off** is the part that makes the next run possible: open the PR, rewrite the status
83
102
  issue (rewrite, not append), reconcile the tracker, update memory only if a fact changed, log
84
103
  real decisions, and write to peers if something touches their patch.
@@ -122,7 +141,7 @@ See [manual steps](manual-steps.md).
122
141
  | `compose.mjs` | the tenant | a run must not depend on npm or on the framework |
123
142
  | `agents.mjs` | the tenant | same |
124
143
  | `runner-plan.mjs` | the tenant | same |
125
- | `inflight.mjs`, `run-record.mjs` | the tenant | same |
144
+ | `inflight.mjs`, `run-record.mjs`, `status-week.mjs` | the tenant | same |
126
145
  | `session.yaml` | the tenant | private reusable workflows are same-org only |
127
146
  | the CLI | the framework | runs on your machine, when you ask it to |
128
147
  | the portal | the framework | reads the tenant's repos from GitHub, as the person using it |
package/docs/commands.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Commands"
3
3
  description: "Every CLI command and flag."
4
- sidebar_order: 8
4
+ sidebar_order: 9
5
5
  ---
6
6
 
7
7
  # Commands
@@ -16,6 +16,33 @@ Every command that changes anything prints a plan and changes nothing unless you
16
16
  `portal` is the exception: it is interactive, and each change there is a button you press after
17
17
  seeing what it will do.
18
18
 
19
+ ## `roster setup`
20
+
21
+ Where setup has got to, and the one thing to do next. Every step is read from GitHub and from
22
+ disk each time, so it never disagrees with the world and it is safe to run as often as you like.
23
+
24
+ ```
25
+ --json the steps as JSON: each with done, who (agent or human), do and command
26
+ --join <org> check out an org that already runs roster, here
27
+ --add-repo <name> add a repo in the org to org.yaml as a product the staff work on
28
+ --dir <path> where the workspace is, or would be
29
+ ```
30
+
31
+ This is what the [SKILL.md install](getting-started.md#with-your-coding-agent) follows: a coding
32
+ agent runs `roster setup --json`, does `next`, and runs it again until `ready` is true. A step
33
+ for a human is one only you can do: signing in, confirming on GitHub, a credential typed in your
34
+ own terminal.
35
+
36
+ ## `roster skill install`
37
+
38
+ Saves Roster's SKILL.md for each coding agent on this machine (Claude Code in
39
+ `~/.claude/skills/roster`, Codex in `~/.codex/skills/roster`), so a later session knows how to
40
+ run Roster without being told. It is the same file as https://roster.nanocollective.org/SKILL.md.
41
+
42
+ ```
43
+ --print print the file instead
44
+ ```
45
+
19
46
  ## `roster fix`
20
47
 
21
48
  Every scanner's findings, as one brief you paste into a coding agent working in this workspace.
@@ -128,6 +155,42 @@ claude setup-token # Claude Code; see docs/agents.md for the others
128
155
  roster credential --apply
129
156
  ```
130
157
 
158
+ ## `roster connector`
159
+
160
+ Give staff an outside service to use in their runs, as an MCP server. See
161
+ [connectors](connectors.md).
162
+
163
+ ```
164
+ roster connector [list]
165
+ roster connector add <name> [--staff <handles>] [--read-only] [--set <field=value>] [--apply]
166
+ roster connector remove <name> [--apply]
167
+ ```
168
+
169
+ ```
170
+ --staff <handles> who gets it, comma separated (default: the catalogue's suggestion)
171
+ --read-only hold it to reading, for everybody who has it
172
+ --set <field=value> a setting the service needs, such as --set project_ref=abc123
173
+ --url <url> a service roster does not know: its MCP server's URL
174
+ --command <line> or the command that starts it
175
+ --secret <NAME> a key that service needs, by the name it is given (repeatable)
176
+ --keep-key change who has it without asking for the key again
177
+ --apply do it
178
+ ```
179
+
180
+ `list` shows the services roster knows and the ones this org has, with who has each and whether
181
+ its key is stored. `add` asks for the key at a prompt that does not echo, checks it with the
182
+ service, stores it as a GitHub secret every brain repo can read, and commits `org.yaml`. A key
183
+ the service rejects is not stored. `remove` deletes the keys and takes the connector out of
184
+ `org.yaml`.
185
+
186
+ ```bash
187
+ roster connector add sentry --staff cto --apply
188
+ roster connector add supabase --set project_ref=abc123 --read-only --apply
189
+ ```
190
+
191
+ Notion's hosted server signs in with a browser, so it is added from the hosted portal's
192
+ Connectors page.
193
+
131
194
  ## `roster run <handle>`
132
195
 
133
196
  Start one daily run now and follow it to the end.
@@ -144,6 +207,24 @@ work, so its "unproven" warning goes away. It is a real run and spends what a sc
144
207
  would, which is why it needs `--apply`. The staff card and Health have the same as
145
208
  **Run once now**.
146
209
 
210
+ ## `roster routine <handle>`
211
+
212
+ When a staff member wakes beyond the daily round, and what they do then. With no action it
213
+ lists their daily round and routines.
214
+
215
+ ```
216
+ add --name <n> --at <cron> --do <text> a new routine; --do-file <path> reads the text from a file
217
+ remove <id> take one away
218
+ daily <cron> move the daily round
219
+ run <id> start one routine now
220
+ --apply write, commit and push the brain repo
221
+ --ops <dir> ops repo directory
222
+ ```
223
+
224
+ Times are five-field cron in UTC. A change writes `staff.yaml`, `routines/<id>.md` and the
225
+ daily caller together, so the schedule GitHub fires on is always the one in the manifest. The
226
+ portal's **Routines** screen does the same with a picker. See [routines](routines.md).
227
+
147
228
  ## `roster retire <handle>`
148
229
 
149
230
  Stop a staff member without destroying anything.
@@ -269,15 +350,19 @@ ROSTER_CONTEXT='{"issue_number":"1","comment_id":"1","repo":"o/r"}' \
269
350
 
270
351
  ## `roster portal`
271
352
 
272
- Serve a local UI over the checked-out repositories. **`roster` with no arguments does the same**,
273
- which is the shortest way in. It takes the same flags: `roster --no-open` is `roster portal
274
- --no-open`.
353
+ Serve the portal on your machine. **`roster` with no arguments does the same**, which is the
354
+ shortest way in. It takes the same flags: `roster --no-open` is `roster portal --no-open`.
355
+
356
+ It reads the org from GitHub as you, with your `gh` login (or `GITHUB_TOKEN`), so it needs no
357
+ checkout to show it. Setting up, hiring, retiring and Health use the checkout.
275
358
 
276
359
  ```
277
- --port <n> default 4300
278
- --host <a> default 127.0.0.1. Anything else exposes write actions to the network.
279
- --dir <path> where a tenant would be created or checked out. Default: here.
280
- --no-open don't open a browser
360
+ --port <n> default 4300
361
+ --host <a> default 127.0.0.1. Anything else exposes write actions to the network.
362
+ --dir <path> where a tenant would be created or checked out. Default: here.
363
+ --org <org> show this org, with no checkout. Default: the checkout's org.yaml.
364
+ --ops-repo <n> its ops repo, with --org. Default: roster-ops.
365
+ --no-open don't open a browser
281
366
  ```
282
367
 
283
368
  It opens the page in your browser when it starts. It stays closed in CI, over SSH, when output
@@ -288,11 +373,28 @@ checks out one that already runs roster. Local only. See [the portal](portal.md)
288
373
 
289
374
  Views: Home, Trackers, Runs, Org, Staff, Docs, and per staff member Brain, Prompt, Graph, What changed, Health.
290
375
 
291
- It can act as you through your own `gh`: reply, close, reopen and open issues; hire and retire;
376
+ It can act as you: reply, close, reopen and open issues; hire and retire;
292
377
  edit and commit the org layer, prompt fragments and charters; create a staff member's GitHub App;
293
378
  store the agent credential; set the ops repo's Actions access; start one run and follow it; and
294
379
  copy a prompt for authoring the two files nothing can generate.
295
380
 
381
+ ## `roster portal deploy`
382
+
383
+ The same portal on your own URL, on Cloudflare Workers, behind Sign in with GitHub. Only the
384
+ people in `org.yaml`'s `humans:` can sign in, and each acts as themselves. Setting up, hiring
385
+ and Health stay on your machine.
386
+
387
+ ```
388
+ --domain <host> where it lives, on a zone in your Cloudflare account. Needed the first time.
389
+ --account <id> the Cloudflare account, pinned so a deploy cannot land on another one
390
+ --apply deploy. Without it, says what it would do.
391
+ --ci no questions: deploy what portal/wrangler.jsonc says (the workflow uses this)
392
+ ```
393
+
394
+ The first deploy walks you through creating the GitHub OAuth App, then writes
395
+ `portal/wrangler.jsonc` and a workflow that redeploys every morning. See
396
+ [hosting the portal](hosting.md).
397
+
296
398
  ## `roster export`
297
399
 
298
400
  The whole org as one JSON document.
package/docs/concepts.md CHANGED
@@ -40,7 +40,7 @@ commits and pushes. A change here reaches everybody on their next run, which is
40
40
  rule every staff member should follow is one edit, not one per repo.
41
41
 
42
42
  **Everything else is machinery** and belongs to the framework: `compose.mjs`, `agents.mjs`,
43
- `runner-plan.mjs`, `inflight.mjs`, `run-record.mjs`, `.github/workflows/session.yaml`. Editing these works right up until the
43
+ `runner-plan.mjs`, `inflight.mjs`, `run-record.mjs`, `status-week.mjs`, `.github/workflows/session.yaml`. Editing these works right up until the
44
44
  framework changes the same file, at which point your change is a conflict at best and silently
45
45
  reverted at worst. Fix machinery in the framework, then `roster upgrade`.
46
46
 
@@ -131,6 +131,7 @@ What starts a run:
131
131
  | Trigger | Runs | Counts against `max_runs_per_day` |
132
132
  |---|---|---|
133
133
  | the schedule | `daily` | no |
134
+ | a [routine](routines.md)'s time | `daily`, framed as that routine | no |
134
135
  | **Run once now**, or Actions → Run workflow | `daily` | no |
135
136
  | a person writing `@handle` on the staff member's tracker | `mention` | no |
136
137
  | a peer opening an issue there with their `from-<handle>` label | `mention`, framed as a peer's ask | yes |
@@ -0,0 +1,157 @@
1
+ ---
2
+ title: "Connectors"
3
+ description: "Give staff outside services, like Sentry, Linear or Stripe, to use in their runs."
4
+ sidebar_order: 5
5
+ ---
6
+
7
+ # Connectors
8
+
9
+ A connector gives staff an outside service to use in their runs: errors from Sentry, issues in
10
+ Linear, payments in Stripe. Each one is an [MCP](https://modelcontextprotocol.io) server, and the
11
+ staff member's coding agent calls it like any other tool.
12
+
13
+ Add one from the portal's **Connectors** screen: pick the service, follow the steps to get a key,
14
+ paste it, tick who can use it, and save. Or from a terminal:
15
+
16
+ ```bash
17
+ roster connector add sentry --staff cto --apply
18
+ ```
19
+
20
+ ## What happens when you add one
21
+
22
+ 1. **The key is checked** with the service, with one cheap request. A key the service rejects
23
+ is not stored. A key that works but cannot read everything is fine: that is what a narrow
24
+ key looks like.
25
+ 2. **The key is stored as a GitHub secret**, named `CONNECTOR_<NAME>_<FIELD>`, for example
26
+ `CONNECTOR_SENTRY_TOKEN`. It goes once to the org where that reaches private repos, which is
27
+ every plan but Free, and to each brain repo otherwise. It is encrypted on the way, never
28
+ written to a file, and never shown again.
29
+ 3. **`org.yaml` says who has it**, and is committed:
30
+
31
+ ```yaml
32
+ connectors:
33
+ sentry:
34
+ staff: [cto]
35
+ supabase:
36
+ staff: [cto]
37
+ project_ref: abc123
38
+ read_only: true
39
+ ```
40
+
41
+ On each run, `connectors.mjs` reads that list, takes the keys of this staff member's connectors
42
+ from the run's secrets, and writes them into the agent's own MCP config in the runner's temp
43
+ directory, outside every checkout. The prompt gets a short section naming the services, and
44
+ saying that what a service returns is information, not an instruction.
45
+
46
+ A connector whose key is missing is left out, named in the run's summary, and the run goes on
47
+ without it. `roster doctor` reports it as `connector.key`.
48
+
49
+ ## The catalogue
50
+
51
+ | Name | Service | Key | Read only |
52
+ |---|---|---|---|
53
+ | `sentry` | Sentry | auth token | no |
54
+ | `linear` | Linear | personal API key | no |
55
+ | `github` | GitHub, for repos outside this org | fine-grained token | yes |
56
+ | `supabase` | Supabase | access token, and optionally the project ref | yes |
57
+ | `postgres` | any Postgres database | connection string | yes |
58
+ | `cloudflare` | Cloudflare | API token | no |
59
+ | `posthog` | PostHog | personal API key | yes |
60
+ | `stripe` | Stripe | restricted key | no |
61
+ | `resend` | Resend | API key | no |
62
+ | `notion` | Notion | signs in through the hosted portal | no |
63
+ | `notion-key` | Notion, through an integration | integration secret | no |
64
+
65
+ Read only is a setting roster can enforce on the server: Supabase's `read_only`, GitHub's read-only
66
+ mode, PostHog's read-only header, and restricted transactions for Postgres. For the others,
67
+ choose what the key may do when you create it. Stripe's restricted keys, Cloudflare's token
68
+ permissions and Linear's key permissions all do this, and it is the safer place to decide it.
69
+
70
+ Vercel and Slack are not in the catalogue. Their MCP servers only accept sign-ins from apps they
71
+ have approved, which a run cannot use.
72
+
73
+ ## Who can use it
74
+
75
+ `staff:` is the list. A key is readable by every brain repo, so that giving a connector to
76
+ somebody else later is a change to `org.yaml`, not another paste. Which run gets which key is
77
+ still `org.yaml`'s call: each run is given only its own staff member's connectors.
78
+
79
+ `read_only: true` holds a connector to reading for everybody who has it. A staff member whose
80
+ [permissions](agents.md#permissions) are `read-only` gets every connector held to reading, and a
81
+ connector that cannot be held to reading is left out for them.
82
+
83
+ ## Each agent
84
+
85
+ The same list, in each agent's own words:
86
+
87
+ | Agent | How it is given the servers |
88
+ |---|---|
89
+ | `claude-code-action`, `claude` | `--mcp-config` with a JSON file, and `mcp__<name>` added to `--allowedTools` |
90
+ | `codex` | a `config.toml` in a fresh `CODEX_HOME`; `CODEX_API_KEY` still signs it in |
91
+ | `nanocoder` | `NANOCODER_MCPSERVERS_FILE`, pointing at its own format |
92
+
93
+ Nanocoder only shows MCP tools to a model whose tool profile resolves to `full`. A small local
94
+ model may not see them.
95
+
96
+ ## Signing in: Notion
97
+
98
+ Notion's hosted MCP server takes no key: it signs in with a browser. A run cannot do that, so the
99
+ [hosted portal](hosting.md) does it once and keeps the sign-in:
100
+
101
+ 1. On the Connectors screen, pick Notion, tick who can use it, and press **Sign in to Notion**.
102
+ 2. Notion asks which pages to share. The portal keeps the sign-in, sealed under its session key,
103
+ in a KV namespace of its own.
104
+ 3. Each run asks the portal for a fresh access token. It proves which run it is with GitHub's own
105
+ OIDC token, and the portal only answers a run of this org's `session.yaml`. No secret is
106
+ shared with the run to make that work.
107
+
108
+ This needs the hosted portal, with a KV namespace bound as `CONNECTORS`. `roster portal deploy`
109
+ creates one. A sign-in Notion has not used for 30 days, or one older than 180 days, has to be
110
+ done again; the Connectors screen says so.
111
+
112
+ Without the hosted portal, use `notion-key`: an internal integration's secret, pasted like any
113
+ other key.
114
+
115
+ ## A service that is not in the catalogue
116
+
117
+ Write it out in `org.yaml`, with a `url` or a `command`, and the names of the keys it needs:
118
+
119
+ ```yaml
120
+ connectors:
121
+ acme-api:
122
+ staff: [cto]
123
+ url: https://mcp.acme.dev/mcp
124
+ secrets: [TOKEN]
125
+ headers:
126
+ Authorization: "Bearer ${TOKEN}"
127
+ local-thing:
128
+ staff: [cmo]
129
+ command: npx -y @acme/mcp-server
130
+ secrets: [API_KEY]
131
+ env:
132
+ ACME_API_KEY: "${API_KEY}"
133
+ ```
134
+
135
+ `${TOKEN}` is replaced with the secret `CONNECTOR_ACME_API_TOKEN` in the run. Store it with:
136
+
137
+ ```bash
138
+ roster connector add acme-api --url https://mcp.acme.dev/mcp --secret TOKEN --apply
139
+ ```
140
+
141
+ A name is lower case letters, digits and `-`, because it becomes part of each tool's name.
142
+
143
+ ## Safety
144
+
145
+ - Text a service returns is treated as information. The prompt says so, and says that anything
146
+ acting in public under your name, like sending an email or charging a customer, needs a
147
+ `decision` issue first.
148
+ - Give each key the least it needs. A read-only key is a limit no prompt can talk its way past.
149
+ - The agent can read its own MCP config, and so its keys, in the run. Treat a connector's key as
150
+ given to the staff members who have it.
151
+ - Removing a connector deletes its keys and its sign-in, and takes it out of `org.yaml`.
152
+
153
+ ## Callers from before connectors
154
+
155
+ Keys reach a run because the callers pass their secrets on with `secrets: inherit`. Callers
156
+ generated before connectors map their secrets by hand, so no connector's key reaches them;
157
+ `roster doctor` reports it as `connector.caller`, and `roster upgrade --apply` regenerates them.
package/docs/cost.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Cost"
3
3
  description: "What an agent-run org spends, and on what."
4
- sidebar_order: 12
4
+ sidebar_order: 13
5
5
  ---
6
6
 
7
7
  # Cost
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Working on roster itself"
3
3
  description: "Layout, template classes, and the rules that matter."
4
- sidebar_order: 22
4
+ sidebar_order: 23
5
5
  ---
6
6
 
7
7
  # Working on roster itself
@@ -80,8 +80,8 @@ registers into at boot.
80
80
 
81
81
  ## The rule that matters
82
82
 
83
- **Never fix a generated file in a tenant.** `compose.mjs`, `agents.mjs`, `runner-plan.mjs`,
84
- `inflight.mjs`, `run-record.mjs` and `session.yaml` live in `templates/ops/`. Fix them there and run `roster upgrade`.
83
+ **Never fix a generated file in a tenant.** `compose.mjs`, `agents.mjs`, `connectors.mjs`, `runner-plan.mjs`,
84
+ `inflight.mjs`, `run-record.mjs`, `status-week.mjs` and `session.yaml` live in `templates/ops/`. Fix them there and run `roster upgrade`.
85
85
 
86
86
  A fix made in the tenant's copy goes unnoticed until the framework next touches that file, and
87
87
  then it is a conflict. So `roster upgrade` reports an edit to a framework-owned file whether or
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "doctor codes"
3
3
  description: "Every finding roster doctor can emit, what it means, and what to do."
4
- sidebar_order: 19
4
+ sidebar_order: 20
5
5
  ---
6
6
 
7
7
  # doctor codes
@@ -25,12 +25,14 @@ ran at all.
25
25
  |---|---|
26
26
  | `gh` | Whether `gh` is installed and authenticated. A warning here means every network check was skipped, not that anything is wrong. |
27
27
  | `org.yaml` | The org manifest parsed, and how much it declares. |
28
- | `human` | **fail.** `org.yaml` names nobody with a `github` login, in either `human` or `humans`. The mention callers gate on those logins, so nothing can wake an agent. |
28
+ | `human` | **fail.** `org.yaml` names nobody with a `github` login, in either `human` or `humans`, who is not `view_only`. The mention callers gate on those logins, so nothing can wake an agent. |
29
29
  | `human.login` | One of the people in `humans` has a name but no `github` login. They read as somebody the staff answer to and are not: the gate can never match them. |
30
30
  | `repo` | Every repo in `org.yaml` is reachable. A failure means it does not exist or your `gh` cannot see it. |
31
31
  | `repo.visibility` | A repo's real visibility disagrees with what `org.yaml` records. Cosmetic, but the posture it records is then fiction. |
32
32
  | `agent` | Which runner this org uses, resolved from the tenant's own `agents.mjs`. **fail** if `org.yaml` names one it does not know. |
33
33
  | `agent.config` | **fail.** The agent needs a config file of its own and it is missing, or still has a `FILL IN` in it. Nanocoder is the one preset that does: it is a client rather than a model, so without a provider it starts, finds nothing to call, and exits. |
34
+ | `connector` | Each [connector](connectors.md) in `org.yaml` is usable: in the catalogue or written out with a `url` or `command`, with any setting it needs. A run leaves out one that is not. |
35
+ | `connector.staff` | A connector is given to a handle that is not one of the staff. |
34
36
  | `business` | **fail** if `org/business.md` is missing. Every prompt is composed on top of it. |
35
37
  | `business.stub` | `org/business.md` is still the questions it shipped with. Nothing errors; the agents just write competent work about a business that does not exist. |
36
38
  | `priorities` | No `org/priorities.md`. Nothing breaks; each staff member just picks its own direction. See [concepts](concepts.md#priorities). |
@@ -58,12 +60,16 @@ ran at all.
58
60
  | `memory` | `memory/INDEX.md` parses, and how many facts and notes it holds. |
59
61
  | `compose` | All three prompts compose. A failure names the kind and the placeholder. |
60
62
  | `callers` | Three caller workflows exist. |
63
+ | `connector.key` | A connector this staff member has has no key on their brain repo, neither its own secret nor one shared from the org. The run goes ahead without it. |
64
+ | `connector.caller` | This staff member has connectors, and their callers were generated before connectors: they map their secrets by hand rather than passing them on, so no key reaches a run. `roster upgrade --apply`. |
61
65
  | `callers.uses` | **fail.** A caller references no reusable workflow, or one in a different organisation. A private reusable workflow is only callable inside its own org. |
62
66
  | `callers.target` | **fail.** A caller points at a workflow file that is not in the ops repo. Fails at run time as "workflow not found". |
63
67
  | `surfaces` | A surface declared in `staff.yaml` is not on disk. The portal renders nothing for it. |
64
68
  | `secrets` | Every secret the callers reference exists on the brain repo, or is an organisation secret shared with it. Derived from the callers themselves, not a fixed list. |
65
69
  | `labels` | Every label declared in `staff.yaml` exists. An agent applying a label that does not exist gets an API error mid-run. |
66
70
  | `owned-labels` | Roster's own labels exist on the tracker: `decision`, `review`, `chore` and `keep-open`. Checked whatever `staff.yaml` declares, since the prompts apply them. The fix is the `gh label create` lines. |
71
+ | `person-labels` | Every person's label (their `marker` in `org.yaml`) exists on the tracker. Staff send an ask to someone by labelling it for them, and `gh` refuses a label that does not exist. The portal's People form creates them; the fix is the `gh label create` lines. |
72
+ | `humans-variable` | **fail.** The `ROSTER_HUMANS` Actions variable on the tracker names different people from `org.yaml`. The mention callers prefer the variable, which the portal's People form sets, so a person added to `org.yaml` by hand cannot wake anybody until it matches. Not checked when the variable is unset. The fix is the `gh variable set` line, or saving People in the portal. |
67
73
  | `ask-kind` | An open issue assigned to a human has no ask kind, or more than one. Home sorts what needs you by kind, so an ask without one lands nowhere. |
68
74
  | `peer-labels` | The `from-<handle>` label exists on the *peer's* tracker, which is where this staff member's asks land. |
69
75
  | `status-issue` | The declared status issue is actually pinned. If not, the place you look is not the place the agent maintains. |
package/docs/export.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "roster export reference"
3
3
  description: "The JSON shape, field by field."
4
- sidebar_order: 18
4
+ sidebar_order: 19
5
5
  ---
6
6
 
7
7
  # `roster export` reference
@@ -22,8 +22,9 @@ that reads it gets the same view without reimplementing the memory grammar.
22
22
  | `org` | the GitHub organisation |
23
23
  | `name` | the business name |
24
24
  | `opsName` | the ops repo's directory, so a consumer can address `org.yaml` and `org/*.md` by path |
25
- | `human` | the first human, normalised: `{ github, name, marker, role }`. Kept for consumers written when an org had exactly one |
26
- | `humans[]` | everyone the staff answer to, in order, read from `humans` or the singular `human`. `human` is `humans[0]` |
25
+ | `human` | the first human, normalised: `{ github, name, marker, role, handles }`. Kept for consumers written when an org had exactly one |
26
+ | `humans[]` | everyone the staff answer to, in order, read from `humans` or the singular `human`, leaving out anyone `view_only`. `human` is `humans[0]` |
27
+ | `people[]` | everyone in `org.yaml`, `view_only` included (as `viewOnly: true`), with `handles` where set. What the portal's People form edits |
27
28
  | `generatedAt` | ISO timestamp |
28
29
  | `staff[]` | one entry per staff member |
29
30
 
package/docs/extending.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Extending it"
3
3
  description: "The four seams, and which one to reach for."
4
- sidebar_order: 6
4
+ sidebar_order: 7
5
5
  ---
6
6
 
7
7
  # Extending it for your business
@@ -20,10 +20,25 @@ each a conversation of twenty to thirty minutes with your own AI. The rest is ab
20
20
  clicks and waiting for the run. Those two files are what make the staff worth running, so that
21
21
  hour is the part not to rush.
22
22
 
23
+ ## With your coding agent
24
+
25
+ Paste this into Claude Code, Codex, Cursor or Gemini CLI on your computer:
26
+
27
+ ```
28
+ set up https://roster.nanocollective.org/SKILL.md
29
+ ```
30
+
31
+ The agent installs roster and walks through the same steps as below, one at a time. It runs
32
+ `roster setup --json` to see what is next, interviews you for the business, priorities and
33
+ charter using the same briefs, and hands you the parts only you can do: signing in to `gh`,
34
+ confirming each GitHub App, and typing your agent's credential in your own terminal. It never
35
+ asks for a token in chat. When it is done it opens the portal.
36
+
23
37
  ## Before you start
24
38
 
25
- - **`gh`, [signed in](https://cli.github.com)**, as someone who owns the organisation. roster
26
- does everything through your own `gh` and holds no token of its own.
39
+ - **`gh`, [signed in](https://cli.github.com)**, as someone who owns the organisation. Setting
40
+ up, hiring and the GitHub Apps go through your own `gh`, and the portal on your machine uses
41
+ its token to act as you. roster keeps no token of its own.
27
42
  - **A GitHub organisation.** GitHub has no API for creating one, so if you need one, make it on
28
43
  github.com first. Brains are private repos; on GitHub Free that works, with one difference in
29
44
  step 5.
@@ -187,3 +202,5 @@ each.
187
202
  - **A framework update**: `roster upgrade`, or the same from the portal. See
188
203
  [upgrading](upgrading.md).
189
204
  - **The whole portal**, screen by screen: [the portal](portal.md).
205
+ - **The portal on your own URL**, so you can answer your staff from anywhere, your phone
206
+ included: `roster portal deploy`. See [hosting the portal](hosting.md).
package/docs/hosting.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Hosting the portal"
3
3
  description: "The portal on your own URL, behind Sign in with GitHub, redeploying itself."
4
- sidebar_order: 11
4
+ sidebar_order: 12
5
5
  ---
6
6
 
7
7
  # Hosting the portal
@@ -35,10 +35,12 @@ does. That is not something to put behind a public URL.
35
35
  ## Who can get in
36
36
 
37
37
  Only the people listed under `humans:` in `org.yaml`, signed in with their own GitHub account.
38
+ That includes anyone marked `view_only`, who can read everything and wake nobody; see
39
+ [org.yaml](org-yaml.md#human-and-humans).
38
40
 
39
41
  - Sign-in is GitHub's own OAuth flow, through an OAuth App your org creates for the portal.
40
- The token it hands back is that person's, scoped `repo` and `notifications`, the same kind
41
- `gh` holds on their machine.
42
+ The token it hands back is that person's, scoped `repo`, `notifications` and `workflow`, the
43
+ same kind `gh` holds on their machine.
42
44
  - Everything they do is as themselves. A reply is theirs, a merge is theirs, and what they can
43
45
  read is what GitHub lets them read.
44
46
  - Somebody who signs in and is not one of the humans, or cannot read the ops repo, is turned
@@ -48,6 +50,31 @@ Only the people listed under `humans:` in `org.yaml`, signed in with their own G
48
50
 
49
51
  See [security](security.md#the-hosted-portal) for what is held where.
50
52
 
53
+ ## Talking to your staff from Claude
54
+
55
+ The hosted portal is also an MCP server, at `/mcp`. Add it to Claude as a custom connector with
56
+ the URL `https://roster.acme.com/mcp`. Claude sends you to sign in with GitHub, the same check
57
+ against `humans:` as the portal, and then to a page that says what it will be able to do, with
58
+ **Allow**.
59
+
60
+ Then you can ask Claude things like "what needs me today?", "what did the CTO do?" or "tell the
61
+ CMO to draft this week's post". The tools:
62
+
63
+ | Tool | Does |
64
+ |---|---|
65
+ | `brief` | Each staff member's report, what needs you (with each decision's default), your requests, what was closed today |
66
+ | `read_thread` | One issue or pull request with every reply |
67
+ | `reply` | A reply as you, optionally closing the issue |
68
+ | `ask_staff` | A new issue on a staff member's tracker with their mention, which starts them |
69
+ | `ask_for_report` | Asks a staff member to bring their report up to date now |
70
+ | `read_brain` | `STATE.md`, `CHARTER.md`, `memory/INDEX.md`, `log/decisions.md` or `staff.yaml` |
71
+
72
+ It cannot merge, approve, hire, or change the org: those stay on Home, where you see the diff
73
+ or the plan first. Everything it posts is posted as you.
74
+
75
+ Nothing to set up beyond the portal itself: the connector signs in through the same OAuth App,
76
+ on a callback under the one you registered (`/auth/callback/mcp`), which GitHub accepts.
77
+
51
78
  ## Deploying it
52
79
 
53
80
  You need a Cloudflare account with the domain on it, and wrangler signed in to it. If your
@@ -105,6 +132,18 @@ On your machine it is `~/.cache/roster`. On Cloudflare it is the edge cache, whi
105
132
  setup. To keep it everywhere rather than per data centre, bind a KV namespace as `CACHE` in
106
133
  `portal/wrangler.jsonc`.
107
134
 
135
+ ## Signed-in connectors
136
+
137
+ A [connector](connectors.md) that signs in with a browser, like Notion, keeps its sign-in on the
138
+ hosted portal, which needs somewhere durable to keep it: a KV namespace bound as `CONNECTORS`.
139
+ `roster portal deploy` finds one by name, or creates it, on any deploy that does not have it
140
+ bound yet, the morning one included; a deploy by hand also writes it into
141
+ `portal/wrangler.jsonc`. Without it, connectors that take a key still work, and the ones that
142
+ sign in are not offered.
143
+
144
+ A run collects a fresh access token from `/connectors/token`, proving with GitHub's OIDC token
145
+ that it is a run of this org's `session.yaml`.
146
+
108
147
  ## On your machine
109
148
 
110
149
  `roster portal` binds to `127.0.0.1` and acts as whoever `gh` is signed in as. To open an org
package/docs/memory.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Memory"
3
3
  description: "The grammar, the five rules, and why deleting is the maintenance."
4
- sidebar_order: 7
4
+ sidebar_order: 8
5
5
  ---
6
6
 
7
7
  # Memory
@@ -69,7 +69,8 @@ hand-off and make pruning that run's job when it is over.
69
69
  - **How a thing works.** That is a draft or a strategy document.
70
70
  - **An idea not yet acted on.** That is one line in `strategy/ideas.md`, and it becomes an issue
71
71
  only when it needs a ruling.
72
- - **What is outstanding.** That is the pinned status issue.
72
+ - **What is outstanding.** That is `STATE.md`, the handover each daily run rewrites. The pinned
73
+ status issue is the same picture written for you.
73
74
 
74
75
  Nothing is copied between them. Four places, four jobs, and a fact that appears in two of them
75
76
  will disagree with itself within a month.