POC: move handbook off VitePress to a headless CMS with reader RBAC + Google Workspace auth

[VibratingKoala]

Requirement

The handbook is a VitePress static site — markdown in doc/, edited only via git/PRs, which excludes non-technical staff and can't restrict who reads a page. We're moving off VitePress. Earlier prototypes were rejected: Wiki.js (no custom frontend, content leaves git) and a git-based CMS (edit access = repo write, all-or-nothing; per-reader access can't be served statically). Per-reader permissioning forces a runtime backend + database anyway, so we'll run a POC of a self-hosted headless CMS behind a custom frontend, delivering:

• a fully custom frontend on the house Astro stack
• on-page editing for non-technical staff (built-in CMS editor, no git/PRs)
• editor vs read-only roles (per-page edit rights as a follow-up)
• per-page reader access: public / internal / group-restricted
• identity via Google Workspace OAuth; reader access driven by Google Groups
• fully runnable locally first (Docker, localhost OAuth)

Scoped as a POC: it proves the server-side enforcement engine with manually-assigned groups. Automatic Google Group → role sync (Admin SDK + domain-wide delegation, needs a Workspace super-admin) is a separate pre-prod spike. Specification and test plan to follow in the linked PR.

Notes

Related Issues

1. osbrjp/handbook — wikijs-prototype branch (rejected: no custom frontend, content leaves git)
2. Idea of OSBR new design #67 — OSBR new design (frontend design input)
3. Supersedes the earlier Keystatic / markdown-in-git direction (a git-based CMS can't do editor RBAC or per-reader access)

[VibratingKoala]

POC delivered — PR #72.

Notable change from this issue's original plan: no headless CMS, no database.
The issue proposed a self-hosted headless CMS + DB. The POC instead uses git-backed markdown content + a git identity config on Astro SSR (Cloudflare Workers) — stateless, no datastore. Rationale: it keeps content in git (versioned, reviewable, portable) while still serving server-side per-page access control (public / internal / restricted via Google Workspace) — which a static host can't do, and which a database was originally assumed necessary for. Identity/role/groups live in a small git config rather than a DB.

Delivered: custom Astro frontend; reader ACL (one fail-closed predicate, forbidden == 404); Google OAuth (+ local dev-login shim); in-browser editor for non-technical staff (save = markdown file + git commit); search; markdown pipeline with sanitize.

Deferred: production editor writes via the GitHub API (+ deploy-on-commit); real Google OAuth client; deploy + DNS cutover from GitHub Pages → Cloudflare Worker. Details and migration steps are in POC.md.

Privacy: the content repo is public, so internal/restricted markdown source is readable in git even though the deployed site gates the rendered page — make the content repo private (no code change) before relying on those tiers.

[VibratingKoala]

Status update — POC feature-complete, reviewed, all findings fixed

Since the last update the POC pivoted to its final architecture (PR #72, description current):

Access = GitHub itself. Sign in with GitHub (no scopes); repo permission → role: collaborator = reader, write = editor, maintain/admin = handbook admin. No allow-list, directory, or email anywhere in the codebase (a CI guard now fails the build if a personal email is ever committed — this repo is public). Roles re-verified every ~10 min; a GitHub-side revoke locks the handbook too. The real OAuth round-trip is verified working locally.

Editing = submit for review. A save commits as the signed-in person (their own GitHub App token — no bot) onto handbook/<slug> and opens one PR per page; main's ruleset (1 approval + run-tests) stays fully in force. Admins get an in-app review dashboard (/edit-pages/reviews) to approve & publish (a real GitHub review + merge as that admin) or reject. GitHub blocks self-approval.

Quality: multi-agent code review of the full PR → 8 verified findings (1 data-loss bug in the edit-branch reset, 1 revocation fail-open on bot-token loss, 6 smaller) → all fixed + regression-tested. 68 unit tests, live ACL matrix verified, all gates green.

Remaining to go live (setup, not code):

1. Org GitHub App created + installed on this repo (org-admin one-click) — enables real per-user commits
2. Cloudflare Worker deploy (staging first) + deploy-on-push
3. DNS cutover from GitHub Pages, then make the repo private so internal/restricted content source isn't publicly readable

Test-locally + production steps are in POC.md and the PR description.

🤖 Generated with Claude Code