docs: catch the reference docs up to v0.0.32

[antosubash]

Thirteen commits landed since the docs were last swept (admin section, Inertia cache guard, maintenance mode, the i18n gate, git module sources, the default Docker image). Those PRs updated the pages they touched; this covers what they left behind.

Broken links

The admin move relocated every admin view URL and the reference docs largely still pointed at the old ones — /settings/modules, /users/admin, /audit_log/, /feature_flags/, /dashboard/doctor, /permissions/. Retargeted against each module's actual view_prefix / admin_view_prefix. The /api/* paths are a separate contract and did not move, so they are untouched.

Three were wrong in a second way a URL rewrite alone would have preserved:

Doc	Also wrong
several	/settings/modules/<package> names a route that does not exist — /admin/settings/ is one master/detail page, no per-package path
framework-conventions.md	MenuItem example used ui.nav_groups.administration; the vocabulary is access|appearance|content|system, so the example shipped a key with no catalog entry
testing/fixtures.md	posted form data to /users/admin/invite; the endpoint is /api/users/admin/invite and takes JSON

Features with no docs

• middleware.md listed 9 of 14 middlewares. Adds ProxyHeaders, GZip, InertiaCache, Maintenance, CommitBeforeResponse to both order blocks with a section each, and states why the innermost three are ordered as they are.
• lifecycle.md was missing register_admin_routes and register_audit_links, and still showed register_event_handlers' one-arg signature.
• i18n.md gains label_key/group_key, the cross-locale fallback, the ci-check-untranslated gate with its three exemption forms and documented blind spot, and the installed-vs-active type generation split.
• Maintenance mode had no operator docs anywhere. deployment.md now covers what stays reachable, that it fails open, and that it is not a security boundary.
• The CLI reference never listed smpy add / update / module verify / module build.
• pages.md gains AdminLayout, PageShell's section prop, and the topbar / breadcrumb / palette chrome.

Factual corrections

• env-vars.md claimed task_always_eager was "the one field still read from the environment". feat(docker): default app image, standalone by docker run #281 made broker_url and result_backend env-readable too — that is what lets a container boot before any DB row exists.
• i18n.md documented SM_I18N_* as app configuration. Those are read only by the standalone diagnostics runner (python -m simple_module_core); the app takes its locale set from DB-backed HostSettings. Setting them does not change what the app serves.
• Adds SM_TRUSTED_PROXY, previously absent from the reference despite being required behind a TLS-terminating proxy (without it Inertia's pushState throws and login breaks).

Verification

• vitepress build clean — no dead links
• check_readmes.py, check_metadata.py pass
• Every prefix, hook, field and route name in the diff was read out of the source rather than inferred. Two examples I drafted were caught this way and corrected: AuditLink.url_template needs the literal {id} (a {entity_id} template raises at boot), and the registry method is register(), not add().

Docs-only — no code changes.

https://claude.ai/code/session_01JJtbN97VhtDr28Fuy5JKEF

---

Ship pipeline

Ran the full review → verify pipeline on this branch.

Code review (high effort): 0 findings. Fanned out 6 verification agents to fact-check every concrete claim in the diff against source — admin route moves and redirect status codes, middleware install/execution order, lifecycle hook ordering and the register_event_handlers back-compat dispatch, AuditLink boot validation, i18n DB-backed settings and the untranslated-string gate, SM_TRUSTED_PROXY and the Celery env vars, and the frontend layout/chrome claims. ~35 claims, all CONFIRMED with file:line citations. Both new link anchors (#audience, #maintenance-mode) resolve.

Local CI: green.

Gate	Result
make lint (ruff format + ruff + ty + biome + per-workspace tsc + file-size + hardcoded-strings + untranslated-strings + metadata + readmes)	pass
uv run pytest	2152 passed, 2 skipped
npm test	122 passed (20 files)
vitepress build	clean — no dead links

One real defect surfaced by the gate and fixed in 3c2754a: ruff format --check also covers Python fenced blocks inside markdown, and the aligned inline comments in the new MenuItem / ModuleMeta examples used column padding where ruff wants two spaces. Whitespace only.

Browser QA: deliberately skipped. This branch changes 17 markdown files and zero application code, so browser tests would exercise main's behaviour and QA's auto-fix agents would edit unrelated app code onto a docs PR — no signal available about this diff.

---

Follow-up: host settings, env vs DB (64e3d31)

A review flag on middleware.md's Tenant (only if SM_MULTI_TENANT=true) line turned out to be a false positive — that line is correct — but checking it surfaced that the surrounding story was wrong in both directions, including a claim this branch had just introduced.

Settings is HostSettings + BootstrapSettings and inherits the latter's env_prefix="SM_", so every HostSettings field resolves from SM_* at boot. That instance lands on app.state.sm.settings and configures middleware at construction. The DB-hydrated instance is a plain HostSettings on app.state.host.settings, which declares no prefix. Verified by construction rather than by reading:

SM_I18N_DEFAULT_LOCALE=es  ->  Settings().i18n_default_locale == 'es'
SM_MULTI_TENANT=true       ->  Settings().multi_tenant is True
SM_MAINTENANCE_MODE=true   ->  Settings().maintenance_mode is True
                               HostSettings().maintenance_mode is False

• i18n.md claimed SM_I18N_* were read only by the diagnostics runner, and that setting them "does not change what the running app serves". That was false and it was introduced by this branch. They are the app's actual source — LocaleMiddleware, the i18n manifest, the shared-props builder and i18n_deps all read them off app.state.sm.settings. It is editing those rows in the admin UI that does nothing.
• env-vars.md's "Host settings (DB-backed, not env)" section said the same of tenancy and i18n. Replaced with a per-field table naming the env var and which instance each field is read from, because the answer genuinely differs per field.
• The maintenance fields have no working env var. Worth stating because the code's shape suggests otherwise: SM_MAINTENANCE_MODE=true sets the boot object, nothing reads maintenance from there, and the hydrated HostSettings never sees the prefix. It looks plausible and silently does nothing.
• middleware.md claimed X-Tenant-ID is the default tenant header. TenantMiddleware.__init__ takes header: str | None = None and tenant_header defaults to "", so header lookup is off until a name is set.

Gate re-run on the final commit: make lint clean, 2152 passed / 2 skipped, 122 JS passed, vitepress build clean (the new cross-page anchor resolves).

[cloudflare-workers-and-pages]

Deploying simple-module-python with    Cloudflare Pages

Latest commit:	64e3d31
Status:	✅  Deploy successful!
Preview URL:	https://2c1c5a25.simple-module-python.pages.dev
Branch Preview URL:	https://docs-update-latest.simple-module-python.pages.dev

View logs

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.