ci: remove openssf scorecard

feat: add static introduction website (#29 )
* feat: add static introduction website * feat: expand static website positioning * feat: redesign site with original visuals * docs(readme): add package status badges * ci: add project readiness automation * ci: restrict scorecard workflow permissions * ci: remove duplicate readiness config * ci: pin workflow actions by sha * docs: add scorecard badge --------- Co-authored-by: MerlinH <merlinh221@gmail.com>
2026-08-25 07:53:25 +02:00 · 2026-06-27 01:23:24 +10:00 · 2026-06-27 01:15:39 +10:00 · 2026-06-27 00:05:15 +10:00 · 2026-06-22 18:07:08 +10:00 · 2026-06-22 03:28:02 +10:00
97 changed files with 2464 additions and 764 deletions
@@ -60,7 +60,12 @@ Treat the HTML comments under each template section as normative authoring guida
 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 lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
 Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
-Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists.
+Truth-doc prose style:
+- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.
+- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.
+- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
+- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
+- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references.
 Truth-doc shape repair review:
 - Truth Document may restructure only truth docs for the implemented behavior being documented.
 - repair shape in place only after the ownership review confirms the doc is the right bounded owner
@@ -32,6 +32,12 @@ Parent workflow:
   - No-update-needed rationale: why mapped truth is already current when no truth doc should change
   - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
 11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
+Truth-doc prose style:
+- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.
+- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.
+- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
+- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
+- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references.
 Topology review and repair:
 - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
 - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
@@ -11,26 +11,26 @@ Changed code reviewed:

 Sync Intent:
 - Changed code reviewed: src/auth/session.ts
- Affected route/truth owner: docs/truthmark/routes/areas.md
- Target truth docs: docs/truthmark/engineering/repository/bootstrap-routing.md
+- Affected route/truth owner: docs/truthmark/routes/areas/authentication.md
+- Target truth docs: docs/truthmark/engineering/behaviors/session-timeout.md
 - Intended update: Update session timeout behavior.
- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
+- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11
 - User-provided decisions/rationale: User rationale: session timeout behavior changed for internal implementation consistency
 - No-update-needed rationale: not applicable; mapped truth is stale
 - Blockers: none

 Ownership reviewed:
- docs/truthmark/routes/areas.md
+- docs/truthmark/routes/areas/authentication.md

 Truth docs updated:
- docs/truthmark/engineering/repository/bootstrap-routing.md
+- docs/truthmark/engineering/behaviors/session-timeout.md

 Decision/rationale captured:
- Placed user rationale in the mapped engineering truth doc under Engineering Decisions/Rationale.
+- Placed user rationale in the bounded authentication behavior truth doc under Engineering Decisions/Rationale.

 Evidence checked:
- Claim: Session timeout behavior is documented in the mapped repository truth doc.
-  Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
+- Claim: Session timeout behavior is documented in the bounded authentication behavior truth doc.
+  Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11
  Result: supported

 Notes:
@@ -41,11 +41,12 @@ Blocked report example:
 Truth Sync: blocked

 Reason:
- routing repair is not allowed
+- Changed code maps only to the provisional bootstrap route.

 Files requiring manual review:
- docs/truthmark/routes/areas.md
+- src/auth/**
+- docs/truthmark/routes/areas/repository.md

 Next action:
- update routing metadata and rerun Truth Sync
+- Run Truth Structure for src/auth/** before updating behavior truth.
 ```
@@ -72,7 +72,12 @@ Treat the HTML comments under each template section as normative authoring guida
 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 lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
 Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
-Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists.
+Truth-doc prose style:
+- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.
+- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.
+- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
+- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
+- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references.
 Truth-doc shape repair review:
 - Truth Document may restructure only truth docs for the implemented behavior being documented.
 - repair shape in place only after the ownership review confirms the doc is the right bounded owner
@@ -44,6 +44,12 @@ Parent workflow:
   - No-update-needed rationale: why mapped truth is already current when no truth doc should change
   - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
 11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
+Truth-doc prose style:
+- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.
+- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.
+- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
+- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
+- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references.
 Topology review and repair:
 - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
 - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
@@ -86,26 +92,26 @@ Changed code reviewed:

 Sync Intent:
 - Changed code reviewed: src/auth/session.ts
- Affected route/truth owner: docs/truthmark/routes/areas.md
- Target truth docs: docs/truthmark/engineering/repository/bootstrap-routing.md
+- Affected route/truth owner: docs/truthmark/routes/areas/authentication.md
+- Target truth docs: docs/truthmark/engineering/behaviors/session-timeout.md
 - Intended update: Update session timeout behavior.
- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
+- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11
 - User-provided decisions/rationale: User rationale: session timeout behavior changed for internal implementation consistency
 - No-update-needed rationale: not applicable; mapped truth is stale
 - Blockers: none

 Ownership reviewed:
- docs/truthmark/routes/areas.md
+- docs/truthmark/routes/areas/authentication.md

 Truth docs updated:
- docs/truthmark/engineering/repository/bootstrap-routing.md
+- docs/truthmark/engineering/behaviors/session-timeout.md

 Decision/rationale captured:
- Placed user rationale in the mapped engineering truth doc under Engineering Decisions/Rationale.
+- Placed user rationale in the bounded authentication behavior truth doc under Engineering Decisions/Rationale.

 Evidence checked:
- Claim: Session timeout behavior is documented in the mapped repository truth doc.
-  Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
+- Claim: Session timeout behavior is documented in the bounded authentication behavior truth doc.
+  Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11
  Result: supported

 Notes:
@@ -116,11 +122,12 @@ Blocked report example:
 Truth Sync: blocked

 Reason:
- routing repair is not allowed
+- Changed code maps only to the provisional bootstrap route.

 Files requiring manual review:
- docs/truthmark/routes/areas.md
+- src/auth/**
+- docs/truthmark/routes/areas/repository.md

 Next action:
- update routing metadata and rerun Truth Sync
+- Run Truth Structure for src/auth/** before updating behavior truth.
 ```
@@ -16,6 +16,6 @@ For every checked claim, classify the result as supported | narrowed | removed |
 Do not edit files, stage changes, or invent missing behavior.
 Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsupportedClaims, confidence, recommendedWorkflow, notes.
 Context boundary:
-Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
 Use only the parent-assigned shard plus required checkout evidence files.
 Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
@@ -15,6 +15,6 @@ Do not edit files, stage changes, or rewrite docs.
 Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
 recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
 Context boundary:
-Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
 Use only the parent-assigned shard plus required checkout evidence files.
 Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
@@ -23,6 +23,6 @@ Do not edit files, stage changes, or propose broad rewrites.
 Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
 recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
 Context boundary:
-Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
 Use only the parent-assigned shard plus required checkout evidence files.
 Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
@@ -60,7 +60,12 @@ Treat the HTML comments under each template section as normative authoring guida
 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 lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
 Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
-Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists.
+Truth-doc prose style:
+- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.
+- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.
+- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
+- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
+- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references.
 Truth-doc shape repair review:
 - Truth Document may restructure only truth docs for the implemented behavior being documented.
 - repair shape in place only after the ownership review confirms the doc is the right bounded owner
@@ -32,6 +32,12 @@ Parent workflow:
   - No-update-needed rationale: why mapped truth is already current when no truth doc should change
   - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
 11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
+Truth-doc prose style:
+- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.
+- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.
+- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
+- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
+- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references.
 Topology review and repair:
 - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
 - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
@@ -11,26 +11,26 @@ Changed code reviewed:

 Sync Intent:
 - Changed code reviewed: src/auth/session.ts
- Affected route/truth owner: docs/truthmark/routes/areas.md
- Target truth docs: docs/truthmark/engineering/repository/bootstrap-routing.md
+- Affected route/truth owner: docs/truthmark/routes/areas/authentication.md
+- Target truth docs: docs/truthmark/engineering/behaviors/session-timeout.md
 - Intended update: Update session timeout behavior.
- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
+- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11
 - User-provided decisions/rationale: User rationale: session timeout behavior changed for internal implementation consistency
 - No-update-needed rationale: not applicable; mapped truth is stale
 - Blockers: none

 Ownership reviewed:
- docs/truthmark/routes/areas.md
+- docs/truthmark/routes/areas/authentication.md

 Truth docs updated:
- docs/truthmark/engineering/repository/bootstrap-routing.md
+- docs/truthmark/engineering/behaviors/session-timeout.md

 Decision/rationale captured:
- Placed user rationale in the mapped engineering truth doc under Engineering Decisions/Rationale.
+- Placed user rationale in the bounded authentication behavior truth doc under Engineering Decisions/Rationale.

 Evidence checked:
- Claim: Session timeout behavior is documented in the mapped repository truth doc.
-  Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
+- Claim: Session timeout behavior is documented in the bounded authentication behavior truth doc.
+  Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11
  Result: supported

 Notes:
@@ -41,11 +41,12 @@ Blocked report example:
 Truth Sync: blocked

 Reason:
- routing repair is not allowed
+- Changed code maps only to the provisional bootstrap route.

 Files requiring manual review:
- docs/truthmark/routes/areas.md
+- src/auth/**
+- docs/truthmark/routes/areas/repository.md

 Next action:
- update routing metadata and rerun Truth Sync
+- Run Truth Structure for src/auth/** before updating behavior truth.
 ```
@@ -12,7 +12,7 @@ For every checked claim, classify the result as supported | narrowed | removed |
 Do not edit files, stage changes, or invent missing behavior.
 Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsupportedClaims, confidence, recommendedWorkflow, notes.
 Context boundary:
-Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
 Use only the parent-assigned shard plus required checkout evidence files.
 Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
 """
@@ -11,7 +11,7 @@ Do not edit files, stage changes, or rewrite docs.
 Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
 recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
 Context boundary:
-Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
 Use only the parent-assigned shard plus required checkout evidence files.
 Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
 """
@@ -19,7 +19,7 @@ Do not edit files, stage changes, or propose broad rewrites.
 Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
 recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
 Context boundary:
-Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
 Use only the parent-assigned shard plus required checkout evidence files.
 Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
 """
@@ -0,0 +1,21 @@
+---
+name: truthmark-check
+description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs.
+argument-hint: Optional area, doc path, or audit focus
+user-invocable: true
+---
+
+# Truthmark Check
+
+Use this skill to audit repository truth health.
+
+Use as a Cursor Agent Skill. Cursor discovers project skills under `.cursor/skills/`, selects them from the description when relevant, and supports manual `/` invocation.
+
+Quick procedure:
+- 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 (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then inspect canonical docs and relevant implementation directly.
+- Report issues and suggested fixes; do not silently rewrite unrelated files.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
@@ -1,24 +1,7 @@
---
-description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs.
-alwaysApply: false
---
-
-# Truthmark Check
+# Truthmark Check Procedure

 Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.

-This rule is the Cursor entrypoint for Truthmark Check.
-
-Do not invoke another Truthmark command from here.
-
-Manual invocation: @truthmark-check
-
-If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
-
-Description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs. Not for normal lint/test/typecheck/code-review verification, finish-time Sync, or silently rewriting docs.
-
-## Procedure
-
 # Truthmark Check

 Use this skill to audit repository truth health.
@@ -69,29 +52,3 @@ Truthmark hierarchy hints:
 Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
 Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
 Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
-
-## Report Template
-
-Report completion in this shape:
-
-```md
-Truth Check: completed
-
-Files reviewed:
- docs/truthmark/routes/areas.md
-
-Issues found:
- none
-
-Fixes suggested:
- none
-
-Evidence checked:
- Finding: The root route index is present and maps repository truth owners.
-  Evidence: docs/truthmark/routes/areas.md:1
-  Suggested fix: none
-  Confidence: high
-
-Validation:
- truthmark check
-```
@@ -0,0 +1,27 @@
+# Truthmark Check Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+
+```md
+Truth Check: completed
+
+Files reviewed:
+- docs/truthmark/routes/areas.md
+
+Issues found:
+- none
+
+Fixes suggested:
+- none
+
+Evidence checked:
+- Finding: The root route index is present and maps repository truth owners.
+  Evidence: docs/truthmark/routes/areas.md:1
+  Suggested fix: none
+  Confidence: high
+
+Validation:
+- truthmark check
+```
@@ -0,0 +1,22 @@
+---
+name: truthmark-document
+description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure.
+argument-hint: Optional implemented behavior, API endpoint, route, controller, package, or truth-doc area to document
+user-invocable: true
+---
+
+# Truthmark Document
+
+Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
+
+Use as a Cursor Agent Skill. Cursor discovers project skills under `.cursor/skills/`, selects them from the description when relevant, and supports manual `/` invocation.
+
+Quick procedure:
+- 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 (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then inspect existing canonical docs, implementation code, and tests directly.
+- Document current implemented behavior; do not invent future behavior.
+- May write canonical truth docs and truth routing files only; must not write functional code.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
@@ -1,24 +1,7 @@
---
-description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure.
-alwaysApply: false
---
-
-# Truthmark Document
+# Truthmark Document Procedure

 Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.

-This rule is the Cursor entrypoint for Truthmark Document.
-
-Do not invoke another Truthmark command from here.
-
-Manual invocation: @truthmark-document
-
-If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
-
-Description: Use when the user asks to document existing implemented behavior, or Sync, Check, or Structure finds implemented behavior missing canonical truth. Not for functional-code changes, doc-first implementation, or topology repair that needs Structure.
-
-## Procedure
-
 # Truthmark Document

 Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
@@ -77,7 +60,12 @@ Treat the HTML comments under each template section as normative authoring guida
 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 lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
 Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
-Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists.
+Truth-doc prose style:
+- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.
+- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.
+- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
+- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
+- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references.
 Truth-doc shape repair review:
 - Truth Document may restructure only truth docs for the implemented behavior being documented.
 - repair shape in place only after the ownership review confirms the doc is the right bounded owner
@@ -102,36 +90,3 @@ Parent post-document verification:
 - stop on functional code, generated host surfaces, or unrelated diffs caused by document work
 - for each write lease, validate the worker report against the actual worker diff, allowedWrites, forbiddenWrites, identity fields, filesChanged, offLeaseChanges, blockers, and expected report fields before accepting it
 - verify the final report records ownership review, structure requirement, restructure, routing update, or manual handoff reason when applicable
-
-## Report Template
-
-Report completion in this shape:
-```md
-Truth Document: completed
-
-Implementation reviewed:
- src/routing/area-resolver.ts
-
-Ownership reviewed:
- docs/truthmark/routes/areas.md
-
-Truth docs created:
- docs/truthmark/engineering/contracts/routing.md
-
-Truth docs updated:
- docs/truthmark/engineering/behaviors/check-diagnostics.md
-
-Truth docs restructured:
- docs/truthmark/engineering/behaviors/check-diagnostics.md
-
-Routing updated:
- docs/truthmark/routes/areas.md
-
-Evidence checked:
- Claim: Route resolution behavior is documented in the contracts truth doc.
-  Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/routes/areas.md:9
-  Result: supported
-
-Notes:
- Documented routing and behavior from route handlers and tests.
-```
@@ -0,0 +1,34 @@
+# Truthmark Document Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+```md
+Truth Document: completed
+
+Implementation reviewed:
+- src/routing/area-resolver.ts
+
+Ownership reviewed:
+- docs/truthmark/routes/areas.md
+
+Truth docs created:
+- docs/truthmark/engineering/contracts/routing.md
+
+Truth docs updated:
+- docs/truthmark/engineering/behaviors/check-diagnostics.md
+
+Truth docs restructured:
+- docs/truthmark/engineering/behaviors/check-diagnostics.md
+
+Routing updated:
+- docs/truthmark/routes/areas.md
+
+Evidence checked:
+- Claim: Route resolution behavior is documented in the contracts truth doc.
+  Evidence: src/routing/area-resolver.ts:14 / docs/truthmark/routes/areas.md:9
+  Result: supported
+
+Notes:
+- Documented routing and behavior from route handlers and tests.
+```
@@ -0,0 +1,22 @@
+---
+name: truthmark-realize
+description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits.
+argument-hint: Optional truth doc path, area, or desired code behavior to realize
+user-invocable: true
+---
+
+# Truthmark Realize
+
+Use this skill only when the user explicitly asks to realize truth docs into code.
+
+Use as a Cursor Agent Skill. Cursor discovers project skills under `.cursor/skills/`, selects them from the description when relevant, and supports manual `/` invocation.
+
+Quick procedure:
+- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.
+- Read the source truth docs, inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist, then inspect tests and relevant functional code directly.
+- Truth docs lead; code follows.
+- may write functional code only; must not edit truth docs or truth routing while realizing those docs.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
@@ -1,24 +1,7 @@
---
-description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits.
-alwaysApply: false
---
-
-# Truthmark Realize
+# Truthmark Realize Procedure

 Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.

-This rule is the Cursor entrypoint for Truthmark Realize.
-
-Do not invoke another Truthmark command from here.
-
-Manual invocation: @truthmark-realize
-
-If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
-
-Description: Use when the user explicitly asks to realize Truthmark truth docs into code, including /truthmark-realize, $truthmark-realize, or /truthmark:realize. Not for syncing docs after code changes, documenting existing code, topology repair, or truth audits.
-
-## Procedure
-
 # Truthmark Realize

 Use this skill only when the user explicitly asks to realize truth docs into code.
@@ -56,21 +39,3 @@ Read and write boundaries:
 - may read truth docs, routing docs, and relevant functional code
 - may write functional code only
 - must not edit truth docs or truth routing while realizing those docs
-
-## Report Template
-
-Report completion in this shape:
-
-```md
-Truth Realize: completed
-
-Truth docs used:
- docs/truthmark/product/capabilities/authentication-session.md
- docs/truthmark/engineering/behaviors/authentication-session.md
-
-Code updated:
- src/auth/session.ts
-
-Verification:
- npm test -- auth
-```
@@ -0,0 +1,19 @@
+# Truthmark Realize Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+
+```md
+Truth Realize: completed
+
+Truth docs used:
+- docs/truthmark/product/capabilities/authentication-session.md
+- docs/truthmark/engineering/behaviors/authentication-session.md
+
+Code updated:
+- src/auth/session.ts
+
+Verification:
+- npm test -- auth
+```
@@ -0,0 +1,22 @@
+---
+name: truthmark-structure
+description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.
+argument-hint: Optional area, directory, or routing concern
+user-invocable: true
+---
+
+# Truthmark Structure
+
+Use this skill to design or repair Truthmark area structure.
+
+Use as a Cursor Agent Skill. Cursor discovers project skills under `.cursor/skills/`, selects them from the description when relevant, and supports manual `/` invocation.
+
+Quick procedure:
+- 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 (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then inspect current docs and relevant code directly.
+- Define areas by product or behavior ownership, not by mechanical directory mirroring.
+- Do not edit functional code.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
@@ -1,24 +1,7 @@
---
-description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.
-alwaysApply: false
---
-
-# Truthmark Structure
+# Truthmark Structure Procedure

 Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.

-This rule is the Cursor entrypoint for Truthmark Structure.
-
-Do not invoke another Truthmark command from here.
-
-Manual invocation: @truthmark-structure
-
-If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
-
-Description: Use when routing or truth ownership is missing, stale, broad, overloaded, catch-all, unrouteable, mixed-owner, needs split/repair, or needs new area setup. Not for documenting implemented behavior, syncing a code diff, or realizing docs into code.
-
-## Procedure
-
 Use this skill to design or repair Truthmark area structure.

 Truth Structure is agent-native:
@@ -116,40 +99,3 @@ Truthmark hierarchy hints:
 Decision truth lives in the canonical doc it governs; date active decisions inline when added or changed.
 Do not create separate active-decision ADR/planning logs; replace the active decision and let Git history carry the audit trail.
 Product decisions belong in product truth; engineering, architecture, contract, workflow, and operational decisions belong in engineering truth.
-
-## Report Template
-
-Report completion in this shape:
-```md
-Truth Structure: completed
-Topology reviewed:
- controllers: src/auth/**
- product docs root: docs/truthmark/product
- engineering docs root: docs/truthmark/engineering
- route files: docs/truthmark/routes/areas.md
-Areas reviewed:
- src/auth/**
-Routing updated:
- docs/truthmark/routes/areas.md
-Initial truth boundary:
- Area: Authentication
- Code: src/auth/**
- Product owner: docs/truthmark/product/capabilities/authentication-session.md
- Engineering owner: docs/truthmark/engineering/behaviors/authentication-session.md
- Scope: session behavior only
-Truth docs created:
- docs/truthmark/product/capabilities/authentication-session.md
- docs/truthmark/engineering/behaviors/authentication-session.md
-Truth docs split:
- docs/truthmark/truth/authentication/README.md -> docs/truthmark/product/capabilities/authentication-session.md and docs/truthmark/engineering/behaviors/authentication-session.md
-Truth docs restructured:
- docs/truthmark/truth/authentication/README.md
-Evidence checked:
- Claim: Session behavior belongs to a dedicated Authentication truth owner.
-  Evidence: src/auth/** / docs/truthmark/routes/areas.md:7
-  Result: supported
-Topology decisions:
- Added an Authentication area because session behavior has a distinct code surface and truth owner.
-Notes:
- Added an Authentication area for session behavior.
-```
@@ -0,0 +1,38 @@
+# Truthmark Structure Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+```md
+Truth Structure: completed
+Topology reviewed:
+- controllers: src/auth/**
+- product docs root: docs/truthmark/product
+- engineering docs root: docs/truthmark/engineering
+- route files: docs/truthmark/routes/areas.md
+Areas reviewed:
+- src/auth/**
+Routing updated:
+- docs/truthmark/routes/areas.md
+Initial truth boundary:
+- Area: Authentication
+- Code: src/auth/**
+- Product owner: docs/truthmark/product/capabilities/authentication-session.md
+- Engineering owner: docs/truthmark/engineering/behaviors/authentication-session.md
+- Scope: session behavior only
+Truth docs created:
+- docs/truthmark/product/capabilities/authentication-session.md
+- docs/truthmark/engineering/behaviors/authentication-session.md
+Truth docs split:
+- docs/truthmark/truth/authentication/README.md -> docs/truthmark/product/capabilities/authentication-session.md and docs/truthmark/engineering/behaviors/authentication-session.md
+Truth docs restructured:
+- docs/truthmark/truth/authentication/README.md
+Evidence checked:
+- Claim: Session behavior belongs to a dedicated Authentication truth owner.
+  Evidence: src/auth/** / docs/truthmark/routes/areas.md:7
+  Result: supported
+Topology decisions:
+- Added an Authentication area because session behavior has a distinct code surface and truth owner.
+Notes:
+- Added an Authentication area for session behavior.
+```
@@ -0,0 +1,23 @@
+---
+name: truthmark-sync
+description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design.
+argument-hint: Optional changed-code area, truth-doc area, or sync focus
+user-invocable: true
+---
+
+# Truthmark Sync
+
+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.
+
+Use as a Cursor Agent Skill. Cursor discovers project skills under `.cursor/skills/`, selects them from the description when relevant, and supports manual `/` invocation.
+
+Quick procedure:
+- Follow repository instruction files that exist in this checkout; do not assume any optional policy path exists.
+- Skip docs-only, formatting-only, behavior-preserving renames with no truth impact, missing config, and no-code changes.
+- Inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then inspect relevant canonical docs directly.
+- direct checkout inspection is the canonical path; do not require the truthmark binary.
+- May write canonical truth docs and truth routing files only; must not rewrite functional code.
+
+Progressive disclosure:
+- support/procedure.md — read before edits or detailed auditing; contains core review questions
+- support/report-template.md — read before the final report
@@ -1,24 +1,7 @@
---
-description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design.
-alwaysApply: false
---
-
-# Truthmark Sync
+# Truthmark Sync Procedure

 Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.

-This rule is the Cursor entrypoint for Truthmark Sync.
-
-Do not invoke another Truthmark command from here.
-
-Manual invocation: @truthmark-sync
-
-If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.
-
-Description: Use automatically at finish-time after functional code changes, or explicit /truthmark-sync, $truthmark-sync, or /truthmark:sync. Skip docs-only, formatting-only, behavior-preserving renames, missing config, and no-code changes. Not for doc-first realization or manual topology design.
-
-## Procedure
-
 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.
 Explicit invocation runs immediately when the user directly requests this workflow. Later functional-code changes need a fresh finish-time review, and an earlier explicit run satisfies the finish-time review only if no later functional-code changes occur.
 Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes.
@@ -49,6 +32,12 @@ Parent workflow:
   - No-update-needed rationale: why mapped truth is already current when no truth doc should change
   - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
 11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
+Truth-doc prose style:
+- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.
+- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.
+- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
+- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
+- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references.
 Topology review and repair:
 - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
 - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
@@ -79,53 +68,3 @@ Parent post-sync verification:
 - verify the updated docs correspond to reviewed checkout evidence, changed-code impact, or a recorded stale-truth correction made within the sync write lease
 - verify the final report records ownership review, structure requirement, split, restructure, or manual handoff reason when the ownership review applies
 - manual handoff outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files
-
-## Report Template
-
-Report completion in this shape:
-```md
-Truth Sync: completed
-
-Changed code reviewed:
- src/auth/session.ts
-
-Sync Intent:
- Changed code reviewed: src/auth/session.ts
- Affected route/truth owner: docs/truthmark/routes/areas.md
- Target truth docs: docs/truthmark/engineering/repository/bootstrap-routing.md
- Intended update: Update session timeout behavior.
- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
- User-provided decisions/rationale: User rationale: session timeout behavior changed for internal implementation consistency
- No-update-needed rationale: not applicable; mapped truth is stale
- Blockers: none
-
-Ownership reviewed:
- docs/truthmark/routes/areas.md
-
-Truth docs updated:
- docs/truthmark/engineering/repository/bootstrap-routing.md
-
-Decision/rationale captured:
- Placed user rationale in the mapped engineering truth doc under Engineering Decisions/Rationale.
-
-Evidence checked:
- Claim: Session timeout behavior is documented in the mapped repository truth doc.
-  Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
-  Result: supported
-
-Notes:
- Updated session timeout behavior.
-```
-Blocked report example:
-```md
-Truth Sync: blocked
-
-Reason:
- routing repair is not allowed
-
-Files requiring manual review:
- docs/truthmark/routes/areas.md
-
-Next action:
- update routing metadata and rerun Truth Sync
-```
@@ -0,0 +1,52 @@
+# Truthmark Sync Report Template
+
+Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
+
+Report completion in this shape:
+```md
+Truth Sync: completed
+
+Changed code reviewed:
+- src/auth/session.ts
+
+Sync Intent:
+- Changed code reviewed: src/auth/session.ts
+- Affected route/truth owner: docs/truthmark/routes/areas/authentication.md
+- Target truth docs: docs/truthmark/engineering/behaviors/session-timeout.md
+- Intended update: Update session timeout behavior.
+- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11
+- User-provided decisions/rationale: User rationale: session timeout behavior changed for internal implementation consistency
+- No-update-needed rationale: not applicable; mapped truth is stale
+- Blockers: none
+
+Ownership reviewed:
+- docs/truthmark/routes/areas/authentication.md
+
+Truth docs updated:
+- docs/truthmark/engineering/behaviors/session-timeout.md
+
+Decision/rationale captured:
+- Placed user rationale in the bounded authentication behavior truth doc under Engineering Decisions/Rationale.
+
+Evidence checked:
+- Claim: Session timeout behavior is documented in the bounded authentication behavior truth doc.
+  Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11
+  Result: supported
+
+Notes:
+- Updated session timeout behavior.
+```
+Blocked report example:
+```md
+Truth Sync: blocked
+
+Reason:
+- Changed code maps only to the provisional bootstrap route.
+
+Files requiring manual review:
+- src/auth/**
+- docs/truthmark/routes/areas/repository.md
+
+Next action:
+- Run Truth Structure for src/auth/** before updating behavior truth.
+```
@@ -14,6 +14,6 @@ For every checked claim, classify the result as supported | narrowed | removed |
 Do not edit files, stage changes, or invent missing behavior.
 Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsupportedClaims, confidence, recommendedWorkflow, notes.
 Context boundary:
-Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
 Use only the parent-assigned shard plus required checkout evidence files.
 Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
@@ -13,6 +13,6 @@ Do not edit files, stage changes, or rewrite docs.
 Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
 recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
 Context boundary:
-Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
 Use only the parent-assigned shard plus required checkout evidence files.
 Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
@@ -21,6 +21,6 @@ Do not edit files, stage changes, or propose broad rewrites.
 Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
 recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
 Context boundary:
-Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
 Use only the parent-assigned shard plus required checkout evidence files.
 Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
@@ -60,7 +60,12 @@ Treat the HTML comments under each template section as normative authoring guida
 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 lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
 Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
-Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists.
+Truth-doc prose style:
+- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.
+- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.
+- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
+- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
+- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references.
 Truth-doc shape repair review:
 - Truth Document may restructure only truth docs for the implemented behavior being documented.
 - repair shape in place only after the ownership review confirms the doc is the right bounded owner
@@ -32,6 +32,12 @@ Parent workflow:
   - No-update-needed rationale: why mapped truth is already current when no truth doc should change
   - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
 11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
+Truth-doc prose style:
+- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.
+- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.
+- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
+- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
+- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references.
 Topology review and repair:
 - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
 - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
@@ -11,26 +11,26 @@ Changed code reviewed:

 Sync Intent:
 - Changed code reviewed: src/auth/session.ts
- Affected route/truth owner: docs/truthmark/routes/areas.md
- Target truth docs: docs/truthmark/engineering/repository/bootstrap-routing.md
+- Affected route/truth owner: docs/truthmark/routes/areas/authentication.md
+- Target truth docs: docs/truthmark/engineering/behaviors/session-timeout.md
 - Intended update: Update session timeout behavior.
- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
+- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11
 - User-provided decisions/rationale: User rationale: session timeout behavior changed for internal implementation consistency
 - No-update-needed rationale: not applicable; mapped truth is stale
 - Blockers: none

 Ownership reviewed:
- docs/truthmark/routes/areas.md
+- docs/truthmark/routes/areas/authentication.md

 Truth docs updated:
- docs/truthmark/engineering/repository/bootstrap-routing.md
+- docs/truthmark/engineering/behaviors/session-timeout.md

 Decision/rationale captured:
- Placed user rationale in the mapped engineering truth doc under Engineering Decisions/Rationale.
+- Placed user rationale in the bounded authentication behavior truth doc under Engineering Decisions/Rationale.

 Evidence checked:
- Claim: Session timeout behavior is documented in the mapped repository truth doc.
-  Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
+- Claim: Session timeout behavior is documented in the bounded authentication behavior truth doc.
+  Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11
  Result: supported

 Notes:
@@ -41,11 +41,12 @@ Blocked report example:
 Truth Sync: blocked

 Reason:
- routing repair is not allowed
+- Changed code maps only to the provisional bootstrap route.

 Files requiring manual review:
- docs/truthmark/routes/areas.md
+- src/auth/**
+- docs/truthmark/routes/areas/repository.md

 Next action:
- update routing metadata and rerun Truth Sync
+- Run Truth Structure for src/auth/** before updating behavior truth.
 ```
@@ -13,8 +13,8 @@ jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
        with:
          node-version: 24.x
          cache: npm
@@ -0,0 +1,34 @@
+name: Deploy Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'site/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
+      - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4
@@ -1,9 +1,10 @@
 name: Publish

 on:
-  release:
-    types:
-      - published
+  push:
+    tags:
+      - 'release/**'
+  workflow_dispatch:

 permissions:
  contents: read
@@ -13,8 +14,8 @@ jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-node@v6
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
        with:
          node-version: 24.x
          registry-url: https://registry.npmjs.org
@@ -28,6 +28,6 @@ For every checked claim, classify the result as supported | narrowed | removed |
 Do not edit files, stage changes, or invent missing behavior.
 Return JSON only with keys: scope, filesReviewed, claimsChecked, evidence, unsupportedClaims, confidence, recommendedWorkflow, notes.
 Context boundary:
-Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
 Use only the parent-assigned shard plus required checkout evidence files.
 Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
@@ -27,6 +27,6 @@ Do not edit files, stage changes, or rewrite docs.
 Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
 recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
 Context boundary:
-Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
 Use only the parent-assigned shard plus required checkout evidence files.
 Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
@@ -35,6 +35,6 @@ Do not edit files, stage changes, or propose broad rewrites.
 Return JSON only with keys: scope, filesReviewed, findings, evidence, confidence, recommendedWorkflow, notes.
 recommendedWorkflow must be one of: none, truthmark-document, truthmark-structure.
 Context boundary:
-Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
 Use only the parent-assigned shard plus required checkout evidence files.
 Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.
@@ -60,7 +60,12 @@ Treat the HTML comments under each template section as normative authoring guida
 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 lane-specific sections: product truth says what must be true and why; engineering truth says how the repository currently realizes it.
 Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.
-Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists.
+Truth-doc prose style:
+- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.
+- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.
+- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
+- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
+- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references.
 Truth-doc shape repair review:
 - Truth Document may restructure only truth docs for the implemented behavior being documented.
 - repair shape in place only after the ownership review confirms the doc is the right bounded owner
@@ -32,6 +32,12 @@ Parent workflow:
   - No-update-needed rationale: why mapped truth is already current when no truth doc should change
   - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
 11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
+Truth-doc prose style:
+- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.
+- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.
+- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
+- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
+- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references.
 Topology review and repair:
 - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
 - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
@@ -11,26 +11,26 @@ Changed code reviewed:

 Sync Intent:
 - Changed code reviewed: src/auth/session.ts
- Affected route/truth owner: docs/truthmark/routes/areas.md
- Target truth docs: docs/truthmark/engineering/repository/bootstrap-routing.md
+- Affected route/truth owner: docs/truthmark/routes/areas/authentication.md
+- Target truth docs: docs/truthmark/engineering/behaviors/session-timeout.md
 - Intended update: Update session timeout behavior.
- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
+- Evidence to verify: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11
 - User-provided decisions/rationale: User rationale: session timeout behavior changed for internal implementation consistency
 - No-update-needed rationale: not applicable; mapped truth is stale
 - Blockers: none

 Ownership reviewed:
- docs/truthmark/routes/areas.md
+- docs/truthmark/routes/areas/authentication.md

 Truth docs updated:
- docs/truthmark/engineering/repository/bootstrap-routing.md
+- docs/truthmark/engineering/behaviors/session-timeout.md

 Decision/rationale captured:
- Placed user rationale in the mapped engineering truth doc under Engineering Decisions/Rationale.
+- Placed user rationale in the bounded authentication behavior truth doc under Engineering Decisions/Rationale.

 Evidence checked:
- Claim: Session timeout behavior is documented in the mapped repository truth doc.
-  Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas.md:11
+- Claim: Session timeout behavior is documented in the bounded authentication behavior truth doc.
+  Evidence: src/auth/session.ts:12 / docs/truthmark/routes/areas/authentication.md:11
  Result: supported

 Notes:
@@ -41,11 +41,12 @@ Blocked report example:
 Truth Sync: blocked

 Reason:
- routing repair is not allowed
+- Changed code maps only to the provisional bootstrap route.

 Files requiring manual review:
- docs/truthmark/routes/areas.md
+- src/auth/**
+- docs/truthmark/routes/areas/repository.md

 Next action:
- update routing metadata and rerun Truth Sync
+- Run Truth Structure for src/auth/** before updating behavior truth.
 ```
@@ -2,6 +2,13 @@

 **Your agents write code. Truthmark maintains human-facing, Git-reviewable documentation.**

+[![npm version](https://img.shields.io/npm/v/truthmark?color=cb3837&label=npm)](https://www.npmjs.com/package/truthmark)
+[![CI](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/merlinhu1/truthmark/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js >=24](https://img.shields.io/badge/node-%3E%3D24-339933?logo=node.js&logoColor=white)](package.json)
+
+[Website](https://merlinhu1.github.io/truthmark/) | [GitHub](https://github.com/merlinhu1/truthmark) | [User Guide](docs/user-guide.md)
+
 [🇺🇸 English](README.md) | [🇨🇳 简体中文](docs/readmes/README.zh.md) | [🇯🇵 日本語](docs/readmes/README.ja.md) | [🇰🇷 한국어](docs/readmes/README.ko.md) | [🇩🇪 Deutsch](docs/readmes/README.de.md) | [🇫🇷 Français](docs/readmes/README.fr.md) | [🇪🇸 Español](docs/readmes/README.es.md) | [🇧🇷 Português](docs/readmes/README.pt.md) | [🇷🇺 Русский](docs/readmes/README.ru.md) | [🇸🇦 العربية](docs/readmes/README.ar.md) | [🇮🇹 Italiano](docs/readmes/README.it.md) | [🇵🇱 Polski](docs/readmes/README.pl.md) | [🇹🇷 Türkçe](docs/readmes/README.tr.md) | [🇻🇳 Tiếng Việt](docs/readmes/README.vi.md) | [🇮🇩 Bahasa Indonesia](docs/readmes/README.id.md) | [🇬🇷 Ελληνικά](docs/readmes/README.el.md)

 ![Truthmark banner](docs/assets/truthmark-banner.png)
@@ -59,10 +66,12 @@ AI coding agents are incredible at writing code fast. But this speed creates a d

 ## 🎯 The Solution: Truthmark

-**Truthmark** installs a Git-native workflow layer into your repository. It fixes the part of AI development that usually breaks: helping the documentation stay aligned with the code.
+**Truthmark** installs a Git-native workflow layer into your repository. It fixes the part of AI development that usually breaks: keeping documentation aligned with code after the first draft.

 Instead of hoping humans and AI agents remember to update docs, Truthmark makes documentation a systematic, reviewable habit right inside your repo.

+Truthmark is not a one-shot docs generator. It is an ongoing truth-doc curation loop that keeps human-facing docs small, owned, evidence-backed, and reviewable as agents keep changing code.
+
 ### ✨ Why Truthmark is Unique

 Truthmark isn't just another documentation tool. It is deeply integrated into the AI workflow:
@@ -70,6 +79,7 @@ Truthmark isn't just another documentation tool. It is deeply integrated into th
 * **🚫 Zero Vendor Lock-in:** No hosted services, no hidden databases, no extra servers to operate.
 * **🌳 100% Git-Native:** Everything lives in your repository. The truth moves with your branch.
 * **🤝 Human-owned, agent-followed contract:** Maintainers own the repo contract; agents follow the installed instructions while coding.
+* **🧭 Ongoing truth curation:** Broad or messy docs are routed toward Structure instead of becoming giant catch-all files.
 * **✅ Trust Through Verification:** AI work becomes easier to trust because behavior-changing work includes a human-reviewable truth-doc decision or diff.

 ## 🔄 How It Works
@@ -122,6 +132,7 @@ Truth Structure is not a day-to-day command; it repairs routing or ownership onl
 | Human CLI | Gives maintainers setup, refresh, validation, and inspection commands. |
 | Installed agent guidance | Tells coding agents when to document, test, sync truth, audit, or stop for review. |
 | Explicit routing | Maps code areas to canonical truth docs. |
+| Durable truth curation | Keeps docs bounded, evidence-backed, and reviewable instead of letting them grow into catch-all files. |
 | Reviewable handoffs | Produces ordinary Git diffs for both code and truth docs. |
 | Local-first operation | Requires no hosted service, daemon, database, or MCP server. |
 | Safer write boundaries | Separates code-first, doc-first, read-only, and doc-only workflows. |
@@ -154,6 +165,8 @@ Not governance as ceremony. Governance as a simple question:

 Truthmark helps teams answer that with committed files, explicit routing, and reviewable diffs.

+Most AI tools can draft documentation. Truthmark keeps repository truth curated after the draft, after the next code change, and after the doc starts getting too broad.
+
 It is useful when you need:

 - less documentation drift
@@ -193,6 +206,8 @@ keep the result reviewable in Git

 The README is the storefront: fast context, quick start, and the core mental model.

+The [static website](https://merlinhu1.github.io/truthmark/) is the concise public introduction for GitHub Pages.
+
 For command-by-command usage, surface comparisons, supported platform details, configuration, routing, Portal, and examples, read the [Truthmark User Guide](docs/user-guide.md).

 ## Project status
@@ -0,0 +1,21 @@
+# Version 2.2.5
+
+Previous version: 2.2.4
+New version: 2.2.5
+Diff basis: release/2.2.4..HEAD plus working tree
+Version action: patch
+SemVer rationale: This release is a backward-compatible patch that corrects generated workflow surfaces, validation/report examples, and generated-surface diagnostics without changing public CLI command shape.
+
+Release payload:
+- Move generated Cursor workflow support from large `.cursor/rules` files to native Cursor Agent Skill packages under `.cursor/skills/truthmark-*` with colocated support resources.
+- Keep retired Gemini surfaces as manual-cleanup diagnostics while allowing `truthmark init` to auto-remove non-Gemini retired generated surfaces.
+- Prevent Truth Sync reports and examples from treating provisional `bootstrap-routing.md` as a completed behavior-update target.
+- Narrow Sync `candidateStaleTruthDocs` to signal-backed candidates instead of every indexed truth doc outside the impact set.
+
+User-facing release text:
+- Cursor installs now receive Truthmark workflows as Agent Skills under `.cursor/skills/truthmark-*`, while generated-surface checks and Sync validation avoid stale or over-broad workflow guidance.
+
+Verification:
+- `npx vitest run tests/agents/instructions.test.ts tests/agents/prompts.test.ts tests/agents/truth-check.test.ts tests/agents/truth-document.test.ts tests/agents/truth-sync.test.ts tests/templates/generated-surfaces.test.ts` passed.
+- `npx tsx src/cli/main.ts check --json` passed with no diagnostics after regenerating surfaces.
+- `npm run release:check` passed: lint, format, typecheck, 337 tests, build, package check, and audit.
@@ -0,0 +1,17 @@
+# Fix npm provenance publish trigger
+
+Version action: patch
+
+## PR Summary
+
+- Switch npm publishing from GitHub `release` events to `release/**` tag push events, with manual dispatch retained as an operator fallback.
+- Document that tag-triggered publishing keeps GitHub Actions OIDC provenance tied to a concrete source ref.
+
+## Release Note
+
+- Fix npm publishing provenance failures caused by release-event OIDC certificates missing `SourceRepositoryRef`.
+
+## Verification
+
+- `npm run release:check`
+- `node dist/main.js check --json`
@@ -0,0 +1,26 @@
+# Static Introduction Website
+
+Version action: none
+
+## PR Summary
+
+- Add a static introduction website under `site/` for GitHub Pages with original CSS-only visual design rather than copied README poster artwork.
+- Add a richer tabbed truth-doc storyboard that shows a new invariant, product-promise pressure, ownership splitting, and the final reviewer packet.
+- Add product-positioning sections for checkout-native operation, claim-level review, explicit route ownership, topology repair, repository-file authority, host-shaped agent guidance, and Git-reviewable handoff.
+- Remove copied poster assets from the site branch; the public page no longer depends on README banner images.
+- Add a Pages deployment workflow that publishes `site/**` after relevant pushes to `main` or manual dispatch.
+- Link the site from the root README and document that the site is presentation, not canonical repository truth.
+
+## Release Note
+
+- Truthmark now has a static GitHub Pages introduction site for public onboarding, with original visual design, a truth-doc curation storyboard, and broader repository-truth positioning.
+
+## Verification
+
+- Served `site/` locally with `python3 -m http.server`, captured Playwright screenshots, and validated the rendered HTML response with `curl` plus Python checks.
+- `/opt/data/bin/npm run test -- tests/package-files.test.ts tests/product-boundary.test.ts tests/truth/docs.test.ts` passed: 6 tests.
+- `/opt/data/bin/npm run check` passed: lint, typecheck, 337 tests, and build.
+- `/opt/data/bin/npm run package:check` passed: 4 tests.
+- `/opt/data/bin/npx tsx src/cli/main.ts check --json` passed with no diagnostics.
+- `/opt/data/bin/npx tsx src/cli/main.ts index --json` passed with no diagnostics.
+- `git diff --check` passed.
@@ -0,0 +1,23 @@
+# Version 2.2.6
+
+Previous version: 2.2.5
+New version: 2.2.6
+Diff basis: release/2.2.5-2..HEAD plus working tree
+Version action: patch
+SemVer rationale: This release is a backward-compatible patch that improves shipped workflow guidance for truth-doc prose without changing CLI command shape, config schema, or report contracts.
+
+Release payload:
+- Add compact professional prose guidance to Truth Document and Truth Sync so generated truth-doc edits avoid AI-style padding, keep one durable claim per bullet or line, and limit paragraphs to one or two short sentences.
+- Regenerate configured host workflow procedures for Codex, OpenCode, Claude Code, GitHub Copilot, Antigravity, and Cursor.
+- Record the compact-humanizer adaptation decision in product and engineering truth docs.
+- Emphasize ongoing truth-doc curation in the English README and product truth docs; localized README variants intentionally remain for a later translation pass.
+
+User-facing release text:
+- Truth Document and Truth Sync now guide agents toward plain professional truth-doc prose, avoiding AI-sounding filler without importing a token-heavy humanizer prompt or changing workflow contracts.
+- The README now presents ongoing truth-doc curation as Truthmark's main differentiator: keeping docs bounded, evidence-backed, and reviewable after each code change.
+
+Verification:
+- `npm run release:check` passed: lint, format check, typecheck, 337 tests, build, package check, and audit with 0 vulnerabilities.
+- `npx vitest run tests/product-boundary.test.ts tests/truth/docs.test.ts tests/package-files.test.ts` passed: 6 tests.
+- `npx tsx src/cli/main.ts check --json` passed with no diagnostics.
+- `npx tsx src/cli/main.ts index --json` passed with no diagnostics.
@@ -1,7 +1,7 @@
 ---
 status: active
 doc_type: architecture
-last_reviewed: 2026-06-12
+last_reviewed: 2026-06-26
 source_of_truth:
  - ../../README.md
  - ../truthmark/product/capabilities/agent-native-workflow-injection.md
@@ -33,6 +33,10 @@ Truthmark keeps repository documentation aligned with agent-made code changes so

 Canonical truth documents are human-facing Git-review artifacts. Human maintainers are the primary reviewers; agents write and maintain truth docs, but agents are not the only consumers.

+Truthmark's product value is ongoing truth-doc curation, not one-shot documentation generation.
+
+Truthmark keeps truth docs bounded, evidence-backed, and reviewable as agents continue changing code.
+
 Truth-doc structure, wording, and style must be friendly for humans to read and understand.

 Human-friendly truth docs:
@@ -56,6 +60,7 @@ Truthmark owns:
 - host-native agent workflow surfaces such as skills, prompts, commands, managed instruction blocks, and subagents
 - branch-local documentation checks, workflow indexes, impact summaries, context packs, and workflow state derived from the active checkout
 - write boundaries for read-only, documentation-write, route-write, code-write, and presentation-write workflows
+- the static GitHub Pages introduction site as marketing/onboarding presentation, not repository truth
 - optional CLI/package helpers that improve validation or setup without becoming required for normal agent workflow execution

 Truthmark workflows must remain operational from repository files alone. A design that blocks the agent workflow because a package, CLI, daemon, server, IDE plugin, or external service is missing is outside the product boundary.
@@ -86,6 +91,8 @@ Optional integrations are acceptable only when they preserve host-native agent w
 6. **Human review stays central.** Truthmark produces reviewable documentation changes, not silent approval or merge authority.
 7. **Local-first simplicity wins.** Add dependencies, services, or runtime layers only when they preserve the no-blockade repository-file workflow.
 8. **Truth docs stay human-friendly.** Truth docs must be structured and written for maintainers to review, scan, and understand before they are optimized for agent or machine consumption.
+9. **Curation beats generation.** Truthmark should route overgrown or mixed-owner docs toward Structure instead of rewarding more appended prose.
+10. **Presentation is not authority.** The static introduction website may present the product, but canonical behavior remains in README, routed truth docs, source, tests, and config.

 ## Required Product Boundary Check

@@ -107,6 +114,9 @@ A plan that cannot answer these questions is not ready for implementation.
 - Decision (2026-06-12): Repository rules cite this document so agents must check product boundaries before generating new designs or plans.
 - Decision (2026-06-12): Truthmark workflows must stay 100% operational from repository files and host-native agent surfaces; missing packages, CLIs, daemons, services, or plugins must not block normal workflow execution.
 - Decision (2026-06-12): Human-facing readability is part of the Truthmark product boundary for canonical truth documents.
+- Decision (2026-06-26): Ongoing truth-doc curation is a primary product value.
+  - Marketing should emphasize bounded ownership, evidence-backed updates, Git-reviewable docs, and Structure handoff for overgrown docs instead of generic documentation generation.
+- Decision (2026-06-26): The GitHub Pages site is a static marketing/onboarding surface, not a documentation hosting platform or source of repository truth.

 ## Maintenance Notes

@@ -8,7 +8,8 @@ last_reviewed: 2026-06-14

 This directory is an index for current truth docs organized by the configured Truthmark hierarchy.

-Engineering truth owns current realization, contracts, architecture, workflows, operations, and tests. Engineering lane docs describe how the repository currently implements and operates the behavior.
+- Engineering truth owns current realization, contracts, architecture, workflows, operations, and tests.
+- Engineering lane docs describe how the repository currently implements and operates the behavior.

 README.md files are indexes, not Truth Sync targets. Keep engineering truth in bounded behavior, contract, architecture, workflow, operations, and test docs.

@@ -22,7 +22,8 @@ It turns checkout evidence, route metadata, and source renderers into committed

 ## Current Implementation Behavior

-Truthmark is a local CLI and generated-surface renderer. It reads checkout files, normalizes configuration, parses route files, emits diagnostics, and writes configured workflow surfaces during init.
+- Truthmark is a local CLI and generated-surface renderer.
+- It reads checkout files, normalizes configuration, parses route files, emits diagnostics, and writes configured workflow surfaces during init.

 ## Boundaries

@@ -1,7 +1,7 @@
 ---
 status: active
 truth_kind: engineering-behavior
-last_reviewed: 2026-06-20
+last_reviewed: 2026-06-26
 ---

 # Check Diagnostics
@@ -16,11 +16,27 @@ It covers route coverage, lane shape, lane drift, traceability, frontmatter, gen

 ## Current Implementation Behavior

-`truthmark check` combines config, area routing, frontmatter, link, lane-shape, lane-drift, traceability, generated-surface, source-traceability, and freshness diagnostics. Missing product links for engineering behavior, workflow, and contract docs are review diagnostics only when the same routed area includes product truth evidence. Cross-lane route metadata is route-local: product `realized_by` links and engineering `realizes` links must target existing opposite-lane truth docs, but they do not have to be reciprocated by the target entry. Repeated route entries for the same truth document, kind, and lane merge their `realized_by`, `realizes`, and `depends_on` metadata before traceability validation; conflicting duplicate kinds or lanes are area-index errors.
+- `truthmark check` combines config, area routing, frontmatter, link, lane-shape, lane-drift, traceability, generated-surface, source-traceability, and freshness diagnostics.
+- Missing product links for engineering behavior, workflow, and contract docs are review diagnostics only when the same routed area includes product truth evidence.
+- Cross-lane route metadata is route-local.
+  - Product `realized_by` links and engineering `realizes` links must target existing opposite-lane truth docs.
+  - Relationship links do not have to be reciprocated by the target entry.
+- Repeated route entries for the same truth document, kind, and lane merge their `realized_by`, `realizes`, and `depends_on` metadata before traceability validation.
+- Conflicting duplicate kinds or lanes are area-index errors.

-Frontmatter diagnostics reject relationship metadata fields `realized_by`, `realizes`, and `depends_on` when they appear in truth document frontmatter. Relationship authority stays in fenced route YAML entries.
+- Frontmatter diagnostics reject relationship metadata fields `realized_by`, `realizes`, and `depends_on` when they appear in truth document frontmatter.
+- Relationship authority stays in fenced route YAML entries.

-Product truth doc structure validation enforces the `product-capability` shape. Product capability docs require capability sections for the capability promise, users and value, capability scope including boundary constraints and adjacent systems, current product behavior, acceptance criteria, product decisions, engineering realization links, and non-goals.
+- Product truth doc structure validation enforces the `product-capability` shape.
+- Product capability docs require capability sections for:
+  - capability promise
+  - users and value
+  - capability scope, including boundary constraints and adjacent systems
+  - current product behavior
+  - acceptance criteria
+  - product decisions
+  - engineering realization links
+  - non-goals

 ## Core Rules

@@ -33,6 +49,29 @@ Product truth doc structure validation enforces the `product-capability` shape.
 - Duplicate route entries for the same path, kind, and lane merge `realized_by`, `realizes`, and `depends_on` by unique sorted set.
 - Check reports structure and evidence only; it does not judge product strategy.

+## Behavior Scenarios
+
+#### Scenario: Generated surface drift is review-only
+
+- **GIVEN** a committed generated workflow surface differs from the current renderer output
+- **WHEN** `truthmark check` compares rendered surfaces with checked-in files
+- **THEN** it reports a `generated-surface` review diagnostic for the stale path
+- **AND** it does not mutate files during the check
+
+#### Scenario: Route relationship metadata stays in route YAML
+
+- **GIVEN** a truth document frontmatter block declares `realized_by`, `realizes`, or `depends_on`
+- **WHEN** `truthmark check` validates frontmatter
+- **THEN** it reports the relationship metadata as invalid frontmatter
+- **AND** keeps relationship authority in fenced route YAML entries
+
+#### Scenario: Duplicate route entries merge compatible relationships
+
+- **GIVEN** route files contain duplicate entries for the same truth document path, kind, and lane
+- **WHEN** Check validates route traceability
+- **THEN** it merges `realized_by`, `realizes`, and `depends_on` metadata by unique sorted set
+- **AND** conflicting duplicate kinds or lanes remain area-index errors.
+
 ## Flows And States

 - Check loads config and routed truth docs from the active checkout.
@@ -50,10 +89,14 @@ Product truth doc structure validation enforces the `product-capability` shape.

 ## Engineering Decisions

- Decision (2026-06-14): Wrong-lane content is a lane-drift diagnostic; missing product links for engineering behavior, workflow, and contract docs are review diagnostics only when routed area evidence indicates product truth context.
- Decision (2026-06-14): Downstream injected/default product truth supports `product-capability` only; boundary material belongs inside capability scope, acceptance criteria, and non-goals.
- Decision (2026-06-15): Duplicate route entries with the same path, kind, and lane are an additive relationship model; divergent relationship arrays merge instead of erroring so area-local route entries do not have to repeat the full relationship closure.
- Decision (2026-06-15): `realized_by` and `realizes` route metadata is route-local navigation metadata, not a canonical global graph, so check validates target existence and lane compatibility without requiring reciprocal edges.
+- Decision (2026-06-14): Wrong-lane content is a lane-drift diagnostic.
+  - Missing product links for engineering behavior, workflow, and contract docs are review diagnostics only when routed area evidence indicates product truth context.
+- Decision (2026-06-14): Downstream injected/default product truth supports `product-capability` only.
+  - Boundary material belongs inside capability scope, acceptance criteria, and non-goals.
+- Decision (2026-06-15): Duplicate route entries with the same path, kind, and lane are an additive relationship model.
+  - Divergent relationship arrays merge instead of erroring so area-local route entries do not have to repeat the full relationship closure.
+- Decision (2026-06-15): `realized_by` and `realizes` route metadata is route-local navigation metadata, not a canonical global graph.
+  - Check validates target existence and lane compatibility without requiring reciprocal edges.

 ## Rationale

@@ -71,13 +114,12 @@ Update when check categories, severity rules, lane audit behavior, or product ki

 ## Source References

- ../../../../src/checks/check.ts
- ../../../../src/checks/areas.ts
- ../../../../src/checks/decisions.ts
- ../../../../src/checks/frontmatter.ts
- ../../../../tests/checks/frontmatter.test.ts
- `src/checks/areas.ts`
- `src/checks/decisions.ts`
- `src/checks/frontmatter.ts`
- `tests/checks/frontmatter.test.ts`
- `src/output/diagnostic.ts`
+- src/checks/check.ts
+- src/checks/areas.ts
+- src/checks/decisions.ts
+- src/checks/frontmatter.ts
+- src/checks/generated-surfaces.ts
+- src/output/diagnostic.ts
+- tests/checks/check.test.ts
+- tests/checks/frontmatter.test.ts
+- tests/templates/generated-surfaces.test.ts
@@ -1,7 +1,7 @@
 ---
 status: active
 truth_kind: engineering-behavior
-last_reviewed: 2026-06-20
+last_reviewed: 2026-06-26
 ---

 # Init And Scaffold
@@ -44,10 +44,30 @@ Generated truth-doc frontmatter includes `truth_kind`.

 Generated truth-doc frontmatter does not include `doc_type` or `truth_lane`.

-`truthmark init` also removes retired generated-surface artifacts (for example `truthmark-preview` package files, retired Preview prompt/command adapters, and legacy `helper-manifest.yml`/`support/helper-policy.md`) when those paths are no longer part of current generated output.
+`truthmark init` removes auto-removable retired generated-surface artifacts when those paths are no longer part of current generated output.
+
+Auto-removable retired artifacts include:
+
+- `truthmark-preview` package files
+- retired non-Gemini Preview adapters
+- legacy `helper-manifest.yml` and `support/helper-policy.md` files
+
+Init leaves retired Gemini surfaces in place for manual cleanup:
+
+- `GEMINI.md`
+- `.gemini/**`
+
+Those files may contain user-owned instructions alongside old Truthmark injections.

 Generated truth-doc templates keep kind-specific and section-specific authoring comments in the template files.

+Engineering behavior templates include a `Behavior Scenarios` section after `Core Rules`:
+
+- Scenario blocks are optional and clarify normal, fallback, or compatibility-critical behavior.
+- Scenario bullets use `GIVEN`, `WHEN`, `THEN`, and optional `AND` labels.
+- Scenario guidance frames entries as current implemented truth rather than future requirements.
+- Scenario bullets do not replace source-backed behavior claims or Source References.
+
 Global diff-friendly authoring style lives in the Truth Document workflow procedure rather than in every template preamble:

 - Prefer one durable claim per bullet or line.
@@ -79,14 +99,39 @@ Capability docs own:

 - Scaffolded paths derive from `truthmark.workspace`.
 - Template filenames match `truth_kind` values.
+- Engineering behavior templates provide optional current-state scenario blocks for normal, fallback, or compatibility-critical behavior.
 - Fresh configs do not assume any AI host platform.
 - Global prose style guidance belongs in writer-facing workflow procedures, not every truth-doc template preamble.

+## Behavior Scenarios
+
+#### Scenario: Fresh config does not assume a host platform
+
+- **GIVEN** a repository uses the default generated Truthmark config
+- **WHEN** `truthmark init` creates or refreshes the scaffold
+- **THEN** `platforms` remains omitted by default
+- **AND** host-specific workflow surfaces require explicit platform configuration
+
+#### Scenario: Retired Gemini surfaces are preserved for manual cleanup
+
+- **GIVEN** a repository contains retired Gemini instruction or command surfaces
+- **WHEN** `truthmark init` removes auto-removable retired generated artifacts
+- **THEN** it leaves `GEMINI.md` and `.gemini/**` in place
+- **AND** check diagnostics tell maintainers to review stale Gemini guidance manually
+
+#### Scenario: Engineering behavior templates support compact scenarios
+
+- **GIVEN** Truthmark renders the editable `engineering-behavior.md` template
+- **WHEN** maintainers create or refresh truth-doc templates
+- **THEN** the template includes an optional `Behavior Scenarios` section after `Core Rules`
+- **AND** the guidance frames scenarios as current implemented truth rather than `SHALL`-style future requirements
+
 ## Flows And States

 - `truthmark init` creates or refreshes workspace scaffold files.
 - It renders current templates and generated host surfaces from source renderers.
- It removes retired generated-surface artifacts that are no longer part of current generated output.
+- It removes retired non-Gemini generated-surface artifacts that are no longer part of current generated output.
+- It leaves retired Gemini surfaces for manual cleanup.

 ## Contracts

@@ -102,13 +147,21 @@ Capability docs own:
 - Decision (2026-06-14): New scaffold targets do not create `docs/truthmark/truth` as the canonical target root.
 - Decision (2026-06-14): Editable template filenames match `truth_kind` values directly so generated docs do not point agents at legacy `*-doc.md` names.
 - Decision (2026-06-14): Init scaffolds routes, templates, product truth, and engineering truth at fixed workspace-derived paths rather than accepting route or template roots from config.
- Decision (2026-06-17): The default broad `repository` route is provisional bootstrap state; init creates a compact `bootstrap-routing.md` workflow handoff instead of a catch-all behavior overview so agents run Truth Structure before normal Sync on real touched code.
- Decision (2026-06-18): Fresh configs omit `platforms` by default. Truthmark does not infer Codex, OpenCode, or any other host from a fresh checkout; host-native workflow surfaces require explicit platform configuration.
+- Decision (2026-06-17): The default broad `repository` route is provisional bootstrap state.
+  - Init creates a compact `bootstrap-routing.md` workflow handoff instead of a catch-all behavior overview so agents run Truth Structure before normal Sync on real touched code.
+- Decision (2026-06-18): Fresh configs omit `platforms` by default.
+  - Truthmark does not infer Codex, OpenCode, or any other host from a fresh checkout; host-native workflow surfaces require explicit platform configuration.
+- Decision (2026-06-21): Init does not delete retired Gemini surfaces automatically; users remove stale injected Gemini guidance manually after reviewing `GEMINI.md` and `.gemini/**`.
+- Decision (2026-06-26): Engineering behavior templates may use compact scenario blocks for behavior clarity.
+  - Scenario guidance adopts the useful requirement/scenario shape from specification formats while preserving Truthmark's current-state, evidence-backed truth-doc role.
+  - The template avoids `SHALL`-style future requirements and does not require a scenario for every rule.

 ## Rationale

 Fixed workspace-derived scaffold paths keep Truthmark predictable while route files provide the semantic ownership layer.

+Optional scenario blocks make normal and fallback behavior easier to review in Git without turning truth docs into future-looking requirement specs.
+
 Keeping templates kind-specific and moving global prose style into workflow guidance reduces generated-template bloat.

 ## Non-Goals
@@ -116,6 +169,7 @@ Keeping templates kind-specific and moving global prose style into workflow guid
 - Init does not infer a preferred agent host.
 - Init does not create behavior truth for unknown code ownership beyond the provisional bootstrap routing handoff.
 - Init does not maintain a legacy `docs/truthmark/truth` tree.
+- Init does not delete retired Gemini instruction files automatically.

 ## Maintenance Notes

@@ -127,3 +181,4 @@ Update when init writes new files, changes default paths, changes template filen
 - ../../../../src/init/hierarchy.ts
 - ../../../../src/templates/init-files.ts
 - ../../../../tests/init/init-instructions.test.ts
+- ../../../../tests/init/truth-doc-templates.test.ts
@@ -1,7 +1,7 @@
 ---
 status: active
 truth_kind: engineering-contract
-last_reviewed: 2026-06-20
+last_reviewed: 2026-06-21
 ---

 # Generated Host Surfaces
@@ -18,25 +18,37 @@ It covers configured platform output paths, generated workflow files, managed in

 Truthmark renders workflow surfaces only for configured platforms. Legacy package artifacts and retired Preview adapters are explicitly retired.

- `truthmark init` removes obsolete generated files that are no longer in `renderGeneratedSurfaces(...)`, including `truthmark-preview` package contents, retired Preview prompt/command adapters, and legacy `helper-manifest.yml` and `support/helper-policy.md` files under host skill roots.
+- `truthmark init` removes obsolete generated files that are no longer in `renderGeneratedSurfaces(...)`.
+  - Removed obsolete files include `truthmark-preview` package contents.
+  - Removed obsolete files include retired non-Gemini Preview adapters.
+  - Removed obsolete files include legacy `helper-manifest.yml` and `support/helper-policy.md` files under host skill roots.
 - `truthmark check` reports missing, stale, or obsolete generated surfaces when render outputs and committed files differ.
+  - Stale Gemini surfaces are reported for manual cleanup rather than deleted by init.

-When `platforms` is omitted, fresh config does not assume a host platform; `truthmark init` still maintains instruction targets, but host-specific skill/prompt/command surfaces are opt-in through explicit `platforms` entries.
-Host skill packages carry canonical workflow entrypoints plus support files for full procedures, report templates, and subagent/lease guidance when the workflow uses subagents; generated helper manifest and helper policy files are intentionally not emitted.
-GitHub Copilot prompt files are lightweight workflow adapters for supported generated workflows: they point to the current host entrypoint and tell the agent not to invoke another Truthmark command from inside that entrypoint.
-Antigravity and Cursor rule files are flat rule surfaces that inline the workflow procedure and report template, omit the duplicate quick-procedure block, and do not reference package-local `support/` files that those hosts do not consume.
-Truth Preview is not generated as a skill package, prompt file, or command file for any host.
+- When `platforms` is omitted, fresh config does not assume a host platform.
+- `truthmark init` still maintains instruction targets, but host-specific skill/prompt/command surfaces are opt-in through explicit `platforms` entries.
+- Host skill packages carry canonical workflow entrypoints plus support files for full procedures, report templates, and subagent/lease guidance when the workflow uses subagents.
+- Generated helper manifest and helper policy files are intentionally not emitted.
+- GitHub Copilot prompt files are lightweight workflow adapters for supported generated workflows.
+  - They point to the current host entrypoint.
+  - They tell the agent not to invoke another Truthmark command from inside that entrypoint.
+- Cursor Agent Skills are generated as native project skill packages under `.cursor/skills/truthmark-*` with package-local support files.
+- Cursor Rules remain supported by Cursor as a platform concept.
+- Truthmark does not use `.cursor/rules` for its workflow surface because the Agent Skills directory is the better current native workflow representation.
+- Truth Preview is not generated as a skill package, prompt file, or command file for any host.

 ## Contract Surface

- Codex, OpenCode, Claude Code, GitHub Copilot, Antigravity, and Cursor skills/prompts/rules/agents
+- Codex, OpenCode, Claude Code, GitHub Copilot, Cursor, and Antigravity skills/prompts/rules/agents
 - `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md` managed blocks

 ## Platform Implementation References

- Antigravity support renders workflow rule files under `.antigravity/rules/truthmark-*.md`; implementation reference: Antigravity documentation entrypoint at <https://antigravity.google/docs>.
- Cursor support renders project rules under `.cursor/rules/truthmark-*.mdc` with Cursor frontmatter; implementation reference: Cursor Rules documentation at <https://cursor.com/docs/rules>.
- Gemini CLI support is retired. `GEMINI.md` and `.gemini/**` are treated as obsolete generated surfaces for cleanup and check diagnostics, not active host implementations.
+- Antigravity support renders workflow rule files under `.antigravity/rules/truthmark-*.md`.
+  - Implementation reference: Antigravity documentation entrypoint at <https://antigravity.google/docs>.
+- Cursor support renders Agent Skill project packages under `.cursor/skills/truthmark-*` with package-local `SKILL.md` and `support/` resources.
+  - Implementation reference: Cursor Agent Skills documentation at <https://cursor.com/docs/skills>.
+- Gemini CLI support is retired. `GEMINI.md` and `.gemini/**` are obsolete generated surfaces for check diagnostics and manual cleanup, not active host implementations.

 ## Inputs

@@ -46,7 +58,7 @@ Truth Preview is not generated as a skill package, prompt file, or command file

 ## Outputs

- Host-native workflow skill packages, compact prompt adapters, and flat Antigravity/Cursor rule surfaces
+- Host-native workflow skill packages, compact prompt adapters, and flat Antigravity rule surfaces
 - No generated Truth Preview skill package, prompt, or command
 - Procedure, report-template, and subagent/lease support files only when a workflow needs them
 - Managed instruction blocks with non-versioned refresh guidance
@@ -54,7 +66,7 @@ Truth Preview is not generated as a skill package, prompt file, or command file
 ## Errors And Diagnostics

 - `truthmark check` reports missing, stale, or obsolete generated surfaces.
- `truthmark init` removes retired managed artifacts when they are no longer rendered.
+- `truthmark init` removes retired non-Gemini managed artifacts when they are no longer rendered; retired Gemini files are left for manual cleanup.
 - Generated-surface freshness uses rendered-content comparison rather than package-version markers.

 ## Compatibility Rules
@@ -65,7 +77,8 @@ Truth Preview is not generated as a skill package, prompt file, or command file

 ## Versioning And Migration

- Retired generated files are removed during init instead of remaining as stale runtime guidance.
+- Retired non-Gemini generated files are removed during init instead of remaining as stale runtime guidance.
+- Retired Gemini files are diagnosed but not deleted automatically because repositories may have user-owned Gemini instructions beside old Truthmark injections.
 - Generated surfaces use non-versioned refresh wording; package versions are not runtime authority.

 ## Product Truth Links
@@ -75,16 +88,31 @@ Truth Preview is not generated as a skill package, prompt file, or command file
 ## Engineering Decisions

 - Decision (2026-06-14): Generated surfaces must preserve Truthmark as a workflow injector, not a runtime authority.
- Decision (2026-06-15): GitHub Copilot prompt files stay compact workflow adapters; Antigravity and Cursor rules are flat rendered rule bodies that carry procedure/report content directly.
- Decision (2026-06-20): Runtime surfaces must not carry redundant host-switch or support-file overhead. Cross-host invocation lists belong in human-facing docs or platform-reference contracts, native `SKILL.md` quick procedures do not repeat support-file read instructions already listed under Progressive disclosure, and flat Antigravity/Cursor rules do not reference nonexistent `support/` files.
+- Decision (2026-06-15): GitHub Copilot prompt files stay compact workflow adapters; Antigravity rules are flat rendered rule bodies that carry procedure/report content directly.
+- Decision (2026-06-21): Cursor support uses Agent Skill project packages under `.cursor/skills/truthmark-*`, not large dynamic `.cursor/rules` files.
+  - Cursor's current Agent Skills surface supplies description-based selection plus package-local support resources, so it is the single native Cursor workflow representation Truthmark uses.
+- Decision (2026-06-20): Runtime surfaces must not carry redundant host-switch or support-file overhead.
+  - Cross-host invocation lists belong in human-facing docs or platform-reference contracts.
+  - Native `SKILL.md` quick procedures do not repeat support-file read instructions already listed under Progressive disclosure.
+  - Flat Antigravity rules do not reference nonexistent `support/` files.
 - Decision (2026-06-18): Fresh configs do not assume Codex, OpenCode, or any other host platform. Host-specific surfaces are opt-in through explicit `platforms` entries.
- Decision (2026-06-18): Generated helper manifest and helper policy files are removed; optional validation commands remain in workflow metadata and report validation accepts manual fallback evidence.
- Decision (2026-06-20): Truth Preview generated host surfaces are retired. Truthmark no longer emits Preview skill packages, Copilot prompts, Antigravity rules, or Cursor rules; preview-like route/workflow selection remains internal advisory behavior rather than an installed workflow surface.
- Decision (2026-06-18): Truth Sync keeps bounded topology repair in the finish-time path; Sync runs or applies Truth Structure-style repair when safe and scoped, and hands off only unsafe or ambiguous topology work.
+- Decision (2026-06-18): Generated helper manifest and helper policy files are removed.
+  - Optional validation commands remain in workflow metadata.
+  - Report validation accepts manual fallback evidence.
+- Decision (2026-06-20): Truth Preview generated host surfaces are retired.
+  - Truthmark no longer emits Preview skill packages, Copilot prompts, Antigravity rules, or Cursor rules.
+  - Preview-like route/workflow selection remains internal advisory behavior rather than an installed workflow surface.
+- Decision (2026-06-18): Truth Sync keeps bounded topology repair in the finish-time path.
+  - Sync runs or applies Truth Structure-style repair when safe and scoped.
+  - Sync hands off only unsafe or ambiguous topology work.
+- Decision (2026-06-21): Init does not delete retired Gemini surfaces automatically.
+  - Check diagnostics identify obsolete `GEMINI.md` and `.gemini/**` files so users can remove stale injected Gemini guidance themselves.

 ## Rationale

-Host-native skill packages preserve progressive disclosure for agents that package skill directories. Compact prompt adapters avoid duplicating full workflow bodies, while flat Antigravity/Cursor rules inline only the procedure/report body those rule hosts can load directly.
+- Host-native skill packages preserve progressive disclosure for agents that package skill directories.
+- Compact prompt adapters avoid duplicating full workflow bodies, while flat Antigravity rules inline only the procedure/report body that rule host can load directly.
+- Cursor now uses Agent Skill packages because that current native Cursor surface supports description-based selection and package-local resources.

 ## Non-Goals

@@ -1,7 +1,7 @@
 ---
 status: active
 truth_kind: engineering-operations
-last_reviewed: 2026-06-20
+last_reviewed: 2026-06-26
 ---

 # Release Automation
@@ -16,11 +16,22 @@ It covers GitHub workflow triggers, verification steps, and generated GitHub Act

 ## Current Implementation Behavior

-Release and CI behavior is implemented through checked-in GitHub workflow files and the GitHub Action template renderer.
+Release, CI, GitHub Pages deployment, and repository-readiness automation are implemented through checked-in GitHub workflow files and GitHub repository settings.
+
+The npm publish workflow runs from `release/**` tag push events, with manual `workflow_dispatch` as an operator fallback. Tag-triggered publishing keeps the GitHub Actions OIDC signing certificate tied to a concrete `refs/tags/...` source ref for npm provenance verification.
+
+The GitHub Pages workflow deploys the committed static introduction site from `site/**` after pushes to `main` that change the site or Pages workflow.
+
+CodeQL is handled by GitHub's default setup for this repository.
+
+Checked-in advanced CodeQL workflow configuration is intentionally absent while default setup is enabled.
+
+Dependency-update monitoring is managed by existing GitHub repository configuration outside this PR's checked-in workflow changes.

 ## Operational Surface

 - GitHub Actions workflows under `.github/workflows/**`
+- static introduction site files under `site/**`
 - GitHub Action template rendering in `src/templates/github-action.ts`

 ## Runtime Topology
@@ -29,7 +40,9 @@ Automation runs in GitHub Actions. There is no Truthmark daemon or persistent ru

 ## Configuration

- GitHub workflow YAML files define CI and release triggers.
+- GitHub workflow YAML files define CI, release, and Pages deployment triggers.
+- Checked-in workflow actions are pinned to full commit SHAs, with inline comments preserving the upstream action version tag used to choose each SHA.
+- GitHub repository settings own CodeQL default setup and existing dependency-update monitoring.
 - `src/templates/github-action.ts` owns generated GitHub Action template behavior.

 ## Permissions
@@ -41,6 +54,7 @@ This doc does not add permissions beyond those source files.
 ## Deployment And Rollback

 - Workflow changes deploy when repository workflow files are committed to the target branch.
+- Static introduction site changes deploy through GitHub Pages after they merge to `main`.
 - Rollback is a normal Git revert or follow-up workflow-file change.

 ## Availability And Observability
@@ -55,6 +69,11 @@ This doc does not add permissions beyond those source files.
 ## Engineering Decisions

 - Decision (2026-06-14): Release automation truth is engineering/operational truth because it describes current repository mechanics.
+- Decision (2026-06-26): GitHub Pages deploys only the committed static introduction site under `site/**`.
+  - The site is a presentation artifact; Markdown truth docs remain canonical.
+- Decision (2026-06-26): Repository-readiness checks stay on existing GitHub-native configuration unless a checked-in workflow is explicitly needed.
+  - CodeQL default setup covers code scanning without a checked-in advanced workflow.
+  - Existing GitHub repository configuration covers dependency-update monitoring.

 ## Rationale

@@ -67,11 +86,14 @@ Release automation is documented as operations truth because failures, permissio

 ## Maintenance Notes

-Update when CI triggers, release prerequisites, publish steps, or action templates change.
+Update when CI triggers, release prerequisites, publish steps, Pages deployment steps, checked-in readiness scans, or action templates change.

 ## Source References

 - ../../../../.github/workflows/ci.yml
+- ../../../../.github/workflows/pages.yml
 - ../../../../src/templates/github-action.ts
+- ../../../../site/index.html
 - `.github/workflows/**`
+- `site/**`
 - `src/templates/github-action.ts`
@@ -1,6 +1,6 @@
 ---
 status: active
-last_reviewed: 2026-06-14
+last_reviewed: 2026-06-26
 ---

 # Repository Truth Docs
@@ -11,8 +11,12 @@ README.md files are indexes, not Truth Sync targets. Keep bounded truth in leaf

 Current leaf docs:

- [Overview](overview.md)
+- [Repository Bootstrap Routing](bootstrap-routing.md) — provisional broad-route handoff for fresh or under-structured repositories.
+- [Repository Intelligence](repository-intelligence.md) — RepoIndex, RouteMap, ImpactSet, evidence, freshness, and WorkflowState behavior.
+- [Repository Overview](overview.md) — guardrail that prevents broad repository overviews from becoming catch-all implementation truth.

 ## Source References

- ../../routes/areas/repository.md
+- docs/truthmark/engineering/repository/bootstrap-routing.md
+- docs/truthmark/engineering/repository/repository-intelligence.md
+- docs/truthmark/engineering/repository/overview.md
@@ -1,7 +1,7 @@
 ---
 status: active
 truth_kind: engineering-workflow
-last_reviewed: 2026-06-17
+last_reviewed: 2026-06-26
 ---

 # Repository Bootstrap Routing
@@ -19,7 +19,8 @@ It does not own implementation behavior under that code surface.

 ## Current Implementation Behavior

-The scaffold creates this provisional bootstrap handoff only when a default broad route needs a canonical owner. Agents use it as a signal to run Truth Structure and create bounded routes before normal Truth Sync, not as a place to accumulate implementation claims.
+- The scaffold creates this provisional bootstrap handoff only when a default broad route needs a canonical owner.
+- Agents use it as a signal to run Truth Structure and create bounded routes before normal Truth Sync, not as a place to accumulate implementation claims.

 ## Product Truth Links

@@ -39,7 +40,8 @@ The scaffold creates this provisional bootstrap handoff only when a default broa

 ## Execution Model

-Run Truth Structure before normal Truth Sync when real code changes touch only this broad route. Truth Structure should create or repair bounded areas first; Truth Sync should then update the bounded owner docs.
+- Run Truth Structure before normal Truth Sync when real code changes touch only this broad route.
+- Truth Structure should create or repair bounded areas first; Truth Sync should then update the bounded owner docs.

 ## Steps

@@ -64,7 +66,8 @@ If ownership cannot be inferred safely, stop and report manual-review files inst

 ## Rationale

-Scoped ownership keeps agent context close to affected files and prevents broad default docs from absorbing unrelated behavior. This preserves agent-native truth maintenance without adding a token-heavy discovery layer.
+- Scoped ownership keeps agent context close to affected files and prevents broad default docs from absorbing unrelated behavior.
+- This preserves agent-native truth maintenance without adding a token-heavy discovery layer.

 ## Non-Goals

@@ -78,5 +81,6 @@ Keep this doc short. When a repository has real bounded routes, prefer updating

 ## Source References

- ../../routes/areas/repository.md
- ../../../../.truthmark/config.yml
+- docs/truthmark/engineering/behaviors/init-and-scaffold.md
+- src/templates/init-files.ts
+- .truthmark/config.yml
@@ -1,111 +1,90 @@
 ---
 status: active
 truth_kind: engineering-behavior
-last_reviewed: 2026-06-20
+last_reviewed: 2026-06-26
 ---

 # Repository Overview

 ## Purpose

-<!--
-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 References rather than prose-only assertion.
-->
-
-Describe why the default repository behavior surface exists and what outcome it protects.
+This doc records the repository-directory guardrail that broad repository docs are indexes or handoffs, not catch-all implementation truth.

 ## Scope

-<!--
-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.
-->
+It covers the repository truth-doc directory shape and the handoff away from legacy broad overview ownership.

-This bounded leaf truth doc owns the default repository behavior surface created by Truthmark.
-
-This doc was created from the editable engineering-behavior template at docs/truthmark/templates/engineering-behavior.md.
+It does not own implementation behavior under `src/**`, route-map behavior, or repository-intelligence output details.

 ## Current Implementation 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 References.
-->
-
- Document current behavior here when implementation changes make repository truth incomplete.
+- Truthmark no longer treats this file as the default behavior owner for broad repository code surfaces.
+- Init uses `engineering/repository/bootstrap-routing.md` as the provisional broad-route handoff when a fresh repository needs initial routeability.
+- Normal behavior truth belongs in bounded route-owned leaf docs after Truth Structure identifies the durable owner.
+- Repository-intelligence behavior lives in `engineering/repository/repository-intelligence.md`.
+- README files in truth-doc directories remain indexes instead of Truth Sync targets.

 ## Core Rules

-<!--
-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.
-->
+- Do not append unrelated implementation behavior to this overview.
+- Use `bootstrap-routing.md` when the repository still needs a provisional broad-route handoff.
+- Use bounded route-owned truth docs for real implementation behavior.
+- Use `repository-intelligence.md` for RepoIndex, RouteMap, ImpactSet, evidence, freshness, and WorkflowState behavior.

- Truth README files are indexes; behavior truth belongs in bounded leaf docs.
+## Behavior Scenarios
+
+#### Scenario: Broad default routing does not expand the overview
+
+- **GIVEN** a real code change maps only to a provisional broad repository route
+- **WHEN** Truth Sync cannot identify a bounded truth owner safely
+- **THEN** agents run or recommend Truth Structure before updating behavior truth
+- **AND** they do not append implementation claims to this overview
+
+#### Scenario: Repository truth docs stay indexable by bounded owner
+
+- **GIVEN** a maintainer opens the repository truth-doc directory
+- **WHEN** they choose a target truth doc for repository behavior
+- **THEN** the directory index points to bounded leaf docs and bootstrap handoffs
+- **AND** this overview remains a guardrail against catch-all behavior prose

 ## Flows And States

-<!--
-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.
-->
-
- None beyond current behavior.
+- None beyond the broad-overview-to-bounded-owner handoff described above.

 ## 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; link to it when contract ownership lives elsewhere.
-->
-
- External contracts should link to the nearest canonical contract doc when one exists.
+- Route metadata and check diagnostics are owned by `docs/truthmark/engineering/contracts/config-route-and-check-contracts.md`.
+- Repository-intelligence JSON contracts are owned by `docs/truthmark/engineering/contracts/config-route-and-check-contracts.md`.

 ## Product Truth Links

- None.
+- None. This is an internal engineering guardrail.

 ## Engineering Decisions

-<!--
-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 (2026-06-14): Truth README files are indexes; behavior truth belongs in bounded leaf docs.
+- Decision (2026-06-26): The repository overview is a guardrail against catch-all truth ownership, not the default behavior owner.
+  - Init creates `bootstrap-routing.md` for provisional broad routes.
+  - Truth Structure creates or repairs bounded owners before normal Truth Sync writes behavior details.

 ## Rationale

-<!--
-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.
-->
+Broad overview docs tend to accumulate unrelated behavior and become hard to review in Git.

-Bounded leaf docs keep agent context focused and prevent large products from accumulating unreviewable feature manuals.
+Keeping this file as a narrow guardrail preserves the old path's intent while directing real behavior to bounded owners.

 ## Non-Goals

-<!--
-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.
-->
-
- This doc is not a catch-all for unrelated repository behavior.
+- This doc is not a catch-all for repository behavior.
+- This doc is not a route-map, impact, or workflow-state behavior owner.
+- This doc is not a product capability or external contract.

 ## Maintenance Notes

-<!--
-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.
-->
-
- Update this doc when routed implementation changes alter current behavior, rules, contracts, or decisions.
+Update this doc only when repository-directory ownership, bootstrap handoff behavior, or broad-overview retirement behavior changes.

 ## Source References

- ../../routes/areas/repository.md
+- docs/truthmark/engineering/repository/bootstrap-routing.md
+- docs/truthmark/engineering/repository/repository-intelligence.md
+- docs/truthmark/engineering/behaviors/init-and-scaffold.md
+- docs/truthmark/engineering/repository/README.md
@@ -1,7 +1,7 @@
 ---
 status: active
 truth_kind: engineering-behavior
-last_reviewed: 2026-06-20
+last_reviewed: 2026-06-26
 ---

 # Repository Intelligence
@@ -16,17 +16,52 @@ It covers RepoIndex, RouteMap, ImpactSet, evidence validation, freshness, and Wo

 ## Current Implementation Behavior

-RepoIndex and RouteMap are derived from the active checkout. They preserve repository metadata, discovered files, truth docs, test files, route lane metadata, and route-local relationship metadata. RouteMap emits duplicate truth document entries with the same path, kind, and lane as one relationship view whose `realized_by`, `realizes`, and `depends_on` metadata is merged by unique sorted set. RepoIndex derives truth-doc lane and doc type from `truth_kind` when canonical truth docs omit explicit `truth_lane` and `doc_type` frontmatter.
+- RepoIndex and RouteMap are derived from the active checkout.
+- They preserve repository metadata, discovered files, truth docs, test files, route lane metadata, and route-local relationship metadata.
+- RouteMap emits duplicate truth document entries with the same path, kind, and lane as one relationship view whose `realized_by`, `realizes`, and `depends_on` metadata is merged by unique sorted set.
+- RepoIndex derives truth-doc lane and doc type from `truth_kind` when canonical truth docs omit explicit `truth_lane` and `doc_type` frontmatter.

-Repository intelligence is language-neutral workflow context, not a language-semantic code index. Truthmark does not maintain import graphs, export lists, public-symbol tables, or language-specific symbol validation. Agents inspect source code directly; these artifacts guide routing, context selection, verification planning, and write boundaries without overriding source files, route files, truth docs, or workflow write boundaries.
+- Repository intelligence is language-neutral workflow context, not a language-semantic code index.
+- Truthmark does not maintain import graphs, export lists, public-symbol tables, or language-specific symbol validation.
+- Agents inspect source code directly.
+- These artifacts guide routing, context selection, verification planning, and write boundaries without overriding source files, route files, truth docs, or workflow write boundaries.

-ImpactSet remains the branch-diff routing handoff for changed files, affected routes, affected truth docs, affected tests, and diagnostics. It derives affected routes from route code surfaces and truth-doc ownership, derives affected tests from changed test paths and path/name hints, and reports diagnostics for unmapped functional-code changes. It does not report TypeScript public-symbol changes or use TypeScript/JavaScript import parsing to infer affected tests.
+- ImpactSet remains the branch-diff routing handoff for changed files, affected routes, affected truth docs, affected tests, and diagnostics.
+- It derives affected routes from route code surfaces and truth-doc ownership, derives affected tests from changed test paths and path/name hints, and reports diagnostics for unmapped functional-code changes.
+- It does not report TypeScript public-symbol changes or use TypeScript/JavaScript import parsing to infer affected tests.

-WorkflowState is the workflow-scoped advisory handoff for helper readiness, a workflow card, write-boundary suggestions, target truth docs, optional helper commands, review checklist, compact affected-test guidance, diagnostics, next steps, and report sections. The advisory card presents affected files, likely route owners, suggested truth docs, open questions, and skipped optional-helper status so helper output remains review material rather than repository authority. Workflow applicability uses context-shaped states such as `ready`, `needs_manual_review`, and `needs_routing_review`; diagnostics or missing route ownership produce open questions and manual handoff guidance instead of making the CLI the arbiter. `truthmark-sync` includes `Sync Intent` in its report sections as a transient pre-write checklist and keeps affected truth docs in `targetTruthDocs` for review focus. Sync action context separates `primaryTruthDocs`, `candidateStaleTruthDocs`, and `routeFiles`: agents start with impacted route owners, while indexed canonical truth docs outside the impact set remain candidate stale-truth repair targets that require checkout evidence and a recorded reason before being touched. The standalone ContextPack handoff is retired; agents use workflow status plus impact as optional guidance and continue with direct checkout inspection when helpers are skipped or unavailable. These outputs do not emit source-file or truth-doc body contents.
+- WorkflowState is the workflow-scoped advisory handoff for:
+  - helper readiness
+  - a workflow card
+  - write-boundary suggestions
+  - target truth docs
+  - optional helper commands
+  - review checklist
+  - compact affected-test guidance
+  - diagnostics
+  - next steps
+  - report sections
+- The advisory card presents affected files, likely route owners, suggested truth docs, open questions, and skipped optional-helper status so helper output remains review material rather than repository authority.
+- Workflow applicability uses context-shaped states such as `ready`, `needs_manual_review`, and `needs_routing_review`.
+- Diagnostics or missing route ownership produce open questions and manual handoff guidance instead of making the CLI the arbiter.
+- `truthmark-sync` includes `Sync Intent` in its report sections as a transient pre-write checklist and keeps affected truth docs in `targetTruthDocs` for review focus.
+- Sync action context separates `primaryTruthDocs`, `candidateStaleTruthDocs`, and `routeFiles`.
+- Agents start with impacted route owners.
+- Stale candidates are included only when a concrete signal exists.
+- Stale-candidate signals include freshness diagnostics naming a truth doc.
+- Stale-candidate signals include route relationships through `realized_by`, `realizes`, or `depends_on`.
+- Stale-candidate signals include truth docs whose `source_of_truth` references changed files.
+- Stale-candidate signals include changed route metadata and changed linked counterpart docs.
+- When no signal exists, `candidateStaleTruthDocs` is empty; agents may still inspect another document when direct checkout evidence reveals a stale claim.
+- The standalone ContextPack handoff is retired.
+- Agents use workflow status plus impact as optional guidance and continue with direct checkout inspection when helpers are skipped or unavailable.
+- These outputs do not emit source-file or truth-doc body contents.

-Evidence validation checks repository containment, referenced file or glob existence, line spans, and `sha256:` content hashes. Evidence `symbol` metadata, when present in an evidence YAML block, is non-normative metadata and is not validated through TypeScript-specific parsing.
+- Evidence validation checks repository containment, referenced file or glob existence, line spans, and `sha256:` content hashes.
+- Evidence `symbol` metadata, when present in an evidence YAML block, is non-normative metadata and is not validated through TypeScript-specific parsing.

-Generated-surface diagnostics are checkout-derived repository intelligence for the installed workflow runtime. `truthmark check` compares rendered generated surfaces with committed files and reports missing or stale generated host-native skill package files so skill-directory resources stay colocated with `SKILL.md`.
+- Generated-surface diagnostics are checkout-derived repository intelligence for the installed workflow runtime.
+- `truthmark check` compares rendered generated surfaces with committed files and reports missing or stale generated host-native skill package files so skill-directory resources stay colocated with `SKILL.md`.

 ## Core Rules

@@ -34,6 +69,29 @@ Generated-surface diagnostics are checkout-derived repository intelligence for t
 - WorkflowState and ImpactSet expose paths, metadata, diagnostics, and checklists without embedding source-file or truth-doc bodies.
 - Route relationships remain route-local metadata.

+## Behavior Scenarios
+
+#### Scenario: Impact maps branch changes to review focus
+
+- **GIVEN** a branch changes source, test, route, or truth-document paths
+- **WHEN** Truthmark builds an ImpactSet for the branch
+- **THEN** it reports affected routes, affected truth docs, affected tests, and unmapped functional-code diagnostics
+- **AND** it does not infer TypeScript public-symbol changes through language import parsing
+
+#### Scenario: Workflow status keeps stale candidates signal-based
+
+- **GIVEN** a changed file maps to primary truth docs and no concrete stale-truth signal names another doc
+- **WHEN** Sync action context is built
+- **THEN** `candidateStaleTruthDocs` remains empty
+- **AND** agents may still inspect another document only when direct checkout evidence reveals a stale claim
+
+#### Scenario: Evidence validation stays repository-contained
+
+- **GIVEN** truth evidence names a repository path, glob, line span, or `sha256:` hash
+- **WHEN** Truthmark validates evidence
+- **THEN** it checks repository containment and referenced file or glob existence
+- **AND** it treats optional `symbol` metadata as non-normative metadata rather than TypeScript-specific proof
+
 ## Flows And States

 - RepoIndex and RouteMap are built from committed repository files.
@@ -54,11 +112,19 @@ Generated-surface diagnostics are checkout-derived repository intelligence for t

 - Decision (2026-06-14): Repository intelligence is derived context, not hidden memory or off-repo authority.
 - Decision (2026-06-15): Repository intelligence is a language-neutral workflow helper, not a semantic code index; TypeScript-specific import/export/public-symbol analysis is not part of the public contract.
- Decision (2026-06-15): The standalone ContextPack handoff is retired; agents use `truthmark workflow status --workflow <workflow> [--base <ref>] --json` for optional workflow-scoped guidance and `truthmark impact --base <ref> --json` for branch-diff routing.
- Decision (2026-06-16): `workflow status` is status/debug/handoff only; Truthmark does not expose a `workflow instructions` command and generated workflows must remain usable from committed repository files without live CLI preflight.
- Decision (2026-06-17): WorkflowState presents optional helper output as an advisory workflow card with affected files, likely route owners, suggested truth docs, open questions, skipped helper status, `reviewChecklist`, and `evidencePrompts`; it does not expose retired enforcement-shaped names such as `checks.required`, the old gate alias, or `requiredEvidence`.
+- Decision (2026-06-15): The standalone ContextPack handoff is retired.
+  - Agents use `truthmark workflow status --workflow <workflow> [--base <ref>] --json` for optional workflow-scoped guidance and `truthmark impact --base <ref> --json` for branch-diff routing.
+- Decision (2026-06-16): `workflow status` is status/debug/handoff only.
+  - Truthmark does not expose a `workflow instructions` command and generated workflows must remain usable from committed repository files without live CLI preflight.
+- Decision (2026-06-17): WorkflowState presents optional helper output as an advisory workflow card.
+  - The advisory card includes affected files, likely route owners, suggested truth docs, open questions, skipped helper status, `reviewChecklist`, and `evidencePrompts`.
+  - It does not expose retired enforcement-shaped names such as `checks.required`, the old gate alias, or `requiredEvidence`.
 - Decision (2026-06-16): Sync Intent is a transient report-section checklist exposed through workflow/report surfaces and WorkflowState report sections; it is not repository-intelligence state or a persisted plan.
- Decision (2026-06-17): Generated-surface freshness includes host-native package diagnostics; these diagnostics are review output and do not add hooks, live services, duplicate workflow packages, or mandatory workflow preflight execution.
+- Decision (2026-06-17): Generated-surface freshness includes host-native package diagnostics.
+  - These diagnostics are review output and do not add hooks, live services, duplicate workflow packages, or mandatory workflow preflight execution.
+- Decision (2026-06-21): Sync `candidateStaleTruthDocs` stays signal-based.
+  - WorkflowState does not enumerate every indexed truth doc outside the impact set.
+  - It returns an empty candidate list unless freshness, relationships, source references, changed route metadata, or changed linked docs indicate a possible stale-truth repair.

 ## Rationale

@@ -76,21 +142,17 @@ Update when index, route-map, impact, evidence, freshness, or workflow-state out

 ## Source References

- ../../../../src/repo-index/build.ts
- ../../../../src/repo-index/file-tree.ts
- ../../../../src/repo-index/route-map.ts
- ../../../../src/repo-index/types.ts
- ../../../../src/impact/build.ts
- ../../../../src/impact/types.ts
- ../../../../src/evidence/validate.ts
- ../../../../src/workflow-state/action-context.ts
- ../../../../src/workflow-state/build.ts
- ../../../../src/workflow-state/types.ts
- ../../../../src/checks/generated-surfaces.ts
- ../../../../tests/workflow-state/build.test.ts
- `src/repo-index/build.ts`
- `src/repo-index/file-tree.ts`
- `src/repo-index/route-map.ts`
- `src/repo-index/types.ts`
- `src/impact/build.ts`
- `src/workflow-state/build.ts`
+- src/repo-index/build.ts
+- src/repo-index/file-tree.ts
+- src/repo-index/route-map.ts
+- src/repo-index/types.ts
+- src/impact/build.ts
+- src/impact/types.ts
+- src/evidence/validate.ts
+- src/workflow-state/action-context.ts
+- src/workflow-state/build.ts
+- src/workflow-state/types.ts
+- src/checks/generated-surfaces.ts
+- tests/impact/build.test.ts
+- tests/evidence/validate.test.ts
+- tests/workflow-state/build.test.ts
@@ -1,7 +1,7 @@
 ---
 status: active
 truth_kind: engineering-workflow
-last_reviewed: 2026-06-20
+last_reviewed: 2026-06-26
 ---

 # Installed Workflow Runtime
@@ -50,12 +50,18 @@ GitHub Copilot prompts and top-level managed instruction blocks stay thin:
 - They point to host-native workflow entrypoints when a host skill package exists.
 - They do not embed full workflow bodies or cross-host invocation lists.

-Antigravity and Cursor rule files are flat host rule surfaces:
+Antigravity rule files remain flat host rule surfaces:

- They inline the workflow procedure and report template because those hosts do not consume the package-local `support/` directory model.
+- They inline the workflow procedure and report template because that host does not consume the package-local `support/` directory model.
 - They omit the duplicate quick-procedure block and do not reference nonexistent `support/` files.
 - They keep only host-local invocation framing and do not embed cross-host invocation lists.

+Cursor Agent Skills are generated as project skill packages under `.cursor/skills/truthmark-*`:
+
+- They use Cursor's current Agent Skills model rather than `.cursor/rules` dynamic rule files.
+- `SKILL.md` carries the description that lets Cursor select the workflow automatically when relevant and supports manual `/` invocation.
+- Package-local `support/procedure.md`, `support/report-template.md`, and any lease guidance stay colocated with the Cursor skill.
+
 Generated-surface checks report missing or stale configured host-native skill package files.

 Workflow manifest entries use review-oriented questions that surface as a WorkflowState `reviewChecklist`.
@@ -86,11 +92,13 @@ Truth Sync performs decision context capture from the current task conversation:
 - Supported context is placed in the correct product or engineering truth lane.
 - The report records whether context was placed, skipped because none was provided, or handed off for manual review.

-Truth Document procedures tell agents to write diff-friendly truth docs:
+Truth Document and Truth Sync procedures tell agents to write professional, readable truth docs without importing a full external writing prompt:

- Prefer one durable claim per bullet or line.
- Keep paragraphs to one or two short sentences.
- Use bullets or tables for rules, criteria, fields, files, and lists.
+- Prefer specific current-state claims over promotional, symbolic, or generic significance language.
+- Avoid common AI-writing tells such as vague expert attribution, generic upbeat conclusions, and stock words like "pivotal", "crucial", "underscores", "serves as", "stands as", "showcases", and "landscape".
+- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.
+- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.
+- Rewrite dense or formulaic prose only when readability improves without removing scope, evidence, decisions, or source references.

 Truth Structure stays topology-first:

@@ -131,6 +139,12 @@ Truth Sync generated procedures and report templates include a transient Sync In
 - no-update-needed rationale
 - blockers

+Truth Sync successful report examples target bounded behavior ownership rather than the provisional bootstrap handoff:
+
+- The successful session-timeout example uses a bounded authentication route and `engineering/behaviors/session-timeout.md`.
+- The provisional `bootstrap-routing.md` document is represented only as a blocked topology case that tells agents to run Truth Structure before updating behavior truth.
+- `truthmark validate sync-report` rejects completed reports that list `bootstrap-routing.md` as an updated or target truth doc.
+
 Optional CLI repository-intelligence helpers are compact advisory cards:

 - `workflow status` reports affected files, likely route owners, suggested truth docs, open questions, skipped helper status, and compact write-boundary suggestions.
@@ -185,17 +199,32 @@ Committed workflow files are the runtime contract. The CLI installs and validate
 ## Engineering Decisions

 - Decision (2026-06-14): Product and engineering truth remain separate generated-workflow lanes for truth creation, structure, audit, and cross-lane ownership checks.
- Decision (2026-06-17): Routine code-first Truth Sync uses a product-truth decision instead of a full lane-classification gate; product truth is opt-in for externally visible promises, product boundaries, APIs, acceptance criteria, or explicit user/product evidence.
+- Decision (2026-06-17): Routine code-first Truth Sync uses a product-truth decision instead of a full lane-classification gate.
+  - Product truth is opt-in for externally visible promises, product boundaries, APIs, acceptance criteria, or explicit user/product evidence.
 - Decision (2026-06-15): Optional workflow handoff helpers use `workflow status --json` and `impact --json`; generated surfaces must not direct agents to a standalone ContextPack command.
- Decision (2026-06-16): `truthmark workflow instructions` is intentionally absent; committed host-native workflow files and direct checkout inspection are the runtime contract, while `workflow status` remains an optional compact helper.
- Decision (2026-06-17): Workflow status presents optional helper output as advisory workflow cards with review checklists, evidence prompts, open questions, and skipped-helper status; generated workflows still run from committed host-native files and direct checkout inspection when helpers are unavailable.
+- Decision (2026-06-16): `truthmark workflow instructions` is intentionally absent.
+  - Committed host-native workflow files and direct checkout inspection are the runtime contract, while `workflow status` remains an optional compact helper.
+- Decision (2026-06-17): Workflow status presents optional helper output as advisory workflow cards with review checklists, evidence prompts, open questions, and skipped-helper status.
+  - Generated workflows still run from committed host-native files and direct checkout inspection when helpers are unavailable.
 - Decision (2026-06-16): Truth Sync uses a transient Sync Intent checklist in generated procedures and report templates before truth writes; it is not a persistent plan object or lifecycle artifact.
- Decision (2026-06-18): Truth Sync treats user-provided decision rationale from the current task conversation as first-class sync input. The workflow records that context in Sync Intent, routes it to the correct product or engineering truth section when supported, and reports where it was placed, skipped because none was provided, or handed off for manual review.
- Decision (2026-06-17): Source manifest/renderers are the workflow-generation authority; configured host skill directories are native generated packages with colocated resources. Truthmark does not emit a separate `.truthmark/agent/` workflow copy when no host surface consumes it.
+- Decision (2026-06-18): Truth Sync treats user-provided decision rationale from the current task conversation as first-class sync input.
+  - The workflow records that context in Sync Intent, routes it to the correct product or engineering truth section when supported, and reports where it was placed, skipped because none was provided, or handed off for manual review.
+- Decision (2026-06-17): Source manifest/renderers are the workflow-generation authority; configured host skill directories are native generated packages with colocated resources.
+  - Truthmark does not emit a separate `.truthmark/agent/` workflow copy when no host surface consumes it.
 - Decision (2026-06-18): Fresh configs do not assume Codex, OpenCode, or any other host platform. Host-specific surfaces are generated only for explicit `platforms` entries.
 - Decision (2026-06-18): Generated helper manifest and helper policy files are retired. Validation helpers remain as optional workflow metadata and explicit `truthmark validate ...` commands, not package support files.
- Decision (2026-06-20): Truth Preview generated host surfaces are retired. The repository no longer emits Preview skill packages, Copilot prompts, Antigravity rules, or Cursor rules; route/workflow preview remains an internal read-only selection behavior rather than an installed workflow surface.
- Decision (2026-06-18): Truth Sync retains bounded topology repair. Missing, stale, broad, overloaded, or catch-all route ownership is repaired inside Sync when safe and scoped to the changed functional code; only unsafe, ambiguous, or out-of-scope topology repair is handed off manually to Truth Structure.
+- Decision (2026-06-20): Truth Preview generated host surfaces are retired.
+  - The repository no longer emits Preview skill packages, Copilot prompts, Antigravity rules, or Cursor rules.
+  - Route/workflow preview remains an internal read-only selection behavior rather than an installed workflow surface.
+- Decision (2026-06-18): Truth Sync retains bounded topology repair.
+  - Missing, stale, broad, overloaded, or catch-all route ownership is repaired inside Sync when safe and scoped to the changed functional code.
+  - Only unsafe, ambiguous, or out-of-scope topology repair is handed off manually to Truth Structure.
+- Decision (2026-06-21): Truth Sync report examples and validation must not accept `bootstrap-routing.md` as a completed behavior-update target.
+  - Bootstrap-only mappings are blocked topology handoffs until Truth Structure assigns a bounded owner.
+- Decision (2026-06-21): Cursor workflow generation uses Agent Skill project packages under `.cursor/skills/truthmark-*`, not dynamic `.cursor/rules` files.
+  - Agent Skills are the single current native Cursor workflow representation because they provide description-based selection plus package-local resources.
+- Decision (2026-06-26): Truth-doc prose guidance uses a compact professional checklist instead of vendoring a full humanizer prompt into generated workflows.
+  - Truthmark keeps the benefit of avoiding AI-style padding while controlling token cost and preserving evidence-backed documentation tone.

 ## Rationale

@@ -216,6 +245,7 @@ Update this doc when workflow manifest fields, generated surface paths, optional
 - ../../../../src/agents/instructions.ts
 - ../../../../src/agents/prompts.ts
 - ../../../../src/agents/workflow-manifest.ts
+- ../../../../src/agents/workflow-helper-validation.ts
 - ../../../../src/agents/truth-sync.ts
 - ../../../../src/sync/report.ts
 - ../../../../src/agents/shared.ts
@@ -1,50 +1,112 @@
 ---
 status: active
 truth_kind: product-capability
-last_reviewed: 2026-06-20
+last_reviewed: 2026-06-26
 ---

 # Agent-Native Workflow Injection

 ## Capability Promise

-Truthmark gives configured AI hosts explicit, committed workflow surfaces for Structure, Document, Sync, Realize, and Check. Portal surfaces are generated only when Portal is enabled. Truth Preview generated host surfaces are retired; preview-like route/workflow selection remains internal advisory behavior rather than an installed workflow surface.
+- Truthmark gives configured AI hosts explicit, committed workflow surfaces for Structure, Document, Sync, Realize, and Check.
+- Portal surfaces are generated only when Portal is enabled.
+- Truth Preview generated host surfaces are retired; preview-like route/workflow selection remains internal advisory behavior rather than an installed workflow surface.

 ## Users And Value

 Repository maintainers and agents can follow the checked-in workflow contract without relying on a live Truthmark daemon, hidden runtime state, or off-repo packet.

+Truthmark turns AI documentation from one-shot generation into ongoing truth-doc curation.
+
+Maintainers get bounded, evidence-backed, Git-reviewable truth docs that stay connected to code changes.
+
 ## Capability Scope

-This capability covers generated host-native workflow files, managed instruction blocks, bounded write rules, compact optional validation commands, workflow status/impact guidance, and direct-checkout fallback behavior.
+This capability covers:
+
+- generated host-native workflow files
+- managed instruction blocks
+- bounded write rules
+- compact optional validation commands
+- workflow status/impact guidance
+- direct-checkout fallback behavior

 ## Current Product Behavior

-Supported surfaces include Codex, OpenCode, Claude Code, GitHub Copilot, Antigravity, and Cursor workflow files generated from the source templates and manifest when those platforms are configured. Fresh configs do not assume a host platform; host-specific surfaces are opt-in through `.truthmark/config.yml` `platforms`. Host skill directories are generated as native skill packages for Structure, Document, Sync, Realize, Check, and Portal when enabled: `SKILL.md` plus colocated procedure/report support files and subagent or lease guidance where the workflow uses them. Antigravity and Cursor rule files are flat host rule surfaces that inline the procedure and report template, omit duplicate quick-procedure summaries, and do not reference package-local support files those hosts do not consume. Generated helper manifests and helper policy files are intentionally not emitted; validation helpers remain optional commands and report validators allow manual fallback evidence. Compact prompt, command, and top-level instruction surfaces may point into host-native packages, but configured skill directories are not adapter-only pointer folders because some hosts package and progressively disclose resources from the skill directory itself. Truth Preview is not generated as a skill package, prompt file, or command file for any host. Truthmark does not add a separate `.truthmark/agent/` workflow copy unless a host surface actually consumes it; the checked-in host-native packages are the runtime workflow surfaces. Agents may use `truthmark workflow status --workflow <workflow> [--base <ref>] --json` and `truthmark impact --base <ref> --json` as optional compact helpers for advisory workflow cards, affected files, likely route owners, suggested truth docs, review checklists, evidence prompts, open questions, skipped helper status, and diagnostics; these helpers do not provide file-content packets and are not sources of truth. Truth Sync status separates impacted `primaryTruthDocs`, `candidateStaleTruthDocs`, and `routeFiles` so agents start with affected route owners while preserving evidence-backed stale repository-truth correction beyond the initially affected route set.
+- Supported surfaces include Codex, OpenCode, Claude Code, GitHub Copilot, Antigravity, and Cursor workflow files generated from the source templates and manifest when those platforms are configured.
+- Fresh configs do not assume a host platform; host-specific surfaces are opt-in through `.truthmark/config.yml` `platforms`.
+- Host skill directories are generated as native skill packages for Structure, Document, Sync, Realize, Check, and Portal when enabled.
+  - They include `SKILL.md` plus colocated procedure/report support files.
+  - They include subagent or lease guidance where the workflow uses them.
+- Antigravity rule files are flat host rule surfaces.
+  - They inline the procedure and report template.
+  - They omit duplicate quick-procedure summaries.
+  - They do not reference package-local support files that Antigravity does not consume.
+- Cursor uses Agent Skill project packages under `.cursor/skills/truthmark-*`.
+- Cursor Rules remain a platform surface, but Truthmark uses Agent Skills as its single current native Cursor workflow representation because they provide description-based selection and package-local support resources.
+- Generated helper manifests and helper policy files are intentionally not emitted; validation helpers remain optional commands and report validators allow manual fallback evidence.
+- Compact prompt, command, and top-level instruction surfaces may point into host-native packages.
+- Configured skill directories are not adapter-only pointer folders.
+- Some hosts package and progressively disclose resources from the skill directory itself.
+- Truth Preview is not generated as a skill package, prompt file, or command file for any host.
+- Truthmark does not add a separate `.truthmark/agent/` workflow copy unless a host surface actually consumes it.
+- The checked-in host-native packages are the runtime workflow surfaces.
+- Agents may use optional compact helpers for workflow guidance:
+  - `truthmark workflow status --workflow <workflow> [--base <ref>] --json`
+  - `truthmark impact --base <ref> --json`
+- Optional helpers can expose advisory workflow cards, affected files, likely route owners, suggested truth docs, review checklists, evidence prompts, open questions, skipped helper status, and diagnostics.
+- These helpers do not provide file-content packets and are not sources of truth.
+- Truth Sync status separates impacted `primaryTruthDocs`, `candidateStaleTruthDocs`, and `routeFiles`.
+- Agents start with affected route owners.
+- Evidence-backed stale repository-truth correction remains available beyond the initially affected route set.
+- Broad, catch-all, mixed-owner, or overgrown truth docs are treated as curation problems that require Structure instead of more appended prose.

 ## Acceptance Criteria

 - Each configured platform receives host-native workflow entrypoints.
 - Fresh config defaults do not generate host-specific surfaces unless platforms are explicitly configured.
 - Each configured host skill directory receives the workflow support files needed for native skill resource packaging, without generated helper manifests or helper policy files.
- Flat Antigravity and Cursor rule surfaces inline procedure/report content without duplicate quick-procedure summaries, nonexistent support-file references, or cross-host invocation matrices.
+- Flat Antigravity rule surfaces inline procedure/report content without duplicate quick-procedure summaries, nonexistent support-file references, or cross-host invocation matrices.
+- Cursor Agent Skill packages under `.cursor/skills/truthmark-*` include package-local support resources and are the only generated Cursor workflow surface.
 - Generated surfaces preserve workflow boundaries, direct-checkout fallback, and bounded Sync-owned topology repair.
 - Truth Preview generated host surfaces are retired; preview-like routing selection remains internal, read-only advisory behavior rather than an installed workflow package, prompt, or command.
 - Routine code-first Truth Sync defaults internal implementation changes to engineering truth unless a user-visible promise, capability boundary, API contract, acceptance criterion, or explicit user/product evidence changed.
- Truth Sync carries user-provided decision rationale, constraints, tradeoffs, rejection reasons, and scope boundaries from the current task conversation into Sync Intent, routes them to the correct truth lane when supported, and reports placement, skip, or manual handoff.
+- Truth Sync carries user-provided decision rationale, constraints, tradeoffs, rejection reasons, and scope boundaries from the current task conversation into Sync Intent.
+- Truth Sync routes supported context to the correct truth lane.
+- Truth Sync reports placement, skip, or manual handoff.
 - Workflows that create, structure, or audit truth docs still preserve product and engineering truth as separate lanes.
+- Truth Document and Truth Sync carry compact professional prose guidance for truth-doc edits without embedding a full external humanizer prompt in generated workflow surfaces.
+- Truthmark positions ongoing truth-doc curation as a core product value rather than presenting itself as a one-shot documentation generator.

 ## Product Decisions

 - Decision (2026-06-14): Workflow surfaces remain committed repository files; optional CLI helpers validate after relevant work and do not orchestrate workflow execution.
 - Decision (2026-06-15): Agent-facing repository-intelligence handoff uses workflow status plus impact instead of a standalone ContextPack command.
- Decision (2026-06-17): Optional workflow status presents helper output as advisory workflow cards with review checklists, evidence prompts, open questions, and skipped-helper status; direct checkout inspection remains the fallback when helpers are skipped, unavailable, or unnecessary.
- Decision (2026-06-17): Host skill directories are product-owned native packages, not adapter-only pointers. Justification: agent skill systems may discover and package the skill directory as the resource boundary, so `SKILL.md` must be colocated with procedure, report-template, and lease resources needed for progressive disclosure. Compact adapters may point to host-native packages, but removing those colocated resources from configured skill folders would make workflow behavior depend on manual cross-repository reads and could fail in hosts or sandboxes that package only the skill directory. A separate `.truthmark/agent/` workflow copy is not generated unless a host surface actually consumes it, because otherwise it is duplicate repository documentation rather than runtime surface.
- Decision (2026-06-18): Truth Sync exposes conversation-provided decision rationale as a visible workflow input and report outcome, without transcript ingestion, hidden memory, required hooks, persistent inbox files, mandatory ADRs, or extra proposal artifacts.
- Decision (2026-06-18): Fresh installs do not assume Codex, OpenCode, or any other host platform; maintainers opt into Codex, OpenCode, Claude Code, GitHub Copilot, Antigravity, or Cursor surfaces by listing them in `platforms`.
+- Decision (2026-06-17): Optional workflow status presents helper output as advisory workflow cards with review checklists, evidence prompts, open questions, and skipped-helper status.
+  - Direct checkout inspection remains the fallback when helpers are skipped, unavailable, or unnecessary.
+- Decision (2026-06-17): Host skill directories are product-owned native packages, not adapter-only pointers.
+  - Agent skill systems may discover and package the skill directory as the resource boundary.
+  - `SKILL.md` must be colocated with procedure, report-template, and lease resources needed for progressive disclosure.
+  - Compact adapters may point to host-native packages.
+  - Removing colocated resources from configured skill folders would make workflow behavior depend on manual cross-repository reads.
+  - Removing colocated resources could fail in hosts or sandboxes that package only the skill directory.
+  - A separate `.truthmark/agent/` workflow copy is not generated unless a host surface actually consumes it, because otherwise it is duplicate repository documentation rather than runtime surface.
+- Decision (2026-06-18): Truth Sync exposes conversation-provided decision rationale as a visible workflow input and report outcome.
+  - It does not use transcript ingestion, hidden memory, required hooks, persistent inbox files, mandatory ADRs, or extra proposal artifacts.
+- Decision (2026-06-18): Fresh installs do not assume Codex, OpenCode, or any other host platform.
+  - Maintainers opt into Codex, OpenCode, Claude Code, GitHub Copilot, Antigravity, or Cursor surfaces by listing them in `platforms`.
 - Decision (2026-06-18): Generated helper manifest and helper policy files are removed from skill packages; optional validation remains available through explicit CLI validation commands and manual fallback checks.
- Decision (2026-06-20): Truth Preview generated host surfaces are retired. Truthmark no longer emits Preview skill packages, Copilot prompts, Antigravity rules, or Cursor rules; preview-like route/workflow selection remains internal advisory behavior rather than an installed workflow surface.
- Decision (2026-06-18): Finish-time Truth Sync retains bounded topology repair. Safe repairs happen inside Sync before normal truth syncing; manual Truth Structure handoff is only for unsafe, ambiguous, or out-of-scope topology changes.
+- Decision (2026-06-20): Truth Preview generated host surfaces are retired.
+  - Truthmark no longer emits Preview skill packages, Copilot prompts, Antigravity rules, or Cursor rules.
+  - Preview-like route/workflow selection remains internal advisory behavior rather than an installed workflow surface.
+- Decision (2026-06-18): Finish-time Truth Sync retains bounded topology repair.
+  - Safe repairs happen inside Sync before normal truth syncing; manual Truth Structure handoff is only for unsafe, ambiguous, or out-of-scope topology changes.
+- Decision (2026-06-21): Cursor uses Agent Skill project packages under `.cursor/skills/truthmark-*`, not dynamic `.cursor/rules` files.
+  - Cursor Agent Skills are the single current native Cursor workflow representation for Truthmark because they support description-based selection plus package-local support resources.
+- Decision (2026-06-26): Humanizer-style cleanup is adapted only as a compact professional prose checklist.
+  - The workflow must avoid token-heavy prompt imports and must not push truth docs toward personal, rhetorical, or marketing tone.
+- Decision (2026-06-26): Ongoing truth-doc curation is a primary product value.
+  - Marketing should emphasize bounded ownership, evidence-backed updates, Git-reviewable docs, and Structure handoff for overgrown docs rather than claiming generic documentation generation.

 ## Engineering Realization Links

@@ -16,11 +16,15 @@ Maintainers can review product promises and implementation realization without e

 ## Capability Scope

-Product truth belongs under `docs/truthmark/product`; engineering truth belongs under `docs/truthmark/engineering`. Downstream product truth uses `product-capability` only. Product boundary, scope, adjacent-system, and non-goal guidance lives inside capability docs instead of a separate downstream boundary kind. Relationships between lanes are traceability edges, not content inheritance.
+- Product truth belongs under `docs/truthmark/product`; engineering truth belongs under `docs/truthmark/engineering`.
+- Downstream product truth uses `product-capability` only.
+- Product boundary, scope, adjacent-system, and non-goal guidance lives inside capability docs instead of a separate downstream boundary kind.
+- Relationships between lanes are traceability edges, not content inheritance.

 ## Current Product Behavior

-Route metadata supports explicit `lane`, `realized_by`, `realizes`, and `depends_on` fields for route-local traceability. Product-path kind inference returns `product-capability`, and init scaffolds `product-capability.md` without scaffolding a downstream `product-boundary` template.
+- Route metadata supports explicit `lane`, `realized_by`, `realizes`, and `depends_on` fields for route-local traceability.
+- Product-path kind inference returns `product-capability`, and init scaffolds `product-capability.md` without scaffolding a downstream `product-boundary` template.

 ## Acceptance Criteria

@@ -36,7 +40,8 @@ Route metadata supports explicit `lane`, `realized_by`, `realizes`, and `depends
 - Decision (2026-06-14): Product docs may cite code directly as evidence for current product behavior, but detailed mechanics stay in engineering docs.
 - Decision (2026-06-14): Missing product links for user-visible engineering docs are review diagnostics, not hard errors.
 - Decision (2026-06-14): Downstream product truth supports `product-capability` only; product boundary guidance belongs inside capability scope, acceptance criteria, and non-goals.
- Decision (2026-06-15): Route `realized_by` and `realizes` relationships are local navigation metadata, not a single global doc graph; validation requires existing opposite-lane targets without requiring reciprocal declarations.
+- Decision (2026-06-15): Route `realized_by` and `realizes` relationships are local navigation metadata, not a single global doc graph.
+  - Validation requires existing opposite-lane targets without requiring reciprocal declarations.

 ## Engineering Realization Links

@@ -105,12 +105,15 @@ Area files:
 Code surface:

 - .github/workflows/\*\*
+- site/\*\*
 - src/templates/github-action.ts

 Update truth when:

 - CI verification steps or triggers change
 - release publishing prerequisites or publish steps change
+- checked-in repository-readiness scans change
+- GitHub Pages deployment or static introduction site behavior changes

 ## Repository Intelligence

@@ -20,12 +20,15 @@ truth_documents:
 Code surface:

 - .github/workflows/\*\*
+- site/\*\*
 - src/templates/github-action.ts

 Update truth when:

 - CI verification steps or triggers change
 - release publishing prerequisites or publish steps change
+- CodeQL or other checked-in repository-readiness automation changes
+- GitHub Pages deployment or static introduction site behavior changes
 - GitHub Action examples or action template rendering changes

 ## Source References
@@ -48,6 +48,16 @@ Separate rules from incidental implementation details; cite current implementati

 {{core_rules}}

+## Behavior Scenarios
+
+<!--
+Use compact scenario blocks only where they clarify normal, fallback, or compatibility-critical behavior.
+Write scenarios as current truth, not desired requirements: `#### Scenario: <implemented case>` followed by `- **GIVEN** ...`, `- **WHEN** ...`, `- **THEN** ...`, and optional `- **AND** ...` bullets.
+Keep each bullet evidence-backed and observable; do not force a scenario for every rule.
+-->
+
+{{behavior_scenarios}}
+
 ## Flows And States

 <!--
@@ -62,7 +62,7 @@ truthmark init
 | `github-copilot` | Agent skills, prompt commands, custom agents, and managed instructions | `/truthmark-*` in supported Copilot IDEs; `@truth-*` custom agents in Copilot CLI |
 | `opencode` | Skill packages and verifier agents | `/skill truthmark-*` |
 | `antigravity` | Project rule files for Truthmark workflows | `@truthmark-*` |
-| `cursor` | Project rule files under `.cursor/rules` | `@truthmark-*` |
+| `cursor` | Agent Skill project packages under `.cursor/skills` | selected by description or invoked with `/` in Cursor Agent chat |

 Unknown platform names are config errors.

@@ -120,7 +120,7 @@ Use Truth Document when the implementation already exists but the repository tru
 /truthmark-document document the implemented session timeout behavior across src/auth/session.ts, src/auth/middleware.ts, and tests/auth/session.test.ts
 ```

-Give it the feature name, code paths, test paths, or desired truth-doc area. On OpenCode-style hosts, call the same workflow as `/skill truthmark-document ...`; on Antigravity or Cursor, use `@truthmark-document ...`.
+Give it the feature name, code paths, test paths, or desired truth-doc area. On OpenCode-style hosts, call the same workflow as `/skill truthmark-document ...`; on Antigravity, use `@truthmark-document ...`; in Cursor, use `/truthmark-document ...` or let the Agent Skill be selected by description.

 Start with Truth Document for one bounded feature or area at a time.

@@ -170,7 +170,7 @@ Most maintainers start with three commands.
 | `truthmark init` | Install or refresh configured workflow surfaces from the reviewed config. |
 | `truthmark check` | Validate configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, generated surfaces, freshness, and coverage diagnostics. |

-Optional repository-intelligence helpers generate derived review material for the active checkout, such as RepoIndex, RouteMap, ImpactSet, and compact WorkflowState/action-context JSON. Validation helpers are exposed as optional workflow metadata and explicit `truthmark validate ... --json` commands; they are accelerators, not bundled repo-local helper manifest or policy files and not sources of truth. Standalone Copilot prompts and Antigravity/Cursor rules use the same CLI validator contract when the installed runner is available, and otherwise report a visible skipped helper status with manual validation.
+Optional repository-intelligence helpers generate derived review material for the active checkout, such as RepoIndex, RouteMap, ImpactSet, and compact WorkflowState/action-context JSON. Validation helpers are exposed as optional workflow metadata and explicit `truthmark validate ... --json` commands; they are accelerators, not bundled repo-local helper manifest or policy files and not sources of truth. Standalone Copilot prompts, Antigravity rules, and Cursor Agent Skills use the same CLI validator contract when the installed runner is available, and otherwise report a visible skipped helper status with manual validation.

 They are not sources of truth.

@@ -1,12 +1,12 @@
 {
  "name": "truthmark",
-  "version": "2.2.4",
+  "version": "2.2.6",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "truthmark",
-      "version": "2.2.4",
+      "version": "2.2.6",
      "license": "MIT",
      "dependencies": {
        "ajv": "^8.17.1",
@@ -1,6 +1,6 @@
 {
  "name": "truthmark",
-  "version": "2.2.4",
+  "version": "2.2.6",
  "description": "Git-native, branch-scoped truth workflow installer for local AI coding agents.",
  "license": "MIT",
  "type": "module",
@@ -0,0 +1,862 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Truthmark — the branch explains itself</title>
+  <meta name="description" content="Truthmark helps AI-assisted branches carry accurate, reviewable repository truth alongside code changes.">
+  <meta property="og:title" content="Truthmark — the branch explains itself">
+  <meta property="og:description" content="A repository-native review layer for code, decisions, and current truth.">
+  <meta property="og:type" content="website">
+  <meta name="theme-color" content="#07131f">
+  <style>
+    :root {
+      color-scheme: dark;
+      --ink: #07131f;
+      --ink-2: #0a1a2a;
+      --ink-3: #102236;
+      --paper: #f5f7ef;
+      --paper-2: #e8f2dd;
+      --text: #f8fbf2;
+      --muted: #b9c7d6;
+      --dim: #7f90a3;
+      --green: #8ee66b;
+      --green-2: #58bf43;
+      --lime-glow: rgba(142, 230, 107, 0.2);
+      --cyan: #77d9ff;
+      --amber: #f1c765;
+      --rose: #ff8d9a;
+      --line: rgba(220, 236, 255, 0.16);
+      --line-strong: rgba(220, 236, 255, 0.28);
+      --panel: rgba(255, 255, 255, 0.045);
+      --panel-2: rgba(255, 255, 255, 0.075);
+      --shadow: 0 30px 90px rgba(0, 0, 0, 0.36);
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }
+
+    * { box-sizing: border-box; }
+    html { scroll-behavior: smooth; }
+
+    body {
+      margin: 0;
+      min-height: 100vh;
+      color: var(--text);
+      background:
+        radial-gradient(circle at 18% 6%, rgba(142, 230, 107, 0.18), transparent 28rem),
+        radial-gradient(circle at 82% 10%, rgba(119, 217, 255, 0.13), transparent 32rem),
+        radial-gradient(circle at 50% 56%, rgba(241, 199, 101, 0.06), transparent 38rem),
+        linear-gradient(180deg, #020812 0%, var(--ink) 36%, #050b12 100%);
+      overflow-x: hidden;
+    }
+
+    body::before {
+      content: "";
+      position: fixed;
+      inset: 0;
+      z-index: -1;
+      background-image:
+        linear-gradient(rgba(255,255,255,0.035) 1px, transparent 1px),
+        linear-gradient(90deg, rgba(255,255,255,0.035) 1px, transparent 1px);
+      background-size: 48px 48px;
+      mask-image: linear-gradient(180deg, rgba(0,0,0,0.75), transparent 72%);
+    }
+
+    a { color: inherit; }
+
+    .shell {
+      width: min(1240px, calc(100% - 48px));
+      margin: 0 auto;
+    }
+
+    .nav {
+      position: sticky;
+      top: 0;
+      z-index: 50;
+      border-bottom: 1px solid rgba(220,236,255,0.08);
+      background: rgba(3, 10, 18, 0.78);
+      backdrop-filter: blur(18px);
+    }
+
+    .nav-inner {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      min-height: 74px;
+    }
+
+    .brand {
+      display: inline-flex;
+      align-items: center;
+      gap: 12px;
+      text-decoration: none;
+      font-weight: 780;
+      letter-spacing: -0.03em;
+    }
+
+    .glyph {
+      position: relative;
+      width: 38px;
+      height: 38px;
+      border: 1px solid rgba(142,230,107,0.55);
+      border-radius: 13px;
+      background: linear-gradient(145deg, rgba(142,230,107,0.2), rgba(119,217,255,0.1));
+      box-shadow: 0 0 30px rgba(142,230,107,0.18);
+    }
+
+    .glyph::before,
+    .glyph::after {
+      content: "";
+      position: absolute;
+      border-radius: 999px;
+      background: var(--green);
+    }
+
+    .glyph::before { width: 16px; height: 3px; left: 10px; top: 18px; transform: rotate(42deg); }
+    .glyph::after { width: 23px; height: 3px; left: 15px; top: 16px; transform: rotate(-48deg); }
+
+    .nav-links {
+      display: flex;
+      align-items: center;
+      gap: 21px;
+      color: var(--muted);
+      font-size: 0.94rem;
+      font-weight: 620;
+    }
+
+    .nav-links a {
+      text-decoration: none;
+      transition: color 150ms ease;
+    }
+
+    .nav-links a:hover { color: var(--text); }
+
+    .button {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      min-height: 44px;
+      padding: 0 17px;
+      border: 1px solid var(--line-strong);
+      border-radius: 999px;
+      background: rgba(255,255,255,0.045);
+      color: var(--text);
+      font-weight: 720;
+      text-decoration: none;
+      box-shadow: 0 12px 34px rgba(0,0,0,0.22);
+    }
+
+    .button.primary {
+      color: #06110a;
+      border-color: rgba(142,230,107,0.92);
+      background: linear-gradient(180deg, #a4f483, #62c94b);
+    }
+
+    .hero {
+      display: grid;
+      grid-template-columns: 0.9fr 1.1fr;
+      gap: 52px;
+      align-items: center;
+      min-height: calc(100vh - 74px);
+      padding: 76px 0 88px;
+    }
+
+    .eyebrow {
+      display: inline-flex;
+      align-items: center;
+      gap: 10px;
+      padding: 7px 12px;
+      border: 1px solid rgba(142,230,107,0.28);
+      border-radius: 999px;
+      background: rgba(142,230,107,0.09);
+      color: #d9ffd0;
+      font-size: 0.9rem;
+      font-weight: 760;
+      letter-spacing: -0.01em;
+    }
+
+    .pulse {
+      width: 8px;
+      height: 8px;
+      border-radius: 999px;
+      background: var(--green);
+      box-shadow: 0 0 16px rgba(142,230,107,0.8);
+    }
+
+    h1 {
+      margin: 22px 0 20px;
+      font-size: clamp(3.35rem, 6.7vw, 6.6rem);
+      line-height: 0.91;
+      letter-spacing: -0.078em;
+      text-wrap: balance;
+    }
+
+    .lead {
+      max-width: 740px;
+      margin: 0;
+      color: var(--muted);
+      font-size: clamp(1.18rem, 1.55vw, 1.48rem);
+      line-height: 1.58;
+      letter-spacing: -0.02em;
+    }
+
+    .hero-actions {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 14px;
+      margin-top: 32px;
+    }
+
+    .signals {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 12px;
+      margin-top: 34px;
+      max-width: 690px;
+    }
+
+    .signal {
+      padding: 15px;
+      border: 1px solid var(--line);
+      border-radius: 16px;
+      background: var(--panel);
+    }
+
+    .signal strong { display: block; margin-bottom: 6px; letter-spacing: -0.025em; }
+    .signal span { color: var(--dim); font-size: 0.92rem; line-height: 1.42; }
+
+    .stage {
+      position: relative;
+      min-height: 680px;
+      border: 1px solid var(--line-strong);
+      border-radius: 34px;
+      background:
+        radial-gradient(circle at 70% 16%, rgba(142,230,107,0.17), transparent 18rem),
+        radial-gradient(circle at 22% 80%, rgba(119,217,255,0.1), transparent 20rem),
+        rgba(255,255,255,0.045);
+      box-shadow: var(--shadow);
+      overflow: hidden;
+    }
+
+    .stage::before {
+      content: "";
+      position: absolute;
+      inset: 42px;
+      border: 1px dashed rgba(220,236,255,0.13);
+      border-radius: 999px;
+      transform: rotate(-14deg);
+    }
+
+    .orbit {
+      position: absolute;
+      border: 1px solid var(--line);
+      background: rgba(4, 12, 22, 0.78);
+      backdrop-filter: blur(8px);
+      box-shadow: 0 18px 60px rgba(0,0,0,0.28);
+    }
+
+    .orbit.core {
+      left: 50%; top: 50%; transform: translate(-50%, -50%);
+      width: min(390px, 72%);
+      border-radius: 28px;
+      padding: 26px;
+      z-index: 4;
+    }
+
+    .core h2 {
+      margin: 0 0 12px;
+      font-size: 2rem;
+      line-height: 1.04;
+      letter-spacing: -0.055em;
+    }
+
+    .core p { margin: 0; color: var(--muted); line-height: 1.55; }
+
+    .route-line {
+      display: grid;
+      grid-template-columns: 18px 1fr auto;
+      gap: 10px;
+      align-items: center;
+      margin-top: 18px;
+      padding: 12px;
+      border: 1px solid rgba(220,236,255,0.12);
+      border-radius: 14px;
+      color: #dfe9f6;
+      font: 0.86rem/1.4 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      background: rgba(255,255,255,0.035);
+    }
+
+    .route-line i {
+      display: block;
+      width: 11px;
+      height: 11px;
+      border-radius: 999px;
+      background: var(--green);
+      box-shadow: 0 0 14px rgba(142,230,107,0.6);
+    }
+
+    .route-line em { color: var(--dim); font-style: normal; }
+
+    .node {
+      position: absolute;
+      width: 172px;
+      padding: 16px;
+      border-radius: 20px;
+    }
+
+    .node strong { display: block; margin-bottom: 7px; letter-spacing: -0.02em; }
+    .node span { display: block; color: var(--dim); font-size: 0.86rem; line-height: 1.38; }
+    .node.a { top: 44px; left: 54px; }
+    .node.b { top: 88px; right: 42px; }
+    .node.c { left: 42px; bottom: 76px; }
+    .node.d { right: 58px; bottom: 52px; }
+
+    .rail {
+      position: absolute;
+      height: 2px;
+      background: linear-gradient(90deg, transparent, rgba(142,230,107,0.62), transparent);
+      transform-origin: left center;
+      opacity: 0.7;
+    }
+
+    .rail.r1 { width: 260px; top: 206px; left: 180px; transform: rotate(24deg); }
+    .rail.r2 { width: 230px; top: 224px; right: 170px; transform: rotate(145deg); }
+    .rail.r3 { width: 260px; bottom: 214px; left: 180px; transform: rotate(-22deg); }
+    .rail.r4 { width: 230px; bottom: 202px; right: 184px; transform: rotate(205deg); }
+
+    .section {
+      padding: 92px 0;
+      border-top: 1px solid rgba(220,236,255,0.08);
+    }
+
+    .section-header {
+      max-width: 860px;
+      margin-bottom: 34px;
+    }
+
+    h2.section-title,
+    .section-header h2 {
+      margin: 0 0 14px;
+      font-size: clamp(2.35rem, 4.5vw, 4.6rem);
+      line-height: 0.96;
+      letter-spacing: -0.068em;
+      text-wrap: balance;
+    }
+
+    .section-header p {
+      margin: 0;
+      color: var(--muted);
+      font-size: 1.16rem;
+      line-height: 1.62;
+      letter-spacing: -0.015em;
+    }
+
+    .map-grid {
+      display: grid;
+      grid-template-columns: repeat(4, minmax(0, 1fr));
+      gap: 14px;
+    }
+
+    .surface-card {
+      position: relative;
+      min-height: 250px;
+      padding: 22px;
+      border: 1px solid var(--line);
+      border-radius: 22px;
+      background: var(--panel);
+      overflow: hidden;
+    }
+
+    .surface-card::after {
+      content: attr(data-index);
+      position: absolute;
+      right: 18px;
+      bottom: 12px;
+      color: rgba(248,251,242,0.08);
+      font-size: 4.8rem;
+      font-weight: 800;
+      letter-spacing: -0.08em;
+    }
+
+    .surface-card:hover { border-color: rgba(142,230,107,0.38); background: var(--panel-2); }
+
+    .surface-card h3 {
+      position: relative;
+      margin: 0 0 10px;
+      font-size: 1.35rem;
+      line-height: 1.08;
+      letter-spacing: -0.04em;
+      z-index: 1;
+    }
+
+    .surface-card p {
+      position: relative;
+      margin: 0;
+      color: var(--muted);
+      line-height: 1.55;
+      z-index: 1;
+    }
+
+    .mini-kicker {
+      display: inline-flex;
+      margin-bottom: 18px;
+      padding: 5px 9px;
+      border: 1px solid rgba(142,230,107,0.32);
+      border-radius: 999px;
+      color: var(--green);
+      background: rgba(142,230,107,0.08);
+      font-size: 0.72rem;
+      font-weight: 820;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+    }
+
+    .timeline {
+      display: grid;
+      grid-template-columns: 310px 1fr;
+      gap: 18px;
+      align-items: stretch;
+    }
+
+    .tabs {
+      display: grid;
+      gap: 12px;
+    }
+
+    .tab {
+      width: 100%;
+      padding: 18px;
+      border: 1px solid var(--line);
+      border-radius: 18px;
+      background: var(--panel);
+      color: var(--muted);
+      text-align: left;
+      cursor: pointer;
+      font: inherit;
+    }
+
+    .tab strong {
+      display: block;
+      margin-bottom: 7px;
+      color: var(--text);
+      font-size: 1.04rem;
+      letter-spacing: -0.03em;
+    }
+
+    .tab[aria-selected="true"] {
+      border-color: rgba(142,230,107,0.56);
+      background: rgba(142,230,107,0.12);
+      color: #dcefd7;
+    }
+
+    .panel {
+      display: none;
+      min-height: 640px;
+      border: 1px solid var(--line-strong);
+      border-radius: 26px;
+      background: rgba(4, 12, 22, 0.74);
+      box-shadow: var(--shadow);
+      overflow: hidden;
+    }
+
+    .panel.active { display: block; }
+
+    .panel-head {
+      display: flex;
+      justify-content: space-between;
+      gap: 16px;
+      padding: 18px 22px;
+      border-bottom: 1px solid var(--line);
+    }
+
+    .panel-head strong { letter-spacing: -0.03em; }
+
+    .status-pill {
+      display: inline-flex;
+      align-items: center;
+      padding: 5px 9px;
+      border: 1px solid rgba(142,230,107,0.36);
+      border-radius: 999px;
+      color: var(--green);
+      background: rgba(142,230,107,0.09);
+      font-size: 0.76rem;
+      font-weight: 820;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+    }
+
+    .panel-grid {
+      display: grid;
+      grid-template-columns: 0.9fr 1.1fr;
+      min-height: 590px;
+    }
+
+    .evidence,
+    .truth-sheet {
+      padding: 24px;
+    }
+
+    .evidence {
+      border-right: 1px solid var(--line);
+      background: rgba(255,255,255,0.025);
+    }
+
+    .label {
+      display: block;
+      margin-bottom: 14px;
+      color: var(--green);
+      font-size: 0.78rem;
+      font-weight: 850;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+    }
+
+    .evidence-list { display: grid; gap: 11px; }
+
+    .file-row,
+    .claim-row {
+      padding: 12px 13px;
+      border: 1px solid rgba(220,236,255,0.11);
+      border-radius: 12px;
+      background: rgba(255,255,255,0.035);
+      color: #dfe9f6;
+      font: 0.88rem/1.42 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    }
+
+    .truth-sheet h3 {
+      margin: 0 0 12px;
+      font-size: 1.48rem;
+      line-height: 1.1;
+      letter-spacing: -0.045em;
+    }
+
+    .truth-sheet h4 {
+      margin: 18px 0 8px;
+      color: var(--green);
+      font-size: 0.96rem;
+      letter-spacing: -0.01em;
+    }
+
+    .truth-sheet p,
+    .truth-sheet li { color: var(--muted); line-height: 1.55; }
+    .truth-sheet ul { margin: 8px 0 0; padding-left: 18px; }
+
+    .add { color: #b8f5a4; }
+    .edit { color: #f5d37d; }
+    .move { color: #9fdcff; }
+    .quiet { color: #9dafc4; }
+
+    .split-view {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 18px;
+    }
+
+    .lane {
+      padding: 26px;
+      border: 1px solid var(--line);
+      border-radius: 24px;
+      background: var(--panel);
+    }
+
+    .lane h3 {
+      margin: 0 0 12px;
+      font-size: 1.7rem;
+      letter-spacing: -0.055em;
+    }
+
+    .lane p,
+    .lane li { color: var(--muted); line-height: 1.58; }
+    .lane ul { padding-left: 18px; }
+
+    .diagram {
+      margin-top: 28px;
+      padding: 24px;
+      border: 1px solid var(--line);
+      border-radius: 26px;
+      background:
+        linear-gradient(135deg, rgba(142,230,107,0.08), transparent 38%),
+        rgba(255,255,255,0.035);
+    }
+
+    .diagram-grid {
+      display: grid;
+      grid-template-columns: repeat(5, minmax(0, 1fr));
+      gap: 12px;
+      align-items: center;
+    }
+
+    .diagram-cell {
+      min-height: 118px;
+      display: grid;
+      place-items: center;
+      padding: 14px;
+      border: 1px solid rgba(220,236,255,0.13);
+      border-radius: 18px;
+      background: rgba(4,12,22,0.58);
+      text-align: center;
+      color: var(--muted);
+      line-height: 1.38;
+    }
+
+    .diagram-cell strong { color: var(--text); display: block; margin-bottom: 6px; }
+    .arrow { color: var(--green); font-size: 1.8rem; text-align: center; }
+
+    .install {
+      display: grid;
+      grid-template-columns: 0.85fr 1.15fr;
+      gap: 22px;
+      align-items: stretch;
+    }
+
+    .terminal {
+      border: 1px solid var(--line-strong);
+      border-radius: 24px;
+      background: rgba(3,9,18,0.78);
+      box-shadow: var(--shadow);
+      overflow: hidden;
+    }
+
+    .terminal-top {
+      display: flex;
+      gap: 8px;
+      padding: 16px 18px;
+      border-bottom: 1px solid var(--line);
+      background: rgba(255,255,255,0.035);
+    }
+
+    .term-dot { width: 10px; height: 10px; border-radius: 999px; background: #5f6b7a; }
+    .term-dot:nth-child(2) { background: #94a0ae; }
+    .term-dot:nth-child(3) { background: var(--green); }
+
+    pre {
+      margin: 0;
+      padding: 25px;
+      color: #dfe9f6;
+      white-space: pre-wrap;
+      font: 500 0.97rem/1.78 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    }
+
+    .prompt { color: var(--green); }
+    .comment { color: var(--dim); }
+
+    .footer {
+      display: flex;
+      justify-content: space-between;
+      gap: 24px;
+      padding: 44px 0 64px;
+      border-top: 1px solid rgba(220,236,255,0.08);
+      color: var(--dim);
+    }
+
+    .footer a { color: var(--text); text-decoration: none; }
+
+    @media (max-width: 1080px) {
+      .hero,
+      .timeline,
+      .panel-grid,
+      .split-view,
+      .install { grid-template-columns: 1fr; }
+      .stage { min-height: 620px; }
+      .map-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+      .diagram-grid { grid-template-columns: 1fr; }
+      .arrow { transform: rotate(90deg); }
+      .evidence { border-right: 0; border-bottom: 1px solid var(--line); }
+      .nav-links { display: none; }
+    }
+
+    @media (max-width: 680px) {
+      .shell { width: min(100% - 28px, 1240px); }
+      .hero { padding-top: 52px; }
+      .signals,
+      .map-grid { grid-template-columns: 1fr; }
+      .stage { min-height: 720px; }
+      .node { width: 145px; }
+      .node.a { top: 30px; left: 20px; }
+      .node.b { top: 54px; right: 20px; }
+      .node.c { left: 20px; bottom: 58px; }
+      .node.d { right: 20px; bottom: 40px; }
+      .rail { display: none; }
+      .footer { flex-direction: column; }
+    }
+  </style>
+</head>
+<body>
+  <header class="nav">
+    <div class="shell nav-inner">
+      <a class="brand" href="#top" aria-label="Truthmark home">
+        <span class="glyph" aria-hidden="true"></span>
+        <span>Truthmark</span>
+      </a>
+      <nav class="nav-links" aria-label="Primary navigation">
+        <a href="#surface-map">Surface map</a>
+        <a href="#storyboard">Storyboard</a>
+        <a href="#lanes">Lanes</a>
+        <a href="#workflow">Workflow</a>
+        <a href="https://github.com/merlinhu1/truthmark">GitHub</a>
+      </nav>
+    </div>
+  </header>
+
+  <main id="top">
+    <section class="shell hero">
+      <div>
+        <div class="eyebrow"><span class="pulse"></span>Repository truth carried by the branch</div>
+        <h1>The branch should explain itself.</h1>
+        <p class="lead">Truthmark gives AI-assisted work a reviewable truth layer: current claims, ownership routes, product promises, and implementation facts travel with the same Git branch as the code.</p>
+        <div class="hero-actions">
+          <a class="button primary" href="https://github.com/merlinhu1/truthmark">View on GitHub</a>
+          <a class="button" href="#storyboard">Open the demo</a>
+        </div>
+        <div class="signals" aria-label="Truthmark summary signals">
+          <div class="signal"><strong>Checkout-native</strong><span>After setup, normal agent work can proceed from committed repository files.</span></div>
+          <div class="signal"><strong>Claim-level review</strong><span>Docs change as small, source-backed claims instead of anonymous summaries.</span></div>
+          <div class="signal"><strong>Topology aware</strong><span>When truth gets too broad, ownership gets repaired rather than hidden.</span></div>
+          <div class="signal"><strong>Host-shaped</strong><span>Instructions meet agents in their existing coding environments.</span></div>
+        </div>
+      </div>
+
+      <aside class="stage" aria-label="Original Truthmark concept illustration">
+        <div class="rail r1"></div><div class="rail r2"></div><div class="rail r3"></div><div class="rail r4"></div>
+        <div class="orbit node a"><strong>Code delta</strong><span>Changed files enter through the active checkout.</span></div>
+        <div class="orbit node b"><strong>Route owner</strong><span>The repo says which truth surface owns the claim.</span></div>
+        <div class="orbit node c"><strong>Human review</strong><span>Truth diffs sit beside implementation diffs.</span></div>
+        <div class="orbit node d"><strong>Agent host</strong><span>Codex, Claude Code, Copilot, Cursor, OpenCode, and peers read local guidance.</span></div>
+        <div class="orbit core">
+          <h2>Branch truth ledger</h2>
+          <p>A compact view of what this branch changed, which claims are affected, and which docs need curation before handoff.</p>
+          <div class="route-line"><i></i><span>src/webhooks/retry.ts</span><em>engineering/webhook-delivery.md</em></div>
+          <div class="route-line"><i></i><span>README reliability copy</span><em>product/webhook-reliability.md</em></div>
+          <div class="route-line"><i></i><span>operator replay UI</span><em>engineering/webhook-replay.md</em></div>
+        </div>
+      </aside>
+    </section>
+
+    <section id="surface-map" class="shell section">
+      <div class="section-header">
+        <h2>More than a docs generator.</h2>
+        <p>Truthmark is best understood as a repository-truth workflow surface. The value is not one feature; it is how several constraints reinforce each other.</p>
+      </div>
+      <div class="map-grid">
+        <article class="surface-card" data-index="01"><span class="mini-kicker">Operation</span><h3>No resident service in the critical path</h3><p>Helpers can validate and refresh, but the daily closeout path is designed to remain readable from the checkout.</p></article>
+        <article class="surface-card" data-index="02"><span class="mini-kicker">Continuity</span><h3>Truth is maintained after the first draft</h3><p>Code changes keep revisiting the mapped docs, so documentation becomes a living review artifact rather than a launch-week export.</p></article>
+        <article class="surface-card" data-index="03"><span class="mini-kicker">Architecture</span><h3>Routes make ownership explicit</h3><p>Files, areas, and truth docs are connected by committed routing metadata instead of implicit tribal knowledge.</p></article>
+        <article class="surface-card" data-index="04"><span class="mini-kicker">Governance</span><h3>Product truth and mechanics do not collapse together</h3><p>User-facing promises can link to implementation reality without becoming the same document.</p></article>
+        <article class="surface-card" data-index="05"><span class="mini-kicker">Review</span><h3>Claims are small enough for Git</h3><p>The desired unit is a durable claim per line or bullet, making truth updates easy to inspect in pull requests.</p></article>
+        <article class="surface-card" data-index="06"><span class="mini-kicker">Portability</span><h3>Agent guidance follows the repo</h3><p>Generated skills, prompts, commands, and instruction blocks are committed where the agent can read them.</p></article>
+        <article class="surface-card" data-index="07"><span class="mini-kicker">Repair</span><h3>Overgrown docs trigger structure work</h3><p>When a file starts mixing owners, Truth Structure is the product answer, not a larger paragraph.</p></article>
+        <article class="surface-card" data-index="08"><span class="mini-kicker">Boundary</span><h3>Repository files outrank session memory</h3><p>Current truth lives where maintainers can diff, revert, blame, and review it.</p></article>
+      </div>
+    </section>
+
+    <section id="storyboard" class="shell section">
+      <div class="section-header">
+        <h2>A truth document over time.</h2>
+        <p>This demo is fictional, but the workflow is concrete: create the right doc, update it when behavior changes, and split it when ownership gets crowded.</p>
+      </div>
+      <div class="timeline">
+        <div class="tabs" role="tablist" aria-label="Truth document curation timeline">
+          <button class="tab" role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1"><strong>Episode 1 · New invariant</strong>A retry policy appears in code and needs a current-state owner.</button>
+          <button class="tab" role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2"><strong>Episode 2 · Promise pressure</strong>Marketing copy changes; product truth and engineering truth diverge.</button>
+          <button class="tab" role="tab" aria-selected="false" aria-controls="panel-3" id="tab-3"><strong>Episode 3 · Ownership split</strong>Replay, delivery, audit, and alerts no longer belong in one file.</button>
+          <button class="tab" role="tab" aria-selected="false" aria-controls="panel-4" id="tab-4"><strong>Episode 4 · Reviewer packet</strong>The pull request shows implementation, evidence, and truth changes together.</button>
+        </div>
+
+        <article class="panel active" role="tabpanel" id="panel-1" aria-labelledby="tab-1">
+          <div class="panel-head"><strong>Truth Document creates a narrow engineering owner.</strong><span class="status-pill">created</span></div>
+          <div class="panel-grid">
+            <div class="evidence"><span class="label">Evidence read</span><div class="evidence-list"><div class="file-row">src/webhooks/retry-policy.ts</div><div class="file-row">tests/webhooks/retry-policy.test.ts</div><div class="file-row">config/webhook-delivery.yml</div></div></div>
+            <div class="truth-sheet"><span class="label">Created doc</span><h3>Webhook delivery behavior</h3><h4>Current behavior</h4><ul><li class="add">Failed deliveries are retried three times.</li><li class="add">Backoff starts at 30 seconds and doubles per attempt.</li><li class="add">Manual replay remains available after automatic retries stop.</li></ul><h4>Non-goals</h4><ul><li class="quiet">The service does not claim exactly-once delivery.</li></ul></div>
+          </div>
+        </article>
+
+        <article class="panel" role="tabpanel" id="panel-2" aria-labelledby="tab-2">
+          <div class="panel-head"><strong>Truth Sync separates a user promise from runtime mechanics.</strong><span class="status-pill">curated</span></div>
+          <div class="panel-grid">
+            <div class="evidence"><span class="label">Branch changes</span><div class="evidence-list"><div class="file-row">README.md adds operator reliability copy</div><div class="file-row">src/webhooks/replay-audit.ts</div><div class="file-row">tests/webhooks/replay-audit.test.ts</div></div></div>
+            <div class="truth-sheet"><span class="label">Two updated surfaces</span><h3>Product promise vs implementation fact</h3><h4>Product truth</h4><ul><li class="add">Operators can inspect failed delivery history before replay.</li><li class="add">The product presents replay as an operator recovery tool, not an automatic guarantee.</li></ul><h4>Engineering truth</h4><ul><li class="edit">Replay writes an audit row with actor, delivery id, and timestamp.</li><li class="quiet">The retry limit remains unchanged.</li></ul></div>
+          </div>
+        </article>
+
+        <article class="panel" role="tabpanel" id="panel-3" aria-labelledby="tab-3">
+          <div class="panel-head"><strong>Truth Structure changes the shape before prose gets heavier.</strong><span class="status-pill">split</span></div>
+          <div class="panel-grid">
+            <div class="evidence"><span class="label">Topology pressure</span><div class="evidence-list"><div class="file-row">delivery retries + manual replay + alert thresholds + export audit</div><div class="file-row">one doc now has four owners</div><div class="file-row">future edits would be ambiguous</div></div></div>
+            <div class="truth-sheet"><span class="label">New ownership map</span><h3>Owned docs after split</h3><ul><li class="move">engineering/webhook-delivery.md owns retry and delivery lifecycle.</li><li class="move">engineering/webhook-replay.md owns operator replay behavior.</li><li class="move">engineering/webhook-audit.md owns audit rows and export format.</li><li class="move">product/webhook-reliability.md owns customer-facing recovery promises.</li></ul></div>
+          </div>
+        </article>
+
+        <article class="panel" role="tabpanel" id="panel-4" aria-labelledby="tab-4">
+          <div class="panel-head"><strong>The reviewer sees a small packet, not a mystery transcript.</strong><span class="status-pill">review</span></div>
+          <div class="panel-grid">
+            <div class="evidence"><span class="label">Pull request surface</span><div class="evidence-list"><div class="file-row">code diff: retry + replay behavior</div><div class="file-row">test diff: replay audit coverage</div><div class="file-row">truth diff: product + engineering docs</div><div class="file-row">route diff: ownership split</div></div></div>
+            <div class="truth-sheet"><span class="label">Reviewer questions</span><h3>What the PR now answers</h3><ul><li class="add">Which user promise changed?</li><li class="add">Which implementation behavior supports it?</li><li class="add">Which files own future updates?</li><li class="add">Which claims should be rejected if the code changes again?</li></ul></div>
+          </div>
+        </article>
+      </div>
+    </section>
+
+    <section id="lanes" class="shell section">
+      <div class="section-header"><h2>Two lanes, linked on purpose.</h2><p>Truthmark can let product and engineering documents reference each other without forcing them into the same voice or authority level.</p></div>
+      <div class="split-view">
+        <article class="lane"><span class="mini-kicker">Promise lane</span><h3>What the project says users can rely on</h3><p>This lane is for product capabilities, boundaries, acceptance criteria, and non-goals.</p><ul><li>Operators can inspect replay history.</li><li>The workflow is repository-native by default.</li><li>Generated presentation pages are not canonical truth.</li></ul></article>
+        <article class="lane"><span class="mini-kicker">Mechanics lane</span><h3>What the current implementation actually does</h3><p>This lane is for runtime behavior, contracts, operations, architecture, and failure modes.</p><ul><li>Backoff doubles after each failed delivery attempt.</li><li>GitHub Pages deploys the committed static site under site/**.</li><li>Generated surfaces refresh when rendered content changes.</li></ul></article>
+      </div>
+    </section>
+
+    <section id="workflow" class="shell section">
+      <div class="section-header"><h2>The workflow is deliberately boring at runtime.</h2><p>Truthmark's ambition is in the repository model, not in requiring every contributor to adopt a new always-on system.</p></div>
+      <div class="diagram">
+        <div class="diagram-grid" aria-label="Truthmark workflow diagram">
+          <div class="diagram-cell"><strong>1. Setup</strong><span>Configure routes and install agent-facing surfaces.</span></div>
+          <div class="arrow">→</div>
+          <div class="diagram-cell"><strong>2. Work</strong><span>Agent changes code in its normal host.</span></div>
+          <div class="arrow">→</div>
+          <div class="diagram-cell"><strong>3. Closeout</strong><span>Mapped truth docs are checked, edited, split, or left unchanged with evidence.</span></div>
+        </div>
+      </div>
+    </section>
+
+    <section id="install" class="shell section install">
+      <div class="section-header"><h2>Start with the repo, not a server.</h2><p>Install once, commit the workflow surface, and let future branches carry their truth updates through normal review.</p></div>
+      <div class="terminal" aria-label="Install commands"><div class="terminal-top"><span class="term-dot"></span><span class="term-dot"></span><span class="term-dot"></span></div><pre><span class="prompt">$</span> cd /path/to/your-repo
+<span class="prompt">$</span> npm install -g truthmark
+<span class="prompt">$</span> truthmark config
+<span class="prompt">$</span> truthmark init
+<span class="prompt">$</span> truthmark check
+
+<span class="comment"># After setup, agent guidance and truth routes live in the checkout.</span></pre></div>
+    </section>
+  </main>
+
+  <footer class="shell footer"><div>Truthmark keeps current repository truth reviewable where code review already happens.</div><div><a href="https://github.com/merlinhu1/truthmark">GitHub</a> · <a href="https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md">User guide</a></div></footer>
+
+  <script>
+    const tabs = Array.from(document.querySelectorAll('[role="tab"]'));
+    const panels = Array.from(document.querySelectorAll('[role="tabpanel"]'));
+
+    function selectTab(tab) {
+      tabs.forEach((item) => item.setAttribute('aria-selected', String(item === tab)));
+      panels.forEach((panel) => panel.classList.toggle('active', panel.id === tab.getAttribute('aria-controls')));
+    }
+
+    tabs.forEach((tab) => {
+      tab.addEventListener('click', () => selectTab(tab));
+      tab.addEventListener('keydown', (event) => {
+        const index = tabs.indexOf(tab);
+        if (event.key === 'ArrowDown' || event.key === 'ArrowRight') {
+          event.preventDefault();
+          const next = tabs[(index + 1) % tabs.length];
+          next.focus();
+          selectTab(next);
+        }
+        if (event.key === 'ArrowUp' || event.key === 'ArrowLeft') {
+          event.preventDefault();
+          const previous = tabs[(index - 1 + tabs.length) % tabs.length];
+          previous.focus();
+          selectTab(previous);
+        }
+      });
+    });
+  </script>
+</body>
+</html>
@@ -106,8 +106,14 @@ export const FEATURE_DOC_TEMPLATE_INSTRUCTIONS = [
  "Teams may edit template files under the configured Truthmark templates root to define their local truth-doc standards.",
 ].join("\n");

-export const TRUTH_DOC_AUTHORING_STYLE_INSTRUCTIONS =
-  "Prefer diff-friendly Markdown: one durable claim per bullet or line, paragraphs no longer than one or two short sentences, and bullets or tables for rules, criteria, fields, files, and lists.";
+export const TRUTH_DOC_AUTHORING_STYLE_INSTRUCTIONS = [
+  "Truth-doc prose style:",
+  "- Use professional, plain technical prose. Prefer specific current-state claims over promotional, symbolic, or generic significance language.",
+  "- Avoid common AI-writing tells: pivotal, crucial, underscores, serves as, stands as, showcases, landscape, vague expert attributions, and generic upbeat conclusions.",
+  "- Keep claims evidence-backed and diff-friendly: one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences.",
+  "- Do not add personality, rhetorical flourish, first-person commentary, or marketing tone.",
+  "- Rewrite dense or formulaic prose only when it improves readability without removing scope, evidence, decisions, or source references.",
+].join("\n");

 export const renderTruthDocOwnershipGateSection = (
  subject: string,
@@ -20,7 +20,7 @@ const renderMarkdownExample = (content: string): string => {
 };

 export const TRUTH_CHECK_EXPLICIT_INVOCATIONS =
-  "OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Antigravity @truthmark-check; Cursor @truthmark-check.";
+  "OpenCode /skill truthmark-check; Codex /truthmark-check or $truthmark-check; Claude Code /truthmark-check; GitHub Copilot /truthmark-check; Antigravity @truthmark-check; Cursor /truthmark-check.";

 export const renderTruthCheckReportExample = (
  config: TruthmarkConfig = defaultAgentConfig(),
@@ -29,7 +29,7 @@ const renderMarkdownExample = (content: string): string => {
 };

 export const TRUTH_DOCUMENT_EXPLICIT_INVOCATIONS =
-  "OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Antigravity @truthmark-document; Cursor @truthmark-document.";
+  "OpenCode /skill truthmark-document; Codex /truthmark-document or $truthmark-document; Claude Code /truthmark-document; GitHub Copilot /truthmark-document; Antigravity @truthmark-document; Cursor /truthmark-document.";

 export const renderTruthDocumentReportExample = (
  config: TruthmarkConfig = defaultAgentConfig(),
@@ -23,7 +23,7 @@ const renderMarkdownExample = (content: string): string => {
 };

 export const TRUTH_STRUCTURE_EXPLICIT_INVOCATIONS =
-  "OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Antigravity @truthmark-structure; Cursor @truthmark-structure.";
+  "OpenCode /skill truthmark-structure; Codex /truthmark-structure or $truthmark-structure; Claude Code /truthmark-structure; GitHub Copilot /truthmark-structure; Antigravity @truthmark-structure; Cursor /truthmark-structure.";

 export const renderTruthStructureReportExample = (
  config: TruthmarkConfig = defaultAgentConfig(),
@@ -1,6 +1,7 @@
 import type { TruthmarkConfig } from "../config/schema.js";
 import {
  EVIDENCE_AUTHORITY_INSTRUCTIONS,
+  TRUTH_DOC_AUTHORING_STYLE_INSTRUCTIONS,
  defaultAgentConfig,
  renderClaudeSubagentModeSection,
  renderCodexSubagentModeSection,
@@ -17,7 +18,7 @@ import {
 import { getTruthmarkWorkflow } from "./workflow-manifest.js";

 export const TRUTH_SYNC_EXPLICIT_INVOCATIONS =
-  "OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Antigravity @truthmark-sync; Cursor @truthmark-sync.";
+  "OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Antigravity @truthmark-sync; Cursor /truthmark-sync.";

 const renderMarkdownExample = (content: string): string => {
  return ["```md", content, "```"].join("\n");
@@ -139,6 +140,7 @@ ${renderTruthSyncProductDecisionRuleBlock(config)}
   - No-update-needed rationale: why mapped truth is already current when no truth doc should change
   - Blockers: missing routing, ambiguous ownership, failed verification, unavailable evidence, or off-boundary write needs
 11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
+${TRUTH_DOC_AUTHORING_STYLE_INSTRUCTIONS}
 ${subagentMode}Topology review and repair:
 - before updating truth docs, verify the changed code resolves to a specific behavior-owned area and bounded truth owner
 - if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
@@ -191,14 +193,14 @@ ${renderMarkdownExample(
    changedCode: ["src/auth/session.ts"],
    syncIntent: {
      changedCodeReviewed: ["src/auth/session.ts"],
-      affectedRouteOrTruthOwner: [config.truthmark.paths.routesIndex],
-      targetTruthDocs: [
-        `${engineeringTruthRoot}/repository/bootstrap-routing.md`,
+      affectedRouteOrTruthOwner: [
+        `${config.truthmark.paths.routeAreasRoot}/authentication.md`,
      ],
+      targetTruthDocs: [`${engineeringTruthRoot}/behaviors/session-timeout.md`],
      intendedUpdate: ["Update session timeout behavior."],
      evidenceToVerify: [
        "src/auth/session.ts:12",
-        `${config.truthmark.paths.routesIndex}:11`,
+        `${config.truthmark.paths.routeAreasRoot}/authentication.md:11`,
      ],
      userProvidedDecisionRationale: [
        "User rationale: session timeout behavior changed for internal implementation consistency",
@@ -206,23 +208,21 @@ ${renderMarkdownExample(
      noUpdateNeededRationale: ["not applicable; mapped truth is stale"],
      blockers: ["none"],
    },
-    ownershipReviewed: [config.truthmark.paths.routesIndex],
-    truthDocsUpdated: [
-      `${engineeringTruthRoot}/repository/bootstrap-routing.md`,
-    ],
+    ownershipReviewed: [`${config.truthmark.paths.routeAreasRoot}/authentication.md`],
+    truthDocsUpdated: [`${engineeringTruthRoot}/behaviors/session-timeout.md`],
    evidenceChecked: [
      {
        claim:
-          "Session timeout behavior is documented in the mapped repository truth doc.",
+          "Session timeout behavior is documented in the bounded authentication behavior truth doc.",
        evidence: [
          "src/auth/session.ts:12",
-          `${config.truthmark.paths.routesIndex}:11`,
+          `${config.truthmark.paths.routeAreasRoot}/authentication.md:11`,
        ],
        result: "supported",
      },
    ],
    decisionRationaleCaptured: [
-      "Placed user rationale in the mapped engineering truth doc under Engineering Decisions/Rationale.",
+      "Placed user rationale in the bounded authentication behavior truth doc under Engineering Decisions/Rationale.",
    ],
    notes: ["Updated session timeout behavior."],
  }),
@@ -230,9 +230,12 @@ ${renderMarkdownExample(
 Blocked report example:
 ${renderMarkdownExample(
  renderTruthSyncBlockedReport({
-    reason: "routing repair is unsafe or ambiguous",
-    manualReviewFiles: [config.truthmark.paths.routesIndex],
-    nextAction: "run Truth Structure with the listed files before rerunning Truth Sync",
+    reason: "Changed code maps only to the provisional bootstrap route.",
+    manualReviewFiles: [
+      "src/auth/**",
+      `${config.truthmark.paths.routeAreasRoot}/${config.truthmark.routes.defaultArea}.md`,
+    ],
+    nextAction: "Run Truth Structure for src/auth/** before updating behavior truth.",
  }),
 )}`;
 };
@@ -3,7 +3,7 @@ import { defaultAgentConfig, renderHierarchySummary } from "./shared.js";
 import { getTruthmarkWorkflow } from "./workflow-manifest.js";

 export const TRUTHMARK_PORTAL_EXPLICIT_INVOCATIONS =
-  "OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Antigravity @truthmark-portal; Cursor @truthmark-portal.";
+  "OpenCode /skill truthmark-portal; Codex /truthmark-portal or $truthmark-portal; Claude Code /truthmark-portal; GitHub Copilot /truthmark-portal; Antigravity @truthmark-portal; Cursor /truthmark-portal.";

 export const renderTruthmarkPortalProcedureBody = (
  config: TruthmarkConfig = defaultAgentConfig(),
@@ -195,6 +195,17 @@ export const validateTruthSyncReportText = (text: string): WorkflowHelperValidat
        );
      }

+      const completedTargets = [
+        ...report.truthDocsUpdated,
+        ...(report.syncIntent?.targetTruthDocs ?? []),
+      ];
+      const bootstrapTargets = completedTargets.filter(isBootstrapRoutingDocPath);
+      if (bootstrapTargets.length > 0) {
+        errors.push(
+          `bootstrap-routing.md is a provisional topology handoff, not a completed behavior-update target: ${bootstrapTargets.join(", ")}`,
+        );
+      }
+
      if (report.syncIntent !== undefined) {
        checks.push("Sync Intent");
      }
@@ -265,6 +276,8 @@ export const validateTruthDocumentReportText = (text: string): WorkflowHelperVal

 const cleanPathValue = (value: string): string => value.trim().replace(/^["']|["']$/gu, "");
 const normalizePath = (value: string): string => cleanPathValue(value).replace(/^\.\//u, "");
+const isBootstrapRoutingDocPath = (value: string): boolean =>
+  normalizePath(value).endsWith("/bootstrap-routing.md");
 const windowsDriveAbsolutePattern = /^[A-Za-z]:[\\/]/u;
 const uncPathPattern = /^[/\\]{2}[^/\\]+[/\\]+[^/\\]+/u;

@@ -51,6 +51,7 @@ const GENERATED_HOST_SKILL_ROOTS = [
  ".opencode/skills",
  ".claude/skills",
  ".github/skills",
+  ".cursor/skills",
 ] as const;

 const RETIRED_SKILL_HELPER_PATHS = [
@@ -63,10 +64,31 @@ const RETIRED_PACKAGE_DIRECTORIES = ["truthmark-preview"] as const;
 const RETIRED_GENERATED_SURFACE_PATHS = [
  "GEMINI.md",
  ".github/prompts/truthmark-preview.prompt.md",
+  ".cursor/rules/truthmark-structure.mdc",
+  ".cursor/rules/truthmark-document.mdc",
+  ".cursor/rules/truthmark-sync.mdc",
+  ".cursor/rules/truthmark-realize.mdc",
+  ".cursor/rules/truthmark-check.mdc",
+  ".cursor/rules/truthmark-portal.mdc",
 ] as const;

 const RETIRED_GENERATED_SURFACE_ROOTS = [".gemini"] as const;

+const isRetiredGeminiSurfacePath = (filePath: string): boolean =>
+  filePath === "GEMINI.md" || filePath.startsWith(".gemini/");
+
+const obsoleteGeneratedSurfaceMessage = (surfacePath: string): string => {
+  if (isRetiredGeminiSurfacePath(surfacePath)) {
+    return `Generated surface ${surfacePath} is obsolete; remove stale Gemini instructions manually if they are no longer wanted.`;
+  }
+
+  return `Generated surface ${surfacePath} is obsolete; rerun truthmark init.`;
+};
+
+type RetiredSurfaceCollectionOptions = {
+  includeGeminiSurfaces?: boolean;
+};
+
 const pathExists = async (absolutePath: string): Promise<boolean> => {
  try {
    await fs.access(absolutePath);
@@ -116,10 +138,16 @@ const listDirectoryFiles = async (
 const collectRetiredGeneratedSurfaces = async (
  rootDir: string,
  expectedSurfacePaths: Set<string>,
+  options: RetiredSurfaceCollectionOptions = {},
 ): Promise<string[]> => {
  const legacyCandidates = new Set<string>();
+  const includeGeminiSurfaces = options.includeGeminiSurfaces ?? true;

  for (const retiredPath of RETIRED_GENERATED_SURFACE_PATHS) {
+    if (!includeGeminiSurfaces && isRetiredGeminiSurfacePath(retiredPath)) {
+      continue;
+    }
+
    const absoluteRetiredPath = resolveRepoPath(rootDir, retiredPath);

    if (
@@ -131,6 +159,10 @@ const collectRetiredGeneratedSurfaces = async (
  }

  for (const retiredRoot of RETIRED_GENERATED_SURFACE_ROOTS) {
+    if (!includeGeminiSurfaces && isRetiredGeminiSurfacePath(`${retiredRoot}/`)) {
+      continue;
+    }
+
    const absoluteRetiredRoot = resolveRepoPath(rootDir, retiredRoot);

    if (!(await pathExists(absoluteRetiredRoot))) {
@@ -245,7 +277,7 @@ export const checkGeneratedSurfaces = async (
    diagnostics.push({
      category: "generated-surface",
      severity: "review",
-      message: `Generated surface ${surfacePath} is obsolete; rerun truthmark init.`,
+      message: obsoleteGeneratedSurfaceMessage(surfacePath),
      file: surfacePath,
    });
  }
@@ -259,3 +291,12 @@ export const findRetiredGeneratedSurfaces = async (
 ): Promise<string[]> => {
  return collectRetiredGeneratedSurfaces(rootDir, expectedSurfacePaths);
 };
+
+export const findAutoRemovableRetiredGeneratedSurfaces = async (
+  rootDir: string,
+  expectedSurfacePaths: Set<string>,
+): Promise<string[]> => {
+  return collectRetiredGeneratedSurfaces(rootDir, expectedSurfacePaths, {
+    includeGeminiSurfaces: false,
+  });
+};
@@ -6,7 +6,7 @@ import type { CommandResult, DiagnosticCategory } from "../output/diagnostic.js"
 import { getGitRepository } from "../git/repository.js";
 import { resolveRepoPath, type FileWriteResult, writeRepoFile } from "../fs/paths.js";
 import { scaffoldHierarchy } from "./hierarchy.js";
-import { findRetiredGeneratedSurfaces } from "../checks/generated-surfaces.js";
+import { findAutoRemovableRetiredGeneratedSurfaces } from "../checks/generated-surfaces.js";
 import { renderAgentsBlock, TRUTHMARK_BLOCK_END, TRUTHMARK_BLOCK_START } from "../templates/agents-block.js";
 import { renderGeneratedSurfaces, type GeneratedSurface } from "../templates/generated-surfaces.js";

@@ -164,7 +164,8 @@ const diagnosticCategoryForPath = (
    filePath.startsWith(".opencode/skills/truthmark-realize/") ||
    filePath.startsWith(".agents/skills/truthmark-realize/") ||
    filePath.startsWith(".antigravity/rules/truthmark-realize") ||
-    filePath.startsWith(".cursor/rules/truthmark-realize")
+    filePath.startsWith(".cursor/rules/truthmark-realize") ||
+    filePath.startsWith(".cursor/skills/truthmark-realize/")
  ) {
    return "realization";
  }
@@ -181,7 +182,8 @@ const diagnosticCategoryForPath = (
    filePath.startsWith(".opencode/agents/") ||
    filePath.startsWith(".codex/agents/") ||
    filePath.startsWith(".antigravity/rules/truthmark-") ||
-    filePath.startsWith(".cursor/rules/truthmark-")
+    filePath.startsWith(".cursor/rules/truthmark-") ||
+    filePath.startsWith(".cursor/skills/truthmark-")
  ) {
    return "truth-sync";
  }
@@ -265,7 +267,7 @@ export const runInit = async (cwd: string): Promise<CommandResult> => {
    results.push(await writePlatformFile(rootDir, file));
  }

-  const obsoleteSurfacePaths = await findRetiredGeneratedSurfaces(
+  const obsoleteSurfacePaths = await findAutoRemovableRetiredGeneratedSurfaces(
    rootDir,
    expectedSurfacePaths,
  );
@@ -169,6 +169,7 @@ export const classifyPath = (
    normalizedPath.startsWith(".opencode/") ||
    normalizedPath.startsWith(".antigravity/rules/truthmark-") ||
    normalizedPath.startsWith(".cursor/rules/truthmark-") ||
+    normalizedPath.startsWith(".cursor/skills/truthmark-") ||
    normalizedPath === ".github/copilot-instructions.md" ||
    normalizedPath.startsWith(".github/agents/truth-") ||
    normalizedPath.startsWith(".github/prompts/truthmark-") ||
@@ -25,12 +25,6 @@ import {
  renderTruthmarkAntigravityRealizeRule,
  renderTruthmarkAntigravityStructureRule,
  renderTruthmarkAntigravitySyncRule,
-  renderTruthmarkCursorCheckRule,
-  renderTruthmarkCursorDocumentRule,
-  renderTruthmarkCursorPortalRule,
-  renderTruthmarkCursorRealizeRule,
-  renderTruthmarkCursorStructureRule,
-  renderTruthmarkCursorSyncRule,
  renderTruthmarkSkillPackage,
  renderTruthmarkCheckSkillMetadata,
  renderTruthmarkOpenCodeClaimVerifierAgent,
@@ -55,12 +49,12 @@ import {
  TRUTHMARK_ANTIGRAVITY_REALIZE_RULE_PATH,
  TRUTHMARK_ANTIGRAVITY_STRUCTURE_RULE_PATH,
  TRUTHMARK_ANTIGRAVITY_SYNC_RULE_PATH,
-  TRUTHMARK_CURSOR_CHECK_RULE_PATH,
-  TRUTHMARK_CURSOR_DOCUMENT_RULE_PATH,
-  TRUTHMARK_CURSOR_PORTAL_RULE_PATH,
-  TRUTHMARK_CURSOR_REALIZE_RULE_PATH,
-  TRUTHMARK_CURSOR_STRUCTURE_RULE_PATH,
-  TRUTHMARK_CURSOR_SYNC_RULE_PATH,
+  TRUTHMARK_CURSOR_CHECK_SKILL_PATH,
+  TRUTHMARK_CURSOR_DOCUMENT_SKILL_PATH,
+  TRUTHMARK_CURSOR_PORTAL_SKILL_PATH,
+  TRUTHMARK_CURSOR_REALIZE_SKILL_PATH,
+  TRUTHMARK_CURSOR_STRUCTURE_SKILL_PATH,
+  TRUTHMARK_CURSOR_SYNC_SKILL_PATH,
  TRUTHMARK_COPILOT_CLAIM_VERIFIER_AGENT_PATH,
  TRUTHMARK_COPILOT_CHECK_PROMPT_PATH,
  TRUTHMARK_COPILOT_DOCUMENT_PROMPT_PATH,
@@ -444,33 +438,47 @@ const antigravityFiles = (config: TruthmarkConfig): GeneratedSurface[] => {

 const cursorFiles = (config: TruthmarkConfig): GeneratedSurface[] => {
  const files: GeneratedSurface[] = [
-    {
-      path: TRUTHMARK_CURSOR_STRUCTURE_RULE_PATH,
-      content: renderTruthmarkCursorStructureRule(config),
-    },
-    {
-      path: TRUTHMARK_CURSOR_DOCUMENT_RULE_PATH,
-      content: renderTruthmarkCursorDocumentRule(config),
-    },
-    {
-      path: TRUTHMARK_CURSOR_SYNC_RULE_PATH,
-      content: renderTruthmarkCursorSyncRule(config),
-    },
-    {
-      path: TRUTHMARK_CURSOR_CHECK_RULE_PATH,
-      content: renderTruthmarkCursorCheckRule(config),
-    },
-    {
-      path: TRUTHMARK_CURSOR_REALIZE_RULE_PATH,
-      content: renderTruthmarkCursorRealizeRule(config),
-    },
+    ...renderTruthmarkSkillPackage({
+      skillPath: TRUTHMARK_CURSOR_STRUCTURE_SKILL_PATH,
+      workflowId: "truthmark-structure",
+      host: "cursor",
+      config,
+    }),
+    ...renderTruthmarkSkillPackage({
+      skillPath: TRUTHMARK_CURSOR_DOCUMENT_SKILL_PATH,
+      workflowId: "truthmark-document",
+      host: "cursor",
+      config,
+    }),
+    ...renderTruthmarkSkillPackage({
+      skillPath: TRUTHMARK_CURSOR_SYNC_SKILL_PATH,
+      workflowId: "truthmark-sync",
+      host: "cursor",
+      config,
+    }),
+    ...renderTruthmarkSkillPackage({
+      skillPath: TRUTHMARK_CURSOR_CHECK_SKILL_PATH,
+      workflowId: "truthmark-check",
+      host: "cursor",
+      config,
+    }),
+    ...renderTruthmarkSkillPackage({
+      skillPath: TRUTHMARK_CURSOR_REALIZE_SKILL_PATH,
+      workflowId: "truthmark-realize",
+      host: "cursor",
+      config,
+    }),
  ];

  if (config.truthmark.generated.portal.enabled) {
-    files.push({
-      path: TRUTHMARK_CURSOR_PORTAL_RULE_PATH,
-      content: renderTruthmarkCursorPortalRule(config),
-    });
+    files.push(
+      ...renderTruthmarkSkillPackage({
+        skillPath: TRUTHMARK_CURSOR_PORTAL_SKILL_PATH,
+        workflowId: "truthmark-portal",
+        host: "cursor",
+        config,
+      }),
+    );
  }

  return files;
@@ -630,6 +630,16 @@ export const renderBehaviorDocTemplateFile = (): string => {
    "",
    "{{core_rules}}",
    "",
+    "## Behavior Scenarios",
+    "",
+    "<!--",
+    "Use compact scenario blocks only where they clarify normal, fallback, or compatibility-critical behavior.",
+    "Write scenarios as current truth, not desired requirements: `#### Scenario: <implemented case>` followed by `- **GIVEN** ...`, `- **WHEN** ...`, `- **THEN** ...`, and optional `- **AND** ...` bullets.",
+    "Keep each bullet evidence-backed and observable; do not force a scenario for every rule.",
+    "-->",
+    "",
+    "{{behavior_scenarios}}",
+    "",
    "## Flows And States",
    "",
    "<!--",
@@ -133,23 +133,23 @@ export const TRUTHMARK_ANTIGRAVITY_CHECK_RULE_PATH =
 export const TRUTHMARK_ANTIGRAVITY_PORTAL_RULE_PATH =
  ".antigravity/rules/truthmark-portal.md";

-export const TRUTHMARK_CURSOR_STRUCTURE_RULE_PATH =
-  ".cursor/rules/truthmark-structure.mdc";
+export const TRUTHMARK_CURSOR_STRUCTURE_SKILL_PATH =
+  ".cursor/skills/truthmark-structure/SKILL.md";

-export const TRUTHMARK_CURSOR_DOCUMENT_RULE_PATH =
-  ".cursor/rules/truthmark-document.mdc";
+export const TRUTHMARK_CURSOR_DOCUMENT_SKILL_PATH =
+  ".cursor/skills/truthmark-document/SKILL.md";

-export const TRUTHMARK_CURSOR_SYNC_RULE_PATH =
-  ".cursor/rules/truthmark-sync.mdc";
+export const TRUTHMARK_CURSOR_SYNC_SKILL_PATH =
+  ".cursor/skills/truthmark-sync/SKILL.md";

-export const TRUTHMARK_CURSOR_REALIZE_RULE_PATH =
-  ".cursor/rules/truthmark-realize.mdc";
+export const TRUTHMARK_CURSOR_REALIZE_SKILL_PATH =
+  ".cursor/skills/truthmark-realize/SKILL.md";

-export const TRUTHMARK_CURSOR_CHECK_RULE_PATH =
-  ".cursor/rules/truthmark-check.mdc";
+export const TRUTHMARK_CURSOR_CHECK_SKILL_PATH =
+  ".cursor/skills/truthmark-check/SKILL.md";

-export const TRUTHMARK_CURSOR_PORTAL_RULE_PATH =
-  ".cursor/rules/truthmark-portal.mdc";
+export const TRUTHMARK_CURSOR_PORTAL_SKILL_PATH =
+  ".cursor/skills/truthmark-portal/SKILL.md";

 export const TRUTHMARK_COPILOT_STRUCTURE_PROMPT_PATH =
  ".github/prompts/truthmark-structure.prompt.md";
@@ -241,7 +241,8 @@ type TruthmarkSkillPackageHost =
  | "codex"
  | "opencode"
  | "claude-code"
-  | "github-copilot";
+  | "github-copilot"
+  | "cursor";

 type TruthmarkSkillPackageFile = {
  path: string;
@@ -374,14 +375,14 @@ const renderWorkflowReportTemplate = (
          changedCode: ["src/auth/session.ts"],
          syncIntent: {
            changedCodeReviewed: ["src/auth/session.ts"],
-            affectedRouteOrTruthOwner: [config.truthmark.paths.routesIndex],
-            targetTruthDocs: [
-              `${engineeringTruthRoot}/repository/bootstrap-routing.md`,
+            affectedRouteOrTruthOwner: [
+              `${config.truthmark.paths.routeAreasRoot}/authentication.md`,
            ],
+            targetTruthDocs: [`${engineeringTruthRoot}/behaviors/session-timeout.md`],
            intendedUpdate: ["Update session timeout behavior."],
            evidenceToVerify: [
              "src/auth/session.ts:12",
-              `${config.truthmark.paths.routesIndex}:11`,
+              `${config.truthmark.paths.routeAreasRoot}/authentication.md:11`,
            ],
            userProvidedDecisionRationale: [
              "User rationale: session timeout behavior changed for internal implementation consistency",
@@ -389,31 +390,34 @@ const renderWorkflowReportTemplate = (
            noUpdateNeededRationale: ["not applicable; mapped truth is stale"],
            blockers: ["none"],
          },
-          ownershipReviewed: [config.truthmark.paths.routesIndex],
-          truthDocsUpdated: [
-            `${engineeringTruthRoot}/repository/bootstrap-routing.md`,
+          ownershipReviewed: [
+            `${config.truthmark.paths.routeAreasRoot}/authentication.md`,
          ],
+          truthDocsUpdated: [`${engineeringTruthRoot}/behaviors/session-timeout.md`],
          evidenceChecked: [
            {
              claim:
-                "Session timeout behavior is documented in the mapped repository truth doc.",
+                "Session timeout behavior is documented in the bounded authentication behavior truth doc.",
              evidence: [
                "src/auth/session.ts:12",
-                `${config.truthmark.paths.routesIndex}:11`,
+                `${config.truthmark.paths.routeAreasRoot}/authentication.md:11`,
              ],
              result: "supported",
            },
          ],
          decisionRationaleCaptured: [
-            "Placed user rationale in the mapped engineering truth doc under Engineering Decisions/Rationale.",
+            "Placed user rationale in the bounded authentication behavior truth doc under Engineering Decisions/Rationale.",
          ],
          notes: ["Updated session timeout behavior."],
        }),
      )}\nBlocked report example:\n${renderMarkdownExample(
        renderTruthSyncBlockedReport({
-          reason: "routing repair is not allowed",
-          manualReviewFiles: [config.truthmark.paths.routesIndex],
-          nextAction: "update routing metadata and rerun Truth Sync",
+          reason: "Changed code maps only to the provisional bootstrap route.",
+          manualReviewFiles: [
+            "src/auth/**",
+            `${config.truthmark.paths.routeAreasRoot}/${config.truthmark.routes.defaultArea}.md`,
+          ],
+          nextAction: "Run Truth Structure for src/auth/** before updating behavior truth.",
        }),
      )}`;
    case "truthmark-realize":
@@ -526,7 +530,9 @@ const renderWorkflowEntrypoint = (
  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."
-      : undefined;
+      : host === "cursor"
+        ? "Use as a Cursor Agent Skill. Cursor discovers project skills under `.cursor/skills/`, selects them from the description when relevant, and supports manual `/` invocation."
+        : undefined;

  return `---
 name: ${workflowId}
@@ -592,6 +598,8 @@ const renderWorkflowSubagentSupport = (
        definition.parentRule,
        writeAgents,
      );
+    case "cursor":
+      return undefined;
  }
 };

@@ -613,7 +621,11 @@ export const renderTruthmarkSkillPackage = ({
    config,
  );
  const subagents = renderWorkflowSubagentSupport(workflowId, host);
-  const supportFiles = workflowSupportFiles(workflowId);
+  const supportFiles = [
+    "support/procedure.md",
+    "support/report-template.md",
+    ...(subagents !== undefined ? ["support/subagents-and-leases.md"] : []),
+  ];
  const definition = WORKFLOW_PACKAGE_DEFINITIONS[workflowId];
  const files: TruthmarkSkillPackageFile[] = [
    {
@@ -697,7 +709,7 @@ type TruthmarkSubagentProfile = {
 };

 const READ_ONLY_SUBAGENT_CONTEXT_BOUNDARY = `Context boundary:
-Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
+Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.
 Use only the parent-assigned shard plus required checkout evidence files.
 Return findings only; the parent workflow owns repository-policy interpretation, final decisions, and all writes.`;

@@ -1374,13 +1386,11 @@ const renderWorkflowRuleFile = ({
  workflowId,
  hostName,
  ruleName,
-  includeCursorFrontmatter = false,
  config = defaultAgentConfig(),
 }: {
  workflowId: TruthmarkWorkflowId;
  hostName: string;
  ruleName: string;
-  includeCursorFrontmatter?: boolean;
  config?: TruthmarkConfig;
 }): string => {
  const workflow = getTruthmarkWorkflow(workflowId);
@@ -1412,16 +1422,7 @@ ${procedure}
 ${reportTemplate}
 `;

-  if (!includeCursorFrontmatter) {
-    return body;
-  }
-
-  return `---
-description: ${workflow.description}
-alwaysApply: false
---
-
-${body}`;
+  return body;
 };

 const renderCopilotWorkflowPrompt = (
@@ -1501,72 +1502,6 @@ export const renderTruthmarkAntigravityPortalRule = (
    config,
  });

-export const renderTruthmarkCursorStructureRule = (
-  config: TruthmarkConfig = defaultAgentConfig(),
-): string =>
-  renderWorkflowRuleFile({
-    workflowId: "truthmark-structure",
-    hostName: "Cursor",
-    ruleName: "truthmark-structure",
-    includeCursorFrontmatter: true,
-    config,
-  });
-
-export const renderTruthmarkCursorDocumentRule = (
-  config: TruthmarkConfig = defaultAgentConfig(),
-): string =>
-  renderWorkflowRuleFile({
-    workflowId: "truthmark-document",
-    hostName: "Cursor",
-    ruleName: "truthmark-document",
-    includeCursorFrontmatter: true,
-    config,
-  });
-
-export const renderTruthmarkCursorSyncRule = (
-  config: TruthmarkConfig = defaultAgentConfig(),
-): string =>
-  renderWorkflowRuleFile({
-    workflowId: "truthmark-sync",
-    hostName: "Cursor",
-    ruleName: "truthmark-sync",
-    includeCursorFrontmatter: true,
-    config,
-  });
-
-export const renderTruthmarkCursorRealizeRule = (
-  config: TruthmarkConfig = defaultAgentConfig(),
-): string =>
-  renderWorkflowRuleFile({
-    workflowId: "truthmark-realize",
-    hostName: "Cursor",
-    ruleName: "truthmark-realize",
-    includeCursorFrontmatter: true,
-    config,
-  });
-
-export const renderTruthmarkCursorCheckRule = (
-  config: TruthmarkConfig = defaultAgentConfig(),
-): string =>
-  renderWorkflowRuleFile({
-    workflowId: "truthmark-check",
-    hostName: "Cursor",
-    ruleName: "truthmark-check",
-    includeCursorFrontmatter: true,
-    config,
-  });
-
-export const renderTruthmarkCursorPortalRule = (
-  config: TruthmarkConfig = defaultAgentConfig(),
-): string =>
-  renderWorkflowRuleFile({
-    workflowId: "truthmark-portal",
-    hostName: "Cursor",
-    ruleName: "truthmark-portal",
-    includeCursorFrontmatter: true,
-    config,
-  });
-
 export const renderTruthmarkCopilotStructurePrompt = (
  config: TruthmarkConfig = defaultAgentConfig(),
 ): string => {
@@ -1,4 +1,5 @@
 import { execa } from "execa";
+import micromatch from "micromatch";

 import {
  TRUTHMARK_WORKFLOW_MANIFEST,
@@ -78,11 +79,89 @@ const routeFilesFor = (repoIndex: RepoIndex): string[] =>
  uniqueSorted(repoIndex.routeMap.routes.map((route) => route.sourcePath));

 const candidateStaleTruthDocsFor = (
-  indexedTruthDocs: string[],
+  repoIndex: RepoIndex,
  primaryTruthDocs: string[],
+  impactSet: ImpactSet | null,
+  diagnostics: Diagnostic[],
 ): string[] => {
+  const indexedTruthDocs = new Set(
+    repoIndex.routeMap.routes.flatMap((route) => route.truthDocs),
+  );
  const primary = new Set(primaryTruthDocs);
-  return indexedTruthDocs.filter((truthDoc) => !primary.has(truthDoc));
+  const candidates = new Set<string>();
+  const changedPaths = new Set(
+    (impactSet?.changedFiles ?? []).flatMap((file) => [
+      file.path,
+      ...(file.previousPath ? [file.previousPath] : []),
+    ]),
+  );
+  const docEntries = new Map(
+    repoIndex.routeMap.routes
+      .flatMap((route) => route.truthDocumentEntries)
+      .map((entry) => [entry.path, entry]),
+  );
+
+  const addCandidate = (truthDoc: string): void => {
+    if (indexedTruthDocs.has(truthDoc) && !primary.has(truthDoc)) {
+      candidates.add(truthDoc);
+    }
+  };
+
+  const linkedTruthDocs = (truthDoc: string): string[] => {
+    const entry = docEntries.get(truthDoc);
+    return uniqueSorted([
+      ...(entry?.realizedBy ?? []),
+      ...(entry?.realizes ?? []),
+      ...(entry?.dependsOn ?? []),
+      ...[...docEntries.values()]
+        .filter(
+          (candidate) =>
+            candidate.realizedBy.includes(truthDoc) ||
+            candidate.realizes.includes(truthDoc) ||
+            candidate.dependsOn.includes(truthDoc),
+        )
+        .map((candidate) => candidate.path),
+    ]);
+  };
+
+  for (const truthDoc of [...primary, ...changedPaths].filter((path) =>
+    indexedTruthDocs.has(path),
+  )) {
+    for (const linkedTruthDoc of linkedTruthDocs(truthDoc)) {
+      addCandidate(linkedTruthDoc);
+    }
+  }
+
+  for (const diagnostic of diagnostics) {
+    if (diagnostic.category === "freshness" && diagnostic.file) {
+      addCandidate(diagnostic.file);
+    }
+  }
+
+  for (const route of repoIndex.routeMap.routes) {
+    if (changedPaths.has(route.sourcePath)) {
+      route.truthDocs.forEach(addCandidate);
+    }
+  }
+
+  for (const doc of repoIndex.docs) {
+    if (!indexedTruthDocs.has(doc.path) || primary.has(doc.path)) {
+      continue;
+    }
+
+    if (
+      doc.sourceOfTruth.some((reference) =>
+        [...changedPaths].some(
+          (changedPath) =>
+            reference === changedPath || micromatch.isMatch(changedPath, reference),
+        ),
+      )
+    ) {
+      candidates.add(doc.path);
+    }
+  }
+
+  return uniqueSorted([...candidates]);
 };

 const hasUnmappedFunctionalChange = (impactSet: ImpactSet | null): boolean =>
@@ -186,6 +265,7 @@ const contextDataFor = (
  repoIndex: RepoIndex,
  config: Awaited<ReturnType<typeof loadConfig>>["config"],
  impactSet: ImpactSet | null,
+  diagnostics: Diagnostic[],
 ): WorkflowActionContextData => {
  if (!config) {
    return {};
@@ -198,7 +278,12 @@ const contextDataFor = (
  const primaryTruthDocs = uniqueSorted(impactSet?.affectedTruthDocs ?? []);
  const candidateStaleTruthDocs =
    workflow === "truthmark-sync"
-      ? candidateStaleTruthDocsFor(indexedTruthDocs, primaryTruthDocs)
+      ? candidateStaleTruthDocsFor(
+          repoIndex,
+          primaryTruthDocs,
+          impactSet,
+          diagnostics,
+        )
      : [];
  const truthDocs =
    workflow === "truthmark-sync"
@@ -297,6 +382,7 @@ export const buildWorkflowState = async (
          repoIndex,
          loadResult.config,
          impactSet,
+          diagnostics,
        );

  return {
@@ -15,7 +15,7 @@ describe("renderTruthSyncInstructions", () => {
    expect(instructions).toContain("Automatic finish-time trigger");
    expect(instructions).toContain("use the truthmark-sync skill before finishing");
    expect(instructions).toContain(
-      "OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Antigravity @truthmark-sync; Cursor @truthmark-sync",
+      "OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Antigravity @truthmark-sync; Cursor /truthmark-sync",
    );
    expect(instructions).toContain("staged, unstaged, and untracked functional code files");
    expect(instructions).toContain("Run relevant tests before finishing");
@@ -32,7 +32,7 @@ describe("renderTruthCheckSkillBody", () => {
  it("renders the agent-led truth audit workflow", () => {
    const skill = renderTruthCheckSkillBody();

-    expect(TRUTH_CHECK_EXPLICIT_INVOCATIONS).toContain("Cursor @truthmark-check");
+    expect(TRUTH_CHECK_EXPLICIT_INVOCATIONS).toContain("Cursor /truthmark-check");
    expect(skill).toContain("name: truthmark-check");
    expect(skill).toContain(
      "description: Use when the user asks to audit repository truth health, routing, ownership, or canonical docs.",
@@ -84,7 +84,7 @@ describe("renderTruthCheckSkillBody", () => {

 describe("Truth Check generated surfaces", () => {
  const readOnlyContextBoundary =
-    "Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.";
+    "Do not preload AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .cursor/skills, .antigravity/rules, or repo-wide policy docs unless the parent explicitly assigns them as evidence.";

  it("renders Codex metadata and OpenCode skill content", () => {
    expect(renderTruthmarkCheckSkill()).toContain("name: truthmark-check");
@@ -13,7 +13,7 @@ import {
  renderTruthmarkDocumentLocalSkill,
  renderTruthmarkDocumentSkill,
  renderTruthmarkDocumentSkillMetadata,
-  renderTruthmarkCursorDocumentRule,
+  renderTruthmarkSkillPackage,
 } from "../../src/templates/workflow-surfaces.js";

 describe("renderTruthDocumentSkillBody", () => {
@@ -37,7 +37,7 @@ describe("renderTruthDocumentSkillBody", () => {
  it("renders the manual existing-implementation documentation workflow", () => {
    const skill = renderTruthDocumentSkillBody();

-    expect(TRUTH_DOCUMENT_EXPLICIT_INVOCATIONS).toContain("Cursor @truthmark-document");
+    expect(TRUTH_DOCUMENT_EXPLICIT_INVOCATIONS).toContain("Cursor /truthmark-document");
    expect(skill).toContain("name: truthmark-document");
    expect(skill).toContain("manual and implementation-first");
    expect(skill).toContain("existing implemented behavior");
@@ -45,7 +45,17 @@ describe("renderTruthDocumentSkillBody", () => {
    expect(skill).toContain("must not write functional code");
    expect(skill).toContain("configured Truthmark templates root");
    expect(skill).toContain("When creating or updating a truth doc");
-    expect(skill).toContain("Prefer diff-friendly Markdown: one durable claim per bullet or line");
+    expect(skill).toContain("Truth-doc prose style:");
+    expect(skill).toContain("Use professional, plain technical prose");
+    expect(skill).toContain("Prefer specific current-state claims over promotional, symbolic, or generic significance language");
+    expect(skill).toContain("Avoid common AI-writing tells");
+    expect(skill).toContain(
+      "one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences",
+    );
+    expect(skill).toContain("Do not add personality, rhetorical flourish, first-person commentary, or marketing tone");
+    expect(skill).toContain("without removing scope, evidence, decisions, or source references");
+    expect(skill).not.toContain("PERSONALITY AND SOUL");
+    expect(skill).not.toContain("What makes the below so obviously AI generated?");
    expect(skill).toContain("HTML comments under each template section");
    expect(skill).toContain("normative authoring guidance");
    expect(skill).toContain("Truth-doc ownership review");
@@ -177,7 +187,7 @@ describe("Truth Document generated surfaces", () => {
      "Claude Code subagent mode:",
    );
    expect(renderTruthmarkDocumentLocalSkill()).not.toContain("OpenCode /skill truthmark-document");
-    expect(renderTruthmarkDocumentLocalSkill()).not.toContain("Cursor @truthmark-document");
+    expect(renderTruthmarkDocumentLocalSkill()).not.toContain("Cursor /truthmark-document");
    expect(renderTruthmarkDocumentSkillMetadata()).toContain(
      'display_name: "Truthmark Document"',
    );
@@ -187,16 +197,29 @@ describe("Truth Document generated surfaces", () => {
    expect(renderTruthmarkDocumentSkillMetadata()).toContain(
      'refresh_command: "truthmark init"',
    );
-    expect(renderTruthmarkCursorDocumentRule()).toContain(
-      "This rule is the Cursor entrypoint for Truthmark Document.",
-    );
+    const cursorDocumentPackage = renderTruthmarkSkillPackage({
+      skillPath: ".cursor/skills/truthmark-document/SKILL.md",
+      workflowId: "truthmark-document",
+      host: "cursor",
+    });
+    const cursorDocumentSkill =
+      cursorDocumentPackage.find((file) => file.path.endsWith("/SKILL.md"))?.content ?? "";
+    const cursorDocumentProcedure =
+      cursorDocumentPackage.find((file) => file.path.endsWith("/support/procedure.md"))
+        ?.content ?? "";
+    const cursorDocumentReportTemplate =
+      cursorDocumentPackage.find((file) => file.path.endsWith("/support/report-template.md"))
+        ?.content ?? "";
+
+    expect(cursorDocumentSkill).toContain("Use as a Cursor Agent Skill.");
+    expect(cursorDocumentSkill).toContain(".cursor/skills/");
+    expect(cursorDocumentSkill).toContain("Progressive disclosure:");
+    expect(cursorDocumentSkill).toContain("support/procedure.md");
+    expect(cursorDocumentSkill).toContain("support/report-template.md");
    expect(renderTruthmarkCopilotDocumentPrompt()).toContain(
      "This prompt is the GitHub Copilot entrypoint for Truthmark Document.",
    );
-    for (const surface of [
-      renderTruthmarkCursorDocumentRule(),
-      renderTruthmarkCopilotDocumentPrompt(),
-    ]) {
+    for (const surface of [renderTruthmarkCopilotDocumentPrompt()]) {
      expect(surface).toContain("Do not invoke another Truthmark command from here.");
      expect(surface).toContain(
        "If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.",
@@ -210,12 +233,8 @@ describe("Truth Document generated surfaces", () => {
    expect(renderTruthmarkCopilotDocumentPrompt()).toContain(
      "support/report-template.md",
    );
-    expect(renderTruthmarkCursorDocumentRule()).not.toContain(
-      "support/procedure.md",
-    );
-    expect(renderTruthmarkCursorDocumentRule()).not.toContain(
-      "support/report-template.md",
-    );
-    expect(renderTruthmarkCursorDocumentRule()).not.toContain("Quick procedure:");
+    expect(cursorDocumentProcedure).toContain("Truthmark Document Procedure");
+    expect(cursorDocumentProcedure).not.toContain("Report completion in this shape:");
+    expect(cursorDocumentReportTemplate).toContain("Report completion in this shape:");
  });
 });
@@ -13,7 +13,6 @@ import {
 } from "../../src/agents/truth-sync.js";
 import {
  renderTruthmarkCopilotSyncPrompt,
-  renderTruthmarkCursorSyncRule,
  renderTruthmarkSyncClaudeSkill,
  renderTruthmarkSyncLocalSkill,
  renderTruthmarkSkillPackage,
@@ -25,7 +24,7 @@ describe("renderTruthSyncWorkerPrompt", () => {
  it("renders the prepared-context worker contract and result shape", () => {
    const prompt = renderTruthSyncWorkerPrompt();

-    expect(TRUTH_SYNC_EXPLICIT_INVOCATIONS).toContain("Cursor @truthmark-sync");
+    expect(TRUTH_SYNC_EXPLICIT_INVOCATIONS).toContain("Cursor /truthmark-sync");
    expect(prompt).toContain("parent provides the task focus");
    expect(prompt).toContain("explicit write lease");
    expect(prompt).toContain(
@@ -133,6 +132,15 @@ describe("renderTruthSyncSkillBody", () => {
      "Only edit allowed truth docs/routes after Sync Intent is clear",
    );
    expect(skillBody).toContain("Evidence checked");
+    expect(skillBody).toContain("Truth-doc prose style:");
+    expect(skillBody).toContain("Use professional, plain technical prose");
+    expect(skillBody).toContain("Avoid common AI-writing tells");
+    expect(skillBody).toContain(
+      "one durable claim per bullet or line; paragraphs should be no longer than one or two short sentences",
+    );
+    expect(skillBody).toContain("Do not add personality, rhetorical flourish, first-person commentary, or marketing tone");
+    expect(skillBody).not.toContain("PERSONALITY AND SOUL");
+    expect(skillBody).not.toContain("What makes the below so obviously AI generated?");
    expect(skillBody).toContain("Claim:");
    expect(skillBody).toContain("Result: supported");
    expect(skillBody).toContain("structured Truth Sync report contract");
@@ -158,9 +166,9 @@ describe("renderTruthSyncSkillBody", () => {
    const skillBody = renderTruthSyncSkillBody(config);

    expect(skillBody).toContain(
-      "docs/truthmark/engineering/repository/bootstrap-routing.md",
+      "docs/truthmark/engineering/behaviors/session-timeout.md",
    );
-    expect(skillBody).toContain("docs/routes/index.md:11");
+    expect(skillBody).toContain("docs/routes/areas/authentication.md:11");
    expect(skillBody).toContain(
      "verify only truth docs and leased truth routing files changed",
    );
@@ -280,22 +288,30 @@ describe("Truth Sync generated metadata", () => {
      'short_description: "Sync truth docs from functional code changes; skip docs-only/no-code changes"',
    );
    expect(metadata).toContain("allow_implicit_invocation: true");
-    expect(renderTruthmarkCursorSyncRule()).toContain(
+    const cursorSyncPackage = renderTruthmarkSkillPackage({
+      skillPath: ".cursor/skills/truthmark-sync/SKILL.md",
+      workflowId: "truthmark-sync",
+      host: "cursor",
+    });
+    const cursorSyncSkill =
+      cursorSyncPackage.find((file) => file.path.endsWith("/SKILL.md"))?.content ?? "";
+    const cursorSyncProcedure =
+      cursorSyncPackage.find((file) => file.path.endsWith("/support/procedure.md"))
+        ?.content ?? "";
+
+    expect(cursorSyncSkill).toContain(
      'description: Use automatically at finish-time after functional code changes',
    );
+    expect(cursorSyncSkill).toContain("Use as a Cursor Agent Skill.");
+    expect(cursorSyncSkill).toContain("support/procedure.md");
+    expect(cursorSyncSkill).toContain("support/report-template.md");
    expect(renderTruthmarkCopilotSyncPrompt()).toContain(
      "description: 'Use automatically at finish-time after functional code changes",
    );
-    expect(renderTruthmarkCursorSyncRule()).toContain(
-      "This rule is the Cursor entrypoint for Truthmark Sync.",
-    );
    expect(renderTruthmarkCopilotSyncPrompt()).toContain(
      "This prompt is the GitHub Copilot entrypoint for Truthmark Sync.",
    );
-    for (const surface of [
-      renderTruthmarkCursorSyncRule(),
-      renderTruthmarkCopilotSyncPrompt(),
-    ]) {
+    for (const surface of [renderTruthmarkCopilotSyncPrompt()]) {
      expect(surface).toContain(
        "If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.",
      );
@@ -311,11 +327,8 @@ describe("Truth Sync generated metadata", () => {
    expect(renderTruthmarkCopilotSyncPrompt()).toContain(
      "support/report-template.md",
    );
-    expect(renderTruthmarkCursorSyncRule()).not.toContain("support/procedure.md");
-    expect(renderTruthmarkCursorSyncRule()).not.toContain(
-      "support/report-template.md",
-    );
-    expect(renderTruthmarkCursorSyncRule()).not.toContain("Quick procedure:");
+    expect(cursorSyncProcedure).toContain("Truthmark Sync Procedure");
+    expect(cursorSyncProcedure).not.toContain("Report completion in this shape:");
  });

  it("adds host-specific subagent guidance without changing generic surfaces", () => {
@@ -356,7 +369,14 @@ describe("Truth Sync generated metadata", () => {
    expect(renderTruthmarkSyncLocalSkill()).not.toContain(
      "Claude Code subagent mode:",
    );
-    expect(renderTruthmarkCursorSyncRule()).not.toContain(
+    const cursorSyncProcedure =
+      renderTruthmarkSkillPackage({
+        skillPath: ".cursor/skills/truthmark-sync/SKILL.md",
+        workflowId: "truthmark-sync",
+        host: "cursor",
+      }).find((file) => file.path.endsWith("/support/procedure.md"))?.content ?? "";
+
+    expect(cursorSyncProcedure).not.toContain(
      "Codex subagent mode:",
    );
    expect(renderTruthmarkCopilotSyncPrompt()).not.toContain(
@@ -958,7 +958,7 @@ Update truth when:
    }
  });

-  it("reports stale generated Cursor rule surfaces when configured", async () => {
+  it("reports stale generated Cursor skill surfaces when configured", async () => {
    const repo = await createTempRepo();

    try {
@@ -986,8 +986,8 @@ ignore: []
      );
      await runInit(repo.rootDir);
      await repo.writeFile(
-        ".cursor/rules/truthmark-sync.mdc",
-        `${await repo.readFile(".cursor/rules/truthmark-sync.mdc")}\n# stale\n`,
+        ".cursor/skills/truthmark-sync/SKILL.md",
+        `${await repo.readFile(".cursor/skills/truthmark-sync/SKILL.md")}\n# stale\n`,
      );

      const result = await runCheck(repo.rootDir);
@@ -997,7 +997,7 @@ ignore: []
          expect.objectContaining({
            category: "generated-surface",
            severity: "review",
-            file: ".cursor/rules/truthmark-sync.mdc",
+            file: ".cursor/skills/truthmark-sync/SKILL.md",
            message: expect.stringContaining("stale"),
          }),
        ]),
@@ -126,6 +126,39 @@ describe("truthmark validate CLI helpers", () => {
    }
  });

+  it("rejects bootstrap-routing as a completed behavior-update target", async () => {
+    const repo = await createTempRepo();
+    try {
+      await repo.writeFile(
+        "report.md",
+        validSyncReportWithIntent
+          .replace(
+            "docs/truthmark/truth/init-and-scaffold.md",
+            "docs/truthmark/engineering/repository/bootstrap-routing.md",
+          )
+          .replace(
+            "docs/truthmark/truth/init-and-scaffold.md",
+            "docs/truthmark/engineering/repository/bootstrap-routing.md",
+          ),
+      );
+
+      const result = await runCli(["validate", "sync-report", "report.md", "--json"], {
+        cwd: repo.rootDir,
+      });
+      const output = JSON.parse(result.stdout) as {
+        data?: { validation?: { ok: boolean; errors?: string[] } };
+      };
+
+      expect(result.exitCode).toBe(1);
+      expect(output.data?.validation?.ok).toBe(false);
+      expect(output.data?.validation?.errors?.join("\n")).toContain(
+        "bootstrap-routing.md is a provisional topology handoff",
+      );
+    } finally {
+      await repo.cleanup();
+    }
+  });
+
  it("validates document reports through the Truthmark CLI", async () => {
    const repo = await createTempRepo();
    try {
@@ -90,7 +90,7 @@ ignore: []
    }
  });

-  it("removes retired generated surfaces from older versions", async () => {
+  it("removes auto-removable retired generated surfaces but preserves stale Gemini surfaces", async () => {
    const repo = await createTempRepo();

    try {
@@ -140,17 +140,17 @@ ignore: []
      ).rejects.toThrow();
      await expect(
        fs.stat(`${repo.rootDir}/.gemini/commands/truthmark/preview.toml`),
-      ).rejects.toThrow();
-      await expect(fs.stat(`${repo.rootDir}/GEMINI.md`)).rejects.toThrow();
+      ).resolves.toBeDefined();
+      await expect(fs.stat(`${repo.rootDir}/GEMINI.md`)).resolves.toBeDefined();
      await expect(
        fs.stat(`${repo.rootDir}/.gemini/skills/truthmark-sync/SKILL.md`),
-      ).rejects.toThrow();
+      ).resolves.toBeDefined();
      await expect(
        fs.stat(`${repo.rootDir}/.gemini/agents/truth-doc-writer.md`),
-      ).rejects.toThrow();
+      ).resolves.toBeDefined();
      await expect(
        fs.stat(`${repo.rootDir}/.gemini/commands/truthmark/sync.toml`),
-      ).rejects.toThrow();
+      ).resolves.toBeDefined();
      await expect(
        fs.stat(`${repo.rootDir}/.agents/skills/truthmark-sync/helper-manifest.yml`),
      ).rejects.toThrow();
@@ -0,0 +1,42 @@
+import fs from "node:fs/promises";
+
+import { describe, expect, it } from "vitest";
+
+import { renderBehaviorDocTemplateFile } from "../../src/templates/init-files.js";
+
+const behaviorTruthDocs = [
+  "docs/truthmark/engineering/behaviors/check-diagnostics.md",
+  "docs/truthmark/engineering/behaviors/init-and-scaffold.md",
+  "docs/truthmark/engineering/repository/overview.md",
+  "docs/truthmark/engineering/repository/repository-intelligence.md",
+];
+
+describe("truth doc templates", () => {
+  it("guides engineering behavior docs toward current-state scenario blocks", () => {
+    const template = renderBehaviorDocTemplateFile();
+
+    expect(template).toContain("## Behavior Scenarios");
+    expect(template).toContain(
+      "Use compact scenario blocks only where they clarify normal, fallback, or compatibility-critical behavior.",
+    );
+    expect(template).toContain("#### Scenario: <implemented case>");
+    expect(template).toContain("- **GIVEN** ...");
+    expect(template).toContain("- **WHEN** ...");
+    expect(template).toContain("- **THEN** ...");
+    expect(template).toContain("- **AND** ...");
+    expect(template).toContain("current truth, not desired requirements");
+    expect(template).not.toContain("SHALL");
+  });
+
+  it("keeps existing engineering behavior docs aligned with the scenario section", async () => {
+    for (const path of behaviorTruthDocs) {
+      const doc = await fs.readFile(path, "utf8");
+
+      expect(doc, path).toContain("truth_kind: engineering-behavior");
+      expect(doc, path).toContain("## Behavior Scenarios");
+      expect(doc, path).toContain("- **GIVEN**");
+      expect(doc, path).toContain("- **WHEN**");
+      expect(doc, path).toContain("- **THEN**");
+    }
+  });
+});
@@ -76,8 +76,8 @@ describe("installed workflow contract", () => {
      const antigravitySyncRule = await repo.readFile(
        ".antigravity/rules/truthmark-sync.md",
      );
-      const cursorSyncRule = await repo.readFile(
-        ".cursor/rules/truthmark-sync.mdc",
+      const cursorSyncSkill = await repo.readFile(
+        ".cursor/skills/truthmark-sync/SKILL.md",
      );

      expect(agents.split("\n").length).toBeLessThanOrEqual(20);
@@ -163,7 +163,8 @@ describe("installed workflow contract", () => {
      await expect(repo.readFile(".gemini/skills/truthmark-sync/SKILL.md")).rejects.toThrow();
      await expect(repo.readFile(".gemini/commands/truthmark/sync.toml")).rejects.toThrow();
      expect(antigravitySyncRule).toContain("This rule is the Antigravity entrypoint");
-      expect(cursorSyncRule).toContain("This rule is the Cursor entrypoint");
+      expect(cursorSyncSkill).toContain("Use as a Cursor Agent Skill.");
+      expect(cursorSyncSkill).toContain("support/procedure.md");
      expect(checkSkill).toContain("name: truthmark-check");
      expect(checkSkill).toContain("support/report-template.md");
      expect(checkSkill).toContain("support/subagents-and-leases.md");
@@ -87,9 +87,7 @@ describe("package and release integrity", () => {
  it("includes localized README files linked from the published README", async () => {
    const tarballPaths = (await readPackFiles()).map((file) => file.path);

-    expect(tarballPaths).toEqual(
-      expect.arrayContaining(localizedReadmeFiles),
-    );
+    expect(tarballPaths).toEqual(expect.arrayContaining(localizedReadmeFiles));
  });

  it("publishes only expected files with intentional executable modes", async () => {
@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { describe, expect, it } from "vitest";

 import { createDefaultConfig } from "../../src/config/defaults.js";
+import { renderTruthSyncSkillBody } from "../../src/agents/truth-sync.js";
 import { renderAgentsBlock } from "../../src/templates/agents-block.js";
 import { renderGeneratedSurfaces } from "../../src/templates/generated-surfaces.js";

@@ -24,7 +25,7 @@ const portalPaths = [
  ".github/skills/truthmark-portal/SKILL.md",
  ".github/prompts/truthmark-portal.prompt.md",
  ".antigravity/rules/truthmark-portal.md",
-  ".cursor/rules/truthmark-portal.mdc",
+  ".cursor/skills/truthmark-portal/SKILL.md",
 ];

 const readOnlyProcedurePaths = [
@@ -92,8 +93,7 @@ describe("Truthmark Portal generated surfaces", () => {
      (surface) =>
        surface.path.endsWith("/SKILL.md") ||
        surface.path.startsWith(".github/prompts/") ||
-        surface.path.startsWith(".antigravity/rules/") ||
-        surface.path.startsWith(".cursor/rules/"),
+        surface.path.startsWith(".antigravity/rules/"),
    );
    const forbiddenText = [
      "## Optional local CLI validation",
@@ -209,7 +209,9 @@ describe("Truthmark Portal generated surfaces", () => {
    expect(byPath.has(".gemini/skills/truthmark-sync/SKILL.md")).toBe(false);
    expect(byPath.has(".gemini/commands/truthmark/sync.toml")).toBe(false);
    expect(byPath.has(".antigravity/rules/truthmark-sync.md")).toBe(true);
-    expect(byPath.has(".cursor/rules/truthmark-sync.mdc")).toBe(true);
+    expect(byPath.has(".cursor/skills/truthmark-sync/SKILL.md")).toBe(true);
+    expect(byPath.has(".cursor/skills/truthmark-sync/support/procedure.md")).toBe(true);
+    expect(byPath.has(".cursor/skills/truthmark-sync/support/report-template.md")).toBe(true);
    expect(byPath.has(".agents/skills/truthmark-preview/agents/openai.yaml")).toBe(
      false,
    );
@@ -250,6 +252,62 @@ describe("Truthmark Portal generated surfaces", () => {
    expect(claudeProcedure).not.toContain("truthmark:adapter-mode=expanded-adapter");
  });

+  it("does not teach Sync to update bootstrap routing as behavior truth", () => {
+    const config = createDefaultConfig();
+    config.platforms = [...allPlatforms];
+    const renderedSurfaces = renderGeneratedSurfaces(config);
+    const generatedSyncReportSurfaces = renderedSurfaces.filter(
+      (surface) =>
+        surface.path.endsWith("truthmark-sync/support/report-template.md") ||
+        surface.path === ".antigravity/rules/truthmark-sync.md" ||
+        surface.path === ".cursor/skills/truthmark-sync/support/report-template.md",
+    );
+    const checkedInSyncReportPaths = [
+      ".agents/skills/truthmark-sync/support/report-template.md",
+      ".opencode/skills/truthmark-sync/support/report-template.md",
+      ".claude/skills/truthmark-sync/support/report-template.md",
+      ".github/skills/truthmark-sync/support/report-template.md",
+      ".antigravity/rules/truthmark-sync.md",
+      ".cursor/skills/truthmark-sync/support/report-template.md",
+    ];
+    const surfacesToCheck = [
+      { path: "renderTruthSyncSkillBody", content: renderTruthSyncSkillBody(config) },
+      ...generatedSyncReportSurfaces,
+      ...checkedInSyncReportPaths.map((path) => ({
+        path,
+        content: readFileSync(join(process.cwd(), path), "utf8"),
+      })),
+    ];
+
+    expect(generatedSyncReportSurfaces.length).toBeGreaterThan(0);
+    for (const surface of surfacesToCheck) {
+      expect(surface.content, surface.path).toContain(
+        "docs/truthmark/routes/areas/authentication.md",
+      );
+      expect(surface.content, surface.path).toContain(
+        "docs/truthmark/engineering/behaviors/session-timeout.md",
+      );
+      expect(surface.content, surface.path).toContain(
+        "Changed code maps only to the provisional bootstrap route.",
+      );
+      expect(surface.content, surface.path).toContain(
+        "Run Truth Structure for src/auth/** before updating behavior truth.",
+      );
+      expect(surface.content, surface.path).not.toContain(
+        "- Target truth docs: docs/truthmark/engineering/repository/bootstrap-routing.md",
+      );
+      expect(surface.content, surface.path).not.toContain(
+        [
+          "Truth docs updated:",
+          "- docs/truthmark/engineering/repository/bootstrap-routing.md",
+        ].join("\n"),
+      );
+      expect(surface.content, surface.path).not.toContain(
+        "Session timeout behavior is documented in the mapped repository truth doc.",
+      );
+    }
+  });
+
  it("omits Portal surfaces and AGENTS wording when disabled", () => {
    const config = createDefaultConfig();
    const paths = renderGeneratedSurfaces(config).map(
@@ -287,7 +345,9 @@ describe("Truthmark Portal generated surfaces", () => {
      byPath.get(".github/prompts/truthmark-portal.prompt.md") ?? "";
    const antigravityRule =
      byPath.get(".antigravity/rules/truthmark-portal.md") ?? "";
-    const cursorRule = byPath.get(".cursor/rules/truthmark-portal.mdc") ?? "";
+    const cursorSkill = byPath.get(".cursor/skills/truthmark-portal/SKILL.md") ?? "";
+    const cursorProcedure =
+      byPath.get(".cursor/skills/truthmark-portal/support/procedure.md") ?? "";
    const agentsBlock = renderAgentsBlock(config);

    for (const text of [portalSkill, portalProcedure]) {
@@ -309,10 +369,10 @@ describe("Truthmark Portal generated surfaces", () => {
    expect(antigravityRule).toContain(
      "This rule is the Antigravity entrypoint for Truthmark Portal.",
    );
-    expect(cursorRule).toContain(
-      "This rule is the Cursor entrypoint for Truthmark Portal.",
-    );
-    expect(cursorRule).toContain("alwaysApply: false");
+    expect(cursorSkill).toContain("Use as a Cursor Agent Skill.");
+    expect(cursorSkill).toContain(".cursor/skills/");
+    expect(cursorSkill).toContain("Progressive disclosure:");
+    expect(cursorProcedure).toContain("manual-only");

    expect(portalProcedure).toContain("replace the entire output directory");
    expect(portalProcedure).toContain("fixed Portal output directory only");
@@ -278,7 +278,7 @@ describe("buildWorkflowState", () => {
    expect(JSON.stringify(state)).not.toContain('"content":');
  });

-  it("authorizes sync to correct any indexed truth docs and routing files", async () => {
+  it("authorizes sync to correct signal-linked truth docs and routing files", async () => {
    const repo = await setupConfiguredRepo({ includeUnrelatedRoute: true });
    repos.push(repo);

@@ -292,14 +292,14 @@ describe("buildWorkflowState", () => {
    ]);
    expect(state.targetTruthDocs).toEqual(["docs/truthmark/engineering/repository/bootstrap-routing.md"]);
    expect(state.actionContext.allowedWritePaths).toEqual(
-      expect.arrayContaining([
+      [
        "docs/truthmark/engineering/repository/bootstrap-routing.md",
-        "docs/truthmark/engineering/unrelated.md",
        "docs/truthmark/routes/areas.md",
        "docs/truthmark/routes/areas/repository.md",
        "docs/truthmark/routes/areas/unrelated.md",
-      ]),
+      ],
    );
+    expect(state.actionContext.candidateStaleTruthDocs).toEqual([]);
  });

  it("does not expose a legacy ContextPack opt-in path", async () => {
Author	SHA1	Message	Date
MerlinH	932a08ed93	ci: remove openssf scorecard	2026-06-27 01:23:24 +10:00
Merlin's Cat GitHub MerlinH	3c52f21d90	feat: add static introduction website (#29 ) * feat: add static introduction website * feat: expand static website positioning * feat: redesign site with original visuals * docs(readme): add package status badges * ci: add project readiness automation * ci: restrict scorecard workflow permissions * ci: remove duplicate readiness config * ci: pin workflow actions by sha * docs: add scorecard badge --------- Co-authored-by: MerlinH <merlinh221@gmail.com>	2026-06-27 01:15:39 +10:00
Merlin's Cat GitHub MerlinH	15b8bb94e9	chore: prepare Truthmark 2.2.6 (#28 ) * feat: add compact truth-doc prose guidance * chore: prepare Truthmark 2.2.6 * fix: preserve truth doc line discipline * docs: emphasize ongoing truth curation * docs(truth): add behavior scenarios to truth docs --------- Co-authored-by: MerlinH <merlinh221@gmail.com>	2026-06-27 00:05:15 +10:00
MerlinH	f599b15238	fix: publish npm from release tags	2026-06-22 18:07:08 +10:00
Merlin's Cat GitHub MerlinH	7e60fbce68	chore: prepare Truthmark 2.2.5 (#26 ) Co-authored-by: MerlinH <merlinh221@gmail.com>	2026-06-22 03:28:02 +10:00