The documentation tree for Instatic. This index tells you what to read, in what order, and where to look for what.
If you're an agent: start at CLAUDE.md (repo root) for the rules, then come here for the explanations.
If you're a human contributor: start with architecture.md, then read whichever feature or reference page is closest to what you're changing.
docs/
├── README.md ← this file (start here)
├── CONVENTIONS.md ← how docs in this repo are written (read before authoring)
│
├── architecture.md ← system overview (start here for orientation)
├── design.md ← visual design system (tokens, surfaces, components)
├── server.md ← server-side deep dive
├── editor.md ← admin + visual editor deep dive
│
├── features/ ← "what X is and how it works" (per-feature)
│ ├── plugin-system.md ← plugin SDK, sandbox, lifecycle, permissions
│ ├── publisher.md ← page tree → static HTML/CSS pipeline
│ ├── visual-components.md ← VCs, slots, params, instantiation
│ ├── content-storage.md ← data_tables + data_rows (the universal store)
│ ├── content-workspace.md ← Content workspace: collections, entries, body editor
│ ├── auth-and-access.md ← sessions, MFA, capabilities, roles
│ ├── site-shell.md ← site config (breakpoints, classes, files, deps)
│ ├── modules.md ← module engine + first-party blocks
│ ├── data-workspace.md ← Data workspace: table schema + field management UI
│ ├── dashboard.md ← Dashboard workspace + widget registry
│ ├── spotlight.md ← Cmd+K command palette
│ ├── agent.md ← AI agent integration
│ ├── templates.md ← entry templates + dynamic bindings
│ ├── loops.md ← base.loop + loop sources
│ ├── cms-native-forms.md ← visual form primitives + data_rows submissions
│ ├── media.md ← Media workspace + storage adapters
│ ├── audit-log.md ← audit_events catalog
│ ├── site-transfer.md ← export / import CMS bundles
│ ├── site-import.md ← Super Import (static sites → CMS)
│ ├── html-import.md ← paste / import HTML into the page tree
│ ├── editor-preferences.md ← catalog-driven editor prefs
│ └── canvas-iframe-per-frame.md ← per-breakpoint iframe rendering
│
├── reference/ ← short cookbook pages for primitives + patterns
│ ├── page-tree.md ← NodeTree<TNode> primitive
│ ├── database-dialects.md ← PG vs SQLite rules
│ ├── typebox-patterns.md ← boundary validation patterns
│ ├── ui-primitives.md ← Button/Input/etc. usage cookbook
│ ├── design-tokens.md ← complete CSS token catalog
│ ├── module-engine.md ← defining a new module
│ ├── canvas-dnd.md ← drag-and-drop patterns
│ ├── admin-router.md ← in-house router usage
│ ├── css-class-registry.md ← user CSS classes + scoped classes
│ ├── capabilities.md ← full capability matrix
│ ├── persistence-keys.md ← localStorage / server prefs catalog
│ ├── error-boundaries.md ← boundary placements + error reporting
│ ├── architecture-tests.md ← catalog of every architecture gate
│ ├── editor-history.md ← patch-based undo/redo history
│ ├── react-compiler.md ← memoization rule, three exceptions, gates
│ └── use-async-resource.md ← canonical async load hook; when to use vs. not
│
├── deployment/ ← operator docs (running the thing)
└── e2e/ ← browser test protocols (agent-run + Playwright automation)
Three categories, three voices:
- Top-level docs are long-lived references that describe the system as it currently is.
- Feature docs describe one first-class capability — its architecture, lifecycle, file layout.
- Reference docs are short, focused cookbooks for primitives and patterns reused across features.
"I want to understand the system"
- architecture.md — the 10-minute orientation. Process layout, layer responsibilities, request lifecycle, publishing pipeline, plugin sandbox, where everything lives.
- design.md — what the editor looks like and why. Tokens, surface system, UI primitives.
- server.md and editor.md — the two deep dives. Pick whichever side you're touching.
"I want to add a feature"
- Skim architecture.md → "Where things live — decision table".
- Read the feature doc closest to what you're adding (e.g. features/plugin-system.md for a plugin SDK extension).
- Read the relevant reference doc(s) for the primitives you'll touch (reference/page-tree.md, reference/database-dialects.md, reference/typebox-patterns.md).
- Make the change. Verify with bun test && bun run build && bun run lint.
"I want to change the visual design"
- design.md — the principles, tokens, surface systems.
- src/styles/globals.css — the actual tokens.
- src/ui/components/ — the actual primitives.
- If you're adding a new token or surface pattern, update design.md in the same change.
"I want to add a new HTTP endpoint"
- server.md → "Adding a new endpoint".
- reference/typebox-patterns.md for body validation.
- reference/database-dialects.md if persistence is involved.
"I want to mutate the page tree"
- reference/page-tree.md — the NodeTree primitive and mutateActiveTree.
- editor.md → "Editor store" for how mutations are wired up.
"I want to write a plugin"
- features/plugin-system.md — the SDK surface, lifecycle, sandbox rules.
- examples/plugins/template/ — working example.
- src/core/plugin-sdk/capabilities.ts — permission catalog (source of truth).
"I want to deploy / operate the CMS"
- README.md (repo root) — install, run, basic commands.
- deployment/README.md — platform and generic deployment targets.
- deployment/backup-restore.md — backing up production data.
| Doc |
What it covers |
| architecture.md |
System overview: process, folders, request lifecycle, data model, validation, decision tables |
| design.md |
Visual design system: principles, tokens, surface systems, UI primitives, forbidden patterns |
| server.md |
Server deep dive: boot sequence, router, handlers, auth, DB adapter, publishing, plugin runtime |
| editor.md |
Admin + editor deep dive: routing, workspaces, editor store, canvas, sidebars, spotlight |
| CONVENTIONS.md |
How docs in this repo are structured and written (read before authoring) |
| Doc |
What it covers |
| features/plugin-system.md |
The plugin system end-to-end: package shape, lifecycle, sandbox, SDK, permissions, CLI |
| features/publisher.md |
The page-tree-to-HTML/CSS renderer + server-side publishing wrappers |
| features/visual-components.md |
VCs, slots, params, instantiation, recursion guard |
| features/content-storage.md |
data_tables + data_rows — the universal content store |
| features/content-workspace.md |
Content workspace UI: collections, entries, body editor, settings panel |
| features/data-workspace.md |
Data workspace UI: DataInspector, field management, DataGrid |
| features/auth-and-access.md |
Sessions, MFA, step-up, lockout, CSRF, capabilities |
| features/site-shell.md |
The persisted site config (breakpoints, classes, files, deps) |
| features/modules.md |
Module engine, defining first-party blocks |
| features/dashboard.md |
Dashboard workspace, widgets, grid, customize mode |
| features/spotlight.md |
Cmd+K command palette |
| features/agent.md |
AI agent integration and provider-agnostic runtime |
| features/mcp-connectors.md |
Instatic as an MCP server — external AI clients drive the CMS over MCP |
| features/templates.md |
Entry templates + dynamic bindings + token interpolation |
| features/loops.md |
base.loop + loop entity sources |
| features/cms-native-forms.md |
Visual form primitives and secure public submissions |
| features/media.md |
Media workspace, upload pipeline, storage adapters |
| features/audit-log.md |
Audit event catalog + recording new actions |
| features/site-transfer.md |
Export / import CMS bundle (JSON round-trip between instances) |
| features/site-import.md |
Super Import — static-site files / ZIP → pages, style rules, media |
| features/html-import.md |
HTML string → PageNode fragment (paste HTML, AI insertHtml tool) |
| features/editor-preferences.md |
Catalog-driven local UI preferences for the editor |
| features/canvas-iframe-per-frame.md |
Per-breakpoint iframe rendering in the visual editor canvas |
| Folder |
Contents |
| deployment/ |
Platform deploys, VPS/Docker installs, TLS, backup, releases |
| e2e/ |
Browser E2E protocols: agent-run audits and Playwright automation docs |
Conventions in one paragraph
Every doc has the shape: one-line scope statement → TL;DR → body sections → Related. Every claim about code anchors to a real file path. Every invariant links to the gate test (in src/__tests__/architecture/) that enforces it. No history, no aspiration, no marketing copy — describe what the system is, not what it could be or what it used to be. If a doc is over ~600 lines, it's doing too much; split it. The full rules are in CONVENTIONS.md.
Quick map from "where do I look for X?" to the canonical file:
| Concept |
Source of truth |
| Agent rules and constraints |
CLAUDE.md (repo root) |
| Design tokens |
src/styles/globals.css |
| UI primitives |
src/ui/components/ |
| Page tree shape |
src/core/page-tree/treeSchema.ts |
| Editor store |
src/admin/pages/site/store/ |
| Server router |
server/router.ts |
| CMS API handlers |
server/handlers/cms/ |
| Repositories |
server/repositories/ |
| DB adapter interface |
server/db/client.ts |
| DB adapters |
server/db/postgres.ts, server/db/sqlite.ts |
| Migrations |
server/db/migrations-pg.ts, server/db/migrations-sqlite.ts |
| Plugin SDK |
src/core/plugin-sdk/ |
| Plugin permission catalog |
src/core/plugin-sdk/capabilities.ts |
| Plugin manifest parser |
src/core/plugins/manifest.ts |
| Plugin worker + sandbox host |
server/plugins/pluginWorker.ts, server/plugins/host/workerPool.ts, server/plugins/quickjs/vm.ts, server/plugins/modulePackVm.ts |
| Publisher |
src/core/publisher/ |
| CSS value sanitiser |
src/core/css-sanitize/sanitiseCssValue.ts |
| TypeBox helpers |
src/core/utils/typeboxHelpers.ts |
| Error message extraction |
src/core/utils/errorMessage.ts |
| Architecture gate tests |
src/__tests__/architecture/*.test.ts |