docs(topics): expand comprehensive topic map

docs/topics/README.md

@@ -10,15 +10,44 @@ short path to the authoritative surface.
 
 ## Topic Map
 
-| Task                                                         | Start Here                                  | Authority                                                    |
-| ------------------------------------------------------------ | ------------------------------------------- | ------------------------------------------------------------ |
-| Decide whether a change belongs in Wesley or an extension.   | [Compiler Boundary](./compiler-boundary.md) | `docs/design/0014-domain-empty-core-boundary/`               |
-| Configure schema sets, changed-schema selection, or targets. | [Project Manifests](./project-manifests.md) | `docs/reference/project-manifest.md`                         |
-| Author or review descriptor-only extension fixtures.         | [Compiler Boundary](./compiler-boundary.md) | `docs/guides/module-authoring.md`                            |
-| Choose local checks before a PR or release.                  | [Validation](./validation.md)               | `cargo xtask preflight`, `docs/governance/RELEASE_POLICY.md` |
-| Understand HOLMES CI and evidence artifacts.                 | [HOLMES CI](./holmes-ci.md)                 | `.github/workflows/wesley-holmes.yml`, `docs/architecture/`  |
-| Prepare or judge a release.                                  | [Releases](./releases.md)                   | `docs/method/release-runbook.md`, `docs/governance/`         |
-| Triage issues into release lanes.                            | [Issue Triage](./contributing/triage.md)    | GitHub Issues, Milestones, Projects, and labels              |
+### Compiler Use
+
+| Task                                      | Start Here                                      | Authority                                  |
+| ----------------------------------------- | ----------------------------------------------- | ------------------------------------------ |
+| Run the current product command surface.  | [Native CLI](./native-cli.md)                   | `docs/reference/cli.md`                    |
+| Inspect GraphQL lowering, hashes, or IR.  | [Schema And IR](./schema-ir.md)                 | `docs/reference/cli.md#schema`             |
+| Work with operations and directive args.  | [Operations](./operations.md)                   | `docs/reference/cli.md#operation`          |
+| Use or classify GraphQL directives.       | [Directives](./directives.md)                   | `docs/reference/directives.md`             |
+| Author or validate `weslaw/v1`.           | [Weslaw](./weslaw.md)                           | `docs/design/0019-weslaw-semantic-law-ir/` |
+| Emit Rust, TypeScript, or LE-binary code. | [Emitters](./emitters.md)                       | `docs/reference/cli.md#emit`               |
+| Understand generated files and caches.    | [Artifacts And Cache](./artifacts-and-cache.md) | `docs/build-artifacts.md`                  |
+
+### Boundaries And Extension
+
+| Task                                                         | Start Here                                  | Authority                                      |
+| ------------------------------------------------------------ | ------------------------------------------- | ---------------------------------------------- |
+| Decide whether a change belongs in Wesley or an extension.   | [Compiler Boundary](./compiler-boundary.md) | `docs/design/0014-domain-empty-core-boundary/` |
+| Configure schema sets, changed-schema selection, or targets. | [Project Manifests](./project-manifests.md) | `docs/reference/project-manifest.md`           |
+| Author or review descriptor-only extension fixtures.         | [Extension Modules](./extension-modules.md) | `docs/guides/module-authoring.md`              |
+| Handle old Node, host, or package references.                | [Legacy Node Retirement](./legacy-node.md)  | `docs/LEGACY_NODE_MIGRATION.md`                |
+| Check durable repo properties.                               | [Invariants](./invariants.md)               | `docs/invariants/README.md`                    |
+
+### Assurance, CI, And Release
+
+| Task                                        | Start Here                                    | Authority                                                    |
+| ------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------ |
+| Choose local checks before a PR or release. | [Validation](./validation.md)                 | `cargo xtask preflight`, `docs/governance/RELEASE_POLICY.md` |
+| Interpret GitHub Actions checks.            | [CI Workflows](./ci-workflows.md)             | `docs/ci.md`, `.github/workflows/`                           |
+| Understand HOLMES CI and PR comments.       | [HOLMES CI](./holmes-ci.md)                   | `.github/workflows/wesley-holmes.yml`, `docs/architecture/`  |
+| Work with assurance evidence and policies.  | [Assurance Evidence](./assurance-evidence.md) | `docs/holmes-policy-spec.md`                                 |
+| Prepare or judge a release.                 | [Releases](./releases.md)                     | `docs/method/release-runbook.md`, `docs/governance/`         |
+
+### Contributor Process
+
+| Task                              | Start Here                                | Authority                                       |
+| --------------------------------- | ----------------------------------------- | ----------------------------------------------- |
+| Triage issues into release lanes. | [Issue Triage](./contributing/triage.md)  | GitHub Issues, Milestones, Projects, and labels |
+| Keep docs accurate and covered.   | [Docs Maintenance](./docs-maintenance.md) | `docs/governance/DOCUMENTATION_STANDARD.md`     |
 
 ## Coverage Rule
 
@@ -27,6 +56,10 @@ either cover that workflow directly or link clearly to the current
 authoritative page. Topic pages may summarize, but they must not duplicate live
 roadmap state, issue counts, or release progress.
 
+When a PR adds or materially changes a public capability, command family,
+workflow, invariant, release procedure, or extension boundary, update this topic
+map or state why the existing topic path already covers it.
+
 The release gate for this directory is defined in
 [`docs/governance/RELEASE_POLICY.md`](../governance/RELEASE_POLICY.md) and the
 execution runbook in [`docs/method/release-runbook.md`](../method/release-runbook.md).

docs/topics/artifacts-and-cache.md

@@ -0,0 +1,36 @@
+# Artifacts And Cache
+
+<!-- docs-truth: status=current owner=@flyingrobots -->
+
+Use this topic when generated files, cache directories, evidence bundles, or
+report artifacts appear in the checkout.
+
+Generated outputs are disposable unless a specific release or audit process
+says otherwise. Source files, manifests, docs, tests, and checked-in fixtures
+remain the durable repo truth.
+
+## Common Locations
+
+| Location                          | Meaning                                                         |
+| --------------------------------- | --------------------------------------------------------------- |
+| `.wesley-cache/`                  | Default generated evidence/cache location for Wesley workflows. |
+| `out/`                            | Default output root for explicit native emit commands.          |
+| `test/fixtures/**/out/`           | Fixture-generated artifacts.                                    |
+| `test/fixtures/**/.wesley-cache/` | Fixture-generated evidence bundles.                             |
+| `coverage/`                       | Test coverage output.                                           |
+| `dist/`                           | Package build output where retained packages emit bundles.      |
+| `reports-by-schema/`              | HOLMES workflow staging layout for schema-scoped reports.       |
+
+## Rules Of Thumb
+
+- If a generated path is gitignored, assume it can be deleted and regenerated.
+- Do not make generated files an authority over authored GraphQL.
+- External targets own their own cache and output layouts.
+- HOLMES report artifacts are evidence surfaces, not source inputs.
+
+## Related Authority
+
+- [Build Artifacts Reference](../build-artifacts.md)
+- [Project Manifests](./project-manifests.md)
+- [HOLMES CI](./holmes-ci.md)
+- [Validation](./validation.md)

docs/topics/assurance-evidence.md

@@ -0,0 +1,43 @@
+# Assurance Evidence
+
+<!-- docs-truth: status=current owner=@flyingrobots -->
+
+Use this topic when a change touches HOLMES, Watson, Moriarty, BLADE, policy
+templates, evidence bundles, or report interpretation.
+
+Assurance tooling judges explicit evidence. It does not replace the compiler,
+and it does not create product semantics for GraphQL.
+
+## Current Surfaces
+
+| Surface                               | Use For                                                   |
+| ------------------------------------- | --------------------------------------------------------- |
+| `packages/wesley-holmes/`             | Retained JavaScript assurance reporting tools.            |
+| `crates/wesley-holmes/`               | Rust foundation for assurance data models and validation. |
+| `docs/holmes-policy/`                 | Policy documentation.                                     |
+| `docs/templates/holmes-policy/`       | Policy templates for host contexts.                       |
+| `docs/architecture/holmes-*`          | Architecture and integration notes.                       |
+| `.github/workflows/wesley-holmes.yml` | Pull request assurance workflow.                          |
+
+## Rules Of Thumb
+
+- Reports should expose unavailable or invalid evidence honestly.
+- Missing artifacts should not be hidden behind a passing workflow.
+- Policy and report quality are evidence questions, not compiler semantics.
+- Domain-specific target facts should be produced by the owning target module.
+
+## Useful Checks
+
+```bash
+node --test packages/wesley-holmes/test/pr-comment.test.mjs
+BATS_LIB_PATH=test/vendor bats -t test/ci-workflows.bats
+cargo test -p wesley-holmes
+```
+
+## Related Authority
+
+- [HOLMES CI](./holmes-ci.md)
+- [HOLMES Architecture](../architecture/holmes-architecture.md)
+- [HOLMES Integration](../architecture/holmes-integration.md)
+- [HOLMES Policy Spec](../holmes-policy-spec.md)
+- [Policy Templates](../templates/holmes-policy/README.md)

docs/topics/ci-workflows.md

@@ -0,0 +1,56 @@
+# CI Workflows
+
+<!-- docs-truth: status=current owner=@flyingrobots -->
+
+Use this topic when choosing or interpreting GitHub Actions checks.
+
+CI protects the Rust product spine, repository hygiene, retained package
+surfaces, and assurance evidence. It is not a substitute for reading the local
+diff or running focused checks before a PR.
+
+## Check Families
+
+| Family                       | Protects                                           |
+| ---------------------------- | -------------------------------------------------- |
+| Rust product preflight       | Native compiler crates, CLI, tests, clippy.        |
+| Repository hygiene preflight | Docs links, truth manifest, policy hygiene.        |
+| Compatibility smoke          | Workspace compatibility and Rust product smoke.    |
+| CodeQL / analysis            | Static analysis for supported languages.           |
+| Dependency review            | Dependency risk in PRs.                            |
+| HOLMES workflow              | Schema-selected assurance reports and PR comments. |
+
+## Local Mirrors
+
+Run the full product gate:
+
+```bash
+cargo xtask preflight
+```
+
+Run docs-only checks:
+
+```bash
+cargo xtask docs-check
+git diff --check
+```
+
+Run workflow invariant tests:
+
+```bash
+BATS_LIB_PATH=test/vendor bats -t test/ci-workflows.bats
+```
+
+## Rules Of Thumb
+
+- A skipped HOLMES matrix can be correct when no schema set is selected.
+- Browser, Bun, and Deno host experiment workflows are retired from Wesley.
+- Required checks should name the Rust product or repository hygiene surface
+  they protect.
+- Do not widen workflow permissions or secret exposure casually.
+
+## Related Authority
+
+- [Continuous Integration](../ci.md)
+- [HOLMES CI](./holmes-ci.md)
+- [Validation](./validation.md)
+- [Release Workflow](./releases.md)

docs/topics/directives.md

@@ -0,0 +1,47 @@
+# Directives
+
+<!-- docs-truth: status=current owner=@flyingrobots -->
+
+Use this topic when deciding which GraphQL directives are current Wesley
+surface area.
+
+Directive support is not "everything ever mentioned in old docs." Current
+support is what the Rust-native SDL path actually parses, validates, lowers, or
+preserves for current command paths.
+
+## Current Compatibility Path
+
+Existing core directive names are compatibility structure, not domain ownership.
+When current command paths parse names such as the list below, Wesley lowers or
+preserves structural metadata and leaves target meaning to downstream modules.
+
+- `@wes_table`
+- `@wes_pk`
+- `@wes_fk`
+- `@wes_unique`
+- `@wes_index`
+- `@wes_tenant`
+- `@wes_default`
+- `@wes_rls`
+
+Do not present these names as proof that Wesley owns database, tenant, policy,
+runtime, or renderer semantics. For new generic Wesley examples, prefer
+directive examples that demonstrate preservation or law metadata without
+assigning target meaning. When documenting the existing current-path directives,
+use canonical `@wes_*` names and point to the directive truth table.
+
+## Boundary Rules
+
+- Product directive families belong with their owning module or repo.
+- TTD, Continuum, Echo, renderer, database, and runtime directives are not
+  generic Wesley surface unless the current directive reference says so.
+- Registry presence alone does not prove end-to-end command support.
+- Dead or historical directive examples should stay in archives or migration
+  context, not in current quick starts.
+
+## Related Authority
+
+- [Directive Truth Table](../reference/directives.md)
+- [Schema And IR](./schema-ir.md)
+- [Compiler Boundary](./compiler-boundary.md)
+- [Extending Wesley](../guides/extending.md)

docs/topics/docs-maintenance.md

@@ -0,0 +1,51 @@
+# Docs Maintenance
+
+<!-- docs-truth: status=current owner=@flyingrobots -->
+
+Use this topic when editing documentation or deciding whether a new signpost
+belongs in the repo.
+
+Docs are a product interface and an evidence ledger. They are not a live
+backlog, status board, or progress counter.
+
+## Maintenance Rules
+
+- Give each page one primary job: tutorial, how-to, reference, explanation,
+  troubleshooting, contributor guide, or evidence.
+- Keep live work state in GitHub Issues, Milestones, Projects, and labels.
+- Update `docs/truth-manifest.json` when adding or changing public or
+  governance signposts that should be checked.
+- Update `docs/topics/` when a release changes contributor or operator
+  workflows.
+- Do not leave TODOs or hidden backlog state in prose.
+
+## Local Checks
+
+```bash
+cargo xtask docs-check
+git diff --check
+pnpm exec prettier --check <changed-markdown-files>
+```
+
+For release prep, also audit `docs/topics/` for accuracy and coverage against
+the actual release diff.
+
+## Topic Coverage Standard
+
+Every public capability should have an obvious path to:
+
+- orientation or explanation
+- command, API, schema, or invariant reference
+- at least one runnable or clearly illustrative example when useful
+- troubleshooting or known failure behavior when relevant
+- release or closeout evidence when recently shipped
+
+Topic pages may summarize and route. They should not duplicate full reference
+pages or live roadmap state.
+
+## Related Authority
+
+- [Documentation Standard](../governance/DOCUMENTATION_STANDARD.md)
+- [Topics Index](./README.md)
+- [Releases](./releases.md)
+- [Validation](./validation.md)

docs/topics/emitters.md

@@ -0,0 +1,59 @@
+# Emitters
+
+<!-- docs-truth: status=current owner=@flyingrobots -->
+
+Use this topic when generating Rust, TypeScript, or LE-binary codec artifacts
+from GraphQL SDL.
+
+Emitters consume Wesley compiler facts and write generic projection artifacts.
+They must not smuggle database, renderer, runtime, or product semantics into
+Wesley core.
+
+## Common Tasks
+
+Emit Rust declarations and operation bindings:
+
+```bash
+cargo run --bin wesley -- emit rust \
+  --schema schema.graphql \
+  --out generated/models.rs \
+  --metadata-out generated/models.metadata.json
+```
+
+Emit TypeScript declarations and operation bindings:
+
+```bash
+cargo run --bin wesley -- emit typescript \
+  --schema schema.graphql \
+  --out generated/models.ts \
+  --metadata-out generated/models.metadata.json
+```
+
+Emit LE-binary codecs:
+
+```bash
+cargo run --bin wesley -- emit le-binary-rust \
+  --schema schema.graphql \
+  --out generated/codec.rs
+
+cargo run --bin wesley -- emit le-binary-typescript \
+  --schema schema.graphql \
+  --out generated/codec.ts
+```
+
+## Rules Of Thumb
+
+- Use Rust and TypeScript emitters for generic data models and operation
+  bindings.
+- Use metadata sidecars when outputs need deterministic provenance.
+- Put Zod, Postgres, Vue, Vite, renderer, or product artifacts in an external
+  target module.
+- Emitter changes should use structured AST/printer code, not ad hoc semantic
+  string splicing.
+
+## Related Authority
+
+- [CLI Reference](../reference/cli.md#emit)
+- [Extending Wesley](../guides/extending.md#emitter-extensions)
+- [Build Artifacts](../build-artifacts.md)
+- [Compiler Boundary](./compiler-boundary.md)