@uniqbit/mate-core 0.18.4 → 1.0.0-canary.0

package/src/cli/commands/doctor.ts

@@ -1,15 +1,21 @@
 import { execFileSync } from "node:child_process";
+import fs from "node:fs/promises";
 import path from "node:path";
 
+import { parse as parseYaml } from "yaml";
+
 import { FRAMEWORK_NAME } from "../../framework";
 import { gitEnvironment } from "../../runtime/companion-git";
-import { readWrapStateSync } from "../../runtime/wrap-state";
+import { companionClaudeMdHasOwnText } from "../../runtime/companion-instructions";
 import { getActiveDistribution } from "../../distribution";
+import { hasOpenspecCapability } from "../../lib/orchestrator/capabilities";
 import { checkEngineRequirement } from "../../lib/orchestrator/engine-guard";
 import type { GlobalConfigStore } from "../../lib/orchestrator/global-config-store";
 import { pathIsDirectory } from "../../lib/fs-utils";
 import { resolveRootContext, type RootContext } from "../../lib/orchestrator/root-context";
 import type { CapabilityConfig, FrameworkConfig, HubMember } from "../../lib/orchestrator/types";
+import { locateOpenSpec, type OpenSpecLocation } from "../../lib/openspec-cli";
+import { MATE_CLAUDE_PLUGIN_NAME } from "../../lib/package-paths";
 import {
   describeUnknownAudience,
   readAudienceSelection,
@@ -20,12 +26,20 @@ import {
   type PluginInspection,
   type PluginVerificationFailure,
 } from "../../tools/setup/dynamic-plugins/verify";
+import { hydrateDynamicPlugins } from "../../tools/setup/dynamic-plugins/hydrate";
 import {
-  inspectAudienceIsolation,
-  type AudienceIsolationReport,
-} from "../../tools/setup/isolation-diagnostics";
+  inspectClaudePluginDirectories,
+  type ClaudePluginDirectoryInspection,
+} from "../../tools/setup";
 import { getRequiredPluginDrift } from "../../tools/setup/policy";
-import type { PluginRegistry } from "../../tools/setup/registry";
+import {
+  CLAUDE_PLUGIN_MANIFEST,
+  CLAUDE_PLUGIN_MARKETPLACE,
+  type ClaudePluginContributionFailure,
+  type ClaudePluginDirectoryProblem,
+  type ClaudePluginDirectoryReport,
+  type ClaudePluginUnpublishedReason,
+} from "../../tools/setup/providers/claude-plugin-folders";
 import { resolveCommandOnPath } from "../../tools/setup/utils";
 import { writeJsonStdout } from "../write-json-stdout";
 import { printSection, renderKeyValueTable, renderTable } from "./status";
@@ -37,10 +51,14 @@ interface DoctorDeps {
   /** Returns a member checkout's HEAD commit, or null when unreadable. */
   gitHead?: (memberPath: string) => string | null;
   inspectPlugins?: (companionPath: string) => Promise<PluginInspection>;
+  /** Loads the companion's declared plugins so their Capabilities contribute. */
+  hydratePlugins?: (companionPath: string) => Promise<void>;
+  inspectClaudePlugins?: (
+    companionPath: string,
+    config: FrameworkConfig,
+  ) => Promise<ClaudePluginDirectoryInspection>;
   /** Environment `MATE_AUDIENCE` is read from; defaults to the process environment. */
   env?: Record<string, string | undefined>;
-  /** The hydrated registry; the active distribution's when absent. */
-  registry?: PluginRegistry;
 }
 
 export type DoctorKind = "core" | "working" | "companion" | "hub";
@@ -50,6 +68,8 @@ export interface DoctorToolInstallation {
   source: string;
   status: "ok" | "missing";
   path: string | null;
+  /** Set for a tool Mate ships itself, such as the OpenSpec CLI. */
+  version?: string;
 }
 
 export interface DoctorHubMember {
@@ -74,18 +94,26 @@ export interface DoctorReport {
   toolInstallations?: DoctorToolInstallation[];
   requiredPluginDrift?: Array<{ pluginId: string; kind: string; reason: string }>;
   pluginFailures?: PluginVerificationFailure[];
-  /**
-   * Present for a companion that declares audiences or has one selected.
-   * `wrapped` is the audience the working repository is wrapped for, when any.
-   */
-  audiences?: { declared: string[]; active: string | null; wrapped?: string };
+  /** Present for a companion that declares audiences or has one selected. */
+  audiences?: { declared: string[]; active: string | null };
   /** Set when `MATE_AUDIENCE` names an audience the companion does not declare. */
   audienceError?: string;
-  /** Present when an audience's contributions reached a persisted surface, or a launch layer cannot deliver part of one. */
-  audienceIsolation?: AudienceIsolationReport;
   /** IDs of the capabilities the verified plugins provide. */
   pluginCapabilities?: string[];
   engineRequirement?: { range: string; ok: boolean; detail: string };
+  /** Present when the companion's `openspec/config.yaml` has `rules` keys OpenSpec ignores. */
+  openspecRuleWarnings?: Array<{ key: string; message: string }>;
+  /** Present when the companion `CLAUDE.md` holds text no Working Repository session receives. */
+  companionInstructionWarnings?: Array<{ file: string; message: string }>;
+  /**
+   * Enabled Capabilities' Claude plugin folders, which load only with `mate claude`; absent when
+   * none. `problem` names why `mate claude` leaves a folder out: `not-absolute`,
+   * `missing-manifest`, `bundled-mate-plugin` (Mate's own plugin, which every managed launch
+   * loads already) or `mate-plugin-name` (its manifest uses Mate's plugin name).
+   */
+  claudePlugins?: ClaudePluginDirectoryReport[];
+  /** Capabilities whose contributions failed, so their Claude plugin folders are unknown; absent when none. */
+  claudePluginFailures?: ClaudePluginContributionFailure[];
   hub?: { members: DoctorHubMember[] };
   resolutionFailures: Array<{ companionPath: string; message: string }>;
 }
@@ -94,6 +122,8 @@ interface ToolCheck {
   name: string;
   command: string;
   source: string;
+  /** Locates a tool Mate ships instead of looking it up on PATH. */
+  bundled?: () => OpenSpecLocation;
 }
 
 /** Doctor's view of the shared root kind: registry/env resolution means cwd is a working repo. */
@@ -134,7 +164,12 @@ function getSelectedToolChecks(config: {
     checks.push({ name: "uv", command: "uv", source: "package manager" });
   }
   if (selectedCapabilities.has("openspec")) {
-    checks.push({ name: "openspec", command: "openspec", source: "capability" });
+    checks.push({
+      name: "openspec",
+      command: "openspec",
+      source: "capability",
+      bundled: locateOpenSpec,
+    });
   }
   if (selectedCapabilities.has("tokensave")) {
     checks.push({ name: "tokensave", command: "tokensave", source: "capability" });
@@ -154,6 +189,21 @@ function collectToolInstallations(
   pathValue: string,
 ): DoctorToolInstallation[] {
   return getSelectedToolChecks(config).map((check) => {
+    if (check.bundled) {
+      const source = `${check.source}, bundled with ${FRAMEWORK_NAME}`;
+      const location = check.bundled();
+      if ("missing" in location) {
+        return { tool: check.name, source, status: "missing", path: null };
+      }
+      // An unreadable manifest only loses the version; the CLI itself resolved.
+      return {
+        tool: check.name,
+        source,
+        status: "ok",
+        path: location.bin,
+        ...(location.version ? { version: location.version } : {}),
+      };
+    }
     const resolved = resolveCommandOnPath(check.command, pathValue);
     return {
       tool: check.name,
@@ -243,21 +293,92 @@ function collectAudiences(
   report: DoctorReport,
   config: FrameworkConfig,
   env: Record<string, string | undefined>,
-  repositoryPath: string | null,
 ): void {
   const declared = Object.keys(config.audiences ?? {});
   const requested = readAudienceSelection(env);
   if (declared.length === 0 && requested === null) return;
   const resolution = resolveAudience(config, requested);
-  const wrapped = repositoryPath ? readWrapStateSync(repositoryPath).audience : null;
-  report.audiences = {
-    declared,
-    active: resolution.ok ? resolution.active : null,
-    ...(wrapped ? { wrapped } : {}),
-  };
+  report.audiences = { declared, active: resolution.ok ? resolution.active : null };
   if (!resolution.ok) report.audienceError = describeUnknownAudience(resolution);
 }
 
+/** Artifact IDs of OpenSpec's built-in `spec-driven` schema. */
+const BUILT_IN_OPENSPEC_ARTIFACTS = ["proposal", "specs", "design", "tasks"];
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+/** Built-in IDs plus every `artifacts[].id` from a `schema.yaml` under the companion's `openspec/schemas/`. */
+async function knownOpenSpecArtifactIds(companionPath: string): Promise<Set<string>> {
+  const schemasDir = path.join(companionPath, "openspec", "schemas");
+  let schemaNames: string[] = [];
+  try {
+    schemaNames = await fs.readdir(schemasDir);
+  } catch {
+    /* no companion schemas */
+  }
+  const schemaIds = await Promise.all(
+    schemaNames.map(async (name) => {
+      try {
+        const schema = asRecord(
+          parseYaml(await fs.readFile(path.join(schemasDir, name, "schema.yaml"), "utf8")),
+        );
+        const artifacts: unknown[] = Array.isArray(schema?.artifacts) ? schema.artifacts : [];
+        return artifacts.flatMap((artifact) => {
+          const id = asRecord(artifact)?.id;
+          return typeof id === "string" ? [id] : [];
+        });
+      } catch {
+        return []; // not a readable schema
+      }
+    }),
+  );
+  return new Set([...BUILT_IN_OPENSPEC_ARTIFACTS, ...schemaIds.flat()]);
+}
+
+/**
+ * OpenSpec ignores a `rules` key that names no artifact, warning only on stderr
+ * of the command that reads it. Read-only; a missing or unparseable config is silent.
+ */
+async function collectOpenSpecRuleWarnings(
+  companionPath: string,
+): Promise<NonNullable<DoctorReport["openspecRuleWarnings"]>> {
+  let rules: Record<string, unknown> | undefined;
+  try {
+    const config = parseYaml(
+      await fs.readFile(path.join(companionPath, "openspec", "config.yaml"), "utf8"),
+    );
+    rules = asRecord(asRecord(config)?.rules);
+  } catch {
+    return [];
+  }
+  if (!rules) return [];
+
+  const known = await knownOpenSpecArtifactIds(companionPath);
+  return Object.keys(rules)
+    .filter((key) => !known.has(key))
+    .map((key) => ({
+      key,
+      message: `rules.${key} matches no OpenSpec artifact and is ignored; put workflow guidance in operations.apply.guidance or operations.archive.guidance`,
+    }));
+}
+
+function collectCompanionInstructionWarnings(
+  companionPath: string,
+): NonNullable<DoctorReport["companionInstructionWarnings"]> {
+  if (!companionClaudeMdHasOwnText(companionPath)) return [];
+  const file = path.join(companionPath, "CLAUDE.md");
+  return [
+    {
+      file,
+      message: `${file} holds text besides @AGENTS.md and Mate-managed blocks. That text does not reach Working Repository sessions, only sessions started in the companion. Move rules meant for every session into ${path.join(companionPath, "AGENTS.md")}.`,
+    },
+  ];
+}
+
 export async function collectDoctorReport(deps: DoctorDeps = {}): Promise<DoctorReport> {
   const cwd = path.resolve(deps.cwd ?? process.cwd());
   const pathValue = deps.pathValue ?? process.env.PATH ?? "";
@@ -293,16 +414,33 @@ export async function collectDoctorReport(deps: DoctorDeps = {}): Promise<Doctor
 
   const env = deps.env ?? process.env;
   if (root.rootPath && root.config && kind !== "hub") {
-    collectAudiences(report, root.config, env, root.linkedRepository?.path ?? null);
-    const isolation = await inspectAudienceIsolation(
-      root.rootPath,
-      root.config,
-      deps.registry ?? getActiveDistribution().registry,
-      report.audiences?.active ?? null,
-    );
-    if (isolation.leaked.length + isolation.unswept.length + isolation.undelivered.length > 0) {
-      report.audienceIsolation = isolation;
-    }
+    collectAudiences(report, root.config, env);
+  }
+
+  if (
+    root.rootPath &&
+    (kind === "working" || kind === "companion") &&
+    hasOpenspecCapability(root.config?.capabilities)
+  ) {
+    const warnings = await collectOpenSpecRuleWarnings(root.rootPath);
+    if (warnings.length > 0) report.openspecRuleWarnings = warnings;
+  }
+
+  if (root.rootPath && (kind === "working" || kind === "companion")) {
+    const warnings = collectCompanionInstructionWarnings(root.rootPath);
+    if (warnings.length > 0) report.companionInstructionWarnings = warnings;
+  }
+
+  if (root.rootPath && root.config && (kind === "working" || kind === "companion")) {
+    /** Doctor reports plugin failures below; hydration supplies their contributions. */
+    const hydrate =
+      deps.hydratePlugins ??
+      ((companionPath) => hydrateDynamicPlugins({ companionPath, env, warn: () => {} }));
+    await hydrate(root.rootPath);
+    const inspectClaudePlugins = deps.inspectClaudePlugins ?? inspectClaudePluginDirectories;
+    const inspection = await inspectClaudePlugins(root.rootPath, root.config);
+    if (inspection.plugins.length > 0) report.claudePlugins = inspection.plugins;
+    if (inspection.failures.length > 0) report.claudePluginFailures = inspection.failures;
   }
 
   if (root.rootPath && root.config) {
@@ -335,7 +473,12 @@ function renderToolInstallations(installations: DoctorToolInstallation[]): strin
   }
   return renderTable(
     ["Tool", "Source", "Status", "Path"],
-    installations.map((item) => [item.tool, item.source, item.status, item.path ?? ""]),
+    installations.map((item) => [
+      item.version ? `${item.tool} ${item.version}` : item.tool,
+      item.source,
+      item.status,
+      item.path ?? "",
+    ]),
   );
 }
 
@@ -353,47 +496,63 @@ function renderHubMembers(members: DoctorHubMember[]): string {
   );
 }
 
-function renderAudienceIsolation(isolation: AudienceIsolationReport): string {
-  const parts: string[] = [];
-  if (isolation.leaked.length > 0) {
-    parts.push(
-      "Contributions on persisted surfaces that no base plugin owns; the next sync removes them:",
+/** The Status column's text for each reason a folder is left out. */
+const CLAUDE_PLUGIN_PROBLEM_STATUS: Record<ClaudePluginDirectoryProblem, string> = {
+  "not-absolute": "not an absolute path",
+  "bundled-mate-plugin": "Mate's bundled plugin, already loaded",
+  "missing-manifest": `missing ${CLAUDE_PLUGIN_MANIFEST}`,
+  "mate-plugin-name": `uses Mate's plugin name ${MATE_CLAUDE_PLUGIN_NAME}`,
+};
+
+function claudePluginStatus(plugin: ClaudePluginDirectoryReport): string {
+  return plugin.problem ? CLAUDE_PLUGIN_PROBLEM_STATUS[plugin.problem] : "present";
+}
+
+/** The Plain Sessions column's text for each reason a loadable folder is not published. */
+const CLAUDE_PLUGIN_UNPUBLISHED_STATUS: Record<ClaudePluginUnpublishedReason, string> = {
+  "foreign-marketplace": `no: ${CLAUDE_PLUGIN_MARKETPLACE} is not Mate's and does not list it`,
+  "invalid-marketplace-name": "no: its name cannot form a marketplace name",
+  "name-conflict": "no: its marketplace name is already in use",
+  "missing-marketplace": `no: ${CLAUDE_PLUGIN_MARKETPLACE} could not be written`,
+};
+
+function claudePluginPlainSessions(plugin: ClaudePluginDirectoryReport): string {
+  if (plugin.marketplace) return `marketplace ${plugin.marketplace}`;
+  if (plugin.unpublishedReason) return CLAUDE_PLUGIN_UNPUBLISHED_STATUS[plugin.unpublishedReason];
+  return "no";
+}
+
+/** A table for each list present, then a note on where plain sessions load them. */
+function renderClaudePlugins(
+  plugins: ClaudePluginDirectoryReport[] | undefined,
+  failures: ClaudePluginContributionFailure[] | undefined,
+): string {
+  const tables: string[] = [];
+  if (plugins) {
+    tables.push(
       renderTable(
-        ["Surface", "Kind", "Entry", "Owner"],
-        isolation.leaked.map((entry) => [
-          entry.surface,
-          entry.kind,
-          entry.identity ?? "",
-          entry.owner,
+        ["Capability", "Plugin Folder", "Status", "Plain Sessions"],
+        plugins.map((plugin) => [
+          plugin.capability,
+          plugin.path,
+          claudePluginStatus(plugin),
+          claudePluginPlainSessions(plugin),
         ]),
       ),
     );
   }
-  if (isolation.unswept.length > 0) {
-    parts.push(
-      `Audience plugins not swept (could not be loaded); run \`MATE_AUDIENCE=<audience> ${FRAMEWORK_NAME} install --yes\` with their credentials:`,
-      renderList(isolation.unswept, ""),
-    );
-  }
-  if (isolation.undelivered.length > 0) {
-    parts.push(
-      "Active audience plugins contribute declaratively only; these parts are not delivered:",
-      renderList(
-        isolation.undelivered.map(
-          (entry) =>
-            `${entry.pluginId}: ${entry.parts
-              .map((part) =>
-                part === "pluginReferences"
-                  ? "OpenCode plugin references are not delivered"
-                  : `${part} is not run`,
-              )
-              .join("; ")}`,
-        ),
-        "",
+  if (failures) {
+    tables.push(
+      renderTable(
+        ["Capability", "Error"],
+        failures.map((failure) => [failure.capability, failure.reason]),
       ),
     );
   }
-  return parts.join("\n\n");
+  return [
+    ...tables.flatMap((table) => [table, ""]),
+    `\`${FRAMEWORK_NAME} claude\` loads every present plugin. Plain \`claude\` sessions load one with a marketplace, and only in a wrapped repository that Claude Code trusts.`,
+  ].join("\n");
 }
 
 function renderHumanReport(report: DoctorReport): void {
@@ -442,20 +601,9 @@ function renderHumanReport(report: DoctorReport): void {
       renderKeyValueTable([
         ["Declared", report.audiences.declared.join(", ") || "none"],
         ["Active", report.audiences.active ?? "none"],
-        ...(report.audiences.wrapped
-          ? [
-              ["Wrapped", `${report.audiences.wrapped} (bare sessions of this checkout)`] as [
-                string,
-                string,
-              ],
-            ]
-          : []),
       ]),
     );
   }
-  if (report.audienceIsolation) {
-    printSection("Audience Isolation", renderAudienceIsolation(report.audienceIsolation));
-  }
   if (report.hub) printSection("Hub Members", renderHubMembers(report.hub.members));
   // Companions with no drift produce no section at all: required plugins are
   // silent when healthy.
@@ -480,6 +628,30 @@ function renderHumanReport(report: DoctorReport): void {
   if (report.engineRequirement) {
     printSection("Version Requirement", report.engineRequirement.detail);
   }
+  if (report.claudePlugins || report.claudePluginFailures) {
+    printSection(
+      "Claude Plugins",
+      renderClaudePlugins(report.claudePlugins, report.claudePluginFailures),
+    );
+  }
+  if (report.openspecRuleWarnings) {
+    printSection(
+      "OpenSpec Config",
+      renderList(
+        report.openspecRuleWarnings.map((warning) => warning.message),
+        "",
+      ),
+    );
+  }
+  if (report.companionInstructionWarnings) {
+    printSection(
+      "Companion Instructions",
+      renderList(
+        report.companionInstructionWarnings.map((warning) => warning.message),
+        "",
+      ),
+    );
+  }
 
   printSection(
     "Resolution Failures",
@@ -500,7 +672,8 @@ function renderHumanReport(report: DoctorReport): void {
  * capabilities and tool checks for companions, member health for hubs.
  * Declared plugins of the effective set (base plus the `MATE_AUDIENCE`
  * audience) are verified strictly (installed, loadable); any failure is named
- * on stderr and exits non-zero, as is an undeclared `MATE_AUDIENCE`.
+ * on stderr and exits non-zero, as is an undeclared `MATE_AUDIENCE` or a
+ * Capability whose runtime contributions fail to load.
  * `--json` emits the same report as one JSON document.
  */
 export async function runDoctorCommand(argv: string[] = [], deps: DoctorDeps = {}): Promise<void> {
@@ -512,6 +685,12 @@ export async function runDoctorCommand(argv: string[] = [], deps: DoctorDeps = {
   for (const failure of failures) {
     process.stderr.write(`${FRAMEWORK_NAME}: plugin ${failure.package}: ${failure.reason}\n`);
   }
+  for (const failure of report.claudePluginFailures ?? []) {
+    process.stderr.write(
+      `${FRAMEWORK_NAME}: capability ${failure.capability}: ${failure.reason}\n`,
+    );
+    process.exitCode = 1;
+  }
   if (report.audienceError) {
     process.stderr.write(`${FRAMEWORK_NAME}: ${report.audienceError}\n`);
     process.exitCode = 1;

package/src/cli/commands/install.ts

@@ -1,8 +1,5 @@
-import path from "node:path";
-
 import { confirm } from "../confirm";
 import { FRAMEWORK_NAME } from "../../framework";
-import { ConfigStore } from "../../lib/orchestrator/config-store";
 import {
   buildInstallPlan,
   inspectInstallPlan,
@@ -179,11 +176,6 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
   }
 
   try {
-    if (!frozen && context.kind === "companion" && context.companionPath) {
-      await new ConfigStore(
-        path.join(context.companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
-      ).save(context.config);
-    }
     await reconcileInstalledCompanion(plan);
     await saveCompleteInstallState(plan, execution.results);
   } catch (error) {

package/src/cli/commands/plugin/install.ts

@@ -32,6 +32,8 @@ function withDeclaration(
   );
 }
 
+const INSTALL_USAGE = `usage: ${FRAMEWORK_NAME} plugin install <package>[@version]`;
+
 export interface PluginInstallCommandDeps {
   cwd?: string;
   installDeps?: PluginInstallDeps;
@@ -50,10 +52,13 @@ export async function runPluginInstallCommand(
   deps: PluginInstallCommandDeps = {},
 ): Promise<boolean> {
   const spec = argv[0];
-  if (!spec) {
-    process.stderr.write(
-      `${FRAMEWORK_NAME}: usage: ${FRAMEWORK_NAME} plugin install <package>[@version]\n`,
-    );
+  if (spec === "-h" || spec === "--help") {
+    process.stdout.write(`${INSTALL_USAGE}\n`);
+    return true;
+  }
+  if (!spec || spec.startsWith("-")) {
+    const problem = spec ? `unknown option ${spec}; ` : "";
+    process.stderr.write(`${FRAMEWORK_NAME}: ${problem}${INSTALL_USAGE}\n`);
     process.exitCode = 1;
     return false;
   }

package/src/cli/commands/plugin/plugin.ts

@@ -1,13 +1,14 @@
 import { usage } from "../../usage";
-import { runPluginInstallCommand } from "./install";
+import { type PluginInstallCommandDeps, runPluginInstallCommand } from "./install";
 
 export async function runPluginCommand(
   subcommand: string | undefined,
   argv: string[],
+  deps: PluginInstallCommandDeps = {},
 ): Promise<void> {
   switch (subcommand) {
     case "install":
-      await runPluginInstallCommand(argv);
+      if (!(await runPluginInstallCommand(argv, deps))) process.exitCode = 1;
       return;
     default:
       console.error(`Unknown plugin command: ${subcommand ?? ""}`);

package/src/cli/commands/report/adapter.ts

@@ -5,13 +5,21 @@ import type {
   ReportKeyValue,
   ReportMetric,
   ReportSection,
+  ReportStatusTone,
 } from "./types";
 import { REPORT_DOCUMENT_VERSION } from "./types";
 
+/** Collector status strings mapped to tones, so the built-in report never relies on inference. */
+const TOOL_STATUS_TONES: Record<string, ReportStatusTone> = {
+  ok: "ok",
+  "no data": "warn",
+  "no window data": "warn",
+  "not installed": "neutral",
+  "not enabled": "neutral",
+};
+
 export function reportDataToDocument(data: ReportData): ReportDocument {
   const metadata: ReportKeyValue[] = [
-    { label: "Window", value: `Last ${data.days} days` },
-    { label: "Generated", value: data.generatedAt },
     { label: "Working repository", value: data.workingRepoPath },
     { label: "Companion repository", value: data.companionRepoPath },
     { label: "Active agents", value: data.activeAgents.join(", ") || "None" },
@@ -57,6 +65,7 @@ export function reportDataToDocument(data: ReportData): ReportDocument {
       items: data.toolStatus.map((entry) => ({
         label: entry.name,
         status: entry.status,
+        tone: TOOL_STATUS_TONES[entry.status] ?? "neutral",
       })),
     },
   ];

package/src/cli/commands/report/contract.ts

@@ -1,5 +1,7 @@
 import {
   REPORT_DOCUMENT_VERSION,
+  REPORT_STATUS_TONES,
+  REPORT_TEXT_FORMATS,
   type ReportDiagramSection,
   type ReportDiffSection,
   type ReportDocument,
@@ -46,6 +48,21 @@ function requiredString(
   return true;
 }
 
+function optionalEnum(
+  value: unknown,
+  allowed: readonly string[],
+  path: string,
+  issues: ReportValidationIssue[],
+): void {
+  if (value === undefined || allowed.includes(value as string)) return;
+  const list = `${allowed.slice(0, -1).join(", ")}${allowed.length > 2 ? "," : ""} or ${allowed.at(-1)}`;
+  issues.push({ path, message: `must be one of ${list}` });
+}
+
+function optionalCaption(value: unknown, path: string, issues: ReportValidationIssue[]): void {
+  if (value !== undefined) requiredString(value, path, issues);
+}
+
 function validateKeyValues(value: unknown, path: string, issues: ReportValidationIssue[]): boolean {
   if (!Array.isArray(value)) {
     issues.push({ path, message: "must be an array" });
@@ -112,6 +129,7 @@ function validateStatuses(value: unknown, path: string, issues: ReportValidation
     if (item.detail !== undefined && typeof item.detail !== "string") {
       issues.push({ path: `${itemPath}.detail`, message: "must be a string" });
     }
+    optionalEnum(item.tone, REPORT_STATUS_TONES, `${itemPath}.tone`, issues);
   });
   return true;
 }
@@ -209,14 +227,17 @@ function validateSection(value: unknown, path: string, issues: ReportValidationI
       if (typeof value.content !== "string") {
         issues.push({ path: `${path}.content`, message: "must be a string" });
       }
+      optionalEnum(value.format, REPORT_TEXT_FORMATS, `${path}.format`, issues);
       return;
     case "diagram":
       validateDiagram(value, path, issues);
+      optionalCaption(value.caption, `${path}.caption`, issues);
       return;
     case "diff":
       if (typeof value.patch !== "string") {
         issues.push({ path: `${path}.patch`, message: "must be a string" });
       }
+      optionalCaption(value.caption, `${path}.caption`, issues);
       return;
     default:
       issues.push({

package/src/cli/commands/report/highlight.ts

@@ -1,5 +1,12 @@
-import { normalizeLanguage, renderNodesToHtml, renderTokens, tokenize } from "@tanstack/highlight";
-import { createThemeCss } from "@tanstack/highlight/theme";
+import {
+  type HighlightRenderNode,
+  normalizeLanguage,
+  renderNodesToHtml,
+  renderTokens,
+  tokenize,
+} from "@tanstack/highlight";
+import { createThemeCss, createThemeRule } from "@tanstack/highlight/theme";
+import githubDark from "@tanstack/highlight/themes/github-dark";
 import githubLight from "@tanstack/highlight/themes/github-light";
 
 /** Sole boundary against `@tanstack/highlight`, so an upstream API break stays a single-file fix. */
@@ -18,7 +25,30 @@ export function highlightInline(code: string, language: string | undefined): str
   return renderNodesToHtml(renderTokens(tokens));
 }
 
-/** Token colours as an inlinable stylesheet; carries no script, font, or external reference. */
+/**
+ * The same tokens as structure rather than markup, for a renderer that builds elements
+ * and so never holds a markup string. An unknown language yields plain text nodes.
+ */
+export function highlightNodes(
+  code: string,
+  language: string | undefined,
+): ReadonlyArray<HighlightRenderNode> {
+  const { tokens } = tokenize(code, { lang: resolveHighlightLanguage(language) });
+  return renderTokens(tokens);
+}
+
+/**
+ * Token colours as an inlinable stylesheet; carries no script, font, or external reference.
+ * Light by default, dark on screen when the reader prefers it or the page sets
+ * `data-scheme="dark"`, and light in print because both dark rules are screen-only.
+ */
 export function highlightStyleBlock(codeBlockSelector: string): string {
-  return createThemeCss({ light: githubLight, codeBlockSelector });
+  const light = createThemeCss({ light: githubLight, codeBlockSelector });
+  return `${light}
+@media screen and (prefers-color-scheme: dark) {
+${createThemeRule(':root:not([data-scheme="light"])', githubDark)}
+}
+@media screen {
+${createThemeRule(':root[data-scheme="dark"]', githubDark)}
+}`;
 }