@open-agent-toolkit/cli 0.3.29 → 0.3.31

package/README.md

@@ -51,6 +51,8 @@ Fumadocs static exports include `llms.txt`, `llms-full.txt` and `llms/<page-slug
 
 `oat docs check [--target-dir <dir>] [--rule <id>...] [--json]` performs read-only reader, navigation, contributor-command and Mermaid/SVG checks without a site build. Errors exit 1; warnings exit 0. Configure validated severities, numeric thresholds and reason-bearing exceptions under `documentation.check`. Mermaid syntax parsing lazily uses a real DOM with strict sanitization and no script/resource execution; Node 22.17 remains the minimum. See [checker rules and configuration](../../apps/oat-docs/docs/docs-tooling/check.md).
 
+`oat docs literals [--target-dir <dir>] --page <content-relative-reader.md> --source-root <repo-relative-dir> [--source-exclude <pattern>] --json` supplies read-only inline-code occurrence candidates for a matching triad IA mirror. Repeat each single-value selection flag as needed. Sources stay within narrow explicit implementation roots; searched/skipped evidence and first source physical lines are reported. Once-only strict HTML entity decoding and case-sensitive line-local substring matching do not establish runtime validity; analyze judges canonical relevance and authored IA acceptance. Completed not-found/not-applicable exits 0, input/config errors 1, unexpected failures 2. See [literal helper scope and limits](../../apps/oat-docs/docs/docs-tooling/commands.md#oat-docs-literals).
+
 Fumadocs starters constrain `mdast-util-to-markdown` to 2.1.2 for the current upstream handler compatibility defect. New independent install roots get `pnpm-workspace.yaml`; workspace members get manual setup advice for the existing root YAML, with approval/conflict preservation in bootstrap. No member-local boundary or root dependency-policy merge is performed; `--no-root-patch` still controls build scripts only. Keep the effective policy and lockfile and verify actual resolution before building.
 
 Framework starters expose `docs:check` and run it before build; MkDocs `test` is a real check. Bootstrap proposes approved PR CI edits with explicit generated-manifest freshness. Markdown needs neither an app build nor a default manifest.

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.29"
+  "oatVersion": "0.3.31"
 }

package/assets/docs/docs-tooling/add-docs-to-a-repo.md

@@ -69,7 +69,7 @@ For framework apps, it wraps `oat docs init` with a seven-step guided flow: pref
 
 What the framework path adds over the raw CLI:
 
-- **Preflight + conflict resolution.** Detects existing `documentation` config / docs app dir / root `AGENTS.md` section and walks a deliberate resolution choice (replace, abort, repair, or deferred second-app) before any mutation.
+- **Preflight + existing-docs front door.** Detects existing `documentation` config / docs app dir / root `AGENTS.md` section and defaults to audit (`oat-docs-analyze` then approved `oat-docs-apply`), then exits before scaffolding. Replacement requires an explicit choice; a second app remains unsupported. See [IA selection and existing-docs routing](workflows.md#ia-selection-and-guidance).
 - **Richer inputs.** Asks for a **site name** separate from the package name, so layout branding and page metadata converge on the same display title. `createDocsConfig()` handles runtime configuration, not titles.
 - **CLI-owned guidance.** Fresh Fumadocs and MkDocs apps include app-root `AGENTS.md`, a reader-first Getting Started stub, a human contributor entry and `docs/contributing/docs-toolchain.md`. Commands state their working directory. Bootstrap observes this output; older CLIs missing it get analyze/manual CLI-template upgrade advice, rather than a second template owner. Existing and Markdown surfaces are preserved. Nested-standalone Fumadocs still uses the ESM-safe Turbopack root while monorepo and single-package apps use Next root discovery.
 - **Agent Markdown.** Fumadocs exports `/llms.txt`, `/llms-full.txt` and `/llms/<page-slugs>/content.md` (root `/llms/content.md`) from loaded `.md` readers. MDX and configured non-readers are excluded. Source headers identify how to resolve authored relative links; rendered and Markdown URLs include the deployment base path once.

package/assets/docs/docs-tooling/commands.md

@@ -13,7 +13,7 @@ or **MkDocs Material**.
 
 - What it does: documents the docs-specific CLI surface for scaffolding apps, migrating markdown, generating Fumadocs app-root index manifests, and syncing MkDocs or Fumadocs navigation.
 - When to use it: when you already know you are working on a docs surface and need the exact command-level behavior.
-- Primary commands: `oat docs init`, `oat docs migrate`, `oat docs generate-index`, `oat docs nav sync`, `oat docs check`
+- Primary commands: `oat docs init`, `oat docs migrate`, `oat docs generate-index`, `oat docs nav sync`, `oat docs check`, `oat docs literals`
 
 ## Command surface
 
@@ -24,6 +24,7 @@ or **MkDocs Material**.
 | `oat docs generate-index` | Generate a manifest from Markdown files, outside authored content.                    |
 | `oat docs nav sync`       | Regenerate `mkdocs.yml` nav or Fumadocs `meta.json` from `index.md` maps.             |
 | `oat docs check`          | Read-only reader, navigation, command and diagram checks; errors fail, warnings pass. |
+| `oat docs literals`       | Read-only occurrence candidates for explicitly selected Product/QA pages in a triad.  |
 | `oat docs analyze`        | CLI entrypoint that points users to the `oat-docs-analyze` skill.                     |
 | `oat docs apply`          | CLI entrypoint that points users to the `oat-docs-apply` skill.                       |
 
@@ -315,6 +316,68 @@ Related reference:
 
 - [`../reference/docs-index-contract.md`](../reference/docs-index-contract.md)
 
+## `oat docs literals`
+
+After `oat-docs-analyze` confirms the authored accepted IA and config mirror
+agree on `verification: triad`, select Product/QA reader pages and narrow
+canonical implementation directories:
+
+```bash
+oat docs literals --target-dir manual \
+  --page experience/save.md --page verify/save.md \
+  --source-root src/ui --source-exclude src/ui/generated/ --json
+```
+
+`--target-dir` is optional and uses the same configured-root/app/content
+resolution as check. `--page` and `--source-root` are required, repeatable
+single-value flags. Pages are content-relative Markdown (`.md` or `.mdx`,
+without evaluating JSX); roots are repo-relative directories, never the repo
+root. Source roots must also use their canonical on-disk spelling (including case).
+Pages must use their canonical on-disk spelling (including case) and be
+readable readers within the real content tree, outside `nonReaderPaths`,
+with no symlink components below the resolved content root
+(including page files and directory aliases). Sources must remain within the
+repository; nested symlinks are skipped, never traversed. Invalid/escaping selections, unreadable traversal
+and an empty effective text inventory fail visibly. Select implementation
+roots and explicit exclusions to omit docs, fixtures, generated output and
+vendor code as evidence. The helper does not automatically exclude documentation
+from selected source roots. A match to documentation itself is not canonical
+implementation support; inspect the citation and judge its relevance.
+
+`--source-exclude` is optional/repeatable, using the existing bounded POSIX
+exclusion grammar in **repository** coordinates: segment `*`, whole-segment
+`**`, trailing `/` for directories; other metacharacters are literal. Parent
+segments, absolute patterns and backslashes are invalid. `documentation.excludes`
+remains manifest-only; `nonReaderPaths` remains content-relative.
+
+Only a matching mirror declaring triad enables extraction. Other overlays,
+absent IA or an unrelated explicit target return `not-applicable` with reason
+and empty candidates before selected pages/sources are read. This gate does
+not establish authored acceptance; the skill judges that separately.
+
+JSON completion has `status: ok`, `scope: {contentRoot, pages, sourceRoots,
+sourceExcludes}`, `searched` source paths, `skipped: [{path, reason}]`, and
+`literals: [{path, line, literal, normalized, status, source?}]`. Candidate
+status is `found` or `not-found`; source is `{path, line}`. Docs locations are
+content-relative; contentRoot/source scope is repo-relative POSIX. Duplicate
+pages/overlapping inventories are deduplicated. Page order and source file
+order are lexical, then physical line order; the first source occurrence is
+reported. Skipped reasons include symlink, binary, non-UTF8 and non-regular.
+No source snippets, severity or runtime verdict are emitted.
+
+Extraction uses Markdown AST inline code and ignores fenced blocks. Matching
+applies one strict HTML entity decode to each value and each physical source
+line, then a case-sensitive substring search. CommonMark may normalize multiline
+spans; source matching stays per physical line. There is no whitespace/Unicode
+folding, JS escape decoding, interpolation, i18n loading or runtime evaluation.
+A comment, dead code or longer text can match. Inspect canonical relevance;
+`not-found` starts as unverified, and explained concepts require judgment.
+
+Exit 0 means completed evidence, including not-found/not-applicable; exit 1 is
+an actionable input/config error; exit 2 is an unexpected runtime failure.
+Global `--json`/`--cwd` work as usual. This helper is separate from check's G5
+rules, and `oat docs analyze` remains a guidance entrypoint.
+
 ## `oat docs analyze` and `oat docs apply`
 
 These CLI commands intentionally reserve the docs workflow surface without

package/assets/docs/docs-tooling/workflows.md

@@ -19,7 +19,9 @@ Install the workflow skills with `oat tools install docs` (preferred) or
 - `oat docs migrate` converts MkDocs admonitions to GFM callouts and injects frontmatter
 - `oat docs generate-index` generates a Fumadocs app-root docs index manifest from the Markdown file tree
 - `oat docs nav sync` regenerates MkDocs `mkdocs.yml` nav, or strict Fumadocs `meta.json` files, from `index.md` `## Contents` sections
-- `oat docs analyze` and `oat docs apply` expose the workflow surface in CLI help
+- [`oat docs check`](check.md) checks reader pages, navigation, contributor commands and diagrams without building a site
+- [`oat docs literals`](commands.md#oat-docs-literals) supplies bounded inline-code occurrence evidence for analyze
+- `oat docs analyze` and `oat docs apply` expose guidance pointers in CLI help; the skills perform analysis and apply
 
 ### Skills
 
@@ -93,8 +95,9 @@ Diagram: bootstrap once, then analyze, approve and apply only agreed improvement
       Q -->|"all skipped"| STOP
     ```
 
-- **Setup, once.** `oat-docs-bootstrap` checks the repo without writing, asks
-  you to confirm its inputs, then runs `oat docs init`. Plain Markdown setup validates authored files,
+- **Fresh setup or explicit adoption.** `oat-docs-bootstrap` checks the repo without writing, asks
+  you to confirm its inputs, then runs `oat docs init`. Existing docs default to
+  [analyze then approved apply](#ia-selection-and-guidance) and exit before scaffolding. Plain Markdown setup validates authored files,
   configuration and guidance without installing app dependencies or building a
   site. Fumadocs and MkDocs setup inspects CLI-owned scaffold output, installs
   dependencies, verifies the build and provides a walkthrough.
@@ -277,9 +280,10 @@ with a docs app simply because one can be scaffolded.
 
 Preflight only reads. It checks declared documentation configuration before
 discovery and checks framework evidence before assuming a populated
-directory is plain Markdown. The skill then summarizes your choices and asks
-you to confirm them before it runs `oat docs init`. The two setup paths
-differ from that point on.
+directory is plain Markdown. Existing docs default to analyze then approved
+apply and exit before scaffolding. For fresh setup or explicit adoption, the
+skill summarizes your choices and asks you to confirm them before it runs
+`oat docs init`. The two setup paths differ from that point on.
 
 **Plain Markdown path:** Use this when you want plain Markdown files and no
 site runtime. The skill collects a title, a dedicated repository-relative
@@ -352,8 +356,9 @@ pages, grouped headings in one flat index often suffice.
 For fresh Markdown/framework setup and explicit adoption, bootstrap proposes
 two plausible two-level trees with 5–8 representative page placements each,
 page jobs, nearest presets and tradeoffs. Analyze's `--ia` does the same in its
-existing analysis artifact and review loop. These are **skill arguments**;
-they do not add CLI bootstrap commands or flags to `oat docs init`.
+existing analysis artifact and review loop. `--ia` and `--ia-guidance` are
+**skill arguments**, not `oat docs init` flags. The CLI accepts the approved
+selection through the paired [`--ia-preset` and `--planned-pages` flags](commands.md#approved-preset-readers).
 
 Resolve advisory sources in this order: explicit `--ia-guidance <path|url>` or
 conversation, repo `documentation.guidance`, user config, then the installed
@@ -372,8 +377,15 @@ proposal becomes durable only after approval: bootstrap/apply use `oat decision
 and an Information architecture section in the framework docs-app `AGENTS.md`
 or Markdown contributing page, plus the shared `documentation.ia` mirror.
 Authored records stay authoritative; missing/conflicting records become `ask_user`.
-Preset scaffolds and Feature/QA validation page templates are a later delivery;
-the IA Proposal template is available now.
+Fresh empty targets can now materialize all six presets and their relevant
+page-template subsets, including Feature and QA validation templates, through
+that opt-in flag pair. Counts below 15 collapse reader tracks into grouped root
+headings; 15 or more creates tracks, while `flat-small` always stays flat.
+`contributing/templates/**` is excluded from reader navigation, checks and
+manifests. See [preset mappings and template subsets](commands.md#approved-preset-readers),
+including the MkDocs rendered-route limitation. Selection does not create the
+separate approved IA decision; the IA Proposal template remains the selection
+artifact.
 
 ## oat-docs-analyze
 
@@ -454,8 +466,10 @@ navigation or generated-artifact refreshes, plus a structured result listing
 applied, skipped (ID/reason), and failed IDs. Markdown retains its authored
 index and needs no framework build or nav sync; Fumadocs sidebar metadata is
 regenerated only with recorded `navOwner: nav-sync`. Hand-authored navigation
-gets approved edits and read-only Contents membership/order comparison;
-undeclared ownership becomes `ask_user`. The summary
+gets approved edits and read-only Contents membership/order comparison.
+[Absent optional metadata/pages/nav skips comparison](check.md); implicit
+Fumadocs order is not checked. Explicit lists remain checked and nav-sync
+freshness stays strict. Undeclared ownership becomes `ask_user`. The summary
 reports the applied plan and checks.
 
 **What it does without asking:** Nothing changes until you approve the plan.
@@ -508,10 +522,31 @@ consumer and agent coverage. A top-level misroute is High when it blocks normal
 first success/verification, Medium when it causes material detours; cosmetic
 organization stays Low. Missing IA/owner raises `ask_user`.
 
+When the authored accepted IA and its mirror agree on triad verification,
+analyze also checks six source-related concerns: mapped feature slug parity,
+real peer links/anchors (including QA Scope pairing), quoted literals versus
+explained concepts, exact membership in the repository's own test-ID registry,
+scoped duplicate/contradictory scenarios, and raw Contents links to templates
+even when nav excludes them. Roles come from the decision/local guidance,
+including renamed tracks and hybrid Engineering; flat layouts may be not
+applicable. Missing mapping/registry stays unverified / `ask_user`. Other
+overlays continue ordinary analysis unchanged.
+
+The [literal occurrence helper](commands.md#oat-docs-literals) supplies bounded
+text candidates for selected Product/QA pages. A found substring requires
+canonical-source judgment; not-found is initially unverified. It cannot prove
+runtime behavior, registry membership or scenario correctness. Accepted IA,
+source citations and existing recommendation approval classes still govern.
+
 For framework apps, offline drift compares installed `@open-agent-toolkit/docs-*` packages to the
 running CLI's bundled `public-package-versions.json`, never registry latest.
-Missing installations are unverified. The recommendation includes the exact
-upgrade command. Individual tooling approval permits only docs-app `@open-agent-toolkit/docs-*`
+Older installed packages produce an explicit drift recommendation with the
+exact upgrade command. Equal versions are current. Newer packages are `ahead`: select
+or update the intended CLI installation before re-analysis, without a package
+downgrade command. Missing installations or bundle metadata and non-orderable
+versions are `unverified` and require manual verification; hoisted-only packages
+also remain unverified. Neither ahead nor unverified supplies a package-update
+command or authorizes an upgrade. Individual tooling approval permits only docs-app `@open-agent-toolkit/docs-*`
 dependency bumps (and resulting lockfile), the admonition/frontmatter conversions
 already supported by `oat docs migrate`, and build verification. App config,
 routes and package scripts remain manual required changes.

package/assets/docs/reference/cli-reference.md

@@ -80,6 +80,8 @@ Lifecycle](../workflows/backlog-and-planning/backlog-lifecycle.md).
 
 `oat docs check [--target-dir <dir>] [--rule <id>...] [--json]` validates reader structure, links, navigation, contributor commands and diagrams without a site build. Errors exit 1; warning-only exits 0. See [Check Documentation](../docs-tooling/check.md) for rules/config and JSON.
 
+`oat docs literals --page <reader.md> --source-root <implementation-dir> [--target-dir <dir>] [--source-exclude <pattern>] --json` reports bounded inline-code occurrence candidates for triad IA mirrors. Pages and roots are repeatable single-value flags in content/repository coordinates respectively. Found candidates require canonical-source judgment. See [literal helper scope, JSON and limits](../docs-tooling/commands.md#oat-docs-literals).
+
 ## Command Groups
 
 | Command group                                   | What it covers                                                                                                                                                                                                             | Go deeper                                                                                   |

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.29",
-  "docs-config": "0.3.29",
-  "docs-theme": "0.3.29",
-  "docs-transforms": "0.3.29"
+  "cli": "0.3.31",
+  "docs-config": "0.3.31",
+  "docs-theme": "0.3.31",
+  "docs-transforms": "0.3.31"
 }

package/assets/skills/oat-docs-analyze/SKILL.md

@@ -4,9 +4,9 @@ description: Run when you need to evaluate documentation structure, navigation,
 argument-hint: '[target] [--ia] [--ia-guidance <path|url>]'
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Bash(oat config:*), Bash(oat docs nav sync --check:*), Bash(oat docs check:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(node:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion, Task
+allowed-tools: Read, Write, Bash(git:*), Bash(oat config:*), Bash(oat docs nav sync --check:*), Bash(oat docs check:*), Bash(oat docs literals:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(node:*), Bash(command -v:*), Bash(sed:*), Bash(npm root -g:*), Bash(test:*), Bash(oat --version), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: '1.7.3'
+  version: '1.7.5'
 ---
 
 # Docs Analysis
@@ -336,7 +336,8 @@ app's docs avoid merely mirroring implementation directories. Review coverage
 only for declared readers: Product features/journeys/screens/states; QA scenario
 tables with seeds and automation references; consumer first-success/task guides;
 agent entrypoints, canonical sources and verification commands. Do not demand
-these tracks from every repository or implement the later P24 source checks.
+these tracks from every repository. For an accepted triad, also perform the
+conditional source assessments below.
 
 Top-level IA misroutes a declared audience: `High` when the reader cannot find
 a normal first-success or required verification path; `Medium` when that path
@@ -389,6 +390,91 @@ Evidence standard for this step:
 - If multiple repo files are needed to verify a claim, cite all relevant sources.
 - If the canonical source is ambiguous, mark the claim `unverified` rather than guessing.
 
+### Conditional triad source assessments (P24)
+
+Run these six assessments only after the authored **accepted** IA decision and
+local Information architecture section agree with the mirror's
+`verification: triad`. Cite that agreement first. A mirror alone does not prove
+acceptance. For absent, `agent-only`, or `none` overlays, record not applicable
+and continue ordinary analysis unchanged. Missing/broken authored acceptance or
+a conflicting mirror blocks these assessments with `unverified` / `ask_user`;
+it does not block ordinary analysis or justify choosing an IA.
+
+Map Product, QA and Engineering feature subsets from the accepted decision,
+tracks/principles and local guidance, citing each mapping. Do not infer roles
+from fixed folder names or tracks array order. Engineering may mix domain
+contracts with feature pages: compare only its mapped feature subset. A grouped
+flat IA may have no per-feature triad; explain not applicable rather than invent
+folders. An unresolved mapping stays `unverified` / `ask_user` without new config.
+
+1. **Slug parity.** Compare relative feature/journey keys in the mapped subsets.
+   Exclude indexes, support pages, templates and Engineering domain contracts.
+   Cite missing/extra peers and the declared mapping before recommending repair.
+2. **Paired documentation.** Inspect each member's actual peer links, resolving
+   relative paths and anchors within the repository. Accept case-insensitive
+   Paired Documentation headings and QA's canonical Scope links when they point
+   to the appropriate Product/Engineering peers. A heading alone or an unrelated
+   resolving link is insufficient. Cite both link and target/anchor; unresolved
+   or wrong-peer links become evidence-backed findings.
+3. **Quoted literals and concepts.** Select Product/QA reader Markdown and narrow
+   canonical implementation directories from cited source references/local
+   guidance, then invoke the read-only helper (repeat one value per flag):
+
+   ```bash
+   oat docs literals --target-dir <resolved-target> \
+     --page <product-page> --page <qa-page> \
+     --source-root <implementation-dir> \
+     --source-exclude <generated-or-fixture-pattern> --json
+   ```
+
+   Pages are content-relative; roots and exclusions are repository-relative.
+   Never scan the repository root, dependencies, home or external sources.
+   Select implementation roots and exclusions that omit docs, templates,
+   generated/vendor output and example/test fixtures as evidence. The helper
+   does not automatically exclude documentation from selected source roots;
+   a match to documentation itself is not canonical implementation support.
+   Inspect the returned scope, searched files and skipped symlink/binary/non-UTF8
+   inputs; incomplete traversal or invalid selections fail visibly. Missing
+   canonical sources remain unverified; do not broaden scanning to manufacture
+   matches.
+
+   The helper extracts AST inline code, ignores fences, and performs exactly
+   one strict HTML entity decode per value and physical source line, followed
+   by case-sensitive substring matching. It reports the first lexical source
+   file/physical line, without snippets or a runtime verdict. CommonMark can
+   normalize multiline spans; source matching stays per physical line. It does
+   not fold whitespace/Unicode, decode JS escapes, evaluate interpolation or
+   load i18n/runtime values. A found substring can be in a comment, dead code,
+   fixture or longer text: read the citation and judge canonical relevance.
+   `not-found` is initially **unverified**, never automatic contradiction.
+   Require a differing canonical value before judging contradicted. Distinguish
+   intentionally explained concepts from UI literals; prose concepts need no
+   occurrence, while ambiguous backticked concepts require clarification or a
+   cited conceptual explanation. Exit 0 means completed candidates (including
+   not-found/not-applicable), not verified documentation.
+
+4. **Test-ID registry membership.** Locate the repository's actual canonical
+   test-ID registry and read its real format. Check exact member equality,
+   never substring occurrence in arbitrary source. Cite registry and docs.
+   Missing/ambiguous registry stays `unverified` / `ask_user`; do not invent a
+   registry path/schema or treat helper matches as membership proof.
+5. **Scoped scenario candidates.** Inspect QA tables for duplicate IDs and the
+   same scoped Given + When with different Then outcomes. Compare feature,
+   seed, platform and configuration preconditions before judging contradiction;
+   meaningful differences can explain the result. Cite both rows and scope.
+   Ambiguous scope stays unverified. This is judgment, not a scenario engine.
+6. **Templates in authored Contents.** Read raw authored `## Contents` links
+   before applying reader/nav exclusions. Flag links that expose drafting
+   templates as reader destinations even when `nonReaderPaths` makes nav/check
+   skip them; cite the map entry and template purpose/local declaration. Do not
+   infer safety from a clean generated nav or checker result.
+
+Record applicability, mappings, docs/source citations, candidates and judgments
+in the existing artifact's Accuracy Verification section. Use the existing
+severity and recommendation `approval: explicit | default` classes; missing
+mapping/registry evidence is not permission to add a schema or implementation.
+No P24 `oat docs check` rule is added, and its G5 JSON/rule IDs are unchanged.
+
 ### Step 5: Analyze Content Coverage Opportunities
 
 Add a coverage-gap pass after accuracy verification.

package/assets/skills/oat-docs-analyze/references/analysis-artifact-template.md

@@ -247,6 +247,29 @@ runtime-only behavior here.
 
 {Or: "No repo-checkable substantive claims required accuracy verification."}
 
+### Conditional triad source assessments (P24)
+
+- Gate: {accepted authored IA + local section citations and mirror agreement;
+  non-triad: not applicable; missing/conflict: unverified / ask_user}
+- Role/subset mapping: {Product, QA, Engineering feature roots and citations;
+  hybrid domain exclusions; flat applicability; never folder names/array order}
+- Literal helper: {exact invocation; scope, searched files and skipped reasons;
+  occurrence candidates only, not a runtime verdict}
+
+| Assessment                 | Docs / canonical evidence                                      | Candidate and judgment                                                                  |
+| -------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Slug parity                | {mapped feature keys and missing/extra peers}                  | {verdict or unverified / not applicable}                                                |
+| Paired documentation       | {peer links + resolved target anchors; QA Scope accepted}      | {correct peers, not just any resolving link}                                            |
+| Quoted literals / concepts | {helper path:line + canonical source / conceptual explanation} | {found requires relevance judgment; not-found initially unverified}                     |
+| Test-ID registry           | {actual registry path:line + exact member}                     | {membership; absent registry unverified / ask_user}                                     |
+| Scoped scenarios           | {both rows + feature/seed/platform/config scope}               | {duplicate ID / same Given+When with differing Then candidate; explained or unresolved} |
+| Raw authored Contents      | {map entry + template purpose / nonReaderPaths}                | {flag reader links to templates even when nav excludes them}                            |
+
+Keep one strict HTML entity decode per side and physical-source-line matching
+limits visible. No JS/i18n evaluation, runtime claim, invented mapping/registry,
+or automatic contradiction from absence. Recommendations retain existing
+approval classes and docs/source citations.
+
 ## Coverage Review by Surface
 
 Summarize which documentable surfaces were proven by repo evidence and how well

package/assets/skills/oat-docs-analyze/references/quality-checklist.md

@@ -55,6 +55,24 @@ Use this checklist when evaluating a docs surface.
 - Referenced paths exist.
 - Tooling/setup instructions are current.
 
+## Conditional triad source assessments (P24)
+
+- Authored accepted IA and local section agree with the mirror's triad overlay;
+  other overlays are not applicable, missing/conflicting evidence unverified / ask_user.
+- Roles and feature subsets come from cited decisions/local guidance, including
+  renamed tracks, hybrid Engineering and flat applicability; no folder/order inference.
+- Slug parity compares only mapped feature keys, excluding support/domain pages.
+- Peer links resolve to the correct member and anchor; QA Scope links count.
+- Product/QA literals use `oat docs literals` with explicit pages, narrow source
+  roots and source exclusions. Scope, searched files and skipped reasons are reviewed.
+- Once-decoded, case-sensitive physical-line occurrences receive canonical-source
+  judgment; not-found remains unverified and explained concepts are distinguished.
+- Test IDs use exact membership in the actual registry; absent registry stays unverified.
+- Duplicate IDs and same scoped Given+When/different Then candidates are judged
+  with seed/platform/configuration evidence, never automatically contradicted.
+- Raw authored Contents links to templates are flagged despite reader/nav exclusions.
+- Existing severity, citations and recommendation approval classes are preserved.
+
 ## Discoverability
 
 - Important pages are reachable from a parent `index.md` or site nav.

package/dist/commands/docs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/docs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,wBAAgB,iBAAiB,IAAI,OAAO,CAU3C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/docs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,wBAAgB,iBAAiB,IAAI,OAAO,CAW3C"}

package/dist/commands/docs/index.js

@@ -4,12 +4,14 @@ import { createDocsApplyCommand } from './apply.js';
 import { createDocsCheckCommand } from './check/check.js';
 import { createDocsGenerateIndexCommand } from './index-generate/index.js';
 import { createDocsInitCommand } from './init/index.js';
+import { createDocsLiteralsCommand } from './literals/literals.js';
 import { createDocsMigrateCommand } from './migrate/index.js';
 import { createDocsNavCommand } from './nav/index.js';
 export function createDocsCommand() {
     return new Command('docs')
         .description('OAT documentation bootstrap and maintenance commands')
         .addCommand(createDocsCheckCommand())
+        .addCommand(createDocsLiteralsCommand())
         .addCommand(createDocsAnalyzeCommand())
         .addCommand(createDocsApplyCommand())
         .addCommand(createDocsGenerateIndexCommand())

package/dist/commands/docs/literals/evidence.d.ts

@@ -0,0 +1,39 @@
+export declare class LiteralInputError extends Error {
+}
+export interface LiteralOptions {
+    cwd: string;
+    targetDir?: string;
+    page: string[];
+    sourceRoot: string[];
+    sourceExclude: string[];
+}
+interface Candidate {
+    path: string;
+    line: number;
+    literal: string;
+    normalized: string;
+    status: 'found' | 'not-found';
+    source?: {
+        path: string;
+        line: number;
+    };
+}
+export interface LiteralResult {
+    status: 'ok' | 'not-applicable';
+    reason?: string;
+    scope: {
+        contentRoot: string;
+        pages: string[];
+        sourceRoots: string[];
+        sourceExcludes: string[];
+    };
+    searched: string[];
+    skipped: {
+        path: string;
+        reason: 'symlink' | 'binary' | 'non-utf8' | 'non-regular';
+    }[];
+    literals: Candidate[];
+}
+export declare function collectLiteralEvidence(options: LiteralOptions): Promise<LiteralResult>;
+export {};
+//# sourceMappingURL=evidence.d.ts.map

package/dist/commands/docs/literals/evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/literals/evidence.ts"],"names":[],"mappings":"AAgBA,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAE/C,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AACD,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,GAAG,WAAW,CAAC;IAC9B,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC;AACD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,IAAI,GAAG,gBAAgB,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QACL,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,cAAc,EAAE,MAAM,EAAE,CAAC;KAC1B,CAAC;IACF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,CAAC;KAC3D,EAAE,CAAC;IACJ,QAAQ,EAAE,SAAS,EAAE,CAAC;CACvB;AAkDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CA6MxB"}

package/dist/commands/docs/literals/evidence.js

@@ -0,0 +1,205 @@
+import { lstat, readFile, readdir, realpath, stat } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import { containedFile, inside, posix, resolveCheckTarget, } from '../../docs/check/files.js';
+import { parsePage } from '../../docs/check/markdown.js';
+import { createExclusionMatcher, isExcludedPath, } from '../../docs/shared/exclusions.js';
+import { decodeHTMLStrict } from 'entities';
+export class LiteralInputError extends Error {
+}
+function inputPath(value, label, pattern = false) {
+    const path = value.trim().replace(/^\.\//, '');
+    const parts = path.replace(/\/$/, '').split('/');
+    if (!path ||
+        path.startsWith('/') ||
+        /^[A-Za-z]:/.test(path) ||
+        path.includes('\\') ||
+        [...path].some((c) => c.charCodeAt(0) < 32) ||
+        parts.some((p) => !p || p === '.' || p === '..') ||
+        (!pattern && path.includes('*')))
+        throw new LiteralInputError(`${label} must be a non-empty relative POSIX ${pattern ? 'pattern' : 'path'} without parent segments.`);
+    return pattern ? path : path.replace(/\/$/, '');
+}
+const unique = (values) => [...new Set(values)].sort();
+async function selected(label, operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (['ENOENT', 'ENOTDIR', 'EACCES', 'EPERM', 'ELOOP', 'EISDIR'].includes(error.code ?? ''))
+            throw new LiteralInputError(`Cannot read ${label}; check that it exists and is readable.`);
+        throw error;
+    }
+}
+function text(bytes) {
+    if (bytes.includes(0))
+        return { reason: 'binary' };
+    try {
+        return { value: new TextDecoder('utf-8', { fatal: true }).decode(bytes) };
+    }
+    catch {
+        return { reason: 'non-utf8' };
+    }
+}
+export async function collectLiteralEvidence(options) {
+    const target = await selected('documentation target/config', async () => {
+        try {
+            return await resolveCheckTarget(options.cwd, options.targetDir);
+        }
+        catch (error) {
+            if (!error.code)
+                throw new LiteralInputError('Cannot resolve documentation target/config; check .oat/config.json, documentation.root, documentation.ia and --target-dir.');
+            throw error;
+        }
+    });
+    const result = {
+        status: 'not-applicable',
+        scope: {
+            contentRoot: posix(relative(target.repoRoot, target.contentRoot)) || '.',
+            pages: [],
+            sourceRoots: [],
+            sourceExcludes: [],
+        },
+        searched: [],
+        skipped: [],
+        literals: [],
+    };
+    // Config is only the extraction gate. The skill separately reconciles authored acceptance.
+    if (target.documentation.ia?.verification !== 'triad') {
+        result.reason =
+            'The matching documentation IA mirror does not declare verification: triad.';
+        return result;
+    }
+    if (!inside(target.repoRoot, target.contentRoot))
+        throw new LiteralInputError('Docs content root must be inside the repository.');
+    if (!options.page.length || !options.sourceRoot.length)
+        throw new LiteralInputError('Provide at least one --page and one narrow --source-root.');
+    const pages = unique(options.page.map((p) => inputPath(p, '--page')));
+    const roots = unique(options.sourceRoot.map((p) => inputPath(p, '--source-root')));
+    const excludes = unique(options.sourceExclude.map((p) => inputPath(p, '--source-exclude', true)));
+    result.scope = {
+        contentRoot: result.scope.contentRoot,
+        pages,
+        sourceRoots: roots,
+        sourceExcludes: excludes,
+    };
+    const matcher = createExclusionMatcher(excludes);
+    const sources = new Set();
+    const skipped = new Map();
+    // Inspect each component so an explicitly selected nested alias cannot bypass traversal policy.
+    const symlinkComponent = async (root, path) => {
+        const parts = path.split('/');
+        for (let i = 1; i <= parts.length; i++) {
+            if ((await lstat(join(root, ...parts.slice(0, i)))).isSymbolicLink())
+                return true;
+        }
+        return false;
+    };
+    const walk = async (path) => {
+        const absolute = join(target.repoRoot, path);
+        const info = await selected(`source ${path}`, () => lstat(absolute));
+        if (info.isSymbolicLink()) {
+            skipped.set(path, 'symlink');
+            return;
+        }
+        if (isExcludedPath(matcher, path, info.isDirectory()))
+            return;
+        if (info.isDirectory()) {
+            const entries = await selected(`source directory ${path}`, () => readdir(absolute));
+            for (const name of entries.sort())
+                await walk(`${path}/${name}`);
+        }
+        else if (info.isFile())
+            sources.add(path);
+        else
+            skipped.set(path, 'non-regular');
+    };
+    for (const path of roots) {
+        await selected(`source root ${path}`, async () => {
+            const absolute = resolve(target.repoRoot, path);
+            if (!inside(target.repoRoot, absolute) || absolute === target.repoRoot)
+                throw new LiteralInputError('Source roots must be narrow directories inside the repository, never the repository root.');
+            if (await symlinkComponent(target.repoRoot, path)) {
+                // An external alias is invalid input, even though it will never be read.
+                if (!inside(target.repoRoot, await realpath(absolute)))
+                    throw new LiteralInputError(`Source root ${path} resolves outside the repository.`);
+                skipped.set(path, 'symlink');
+                return;
+            }
+            if (!inside(target.repoRoot, await realpath(absolute)) ||
+                !(await stat(absolute)).isDirectory())
+                throw new LiteralInputError(`Source root ${path} must be a contained directory.`);
+            const canonical = posix(relative(await realpath(target.repoRoot), await realpath(absolute)));
+            if (canonical !== path)
+                throw new LiteralInputError(`Source root ${path} must use its canonical repo-relative spelling: ${canonical}.`);
+            await walk(path);
+        });
+    }
+    const sourceLines = [];
+    for (const path of [...sources].sort()) {
+        if (!(await containedFile(target.repoRoot, join(target.repoRoot, path))))
+            throw new LiteralInputError(`Source ${path} is no longer a contained file; rerun with stable inputs.`);
+        const decoded = text(await selected(`source ${path}`, () => readFile(join(target.repoRoot, path))));
+        if ('reason' in decoded)
+            skipped.set(path, decoded.reason);
+        else {
+            result.searched.push(path);
+            sourceLines.push({
+                path,
+                lines: decoded.value
+                    .split(/\r\n|\n|\r/)
+                    .map((line) => decodeHTMLStrict(line)),
+            });
+        }
+    }
+    if (!sourceLines.length)
+        throw new LiteralInputError(`No readable UTF-8 source files remain after exclusions; correct --source-root/--source-exclude. Skipped: ${[...skipped]
+            .sort()
+            .map(([path, reason]) => `${path} (${reason})`)
+            .join(', ') || 'none'}.`);
+    for (const path of pages) {
+        await selected(`page ${path}`, async () => {
+            const absolute = resolve(target.contentRoot, path);
+            if (!/\.mdx?$/.test(path) ||
+                isExcludedPath(target.matcher, path) ||
+                (await symlinkComponent(target.contentRoot, path)) ||
+                !(await containedFile(target.contentRoot, absolute)))
+                throw new LiteralInputError(`Page ${path} must be readable reader Markdown inside the content root, outside nonReaderPaths, with no symlink components below the content root.`);
+            const canonical = posix(relative(await realpath(target.contentRoot), await realpath(absolute)));
+            if (canonical !== path)
+                throw new LiteralInputError(`Page ${path} must use its canonical content-relative spelling: ${canonical}.`);
+            const decoded = text(await readFile(absolute));
+            if ('reason' in decoded)
+                throw new LiteralInputError(`Page ${path} must be UTF-8 Markdown text.`);
+            const page = parsePage(path, decoded.value);
+            if (page.frontmatterError)
+                throw new LiteralInputError(`Page ${path} has invalid YAML frontmatter.`);
+            for (const node of page.nodes) {
+                if (node.type !== 'inlineCode')
+                    continue;
+                const literal = node.value ?? '';
+                const normalized = decodeHTMLStrict(literal);
+                const candidate = {
+                    path,
+                    line: node.position?.start.line ?? 1,
+                    literal,
+                    normalized,
+                    status: 'not-found',
+                };
+                for (const source of sourceLines) {
+                    const index = source.lines.findIndex((line) => line.includes(normalized));
+                    if (index >= 0) {
+                        candidate.status = 'found';
+                        candidate.source = { path: source.path, line: index + 1 };
+                        break;
+                    }
+                }
+                result.literals.push(candidate);
+            }
+        });
+    }
+    result.status = 'ok';
+    result.skipped = [...skipped]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([path, reason]) => ({ path, reason }));
+    return result;
+}

package/dist/commands/docs/literals/literals.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createDocsLiteralsCommand(): Command;
+//# sourceMappingURL=literals.d.ts.map

package/dist/commands/docs/literals/literals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"literals.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/literals/literals.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,wBAAgB,yBAAyB,IAAI,OAAO,CAmEnD"}

package/dist/commands/docs/literals/literals.js

@@ -0,0 +1,50 @@
+import { buildCommandContext } from '../../../app/command-context.js';
+import { readGlobalOptions } from '../../shared/shared.utils.js';
+import { Command } from 'commander';
+import { collectLiteralEvidence, LiteralInputError, } from './evidence.js';
+export function createDocsLiteralsCommand() {
+    const append = (value, previous = []) => previous.concat(value);
+    return new Command('literals')
+        .allowExcessArguments(false)
+        .description('Read-only triad inline-code occurrence candidates; found does not prove runtime behavior')
+        .option('--target-dir <dir>', 'Docs app root or literal Markdown content root')
+        .requiredOption('--page <path>', 'Content-relative Product/QA reader Markdown (repeat one value per flag)', append)
+        .requiredOption('--source-root <dir>', 'Narrow repo-relative implementation directory, never repo root (repeatable)', append)
+        .option('--source-exclude <pattern>', 'Repo-relative bounded POSIX exclusion: segment *, whole-segment **, trailing / directories (repeatable)', append, [])
+        .addHelpText('after', '\nMatching: one strict HTML entity decode per inline-code value and physical source line; case-sensitive substring. CommonMark may normalize multiline code spans. No whitespace/Unicode folding, JS escapes, interpolation or runtime evaluation. Sources are searched only within explicit roots; inspect searched/skipped evidence. Exit 0: completed (including not-found/not-applicable); 1: input/config; 2: runtime failure.')
+        .action(async (options, command) => {
+        const context = buildCommandContext(readGlobalOptions(command));
+        try {
+            const result = await collectLiteralEvidence({
+                ...options,
+                cwd: context.cwd,
+            });
+            process.exitCode = 0;
+            if (context.json)
+                context.logger.json(result);
+            else {
+                context.logger.info(result.status === 'not-applicable'
+                    ? `Not applicable: ${result.reason}`
+                    : `Literal occurrence candidates: ${result.literals.filter((c) => c.status === 'found').length} found, ${result.literals.filter((c) => c.status === 'not-found').length} not-found. These require canonical-source judgment.`);
+                context.logger.info(JSON.stringify({
+                    scope: result.scope,
+                    searched: result.searched,
+                    skipped: result.skipped,
+                    literals: result.literals,
+                }));
+            }
+        }
+        catch (error) {
+            const input = error instanceof LiteralInputError;
+            process.exitCode = input ? 1 : 2;
+            // Resolver/config diagnostics can carry local absolute paths; keep evidence relative.
+            const message = error.message
+                .replaceAll(`${context.cwd}/`, '')
+                .replaceAll(context.cwd, '.');
+            if (context.json)
+                context.logger.json({ status: 'error', message });
+            else
+                context.logger.error(message);
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.3.29",
+  "version": "0.3.31",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -42,8 +42,8 @@
     "unified": "11.0.5",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.3.29",
-    "@open-agent-toolkit/docs-transforms": "0.3.29"
+    "@open-agent-toolkit/control-plane": "0.3.31",
+    "@open-agent-toolkit/docs-transforms": "0.3.31"
   },
   "devDependencies": {
     "@types/jsdom": "28.0.3",