pig/AGENTS.md

Working on PIG

Onboarding for an agent or engineer joining this codebase cold. Read this first, then docs/build-plan.md for what to build.

Named AGENTS.md because that is the file coding agents look for by convention. Everything here applies equally to humans.

---

1. What PIG is, in three sentences

A company that aggregates GPU capacity and resells it runs two pipelines, and its business is the spread between them. Generic CRMs model one pipeline against companies — they have no concept of inventory, no concept of a commitment you already paid for, and so cannot answer the only question that matters: which contracted capacity is sold, to whom, at what margin, and what is idle right now.

PIG is built around that question, it is Apache 2.0, and it is designed to be self-hosted by the customer.

The load-bearing table is allocations, which joins a capacity_commitment (what we bought, at a known cost) to a demand_deal (what we sold, at a known price). Margin, utilisation and idle capacity all fall out of that one join. Everything else is plumbing that exists to keep that ledger honest.

---

2. Orientation

packages/core     Ontology (stages, tiers, enums) + permissions + margin + palette
                  + motion.ts (template kinds, integer qualification scoring)
packages/db       Drizzle schema (51 tables), migrations, seeds
                  schema/motion.ts — the library, engagements and the loop
packages/prime    Typed client for the Prime Intellect compute API
apps/api          Hono HTTP API, auth, capacity/contract/calendar/motion services
apps/web          React + Vite + Tailwind + shadcn-idiom components
apps/piggy        The agent — lease-based queue worker + private chat server
apps/mcp          MCP server (stdio) — 10 tools
apps/cli          `pig`, the HTTP surface for scripts and agent kernels
docs/             ontology.md, motion.md, build-plan.md, agents.md, seed-data.md
deploy/           README.md (deployment), Caddyfile example, autodeploy units

~48,000 lines including tests. 382 tests across five packages (core 78, prime 24, api 212, piggy 63, cli 5), plus a critical-path E2E suite under apps/api/e2e. Node 22+.

Repo	PIG/pig on git.karti.ai (Gitea)
Live	https://primeintellectgrowth.com
CI	Gitea Actions, .gitea/workflows/ci.yml, ~2 min, must stay green
Deploy	Push a release-* tag; CI publishes the image and the host's poller pulls it. A push to main deploys nothing. bash scripts/deploy.sh on the host is the manual path

---

3. Running it

PIG uses pnpm, pinned by the packageManager field. Do not run npm install — it will write a package-lock.json that nothing reads and resolve a dependency tree that neither CI nor the image uses. Corepack ships with Node and installs the pinned version for you:

corepack enable

pnpm install

# Postgres. PIG needs its own database — never point it at a shared one.
docker run -d --name pig-dev -p 5432:5432 \
  -e POSTGRES_USER=pig -e POSTGRES_PASSWORD=pig -e POSTGRES_DB=pig \
  postgres:16-alpine

export DATABASE_URL=postgres://pig:pig@localhost:5432/pig
pnpm run db:migrate
pnpm run db:seed     # sourced, cited people — optional
pnpm run db:demo     # a plausible demo book — optional, prefixed "DEMO — "

pnpm run dev:api     # :8920
pnpm run dev:web     # :5173, proxies /api to 8920

With no SUPABASE_URL set, authentication is disabled in development and every request runs as the first user in the table. loadConfig refuses to start in production without it, so this cannot leak.

Before pushing:

pnpm run typecheck && pnpm test

---

4. Rules that must not be broken

These are load-bearing. Breaking one produces a subtle failure, not an error.

Intelligence never lives in the API. Handlers validate, authorize, call a service, serialise. Research, enrichment, scoring and matching heuristics live in the service layer or in the agent. The API signals the agent by writing a row to agent_tasks, never by calling it — so the queue survives the agent being down and no request thread ever blocks on a model.

There are two auth providers, behind one interface. Supabase for the hosted deployment, OIDC for on-premises — see apps/api/src/lib/auth-provider.ts. Both reduce to "verify a bearer token, return a subject and an email", because that is all PIG needs. Never reach for a provider SDK outside that file.

Authentication is not authorization. A verified JWT proves someone has an account in an identity provider that PIG shares with another application. It does not prove they belong here. Access requires a row in PIG's own users table. A token without one gets 403 needs_profile, which the front end turns into the join flow — never a login screen they have already completed.

Cost is charged against the full commitment, not the hours that sold. Unsold hours are already paid for. Any other treatment reports a healthy margin on a block that is losing money, which is precisely the failure PIG exists to prevent. There is a test pinning this; if you "fix" it, read the test first.

Sold and held are different. A live hold removes capacity from everyone else's availability — otherwise two sellers promise the same GPUs — but it is not revenue and must never count toward utilisation.

Money is integer cents. Never floats. Round, never truncate: 2.43 is 2.4299999 in binary and a lost cent compounds across millions of GPU-hours.

Agent claims carry evidence. Enrichment writes to facts with a score, a band, a source URL and a status — never directly to the record. Only verified self-applies; anything weaker waits for a human. An agent allowed to write unattributed claims will eventually write a wrong one and nobody will be able to tell which.

Never invent data about real people. Seed records carry a confidence grade and a source URL, both shown in the UI. No email address is ever inferred. Authorship is not employment — contributors, residency participants and alumni are recorded as what the evidence shows. Demo data is prefixed DEMO — and its customers are fictional.

---

5. Traps that have already bitten

Each of these cost real time. None produced an error message.

onConflictDoNothing() is a no-op without a matching unique constraint. It has silently duplicated seed data twice. If there is no unique index to conflict on, do an existence check instead.

z.coerce.boolean() turns the string "false" into true. Every feature flag set to false was silently on. Use the envBoolean helper in apps/api/src/lib/config.ts.

Mutations must confirm themselves. <Toaster /> is mounted in App.tsx inside ThemeProvider; use toast.success / toast.error in every mutation's onSuccess / onError. The shadcn Toaster ships wired to next-themes, which PIG does not use — it was rewired to PIG's useTheme. Before that it was never mounted, so toasts already written in RecordSheets fired into nothing and every save completed in silence.

shadcn's accent is a SUBTLE surface, not the brand. shadcn uses bg-accent for hover, focus and selected states — dropdown items, command rows, ghost buttons. The brand is primary. In tailwind.config.js, accent is therefore aliased to --accent-subtle and primary to --accent. Use bg-primary for a solid brand fill; never bg-accent. Mapping them the other way makes every hover state paint a full-strength brand block, which in dark mode with the monochrome palette is a glaring white slab.

Grid and flex children need min-w-0. They default to min-width: auto, meaning they refuse to shrink below their content — and a tabular-nums figure, a whitespace-nowrap badge or a truncate title is all it takes. The page then scrolls sideways on a phone and nothing reports an error. This was fixed three separate times at individual call sites before Card was given min-w-0 on its base class; any new container primitive needs the same. Check with:

document.documentElement.scrollWidth - document.documentElement.clientWidth

It should be 0 on every route at 393px wide.

pnpm needs CI=true in any non-interactive build. When it decides a modules directory is stale it asks before removing it; with no TTY it cannot ask, so it aborts with ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY. This reads like a pnpm bug and is not — it is pnpm refusing to delete files nobody confirmed. Both the Dockerfile and CI set it. The usual trigger is a host node_modules reaching the build context, which is why .dockerignore exists: pnpm's tree is symlinks into a content-addressed store, so copying it into an image yields dangling links and a modules directory pnpm considers corrupt.

tsx is a production dependency, not a dev one. The server runs TypeScript directly — pnpm exec tsx apps/api/src/server.ts is the container's command — so pruning it away breaks the image. It lives in dependencies deliberately; moving it back to devDependencies because "it's a build tool" makes pnpm install --prod produce an image that cannot start.

Drizzle-generated migrations are not always valid SQL. A jsonb → integer cast was emitted without the USING clause Postgres requires. Always apply a new migration to a real empty database before pushing — CI does this, but find out before CI does.

The proxy allows exactly one inline script, by hash. index.html carries a pre-paint theme script that prevents a white flash for dark-mode users. Editing it changes its hash and the browser silently blocks it. CI asserts the hash; if it fails, update the CSP in deploy/Caddyfile.example, on the server, and the expected value in the workflow.

prices.onDemand from the Prime Intellect API is the TOTAL FOR THE NODE. Verified: 1× A100 at 1.79, 2× A100 at 3.58. gpuMemory is likewise a node total. packages/prime/src/map.ts now divides both by gpuCount at the boundary and keeps the node totals in raw for reconciliation — this was a real bug that made an 8-GPU node read eight times too expensive. Anything new that reads an upstream price must normalise the same way.

The SPA fallback must never answer an /api/ path. Without an explicit guard, an unknown API route returns 200 text/html — the app shell — and the caller sees response.ok === true before failing on JSON.parse with "Unexpected token '<'", a long way from the cause. Both the static-file middleware and the SPA fallback in apps/api/src/server.ts carry the guard; anything added after them needs it too.

Prime Intellect has two API hosts. api.primeintellect.ai is compute and pods. Inference is api.pinference.ai/api/v1, OpenAI-compatible.

Piggy's default model thinks aloud. nvidia/nemotron-3-nano-30b-a3b is a hybrid reasoning model; under a tight max_tokens it rambles and truncates. Pass reasoning_effort: "none" for tool use, routing and extraction.

A route file with green tests can still be unmounted. Every route module is a factory returning a Hono app, and createApp has to call it. The tests mount the factory themselves, so they pass whether or not app.ts ever does. read-guards.ts and learn.ts were in exactly that state — which is why read authorisation went unenforced and /learn answered 404 from a page that was in the navigation — and are now mounted. hubspot.ts and hubspot-webhook.ts still are not. After adding a route file, curl the path against a running server; the test suite cannot tell you.

A stale dev server on :8920 makes a mounted route look unmounted. The curl check the entry above recommends is only as good as the process answering it. pnpm run dev:api prints its EADDRINUSE and keeps running under the process manager, so a server started hours earlier from an older checkout goes on answering — and every new route 404s with a perfectly plausible {"error":"Not found"} JSON body. Found this way: five Motion routes that were correctly mounted read as missing for twenty minutes. Check ss -lptn 'sport = :8920' before believing a 404, and read the dev server's log rather than only its port.

The demo seed skips an account it has already seen, and the rows hanging off that account never appear. seedDemo is idempotent per account, so a database carrying a partial demo book from an earlier run silently produces no demand deals — and anything that looks a deal up by name, as seed/demo/motion.ts does, then reports zero and reads exactly like a broken loader. The fix is pnpm db:demo -- --clear and a reseed, not a patch to the lookup.

Deployment traps live in deploy/README.md — chiefly that every Caddy site block on that host needs bind 10.0.0.2, and that the CI runner uses container.network: host so dependencies must be published on 127.0.0.1.

---

6. Conventions

Comments explain why, never what. The code says what it does. Comments carry the reasoning that would otherwise be lost — why this treatment and not the obvious one, what breaks if it changes, what was tried and rejected. Match the density already in the file; do not add narration.

Match the surrounding style. British spelling in prose and comments (utilisation, normalise). Types are explicit at module boundaries. No default exports.

Enums come from @pig/core. Never retype a stage list or a tier into a zod schema — import it, so removing a value stops validating rather than silently persisting.

Tests pin decisions, not implementations. The valuable cases are the ones that would pass under a plausible-but-wrong version. Look at packages/core/test/margin.test.ts for the register.

Commits explain the reasoning, including what was tried and rejected, and say plainly when something was found by running the code rather than reading it. Read git log for the register.

Verify by running, not by assuming. Several of the worst defects here were found only by fetching a URL from another machine or applying a migration to a real database. "It should work" has been wrong repeatedly.

---

7. Where to start

Every task in the original three-wave plan has shipped. docs/build-plan.md is now an audited record of that rather than a queue, and it carries the remaining work at the bottom. The two interfaces everything else codes against — packages/core/src/permissions.ts (the RBAC model) and apps/api/src/lib/mutation.ts (the write path) — are settled; read them before adding any write.

The highest-value work now, in order:

1. Mount createReadGuardRoutes. The read half of the permission model is written, tabulated and tested, and does nothing, because app.ts never mounts it. Until it does, every authenticated member can read supplier cost and margin. It is one line, and it must be registered before the handlers it guards — Hono runs matched handlers in registration order.
2. Mount learn.ts. /learn is in the navigation and its API answers 404.
3. Enqueue the other six agent task kinds. The worker is complete; only enrich_account and enrich_contact are ever written to agent_tasks, so Piggy does far less than the ontology implies.
4. Mount the HubSpot routes, or delete them. Seven tables, OAuth, sync jobs and webhook verification, all written, tested and unreachable.

app.ts is the one shared file. If your change needs a route mounted, a public path allowlisted or a schema widened there, say so rather than racing another agent for it.

---

8. What not to do

• Do not copy component files out of other people's repositories. Where a primitive is a shadcn/ui original, take it from upstream, where it is canonical and current. Compositions we write ourselves.
• Do not open self-registration on the identity provider. It is shared with another application. PIG mints accounts itself, gated on an invite.
• Do not put a production SSH key on the CI runner. Deployment is manual on purpose.
• Do not weaken the production guard that refuses to start without an identity provider.
• Do not seed or infer email addresses for real people.