@nanocollective/roster 0.1.0-alpha.42 → 0.1.0-alpha.44

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()}
 
@@ -5356,11 +5426,84 @@ async function act(req) {
     if (!flag) throw new Error(`unknown merge method "${req.mergeMethod}"`);
     const args = ["pr", "merge", n, "--repo", repo, flag];
     if (req.body?.trim() && how !== "rebase") args.push("--body", req.body.trim());
-    await run3("gh", args, { encoding: "utf8" });
+    try {
+      await run3("gh", args, { encoding: "utf8" });
+    } catch (err) {
+      throw new Error(whyNotMerged(errText(err), await prState(repo, n)));
+    }
     return { ok: true, action, mergedBy: how };
   }
   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";
+  const running = checks.filter(
+    (c) => c.status && c.status !== "COMPLETED" || c.state === "PENDING" || c.state === "EXPECTED"
+  );
+  const failing = checks.filter(
+    (c) => ["FAILURE", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "ERROR"].includes(
+      String(c.conclusion || c.state || "")
+    )
+  );
+  const list = (cs) => cs.map(name).join(", ");
+  if (pr?.mergeStateStatus === "BLOCKED" && failing.length)
+    return `Not merged: checks failed (${list(failing)}).`;
+  if (pr?.mergeStateStatus === "BLOCKED" && running.length)
+    return `Not merged: checks are still running (${list(running)}). Merge again once they pass.`;
+  if (pr?.mergeStateStatus === "BLOCKED")
+    return "Not merged: the branch rules require something first, such as a review. Open it in GitHub to see what.";
+  if (pr?.mergeStateStatus === "BEHIND")
+    return "Not merged: the branch is behind its base, and the branch rules require it to be up to date.";
+  if (pr?.mergeStateStatus === "DIRTY") return "Not merged: the branch conflicts with its base.";
+  const line = ghError.split("\n").map((l) => l.replace(/^[!X✗]\s*/, "").trim()).find((l) => l && !l.startsWith("Command failed") && !/--auto|--admin/.test(l));
+  return `Not merged: ${line ?? "GitHub refused it without saying why."}`;
+}
+function errText(err) {
+  const e = err;
+  return `${e?.stderr ?? ""}
+${e?.message ?? ""}`;
+}
+async function prState(repo, n) {
+  try {
+    const { stdout } = await run3(
+      "gh",
+      ["pr", "view", n, "--repo", repo, "--json", "mergeStateStatus,statusCheckRollup"],
+      { encoding: "utf8" }
+    );
+    return JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+}
 async function mergeMethodFor(repo) {
   try {
     const { stdout } = await run3(
@@ -5560,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 = `
@@ -5658,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 ?? "",
@@ -5674,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,
@@ -5824,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();
@@ -7432,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) {
@@ -8149,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`