@nanocollective/roster 0.1.0-alpha.43 → 0.1.0-alpha.45

package/dist/cli.js

@@ -337,7 +337,8 @@ function tokensFor(org, s) {
     APP: s.app,
     PUBLIC_APP: s.publicApp,
     PUBLIC_TOKEN_ENV: s.publicTokenEnv,
-    AGENT_SECRET: s.agentSecret
+    AGENT_SECRET: s.agentSecret,
+    MAX_RUNS: String(s.maxRunsPerDay)
   };
 }
 function render(text, tokens, where = "template") {
@@ -426,7 +427,9 @@ function specFromManifest(m, dir) {
     app: String(priv.app ?? ""),
     publicApp: String(pub.app ?? ""),
     publicTokenEnv: String(m.public_token_env ?? "PUBLIC_TOKEN"),
-    agentSecret: String(m.agent_secret ?? "CLAUDE_CODE_OAUTH_TOKEN")
+    agentSecret: String(m.agent_secret ?? "CLAUDE_CODE_OAUTH_TOKEN"),
+    // Peer and follow-on runs a day. Mentions are a person asking and never count.
+    maxRunsPerDay: Number(m.max_runs_per_day ?? 6)
   };
 }
 
@@ -1471,6 +1474,14 @@ import { execFileSync as execFileSync3 } from "child_process";
 import { existsSync as existsSync12, mkdirSync as mkdirSync2, readFileSync as readFileSync11, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname5, join as join13 } from "path";
 
+// src/lib/asks.ts
+var ASK_KINDS = ["decision", "review", "chore"];
+var KEEP_OPEN = "keep-open";
+var OWNED_LABELS = [...ASK_KINDS, KEEP_OPEN];
+function askKinds(labels) {
+  return labels.filter((l) => ASK_KINDS.includes(l));
+}
+
 // src/lib/commit.ts
 import { execFileSync as execFileSync2 } from "child_process";
 function commitAndPush(repoDir, paths, message) {
@@ -1757,7 +1768,8 @@ function buildPlan(ws, org, handle, opts, parseYaml) {
     app: app ?? `${handle}`,
     publicApp: publicApp || `${org.org}-robot`,
     publicTokenEnv: String(sample?.public_token_env ?? "PUBLIC_TOKEN"),
-    agentSecret: opts.agentSecret ?? agentTokenEnv(org)
+    agentSecret: opts.agentSecret ?? agentTokenEnv(org),
+    maxRunsPerDay: Number(org.defaults?.max_runs_per_day ?? 6)
   };
   if (!opts.name) warnings.push(`no --name given, so the role is called "${staff.name}"`);
   if (staff.worksIn.length) {
@@ -1799,8 +1811,8 @@ function buildPlan(ws, org, handle, opts, parseYaml) {
     .../* @__PURE__ */ new Set([
       orgSpec2.humanMarker,
       handle,
-      "decision",
-      "setup",
+      ...ASK_KINDS,
+      "keep-open",
       "build",
       "blocked",
       ...peers.map((p) => `from-${p.handle}`)
@@ -2062,7 +2074,10 @@ async function applyPlan(ws, plan2, opts) {
     "-f",
     "title=\u{1F4CD} Where we are (living status - always current)",
     "-f",
-    `body=${statusBody(staff)}`
+    `body=${statusBody(staff)}`,
+    // A sweep closes anything with nothing left to do on it. This one never runs out.
+    "-f",
+    "labels[]=keep-open"
   ]);
   if (issue.ok && issue.data?.number) {
     await ghJson([
@@ -3707,7 +3722,8 @@ async function checkStaff(ws, org, entry, composer, online) {
     });
   }
   if (online && manifest.brain) {
-    out.push(...await checkStaffOnline(scope, manifest, callers));
+    const logins = readHumans(org).flatMap((h) => h.github ? [h.github] : []);
+    out.push(...await checkStaffOnline(scope, manifest, callers, logins));
   }
   return out;
 }
@@ -3834,14 +3850,14 @@ async function checkReviewGates(ws, org, composer) {
   const readings = await Promise.all([...repos].map((r) => readGate(r, [...apps])));
   return readings.map((r) => ({ scope: "workspace", id: "review-gate", ...judgeGate(r) }));
 }
-async function checkStaffOnline(scope, manifest, callers) {
+async function checkStaffOnline(scope, manifest, callers, humans = []) {
   const out = [];
   const repo = manifest.brain;
   const needed = /* @__PURE__ */ new Set();
   for (const c of callers) {
     for (const m of c.text.matchAll(/secrets\.([A-Z0-9_]+)/g)) needed.add(m[1]);
   }
-  const [secrets, orgSecrets, labels, runs, pinned, workflows] = await Promise.all([
+  const [secrets, orgSecrets, labels, runs, pinned, workflows, open2] = await Promise.all([
     api(`repos/${repo}/actions/secrets`),
     /* An agent credential kept once for the org, and shared with this repo, is as good as one
        on the repo: Actions resolves `secrets.X` from either. Read separately because the two
@@ -3869,7 +3885,8 @@ async function checkStaffOnline(scope, manifest, callers) {
       { owner: repo.split("/")[0], name: repo.split("/")[1] }
     ) : Promise.resolve(null),
     // The callers are read in detail below, so only everything else in the repo is looked at.
-    checkWorkflows(scope, repo, new Set(callers.map((c) => c.name)))
+    checkWorkflows(scope, repo, new Set(callers.map((c) => c.name))),
+    api(`repos/${repo}/issues?state=open&per_page=100`)
   ]);
   out.push(...workflows);
   if (!secrets.ok) {
@@ -3921,7 +3938,9 @@ async function checkStaffOnline(scope, manifest, callers) {
         fix: "An agent applying a label that does not exist gets an API error mid-run."
       } : { scope, level: "ok", id: "labels", title: "every declared label exists" }
     );
+    out.push(ownedLabels(scope, repo, have));
   }
+  if (open2.ok) out.push(...unkindedAsks(scope, repo, open2.data, humans));
   const peers = (manifest.peers ?? []).filter((p) => p.label && p.brain);
   const peerLabels = await Promise.all(
     peers.map(
@@ -4231,6 +4250,32 @@ function parseFlags6(argv) {
   }
   return out;
 }
+function ownedLabels(scope, repo, have) {
+  const gone = OWNED_LABELS.filter((l) => !have.has(l));
+  return gone.length ? {
+    scope,
+    level: "warn",
+    id: "owned-labels",
+    title: `roster's labels are missing from ${repo}: ${gone.join(", ")}`,
+    fix: gone.map((l) => `gh label create ${l} --repo ${repo} --force`).join("\n")
+  } : { scope, level: "ok", id: "owned-labels", title: "roster's own labels exist" };
+}
+function unkindedAsks(scope, repo, issues, humans) {
+  const on = new Set(humans.map((h) => h.toLowerCase()));
+  const bad = issues.filter(
+    (i) => !i.pull_request && (i.assignees ?? []).some((a) => on.has(a.login.toLowerCase())) && askKinds(i.labels.map((l) => l.name)).length !== 1
+  );
+  if (!bad.length) return [];
+  return [
+    {
+      scope,
+      level: "warn",
+      id: "ask-kind",
+      title: `${bad.length} open ask${bad.length === 1 ? "" : "s"} on ${repo} without exactly one of decision, review or chore: ${bad.map((i) => "#" + i.number).join(", ")}`,
+      fix: "Label each with one kind. The next daily sweep does this too."
+    }
+  ];
+}
 
 // src/commands/export.ts
 import { writeFileSync as writeFileSync6 } from "fs";
@@ -5222,9 +5267,24 @@ import { promisify as promisify3 } from "util";
 
 // src/lib/ask.ts
 var MAX_PATCH_LINES = 40;
-function askTitle(req) {
+function askHead(req) {
   const name = req.pr.repo.split("/")[1] ?? req.pr.repo;
-  const head2 = `${name}#${req.pr.number} \u2014 `;
+  return `${name}#${req.pr.number} \u2014 `;
+}
+function askFollowUp(req) {
+  const said = req.body.trim();
+  const it = req.pr.kind === "issue" ? "issue" : "pull request";
+  const first = stripLeadingMention(said, req.staff.mention) ? `${req.staff.mention} ${said}` : said;
+  const where = req.anchor?.path ? `
+
+They were looking at \`${req.anchor.path}\`.` : "";
+  return `${first}${where}
+
+Same as above: answer on the ${it}, then close this issue.
+`;
+}
+function askTitle(req) {
+  const head2 = askHead(req);
   const room = 120 - head2.length;
   const title = req.pr.title.trim() || "a pull request";
   return head2 + (title.length > room ? `${title.slice(0, room - 1).trimEnd()}\u2026` : title);
@@ -5302,11 +5362,21 @@ async function act(req) {
     if (repo !== ask.staff.brain)
       throw new Error(`an ask goes to ${ask.staff.brain}, not to ${repo}`);
     if (!ask.body?.trim()) throw new Error("an empty ask is not an ask");
-    const title = (req.title ?? "").trim() || askTitle(ask);
-    const args = ["issue", "create", "--repo", repo, "--title", title, "--body-file", "-"];
-    for (const l of req.labels ?? []) args.push("--label", l);
-    const { stdout } = await execWithStdin(args, askBody(ask));
-    const url = stdout.trim().split("\n").pop();
+    const open2 = await openAskFor(repo, askHead(ask));
+    let url;
+    if (open2) {
+      const { stdout } = await execWithStdin(
+        ["issue", "comment", String(open2), "--repo", repo, "--body-file", "-"],
+        askFollowUp(ask)
+      );
+      url = stdout.trim().split("\n").pop();
+    } else {
+      const title = (req.title ?? "").trim() || askTitle(ask);
+      const args = ["issue", "create", "--repo", repo, "--title", title, "--body-file", "-"];
+      for (const l of req.labels ?? []) args.push("--label", l);
+      const { stdout } = await execWithStdin(args, askBody(ask));
+      url = stdout.trim().split("\n").pop();
+    }
     if (!req.alsoOnPr) return { ok: true, action, url };
     const note = `${ask.body.trim()}
 
@@ -5365,6 +5435,34 @@ async function act(req) {
   }
   throw new Error(`unknown action "${action}"`);
 }
+async function openAskFor(repo, head2) {
+  try {
+    const { stdout } = await run3(
+      "gh",
+      [
+        "issue",
+        "list",
+        "--repo",
+        repo,
+        "--state",
+        "open",
+        "--limit",
+        "20",
+        "--search",
+        `in:title "${head2.replace(/ — $/, "")}"`,
+        "--json",
+        "number,title"
+      ],
+      { encoding: "utf8" }
+    );
+    const found = JSON.parse(stdout).find(
+      (i) => i.title.startsWith(head2)
+    );
+    return found?.number ?? null;
+  } catch {
+    return null;
+  }
+}
 function whyNotMerged(ghError, pr) {
   const checks = pr?.statusCheckRollup ?? [];
   const name = (c) => c.name || c.context || "a check";
@@ -5605,11 +5703,15 @@ var PR_TYPES = `[ISSUE_COMMENT, CROSS_REFERENCED_EVENT, REFERENCED_EVENT, CLOSED
   REOPENED_EVENT, MERGED_EVENT, LABELED_EVENT, UNLABELED_EVENT, ASSIGNED_EVENT,
   UNASSIGNED_EVENT, RENAMED_TITLE_EVENT, PULL_REQUEST_REVIEW, READY_FOR_REVIEW_EVENT,
   REVIEW_REQUESTED_EVENT]`;
-var LIGHT = `number title url state createdAt updatedAt
+var LIGHT = `number title url state createdAt updatedAt closedAt body
         author { login }
         labels(first:12) { nodes { name } }
         assignees(first:8) { nodes { login } }
-        comments { totalCount }`;
+        comments { totalCount }
+        last: comments(last:1) { nodes { author { login } createdAt body } }
+        closer: timelineItems(last:1, itemTypes:[CLOSED_EVENT]) {
+          nodes { ... on ClosedEvent { actor { login } } }
+        }`;
 var LIGHT_PR = `${LIGHT} isDraft mergeable
         commits(last:1) { nodes { commit { statusCheckRollup { state } } } }`;
 var QUERY = `
@@ -5703,7 +5805,10 @@ function shape(n, repo, role, kind) {
     kind,
     number: n.number,
     title: n.title ?? "",
-    body: n.body ?? "",
+    // The list carries the body only to find a decision's default; a row never shows it, and
+    // a thread that is opened is read whole on its own.
+    body: n.timelineItems ? n.body ?? "" : "",
+    ...extras(n),
     labels: (n.labels?.nodes ?? []).map((l) => l.name),
     assignees: (n.assignees?.nodes ?? []).map((a) => a.login),
     author: n.author?.login ?? "",
@@ -5719,6 +5824,29 @@ function shape(n, repo, role, kind) {
     reactions: reactions(n)
   };
 }
+function extras(n) {
+  const out = {};
+  if (n.closedAt) out.closedAt = n.closedAt;
+  const closer = n.closer?.nodes?.[0]?.actor?.login;
+  if (closer) out.closedBy = closer;
+  const last = n.last?.nodes?.[0];
+  if (last) {
+    out.lastComment = {
+      author: last.author?.login ?? "",
+      createdAt: last.createdAt,
+      body: String(last.body ?? "").slice(0, 800)
+    };
+  }
+  const due = dueOf(n.body ?? "");
+  if (due) out.due = due;
+  return out;
+}
+function dueOf(body) {
+  const m = /if i hear nothing by \**(\d{4}-\d{2}-\d{2})\**,?\s*i(?:'|’)?ll\s+([^\n]+)/i.exec(body);
+  if (!m) return void 0;
+  const action = m[2].replace(/[*_"“”]+/g, "").replace(/\.\s*$/, "").trim();
+  return { date: m[1], action };
+}
 function reactions(n) {
   return (n.reactionGroups ?? []).filter((g) => (g.reactors?.totalCount ?? 0) > 0).map((g) => ({
     content: g.content,
@@ -5869,6 +5997,74 @@ function short4(e) {
   return line.length > 200 ? line.slice(0, 199) + "\u2026" : line;
 }
 
+// src/lib/live.ts
+var FINISHED_HOURS = 6;
+function parseTitle(handle, title, workflow = "") {
+  const m = new RegExp(
+    `^${handle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")} (daily|manual|follow-on|mention|peer)(?: #(\\d+))?\\s*$`
+  ).exec(title.trim());
+  if (m) return { trigger: m[1], issue: m[2] ? Number(m[2]) : null };
+  if (/daily/i.test(workflow)) return { trigger: "daily", issue: null };
+  if (/mention/i.test(workflow)) return { trigger: "mention", issue: null };
+  return { trigger: "unknown", issue: null };
+}
+function shapeLive(handle, brain, raw, limit, now = Date.now()) {
+  const today = new Date(now).toISOString().slice(0, 10);
+  const since = now - FINISHED_HOURS * 36e5;
+  const out = { handle, brain, running: [], finished: [], automatic: 0, limit };
+  for (const r of raw) {
+    if (r.conclusion === "skipped") continue;
+    const { trigger, issue } = parseTitle(handle, r.displayTitle ?? "", r.workflowName ?? "");
+    const run6 = {
+      id: Number(r.databaseId),
+      trigger,
+      issue,
+      status: String(r.status ?? ""),
+      conclusion: r.conclusion ?? null,
+      createdAt: String(r.createdAt ?? ""),
+      updatedAt: String(r.updatedAt ?? r.createdAt ?? ""),
+      url: String(r.url ?? "")
+    };
+    if ((trigger === "peer" || trigger === "follow-on") && run6.createdAt.slice(0, 10) === today) {
+      out.automatic++;
+    }
+    if (run6.status !== "completed") out.running.push(run6);
+    else if (new Date(run6.updatedAt).getTime() >= since) out.finished.push(run6);
+  }
+  out.running.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  out.finished.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+  return out;
+}
+async function liveFor(staff) {
+  return Promise.all(
+    staff.map(async (s) => {
+      const res = await ghJson([
+        "run",
+        "list",
+        "--repo",
+        s.brain,
+        "--limit",
+        // Skipped mentions are most of the list; this is enough to reach past them to today's.
+        "60",
+        "--json",
+        "databaseId,displayTitle,workflowName,status,conclusion,createdAt,updatedAt,url"
+      ]);
+      if (!res.ok) {
+        return {
+          handle: s.handle,
+          brain: s.brain,
+          running: [],
+          finished: [],
+          automatic: 0,
+          limit: s.limit,
+          error: res.error
+        };
+      }
+      return shapeLive(s.handle, s.brain, res.data ?? [], s.limit);
+    })
+  );
+}
+
 // src/lib/notifications.ts
 async function unreadFor(owner, pages = 5) {
   const out = /* @__PURE__ */ new Map();
@@ -7477,6 +7673,24 @@ async function portalCommand(argv) {
         });
         return;
       }
+      if (url.pathname === "/api/live") {
+        const org = readOrg(w.opsDir, parseYaml);
+        const staff = (org.staff ?? []).map((s) => {
+          const dir = s.dir ?? s.handle;
+          let m = {};
+          try {
+            m = readManifest2(join28(w.root, dir), parseYaml);
+          } catch {
+          }
+          return {
+            handle: String(s.handle),
+            brain: String(m.brain ?? `${org.org}/${dir}`),
+            limit: Number(m.max_runs_per_day ?? 6)
+          };
+        });
+        liveFor(staff).then((list) => json(res, { fetchedAt: (/* @__PURE__ */ new Date()).toISOString(), staff: list })).catch((err) => json(res, { error: String(err?.message ?? err), staff: [] }));
+        return;
+      }
       if (url.pathname === "/api/runs") {
         const fresh = url.searchParams.get("refresh") === "1";
         if (!fresh && runsCache && Date.now() - runsCache.at < TTL) {
@@ -8194,7 +8408,9 @@ async function main(argv) {
   const raw = rewriteOutput();
   const [command, ...rest] = argv;
   if (!command) return portalCommand([]);
-  if (command === "help" || command === "--help" || command === "-h") {
+  const asksHelp = command === "help" || command === "--help" || command === "-h";
+  if (command.startsWith("-") && !asksHelp) return portalCommand(argv);
+  if (asksHelp) {
     const topic = rest[0];
     if (!topic || !HELPS[topic]) {
       const name = bin();

package/docs/README.md

@@ -26,7 +26,7 @@ Read in this order.
 | [Getting started](getting-started.md) | One command, in a browser: stand up an org, or join one that exists. |
 | [The portal](portal.md) | Where the work happens: setup, every screen, every action. |
 | [Manual steps](manual-steps.md) | What only a person can do, why, and what breaks if it is skipped. |
-| [Concepts](concepts.md) | The six things you need to know, then the detail. |
+| [Concepts](concepts.md) | The three things you need to know, then the detail. |
 | [Choosing a coding agent](agents.md) | Claude, Codex, Nanocoder, or anything with a command line. |
 | [Writing a charter](writing-a-charter.md) | The one file nothing can generate for you. |
 | [Extending it](extending.md) | The four seams, and which one to reach for. |

package/docs/commands.md

@@ -270,7 +270,8 @@ ROSTER_CONTEXT='{"issue_number":"1","comment_id":"1","repo":"o/r"}' \
 ## `roster portal`
 
 Serve a local UI over the checked-out repositories. **`roster` with no arguments does the same**,
-which is the shortest way in.
+which is the shortest way in. It takes the same flags: `roster --no-open` is `roster portal
+--no-open`.
 
 ```
 --port <n>    default 4300
@@ -285,7 +286,7 @@ 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).
 
-Views: Inbox, Org, Staff, Docs, and per staff member Brain, Prompt, Graph, What changed, Health.
+Views: Home, Trackers, Runs, Org, Staff, Docs, and per staff member Brain, Prompt, Graph, What changed, Health.
 
 It can act as you through your own `gh`: reply, close, reopen and open issues; hire and retire;
 edit and commit the org layer, prompt fragments and charters; create a staff member's GitHub App;

package/docs/concepts.md

@@ -6,30 +6,24 @@ sidebar_order: 3
 
 # Concepts
 
-## The six things you need to know
+## The three things you need to know
 
 Enough to set up an org and read what it does. Everything after this section is detail you
 can learn when you need it.
 
-1. **The org layer.** One private repo, `<org>/roster-ops`, holds what every staff member
-   shares: what the business is (`org/business.md`), what matters this month
-   (`org/priorities.md`), the house voice and the guardrails. Change it once and every staff
-   member has it on their next run. [More](#the-ops-repo).
-2. **A staff member is a repo.** Each one has a private repo, its *brain*: what it knows, what
-   it is working on, and what it has decided. There is no database and no server; the portal
-   reads the repos. [More](#the-brain).
-3. **The charter.** `CHARTER.md` in the brain says who this staff member is and what it
-   decides alone. You write it, with a brief that interviews you; roster never generates one,
-   because a generated charter makes a generic agent. [More](#charter-and-manifest).
-4. **Memory.** `memory/INDEX.md` is one line per fact, read at the start of every run. The
-   agent writes it and deletes from it; you can read and correct it in the portal. That is how
-   a staff member remembers yesterday. [More](memory.md).
-5. **The daily run.** A scheduled GitHub Actions workflow in each brain wakes the staff member,
-   hands it a prompt built from the org layer plus its charter and memory, and it does one piece
-   of work and writes down what happened. [More](#kinds-of-run).
-6. **Mentions.** Write `@handle` in an issue or comment on a staff member's own tracker and it
-   runs to answer that, between daily runs. Nothing on a product repo wakes anybody; you ask
-   them on their tracker. [More](#kinds-of-run).
+1. **The org files everyone shares.** One private repo, `<org>/roster-ops`, holds what every
+   staff member reads: what the business is (`org/business.md`), what matters this month
+   (`org/priorities.md`), the house voice and the guardrails. Change one and every staff member
+   has it on their next run. [More](#the-ops-repo).
+2. **One repo per staff member.** Each staff member is a private repo, its *brain*. In it,
+   `CHARTER.md` says who they are and what they decide alone. You write it; roster never
+   generates one, because a generated charter makes a generic agent. `memory/INDEX.md` is what
+   they know, one line per fact, which they keep and you can correct. There is no database and
+   no server; the portal reads the repos. [More](#the-brain).
+3. **The daily run, and asking.** Each weekday a scheduled run wakes them: it reads the org
+   files, their charter and their memory, does one piece of work, and hands it to you as a pull
+   request or a question. Between runs, write `@handle` on their tracker and they answer that.
+   [More](#kinds-of-run).
 
 Everything below, and the rest of the docs, is detail: identities, peers, surfaces, the
 prompt's layers, upgrading. None of it is needed to get a first run.
@@ -60,6 +54,11 @@ ranked, and what is out of scope. It is composed into every daily run, a run pic
 serves it, and a PR names the priority it serves. Keep it to three priorities or fewer, and
 rewrite it when the month turns.
 
+In the last three days of each month the staff member `org.yaml` lists first opens a pull
+request on the ops repo with a draft for next month, built from this month's, what shipped and
+the other staff's status issues. It shows on Home with Merge; edit it first if you like. Until it
+is merged, this month's stand.
+
 Without it each staff member picks its own work from its own charter, and they drift. `roster
 init` writes a stub; `roster doctor` warns while it is missing or still the stub. An org that
 predates it just adds the file.
@@ -127,6 +126,20 @@ control.
 | `daily` | the scheduled session. Boot, work, hand off. |
 | `mention` | `@handle` in a comment or a new issue body. A task, not a session. |
 
+What starts a run:
+
+| Trigger | Runs | Counts against `max_runs_per_day` |
+|---|---|---|
+| the schedule | `daily` | no |
+| **Run once now**, or Actions → Run workflow | `daily` | no |
+| a person writing `@handle` on the staff member's tracker | `mention` | no |
+| a peer opening an issue there with their `from-<handle>` label | `mention`, framed as a peer's ask | yes |
+| a daily run that ended with the next step ready | `daily`, as a follow-on | yes |
+
+A person commenting without the `@handle` wakes nobody, so people can discuss on an issue
+among themselves. A run started by a peer may not file on another peer, and the limit (6 a day
+unless `staff.yaml` says otherwise) stops a chain of runs that nobody asked for.
+
 A `mention` prompt refuses to compose without trigger context, because it is written for the
 comment that woke it. That is correct behaviour, not a bug.
 

package/docs/doctor-codes.md

@@ -63,6 +63,8 @@ ran at all.
 | `surfaces` | A surface declared in `staff.yaml` is not on disk. The portal renders nothing for it. |
 | `secrets` | Every secret the callers reference exists on the brain repo, or is an organisation secret shared with it. Derived from the callers themselves, not a fixed list. |
 | `labels` | Every label declared in `staff.yaml` exists. An agent applying a label that does not exist gets an API error mid-run. |
+| `owned-labels` | Roster's own labels exist on the tracker: `decision`, `review`, `chore` and `keep-open`. Checked whatever `staff.yaml` declares, since the prompts apply them. The fix is the `gh label create` lines. |
+| `ask-kind` | An open issue assigned to a human has no ask kind, or more than one. Home sorts what needs you by kind, so an ask without one lands nowhere. |
 | `peer-labels` | The `from-<handle>` label exists on the *peer's* tracker, which is where this staff member's asks land. |
 | `status-issue` | The declared status issue is actually pinned. If not, the place you look is not the place the agent maintains. |
 | `runs` | A window of recent runs. See below. |

package/docs/getting-started.md

@@ -30,7 +30,7 @@ hour is the part not to rush.
 - **A credential for your [coding agent](agents.md).** For Claude Code, run
   `claude setup-token` and keep the token it prints for step 5.
 
-You only need [the six things in Concepts](concepts.md#the-six-things-you-need-to-know) to follow
+You only need [the three things in Concepts](concepts.md#the-three-things-you-need-to-know) to follow
 this. Everything else can wait.
 
 ## 1. Say which organisation, then read the plan
@@ -51,7 +51,8 @@ can call its workflow. Without that every run fails with "workflow not found". I
 (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.
+started**, which keeps them in the sidebar until they are done, with hiring first. The sidebar
+counts them: three for the org, five for each staff member.
 
 ## 2. Say what the business is
 
@@ -181,8 +182,8 @@ each.
 
 - **A second staff member**: Staff → Hire someone, then GitHub App, the charter and one run. The
   credential is already there.
-- **Answering your agents**: [the Inbox](portal.md#inbox) is everything open across the org, and
-  the reply goes out as you. Work they finished sits in [Pending work](portal.md#pending-work).
+- **Answering your agents**: [Home](portal.md#home) is what needs you, who is working and
+  what you asked for. Replies and merges go out as you.
 - **A framework update**: `roster upgrade`, or the same from the portal. See
   [upgrading](upgrading.md).
 - **The whole portal**, screen by screen: [the portal](portal.md).

package/docs/org-yaml.md

@@ -126,6 +126,7 @@ Fallbacks for staff members who do not set their own.
 | `model` | Model id passed to the agent. |
 | `timeout_minutes` | Ceiling on a daily session. `90` if unset. |
 | `mention_timeout_minutes` | Ceiling on a mention run. Falls back to `timeout_minutes`, then `90`. |
+| `max_runs_per_day` | What a new hire's `max_runs_per_day` starts at. `6` when unset. |
 | `allowed_tools` | Claude's own spelling of a permission level, kept because it predates `agent.permissions` and still wins for the agents that take a tool list. Nothing translates it for the others: a list written for one agent is not a permission level for another. Prefer [`agent.permissions`](agents.md#permissions), which every agent understands. |
 
 ### `memory`

package/docs/portal.md

@@ -21,8 +21,8 @@ Keep the repos checked out beside each other, in the same shape the runner uses.
 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
+**The counts are right on load.** The badges beside Home and Trackers are fetched once at
+boot, and the screens share that request rather than making a second one. A sidebar that
 says nothing until you look at it is not a sidebar.
 
 While the first answer is outstanding the badge is a placeholder rather than blank, because an
@@ -78,12 +78,49 @@ staff member* first, then the Actions setting, the credential, the repo picker,
 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
+## Home
+
+Where the portal opens. An Ask box at the top, then these, in order.
+
+- **Ask.** Pick a staff member, type what you want, **Send**. It opens an issue on their
+  tracker with their `@handle` in front, which wakes them in about a minute.
+- **Latest reports.** Each staff member's run report from the last day: the three lines they
+  post on their status issue at the end of a daily run. Nothing shows until there is one.
+- **Needs you.** Every ask a staff member has put on you, and every pull request ready to
+  merge, oldest first. Each card has one action on its right:
+  - a `decision` has **Reply**, and **Go with the default** when it carries one. The default
+    and its date are shown, and turn amber once the date has passed.
+  - a `review` has **Approve**.
+  - a `chore` has **Done**, which closes it.
+  - a pull request has **Merge**, unless its checks fail, are still running, or it conflicts.
+
+  Answers go out as you, with the staff member's `@handle`, so they act on them straight away.
+  When nothing is waiting, it says so.
+- **Working now.** Each staff member: what they are running and what started it (the daily run,
+  a follow-on, answering an issue, a peer's ask), for how long, with a link to the log. When
+  they are idle, how their last run ended. Peer and follow-on runs today are counted against
+  `max_runs_per_day`. This asks GitHub every few seconds while a run is going and every half
+  minute otherwise, and only while Home is on screen.
+- **Your requests.** What you asked for: waiting, being worked on (a run for it is going), or
+  answered (a staff member had the last word).
+- **Closed today.** What the staff closed today, with the line they closed it with, and
+  **Reopen** beside each. Staff close finished issues themselves, so this is where you check.
+
+**Every item opens in a side sheet.** Click anywhere on a card or a row and its thread opens
+on the right: the conversation, Reply, Close or Reopen, Merge for a pull request, and Open in
+GitHub. Escape or the × closes it, and Home repaints where you were.
+
+**Nothing is missed.** Every open issue and pull request has exactly one place: on Home, or on
+the staff member's own tracker (their status issue, a peer's ask, their own work), or elsewhere
+(draft pull requests, contributor issues). The line at the bottom counts the last two, with a
+link to Trackers.
+
+## Trackers
 
 Everything open across the org, from one GraphQL call per repo. Bodies and full timelines come
 down with the list, so opening a thread is a render rather than a request.
 
-- **The links under Inbox in the sidebar filter it.** All; Unread; each staff member, which
+- **The links under Trackers in the sidebar filter it.** All; Unread; each staff member, which
   lists the issues on their own tracker whoever filed them; and Issues, the product repos.
 - **Unread comes from your GitHub notifications.** A thread with activity you have not read has
   a bar on the left and a bold title, and Unread lists only those, with a count. Opening one
@@ -144,7 +181,7 @@ down with the list, so opening a thread is a render rather than a request.
 
 ## Pending work
 
-The same screen, scoped to pull requests, in its own place in the sidebar. An inbox is what is
+The same screen, scoped to pull requests. It is where a pull request opens from Home. An inbox is what is
 waiting on you; a pull request is work that is finished and waiting on a merge, and the count
 that matters is not how many are open but how many are green and still sitting there.
 
@@ -339,7 +376,7 @@ already declared `memory/` as a surface.
 The navigator has three boxes, because a parsed memory section and a file on disk are
 different kinds of thing.
 
-**Memory** is the fact sections, the notes behind them, and `INDEX.md` itself. A note is the
+**What they know** is the fact sections, the notes behind them, and `INDEX.md` itself. A note is the
 argument behind one fact, read only when that fact is in play, which is what keeps the index
 cheap enough to read at every boot. Both live here rather than among the files: `INDEX.md` is
 literally what "All facts" renders.