projectstore-claude 0.29.2 → 0.29.3

package/node_modules/projectstore/scripts/doctor-report.mjs

@@ -0,0 +1,185 @@
+// projectstore — doctor-report.mjs: doctor's text report, drawn from its
+// findings (the presentation spec, *Terminal presentation of the projectstore
+// CLI: layout, glyphs, colour roles, questions and live lines*, contract 11).
+//
+// A renderer, not a second doctor: it imports no check and is pure — it
+// returns text and writes nothing. That is why doctor.mjs itself stays
+// spawned, never imported (the MCP ADR's decision 2 table), while this module
+// is imported by both readers of the findings: the bin, which renders the
+// findings of its one `--json` spawn in its own process (so a terminal gets
+// colour), and doctor.mjs's own text mode, through a dynamic import. The
+// dynamic import keeps the SessionStart hook's static graph — which reaches
+// doctor.mjs — as it was; this module imports only term.mjs and lib.mjs.
+//
+//   report(findings, groups, { caps, verbose, version, project, env }) → text
+//   CHECKS                                                            → the check table
+//
+// The layout: a badge with the version and the project's folder name; per
+// section (INSTALL, VAULT) a heading with its counts and a rule; issues, then
+// warnings, then notes; the Summary line last, verbatim — the write ceremony
+// reads it (commands/story.md step 5a, agents/clerk.md). That line is
+// lib.mjs's doctorSummaryLine, so a caller's fallback ends with it too.
+//
+// Two readers, one layout:
+//   - plain (a pipe, an agent's Bash tool) prints every finding, its message
+//     whole on one line with its path, and every note. Agents read it, and the
+//     vocabulary suite's about-filter cuts a finding out by its exact message;
+//   - a terminal gets the same report compacted: a cause with many instances
+//     lists each by its capture and path, at most eight, and the notes of the
+//     folding rows fold into one line. `--verbose` turns the compaction off.
+// Every entry keeps its `[check]` id: the `--fix` walk of commands/doctor.md
+// keys on it.
+
+import { PLAIN, painter, icon, badge, heading, rule, rowLines, wrap, commandBlock } from "./term.mjs";
+import { commandForm, doctorSummaryLine } from "./lib.mjs";
+
+// ─── The check table ─────────────────────────────────────────────────────
+//
+// One row per check id that is grouped, fixed or folded; a check with no row
+// prints each finding as it is. A row is { instance, title, fix, folds }:
+//   - instance: a pattern over the message, with zero or one capture. Two or
+//     more findings of one check and one level that match it form one entry:
+//     the title once, then each finding's capture and path. A finding that
+//     does not match — and a finding about another harness (`about`), whose
+//     exact message the vocabulary suite cuts out — prints on its own.
+//   - fix: what to do, listed once under the check's entries at each level,
+//     only for a check whose messages carry no command (contract 11): a
+//     sentence, or { say, command } where the command is composed through
+//     commandForm and stands on its own line (contract 6). Each is worded to
+//     be true for every message its check can carry.
+//   - folds: notes of this check fold on a terminal — true for all of them,
+//     or a pattern for the ones it names. The offer checks (doctor.mjs's
+//     OFFER_CHECKS: upgrade, layout-legacy) never fold, so they have no row.
+const row = ({ instance = null, title = null, fix = null, folds = false }) => Object.freeze({ instance, title, fix, folds });
+
+export const CHECKS = Object.freeze({
+  // Fixes: the checks whose messages name no command.
+  "code-refs": row({
+    instance: /^code_refs path "([^"]+)" does not resolve/,
+    title: "code_refs path does not resolve inside the project",
+    fix: "make each code_refs path exist in the project, and keep a story's paths inside its epic's",
+  }),
+  "wikilink": row({
+    instance: /^Dead wiki-link \[\[(.+)\]\]\.$/,
+    title: "Dead wiki-link",
+    fix: "make each [[link]] name exactly one existing artifact (correct the name, or qualify it with its folder); if the check was skipped, fix the error it names",
+  }),
+  "rel-link": row({
+    instance: /^Dead relative link \((.+)\)\.$/,
+    title: "Dead relative link",
+    fix: "point each relative link at a file that exists, or remove it",
+  }),
+  "acceptance": row({ fix: "tick the criteria the work met, or move the story out of done" }),
+  "review-status": row({ fix: "set reviewed_at to the review's date, or clear review_status" }),
+  "epic-status": row({ fix: "close the open stories, or move the epic out of done" }),
+  "spec-links": row({ fix: "make each spec's stories and each story's specs name existing artifacts that list each other back, written inline as specs: [\"id\"]" }),
+  "index": row({
+    instance: / is not listed in .+\/README\.md's index\.$/,
+    title: "Artifact is not listed in its folder's README index",
+    fix: { say: "rebuild the folder indexes from frontmatter", command: (env) => commandForm("reconcile", { env }) },
+  }),
+  "index-header": row({ fix: "rewrite the index header in a registered form, so reconcile can rebuild the index" }),
+  // Notes that fold on a terminal while their section has something to fix.
+  "surface": row({ folds: /— current, last written by / }),
+  "mcp": row({ folds: true }),
+  "statusline": row({ folds: /^Base HUD present/ }),
+  "harness": row({ folds: true }),
+  "plugin-registration": row({ folds: / registered from the npm package / }),
+  "spec-policy": row({ folds: true }),
+  "identity": row({ folds: true }),
+  "artifact-name": row({ folds: true }),
+});
+
+// The instance list on a terminal: at most this many, then `+N more`.
+export const INSTANCE_CAP = 8;
+
+const NONE = row({});
+const LEVELS = Object.freeze([
+  // [level, glyph name, role, count word]
+  ["issue", "issue", "error", "issue"],
+  ["warn", "warning", "attention", "warning"],
+  // A note is not a warning: its own glyph, so the two differ without colour.
+  ["info", "info", "explanation", "note"],
+]);
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+// Joins the dash to the path after it, so wrapping never leaves a bare dash
+// at a line's end with the path alone below; a space again once wrapped.
+const GLUE = "";
+
+const folderName = (p) => (p ? String(p).replace(/[\\/]+$/, "").split(/[\\/]/).pop() || null : null);
+const folds = (r, f) => f.level === "info" && Boolean(r.folds) && (r.folds === true || r.folds.test(f.message));
+const capture = (r, f) => { const m = r.instance.exec(f.message); return m && m[1] !== undefined ? m[1] : null; };
+
+export function report(findings, groups, { caps: c = PLAIN, verbose = false, version = null, project = null, env = process.env } = {}) {
+  const paint = painter(c);
+  // The terminal's compaction (contract 11, "on a TTY only"): the cap, the
+  // folds and the short instance lines. Plain output prints everything, and
+  // --verbose asks a terminal for the same.
+  const compact = c.live && !verbose;
+  const width = c.live ? c.width : 0;
+  const dash = icon(c, "dash");
+  // Prose at an indent: wrapped on a live terminal, every line after the
+  // first indented two further; one line anywhere else.
+  const prose = (n, text) => {
+    const pad = " ".repeat(n);
+    return wrap(text, width, pad + "  ").split("\n").map((l, k) => (k ? l : pad + l).split(GLUE).join(" "));
+  };
+  const withPath = (text, f) => (f.file ? `${text} ${paint("explanation", dash)}${GLUE}${paint("explanation", f.file)}` : text);
+
+  function entries(level, check, r, these) {
+    const [, glyph, role] = LEVELS.find(([l]) => l === level);
+    const lead = `${paint(role, icon(c, glyph))} [${check}]`;
+    const matched = r.instance ? these.filter((f) => !f.about && r.instance.test(f.message)) : [];
+    const grouped = matched.length >= 2 ? matched : [];
+    const out = [];
+    for (const f of these) {
+      if (!grouped.includes(f)) { out.push(...prose(2, withPath(`${lead} ${f.message}`, f))); continue; }
+      if (f !== grouped[0]) continue;
+      out.push(...prose(2, `${lead} ${paint("emphasis", r.title)} (${grouped.length})`));
+      if (!compact) { for (const g of grouped) out.push(...prose(6, withPath(g.message, g))); continue; }
+      // Each instance a row with its own glyph: its capture, then its path.
+      // A path moved beneath its capture (contract 5) reads `— <path>`, as
+      // plain's `message — file` does, so neither colour nor the indent is
+      // all that tells it from the next capture.
+      const shown = grouped.slice(0, INSTANCE_CAP);
+      const laid = rowLines(c, shown.map((g) => { const cap = capture(r, g); return { glyph: "dot", role: "explanation", ...(cap === null ? { target: g.file || g.message } : { target: cap, note: g.file || "" }) }; }), { indent: 6 });
+      for (const [first, ...moved] of laid) out.push(first, ...moved.map((l, k) => (k ? l : l.replace(/^ */, (pad) => `${pad}${paint("explanation", dash)} `))));
+      if (grouped.length > shown.length) out.push(`      ${paint("explanation", `+${grouped.length - shown.length} more`)}`);
+    }
+    if (r.fix) {
+      const fix = typeof r.fix === "string" ? { say: r.fix, command: null } : r.fix;
+      out.push(...prose(4, `${paint("action", "fix:")} ${fix.say}${fix.command ? ":" : "."}`));
+      if (fix.command) out.push(...commandBlock(c, [fix.command(env)], { indent: 6 }), "");
+    }
+    return out;
+  }
+
+  function section(group) {
+    const fs = findings.filter((f) => f.group === group);
+    const n = Object.fromEntries(LEVELS.map(([l]) => [l, fs.filter((f) => f.level === l).length]));
+    // Each count in its role; a zero issue or warning count is the done role.
+    const counts = LEVELS.map(([l, , role, word]) => [plural(n[l], word), l === "info" ? role : n[l] ? role : "done"]);
+    const out = [heading(c, group.toUpperCase(), counts), rule(c)];
+    if (!fs.length) return [...out, `  ${paint("done", icon(c, "ok"))} clean`];
+    // A note folds only while its section has something to fix.
+    const folding = compact && n.issue + n.warn > 0;
+    let hidden = 0;
+    for (const [level] of LEVELS) {
+      const atLevel = fs.filter((f) => f.level === level);
+      for (const check of [...new Set(atLevel.map((f) => f.check))]) {
+        const r = Object.hasOwn(CHECKS, check) ? CHECKS[check] : NONE;
+        let these = atLevel.filter((f) => f.check === check);
+        if (folding) { const kept = these.filter((f) => !folds(r, f)); hidden += these.length - kept.length; these = kept; }
+        if (these.length) out.push(...entries(level, check, r, these));
+      }
+    }
+    if (hidden) out.push(`  ${paint("explanation", `${plural(hidden, "note")} hidden ${icon(c, "dot")} --verbose shows them`)}`);
+    while (out.at(-1) === "") out.pop();
+    return out;
+  }
+
+  const lines = [badge(c, "projectstore doctor", [version, folderName(project)])];
+  for (const g of groups) lines.push("", ...section(g));
+  lines.push("", doctorSummaryLine(findings, { env }));
+  return lines.join("\n") + "\n";
+}

package/node_modules/projectstore/scripts/doctor.mjs

@@ -14,6 +14,8 @@
 //
 // CLI: node doctor.mjs [--install] [--vault] [--startup] [--json]
 //      default = --install --vault. Exit code is always 0 (reporting tool).
+//      Without --json the findings are drawn by doctor-report.mjs, the
+//      renderer the bin uses, in its plain layout.
 
 import {
   existsSync,
@@ -66,7 +68,8 @@ import {
   findAgentsBlock,
   statusLineLauncherPath,
   LAUNCHER_HEADER,
-  installedPluginEntries, isMain,
+  installedPluginEntries, selectCopy, takesNoRegister, copyUpdateAdvice, isMain,
+  channelMark,
   pickExisting,
   legacyStatusLineLauncherPath,
   stateDir,
@@ -85,6 +88,7 @@ import {
   speakingHarness,
   inheritForm,
   bindInherits,
+  doctorFallbackText,
 } from "./lib.mjs";
 import { agentOverrides, childEnv, sourceHarness, runtimeEnvNames, loadHarness, detectHarnesses, identifiedHarnessId, configPath as harnessConfigPath, packageCommand, invocation } from "./harness.mjs";
 
@@ -101,6 +105,7 @@ import { agentOverrides, childEnv, sourceHarness, runtimeEnvNames, loadHarness,
 // brand, and --harness still carries the target.
 import { uncommittedProjectFiles, lastCommitMs } from "./diff-refs.mjs";
 import { resolveBinding } from "./worktree.mjs";
+import { missingScaffoldRequirements } from "./scaffold.mjs";
 
 const AGENT_BLOCK_MARKER = new RegExp(AGENTS_BLOCK_OPEN_SRC, "g");
 // The provenance grammar's prefix, duplicated here on purpose: the startup
@@ -257,6 +262,15 @@ export function checkLayoutTemplates(cfg) {
       out.push(finding("install", "issue", "templates", `Missing template for language "${lang}": ${k}.md.tmpl`));
     }
   }
+  // What `scaffold` (and `init`) refuse on, through the same check the plan
+  // makes: the vault README's template, and a name and a description for every
+  // folder kind the layout declares — `diagram` included. A warn, not an issue:
+  // a vault already scaffolded is not broken by a hand-added kind; only its
+  // next scaffold is refused. The folder README is the issue above.
+  for (const m of missingScaffoldRequirements(layout, lang, pluginRoot())) {
+    if (m.what === "template" && m.name === "folder-readme") continue;
+    out.push(finding("install", "warn", "templates", `${m.message} — scaffold and init refuse until it is there.`));
+  }
   if (!existsSync(join(pluginRoot(), "scaffold", "headings.json"))) {
     out.push(finding("install", "issue", "templates",
       "scaffold/headings.json is missing — heading-registry checks (index headers, acceptance, spec gates) cannot run. Stale/corrupt plugin install?"));
@@ -492,14 +506,17 @@ export function checkAgentsBlock(proj, { env = process.env, root = pluginRoot()
   // contract 6 as amended after the rc.3 tag): one well-formed block, seen by
   // every harness the project uses. rc.1 and rc.2 left a block in an
   // AGENTS.md-only project with no CLAUDE.md, so Claude Code saw nothing, and
-  // nothing said so. Used means detected by directory, or identified from the
-  // environment — never the source harness a terminal run falls back to, so a
-  // Codex-only project hears nothing about CLAUDE.md (contract 16). An issue
+  // nothing said so. Used means detected by directory or by its state
+  // directory, or identified from the environment — never the source harness
+  // a terminal run falls back to, so a Codex-only project hears nothing about
+  // CLAUDE.md (contract 16). The state directory is what a bare upgrade and a
+  // bare uninstall select by, so doctor warns about exactly the block they
+  // move (the story "One run plans the agents block once…", rule 5). An issue
   // for the harness that identified itself, a warning for one only detected.
   const blockFile = blocks === 1 && !refuses ? Object.keys(perFile)[0] : null;
   if (blockFile) {
     const identified = identifiedHarnessId(env);
-    const used = new Set([...detectHarnesses(proj).map((d) => d.id), ...(identified ? [identified] : [])]);
+    const used = new Set([...detectHarnesses(proj, { state: true }).map((d) => d.id), ...(identified ? [identified] : [])]);
     for (const id of used) {
       const m = loadHarness(id);
       if (!m || blockVisibleTo(m, blockFile, texts)) continue;
@@ -616,9 +633,12 @@ export async function checkHarnessSurfaces(_cfg, proj, { home = homedir(), root
         push(finding("install", "warn", "surface", `${where} [projectstore:agents] — ${s.reason}. Run ${invocation(sh, "agents", { args: "register" })}.`, where));
       }
     }
-    // The statusline entry's states are checkStatusline's, under its own id —
-    // its ours-stale (a command this installation would not write) is
-    // self-healing: syncStatusLine rewrites it on the next SessionStart.
+    // The statusline entry's states are checkStatusline's, under its own id.
+    // Its ours-stale (a command this installation would not write) is not
+    // always self-healing: syncStatusLine re-points a direct entry at the
+    // running root's script and never touches an entry naming a launcher on
+    // disk, so install is what re-points an entry at the launcher
+    // (contract 0 as amended 2026-10-10).
   }
   return out;
 }
@@ -655,8 +675,9 @@ export function checkOverlays(cfg, proj, { root = pluginRoot(), home = homedir()
   // Only when another harness in this project HAS an overlay. A project with
   // none at all is the ordinary fresh state and needs no advice; the asymmetry
   // is what is actionable, because it is almost always the second harness that
-  // was forgotten rather than the first that was deliberate.
-  const used = detectHarnesses(proj).map((d) => d.id);
+  // was forgotten rather than the first that was deliberate. Used as a bare
+  // upgrade or uninstall selects: by directory or by state directory.
+  const used = detectHarnesses(proj, { state: true }).map((d) => d.id);
   if (used.length > 1) {
     const overlays = used.map((id) => ({ id, o: readOverlayAt(proj, loadHarness(id)?.runtime?.overlay || id) }));
     const configured = overlays.filter(({ o }) => o.present);
@@ -691,8 +712,13 @@ export function checkOverlays(cfg, proj, { root = pluginRoot(), home = homedir()
 // itself); a competing copy enabled beside ours → an issue (two enabled copies
 // of one plugin); a competitor alone → an info naming the npm path; foreign →
 // never repairable; the host CLI missing → an info.
-export function checkPluginRegistration(proj, states = [], { home = homedir(), speaker = speakingHarness() } = {}) {
+export function checkPluginRegistration(proj, states = [], { home = homedir(), speaker = speakingHarness(), cfg = null } = {}) {
   const out = [];
+  // A checkout whose binding records a channel switch (the converge story's
+  // rule 3) chose the npm install: the info that ends "If moving to npm was
+  // meant, ignore this" is the one thing it no longer needs. Doctor never
+  // reads who made the mark.
+  const marked = Boolean(channelMark(cfg));
   for (const s of states.filter((x) => x.kind === "registration")) {
     // The shell form when the manifest names a shell (contract 12): the
     // command a user can paste, built in one place.
@@ -719,6 +745,7 @@ export function checkPluginRegistration(proj, states = [], { home = homedir(), s
           push(finding("install", "info", "plugin-registration", `${key} is held off in this checkout's local settings, where the npm registration turned it off — and that copy is no longer installed, so the entry is stale.`, s.path));
           continue;
         }
+        if (marked) continue;
         // The release line, not the build: a 0.28 release candidate reads a
         // moved project; 0.27.x reads it as unbound. No version reads as old.
         const old = !row.version || cmpVersion(row.version, "0.28.0") < 0;
@@ -737,8 +764,16 @@ export function checkPluginRegistration(proj, states = [], { home = homedir(), s
     } else if (s.state === "stale") {
       push(finding("install", "issue", "plugin-registration", `${s.entry} — stale: ${s.reason}. Refresh it: ${refresh}`, s.path));
     } else if (s.state === "current") {
+      // The host loads a host plugin registration in place, from the
+      // plugin's root inside our marketplace directory (the payload — what
+      // its plugin-root variable names); the install path is the registry's
+      // copy, the one the launcher renders (measured on host 2.1.293 and
+      // 2.1.296). A portable registration's host loads the copy.
+      const loaded = h.surfaces?.[s.surface]?.format === "host-plugin-registration" && s.payload
+        ? `install path ${s.installPath}; loaded in place from ${s.payload}`
+        : `loaded from ${s.installPath}`;
       if (others) push(finding("install", "issue", "plugin-registration", `${s.entry} is current, and ${others} is enabled for this project too — two enabled copies of one plugin load twice. install silences the other for this project: ${packageCommand(h, "install", { args: `--surface ${s.surface} --project "${proj}"` })} (or the host's own disable at the scope the manifest names — never the committed project scope).`, s.path));
-      else push(finding("install", "info", "plugin-registration", `${s.entry} ${s.installedVersion} registered from the npm package for this project (loaded from ${s.installPath}); refresh with ${refresh}.`));
+      else push(finding("install", "info", "plugin-registration", `${s.entry} ${s.installedVersion} registered from the npm package for this project (${loaded}); refresh with ${refresh}.`));
     }
   }
   return out;
@@ -913,20 +948,13 @@ export function checkLayout(proj, harness = sourceHarness(), { level = "warn", r
 // the move never needs the registration, so a misread channel can cost a
 // launcher stamp but never a channel switch. A copy that predates the move
 // (no bin/projectstore.mjs — 0.27.x) cannot run it: update that copy first.
-// Nor can one whose CLI predates --no-register (takesNoRegister).
+// Nor can one whose CLI predates --no-register (lib's takesNoRegister).
 //
-// Whether a registry copy can run the command named for it. `--no-register`
-// arrived in 0.28.0-rc.3, and rc.1 and rc.2 parse strictly, so the command
-// exits 2 on the flag and writes nothing (the layout spec, contract 12 as
-// amended after the rc.3 tag). Read from the copy's own parse table, never
-// from its version: a never-published 0.28.0 build ranks above rc.3 and lacks
-// the flag, while a copy labelled rc.2 taken from main at 418448e has it. A
-// file read, because this runs in the SessionStart subset: never an import()
-// of the copy, never a spawn. Add files to the read, never drop cli.mjs:
-// released copies keep their parse there.
-export function takesNoRegister(copy) {
-  try { return readFileSync(join(copy, "scripts", "cli.mjs"), "utf8").includes('"no-register"'); } catch { return false; }
-}
+// The selection, the capability read and the copy advice are lib's
+// (selectCopy, takesNoRegister, copyUpdateAdvice), shared with the
+// installer's keep (the converge story's rule 5). takesNoRegister is
+// re-exported here, where its callers already import it.
+export { takesNoRegister };
 
 export function layoutRemedy(proj, { root = pluginRoot(), home = homedir(), harness = sourceHarness(), env = process.env } = {}) {
   // A session under a relocated host home hands it on: a terminal without it
@@ -939,29 +967,23 @@ export function layoutRemedy(proj, { root = pluginRoot(), home = homedir(), harn
   const channel = installChannel(root, { home, harness });
   if (channel === "registration") return shell(pluginVersion(root));
   if (channel === "marketplace") return own(root);
-  // Real paths: the host records the project's cwd as one, and /var against
-  // /private/var would otherwise drop the project's own row.
-  const real = (x) => { try { return realpathSync.native(x); } catch { return resolve(x); } };
-  const here = real(proj);
-  const mine = (e) => Boolean(e.projectPath) && real(e.projectPath) === here;
-  const copy = installedPluginEntries(home, proj)
-    .filter((e) => e.present && e.enabled && (!e.projectPath || mine(e)))
-    .sort((a, b) => (Number(mine(b)) - Number(mine(a))) || (b.at - a.at))[0];
+  // The selection is lib's selectCopy: this checkout's row first, then
+  // user-scope rows by recency, never another checkout's.
+  const copy = selectCopy(home, proj, { harness });
   if (copy) {
     const v = copy.version ? ` (${copy.version})` : "";
-    if (!existsSync(join(copy.path, "bin", "projectstore.mjs"))) {
-      return { advice: `This project's projectstore plugin${v} predates the move and cannot run it: update it first (in Claude Code: /plugin marketplace update, then /plugin update, then restart), and the startup line names the command` };
-    }
+    const then = "and the startup line names the command";
+    if (copy.missing === "bin") return { advice: copyUpdateAdvice(copy, { cannot: "predates the move and cannot run it", then }) };
     // Chosen first, gated after: the copy is what the project runs, so an
     // incapable one gets advice even beside a capable user-scope copy.
-    const viaRegistration = installChannel(copy.path, { home, harness }) === "registration";
-    if (!takesNoRegister(copy.path)) {
+    const viaRegistration = copy.channel === "registration";
+    if (copy.missing === "no-register") {
       return { advice: viaRegistration
         // Its channel's ordinary refresh, at the running version: the plain
         // upgrade re-registers from npm — not a switch for an npm project — and
         // moves the project in the same run.
         ? `This project's projectstore plugin${v} is the npm registration's copy and predates --no-register, so it cannot run the move as named: refresh that registration, which moves the project too, from a terminal outside the session: ${prefix}${packageCommand(harness, "upgrade", { version: pluginVersion(root) || "latest", args: `--project "${proj}"` })}`
-        : `This project's projectstore plugin${v} predates --no-register and cannot run the move as named: update it first (in Claude Code: /plugin marketplace update, then /plugin update, then restart), and the startup line names the command` };
+        : copyUpdateAdvice(copy, { cannot: "predates --no-register and cannot run the move as named", then }) };
     }
     return viaRegistration ? shell(copy.version) : own(copy.path);
   }
@@ -2032,7 +2054,7 @@ export async function runInstallChecks(cfg, proj, opts = {}) {
   let read = null;
   try { read = await readSurfaceStates(proj, opts); } catch {} // reported as a warn by checkHarnessSurfaces
   out.push(...await checkHarnessSurfaces(cfg, proj, { ...opts, read }));
-  if (read) out.push(...checkPluginRegistration(proj, read.result.states, { home: opts.home }));
+  if (read) out.push(...checkPluginRegistration(proj, read.result.states, { home: opts.home, cfg }));
   if (read) out.push(...checkVersionDrift(opts.home, read.result.states, proj));
   return foldIntoMove(out);
 }
@@ -2122,27 +2144,6 @@ export function runStartupChecks(cfg, proj, budgetMs = 150) {
 
 // ─── CLI ───────────────────────────────────────────────────────────────
 
-function icon(level) {
-  return level === "issue" ? "✖" : level === "warn" ? "⚠" : "ℹ";
-}
-
-function report(findings, groups) {
-  const ver = pluginVersion();
-  const lines = [`projectstore doctor — plugin v${ver || "?"}, ${new Date().toISOString().slice(0, 10)}`];
-  for (const g of groups) {
-    const fs = findings.filter((f) => f.group === g);
-    lines.push("", `## ${g} (${fs.filter((f) => f.level === "issue").length} issue(s), ${fs.filter((f) => f.level === "warn").length} warning(s))`);
-    if (!fs.length) lines.push("  ✓ clean");
-    for (const f of fs) {
-      lines.push(`  ${icon(f.level)} [${f.check}] ${f.message}${f.file ? `  — ${f.file}` : ""}`);
-    }
-  }
-  const issues = findings.filter((f) => f.level === "issue").length;
-  const warns = findings.filter((f) => f.level === "warn").length;
-  lines.push("", `Summary: ${issues} issue(s), ${warns} warning(s). ${issues ? `Repairs: ${commandForm("doctor", { args: "--fix" })} (install), ${commandForm("kanban")} / reconcile (vault).` : "Vault and wiring look healthy."}`);
-  return lines.join("\n");
-}
-
 async function main() {
   const args = process.argv.slice(2);
   const wantJson = args.includes("--json");
@@ -2171,7 +2172,24 @@ async function main() {
     findings.push(finding("vault", "info", "vault", "Vault checks skipped — no usable vault (see install issues)."));
   }
 
-  process.stdout.write((wantJson ? JSON.stringify(findings, null, 2) : report(findings, groups)) + "\n");
+  if (wantJson) { process.stdout.write(JSON.stringify(findings, null, 2) + "\n"); return; }
+  process.stdout.write(await textReport(findings, groups, { version: pluginVersion(), project: proj }));
+}
+
+// The text is the bin's renderer's, in its plain layout (the presentation
+// spec, contract 11) — one report, whoever prints it. Imported at run time,
+// and nowhere else in this file: the SessionStart hook imports this module
+// statically, and the renderer's term.mjs is not on its path. A renderer
+// that cannot load, or throws, costs the reader nothing: the findings one
+// per line and the Summary line, still last (lib.mjs). `load` is a test's.
+export async function textReport(findings, groups, { version = null, project = null, env = process.env, stderr = process.stderr } = {}, { load = () => import("./doctor-report.mjs") } = {}) {
+  try {
+    const { report } = await load();
+    return report(findings, groups, { version, project, env });
+  } catch (e) {
+    if (stderr) stderr.write(`doctor: the report could not be drawn (${e && e.message ? e.message : e}); its findings follow, one per line.\n`);
+    return doctorFallbackText(findings, { env });
+  }
 }
 
 if (isMain(import.meta.url)) {