@mutmutco/cli 0.10.0 → 0.11.0

package/dist/index.cjs

@@ -3038,7 +3038,7 @@ var {
 
 // src/index.ts
 var import_promises = require("node:fs/promises");
-var import_node_fs3 = require("node:fs");
+var import_node_fs4 = require("node:fs");
 var import_node_crypto = require("node:crypto");
 
 // src/rules-sync.ts
@@ -3065,6 +3065,27 @@ function rulesSourceAuthHeaders(sourceUrl, token) {
   return void 0;
 }
 
+// src/docs-sync.ts
+var SYNCED_DOCS = ["README.md", "architecture.md"];
+async function syncDocs(deps, docs2 = SYNCED_DOCS) {
+  const updated = [];
+  const skippedDirty = [];
+  for (const file of docs2) {
+    if (await deps.isDirty(file)) {
+      skippedDirty.push(file);
+      continue;
+    }
+    const origin = await deps.originContent(file);
+    if (origin === null) continue;
+    const local = await deps.localContent(file);
+    if (needsUpdate(origin, local)) {
+      await deps.writeDoc(file, normalizeEol(origin));
+      updated.push(file);
+    }
+  }
+  return { updated, skippedDirty };
+}
+
 // src/saga-capture.ts
 function parseHookInput(stdin) {
   try {
@@ -3194,7 +3215,7 @@ async function runHeadEngine(prompt, timeoutMs = HEAD_ENGINE_TIMEOUT_MS) {
 
 // src/gh-create.ts
 var ISSUE_TYPES = ["bug", "feature", "task"];
-var PRIORITIES = ["high", "medium", "low"];
+var PRIORITIES = ["urgent", "high", "medium", "low"];
 function parseCreatedUrl(stdout) {
   const re = /https:\/\/github\.com\/[^\s]+\/(?:issues|pull)\/(\d+)/g;
   let match;
@@ -3206,7 +3227,7 @@ function parseCreatedUrl(stdout) {
 ${stdout.trim() || "(empty)"}`);
   return last;
 }
-function buildIssueArgs({ type, title, body, priority, repo }) {
+function buildIssueArgs({ type, title, body, priority, repo, labels }) {
   if (!ISSUE_TYPES.includes(type)) throw new Error(`unknown issue type "${type}" \u2014 expected one of: ${ISSUE_TYPES.join(", ")}`);
   if (!PRIORITIES.includes(priority)) {
     throw new Error(`unknown priority "${priority}" \u2014 expected one of: ${PRIORITIES.join(", ")}`);
@@ -3215,8 +3236,36 @@ function buildIssueArgs({ type, title, body, priority, repo }) {
   if (repo) args.push("--repo", repo);
   args.push("--title", title, "--body", body, "--label", type);
   args.push("--label", `priority:${priority}`);
+  for (const label of labels ?? []) args.push("--label", label);
   return args;
 }
+function boardAttachSkipReason(cwdRepo, targetRepo2) {
+  if (targetRepo2 && cwdRepo && targetRepo2 !== cwdRepo) {
+    return `issue was created in ${targetRepo2}, not the board's repo ${cwdRepo}`;
+  }
+  return null;
+}
+function buildAddToProjectArgs(projectId, contentId) {
+  if (!projectId) throw new Error("addToProject: projectId is required");
+  if (!contentId) throw new Error("addToProject: contentId is required");
+  return [
+    "api",
+    "graphql",
+    "-f",
+    "query=mutation($p:ID!,$c:ID!){addProjectV2ItemById(input:{projectId:$p,contentId:$c}){item{id}}}",
+    "-f",
+    `p=${projectId}`,
+    "-f",
+    `c=${contentId}`
+  ];
+}
+function parseAddedItemId(stdout) {
+  try {
+    return JSON.parse(stdout)?.data?.addProjectV2ItemById?.item?.id || void 0;
+  } catch {
+    return void 0;
+  }
+}
 function buildPrArgs({ title, body, base, head, repo }) {
   const args = ["pr", "create"];
   if (repo) args.push("--repo", repo);
@@ -3343,6 +3392,10 @@ function buildVersionLagReport(input) {
     releasedVersion: input.releasedVersion
   };
 }
+function versionAutoUpdateAction(report, hasPluginRoot) {
+  if (report.ok || report.staleAgainst !== "released") return "none";
+  return hasPluginRoot ? "plugin-pull" : "npm";
+}
 
 // src/issue-related.ts
 var STOPWORDS = /* @__PURE__ */ new Set([
@@ -3401,7 +3454,50 @@ ${lines.join("\n")}`;
 // src/board.ts
 var import_node_child_process2 = require("node:child_process");
 var import_node_util = require("node:util");
-var execFileP = (0, import_node_util.promisify)(import_node_child_process2.execFile);
+
+// src/board-priority.ts
+var BOARD_PRIORITY_NAMES = ["Urgent", "High", "Medium", "Low"];
+var CLI_PRIORITIES = ["urgent", "high", "medium", "low"];
+var LABEL_PREFIX = "priority:";
+function cliPriorityToFieldName(priority) {
+  if (!CLI_PRIORITIES.includes(priority)) {
+    throw new Error(`unknown priority "${priority}" \u2014 expected one of: ${CLI_PRIORITIES.join(", ")}`);
+  }
+  return priority.charAt(0).toUpperCase() + priority.slice(1);
+}
+function labelToFieldPriority(label) {
+  if (!label.startsWith(LABEL_PREFIX)) return void 0;
+  const slug = label.slice(LABEL_PREFIX.length).toLowerCase();
+  if (!CLI_PRIORITIES.includes(slug)) return void 0;
+  return cliPriorityToFieldName(slug);
+}
+function resolvePriorityOptionId(cfg, priority) {
+  if (!cfg.priorityFieldId || !cfg.priorityOptions) return void 0;
+  const name = cliPriorityToFieldName(priority);
+  return cfg.priorityOptions[name];
+}
+function isPriorityFieldConfigured(cfg) {
+  return Boolean(
+    cfg.priorityFieldId && BOARD_PRIORITY_NAMES.every((name) => cfg.priorityOptions?.[name])
+  );
+}
+function recoverPriorityFromEvents(events) {
+  let found;
+  for (const event of events) {
+    if (event.event !== "labeled" || !event.label?.name) continue;
+    const mapped = labelToFieldPriority(event.label.name);
+    if (mapped) found = mapped;
+  }
+  return found;
+}
+
+// src/board.ts
+var rawExecFileP = (0, import_node_util.promisify)(import_node_child_process2.execFile);
+var execFileP = (file, args, options = {}) => (
+  // encoding 'utf8' guarantees string output at runtime; the cast pins the type (promisify's
+  // overloads widen to string|Buffer when options is spread in).
+  rawExecFileP(file, args, { encoding: "utf8", windowsHide: true, ...options })
+);
 var BOARD_STATUSES = ["Todo", "In Progress", "In Review", "Done"];
 var ACTIVE_STATUSES = /* @__PURE__ */ new Set(["Todo", "In Progress", "In Review"]);
 var STATUS_ORDER = new Map(BOARD_STATUSES.map((s, i) => [s, i]));
@@ -3419,7 +3515,7 @@ var defaultGit = async (args) => {
   }
 };
 var PROJECT_ITEMS_QUERY = `
-query($owner: String!, $number: Int!, $statusField: String!, $after: String) {
+query($owner: String!, $number: Int!, $after: String) {
   viewer { login }
   organization(login: $owner) {
     projectV2(number: $number) {
@@ -3429,8 +3525,14 @@ query($owner: String!, $number: Int!, $statusField: String!, $after: String) {
         pageInfo { hasNextPage endCursor }
         nodes {
           id
-          fieldValueByName(name: $statusField) {
-            ... on ProjectV2ItemFieldSingleSelectValue { name optionId }
+          fieldValues(first: 8) {
+            nodes {
+              ... on ProjectV2ItemFieldSingleSelectValue {
+                name
+                optionId
+                field { ... on ProjectV2SingleSelectField { name } }
+              }
+            }
           }
           content {
             __typename
@@ -3476,7 +3578,9 @@ function resolveBoardConfig(cfg) {
     projectNumber: cfg.projectNumber,
     projectId: cfg.projectId,
     statusFieldId: cfg.statusFieldId,
-    statusOptions: cfg.statusOptions
+    statusOptions: cfg.statusOptions,
+    priorityFieldId: cfg.priorityFieldId,
+    priorityOptions: cfg.priorityOptions
   };
 }
 function repoFromGitRemote(remote) {
@@ -3549,6 +3653,22 @@ function findClaimableItem(report, selector) {
   }
   throw new Error(`${selector.repo}#${selector.number} is not on this project board`);
 }
+function renderBoardItem(item) {
+  const assignees = item.assignees.length ? `@${item.assignees.join(", @")}` : "unassigned";
+  const lines = [
+    `${item.ref} - ${item.title}`,
+    `Status: ${item.status} \xB7 ${assignees}${item.priority ? ` \xB7 Priority: ${item.priority}` : ""}`,
+    `Type: ${item.type ?? "item"}${item.labels.length ? ` \xB7 ${item.labels.join(", ")}` : ""}`,
+    item.url
+  ];
+  if (item.details) {
+    lines.push("", item.details.body.trim() || "_(no body)_");
+    for (const comment of item.details.comments) {
+      lines.push("", `\u2014 @${comment.author}:`, comment.body.trim());
+    }
+  }
+  return lines.join("\n");
+}
 function renderBoardReport(report) {
   const lines = [`Board \xB7 ${report.project.title} \xB7 @${report.viewer}`];
   renderScope(lines, "PRIMARY", report.repo, report.primary);
@@ -3559,8 +3679,7 @@ function renderBoardReport(report) {
   }
   return lines.join("\n");
 }
-async function readBoard(options, deps = {}) {
-  const cfg = resolveBoardConfig(options.config);
+async function collectBoardItems(cfg, options, deps) {
   const gh = deps.gh ?? defaultGh;
   const git = deps.git ?? defaultGit;
   const currentRepo = options.repo ?? repoFromGitRemote(await git(["remote", "get-url", "origin"])) ?? "";
@@ -3590,21 +3709,93 @@ async function readBoard(options, deps = {}) {
       after = void 0;
     }
   } while (after);
-  const items = nodesToItems(nodes, warnings);
-  const groups = partitionBoardItems(items, viewer, currentRepo);
+  return { items: nodesToItems(nodes, warnings), viewer, repo: currentRepo, projectId, projectTitle, warnings, partial };
+}
+async function readBoard(options, deps = {}) {
+  const cfg = resolveBoardConfig(options.config);
+  const gh = deps.gh ?? defaultGh;
+  const collected = await collectBoardItems(cfg, options, deps);
+  const groups = partitionBoardItems(collected.items, collected.viewer, collected.repo);
   const report = {
-    project: { owner: cfg.projectOwner, number: cfg.projectNumber, id: projectId, title: projectTitle || String(cfg.projectNumber) },
-    viewer,
-    repo: currentRepo,
+    project: { owner: cfg.projectOwner, number: cfg.projectNumber, id: collected.projectId, title: collected.projectTitle || String(cfg.projectNumber) },
+    viewer: collected.viewer,
+    repo: collected.repo,
     ...groups,
-    warnings,
-    partial
+    warnings: collected.warnings,
+    partial: collected.partial
   };
   if (options.includeBundleDetails) {
     await attachBundleDetails(report, gh, options.allowPartial ?? false);
   }
   return report;
 }
+function findBoardItem(items, selector) {
+  const found = items.find(
+    (candidate) => candidate.repository.toLowerCase() === selector.repo.toLowerCase() && candidate.number === selector.number
+  );
+  if (!found) throw new Error(`${selector.repo}#${selector.number} is not on this project board`);
+  return found;
+}
+async function moveBoardItem(options, deps = {}) {
+  if (!BOARD_STATUSES.includes(options.status)) {
+    throw new Error(`unknown status '${options.status}'; expected one of ${BOARD_STATUSES.join(", ")}`);
+  }
+  const cfg = resolveBoardConfig(options.config);
+  const gh = deps.gh ?? defaultGh;
+  const collected = await collectBoardItems(cfg, options, deps);
+  const selector = parseIssueSelector(options.selector, collected.repo);
+  const item = findBoardItem(collected.items, selector);
+  if (item.contentType !== "Issue") throw new Error(`${item.ref} is not an issue`);
+  const optionId = cfg.statusOptions[options.status];
+  try {
+    await gh([
+      "project",
+      "item-edit",
+      "--id",
+      item.itemId,
+      "--project-id",
+      cfg.projectId,
+      "--field-id",
+      cfg.statusFieldId,
+      "--single-select-option-id",
+      optionId
+    ]);
+  } catch (e) {
+    const warning = `partial move: ${item.ref} status was not changed to ${options.status} (${ghError(e)})`;
+    if (!options.allowPartial) throw new Error(warning);
+    return { item, viewer: collected.viewer, repo: collected.repo, status: item.status, partial: true, warning };
+  }
+  return {
+    item: { ...item, status: options.status, statusOptionId: optionId },
+    viewer: collected.viewer,
+    repo: collected.repo,
+    status: options.status,
+    partial: false
+  };
+}
+async function showBoardItem(options, deps = {}) {
+  const cfg = resolveBoardConfig(options.config);
+  const gh = deps.gh ?? defaultGh;
+  const collected = await collectBoardItems(cfg, options, deps);
+  const selector = parseIssueSelector(options.selector, collected.repo);
+  const item = findBoardItem(collected.items, selector);
+  if (item.contentType === "Issue") {
+    try {
+      const { stdout } = await gh(["issue", "view", String(item.number), "--repo", item.repository, "--json", "body,comments"]);
+      const detail = JSON.parse(stdout);
+      item.details = {
+        body: detail.body ?? "",
+        comments: (detail.comments ?? []).map((comment) => ({
+          author: comment.author?.login ?? "",
+          body: comment.body ?? ""
+        }))
+      };
+    } catch (e) {
+      if (!options.allowPartial) throw new Error(`detail read failed: ${item.ref}: ${ghError(e)}`);
+    }
+  }
+  return item;
+}
 async function claimBoardIssue(options, deps = {}) {
   const cfg = resolveBoardConfig(options.config);
   const gh = deps.gh ?? defaultGh;
@@ -3612,8 +3803,10 @@ async function claimBoardIssue(options, deps = {}) {
   const selector = parseIssueSelector(options.selector, report.repo);
   const item = findClaimableItem(report, selector);
   if (item.contentType !== "Issue") throw new Error(`${item.ref} is not an issue`);
+  const assignee = options.assignee ?? "@me";
+  const assignedLogin = assignee === "@me" ? report.viewer : assignee.replace(/^@/, "");
   try {
-    await gh(["issue", "edit", String(item.number), "--repo", item.repository, "--add-assignee", "@me"]);
+    await gh(["issue", "edit", String(item.number), "--repo", item.repository, "--add-assignee", assignee]);
   } catch (e) {
     throw new Error(`claim failed before board status changed: ${ghError(e)}`);
   }
@@ -3631,11 +3824,117 @@ async function claimBoardIssue(options, deps = {}) {
       cfg.statusOptions["In Progress"]
     ]);
   } catch (e) {
-    const warning = `partial claim: ${item.ref} was assigned to @${report.viewer}, but Status was not moved to In Progress (${ghError(e)})`;
+    const warning = `partial claim: ${item.ref} was assigned to @${assignedLogin}, but Status was not moved to In Progress (${ghError(e)})`;
     if (!options.allowPartial) throw new Error(warning);
     return { item, viewer: report.viewer, repo: report.repo, status: "Todo", partial: true, warning };
   }
-  return { item: { ...item, assignees: [...item.assignees, report.viewer], status: "In Progress" }, viewer: report.viewer, repo: report.repo, status: "In Progress", partial: false };
+  return {
+    item: {
+      ...item,
+      assignees: item.assignees.includes(assignedLogin) ? item.assignees : [...item.assignees, assignedLogin],
+      status: "In Progress",
+      statusOptionId: cfg.statusOptions["In Progress"]
+    },
+    viewer: report.viewer,
+    repo: report.repo,
+    status: "In Progress",
+    partial: false
+  };
+}
+async function setBoardItemPriority(gh, cfg, itemId, priority) {
+  if (!isPriorityFieldConfigured(cfg)) return void 0;
+  const optionId = resolvePriorityOptionId(cfg, priority);
+  if (!optionId || !cfg.priorityFieldId || !cfg.projectId) return void 0;
+  await gh([
+    "project",
+    "item-edit",
+    "--id",
+    itemId,
+    "--project-id",
+    cfg.projectId,
+    "--field-id",
+    cfg.priorityFieldId,
+    "--single-select-option-id",
+    optionId
+  ]);
+  return cliPriorityToFieldName(priority);
+}
+async function backfillBoardPriorities(options, deps = {}) {
+  const cfg = resolveBoardConfig(options.config);
+  if (!isPriorityFieldConfigured(cfg)) {
+    throw new Error("priority field is not configured in .mmi/config.json (priorityFieldId + priorityOptions)");
+  }
+  const gh = deps.gh ?? defaultGh;
+  const collected = await collectBoardItems(cfg, { repo: options.repo }, deps);
+  const issues = collected.items.filter((item) => item.contentType === "Issue");
+  const concurrency = Math.max(1, options.concurrency ?? 8);
+  const result = { scanned: issues.length, set: 0, skipped: 0, failed: 0, details: [] };
+  async function work(item) {
+    if (item.priority) {
+      result.skipped += 1;
+      return;
+    }
+    try {
+      const priority = await recoverIssuePriority(gh, item);
+      if (!priority) {
+        result.skipped += 1;
+        return;
+      }
+      if (options.dryRun) {
+        result.set += 1;
+        result.details.push(`${item.ref} \u2192 ${priority} (dry-run)`);
+        return;
+      }
+      const optionId = cfg.priorityOptions?.[priority];
+      if (!optionId) throw new Error(`no option id for ${priority}`);
+      await gh([
+        "project",
+        "item-edit",
+        "--id",
+        item.itemId,
+        "--project-id",
+        cfg.projectId,
+        "--field-id",
+        cfg.priorityFieldId,
+        "--single-select-option-id",
+        optionId
+      ]);
+      result.set += 1;
+      result.details.push(`${item.ref} \u2192 ${priority}`);
+    } catch (e) {
+      result.failed += 1;
+      result.details.push(`${item.ref}: ${ghError(e)}`);
+    }
+  }
+  for (let i = 0; i < issues.length; i += concurrency) {
+    await Promise.all(issues.slice(i, i + concurrency).map(work));
+  }
+  return result;
+}
+async function recoverIssuePriority(gh, item) {
+  for (const label of item.labels) {
+    const fromLabel = labelToFieldPriority(label);
+    if (fromLabel) return fromLabel;
+  }
+  const { stdout } = await gh(["api", `repos/${item.repository}/issues/${item.number}/events`, "--paginate"]);
+  return recoverPriorityFromEvents(parsePaginatedEvents(stdout));
+}
+function parsePaginatedEvents(stdout) {
+  const trimmed = stdout.trim();
+  if (!trimmed) return [];
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (Array.isArray(parsed)) return parsed;
+  } catch {
+  }
+  return trimmed.split(/\r?\n/).filter(Boolean).flatMap((line) => {
+    try {
+      const parsed = JSON.parse(line);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      return [];
+    }
+  });
 }
 async function fetchProjectPage(gh, cfg, after) {
   const args = [
@@ -3646,9 +3945,7 @@ async function fetchProjectPage(gh, cfg, after) {
     "-f",
     `owner=${cfg.projectOwner}`,
     "-F",
-    `number=${cfg.projectNumber}`,
-    "-f",
-    "statusField=Status"
+    `number=${cfg.projectNumber}`
   ];
   if (after) args.push("-f", `after=${after}`);
   const { stdout } = await gh(args);
@@ -3665,10 +3962,27 @@ function nodesToItems(nodes, warnings) {
   }
   return items;
 }
+function parseSingleSelectFields(nodes) {
+  const out = {};
+  for (const node of nodes ?? []) {
+    const fieldName = node.field?.name;
+    if (fieldName === "Status") {
+      const status = asBoardStatus(node.name);
+      if (status) out.status = { name: status, optionId: node.optionId };
+    } else if (fieldName === "Priority" && node.name) {
+      const priority = node.name;
+      if (["Urgent", "High", "Medium", "Low"].includes(priority)) {
+        out.priority = { name: priority, optionId: node.optionId };
+      }
+    }
+  }
+  return out;
+}
 function nodeToItem(node) {
   const content = node.content;
   if (!node.id || !isSupportedContent(content)) return void 0;
-  const status = asBoardStatus(node.fieldValueByName?.name);
+  const fields = parseSingleSelectFields(node.fieldValues?.nodes);
+  const status = fields.status?.name;
   const repository = content.repository?.nameWithOwner;
   if (!status || !content.id || !content.number || !content.title || !content.url || !repository) return void 0;
   const labels = (content.labels?.nodes ?? []).map((l) => l.name).filter((name) => Boolean(name));
@@ -3684,7 +3998,9 @@ function nodeToItem(node) {
     title: content.title,
     state: content.state ?? "",
     status,
-    statusOptionId: node.fieldValueByName?.optionId,
+    statusOptionId: fields.status?.optionId,
+    priority: fields.priority?.name,
+    priorityOptionId: fields.priority?.optionId,
     assignees,
     labels,
     type: labels.find((label) => TYPE_LABELS.includes(label)) ?? labels[0]
@@ -3743,7 +4059,8 @@ function renderTaken(lines, items) {
   for (const item of items) lines.push(`  ${item.ref} \xB7 ${item.status} \xB7 @${item.assignees.join(", @")}`);
 }
 function renderTitledItem(item) {
-  return `${item.ref} - [${item.type ?? "item"}] ${item.title}`;
+  const pri = item.priority ? ` \xB7 ${item.priority}` : "";
+  return `${item.ref} - [${item.type ?? "item"}]${pri} ${item.title}`;
 }
 function hasItems(buckets) {
   return buckets.userOwned.length > 0 || buckets.claimable.length > 0 || buckets.taken.length > 0;
@@ -3942,6 +4259,7 @@ function buildGithubAuthCheck(input) {
 var import_node_child_process3 = require("node:child_process");
 var import_node_fs2 = require("node:fs");
 var import_node_path2 = require("node:path");
+var import_node_net = require("node:net");
 var import_node_util2 = require("node:util");
 var execFileP2 = (0, import_node_util2.promisify)(import_node_child_process3.execFile);
 function stageStatePath(cwd = process.cwd()) {
@@ -3954,8 +4272,29 @@ function validateStageConfig(config = {}, action) {
   if (config.healthUrl != null && config.healthUrl.trim() && !/^https?:\/\//.test(config.healthUrl.trim())) {
     problems.push("stage.healthUrl must be an http(s) URL");
   }
+  if (config.portRange != null) {
+    const r = config.portRange;
+    const ok = Array.isArray(r) && r.length === 2 && r.every((n) => Number.isInteger(n) && n >= 1024 && n <= 65535) && r[0] <= r[1];
+    if (!ok) problems.push("stage.portRange must be [start, end] within 1024-65535 with start <= end");
+  }
   return problems;
 }
+function pickStagePort(range, isFree) {
+  if (!range) return void 0;
+  const [start, end] = range;
+  for (let port = start; port <= end; port++) {
+    if (isFree(port)) return port;
+  }
+  throw new Error(`no free stage port in range ${start}-${end} \u2014 every port is in use`);
+}
+function isPortFree(port) {
+  return new Promise((resolve) => {
+    const srv = (0, import_node_net.createServer)();
+    srv.once("error", () => resolve(false));
+    srv.once("listening", () => srv.close(() => resolve(true)));
+    srv.listen(port, "127.0.0.1");
+  });
+}
 async function shell(command, cwd, timeoutMs) {
   await execFileP2(command, [], {
     cwd,
@@ -4030,24 +4369,34 @@ async function startStage(config = {}, opts = {}) {
   const statePath = opts.statePath ?? stageStatePath(cwd);
   const dir = statePath.slice(0, Math.max(statePath.lastIndexOf("/"), statePath.lastIndexOf("\\")));
   (0, import_node_fs2.mkdirSync)(dir, { recursive: true });
-  const up = config.up.trim();
+  let stagePort;
+  if (config.portRange) {
+    const [s, e] = config.portRange;
+    const free = /* @__PURE__ */ new Set();
+    for (let p = s; p <= e; p++) if (await isPortFree(p)) free.add(p);
+    stagePort = pickStagePort(config.portRange, (p) => free.has(p));
+  }
+  const sub = (s) => s != null && stagePort != null ? s.replace(/\$\{?STAGE_PORT\}?/g, String(stagePort)) : s;
+  const up = sub(config.up.trim());
   const child = (0, import_node_child_process3.spawn)(up, {
     cwd,
     shell: true,
     detached: true,
     windowsHide: true,
-    stdio: "ignore"
+    stdio: "ignore",
+    env: stagePort != null ? { ...process.env, STAGE_PORT: String(stagePort) } : process.env
   });
   const state = {
     pid: child.pid ?? 0,
     command: up,
     cwd,
     startedAt: (opts.now ?? (() => /* @__PURE__ */ new Date()))().toISOString(),
-    healthUrl: config.healthUrl?.trim() || void 0
+    healthUrl: sub(config.healthUrl?.trim()) || void 0,
+    port: stagePort
   };
   (0, import_node_fs2.writeFileSync)(statePath, JSON.stringify(state, null, 2), "utf8");
   if (state.healthUrl) await waitForHealth(state.healthUrl, opts.timeoutMs ?? 6e4);
-  const result = { ok: true, action: "start", statePath, pid: state.pid, message: `started stage pid ${state.pid}` };
+  const result = { ok: true, action: "start", statePath, pid: state.pid, message: `started stage pid ${state.pid}${stagePort != null ? ` on port ${stagePort}` : ""}` };
   opts.onReady?.(result);
   child.unref();
   return result;
@@ -4063,6 +4412,190 @@ async function runStage(config = {}, opts = {}) {
   return { ...started, action: "run", message: `built and ${started.message}` };
 }
 
+// src/port-registry.ts
+var import_node_fs3 = require("node:fs");
+var BLOCK = 100;
+var SPAN = 10;
+var FIRST = 3e3;
+function nextPortBlock(registry) {
+  const bases = Object.values(registry).map(([start]) => start);
+  const base = bases.length ? Math.max(...bases) + BLOCK : FIRST;
+  return [base, base + SPAN];
+}
+function loadPortRegistry(path) {
+  if (!(0, import_node_fs3.existsSync)(path)) return {};
+  const raw = JSON.parse((0, import_node_fs3.readFileSync)(path, "utf8"));
+  const out = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (Array.isArray(value) && value.length === 2 && value.every((n) => typeof n === "number")) {
+      out[key] = [value[0], value[1]];
+    }
+  }
+  return out;
+}
+function ensurePortRange(repo, path) {
+  const registry = loadPortRegistry(path);
+  const existing = registry[repo];
+  if (existing) return existing;
+  const range = nextPortBlock(registry);
+  const raw = (0, import_node_fs3.existsSync)(path) ? JSON.parse((0, import_node_fs3.readFileSync)(path, "utf8")) : {};
+  raw[repo] = range;
+  (0, import_node_fs3.writeFileSync)(path, JSON.stringify(raw, null, 2) + "\n", "utf8");
+  return range;
+}
+
+// src/access.ts
+var OWNER = "mutmutco";
+var LOCKED_APP = "mmi-github-app";
+var OVERGRANT_ROLES = /* @__PURE__ */ new Set(["admin", "maintain"]);
+function lockedBranches(repoClass) {
+  return repoClass === "content" ? ["main"] : ["development", "rc", "main"];
+}
+function safeJson(text, fallback) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return fallback;
+  }
+}
+async function ghJson(deps, args, fallback) {
+  try {
+    return safeJson((await deps.gh(args)).stdout, fallback);
+  } catch {
+    return fallback;
+  }
+}
+async function resolveOwners(deps) {
+  const members = await ghJson(deps, ["api", `orgs/${OWNER}/members?role=admin`, "--paginate"], []);
+  return members.map((m) => m.login);
+}
+function collaboratorRole(c) {
+  return c.role_name ?? (c.permissions?.admin ? "admin" : c.permissions?.maintain ? "maintain" : "write");
+}
+async function auditRepoCollaborators(repo, owners, deps) {
+  const collabs = await ghJson(deps, ["api", `repos/${repo}/collaborators?affiliation=direct`, "--paginate"], []);
+  const findings = [];
+  for (const c of collabs) {
+    if (owners.has(c.login)) continue;
+    const role = collaboratorRole(c);
+    if (OVERGRANT_ROLES.has(role)) {
+      findings.push({
+        repo,
+        kind: "collaborator-overgrant",
+        severity: "high",
+        actor: c.login,
+        detail: `direct collaborator @${c.login} holds role '${role}'; a developer must be 'write' (admin/maintain is master-only)`,
+        remediation: `gh api -X PUT repos/${repo}/collaborators/${c.login} -f permission=push`
+      });
+    }
+  }
+  return findings;
+}
+async function auditTrainBranch(repo, branch, owners, deps, projectAdmins = /* @__PURE__ */ new Set()) {
+  let restrictions = null;
+  try {
+    restrictions = safeJson((await deps.gh(["api", `repos/${repo}/branches/${branch}/protection/restrictions`])).stdout, null);
+  } catch {
+    restrictions = null;
+  }
+  if (!restrictions) {
+    return [{
+      repo,
+      branch,
+      kind: "unprotected-branch",
+      severity: "medium",
+      detail: `${branch} has no push restrictions (branch unprotected, or protection without a user/app allowlist)`,
+      remediation: `initialize the lock \u2014 see docs/Guides/repo-access.md "Initialize the lock"; PUT repos/${repo}/branches/${branch}/protection with restrictions {users:[<owners>], apps:["${LOCKED_APP}"]}`
+    }];
+  }
+  const findings = [];
+  const users = (restrictions.users ?? []).map((u) => u.login);
+  for (const login of users) {
+    if (!owners.has(login) && !projectAdmins.has(login)) {
+      findings.push({
+        repo,
+        branch,
+        kind: "train-allowlist-extra",
+        severity: "medium",
+        actor: login,
+        detail: `@${login} is on the ${branch} push allowlist \u2014 legitimate only if an intended full-write project-admin; confirm`,
+        remediation: `# if NOT an intended full-write member: gh api -X DELETE repos/${repo}/branches/${branch}/protection/restrictions/users --input - <<< '["${login}"]'`
+      });
+    }
+  }
+  for (const owner of owners) {
+    if (!users.includes(owner)) {
+      findings.push({
+        repo,
+        branch,
+        kind: "train-allowlist-missing",
+        severity: "medium",
+        actor: owner,
+        detail: `org owner @${owner} is missing from the ${branch} push allowlist`,
+        remediation: `gh api -X POST repos/${repo}/branches/${branch}/protection/restrictions/users --input - <<< '["${owner}"]'`
+      });
+    }
+  }
+  const apps = (restrictions.apps ?? []).map((a) => a.slug);
+  if (!apps.includes(LOCKED_APP)) {
+    findings.push({
+      repo,
+      branch,
+      kind: "app-bypass-missing",
+      severity: "high",
+      detail: `the ${LOCKED_APP} App is missing from the ${branch} allowlist \u2014 fanout/promotions will break`,
+      remediation: `gh api -X POST repos/${repo}/branches/${branch}/protection/restrictions/apps --input - <<< '["${LOCKED_APP}"]'`
+    });
+  }
+  return findings;
+}
+async function auditRepoAccess(repo, repoClass, owners, deps, projectAdmins = /* @__PURE__ */ new Set()) {
+  const findings = [];
+  findings.push(...await auditRepoCollaborators(repo, owners, deps));
+  for (const branch of lockedBranches(repoClass)) {
+    findings.push(...await auditTrainBranch(repo, branch, owners, deps, projectAdmins));
+  }
+  return { repo, class: repoClass, ok: !findings.some((f) => f.severity === "high"), findings };
+}
+async function auditOrgAccess(targets, deps, matrix = {}) {
+  const owners = new Set(await resolveOwners(deps));
+  const repos = [];
+  for (const target of targets) {
+    repos.push(await auditRepoAccess(target.repo, target.class, owners, deps, new Set(matrix[target.repo] ?? [])));
+  }
+  return { ok: repos.every((r) => r.ok), owners: [...owners], repos };
+}
+function loadAccessTargets(projectsJson, fanoutJson) {
+  const projects = safeJson(projectsJson, {}).projects ?? [];
+  const fanout = fanoutJson ? safeJson(fanoutJson, {}).repos ?? [] : [];
+  const contentNames = new Set(fanout.filter((r) => r.class === "content").map((r) => r.repo));
+  const seen = /* @__PURE__ */ new Set();
+  const targets = [];
+  for (const project of projects) {
+    for (const repo of project.repos ?? []) {
+      if (seen.has(repo)) continue;
+      seen.add(repo);
+      targets.push({ repo, class: contentNames.has(repo.split("/")[1]) ? "content" : "deployable" });
+    }
+  }
+  return targets;
+}
+function loadAccessMatrix(matrixJson) {
+  if (!matrixJson) return {};
+  return safeJson(matrixJson, {}).projectAdmins ?? {};
+}
+function renderAccessReport(report) {
+  const lines = [`mmi-cli access audit: ${report.ok ? "OK" : "CHECK"} (owners: ${report.owners.map((o) => "@" + o).join(", ") || "none"})`];
+  for (const repo of report.repos) {
+    lines.push(`${repo.ok ? "OK" : "FLAG"} ${repo.repo} (${repo.class})`);
+    for (const finding of repo.findings) {
+      lines.push(`  [${finding.severity}] ${finding.kind}${finding.branch ? ` @${finding.branch}` : ""}: ${finding.detail}`);
+      if (finding.remediation) lines.push(`      ${finding.remediation}`);
+    }
+  }
+  return lines.join("\n");
+}
+
 // src/bootstrap-verify.ts
 var requiredDocs = ["README.md", "architecture.md", "AGENTS.md", "CLAUDE.md", ".claude/settings.json", ".mmi/config.json"];
 var requiredIssueTemplates = [
@@ -4072,7 +4605,9 @@ var requiredIssueTemplates = [
   ".github/ISSUE_TEMPLATE/config.yml"
 ];
 var requiredWorkflows = [".github/workflows/pr-to-board.yml"];
-var requiredLabels = ["bug", "feature", "task", "priority:high", "priority:medium", "priority:low"];
+var requiredLabels = ["bug", "feature", "task", "priority:urgent", "priority:high", "priority:medium", "priority:low"];
+var requiredPriorityOptions = ["Urgent", "High", "Medium", "Low"];
+var strayDefaultLabels = ["documentation", "duplicate", "enhancement", "good first issue", "help wanted", "invalid", "question", "wontfix"];
 var requiredStatusOptions = ["Todo", "In Progress", "In Review", "Done"];
 var requiredProjectWorkflows = [
   "Auto-add sub-issues to project",
@@ -4087,16 +4622,16 @@ var requiredActionsSecrets = ["MMI_APP_PRIVATE_KEY"];
 function expectedBranches(repoClass) {
   return repoClass === "content" ? ["main"] : ["development", "rc", "main"];
 }
-function safeJson(text, fallback) {
+function safeJson2(text, fallback) {
   try {
     return JSON.parse(text);
   } catch {
     return fallback;
   }
 }
-async function ghJson(deps, args, fallback) {
+async function ghJson2(deps, args, fallback) {
   try {
-    return safeJson((await deps.gh(args)).stdout, fallback);
+    return safeJson2((await deps.gh(args)).stdout, fallback);
   } catch {
     return fallback;
   }
@@ -4113,7 +4648,7 @@ async function contentExists(deps, repo, branch, path) {
 async function contentText(deps, repo, branch, path) {
   try {
     const encodedPath = path.split("/").map(encodeURIComponent).join("/");
-    const response = safeJson(
+    const response = safeJson2(
       (await deps.gh(["api", `repos/${repo}/contents/${encodedPath}?ref=${encodeURIComponent(branch)}`])).stdout,
       {}
     );
@@ -4124,36 +4659,51 @@ async function contentText(deps, repo, branch, path) {
     return null;
   }
 }
-async function protectedBranch(deps, repo, branch) {
+async function getProtection(deps, repo, branch) {
   try {
-    await deps.gh(["api", `repos/${repo}/branches/${branch}/protection`]);
-    return true;
+    return safeJson2((await deps.gh(["api", `repos/${repo}/branches/${branch}/protection`])).stdout, {});
   } catch {
-    return false;
+    return null;
   }
 }
+function hasPushAllowlist(p) {
+  return Array.isArray(p?.restrictions?.users) && p.restrictions.users.length > 0;
+}
 function optionDetail(missing) {
   return missing.length === 0 ? void 0 : `missing: ${missing.join(", ")}`;
 }
 function localRegistryCheck(deps, path, predicate) {
   const text = deps.readLocalFile?.(path);
   if (text == null) return null;
-  return predicate(safeJson(text, null));
+  return predicate(safeJson2(text, null));
 }
 async function verifyBootstrap(repo, repoClass, deps) {
   const branchesWanted = expectedBranches(repoClass);
   const baseBranch = repoClass === "content" ? "main" : "development";
   const checks = [];
-  const repoInfo = await ghJson(deps, ["api", `repos/${repo}`], {});
+  const repoInfo = await ghJson2(deps, ["api", `repos/${repo}`], {});
   checks.push({ ok: Boolean(repoInfo.default_branch), label: "repo exists" });
   checks.push({ ok: repoInfo.default_branch === baseBranch, label: `default branch is ${baseBranch}`, detail: repoInfo.default_branch || "missing" });
   checks.push({ ok: repoInfo.has_wiki === true, label: "wiki enabled", detail: repoInfo.has_wiki === true ? void 0 : "has_wiki is false or unavailable" });
-  const branchList = await ghJson(deps, ["api", `repos/${repo}/branches`, "--paginate"], []);
+  const branchList = await ghJson2(deps, ["api", `repos/${repo}/branches`, "--paginate"], []);
   const branchNames = new Set(branchList.map((b) => b.name));
   for (const branch of branchesWanted) {
     checks.push({ ok: branchNames.has(branch), label: `branch exists: ${branch}` });
-    checks.push({ ok: await protectedBranch(deps, repo, branch), label: `branch protection exists: ${branch}` });
+    const protection = await getProtection(deps, repo, branch);
+    checks.push({ ok: protection != null, label: `branch protection exists: ${branch}` });
+    checks.push({
+      ok: hasPushAllowlist(protection),
+      label: `push allowlist configured: ${branch}`,
+      detail: hasPushAllowlist(protection) ? void 0 : "restrictions.users is empty or unset"
+    });
   }
+  const owners = new Set(await resolveOwners(deps));
+  const overgrants = await auditRepoCollaborators(repo, owners, deps);
+  checks.push({
+    ok: overgrants.length === 0,
+    label: "collaborator roles are master-only (no admin/maintain over-grant)",
+    detail: overgrants.length ? `over-granted: ${overgrants.map((f) => f.actor).join(", ")}` : void 0
+  });
   for (const path of requiredDocs) {
     checks.push({ ok: await contentExists(deps, repo, baseBranch, path), label: `bootstrap artifact exists: ${path}` });
   }
@@ -4163,31 +4713,37 @@ async function verifyBootstrap(repo, repoClass, deps) {
   for (const path of requiredWorkflows) {
     checks.push({ ok: await contentExists(deps, repo, baseBranch, path), label: `automation workflow exists: ${path}` });
   }
+  if (repoClass === "deployable") {
+    const trainScript = "scripts/next-version.mjs";
+    checks.push({ ok: await contentExists(deps, repo, baseBranch, trainScript), label: `train tooling script exists: ${trainScript}` });
+  }
   checks.push({ ok: await contentExists(deps, repo, baseBranch, ".cursor/environment.json"), label: "Cursor environment committed" });
-  const labels = await ghJson(deps, ["label", "list", "--repo", repo, "--limit", "200", "--json", "name"], []);
+  const labels = await ghJson2(deps, ["label", "list", "--repo", repo, "--limit", "200", "--json", "name"], []);
   const labelNames = new Set(labels.map((l) => l.name));
   for (const label of requiredLabels) {
     checks.push({ ok: labelNames.has(label), label: `label exists: ${label}` });
   }
-  const actions = await ghJson(deps, ["api", `repos/${repo}/actions/permissions`], {});
+  const strays = strayDefaultLabels.filter((l) => labelNames.has(l));
+  checks.push({ ok: strays.length === 0, label: "no stray GitHub-default labels", detail: optionDetail(strays) });
+  const actions = await ghJson2(deps, ["api", `repos/${repo}/actions/permissions`], {});
   checks.push({ ok: actions.enabled === true, label: "GitHub Actions enabled" });
-  const variables = await ghJson(deps, ["variable", "list", "--repo", repo, "--json", "name"], []);
+  const variables = await ghJson2(deps, ["variable", "list", "--repo", repo, "--json", "name"], []);
   const variableNames = new Set(variables.map((v) => v.name));
   for (const variable of requiredActionsVariables) {
     checks.push({ ok: variableNames.has(variable), label: `Actions variable exists: ${variable}` });
   }
-  const secrets = await ghJson(deps, ["secret", "list", "--repo", repo, "--json", "name"], []);
-  const secretNames = new Set(secrets.map((s) => s.name));
+  const secrets2 = await ghJson2(deps, ["secret", "list", "--repo", repo, "--json", "name"], []);
+  const secretNames = new Set(secrets2.map((s) => s.name));
   for (const secret of requiredActionsSecrets) {
     checks.push({ ok: secretNames.has(secret), label: `Actions secret exists: ${secret}` });
   }
-  const config = safeJson(await contentText(deps, repo, baseBranch, ".mmi/config.json") || "", null);
+  const config = safeJson2(await contentText(deps, repo, baseBranch, ".mmi/config.json") || "", null);
   checks.push({
     ok: Boolean(config?.projectOwner && config?.projectNumber),
     label: ".mmi project board config exists"
   });
   if (config?.projectOwner && config.projectNumber != null) {
-    const project = await ghJson(
+    const project = await ghJson2(
       deps,
       ["project", "field-list", String(config.projectNumber), "--owner", config.projectOwner, "--format", "json"],
       {}
@@ -4223,8 +4779,33 @@ async function verifyBootstrap(repo, repoClass, deps) {
         });
       }
     }
+    const priorityField = fields.find((field) => field.name === "Priority" && (field.options?.length ?? 0) > 0);
+    checks.push({
+      ok: Boolean(priorityField),
+      label: `Project Priority field exists (API-writable): ${config.projectOwner}#${config.projectNumber}`
+    });
+    if (priorityField != null) {
+      const priorityNames = new Set((priorityField.options || []).map((option) => option.name));
+      const missingPriority = requiredPriorityOptions.filter((option) => !priorityNames.has(option));
+      checks.push({
+        ok: missingPriority.length === 0,
+        label: "Project Priority options configured",
+        detail: optionDetail(missingPriority)
+      });
+      checks.push({
+        ok: config.priorityFieldId === priorityField.id,
+        label: ".mmi priorityFieldId matches project"
+      });
+      for (const optionName of requiredPriorityOptions) {
+        const projectOption = priorityField.options?.find((option) => option.name === optionName);
+        checks.push({
+          ok: Boolean(projectOption?.id && config.priorityOptions?.[optionName] === projectOption.id),
+          label: `.mmi priority option matches project: ${optionName}`
+        });
+      }
+    }
     const workflowQuery = "query($login: String!, $number: Int!) { organization(login: $login) { projectV2(number: $number) { workflows(first: 30) { nodes { name enabled } } } } }";
-    const workflowResponse = await ghJson(
+    const workflowResponse = await ghJson2(
       deps,
       ["api", "graphql", "-f", `query=${workflowQuery}`, "-f", `login=${config.projectOwner}`, "-F", `number=${config.projectNumber}`],
       {}
@@ -4241,15 +4822,139 @@ async function verifyBootstrap(repo, repoClass, deps) {
   if (fanout != null) checks.push({ ok: fanout, label: `fanout target registered on ${baseBranch}` });
   const projectRegistry = localRegistryCheck(deps, "projects.json", (json) => Array.isArray(json?.projects) && json.projects.some((p) => (p.repos || []).includes(repo)));
   if (projectRegistry != null) checks.push({ ok: projectRegistry, label: "cloud-agent project registry includes repo" });
-  return { ok: checks.every((c) => c.ok), repo, class: repoClass, baseBranch, checks };
+  const rulesets = await ghJson2(
+    deps,
+    ["api", `repos/${repo}/rulesets?includes_parents=true`],
+    []
+  );
+  const orgRuleset = rulesets.some(
+    (r) => r.source_type === "Organization" && r.target === "branch" && r.enforcement === "active"
+  );
+  checks.push({
+    ok: orgRuleset,
+    label: "covered by an active org ruleset",
+    detail: orgRuleset ? void 0 : "no active Organization-sourced branch ruleset targets this repo"
+  });
+  const waived = applyWaivers(checks, config?.verifyWaivers ?? []);
+  return { ok: waived.every((c) => c.ok || c.waived), repo, class: repoClass, baseBranch, checks: waived };
+}
+function applyWaivers(checks, waivers) {
+  if (!waivers?.length) return checks;
+  const set = new Set(waivers);
+  return checks.map((c) => !c.ok && set.has(c.label) ? { ...c, waived: true } : c);
 }
 function renderBootstrapVerifyReport(report) {
   const lines = [`mmi-cli bootstrap verify: ${report.ok ? "OK" : "CHECK"} ${report.repo} (${report.class}, ${report.baseBranch})`];
   for (const check of report.checks) {
-    lines.push(`${check.ok ? "OK" : "FAIL"} ${check.label}${check.detail ? ` - ${check.detail}` : ""}`);
+    const status = check.ok ? "OK" : check.waived ? "WAIVE" : "FAIL";
+    lines.push(`${status} ${check.label}${check.detail ? ` - ${check.detail}` : ""}`);
+  }
+  return lines.join("\n");
+}
+
+// src/bootstrap-seeds.ts
+var PLACEHOLDER_RE = /\{\{([A-Z0-9_]+)\}\}/g;
+function loadBootstrapSeeds(manifestJson) {
+  let parsed;
+  try {
+    parsed = JSON.parse(manifestJson);
+  } catch {
+    throw new Error("bootstrap seed manifest is not valid JSON");
+  }
+  const obj = parsed ?? {};
+  const seeds = obj.seeds ?? [];
+  for (const s of seeds) {
+    if (!s || !s.target || !s.source || !Array.isArray(s.classes)) {
+      throw new Error(`invalid seed entry (needs target, source, classes): ${JSON.stringify(s)}`);
+    }
+    if (s.ownership !== "org" && s.ownership !== "repo") {
+      throw new Error(`invalid seed ownership '${s.ownership}' for ${s.target} (must be 'org' or 'repo')`);
+    }
+  }
+  return {
+    seeds,
+    labels: obj.labels ?? [],
+    placeholders: obj.placeholders ?? []
+  };
+}
+function renderSeed(template, vars) {
+  return template.replace(PLACEHOLDER_RE, (match, key) => key in vars ? vars[key] : match);
+}
+function missingPlaceholders(rendered) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of rendered.matchAll(PLACEHOLDER_RE)) out.add(m[1]);
+  return [...out];
+}
+
+// src/bootstrap-apply.ts
+function planSeedAction(seed, exists) {
+  if (seed.source === "fanout") {
+    return { target: seed.target, action: "skip", ownership: "fanout", reason: "delivered by the fanout pipeline" };
+  }
+  if (seed.ownership === "repo") {
+    return exists ? { target: seed.target, action: "skip", ownership: "repo", reason: "repo-owned, already present (never clobbered)" } : { target: seed.target, action: "create", ownership: "repo", reason: "repo-owned, missing" };
   }
+  return exists ? { target: seed.target, action: "update", ownership: "org", reason: "org-owned, refresh to current" } : { target: seed.target, action: "create", ownership: "org", reason: "org-owned, missing" };
+}
+function renderSeedPlan(actions) {
+  const lines = ["bootstrap apply \u2014 seed plan (dry-run; no mutations):"];
+  for (const a of actions) {
+    lines.push(`  ${a.action.toUpperCase().padEnd(6)} ${a.target}  (${a.ownership}: ${a.reason})`);
+  }
+  const order = ["create", "update", "skip"];
+  lines.push(`  \u2014 ${order.map((k) => `${actions.filter((a) => a.action === k).length} ${k}`).join(", ")}`);
   return lines.join("\n");
 }
+function resolveSeedContent(seed, vars, readFile2) {
+  if (seed.source === "self") return readFile2(seed.target);
+  if (seed.source.startsWith("seed:")) {
+    const tmpl = readFile2(`skills/bootstrap/seeds/${seed.source.slice("seed:".length)}`);
+    return tmpl == null ? null : renderSeed(tmpl, vars);
+  }
+  return null;
+}
+function contentPutArgs(repo, path, content, branch, sha) {
+  const args = [
+    "api",
+    "-X",
+    "PUT",
+    `repos/${repo}/contents/${path.split("/").map(encodeURIComponent).join("/")}`,
+    "-f",
+    `message=bootstrap: seed ${path}`,
+    "-f",
+    `content=${Buffer.from(content, "utf8").toString("base64")}`,
+    "-f",
+    `branch=${branch}`
+  ];
+  if (sha) args.push("-f", `sha=${sha}`);
+  return args;
+}
+
+// src/kb.ts
+var DEFAULT_KB = { owner: "mutmutco", repo: "MM-KB", ref: "main" };
+function resolveKbSource(rawBase) {
+  if (!rawBase) return DEFAULT_KB;
+  const m = rawBase.match(/raw\.githubusercontent\.com\/([^/]+)\/([^/]+)\/([^/?#]+)/);
+  if (!m) return DEFAULT_KB;
+  return { owner: m[1], repo: m[2], ref: m[3] };
+}
+function buildKbGetArgs(src, path) {
+  const clean = path.replace(/^\/+/, "");
+  return ["api", `repos/${src.owner}/${src.repo}/contents/${clean}?ref=${src.ref}`, "-H", "Accept: application/vnd.github.raw"];
+}
+function buildKbTreeArgs(src) {
+  return ["api", `repos/${src.owner}/${src.repo}/git/trees/${src.ref}?recursive=1`];
+}
+function parseKbTree(stdout, prefix) {
+  let tree;
+  try {
+    tree = JSON.parse(stdout)?.tree ?? [];
+  } catch {
+    return [];
+  }
+  const pre = prefix ? prefix.replace(/^\/+/, "") : void 0;
+  return tree.filter((t) => t.type === "blob" && typeof t.path === "string" && t.path.startsWith("kb/")).map((t) => t.path).filter((p) => pre ? p.startsWith(pre) : true).sort();
+}
 
 // src/plan.ts
 var import_node_path3 = require("node:path");
@@ -4391,8 +5096,178 @@ async function planDelete(deps, slug, opts = {}) {
   deps.log(`deleted ${slug}`);
 }
 
+// src/secrets.ts
+var OWNER2 = "mutmutco";
+var SSM_ROOT = "/mmi-future";
+var PROJECT_TIER_SEGMENT = "dev";
+var KEY_RE = /^(?:[a-z][a-z0-9-]*\/)?[A-Za-z][A-Za-z0-9_]*$/;
+function isValidSecretKey(key) {
+  if (!key || key.length > 256) return false;
+  if (key.includes("..") || key.startsWith("/") || key.includes("*")) return false;
+  return KEY_RE.test(key);
+}
+function classifyTier(_slug, key) {
+  const slash = key.indexOf("/");
+  if (slash === -1) return "project";
+  return key.slice(0, slash) === PROJECT_TIER_SEGMENT ? "project" : "org";
+}
+function secretParamName(slug, key) {
+  const rel = key.includes("/") ? key : `${PROJECT_TIER_SEGMENT}/${key}`;
+  return `${SSM_ROOT}/${slug}/${rel}`;
+}
+function formatSecretList(items) {
+  if (!items.length) return "no secrets";
+  const width = Math.max(...items.map((i) => i.key.length));
+  return items.map((i) => `${i.canManage ? "*" : " "} ${i.key.padEnd(width)}  ${i.tier}`).join("\n").concat("\n\n* = you can manage (write/rotate) this secret. Values are never shown \u2014 `secrets get <KEY>` prints one.");
+}
+var TIMEOUT_MS2 = 8e3;
+var repoOf = (slug) => `${OWNER2}/${slug}`;
+async function targetRepo(deps, opts) {
+  return opts.repo ?? repoOf(await deps.slug());
+}
+async function readErr(res) {
+  try {
+    const j = await res.json();
+    return j?.error ? `: ${j.error}` : "";
+  } catch {
+    return "";
+  }
+}
+async function secretsList(deps, opts) {
+  const repo = await targetRepo(deps, opts);
+  const qs = new URLSearchParams({ repo }).toString();
+  let res;
+  try {
+    res = await deps.fetch(`${deps.apiUrl}/secrets/list?${qs}`, {
+      method: "GET",
+      headers: await deps.headers(),
+      signal: AbortSignal.timeout(TIMEOUT_MS2)
+    });
+  } catch (e) {
+    deps.err(`secrets list: ${e.message}`);
+    return;
+  }
+  if (!res.ok) {
+    deps.err(`secrets list failed: HTTP ${res.status}${await readErr(res)}`);
+    return;
+  }
+  const { secrets: secrets2 } = await res.json();
+  deps.log(formatSecretList(secrets2 ?? []));
+}
+async function secretsGet(deps, key, opts) {
+  if (!isValidSecretKey(key)) return deps.err(`invalid secret key ${JSON.stringify(key)}`);
+  const repo = await targetRepo(deps, opts);
+  const res = await deps.fetch(`${deps.apiUrl}/secrets/get`, {
+    method: "POST",
+    headers: await deps.headers({ "content-type": "application/json" }),
+    body: JSON.stringify({ repo, key }),
+    signal: AbortSignal.timeout(TIMEOUT_MS2)
+  });
+  if (!res.ok) {
+    deps.err(
+      res.status === 403 ? `secrets get: not authorized for ${key} (HTTP 403)${await readErr(res)}` : `secrets get failed: HTTP ${res.status}${await readErr(res)}`
+    );
+    return;
+  }
+  const { value } = await res.json();
+  deps.log(value ?? "");
+}
+async function secretsSet(deps, key, opts) {
+  if (!isValidSecretKey(key)) return deps.err(`invalid secret key ${JSON.stringify(key)}`);
+  const repo = await targetRepo(deps, opts);
+  const value = await deps.readSecretValue(`value for ${key} (input hidden; will not be echoed): `);
+  if (!value) {
+    deps.err("secrets set: empty value \u2014 aborted (nothing written)");
+    return;
+  }
+  const res = await deps.fetch(`${deps.apiUrl}/secrets/set`, {
+    method: "POST",
+    headers: await deps.headers({ "content-type": "application/json" }),
+    body: JSON.stringify({ repo, key, value }),
+    signal: AbortSignal.timeout(TIMEOUT_MS2)
+  });
+  if (!res.ok) {
+    deps.err(
+      res.status === 403 ? `secrets set: not authorized to write ${key} (HTTP 403)${await readErr(res)}` : `secrets set failed: HTTP ${res.status}${await readErr(res)}`
+    );
+    return;
+  }
+  deps.log(`set ${key} (${classifyTier(await deps.slug(), key)} tier)`);
+}
+async function secretsEdit(deps, key, opts) {
+  return secretsSet(deps, key, opts);
+}
+async function secretsRemove(deps, key, opts) {
+  if (!isValidSecretKey(key)) return deps.err(`invalid secret key ${JSON.stringify(key)}`);
+  const repo = await targetRepo(deps, opts);
+  const res = await deps.fetch(`${deps.apiUrl}/secrets/rm`, {
+    method: "POST",
+    headers: await deps.headers({ "content-type": "application/json" }),
+    body: JSON.stringify({ repo, key }),
+    signal: AbortSignal.timeout(TIMEOUT_MS2)
+  });
+  if (!res.ok) {
+    deps.err(
+      res.status === 403 ? `secrets rm: not authorized to remove ${key} (HTTP 403)${await readErr(res)}` : `secrets rm failed: HTTP ${res.status}${await readErr(res)}`
+    );
+    return;
+  }
+  deps.log(`removed ${key}`);
+}
+async function secretsGrant(deps, repo, login, key, _opts) {
+  const res = await deps.fetch(`${deps.apiUrl}/secrets/grant`, {
+    method: "POST",
+    headers: await deps.headers({ "content-type": "application/json" }),
+    body: JSON.stringify({ repo, login, key }),
+    signal: AbortSignal.timeout(TIMEOUT_MS2)
+  });
+  if (!res.ok) {
+    deps.err(
+      res.status === 403 ? `secrets grant: master-admin only (HTTP 403)${await readErr(res)}` : `secrets grant failed: HTTP ${res.status}${await readErr(res)}`
+    );
+    return;
+  }
+  deps.log(`granted @${login} access to ${key} in ${repo}`);
+}
+async function secretsRevoke(deps, repo, login, key, _opts) {
+  const res = await deps.fetch(`${deps.apiUrl}/secrets/revoke`, {
+    method: "POST",
+    headers: await deps.headers({ "content-type": "application/json" }),
+    body: JSON.stringify({ repo, login, key }),
+    signal: AbortSignal.timeout(TIMEOUT_MS2)
+  });
+  if (!res.ok) {
+    deps.err(
+      res.status === 403 ? `secrets revoke: master-admin only (HTTP 403)${await readErr(res)}` : `secrets revoke failed: HTTP ${res.status}${await readErr(res)}`
+    );
+    return;
+  }
+  deps.log(`revoked @${login}'s access to ${key} in ${repo}`);
+}
+async function secretsUse(deps, key, _opts) {
+  const slug = await deps.slug();
+  const tier = classifyTier(slug, key);
+  const path = secretParamName(slug, key);
+  deps.log(
+    [
+      `${key} \u2192 ${path} (${tier} tier)`,
+      "",
+      "Consume it WITHOUT committing it:",
+      `  \u2022 Runtime / agents: read it keylessly at runtime via the box's OIDC role (it can read its own ${tier} tier). Never bake it into an image or commit it.`,
+      `  \u2022 CI (GitHub Actions): the workflow assumes its OIDC role and runs \`aws ssm get-parameter --with-decryption --name ${path}\` \u2014 no GitHub secret.`,
+      "  \u2022 Local dev: pull it into a gitignored .env from the vault \u2014 `mmi-cli secrets get " + key + " > /dev/null` to confirm access, then export it in your shell. Never paste it into tracked files or chat.",
+      tier === "project" ? "  \u2022 If this dev secret graduates to a real prod credential, ask the master to promote it to the org tier (rc/ or main/)." : "  \u2022 This is an ORG-tier secret \u2014 master-gated. If you need standing access, ask the master for a `secrets grant`."
+    ].join("\n")
+  );
+}
+
 // src/index.ts
-var execFileP3 = (0, import_node_util3.promisify)(import_node_child_process4.execFile);
+var rawExecFileP2 = (0, import_node_util3.promisify)(import_node_child_process4.execFile);
+var execFileP3 = (file, args, options = {}) => (
+  // encoding 'utf8' guarantees string stdout/stderr at runtime; the cast pins the type because
+  // promisify(execFile)'s overloads widen to string|Buffer when options is spread in.
+  rawExecFileP2(file, args, { encoding: "utf8", windowsHide: true, ...options })
+);
 var GIT_TIMEOUT_MS = 1e4;
 var GC_GH_TIMEOUT_MS = 2e4;
 async function githubToken() {
@@ -4425,7 +5300,6 @@ async function loadConfig() {
   }
 }
 var DEFAULT_RULES_SOURCE = "https://raw.githubusercontent.com/mutmutco/MMI-Hub/development";
-var DEFAULT_KB_SOURCE = "https://raw.githubusercontent.com/mutmutco/MM-KB/main";
 var SESSION_FILE = ".mmi/.session";
 var gitOut = async (args) => {
   try {
@@ -4439,7 +5313,7 @@ function sessionDeps() {
     env: process.env,
     readPersisted: () => {
       try {
-        return (0, import_node_fs3.readFileSync)(SESSION_FILE, "utf8");
+        return (0, import_node_fs4.readFileSync)(SESSION_FILE, "utf8");
       } catch {
         return null;
       }
@@ -4452,8 +5326,8 @@ function sessionDeps() {
 var resolveSessionId = () => resolveSession(sessionDeps());
 function persistSession(id) {
   try {
-    (0, import_node_fs3.mkdirSync)(".mmi", { recursive: true });
-    (0, import_node_fs3.writeFileSync)(SESSION_FILE, id, "utf8");
+    (0, import_node_fs4.mkdirSync)(".mmi", { recursive: true });
+    (0, import_node_fs4.writeFileSync)(SESSION_FILE, id, "utf8");
   } catch {
   }
 }
@@ -4473,7 +5347,11 @@ async function postCapture(capture, quiet = false) {
       method: "POST",
       headers: await sagaHeaders({ "content-type": "application/json" }),
       body: JSON.stringify({ ...capture, ...await sagaKey(cfg) }),
-      signal: AbortSignal.timeout(8e3)
+      // Capture latency is high + variable (server-side HEAD render); 8s dropped larger notes. Match the
+      // head-write timeout (20s) so a continuity note isn't lost to a slow/cold backend. No client retry:
+      // the capture isn't guaranteed idempotent, so a retry after a server-side-completed write could
+      // duplicate the note. Backend capture-latency root cause tracked in #255.
+      signal: AbortSignal.timeout(2e4)
     });
     if (!quiet) console.log(res.ok ? "noted" : `saga: HTTP ${res.status}`);
   } catch (e) {
@@ -4537,14 +5415,35 @@ async function applyGcPlan(plan2, remote) {
     await execFileP3("git", ["worktree", "prune"], { timeout: GIT_TIMEOUT_MS });
   }
 }
+async function cleanupLocalBranch(branch) {
+  const result = { branchDeleted: false };
+  if (!branch) return result;
+  const { stdout } = await execFileP3("git", ["worktree", "list", "--porcelain"], { timeout: GIT_TIMEOUT_MS });
+  const wt = parseWorktreePorcelain(stdout).find((w) => w.branch === branch);
+  if (wt) {
+    await execFileP3("git", ["worktree", "remove", "--force", wt.path], { timeout: GIT_TIMEOUT_MS }).catch(() => {
+    });
+    result.worktreeRemoved = wt.path;
+  }
+  const current = await gitOut(["rev-parse", "--abbrev-ref", "HEAD"]) || "";
+  if (branch !== current) {
+    await execFileP3("git", ["branch", "-D", branch], { timeout: GIT_TIMEOUT_MS }).then(() => {
+      result.branchDeleted = true;
+    }).catch(() => {
+    });
+  }
+  if (wt) await execFileP3("git", ["worktree", "prune"], { timeout: GIT_TIMEOUT_MS }).catch(() => {
+  });
+  return result;
+}
 function resolveVersion() {
   try {
     const manifest = (0, import_node_path4.join)(__dirname, "..", "..", ".claude-plugin", "plugin.json");
-    return JSON.parse((0, import_node_fs3.readFileSync)(manifest, "utf8")).version || "0.0.0";
+    return JSON.parse((0, import_node_fs4.readFileSync)(manifest, "utf8")).version || "0.0.0";
   } catch {
     try {
       const pkg = (0, import_node_path4.join)(__dirname, "..", "package.json");
-      return JSON.parse((0, import_node_fs3.readFileSync)(pkg, "utf8")).version || "0.0.0";
+      return JSON.parse((0, import_node_fs4.readFileSync)(pkg, "utf8")).version || "0.0.0";
     } catch {
       return "0.0.0";
     }
@@ -4552,7 +5451,7 @@ function resolveVersion() {
 }
 function readRepoVersion() {
   try {
-    return JSON.parse((0, import_node_fs3.readFileSync)((0, import_node_path4.join)(process.cwd(), ".claude-plugin", "plugin.json"), "utf8")).version || void 0;
+    return JSON.parse((0, import_node_fs4.readFileSync)((0, import_node_path4.join)(process.cwd(), ".claude-plugin", "plugin.json"), "utf8")).version || void 0;
   } catch {
     return void 0;
   }
@@ -4568,6 +5467,31 @@ async function fetchReleasedVersion() {
     return void 0;
   }
 }
+var NPM_UPDATE_TIMEOUT_MS = 12e4;
+var PLUGIN_PULL_TIMEOUT_MS = 3e4;
+async function applyVersionAutoUpdate(report, log) {
+  const action = versionAutoUpdateAction(report, Boolean(process.env.CLAUDE_PLUGIN_ROOT));
+  if (action === "none") return report;
+  const target = report.releasedVersion ?? "latest";
+  if (action === "plugin-pull") {
+    try {
+      const root = (await execFileP3("git", ["-C", process.env.CLAUDE_PLUGIN_ROOT, "rev-parse", "--show-toplevel"], { timeout: PLUGIN_PULL_TIMEOUT_MS })).stdout.trim();
+      log(`  \u21BB refreshing MMI plugin ${report.currentVersion} \u2192 ${target} (effective next session)\u2026`);
+      await execFileP3("git", ["-C", root, "pull", "--ff-only"], { timeout: PLUGIN_PULL_TIMEOUT_MS });
+      return { ...report, ok: true };
+    } catch {
+      return report;
+    }
+  }
+  try {
+    const npm = process.platform === "win32" ? "npm.cmd" : "npm";
+    log(`  \u21BB updating mmi-cli ${report.currentVersion} \u2192 ${target}\u2026`);
+    await execFileP3(npm, ["install", "-g", "@mutmutco/cli@latest"], { timeout: NPM_UPDATE_TIMEOUT_MS });
+    return { ...report, ok: true };
+  } catch {
+    return report;
+  }
+}
 var program2 = new Command();
 program2.name("mmi-cli").description("MMI Future CLI \u2014 org rules delivery, saga, KB. The engine the plugin SessionStart hook drives.").version(resolveVersion());
 var rules = program2.command("rules").description("org rules delivery");
@@ -4591,10 +5515,10 @@ rules.command("sync").option("--quiet", "stay silent unless something changed or
       if (!opts.quiet) console.error(`mmi-cli rules: could not fetch ${file} (${e.message}); left it untouched`);
       continue;
     }
-    const current = (0, import_node_fs3.existsSync)(file) ? await (0, import_promises.readFile)(file, "utf8") : null;
+    const current = (0, import_node_fs4.existsSync)(file) ? await (0, import_promises.readFile)(file, "utf8") : null;
     if (needsUpdate(source, current)) {
       const slash = file.lastIndexOf("/");
-      if (slash > 0) (0, import_node_fs3.mkdirSync)(file.slice(0, slash), { recursive: true });
+      if (slash > 0) (0, import_node_fs4.mkdirSync)(file.slice(0, slash), { recursive: true });
       await (0, import_promises.writeFile)(file, normalizeEol(source), "utf8");
       changed++;
       if (!opts.quiet) console.log(`mmi-cli rules: updated ${file}`);
@@ -4602,6 +5526,29 @@ rules.command("sync").option("--quiet", "stay silent unless something changed or
   }
   if (!opts.quiet && changed === 0) console.log("mmi-cli rules: up to date");
 });
+var docs = program2.command("docs").description("repo-owned authoritative docs");
+docs.command("sync").option("--quiet", "stay silent unless something changed or errored").description("refresh README.md / architecture.md from the repo default branch (keeper-authored); never clobbers uncommitted edits").action(async (opts) => {
+  const ref = await gitOut(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]);
+  const def = (ref.startsWith("origin/") ? ref.slice("origin/".length) : ref) || "development";
+  await gitOut(["fetch", "origin", def, "--quiet"]);
+  const result = await syncDocs({
+    isDirty: async (f) => await gitOut(["status", "--porcelain", "--", f]) !== "",
+    originContent: async (f) => {
+      try {
+        return (await execFileP3("git", ["show", `origin/${def}:${f}`], { maxBuffer: 10 * 1024 * 1024 })).stdout;
+      } catch {
+        return null;
+      }
+    },
+    localContent: async (f) => (0, import_node_fs4.existsSync)(f) ? await (0, import_promises.readFile)(f, "utf8") : null,
+    writeDoc: async (f, c) => {
+      await (0, import_promises.writeFile)(f, c, "utf8");
+    }
+  });
+  for (const f of result.updated) console.log(`mmi-cli docs: updated ${f} (from origin/${def})`);
+  if (!opts.quiet && result.skippedDirty.length) console.log(`mmi-cli docs: kept local edits in ${result.skippedDirty.join(", ")}`);
+  if (!opts.quiet && result.updated.length === 0 && result.skippedDirty.length === 0) console.log("mmi-cli docs: up to date");
+});
 var saga = program2.command("saga").description("per-session continuity");
 async function runNote(summary, o) {
   const [sha, key] = await Promise.all([gitOut(["rev-parse", "--short", "HEAD"]), sagaKey(await loadConfig())]);
@@ -4719,11 +5666,28 @@ program2.command("gc").description("dry-run cleanup for merged/closed PR branche
     fail(`gc: ${e.message}`);
   }
 });
-program2.command("kb").description("org knowledgebase (read-only)").command("get <path>").description("print a KB document by path").action(async (path) => {
-  const cfg = await loadConfig();
-  const base = (cfg.kbSource ?? DEFAULT_KB_SOURCE).replace(/\/$/, "");
-  const res = await fetch(`${base}/${path.replace(/^\//, "")}`);
-  console.log(res.ok ? await res.text() : `kb get failed: HTTP ${res.status}`);
+var kb = program2.command("kb").description("org knowledgebase (read-only)");
+kb.command("get <path>").description("print a KB document by path").action(async (path) => {
+  const src = resolveKbSource((await loadConfig()).kbSource);
+  try {
+    const { stdout } = await execFileP3("gh", buildKbGetArgs(src, path), { timeout: 1e4 });
+    process.stdout.write(stdout);
+  } catch (e) {
+    const err = e;
+    fail(`kb get failed: ${(err.stderr || err.message || String(e)).trim()}`);
+  }
+});
+kb.command("list [prefix]").description("list KB document paths (optionally under a prefix)").action(async (prefix) => {
+  const src = resolveKbSource((await loadConfig()).kbSource);
+  try {
+    const { stdout } = await execFileP3("gh", buildKbTreeArgs(src), { timeout: 1e4 });
+    const paths = parseKbTree(stdout, prefix);
+    if (!paths.length) return fail(`kb list: no documents${prefix ? ` under ${prefix}` : ""}`);
+    console.log(paths.join("\n"));
+  } catch (e) {
+    const err = e;
+    fail(`kb list failed: ${(err.stderr || err.message || String(e)).trim()}`);
+  }
 });
 async function ghCreate(args) {
   try {
@@ -4734,7 +5698,7 @@ async function ghCreate(args) {
     fail(`gh ${args[0]} create failed: ${(err.stderr || err.message || String(e)).trim()}`);
   }
 }
-async function ghJson2(args, timeout = 1e4) {
+async function ghJson3(args, timeout = 1e4) {
   const { stdout } = await execFileP3("gh", args, { timeout });
   return JSON.parse(stdout);
 }
@@ -4747,6 +5711,47 @@ async function resolveRepo(repo) {
     return void 0;
   }
 }
+async function attachToProject(issueNumber, repo, priority) {
+  const cfg = await loadConfig();
+  if (!cfg.projectId) return void 0;
+  if (repo) {
+    const skip = boardAttachSkipReason(await resolveRepo(), repo);
+    if (skip) {
+      process.stderr.write(`warning: issue #${issueNumber} NOT added to this board \u2014 ${skip}
+`);
+      return void 0;
+    }
+  }
+  try {
+    const viewArgs = ["issue", "view", String(issueNumber), "--json", "id", "--jq", ".id"];
+    if (repo) viewArgs.push("--repo", repo);
+    const { stdout: idOut } = await execFileP3("gh", viewArgs, { timeout: 1e4 });
+    const contentId = idOut.trim();
+    if (!contentId) throw new Error("could not resolve issue node id");
+    const { stdout } = await execFileP3("gh", buildAddToProjectArgs(cfg.projectId, contentId), { timeout: 1e4 });
+    const projectItemId = parseAddedItemId(stdout);
+    if (projectItemId && priority) {
+      try {
+        await setBoardItemPriority(
+          async (args) => execFileP3("gh", args, { timeout: 1e4 }),
+          cfg,
+          projectItemId,
+          priority
+        );
+      } catch (e) {
+        const err = e;
+        process.stderr.write(`warning: issue #${issueNumber} board Priority not set: ${(err.stderr || err.message || String(e)).trim()}
+`);
+      }
+    }
+    return projectItemId;
+  } catch (e) {
+    const err = e;
+    process.stderr.write(`warning: issue #${issueNumber} created but NOT added to the project board: ${(err.stderr || err.message || String(e)).trim()}
+`);
+    return void 0;
+  }
+}
 function scheduleRelatedDiscovery(o) {
   try {
     const args = ["issue", "discover-related", "--number", String(o.number), "--title", o.title, "--body", o.body];
@@ -4761,7 +5766,7 @@ function scheduleRelatedDiscovery(o) {
   }
 }
 function makePlanDeps(cfg) {
-  const ensureDir = () => (0, import_node_fs3.mkdirSync)(PLANS_DIR, { recursive: true });
+  const ensureDir = () => (0, import_node_fs4.mkdirSync)(PLANS_DIR, { recursive: true });
   return {
     apiUrl: cfg.sagaApiUrl,
     fetch: (url, init) => fetch(url, init),
@@ -4769,31 +5774,31 @@ function makePlanDeps(cfg) {
     project: async () => (await sagaKey(cfg)).project,
     readLocal: (slug) => {
       try {
-        return (0, import_node_fs3.readFileSync)(planPath(slug), "utf8");
+        return (0, import_node_fs4.readFileSync)(planPath(slug), "utf8");
       } catch {
         return null;
       }
     },
     writeLocal: (slug, content) => {
       ensureDir();
-      (0, import_node_fs3.writeFileSync)(planPath(slug), content, "utf8");
+      (0, import_node_fs4.writeFileSync)(planPath(slug), content, "utf8");
     },
     removeLocal: (slug) => {
       try {
-        (0, import_node_fs3.rmSync)(planPath(slug));
+        (0, import_node_fs4.rmSync)(planPath(slug));
       } catch {
       }
     },
     readMetaRaw: () => {
       try {
-        return (0, import_node_fs3.readFileSync)(META_FILE, "utf8");
+        return (0, import_node_fs4.readFileSync)(META_FILE, "utf8");
       } catch {
         return null;
       }
     },
     writeMetaRaw: (raw) => {
       ensureDir();
-      (0, import_node_fs3.writeFileSync)(META_FILE, raw, "utf8");
+      (0, import_node_fs4.writeFileSync)(META_FILE, raw, "utf8");
     },
     log: (m) => console.log(m),
     err: (m) => console.error(m),
@@ -4831,17 +5836,65 @@ plan.command("open <slug>").description("pull if needed, then open plans/<slug>.
   })
 );
 plan.command("delete <slug>").description("delete a plan from the server and the local copy").option("--project <name>", "override the project key").action((slug, o) => withPlan(false, (d) => planDelete(d, slug, o)));
+async function readSecretStdin() {
+  if (process.stdin.isTTY) {
+    process.stderr.write(
+      'secrets set: pipe the value on stdin (it is never an argument) \u2014 e.g.\n  printf %s "$VALUE" | mmi-cli secrets set <KEY>\n'
+    );
+    return "";
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8").replace(/\r?\n$/, "");
+}
+function makeSecretsDeps(cfg) {
+  return {
+    apiUrl: cfg.sagaApiUrl,
+    fetch: (url, init) => fetch(url, init),
+    headers: (extra) => sagaHeaders(extra),
+    slug: async () => (await sagaKey(cfg)).project,
+    readSecretValue: () => readSecretStdin(),
+    log: (m) => console.log(m),
+    err: (m) => console.error(m)
+  };
+}
+async function withSecrets(run) {
+  const cfg = await loadConfig();
+  if (!cfg.sagaApiUrl) {
+    fail("secrets: sagaApiUrl not configured in .mmi/config.json (this repo is not bootstrapped)");
+    return;
+  }
+  await run(makeSecretsDeps(cfg));
+}
+var secrets = program2.command("secrets").description("two-tier project secrets \u2014 self-serve your repo dev/* tier; org tier is master-gated");
+secrets.command("list").description("list secret NAMES + tier for this repo (never values)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((o) => withSecrets((d) => secretsList(d, o)));
+secrets.command("get <key>").description("print one secret value over TLS (prints once, raw \u2014 do not log/paste it)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((key, o) => withSecrets((d) => secretsGet(d, key, o)));
+secrets.command("set <key>").description("write/rotate a secret; value is read from stdin (never an argument)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((key, o) => withSecrets((d) => secretsSet(d, key, o)));
+secrets.command("edit <key>").description("alias for set \u2014 replace a secret value (read from stdin)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((key, o) => withSecrets((d) => secretsEdit(d, key, o)));
+secrets.command("rm <key>").description("remove a secret (project tier self-serve; org tier needs a grant)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((key, o) => withSecrets((d) => secretsRemove(d, key, o)));
+secrets.command("use <key>").description("print guidance on consuming a secret without committing it (no value)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action((key, o) => withSecrets((d) => secretsUse(d, key, o)));
+secrets.command("grant <repo> <login> <key>").description("MASTER-ONLY: grant a project-admin standing access to a specific org-tier secret").action((repo, login, key) => withSecrets((d) => secretsGrant(d, repo, login, key, {})));
+secrets.command("revoke <repo> <login> <key>").description("MASTER-ONLY: withdraw a previously granted org-tier secret access").action((repo, login, key) => withSecrets((d) => secretsRevoke(d, repo, login, key, {})));
 var issue = program2.command("issue").description("issues \u2014 reliable create with structured output");
-issue.command("create").description("create an issue (type \u2192 label) and print {number,url,label} JSON").requiredOption("--type <type>", "bug | feature | task (sets the matching label)").requiredOption("--title <title>", "issue title").requiredOption("--body <body>", "issue body (markdown)").requiredOption("--priority <priority>", "high | medium | low (adds a priority:<p> label)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action(async (o) => {
+issue.command("create").description("create an issue (type \u2192 label) and print {number,url,label} JSON").requiredOption("--type <type>", "bug | feature | task (sets the matching label)").requiredOption("--title <title>", "issue title").requiredOption("--body <body>", "issue body (markdown)").requiredOption("--priority <priority>", "urgent | high | medium | low (label + board Priority field when configured)").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--label <label...>", "extra label(s) to attach (repeatable; auto-created if missing)").option("--no-related", "skip the auto related-issues comment").action(async (o) => {
   let args;
   try {
-    args = buildIssueArgs({ type: o.type, title: o.title, body: o.body, priority: o.priority, repo: o.repo });
+    args = buildIssueArgs({ type: o.type, title: o.title, body: o.body, priority: o.priority, repo: o.repo, labels: o.label });
   } catch (e) {
     return fail(`issue create: ${e.message}`);
   }
+  for (const label of o.label ?? []) {
+    const la = ["label", "create", label, "--color", "ededed"];
+    if (o.repo) la.push("--repo", o.repo);
+    try {
+      await execFileP3("gh", la, { timeout: 1e4 });
+    } catch {
+    }
+  }
   const created = await ghCreate(args);
-  scheduleRelatedDiscovery({ repo: o.repo, number: created.number, title: o.title, body: o.body });
-  console.log(JSON.stringify({ ...created, label: o.type, priority: o.priority }));
+  const projectItemId = await attachToProject(created.number, o.repo, o.priority);
+  if (o.related !== false) scheduleRelatedDiscovery({ repo: o.repo, number: created.number, title: o.title, body: o.body });
+  console.log(JSON.stringify({ ...created, label: o.type, priority: o.priority, projectItemId }));
 });
 issue.command("discover-related").description("find related issues for an existing issue and post only high-confidence links").requiredOption("--number <number>", "created issue number").requiredOption("--title <title>", "created issue title").requiredOption("--body <body>", "created issue body").option("--repo <owner/repo>", "target repo (defaults to the current repo)").option("--json", "print candidates instead of posting").action(async (o) => {
   const number = Number(o.number);
@@ -4849,7 +5902,7 @@ issue.command("discover-related").description("find related issues for an existi
   const repo = await resolveRepo(o.repo);
   if (!repo) return fail("issue discover-related: could not resolve repo");
   try {
-    const issues = await ghJson2([
+    const issues = await ghJson3([
       "issue",
       "list",
       "--repo",
@@ -4864,7 +5917,7 @@ issue.command("discover-related").description("find related issues for an existi
     const candidates = findRelatedIssues({ number, title: o.title, body: o.body }, issues);
     if (o.json) return console.log(JSON.stringify({ number, repo, candidates }, null, 2));
     if (!candidates.length) return;
-    const viewed = await ghJson2([
+    const viewed = await ghJson3([
       "issue",
       "view",
       String(number),
@@ -4883,6 +5936,16 @@ pr.command("create").description("create a PR and print {number,url} JSON").requ
   const created = await ghCreate(buildPrArgs({ title: o.title, body: o.body, base: o.base, head: o.head, repo: o.repo }));
   console.log(JSON.stringify(created));
 });
+pr.command("merge <number>").description("merge a PR (squash by default) and clean up its branch + worktree \u2014 no leftover local branch").option("--squash", "squash merge (default)").option("--merge", "create a merge commit").option("--rebase", "rebase merge").option("--repo <owner/repo>", "target repo (defaults to the current repo)").action(async (number, o) => {
+  const method = o.rebase ? "--rebase" : o.merge ? "--merge" : "--squash";
+  const repoArgs = o.repo ? ["--repo", o.repo] : [];
+  const headRef = (await execFileP3("gh", ["pr", "view", number, ...repoArgs, "--json", "headRefName", "--jq", ".headRefName"], { timeout: GC_GH_TIMEOUT_MS })).stdout.trim();
+  await execFileP3("gh", ["pr", "merge", number, ...repoArgs, method, "--delete-branch"], { timeout: GC_GH_TIMEOUT_MS }).catch((e) => {
+    if (!/used by worktree|cannot delete branch|already been merged/i.test(String(e.message || ""))) throw e;
+  });
+  const cleaned = repoArgs.length ? { branchDeleted: false } : await cleanupLocalBranch(headRef);
+  console.log(JSON.stringify({ merged: number, branch: headRef, method: method.slice(2), ...cleaned }));
+});
 async function runBoardRead(o) {
   try {
     const report = await readBoard({
@@ -4896,17 +5959,69 @@ async function runBoardRead(o) {
     fail(`board read failed: ${e.message}`);
   }
 }
-var board = program2.command("board").description("read and claim Project v2 work items for the current repo");
+var board = program2.command("board").description("read, claim, show, and move Project v2 work items for the current repo");
 board.command("read", { isDefault: true }).description("read the board and print user-owned, claimable, and taken items").option("--json", "machine-readable output").option("--repo <owner/repo>", "current repo (defaults to git origin)").option("--bundle-details", "fetch body/comments only for user-owned and claimable issues").option("--allow-partial", "return partial board results when later page/detail reads fail").action((o) => runBoardRead(o));
-board.command("claim <issue>").description("assign a Todo issue to you and move its Project v2 Status to In Progress").option("--json", "machine-readable output").option("--repo <owner/repo>", "current repo for local issue numbers (defaults to git origin)").option("--allow-partial", "return success JSON if assignment succeeds but the status move fails").action(async (issueRef, o) => {
+board.command("claim <issue>").description("assign a Todo issue and move its Project v2 Status to In Progress").option("--json", "machine-readable output").option("--repo <owner/repo>", "current repo for local issue numbers (defaults to git origin)").option("--for <login>", "assign to this login instead of @me \u2014 agent claims on behalf of the master").option("--allow-partial", "return success JSON if assignment succeeds but the status move fails").action(async (issueRef, o) => {
   try {
-    const result = await claimBoardIssue({ config: await loadConfig(), selector: issueRef, repo: o.repo, allowPartial: o.allowPartial });
+    const result = await claimBoardIssue({
+      config: await loadConfig(),
+      selector: issueRef,
+      repo: o.repo,
+      assignee: o.for,
+      allowPartial: o.allowPartial
+    });
     if (o.json) return console.log(JSON.stringify(result));
     console.log(result.partial ? `Partially claimed ${result.item.ref}: ${result.warning}` : `Claimed ${result.item.ref} - In Progress`);
   } catch (e) {
     fail(`board claim failed: ${e.message}`);
   }
 });
+board.command("show <issue>").alias("open").description("print one board item (status, assignees, type, url) with its body and comments").option("--json", "machine-readable output").option("--repo <owner/repo>", "current repo for local issue numbers (defaults to git origin)").option("--allow-partial", "return the item even if its body/comments fetch fails").action(async (issueRef, o) => {
+  try {
+    const item = await showBoardItem({ config: await loadConfig(), selector: issueRef, repo: o.repo, allowPartial: o.allowPartial });
+    console.log(o.json ? JSON.stringify(item) : renderBoardItem(item));
+  } catch (e) {
+    fail(`board show failed: ${e.message}`);
+  }
+});
+board.command("move <issue> <status>").description(`move a board item's Status to one of: ${BOARD_STATUSES.join(", ")} (quote multi-word statuses)`).option("--json", "machine-readable output").option("--repo <owner/repo>", "current repo for local issue numbers (defaults to git origin)").option("--allow-partial", "return success JSON if the item resolves but the status move fails").action(async (issueRef, status, o) => {
+  if (!BOARD_STATUSES.includes(status)) {
+    return fail(`board move failed: unknown status '${status}'; expected one of ${BOARD_STATUSES.join(", ")}`);
+  }
+  try {
+    const result = await moveBoardItem({ config: await loadConfig(), selector: issueRef, status, repo: o.repo, allowPartial: o.allowPartial });
+    if (o.json) return console.log(JSON.stringify(result));
+    console.log(result.partial ? `Partially moved ${result.item.ref}: ${result.warning}` : `Moved ${result.item.ref} -> ${result.status}`);
+  } catch (e) {
+    fail(`board move failed: ${e.message}`);
+  }
+});
+board.command("backfill-priority").description("set board Priority from priority:* labels or issue timeline for items missing the field").option("--json", "machine-readable output").option("--repo <owner/repo>", "current repo (defaults to git origin)").option("--dry-run", "report what would be set without writing").option("--concurrency <n>", "parallel timeline reads (default 8)", "8").action(async (o) => {
+  try {
+    const result = await backfillBoardPriorities({
+      config: await loadConfig(),
+      repo: o.repo,
+      dryRun: o.dryRun,
+      concurrency: Number(o.concurrency) || 8
+    });
+    if (o.json) return console.log(JSON.stringify(result));
+    console.log(`backfill-priority: scanned ${result.scanned}, set ${result.set}, skipped ${result.skipped}, failed ${result.failed}`);
+    for (const line of result.details.slice(0, 30)) console.log(`  ${line}`);
+    if (result.details.length > 30) console.log(`  ... +${result.details.length - 30} more`);
+    if (result.failed) process.exitCode = 1;
+  } catch (e) {
+    fail(`board backfill-priority failed: ${e.message}`);
+  }
+});
+board.command("done <issue>").description("set a board item's Status to Done (does not close the GitHub issue; use `gh issue close`)").option("--json", "machine-readable output").option("--repo <owner/repo>", "current repo for local issue numbers (defaults to git origin)").option("--allow-partial", "return success JSON if the item resolves but the status move fails").action(async (issueRef, o) => {
+  try {
+    const result = await moveBoardItem({ config: await loadConfig(), selector: issueRef, status: "Done", repo: o.repo, allowPartial: o.allowPartial });
+    if (o.json) return console.log(JSON.stringify(result));
+    console.log(result.partial ? `Partially moved ${result.item.ref}: ${result.warning}` : `Moved ${result.item.ref} -> Done`);
+  } catch (e) {
+    fail(`board done failed: ${e.message}`);
+  }
+});
 function renderSteps(title, steps) {
   return [
     title,
@@ -4921,12 +6036,17 @@ function rawValue(flag, fallback) {
   return index >= 0 && process.argv[index + 1] ? process.argv[index + 1] : fallback;
 }
 function printLine(value) {
-  (0, import_node_fs3.writeSync)(1, `${value}
+  (0, import_node_fs4.writeSync)(1, `${value}
 `);
 }
 function stageKeepAlive() {
   return setTimeout(() => void 0, 5 * 60 * 1e3);
 }
+program2.command("port-range <repo>").description("assign (idempotently) + print the repo's local stage port block from infra/port-ranges.json").option("--json", "machine-readable output").action((repo, o) => {
+  const path = (0, import_node_path4.join)(process.cwd(), "infra", "port-ranges.json");
+  const [start, end] = ensurePortRange(repo, path);
+  printLine(o.json ? JSON.stringify({ repo, portRange: [start, end] }) : `${repo}: stage.portRange [${start}, ${end}]`);
+});
 var stage = program2.command("stage").description("plan or run the repo local stage environment").option("--json", "machine-readable output").option("--apply", "run the full local stage: stop previous, build, start, health-check").option("--timeout-ms <ms>", "bounded build/health timeout", "60000").action(async (o) => {
   const cfg = (await loadConfig()).stage;
   if (o.apply) {
@@ -5028,11 +6148,101 @@ bootstrap.command("verify <repo>").description("audit whether an existing repo i
   if (o.class !== "deployable" && o.class !== "content") return fail("bootstrap verify: --class must be deployable or content");
   const report = await verifyBootstrap(repo, o.class, {
     gh: async (args) => execFileP3("gh", args, { timeout: 2e4 }),
-    readLocalFile: (path) => (0, import_node_fs3.existsSync)(path) ? (0, import_node_fs3.readFileSync)(path, "utf8") : null
+    readLocalFile: (path) => (0, import_node_fs4.existsSync)(path) ? (0, import_node_fs4.readFileSync)(path, "utf8") : null
   });
   console.log(o.json ? JSON.stringify(report, null, 2) : renderBootstrapVerifyReport(report));
   if (!report.ok) process.exitCode = 1;
 });
+bootstrap.command("apply <repo>").description("idempotent seed apply from skills/bootstrap/seeds/manifest.json; dry-run unless --execute (live, master-gated)").option("--class <class>", "deployable | content", "deployable").option("--execute", "LIVE apply via gh (master-gated) \u2014 stamps seed files + labels into the repo").option("--var <KEY=VALUE...>", "placeholder values for repo-owned templates (repeatable)").option("--json", "machine-readable output").action(async (repo) => {
+  const o = { class: rawValue("--class", "deployable"), execute: rawFlag("--execute"), json: rawFlag("--json") };
+  if (o.class !== "deployable" && o.class !== "content") return fail("bootstrap apply: --class must be deployable or content");
+  const manifestPath = "skills/bootstrap/seeds/manifest.json";
+  if (!(0, import_node_fs4.existsSync)(manifestPath)) return fail(`bootstrap apply: ${manifestPath} not found; run from the MMI-Hub repo root`);
+  const manifest = loadBootstrapSeeds((0, import_node_fs4.readFileSync)(manifestPath, "utf8"));
+  const baseBranch = o.class === "content" ? "main" : "development";
+  const slug = repo.split("/")[1].toLowerCase();
+  const gh = async (args) => execFileP3("gh", args, { timeout: 2e4 });
+  const readFile2 = (p) => (0, import_node_fs4.existsSync)(p) ? (0, import_node_fs4.readFileSync)(p, "utf8") : null;
+  const enc = (p) => p.split("/").map(encodeURIComponent).join("/");
+  const vars = {};
+  for (let i = 0; i < process.argv.length - 1; i++) {
+    if (process.argv[i] === "--var") {
+      const eq = process.argv[i + 1].indexOf("=");
+      if (eq > 0) vars[process.argv[i + 1].slice(0, eq)] = process.argv[i + 1].slice(eq + 1);
+    }
+  }
+  const actions = [];
+  const applied = [];
+  for (const seed of manifest.seeds) {
+    if (!seed.classes.includes(o.class)) continue;
+    const resolved = { ...seed, target: seed.target.replace("{{REPO_SLUG}}", slug) };
+    let exists = false;
+    let sha;
+    if (resolved.source !== "fanout") {
+      try {
+        const r = await gh(["api", `repos/${repo}/contents/${enc(resolved.target)}?ref=${baseBranch}`]);
+        exists = true;
+        try {
+          sha = JSON.parse(r.stdout).sha;
+        } catch {
+        }
+      } catch {
+        exists = false;
+      }
+    }
+    const action = planSeedAction(resolved, exists);
+    actions.push(action);
+    if (o.execute && (action.action === "create" || action.action === "update")) {
+      const content = resolveSeedContent(resolved, vars, readFile2);
+      if (content == null) {
+        applied.push(`skip ${resolved.target} (no resolvable content)`);
+        continue;
+      }
+      const missing = missingPlaceholders(content);
+      if (missing.length) {
+        applied.push(`skip ${resolved.target} (unfilled: ${missing.join(", ")} \u2014 pass --var)`);
+        continue;
+      }
+      await gh(contentPutArgs(repo, resolved.target, content, baseBranch, action.action === "update" ? sha : void 0));
+      applied.push(`${action.action} ${resolved.target}`);
+    }
+  }
+  if (o.execute) {
+    for (const l of manifest.labels) {
+      try {
+        await gh(["label", "create", l.name, "--color", l.color, "--description", l.description, "--force", "-R", repo]);
+        applied.push(`label ${l.name}`);
+      } catch {
+        applied.push(`label ${l.name} (failed)`);
+      }
+    }
+  }
+  if (o.json) console.log(JSON.stringify({ repo, class: o.class, execute: o.execute, actions, applied }, null, 2));
+  else {
+    console.log(renderSeedPlan(actions));
+    if (o.execute) console.log(`
+LIVE apply to ${repo}:
+  ${applied.join("\n  ")}`);
+  }
+});
+var access = program2.command("access").description("org access audit (read-only)");
+access.command("audit").description("audit collaborator roles + train-branch push allowlists vs the locked state; read-only, emits gh remediation, never applies").option("--json", "machine-readable output").option("--repo <owner/repo>", "audit a single repo instead of the whole org").option("--class <class>", "repo class for --repo (deployable | content)", "deployable").action(async () => {
+  const o = { json: rawFlag("--json"), repo: rawValue("--repo", ""), class: rawValue("--class", "deployable") };
+  const deps = { gh: async (args) => execFileP3("gh", args, { timeout: 2e4 }) };
+  let targets;
+  if (o.repo) {
+    if (o.class !== "deployable" && o.class !== "content") return fail("access audit: --class must be deployable or content");
+    targets = [{ repo: o.repo, class: o.class }];
+  } else {
+    if (!(0, import_node_fs4.existsSync)("projects.json")) return fail("access audit: projects.json not found; run from the MMI-Hub repo root or pass --repo <owner/repo>");
+    const fanoutJson = (0, import_node_fs4.existsSync)(".github/fanout-targets.json") ? (0, import_node_fs4.readFileSync)(".github/fanout-targets.json", "utf8") : null;
+    targets = loadAccessTargets((0, import_node_fs4.readFileSync)("projects.json", "utf8"), fanoutJson);
+  }
+  const matrix = (0, import_node_fs4.existsSync)("access-matrix.json") ? loadAccessMatrix((0, import_node_fs4.readFileSync)("access-matrix.json", "utf8")) : {};
+  const report = await auditOrgAccess(targets, deps, matrix);
+  console.log(o.json ? JSON.stringify(report, null, 2) : renderAccessReport(report));
+  if (!report.ok) process.exitCode = 1;
+});
 var isWin = process.platform === "win32";
 program2.command("doctor").description("check onboarding gates (GitHub auth, mmi-cli on PATH, repo config, plugin git clone) and print fixes").option("--banner", "one-line resume summary; silent when all gates pass").option("--json", "machine-readable output").action(async (opts) => {
   const checks = [];
@@ -5054,14 +6264,16 @@ program2.command("doctor").description("check onboarding gates (GitHub auth, mmi
   }
   if (!onPath) {
     const root = process.env.CLAUDE_PLUGIN_ROOT;
-    if (root && (0, import_node_fs3.existsSync)(`${root}/bin/mmi-cli${isWin ? ".cmd" : ""}`)) onPath = true;
+    if (root && (0, import_node_fs4.existsSync)(`${root}/bin/mmi-cli${isWin ? ".cmd" : ""}`)) onPath = true;
   }
   checks.push({ ok: onPath, label: "mmi-cli on PATH", fix: "auto-provisioned at session start \u2014 reopen the session, or install the MMI plugin" });
-  checks.push(buildVersionLagReport({
+  let versionReport = buildVersionLagReport({
     currentVersion: resolveVersion(),
     repoVersion: readRepoVersion(),
     releasedVersion: await fetchReleasedVersion()
-  }));
+  });
+  if (!opts.json) versionReport = await applyVersionAutoUpdate(versionReport, (m) => console.error(m));
+  checks.push(versionReport);
   const cfg = await loadConfig();
   checks.push({ ok: Boolean(cfg.sagaApiUrl), label: "repo config (.mmi/config.json)", fix: "ask a master-admin to run /bootstrap on this repo" });
   const REWRITE_KEY = "url.https://github.com/.insteadOf";