docs: add project planning documents

2026-04-28 23:59:45 -04:00
commit 8e6646499f
16 changed files with 2343 additions and 0 deletions
--- a/docs/milestones/milestone-01-foundation.md
+++ b/docs/milestones/milestone-01-foundation.md
@@ -0,0 +1,118 @@
+# Milestone 1: Foundation
+
+**Duration:** 2 weeks  
+**Goal:** Working server that can serve markdown files as HTML
+
+## Tasks
+
+### Week 1: Project Setup & Infrastructure
+
+- [ ] Initialize monorepo structure
+  - `apps/server/` with Go module
+  - `apps/web/` with Vite + Preact + TypeScript
+  - `packages/protocol/` with protobuf schema
+  - `docs/` with existing documentation
+  
+- [ ] Go server skeleton
+  - `main.go` with graceful shutdown
+  - Chi router with middleware chain
+  - Configuration management (environment variables + config file)
+  - Structured logging (slog)
+  
+- [ ] Database layer
+  - libsql connection setup
+  - Migration system (golang-migrate)
+  - Initial schema (users, documents, document_versions)
+  - Query builder / repository pattern
+  
+- [ ] Docker setup
+  - Multi-stage Dockerfile for Go app
+  - `docker-compose.yml` with volume mounts
+  - Health check endpoint
+  - Non-root user in container
+
+### Week 2: Markdown Rendering & Static Serving
+
+- [ ] Markdown parser integration
+  - Goldmark with all extensions
+  - Wiki-link parser: `[[Page Name]]` → internal link
+  - Tag extractor: `#tagname` → tag link
+  - Admonition support: `> [!NOTE]` blocks
+  - Mermaid diagram containers
+  - Math markup containers (KaTeX)
+  
+- [ ] Template system
+  - Base layout template (header, nav, footer)
+  - Document template with rendered markdown
+  - Error page templates (404, 500)
+  - Design system CSS custom properties
+  
+- [ ] Static file serving
+  - Content-addressed filesystem setup
+  - File upload endpoint (basic)
+  - Security headers middleware
+  - MIME type detection
+  
+- [ ] Initial frontend
+  - Preact app setup with Vite
+  - Basic routing (preact-iso)
+  - Hydration entry point
+  - CSS design system foundation
+
+## Acceptance Criteria
+
+### Functional
+- [ ] Server starts and listens on configurable port (default 8080)
+- [ ] Database auto-migrates on startup with no manual intervention
+- [ ] Markdown files render correctly with all extensions:
+  - [ ] Wiki-links resolve to internal document paths
+  - [ ] Tags are extracted and displayed
+  - [ ] Admonitions render with appropriate styling
+  - [ ] Mermaid diagrams have syntax-highlighted containers
+  - [ ] Math markup has proper delimiters for KaTeX
+- [ ] Attachments served with correct Content-Type headers
+- [ ] 404 and 500 pages render correctly
+
+### Non-Functional
+- [ ] Docker compose brings up full stack with `docker-compose up -d`
+- [ ] Container health check passes within 30 seconds
+- [ ] All Go dependencies pinned in go.sum
+- [ ] Build is reproducible (same commit → same binary hash)
+- [ ] No plaintext secrets in code or logs
+- [ ] Security headers present on all responses:
+  - [ ] Content-Security-Policy
+  - [ ] X-Content-Type-Options: nosniff
+  - [ ] X-Frame-Options: DENY
+  - [ ] Referrer-Policy: strict-origin-when-cross-origin
+
+### Performance
+- [ ] Initial page load (TTFB) <100ms for cached documents
+- [ ] Markdown rendering <50ms for documents <100KB
+- [ ] Static file serving supports 1000 concurrent requests
+
+## Deliverables
+
+1. Working development environment (README with setup instructions)
+2. CI pipeline (GitHub Actions or similar) with:
+   - Go tests
+   - TypeScript type checking
+   - Dockerfile build
+   - Security scan (govulncheck)
+3. API documentation (OpenAPI spec)
+4. Database migration files
+
+## Risk Mitigation
+
+| Risk | Mitigation |
+|------|-----------|
+| Goldmark extension conflicts | Test each extension in isolation, then combined |
+| Docker volume permissions | Document UID/GID requirements, provide setup script |
+| libsql compatibility | Test on both native SQLite and Turso cloud |
+
+## Definition of Done
+
+- [ ] All acceptance criteria pass
+- [ ] Code review completed
+- [ ] Documentation updated
+- [ ] CI pipeline green
+- [ ] Security scan shows no critical/high vulnerabilities
--- a/docs/milestones/milestone-02-sync-protocol.md
+++ b/docs/milestones/milestone-02-sync-protocol.md
@@ -0,0 +1,143 @@
+# Milestone 2: Sync Protocol
+
+**Duration:** 2 weeks  
+**Goal:** Bidirectional file sync between server and filesystem/web client
+
+## Tasks
+
+### Week 3: Server-Side Sync
+
+- [ ] Content-addressed filesystem implementation
+  - SHA-256 hash computation
+  - Directory layout: `store/ab/cd/abcdef...`
+  - Write-once semantics
+  - Deduplication verification
+  
+- [ ] File watcher (fsnotify)
+  - Watch configured directory recursively
+  - Debounce rapid changes (1s window)
+  - Ignore patterns (.git, temp files)
+  - Compute hash on change, update database
+  
+- [ ] WebSocket server
+  - Connection management (connection pool)
+  - Message framing and parsing
+  - Authentication over WebSocket (token validation)
+  - Heartbeat/ping-pong for connection health
+  
+- [ ] SimpleSync protocol server implementation
+  - Sync request/response handler
+  - Root hash computation (Merkle tree)
+  - Missing content detection
+  - Conflict detection logic
+
+### Week 4: Client-Side Sync & Offline Support
+
+- [ ] WebSocket client (Preact)
+  - Connection management with auto-reconnect
+  - Message queue for offline periods
+  - Exponential backoff for reconnection
+  
+- [ ] IndexedDB cache layer
+  - Store file content by hash
+  - Store sync state and pending changes
+  - LRU eviction for cache management
+  
+- [ ] File sync UI
+  - Sync status indicator
+  - Offline mode banner
+  - Pending changes list
+  - Manual sync trigger button
+  
+- [ ] Conflict detection display
+  - Visual indicator for conflicting files
+  - Basic conflict resolution UI (choose local/server)
+
+## Acceptance Criteria
+
+### Functional
+- [ ] File changes on disk automatically sync to server within 5 seconds
+- [ ] Web client receives real-time updates when files change on server
+- [ ] Client can make changes offline and sync when reconnected
+- [ ] Concurrent edits to different files succeed without conflict
+- [ ] Concurrent edits to same file detected as conflict
+- [ ] Content hash verified on every transfer (client and server)
+- [ ] Sync works across browser refresh (IndexedDB persistence)
+
+### Non-Functional
+- [ ] WebSocket connections authenticated (reject unauthenticated)
+- [ ] File watcher doesn't consume >1% CPU on idle
+- [ ] IndexedDB storage cleared on logout
+- [ ] Sync protocol documented with sequence diagrams
+
+### Performance
+- [ ] Sync of 100 files completes in <10 seconds
+- [ ] WebSocket message overhead <1KB per sync cycle
+- [ ] File watcher detects changes within 500ms
+
+## Protocol Specification
+
+### Message Types
+
+```typescript
+// Client → Server
+interface SyncRequest {
+  type: 'sync_request';
+  clientId: string;
+  rootHash: string;
+  files: Record<string, string>; // path → hash
+}
+
+// Server → Client
+interface SyncResponse {
+  type: 'sync_response';
+  serverRootHash: string;
+  missingFromClient: string[]; // hashes to download
+  missingFromServer: string[]; // hashes to upload
+  conflicts: string[]; // file paths with conflicts
+}
+
+// Content request
+interface ContentRequest {
+  type: 'content_request';
+  hash: string;
+}
+
+// Content response
+interface ContentResponse {
+  type: 'content_response';
+  hash: string;
+  content: string; // base64 encoded
+}
+```
+
+### State Machine
+
+```
+[Idle] --sync_request--> [Comparing] --has_differences--> [Transferring] --complete--> [Idle]
+                                      --no_differences--> [Idle]
+[Idle] --file_change--> [LocalChange] --sync--> [Comparing]
+```
+
+## Deliverables
+
+1. SimpleSync protocol specification document
+2. Sequence diagrams for all sync scenarios
+3. WebSocket API documentation
+4. Offline sync test suite
+
+## Risk Mitigation
+
+| Risk | Mitigation |
+|------|-----------|
+| WebSocket connection drops frequently | Auto-reconnect with exponential backoff, queue offline |
+| Large files cause sync delays | Chunked transfer, progress indicators, size limits |
+| Conflicts in frequently edited files | Optimistic UI, clear conflict resolution, email notification |
+
+## Definition of Done
+
+- [ ] All acceptance criteria pass
+- [ ] Sync protocol tested with 2+ concurrent clients
+- [ ] Offline/online transition tested
+- [ ] Performance benchmarks meet targets
+- [ ] Documentation complete
--- a/docs/milestones/milestone-03-authentication.md
+++ b/docs/milestones/milestone-03-authentication.md
@@ -0,0 +1,134 @@
+# Milestone 3: Authentication & Authorization
+
+**Duration:** 2 weeks  
+**Goal:** Secure access control with passkeys and granular permissions
+
+## Tasks
+
+### Week 5: Passkey Authentication
+
+- [ ] WebAuthn server implementation
+  - Relying party configuration
+  - Challenge generation and storage
+  - Attestation verification
+  - Credential storage (credential ID, public key, sign count)
+  
+- [ ] Passkey registration flow
+  - Initiate registration endpoint
+  - Verify registration response
+  - Store credential with user association
+  - Support multiple passkeys per user
+  
+- [ ] Passkey authentication flow
+  - Initiate login endpoint
+  - Verify assertion response
+  - Create session on success
+  
+- [ ] Session management
+  - Signed cookie generation
+  - Session storage in database
+  - Session validation middleware
+  - Session revocation endpoint
+  - Automatic session refresh
+
+### Week 6: Password Fallback & Authorization
+
+- [ ] Password authentication
+  - Argon2id password hashing
+  - Password validation endpoint
+  - Password change endpoint
+  - Password strength requirements
+  
+- [ ] Role-based access control
+  - Permission model: read, write, admin
+  - Scope: global, collection, document
+  - Middleware for permission checking
+  - Admin UI for managing permissions
+  
+- [ ] User management
+  - User registration (email + passkey/password)
+  - User profile management
+  - Account deletion (GDPR compliance)
+  - User listing (admin only)
+  
+- [ ] Content signing (optional)
+  - Ed25519 key pair generation
+  - Document signing on publish
+  - Signature verification display
+
+## Acceptance Criteria
+
+### Functional
+- [ ] Users can register with passkey on supported browsers
+- [ ] Passkey login works with Touch ID, Windows Hello, YubiKey
+- [ ] Password fallback works when passkey unavailable
+- [ ] Sessions expire after configurable timeout (default 24h)
+- [ ] Sessions can be revoked (logout all devices)
+- [ ] Read/write/admin permissions enforced on all endpoints
+- [ ] Users can only access documents they have permission for
+- [ ] Admin users can manage other users' permissions
+
+### Non-Functional
+- [ ] Argon2id parameters: time=3, memory=64MB, parallelism=4
+- [ ] Session cookies: HttpOnly, Secure, SameSite=Strict
+- [ ] Rate limiting: 5 auth attempts per minute per IP
+- [ ] No timing attacks on password comparison (constant-time)
+- [ ] All auth events logged to audit_log table
+- [ ] Ed25519 signatures verified on document read (if enabled)
+
+### Security
+- [ ] WebAuthn challenges single-use and time-limited (5 minutes)
+- [ ] Credential IDs are unpredictable (128-bit random)
+- [ ] Password reset requires email verification
+- [ ] No enumeration attacks (same response for exist/non-exist user)
+
+## Database Schema Additions
+
+```sql
+-- WebAuthn credentials
+CREATE TABLE webauthn_credentials (
+    id TEXT PRIMARY KEY,
+    user_id TEXT NOT NULL REFERENCES users(id),
+    credential_id BLOB NOT NULL UNIQUE,
+    public_key BLOB NOT NULL,
+    sign_count INTEGER NOT NULL DEFAULT 0,
+    created_at DATETIME NOT NULL,
+    last_used_at DATETIME
+);
+
+-- Permissions
+CREATE TABLE permissions (
+    id TEXT PRIMARY KEY,
+    user_id TEXT NOT NULL REFERENCES users(id),
+    resource_type TEXT NOT NULL CHECK(resource_type IN ('global', 'collection', 'document')),
+    resource_id TEXT, -- NULL for global
+    permission TEXT NOT NULL CHECK(permission IN ('read', 'write', 'admin')),
+    granted_by TEXT REFERENCES users(id),
+    created_at DATETIME NOT NULL
+);
+```
+
+## Deliverables
+
+1. Authentication API documentation
+2. WebAuthn flow diagrams
+3. Permission system documentation
+4. Security test results (penetration test guide)
+
+## Risk Mitigation
+
+| Risk | Mitigation |
+|------|-----------|
+| Passkey not supported on user's device | Password fallback always available |
+| User loses all passkeys | Recovery email + backup codes |
+| Permission system too complex | Start with simple roles, iterate |
+| Session hijacking | Short expiry, rotation, revocation |
+
+## Definition of Done
+
+- [ ] All acceptance criteria pass
+- [ ] Security review completed
+- [ ] Auth flow tested on Chrome, Firefox, Safari, Edge
+- [ ] Mobile passkey tested (iOS, Android)
+- [ ] Rate limiting verified
+- [ ] Audit logs verified
--- a/docs/milestones/milestone-04-collaboration.md
+++ b/docs/milestones/milestone-04-collaboration.md
@@ -0,0 +1,171 @@
+# Milestone 4: Collaboration Features
+
+**Duration:** 2 weeks  
+**Goal:** Comments, notifications, email integration, and conflict resolution
+
+## Tasks
+
+### Week 7: Comments & Notifications
+
+- [ ] Comment system
+  - Comment creation endpoint (web)
+  - Comment threading (parent/child)
+  - Line/section anchoring (hash-based)
+  - Comment resolution (mark as resolved)
+  - Comment display in Preact UI
+  
+- [ ] Notification system
+  - Notification queue in database
+  - Per-file watcher subscriptions
+  - Per-folder watcher subscriptions
+  - Global notification settings
+  - Digest mode (hourly/daily batches)
+  
+- [ ] Web notification UI
+  - Notification bell with unread count
+  - Notification list dropdown
+  - Mark as read functionality
+  - Notification preferences page
+
+### Week 8: Email Integration & Conflict Resolution
+
+- [ ] Postmark integration
+  - Go adapter setup
+  - Plain-text email templates
+  - Outgoing email queue with retry
+  - Webhook endpoint for inbound email
+  
+- [ ] Email notification types
+  - File changed notification
+  - New comment notification
+  - Mention notification (@username)
+  - Conflict alert notification
+  - Digest summary email
+  
+[ ] Email reply handling
+  - Parse inbound email (from, subject, body)
+  - Match to comment thread via In-Reply-To
+  - Create comment from email body
+  - Validate sender permission
+  
+- [ ] Conflict resolution UI
+  - Side-by-side diff view
+  - Accept local/server/merge options
+  - Manual merge editor
+  - Conflict notification email
+
+## Acceptance Criteria
+
+### Functional
+- [ ] Users can add comments to specific lines in a document
+- [ ] Comments are linked to document version (hash)
+[ ] Comment threading works (reply to reply)
+- [ ] Users can watch files or folders for changes
+- [ ] Email notifications sent within 1 minute of event
+- [ ] Replying to notification email creates a comment
+- [ ] Digest emails batch notifications by time window
+- [ ] Conflicts display side-by-side diff
+- [ ] Users can resolve conflicts via web UI
+- [ ] Resolved comments are hidden but accessible in history
+
+### Non-Functional
+- [ ] Emails are plain-text only (no HTML)
+- [ ] Email threading works in Gmail, Outlook, Apple Mail
+- [ ] Webhook signature verified for inbound email
+- [ ] Failed emails retried 3 times with exponential backoff
+- [ ] Email queue doesn't block web requests (async processing)
+
+### Email Template Examples
+
+**File Change Notification:**
+```
+Subject: [docs/api-reference.md] Updated by Alice
+
+Alice updated "API Reference" at 2024-01-15 14:30 UTC.
+
+Changed sections:
+- Authentication
+- Rate Limiting
+
+View changes: https://example.com/docs/api-reference?v=abc123
+Unsubscribe: https://example.com/unsubscribe/123
+```
+
+**Comment Notification:**
+```
+Subject: [docs/getting-started.md] Comment from Bob
+
+Bob commented on "Getting Started":
+
+> This step is unclear. Can we add an example?
+
+Reply to this email to respond.
+
+View online: https://example.com/docs/getting-started#comment-456
+```
+
+## Database Schema Additions
+
+```sql
+-- Comments
+CREATE TABLE comments (
+    id TEXT PRIMARY KEY,
+    document_id TEXT NOT NULL REFERENCES documents(id),
+    version_hash TEXT NOT NULL,
+    parent_id TEXT REFERENCES comments(id),
+    author_id TEXT NOT NULL REFERENCES users(id),
+    content TEXT NOT NULL,
+    anchor_line INTEGER, -- line number for anchoring
+    anchor_hash TEXT, -- hash of specific content for anchoring
+    created_at DATETIME NOT NULL,
+    resolved_at DATETIME,
+    resolved_by TEXT REFERENCES users(id)
+);
+
+-- Notifications
+CREATE TABLE notifications (
+    id TEXT PRIMARY KEY,
+    user_id TEXT NOT NULL REFERENCES users(id),
+    type TEXT NOT NULL, -- file_changed, comment, mention, conflict
+    resource_type TEXT NOT NULL,
+    resource_id TEXT NOT NULL,
+    message TEXT NOT NULL,
+    read_at DATETIME,
+    emailed_at DATETIME,
+    created_at DATETIME NOT NULL
+);
+
+-- Watcher subscriptions
+CREATE TABLE watchers (
+    user_id TEXT REFERENCES users(id),
+    document_id TEXT REFERENCES documents(id),
+    folder_path TEXT,
+    created_at DATETIME NOT NULL,
+    PRIMARY KEY (user_id, document_id, folder_path)
+);
+```
+
+## Deliverables
+
+1. Email template documentation
+2. Webhook integration guide
+3. Comment API documentation
+4. Conflict resolution flow diagrams
+
+## Risk Mitigation
+
+| Risk | Mitigation |
+|------|-----------|
+| Email deliverability issues | Postmark reputation monitoring, SPF/DKIM setup |
+| Comment spam | Rate limiting, auth required, moderation tools |
+| Email parsing errors | Robust parser, fallback to plain text extraction |
+| Conflict resolution UI confusion | Clear visual design, undo option, help text |
+
+## Definition of Done
+
+- [ ] All acceptance criteria pass
+- [ ] Email flows tested with real Postmark account
+- [ ] Comment threading tested with 3+ levels
+- [ ] Conflict resolution tested with 2+ concurrent editors
+- [ ] Notification preferences persist across sessions
+- [ ] Digest mode tested with 24-hour window
--- a/docs/milestones/milestone-05-search-ui.md
+++ b/docs/milestones/milestone-05-search-ui.md
@@ -0,0 +1,195 @@
+# Milestone 5: Search & UI Polish
+
+**Duration:** 2 weeks  
+**Goal:** Fast search, design system, responsive layout, and performance optimization
+
+## Tasks
+
+### Week 9: Search Implementation
+
+- [ ] Server-side search index
+  - FTS5 virtual table setup
+  - Index population from documents
+  - Incremental index updates on file changes
+  - Search query endpoint
+  
+- [ ] Client-side search
+  - Flexsearch or Pagefind integration
+  - Index sync from server on load
+  - Incremental index updates via WebSocket
+  - Search UI (input, results, filters)
+  
+- [ ] Search features
+  - Full-text content search
+  - Tag filtering
+  - Title search (boosted)
+  - Recent results caching
+  - Search suggestions (autocomplete)
+
+### Week 10: Design System & Performance
+
+- [ ] Design system
+  - CSS custom properties for theming
+  - Component library (buttons, inputs, cards, navigation)
+  - Typography scale
+  - Color system (light/dark mode)
+  - Spacing scale
+  - `/design` route for browser-based design tool
+  
+- [ ] Responsive layout
+  - Mobile-first CSS
+  - Container queries for components
+  - Navigation adapts to screen size
+  - Touch-friendly targets (min 44px)
+  - Print styles for documents
+  
+- [ ] Performance optimization
+  - Bundle analysis and optimization
+  - Lazy loading for non-critical components
+  - Image optimization (if applicable)
+  - CSS critical path extraction
+  - Service worker for offline caching
+  
+- [ ] Accessibility
+  - ARIA labels on interactive elements
+  - Keyboard navigation
+  - Focus management
+  - Color contrast compliance (WCAG AA)
+  - Screen reader testing
+
+## Acceptance Criteria
+
+### Functional
+- [ ] Search returns results in <50ms after initial sync
+- [ ] Search works offline after first load
+- [ ] Search supports exact phrases (quoted)
+- [ ] Tag filtering narrows search results
+- [ ] `/design` route displays all components with editable CSS
+- [ ] Dark mode toggles correctly (no flash)
+- [ ] All pages responsive down to 320px width
+- [ ] Keyboard navigation works throughout app
+
+### Non-Functional
+- [ ] Lighthouse score >90 on all metrics
+- [ ] Bundle size <100KB gzipped (JS + CSS)
+- [ ] Time to Interactive <200ms
+- [ ] No layout shift during hydration
+- [ ] CSS custom properties work without JS
+
+### Performance Targets
+
+| Metric | Target | Measurement |
+|--------|--------|-------------|
+| Initial Page Load | <100ms | TTFB + FCP |
+| Time to Interactive | <200ms | Hydration complete |
+| Search Query | <50ms | Client-side after sync |
+| Bundle Size | <100KB | Gzipped JS + CSS |
+| Lighthouse Performance | >90 | Chrome DevTools |
+| Accessibility | >90 | Lighthouse a11y |
+
+## Design System Specification
+
+### CSS Custom Properties
+
+```css
+:root {
+  /* Colors */
+  --color-primary: #2563eb;
+  --color-primary-hover: #1d4ed8;
+  --color-text: #1f2937;
+  --color-text-muted: #6b7280;
+  --color-background: #ffffff;
+  --color-surface: #f9fafb;
+  --color-border: #e5e7eb;
+  
+  /* Typography */
+  --font-sans: system-ui, -apple-system, sans-serif;
+  --font-mono: ui-monospace, monospace;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.25rem;
+  
+  /* Spacing */
+  --space-1: 0.25rem;
+  --space-2: 0.5rem;
+  --space-4: 1rem;
+  --space-8: 2rem;
+  
+  /* Shadows */
+  --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
+  --shadow-md: 0 4px 6px rgba(0,0,0,0.1);
+  
+  /* Radii */
+  --radius-sm: 0.25rem;
+  --radius-md: 0.5rem;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-text: #f9fafb;
+    --color-text-muted: #9ca3af;
+    --color-background: #111827;
+    --color-surface: #1f2937;
+    --color-border: #374151;
+  }
+}
+```
+
+### Component Examples
+
+**Button:**
+```html
+<button class="btn btn-primary">Click me</button>
+```
+
+```css
+.btn {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-2) var(--space-4);
+  border-radius: var(--radius-md);
+  font-size: var(--text-base);
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.btn-primary {
+  background: var(--color-primary);
+  color: white;
+  border: none;
+}
+
+.btn-primary:hover {
+  background: var(--color-primary-hover);
+}
+```
+
+## Deliverables
+
+1. Design system documentation
+2. Component showcase at `/design`
+3. Performance audit report
+4. Accessibility audit report
+5. Search API documentation
+
+## Risk Mitigation
+
+| Risk | Mitigation |
+|------|-----------|
+| Bundle size exceeds target | Tree-shaking, code splitting, lazy loading |
+| Search index too large for client | Pagination, server-side fallback, index pruning |
+| Design system inconsistent | CSS custom properties, component tests, design tokens |
+| Mobile layout issues | Test on real devices, container queries, touch targets |
+
+## Definition of Done
+
+- [ ] All acceptance criteria pass
+- [ ] Lighthouse audit green on all metrics
+- [ ] Manual testing on Chrome, Firefox, Safari, Edge
+- [ ] Mobile testing on iOS Safari and Android Chrome
+- [ ] Screen reader tested (VoiceOver, NVDA)
+- [ ] Performance benchmarks documented
+- [ ] Design system reviewed by team
--- a/docs/milestones/milestone-06-production.md
+++ b/docs/milestones/milestone-06-production.md
@@ -0,0 +1,150 @@
+# Milestone 6: Production Hardening
+
+**Duration:** 2 weeks  
+**Goal:** Deploy with confidence through testing, security audit, and operational documentation
+
+## Tasks
+
+### Week 11: Testing & Security
+
+- [ ] Unit tests
+  - Go: >80% coverage for all packages
+  - Preact: Component testing with uvu
+  - Mock external dependencies (email, filesystem)
+  
+- [ ] Integration tests
+  - API endpoint testing
+  - Database operation testing
+  - Auth flow testing
+  - Sync protocol testing
+  
+- [ ] End-to-end tests
+  - User registration and login
+  - Document creation and editing
+  - Comment and notification flow
+  - Conflict resolution
+  - Search functionality
+  
+- [ ] Security audit
+  - Dependency vulnerability scan (govulncheck, npm audit)
+  - OWASP ZAP scan
+  - Manual penetration testing guide
+  - Rate limiting verification
+  - Session security testing
+  - File upload security testing
+
+### Week 12: Operations & Documentation
+
+- [ ] Backup and restore
+  - Automated backup script (database + files)
+  - Point-in-time recovery procedure
+  - Backup encryption (optional)
+  - Restore testing
+  
+- [ ] Monitoring
+  - Health check endpoint (`/health`)
+  - Metrics endpoint (`/metrics`) with Prometheus format
+  - Error tracking and alerting
+  - Log aggregation (structured JSON)
+  
+- [ ] Documentation
+  - Installation guide
+  - Upgrade procedures
+  - Backup/restore procedures
+  - Security incident response guide
+  - Troubleshooting guide
+  - API reference
+  
+- [ ] Load testing
+  - 1000 concurrent readers
+  - 100 concurrent editors
+  - File sync stress test
+  - Search performance under load
+
+## Acceptance Criteria
+
+### Functional
+- [ ] >80% test coverage (Go + TypeScript)
+- [ ] All integration tests pass
+- [ ] All e2e tests pass
+- [ ] Backup script creates restorable archive
+- [ ] Restore procedure tested and documented
+- [ ] Health check verifies: database, filesystem, email connectivity
+
+### Non-Functional
+- [ ] No critical or high-severity vulnerabilities
+- [ ] No medium-severity vulnerabilities without documented mitigations
+- [ ] Rate limiting prevents brute force attacks
+- [ ] File uploads cannot execute code
+- [ ] SQL injection impossible (parameterized queries only)
+- [ ] XSS prevented (auto-escaping, CSP)
+
+### Performance
+- [ ] 1000 concurrent readers: p99 latency <500ms
+- [ ] 100 concurrent editors: no sync conflicts lost
+- [ ] Search performance: p99 <100ms under load
+- [ ] Memory usage stable over 24-hour test (no leaks)
+
+## Security Checklist
+
+### Authentication
+- [ ] Passkey registration works securely
+- [ ] Passkey login validates signature
+- [ ] Password hashing uses Argon2id
+- [ ] Session cookies are signed and HttpOnly
+- [ ] Session expiry is enforced
+- [ ] Rate limiting on auth endpoints
+
+### Authorization
+- [ ] Permission checks on all endpoints
+- [ ] No horizontal privilege escalation
+- [ ] No vertical privilege escalation
+- [ ] Content only served to authorized users
+
+### Input Validation
+- [ ] Markdown sanitized (no raw HTML injection)
+- [ ] File uploads validated (magic numbers, size)
+- [ ] Path traversal prevented
+- [ ] SQL injection impossible
+- [ ] XSS prevented
+
+### Transport
+- [ ] TLS 1.3 enforced
+- [ ] HSTS header present
+- [ ] CSP header restricts scripts
+- [ ] CORS restrictive
+
+### Operational
+- [ ] No secrets in logs
+- [ ] No secrets in environment (config file or encrypted)
+- [ ] Container runs as non-root
+- [ ] Read-only filesystem except /data
+- [ ] Resource limits configured
+
+## Deliverables
+
+1. Test suite (unit, integration, e2e)
+2. Security audit report
+3. Backup/restore scripts
+4. Monitoring dashboard configuration
+5. Operator documentation
+6. Load test results
+
+## Risk Mitigation
+
+| Risk | Mitigation |
+|------|-----------|
+| Security vulnerability found | Patch immediately, assess impact, notify users |
+| Data loss | Automated backups, point-in-time recovery tested |
+| Performance degradation | Monitoring alerts, load testing, scaling plan |
+| Dependency vulnerability | Automated scans, rapid patching process |
+
+## Definition of Done
+
+- [ ] All acceptance criteria pass
+- [ ] Security audit signed off
+- [ ] Load tests meet targets
+- [ ] Documentation complete and reviewed
+- [ ] CI/CD pipeline green
+- [ ] Rollback procedure tested
+- [ ] Team trained on operations procedures