Address PR review feedback: comprehensive improvements

Implements all P0, P1, and P2 items from code review:

## P0 (Blockers)
- Add 12 comprehensive tests for document-session parser
  - Round-trip edits, multi-segment edits, error cases
  - Segment reordering, validation, whitespace handling
- Update CLAUDE.md with canonical document model section
  - Architecture, lifecycle, editor buffer format
  - Database schema with all new tables
- Fix node refresh persistence bug
  - updateNode now called to persist changes to DB

## P1 (Recommended)
- Add /api/v1/documents endpoints
  - GET /documents - list all
  - GET /documents/:id - get by ID
  - GET /documents/:id/chunks - get chunks
- Add backfill logging for observability
  - Shows count when backfilling canonical documents
- Type DocumentMetadata properly
  - Replaces Record<string, unknown> with typed interface
  - Includes import settings, edit tracking, backfill flags

## P2 (Nice to Have)
- Add CLI document commands
  - forest documents list
  - forest documents show [id] --chunks
  - forest documents stats
- Improve bun:test types
  - Replace stub with @types/bun package

Generated with Claude Code (https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: bwl

.claude/settings.local.json

@@ -8,7 +8,9 @@
       "WebFetch(domain:platform.openai.com)",
       "WebFetch(domain:raw.githubusercontent.com)",
       "Bash(gh pr view:*)",
-      "Bash(gh pr diff:*)"
+      "Bash(gh pr diff:*)",
+      "Bash(bun test:*)",
+      "Bash(bun run lint)"
     ],
     "deny": [],
     "ask": []

CLAUDE.md

@@ -327,13 +327,120 @@ When implementing a new feature that should be available in both CLI and API:
 Uses **sql.js** (SQLite compiled to WASM) with in-memory database persisted to disk on mutation.
 
 **Core types:**
-- `NodeRecord`: Nodes with id, title, body, tags, tokenCounts, optional embedding
-- `EdgeRecord`: Edges with sourceId, targetId, score, status ('accepted' | 'suggested')
+- `NodeRecord`: Nodes with id, title, body, tags, tokenCounts, optional embedding, isChunk, parentDocumentId, chunkOrder
+- `EdgeRecord`: Edges with sourceId, targetId, score, status ('accepted' | 'suggested'), edgeType
+- `DocumentRecord`: Canonical documents with id, title, body, metadata, version, rootNodeId, timestamps
+- `DocumentChunkRecord`: Segment mappings with documentId, segmentId, nodeId, offset, length, chunkOrder, checksum, timestamps
 
 **Key pattern**: Database is lazily initialized on first access. All mutations set `dirty = true` and persist to disk.
 
 Database path controlled by `FOREST_DB_PATH` env var (default: `forest.db` in cwd).
 
+**Database Schema:**
+```sql
+-- Core node storage
+nodes: id, title, body, tags, token_counts, embedding, created_at, updated_at,
+       is_chunk, parent_document_id, chunk_order
+
+-- Edge relationships
+edges: id, source_id, target_id, score, status, edge_type, metadata, created_at, updated_at
+
+-- Canonical document storage
+documents: id, title, body, metadata, version, root_node_id, created_at, updated_at
+
+-- Document-to-node mappings
+document_chunks: document_id, segment_id, node_id, offset, length, chunk_order, checksum,
+                 created_at, updated_at
+
+-- Edge event history (for undo)
+edge_events: id, edge_id, source_id, target_id, prev_status, next_status, payload,
+             created_at, undone
+
+-- Metadata key-value store
+metadata: key, value
+```
+
+### Canonical Document Model (src/lib/db.ts, src/core/import.ts)
+
+Forest treats multi-chunk imports as first-class documents with versioned canonical storage.
+
+**Architecture:**
+- **Canonical body**: Stored in `documents.body` as the authoritative source, reconstructed from `\n\n`-joined segment bodies
+- **Chunk mappings**: `document_chunks` table tracks byte offsets, lengths, and SHA-256 checksums for each segment
+- **Version tracking**: `documents.version` increments on every edit; metadata stores `lastEditedAt` and `lastEditedNodeId`
+- **Automatic backfill**: On startup, `backfillCanonicalDocuments()` scans for chunk nodes without canonical entries (idempotent)
+
+**Lifecycle:**
+
+1. **Import** (`importDocumentCore` in `src/core/import.ts`)
+   - Chunks document via `chunkDocument()` using headers/size/hybrid strategy
+   - Creates root node (optional summary) and chunk nodes with `isChunk=true`, `parentDocumentId` set
+   - Inserts canonical document record with metadata (chunkStrategy, maxTokens, overlap, etc.)
+   - Creates `document_chunks` mappings with offsets and checksums
+   - Builds structural edges: parent-child (root→chunks) and sequential (chunk[i]→chunk[i+1])
+   - Optionally auto-links against existing graph
+
+2. **Edit** (`forest node edit <chunk-id>`)
+   - Detects chunk membership via `loadDocumentSessionForNode()`
+   - Renders full document with `<!-- forest:segment -->` markers (HTML comments)
+   - User edits in their preferred editor
+   - Parser validates all segments present, IDs match, no orphans
+   - Only modified segments get re-embedded and rescored (selective performance optimization)
+   - Canonical body, version, and chunk records updated atomically
+   - Console shows: "document updated: <title> (version 1 → 2, segments touched: 2)"
+
+3. **Refresh** (`forest node refresh <chunk-id>`)
+   - Updates chunk node via flags/files/stdin
+   - Detects chunk membership and rebuilds canonical document
+   - Version bumps, checksums and offsets recalculated
+   - Logs: "document updated" or "document unchanged (no structural delta)"
+
+4. **Standalone notes**
+   - Nodes with `isChunk=false` bypass document session entirely
+   - Edited as independent entities with no canonical storage
+
+**Key behaviors:**
+- **Selective re-embedding**: Unchanged segments retain embeddings and edges (avoids expensive recomputation)
+- **Checksum-based change detection**: SHA-256 of normalized content enables efficient diffing
+- **Temp file preservation**: Parse failures save edited content to `/tmp/forest-edit-*` for debugging
+- **Segment reordering**: Parser detects order changes; `chunkOrder` updated accordingly
+- **Error recovery**: Validation errors show line numbers; user can fix and retry
+
+**Editor buffer format example:**
+```markdown
+# Forest Document Editor
+# Document: My Research Paper (7fa7acb2)
+# Total segments: 3
+
+<!-- forest:segment start segment_id=seg-1 node_id=abc123 order=0 title="Introduction" -->
+This is the introduction content...
+<!-- forest:segment end segment_id=seg-1 -->
+
+<!-- forest:segment start segment_id=seg-2 node_id=def456 order=1 title="Methods" focus=true -->
+This is the methods section...
+<!-- forest:segment end segment_id=seg-2 -->
+```
+
+**Metadata schema** (DocumentRecord.metadata):
+```typescript
+{
+  // Import settings
+  chunkStrategy: 'headers' | 'size' | 'hybrid',
+  maxTokens: number,
+  overlap: number,
+  chunkCount: number,
+  source: 'import' | 'backfill',
+
+  // Edit tracking
+  lastEditedAt: ISO8601 timestamp,
+  lastEditedNodeId: UUID,
+
+  // Backfill flags
+  backfill: boolean,
+  chunkOrdersProvided: boolean
+}
+```
+
 ### Scoring Algorithm (src/lib/scoring.ts)
 
 **Hybrid scoring** computes edge weights between node pairs:

bun.lock

@@ -10,7 +10,8 @@
     "lint": "bunx tsc --noEmit",
     "dev": "bunx tsx src/index.ts",
     "dev:server": "bunx tsx src/server/index.ts",
-    "start": "bun run dist/index.js"
+    "start": "bun run dist/index.js",
+    "test": "bun test"
   },
   "keywords": [
     "graph",
@@ -34,6 +35,7 @@
     "sql.js": "^1.11.0"
   },
   "devDependencies": {
+    "@types/bun": "^1.3.0",
     "@types/marked-terminal": "^6.1.1",
     "@types/node": "^20.11.20",
     "@types/sql.js": "^1.4.9",