@beyondwork/docx-react-component 1.0.0

package/docs/reference/public-api.md

@@ -0,0 +1,456 @@
+# Public API
+
+This file defines the intended public API for the shipped docx React component.
+
+Within the broader `react-ooxml-office` repo story, this remains a format-specific contract:
+
+- it describes the current `docx` implementation only
+- it does not define a neutral multi-format editor API
+- future `xlsx` or other verticals should gain sibling API docs rather than silently widening `WordReviewEditor`
+
+## Public Component
+
+```tsx
+<WordReviewEditor />
+```
+
+The repo standardizes on `WordReviewEditor` as the public name across docs, source, and services.
+
+Internal harness routes, Railway demo pages, certification dashboards, and other operator-facing surfaces are not part of the public component API. They may exercise the same runtime, but they are documentation, proof, or demo surfaces rather than shipped host contracts.
+
+## Public Contracts
+
+The implementation should expose:
+
+- `WordReviewEditor`
+- `WordReviewEditorProps`
+- `WordReviewEditorRef`
+- `EditorUser`
+- `EditorDatastoreAdapter`
+- `PersistedEditorSnapshot`
+- `CompatibilityReport`
+- `EditorWarning`
+- `EditorError`
+- `WordReviewEditorEvent`
+
+The runtime-facing internal session type is `DocumentRuntime`. `WordEditor` is not a shipped public name.
+
+## Usage Model
+
+The component is uncontrolled by default.
+
+Host responsibilities:
+
+- provide `documentId`
+- provide `currentUser`
+- provide exactly one initial source on first load: `initialDocx` or `initialSnapshot`
+- optionally provide a datastore adapter
+- optionally listen to events, warnings, and errors
+
+Runtime responsibilities:
+
+- own the live editing session
+- apply commands and transactions
+- manage undo and redo
+- manage comments and revisions
+- expose review-ready runtime snapshot projections for the document surface, comment sidebar, revision sidebar, and compatibility surfaces
+- provide export and compatibility reporting
+
+Controlled behavior is intentionally narrow:
+
+- hosts may replace the active document only through `externalDocumentRevision` plus `externalDocSource`
+- when the revision token changes, the editor tears down the current session and reloads the new source
+- hosts do not stream keystrokes or partial selections back into props
+
+## Ref Surface
+
+The ref should support:
+
+- `focus()`
+- `blur()`
+- `undo()`
+- `redo()`
+- `addComment(...)`
+- `openComment(commentId)`
+- `resolveComment(commentId)`
+- `reopenComment(commentId)`
+- `addCommentReply(commentId, body)`
+- `editCommentBody(commentId, body)`
+- `acceptChange(changeId)`
+- `rejectChange(changeId)`
+- `acceptAllChanges()`
+- `rejectAllChanges()`
+- `exportDocx(options?)`
+- `getSnapshot()`
+- `getCompatibilityReport()`
+- `getWarnings()`
+
+The ref is a thin wrapper over the runtime. It does not expose DOM nodes or mutable canonical state.
+
+## Props Surface
+
+```ts
+type ExternalDocumentSource =
+  | {
+      kind: "docx";
+      bytes: Uint8Array | ArrayBuffer;
+      sourceLabel?: string;
+    }
+  | {
+      kind: "snapshot";
+      snapshot: PersistedEditorSnapshot;
+      sourceLabel?: string;
+    };
+
+interface WordReviewEditorProps {
+  documentId: string;
+  currentUser: EditorUser;
+
+  initialDocx?: Uint8Array | ArrayBuffer;
+  initialSnapshot?: PersistedEditorSnapshot;
+  initialSourceLabel?: string;
+
+  externalDocumentRevision?: string;
+  externalDocSource?: ExternalDocumentSource;
+
+  readOnly?: boolean;
+  reviewMode?: "editing" | "review";
+
+  // reviewMode behavior:
+  // - "editing" (default in some contexts): Reduces review chrome. Review rail hidden by default. Editing controls primary.
+  // - "review" (default): Review rail visible. Comments and changes are prominent.
+  // - Both modes keep health/trust information reachable and fatal errors always visible.
+  // - reviewMode does NOT control editing capability — use readOnly for that.
+
+  markupDisplay?: "clean" | "simple" | "all";
+  // markupDisplay is accepted for backward compatibility but is now
+  // derived internally from the editor's view mode (canvas → clean,
+  // document → all). The editor manages viewMode as internal state;
+  // it is not a public prop on WordReviewEditorProps.
+
+  datastore?: EditorDatastoreAdapter;
+  autosave?: AutosaveConfig;
+
+  onEvent?: (event: WordReviewEditorEvent) => void;
+  onWarning?: (warning: EditorWarning) => void;
+  onError?: (error: EditorError) => void;
+}
+```
+
+Load rules:
+
+- provide exactly one of `initialDocx` or `initialSnapshot` for an explicit initial load
+- `externalDocumentRevision` plus `externalDocSource` is the only replace-on-change path
+- if the external revision token does not change, props do not mutate the live session
+- `initialDocx` now boots a real package-backed session, not a text-only fallback snapshot
+- malformed or unreadable package bytes fail closed into diagnostics/read-only mode with export blocked
+
+## Planned AI Action Extension
+
+This contract is reserved for the post-v1 roadmap and is not part of the
+currently shipped public surface in `src/api/public-types.ts`.
+
+The intended shape is:
+
+- the host supplies the model access or action executor
+- the runtime packages canonical context such as selection, section bounds, anchors, comment threads, revisions, compatibility warnings, and edit capabilities
+- AI actions target bounded legal-review workflows rather than arbitrary document mutation
+- content-changing results come back as proposals or runtime command requests that must pass normal validation, compatibility, and export gates
+- the UI must present explicit review/confirmation affordances before applying content-changing proposals
+
+Illustrative direction:
+
+```ts
+type PlannedWordReviewEditorAiAction =
+  | "edit_selection"
+  | "rewrite_section"
+  | "summarize_comments"
+  | "suggest_comment_response"
+  | "resolve_comment_thread"
+  | "apply_drafting_instruction"
+  | "validate_and_export";
+
+interface PlannedWordReviewEditorAiRequest {
+  action: PlannedWordReviewEditorAiAction;
+  instruction?: string;
+  selection?: SelectionSnapshot;
+  anchor?: EditorAnchorProjection;
+  commentIds?: string[];
+  revisionIds?: string[];
+  compatibility: CompatibilityReport;
+  capabilities: {
+    readOnly: boolean;
+    canEdit: boolean;
+    canExport: boolean;
+  };
+}
+
+interface PlannedWordReviewEditorAiAdapter {
+  runAction(
+    request: PlannedWordReviewEditorAiRequest,
+  ): Promise<
+    | {
+        kind: "proposal";
+        summary: string;
+        requiresConfirmation: true;
+      }
+    | {
+        kind: "workflow";
+        workflow: "validate_and_export";
+      }
+    | {
+        kind: "rejected";
+        reason: string;
+      }
+  >;
+}
+```
+
+Guardrails for the planned surface:
+
+- no built-in model client ships inside `WordReviewEditor`
+- no direct DOM writes or direct canonical-state mutation from model output
+- no bypass around permissions, protected ranges, compatibility warnings, or export blockers
+- no implication that unsupported OOXML becomes editable just because an AI action exists
+
+## Encrypted Source Handling
+
+The active component contract does not include editor-owned handling for password-to-open Office containers, and encrypted intake is not part of the active wave roadmap.
+
+Hosts must provide one of:
+
+- normal OPC `.docx` bytes through `initialDocx`
+- normal OPC `.docx` bytes through `externalDocSource.kind = "docx"`
+- a canonical snapshot
+
+If an upstream system accepts encrypted Office containers, it must decrypt or otherwise preprocess them before handing bytes to `WordReviewEditor`. Reintroducing editor-owned encrypted intake would require an explicit public-API revision rather than a silent expansion of the current load surface.
+
+## Runtime Snapshot Direction
+
+The host-facing persisted snapshot is still `PersistedEditorSnapshot`.
+
+The live UI should render from `RuntimeRenderSnapshot`, not by reconstructing review state from persisted data during render. In particular:
+
+- the comment sidebar reads runtime-owned thread projections, detached/open/resolved counts, and the active thread id from `RuntimeRenderSnapshot.comments`
+- the tracked-change sidebar reads runtime-owned revision projections, actionability flags, and batch counts from `RuntimeRenderSnapshot.trackedChanges`
+- compatibility surfaces read explicit blocking reasons from `RuntimeRenderSnapshot.compatibility`
+
+Selectors may reshape those projections for presentation, but they must not invent a second source of live review truth.
+
+Current boundary note:
+
+- `SelectionSnapshot`, `EditorAnchorProjection`, and `EditorSurfaceSnapshot` still describe the current flat paragraph/opaque-block runtime.
+- Imported body-level tables remain preserve-only in the live editor path.
+- Future post-v1 waves must revise these contracts explicitly as new slices become `read-only projected`, `bounded editable`, or fully owned rather than silently widening the current public types.
+
+## Event Surface
+
+The canonical host event stream is a discriminated union:
+
+```ts
+type WordReviewEditorEvent =
+  | {
+      type: "ready";
+      documentId: string;
+      sessionId: string;
+      source: "docx" | "snapshot" | "datastore" | "canonical";
+      stats: DocumentStats;
+      compatibility: CompatibilityReport;
+    }
+  | {
+      type: "dirty_changed";
+      documentId: string;
+      isDirty: boolean;
+    }
+  | {
+      type: "selection_changed";
+      documentId: string;
+      selection: SelectionSnapshot;
+    }
+  | {
+      type: "comment_added";
+      documentId: string;
+      commentId: string;
+      anchor: EditorAnchorProjection;
+    }
+  | {
+      type: "comment_resolved";
+      documentId: string;
+      commentId: string;
+    }
+  | {
+      type: "change_accepted";
+      documentId: string;
+      changeId: string;
+    }
+  | {
+      type: "change_rejected";
+      documentId: string;
+      changeId: string;
+    }
+  | {
+      type: "warning_added";
+      documentId: string;
+      warning: EditorWarning;
+    }
+  | {
+      type: "warning_cleared";
+      documentId: string;
+      warningId: string;
+      code: EditorWarning["code"];
+    }
+  | {
+      type: "error";
+      documentId: string;
+      error: EditorError;
+    }
+  | {
+      type: "autosave_state";
+      documentId: string;
+      state: AutosaveState;
+    }
+  | {
+      type: "snapshot_saved";
+      documentId: string;
+      snapshot: PersistedEditorSnapshot;
+      isAutosave: boolean;
+    }
+  | {
+      type: "export_completed";
+      documentId: string;
+      result: ExportResult;
+    };
+```
+
+Event delivery rules:
+
+- each mounted runtime load emits exactly one `ready` event
+- hosts should treat `ready` as the authoritative session-start marker rather than inferring load completion from render timing
+
+Planned AI-event direction:
+
+- a future AI extension may add runtime-owned events such as `ai_action_started`, `ai_action_proposed`, `ai_action_applied`, and `ai_action_failed`
+- those events are not part of the current shipped `WordReviewEditorEvent` union and should not be exposed until the AI contract lands as a deliberate API revision
+
+## Warnings And Errors
+
+```ts
+type EditorAnchorProjection =
+  | {
+      kind: "range";
+      from: number;
+      to: number;
+      assoc: {
+        start: -1 | 1;
+        end: -1 | 1;
+      };
+    }
+  | {
+      kind: "node";
+      at: number;
+      assoc: -1 | 1;
+    }
+  | {
+      kind: "detached";
+      lastKnownRange: {
+        from: number;
+        to: number;
+      };
+      reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
+    };
+
+interface EditorWarning {
+  warningId: string;
+  code:
+    | "unsupported_ooxml_preserved"
+    | "unsupported_ooxml_locked"
+    | "import_normalized"
+    | "export_roundtrip_risk"
+    | "comment_anchor_detached"
+    | "revision_anchor_detached"
+    | "large_document_degraded"
+    | "font_substitution"
+    | "image_missing";
+  severity: "info" | "warning";
+  message: string;
+  source:
+    | "import"
+    | "runtime"
+    | "review"
+    | "preservation"
+    | "validation"
+    | "export";
+  affectedAnchor?: EditorAnchorProjection;
+  featureEntryId?: string;
+  details?: Record<string, unknown>;
+}
+
+interface EditorError {
+  errorId: string;
+  code:
+    | "import_failed"
+    | "export_failed"
+    | "package_corrupt"
+    | "validation_failed"
+    | "datastore_failed"
+    | "internal_invariant";
+  message: string;
+  isFatal: boolean;
+  source:
+    | "import"
+    | "runtime"
+    | "validation"
+    | "datastore"
+    | "export";
+  details?: Record<string, unknown>;
+}
+```
+
+Range references are runtime-derived projections over canonical positions. DOM paths are not part of the public contract.
+
+## Persistence Model
+
+The datastore adapter should support:
+
+- loading the latest snapshot or source document
+- saving fast JSON checkpoints
+- saving exported `.docx` artifacts
+- optional telemetry emission
+
+The persisted resume artifact is:
+
+```ts
+interface PersistedEditorSnapshot {
+  snapshotVersion: "persisted-editor-snapshot/1";
+  schemaVersion: "cds/1.0.0";
+  documentId: string;
+  docId: string;
+  createdAt: string;
+  updatedAt: string;
+  savedAt: string;
+  editorBuild: string;
+  canonicalDocument: CanonicalDocument;
+  compatibility: CompatibilityReport;
+  warningLog: EditorWarning[];
+}
+
+interface CompatibilityReport {
+  reportVersion: "compatibility-report/1";
+  generatedAt: string;
+  blockExport: boolean;
+  featureEntries: CompatibilityFeatureEntry[];
+  warnings: EditorWarning[];
+  errors: EditorError[];
+}
+```
+
+Persistence rules:
+
+- `getSnapshot()` returns `PersistedEditorSnapshot`
+- loading a snapshot resumes canonical state without rerunning `.docx` import
+- render snapshots are internal runtime projections and are not a persistence contract
+- manual export first saves a non-autosave snapshot checkpoint through `datastore.saveSnapshot(...)`
+- if that manual checkpoint fails, export is rejected and `saveExport(...)` is not attempted
+- autosave timers are scoped to the current revision token, so a successful manual export checkpoint clears any pending autosave for the same revision
+
+The host does not stream keystrokes through props. Replace-on-change is the only supported controlled pattern.

package/docs/reference/repository-guidance.md

@@ -0,0 +1,58 @@
+# Repository Guidance
+
+Use this page as the default in-repo guidance for product and architecture work.
+
+## Defaults
+
+- Keep host-format fidelity as the top-level product invariant.
+- Treat runtime-owned structured state as the canonical source of truth.
+- Route all edits through commands and transactions; do not patch DOM state directly and call it authoritative.
+- Preserve unsupported but preservable OOXML whenever possible; never silently drop unknown content.
+- Keep file ownership explicit in plans, waves, and ad-hoc prompts.
+- Prefer small, reviewable changes over broad speculative rewrites.
+- Update impacted docs when interfaces, scope, component maturity, or proof expectations change.
+- Keep maturity docs aligned with real subsystem status rather than narrative progress.
+- Run the relevant validation commands or fixture checks for touched surfaces.
+- Treat external docs as non-canonical unless the task is explicitly about third-party APIs or OOXML behavior.
+
+## Layered Repo Rules
+
+- The only shipped implementation today is the docx runtime behind `WordReviewEditor`.
+- Shared platform docs may broaden before the source tree does; do not misrepresent planned structure as landed code.
+- `xlsx` planning work should align to the shared OOXML platform doctrine without copying docx-specific UI or ProseMirror assumptions into spreadsheet architecture.
+- `pdf` may appear in repo-level planning, but it is not part of the first shared OOXML platform contract.
+
+## Current Docx Rules
+
+- The current shipped editor is not a Word clone. Keep UI clean, contextual, and minimal.
+- The repo is still optimized around legal-review workflows in the landed docx runtime. Comments, redlines, lists, tables, and safe round-trip behavior matter more than cosmetic formatting breadth.
+- Follow `DESIGN.md` for current docx layout, token, and interaction decisions.
+- Default visual posture is calm, precise, and review-oriented.
+- Prefer canvas mode as the baseline review experience; page mode is optional and secondary.
+- Keep the document surface central. Toolbars, sidebars, and status surfaces should support it, not compete with it.
+- Separate canonical content, review state, preservation layer, UI state, and OOXML import or export boundaries.
+- The shipped editor runs in the main thread with no Web Workers.
+- The Microsoft Open XML SDK must not be pulled into the shipped React bundle. Use it only in CI or internal validation services.
+
+## Validation Bias
+
+When making architecture decisions, prefer proofs that increase confidence in:
+
+- current docx import safety
+- current docx export safety
+- Word reopen compatibility for shipped flows
+- future Excel reopen compatibility for planned xlsx flows
+- anchor and range remapping stability
+- preservation of unsupported content
+- adherence to the token-driven design system when UI surfaces are touched
+
+## Update These Docs When Behavior Changes
+
+- `docs/plans/master-plan.md`
+- `docs/plans/current-state.md`
+- `docs/roadmap.md`
+- `docs/plans/component-cutover-matrix.md`
+- `docs/plans/waves/README.md`
+- `docs/reference/public-api.md` when the shipped docx public behavior changes
+- `docs/reference/ooxml-compliance.md` for shipped docx compatibility changes
+- `docs/reference/xlsx/xlsx-ooxml-compliance.md` for planned xlsx contract changes

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

@@ -0,0 +1,182 @@
+# Runtime Configuration Reference
+
+This directory is the canonical reference for executor configuration in the packaged Wave release.
+
+Use it when you need the full supported surface for:
+
+- `wave.config.json`
+- `lanes.<lane>.executors`
+- `waveControl`
+- `executors.profiles.<profile>`
+- per-agent `### Executor` blocks inside a wave file
+
+## Naming Conventions
+
+- `wave.config.json` uses camelCase keys such as `profileName`, `addDirs`, `settingsJson`, and `allowedHttpHookUrls`.
+- Wave markdown `### Executor` blocks use snake_case after the runtime prefix, such as `codex.profile_name`, `codex.add_dirs`, `claude.settings_json`, and `claude.allowed_http_hook_urls`.
+
+## Resolution Order
+
+Executor id selection resolves in this order:
+
+1. agent `### Executor` `id`
+2. agent `### Executor` `profile` -> `executors.profiles.<profile>.id`
+3. `lanes.<lane>.runtimePolicy.defaultExecutorByRole`
+4. launcher `--executor`
+5. `executors.default`
+
+Runtime settings resolve in layers:
+
+1. `executors.<runtime>` global defaults
+2. `lanes.<lane>.executors.<runtime>` lane overrides
+3. `executors.profiles.<profile>` or `lanes.<lane>.executors.profiles.<profile>`
+4. agent `### Executor`
+
+Merge behavior:
+
+- scalar values override from later layers
+- list values merge for profile plus agent resolution on top of the lane base
+- lane executor overrides replace the corresponding global runtime fields before profile and agent resolution
+- a lane profile with the same name as a global profile replaces that profile definition for the lane
+
+Skill settings resolve after executor selection, because runtime and deploy-kind skill attachment depend on the resolved executor id and the wave's default deploy environment kind. The starter layering order is:
+
+1. `skills.base`
+2. `lanes.<lane>.skills.base`
+3. `skills.byRole[resolvedRole]`
+4. `lanes.<lane>.skills.byRole[resolvedRole]`
+5. `skills.byRuntime[resolvedExecutorId]`
+6. `lanes.<lane>.skills.byRuntime[resolvedExecutorId]`
+7. `skills.byDeployKind[defaultDeployEnvironmentKind]`
+8. `lanes.<lane>.skills.byDeployKind[defaultDeployEnvironmentKind]`
+9. agent `### Skills`
+
+Then Wave filters configured skills through each bundle's activation metadata. Explicit per-agent `### Skills` still force attachment even when activation metadata would not auto-match.
+
+When retry-time fallback changes the runtime, Wave recomputes the effective skill set and rewrites the executor overlay before relaunch.
+
+## Common Fields
+
+These fields are shared across runtimes:
+
+| Surface | `wave.config.json` / profile key | Wave `### Executor` key | Notes |
+| --- | --- | --- | --- |
+| Executor id | `id` in profile only | `id` | Runtime id: `codex`, `claude`, `opencode`, `local` |
+| Profile selection | n/a | `profile` | Selects `executors.profiles.<name>` |
+| Model | `model` in profile, `executors.claude.model`, `executors.opencode.model` | `model` | Codex uses shared `model` from profile or agent only |
+| Fallbacks | `fallbacks` in profile | `fallbacks` | Runtime ids used for retry-time reassignment |
+| Tags | `tags` in profile | `tags` | Stored in resolved executor state for policy and traces |
+| Budget turns | `budget.turns` in profile | `budget.turns` | Advisory generic turn budget. Wave records it in resolved metadata, but only runtime-specific settings such as `claude.maxTurns` or `opencode.steps` emit hard turn-limit flags. It does not set a Codex turn limit. |
+| Budget minutes | `budget.minutes` in profile | `budget.minutes` | Primary wall-clock attempt budget |
+
+Practical guidance:
+
+- prefer `budget.minutes` for normal synthesis, integration, and closure work
+- use generic `budget.turns` as a planning hint, not a hard failure trigger
+- only set `claude.maxTurns` or `opencode.steps` when you deliberately want a hard ceiling for that runtime
+- see [../../guides/recommendations-0.8.9.md](../../guides/recommendations-0.8.9.md) for the recommended `0.8.9` operating stance that combines advisory turn budgets with softer non-proof coordination states
+
+## Runtime Pages
+
+- [codex.md](./codex.md)
+- [claude.md](./claude.md)
+- [opencode.md](./opencode.md)
+
+## Wave Control
+
+`wave.config.json` may also declare a `waveControl` block for local-first telemetry delivery.
+
+Supported top-level fields:
+
+| Key | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `enabled` | boolean | `true` | Master switch for local queueing and remote delivery |
+| `endpoint` | string | unset | Base URL for the Railway-hosted `services/wave-control` API |
+| `workspaceId` | string | derived from repo path | Stable workspace identity used across runs |
+| `projectId` | string | derived from `projectName` | Stable project/repo identity used for cross-workspace reporting and filtering |
+| `authTokenEnvVar` | string | `WAVE_CONTROL_AUTH_TOKEN` | Environment variable name holding the bearer token |
+| `reportMode` | string | `metadata-plus-selected` | `disabled`, `metadata-only`, `metadata-plus-selected`, or `full-artifact-upload` |
+| `uploadArtifactKinds` | string[] | selected proof/trace/benchmark kinds | Artifact classes eligible for body upload when an artifact's upload policy requests a body |
+| `requestTimeoutMs` | integer | `5000` | Per-batch network timeout |
+| `flushBatchSize` | integer | `25` | Max queued telemetry events flushed per batch |
+| `maxPendingEvents` | integer | `1000` | Cap for pending remote-delivery queue files; oldest pending uploads are dropped from the remote queue while the local `events.jsonl` stream remains authoritative |
+| `captureCoordinationRecords` | boolean | `true` | Emit `coordination_record` telemetry |
+| `captureControlPlaneEvents` | boolean | `true` | Emit `wave_run`, `attempt`, `proof_bundle`, and related control-plane events |
+| `captureTraceBundles` | boolean | `true` | Emit finalized trace-bundle artifacts and gate snapshots |
+| `captureBenchmarkRuns` | boolean | `true` | Emit `benchmark_run`, `benchmark_item`, `verification`, and `review` events |
+
+Lane overrides may refine the same keys under `lanes.<lane>.waveControl`.
+
+One-run override:
+
+- `wave launch --no-telemetry` disables Wave Control queueing and remote delivery for that launcher invocation without changing the repo config.
+
+Example:
+
+```json
+{
+  "waveControl": {
+    "endpoint": "https://wave-control.up.railway.app/api/v1",
+    "workspaceId": "wave-main",
+    "projectId": "wave-orchestration",
+    "reportMode": "metadata-plus-selected",
+    "uploadArtifactKinds": [
+      "trace-run-metadata",
+      "trace-quality",
+      "benchmark-results"
+    ]
+  }
+}
+```
+
+Runtime-emitted Wave Control events also attach:
+
+- `orchestratorId` from the active launcher or resident orchestrator
+- `runtimeVersion` from the installed Wave package metadata
+
+Those fields are queryable in the `wave-control` service alongside `workspaceId`,
+`projectId`, `runKind`, `runId`, `lane`, and benchmark ids.
+
+See [../wave-control.md](../wave-control.md) for the event contract and upload-policy model.
+
+## Generated Artifacts
+
+Wave writes runtime artifacts here:
+
+- live runs: `.tmp/<lane>-wave-launcher/executors/wave-<n>/<agent-slug>/`
+- dry-run previews: `.tmp/<lane>-wave-launcher/dry-run/executors/wave-<n>/<agent-slug>/`
+
+Common files:
+
+- `launch-preview.json`: resolved invocation lines, env vars, retry mode, and structured attempt/turn-limit metadata for both dry-run and live launches
+- `skills.resolved.md`: compact metadata-first skill catalog for the selected agent and runtime
+- `skills.expanded.md`: full canonical/debug skill payload with `SKILL.md` bodies and adapters
+- `skills.metadata.json`: resolved skill ids, activation metadata, permissions, hashes, and generated artifact paths
+- `<runtime>-skills.txt`: runtime-projected compact skill text used by the selected executor
+- `claude-system-prompt.txt`: generated Claude harness prompt overlay
+- `claude-settings.json`: generated Claude settings overlay when inline settings data is present
+- `opencode-agent-prompt.txt`: generated OpenCode harness prompt overlay
+- `opencode.json`: generated OpenCode runtime config overlay
+- `.tmp/<lane>-wave-launcher/control-plane/telemetry/events.jsonl`: local-first Wave Control event stream
+- `.tmp/<lane>-wave-launcher/control-plane/telemetry/pending/`: queued event batches awaiting remote delivery
+- `.tmp/<lane>-wave-launcher/control-plane/telemetry/delivery-state.json`: remote-delivery counters and last-error state
+
+Runtime-specific delivery:
+
+- Codex uses the compact catalog in the compiled prompt and attaches bundle directories through `--add-dir`.
+- Claude appends the compact catalog to the generated system-prompt overlay.
+- OpenCode injects the compact catalog into `opencode.json` and attaches `skill.json`, `SKILL.md`, the selected adapter, and recursive `references/**` files through `--file`.
+- Local keeps skills prompt-only.
+
+`launch-preview.json` also records the resolved skill metadata plus a `limits` section. For Claude and OpenCode, that section reports the runtime-specific turn ceiling when one was actually configured; when only generic `budget.turns` exists, the preview keeps it as advisory metadata and notes that Wave emitted no hard turn-limit flag. For Codex, it explicitly records that Wave emitted no turn-limit flag and that any effective ceiling may come from the selected Codex profile or upstream runtime. If a live Codex run later terminates with a visible `Reached max turns (N)` log line, Wave appends that observed ceiling back into the live `launch-preview.json` as runtime evidence rather than pretending Wave set it.
+
+## Recommended Validation Path
+
+Use dry-run before relying on a new runtime configuration:
+
+```bash
+pnpm exec wave doctor
+pnpm exec wave launch --lane main --dry-run --no-dashboard
+```
+
+Then inspect the generated preview and overlay files under `.tmp/<lane>-wave-launcher/dry-run/executors/`.