docs(postgres): document the PostgreSQL backend and its upstream blockers

[eldonm]

Summary

Documents the PostgreSQL backend — and, more importantly, documents that it does not currently work.

jvspatial ships a complete PostgresDB and jvagent needs no code changes to use it, but JVSPATIAL_DB_TYPE=postgres fails at startup. Nothing in our docs said so: .env.example listed four backends and .planning/reference/jvspatial-integration.md §2.5 listed the same four, so the only way to discover Postgres was unavailable was to try it and read a traceback.

This is docs-only. No jvagent code changes — the fixes belong upstream (CLAUDE.md §4, ADR-0006), and TrueSelph/jvspatial#35 is open with both of them.

Related issues

None filed. Upstream fix: TrueSelph/jvspatial#35.

Type of change

• Bug fix (non-breaking)
• New feature (non-breaking)
• Breaking change
• Documentation
• Chore / tooling / CI

Checklist

• I read CONTRIBUTING.md and (for subsystem work) the local CLAUDE.md.
• pre-commit run --all-files passes.
• pytest tests/ passes — 3218 passed, 0 failures. No tests added: docs-only, no behavior to cover.
• Bug fixes cite file:line in the description. (the upstream defects are cited by file:line in docs/postgres.md §3)
• Docs / CHANGELOG.md updated where relevant — see note below.
• No ADR was modified in place.

Notes for reviewers

No CHANGELOG entry — deliberate, tell me if you disagree. Our changelog records changes to jvagent package behavior; this PR changes none. Happy to add an entry under [Unreleased] if you'd rather every doc addition be listed.

Why "blocked" rather than "supported". The doc leads with the failure and keeps the setup instructions after it. Writing it as a supported backend would have been false, and writing nothing leaves the next person to rediscover it via traceback. When jvspatial#35 merges and ships, §1 (config surface) and §2 (setup) stay as-is and §3 (blockers) becomes a version note.

The two upstream blockers, both reproduced on jvspatial 0.0.9, 0.0.12, and 0.0.15 (our current pin):

1. jvspatial/api/components/database_configurator.py:177 — initialize_graph_context() dispatches through a hard-coded json/mongodb/sqlite/dynamodb chain and raises ValueError: Unsupported database type: postgres. Only the Server path is missing; create_database("postgres", ...) works today.
2. jvspatial/db/postgres.py:353 — _ensure_pool() memoizes the pool and its lock with no event-loop affinity. This one is ours specifically: our CLI bootstraps the graph inside asyncio.run() and then hands off to uvicorn's loop, so the first server-loop query dies with cannot perform operation: another operation is in progress.

Two quieter traps also documented, since both cost real debugging time:

• The DSN reaches the driver through env only. server_config.py:126-164 threads a connection string into DatabaseConfig for mongodb and table/region for dynamodb, but has no Postgres field — so an app.yaml database.uri is silently ignored.
• The log DB silently rewrites any type jvspatial doesn't recognize to a json file log, Postgres included. JVSPATIAL_LOG_DB_TYPE defaults to JVSPATIAL_DB_TYPE, so this fires by default and never warns.

Everything in §4 was verified, not inferred. Against jvspatial#35 with stock jvagent and no patches: bootstrap persists the full graph to Postgres, /health reports PostgresDB, JWT login works off a Postgres-stored user, agent turns run end to end, and conversation state survives a full server restart. Row counts in the doc are measured. A repeatable smoke script exists if you want it in the repo — I left it out to keep this docs-only.

Base branch note. Branched from main, not feat/skill-only-tools, since this is unrelated to that work.