Agent guide

This section is the source of truth for autonomous work in the repository. It sits next to How we work under Process: roadmap and task board describe what to build toward 1.0; the pages below describe how the codebase is organised.

If you are an AI agent picking up work, start at Start here and follow its decision tree.

If you are a human contributor onboarding to the project, the same path works — these documents are written for any reader who needs the operating manual rather than user-facing API docs.

Map

• Start here — operating contract, commands, path map, decision tree, anti-patterns, hand-off checklist.
• Conventions — naming, package boundaries, error handling, testing patterns. Companion to /design/principles.
• Agent workflows — informal shapes (feature, bugfix, docs, release) when aligning work in chat.
• Grist plugin API notes — quirks of the underlying grist-plugin-api.js host bridge.
• Library build mode — packages/core is a tsup library, not a Vite app.
• Deploy notes — deploying widgets (GitHub Pages) and the hosted apps (Cloudflare Pages). Not npm publishing — see Releasing below.
• Releasing & publishing — Changesets, staging/rc pre-releases, and the template canary's post-release verification.
• VitePress doc guide — how to edit pages on this docs site.
• shadcn conventions — UI primitives used in the playground.

Topics that do not live here

These are documented canonically under the developer-facing tree; follow the link, don't expect a duplicate inside /files/:

• Demo catalogue (live widgets + paste URLs) → /demos.
• Architecture, monorepo layout, design rationale → /design/principles.
• Replica document JSON shape → /design/replica-document.
• Testing strategy (for SDK consumers) → /guide/testing. Repo-internal testing rules live under Conventions.