canvas-drop: Instructions file for Codex

AGENTS.md — canvas-drop

Canonical agent instructions for this repo. CLAUDE.md is a symlink to this file, so Claude Code and Codex read the same contract. Edit this file, never the symlink.

canvas-drop is an open-source (MIT), self-hostable platform where authenticated org members deploy and share small web artifacts ("canvases"). The locked product spec is BUILD_BRIEF.md — it supersedes everything when there's a conflict.

How we work (the loop)

Both agents follow the same compound-engineering loop:

1. Plan — work comes from a plan in docs/plans/. v1 is feature-complete: M1–M9 are all shipped and merged to main — foundation (M1), hosting + deploy (M2), dashboard core (M3), canvas-management depth (M4), the editor + draft/publish version model on content-addressed storage (M5), the five primitives + browser SDK (M6: KV, files, me(), browser SDK), admin + hardening (M7), gallery (M8), and the AI proxy + realtime (M9). Every post-v1 feature is also merged: the canvas sharing access ladder (auth-delegated Add person grants + admin-gated public links), Shared discovery for canvases already opened to the viewer, usage stats, server-side list filters, the docs system (/docs, /llms.txt, /skill.zip), clone-as-template, the primitives showcase, owner-chosen custom slugs, the MCP server (connect-once /mcp, OAuth 2.1, identity-scoped tools, on by default), the staged content-addressed upload (begin→stage→finalize), the signed-out landing page, the per-canvas preview control (auto-screenshot / off / owner-uploaded custom cover that survives publishes), tenancy (P1 org boundary, PR #56; P2 org teams + personal teams + auth-delegated invites, PR #58; access governance), the authoring capability (page-driven create, PR #70) + managed shares (PR #71), admin-flippable design skins, Anthropic prompt caching, per-version ZIP download + delete (PR #74), org-scoped gallery listing (PR #76), bulk archive/unarchive/delete, and the popular sort. The only open milestone is M10 ops/packaging (BUILD_BRIEF §16: Docker image + compose, backup/restore drill, single-VPS load test, IAP pilot). Of M10, the Docker image + compose, vendor-neutral deploy docs, backup/restore (the pnpm backup|restore|purge CLI in apps/server/src/ops/, the docs/ops.md runbook, and an automated round-trip test on both dialects), the security review of the five invariants (docs/security/), README/quickstart, the 3 starter examples, and the secret-scan have shipped; the single-VPS load test and the IAP colleague pilot are still deferred. Also shipped: MCP ↔ user parity (docs/plans/2026-06-17-001-feat-mcp-user-parity-plan.md) — the MCP tool surface (47 tools) is now at full parity with the dashboard owner/editor/viewer surface: anything a user can do in the UI, an agent can do over MCP (settings/sharing via update_canvas, the preview cover via update_canvas previewMode + set_canvas_preview, the access/guest tools, list_shared_canvases, lifecycle, clone_canvas, get_canvas_usage, version export/deletion, and the whole draft-editor loop), each wrapping the same service layer with the same role checks (the agent-native parity rule). Also shipped (2026-09-01): canvas editor roles + ownership transfer (docs/plans/2026-09-01-1909-feat-canvas-editor-roles-plan.md, issue #82, PR #84) — viewer/editor roles on every canvas's people list (people and teams), one role resolver behind every owner gate, owner→editor transfer and admin reassign, per-file stale-save conflicts, owned-or-edited lists, and MCP parity driven by tool-roles.ts; learnings in docs/solutions/2026-09-01-canvas-editor-roles-role-threading-and-transfer-atomicity.md. Also shipped (2026-09-02): the restricted access model (docs/plans/2026-09-02-0830-feat-restricted-access-model-plan.md, issue #86) — the people-and-teams list applies at every rung (HTTP + realtime, one predicate), General access is Restricted / Whole org / Public link, specific_people and team are legacy aliases of private (no migration), team grants are never cleared by a rung change, Shared lists direct and team grants at any rung, and authored-share lists expose every non-deleted lifecycle (draft, published, expired, unpublished, archived, disabled); learnings in docs/solutions/2026-09-02-restricted-access-model-the-list-always-applies.md. Also shipped (2026-09-02): Sharing and permissions UX + viewer clone parity (docs/plans/2026-09-02-1340-feat-share-permissions-ux-clone-parity-plan.md, issue #92) — one direct-access list with People/Teams add tabs, native role controls, a quiet action menu, separate General access and Protection sections, owner-only Advanced transfer, and one clone-eligibility resolver for direct and team viewers. Also shipped (2026-09-12): deployment coordination (docs/plans/2026-09-12-1811-feat-deployment-coordination-plan.md) — an optional opaque releaseId stored on versions (at most one kept ready version per canvas carries a value) and a per-canvas publicationToken rotated by every live-pointer write, accepted as expectedPublicationToken on the ZIP, staged and MCP deploy paths with one atomic conditional activation; already_current success, PUBLICATION_CHANGED / RELEASE_NOT_CURRENT conflicts, no side effects on either; learnings in docs/solutions/2026-09-12-publication-token-and-release-identity.md. Check docs/project-status.md for current status (it is kept in step with the code; BUILD_BRIEF.md §16 is the roadmap, not a status ledger); don't free-style features that aren't in a plan.
2. Issue — each plan/phase has a GitHub issue with the units as a checklist (foundation = #1, C+D = #4, area E = #6, all closed). Tick a unit's box when its PR merges.
3. Branch in your worktree — never work in the shared checkout. Branch name: feat/u<N>-<slug> (e.g. feat/u7-auth-core).
4. Implement one unit at a time, with its test scenarios from the plan. Tests are not optional for feature-bearing units.
5. Capture learnings — run /ce-compound (or write to docs/solutions/) whenever you hit something non-obvious: a gotcha, a decision, a pattern, a workflow fix. This is how knowledge compounds across Claude and Codex.
6. PR per unit — title U<N>: <what> (#1). The CI matrix must be green before merge.
7. Merge small, merge often — see "Compounding" below.