Build the agent-native compute CRM platform

deploy/README.md

@@ -1,7 +1,8 @@
 # Deploying PIG
 
-PIG is one container plus a Postgres, behind any reverse proxy that terminates
-TLS. Nothing here is specific to a particular host.
+PIG is an API/web container, a private Piggy worker/chat container and Postgres,
+behind any reverse proxy that terminates TLS. Nothing here is specific to a
+particular host.
 
 ## 1. DNS
 
@@ -27,9 +28,17 @@ The values that must be set for a production start:
 | `PIG_PUBLIC_URL` | The single origin the app is served from |
 | `SUPABASE_URL` / `SUPABASE_ANON_KEY` | Authentication. The app refuses to start in production without a Supabase URL, because it would otherwise serve the whole CRM unauthenticated |
 | `PIG_ADMIN_EMAILS` | Who may administer. **Every address here must already have an account** — an unregistered address listed as an admin is a standing offer of admin rights to whoever claims it first |
+| `PIGGY_INFERENCE_API_KEY` | Model credential held only by the Piggy process |
+| `PIGGY_INTERNAL_TOKEN` | A generated 32+ character bearer token shared only by API and Piggy |
 
 Optional: `PRIME_API_KEY` (scope it to `Availability → Read` only),
-`PIGGY_ENABLED` + `ANTHROPIC_API_KEY`, and the Slack and Buzz credentials.
+`PIGGY_ENABLED`, and the Slack and Buzz credentials.
+
+Piggy listens on `piggy:8931` inside the Compose network. The port is exposed to
+other containers but never published to the host, and Caddy must not route to
+it. The CRM API authenticates the user, forwards only bounded chat context, and
+uses `PIGGY_INTERNAL_TOKEN` in an Authorization header. Never put that token in
+a query string, where proxies and access logs can retain it.
 
 ## 3. Start
 
@@ -39,6 +48,12 @@ docker compose -p pig exec app npx tsx packages/db/src/migrate.ts
 docker compose -p pig exec app npx tsx packages/db/src/seed/index.ts   # optional
 ```
 
+When Piggy is enabled, start its private profile as well:
+
+```bash
+docker compose -p pig --profile piggy up -d --build
+```
+
 Use `-p pig`. A compose project that shares a name with a neighbouring stack
 will adopt its volumes, which is a memorable way to lose a database.