docs: add USER_GUIDE.md, tighten comments, fix CLI needing a DSN

The comment pass is prose-only: every distinct "why" is kept, the
narration around it is not. Verified by AST-comparing each changed file
against HEAD with docstrings stripped — only the two files below differ
in executable code.

Two real fixes fell out of the read-through:

* The CLI documented itself as never touching the database, then called
  load_settings(), which requires SVCFORGE_PG_DSN. It refused to start
  without a Postgres URL it never opens. It now has its own two-field
  ClientSettings; the orphaned api_url/api_token are dropped from
  Settings, where nothing else read them.
* repo/db.py had the DictRow alias comment and the ERROR_MAX_CHARS
  comment run together above the wrong symbol.

USER_GUIDE.md is the caller-facing guide the README only gestured at:
auth, catalog, every endpoint with curl, the lifecycle, the error table,
rate limiting, the CLI, client generation, an end-to-end poll loop.

It records two facts about the live deployment rather than documenting a
flow nobody can run. SVCFORGE_JWKS_URL points at a realm with no IdP
behind it, so the API logs "JWKS warm-up failed" at startup and every
/v1 request is a 401. And `helm repo list` in the worker returns no
repositories, so the three bitnamilegacy/ catalog entries cannot resolve
at provision time; only the oci:// entries can.

make lint clean, 76 unit + 111 integration tests pass.

README.md

@@ -80,8 +80,11 @@ uv run python -m scripts.redis_budget            # projects month-end burn, exit
 
 ## Using the API
 
-The API documents itself. FastAPI generates OpenAPI from the same models and routes it
-serves, so the spec cannot drift from the implementation the way a hand-written one does.
+**[USER_GUIDE.md](USER_GUIDE.md)** is the guide for callers: auth, the catalog, every
+endpoint with curl, the lifecycle, the error table, the CLI.
+
+The API also documents itself — FastAPI generates OpenAPI from the same models and routes
+it serves, so the spec cannot drift the way a hand-written one does.
 
 | What | Where |
 |---|---|
@@ -90,24 +93,6 @@ serves, so the spec cannot drift from the implementation the way a hand-written
 | Raw spec, for generating clients | `https://svcforge.oci-oci.duckdns.org/openapi.json` |
 
 Locally, `uv run uvicorn services.api.main:app --factory` then <http://127.0.0.1:8000/docs>.
-
-Three things a caller needs that a schema cannot state on its own, so they are written into
-the spec's description and rendered at the top of `/docs`:
-
-- **Every write is asynchronous.** `POST` and `DELETE` return `202 Accepted` and enqueue
-  work. Poll `GET /v1/instances/{id}` and watch `state`; only `ready` carries an endpoint.
-- **Authorisation is a WHERE clause.** Another team's instance returns `404`, not `403`, so
-  the API never confirms that an id you cannot access exists.
-- **Every non-2xx body is `{"code", "message"}`**, including the 404s and 405s raised by
-  the framework itself, so clients never branch on the body's shape.
-
-Generate a client from the spec rather than hand-rolling one:
-
-```bash
-curl -s https://svcforge.oci-oci.duckdns.org/openapi.json > openapi.json
-# e.g. openapi-generator-cli generate -i openapi.json -g python -o ./client
-```
-
 `tests/integration/test_api.py` pins the description, the tags and the bearer security
 scheme, so the docs fail CI if they rot.