docs: feature-first README, app-level architecture, opt-in auth and tutorial docs #83

Merged
yuuhikaze merged 1 commit from docs/feature-first-readme into master 2026-10-25 04:50:04 -05:00
Owner

Closes #79.

What changed

README.md — feature-first rewrite

  • Leads with what the system does: a "What it does" list covering the canvas editor + text DSL, word running with epsilon-closed traces and TM tape playback, the OPS algebra (determinize, minimize, complement, products, table-filling), regex ⇄ automaton, grammars (CNF, chart parsing, parse trees, PDA ⇄ CFG), multi-tape/nondeterministic PDAs and TMs with search + playback, graphviz/LaTeX rendering, saved documents, the dojo, EN/ES, and the retro CRT look.
  • Intro no longer says "self-hosted on Kubernetes": rgxr is self-hostable by anyone, anonymous by default (USER: anonymous), SSO optional.
  • Architecture mermaid now describes the application, not our deployment: browser (SvelteKit SPA) → rgxr-web (adapter-node, forwards /api) → rgxr-api (axum, stateless) → Postgres (jsonb documents, per-user scoping), with a dotted identity edge: trusted proxy (optional SSO forward-auth) → remote-user headers, else anonymous. Sensei/API-key and graphviz/LaTeX notes sit in prose below the one diagram.
  • Repository layout block compacted (Dockerfile lines dropped; they remain in docs/development.md's build commands). Screens table, Documentation links, Quick start, Docs build and License untouched; image paths unchanged.

docs/reference.md

  • Auth model rewritten to the opt-in contract: identity = remote-user/remote-name/remote-email/remote-groups headers from a trusted proxy when present, otherwise the anonymous user; no more "prod missing header = 401". Sign-in is opt-in from the UI.
  • Documented the new rgxr-web env var AUTH_SIGNIN_PATH (when unset, the UI hides sign-in) in its own row; RGXR_DEV_MODE meaning updated (Vite-origin CORS; anonymous fallback is unconditional now).
  • The OpenBao/ESO/K8s injection chain is now framed as "our production deployment", with a pointer for other deployments.

docs/operations.md — kept as the record of our production deployment (k8s, Authelia, Kargo lanes), explicitly framed as one way to run rgxr, not a dependency; the Auth section notes self-hosters need none of it.

docs/index.md — "self-hostable", anonymous visitors welcome, SSO opt-in.

Tutorials (issue #81, docs slice)

  • README gains a per-section-tutorials bullet (sensei-guided, theory-while-you-use-it, [ SHOW ME ] steps).
  • docs/design.md gets a Tutorials subsection consistent with the retro-terminal language (opt-in lightbulb trigger, amber second accent, sensei dock reusing the dojo Scene, spotlight, stateless) plus a top-bar row in the surface table.
  • docs/development.md notes tutorial content lives in web/src/lib/tutorial/ as typed steps with inline en/es content (dojo lines.ts precedent).

docs-html/ regenerated with tern (2/2 pipelines, 7 files). Links verified: sibling .html links and ../resources/images/ paths are intact — the forge rendering and the tern filter dependencies are untouched.

Deliberately left alone: docs/dojo.md, docs/design.md theme (beyond the tutorials subsection), web//crates//openapi.yaml/resources/images, and the README Screens table.

Closes #79. ## What changed **README.md — feature-first rewrite** - Leads with what the system does: a "What it does" list covering the canvas editor + text DSL, word running with epsilon-closed traces and TM tape playback, the OPS algebra (determinize, minimize, complement, products, table-filling), regex ⇄ automaton, grammars (CNF, chart parsing, parse trees, PDA ⇄ CFG), multi-tape/nondeterministic PDAs and TMs with search + playback, graphviz/LaTeX rendering, saved documents, the dojo, EN/ES, and the retro CRT look. - Intro no longer says "self-hosted on Kubernetes": rgxr is **self-hostable by anyone, anonymous by default (`USER: anonymous`), SSO optional**. - Architecture mermaid now describes the **application**, not our deployment: browser (SvelteKit SPA) → rgxr-web (adapter-node, forwards `/api`) → rgxr-api (axum, stateless) → Postgres (jsonb documents, per-user scoping), with a dotted identity edge: trusted proxy (optional SSO forward-auth) → `remote-user` headers, else anonymous. Sensei/API-key and graphviz/LaTeX notes sit in prose below the one diagram. - Repository layout block compacted (Dockerfile lines dropped; they remain in docs/development.md's build commands). Screens table, Documentation links, Quick start, Docs build and License untouched; image paths unchanged. **docs/reference.md** - Auth model rewritten to the opt-in contract: identity = `remote-user`/`remote-name`/`remote-email`/`remote-groups` headers from a trusted proxy when present, **otherwise the anonymous user**; no more "prod missing header = 401". Sign-in is opt-in from the UI. - Documented the new `rgxr-web` env var **`AUTH_SIGNIN_PATH`** (when unset, the UI hides sign-in) in its own row; `RGXR_DEV_MODE` meaning updated (Vite-origin CORS; anonymous fallback is unconditional now). - The OpenBao/ESO/K8s injection chain is now framed as "our production deployment", with a pointer for other deployments. **docs/operations.md** — kept as the record of **our** production deployment (k8s, Authelia, Kargo lanes), explicitly framed as one way to run rgxr, not a dependency; the Auth section notes self-hosters need none of it. **docs/index.md** — "self-hostable", anonymous visitors welcome, SSO opt-in. **Tutorials (issue #81, docs slice)** - README gains a per-section-tutorials bullet (sensei-guided, theory-while-you-use-it, `[ SHOW ME ]` steps). - docs/design.md gets a Tutorials subsection consistent with the retro-terminal language (opt-in lightbulb trigger, amber second accent, sensei dock reusing the dojo Scene, spotlight, stateless) plus a top-bar row in the surface table. - docs/development.md notes tutorial content lives in `web/src/lib/tutorial/` as typed steps with inline en/es content (dojo `lines.ts` precedent). **docs-html/** regenerated with tern (2/2 pipelines, 7 files). Links verified: sibling `.html` links and `../resources/images/` paths are intact — the forge rendering and the tern filter dependencies are untouched. Deliberately left alone: docs/dojo.md, docs/design.md theme (beyond the tutorials subsection), `web/`/`crates/`/`openapi.yaml`/`resources/images`, and the README Screens table.
docs: feature-first README, app-level architecture, opt-in auth and tutorial docs (#79)
All checks were successful
ci / web (pull_request) Successful in 3m50s
ci / rust (pull_request) Successful in 12m3s
ci / image (oven/bun:1.4.2-debian=docker-image://git.yhkze.net/actions/bun:1.4.2-debian node:22-bookworm-slim=docker-image://git.yhkze.net/actions/node:22-bookworm-slim , web, web.Dockerfile, rgxr-web) (pull_request) Has been skipped
ci / image (rust:1-slim-bookworm=docker-image://git.yhkze.net/actions/rust:1-slim-bookworm debian:bookworm-slim=docker-image://git.yhkze.net/actions/debian:bookworm-slim , ., api.Dockerfile, rgxr-api) (pull_request) Has been skipped
298c316a5d
Co-Authored-By: GLM (OpenCode) <dev@yhkze.net>
yuuhikaze merged commit 2ae082510f into master 2026-10-25 04:50:04 -05:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
k8s-services/rgxr!83
No description provided.