@nanocollective/roster 0.1.0-alpha.11 → 0.1.0-alpha.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanocollective/roster",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.13",
   "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

@@ -117,3 +117,7 @@
 .verdict{background:var(--accent-soft);border:1px solid transparent;border-radius:var(--r);
       padding:9px 12px;font-size:12.5px}
 .verdict p{margin:0}
+
+.plansteps{margin:6px 0 12px;padding-left:20px;font-size:13.5px;line-height:1.7}
+.planfiles{margin:0 0 12px}
+.planfiles summary{cursor:pointer;color:var(--ink-dim);font-size:12.5px}

package/templates/portal/js/views/checklist.js

@@ -10,6 +10,8 @@ import { el, toClipboard } from "../dom.js";
 const LEVEL_ORDER = { fail: 0, warn: 1, ok: 2 };
 
 /**
+ * @param opts.skip  finding ids the caller already shows as a step of its own, so they are not
+ *   reported twice. With `opts.hideWhenClean`, a list left empty draws nothing at all.
  * @param opts.shell  when Health draws this, the section it lives in: `{actions, say}`. The
  *   setup screen passes nothing and gets the layout it has always had. Its own screen is a
  *   wizard, where a chunky button and a paragraph under it are right; on Health it is one
@@ -32,9 +34,14 @@ export async function checklist(host, opts = {}) {
   const findings = (report.findings ?? []).slice().sort(
     (a, b) => (LEVEL_ORDER[a.level] ?? 3) - (LEVEL_ORDER[b.level] ?? 3),
   );
-  const bad = findings.filter((f) => f.level !== "ok");
+  const skip = new Set(opts.skip ?? []);
+  const bad = findings.filter((f) => f.level !== "ok" && !skip.has(f.id));
 
   host.replaceChildren();
+  if (!bad.length && opts.hideWhenClean) {
+    opts.onEmpty?.();
+    return;
+  }
   opts.shell?.say(bad.length ? String(bad.length) : "clean");
   host.append(
     el("p", {
@@ -83,7 +90,7 @@ export async function checklist(host, opts = {}) {
   const again = el("button", { className: btnClass, textContent: "Check again" });
   again.onclick = () => checklist(host, opts);
 
-  const feet = opts.shell?.actions ?? host;
+  const feet = opts.shell?.actions ?? host.appendChild(el("div", { className: "row" }));
   if (opts.shell) feet.replaceChildren();
   feet.append(copy, again, note);
   if (bad.length) {
@@ -92,8 +99,7 @@ export async function checklist(host, opts = {}) {
         className: noteClass,
         style: "flex-basis:100%",
         textContent:
-          "Paste it into Cursor, Claude Code or anything else that can edit files here, then " +
-          "check again. The ids above should be gone.",
+          "Paste them into your coding agent, then check again.",
       }),
     );
   }

package/templates/portal/js/views/credential.js

@@ -8,7 +8,7 @@ import { el } from "../dom.js";
 
 export function credentialPanel() {
   const box = el("div", { className: "manual" });
-  box.append(el("b", { textContent: "Your agent's credential, once" }));
+  box.append(el("b", { textContent: "Agent credential" }));
   const body = el("div");
   box.append(body);
   body.append(el("p", { className: "sub", textContent: "Looking at where it would go…" }));
@@ -28,8 +28,7 @@ function draw(body, c) {
       el("p", {
         className: "sub",
         textContent:
-          "Nothing reads it until somebody is hired, so this box opens once there is a staff " +
-          "member. It is asked for once, not once per hire.",
+          "Available after your first hire. You only add it once.",
       }),
     );
     return;
@@ -40,8 +39,7 @@ function draw(body, c) {
       el("p", {
         className: "sub",
         textContent:
-          c.name + " is already an org secret, shared with " + c.orgSecret.visibility + " repos. " +
-          "Each hire adds its brain to it. Paste a new one only to replace it.",
+          c.name + " is already set. Paste a new one only to replace it.",
       }),
     );
   }
@@ -53,7 +51,7 @@ function draw(body, c) {
         (c.plan.mode === "org"
           ? "Stored as one org secret, " + c.name + ", shared with " + c.brains.join(", ") + ". "
           : "Stored as " + c.name + " on each of " + c.brains.join(", ") + ", because " + c.plan.reason + ". ") +
-        "It goes to gh on standard input and is never written to disk.",
+        "It's never written to disk.",
     }),
   );
 
@@ -80,8 +78,8 @@ function draw(body, c) {
         el("p", {
           textContent:
             r.mode === "org"
-              ? "Stored once for the org, shared with " + r.repos.length + " brains."
-              : "Stored on " + r.repos.join(", ") + ".",
+              ? "Saved."
+              : "Saved on " + r.repos.join(", ") + ".",
         }),
       );
     } catch (err) {

package/templates/portal/js/views/repos.js

@@ -18,9 +18,7 @@ export function repoPicker(opts) {
     el("b", { textContent: "Which repos the staff work in" }),
     el("p", {
       textContent:
-        "Repos marked as products are the ones staff contribute to without owning. A new hire " +
-        "picks them up automatically; somebody already hired keeps the works_in list in their " +
-        "own staff.yaml.",
+        "Add the repos your staff should work on. New hires get access to them automatically.",
     }),
   );
 

package/templates/portal/js/views/setup.js

@@ -30,6 +30,12 @@ let S = null; // /api/setup/status, refreshed after anything that changes the wo
 /* Where the doctor checklist is drawn on this screen, so a save can re-run it. Left stale, it
    went on saying business.stub after business.md had been saved, until "Check again". */
 let healthHost = null;
+let healthStep = null;
+
+/* What the "What is left" cards already ask for. Doctor reporting them as well, right after a
+   successful create, read as the create having failed. */
+const COVERED = ["business", "business.stub", "priorities", "priorities.stub", "actions-access", "secrets", "agent"];
+const HEALTH = { skip: COVERED, hideWhenClean: true };
 
 /* Each "what is left" step that is a file, by id, so a save can mark it done in place rather
    than repainting the page and throwing away the diff somebody is still reading. */
@@ -66,8 +72,7 @@ export async function viewGettingStarted(main) {
     next.append(
       el("p", {
         textContent:
-          "Nothing runs until somebody is hired. Hiring creates their repo, their workflows and " +
-          "their pinned issue; the GitHub App and the charter follow on their card.",
+          "Nothing runs until you hire someone. You'll set up their GitHub App and charter from their card.",
       }),
       el("div", { className: "row" }, [hire]),
     );
@@ -76,11 +81,12 @@ export async function viewGettingStarted(main) {
 
   main.append(afterCreate(App.data?.staff?.length ? 1 : 2));
 
-  const health = step(App.data?.staff?.length ? 2 : 3, "What doctor still says", false);
+  const health = step(App.data?.staff?.length ? 2 : 3, "Other problems", false);
   healthHost = el("div", { style: "margin-top:12px" });
   health.append(healthHost);
   main.append(health);
-  checklist(healthHost, {});
+  healthStep = health;
+  checklist(healthHost, { ...HEALTH, onEmpty: () => health.remove() });
 }
 
 /** Whether the sidebar offers Getting started: while anything is left, or while it is open. */
@@ -94,7 +100,7 @@ export function paintSetupNav() {
    again rather than updated by hand. The sidebar's list comes from /api/org, which is the one
    the portal already reads. */
 async function recheck() {
-  if (healthHost) checklist(healthHost, {});
+  if (healthHost) checklist(healthHost, { ...HEALTH, onEmpty: () => healthStep?.remove() });
   try {
     S = await getSetup();
     for (const [id, mark] of fileSteps) mark(!(S.tenant.left ?? []).includes(id));
@@ -120,9 +126,7 @@ function render(main) {
     el("p", {
       className: "sub",
       textContent:
-        "Sign in with gh, choose the organisation and the agent, then what is left: a setting " +
-        "roster tries for you, the agent's credential, the repos your staff work in, and the two " +
-        "files only you can write. Nothing is created until you have read the plan.",
+        "Choose an organisation and a coding agent. Nothing is created until you press Create it.",
     }),
   );
 
@@ -148,8 +152,7 @@ function stepGh() {
     el("p", {
       className: "sub",
       textContent:
-        "roster does everything through your own gh, so it holds no token of its own. Run this " +
-        "in a terminal, then reload:",
+        "Run this in a terminal, then reload:",
     }),
     el("pre", { className: "cmd", textContent: "gh auth login" }),
   );
@@ -170,13 +173,9 @@ function stepOrg(main) {
       el("p", {
         className: "sub",
         textContent:
-          "Reload the page to open the portal. Anything below that is still undone stays under " +
-          "Getting started in the sidebar until it is.",
+          "Finish the steps below. They stay under Getting started in the sidebar until they're done.",
       }),
     );
-    healthHost = el("div", { style: "margin-top:12px" });
-    card.append(healthHost);
-    checklist(healthHost, {});
     return card;
   }
 
@@ -206,8 +205,7 @@ function stepOrg(main) {
   orgWrap.append(
     el("small", {
       textContent:
-        "Repos are created here. GitHub has no API for creating an organisation, so make one on " +
-        "github.com first if you need to.",
+        "Don't have one? Create it on github.com first.",
     }),
   );
   form.append(orgWrap);
@@ -250,8 +248,8 @@ function stepOrg(main) {
   });
   other.input.addEventListener("change", look);
 
-  const name = field("name", "What the business is called", "", "Shown to the agents. Defaults to the org.");
-  const human = field("human", "Your GitHub login", S.gh.login ?? "", "The person the agents answer to.");
+  const name = field("name", "What the business is called", "", "Defaults to the organisation name.");
+  const human = field("human", "Your GitHub login", S.gh.login ?? "", "The person the staff report to.");
 
   card.append(form);
   const agentHead = el("h3", { textContent: "Which coding agent runs a session" });
@@ -272,8 +270,7 @@ function stepOrg(main) {
   const agentNote = el("p", {
     className: "sub",
     textContent:
-      "Anything else works too: a runner is an install command, a run command and the name of " +
-      "the secret holding its credential. Write those three into org.yaml afterwards.",
+      "Using a different agent? Pick any of these, then set it in org.yaml afterwards.",
   });
   card.append(agentNote);
 
@@ -349,26 +346,20 @@ function stepOrg(main) {
     out.replaceChildren(el("p", { className: "sub", textContent: "Working…" }));
     try {
       const result = await planTenant(p);
-      out.replaceChildren();
-      out.append(
-        el("p", {
-          textContent:
-            `${result.files.length} files in ${result.dir}, and one private repo, ${p.org}/roster-ops, ` +
-            "with its Actions access set so every repo in the org can call its workflow. If GitHub " +
-            "refuses that, you get the reason and the page to click.",
-        }),
-      );
-      const list = el("div", { className: "filelist" });
-      for (const f of result.files) list.append(el("code", { textContent: "+ " + f }));
-      out.append(list);
-      out.append(
-        el("p", {
-          className: "sub",
-          textContent:
-            "org/business.md arrives as questions, not prose. Answering it is the next step and " +
-            "it is the one that decides whether any of this is worth running.",
-        }),
-      );
+      const steps = el("ol", { className: "plansteps" }, [
+        el("li", { textContent: `Create a private repo, ${p.org}/roster-ops, to hold the org's shared settings.` }),
+        el("li", { textContent: `Put a copy of it in ${result.dir}.` }),
+        el("li", { textContent: `Let the other repos in ${p.org} run its workflow.` }),
+      ]);
+      const files = el("details", { className: "planfiles" }, [
+        el("summary", { textContent: `The ${result.files.length} files it writes` }),
+        el("div", { className: "filelist" }, result.files.map((f) => el("code", { textContent: f }))),
+      ]);
+      const next = el("p", {
+        className: "sub",
+        textContent: "After that: describe the business, set this month's priorities, and hire your first staff member.",
+      });
+      out.replaceChildren(el("p", { textContent: "Create it will:" }), steps, files, next);
       go.hidden = false;
     } catch (err) {
       out.replaceChildren(el("p", { className: "err", textContent: String(err.message || err) }));
@@ -401,13 +392,6 @@ function stepOrg(main) {
 function afterCreate(n) {
   fileSteps.clear();
   const card = step(n, "What is left", false);
-  card.append(
-    el("p", {
-      textContent:
-        "The first is a setting roster tries for you. The last two are the files that decide " +
-        "whether any of this is worth running, and only you can write them.",
-    }),
-  );
   card.append(accessStep());
   card.append(credentialPanel());
 
@@ -417,9 +401,8 @@ function afterCreate(n) {
 
   const business = fileStep(
     "business",
-    "Answer org/business.md",
-    "It ships as questions. It is composed into the top of every prompt, every run, and an " +
-      "agent that cannot answer them writes work that is plausible and generic.",
+    "Describe the business",
+    "Answer the questions in org/business.md. Every staff member reads it before they start work.",
   );
   // The copy-a-prompt loop, which is the whole answer to "how do I write this file".
   business.append(paste({ kind: "discover", title: "Write it with your own AI", onSaved: recheck }));
@@ -427,9 +410,8 @@ function afterCreate(n) {
 
   const priorities = fileStep(
     "priorities",
-    "Rank org/priorities.md",
-    "What matters this month, at most three things in order, and what is out of scope. Every " +
-      "daily run reads it; without it each staff member picks its own direction from its charter.",
+    "Set this month's priorities",
+    "Up to three things, in order, plus what's out of scope. Saved as org/priorities.md.",
   );
   priorities.append(prioritiesEditor());
   card.append(priorities);
@@ -500,7 +482,7 @@ function prioritiesEditor() {
         el("p", {
           className: r.pushed ? "sub" : "err",
           textContent: r.pushed
-            ? "Committed and pushed. Every daily run reads it from the next one."
+            ? "Saved and pushed."
             : "Committed, but the push failed: " + (r.note ?? ""),
         }),
       );
@@ -529,7 +511,7 @@ function opsName() {
  */
 function accessStep() {
   const box = el("div", { className: "manual" });
-  box.append(el("b", { textContent: "Let every repo in the org call the ops repo's workflow" }));
+  box.append(el("b", { textContent: "Let staff repos run the shared workflow" }));
   const out = el("div");
   box.append(out);
   const say = (text, cls) => el("p", { className: cls ?? "sub", textContent: text });
@@ -539,8 +521,7 @@ function accessStep() {
     out.replaceChildren(
       say(
         (why ? why + " " : "") +
-          "Settings → Actions → General → Access on roster-ops. Skip it and every workflow fails " +
-          "with “workflow not found”.",
+          "Needed so staff repos can run the shared workflow.",
       ),
       el("div", { className: "row" }, [go]),
     );
@@ -549,7 +530,7 @@ function accessStep() {
       try {
         const r = await setAccess();
         if (r.ok) {
-          out.replaceChildren(say("Set. Every repo in the org can call roster-ops."));
+          out.replaceChildren(say("Done."));
           return;
         }
         out.replaceChildren(
@@ -567,7 +548,7 @@ function accessStep() {
   out.replaceChildren(say("Checking…"));
   getAccess()
     .then((r) => {
-      if (r.ok) out.replaceChildren(say("Done. Every repo in the org can call roster-ops."));
+      if (r.ok) out.replaceChildren(say("Done."));
       else offer(r.level ? "It is set to “" + r.level + "”." : "");
     })
     .catch(() => offer(""));