docs: add docs/development/build-order.md

content/docs/development/build-order.md

@@ -0,0 +1,77 @@
+# Build Order
+
+The core loop to prove first: **workspace registers -> canvas shows it -> heartbeat keeps it alive -> workspace goes offline -> canvas shows it gray.**
+
+Once that loop works end to end, you have the skeleton of the entire product.
+
+## Step 1: Infrastructure
+
+Write `docker-compose.yml` that starts Postgres, Redis, and Langfuse. Verify all services start cleanly. Write `infra/scripts/nuke.sh` and `infra/scripts/setup.sh`.
+
+## Step 2: Database Migrations
+
+Write the SQL migration files:
+
+1. `001_workspaces.sql` — full workspaces table (includes `parent_id`, heartbeat columns, `forwarded_to` — all core workspace state in one migration)
+2. `002_agents.sql` — agents table
+3. `003_events.sql` — structure_events table + indexes
+4. `004_secrets.sql` — workspace_secrets table
+5. `005_canvas_layouts.sql` — canvas_layouts + canvas_viewport tables
+6. `006_workspace_config_memory.sql` — workspace config and memory key-value tables
+
+See [Database Schema](../architecture/database-schema.md) for the full table definitions.
+
+## Step 3: Platform API Skeleton
+
+Initialize Go module, install `gin`, write `cmd/server/main.go`, set up router with CORS middleware. Connect to Postgres and Redis. Verify the server starts.
+
+## Step 4: Registry Endpoints
+
+Implement `POST /registry/register`, `POST /registry/heartbeat`, and `POST /registry/update-card` in Go. Write Redis TTL logic. Enable Redis keyspace notifications. Subscribe to expiry events and log them.
+
+See [Registry & Heartbeat](../api-protocol/registry-and-heartbeat.md) for the full flow.
+
+## Step 5: Workspace Runtime Layer
+
+Write `main.py`, `config.py`, `heartbeat.py`, `a2a_executor.py`. Create a minimal LangGraph-based workspace that just echoes responses. Wrap it with `a2a-sdk` (`A2AStarletteApplication`) to create the A2A server. Verify:
+
+- Agent Card is served at `/.well-known/agent-card.json`
+- Heartbeat POSTs reach the platform
+
+See [Workspace Runtime](../agent-runtime/workspace-runtime.md) for the file structure.
+
+## Step 6: Canvas Skeleton
+
+Initialize Next.js 15 project with React Flow and Zustand. Create the canvas page with a basic React Flow setup. Create `WorkspaceNode` component that renders a node from an Agent Card. Implement initial hydration (`GET /workspaces` + WebSocket connect). Edges render automatically from `parent_id` hierarchy.
+
+## Step 7: WebSocket Live Updates
+
+Implement WebSocket handler in Go (`handlers/socket.go`). Implement Redis pub/sub broadcaster (`events/broadcast.go`). Implement `useSocket.ts` in the canvas.
+
+Verify: when a workspace registers, the node appears on the canvas in real time. When it goes offline, it turns gray.
+
+## Step 8: First Real Workspace Config
+
+Write `workspace-configs-templates/seo-agent/` with a real `config.yaml`, `system-prompt.md`, and at least one skill. Deploy it as a workspace container.
+
+Verify end-to-end: container starts -> registers -> appears on canvas -> heartbeat -> stays green.
+
+## Step 9: Hierarchy & Communication
+
+Implement `GET /registry/:id/peers` and `POST /registry/check-access` with the `CanCommunicate()` hierarchy check. Implement workspace nesting on the canvas (drag-into to nest). Verify: edges render automatically from parent/child relationships.
+
+See [Communication Rules](../api-protocol/communication-rules.md) for the access model.
+
+## Step 10: Bundle Export/Import
+
+Implement `bundle/exporter.go` to serialize a running workspace into a bundle JSON. Implement `bundle/importer.go` to provision a workspace from a bundle. Add `BundleDropZone` to canvas.
+
+Test round-trip: export -> delete workspace -> import -> workspace reappears.
+
+## Related Docs
+
+- [Architecture](../architecture/architecture.md) — System overview
+- [Platform API](../api-protocol/platform-api.md) — Endpoints to build
+- [Workspace Runtime](../agent-runtime/workspace-runtime.md) — Runtime layer to build
+- [Canvas UI](../frontend/canvas.md) — Frontend to build
+- [Communication Rules](../api-protocol/communication-rules.md) — Hierarchy-based access