0.1.100 — docs site fixed + Casdoor setup runbook + sample.env refresh

Three docs-only deliverables on top of the auth + sync work that landed in 0.1.90 → 0.1.99. Closes the user-reported "the docs page isn't updating" complaint and gets the published site current with everything that's shipped this session.

docs/SUMMARY.md was 78 entries behind

https://trance-0.github.io/Notechondria/docs/ looked frozen because mdBook only renders pages listed in docs/SUMMARY.md. The tree had drifted: docs/versions/0.1.21.md was the last entry in the table of contents, while files for 0.1.22 → 0.1.99 (78 round logs) plus three new docs/integrations/ pages (github-sync, casdoor-migration, casdoor-setup) lived on disk but were unlinked, so mdBook silently skipped them on every build.

Fixed by regenerating SUMMARY.md programmatically:

  • All 100 version files are now listed in reverse-chronological order, with first-line titles parsed out of each file (or the bare semver as a fallback for the 0.1.0–0.1.15 range that predates the # 0.1.X — title convention).
  • The Integrations block lists github-sync.md, casdoor-migration.md, and the new casdoor-setup.md runbook.

CI: belt-and-braces against silent drift

.github/workflows/frontend-pages.yml:

  • paths: trigger now also fires on changes to VERSION and sample.env. Round logs always touch docs/versions/<semver>.md so they already match docs/**, but a pure version-bump or env-sample commit would otherwise skip the docs leg.
  • The "Build docs (mdBook)" step now set -euo pipefail and asserts docs/build/versions/<deployed-version>.html exists after the build. If SUMMARY.md ever drifts behind docs/versions/ again, CI fails loudly with ::error file=docs/SUMMARY.md::expected ... — SUMMARY.md probably doesn't list ....

Casdoor setup runbook (docs/integrations/casdoor-setup.md)

Step-by-step admin-UI walkthrough for wiring the Notechondria backend to the https://auth.trance-0.com Casdoor instance, with five sections:

  1. Casdoor admin-UI walkthrough — create org, create app, set up the signing certificate, register per-app redirect URIs, optional email + invitation gates.
  2. Notechondria backend env vars — the 6+1 CASDOOR_* env vars + the shadow-mode default behaviour.
  3. Verify — /api/v1/auth/casdoor/config/ smoke, /api/v1/handshake/ version check, frontend SSO + bind smoke.
  4. Failure modes — the seven most common "what went wrong" tabular lookups (redirect_uri mismatch, JWT verification failed, 409 on bind, etc.).
  5. What gets stored where — Creator.casdoor_sub + the relationship to creators.Session until phase-4 cutover.

sample.env refresh

sample.env had been frozen at the 0.1.15 image-tag baseline. This round adds five new env-var blocks corresponding to features shipped 0.1.90 → 0.1.99:

  • Per-app OAuth allow-lists — GOOGLE_AUTHORIZED_REDIRECT_URIS
    • GITHUB_AUTHORIZED_REDIRECT_URIS (since 0.1.90).
  • Casdoor SSO — full CASDOOR_* block + comment pointing at casdoor-setup.md.
  • Backend version + build provenance — BACKEND_VERSION, BACKEND_BUILD_COMMIT, BACKEND_BUILD_TIME, BACKEND_DEPLOY_TARGET (since 0.1.95).
  • GitHub data-sync App — full GITHUB_DATA_SYNC_APP_* block (since 0.1.90, push pipeline live in 0.1.93).

All new fields are empty by default so the existing shadow-mode guards on the backend stay engaged until the operator deliberately flips the switch.

Verification

  • docs/SUMMARY.md head + tail manually inspected; 100 version links + the new Integrations rows present.
  • The new mdBook fail-loud guard in CI was sanity-checked against the local file tree (docs/build/versions/0.1.99.html would have existed had we been able to run mdbook locally — the aarch64 binary isn't published, so this round only smoke- tests via the regen script's correctness; CI on x86_64 will be the real check).
  • sample.env reviewed — all new vars carry inline comments pointing at the round logs that introduced them.

Operator action

When the next deploy lands, hit https://trance-0.github.io/Notechondria/docs/ and confirm the sidebar shows entries up to 0.1.100. If it still stops at 0.1.21, the gh-pages branch's prior docs/ tree is stale and needs keep_files: true swapped to keep_files: false for one publish so the old static files get replaced — only do this if the site is genuinely empty otherwise (the flag is on so editor / planner / portal builds don't tear each other down between workflow runs).

Carryover

  • The conflict-resolution work scoped at the start of this round (push-side fetch-diff-warn for GitHub Sync) was deferred when the docs failure surfaced; queued for next round.
  • Phase 4 cutover + phase 5 cleanup of the Casdoor migration remain open.