Add a build plan, informed by reading Comp AI CRM properly

Cloned trycompai/crm (MIT) and inventoried it rather than assuming. Three
findings shaped the plan.

Their component library is far deeper: 68 primitives to our 9, including
data-table, command, sheet, drawer, combobox, chart, and a set of agent-chat
components that map almost exactly onto what Piggy needs.

Their SourcedValue/Provenance pattern is worth adopting outright — a dotted
underline on any agent-derived value with a tooltip carrying the claim, the
reasons, when it was observed and the source URL. PIG already stores all of
that in `facts` and surfaces none of it.

But we are ahead of them on mobile, not behind. Measured across both repos:
211 responsive utilities across their 329 tsx files (0.6 per file) against 58
across our 16 (3.6 per file); zero safe-area handling to our five; no drawer or
sheet used for navigation, no viewport-fit. Their app is effectively
desktop-only. So the plan takes depth from them, not mobile behaviour.

The plan also says not to copy their component files. Most are shadcn/ui
originals — MIT, and designed to be installed from upstream where they are
canonical and current. Borrow the compositions as ideas; the debt is already
credited in NOTICE.

Structured into waves with real dependency edges so the work can be handed to
several agents without collision. Two foundation tasks must land alone first
(the primitive set, and the API write-path convention) because eight parallel
CRUD tracks would otherwise each invent their own.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/build-plan.md

@@ -0,0 +1,129 @@
+# Build plan
+
+Where PIG stands, what remains, and what can be built in parallel.
+
+Written so that work can be handed to several people (or several agents) at
+once without them colliding. The dependency edges are real — the waves are not
+decoration.
+
+---
+
+## What already works
+
+Live at primeintellectgrowth.com. ~10.7k lines, 39 tests, green CI.
+
+- The ontology and margin engine, with the `allocations` join at the centre
+- Both pipelines, capacity availability / matching / idle alerts
+- Auth: sign in, register with an invite code, profile creation, sign out
+- Theming (7 accents, light/dark, server-persisted), responsive to 393px
+- MCP server (9 tools), Prime Intellect API client, demo dataset
+- Docker + compose + Caddy, deploy script, CI on Gitea Actions
+
+## The two gaps that block a demo
+
+1. **No write path for allocations or commitments.** The core table can only be
+   populated by seed. A visitor can look at the demo book but cannot enter a
+   deal of their own.
+2. **No way to mint an API key**, so the MCP server is unreachable in
+   production despite being the headline feature.
+
+Everything else is additive. These two are load-bearing.
+
+---
+
+## On borrowing from Comp AI CRM
+
+Their repo (MIT) was cloned and inventoried. Findings that shaped this plan:
+
+**Their component library is far deeper — 68 primitives to our 9.** Notably
+`data-table`, `command`, `sheet`, `drawer`, `combobox`, `chart`,
+`sortable-list`, and a set of agent-chat components (`message`, `reasoning`,
+`thinking-indicator`, `thread-message`, `suggestion`) that map almost exactly
+onto what Piggy will need.
+
+**`SourcedValue` / `Provenance` is worth adopting outright.** A dotted underline
+on any agent-derived value, with a tooltip carrying the claim, the reasons, when
+it was observed, and the source URL. PIG already has that data — `facts` holds
+score, band, evidence and `sourceUrl` — and nothing currently surfaces it.
+
+**But we are ahead of them on mobile, not behind.** Measured across both repos:
+
+| | Comp AI | PIG |
+|---|---|---|
+| tsx files | 329 | 16 |
+| Responsive utilities | 211 (0.6/file) | 58 (3.6/file) |
+| Safe-area handling | 0 | 5 |
+| Mobile nav | none found | bottom tab bar |
+
+They have no drawer or sheet used for navigation, no `viewport-fit`, and no
+safe-area insets anywhere. Their app is effectively desktop-only. So the plan
+below adds *depth* from them, not mobile behaviour.
+
+**Do not copy their component files.** Most are shadcn/ui originals, which are
+MIT and designed to be installed from upstream — take them from source, where
+they are canonical and current. Borrow their *compositions* (data-table,
+provenance, agent chat) as ideas, and credit in NOTICE as already done.
+
+---
+
+## Waves
+
+### Wave 0 — Foundation (must finish before Wave 1 UI work)
+
+Two tracks, independent of each other, so both can run at once.
+
+| | Task | Why it blocks |
+|---|---|---|
+| **F1** | Install the shadcn primitive set: dialog, sheet, drawer, select, dropdown-menu, table, tabs, tooltip, popover, command, form, switch, textarea, label, separator, sonner, avatar, checkbox, radio-group | Every form and table below needs these. Building them ad hoc in parallel guarantees five inconsistent buttons. |
+| **F2** | A shared write-path convention in the API: zod schemas derived from the ontology, a mutation helper, consistent error shapes, and activity logging on every mutation | Eight CRUD tasks land at once in Wave 1. Without a settled pattern they will each invent one. |
+
+### Wave 1 — Parallel build (up to ~10 tracks)
+
+Backend tracks need only **F2**. Frontend tracks need **F1**.
+
+**Backend**
+
+| | Task | Depends on |
+|---|---|---|
+| **A1** | Allocations + capacity commitments write API, with the availability invariant enforced server-side (cannot allocate beyond the shape) | F2 |
+| **A2** | API keys: generate, list, revoke. Show the plaintext once. | F2 |
+| **A3** | Auth-provider seam — extract Supabase behind an interface so OIDC is a second implementation | — |
+| **A4** | **Piggy**: worker draining `agent_tasks`, `AgentProvider` interface, prime-agent adapter using `defineTool` with PIG tools only (no bash, no filesystem), writing to `facts` | — |
+| **A5** | Slack adapter: link channels to accounts, post stage changes and idle alerts, slash command for capacity match | F2 |
+| **A6** | Buzz adapter behind the same notifier interface as Slack | A5 |
+| **A7** | `pig` CLI with `--json` output, for prime-agent's kernel and for scripts | A2 |
+
+**Frontend**
+
+| | Task | Depends on |
+|---|---|---|
+| **A8** | Data table (sort, filter, paginate, column visibility) + ⌘K command palette | F1 |
+| **A9** | `SourcedValue` / provenance display, wired to `facts`; fact review queue (approve/dismiss proposals) | F1 |
+| **A10** | Contracts UI — the schema is rich and nothing surfaces it | F1 |
+| **A11** | Record create/edit sheets for accounts, contacts, demand deals, supply deals | F1, F2 |
+
+### Wave 2 — Integration (needs Wave 1)
+
+| | Task | Depends on |
+|---|---|---|
+| **B1** | Allocation UI: allocate capacity to a deal from the matcher, place and release holds | A1, A8, A11 |
+| **B2** | Piggy chat UI: streaming, reasoning, tool calls, in-record ask | A4, F1 |
+| **B3** | Settings for Slack/Buzz connections and channel links | A5, A6, F1 |
+| **B4** | End-to-end tests over the critical paths: register → create a commitment → allocate → see margin move | B1 |
+
+---
+
+## Sequencing advice
+
+Build **F1 and F2 first and alone.** They are small and they are the interface
+every other track codes against. Starting Wave 1 before they settle is how
+parallel work turns into merge conflict.
+
+**A1 and A2 are the highest value in Wave 1** — they close the two gaps that
+block a demo. If only two things get done, do those.
+
+**A4 (Piggy) is fully independent** and can start immediately alongside
+Wave 0; it touches no UI and no shared API conventions.
+
+**A3 (auth seam) should land before any second deployment exists.** It is cheap
+now and expensive once an on-prem install has to keep working.