@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/docs/reference/public-api.md

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

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

@@ -1,182 +0,0 @@
-# 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/`.