@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

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

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

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

@@ -1,105 +0,0 @@
----
-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

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