pig/docs/build-plan.md

# 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)

Three tracks. F1 and F3 are independent of each other; F2 should follow F3, or
the two should be built together, because the write path needs the permission
model to call into.

| | 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. |
| **F3** | **RBAC.** A real permission model: capability checks (`deal:write`, `commitment:write`, `contract:sign`, `data:import`, `settings:admin`) resolved from team membership and role, enforced in one place, and used to disable the UI control as well as reject the request — so the button and the 403 cannot disagree. | Today authorization stops at "is a member". Eight CRUD tracks and a bulk-import feature are about to land; without this each invents its own check, and import in particular is a bulk write that must not be available to everyone. |
| **F2** | A shared write-path convention in the API: zod schemas derived from the ontology, a mutation helper, consistent error shapes, automatic activity logging, and capability checks from F3 | 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 |

| **A12** | **Capacity tiers.** Add a `government` (sovereign) tier alongside `secure_cloud` and `community_cloud`. A schema change with a migration, plus matching rules: a government requirement must never be satisfied by community capacity, and the tier interacts with the export-control predicate already in `compliance.ts`. | — |
| **A14** | **Import framework.** CSV and Excel first, since both are just tabular: upload, column mapping, a dry-run preview showing what would be created or updated, per-row validation and error reporting, and an idempotent commit keyed on a chosen column. Gated on `data:import`. | F2, F3 |
| **A15** | **Notion import.** Notion databases are tables with typed properties, so this maps onto A14's mapping step rather than being a separate importer. OAuth, database picker, property→field mapping. | A14 |
| **A16** | **Google Sheets import.** Same shape as A15: OAuth, sheet and range picker, then A14's mapping. | A14 |

**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 the richest part of PIG and nothing surfaces it. Build it out fully and plausibly: MSA / DPA / SLA / order form / capacity commitment, the parent-child hierarchy with order-form-beats-MSA precedence, negotiated SLA terms (uptime target, measurement unit and window, remedy type including fee abatement with its trigger duration, credit tiers and cap, claim deadline, credit expiry, spare-pool scope, maintenance classes, reasonable-endeavours carve-out, RCA hours), obligations with renewal alarms, and take-or-pay / prepay / termination-tier fields that make a backlog figure meaningful. Treat the field set as a first draft to be corrected by anyone who negotiates these for a living. | F1, F2 |
| **A11** | Record create/edit sheets for accounts, contacts, demand deals, supply deals | F1, F2 |
| **A13** | **Admin settings.** Platform-admin-only page: Piggy's model (defaulting to a Nemotron model on Prime Intellect inference), the inference endpoint, invite management, team and role administration, Prime Intellect API key, and sync toggles. | F1, F3 |

### 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.

**F3 (RBAC) gates the import work.** Bulk import is the single most dangerous
write in the product — one bad mapping can rewrite thousands of records — so it
must not ship before there is a real answer to who may run it.

**A12 (capacity tiers) is a schema change**, so it is cheaper before the tables
carry real data than after.

---

## Open questions

- **Where is the Prime Intellect API token?** Searched cloud-1's `~/.prime`,
  `~/.config/prime`, `/opt` and `/etc` and found nothing. Needed for A13 (model
  selection against PI inference) and to switch inventory sync on. Scope it to
  `Availability → Read` for sync; model access needs its own key.
- **Which Nemotron model** should Piggy default to, and is it served from PI
  inference or from your own spark-1 box? The adapter should treat the endpoint
  as configuration either way.
- **Who may import?** Suggested default: team leads and platform admins only,
  never a plain member. Easy to loosen, unpleasant to tighten after the fact.