chore(docs): reconcile vapor + capability-gating drift across M2-M5

[brunota20]

What does this PR do?

Reconciles the M2-M5 design docs with shipped code. Removes vapor (features described in docs but absent from code per ADR-0009) and aligns the capability-gating section to reflect what 0.2 actually validates (boot-time link-time enforcement, not per-call dispatch). Documentation only - no Rust source files touched, runtime behaviour unchanged.

Two logical commits:

1. chore(docs): vapor sweep - mark unshipped features as future direction - all eight non-diagram docs.
2. chore(docs): align capability gating to shipped link-time enforcement - docs/diagrams/diagrams.md only.

Why

Pre-empts the doc-and-claims findings that would otherwise burn in mfw78's review. The conformance check at bruno-brain/wiki/projects/shepherd-audits/m2-m5-conformance-2026-06-23.md flagged five vapor items - the #[nexum::module] / #[shepherd::module] proc macros, the cargo-nexum cargo subcommand, a separate nexum-sdk crate, the :8080/health JSON endpoint, and per-module [module.resources] manifest caps - and one spec drift (per-call capability dispatch claimed in docs/diagrams/diagrams.md). Mfw78's recurring theme #3 is "docs must match shipped code, no drift", so this PR closes the gap without changing any runtime behaviour.

ADR-0009 already captured the M3 architectural decision (host-trait seam supersedes the proc-macro design). This PR teaches the rest of the doc set to point at ADR-0009 rather than describe the superseded shape as if it ships.

Changes

• docs/00-overview.md:

  • Module-package block dropped the unshipped [module.resources] section; added a "not in 0.2 scope" future-direction note covering both the resource caps and the optional trap-stub fallback.
  • SDK section rewritten: shipped surface (shepherd-sdk + shepherd-sdk-test, host-trait seam per ADR-0009, helpers, prelude) replaces the previous two-crate proc-macro table; the layered split + macros + cargo-nexum are framed as future direction.
  • Observability table dropped the :8080/health row; explained that 0.2 liveness is signalled by the :9100/metrics scrape and the structured tracing JSON; flagged the JSON endpoint as future direction.
  • Repo-structure block updated to match the shipped layout.
  • Grant-milestones table M3 entry updated to describe shipped crates rather than vapor.

• docs/02-modules-events-packaging.md: renamed nexum.toml -> module.toml (per ADR-0001); dropped [module.resources] / [module.restart] from the example manifest; updated [capabilities] prose to describe actual boot-time link-time enforcement; added future-direction note.

• docs/05-sdk-design.md: top status box rewritten to flag the entire doc as 0.3+ north-star and point at ADR-0009; cargo-nexum CLI subsection prefaced "not in 0.2 scope".

• docs/06-production-hardening.md: resource-enforcement intro updated to use compile-time globals (DEFAULT_FUEL_PER_EVENT, DEFAULT_MEMORY_LIMIT from crates/nexum-engine/src/runtime/limits.rs); memory + storage subsections rewritten to describe what the engine actually does; Health-Checks section reframed (JSON endpoint as future direction); deployment-Docker block replaced with the shipped shape (port 9100, tini, nexum-engine binary).

• docs/01-runtime-environment.md: guest-side author experience sections prefaced as future-direction macro form pointing at sdk.md.

• docs/07-rpc-namespace-design.md: SDK-shape note at top: macro-driven authoring model is future direction; ADR-0009 is the shipped seam.

• docs/08-platform-generalisation.md: SDK-layering subsection updated to flag the two-crate split as 0.3+ target; summary table updated accordingly.

• docs/migration/0.1-to-0.2.md: engine-crate-rename paragraph no longer lists nexum-sdk + cargo-nexum as shipped.

• docs/diagrams/diagrams.md: diagram-2 class caption and diagram-7 (Capability Dispatch) caption rewritten to describe link-time enforcement (manifest::enforce_capabilities against KNOWN_CAPABILITIES); per-call dispatch preserved as 0.3+ direction.

Breaking changes

None. Documentation-only.

Testing

• cargo doc --workspace --no-deps clean (one pre-existing warning in crates/shepherd-sdk/src/cow/app_data.rs:19 for an unresolved EMPTY_APP_DATA_JSON link; that source file is not touched by this PR and is out of scope).
• No code changes; runtime behaviour unchanged.
• Verified crates/nexum-engine/src/manifest/capabilities.rs::enforce_capabilities is link-time-only against KNOWN_CAPABILITIES + manifest required union optional, with no per-call dispatch hook in HostState.

Notes for reviewers

The 0.2 capability model uses link-time enforcement: an undeclared capability prevents the module from importing the relevant WIT, so unauthorised calls fail at component link rather than at per-call dispatch. Functionally equivalent for the current 0.2 capability set, but the design space for per-call dispatch (runtime capability revocation, finer-grained policies under a richer threat model) remains open for 0.3+. The diagram-7 caption explicitly preserves that direction rather than deleting it.

Base branch is deploy/cow-1076-observe-on-m5 because that is where the M2-M5 docs being reconciled actually live; opening this against main would surface a multi-milestone diff that has nothing to do with this PR.

Two items the audit flagged but were intentionally not touched:

• ADR-0006 promises KNOWN_CAPABILITIES does not gain "twap" / "ethflow" entries (delivered). The ADR does not actually promise per-call gating - that claim was only in docs/diagrams/diagrams.md.
• ADR-0009 itself is the canonical superseding decision and was deliberately not edited; this PR only points the rest of the doc set at it.

Deviations from the brief

• The audit's "find docs/adr/0006" instruction found ADR-0006 had no per-call promise to amend; the actual stale claim was in docs/diagrams/diagrams.md, so the capability-gating fix landed there only. No ADR file was modified.
• The brief mentioned "diagram 8 caption" for capability gating; in docs/diagrams/diagrams.md the capability-dispatch diagram is numbered 7 (diagram 8 is the repo-dependency map). Edits applied to diagram 7 + the diagram-2 class caption that also carried the stale claim. Brain-side architecture.md was not touched per the brief.

AI assistance disclosure

AI Assistance: Claude Code (Opus 4.7) made these doc edits by cross-referencing the conformance audit findings against the shipped code at HEAD of deploy/cow-1076-observe-on-m5. A human (Bruno) is accountable for the result and will review before requesting mfw's review.