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/deploy/database.md

@@ -0,0 +1,77 @@
+---
+title: Database
+summary: Embedded PGlite vs Docker Postgres vs hosted
+---
+
+Paperclip uses PostgreSQL via Drizzle ORM. There are three ways to run the database.
+
+## 1. Embedded PostgreSQL (Default)
+
+Zero config. If you don't set `DATABASE_URL`, the server starts an embedded PostgreSQL instance automatically.
+
+```sh
+pnpm dev
+```
+
+On first start, the server:
+
+1. Creates `~/.paperclip/instances/default/db/` for storage
+2. Ensures the `paperclip` database exists
+3. Runs migrations automatically
+4. Starts serving requests
+
+Data persists across restarts. To reset: `rm -rf ~/.paperclip/instances/default/db`.
+
+The Docker quickstart also uses embedded PostgreSQL by default.
+
+## 2. Local PostgreSQL (Docker)
+
+For a full PostgreSQL server locally:
+
+```sh
+docker compose up -d
+```
+
+This starts PostgreSQL 17 on `localhost:5432`. Set the connection string:
+
+```sh
+cp .env.example .env
+# DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip
+```
+
+Push the schema:
+
+```sh
+DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip \
+  npx drizzle-kit push
+```
+
+## 3. Hosted PostgreSQL (Supabase)
+
+For production, use a hosted provider like [Supabase](https://supabase.com/).
+
+1. Create a project at [database.new](https://database.new)
+2. Copy the connection string from Project Settings > Database
+3. Set `DATABASE_URL` in your `.env`
+
+Use the **direct connection** (port 5432) for migrations and the **pooled connection** (port 6543) for the application.
+
+If using connection pooling, disable prepared statements:
+
+```ts
+// packages/db/src/client.ts
+export function createDb(url: string) {
+  const sql = postgres(url, { prepare: false });
+  return drizzlePg(sql, { schema });
+}
+```
+
+## Switching Between Modes
+
+| `DATABASE_URL` | Mode |
+|----------------|------|
+| Not set | Embedded PostgreSQL |
+| `postgres://...localhost...` | Local Docker PostgreSQL |
+| `postgres://...supabase.com...` | Hosted Supabase |
+
+The Drizzle schema (`packages/db/src/schema/`) is the same regardless of mode.