fix: fail closed on unusable Codex auth during sandbox auth merge

When reusing a Codex sandbox, the workspace-restore step now performs
an auth-merge check before adopting the sandbox's auth.json. The merge
fails closed when:

- host or sandbox Codex auth is unusable (missing token or account)
- the subscription payload shapes differ between host and sandbox
- subscription account identities do not match

Additional hardening: node absence on PATH during the embedded decision
script now exits non-zero instead of silently falling through. Co-change
comments link parseAuth (the embedded script) to hasUsableAuthPayload
(codex-home.ts) so a future auth-format change cannot silently diverge
between the two implementations.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

docs/api/authentication.md

@@ -0,0 +1,56 @@
+---
+title: Authentication
+summary: API keys, JWTs, and auth modes
+---
+
+Paperclip supports multiple authentication methods depending on the deployment mode and caller type.
+
+## Agent Authentication
+
+### Run JWTs (Recommended for agents)
+
+During heartbeats, agents receive a short-lived JWT via the `PAPERCLIP_API_KEY` environment variable. Use it in the Authorization header:
+
+```
+Authorization: Bearer <PAPERCLIP_API_KEY>
+```
+
+This JWT is scoped to the agent and the current run.
+
+### Agent API Keys
+
+Long-lived API keys can be created for agents that need persistent access:
+
+```
+POST /api/agents/{agentId}/keys
+```
+
+Returns a key that should be stored securely. The key is hashed at rest — you can only see the full value at creation time.
+
+### Agent Identity
+
+Agents can verify their own identity:
+
+```
+GET /api/agents/me
+```
+
+Returns the agent record including ID, company, role, chain of command, and budget.
+
+## Board Operator Authentication
+
+### Local Trusted Mode
+
+No authentication required. All requests are treated as the local board operator.
+
+### Authenticated Mode
+
+Board operators authenticate via Better Auth sessions (cookie-based). The web UI handles login/logout flows automatically.
+
+## Company Scoping
+
+All entities belong to a company. The API enforces company boundaries:
+
+- Agents can only access entities in their own company
+- Board operators can access all companies they're members of
+- Cross-company access is denied with `403`