@beyondwork/docx-react-component 1.0.0 → 1.0.1

package/docs/comment-redline-overview.md

@@ -1,350 +0,0 @@
-# Word Comments and Redlines Overview
-
-This document records three things:
-
-1. How current Microsoft Word handles comments, replies, resolution, and tracked changes.
-2. What this repo already proves or intentionally treats as preserve-only.
-3. What this editor should allow, keep preserve-only, or block so the product stays Word-compatible.
-
-This is a requirements and research memo, not a marketing summary. When Word behavior and current repo behavior differ, Word behavior wins and the repo should either align or stay explicit about the gap.
-
-## Bottom line
-
-- Comments and tracked changes are separate systems in Word. Comments are not "part of" Track Changes.
-- Modern Word comments are thread-based: one anchored root comment plus direct replies. Reply-to-reply nesting should not be exposed.
-- In modern comments, resolution is thread-level. Do not expose "resolve only this reply" as a first-class action.
-- Word supports more review features than this repo should currently author. Unsupported review markup must stay preserve-only, not be normalized away.
-- This repo already has real proof for:
-  - single-paragraph comments
-  - threaded comments with resolution metadata
-  - comments interacting with deleted text in the owned slice
-  - run-level tracked insertions/deletions
-  - bounded paragraph-mark insertion/deletion accept or reject
-- This repo should continue to treat as preserve-only:
-  - multi-paragraph comment authoring
-  - comments whose anchors overlap opaque or preserve-only review markup
-  - move revisions
-  - formatting revisions
-  - structural revisions in tables and list structures
-  - review metadata in newer extension formats the runtime does not model
-
-## Repo facts today
-
-### Public/runtime surface already present
-
-The public editor ref already exposes comment and tracked-change actions in [docs/reference/public-api.md](./reference/public-api.md) and [src/api/public-types.ts](../src/api/public-types.ts):
-
-- `addComment(...)`
-- `openComment(commentId)`
-- `resolveComment(commentId)`
-- `reopenComment(commentId)`
-- `addCommentReply(commentId, body)`
-- `editCommentBody(commentId, body)`
-- `acceptChange(changeId)`
-- `rejectChange(changeId)`
-- `acceptAllChanges()`
-- `rejectAllChanges()`
-
-### Current repo proof and boundaries
-
-The current fixtures and parsers establish these boundaries:
-
-- [test/fixtures/docx/F09-comments-single-paragraph.docx](../test/fixtures/docx/F09-comments-single-paragraph.docx)
-  - single-paragraph comments are supported-roundtrip
-- [test/fixtures/docx/F10-threaded-comments-resolve.docx](../test/fixtures/docx/F10-threaded-comments-resolve.docx)
-  - threaded comments and resolution metadata import/export through one runtime thread
-- [test/fixtures/docx/F13-comments-on-deleted-text.docx](../test/fixtures/docx/F13-comments-on-deleted-text.docx)
-  - comment and deletion overlap is supported only where representable; preserve-only overlap stays explicit
-- [test/fixtures/docx/F11-redlines-basic.docx](../test/fixtures/docx/F11-redlines-basic.docx)
-  - run-level `w:ins` and `w:del` are actionable
-- [test/fixtures/docx/F12-redlines-paragraph-joins-splits.docx](../test/fixtures/docx/F12-redlines-paragraph-joins-splits.docx)
-  - bounded paragraph-mark insert/delete accept/reject is actionable
-- [test/fixtures/docx/F14-revisions-in-tables-and-lists.docx](../test/fixtures/docx/F14-revisions-in-tables-and-lists.docx)
-  - structural revisions in tables/lists remain preserve-only
-
-Implementation details that matter:
-
-- [src/io/ooxml/parse-comments.ts](../src/io/ooxml/parse-comments.ts)
-  - imports threaded comments from `comments.xml` plus `commentsExtended.xml` and `commentsIds.xml`
-  - downgrades multi-paragraph comment anchors to detached preserve-only
-- [src/io/export/serialize-comments.ts](../src/io/export/serialize-comments.ts)
-  - exports `comments.xml`, `commentsExtended.xml`, `commentsIds.xml`, and `people.xml`
-- [src/io/ooxml/parse-revisions.ts](../src/io/ooxml/parse-revisions.ts)
-  - treats `ins` and `del` as supported containers
-  - imports `moveFrom` or `moveTo` and formatting revisions as preserve-only
-- [src/io/docx-session.ts](../src/io/docx-session.ts)
-  - detaches comment anchors that overlap opaque content or preserve-only revision ranges
-- [docs/reference/word-review-editor-frontend-architecture.md](./reference/word-review-editor-frontend-architecture.md)
-  - the UI "Show/Hide tracked changes" control is only a display toggle; the runtime always tracks changes internally
-
-### Current repo gaps relative to Word
-
-These are not theoretical; they are visible in current command handling:
-
-- [src/core/commands/index.ts](../src/core/commands/index.ts)
-  - `comment.add-reply` currently does not block replies on resolved or detached threads
-  - `comment.edit-body` edits only the first entry in a thread and does not enforce author ownership
-
-Those behaviors diverge from modern Word expectations and should be tightened.
-
-## How Word comments work
-
-### Core model
-
-Word comments attach to an anchored document position or range. In OOXML the visible anchor is represented with:
-
-- `w:commentRangeStart`
-- `w:commentRangeEnd`
-- `w:commentReference`
-- comment bodies in `word/comments.xml`
-
-Threading and resolution are not fully represented in `comments.xml` alone:
-
-- `commentsExtended.xml` (`w15`) carries per-comment paragraph IDs, reply parentage, and thread "done" state
-- `commentsIds.xml` (`w16cid`) carries durable IDs
-- newer comment extensibility schemas add more metadata and must be preserved unless explicitly modeled
-
-Important Word/OOXML constraints:
-
-- The OOXML notes for `commentRangeStart` say Word ignores comment anchors under headers, footers, text boxes, footnotes, and endnotes even though the base standard allows the element there.
-- A comment can degrade to a single anchor point if a matching range end is missing; Word falls back to the `commentReference` location.
-
-### What Word exposes for comments
-
-| Capability | Word behavior | Repo policy |
-| --- | --- | --- |
-| Add a comment | Word allows a comment on selected text or at an insertion point. | Allow on supported body-text anchors only. |
-| Root comment body | Root comment is the anchored item. | Allow. |
-| Direct reply | Word supports replies on a comment thread. | Allow on open threads. |
-| Reply to a reply | Word's `Comment.Replies` docs say adding a reply fails when called from a reply-to-a-reply collection. Treat the thread as flat: root + direct replies only. | Do not expose nested replies. |
-| Edit a comment | Modern comments allow editing, but modern UI intentionally blocks editing others' comments. Microsoft also notes file-level edit access can still modify comments via other experiences. | Inference: default UI should enforce author-only edit for both root comments and replies. Preserve imported mutations from elsewhere. |
-| Resolve a thread | Word resolves the thread; no more replies can be added until reopened. | Allow on thread root only. |
-| Reopen a thread | Word allows reopening resolved threads. | Allow. |
-| Resolve only one reply | Microsoft VBA docs say `Comment.Done` on a single reply has no visible effect in redesigned comments. | Do not expose reply-level resolve. |
-| Delete thread | Word allows deleting a thread. | Add only when delete/export proof exists. Not currently public API. |
-| Get link to comment | Word exposes "Get link" in modern comments. | Optional later. Not fidelity-critical. |
-| Contextual vs list view | Word has both views; contextual hides resolved comments, list view can show all. | Safe to mirror in UI. |
-| Draft then post | Modern comments require an explicit Post action; Word currently supports one draft at a time. | Optional UI fidelity. Not a file-format requirement. |
-| @mentions | Word can mention users and notify them. | Preserve if present; do not author until user identity and notification semantics exist. |
-| Assign task from comment | Word supports task assignment via `@mention` and Assign-to. | Preserve if present; do not author in v1. |
-| Images in comments | Modern comments allow text and images; the support page says image insertion is Windows-only. | Preserve imported images if encountered inside unsupported comment content; do not expand authoring scope yet. |
-| Rich formatting in comments | Modern comments support bold, italic, underline, strikethrough, font color, and highlight. They do not support font size, font family changes, or paragraph settings in the modern card UI. | Keep runtime comment authoring plain text unless a schema-backed comment-content model is introduced. Preserve richer imported content. |
-| Tables, equations, shapes, fields in comments | Microsoft says these are not supported in modern comment cards and may only appear in the Reviewing Pane. | Preserve-only if present. Do not author. |
-| Reactions on comments | Word for the web supports reactions; cross-platform visibility is incomplete. | Preserve-only. Do not author in v1. |
-
-### Important comment-specific conclusions
-
-- Thread shape should remain flat:
-  - one anchored root comment
-  - zero or more direct replies
-  - no nested reply tree
-- Resolution should stay thread-level.
-- Replying to a resolved thread should be blocked until the thread is reopened.
-- Editing comment text should be stricter than the raw file format:
-  - default to author-only in UI
-  - preserve imported content even if another Word surface edited it
-- Comments outside the main editable story should not be authored even if encountered in source packages.
-
-## How Word tracked changes and redlines work
-
-### Core model
-
-Word tracked changes are distinct review records over the document body. In OOXML they can appear as:
-
-- run-level insertions: `w:ins`
-- run-level deletions: `w:del`
-- move revisions: `w:moveFrom`, `w:moveTo`
-- formatting revisions: `w:rPrChange`, `w:pPrChange`
-- paragraph-mark revisions via revision markers in paragraph properties
-- many additional structural cases when lists, tables, numbering, or document shell markup are involved
-
-Word also has a separate permission and display layer around tracked changes:
-
-- Review mode
-- Track Changes on/off
-- display modes such as All Markup or No Markup
-- show or hide by reviewer
-- show or hide by change type
-- accept or reject one, all, or all shown
-
-### What Word exposes for tracked changes
-
-| Capability | Word behavior | Repo policy |
-| --- | --- | --- |
-| Review mode | In Word review mode, a reviewer cannot directly edit final content but can add comments and tracked suggestions. | Treat as a host-level permission mode, not just UI chrome. Current repo `reviewMode` is not equivalent to Word review permissions. |
-| Track Changes on/off | Word supports actual recording on/off. | Do not expose a fake Word-style on/off switch in v1. Current repo intentionally always tracks runtime edits internally. |
-| Track only my changes / everyone | Word supports `Just Mine` and `For Everyone` in some surfaces. | Out of scope for v1 single-runtime semantics. |
-| Display mode: All Markup | Shows markup inline and in balloons. | Repo `markupDisplay="all"` is the closest analog. |
-| Display mode: No Markup | Hides markup but does not remove it. | Repo `clean` should remain display-only, never destructive. |
-| Display mode: Original | Shows the original document view without removing tracked data. | No current repo equivalent. Add only if the runtime can project it honestly. |
-| Simple Markup | Word shows a simplified review view while retaining markup. | Repo `simple` is repo-specific, not a one-to-one Word mode. Keep the distinction explicit. |
-| Show or hide by change type | Word can filter insertions/deletions, formatting, ink, balloons, reviewers, and similar display categories. | Safe later as a display filter only. Must never mutate canonical review state. |
-| Accept this change | Word can accept a selected change. | Allow for actionable supported revisions only. |
-| Reject this change | Word can reject a selected change. | Allow for actionable supported revisions only. |
-| Accept/reject and move to next | Word has sequential review navigation. | Nice to have later. Not required for file fidelity. |
-| Accept all changes shown | Word can accept only visible changes under current filters. | Do not implement until reviewer and type filters are first-class and honest. |
-| Reject all changes shown | Same as above. | Same restriction. |
-| Accept all changes | Word supports it. | Allow for actionable supported revisions only. Preserve-only revisions must remain untouched. |
-| Reject all changes | Word supports it. | Allow for actionable supported revisions only. Preserve-only revisions must remain untouched. |
-| Accept/reject all and stop tracking | Word supports stop-tracking variants. | Do not expose until the runtime has a real tracking-mode model. |
-| Run-level insertion/deletion | Core Word tracked-change path. | Allow and keep as primary supported redline slice. |
-| Paragraph-mark insertion/deletion | Word supports paragraph join/split style revisions. | Allow only in the bounded, proved slice from F12. |
-| Move revisions | Word supports them and can display Move From/Move To. | Preserve-only in v1. Do not author or accept/reject. |
-| Formatting revisions | Word supports them. | Preserve-only in v1. Do not author or accept/reject. |
-| Structural revisions in tables/lists | Word supports them. | Preserve-only in v1. Do not author or accept/reject. |
-| Lock Track Changes with password | Word supports locking tracking. | Preserve protection markup if imported; do not implement runtime control in v1. |
-| Compare / legal blackline | Word desktop can compare or combine documents to create a review/redline document. | Treat generated redline documents as import sources. Do not add in-editor compare/combine in v1. |
-
-### Important tracked-change conclusions
-
-- Showing or hiding markup is not the same as accepting or rejecting markup.
-- Accept/reject actions must be limited to revision kinds the runtime can rewrite semantically and reserialize safely.
-- "Accept all" in this product should mean:
-  - accept all actionable revisions
-  - leave preserve-only revisions intact
-  - surface that preserve-only revisions remain
-- Do not silently collapse move, formatting, or structural revisions into plain content.
-
-## Comment and redline interaction rules
-
-This is the high-risk area for Word compatibility.
-
-Word facts and repo implications:
-
-- Microsoft explicitly says comments are no longer part of the Track Changes function.
-- In real documents, comment anchors and tracked changes can overlap.
-- This repo already carries explicit handling for comments on deleted text and for comment overlap with preserve-only review markup.
-
-Required product rules:
-
-| Interaction | Rule |
-| --- | --- |
-| Comment anchored in supported plain-text content | Allow. |
-| Comment anchored in content that later shifts because of supported edits | Allow, but remap anchor through transactions. |
-| Comment overlapping preserve-only revision markup | Preserve-only, detached if necessary, with an explicit warning. |
-| Comment overlapping opaque unsupported OOXML | Preserve-only, detached if necessary, with an explicit warning. |
-| Comment on deleted text in the owned F13 slice | Keep explicit and reviewable; do not flatten silently. |
-| Accept/reject of a revision with attached comments | Recompute comment anchors through mapping; never drop the thread just because nearby content changed. |
-| A review action that would force destructive rewrite of unsupported overlap | Warn or block. Do not improvise. |
-
-## Recommended allow/preserve-only/block matrix
-
-This is the concrete action list the product should implement against.
-
-### Comments
-
-| Action | Status | Notes |
-| --- | --- | --- |
-| Add comment on a supported single-paragraph body-text range | Allow now | Core supported feature. |
-| Add comment at insertion point in supported body text | Allow now | Use a zero-width or point-style anchor model that serializes back to a valid comment reference. |
-| Add multi-paragraph comment | Preserve-only / block authoring | Word documents may contain these, but this repo has not proved stable remapping. |
-| Add comment in header/footer/text box/footnote/endnote | Block authoring | Word ignores these anchors in practice; preserve on import only. |
-| Open/navigate to thread | Allow now | UI/navigation only. |
-| Edit root comment body authored by current user | Allow now | Align with modern comments. |
-| Edit root comment body authored by another user | Block in default UI | Inference from Word modern comments; preserve imported external edits. |
-| Edit reply body authored by current user | Future, but valid | Word supports editing comments; if added here, enforce author-only and flat thread semantics. |
-| Edit reply body authored by another user | Block in default UI | Same rationale. |
-| Reply to open thread | Allow now | Direct reply only. |
-| Reply to resolved thread | Block | Must require reopen first. Current repo behavior should be tightened here. |
-| Reply to detached thread | Block | Detached means preserve-only anchor. |
-| Nested reply to reply | Block | Not a Word-modern thread model. |
-| Resolve thread | Allow now | Thread-level only. |
-| Resolve individual reply | Block | No modern Word-visible semantics. |
-| Reopen resolved thread | Allow now | Required for parity. |
-| Delete thread | Future, but valid | Add only when delete merge/export proof exists. |
-| Delete individual reply while retaining thread | Future, research first | Do not add until Word-surface behavior and OOXML export semantics are separately verified. |
-| @mention | Future preserve-and-author | Needs identity, notifications, and task semantics. |
-| Assign task from comment | Future preserve-and-author | Same dependency. |
-| Add image in comment | Preserve-only / later | Not fidelity-critical for v1. |
-| Add tables/equations/shapes/fields in comment | Preserve-only | Do not author. |
-| Add reactions to comments | Preserve-only | Web-only and extension-based today. |
-
-### Tracked changes / redlines
-
-| Action | Status | Notes |
-| --- | --- | --- |
-| Record text insertion as tracked insertion | Allow now | Core redline feature. |
-| Record text deletion as tracked deletion | Allow now | Core redline feature. |
-| Record paragraph join/split in bounded F12 slice | Allow now | Only the proved paragraph-mark cases. |
-| Turn tracking fully off | Do not expose in v1 | Repo intentionally always tracks runtime edits. |
-| Show or hide markup | Allow now | Display-only control. |
-| Provide a false "track changes off" button that only hides markup | Block | Misleading and Word-incompatible. |
-| Accept one supported insertion/deletion | Allow now | Already proved. |
-| Reject one supported insertion/deletion | Allow now | Already proved. |
-| Accept/reject one supported paragraph-mark revision | Allow now | Only in the bounded slice. |
-| Accept/reject move revision | Preserve-only | Keep visible, not actionable. |
-| Accept/reject formatting revision | Preserve-only | Keep visible, not actionable. |
-| Accept/reject structural revision in table/list | Preserve-only | Keep visible, not actionable. |
-| Accept all supported revisions | Allow now | Must skip preserve-only revisions and report that honestly. |
-| Reject all supported revisions | Allow now | Same rule. |
-| Accept/reject all shown under filters | Future | Only after reviewer/type filters are honest and first-class. |
-| Filter by reviewer | Future display feature | Display only, not semantic rewrite. |
-| Filter by revision type | Future display feature | Display only. |
-| Compare two docs to create a legal blackline | Out of scope for editor v1 | Treat compared docs as import sources. |
-| Lock tracking with password | Out of scope for editor v1 | Preserve imported protection markup only. |
-
-## Specific engineering changes implied by this research
-
-These are the main behavior changes the repo should make or preserve:
-
-1. Keep comments and tracked changes as separate stores and separate command families.
-2. Keep thread resolution on the thread root only.
-3. Block `addCommentReply` on resolved or detached threads.
-4. Enforce flat thread semantics: no reply-to-reply UI or data model.
-5. Add author-ownership checks before allowing comment-body edits in the default UI.
-6. If reply editing is added later, edit a specific reply entry, not just thread entry `0`.
-7. Continue exporting and preserving `commentsExtended.xml`, `commentsIds.xml`, and `people.xml` for threaded comment fidelity.
-8. Continue treating multi-paragraph comment anchors as preserve-only until anchor remapping is proved across paragraph surgery.
-9. Continue treating move, formatting, and structural revisions as preserve-only.
-10. Keep the track-changes visibility toggle honest: display only, not mutation mode.
-11. Never implement "accept all" by flattening preserve-only revisions.
-12. Preserve newer comment extension data rather than dropping it, even if the runtime does not yet model it.
-
-## Sources
-
-### Repo sources
-
-- [README.md](../README.md)
-- [docs/reference/repository-guidance.md](./reference/repository-guidance.md)
-- [docs/reference/public-api.md](./reference/public-api.md)
-- [docs/reference/ooxml-compliance.md](./reference/ooxml-compliance.md)
-- [docs/reference/word-review-editor-frontend-architecture.md](./reference/word-review-editor-frontend-architecture.md)
-- [src/api/public-types.ts](../src/api/public-types.ts)
-- [src/core/commands/index.ts](../src/core/commands/index.ts)
-- [src/io/docx-session.ts](../src/io/docx-session.ts)
-- [src/io/ooxml/parse-comments.ts](../src/io/ooxml/parse-comments.ts)
-- [src/io/export/serialize-comments.ts](../src/io/export/serialize-comments.ts)
-- [src/io/ooxml/parse-revisions.ts](../src/io/ooxml/parse-revisions.ts)
-- [test/io/comment-roundtrip.test.ts](../test/io/comment-roundtrip.test.ts)
-- [test/io/revision-roundtrip.test.ts](../test/io/revision-roundtrip.test.ts)
-- [test/io/docx-session.test.ts](../test/io/docx-session.test.ts)
-- [test/fixtures/docx/F10-threaded-comments-resolve.md](../test/fixtures/docx/F10-threaded-comments-resolve.md)
-- [test/fixtures/docx/F11-redlines-basic.md](../test/fixtures/docx/F11-redlines-basic.md)
-- [test/fixtures/docx/F12-redlines-paragraph-joins-splits.md](../test/fixtures/docx/F12-redlines-paragraph-joins-splits.md)
-- [test/fixtures/docx/F13-comments-on-deleted-text.md](../test/fixtures/docx/F13-comments-on-deleted-text.md)
-- [test/fixtures/docx/F14-revisions-in-tables-and-lists.md](../test/fixtures/docx/F14-revisions-in-tables-and-lists.md)
-
-### Microsoft sources
-
-- Microsoft Support: [Using Modern comments in Word](https://support.microsoft.com/en-us/office/using-modern-comments-in-word-edc6ae71-0a2d-49fe-8faa-986f1e48136a)
-- Microsoft Support: [Review mode in Word](https://support.microsoft.com/en-us/office/review-mode-in-word-941d357d-c9f3-4f3f-b7b0-122ed0074f30)
-- Microsoft Support: [Track changes in Word](https://support.microsoft.com/en-us/office/track-changes-in-word-197ba630-0f5f-4a8e-9a77-3712475e806a)
-- Microsoft Support: [Give and receive feedback in Word](https://support.microsoft.com/en-gb/office/give-and-receive-feedback-in-word-07f25746-7b26-4769-9ebb-ca2f0f5783b8)
-- Microsoft Support: [Use a screen reader to add, read, and delete comments in Word](https://support.microsoft.com/en-us/office/use-a-screen-reader-to-add-read-and-delete-comments-in-word-c4648d50-4f7b-4795-b487-9e3141a5a596)
-- Microsoft Support: [React to a comment in Word for the web](https://support.microsoft.com/en-us/office/react-to-a-comment-in-word-for-the-web-5a50bc81-634f-4bcc-b5b5-900768f0afba)
-- Microsoft Support: [Compare document differences using the legal blackline option](https://support.microsoft.com/en-us/office/compare-document-differences-using-the-legal-blackline-option-dbfc7351-4022-43a2-a0c4-54d1898702a0)
-- Microsoft Learn: [Comment.Replies property (Word)](https://learn.microsoft.com/en-us/office/vba/api/word.comment.replies)
-- Microsoft Learn: [Comment.Done property (Word)](https://learn.microsoft.com/en-us/office/vba/api/word.comment.done)
-- Microsoft Learn: [Comments.Add method (Word)](https://learn.microsoft.com/en-us/office/vba/api/word.comments.add)
-- Microsoft Learn Open Specifications: [commentRangeStart (Comment Anchor Range Start)](https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oi29500/64b95366-980f-4c75-9519-b745345ded9a)
-- Microsoft Learn Open Specifications: [CT_CommentId](https://learn.microsoft.com/en-us/openspecs/office_standards/ms-docx/9c360cd7-653f-4d82-82be-7bda2488c0c1)
-- Microsoft Learn Open Specifications: [CT_CommentExtensible](https://learn.microsoft.com/en-us/openspecs/office_standards/ms-docx/a7b57225-42e5-43e7-8d98-d90eabf3ca25)
-
-## Notes on inference
-
-Two policy calls above are informed by multiple Microsoft sources rather than one perfectly aligned statement:
-
-- "Only the author can edit a comment" is the correct default modern-comments UI rule, even though Microsoft separately notes that anyone with file edit access can still change comment content through other file-backed surfaces.
-- Multi-paragraph comment anchors are treated here as a real Word/OOXML case that must be preserved, even though this repo does not yet claim safe authoring or remapping support for them.
-
-Those are intentional product inferences, not accidental assumptions.

package/docs/concepts/context7-vs-skills.md

@@ -1,118 +0,0 @@
-# Context7 vs Skills
-
-Context7 and skills solve different problems.
-
-Use Context7 for external library truth. Use skills for repo-owned, reusable operating knowledge.
-
-That comparison matters because Wave treats context as something to compile at runtime, not something humans should maintain separately for Claude, Codex, OpenCode, and every other executor.
-
-## Compiled Context, Not Hand-Maintained Context Files
-
-The active context for an agent is assembled from multiple layers:
-
-- repository source and the wave's owned files
-- wave markdown and shared plan docs
-- generated shared summary and per-agent inbox
-- saved project defaults such as `.wave/project-profile.json`
-- resolved repo-owned skills
-- selected Context7 snippets for external library truth
-- generated runtime overlays and launch artifacts
-
-Because of that, the question is not "which hand-written context file does this runtime use?" The question is "which context sources does this wave compile for the selected runtime right now?"
-
-Runtime-specific context is still real, but it is mostly generated:
-
-- Claude gets merged system-prompt and settings overlays
-- Codex gets executor flags plus runtime-projected skills
-- OpenCode gets generated config, attachments, and runtime instructions
-
-That keeps the context model unified even when the transport layer differs.
-
-## Short Version
-
-- Context7
-  Up-to-date third-party library or API context.
-- Skills
-  Reusable guidance tailored to your repository, environments, roles, and runtime choices.
-
-## Comparison
-
-| Surface | Context7 | Skills |
-| --- | --- | --- |
-| Primary purpose | External docs and SDK truth | Internal reusable operating guidance |
-| Typical source | `docs/context7/bundles.json` and fetched snippets | `skills/<skill-id>/skill.json` and `SKILL.md` |
-| Ownership | Package or repo operator config | Repository maintainers |
-| Scope | Library versions, APIs, setup syntax | Coding rules, deploy norms, repo conventions, workflow rules |
-| Selection | Wave defaults plus per-agent `### Context7` | Base plus role, runtime, deploy-kind, and per-agent `### Skills` |
-| Change rate | Often changes with external libraries | Changes when your repo or environment changes |
-| Projection | Injected as prompt context | Projected into runtime-specific overlays and prompt context |
-
-## When To Use Context7
-
-Use Context7 when the agent needs information that lives outside the repo and can change over time, such as:
-
-- framework APIs
-- SDK method signatures
-- library setup syntax
-- version-specific behavior
-- hosted service docs
-
-Context7 is intentionally narrow. It is for third-party truth, not for your repo's own architecture or policies.
-
-## When To Use Skills
-
-Use skills when the guidance is reusable, repo-owned, and should survive across waves, roles, or runtimes, such as:
-
-- coding norms
-- review expectations
-- environment-specific rules
-- Railway, Kubernetes, or GitHub release procedures
-- runtime-specific instructions for Codex, Claude, or OpenCode
-- role-oriented heuristics for implementation, deploy, cont-QA, or research agents
-
-## What Remains Authoritative
-
-Neither Context7 nor skills replace the actual repo.
-
-The highest-authority sources are still:
-
-- repository source
-- `wave.config.json`
-- wave markdown
-- role prompts in `docs/agents/*.md`
-- shared plan docs
-- the generated shared summary and inboxes for the active run
-
-Skills are additive guidance. Context7 is non-canonical external context. The repo and wave artifacts remain authoritative.
-
-## How They Work Together
-
-A typical deploy-focused wave might use both:
-
-- Context7
-  For the latest official framework or platform docs.
-- Skills
-  For repo-specific deploy rules, Railway conventions, and runtime-specific execution guidance.
-
-That combination keeps the agent grounded in both external truth and local operating rules.
-
-## Runtime Behavior
-
-Both surfaces are runtime aware, but in different ways:
-
-- Context7 is fetched and injected into the compiled prompt.
-- Skills are resolved after executor selection and then projected into the runtime-specific overlay surface for that executor.
-
-Because of that:
-
-- changing Context7 selection changes the prompt fingerprint
-- changing resolved skills also changes the prompt fingerprint and trace metadata
-
-## Best Practice
-
-- Put version-sensitive third-party docs into Context7.
-- Put stable repo or environment playbooks into skills.
-- Keep wave prompts focused on the specific assignment, not long-lived reusable rules.
-- If the same guidance is repeated across waves, promote it into a skill.
-
-For exact skill bundle layout and resolution order, see [reference/skills.md](../reference/skills.md).

package/docs/concepts/operating-modes.md

@@ -1,91 +0,0 @@
-# Oversight, Dark-Factory, And Human Feedback
-
-Wave now has an explicit planning vocabulary for execution posture.
-
-Today that posture is captured in project profile memory and planner output. The deeper runtime policy attached to those modes is still roadmap work, so this page distinguishes what is already shipped from what is still a convention.
-
-## The Two Postures
-
-- `oversight`
-  Human review and intervention are expected parts of the operating model for risky work.
-- `dark-factory`
-  The goal is end-to-end execution without routine human intervention.
-
-These values are stored in `.wave/project-profile.json` and emitted into planner-generated specs and wave markdown.
-
-## What Ships Today
-
-Today the runtime ships:
-
-- project-profile memory for default oversight mode
-- planner prompts that ask for oversight mode
-- generated specs and waves that record the chosen mode
-- deploy-environment memory that helps infra and release planning
-- orchestrator-first clarification handling and human feedback queueing
-
-The runtime does not yet enforce a separate hard policy profile for `dark-factory` beyond what is already encoded in the wave itself.
-
-## How To Interpret The Modes Right Now
-
-Treat them as planning posture:
-
-- `oversight`
-  Default when a human operator should expect to inspect progress, answer questions, or approve risky transitions.
-- `dark-factory`
-  Use only when the wave already has explicit environment modeling, validation, rollback posture, and clear closure signals.
-
-## Human Feedback Is Not The Same Thing
-
-Human feedback is a runtime escalation mechanism, not an operating mode.
-
-The runtime flow is:
-
-1. agent emits a clarification request or blocker
-2. the orchestrator tries to resolve it from repo state, policy, ownership, or targeted rerouting
-3. only unresolved items become human feedback tickets
-4. those tickets stay visible in ledgers, summaries, and traces until resolved
-
-That means even `oversight` mode still tries to keep routine clarification inside the orchestration loop before escalating to a human.
-
-## Oversight Mode Best Fit
-
-Choose `oversight` when:
-
-- deploy or infra mutation is live and risky
-- the environment model is incomplete
-- rollback steps are still implicit
-- legal, compliance, or release decisions need explicit human sign-off
-- the repo is still shaping its skills and closure rules
-
-## Dark-Factory Best Fit
-
-Choose `dark-factory` only when all of these are already true:
-
-- deploy environments are typed and explicit
-- runtime and credential expectations are known
-- validation commands are concrete
-- rollback or recovery posture is documented
-- closure evidence is machine-checkable or strongly operator-visible
-- missing context would be treated as a planning failure, not something to improvise live
-
-## Best Practice
-
-Default to `oversight` until the repo has earned `dark-factory`.
-
-That usually means:
-
-- stable skills for deploy and infra work
-- consistent deploy-environment naming
-- strong validation commands
-- reliable docs and trace review habits
-- low ambiguity about who owns live mutation
-
-## Relationship To The Roadmap
-
-The roadmap still includes stronger explicit oversight vs dark-factory workflows. What is shipped today is the planning foundation:
-
-- stored project defaults
-- typed values in planner output
-- better environment modeling
-
-The stricter execution semantics are the next step, not a hidden already-finished feature.