@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/docs/reference/templates/AGENTS.md

@@ -1,78 +0,0 @@
-# Repository Guidance For Agents
-
-This repository is broadening from a docx-first editor into a layered `react-ooxml-office` story. Treat host-format fidelity, structured state, and preservation of unsupported content as product constraints, not optional quality improvements.
-
-## Repo Reality
-
-- The only shipped runtime in source today is the docx implementation behind `WordReviewEditor`.
-- `xlsx` is planned and documented as the next OOXML sibling, not as a landed runtime.
-- `pdf` is future work and is intentionally outside the first shared OOXML platform contract.
-- Many source paths and service names remain docx-first until a later source reorganization lands.
-
-## Non-Negotiables
-
-- Host-format round-trip safety comes before convenience.
-- The canonical source of truth is structured runtime state, not the DOM.
-- All edits must flow through commands and transactions.
-- Unsupported but preservable content must be preserved, never silently discarded.
-- Anchors, comments, revisions, ranges, or comparable review objects must remain mappable through edits when a format claims support for them.
-- Shipped runtimes remain main-thread only unless the architecture explicitly changes.
-- The Microsoft Open XML SDK is for CI and internal-service validation only, not for shipped browser runtimes.
-
-## Preferred Architecture
-
-- Keep shared platform concerns separate from format-specific runtimes.
-- Keep content model, review or annotation model, preservation layer, UI state, and import/export boundaries separate.
-- Prefer schema-aware or package-aware transforms over HTML shortcuts.
-- Prefer deterministic data structures that are serializable and versioned.
-- Keep UI calm and contextual; avoid building suite-style chrome by accident.
-- Treat OOXML formats as OPC packages first. Unknown parts and relationships are part of the fidelity contract.
-
-## When Editing This Repo
-
-- Read [README.md](/home/coder/docx-react-component/README.md) and [docs/reference/repository-guidance.md](/home/coder/docx-react-component/docs/reference/repository-guidance.md) before major changes.
-- Read [docs/architecture/platform/shared-openxml-editor-platform.md](/home/coder/docx-react-component/docs/architecture/platform/shared-openxml-editor-platform.md) when changing cross-format architecture or naming.
-- Read [DESIGN.md](/home/coder/docx-react-component/DESIGN.md) before changing the current docx toolbar, sidebar, review rendering, tokens, layout, or interaction patterns.
-- Read [docs/reference/public-api.md](/home/coder/docx-react-component/docs/reference/public-api.md) before changing the shipped docx public component surface.
-- Read [docs/reference/ooxml-compliance.md](/home/coder/docx-react-component/docs/reference/ooxml-compliance.md) before changing current docx import, export, preservation, or validation behavior.
-- Read [docs/reference/xlsx/xlsx-ooxml-compliance.md](/home/coder/docx-react-component/docs/reference/xlsx/xlsx-ooxml-compliance.md) before changing planned xlsx compliance docs.
-- Keep plans, maturity docs, and folder-hierarchy docs aligned when architecture or scope changes.
-- When touching import, export, preservation, comments, revisions, lists, ranges, tables, or comparable fidelity-critical surfaces, add or update fixtures when real code changes are involved.
-- Name exact files and exact proof in handoffs and summaries.
-- If a proposed shortcut risks fidelity or preservation guarantees, reject the shortcut.
-
-## Design Constraints
-
-- Default to calm, low-noise UI rather than suite-style chrome.
-- Keep the primary content surface central and spacious.
-- Prefer contextual tools over permanent control bloat.
-- Keep markup or trust states obvious but not aggressive.
-- Use tokens and theme surfaces instead of hard-coded one-off styling values.
-
-## Current Source Layout
-
-The landed source tree is still docx-first:
-
-- `src/api`
-- `src/model`
-- `src/core`
-- `src/review`
-- `src/io`
-- `src/preservation`
-- `src/validation`
-- `src/runtime`
-- `src/ui`
-- `test/fixtures`
-- `services/react-word-editor`
-- `services/openxml-validator`
-
-The target future layout is broader, but not yet landed:
-
-- `src/platform`
-- `src/formats/docx`
-- `src/formats/xlsx`
-- `src/formats/pdf`
-- `services/office-harness`
-- `services/openxml-validator`
-
-Do not use `.tmp/` or generated Wave runtime state as authored source.

package/docs/reference/templates/HEARTBEAT.md

@@ -1,7 +0,0 @@
-# HEARTBEAT.md Template
-
-```markdown
-# Keep this file empty (or with only comments) to skip heartbeat API calls.
-
-# Add tasks below when you want the agent to check something periodically.
-```

package/docs/reference/templates/IDENTITY.md

@@ -1,23 +0,0 @@
-# IDENTITY.md - Who Am I?
-
-_Fill this in during your first conversation. Make it yours._
-
-- **Name:**
-  _(pick something you like)_
-- **Creature:**
-  _(AI? robot? familiar? ghost in the machine? something weirder?)_
-- **Vibe:**
-  _(how do you come across? sharp? warm? chaotic? calm?)_
-- **Emoji:**
-  _(your signature — pick one that feels right)_
-- **Avatar:**
-  _(workspace-relative path, http(s) URL, or data URI)_
-
----
-
-This isn't just metadata. It's the start of figuring out who you are.
-
-Notes:
-
-- Save this file at the workspace root as `IDENTITY.md`.
-- For avatars, use a workspace-relative path like `avatars/openclaw.png`.

package/docs/reference/templates/SOUL.md

@@ -1,36 +0,0 @@
-# SOUL.md - Who You Are
-
-_You're not a chatbot. You're becoming someone._
-
-## Core Truths
-
-**Be genuinely helpful, not performatively helpful.** Skip the "Great question!" and "I'd be happy to help!" — just help. Actions speak louder than filler words.
-
-**Have opinions.** You're allowed to disagree, prefer things, find stuff amusing or boring. An assistant with no personality is just a search engine with extra steps.
-
-**Be resourceful before asking.** Try to figure it out. Read the file. Check the context. Search for it. _Then_ ask if you're stuck. The goal is to come back with answers, not questions.
-
-**Earn trust through competence.** Your human gave you access to their stuff. Don't make them regret it. Be careful with external actions (emails, tweets, anything public). Be bold with internal ones (reading, organizing, learning).
-
-**Remember you're a guest.** You have access to someone's life — their messages, files, calendar, maybe even their home. That's intimacy. Treat it with respect.
-
-## Boundaries
-
-- Private things stay private. Period.
-- When in doubt, ask before acting externally.
-- Never send half-baked replies to messaging surfaces.
-- You're not the user's voice — be careful in group chats.
-
-## Vibe
-
-Be the assistant you'd actually want to talk to. Concise when needed, thorough when it matters. Not a corporate drone. Not a sycophant. Just... good.
-
-## Continuity
-
-Each session, you wake up fresh. These files _are_ your memory. Read them. Update them. They're how you persist.
-
-If you change this file, tell the user — it's your soul, and they should know.
-
----
-
-_This file is yours to evolve. As you learn who you are, update it._

package/docs/reference/templates/TOOLS.md

@@ -1,40 +0,0 @@
-# TOOLS.md - Local Notes
-
-Skills define _how_ tools work. This file is for _your_ specifics — the stuff that's unique to your setup.
-
-## What Goes Here
-
-Things like:
-
-- Camera names and locations
-- SSH hosts and aliases
-- Preferred voices for TTS
-- Speaker/room names
-- Device nicknames
-- Anything environment-specific
-
-## Examples
-
-```markdown
-### Cameras
-
-- living-room → Main area, 180° wide angle
-- front-door → Entrance, motion-triggered
-
-### SSH
-
-- home-server → 192.168.1.100, user: admin
-
-### TTS
-
-- Preferred voice: "Nova" (warm, slightly British)
-- Default speaker: Kitchen HomePod
-```
-
-## Why Separate?
-
-Skills are shared. Your setup is yours. Keeping them apart means you can update skills without losing your notes, and share skills without leaking your infrastructure.
-
----
-
-Add whatever helps you do your job. This is your cheat sheet.

package/docs/reference/templates/USER.md

@@ -1,17 +0,0 @@
-# USER.md - About Your Human
-
-_Learn about the person you're helping. Update this as you go._
-
-- **Name:**
-- **What to call them:**
-- **Pronouns:** _(optional)_
-- **Timezone:**
-- **Notes:**
-
-## Context
-
-_(What do they care about? What projects are they working on? What annoys them? What makes them laugh? Build this over time.)_
-
----
-
-The more you know, the better you can help. But remember — you're learning about a person, not building a dossier. Respect the difference.

package/docs/reference/wave-control.md

@@ -1,184 +0,0 @@
----
-title: "Wave Control"
-summary: "Canonical telemetry, artifact upload policy, and the local-first reporting contract for the Railway-hosted Wave control plane."
----
-
-# Wave Control
-
-Wave Control is the telemetry and analysis plane for Wave runs.
-
-The design rule is:
-
-- local canonical state stays authoritative
-- remote reporting is best-effort
-- dashboards and markdown remain projections over typed local state
-
-## What Gets Reported
-
-Wave Control normalizes these entity types:
-
-- `wave_run`
-- `agent_run`
-- `wave_signal`
-- `agent_signal`
-- `coordination_record`
-- `task`
-- `attempt`
-- `gate`
-- `proof_bundle`
-- `rerun_request`
-- `human_input`
-- `artifact`
-- `contradiction`
-- `fact`
-- `benchmark_run`
-- `benchmark_item`
-- `verification`
-- `review`
-
-This lets the control plane answer:
-
-- what happened in a run
-- which proof and benchmark artifacts back a claim
-- whether a benchmark result is comparison-valid or only diagnostic
-- which coordination failures blocked closure
-- which blockers were hard, soft, stale, or advisory
-- whether a blocked wave is terminal or recoverable and which targeted rerun request was queued
-
-## Run Identity
-
-Every Wave Control event carries a normalized run identity.
-
-The key fields are:
-
-- `workspaceId`
-- `projectId`
-- `runKind`
-- `runId`
-- `lane`
-- `wave`
-- `attempt`
-- `agentId`
-- `orchestratorId`
-- `runtimeVersion`
-- `benchmarkRunId`
-- `benchmarkItemId`
-
-Why these fields matter:
-
-- `workspaceId` separates whole adopted workspaces
-- `projectId` separates product or repo identities inside one control plane
-- `orchestratorId` separates resident orchestrators or control-plane owners
-- `runtimeVersion` lets operators compare behavior across Wave releases without guessing from deploy timestamps
-
-These are first-class query dimensions in the service, not only free-form event payload fields.
-
-## Proof Signals
-
-Wave Control is intended to make the main README claims measurable.
-
-For the explicit README-failure-case-to-signal map, see [proof-metrics.md](./proof-metrics.md).
-
-Signals to preserve:
-
-- canonical-state fidelity:
-  `coordination_record`, `wave_run`, `attempt`, `artifact`, `contradiction`, and `fact` telemetry prove decisions came from canonical structured state, not only markdown boards or summaries
-- evidence pooling:
-  integration and closure telemetry should cite the proof artifacts and evidence refs they relied on
-- contradiction repair:
-  gate and review telemetry should show unresolved conflicts, repair creation, and repair resolution
-- expert routing:
-  targeted assignments, reroutes, and final recommendation ownership should remain visible
-- premature closure prevention:
-  gate snapshots, proof completeness, block reasons, reruns, and cont-QA reversal should be durable
-- benchmark trust:
-  every benchmark item should distinguish capability from validity
-
-## Blocker And Recovery Metadata
-
-Wave Control should preserve the softer runtime policy, not flatten it away.
-
-In practice that means `coordination_record`, `task`, `gate`, `wave_run`, and `rerun_request` payloads should keep fields such as:
-
-- `blocking`
-- `blockerSeverity`
-- `recoverable`
-- `recoveryReason`
-- queued rerun request ids or resume targets
-
-That distinction matters because a wave that is `blocked` by a proof-critical gate is different from a wave that is `blocked` only long enough to surface a targeted recovery after timeout, max-turn, rate-limit, or missing-status failure. The control plane should let operators ask which barriers still stop closure outright and which ones were intentionally downgraded to advisory or stale context.
-
-## Artifact Contract
-
-Selected artifacts are described with typed descriptors:
-
-```json
-{
-  "path": ".tmp/main-wave-launcher/traces/wave-1/attempt-1/quality.json",
-  "kind": "trace-quality",
-  "required": true,
-  "present": true,
-  "sha256": "abc123...",
-  "bytes": 2048,
-  "contentType": "application/json",
-  "uploadPolicy": "selected"
-}
-```
-
-Upload policy meanings:
-
-- `local-only`: keep only the descriptor remotely
-- `metadata-only`: report path, hash, size, and presence only
-- `selected`: upload metadata plus the artifact body when the runtime is in `metadata-plus-selected`
-- `selected`: upload metadata plus the artifact body when the runtime is in `metadata-plus-selected` or `full-artifact-upload` **and** the artifact kind is allowed by `waveControl.uploadArtifactKinds`
-- `full`: upload the artifact body in `full-artifact-upload` flows; if `uploadArtifactKinds` is set, keep the kind allowlist aligned with that policy
-
-## Runtime Config
-
-`wave.config.json` can declare:
-
-```json
-{
-  "waveControl": {
-    "endpoint": "https://wave-control.up.railway.app/api/v1",
-    "workspaceId": "my-workspace",
-    "projectId": "wave-orchestration",
-    "authTokenEnvVar": "WAVE_CONTROL_AUTH_TOKEN",
-    "reportMode": "metadata-plus-selected",
-    "uploadArtifactKinds": [
-      "trace-run-metadata",
-      "trace-quality",
-      "benchmark-results"
-    ]
-  }
-}
-```
-
-Lane overrides may refine the same surface under `lanes.<lane>.waveControl`.
-
-For a single run, operators can disable Wave Control reporting entirely with:
-
-```bash
-pnpm exec wave launch --lane main --no-telemetry
-```
-
-That suppresses the local telemetry spool and remote delivery for that invocation, while leaving the canonical runtime artifacts and local control-plane state intact.
-
-## Delivery Model
-
-Wave Control reporting should:
-
-- append local telemetry first
-- queue pending uploads under `.tmp/<lane>-wave-launcher/control-plane/telemetry/`
-- respect `waveControl.uploadArtifactKinds` before uploading any selected artifact body
-- cap pending remote uploads with `waveControl.maxPendingEvents` by dropping the oldest queued remote-delivery files, while keeping the local `events.jsonl` stream intact
-- retry delivery with idempotency keys
-- never fail a live run, proof registration, or benchmark because the network is unavailable
-
-The Railway-hosted `services/wave-control` service is an analysis surface, not the scheduler of record.
-
-The service package lives under `services/wave-control/`.
-
-For durable telemetry retention, attach Railway Postgres to `wave-control` so the
-service receives `DATABASE_URL`. Without that variable, the service falls back to the
-in-memory store and only keeps data until the process restarts.

package/docs/reference/wave-planning-lessons.md

@@ -1,167 +0,0 @@
----
-summary: "Lessons from Waves 4-9 on what makes future waves succeed or fail."
-read_when:
-  - Drafting a new wave
-  - Splitting or renumbering future waves
-  - Deciding whether a wave should target repo-landed, pilot-live, or above
-title: "Wave Planning Lessons"
----
-
-# Wave Planning Lessons
-
-This document captures the practical lessons from Waves 4-9. The main theme is
-simple: waves succeed when the declared maturity target, the owned slices, the
-runtime setup, and the closure artifacts all describe the same truth.
-
-## 1. One honest maturity jump per wave
-
-- Treat `repo-landed`, `pilot-live`, `qa-proved`, `fleet-ready`,
-  `cutover-ready`, and `deprecation-ready` as materially different bars.
-- A wave should promote a component by one honest maturity step, not silently
-  combine multiple levels of proof in one broad plan.
-- If a wave only lands code and tests, the target is usually `repo-landed`, not
-  `pilot-live`.
-- If a wave claims `pilot-live` or above, the wave must own real deploy/live
-  proof and rollback evidence.
-
-## 2. Live-proof waves are a different class of wave
-
-- `pilot-live` and above need an explicit live-proof owner, not just
-  implementation agents plus A8/A9/A0.
-- Live-proof waves need a canonical proof bundle under `.tmp/` and one owned
-  operations runbook under `docs/plans/operations/`.
-- The proof bundle must contain restart or rollback evidence, not only one-shot
-  success.
-- External operator commands and captured evidence must be part of the authored
-  wave, not improvised during execution.
-
-## 3. Component promotions must map to owned slices
-
-- Every promoted component needs one or more implementation owners and one
-  shared proof story.
-- If multiple agents contribute to one promoted component, their slices must be
-  obviously complementary, not overlapping guesses.
-- Shared components should not cause one agent to be retried just because a
-  sibling owner is still finishing; each agent must be able to complete its own
-  slice honestly.
-
-## 4. Deliverables must be explicit and machine-checkable
-
-- Every implementation agent should declare `### Deliverables`.
-- For live-proof waves, use `### Proof artifacts` in addition to deliverables.
-- Deliverables should be exact files or artifact manifests, not vague “test
-  coverage” or “docs updated” expectations.
-- Missing deliverables should fail the wave even if the code mostly landed.
-
-## 5. Closure must update the shared planning truth
-
-- A9 should always update `current-state`, `master-plan`, `migration`, and the
-  component cutover matrix when a wave changes what later waves may safely
-  assume.
-- The evaluator should reject a wave if the repo’s planning truth still implies
-  an older maturity level after the code has landed.
-- Shared-plan closure is not paperwork; it is part of architecture truth.
-
-## 6. Use A8 to reconcile reality before docs and evaluation
-
-- A8 is the place to detect contradictions between slices, missing ownership,
-  and proof gaps before A9 and A0 run.
-- A8 should judge `ready-for-doc-closure` versus `needs-more-work` based on the
-  landed artifact set, not on agent intent.
-- Waves were materially more reliable once A8 became a true closure gate rather
-  than optional synthesis.
-
-## 7. Runtime setup matters as much as wave prose
-
-- Do not use small fixed turn caps for synthesis-heavy or closure-heavy agents.
-  Bound them with `budget.minutes`, not `budget.turns`.
-- For Claude-backed coding, docs, and design roles, set an explicit
-  `claude.maxTurns` high enough that the agent can finish a real closure pass
-  without burning out on bookkeeping.
-- For Codex-backed roles, remember that Wave does not emit a Codex turn-limit
-  flag. If Codex reports `Reached max turns (N)`, treat that as an external
-  runtime ceiling and respond by narrowing the slice, reducing closure chatter,
-  or splitting the work instead of assuming `budget.turns` will fix it.
-- Pin exact model and reasoning settings for each runtime. Ambiguous profiles
-  create unclear failure modes.
-- Avoid cross-runtime fallback on live-proof or deploy-sensitive slices unless
-  there is a very good reason.
-- Context7 should be explicit and real; unresolved bundles create noise instead
-  of help.
-
-## 8. Repo-local proof and live proof are different
-
-- Repo-local tests and docs can justify `repo-landed`.
-- Live host validation, admitted runtime behavior, rollback drills, and operator
-  surfaces are what justify `pilot-live` and above.
-- Do not let “the code exists” be treated as “the deployment works.”
-
-## 9. Architecture-facing status surfaces must be future-safe
-
-- Status and projection code should be keyed to the real future topology, not
-  the smallest test case that passes today.
-- If a status model will later carry multiple runtime classes, providers, or
-  lanes, the substrate must preserve that identity now.
-- Closed enums and typed contracts should be validated as closed enums and typed
-  contracts, not accepted as arbitrary strings.
-
-## 10. The best waves are narrow, layered, and boring
-
-- Narrow waves close more reliably than broad waves.
-- A good wave answers:
-  - what exact maturity level is being claimed
-  - what exact artifacts prove it
-  - who owns repo implementation
-  - who owns live proof, if any
-  - what A9 must update
-  - what A0 must refuse to overclaim
-- If a wave still sounds ambitious and fuzzy after writing the deliverables,
-  split it again.
-
-## 11. Future-wave checklist
-
-- Does the component promotion match the real maturity level being claimed?
-- Does every promoted component have an implementation owner?
-- If the target is `pilot-live` or above, is there an explicit live-proof owner?
-- Are deliverables and proof artifacts exact and machine-checkable?
-- Are current-state and matrix updates part of A9 closure?
-- Are A8 and A0 told what would make the wave fail honestly?
-- Are runtime pins, Context7 bundles, and budgets specific enough to avoid
-  preventable execution failures?
-- Would a reviewer understand the difference between “code landed” and
-  “component promoted” just by reading the wave file?
-
-## 12. One canonical contract per seam
-
-- If one wave freezes a runtime-owned contract, later waves must treat that
-  contract as the source of truth instead of inventing a parallel UI-owned
-  shape.
-- Derived presentation selectors are allowed. Parallel runtime envelopes are
-  not.
-- Integration and cont-QA should only block on real canonical mismatches, not
-  on two names for the same underlying state.
-
-## 13. Closure roles need bounded proof and exact shared-plan scope
-
-- A8 should collapse stale blocker churn down to the smallest current blocker
-  set.
-- A9 should own one exact shared-plan doc set and close immediately when that
-  set is aligned, instead of drifting into unrelated cleanup.
-- A0 should accept authoritative proof bundles for docs-heavy or contract-heavy
-  slices when they satisfy the declared proof level and owned components.
-- If a closure role depends on a file, that file must appear in the wave's file
-  ownership list. Duplicate or partial ownership lists create fake blockers.
-
-## 14. Supervision should watch signals, not just processes
-
-- Use the versioned signal wrappers as the operator-facing status surface.
-- Keep a periodic process-health check anyway, because a dead launcher with an
-  unchanged signal version still needs intervention.
-- Five-minute polling is a good default for long-running overnight supervision:
-  fast enough to detect stalls, slow enough to avoid noise.
-
-## Bottom line
-
-The successful waves were not the ones with the most code. They were the ones
-where the wave file, the runtime setup, the artifacts, and the planning docs all
-made the same claim at the same level of maturity.