@beyondwork/docx-react-component 1.0.0

package/docs/reference/runtime-config/claude.md

@@ -0,0 +1,110 @@
+# Claude Runtime Configuration
+
+Wave launches Claude headlessly with `claude -p --no-session-persistence`.
+
+## Supported Configuration
+
+| Behavior | `wave.config.json` / profile key | Wave `### Executor` key | Launch effect |
+| --- | --- | --- | --- |
+| Command | `executors.claude.command`, `executors.profiles.<name>.claude.command` | `claude.command` | Selects the executable |
+| Default model | `executors.claude.model`, `executors.profiles.<name>.model` | `model` | Adds `--model <name>` |
+| Agent | `executors.claude.agent`, `executors.profiles.<name>.claude.agent` | `claude.agent` | Adds `--agent <name>` |
+| Prompt mode | `executors.claude.appendSystemPromptMode` | n/a | Uses `--append-system-prompt-file` or `--system-prompt-file` |
+| Permission mode | `executors.claude.permissionMode`, `executors.profiles.<name>.claude.permissionMode` | `claude.permission_mode` | Adds `--permission-mode <mode>` |
+| Permission prompt tool | `executors.claude.permissionPromptTool`, `executors.profiles.<name>.claude.permissionPromptTool` | `claude.permission_prompt_tool` | Adds `--permission-prompt-tool <tool>` |
+| Effort | `executors.claude.effort`, `executors.profiles.<name>.claude.effort` | `claude.effort` | Adds `--effort low|medium|high|max` |
+| Max turns | `executors.claude.maxTurns`, `executors.profiles.<name>.claude.maxTurns` | `claude.max_turns` | Adds `--max-turns <n>` |
+| MCP config | `executors.claude.mcpConfig`, `executors.profiles.<name>.claude.mcpConfig` | `claude.mcp_config` | Adds repeated `--mcp-config <path>` |
+| Strict MCP mode | `executors.claude.strictMcpConfig`, `executors.profiles.<name>.claude.strictMcpConfig` | n/a | Adds `--strict-mcp-config` |
+| Base settings file | `executors.claude.settings`, `executors.profiles.<name>.claude.settings` | `claude.settings` | Passed through `--settings` when no inline overlay is generated, or used as the base for the generated overlay |
+| Inline settings JSON | `executors.claude.settingsJson`, `executors.profiles.<name>.claude.settingsJson` | `claude.settings_json` | Merged into generated settings overlay |
+| Inline hooks JSON | `executors.claude.hooksJson`, `executors.profiles.<name>.claude.hooksJson` | `claude.hooks_json` | Written under top-level `hooks` in the generated settings overlay |
+| Allowed HTTP hook URLs | `executors.claude.allowedHttpHookUrls`, `executors.profiles.<name>.claude.allowedHttpHookUrls` | `claude.allowed_http_hook_urls` | Written under top-level `allowedHttpHookUrls` in the generated settings overlay |
+| Output format | `executors.claude.outputFormat`, `executors.profiles.<name>.claude.outputFormat` | `claude.output_format` | Adds `--output-format text|json|stream-json` |
+| Allowed tools | `executors.claude.allowedTools`, `executors.profiles.<name>.claude.allowedTools` | `claude.allowed_tools` | Adds repeated `--allowedTools <tool>` |
+| Disallowed tools | `executors.claude.disallowedTools`, `executors.profiles.<name>.claude.disallowedTools` | `claude.disallowed_tools` | Adds repeated `--disallowedTools <tool>` |
+
+## Overlay Behavior
+
+Wave always writes `claude-system-prompt.txt` for the harness runtime instructions.
+
+Wave validates the effort enum only. Model-specific compatibility for values such as `max` remains enforced by Claude Code itself.
+
+Wave writes `claude-settings.json` only when at least one inline overlay input is present:
+
+- `settingsJson`
+- `hooksJson`
+- `allowedHttpHookUrls`
+
+Merge order:
+
+1. base `claude.settings` JSON file, if provided
+2. inline `settingsJson`
+3. inline `hooksJson` under top-level `hooks`
+4. inline `allowedHttpHookUrls` under top-level `allowedHttpHookUrls`
+
+If no inline overlay data is present, Wave passes the base `claude.settings` file directly through `--settings` without generating `claude-settings.json`.
+
+## Example: `wave.config.json`
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "deep-review": {
+        "id": "claude",
+        "model": "claude-sonnet-4-6",
+        "budget": {
+          "turns": 10,
+          "minutes": 30
+        },
+        "claude": {
+          "agent": "reviewer",
+          "effort": "high",
+          "permissionMode": "plan",
+          "allowedTools": ["Read"],
+          "disallowedTools": ["Edit"]
+        }
+      }
+    },
+    "claude": {
+      "command": "claude",
+      "appendSystemPromptMode": "append",
+      "outputFormat": "text",
+      "settingsJson": {
+        "permissions": {
+          "allow": ["Read"]
+        }
+      }
+    }
+  }
+}
+```
+
+## Example: Wave `### Executor`
+
+````md
+### Executor
+
+- id: claude
+- model: claude-sonnet-4-6
+- claude.effort: high
+- claude.permission_mode: plan
+- claude.max_turns: 4
+- claude.settings_json: {"permissions":{"allow":["Read"]}}
+- claude.hooks_json: {"Stop":[{"command":"echo stop"}]}
+- claude.allowed_http_hook_urls: https://example.com/hooks
+- claude.output_format: json
+- claude.allowed_tools: Read
+- claude.disallowed_tools: Edit
+````
+
+## Dry-Run Output
+
+For a dry run, inspect:
+
+- `claude-system-prompt.txt`
+- `claude-settings.json`, when generated
+- `launch-preview.json`
+
+`launch-preview.json` shows the final `claude -p` invocation, whether `--effort`, `--settings`, `--allowedTools`, `--disallowedTools`, `--mcp-config`, or `--system-prompt-file` were included, and the resolved `limits` block for attempt timeout plus known turn ceiling.

package/docs/reference/runtime-config/codex.md

@@ -0,0 +1,82 @@
+# Codex Runtime Configuration
+
+Wave launches Codex with `codex exec` and pipes the generated task prompt through stdin.
+
+## Supported Configuration
+
+| Behavior | `wave.config.json` / profile key | Wave `### Executor` key | Launch effect |
+| --- | --- | --- | --- |
+| Command | `executors.codex.command`, `executors.profiles.<name>.codex.command` | `codex.command` | Selects the executable |
+| Sandbox | `executors.codex.sandbox`, `executors.profiles.<name>.codex.sandbox` | `codex.sandbox` | Sets `--sandbox`; if absent on a selected Codex agent, launcher `--codex-sandbox` can supply the runtime default |
+| CLI profile | `executors.codex.profileName`, `executors.profiles.<name>.codex.profileName` | `codex.profile_name` | Adds `--profile <name>` |
+| Inline config overrides | `executors.codex.config`, `executors.profiles.<name>.codex.config` | `codex.config` | Adds repeated `-c key=value` |
+| Search | `executors.codex.search`, `executors.profiles.<name>.codex.search` | `codex.search` | Adds `--search` |
+| Images | `executors.codex.images`, `executors.profiles.<name>.codex.images` | `codex.images` | Adds repeated `--image <path>` |
+| Extra directories | `executors.codex.addDirs`, `executors.profiles.<name>.codex.addDirs` | `codex.add_dirs` | Adds repeated `--add-dir <path>` |
+| JSON mode | `executors.codex.json`, `executors.profiles.<name>.codex.json` | `codex.json` | Adds `--json` |
+| Ephemeral session | `executors.codex.ephemeral`, `executors.profiles.<name>.codex.ephemeral` | `codex.ephemeral` | Adds `--ephemeral` |
+| Model | `executors.profiles.<name>.model` | `model` | Adds `--model <name>` |
+
+## Notes
+
+- There is no `executors.codex.model` key today. Use profile `model` or per-agent `model`.
+- Generic `budget.turns` does not set a Codex turn limit. If Codex stops on a turn ceiling, that limit came from the selected Codex profile or upstream Codex runtime, not from a Wave-emitted CLI flag.
+- Live runs still write `launch-preview.json`. If Codex later logs `Reached max turns (N)`, Wave records that observed ceiling under `limits.observedTurnLimit` with source `runtime-log`.
+- `codex.images`, `codex.add_dirs`, and `codex.config` accept either a string array in `wave.config.json` or a comma-separated list in a wave file.
+- Relative paths are passed to Codex relative to the repository root because Wave launches the executor from the repo workspace.
+
+## Example: `wave.config.json`
+
+```json
+{
+  "executors": {
+    "default": "codex",
+    "profiles": {
+      "implement-fast": {
+        "id": "codex",
+        "model": "gpt-5-codex",
+        "fallbacks": ["claude", "opencode"],
+        "budget": {
+          "minutes": 45
+        },
+        "codex": {
+          "profileName": "review",
+          "config": ["model_reasoning_effort=medium"],
+          "search": true
+        }
+      }
+    },
+    "codex": {
+      "command": "codex",
+      "sandbox": "danger-full-access",
+      "json": false,
+      "ephemeral": false
+    }
+  }
+}
+```
+
+## Example: Wave `### Executor`
+
+````md
+### Executor
+
+- id: codex
+- model: gpt-5-codex
+- codex.profile_name: review
+- codex.config: model_reasoning_effort=high,model_verbosity=low
+- codex.search: true
+- codex.images: docs/mock-ui.png
+- codex.add_dirs: ../shared,../infra
+- codex.json: true
+- codex.ephemeral: true
+````
+
+## Dry-Run Output
+
+For a dry run, inspect:
+
+- `launch-preview.json` for the final `codex exec` command
+- any referenced prompt file under `.tmp/<lane>-wave-launcher/dry-run/prompts/`
+
+The preview records the exact `--profile`, repeated `-c`, `--image`, and `--add-dir` flags that Wave would use in a live launch. It also includes a `limits` block that makes Wave's Codex visibility explicit: `turnLimitSource: "not-set-by-wave"` means Wave emitted no Codex turn-limit flag, so any effective ceiling is external to the Wave CLI invocation. On a live run, that same preview file may later gain `observedTurnLimit` if the Codex runtime reports the ceiling in its log output.

package/docs/reference/runtime-config/opencode.md

@@ -0,0 +1,93 @@
+# OpenCode Runtime Configuration
+
+Wave launches OpenCode with `opencode run` and points `OPENCODE_CONFIG` at a generated overlay.
+
+## Supported Configuration
+
+| Behavior | `wave.config.json` / profile key | Wave `### Executor` key | Launch effect |
+| --- | --- | --- | --- |
+| Command | `executors.opencode.command`, `executors.profiles.<name>.opencode.command` | `opencode.command` | Selects the executable |
+| Default model | `executors.opencode.model`, `executors.profiles.<name>.model` | `model` | Adds `--model <name>` |
+| Agent name | `executors.opencode.agent`, `executors.profiles.<name>.opencode.agent` | `opencode.agent` | Selects the injected agent name used with `--agent <name>` |
+| Single attachment | `executors.opencode.attach`, `executors.profiles.<name>.opencode.attach` | `opencode.attach` | Adds `--attach <path>` |
+| Multiple files | `executors.opencode.files`, `executors.profiles.<name>.opencode.files` | `opencode.files` | Adds repeated `--file <path>` |
+| Output format | `executors.opencode.format`, `executors.profiles.<name>.opencode.format` | `opencode.format` | Adds `--format default|json` |
+| Step limit | `executors.opencode.steps`, `executors.profiles.<name>.opencode.steps` | `opencode.steps` | Stored in the generated agent config |
+| Instructions | `executors.opencode.instructions`, `executors.profiles.<name>.opencode.instructions` | `opencode.instructions` | Merged into top-level `instructions` in the generated overlay |
+| Permission JSON | `executors.opencode.permission`, `executors.profiles.<name>.opencode.permission` | `opencode.permission` | Stored in the generated agent config |
+| Config overlay JSON | `executors.opencode.configJson`, `executors.profiles.<name>.opencode.configJson` | `opencode.config_json` | Deep-merged into the generated `opencode.json` |
+
+## Overlay Behavior
+
+Wave always writes:
+
+- `opencode-agent-prompt.txt`
+- `opencode.json`
+
+Merge order for `opencode.json`:
+
+1. inline `configJson` from config, profile, and agent resolution
+2. generated `$schema` if the merged config does not already define one
+3. merged top-level `instructions`
+4. generated or merged `agent.<resolved-name>` entry that points to `opencode-agent-prompt.txt`
+
+Wave then exports `OPENCODE_CONFIG=<generated-path>` for the run.
+
+## Example: `wave.config.json`
+
+```json
+{
+  "executors": {
+    "profiles": {
+      "ops-triage": {
+        "id": "opencode",
+        "model": "anthropic/claude-sonnet-4-20250514",
+        "budget": {
+          "turns": 8,
+          "minutes": 20
+        },
+        "opencode": {
+          "instructions": ["Keep findings concise."],
+          "permission": {
+            "task": "ask"
+          },
+          "configJson": {
+            "plugins": ["./plugins/runtime.mjs"]
+          }
+        }
+      }
+    },
+    "opencode": {
+      "command": "opencode",
+      "format": "default"
+    }
+  }
+}
+```
+
+## Example: Wave `### Executor`
+
+````md
+### Executor
+
+- id: opencode
+- model: anthropic/claude-sonnet-4-20250514
+- opencode.agent: docs-runner
+- opencode.attach: docs/plans/current-state.md
+- opencode.files: README.md,docs/plans/current-state.md
+- opencode.format: json
+- opencode.steps: 6
+- opencode.instructions: Keep shared-plan edits concise.
+- opencode.permission: {"task":"ask"}
+- opencode.config_json: {"plugins":["./plugins/runtime.mjs"]}
+````
+
+## Dry-Run Output
+
+For a dry run, inspect:
+
+- `opencode-agent-prompt.txt`
+- `opencode.json`
+- `launch-preview.json`
+
+`launch-preview.json` shows the final `opencode run` command, the exported `OPENCODE_CONFIG` path, and the resolved `limits` block for attempt timeout plus known step ceiling.

package/docs/reference/sample-waves.md

@@ -0,0 +1,105 @@
+---
+title: "Sample Waves"
+summary: "Showcase-first sample waves that demonstrate the shipped 0.8.9 authored surface, including the optional design-role path."
+---
+
+# Sample Waves
+
+This guide points to showcase-first sample waves that demonstrate the shipped `0.8.9` authored Wave surface.
+
+The examples are intentionally denser than typical production waves. Their job is to teach the current authoring and runtime surface quickly, not to be the smallest possible launch-ready files.
+
+## Canonical Examples
+
+- [High-fidelity repo-landed rollout wave](../plans/examples/wave-example-rollout-fidelity.md)
+  Shows what a good `repo-landed` outcome looks like when one promoted component only closes honestly if desired-state records, reconcile-loop substrate, and cluster-view surfaces land together. It emphasizes maturity discipline, explicit deliverables, and shared-plan closure without drifting into `pilot-live` claims.
+
+- [Full modern sample wave](../plans/examples/wave-example-live-proof.md)
+  Shows the combined `0.8.9` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
+
+- [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md)
+  Shows the shipped design-role surface: one pre-implementation design steward publishes a design packet, downstream implementation owners read that packet before coding, and normal closure roles still decide final completion. For terminal or operator-surface work, pair that shape with explicit `tui-design` in the design steward's `### Skills`. For the hybrid variant, explicitly give that same design agent implementation-owned paths and the normal implementation contract sections.
+
+## What These Examples Teach
+
+- the standard closure-role structure with `A0`, `A8`, and `A9`
+- `E0` and wave-level `## Eval targets` in the full modern sample
+- honest `repo-landed` maturity framing without `pilot-live` drift
+- multi-slice component promotion where all sibling owners must land together
+- shared-plan and component-matrix closure as part of the architecture truth
+- delegated versus pinned benchmark selection
+- coordination benchmark families from `docs/evals/benchmark-catalog.json`
+- richer executor blocks, runtime budgets, and retry policy
+- cross-runtime `### Skills`
+- helper-routing hints via `### Capabilities`
+- `### Deliverables`
+- `### Exit contract`
+- proof-first `### Proof artifacts`
+- sticky retry for proof-bearing owners
+- deploy environments and provider-skill examples
+- infra and deploy-verifier specialist slices
+- optional pre-implementation design packets and design-to-implementation handoff
+
+## Feature Coverage Map
+
+Together these samples cover the main surfaces added or hardened through `0.8.9`:
+
+- repo-landed maturity discipline and anti-overclaim framing
+- explicit shared-plan closure for future-wave safety
+- coordinated component slices with per-agent deliverables
+- planner-era authored wave structure
+- cross-runtime `### Skills`
+- richer `### Executor` blocks and runtime budgets
+- `cont-EVAL` plus `## Eval targets`
+- delegated and pinned benchmark selection
+- coordination benchmark families from `docs/evals/benchmark-catalog.json`
+- helper-routing hints through `### Capabilities`
+- `### Deliverables`
+- `### Proof artifacts`
+- sticky retry for proof-bearing owners
+- proof-first live-wave prompts
+- deploy environments and deploy-kind-aware skills
+- integration, documentation, and cont-QA closure-role structure
+- optional `design` worker role and `design-pass` executor profile
+
+## When To Copy Literally Vs Adapt
+
+Copy more literally when:
+
+- you need the section layout
+- you want a concrete example of what good repo-landed wave fidelity looks like
+- you want concrete wording for delegated versus pinned benchmark targets
+- you want a proof-first owner example with local artifact bundles and sticky retry
+
+Adapt more aggressively when:
+
+- your repo has different role ids or role prompts
+- your component promotions and maturity levels differ
+- your runtime policy uses different executor profiles or runtime mix targets
+- your deploy environments or provider skills differ from the example
+
+## How This Example Maps To Other Docs
+
+- Use [docs/guides/planner.md](../guides/planner.md) for the planner-generated baseline, then use these samples to see how a human would enrich the generated draft for either repo-landed or proof-first work.
+- Use [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md) when the wave should start with a reusable design packet before implementation begins.
+- Use [docs/evals/README.md](../evals/README.md) with the full modern sample when you need to see delegated and pinned benchmark targets in a real wave.
+- Use [docs/reference/live-proof-waves.md](./live-proof-waves.md) with the full modern sample when you need proof-first authoring for `pilot-live` and above.
+- Use [docs/plans/wave-orchestrator.md](../plans/wave-orchestrator.md) for the operational runbook that explains how the launcher interprets these sections.
+
+## Suggested Reading Order
+
+1. Start with [High-fidelity repo-landed rollout wave](../plans/examples/wave-example-rollout-fidelity.md) if you want the clearest example of good closure-ready wave fidelity for a repo-only outcome.
+2. Read [Full modern sample wave](../plans/examples/wave-example-live-proof.md) if you want the denser proof-first and eval-heavy `0.8.9` surface.
+3. Read [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md) if the task needs a design packet before implementation fan-out.
+4. Read [docs/evals/README.md](../evals/README.md) if you want more background on benchmark target selection.
+5. Read [docs/reference/live-proof-waves.md](./live-proof-waves.md) if you want more detail on proof-first `pilot-live` authoring.
+
+## Why These Examples Live In `docs/plans/examples/`
+
+The examples live outside `docs/plans/waves/` on purpose.
+
+That keeps it:
+
+- easy to browse as teaching material
+- clearly separate from the repo's real launcher-facing wave sequence
+- safe to evolve as reference material without implying that they are part of the current lane's actual plan history

package/docs/reference/skills.md

@@ -0,0 +1,237 @@
+# Skills Reference
+
+Skills are repo-owned reusable instruction bundles. Wave resolves them by config layer, then filters them through each bundle's activation metadata before projecting them into the selected runtime.
+They shape runtime behavior, but they are not part of the canonical authority set.
+
+## Canonical Bundle Layout
+
+Each bundle lives under `skills/<skill-id>/` and requires:
+
+- `skill.json`
+- `SKILL.md`
+
+Optional files:
+
+- `adapters/codex.md`
+- `adapters/claude.md`
+- `adapters/opencode.md`
+- `adapters/local.md`
+- `references/**` for on-demand reference material
+
+Minimal example:
+
+```text
+skills/provider-railway/
+  skill.json
+  SKILL.md
+  adapters/
+    codex.md
+    claude.md
+    opencode.md
+  references/
+    verification-commands.md
+```
+
+## `skill.json`
+
+Required fields:
+
+- `id`
+- `title`
+- `description`
+- `activation.when`
+
+Optional fields:
+
+- `version`
+- `tags`
+- `activation.roles`
+- `activation.runtimes`
+- `activation.deployKinds`
+- `termination.when`
+- `permissions.network`
+- `permissions.shell`
+- `permissions.mcpServers`
+- `trust.tier`
+- `evalCases[]`
+
+Example:
+
+```json
+{
+  "id": "provider-railway",
+  "title": "Railway",
+  "description": "Provider-aware Railway verification and rollback guidance.",
+  "activation": {
+    "when": "Attach when the wave deploy surface is Railway and the agent is acting in deploy, infra, integration, or cont-qa scope.",
+    "roles": ["deploy", "infra", "integration", "cont-qa"],
+    "runtimes": [],
+    "deployKinds": ["railway-cli", "railway-mcp"]
+  },
+  "termination": "Stop when Railway evidence is recorded or the blocking surface is explicit.",
+  "permissions": {
+    "network": ["railway.app"],
+    "shell": ["railway"],
+    "mcpServers": ["railway"]
+  },
+  "trust": {
+    "tier": "repo-owned"
+  },
+  "evalCases": [
+    {
+      "id": "deploy-railway-cli",
+      "role": "deploy",
+      "runtime": "opencode",
+      "deployKind": "railway-cli",
+      "expectActive": true
+    }
+  ]
+}
+```
+
+The bundle directory name and manifest `id` must match the normalized skill id.
+
+## `SKILL.md`
+
+`SKILL.md` is the canonical instruction body. Keep it reusable and procedural:
+
+- reusable across many waves
+- free of assignment-specific details that belong in the wave prompt
+- compact enough that long catalogs and command references can move into `references/`
+
+## `wave.config.json` Surface
+
+Top-level and lane-local skill attachment use the same shape:
+
+```json
+{
+  "skills": {
+    "dir": "skills",
+    "base": ["wave-core", "repo-coding-rules"],
+    "byRole": {
+      "design": ["role-design"],
+      "deploy": ["role-deploy"]
+    },
+    "byRuntime": {
+      "claude": ["runtime-claude"]
+    },
+    "byDeployKind": {
+      "railway-mcp": ["provider-railway"]
+    }
+  }
+}
+```
+
+Lane-local `lanes.<lane>.skills` extends the global config instead of replacing it.
+
+Optional design workers in the shipped `0.8.9` surface normally attach `role-design`. That bundle is intended for docs/spec-first design packets and explicit implementation handoff work before implementation starts. When the design packet covers terminal UX, dashboards, or other operator surfaces, add `tui-design` explicitly in the wave's `### Skills`.
+
+## Resolution Order
+
+Resolved skills are gathered in this order:
+
+1. global `skills.base`
+2. lane `skills.base`
+3. global `skills.byRole[resolvedRole]`
+4. lane `skills.byRole[resolvedRole]`
+5. global `skills.byRuntime[resolvedExecutorId]`
+6. lane `skills.byRuntime[resolvedExecutorId]`
+7. global `skills.byDeployKind[defaultDeployEnvironmentKind]`
+8. lane `skills.byDeployKind[defaultDeployEnvironmentKind]`
+9. agent `### Skills`
+
+Then Wave applies manifest activation filtering:
+
+- configured skills only stay active if their `activation.roles`, `activation.runtimes`, and `activation.deployKinds` match the agent context
+- explicit agent `### Skills` still attach even if activation metadata would not auto-match
+
+Duplicates are removed while preserving first-seen order.
+
+## Deploy-Kind Attachment
+
+Deploy-kind mapping uses the wave's default deploy environment from `## Deploy environments`.
+
+If the wave declares:
+
+````md
+## Deploy environments
+
+- `prod`: `railway-mcp` default
+````
+
+then `byDeployKind.railway-mcp` skills become eligible for that wave. Whether they actually attach still depends on each bundle's activation metadata.
+
+Config-time validation rules:
+
+- `skills.byRole` keys must be supported Wave roles
+- `skills.byRuntime` keys must be supported runtimes
+- `skills.byDeployKind` keys are validated by `wave doctor` against built-in kinds plus kinds declared in wave files
+
+Built-in deploy kinds shipped by the starter profile are:
+
+- `railway-cli`
+- `railway-mcp`
+- `docker-compose`
+- `kubernetes`
+- `ssh-manual`
+- `custom`
+- `aws`
+- `github-release`
+
+## Runtime Projection
+
+Wave now projects skills metadata-first:
+
+- `skills.resolved.md` is a compact catalog with bundle summaries, activation scope, permissions, manifest paths, adapter paths, and available references
+- `skills.expanded.md` contains the full canonical `SKILL.md` bodies plus runtime adapters for debugging and audit
+
+Runtime delivery:
+
+- Codex
+  Bundle directories become `--add-dir` inputs. The compact catalog stays in the compiled prompt, and the agent can read bundle files directly from disk.
+- Claude
+  The compact catalog is appended to the generated system-prompt overlay.
+- OpenCode
+  The compact catalog is injected into `opencode.json`, and `skill.json`, `SKILL.md`, the selected adapter, and every recursive `references/**` file are attached through `--file`.
+- Local
+  The compact catalog stays prompt-only.
+
+These runtime projections are guidance surfaces. They should stay aligned with the canonical authority model, but they are not replay inputs or decision state on their own.
+
+For the optional `design` worker role, the default pattern is:
+
+- `role-design` for the design packet contract
+- `tui-design` only when the packet covers terminal UX, dashboards, or other operator surfaces
+- no runtime-specific coding bundle unless the wave explicitly gives the design steward code ownership and makes it a hybrid design steward
+
+## Generated Artifacts
+
+Executor overlay directories can contain:
+
+- `skills.resolved.md`
+- `skills.expanded.md`
+- `skills.metadata.json`
+- `<runtime>-skills.txt`
+
+Dry-run `launch-preview.json` and live trace metadata also record the resolved skill ids, bundle metadata, hashes, activation metadata, and artifact paths.
+
+## Validation
+
+`wave doctor` validates the skill surface end to end:
+
+- referenced bundles exist and load
+- every bundle under the skills directory has a valid manifest and `SKILL.md`
+- `skills.byRole`, `skills.byRuntime`, and `skills.byDeployKind` selectors are valid
+- config mapping does not contradict manifest activation metadata
+- every shipped `evalCases[]` route resolves to the expected active or inactive outcome
+
+Missing or malformed bundles are configuration errors, not silent no-ops.
+
+## Best Practices
+
+- Keep `SKILL.md` procedural and move long catalogs into `references/`.
+- Put routing intent into `activation.*`, not only prose.
+- Use explicit per-agent `### Skills` for true exceptions, not as a substitute for missing activation metadata.
+- Keep provider skills role-scoped unless every role genuinely needs the provider context.
+- Keep bundle ids stable so traces and prompt fingerprints remain intelligible across runs.
+- Keep `role-design` docs/spec-first by default; add `tui-design` when terminal or operator-surface work is in scope, and only attach broader coding bundles when the wave explicitly assigns code ownership and expects the same design steward to return for implementation.