Instatic Docs

July 3, 2026 · View on GitHub

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.

How to read this tree

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.

Where to look first

"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 index

Top-level

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)

Features

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

Reference

Doc	What it answers
reference/page-tree.md	The `NodeTree<TNode>` primitive — mutations, store routing
reference/database-dialects.md	Postgres vs. SQLite — three rules + cookbook
reference/typebox-patterns.md	Validating every untyped boundary with TypeBox
reference/ui-primitives.md	Full UI primitive catalog with "when to use"
reference/design-tokens.md	Complete CSS custom property catalog
reference/module-engine.md	"How do I define a new module?"
reference/canvas-dnd.md	Drag-and-drop / drop zones / insert location
reference/admin-router.md	In-house router primitives
reference/css-class-registry.md	User-defined CSS classes + scoped classes
reference/capabilities.md	Full capability matrix + how to add one
reference/persistence-keys.md	All localStorage / sessionStorage / server-prefs keys
reference/error-boundaries.md	`<ErrorBoundary>` placements + reporting
reference/architecture-tests.md	Catalog of every architecture gate test
reference/editor-history.md	Patch-based undo/redo history: `HistoryEntry`, `mutate*` helpers, coalescing
reference/react-compiler.md	React Compiler memoization rule, three exceptions, enforcement gates
reference/use-async-resource.md	`useAsyncResource` — canonical single-resource async load hook; when to use and when not to

Operations

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.

Source-of-truth pointers

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`