feat: v2.3.0 add interactive platform selection to init (#38 )

* feat: add interactive platform selection to init * chore: remove completed OpenSpec artifacts * chore: remove implemented design note * fix: protect init lifecycle from unsafe config paths * fix: support clearing init platforms from CLI * docs: retire config command from repository rules * docs: align init lifecycle and clear-platform contracts * docs: keep repository guidance current-state focused * docs: limit cleanup to repository-native documents * docs: preserve historical version notes --------- Co-authored-by: MerlinH <merlinh221@gmail.com>
chore(deps): bump the npm_and_yarn group across 1 directory with 2 updates (#35 )
2026-08-25 07:53:25 +02:00 · 2026-07-31 18:54:10 +10:00 · 2026-07-30 23:03:23 +10:00 · 2026-07-28 09:27:55 +10:00 · 2026-07-27 00:19:37 +10:00 · 2026-07-25 23:06:59 +10:00
374 changed files with 12737 additions and 8279 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
@@ -35,3 +35,7 @@ Thumbs.db
 .hermes/
 .lean-ctx/graph.db
 .lean-ctx/graph.meta.json
+
+# Manual workflow eval run artifacts
+workflow-eval-framwork/runs/*
+!workflow-eval-framwork/runs/.gitkeep
@@ -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.
 ```
@@ -11,8 +11,6 @@ truthmark:
  generated:
    portal:
      enabled: false
-instruction_targets:
-  - AGENTS.md
 frontmatter:
  required: []
  recommended:
@@ -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)
@@ -13,30 +20,22 @@ Run this inside the Git repository you want Truthmark to manage:
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-Enable the AI host you actually use. Fresh configs are host-neutral, so add a top-level `platforms` list to `.truthmark/config.yml` before initialization:
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-Then install the repo-local truth docs, routing, and AI-host instructions:
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+In an interactive terminal, `truthmark init` shows a numbered multi-select for Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, and Cursor. Select zero or more hosts; choose `none` for a host-neutral, CLI-only repository.
+
+For scripts and CI, repeat `--platform` to replace the selected host set without prompting:
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+`--json` never prompts. On a first noninteractive run with no `--platform`, initialization stays host-neutral; later reruns retain the platforms already saved in `.truthmark/config.yml`.
+
 Now try the most common adoption path: document one existing behavior from code and tests. In your AI coding host, ask the installed workflow:

 ```text
@@ -45,7 +44,7 @@ Now try the most common adoption path: document one existing behavior from code

 After that, users should not normally invoke Truth Sync directly. Keep coding through your AI host; the installed repository instructions tell the agent to run relevant tests and perform the Truth Sync review before handoff when functional code changes. You review the resulting code diff plus truth-doc diff.

-If you only want CLI validation and do not want host-specific AI workflows yet, leave `platforms` omitted and run `truthmark init && truthmark check`; you can add a platform later and rerun `truthmark init`.
+If you only want CLI validation and do not want host-specific AI workflows yet, select `none` and continue with `truthmark check`; you can rerun `truthmark init` later to select platforms.

 ## 💡 The Problem: The AI Documentation Gap

@@ -59,10 +58,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 +71,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
@@ -90,9 +92,9 @@ Truthmark has one repo-local contract with two ways to use it.

 Maintainers and CI use the CLI:

-* `truthmark config` - create the initial configuration.
-* `truthmark init` - install or refresh routing, truth-doc scaffolds, and AI-host instructions.
+* `truthmark init` - create or refresh configuration, select zero or more platforms, and install routing, truth-doc scaffolds, and selected AI-host instructions.
 * `truthmark check` - validate the repository truth from the terminal.
+* `truthmark uninstall --dry-run|--apply` - preview or remove generated host surfaces while preserving authored truth and configuration.

 ### Agents follow the contract while coding

@@ -122,6 +124,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 +157,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,13 +198,15 @@ 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

-The current release provides:
+Truthmark 2.3 provides:

- local CLI commands for config, init, check, index, impact, and workflow status
+- local CLI commands for init, uninstall, check, index, impact, workflow status, and validate
 - generated repo-local agent instructions for Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, and Cursor
 - route, authority, frontmatter, link, freshness, generated-surface, branch-scope, and coverage diagnostics
 - branch-scoped truth docs and derived repository-intelligence artifacts
@@ -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.
@@ -0,0 +1,13 @@
+# Harden Init routing and generated-surface lifecycle
+
+Date: 2026-07-10
+Previous version: 2.2.6
+New version: 2.2.7
+Version action: patch
+SemVer rationale: This is a backward-compatible release that adds platform-derived instruction routing, repository-wide coverage discovery, generated-surface reconciliation, and explicit uninstall lifecycle controls while retaining legacy configuration parsing.
+
+- Instruction placement now follows configured platforms; legacy version-2 `instruction_targets` remains accepted but ignored.
+- Check and RepoIndex share Git-visible, NUL-safe repository discovery, including functional code under arbitrary roots.
+- Init reconciles exact safely recognized inactive generated surfaces while preserving diverged, Gemini, and unrelated files.
+- `truthmark uninstall --dry-run|--apply [--json]` provides a deterministic removal plan and preserves authored truth, configuration, templates, Portal output, and global package installation.
+- Human-readable `truthmark workflow status` output now presents bounded applicability and advisory context while JSON retains the full schema-versioned contract; duplicate diagnostics are collapsed at WorkflowState composition.
@@ -0,0 +1,28 @@
+# Version 2.3.0
+
+Previous version: 2.2.7
+New version: 2.3.0
+Diff basis: origin/main..HEAD plus working tree
+Version action: minor
+SemVer rationale: This release adds backward-compatible repository setup behavior while preserving the version-2 config schema, existing repository configs, generated host contracts, and finish-time Truth Sync semantics.
+
+Release payload:
+- Make `truthmark init` create and update `.truthmark/config.yml` as part of repository setup.
+- Add a numbered interactive platform multi-select backed by the existing supported-platform catalog, with saved selections preselected on rerun.
+- Add repeatable `truthmark init --platform <id>` flags for automation and keep JSON/non-TTY setup noninteractive.
+- Preserve host-neutral initialization through an explicit empty selection and through first-run noninteractive init without platform flags.
+- Generate only selected host-native workflow surfaces while preserving unrelated configuration values and comments.
+- Remove the redundant public `truthmark config` command without changing the persisted config schema.
+- Keep Personal installation and Git-hook automation deferred; repository finish-time Truth Sync behavior is unchanged.
+- Refresh the transitive `fast-uri` lock to 3.1.4 so the production dependency audit clears the current host-confusion advisories.
+
+User-facing release text:
+- Repository setup is now one step: run `truthmark init`, choose the agent platforms used by the repository, and Truthmark writes their version-2 config and host-native workflow surfaces.
+- Automation can repeat `--platform <id>`; JSON and other noninteractive invocations never wait for prompt input.
+- Existing repositories remain compatible and retain their selections on rerun.
+
+Verification:
+- `npm run release:check` passed: lint, format check, typecheck, 410 tests, build, 4 package-integrity tests, and production audit with 0 vulnerabilities.
+- `npm pack --dry-run --json --silent` passed for `truthmark@2.3.0`: 21 files and 1,195,813 unpacked bytes.
+- Built-artifact and PTY smoke tests initialized fresh repositories, persisted version-2 Codex/Cursor selections, generated the selected host surfaces, and rejected the removed `config` command.
+- `node --import tsx src/cli/main.ts check --json` and `index --json` passed with 0 error diagnostics.
@@ -1,7 +1,7 @@
 ---
 status: active
 doc_type: index
-last_reviewed: 2026-06-20
+last_reviewed: 2026-07-30
 source_of_truth:
  - docs/ai/repo-rules.md
  - ../.truthmark/config.yml
@@ -11,7 +11,7 @@ source_of_truth:

 ## Purpose

-`docs/` is Truthmark's canonical repository documentation tree. It keeps repository-wide agent rules, reusable standards, current architecture, and current lane-separated truth docs separate from onboarding copy and historical planning notes.
+`docs/` is Truthmark's repository documentation tree. It keeps repository-wide agent rules, reusable standards, current architecture, current lane-separated truth docs, and non-canonical research notes separate from onboarding copy.

 `AGENTS.md` is the agent entry point, but it delegates repository-wide rules to [docs/ai/repo-rules.md](ai/repo-rules.md). [README.md](../README.md) remains the human onboarding and product entry point. [docs/user-guide.md](user-guide.md) owns detailed human-facing command, workflow, and configuration guidance. `.truthmark/config.yml` defines the committed hierarchy contract.

@@ -35,6 +35,7 @@ Repository-wide conflict order and completion policy live in [docs/ai/repo-rules
 - `docs/truthmark/product/` for product capability promises, boundaries, and acceptance criteria
 - `docs/truthmark/engineering/` for current implementation behavior, architecture, contracts, workflows, and operations
 - `docs/architecture/` for repository-specific architecture guardrails
+- `docs/research/` for non-canonical research evidence, evaluations, and comparisons
 - `docs/truthmark/templates/` for editable scaffold templates used to create new docs
 - `docs/truthmark/engineering/contracts/` for stable contracts the CLI exposes

@@ -45,16 +46,17 @@ Repository-wide conflict order and completion policy live in [docs/ai/repo-rules

 ## Directory Map

-| Path | Type | Primary audience | Purpose |
-| --- | --- | --- | --- |
-| `docs/ai/` | agent rules | agent | Repository-wide rules and fast onboarding |
-| `docs/truthmark/routes/` | routing | both | Truth-routing metadata such as `areas.md` and `areas/**/*.md` |
-| `docs/standards/` | standard | agent | Reusable constraints, verification rules, completion gates |
-| `docs/truthmark/product/` | product truth | agent | Product capability promises, boundaries, decisions, and acceptance criteria |
-| `docs/truthmark/engineering/` | engineering truth | agent | Current implementation behavior for init, check, contracts, workflows, and operations |
-| `docs/architecture/` | architecture | agent | Repository-specific architecture guardrails |
-| `docs/truthmark/templates/` | template | both | Editable templates for scaffolded docs; templates are not Truth Sync targets |
-| `docs/user-guide.md` | guide | human | Detailed usage guide kept out of the root README so onboarding stays concise |
+| Path                          | Type              | Primary audience | Purpose                                                                               |
+| ----------------------------- | ----------------- | ---------------- | ------------------------------------------------------------------------------------- |
+| `docs/ai/`                    | agent rules       | agent            | Repository-wide rules and fast onboarding                                             |
+| `docs/truthmark/routes/`      | routing           | both             | Truth-routing metadata such as `areas.md` and `areas/**/*.md`                         |
+| `docs/standards/`             | standard          | agent            | Reusable constraints, verification rules, completion gates                            |
+| `docs/truthmark/product/`     | product truth     | agent            | Product capability promises, boundaries, decisions, and acceptance criteria           |
+| `docs/truthmark/engineering/` | engineering truth | agent            | Current implementation behavior for init, check, contracts, workflows, and operations |
+| `docs/architecture/`          | architecture      | agent            | Repository-specific architecture guardrails                                           |
+| `docs/research/`              | research          | human            | Non-canonical research evidence, evaluations, and comparisons                           |
+| `docs/truthmark/templates/`   | template          | both             | Editable templates for scaffolded docs; templates are not Truth Sync targets          |
+| `docs/user-guide.md`          | guide             | human            | Detailed usage guide kept out of the root README so onboarding stays concise          |

 ## Frontmatter Policy

@@ -74,13 +76,13 @@ Canonical docs should include frontmatter and keep these fields current:
 - When `truthmark init` or scaffolded files change, update the relevant truth or architecture doc, not only [README.md](../README.md).
 - When `truthmark check` changes what it validates or how it reports diagnostics, update both the current truth doc and the contract doc.
 - When major product, onboarding, install, command, positioning, or workflow behavior changes, review the root [README.md](../README.md) and update it if the human entry point would otherwise be stale.
- Keep planning or proposal material outside the canonical current-state docs until it becomes implemented truth.
- When current behavior changes for architecture, contracts, or lane-separated truth docs, update the owning canonical doc's `Product Decisions` and `Rationale` sections in the same change.
+- Keep active docs current-state focused; promote necessary accepted rationale into the owning decision section and rely on Git history for superseded plans.
+- When current behavior changes for architecture, contracts, or lane-separated truth docs, update the owning current-behavior and Product Decisions or Engineering Decisions sections in the same change.
 - Do not keep parallel documentation trees for the same subject.

 ## Important Truthmark-Specific Caveat

-New repositories should run `truthmark config` before `truthmark init` so teams can review the committed hierarchy contract before workflow surfaces are installed. The current scaffold writes a root route index plus one child route file under the configured routing root.
+`truthmark init` is the only setup command. In a TTY it offers a numbered zero-or-more platform selection; repeatable `--platform <id>` values provide noninteractive selection, while `--json` never prompts. A first noninteractive run without platform flags remains host-neutral. Init creates or updates the version-2 `.truthmark/config.yml`, then writes a root route index plus one child route file under the configured routing root.

 ## Recommended Reading Order

@@ -105,7 +107,7 @@ Use the route files under [docs/truthmark/routes/](truthmark/routes/) when desig

 ## Maintenance Principle

-The canonical tree should stay small, explicit, and current. Historical notes are useful for traceability, but current behavior belongs in the nearest maintained document class, not in old plans or chat summaries.
+The canonical tree should stay small, explicit, and current. Git history provides traceability for superseded context; active docs keep current behavior in the owning current-state section and accepted rationale in the owning decision section.

 ## Product Decisions

@@ -31,7 +31,7 @@ Code is the implementation. On code/doc conflict, inspect code, decide whether c

 The canonical product boundary is [docs/architecture/product-boundary.md](../architecture/product-boundary.md). This is repo-local policy for developing Truthmark itself; do not treat it as a downstream scaffold, generated surface, or required artifact for repositories that install Truthmark. Read it before generating any new design, implementation plan, generated-workflow redesign, architecture proposal, runtime/dependency change, or command-surface change. New designs and plans must include a product-boundary check that explains how the proposal preserves Truthmark's North Star, in-scope surfaces, explicit non-goals, optional-helper rule, and fail-closed write boundaries.

-Truthmark public CLI commands are `config`, `init`, `check`, `index`, `impact`, `context`, `workflow`, and `validate`. The `workflow` subcommands expose read-only agent-facing status/instructions contracts; they do not run installed workflows. The `validate` subcommands are optional CLI-owned workflow helper validators; they validate reports or write leases but do not run Truth Structure, Truth Document, Truth Sync, Truth Realize, or Truth Check. Those named workflows are installed workflow surfaces, not top-level CLI commands. Truth Preview is not an installed workflow surface; preview-like routing selection is internal advisory behavior.
+Truthmark public CLI commands are `init`, `uninstall`, `check`, `index`, `impact`, `workflow status`, and `validate`. Repository configuration lives in `.truthmark/config.yml` and is managed by `init`. The `workflow status` command exposes a read-only agent-facing state contract; it does not run installed workflows. The `validate` subcommands validate reports or write leases. Named agent workflows are installed workflow surfaces rather than top-level CLI commands.

 Agents inspect the active checkout directly. There is no daemon, database, remote service, hidden memory layer, or product-centered MCP server.

@@ -41,7 +41,7 @@ Agents inspect the active checkout directly. There is no daemon, database, remot
 2. Product boundaries are mandatory design inputs. Before generating a new design or plan, read [docs/architecture/product-boundary.md](../architecture/product-boundary.md) and include its product-boundary check in the design/plan artifact.
 3. Rules in this file are a compact behavior contract for observed repository failure modes. Prefer replacing weak or stale rules over accumulating generic prompts, identity statements, examples, or tool-dependent ceremony.
 4. Branch-local Markdown is canonical; the current checkout is the truth boundary.
-5. Current truth belongs in canonical docs, not historical plans or separate timestamped decision logs.
+5. Active docs state current behavior. Keep necessary historical rationale in Product/Engineering Decisions, keep Non-Goals limited to current ownership boundaries, and keep current truth in canonical docs rather than research snapshots, historical plans, or timestamped decision logs.
 6. Active decisions and rationale live in the canonical doc for the governed behavior.
 7. Read owning surfaces before writing: for workflows, skills, prompts, commands, generated instructions, or managed blocks, inspect the nearest canonical doc plus the source renderer, template, schema, or parser before editing.
 8. Generated surfaces are products, not source authority. Edit templates and renderers by default; patch generated output only when explicitly maintaining that generated surface.
@@ -1,7 +1,7 @@
 ---
 status: active
 doc_type: architecture
-last_reviewed: 2026-06-12
+last_reviewed: 2026-07-30
 source_of_truth:
  - ../../README.md
  - ../truthmark/product/capabilities/agent-native-workflow-injection.md
@@ -33,12 +33,16 @@ 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:

 - Make the audience and purpose clear near the top.
- Separate current behavior from rationale, decisions, operations, contracts, and future or non-goals.
+- Separate current behavior from rationale, decisions, operations, contracts, and ownership non-goals.
 - Use scannable headings and bounded sections.
 - Use plain, concrete, present-tense wording.
 - Expand or link terms and acronyms that are not obvious to a maintainer.
@@ -54,8 +58,9 @@ Truthmark owns:

 - Git-tracked repository documentation and routing metadata
 - 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
+- branch-local documentation checks, workflow indexes, impact summaries, bounded workflow status, 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

@@ -13,30 +13,22 @@
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-فعّل مضيف الذكاء الاصطناعي الذي تستخدمه فعلياً. تكون الإعدادات الجديدة محايدة تجاه المضيف، لذلك أضف قائمة `platforms` في المستوى الأعلى إلى `.truthmark/config.yml` قبل التهيئة:
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-ثم ثبّت توثيق الحقيقة المحلي للمستودع، والتوجيه، وأسطح سير عمل الوكلاء:
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+في الطرفية التفاعلية يعرض `truthmark init` قائمة اختيار متعددة مرقمة. اختر صفراً أو أكثر من المنصات، أو أدخل `none` لإعداد محايد تجاه المضيف ويقتصر على CLI.
+
+في السكربتات وCI كرّر `--platform`؛ ولا يعرض `--json` أي مطالبة تفاعلية أبداً:
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+في أول تشغيل غير تفاعلي من دون `--platform` يبقى الإعداد محايداً تجاه المضيف؛ وتحافظ التشغيلات اللاحقة على الاختيار المحفوظ في `.truthmark/config.yml`.
+
 جرّب الآن مسار الاعتماد الأكثر شيوعاً: توثيق سلوك موجود من الكود والاختبارات. في مضيف البرمجة بالذكاء الاصطناعي، اطلب من سير العمل المثبّت:

 ```text
@@ -45,7 +37,7 @@ git diff

 بعد ذلك، لا ينبغي للمستخدمين عادةً استدعاء Truth Sync مباشرة. واصل البرمجة عبر مضيف الذكاء الاصطناعي؛ فتعليمات المستودع المثبّتة تطلب من الوكيل تشغيل الاختبارات ذات الصلة وتنفيذ مراجعة Truth Sync قبل التسليم عندما تتغير الشيفرة الوظيفية. أنت تراجع فرق الكود الناتج مع فرق توثيق الحقيقة.

-إذا كنت تريد فقط التحقق عبر CLI ولا تريد بعدُ مسارات عمل ذكاء اصطناعي خاصة بمضيف، فاترك `platforms` محذوفة وشغّل `truthmark init && truthmark check`؛ يمكنك إضافة منصة لاحقاً وإعادة تشغيل `truthmark init`.
+إذا كنت تريد التحقق عبر CLI فقط، فاختر `none` ثم شغّل `truthmark check`؛ ويمكنك إعادة تشغيل `truthmark init` لاحقاً لاختيار المنصات.

 ## 💡 المشكلة: فجوة توثيق الذكاء الاصطناعي

@@ -90,8 +82,7 @@ Truthmark ليس مجرد أداة توثيق أخرى. إنه مدمج بعمق

 يستخدم الصائنون وCI واجهة CLI:

-* `truthmark config` - إنشاء الإعدادات الأولية.
-* `truthmark init` - تثبيت أو تحديث التوجيه، وقوالب وثائق الحقيقة، وتعليمات مضيف الذكاء الاصطناعي.
+* `truthmark init` - إنشاء الإعدادات أو تحديثها، واختيار صفر أو أكثر من المنصات، وتثبيت التوجيه وقوالب وثائق الحقيقة وتعليمات المضيفات المختارة.
 * `truthmark check` - التحقق من حقيقة المستودع من الطرفية.

 ### الوكلاء يتبعون العقد أثناء البرمجة
@@ -199,7 +190,7 @@ README هو الواجهة: سياق سريع، وبدء سريع، والنمو

 يوفر الإصدار الحالي:

- أوامر CLI محلية للإعداد والتهيئة والتحقق والفهرسة وتحليل الأثر وحالة سير العمل
+- أوامر CLI محلية للتهيئة والتحقق والفهرسة وتحليل الأثر وحالة سير العمل
 - تعليمات وكلاء محلية مولّدة لـ Codex وClaude Code وGitHub Copilot وOpenCode وAntigravity وCursor
 - تشخيصات للتوجيه والسلطة وfrontmatter والروابط والحداثة والأسطح المولّدة ونطاق الفرع والتغطية
 - وثائق حقيقة مرتبطة بالفرع وعناصر مستمدة لاستخبارات المستودع
@@ -223,3 +214,7 @@ Truthmark صغير عمداً: محلي، ملتزم به، مرتبط بالف
 ## الترخيص

 MIT. راجع [LICENSE](../../LICENSE).
+
+## إزالة آمنة
+
+استخدم `truthmark uninstall --dry-run` لمراجعة أسطح الاستضافة المولّدة بدقة، ثم `truthmark uninstall --apply` لإزالتها. يتم الاحتفاظ بـ truth المؤلفة والتكوين والقوالب ومخرجات البوابة وملفات Gemini والملفات غير المتعلقة بالمستخدم؛ أزل التثبيت العالمي لـ npm بشكل منفصل عبر مدير الحزم.
@@ -13,30 +13,22 @@ Führe dies in dem Git-Repository aus, das Truthmark verwalten soll:
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-Aktiviere den KI-Host, den du tatsächlich nutzt. Neue Konfigurationen sind host-neutral; füge daher vor der Initialisierung eine `platforms`-Liste auf oberster Ebene zu `.truthmark/config.yml` hinzu:
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-Installiere anschließend die repo-lokalen Truth-Dokumente, das Routing und die Anweisungen für KI-Hosts:
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+In einem interaktiven Terminal zeigt `truthmark init` eine nummerierte Mehrfachauswahl. Wähle null oder mehr Plattformen oder `none` für eine host-neutrale, reine CLI-Einrichtung.
+
+Für Skripte und CI kannst du `--platform` wiederholen; `--json` fragt niemals interaktiv nach:
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+Beim ersten nicht interaktiven Lauf ohne `--platform` bleibt die Einrichtung host-neutral; spätere Läufe behalten die in `.truthmark/config.yml` gespeicherte Auswahl bei.
+
 Probiere nun den häufigsten Einstiegspfad: ein bestehendes Verhalten anhand von Code und Tests dokumentieren. Bitte in deinem KI-Coding-Host den installierten Workflow:

 ```text
@@ -45,7 +37,7 @@ Probiere nun den häufigsten Einstiegspfad: ein bestehendes Verhalten anhand von

 Danach sollten Nutzer Truth Sync normalerweise nicht direkt aufrufen. Programmiere weiter über deinen KI-Host; die installierten Repository-Anweisungen weisen den Agenten an, relevante Tests auszuführen und vor der Übergabe die Truth Sync-Prüfung durchzuführen, wenn funktionaler Code geändert wurde. Du prüfst den daraus entstehenden Code-Diff plus den Truth-Doc-Diff.

-Wenn du nur CLI-Validierung möchtest und noch keine host-spezifischen KI-Workflows willst, lasse `platforms` weg und führe `truthmark init && truthmark check` aus; du kannst später eine Plattform hinzufügen und `truthmark init` erneut ausführen.
+Wenn du nur CLI-Validierung möchtest, wähle `none` und fahre mit `truthmark check` fort; du kannst `truthmark init` später erneut ausführen und Plattformen auswählen.

 ## 💡 Das Problem: die KI-Dokumentationslücke

@@ -90,8 +82,7 @@ Truthmark hat einen repo-lokalen Vertrag und zwei Arten, ihn zu nutzen.

 Maintainer und CI nutzen die CLI:

-* `truthmark config` - erstellt die Anfangskonfiguration.
-* `truthmark init` - installiert oder aktualisiert Routing, Truth-Doc-Scaffolds und Anweisungen für KI-Hosts.
+* `truthmark init` - erstellt oder aktualisiert die Konfiguration, lässt null oder mehr Plattformen auswählen und installiert Routing, Truth-Doc-Scaffolds und die ausgewählten KI-Host-Anweisungen.
 * `truthmark check` - validiert die Repository-Truth im Terminal.

 ### Agenten folgen dem Vertrag beim Coden
@@ -199,7 +190,7 @@ Für befehlsweise Nutzung, Oberflächenvergleiche, Details zu unterstützten Pla

 Die aktuelle Version bietet:

- lokale CLI-Befehle für config, init, check, index, impact und Workflow-Status
+- lokale CLI-Befehle für init, check, index, impact und Workflow-Status
 - generierte repo-lokale Agentenanweisungen für Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity und Cursor
 - Diagnosen für Routing, Autorität, Frontmatter, Links, Aktualität, generierte Oberflächen, Branch-Scope und Abdeckung
 - branch-bezogene Truth-Dokumente und abgeleitete Repository-Intelligence-Artefakte
@@ -223,3 +214,7 @@ Es ist kein gehosteter Dienst, MCP-Server, keine Vektordatenbank, versteckte Mem
 ## Lizenz

 MIT. Siehe [LICENSE](../../LICENSE).
+
+## Sichere Entfernung
+
+Verwenden Sie `truthmark uninstall --dry-run`, um die exakt erzeugten Host-Surfaces zu prüfen, und anschließend `truthmark uninstall --apply`, um sie zu entfernen. Erstellte truth, Konfiguration, Templates, Portal-Ausgabe, Gemini-Dateien und nicht zusammenhängende Benutzerdateien bleiben erhalten; entfernen Sie eine globale npm-Installation separat mit Ihrem Paketmanager.
@@ -13,30 +13,22 @@
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-Ενεργοποιήστε τον AI host που πραγματικά χρησιμοποιείτε. Οι νέες ρυθμίσεις είναι ουδέτερες ως προς τον host, οπότε προσθέστε μια λίστα `platforms` στο ανώτερο επίπεδο του `.truthmark/config.yml` πριν από την αρχικοποίηση:
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-Έπειτα εγκαταστήστε τοπικά τα έγγραφα αλήθειας του αποθετηρίου, τη δρομολόγηση και τις επιφάνειες ροής εργασίας πρακτόρων:
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+Σε διαδραστικό τερματικό, το `truthmark init` εμφανίζει αριθμημένη πολλαπλή επιλογή. Επιλέξτε μηδέν ή περισσότερες πλατφόρμες ή εισαγάγετε `none` για ρύθμιση ουδέτερη ως προς τον host και μόνο με CLI.
+
+Για scripts και CI, επαναλάβετε το `--platform`· το `--json` δεν εμφανίζει ποτέ προτροπή:
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+Στην πρώτη μη διαδραστική εκτέλεση χωρίς `--platform`, η ρύθμιση παραμένει ουδέτερη· οι επόμενες εκτελέσεις διατηρούν την επιλογή που έχει αποθηκευτεί στο `.truthmark/config.yml`.
+
 Τώρα δοκιμάστε την πιο συνηθισμένη διαδρομή υιοθέτησης: τεκμηριώστε μια υπάρχουσα συμπεριφορά από κώδικα και tests. Στον AI coding host σας, ζητήστε από την εγκατεστημένη ροή εργασίας:

 ```text
@@ -45,7 +37,7 @@ git diff

 Μετά από αυτό, οι χρήστες συνήθως δεν πρέπει να καλούν απευθείας το Truth Sync. Συνεχίστε να γράφετε κώδικα μέσω του AI host σας· οι εγκατεστημένες οδηγίες του αποθετηρίου λένε στον πράκτορα να εκτελεί τα σχετικά tests και να πραγματοποιεί την ανασκόπηση Truth Sync πριν από την παράδοση όταν αλλάζει λειτουργικός κώδικας. Εσείς ανασκοπείτε το προκύπτον code diff μαζί με το truth-doc diff.

-Αν θέλετε μόνο επικύρωση CLI και δεν θέλετε ακόμη host-specific AI workflows, αφήστε το `platforms` εκτός και εκτελέστε `truthmark init && truthmark check`· μπορείτε να προσθέσετε πλατφόρμα αργότερα και να εκτελέσετε ξανά `truthmark init`.
+Αν θέλετε μόνο επικύρωση CLI, επιλέξτε `none` και εκτελέστε `truthmark check`· μπορείτε αργότερα να εκτελέσετε ξανά `truthmark init` για να επιλέξετε πλατφόρμες.

 ## 💡 Το πρόβλημα: το κενό τεκμηρίωσης της AI

@@ -90,8 +82,7 @@ git diff

 Οι συντηρητές και το CI χρησιμοποιούν το CLI:

-* `truthmark config` - δημιουργεί την αρχική διαμόρφωση.
-* `truthmark init` - εγκαθιστά ή ανανεώνει routing, truth-doc scaffolds και οδηγίες για AI hosts.
+* `truthmark init` - δημιουργεί ή ανανεώνει τη διαμόρφωση, επιτρέπει επιλογή μηδέν ή περισσότερων πλατφορμών και εγκαθιστά routing, truth-doc scaffolds και οδηγίες για τους επιλεγμένους AI hosts.
 * `truthmark check` - επικυρώνει την αλήθεια του αποθετηρίου από το τερματικό.

 ### Οι agents ακολουθούν το συμβόλαιο ενώ γράφουν κώδικα
@@ -199,7 +190,7 @@ keep the result reviewable in Git

 Η τρέχουσα έκδοση παρέχει:

- τοπικές CLI commands για config, init, check, index, impact και workflow status
+- τοπικές CLI commands για init, check, index, impact και workflow status
 - παραγόμενες repo-local οδηγίες για agents για Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity και Cursor
 - diagnostics για route, authority, frontmatter, link, freshness, generated-surface, branch-scope και coverage
 - έγγραφα αλήθειας με scope branch και παράγωγα τεχνουργήματα ευφυΐας αποθετηρίου
@@ -223,3 +214,7 @@ keep the result reviewable in Git
 ## Άδεια

 MIT. Δείτε [LICENSE](../../LICENSE).
+
+## Ασφαλής κατάργηση
+
+Χρησιμοποιήστε το `truthmark uninstall --dry-run` για να ελέγξετε τις ακριβώς παραγόμενες επιφάνειες host και στη συνέχεια το `truthmark uninstall --apply` για να τις αφαιρέσετε. Το δημιουργημένο truth, η διαμόρφωση, τα templates, η έξοδος του Portal, τα αρχεία Gemini και τα μη σχετιζόμενα αρχεία χρήστη διατηρούνται. Καταργήστε την παγκόσμια εγκατάσταση του npm ξεχωριστά με το εργαλείο διαχείρισης πακέτων σας.
@@ -13,30 +13,22 @@ Ejecuta esto dentro del repositorio Git que quieres que Truthmark gestione:
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-Activa el host de IA que realmente usas. Las configuraciones nuevas son neutrales respecto al host, así que añade una lista `platforms` de nivel superior a `.truthmark/config.yml` antes de la inicialización:
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-Después instala los documentos de verdad locales del repositorio, el enrutamiento y las instrucciones para hosts de IA:
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+En una terminal interactiva, `truthmark init` muestra una selección múltiple numerada. Elige cero o más plataformas, o `none` para una configuración neutral respecto al host y solo de CLI.
+
+Para scripts y CI, repite `--platform`; `--json` nunca solicita entrada interactiva:
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+En la primera ejecución no interactiva sin `--platform`, la configuración permanece neutral; las ejecuciones posteriores conservan la selección guardada en `.truthmark/config.yml`.
+
 Ahora prueba la ruta de adopción más común: documentar un comportamiento existente a partir del código y las pruebas. En tu host de codificación con IA, pídele al workflow instalado:

 ```text
@@ -45,7 +37,7 @@ Ahora prueba la ruta de adopción más común: documentar un comportamiento exis

 Después de eso, normalmente los usuarios no deberían invocar Truth Sync directamente. Sigue programando mediante tu host de IA; las instrucciones instaladas en el repositorio le dicen al agente que ejecute las pruebas pertinentes y realice la revisión de Truth Sync antes de la entrega cuando haya cambios de código funcional. Tú revisas el diff de código resultante junto con el diff de los documentos de verdad.

-Si solo quieres validación por CLI y todavía no quieres workflows de IA específicos de un host, deja `platforms` omitido y ejecuta `truthmark init && truthmark check`; puedes añadir una plataforma más tarde y volver a ejecutar `truthmark init`.
+Si solo quieres validación por CLI, elige `none` y continúa con `truthmark check`; más tarde puedes volver a ejecutar `truthmark init` para seleccionar plataformas.

 ## 💡 El problema: la brecha de documentación de la IA

@@ -90,8 +82,7 @@ Truthmark tiene un contrato local del repositorio y dos formas de usarlo.

 Los mantenedores y CI usan la CLI:

-* `truthmark config` - crea la configuración inicial.
-* `truthmark init` - instala o actualiza el enrutamiento, los andamios de documentos de verdad y las instrucciones para hosts de IA.
+* `truthmark init` - crea o actualiza la configuración, permite elegir cero o más plataformas e instala el enrutamiento, los andamios de documentos de verdad y las instrucciones de los hosts elegidos.
 * `truthmark check` - valida la verdad del repositorio desde la terminal.

 ### Los agentes siguen el contrato mientras programan
@@ -199,7 +190,7 @@ Para uso comando por comando, comparaciones de superficies, detalles de platafor

 La versión actual proporciona:

- comandos CLI locales para config, init, check, index, impact y estado de workflows
+- comandos CLI locales para init, check, index, impact y estado de workflows
 - instrucciones de agente locales del repositorio generadas para Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity y Cursor
 - diagnósticos de enrutamiento, autoridad, frontmatter, enlaces, frescura, superficies generadas, alcance de rama y cobertura
 - documentos de verdad con alcance de rama y artefactos derivados de inteligencia del repositorio
@@ -223,3 +214,7 @@ No es un servicio alojado, servidor MCP, base de datos vectorial, capa de memori
 ## Licencia

 MIT. Consulta [LICENSE](../../LICENSE).
+
+## Eliminación segura
+
+Use `truthmark uninstall --dry-run` para revisar las superficies de host generadas exactas, luego `truthmark uninstall --apply` para eliminarlas. Los truth creados, la configuración, las plantillas, la salida de Portal, los archivos de Gemini y los archivos de usuario no relacionados se conservan; quite una instalación global de npm por separado con su gestor de paquetes.
@@ -13,30 +13,22 @@ Exécutez ceci dans le dépôt Git que vous voulez faire gérer par Truthmark :
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-Activez l’hôte d’IA que vous utilisez réellement. Les nouvelles configurations sont neutres vis-à-vis des hôtes ; ajoutez donc une liste `platforms` de premier niveau à `.truthmark/config.yml` avant l’initialisation :
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-Installez ensuite les documents de vérité locaux au dépôt, le routage et les surfaces de workflow pour agents :
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+Dans un terminal interactif, `truthmark init` affiche une sélection multiple numérotée. Choisissez zéro ou plusieurs plateformes, ou `none` pour une installation neutre vis-à-vis des hôtes et limitée à la CLI.
+
+Pour les scripts et la CI, répétez `--platform` ; `--json` ne déclenche jamais d’invite :
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+Lors d’une première exécution non interactive sans `--platform`, l’installation reste neutre ; les exécutions suivantes conservent la sélection enregistrée dans `.truthmark/config.yml`.
+
 Essayez maintenant le chemin d’adoption le plus courant : documenter, à partir du code et des tests, un comportement existant. Dans votre hôte de codage IA, demandez au workflow installé :

 ```text
@@ -45,7 +37,7 @@ Essayez maintenant le chemin d’adoption le plus courant : documenter, à parti

 Après cela, les utilisateurs ne devraient normalement pas invoquer Truth Sync directement. Continuez à coder dans votre hôte d’IA ; les instructions installées dans le dépôt indiquent à l’agent d’exécuter les tests pertinents et d’effectuer la revue Truth Sync avant la remise lorsqu’il y a des changements de code fonctionnel. Vous examinez le diff de code obtenu ainsi que le diff des documents de vérité.

-Si vous voulez seulement la validation CLI et ne voulez pas encore de workflows IA propres à un hôte, laissez `platforms` omis et exécutez `truthmark init && truthmark check` ; vous pourrez ajouter une plateforme plus tard et relancer `truthmark init`.
+Si vous voulez seulement la validation CLI, choisissez `none` puis exécutez `truthmark check` ; vous pourrez relancer `truthmark init` plus tard pour sélectionner des plateformes.

 ## 💡 Le problème : l’écart de documentation avec l’IA

@@ -90,8 +82,7 @@ Truthmark fournit un contrat local au dépôt, avec deux façons de l’utiliser

 Les mainteneurs et la CI utilisent la CLI :

-* `truthmark config` - crée la configuration initiale.
-* `truthmark init` - installe ou actualise le routage, les échafaudages de documents de vérité et les instructions pour les hôtes IA.
+* `truthmark init` - crée ou actualise la configuration, permet de choisir zéro ou plusieurs plateformes et installe le routage, les échafaudages de documents de vérité et les instructions des hôtes sélectionnés.
 * `truthmark check` - valide la vérité du dépôt depuis le terminal.

 ### Les agents suivent le contrat pendant qu’ils codent
@@ -199,7 +190,7 @@ Pour l’utilisation commande par commande, les comparaisons de surfaces, les d

 La version actuelle fournit :

- des commandes CLI locales pour config, init, check, index, impact et l’état des workflows
+- des commandes CLI locales pour init, check, index, impact et l’état des workflows
 - instructions agent locales au dépôt générées pour Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity et Cursor
 - des diagnostics de routage, d’autorité, de frontmatter, de liens, de fraîcheur, de surfaces générées, de portée de branche et de couverture
 - des documents de vérité limités à la branche et des artefacts dérivés d’intelligence du dépôt
@@ -223,3 +214,7 @@ Ce n’est pas un service hébergé, un serveur MCP, une base de données vector
 ## Licence

 MIT. Voir [LICENSE](../../LICENSE).
+
+## Suppression sûre
+
+Utilisez `truthmark uninstall --dry-run` pour examiner précisément les surfaces hôtes générées, puis `truthmark uninstall --apply` pour les supprimer. Les truth rédigées, la configuration, les templates, la sortie Portal, les fichiers Gemini et les fichiers utilisateur non liés sont conservés ; supprimez séparément une installation npm globale avec votre gestionnaire de paquets.
@@ -13,30 +13,22 @@ Jalankan ini di dalam repositori Git yang ingin Anda kelola dengan Truthmark:
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-Aktifkan host AI yang benar-benar Anda gunakan. Konfigurasi baru bersifat netral terhadap host, jadi tambahkan daftar `platforms` tingkat atas ke `.truthmark/config.yml` sebelum inisialisasi:
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-Kemudian pasang dokumen kebenaran lokal repositori, perutean, dan permukaan alur kerja agen:
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+Di terminal interaktif, `truthmark init` menampilkan pilihan ganda bernomor. Pilih nol atau lebih platform, atau masukkan `none` untuk penyiapan netral terhadap host yang hanya memakai CLI.
+
+Untuk skrip dan CI, ulangi `--platform`; `--json` tidak pernah menampilkan prompt:
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+Pada proses noninteraktif pertama tanpa `--platform`, penyiapan tetap netral terhadap host; proses berikutnya mempertahankan pilihan yang tersimpan di `.truthmark/config.yml`.
+
 Sekarang coba jalur adopsi yang paling umum: dokumentasikan satu perilaku yang sudah ada dari kode dan pengujian. Di host pengodean AI Anda, minta alur kerja yang terpasang:

 ```text
@@ -45,7 +37,7 @@ Sekarang coba jalur adopsi yang paling umum: dokumentasikan satu perilaku yang s

 Setelah itu, pengguna biasanya tidak perlu memanggil Truth Sync secara langsung. Teruslah membuat kode melalui host AI Anda; instruksi repositori yang terpasang memberi tahu agen untuk menjalankan pengujian yang relevan dan melakukan tinjauan Truth Sync sebelum serah terima ketika kode fungsional berubah. Anda meninjau diff kode yang dihasilkan beserta diff dokumen truth.

-Jika Anda hanya menginginkan validasi CLI dan belum menginginkan alur kerja AI khusus host, biarkan `platforms` tidak dicantumkan dan jalankan `truthmark init && truthmark check`; Anda dapat menambahkan platform nanti dan menjalankan ulang `truthmark init`.
+Jika Anda hanya menginginkan validasi CLI, pilih `none` lalu jalankan `truthmark check`; Anda dapat menjalankan ulang `truthmark init` nanti untuk memilih platform.

 ## 💡 Masalah: kesenjangan dokumentasi AI

@@ -90,8 +82,7 @@ Truthmark memiliki satu kontrak lokal repositori dengan dua cara pemakaian.

 Pemelihara dan CI menggunakan CLI:

-* `truthmark config` - membuat konfigurasi awal.
-* `truthmark init` - memasang atau menyegarkan perutean, scaffold dokumen kebenaran, dan instruksi host AI.
+* `truthmark init` - membuat atau menyegarkan konfigurasi, memilih nol atau lebih platform, lalu memasang perutean, scaffold dokumen kebenaran, dan instruksi untuk host AI yang dipilih.
 * `truthmark check` - memvalidasi kebenaran repositori dari terminal.

 ### Agen mengikuti kontrak saat membuat kode
@@ -199,7 +190,7 @@ Untuk penggunaan per perintah, perbandingan permukaan, detail platform yang didu

 Rilis saat ini menyediakan:

- perintah CLI lokal untuk config, init, check, index, impact, dan status alur kerja
+- perintah CLI lokal untuk init, check, index, impact, dan status alur kerja
 - instruksi agen lokal repositori yang dihasilkan untuk Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, dan Cursor
 - diagnostik perutean, otoritas, frontmatter, tautan, kesegaran, permukaan yang dihasilkan, cakupan branch, dan coverage
 - dokumen kebenaran berlingkup branch dan artefak kecerdasan repositori turunan
@@ -223,3 +214,7 @@ Ini bukan layanan ter-host, server MCP, basis data vektor, lapisan memori tersem
 ## Lisensi

 MIT. Lihat [LICENSE](../../LICENSE).
+
+## Penghapusan aman
+
+Gunakan `truthmark uninstall --dry-run` untuk meninjau permukaan host yang tepat dihasilkan, lalu `truthmark uninstall --apply` untuk menghapusnya. Truth hasil penulisan, konfigurasi, template, keluaran Portal, berkas Gemini, dan berkas pengguna yang tidak terkait akan tetap dipertahankan; hapus instalasi npm global secara terpisah melalui pengelola paket Anda.
@@ -13,30 +13,22 @@ Esegui questo comando nel repository Git che vuoi far gestire a Truthmark:
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-Abilita l’host IA che usi davvero. Le nuove configurazioni sono neutrali rispetto all’host, quindi aggiungi un elenco `platforms` di primo livello a `.truthmark/config.yml` prima dell’inizializzazione:
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-Poi installa i documenti di verità locali al repository, il routing e le superfici di workflow per agenti:
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+In un terminale interattivo, `truthmark init` mostra una selezione multipla numerata. Scegli zero o più piattaforme, oppure `none` per una configurazione neutrale rispetto all’host e solo CLI.
+
+Per script e CI, ripeti `--platform`; `--json` non mostra mai prompt:
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+Alla prima esecuzione non interattiva senza `--platform`, la configurazione resta neutrale; le esecuzioni successive mantengono la selezione salvata in `.truthmark/config.yml`.
+
 Ora prova il percorso di adozione più comune: documentare un comportamento esistente a partire da codice e test. Nel tuo host di coding IA, chiedi al workflow installato:

 ```text
@@ -45,7 +37,7 @@ Ora prova il percorso di adozione più comune: documentare un comportamento esis

 Dopo questo, di norma gli utenti non dovrebbero invocare Truth Sync direttamente. Continua a scrivere codice tramite il tuo host IA; le istruzioni installate nel repository dicono all’agente di eseguire i test pertinenti e svolgere la revisione Truth Sync prima della consegna quando cambiano parti di codice funzionale. Tu revisioni il diff di codice risultante insieme al diff dei documenti di verità.

-Se vuoi solo la validazione CLI e non vuoi ancora workflow IA specifici per un host, lascia `platforms` omesso ed esegui `truthmark init && truthmark check`; potrai aggiungere una piattaforma più tardi e rieseguire `truthmark init`.
+Se vuoi solo la validazione CLI, scegli `none` e continua con `truthmark check`; potrai rieseguire `truthmark init` in seguito per selezionare le piattaforme.

 ## 💡 Il problema: il divario di documentazione dell’IA

@@ -90,8 +82,7 @@ Truthmark ha un contratto locale al repository e due modi per usarlo.

 Maintainer e CI usano la CLI:

-* `truthmark config` - crea la configurazione iniziale.
-* `truthmark init` - installa o aggiorna routing, scaffold dei documenti di verità e istruzioni per host IA.
+* `truthmark init` - crea o aggiorna la configurazione, consente di scegliere zero o più piattaforme e installa routing, scaffold dei documenti di verità e istruzioni per gli host selezionati.
 * `truthmark check` - valida la verità del repository dal terminale.

 ### Gli agenti seguono il contratto mentre scrivono codice
@@ -199,7 +190,7 @@ Per l’uso comando per comando, confronti tra superfici, dettagli sulle piattaf

 La release attuale fornisce:

- comandi CLI locali per config, init, check, index, impact e stato dei workflow
+- comandi CLI locali per init, check, index, impact e stato dei workflow
 - istruzioni agente locali al repository generate per Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor
 - diagnostica su routing, autorità, frontmatter, link, freschezza, superfici generate, ambito di branch e copertura
 - documenti di verità con ambito di branch e artefatti derivati di intelligence del repository
@@ -223,3 +214,7 @@ Non è un servizio ospitato, un server MCP, un database vettoriale, un livello d
 ## Licenza

 MIT. Vedi [LICENSE](../../LICENSE).
+
+## Rimozione sicura
+
+Usa `truthmark uninstall --dry-run` per rivedere le superfici host generate con precisione, quindi `truthmark uninstall --apply` per rimuoverle. I truth creati, la configurazione, i template, l’output di Portal, i file Gemini e i file utente non correlati vengono preservati; rimuovi separatamente un’installazione npm globale con il tuo gestore pacchetti.
@@ -13,30 +13,22 @@ Truthmark に管理させたい Git リポジトリ内でこれを実行しま
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-実際に使っている AI ホストを有効にします。新しい設定はホスト非依存なので、初期化前にトップレベルの `platforms` リストを `.truthmark/config.yml` に追加してください：
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-次に、リポジトリローカルの truth ドキュメント、ルーティング、エージェントワークフローサーフェスをインストールします：
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+対話型ターミナルでは、`truthmark init` が番号付きの複数選択を表示します。0 個以上のプラットフォームを選ぶか、`none` を入力してホスト非依存の CLI 専用セットアップにします。
+
+スクリプトや CI では `--platform` を繰り返します。`--json` は決してプロンプトを表示しません：
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+初回の非対話実行で `--platform` がなければホスト非依存のままです。以後の実行では `.truthmark/config.yml` に保存済みの選択を維持します。
+
 次に、最も一般的な導入パスを試します。コードとテストから既存の振る舞いを 1 つドキュメント化します。AI コーディングホストで、インストール済みワークフローに依頼してください：

 ```text
@@ -45,7 +37,7 @@ git diff

 その後、通常ユーザーが Truth Sync を直接呼び出す必要はありません。AI ホストを通じてコーディングを続けてください。インストールされたリポジトリ指示が、機能コードの変更時に関連テストを実行し、引き渡し前に Truth Sync レビューを行うようエージェントに伝えます。あなたは結果のコード diff と truth-doc diff をレビューします。

-CLI 検証だけが必要で、ホスト固有の AI ワークフローをまだ使わない場合は、`platforms` を省略したまま `truthmark init && truthmark check` を実行してください。後からプラットフォームを追加し、`truthmark init` を再実行できます。
+CLI 検証だけが必要なら `none` を選び、`truthmark check` を実行してください。後から `truthmark init` を再実行してプラットフォームを選択できます。

 ## 💡 問題：AI ドキュメントギャップ

@@ -90,8 +82,7 @@ Truthmark には、リポジトリローカルな契約が 1 つあり、それ

 メンテナーと CI は CLI を使います:

-* `truthmark config` - 初期設定を作成します。
-* `truthmark init` - ルーティング、truth-doc の足場、AI ホスト向け指示をインストールまたは更新します。
+* `truthmark init` - 設定を作成または更新し、0 個以上のプラットフォームを選択して、ルーティング、truth-doc の足場、選択した AI ホスト向け指示をインストールします。
 * `truthmark check` - ターミナルからリポジトリ truth を検証します。

 ### エージェントはコーディング中に契約に従う
@@ -199,7 +190,7 @@ README は店頭のようなものです。素早い文脈、クイックスタ

 現在のリリースは次を提供します：

- config、init、check、index、impact、workflow status のためのローカル CLI コマンド
+- init、check、index、impact、workflow status のためのローカル CLI コマンド
 - Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity、Cursor 向けに生成されるリポジトリローカルなエージェント指示
 - ルーティング、権限、frontmatter、リンク、鮮度、生成サーフェス、ブランチスコープ、カバレッジの診断
 - ブランチ単位の truth ドキュメントと、派生したリポジトリインテリジェンス成果物
@@ -223,3 +214,7 @@ Truthmark は意図的に小さく保たれています：ローカル、コミ
 ## ライセンス

 MIT。[LICENSE](../../LICENSE) を参照してください。
+
+## 安全な削除
+
+`truthmark uninstall --dry-run` を使用して正確に生成されたホストサーフェスを確認し、次に `truthmark uninstall --apply` でそれらを削除します。作成した truth、設定、テンプレート、Portal の出力、Gemini ファイル、関連のないユーザーファイルは保持されます。npm のグローバルインストールはパッケージマネージャーで別途削除してください。
@@ -13,30 +13,22 @@ Truthmark가 관리하길 원하는 Git 저장소 안에서 실행하세요:
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-실제로 사용하는 AI 호스트를 활성화하세요. 새 설정은 기본적으로 호스트 중립적이므로, 초기화 전에 `.truthmark/config.yml`에 최상위 `platforms` 목록을 추가하세요:
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-그런 다음 저장소 로컬 truth 문서, 라우팅, 에이전트 워크플로 표면을 설치하세요:
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+대화형 터미널에서 `truthmark init`은 번호가 붙은 다중 선택을 표시합니다. 플랫폼을 0개 이상 선택하거나 `none`을 입력해 호스트 중립적인 CLI 전용 설정을 사용하세요.
+
+스크립트와 CI에서는 `--platform`을 반복해서 사용합니다. `--json`은 절대 입력을 요청하지 않습니다:
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+처음 비대화형으로 실행할 때 `--platform`이 없으면 호스트 중립 상태를 유지하고, 이후 실행에서는 `.truthmark/config.yml`에 저장된 선택을 유지합니다.
+
 이제 가장 흔한 도입 경로를 시도해 보세요. 코드와 테스트에서 기존 동작 하나를 문서화합니다. AI 코딩 호스트에서 설치된 워크플로에 요청하세요:

 ```text
@@ -45,7 +37,7 @@ git diff

 그 이후에는 사용자가 일반적으로 Truth Sync를 직접 호출할 필요가 없습니다. AI 호스트를 통해 계속 코딩하세요. 설치된 저장소 지침이 기능 코드가 변경될 때 에이전트에게 관련 테스트를 실행하고 인계 전에 Truth Sync 검토를 수행하라고 알려줍니다. 사용자는 결과 코드 diff와 truth-doc diff를 함께 검토합니다.

-아직 호스트별 AI 워크플로는 원하지 않고 CLI 검증만 원한다면 `platforms`를 생략한 채 `truthmark init && truthmark check`를 실행하세요. 나중에 플랫폼을 추가하고 `truthmark init`을 다시 실행할 수 있습니다.
+CLI 검증만 원한다면 `none`을 선택하고 `truthmark check`를 실행하세요. 나중에 `truthmark init`을 다시 실행해 플랫폼을 선택할 수 있습니다.

 ## 💡 문제: AI 문서화 격차

@@ -90,8 +82,7 @@ Truthmark에는 저장소 로컬 계약 하나와 그것을 사용하는 두 가

 유지관리자와 CI는 CLI를 사용합니다:

-* `truthmark config` - 초기 설정을 만듭니다.
-* `truthmark init` - 라우팅, truth-doc 스캐폴드, AI 호스트 지침을 설치하거나 새로 고칩니다.
+* `truthmark init` - 설정을 만들거나 새로 고치고, 플랫폼을 0개 이상 선택하며, 라우팅, truth-doc 스캐폴드와 선택한 AI 호스트 지침을 설치합니다.
 * `truthmark check` - 터미널에서 저장소 truth를 검증합니다.

 ### 에이전트는 코딩하는 동안 계약을 따릅니다
@@ -199,7 +190,7 @@ README는 쇼윈도입니다. 빠른 맥락, 빠른 시작, 핵심 사고 모델

 현재 릴리스는 다음을 제공합니다:

- config, init, check, index, impact, workflow status를 위한 로컬 CLI 명령
+- init, check, index, impact, workflow status를 위한 로컬 CLI 명령
 - Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, Cursor용으로 생성된 저장소 로컬 에이전트 지침
 - 라우팅, 권한, frontmatter, 링크, 신선도, 생성 표면, 브랜치 범위, 커버리지 진단
 - 브랜치 범위 truth 문서와 파생된 저장소 인텔리전스 산출물
@@ -223,3 +214,7 @@ Truthmark는 호스팅 서비스, MCP 서버, 벡터 데이터베이스, 숨겨
 ## 라이선스

 MIT. [LICENSE](../../LICENSE)를 참조하세요.
+
+## 안전한 제거
+
+`truthmark uninstall --dry-run`을(를) 사용하여 정확히 생성된 호스트 표면을 검토한 후 `truthmark uninstall --apply`를 사용해 제거하세요. 작성된 truth, 구성, 템플릿, Portal 출력, Gemini 파일 및 관련 없는 사용자 파일은 보존되며, npm 전역 설치는 패키지 관리자에서 별도로 제거하십시오.
@@ -13,30 +13,22 @@ Uruchom to w repozytorium Git, którym ma zarządzać Truthmark:
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-Włącz hosta AI, którego faktycznie używasz. Nowe konfiguracje są neutralne wobec hosta, więc przed inicjalizacją dodaj listę najwyższego poziomu `platforms` do `.truthmark/config.yml`:
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-Następnie zainstaluj lokalne dla repozytorium dokumenty truth, routing i powierzchnie workflow agentów:
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+W terminalu interaktywnym `truthmark init` wyświetla numerowany wybór wielokrotny. Wybierz zero lub więcej platform albo wpisz `none`, aby skonfigurować tryb neutralny wobec hosta i tylko CLI.
+
+W skryptach i CI powtarzaj `--platform`; `--json` nigdy nie wyświetla pytania:
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+Przy pierwszym nieinteraktywnym uruchomieniu bez `--platform` konfiguracja pozostaje neutralna; kolejne uruchomienia zachowują wybór zapisany w `.truthmark/config.yml`.
+
 Teraz wypróbuj najczęstszą ścieżkę adopcji: udokumentuj jedno istniejące zachowanie na podstawie kodu i testów. W swoim hoście kodowania AI poproś zainstalowany workflow:

 ```text
@@ -45,7 +37,7 @@ Teraz wypróbuj najczęstszą ścieżkę adopcji: udokumentuj jedno istniejące

 Po tym użytkownicy zwykle nie powinni wywoływać Truth Sync bezpośrednio. Kontynuuj kodowanie przez swojego hosta AI; zainstalowane instrukcje repozytorium mówią agentowi, aby przy zmianach kodu funkcjonalnego uruchomił odpowiednie testy i wykonał przegląd Truth Sync przed przekazaniem pracy. Ty przeglądasz wynikowy diff kodu oraz diff truth-doc.

-Jeśli chcesz tylko walidacji CLI i nie potrzebujesz jeszcze workflow AI specyficznych dla hosta, pozostaw `platforms` pominięte i uruchom `truthmark init && truthmark check`; później możesz dodać platformę i ponownie uruchomić `truthmark init`.
+Jeśli chcesz tylko walidacji CLI, wybierz `none` i uruchom `truthmark check`; później możesz ponownie uruchomić `truthmark init`, aby wybrać platformy.

 ## 💡 Problem: luka w dokumentacji AI

@@ -90,8 +82,7 @@ Truthmark ma jeden lokalny kontrakt repozytorium i dwa sposoby korzystania z nie

 Opiekunowie i CI używają CLI:

-* `truthmark config` - tworzy początkową konfigurację.
-* `truthmark init` - instaluje lub odświeża routing, szkielety truth-doc i instrukcje dla hostów AI.
+* `truthmark init` - tworzy lub odświeża konfigurację, pozwala wybrać zero lub więcej platform oraz instaluje routing, szkielety truth-doc i instrukcje dla wybranych hostów AI.
 * `truthmark check` - waliduje truth repozytorium z terminala.

 ### Agenci podążają za kontraktem podczas kodowania
@@ -199,7 +190,7 @@ Aby poznać użycie komenda po komendzie, porównanie powierzchni, szczegóły o

 Obecne wydanie zapewnia:

- lokalne komendy CLI dla config, init, check, index, impact i workflow status
+- lokalne komendy CLI dla init, check, index, impact i workflow status
 - wygenerowane lokalne instrukcje agenta dla Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity i Cursor
 - diagnostykę route, authority, frontmatter, link, freshness, generated-surface, branch-scope i coverage
 - dokumenty truth w zakresie gałęzi oraz pochodne artefakty inteligencji repozytorium
@@ -223,3 +214,7 @@ Nie jest usługą hostowaną, serwerem MCP, wektorową bazą danych, ukrytą war
 ## Licencja

 MIT. Zobacz [LICENSE](../../LICENSE).
+
+## Bezpieczne usuwanie
+
+Użyj `truthmark uninstall --dry-run`, aby przejrzeć dokładnie wygenerowane powierzchnie hosta, a następnie `truthmark uninstall --apply`, aby je usunąć. Utworzone truth, konfiguracja, szablony, wyjście Portalu, pliki Gemini i niezwiązane pliki użytkownika są zachowane; globalną instalację npm usuń oddzielnie za pomocą swojego menedżera pakietów.
@@ -13,30 +13,22 @@ Execute isto dentro do repositório Git que você quer que o Truthmark gerencie:
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-Ative o host de IA que você realmente usa. Configurações novas são neutras em relação a host; portanto, adicione uma lista `platforms` de nível superior a `.truthmark/config.yml` antes da inicialização:
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-Em seguida, instale os documentos de verdade locais do repositório, o roteamento e as instruções para hosts de IA:
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+Em um terminal interativo, `truthmark init` mostra uma seleção múltipla numerada. Escolha zero ou mais plataformas, ou `none` para uma configuração neutra em relação a host e somente de CLI.
+
+Para scripts e CI, repita `--platform`; `--json` nunca exibe uma solicitação interativa:
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+Na primeira execução não interativa sem `--platform`, a configuração permanece neutra; execuções posteriores mantêm a seleção salva em `.truthmark/config.yml`.
+
 Agora experimente o caminho de adoção mais comum: documentar, a partir do código e dos testes, um comportamento existente. No seu host de codificação com IA, peça ao workflow instalado:

 ```text
@@ -45,7 +37,7 @@ Agora experimente o caminho de adoção mais comum: documentar, a partir do cód

 Depois disso, usuários normalmente não devem invocar o Truth Sync diretamente. Continue codificando por meio do seu host de IA; as instruções instaladas no repositório dizem ao agente para executar os testes relevantes e realizar a revisão Truth Sync antes da entrega quando houver mudanças em código funcional. Você revisa o diff de código resultante junto com o diff dos documentos de verdade.

-Se você quer apenas validação por CLI e ainda não quer workflows de IA específicos de host, deixe `platforms` omitido e execute `truthmark init && truthmark check`; você pode adicionar uma plataforma depois e executar `truthmark init` novamente.
+Se você quer apenas validação por CLI, escolha `none` e continue com `truthmark check`; depois você pode executar `truthmark init` novamente para selecionar plataformas.

 ## 💡 O problema: a lacuna de documentação da IA

@@ -90,8 +82,7 @@ Truthmark tem um contrato local do repositório e duas formas de usá-lo.

 Mantenedores e CI usam a CLI:

-* `truthmark config` - cria a configuração inicial.
-* `truthmark init` - instala ou atualiza roteamento, scaffolds de documentos de verdade e instruções para hosts de IA.
+* `truthmark init` - cria ou atualiza a configuração, permite escolher zero ou mais plataformas e instala roteamento, scaffolds de documentos de verdade e instruções dos hosts selecionados.
 * `truthmark check` - valida a verdade do repositório pelo terminal.

 ### Agentes seguem o contrato enquanto programam
@@ -199,7 +190,7 @@ Para uso comando por comando, comparações de superfícies, detalhes de platafo

 A versão atual fornece:

- comandos CLI locais para config, init, check, index, impact e status de workflows
+- comandos CLI locais para init, check, index, impact e status de workflows
 - instruções de agente locais do repositório geradas para Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity e Cursor
 - diagnósticos de roteamento, autoridade, frontmatter, links, frescor, superfícies geradas, escopo de branch e cobertura
 - documentos de verdade com escopo de branch e artefatos derivados de inteligência do repositório
@@ -223,3 +214,7 @@ Ele não é um serviço hospedado, servidor MCP, banco de dados vetorial, camada
 ## Licença

 MIT. Veja [LICENSE](../../LICENSE).
+
+## Remoção segura
+
+Use `truthmark uninstall --dry-run` para revisar as superfícies de host geradas com precisão, e depois `truthmark uninstall --apply` para removê-las. Truth criada, configuração, templates, saída do Portal, arquivos Gemini e arquivos de usuário não relacionados são preservados; remova uma instalação global de npm separadamente com seu gerenciador de pacotes.
@@ -13,30 +13,22 @@
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-Включите AI-хост, которым вы действительно пользуетесь. Новые конфигурации нейтральны к хостам, поэтому перед инициализацией добавьте список верхнего уровня `platforms` в `.truthmark/config.yml`:
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-Затем установите локальные для репозитория truth-документы, маршрутизацию и поверхности рабочих процессов агентов:
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+В интерактивном терминале `truthmark init` показывает нумерованный множественный выбор. Выберите ноль или несколько платформ либо введите `none` для нейтральной к хосту настройки только с CLI.
+
+В скриптах и CI повторяйте `--platform`; `--json` никогда не показывает запрос:
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+При первом неинтерактивном запуске без `--platform` настройка остаётся нейтральной; последующие запуски сохраняют выбор из `.truthmark/config.yml`.
+
 Теперь попробуйте самый распространенный путь внедрения: задокументируйте одно существующее поведение по коду и тестам. В вашем AI-хосте для разработки попросите установленный рабочий процесс:

 ```text
@@ -45,7 +37,7 @@ git diff

 После этого пользователям обычно не следует напрямую вызывать Truth Sync. Продолжайте писать код через ваш AI-хост; установленные инструкции репозитория скажут агенту запускать релевантные тесты и выполнять проверку Truth Sync перед передачей, когда меняется функциональный код. Вы просматриваете получившийся diff кода вместе с diff truth-документов.

-Если вам нужна только CLI-валидация, а хост-специфичные AI workflow пока не нужны, оставьте `platforms` неуказанным и выполните `truthmark init && truthmark check`; позже можно добавить платформу и заново выполнить `truthmark init`.
+Если нужна только CLI-валидация, выберите `none` и выполните `truthmark check`; позже можно снова выполнить `truthmark init` и выбрать платформы.

 ## 💡 Проблема: разрыв в AI-документации

@@ -90,8 +82,7 @@ Truthmark — не просто очередной инструмент доку

 Мейнтейнеры и CI используют CLI:

-* `truthmark config` - создает начальную конфигурацию.
-* `truthmark init` - устанавливает или обновляет маршруты, scaffold для truth-doc и инструкции для AI-хостов.
+* `truthmark init` - создаёт или обновляет конфигурацию, позволяет выбрать ноль или несколько платформ и устанавливает маршруты, scaffold для truth-doc и инструкции выбранных AI-хостов.
 * `truthmark check` - проверяет truth репозитория из терминала.

 ### Агенты следуют контракту во время кодинга
@@ -199,7 +190,7 @@ README — это витрина: быстрый контекст, быстры

 Текущий релиз предоставляет:

- локальные CLI-команды для config, init, check, index, impact и workflow status
+- локальные CLI-команды для init, check, index, impact и workflow status
 - сгенерированные локальные инструкции агента для Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity и Cursor
 - диагностику route, authority, frontmatter, links, freshness, generated-surface, branch-scope и coverage
 - branch-scoped truth docs и производные артефакты repository intelligence
@@ -223,3 +214,7 @@ Truthmark намеренно мал: локальный, закоммиченн
 ## Лицензия

 MIT. См. [LICENSE](../../LICENSE).
+
+## Безопасное удаление
+
+Используйте `truthmark uninstall --dry-run` для проверки точно сгенерированных host-поверхностей, затем `truthmark uninstall --apply` для их удаления. Сформированные truth, конфигурация, шаблоны, вывод Portal, файлы Gemini и несвязанные пользовательские файлы сохраняются; глобальную установку npm удаляйте отдельно через менеджер пакетов.
@@ -13,30 +13,22 @@ Bunu Truthmark tarafından yönetilmesini istediğiniz Git deposunun içinde ça
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-Gerçekten kullandığınız AI ana makinesini etkinleştirin. Yeni yapılandırmalar ana makineden bağımsızdır; bu yüzden başlatmadan önce `.truthmark/config.yml` dosyasına üst düzey bir `platforms` listesi ekleyin:
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-Ardından depoya yerel gerçeklik belgelerini, yönlendirmeyi ve ajan iş akışı yüzeylerini kurun:
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+Etkileşimli bir terminalde `truthmark init`, numaralı bir çoklu seçim gösterir. Sıfır veya daha fazla platform seçin ya da ana makineden bağımsız, yalnızca CLI kurulumu için `none` girin.
+
+Betikler ve CI için `--platform` seçeneğini tekrarlayın; `--json` hiçbir zaman istem göstermez:
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+`--platform` olmadan ilk etkileşimsiz çalıştırmada kurulum ana makineden bağımsız kalır; sonraki çalıştırmalar `.truthmark/config.yml` içinde kayıtlı seçimi korur.
+
 Şimdi en yaygın benimseme yolunu deneyin: kod ve testlerden mevcut bir davranışı belgeleyin. AI kodlama ana makinenizde, kurulu iş akışına şunu isteyin:

 ```text
@@ -45,7 +37,7 @@ git diff

 Bundan sonra kullanıcılar normalde Truth Sync'i doğrudan çağırmamalıdır. AI ana makineniz üzerinden kod yazmaya devam edin; kurulu depo yönergeleri, işlevsel kod değiştiğinde teslimden önce ajana ilgili testleri çalıştırmasını ve Truth Sync incelemesini yapmasını söyler. Siz ortaya çıkan kod farkını ve truth-belge farkını incelersiniz.

-Yalnızca CLI doğrulaması istiyor ve henüz ana makineye özgü AI iş akışları istemiyorsanız, `platforms` alanını dışarıda bırakıp `truthmark init && truthmark check` çalıştırın; daha sonra bir platform ekleyip `truthmark init` komutunu yeniden çalıştırabilirsiniz.
+Yalnızca CLI doğrulaması istiyorsanız `none` seçip `truthmark check` çalıştırın; platform seçmek için daha sonra `truthmark init` komutunu yeniden çalıştırabilirsiniz.

 ## 💡 Sorun: AI dokümantasyon boşluğu

@@ -90,8 +82,7 @@ Truthmark’ın depo yerelinde tek bir sözleşmesi ve onu kullanmanın iki yolu

 Bakımcılar ve CI, CLI kullanır:

-* `truthmark config` - ilk yapılandırmayı oluşturur.
-* `truthmark init` - yönlendirmeyi, truth-doc iskelelerini ve AI ana makine talimatlarını kurar veya yeniler.
+* `truthmark init` - yapılandırmayı oluşturur veya yeniler, sıfır ya da daha fazla platform seçtirir ve yönlendirmeyi, truth-doc iskelelerini ve seçilen AI ana makine talimatlarını kurar.
 * `truthmark check` - depo gerçeğini terminalden doğrular.

 ### Ajanlar kod yazarken sözleşmeyi izler
@@ -199,7 +190,7 @@ Komut komut kullanım, yüzey karşılaştırmaları, desteklenen platform ayrı

 Mevcut sürüm şunları sağlar:

- config, init, check, index, impact ve iş akışı durumu için yerel CLI komutları
+- init, check, index, impact ve iş akışı durumu için yerel CLI komutları
 - Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity ve Cursor için oluşturulan depo yerelinde ajan talimatları
 - yönlendirme, yetki, frontmatter, bağlantı, güncellik, üretilmiş yüzey, dal kapsamı ve kapsam tanıları
 - dal kapsamlı gerçeklik belgeleri ve türetilmiş depo zekâsı artefaktları
@@ -223,3 +214,7 @@ Barındırılan bir hizmet, MCP sunucusu, vektör veritabanı, gizli bellek katm
 ## Lisans

 MIT. Bkz. [LICENSE](../../LICENSE).
+
+## Güvenli kaldırma
+
+`truthmark uninstall --dry-run` komutunu kullanarak tam olarak oluşturulan ana bilgisayar yüzeylerini inceleyin, ardından kaldırmak için `truthmark uninstall --apply` komutunu çalıştırın. Oluşturulan truth, yapılandırma, şablonlar, Portal çıktısı, Gemini dosyaları ve alakasız kullanıcı dosyaları korunur; global npm kurulumunu paket yöneticinizle ayrı olarak kaldırın.
@@ -13,30 +13,22 @@ Chạy lệnh này bên trong kho Git mà bạn muốn Truthmark quản lý:
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-Bật máy chủ AI mà bạn thực sự sử dụng. Cấu hình mới không gắn với máy chủ nào, vì vậy hãy thêm danh sách `platforms` ở cấp cao nhất vào `.truthmark/config.yml` trước khi khởi tạo:
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-Sau đó cài đặt tài liệu sự thật cục bộ của kho, định tuyến và các bề mặt quy trình làm việc cho tác tử:
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+Trong terminal tương tác, `truthmark init` hiển thị danh sách đa lựa chọn được đánh số. Chọn không, một hoặc nhiều nền tảng, hoặc nhập `none` để thiết lập chỉ dùng CLI và không gắn với host.
+
+Với script và CI, hãy lặp lại `--platform`; `--json` không bao giờ hiển thị lời nhắc:
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+Ở lần chạy không tương tác đầu tiên mà không có `--platform`, thiết lập vẫn trung lập với host; các lần chạy sau giữ lựa chọn đã lưu trong `.truthmark/config.yml`.
+
 Bây giờ hãy thử lộ trình áp dụng phổ biến nhất: ghi tài liệu cho một hành vi hiện có từ mã và kiểm thử. Trong máy chủ lập trình AI của bạn, hãy yêu cầu quy trình đã cài đặt:

 ```text
@@ -45,7 +37,7 @@ Bây giờ hãy thử lộ trình áp dụng phổ biến nhất: ghi tài liệ

 Sau đó, người dùng thường không nên gọi Truth Sync trực tiếp. Hãy tiếp tục lập trình qua máy chủ AI của bạn; các chỉ dẫn kho đã cài đặt yêu cầu tác tử chạy các kiểm thử liên quan và thực hiện đánh giá Truth Sync trước khi bàn giao khi mã chức năng thay đổi. Bạn xem xét phần diff mã kết quả cùng với diff tài liệu truth.

-Nếu bạn chỉ muốn xác thực bằng CLI và chưa muốn các quy trình AI theo máy chủ, hãy để trống `platforms` và chạy `truthmark init && truthmark check`; bạn có thể thêm nền tảng sau và chạy lại `truthmark init`.
+Nếu bạn chỉ muốn xác thực bằng CLI, hãy chọn `none` rồi chạy `truthmark check`; bạn có thể chạy lại `truthmark init` sau để chọn nền tảng.

 ## 💡 Vấn đề: khoảng trống tài liệu AI

@@ -90,8 +82,7 @@ Truthmark có một hợp đồng cục bộ trong kho và hai cách sử dụng

 Người bảo trì và CI dùng CLI:

-* `truthmark config` - tạo cấu hình ban đầu.
-* `truthmark init` - cài đặt hoặc làm mới định tuyến, scaffold truth-doc và hướng dẫn cho AI host.
+* `truthmark init` - tạo hoặc làm mới cấu hình, cho phép chọn không, một hoặc nhiều nền tảng, rồi cài đặt định tuyến, scaffold truth-doc và hướng dẫn cho các AI host đã chọn.
 * `truthmark check` - xác thực sự thật của kho từ terminal.

 ### Tác tử tuân theo hợp đồng khi viết mã
@@ -199,7 +190,7 @@ README là mặt tiền: ngữ cảnh nhanh, bắt đầu nhanh và mô hình t

 Bản phát hành hiện tại cung cấp:

- các lệnh CLI cục bộ cho config, init, check, index, impact và trạng thái quy trình
+- các lệnh CLI cục bộ cho init, check, index, impact và trạng thái quy trình
 - hướng dẫn tác tử cục bộ trong kho được tạo cho Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity và Cursor
 - chẩn đoán về định tuyến, thẩm quyền, frontmatter, liên kết, độ mới, bề mặt sinh ra, phạm vi nhánh và độ phủ
 - tài liệu sự thật theo phạm vi nhánh và các hiện vật trí tuệ kho được suy dẫn
@@ -223,3 +214,7 @@ Nó không phải dịch vụ lưu trữ, máy chủ MCP, cơ sở dữ liệu v
 ## Giấy phép

 MIT. Xem [LICENSE](../../LICENSE).
+
+## Gỡ cài đặt an toàn
+
+Sử dụng `truthmark uninstall --dry-run` để xem lại chính xác các bề mặt host đã tạo ra, rồi `truthmark uninstall --apply` để loại bỏ chúng. Các truth đã tạo, cấu hình, mẫu, đầu ra Portal, tệp Gemini và các tệp người dùng không liên quan sẽ được giữ nguyên; hãy gỡ bỏ cài đặt npm toàn cục riêng biệt bằng trình quản lý gói của bạn.
@@ -13,30 +13,22 @@
 ```bash
 cd /path/to/your-repo
 npm install -g truthmark
-truthmark config
-```
-
-启用你实际使用的 AI 宿主。新配置默认与宿主无关，因此在初始化前，先把顶层 `platforms` 列表添加到 `.truthmark/config.yml`：
-
-```yaml
-version: 2
-platforms:
-  - codex        # or: claude-code, github-copilot, opencode, antigravity, cursor
-truthmark:
-  workspace: docs/truthmark
-  generated:
-    portal:
-      enabled: false
-```
-
-然后安装仓库本地的事实文档、路由和 AI 宿主指令：
-
-```bash
 truthmark init
 truthmark check
 git diff
 ```

+在交互式终端中，`truthmark init` 会显示带编号的多选列表。可选择零个或多个平台，也可输入 `none`，仅进行与宿主无关的 CLI 设置。
+
+在脚本和 CI 中可重复使用 `--platform`；`--json` 永远不会提示输入：
+
+```bash
+truthmark init --platform codex --platform cursor
+truthmark init --json
+```
+
+首次非交互运行且没有 `--platform` 时，初始化保持宿主中立；之后的运行会保留 `.truthmark/config.yml` 中保存的选择。
+
 现在尝试最常见的采用路径：根据代码和测试记录一个已有行为。在你的 AI 编码宿主中，请求已安装的工作流：

 ```text
@@ -45,7 +37,7 @@ git diff

 之后，用户通常不应直接调用 Truth Sync。继续通过你的 AI 宿主编写代码；已安装的仓库指令会告诉代理：当功能代码发生变化时，在交接前运行相关测试并执行 Truth Sync 审查。你审查最终的代码 diff 和事实文档 diff。

-如果你暂时只想要 CLI 验证，而不需要特定宿主的 AI 工作流，可以省略 `platforms`，并运行 `truthmark init && truthmark check`；之后你可以再添加平台并重新运行 `truthmark init`。
+如果暂时只需要 CLI 验证，请选择 `none`，然后运行 `truthmark check`；之后可重新运行 `truthmark init` 来选择平台。

 ## 💡 问题：AI 文档缺口

@@ -90,8 +82,7 @@ Truthmark 有一个仓库本地契约，以及两种使用方式。

 维护者和 CI 使用 CLI：

-* `truthmark config` - 创建初始配置。
-* `truthmark init` - 安装或刷新路由、事实文档脚手架和 AI 宿主指令。
+* `truthmark init` - 创建或刷新配置，选择零个或多个平台，并安装路由、事实文档脚手架及所选 AI 宿主的指令。
 * `truthmark check` - 从终端验证仓库事实。

 ### 代理在编码时遵循契约
@@ -199,7 +190,7 @@ README 是门面：快速背景、快速开始和核心心智模型。

 当前版本提供：

- 用于 config、init、check、index、impact 和 workflow status 的本地 CLI 命令
+- 用于 init、check、index、impact 和 workflow status 的本地 CLI 命令
 - 为 Codex、Claude Code、GitHub Copilot、OpenCode、Antigravity 和 Cursor 生成的仓库本地代理指令
 - 路由、权限、frontmatter、链接、新鲜度、生成界面、分支范围和覆盖率诊断
 - 按分支生效的事实文档和派生的仓库智能产物
@@ -223,3 +214,7 @@ Truthmark 有意保持小而明确：本地、已提交、按分支生效、可
 ## 许可证

 MIT。见 [LICENSE](../../LICENSE)。
+
+## 安全移除
+
+使用 `truthmark uninstall --dry-run` 查看精确生成的主机表面（host surfaces），然后使用 `truthmark uninstall --apply` 将其移除。已创建的 truth、配置、模板、Portal 输出、Gemini 文件以及不相关的用户文件将被保留；请使用包管理器单独移除全局 npm 安装。
@@ -0,0 +1,27 @@
+---
+status: draft
+doc_type: research-index
+last_reviewed: 2026-06-29
+source_of_truth:
+  - ../../workflow-eval-framwork/README.md
+  - ../../workflow-eval-framwork/catalog.yaml
+  - ../../scripts/workflow-eval-framwork/run-agent-scenario.mjs
+  - ../../tests/evals/workflow-eval-framwork.test.ts
+---
+
+# Manual Agent Skill And Prompt Quality Eval Framework
+
+The implemented manual evaluation framework lives under `workflow-eval-framwork/`.
+
+Use these artifacts:
+
+- Framework README: [`../../workflow-eval-framwork/README.md`](../../workflow-eval-framwork/README.md)
+- Catalog: [`../../workflow-eval-framwork/catalog.yaml`](../../workflow-eval-framwork/catalog.yaml)
+- Manual runner: [`../../scripts/workflow-eval-framwork/run-agent-scenario.mjs`](../../scripts/workflow-eval-framwork/run-agent-scenario.mjs)
+- Schema and fake-runner tests: [`../../tests/evals/workflow-eval-framwork.test.ts`](../../tests/evals/workflow-eval-framwork.test.ts)
+
+The requested framework folder name is intentionally spelled `workflow-eval-framwork`.
+
+The key invariant is that Truthmark's generated-surface tests prove injection and freshness, while this framework tests actual agent behavior when workflow skills and prompts are used.
+
+The framework is manual and token-expensive. It must not become a default CI gate, hosted service, daemon, database, hidden memory layer, or required downstream runtime.
@@ -101,7 +101,7 @@ Gemini generated surfaces are command files such as `.gemini/commands/truthmark/

 ### Research folder

-The research folder contains non-canonical design references. The 2026-05-15 review describes skills as context packages, descriptions as routing logic, progressive disclosure, evals, and security considerations. It explicitly states that behavior-bearing findings must be promoted into truth docs, the manifest, renderers, generated surfaces, and tests before becoming behavior. Source: [research/2026-05-15-agent-skills-workflow-review.md](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-15-agent-skills-workflow-review.md).
+The docs/research folder contains non-canonical design references. The 2026-05-15 review describes skills as context packages, descriptions as routing logic, progressive disclosure, evals, and security considerations. It explicitly states that behavior-bearing findings must be promoted into truth docs, the manifest, renderers, generated surfaces, and tests before becoming behavior. Source: [research/2026-05-15-agent-skills-workflow-review.md](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-15-agent-skills-workflow-review.md).

 The 2026-05-16 write-capable OpenCode subagents design proposes parent-issued write leases, parent-owned final acceptance, and possible workers such as `truth-doc-writer`, `truth-route-structurer`, and `truth-realize-writer`. The research file is explicitly non-canonical. Source: [research/2026-05-16-write-capable-opencode-subagents-design.md](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-16-write-capable-opencode-subagents-design.md).

@@ -805,7 +805,7 @@ The literature raises several questions that are not fully answered for this rep
 - Host surfaces include skills, prompts, commands, managed instruction blocks, and agents depending on host.
 - Current generated surfaces include read-only verifiers plus leased `truth-doc-writer` agents where hosts support agents.
 - Gemini generated surfaces in the inspected branch are command files rather than generated Gemini subagents.
- The research folder contains non-canonical design references and should not be treated as behavior-bearing unless promoted.
+- The docs/research folder contains non-canonical design references and should not be treated as behavior-bearing unless promoted.
 - The write-capable OpenCode subagents research file proposes a broader write-worker design, while the current promoted worker in source/generated surfaces is the doc writer.

 ## Appendix C: Search Queries Used
@@ -1,6 +1,6 @@
 # Truthmark Prompt, Skill, Agent, and Workflow Quality Uplift Review

-Intended commit path: `research/prompt-skill-agent-workflow-quality-uplift-review.md`
+Intended commit path: `docs/research/prompt-skill-agent-workflow-quality-uplift-review.md`

 ## Status

@@ -11,7 +11,7 @@ It does not by itself change Truthmark workflows, generated surfaces, skills, ag
 This review is based on:

 - the current repository branch: `subagent-improvement`;
- the current Truthmark research folder;
+- the current Truthmark docs/research folder;
 - the current generated host surfaces;
 - the literature review corpus on prompt standards, skills, agents/subagents, workflow implementation, permissions, routing, evaluation, security, and maintenance.

@@ -136,11 +136,11 @@ Truthmark also has a write-capable `truth-doc-writer`. It requires a parent-issu

 ### Research folder

-The research folder contains non-canonical design references.
+The docs/research folder contains non-canonical design references.

-`research/2026-05-15-agent-skills-workflow-review.md` describes skills as context packages, descriptions as routing logic, progressive disclosure, and eval needs. Repository evidence: [`research/2026-05-15-agent-skills-workflow-review.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-15-agent-skills-workflow-review.md).
+`docs/research/2026-05-15-agent-skills-workflow-review.md` describes skills as context packages, descriptions as routing logic, progressive disclosure, and eval needs. Repository evidence: [`docs/research/2026-05-15-agent-skills-workflow-review.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-15-agent-skills-workflow-review.md).

-`research/2026-05-16-write-capable-opencode-subagents-design.md` proposes write-capable OpenCode subagents under explicit parent-issued leases. It is non-canonical. Current source has already promoted the `truth-doc-writer` pattern beyond OpenCode to several host surfaces; broader workers such as route structurer and realize writer remain research-only ideas. Repository evidence: [`research/2026-05-16-write-capable-opencode-subagents-design.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-16-write-capable-opencode-subagents-design.md).
+`docs/research/2026-05-16-write-capable-opencode-subagents-design.md` proposes write-capable OpenCode subagents under explicit parent-issued leases. It is non-canonical. Current source has already promoted the `truth-doc-writer` pattern beyond OpenCode to several host surfaces; broader workers such as route structurer and realize writer remain research-only ideas. Repository evidence: [`docs/research/2026-05-16-write-capable-opencode-subagents-design.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-16-write-capable-opencode-subagents-design.md).

 ### Current tests

@@ -321,13 +321,13 @@ Severity levels:
 | Already strong | Sync-only automatic workflow | Truth Sync is the only automatic finish-time workflow; Structure, Document, Realize, and Check are explicit/manual. | Workflow overview, manifest, root blocks, and generated surfaces all state this. Sources: [`docs/truth/workflows/overview.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/docs/truth/workflows/overview.md), [`src/agents/workflow-manifest.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/src/agents/workflow-manifest.ts), [`AGENTS.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/AGENTS.md). | Microsoft distinguishes AI-selected skills from deterministic workflows for side effects/approvals; Claude supports manual-only skill modes; GitHub distinguishes automatic and manual surfaces. Sources: [Microsoft Agent Skills](https://learn.microsoft.com/en-us/agent-framework/agents/skills), [Claude Code skills](https://code.claude.com/docs/en/slash-commands), [GitHub customization cheat sheet](https://docs.github.com/en/copilot/reference/customization-cheat-sheet). | Automatic side-effecting workflows should be narrowly scoped. Truthmark’s current automatic behavior is conservative. |
 | Already strong | Read-only verifier subagents | Route auditor, claim verifier, and doc reviewer are scoped as read-only verifier agents with parent-owned decisions. | `workflow-surfaces.ts` defines read-only context boundaries and JSON report expectations. Generated host agents reflect this. Source: [`src/templates/workflow-surfaces.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/src/templates/workflow-surfaces.ts). | Claude, Codex, OpenCode, and Gemini describe subagents as specialists with separate context and tool scopes. Sources: [Claude Code subagents](https://code.claude.com/docs/en/sub-agents), [OpenAI Codex Subagents](https://developers.openai.com/codex/subagents), [OpenCode Agents](https://opencode.ai/docs/agents/), [Gemini CLI subagents](https://developers.googleblog.com/subagents-have-arrived-in-gemini-cli/). | Verifier agents are a low-risk, high-fit subagent pattern for Truthmark. |
 | Already strong | Write lease concept | `truth-doc-writer` requires a parent-issued lease and parent diff validation. | `workflow-surfaces.ts`, generated doc-writer agents, and write-lease tests encode lease fields, off-lease behavior, and path validation. Sources: [`src/templates/workflow-surfaces.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/src/templates/workflow-surfaces.ts), [`.opencode/agents/truth-doc-writer.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/.opencode/agents/truth-doc-writer.md), [`tests/agents/write-lease.test.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/tests/agents/write-lease.test.ts). | OpenCode supports least-privilege permissions, Microsoft and MCP stress sandbox/allowlist controls, and NCSC stresses deterministic safeguards because prompt injection cannot be fully eliminated. Sources: [OpenCode Permissions](https://opencode.ai/docs/permissions/), [Microsoft Agent Skills](https://learn.microsoft.com/en-us/agent-framework/agents/skills), [MCP Security Best Practices](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices), [NCSC prompt injection guidance](https://www.ncsc.gov.uk/blog-post/prompt-injection-is-not-sql-injection). | The lease model is a practical bridge between static host permissions and runtime workflow intent. |
-| Critical | Future write-worker expansion | Adding `truth-route-structurer`, `truth-realize-writer`, or other write-capable workers before complete leases, conflict policy, diff validation, report schemas, and evals would be a critical risk. | The research file proposes additional write-capable workers but labels itself non-canonical. Current source promotes only `truth-doc-writer`. Sources: [`research/2026-05-16-write-capable-opencode-subagents-design.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-16-write-capable-opencode-subagents-design.md), [`src/agents/workflow-manifest.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/src/agents/workflow-manifest.ts). | Gemini cautions that heavy code-edit subagents can conflict or overwrite each other; Anthropic recommends adding complexity only when measurement shows improvement; NCSC recommends deterministic safeguards and privilege reduction. Sources: [Gemini CLI subagents](https://developers.googleblog.com/subagents-have-arrived-in-gemini-cli/), [Anthropic Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents), [NCSC prompt injection guidance](https://www.ncsc.gov.uk/blog-post/prompt-injection-is-not-sql-injection). | Code-writing or route-rewriting workers can create overlapping edits, hidden policy drift, and false acceptance if not strictly controlled. |
+| Critical | Future write-worker expansion | Adding `truth-route-structurer`, `truth-realize-writer`, or other write-capable workers before complete leases, conflict policy, diff validation, report schemas, and evals would be a critical risk. | The research file proposes additional write-capable workers but labels itself non-canonical. Current source promotes only `truth-doc-writer`. Sources: [`docs/research/2026-05-16-write-capable-opencode-subagents-design.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-16-write-capable-opencode-subagents-design.md), [`src/agents/workflow-manifest.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/src/agents/workflow-manifest.ts). | Gemini cautions that heavy code-edit subagents can conflict or overwrite each other; Anthropic recommends adding complexity only when measurement shows improvement; NCSC recommends deterministic safeguards and privilege reduction. Sources: [Gemini CLI subagents](https://developers.googleblog.com/subagents-have-arrived-in-gemini-cli/), [Anthropic Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents), [NCSC prompt injection guidance](https://www.ncsc.gov.uk/blog-post/prompt-injection-is-not-sql-injection). | Code-writing or route-rewriting workers can create overlapping edits, hidden policy drift, and false acceptance if not strictly controlled. |
 | High | Empirical prompt/workflow eval coverage | The repo has strong deterministic shape tests, but inspected evidence does not show a complete prompt-style eval suite for real workflow routing, negative prompts, forbidden adjacency, report compliance, and delegation behavior. | Tests enforce manifest shape and generated surfaces; they do not appear to exercise a broad model-facing prompt corpus. Sources: [`tests/agents/workflow-manifest.test.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/tests/agents/workflow-manifest.test.ts), [`tests/init/init.test.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/tests/init/init.test.ts), [`tests/agents/prompts.test.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/tests/agents/prompts.test.ts). | OpenAI recommends explicit, implicit, contextual, and negative-control eval prompts; Perplexity recommends evals before skill changes and neighbor-confusion tests; Anthropic says prompt engineering should begin from success criteria and empirical tests. Sources: [OpenAI Eval Skills](https://developers.openai.com/blog/eval-skills), [Perplexity](https://research.perplexity.ai/articles/designing-refining-and-maintaining-agent-skills-at-perplexity), [Anthropic Prompt Engineering Overview](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview). | Without behavioral evals, prompt and routing quality cannot be claimed as world-class. |
 | High | Delegation policy not fully first-class | The manifest lists subagents but does not appear to own detailed `delegateWhen`, `inlineWhen`, conflict policy, parallelism policy, or host fallback policy. | `workflow-manifest.ts` has read-only and write subagent assignment but no structured delegation-policy fields. Source: [`src/agents/workflow-manifest.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/src/agents/workflow-manifest.ts). | Claude distinguishes when to use subagents versus the main conversation; Codex notes subagents consume more tokens; Gemini cautions about parallel code-edit conflicts; Anthropic recommends simple workflows and measured complexity. Sources: [Claude Code subagents](https://code.claude.com/docs/en/sub-agents), [OpenAI Codex Subagents](https://developers.openai.com/codex/subagents), [Gemini CLI subagents](https://developers.googleblog.com/subagents-have-arrived-in-gemini-cli/), [Anthropic Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents). | Subagent dispatch is a product behavior, not a documentation detail. It should be manifest-owned and testable. |
 | High | Cross-host permission equivalence cannot be assumed | The same logical doc writer exists across several hosts, but host permission systems differ; Gemini currently has commands only. | Generated surfaces include doc writers for Codex, OpenCode, Claude, and GitHub Copilot, while Gemini receives commands. OpenCode has explicit granular permissions. Sources: [`src/templates/generated-surfaces.ts`](https://github.com/merlinhu1/truthmark/blob/subagent-improvement/src/templates/generated-surfaces.ts), [`.gemini/commands/truthmark/sync.toml`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/.gemini/commands/truthmark/sync.toml), [`.opencode/agents/truth-doc-writer.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/.opencode/agents/truth-doc-writer.md). | GitHub docs show feature support varies across surfaces; Claude states skill `allowed-tools` grants permission but does not necessarily restrict other tools; OpenCode permissions are granular but host-specific; Gemini subagents are separate from command files. Sources: [GitHub customization cheat sheet](https://docs.github.com/en/copilot/reference/customization-cheat-sheet), [Claude Code skills](https://code.claude.com/docs/en/slash-commands), [OpenCode Permissions](https://opencode.ai/docs/permissions/), [Gemini CLI subagents](https://developers.googleblog.com/subagents-have-arrived-in-gemini-cli/). | Protocol parity and permission parity are different. Truthmark should not imply identical safety across hosts without conformance evidence. |
 | High | Parent diff validation is not yet proven end-to-end | The lease pattern and path validator are strong, but inspected tests do not show complete parent-orchestration simulations that compare worker reports, actual diffs, workflow status, and final acceptance. | `write-lease.test.ts` validates allowed/off-lease paths; generated prompts instruct parent diff validation. Sources: [`tests/agents/write-lease.test.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/tests/agents/write-lease.test.ts), [`src/templates/workflow-surfaces.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/src/templates/workflow-surfaces.ts). | OpenAI agent evals evaluate traces, handoffs, and violations; Goalkeeper’s judge gate inspects diff/log against a Definition of Done after validators pass. Sources: [OpenAI Agent Evals Guide](https://developers.openai.com/api/docs/guides/agent-evals), [Goalkeeper](https://github.com/itsuzef/goalkeeper). | The most important safety property for write-capable workers is acceptance based on actual diff, not self-report. |
 | High | Report contracts are not fully schema-owned across all surfaces | The manifest includes report sections and generated surfaces contain report instructions, but inspected evidence does not show a complete schema validator for every workflow report and every worker report across hosts. | Manifest has `reportSections`; write worker returns YAML; Sync has structured parser references; tests check some report sections. Sources: [`src/agents/workflow-manifest.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/src/agents/workflow-manifest.ts), [`src/templates/workflow-surfaces.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/src/templates/workflow-surfaces.ts), [`tests/agents/prompts.test.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/tests/agents/prompts.test.ts). | OpenAI evals and Goalkeeper both treat structured outputs and checkable definitions of done as evaluation artifacts. Sources: [OpenAI Eval Skills](https://developers.openai.com/blog/eval-skills), [OpenAI Agent Evals Guide](https://developers.openai.com/api/docs/guides/agent-evals), [Goalkeeper](https://github.com/itsuzef/goalkeeper). | Report shape is part of workflow reliability and should be machine-checkable where possible. |
-| High | Stale research/canonical drift risk | The write-capable subagent research doc describes a proposed OpenCode-first direction, but current source has already promoted `truth-doc-writer` across several hosts. | Research file is non-canonical and proposes broader workers; canonical source/generated surfaces include doc writer across Codex/OpenCode/Claude/GitHub. Sources: [`research/2026-05-16-write-capable-opencode-subagents-design.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-16-write-capable-opencode-subagents-design.md), [`src/templates/generated-surfaces.ts`](https://github.com/merlinhu1/truthmark/blob/subagent-improvement/src/templates/generated-surfaces.ts). | Anthropic cautions against time-sensitive stale skill content; Perplexity says skill descriptions and changes need maintenance/evals because small wording changes affect routing. Sources: [Anthropic Skill Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices), [Perplexity](https://research.perplexity.ai/articles/designing-refining-and-maintaining-agent-skills-at-perplexity). | Agents may treat research as current behavior unless the canonical boundary is repeatedly clear. |
+| High | Stale research/canonical drift risk | The write-capable subagent research doc describes a proposed OpenCode-first direction, but current source has already promoted `truth-doc-writer` across several hosts. | Research file is non-canonical and proposes broader workers; canonical source/generated surfaces include doc writer across Codex/OpenCode/Claude/GitHub. Sources: [`docs/research/2026-05-16-write-capable-opencode-subagents-design.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-16-write-capable-opencode-subagents-design.md), [`src/templates/generated-surfaces.ts`](https://github.com/merlinhu1/truthmark/blob/subagent-improvement/src/templates/generated-surfaces.ts). | Anthropic cautions against time-sensitive stale skill content; Perplexity says skill descriptions and changes need maintenance/evals because small wording changes affect routing. Sources: [Anthropic Skill Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices), [Perplexity](https://research.perplexity.ai/articles/designing-refining-and-maintaining-agent-skills-at-perplexity). | Agents may treat research as current behavior unless the canonical boundary is repeatedly clear. |
 | Medium | Skill body bloat and progressive disclosure | Generated workflow skills are necessarily procedural, but the repository does not yet appear to enforce broad body-size or duplication budgets across all generated host surfaces. | Existing tests enforce compact root blocks and description length, but inspected tests do not appear to enforce skill body budget or duplicated-procedure budget across every generated skill. Sources: [`tests/init/init.test.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/tests/init/init.test.ts), [`tests/agents/workflow-manifest.test.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/tests/agents/workflow-manifest.test.ts). | Anthropic recommends keeping `SKILL.md` concise and splitting details; Perplexity says every skill is a context tax; Agent Skills spec recommends progressive disclosure. Sources: [Anthropic Skill Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices), [Perplexity](https://research.perplexity.ai/articles/designing-refining-and-maintaining-agent-skills-at-perplexity), [Agent Skills Specification](https://agentskills.io/specification). | Workflow skills can become too large to route well or too expensive to load. |
 | Medium | Positive/negative routing examples are manifest data but not enough by themselves | The manifest has positive, negative, and forbidden-adjacent examples, but model-facing prompt behavior needs an eval corpus. | Manifest includes these arrays and tests require them. Source: [`src/agents/workflow-manifest.ts`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/src/agents/workflow-manifest.ts). | OpenAI and Perplexity both recommend explicit prompt sets, negative controls, and neighbor-confusion evals. Sources: [OpenAI Eval Skills](https://developers.openai.com/blog/eval-skills), [Perplexity](https://research.perplexity.ai/articles/designing-refining-and-maintaining-agent-skills-at-perplexity). | Metadata can be correct while actual model routing still fails. |
 | Medium | Gemini capability gap | Truthmark currently generates Gemini commands, while 2026 Gemini CLI also supports subagents. This is not necessarily wrong, but it is a capability difference that should remain explicit. | Gemini generated surfaces are command TOMLs under `.gemini/commands/truthmark`. Source: [`.gemini/commands/truthmark/sync.toml`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/.gemini/commands/truthmark/sync.toml). | Gemini CLI supports project/global subagents under `.gemini/agents` with descriptions, tools, and separate context; Google cautions about heavy code-edit conflicts. Source: [Gemini CLI subagents](https://developers.googleblog.com/subagents-have-arrived-in-gemini-cli/). | Users may assume all hosts have the same generated subagent behavior. |
@@ -469,15 +469,15 @@ Every recommendation below is traceable to both repository evidence and reviewed

 These are small, low-risk changes that improve workflow quality immediately.

-#### 1. Add this research document under `research/`
+#### 1. Add this research document under `docs/research/`

 Change:

- Add `research/prompt-skill-agent-workflow-quality-uplift-review.md`.
+- Add `docs/research/prompt-skill-agent-workflow-quality-uplift-review.md`.

 Repository evidence:

- The research folder already contains non-canonical design references and explicitly separates research from canonical behavior. Source: [`research/2026-05-15-agent-skills-workflow-review.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-15-agent-skills-workflow-review.md).
+- The docs/research folder already contains non-canonical design references and explicitly separates research from canonical behavior. Source: [`docs/research/2026-05-15-agent-skills-workflow-review.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-15-agent-skills-workflow-review.md).

 External evidence:

@@ -491,14 +491,14 @@ Rationale:

 Change:

- Add a short note near the top of `research/2026-05-16-write-capable-opencode-subagents-design.md`:
+- Add a short note near the top of `docs/research/2026-05-16-write-capable-opencode-subagents-design.md`:
  - `truth-doc-writer` has been promoted into source/generated surfaces for several hosts.
  - Additional workers such as `truth-route-structurer` and `truth-realize-writer` remain research-only.
  - Behavior-bearing rules live in source/generated surfaces/tests, not this research file.

 Repository evidence:

- The research file proposes write-capable OpenCode subagents, while current source/generated surfaces include `truth-doc-writer` across more hosts. Sources: [`research/2026-05-16-write-capable-opencode-subagents-design.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-16-write-capable-opencode-subagents-design.md), [`src/templates/generated-surfaces.ts`](https://github.com/merlinhu1/truthmark/blob/subagent-improvement/src/templates/generated-surfaces.ts).
+- The research file proposes write-capable OpenCode subagents, while current source/generated surfaces include `truth-doc-writer` across more hosts. Sources: [`docs/research/2026-05-16-write-capable-opencode-subagents-design.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-16-write-capable-opencode-subagents-design.md), [`src/templates/generated-surfaces.ts`](https://github.com/merlinhu1/truthmark/blob/subagent-improvement/src/templates/generated-surfaces.ts).

 External evidence:

@@ -816,7 +816,7 @@ Research question:

 Repository evidence:

- The research file proposes broader write-capable workers, but source currently promotes only `truth-doc-writer`. Source: [`research/2026-05-16-write-capable-opencode-subagents-design.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-16-write-capable-opencode-subagents-design.md).
+- The research file proposes broader write-capable workers, but source currently promotes only `truth-doc-writer`. Source: [`docs/research/2026-05-16-write-capable-opencode-subagents-design.md`](https://raw.githubusercontent.com/merlinhu1/truthmark/subagent-improvement/research/2026-05-16-write-capable-opencode-subagents-design.md).

 External evidence:

@@ -1098,8 +1098,8 @@ Likely files to change for the “Ship now” and “Build next” items:

 ### Research files

- `research/prompt-skill-agent-workflow-quality-uplift-review.md`
- `research/2026-05-16-write-capable-opencode-subagents-design.md`
+- `docs/research/prompt-skill-agent-workflow-quality-uplift-review.md`
+- `docs/research/2026-05-16-write-capable-opencode-subagents-design.md`

 ### Canonical truth docs

@@ -1,7 +1,7 @@
 ---
 status: active
 doc_type: standard
-last_reviewed: 2026-05-06
+last_reviewed: 2026-07-30
 source_of_truth:
  - ../README.md
  - documentation-governance.md
@@ -35,8 +35,8 @@ These are bootstrap defaults, not immutable law. Repositories should replace or

 - Each document should have one primary responsibility.
 - Each class of fact should have one canonical source.
- Current implementation, reusable standards, and future proposals should be stored separately.
- Historical planning artifacts should stay historical until they are rewritten into the current canonical tree.
+- Current implementation, reusable standards, and accepted decision rationale have distinct canonical owners.
+- Git history carries superseded planning context; active docs keep only current behavior and necessary rationale in the owning decision section.
 - Do not maintain parallel documentation trees for the same subject.
 - The root README may remain an onboarding or product-facing entry point, but it should not silently compete with canonical engineering docs.

@@ -1,7 +1,7 @@
 ---
 status: active
 doc_type: standard
-last_reviewed: 2026-05-09
+last_reviewed: 2026-07-30
 source_of_truth:
  - ../README.md
  - ../ai/repo-rules.md
@@ -23,8 +23,8 @@ Small repositories are in scope. A project does not need a large documentation p

 - Each document should have one primary responsibility.
 - Each class of fact should have one canonical source.
- Current implementation, reusable standards, and future proposals should be stored separately.
- Historical plans and generated planning artifacts should stay outside the canonical current-state tree until they are intentionally rewritten.
+- Current implementation, reusable standards, and accepted decision rationale have distinct canonical owners.
+- Git history carries superseded plans and implementation choices; active docs keep only current behavior and necessary rationale in the owning decision section.
 - Do not maintain parallel documentation trees for the same subject.
 - The root README may introduce the project or product, but it should not silently compete with canonical engineering or behavior docs.
 - Agent instruction files may install workflow behavior, but they are not product truth unless a project explicitly includes them in authority.
@@ -60,7 +60,7 @@ Use a small number of stable document classes:
 - architecture for current structural decisions
 - truth docs for current behavior and invariants

-Projects do not need every class on day one. They do need a clear separation between current truth and future proposals.
+Projects do not need every class on day one. They do need clear ownership for current truth, reusable standards, and accepted decision rationale.

 Architecture docs describe system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, and generated-surface ownership.

@@ -70,13 +70,13 @@ Architecture docs should not carry ordinary product behavior, endpoint details,

 Active decisions are part of current truth. They live in the canonical doc for the feature, contract, architecture surface, or standard they govern.

-Use `Product Decisions` and `Rationale` sections for decisions that explain non-obvious behavior, boundaries, rejected directions, or migration constraints.
+Use `Product Decisions` and `Engineering Decisions` sections for accepted decisions and the rationale needed to explain non-obvious behavior, boundaries, rejected directions, or migration constraints.

 When a decision changes, replace the old active decision in the same canonical doc. Git history is the historical decision log.

 Date active decisions inline when added or changed, for example `Decision (2026-05-09): keep routing agent-native`. The date is context on the active decision, not a separate historical log.

-Do not create separate timestamped ADR folders, planning tickets, or historical design notes as the current decision source. Historical notes may remain supplementary only after the active decision is promoted into the canonical doc.
+Do not create separate timestamped ADR folders, planning tickets, or historical design notes as repository guidance. Promote necessary accepted rationale into the owning decision section and rely on Git history for superseded context.

 ## Update Rules

@@ -115,7 +115,7 @@ Do not create separate timestamped ADR folders, planning tickets, or historical
 - If routing is broad or overloaded, has Truth Structure repaired topology before new truth docs were created?
 - Are duplicated or shadow documentation paths being avoided?
 - Is generated helper output still treated as non-authoritative rather than truth?
- If historical notes exist, have they stayed clearly separate from the current canonical tree?
+- Are superseded plans absent from active docs, with necessary accepted rationale kept in the owning decision section?

 ## Product Decisions

@@ -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.

@@ -1,7 +1,7 @@
 ---
 status: active
 truth_kind: engineering-architecture
-last_reviewed: 2026-06-20
+last_reviewed: 2026-07-30
 ---

 # Architecture Overview
@@ -22,7 +22,9 @@ 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.
+- Generated ownership is derived from renderer outputs. Init, Check, and Uninstall operate on exact renderer paths, while committed repository files remain the complete host-native runtime.

 ## Boundaries

@@ -67,6 +69,7 @@ Workflow-surface architecture is owned by the installed-workflows route area.
 ## Engineering Decisions

 - Decision (2026-06-14): Architecture docs describe current repository realization and do not redefine product promises.
+- Decision (2026-07-10): Generated ownership is renderer-derived and exact-path lifecycle operations preserve committed files as the host-native runtime.

 ## Rationale

@@ -87,7 +90,3 @@ Update when module boundaries, generated-surface ownership, or command architect
 - ../../../../src/config/load.ts
 - ../../../../src/routing/areas.ts
 - ../../../../src/templates/generated-surfaces.ts
- `src/cli/handlers.ts`
- `src/config/load.ts`
- `src/routing/areas.ts`
- `src/templates/generated-surfaces.ts`
@@ -1,7 +1,7 @@
 ---
 status: active
 truth_kind: engineering-behavior
-last_reviewed: 2026-06-20
+last_reviewed: 2026-07-30
 ---

 # Check Diagnostics
@@ -16,11 +16,28 @@ 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.
+- It reports unmapped functional code under any Git-visible root in routing-coverage and ownership-clarity scorecards, and previews exact inactive generated surfaces without claiming unrelated files in host directories.
+- 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 +50,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 +90,15 @@ 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.
+- Decision (2026-07-10): Routing coverage includes functional code under any Git-visible root, while inactive generated-surface previews remain exact-path and renderer-owned.

 ## Rationale

@@ -71,13 +116,11 @@ 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
@@ -1,7 +1,7 @@
 ---
 status: active
 truth_kind: engineering-behavior
-last_reviewed: 2026-06-20
+last_reviewed: 2026-07-30
 ---

 # Init And Scaffold
@@ -25,10 +25,18 @@ Scaffold paths derive from `truthmark.workspace`:
 - The default scaffolded route area is `repository`.
 - Max route delegation depth is `1`.

-Fresh configs do not assume a host platform:
+`truthmark init` is the only setup command:

- `platforms` is omitted by default.
- Host-specific workflow surfaces are generated only after maintainers explicitly list Codex, OpenCode, Claude Code, GitHub Copilot, Antigravity, or Cursor.
+- In an interactive TTY, init renders the supported platform catalog as a numbered, comma-separated multi-select.
+- Selection is zero or more; `none` preserves host-neutral CLI-only initialization, and cancellation writes nothing.
+- Existing saved platforms are preselected, and an empty response keeps them.
+- Repeatable `--platform <id>` values replace the selected set for automation; `--clear-platforms` explicitly selects an empty set.
+- `--json` never prompts.
+- A first noninteractive run with neither saved config nor explicit platform values remains host-neutral.
+- A noninteractive rerun with no explicit values keeps the saved platform set.
+- Host detection never selects a platform.
+
+Init creates `.truthmark/config.yml` when absent. Existing valid version-2 configs remain valid; when platform ownership changes, init updates only the top-level `platforms` node while preserving other supported values and YAML comments. An empty selection omits `platforms`.

 Editable truth template filenames match `truth_kind` values directly:

@@ -44,10 +52,19 @@ 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` reconciles generated surfaces to the selected platform set. It removes a whole file only when its bytes prove renderer ownership, preserves authored content outside valid managed blocks, and reports unsafe or mixed-ownership paths for manual review.
+
+Configured platforms select exact instruction surfaces. Shared-contract hosts aggregate `AGENTS.md` ownership, Claude Code owns `CLAUDE.md`, and host-neutral configuration emits no generic instruction file. Lifecycle diagnostics expose planned removals, preserved diverged files, and preflight failures to human and JSON callers.

 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 +96,52 @@ Capability docs own:

 - Scaffolded paths derive from `truthmark.workspace`.
 - Template filenames match `truth_kind` values.
- Fresh configs do not assume any AI host platform.
+- Engineering behavior templates provide optional current-state scenario blocks for normal, fallback, or compatibility-critical behavior.
+- Setup and platform selection are owned by `truthmark init`.
+- Platform selection is zero or more and never assumes an AI host.
 - Global prose style guidance belongs in writer-facing workflow procedures, not every truth-doc template preamble.

+## Behavior Scenarios
+
+#### Scenario: Interactive init selects zero or more platforms
+
+- **GIVEN** `truthmark init` runs in an interactive TTY without explicit platform flags
+- **WHEN** the maintainer submits numbered choices, `none`, or the preselected defaults
+- **THEN** init persists that complete platform set and generates only the selected host surfaces
+- **AND** selecting none omits `platforms` and generates no host-specific surfaces
+
+#### Scenario: Noninteractive init remains deterministic
+
+- **GIVEN** init runs noninteractively or with `--json`
+- **WHEN** repeatable `--platform <id>` values or `--clear-platforms` are present
+- **THEN** those values replace the complete selected platform set without prompting
+- **AND** a first no-flag run remains host-neutral while a later no-flag rerun keeps saved platforms
+
+#### Scenario: Existing version-2 config preserves authored YAML
+
+- **GIVEN** a valid version-2 `.truthmark/config.yml` contains comments and supported non-platform values
+- **WHEN** init changes the selected platforms
+- **THEN** only top-level platform ownership changes
+- **AND** other supported values and comments are preserved
+
+#### 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 resolves platform choice from explicit flags, interactive selection, saved values, or the empty first-run default, in that order.
+- It prepares a version-2 config update, preflighting the config path and lifecycle mutations before writing scaffold and generated-surface files; lifecycle removals are applied last so a failed write does not delete existing generated surfaces, and invalid existing config still fails closed.
 - 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.
+- Before any scaffold or generated-surface write, it rejects aliased, non-regular, or hard-linked managed instruction destinations and preflights every planned lifecycle mutation.
+- It revalidates every planned mutation before applying the first removal, so a changed or unsafe later target prevents partial cleanup; earlier scaffold writes remain visible for retry if lifecycle application is blocked.
+- It removes only renderer-owned generated artifacts that are outside the selected surface set.
+- It preserves user bytes outside a removed managed block, including surrounding whitespace and line-ending convention.
+- It leaves unsafe or mixed-ownership paths for manual review.

 ## Contracts

@@ -99,23 +154,33 @@ Capability docs own:

 ## Engineering Decisions

- 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): New scaffold targets use separate product and engineering truth roots.
+- Decision (2026-06-14): Editable template filenames match `truth_kind` values directly.
 - 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.
+- Decision (2026-07-10): Configured platforms select exact instruction ownership, and deterministic lifecycle diagnostics expose reconciliation without transferring ownership of authored files.
+- Decision (2026-07-30): Truthmark 2.3 uses `truthmark init` for repository setup and platform selection.
+  - Interactive selection is zero-or-more, while repeatable `--platform` values provide deterministic automation and `--json` never prompts.
+  - Existing version-2 configs do not require migration; platform updates preserve other values and comments.

 ## 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

- 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.

 ## Maintenance Notes

@@ -124,6 +189,13 @@ Update when init writes new files, changes default paths, changes template filen
 ## Source References

 - ../../../../src/config/defaults.ts
+- ../../../../src/config/render.ts
+- ../../../../src/cli/platform-selection.ts
+- ../../../../src/cli/program.ts
+- ../../../../src/init/init.ts
 - ../../../../src/init/hierarchy.ts
 - ../../../../src/templates/init-files.ts
- ../../../../tests/init/init-instructions.test.ts
+- ../../../../tests/lifecycle/uninstall.test.ts
+- ../../../../tests/init/truth-doc-templates.test.ts
+- ../../../../tests/cli/platform-selection.test.ts
+- ../../../../tests/init/interactive-platform-selection.test.ts
@@ -1,7 +1,7 @@
 ---
 status: active
 truth_kind: engineering-contract
-last_reviewed: 2026-06-20
+last_reviewed: 2026-07-30
 ---

 # Config, Route, And Check Contracts
@@ -16,10 +16,21 @@ It covers config normalization, route `truth_documents` metadata, diagnostic cat

 ## Current Implementation Behavior

-Default config exposes optional `platforms`, `truthmark.workspace`, and `truthmark.generated.portal.enabled`.
+Version-2 config exposes optional `platforms`, `truthmark.workspace`, and `truthmark.generated.portal.enabled`.

 Default config does not expose route layout, template layout, or truth lane roots as knobs.

+`truthmark init` owns setup and platform persistence.
+
+Platform resolution follows this order:
+
+1. Repeatable explicit `--platform <id>` values replace the full selected set; `--clear-platforms` selects the empty set.
+2. An interactive TTY uses a numbered zero-or-more selector preselected from saved values.
+3. A noninteractive rerun with no explicit values keeps saved values.
+4. A first noninteractive run with no explicit values uses the empty host-neutral default.
+
+`--json` never prompts. Unsupported platform IDs are config errors, and platform detection never selects a host.
+
 When `platforms` is omitted, normalized config defaults to an empty platform list:

 - No host-specific workflow surfaces are generated by default.
@@ -45,9 +56,7 @@ Duplicate route entries for the same path, kind, and lane merge relationship met

 Conflicting duplicate kinds or lanes are reported as area-index errors.

-The public ContextPack command surface is retired.
-
-Agents use `truthmark workflow status --workflow <workflow> [--base <ref>] --json` for:
+Agents use `truthmark workflow status --workflow <workflow> [--base <ref>]` for a bounded human-readable advisory card and add `--json` when they need the schema-versioned contract for:

 - an advisory workflow card
 - write-boundary suggestions
@@ -61,15 +70,20 @@ Agents use `truthmark workflow status --workflow <workflow> [--base <ref>] --jso
 - next steps
 - compact affected-test guidance

+The human-readable card reports applicability and non-empty affected files, likely route owners, suggested truth docs, open questions, and next steps. Each list is capped at five entries with a remaining-count summary.
+
+WorkflowState composes diagnostics from config, RepoIndex, ImpactSet, and Check by exact-value deduplication so the same review or error signal appears once.
+
 Agents use `truthmark impact --base <ref> --json` for branch-diff routing.

-These replacement JSON outputs emit paths, metadata, diagnostics, and command arrays only.
+These JSON outputs emit paths, metadata, diagnostics, and command arrays only.

 They do not embed source-file or truth-doc body contents.

 ## Contract Surface

 - `.truthmark/config.yml`
+- `truthmark init [--platform <id> ...] [--clear-platforms] [--json]`
 - `docs/truthmark/routes/areas.md`
 - `docs/truthmark/routes/areas/**/*.md`
 - `CommandResult` JSON envelopes
@@ -84,7 +98,9 @@ They do not embed source-file or truth-doc body contents.

 ## Outputs

- Normalized config includes an empty `platforms` list when the field is omitted; host-specific surfaces require explicit platform entries.
+- Init creates a version-2 config when absent and preserves existing valid version-2 config compatibility.
+- When a selected set changes, only top-level platform ownership changes; other supported values and YAML comments are preserved.
+- Normalized config includes an empty `platforms` list when the field is omitted; host-specific surfaces require explicit platform selection.
 - Normalized config paths for fixed route, template, product truth, engineering truth, and Portal locations derived from `truthmark.workspace`
 - RouteMap data preserving lane and relationship metadata, plus RepoIndex data preserving derived doc type and lane metadata
 - WorkflowState data preserving workflow write boundaries and compact test guidance without file contents
@@ -94,19 +110,21 @@ They do not embed source-file or truth-doc body contents.
 ## Errors And Diagnostics

 - Unsupported config fields are validation diagnostics.
+- Unsupported `--platform` values are error diagnostics and cause no repository writes.
+- Invalid existing config fails closed and is not overwritten by init.
 - Conflicting duplicate route kinds or lanes are area-index errors.
 - Missing or stale truth-doc relationships are traceability diagnostics.
 - Unmapped functional-code changes are freshness or routing diagnostics depending on command context.

 ## Compatibility Rules

-The target model is lane-first and does not use `docs/truthmark/truth` as the canonical scaffold target.
+Canonical truth is lane-first under the product and engineering roots.

 ## Versioning And Migration

 - Config files use `version: 2`.
- Removed public command surfaces, such as standalone ContextPack, are hard-removed rather than preserved as aliases in this branch.
- Legacy canonical truth roots are migrated into product and engineering lane roots.
+- Truthmark package release `2.3.0` does not change the persisted config version.
+- Existing valid version-2 config remains accepted without migration.

 ## Product Truth Links

@@ -119,8 +137,14 @@ The target model is lane-first and does not use `docs/truthmark/truth` as the ca
 - Decision (2026-06-14): Route layout, template layout, default area `repository`, and max delegation depth `1` are product invariants derived from `truthmark.workspace`, not user config fields.
 - Decision (2026-06-15): Duplicate route relationship metadata is additive for matching path, kind, and lane entries; kind and lane conflicts remain hard validation errors.
 - Decision (2026-06-15): Route relationships are route-local metadata; checks validate relationship targets for existence and lane compatibility without requiring a reciprocal global graph edge.
- Decision (2026-06-15): ContextPack is folded into workflow status and impact; the standalone `truthmark context` command is hard-removed from the public CLI.
+- Decision (2026-06-15): Agent-facing repository intelligence is exposed through workflow status and impact.
 - Decision (2026-06-18): Omitted `platforms` normalize to an empty platform list; all host-specific generated surfaces, including Codex, are explicit opt-in config.
+- Decision (2026-07-10): Instruction destinations derive from configured platforms. The version-2 `instruction_targets` field remains parseable but is ignored with a review diagnostic and omitted from new configuration. `uninstall` requires exactly one of `--dry-run` or `--apply` and returns a deterministic `truthmark-lifecycle/v0` plan.
+- Decision (2026-07-26): Human workflow status reuses the existing advisory card with bounded lists, while JSON retains the full schema-versioned state.
+  - Exact duplicate diagnostics are collapsed at WorkflowState composition so optional helper output stays compact without hiding distinct signals.
+- Decision (2026-07-30): Truthmark 2.3 uses `truthmark init` as the repository setup command.
+  - Interactive selection accepts zero or more platforms; repeated explicit flags replace the set for automation, and JSON output is non-prompting.
+  - Package release 2.3.0 retains config schema version 2 and preserves existing config values and comments outside platform ownership.

 ## Rationale

@@ -129,7 +153,6 @@ The public contract exposes compact routing and workflow metadata instead of fil
 ## Non-Goals

 - This contract does not define language-semantic import graphs or symbol indexes.
- This contract does not preserve legacy ContextPack aliases.
 - This contract does not make route relationships a required reciprocal global graph.

 ## Maintenance Notes
@@ -140,7 +163,11 @@ Update when config fields, route metadata, diagnostics, route/index output schem

 - ../../../../src/config/schema.ts
 - ../../../../src/config/defaults.ts
+- ../../../../src/config/render.ts
 - ../../../../src/config/load.ts
+- ../../../../src/cli/platform-selection.ts
+- ../../../../src/cli/program.ts
+- ../../../../src/init/init.ts
 - ../../../../src/routing/areas.ts
 - ../../../../src/output/diagnostic.ts
 - ../../../../src/workflow-state/types.ts
@@ -1,7 +1,7 @@
 ---
 status: active
 truth_kind: engineering-contract
-last_reviewed: 2026-06-20
+last_reviewed: 2026-07-30
 ---

 # Generated Host Surfaces
@@ -16,27 +16,31 @@ It covers configured platform output paths, generated workflow files, managed in

 ## Current Implementation Behavior

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

- `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 check` reports missing, stale, or obsolete generated surfaces when render outputs and committed files differ.
-
-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.
+- `truthmark init` reconciles generated files against `renderGeneratedSurfaces(...)` and removes a whole file only when exact recognized bytes establish renderer ownership.
+- `truthmark check` reports missing or stale generated surfaces when render outputs and committed files differ.
+- Check, Init reconciliation, and Uninstall consume the same renderer-derived catalog and lifecycle inventory.
+- Destructive lifecycle application snapshots and revalidates containment, parent and final link status, regular-file and hard-link status, managed-block structure, and recognized whole-file bytes for every mutation before applying the first mutation.
+- Lifecycle inventory catalogs exact renderer paths plus bounded ownership patterns. Check previews inactive claims; Init and Uninstall reconcile only recognized whole files or valid managed blocks, preserve diverged or unsafe paths and unrelated siblings, and never recursively delete generated directories.
+- Managed-block removal preserves all bytes outside the single valid marker range; a block-only file is removed.
+- When `platforms` is omitted, fresh config does not assume a host platform.
+- `platforms` is the complete platform-ownership declaration. An explicit platform refreshes or retains renderer-owned instruction surfaces; an empty platform set reconciles generated surfaces to a host-neutral repository.
+- Host skill packages carry canonical workflow entrypoints plus support files for full procedures, report templates, and subagent/lease guidance when the workflow uses subagents.
+- GitHub Copilot prompt files are lightweight workflow adapters that point to the current host entrypoint.
+- Cursor Agent Skills are generated as native project skill packages under `.cursor/skills/truthmark-*` with package-local support files.

 ## 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>.

 ## Inputs

@@ -46,15 +50,14 @@ 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
- No generated Truth Preview skill package, prompt, or command
+- Host-native workflow skill packages, compact prompt adapters, and flat Antigravity rule surfaces
 - Procedure, report-template, and subagent/lease support files only when a workflow needs them
 - Managed instruction blocks with non-versioned refresh guidance

 ## 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 check` reports missing or stale generated surfaces.
+- `truthmark init` reconciles renderer-owned artifacts to the selected platform set and leaves unsafe or mixed-ownership paths for manual review.
 - Generated-surface freshness uses rendered-content comparison rather than package-version markers.

 ## Compatibility Rules
@@ -65,7 +68,6 @@ 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.
 - Generated surfaces use non-versioned refresh wording; package versions are not runtime authority.

 ## Product Truth Links
@@ -75,22 +77,36 @@ 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.
+- Decision (2026-07-10): Exact-path lifecycle ownership and fail-closed revalidation are shared by Check, Init, and Uninstall so reconciliation never requires recursive directory deletion.

 ## 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

 - Generated surfaces are not a live daemon or orchestration layer.
- Preview is not a generated host surface.
- Optional validators do not require generated helper manifest files.

 ## Maintenance Notes

@@ -101,6 +117,3 @@ Update when platform paths, supported hosts, optional validation commands, or ma
 - ../../../../src/templates/generated-surfaces.ts
 - ../../../../src/templates/workflow-surfaces.ts
 - ../../../../src/templates/agents-block.ts
- `src/templates/generated-surfaces.ts`
- `src/templates/workflow-surfaces.ts`
- `src/templates/agents-block.ts`
@@ -1,7 +1,7 @@
 ---
 status: active
 truth_kind: engineering-operations
-last_reviewed: 2026-06-20
+last_reviewed: 2026-07-26
 ---

 # Release Automation
@@ -16,11 +16,26 @@ 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.
+
+The static introduction site replaces the positioned hero illustration with a bounded grid at narrow desktop and tablet widths, then stacks the same content at phone widths. The header brand mark uses an inline SVG checkmark that remains contained within its rounded glyph.
+
+The introduction site groups its overview, workflow guide, truth model, and adoption content into hash-addressable tab pages. The static page keeps each view in the committed HTML, uses client-side navigation as progressive enhancement, and keeps the selected tab visible inside the horizontally scrollable phone navigation.
+
+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 +44,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 +58,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 +73,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 +90,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-07-30
 ---

 # 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 from broad bootstrap routing to bounded behavior 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.
+- This file is a directory guardrail rather than 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 directs real behavior to bounded owners while preserving repository-level navigation.

 ## 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 repository-overview guardrails change.

 ## 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-07-30
 ---

 # Repository Intelligence
@@ -16,17 +16,54 @@ 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.
+- Check and RepoIndex share NUL-delimited `git ls-files` discovery for tracked and visible untracked regular files. Discovery applies configured and default ignores, excludes deleted or escaping paths, normalizes and sorts results, and uses a deterministic full-tree fallback when Git enumeration is unavailable; the fallback cannot reproduce every Git ignore rule.
+- 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.
+- Human workflow status renders applicability plus non-empty advisory-card and next-step lists, capped at five entries per list; JSON retains the complete WorkflowState contract.
+- WorkflowState collapses exact duplicate diagnostics collected from config, RepoIndex, ImpactSet, and Check while preserving distinct diagnostics.
+- 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.
+- 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 +71,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 +114,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): 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, and generated workflows 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`.
 - 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.
+- Decision (2026-07-10): Check and RepoIndex share one Git-visible file-discovery path so routing, coverage, and repository indexing operate on the same normalized file set.
+- Decision (2026-07-26): Human workflow status renders the existing advisory card as bounded context rather than requiring callers to load the full JSON contract.
+  - WorkflowState removes exact duplicate diagnostics at its composition boundary.

 ## Rationale

@@ -76,21 +144,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-07-30
 ---

 # Installed Workflow Runtime
@@ -30,32 +30,26 @@ Generated host skill directories are native skill packages for write-capable and
 - Subagent and lease guidance is kept only when the workflow uses subagents.
 - Hosts that package skill-directory resources do not depend on arbitrary cross-repository file reads.

-Generated helper manifests and helper policy support files are not emitted:
+Optional validation commands stay in workflow metadata, and report validation accepts manual fallback evidence.

- Optional validation commands stay in workflow metadata.
- Report validation accepts manual fallback evidence.
-
-Truthmark no longer emits Truth Preview as a generated host surface:
-
- No configured host receives a Preview skill package, prompt, or command.
- Preview-like route/workflow selection remains internal advisory behavior that agents can perform with direct checkout inspection or optional workflow-status/impact helpers.
-
-Truthmark does not emit a separate `.truthmark/agent/` workflow copy:
-
- Host surfaces are the runtime surfaces agents actually load.
- Duplicating workflow packages under `.truthmark/agent/` would add repository docs with no active host consumer.
+Host-native packages are the runtime workflow surfaces that agents load.

 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-*`:
+
+- `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,15 +80,17 @@ 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:

- It creates skeletal starter truth docs only when missing ownership would block future workflows.
+- It creates skeletal starter truth docs only when missing ownership would block later workflow execution.
 - Starter docs are ownership anchors, not substantive behavior writeups.
 - Template-section authoring, doc-shape repair, and architecture-doc prose guidance stay out of the Structure procedure.

@@ -131,12 +127,37 @@ 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.
 - `impact` exposes branch-diff routing data.
 - Neither helper emits source-file or truth-doc body contents.

+- The repository includes a maintainer-only workflow evaluation framework under `workflow-eval-framwork/`; it is not part of the published npm package and normal Truthmark users do not need it:
+
+- It tests agent behavior for installed workflow skills and prompts using cataloged scenarios, rubrics, realistic multi-file development fixtures, fake agents, deterministic grading, required manual LLM judge commands, and human review.
+- Scenarios include source files, tests, route ownership, product truth, engineering behavior truth, API contract truth, and operations truth so workflow agents must choose the correct lane and bounded owner instead of solving a one-file toy case.
+- A catalog run executes registered scenarios across Truth Sync, Truth Document, Truth Realize, Truth Check, and Truth Structure, then persists only `final-report.md` and `audit.json` for the full suite.
+- Per-scenario command output, patches, reports, and judge scratch files are temporary in catalog mode and are discarded after aggregation.
+- Scenario setup patches are applied after the fixture baseline commit so agents evaluate real pre-existing diffs.
+- Deterministic expectations are prompt-visible or semantically forced by the workflow; exact command requirements and required file targets are not hidden arbitrary grader traps.
+- Catalog runs without judge results are `not_evaluable`; deterministic-only output is only a harness smoke test.
+- Judge failures produce failed runs; `not_evaluable` is reserved for missing or malformed judge output.
+- Explicit `--agent-model` and `--judge-model` labels are preserved in `audit.json`, `final-report.md`, and wrapper environment variables for reproducible model comparisons.
+- The runner exports `TRUTHMARK_EVAL_AGENT_USAGE` and `TRUTHMARK_EVAL_JUDGE_USAGE` sidecar paths so wrappers can report provider token usage without coupling the runner to one provider event format.
+- Scenario results, suite `audit.json`, and `final-report.md` record measured agent tokens, judge tokens, and suite totals for prompt/workflow-surface usage comparisons.
+- `--require-usage` makes missing or invalid usage sidecars non-passing for real model-comparison runs.
+- The framework does not enforce token budgets or estimate dollar cost; raw token counts are the durable telemetry signal.
+- Focused single-scenario runs require an explicit debug flag and are not sufficient for workflow-quality claims across the product surface.
+- Manual run artifacts stay ignored by default so expensive or stale eval history is not committed accidentally.
+- The framework is not part of normal `truthmark check`, `truthmark init`, generated host surfaces, package install, downstream workflow execution, or default CI agent execution.
+
 Truth Sync workflow status separates impacted primary truth docs from candidate stale truth docs and route files.

 This keeps stale repository-truth correction available without making every indexed doc look like the starting scope.
@@ -185,17 +206,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,12 +252,15 @@ 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
 - ../../../../src/templates/workflow-surfaces.ts
 - ../../../../src/templates/generated-surfaces.ts
 - ../../../../src/checks/generated-surfaces.ts
+- ../../../../workflow-eval-framwork/catalog.yaml
+- ../../../../scripts/workflow-eval-framwork/run-agent-scenario.mjs
 - `src/agents/workflow-manifest.ts`
 - `src/templates/workflow-surfaces.ts`
 - `src/templates/generated-surfaces.ts`
@@ -1,50 +1,109 @@
 ---
 status: active
 truth_kind: product-capability
-last_reviewed: 2026-06-20
+last_reviewed: 2026-07-30
 ---

 # 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.

 ## 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`.
+- Configured platforms select exact host instruction surfaces. Shared-contract hosts aggregate ownership of `AGENTS.md`, Claude Code owns `CLAUDE.md`, and disabling a host makes only its recognized renderer-owned outputs eligible for reconciliation.
+- 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-*` for description-based selection and package-local support resources.
+- Validation helpers remain available through explicit 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.
+- 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.
+- Each configured host skill directory receives the workflow support files needed for native skill resource packaging.
+- 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 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.
+- Decision (2026-07-10): Platform configuration is the ownership authority for exact host instruction surfaces; shared files aggregate host claims, and reconciliation applies only to recognized renderer-owned output.

 ## Engineering Realization Links

@@ -1,7 +1,7 @@
 ---
 status: active
 truth_kind: product-capability
-last_reviewed: 2026-06-14
+last_reviewed: 2026-07-30
 ---

 # Lane-Separated Truth
@@ -16,17 +16,22 @@ 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` as the product truth template.
+- Routing coverage considers Git-visible functional code under any repository root. Tests, ignored paths, documentation, assets, and generated surfaces do not create unmapped-code findings.

 ## Acceptance Criteria

- New scaffold defaults do not target `docs/truthmark/truth`.
- Product truth defaults, path inference, and templates use `product-capability` only.
- `product-boundary` is rejected as downstream truth kind metadata instead of being listed as supported.
+- New scaffolds use separate product and engineering truth roots under the configured workspace.
+- Product truth defaults, path inference, and templates use `product-capability`.
+- Product capability scope and non-goals carry product boundary guidance.
 - RouteMap and RepoIndex preserve lane and relationship metadata.
 - Check diagnostics report lane shape, lane drift, and route-local traceability.
 - Missing product links for user-visible engineering docs remain review diagnostics.
@@ -36,7 +41,9 @@ 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.
+- Decision (2026-07-10): Repository-wide coverage follows Git-visible functional code across arbitrary roots while excluding non-functional and ignored surfaces.

 ## Engineering Realization Links

@@ -1,7 +1,7 @@
 ---
 status: active
 doc_type: routing
-last_reviewed: 2026-05-16
+last_reviewed: 2026-07-26
 ---

 # Truthmark Areas
@@ -17,9 +17,9 @@ Area files:
 Code surface:

 - src/cli/\*\*
- src/config/command.ts
 - src/config/defaults.ts
 - src/config/load.ts
+- src/config/render.ts
 - src/config/schema.ts
 - src/output/\*\*

@@ -85,8 +85,11 @@ Code surface:
 - src/templates/workflow-surfaces.ts
 - src/templates/generated-surfaces.ts
 - src/checks/generated-surfaces.ts
+- src/managed-block.ts
 - src/truth/\*\*
 - src/version.ts
+- workflow-eval-framwork/\*\*
+- scripts/workflow-eval-framwork/\*\*
 - tests/evals/\*\*
 - tests/templates/\*\*

@@ -105,12 +108,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

@@ -22,9 +22,9 @@ truth_documents:
 Code surface:

 - src/cli/\*\*
- src/config/command.ts
 - src/config/defaults.ts
 - src/config/load.ts
+- src/config/render.ts
 - src/config/schema.ts
 - src/output/\*\*

@@ -1,7 +1,7 @@
 ---
 status: active
 doc_type: routing
-last_reviewed: 2026-05-16
+last_reviewed: 2026-07-26
 ---

 # Installed Workflows Areas
@@ -40,8 +40,11 @@ Code surface:
 - src/templates/workflow-surfaces.ts
 - src/templates/generated-surfaces.ts
 - src/checks/generated-surfaces.ts
+- src/managed-block.ts
 - src/truth/\*\*
 - src/version.ts
+- workflow-eval-framwork/\*\*
+- scripts/workflow-eval-framwork/\*\*
 - tests/evals/\*\*
 - tests/templates/\*\*

@@ -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

 <!--
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Merlin's Cat GitHub MerlinH	e3edcc8afa	feat: v2.3.0 add interactive platform selection to init (#38 ) * feat: add interactive platform selection to init * chore: remove completed OpenSpec artifacts * chore: remove implemented design note * fix: protect init lifecycle from unsafe config paths * fix: support clearing init platforms from CLI * docs: retire config command from repository rules * docs: align init lifecycle and clear-platform contracts * docs: keep repository guidance current-state focused * docs: limit cleanup to repository-native documents * docs: preserve historical version notes --------- Co-authored-by: MerlinH <merlinh221@gmail.com>	2026-07-31 18:54:10 +10:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	d88e4eb16d	chore(deps): bump the npm_and_yarn group across 1 directory with 2 updates (#35 ) Bumps the npm_and_yarn group with 2 updates in the / directory: [fast-uri](https://github.com/fastify/fast-uri) and [js-yaml](https://github.com/nodeca/js-yaml). Updates `fast-uri` from 3.1.2 to 3.1.4 - [Release notes](https://github.com/fastify/fast-uri/releases) - [Commits](https://github.com/fastify/fast-uri/compare/v3.1.2...v3.1.4) Updates `js-yaml` from 4.2.0 to 4.3.0 - [Changelog](https://github.com/nodeca/js-yaml/blob/master/CHANGELOG.md) - [Commits](https://github.com/nodeca/js-yaml/compare/4.2.0...4.3.0) --- updated-dependencies: - dependency-name: fast-uri dependency-version: 3.1.4 dependency-type: indirect dependency-group: npm_and_yarn - dependency-name: js-yaml dependency-version: 4.3.0 dependency-type: indirect dependency-group: npm_and_yarn ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2026-07-30 23:03:23 +10:00
MerlinH	c067e3e99f	feat(site): add responsive tabbed product guide	2026-07-28 09:27:55 +10:00
MerlinH	bfee763ab2	feat: compact workflow status context	2026-07-27 00:19:37 +10:00
dependabot[bot]andMerlinH	72e6117cf4	chore(deps-dev): bump brace-expansion Bumps the npm_and_yarn group with 1 update in the / directory: [brace-expansion](https://github.com/juliangruber/brace-expansion). Updates `brace-expansion` from 1.1.15 to 1.1.16 - [Release notes](https://github.com/juliangruber/brace-expansion/releases) - [Commits](https://github.com/juliangruber/brace-expansion/compare/v1.1.15...v1.1.16) --- updated-dependencies: - dependency-name: brace-expansion dependency-version: 1.1.16 dependency-type: indirect dependency-group: npm_and_yarn ... Signed-off-by: dependabot[bot] <support@github.com>	2026-07-25 23:06:59 +10:00
Merlin's Cat GitHub MerlinH	c92b46ad65	feat: harden init routing and generated lifecycle (#33 ) * feat: harden init routing and generated lifecycle * test: align restored coverage with platform routing * docs: translate localized uninstall guidance * test: complete init routing and lifecycle coverage * docs: record completed OpenSpec tasks * chore: archive implemented init lifecycle OpenSpec change * chore: remove OpenSpec configuration * docs: clarify platform omission reconciliation --------- Co-authored-by: MerlinH <merlinh221@gmail.com>	2026-07-12 20:48:09 +10:00
Merlin's Cat GitHubCopilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>MerlinHCopilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>	9fa9ac25a4	feat: add workflow eval framework (#32 ) * feat: add workflow eval framework Add workflow evaluation scenarios, rubrics, schemas, and runner scripts for installed Truthmark workflows. Move research notes under docs/research and migrate tests from Vitest to node:test. * Potential fix for pull request finding 'CodeQL / Replacement of a substring with itself' Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com> --------- Co-authored-by: MerlinH <merlinh221@gmail.com> Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>	2026-06-30 20:57:55 +10:00
MerlinH	98061f7456	site: improve mobile layout	2026-06-27 01:47:11 +10:00
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