title: Ensemble summary: Composer, Conductor, and Clarity — the Ensemble product family, implementation boundaries, and developer entry points. audience: consumer, wrapper, agent, maintainer stability: main-path docRole: main-path canonical: true

Ensemble

Make your work matter. A Beyond Labs release.

Ensemble brings together Composer, Conductor, and Clarity inside WORKABLE constructs on the Beyond Work platform. This repository contains the document and workbook implementations and the Clarity project scaffold.

This repository builds embeddable React components for backoffice document work, on one principle: advanced tasks should be equally easy for AI agents and human users. Every capability exposed through the UI is also available through a structured API, so a human clicking "Accept change" and an agent calling api.runtime.review.getChanges() operate on the same runtime, the same commands, the same read models, and the same round-trip OOXML fidelity guarantees.

| Component | What it is | Status | |---|---|---| | Composer | Word (.docx) review editor — trustworthy WYSIWYG, tracked changes, comments, workflow scopes, round-trip OOXML fidelity | Published as @beyondwork/docx-react-component | | Conductor | Models and workbooks — native Rust calculation engine, canvas grid, review workflows, and round-trip preservation | In this repo (crates/sheets-*, services/xlsx-conductor); package identity remains stable | | Clarity | Argument and communication: claims, evidence, narrative, and audience-specific form | Project stub at services/clarity; PDF review, deck authoring, and HTML output are planned |

Quickstart (Composer)

Composer is Ensemble’s document authorship and review surface. Its package identity remains @beyondwork/docx-react-component.

pnpm add @beyondwork/docx-react-component react react-dom tailwindcss \
  prosemirror-commands prosemirror-keymap prosemirror-model prosemirror-state \
  prosemirror-tables prosemirror-transform prosemirror-view

import "@beyondwork/docx-react-component/ui-tailwind/theme/editor-theme.css";
import { WordReviewEditor } from "@beyondwork/docx-react-component";

export function Review({ docx }: { docx: Uint8Array }) {
  return (
    <div style={{ height: "80vh" }}>
      <WordReviewEditor
        documentId="contract-1"
        currentUser={{ userId: "u1", displayName: "Taylor Shaw" }}
        initialDocx={docx}
      />
    </div>
  );
}

Your app's CSS pipeline must already be configured for Tailwind v4. Use exactly one load path (initialDocx, initialSnapshot, initialSessionState, hostAdapter, or datastore); the runtime owns the session from that point on.

Where to go next

| You are | Go to | |---|---| | An AI agent working in this repo | /skills — task-shaped operating instructions | | Reading the detailed guide | wiki.beyondwork.ai — the authoritative depth | | Looking for runnable code | /examples — chromeless viewer, headless toolbar, headless service | | Working on Conductor (xlsx) | crates/ — calc engine and grid; docs/architecture.md covers both stacks | | Contributing | docs/contributing.md |

Tools/Build

On the shared Ceobox workspace, keep editing, searches, formatting and small metadata checks local. Send expensive compilation and test recipes to the appropriate runner below. Choose the smallest check that covers the change; reserve full suites for the repository's required gates.

The estate's managed build client is installed at ~/.local/bin/buildctl on Ceobox; it is separate from Docker BuildKit's command of the same name. It is not a dependency installed by this repository. Check the live deployment first:

~/.local/bin/buildctl doctor

Use the examples below only when that client is on PATH and the required profile is enabled. The installed runbook, profile qualification results and workspace/runner inventory are in ~/.local/share/agent-build/ (README.md, ROLLOUT.md, VALIDATION.md, WORKSPACE-AUDIT.md). Outside this estate, use the repository's normal CI or an explicitly provisioned runner.

Choose the runner

| Work | Route | | --- | --- | | Rust calculation/OOXML checks without browser or Office dependencies | Managed rust-node, after checking the required toolchain and inputs. | | Browser, rendering, dev-server and corpus jobs | Existing protected tools workspace via scripts/run-tool-workspace-command.sh. The managed browser adapter is not qualified. | | Word/Excel COM | Existing Windows fleet and COM wrappers; no managed Office adapter is qualified. |

For example, a scoped Rust check from this worktree:

buildctl run --profile rust-node --lane ensemble-my-task -- \
  cargo test --locked -p sheets-engine

The current managed image provides Rust 1.97.1 and Node 22.14.0. A differing toolchain, browser dependency or required credential needs the established specialist runner; do not change the test to fit the image.

For the tools workspace, use the existing sync procedure and verify the exact source being tested before invoking its wrapper. DOCX_TOOL_RUNNER_EXPECTED_HEAD checks HEAD only: it does not prove dirty worktree contents were synchronized. Read word-evidence-tools for the command-specific workflow.

For Word/Excel COM, read the Windows fleet guide and the relevant Word or Excel wrapper. Select an explicitly approved slot, establish ownership and use the runner's timeout/cleanup rules. Do not assume a wrapper's default slot is available for unattended work; an interactive seat is not spare build capacity.

Submit from the worktree; keep the result

Run from the root of the worktree you are validating. A managed submission captures its Git HEAD/history, index, staged and unstaged changes, nonignored untracked files and submodules. Initialize submodules at their pinned commits before submission (git submodule update --init --recursive). Edits during capture cause a refusal: finish the edit and retry. Declare required ignored inputs with --include relative/path; do not include credentials. External inputs and custom toolchain wrappers need an explicitly supported mapping, not a silent substitution.

Submit the whole outer recipe in one job, including prerequisite installation and child compilers. Preserve compiler versions, features, optimization levels, selected tests and independent verifier execution. Reuse a stable task/lane name for warm caches. Keep candidate-local target directories separate; never point all worktrees at one mutable Cargo target directory.

buildctl run submits and waits; buildctl submit accepts the same job options and returns a job ID. With that ID:

buildctl status JOB_ID
buildctl logs JOB_ID
buildctl wait JOB_ID
buildctl cancel JOB_ID       # explicitly stop the job and its descendants
buildctl fetch JOB_ID        # retrieve declared artifacts and receipt

Ctrl-C detaches the waiting client; it does not cancel the remote job. For reports, add --artifact @results before -- and have the recipe write to /build-results (also exposed as BUILD_ARTIFACT_DIR). Fetch creates a new directory under ~/.local/state/agent-build/results/JOB_ID/; --out must name a new destination. It does not overwrite edited source. Record the job ID, source revision, exact command, exit status and receipt with validation results. Use receipts to compare queue time and execution time; do not present an unmeasured recipe as a build-time or throughput guarantee.

Resource and failure rules

Managed Linux jobs have enforced memory, CPU, PID, disk and deadline limits, plus admission based on reservations and host pressure. Cargo/test concurrency defaults to four in the current Rust/Node worker; these thread counts are not the memory boundary. doctor and the installed runbook own current capacity.

If a job queues, a profile is disabled, or a resource limit is hit, inspect the status and receipt, correct the input or route, and retry deliberately. Do not start a second unrestricted build on Ceobox, raise parallelism automatically, or leave a background retry loop. Keep scratch on disk and clean up only work you own. Direct SSH/Docker commands and existing specialist runners can bypass the managed service; their limits and ownership rules remain separate.

Working in this repo — agents start here

Read the knowledge layers in this order. Each one is cheaper than the next, and most questions are answered before you reach the bottom.

| Read | For | Cost | |---|---|---| | CLAUDE.md and AGENTS.md | Policy and routing: how work runs here, canonical truth order, which seat you are, how a slice lands | Two files | | skills/ | Task-shaped instructions. Match your concrete trigger to one skill and load it; the index is skills/README.md | One file | | docs/wiki/ | The authoritative detailed guide — what is actually true about each layer. Agents reach it through the knowledge MCP (knowledge_overview -> knowledge_topic -> knowledge_files) | A few pages | | src/ | Final authority. Read it when the layers above do not settle the question | Whole subsystems |

Humans read the same wiki content at wiki.beyondwork.ai. It is one guide serving both audiences, not an agent copy of a human document.

Truth flows one direction. In Composer: OOXML package bytes -> CanonicalDocument -> runtime derived state -> EditorSurfaceSnapshot -> ProseMirror -> DOM. Conductor mirrors the same order over its workbook model and canvas grid. Every layer may project or cache what is below it; none may invent authority. Reading DOM or ProseMirror state as the source of content, layout, geometry, editability, or page truth is a bug, not a shortcut.

How work runs here. Sessions run unattended, so research until the evidence decides rather than stopping to ask — interrupt only for something unsafe, irreversible, or genuinely unanswerable from the repo. Decide on evidence you gathered yourself: run the test, read the source, check the registry, measure it. Finish at green — gates passing and the change on pe2 — because "routed", "flagged", and "known issue" are not finished states.

Status, license, branch model

Ensemble is a Beyond Labs release. Composer and Conductor retain their existing package, API, and service names while the family identity is introduced. See the brand guide.

Composer is published as @beyondwork/docx-react-component under the Beyond Work Use License (see LICENSE.md). React 19 and Tailwind v4 are peer dependencies; yjs, y-prosemirror, and y-protocols are optional peers required only for collaboration.

main is the published projection of the internal pe2 branch and is effectively read-only; PRs against main will be closed by the next projection; open an issue instead.