truthmark 1.6.0 → 2.1.0

package/dist/main.js

@@ -266,11 +266,11 @@ var DEFAULT_PLATFORMS = [
 var truthmarkConfigSchema = {
   type: "object",
   additionalProperties: false,
-  required: ["version", "authority"],
+  required: ["version", "truthmark"],
   properties: {
     version: {
       type: "integer",
-      const: 1
+      const: 2
     },
     platforms: {
       type: "array",
@@ -281,52 +281,58 @@ var truthmarkConfigSchema = {
       },
       minItems: 1
     },
-    docs: {
+    truthmark: {
       type: "object",
-      nullable: true,
       additionalProperties: false,
-      required: ["layout", "roots", "routing"],
+      required: ["workspace", "routes", "truth", "templates", "generated"],
       properties: {
-        layout: {
-          type: "string",
-          const: "hierarchical"
+        workspace: {
+          type: "string"
         },
-        roots: {
+        routes: {
           type: "object",
-          required: [],
-          additionalProperties: {
-            type: "string"
+          additionalProperties: false,
+          required: ["index", "areas", "default_area", "max_delegation_depth"],
+          properties: {
+            index: { type: "string" },
+            areas: { type: "string" },
+            default_area: { type: "string" },
+            max_delegation_depth: { type: "integer", const: 1 }
+          }
+        },
+        truth: {
+          type: "object",
+          additionalProperties: false,
+          required: ["root"],
+          properties: {
+            root: { type: "string" }
+          }
+        },
+        templates: {
+          type: "object",
+          additionalProperties: false,
+          required: ["root"],
+          properties: {
+            root: { type: "string" }
           }
         },
-        routing: {
+        generated: {
           type: "object",
           additionalProperties: false,
-          required: ["root_index", "area_files_root", "default_area", "max_delegation_depth"],
+          required: ["portal"],
           properties: {
-            root_index: {
-              type: "string"
-            },
-            area_files_root: {
-              type: "string"
-            },
-            default_area: {
-              type: "string"
-            },
-            max_delegation_depth: {
-              type: "integer",
-              const: 1
+            portal: {
+              type: "object",
+              additionalProperties: false,
+              required: ["enabled"],
+              properties: {
+                enabled: { type: "boolean" }
+              }
             }
           }
         }
       }
     },
-    authority: {
-      type: "array",
-      items: {
-        type: "string"
-      },
-      minItems: 1
-    },
     instruction_targets: {
       type: "array",
       nullable: true,
@@ -334,22 +340,6 @@ 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,
@@ -383,44 +373,39 @@ var truthmarkConfigSchema = {
 };
 
 // src/config/defaults.ts
-var DEFAULT_DOCS_HIERARCHY = {
-  layout: "hierarchical",
-  roots: {
-    ai: "docs/ai",
-    standards: "docs/standards",
-    architecture: "docs/architecture",
-    truth: "docs/truth"
-  },
-  routing: {
-    root_index: "docs/truthmark/areas.md",
-    area_files_root: "docs/truthmark/areas",
+var DEFAULT_TRUTHMARK_WORKSPACE = {
+  workspace: "docs/truthmark",
+  routes: {
+    index: "routes/areas.md",
+    areas: "routes/areas",
     default_area: "repository",
     max_delegation_depth: 1
+  },
+  truth: {
+    root: "truth"
+  },
+  templates: {
+    root: "templates"
+  },
+  generated: {
+    portal: {
+      enabled: false
+    }
   }
 };
-var DEFAULT_AUTHORITY = [
-  DEFAULT_DOCS_HIERARCHY.routing.root_index,
-  `${DEFAULT_DOCS_HIERARCHY.routing.area_files_root}/**/*.md`,
-  `${DEFAULT_DOCS_HIERARCHY.roots.ai}/**/*.md`,
-  `${DEFAULT_DOCS_HIERARCHY.roots.standards}/**/*.md`,
-  `${DEFAULT_DOCS_HIERARCHY.roots.architecture}/**/*.md`,
-  `${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,
+  version: 2,
   platforms: [...DEFAULT_PLATFORMS],
-  docs: {
-    layout: DEFAULT_DOCS_HIERARCHY.layout,
-    roots: { ...DEFAULT_DOCS_HIERARCHY.roots },
-    routing: { ...DEFAULT_DOCS_HIERARCHY.routing }
+  truthmark: {
+    workspace: DEFAULT_TRUTHMARK_WORKSPACE.workspace,
+    routes: { ...DEFAULT_TRUTHMARK_WORKSPACE.routes },
+    truth: { ...DEFAULT_TRUTHMARK_WORKSPACE.truth },
+    templates: { ...DEFAULT_TRUTHMARK_WORKSPACE.templates },
+    generated: {
+      portal: { ...DEFAULT_TRUTHMARK_WORKSPACE.generated.portal }
+    }
   },
-  authority: [...DEFAULT_AUTHORITY],
   instruction_targets: [...DEFAULT_INSTRUCTION_TARGETS],
   frontmatter: {
     required: [],
@@ -429,21 +414,37 @@ var createDefaultRawConfig = () => ({
   ignore: ["node_modules/**", "vendor/**", "dist/**", "build/**"]
 });
 var createDefaultConfig = () => ({
-  version: 1,
+  version: 2,
   platforms: [...DEFAULT_PLATFORMS],
-  docs: {
-    layout: DEFAULT_DOCS_HIERARCHY.layout,
-    roots: { ...DEFAULT_DOCS_HIERARCHY.roots },
-    routing: {
-      rootIndex: DEFAULT_DOCS_HIERARCHY.routing.root_index,
-      areaFilesRoot: DEFAULT_DOCS_HIERARCHY.routing.area_files_root,
-      defaultArea: DEFAULT_DOCS_HIERARCHY.routing.default_area,
-      maxDelegationDepth: DEFAULT_DOCS_HIERARCHY.routing.max_delegation_depth
-    }
+  truthmark: {
+    workspace: DEFAULT_TRUTHMARK_WORKSPACE.workspace,
+    routes: {
+      index: DEFAULT_TRUTHMARK_WORKSPACE.routes.index,
+      areas: DEFAULT_TRUTHMARK_WORKSPACE.routes.areas,
+      defaultArea: DEFAULT_TRUTHMARK_WORKSPACE.routes.default_area,
+      maxDelegationDepth: DEFAULT_TRUTHMARK_WORKSPACE.routes.max_delegation_depth
+    },
+    truth: { root: DEFAULT_TRUTHMARK_WORKSPACE.truth.root },
+    templates: { root: DEFAULT_TRUTHMARK_WORKSPACE.templates.root },
+    generated: {
+      portal: { ...DEFAULT_TRUTHMARK_WORKSPACE.generated.portal }
+    },
+    paths: {
+      routesIndex: "docs/truthmark/routes/areas.md",
+      routeAreasRoot: "docs/truthmark/routes/areas",
+      truthRoot: "docs/truthmark/truth",
+      templatesRoot: "docs/truthmark/templates",
+      portalOutput: "docs/truthmark/generated/portal",
+      portalTemplate: "docs/truthmark/templates/portal.html"
+    },
+    controlledPaths: [
+      "docs/truthmark/routes/areas.md",
+      "docs/truthmark/routes/areas/**/*.md",
+      "docs/truthmark/truth/**/*.md",
+      "docs/truthmark/templates/*.md"
+    ]
   },
-  authority: [...DEFAULT_AUTHORITY],
   instructionTargets: [...DEFAULT_INSTRUCTION_TARGETS],
-  truthmarkPortal: { ...DEFAULT_TRUTHMARK_PORTAL },
   frontmatter: {
     required: [],
     recommended: ["status", "doc_type", "last_reviewed", "source_of_truth"]
@@ -461,6 +462,7 @@ var TRUTH_DOCUMENT_KINDS = [
   "operations",
   "test-behavior"
 ];
+var DEFAULT_WORKSPACE_TRUTH_DOCS_ROOT = "docs/truthmark/truth";
 var slugify = (value) => {
   return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 };
@@ -480,25 +482,10 @@ var isTruthDocumentKind = (value) => {
 };
 var inferTruthDocumentKindFromPath = (documentPath, options = {}) => {
   const normalizedPath = documentPath.replaceAll("\\", "/");
-  const truthDocsRoot = options.truthDocsRoot?.replaceAll("\\", "/").replace(/\/+$/u, "");
-  if (truthDocsRoot && normalizedPath.startsWith(`${truthDocsRoot}/`) || normalizedPath.startsWith("docs/truth/")) {
+  const truthDocsRoot = (options.truthDocsRoot ?? DEFAULT_WORKSPACE_TRUTH_DOCS_ROOT)?.replaceAll("\\", "/").replace(/\/+$/u, "");
+  if (truthDocsRoot && normalizedPath.startsWith(`${truthDocsRoot}/`)) {
     return "behavior";
   }
-  if (normalizedPath.startsWith("docs/contracts/") || normalizedPath.startsWith("docs/contract/") || normalizedPath.startsWith("docs/api/")) {
-    return "contract";
-  }
-  if (normalizedPath.startsWith("docs/architecture/")) {
-    return "architecture";
-  }
-  if (normalizedPath.startsWith("docs/workflows/") || normalizedPath.startsWith("docs/workflow/")) {
-    return "workflow";
-  }
-  if (normalizedPath.startsWith("docs/operations/") || normalizedPath.startsWith("docs/platform/")) {
-    return "operations";
-  }
-  if (normalizedPath.startsWith("docs/testing/") || normalizedPath.startsWith("docs/tests/")) {
-    return "test-behavior";
-  }
   return null;
 };
 var findTruthDocumentsYamlFenceRange = (sectionLines) => {
@@ -738,9 +725,8 @@ var parseAreasMarkdown = (source, options = {}) => {
 };
 
 // src/truth/docs.ts
-var DEFAULT_TRUTH_DOCS_ROOT = DEFAULT_DOCS_HIERARCHY.roots.truth;
 var resolveTruthDocsRoot = (config) => {
-  return config.docs.roots.truth ?? DEFAULT_TRUTH_DOCS_ROOT;
+  return config.truthmark.paths.truthRoot;
 };
 
 // src/templates/init-files.ts
@@ -759,11 +745,11 @@ var titleCase = (value) => {
   return value.split(/[-_\s]+/u).filter(Boolean).map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1)).join(" ");
 };
 var renderHierarchicalAreasIndexTemplate = (config) => {
-  const defaultArea = config.docs.routing.defaultArea;
-  const childPath = `${config.docs.routing.areaFilesRoot}/${defaultArea}.md`;
+  const defaultArea = config.truthmark.routes.defaultArea;
+  const childPath = `${config.truthmark.paths.routeAreasRoot}/${defaultArea}.md`;
   const title = titleCase(defaultArea);
   const sourceOfTruth = resolveRelativePath(
-    config.docs.routing.rootIndex,
+    config.truthmark.paths.routesIndex,
     ".truthmark/config.yml"
   );
   return [
@@ -792,11 +778,11 @@ var renderHierarchicalAreasIndexTemplate = (config) => {
   ].join("\n");
 };
 var renderChildAreaTemplate = (config) => {
-  const defaultArea = config.docs.routing.defaultArea;
+  const defaultArea = config.truthmark.routes.defaultArea;
   const title = titleCase(defaultArea);
   const truthDocsRoot = truthRoot(config);
   const leafTruthDoc = `${truthDocsRoot}/${defaultArea}/overview.md`;
-  const templatePath = `${config.docs.routing.areaFilesRoot}/${defaultArea}.md`;
+  const templatePath = `${config.truthmark.paths.routeAreasRoot}/${defaultArea}.md`;
   const sourceOfTruth = resolveRelativePath(templatePath, ".truthmark/config.yml");
   return [
     "---",
@@ -830,7 +816,7 @@ var renderTruthRootReadmeTemplate = (config = createDefaultConfig()) => {
   const templatePath = `${truthRoot(config)}/README.md`;
   const sourceOfTruth = resolveRelativePath(
     templatePath,
-    config.docs.routing.rootIndex
+    config.truthmark.paths.routesIndex
   );
   return [
     "---",
@@ -850,12 +836,12 @@ var renderTruthRootReadmeTemplate = (config = createDefaultConfig()) => {
   ].join("\n");
 };
 var renderTruthDomainReadmeTemplate = (config) => {
-  const defaultArea = config.docs.routing.defaultArea;
+  const defaultArea = config.truthmark.routes.defaultArea;
   const title = titleCase(defaultArea);
   const templatePath = `${truthRoot(config)}/${defaultArea}/README.md`;
   const sourceOfTruth = resolveRelativePath(
     templatePath,
-    `${config.docs.routing.areaFilesRoot}/${defaultArea}.md`
+    `${config.truthmark.paths.routeAreasRoot}/${defaultArea}.md`
   );
   return [
     "---",
@@ -878,12 +864,103 @@ var renderTruthDomainReadmeTemplate = (config) => {
     ""
   ].join("\n");
 };
-var BEHAVIOR_DOC_TEMPLATE_PATH = "docs/templates/behavior-doc.md";
-var CONTRACT_DOC_TEMPLATE_PATH = "docs/templates/contract-doc.md";
-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 BEHAVIOR_DOC_TEMPLATE_PATH = "docs/truthmark/templates/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 [
     "---",
@@ -899,81 +976,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",
@@ -986,86 +1112,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) => {
@@ -1074,12 +1267,12 @@ var renderTemplate = (template, values) => {
   }, template);
 };
 var renderBehaviorLeafDocTemplate = (config, template = renderBehaviorDocTemplateFile()) => {
-  const defaultArea = config.docs.routing.defaultArea;
+  const defaultArea = config.truthmark.routes.defaultArea;
   const title = titleCase(defaultArea);
   const templatePath = `${truthRoot(config)}/${defaultArea}/overview.md`;
   const sourceOfTruth = resolveRelativePath(
     templatePath,
-    `${config.docs.routing.areaFilesRoot}/${defaultArea}.md`
+    `${config.truthmark.paths.routeAreasRoot}/${defaultArea}.md`
   );
   const today = currentDate();
   return renderTemplate(template, {
@@ -1187,18 +1380,15 @@ import { Ajv } from "ajv";
 import { parse as parse2 } from "yaml";
 var ajv = new Ajv({ allErrors: true });
 var validateTruthmarkConfig = ajv.compile(truthmarkConfigSchema);
-var toConfigDiagnostic = (message, file) => {
-  return {
-    category: "config",
-    severity: "error",
-    message,
-    file
-  };
-};
+var toConfigDiagnostic = (message, file) => ({
+  category: "config",
+  severity: "error",
+  message,
+  file
+});
 var normalizeRepoRelativePath = (value) => {
   const slashNormalized = value.replace(/\\/gu, "/");
-  const pathNormalized = path4.posix.normalize(slashNormalized).replace(/\/+$/u, "");
-  return pathNormalized;
+  return path4.posix.normalize(slashNormalized).replace(/\/+$/u, "");
 };
 var isUnsafeRepoRelativePath = (value) => {
   const slashNormalized = value.replace(/\\/gu, "/");
@@ -1206,85 +1396,153 @@ var isUnsafeRepoRelativePath = (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 joinWorkspacePath = (workspace, childPath) => {
+  return normalizeRepoRelativePath(`${workspace}/${childPath}`);
+};
+var portalOutputFor = (workspace) => joinWorkspacePath(workspace, "generated/portal");
+var portalTemplateFor = (templatesRoot) => joinWorkspacePath(templatesRoot, "portal.html");
 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) {
+var CONFIG_PATH2 = ".truthmark/config.yml";
+var FORBIDDEN_WORKSPACE_OVERLAPS = [
+  ".git",
+  ".truthmark",
+  "package.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "src",
+  "tests"
+];
+var unsupportedShapeDiagnostics = (parsedConfig, configPath) => {
+  if (!parsedConfig || typeof parsedConfig !== "object" || Array.isArray(parsedConfig)) {
     return [];
   }
+  const record = parsedConfig;
   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))) {
+  if (record.version !== 2) {
     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.",
+        "Unsupported Truthmark config shape. This release requires version: 2 with a truthmark workspace block.",
         configPath
       )
     );
   }
-  if (template !== "default" && isUnsafeRepoRelativePath(template)) {
+  if ("docs" in record || "authority" in record) {
     diagnostics.push(
       toConfigDiagnostic(
-        "truthmark-portal.template must be 'default' or a non-empty repo-relative template path without absolute or parent traversal segments.",
+        "Unsupported Truthmark config shape. Remove old docs.roots and legacy authority settings; use version: 2 truthmark.workspace paths.",
         configPath
       )
     );
   }
   return diagnostics;
 };
+var validateWorkspacePaths = (rawConfig, configPath) => {
+  const diagnostics = [];
+  const workspace = normalizeRepoRelativePath(rawConfig.truthmark.workspace);
+  const childPaths = [
+    ["truthmark.routes.index", rawConfig.truthmark.routes.index],
+    ["truthmark.routes.areas", rawConfig.truthmark.routes.areas],
+    ["truthmark.truth.root", rawConfig.truthmark.truth.root],
+    ["truthmark.templates.root", rawConfig.truthmark.templates.root]
+  ];
+  if (isUnsafeRepoRelativePath(rawConfig.truthmark.workspace) || FORBIDDEN_WORKSPACE_OVERLAPS.some((forbidden) => pathsOverlap(workspace, forbidden))) {
+    diagnostics.push(
+      toConfigDiagnostic(
+        "truthmark.workspace must be a non-empty repo-relative directory that does not overlap repository control, package, source, test, or instruction paths.",
+        configPath
+      )
+    );
+  }
+  for (const [name, value] of childPaths) {
+    if (isUnsafeRepoRelativePath(value)) {
+      diagnostics.push(
+        toConfigDiagnostic(
+          `${name} must be a non-empty path relative to truthmark.workspace without absolute or parent traversal segments.`,
+          configPath
+        )
+      );
+    }
+  }
+  const portalOutput = normalizeRepoRelativePath("generated/portal");
+  const controlledWorkspaceChildren = [
+    ["truthmark.routes.index", rawConfig.truthmark.routes.index],
+    ["truthmark.routes.areas", rawConfig.truthmark.routes.areas],
+    ["truthmark.truth.root", rawConfig.truthmark.truth.root],
+    ["truthmark.templates.root", rawConfig.truthmark.templates.root]
+  ];
+  for (const [name, value] of controlledWorkspaceChildren) {
+    if (pathsOverlap(portalOutput, value)) {
+      diagnostics.push(
+        toConfigDiagnostic(
+          `Truthmark Portal output ${portalOutputFor(workspace)} must not overlap ${name}; Portal output is generated and must stay outside controlled truth, routing, and template paths.`,
+          configPath
+        )
+      );
+    }
+  }
+  for (const target of rawConfig.instruction_targets ?? DEFAULT_INSTRUCTION_TARGETS) {
+    if (isUnsafeRepoRelativePath(target) || pathsOverlap(workspace, target)) {
+      diagnostics.push(
+        toConfigDiagnostic(
+          "instruction_targets must be repo-relative files outside truthmark.workspace.",
+          configPath
+        )
+      );
+    }
+  }
+  return diagnostics;
+};
 var normalizeConfig = (rawConfig) => {
-  const rawDocs = rawConfig.docs ?? {
-    layout: DEFAULT_DOCS_HIERARCHY.layout,
-    roots: { ...DEFAULT_DOCS_HIERARCHY.roots },
-    routing: { ...DEFAULT_DOCS_HIERARCHY.routing }
-  };
-  const roots = { ...DEFAULT_DOCS_HIERARCHY.roots, ...rawDocs.roots };
+  const workspace = normalizeRepoRelativePath(rawConfig.truthmark.workspace);
+  const routesIndex = joinWorkspacePath(workspace, rawConfig.truthmark.routes.index);
+  const routeAreasRoot = joinWorkspacePath(workspace, rawConfig.truthmark.routes.areas);
+  const truthRoot3 = joinWorkspacePath(workspace, rawConfig.truthmark.truth.root);
+  const templatesRoot = joinWorkspacePath(workspace, rawConfig.truthmark.templates.root);
+  const portalOutput = portalOutputFor(workspace);
+  const portalTemplate = portalTemplateFor(templatesRoot);
   return {
     version: rawConfig.version,
     platforms: rawConfig.platforms ?? [...DEFAULT_PLATFORMS],
-    docs: {
-      layout: rawDocs.layout,
-      roots,
-      routing: {
-        rootIndex: rawDocs.routing.root_index,
-        areaFilesRoot: rawDocs.routing.area_files_root,
-        defaultArea: rawDocs.routing.default_area,
-        maxDelegationDepth: rawDocs.routing.max_delegation_depth
-      }
+    truthmark: {
+      workspace,
+      routes: {
+        index: normalizeRepoRelativePath(rawConfig.truthmark.routes.index),
+        areas: normalizeRepoRelativePath(rawConfig.truthmark.routes.areas),
+        defaultArea: rawConfig.truthmark.routes.default_area,
+        maxDelegationDepth: rawConfig.truthmark.routes.max_delegation_depth
+      },
+      truth: {
+        root: normalizeRepoRelativePath(rawConfig.truthmark.truth.root)
+      },
+      templates: {
+        root: normalizeRepoRelativePath(rawConfig.truthmark.templates.root)
+      },
+      generated: {
+        portal: {
+          enabled: rawConfig.truthmark.generated.portal.enabled
+        }
+      },
+      paths: {
+        routesIndex,
+        routeAreasRoot,
+        truthRoot: truthRoot3,
+        templatesRoot,
+        portalOutput,
+        portalTemplate
+      },
+      controlledPaths: [
+        routesIndex,
+        `${routeAreasRoot}/**/*.md`,
+        `${truthRoot3}/**/*.md`,
+        `${templatesRoot}/*.md`
+      ]
     },
-    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 ?? []
@@ -1293,8 +1551,7 @@ var normalizeConfig = (rawConfig) => {
   };
 };
 var loadConfig = async (rootDir) => {
-  const configPath = ".truthmark/config.yml";
-  const absolutePath = resolveRepoPath(rootDir, configPath);
+  const absolutePath = resolveRepoPath(rootDir, CONFIG_PATH2);
   let source;
   try {
     source = await fs4.readFile(absolutePath, "utf8");
@@ -1303,8 +1560,8 @@ var loadConfig = async (rootDir) => {
       return {
         status: "missing",
         config: null,
-        diagnostics: [toConfigDiagnostic("Missing .truthmark/config.yml.", configPath)],
-        configPath
+        diagnostics: [toConfigDiagnostic("Missing .truthmark/config.yml.", CONFIG_PATH2)],
+        configPath: CONFIG_PATH2
       };
     }
     throw error;
@@ -1319,10 +1576,19 @@ var loadConfig = async (rootDir) => {
       diagnostics: [
         toConfigDiagnostic(
           `Invalid YAML: ${error instanceof Error ? error.message : String(error)}`,
-          configPath
+          CONFIG_PATH2
         )
       ],
-      configPath
+      configPath: CONFIG_PATH2
+    };
+  }
+  const unsupportedDiagnostics = unsupportedShapeDiagnostics(parsedConfig, CONFIG_PATH2);
+  if (unsupportedDiagnostics.length > 0) {
+    return {
+      status: "invalid",
+      config: null,
+      diagnostics: unsupportedDiagnostics,
+      configPath: CONFIG_PATH2
     };
   }
   if (!validateTruthmarkConfig(parsedConfig)) {
@@ -1333,49 +1599,30 @@ var loadConfig = async (rootDir) => {
         const propertyPath = error.instancePath || "/";
         const additionalProperty = error.keyword === "additionalProperties" && error.params && "additionalProperty" in error.params ? String(error.params.additionalProperty) : null;
         const message = additionalProperty ? `${propertyPath} additional property ${additionalProperty} is not allowed` : `${propertyPath} ${error.message ?? "is invalid"}`.trim();
-        return toConfigDiagnostic(message, configPath);
+        return toConfigDiagnostic(message, CONFIG_PATH2);
       }),
-      configPath
+      configPath: CONFIG_PATH2
     };
   }
-  const portalDiagnostics = validatePortalConfig(
-    parsedConfig,
-    configPath
-  );
-  if (portalDiagnostics.length > 0) {
+  const pathDiagnostics = validateWorkspacePaths(parsedConfig, CONFIG_PATH2);
+  if (pathDiagnostics.length > 0) {
     return {
       status: "invalid",
       config: null,
-      diagnostics: portalDiagnostics,
-      configPath
+      diagnostics: pathDiagnostics,
+      configPath: CONFIG_PATH2
     };
   }
   return {
     status: "loaded",
     config: normalizeConfig(parsedConfig),
     diagnostics: [],
-    configPath
+    configPath: CONFIG_PATH2
   };
 };
 
 // src/init/hierarchy.ts
 import fs5 from "fs/promises";
-import fg from "fast-glob";
-var KNOWN_DEFAULT_ROOTS = [
-  DEFAULT_DOCS_HIERARCHY.roots.truth,
-  "docs/api",
-  DEFAULT_DOCS_HIERARCHY.roots.architecture,
-  DEFAULT_DOCS_HIERARCHY.roots.standards,
-  "docs/guides"
-];
-var hasMarkdownFiles = async (rootDir, root) => {
-  const matches = await fg([`${root}/**/*.md`], {
-    cwd: rootDir,
-    onlyFiles: true,
-    followSymbolicLinks: false
-  });
-  return matches.length > 0;
-};
 var truthRoot2 = resolveTruthDocsRoot;
 var rootIndexReferencesChildRoute = async (rootDir, rootIndexPath, childRoutePath) => {
   const rootIndexSource = await fs5.readFile(resolveRepoPath(rootDir, rootIndexPath), "utf8");
@@ -1384,9 +1631,15 @@ var rootIndexReferencesChildRoute = async (rootDir, rootIndexPath, childRoutePat
     (areaReference) => areaReference.areaFiles.includes(childRoutePath)
   );
 };
-var readBehaviorDocTemplate = async (rootDir) => {
+var truthTemplatePath = (config, fileName) => {
+  return `${config.truthmark.paths.templatesRoot}/${fileName}`;
+};
+var readBehaviorDocTemplate = async (rootDir, config) => {
   try {
-    return await fs5.readFile(resolveRepoPath(rootDir, BEHAVIOR_DOC_TEMPLATE_PATH), "utf8");
+    return await fs5.readFile(
+      resolveRepoPath(rootDir, truthTemplatePath(config, "behavior-doc.md")),
+      "utf8"
+    );
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT") {
       return renderBehaviorDocTemplateFile();
@@ -1394,19 +1647,28 @@ 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);
-  const truthDomainRoot = `${truthDocsRoot}/${config.docs.routing.defaultArea}`;
-  const childRoutePath = `${config.docs.routing.areaFilesRoot}/${config.docs.routing.defaultArea}.md`;
+  const truthDomainRoot = `${truthDocsRoot}/${config.truthmark.routes.defaultArea}`;
+  const childRoutePath = `${config.truthmark.paths.routeAreasRoot}/${config.truthmark.routes.defaultArea}.md`;
   results.push(
     await ensureRepoFile(
       rootDir,
-      config.docs.routing.rootIndex,
+      config.truthmark.paths.routesIndex,
       renderHierarchicalAreasIndexTemplate(config)
     )
   );
-  if (await rootIndexReferencesChildRoute(rootDir, config.docs.routing.rootIndex, childRoutePath)) {
+  if (await rootIndexReferencesChildRoute(rootDir, config.truthmark.paths.routesIndex, childRoutePath)) {
     results.push(await ensureRepoFile(rootDir, childRoutePath, renderChildAreaTemplate(config)));
   }
   results.push(
@@ -1424,32 +1686,48 @@ var scaffoldHierarchy = async (rootDir, config) => {
     )
   );
   results.push(
-    await ensureRepoFile(rootDir, BEHAVIOR_DOC_TEMPLATE_PATH, renderBehaviorDocTemplateFile())
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      truthTemplatePath(config, "behavior-doc.md"),
+      renderBehaviorDocTemplateFile()
+    )
   );
   results.push(
-    await ensureRepoFile(rootDir, CONTRACT_DOC_TEMPLATE_PATH, renderContractDocTemplateFile())
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      truthTemplatePath(config, "contract-doc.md"),
+      renderContractDocTemplateFile()
+    )
   );
   results.push(
-    await ensureRepoFile(
+    await ensureOrUpdateTruthDocTemplate(
       rootDir,
-      ARCHITECTURE_DOC_TEMPLATE_PATH,
+      truthTemplatePath(config, "architecture-doc.md"),
       renderArchitectureDocTemplateFile()
     )
   );
   results.push(
-    await ensureRepoFile(rootDir, WORKFLOW_DOC_TEMPLATE_PATH, renderWorkflowDocTemplateFile())
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      truthTemplatePath(config, "workflow-doc.md"),
+      renderWorkflowDocTemplateFile()
+    )
   );
   results.push(
-    await ensureRepoFile(rootDir, OPERATIONS_DOC_TEMPLATE_PATH, renderOperationsDocTemplateFile())
+    await ensureOrUpdateTruthDocTemplate(
+      rootDir,
+      truthTemplatePath(config, "operations-doc.md"),
+      renderOperationsDocTemplateFile()
+    )
   );
   results.push(
-    await ensureRepoFile(
+    await ensureOrUpdateTruthDocTemplate(
       rootDir,
-      TEST_BEHAVIOR_DOC_TEMPLATE_PATH,
+      truthTemplatePath(config, "test-behavior-doc.md"),
       renderTestBehaviorDocTemplateFile()
     )
   );
-  const behaviorDocTemplate = await readBehaviorDocTemplate(rootDir);
+  const behaviorDocTemplate = await readBehaviorDocTemplate(rootDir, config);
   results.push(
     await ensureRepoFile(
       rootDir,
@@ -1459,24 +1737,6 @@ var scaffoldHierarchy = async (rootDir, config) => {
   );
   return results;
 };
-var detectHierarchyMigrationDiagnostics = async (rootDir, config) => {
-  const configuredRoots = new Set(Object.values(config.docs.roots));
-  const diagnostics = [];
-  for (const defaultRoot of KNOWN_DEFAULT_ROOTS) {
-    if (configuredRoots.has(defaultRoot)) {
-      continue;
-    }
-    if (await hasMarkdownFiles(rootDir, defaultRoot)) {
-      diagnostics.push({
-        category: "config",
-        severity: "review",
-        message: `Configured hierarchy no longer includes ${defaultRoot}, but markdown still exists there. Perform manual migration before relying on the new hierarchy.`,
-        file: ".truthmark/config.yml"
-      });
-    }
-  }
-  return diagnostics;
-};
 
 // src/truth/evidence.ts
 var renderClaimEvidenceCheckedSection = (items) => {
@@ -1521,11 +1781,12 @@ var REPOSITORY_INTELLIGENCE_INSTRUCTIONS = [
   "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.",
+  "When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.",
   "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."
+  "Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards."
 ].join("\n");
 var renderTruthDocOwnershipGateSection = (subject, outcome) => {
   return [
@@ -1699,8 +1960,8 @@ var renderHierarchySummary = (config) => {
   return [
     "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`,
+    `- Root route index, when present: ${config.truthmark.paths.routesIndex}`,
+    `- Area route files, when present: ${config.truthmark.paths.routeAreasRoot}/**/*.md`,
     `- Truth docs, when present: ${truthRoot3}/**/*.md`
   ].join("\n");
 };
@@ -1717,10 +1978,10 @@ var TRUTHMARK_BLOCK_START = "<!-- truthmark:start -->";
 var TRUTHMARK_BLOCK_END = "<!-- truthmark:end -->";
 var renderCompactHierarchySummary = (config) => {
   const truthRoot3 = resolveTruthDocsRoot(config);
-  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.`;
+  return `Hierarchy hints: config .truthmark/config.yml when present; routes ${config.truthmark.paths.routesIndex} and ${config.truthmark.paths.routeAreasRoot}/**/*.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;
+  const portalLine = config.truthmark.generated.portal.enabled ? `Truthmark Portal is a separate manual-only presentation workflow. Run it only when explicitly requested; it writes generated non-canonical static files under ${config.truthmark.paths.portalOutput}/. Markdown remains canonical.` : null;
   return [
     TRUTHMARK_BLOCK_START,
     "## Truthmark Workflow",
@@ -1740,70 +2001,6 @@ var renderAgentsBlock = (config = defaultAgentConfig()) => {
   ].join("\n");
 };
 
-// src/templates/default-standards.ts
-var DEFAULT_STANDARDS = [
-  {
-    path: "docs/standards/default-principles.md",
-    content: `---
-status: active
-doc_type: standard
-last_reviewed: 2026-05-03
-source_of_truth:
-  - README.md
----
-
-# Default Principles
-
-## Scope
-
-This is a bootstrap standards baseline for repositories that adopt Truthmark.
-
-## Reusable Defaults
-
-- Authority order should be explicit.
-- Committed repository artifacts are the durable source of truth.
-- Each document should have one primary responsibility.
-- Each class of fact should have one canonical source.
-- Architecture docs describe system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, and generated-surface ownership.
-- Do not put ordinary feature behavior in architecture docs.
-- Verification should be explicit, and skipped checks should state why.
-- Missing, stale, broad, overloaded, or unrouteable documentation topology should be repaired through AI-native structure workflow before agents create more generic truth docs.
-- Installed repository workflows should remain usable from committed files even when the Truthmark CLI is unavailable.
-`
-  },
-  {
-    path: "docs/standards/documentation-governance.md",
-    content: `---
-status: active
-doc_type: standard
-last_reviewed: 2026-05-03
-source_of_truth:
-  - README.md
----
-
-# Documentation Governance
-
-## Core Rules
-
-- Each document should have one primary responsibility.
-- Each class of fact should have one canonical source.
-- Current implementation, reusable standards, and future proposals should be stored separately.
-- Generated helper output is never canonical truth.
-- Architecture docs describe structure and ownership; truth docs describe current product behavior.
-
-## Truthmark Implications
-
-- Truth Sync should extend mapped docs first, create an area-local doc second, and create a new area only as a last resort.
-- Weak routing produces weak truth maintenance.
-- Missing, stale, broad, overloaded, or unrouteable routing should trigger Truth Structure before more generic truth docs are created.
-`
-  }
-];
-var renderDefaultStandards = (documents) => {
-  const existingPaths = new Set(documents.map((document) => document.path));
-  return DEFAULT_STANDARDS.filter((template) => !existingPaths.has(template.path));
-};
-
 // src/templates/workflow-surfaces.ts
 import { stringify as stringify2 } from "yaml";
 
@@ -2087,7 +2284,7 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "generate the Truthmark Portal",
       "refresh the committed HTML docs site",
       "create a browsable project map from Truthmark docs",
-      "update docs/truthmark-portal",
+      "update the Truthmark Portal output",
       "make a human-readable static site from the truth docs"
     ],
     negativeTriggers: [
@@ -2101,7 +2298,7 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
     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"
+      "must not write outside the fixed Portal output directory"
     ],
     requiredGates: [
       "manual-only invocation",
@@ -2109,7 +2306,7 @@ var TRUTHMARK_WORKFLOW_MANIFEST = {
       "Markdown canonical statement",
       "source provenance"
     ],
-    allowedWrites: ["configured Portal output directory only"],
+    allowedWrites: ["fixed Portal output directory only"],
     reportSections: [
       "Output path",
       "Page count",
@@ -2134,7 +2331,7 @@ var renderMarkdownExample = (content) => {
 };
 var TRUTH_CHECK_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Gemini CLI /truthmark:check.";
 var renderTruthCheckReportExample = (config = defaultAgentConfig()) => {
-  const rootRouteIndex = config.docs.routing.rootIndex;
+  const rootRouteIndex = config.truthmark.paths.routesIndex;
   return `Truth Check: completed
 
 Files reviewed:
@@ -2203,7 +2400,7 @@ Truth Check is agent-led:
 
 - 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}/ when they exist
+- inspect the configured root route index at ${config.truthmark.paths.routesIndex} and relevant child route files under ${config.truthmark.paths.routeAreasRoot}/ when they exist
 - check that current docs describe current code rather than historical plans
 - 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
@@ -2236,7 +2433,7 @@ Implementation reviewed:
 - src/routing/area-resolver.ts
 
 Ownership reviewed:
-- ${config.docs.routing.rootIndex}
+- ${config.truthmark.paths.routesIndex}
 
 Truth docs created:
 - ${truthDocsRoot}/contracts.md
@@ -2248,14 +2445,14 @@ Truth docs restructured:
 - ${truthDocsRoot}/check-diagnostics.md
 
 Routing updated:
-- ${config.docs.routing.rootIndex}
+- ${config.truthmark.paths.routesIndex}
 
 ${renderClaimEvidenceCheckedSection([
     {
       claim: "Route resolution behavior is documented in the contracts truth doc.",
       evidence: [
         "src/routing/area-resolver.ts:14",
-        `${config.docs.routing.rootIndex}:9`
+        `${config.truthmark.paths.routesIndex}:9`
       ],
       result: "supported"
     }
@@ -2313,7 +2510,7 @@ Truth Document is manual and implementation-first:
 - 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
+- may write canonical truth docs and ${config.truthmark.paths.routesIndex} or relevant child route files only
 - must not write functional code
 - when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope
 - block and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
@@ -2376,7 +2573,7 @@ Why this workflow:
 - forbidden adjacency considered: must not edit functional code
 
 Likely route owner:
-- route file: ${config.docs.routing.rootIndex}
+- route file: ${config.truthmark.paths.routesIndex}
 - truth doc: ${truthDocsRoot}/example.md
 - confidence: medium
 
@@ -2420,8 +2617,8 @@ Purpose:
 
 Read:
 - .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
+- ${config.truthmark.paths.routesIndex}, only when present
+- relevant child route files under ${config.truthmark.paths.routeAreasRoot}/, only when present
 - relevant truth docs and implementation files needed to preview ownership
 - ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
 
@@ -2450,12 +2647,12 @@ ${renderMarkdownExample3(renderTruthPreviewReportExample(config))}`;
 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;
+  const output = config.truthmark.paths.portalOutput;
+  const template = config.truthmark.paths.portalTemplate;
   return `---
 name: truthmark-portal
 description: ${workflow.description}
-argument-hint: Optional output path, template, or portal generation focus
+argument-hint: Optional portal generation focus
 user-invocable: true
 truthmark-version: ${TRUTHMARK_VERSION}
 ---
@@ -2471,9 +2668,9 @@ 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.
+- Determined Portal output is ${output}.
+- Determined Portal template path is ${template}; use built-in template instructions if that file is absent.
+- The workflow may replace the entire output directory, but writes are limited to the fixed Portal output directory only.
 - 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.
@@ -2485,8 +2682,8 @@ Core rules:
 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.
+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 determined Portal template when present.
+3. Validate the determined 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.
@@ -2533,11 +2730,11 @@ var renderTruthStructureReportExample = (config = defaultAgentConfig()) => {
 Topology reviewed:
 - controllers: src/auth/**
 - docs root: ${truthDocsRoot}
-- route files: ${config.docs.routing.rootIndex}
+- route files: ${config.truthmark.paths.routesIndex}
 Areas reviewed:
 - src/auth/**
 Routing updated:
-- ${config.docs.routing.rootIndex}
+- ${config.truthmark.paths.routesIndex}
 Initial truth boundary:
 - Area: Authentication
 - Code: src/auth/**
@@ -2552,7 +2749,7 @@ Truth docs restructured:
 ${renderClaimEvidenceCheckedSection([
     {
       claim: "Session behavior belongs to a dedicated Authentication truth owner.",
-      evidence: ["src/auth/**", `${config.docs.routing.rootIndex}:7`],
+      evidence: ["src/auth/**", `${config.truthmark.paths.routesIndex}:7`],
       result: "supported"
     }
   ])}
@@ -2588,15 +2785,15 @@ Invocations: ${TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS}
 Truth Structure is agent-native:
 - 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}/ when they exist
+- inspect the configured root route index at ${config.truthmark.paths.routesIndex} and relevant child route files under ${config.truthmark.paths.routeAreasRoot}/ when they exist
 - define areas by product or behavior ownership, not by mechanical directory mirroring
-- create or repair ${config.docs.routing.rootIndex}
+- create or repair ${config.truthmark.paths.routesIndex}
 - create starter truth docs when useful and when they belong in the canonical current-truth surface
 - Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, doc_type, last_reviewed, and source_of_truth inside that frontmatter.
 - Starter truth docs must include ## Product Decisions and ## Rationale sections.
 ${subagentMode}
 ${FEATURE_DOC_TEMPLATE_INSTRUCTIONS}
-- use ${truthDocsRoot}/**, docs/architecture/**, or docs/standards/** for current truth destinations
+- use ${truthDocsRoot}/** for current truth destinations
 - use only canonical current-truth destinations for starter truth docs
 - keep active Product Decisions and Rationale in the canonical doc that owns the behavior
 - preserve unrelated authored content
@@ -2631,7 +2828,7 @@ Topology pressure signals:
 - the configured truth root has many direct non-index docs
 - a changed controller, route, or service cannot map to a specific behavior doc
 - Truth Sync would need to create a new generic truth doc because routing is too broad
-- endpoint or controller names reveal domains missing from ${config.docs.routing.areaFilesRoot}/**
+- endpoint or controller names reveal domains missing from ${config.truthmark.paths.routeAreasRoot}/**
 Use these review thresholds as guidance:
 - more than 10 direct truth docs in one folder
 - more than 15 leaf areas in one child route file
@@ -2640,7 +2837,7 @@ Use these review thresholds as guidance:
 Repair rules:
 - split broad, overloaded, or catch-all areas into behavior-owned child route files
 - split mixed-owner truth docs into bounded owner docs before adding new behavior claims
-- create route files under ${config.docs.routing.areaFilesRoot}/ when a product/domain boundary is clear
+- create route files under ${config.truthmark.paths.routeAreasRoot}/ when a product/domain boundary is clear
 - create behavior truth docs under the configured truth root only when behavior lacks a current doc
 - README.md files are indexes, not Truth Sync targets
 - prefer bounded leaf truth docs at <truth-root>/<domain>/<behavior>.md
@@ -2879,12 +3076,12 @@ Report completion in this shape:
 ${renderMarkdownExample5(
     renderTruthSyncCompletedReport({
       changedCode: ["src/auth/session.ts"],
-      ownershipReviewed: [config.docs.routing.rootIndex],
+      ownershipReviewed: [config.truthmark.paths.routesIndex],
       truthDocsUpdated: [`${truthDocsRoot}/repository/overview.md`],
       evidenceChecked: [
         {
           claim: "Session timeout behavior is documented in the mapped repository truth doc.",
-          evidence: ["src/auth/session.ts:12", `${config.docs.routing.rootIndex}:11`],
+          evidence: ["src/auth/session.ts:12", `${config.truthmark.paths.routesIndex}:11`],
           result: "supported"
         }
       ],
@@ -2896,7 +3093,7 @@ Blocked report example:
 ${renderMarkdownExample5(
     renderTruthSyncBlockedReport({
       reason: "routing repair is not allowed",
-      manualReviewFiles: [config.docs.routing.rootIndex],
+      manualReviewFiles: [config.truthmark.paths.routesIndex],
       nextAction: "update routing metadata and rerun Truth Sync"
     })
   )}`;
@@ -2919,20 +3116,20 @@ var TRUTHMARK_WRITE_WORKER_REPORT_FIELDS = [
 ];
 
 // src/templates/workflow-surfaces.ts
-var TRUTHMARK_STRUCTURE_SKILL_PATH = ".codex/skills/truthmark-structure/SKILL.md";
-var TRUTHMARK_STRUCTURE_SKILL_METADATA_PATH = ".codex/skills/truthmark-structure/agents/openai.yaml";
-var TRUTHMARK_DOCUMENT_SKILL_PATH = ".codex/skills/truthmark-document/SKILL.md";
-var TRUTHMARK_DOCUMENT_SKILL_METADATA_PATH = ".codex/skills/truthmark-document/agents/openai.yaml";
-var TRUTHMARK_SYNC_SKILL_PATH = ".codex/skills/truthmark-sync/SKILL.md";
-var TRUTHMARK_SYNC_SKILL_METADATA_PATH = ".codex/skills/truthmark-sync/agents/openai.yaml";
-var TRUTHMARK_REALIZE_SKILL_PATH = ".codex/skills/truthmark-realize/SKILL.md";
-var TRUTHMARK_REALIZE_SKILL_METADATA_PATH = ".codex/skills/truthmark-realize/agents/openai.yaml";
-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_STRUCTURE_SKILL_PATH = ".agents/skills/truthmark-structure/SKILL.md";
+var TRUTHMARK_STRUCTURE_SKILL_METADATA_PATH = ".agents/skills/truthmark-structure/agents/openai.yaml";
+var TRUTHMARK_DOCUMENT_SKILL_PATH = ".agents/skills/truthmark-document/SKILL.md";
+var TRUTHMARK_DOCUMENT_SKILL_METADATA_PATH = ".agents/skills/truthmark-document/agents/openai.yaml";
+var TRUTHMARK_SYNC_SKILL_PATH = ".agents/skills/truthmark-sync/SKILL.md";
+var TRUTHMARK_SYNC_SKILL_METADATA_PATH = ".agents/skills/truthmark-sync/agents/openai.yaml";
+var TRUTHMARK_REALIZE_SKILL_PATH = ".agents/skills/truthmark-realize/SKILL.md";
+var TRUTHMARK_REALIZE_SKILL_METADATA_PATH = ".agents/skills/truthmark-realize/agents/openai.yaml";
+var TRUTHMARK_CHECK_SKILL_PATH = ".agents/skills/truthmark-check/SKILL.md";
+var TRUTHMARK_CHECK_SKILL_METADATA_PATH = ".agents/skills/truthmark-check/agents/openai.yaml";
+var TRUTHMARK_PREVIEW_SKILL_PATH = ".agents/skills/truthmark-preview/SKILL.md";
+var TRUTHMARK_PREVIEW_SKILL_METADATA_PATH = ".agents/skills/truthmark-preview/agents/openai.yaml";
+var TRUTHMARK_PORTAL_SKILL_PATH = ".agents/skills/truthmark-portal/SKILL.md";
+var TRUTHMARK_PORTAL_SKILL_METADATA_PATH = ".agents/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";
@@ -2963,10 +3160,10 @@ var TRUTHMARK_COPILOT_REALIZE_PROMPT_PATH = ".github/prompts/truthmark-realize.p
 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";
-var TRUTHMARK_COPILOT_DOC_WRITER_AGENT_PATH = ".github/agents/truth-doc-writer.agent.md";
+var TRUTHMARK_COPILOT_ROUTE_AUDITOR_AGENT_PATH = ".github/agents/truth-route-auditor.md";
+var TRUTHMARK_COPILOT_CLAIM_VERIFIER_AGENT_PATH = ".github/agents/truth-claim-verifier.md";
+var TRUTHMARK_COPILOT_DOC_REVIEWER_AGENT_PATH = ".github/agents/truth-doc-reviewer.md";
+var TRUTHMARK_COPILOT_DOC_WRITER_AGENT_PATH = ".github/agents/truth-doc-writer.md";
 var renderGeminiCommand = (description, prompt) => {
   const promptWithArgs = `${prompt.trimEnd()}
 User focus or arguments: {{args}}`;
@@ -2992,7 +3189,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 routeFilesHint = (config) => `${config.truthmark.paths.routesIndex}; ${config.truthmark.paths.routeAreasRoot}/`;
 var WORKFLOW_PACKAGE_DEFINITIONS = {
   "truthmark-structure": {
     title: "Truthmark Structure",
@@ -3020,7 +3217,7 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
       "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.",
-      "Read support/subagents-and-leases.md before dispatching or accepting worker output.",
+      "Read support/subagents-and-leases.md only when dispatching or accepting worker output.",
       "Read support/report-template.md before the final report."
     ],
     parentRule: "Parent agent owns Truth Document acceptance, lease validation, and final report"
@@ -3037,7 +3234,7 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
       "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.",
-      "Read support/subagents-and-leases.md before dispatching or accepting worker output.",
+      "Read support/subagents-and-leases.md only when dispatching or accepting worker output.",
       "Read support/report-template.md before the final report."
     ],
     parentRule: "Parent agent owns Truth Sync acceptance, lease validation, and final report"
@@ -3080,16 +3277,15 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
       "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.",
-      "Read support/subagents-and-leases.md before dispatching verifier subagents.",
+      "Read support/subagents-and-leases.md only when dispatching verifier subagents.",
       "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",
+    argumentHint: "Optional 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) => [
@@ -3098,8 +3294,8 @@ var WORKFLOW_PACKAGE_DEFINITIONS = {
       "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.`,
+      `Write only under fixed Portal output ${config.truthmark.paths.portalOutput}.`,
+      `Use determined Portal template ${config.truthmark.paths.portalTemplate} when present; 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."
@@ -3203,7 +3399,25 @@ var renderStandaloneWorkflowSkillBody = (workflowId, config) => {
 var renderWorkflowEntrypoint = (workflowId, config, supportFiles, host) => {
   const workflow = getTruthmarkWorkflow(workflowId);
   const definition = WORKFLOW_PACKAGE_DEFINITIONS[workflowId];
-  const supportFileList = supportFiles.map((supportFile) => `- ${supportFile}`).join("\n");
+  const supportFileUsage = (supportFile) => {
+    if (supportFile === "support/procedure.md") {
+      return "read before edits or detailed auditing; contains core quality gates";
+    }
+    if (supportFile === "support/report-template.md") {
+      return "read before the final report";
+    }
+    if (supportFile === "support/subagents-and-leases.md") {
+      return "read only when using subagents, leases, or accepting worker output";
+    }
+    if (supportFile === "support/helper-policy.md") {
+      return "read only when invoking helper validators or reporting helper status";
+    }
+    if (supportFile === "helper-manifest.yml") {
+      return "read only when invoking helper validators or validating helper registration";
+    }
+    return "available when relevant to the current step";
+  };
+  const supportFileList = supportFiles.map((supportFile) => `- ${supportFile} \u2014 ${supportFileUsage(supportFile)}`).join("\n");
   const hostUsage = host === "github-copilot" ? "Use as a Copilot agent skill. Prompt files remain available under `.github/prompts/` for command-style invocation in supported Copilot IDEs." : host === "gemini-cli" ? "Use as a Gemini CLI Agent Skill; commands remain available under `/truthmark:*` for command-first invocation." : void 0;
   return `---
 name: ${workflowId}
@@ -3215,10 +3429,9 @@ truthmark-version: ${TRUTHMARK_VERSION}
 
 # ${definition.title}
 
-${definition.use(config)}
-${hostUsage === void 0 ? "" : `
-${hostUsage}
-`}
+${definition.use(config)}${hostUsage === void 0 ? "" : `
+
+${hostUsage}`}
 
 Invocations: ${definition.invocations}
 
@@ -3348,10 +3561,10 @@ var renderOpenCodeWriterEditAllowRules = (config) => {
     resolveTruthDocsRoot(config)
   );
   const rootRouteIndex = normalizeOpenCodePermissionPath(
-    config.docs.routing.rootIndex
+    config.truthmark.paths.routesIndex
   );
   const areaFilesRoot = normalizeOpenCodePermissionPath(
-    config.docs.routing.areaFilesRoot
+    config.truthmark.paths.routeAreasRoot
   );
   const allowedPatterns = [
     appendOpenCodePermissionGlob(truthDocsRoot, "/**"),
@@ -4121,7 +4334,7 @@ var codexFiles = (config) => {
       content: renderTruthmarkDocWriterAgent()
     }
   ];
-  if (config.truthmarkPortal.enabled) {
+  if (config.truthmark.generated.portal.enabled) {
     files.push(
       ...renderTruthmarkSkillPackage({
         skillPath: TRUTHMARK_PORTAL_SKILL_PATH,
@@ -4192,7 +4405,7 @@ var opencodeFiles = (config) => {
       content: renderTruthmarkOpenCodeDocWriterAgent(config)
     }
   ];
-  if (config.truthmarkPortal.enabled) {
+  if (config.truthmark.generated.portal.enabled) {
     files.push(
       ...renderTruthmarkSkillPackage({
         skillPath: ".opencode/skills/truthmark-portal/SKILL.md",
@@ -4260,7 +4473,7 @@ var claudeFiles = (config, block) => {
       content: renderTruthmarkClaudeDocWriterAgent()
     }
   ];
-  if (config.truthmarkPortal.enabled) {
+  if (config.truthmark.generated.portal.enabled) {
     files.push(
       ...renderTruthmarkSkillPackage({
         skillPath: ".claude/skills/truthmark-portal/SKILL.md",
@@ -4352,7 +4565,7 @@ var copilotFiles = (config, block) => {
       content: renderTruthmarkCopilotDocWriterAgent()
     }
   ];
-  if (config.truthmarkPortal.enabled) {
+  if (config.truthmark.generated.portal.enabled) {
     files.push(
       ...renderTruthmarkSkillPackage({
         skillPath: ".github/skills/truthmark-portal/SKILL.md",
@@ -4448,7 +4661,7 @@ var geminiFiles = (config, block) => {
       content: renderTruthmarkGeminiDocWriterAgent()
     }
   ];
-  if (config.truthmarkPortal.enabled) {
+  if (config.truthmark.generated.portal.enabled) {
     files.push(
       ...renderTruthmarkSkillPackage({
         skillPath: ".gemini/skills/truthmark-portal/SKILL.md",
@@ -4502,19 +4715,10 @@ var escapeRegExp = (value) => {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 };
 var MANAGED_WORKFLOW_HEADING = "## Truthmark Workflow";
-var LEGACY_MANAGED_LINES = [
-  "### Truth Sync",
-  "- may read changed functional code files",
-  "- may write truth docs only",
-  "- must not rewrite functional code"
-];
-var CANONICAL_MANAGED_LINES = /* @__PURE__ */ new Set(
-  [
-    ...renderAgentsBlock().split("\n").map((line) => line.trim()).filter(
-      (line) => line.length > 0 && line !== TRUTHMARK_BLOCK_START && line !== TRUTHMARK_BLOCK_END
-    ),
-    ...LEGACY_MANAGED_LINES
-  ]
+var CANONICAL_MANAGED_LINES = new Set(
+  renderAgentsBlock().split("\n").map((line) => line.trim()).filter(
+    (line) => line.length > 0 && line !== TRUTHMARK_BLOCK_START && line !== TRUTHMARK_BLOCK_END
+  )
 );
 var countCanonicalManagedLineMatches = (lines) => {
   return lines.reduce((matchCount, line) => {
@@ -4541,46 +4745,11 @@ 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(
-    `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 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 \`${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) => {
   if (!existingContent || existingContent.trim().length === 0) {
     return block;
   }
-  const normalizedExistingContent = normalizeLegacyInstructionPreamble(existingContent);
+  const normalizedExistingContent = existingContent;
   const startMarkerPattern = new RegExp(escapeRegExp(TRUTHMARK_BLOCK_START), "g");
   const endMarkerPattern = new RegExp(escapeRegExp(TRUTHMARK_BLOCK_END), "g");
   const managedBlockPattern = new RegExp(
@@ -4649,13 +4818,13 @@ var diagnosticCategoryForPath = (filePath, config) => {
   if (filePath === "AGENTS.md") {
     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/")) {
+  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(".agents/skills/truthmark-realize/") || filePath.startsWith(".gemini/skills/truthmark-realize/")) {
     return "realization";
   }
   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-")) {
+  if (filePath.startsWith(".agents/skills/truthmark-")) {
     return "truth-sync";
   }
   if (filePath.startsWith(".gemini/commands/truthmark/realize")) {
@@ -4664,8 +4833,8 @@ var diagnosticCategoryForPath = (filePath, config) => {
   if (filePath.startsWith(".gemini/commands/truthmark/")) {
     return "truth-sync";
   }
-  if (filePath === config.docs.routing.rootIndex) {
-    return "authority";
+  if (filePath === config.truthmark.paths.routesIndex) {
+    return "area-index";
   }
   return "config";
 };
@@ -4700,7 +4869,7 @@ var runInit = async (cwd) => {
   if (!loadedConfig.config) {
     return {
       command: "init",
-      summary: "Truthmark init requires .truthmark/config.yml. Run truthmark config first, review the hierarchy, then run truthmark init.",
+      summary: "Truthmark init requires .truthmark/config.yml. Run truthmark config first, review the workspace paths, then run truthmark init.",
       diagnostics: loadedConfig.diagnostics,
       data: {
         repositoryRoot: repository.repositoryRoot,
@@ -4711,14 +4880,9 @@ var runInit = async (cwd) => {
       }
     };
   }
-  const defaultStandards = renderDefaultStandards([]);
   const results = [];
-  for (const template of defaultStandards) {
-    results.push(await ensureRepoFile(rootDir, template.path, template.content));
-  }
   const config = loadedConfig.config;
   results.push(...await scaffoldHierarchy(rootDir, config));
-  const migrationDiagnostics = await detectHierarchyMigrationDiagnostics(rootDir, config);
   const block = renderAgentsBlock(config);
   const platformFiles = renderGeneratedSurfaces(config, block);
   for (const file of platformFiles) {
@@ -4728,7 +4892,7 @@ var runInit = async (cwd) => {
   return {
     command: "init",
     summary: changedResults.length > 0 ? "Initialized or updated the Truthmark repository scaffold." : "Truthmark repository scaffold is already up to date.",
-    diagnostics: [...writeDiagnostics(results, config), ...migrationDiagnostics],
+    diagnostics: writeDiagnostics(results, config),
     data: {
       repositoryRoot: repository.repositoryRoot,
       worktreePath: repository.worktreePath,
@@ -4741,7 +4905,7 @@ var runInit = async (cwd) => {
 
 // src/checks/branch-scope.ts
 import fs8 from "fs/promises";
-import fg2 from "fast-glob";
+import fg from "fast-glob";
 
 // src/markdown/hash.ts
 import { createHash } from "crypto";
@@ -4782,10 +4946,11 @@ var getBranchScopeData = async (cwd) => {
   const repository = await getGitRepository(cwd);
   const relevantFileHashes = {};
   const loadResult = await loadConfig(repository.worktreePath);
-  const rootIndex = loadResult.config?.docs.routing.rootIndex ?? DEFAULT_DOCS_HIERARCHY.routing.root_index;
-  const areaFilesRoot = loadResult.config?.docs.routing.areaFilesRoot ?? DEFAULT_DOCS_HIERARCHY.routing.area_files_root;
+  const defaultConfig = createDefaultConfig();
+  const rootIndex = loadResult.config?.truthmark.paths.routesIndex ?? defaultConfig.truthmark.paths.routesIndex;
+  const areaFilesRoot = loadResult.config?.truthmark.paths.routeAreasRoot ?? defaultConfig.truthmark.paths.routeAreasRoot;
   const relevantFiles = /* @__PURE__ */ new Set([...RELEVANT_BRANCH_SCOPE_FILES, rootIndex]);
-  const routeFiles = await fg2([`${areaFilesRoot}/**/*.md`], {
+  const routeFiles = await fg([`${areaFilesRoot}/**/*.md`], {
     cwd: repository.worktreePath,
     onlyFiles: true,
     followSymbolicLinks: false
@@ -4813,7 +4978,7 @@ var getBranchScopeData = async (cwd) => {
 
 // src/checks/authority.ts
 import fs9 from "fs/promises";
-import fg3 from "fast-glob";
+import fg2 from "fast-glob";
 var looksLikeGlob = (pattern) => {
   return /[*?[\]{}()!+@]/u.test(pattern);
 };
@@ -4828,11 +4993,11 @@ var pathExists = async (absolutePath) => {
     throw error;
   }
 };
-var checkAuthority = async (rootDir, config) => {
+var checkControlledPaths = async (rootDir, controlledPaths) => {
   const diagnostics = [];
   const orderedPaths = [];
   const seenPaths = /* @__PURE__ */ new Set();
-  for (const entry of config.authority) {
+  for (const entry of controlledPaths) {
     if (looksLikeGlob(entry)) {
       try {
         resolveRepoPath(rootDir, entry);
@@ -4840,17 +5005,17 @@ var checkAuthority = async (rootDir, config) => {
         diagnostics.push({
           category: "authority",
           severity: "error",
-          message: `Authority entry ${entry} must stay inside the repository root.`,
+          message: `Truthmark-controlled path ${entry} must stay inside the repository root.`,
           file: entry
         });
         continue;
       }
-      const matches = (await fg3([entry], { cwd: rootDir, onlyFiles: true })).sort();
+      const matches = (await fg2([entry], { cwd: rootDir, onlyFiles: true })).sort();
       if (matches.length === 0) {
         diagnostics.push({
           category: "authority",
           severity: "review",
-          message: `Authority glob ${entry} did not match any files.`,
+          message: `Truthmark-controlled glob ${entry} did not match any files.`,
           file: entry
         });
       }
@@ -4862,7 +5027,7 @@ var checkAuthority = async (rootDir, config) => {
           diagnostics.push({
             category: "authority",
             severity: "error",
-            message: `Authority path ${match} must stay inside the repository root.`,
+            message: `Truthmark-controlled path ${match} must stay inside the repository root.`,
             file: match
           });
           continue;
@@ -4882,7 +5047,7 @@ var checkAuthority = async (rootDir, config) => {
       diagnostics.push({
         category: "authority",
         severity: "error",
-        message: `Authority entry ${entry} must stay inside the repository root.`,
+        message: `Truthmark-controlled path ${entry} must stay inside the repository root.`,
         file: entry
       });
       continue;
@@ -4891,7 +5056,7 @@ var checkAuthority = async (rootDir, config) => {
       diagnostics.push({
         category: "authority",
         severity: "error",
-        message: `Missing authority file ${entry}.`,
+        message: `Missing Truthmark-controlled file ${entry}.`,
         file: entry
       });
       continue;
@@ -4906,6 +5071,9 @@ var checkAuthority = async (rootDir, config) => {
     diagnostics
   };
 };
+var checkAuthority = async (rootDir, config) => {
+  return checkControlledPaths(rootDir, config.truthmark.controlledPaths);
+};
 
 // src/checks/frontmatter.ts
 import fs10 from "fs/promises";
@@ -5082,12 +5250,12 @@ var checkLinks = async (rootDir, markdownPaths) => {
 
 // src/checks/areas.ts
 import fs13 from "fs/promises";
-import fg5 from "fast-glob";
+import fg4 from "fast-glob";
 import micromatch4 from "micromatch";
 
 // src/routing/area-resolver.ts
 import fs12 from "fs/promises";
-import fg4 from "fast-glob";
+import fg3 from "fast-glob";
 import micromatch2 from "micromatch";
 var unique = (values) => {
   return [...new Set(values)];
@@ -5252,7 +5420,7 @@ var resolveAreaRouting = async (rootDir, config) => {
       );
     }
   }
-  const routeFilesUnderRoot = await fg4([`${config.areaFilesRoot}/**/*.md`], {
+  const routeFilesUnderRoot = await fg3([`${config.areaFilesRoot}/**/*.md`], {
     cwd: rootDir,
     onlyFiles: true,
     followSymbolicLinks: false
@@ -5414,7 +5582,7 @@ var classifyPath = (filePath, ignorePatterns) => {
   if (normalizedPath.startsWith(".truthmark/")) {
     return "derived";
   }
-  if (normalizedPath.startsWith(".claude/") || normalizedPath.startsWith(".codex/") || normalizedPath.startsWith(".gemini/commands/") || normalizedPath.startsWith(".opencode/") || normalizedPath === ".github/copilot-instructions.md" || normalizedPath.startsWith(".github/agents/truth-") || normalizedPath.startsWith(".github/prompts/truthmark-") || normalizedPath === "AGENTS.md" || normalizedPath === "CLAUDE.md" || normalizedPath === "GEMINI.md" || normalizedPath.startsWith(".gemini/commands/truthmark/")) {
+  if (normalizedPath.startsWith(".agents/skills/truthmark-") || normalizedPath.startsWith(".claude/") || normalizedPath.startsWith(".codex/") || normalizedPath.startsWith(".gemini/agents/truth-") || normalizedPath.startsWith(".gemini/commands/") || normalizedPath.startsWith(".gemini/skills/truthmark-") || normalizedPath.startsWith(".opencode/") || normalizedPath === ".github/copilot-instructions.md" || normalizedPath.startsWith(".github/agents/truth-") || normalizedPath.startsWith(".github/prompts/truthmark-") || normalizedPath.startsWith(".github/skills/truthmark-") || normalizedPath === "AGENTS.md" || normalizedPath === "CLAUDE.md" || normalizedPath === "GEMINI.md" || normalizedPath.startsWith(".gemini/commands/truthmark/")) {
     return "derived";
   }
   if (ignorePatterns.length > 0 && micromatch3.isMatch(normalizedPath, ignorePatterns)) {
@@ -5490,11 +5658,11 @@ var isBroadCodeSurface = (pattern) => {
 };
 var checkAreas = async (rootDir, config) => {
   const routing = await resolveAreaRouting(rootDir, {
-    rootIndex: config.docs.routing.rootIndex,
-    areaFilesRoot: config.docs.routing.areaFilesRoot,
+    rootIndex: config.truthmark.paths.routesIndex,
+    areaFilesRoot: config.truthmark.paths.routeAreasRoot,
     truthDocsRoot: resolveTruthDocsRoot(config)
   });
-  const discoveredCodeFiles = await fg5([...COVERAGE_SCAN_PATTERNS], {
+  const discoveredCodeFiles = await fg4([...COVERAGE_SCAN_PATTERNS], {
     cwd: rootDir,
     onlyFiles: true,
     ignore: config.ignore,
@@ -5547,7 +5715,7 @@ var checkAreas = async (rootDir, config) => {
         const routedGlobEntry = area.truthDocumentEntries.find(
           (entry) => entry.path === truthDocument
         );
-        const matches = (await fg5([truthDocument], { cwd: rootDir, onlyFiles: true })).sort();
+        const matches = (await fg4([truthDocument], { cwd: rootDir, onlyFiles: true })).sort();
         if (matches.length === 0) {
           diagnostics.push({
             category: "area-index",
@@ -5650,7 +5818,7 @@ var checkAreas = async (rootDir, config) => {
           entry.valid = false;
           continue;
         }
-        const matches = await fg5([codeSurfaceEntry], {
+        const matches = await fg4([codeSurfaceEntry], {
           cwd: rootDir,
           onlyFiles: true,
           followSymbolicLinks: false
@@ -5801,11 +5969,7 @@ var kindSpecificHeadingMessages = (source, kind) => {
   return [];
 };
 var decisionTruthGlobs = (config) => {
-  return [
-    config.docs.roots.architecture,
-    resolveTruthDocsRoot(config),
-    config.docs.roots.api
-  ].filter((root) => Boolean(root)).map((root) => `${root}/**/*.md`);
+  return [`${resolveTruthDocsRoot(config)}/**/*.md`];
 };
 var isDecisionTruthCandidate = (config, filePath) => {
   return !filePath.endsWith("/README.md") && micromatch5.isMatch(filePath, decisionTruthGlobs(config));
@@ -5937,7 +6101,7 @@ import path8 from "path";
 import fs16 from "fs/promises";
 import path6 from "path";
 import { execa as execa2 } from "execa";
-import fg6 from "fast-glob";
+import fg5 from "fast-glob";
 import matter2 from "gray-matter";
 import micromatch6 from "micromatch";
 var languageByExtension = /* @__PURE__ */ new Map([
@@ -6019,7 +6183,7 @@ var isIgnoredPath = (filePath, ignore) => {
   return micromatch6.isMatch(filePath, [...defaultIgnore, ...ignore]);
 };
 var discoverRepoFiles = async (rootDir, ignore) => {
-  const discoveredFiles = await gitDiscoverableFiles(rootDir) ?? await fg6(["**/*"], {
+  const discoveredFiles = await gitDiscoverableFiles(rootDir) ?? await fg5(["**/*"], {
     cwd: rootDir,
     onlyFiles: true,
     dot: true,
@@ -6080,7 +6244,7 @@ var discoverRepoFiles = async (rootDir, ignore) => {
 // src/repo-index/package-metadata.ts
 import fs17 from "fs/promises";
 import path7 from "path";
-import fg7 from "fast-glob";
+import fg6 from "fast-glob";
 var packageManagerFor = async (rootDir, packageDir) => {
   const lockfiles = [
     ["package-lock.json", "npm"],
@@ -6100,7 +6264,7 @@ var packageManagerFor = async (rootDir, packageDir) => {
   return "npm";
 };
 var discoverPackageMetadata = async (rootDir) => {
-  const packageFiles = await fg7(["package.json", "*/package.json", "packages/*/package.json"], {
+  const packageFiles = await fg6(["package.json", "*/package.json", "packages/*/package.json"], {
     cwd: rootDir,
     onlyFiles: true,
     ignore: ["node_modules/**", "dist/**", "build/**"],
@@ -6134,8 +6298,8 @@ var buildRouteMap = async (rootDir) => {
     };
   }
   const routing = await resolveAreaRouting(rootDir, {
-    rootIndex: loadResult.config.docs.routing.rootIndex,
-    areaFilesRoot: loadResult.config.docs.routing.areaFilesRoot,
+    rootIndex: loadResult.config.truthmark.paths.routesIndex,
+    areaFilesRoot: loadResult.config.truthmark.paths.routeAreasRoot,
     truthDocsRoot: resolveTruthDocsRoot(loadResult.config)
   });
   return {
@@ -6640,16 +6804,37 @@ var buildImpactSet = async (cwd, options) => {
   };
 };
 
+// src/freshness/check.ts
+var checkFreshness = async (rootDir, _config, _truthDocumentPaths, base) => {
+  const impactSet = await buildImpactSet(rootDir, { base });
+  const diagnostics = [];
+  for (const diagnostic of impactSet.diagnostics) {
+    if (diagnostic.category !== "impact") {
+      continue;
+    }
+    diagnostics.push({
+      ...diagnostic,
+      category: "freshness",
+      message: diagnostic.message.replace("not mapped to a Truthmark route", "not routed to truth ownership")
+    });
+  }
+  return {
+    diagnostics,
+    impactSet
+  };
+};
+
 // src/evidence/validate.ts
 import fs21 from "fs/promises";
-import fg8 from "fast-glob";
+import fg7 from "fast-glob";
 
 // src/evidence/parse.ts
 import fs20 from "fs/promises";
 import path11 from "path";
 import matter3 from "gray-matter";
 import { parse as parse3 } from "yaml";
-var evidenceBlockPattern = /```ya?ml\s*\n([\s\S]*?)```/giu;
+var yamlFencePattern = /```ya?ml\s*\n([\s\S]*?)```/giu;
+var topLevelEvidenceMarkerPattern = /^evidence\s*:/imu;
 var repoRootPrefixes = [".codex/", ".github/", ".truthmark/", "docs/", "src/", "tests/"];
 var normalizeReferencePath = (truthDocPath, referencePath) => {
   const strippedPath = referencePath.split("#")[0]?.trim() ?? "";
@@ -6688,8 +6873,12 @@ var parseEvidenceReferences = async (rootDir, truthDocPath) => {
       source: "frontmatter"
     });
   }
-  for (const match of parsed.content.matchAll(evidenceBlockPattern)) {
-    const block = parse3(match[1] ?? "");
+  for (const match of parsed.content.matchAll(yamlFencePattern)) {
+    const yamlBlock = match[1] ?? "";
+    if (!topLevelEvidenceMarkerPattern.test(yamlBlock)) {
+      continue;
+    }
+    const block = parse3(yamlBlock);
     const rawEvidence = block && typeof block === "object" && "evidence" in block ? block.evidence : null;
     if (!Array.isArray(rawEvidence)) {
       continue;
@@ -6714,7 +6903,7 @@ var pathExists5 = async (filePath) => {
   }
 };
 var diagnosticFor = (reference, message) => ({
-  category: "freshness",
+  category: "source-traceability",
   severity: "error",
   message,
   file: reference.truthDocPath,
@@ -6723,12 +6912,21 @@ var diagnosticFor = (reference, message) => ({
     source: reference.source
   }
 });
+var parseDiagnosticFor = (truthDocPath, error) => ({
+  category: "source-traceability",
+  severity: "error",
+  message: `Malformed evidence YAML block in ${truthDocPath}: ${error instanceof Error ? error.message : String(error)}`,
+  file: truthDocPath,
+  data: {
+    source: "evidence-block"
+  }
+});
 var isGlobReference = (referencePath) => /[*?[\]{}()]/u.test(referencePath);
 var validateGlob = async (rootDir, reference) => {
   if (reference.path.startsWith("../") || reference.path.startsWith("/")) {
     return diagnosticFor(reference, `Referenced file pattern ${reference.path} must stay inside the repository root.`);
   }
-  const matches = await fg8(reference.path, {
+  const matches = await fg7(reference.path, {
     cwd: rootDir,
     dot: true,
     onlyFiles: true,
@@ -6806,7 +7004,13 @@ var validateReference = async (rootDir, reference) => {
 var validateEvidenceReferences = async (rootDir, truthDocPaths) => {
   const diagnostics = [];
   for (const truthDocPath of [...truthDocPaths].sort()) {
-    const references = await parseEvidenceReferences(rootDir, truthDocPath);
+    let references;
+    try {
+      references = await parseEvidenceReferences(rootDir, truthDocPath);
+    } catch (error) {
+      diagnostics.push(parseDiagnosticFor(truthDocPath, error));
+      continue;
+    }
     for (const reference of references) {
       diagnostics.push(...await validateReference(rootDir, reference));
     }
@@ -6814,25 +7018,135 @@ var validateEvidenceReferences = async (rootDir, truthDocPaths) => {
   return diagnostics;
 };
 
-// src/freshness/check.ts
-var checkFreshness = async (rootDir, _config, truthDocumentPaths, base) => {
-  const impactSet = await buildImpactSet(rootDir, { base });
-  const diagnostics = [...await validateEvidenceReferences(rootDir, truthDocumentPaths)];
-  for (const diagnostic of impactSet.diagnostics) {
-    if (diagnostic.category !== "impact") {
-      continue;
+// src/checks/scorecard.ts
+var TRUTH_HEALTH_SCORECARD_SCHEMA_VERSION = "truthmark-scorecard/v0";
+var TRUTH_HEALTH_DIMENSION_IDS = [
+  "routing-coverage",
+  "ownership-clarity",
+  "source-traceability",
+  "branch-freshness",
+  "generated-surface-freshness",
+  "truth-doc-structure",
+  "decision-rationale-preservation"
+];
+var EVIDENCE_LIMIT = 2;
+var textIncludesAny = (text, needles) => {
+  const normalized = text.toLowerCase();
+  return needles.some((needle) => normalized.includes(needle));
+};
+var diagnosticText = (diagnostic) => {
+  const dataText = diagnostic.data ? JSON.stringify(diagnostic.data) : "";
+  return `${diagnostic.message} ${diagnostic.file ?? ""} ${diagnostic.area ?? ""} ${dataText}`;
+};
+var isRouteAmbiguityDiagnostic = (diagnostic) => diagnostic.category === "context-pack" && textIncludesAny(diagnosticText(diagnostic), [
+  "route",
+  "routing",
+  "ownership",
+  "write boundary",
+  "allowed write"
+]);
+var isSourceTraceabilityDiagnostic = (diagnostic) => diagnostic.category === "source-traceability" || diagnostic.category === "links" && textIncludesAny(diagnosticText(diagnostic), [
+  "source_of_truth",
+  "source of truth",
+  "source evidence",
+  "evidence"
+]);
+var isMarkdownShapeDiagnostic = (diagnostic) => diagnostic.category === "authority" && textIncludesAny(diagnosticText(diagnostic), ["markdown", "heading", "section"]);
+var isOwnershipFreshnessDiagnostic = (diagnostic) => diagnostic.category === "freshness" && textIncludesAny(diagnosticText(diagnostic), [
+  "route",
+  "routing",
+  "ownership",
+  "truth owner",
+  "truth ownership",
+  "affected truth document"
+]);
+var isDecisionRationaleDiagnostic = (diagnostic) => diagnostic.category === "doc-structure" && textIncludesAny(diagnosticText(diagnostic), ["product decisions", "rationale"]);
+var mapsToDimension = (diagnostic, dimensionId) => {
+  switch (dimensionId) {
+    case "routing-coverage":
+      return ["config", "authority", "area-index", "coverage", "repo-index"].includes(
+        diagnostic.category
+      );
+    case "ownership-clarity":
+      return ["config", "area-index", "coverage", "impact"].includes(diagnostic.category) || isRouteAmbiguityDiagnostic(diagnostic) || isOwnershipFreshnessDiagnostic(diagnostic);
+    case "source-traceability":
+      return isSourceTraceabilityDiagnostic(diagnostic);
+    case "branch-freshness":
+      return diagnostic.category === "freshness";
+    case "generated-surface-freshness":
+      return diagnostic.category === "config" || diagnostic.category === "generated-surface";
+    case "truth-doc-structure":
+      return diagnostic.category === "config" || diagnostic.category === "frontmatter" || diagnostic.category === "links" || diagnostic.category === "doc-structure" || isMarkdownShapeDiagnostic(diagnostic);
+    case "decision-rationale-preservation":
+      return isDecisionRationaleDiagnostic(diagnostic);
+  }
+};
+var checkerRanForDimension = (dimensionId, context) => {
+  switch (dimensionId) {
+    case "routing-coverage":
+      return context.routingChecksRan ?? true;
+    case "ownership-clarity":
+      return context.ownershipChecksRan ?? true;
+    case "source-traceability":
+      return context.evidenceChecksRan ?? true;
+    case "branch-freshness":
+      return context.branchFreshnessRan;
+    case "generated-surface-freshness":
+      return context.generatedSurfaceChecksRan ?? true;
+    case "truth-doc-structure":
+      return context.truthDocStructureChecksRan ?? true;
+    case "decision-rationale-preservation":
+      return context.decisionRationaleChecksRan ?? true;
+  }
+};
+var statusForDiagnostics = (diagnostics, diagnosticIndexes, checkerRan) => {
+  if (diagnosticIndexes.length > 0) {
+    return diagnosticIndexes.some((index) => diagnostics[index]?.severity === "error") ? "fail" : "warn";
+  }
+  return checkerRan ? "pass" : "not-run";
+};
+var evidenceForDiagnostics = (diagnostics, diagnosticIndexes, status, dimensionId, context) => {
+  if (status === "pass") {
+    return void 0;
+  }
+  if (diagnosticIndexes.length === 0) {
+    if (dimensionId === "branch-freshness") {
+      return [context.branchFreshnessNotRunReason ?? "base not supplied"];
     }
-    diagnostics.push({
-      ...diagnostic,
-      category: "freshness",
-      message: diagnostic.message.replace("not mapped to a Truthmark route", "not routed to truth ownership")
-    });
+    return ["checker not run"];
   }
-  return {
-    diagnostics,
-    impactSet
-  };
+  return diagnosticIndexes.slice(0, EVIDENCE_LIMIT).map((index) => {
+    const diagnostic = diagnostics[index];
+    const subject = diagnostic.file ?? diagnostic.area;
+    return subject ? `${diagnostic.category}:${subject}` : diagnostic.category;
+  });
 };
+var buildTruthHealthScorecard = (diagnostics, context) => ({
+  schemaVersion: TRUTH_HEALTH_SCORECARD_SCHEMA_VERSION,
+  dimensions: TRUTH_HEALTH_DIMENSION_IDS.map((dimensionId) => {
+    const diagnosticIndexes = diagnostics.flatMap(
+      (diagnostic, index) => mapsToDimension(diagnostic, dimensionId) ? [index] : []
+    );
+    const status = statusForDiagnostics(
+      diagnostics,
+      diagnosticIndexes,
+      checkerRanForDimension(dimensionId, context)
+    );
+    const evidence = evidenceForDiagnostics(
+      diagnostics,
+      diagnosticIndexes,
+      status,
+      dimensionId,
+      context
+    );
+    return {
+      id: dimensionId,
+      status,
+      diagnosticIndexes,
+      ...evidence ? { evidence } : {}
+    };
+  })
+});
 
 // src/checks/check.ts
 var summarizeDiagnostics = (diagnostics) => {
@@ -6849,12 +7163,23 @@ var runCheck = async (cwd, options = {}) => {
   const branchScope = await getBranchScopeData(rootDir);
   const loadResult = await loadConfig(rootDir);
   if (!loadResult.config) {
+    const scorecard2 = buildTruthHealthScorecard(loadResult.diagnostics, {
+      branchFreshnessRan: false,
+      branchFreshnessNotRunReason: options.base ? "config unavailable" : "base not supplied",
+      routingChecksRan: false,
+      ownershipChecksRan: false,
+      evidenceChecksRan: false,
+      generatedSurfaceChecksRan: false,
+      truthDocStructureChecksRan: false,
+      decisionRationaleChecksRan: false
+    });
     return {
       command: "check",
       summary: summarizeDiagnostics(loadResult.diagnostics),
       diagnostics: loadResult.diagnostics,
       data: {
-        branchScope
+        branchScope,
+        scorecard: scorecard2
       }
     };
   }
@@ -6875,6 +7200,7 @@ var runCheck = async (cwd, options = {}) => {
     areas.truthDocumentEntries
   );
   const generatedSurfaces = await checkGeneratedSurfaces(rootDir, loadResult.config);
+  const sourceTraceability = await validateEvidenceReferences(rootDir, areas.truthDocumentPaths);
   const freshness = options.base ? await checkFreshness(rootDir, loadResult.config, areas.truthDocumentPaths, options.base) : null;
   const diagnostics = [
     ...loadResult.diagnostics,
@@ -6884,6 +7210,7 @@ var runCheck = async (cwd, options = {}) => {
     ...areas.diagnostics,
     ...decisionSections,
     ...generatedSurfaces,
+    ...sourceTraceability,
     ...freshness?.diagnostics ?? []
   ];
   const truthVisibility = {
@@ -6898,6 +7225,11 @@ var runCheck = async (cwd, options = {}) => {
     topologyPressureCount: areas.topologyPressureCount,
     freshnessDiagnosticCount: freshness?.diagnostics.length ?? 0
   };
+  const scorecard = buildTruthHealthScorecard(diagnostics, {
+    branchFreshnessRan: Boolean(freshness),
+    branchFreshnessNotRunReason: options.base ? "freshness checker skipped" : "base not supplied",
+    evidenceChecksRan: true
+  });
   return {
     command: "check",
     summary: summarizeDiagnostics(diagnostics),
@@ -6905,6 +7237,7 @@ var runCheck = async (cwd, options = {}) => {
     data: {
       branchScope,
       truthVisibility,
+      scorecard,
       ...freshness ? { impactSet: freshness.impactSet } : {}
     }
   };
@@ -6913,7 +7246,7 @@ var runCheck = async (cwd, options = {}) => {
 // src/context-pack/build.ts
 import fs22 from "fs/promises";
 import path12 from "path";
-import fg9 from "fast-glob";
+import fg8 from "fast-glob";
 var uniqueSorted2 = (values) => [...new Set(values)].sort();
 var repoRootPrefixes2 = [".codex/", ".github/", ".truthmark/", "docs/", "src/", "tests/"];
 var isGlobReference2 = (referencePath) => /[*?[\]{}()]/u.test(referencePath);
@@ -6933,9 +7266,19 @@ var readIfExists = async (rootDir, filePath) => {
     return null;
   }
 };
-var boundedContent = (filePath, content, warnings) => {
+var boundContent = (content) => {
   const lines = content.split("\n");
   if (lines.length <= 200) {
+    return { content, truncated: false };
+  }
+  return {
+    content: [...lines.slice(0, 80), "...", ...lines.slice(-40)].join("\n"),
+    truncated: true
+  };
+};
+var boundedContent = (filePath, content, warnings) => {
+  const bounded = boundContent(content);
+  if (!bounded.truncated) {
     return { path: filePath, content, truncated: false };
   }
   warnings.push({
@@ -6946,16 +7289,25 @@ var boundedContent = (filePath, content, warnings) => {
   });
   return {
     path: filePath,
-    content: [...lines.slice(0, 80), "...", ...lines.slice(-40)].join("\n"),
+    content: bounded.content,
     truncated: true
   };
 };
-var documentsFor = async (rootDir, paths) => {
+var documentsFor = async (rootDir, paths, warnings) => {
   const documents = [];
   for (const filePath of uniqueSorted2(paths)) {
     const content = await readIfExists(rootDir, filePath);
     if (content !== null) {
-      documents.push({ path: filePath, content });
+      const bounded = boundContent(content);
+      if (bounded.truncated) {
+        warnings.push({
+          category: "context-pack",
+          severity: "review",
+          message: `Context truth doc ${filePath} was truncated to fit ContextPack v0 bounds.`,
+          file: filePath
+        });
+      }
+      documents.push({ path: filePath, content: bounded.content, truncated: bounded.truncated });
     }
   }
   return documents;
@@ -6984,7 +7336,7 @@ var sourceOfTruthPathsFor = async (rootDir, docs, truthDocPaths) => {
       }
       if (isGlobReference2(normalizedPath)) {
         sourcePaths.push(
-          ...await fg9(normalizedPath, {
+          ...await fg8(normalizedPath, {
             cwd: rootDir,
             dot: true,
             onlyFiles: true,
@@ -6998,12 +7350,12 @@ var sourceOfTruthPathsFor = async (rootDir, docs, truthDocPaths) => {
   }
   return uniqueSorted2(sourcePaths);
 };
-var writePathsFor = (workflow, truthDocs, routes) => {
+var writePathsFor = (workflow, routeIndexPath, truthDocs, routes) => {
   if (workflow === "truth-sync") {
-    return uniqueSorted2(["docs/truthmark/areas.md", ...truthDocs]);
+    return uniqueSorted2([routeIndexPath, ...truthDocs]);
   }
   if (workflow === "truth-document") {
-    return uniqueSorted2(["docs/truthmark/areas.md", ...truthDocs]);
+    return uniqueSorted2([routeIndexPath, ...truthDocs]);
   }
   return uniqueSorted2(routes.flatMap((route) => route.codeSurface));
 };
@@ -7013,9 +7365,11 @@ var testCommandsFor = (affectedTests) => {
 var buildContextPack = async (cwd, options) => {
   const repoIndex = await buildRepoIndex(cwd);
   const rootDir = repoIndex.repository.root;
+  const loadResult = await loadConfig(rootDir);
+  const config = loadResult.config ?? (loadResult.status === "missing" ? createDefaultConfig() : null);
   const impactSet = options.base ? await buildImpactSet(rootDir, { base: options.base }) : null;
   const routeMap = impactSet ? repoIndex.routeMap : repoIndex.routeMap;
-  const warnings = [];
+  const warnings = loadResult.status === "invalid" ? [...loadResult.diagnostics] : [];
   const truthDocPaths = impactSet?.affectedTruthDocs ?? (options.workflow === "truth-realize" ? [] : routeMap.routes.flatMap((route) => route.truthDocs));
   const contextRoutes = impactSet?.affectedRoutes ?? (options.workflow === "truth-realize" ? [] : routeMap.routes);
   if (options.workflow === "truth-realize" && !impactSet) {
@@ -7036,8 +7390,13 @@ var buildContextPack = async (cwd, options) => {
     base: options.base ?? null,
     impactSet,
     routeMap,
-    allowedWritePaths: writePathsFor(options.workflow, truthDocPaths, contextRoutes),
-    truthDocs: await documentsFor(rootDir, truthDocPaths),
+    allowedWritePaths: config === null ? [] : writePathsFor(
+      options.workflow,
+      config.truthmark.paths.routesIndex,
+      truthDocPaths,
+      contextRoutes
+    ),
+    truthDocs: await documentsFor(rootDir, truthDocPaths, warnings),
     sourceFiles: await sourceFilesFor(rootDir, sourceFilePaths, warnings),
     testCommands: testCommandsFor(impactSet?.affectedTests ?? []),
     warnings
@@ -7056,7 +7415,7 @@ var renderContextPackMarkdown = (pack) => {
     ...pack.allowedWritePaths.map((filePath) => `- ${filePath}`),
     "",
     "## Truth Docs",
-    ...pack.truthDocs.map((doc) => `- ${doc.path}`),
+    ...pack.truthDocs.map((doc) => `- ${doc.path}${doc.truncated ? " (truncated)" : ""}`),
     "",
     "## Source Files",
     ...pack.sourceFiles.map((file) => `- ${file.path}${file.truncated ? " (truncated)" : ""}`),
@@ -7068,6 +7427,198 @@ var renderContextPackMarkdown = (pack) => {
 `;
 };
 
+// src/workflow-state/build.ts
+import { execa as execa5 } from "execa";
+
+// src/workflow-state/action-context.ts
+var uniqueSorted3 = (values) => [...new Set(values.filter((value) => value.length > 0))].sort();
+var helperCommandsFor = (manifestEntry) => (manifestEntry.helpers ?? []).map((helper) => ({
+  id: helper.id,
+  runner: helper.runner,
+  argv: [...helper.command.argv],
+  optional: helper.optional
+}));
+var evidenceFor = (manifestEntry) => manifestEntry.requiredGates.filter((gate) => /evidence|ownership|containment/iu.test(gate));
+var baseContext = (manifestEntry, mode, allowedWritePaths, forbiddenWritePaths, writeLeaseRequired) => ({
+  mode,
+  allowedWritePaths: uniqueSorted3(allowedWritePaths),
+  forbiddenWritePaths: uniqueSorted3(forbiddenWritePaths),
+  stopConditions: [...manifestEntry.negativeTriggers, ...manifestEntry.forbiddenAdjacency],
+  requiredEvidence: evidenceFor(manifestEntry),
+  helperValidationCommands: helperCommandsFor(manifestEntry),
+  writeLeaseRequired
+});
+var buildWorkflowActionContext = (manifestEntry, data = {}) => {
+  if (manifestEntry.id === "truthmark-preview" || manifestEntry.id === "truthmark-check") {
+    return baseContext(manifestEntry, "read-only", [], [], false);
+  }
+  if (manifestEntry.id === "truthmark-sync" || manifestEntry.id === "truthmark-document") {
+    return baseContext(
+      manifestEntry,
+      "truth-doc-write",
+      [...data.routeIndexPath ? [data.routeIndexPath] : [], ...data.routeFiles ?? [], ...data.truthDocs ?? []],
+      [],
+      true
+    );
+  }
+  if (manifestEntry.id === "truthmark-structure") {
+    return baseContext(
+      manifestEntry,
+      "route-write",
+      [
+        ...data.routeIndexPath ? [data.routeIndexPath] : [],
+        ...data.routeFiles ?? [],
+        ...data.starterTruthDocs ?? []
+      ],
+      [],
+      true
+    );
+  }
+  if (manifestEntry.id === "truthmark-realize") {
+    return baseContext(
+      manifestEntry,
+      "code-write",
+      data.codeWritePaths ?? [],
+      [
+        ...data.routeIndexPath ? [data.routeIndexPath] : [],
+        ...data.routeFiles ?? [],
+        ...data.truthRoot ? [`${data.truthRoot}/**/*.md`] : [],
+        ...data.truthDocs ?? []
+      ],
+      false
+    );
+  }
+  return baseContext(
+    manifestEntry,
+    "portal-write",
+    data.portalEnabled && data.portalOutputPath ? [`${data.portalOutputPath}/**`] : [],
+    [],
+    false
+  );
+};
+
+// src/workflow-state/build.ts
+var helperCommandsFor2 = (workflow) => (TRUTHMARK_WORKFLOW_MANIFEST[workflow].helpers ?? []).map((helper) => ({
+  id: helper.id,
+  runner: helper.runner,
+  argv: [...helper.command.argv],
+  optional: helper.optional
+}));
+var uniqueSorted4 = (values) => [...new Set(values.filter((value) => value.length > 0))].sort();
+var isWriteCapable = (workflow) => !["truthmark-preview", "truthmark-check"].includes(workflow);
+var DEFAULT_BASE_CANDIDATES = ["@{upstream}", "origin/main", "main", "origin/master", "master"];
+var selectComparisonBase = async (rootDir, suppliedBase) => {
+  if (suppliedBase) {
+    return suppliedBase;
+  }
+  for (const candidate of DEFAULT_BASE_CANDIDATES) {
+    const result = await execa5("git", ["rev-parse", "--verify", `${candidate}^{commit}`], {
+      cwd: rootDir,
+      reject: false
+    });
+    if ((result.exitCode ?? 1) === 0) {
+      return candidate;
+    }
+  }
+  return null;
+};
+var routeFilesFor = (repoIndex) => uniqueSorted4(repoIndex.routeMap.routes.map((route) => route.sourcePath));
+var hasUnmappedFunctionalChange = (impactSet) => impactSet?.diagnostics.some(
+  (diagnostic) => diagnostic.category === "impact" && /not mapped to a Truthmark route|no affected truth document/u.test(diagnostic.message)
+) ?? false;
+var applicabilityFor = (workflow, diagnostics, impactSet) => {
+  const reasons = [];
+  if (diagnostics.some((diagnostic) => diagnostic.message.includes("Missing .truthmark/config.yml"))) {
+    reasons.push("Missing .truthmark/config.yml.");
+    return { state: isWriteCapable(workflow) ? "blocked" : "not_applicable", reasons };
+  }
+  if (workflow === "truthmark-sync" && !impactSet) {
+    reasons.push("truthmark-sync requires --base to derive bounded truth-doc write paths.");
+    return { state: "blocked", reasons };
+  }
+  if (workflow === "truthmark-realize" && !impactSet) {
+    reasons.push("truthmark-realize requires --base to derive bounded allowed write paths.");
+    return { state: "blocked", reasons };
+  }
+  if (hasUnmappedFunctionalChange(impactSet)) {
+    reasons.push("Changed functional files have ambiguous or missing Truthmark route ownership.");
+    return { state: "ambiguous", reasons };
+  }
+  if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+    reasons.push("Existing diagnostics contain errors that block safe workflow execution.");
+    return { state: "blocked", reasons };
+  }
+  return { state: "applicable", reasons };
+};
+var contextDataFor = (workflow, repoIndex, config, impactSet) => {
+  if (!config) {
+    return {};
+  }
+  const routeFiles = routeFilesFor(repoIndex);
+  const truthDocs = uniqueSorted4(
+    impactSet?.affectedTruthDocs ?? repoIndex.routeMap.routes.flatMap((route) => route.truthDocs)
+  );
+  return {
+    routeIndexPath: config.truthmark.paths.routesIndex,
+    routeFiles,
+    truthRoot: config.truthmark.paths.truthRoot,
+    truthDocs,
+    starterTruthDocs: workflow === "truthmark-structure" ? truthDocs : [],
+    codeWritePaths: workflow === "truthmark-realize" ? uniqueSorted4(impactSet?.affectedRoutes.flatMap((route) => route.codeSurface) ?? []) : [],
+    portalEnabled: config.truthmark.generated.portal.enabled,
+    portalOutputPath: config.truthmark.paths.portalOutput,
+    routes: repoIndex.routeMap.routes
+  };
+};
+var nextStepsFor = (workflow, applicability, comparisonBase) => {
+  if (applicability.state === "ambiguous") {
+    return ["Run Truth Structure or repair route ownership before writing truth docs."];
+  }
+  if ((workflow === "truthmark-sync" || workflow === "truthmark-realize") && applicability.state === "blocked" && !comparisonBase) {
+    return [
+      workflow === "truthmark-sync" ? "Rerun with --base <ref> so Truthmark can derive bounded truth-doc write paths." : "Rerun with --base <ref> so Truthmark can derive bounded allowed code-write paths."
+    ];
+  }
+  return [];
+};
+var buildWorkflowState = async (cwd, options) => {
+  const manifestEntry = TRUTHMARK_WORKFLOW_MANIFEST[options.workflow];
+  if (!manifestEntry) {
+    throw new Error(`Unknown Truthmark workflow: ${String(options.workflow)}`);
+  }
+  const repoIndex = await buildRepoIndex(cwd);
+  const rootDir = repoIndex.repository.root;
+  const loadResult = await loadConfig(rootDir);
+  const comparisonBase = options.base ? options.base : options.workflow === "truthmark-sync" ? await selectComparisonBase(rootDir) : null;
+  const impactSet = comparisonBase ? await buildImpactSet(rootDir, { base: comparisonBase }) : null;
+  const checkResult = await runCheck(cwd, comparisonBase ? { base: comparisonBase } : {});
+  const diagnostics = [
+    ...loadResult.diagnostics,
+    ...repoIndex.diagnostics,
+    ...impactSet?.diagnostics ?? [],
+    ...checkResult.diagnostics
+  ];
+  const applicability = applicabilityFor(options.workflow, diagnostics, impactSet);
+  const actionData = applicability.state === "blocked" || applicability.state === "ambiguous" ? {} : contextDataFor(options.workflow, repoIndex, loadResult.config, impactSet);
+  return {
+    schemaVersion: "truthmark-workflow/v0",
+    workflow: options.workflow,
+    applicability,
+    actionContext: buildWorkflowActionContext(manifestEntry, actionData),
+    changedFiles: impactSet?.changedFiles ?? [],
+    affectedRoutes: impactSet?.affectedRoutes ?? [],
+    targetTruthDocs: applicability.state === "ambiguous" ? [] : impactSet?.affectedTruthDocs ?? [],
+    diagnostics,
+    checks: {
+      required: [...manifestEntry.requiredGates],
+      recommended: [...manifestEntry.positiveTriggers],
+      helpers: helperCommandsFor2(options.workflow)
+    },
+    nextSteps: nextStepsFor(options.workflow, applicability, comparisonBase),
+    reportSections: [...manifestEntry.reportSections]
+  };
+};
+
 // src/cli/handlers.ts
 import fs23 from "fs/promises";
 
@@ -7434,9 +7985,26 @@ var runImpact = async (options) => {
 var isContextPackWorkflow = (value) => {
   return value === "truth-sync" || value === "truth-document" || value === "truth-realize";
 };
-var isContextPackFormat = (value) => {
-  return value === void 0 || value === "json" || value === "markdown";
+var isContextMarkdownFormat = (value) => {
+  return value === void 0 || value === "markdown";
 };
+var isTruthmarkWorkflowId = (value) => {
+  return typeof value === "string" && TRUTHMARK_WORKFLOW_IDS.includes(value);
+};
+var invalidWorkflowResult = (command, workflow) => ({
+  command,
+  summary: workflow ? `Truthmark workflow requires a supported full workflow ID; received ${workflow}.` : "Truthmark workflow requires --workflow.",
+  diagnostics: [
+    {
+      category: "workflow-state",
+      severity: "error",
+      message: workflow ? `Unknown Truthmark workflow: ${workflow}. Use a canonical full manifest ID such as truthmark-sync or truthmark-check.` : `truthmark ${command} requires --workflow <workflow>.`
+    }
+  ],
+  data: {
+    request: workflow ? { workflow } : {}
+  }
+});
 var readHelperFile = async (filePath, helper) => {
   try {
     return await fs23.readFile(filePath, "utf8");
@@ -7478,7 +8046,20 @@ var runContext = async (options) => {
       ]
     };
   }
-  if (!isContextPackFormat(options.format)) {
+  if (options.format === "json") {
+    return {
+      command: "context",
+      summary: "Truthmark context no longer supports JSON ContextPack output.",
+      diagnostics: [
+        {
+          category: "context-pack",
+          severity: "error",
+          message: "JSON ContextPack output was removed in v2; use --format markdown."
+        }
+      ]
+    };
+  }
+  if (!isContextMarkdownFormat(options.format)) {
     return {
       command: "context",
       summary: "Truthmark context requires a supported --format value.",
@@ -7486,7 +8067,7 @@ var runContext = async (options) => {
         {
           category: "context-pack",
           severity: "error",
-          message: "truthmark context requires --format json or markdown."
+          message: "truthmark context supports only --format markdown; JSON ContextPack output was removed in v2."
         }
       ]
     };
@@ -7496,26 +8077,56 @@ var runContext = async (options) => {
     base: options.base
   });
   const diagnostics = contextPack.warnings;
+  const summary = `Truthmark context generated ${contextPack.workflow} ContextPack with ${diagnostics.length} warnings.`;
+  const markdown = renderContextPackMarkdown(contextPack);
   return {
     command: "context",
-    summary: `Truthmark context generated ${contextPack.workflow} ContextPack with ${diagnostics.length} warnings.`,
+    summary,
     diagnostics,
     data: {
-      contextPack,
-      ...options.format === "markdown" ? { markdown: renderContextPackMarkdown(contextPack) } : {}
+      markdown,
+      summary
+    }
+  };
+};
+var runWorkflowStatus = async (options) => {
+  if (!isTruthmarkWorkflowId(options.workflow)) {
+    return invalidWorkflowResult("workflow status", options.workflow);
+  }
+  const workflowState = await buildWorkflowState(process.cwd(), {
+    workflow: options.workflow,
+    ...options.base ? { base: options.base } : {}
+  });
+  return {
+    command: "workflow status",
+    summary: `Truthmark workflow status completed for ${options.workflow}.`,
+    diagnostics: workflowState.diagnostics,
+    data: {
+      request: {
+        workflow: options.workflow,
+        ...options.base ? { base: options.base } : {}
+      },
+      workflowState
     }
   };
 };
 
 // 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") {
+  if (!options.json && typeof result.data?.markdown === "string") {
     process.stdout.write(result.data.markdown);
+    markFailedWhenErrorDiagnosticsExist(result);
     return;
   }
   writeResult(result, options);
@@ -7574,7 +8185,7 @@ var buildProgram = () => {
     writeResult(await runImpact({ base: options.base }), options);
   });
   addJsonOption(
-    program.command("context").description("Generate a bounded workflow context pack.").requiredOption("--workflow <workflow>", "Workflow name: truth-sync, truth-document, or truth-realize").option("--base <ref>", "Base Git ref for impact-backed packs").option("--format <format>", "Output format: json or markdown", "json")
+    program.command("context").description("Generate a bounded workflow context pack.").requiredOption("--workflow <workflow>", "Workflow name: truth-sync, truth-document, or truth-realize").option("--base <ref>", "Base Git ref for impact-backed packs").option("--format <format>", "Output format: markdown", "markdown")
   ).action(async (options) => {
     writeContextResult(
       await runContext({
@@ -7585,6 +8196,18 @@ var buildProgram = () => {
       options
     );
   });
+  const workflow = program.command("workflow").description("Inspect agent-facing Truthmark workflow state.");
+  addJsonOption(
+    workflow.command("status").description("Return schema-versioned workflow state for a canonical workflow ID.").option("--workflow <workflow>", "Canonical workflow ID, such as truthmark-sync").option("--base <ref>", "Base Git ref for impact-backed workflow state")
+  ).action(async (options) => {
+    writeResult(
+      await runWorkflowStatus({
+        workflow: options.workflow,
+        base: options.base
+      }),
+      options
+    );
+  });
   const validate = program.command("validate").description("Run optional Truthmark workflow helper validators from the installed CLI.");
   addJsonOption(
     validate.command("sync-report").description("Validate a Truth Sync report file.").argument("<report-file>", "Truth Sync report file")