The document as a shared workspace
Chopin puts people and an agent inside the same editable document. Its most useful ideas concern how that document changes, how decisions survive a rewrite, and how a reader can understand what the agent did.
A document people can keep shaping
Chopin is a GitHub Next research prototype for people and repository-grounded agents to co-author durable documents. Implementation plans are its main workflow, but the model also covers specifications, RFCs, proposals and decision records. Its agent, currently called Planner, is still prompted and tooled primarily for planning.
The project introduction identifies four weaknesses in existing planning interfaces: limited interaction with the plan, isolated team members, unclear decision ownership, and too much explanation confined to prose. Chopin explores a shared editing surface with comments, visuals, research and an agent that participates in the work.
The durable artifact is the document. Chat supplies discussion and instructions. Decision records retain what people chose and who chose it. Those pieces remain related without becoming interchangeable.
A channel contains one repository-connected document and its collaboration context. Published research can become a child document. The architecture and maintainer guide say children share their root’s Chat while owning their document and Decisions; the README still describes separate child Chat. This study follows the more specific architecture contract and records the discrepancy.
Four layers inside the editor
- MDXEditorThe rich editing interface and Markdown import/export machinery.
- LexicalThe editable node tree: paragraphs, selections, formatting and commands.
- YjsShared document updates, collaborative undo and live presence.
- Server roomAuthoritative shared state, headless validation and durable commits.
At the inspected revision, the workspace pins MDXEditor 4.1.0 and Lexical 0.48.0. Chopin adds substantial integration around them: a shared schema registry, custom collaboration and history handling, table nodes, comments, decision widgets and server-side conversion. Its MDXEditor patch restores a missing TypeScript declaration for a runtime export used by that registry.
| Area | Responsibility |
|---|---|
apps/web | React workspace, repository picker, navigation and Chat. |
packages/editor | Rich editor, collaboration provider, cursors, comments and widgets. |
packages/dialect | Allowed MDX, parser, serializer and shared Lexical schema. |
packages/protocol | Messages used by browser and server. |
apps/server | Authentication, live rooms, storage, Planner, background jobs and MCP. |
apps/connector | Connects a person’s machine and ACP-compatible coding agent for local work. |
Shared packages do not depend on either application. The runtime is a Bun server serving the built React client, HTTP API, MCP and WebSockets from one origin, backed by PostgreSQL. A renewable database writer lease permits one application process to write at a time.
Document architecture · Editor composition · Shared registry
A human types; an agent addresses blocks
Both paths end in the same live document and durable storage, but they start with different editing operations. Open either trace to follow a change.
Follow a human edit
- The browser edits its Lexical tree; the Lexical/Yjs binding produces a collaborative update.
- The provider keeps the update until acknowledgement, allowing compatible updates to be replayed after reconnection.
- The server groups incoming updates for 5 milliseconds, applies them to its document, and projects canonical MDX through headless Lexical.
- After validation, the update and related state commit under the database writer fence. Only then does the server acknowledge and relay the accepted state.
If an update produces an invalid document, Yjs cannot simply roll back that transaction. The room rebuilds its last known-good state under a new epoch, and clients reopen against that history.
Follow an agent edit
- Planner reads the current document revision and an outline of addressable top-level blocks.
- It proposes operations such as insert, replace, move or delete against that revision. A stale revision is refused before applying the batch.
- Operations stage against a parsed Markdown tree. The assembled result must pass dialect validation and a Lexical import/export round trip.
- Reconciliation reuses untouched or moved nodes. A durable commit precedes broadcasting the update and its recent-change markers.
Preserving node identity helps preserve unaffected selections, cursors and undo history. The ordinary operation vocabulary also includes whole-document replacement; careful block edits are a supported mechanism, not a promise that every agent change is small.
The edit engine is the most useful starting point for studying agent changes. Read it beside the browser binding and the architecture’s human edit flow.
The document language is an explicit boundary
Chopin’s MDX is parsed into approved structures and rendered through components the application owns. Imports, exports, expressions, raw HTML and unknown JSX are rejected. It does not compile arbitrary document text into executable React code. The same dialect allowlist and validation rules shape browser feedback and server acceptance.
Keep decisions and authorship durable
Questionnaire answers and accepted comment decisions live in records beside the document. Their visible components project those records. An ordinary browser edit cannot create, remove or alter a protected decision projection; domain operations update the record and its projection together.
This matters when an agent rewrites a plan. A recommendation, a casual agreement in Chat and a saved decision have different meanings. Saving an answer records its author. Reopening retains earlier answers while a new one develops. A rewrite of the prose does not acquire authority to change that history. See the decision lifecycle.
Recent agent change marks are a different feature. They help a person notice additions, moves and deletions while working. They are temporary browser decoration, not a durable ledger of agent and model contributions. LL’s machine-readable attribution still needs to survive saves, imports and exports independently of any visible highlight.
Document authority and execution authority are separate
The default Copilot-backed Planner has bounded repository-reading tools and document tools. The Atomic harness deliberately gives Planner shell and filesystem capabilities as the server process’s user. A remote Planner moves model execution to an attached client while server tools still enforce document authority. Those configurations have materially different execution boundaries.
Chopin uses GitHub identity and repository permissions: pull access can read channels, while push or administration access permits changes. Browser access also checks the GitHub App installation. External MCP uses its caller’s GitHub bearer directly. Public repository access does not make the channel anonymously readable. These rules fit repository collaboration; LL’s owner, invited-reader and public audiences need their own authorization. Trust boundaries.
A small authoring experiment for Liberty Labs
Proposed first step: evaluate a visual Markdown editor for the owner’s writing room, using synthetic writing and the existing save contract. This is a local experiment to decide whether editing becomes better. Real-time multiplayer, a hosted Planner and a storage migration are separate choices.
LL currently uses CodeMirror for Markdown source editing. An MDXEditor integration could live in a bounded React mount in the owner editor while the application keeps its TypeScript request handler, server-rendered reading pages and authoritative D1 store. That is an implementation hypothesis to test; this study has not installed or integrated it.
- Define the supported writing subset. Use synthetic headings, links, lists, quotations, fenced code, tables and images. Include comments and protected source fragments whose preservation matters. Unsupported content must remain intact or refuse the edit clearly.
- Prove round trips before choosing the editor. Import, edit, undo, export, save, reload and compare meaning and preserved source. Exercise keyboard selection, paste and phone editing. A successful mount is insufficient.
- Keep one save authority. Save to D1 through the existing owner checks and writing revision. Keep audience changes separate. Stale saves, disconnects and failed saves must not lose text or quietly replace newer writing.
- Retain source editing as a deliberate choice. Test moving between source and visual views without introducing a second independently saved copy. Imported standalone HTML documents keep their existing format; they do not become restricted MDX through a bulk conversion.
- Study agent edits separately. A later owner-authorized edit tool could accept revision-checked block operations. Record the contributor and verified model, preserve earlier attribution, and let LL choose its public presentation. Any persistent schema change needs its own reviewed migration.
| Question | Required result |
|---|---|
| Does editing help? | Normal writing, keyboard use, undo and phone editing work in the real browser. |
| Does content survive? | Supported content round-trips; unsupported content and attribution are preserved or explicitly refused. |
| Does saving remain correct? | Reloads read the same D1 state; stale and failed saves preserve the author’s work. |
| Does access remain correct? | Only the owner edits. Invited readers remain readers. Ordinary saves retain the current audience. |
| Is adoption worthwhile? | Observed editing improvements justify bundle, integration and maintenance costs. |
The most transferable Chopin patterns are shared validation, revision-aware edits and durable records for decisions and contributions. Its PostgreSQL writer lease, collaborative server and GitHub authorization model belong to a larger system choice.
Sources and evidence limits
This is a dated reading of source and design contracts at one commit. It is not a fresh runtime test, security audit, editor benchmark or claim of production readiness. Chopin’s own documentation describes it as an experimental research prototype and lists implementation gaps.
- README and GitHub Next introduction: purpose and collaboration model. The child-Chat discrepancy is noted above.
- Architecture and maintainer guide: authority, persistence, collaboration and known gaps.
- Pinned dependencies, editor composition, collaboration binding and schema registry: the actual MDXEditor/Lexical/Yjs integration.
- Agent edit engine and validator: revision checks, staging and accepted document structures.
- Decisions and storage: saved answers, related prose and durable state.
The LL section is a proposed experiment based on the current authoring contract. No editor replacement, data migration or deployment follows from this note.