Zus Documentation Index

Project management, architecture, and strategy docs for Zus — a local-first writing, collaboration, and publishing platform.

Quick Reference

Team-facing operational docs that live at the root for easy access.

Document Summary
ROADMAP Linear checklist to MVP
Code Review Standards Review checklist, severity levels, no-tech-debt policy
Troubleshooting Guide Known issues, root causes, and proven fixes
UI Glossary Standard terminology for shell, components, and design tokens
Worktree Workflow Git worktree process for parallel development

Product and Strategy

The foundational "why" and "what" of Zus.

Document Summary Status
MVP Scope What the MVP is and isn't Active
Roadmap Feature timeline and priorities Active
Platform Narrative Core story: documents remember everything, plugins extend everything, AI orchestrates the experience Active
Platform Vision Review Strategic alignment assessment across four foundational pillars Reference
Independent Project Review External architectural audit and recommendations Reference

Business and Marketing

Revenue model, competitive positioning, launch planning, and growth strategy.

Document Summary Status
Business Strategy Unit economics, ARPU analysis, VC positioning, acquisition thesis, revenue projections Active
GTM Strategy Positioning, pricing tiers, competitive landscape, launch channels, web presence, content plan Active
Launch Strategy Release stages (MVP → Preview → EA → 1.0), schedule, exit criteria, data preservation Active
Cost Analysis Cloudflare infrastructure costs by phase, Publisher tier cost drivers, monitoring strategy Active
Pricing Strategy Tier details, competitive pricing, usage-based considerations, conversion strategy Active

Core Architecture Decisions

Decisions that anchor the entire system. Read these first.

Document Summary Status
Architecture Overview Start here — high-level map of all layers and how they connect Active
Markdown-First Pivot THE foundational decision — documents are .md files, not block-UUID structures Done
Local-First Architecture Smart client, dumb storage. Yjs CRDTs for sync and collaboration Active
Plugin Tiers and Architecture Everything with a lifecycle is a plugin. Three tiers: system, core, community Active
AI Agent Architecture The AI agent is intrinsic to the app — full workspace access, command dispatch, agent orchestration via MCP Active
Content Model Document types, block types, and the contract between core and renderers Active

Editor

The editor is the product. Everything else flows through it.

Document Summary Status
Editor Comprehensive Guide Master reference — vision, architecture layers, module summary, integration checklist, decision log Active
Editor Library Spec Module structure, design principles, feature tiers, implementation checklist Active
Slate-to-Core Refactor Why slate moved from web to core, what changed Done
Editor Modes Architecture Tri-state editor modes — Visual, Expert, Read Comprehensive Spec
Theme Presets Integration CSS-only theme system, wiring guide for shell CSS ready, needs shell wiring

Session Guides

Working-boundary docs that live with the code they govern.

Document Summary
Editor Session Guide Boundaries for the editor library session
Theme Session Guide Boundaries for the CSS/theme session

Plugin System

How extensibility works — from command registration to block types to event handling.

Document Summary Status
Plugin System Original plugin architecture — categories, registry, lifecycle Active (being refactored)
Plugin Tiers and Architecture System/core/community tiers, library vs plugin vs runtime layers Active
UI Extension Points Where plugins can inject UI: block actions, toolbar, status bar, slash menu, side panel Active

Shell and UI

Layout, navigation, surfaces, and visual design.

Document Summary Status
ZUI Framework Declarative shell layout framework — SwiftUI-aligned vocabulary, typed builders Design Approved
ZUI Observable System Reactive workspace state — observable proxy, useObservable hook, watch() Active
Data Model & Navigation Graph data model, perspectives, sliding window navigation, in-memory index Design In Progress
Islands Shell Design Islands visual architecture — no global toolbar, zone-owned chrome, hover pills Active
Shell Architecture Shell as system plugin — control bar, side panel, main surface Draft
Shell Foundation Brainstorming Design decisions: command palette, ergonomics, configurability Brainstorming
Ambient UI Patterns Core UX philosophy — interface disappears so the writer can focus Active
Controlbar Layout Top region layout: hamburger, omnibar, gear Active
Perspective Transition Architecture Phase clock, orchestration model, conveyor-belt sidebar animation Active
Routing Architecture Dual-identity URL routing — UUID permalinks and human-readable author paths Design
View State Restoration Session continuity — what Zus remembers and restores across navigation and reload Design Approved
Dashboard Design System Grid-based document browser (Apple Notes inspired) Experimental
Navigator Component Reusable tree navigation component Design Approved
Component Library Catalog of reusable UI components Active
Zus Config Settings User configuration: zus.json in .zus/ directory Consensus

Publishing

How documents get shared and published as browsable sites.

Document Summary Status
Publishing Architecture Two models — shared workspace (live app) and static site generation (portable bundle) Design Spec

Data and Sync

How documents are stored, synced, and collaborated on.

Document Summary Status
Data Model & Navigation Graph as source of truth, providers per source, content loaded on demand Design In Progress
Storage Architecture IndexedDB adapter, Cloudflare D1/R2 backend, pluggable storage interface Active
Yjs + Slate Integration CRDT sync bridge — initialization sequence, invariants, new block types Active
Local-First Architecture Unified sync model: same-device and multi-user Active
Document Sync Architecture Sync protocol, conflict resolution, offline support Active
Search Index Strategy Client-computed search indexes for encrypted documents Active

Design

Visual design system, UX philosophy, and iconography.

Document Summary Status
UX Design Guide North star for Zus UX — Ambient UI, Islands, Cascading Master-Detail, Graceful Transitions, Pristine Aesthetic Active
Iconify Usage Guide How to find, install, and use icons Active
UI Glossary Standard terminology for shell, components, interaction patterns, and design tokens Active

Operations and Infrastructure

Document Summary Status
Cloudflare Deployment Deployment configuration and procedures Active
Deployment Strategy CI/CD, rollbacks, migrations, infrastructure Active
Electron Setup Desktop app build instructions Active
Auth Architecture Authentication providers, session management, Zoom OAuth Active

Research and Analysis

Document Summary Status
CRDT vs OT Analysis Why Yjs (CRDT) over OT for real-time collaboration Done
Auth Provider Evaluation Comparative analysis of authentication providers Done

Bugs, Troubleshooting, and Post-Mortems

Document Summary Status
Troubleshooting Guide Known issues, root causes, and proven fixes Active
BUG-001: Yjs-Slate Path Error Initialization bug that informed the Yjs integration design Resolved

Futures

Ideas and designs for post-1.0 features.

Document Summary Status
Markdown Filesystem Sync Bidirectional sync between Zus and local .md files Future

Mockups

Visual references in specs/mockups/:

File Shows
ambient-ui-{1-4}.png Ambient UI pattern progression
editor_page_edit_mode.png Editor in edit mode
editor_page_ai_sidebar.png AI sidebar panel
editor_page_hover_sidebar_icon.png Hover state on sidebar
editor_page_mouse_move.png Mouse movement ambient response
editor_page_theme_settings.png Theme settings panel
editor_page_theme_settings_mode_hover.png Theme mode hover state
editor_page_theme_settings_font_style_select.png Font style selector
new_editor_page.png New editor page layout
notion-sidebar.png Notion sidebar reference
workspace-sidebar-{collapsed,expanded}.png Workspace sidebar states
card-preview-typography.md Card preview typography spec

Gaps Identified

Docs that don't exist yet but should:

Topic Why it's needed
Markdown Adapter Spec markdown-adapter.ts is a critical subsystem with no dedicated spec
Block Type Registry Spec How block types are defined, registered, rendered
Keymap System Spec Resolver state machine, vim mode, multi-key sequences
Document Versioning Spec Google Docs-style history without git
Collaboration and Presence Spec Multi-user editing, cursor presence, awareness protocol
Asset/Resource Management Spec How images, diagrams, and media are stored alongside markdown
Accessibility Spec Keyboard navigation, screen reader support, ARIA attributes

Directory Structure

pm/
├── README.md              ← You are here
├── ROADMAP.md             ← MVP checklist
├── code-review-standards.md
├── troubleshooting.md
├── ui-glossary.md
├── worktree-workflow.md
├── archive/               ← Superseded designs
├── bugs/                  ← Bug investigations
├── design/                ← UX design guide, iconography
├── dev/                   ← Developer setup guides
├── futures/               ← Post-1.0 ideas
├── marketing/             ← Business strategy, GTM, pricing, launch plan
├── ops/                   ← Deployment and infrastructure
├── product/               ← Vision, scope, roadmap, reviews
├── research/              ← Technical research and analysis
└── specs/                 ← Architecture and design specs
    └── mockups/           ← Visual references

Conventions