regstack 0.2.1__tar.gz → 0.2.2__tar.gz

{regstack-0.2.1 → regstack-0.2.2}/CHANGELOG.md

@@ -5,6 +5,16 @@ authoritative copy lives at
 [`docs/changelog.md`](docs/changelog.md) and is rendered into the
 Sphinx docs.
 
+## 0.2.2 — 2026-04-28
+
+Docs-only release. The README and Sphinx docs landing page now lead
+with the same pitch (problem framing, "Why not just use…?" comparison
+vs Auth0 / Clerk / Keycloak / fastapi-users) before diving into
+architecture. Hyperlink density trimmed back: only major external
+packages, products, and JWT (RFC 7519) are linked — Wikipedia trivia,
+MDN basics, OWASP article links, and deep-dependency helper-class
+docs were removed.
+
 ## 0.2.1 — 2026-04-28
 
 Hotfix for 0.2.0: `import regstack` failed on a base install because

{regstack-0.2.1 → regstack-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regstack
-Version: 0.2.1
+Version: 0.2.2
 Summary: Embeddable user registration, login, and account management for FastAPI apps. SQLite / Postgres / MongoDB.
 Project-URL: Homepage, https://github.com/jdrumgoole/regstack
 Project-URL: Repository, https://github.com/jdrumgoole/regstack
@@ -96,17 +96,15 @@ the admin panel, lock out brute-force attackers, and ideally a second
 factor. Every one of those endpoints has a well-known way to get
 subtly wrong:
 
-- **Password hashing.** Use [Argon2](https://en.wikipedia.org/wiki/Argon2)
-  (the [PHC winner](https://www.password-hashing.net/)), not MD5, SHA-1,
-  bcrypt-without-pepper, or — somehow still common — plain text.
+- **Password hashing.** Use Argon2id, not MD5, SHA-1, bcrypt-without-pepper,
+  or — somehow still common — plain text.
 - **Token revocation.** A [JWT](https://datatracker.ietf.org/doc/html/rfc7519)
   is signed and self-contained: the server can't "log it out" unless you
   build a revocation list. Forget this and a stolen token works until it
   expires.
 - **Account enumeration.** A login or password-reset endpoint that
   responds differently for "user exists" vs "user doesn't" lets an
-  attacker harvest your customer list. See
-  [OWASP WSTG-IDNT-04](https://owasp.org/www-project-web-security-testing-guide/v42/4-Web_Application_Security_Testing/03-Identity_Management_Testing/04-Testing_for_Account_Enumeration_and_Guessable_User_Account).
+  attacker harvest your customer list.
 - **Bulk session invalidation.** When a user changes their password
   because they think they were compromised, every existing token they
   hold should stop working immediately. Most homegrown JWT layers don't
@@ -115,9 +113,9 @@ subtly wrong:
   random, hashed at rest, single-use, and expire fast. Storing the raw
   token in the database is a "now your DB backup is also a credential
   dump" mistake.
-- **Phone numbers.** SMS codes need [E.164](https://en.wikipedia.org/wiki/E.164)-validated
-  numbers, attempt limits, and an upstream provider. Wiring all of that
-  yourself for a single feature is rarely worth it.
+- **Phone numbers.** SMS codes need E.164-validated numbers, attempt
+  limits, and an upstream provider. Wiring all of that yourself for a
+  single feature is rarely worth it.
 
 Doing all of these correctly, with tests, is two to four weeks of
 engineering for a competent team. Doing them once and embedding the
@@ -244,9 +242,9 @@ The same docs are also browsable as Markdown in [`docs/`](https://github.com/jdr
 
 Alpha. Single-file SQLite is the default and runs with no infrastructure;
 PostgreSQL and MongoDB backends pass the same parametrized integration
-suite. The next tagged release is `v0.2.0`. See the
+suite. Latest tagged release: `v0.2.1`. See the
 [changelog](https://regstack.readthedocs.io/en/latest/changelog.html)
-for the per-milestone breakdown.
+for the per-release breakdown.
 
 ## Contributing
 

{regstack-0.2.1 → regstack-0.2.2}/README.md

@@ -32,17 +32,15 @@ the admin panel, lock out brute-force attackers, and ideally a second
 factor. Every one of those endpoints has a well-known way to get
 subtly wrong:
 
-- **Password hashing.** Use [Argon2](https://en.wikipedia.org/wiki/Argon2)
-  (the [PHC winner](https://www.password-hashing.net/)), not MD5, SHA-1,
-  bcrypt-without-pepper, or — somehow still common — plain text.
+- **Password hashing.** Use Argon2id, not MD5, SHA-1, bcrypt-without-pepper,
+  or — somehow still common — plain text.
 - **Token revocation.** A [JWT](https://datatracker.ietf.org/doc/html/rfc7519)
   is signed and self-contained: the server can't "log it out" unless you
   build a revocation list. Forget this and a stolen token works until it
   expires.
 - **Account enumeration.** A login or password-reset endpoint that
   responds differently for "user exists" vs "user doesn't" lets an
-  attacker harvest your customer list. See
-  [OWASP WSTG-IDNT-04](https://owasp.org/www-project-web-security-testing-guide/v42/4-Web_Application_Security_Testing/03-Identity_Management_Testing/04-Testing_for_Account_Enumeration_and_Guessable_User_Account).
+  attacker harvest your customer list.
 - **Bulk session invalidation.** When a user changes their password
   because they think they were compromised, every existing token they
   hold should stop working immediately. Most homegrown JWT layers don't
@@ -51,9 +49,9 @@ subtly wrong:
   random, hashed at rest, single-use, and expire fast. Storing the raw
   token in the database is a "now your DB backup is also a credential
   dump" mistake.
-- **Phone numbers.** SMS codes need [E.164](https://en.wikipedia.org/wiki/E.164)-validated
-  numbers, attempt limits, and an upstream provider. Wiring all of that
-  yourself for a single feature is rarely worth it.
+- **Phone numbers.** SMS codes need E.164-validated numbers, attempt
+  limits, and an upstream provider. Wiring all of that yourself for a
+  single feature is rarely worth it.
 
 Doing all of these correctly, with tests, is two to four weeks of
 engineering for a competent team. Doing them once and embedding the
@@ -180,9 +178,9 @@ The same docs are also browsable as Markdown in [`docs/`](https://github.com/jdr
 
 Alpha. Single-file SQLite is the default and runs with no infrastructure;
 PostgreSQL and MongoDB backends pass the same parametrized integration
-suite. The next tagged release is `v0.2.0`. See the
+suite. Latest tagged release: `v0.2.1`. See the
 [changelog](https://regstack.readthedocs.io/en/latest/changelog.html)
-for the per-milestone breakdown.
+for the per-release breakdown.
 
 ## Contributing
 

{regstack-0.2.1 → regstack-0.2.2}/docs/architecture.md

@@ -5,10 +5,11 @@ who wants to embed it, extend it, or contribute to it. If you only
 want to use it, [Quickstart](quickstart.md) is shorter.
 
 regstack is a single embeddable façade — `RegStack` — that wires
-together storage, password and JWT primitives, an email service, an
-SMS service, a [hooks bus](#hooks), and a [FastAPI](https://fastapi.tiangolo.com/)
-router. Hosts construct one façade per application and mount its
-router(s) wherever they like.
+together storage, password and [JWT](https://datatracker.ietf.org/doc/html/rfc7519)
+primitives, an email service, an SMS service, a [hooks bus](#hooks),
+and a [FastAPI](https://fastapi.tiangolo.com/) router. Hosts
+construct one façade per application and mount its router(s) wherever
+they like.
 
 ```text
 ┌────────────────────────────────────────────────┐
@@ -36,10 +37,9 @@ router(s) wherever they like.
    └────────┘  └──────────┘  └──────────┘
 ```
 
-The pattern is the
-[façade pattern](https://en.wikipedia.org/wiki/Facade_pattern): one
-object that owns and exposes a coherent set of related sub-systems,
-so the host has a single import to learn.
+The pattern is the façade pattern: one object that owns and exposes
+a coherent set of related sub-systems, so the host has a single
+import to learn.
 
 ## One façade per process
 
@@ -48,8 +48,7 @@ sms_service=…, mail_composer=…)` is the only public constructor.
 Everything downstream (routers, dependencies, repos) takes its
 dependencies from this instance, so you can run **two regstack
 instances in the same process** without shared state — useful for
-[multi-tenant](https://en.wikipedia.org/wiki/Multitenancy) deployments
-where a single FastAPI app serves multiple
+multi-tenant deployments where a single FastAPI app serves multiple
 `<host, database, branding>` triples.
 
 The backend is auto-built from `config.database_url` if not supplied
@@ -64,9 +63,7 @@ The façade exposes:
 - `router` — the JSON `APIRouter` to mount under `config.api_prefix`.
 - `ui_router` — the SSR `APIRouter` (built on first access; only
   meaningful when `enable_ui_router=True`).
-- `static_files` — Starlette
-  [`StaticFiles`](https://www.starlette.io/staticfiles/) over the
-  bundled CSS/JS.
+- `static_files` — Starlette `StaticFiles` over the bundled CSS/JS.
 - `deps` — `AuthDependencies` factory for `current_user` /
   `current_admin` (each call returns a closure-bound dep).
 - `users`, `pending`, `blacklist`, `attempts`, `mfa_codes` — repos.
@@ -75,7 +72,7 @@ The façade exposes:
 - `backend` — the active `regstack.backends.base.Backend`.
 - `install_schema()` — install indexes (Mongo) or run
   [Alembic](https://alembic.sqlalchemy.org/) migrations (SQL).
-  `install_indexes()` is kept as a backwards-compat alias.
+  `install_indexes()` is kept as a back-compat alias.
 - `aclose()` — tear down the backend's connection pool.
 - `bootstrap_admin(email, password)`,
   `add_template_dir(path)`, `set_email_backend(...)`,
@@ -85,9 +82,8 @@ The façade exposes:
 
 The Backend ABC owns the persistence story. Each backend ships:
 
-- One concrete repository per
-  [Protocol](https://docs.python.org/3/library/typing.html#typing.Protocol):
-  `UserRepoProtocol`, `PendingRepoProtocol`, `BlacklistRepoProtocol`,
+- One concrete repository per Protocol: `UserRepoProtocol`,
+  `PendingRepoProtocol`, `BlacklistRepoProtocol`,
   `LoginAttemptRepoProtocol`, `MfaCodeRepoProtocol`.
 - `install_schema()` to create indexes (Mongo) or run table creation /
   Alembic migrations (SQL).
@@ -95,16 +91,15 @@ The Backend ABC owns the persistence story. Each backend ships:
 - `aclose()` for clean shutdown.
 
 The Mongo backend lives at `regstack.backends.mongo`; the SQL backend
-(driving both SQLite and Postgres via [SQLAlchemy 2 async](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html))
-lives at `regstack.backends.sql`. Both are routed via the
+(driving both SQLite and Postgres via [SQLAlchemy](https://www.sqlalchemy.org/)
+async) lives at `regstack.backends.sql`. Both are routed via the
 `regstack.backends.factory.build_backend(config)` factory.
 
 ### TTL handling differences
 
-Mongo gets free expiry via [TTL indexes](https://www.mongodb.com/docs/manual/core/index-ttl/) —
-`pending_registrations`, `token_blacklist`, `login_attempts`, and
-`mfa_codes` all have `expireAfterSeconds` indexes that the Mongo
-background task reaps.
+Mongo gets free expiry via TTL indexes — `pending_registrations`,
+`token_blacklist`, `login_attempts`, and `mfa_codes` all have
+`expireAfterSeconds` indexes that the Mongo background task reaps.
 
 The SQL backends have no equivalent. Two safety nets:
 
@@ -112,22 +107,21 @@ The SQL backends have no equivalent. Two safety nets:
   checks `expires_at > now()` (or equivalent). A stale row in the
   table is harmless because it's never returned.
 - **Periodic reaper**: each repo exposes `purge_expired(...)`. Hosts
-  that care about disk usage can run it on a schedule (e.g. via
-  [APScheduler](https://apscheduler.readthedocs.io/) or a
-  `regstack reap` cron job).
+  that care about disk usage can run it on a schedule (e.g. a cron
+  job calling a small `regstack reap` script).
 
 This means SQL backends are functionally correct without the reaper,
 but accumulate dead rows over time. Mongo doesn't.
 
 ## Repositories
 
-Each backend ships a thin async repo per collection / table. The Mongo
-repos are tz-aware because `make_client` configures
+Each backend ships a thin async repo per collection / table. The
+Mongo repos are tz-aware because `make_client` configures
 `AsyncMongoClient(..., tz_aware=True)`; the SQL repos use a custom
-`UtcDateTime` [TypeDecorator](https://docs.sqlalchemy.org/en/20/core/custom_types.html#sqlalchemy.types.TypeDecorator)
-that stores UTC and re-attaches the UTC tzinfo on read. Every layer
-above the repo assumes UTC-aware datetimes — there is no naive
-datetime anywhere in the public API.
+`UtcDateTime` SQLAlchemy `TypeDecorator` that stores UTC and
+re-attaches the UTC tzinfo on read. Every layer above the repo
+assumes UTC-aware datetimes — there is no naive datetime anywhere in
+the public API.
 
 `UserRepo` accepts an injected `Clock`; bulk-revoke writes
 (`update_password`, `update_email`, `set_tokens_invalidated_after`)
@@ -179,20 +173,18 @@ one mechanism:
 - `build_ui_environment` — SSR HTML templates under
   `regstack/ui/templates/`.
 
-Both wrap a
-[`ChoiceLoader([host_dirs..., regstack_default])`](https://jinja.palletsprojects.com/en/stable/api/#jinja2.ChoiceLoader)
-so a host override drops a same-named file into its template
-directory and wins over the bundled version.
-`RegStack.add_template_dir(path)` feeds both loaders simultaneously.
+Both wrap a `ChoiceLoader([host_dirs..., regstack_default])` so a
+host override drops a same-named file into its template directory and
+wins over the bundled version. `RegStack.add_template_dir(path)`
+feeds both loaders simultaneously.
 
 ## CLI runtime
 
 `regstack init`, `regstack create-admin`, and `regstack doctor` share
-`cli/_runtime.py`. `open_regstack(toml_path=None)` is an
-[async context manager](https://docs.python.org/3/library/contextlib.html#contextlib.asynccontextmanager)
-that builds a real RegStack against a real backend, runs
-`install_schema()`, and tears the connection down on exit — the right
-pattern for a short-lived CLI invocation.
+`cli/_runtime.py`. `open_regstack(toml_path=None)` is an async
+context manager that builds a real RegStack against a real backend,
+runs `install_schema()`, and tears the connection down on exit — the
+right pattern for a short-lived CLI invocation.
 
 ## Testing seams
 
@@ -206,5 +198,4 @@ pattern for a short-lived CLI invocation.
   test build multiple `RegStack` instances against per-worker DBs to
   exercise different config combinations without leaking. The
   parametrized `backend_kind` fixture runs every integration test
-  against every active backend in parallel via
-  [`pytest-xdist`](https://pytest-xdist.readthedocs.io/).
+  against every active backend in parallel via pytest-xdist.

{regstack-0.2.1 → regstack-0.2.2}/docs/changelog.md

@@ -3,6 +3,31 @@
 All notable changes to this project are documented here. Versions follow
 [Semantic Versioning](https://semver.org/) once `1.0.0` ships.
 
+## 0.2.2 — 2026-04-28
+
+**Docs-only release.**
+
+### Changed
+
+- README and `docs/index.md` both now lead with the same pitch — a
+  tagline ("Production-grade user accounts for your FastAPI app —
+  without the vendor lock-in, the second service to run, or the
+  homegrown auth bugs"), a "The problem regstack solves" section
+  (Argon2, JWT revocation, account enumeration, bulk session
+  invalidation, hashed one-time tokens, E.164 phone numbers), and a
+  "Why not just use…?" comparison table covering hosted SaaS
+  (Auth0 / Clerk / WorkOS / Stytch), self-hosted IAM (Keycloak /
+  Authentik / Authelia / Ory Kratos), `fastapi-users`, and DIY.
+- Trimmed hyperlink density back. Only major external packages,
+  products, and JWT (RFC 7519) are linked. Wikipedia articles on
+  CS concepts (façade pattern, multitenancy, idempotence, E.164,
+  SHA-256, HMAC), MDN web platform basics (CSP, fetch, localStorage,
+  HTTP 429, Retry-After, HTTPS, CSS custom properties), OWASP article
+  links, Python stdlib pages, and deep-dependency helper-class docs
+  (pwdlib, pydantic, asyncpg, pymongo, ChoiceLoader, TypeDecorator,
+  StaticFiles, ProxyHeadersMiddleware, slowapi, APScheduler,
+  pytest-xdist, Kubernetes probes) were removed.
+
 ## 0.2.1 — 2026-04-28
 
 **Hotfix for 0.2.0.** `import regstack` was broken on any install that

{regstack-0.2.1 → regstack-0.2.2}/docs/embedding.md

@@ -110,9 +110,8 @@ regstack.add_template_dir(Path("/app/host/templates"))
 ```
 
 Drop a same-named file into your directory to win against the bundled
-default — regstack uses Jinja2's
-[`ChoiceLoader`](https://jinja.palletsprojects.com/en/stable/api/#jinja2.ChoiceLoader)
-so the host directory is searched first. Examples:
+default — regstack uses Jinja2's `ChoiceLoader` so the host directory
+is searched first. Examples:
 
 - `auth/login.html` — replaces the SSR sign-in page.
 - `verification.html` / `verification.txt` /
@@ -125,8 +124,8 @@ A list of every overridable file lives in
 ## Switching the SSR theme without templates
 
 If you only want to flip colors / fonts, you don't need to override
-any templates — just supply a CSS file that overrides the
-[CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*):
+any templates — just supply a CSS file that overrides the bundled
+CSS custom properties:
 
 ```toml
 # regstack.toml
@@ -171,8 +170,8 @@ In code:
 await regstack.bootstrap_admin("admin@example.com", "long-strong-password")
 ```
 
-This is [idempotent](https://en.wikipedia.org/wiki/Idempotence) —
-promotes an existing user, creates one if not present.
+This is idempotent — promotes an existing user, creates one if not
+present.
 
 ## Health-check and probes
 
@@ -183,16 +182,14 @@ uv run regstack doctor [--config ...] [--check-dns] [--send-test-email <addr>]
 `doctor` reports JWT secret strength, database reachability, indexes,
 the email backend's instantiability, and optionally DNS (SPF/DKIM/MX)
 and a real email send. Exit code is the number of failed checks —
-wire it into a container health check or a
-[Kubernetes liveness probe](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)
+wire it into a container health check or a Kubernetes liveness probe
 for production probes that need more than a TCP hit.
 
 ## What regstack does *not* do
 
-- It does not mount a [CSRF](https://owasp.org/www-community/attacks/csrf)
-  middleware. The bundled SSR pages don't use cookies, so they don't
-  need it; if you swap the bundled JS for a cookie-based variant,
-  configure CSRF at the host.
+- It does not mount a CSRF middleware. The bundled SSR pages don't
+  use cookies, so they don't need it; if you swap the bundled JS for
+  a cookie-based variant, configure CSRF at the host.
 - It does not enforce HTTPS. Run behind a TLS terminator.
 - It does not provision SES identities, Route 53 records, IAM users,
   or anything else outside the database.

regstack-0.2.2/docs/index.md

@@ -0,0 +1,141 @@
+# regstack
+
+**Production-grade user accounts for your [FastAPI](https://fastapi.tiangolo.com/)
+app — without the vendor lock-in, the second service to run, or the
+homegrown auth bugs.**
+
+`pip install regstack`, point it at SQLite (default),
+[PostgreSQL](https://www.postgresql.org/), or
+[MongoDB](https://www.mongodb.com/), and you have register / login /
+verify-email / reset-password / change-email / delete-account /
+optional SMS two-factor / admin endpoints / themeable HTML pages —
+all behind a small Python API and one config file.
+
+## The problem regstack solves
+
+Every web application that has users eventually needs the same dozen
+endpoints: register, log in, log out, verify email, reset a forgotten
+password, change password, change email, delete account, list users
+for the admin panel, lock out brute-force attackers, and ideally a
+second factor. Every one of those endpoints has a well-known way to
+get subtly wrong:
+
+- **Password hashing.** Use Argon2id, not MD5, SHA-1,
+  bcrypt-without-pepper, or — somehow still common — plain text.
+- **Token revocation.** A [JWT](https://datatracker.ietf.org/doc/html/rfc7519)
+  is signed and self-contained: the server can't "log it out" unless
+  you build a revocation list. Forget this and a stolen token works
+  until it expires.
+- **Account enumeration.** A login or password-reset endpoint that
+  responds differently for "user exists" vs "user doesn't" lets an
+  attacker harvest your customer list.
+- **Bulk session invalidation.** When a user changes their password
+  because they think they were compromised, every existing token they
+  hold should stop working immediately. Most homegrown JWT layers
+  don't do this.
+- **One-time tokens.** Verification and password-reset tokens should
+  be random, hashed at rest, single-use, and expire fast. Storing the
+  raw token in the database is a "now your DB backup is also a
+  credential dump" mistake.
+- **Phone numbers.** SMS codes need E.164-validated numbers, attempt
+  limits, and an upstream provider. Wiring all of that yourself for a
+  single feature is rarely worth it.
+
+Doing all of these correctly, with tests, is two to four weeks of
+engineering for a competent team. Doing them once and embedding the
+result everywhere is what regstack is for.
+
+## Why not just use…?
+
+There are real alternatives. Here's why regstack might still be the
+right call.
+
+| Alternative | Why you might pick it | Why you might pick regstack instead |
+|---|---|---|
+| **[Auth0](https://auth0.com/) / [Clerk](https://clerk.com/) / [WorkOS](https://workos.com/) / [Stytch](https://stytch.com/)** (hosted SaaS) | Zero ops. Polished UI. Enterprise SSO out of the box. | Cost scales per-user. Your auth lives on someone else's servers. Your customer list is in their database. Vendor lock-in is real and migrations are painful. |
+| **[Keycloak](https://www.keycloak.org/) / [Authentik](https://goauthentik.io/) / [Authelia](https://www.authelia.com/) / [Ory Kratos](https://www.ory.sh/kratos/)** (self-hosted IAM) | Full identity platform. SAML, OIDC, federation. | A separate Java/Go service to run, monitor, back up, upgrade, and reason about. Heavyweight for "let users sign up". Schema lives outside your app. |
+| **[fastapi-users](https://fastapi-users.github.io/fastapi-users/)** | Same language, same framework. Good registration / login primitives. | Doesn't ship verification flows, anti-enumeration, bulk revoke, SMS MFA, admin endpoints, or themeable pages — you build those. regstack is the longer tail. |
+| **Roll your own** | Total control. No dependency to learn. | You re-solve every bullet from "The problem" above, including the ones you didn't know existed yet. Two to four engineering weeks, then forever to maintain. |
+
+regstack's bet is that for most FastAPI apps the right answer is
+**embed a small Python library that owns the boring 80% correctly,
+and keep the user table in your own database** — not "stand up a
+separate auth product" and not "write the boring 80% from scratch
+each time".
+
+## What's in the box
+
+- **Three storage backends, one API.** SQLite (the default — single
+  file, no server), Postgres (via asyncpg), MongoDB (via pymongo).
+  Same routers, same hooks; switch by changing the `database_url`.
+- **JSON API.** Register, verify email, resend verification, log in
+  (with optional SMS second step), log out, `me`, change password,
+  change email + confirm, forgot/reset password, delete account,
+  admin endpoints.
+- **Server-rendered HTML pages** (opt-in). Login, register, verify,
+  forgot, reset, MFA confirm, account dashboard. Themed via CSS
+  custom properties — no template editing required for a re-skin.
+  Full template overrides are still possible per host.
+- **CLIs.** `regstack init` (interactive setup wizard),
+  `regstack create-admin`, `regstack doctor`.
+- **Pluggable email and SMS.** Email backends: `console` (dev), SMTP,
+  [Amazon SES](https://aws.amazon.com/ses/). SMS backends:
+  [Amazon SNS](https://aws.amazon.com/sns/),
+  [Twilio](https://www.twilio.com/). Plug your own in by implementing
+  one method.
+- **Security defaults you would otherwise have to research.**
+  Argon2id password hashing, per-purpose
+  [JWT](https://datatracker.ietf.org/doc/html/rfc7519) signing keys,
+  per-token revocation, bulk session invalidation on password change,
+  login lockout with HTTP 429 + `Retry-After`, durable hashed
+  verification tokens, 6-digit SMS codes with attempt limits,
+  anti-enumeration on forgot/resend endpoints, CSP-friendly templates
+  with no inline styles.
+
+## Where to next
+
+- New here? Start with the [Quickstart](quickstart.md) — install,
+  generate a config, register a user end-to-end.
+- Embedding regstack in an existing app? Read
+  [Embedding](embedding.md) for the patterns most hosts adopt
+  (custom email, hooks, multiple regstacks, theming).
+- Curious how it's put together internally? See
+  [Architecture](architecture.md).
+- Designing a deployment? The [Security model](security.md) page is
+  the threat model, the JWT scheme, and the things you still own as
+  a host.
+
+```{toctree}
+:maxdepth: 2
+:caption: Getting started
+
+quickstart
+configuration
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Guides
+
+architecture
+security
+embedding
+theming
+cli
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Reference
+
+api
+changelog
+```
+
+## Project status
+
+Alpha. Latest tagged release: `v0.2.1`. SQLite is the default and
+runs with no infrastructure; PostgreSQL and MongoDB pass the same
+parametrized integration suite. The full backend matrix runs in
+parallel against every test, so a green CI on `main` is a strong
+correctness signal.

{regstack-0.2.1 → regstack-0.2.2}/docs/quickstart.md

@@ -2,13 +2,13 @@
 
 This guide walks you from "nothing installed" to "registered user
 with a verified email" in about ten minutes. You will need
-[Python 3.11 or newer](https://www.python.org/downloads/) and
-[`uv`](https://docs.astral.sh/uv/) (Astral's fast Python package
-manager — used throughout regstack's tooling).
+Python 3.11 or newer and [`uv`](https://docs.astral.sh/uv/)
+(Astral's fast Python package manager — used throughout regstack's
+tooling).
 
-The default storage backend is [SQLite](https://www.sqlite.org/index.html),
-so **no database server is required for development**. The same code
-runs against [PostgreSQL](https://www.postgresql.org/) or
+The default storage backend is SQLite, so **no database server is
+required for development**. The same code runs against
+[PostgreSQL](https://www.postgresql.org/) or
 [MongoDB](https://www.mongodb.com/) by changing one URL.
 
 ## Install
@@ -45,9 +45,9 @@ The wizard asks a handful of questions and writes two files:
 1. Which backend do you want? (SQLite / Postgres / MongoDB)
 2. Builds the right `database_url` for your choice (a SQLite path, a
    Postgres connection URL, or a Mongo URL).
-3. Generates a 64-byte JWT signing secret (used to sign and verify
-   [JSON Web Tokens](https://datatracker.ietf.org/doc/html/rfc7519) —
-   keep this secret).
+3. Generates a 64-byte signing secret used to sign and verify
+   [JWTs](https://datatracker.ietf.org/doc/html/rfc7519) — keep this
+   secret.
 4. Walks through email backend (`console` / SMTP / SES) and feature
    flags.
 
@@ -131,8 +131,8 @@ if config.enable_ui_router:
 This adds pages at `/account/login`, `/account/register`,
 `/account/me`, etc., and serves the bundled `core.css`, `theme.css`,
 and `regstack.js` at `/regstack-static/`. The pages are stateless and
-talk to the JSON API via [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
-Re-skin them by serving a single CSS file — see [Theming](theming.md).
+talk to the JSON API via `fetch`. Re-skin them by serving a single
+CSS file — see [Theming](theming.md).
 
 ## End-to-end smoke test (zero infrastructure)