@nanocollective/roster 0.1.0-alpha.5 → 0.1.0-alpha.50

package/templates/portal/js/homesort.js

@@ -0,0 +1,174 @@
+/* Where every issue and pull request goes on Home.
+ *
+ * Every open item lands in exactly one place, so nothing is missed and nothing shows twice:
+ *
+ *   needs      an ask on a person, or a pull request ready to merge
+ *   requests   something a person asked a staff member for
+ *   staff      a staff member's own work: their status issue, a peer's ask, their own issues
+ *   elsewhere  draft pull requests, and product or ops issues nobody has put on a person
+ *
+ * `unread` is not a place: it lists what in `staff` and `elsewhere` has activity you have not
+ * seen (from your GitHub notifications), since those two are otherwise off Home. Items in the
+ * other places carry their own unread mark.
+ *
+ * Closed items only matter when a staff member closed them today: that is "Closed today", with
+ * Reopen beside each, because staff now close things without asking. */
+
+/** The kinds an ask on a person carries. Older trackers used other words for a chore. */
+const KINDS = ["decision", "review", "chore"];
+const CHORE_WORDS = ["setup", "submit", "data", "blocked"];
+
+const lower = (s) => String(s ?? "").toLowerCase();
+
+/** How old a run report can be and still be this morning's. */
+const REPORT_HOURS = 20;
+
+/** A run report as lines, without the @mention it opens with. */
+function reportLines(body) {
+  return String(body ?? "")
+    .split("\n")
+    .map((l) => l.replace(/^\s*(@[\w-]+\s*)+/, "").replace(/^[-*]\s+/, "").trim())
+    .filter(Boolean)
+    .slice(0, 5);
+}
+
+/**
+ * @param items   the inbox list: open and recently closed issues and pull requests
+ * @param staff   S.data.staff: handle, name, brain, statusIssue, mention
+ * @param humans  [{ github, marker }]
+ * @param live    /api/live's staff list, or [] before it has answered
+ * @param now     for "today", in the viewer's own day
+ */
+export function sortHome(items, staff, humans, live = [], now = new Date()) {
+  const people = new Set(humans.map((h) => lower(h.github)).filter(Boolean));
+  const markers = new Set(humans.map((h) => lower(h.marker)).filter(Boolean));
+  const byBrain = new Map(staff.filter((s) => s.brain).map((s) => [s.brain, s]));
+  const working = new Set();
+  for (const l of live) {
+    const s = staff.find((x) => x.handle === l.handle);
+    for (const r of l.running ?? []) if (s && r.issue) working.add(`${s.brain}#${r.issue}`);
+  }
+
+  const out = {
+    reports: [],
+    needs: [],
+    requests: [],
+    staff: [],
+    elsewhere: [],
+    unread: [],
+    closedToday: [],
+  };
+  const today = dayOf(now);
+
+  for (const item of items) {
+    const owner = byBrain.get(item.repo) ?? null;
+
+    if (item.state !== "OPEN") {
+      if (
+        owner &&
+        item.kind === "issue" &&
+        item.closedAt &&
+        dayOf(new Date(item.closedAt)) === today &&
+        !people.has(lower(item.closedBy))
+      ) {
+        out.closedToday.push({ item, staff: owner, reason: reasonOf(item, people) });
+      }
+      continue;
+    }
+
+    // The run report: the last word on a status issue, from the staff member, in the last day.
+    const c = item.lastComment;
+    if (
+      owner &&
+      item.number === owner.statusIssue &&
+      c &&
+      !people.has(lower(c.author)) &&
+      now - new Date(c.createdAt) < REPORT_HOURS * 3_600_000
+    ) {
+      out.reports.push({ staff: owner, item, at: c.createdAt, lines: reportLines(c.body) });
+    }
+
+    const place = placeOf(item, owner, people, markers);
+    const entry = { item, staff: owner, ...place };
+    if (place.place === "requests") {
+      entry.status = working.has(`${item.repo}#${item.number}`)
+        ? "working"
+        : item.lastComment && !people.has(lower(item.lastComment.author))
+          ? "answered"
+          : "waiting";
+    }
+    out[place.place].push(entry);
+  }
+
+  const oldest = (a, b) => a.item.createdAt.localeCompare(b.item.createdAt);
+  out.needs.sort(oldest);
+  out.requests.sort((a, b) => b.item.updatedAt.localeCompare(a.item.updatedAt));
+  out.closedToday.sort((a, b) => b.item.closedAt.localeCompare(a.item.closedAt));
+  out.unread = [...out.staff, ...out.elsewhere]
+    .filter((e) => e.item.unread)
+    .sort((a, b) => b.item.updatedAt.localeCompare(a.item.updatedAt));
+  return out;
+}
+
+/** Which place an open item belongs in, and for an ask, which kind it is. */
+export function placeOf(item, owner, people, markers) {
+  if (item.kind === "pr") {
+    return item.draft ? { place: "elsewhere", why: "draft" } : { place: "needs", kind: "merge" };
+  }
+
+  const labels = (item.labels ?? []).map(lower);
+  const onPerson =
+    (item.assignees ?? []).some((a) => people.has(lower(a))) ||
+    labels.some((l) => markers.has(l));
+  const byPerson = people.has(lower(item.author));
+  /* You had the last word on an ask: approved it, answered it, said go with the default. It is
+     waiting on them now, so it is one of your requests until they reply or close it. If they
+     reply, the last word is theirs and it is back on you. */
+  const youAnswered = Boolean(item.lastComment) && people.has(lower(item.lastComment.author));
+
+  if (!owner) {
+    if (!onPerson || byPerson) {
+      return { place: "elsewhere", why: item.role === "product" ? "contributor" : "other" };
+    }
+    return youAnswered ? { place: "requests" } : { place: "needs", kind: kindOf(labels) };
+  }
+  if (item.number === owner.statusIssue || labels.includes("keep-open")) {
+    return { place: "staff", why: "status" };
+  }
+  if (byPerson) return { place: "requests" };
+  if (onPerson) return youAnswered ? { place: "requests" } : { place: "needs", kind: kindOf(labels) };
+  return {
+    place: "staff",
+    why: labels.some((l) => l.startsWith("from-")) ? "peer" : "own",
+  };
+}
+
+function kindOf(labels) {
+  const found = KINDS.find((k) => labels.includes(k));
+  if (found) return found;
+  return labels.some((l) => CHORE_WORDS.includes(l)) ? "chore" : "ask";
+}
+
+/** The one line a staff member closed it with: their last comment's first line. */
+function reasonOf(item, people) {
+  const c = item.lastComment;
+  if (!c || people.has(lower(c.author))) return "";
+  const line = String(c.body ?? "")
+    .split("\n")
+    .map((l) => l.trim())
+    .find(Boolean);
+  return line ? line.replace(/^[#>*\s-]+/, "").slice(0, 160) : "";
+}
+
+/** A date as the viewer's own calendar day. */
+export function dayOf(d) {
+  return `${d.getFullYear()}-${d.getMonth() + 1}-${d.getDate()}`;
+}
+
+/** Whole days from today to a YYYY-MM-DD date: 0 today, negative once it has passed. */
+export function daysUntil(date, now = new Date()) {
+  const [y, m, d] = String(date).split("-").map(Number);
+  const due = new Date(y, m - 1, d);
+  const start = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  return Math.round((due - start) / 86_400_000);
+}

package/templates/portal/js/icons.js

@@ -13,6 +13,26 @@
  */
 
 const PATHS = {
+  "code":
+    "<polyline points=\"16 18 22 12 16 6\" /> <polyline points=\"8 6 2 12 8 18\" />",
+  "megaphone":
+    "<path d=\"m3 11 18-5v12L3 14v-3z\" /> <path d=\"M11.6 16.8a3 3 0 1 1-5.8-1.6\" />",
+  "life-buoy":
+    "<circle cx=\"12\" cy=\"12\" r=\"10\" /> <path d=\"m4.93 4.93 4.24 4.24\" /> <path d=\"m14.83 9.17 4.24-4.24\" /> <path d=\"m14.83 14.83 4.24 4.24\" /> <path d=\"m9.17 14.83-4.24 4.24\" /> <circle cx=\"12\" cy=\"12\" r=\"4\" />",
+  "compass":
+    "<circle cx=\"12\" cy=\"12\" r=\"10\" /> <polygon points=\"16.24 7.76 14.12 14.12 7.76 16.24 9.88 9.88 16.24 7.76\" />",
+  "brush":
+    "<path d=\"m9.06 11.9 8.07-8.06a2.85 2.85 0 1 1 4.03 4.03l-8.06 8.08\" /> <path d=\"M7.07 14.94c-1.66 0-3 1.35-3 3.02 0 1.33-2.5 1.52-2 2.02 1.08 1.1 2.49 2.02 4 2.02 2.2 0 4-1.8 4-4.04a3.01 3.01 0 0 0-3-3.02z\" />",
+  "bug":
+    "<path d=\"m8 2 1.88 1.88\" /> <path d=\"M14.12 3.88 16 2\" /> <path d=\"M9 7.13v-1a3.003 3.003 0 1 1 6 0v1\" /> <path d=\"M12 20c-3.3 0-6-2.7-6-6v-3a4 4 0 0 1 4-4h4a4 4 0 0 1 4 4v3c0 3.3-2.7 6-6 6\" /> <path d=\"M12 20v-9\" /> <path d=\"M6.53 9C4.6 8.8 3 7.1 3 5\" /> <path d=\"M6 13H2\" /> <path d=\"M3 21c0-2.1 1.7-3.9 3.8-4\" /> <path d=\"M20.97 5c0 2.1-1.6 3.8-3.5 4\" /> <path d=\"M22 13h-4\" /> <path d=\"M17.2 17c2.1.1 3.8 1.9 3.8 4\" />",
+  "server":
+    "<rect width=\"20\" height=\"8\" x=\"2\" y=\"2\" rx=\"2\" ry=\"2\" /> <rect width=\"20\" height=\"8\" x=\"2\" y=\"14\" rx=\"2\" ry=\"2\" /> <line x1=\"6\" x2=\"6.01\" y1=\"6\" y2=\"6\" /> <line x1=\"6\" x2=\"6.01\" y1=\"18\" y2=\"18\" />",
+  "book-open":
+    "<path d=\"M2 3h6a4 4 0 0 1 4 4v14a3 3 0 0 0-3-3H2z\" /> <path d=\"M22 3h-6a4 4 0 0 0-4 4v14a3 3 0 0 1 3-3h7z\" />",
+  "bar-chart":
+    "<line x1=\"12\" x2=\"12\" y1=\"20\" y2=\"10\" /> <line x1=\"18\" x2=\"18\" y1=\"20\" y2=\"4\" /> <line x1=\"6\" x2=\"6\" y1=\"20\" y2=\"16\" />",
+  "users":
+    "<path d=\"M16 21v-2a4 4 0 0 0-4-4H6a4 4 0 0 0-4 4v2\" /> <circle cx=\"9\" cy=\"7\" r=\"4\" /> <path d=\"M22 21v-2a4 4 0 0 0-3-3.87\" /> <path d=\"M16 3.13a4 4 0 0 1 0 7.75\" />",
   "check":
     "<path d=\"M20 6 9 17l-5-5\" />",
   "chevron":
@@ -96,6 +116,23 @@ export function icon(name, cls = "") {
   return span.firstChild ?? span;
 }
 
+/* A staff member's icon: `icon:` in their staff.yaml, or one picked from their role. */
+const ROLE_ICONS = {
+  cto: "code",
+  cmo: "megaphone",
+  support: "life-buoy",
+  pm: "compass",
+  designer: "brush",
+  qa: "bug",
+  devops: "server",
+  writer: "book-open",
+  analyst: "bar-chart",
+  community: "users",
+};
+export function staffIcon(s) {
+  return s?.icon && hasIcon(s.icon) ? s.icon : (ROLE_ICONS[s?.handle] ?? "person");
+}
+
 export function hasIcon(name) {
   return Object.hasOwn(PATHS, name);
 }

package/templates/portal/js/inflight.js

@@ -0,0 +1,18 @@
+/* How many requests the page has open. The setup dialog waits for this to reach zero before it
+ * shows itself, because the list it draws is only final once every answer is back. */
+
+let open = 0;
+
+if (typeof globalThis.fetch === "function" && !globalThis.fetch.counted) {
+  const real = globalThis.fetch.bind(globalThis);
+  const counted = (...args) => {
+    open++;
+    return real(...args).finally(() => {
+      open--;
+    });
+  };
+  counted.counted = true;
+  globalThis.fetch = counted;
+}
+
+export const pending = () => open;

package/templates/portal/js/md.js

@@ -361,7 +361,9 @@ function mdAsset(src, opts) {
   return path ? "/api/file?path=" + encodeURIComponent(opts.file.staffDir + "/" + path) : src;
 }
 
-const REF_RE = /(^|[\s(>])([\w.-]+\/[\w.-]+)?#(\d+)\b/g;
+/* #123, repo#123 and owner/repo#123. The short repo form is how the staff write about the other
+   repos in their own org (pip-web#172), and it was left as plain text. */
+const REF_RE = /(^|[\s(>])((?:[\w.-]+\/)?[\w.-]+)?#(\d+)\b/g;
 // GitHub's own username shape, plus the short aliases the agents answer to.
 const AT_RE = /(^|[\s(>])@([a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38})\b/gi;
 
@@ -381,7 +383,8 @@ export function chips(html, opts = {}) {
       if (inA) return p;
       return p
         .replace(REF_RE, (m, pre, repo, n) => {
-          const target = repo || opts.repo;
+          const owner = String(opts.repo ?? "").split("/")[0];
+          const target = !repo ? opts.repo : repo.includes("/") ? repo : owner ? owner + "/" + repo : "";
           if (!target) return m;
           // /issues/N redirects to /pull/N when it is a PR, so one form is always right.
           return pre + '<a class="ref" href="https://github.com/' + target + "/issues/" + n +

package/templates/portal/js/mdedit.js

@@ -0,0 +1,84 @@
+/* Colour behind a textarea, for the files people edit here.
+ *
+ * The textarea stays the thing you type into, so undo, selection, spellcheck and ⌘S all work
+ * as they always did. Its text is made transparent and a <pre> with the same box sits behind
+ * it, redrawn on every keystroke. The editors grow to fit rather than scroll, which is what
+ * keeps the two lined up without syncing a scroll position.
+ *
+ * Markdown here is a per-line tokeniser, like yaml.js: enough to read by, and anything it does
+ * not recognise is plain text rather than an error.
+ */
+
+import { el, esc } from "./dom.js";
+import { yamlHTML } from "./yaml.js";
+
+/**
+ * Wrap a textarea so its contents are highlighted. Returns the wrapper, which is what goes on
+ * the page in place of the textarea.
+ * @param {"md"|"yaml"} lang
+ */
+export function highlighted(ta, lang = "md") {
+  const wrap = el("div", { className: "hled" });
+  const back = el("pre", { className: "hlback" });
+  back.setAttribute?.("aria-hidden", "true");
+  ta.classList?.add("hlfront");
+  wrap.append(back, ta);
+  /* The colours only line up if both boxes set text identically, and the textarea's box comes
+     from whichever class it already had, so it is read rather than restated in CSS. */
+  const match = () => {
+    if (typeof getComputedStyle !== "function" || !ta.isConnected) return;
+    const cs = getComputedStyle(ta);
+    for (const k of ["font", "lineHeight", "letterSpacing", "tabSize", "padding", "borderWidth", "borderStyle", "borderRadius"]) {
+      back.style[k] = cs[k];
+    }
+  };
+  const paint = () => {
+    match();
+    // A trailing newline in a textarea is a line; in a <pre> it is not, without something after it.
+    back.innerHTML = (lang === "yaml" ? yamlHTML(ta.value) : markdownHTML(ta.value)) + "\n ";
+  };
+  ta.addEventListener("input", paint);
+  paint();
+  // Setting .value from code fires no input event, so the owner can ask for a repaint.
+  wrap.repaint = paint;
+  return wrap;
+}
+
+/** Escaped, highlighted HTML for markdown source. */
+export function markdownHTML(text) {
+  let fenced = false;
+  return String(text ?? "")
+    .split("\n")
+    .map((line) => {
+      if (/^\s*(```|~~~)/.test(line)) {
+        fenced = !fenced;
+        return span("mdfence", line);
+      }
+      if (fenced) return span("mdcode", line);
+      if (/^#{1,6}\s/.test(line)) return span("mdh", line);
+      if (/^\s*>/.test(line)) return span("mdq", line);
+      if (/^\s*([-*_])(\s*\1){2,}\s*$/.test(line)) return span("mdfence", line);
+      const list = /^(\s*)([-*+]|\d+[.)])(\s+)(.*)$/.exec(line);
+      if (list) return esc(list[1]) + span("mdl", list[2]) + esc(list[3]) + inline(list[4]);
+      return inline(line);
+    })
+    .join("\n");
+}
+
+const span = (cls, text) => '<span class="' + cls + '">' + esc(text) + "</span>";
+
+/** Inline marks, on one line. Code spans first, so nothing inside one is read as markup. */
+function inline(line) {
+  return line
+    .split(/(`[^`]+`)/)
+    .map((part, i) => (i % 2 ? span("mdc", part) : marks(part)))
+    .join("");
+}
+
+function marks(text) {
+  return esc(text)
+    .replace(/\{\{[^}]*\}\}/g, (m) => '<span class="mdt">' + m + "</span>")
+    .replace(/(\*\*|__)(?=\S)(.+?)(?<=\S)\1/g, '<span class="mdb">$1$2$1</span>')
+    .replace(/(^|[^*\w])([*_])(?=\S)([^*_]+?)(?<=\S)\2(?![*\w])/g, '$1<span class="mdi">$2$3$2</span>')
+    .replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, '<span class="mdk">[$1]</span><span class="mdu">($2)</span>');
+}

package/templates/portal/js/readiness.js

@@ -0,0 +1,70 @@
+/* Whether each staff member can actually run yet.
+ *
+ * A hire that had its App created but not installed, and no credential, looked finished: the
+ * card said so and Getting started went away. This is the one answer every screen asks. */
+
+import { getStaffProgress } from "./api.js";
+import { S } from "./state.js";
+
+/** What is left for one staff member, as short instructions. Empty when they are ready. */
+export async function whatsLeft(s, fresh = false) {
+  const left = [];
+  if (s.rig?.charterStub) left.push("write the charter");
+  const p = await getStaffProgress(s.handle, fresh).catch(() => ({}));
+  if (p.installed === false) left.push(p.app ? "install the GitHub App" : "create the GitHub App");
+  if (p.credential === false) left.push("add the agent credential");
+  if (p.ran === false) left.push("run once");
+  S.readiness = { ...(S.readiness ?? {}), [s.handle]: left };
+  return left;
+}
+
+/** Every staff member's, then `then` once all have answered. */
+export function checkAll(then) {
+  return Promise.all((S.data?.staff ?? []).map((s) => whatsLeft(s))).then(() => then?.());
+}
+
+/** The staff with anything left, from what has been checked so far. */
+export function notReady() {
+  return (S.data?.staff ?? []).filter((s) => (S.readiness?.[s.handle] ?? []).length);
+}
+
+/** "install the GitHub App, add the agent credential and run once" */
+export function sentence(left) {
+  if (left.length < 2) return left.join("");
+  return left.slice(0, -1).join(", ") + " and " + left.at(-1);
+}
+
+/** Per staff member: hire, the GitHub App, the charter, the agent credential, a first run. */
+const STAFF_STEPS = 5;
+
+/**
+ * Setup as a count, from the same answers as everything above: the org's three steps (create
+ * it, business.md, priorities.md), then five per staff member. With nobody hired, the first
+ * hire's five are counted as still to do.
+ *
+ * Null until every staff member's readiness has answered. A count that starts high and drops
+ * when GitHub replies reads as steps coming undone.
+ */
+export function progress(
+  unfinished = S.data?.unfinished ?? [],
+  staff = S.data?.staff ?? [],
+  readiness = S.readiness ?? {},
+) {
+  const orgSteps = 3;
+  let done = orgSteps - unfinished.filter((id) => id !== "hire").length;
+  let total = orgSteps;
+  if (!staff.length) return { done, total: total + STAFF_STEPS };
+  for (const s of staff) {
+    const left = readiness[s.handle];
+    if (!left) return null;
+    total += STAFF_STEPS;
+    done += STAFF_STEPS - left.length;
+  }
+  return { done, total };
+}
+
+/** One staff member's own count, or null before their readiness is known. */
+export function staffProgress(handle, readiness = S.readiness ?? {}) {
+  const left = readiness[handle];
+  return left ? { done: STAFF_STEPS - left.length, total: STAFF_STEPS } : null;
+}

package/templates/portal/js/refresh.js

@@ -10,7 +10,8 @@
 import { getInbox, getOrg, getSync } from "./api.js";
 import { $, ago, el, esc } from "./dom.js";
 import { render } from "./router.js";
-import { openCount, openPrCount, S } from "./state.js";
+import { sortHome } from "./homesort.js";
+import { humansOf, openCount, S, unreadCount } from "./state.js";
 
 /**
  * The inbox, fetched at most once at a time.
@@ -53,8 +54,9 @@ export function ensureInbox(force) {
 export function stampCounts() {
   const waiting = !S.inbox;
   for (const [sel, n] of [
+    ["#homecount", needsCount],
     ["#inboxcount", openCount],
-    ["#prcount", openPrCount],
+    ["#unreadcount", unreadCount],
   ]) {
     const slot = document.querySelector(sel);
     if (!slot) continue;
@@ -70,6 +72,12 @@ export function stampCounts() {
  * which in practice meant "after you visit the Inbox". A sidebar that says nothing until you
  * look at it is not a sidebar.
  */
+/** What Home's "Needs you" holds, for the sidebar. */
+function needsCount() {
+  if (!S.inbox || !S.data) return 0;
+  return sortHome(S.inbox.items ?? [], S.data.staff, humansOf(), S.live?.staff ?? []).needs.length;
+}
+
 export function countInBackground() {
   stampCounts();
   return ensureInbox(false)

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", "org", "staff", "docs"]);
+export const ORG_WIDE = new Set(["setup", "home", "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"]);
@@ -32,13 +32,19 @@ export const S = {
   data: null,
   docs: null,
   inbox: null,
+  /** /api/runs. Kept once read: it is minutes of downloads on a cold cache. */
+  runs: null,
   sync: null,
   loadedAt: null,
+  /** The role whose hire list is open on the Staff screen, kept across a refresh. */
+  staffOpen: null,
+  /** Per staff member, what is left before they can run. See readiness.js. */
+  readiness: null,
 
   staffHandle: null,
   /* What is waiting on you, not whose brain you read last. The org-wide screens are where a
      session starts, which is also why the Staff list below them opens folded. */
-  view: "inbox",
+  view: "home",
   /** The inbox filter box. Brain and "what changed" keep their own, below. */
   query: "",
 
@@ -80,9 +86,9 @@ export const S = {
 export const openCount = () =>
   (S.inbox?.items ?? []).filter((i) => i.state === "OPEN" && i.kind !== "pr").length;
 
-/** The same, for the screen that is only pull requests. */
-export const openPrCount = () =>
-  (S.inbox?.items ?? []).filter((i) => i.state === "OPEN" && i.kind === "pr").length;
+/** Issues with activity you have not read, from GitHub's notifications. */
+export const unreadCount = () =>
+  (S.inbox?.items ?? []).filter((i) => i.unread && i.state === "OPEN" && i.kind !== "pr").length;
 
 export const staff = () => S.data.staff.find((s) => s.handle === S.staffHandle) ?? S.data.staff[0];
 

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

@@ -6,8 +6,8 @@
  * it is one browser, one origin, and nothing extra to explain.
  *
  * What it still cannot do is install the App. Installing is a grant of access to specific
- * repositories and GitHub asks a human to choose them, which is correct behaviour and should not
- * be worked around. */
+ * repositories and GitHub asks a human to confirm them, which is correct behaviour and should not
+ * be worked around. The link it hands back has the right repos already selected. */
 
 import { appResult, startApp } from "../api.js";
 import { el } from "../dom.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.",
     }),
   );
 
@@ -48,6 +47,11 @@ export function appPanel(opts) {
          it: an App that exists is not a problem, it is a step you have already done. */
       const note = el("div");
       note.append(el("p", { className: "err", textContent: String(err.message || err) }));
+      if (err.data?.install) {
+        note.append(
+          el("a", { className: "btn", href: err.data.install, target: "_blank", textContent: "Install it" }),
+        );
+      }
       out.replaceChildren(note);
       return;
     }
@@ -102,9 +106,21 @@ export function appPanel(opts) {
         el("p", {
           className: "sub",
           textContent:
-            "Grant it every tracker this staff member writes to, not just their own: the token " +
-            "is minted organisation-wide and a peer's board is where a brief lands.",
+            "The link opens GitHub's install page with the org and the repos already selected: " +
+            "this staff member's brain, every peer tracker it writes to, and the product repos. " +
+            "Check the list and confirm.",
         }),
+        ...((result.preselected ?? []).length
+          ? [el("p", { className: "sub", textContent: "Selected: " + result.preselected.join(", ") })]
+          : []),
+        ...((result.missing ?? []).length
+          ? [
+              el("p", {
+                className: "err",
+                textContent: "Tick these yourself, their ids could not be read: " + result.missing.join(", "),
+              }),
+            ]
+          : []),
         el("a", {
           className: "btn primary",
           href: result.install,
@@ -115,7 +131,8 @@ export function appPanel(opts) {
           className: "sub",
           textContent:
             "Do not verify this by reading the API. It reports what an App declares separately " +
-            "from what an installation was granted. Only a run that finished proves the chain.",
+            "from what an installation was granted. Only a run that finished proves the chain, " +
+            "which is what Run once now on the staff card is for.",
         }),
       );
       out.replaceChildren(done);

package/templates/portal/js/views/brain.js

@@ -150,7 +150,7 @@ export function viewBrain(m) {
     const fileHits = plain.filter((f) => !q || f.path.toLowerCase().includes(q));
 
     /* ---- memory ---- */
-    const mem = group("Memory", s.facts.length + " facts");
+    const mem = group("What they know", s.facts.length + " facts");
     if (q) {
       for (const f of hits.slice(0, 200)) mem.append(row("fact:" + f.slug, f.slug, "", "tmem"));
       if (!hits.length) {

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.",
       }),
     );
   }