feat(workspace): unify document content model — timeline-backed DocumentHandle

.agents/skills/workspace-api/SKILL.md

@@ -275,53 +275,68 @@ return { ...row, views: 0, _v: 2 as const }; // Also works — redundant
 
 ## Document Content (Per-Row Y.Docs)
 
-Tables with `.withDocument()` create a content Y.Doc per row. Content is stored using a **timeline model**: a `Y.Array('timeline')` inside the Y.Doc, where each entry is a typed `Y.Map` supporting text, binary, and sheet modes.
+Tables with `.withDocument()` create a content Y.Doc per row. Content is stored using a **timeline model**: a `Y.Array('timeline')` inside the Y.Doc, where each entry is a typed `Y.Map` supporting text, richtext, and sheet modes.
 
 ### Reading and Writing Content
 
-Use the filesystem package's content helpers, which read/write via the timeline:
+Use `handle.read()`/`handle.write()` on the document handle:
 
 ```typescript
-import { createYjsFileSystem } from '@epicenter/filesystem';
-
-const fs = createYjsFileSystem(ws.tables.files, ws.documents.files.content);
+const handle = await documents.open(fileId);
 
 // Read content (timeline-backed)
-const text = await fs.content.read(fileId);
+const text = handle.read();
 
 // Write content (timeline-backed)
-await fs.content.write(fileId, 'hello');
+handle.write('hello');
+
+// Editor binding — Y.Text (converts from other modes if needed)
+const ytext = handle.asText();
+
+// Richtext editor binding — Y.XmlFragment (converts if needed)
+const fragment = handle.asRichText();
+
+// Spreadsheet binding — SheetBinding (converts if needed)
+const { columns, rows } = handle.asSheet();
+
+// Current content mode
+handle.mode; // 'text' | 'richtext' | 'sheet' | undefined
+
+// Advanced timeline operations
+const tl = handle.timeline;
 ```
 
-### Anti-Patterns
+For filesystem operations, `fs.content.read(fileId)` and `fs.content.write(fileId, data)` open the handle and delegate to these methods internally.
+
+### Batching Mutations
 
-**Do not use `handle.read()`/`handle.write()`** for apps that also use the filesystem API. These methods read/write from `Y.Text('content')`—a different shared type than the timeline—causing silent data loss:
+Use `handle.batch()` to group multiple mutations into a single Yjs transaction:
 
 ```typescript
-// ❌ BAD: handle uses Y.Text('content'), filesystem uses Y.Array('timeline')
-const handle = await ws.documents.files.content.open(id);
-handle.read();      // reads from wrong shared type
-handle.write('x');  // writes to wrong shared type
-
-// ✅ GOOD: use fs.content which reads/writes via timeline
-await fs.content.read(id);
-await fs.content.write(id, 'hello');
+handle.batch(() => {
+  handle.write('hello');
+  // ...other mutations
+});
 ```
 
-**Do not access `handle.ydoc` directly for content:**
+**Do NOT call `handle.ydoc.transact()` directly.** Use `handle.batch()` instead.
+
+### Anti-Patterns
+
+**Do not access `handle.ydoc` for content operations:**
 
 ```typescript
-// ❌ BAD: bypasses all abstractions
+// ❌ BAD: bypasses timeline abstraction
 const ytext = handle.ydoc.getText('content');
-const fragment = handle.ydoc.getXmlFragment('content');
+handle.ydoc.transact(() => { ... });
 
-// ✅ GOOD: use timeline abstraction
-import { createTimeline } from '@epicenter/filesystem';
-const tl = createTimeline(handle.ydoc);
-const text = tl.readAsString();
+// ✅ GOOD: use handle methods
+const ytext = handle.asText();
+const fragment = handle.asRichText();
+handle.batch(() => { ... });
 ```
 
-See `specs/20260313T224500-unify-document-content-model.md` for the full unification plan.
+`handle.ydoc` is an **escape hatch** for document extensions (persistence, sync providers) and tests. App code should never need it.
 
 ## References
 

.agents/skills/yjs/SKILL.md

@@ -209,28 +209,21 @@ Any concurrent edits to the "moved" item are lost because you deleted the origin
 
 ### 6. Accessing Raw Y.Doc Shared Types for Document Content
 
-Document Y.Docs in this codebase use a timeline model (`Y.Array('timeline')` with nested typed entries). Accessing top-level shared types directly writes to a different location than the timeline, causing silent data loss:
+Document Y.Docs use a timeline model (`Y.Array('timeline')` with nested typed entries). Never access raw shared types on the ydoc directly—use the handle methods:
 
 ```typescript
-// BAD: writes to Y.Text('content'), not the timeline
+// BAD: bypasses the timeline
 const ytext = handle.ydoc.getText('content');
-ytext.insert(0, 'hello');  // invisible to fs.readFile()
 
-// BAD: handle.read/write also uses Y.Text('content')
-handle.read();   // reads from wrong shared type
-handle.write('x'); // writes to wrong shared type
-
-// GOOD: use filesystem content helpers (timeline-backed)
-await fs.content.read(id);
-await fs.content.write(id, 'hello');
-
-// GOOD: use timeline abstraction directly if needed
-import { createTimeline } from '@epicenter/filesystem';
-const tl = createTimeline(handle.ydoc);
-const text = tl.readAsString();
+// GOOD: use handle methods (timeline-backed)
+handle.read();        // string I/O
+handle.write('hello');
+handle.asText();      // Y.Text for editor binding
+handle.asRichText();  // Y.XmlFragment for richtext binding
+handle.asSheet();     // SheetBinding for spreadsheet binding
 ```
 
-See `specs/20260313T224500-unify-document-content-model.md`.
+See the **workspace-api** skill for the full `DocumentHandle` API.
 
 ## Debugging Tips
 

AGENTS.md

@@ -11,5 +11,3 @@ Destructive actions need approval: Force pushes, hard resets (`--hard`), branch
 Token-efficient execution: When possible, delegate to sub-agent with only the command. Instruct it to execute without re-analyzing.
 
 Writing conventions: Load `writing-voice` skill for any user-facing text—UI strings, tooltips, error messages, docs. Em dashes are always closed (no spaces).
-
-Content model: Document content uses the timeline model (`Y.Array('timeline')`). Never access `handle.ydoc.getText('content')` or use `handle.read()`/`handle.write()` alongside filesystem APIs—use `fs.content.read/write` or `createTimeline(ydoc)` from `@epicenter/filesystem` instead. See `specs/20260313T224500-unify-document-content-model.md`.

apps/fuji/src/routes/+page.svelte

@@ -133,7 +133,7 @@
 		workspaceClient.documents.entries.body.open(entryId).then((handle) => {
 			if (cancelled) return;
 			currentDocHandle = handle;
-			currentYText = handle.ydoc.getText('content');
+			currentYText = handle.asText();
 		});
 
 		return () => {

apps/honeycrisp/src/routes/+page.svelte

@@ -125,7 +125,7 @@
 		workspaceClient.documents.notes.body.open(noteId).then((handle) => {
 			if (cancelled) return;
 			currentDocHandle = handle;
-			currentYXmlFragment = handle.ydoc.getXmlFragment('content');
+			currentYXmlFragment = handle.asRichText();
 		});
 
 		return () => {

docs/articles/only-the-leaves-need-revision-history.md

@@ -22,7 +22,7 @@ Metadata Y.Doc (gc: true, always loaded)
     └── { key: 'theme', val: 'dark', ts: ... }
 
 Content Y.Doc (gc: false, loaded on demand)          ← one per file
-└── Y.Text('content')    or    Y.XmlFragment('content')
+└── Y.Array('timeline')  →  [{ type: 'text', content: Y.Text }]
 ```
 
 The metadata doc is a single document containing all your structural data: file names, parent IDs, timestamps, settings. It's small and always in memory. Garbage collection is on, so tombstones from updates get merged into a few bytes.

docs/articles/updated-at-sentinel-for-external-yjs-docs.md

@@ -13,10 +13,10 @@ Metadata Y.Doc (gc: true, always loaded)
 │   └── { id: 'def', name: 'index.ts', size: 512, updatedAt: ... }
 
 Content Y.Doc 'abc' (gc: false, loaded on demand)
-└── Y.Text('content')  →  "# API Reference\n..."
+└── Y.Array('timeline')  →  [{ type: 'text', content: Y.Text('# API Reference\n...') }]
 
 Content Y.Doc 'def' (gc: false, loaded on demand)
-└── Y.Text('content')  →  "export function main() {..."
+└── Y.Array('timeline')  →  [{ type: 'text', content: Y.Text('export function main() {...') }]
 ```
 
 A user opens `api.md` and starts typing. Content doc `abc` gets updated, but the files table row still has the same name, same size, same `updatedAt`. No observer fires. Persistence doesn't save. The UI doesn't reflect the edit. The reference doesn't propagate change events.

packages/filesystem/src/content/entry-types.ts

@@ -1,27 +1,11 @@
-import type * as Y from 'yjs';
-
 /**
- * Timeline entry shapes — a discriminated union on 'type'.
- * These describe the SHAPE of what's stored. At runtime, entries are Y.Map
- * instances accessed via .get('type'), .get('content'), etc.
+ * Re-export entry types from @epicenter/workspace where the canonical
+ * definitions now live.
  */
-export type TextEntry = { type: 'text'; content: Y.Text };
-export type RichTextEntry = {
-	type: 'richtext';
-	content: Y.XmlFragment;
-	frontmatter: Y.Map<unknown>;
-};
-export type BinaryEntry = { type: 'binary'; content: Uint8Array };
-export type SheetEntry = {
-	type: 'sheet';
-	columns: Y.Map<Y.Map<string>>;
-	rows: Y.Map<Y.Map<string>>;
-};
-export type TimelineEntry =
-	| TextEntry
-	| RichTextEntry
-	| BinaryEntry
-	| SheetEntry;
-
-/** Content modes supported by timeline entries */
-export type ContentMode = TimelineEntry['type'];
+export type {
+	ContentMode,
+	RichTextEntry,
+	SheetEntry,
+	TextEntry,
+	TimelineEntry,
+} from '@epicenter/workspace';

packages/filesystem/src/content/index.ts

@@ -1,9 +1,4 @@
-export {
-	type ContentHelpers,
-	createContentHelpers,
-} from './content.js';
 export type {
-	BinaryEntry,
 	ContentMode,
 	RichTextEntry,
 	SheetEntry,