Refine product description and roadmap per product-owner review; add lucide-static

README.md

@@ -15,6 +15,34 @@ TypeScript, no build step, Docker-only.** Heavy lifting that *isn't* simple to d
 well — identity, sessions, SSO, OAuth2, permission checks — is delegated to **Ory**
 sidecar services rather than reinvented.
 
+"Simple" here is about the **whole architecture staying simple** — not just at the
+start, but after you've dropped in 240 plugins and run it hard in production. The
+shape doesn't change as it grows: every plugin is the same self-contained folder,
+the hot path is the same I/O-free JWT check, and there's no app database to scale
+or migrate.
+
+## Who this is for
+
+**Experienced developers building back-office, admin, and dashboard products** —
+for their own use or for a client. You know your way around HTTP, Docker, and an
+identity provider, and you'd rather assemble pages from solid building blocks than
+fight a framework or hand-roll auth for the tenth time. Plainpages hands you the
+boring-but-hard parts (auth, authz, menu, design system, plugin host) and stays out
+of the way of your domain logic. It does not try to be a no-code tool or hide its
+moving parts: if "Ory is down ⇒ no logins" (see [Auth](#auth-sessions--permissions-planned))
+reads as an obvious consequence rather than a surprise, you're the audience.
+
+## Project goals
+
+Beyond the priorities above, Plainpages deliberately targets **low-end systems, odd
+hardware, and low-bandwidth environments** — a tablet on a factory floor, an old
+thin client at a reception desk, a remote site on a flaky link. That's *why* the
+baseline is standards-compliant, boring **HTML + CSS** with zero JavaScript: it
+loads fast, degrades gracefully, and works on whatever browser the site already
+has. Where a modern **CSS** feature removes the need to ship JavaScript (theme
+switching, popovers, disclosure), we'll happily use it — the trade we avoid is
+shipping a client-side runtime, not using the platform.
+
 > **Status.** This README describes the target architecture (the project's scope).
 > What exists in the repo today is the **scaffold** — a Node 24 + EJS HTTP server
 > with static serving — plus the **design foundation** in `html-css-foundation/`
@@ -22,6 +50,17 @@ sidecar services rather than reinvented.
 > integration (Kratos/Keto/Hydra + their Postgres) are the roadmap below, not yet
 > implemented. Sections marked _(planned)_ are not built yet.
 
+## The MVP — "clone, one command, hack on a plugin" _(planned)_
+
+The bar for a first usable release: **clone the repo, run one command, and you have
+a working register/login and can start building your own plugin** — no manual key
+generation, no hand-edited Ory config, no separate database setup. One command
+brings up the whole stack (web + Ory + Postgres), generates signing keys and seeds
+an admin on first boot, and drops you at a login screen. From there you copy the
+example plugin folder and you're writing your own page. That moment — clone → one
+command → login → your plugin renders — *is* the MVP. SSO and the OAuth2-provider
+role (Hydra) come after; they aren't required to start.
+
 ## Architecture
 
 Plainpages runs as a small set of containers, orchestrated by Docker Compose:
@@ -43,9 +82,11 @@ acts as an OAuth2 **login & consent provider** for other apps. It reaches the Or
 services over their **REST APIs using Node's built-in `fetch`** — no SDK
 dependency. See [Auth, sessions & permissions](#auth-sessions--permissions-planned).
 
-So the `web` app is **stateless** and its npm footprint stays at a single runtime
-dependency — **`ejs`**. Auth, sessions, SSO, and OAuth2 add *services*, not npm
-packages; data lives upstream (see [Stateless — no application database](#stateless--no-application-database)).
+So the `web` app is **stateless** and its npm footprint stays tiny — a small,
+pinned set of runtime deps (today **`ejs`** for templating and **`lucide-static`**
+for icons), grown only with justification and never a framework. Auth, sessions,
+SSO, and OAuth2 add *services*, not npm packages; data lives upstream (see
+[Stateless — no application database](#stateless--no-application-database)).
 
 ## What's included vs. what you add
 
@@ -163,8 +204,13 @@ the work is extracting it into reusable EJS partials + TS helpers:
 ## Interactivity: zero-JS spine, opt-in enhancement
 
 The core and all building blocks **work with zero JavaScript** — menus, theme
-switching, and filtering are pure CSS + GET forms (server-side). This is the
-robust default for back-office and industrial use.
+switching, and filtering are pure CSS + GET forms (server-side). This is the robust
+default for back-office and industrial use, and on the [low-end, low-bandwidth
+targets](#project-goals) we care about it's usually *faster*: a full round-trip
+that returns a small, already-rendered HTML page beats a client-side runtime that
+must boot, fetch JSON, and re-render before the user sees anything. List state
+(`?q=…&status=…&sort=…&page=…`) lives **in the URL**, so a view is bookmarkable,
+shareable, and reproducible — the URL is the only state the UI keeps.
 
 Plugins that genuinely need it — live dashboards, bulk actions, client-side
 validation — may **opt into progressive enhancement** (htmx, Alpine, or vanilla
@@ -179,8 +225,12 @@ fine-grained, must-be-fresh check.
 ### Login → session JWT (the Kratos session tokenizer)
 
 The themed sign-in / register / reset / SSO screens drive Kratos self-service
-flows. On success, instead of keeping the opaque Kratos cookie and calling
-`whoami` on every request, the app **exchanges the session for a signed JWT once**
+flows. **SSO is entirely optional and self-configuring:** each provider's button
+renders only when its credentials are present, and if no provider is configured the
+SSO section disappears altogether — leaving plain password login. A developer never
+has to touch SSO to get started. On success, instead of keeping the opaque Kratos
+cookie and calling `whoami` on every request, the app **exchanges the session for a
+signed JWT once**
 via the Kratos **session tokenizer** — `whoami` with a `tokenize_as` template — and
 stores that JWT as the session cookie.
 
@@ -203,7 +253,8 @@ stores that JWT as the session cookie.
 (e.g. `role:admin#member@user:alice`); the admin screens write them *only* to Keto.
 But the tokenizer's claims mapper can only read the **identity**, not call Keto — so
 at login the app reads the user's roles from Keto and refreshes a **derived
-projection** onto the identity's `metadata_admin`, which the tokenizer template then
+projection** — a read-only copy of those roles written onto the identity's
+`metadata_admin` so the tokenizer can see them — which the tokenizer template then
 maps into the JWT `roles` claim. That projection is a per-login cache, authoritative
 nowhere; nothing edits it by hand, and a stale one self-heals on the next login.
 
@@ -212,6 +263,23 @@ is cached, so even signature verification hits the network only on key rotation.
 app stays stateless; "stay signed in" = re-mint the JWT on a short TTL, the one
 moment authz is recomputed from Keto.
 
+#### Two trade-offs — both deliberate
+
+This design buys an I/O-free hot path that scales to **tens of thousands of
+concurrent users** on modest hardware. In return:
+
+- **Role changes lag by up to one TTL (~10m).** Because gating reads the JWT, not
+  Keto, a granted or revoked role only takes effect when the token is next minted
+  (re-login or TTL refresh). For an admin tool this is intentional: the alternative
+  is a Keto call on every request, which we explicitly traded away. If a deployment
+  needs instant revoke, the optional revocation denylist (roadmap) closes the gap
+  for the security-critical cases without putting Keto back on the hot path.
+- **Ory is on the critical path for sign-in.** If Kratos is down, no one can log
+  in; if it stays down past the TTL, existing sessions can't refresh and the UI
+  goes dark. This is the direct consequence of being stateless and delegating
+  identity — there is no local fallback, by design. Run Ory with the same
+  availability you'd give any auth provider.
+
 ### Three tiers of "may I?"
 
 ```