@nanocollective/roster 0.1.0-beta.2 → 0.1.0-beta.22
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.
- package/README.md +8 -0
- package/dist/agents-POITEZRI.js +232 -0
- package/dist/chunk-FF2WBNNW.js +370 -0
- package/dist/chunk-GDAJPOHK.js +562 -0
- package/dist/cli.js +3187 -1105
- package/dist/compose-5DBEHSEV.js +17 -0
- package/dist/connectors-5E5ZMGZV.js +23 -0
- package/dist/worker/assets/assets/css/astryx.css +948 -0
- package/dist/worker/assets/assets/css/base.css +64 -110
- package/dist/worker/assets/assets/css/brain.css +26 -2
- package/dist/worker/assets/assets/css/connectors.css +50 -0
- package/dist/worker/assets/assets/css/graph.css +9 -12
- package/dist/worker/assets/assets/css/health.css +4 -7
- package/dist/worker/assets/assets/css/home.css +145 -60
- package/dist/worker/assets/assets/css/inbox.css +11 -0
- package/dist/worker/assets/assets/css/layout.css +16 -20
- package/dist/worker/assets/assets/css/markdown.css +22 -1
- package/dist/worker/assets/assets/css/routines.css +40 -0
- package/dist/worker/assets/assets/css/runs.css +5 -3
- package/dist/worker/assets/assets/css/search.css +3 -6
- package/dist/worker/assets/assets/css/setup.css +3 -15
- package/dist/worker/assets/assets/js/api.js +33 -0
- package/dist/worker/assets/assets/js/app.js +49 -3
- package/dist/worker/assets/assets/js/astryx-ui.js +34 -0
- package/dist/worker/assets/assets/js/homesort.js +28 -21
- package/dist/worker/assets/assets/js/icons.js +6 -0
- package/dist/worker/assets/assets/js/md.js +7 -2
- package/dist/worker/assets/assets/js/refcard.js +216 -0
- package/dist/worker/assets/assets/js/refresh.js +4 -2
- package/dist/worker/assets/assets/js/report.js +51 -0
- package/dist/worker/assets/assets/js/select.js +362 -0
- package/dist/worker/assets/assets/js/state.js +14 -1
- package/dist/worker/assets/assets/js/views/connectors.js +290 -0
- package/dist/worker/assets/assets/js/views/graph.js +67 -28
- package/dist/worker/assets/assets/js/views/home.js +378 -176
- package/dist/worker/assets/assets/js/views/inbox.js +68 -16
- package/dist/worker/assets/assets/js/views/org.js +2 -0
- package/dist/worker/assets/assets/js/views/people.js +109 -0
- package/dist/worker/assets/assets/js/views/routines.js +378 -0
- package/dist/worker/assets/assets/js/views/runs.js +3 -1
- package/dist/worker/assets/docs-images/brain.jpg +0 -0
- package/dist/worker/assets/docs-images/home.jpg +0 -0
- package/dist/worker/assets/docs-images/org.jpg +0 -0
- package/dist/worker/assets/docs-images/prompt.jpg +0 -0
- package/dist/worker/assets/docs-images/setup-org.jpg +0 -0
- package/dist/worker/assets/docs-images/setup-plan.jpg +0 -0
- package/dist/worker/assets/docs-images/staff.jpg +0 -0
- package/dist/worker/assets/index.html +16 -1
- package/dist/worker/index.js +3972 -963
- package/docs/README.md +2 -0
- package/docs/architecture.md +23 -4
- package/docs/commands.md +111 -9
- package/docs/concepts.md +2 -1
- package/docs/connectors.md +157 -0
- package/docs/cost.md +1 -1
- package/docs/developing.md +3 -3
- package/docs/doctor-codes.md +8 -2
- package/docs/export.md +4 -3
- package/docs/extending.md +1 -1
- package/docs/getting-started.md +20 -3
- package/docs/hosting.md +42 -3
- package/docs/images/brain.jpg +0 -0
- package/docs/images/home.jpg +0 -0
- package/docs/images/org.jpg +0 -0
- package/docs/images/prompt.jpg +0 -0
- package/docs/images/setup-org.jpg +0 -0
- package/docs/images/setup-plan.jpg +0 -0
- package/docs/images/staff.jpg +0 -0
- package/docs/memory.md +3 -2
- package/docs/org-yaml.md +58 -5
- package/docs/portal.md +43 -10
- package/docs/prompts.md +3 -2
- package/docs/routines.md +65 -0
- package/docs/security.md +35 -4
- package/docs/session-workflow.md +31 -8
- package/docs/staff-yaml.md +7 -3
- package/docs/troubleshooting.md +1 -1
- package/docs/upgrading.md +1 -1
- package/docs/writing-a-charter.md +1 -1
- package/package.json +8 -1
- package/templates/brain/.gitattributes +3 -0
- package/templates/brain/.github/workflows/%%STAFF%%-daily.yaml +24 -15
- package/templates/brain/.github/workflows/%%STAFF%%-mention.yaml +12 -10
- package/templates/brain/CHARTER.md +2 -2
- package/templates/brain/STATE.md +16 -0
- package/templates/brain/memory/INDEX.md +1 -1
- package/templates/brain/staff.yaml +3 -0
- package/templates/ops/.gitattributes +3 -0
- package/templates/ops/.github/workflows/session.yaml +74 -13
- package/templates/ops/agents.mjs +38 -11
- package/templates/ops/compose.mjs +60 -2
- package/templates/ops/connectors.mjs +722 -0
- package/templates/ops/org/operating.md +10 -0
- package/templates/ops/org/voice.md +21 -3
- package/templates/ops/prompts/_identity.md +20 -0
- package/templates/ops/prompts/daily.md +70 -19
- package/templates/ops/prompts/mention.md +7 -2
- package/templates/ops/status-week.mjs +169 -0
- package/templates/portal/css/astryx.css +948 -0
- package/templates/portal/css/base.css +64 -110
- package/templates/portal/css/brain.css +26 -2
- package/templates/portal/css/connectors.css +50 -0
- package/templates/portal/css/graph.css +9 -12
- package/templates/portal/css/health.css +4 -7
- package/templates/portal/css/home.css +145 -60
- package/templates/portal/css/inbox.css +11 -0
- package/templates/portal/css/layout.css +16 -20
- package/templates/portal/css/markdown.css +22 -1
- package/templates/portal/css/routines.css +40 -0
- package/templates/portal/css/runs.css +5 -3
- package/templates/portal/css/search.css +3 -6
- package/templates/portal/css/setup.css +3 -15
- package/templates/portal/index.html +16 -1
- package/templates/portal/js/api.js +33 -0
- package/templates/portal/js/app.js +49 -3
- package/templates/portal/js/astryx-ui.js +34 -0
- package/templates/portal/js/homesort.js +28 -21
- package/templates/portal/js/icons.js +6 -0
- package/templates/portal/js/md.js +7 -2
- package/templates/portal/js/refcard.js +216 -0
- package/templates/portal/js/refresh.js +4 -2
- package/templates/portal/js/report.js +51 -0
- package/templates/portal/js/select.js +362 -0
- package/templates/portal/js/state.js +14 -1
- package/templates/portal/js/views/connectors.js +290 -0
- package/templates/portal/js/views/graph.js +67 -28
- package/templates/portal/js/views/home.js +378 -176
- package/templates/portal/js/views/inbox.js +68 -16
- package/templates/portal/js/views/org.js +2 -0
- package/templates/portal/js/views/people.js +109 -0
- package/templates/portal/js/views/routines.js +378 -0
- package/templates/portal/js/views/runs.js +3 -1
- 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. |
|
package/docs/architecture.md
CHANGED
|
@@ -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:
|
|
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
|
|
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
|
|
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:
|
|
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
|
|
273
|
-
|
|
274
|
-
|
|
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>
|
|
278
|
-
--host <a>
|
|
279
|
-
--dir <path>
|
|
280
|
-
--no
|
|
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
|
|
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
package/docs/developing.md
CHANGED
|
@@ -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:
|
|
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
|
package/docs/doctor-codes.md
CHANGED
|
@@ -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:
|
|
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:
|
|
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
package/docs/getting-started.md
CHANGED
|
@@ -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.
|
|
26
|
-
|
|
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.
|
|
@@ -41,7 +56,7 @@ Pick the organisation, say what the business is called and which coding agent ru
|
|
|
41
56
|
If the organisation already runs roster, the page offers to check it out here instead, which is
|
|
42
57
|
how a second person joins.
|
|
43
58
|
|
|
44
|
-

|
|
45
60
|
|
|
46
61
|
**Show me the plan** lists every file and repo it would make; *Create it* is a separate button.
|
|
47
62
|
That is the pattern everywhere in roster: the plan first, then the apply.
|
|
@@ -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:
|
|
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 `
|
|
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/images/brain.jpg
CHANGED
|
Binary file
|
package/docs/images/home.jpg
CHANGED
|
Binary file
|
package/docs/images/org.jpg
CHANGED
|
Binary file
|
package/docs/images/prompt.jpg
CHANGED
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/docs/images/staff.jpg
CHANGED
|
Binary file
|