crewhaus 0.2.4 → 0.3.0

package/dist/sessions-index.d.ts

@@ -5,23 +5,11 @@
  * knowledge (outcome, tools used, ratings, key facts) past raw-transcript
  * retention. These entries feed the memory-store / few-shot / FAQ features.
  *
- * The summary logic lives in `@crewhaus/session-store` (`summarizeSession`, a
- * deterministic no-model reducer). This module is the CLI-side glue: read a
- * session's JSONL, summarize it, and write the index entry idempotently. Kept
- * thin + separately testable, mirroring `feedback.ts` / `dataset-mine.ts`.
+ * v0.3.0 PR 14: the glue (`parseSessionLog`, `summarizeSessionIntoIndex`,
+ * `SESSIONS_INDEX_DIRNAME`) moved into `@crewhaus/session-store` — next to
+ * `summarizeSession`, which it always wrapped — so the dream engine's
+ * sessions fold-in step can call it without reaching into the CLI. This
+ * module stays as a re-export so `crewhaus sessions summarize` (and any
+ * other CLI import) is untouched.
  */
-import { type SessionSummary } from "@crewhaus/session-store";
-/** The index directory, relative to a session root's PARENT `.crewhaus`. */
-export declare const SESSIONS_INDEX_DIRNAME = "sessions-index";
-/** Parse a JSONL blob into `{ kind, payload }` events, skipping bad lines. */
-export declare function parseSessionLog(text: string): Array<{
-    kind?: string;
-    payload?: unknown;
-}>;
-/**
- * Summarize the session whose `.jsonl` lives at `logPath` into `indexDir`,
- * returning the written summary (or undefined when the log is missing/empty).
- * Idempotent: re-writing the same session overwrites its entry rather than
- * duplicating. `now` is injectable for deterministic tests.
- */
-export declare function summarizeSessionIntoIndex(sessionId: string, logPath: string, indexDir: string, now?: () => Date): SessionSummary | undefined;
+export { SESSIONS_INDEX_DIRNAME, parseSessionLog, summarizeSessionIntoIndex, } from "@crewhaus/session-store";

package/dist/sessions-index.js

@@ -5,47 +5,11 @@
  * knowledge (outcome, tools used, ratings, key facts) past raw-transcript
  * retention. These entries feed the memory-store / few-shot / FAQ features.
  *
- * The summary logic lives in `@crewhaus/session-store` (`summarizeSession`, a
- * deterministic no-model reducer). This module is the CLI-side glue: read a
- * session's JSONL, summarize it, and write the index entry idempotently. Kept
- * thin + separately testable, mirroring `feedback.ts` / `dataset-mine.ts`.
+ * v0.3.0 PR 14: the glue (`parseSessionLog`, `summarizeSessionIntoIndex`,
+ * `SESSIONS_INDEX_DIRNAME`) moved into `@crewhaus/session-store` — next to
+ * `summarizeSession`, which it always wrapped — so the dream engine's
+ * sessions fold-in step can call it without reaching into the CLI. This
+ * module stays as a re-export so `crewhaus sessions summarize` (and any
+ * other CLI import) is untouched.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { summarizeSession } from "@crewhaus/session-store";
-/** The index directory, relative to a session root's PARENT `.crewhaus`. */
-export const SESSIONS_INDEX_DIRNAME = "sessions-index";
-/** Parse a JSONL blob into `{ kind, payload }` events, skipping bad lines. */
-export function parseSessionLog(text) {
-    const out = [];
-    for (const line of text.split("\n")) {
-        if (line.trim() === "")
-            continue;
-        try {
-            out.push(JSON.parse(line));
-        }
-        catch {
-            // A single malformed line must not abort the summary.
-        }
-    }
-    return out;
-}
-/**
- * Summarize the session whose `.jsonl` lives at `logPath` into `indexDir`,
- * returning the written summary (or undefined when the log is missing/empty).
- * Idempotent: re-writing the same session overwrites its entry rather than
- * duplicating. `now` is injectable for deterministic tests.
- */
-export function summarizeSessionIntoIndex(sessionId, logPath, indexDir, now = () => new Date()) {
-    if (!existsSync(logPath))
-        return undefined;
-    const events = parseSessionLog(readFileSync(logPath, "utf-8"));
-    if (events.length === 0)
-        return undefined;
-    const summary = summarizeSession(sessionId, events, { now });
-    mkdirSync(indexDir, { recursive: true });
-    writeFileSync(join(indexDir, `${sessionId}.json`), `${JSON.stringify(summary, null, 2)}\n`, {
-        mode: 0o600,
-    });
-    return summary;
-}
+export { SESSIONS_INDEX_DIRNAME, parseSessionLog, summarizeSessionIntoIndex, } from "@crewhaus/session-store";

package/dist/thredz-probe.d.ts

@@ -0,0 +1,36 @@
+import { type UnresolvedMcpServerConfig } from "@crewhaus/mcp-host";
+import type { DoctorCredentialCheck } from "./doctor-checks";
+/**
+ * Extract the thredz MCP server config from a spec text, or undefined when
+ * the spec has no `thredz:` block (or does not parse/lower — doctor's other
+ * checks own spec validity; the probe never doubles up on those errors).
+ */
+export declare function thredzProbeTarget(specText: string): UnresolvedMcpServerConfig | undefined;
+export type ThredzProbeResult = {
+    readonly pass: boolean;
+    /** Human-readable outcome ("wiki_stats ok (89ms)" / "thredz_billing — …"). */
+    readonly detail: string;
+    /** The classified failure (thredz_* | config | mcp_boot) on a miss. */
+    readonly failureClass?: string;
+};
+export type ThredzProbeDeps = {
+    /** Env consulted for the config's secret refs. Default `process.env`. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** Injected clock for deterministic durations in tests. */
+    readonly now?: () => number;
+    /**
+     * Injected call seam (tests): given the RESOLVED config, return the
+     * `wiki_stats` result. Production spawns the configured server through
+     * McpHost — the same transport the run path uses.
+     */
+    readonly call?: (config: {
+        transport: string;
+    }) => Promise<{
+        content: string;
+        isError: boolean;
+    }>;
+};
+/** Run the live `wiki_stats` round-trip against the configured server. */
+export declare function probeThredz(config: UnresolvedMcpServerConfig, deps?: ThredzProbeDeps): Promise<ThredzProbeResult>;
+/** Fold the probe result into doctor's ✓/✗ check shape. */
+export declare function thredzProbeToCheck(result: ThredzProbeResult): DoctorCredentialCheck;

package/dist/thredz-probe.js

@@ -0,0 +1,93 @@
+/**
+ * v0.3.0 Goal 3 (design §4.4) — `crewhaus doctor --probe`'s Thredz check: a
+ * live `wiki_stats` round-trip through the SAME synthesized (or
+ * user-declared) `mcp_servers.thredz` config the run path boots, so what
+ * passes here is exactly what a run will do. One cheap read call — no
+ * writes, no quota consumption.
+ *
+ * Failures classify through the wiring layer's one error-mapping choke
+ * point (`classifyThredzFailure`): a disabled key reports `thredz_billing`,
+ * a plan cap `thredz_quota`, a missing THREDZ_API_KEY a `config` failure
+ * naming the variable, and a server that won't boot `mcp_boot` — doctor's ✗
+ * line names the fix class instead of dumping a raw MCP error.
+ *
+ * Factored out of the entry file `index.ts` (which runs a top-level argv
+ * switch and so cannot be imported by a test without executing the CLI).
+ * Target extraction is pure; the prober takes an injected `call` seam so
+ * tests drive it without spawning a real server.
+ */
+import { lower } from "@crewhaus/compiler";
+import { McpHost, resolveMcpServerConfig, } from "@crewhaus/mcp-host";
+import { classifyThredzFailure } from "@crewhaus/memory-service";
+import { parseSpec } from "@crewhaus/spec";
+/**
+ * Extract the thredz MCP server config from a spec text, or undefined when
+ * the spec has no `thredz:` block (or does not parse/lower — doctor's other
+ * checks own spec validity; the probe never doubles up on those errors).
+ */
+export function thredzProbeTarget(specText) {
+    try {
+        const ir = lower(parseSpec(specText));
+        if (ir.thredz === undefined)
+            return undefined;
+        return ir.mcp_servers?.["thredz"];
+    }
+    catch {
+        return undefined;
+    }
+}
+/** First line, capped — doctor rows stay one line. */
+function firstLine(text, cap = 160) {
+    const line = text.split("\n", 1)[0] ?? "";
+    return line.length > cap ? `${line.slice(0, cap)}…` : line;
+}
+/** Run the live `wiki_stats` round-trip against the configured server. */
+export async function probeThredz(config, deps = {}) {
+    const now = deps.now ?? (() => performance.now());
+    const startMs = now();
+    // Secret resolution first: a missing THREDZ_API_KEY is a `config` failure
+    // that NAMES the variable (the §4.4 boot contract), not a server error.
+    let resolved;
+    try {
+        resolved = resolveMcpServerConfig(config, {
+            name: "thredz",
+            ...(deps.env !== undefined ? { env: deps.env } : {}),
+        });
+    }
+    catch (err) {
+        return { pass: false, failureClass: "config", detail: `config — ${err.message}` };
+    }
+    let result;
+    const host = new McpHost();
+    try {
+        if (deps.call !== undefined) {
+            result = await deps.call(resolved);
+        }
+        else {
+            const client = host.addServer("thredz", resolved);
+            await client.connect();
+            result = await client.callTool("wiki_stats", {});
+        }
+    }
+    catch (err) {
+        return {
+            pass: false,
+            failureClass: "mcp_boot",
+            detail: `mcp_boot — ${firstLine(err.message)}`,
+        };
+    }
+    finally {
+        await host.disconnectAll();
+    }
+    if (result.isError) {
+        const failureClass = classifyThredzFailure(result.content);
+        return { pass: false, failureClass, detail: `${failureClass} — ${firstLine(result.content)}` };
+    }
+    return { pass: true, detail: `wiki_stats ok (${Math.round(now() - startMs)}ms)` };
+}
+/** Fold the probe result into doctor's ✓/✗ check shape. */
+export function thredzProbeToCheck(result) {
+    return result.pass
+        ? { label: `live probe: thredz (wiki_stats) — ${result.detail}`, pass: true }
+        : { label: "live probe: thredz (wiki_stats)", pass: false, reason: result.detail };
+}

package/dist/upgrade.d.ts

@@ -12,10 +12,45 @@ import { type SpecDiffEntry } from "@crewhaus/spec-patch";
  * migrated spec was written UNCHECKED; here every migrated spec must parse
  * before it can be written.
  *
+ * v0.3.0 (PR 20) — the assistant also carries RELEASE notes: informational,
+ * per-spec 0.2.x→0.3.0 prompts (see {@link collect030UpgradeNotes}). They are
+ * deliberately NOT `Migration` entries on the engine: 0.3.0 changes zero spec
+ * SYNTAX (old specs parse unchanged — no schema-version bump to migrate), it
+ * changes compile-time BEHAVIOR (default-on continuity, MCP env/header secret
+ * lowering) and store formats (`crewhaus migrate memories`). Notes never
+ * mutate the spec; each one tells the author the exact line or command.
+ *
  * Side-effect-free: `planUpgrade` is a pure function over the spec text + an
  * injected engine + validator. The CLI wrapper reads/writes the file and prints.
  */
 export type UpgradeAction = "up-to-date" | "upgrade" | "ahead" | "validate-fail";
+/** One informational 0.2.x→0.3.0 prompt for the spec being upgraded. */
+export type UpgradeNote = {
+    /** Stable identity for tests/tooling (`continuity-default-on`, …). */
+    readonly id: string;
+    /** One-line headline. */
+    readonly title: string;
+    /** Follow-up lines, rendered indented under the headline. */
+    readonly body: ReadonlyArray<string>;
+};
+/**
+ * v0.3.0 (PR 20) — collect the 0.2.x→0.3.0 release notes that apply to THIS
+ * spec. Pure over the YAML text; returns `[]` for unparseable YAML (the plan
+ * itself reports that) and for specs the release doesn't affect.
+ *
+ *   - `continuity-default-on`: an agent-loop spec with no textual
+ *     `continuity:` key recompiles with the continuity fabric wired; the note
+ *     offers the one-line `continuity: false` pin that restores the 0.2.x
+ *     bundle byte-for-byte.
+ *   - `migrate-memories`: a `memory:` spec has fact stores under
+ *     `.crewhaus/memories/` — the note points at the idempotent
+ *     `crewhaus migrate memories` v2 backfill.
+ *   - `mcp-secret-lowering`: `mcp_servers` env/headers values are now lowered
+ *     through the `$UPPER_SNAKE` secret machinery — resolved from the running
+ *     process env at boot, with malformed `$…` refs under credential-shaped
+ *     keys failing compilation (behavior note, no spec change needed).
+ */
+export declare function collect030UpgradeNotes(yamlText: string): ReadonlyArray<UpgradeNote>;
 export type UpgradePlan = {
     readonly action: UpgradeAction;
     /** The spec's current schema version (`version ?? 0`). */
@@ -28,6 +63,13 @@ export type UpgradePlan = {
     readonly diff?: ReadonlyArray<SpecDiffEntry>;
     /** Failure detail for `action: "validate-fail"`. */
     readonly error?: string;
+    /**
+     * v0.3.0 — the informational 0.2.x→0.3.0 release notes that apply to this
+     * spec (see {@link collect030UpgradeNotes}). Present for every parseable
+     * spec, INCLUDING `up-to-date`: the schema-version stamp is orthogonal to
+     * the release's behavior changes.
+     */
+    readonly notes?: ReadonlyArray<UpgradeNote>;
 };
 /**
  * Compute the upgrade plan for a spec's YAML against `engine`.

package/dist/upgrade.js

@@ -1,5 +1,92 @@
-import { diffSpecYaml } from "@crewhaus/spec-patch";
+import { diffSpecYaml, specHasPath } from "@crewhaus/spec-patch";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+/** The agent-loop shapes on which 0.3.0's continuity fabric is default-on. */
+const CONTINUITY_DEFAULT_ON_TARGETS = new Set([
+    "cli",
+    "channel",
+    "managed",
+    "research",
+    "crew",
+]);
+/**
+ * v0.3.0 (PR 20) — collect the 0.2.x→0.3.0 release notes that apply to THIS
+ * spec. Pure over the YAML text; returns `[]` for unparseable YAML (the plan
+ * itself reports that) and for specs the release doesn't affect.
+ *
+ *   - `continuity-default-on`: an agent-loop spec with no textual
+ *     `continuity:` key recompiles with the continuity fabric wired; the note
+ *     offers the one-line `continuity: false` pin that restores the 0.2.x
+ *     bundle byte-for-byte.
+ *   - `migrate-memories`: a `memory:` spec has fact stores under
+ *     `.crewhaus/memories/` — the note points at the idempotent
+ *     `crewhaus migrate memories` v2 backfill.
+ *   - `mcp-secret-lowering`: `mcp_servers` env/headers values are now lowered
+ *     through the `$UPPER_SNAKE` secret machinery — resolved from the running
+ *     process env at boot, with malformed `$…` refs under credential-shaped
+ *     keys failing compilation (behavior note, no spec change needed).
+ */
+export function collect030UpgradeNotes(yamlText) {
+    let parsed;
+    try {
+        parsed = parseYaml(yamlText);
+    }
+    catch {
+        return [];
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return [];
+    const spec = parsed;
+    const target = typeof spec["target"] === "string" ? spec["target"] : "";
+    const notes = [];
+    if (CONTINUITY_DEFAULT_ON_TARGETS.has(target) && !specHasPath(yamlText, ["continuity"])) {
+        notes.push({
+            id: "continuity-default-on",
+            title: "0.3.0 recompiles this spec with continuity ON by default",
+            body: [
+                "Persistent focus/plans/goals, the requirements ledger, and teardown",
+                "handoff.md are wired without a spec change (the release's one sanctioned",
+                "behavior change). Want the exact 0.2.x bundle back? Add one line:",
+                "  continuity: false   # restores the previous bundle byte-for-byte",
+            ],
+        });
+    }
+    if (specHasPath(yamlText, ["memory"])) {
+        notes.push({
+            id: "migrate-memories",
+            title: "existing fact stores can take the optional v2 backfill",
+            body: [
+                "0.3.0 memory entries carry provenance/TTL/status fields; old stores keep",
+                "reading as-is. Run `crewhaus migrate memories [--dry-run]` once to",
+                "backfill .crewhaus/memories/*.jsonl in place (idempotent).",
+            ],
+        });
+    }
+    const mcpServers = spec["mcp_servers"];
+    if (typeof mcpServers === "object" && mcpServers !== null && !Array.isArray(mcpServers)) {
+        const affected = Object.entries(mcpServers)
+            .filter(([, cfg]) => {
+            if (typeof cfg !== "object" || cfg === null || Array.isArray(cfg))
+                return false;
+            const c = cfg;
+            return c["env"] !== undefined || c["headers"] !== undefined;
+        })
+            .map(([name]) => name);
+        if (affected.length > 0) {
+            notes.push({
+                id: "mcp-secret-lowering",
+                title: `mcp_servers env/headers are now secret-lowered (${affected.join(", ")})`,
+                body: [
+                    "Values route through the $UPPER_SNAKE secret machinery: `$VAR` resolves",
+                    "from the RUNNING process env at boot (no longer baked into the bundle),",
+                    "and a malformed `$…` ref under a credential-shaped key (*_KEY / *_TOKEN /",
+                    "*_SECRET / *_PASSWORD, Authorization, x-api-key) now fails compilation.",
+                    "Recompile and make sure those variables are exported where the harness runs.",
+                ],
+            });
+        }
+    }
+    return notes;
+}
 /**
  * Compute the upgrade plan for a spec's YAML against `engine`.
  *
@@ -29,11 +116,12 @@ export function planUpgrade(yamlText, engine, validate) {
         };
     }
     const fromVersion = (parsed?.version ?? 0) | 0;
+    const notes = collect030UpgradeNotes(yamlText);
     if (fromVersion === toVersion) {
-        return { action: "up-to-date", fromVersion, toVersion };
+        return { action: "up-to-date", fromVersion, toVersion, notes };
     }
     if (fromVersion > toVersion) {
-        return { action: "ahead", fromVersion, toVersion };
+        return { action: "ahead", fromVersion, toVersion, notes };
     }
     let migrated;
     try {
@@ -62,7 +150,7 @@ export function planUpgrade(yamlText, engine, validate) {
     }
     const migratedYaml = stringifyYaml(migrated);
     const diff = diffSpecYaml(yamlText, migratedYaml);
-    return { action: "upgrade", fromVersion, toVersion, migratedYaml, diff };
+    return { action: "upgrade", fromVersion, toVersion, migratedYaml, diff, notes };
 }
 /**
  * Build the validate callback the CLI passes to {@link planUpgrade}: it
@@ -76,12 +164,28 @@ export function makeSpecValidator(parse) {
         parse(stringifyYaml(spec));
     };
 }
+/** Render the 0.2.x→0.3.0 notes block (empty string when no notes apply). */
+function formatUpgradeNotes(notes) {
+    if (notes === undefined || notes.length === 0)
+        return "";
+    const lines = [
+        "",
+        "  0.2.x → 0.3.0 notes for this spec (informational — nothing is rewritten):",
+    ];
+    for (const note of notes) {
+        lines.push(`  • ${note.title}`);
+        for (const bodyLine of note.body) {
+            lines.push(`      ${bodyLine}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
 /** Render an upgrade plan as the human-readable report. `write` toggles the
  *  "would apply" vs "applied" wording; returns the block. */
 export function formatUpgradePlan(plan, write) {
     switch (plan.action) {
         case "up-to-date":
-            return `upgrade: spec is already at the current version (v${plan.toVersion}) — nothing to do.\n`;
+            return `upgrade: spec is already at the current version (v${plan.toVersion}) — nothing to do.\n${formatUpgradeNotes(plan.notes)}`;
         case "ahead":
             return `upgrade: spec version v${plan.fromVersion} is NEWER than this CLI supports (v${plan.toVersion}).\n  Upgrade the CLI (\`brew upgrade crewhaus\` / \`npm i -g crewhaus\`) rather than downgrading the spec.\n`;
         case "validate-fail":
@@ -107,7 +211,7 @@ export function formatUpgradePlan(plan, write) {
             lines.push(write
                 ? "  applied — spec rewritten in place."
                 : "  dry-run — re-run with --write to apply.");
-            return `${lines.join("\n")}\n`;
+            return `${lines.join("\n")}\n${formatUpgradeNotes(plan.notes)}`;
         }
     }
 }

package/dist/wiki-cli.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 0.3.0 memory release (design §3.1/§3.2) — the `crewhaus wiki` verb
+ * cluster's pure/IO helpers. Kept thin + separately testable, mirroring
+ * `memory-cli.ts` (the entry file runs an argv switch on import, so logic
+ * lives here). Read-only verbs only in PR 9 — `clear|restore` ride the
+ * continuity trash machinery and `push|pull --thredz` the Thredz PR.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import type { WikiArticle, WikiRef, WikiStats } from "@crewhaus/wiki-store";
+export declare class WikiCliError extends CrewhausError {
+    readonly name = "WikiCliError";
+    constructor(message: string, cause?: unknown);
+}
+/** The wiki root, relative to a harness cwd. */
+export declare const WIKI_SUBDIR: string;
+/** Spec names that have a wiki directory under `wikiDir`, sorted. A spec
+ *  counts once it has an articles/ dir or an index.json (an empty scaffold
+ *  directory is not a wiki yet). */
+export declare function listWikiSpecs(wikiDir: string): string[];
+/**
+ * Resolve which spec's wiki a single-target verb operates on: an explicit
+ * `--spec` wins; otherwise a lone wiki is unambiguous; anything else is an
+ * error naming the candidates. Mirrors `resolveMemorySpec`.
+ */
+export declare function resolveWikiSpec(wikiDir: string, specFlag?: string): string;
+/** Compact human age: "3m", "7h", "12d". Injectable clock for tests. */
+export declare function humanAge(updatedAtIso: string, nowMs: number): string;
+/**
+ * Render one `wiki list` row: slug / version / age / status flag /
+ * verified+confidence signals / title / tags. Deterministic given `nowMs`.
+ */
+export declare function renderWikiListRow(ref: WikiRef, nowMs: number): string;
+/** Render the `wiki list` block for one spec's refs (already sorted). */
+export declare function renderWikiList(specName: string, refs: ReadonlyArray<WikiRef>, nowMs: number): string[];
+/** Render `wiki show <slug>`: full frontmatter + the body verbatim. */
+export declare function renderWikiShow(article: WikiArticle): string[];
+/** Render `wiki search <q>` results (refs are already ranked best-first). */
+export declare function renderWikiSearch(specName: string, query: string, refs: ReadonlyArray<WikiRef>): string[];
+/** Render `wiki stats` for one spec. */
+export declare function renderWikiStats(specName: string, stats: WikiStats): string[];

package/dist/wiki-cli.js

@@ -0,0 +1,133 @@
+/**
+ * 0.3.0 memory release (design §3.1/§3.2) — the `crewhaus wiki` verb
+ * cluster's pure/IO helpers. Kept thin + separately testable, mirroring
+ * `memory-cli.ts` (the entry file runs an argv switch on import, so logic
+ * lives here). Read-only verbs only in PR 9 — `clear|restore` ride the
+ * continuity trash machinery and `push|pull --thredz` the Thredz PR.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+export class WikiCliError extends CrewhausError {
+    name = "WikiCliError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+/** The wiki root, relative to a harness cwd. */
+export const WIKI_SUBDIR = join(".crewhaus", "wiki");
+/** Spec names that have a wiki directory under `wikiDir`, sorted. A spec
+ *  counts once it has an articles/ dir or an index.json (an empty scaffold
+ *  directory is not a wiki yet). */
+export function listWikiSpecs(wikiDir) {
+    if (!existsSync(wikiDir))
+        return [];
+    return readdirSync(wikiDir)
+        .filter((d) => existsSync(join(wikiDir, d, "articles")) || existsSync(join(wikiDir, d, "index.json")))
+        .sort();
+}
+/**
+ * Resolve which spec's wiki a single-target verb operates on: an explicit
+ * `--spec` wins; otherwise a lone wiki is unambiguous; anything else is an
+ * error naming the candidates. Mirrors `resolveMemorySpec`.
+ */
+export function resolveWikiSpec(wikiDir, specFlag) {
+    const specs = listWikiSpecs(wikiDir);
+    if (specFlag !== undefined) {
+        if (!specs.includes(specFlag)) {
+            throw new WikiCliError(`no wiki for spec "${specFlag}" under ${wikiDir}${specs.length > 0 ? ` (have: ${specs.join(", ")})` : ""}`);
+        }
+        return specFlag;
+    }
+    if (specs.length === 0) {
+        throw new WikiCliError(`no wikis under ${wikiDir}`);
+    }
+    if (specs.length === 1)
+        return specs[0];
+    throw new WikiCliError(`multiple wikis under ${wikiDir} — pick one with --spec <name> (have: ${specs.join(", ")})`);
+}
+/** Compact human age: "3m", "7h", "12d". Injectable clock for tests. */
+export function humanAge(updatedAtIso, nowMs) {
+    const updated = Date.parse(updatedAtIso);
+    if (Number.isNaN(updated))
+        return "?";
+    const deltaMs = Math.max(0, nowMs - updated);
+    const minutes = Math.floor(deltaMs / 60_000);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}
+const TITLE_PREVIEW_LEN = 48;
+function previewTitle(title) {
+    const oneLine = title.replace(/\s+/g, " ").trim();
+    return oneLine.length > TITLE_PREVIEW_LEN
+        ? `${oneLine.slice(0, TITLE_PREVIEW_LEN - 1)}…`
+        : oneLine;
+}
+/**
+ * Render one `wiki list` row: slug / version / age / status flag /
+ * verified+confidence signals / title / tags. Deterministic given `nowMs`.
+ */
+export function renderWikiListRow(ref, nowMs) {
+    const age = humanAge(ref.updatedAt, nowMs).padStart(4);
+    const statusCol = (ref.status === "published" ? "" : ref.status).padEnd(8);
+    const signalsCol = `${ref.verified ? "✓" : " "}${ref.confidence.toFixed(2)}`;
+    const tagsCol = ref.tags.length > 0 ? ` [${ref.tags.join(", ")}]` : "";
+    return `  ${ref.slug.padEnd(28)}  v${String(ref.version).padEnd(3)}  ${age}  ${statusCol}  ${signalsCol}  ${previewTitle(ref.title)}${tagsCol}`;
+}
+/** Render the `wiki list` block for one spec's refs (already sorted). */
+export function renderWikiList(specName, refs, nowMs) {
+    const verified = refs.filter((r) => r.verified).length;
+    const lines = [
+        `[wiki] ${specName} — ${refs.length} article(s), ${verified} verified (stalest first)`,
+    ];
+    for (const ref of refs)
+        lines.push(renderWikiListRow(ref, nowMs));
+    return lines;
+}
+/** Render `wiki show <slug>`: full frontmatter + the body verbatim. */
+export function renderWikiShow(article) {
+    const lines = [
+        `slug:        ${article.slug}`,
+        `title:       ${article.title}`,
+        `version:     ${article.version}${article.supersedes !== undefined ? ` (supersedes v${article.supersedes} — priors in versions/${article.slug}/)` : ""}`,
+        `status:      ${article.status}`,
+        `verified:    ${article.verified}`,
+        `confidence:  ${article.confidence.toFixed(2)}`,
+        `tags:        ${article.tags.length > 0 ? article.tags.join(", ") : "(none)"}`,
+        `sources:     ${article.sources.length > 0 ? article.sources.join(" · ") : "(none)"}`,
+        `created:     ${article.createdAt}`,
+        `updated:     ${article.updatedAt}`,
+    ];
+    if (article.createdBy !== undefined) {
+        lines.push(`createdBy:   session ${article.createdBy.sessionId}${article.createdBy.agentIdentity !== undefined ? ` · ${article.createdBy.agentIdentity}` : ""}`);
+    }
+    lines.push("", article.body);
+    return lines;
+}
+/** Render `wiki search <q>` results (refs are already ranked best-first). */
+export function renderWikiSearch(specName, query, refs) {
+    if (refs.length === 0) {
+        return [`[wiki] ${specName} — no articles matched "${query}"`];
+    }
+    const lines = [`[wiki] ${specName} — ${refs.length} match(es) for "${query}":`];
+    for (const ref of refs) {
+        lines.push(`  ${ref.slug} (v${ref.version})  ${previewTitle(ref.title)}`);
+    }
+    return lines;
+}
+/** Render `wiki stats` for one spec. */
+export function renderWikiStats(specName, stats) {
+    return [
+        `[wiki] ${specName}`,
+        `  articles:        ${stats.articles} (published ${stats.byStatus.published}, draft ${stats.byStatus.draft}, review ${stats.byStatus.review}, archived ${stats.byStatus.archived})`,
+        `  prior versions:  ${stats.priorVersions}`,
+        `  unique tags:     ${stats.uniqueTags}`,
+        `  verified:        ${stats.verified}`,
+        `  avg confidence:  ${stats.averageConfidence.toFixed(2)}`,
+        `  link edges:      ${stats.links}`,
+    ];
+}