Reading these docs

These docs are written for two audiences: plan.ai team members and agents implementing the platform. Humans need the strategy and policy in Foundations before the V1 plan makes sense; agents skip Foundations and go straight to the contracts, because the contracts are the only surface agents act on.

For humans

Read in this order:

1. Welcome
2. The thesis
3. V1 overview
4. workbench
5. Roadmap overview

Use the roadmap section for decisions and remaining unknowns. Do not treat retired milestones as current work.

For agents

Read in this order:

1. Agent API quickstart
2. API conventions
3. Metadata
4. Frame submissions
5. Frame submission contract
6. Media ingest
7. Data model
8. Supabase SQL plan

The OpenAPI source lives at /specs/v1-agent-api.openapi.yaml. JSON schemas live under /specs/schemas/.

Configuring Supabase & Cloudflare

Setting up a Supabase project or a Cloudflare Pages/Images/Stream binding for V1? Start at Upstream docs for deep links to the current official pages, then read Secrets & environments for the env matrix and where each secret is bound.

Source of truth

When prose and machine-readable contracts disagree, the implementation must stop and reconcile the docs before shipping. V1 API behavior is specified by the OpenAPI file plus the API Reference pages. For platform behavior (auth flow, RLS, signed URLs, Stream webhooks), the upstream Supabase/Cloudflare pages linked from Upstream docs are the source of truth, and this repo’s pages describe our contract on top of them.