Agent guide — start here

Audience: LLM agents working in this repository. Companion doc: How we work

Read this once per session, then use Roadmap and Task board for what to build next. Scope for the current task is agreed in chat with the developer — there is no required /ITERATION.md spec file.

Operating contract

1. Follow the task board. Pick work from Task board; respect milestone order in Roadmap.
2. Public exports only. Use grist-widget-sdk and grist-widget-sdk/emulator entry points — never grist-widget-sdk/src/....
3. Widgets use the SDK. No direct window.grist.* in widget code.
4. Docs ship with behaviour. Public API or contract changes update /guide/, /api/, or /design/ in the same change set.
5. Changelog. User-visible changes get a bullet under CHANGELOG.md → Unreleased.
6. Do not touch .github/workflows/deploy-v0-minimal-demo.yml (separate widgets deploy lane).

Commands

Intent	Command
Install everything	pnpm install
Build the SDK	pnpm --filter grist-widget-sdk build
Test the SDK	pnpm --filter grist-widget-sdk test
Full suite (SDK + docs + playground widgets)	pnpm test
Type-check the SDK	pnpm --filter grist-widget-sdk exec tsc --noEmit
Docs dev / build	pnpm --filter docs dev / pnpm --filter docs build
Playground	pnpm --filter playground dev

Path map

Concept	Path
Roadmap	ROADMAP.md → /roadmap
Task board	TASKS.md → /tasks
How we work	apps/docs/work.md → /work
Changelog	CHANGELOG.md → /changelog
SDK source	packages/core/src/sdk/
SDK tests	packages/core/tests/
Docs	apps/docs/
Playground	apps/playground/

Decision tree

Task type	Read next
What to build next	/tasks, /roadmap
SDK public API	packages/core/src/sdk/index.ts, /design/principles
Testing widgets	/guide/testing, /api/emulator
Repo / deploy	conventions, deploy

Anti-patterns

• Importing from grist-widget-sdk/src/...
• Calling window.grist.* inside widget code
• Shipping public API changes without doc updates
• Skipping CHANGELOG for user-visible changes
• Duplicating /files/* into /guide/ (link instead)

Hand-off checklist

• [ ] pnpm --filter grist-widget-sdk test green
• [ ] tsc --noEmit + build green
• [ ] pnpm --filter docs build when docs changed
• [ ] /TASKS.md updated for finished task ids
• [ ] CHANGELOG.md Unreleased entry if user-visible