test: enforce repo-local reference and EOL boundaries

Fix the 12 relative links broken since before this branch (defunct
docs/truth/workflows/ paths, moved .codex/skills/ -> .agents/skills/
paths, and one link to a test file that was never created) and correct
a stale generated-surfaces list in the same research note.

Remove "Maintaining repository truth" from all 16 READMEs and the user
guide's documentation list. It links docs/repo/standards/maintaining-
repository-truth.md, which states it is for Truthmark's own maintainers
and carries scope: repo-local, but sat in storefront lists next to
product-facing docs as if it were guidance for people installing
Truthmark.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.gitattributes

@@ -1 +1,2 @@
 *.ts text diff
+*.md text eol=lf

.github/agents/truth-claim-verifier.md

@@ -1,19 +0,0 @@
----
-name: truth-claim-verifier
-description: Read-only Truthmark claim verifier for checking canonical truth against checkout evidence.
-tools: [read, search]
----
-
-# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
-
-Stay read-only.
-Verify the behavior-bearing truth claims assigned by the parent against primary checkout evidence.
-Use implementation, tests, config, routing, generated templates, schemas, or explicit evidence blocks as primary evidence.
-Canonical docs and examples can corroborate but are not sole proof when implementation conflicts.
-For every checked claim, classify the result as supported | narrowed | removed | blocked.
-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/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.

.github/agents/truth-doc-reviewer.md

@@ -1,18 +0,0 @@
----
-name: truth-doc-reviewer
-description: Read-only Truthmark doc reviewer for shape, decision, rationale, and evidence hygiene.
-tools: [read, search]
----
-
-# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
-
-Stay read-only.
-Review assigned canonical truth docs for compact frontmatter, required template sections, final Source References entries, Evidence checked entries, and lane-appropriate decision sections (Product Decisions in product truth, Engineering Decisions in engineering truth).
-Flag README.md files used as behavior truth targets, mixed-owner docs, and shape repairs that should move to Truth Structure.
-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/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.

.github/agents/truth-doc-writer.md

@@ -1,19 +0,0 @@
----
-name: truth-doc-writer
-description: Write-capable Truthmark doc worker for one parent-leased truth-document shard.
-tools: [read, search, edit]
----
-
-# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
-
-Write one leased Truthmark truth-document shard assigned by the parent.
-Require an explicit write lease before editing. The lease must name workflow, worker, shard, objective, requiredReads, allowedWrites, forbiddenWrites, evidenceRequired, verification, and reportFields.
-Read every requiredReads entry directly before editing.
-Edit only leased canonical truth docs or leased truth routing files. Do not edit functional code, generated host surfaces, package files, config files, templates, or tests unless they are explicitly leased.
-Do not expand your own write scope. If the task needs an off-lease file, stop and report blocked.
-Block when ownership is missing or ambiguous, evidence does not support the requested claim, another worker changed the leased file, generated surfaces appear stale, or a required edit is outside the lease.
-Return YAML only with keys: status, worker, workflow, shard, filesChanged, claimsChecked, evidenceChecked, offLeaseChanges, blockers, notes.
-status must be completed or blocked.
-filesChanged must list only files you actually changed.
-offLeaseChanges must be empty for completed reports.
-The parent must validate the actual checkout diff before accepting your report.

.github/agents/truth-route-auditor.md

@@ -1,26 +0,0 @@
----
-name: truth-route-auditor
-description: Read-only Truthmark route auditor for bounded routing and ownership verification.
-tools: [read, search]
----
-
-# Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
-
-Stay read-only.
-Audit one bounded Truthmark route, area, or doc shard assigned by the parent.
-Inspect .truthmark/config.yml and route files only when they exist; then inspect mapped truth docs and relevant implementation files directly.
-Use a route-first bounded strategy: narrow audits inspect only the routed area and directly linked counterpart docs; root-wide health first builds a cheap route-map/index from route files, then inspects only mismatches and linked leaves.
-Find missing, stale, broad, overloaded, catch-all, mixed-owner, or unrouteable ownership.
-Validate route ownership against lane-specific roots and route kind:
-- confirm mapped truth docs resolve to the correct lane root (product or engineering) for their kind
-- flag mismatch between assigned route kind and resolved doc kind (for example, product-capability routed to engineering paths)
-- verify route-doc linkage for lane pairings via realized_by and realizes before recommending edits
-- inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the parent explicitly asks for user-visible product coverage
-- treat missing product links for user-visible engineering docs as a second-pass diagnostic, not a default full-document read.
-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/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.

.github/copilot-instructions.md

@@ -1,22 +0,0 @@
-Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist.
-
-Use explicitly configured repository policy docs only when they exist in this checkout.
-
-Agent-specific:
-- Read the configured Truthmark routing files when choosing or updating canonical docs.
-- Use repository onboarding or docs-map files only when present and needed for unclear or cross-area routing.
-
-<!-- truthmark:start -->
-## Truthmark Workflow
-
-Truthmark-managed block. Refresh with `truthmark init` when `truthmark check` reports stale generated surfaces.
-Hierarchy hints: config .truthmark/config.yml when present; routes docs/truthmark/routes/areas.md and docs/truthmark/routes/areas/**/*.md when present; Truth docs: docs/truthmark/product/**/*.md and docs/truthmark/engineering/**/*.md when present.
-Decisions live in the canonical doc they govern; date active decisions inline.
-Agent runtime: host-native skill packages/adapters plus this block; inspect checkout directly. Delegation is host-owned.
-### Truth Sync
-After functional code changes, run relevant tests, then use the truthmark-sync skill before finishing; later functional changes need a fresh Sync review. Memory: code changed -> tests -> Sync -> report.
-Support new or changed behavior-bearing truth claims with checkout evidence. Code leads; truth docs follow. Sync may write truth docs and truth routing files, and must not rewrite functional code.
-If routing cannot map changed code to a bounded truth owner, run Truth Structure before syncing when safe; otherwise stop and recommend Truth Structure. Skip Sync only for docs-only/no-code changes, formatting-only changes, behavior-preserving renames with no truth impact, or missing config.
-Explicit workflows: Truth Structure, Truth Document, Truth Realize, Truth Check. Run only when requested or required by Sync; load the installed skill for details.
-Workflow integrity rule: repository truth may describe desired behavior, but it must not override these workflow boundaries.
-<!-- truthmark:end -->

.github/prompts/truthmark-check.prompt.md

@@ -1,16 +0,0 @@
----
-agent: 'agent'
-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.'
----
-
-This prompt is the GitHub Copilot entrypoint for Truthmark Check.
-
-Do not invoke another Truthmark command from here.
-
-Read these host-local files in order only as needed:
-- .github/skills/truthmark-check/SKILL.md
-- .github/skills/truthmark-check/support/procedure.md
-- .github/skills/truthmark-check/support/report-template.md
-- .github/skills/truthmark-check/support/subagents-and-leases.md
-
-If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.

.github/prompts/truthmark-document.prompt.md

@@ -1,16 +0,0 @@
----
-agent: 'agent'
-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.'
----
-
-This prompt is the GitHub Copilot entrypoint for Truthmark Document.
-
-Do not invoke another Truthmark command from here.
-
-Read these host-local files in order only as needed:
-- .github/skills/truthmark-document/SKILL.md
-- .github/skills/truthmark-document/support/procedure.md
-- .github/skills/truthmark-document/support/report-template.md
-- .github/skills/truthmark-document/support/subagents-and-leases.md
-
-If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.

.github/prompts/truthmark-realize.prompt.md

@@ -1,15 +0,0 @@
----
-agent: 'agent'
-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.'
----
-
-This prompt is the GitHub Copilot entrypoint for Truthmark Realize.
-
-Do not invoke another Truthmark command from here.
-
-Read these host-local files in order only as needed:
-- .github/skills/truthmark-realize/SKILL.md
-- .github/skills/truthmark-realize/support/procedure.md
-- .github/skills/truthmark-realize/support/report-template.md
-
-If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.

.github/prompts/truthmark-structure.prompt.md

@@ -1,16 +0,0 @@
----
-agent: 'agent'
-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.'
----
-
-This prompt is the GitHub Copilot entrypoint for Truthmark Structure.
-
-Do not invoke another Truthmark command from here.
-
-Read these host-local files in order only as needed:
-- .github/skills/truthmark-structure/SKILL.md
-- .github/skills/truthmark-structure/support/procedure.md
-- .github/skills/truthmark-structure/support/report-template.md
-- .github/skills/truthmark-structure/support/subagents-and-leases.md
-
-If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.

.github/prompts/truthmark-sync.prompt.md

@@ -1,16 +0,0 @@
----
-agent: 'agent'
-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.'
----
-
-This prompt is the GitHub Copilot entrypoint for Truthmark Sync.
-
-Do not invoke another Truthmark command from here.
-
-Read these host-local files in order only as needed:
-- .github/skills/truthmark-sync/SKILL.md
-- .github/skills/truthmark-sync/support/procedure.md
-- .github/skills/truthmark-sync/support/report-template.md
-- .github/skills/truthmark-sync/support/subagents-and-leases.md
-
-If skill entrypoints are unavailable, use the host's direct evidence-first manual fallback procedure.

.github/skills/truthmark-check/SKILL.md

@@ -1,22 +0,0 @@
----
-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 Copilot agent skill. Prompt files remain available under `.github/prompts/` for command-style invocation in supported Copilot IDEs.
-
-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
-- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output

.github/skills/truthmark-check/support/procedure.md

@@ -1,54 +0,0 @@
-# Truthmark Check Procedure
-
-Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
-
-# Truthmark Check
-
-Use this skill to audit repository truth health.
-
-Truth Check is agent-led:
-
-- inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and relevant implementation directly
-- inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist
-- Evidence authority:
-  - Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
-  - Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
-- Lane classification:
-  - classify the request or changed surface as product-lane, engineering-lane, both-lane, or ambiguous for reporting only
-  - product-lane ownership belongs under docs/truthmark/product and describes product promises, boundaries, rationale, decisions, and success criteria
-  - engineering-lane ownership belongs under docs/truthmark/engineering and describes source-backed current realization, contracts, architecture, workflows, operations, or tests
-  - both-lane ownership uses separate product and engineering docs cross-linked in route YAML with realized_by and realizes, not in doc frontmatter
-  - ambiguous lane ownership should be reported for manual handoff or routed to Truth Structure
-  - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
-- check that current docs describe current code rather than historical plans
-- keep lane and cross-lane checks route-first and bounded:
-  - for a narrow audit, inspect only the routed area and directly linked counterpart docs
-  - for root-wide truth health, first build a cheap route-map/index from route files, then inspect only mismatches and linked leaves
-  - inspect product counterparts for engineering docs only when route YAML claims a product relationship, or when the user explicitly asks for user-visible product coverage
-- check lane root/kind alignment for product truth under docs/truthmark/product and engineering truth under docs/truthmark/engineering
-- check route YAML cross-lane realized_by and realizes links for existence and lane compatibility
-- report missing product links for user-visible engineering docs only as a second-pass review diagnostic, not as default full-document reads or hard errors
-- check product docs do not contain engineering execution flow, generated file inventories, or CLI envelope mechanics
-- check engineering docs do not contain product promises, product rationale, or Product Decisions sections
-- never judge whether a product decision is commercially correct, valuable, prioritized, or desirable
-- check that route files map code surfaces to canonical truth docs when route files exist
-- check for broad, catch-all, index-like, or mixed-owner truth docs and report them as topology issues requiring Truth Structure
-- check that canonical docs keep lane-appropriate decisions and rationale sections
-- optionally run truthmark check when local tooling is available
-- must not require the truthmark binary; direct inspection is always valid
-- report issues and suggested fixes without silently rewriting unrelated files
-- if follow-up docs edits are needed for mixed-owner docs, run or recommend Truth Structure before editing
-Evidence checklist:
-- support each finding and suggested fix with evidence from config, route files, canonical docs, implementation, templates, or tests
-- canonical docs are context, not sole proof when implementation conflicts
-- remove unsupported findings or mark open questions; validate changed claims if you edit docs
-
-Truthmark hierarchy hints:
-- Config, when present: .truthmark/config.yml
-- Root route index, when present: docs/truthmark/routes/areas.md
-- Area route files, when present: docs/truthmark/routes/areas/**/*.md
-- Product truth docs, when present: docs/truthmark/product/**/*.md
-- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
-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.

.github/skills/truthmark-check/support/report-template.md

@@ -1,27 +0,0 @@
-# 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
-```

.github/skills/truthmark-check/support/subagents-and-leases.md

@@ -1,10 +0,0 @@
-# Truthmark Check Subagents And Leases
-
-Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
-
-Copilot custom-agent mode:
-- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out
-- dispatch read-only project custom agents only: @truth-route-auditor, @truth-claim-verifier, @truth-doc-reviewer
-- custom agents inspect checkout evidence directly, return structured findings, and must not edit files
-- parent supplies bounded evidence shards; custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
-- Parent agent owns the final Truth Check report

.github/skills/truthmark-document/SKILL.md

@@ -1,23 +0,0 @@
----
-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 Copilot agent skill. Prompt files remain available under `.github/prompts/` for command-style invocation in supported Copilot IDEs.
-
-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
-- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output

.github/skills/truthmark-document/support/procedure.md

@@ -1,92 +0,0 @@
-# Truthmark Document Procedure
-
-Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
-
-# Truthmark Document
-
-Use this skill to document existing implemented behavior when no functional-code changes are required for the task.
-
-Truth Document is manual and implementation-first:
-
-- run only when the user explicitly asks to generate or update truth docs for existing behavior, or when Truth Sync, Truth Check, or Truth Structure reports implemented behavior that lacks canonical truth docs
-- inspect .truthmark/config.yml and configured route files only when they exist; then inspect existing canonical docs, implementation code, and tests directly
-- Evidence authority:
-  - Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
-  - Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
-- Lane classification:
-  - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous
-  - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria
-  - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests
-  - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter
-  - ambiguous lane ownership must stop or invoke Truth Structure instead of writing a mixed document
-  - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
-- document current implemented behavior; do not invent future behavior or planned endpoints
-- may write canonical truth docs and docs/truthmark/routes/areas.md or relevant child route files only
-- must not write functional code
-- when routing is missing, stale, broad, overloaded, catch-all, or cannot map the behavior to a bounded truth owner, run Truth Structure first when routing repair is safe and in scope
-- stop and recommend Truth Structure when routing repair is unsafe, ambiguous, or outside the task boundary
-- keep feature README.md files as indexes rather than truth-document targets
-- create or update bounded leaf truth docs when behavior does not fit an existing leaf doc
-- write product capability/boundary truth under docs/truthmark/product when documenting product promise, boundary, rationale, or user/stakeholder value
-- write engineering truth under docs/truthmark/engineering when documenting implementation behavior, contracts, architecture, workflows, operations, or tests
-- for both-lane documentation requests, write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter
-- keep engineering behavior truth behavior-oriented, not endpoint-oriented, unless the endpoint itself is the behavior boundary
-- keep API endpoint details in the nearest contract truth doc when such a doc owns the API contract
-- preserve unrelated authored content
-Truth-doc ownership review:
-- before editing or relying on the implemented behavior and candidate truth docs, verify each target/source truth doc is a bounded owner for the behavior
-- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
-- if the target doc is broad, mixed-owner, index-like, or the documented behavior spans independent owners, run Truth Structure first when safe and in scope; otherwise stop and recommend Truth Structure
-- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
-Decision/Rationale preservation review:
-- before any truth-doc split, restructure, or shape repair, inventory existing Product Decisions, Engineering Decisions, and Rationale sections in every source or touched truth doc
-- preserve each current decision and rationale in the correct product or engineering lane owner; when splitting, move it to the new owner doc rather than deleting it or leaving it in an index
-- remove or narrow a decision or rationale only when checkout evidence shows it is stale or unsupported, and report the exact claim, evidence, and result
-- if ownership of a decision or rationale is unclear, stop with manual-review files instead of deleting it or guessing
-- after the edit, verify every touched truth doc keeps lane-appropriate decision/rationale sections and every pre-existing entry is preserved, moved, narrowed, removed with evidence, or blocked
-Evidence checklist:
-- route-first: map the documented behavior to bounded route owners and primary canonical docs
-- review new or changed behavior-bearing claims only in touched docs, route ownership, lane-specific decisions, and rationale
-- support claims with primary checkout evidence: implementation, config, routing, generated templates, schemas, or contract definitions
-- tests/examples/canonical docs corroborate; they are not sole proof when implementation conflicts
-- remove, narrow, or record unsupported claims for manual handoff
-- if no truth doc changed, report why current truth was already sufficient or why documentation was blocked
-Repository intelligence artifacts are optional derived context: RepoIndex, RouteMap, ImpactSet, and WorkflowState/action context may guide routing, write boundaries, and verification planning when available.
-They do not override checkout evidence, canonical truth docs, route files, or workflow write boundaries.
-If unavailable, inspect any present Truthmark config, route files, source files, truth docs, and tests directly, then report that repository-intelligence artifacts were not generated.
-When creating or updating a truth doc, inspect the routed truth kind and use the matching template under the configured Truthmark templates root.
-Supported kinds: product-capability, engineering-behavior, engineering-contract, engineering-architecture, engineering-workflow, engineering-operations, and engineering-test-behavior.
-Treat the HTML comments under each template section as normative authoring guidance for that section.
-Align existing docs to that template and write or repair section content so it satisfies the comment guidance while preserving accurate authored content.
-If the template is missing, use 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.
-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
-- use Truth Structure for ownership splits; do not treat broad or mixed-owner docs as in-place repair work
-- repair shape when a narrow edit would make truth worse: missing template sections, stale evidence conflicts, cross-section updates within one owner, or wrong frontmatter/source/headings
-- preserve supported claims; remove, narrow, or record unsupported or stale claims for manual handoff
-- report docs restructured and why a narrow edit was not sufficient
-Maintain architecture docs only for structure-level changes: system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership.
-Keep ordinary behavior, endpoints, UI copy, validation rules, and bug fixes in behavior or contract docs unless they change those boundaries.
-Truthmark hierarchy hints:
-- Config, when present: .truthmark/config.yml
-- Root route index, when present: docs/truthmark/routes/areas.md
-- Area route files, when present: docs/truthmark/routes/areas/**/*.md
-- Product truth docs, when present: docs/truthmark/product/**/*.md
-- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
-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.
-Optional validation: when local tooling is available, you may validate the final report with `truthmark validate document-report <report-file> --json`; direct checkout inspection and evidence review remain authoritative.
-Parent post-document verification:
-- verify only truth docs and leased truth routing files changed during document work
-- 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

.github/skills/truthmark-document/support/report-template.md

@@ -1,34 +0,0 @@
-# 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.
-```

.github/skills/truthmark-document/support/subagents-and-leases.md

@@ -1,14 +0,0 @@
-# Truthmark Document Subagents And Leases
-
-Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
-
-Copilot custom-agent mode:
-- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out
-- dispatch read-only project custom agents for verification: @truth-route-auditor, @truth-claim-verifier
-- read-only custom agents inspect checkout evidence directly, return structured findings, and must not edit files
-- parent supplies bounded evidence shards; read-only custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
-- dispatch write-capable project custom agents only with explicit write leases: @truth-doc-writer
-- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields
-- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes
-- parent must inspect the actual checkout diff against each lease before accepting a worker report
-- Parent agent owns Truth Document acceptance, lease validation, and final report

.github/skills/truthmark-realize/SKILL.md

@@ -1,22 +0,0 @@
----
-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 Copilot agent skill. Prompt files remain available under `.github/prompts/` for command-style invocation in supported Copilot IDEs.
-
-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

.github/skills/truthmark-realize/support/procedure.md

@@ -1,41 +0,0 @@
-# Truthmark Realize Procedure
-
-Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
-
-# Truthmark Realize
-
-Use this skill only when the user explicitly asks to realize truth docs into code.
-
-Truth Realize is doc-first:
-
-- truth docs lead
-- code follows
-- Truth Realize never edits the truth docs it is realizing
-
-Workflow:
-
-1. Read the updated truth docs named by the user, or infer the relevant docs from configured route files when present.
-2. Inspect .truthmark/config.yml and configured route files (docs/truthmark/routes/areas.md; docs/truthmark/routes/areas/) only when they exist; then read tests and the relevant functional code.
-3. Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
-Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
-Truth-doc ownership review:
-- before editing or relying on source truth docs before writing code, verify each target/source truth doc is a bounded owner for the behavior
-- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
-- if a source truth doc is broad, mixed-owner, index-like, unrouteable, stale, or conflicts with implementation evidence, stop before writing code and recommend Truth Structure or Truth Document
-- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
-4. Update functional code only so implementation matches bounded, current truth claims from the source docs.
-5. Do not edit truth docs or truth routing while realizing those docs.
-6. Run relevant tests for the changed code.
-7. Report changed code files and verification steps.
-Truthmark hierarchy hints:
-- Config, when present: .truthmark/config.yml
-- Root route index, when present: docs/truthmark/routes/areas.md
-- Area route files, when present: docs/truthmark/routes/areas/**/*.md
-- Product truth docs, when present: docs/truthmark/product/**/*.md
-- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
-
-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

.github/skills/truthmark-realize/support/report-template.md

@@ -1,19 +0,0 @@
-# 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
-```

.github/skills/truthmark-structure/SKILL.md

@@ -1,23 +0,0 @@
----
-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 Copilot agent skill. Prompt files remain available under `.github/prompts/` for command-style invocation in supported Copilot IDEs.
-
-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
-- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output

.github/skills/truthmark-structure/support/procedure.md

@@ -1,101 +0,0 @@
-# Truthmark Structure Procedure
-
-Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
-
-Use this skill to design or repair Truthmark area structure.
-
-Truth Structure is agent-native:
-- inspect repository layout, current docs, Truthmark config and route files when present, and relevant code directly
-- Evidence authority:
-  - Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
-  - Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
-- Lane classification:
-  - before writing canonical truth docs, classify the request or change as product-lane, engineering-lane, both-lane, or ambiguous
-  - product-lane writes belong under docs/truthmark/product and state product promises, boundaries, rationale, decisions, and success criteria
-  - engineering-lane writes belong under docs/truthmark/engineering and state source-backed current realization, contracts, architecture, workflows, operations, or tests
-  - both-lane work must write separate product and engineering docs and cross-link them in route YAML with realized_by and realizes, not in doc frontmatter
-  - ambiguous lane ownership must stop or invoke Truth Structure instead of writing a mixed document
-  - Do not make product docs a summary of engineering docs. Do not make engineering docs a detailed version of product docs. Product truth says what must be true and why. Engineering truth says how the repository currently realizes it.
-- inspect the configured root route index at docs/truthmark/routes/areas.md and relevant child route files under docs/truthmark/routes/areas/ when they exist
-- define areas by product or behavior ownership, not by mechanical directory mirroring
-- create or repair docs/truthmark/routes/areas.md
-- create skeletal starter truth docs only when missing ownership would otherwise block future workflows
-- Starter truth docs must use closed YAML frontmatter bounded by opening and closing --- lines; include status, truth_kind, and last_reviewed inside that frontmatter. Put source references in the final ## Source References section, not in frontmatter.
-- Starter truth docs are ownership anchors, not behavior writeups: include only the title, bounded area/scope, and Source References needed to make routing explicit.
-- Starter truth docs must keep product and engineering truth in separate files; leave substantive behavior, contract, architecture, workflow, operations, or test prose to Truth Document.
-
-- use docs/truthmark/product/** for product truth destinations
-- use docs/truthmark/engineering/** for engineering truth destinations
-- use only canonical current-truth destinations for starter truth docs
-- keep Product Decisions in product truth and Engineering Decisions in engineering truth when selecting destinations; report any relocation need instead of rewriting decision prose during topology review
-- preserve unrelated authored content
-## New area setup
-Use when a user asks to onboard a new code area into Truthmark, a new package, controller, domain, or product area lacks bounded truth ownership, or a new product area needs routing and starter truth docs.
-Do:
-- inspect the named code area
-- infer bounded product or behavior ownership
-- choose the owning route when ownership is clear; otherwise propose the route and stop for manual review
-- create or update the child route entry or file
-- create starter truth docs only where current truth is missing
-- report the initial truth boundary
-Do not:
-- do not edit functional code
-- do not perform full behavior documentation unless evidence is inspected and the task explicitly asks for it
-- do not patch broad or mixed-owner docs in place
-- do not create generic catch-all docs
-- do not treat README files as Sync targets
-## Topology Governance
-Truth Structure owns documentation topology, lane splits, decision relocation, and relationship repair. Do not depend on humans to manually organize docs/truthmark/product or docs/truthmark/engineering. Treat both configured lane roots as managed semantic roots.
-Inspect controllers, routes, handlers, services, packages, tests, existing truth docs, and route files; infer product and domain ownership from behavior boundaries, not from mechanical directory mirroring.
-When topology pressure exists, repair route structure before creating or extending truth ownership anchors.
-Truth-doc ownership review:
-- before editing or relying on candidate route owners and current truth docs, verify each target/source truth doc is a bounded owner for the behavior
-- if a target/source doc mixes independent owners, spans unrelated behaviors, acts as an index, or needs cross-owner edits, do not patch or in-place repair it
-- if a truth doc mixes independent owners, route ownership is broad, or a split is required for bounded ownership, split or reroute only the ownership topology when safe; otherwise stop with manual-review files
-- report Ownership reviewed, Structure required, Truth docs split, Truth docs restructured, or Manual handoff reason as applicable
-Topology pressure signals:
-- one area maps broad code such as src/**, app/**, server/**, services/**, or packages/**
-- one area maps multiple unrelated controllers, route groups, services, or bounded contexts
-- one truth doc owns unrelated behaviors or unrelated endpoint families
-- either configured lane root has many direct non-index docs
-- a changed controller, route, or service cannot map to a specific behavior doc
-- Truth Sync would need to create a new generic truth doc because routing is too broad
-- endpoint or controller names reveal domains missing from docs/truthmark/routes/areas/**
-Use these review thresholds as guidance:
-- more than 10 direct truth docs in one folder
-- more than 15 leaf areas in one child route file
-- more than 8 truth docs mapped to one area
-- more than 5 controllers mapped through one catch-all area
-Repair rules:
-- split broad, overloaded, or catch-all areas into behavior-owned child route files
-- split or flag mixed-owner truth docs for bounded owners before any workflow adds new behavior claims
-- create route files under docs/truthmark/routes/areas/ when a product/domain boundary is clear
-- create skeletal engineering ownership anchors under docs/truthmark/engineering only when behavior lacks a current owner
-- create skeletal product ownership anchors under docs/truthmark/product only when product promise, boundary, rationale, or user-visible capability ownership is in scope
-- README.md files are indexes, not Truth Sync targets
-- prefer bounded product docs under product/capabilities or product/decisions and engineering docs under engineering/<kind>/<surface>.md
-- keep behavior truth docs behavior-oriented, not endpoint-oriented
-- keep API endpoint details in the nearest contract truth doc when such a doc exists
-- update routing so future Truth Sync can target small docs
-- preserve existing authored docs; move or rewrite only when needed to remove ambiguity
-- report Truth docs split when one broad or mixed-owner truth doc becomes multiple bounded docs
-Evidence checklist:
-- apply the evidence checklist before finishing when Truth Structure writes routed docs, ownership claims, lane-specific decisions, or rationale
-- support ownership/behavior claims with topology or primary checkout evidence from layout, implementation boundaries, docs, config, route files, tests, templates, schemas, or contracts
-- tests/examples/canonical docs corroborate; remove, narrow, or record unsupported claims for manual handoff
-- Do not finish topology repair with mixed product/engineering authority in a single canonical truth doc.
-- If an existing canonical doc has wrong-lane sections, report the lane repair needed and only move content when the topology split explicitly requires it.
-Portable fallback:
-- If this skill surface is unavailable, perform the same workflow directly from committed repository files.
-- Do not require the truthmark CLI.
-- Inspect .truthmark/config.yml and configured route files only when they exist; then inspect canonical docs and representative implementation code.
-- Use a subagent only when the host supports that pattern; otherwise perform the topology repair inline.
-Truthmark hierarchy hints:
-- Config, when present: .truthmark/config.yml
-- Root route index, when present: docs/truthmark/routes/areas.md
-- Area route files, when present: docs/truthmark/routes/areas/**/*.md
-- Product truth docs, when present: docs/truthmark/product/**/*.md
-- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
-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.

.github/skills/truthmark-structure/support/report-template.md

@@ -1,38 +0,0 @@
-# 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.
-```

.github/skills/truthmark-structure/support/subagents-and-leases.md

@@ -1,10 +0,0 @@
-# Truthmark Structure Subagents And Leases
-
-Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
-
-Copilot custom-agent mode:
-- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out
-- dispatch read-only project custom agents only: @truth-route-auditor
-- custom agents inspect checkout evidence directly, return structured findings, and must not edit files
-- parent supplies bounded evidence shards; custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
-- Parent agent owns all Truth Structure writes and final topology decisions

.github/skills/truthmark-sync/SKILL.md

@@ -1,24 +0,0 @@
----
-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 Copilot agent skill. Prompt files remain available under `.github/prompts/` for command-style invocation in supported Copilot IDEs.
-
-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
-- support/subagents-and-leases.md — read only when using subagents, leases, or accepting worker output

.github/skills/truthmark-sync/support/procedure.md

@@ -1,70 +0,0 @@
-# Truthmark Sync Procedure
-
-Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
-
-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.
-Parent workflow:
-1. Inspect git status, staged changes, unstaged changes, and untracked files directly.
-2. Inspect .truthmark/config.yml and configured route files only when they exist; then inspect relevant canonical docs.
-3. Identify functional-code changes and the nearest truth docs or routing repairs.
-4. Evidence authority:
-  - Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
-  - Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
-5. Product truth decision:
-  - ask whether a user-visible promise, capability boundary, API contract, acceptance criterion, or explicit user/product evidence changed
-  - if yes, update or route product truth under docs/truthmark/product as well as engineering truth under docs/truthmark/engineering
-  - if no, default to engineering truth under docs/truthmark/engineering for internal implementation changes
-  - when both lanes change, keep separate product and engineering docs cross-linked through route YAML with realized_by and realizes
-  - when ownership is ambiguous, stop or route to Truth Structure instead of writing a mixed document
-6. Capture decision context from the task conversation: ask whether the user provided a product or technical decision, rationale, constraint, tradeoff, rejection reason, or scope boundary. Preserve concise user-provided decision rationale in Sync Intent before truth edits, route it to Product Decisions, Engineering Decisions, Rationale, Capability Scope, Non-Goals, Maintenance Notes, or the relevant workflow/contract section, and report whether it was placed, skipped because none was provided, or needs manual handoff.
-7. Update engineering truth first after code changes. Product truth is opt-in for externally visible promises, product boundaries, APIs, acceptance criteria, or explicit user/product evidence.
-8. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
-9. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline.
-10. Fill Sync Intent before editing truth docs or truth routing files:
-   - Changed code reviewed: functional files, tests, configs, generated outputs, or other implementation evidence inspected
-   - Affected route/truth owner: bounded route area or canonical truth owner that maps the change
-   - Target truth docs: docs expected to change, or docs reviewed and left unchanged
-   - Intended update: claim/doc/routing update planned before writing
-   - Evidence to verify: checkout evidence that will support, narrow, remove, or record each claim for manual handoff
-   - User-provided decisions/rationale: decisions, rationale, constraints, tradeoffs, rejection reasons, or scope boundaries from the current task conversation, or "none provided"
-   - 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
-- safe in-scope topology repair may update truth routing files and create or update bounded leaf truth docs needed to map the changed functional code; keep the repair limited to the affected route owner
-- stop and recommend Truth Structure only when topology repair is unsafe, ambiguous, or outside the current task boundary
-- report the route files and changed code paths that required structure repair
-- do not create another generic truth doc
-- README.md files are indexes, not Truth Sync targets
-- must not append behavior details to a README.md index
-- write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes
-Optional validation tooling:
-- you may run truthmark check when local tooling is available
-- you may validate the final report with `truthmark validate sync-report <report-file> --json` when available
-- do not require the truthmark binary; direct checkout inspection is the canonical path
-- optional validation must not replace agent judgment about docs and routing
-- update Product Decisions only in product truth and Engineering Decisions only in engineering truth when evidence supports the lane-specific decision change
-Truthmark hierarchy hints:
-- Config, when present: .truthmark/config.yml
-- Root route index, when present: docs/truthmark/routes/areas.md
-- Area route files, when present: docs/truthmark/routes/areas/**/*.md
-- Product truth docs, when present: docs/truthmark/product/**/*.md
-- Engineering truth docs, when present: docs/truthmark/engineering/**/*.md
-Parent post-sync verification:
-- verify only truth docs and leased truth routing files changed during sync
-- stop on any unrelated diff caused by the sync step
-- stop if functional code changed during sync
-- validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked
-- 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

.github/skills/truthmark-sync/support/report-template.md

@@ -1,52 +0,0 @@
-# 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.
-```

.github/skills/truthmark-sync/support/subagents-and-leases.md

@@ -1,14 +0,0 @@
-# Truthmark Sync Subagents And Leases
-
-Truthmark-managed generated file. Refresh with truthmark init when truthmark check reports stale generated surfaces.
-
-Copilot custom-agent mode:
-- use automatically when this workflow runs in Copilot and the parent agent chooses bounded custom-agent fan-out
-- dispatch read-only project custom agents for verification: @truth-route-auditor, @truth-claim-verifier
-- read-only custom agents inspect checkout evidence directly, return structured findings, and must not edit files
-- parent supplies bounded evidence shards; read-only custom agents must not preload host instruction files or repo-wide policy docs unless assigned as evidence
-- dispatch write-capable project custom agents only with explicit write leases: @truth-doc-writer
-- each write lease must name objective, required reads, allowed writes, forbidden writes, evidence, verification, and report fields
-- write workers must stop when a required edit is off-lease and report status, filesChanged, evidence, offLeaseChanges, blockers, and notes
-- parent must inspect the actual checkout diff against each lease before accepting a worker report
-- Parent agent owns Truth Sync acceptance, lease validation, and final report

.truthmark/config.yml

@@ -3,7 +3,6 @@ platforms:
   - codex
   - opencode
   - claude-code
-  - github-copilot
   - antigravity
   - cursor
 truthmark:
@@ -21,3 +20,6 @@ ignore:
   - vendor/**
   - dist/**
   - build/**
+  # Repo-local tooling for repo-local policy; no product truth owner by design.
+  - scripts/repo-rules-block.ts
+  - scripts/render-repo-rules.ts

AGENTS.md

@@ -1,4 +1,4 @@
-Repository rule source of truth: [docs/ai/repo-rules.md](docs/ai/repo-rules.md). Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist.
+Repository rule source of truth: [docs/repo/ai/repo-rules.md](docs/repo/ai/repo-rules.md). Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist.
 
 Use explicitly configured repository policy docs only when they exist in this checkout.
 
@@ -6,6 +6,75 @@ Agent-specific:
 - Read the configured Truthmark routing files when choosing or updating canonical docs.
 - Use repository onboarding or docs-map files only when present and needed for unclear or cross-area routing.
 
+<!-- repo-rules:start -->
+<!-- Generated from docs/repo/ai/repo-rules.md by `node --import tsx scripts/render-repo-rules.ts`. Edit the source doc, not this block. -->
+
+## Authority
+
+Conflict order:
+
+1. this file (`docs/repo/ai/repo-rules.md`)
+2. [.truthmark/config.yml](.truthmark/config.yml)
+3. [docs/truthmark/routes/areas.md](docs/truthmark/routes/areas.md) and `docs/truthmark/routes/areas/**/*.md`
+4. `docs/repo/standards/**/*.md`
+5. `docs/repo/architecture/**/*.md`
+6. `docs/truthmark/product/**/*.md` and `docs/truthmark/engineering/**/*.md`
+
+Authoritative context is the current checkout plus user-provided session context; chat, external notes, and off-repo memory are non-authoritative unless committed or supplied now.
+
+Code is the implementation. On code/doc conflict, inspect code, decide whether code is intentional or docs are stale, update stale docs for intentional behavior, and change code to match docs only when requested or required.
+
+## Documentation Scope
+
+Everything under `docs/repo/**` is repo-local policy for developing Truthmark itself. It ships to nobody, `src/**` never references it, and it is not a downstream scaffold, generated surface, or required artifact for repositories that install Truthmark. Repo-local docs declare `scope: repo-local` and use `doc_type`, never `truth_kind`.
+
+Everything else under `docs/**` describes the installed product. `docs/truthmark/**` is this repository dogfooding the same truth schema `truthmark init` scaffolds downstream, so it is evidence about the product; `docs/repo/**` is not.
+
+When answering a question or making a claim about the product's schema, lanes, commands, or installed surfaces, cite `src/**`, `docs/truthmark/**`, or generated host surfaces. A repo-local doc is never evidence for what downstream repositories get. [tests/doc-scope.test.ts](tests/doc-scope.test.ts) enforces this boundary.
+
+## Product Boundary
+
+The canonical product boundary is [docs/repo/architecture/product-boundary.md](docs/repo/architecture/product-boundary.md), which is repo-local under the rule above. 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 `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.
+
+## Rules
+
+1. Workflow and skill quality, performance, dispatch clarity, and agent effectiveness are the highest-priority repo concerns. Treat workflows and skills as the core product surface of this agent-native project; when tradeoffs conflict, optimize them before secondary structure, convenience, or polish.
+2. Product boundaries are mandatory design inputs. Before generating a new design or plan, read [docs/repo/architecture/product-boundary.md](docs/repo/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. 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.
+9. Claims about commands, platforms, runtime topology, services, generated surfaces, or workflow capabilities require primary checkout evidence. Surface desired-vs-implemented conflicts instead of averaging patterns or inventing future behavior.
+10. Deterministic policy belongs in code, schemas, parsers, templates, or checks when the repository can enforce it. Use model-facing workflow prose to guide agents, not as the only guard for repeatable routing, ownership, parsing, or generation decisions.
+11. Keep routing explicit: when a code area changes canonical docs, update truth routing in the same change.
+12. Behavior, contract, workflow, and completion-rule changes update the nearest canonical doc. Major product/onboarding/install/command/positioning/workflow changes also update the root README. A material root README change blocks completion until the localized root READMEs change in the same working change.
+13. Follow established module boundaries and existing generated-surface patterns; avoid duplicate surfaces, single-use abstractions, speculative configurability, and impossible-scenario error handling.
+14. Verify the text and file contracts that changed with the narrowest evidence that can falsify them: generated diffs, structured parsers, snapshots, fixture round-trips, build/package/check commands, or focused tests. Do not run broad tests as ceremony when they add no evidence; state skipped checks.
+15. Work surgically and fail visibly: surface assumptions, conflicts, skipped files, blocked ownership, and unverified claims; touch only request-traceable lines, match existing style, checkpoint long workflow or skill edits, and report unrelated issues instead of editing them.
+
+## Instruction Surface Boundary
+
+`AGENTS.md` and `CLAUDE.md` carry two generated regions, and neither is hand-edited:
+
+- the `truthmark:start` / `truthmark:end` comment markers wrap the Truthmark workflow surface, refreshed by `truthmark init`
+- the `repo-rules:start` / `repo-rules:end` comment markers wrap this file's always-on section, rendered locally with `node --import tsx scripts/render-repo-rules.ts`
+
+Marker names appear here without their comment syntax on purpose: a literal marker inside the rendered region would duplicate it in the instruction files and make the managed block unparseable.
+
+This file stays the authority; the rendered region is generated output under rule 8. Change policy here and re-render. Hand-written preamble outside both regions stays short and delegates rather than restating policy. Do not put this repository's internal policy, completion gates, or maintainer-only standards inside the Truthmark managed block, package templates, installed workflow skills, prompts, or downstream scaffold output.
+
+## Completion Gate
+
+Before declaring changed repository work complete, apply [docs/repo/standards/pre-completion-checklist.md](docs/repo/standards/pre-completion-checklist.md) and [docs/repo/standards/testing-and-verification.md](docs/repo/standards/testing-and-verification.md). Skip this gate only for read-only or no-file-change sessions, and state the skip reason when completion or verification would otherwise be expected.
+
+<!-- repo-rules:end -->
+
 <!-- truthmark:start -->
 ## Truthmark Workflow
 

CLAUDE.md

@@ -1,4 +1,4 @@
-Repository rule source of truth: [docs/ai/repo-rules.md](docs/ai/repo-rules.md). Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist.
+Repository rule source of truth: [docs/repo/ai/repo-rules.md](docs/repo/ai/repo-rules.md). Follow repository instruction files that are present in this checkout; do not assume optional policy docs exist.
 
 Use explicitly configured repository policy docs only when they exist in this checkout.
 
@@ -6,6 +6,75 @@ Agent-specific:
 - Read the configured Truthmark routing files when choosing or updating canonical docs.
 - Use repository onboarding or docs-map files only when present and needed for unclear or cross-area routing.
 
+<!-- repo-rules:start -->
+<!-- Generated from docs/repo/ai/repo-rules.md by `node --import tsx scripts/render-repo-rules.ts`. Edit the source doc, not this block. -->
+
+## Authority
+
+Conflict order:
+
+1. this file (`docs/repo/ai/repo-rules.md`)
+2. [.truthmark/config.yml](.truthmark/config.yml)
+3. [docs/truthmark/routes/areas.md](docs/truthmark/routes/areas.md) and `docs/truthmark/routes/areas/**/*.md`
+4. `docs/repo/standards/**/*.md`
+5. `docs/repo/architecture/**/*.md`
+6. `docs/truthmark/product/**/*.md` and `docs/truthmark/engineering/**/*.md`
+
+Authoritative context is the current checkout plus user-provided session context; chat, external notes, and off-repo memory are non-authoritative unless committed or supplied now.
+
+Code is the implementation. On code/doc conflict, inspect code, decide whether code is intentional or docs are stale, update stale docs for intentional behavior, and change code to match docs only when requested or required.
+
+## Documentation Scope
+
+Everything under `docs/repo/**` is repo-local policy for developing Truthmark itself. It ships to nobody, `src/**` never references it, and it is not a downstream scaffold, generated surface, or required artifact for repositories that install Truthmark. Repo-local docs declare `scope: repo-local` and use `doc_type`, never `truth_kind`.
+
+Everything else under `docs/**` describes the installed product. `docs/truthmark/**` is this repository dogfooding the same truth schema `truthmark init` scaffolds downstream, so it is evidence about the product; `docs/repo/**` is not.
+
+When answering a question or making a claim about the product's schema, lanes, commands, or installed surfaces, cite `src/**`, `docs/truthmark/**`, or generated host surfaces. A repo-local doc is never evidence for what downstream repositories get. [tests/doc-scope.test.ts](tests/doc-scope.test.ts) enforces this boundary.
+
+## Product Boundary
+
+The canonical product boundary is [docs/repo/architecture/product-boundary.md](docs/repo/architecture/product-boundary.md), which is repo-local under the rule above. 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 `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.
+
+## Rules
+
+1. Workflow and skill quality, performance, dispatch clarity, and agent effectiveness are the highest-priority repo concerns. Treat workflows and skills as the core product surface of this agent-native project; when tradeoffs conflict, optimize them before secondary structure, convenience, or polish.
+2. Product boundaries are mandatory design inputs. Before generating a new design or plan, read [docs/repo/architecture/product-boundary.md](docs/repo/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. 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.
+9. Claims about commands, platforms, runtime topology, services, generated surfaces, or workflow capabilities require primary checkout evidence. Surface desired-vs-implemented conflicts instead of averaging patterns or inventing future behavior.
+10. Deterministic policy belongs in code, schemas, parsers, templates, or checks when the repository can enforce it. Use model-facing workflow prose to guide agents, not as the only guard for repeatable routing, ownership, parsing, or generation decisions.
+11. Keep routing explicit: when a code area changes canonical docs, update truth routing in the same change.
+12. Behavior, contract, workflow, and completion-rule changes update the nearest canonical doc. Major product/onboarding/install/command/positioning/workflow changes also update the root README. A material root README change blocks completion until the localized root READMEs change in the same working change.
+13. Follow established module boundaries and existing generated-surface patterns; avoid duplicate surfaces, single-use abstractions, speculative configurability, and impossible-scenario error handling.
+14. Verify the text and file contracts that changed with the narrowest evidence that can falsify them: generated diffs, structured parsers, snapshots, fixture round-trips, build/package/check commands, or focused tests. Do not run broad tests as ceremony when they add no evidence; state skipped checks.
+15. Work surgically and fail visibly: surface assumptions, conflicts, skipped files, blocked ownership, and unverified claims; touch only request-traceable lines, match existing style, checkpoint long workflow or skill edits, and report unrelated issues instead of editing them.
+
+## Instruction Surface Boundary
+
+`AGENTS.md` and `CLAUDE.md` carry two generated regions, and neither is hand-edited:
+
+- the `truthmark:start` / `truthmark:end` comment markers wrap the Truthmark workflow surface, refreshed by `truthmark init`
+- the `repo-rules:start` / `repo-rules:end` comment markers wrap this file's always-on section, rendered locally with `node --import tsx scripts/render-repo-rules.ts`
+
+Marker names appear here without their comment syntax on purpose: a literal marker inside the rendered region would duplicate it in the instruction files and make the managed block unparseable.
+
+This file stays the authority; the rendered region is generated output under rule 8. Change policy here and re-render. Hand-written preamble outside both regions stays short and delegates rather than restating policy. Do not put this repository's internal policy, completion gates, or maintainer-only standards inside the Truthmark managed block, package templates, installed workflow skills, prompts, or downstream scaffold output.
+
+## Completion Gate
+
+Before declaring changed repository work complete, apply [docs/repo/standards/pre-completion-checklist.md](docs/repo/standards/pre-completion-checklist.md) and [docs/repo/standards/testing-and-verification.md](docs/repo/standards/testing-and-verification.md). Skip this gate only for read-only or no-file-change sessions, and state the skip reason when completion or verification would otherwise be expected.
+
+<!-- repo-rules:end -->
+
 <!-- truthmark:start -->
 ## Truthmark Workflow
 

README.md

@@ -185,7 +185,6 @@ Structured JSON output is available throughout the command-line interface for sc
 - [Documentation index](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [Architecture overview](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [Configuration, routing, and command contracts](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [Maintaining repository truth](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [Contributing](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **Install Truthmark, select your coding host, and turn one real behavior into documentation today.**

changes/2026-08-23-agent-instruction-surface-consolidation.md

@@ -0,0 +1,29 @@
+# Agent Instruction Surface Consolidation
+
+Version action: none
+
+## PR Summary
+
+- Removed `github-copilot` from `.truthmark/config.yml`, let the init lifecycle prune the 29 generated surfaces it owned, and deleted the leftover `.github/copilot-instructions.md`. Copilot remains a supported platform of the product; only this repository's installation changed.
+- Narrowed the checked-in path lists in `tests/templates/generated-surfaces.test.ts` to the platforms this repository installs. The `allPlatforms` render assertions keep full Copilot coverage.
+- Added a generated `repo-rules:start` / `repo-rules:end` region to `AGENTS.md` and `CLAUDE.md`, rendered from the always-on section of `docs/repo/ai/repo-rules.md` by the local `node --import tsx scripts/render-repo-rules.ts` command, so repository authority, documentation scope, product boundary, the numbered rules, and the completion gate survive context compaction.
+- Added `scripts/repo-rules-block.ts` and `scripts/render-repo-rules.ts`, plus `tests/repo-rules-block.test.ts` covering source sync, cross-file equality, marker ordering, link rewriting, malformed-marker rejection, managed-block round-trip, and idempotence.
+- Rewrote the Instruction Surface Boundary rule to describe the two-region model, since the previous wording forbade the preamble duplication this change introduces.
+- Included `scripts/**/*.ts` in `tsconfig.json` so the new repo-local tooling is typechecked.
+
+`docs/repo/ai/repo-rules.md` remains the authority. The region in each instruction file is generated output under rule 8, so no second document claims authority over repository policy. `agent-onboarding.md` deliberately stays a file: it is conditional routing, and inlining it would cost every session for guidance most tasks do not need.
+
+The two new scripts are excluded in `.truthmark/config.yml` rather than routed. They are repo-local tooling implementing repo-local policy, so mapping them to a product truth doc would reintroduce the boundary confusion this work removes.
+
+## Release Note
+
+- None; internal-only change. No `src/` behavior changed.
+
+## Verification
+
+- `npm run lint`
+- `npm run typecheck`
+- `npm test` (423 pass, 0 fail)
+- `npm run build`
+- `npm run dev -- init` followed by `npm run dev -- check` (no diagnostics; the managed-block refresh leaves the repo-local region intact and preserves config comments)
+- Relative-link audit across all tracked Markdown: 12 broken links, unchanged from before this work and all pre-existing in `docs/repo/research/`.

changes/2026-08-23-fix-stale-doc-links.md

@@ -0,0 +1,23 @@
+# Fix Stale Documentation Links
+
+Version action: none
+
+## PR Summary
+
+- Fixed all 12 relative links broken since before this branch, all inside `docs/repo/research/`: 11 in `2026-05-15-agent-skills-workflow-review.md` pointed at a defunct `docs/truth/workflows/` tree and `.codex/skills/` paths that moved to `.agents/skills/`; 1 in `2026-06-29-manual-agent-skill-quality-eval-framework.md` cited a `tests/evals/workflow-eval-framwork.test.ts` that was never created, replaced with the actual routing-case fixture file it should have pointed to.
+- Corrected a stale generated-surfaces list in the same 2026-05-15 note (it still named `.codex/skills/`, `.github/prompts/`, `.github/agents/`, and a `.gemini/commands/truthmark/` path that never existed in the schema) to match what this repository actually installs.
+- Removed the "Maintaining repository truth" link from the root README and all 15 localized READMEs. That guide's own text says "This guide is for humans maintaining Truthmark's own docs tree" — it is repo-local content (`docs/repo/standards/maintaining-repository-truth.md`, `scope: repo-local`), but the storefront "Learn more" section presented it alongside product-facing docs (User Guide, Architecture overview, Configuration contracts) as if it were guidance for people installing Truthmark. Removed the same mispositioned link from `docs/user-guide.md`'s documentation list for the same reason.
+
+A full relative-link audit across every tracked Markdown file now reports zero broken links, down from a 12-link baseline that predates this branch.
+
+## Release Note
+
+- None; internal-only documentation fixes. No `src/` behavior changed.
+
+## Verification
+
+- `npm run lint`
+- `npm run typecheck`
+- `npm test` (423 pass, 0 fail)
+- `npm run dev -- check` (no diagnostics)
+- Relative-link audit across all tracked Markdown: 0 broken (was 12).

changes/2026-08-23-repo-local-docs-scope-boundary.md

@@ -0,0 +1,28 @@
+# Repo-Local Documentation Scope Boundary
+
+Version action: none
+
+## PR Summary
+
+- Moved repo-local policy docs under `docs/repo/` (`docs/ai`, `docs/standards`, `docs/architecture`, `docs/research`) so the repo-local versus product-surface boundary is visible in every path rather than only in prose.
+- Added `scope: repo-local` frontmatter to all 19 docs under `docs/repo/`, including six research notes that previously had no frontmatter.
+- Added `tests/doc-scope.test.ts` enforcing four invariants: every doc under `docs/repo/` declares `scope: repo-local`; that scope never appears in published product docs; `truth_kind` never appears in repo-local docs; and `src/**` never references `docs/repo`.
+- Replaced the near-uniform "Primary audience" column in the `docs/README.md` directory map with a `Scope` column, and regrouped the audience split by scope.
+- Added a `Documentation Scope` section to `docs/repo/ai/repo-rules.md` generalizing the repo-local rule that previously applied only to `product-boundary.md`, and a one-line scope statement to the `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md` preambles.
+- Updated inbound references in `AGENTS.md`, `CLAUDE.md`, `docs/README.md`, `docs/user-guide.md`, `tests/product-boundary.test.ts`, and the root plus 15 localized READMEs.
+
+The enforcing check is a repo-local test rather than a `src/checks/` diagnostic because `truthmark check` runs in downstream repositories, which have no `docs/repo/` boundary and would see spurious findings.
+
+## Release Note
+
+- None; internal-only change. No `src/` behavior changed.
+
+## Verification
+
+- `npm run lint`
+- `npm run typecheck`
+- `npm test` (416 pass, 0 fail)
+- `npm run build`
+- `npm run dev -- check` (no diagnostics)
+- Relative-link audit across all tracked Markdown: 12 broken links before and after the move, all pre-existing in `docs/repo/research/` and unrelated to this change.
+- Mutation-tested `tests/doc-scope.test.ts`: removing the scope field, leaking `scope: repo-local` into `docs/truthmark/`, and referencing `docs/repo` from `src/` each fail the suite.

docs/README.md

@@ -1,9 +1,9 @@
 ---
 status: active
 doc_type: index
-last_reviewed: 2026-07-30
+last_reviewed: 2026-08-23
 source_of_truth:
-  - docs/ai/repo-rules.md
+  - docs/repo/ai/repo-rules.md
   - ../.truthmark/config.yml
 ---
 
@@ -13,7 +13,14 @@ source_of_truth:
 
 `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.
+The first thing to establish about any doc here is its **scope**:
+
+- **repo-local** (`docs/repo/**`): policy for developing Truthmark itself. It is not a downstream scaffold, generated surface, or required artifact for repositories that install Truthmark. Nothing under `docs/repo/` ships, and `src/` never references it.
+- **product surface** (everything else under `docs/`): documentation of the product Truthmark installs into other repositories. `docs/truthmark/**` is this repository dogfooding the same truth schema that `truthmark init` scaffolds downstream.
+
+Do not cite a repo-local doc as evidence about the product's behavior, schema, or installed surfaces. Every doc under `docs/repo/` declares `scope: repo-local` in frontmatter, and `tests/doc-scope.test.ts` enforces the boundary.
+
+`AGENTS.md` is the agent entry point, but it delegates repository-wide rules to [docs/repo/ai/repo-rules.md](repo/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.
 
 ## Scope
 
@@ -21,42 +28,44 @@ This doc defines the current structure, navigation map, and maintenance expectat
 
 ## Authority Source
 
-Repository-wide conflict order and completion policy live in [docs/ai/repo-rules.md](ai/repo-rules.md). Use this index for navigation and document-class guidance; it does not restate the full authority hierarchy.
+Repository-wide conflict order and completion policy live in [docs/repo/ai/repo-rules.md](repo/ai/repo-rules.md). Use this index for navigation and document-class guidance; it does not restate the full authority hierarchy.
 
 [README.md](../README.md) may help with onboarding and positioning, but it must not override current-state docs or repository-wide agent rules.
 
-## Audience Split
+## Scope Split
 
-### Agent-centric docs
+### Repo-local docs (`scope: repo-local`, ships to nobody)
+
+- `docs/repo/ai/` for repository rules and agent onboarding
+- `docs/repo/standards/` for reusable constraints and completion rules
+- `docs/repo/architecture/` for repository-specific architecture guardrails
+- `docs/repo/research/` for non-canonical research evidence, evaluations, and comparisons
+
+### Product-surface docs
 
-- `docs/ai/` for repository rules and agent onboarding
-- `docs/truthmark/routes/` for routing metadata
-- `docs/standards/` for reusable constraints and completion 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
-
-### Human-centric docs
-
+- `docs/truthmark/routes/` for routing metadata
+- `docs/truthmark/templates/` for editable scaffold templates used to create new docs
 - [README.md](../README.md) for onboarding and positioning
 - [docs/user-guide.md](user-guide.md) for detailed usage, command, workflow, configuration, routing, Portal, and example guidance
 
 ## 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/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          |
+| Path                          | Type              | Scope           | Purpose                                                                               |
+| ----------------------------- | ----------------- | --------------- | ------------------------------------------------------------------------------------- |
+| `docs/repo/ai/`               | agent rules       | repo-local      | Repository-wide rules and fast onboarding for developing Truthmark itself             |
+| `docs/repo/standards/`        | standard          | repo-local      | Reusable constraints, verification rules, completion gates                            |
+| `docs/repo/architecture/`     | architecture      | repo-local      | Repository-specific architecture guardrails                                           |
+| `docs/repo/research/`         | research          | repo-local      | Non-canonical research evidence, evaluations, and comparisons                         |
+| `docs/truthmark/product/`     | product truth     | product surface | Product capability promises, boundaries, decisions, and acceptance criteria           |
+| `docs/truthmark/engineering/` | engineering truth | product surface | Current implementation behavior for init, check, contracts, workflows, and operations |
+| `docs/truthmark/routes/`      | routing           | product surface | Truth-routing metadata such as `areas.md` and `areas/**/*.md`                         |
+| `docs/truthmark/templates/`   | template          | product surface | Editable templates for scaffolded docs; templates are not Truth Sync targets          |
+| `docs/user-guide.md`          | guide             | product surface | Detailed usage guide kept out of the root README so onboarding stays concise          |
+
+`docs/truthmark/**` carries `truth_kind` (the schema `truthmark init` scaffolds downstream); `docs/repo/**` carries `doc_type` and never `truth_kind`.
 
 ## Frontmatter Policy
 
@@ -67,12 +76,14 @@ Canonical docs should include frontmatter and keep these fields current:
 - `last_reviewed`
 - `source_of_truth`
 
+Every doc under `docs/repo/` must also declare `scope: repo-local`.
+
 ## Update Rules
 
-- When repository-wide agent policy changes, update [docs/ai/repo-rules.md](ai/repo-rules.md).
+- When repository-wide agent policy changes, update [docs/repo/ai/repo-rules.md](repo/ai/repo-rules.md).
 - When code-to-doc routing changes, update [docs/truthmark/routes/areas.md](truthmark/routes/areas.md) in the same change.
-- When package versions or release/version policy change, apply [docs/standards/versioning.md](standards/versioning.md) before accepting the version.
-- When PR or release source text is needed, write a `changes/` note using [docs/standards/change-notes.md](standards/change-notes.md).
+- When package versions or release/version policy change, apply [docs/repo/standards/versioning.md](repo/standards/versioning.md) before accepting the version.
+- When PR or release source text is needed, write a `changes/` note using [docs/repo/standards/change-notes.md](repo/standards/change-notes.md).
 - 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.
@@ -91,14 +102,14 @@ Canonical docs should include frontmatter and keep these fields current:
 1. [README.md](../README.md)
 2. [docs/user-guide.md](user-guide.md), when command or workflow detail is needed
 3. [.truthmark/config.yml](../.truthmark/config.yml)
-4. [docs/ai/repo-rules.md](ai/repo-rules.md)
+4. [docs/repo/ai/repo-rules.md](repo/ai/repo-rules.md)
 5. [docs/truthmark/engineering/architecture/overview.md](truthmark/engineering/architecture/overview.md)
 6. the relevant product, engineering, or standard doc for the area being changed
 
 ### For agents
 
-1. [docs/ai/repo-rules.md](ai/repo-rules.md)
-2. [docs/ai/agent-onboarding.md](ai/agent-onboarding.md), when routing is unclear or cross-area
+1. [docs/repo/ai/repo-rules.md](repo/ai/repo-rules.md)
+2. [docs/repo/ai/agent-onboarding.md](repo/ai/agent-onboarding.md), when routing is unclear or cross-area
 3. [docs/truthmark/routes/areas.md](truthmark/routes/areas.md), when mapping code to canonical truth
 4. [docs/truthmark/engineering/architecture/overview.md](truthmark/engineering/architecture/overview.md), when changing module boundaries
 5. the relevant standard, product truth, and engineering truth docs for the task
@@ -111,8 +122,9 @@ The canonical tree should stay small, explicit, and current. Git history provide
 
 ## Product Decisions
 
-- Decision (2026-05-15): The docs index owns navigation and document-class guidance for the canonical tree, while [docs/ai/repo-rules.md](ai/repo-rules.md) owns repository-wide authority order and completion policy.
+- Decision (2026-05-15): The docs index owns navigation and document-class guidance for the canonical tree, while [docs/repo/ai/repo-rules.md](repo/ai/repo-rules.md) owns repository-wide authority order and completion policy.
 - Decision (2026-06-20): The root README is the concise human storefront. Detailed human-facing command, workflow, configuration, routing, Portal, and example material belongs in [docs/user-guide.md](user-guide.md).
+- Decision (2026-08-23): Repo-local policy lives under `docs/repo/` so the repo-local versus product-surface boundary is visible in every path, not only in prose. Agents reason from paths constantly and read prose once, so the boundary is encoded in the directory name, in `scope: repo-local` frontmatter, and in `tests/doc-scope.test.ts`. The enforcing test is repo-local because `truthmark check` runs in downstream repositories, which do not have this boundary.
 
 ## Rationale
 

docs/ai/agent-onboarding.md

@@ -1,97 +0,0 @@
----
-status: active
-doc_type: agent-guide
-last_reviewed: 2026-05-16
-source_of_truth:
-  - repo-rules.md
-  - ../README.md
----
-
-# Agent Onboarding
-
-## Purpose
-
-Fast routing for agents. Repository-wide rules live in [docs/ai/repo-rules.md](repo-rules.md).
-
-## Startup
-
-1. Read your agent entry point, usually [AGENTS.md](../../AGENTS.md).
-2. Read [docs/README.md](../README.md).
-3. Identify whether the task changes scaffold behavior, diagnostics, installed workflows, or only documentation placement.
-4. Read only the docs that govern that slice before editing code or canonical docs.
-
-## Change Routing
-
-### CLI or scaffold behavior
-
-Read:
-
-1. [docs/truthmark/engineering/architecture/overview.md](../truthmark/engineering/architecture/overview.md)
-2. [docs/truthmark/engineering/behaviors/init-and-scaffold.md](../truthmark/engineering/behaviors/init-and-scaffold.md)
-3. [docs/truthmark/engineering/contracts/config-route-and-check-contracts.md](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
-4. [docs/truthmark/product/capabilities/lane-separated-truth.md](../truthmark/product/capabilities/lane-separated-truth.md)
-
-### Diagnostics, routing, or containment checks
-
-Read:
-
-1. [docs/truthmark/engineering/architecture/overview.md](../truthmark/engineering/architecture/overview.md)
-2. [docs/truthmark/engineering/behaviors/check-diagnostics.md](../truthmark/engineering/behaviors/check-diagnostics.md)
-3. [docs/standards/documentation-governance.md](../standards/documentation-governance.md)
-4. [docs/truthmark/engineering/contracts/config-route-and-check-contracts.md](../truthmark/engineering/contracts/config-route-and-check-contracts.md)
-
-### Installed workflow, prompt, or reporting changes
-
-Read:
-
-1. [.truthmark/config.yml](../../.truthmark/config.yml)
-2. [docs/truthmark/product/capabilities/agent-native-workflow-injection.md](../truthmark/product/capabilities/agent-native-workflow-injection.md)
-3. [docs/truthmark/engineering/workflows/installed-workflow-runtime.md](../truthmark/engineering/workflows/installed-workflow-runtime.md) and [docs/truthmark/engineering/contracts/generated-host-surfaces.md](../truthmark/engineering/contracts/generated-host-surfaces.md)
-4. [docs/standards/maintaining-repository-truth.md](../standards/maintaining-repository-truth.md)
-5. The manifest, renderer, generated surfaces, and focused tests named by the workflow truth docs
-
-### Package version changes
-
-Read:
-
-1. [docs/standards/versioning.md](../standards/versioning.md)
-2. [docs/standards/change-notes.md](../standards/change-notes.md)
-3. [docs/standards/testing-and-verification.md](../standards/testing-and-verification.md)
-
-### PR or release text
-
-Read:
-
-1. [docs/standards/change-notes.md](../standards/change-notes.md)
-2. [docs/standards/versioning.md](../standards/versioning.md), only when package version changes are in scope
-
-### Documentation structure or policy changes
-
-Read:
-
-1. [docs/README.md](../README.md)
-2. [docs/standards/documentation-governance.md](../standards/documentation-governance.md)
-3. [docs/standards/maintaining-repository-truth.md](../standards/maintaining-repository-truth.md)
-
-## Agent Rules
-
-Do:
-
-- treat [docs/ai/repo-rules.md](repo-rules.md) as the primary authority for repository-wide rules
-- route code changes to the nearest maintained architecture, contract, and truth docs
-- update [docs/truthmark/routes/areas.md](../truthmark/routes/areas.md) when canonical routing changes
-- apply [docs/standards/versioning.md](../standards/versioning.md) before changing or accepting a package version
-- write `changes/` notes from [docs/standards/change-notes.md](../standards/change-notes.md) when PR or release text is needed
-- preserve the generated Truthmark block in [AGENTS.md](../../AGENTS.md) unless the template behavior itself is changing
-- keep non-canonical planning notes separate from current-state docs
-
-Do not:
-
-- treat [README.md](../../README.md) as the final source of behavioral truth
-- invent unimplemented commands such as a current `truthmark realize` CLI command
-- leave routing broad when you can point to a smaller maintained truth surface
-- rewrite functional code during documentation-only tasks
-
-## Verification
-
-Use [docs/standards/testing-and-verification.md](../standards/testing-and-verification.md) for commands and [docs/standards/pre-completion-checklist.md](../standards/pre-completion-checklist.md) as the completion gate.

docs/readmes/README.ar.md

@@ -185,7 +185,6 @@ truthmark check --base <base-ref>
 - [فهرس التوثيق](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [نظرة عامة على المعمارية](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [عقود الإعداد والتوجيه والأوامر](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [صيانة حقيقة المستودع](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [المساهمة](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **ثبّت Truthmark، واختر مضيف البرمجة، وحوّل سلوكاً حقيقياً إلى توثيق اليوم.**

docs/readmes/README.de.md

@@ -185,7 +185,6 @@ Strukturierte JSON-Ausgabe ist in der gesamten Befehlszeilenschnittstelle für S
 - [Dokumentationsindex](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [Architekturüberblick](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [Konfigurations-, Routing- und Befehlsverträge](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [Repository-Wahrheit pflegen](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [Mitwirken](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **Installiere Truthmark, wähle deinen Coding-Host und verwandle noch heute ein echtes Verhalten in Dokumentation.**

docs/readmes/README.el.md

@@ -185,7 +185,6 @@ truthmark check --base <base-ref>
 - [Ευρετήριο τεκμηρίωσης](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [Επισκόπηση αρχιτεκτονικής](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [Συμβόλαια διαμόρφωσης, δρομολόγησης και εντολών](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [Συντήρηση της αλήθειας του αποθετηρίου](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [Συνεισφορά](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **Εγκαταστήστε το Truthmark, επιλέξτε τον host προγραμματισμού σας και μετατρέψτε σήμερα μία πραγματική συμπεριφορά σε τεκμηρίωση.**

docs/readmes/README.es.md

@@ -185,7 +185,6 @@ La salida JSON estructurada está disponible en toda la interfaz de línea de co
 - [Índice de documentación](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [Descripción general de la arquitectura](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [Contratos de configuración, enrutamiento y comandos](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [Mantenimiento de la verdad del repositorio](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [Contribuir](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **Instala Truthmark, selecciona tu host de programación y convierte hoy un comportamiento real en documentación.**

docs/readmes/README.fr.md

@@ -185,7 +185,6 @@ Une sortie JSON structurée est disponible dans toute l’interface en ligne de
 - [Index de la documentation](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [Vue d’ensemble de l’architecture](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [Contrats de configuration, de routage et de commande](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [Maintenir la vérité du dépôt](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [Contribuer](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **Installez Truthmark, sélectionnez votre hôte de codage et transformez dès aujourd’hui un comportement réel en documentation.**

docs/readmes/README.id.md

@@ -185,7 +185,6 @@ Output JSON terstruktur tersedia di seluruh antarmuka baris perintah untuk skrip
 - [Indeks dokumentasi](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [Ikhtisar arsitektur](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [Kontrak konfigurasi, perutean, dan perintah](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [Memelihara kebenaran repositori](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [Berkontribusi](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **Pasang Truthmark, pilih host pengodean Anda, dan ubah satu perilaku nyata menjadi dokumentasi hari ini.**

docs/readmes/README.it.md

@@ -185,7 +185,6 @@ L’output JSON strutturato è disponibile in tutta l’interfaccia a riga di co
 - [Indice della documentazione](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [Panoramica dell’architettura](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [Contratti di configurazione, routing e comandi](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [Manutenzione della verità del repository](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [Contribuire](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **Installa Truthmark, seleziona il tuo host di coding e trasforma oggi stesso un comportamento reale in documentazione.**

docs/readmes/README.ja.md

@@ -185,7 +185,6 @@ Truthmark は、すでに AI コーディングエージェントを利用し、
 - [ドキュメント索引](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [アーキテクチャ概要](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [設定、ルーティング、コマンドの契約](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [リポジトリの事実を維持する](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [コントリビューション](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **Truthmark をインストールし、コーディングホストを選び、今日から実際の振る舞いをドキュメントに変えましょう。**

docs/readmes/README.ko.md

@@ -185,7 +185,6 @@ Truthmark는 이미 AI 코딩 에이전트를 사용하며, 코드가 변하는
 - [문서 색인](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [아키텍처 개요](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [구성, 라우팅, 명령 계약](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [저장소의 진실 유지관리](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [기여하기](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **Truthmark를 설치하고 코딩 호스트를 선택해 오늘 바로 실제 동작 하나를 문서로 바꾸세요.**

docs/readmes/README.pl.md

@@ -185,7 +185,6 @@ Strukturyzowane dane wyjściowe JSON są dostępne w całym interfejsie wiersza
 - [Indeks dokumentacji](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [Przegląd architektury](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [Kontrakty konfiguracji, routingu i poleceń](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [Utrzymywanie prawdy repozytorium](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [Współtworzenie](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **Zainstaluj Truthmark, wybierz host programistyczny i już dziś zamień jedno rzeczywiste zachowanie w dokumentację.**

docs/readmes/README.pt.md

@@ -185,7 +185,6 @@ A saída JSON estruturada está disponível em toda a interface de linha de coma
 - [Índice da documentação](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [Visão geral da arquitetura](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [Contratos de configuração, roteamento e comandos](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [Manutenção da verdade do repositório](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [Como contribuir](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **Instale o Truthmark, selecione seu host de programação e transforme hoje um comportamento real em documentação.**

docs/readmes/README.ru.md

@@ -185,7 +185,6 @@ Truthmark создан для сопровождающих и инженерны
 - [Индекс документации](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [Обзор архитектуры](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [Контракты конфигурации, маршрутизации и команд](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [Поддержание достоверности репозитория](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [Участие в разработке](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **Установите Truthmark, выберите хост разработки и уже сегодня превратите реальное поведение в документацию.**

docs/readmes/README.tr.md

@@ -185,7 +185,6 @@ Betikler ve sürekli entegrasyon için komut satırı arayüzünün tamamında y
 - [Dokümantasyon dizini](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [Mimariye genel bakış](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [Yapılandırma, yönlendirme ve komut sözleşmeleri](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [Depo gerçeğini koruma](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [Katkıda bulunma](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **Truthmark'ı kurun, kodlama ana bilgisayarınızı seçin ve gerçek bir davranışı bugün belgeye dönüştürün.**

docs/readmes/README.vi.md

@@ -185,7 +185,6 @@ Các host tác nhân được hỗ trợ:
 - [Chỉ mục tài liệu](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [Tổng quan kiến trúc](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [Hợp đồng cấu hình, định tuyến và lệnh](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [Duy trì sự thật của kho](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [Đóng góp](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **Cài đặt Truthmark, chọn host lập trình và biến một hành vi thực tế thành tài liệu ngay hôm nay.**

docs/readmes/README.zh.md

@@ -185,7 +185,6 @@ Truthmark 专为已经使用 AI 编码代理，并希望仓库事实与代码同
 - [文档索引](https://github.com/merlinhu1/truthmark/blob/main/docs/README.md)
 - [架构概览](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/architecture/overview.md)
 - [配置、路由和命令契约](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/contracts/config-route-and-check-contracts.md)
-- [维护仓库事实](https://github.com/merlinhu1/truthmark/blob/main/docs/standards/maintaining-repository-truth.md)
 - [参与贡献](https://github.com/merlinhu1/truthmark/blob/main/CONTRIBUTING.md)
 
 **立即安装 Truthmark，选择您的编码宿主，今天就把一个真实行为转化为文档。**

docs/repo/ai/agent-onboarding.md

@@ -0,0 +1,98 @@
+---
+status: active
+scope: repo-local
+doc_type: agent-guide
+last_reviewed: 2026-05-16
+source_of_truth:
+  - repo-rules.md
+  - ../../../README.md
+---
+
+# Agent Onboarding
+
+## Purpose
+
+Fast routing for agents. Repository-wide rules live in [docs/repo/ai/repo-rules.md](repo-rules.md).
+
+## Startup
+
+1. Read your agent entry point, usually [AGENTS.md](../../../AGENTS.md).
+2. Read [docs/README.md](../../README.md).
+3. Identify whether the task changes scaffold behavior, diagnostics, installed workflows, or only documentation placement.
+4. Read only the docs that govern that slice before editing code or canonical docs.
+
+## Change Routing
+
+### CLI or scaffold behavior
+
+Read:
+
+1. [docs/truthmark/engineering/architecture/overview.md](../../truthmark/engineering/architecture/overview.md)
+2. [docs/truthmark/engineering/behaviors/init-and-scaffold.md](../../truthmark/engineering/behaviors/init-and-scaffold.md)
+3. [docs/truthmark/engineering/contracts/config-route-and-check-contracts.md](../../truthmark/engineering/contracts/config-route-and-check-contracts.md)
+4. [docs/truthmark/product/capabilities/lane-separated-truth.md](../../truthmark/product/capabilities/lane-separated-truth.md)
+
+### Diagnostics, routing, or containment checks
+
+Read:
+
+1. [docs/truthmark/engineering/architecture/overview.md](../../truthmark/engineering/architecture/overview.md)
+2. [docs/truthmark/engineering/behaviors/check-diagnostics.md](../../truthmark/engineering/behaviors/check-diagnostics.md)
+3. [docs/repo/standards/documentation-governance.md](../standards/documentation-governance.md)
+4. [docs/truthmark/engineering/contracts/config-route-and-check-contracts.md](../../truthmark/engineering/contracts/config-route-and-check-contracts.md)
+
+### Installed workflow, prompt, or reporting changes
+
+Read:
+
+1. [.truthmark/config.yml](../../../.truthmark/config.yml)
+2. [docs/truthmark/product/capabilities/agent-native-workflow-injection.md](../../truthmark/product/capabilities/agent-native-workflow-injection.md)
+3. [docs/truthmark/engineering/workflows/installed-workflow-runtime.md](../../truthmark/engineering/workflows/installed-workflow-runtime.md) and [docs/truthmark/engineering/contracts/generated-host-surfaces.md](../../truthmark/engineering/contracts/generated-host-surfaces.md)
+4. [docs/repo/standards/maintaining-repository-truth.md](../standards/maintaining-repository-truth.md)
+5. The manifest, renderer, generated surfaces, and focused tests named by the workflow truth docs
+
+### Package version changes
+
+Read:
+
+1. [docs/repo/standards/versioning.md](../standards/versioning.md)
+2. [docs/repo/standards/change-notes.md](../standards/change-notes.md)
+3. [docs/repo/standards/testing-and-verification.md](../standards/testing-and-verification.md)
+
+### PR or release text
+
+Read:
+
+1. [docs/repo/standards/change-notes.md](../standards/change-notes.md)
+2. [docs/repo/standards/versioning.md](../standards/versioning.md), only when package version changes are in scope
+
+### Documentation structure or policy changes
+
+Read:
+
+1. [docs/README.md](../../README.md)
+2. [docs/repo/standards/documentation-governance.md](../standards/documentation-governance.md)
+3. [docs/repo/standards/maintaining-repository-truth.md](../standards/maintaining-repository-truth.md)
+
+## Agent Rules
+
+Do:
+
+- treat [docs/repo/ai/repo-rules.md](repo-rules.md) as the primary authority for repository-wide rules
+- route code changes to the nearest maintained architecture, contract, and truth docs
+- update [docs/truthmark/routes/areas.md](../../truthmark/routes/areas.md) when canonical routing changes
+- apply [docs/repo/standards/versioning.md](../standards/versioning.md) before changing or accepting a package version
+- write `changes/` notes from [docs/repo/standards/change-notes.md](../standards/change-notes.md) when PR or release text is needed
+- preserve the generated Truthmark block in [AGENTS.md](../../../AGENTS.md) unless the template behavior itself is changing
+- keep non-canonical planning notes separate from current-state docs
+
+Do not:
+
+- treat [README.md](../../README.md) as the final source of behavioral truth
+- invent unimplemented commands such as a current `truthmark realize` CLI command
+- leave routing broad when you can point to a smaller maintained truth surface
+- rewrite functional code during documentation-only tasks
+
+## Verification
+
+Use [docs/repo/standards/testing-and-verification.md](../standards/testing-and-verification.md) for commands and [docs/repo/standards/pre-completion-checklist.md](../standards/pre-completion-checklist.md) as the completion gate.

docs/repo/ai/repo-rules.md

@@ -1,35 +1,46 @@
 ---
 status: active
+scope: repo-local
 doc_type: agent-rules
-last_reviewed: 2026-06-12
+last_reviewed: 2026-08-23
 source_of_truth:
-  - ../../AGENTS.md
-  - ../README.md
+  - ../../../AGENTS.md
+  - ../../../README.md
   - ../architecture/product-boundary.md
 ---
 
 # Repository Rules
 
-Repository-wide agent authority, routing, and completion rules. Read the smallest sufficient set; detailed behavior lives in [docs/](../README.md).
+Repository-wide agent authority, routing, and completion rules. Read the smallest sufficient set; detailed behavior lives in [docs/](../../README.md).
+
+<!-- always-on:start -->
 
 ## Authority
 
 Conflict order:
 
-1. this file
-2. [.truthmark/config.yml](../../.truthmark/config.yml)
-3. [docs/truthmark/routes/areas.md](../truthmark/routes/areas.md) and `docs/truthmark/routes/areas/**/*.md`
-4. `docs/standards/**/*.md`
-5. `docs/architecture/**/*.md`
+1. this file (`docs/repo/ai/repo-rules.md`)
+2. [.truthmark/config.yml](../../../.truthmark/config.yml)
+3. [docs/truthmark/routes/areas.md](../../truthmark/routes/areas.md) and `docs/truthmark/routes/areas/**/*.md`
+4. `docs/repo/standards/**/*.md`
+5. `docs/repo/architecture/**/*.md`
 6. `docs/truthmark/product/**/*.md` and `docs/truthmark/engineering/**/*.md`
 
 Authoritative context is the current checkout plus user-provided session context; chat, external notes, and off-repo memory are non-authoritative unless committed or supplied now.
 
 Code is the implementation. On code/doc conflict, inspect code, decide whether code is intentional or docs are stale, update stale docs for intentional behavior, and change code to match docs only when requested or required.
 
+## Documentation Scope
+
+Everything under `docs/repo/**` is repo-local policy for developing Truthmark itself. It ships to nobody, `src/**` never references it, and it is not a downstream scaffold, generated surface, or required artifact for repositories that install Truthmark. Repo-local docs declare `scope: repo-local` and use `doc_type`, never `truth_kind`.
+
+Everything else under `docs/**` describes the installed product. `docs/truthmark/**` is this repository dogfooding the same truth schema `truthmark init` scaffolds downstream, so it is evidence about the product; `docs/repo/**` is not.
+
+When answering a question or making a claim about the product's schema, lanes, commands, or installed surfaces, cite `src/**`, `docs/truthmark/**`, or generated host surfaces. A repo-local doc is never evidence for what downstream repositories get. [tests/doc-scope.test.ts](../../../tests/doc-scope.test.ts) enforces this boundary.
+
 ## Product Boundary
 
-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.
+The canonical product boundary is [docs/repo/architecture/product-boundary.md](../architecture/product-boundary.md), which is repo-local under the rule above. 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 `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.
 
@@ -38,7 +49,7 @@ Agents inspect the active checkout directly. There is no daemon, database, remot
 ## Rules
 
 1. Workflow and skill quality, performance, dispatch clarity, and agent effectiveness are the highest-priority repo concerns. Treat workflows and skills as the core product surface of this agent-native project; when tradeoffs conflict, optimize them before secondary structure, convenience, or polish.
-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.
+2. Product boundaries are mandatory design inputs. Before generating a new design or plan, read [docs/repo/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. 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.
@@ -55,11 +66,20 @@ Agents inspect the active checkout directly. There is no daemon, database, remot
 
 ## Instruction Surface Boundary
 
-In `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`, only text between `<!-- truthmark:start -->` and `<!-- truthmark:end -->` is the generated Truthmark workflow surface. Repo-local preamble outside those markers should delegate to this file and conditional routing docs, not duplicate completion policy. Do not put this repository's internal policy, completion gates, or maintainer-only standards inside marker-delimited blocks, package templates, installed workflow skills, prompts, or downstream scaffold output.
+`AGENTS.md` and `CLAUDE.md` carry two generated regions, and neither is hand-edited:
+
+- the `truthmark:start` / `truthmark:end` comment markers wrap the Truthmark workflow surface, refreshed by `truthmark init`
+- the `repo-rules:start` / `repo-rules:end` comment markers wrap this file's always-on section, rendered locally with `node --import tsx scripts/render-repo-rules.ts`
+
+Marker names appear here without their comment syntax on purpose: a literal marker inside the rendered region would duplicate it in the instruction files and make the managed block unparseable.
+
+This file stays the authority; the rendered region is generated output under rule 8. Change policy here and re-render. Hand-written preamble outside both regions stays short and delegates rather than restating policy. Do not put this repository's internal policy, completion gates, or maintainer-only standards inside the Truthmark managed block, package templates, installed workflow skills, prompts, or downstream scaffold output.
 
 ## Completion Gate
 
-Before declaring changed repository work complete, apply [docs/standards/pre-completion-checklist.md](../standards/pre-completion-checklist.md) and [docs/standards/testing-and-verification.md](../standards/testing-and-verification.md). Skip this gate only for read-only or no-file-change sessions, and state the skip reason when completion or verification would otherwise be expected.
+Before declaring changed repository work complete, apply [docs/repo/standards/pre-completion-checklist.md](../standards/pre-completion-checklist.md) and [docs/repo/standards/testing-and-verification.md](../standards/testing-and-verification.md). Skip this gate only for read-only or no-file-change sessions, and state the skip reason when completion or verification would otherwise be expected.
+
+<!-- always-on:end -->
 
 ## Routing
 

docs/repo/architecture/product-boundary.md

@@ -1,13 +1,14 @@
 ---
 status: active
+scope: repo-local
 doc_type: architecture
 last_reviewed: 2026-07-30
 source_of_truth:
-  - ../../README.md
-  - ../truthmark/product/capabilities/agent-native-workflow-injection.md
-  - ../truthmark/product/capabilities/lane-separated-truth.md
-  - ../truthmark/engineering/architecture/overview.md
-  - ../truthmark/engineering/workflows/installed-workflow-runtime.md
+  - ../../../README.md
+  - ../../truthmark/product/capabilities/agent-native-workflow-injection.md
+  - ../../truthmark/product/capabilities/lane-separated-truth.md
+  - ../../truthmark/engineering/architecture/overview.md
+  - ../../truthmark/engineering/workflows/installed-workflow-runtime.md
 ---
 
 # Truthmark Product Boundary

docs/repo/research/2026-05-14-repoagent-ai-doc-gen-truthmark-comparison.md

@@ -1,3 +1,9 @@
+---
+status: non-canonical
+scope: repo-local
+doc_type: research
+---
+
 # RepoAgent, ai-doc-gen, and TruthMark
 
 Focused product and implementation comparison for improving TruthMark.

docs/repo/research/2026-05-15-agent-skills-workflow-review.md

@@ -1,23 +1,29 @@
+---
+status: non-canonical
+scope: repo-local
+doc_type: research
+---
+
 # Agent Skills Workflow Review
 
 Status: research reference
 Date: 2026-05-15
 Audience: Truthmark maintainers
 
-This is a non-canonical research reference. It summarizes external skill-authoring guidance reviewed on 2026-05-15 and applies it to Truthmark's installed project workflows. It must not be treated as current Truthmark behavior unless the behavior-bearing parts are promoted into [workflow overview](../docs/truth/workflows/overview.md), the bounded workflow truth docs under `docs/truth/workflows/`, the workflow manifest, renderers, and tests.
+This is a non-canonical research reference. It summarizes external skill-authoring guidance reviewed on 2026-05-15 and applies it to Truthmark's installed project workflows. It must not be treated as current Truthmark behavior unless the behavior-bearing parts are promoted into [installed workflow runtime](../../truthmark/engineering/workflows/installed-workflow-runtime.md), the workflow manifest, renderers, and tests.
 
 Checkout references:
 
-- [docs/ai/repo-rules.md](../docs/ai/repo-rules.md)
-- [docs/truth/workflows/overview.md](../docs/truth/workflows/overview.md)
-- [docs/truth/workflows/shared-gates.md](../docs/truth/workflows/shared-gates.md)
-- [src/agents/workflow-manifest.ts](../src/agents/workflow-manifest.ts)
-- [src/templates/workflow-surfaces.ts](../src/templates/workflow-surfaces.ts)
-- [.codex/skills/truthmark-sync/SKILL.md](../.codex/skills/truthmark-sync/SKILL.md)
-- [.codex/skills/truthmark-structure/SKILL.md](../.codex/skills/truthmark-structure/SKILL.md)
-- [.codex/skills/truthmark-document/SKILL.md](../.codex/skills/truthmark-document/SKILL.md)
-- [.codex/skills/truthmark-realize/SKILL.md](../.codex/skills/truthmark-realize/SKILL.md)
-- [.codex/skills/truthmark-check/SKILL.md](../.codex/skills/truthmark-check/SKILL.md)
+- [docs/repo/ai/repo-rules.md](../ai/repo-rules.md)
+- [docs/truthmark/engineering/workflows/installed-workflow-runtime.md](../../truthmark/engineering/workflows/installed-workflow-runtime.md)
+- [src/agents/workflow-manifest.ts](../../../src/agents/workflow-manifest.ts)
+- [src/agents/shared.ts](../../../src/agents/shared.ts)
+- [src/templates/workflow-surfaces.ts](../../../src/templates/workflow-surfaces.ts)
+- [.agents/skills/truthmark-sync/SKILL.md](../../../.agents/skills/truthmark-sync/SKILL.md)
+- [.agents/skills/truthmark-structure/SKILL.md](../../../.agents/skills/truthmark-structure/SKILL.md)
+- [.agents/skills/truthmark-document/SKILL.md](../../../.agents/skills/truthmark-document/SKILL.md)
+- [.agents/skills/truthmark-realize/SKILL.md](../../../.agents/skills/truthmark-realize/SKILL.md)
+- [.agents/skills/truthmark-check/SKILL.md](../../../.agents/skills/truthmark-check/SKILL.md)
 
 External sources reviewed:
 
@@ -79,7 +85,7 @@ Truthmark currently installs five workflows across host-specific surfaces:
 | `truthmark-realize` | Realize truth docs into functional code | `allow_implicit_invocation: false` |
 | `truthmark-check` | Audit repository truth health | `allow_implicit_invocation: false` |
 
-Generated runtime surfaces include `.codex/skills/`, `.codex/agents/`, `.claude/skills/`, `.opencode/skills/`, `.opencode/agents/`, `.github/prompts/`, `.github/agents/`, `.gemini/commands/truthmark/`, and compact managed instruction blocks in files such as `AGENTS.md`.
+Generated runtime surfaces include `.agents/skills/`, `.codex/agents/`, `.claude/skills/`, `.claude/agents/`, `.opencode/skills/`, `.opencode/agents/`, `.cursor/skills/`, `.antigravity/rules/`, and compact managed instruction blocks in files such as `AGENTS.md`.
 
 Current strengths:
 

docs/repo/research/2026-05-16-write-capable-opencode-subagents-design.md

@@ -1,3 +1,9 @@
+---
+status: non-canonical
+scope: repo-local
+doc_type: research
+---
+
 # Write-Capable OpenCode Subagents Design
 
 Status: proposed review draft

docs/repo/research/2026-06-01-openspec-comparison.md

@@ -1,3 +1,9 @@
+---
+status: non-canonical
+scope: repo-local
+doc_type: research
+---
+
 # Truthmark × OpenSpec Deep Behavioral Research
 
 Date: 2026-06-01  

docs/repo/research/2026-06-29-manual-agent-skill-quality-eval-framework.md

@@ -1,12 +1,13 @@
 ---
 status: draft
+scope: repo-local
 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
+  - ../../../workflow-eval-framwork/README.md
+  - ../../../workflow-eval-framwork/catalog.yaml
+  - ../../../scripts/workflow-eval-framwork/run-agent-scenario.mjs
+  - ../../../tests/evals/workflow-routing-cases.ts
 ---
 
 # Manual Agent Skill And Prompt Quality Eval Framework
@@ -15,10 +16,10 @@ 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)
+- 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)
+- Routing case fixtures: [`tests/evals/workflow-routing-cases.ts`](../../../tests/evals/workflow-routing-cases.ts)
 
 The requested framework folder name is intentionally spelled `workflow-eval-framwork`.
 

docs/repo/research/prompt-skill-agent-workflow-literature-review-2026-05-16.md

@@ -1,3 +1,9 @@
+---
+status: non-canonical
+scope: repo-local
+doc_type: research
+---
+
 # Prompt, Skill, Agent, and Workflow Literature Review
 
 ## Status

docs/repo/research/prompt-skill-agent-workflow-quality-uplift-review.md

@@ -1,3 +1,9 @@
+---
+status: non-canonical
+scope: repo-local
+doc_type: research
+---
+
 # Truthmark Prompt, Skill, Agent, and Workflow Quality Uplift Review
 
 Intended commit path: `docs/research/prompt-skill-agent-workflow-quality-uplift-review.md`

docs/repo/research/truthmark_competitive_research_report_2026-05-15.md

@@ -1,3 +1,9 @@
+---
+status: non-canonical
+scope: repo-local
+doc_type: research
+---
+
 # TruthMark Competitive Research Report
 
 Status judgments are as of **2026-05-15**. This report treats TruthMark as a Git-native truth/workflow product, not as a generic documentation generator.

docs/repo/standards/change-notes.md

@@ -1,5 +1,6 @@
 ---
 status: active
+scope: repo-local
 doc_type: standard
 last_reviewed: 2026-05-16
 source_of_truth:

docs/repo/standards/default-principles.md

@@ -1,9 +1,10 @@
 ---
 status: active
+scope: repo-local
 doc_type: standard
 last_reviewed: 2026-07-30
 source_of_truth:
-  - ../README.md
+  - ../../../README.md
   - documentation-governance.md
 ---
 
@@ -40,7 +41,7 @@ These are bootstrap defaults, not immutable law. Repositories should replace or
 - 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.
 
-See [docs/standards/documentation-governance.md](documentation-governance.md) for the governance baseline.
+See [docs/repo/standards/documentation-governance.md](documentation-governance.md) for the governance baseline.
 
 ### Verification Discipline
 

docs/repo/standards/documentation-governance.md

@@ -1,9 +1,10 @@
 ---
 status: active
+scope: repo-local
 doc_type: standard
 last_reviewed: 2026-07-30
 source_of_truth:
-  - ../README.md
+  - ../../../README.md
   - ../ai/repo-rules.md
 ---
 
@@ -15,7 +16,7 @@ This standard defines the documentation-governance rules Truthmark itself follow
 
 Projects may adapt the exact directory layout, but the rules below are the reusable core that makes branch-local truth routing work.
 
-For the broader reusable baseline beyond documentation governance, see `docs/standards/default-principles.md`.
+For the broader reusable baseline beyond documentation governance, see `docs/repo/standards/default-principles.md`.
 
 Small repositories are in scope. A project does not need a large documentation program to benefit from Truthmark. It needs only a small canonical truth surface, clear ownership, and a willingness to improve routing quality over time.
 
@@ -43,10 +44,10 @@ Small repositories are in scope. A project does not need a large documentation p
 
 Truthmark's minimal canonical surface is:
 
-- `docs/ai/repo-rules.md` as the repository-wide agent policy source
+- `docs/repo/ai/repo-rules.md` as the repository-wide agent policy source
 - `.truthmark/config.yml` as the committed hierarchy contract
 - `docs/truthmark/routes/areas.md` as the primary routing surface
-- the project's canonical docs under directories such as `docs/standards/`, `docs/architecture/`, `docs/truthmark/product/`, and `docs/truthmark/engineering/`
+- the project's canonical docs under directories such as `docs/repo/standards/`, `docs/repo/architecture/`, `docs/truthmark/product/`, and `docs/truthmark/engineering/`
 
 By default, instruction files such as `AGENTS.md` install workflow behavior. They do not outrank the canonical truth surface unless a project opts into that explicitly.
 

docs/repo/standards/maintaining-repository-truth.md

@@ -1,9 +1,10 @@
 ---
 status: active
+scope: repo-local
 doc_type: guide
 last_reviewed: 2026-05-09
 source_of_truth:
-  - ../README.md
+  - ../../../README.md
   - documentation-governance.md
   - testing-and-verification.md
 ---
@@ -16,14 +17,14 @@ This guide is for humans maintaining Truthmark's own docs tree.
 
 ## When To Update Which Docs
 
-- Change to scaffolded files or AGENTS management: update [docs/truthmark/engineering/behaviors/init-and-scaffold.md](../truthmark/engineering/behaviors/init-and-scaffold.md)
-- Change to diagnostics, routing, containment, or branch scope: update [docs/truthmark/engineering/behaviors/check-diagnostics.md](../truthmark/engineering/behaviors/check-diagnostics.md)
-- Change to installed workflow text, skip reasons, report shape, or ownership gates: update [docs/truthmark/product/capabilities/agent-native-workflow-injection.md](../truthmark/product/capabilities/agent-native-workflow-injection.md), [docs/truthmark/engineering/workflows/installed-workflow-runtime.md](../truthmark/engineering/workflows/installed-workflow-runtime.md), and the relevant bounded engineering workflow or generated-surface doc
-- Change to repository-wide rules or completion policy: update [docs/ai/repo-rules.md](../ai/repo-rules.md) or the relevant standard
+- Change to scaffolded files or AGENTS management: update [docs/truthmark/engineering/behaviors/init-and-scaffold.md](../../truthmark/engineering/behaviors/init-and-scaffold.md)
+- Change to diagnostics, routing, containment, or branch scope: update [docs/truthmark/engineering/behaviors/check-diagnostics.md](../../truthmark/engineering/behaviors/check-diagnostics.md)
+- Change to installed workflow text, skip reasons, report shape, or ownership gates: update [docs/truthmark/product/capabilities/agent-native-workflow-injection.md](../../truthmark/product/capabilities/agent-native-workflow-injection.md), [docs/truthmark/engineering/workflows/installed-workflow-runtime.md](../../truthmark/engineering/workflows/installed-workflow-runtime.md), and the relevant bounded engineering workflow or generated-surface doc
+- Change to repository-wide rules or completion policy: update [docs/repo/ai/repo-rules.md](../ai/repo-rules.md) or the relevant standard
 
 ## Maintaining AGENTS.md
 
-Treat [AGENTS.md](../../AGENTS.md) as two surfaces:
+Treat [AGENTS.md](../../../AGENTS.md) as two surfaces:
 
 - manual repository-specific guidance outside the managed block
 - the generated Truthmark block between `<!-- truthmark:start -->` and `<!-- truthmark:end -->`
@@ -40,7 +41,7 @@ When code boundaries or canonical docs change:
 2. narrow overly broad truth-doc lists instead of adding more shadow docs
 3. make sure every relevant `src/**` file still matches at least one area mapping
 
-With hierarchical routing, treat [docs/truthmark/routes/areas.md](../truthmark/routes/areas.md) as the root route index and `docs/truthmark/routes/areas/**/*.md` as the delegated child route files. Keep delegation to one level.
+With hierarchical routing, treat [docs/truthmark/routes/areas.md](../../truthmark/routes/areas.md) as the root route index and `docs/truthmark/routes/areas/**/*.md` as the delegated child route files. Keep delegation to one level.
 
 ## Changing Hierarchy
 
@@ -69,4 +70,4 @@ If a historical note becomes current truth, rewrite it into the correct canonica
 
 ## Verification
 
-Run [docs/standards/testing-and-verification.md](../standards/testing-and-verification.md) commands appropriate to the change. For docs-only routing work, `npm run dev -- check` is the default validation step.
+Run [docs/repo/standards/testing-and-verification.md](../standards/testing-and-verification.md) commands appropriate to the change. For docs-only routing work, `npm run dev -- check` is the default validation step.

docs/repo/standards/pre-completion-checklist.md

@@ -1,5 +1,6 @@
 ---
 status: active
+scope: repo-local
 doc_type: standard
 last_reviewed: 2026-05-13
 source_of_truth:
@@ -21,10 +22,10 @@ Use this checklist before declaring Truthmark work complete.
 - If behavior, contracts, or workflow text changed, did the nearest canonical docs change in the same working change?
 - If this was a major product, onboarding, install, command, positioning, or workflow change, did you review the root [README.md](../../README.md) and update stale user-facing claims, examples, or command sequences?
 - If the root README changed materially, did the localized README variants change in the same working change? If not, stop unless you have an explicit repo-authorized reason they intentionally remain different, and state that reason. A passing verification command does not waive this gate.
-- If canonical routing changed, did [docs/truthmark/routes/areas.md](../truthmark/routes/areas.md) change too?
-- If the change is PR-worthy, release-worthy, or changes the package version, did you add or update a `changes/` note using [docs/standards/change-notes.md](change-notes.md)?
-- If any package version or release/version policy changed, did you apply [docs/standards/versioning.md](versioning.md) before accepting the version?
-- If [AGENTS.md](../../AGENTS.md) changed, did manual edits stay outside the managed Truthmark block?
-- Did you run the narrowest meaningful verification command from [docs/standards/testing-and-verification.md](testing-and-verification.md)?
+- If canonical routing changed, did [docs/truthmark/routes/areas.md](../../truthmark/routes/areas.md) change too?
+- If the change is PR-worthy, release-worthy, or changes the package version, did you add or update a `changes/` note using [docs/repo/standards/change-notes.md](change-notes.md)?
+- If any package version or release/version policy changed, did you apply [docs/repo/standards/versioning.md](versioning.md) before accepting the version?
+- If [AGENTS.md](../../../AGENTS.md) changed, did manual edits stay outside the managed Truthmark block?
+- Did you run the narrowest meaningful verification command from [docs/repo/standards/testing-and-verification.md](testing-and-verification.md)?
 - If a normally expected verification step was skipped, did you state the reason explicitly?
 - If the task was documentation-only, did you confirm whether Truth Sync should be skipped rather than run?

docs/repo/standards/template-standards.md

@@ -1,5 +1,6 @@
 ---
 status: active
+scope: repo-local
 doc_type: standard
 last_reviewed: 2026-05-30
 source_of_truth:
@@ -98,4 +99,4 @@ Truthmark defaults are justified because they optimize for the reviewable artifa
 
 Update this standard when Truthmark adds, removes, renames, or materially changes default truth-document templates, or when the references behind the default template rationale change.
 
-When changing default template content, keep `docs/truthmark/templates/*.md`, `src/templates/init-files.ts`, `docs/standards/default-principles.md`, and this standard aligned.
+When changing default template content, keep `docs/truthmark/templates/*.md`, `src/templates/init-files.ts`, `docs/repo/standards/default-principles.md`, and this standard aligned.

docs/repo/standards/testing-and-verification.md

@@ -1,10 +1,11 @@
 ---
 status: active
+scope: repo-local
 doc_type: standard
 last_reviewed: 2026-05-13
 source_of_truth:
-  - ../../package.json
-  - ../truthmark/engineering/contracts/config-route-and-check-contracts.md
+  - ../../../package.json
+  - ../../truthmark/engineering/contracts/config-route-and-check-contracts.md
   - versioning.md
 ---
 
@@ -16,7 +17,7 @@ This standard defines the canonical verification commands for Truthmark.
 
 ## Command Sources
 
-Repository-level verification commands live in [package.json](../../package.json).
+Repository-level verification commands live in [package.json](../../../package.json).
 
 Current commands:
 

docs/repo/standards/versioning.md

@@ -1,10 +1,11 @@
 ---
 status: active
+scope: repo-local
 doc_type: standard
 last_reviewed: 2026-05-16
 source_of_truth:
-  - ../../package.json
-  - ../../package-lock.json
+  - ../../../package.json
+  - ../../../package-lock.json
   - change-notes.md
   - https://semver.org/
 ---

docs/user-guide.md

@@ -500,7 +500,6 @@ Detailed current behavior lives under `docs/`:
 - [Init and scaffold behavior](truthmark/engineering/behaviors/init-and-scaffold.md)
 - [Check diagnostics](truthmark/engineering/behaviors/check-diagnostics.md)
 - [Installed workflows](truthmark/engineering/workflows/installed-workflow-runtime.md)
-- [Repository truth maintenance guide](standards/maintaining-repository-truth.md)
 
 ## Design boundaries
 

package-lock.json

@@ -2315,9 +2315,9 @@
       "license": "MIT"
     },
     "node_modules/fast-uri": {
-      "version": "3.1.5",
-      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.5.tgz",
-      "integrity": "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==",
+      "version": "3.1.4",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.4.tgz",
+      "integrity": "sha512-8JnbkQ4juDyvYs4mgFGQqg4yCYtFDtUtmp2QIQq11ZZe5CFQ5wcqm1rqDgAh/QdMySuBnPzMUiJUNZG5N/AiQw==",
       "funding": [
         {
           "type": "github",
@@ -2762,9 +2762,9 @@
       "license": "MIT"
     },
     "node_modules/js-yaml": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.1.tgz",
-      "integrity": "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==",
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.0.tgz",
+      "integrity": "sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==",
       "dev": true,
       "funding": [
         {

scripts/render-repo-rules.ts

@@ -0,0 +1,25 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import {
+  INSTRUCTION_FILES,
+  renderRepoRulesBlock,
+  upsertRepoRulesBlock,
+} from "./repo-rules-block.js";
+
+const rootDir = process.cwd();
+const block = renderRepoRulesBlock(rootDir);
+
+for (const instructionFile of INSTRUCTION_FILES) {
+  const filePath = path.join(rootDir, instructionFile);
+  const existing = readFileSync(filePath, "utf8");
+  const updated = upsertRepoRulesBlock(existing, block);
+
+  if (updated === existing) {
+    console.log(`unchanged ${instructionFile}`);
+    continue;
+  }
+
+  writeFileSync(filePath, updated);
+  console.log(`updated   ${instructionFile}`);
+}

scripts/repo-rules-block.ts

@@ -0,0 +1,138 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Renders the always-on subset of docs/repo/ai/repo-rules.md into the
+ * repo-local managed region carried by AGENTS.md and CLAUDE.md.
+ *
+ * This is repo-local tooling, not part of the shipped product. The source doc
+ * stays the authority; the region in each instruction file is generated output.
+ */
+
+export const REPO_RULES_SOURCE = "docs/repo/ai/repo-rules.md";
+export const REPO_RULES_BLOCK_START = "<!-- repo-rules:start -->";
+export const REPO_RULES_BLOCK_END = "<!-- repo-rules:end -->";
+export const INSTRUCTION_FILES = ["AGENTS.md", "CLAUDE.md"];
+
+const ALWAYS_ON_START = "<!-- always-on:start -->";
+const ALWAYS_ON_END = "<!-- always-on:end -->";
+const GENERATED_NOTICE = `<!-- Generated from ${REPO_RULES_SOURCE} by \`node --import tsx scripts/render-repo-rules.ts\`. Edit the source doc, not this block. -->`;
+
+const sourceDir = path.posix.dirname(REPO_RULES_SOURCE);
+
+const normalizeLineEndings = (content: string): string =>
+  content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+
+const lineEndingFor = (content: string): "\n" | "\r\n" =>
+  content.includes("\r\n") ? "\r\n" : "\n";
+
+const withLineEnding = (content: string, lineEnding: "\n" | "\r\n"): string =>
+  normalizeLineEndings(content).replace(/\n/g, lineEnding);
+
+/**
+ * Rewrites links that were relative to the source doc so they resolve from the
+ * repository root, where the instruction files live.
+ */
+const rewriteRelativeLinks = (markdown: string): string => {
+  return markdown.replace(
+    /\[([^\]]*)\]\(([^)]+)\)/g,
+    (match, label: string, target: string) => {
+      const trimmed = target.trim();
+
+      if (/^(https?:|mailto:|#)/.test(trimmed)) {
+        return match;
+      }
+
+      return `[${label}](${path.posix.normalize(path.posix.join(sourceDir, trimmed))})`;
+    },
+  );
+};
+
+export const renderRepoRulesBlock = (rootDir: string): string => {
+  const source = readFileSync(path.join(rootDir, REPO_RULES_SOURCE), "utf8");
+  const start = source.indexOf(ALWAYS_ON_START);
+  const end = source.indexOf(ALWAYS_ON_END);
+
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error(
+      `${REPO_RULES_SOURCE} must contain ${ALWAYS_ON_START} before ${ALWAYS_ON_END}.`,
+    );
+  }
+
+  const alwaysOn = source.slice(start + ALWAYS_ON_START.length, end).trim();
+
+  return [
+    REPO_RULES_BLOCK_START,
+    GENERATED_NOTICE,
+    "",
+    rewriteRelativeLinks(alwaysOn),
+    "",
+    REPO_RULES_BLOCK_END,
+  ].join("\n");
+};
+
+const countOccurrences = (content: string, marker: string): number => {
+  return content.split(marker).length - 1;
+};
+
+/**
+ * Mirrors src/managed-block.ts: a duplicated marker means the region cannot be
+ * replaced safely, so fail loudly instead of corrupting the file.
+ */
+export const extractRepoRulesBlock = (content: string): string | null => {
+  const starts = countOccurrences(content, REPO_RULES_BLOCK_START);
+  const ends = countOccurrences(content, REPO_RULES_BLOCK_END);
+
+  if (starts === 0 && ends === 0) {
+    return null;
+  }
+
+  if (starts !== 1 || ends !== 1) {
+    throw new Error(
+      `Repo-local rules markers are malformed: found ${starts} start and ${ends} end markers.`,
+    );
+  }
+
+  const start = content.indexOf(REPO_RULES_BLOCK_START);
+  const end = content.indexOf(REPO_RULES_BLOCK_END);
+
+  if (end < start) {
+    throw new Error("Repo-local rules end marker precedes its start marker.");
+  }
+
+  return content.slice(start, end + REPO_RULES_BLOCK_END.length);
+};
+
+export const upsertRepoRulesBlock = (
+  existingContent: string,
+  block: string,
+): string => {
+  const current = extractRepoRulesBlock(existingContent);
+
+  if (current !== null) {
+    if (normalizeLineEndings(current) === normalizeLineEndings(block)) {
+      return existingContent;
+    }
+
+    return existingContent.replace(
+      current,
+      withLineEnding(block, lineEndingFor(existingContent)),
+    );
+  }
+
+  const lineEnding = lineEndingFor(existingContent);
+  const renderedBlock = withLineEnding(block, lineEnding);
+
+  const truthmarkStart = existingContent.indexOf("<!-- truthmark:start -->");
+
+  if (truthmarkStart === -1) {
+    return `${existingContent.replace(/(?:\r\n|\r|\n)+$/u, "")}${lineEnding}${lineEnding}${renderedBlock}${lineEnding}`;
+  }
+
+  const before = existingContent
+    .slice(0, truthmarkStart)
+    .replace(/(?:\r\n|\r|\n)+$/u, "");
+  const after = existingContent.slice(truthmarkStart);
+
+  return `${before}${lineEnding}${lineEnding}${renderedBlock}${lineEnding}${lineEnding}${after}`;
+};

tests/doc-scope.test.ts

@@ -0,0 +1,120 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import fg from "fast-glob";
+import { describe, it } from "node:test";
+import { expect } from "expect";
+
+import { parseFrontmatter } from "../src/markdown/frontmatter.js";
+import { resolveRepoPath } from "../src/fs/paths.js";
+import { normalizeSourceReferencePath } from "../src/truth/source-references.js";
+
+const REPO_LOCAL_ROOT = "docs/repo";
+
+const markdownFilesUnder = (relativeDir: string): string[] => {
+  return readdirSync(join(process.cwd(), relativeDir), { recursive: true })
+    .map((entry) => String(entry).replaceAll("\\", "/"))
+    .filter((entry) => entry.endsWith(".md"))
+    .map((entry) => `${relativeDir}/${entry}`)
+    .sort();
+};
+
+const frontmatterOf = (relativePath: string) => {
+  const source = readFileSync(join(process.cwd(), relativePath), "utf8");
+  return parseFrontmatter(source).data;
+};
+
+const publishedMarkdownFiles = (): string[] =>
+  markdownFilesUnder("docs").filter(
+    (relativePath) =>
+      relativePath !== REPO_LOCAL_ROOT &&
+      !relativePath.startsWith(`${REPO_LOCAL_ROOT}/`),
+  );
+
+describe("repo-local documentation scope", () => {
+  it("declares repo-local scope on every doc under docs/repo", () => {
+    const missingScope = markdownFilesUnder(REPO_LOCAL_ROOT).filter(
+      (relativePath) => frontmatterOf(relativePath).scope !== "repo-local",
+    );
+
+    expect(missingScope).toEqual([]);
+  });
+
+  it("keeps repo-local scope out of published product documentation", () => {
+    const leaked = publishedMarkdownFiles().filter(
+      (relativePath) => frontmatterOf(relativePath).scope === "repo-local",
+    );
+
+    expect(leaked).toEqual([]);
+  });
+
+  it("keeps repo-local source_of_truth references valid", async () => {
+    const missing: string[] = [];
+
+    for (const relativePath of markdownFilesUnder(REPO_LOCAL_ROOT)) {
+      const entries = parseFrontmatter(
+        readFileSync(join(process.cwd(), relativePath), "utf8"),
+      ).data.source_of_truth;
+
+      if (!Array.isArray(entries)) {
+        continue;
+      }
+
+      for (const entry of entries) {
+        if (typeof entry !== "string") {
+          continue;
+        }
+
+        if (/^(?:https?|mailto):/u.test(entry)) {
+          continue;
+        }
+
+        const reference = normalizeSourceReferencePath(relativePath, entry);
+        const hasGlobSyntax = ["*", "?", "[", "]", "{", "}", "(", ")"].some(
+          (character) => reference.includes(character),
+        );
+        const matches = hasGlobSyntax
+          ? await fg(reference, {
+              cwd: process.cwd(),
+              dot: true,
+              onlyFiles: true,
+              followSymbolicLinks: false,
+            })
+          : existsSync(resolveRepoPath(process.cwd(), reference))
+            ? [reference]
+            : [];
+
+        if (matches.length === 0) {
+          missing.push(`${relativePath}: ${entry}`);
+        }
+      }
+    }
+
+    expect(missing).toEqual([]);
+  });
+
+  it("keeps product truth-doc vocabulary out of repo-local policy docs", () => {
+    const usingTruthKind = markdownFilesUnder(REPO_LOCAL_ROOT).filter(
+      (relativePath) => typeof frontmatterOf(relativePath).truth_kind === "string",
+    );
+
+    expect(usingTruthKind).toEqual([]);
+  });
+
+  it("keeps repo-local documentation out of the shipped product source", () => {
+    const sourceFiles = readdirSync(join(process.cwd(), "src"), {
+      recursive: true,
+    })
+      .map((entry) => String(entry).replaceAll("\\", "/"))
+      .filter((entry) => entry.endsWith(".ts"))
+      .map((entry) => `src/${entry}`)
+      .sort();
+    const referencingRepoLocalDocs = sourceFiles.filter((relativePath) =>
+      readFileSync(join(process.cwd(), relativePath), "utf8").includes(
+        REPO_LOCAL_ROOT,
+      ),
+    );
+
+    expect(referencingRepoLocalDocs).toEqual([]);
+  });
+});

tests/product-boundary.test.ts

@@ -7,7 +7,7 @@ import { expect } from "expect";
 describe("Truthmark product boundary", () => {
   it("keeps spec/proposal lifecycle and workflow-engine drift out of scope", () => {
     const productBoundary = readFileSync(
-      join(process.cwd(), "docs/architecture/product-boundary.md"),
+      join(process.cwd(), "docs/repo/architecture/product-boundary.md"),
       "utf8",
     );
 

tests/repo-rules-block.test.ts

@@ -0,0 +1,106 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { describe, it } from "node:test";
+import { expect } from "expect";
+
+import { createDefaultConfig } from "../src/config/defaults.js";
+import { upsertManagedBlock } from "../src/managed-block.js";
+import { renderAgentsBlock } from "../src/templates/agents-block.js";
+import {
+  INSTRUCTION_FILES,
+  REPO_RULES_BLOCK_END,
+  REPO_RULES_BLOCK_START,
+  extractRepoRulesBlock,
+  renderRepoRulesBlock,
+  upsertRepoRulesBlock,
+} from "../scripts/repo-rules-block.js";
+
+const readInstructionFile = (relativePath: string): string => {
+  return readFileSync(join(process.cwd(), relativePath), "utf8");
+};
+
+const normalizeLineEndings = (content: string): string =>
+  content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+
+describe("repo-local rules block", () => {
+  it("keeps every instruction file in sync with the source doc", () => {
+    const expected = renderRepoRulesBlock(process.cwd());
+    const stale = INSTRUCTION_FILES.filter(
+      (instructionFile) =>
+        normalizeLineEndings(extractRepoRulesBlock(readInstructionFile(instructionFile)) ?? "") !==
+        expected,
+    );
+
+    expect(stale).toEqual([]);
+  });
+
+  it("keeps the instruction files identical to each other", () => {
+    const contents = INSTRUCTION_FILES.map((instructionFile) =>
+      readInstructionFile(instructionFile),
+    );
+
+    expect(new Set(contents.map(normalizeLineEndings)).size).toBe(1);
+  });
+
+  it("places the repo-local region before the Truthmark managed block", () => {
+    for (const instructionFile of INSTRUCTION_FILES) {
+      const content = readInstructionFile(instructionFile);
+
+      expect(content.indexOf(REPO_RULES_BLOCK_START)).toBeGreaterThan(-1);
+      expect(content.indexOf(REPO_RULES_BLOCK_END)).toBeLessThan(
+        content.indexOf("<!-- truthmark:start -->"),
+      );
+    }
+  });
+
+  it("rewrites source-relative links to resolve from the repository root", () => {
+    const block = renderRepoRulesBlock(process.cwd());
+
+    expect(block).toContain("(docs/repo/architecture/product-boundary.md)");
+    expect(block).toContain("(.truthmark/config.yml)");
+    expect(block).not.toContain("(../");
+  });
+
+  it("rejects duplicated markers instead of corrupting the region", () => {
+    const content = readInstructionFile(INSTRUCTION_FILES[0]);
+    const duplicated = `${content}\n${REPO_RULES_BLOCK_END}\n`;
+
+    expect(() => extractRepoRulesBlock(duplicated)).toThrow(/malformed/u);
+  });
+
+  it("survives a Truthmark managed-block refresh", () => {
+    const block = renderRepoRulesBlock(process.cwd());
+
+    for (const instructionFile of INSTRUCTION_FILES) {
+      const content = readInstructionFile(instructionFile);
+      const refreshed = upsertManagedBlock(
+        content,
+        renderAgentsBlock(createDefaultConfig()),
+      );
+
+      expect(extractRepoRulesBlock(refreshed)).toBe(block);
+    }
+  });
+
+  it("is idempotent when re-applied to an already-rendered file", () => {
+    const block = renderRepoRulesBlock(process.cwd());
+
+    for (const instructionFile of INSTRUCTION_FILES) {
+      const content = readInstructionFile(instructionFile);
+
+      expect(upsertRepoRulesBlock(content, block)).toBe(content);
+    }
+  });
+
+  it("keeps CRLF instruction files homogeneous and semantically synchronized", () => {
+    const block = renderRepoRulesBlock(process.cwd());
+    const content = readInstructionFile(INSTRUCTION_FILES[0]);
+    const crlfContent = content.replace(/\n/g, "\r\n");
+    const updated = upsertRepoRulesBlock(crlfContent, block);
+
+    expect(updated).toBe(crlfContent);
+    expect(normalizeLineEndings(extractRepoRulesBlock(updated) ?? "")).toBe(block);
+    expect(updated.replace(/\r\n/g, "")).not.toContain("\n");
+  });
+});

tests/templates/generated-surfaces.test.ts

@@ -39,18 +39,18 @@ const portalPaths = [
   ".cursor/skills/truthmark-portal/SKILL.md",
 ];
 
+// Checked-in path lists follow the platforms this repository installs. Copilot
+// render coverage lives in the allPlatforms render assertions below.
 const readOnlyProcedurePaths = [
   ".agents/skills/truthmark-check/support/procedure.md",
   ".opencode/skills/truthmark-check/support/procedure.md",
   ".claude/skills/truthmark-check/support/procedure.md",
-  ".github/skills/truthmark-check/support/procedure.md",
 ];
 
 const syncProcedurePaths = [
   ".agents/skills/truthmark-sync/support/procedure.md",
   ".opencode/skills/truthmark-sync/support/procedure.md",
   ".claude/skills/truthmark-sync/support/procedure.md",
-  ".github/skills/truthmark-sync/support/procedure.md",
 ];
 
 const staleWriteAuthorizingLaneText =
@@ -291,7 +291,6 @@ describe("Truthmark Portal generated surfaces", () => {
       ".agents/skills/truthmark-sync/support/report-template.md",
       ".opencode/skills/truthmark-sync/support/report-template.md",
       ".claude/skills/truthmark-sync/support/report-template.md",
-      ".github/skills/truthmark-sync/support/report-template.md",
       ".antigravity/rules/truthmark-sync.md",
       ".cursor/skills/truthmark-sync/support/report-template.md",
     ];

tsconfig.json

@@ -14,6 +14,6 @@
     "types": ["node"],
     "verbatimModuleSyntax": true
   },
-  "include": ["src/**/*.ts", "tests/**/*.ts", "*.config.ts"],
+  "include": ["src/**/*.ts", "tests/**/*.ts", "scripts/**/*.ts", "*.config.ts"],
   "exclude": ["dist", "node_modules"]
 }