@nanocollective/roster 0.1.0-alpha.23 → 0.1.0-alpha.25

package/dist/cli.js

@@ -140,7 +140,7 @@ async function createApp(spec2, opts = {}) {
         res.end(
           page(
             `${app.slug} created`,
-            "The private key went straight into the repository's secrets and was never written to disk. You can close this tab; the terminal has the next step."
+            "Its keys are saved in the repository's secrets. You can close this tab; the terminal has the next step."
           )
         );
         finish(() => resolve6(app));
@@ -210,7 +210,8 @@ async function open(url) {
 // src/lib/install.ts
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
-function installTargets(ws, org, parseYaml, handle, spec2) {
+function installTargets(ws, org, parseYaml, handle, spec2, scope = "private") {
+  if (scope === "public") return [...new Set(spec2.worksIn)];
   const peers = [];
   for (const s of org.staff ?? []) {
     if (s.handle === handle) continue;
@@ -222,7 +223,8 @@ function installTargets(ws, org, parseYaml, handle, spec2) {
     } catch {
     }
   }
-  return [.../* @__PURE__ */ new Set([spec2.brain, ...spec2.worksIn, ...peers])];
+  const ops = org.org ? [`${org.org}/${ws.opsName}`] : [];
+  return [.../* @__PURE__ */ new Set([spec2.brain, ...ops, ...spec2.worksIn, ...peers])];
 }
 function installUrl(slug, targetId, repoIds = []) {
   const base2 = `https://github.com/apps/${encodeURIComponent(slug)}/installations/new`;
@@ -538,7 +540,14 @@ async function appCommand(argv) {
 `);
     return 2;
   }
-  const targets = installTargets(ws, org, parseYaml, handle, spec2);
+  const targets = installTargets(
+    ws,
+    org,
+    parseYaml,
+    handle,
+    spec2,
+    opts.public ? "public" : "private"
+  );
   const existing = await api(`/apps/${name}`);
   if (existing.ok) {
     const install2 = await preselectedInstall(existing.data?.slug ?? name, org.org, targets);
@@ -808,6 +817,11 @@ function exampleSection(choice) {
     ""
   ].join("\n");
 }
+function charterStarter(choice, business) {
+  const path = join8(docsDir(), "charters", `${choice}.md`);
+  if (!existsSync8(path)) throw new Error(`there is no example charter called "${choice}"`);
+  return readFileSync7(path, "utf8").replace(/^> \*\*An example to adapt[\s\S]*?\n\n/m, "").replace(/\bAcme\b/g, business);
+}
 function exampleOffer(handle) {
   return [
     "## Worked examples",
@@ -4260,6 +4274,7 @@ function readRig(root, manifest, commits) {
   return {
     workflows: existsSync17(wfDir) ? readdirSync7(wfDir).filter((f) => /\.ya?ml$/.test(f)).sort() : [],
     hasCharter: existsSync17(join19(root, "CHARTER.md")),
+    charterStub: !existsSync17(join19(root, "CHARTER.md")) || looksUnwritten(readFileSync16(join19(root, "CHARTER.md"), "utf8")),
     hasManifest: existsSync17(join19(root, "staff.yaml")),
     missingSurfaces: declared.filter((s) => s?.path && !existsSync17(join19(root, s.path))).map((s) => s.path),
     memoryBytes: bytesOf(join19(root, "memory", "INDEX.md")),
@@ -6422,6 +6437,7 @@ async function portalCommand(argv) {
   const TTL = 45e3;
   const labelCache = /* @__PURE__ */ new Map();
   let runsCache = null;
+  const progressCache = /* @__PURE__ */ new Map();
   const LABEL_TTL = 3e5;
   const brainDirs = () => (readOrg(ws.opsDir, parseYaml).staff ?? []).map((s) => s.dir ?? s.handle);
   const knownRepos = () => {
@@ -6429,7 +6445,9 @@ async function portalCommand(argv) {
     return (org.repos ?? []).map((r) => ({
       name: r.name,
       owner: org.org,
-      role: r.role ?? "repo"
+      role: r.role ?? "repo",
+      // As org.yaml has it. Absent on a hand-written entry, which hire treats as public.
+      visibility: r.visibility
     }));
   };
   const writeAllowed = (req) => {
@@ -6471,7 +6489,14 @@ async function portalCommand(argv) {
         res.end(JSON.stringify({ error: `staff.yaml declares no ${payload.scope} app` }));
         return;
       }
-      const targets = installTargets(ws, org, parseYaml, entry.handle, spec2);
+      const targets = installTargets(
+        ws,
+        org,
+        parseYaml,
+        entry.handle,
+        spec2,
+        isPublic ? "public" : "private"
+      );
       const existing = await api(`/apps/${name}`);
       if (existing.ok) {
         const install = await preselectedInstall(existing.data?.slug ?? name, org.org, targets);
@@ -6808,7 +6833,7 @@ async function portalCommand(argv) {
           });
           res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
           res.end(
-            `<body style="font:15px/1.6 system-ui;max-width:34rem;margin:14vh auto;padding:0 1.4rem"><h1 style="font-size:1.3rem">${app.slug} created</h1><p>Its id and private key went straight into ${pending.brain}'s secrets. The key was never written to disk.</p><p><b>It still has to be installed</b>, and granted every tracker this staff member writes to \u2014 not just their own.</p><p>Close this tab; the portal has the link.</p></body>`
+            `<body style="font:15px/1.6 system-ui;max-width:34rem;margin:14vh auto;padding:0 1.4rem"><h1 style="font-size:1.3rem">${app.slug} created</h1><p>Its keys are saved in ${pending.brain}'s secrets.</p><p><b>Next: install it.</b> Go back to the portal and press Install.</p><p>You can close this tab.</p></body>`
           );
         }).catch((err) => {
           appResults.set(state, { ok: false, error: err.message });
@@ -6894,6 +6919,40 @@ async function portalCommand(argv) {
         }
         return;
       }
+      if (url.pathname === "/api/charter-example") {
+        const org = readOrg(w.opsDir, parseYaml);
+        const handle = url.searchParams.get("staff") ?? "";
+        const entry = (org.staff ?? []).find((s) => s.handle === handle);
+        const asked = url.searchParams.get("kind") ?? matchExample(handle, entry?.name ?? "");
+        if (!asked || !CHARTER_EXAMPLES.includes(asked)) {
+          json(res, { kind: null, text: "" });
+          return;
+        }
+        json(res, { kind: asked, text: charterStarter(asked, String(org.name ?? org.org)) });
+        return;
+      }
+      if (url.pathname === "/api/staff/progress") {
+        const handle = url.searchParams.get("staff") ?? "";
+        const hit = progressCache.get(handle);
+        if (url.searchParams.get("fresh") !== "1" && hit && Date.now() - hit.at < 6e4) {
+          json(res, hit.body);
+          return;
+        }
+        const org = readOrg(w.opsDir, parseYaml);
+        const entry = (org.staff ?? []).find((s) => s.handle === handle);
+        if (!entry) {
+          res.writeHead(400, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: `no staff member "${handle}"` }));
+          return;
+        }
+        const dir = entry.dir ?? entry.handle;
+        const spec2 = specFromManifest(readManifest2(join28(w.root, dir), parseYaml), dir);
+        staffProgress(spec2, dailyWorkflow(entry.handle)).then((body2) => {
+          progressCache.set(handle, { at: Date.now(), body: body2 });
+          json(res, body2);
+        }).catch(() => json(res, { app: null, publicApp: null, ran: null }));
+        return;
+      }
       if (url.pathname === "/api/staff/plan") {
         const handle = url.searchParams.get("handle") ?? "";
         const action = url.searchParams.get("action") === "retire" ? "retire" : "hire";
@@ -7009,7 +7068,8 @@ async function portalCommand(argv) {
             parseYaml,
             kind,
             handle,
-            url.searchParams.get("example") ?? void 0
+            url.searchParams.get("example") ?? void 0,
+            url.searchParams.get("about") ?? void 0
           );
           json(res, {
             kind,
@@ -7485,7 +7545,7 @@ ${warn}
     });
   });
 }
-function buildPasteBrief(ws, parseYaml, kind, handle, example) {
+function buildPasteBrief(ws, parseYaml, kind, handle, example, about) {
   if (!pasteable(kind)) throw new Error(`there is no paste-mode brief for "${kind}"`);
   const org = readOrg(ws.opsDir, parseYaml);
   const staff = org.staff ?? [];
@@ -7510,6 +7570,14 @@ function buildPasteBrief(ws, parseYaml, kind, handle, example) {
   let rendered = renderBrief2(briefTemplate(kind), tokens);
   const chosen = kind === "charter" ? example ?? matchExample(handle, tokens.NAME ?? "") ?? "none" : void 0;
   if (chosen) rendered = withExample(rendered, handle, tokens.NAME ?? "", chosen);
+  if (kind === "charter" && about?.trim()) {
+    rendered = `${rendered.trimEnd()}
+
+## What the owner said this role does
+
+${about.trim()}
+`;
+  }
   return { ...pasteBrief(ws, kind, rendered, { dir, peers }), example: chosen };
 }
 function renderBrief2(text, tokens) {
@@ -7527,6 +7595,24 @@ function json(res, data, advice = false) {
   const text = JSON.stringify(data);
   res.end(advice ? withBin(text) : text);
 }
+async function staffProgress(spec2, workflow) {
+  const [repo, shared, runs] = await Promise.all([
+    api(`repos/${spec2.brain}/actions/secrets`),
+    api(`repos/${spec2.brain}/actions/organization-secrets`),
+    api(
+      `repos/${spec2.brain}/actions/workflows/${workflow}/runs?status=success&per_page=1`
+    )
+  ]);
+  const names = repo.ok ? /* @__PURE__ */ new Set([
+    ...repo.data.secrets.map((x) => x.name),
+    ...shared.ok ? shared.data.secrets.map((x) => x.name) : []
+  ]) : null;
+  return {
+    app: names ? names.has(`${spec2.secretPrefix}_APP_ID`) : null,
+    publicApp: names ? names.has(`${spec2.publicSecretPrefix}_APP_ID`) : null,
+    ran: runs.ok ? (runs.data?.total_count ?? 0) > 0 : null
+  };
+}
 function hireFlags(params) {
   const num = (k) => params.get(k) ? Number(params.get(k)) : void 0;
   return {

package/docs/export.md

@@ -99,6 +99,7 @@ Only surfaces that exist on disk appear. A declared surface that is missing show
 |---|---|
 | `workflows[]` | filenames under `.github/workflows/` |
 | `hasCharter`, `hasManifest` | |
+| `charterStub` | `CHARTER.md` is absent or still the scaffold, the same test as doctor's `charter.stub` |
 | `missingSurfaces[]` | declared, not on disk |
 | `memoryBytes` | size of `INDEX.md` |
 | `notesBytes` | total size of `memory/notes/` |

package/docs/getting-started.md

@@ -71,49 +71,61 @@ See [concepts](concepts.md#priorities).
 
 ![The Staff screen, with a card per staff member and Hire someone underneath](images/staff.jpg)
 
-**Staff → Hire someone.** Only the handle is required. The plan shows the repo it creates, the
-schedule it chose, and the commits it will make **as you** in repos that already exist: each
-peer's `staff.yaml`, and `org.yaml`. Nothing is left uncommitted on disk.
+**Staff**, then pick a role: CTO, CMO, Support, or **Something else** with a name and a sentence
+about what they do. With nobody hired yet the Staff screen opens on the picker. The role fills
+in the handle, name and repo; they are under **Advanced** if you want to change them.
 
-For the first hire there is nobody to copy an App name from, so the form asks for two: this
-staff member's App, and the shared public App. Names are unique across GitHub, so prefix them
-with the org. The public one only matters if a product repo is public; leave it empty when they
-are all private.
+The role opens a numbered list: hire, create their GitHub App, write their charter, add your
+agent credential, run once now. The steps after the hire say *Hire first* until it is done.
+
+Step 1 says in one sentence what the hire creates and when they run. **Show details** has the
+full plan: the repo, the schedule and why, and the commits it will make **as you** in repos that
+already exist: each peer's `staff.yaml`, and `org.yaml`. Nothing is left uncommitted on disk.
+
+For the first hire there is nobody to copy an App name from, so **Advanced** also has two:
+this staff member's App, and the shared public App, filled in as `<org>-<handle>` and
+`<org>-robot`. Names are unique across GitHub, so keep the org prefix. The public one only
+matters if a product repo is public.
 
 Product repos come from `org.yaml`. Mark one on the setup screen, or later with **Org → Add a
 product repo**.
 
+After **Hire** the list stays on the same staff member, now on step 2. Leave and come back later
+with **Finish setting up** on their card.
+
 ## 4. Create the App, and confirm the install
 
-**GitHub App**, on the new card. GitHub has no API that creates an App, so a tab opens and you
+**Create the App**, in step 2. GitHub has no API that creates an App, so a tab opens and you
 confirm. The App's id and private key go straight into the repo's secrets and never touch disk.
+The public App is offered too when a product repo is public.
 
 Then **Install it**. The install page opens with the organisation and every repo this staff
 member needs already ticked: its brain, the trackers of its peers, and the product repos. Check
 the list and confirm. That confirmation is yours by design: installing grants access, and GitHub
 asks a person.
 
-## 5. Store the agent credential, once
+## 5. Write the charter
 
-**Agent credential**, on the card or on the setup screen. Paste the token from `claude
-setup-token` (or your agent's key; the box says where to get one). It is stored as one
-organisation secret, shared with the brain repos, and each later hire is added to it. It is not
-asked for again.
+Step 3. **Let an AI interview you** is the same copy-a-prompt loop as step 2 of this guide, aimed
+at `CHARTER.md`, carrying the org layer, the peers' charters and, where the role matches one, a
+[worked example](writing-a-charter.md#worked-examples) to model the shape on. **Start from the
+template** opens that example in an editor with your business's name in it; edit it so it fits
+before saving. **Edit the file** is the file as it is. roster never generates a charter, because
+a generated one makes exactly the generic agent this whole arrangement exists to avoid.
 
-On GitHub Free an org secret does not reach private repos, so there it goes on each brain repo
-instead, and the page says so. It is still one paste now; a later hire needs it once more.
+## 6. Store the agent credential, once
 
-## 6. Write the charter
+Step 4, shown only while no credential is stored. It is also on the card and on the setup
+screen. Paste the token from `claude setup-token` (or your agent's key; the box says where to
+get one). It is stored as one organisation secret, shared with the brain repos, and each later
+hire is added to it. It is not asked for again.
 
-**Write the charter**, on the card. The same copy-a-prompt loop as step 2, aimed at
-`CHARTER.md`, carrying the org layer, the peers' charters and, where the role matches one, a
-[worked example](writing-a-charter.md#worked-examples) to model the shape on. The brief
-interviews you; the charter is yours. roster never generates one, because a generated charter
-makes exactly the generic agent this whole arrangement exists to avoid.
+On GitHub Free an org secret does not reach private repos, so there it goes on each brain repo
+instead, and the page says so. It is still one paste now; a later hire needs it once more.
 
 ## 7. Run it once
 
-**Run once now**, on the card or on **Health**. It starts the daily workflow, follows it, and
+**Run once now**, step 5, also on the card and on **Health**. It starts the daily workflow, follows it, and
 tells you how it ended, with the log.
 
 **A workflow that has never run has proved nothing**: not that the App is installed on the right

package/docs/manual-steps.md

@@ -45,8 +45,9 @@ hand. roster says so if it happens.
 ## 3. Confirm the App's install
 
 **Do:** press **Install it** in the portal, or open the link `roster app` prints. The page opens
-with the organisation and the repos this staff member needs already selected: its brain, each
-peer's tracker, and the product repos. Check the list and confirm.
+with the organisation and the repos this staff member needs already selected: its brain, the
+ops repo (every run checks it out first), each peer's tracker, and the product repos. Check the
+list and confirm. Choosing **All repositories** instead also works.
 
 **Why not automated:** installing is a grant of access to specific repositories, and GitHub asks
 a person to confirm it. That is correct and should not be worked around.

package/docs/portal.md

@@ -262,21 +262,48 @@ have more than one human, and a card that names one of two reads as the only one
 
 Everyone on the roster, and the things you would otherwise do from a terminal.
 
-**Hiring** runs the same `buildPlan` and `applyPlan` that `roster hire` does, on the server.
-Only the handle is required; everything else is copied from whoever is already here. The first
-hire has nobody to copy App names from, so its form also asks for the App's name and the shared
-public App's, which are `--app` and `--public-app`. The public one only matters when a product
-repo is public; on private ones the session uses the staff member's own App. You see
-the plan first, listing every file, every label, the schedule it chose and why, the commits it
-will make as you in repos that already exist (each peer's `staff.yaml`, `org.yaml`), whether the
-new brain joins the credential's org secret, and what is left for you. Nothing happens until you
-apply. What the terminal would have printed is shown when it finishes.
+**Hiring** starts from a role. With nobody hired the Staff screen opens on the role picker;
+after that it is behind **Hire someone**. The cards are CTO, CMO and Support, each with a line
+on what they do, and **Something else**, which asks for the role's name and a sentence about it.
+A role that is already hired is not offered. Picking one fills in the handle, name and repo
+(`cto`, `cmo`, `support`, or a handle made from the name) and leaves the schedule empty, so the
+server picks a free slot. All four are under **Advanced**, still editable. The first hire has
+nobody to copy App names from, so Advanced also holds the App's name and the shared public
+App's, which are `--app` and `--public-app`, filled in as `<org>-<handle>` and `<org>-robot`.
+The public one only matters when a product repo is public; on private ones the session uses the
+staff member's own App.
+
+The role opens a numbered list on the same screen:
+
+1. **Hire.** One sentence from the plan: the repo it creates and when it runs. **Show details**
+   has the full plan, from the same `buildPlan` and `applyPlan` that `roster hire` runs on the
+   server: every file, every label, the schedule and why, the commits it makes as you in repos
+   that already exist (each peer's `staff.yaml`, `org.yaml`), and whether the new brain joins
+   the credential's org secret. **Hire** asks before it acts.
+2. **Create their GitHub App.** The private App, and the shared public one only when a product
+   repo in `org.yaml` is public (or has no visibility written, which hire treats as public).
+3. **Write their charter.** Three tabs: an AI interview (the default), the matching worked
+   example with your business's name in place of Acme's, and the file itself. A role that
+   matches no example has no template tab.
+4. **Add your agent credential.** Only while none is stored.
+5. **Run once now.**
+
+Steps 2 to 5 say *Hire first* until the hire is done. Each step's Done comes from real data:
+the hire from the staff member appearing in `org.yaml`, the charter from `CHARTER.md` no longer
+being the stub (the same test as doctor's `charter.stub`), the App from its `_APP_ID` secret on
+the brain repo, the credential from the org secret, and the run from a successful daily run.
+After **Hire** the screen reloads the org and stays on the same staff member, on step 2.
+
+A card whose setup is not finished (a stub charter, no App secrets, or no successful run yet)
+shows **Finish setting up**, which opens the same list for them. The App secrets and the run
+are read from GitHub, so offline only the charter counts.
 
 **Writing the charter** is the copy-a-prompt loop below, aimed at `CHARTER.md`. `hire`
 deliberately does not write it, because a generated charter produces exactly the generic agent
 this whole arrangement exists to avoid. It is the same brief as `roster brief charter
 <handle>`, with somewhere to put the answer, and a picker for the worked example it carries as a
-model: matched to the role, or another, or none.
+model: matched to the role, or another, or none. For a role added with **Something else**, the
+sentence you typed goes into the brief.
 
 **The GitHub App** is `roster app`, on this server rather than a second one. There is no API that
 creates an App: the only route is the manifest flow, where you post a manifest to a settings page,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanocollective/roster",
-  "version": "0.1.0-alpha.23",
+  "version": "0.1.0-alpha.25",
   "description": "An agent-run org, powered by GitHub. Scaffold AI staff members whose brain is a repo.",
   "type": "module",
   "bin": {

package/templates/portal/css/setup.css

@@ -137,6 +137,30 @@
 .todohint{margin:8px 0 0 35px}
 .todobody{margin:12px 0 0 35px}
 .todobody .row{margin-top:10px}
+.todo.locked{background:transparent;border-style:dashed}
+.todo.locked h3{color:var(--ink-dim)}
+.todo.locked .todopill{background:none;border:1px solid var(--line);color:var(--ink-faint)}
+
+/* ---------- hiring on the Staff screen ---------- */
+
+.hirepane > h3{margin:0 0 10px;font:600 14.5px var(--sans)}
+.roles{display:grid;grid-template-columns:repeat(auto-fill,minmax(220px,1fr));gap:10px;max-width:920px}
+.role{display:grid;gap:5px;align-content:start;text-align:left;cursor:pointer;
+      background:var(--panel);border:1px solid var(--line);border-radius:var(--r-lg);padding:14px 16px;
+      color:var(--ink);font:inherit;
+      transition:border-color .15s var(--ease),box-shadow .15s var(--ease),transform .15s var(--ease)}
+.role:hover{border-color:var(--accent-dim);box-shadow:var(--shadow-sm);transform:translateY(-1px)}
+.role:focus-visible{outline:2px solid var(--accent);outline-offset:2px}
+.role b{font:600 14px var(--sans);letter-spacing:-.01em}
+.role span{color:var(--ink-dim);font:12.5px/1.5 var(--sans)}
+.roleform{max-width:560px;margin:14px 0 0}
+.roleform textarea{width:100%}
+.hireflow{max-width:920px}
+.hireflowhead{justify-content:space-between;margin:0 0 12px}
+.hireflowhead h2{margin:0;font:600 17px var(--sans);letter-spacing:-.015em}
+.hiresummary{margin:0;font:13.5px/1.55 var(--sans);color:var(--ink)}
+.hiresummary.err{color:var(--err)}
+.hireadvanced{margin-top:12px;padding:12px 14px;border:1px solid var(--line);border-radius:var(--r);max-width:560px}
 .qfield{display:grid;gap:5px;margin:0 0 12px}
 .qfield span{font:600 12.5px var(--sans)}
 .qfield input{background:var(--bg-elev);border:1px solid var(--border-strong);color:var(--ink);

package/templates/portal/js/api.js

@@ -86,13 +86,22 @@ export const planTenant = (params) =>
 export const createTenant = (params) => post(params, "/api/setup/apply");
 
 /** The copyable prompt, with every file it refers to carried inside it. */
-export const getBrief = (kind, staff, example) =>
+export const getBrief = (kind, staff, example, about) =>
   json(
     "/api/brief?kind=" + encodeURIComponent(kind) +
       (staff ? "&staff=" + encodeURIComponent(staff) : "") +
-      (example ? "&example=" + encodeURIComponent(example) : ""),
+      (example ? "&example=" + encodeURIComponent(example) : "") +
+      (about ? "&about=" + encodeURIComponent(about) : ""),
   );
 
+/** The worked charter that matches a staff member, with the business's name in it. */
+export const getCharterExample = (staff) =>
+  json("/api/charter-example?staff=" + encodeURIComponent(staff));
+
+/** Whether a staff member's App secrets are set and a daily run has succeeded. Online only. */
+export const getStaffProgress = (staff, fresh) =>
+  json("/api/staff/progress?staff=" + encodeURIComponent(staff) + (fresh ? "&fresh=1" : ""));
+
 /** Parse what came back from the model. Reads only: saving is a second, deliberate step. */
 export const parsePaste = (kind, staff, answer) =>
   fetch("/api/paste", {

package/templates/portal/js/app.js

@@ -111,6 +111,7 @@ export async function boot() {
 
   S.data = first;
   S.loadedAt = new Date();
+  S.staffOpen = null; // an open hire list survives a refresh, not a page load
   S.staffHandle = S.data.staff[0]?.handle ?? null;
   $("#orgname").textContent = S.data.name + " · " + S.data.staff.length + " staff";
 

package/templates/portal/js/state.js

@@ -36,6 +36,8 @@ export const S = {
   runs: null,
   sync: null,
   loadedAt: null,
+  /** The role whose hire list is open on the Staff screen, kept across a refresh. */
+  staffOpen: null,
 
   staffHandle: null,
   /* What is waiting on you, not whose brain you read last. The org-wide screens are where a

package/templates/portal/js/views/app.js

@@ -27,8 +27,7 @@ export function appPanel(opts) {
     }),
     el("p", {
       textContent:
-        "A tab opens, GitHub asks you to confirm, and the App's id and private key go straight " +
-        "into the repo's secrets. The key is held in memory and never written to disk.",
+        "A GitHub tab opens. Confirm there, then come back here to install it.",
     }),
   );