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.

services/api/routes/health.py

@@ -3,11 +3,11 @@
 The distinction between the first two is the difference between a 30-second blip and a
 fleet-wide outage:
 
-* `/healthz` (liveness) answers "is this process wedged?" A failure here gets the
-  container KILLED. It must therefore touch NOTHING external. Wire it to the DB and a
-  20-second Postgres failover restarts every pod at once; they come back, find the DB
-  still down, and CrashLoopBackOff with exponential restart delays — so the fleet is now
-  down for minutes after the database recovered.
+* `/healthz` (liveness) answers "is this process wedged?" A failure here KILLS the
+  container, so it must touch nothing external. Wired to the DB, a 20-second Postgres
+  failover restarts every pod at once; they come back, find the DB still down, and
+  CrashLoopBackOff with exponential delays — the fleet stays down for minutes after the
+  database recovered.
 * `/readyz` (readiness) answers "should this pod get traffic?" A failure here only removes
   it from the Service endpoints. It is allowed to check dependencies, and it recovers by
   itself the moment the check passes.
@@ -26,10 +26,10 @@ from services.api.models import ErrorBody
 
 router = APIRouter(tags=["ops"])
 
-# No PROMETHEUS_MULTIPROC_DIR here, deliberately: it exists for prefork servers where each
-# worker process holds a slice of the counters. One uvicorn process per container means
-# the default in-process registry is already correct, and multiproc mode would add a
-# shared temp dir, a cleanup obligation, and a class of stale-file bugs for nothing.
+# No PROMETHEUS_MULTIPROC_DIR, deliberately: it exists for prefork servers where each
+# process holds a slice of the counters. One uvicorn process per container makes the
+# in-process registry correct, and multiproc mode would add a shared temp dir, a cleanup
+# obligation, and a class of stale-file bugs for nothing.
 
 
 @router.get("/healthz", status_code=status.HTTP_200_OK)
@@ -45,10 +45,9 @@ async def healthz() -> dict[str, str]:
 async def readyz(pool: PoolDep) -> dict[str, str]:
     """Readiness. Postgres only.
 
-    Postgres-only is the rule, and Redis is the temptation. Redis holds derived state —
-    rate-limit buckets, caches — and everything degrades gracefully without it. Put it in
-    this check and an Upstash hiccup marks every pod unready, Kubernetes empties the
-    Service, and a cache outage becomes a total API outage.
+    Redis is the temptation and stays out: it holds derived state that degrades gracefully,
+    so checking it here would let an Upstash hiccup mark every pod unready, empty the
+    Service, and turn a cache outage into a total API outage.
     """
     try:
         async with pool.connection() as conn, conn.cursor() as cur:
@@ -68,14 +67,13 @@ async def readyz(pool: PoolDep) -> dict[str, str]:
 async def metrics(request: Request) -> Response:
     """The Prometheus scrape endpoint.
 
-    A route rather than `app.mount("/metrics", make_asgi_app())`, for two reasons. A
-    Starlette `Mount` compiles to `^/metrics(?P<path>/.*)$`, which does not match a bare
-    `/metrics` — the exact URL every scrape config uses — and a `Mount` is invisible to
-    OpenAPI, while the deliverable asks for `/metrics` in `openapi.json`.
+    A route rather than `app.mount("/metrics", make_asgi_app())`: a Starlette `Mount`
+    compiles to `^/metrics(?P<path>/.*)$`, which does not match the bare `/metrics` every
+    scrape config uses, and a Mount is invisible to OpenAPI.
 
-    The encoding is still prometheus_client's: `choose_encoder` reads the Accept header and
-    picks the exposition format (Prometheus text vs OpenMetrics) with its matching content
-    type. Hand-rolling either is how you end up serving text/plain that a scraper rejects.
+    The encoding stays prometheus_client's — `choose_encoder` reads Accept and picks the
+    exposition format with its matching content type. Hand-rolling it serves text/plain a
+    scraper rejects.
     """
     encoder, content_type = choose_encoder(request.headers.get("Accept", ""))
     return Response(content=encoder(REGISTRY), media_type=content_type)