truthmark 1.5.0 → 1.6.1

package/dist/main.js

@@ -334,6 +334,22 @@ var truthmarkConfigSchema = {
         type: "string"
       }
     },
+    "truthmark-portal": {
+      type: "object",
+      additionalProperties: false,
+      required: [],
+      properties: {
+        enabled: {
+          type: "boolean"
+        },
+        output: {
+          type: "string"
+        },
+        template: {
+          type: "string"
+        }
+      }
+    },
     frontmatter: {
       type: "object",
       nullable: true,
@@ -391,6 +407,11 @@ var DEFAULT_AUTHORITY = [
   `${DEFAULT_DOCS_HIERARCHY.roots.truth}/**/*.md`
 ];
 var DEFAULT_INSTRUCTION_TARGETS = ["AGENTS.md"];
+var DEFAULT_TRUTHMARK_PORTAL = {
+  enabled: false,
+  output: "docs/truthmark-portal",
+  template: "default"
+};
 var createDefaultRawConfig = () => ({
   version: 1,
   platforms: [...DEFAULT_PLATFORMS],
@@ -422,6 +443,7 @@ var createDefaultConfig = () => ({
   },
   authority: [...DEFAULT_AUTHORITY],
   instructionTargets: [...DEFAULT_INSTRUCTION_TARGETS],
+  truthmarkPortal: { ...DEFAULT_TRUTHMARK_PORTAL },
   frontmatter: {
     required: [],
     recommended: ["status", "doc_type", "last_reviewed", "source_of_truth"]
@@ -578,9 +600,9 @@ var parseTruthDocumentsFromYaml = (sectionLines, areaName) => {
   const diagnostics = [];
   const truthDocumentEntries = [];
   for (const rawEntry of rawEntries) {
-    const path12 = rawEntry && typeof rawEntry === "object" && "path" in rawEntry ? rawEntry.path : null;
+    const path13 = rawEntry && typeof rawEntry === "object" && "path" in rawEntry ? rawEntry.path : null;
     const kind = rawEntry && typeof rawEntry === "object" && "kind" in rawEntry ? rawEntry.kind : null;
-    if (typeof path12 !== "string" || path12.trim().length === 0 || !isTruthDocumentKind(kind)) {
+    if (typeof path13 !== "string" || path13.trim().length === 0 || !isTruthDocumentKind(kind)) {
       diagnostics.push(
         createAreaDiagnostic(
           `Area ${areaName} truth_documents entries must include non-empty path and valid kind fields.`,
@@ -590,7 +612,7 @@ var parseTruthDocumentsFromYaml = (sectionLines, areaName) => {
       continue;
     }
     truthDocumentEntries.push({
-      path: path12.trim(),
+      path: path13.trim(),
       kind,
       kindSource: "explicit"
     });
@@ -862,6 +884,102 @@ var ARCHITECTURE_DOC_TEMPLATE_PATH = "docs/templates/architecture-doc.md";
 var WORKFLOW_DOC_TEMPLATE_PATH = "docs/templates/workflow-doc.md";
 var OPERATIONS_DOC_TEMPLATE_PATH = "docs/templates/operations-doc.md";
 var TEST_BEHAVIOR_DOC_TEMPLATE_PATH = "docs/templates/test-behavior-doc.md";
+var renderTemplateSection = (section) => {
+  return [
+    section.heading,
+    "",
+    "<!--",
+    ...section.guidance,
+    "-->",
+    "",
+    `{{${section.placeholder}}}`,
+    ""
+  ];
+};
+var titleToPlaceholder = (title) => {
+  return title.replace(/^#+\s+/u, "").toLowerCase().replaceAll(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+};
+var findTemplateSectionHeadings = (template) => {
+  const matches = [];
+  let fencedCodeMarker = null;
+  let fencedCodeLength = 0;
+  for (const lineMatch of template.matchAll(/^.*(?:\r?\n|$)/gm)) {
+    const rawLine = lineMatch[0];
+    if (rawLine.length === 0) {
+      continue;
+    }
+    const line = rawLine.replace(/\r?\n$/u, "");
+    const fenceMatch = /^(?: {0,3})(`{3,}|~{3,})/u.exec(line);
+    if (fenceMatch) {
+      const marker = fenceMatch[1]?.[0];
+      const length = fenceMatch[1]?.length ?? 0;
+      if (fencedCodeMarker === null) {
+        fencedCodeMarker = marker;
+        fencedCodeLength = length;
+      } else if (marker === fencedCodeMarker && length >= fencedCodeLength) {
+        fencedCodeMarker = null;
+        fencedCodeLength = 0;
+      }
+      continue;
+    }
+    if (fencedCodeMarker === null && /^## .+$/u.test(line)) {
+      matches.push({ heading: line.trim(), index: lineMatch.index });
+    }
+  }
+  return matches;
+};
+var parseTemplateSections = (template) => {
+  const matches = findTemplateSectionHeadings(template);
+  if (matches.length === 0) {
+    return { preamble: template.trimEnd(), sections: [] };
+  }
+  const sections = matches.map((match, index) => {
+    const start = match.index;
+    const next = matches[index + 1];
+    const end = next?.index ?? template.length;
+    return {
+      heading: match.heading,
+      block: template.slice(start, end).trimEnd()
+    };
+  });
+  return {
+    preamble: template.slice(0, matches[0]?.index ?? 0).trimEnd(),
+    sections
+  };
+};
+var mergeTruthDocTemplate = (existingTemplate, defaultTemplate) => {
+  if (existingTemplate.trim().length === 0) {
+    return defaultTemplate;
+  }
+  const defaultParsed = parseTemplateSections(defaultTemplate);
+  const existingParsed = parseTemplateSections(existingTemplate);
+  const defaultHeadings = new Set(defaultParsed.sections.map((section) => section.heading));
+  const customBeforeDefault = /* @__PURE__ */ new Map();
+  const trailingCustomSections = [];
+  existingParsed.sections.forEach((section, index) => {
+    if (defaultHeadings.has(section.heading)) {
+      return;
+    }
+    const nextDefaultSection = existingParsed.sections.slice(index + 1).find((candidate) => defaultHeadings.has(candidate.heading));
+    if (nextDefaultSection) {
+      const bucket = customBeforeDefault.get(nextDefaultSection.heading) ?? [];
+      bucket.push(section);
+      customBeforeDefault.set(nextDefaultSection.heading, bucket);
+      return;
+    }
+    trailingCustomSections.push(section);
+  });
+  const mergedSections = defaultParsed.sections.flatMap((section) => [
+    ...customBeforeDefault.get(section.heading) ?? [],
+    section
+  ]);
+  return [
+    existingParsed.preamble,
+    ...mergedSections.map((section) => section.block),
+    ...trailingCustomSections.map((section) => section.block),
+    ""
+  ].filter((block) => block.length > 0).join("\n\n");
+};
 var renderBehaviorDocTemplateFile = () => {
   return [
     "---",
@@ -877,81 +995,130 @@ var renderBehaviorDocTemplateFile = () => {
     "",
     "## Purpose",
     "",
-    "<!-- State why this feature exists, the user or system outcome it protects, and the problem it solves. Keep roadmap or implementation plans out of this section. -->",
+    "<!--",
+    "State the user/system outcome this behavior protects and why it exists.",
+    "Include the problem boundary and durable value; exclude roadmap, implementation plan, and historical narrative.",
+    "List the code, config, docs, or tests that support the claim in source_of_truth rather than prose-only assertion.",
+    "-->",
     "",
     "{{purpose}}",
     "",
     "## Scope",
     "",
-    "{{scope}}",
-    "",
     "<!--",
-    "This doc must own one coherent behavior surface.",
-    "Split into another leaf doc when content introduces:",
-    "- a distinct user or system outcome",
-    "- a separate lifecycle or state machine",
-    "- an unrelated rule family",
-    "- a different external contract",
-    "- code that should route through a different owner",
+    "Define the one coherent behavior surface this document owns.",
+    "Include in-scope actors, entrypoints, state/data owned by this doc, and explicit handoffs to neighboring truth docs.",
+    "Split into another leaf doc when content introduces a distinct outcome, state machine, rule family, external contract, or route owner.",
     "Keep README.md files as indexes only.",
     "-->",
     "",
+    "{{scope}}",
+    "",
     "This doc was created from the editable behavior-doc template at {{template_path}}.",
     "",
     "## Current Behavior",
     "",
-    "<!-- Describe implemented behavior in present tense. Do not include desired future behavior. -->",
+    "<!--",
+    "Describe only current implemented behavior in present tense.",
+    "Cover observable behavior, important defaults, and user/system-visible effects; exclude desired future behavior and speculative design.",
+    "Every non-obvious claim should be checkable from source_of_truth evidence.",
+    "-->",
     "",
     "{{current_behavior}}",
     "",
     "## Core Rules",
     "",
-    "<!-- Capture stable business rules, invariants, precedence rules, validation rules, and must-never constraints. Omit incidental implementation details. -->",
+    "<!--",
+    "Capture stable business rules, invariants, precedence rules, validation rules, and must-never constraints.",
+    "Separate rules from incidental implementation details; cite current implementation or tests for rule enforcement.",
+    "-->",
     "",
     "{{core_rules}}",
     "",
     "## Flows And States",
     "",
-    "<!-- Use for route switches, state transitions, lifecycle stages, retries, fallbacks, and important error paths. Write 'None beyond current behavior.' when no distinct flow or state model exists. -->",
+    "<!--",
+    "Document state transitions, lifecycle stages, retries, fallbacks, route switches, and important error paths.",
+    "State 'None beyond current behavior.' when this behavior has no distinct flow or state model.",
+    "-->",
     "",
     "{{flows_and_states}}",
     "",
     "## Contracts",
     "",
-    "<!-- Capture user-visible or integration contracts: CLI/API shape, inputs, outputs, diagnostics, files, events, permissions, or links to canonical contract docs. Avoid duplicating a separate canonical contract doc. -->",
+    "<!--",
+    "Capture user-visible or integration contracts: CLI/API shape, inputs, outputs, diagnostics, files, events, permissions, or links to canonical contract docs.",
+    "Avoid duplicating a separate canonical contract doc; link to it when contract ownership lives elsewhere.",
+    "-->",
     "",
     "{{contracts}}",
     "",
     "## Product Decisions",
     "",
-    "<!-- Keep active decisions only. Replace stale decisions instead of appending historical logs. -->",
+    "<!--",
+    "Keep active decisions only, dated inline when added or changed.",
+    "Explain decisions that shape behavior, boundaries, rejected alternatives, or migration constraints; replace stale decisions instead of appending historical logs.",
+    "-->",
     "",
     "{{decision}}",
     "",
     "## Rationale",
     "",
-    "<!-- Explain why the current behavior and active decisions are this way, including tradeoffs. -->",
+    "<!--",
+    "Explain why the current behavior and active decisions are this way, including tradeoffs and constraints.",
+    "Tie rationale to evidence-backed behavior; do not use this as a changelog.",
+    "-->",
     "",
     "{{rationale}}",
     "",
     "## Non-Goals",
     "",
-    "<!-- Name adjacent behavior this doc intentionally does not own, especially tempting future expansions. -->",
+    "<!--",
+    "Name adjacent behavior this doc intentionally does not own, especially tempting future expansions or neighboring route owners.",
+    "Use this section to prevent scope creep and duplicate truth ownership.",
+    "-->",
     "",
     "{{non_goals}}",
     "",
     "## Maintenance Notes",
     "",
-    "<!-- List related tests, routing cautions, migration notes, and common drift risks for future agents. Keep this operational, not historical. -->",
+    "<!--",
+    "List related tests, routing cautions, migration notes, evidence drift risks, and review triggers for future maintainers or agents.",
+    "Keep this operational and current-state focused, not historical.",
+    "-->",
     "",
     "{{maintenance_notes}}",
     ""
   ].join("\n");
 };
+var sectionSpec = (heading, guidance, placeholder = titleToPlaceholder(heading)) => ({ heading, guidance, placeholder });
+var PURPOSE_SECTION = sectionSpec("## Purpose", [
+  "State the software-engineering outcome this document protects and why the documented surface exists.",
+  "Include durable value, impacted users/systems, and the problem boundary; exclude roadmap, implementation plans, and historical narrative.",
+  "Keep claims traceable to source_of_truth evidence rather than prose-only assertion."
+]);
+var SCOPE_SECTION = sectionSpec("## Scope", [
+  "Define the one coherent surface this document owns, including actors, entrypoints, owned state/data, and handoffs to neighboring truth docs.",
+  "Call out important out-of-scope boundaries here or in Non-Goals; split the doc when it mixes distinct outcomes, lifecycles, contracts, or owners."
+]);
+var PRODUCT_DECISIONS_SECTION = sectionSpec("## Product Decisions", [
+  "Keep active decisions only, dated inline when added or changed.",
+  "Capture decisions that shape behavior, interfaces, boundaries, compatibility, risk acceptance, or migration constraints.",
+  "Replace stale decisions instead of appending historical logs."
+], "decision");
+var RATIONALE_SECTION = sectionSpec("## Rationale", [
+  "Explain why the current behavior, structure, or contract is this way, including tradeoffs and constraints.",
+  "Tie rationale to evidence-backed facts and active decisions; do not use this as a changelog."
+]);
+var NON_GOALS_SECTION = sectionSpec("## Non-Goals", [
+  "Name adjacent behavior, responsibilities, interfaces, or future expansions this doc intentionally does not own.",
+  "Use this section to prevent scope creep and duplicate truth ownership."
+]);
+var MAINTENANCE_NOTES_SECTION = sectionSpec("## Maintenance Notes", [
+  "List related tests, routing cautions, migration notes, compatibility risks, evidence drift risks, and review triggers for future maintainers or agents.",
+  "Keep this operational and current-state focused, not historical."
+]);
 var renderTypedTruthDocTemplate = (truthKind, docType, title, sections) => {
-  const placeholderNameForSection = (section) => {
-    return section.replace(/^#+\s+/u, "").toLowerCase().replaceAll(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
-  };
   return [
     "---",
     "status: active",
@@ -964,86 +1131,153 @@ var renderTypedTruthDocTemplate = (truthKind, docType, title, sections) => {
     "",
     `# ${title}`,
     "",
-    "## Purpose",
-    "",
-    "{{purpose}}",
-    "",
-    "## Scope",
-    "",
-    "{{scope}}",
-    "",
-    ...sections.flatMap((section) => [
-      section,
-      "",
-      `{{${placeholderNameForSection(section)}}}`,
-      ""
-    ]),
-    "## Product Decisions",
-    "",
-    "{{decision}}",
-    "",
-    "## Rationale",
-    "",
-    "{{rationale}}",
-    "",
-    "## Non-Goals",
-    "",
-    "{{non_goals}}",
-    "",
-    "## Maintenance Notes",
-    "",
-    "{{maintenance_notes}}",
-    ""
+    ...renderTemplateSection(PURPOSE_SECTION),
+    ...renderTemplateSection(SCOPE_SECTION),
+    ...sections.flatMap(renderTemplateSection),
+    ...renderTemplateSection(PRODUCT_DECISIONS_SECTION),
+    ...renderTemplateSection(RATIONALE_SECTION),
+    ...renderTemplateSection(NON_GOALS_SECTION),
+    ...renderTemplateSection(MAINTENANCE_NOTES_SECTION)
   ].join("\n");
 };
 var renderContractDocTemplateFile = () => {
   return renderTypedTruthDocTemplate("contract", "contract", "{{title}}", [
-    "## Contract Surface",
-    "## Inputs",
-    "## Outputs",
-    "## Errors And Diagnostics",
-    "## Compatibility Rules",
-    "## Versioning And Migration"
+    sectionSpec("## Contract Surface", [
+      "Identify the owned API, CLI, file format, event, protocol, permission boundary, or integration surface.",
+      "State consumers/producers, stability level, and the source files/tests that define the contract."
+    ]),
+    sectionSpec("## Inputs", [
+      "Document accepted parameters, payloads, files, environment/config keys, permissions, and validation rules.",
+      "Include required/optional status, defaults, constraints, and normalization behavior."
+    ]),
+    sectionSpec("## Outputs", [
+      "Document returned values, emitted files/events, state changes, side effects, and success diagnostics.",
+      "Make externally observable behavior explicit enough for compatibility review."
+    ]),
+    sectionSpec("## Errors And Diagnostics", [
+      "List error classes, exit/status codes, user-facing diagnostics, retries, and recoverability expectations.",
+      "Distinguish validation errors, dependency failures, authorization failures, and internal faults when applicable."
+    ]),
+    sectionSpec("## Compatibility Rules", [
+      "State backward/forward compatibility guarantees, tolerated inputs, deprecation rules, and breaking-change triggers.",
+      "Include compatibility tests or review gates that protect the contract."
+    ]),
+    sectionSpec("## Versioning And Migration", [
+      "Document version negotiation, schema/API version fields, rollout requirements, migration steps, and rollback expectations.",
+      "State 'Not versioned' only when the implementation truly has no versioning or migration surface."
+    ])
   ]);
 };
 var renderArchitectureDocTemplateFile = () => {
   return renderTypedTruthDocTemplate("architecture", "architecture", "{{title}}", [
-    "## System Role",
-    "## Boundaries",
-    "## Components",
-    "## Data And Control Flow",
-    "## Ownership",
-    "## Cross-Cutting Constraints"
+    sectionSpec("## System Role", [
+      "Describe the current architectural role of this subsystem/component in the larger system.",
+      "State the primary responsibilities, consumers, providers, and why this boundary exists now."
+    ]),
+    sectionSpec("## Boundaries", [
+      "Define owned code/config/data, external dependencies, trust boundaries, and interfaces crossed by this architecture.",
+      "Name what is deliberately outside the boundary and link neighboring architecture or contract docs when they own it."
+    ]),
+    sectionSpec("## Components", [
+      "List the major runtime/build-time components, modules, services, jobs, or generated artifacts and their responsibilities.",
+      "Keep the component list current and evidence-backed; avoid speculative target architecture."
+    ]),
+    sectionSpec("## Data And Control Flow", [
+      "Describe important data movement, command/control paths, synchronization points, state ownership, and failure paths.",
+      "Call out persistence, queues, caches, external calls, and security-sensitive transitions where relevant."
+    ]),
+    sectionSpec("## Ownership", [
+      "Document team/module ownership, review responsibility, operational responsibility, and escalation paths if known.",
+      "If ownership is inferred from codeowners, config, or repository structure, cite that evidence."
+    ]),
+    sectionSpec("## Cross-Cutting Constraints", [
+      "Record active constraints such as security, privacy, reliability, performance, portability, maintainability, compliance, and cost.",
+      "Tie constraints to source evidence, tests, standards, or operational requirements where available."
+    ])
   ]);
 };
 var renderWorkflowDocTemplateFile = () => {
   return renderTypedTruthDocTemplate("workflow", "behavior", "{{title}}", [
-    "## Triggers",
-    "## Inputs",
-    "## Execution Model",
-    "## Steps",
-    "## State, Retry, And Failure Behavior",
-    "## Outputs"
+    sectionSpec("## Triggers", [
+      "List events, commands, schedules, user actions, webhooks, or dependency signals that start this workflow.",
+      "Include preconditions, authorization requirements, debounce/coalescing behavior, and disabled states when applicable."
+    ]),
+    sectionSpec("## Inputs", [
+      "Document data, files, config, context, credentials, and environmental assumptions consumed by the workflow.",
+      "Include validation, defaults, and normalization that happen before execution."
+    ]),
+    sectionSpec("## Execution Model", [
+      "Describe synchronous/asynchronous execution, concurrency, locking, leases, batching, ordering, and idempotency behavior.",
+      "State whether the workflow is user-blocking, background, distributed, or delegated to another system."
+    ]),
+    sectionSpec("## Steps", [
+      "Capture the current ordered steps or phases at a level useful for maintenance and review.",
+      "Reference implementation entrypoints instead of duplicating line-by-line code behavior."
+    ]),
+    sectionSpec("## State, Retry, And Failure Behavior", [
+      "Document state transitions, retries, timeouts, compensation, fallback, partial-success, and terminal-failure behavior.",
+      "Make externally visible failure semantics and recovery responsibilities clear."
+    ]),
+    sectionSpec("## Outputs", [
+      "List artifacts, state changes, notifications, logs, metrics, diagnostics, and downstream triggers produced by the workflow.",
+      "Include success criteria and handoff points to other truth docs or systems."
+    ])
   ]);
 };
 var renderOperationsDocTemplateFile = () => {
   return renderTypedTruthDocTemplate("operations", "behavior", "{{title}}", [
-    "## Operational Surface",
-    "## Runtime Topology",
-    "## Configuration",
-    "## Permissions",
-    "## Deployment And Rollback",
-    "## Availability And Observability"
+    sectionSpec("## Operational Surface", [
+      "Describe what operators, maintainers, or automated systems can observe or control for this surface.",
+      "Include commands, dashboards, alerts, runbooks, jobs, or operational APIs that define current operations."
+    ]),
+    sectionSpec("## Runtime Topology", [
+      "Document services, processes, containers, hosts, regions, dependencies, queues, stores, and network boundaries involved at runtime.",
+      "State single-node/local behavior explicitly when there is no distributed topology."
+    ]),
+    sectionSpec("## Configuration", [
+      "List operational config, environment variables, feature flags, secrets references, defaults, and reload/restart requirements.",
+      "Do not include secret values; describe storage and rotation expectations instead."
+    ]),
+    sectionSpec("## Permissions", [
+      "Document required identities, roles, scopes, filesystem/network permissions, and least-privilege boundaries.",
+      "Include user-facing authorization behavior and operator access requirements when relevant."
+    ]),
+    sectionSpec("## Deployment And Rollback", [
+      "Describe deployment mechanism, migration ordering, compatibility windows, rollback path, and known irreversible operations.",
+      "Call out manual gates, smoke checks, and post-deploy verification responsibilities."
+    ]),
+    sectionSpec("## Availability And Observability", [
+      "Capture availability expectations, health checks, metrics, logs, traces, alerts, SLO/error-budget signals, and known blind spots.",
+      "Include what maintainers should inspect first during incidents or degraded behavior."
+    ])
   ]);
 };
 var renderTestBehaviorDocTemplateFile = () => {
   return renderTypedTruthDocTemplate("test-behavior", "behavior", "{{title}}", [
-    "## Test Surface",
-    "## Fixtures And Data Model",
-    "## Execution Model",
-    "## Assertions And Invariants",
-    "## Isolation Rules",
-    "## Reporting And Failure Semantics"
+    sectionSpec("## Test Surface", [
+      "Define the behavior, contract, architecture, or workflow surface these tests verify.",
+      "Link the canonical truth docs and code paths the tests are meant to protect."
+    ]),
+    sectionSpec("## Fixtures And Data Model", [
+      "Document fixtures, factories, seeds, mocks/fakes, test repositories, external-service substitutes, and data lifecycle rules.",
+      "Include cleanup, determinism, privacy, and cross-test contamination constraints."
+    ]),
+    sectionSpec("## Execution Model", [
+      "Describe how tests run: command, framework, parallelism, isolation, network/filesystem assumptions, and required services.",
+      "State whether tests are unit, integration, e2e, contract, smoke, regression, or generated checks."
+    ]),
+    sectionSpec("## Assertions And Invariants", [
+      "List the critical assertions, invariants, failure modes, and negative cases that make the tests meaningful.",
+      "Tie assertions to product/contract rules rather than incidental implementation details."
+    ]),
+    sectionSpec("## Isolation Rules", [
+      "Document transaction boundaries, temp directories, fake clocks, network blocking, shared resources, and teardown rules.",
+      "Call out known order dependencies or flake risks and how they are controlled."
+    ]),
+    sectionSpec("## Reporting And Failure Semantics", [
+      "Describe diagnostics, snapshots, logs, coverage signals, retry policy, and how maintainers should interpret failures.",
+      "Include escalation or quarantine criteria for flaky or environment-sensitive tests."
+    ])
   ]);
 };
 var renderTemplate = (template, values) => {
@@ -1160,6 +1394,7 @@ import fs7 from "fs/promises";
 
 // src/config/load.ts
 import fs4 from "fs/promises";
+import path4 from "path";
 import { Ajv } from "ajv";
 import { parse as parse2 } from "yaml";
 var ajv = new Ajv({ allErrors: true });
@@ -1172,6 +1407,69 @@ var toConfigDiagnostic = (message, file) => {
     file
   };
 };
+var normalizeRepoRelativePath = (value) => {
+  const slashNormalized = value.replace(/\\/gu, "/");
+  const pathNormalized = path4.posix.normalize(slashNormalized).replace(/\/+$/u, "");
+  return pathNormalized;
+};
+var isUnsafeRepoRelativePath = (value) => {
+  const slashNormalized = value.replace(/\\/gu, "/");
+  const normalized = normalizeRepoRelativePath(value);
+  const parts = slashNormalized.split("/");
+  return normalized.length === 0 || normalized === "." || normalized === ".." || path4.isAbsolute(value) || path4.posix.isAbsolute(slashNormalized) || path4.win32.isAbsolute(value) || /^[A-Za-z]:/u.test(value) || normalized.startsWith("../") || parts.includes("..");
+};
+var pathsOverlap = (left, right) => {
+  const normalizedLeft = normalizeRepoRelativePath(left);
+  const normalizedRight = normalizeRepoRelativePath(right);
+  return normalizedLeft === normalizedRight || normalizedLeft.startsWith(`${normalizedRight}/`) || normalizedRight.startsWith(`${normalizedLeft}/`);
+};
+var portalForbiddenOutputRoots = (rawConfig) => {
+  const rawDocs = rawConfig.docs;
+  const docsRoots = rawDocs?.roots ?? {};
+  const routing = rawDocs?.routing ?? DEFAULT_DOCS_HIERARCHY.routing;
+  return [
+    "src",
+    DEFAULT_DOCS_HIERARCHY.roots.ai,
+    DEFAULT_DOCS_HIERARCHY.roots.standards,
+    DEFAULT_DOCS_HIERARCHY.roots.architecture,
+    DEFAULT_DOCS_HIERARCHY.roots.truth,
+    ...Object.values(docsRoots),
+    routing.root_index,
+    routing.area_files_root,
+    ".truthmark/config.yml",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    ".github/copilot-instructions.md",
+    ...rawConfig.instruction_targets ?? DEFAULT_INSTRUCTION_TARGETS
+  ];
+};
+var validatePortalConfig = (rawConfig, configPath) => {
+  const portal = rawConfig["truthmark-portal"];
+  if (portal === void 0) {
+    return [];
+  }
+  const diagnostics = [];
+  const output = portal.output ?? DEFAULT_TRUTHMARK_PORTAL.output;
+  const template = portal.template ?? DEFAULT_TRUTHMARK_PORTAL.template;
+  if (isUnsafeRepoRelativePath(output) || portalForbiddenOutputRoots(rawConfig).some((forbidden) => pathsOverlap(output, forbidden))) {
+    diagnostics.push(
+      toConfigDiagnostic(
+        "truthmark-portal.output must be a non-empty repo-relative directory that does not overlap source, instruction, routing, or canonical docs roots.",
+        configPath
+      )
+    );
+  }
+  if (template !== "default" && isUnsafeRepoRelativePath(template)) {
+    diagnostics.push(
+      toConfigDiagnostic(
+        "truthmark-portal.template must be 'default' or a non-empty repo-relative template path without absolute or parent traversal segments.",
+        configPath
+      )
+    );
+  }
+  return diagnostics;
+};
 var normalizeConfig = (rawConfig) => {
   const rawDocs = rawConfig.docs ?? {
     layout: DEFAULT_DOCS_HIERARCHY.layout,
@@ -1194,6 +1492,11 @@ var normalizeConfig = (rawConfig) => {
     },
     authority: rawConfig.authority,
     instructionTargets: rawConfig.instruction_targets ?? [...DEFAULT_INSTRUCTION_TARGETS],
+    truthmarkPortal: {
+      enabled: rawConfig["truthmark-portal"]?.enabled ?? DEFAULT_TRUTHMARK_PORTAL.enabled,
+      output: rawConfig["truthmark-portal"]?.output ?? DEFAULT_TRUTHMARK_PORTAL.output,
+      template: rawConfig["truthmark-portal"]?.template ?? DEFAULT_TRUTHMARK_PORTAL.template
+    },
     frontmatter: {
       required: rawConfig.frontmatter?.required ?? [],
       recommended: rawConfig.frontmatter?.recommended ?? []
@@ -1247,6 +1550,18 @@ var loadConfig = async (rootDir) => {
       configPath
     };
   }
+  const portalDiagnostics = validatePortalConfig(
+    parsedConfig,
+    configPath
+  );
+  if (portalDiagnostics.length > 0) {
+    return {
+      status: "invalid",
+      config: null,
+      diagnostics: portalDiagnostics,
+      configPath
+    };
+  }
   return {
     status: "loaded",
     config: normalizeConfig(parsedConfig),
@@ -1291,6 +1606,15 @@ var readBehaviorDocTemplate = async (rootDir) => {
     throw error;
   }
 };
+var ensureOrUpdateTruthDocTemplate = async (rootDir, templatePath, defaultTemplate) => {
+  const seededResult = await ensureRepoFile(rootDir, templatePath, defaultTemplate);
+  if (seededResult.status !== "unchanged") {
+    return seededResult;
+  }
+  const existingTemplate = await fs5.readFile(resolveRepoPath(rootDir, templatePath), "utf8");
+  const mergedTemplate = mergeTruthDocTemplate(existingTemplate, defaultTemplate);
+  return writeRepoFile(rootDir, templatePath, mergedTemplate);
+};
 var scaffoldHierarchy = async (rootDir, config) => {
   const results = [];
   const truthDocsRoot = truthRoot2(config);
@@ -1321,26 +1645,42 @@ var scaffoldHierarchy = async (rootDir, config) => {
     )
   );
   results.push(
-    await ensureRepoFile(rootDir, BEHAVIOR_DOC_TEMPLATE_PATH, renderBehaviorDocTemplateFile())
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      BEHAVIOR_DOC_TEMPLATE_PATH,
+      renderBehaviorDocTemplateFile()
+    )
   );
   results.push(
-    await ensureRepoFile(rootDir, CONTRACT_DOC_TEMPLATE_PATH, renderContractDocTemplateFile())
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      CONTRACT_DOC_TEMPLATE_PATH,
+      renderContractDocTemplateFile()
+    )
   );
   results.push(
-    await ensureRepoFile(
+    await ensureOrUpdateTruthDocTemplate(
       rootDir,
       ARCHITECTURE_DOC_TEMPLATE_PATH,
       renderArchitectureDocTemplateFile()
     )
   );
   results.push(
-    await ensureRepoFile(rootDir, WORKFLOW_DOC_TEMPLATE_PATH, renderWorkflowDocTemplateFile())
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      WORKFLOW_DOC_TEMPLATE_PATH,
+      renderWorkflowDocTemplateFile()
+    )
   );
   results.push(
-    await ensureRepoFile(rootDir, OPERATIONS_DOC_TEMPLATE_PATH, renderOperationsDocTemplateFile())
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      OPERATIONS_DOC_TEMPLATE_PATH,
+      renderOperationsDocTemplateFile()
+    )
   );
   results.push(
-    await ensureRepoFile(
+    await ensureOrUpdateTruthDocTemplate(
       rootDir,
       TEST_BEHAVIOR_DOC_TEMPLATE_PATH,
       renderTestBehaviorDocTemplateFile()
@@ -1409,18 +1749,19 @@ var DECISION_TRUTH_INSTRUCTIONS = [
   "Update Product Decisions and Rationale when a decision changes behavior."
 ].join("\n");
 var EVIDENCE_AUTHORITY_INSTRUCTIONS = [
-  "Repository instruction docs such as docs/ai/repo-rules.md remain instruction authority.",
+  "Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.",
   "Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries."
 ].join("\n");
 var REPOSITORY_INTELLIGENCE_INSTRUCTIONS = [
   "Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and ContextPack may guide routing, context selection, and verification planning when available.",
   "They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.",
-  "If unavailable, inspect .truthmark/config.yml, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated."
+  "If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated."
 ].join("\n");
 var FEATURE_DOC_TEMPLATE_INSTRUCTIONS = [
   "When creating or updating a truth doc, inspect the routed truth kind and use the matching `docs/templates/<kind>-doc.md` template.",
   "Supported kinds: behavior, contract, architecture, workflow, operations, and test-behavior.",
-  "Align existing docs to that template while preserving accurate authored content.",
+  "Treat the HTML comments under each template section as normative authoring guidance for that section.",
+  "Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.",
   "If the template is missing, use Scope, Product Decisions, Rationale, and the kind-specific current-truth section.",
   "Teams may edit the template files under docs/templates/ to define their local truth-doc standards."
 ].join("\n");
@@ -1594,11 +1935,11 @@ var defaultAgentConfig = () => {
 var renderHierarchySummary = (config) => {
   const truthRoot3 = resolveTruthDocsRoot(config);
   return [
-    "Truthmark hierarchy:",
-    "- Config: .truthmark/config.yml",
-    `- Root route index: ${config.docs.routing.rootIndex}`,
-    `- Area route files: ${config.docs.routing.areaFilesRoot}/**/*.md`,
-    `- Truth docs: ${truthRoot3}/**/*.md`
+    "Truthmark hierarchy hints:",
+    "- Config, when present: .truthmark/config.yml",
+    `- Root route index, when present: ${config.docs.routing.rootIndex}`,
+    `- Area route files, when present: ${config.docs.routing.areaFilesRoot}/**/*.md`,
+    `- Truth docs, when present: ${truthRoot3}/**/*.md`
   ].join("\n");
 };
 
@@ -1614,9 +1955,10 @@ var TRUTHMARK_BLOCK_START = "<!-- truthmark:start -->";
 var TRUTHMARK_BLOCK_END = "<!-- truthmark:end -->";
 var renderCompactHierarchySummary = (config) => {
   const truthRoot3 = resolveTruthDocsRoot(config);
-  return `Hierarchy: config .truthmark/config.yml; routes ${config.docs.routing.rootIndex} and ${config.docs.routing.areaFilesRoot}/**/*.md; Truth docs: ${truthRoot3}/**/*.md.`;
+  return `Hierarchy hints: config .truthmark/config.yml when present; routes ${config.docs.routing.rootIndex} and ${config.docs.routing.areaFilesRoot}/**/*.md when present; Truth docs: ${truthRoot3}/**/*.md when present.`;
 };
 var renderAgentsBlock = (config = defaultAgentConfig()) => {
+  const portalLine = config.truthmarkPortal.enabled ? `Truthmark Portal is a separate manual-only presentation workflow. Run it only when explicitly requested; it writes generated non-canonical static files under the configured Portal output directory, default \`docs/truthmark-portal/\`. Markdown remains canonical.` : null;
   return [
     TRUTHMARK_BLOCK_START,
     "## Truthmark Workflow",
@@ -1630,6 +1972,7 @@ var renderAgentsBlock = (config = defaultAgentConfig()) => {
     "Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and truth routing files, and must not rewrite functional code.",
     "If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise block and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.",
     "Explicit workflows: Truth Structure, Truth Document, Truth Preview, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.",
+    ...portalLine === null ? [] : [portalLine],
     "Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.",
     TRUTHMARK_BLOCK_END
   ].join("\n");
@@ -1970,6 +2313,50 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "truth_claim_verifier",
       "truth_doc_reviewer"
     ]
+  },
+  "truthmark-portal": {
+    id: "truthmark-portal",
+    displayName: "Truthmark Portal",
+    description: "Use when the user explicitly asks to generate, refresh, or update the Truthmark Portal static HTML site. Not for code change sync, route repair, truth validation/checking, documenting behavior, realizing docs into code, or machine-readable agent context.",
+    shortDescription: "Generate a committed static HTML Truthmark Portal",
+    defaultPrompt: "Use $truthmark-portal only when explicitly asked to generate or refresh the committed static HTML Portal.",
+    allowImplicitInvocation: false,
+    positiveTriggers: [
+      "generate the Truthmark Portal",
+      "refresh the committed HTML docs site",
+      "create a browsable project map from Truthmark docs",
+      "update docs/truthmark-portal",
+      "make a human-readable static site from the truth docs"
+    ],
+    negativeTriggers: [
+      "code change sync",
+      "route ownership repair",
+      "truth validation or checking",
+      "document implemented behavior",
+      "realize docs into code",
+      "machine-readable agent context"
+    ],
+    forbiddenAdjacency: [
+      "must not run as a completion gate",
+      "must not replace Truth Sync, Truth Check, Truth Document, Truth Realize, or Truth Structure",
+      "must not write outside the configured Portal output directory unless the user changes scope"
+    ],
+    requiredGates: [
+      "manual-only invocation",
+      "Portal output containment",
+      "Markdown canonical statement",
+      "source provenance"
+    ],
+    allowedWrites: ["configured Portal output directory only"],
+    reportSections: [
+      "Output path",
+      "Page count",
+      "Diagrams/assets",
+      "Source docs reviewed",
+      "Skipped/ambiguous docs",
+      "Validation",
+      "Markdown canonical statement"
+    ]
   }
 };
 var TRUTHMARK_WORKFLOW_IDS = Object.keys(
@@ -2000,7 +2387,7 @@ Fixes suggested:
 ${renderAuditEvidenceCheckedSection([
     {
       finding: "The root route index is present and maps repository truth owners.",
-      evidence: [".truthmark/config.yml:1", `${rootRouteIndex}:1`],
+      evidence: [`${rootRouteIndex}:1`],
       suggestedFix: "none",
       confidence: "high"
     }
@@ -2052,11 +2439,11 @@ Invocations: ${TRUTH_CHECK_EXPLICIT_INVOCATIONS}
 
 Truth Check is agent-led:
 
-- inspect .truthmark/config.yml, ${config.docs.routing.rootIndex}, canonical docs, and relevant implementation directly
+- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly
 - ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
-- inspect the configured root route index at ${config.docs.routing.rootIndex} and relevant child route files under ${config.docs.routing.areaFilesRoot}/
+- inspect the configured root route index at ${config.docs.routing.rootIndex} and relevant child route files under ${config.docs.routing.areaFilesRoot}/ when they exist
 - check that current docs describe current code rather than historical plans
-- check that ${config.docs.routing.rootIndex} routes code surfaces to canonical truth docs
+- check that route files map code surfaces to canonical truth docs when route files exist
 - check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure
 - check that canonical behavior docs keep active Product Decisions and Rationale sections
 - optionally run truthmark check when local tooling is available
@@ -2161,7 +2548,7 @@ Invocations: ${TRUTH_DOCUMENT_EXPLICIT_INVOCATIONS}
 Truth Document is manual and implementation-first:
 
 - run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs
-- inspect .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, existing canonical docs, implementation code, and tests directly
+- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly
 - ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
 - document current implemented behavior; do not invent future behavior or planned endpoints
 - may write canonical truth docs and ${config.docs.routing.rootIndex} or relevant child route files only
@@ -2270,9 +2657,9 @@ Purpose:
 - keep the selector thin so agents can avoid loading or acting through heavier workflows prematurely
 
 Read:
-- .truthmark/config.yml
-- ${config.docs.routing.rootIndex}
-- relevant child route files under ${config.docs.routing.areaFilesRoot}/
+- .truthmark/config.yml, only when present
+- ${config.docs.routing.rootIndex}, only when present
+- relevant child route files under ${config.docs.routing.areaFilesRoot}/, only when present
 - relevant truth docs and implementation files needed to preview ownership
 - ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
 
@@ -2297,6 +2684,82 @@ Report completion in this shape:
 ${renderMarkdownExample3(renderTruthPreviewReportExample(config))}`;
 };
 
+// src/agents/truthmark-portal.ts
+var TRUTHMARK_PORTAL_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Gemini CLI /truthmark:portal.";
+var renderTruthmarkPortalSkillBody = (config = defaultAgentConfig()) => {
+  const workflow = getTruthmarkWorkflow("truthmark-portal");
+  const output = config.truthmarkPortal.output;
+  const template = config.truthmarkPortal.template;
+  return `---
+name: truthmark-portal
+description: ${workflow.description}
+argument-hint: Optional output path, template, or portal generation focus
+user-invocable: true
+truthmark-version: ${TRUTHMARK_VERSION}
+---
+
+# Truthmark Portal
+
+Truthmark Portal is a manual-only presentation workflow. It is never a completion gate, never Truth Sync, and runs only when the user explicitly asks to generate, refresh, or update the committed static HTML Portal.
+
+Invocations: ${TRUTHMARK_PORTAL_EXPLICIT_INVOCATIONS}
+
+Core rules:
+
+- Markdown remains canonical; generated HTML is presentation only.
+- Read Markdown directly from the checkout; the workflow does not require the truthmark CLI or package.
+- truthmark check/index may be used only as optional supporting evidence when available.
+- Default output is docs/truthmark-portal; configured output is ${output}.
+- Configured template is ${template}; use default built-in template instructions when the template is default.
+- The workflow may replace the entire output directory, but writes are limited to the configured Portal output directory only unless the user changes scope.
+- Portal writes are generated non-canonical static files for human browsing.
+- Generate a committed multi-page static HTML site with local CSS, JavaScript, assets, and search metadata under the output directory.
+- Use no remote dependencies by default: no remote scripts, analytics, fonts, CSS, or CDN assets.
+- Include source provenance and the Markdown canonical disclaimer on every page.
+- Store manifest and search data under output/assets only.
+- There is no .truthmark/index.json dependency; do not require or create it as infrastructure.
+- Pictures and screenshots require an explicit user or template request.
+
+Workflow:
+
+1. Confirm the user explicitly requested Portal generation or refresh.
+2. Inspect .truthmark/config.yml and configured route docs only when they exist; read repository instruction files when present, truth docs, architecture docs, standards docs, and the configured Portal template when it is a repo-relative file.
+3. Validate the selected output path is repo-relative, non-empty, inside the repository, and does not overlap canonical docs, source roots, routing files, or instruction targets.
+4. Plan the generated page inventory, diagrams/assets, source docs reviewed, and skipped or ambiguous docs.
+5. Replace or write only under ${output}; do not edit canonical Markdown, routing, source code, or instruction files unless the user explicitly changes scope.
+6. Generate the multi-page static site with local assets/search metadata and visible source provenance.
+7. Validate entry page, links where practical, provenance/disclaimers, local-only assets, and that metadata remains under ${output}/assets.
+${renderHierarchySummary(config)}
+
+Report completion in this shape:
+
+\`\`\`md
+Truthmark Portal: completed
+
+Output path:
+- ${output}
+
+Page count:
+- <count>
+
+Diagrams/assets:
+- <generated diagrams/assets or none>
+
+Source docs reviewed:
+- <source markdown paths>
+
+Skipped/ambiguous docs:
+- <paths and reason, or none>
+
+Validation:
+- <checks performed>
+
+Markdown canonical statement:
+- Markdown remains canonical; generated Portal HTML is non-canonical presentation only.
+\`\`\`
+`;
+};
+
 // src/agents/truth-structure.ts
 var renderMarkdownExample4 = (content) => {
   return ["```md", content, "```"].join("\n");
@@ -2361,9 +2824,9 @@ truthmark-version: ${TRUTHMARK_VERSION}
 Use this skill to design or repair Truthmark area structure.
 Invocations: ${TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS}
 Truth Structure is agent-native:
-- inspect repository layout, current docs, .truthmark/config.yml, ${config.docs.routing.rootIndex}, and relevant code directly
+- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly
 - ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
-- inspect the configured root route index at ${config.docs.routing.rootIndex} and relevant child route files under ${config.docs.routing.areaFilesRoot}/
+- inspect the configured root route index at ${config.docs.routing.rootIndex} and relevant child route files under ${config.docs.routing.areaFilesRoot}/ when they exist
 - define areas by product or behavior ownership, not by mechanical directory mirroring
 - create or repair ${config.docs.routing.rootIndex}
 - create starter truth docs when useful and when they belong in the canonical current-truth surface
@@ -2434,7 +2897,7 @@ ${ARCHITECTURE_DOC_BOUNDARY_INSTRUCTIONS}
 Portable fallback:
 - If this skill surface is unavailable, perform the same workflow directly from committed repository files.
 - Do not require the truthmark CLI.
-- Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, canonical docs, and representative implementation code.
+- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code.
 - Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline.
 ${renderHierarchySummary(config)}
 ${DECISION_TRUTH_INSTRUCTIONS}
@@ -2599,7 +3062,7 @@ Explicit invocation runs immediately. Later functional-code changes reopen the f
 Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes.
 Parent workflow:
 1. Inspect git status, staged changes, unstaged changes, and untracked files directly.
-2. Read .truthmark/config.yml, the configured root route index at ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, and relevant canonical docs.
+2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs.
 3. Identify functional-code changes and the nearest truth docs or routing repairs.
 4. ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
 5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
@@ -2706,6 +3169,8 @@ var TRUTHMARK_CHECK_SKILL_PATH = ".codex/skills/truthmark-check/SKILL.md";
 var TRUTHMARK_CHECK_SKILL_METADATA_PATH = ".codex/skills/truthmark-check/agents/openai.yaml";
 var TRUTHMARK_PREVIEW_SKILL_PATH = ".codex/skills/truthmark-preview/SKILL.md";
 var TRUTHMARK_PREVIEW_SKILL_METADATA_PATH = ".codex/skills/truthmark-preview/agents/openai.yaml";
+var TRUTHMARK_PORTAL_SKILL_PATH = ".codex/skills/truthmark-portal/SKILL.md";
+var TRUTHMARK_PORTAL_SKILL_METADATA_PATH = ".codex/skills/truthmark-portal/agents/openai.yaml";
 var TRUTHMARK_ROUTE_AUDITOR_AGENT_PATH = ".codex/agents/truth-route-auditor.toml";
 var TRUTHMARK_CLAIM_VERIFIER_AGENT_PATH = ".codex/agents/truth-claim-verifier.toml";
 var TRUTHMARK_DOC_REVIEWER_AGENT_PATH = ".codex/agents/truth-doc-reviewer.toml";
@@ -2724,6 +3189,7 @@ var TRUTHMARK_GEMINI_SYNC_COMMAND_PATH = ".gemini/commands/truthmark/sync.toml";
 var TRUTHMARK_GEMINI_REALIZE_COMMAND_PATH = ".gemini/commands/truthmark/realize.toml";
 var TRUTHMARK_GEMINI_CHECK_COMMAND_PATH = ".gemini/commands/truthmark/check.toml";
 var TRUTHMARK_GEMINI_PREVIEW_COMMAND_PATH = ".gemini/commands/truthmark/preview.toml";
+var TRUTHMARK_GEMINI_PORTAL_COMMAND_PATH = ".gemini/commands/truthmark/portal.toml";
 var TRUTHMARK_GEMINI_ROUTE_AUDITOR_AGENT_PATH = ".gemini/agents/truth-route-auditor.md";
 var TRUTHMARK_GEMINI_CLAIM_VERIFIER_AGENT_PATH = ".gemini/agents/truth-claim-verifier.md";
 var TRUTHMARK_GEMINI_DOC_REVIEWER_AGENT_PATH = ".gemini/agents/truth-doc-reviewer.md";
@@ -2734,6 +3200,7 @@ var TRUTHMARK_COPILOT_SYNC_PROMPT_PATH = ".github/prompts/truthmark-sync.prompt.
 var TRUTHMARK_COPILOT_REALIZE_PROMPT_PATH = ".github/prompts/truthmark-realize.prompt.md";
 var TRUTHMARK_COPILOT_CHECK_PROMPT_PATH = ".github/prompts/truthmark-check.prompt.md";
 var TRUTHMARK_COPILOT_PREVIEW_PROMPT_PATH = ".github/prompts/truthmark-preview.prompt.md";
+var TRUTHMARK_COPILOT_PORTAL_PROMPT_PATH = ".github/prompts/truthmark-portal.prompt.md";
 var TRUTHMARK_COPILOT_ROUTE_AUDITOR_AGENT_PATH = ".github/agents/truth-route-auditor.agent.md";
 var TRUTHMARK_COPILOT_CLAIM_VERIFIER_AGENT_PATH = ".github/agents/truth-claim-verifier.agent.md";
 var TRUTHMARK_COPILOT_DOC_REVIEWER_AGENT_PATH = ".github/agents/truth-doc-reviewer.agent.md";
@@ -2763,6 +3230,7 @@ var renderTomlStringArray = (values) => {
   return `[${values.map(renderTomlString).join(", ")}]`;
 };
 var TRUTH_REALIZE_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize.";
+var routeFilesHint = (config) => `${config.docs.routing.rootIndex}; ${config.docs.routing.areaFilesRoot}/`;
 var WORKFLOW_PACKAGE_DEFINITIONS = {
   "truthmark-structure": {
     title: "Truthmark Structure",
@@ -2770,8 +3238,8 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
     invocations: TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS,
     use: () => "Use this skill to design or repair Truthmark area structure.",
     quickRules: (config) => [
-      "Follow docs/ai/repo-rules.md as the repository instruction authority.",
-      `Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, current docs, and relevant code directly.`,
+      "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
+      `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect current docs and relevant code directly.`,
       "Define areas by product or behavior ownership, not by mechanical directory mirroring.",
       "Do not edit functional code.",
       "Read support/procedure.md before writing route or starter truth-doc changes.",
@@ -2785,8 +3253,8 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
     invocations: TRUTH_DOCUMENT_EXPLICIT_INVOCATIONS,
     use: () => "Use this skill to document existing implemented behavior when no functional-code changes are required for the task.",
     quickRules: (config) => [
-      "Follow docs/ai/repo-rules.md as the repository instruction authority.",
-      `Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, existing canonical docs, implementation code, and tests directly.`,
+      "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
+      `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect existing canonical docs, implementation code, and tests directly.`,
       "Document current implemented behavior; do not invent future behavior.",
       "May write canonical truth docs and truth routing files only; must not write functional code.",
       "Read support/procedure.md before editing truth docs.",
@@ -2801,9 +3269,9 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
     invocations: TRUTH_SYNC_EXPLICIT_INVOCATIONS,
     use: () => "Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync.",
     quickRules: (config) => [
-      "Follow docs/ai/repo-rules.md as the repository instruction authority.",
+      "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
       "Skip docs-only, formatting-only, behavior-preserving renames with no truth impact, missing config, and no-code changes.",
-      `Read .truthmark/config.yml, the configured root route index at ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, and relevant canonical docs.`,
+      `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect relevant canonical docs directly.`,
       "direct checkout inspection is the canonical path; do not require the truthmark binary.",
       "May write canonical truth docs and truth routing files only; must not rewrite functional code.",
       "Read support/procedure.md before editing truth docs.",
@@ -2818,8 +3286,8 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
     invocations: TRUTH_PREVIEW_EXPLICIT_INVOCATIONS,
     use: () => "Use this skill only when the user explicitly asks to preview Truthmark routing or workflow choice before edits.",
     quickRules: (config) => [
-      "Follow docs/ai/repo-rules.md as the repository instruction authority.",
-      `Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, and only the truth docs or implementation files needed to preview ownership.`,
+      "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
+      `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect only the truth docs or implementation files needed to preview ownership.`,
       "Truth Preview is read-only; this report is intended, not authorized.",
       "must not edit files and must not issue write leases; do not run Truth Sync automatically, replace Truth Check, claim final correctness, or mutate code.",
       "Use optional read-only route-auditor evidence only when it reduces context or clarifies ownership.",
@@ -2833,8 +3301,8 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
     invocations: TRUTH_REALIZE_EXPLICIT_INVOCATIONS,
     use: () => "Use this skill only when the user explicitly asks to realize truth docs into code.",
     quickRules: (config) => [
-      "Follow docs/ai/repo-rules.md as the repository instruction authority.",
-      `Read the source truth docs, .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files, tests, and relevant functional code directly.`,
+      "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
+      `Read the source truth docs, inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist, then inspect tests and relevant functional code directly.`,
       "Truth docs lead; code follows.",
       "may write functional code only; must not edit truth docs or truth routing while realizing those docs.",
       "Read support/procedure.md before changing code.",
@@ -2847,8 +3315,8 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
     invocations: TRUTH_CHECK_EXPLICIT_INVOCATIONS,
     use: () => "Use this skill to audit repository truth health.",
     quickRules: (config) => [
-      "Follow docs/ai/repo-rules.md as the repository instruction authority.",
-      `Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, canonical docs, and relevant implementation directly.`,
+      "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
+      `Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then inspect canonical docs and relevant implementation directly.`,
       "Report issues and suggested fixes; do not silently rewrite unrelated files.",
       "Direct checkout inspection is valid even when local tooling is unavailable.",
       "Read support/procedure.md before auditing details.",
@@ -2856,6 +3324,24 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
       "Read support/report-template.md before the final report."
     ],
     parentRule: "Parent agent owns the final Truth Check report"
+  },
+  "truthmark-portal": {
+    title: "Truthmark Portal",
+    argumentHint: "Optional output path, template, or portal generation focus",
+    invocations: TRUTHMARK_PORTAL_EXPLICIT_INVOCATIONS,
+    use: () => "Use this skill only when the user explicitly asks to generate or refresh the committed static HTML Truthmark Portal.",
+    quickRules: (config) => [
+      "Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.",
+      "Truthmark Portal is manual-only; never run it as a completion gate and never treat it as Truth Sync.",
+      "Markdown remains canonical; generated HTML is non-canonical presentation only.",
+      "Read Markdown directly; the workflow does not require the truthmark CLI or package.",
+      "Generate committed, generated non-canonical static files for humans.",
+      `Write only under configured Portal output ${config.truthmarkPortal.output}; default output is docs/truthmark-portal.`,
+      `Use configured Portal template ${config.truthmarkPortal.template}; no .truthmark/index.json dependency.`,
+      "Use no remote dependencies by default and include source provenance on every page.",
+      "Read support/procedure.md before generating Portal output.",
+      "Read support/report-template.md before the final report."
+    ]
   }
 };
 var stripWorkflowSkillFrontmatter = (body) => {
@@ -2948,6 +3434,8 @@ var renderStandaloneWorkflowSkillBody = (workflowId, config) => {
       return renderTruthmarkRealizeSkillBody(config);
     case "truthmark-check":
       return renderTruthCheckSkillBody(config);
+    case "truthmark-portal":
+      return renderTruthmarkPortalSkillBody(config);
   }
 };
 var renderWorkflowEntrypoint = (workflowId, config, supportFiles, host) => {
@@ -3086,8 +3574,8 @@ var renderTruthmarkSkillPackage = ({
   }
   return files;
 };
-var normalizeOpenCodePermissionPath = (path12) => {
-  const normalized = path12.replace(/\\/gu, "/").replace(/^\.\//u, "").replace(/\/+$/u, "");
+var normalizeOpenCodePermissionPath = (path13) => {
+  const normalized = path13.replace(/\\/gu, "/").replace(/^\.\//u, "").replace(/\/+$/u, "");
   return normalized === "" ? "." : normalized;
 };
 var appendOpenCodePermissionGlob = (root, glob) => {
@@ -3126,7 +3614,7 @@ var TRUTHMARK_SUBAGENT_PROFILES = {
     nicknameCandidates: ["Route Audit", "Route Trace", "Route Check"],
     instructions: `Stay read-only.
 Audit one bounded Truthmark route, area, or doc shard assigned by the parent.
-Read .truthmark/config.yml, the root route index, relevant child route files, mapped truth docs, and relevant implementation files directly.
+Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly.
 Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership.
 Do not edit files, stage changes, or propose broad rewrites.
 Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
@@ -3589,8 +4077,8 @@ Truth Realize is doc-first:
 
 Workflow:
 
-1. Read the updated truth docs named by the user, or infer the relevant docs from ${config.docs.routing.rootIndex}.
-2. Read .truthmark/config.yml, ${config.docs.routing.rootIndex}, relevant child route files, tests, and the relevant functional code.
+1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present.
+2. Inspect .truthmark/config.yml and configured route files (${routeFilesHint(config)}) only when they exist; then read tests and the relevant functional code.
 3. ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
 ${renderTruthDocOwnershipGateSection(
     "source truth docs before writing code",
@@ -3664,6 +4152,21 @@ var renderTruthmarkCheckSkillMetadata = () => {
 policy:
   allow_implicit_invocation: ${workflow.allowImplicitInvocation}
 
+truthmark:
+  version: "${TRUTHMARK_VERSION}"
+  refresh_command: "truthmark init"
+`;
+};
+var renderTruthmarkPortalSkillMetadata = () => {
+  const workflow = getTruthmarkWorkflow("truthmark-portal");
+  return `interface:
+  display_name: "${workflow.displayName}"
+  short_description: "${workflow.shortDescription}"
+  default_prompt: "${workflow.defaultPrompt}"
+
+policy:
+  allow_implicit_invocation: ${workflow.allowImplicitInvocation}
+
 truthmark:
   version: "${TRUTHMARK_VERSION}"
   refresh_command: "truthmark init"
@@ -3711,6 +4214,13 @@ var renderTruthmarkGeminiPreviewCommand = (config = defaultAgentConfig()) => {
     renderTruthPreviewSkillBody(config)
   );
 };
+var renderTruthmarkGeminiPortalCommand = (config = defaultAgentConfig()) => {
+  const workflow = getTruthmarkWorkflow("truthmark-portal");
+  return renderGeminiCommand(
+    workflow.description,
+    renderTruthmarkPortalSkillBody(config)
+  );
+};
 var renderTruthmarkCopilotStructurePrompt = (config = defaultAgentConfig()) => {
   const workflow = getTruthmarkWorkflow("truthmark-structure");
   return renderCopilotPromptFile(
@@ -3761,6 +4271,13 @@ var renderTruthmarkCopilotPreviewPrompt = (config = defaultAgentConfig()) => {
     renderTruthPreviewSkillBody(config)
   );
 };
+var renderTruthmarkCopilotPortalPrompt = (config = defaultAgentConfig()) => {
+  const workflow = getTruthmarkWorkflow("truthmark-portal");
+  return renderCopilotPromptFile(
+    workflow.description,
+    renderTruthmarkPortalSkillBody(config)
+  );
+};
 
 // src/templates/generated-surfaces.ts
 var codexFiles = (config) => {
@@ -3842,10 +4359,24 @@ var codexFiles = (config) => {
       content: renderTruthmarkDocWriterAgent()
     }
   ];
+  if (config.truthmarkPortal.enabled) {
+    files.push(
+      ...renderTruthmarkSkillPackage({
+        skillPath: TRUTHMARK_PORTAL_SKILL_PATH,
+        workflowId: "truthmark-portal",
+        host: "codex",
+        config
+      }),
+      {
+        path: TRUTHMARK_PORTAL_SKILL_METADATA_PATH,
+        content: renderTruthmarkPortalSkillMetadata()
+      }
+    );
+  }
   return files;
 };
 var opencodeFiles = (config) => {
-  return [
+  const files = [
     ...renderTruthmarkSkillPackage({
       skillPath: ".opencode/skills/truthmark-structure/SKILL.md",
       workflowId: "truthmark-structure",
@@ -3899,9 +4430,20 @@ var opencodeFiles = (config) => {
       content: renderTruthmarkOpenCodeDocWriterAgent(config)
     }
   ];
+  if (config.truthmarkPortal.enabled) {
+    files.push(
+      ...renderTruthmarkSkillPackage({
+        skillPath: ".opencode/skills/truthmark-portal/SKILL.md",
+        workflowId: "truthmark-portal",
+        host: "opencode",
+        config
+      })
+    );
+  }
+  return files;
 };
 var claudeFiles = (config, block) => {
-  return [
+  const files = [
     ...instructionBlockFiles(["CLAUDE.md"], block),
     ...renderTruthmarkSkillPackage({
       skillPath: ".claude/skills/truthmark-structure/SKILL.md",
@@ -3956,6 +4498,17 @@ var claudeFiles = (config, block) => {
       content: renderTruthmarkClaudeDocWriterAgent()
     }
   ];
+  if (config.truthmarkPortal.enabled) {
+    files.push(
+      ...renderTruthmarkSkillPackage({
+        skillPath: ".claude/skills/truthmark-portal/SKILL.md",
+        workflowId: "truthmark-portal",
+        host: "claude-code",
+        config
+      })
+    );
+  }
+  return files;
 };
 var copilotFiles = (config, block) => {
   const files = [
@@ -4037,10 +4590,24 @@ var copilotFiles = (config, block) => {
       content: renderTruthmarkCopilotDocWriterAgent()
     }
   ];
+  if (config.truthmarkPortal.enabled) {
+    files.push(
+      ...renderTruthmarkSkillPackage({
+        skillPath: ".github/skills/truthmark-portal/SKILL.md",
+        workflowId: "truthmark-portal",
+        host: "github-copilot",
+        config
+      }),
+      {
+        path: TRUTHMARK_COPILOT_PORTAL_PROMPT_PATH,
+        content: renderTruthmarkCopilotPortalPrompt(config)
+      }
+    );
+  }
   return files;
 };
 var geminiFiles = (config, block) => {
-  return [
+  const files = [
     ...instructionBlockFiles(["GEMINI.md"], block),
     ...renderTruthmarkSkillPackage({
       skillPath: ".gemini/skills/truthmark-structure/SKILL.md",
@@ -4119,10 +4686,25 @@ var geminiFiles = (config, block) => {
       content: renderTruthmarkGeminiDocWriterAgent()
     }
   ];
+  if (config.truthmarkPortal.enabled) {
+    files.push(
+      ...renderTruthmarkSkillPackage({
+        skillPath: ".gemini/skills/truthmark-portal/SKILL.md",
+        workflowId: "truthmark-portal",
+        host: "gemini-cli",
+        config
+      }),
+      {
+        path: TRUTHMARK_GEMINI_PORTAL_COMMAND_PATH,
+        content: renderTruthmarkGeminiPortalCommand(config)
+      }
+    );
+  }
+  return files;
 };
 var instructionBlockFiles = (paths, block) => {
-  return paths.map((path12) => ({
-    path: path12,
+  return paths.map((path13) => ({
+    path: path13,
     content: block,
     managedBlock: true
   }));
@@ -4197,16 +4779,39 @@ var removeTrailingManagedChunk = (preservedLines) => {
     preservedLines.splice(startIndex);
   }
 };
+var LEGACY_REPO_RULES_PATH = ["docs", "ai", `repo-${"rules.md"}`].join("/");
+var LEGACY_AGENT_ONBOARDING_PATH = ["docs", "ai", `agent-${"onboarding.md"}`].join(
+  "/"
+);
+var LEGACY_PRIMARY_REPO_INSTRUCTION_PHRASE = [
+  "primary repository",
+  "instruction source"
+].join(" ");
 var normalizeLegacyInstructionPreamble = (content) => {
   return content.replaceAll(
-    "Use that file as the primary repository instruction source for Codex.",
-    "Use that file as the primary repository instruction source for this agent."
+    `Follow \`${LEGACY_REPO_RULES_PATH}\`.`,
+    "Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist."
+  ).replaceAll(
+    `Follow \`${LEGACY_REPO_RULES_PATH}\` as the ${LEGACY_PRIMARY_REPO_INSTRUCTION_PHRASE}.`,
+    "Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist."
+  ).replaceAll(
+    `Use that file as the ${LEGACY_PRIMARY_REPO_INSTRUCTION_PHRASE} for Codex.`,
+    "Use explicitly configured repository policy docs only when they exist in this checkout."
+  ).replaceAll(
+    `Use that file as the ${LEGACY_PRIMARY_REPO_INSTRUCTION_PHRASE} for this agent.`,
+    "Use explicitly configured repository policy docs only when they exist in this checkout."
   ).replaceAll("Codex-specific:", "Agent-specific:").replaceAll(
     "- Read `docs/README.md` for the canonical docs map.",
-    "- Read `docs/README.md` only when choosing or updating canonical docs."
+    "- Read the configured Truthmark routing files when choosing or updating canonical docs."
+  ).replaceAll(
+    "- Read `docs/README.md` only when choosing or updating canonical docs.",
+    "- Read the configured Truthmark routing files when choosing or updating canonical docs."
   ).replaceAll(
-    "- Use `docs/ai/agent-onboarding.md` for quick task routing.",
-    "- Use `docs/ai/agent-onboarding.md` only when task routing is unclear or cross-area."
+    `- Use \`${LEGACY_AGENT_ONBOARDING_PATH}\` for quick task routing.`,
+    "- Use repository onboarding or docs-map files only when present and needed for unclear or cross-area routing."
+  ).replaceAll(
+    `- Use \`${LEGACY_AGENT_ONBOARDING_PATH}\` only when task routing is unclear or cross-area.`,
+    "- Use repository onboarding or docs-map files only when present and needed for unclear or cross-area routing."
   );
 };
 var upsertManagedBlock = (existingContent, block) => {
@@ -4267,48 +4872,36 @@ var upsertManagedBlock = (existingContent, block) => {
 
 ${block}`;
 };
-var writeManagedAgentsFile = async (rootDir, path12 = "AGENTS.md", block) => {
+var writeManagedAgentsFile = async (rootDir, path13 = "AGENTS.md", block) => {
   let existingContent = null;
   try {
-    existingContent = await fs7.readFile(resolveRepoPath(rootDir, path12), "utf8");
+    existingContent = await fs7.readFile(resolveRepoPath(rootDir, path13), "utf8");
   } catch (error) {
     if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
       throw error;
     }
   }
-  return writeRepoFile(rootDir, path12, upsertManagedBlock(existingContent, block));
+  return writeRepoFile(rootDir, path13, upsertManagedBlock(existingContent, block));
 };
 var diagnosticCategoryForPath = (filePath, config) => {
   if (filePath === "AGENTS.md") {
     return "truth-sync";
   }
-  if (filePath === "CLAUDE.md" || filePath === "GEMINI.md" || filePath === ".github/copilot-instructions.md" || filePath.startsWith(".github/prompts/truthmark-") || filePath.startsWith(".github/agents/truth-") || filePath.startsWith(".claude/agents/truth-") || filePath.startsWith(".claude/skills/truthmark-") || filePath.startsWith(".opencode/skills/truthmark-") || filePath.startsWith(".opencode/agents/") || filePath.startsWith(".codex/agents/")) {
-    return "truth-sync";
-  }
-  if (filePath.startsWith(".codex/skills/truthmark-structure/")) {
-    return "truth-sync";
-  }
-  if (filePath.startsWith(".codex/skills/truthmark-document/")) {
-    return "truth-sync";
+  if (filePath === ".github/prompts/truthmark-realize.prompt.md" || filePath.startsWith(".github/skills/truthmark-realize/") || filePath.startsWith(".claude/skills/truthmark-realize/") || filePath.startsWith(".opencode/skills/truthmark-realize/") || filePath.startsWith(".codex/skills/truthmark-realize/") || filePath.startsWith(".gemini/skills/truthmark-realize/")) {
+    return "realization";
   }
-  if (filePath.startsWith(".codex/skills/truthmark-sync/")) {
+  if (filePath === "CLAUDE.md" || filePath === "GEMINI.md" || filePath === ".github/copilot-instructions.md" || filePath.startsWith(".github/prompts/truthmark-") || filePath.startsWith(".github/agents/truth-") || filePath.startsWith(".github/skills/truthmark-") || filePath.startsWith(".claude/agents/truth-") || filePath.startsWith(".claude/skills/truthmark-") || filePath.startsWith(".opencode/skills/truthmark-") || filePath.startsWith(".opencode/agents/") || filePath.startsWith(".codex/agents/") || filePath.startsWith(".gemini/agents/truth-") || filePath.startsWith(".gemini/skills/truthmark-")) {
     return "truth-sync";
   }
-  if (filePath.startsWith(".codex/skills/truthmark-preview/")) {
+  if (filePath.startsWith(".codex/skills/truthmark-")) {
     return "truth-sync";
   }
-  if (filePath.startsWith(".codex/skills/truthmark-realize/")) {
-    return "realization";
-  }
   if (filePath.startsWith(".gemini/commands/truthmark/realize")) {
     return "realization";
   }
   if (filePath.startsWith(".gemini/commands/truthmark/")) {
     return "truth-sync";
   }
-  if (filePath.startsWith(".codex/skills/truthmark-check/")) {
-    return "truth-sync";
-  }
   if (filePath === config.docs.routing.rootIndex) {
     return "authority";
   }
@@ -4665,7 +5258,7 @@ var checkFrontmatter = async (rootDir, config, markdownPaths, truthDocumentEntri
 
 // src/checks/links.ts
 import fs11 from "fs/promises";
-import path4 from "path";
+import path5 from "path";
 var pathExists2 = async (absolutePath) => {
   try {
     await fs11.stat(absolutePath);
@@ -4699,7 +5292,7 @@ var checkLinks = async (rootDir, markdownPaths) => {
       if (targetPath.length === 0) {
         continue;
       }
-      const absoluteTarget = path4.resolve(path4.dirname(absolutePath), targetPath);
+      const absoluteTarget = path5.resolve(path5.dirname(absolutePath), targetPath);
       const relativeTarget = toRepoRelativePath(rootDir, absoluteTarget);
       try {
         await assertRepoContainment(rootDir, absoluteTarget);
@@ -5571,16 +6164,16 @@ var checkGeneratedSurfaces = async (rootDir, config) => {
 };
 
 // src/impact/build.ts
-import path9 from "path";
+import path10 from "path";
 import micromatch7 from "micromatch";
 
 // src/repo-index/build.ts
 import fs18 from "fs/promises";
-import path7 from "path";
+import path8 from "path";
 
 // src/repo-index/file-tree.ts
 import fs16 from "fs/promises";
-import path5 from "path";
+import path6 from "path";
 import { execa as execa2 } from "execa";
 import fg6 from "fast-glob";
 import matter2 from "gray-matter";
@@ -5600,10 +6193,10 @@ var languageByExtension = /* @__PURE__ */ new Map([
 ]);
 var sourceExtensions = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 var isJavaScriptLikePath = (filePath) => {
-  return sourceExtensions.has(path5.posix.extname(filePath));
+  return sourceExtensions.has(path6.posix.extname(filePath));
 };
 var isTestPath = (filePath) => {
-  return filePath.startsWith("tests/") || filePath.includes("/__tests__/") || /(?:^|[./-])(test|spec)\.[cm]?[jt]sx?$/u.test(path5.posix.basename(filePath));
+  return filePath.startsWith("tests/") || filePath.includes("/__tests__/") || /(?:^|[./-])(test|spec)\.[cm]?[jt]sx?$/u.test(path6.posix.basename(filePath));
 };
 var fileKind = (filePath, ignore) => {
   const classification = classifyPath(filePath, ignore);
@@ -5629,7 +6222,7 @@ var fileKind = (filePath, ignore) => {
 };
 var targetHintsForTest = (filePath) => {
   const hints = /* @__PURE__ */ new Set();
-  const basename = path5.posix.basename(filePath).replace(/\.(test|spec)\.[cm]?[jt]sx?$/u, "");
+  const basename = path6.posix.basename(filePath).replace(/\.(test|spec)\.[cm]?[jt]sx?$/u, "");
   if (basename.length > 0) {
     hints.add(basename);
   }
@@ -5677,7 +6270,7 @@ var discoverRepoFiles = async (rootDir, ignore) => {
   for (const filePath of discoveredFiles.filter((entry) => !isIgnoredPath(entry, ignore)).sort()) {
     let stat;
     try {
-      stat = await fs16.stat(path5.join(rootDir, filePath));
+      stat = await fs16.stat(path6.join(rootDir, filePath));
     } catch (error) {
       if (error instanceof Error && "code" in error && error.code === "ENOENT") {
         continue;
@@ -5687,7 +6280,7 @@ var discoverRepoFiles = async (rootDir, ignore) => {
     if (!stat.isFile()) {
       continue;
     }
-    const extension = path5.posix.extname(filePath);
+    const extension = path6.posix.extname(filePath);
     const kind = fileKind(filePath, ignore);
     files.push({
       path: filePath,
@@ -5701,7 +6294,7 @@ var discoverRepoFiles = async (rootDir, ignore) => {
       });
     }
     if (kind === "doc") {
-      const source = await fs16.readFile(path5.join(rootDir, filePath), "utf8");
+      const source = await fs16.readFile(path6.join(rootDir, filePath), "utf8");
       const parsed = matter2(source);
       const markdown = parseMarkdownDocument(parsed.content);
       const title = markdown.headings.find((heading) => heading.depth === 1)?.text ?? null;
@@ -5724,7 +6317,7 @@ var discoverRepoFiles = async (rootDir, ignore) => {
 
 // src/repo-index/package-metadata.ts
 import fs17 from "fs/promises";
-import path6 from "path";
+import path7 from "path";
 import fg7 from "fast-glob";
 var packageManagerFor = async (rootDir, packageDir) => {
   const lockfiles = [
@@ -5736,7 +6329,7 @@ var packageManagerFor = async (rootDir, packageDir) => {
   ];
   for (const [lockfile, manager] of lockfiles) {
     try {
-      await fs17.access(path6.join(rootDir, packageDir, lockfile));
+      await fs17.access(path7.join(rootDir, packageDir, lockfile));
       return manager;
     } catch {
       continue;
@@ -5753,8 +6346,8 @@ var discoverPackageMetadata = async (rootDir) => {
   });
   const packages = [];
   for (const packageFile of packageFiles.sort()) {
-    const packageDir = path6.posix.dirname(packageFile) === "." ? "" : path6.posix.dirname(packageFile);
-    const raw = JSON.parse(await fs17.readFile(path6.join(rootDir, packageFile), "utf8"));
+    const packageDir = path7.posix.dirname(packageFile) === "." ? "" : path7.posix.dirname(packageFile);
+    const raw = JSON.parse(await fs17.readFile(path7.join(rootDir, packageFile), "utf8"));
     const scripts = raw.scripts && typeof raw.scripts === "object" ? Object.keys(raw.scripts).sort() : [];
     packages.push({
       path: packageFile,
@@ -5813,16 +6406,16 @@ var declarationName = (node) => {
   }
   return node.name.text;
 };
-var addExport = (exports, publicSymbols, path12, name, kind) => {
+var addExport = (exports, publicSymbols, path13, name, kind) => {
   if (!name) {
     return;
   }
-  const entry = { path: path12, name, kind };
+  const entry = { path: path13, name, kind };
   exports.push(entry);
   publicSymbols.push(entry);
 };
-var analyzeTypeScriptSource = (path12, source) => {
-  const sourceFile = ts.createSourceFile(path12, source, ts.ScriptTarget.Latest, true);
+var analyzeTypeScriptSource = (path13, source) => {
+  const sourceFile = ts.createSourceFile(path13, source, ts.ScriptTarget.Latest, true);
   const imports = [];
   const exports = [];
   const publicSymbols = [];
@@ -5842,7 +6435,7 @@ var analyzeTypeScriptSource = (path12, source) => {
         }
       }
       imports.push({
-        from: path12,
+        from: path13,
         specifier: statement.moduleSpecifier.text,
         imported: sortStrings(imported)
       });
@@ -5851,34 +6444,34 @@ var analyzeTypeScriptSource = (path12, source) => {
     if (ts.isExportDeclaration(statement)) {
       if (statement.exportClause && ts.isNamedExports(statement.exportClause)) {
         for (const element of statement.exportClause.elements) {
-          addExport(exports, publicSymbols, path12, element.name.text, "re-export");
+          addExport(exports, publicSymbols, path13, element.name.text, "re-export");
         }
       }
       continue;
     }
     if (ts.isFunctionDeclaration(statement) && hasExportModifier(statement)) {
-      addExport(exports, publicSymbols, path12, declarationName(statement), "function");
+      addExport(exports, publicSymbols, path13, declarationName(statement), "function");
       continue;
     }
     if (ts.isClassDeclaration(statement) && hasExportModifier(statement)) {
-      addExport(exports, publicSymbols, path12, declarationName(statement), "class");
+      addExport(exports, publicSymbols, path13, declarationName(statement), "class");
       continue;
     }
     if (ts.isInterfaceDeclaration(statement) && hasExportModifier(statement)) {
-      addExport(exports, publicSymbols, path12, declarationName(statement), "interface");
+      addExport(exports, publicSymbols, path13, declarationName(statement), "interface");
       continue;
     }
     if (ts.isTypeAliasDeclaration(statement) && hasExportModifier(statement)) {
-      addExport(exports, publicSymbols, path12, declarationName(statement), "type");
+      addExport(exports, publicSymbols, path13, declarationName(statement), "type");
       continue;
     }
     if (ts.isEnumDeclaration(statement) && hasExportModifier(statement)) {
-      addExport(exports, publicSymbols, path12, declarationName(statement), "enum");
+      addExport(exports, publicSymbols, path13, declarationName(statement), "enum");
       continue;
     }
     if (ts.isVariableStatement(statement) && hasExportModifier(statement)) {
       for (const declaration of statement.declarationList.declarations) {
-        addExport(exports, publicSymbols, path12, declarationName(declaration), "const");
+        addExport(exports, publicSymbols, path13, declarationName(declaration), "const");
       }
     }
   }
@@ -5909,7 +6502,7 @@ var buildRepoIndex = async (cwd) => {
     if (!isJavaScriptLikePath(file.path)) {
       continue;
     }
-    const source = await fs18.readFile(path7.join(rootDir, file.path), "utf8");
+    const source = await fs18.readFile(path8.join(rootDir, file.path), "utf8");
     const analysis = analyzeTypeScriptSource(file.path, source);
     imports.push(...analysis.imports);
     exports.push(...analysis.exports);
@@ -5941,7 +6534,7 @@ import { execa as execa4 } from "execa";
 
 // src/git/changes.ts
 import fs19 from "fs/promises";
-import path8 from "path";
+import path9 from "path";
 import { execa as execa3 } from "execa";
 var normalizePath3 = (filePath) => {
   return filePath.replaceAll("\\", "/").replace(/^\.\//u, "");
@@ -5996,7 +6589,7 @@ var getUncommittedChanges = async (cwd) => {
   const deletedPathCandidates = /* @__PURE__ */ new Set([...stagedDeletedPaths, ...unstagedDeletedPaths]);
   for (const deletedPath of deletedPathCandidates) {
     const change = getOrCreateChange(changesByPath, deletedPath);
-    change.deleted = !await pathExists4(path8.join(rootDir, deletedPath));
+    change.deleted = !await pathExists4(path9.join(rootDir, deletedPath));
   }
   return Array.from(changesByPath.values()).sort((left, right) => {
     return left.path.localeCompare(right.path);
@@ -6117,7 +6710,7 @@ var resolveImportPath = (importEdge) => {
   if (!importEdge.specifier.startsWith(".")) {
     return null;
   }
-  const basePath = path9.posix.normalize(path9.posix.join(path9.posix.dirname(importEdge.from), importEdge.specifier));
+  const basePath = path10.posix.normalize(path10.posix.join(path10.posix.dirname(importEdge.from), importEdge.specifier));
   const withoutExtension = basePath.replace(/\.[cm]?[jt]sx?$/u, "");
   return withoutExtension;
 };
@@ -6130,7 +6723,7 @@ var importTargetsChangedFile = (importEdge, changedPath) => {
 };
 var pathSegments = (filePath) => filePath.split("/").filter(Boolean);
 var testHintMatchesChangedFile = (hints, changedPath) => {
-  const changedBaseName = path9.posix.basename(changedPath);
+  const changedBaseName = path10.posix.basename(changedPath);
   const changedSegments = pathSegments(changedPath);
   return hints.some((hint) => changedBaseName.startsWith(hint) || changedSegments.includes(hint));
 };
@@ -6291,7 +6884,7 @@ import fg8 from "fast-glob";
 
 // src/evidence/parse.ts
 import fs20 from "fs/promises";
-import path10 from "path";
+import path11 from "path";
 import matter3 from "gray-matter";
 import { parse as parse3 } from "yaml";
 var evidenceBlockPattern = /```ya?ml\s*\n([\s\S]*?)```/giu;
@@ -6300,9 +6893,9 @@ var normalizeReferencePath = (truthDocPath, referencePath) => {
   const strippedPath = referencePath.split("#")[0]?.trim() ?? "";
   const isRepoRelative = repoRootPrefixes.some((prefix) => strippedPath.startsWith(prefix));
   if (!isRepoRelative && (strippedPath.startsWith(".") || !strippedPath.includes("/"))) {
-    return path10.posix.normalize(path10.posix.join(path10.posix.dirname(truthDocPath), strippedPath));
+    return path11.posix.normalize(path11.posix.join(path11.posix.dirname(truthDocPath), strippedPath));
   }
-  return path10.posix.normalize(strippedPath);
+  return path11.posix.normalize(strippedPath);
 };
 var toEvidenceReference = (truthDocPath, raw) => {
   if (!raw || typeof raw !== "object" || !("path" in raw) || typeof raw.path !== "string") {
@@ -6319,7 +6912,7 @@ var toEvidenceReference = (truthDocPath, raw) => {
   };
 };
 var parseEvidenceReferences = async (rootDir, truthDocPath) => {
-  const source = await fs20.readFile(path10.join(rootDir, truthDocPath), "utf8");
+  const source = await fs20.readFile(path11.join(rootDir, truthDocPath), "utf8");
   const parsed = matter3(source);
   const references = [];
   const sourceOfTruth = Array.isArray(parsed.data.source_of_truth) ? parsed.data.source_of_truth : [];
@@ -6557,7 +7150,7 @@ var runCheck = async (cwd, options = {}) => {
 
 // src/context-pack/build.ts
 import fs22 from "fs/promises";
-import path11 from "path";
+import path12 from "path";
 import fg9 from "fast-glob";
 var uniqueSorted2 = (values) => [...new Set(values)].sort();
 var repoRootPrefixes2 = [".codex/", ".github/", ".truthmark/", "docs/", "src/", "tests/"];
@@ -6568,12 +7161,12 @@ var normalizeDocReferencePath = (docPath, referencePath) => {
     return null;
   }
   const isRepoRelative = repoRootPrefixes2.some((prefix) => strippedPath.startsWith(prefix));
-  const normalized = isRepoRelative ? path11.posix.normalize(strippedPath) : path11.posix.normalize(path11.posix.join(path11.posix.dirname(docPath), strippedPath));
+  const normalized = isRepoRelative ? path12.posix.normalize(strippedPath) : path12.posix.normalize(path12.posix.join(path12.posix.dirname(docPath), strippedPath));
   return normalized === ".." || normalized.startsWith("../") ? null : normalized;
 };
 var readIfExists = async (rootDir, filePath) => {
   try {
-    return await fs22.readFile(path11.join(rootDir, filePath), "utf8");
+    return await fs22.readFile(path12.join(rootDir, filePath), "utf8");
   } catch {
     return null;
   }
@@ -7153,14 +7746,21 @@ var runContext = async (options) => {
 };
 
 // src/cli/program.ts
+var markFailedWhenErrorDiagnosticsExist = (result) => {
+  if (result.diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+    process.exitCode = 1;
+  }
+};
 var writeResult = (result, options) => {
   const output = options.json ? renderJson(result) : renderHuman(result);
   process.stdout.write(`${output}
 `);
+  markFailedWhenErrorDiagnosticsExist(result);
 };
 var writeContextResult = (result, options) => {
   if (!options.json && options.format === "markdown" && typeof result.data?.markdown === "string") {
     process.stdout.write(result.data.markdown);
+    markFailedWhenErrorDiagnosticsExist(result);
     return;
   }
   writeResult(result, options);