Build the agent-native compute CRM platform

docs/agents.md

@@ -27,6 +27,26 @@ acting for you is a **separate principal** from you: it has its own audit trail
 and can be revoked without disturbing your session, and it can never reach
 further than you can.
 
+## CLI
+
+The `pig` CLI is the HTTP API surface for scripts and Prime Agent kernels. It
+never receives database credentials and has no arbitrary-request, shell, or
+filesystem command. Configure it separately from the MCP process:
+
+```bash
+export PIG_API_URL=https://primeintellectgrowth.com
+export PIG_API_KEY=pig_...
+
+npm run pig -- me
+npm run pig -- --json capacity idle --threshold 0.2
+npm run pig -- --json capacity search --gpu-type H100_80GB --min-gpu-count 8
+```
+
+`--api-url` and `--api-key` override the environment for one invocation. In
+`--json` mode success writes one JSON value to stdout, while failures write one
+JSON error to stderr and exit non-zero. The key is sent only as a bearer token
+and is redacted if an upstream error happens to echo it.
+
 ## The tools
 
 | Tool | What it answers |