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/models.py

@@ -1,9 +1,8 @@
-"""Wire types.
+"""Wire types, deliberately not the domain models.
 
-These are deliberately NOT the domain models. `Instance` carries `team`, `namespace` and
-`release_name` — placement details a tenant has no business seeing and no business
-setting. The response model is the allow-list that keeps them off the wire, which is why
-it is written out by hand instead of derived from `Instance`.
+`Instance` carries `team`, `namespace` and `release_name` — placement details a tenant has
+no business seeing or setting. The response model is the allow-list that keeps them off the
+wire, which is why it is written by hand instead of derived from `Instance`.
 """
 
 from __future__ import annotations
@@ -19,9 +18,8 @@ class CreateInstanceRequest(BaseModel):
     """What a tenant may ask for.
 
     `service_type` and `size` are plain strings, not enums: the catalog is data loaded at
-    runtime, so baking its keys into a type would mean a redeploy to add a service type,
-    and a 422 (schema) where the spec wants a 404 (unknown resource). They are validated
-    against the catalog in the handler.
+    runtime, so baking its keys into a type would mean a redeploy to add a service type and
+    a 422 where the spec wants a 404. The handler validates them against the catalog.
     """
 
     model_config = ConfigDict(