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.
Nguyen Minh Phuc