@workflow-cannon/workspace-kit 0.18.0 → 0.24.0

package/src/modules/documentation/index.ts

@@ -27,21 +27,18 @@ function parseOptions(raw: Record<string, unknown>): DocumentationGenerateOption
 export const documentationModule: WorkflowModule = {
   registration: {
     id: "documentation",
-    version: "0.2.0",
+    version: "0.3.0",
     contractVersion: "1",
+    stateSchema: 1,
     capabilities: ["documentation"],
     dependsOn: [],
+    optionalPeers: [],
     enabledByDefault: true,
     config: {
       path: "src/modules/documentation/config.md",
       format: "md",
       description: "Documentation module configuration contract."
     },
-    state: {
-      path: "src/modules/documentation/state.md",
-      format: "md",
-      description: "Documentation module generation/runtime state contract."
-    },
     instructions: {
       directory: "src/modules/documentation/instructions",
       entries: [
@@ -66,50 +63,58 @@ export const documentationModule: WorkflowModule = {
         : {};
     const options = parseOptions(rawOptions);
 
-    if (command.name === "document-project") {
-      const batchResult = await generateAllDocuments({ options }, ctx);
-      return {
-        ok: batchResult.ok,
-        code: batchResult.ok ? "documented-project" : "documentation-batch-failed",
-        message: batchResult.ok
-          ? `Generated ${batchResult.summary.succeeded} documents (${batchResult.summary.skipped} skipped)`
-          : `Batch failed: ${batchResult.summary.failed} of ${batchResult.summary.total} documents failed`,
-        data: {
-          summary: batchResult.summary,
-          results: batchResult.results.map((r) => ({
-            documentType: r.evidence.documentType,
-            ok: r.ok,
-            aiOutputPath: r.aiOutputPath,
-            humanOutputPath: r.humanOutputPath,
-            filesWritten: r.evidence.filesWritten,
-            filesSkipped: r.evidence.filesSkipped,
-          }))
-        }
-      };
-    }
-
-    if (command.name === "generate-document") {
-      const result = await generateDocument(
-        {
-          documentType: typeof args.documentType === "string" ? args.documentType : undefined,
-          options
-        },
-        ctx
-      );
+    const handlers: Record<string, () => Promise<{
+      ok: boolean;
+      code: string;
+      message?: string;
+      data?: Record<string, unknown>;
+    }>> = {
+      "document-project": async () => {
+        const batchResult = await generateAllDocuments({ options }, ctx);
+        return {
+          ok: batchResult.ok,
+          code: batchResult.ok ? "documented-project" : "documentation-batch-failed",
+          message: batchResult.ok
+            ? `Generated ${batchResult.summary.succeeded} documents (${batchResult.summary.skipped} skipped)`
+            : `Batch failed: ${batchResult.summary.failed} of ${batchResult.summary.total} documents failed`,
+          data: {
+            summary: batchResult.summary,
+            results: batchResult.results.map((r) => ({
+              documentType: r.evidence.documentType,
+              ok: r.ok,
+              aiOutputPath: r.aiOutputPath,
+              humanOutputPath: r.humanOutputPath,
+              filesWritten: r.evidence.filesWritten,
+              filesSkipped: r.evidence.filesSkipped
+            }))
+          }
+        };
+      },
+      "generate-document": async () => {
+        const result = await generateDocument(
+          {
+            documentType: typeof args.documentType === "string" ? args.documentType : undefined,
+            options
+          },
+          ctx
+        );
 
-      return {
-        ok: result.ok,
-        code: result.ok ? "generated-document" : "generation-failed",
-        message: result.ok
-          ? `Generated document '${args.documentType ?? "unknown"}'`
-          : `Failed to generate document '${args.documentType ?? "unknown"}'`,
-        data: {
-          aiOutputPath: result.aiOutputPath,
-          humanOutputPath: result.humanOutputPath,
-          evidence: result.evidence
-        }
-      };
-    }
+        return {
+          ok: result.ok,
+          code: result.ok ? "generated-document" : "generation-failed",
+          message: result.ok
+            ? `Generated document '${args.documentType ?? "unknown"}'`
+            : `Failed to generate document '${args.documentType ?? "unknown"}'`,
+          data: {
+            aiOutputPath: result.aiOutputPath,
+            humanOutputPath: result.humanOutputPath,
+            evidence: result.evidence
+          }
+        };
+      }
+    };
+    const handler = handlers[command.name];
+    if (handler) return handler();
 
     return {
       ok: false,

package/src/modules/documentation/instructions/document-project.md

@@ -1,6 +1,6 @@
 # document-project
 
-Generate all project documentation by running `generate-document` for every template in the template library. Outputs AI-optimized docs to `.ai/` and human-readable docs to `docs/maintainers/`.
+Generate all project documentation by running `generate-document` for every view model in `src/modules/documentation/views`. Outputs AI-optimized docs to `.ai/` and human-readable docs to `docs/maintainers/`.
 
 ## Inputs
 
@@ -11,9 +11,9 @@ Generate all project documentation by running `generate-document` for every temp
   - `strict?: boolean` — fail on unresolved warnings (default `false` in batch mode)
   - `maxValidationAttempts?: number` — override retry limit per document
 
-## Shipped templates
+## Shipped targets
 
-All `.md` files under `sources.templatesRoot` (default `src/modules/documentation/templates`) are processed:
+View models in `src/modules/documentation/views` map to these output targets:
 
 - `AGENTS.md`
 - `ARCHITECTURE.md`
@@ -33,10 +33,10 @@ All `.md` files under `sources.templatesRoot` (default `src/modules/documentatio
 
 ## Required behavior
 
-1. Discover all `.md` templates in `sources.templatesRoot`.
-2. For each template, invoke `generate-document` with the template basename as `documentType`.
+1. Discover all `.view.yaml` view models (fallback: discover templates in fixture workspaces without `views/`).
+2. For each view model, invoke `generate-document` using the view model `target` as `documentType`.
 3. Default overwrite behavior: **preserve AI docs** (`overwriteAi: false`), **overwrite human docs** (`overwriteHuman: true`).
-4. Continue through all templates on individual failure; do not stop the batch.
+4. Continue through all targets on individual failure; do not stop the batch.
 5. Collect per-document results and emit a batch summary with total/succeeded/failed/skipped counts.
 6. Return `ok: true` only when zero documents failed.
 

package/src/modules/documentation/instructions/generate-document.md

@@ -1,10 +1,10 @@
 # generate-document
 
-Generate a single document for both canonical AI and human-readable surfaces using module config, schema, and templates.
+Generate a single document for both canonical AI and human-readable surfaces using module config, schema, view models, and deterministic renderers.
 
 ## Inputs
 
-- `documentType` (required): basename of the doc to generate; must match a file under `sources.templatesRoot` (default `src/modules/documentation/templates`). Known templates:
+- `documentType` (required): basename of the doc to generate; should match a `target` declared in `src/modules/documentation/views/*.view.yaml`. Known targets:
   - `AGENTS.md`
   - `ARCHITECTURE.md`
   - `PRINCIPLES.md`
@@ -34,11 +34,11 @@ Generate a single document for both canonical AI and human-readable surfaces usi
 1. Read `src/modules/documentation/RULES.md` and apply precedence order before generation.
 2. Load module config and resolve output roots from configured paths (`sources.aiRoot`, `sources.humanRoot`).
 3. Restrict writes strictly to configured output roots; reject writes outside those roots.
-4. Resolve template for `documentType` from `sources.templatesRoot`.
+4. Resolve template for `documentType` from `sources.templatesRoot` (for section/coverage checks) and resolve matching view model target from `views/`.
 5. If template is missing, warn user and ask whether to continue without a template; continue only on explicit confirmation.
 6. Generate AI output first at `<aiRoot>/<documentType>` using `documentation-maintainer.md` + `documentation-schema.md`.
 7. Validate AI output against schema; on validation failure, auto-resolve/retry up to `generation.maxValidationAttempts` before failing.
-8. Re-read generated AI output with project context, then generate human output at `<humanRoot>/<documentType>`.
+8. Parse AI output into keyed records, validate schema, normalize typed model, then render human output via named renderer functions from the matched view model.
 9. For templates containing `{{{ ... }}}`, execute block contents as generation instructions and ensure no unresolved blocks remain in output.
 10. Run section coverage validation (all required sections present, correct headings/order where required); retry/resolve on failure.
 11. Detect conflicts with higher-precedence docs and stop/prompt when policy-sensitive or unresolved.

package/src/modules/documentation/normalizer.ts

@@ -0,0 +1,187 @@
+import type { AiRecord } from "./parser.js";
+import type {
+  NormalizedBaseRecord,
+  NormalizedCadence,
+  NormalizedCheck,
+  NormalizedCommand,
+  NormalizedConfig,
+  NormalizedDecision,
+  NormalizedDocument,
+  NormalizedExample,
+  NormalizedGuardrail,
+  NormalizedMeta,
+  NormalizedRef,
+  NormalizedRollback,
+  NormalizedRule,
+  NormalizedState,
+  NormalizedTerm,
+  NormalizedWorkflow,
+  NormalizedRunbook,
+  NormalizedWorkbook,
+  NormalizedChain,
+  NormalizedArtifact,
+  NormalizedPromotion,
+  NormalizedTransition
+} from "./types.js";
+
+function asStatus(v?: string): NormalizedBaseRecord["status"] {
+  if (v === "active" || v === "deprecated" || v === "draft" || v === "observed" || v === "planned") return v;
+  return undefined;
+}
+
+function asList(v?: string): string[] {
+  if (!v) return [];
+  return v
+    .split(",")
+    .map((x) => x.trim())
+    .filter(Boolean);
+}
+
+export function normalizeDocument(records: AiRecord[]): NormalizedDocument {
+  const refs: NormalizedRef[] = [];
+  const rules: NormalizedRule[] = [];
+  const checks: NormalizedCheck[] = [];
+  const decisions: NormalizedDecision[] = [];
+  const examples: NormalizedExample[] = [];
+  const terms: NormalizedTerm[] = [];
+  const commands: NormalizedCommand[] = [];
+  const workflows: NormalizedWorkflow[] = [];
+  const runbooks: NormalizedRunbook[] = [];
+  const workbooks: NormalizedWorkbook[] = [];
+  const chains: NormalizedChain[] = [];
+  const states: NormalizedState[] = [];
+  const transitions: NormalizedTransition[] = [];
+  const promotions: NormalizedPromotion[] = [];
+  const rollbacks: NormalizedRollback[] = [];
+  const artifacts: NormalizedArtifact[] = [];
+  const configs: NormalizedConfig[] = [];
+  const cadences: NormalizedCadence[] = [];
+  const guardrails: NormalizedGuardrail[] = [];
+  const refsById = new Map<string, NormalizedRef>();
+  const examplesByParent = new Map<string, NormalizedExample[]>();
+  const profileRecords = new Map<"core" | "runbook" | "workbook", Array<NormalizedBaseRecord>>([
+    ["core", []],
+    ["runbook", []],
+    ["workbook", []]
+  ]);
+
+  let meta: NormalizedMeta | null = null;
+  for (const rec of records) {
+    const status = asStatus(rec.kv["status"] ?? rec.kv["st"]);
+    if (rec.type === "meta") {
+      meta = {
+        schema: "base.v2",
+        doc: rec.kv["doc"] ?? "rules",
+        truth: (rec.kv["truth"] as NormalizedMeta["truth"]) ?? "canonical",
+        profile: rec.kv["profile"] as NormalizedMeta["profile"],
+        status,
+        title: rec.kv["title"],
+        owner: rec.kv["owner"],
+        tags: asList(rec.kv["tags"]),
+        refs: asList(rec.kv["refs"])
+      };
+      continue;
+    }
+
+    if (rec.type === "ref") {
+      const ref: NormalizedRef = {
+        id: rec.kv["id"] ?? rec.kv["name"] ?? "",
+        type: (rec.kv["type"] as NormalizedRef["type"]) ?? "doc",
+        target: rec.kv["target"] ?? rec.kv["path"] ?? "",
+        anchor: rec.kv["anchor"],
+        label: rec.kv["label"] ?? rec.kv["name"],
+        note: rec.kv["note"],
+        status
+      };
+      refs.push(ref);
+      if (ref.id) refsById.set(ref.id, ref);
+      continue;
+    }
+
+    if (rec.type === "rule") {
+      rules.push({
+        id: rec.kv["id"] ?? rec.kv["slot1"] ?? "",
+        level: (rec.kv["level"] as NormalizedRule["level"]) ?? "should",
+        scope: rec.kv["scope"] ?? "",
+        scope_kind: rec.kv["scope_kind"],
+        kind: rec.kv["kind"],
+        directive: rec.kv["directive"] ?? rec.kv["slot3"] ?? "",
+        why: rec.kv["why"] ?? "",
+        unless: rec.kv["unless"],
+        also: asList(rec.kv["also"]),
+        risk: rec.kv["risk"] as NormalizedRule["risk"],
+        approval: rec.kv["approval"] as NormalizedRule["approval"],
+        override: rec.kv["override"] as NormalizedRule["override"],
+        status,
+        refs: asList(rec.kv["refs"])
+      });
+      continue;
+    }
+
+    if (rec.type === "example") {
+      const ex: NormalizedExample = {
+        id: rec.kv["id"] ?? "",
+        for: rec.kv["for"] ?? "",
+        kind: (rec.kv["kind"] as NormalizedExample["kind"]) ?? "edge",
+        text: rec.kv["text"] ?? "",
+        status,
+        refs: asList(rec.kv["refs"])
+      };
+      examples.push(ex);
+      const list = examplesByParent.get(ex.for) ?? [];
+      list.push(ex);
+      examplesByParent.set(ex.for, list);
+      continue;
+    }
+
+    if (rec.type === "check") checks.push({ id: rec.kv["id"] ?? "", scope: rec.kv["scope"] ?? "", assertion: rec.kv["assertion"] ?? rec.kv["assert"] ?? "", when: rec.kv["when"], onFail: rec.kv["onFail"] as NormalizedCheck["onFail"], status, refs: asList(rec.kv["refs"]) });
+    if (rec.type === "decision") decisions.push({ id: rec.kv["id"] ?? "", topic: rec.kv["topic"] ?? "", choice: rec.kv["choice"] ?? "", why: rec.kv["why"] ?? "", consequence: rec.kv["consequence"] ?? rec.kv["then"], status, refs: asList(rec.kv["refs"]) });
+    if (rec.type === "term") terms.push({ name: rec.kv["name"] ?? "", definition: rec.kv["definition"] ?? rec.kv["def"] ?? "", status, refs: asList(rec.kv["refs"]) });
+    if (rec.type === "command" || rec.type === "cmd") commands.push({ id: rec.kv["id"] ?? rec.kv["slot1"] ?? "", name: rec.kv["name"] ?? "", use: rec.kv["use"] ?? "", scope: rec.kv["scope"] ?? "", expectation: rec.kv["expectation"] ?? rec.kv["expect"] ?? "", risk: rec.kv["risk"] as NormalizedCommand["risk"], sensitivity: rec.kv["sensitivity"] as NormalizedCommand["sensitivity"], status, refs: asList(rec.kv["refs"]) });
+    if (rec.type === "workflow" || rec.type === "wf") workflows.push({ id: rec.kv["id"] ?? rec.kv["slot1"] ?? "", name: rec.kv["name"] ?? "", when: rec.kv["when"] ?? "", steps: asList(rec.kv["steps"] ?? rec.kv["do"]), done: asList(rec.kv["done"]), forbid: asList(rec.kv["forbid"]), askIf: rec.kv["askIf"] ?? rec.kv["ask_if"], haltIf: rec.kv["haltIf"] ?? rec.kv["halt_if"], approval: rec.kv["approval"] as NormalizedWorkflow["approval"], risk: rec.kv["risk"] as NormalizedWorkflow["risk"], status, refs: asList(rec.kv["refs"]) });
+    if (rec.type === "runbook") runbooks.push({ name: rec.kv["name"] ?? "", scope: rec.kv["scope"] ?? "", owner: rec.kv["owner"] ?? "", status, refs: asList(rec.kv["refs"]) });
+    if (rec.type === "workbook") workbooks.push({ name: rec.kv["name"] ?? "", phase: rec.kv["phase"] ?? "", state: rec.kv["state"] ?? "", status, refs: asList(rec.kv["refs"]) });
+    if (rec.type === "chain") chains.push({ step: rec.kv["step"] ?? "", command: rec.kv["command"] ?? "", expectExit: Number.parseInt(rec.kv["expectExit"] ?? rec.kv["expect_exit"] ?? "0", 10), status, refs: asList(rec.kv["refs"]) });
+    if (rec.type === "state") states.push({ name: rec.kv["name"] ?? "", distTag: rec.kv["distTag"] ?? rec.kv["dist_tag"] ?? "", intent: rec.kv["intent"] ?? "", status, refs: asList(rec.kv["refs"]) });
+    if (rec.type === "transition") transitions.push({ from: rec.kv["from"] ?? "", to: rec.kv["to"] ?? "", requires: asList(rec.kv["requires"]), status, refs: asList(rec.kv["refs"]) });
+    if (rec.type === "promotion") promotions.push({ from: rec.kv["from"] ?? "", to: rec.kv["to"] ?? "", requires: asList(rec.kv["requires"]), status, refs: asList(rec.kv["refs"]) });
+    if (rec.type === "rollback") rollbacks.push({ strategy: rec.kv["strategy"] ?? "", note: rec.kv["note"] ?? "", status, refs: asList(rec.kv["refs"]) });
+    if (rec.type === "artifact") artifacts.push({ path: rec.kv["path"] ?? "", schema: rec.kv["schema"] ?? "", status, refs: asList(rec.kv["refs"]) });
+    if (rec.type === "config") configs.push({ key: rec.kv["key"] ?? "", default: rec.kv["default"] ?? "", status, refs: asList(rec.kv["refs"]) });
+    if (rec.type === "cadence") cadences.push({ rule: rec.kv["rule"] ?? "", status, refs: asList(rec.kv["refs"]) });
+    if (rec.type === "guardrail") guardrails.push({ id: rec.kv["id"] ?? "", level: (rec.kv["level"] as NormalizedGuardrail["level"]) ?? "should", directive: rec.kv["directive"] ?? "", why: rec.kv["why"] ?? "", status, refs: asList(rec.kv["refs"]) });
+  }
+
+  const core: NormalizedBaseRecord[] = [...refs, ...rules, ...checks, ...decisions, ...examples, ...terms, ...commands, ...workflows];
+  const runbook: NormalizedBaseRecord[] = [...runbooks, ...chains, ...states, ...transitions, ...promotions, ...rollbacks, ...artifacts, ...configs, ...cadences, ...guardrails];
+  const workbook: NormalizedBaseRecord[] = [...workbooks, ...states, ...transitions, ...artifacts, ...guardrails];
+  profileRecords.set("core", core);
+  profileRecords.set("runbook", runbook);
+  profileRecords.set("workbook", workbook);
+
+  return {
+    meta,
+    refs,
+    rules,
+    checks,
+    decisions,
+    examples,
+    terms,
+    commands,
+    workflows,
+    runbooks,
+    workbooks,
+    chains,
+    states,
+    transitions,
+    promotions,
+    rollbacks,
+    artifacts,
+    configs,
+    cadences,
+    guardrails,
+    refsById,
+    examplesByParent,
+    profileRecords
+  };
+}

package/src/modules/documentation/parser.ts

@@ -0,0 +1,41 @@
+export type AiRecord = {
+  type: string;
+  kv: Record<string, string>;
+  raw: string;
+};
+
+export function parseAiRecordLine(line: string): AiRecord | null {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#")) return null;
+  const parts = trimmed.split("|");
+  if (parts.length < 2) return null;
+  const type = parts[0]?.trim() ?? "";
+  if (!type) return null;
+
+  const kv: Record<string, string> = {};
+  let slotIndex = 1;
+  for (const token of parts.slice(1)) {
+    const piece = token.trim();
+    if (!piece) continue;
+    const idx = piece.indexOf("=");
+    if (idx >= 0) {
+      const key = piece.slice(0, idx).trim();
+      const value = piece.slice(idx + 1).trim();
+      if (key) kv[key] = value;
+      continue;
+    }
+    // Transitional support: retain unkeyed tokens as synthetic slots.
+    kv[`slot${slotIndex}`] = piece;
+    slotIndex += 1;
+  }
+  return { type, kv, raw: line };
+}
+
+export function parseAiDocument(text: string): AiRecord[] {
+  const records: AiRecord[] = [];
+  for (const line of text.split("\n")) {
+    const rec = parseAiRecordLine(line);
+    if (rec) records.push(rec);
+  }
+  return records;
+}

package/src/modules/documentation/policy-sensitive-commands.ts

@@ -0,0 +1,8 @@
+/**
+ * Policy-gated `workspace-kit run` commands owned by the documentation module.
+ * Keep in sync with instruction names in `documentation/index.ts`.
+ */
+export const DOCUMENTATION_POLICY_COMMAND_NAMES = [
+  ["document-project", "doc.document-project"],
+  ["generate-document", "doc.generate-document"]
+] as const;

package/src/modules/documentation/renderer.ts

@@ -0,0 +1,121 @@
+import type {
+  NormalizedCheck,
+  NormalizedCommand,
+  NormalizedDecision,
+  NormalizedDocument,
+  NormalizedRule,
+  NormalizedTerm,
+  NormalizedWorkflow,
+  ViewModelDefinition,
+  ViewModelSection
+} from "./types.js";
+
+function stableSort(values: string[]): string[] {
+  return [...values].sort((a, b) => a.localeCompare(b));
+}
+
+export function brief_summary(input: string[]): string {
+  if (input.length === 0) return "No summary records.";
+  return input.map((line) => `- ${line}`).join("\n");
+}
+
+export function ordered_list(input: string[]): string {
+  if (input.length === 0) return "1. No entries";
+  return input.map((line, idx) => `${idx + 1}. ${line}`).join("\n");
+}
+
+export function rule_table(rules: NormalizedRule[]): string {
+  if (rules.length === 0) return "_No rules_";
+  const rows = [...rules].sort((a, b) => a.id.localeCompare(b.id));
+  const body = rows
+    .map((r) => `| ${r.id} | ${r.level} | ${r.scope || "-"} | ${r.directive || "-"} | ${r.why || "-"} |`)
+    .join("\n");
+  return `| ID | Level | Scope | Directive | Why |\n|---|---|---|---|---|\n${body}`;
+}
+
+export function check_table(checks: NormalizedCheck[]): string {
+  if (checks.length === 0) return "_No checks_";
+  const rows = [...checks].sort((a, b) => a.id.localeCompare(b.id));
+  const body = rows
+    .map((c) => `| ${c.id} | ${c.scope || "-"} | ${c.assertion || "-"} | ${c.onFail || "-"} |`)
+    .join("\n");
+  return `| ID | Scope | Assertion | On Fail |\n|---|---|---|---|\n${body}`;
+}
+
+export function command_reference(commands: NormalizedCommand[]): string {
+  if (commands.length === 0) return "_No commands_";
+  const rows = [...commands].sort((a, b) => a.name.localeCompare(b.name));
+  return rows.map((c) => `- \`${c.name}\`: ${c.expectation || c.use || "No expectation"}`).join("\n");
+}
+
+export function decision_section(decisions: NormalizedDecision[]): string {
+  if (decisions.length === 0) return "_No decisions_";
+  const rows = [...decisions].sort((a, b) => a.id.localeCompare(b.id));
+  return rows.map((d) => `### ${d.id}: ${d.topic}\n- Choice: ${d.choice}\n- Why: ${d.why}`).join("\n\n");
+}
+
+export function term_list(terms: NormalizedTerm[]): string {
+  if (terms.length === 0) return "_No terms_";
+  return [...terms]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((t) => `- **${t.name}**: ${t.definition}`)
+    .join("\n");
+}
+
+export function workflow_steps(workflows: NormalizedWorkflow[]): string {
+  if (workflows.length === 0) return "_No workflows_";
+  return workflows
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .map((wf) => `### ${wf.id}: ${wf.name}\n${ordered_list(stableSort(wf.steps))}`)
+    .join("\n\n");
+}
+
+export function chain_steps(chains: Array<{ step: string; command: string; expectExit: number }>): string {
+  if (chains.length === 0) return "_No chain steps_";
+  return chains
+    .map((c, idx) => `${idx + 1}. ${c.step} -> \`${c.command}\` (expect ${c.expectExit})`)
+    .join("\n");
+}
+
+export function ref_table(refs: Array<{ id: string; type: string; target: string }>): string {
+  if (refs.length === 0) return "_No refs_";
+  const body = [...refs]
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .map((r) => `| ${r.id} | ${r.type} | ${r.target} |`)
+    .join("\n");
+  return `| ID | Type | Target |\n|---|---|---|\n${body}`;
+}
+
+export const renderMetaSection = (doc: NormalizedDocument) =>
+  brief_summary([
+    `doc=${doc.meta?.doc ?? "unknown"}`,
+    `truth=${doc.meta?.truth ?? "unknown"}`,
+    `profile=${doc.meta?.profile ?? "core"}`
+  ]);
+export const renderRuleSection = (doc: NormalizedDocument) => rule_table(doc.rules);
+export const renderDecisionSection = (doc: NormalizedDocument) => decision_section(doc.decisions);
+
+function renderSection(doc: NormalizedDocument, section: ViewModelSection): string {
+  const byName: Record<string, (d: NormalizedDocument) => string> = {
+    renderMetaSection,
+    renderRuleSection,
+    renderDecisionSection,
+    brief_summary: (d) => brief_summary(d.examples.map((e) => e.text)),
+    ordered_list: (d) => ordered_list(d.commands.map((c) => c.name)),
+    rule_table: (d) => rule_table(d.rules),
+    check_table: (d) => check_table(d.checks),
+    command_reference: (d) => command_reference(d.commands),
+    decision_section: (d) => decision_section(d.decisions),
+    term_list: (d) => term_list(d.terms),
+    workflow_steps: (d) => workflow_steps(d.workflows),
+    chain_steps: (d) => chain_steps(d.chains),
+    ref_table: (d) => ref_table(d.refs)
+  };
+  const fn = byName[section.renderer] ?? (() => "_No renderer_");
+  const title = section.title ?? section.id;
+  return `## ${title}\n\n${fn(doc)}`;
+}
+
+export function renderDocument(doc: NormalizedDocument, view: ViewModelDefinition): string {
+  return view.sections.map((s) => renderSection(doc, s)).join("\n\n").trim() + "\n";
+}

package/src/modules/documentation/runtime-batch.ts

@@ -0,0 +1,74 @@
+import type { ModuleLifecycleContext } from "../../contracts/module-contract.js";
+import type { DocumentationBatchResult, DocumentationGenerateOptions, DocumentationGenerateResult } from "./types.js";
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { listViewModels, loadViewModel } from "./view-models.js";
+import { loadRuntimeConfig } from "./runtime-config.js";
+
+type GenerateAllDocumentsArgs = {
+  options?: DocumentationGenerateOptions;
+};
+
+export async function runGenerateAllDocuments(
+  args: GenerateAllDocumentsArgs,
+  ctx: ModuleLifecycleContext,
+  generateOne: (args: { documentType?: string; options?: DocumentationGenerateOptions }, ctx: ModuleLifecycleContext) => Promise<DocumentationGenerateResult>
+): Promise<DocumentationBatchResult> {
+  const config = await loadRuntimeConfig(ctx.workspacePath);
+  const workspaceViewsRoot = resolve(ctx.workspacePath, "src/modules/documentation/views");
+  const useWorkspaceViews = existsSync(workspaceViewsRoot);
+  const workItems: Array<{ documentType: string }> = [];
+  if (useWorkspaceViews) {
+    const viewFiles = await listViewModels(ctx.workspacePath);
+    for (const viewFile of viewFiles) {
+      const view = await loadViewModel(ctx.workspacePath, viewFile);
+      workItems.push({ documentType: view.target });
+    }
+  } else {
+    const templatesDir = resolve(config.sourceRoot, config.templatesRoot);
+    const listTemplateFiles = async (dir: string, baseDir: string): Promise<string[]> => {
+      const entries = await readdir(dir, { withFileTypes: true });
+      const files: string[] = [];
+      for (const entry of entries) {
+        const absPath = resolve(dir, entry.name);
+        if (entry.isDirectory()) files.push(...(await listTemplateFiles(absPath, baseDir)));
+        if (entry.isFile() && entry.name.endsWith(".md")) files.push(absPath.slice(baseDir.length + 1).split("\\").join("/"));
+      }
+      return files;
+    };
+    for (const templateFile of (await listTemplateFiles(templatesDir, templatesDir)).sort()) {
+      workItems.push({ documentType: templateFile });
+    }
+  }
+  const results: DocumentationGenerateResult[] = [];
+  let succeeded = 0;
+  let failed = 0;
+  let skipped = 0;
+  const batchOptions: DocumentationGenerateOptions = {
+    ...args.options,
+    overwriteAi: args.options?.overwriteAi ?? false,
+    overwriteHuman: args.options?.overwriteHuman ?? true,
+    strict: args.options?.strict ?? false
+  };
+
+  for (const item of workItems) {
+    const result = await generateOne({ documentType: item.documentType, options: batchOptions }, ctx);
+    results.push(result);
+    if (!result.ok) failed += 1;
+    else if (result.evidence.filesWritten.length > 0) succeeded += 1;
+    else skipped += 1;
+  }
+
+  return {
+    ok: failed === 0,
+    results,
+    summary: {
+      total: workItems.length,
+      succeeded,
+      failed,
+      skipped,
+      timestamp: new Date().toISOString()
+    }
+  };
+}