truthmark 1.2.0 → 1.2.2

package/dist/main.js

@@ -43,7 +43,7 @@ var renderJson = (result) => {
 };
 
 // src/config/command.ts
-import fs3 from "fs/promises";
+import fs4 from "fs/promises";
 
 // src/fs/paths.ts
 import path from "path";
@@ -234,11 +234,16 @@ var SUPPORTED_PLATFORMS = [
   "codex",
   "opencode",
   "claude-code",
-  "cursor",
   "github-copilot",
   "gemini-cli"
 ];
-var DEFAULT_PLATFORMS = ["codex", "opencode", "claude-code"];
+var DEFAULT_PLATFORMS = [
+  "codex",
+  "opencode",
+  "claude-code",
+  "github-copilot",
+  "gemini-cli"
+];
 var truthmarkConfigSchema = {
   type: "object",
   additionalProperties: false,
@@ -423,32 +428,34 @@ var createDefaultConfig = () => ({
 });
 
 // src/version.ts
-var TRUTHMARK_VERSION = "1.2.0";
+import fs3 from "fs";
+var packageJson = JSON.parse(
+  fs3.readFileSync(new URL("../package.json", import.meta.url), "utf8")
+);
+var TRUTHMARK_VERSION = packageJson.version;
 
 // src/templates/init-files.ts
 var renderConfigTemplate = () => {
   return stringify(createDefaultRawConfig());
 };
 var renderTruthmarkTemplate = () => {
-  return `# Truthmark
+  return `---
+status: active
+doc_type: workflow-contract
+last_reviewed: 2026-05-10
+source_of_truth:
+  - .truthmark/config.yml
+---
+
+# Truthmark
 
 Markdown in the current checkout is authoritative for this branch.
 
 Installed workflow surfaces include a Truthmark ${TRUTHMARK_VERSION} version marker. After upgrading Truthmark, rerun \`truthmark init\` and review generated workflow diffs.
 
-Truth Sync runs automatically before finishing when functional code changes exist, and updates truth docs.
-
-Truth Sync can also be invoked explicitly through installed truthmark-sync skill surfaces.
-
-Truth Structure designs or repairs docs/truthmark/areas.md through installed truthmark-structure skill surfaces.
-
-Truth Realize is manual and updates code to match truth docs.
-
-Truth Check audits repository truth health through installed truthmark-check skill surfaces.
-
-Truth Sync may create or extend mapped truth docs when implementation would otherwise remain undocumented.
+Workflow runtime lives in installed skills and managed instruction blocks. Agents inspect the checkout directly; \`truthmark check\` is optional validation.
 
-Truth Realize never edits truth docs.
+Truth Sync follows code; Truth Realize follows docs. Truth Sync may update mapped truth docs; Truth Realize never edits truth docs or routing.
 `;
 };
 var titleCase = (value) => {
@@ -459,6 +466,14 @@ var renderHierarchicalAreasIndexTemplate = (config) => {
   const childPath = `${config.docs.routing.areaFilesRoot}/${defaultArea}.md`;
   const title = titleCase(defaultArea);
   return [
+    "---",
+    "status: active",
+    "doc_type: route-index",
+    "last_reviewed: 2026-05-09",
+    "source_of_truth:",
+    "  - ../../.truthmark/config.yml",
+    "---",
+    "",
     "# Truthmark Areas",
     "",
     `## ${title}`,
@@ -481,6 +496,14 @@ var renderChildAreaTemplate = (config) => {
   const featureRoot = config.docs.roots.features ?? config.docs.roots.features_current ?? "docs/features";
   const leafTruthDoc = `${featureRoot}/${defaultArea}/overview.md`;
   return [
+    "---",
+    "status: active",
+    "doc_type: area-route",
+    "last_reviewed: 2026-05-09",
+    "source_of_truth:",
+    "  - ../../../.truthmark/config.yml",
+    "---",
+    "",
     `# ${title} Areas`,
     "",
     `## ${title}`,
@@ -575,7 +598,7 @@ var renderFeatureLeafDocTemplate = (config) => {
 var CONFIG_PATH = ".truthmark/config.yml";
 var configExists = async (rootDir) => {
   try {
-    await fs3.stat(resolveRepoPath(rootDir, CONFIG_PATH));
+    await fs4.stat(resolveRepoPath(rootDir, CONFIG_PATH));
     return true;
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT") {
@@ -648,10 +671,10 @@ var runConfig = async (cwd, options = {}) => {
 };
 
 // src/init/init.ts
-import fs5 from "fs/promises";
+import fs6 from "fs/promises";
 
 // src/config/load.ts
-import fs4 from "fs/promises";
+import fs5 from "fs/promises";
 import { Ajv } from "ajv";
 import { parse } from "yaml";
 var ajv = new Ajv({ allErrors: true });
@@ -700,7 +723,7 @@ var loadConfig = async (rootDir) => {
   const absolutePath = resolveRepoPath(rootDir, configPath);
   let source;
   try {
-    source = await fs4.readFile(absolutePath, "utf8");
+    source = await fs5.readFile(absolutePath, "utf8");
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT") {
       return {
@@ -845,11 +868,153 @@ var renderHierarchySummary = (config) => {
   ].join("\n");
 };
 
-// src/agents/truth-check.ts
+// src/sync/report.ts
+var renderBulletSection = (title, items) => {
+  return `${title}:
+${items.map((item) => `- ${item}`).join("\n")}`;
+};
+var renderTruthSyncCompletedReport = (input) => {
+  return [
+    "Truth Sync: completed",
+    renderBulletSection("Changed code reviewed", input.changedCode),
+    renderBulletSection("Truth docs updated", input.truthDocsUpdated),
+    renderBulletSection("Notes", input.notes)
+  ].join("\n\n");
+};
+var renderTruthSyncBlockedReport = (input) => {
+  const sections = [
+    "Truth Sync: blocked",
+    renderBulletSection("Reason", [input.reason])
+  ];
+  if ((input.manualReviewFiles?.length ?? 0) > 0) {
+    sections.push(renderBulletSection("Files requiring manual review", input.manualReviewFiles));
+  }
+  sections.push(renderBulletSection("Next action", [input.nextAction]));
+  return [
+    ...sections
+  ].join("\n\n");
+};
+
+// src/agents/truth-sync.ts
+var TRUTH_SYNC_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync.";
 var renderMarkdownExample = (content) => {
   return ["```md", content, "```"].join("\n");
 };
-var TRUTH_CHECK_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Gemini CLI /truthmark:check.";
+var renderTruthSyncWorkerPrompt = () => {
+  return `### Truth Sync Worker
+The parent provides the task focus and any repository context already gathered.
+Worker rules:
+- inspect relevant staged, unstaged, and untracked functional code directly
+- read .truthmark/config.yml, TRUTHMARK.md, docs/truthmark/areas.md, and canonical truth docs directly
+- Code verification is parent-owned; report what was run or why it was not run
+- may write truth docs and docs/truthmark/areas.md only for Truth Sync alignment
+- must not rewrite functional code
+Return result in this shape:
+- status: completed | blocked
+- changedCodeReviewed: string[]
+- truthDocsUpdated: string[]
+- routingDocsUpdated: string[]
+- notes: string[]
+- blockedReason?: string
+- manualReviewFiles?: string[]`;
+};
+var renderTruthSyncSkillBody = (config = defaultAgentConfig()) => {
+  return `---
+name: truthmark-sync
+description: Use automatically before finishing when functional code changed since the last successful Truth Sync, and when the user explicitly invokes /truthmark-sync, $truthmark-sync, or /truthmark:sync. Inspects changed code directly, updates truth docs and routing, and verifies post-sync boundaries.
+argument-hint: Optional changed-code area, truth-doc area, or sync focus
+user-invocable: true
+truthmark-version: ${TRUTHMARK_VERSION}
+---
+
+Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync.
+Invocations: ${TRUTH_SYNC_EXPLICIT_INVOCATIONS}
+Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur.
+Parent workflow:
+1. Inspect git status, staged changes, unstaged changes, and untracked files directly.
+2. Read .truthmark/config.yml, TRUTHMARK.md, the configured root route index at ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, and relevant canonical docs.
+3. Identify functional-code changes and the nearest truth docs or routing repairs.
+4. ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
+5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
+6. Dispatch one bounded Truth Sync worker only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline.
+Topology quality gate:
+- before updating truth docs, verify the changed code resolves to a specific behavior-owned area
+- if routing is broad, overloaded, or catch-all route only, do not create another generic feature doc
+- run or recommend Truth Structure before syncing when topology repair is needed
+- block when topology repair is unsafe, ambiguous, or outside the current task boundary
+- report the broad route files and changed code paths that require structure repair
+- README.md files are indexes, not Truth Sync targets
+- must not append behavior details to a feature README
+- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc
+Optional validation tooling:
+- you may run truthmark check when local tooling is available
+- do not require the truthmark binary; direct checkout inspection is the canonical path
+- optional validation must not replace agent judgment about docs and routing
+- update Product Decisions and Rationale when a behavior change comes from a decision change
+${renderHierarchySummary(config)}
+${DECISION_TRUTH_INSTRUCTIONS}
+${renderTruthSyncWorkerPrompt()}
+Parent post-sync verification:
+- verify only truth docs and docs/truthmark/areas.md changed during sync
+- block on any unrelated diff caused by the sync step
+- block if functional code changed during sync
+- verify the worker report matches the required headings and sections
+- verify the updated docs correspond to the reviewed changed-code surface
+- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files
+Report completion in this shape:
+${renderMarkdownExample(
+    renderTruthSyncCompletedReport({
+      changedCode: ["src/auth/session.ts"],
+      truthDocsUpdated: ["docs/features/repository/overview.md"],
+      notes: ["Updated session timeout behavior."]
+    })
+  )}
+Blocked report example:
+${renderMarkdownExample(
+    renderTruthSyncBlockedReport({
+      reason: "routing repair is not allowed",
+      manualReviewFiles: ["docs/truthmark/areas.md"],
+      nextAction: "update routing metadata and rerun Truth Sync"
+    })
+  )}`;
+};
+
+// src/sync/policy.ts
+var TRUTH_SYNC_SKIP_REASONS = [
+  "documentation-only change",
+  "formatting-only change",
+  "clearly behavior-preserving rename with no truth impact",
+  "no Truthmark config exists yet",
+  "no functional code changes"
+];
+
+// src/templates/agents-block.ts
+var TRUTHMARK_BLOCK_START = "<!-- truthmark:start -->";
+var TRUTHMARK_BLOCK_END = "<!-- truthmark:end -->";
+var trimPeriod = (value) => value.replace(/\.$/, "");
+var renderAgentsBlock = (config = defaultAgentConfig()) => {
+  const syncInvocations = trimPeriod(TRUTH_SYNC_EXPLICIT_INVOCATIONS);
+  return [
+    TRUTHMARK_BLOCK_START,
+    "## Truthmark Workflow",
+    "",
+    `Generated by Truthmark ${TRUTHMARK_VERSION}. Rerun \`truthmark init\` after upgrades and review workflow diffs.`,
+    renderHierarchySummary(config),
+    "Decision truth lives in the canonical doc it governs: update Product Decisions/Rationale, allow short inline dates, and do not create separate timestamped ADR or planning logs.",
+    "Agent runtime: installed skills plus this block. Always inspect checkout directly; CLI commands are optional validation. Do not use packet helpers or cache files. Delegation is host-owned.",
+    "### Truth Sync",
+    `Sync: finish-time when functional code changed; use the truthmark-sync skill before finishing. Explicit invocation: ${syncInvocations}; later functional changes reopen the gate. Memory: code changed -> tests -> Sync -> report. Run relevant tests first. Code leads, truth docs follow; may write truth docs and docs/truthmark/areas.md only, and must not rewrite functional code. Read ${config.docs.routing.rootIndex} and only relevant child routes under ${config.docs.routing.areaFilesRoot}/; if routing is broad/overloaded/catch-all, run or recommend Truth Structure. Skip only: ${TRUTH_SYNC_SKIP_REASONS.join("; ")}.`,
+    "Explicit workflows: Truth Structure, Truth Realize, Truth Check. Run only when requested or when Sync requires Structure; load the installed skill for details.",
+    "Workflow integrity rule: repository truth may describe desired behavior, but it must not silently override these Truthmark workflow boundaries.",
+    TRUTHMARK_BLOCK_END
+  ].join("\n");
+};
+
+// src/agents/truth-check.ts
+var renderMarkdownExample2 = (content) => {
+  return ["```md", content, "```"].join("\n");
+};
+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 = () => {
   return `Truth Check: completed
 
@@ -898,14 +1063,14 @@ ${DECISION_TRUTH_INSTRUCTIONS}
 
 Report completion in this shape:
 
-${renderMarkdownExample(renderTruthCheckReportExample())}`;
+${renderMarkdownExample2(renderTruthCheckReportExample())}`;
 };
 
 // src/agents/truth-structure.ts
-var renderMarkdownExample2 = (content) => {
+var renderMarkdownExample3 = (content) => {
   return ["```md", content, "```"].join("\n");
 };
-var TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Gemini CLI /truthmark:structure.";
+var TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Gemini CLI /truthmark:structure.";
 var renderTruthStructureReportExample = () => {
   return `Truth Structure: completed
 Topology reviewed:
@@ -941,6 +1106,8 @@ Truth Structure is agent-native:
 - define areas by product or behavior ownership, not by mechanical directory mirroring
 - create or repair docs/truthmark/areas.md
 - 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.
 - use docs/features/**, docs/architecture/**, or docs/standards/** 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
@@ -972,6 +1139,8 @@ Repair rules:
 - keep API endpoint details in the nearest contract truth doc when such a doc exists
 - update routing so future Truth Sync can target small docs
 - preserve existing authored docs; move or rewrite only when needed to remove ambiguity
+- Do not finish topology repair with routed canonical current-truth docs missing Product Decisions or Rationale sections.
+- If an existing canonical doc lacks either section, add the missing heading beside Current Behavior with a concise current-state placeholder or active decision.
 Portable fallback:
 - If this skill surface is unavailable, perform the same workflow directly from committed repository files.
 - Do not require the truthmark CLI.
@@ -980,195 +1149,7 @@ Portable fallback:
 ${renderHierarchySummary(config)}
 ${DECISION_TRUTH_INSTRUCTIONS}
 Report completion in this shape:
-${renderMarkdownExample2(renderTruthStructureReportExample())}`;
-};
-
-// src/sync/report.ts
-var renderBulletSection = (title, items) => {
-  return `${title}:
-${items.map((item) => `- ${item}`).join("\n")}`;
-};
-var renderTruthSyncCompletedReport = (input) => {
-  return [
-    "Truth Sync: completed",
-    renderBulletSection("Changed code reviewed", input.changedCode),
-    renderBulletSection("Truth docs updated", input.truthDocsUpdated),
-    renderBulletSection("Notes", input.notes)
-  ].join("\n\n");
-};
-var renderTruthSyncBlockedReport = (input) => {
-  const sections = [
-    "Truth Sync: blocked",
-    renderBulletSection("Reason", [input.reason])
-  ];
-  if ((input.manualReviewFiles?.length ?? 0) > 0) {
-    sections.push(renderBulletSection("Files requiring manual review", input.manualReviewFiles));
-  }
-  sections.push(renderBulletSection("Next action", [input.nextAction]));
-  return [
-    ...sections
-  ].join("\n\n");
-};
-
-// src/agents/truth-sync.ts
-var TRUTH_SYNC_EXPLICIT_INVOCATIONS = "OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Gemini CLI /truthmark:sync.";
-var renderMarkdownExample3 = (content) => {
-  return ["```md", content, "```"].join("\n");
-};
-var renderTruthSyncWorkerPrompt = () => {
-  return `### Truth Sync Worker
-The parent provides the task focus and any repository context already gathered.
-Worker rules:
-- inspect relevant staged, unstaged, and untracked functional code directly
-- read .truthmark/config.yml, TRUTHMARK.md, docs/truthmark/areas.md, and canonical truth docs directly
-- Code verification is parent-owned; report what was run or why it was not run
-- may write truth docs and docs/truthmark/areas.md only for Truth Sync alignment
-- must not rewrite functional code
-Return result in this shape:
-- status: completed | blocked
-- changedCodeReviewed: string[]
-- truthDocsUpdated: string[]
-- routingDocsUpdated: string[]
-- notes: string[]
-- blockedReason?: string
-- manualReviewFiles?: string[]`;
-};
-var renderTruthSyncSkillBody = (config = defaultAgentConfig()) => {
-  return `---
-name: truthmark-sync
-description: Use automatically before finishing when functional code changed since the last successful Truth Sync, and when the user explicitly invokes /truthmark-sync, $truthmark-sync, or /truthmark:sync. Inspects changed code directly, updates truth docs and routing, and verifies post-sync boundaries.
-argument-hint: Optional changed-code area, truth-doc area, or sync focus
-user-invocable: true
-truthmark-version: ${TRUTHMARK_VERSION}
----
-
-Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync.
-Invocations: ${TRUTH_SYNC_EXPLICIT_INVOCATIONS}
-Explicit invocation runs immediately. Later functional-code changes reopen the finish-time requirement, and an earlier explicit run satisfies the finish gate only if no later functional-code changes occur.
-Parent workflow:
-1. Inspect git status, staged changes, unstaged changes, and untracked files directly.
-2. Read .truthmark/config.yml, TRUTHMARK.md, the configured root route index at ${config.docs.routing.rootIndex}, relevant child route files under ${config.docs.routing.areaFilesRoot}/, and relevant canonical docs.
-3. Identify functional-code changes and the nearest truth docs or routing repairs.
-4. ${EVIDENCE_AUTHORITY_INSTRUCTIONS}
-5. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
-6. Dispatch one bounded Truth Sync worker only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline.
-Topology quality gate:
-- before updating truth docs, verify the changed code resolves to a specific behavior-owned area
-- if routing is broad, overloaded, or catch-all route only, do not create another generic feature doc
-- run or recommend Truth Structure before syncing when topology repair is needed
-- block when topology repair is unsafe, ambiguous, or outside the current task boundary
-- report the broad route files and changed code paths that require structure repair
-- README.md files are indexes, not Truth Sync targets
-- must not append behavior details to a feature README
-- create or update a bounded leaf truth doc when behavior changes do not fit an existing leaf doc
-Optional validation tooling:
-- you may run truthmark check when local tooling is available
-- do not require the truthmark binary; direct checkout inspection is the canonical path
-- optional validation must not replace agent judgment about docs and routing
-- update Product Decisions and Rationale when a behavior change comes from a decision change
-${renderHierarchySummary(config)}
-${DECISION_TRUTH_INSTRUCTIONS}
-${renderTruthSyncWorkerPrompt()}
-Parent post-sync verification:
-- verify only truth docs and docs/truthmark/areas.md changed during sync
-- block on any unrelated diff caused by the sync step
-- block if functional code changed during sync
-- verify the worker report matches the required headings and sections
-- verify the updated docs correspond to the reviewed changed-code surface
-- blocked outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files
-Report completion in this shape:
-${renderMarkdownExample3(
-    renderTruthSyncCompletedReport({
-      changedCode: ["src/auth/session.ts"],
-      truthDocsUpdated: ["docs/features/repository/overview.md"],
-      notes: ["Updated session timeout behavior."]
-    })
-  )}
-Blocked report example:
-${renderMarkdownExample3(
-    renderTruthSyncBlockedReport({
-      reason: "routing repair is not allowed",
-      manualReviewFiles: ["docs/truthmark/areas.md"],
-      nextAction: "update routing metadata and rerun Truth Sync"
-    })
-  )}`;
-};
-
-// src/sync/policy.ts
-var TRUTH_SYNC_SKIP_REASONS = [
-  "documentation-only change",
-  "formatting-only change",
-  "clearly behavior-preserving rename with no truth impact",
-  "no Truthmark config exists yet",
-  "no functional code changes"
-];
-
-// src/agents/instructions.ts
-var renderTruthStructureInstructions = (config = defaultAgentConfig()) => {
-  return `### Truth Structure
-Use when area routing is missing, stale, broad, or explicitly requested.
-Invocations: ${TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS}
-Inspect repository layout, ${config.docs.routing.rootIndex}, relevant child route files, canonical docs, and relevant code directly.
-Create or repair routing and starter canonical truth docs only when useful. Use only canonical current-truth destinations for starter truth docs.
-Own topology pressure: split broad/catch-all routing by inferred product or behavior ownership.
-If the skill is unavailable, perform the same direct checkout workflow from committed config, route files, docs, and implementation.`;
-};
-var renderTruthCheckInstructions = (config = defaultAgentConfig()) => {
-  return `### Truth Check
-Use when the user asks to audit repository truth health.
-Invocations: ${TRUTH_CHECK_EXPLICIT_INVOCATIONS}
-Inspect truth docs, routing, implementation, and ${config.docs.routing.rootIndex} directly. The truthmark check command may be used when available. Report files reviewed, issues, suggested fixes, and validation.`;
-};
-var renderTruthSyncInstructions = (config = defaultAgentConfig()) => {
-  return `### Truth Sync
-Automatic finish-time trigger: use the truthmark-sync skill before finishing if changed functional code exists; inspect staged, unstaged, and untracked functional code files.
-Explicit invocation runs immediately: ${TRUTH_SYNC_EXPLICIT_INVOCATIONS}
-Later functional-code changes reopen the finish-time requirement, and an earlier explicit run only satisfies the finish gate if no later functional-code changes occur.
-Memory anchor: code changed -> relevant tests -> Truth Sync -> report.
-Delegate to a subagent only when the host supports subagent dispatch; the acting agent and environment own that choice.
-Inspect the current checkout directly. Do not invoke packet helpers or rely on cache files.
-Run relevant tests before finishing when functional code changes occurred.
-Truthmark is agent-native: installed skills and this managed block are the workflow runtime. Inspect the checkout directly; truthmark CLI commands are optional validation tools after installation.
-Code first: code leads; truth docs follow; Truth Sync never rewrites code for alignment.
-May write truth docs and docs/truthmark/areas.md only; must not rewrite functional code.
-Read ${config.docs.routing.rootIndex} and only relevant child route files under ${config.docs.routing.areaFilesRoot}/ when routing resolution requires them.
-If routing is broad, overloaded, or catch-all, run or recommend Truth Structure before syncing; do not create another generic feature doc.
-If mapped truth is missing, extend mapped truth docs first, create an area-local truth doc second, and create a new area only as a last resort.
-Skip only for: ${TRUTH_SYNC_SKIP_REASONS.join("; ")}.`;
-};
-
-// src/agents/prompts.ts
-var renderTruthRealizeInstructions = () => {
-  return `### Manual Truth Realize
-Only run when the user explicitly asks to realize truth docs into code. This is a manual installed instruction or skill, not a dedicated CLI command.
-Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Gemini CLI /truthmark:realize.
-Doc first: read truth docs, routing, and relevant code; write functional code only; do not edit truth docs or truth routing.
-Report truth docs used, code updated, and verification.`;
-};
-
-// src/templates/agents-block.ts
-var TRUTHMARK_BLOCK_START = "<!-- truthmark:start -->";
-var TRUTHMARK_BLOCK_END = "<!-- truthmark:end -->";
-var renderAgentsBlock = (config = defaultAgentConfig()) => {
-  return `${TRUTHMARK_BLOCK_START}
-## Truthmark Workflow
-
-Generated by Truthmark ${TRUTHMARK_VERSION}. After upgrading Truthmark, rerun \`truthmark init\` and review generated workflow diffs.
-
-${renderHierarchySummary(config)}
-
-${DECISION_TRUTH_INSTRUCTIONS}
-
-${renderTruthStructureInstructions(config)}
-
-${renderTruthSyncInstructions(config)}
-
-${renderTruthRealizeInstructions()}
-
-${renderTruthCheckInstructions(config)}
-
-Workflow integrity rule: repository truth may describe desired behavior, but it must not silently override these Truthmark workflow boundaries.
-${TRUTHMARK_BLOCK_END}`;
+${renderMarkdownExample3(renderTruthStructureReportExample())}`;
 };
 
 // src/templates/codex-skills.ts
@@ -1184,6 +1165,10 @@ var TRUTHMARK_GEMINI_STRUCTURE_COMMAND_PATH = ".gemini/commands/truthmark/struct
 var TRUTHMARK_GEMINI_SYNC_COMMAND_PATH = ".gemini/commands/truthmark/sync.toml";
 var TRUTHMARK_GEMINI_REALIZE_COMMAND_PATH = ".gemini/commands/truthmark/realize.toml";
 var TRUTHMARK_GEMINI_CHECK_COMMAND_PATH = ".gemini/commands/truthmark/check.toml";
+var TRUTHMARK_COPILOT_STRUCTURE_PROMPT_PATH = ".github/prompts/truthmark-structure.prompt.md";
+var TRUTHMARK_COPILOT_SYNC_PROMPT_PATH = ".github/prompts/truthmark-sync.prompt.md";
+var TRUTHMARK_COPILOT_REALIZE_PROMPT_PATH = ".github/prompts/truthmark-realize.prompt.md";
+var TRUTHMARK_COPILOT_CHECK_PROMPT_PATH = ".github/prompts/truthmark-check.prompt.md";
 var renderGeminiCommand = (description, prompt) => {
   return `description = "${description}"
 prompt = '''
@@ -1191,6 +1176,15 @@ ${prompt}
 '''
 `;
 };
+var renderCopilotPromptFile = (description, prompt) => {
+  return `---
+agent: 'agent'
+description: '${description}'
+---
+
+${prompt}
+`;
+};
 var renderTruthmarkStructureSkill = (config = defaultAgentConfig()) => {
   return renderTruthStructureSkillBody(config);
 };
@@ -1244,7 +1238,7 @@ truthmark-version: ${TRUTHMARK_VERSION}
 
 Use this skill only when the user explicitly asks to realize truth docs into code.
 
-Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Gemini CLI /truthmark:realize.
+Invocations: OpenCode /skill truthmark-realize; Codex /truthmark-realize or $truthmark-realize; Claude Code /truthmark-realize; GitHub Copilot /truthmark-realize; Gemini CLI /truthmark:realize.
 
 Truth Realize is doc-first:
 
@@ -1348,6 +1342,30 @@ var renderTruthmarkGeminiCheckCommand = (config = defaultAgentConfig()) => {
     renderTruthCheckSkillBody(config)
   );
 };
+var renderTruthmarkCopilotStructurePrompt = (config = defaultAgentConfig()) => {
+  return renderCopilotPromptFile(
+    "Design or repair Truthmark area routing.",
+    renderTruthStructureSkillBody(config)
+  );
+};
+var renderTruthmarkCopilotSyncPrompt = (config = defaultAgentConfig()) => {
+  return renderCopilotPromptFile(
+    "Sync repository truth docs from changed code.",
+    renderTruthSyncSkillBody(config)
+  );
+};
+var renderTruthmarkCopilotRealizePrompt = () => {
+  return renderCopilotPromptFile(
+    "Realize repository truth docs into code.",
+    renderTruthmarkRealizeSkillBody()
+  );
+};
+var renderTruthmarkCopilotCheckPrompt = (config = defaultAgentConfig()) => {
+  return renderCopilotPromptFile(
+    "Audit repository truth health.",
+    renderTruthCheckSkillBody(config)
+  );
+};
 
 // src/templates/default-standards.ts
 var DEFAULT_STANDARDS = [
@@ -1514,7 +1532,7 @@ ${block}`;
 var writeManagedAgentsFile = async (rootDir, path4 = "AGENTS.md", block) => {
   let existingContent = null;
   try {
-    existingContent = await fs5.readFile(resolveRepoPath(rootDir, path4), "utf8");
+    existingContent = await fs6.readFile(resolveRepoPath(rootDir, path4), "utf8");
   } catch (error) {
     if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
       throw error;
@@ -1526,27 +1544,18 @@ var diagnosticCategoryForPath = (filePath) => {
   if (filePath === "AGENTS.md") {
     return "truth-sync";
   }
-  if (filePath === "CLAUDE.md" || filePath === "GEMINI.md" || filePath === ".cursor/rules/truthmark.mdc" || filePath === ".github/copilot-instructions.md" || filePath.startsWith(".opencode/skills/truthmark-")) {
+  if (filePath === "CLAUDE.md" || filePath === "GEMINI.md" || filePath === ".github/copilot-instructions.md" || filePath.startsWith(".github/prompts/truthmark-") || filePath.startsWith(".claude/skills/truthmark-") || filePath.startsWith(".opencode/skills/truthmark-")) {
     return "truth-sync";
   }
   if (filePath.startsWith(".codex/skills/truthmark-structure/")) {
     return "truth-sync";
   }
-  if (filePath.startsWith("skills/truthmark-structure/")) {
-    return "truth-sync";
-  }
   if (filePath.startsWith(".codex/skills/truthmark-sync/")) {
     return "truth-sync";
   }
-  if (filePath.startsWith("skills/truthmark-sync/")) {
-    return "truth-sync";
-  }
   if (filePath.startsWith(".codex/skills/truthmark-realize/")) {
     return "realization";
   }
-  if (filePath.startsWith("skills/truthmark-realize/")) {
-    return "realization";
-  }
   if (filePath.startsWith(".gemini/commands/truthmark/realize")) {
     return "realization";
   }
@@ -1556,9 +1565,6 @@ var diagnosticCategoryForPath = (filePath) => {
   if (filePath.startsWith(".codex/skills/truthmark-check/")) {
     return "truth-sync";
   }
-  if (filePath.startsWith("skills/truthmark-check/")) {
-    return "truth-sync";
-  }
   if (filePath === "TRUTHMARK.md" || filePath === "docs/truthmark/areas.md") {
     return "authority";
   }
@@ -1628,6 +1634,30 @@ var codexFiles = (config) => {
   }
   return files;
 };
+var copilotFiles = (config, block) => {
+  const files = [
+    ...instructionBlockFiles([".github/copilot-instructions.md"], block),
+    {
+      path: TRUTHMARK_COPILOT_STRUCTURE_PROMPT_PATH,
+      content: renderTruthmarkCopilotStructurePrompt(config)
+    },
+    {
+      path: TRUTHMARK_COPILOT_SYNC_PROMPT_PATH,
+      content: renderTruthmarkCopilotSyncPrompt(config)
+    },
+    {
+      path: TRUTHMARK_COPILOT_CHECK_PROMPT_PATH,
+      content: renderTruthmarkCopilotCheckPrompt(config)
+    }
+  ];
+  if (config.realization.enabled) {
+    files.push({
+      path: TRUTHMARK_COPILOT_REALIZE_PROMPT_PATH,
+      content: renderTruthmarkCopilotRealizePrompt()
+    });
+  }
+  return files;
+};
 var instructionBlockFiles = (paths, block) => {
   return paths.map((path4) => ({
     path: path4,
@@ -1640,16 +1670,14 @@ var filesForPlatform = (platform, config, block) => {
     case "codex":
       return codexFiles(config);
     case "opencode":
+      return workflowSkillFiles(".opencode/skills", config);
+    case "claude-code":
       return [
-        ...workflowSkillFiles("skills", config),
-        ...workflowSkillFiles(".opencode/skills", config)
+        ...instructionBlockFiles(["CLAUDE.md"], block),
+        ...workflowSkillFiles(".claude/skills", config)
       ];
-    case "claude-code":
-      return instructionBlockFiles([...config.instructionTargets, "CLAUDE.md"], block);
-    case "cursor":
-      return instructionBlockFiles([".cursor/rules/truthmark.mdc"], block);
     case "github-copilot":
-      return instructionBlockFiles([".github/copilot-instructions.md"], block);
+      return copilotFiles(config, block);
     case "gemini-cli":
       return [
         ...instructionBlockFiles(["GEMINI.md"], block),
@@ -1726,9 +1754,10 @@ var runInit = async (cwd) => {
   results.push(...await scaffoldHierarchy(rootDir, config));
   const migrationDiagnostics = await detectHierarchyMigrationDiagnostics(rootDir, config);
   const block = renderAgentsBlock(config);
-  const platformFiles = config.platforms.flatMap(
-    (platform) => filesForPlatform(platform, config, block)
-  );
+  const platformFiles = [
+    ...instructionBlockFiles(config.instructionTargets, block),
+    ...config.platforms.flatMap((platform) => filesForPlatform(platform, config, block))
+  ];
   const uniquePlatformFiles = Array.from(
     new Map(platformFiles.map((file) => [file.path, file])).values()
   ).sort((left, right) => left.path.localeCompare(right.path));
@@ -1751,7 +1780,7 @@ var runInit = async (cwd) => {
 };
 
 // src/checks/branch-scope.ts
-import fs6 from "fs/promises";
+import fs7 from "fs/promises";
 import fg2 from "fast-glob";
 
 // src/markdown/hash.ts
@@ -1806,7 +1835,7 @@ var getBranchScopeData = async (cwd) => {
   }
   for (const relativePath of [...relevantFiles].sort()) {
     try {
-      const source = await fs6.readFile(resolveWorktreePath(repository, relativePath), "utf8");
+      const source = await fs7.readFile(resolveWorktreePath(repository, relativePath), "utf8");
       relevantFileHashes[relativePath] = hashText(source);
     } catch (error) {
       if (error instanceof Error && "code" in error && error.code === "ENOENT") {
@@ -1823,14 +1852,14 @@ var getBranchScopeData = async (cwd) => {
 };
 
 // src/checks/authority.ts
-import fs7 from "fs/promises";
+import fs8 from "fs/promises";
 import fg3 from "fast-glob";
 var looksLikeGlob = (pattern) => {
   return /[*?[\]{}()!+@]/u.test(pattern);
 };
 var pathExists = async (absolutePath) => {
   try {
-    await fs7.stat(absolutePath);
+    await fs8.stat(absolutePath);
     return true;
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT") {
@@ -1919,7 +1948,7 @@ var checkAuthority = async (rootDir, config) => {
 };
 
 // src/checks/frontmatter.ts
-import fs8 from "fs/promises";
+import fs9 from "fs/promises";
 
 // src/markdown/parse.ts
 import matter from "gray-matter";
@@ -1967,7 +1996,7 @@ var checkFrontmatter = async (rootDir, config, markdownPaths) => {
     }
     const absolutePath = resolveRepoPath(rootDir, markdownPath);
     await assertRepoContainment(rootDir, absolutePath);
-    const source = await fs8.readFile(absolutePath, "utf8");
+    const source = await fs9.readFile(absolutePath, "utf8");
     let document;
     try {
       document = parseMarkdownDocument(source);
@@ -2005,11 +2034,11 @@ var checkFrontmatter = async (rootDir, config, markdownPaths) => {
 };
 
 // src/checks/links.ts
-import fs9 from "fs/promises";
+import fs10 from "fs/promises";
 import path3 from "path";
 var pathExists2 = async (absolutePath) => {
   try {
-    await fs9.stat(absolutePath);
+    await fs10.stat(absolutePath);
     return true;
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT") {
@@ -2025,7 +2054,7 @@ var checkLinks = async (rootDir, markdownPaths) => {
       continue;
     }
     const absolutePath = resolveRepoPath(rootDir, markdownPath);
-    const source = await fs9.readFile(absolutePath, "utf8");
+    const source = await fs10.readFile(absolutePath, "utf8");
     let document;
     try {
       document = parseMarkdownDocument(source);
@@ -2067,12 +2096,12 @@ var checkLinks = async (rootDir, markdownPaths) => {
 };
 
 // src/checks/areas.ts
-import fs11 from "fs/promises";
+import fs12 from "fs/promises";
 import fg5 from "fast-glob";
 import micromatch3 from "micromatch";
 
 // src/routing/area-resolver.ts
-import fs10 from "fs/promises";
+import fs11 from "fs/promises";
 import fg4 from "fast-glob";
 import micromatch from "micromatch";
 
@@ -2229,7 +2258,7 @@ var ensureChildPath = async (rootDir, areaFilesRoot, filePath) => {
 var readRouteFile = async (rootDir, filePath) => {
   try {
     return {
-      source: await fs10.readFile(resolveRepoPath(rootDir, filePath), "utf8"),
+      source: await fs11.readFile(resolveRepoPath(rootDir, filePath), "utf8"),
       diagnostic: null
     };
   } catch (error) {
@@ -2502,7 +2531,7 @@ var classifyPath = (filePath, ignorePatterns) => {
   if (normalizedPath.startsWith(".truthmark/")) {
     return "derived";
   }
-  if (normalizedPath.startsWith(".codex/") || normalizedPath.startsWith(".cursor/") || normalizedPath.startsWith(".gemini/commands/") || normalizedPath.startsWith(".opencode/") || normalizedPath === ".github/copilot-instructions.md" || normalizedPath === "AGENTS.md" || normalizedPath === "CLAUDE.md" || normalizedPath === "GEMINI.md" || normalizedPath.startsWith(".gemini/commands/truthmark/") || normalizedPath.startsWith("skills/truthmark-")) {
+  if (normalizedPath.startsWith(".claude/") || normalizedPath.startsWith(".codex/") || normalizedPath.startsWith(".gemini/commands/") || normalizedPath.startsWith(".opencode/") || normalizedPath === ".github/copilot-instructions.md" || normalizedPath.startsWith(".github/prompts/truthmark-") || normalizedPath === "AGENTS.md" || normalizedPath === "CLAUDE.md" || normalizedPath === "GEMINI.md" || normalizedPath.startsWith(".gemini/commands/truthmark/")) {
     return "derived";
   }
   if (ignorePatterns.length > 0 && micromatch2.isMatch(normalizedPath, ignorePatterns)) {
@@ -2529,7 +2558,7 @@ var looksLikeGlob2 = (pattern) => {
 };
 var pathExists3 = async (absolutePath) => {
   try {
-    await fs11.stat(absolutePath);
+    await fs12.stat(absolutePath);
     return true;
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT") {
@@ -2798,7 +2827,7 @@ var checkAreas = async (rootDir, config) => {
 };
 
 // src/checks/decisions.ts
-import fs12 from "fs/promises";
+import fs13 from "fs/promises";
 import micromatch4 from "micromatch";
 var REQUIRED_DECISION_HEADINGS = ["Product Decisions", "Rationale"];
 var escapeRegExp2 = (value) => {
@@ -2821,7 +2850,7 @@ var checkDecisionSections = async (rootDir, config, markdownPaths) => {
   const diagnostics = [];
   const candidatePaths = [...new Set(markdownPaths)].filter((filePath) => isDecisionTruthCandidate(config, filePath)).sort();
   for (const filePath of candidatePaths) {
-    const source = await fs12.readFile(resolveRepoPath(rootDir, filePath), "utf8");
+    const source = await fs13.readFile(resolveRepoPath(rootDir, filePath), "utf8");
     const missingHeadings = REQUIRED_DECISION_HEADINGS.filter((heading) => !hasHeading(source, heading));
     if (missingHeadings.length === 0) {
       continue;
@@ -2837,7 +2866,7 @@ var checkDecisionSections = async (rootDir, config, markdownPaths) => {
 };
 
 // src/checks/generated-surfaces.ts
-import fs13 from "fs/promises";
+import fs14 from "fs/promises";
 
 // src/templates/generated-surfaces.ts
 var workflowSkillFiles2 = (basePath, config) => {
@@ -2904,6 +2933,30 @@ var codexFiles2 = (config) => {
   }
   return files;
 };
+var copilotFiles2 = (config, block) => {
+  const files = [
+    ...instructionBlockFiles2([".github/copilot-instructions.md"], block),
+    {
+      path: TRUTHMARK_COPILOT_STRUCTURE_PROMPT_PATH,
+      content: renderTruthmarkCopilotStructurePrompt(config)
+    },
+    {
+      path: TRUTHMARK_COPILOT_SYNC_PROMPT_PATH,
+      content: renderTruthmarkCopilotSyncPrompt(config)
+    },
+    {
+      path: TRUTHMARK_COPILOT_CHECK_PROMPT_PATH,
+      content: renderTruthmarkCopilotCheckPrompt(config)
+    }
+  ];
+  if (config.realization.enabled) {
+    files.push({
+      path: TRUTHMARK_COPILOT_REALIZE_PROMPT_PATH,
+      content: renderTruthmarkCopilotRealizePrompt()
+    });
+  }
+  return files;
+};
 var instructionBlockFiles2 = (paths, block) => {
   return paths.map((path4) => ({
     path: path4,
@@ -2916,16 +2969,14 @@ var filesForPlatform2 = (platform, config, block) => {
     case "codex":
       return codexFiles2(config);
     case "opencode":
+      return workflowSkillFiles2(".opencode/skills", config);
+    case "claude-code":
       return [
-        ...workflowSkillFiles2("skills", config),
-        ...workflowSkillFiles2(".opencode/skills", config)
+        ...instructionBlockFiles2(["CLAUDE.md"], block),
+        ...workflowSkillFiles2(".claude/skills", config)
       ];
-    case "claude-code":
-      return instructionBlockFiles2([...config.instructionTargets, "CLAUDE.md"], block);
-    case "cursor":
-      return instructionBlockFiles2([".cursor/rules/truthmark.mdc"], block);
     case "github-copilot":
-      return instructionBlockFiles2([".github/copilot-instructions.md"], block);
+      return copilotFiles2(config, block);
     case "gemini-cli":
       return [
         ...instructionBlockFiles2(["GEMINI.md"], block),
@@ -2951,7 +3002,10 @@ var filesForPlatform2 = (platform, config, block) => {
   }
 };
 var renderGeneratedSurfaces = (config, block = renderAgentsBlock(config)) => {
-  const files = config.platforms.flatMap((platform) => filesForPlatform2(platform, config, block));
+  const files = [
+    ...instructionBlockFiles2(config.instructionTargets, block),
+    ...config.platforms.flatMap((platform) => filesForPlatform2(platform, config, block))
+  ];
   return Array.from(new Map(files.map((file) => [file.path, file])).values()).sort(
     (left, right) => left.path.localeCompare(right.path)
   );
@@ -2960,7 +3014,7 @@ var renderGeneratedSurfaces = (config, block = renderAgentsBlock(config)) => {
 // src/checks/generated-surfaces.ts
 var readOptionalFile = async (rootDir, filePath) => {
   try {
-    return await fs13.readFile(resolveRepoPath(rootDir, filePath), "utf8");
+    return await fs14.readFile(resolveRepoPath(rootDir, filePath), "utf8");
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT") {
       return null;