@nanocollective/roster 0.1.0-alpha.9 → 0.1.0-beta.1

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 (145) hide show
  1. package/README.md +5 -0
  2. package/dist/cli.js +4067 -1950
  3. package/dist/worker/assets/assets/css/base.css +312 -0
  4. package/dist/worker/assets/assets/css/brain.css +116 -0
  5. package/dist/worker/assets/assets/css/diff.css +33 -0
  6. package/dist/worker/assets/assets/css/graph.css +39 -0
  7. package/dist/worker/assets/assets/css/health.css +75 -0
  8. package/dist/worker/assets/assets/css/home.css +101 -0
  9. package/dist/worker/assets/assets/css/inbox.css +199 -0
  10. package/dist/worker/assets/assets/css/layout.css +175 -0
  11. package/dist/worker/assets/assets/css/markdown.css +96 -0
  12. package/dist/worker/assets/assets/css/runs.css +13 -0
  13. package/dist/worker/assets/assets/css/search.css +48 -0
  14. package/dist/worker/assets/assets/css/setup.css +194 -0
  15. package/dist/worker/assets/assets/js/api.js +161 -0
  16. package/dist/worker/assets/assets/js/app.js +465 -0
  17. package/dist/worker/assets/assets/js/dialog.js +196 -0
  18. package/dist/worker/assets/assets/js/dom.js +131 -0
  19. package/dist/worker/assets/assets/js/homesort.js +174 -0
  20. package/dist/worker/assets/assets/js/icons.js +142 -0
  21. package/dist/worker/assets/assets/js/inflight.js +18 -0
  22. package/dist/worker/assets/assets/js/lightbox.js +273 -0
  23. package/dist/worker/assets/assets/js/md.js +406 -0
  24. package/dist/worker/assets/assets/js/mdedit.js +84 -0
  25. package/dist/worker/assets/assets/js/mention.js +264 -0
  26. package/dist/worker/assets/assets/js/readiness.js +70 -0
  27. package/dist/worker/assets/assets/js/refresh.js +197 -0
  28. package/dist/worker/assets/assets/js/router.js +20 -0
  29. package/dist/worker/assets/assets/js/search.js +366 -0
  30. package/dist/worker/assets/assets/js/state.js +213 -0
  31. package/dist/worker/assets/assets/js/textdiff.js +96 -0
  32. package/dist/worker/assets/assets/js/views/app.js +145 -0
  33. package/dist/worker/assets/assets/js/views/brain.js +260 -0
  34. package/dist/worker/assets/assets/js/views/changed.js +157 -0
  35. package/dist/worker/assets/assets/js/views/checklist.js +115 -0
  36. package/dist/worker/assets/assets/js/views/credential.js +84 -0
  37. package/dist/worker/assets/assets/js/views/docs.js +174 -0
  38. package/dist/worker/assets/assets/js/views/files.js +139 -0
  39. package/dist/worker/assets/assets/js/views/graph.js +436 -0
  40. package/dist/worker/assets/assets/js/views/health.js +304 -0
  41. package/dist/worker/assets/assets/js/views/hire.js +593 -0
  42. package/dist/worker/assets/assets/js/views/home.js +585 -0
  43. package/dist/worker/assets/assets/js/views/inbox.js +1558 -0
  44. package/dist/worker/assets/assets/js/views/memory.js +150 -0
  45. package/dist/worker/assets/assets/js/views/org.js +195 -0
  46. package/dist/worker/assets/assets/js/views/orgedit.js +240 -0
  47. package/dist/worker/assets/assets/js/views/paste.js +216 -0
  48. package/dist/worker/assets/assets/js/views/prompt.js +457 -0
  49. package/dist/worker/assets/assets/js/views/repos.js +97 -0
  50. package/dist/worker/assets/assets/js/views/runonce.js +94 -0
  51. package/dist/worker/assets/assets/js/views/runs.js +182 -0
  52. package/dist/worker/assets/assets/js/views/setup.js +557 -0
  53. package/dist/worker/assets/assets/js/views/staff.js +291 -0
  54. package/dist/worker/assets/assets/js/views/todo.js +62 -0
  55. package/dist/worker/assets/assets/js/yaml.js +134 -0
  56. package/dist/worker/assets/docs-images/brain.jpg +0 -0
  57. package/dist/worker/assets/docs-images/home.jpg +0 -0
  58. package/dist/worker/assets/docs-images/org.jpg +0 -0
  59. package/dist/worker/assets/docs-images/prompt.jpg +0 -0
  60. package/dist/worker/assets/docs-images/setup-org.jpg +0 -0
  61. package/dist/worker/assets/docs-images/setup-plan.jpg +0 -0
  62. package/dist/worker/assets/docs-images/staff.jpg +0 -0
  63. package/dist/worker/assets/index.html +82 -0
  64. package/dist/worker/index.js +4430 -0
  65. package/docs/README.md +2 -2
  66. package/docs/architecture.md +1 -1
  67. package/docs/charters/analyst.md +65 -0
  68. package/docs/charters/community.md +63 -0
  69. package/docs/charters/designer.md +65 -0
  70. package/docs/charters/devops.md +65 -0
  71. package/docs/charters/pm.md +70 -0
  72. package/docs/charters/qa.md +65 -0
  73. package/docs/charters/writer.md +63 -0
  74. package/docs/commands.md +9 -3
  75. package/docs/concepts.md +33 -20
  76. package/docs/cost.md +3 -3
  77. package/docs/developing.md +27 -9
  78. package/docs/doctor-codes.md +3 -1
  79. package/docs/export.md +2 -0
  80. package/docs/getting-started.md +44 -27
  81. package/docs/hosting.md +89 -43
  82. package/docs/images/brain.jpg +0 -0
  83. package/docs/images/home.jpg +0 -0
  84. package/docs/images/org.jpg +0 -0
  85. package/docs/images/prompt.jpg +0 -0
  86. package/docs/images/staff.jpg +0 -0
  87. package/docs/manual-steps.md +3 -2
  88. package/docs/org-yaml.md +3 -0
  89. package/docs/portal.md +143 -45
  90. package/docs/prompts.md +6 -0
  91. package/docs/security.md +57 -11
  92. package/docs/session-workflow.md +14 -0
  93. package/docs/staff-yaml.md +17 -1
  94. package/docs/upgrading.md +3 -3
  95. package/docs/writing-a-charter.md +19 -6
  96. package/package.json +4 -3
  97. package/templates/brain/.github/workflows/%%STAFF%%-daily.yaml +20 -1
  98. package/templates/brain/.github/workflows/%%STAFF%%-mention.yaml +53 -13
  99. package/templates/brain/staff.yaml +4 -1
  100. package/templates/briefs/amend.md +4 -3
  101. package/templates/briefs/priorities.md +46 -0
  102. package/templates/ops/.github/workflows/session.yaml +137 -3
  103. package/templates/ops/compose.mjs +35 -8
  104. package/templates/ops/org/operating.md +29 -10
  105. package/templates/ops/prompts/daily.md +23 -4
  106. package/templates/ops/prompts/mention.md +19 -0
  107. package/templates/ops/run-record.mjs +5 -3
  108. package/templates/portal/css/base.css +34 -0
  109. package/templates/portal/css/health.css +14 -1
  110. package/templates/portal/css/home.css +101 -0
  111. package/templates/portal/css/inbox.css +21 -4
  112. package/templates/portal/css/layout.css +29 -3
  113. package/templates/portal/css/markdown.css +19 -0
  114. package/templates/portal/css/search.css +48 -0
  115. package/templates/portal/css/setup.css +79 -4
  116. package/templates/portal/index.html +15 -9
  117. package/templates/portal/js/api.js +30 -4
  118. package/templates/portal/js/app.js +90 -7
  119. package/templates/portal/js/dialog.js +36 -0
  120. package/templates/portal/js/homesort.js +174 -0
  121. package/templates/portal/js/icons.js +41 -0
  122. package/templates/portal/js/inflight.js +18 -0
  123. package/templates/portal/js/md.js +5 -2
  124. package/templates/portal/js/mdedit.js +84 -0
  125. package/templates/portal/js/readiness.js +70 -0
  126. package/templates/portal/js/refresh.js +10 -2
  127. package/templates/portal/js/search.js +366 -0
  128. package/templates/portal/js/state.js +11 -5
  129. package/templates/portal/js/views/app.js +1 -2
  130. package/templates/portal/js/views/brain.js +1 -1
  131. package/templates/portal/js/views/checklist.js +19 -4
  132. package/templates/portal/js/views/credential.js +42 -51
  133. package/templates/portal/js/views/health.js +11 -6
  134. package/templates/portal/js/views/hire.js +593 -0
  135. package/templates/portal/js/views/home.js +585 -0
  136. package/templates/portal/js/views/inbox.js +237 -68
  137. package/templates/portal/js/views/org.js +31 -111
  138. package/templates/portal/js/views/orgedit.js +240 -0
  139. package/templates/portal/js/views/paste.js +111 -66
  140. package/templates/portal/js/views/prompt.js +94 -40
  141. package/templates/portal/js/views/repos.js +10 -10
  142. package/templates/portal/js/views/runs.js +21 -4
  143. package/templates/portal/js/views/setup.js +130 -163
  144. package/templates/portal/js/views/staff.js +181 -301
  145. package/templates/portal/js/views/todo.js +62 -0
@@ -12,15 +12,16 @@ npm test # the whole suite
12
12
  npx tsc --noEmit # typecheck
13
13
  ```
14
14
 
15
- Tests are `node:test` run through `tsx`. There is no build step for development, and the portal
16
- has no build step at all.
15
+ Tests are `node:test` run through `tsx`. There is no build step for development, and the
16
+ portal's page has no build step at all. `npm run build` builds the CLI and the portal's Worker.
17
17
 
18
18
  ## Layout
19
19
 
20
20
  ```
21
21
  src/cli.ts command table and help
22
22
  src/commands/ one file per command
23
- src/lib/ shared: workspace, memory, render, merge, gh, templates, docs
23
+ src/lib/ shared: workspace, memory, render, merge, gh, github, vfs, templates, docs
24
+ src/portal/ the portal's server: handler.ts, and the Worker that hosts it
24
25
  templates/ops/ what a tenant's ops repo is generated from
25
26
  templates/brain/ what a staff member's repo is generated from
26
27
  templates/portal/ the portal: a shell, css/, and js/ as ES modules
@@ -28,14 +29,31 @@ docs/ these pages
28
29
  test/ one file per area
29
30
  ```
30
31
 
31
- ## The portal has no build step, on purpose
32
+ ## The portal's server
33
+
34
+ `src/portal/handler.ts` answers every route that works the same on your machine and hosted. It
35
+ reads the org through snapshots of its repositories on GitHub (`snapshot.ts`), mounted where a
36
+ checkout would be by `src/lib/vfs.ts`, so the readers in `src/lib` work on either. It acts
37
+ through `src/lib/github.ts`, a `fetch` client holding the person's token.
38
+
39
+ - `src/commands/portal.ts` is the local server. It sends those routes to the handler and keeps
40
+ the ones that need a checkout: setup, the App hand-off, doctor, hire and retire.
41
+ - `src/portal/worker.ts` is the hosted one: the same handler behind Sign in with GitHub
42
+ (`session.ts`). `scripts/build-worker.mjs` builds it into `dist/worker/`, and
43
+ `roster portal deploy` deploys it.
44
+
45
+ `test/hosted-portal.test.ts` runs the handler against a scaffolded tenant served in the API's
46
+ shapes (`test/helpers/githubrepos.ts`), so it needs neither the network nor an org.
47
+
48
+ ## The portal's page has no build step, on purpose
32
49
 
33
50
  `templates/portal/` is a plain `index.html`, one stylesheet per area under `css/`, and one ES
34
51
  module per screen under `js/views/`. `roster portal` serves them from `/assets`, reading each
35
- file per request. Editing a stylesheet and reloading the page is the whole edit loop.
52
+ file per request. Editing a stylesheet and reloading the page is the whole edit loop. The
53
+ Worker serves the same files, copied as they are.
36
54
 
37
- No bundler, because the browser resolves the module graph itself, and a bundler would be a
38
- build step in a tool whose selling point is that it does not have one.
55
+ No bundler for the page, because the browser resolves the module graph itself. Only the
56
+ Worker's server code is bundled, because a Worker is one module.
39
57
 
40
58
  ```
41
59
  templates/portal/
@@ -51,8 +69,8 @@ templates/portal/
51
69
  ```
52
70
 
53
71
  `js/icons.js` holds two dozen [Lucide](https://lucide.dev) glyphs as inlined path data, ISC
54
- licensed. Vendored rather than fetched, because the portal is offline-first and an icon that
55
- needs the network is an icon that is sometimes a blank square. They take colour from
72
+ licensed. Vendored rather than fetched, because an icon that needs a third party's network is an
73
+ icon that is sometimes a blank square. They take colour from
56
74
  `currentColor` and size from a `--ic` custom property, so a component styles them in CSS and
57
75
  never touches the SVG. Nothing in the UI should draw with a text character.
58
76
 
@@ -39,7 +39,7 @@ ran at all.
39
39
  | `workflows` | No workflow in the repo is failing run after run. Reported for the ops repo here, and for each brain repo under its staff member. |
40
40
  | `workflows.failing` | **fail.** A workflow that is not one of roster's callers has failed at least its last two runs, with the date it started. Skipped and cancelled runs are stepped over. This is the canary that goes red and stays red, because whatever would have said so broke with it. |
41
41
  | `budget` | Trailing 30-day spend against a `budget` in `org.yaml`, for the org here and for a staff member under their name. A warning when it is past, never a failure, and only read when a budget is set. Cost comes from each run's record, so it says how many runs it could price. See [cost](cost.md#budgets). |
42
- | `review-gate` | One per product repo. **fail** when nothing requires a pull request on its default branch, or a staff App can bypass the rule; a warning when a PR is required with no approving review, or the settings cannot be read. See [security](security.md#the-review-gate). |
42
+ | `review-gate` | Off unless `review_gate: true` is in `org.yaml`, and then a note that it is off. When on, one per product repo. **fail** when nothing requires a pull request on its default branch, or a staff App can bypass the rule; a warning when a PR is required with no approving review, when the repo is private on GitHub Free (which can't enforce the rule), or when the settings cannot be read. See [security](security.md#the-review-gate). |
43
43
  | `upgrade` | The tenant is in sync with the framework. |
44
44
  | `upgrade.stale` | Generated files are behind. `roster upgrade --apply`. |
45
45
  | `upgrade.owned` | **fail.** A framework-owned file was edited in the tenant. Move the change upstream or the next upgrade reverts it. |
@@ -63,6 +63,8 @@ ran at all.
63
63
  | `surfaces` | A surface declared in `staff.yaml` is not on disk. The portal renders nothing for it. |
64
64
  | `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
65
  | `labels` | Every label declared in `staff.yaml` exists. An agent applying a label that does not exist gets an API error mid-run. |
66
+ | `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. |
67
+ | `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. |
66
68
  | `peer-labels` | The `from-<handle>` label exists on the *peer's* tracker, which is where this staff member's asks land. |
67
69
  | `status-issue` | The declared status issue is actually pinned. If not, the place you look is not the place the agent maintains. |
68
70
  | `runs` | A window of recent runs. See below. |
package/docs/export.md CHANGED
@@ -35,6 +35,7 @@ that reads it gets the same view without reimplementing the memory grammar.
35
35
  | `statusIssue` | pinned issue number |
36
36
  | `schedule` | cron |
37
37
  | `mention` | what wakes them |
38
+ | `icon` | the icon set by `icon:` in staff.yaml, if any |
38
39
  | `bots[]` | every App login, `[bot]` suffix stripped |
39
40
  | `soloBots[]` | identities unique to this staff member |
40
41
  | `sharedBots[]` | identities shared with others |
@@ -99,6 +100,7 @@ Only surfaces that exist on disk appear. A declared surface that is missing show
99
100
  |---|---|
100
101
  | `workflows[]` | filenames under `.github/workflows/` |
101
102
  | `hasCharter`, `hasManifest` | |
103
+ | `charterStub` | `CHARTER.md` is absent or still the scaffold, the same test as doctor's `charter.stub` |
102
104
  | `missingSurfaces[]` | declared, not on disk |
103
105
  | `memoryBytes` | size of `INDEX.md` |
104
106
  | `notesBytes` | total size of `memory/notes/` |
@@ -30,7 +30,7 @@ hour is the part not to rush.
30
30
  - **A credential for your [coding agent](agents.md).** For Claude Code, run
31
31
  `claude setup-token` and keep the token it prints for step 5.
32
32
 
33
- You only need [the six things in Concepts](concepts.md#the-six-things-you-need-to-know) to follow
33
+ You only need [the three things in Concepts](concepts.md#the-three-things-you-need-to-know) to follow
34
34
  this. Everything else can wait.
35
35
 
36
36
  ## 1. Say which organisation, then read the plan
@@ -51,7 +51,8 @@ can call its workflow. Without that every run fails with "workflow not found". I
51
51
  (it needs admin on the repo), the page says why and links to the setting to click instead.
52
52
 
53
53
  The rest of the steps stay on the same page. Reload it and the portal opens on **Getting
54
- started**, which keeps them in the sidebar until they are done, with hiring first.
54
+ started**, which keeps them in the sidebar until they are done, with hiring first. The sidebar
55
+ counts them: three for the org, five for each staff member.
55
56
 
56
57
  ## 2. Say what the business is
57
58
 
@@ -71,49 +72,61 @@ See [concepts](concepts.md#priorities).
71
72
 
72
73
  ![The Staff screen, with a card per staff member and Hire someone underneath](images/staff.jpg)
73
74
 
74
- **Staff → Hire someone.** Only the handle is required. The plan shows the repo it creates, the
75
- schedule it chose, and the commits it will make **as you** in repos that already exist: each
76
- peer's `staff.yaml`, and `org.yaml`. Nothing is left uncommitted on disk.
75
+ **Staff**, then pick a role: CTO, CMO, Support, or **Something else** with a name and a sentence
76
+ about what they do. With nobody hired yet the Staff screen opens on the picker. The role fills
77
+ in the handle, name and repo; they are under **Advanced** if you want to change them.
77
78
 
78
- For the first hire there is nobody to copy an App name from, so the form asks for two: this
79
- staff member's App, and the shared public App. Names are unique across GitHub, so prefix them
80
- with the org. The public one only matters if a product repo is public; leave it empty when they
81
- are all private.
79
+ The role opens a numbered list: hire, create their GitHub App, write their charter, add your
80
+ agent credential, run once now. The steps after the hire say *Hire first* until it is done.
81
+
82
+ Step 1 says in one sentence what the hire creates and when they run. **Show details** has the
83
+ full plan: the repo, the schedule and why, and the commits it will make **as you** in repos that
84
+ already exist: each peer's `staff.yaml`, and `org.yaml`. Nothing is left uncommitted on disk.
85
+
86
+ For the first hire there is nobody to copy an App name from, so **Advanced** also has two:
87
+ this staff member's App, and the shared public App, filled in as `<org>-<handle>` and
88
+ `<org>-robot`. Names are unique across GitHub, so keep the org prefix. The public one only
89
+ matters if a product repo is public.
82
90
 
83
91
  Product repos come from `org.yaml`. Mark one on the setup screen, or later with **Org → Add a
84
92
  product repo**.
85
93
 
94
+ After **Hire** the list stays on the same staff member, now on step 2. Leave and come back later
95
+ with **Finish setting up** on their card.
96
+
86
97
  ## 4. Create the App, and confirm the install
87
98
 
88
- **GitHub App**, on the new card. GitHub has no API that creates an App, so a tab opens and you
99
+ **Create the App**, in step 2. GitHub has no API that creates an App, so a tab opens and you
89
100
  confirm. The App's id and private key go straight into the repo's secrets and never touch disk.
101
+ The public App is offered too when a product repo is public.
90
102
 
91
103
  Then **Install it**. The install page opens with the organisation and every repo this staff
92
104
  member needs already ticked: its brain, the trackers of its peers, and the product repos. Check
93
105
  the list and confirm. That confirmation is yours by design: installing grants access, and GitHub
94
106
  asks a person.
95
107
 
96
- ## 5. Store the agent credential, once
108
+ ## 5. Write the charter
97
109
 
98
- **Agent credential**, on the card or on the setup screen. Paste the token from `claude
99
- setup-token` (or your agent's key; the box says where to get one). It is stored as one
100
- organisation secret, shared with the brain repos, and each later hire is added to it. It is not
101
- asked for again.
110
+ Step 3. **Let an AI interview you** is the same copy-a-prompt loop as step 2 of this guide, aimed
111
+ at `CHARTER.md`, carrying the org layer, the peers' charters and, where the role matches one, a
112
+ [worked example](writing-a-charter.md#worked-examples) to model the shape on. **Start from the
113
+ template** opens that example in an editor with your business's name in it; edit it so it fits
114
+ before saving. **Edit the file** is the file as it is. roster never generates a charter, because
115
+ a generated one makes exactly the generic agent this whole arrangement exists to avoid.
102
116
 
103
- On GitHub Free an org secret does not reach private repos, so there it goes on each brain repo
104
- instead, and the page says so. It is still one paste now; a later hire needs it once more.
117
+ ## 6. Store the agent credential, once
105
118
 
106
- ## 6. Write the charter
119
+ Step 4, shown only while no credential is stored. It is also on the card and on the setup
120
+ screen. Paste the token from `claude setup-token` (or your agent's key; the box says where to
121
+ get one). It is stored as one organisation secret, shared with the brain repos, and each later
122
+ hire is added to it. It is not asked for again.
107
123
 
108
- **Write the charter**, on the card. The same copy-a-prompt loop as step 2, aimed at
109
- `CHARTER.md`, carrying the org layer, the peers' charters and, where the role matches one, a
110
- [worked example](writing-a-charter.md#worked-examples) to model the shape on. The brief
111
- interviews you; the charter is yours. roster never generates one, because a generated charter
112
- makes exactly the generic agent this whole arrangement exists to avoid.
124
+ On GitHub Free an org secret does not reach private repos, so there it goes on each brain repo
125
+ instead, and the page says so. It is still one paste now; a later hire needs it once more.
113
126
 
114
127
  ## 7. Run it once
115
128
 
116
- **Run once now**, on the card or on **Health**. It starts the daily workflow, follows it, and
129
+ **Run once now**, step 5, also on the card and on **Health**. It starts the daily workflow, follows it, and
117
130
  tells you how it ended, with the log.
118
131
 
119
132
  **A workflow that has never run has proved nothing**: not that the App is installed on the right
@@ -144,9 +157,13 @@ member on their next run.
144
157
 
145
158
  The same road, command by command. Each prints its plan and changes nothing without `--apply`.
146
159
 
160
+ `roster` below means `npx @nanocollective/roster@latest`, unless you have installed it with
161
+ `npm install -g @nanocollective/roster`.
162
+
147
163
  ```bash
148
164
  roster init --org acme --apply # the ops repo, and its Actions access
149
- roster brief discover # a brief for org/business.md; write priorities.md too
165
+ roster brief discover # a brief for org/business.md
166
+ roster brief priorities # a brief for org/priorities.md
150
167
  roster hire cto --apply # the brain, the wiring, the commits as you
151
168
  roster app cto --apply # the App, its secrets, and a pre-ticked install link
152
169
  roster credential --apply # the agent credential, once for the org
@@ -165,8 +182,8 @@ each.
165
182
 
166
183
  - **A second staff member**: Staff → Hire someone, then GitHub App, the charter and one run. The
167
184
  credential is already there.
168
- - **Answering your agents**: [the Inbox](portal.md#inbox) is everything open across the org, and
169
- the reply goes out as you. Work they finished sits in [Pending work](portal.md#pending-work).
185
+ - **Answering your agents**: [Home](portal.md#home) is what needs you, who is working and
186
+ what you asked for. Replies and merges go out as you.
170
187
  - **A framework update**: `roster upgrade`, or the same from the portal. See
171
188
  [upgrading](upgrading.md).
172
189
  - **The whole portal**, screen by screen: [the portal](portal.md).
package/docs/hosting.md CHANGED
@@ -1,72 +1,118 @@
1
1
  ---
2
2
  title: "Hosting the portal"
3
- description: "Local is the default, and the honest options if you want it elsewhere."
3
+ description: "The portal on your own URL, behind Sign in with GitHub, redeploying itself."
4
4
  sidebar_order: 11
5
5
  ---
6
6
 
7
7
  # Hosting the portal
8
8
 
9
- `roster portal` is local-first and that is the intended way to run it. It reads the checked-out
10
- repositories from disk, needs no authentication, hits no API rate limits, and works offline.
9
+ The portal runs in two places, and it is the same code in both.
11
10
 
12
11
  ```bash
13
- roster portal # http://localhost:4300
14
- roster portal --port 4400
12
+ roster portal # on your machine, http://localhost:4300
13
+ roster portal deploy --domain roster.acme.com # on the web, on Cloudflare Workers
15
14
  ```
16
15
 
17
- ## Why local is the default
16
+ Both read the org from GitHub, so neither needs the repos checked out to show it. Both act on
17
+ GitHub as the person using them. The hosted one adds a sign-in in front, and leaves out the
18
+ few screens that need a checkout.
18
19
 
19
- **Setup is local only.** The screen that stands up a tenant also creates GitHub Apps and writes
20
- repository secrets, and none of that belongs behind a tunnel or an access proxy. Everything below
21
- is about a portal over an org that already exists.
20
+ ## What you get, and what stays on your machine
22
21
 
23
- The portal can write. It replies to issues, closes them, reopens them and opens new ones,
24
- acting as you through your own `gh`. That is the point: it is where a person answers their
25
- agents. It also means it is not a thing to leave listening on a network.
22
+ Hosted, you get everything you use day to day: Home, the trackers, threads and replies, pull
23
+ requests (approve and merge), Runs, the brains, prompts, the org files and their editors, and
24
+ the docs.
26
25
 
27
- Three things guard it, and they only work locally:
26
+ These stay on your machine, and the hosted page says so where they would be:
28
27
 
29
- - it binds to `127.0.0.1`
30
- - a write needs a `POST` with an `x-roster` header, which forces a CORS preflight that fails
31
- from any other origin
32
- - an `Origin` header, if present, must be localhost
28
+ - **Setup**: standing up an org, the GitHub Apps, the agent credential
29
+ - **Hiring and retiring**
30
+ - **Doctor and the Health checklist**, which read the checkout and the org's secrets
33
31
 
34
- `--host` overrides the bind address and prints a warning. Do not use it to "just have a look
35
- from my phone".
32
+ They create repositories and Apps and write secrets, which is the most privileged thing roster
33
+ does. That is not something to put behind a public URL.
36
34
 
37
- ## Reading it from elsewhere
35
+ ## Who can get in
38
36
 
39
- The honest options, in order of how much you should like them.
37
+ Only the people listed under `humans:` in `org.yaml`, signed in with their own GitHub account.
40
38
 
41
- **A tunnel, briefly.** `ssh -L 4300:localhost:4300 you@yourmachine`, or Tailscale, or
42
- `cloudflared tunnel --url http://localhost:4300`. Your machine stays the only thing running it
43
- and the write path stays behind your own network identity. Turn it off afterwards.
39
+ - 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
+ - Everything they do is as themselves. A reply is theirs, a merge is theirs, and what they can
43
+ read is what GitHub lets them read.
44
+ - Somebody who signs in and is not one of the humans, or cannot read the ops repo, is turned
45
+ away and their token revoked. Somebody removed from `humans:` stops getting in within a few
46
+ minutes.
47
+ - A sign-in lasts fourteen days. Signing out revokes the token on GitHub.
44
48
 
45
- **A read-only static build.** `roster export` produces the whole org as one JSON document, and
46
- the portal's rendering is decoupled from its parsing precisely so this is possible:
49
+ See [security](security.md#the-hosted-portal) for what is held where.
50
+
51
+ ## Deploying it
52
+
53
+ You need a Cloudflare account with the domain on it, and wrangler signed in to it. If your
54
+ login can see more than one account, pass `--account <id>` with the one that has the domain, and
55
+ it is pinned in the config so a later deploy cannot land anywhere else:
47
56
 
48
57
  ```bash
49
- roster export --out org.json
58
+ npx wrangler login
59
+ roster portal deploy --domain roster.acme.com # says what it will do
60
+ roster portal deploy --domain roster.acme.com --apply # does it
50
61
  ```
51
62
 
52
- Serve that plus the portal HTML from anything static (Cloudflare Pages, S3, a directory). You
53
- get memory, the graph, the brain and what-changed. You do not get the inbox or any write
54
- action, because both need `gh`.
63
+ The first time, it stops for the one thing only you can do: **create the OAuth App**. It prints
64
+ the link and the three fields:
65
+
66
+ | Field | Value |
67
+ |---|---|
68
+ | Application name | `<org> roster` |
69
+ | Homepage URL | `https://roster.acme.com` |
70
+ | Authorization callback URL | `https://roster.acme.com/auth/callback` |
71
+
72
+ Register it, generate a client secret, and paste the two values when asked. The secret is not
73
+ shown as you type.
74
+
75
+ Then it deploys the Worker, stores the App's secret and a fresh session key as Worker secrets,
76
+ and commits two files to the ops repo:
77
+
78
+ - `portal/wrangler.jsonc`: the Worker's name, the domain, the org. Nothing secret.
79
+ - `.github/workflows/portal.yaml`: redeploys it.
80
+
81
+ ## Keeping it up to date
82
+
83
+ The workflow redeploys the portal when its config changes, every morning, and when you run it
84
+ by hand. Each deploy uses the newest roster, so updates arrive by themselves.
55
85
 
56
- Put access control in front of it. Cloudflare Access with a one-person policy is the least
57
- work. **This is private business content and a map of what your agents know**, so an
58
- unauthenticated URL is not an option even if nobody knows it.
86
+ It needs two secrets on the ops repo:
59
87
 
60
- **A hosted instance with write access.** Not documented, and not recommended. It would need a
61
- GitHub App of its own, a session layer, and a credible answer to "what can this thing do if
62
- someone reaches it". None of that exists, and the local server plus a tunnel gets you the same
63
- outcome with none of it.
88
+ | Secret | Where from |
89
+ |---|---|
90
+ | `CLOUDFLARE_API_TOKEN` | Cloudflare dashboard → API Tokens → the **Edit Cloudflare Workers** template |
91
+ | `CLOUDFLARE_ACCOUNT_ID` | the Workers page of the dashboard |
64
92
 
65
- ## Keeping it current
93
+ Without them the portal still runs; it only stops updating itself.
66
94
 
67
- The portal reads your working tree, so a stale checkout shows stale data. `/api/sync` fetches
68
- and fast-forwards every repository on each refresh. It refuses to pull one that is dirty or has
69
- diverged, and says which in a banner rather than guessing.
95
+ The portal reads GitHub fresh as you use it, so there is nothing to sync. It asks whether
96
+ anything has moved every few seconds, and an answer of "no" costs nothing against GitHub's
97
+ hourly limit.
98
+
99
+ ## The cache
100
+
101
+ The portal keeps what it has read from GitHub: file contents by their hash, each commit's file
102
+ dates, and finished runs' costs. All of it is immutable, so it is never stale.
103
+
104
+ On your machine it is `~/.cache/roster`. On Cloudflare it is the edge cache, which needs no
105
+ setup. To keep it everywhere rather than per data centre, bind a KV namespace as `CACHE` in
106
+ `portal/wrangler.jsonc`.
107
+
108
+ ## On your machine
109
+
110
+ `roster portal` binds to `127.0.0.1` and acts as whoever `gh` is signed in as. To open an org
111
+ you have never cloned:
112
+
113
+ ```bash
114
+ roster portal --org acme
115
+ ```
70
116
 
71
- If you host a static export, the export is a point in time. Regenerate it on a schedule, or
72
- accept that it is yesterday's.
117
+ `--host` overrides the bind address and prints a warning. The local server has no sign-in, so
118
+ use the hosted portal instead of exposing it.
Binary file
Binary file
Binary file
Binary file
Binary file
@@ -45,8 +45,9 @@ hand. roster says so if it happens.
45
45
  ## 3. Confirm the App's install
46
46
 
47
47
  **Do:** press **Install it** in the portal, or open the link `roster app` prints. The page opens
48
- with the organisation and the repos this staff member needs already selected: its brain, each
49
- peer's tracker, and the product repos. Check the list and confirm.
48
+ with the organisation and the repos this staff member needs already selected: its brain, the
49
+ ops repo (every run checks it out first), each peer's tracker, and the product repos. Check the
50
+ list and confirm. Choosing **All repositories** instead also works.
50
51
 
51
52
  **Why not automated:** installing is a grant of access to specific repositories, and GitHub asks
52
53
  a person to confirm it. That is correct and should not be worked around.
package/docs/org-yaml.md CHANGED
@@ -39,6 +39,7 @@ defaults:
39
39
  mention_timeout_minutes: 90
40
40
 
41
41
  budget: 300
42
+ review_gate: true
42
43
 
43
44
  staff:
44
45
  - { handle: cto, dir: technology, name: Chief Technology Officer, schedule: "0 7 * * 1-5" }
@@ -61,6 +62,7 @@ repos:
61
62
  | `ops_dir` | no | Directory name of the ops repo in the runner checkout. Defaults to `roster-ops`. |
62
63
  | `experiment_private` | no | Whether the fact that this org is agent-run is itself private. Read by the guardrails fragment. |
63
64
  | `budget` | no | USD over any trailing 30 days, for the whole org. See [below](#budget). |
65
+ | `review_gate` | no | `true` to have GitHub require a reviewed pull request before anything merges into a product repo. Off by default, because private repos need a paid plan for it. See [security](security.md#the-review-gate). |
64
66
 
65
67
  ### `human` and `humans`
66
68
 
@@ -124,6 +126,7 @@ Fallbacks for staff members who do not set their own.
124
126
  | `model` | Model id passed to the agent. |
125
127
  | `timeout_minutes` | Ceiling on a daily session. `90` if unset. |
126
128
  | `mention_timeout_minutes` | Ceiling on a mention run. Falls back to `timeout_minutes`, then `90`. |
129
+ | `max_runs_per_day` | What a new hire's `max_runs_per_day` starts at. `6` when unset. |
127
130
  | `allowed_tools` | Claude's own spelling of a permission level, kept because it predates `agent.permissions` and still wins for the agents that take a tool list. Nothing translates it for the others: a list written for one agent is not a permission level for another. Prefer [`agent.permissions`](agents.md#permissions), which every agent understands. |
128
131
 
129
132
  ### `memory`