@nanocollective/roster 0.1.0-alpha.7 → 0.1.0-alpha.9

package/dist/cli.js

@@ -1245,6 +1245,25 @@ function repoName(full) {
 import { execFile as execFile3 } from "child_process";
 import { existsSync as existsSync11, mkdirSync, readFileSync as readFileSync10 } from "fs";
 import { join as join11 } from "path";
+
+// src/lib/stub.ts
+var MARKERS = [
+  "**This file is a stub",
+  "This file is a stub, and it is the most important file in this repo",
+  "This file is a stub, and everything the staff say is downstream of it",
+  "The headings below are the shape that has worked; the words are yours",
+  "Write it with your own AI",
+  "One paragraph. What this role is for, in this business specifically.",
+  "Not a segment. The person, what they were doing ten minutes before they arrived",
+  "The single thing this staff member is optimising",
+  "Or answer these by hand. Short is better than complete."
+];
+function looksUnwritten(body) {
+  if (!body.trim()) return true;
+  return MARKERS.some((marker) => body.includes(marker));
+}
+
+// src/lib/setup.ts
 var AGENTS = [
   {
     id: "claude-code-action",
@@ -1303,7 +1322,8 @@ async function setupStatus(startedIn) {
       root: found.root,
       opsDir: found.opsDir,
       org: readOrgName(found.opsDir),
-      repos: readRepoNames(found.opsDir)
+      repos: readBlockNames(found.opsDir, "repos", "name"),
+      left: unfinished(found.opsDir, readBlockNames(found.opsDir, "staff", "handle").length)
     } : { found: false },
     gh: ready.ok ? { ok: true, login: ready.data?.login } : { ok: false, error: ready.error ?? "gh is not ready" },
     orgs,
@@ -1317,23 +1337,36 @@ function readOrgName(opsDir) {
   const m = /^org:\s*(\S+)\s*$/m.exec(readFileSync10(path, "utf8"));
   return m?.[1];
 }
-function readRepoNames(opsDir) {
+function readBlockNames(opsDir, block, key) {
   const path = join11(opsDir, "org.yaml");
   if (!existsSync11(path)) return [];
   const names = [];
+  const pattern = new RegExp(`\\b${key}:\\s*([\\w.-]+)`);
   let inside = false;
   for (const line of readFileSync10(path, "utf8").split("\n")) {
-    if (/^repos:\s*$/.test(line)) {
+    if (new RegExp(`^${block}:\\s*$`).test(line)) {
       inside = true;
       continue;
     }
     if (inside && /^\S/.test(line)) break;
     if (!inside) continue;
-    const m = /name:\s*([\w.-]+)/.exec(line);
+    const m = pattern.exec(line);
     if (m) names.push(m[1]);
   }
   return names;
 }
+function unfinished(opsDir, staffCount) {
+  const out = [];
+  if (!staffCount) out.push("hire");
+  for (const [id, rel] of [
+    ["business", "org/business.md"],
+    ["priorities", "org/priorities.md"]
+  ]) {
+    const path = join11(opsDir, rel);
+    if (!existsSync11(path) || looksUnwritten(readFileSync10(path, "utf8"))) out.push(id);
+  }
+  return out;
+}
 async function loadFrameworkComposer() {
   const path = join11(templatesRoot(), "ops", "compose.mjs");
   return await import(`file://${path}`);
@@ -1615,9 +1648,12 @@ function buildPlan(ws, org, handle, opts, parseYaml) {
   }
   if (!app) warnings.push("no app slug could be inferred; pass --app");
   const publicApp = opts.publicApp ?? publicIdentity?.app ?? "";
-  if (!publicApp) {
+  const publicProducts = (org.repos ?? []).filter(
+    (r) => r.role === "product" && String(r.visibility ?? "").toLowerCase() !== "private"
+  );
+  if (!publicApp && publicProducts.length) {
     warnings.push(
-      "no shared public identity yet \u2014 pass --public-app, or the product-repo lane will not work"
+      `no shared public identity yet \u2014 pass --public-app, or the product-repo lane will not work on ${publicProducts.map((r) => r.name).join(", ")}, which is public`
     );
   }
   const staff = {
@@ -2630,23 +2666,6 @@ function budgetOf(value) {
   return typeof n === "number" && Number.isFinite(n) && n > 0 ? n : null;
 }
 
-// src/lib/stub.ts
-var MARKERS = [
-  "**This file is a stub",
-  "This file is a stub, and it is the most important file in this repo",
-  "This file is a stub, and everything the staff say is downstream of it",
-  "The headings below are the shape that has worked; the words are yours",
-  "Write it with your own AI",
-  "One paragraph. What this role is for, in this business specifically.",
-  "Not a segment. The person, what they were doing ten minutes before they arrived",
-  "The single thing this staff member is optimising",
-  "Or answer these by hand. Short is better than complete."
-];
-function looksUnwritten(body) {
-  if (!body.trim()) return true;
-  return MARKERS.some((marker) => body.includes(marker));
-}
-
 // src/commands/upgrade.ts
 import { execFileSync as execFileSync5 } from "child_process";
 import {
@@ -5335,6 +5354,29 @@ function short3(e) {
   return line.length > 200 ? `${line.slice(0, 199)}\u2026` : line;
 }
 
+// src/lib/browser.ts
+import { spawn } from "child_process";
+function shouldOpen(env, isTTY, noOpen) {
+  if (noOpen || !isTTY) return false;
+  if (env.CI || env.BROWSER === "none" || env.SSH_CONNECTION) return false;
+  return true;
+}
+function openerFor(platform, url) {
+  if (platform === "darwin") return ["open", [url]];
+  if (platform === "win32") return ["cmd", ["/c", "start", "", url]];
+  return ["xdg-open", [url]];
+}
+function openBrowser(url) {
+  const [cmd, args] = openerFor(process.platform, url);
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+
 // src/lib/inbox.ts
 import { execFile as execFile5 } from "child_process";
 import { promisify as promisify4 } from "util";
@@ -5664,20 +5706,20 @@ function parsePaste(raw, targets) {
   const known = new Map(targets.map((t) => [t.path, t]));
   BLOCK.lastIndex = 0;
   for (const m of text.matchAll(BLOCK)) {
-    const path = m[1].trim();
+    const written = m[1].trim();
     const body = strip(m[2] ?? "");
-    const target = known.get(path);
+    const target = resolveTarget(written, known);
     if (!target) {
       problems.push({
         id: "unknown-path",
-        path,
-        message: `The answer writes ${path}, which this brief did not ask for.`,
+        path: written,
+        message: `The answer writes ${written}, which this brief did not ask for.`,
         retry: `Write only ${[...known.keys()].join(", ")}, using the sentinels exactly as given.`
       });
       continue;
     }
     files.push({
-      path,
+      path: target.path,
       text: ensureNewline(body),
       unchanged: body.trim() === target.before.trim()
     });
@@ -5724,6 +5766,14 @@ ${END}`
   }
   return { files, problems };
 }
+function resolveTarget(written, known) {
+  const exact = known.get(written);
+  if (exact) return exact;
+  const tail2 = written.replace(/^(\.\/)+/, "").replace(/^\/+/, "");
+  if (!tail2 || tail2.split("/").includes("..")) return void 0;
+  const matches = [...known.values()].filter((t) => t.path === tail2 || t.path.endsWith(`/${tail2}`));
+  return matches.length === 1 ? matches[0] : void 0;
+}
 function strip(body) {
   const trimmed = body.replace(/^\n+/, "").replace(/\s+$/, "");
   const fenced = /^(`{3,}|~{3,})[^\n]*\n([\s\S]*)\n\1\s*$/.exec(trimmed);
@@ -6241,6 +6291,7 @@ roster portal
   --host <addr>  default 127.0.0.1. Anything else exposes write actions to the network.
   --ops <dir>    ops repo directory (default: found by walking up)
   --dir <path>   where a tenant would be created or checked out (default: here)
+  --no-open      don't open a browser (also off in CI, over SSH, or with BROWSER=none)
 `;
 var MIME = {
   ".md": "text/plain; charset=utf-8",
@@ -6501,7 +6552,8 @@ async function portalCommand(argv) {
       const payload = JSON.parse(await body(req) || "{}");
       const name = String(payload.name ?? "");
       const role = String(payload.role ?? "product");
-      if (!/^[\w.-]+$/.test(name) || !/^(product|brain|ops|repo)$/.test(role)) {
+      const visibility = String(payload.visibility ?? "private").toLowerCase();
+      if (!/^[\w.-]+$/.test(name) || !/^(product|brain|ops|repo)$/.test(role) || !/^(private|public|internal)$/.test(visibility)) {
         res.writeHead(400, { "content-type": "application/json" });
         res.end(JSON.stringify({ error: "a repo name and a known role are needed" }));
         return;
@@ -6515,7 +6567,11 @@ async function portalCommand(argv) {
       const result = saveFile(
         ws,
         `${ws.opsName}/org.yaml`,
-        insertUnder(text, "repos", `  - { name: ${name}, visibility: private, role: ${role} }`),
+        insertUnder(
+          text,
+          "repos",
+          `  - { name: ${name}, visibility: ${visibility}, role: ${role} }`
+        ),
         `portal: org.yaml lists ${name}`
       );
       json(res, { ok: true, ...result });
@@ -6715,11 +6771,12 @@ async function portalCommand(argv) {
       if (url.pathname === "/api/org") {
         const org = readOrg(w.opsDir, parseYaml);
         const data = buildExport(w, org, parseYaml);
+        const left = unfinished(w.opsDir, (org.staff ?? []).length);
         res.writeHead(200, {
           "content-type": "application/json; charset=utf-8",
           "cache-control": "no-store"
         });
-        res.end(JSON.stringify(data));
+        res.end(JSON.stringify({ ...data, unfinished: left }));
         return;
       }
       if (url.pathname === "/api/orglayer") {
@@ -7347,6 +7404,9 @@ ${warn}
 
 `
       );
+      if (shouldOpen(process.env, Boolean(process.stdout.isTTY), opts.noOpen === true)) {
+        openBrowser(`http://localhost:${port}`);
+      }
     });
   });
 }
@@ -7447,6 +7507,10 @@ function parseFlags11(argv) {
   const out = {};
   for (let i = 0; i < argv.length; i++) {
     const flag = argv[i];
+    if (flag === "--no-open") {
+      out.noOpen = true;
+      continue;
+    }
     const value = argv[++i];
     if (value === void 0) throw new Error(`${flag} needs a value`);
     if (flag === "--port") out.port = Number(value);

package/docs/commands.md

@@ -271,8 +271,12 @@ which is the shortest way in.
 --port <n>    default 4300
 --host <a>    default 127.0.0.1. Anything else exposes write actions to the network.
 --dir <path>  where a tenant would be created or checked out. Default: here.
+--no-open     don't open a browser
 ```
 
+It opens the page in your browser when it starts. It stays closed in CI, over SSH, when output
+is not a terminal, or with `BROWSER=none`.
+
 **With no tenant where you started it, this is the setup screen**: it stands up a new org, or
 checks out one that already runs roster. Local only. See [the portal](portal.md).
 

package/docs/getting-started.md

@@ -50,6 +50,9 @@ Creating it makes `<org>/roster-ops` and **sets its Actions access** so every re
 can call its workflow. Without that every run fails with "workflow not found". If GitHub refuses
 (it needs admin on the repo), the page says why and links to the setting to click instead.
 
+The rest of the steps stay on the same page. Reload it and the portal opens on **Getting
+started**, which keeps them in the sidebar until they are done, with hiring first.
+
 ## 2. Say what the business is
 
 `org/business.md` ships as questions, and it is composed into the top of every prompt. An agent
@@ -61,7 +64,8 @@ reply into the box and you get a diff and a save button. See
 [the portal](portal.md#copy-a-prompt-paste-the-answer-back).
 
 Then `org/priorities.md`: what matters this month, ranked, and what is out of scope. A few
-lines, only you can write it. See [concepts](concepts.md#priorities).
+lines, only you can write it, so it opens in place on the setup screen and saves the same way.
+See [concepts](concepts.md#priorities).
 
 ## 3. Hire someone
 
@@ -71,7 +75,13 @@ lines, only you can write it. See [concepts](concepts.md#priorities).
 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.
 
-For the first hire there is nobody to copy an App name from, so it asks.
+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.
+
+Product repos come from `org.yaml`. Mark one on the setup screen, or later with **Org → Add a
+product repo**.
 
 ## 4. Create the App, and confirm the install
 

package/docs/portal.md

@@ -18,6 +18,9 @@ Keep the repos checked out beside each other, in the same shape the runner uses.
 
 ## The sidebar
 
+Anything that asks before it acts (a merge, a push, a hire, a retire, a paid run) asks in the
+page's own dialog, never the browser's `confirm()`, which blocks the whole tab.
+
 **The counts are right on load.** The badges beside Inbox and Pending work are fetched once at
 boot, and the Inbox screen shares that request rather than making a second one. A sidebar that
 says nothing until you look at it is not a sidebar.
@@ -56,12 +59,24 @@ and where it will be stored (one org secret shared with the brains, or each brai
 secret would not arrive, with the reason). The value goes to the local server in a POST and from
 there to `gh` on standard input; it is never written to disk or echoed back. Until somebody is
 hired the box says so, because nothing would read it. Then which repos the staff work in, as a
-picker over what your `gh` can see minus what `org.yaml` already has, and a prompt for writing
-`org/business.md`.
+picker over what your `gh` can see minus what `org.yaml` already has, recorded with the
+visibility GitHub reports. Then the two files only you can write: a prompt for writing
+`org/business.md`, and `org/priorities.md` opened in place, stub and all, to replace with what
+matters this month. Each says whether it is written yet.
 
 Nothing here stores which step you are on. Setup takes days rather than minutes: an App has to be
 installed, a credential set, a first run finished. So the page derives its state from `roster
-doctor` every time it is drawn. A stored step counter would disagree with the world within an hour.
+doctor` every time it is drawn, and runs the check again after anything on it is saved. A stored
+step counter would disagree with the world within an hour.
+
+### Getting started
+
+**Once the org exists, the same steps stay in the sidebar as *Getting started*** for as long as
+anything is left: nobody hired, or `org/business.md` or `org/priorities.md` still the stub. An
+org nobody has been hired into opens on it rather than on an empty Inbox, with *Hire your first
+staff member* first, then the Actions setting, the credential, the repo picker, both files, and
+what doctor still says. A link to another screen still wins. When the list is empty the entry
+goes away; the repo picker lives on under [Org](#org).
 
 ## Inbox
 
@@ -217,6 +232,10 @@ prompt files in `prompts/`, each with a line saying what it is for, because a fi
 you nothing about which to open. Anything roster does not ship falls back to its own first
 heading.
 
+**Add a product repo** opens the same picker setup uses, so a repo created later does not mean
+typing `role: product` into `org.yaml` by hand. Adding one commits `org.yaml` and pushes. A new
+hire picks it up; somebody already hired keeps the `works_in` in their own `staff.yaml`.
+
 **The list comes off disk**, not out of the page, so a tenant that adds `org/pricing.md` can
 open it like any other. Only files the
 portal may actually write are listed: an editor that offers a file it cannot save is a trap.
@@ -244,7 +263,10 @@ 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. You see
+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

package/package.json

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

@@ -56,6 +56,8 @@
 
 .manual{background:var(--bg-elev);border:1px solid var(--line);border-radius:var(--r);
       padding:13px 15px;margin:11px 0}
+/* A file step that is written says so in the border too, the way a finished step does. */
+.manual.done{border-color:color-mix(in srgb,var(--accent) 30%,var(--line))}
 .manual b{display:block;font:600 13px var(--sans);margin-bottom:4px}
 .manual p{margin:0 0 6px;font-size:13px}
 .manual small{display:block;color:var(--ink-faint);font-size:11.5px;line-height:1.5;margin-bottom:9px}

package/templates/portal/index.html

@@ -27,6 +27,10 @@
       <span class="sync" data-icon="refresh"></span><span id="loaded">data now</span>
     </button>
 
+    <!-- Only while something is left to set up; app.js decides. -->
+    <button class="nav top" id="setupnav" data-view="setup" hidden>
+      <span class="ic" data-icon="task-done"></span> Getting started
+    </button>
     <button class="nav top" id="inboxnav" data-view="inbox">
       <span class="ic" data-icon="inbox"></span> Inbox
       <span class="n" id="inboxcount"></span>
@@ -52,7 +56,10 @@
 
     <!-- The heading is the fold. Collapsed, it carries the count, because a hidden list still
          has to say how much it is hiding. -->
-    <button class="sect sectfold" id="stafffold" aria-expanded="false" aria-controls="stafflist">
+    <!-- Named apart from the Staff screen above it: two controls both called "Staff" is how a
+         click meant for the screen landed on the fold, for people and for automation alike. -->
+    <button class="sect sectfold" id="stafffold" aria-expanded="false" aria-controls="stafflist"
+            aria-label="Staff list" title="Show or hide each staff member's own screens">
       <span class="caret" data-icon="chevron"></span>Staff<span class="n" id="staffcount" hidden></span>
     </button>
     <div id="stafflist"></div>

package/templates/portal/js/api.js

@@ -110,7 +110,9 @@ export const getDoctor = (offline) => json("/api/doctor" + (offline ? "?offline=
 export const getFix = (offline) => json("/api/fix" + (offline ? "?offline=1" : ""));
 
 export const listRepos = (org) => json("/api/setup/repos?org=" + encodeURIComponent(org));
-export const addRepo = (name, role) => post({ name, role }, "/api/setup/add-repo");
+/** Commits org.yaml and pushes, as every other write here does. */
+export const addRepo = (name, role, visibility) =>
+  post({ name, role, visibility }, "/api/setup/add-repo");
 export const startApp = (staff, scope) => post({ staff, scope }, "/api/setup/app");
 export const appResult = (state) => json("/api/setup/app-result?state=" + encodeURIComponent(state));
 

package/templates/portal/js/app.js

@@ -14,7 +14,7 @@ import {
   syncNotice,
 } from "./refresh.js";
 import { onRender } from "./router.js";
-import { ORG_WIDE, S, VIEWS, applyHash, writeHash } from "./state.js";
+import { ORG_WIDE, S, VIEWS, applyHash, readHash, writeHash } from "./state.js";
 import { viewBrain } from "./views/brain.js";
 import { viewChanged } from "./views/changed.js";
 import { viewDocs } from "./views/docs.js";
@@ -24,10 +24,11 @@ import { viewInbox, viewPrs } from "./views/inbox.js";
 import { viewOrg } from "./views/org.js";
 import { viewPrompt } from "./views/prompt.js";
 import { viewRuns } from "./views/runs.js";
-import { viewSetup } from "./views/setup.js";
+import { paintSetupNav, viewGettingStarted, viewSetup } from "./views/setup.js";
 import { viewStaff } from "./views/staff.js";
 
 const SCREEN = {
+  setup: viewGettingStarted,
   inbox: viewInbox,
   prs: viewPrs,
   runs: viewRuns,
@@ -52,8 +53,38 @@ const SCREEN = {
  */
 const NEEDS = ["org", "name", "opsName", "staff"];
 
+/** The org-wide screens in the sidebar, by button. */
+const NAV = [
+  ["#setupnav", "setup"],
+  ["#inboxnav", "inbox"],
+  ["#prsnav", "prs"],
+  ["#runsnav", "runs"],
+  ["#staffnav", "staff"],
+  ["#orgnav", "org"],
+  ["#docsnav", "docs"],
+];
+
 export async function boot() {
   initTheme();
+
+  /* Bound before the first request rather than after it. The sidebar is markup, so it is on
+     screen and clickable while /api/org is still building the export, and a click in that
+     window used to do nothing at all: the first click on Staff after a load was simply lost.
+     Now it is remembered and honoured once there is something to render. */
+  let early = null;
+  for (const [id, view] of NAV) {
+    const b = $(id);
+    if (!b) continue;
+    b.onclick = () => {
+      if (!S.data) {
+        early = view;
+        return;
+      }
+      S.view = view;
+      render();
+    };
+  }
+
   /* Before the first render, and once: it is delegated, so it covers every image any screen
      draws from here on, including the setup screen. */
   installLightbox();
@@ -90,16 +121,15 @@ export async function boot() {
     slot.innerHTML = iconHTML(slot.dataset.icon);
   }
   onRender(render);
+  const linked = readHash() !== null;
   applyHash();
+  /* An org nobody has been hired into has an empty Inbox, which says nothing about what to do
+     next. It opens on what is left instead, unless a link or a click asked for somewhere else. */
+  if (early) S.view = early;
+  else if (!linked && (S.data.unfinished ?? []).includes("hire")) S.view = "setup";
   initStaffFold();
   paintSidebar();
 
-  $("#inboxnav").onclick = () => { S.view = "inbox"; render(); };
-  $("#prsnav").onclick = () => { S.view = "prs"; render(); };
-  $("#runsnav").onclick = () => { S.view = "runs"; render(); };
-  $("#staffnav").onclick = () => { S.view = "staff"; render(); };
-  $("#orgnav").onclick = () => { S.view = "org"; render(); };
-  $("#docsnav").onclick = () => { S.view = "docs"; render(); };
   $("#refreshall").onclick = () => refreshAll(false);
 
   /* Coming back to the tab after a run should show the run — and coming back to it thirty
@@ -299,6 +329,7 @@ function render() {
   // A refresh can add or remove a staff member, and the sidebar is built once.
   const roster = S.data.staff.map((s) => s.handle).join(" ");
   if (roster !== paintedRoster) paintSidebar();
+  paintSetupNav();
   markSidebar();
   stampCounts();
   writeHash(true);

package/templates/portal/js/dialog.js

@@ -111,3 +111,50 @@ export function askText({
     ta.setSelectionRange?.(ta.value.length, ta.value.length);
   });
 }
+
+/**
+ * Asking before something that cannot be taken back: a merge, a push, a new repo, a paid run.
+ *
+ * Native `confirm()` looked like the browser rather than this page, and it blocks the whole
+ * tab, which froze browser automation mid-run. This is the same `<dialog>` as askText, so the
+ * backdrop, Escape and the focus trap come free. The wording is the caller's: `title` is the
+ * question, `hint` says what will happen.
+ *
+ * @returns true only for the confirm button. Escape, Cancel and the backdrop are all no.
+ */
+export function askYes({ title, hint, confirm = "Continue" }) {
+  const box = document.createElement("dialog");
+  // The test shim has no dialog element; see askText.
+  if (typeof box.showModal !== "function") {
+    return Promise.resolve(Boolean(globalThis.confirm?.(hint ? title + "\n\n" + hint : title)));
+  }
+
+  box.className = "ask";
+  box.append(el("h3", { textContent: title }));
+  if (hint) box.append(el("p", { className: "askhint", textContent: hint }));
+
+  const cancel = el("button", { className: "ghbtn", textContent: "Cancel" });
+  const go = el("button", { className: "ghbtn primary", textContent: confirm });
+  box.append(el("div", { className: "row askrow" }, [cancel, go]));
+
+  return new Promise((resolve) => {
+    let answer = false;
+    const done = (yes) => {
+      answer = yes;
+      box.close();
+    };
+    cancel.onclick = () => done(false);
+    go.onclick = () => done(true);
+    box.addEventListener("close", () => {
+      box.remove();
+      resolve(answer);
+    });
+    box.addEventListener("click", (e) => {
+      if (onBackdrop(e, box.getBoundingClientRect?.())) done(false);
+    });
+    document.body.append(box);
+    box.showModal();
+    // Cancel has the focus, so an Enter pressed out of habit does not merge anything.
+    cancel.focus();
+  });
+}

package/templates/portal/js/state.js

@@ -22,7 +22,7 @@ export const VIEWS = [
 export const VIEW_ALIAS = { memory: "brain" };
 
 /** Screens that belong to the org rather than to one staff member. */
-export const ORG_WIDE = new Set(["inbox", "prs", "runs", "org", "staff", "docs"]);
+export const ORG_WIDE = new Set(["setup", "inbox", "prs", "runs", "org", "staff", "docs"]);
 
 /** The two screens that read the inbox, and so share its filters and its `?t=` thread. */
 const INBOXY = new Set(["inbox", "prs"]);

package/templates/portal/js/views/health.js

@@ -1,6 +1,7 @@
 /* Is the scaffolding still there, has the agent been running, and what does lint say. */
 
 import { post } from "../api.js";
+import { askYes } from "../dialog.js";
 import { ago, el, esc, kb } from "../dom.js";
 import { inline } from "../md.js";
 import { render } from "../router.js";
@@ -281,7 +282,7 @@ export async function askToFix(s, problems, btn, status) {
     "Fix in your next session and close this.",
   ].join("\n");
 
-  if (!confirm("Open an issue in " + s.brain + "?")) return;
+  if (!(await askYes({ title: "Open an issue in " + s.brain + "?", confirm: "Open it" }))) return;
   btn.disabled = true;
   status.textContent = "opening…";
   status.className = "meta";

package/templates/portal/js/views/inbox.js

@@ -1,7 +1,7 @@
 /* The inbox: everything open across the org, and the thread beside it. */
 
 import { getLabels, getPr, getThread, post, upload } from "../api.js";
-import { askText } from "../dialog.js";
+import { askText, askYes } from "../dialog.js";
 import { ago, el, esc, markCurrent, skeleton } from "../dom.js";
 import { icon, iconHTML } from "../icons.js";
 import { mdlite } from "../md.js";
@@ -693,7 +693,11 @@ function inboxScreen(m, opts) {
         merge.title = "This branch conflicts with its base";
       }
       merge.onclick = async () => {
-        if (!confirm("Merge " + item.repo + " #" + item.number + " into its base branch?")) return;
+        const yes = await askYes({
+          title: "Merge " + item.repo + " #" + item.number + " into its base branch?",
+          confirm: "Merge",
+        });
+        if (!yes) return;
         busy(true, "merging…");
         try {
           await post({ action: "merge", repo: item.repo, number: item.number });

package/templates/portal/js/views/org.js

@@ -15,11 +15,13 @@
  */
 
 import { getFile, getOrgLayer, post } from "../api.js";
+import { askYes } from "../dialog.js";
 import { el, esc, grow, kb, skeleton } from "../dom.js";
 import { icon } from "../icons.js";
 import { mdlite } from "../md.js";
 import { humansOf, S, writeHash } from "../state.js";
 import { yamlPre } from "../yaml.js";
+import { repoPicker } from "./repos.js";
 
 /* What the files roster itself ships are for, in one line each. A filename says nothing about
    which one to open; anything a tenant has added of its own falls back to its first heading. */
@@ -77,6 +79,20 @@ export function viewOrg(m) {
   );
   m.append(facts);
 
+  /* Marking a product repo after setup. The picker only lived on the setup screen, so a repo
+     created later meant typing `role: product` into org.yaml by hand. Folded, because it asks
+     GitHub for every repo in the org and most visits here are to read a file. */
+  const repoPane = el("div");
+  const repos = el("button", { className: "ghbtn", textContent: "Add a product repo" });
+  repos.onclick = () => {
+    if (repoPane.children.length) {
+      repoPane.replaceChildren();
+      return;
+    }
+    repoPane.replaceChildren(repoPicker({ org: org.org, onAdded: () => open("org.yaml") }));
+  };
+  m.append(el("div", { className: "row", style: "margin-bottom:14px" }, [repos]), repoPane);
+
   const split = el("div", { className: "split" });
   const tree = el("div", { className: "tree" });
   const viewer = el("div", { className: "viewer" });
@@ -222,9 +238,11 @@ export function viewOrg(m) {
          through the question, which is worse than not asking. */
       if (
         isYaml &&
-        !confirm(
-          "Commit " + full(path) + " and push?\n\nEvery staff member picks this up on their next run.",
-        )
+        !(await askYes({
+          title: "Commit " + full(path) + " and push?",
+          hint: "Every staff member picks this up on their next run.",
+          confirm: "Commit and push",
+        }))
       ) {
         return;
       }

package/templates/portal/js/views/prompt.js

@@ -10,7 +10,7 @@
  */
 
 import { getFile, post } from "../api.js";
-import { askText } from "../dialog.js";
+import { askText, askYes } from "../dialog.js";
 import { el, esc, grow, kb, toClipboard } from "../dom.js";
 import { icon } from "../icons.js";
 import { mdlite } from "../md.js";
@@ -375,8 +375,12 @@ export function viewPrompt(m) {
         status.textContent = "nothing changed";
         return;
       }
-      if (!confirm("Commit " + layer.path + " to " + layer.repo + " and push?\n\n" +
-                   "Picked up by " + reach + ".")) return;
+      const yes = await askYes({
+        title: "Commit " + layer.path + " to " + layer.repo + " and push?",
+        hint: "Picked up by " + reach + ".",
+        confirm: "Commit and push",
+      });
+      if (!yes) return;
       save.disabled = cancel.disabled = true;
       status.textContent = "committing…";
       status.className = "meta";

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

@@ -5,11 +5,12 @@
  * spelling a repo name exactly right in a YAML file, which is the kind of thing that fails
  * quietly and reads as the tool being broken. */
 
-import { addRepo, listRepos } from "../api.js";
+import { addRepo, getRepos, listRepos } from "../api.js";
 import { el } from "../dom.js";
 
 /**
- * @param {{org: string, known: string[], onAdded?: () => void}} opts
+ * @param {{org: string, known?: string[], onAdded?: () => void}} opts  without `known`, what
+ *   org.yaml already lists is read off disk, which is how the Org screen uses it long after setup.
  */
 export function repoPicker(opts) {
   const box = el("div", { className: "manual" });
@@ -18,7 +19,8 @@ export function repoPicker(opts) {
     el("p", {
       textContent:
         "Repos marked as products are the ones staff contribute to without owning. A new hire " +
-        "picks them up automatically.",
+        "picks them up automatically; somebody already hired keeps the works_in list in their " +
+        "own staff.yaml.",
     }),
   );
 
@@ -26,10 +28,13 @@ export function repoPicker(opts) {
   box.append(out);
   out.replaceChildren(el("p", { className: "sub", textContent: "Reading your repos…" }));
 
-  listRepos(opts.org)
-    .then((data) => {
+  const known = opts.known
+    ? Promise.resolve(opts.known)
+    : getRepos().then((d) => (d.repos ?? []).map((r) => r.name));
+  Promise.all([listRepos(opts.org), known])
+    .then(([data, listed]) => {
       if (data.error) throw new Error(data.error);
-      const already = new Set(opts.known ?? []);
+      const already = new Set(listed);
       const candidates = (data.repos ?? []).filter((r) => !already.has(r.name));
 
       if (!candidates.length) {
@@ -52,7 +57,7 @@ export function repoPicker(opts) {
           add.disabled = true;
           add.textContent = "Adding…";
           try {
-            await addRepo(repo.name, "product");
+            await addRepo(repo.name, "product", repo.visibility);
             add.textContent = "Added";
             row.classList.add("added");
             opts.onAdded?.();

package/templates/portal/js/views/runonce.js

@@ -5,6 +5,7 @@
  * callers all work together. This starts one, and says how it ended. */
 
 import { runStatus, startRun } from "../api.js";
+import { askYes } from "../dialog.js";
 import { el } from "../dom.js";
 
 /**
@@ -26,7 +27,12 @@ export function runOnce(opts) {
   box.append(el("div", { className: "row" }, [go]), out);
 
   go.onclick = async () => {
-    if (!confirm("Start a daily run for " + opts.name + " now?\n\nIt is a real run, and it costs what one does.")) return;
+    const yes = await askYes({
+      title: "Start a daily run for " + opts.name + " now?",
+      hint: "It is a real run, and it costs what one does.",
+      confirm: "Start the run",
+    });
+    if (!yes) return;
     go.disabled = true;
     const say = (text, cls) => out.replaceChildren(el("p", { className: cls ?? "sub", textContent: text }));
     say("Starting…");

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

@@ -5,8 +5,21 @@
  * is rather than as it was left. Setup cannot be finished in one sitting, so it must survive
  * being abandoned halfway. */
 
-import { checkOrg, createTenant, getAccess, getSetup, joinOrg, planTenant, setAccess } from "../api.js";
-import { $, el, esc, toClipboard } from "../dom.js";
+import {
+  checkOrg,
+  createTenant,
+  fileUrl,
+  getAccess,
+  getOrg,
+  getSetup,
+  joinOrg,
+  planTenant,
+  saveFile,
+  setAccess,
+} from "../api.js";
+import { $, el, esc, grow, toClipboard } from "../dom.js";
+import { go } from "../router.js";
+import { S as App } from "../state.js";
 import { checklist } from "./checklist.js";
 import { credentialPanel } from "./credential.js";
 import { repoPicker } from "./repos.js";
@@ -14,11 +27,87 @@ import { paste } from "./paste.js";
 
 let S = null; // /api/setup/status, refreshed after anything that changes the world
 
+/* 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;
+
+/* 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. */
+const fileSteps = new Map();
+
 export async function viewSetup(main) {
   S = await getSetup();
   render(main);
 }
 
+/**
+ * The same steps once a tenant exists, as their own screen in the portal.
+ *
+ * Setup used to be reachable only before there was a tenant, so the reload that followed
+ * creating one landed on an empty Inbox with the repo picker, the credential and both files
+ * gone. The sidebar offers this while anything is unfinished, and an org nobody has been hired
+ * into opens on it.
+ */
+export async function viewGettingStarted(main) {
+  main.append(el("h1", { textContent: "Getting started" }));
+  const sub = el("p", { className: "sub", textContent: "Reading what is left…" });
+  main.append(sub);
+  S = await getSetup();
+  // Somebody may have clicked elsewhere while GitHub was answering.
+  if (App.view !== "setup") return;
+  sub.textContent =
+    "What is still to do before " + (App.data?.name ?? "this org") + " runs well. Each step " +
+    "reads the world rather than remembering a click, so it is safe to leave and come back.";
+
+  if (!App.data?.staff?.length) {
+    const next = step(1, "Hire your first staff member", false);
+    const hire = el("button", { className: "btn primary", textContent: "Hire someone" });
+    hire.onclick = () => go({ view: "staff" });
+    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.",
+      }),
+      el("div", { className: "row" }, [hire]),
+    );
+    main.append(next);
+  }
+
+  main.append(afterCreate(App.data?.staff?.length ? 1 : 2));
+
+  const health = step(App.data?.staff?.length ? 2 : 3, "What doctor still says", false);
+  healthHost = el("div", { style: "margin-top:12px" });
+  health.append(healthHost);
+  main.append(health);
+  checklist(healthHost, {});
+}
+
+/** Whether the sidebar offers Getting started: while anything is left, or while it is open. */
+export function paintSetupNav() {
+  const nav = $("#setupnav");
+  if (!nav) return;
+  nav.hidden = !App.data?.unfinished?.length && App.view !== "setup";
+}
+
+/* After a save: the checklist and the step list are both derived from disk, so both are asked
+   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, {});
+  try {
+    S = await getSetup();
+    for (const [id, mark] of fileSteps) mark(!(S.tenant.left ?? []).includes(id));
+  } catch {
+    // The saved file is saved either way; a stale tick is not worth an error on top of it.
+  }
+  if (App.data) {
+    const fresh = await getOrg().catch(() => null);
+    if (fresh?.unfinished) App.data.unfinished = fresh.unfinished;
+    paintSetupNav();
+  }
+}
+
 function render(main) {
   /* The sidebar is written by boot() before any of this is known. Once a tenant has been
      adopted, leaving it on "no org yet" contradicts the card directly below it. */
@@ -31,9 +120,9 @@ function render(main) {
     el("p", {
       className: "sub",
       textContent:
-        "Three things here, then what is left: a setting roster tries for you, the repos your " +
-        "staff work in, and the one file only you can write. Nothing is created until you have " +
-        "read the plan.",
+        "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.",
     }),
   );
 
@@ -43,7 +132,7 @@ function render(main) {
 
   /* Drawn whenever a tenant exists, not only in the seconds after creating one. Setup takes
      days: the repo picker and the two manual steps have to still be here tomorrow. */
-  if (S.tenant.found) main.append(afterCreate());
+  if (S.tenant.found) main.append(afterCreate(3));
 }
 
 /* ---------------------------------- 1 · gh ---------------------------------- */
@@ -80,12 +169,14 @@ function stepOrg(main) {
       }),
       el("p", {
         className: "sub",
-        textContent: "Reload the page to leave setup and use the portal.",
+        textContent:
+          "Reload the page to open the portal. Anything below that is still undone stays under " +
+          "Getting started in the sidebar until it is.",
       }),
     );
-    const rows = el("div", { style: "margin-top:12px" });
-    card.append(rows);
-    checklist(rows, {});
+    healthHost = el("div", { style: "margin-top:12px" });
+    card.append(healthHost);
+    checklist(healthHost, {});
     return card;
   }
 
@@ -307,13 +398,14 @@ function stepOrg(main) {
 
 /* ------------------------- 5 · the two GitHub insists on ------------------------- */
 
-function afterCreate() {
-  const card = step(3, "What is left", false);
+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 is the file that decides whether " +
-        "any of this is worth running, and only you can write it.",
+        "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());
@@ -323,22 +415,111 @@ function afterCreate() {
     card.append(repoPicker({ org: S.tenant.org, known: S.tenant.repos ?? [] }));
   }
 
-  const two = el("div", { className: "manual" });
-  two.append(
-    el("b", { textContent: "Answer org/business.md" }),
-    el("p", {
-      textContent:
-        "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.",
-    }),
+  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.",
   );
-  card.append(two);
-
   // The copy-a-prompt loop, which is the whole answer to "how do I write this file".
-  card.append(paste({ kind: "discover", title: "Write it with your own AI" }));
+  business.append(paste({ kind: "discover", title: "Write it with your own AI", onSaved: recheck }));
+  card.append(business);
+
+  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.",
+  );
+  priorities.append(prioritiesEditor());
+  card.append(priorities);
   return card;
 }
 
+/**
+ * One of the files only a person can write, with whether it is written yet.
+ *
+ * Read from the status rather than from the click that saved it, so a file written in an
+ * editor, or by a coding agent, shows as done here too.
+ */
+function fileStep(id, title, why) {
+  const box = el("div", { className: "manual" });
+  const tag = el("span", { className: "meta" });
+  const mark = (done) => {
+    tag.textContent = done ? "Written." : "Still the stub it shipped as.";
+    box.classList[done ? "add" : "remove"]("done");
+  };
+  mark(!(S.tenant.left ?? []).includes(id));
+  fileSteps.set(id, mark);
+  box.append(el("div", {}, [el("b", { textContent: title }), tag]), el("p", { textContent: why }));
+  return box;
+}
+
+/**
+ * org/priorities.md, edited in place.
+ *
+ * There is no brief for it, and it does not want one: business.md needs an interview because
+ * nobody can write it off the top of their head, while a ranked list of three things is
+ * quicker to type than to explain to a model. So the file opens as it is on disk, stub and
+ * all, and saving it is the same commit-and-push as every other editor here.
+ */
+function prioritiesEditor() {
+  const box = el("div", { style: "margin-top:9px" });
+  const path = opsName() + "/org/priorities.md";
+  const ta = el("textarea", { className: "pastebox" });
+  ta.rows = 12;
+  const save = el("button", { className: "btn primary", textContent: "Save and commit" });
+  const out = el("div");
+  box.append(ta, el("div", { className: "row", style: "margin-top:9px" }, [save]), out);
+
+  let before = "";
+  save.disabled = true;
+  // Not getFile: an absent file answers 404 with a message, and that is not what to edit.
+  fetch(fileUrl(path), { cache: "no-store" })
+    .then((r) => (r.ok ? r.text() : ""))
+    .then((text) => {
+      before = text;
+      ta.value = text;
+      grow(ta);
+      save.disabled = false;
+    })
+    .catch((err) => out.replaceChildren(el("p", { className: "err", textContent: String(err.message || err) })));
+  ta.addEventListener("input", () => grow(ta));
+
+  save.onclick = async () => {
+    if (ta.value.trim() === before.trim()) {
+      out.replaceChildren(el("p", { className: "sub", textContent: "Nothing changed yet." }));
+      return;
+    }
+    save.disabled = true;
+    save.textContent = "Saving…";
+    try {
+      const r = await saveFile(path, ta.value, "portal: write org/priorities.md");
+      before = ta.value;
+      out.replaceChildren(
+        el("p", {
+          className: r.pushed ? "sub" : "err",
+          textContent: r.pushed
+            ? "Committed and pushed. Every daily run reads it from the next one."
+            : "Committed, but the push failed: " + (r.note ?? ""),
+        }),
+      );
+      recheck();
+    } catch (err) {
+      out.replaceChildren(el("p", { className: "err", textContent: String(err.message || err) }));
+    } finally {
+      save.disabled = false;
+      save.textContent = "Save and commit";
+    }
+  };
+  return box;
+}
+
+/** The ops repo's directory name, which is what every workspace-relative path starts with. */
+function opsName() {
+  return App.data?.opsName ?? String(S.tenant.opsDir ?? "roster-ops").split("/").pop();
+}
+
 /**
  * The ops repo's Actions access. Read on arrival, so a page reloaded after it was set says it
  * is done without anybody pressing anything; the button asks the server to set it, and a

package/templates/portal/js/views/staff.js

@@ -10,6 +10,7 @@
  */
 
 import { post } from "../api.js";
+import { askYes } from "../dialog.js";
 import { ago, el, esc } from "../dom.js";
 import { icon } from "../icons.js";
 import { refreshAll } from "../refresh.js";
@@ -117,16 +118,21 @@ export function viewStaff(m) {
   /* ------------------------------- hiring -------------------------------- */
 
   function hireForm(host) {
+    /* App names are copied from whoever is already here. The first hire has nobody to copy
+       from, and the CLI asks for --app and --public-app at that point; these are those two. */
+    const first = !S.data.staff.length;
     const box = el("div", { className: "card" });
     box.append(
       el("h3", { textContent: "Hire someone" }),
       el("p", {
         className: "sub",
         style: "margin-bottom:14px",
-        textContent:
-          "Only the handle is required. Everything else is copied from whoever is already " +
-          "here, because app slugs carry a house naming scheme and the public identity is " +
-          "genuinely shared.",
+        textContent: first
+          ? "Only the handle is required. This is the first hire, so there is nobody to copy " +
+            "App names from: name them here, and later hires follow the pattern."
+          : "Only the handle is required. Everything else is copied from whoever is already " +
+            "here, because app slugs carry a house naming scheme and the public identity is " +
+            "genuinely shared.",
       }),
     );
 
@@ -134,7 +140,17 @@ export function viewStaff(m) {
     const name = field("name", "Chief Financial Officer", "defaults to the handle, uppercased");
     const dir = field("dir", "finance", "directory and repo name; defaults to the handle");
     const schedule = scheduleField();
-    for (const f of [handle, name, dir, schedule]) box.append(f.row);
+    const fields = [handle, name, dir, schedule];
+    const apps = [];
+    if (first) {
+      const org = S.data.org;
+      apps.push(
+        ["app", field("app", org + "-cfo", "this staff member's GitHub App. Names are unique across GitHub, so prefix it")],
+        ["publicApp", field("public app", org + "-robot", "the shared identity for public product repos. Optional when they are all private")],
+      );
+      fields.push(...apps.map(([, f]) => f));
+    }
+    for (const f of fields) box.append(f.row);
 
     const status = el("span", { className: "meta" });
     const plan = el("button", { className: "ghbtn primary", textContent: "Show the plan" });
@@ -156,7 +172,7 @@ export function viewStaff(m) {
       status.className = "meta";
       out.replaceChildren();
       const params = new URLSearchParams({ handle: handle.input.value.trim() });
-      for (const [key, f] of [["name", name], ["dir", dir], ["schedule", schedule]]) {
+      for (const [key, f] of [["name", name], ["dir", dir], ["schedule", schedule], ...apps]) {
         const value = (f.value ? f.value() : f.input.value).trim();
         if (value) params.set(key, value);
       }
@@ -211,7 +227,7 @@ export function viewStaff(m) {
       line("todo", "Write the charter"),
       line("todo", "Run once now, or roster run " + s.handle + " --apply: the run that proves the wiring"),
     );
-    for (const w of plan.warnings ?? []) box.append(line("warn", w));
+    for (const w of plan.warnings ?? []) box.append(line("warn", S.data.staff.length ? w : portalWords(w)));
 
     const status = el("span", { className: "meta" });
     const go = el("button", { className: "ghbtn primary", textContent: "Hire " + s.handle });
@@ -222,7 +238,7 @@ export function viewStaff(m) {
           handle: s.handle,
           flags: Object.fromEntries(params),
         },
-        "Create " + s.brain + " and wire it up?\n\nThis creates a repository on GitHub.",
+        { title: "Create " + s.brain + " and wire it up?", hint: "This creates a repository on GitHub.", confirm: "Hire " + s.handle },
         go,
         status,
         box,
@@ -277,7 +293,7 @@ export function viewStaff(m) {
     go.onclick = () =>
       apply(
         { action: "retire", handle: plan.handle },
-        "Retire " + plan.name + "?\n\n" + (plan.brain ?? plan.dir) + " is not touched.",
+        { title: "Retire " + plan.name + "?", hint: (plan.brain ?? plan.dir) + " is not touched.", confirm: "Retire " + plan.handle },
         go,
         status,
         box,
@@ -289,7 +305,7 @@ export function viewStaff(m) {
   /* -------------------------------- apply -------------------------------- */
 
   async function apply(payload, ask, btn, status, box) {
-    if (!confirm(ask)) return;
+    if (!(await askYes(ask))) return;
     btn.disabled = true;
     status.textContent = "working…";
     status.className = "meta";
@@ -308,6 +324,14 @@ export function viewStaff(m) {
   }
 }
 
+/* The plan's warnings are the CLI's, and name its flags. Here the same two options are fields
+   on the form above, and a flag the page has no box for reads as a dead end. */
+function portalWords(warning) {
+  return warning
+    .replace(/pass --public-app\b/, "fill in public app above")
+    .replace(/pass --app\b/, "fill in app above");
+}
+
 function field(label, placeholder, hint) {
   const input = el("input", { type: "search", placeholder, value: "", style: "width:100%" });
   input.dataset.field = label;