diff --git a/.gitignore b/.gitignore
index 3831f06..a9f26a3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,3 +11,6 @@ dist/
 !.env.example
 
 .DS_Store
+
+# local, per-developer agent preferences: never versioned
+.claude/*.local.md
diff --git a/apps/blog/src/content/posts/en/what-is-iam-introduction-to-ferriskey.mdx b/apps/blog/src/content/posts/en/what-is-iam-introduction-to-ferriskey.mdx
index 23a2190..c9a3678 100644
--- a/apps/blog/src/content/posts/en/what-is-iam-introduction-to-ferriskey.mdx
+++ b/apps/blog/src/content/posts/en/what-is-iam-introduction-to-ferriskey.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Who are you, and what are you doing here?"
-description: "IAM (Identity & Access Management) underpins the security of almost every modern application. But what is it really, what does it do, and why is it so hard to get right? We break it all down — and introduce FerrisKey."
+description: "IAM (Identity & Access Management) underpins the security of almost every modern application. But what is it really, what does it do, and why is it so hard to get right? We take it apart, and introduce FerrisKey."
 short_description: "Understand IAM from scratch, and discover FerrisKey."
 date: 2026-03-19
 tags: [iam, identity, access-management, ferriskey, rust, open-source]
@@ -16,7 +16,7 @@ A deceptively simple question. But behind it lies an entire discipline, one that
 
 ## The problem, put simply
 
-Picture a large company. Hundreds of employees. Dozens of applications — accounting, HR, CRM, dev tooling, production servers. Every morning, people log in. Every evening, they log out. In between, they access data, trigger processes, read documents.
+Picture a large company. Hundreds of employees. Dozens of applications: accounting, HR, CRM, dev tooling, production servers. Every morning, people log in. Every evening, they log out. In between, they access data, trigger processes, read documents.
 
 Now, a few simple questions:
 
@@ -43,7 +43,7 @@ It knows who exists. Every human user, every application, every machine service
 :::
 
 :::card{label="Authentication" icon="lucide:key-round"}
-It verifies you are who you claim to be — password, TOTP, hardware key, magic link. When you "Sign in with Google", Google is the IAM.
+It verifies you are who you claim to be, with a password, a TOTP code, a hardware key, or a magic link. When you "Sign in with Google", Google is the IAM.
 :::
 
 :::card{label="Authorization" icon="lucide:shield-check"}
@@ -51,7 +51,7 @@ Once your identity is confirmed, it decides what you're allowed to do. Read? Wri
 :::
 
 :::card{label="Standard protocols" icon="lucide:globe"}
-A good IAM speaks OAuth2 and OpenID Connect (OIDC) — the universal languages of the web. Apps can delegate authentication without ever touching passwords.
+A good IAM speaks OAuth2 and OpenID Connect, the two languages the whole web already understands. Apps can delegate authentication without ever touching passwords.
 :::
 
 :::card{label="Audit" icon="lucide:scroll-text"}
@@ -73,7 +73,7 @@ IAM sounds simple. It's just a `users` table with a `password_hash`, right?
 Managing identities seriously means dealing with dozens of problems that stack up fast:
 secret rotation, token revocation, session expiration, service accounts, multi-tenancy, MFA strategies, webhooks, tamper-proof audit logs…
 
-And all of this has to hold under load. An IAM is a **mandatory chokepoint** — every authenticated request goes through it. If it's slow or goes down, your entire infrastructure stops.
+And all of this has to hold under load. An IAM is a mandatory chokepoint: every authenticated request goes through it. If it slows down or falls over, everything behind it stops.
 :::
 
 That's why large enterprises pay fortunes for solutions like Okta, Auth0, or Azure AD. On the open source side, Keycloak has been around for a long time and does the job, but it carries significant configuration complexity and a JVM footprint that doesn't suit everyone.
@@ -87,10 +87,10 @@ FerrisKey doesn't claim to be the definitive solution. It's an alternative, with
 FerrisKey is an open source IAM system, built in **Rust**, with a hexagonal architecture.
 
 :::callout{variant="info" title="Why Rust?"}
-Performance and reliability are non-negotiable for a component this critical. Rust delivers C-level speed without the pitfalls — no garbage collector, no data races, no memory surprises. For a service handling millions of authentications, that's exactly what you want.
+Performance and reliability are non-negotiable for a component this critical. Rust gives you C-level speed without the traps: no garbage collector, no data races, no memory surprises. For a service handling millions of authentications, that's exactly what you want.
 :::
 
-The hexagonal architecture ensures that business logic stays pure and decoupled from infrastructure. The database can change, the HTTP framework can evolve — the domain core stays stable and testable.
+The hexagonal architecture ensures that business logic stays pure and decoupled from infrastructure. The database can change and the HTTP framework can evolve while the domain core stays stable and testable.
 
 What a decoded OIDC ID token looks like when FerrisKey issues it:
 
@@ -112,23 +112,23 @@ In practice, FerrisKey gives you:
 
 ::::card-group{cols=2}
 :::card{label="Realms" icon="lucide:layers"}
-Fully isolated spaces. Each organization, project, or environment gets its own realm — its own users, roles, and clients. No cross-contamination possible.
+Fully isolated spaces. Each organization, project, or environment gets its own realm, with its own users, roles, and clients. Nothing crosses over.
 :::
 
 :::card{label="OAuth2 & OIDC" icon="lucide:lock-keyhole"}
 The web's standards, implemented correctly, so your apps can delegate authentication without friction.
 :::
 
-:::card{label="Trident — MFA" icon="lucide:shield"}
+:::card{label="Trident, for MFA" icon="lucide:shield"}
 FerrisKey's MFA module: TOTP, WebAuthn (hardware keys, passkeys), magic links, and recovery codes.
 :::
 
-:::card{label="SeaWatch — Audit" icon="lucide:eye"}
+:::card{label="SeaWatch, for audit" icon="lucide:eye"}
 A complete audit system, queryable from the console, tracing every security event across your realms.
 :::
 
 :::card{label="Webhooks" icon="lucide:webhook"}
-Connect FerrisKey to your existing systems and react to lifecycle events — user creation, access revocation, and more.
+Connect FerrisKey to your existing systems and react to lifecycle events: a user created, an access revoked, and the rest.
 :::
 
 :::card{label="Cloud-native" icon="lucide:cloud"}
@@ -136,7 +136,7 @@ An official Helm chart, Kubernetes Operator, and Docker Compose support for fric
 :::
 ::::
 
-:::callout{variant="success" title="Apache 2.0 — fully open"}
+:::callout{variant="success" title="Apache 2.0, fully open"}
 No paywall. No "enterprise" tier hiding critical features behind a contact form. The code is open, the community is here.
 :::
 
@@ -146,7 +146,7 @@ No paywall. No "enterprise" tier hiding critical features behind a contact form.
 
 ::::card-group{cols=3}
 :::card{label="SaaS teams" icon="lucide:rocket"}
-Building a platform and want robust auth without starting from scratch — or paying per monthly active user.
+Building a platform and want solid auth without starting from scratch, or paying per monthly active user.
 :::
 
 :::card{label="Platform engineers" icon="lucide:server"}
diff --git a/apps/blog/src/content/posts/en/why-rust-for-an-iam.mdx b/apps/blog/src/content/posts/en/why-rust-for-an-iam.mdx
index c7cd210..4a9c5f1 100644
--- a/apps/blog/src/content/posts/en/why-rust-for-an-iam.mdx
+++ b/apps/blog/src/content/posts/en/why-rust-for-an-iam.mdx
@@ -72,7 +72,7 @@ For the SREs who get paged when it isn't: no garbage collector means no GC pause
 
 ## What determinism buys us next
 
-Memory safety gets the headlines, but it's not the only property this design gives us for free. Ownership and the absence of a garbage collector also make the runtime deterministic: no GC pause, no JIT warm-up curve, no allocator quietly deciding to compact the heap under load. Feed the same input to the same binary twice and it takes the same path both times, with the same timing characteristics. That's not just a safety property, it's a performance one too: the same determinism that rules out data races is what keeps tail latency boring under load.
+Memory safety gets the headlines, but it's not the only property this design gives us for free. Ownership and the absence of a garbage collector also make the runtime deterministic: no GC pause, no JIT warm-up curve, no allocator quietly deciding to compact the heap under load. Feed the same input to the same binary twice and it takes the same path both times, with the same timing characteristics. That determinism buys you more than safety. The same property that rules out data races is what keeps tail latency boring under load.
 
 That determinism is also a foundation, not just an outcome, and it points at two things we want FerrisKey to grow into.
 
diff --git a/apps/blog/src/content/posts/fr/what-is-iam-introduction-to-ferriskey.mdx b/apps/blog/src/content/posts/fr/what-is-iam-introduction-to-ferriskey.mdx
index 77103da..bff45f5 100644
--- a/apps/blog/src/content/posts/fr/what-is-iam-introduction-to-ferriskey.mdx
+++ b/apps/blog/src/content/posts/fr/what-is-iam-introduction-to-ferriskey.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Qui es-tu, et qu'est-ce que tu fais là ?"
-description: "L'IAM (Identity & Access Management) est au cœur de la sécurité de presque toutes les applications modernes. Mais qu'est-ce que c'est vraiment, à quoi ça sert, et pourquoi c'est si difficile à bien faire ? On démêle tout — et on vous présente FerrisKey."
+description: "L'IAM (Identity & Access Management) est au cœur de la sécurité de presque toutes les applications modernes. Mais qu'est-ce que c'est vraiment, à quoi ça sert, et pourquoi c'est si difficile à bien faire ? On démêle tout, et on vous présente FerrisKey."
 short_description: "Comprendre l'IAM de zéro, et découvrir FerrisKey."
 date: 2026-03-19
 tags: [iam, identity, access-management, ferriskey, rust, open-source]
@@ -16,7 +16,7 @@ Une question trompeusement simple. Mais derrière elle se cache toute une discip
 
 ## Le problème, en clair
 
-Imaginez une grande entreprise. Des centaines d'employés. Des dizaines d'applications — comptabilité, RH, CRM, outils de dev, serveurs de production. Chaque matin, les gens se connectent. Chaque soir, ils se déconnectent. Entre-temps, ils accèdent à des données, déclenchent des processus, lisent des documents.
+Imaginez une grande entreprise. Des centaines d'employés. Des dizaines d'applications : comptabilité, RH, CRM, outils de dev, serveurs de production. Chaque matin, les gens se connectent. Chaque soir, ils se déconnectent. Entre-temps, ils accèdent à des données, déclenchent des processus, lisent des documents.
 
 Quelques questions simples :
 
@@ -43,7 +43,7 @@ Il sait qui existe. Chaque utilisateur humain, chaque application, chaque servic
 :::
 
 :::card{label="Authentification" icon="lucide:key-round"}
-Il vérifie que vous êtes bien qui vous prétendez être — mot de passe, TOTP, clé matérielle, magic link. Quand vous faites « Se connecter avec Google », Google est l'IAM.
+Il vérifie que vous êtes bien qui vous prétendez être, par mot de passe, TOTP, clé matérielle ou magic link. Quand vous faites « Se connecter avec Google », Google est l'IAM.
 :::
 
 :::card{label="Autorisation" icon="lucide:shield-check"}
@@ -51,7 +51,7 @@ Une fois votre identité confirmée, il décide ce que vous avez le droit de fai
 :::
 
 :::card{label="Protocoles standards" icon="lucide:globe"}
-Un bon IAM parle OAuth2 et OpenID Connect (OIDC) — les langages universels du web. Les applications peuvent déléguer l'authentification sans jamais toucher aux mots de passe.
+Un bon IAM parle OAuth2 et OpenID Connect, les deux langages que tout le web comprend déjà. Les applications peuvent déléguer l'authentification sans jamais toucher aux mots de passe.
 :::
 
 :::card{label="Audit" icon="lucide:scroll-text"}
@@ -73,7 +73,7 @@ L'IAM paraît simple. C'est juste une table `users` avec un `password_hash`, non
 Gérer des identités sérieusement, c'est faire face à des dizaines de problèmes qui s'accumulent vite :
 rotation des secrets, révocation de tokens, expiration de sessions, comptes de service, multi-tenancy, stratégies MFA, webhooks, journaux d'audit infalsifiables…
 
-Et tout ça doit tenir sous charge. Un IAM est un **point de passage obligatoire** — chaque requête authentifiée le traverse. S'il est lent ou tombe, toute votre infrastructure s'arrête.
+Et tout ça doit tenir sous charge. Un IAM est un point de passage obligatoire : chaque requête authentifiée le traverse. S'il ralentit ou tombe, tout ce qu'il y a derrière s'arrête.
 :::
 
 C'est pourquoi les grandes entreprises paient des fortunes pour des solutions comme Okta, Auth0 ou Azure AD. Côté open source, Keycloak existe depuis longtemps et fait le travail, mais il embarque une complexité de configuration significative et une empreinte JVM qui ne convient pas à tout le monde.
@@ -87,10 +87,10 @@ FerrisKey ne prétend pas être la solution définitive. C'est une alternative,
 FerrisKey est un système IAM open source, construit en **Rust**, avec une architecture hexagonale.
 
 :::callout{variant="info" title="Pourquoi Rust ?"}
-La performance et la fiabilité ne sont pas négociables pour un composant aussi critique. Rust offre une vitesse comparable au C sans les pièges — pas de garbage collector, pas de data races, pas de surprises mémoire. Pour un service qui gère des millions d'authentifications, c'est exactement ce qu'il faut.
+La performance et la fiabilité ne sont pas négociables pour un composant aussi critique. Rust offre une vitesse comparable au C sans les pièges : pas de garbage collector, pas de data races, pas de surprises mémoire. Pour un service qui gère des millions d'authentifications, c'est exactement ce qu'il faut.
 :::
 
-L'architecture hexagonale garantit que la logique métier reste pure et découplée de l'infrastructure. La base de données peut changer, le framework HTTP peut évoluer — le cœur du domaine reste stable et testable.
+L'architecture hexagonale garantit que la logique métier reste pure et découplée de l'infrastructure. La base de données peut changer et le framework HTTP évoluer, le cœur du domaine reste stable et testable.
 
 Voici à quoi ressemble un ID token OIDC décodé émis par FerrisKey :
 
@@ -112,23 +112,23 @@ En pratique, FerrisKey vous offre :
 
 ::::card-group{cols=2}
 :::card{label="Realms" icon="lucide:layers"}
-Des espaces totalement isolés. Chaque organisation, projet ou environnement dispose de son propre realm — ses propres utilisateurs, rôles et clients. Zéro contamination croisée possible.
+Des espaces totalement isolés. Chaque organisation, projet ou environnement dispose de son propre realm, avec ses utilisateurs, ses rôles et ses clients. Rien ne traverse.
 :::
 
 :::card{label="OAuth2 & OIDC" icon="lucide:lock-keyhole"}
 Les standards du web, implémentés correctement, pour que vos applications puissent déléguer l'authentification sans friction.
 :::
 
-:::card{label="Trident — MFA" icon="lucide:shield"}
+:::card{label="Trident, pour le MFA" icon="lucide:shield"}
 Le module MFA de FerrisKey : TOTP, WebAuthn (clés matérielles, passkeys), magic links et codes de récupération.
 :::
 
-:::card{label="SeaWatch — Audit" icon="lucide:eye"}
+:::card{label="SeaWatch, pour l'audit" icon="lucide:eye"}
 Un système d'audit complet, interrogeable depuis la console, traçant chaque événement de sécurité dans vos realms.
 :::
 
 :::card{label="Webhooks" icon="lucide:webhook"}
-Connectez FerrisKey à vos systèmes existants et réagissez aux événements du cycle de vie — création d'utilisateur, révocation d'accès, et plus encore.
+Connectez FerrisKey à vos systèmes existants et réagissez aux événements du cycle de vie : création d'utilisateur, révocation d'accès, et le reste.
 :::
 
 :::card{label="Cloud-native" icon="lucide:cloud"}
@@ -136,7 +136,7 @@ Un chart Helm officiel, un Kubernetes Operator et le support Docker Compose pour
 :::
 ::::
 
-:::callout{variant="success" title="Apache 2.0 — entièrement ouvert"}
+:::callout{variant="success" title="Apache 2.0, entièrement ouvert"}
 Pas de paywall. Pas de tier « enterprise » qui cache des fonctionnalités critiques derrière un formulaire de contact. Le code est ouvert, la communauté est là.
 :::
 
@@ -146,7 +146,7 @@ Pas de paywall. Pas de tier « enterprise » qui cache des fonctionnalités crit
 
 ::::card-group{cols=3}
 :::card{label="Équipes SaaS" icon="lucide:rocket"}
-Vous construisez une plateforme et voulez une auth robuste sans repartir de zéro — ni payer au nombre d'utilisateurs actifs mensuels.
+Vous construisez une plateforme et voulez une auth solide sans repartir de zéro, ni payer au nombre d'utilisateurs actifs mensuels.
 :::
 
 :::card{label="Ingénieurs plateforme" icon="lucide:server"}
diff --git a/apps/blog/src/content/posts/fr/why-rust-for-an-iam.mdx b/apps/blog/src/content/posts/fr/why-rust-for-an-iam.mdx
index 838b00c..8f37294 100644
--- a/apps/blog/src/content/posts/fr/why-rust-for-an-iam.mdx
+++ b/apps/blog/src/content/posts/fr/why-rust-for-an-iam.mdx
@@ -72,7 +72,7 @@ Pour les SRE qui sont réveillés quand ce n'est pas le cas : pas de garbage col
 
 ## Ce que le déterminisme nous permet ensuite
 
-La sécurité mémoire fait les gros titres, mais ce n'est pas la seule propriété que ce design nous offre gratuitement. L'ownership et l'absence de garbage collector rendent aussi le runtime déterministe : pas de pause GC, pas de courbe de chauffe JIT, pas d'allocateur qui décide discrètement de compacter le heap sous charge. Donnez la même entrée au même binaire deux fois, il emprunte le même chemin les deux fois, avec les mêmes caractéristiques de timing. Ce n'est pas qu'une propriété de sécurité, c'est aussi une propriété de performance : le même déterminisme qui exclut les data races est ce qui garde la latence de queue prévisible sous charge.
+La sécurité mémoire fait les gros titres, mais ce n'est pas la seule propriété que ce design nous offre gratuitement. L'ownership et l'absence de garbage collector rendent aussi le runtime déterministe : pas de pause GC, pas de courbe de chauffe JIT, pas d'allocateur qui décide discrètement de compacter le heap sous charge. Donnez la même entrée au même binaire deux fois, il emprunte le même chemin les deux fois, avec les mêmes caractéristiques de timing. Ce déterminisme rapporte plus que de la sûreté. La même propriété qui exclut les data races est celle qui garde la latence de queue prévisible sous charge.
 
 Ce déterminisme est aussi une fondation, pas juste un résultat, et il pointe vers deux choses qu'on veut voir grandir chez FerrisKey.
 
diff --git a/apps/blog/src/layouts/base.astro b/apps/blog/src/layouts/base.astro
index a518c01..deb410c 100644
--- a/apps/blog/src/layouts/base.astro
+++ b/apps/blog/src/layouts/base.astro
@@ -16,7 +16,7 @@ interface Props {
 const { title, description = 'Explainer Blog', thumbnail, locale = 'en', locales = ['en'], localeSwitchUrls = {} } = Astro.props
 const t = useTranslations(locale)
 const thumbnailPath = thumbnail ?? `${Astro.url.pathname.replace(/\/$/, '')}/thumbnail.png`
-// og:image/twitter:image must be absolute — Discord and most link-preview bots won't resolve a relative path.
+// og:image/twitter:image must be absolute: Discord and most link-preview bots won't resolve a relative path.
 const thumbnailUrl = Astro.site ? new URL(thumbnailPath, Astro.site).toString() : thumbnailPath
 
 const appUrlOverrides = {
@@ -41,7 +41,7 @@ const appUrlOverrides = {
     <meta name="twitter:title" content={title} />
     <meta name="twitter:description" content={description} />
     <meta name="twitter:image" content={thumbnailUrl} />
-    <title>{title} — Blog</title>
+    <title>{title} | Blog</title>
     <ClientRouter />
     <script is:inline>
       (function () {
diff --git a/apps/blog/src/lib/posts.ts b/apps/blog/src/lib/posts.ts
index 57f32ff..4202ba5 100644
--- a/apps/blog/src/lib/posts.ts
+++ b/apps/blog/src/lib/posts.ts
@@ -35,7 +35,7 @@ export function getPostLocale(post: Post): string {
 }
 
 export function getPostSlug(post: Post): string {
-  // id is "en/my-post.mdx" or "en/my-post" — strip locale prefix and extension
+  // id is "en/my-post.mdx" or "en/my-post": strip locale prefix and extension
   const withoutLocale = post.id.includes('/') ? post.id.split('/').slice(1).join('/') : post.id
   return withoutLocale.replace(/\.mdx$/, '')
 }
diff --git a/apps/blog/src/pages/404.astro b/apps/blog/src/pages/404.astro
index e2236c2..562a835 100644
--- a/apps/blog/src/pages/404.astro
+++ b/apps/blog/src/pages/404.astro
@@ -3,7 +3,7 @@ import Base from '../layouts/base.astro'
 import { defaultLang } from '../i18n/ui'
 ---
 
-<Base title="404 — Page not found" locale={defaultLang}>
+<Base title="404 | Page not found" locale={defaultLang}>
   <section class="flex-1 flex flex-col items-center justify-center text-center">
     <p class="text-primary text-sm font-semibold tracking-widest uppercase mb-4">404</p>
     <h1 class="text-4xl md:text-5xl font-bold tracking-tight mb-4">Page not found</h1>
diff --git a/apps/blog/src/pages/index.astro b/apps/blog/src/pages/index.astro
index e4dfcf6..2caf852 100644
--- a/apps/blog/src/pages/index.astro
+++ b/apps/blog/src/pages/index.astro
@@ -15,7 +15,7 @@ const tags = getAllTags(posts)
 const locale = defaultLang
 const t = useTranslations(locale)
 
-// Split into featured/rest per locale, not across the mixed-locale array —
+// Split into featured/rest per locale, not across the mixed-locale array:
 // otherwise an EN and FR copy of the same post can both land in the 2
 // featured slots, and hiding the wrong-locale one leaves an empty grid gap.
 const postsByLocale = locales.map((loc) => {
diff --git a/apps/docs/src/content/docs/cli/default/en/commands/index.mdx b/apps/docs/src/content/docs/cli/default/en/commands/index.mdx
index 596d707..fa88199 100644
--- a/apps/docs/src/content/docs/cli/default/en/commands/index.mdx
+++ b/apps/docs/src/content/docs/cli/default/en/commands/index.mdx
@@ -8,7 +8,7 @@ order: 0
 
 # Commands
 
-`ferris-ctl` exposes seven top-level commands. Every one of them accepts the [global flags](/en/cli/overview#global-flags), and every one resolves where to connect, who you are, and which realm to act on before it sends anything — see [Authentication](/en/cli/authentication).
+`ferris-ctl` has seven top-level commands. All of them accept the [global flags](/en/cli/overview#global-flags), and all of them resolve where to connect, who you are, and which realm to act on before sending anything. [Authentication](/en/cli/authentication) explains how.
 
 ## Connect and authenticate
 
@@ -28,13 +28,13 @@ Drop the stored session by deleting the credentials file.
 
 ::::card-group{cols=3}
 :::card{label="realm" icon="lucide:layers" href="/en/cli/commands/realm"}
-Create, inspect, and delete realms — and import one from an external source.
+Create, inspect, and delete realms, manage their roles, and import one from an external source.
 :::
 :::card{label="client" icon="lucide:box" href="/en/cli/commands/client"}
 Create, inspect, and delete OAuth2 clients within a realm.
 :::
 :::card{label="user" icon="lucide:users" href="/en/cli/commands/user"}
-Create, inspect, and delete users within a realm.
+Create, inspect, and delete users, set their passwords, and assign roles.
 :::
 ::::
 
@@ -54,9 +54,9 @@ The import guide: from a description file, a live Keycloak, or a live Zitadel in
 | Command | Purpose |
 |---------|---------|
 | [`context`](/en/cli/commands/context) | Manage connection contexts |
-| [`realm`](/en/cli/commands/realm) | Manage realms |
+| [`realm`](/en/cli/commands/realm) | Manage realms, their roles, and realm imports |
 | [`client`](/en/cli/commands/client) | Manage OAuth2 clients |
-| [`user`](/en/cli/commands/user) | Manage users |
+| [`user`](/en/cli/commands/user) | Manage users, their passwords, and their role assignments |
 | [`source`](/en/cli/commands/source) | Manage reusable import sources |
 | [`login`](/en/cli/commands/login) | Sign in via the OAuth 2.0 Device Authorization Grant |
 | [`logout`](/en/cli/commands/logout) | Remove the stored login session |
diff --git a/apps/docs/src/content/docs/cli/default/en/commands/realm.mdx b/apps/docs/src/content/docs/cli/default/en/commands/realm.mdx
index 15e790e..35a332f 100644
--- a/apps/docs/src/content/docs/cli/default/en/commands/realm.mdx
+++ b/apps/docs/src/content/docs/cli/default/en/commands/realm.mdx
@@ -1,13 +1,13 @@
 ---
 title: realm
-description: "Create, inspect, delete, and import realms."
+description: "Create, inspect, delete, and import realms, and manage realm and client roles."
 icon: layers
 order: 2
 ---
 
 # `realm`
 
-Manage realms, the isolated tenants that contain clients, users, roles, and credentials.
+Manage realms, the isolated tenants that hold clients, users, roles, and credentials.
 
 ```bash
 ferris-ctl realm <subcommand>
@@ -66,6 +66,69 @@ ferris-ctl realm delete <name> [--force]
 Without `--force`, the command refuses to run in a non-interactive shell rather than deleting silently. Pass `--force` (or `-f`) in CI and automation.
 :::
 
+## `realm role`
+
+Manage the roles of a realm, or the roles scoped to one of its clients. Every subcommand takes `--realm` to target a realm other than the context default, and `--client <client_id>` to work on that client's roles instead of the realm's.
+
+### `realm role create`
+
+```bash
+ferris-ctl realm role create <name> [--description <text>] [--permission <name>]... [--realm <realm>] [--client <client_id>]
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `<name>` | yes | Role name |
+| `--description` | no | Free-text description |
+| `--permission` | no | A permission granted by the role. Repeat the flag for several |
+| `--realm` | no | Realm (defaults to the context realm) |
+| `--client` | no | Create a client role scoped to this client id, instead of a realm role |
+
+Permissions are passed by their snake_case name, for example `manage_users`. See the [permissions reference](/en/discover/core-concepts/roles#permissions-reference) for the full list.
+
+```bash title="A realm role that can manage users"
+ferris-ctl realm role create user-admin \
+  --description "Create and update users" \
+  --permission manage_users \
+  --permission query_users \
+  --permission view_users
+```
+
+```bash title="A role scoped to one client"
+ferris-ctl realm role create service-reader --client backend
+```
+
+:::callout{variant="warning" title="Unknown permission names are dropped"}
+A permission name FerrisKey does not recognize is ignored rather than rejected, so a typo produces a role that grants nothing. Check the created role with `realm role get` after creating it.
+:::
+
+### `realm role list`
+
+```bash
+ferris-ctl realm role list [--realm <realm>] [--client <client_id>]
+```
+
+Lists realm roles, or the roles of `--client` when given. Table columns: NAME, ID.
+
+### `realm role get`
+
+```bash
+ferris-ctl realm role get <name> [--realm <realm>] [--client <client_id>]
+```
+
+### `realm role delete`
+
+```bash
+ferris-ctl realm role delete <name> [--realm <realm>] [--client <client_id>] [--force]
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `<name>` | yes | Role name |
+| `--realm` | no | Realm (defaults to the context realm) |
+| `--client` | no | Delete a client role instead of a realm role |
+| `--force` / `-f` | no | Skip the confirmation prompt (required in non-interactive shells) |
+
 ## `realm import`
 
 Import a realm (its settings, roles, clients, and users) from a description file, a live Keycloak, or a live Zitadel instance.
diff --git a/apps/docs/src/content/docs/cli/default/en/commands/user.mdx b/apps/docs/src/content/docs/cli/default/en/commands/user.mdx
index 77c6c74..677ce1e 100644
--- a/apps/docs/src/content/docs/cli/default/en/commands/user.mdx
+++ b/apps/docs/src/content/docs/cli/default/en/commands/user.mdx
@@ -1,13 +1,13 @@
 ---
 title: user
-description: "Create, inspect, and delete users within a realm."
+description: "Create, inspect, and delete users, set passwords, and manage role assignments."
 icon: users
 order: 4
 ---
 
 # `user`
 
-Manage users within a realm.
+Manage the users of a realm, their passwords, and the roles assigned to them.
 
 ```bash
 ferris-ctl user <subcommand>
@@ -64,9 +64,73 @@ ferris-ctl user create alice \
 ```
 
 :::callout{variant="note" title="Setting a password"}
-`user create` does not set credentials. Set the user's password from the FerrisKey admin console, or have the user complete a recovery flow.
+`user create` does not set credentials. Give the new account a password with [`user set-password`](#user-set-password), or let the user go through a recovery flow.
 :::
 
+## `user set-password`
+
+Set a user's password.
+
+```bash
+ferris-ctl user set-password <username> (--password <value> | --stdin) [--temporary] [--realm <realm>]
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `<username>` | yes | Username |
+| `--password` | one of the two | The new password, inline |
+| `--stdin` | one of the two | Read the password from stdin, trailing newline trimmed |
+| `--temporary` | no | Force the user to change this password at next login |
+| `--realm` | no | Realm (defaults to context realm) |
+
+Exactly one of `--password` and `--stdin` must be given; passing both, or neither, is an error.
+
+```bash title="Prefer stdin"
+printf '%s' "$NEW_PASSWORD" | ferris-ctl user set-password alice --stdin --temporary
+```
+
+:::callout{variant="warning" title="--password leaks into history"}
+A value passed to `--password` ends up in your shell history and in the process list, where anyone on the machine can read it. Use `--stdin` outside of throwaway environments.
+:::
+
+## `user assign-role`
+
+Assign a realm role, or a role of one client, to a user.
+
+```bash
+ferris-ctl user assign-role <username> <role> [--client <client_id>] [--realm <realm>]
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `<username>` | yes | Username |
+| `<role>` | yes | Role name |
+| `--client` | no | Resolve the role among this client's roles instead of the realm's |
+| `--realm` | no | Realm (defaults to context realm) |
+
+```bash
+ferris-ctl user assign-role alice user-admin
+ferris-ctl user assign-role alice service-reader --client backend
+```
+
+## `user remove-role`
+
+The inverse of `assign-role`, with the same arguments.
+
+```bash
+ferris-ctl user remove-role <username> <role> [--client <client_id>] [--realm <realm>]
+```
+
+## `user roles`
+
+List the roles assigned to a user.
+
+```bash
+ferris-ctl user roles <username> [--realm <realm>]
+```
+
+Table columns: NAME, ID.
+
 ## `user delete`
 
 Delete a user. Prompts for confirmation unless `--force` is passed.
diff --git a/apps/docs/src/content/docs/cli/default/en/import/config-file.mdx b/apps/docs/src/content/docs/cli/default/en/import/config-file.mdx
index eb6d8be..f1bbf49 100644
--- a/apps/docs/src/content/docs/cli/default/en/import/config-file.mdx
+++ b/apps/docs/src/content/docs/cli/default/en/import/config-file.mdx
@@ -7,7 +7,7 @@ order: 2
 
 # Import from a file
 
-`--from config` imports a realm from a FerrisKey-native description file. The format is detected from the extension: `.yaml`, `.yml`, or `.toml`. No external system or credentials are involved.
+`--from config` imports a realm from a FerrisKey-native description file. The format comes from the extension: `.yaml`, `.yml`, or `.toml`. No external system and no credentials are involved.
 
 ```bash
 ferris-ctl realm import --from config --file realm.yaml
@@ -21,7 +21,7 @@ ferris-ctl realm import --from config --file realm.yaml --dry-run -o yaml
 
 ## Format
 
-A description has a `name` and optional `settings`, `roles`, `clients`, and `users` sections.
+A description carries a `name`, plus optional `settings`, `roles`, `clients`, and `users` sections. The repository ships a working example at [`cli/examples/realm.yaml`](https://github.com/ferriskey/ferriskey/blob/main/cli/examples/realm.yaml).
 
 ```yaml title="realm.yaml"
 name: acme
@@ -36,9 +36,13 @@ roles:
   - name: admin
     description: Realm administrators
     permissions:
-      - realm:manage
+      - manage_realm
+      - manage_users
   - name: viewer
     description: Read-only access
+    permissions:
+      - view_users
+      - view_clients
 
 clients:
   - client_id: web-app
@@ -73,7 +77,7 @@ users:
 
 ## Settings
 
-All settings are optional; omitted fields keep the FerrisKey default.
+Every setting is optional. Anything you leave out keeps the FerrisKey default.
 
 | Field | Description |
 |-------|-------------|
@@ -91,12 +95,60 @@ All settings are optional; omitted fields keep the FerrisKey default.
 | `email_verification_enabled` | Require email verification |
 | `email_verification_ttl_hours` | Email verification link TTL (hours) |
 
-## Roles, clients, users
-
-- **roles:** `name`, optional `description`, optional `permissions` list.
-- **clients:** `client_id`, optional `name`, `client_type` (`public` / `confidential` / `system`), `public_client`, `service_account_enabled`, `direct_access_grants_enabled`, `protocol`, `enabled`, `redirect_uris`, and per-client `roles`.
-- **users:** `username`, optional `email`, `firstname`, `lastname`, `email_verified`, and a `roles` list referencing realm role names.
+## Roles
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `name` | required | Role name |
+| `description` | none | Free-text description |
+| `permissions` | `[]` | Permission names, in snake_case |
+
+Permissions use the names from the [permissions reference](/en/discover/core-concepts/roles#permissions-reference), so `manage_realm`, not `ManageRealm` and not `realm:manage`. Unrecognized names are dropped silently when the role is created.
+
+## Clients
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `client_id` | required | Client identifier |
+| `name` | none | Display name |
+| `client_type` | `public` | `public`, `confidential`, or `system` |
+| `protocol` | `openid-connect` | Protocol used by the client |
+| `enabled` | `true` | Whether the client can be used |
+| `public_client` | `false` | Public client, no secret |
+| `service_account_enabled` | `false` | Create a linked service account user |
+| `direct_access_grants_enabled` | `false` | Allow the password grant |
+| `device_authorization_grant_enabled` | `false` | Allow the device code grant |
+| `redirect_uris` | `[]` | Allowed redirect URIs |
+| `post_logout_redirect_uris` | `[]` | Allowed post-logout redirect URIs |
+| `web_origins` | `[]` | Browser origins allowed on this client's realm-scoped routes |
+| `require_pkce` | inherit | Require PKCE on the authorization code flow |
+| `access_token_lifetime` | inherit | Override the realm access token TTL, in seconds |
+| `refresh_token_lifetime` | inherit | Override the realm refresh token TTL |
+| `id_token_lifetime` | inherit | Override the realm ID token TTL |
+| `temporary_token_lifetime` | inherit | Override the realm temporary token TTL |
+| `roles` | `[]` | Roles scoped to this client, same shape as realm roles |
+
+## Users
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `username` | required | Username |
+| `email` | none | Email address |
+| `firstname` | none | First name |
+| `lastname` | none | Last name |
+| `email_verified` | none | Mark the email as already verified |
+| `roles` | `[]` | Roles to assign |
+
+A plain name in `roles` refers to a realm role. Prefix it with a client id to pick a role scoped to that client:
+
+```yaml
+users:
+  - username: alice
+    roles:
+      - admin              # realm role
+      - backend:service-reader   # role of the "backend" client
+```
 
 :::callout{variant="note" title="Passwords are not in the blueprint"}
-User credentials are never part of an import. Users are created without a password; set one afterward via the admin console or a recovery flow.
+Credentials are never part of an import. Users come out without a password: set one afterwards with [`ferris-ctl user set-password`](/en/cli/commands/user#user-set-password), from the admin console, or through a recovery flow.
 :::
diff --git a/apps/docs/src/content/docs/cli/default/en/import/keycloak.mdx b/apps/docs/src/content/docs/cli/default/en/import/keycloak.mdx
index 7db3dad..18d7dbf 100644
--- a/apps/docs/src/content/docs/cli/default/en/import/keycloak.mdx
+++ b/apps/docs/src/content/docs/cli/default/en/import/keycloak.mdx
@@ -27,10 +27,12 @@ ferris-ctl realm import --from keycloak \
 
 ## Authentication
 
-Choose one of:
+Two options:
 
-- **Client credentials:** pass `--source-client-id` and `--source-client-secret`. The CLI performs a client-credentials grant against Keycloak.
-- **A ready token:** pass `--source-token` with an existing bearer token, if you already have one.
+- Client credentials: pass `--source-client-id` and `--source-client-secret`, and the CLI runs a client-credentials grant against the source realm's token endpoint.
+- A ready token: pass `--source-token` when you already have a bearer token in hand.
+
+When `--source-token` is set, the client id and secret are ignored.
 
 ```bash title="Using a stored source"
 ferris-ctl source add kc-prod --kind keycloak \
@@ -42,13 +44,20 @@ ferris-ctl realm import --source-ref kc-prod --target-realm acme
 
 ## What gets imported
 
-The importer reads clients, realm roles, and users (paginated 100 per page) and maps them to a FerrisKey realm.
+The importer reads, from `/admin/realms/{realm}`:
+
+- realm settings, mapped onto the FerrisKey realm settings it has an equivalent for
+- clients, with their redirect URIs and flags
+- the roles of each client
+- realm roles
+- users, paged 100 at a time
+
+:::callout{variant="warning" title="What does not come across"}
+Keycloak never exports password hashes, so users arrive without credentials.
 
-:::callout{variant="warning" title="Limitations"}
-- **Passwords are never exported** by Keycloak, so users are recreated without credentials.
-- In the current iteration, realm roles are created but **per-user role mappings are not imported**.
+Role mappings per user are not imported either. The roles themselves are created, but who holds them is not carried over.
 
-Review the imported realm and re-establish credentials and role assignments as needed.
+Go through the imported realm afterwards and re-establish credentials and role assignments.
 :::
 
-Preview first with `--dry-run -o yaml` to see exactly what will be created.
+Run `--dry-run -o yaml` first to see precisely what would be created.
diff --git a/apps/docs/src/content/docs/discover/default/en/core-concepts/authentication.mdx b/apps/docs/src/content/docs/discover/default/en/core-concepts/authentication.mdx
index 0520402..6cd8a6e 100644
--- a/apps/docs/src/content/docs/discover/default/en/core-concepts/authentication.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/core-concepts/authentication.mdx
@@ -7,9 +7,9 @@ order: 16
 
 # Authentication
 
-FerrisKey implements the OAuth 2.0 and OpenID Connect specifications. Authentication always produces tokens, the grant type determines how the user (or client) proves their identity.
+FerrisKey implements OAuth 2.0 and OpenID Connect. Authentication always ends in tokens; the grant type decides how the user, or the client, proves who they are.
 
-## OpenID Connect Discovery
+## OpenID Connect discovery
 
 OpenID Connect applications need to know where the authorization server lives and which endpoints it exposes. FerrisKey publishes that information through the discovery endpoint:
 
@@ -34,69 +34,69 @@ This endpoint returns a JSON document that OIDC clients can read automatically.
 | `jwks_uri` | Where public signing keys are exposed so tokens can be verified |
 | `scopes_supported` | Which scopes can be requested, such as `openid`, `profile`, and `email` |
 
-Most applications use discovery so you do not have to paste every endpoint by hand. You give the application either the discovery endpoint or the issuer URL, and it learns the rest from FerrisKey.
+Most applications support discovery, so you rarely paste endpoints by hand. Give the application the discovery URL or the issuer, and it reads the rest from FerrisKey.
 
-:::callout{variant="info" title="Issuer and discovery are not always the same setting"}
-If an application asks for the **issuer** or **authority**, use the realm URL, for example `https://sso.example.com/realms/home`. If it asks for the **discovery endpoint** or **OpenID configuration URL**, use the full `/.well-known/openid-configuration` URL.
+:::callout{variant="info" title="Issuer and discovery are not the same setting"}
+When an application asks for the issuer or the authority, give it the realm URL, for example `https://sso.example.com/realms/home`. When it asks for the discovery endpoint or the OpenID configuration URL, give it the full `/.well-known/openid-configuration` address.
 :::
 
-## Grant Types
+## Grant types
 
-### Authorization Code
+### Authorization code
 
-The most secure flow for web applications. The user is redirected to FerrisKey, authenticates, and is sent back to the client with an authorization code that gets exchanged for tokens.
+The safest flow for web applications. The user is redirected to FerrisKey, authenticates there, and comes back to the client with a code that the client exchanges for tokens.
 
-**Flow:**
+The steps:
 1. Client redirects user to `/realms/{realm}/protocol/openid-connect/auth`
 2. User authenticates (credentials, MFA if required)
 3. FerrisKey redirects back with a `code` parameter
 4. Client exchanges the code at the token endpoint (server-side)
 5. FerrisKey returns access, refresh, and ID tokens
 
-**Best for:** Web applications, SPAs with a backend.
+Best for web applications and single-page apps with a backend.
 
-### Password (Resource Owner)
+### Password (resource owner)
 
-The client collects credentials directly and sends them to the token endpoint. Simple but less secure, the client handles the user's password.
+The client collects the credentials itself and posts them to the token endpoint. Simpler, and weaker: the client sees the user's password.
 
-**Flow:**
+The steps:
 1. Client sends `grant_type=password`, `username`, `password` to the token endpoint
 2. FerrisKey validates credentials
 3. If MFA is required, returns a temporary token with `requires_otp_challenge` status
 4. Client completes MFA challenge with the temporary token
 5. FerrisKey returns full tokens
 
-**Best for:** Trusted first-party applications, testing, CLI tools.
+Best for trusted first-party applications, testing, and CLI tools.
 
 :::callout{variant="warning" title="Direct access grants required"}
-The client must have `direct_access_grants_enabled` to use this flow.
+The client needs `direct_access_grants_enabled` for this flow to work.
 :::
 
-### Client Credentials
+### Client credentials
 
-Machine-to-machine authentication. The client authenticates with its own credentials (client ID + secret), no user involved.
+Machine to machine. The client authenticates with its own client id and secret, and no user is involved.
 
-**Flow:**
+The steps:
 1. Client sends `grant_type=client_credentials`, `client_id`, `client_secret`
 2. FerrisKey validates client credentials
 3. Returns an access token (no refresh token, no ID token)
 
-**Best for:** Backend services, cron jobs, microservice communication.
+Best for backend services, cron jobs, and calls between microservices.
 
-### Refresh Token
+### Refresh token
 
-Renew an expired access token without re-authentication.
+Renew an expired access token without sending the user back through login.
 
-**Flow:**
+The steps:
 1. Client sends `grant_type=refresh_token` with the refresh token
 2. FerrisKey validates the refresh token
 3. Returns new access and refresh tokens
 
-**Best for:** Any flow that issued a refresh token and needs to maintain a session.
+Best for any flow that issued a refresh token and needs to keep a session alive.
 
-## Authentication Chain
+## Authentication chain
 
-When a user authenticates, FerrisKey follows a strict chain:
+Every user authentication runs through the same chain:
 
 ```mermaid
 graph TD
@@ -112,14 +112,14 @@ graph TD
     MFA -->|No| T
 ```
 
-1. **Credential Validation**: Username and password are verified
-2. **Required Actions Check**: If the user has pending actions (ConfigureOtp, VerifyEmail, UpdatePassword), a temporary token is returned
-3. **MFA Check**: If TOTP or WebAuthn is configured, the user must complete the challenge
-4. **Token Issuance**: Full access, refresh, and ID tokens are generated
+1. Credential validation. The username and password are verified.
+2. Required actions. If any are pending (`configure_otp`, `verify_email`, `update_password`, `configure_passkey`), a temporary token comes back instead of the real thing.
+3. MFA. If TOTP or WebAuthn is configured, the challenge has to be answered.
+4. Token issuance. Access, refresh, and ID tokens are generated.
 
-## Auth Sessions
+## Auth sessions
 
-An **auth session** tracks the state of an in-progress authentication. It holds:
+An auth session tracks a login in progress. It holds:
 
 - The client and realm context
 - The redirect URI and OAuth2 parameters (`state`, `nonce`, `scope`)
@@ -127,4 +127,4 @@ An **auth session** tracks the state of an in-progress authentication. It holds:
 - WebAuthn challenge data (if applicable)
 - The linked Compass flow (if the flow engine is enabled)
 
-Auth sessions are short-lived and expire automatically.
+Auth sessions are short-lived and expire on their own.
diff --git a/apps/docs/src/content/docs/discover/default/en/core-concepts/client-scopes.mdx b/apps/docs/src/content/docs/discover/default/en/core-concepts/client-scopes.mdx
index 6419c1d..3b43c67 100644
--- a/apps/docs/src/content/docs/discover/default/en/core-concepts/client-scopes.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/core-concepts/client-scopes.mdx
@@ -7,57 +7,63 @@ order: 15
 
 # Client Scopes
 
-Client scopes control what information appears in tokens. A scope groups a set of **protocol mappers**: rules that extract user or client data and inject it as JWT claims.
+A client scope decides what ends up inside a token. It groups protocol mappers, which are the rules that pull data off a user or a client and write it into the JWT as claims.
 
-## Scope Types
+## Scope types
 
 | Type | Behavior |
 |---|---|
-| **Default** | Automatically included in every token issued for a client |
-| **Optional** | Only included when explicitly requested in the `scope` parameter |
-| **None** | Not assigned to any client by default |
+| Default | Included in every token issued for the client |
+| Optional | Included only when the client asks for it in the `scope` parameter |
+| None | Not assigned to the client at all |
 
-## Standard OIDC Scopes
+The same scope can be default for one client and optional for another. That is decided by the client scope mapping, not by the scope itself.
 
-FerrisKey includes the standard OpenID Connect scopes:
+## Scopes seeded by default
 
-| Scope | Claims |
-|---|---|
-| `openid` | `sub` (subject identifier) |
-| `profile` | `name`, `family_name`, `given_name`, `preferred_username` |
-| `email` | `email`, `email_verified` |
-| `address` | `address` |
-| `phone` | `phone_number`, `phone_number_verified` |
-| `offline_access` | Enables refresh token issuance |
-| `introspect` | Allows token introspection |
-
-## Protocol Mappers
-
-Protocol mappers define how data flows into tokens. Each mapper has a type that determines its behavior:
-
-| Mapper Type | Description |
-|---|---|
-| `user_attribute` | Maps a custom user attribute to a token claim |
-| `user_property` | Maps a built-in user property (username, email, etc.) to a claim |
-| `user_realm_role_mapper` | Includes the user's realm roles in the token |
-| `user_client_role_mapper` | Includes the user's client-specific roles in the token |
-| `audience_mapper` | Adds an audience (`aud`) value to the token |
-| `hardcoded_claim_mapper` | Adds a static value as a claim |
-
-Each mapper is configured with a JSON object specifying the source property, target claim name, and claim type.
+Every realm is seeded with a standard set of OIDC scopes, and every client in the realm gets them assigned.
 
-## Client Scope Mapping
+| Scope | Assigned as | Claims it produces |
+|---|---|---|
+| `openid` | default | none of its own; marks the request as OIDC |
+| `profile` | default | `given_name`, `family_name`, `preferred_username` |
+| `email` | default | `email`, `email_verified` |
+| `roles` | default | `realm_access.roles` |
+| `offline_access` | optional | none of its own |
+| `phone` | optional | `phone_number` |
+| `address` | optional | `address` |
 
-Scopes are linked to clients through **client scope mappings**. Each mapping specifies:
+## Protocol mappers
 
-- Which client the scope applies to
-- The scope type for that client (Default, Optional, or None)
+A mapper is identified by a `mapper_type` string. FerrisKey keeps the Keycloak names, so configuration written for Keycloak is recognizable here.
 
-This means the same scope can be a default for one client and optional for another.
+| `mapper_type` | What it does |
+|---|---|
+| `oidc-usermodel-property-mapper` | Maps a built-in user property (username, email, first name) to a claim |
+| `oidc-usermodel-attribute-mapper` | Maps a custom user attribute to a claim |
+| `oidc-usermodel-realm-role-mapper` | Writes the user's realm roles into the token |
+| `oidc-usermodel-client-role-mapper` | Writes the user's client roles into the token |
+| `oidc-group-membership-mapper` | Writes the user's group memberships |
+| `oidc-organization-membership-mapper` | Writes the user's organization memberships |
+| `oidc-organization-detail-mapper` | Writes details of the active organization |
+| `oidc-organization-role-mapper` | Writes the user's roles within an organization |
+| `oidc-audience-mapper` | Adds a value to the `aud` claim |
+| `oidc-hardcoded-claim-mapper` | Adds a fixed value as a claim |
+
+Each mapper carries a JSON `config`. The keys follow the Keycloak convention:
+
+```json title="Mapping the username into preferred_username"
+{
+  "user.attribute": "username",
+  "claim.name": "preferred_username",
+  "access.token.claim": "true",
+  "id.token.claim": "true"
+}
+```
 
-## How Scopes Shape Tokens
+`claim.name` supports dotted paths, so `realm_access.roles` produces a nested object rather than a flat key with a dot in its name.
 
-The token generation chain:
+## How scopes shape a token
 
 ```mermaid
 graph LR
@@ -68,12 +74,12 @@ graph LR
     J --> T[Sign Token]
 ```
 
-1. User authenticates to a client
-2. FerrisKey resolves which scopes apply (default + requested optional scopes)
-3. Protocol mappers from each active scope execute in order
-4. Mapper outputs become JWT claims
-5. The token is signed with the realm's signing key
+1. The user authenticates against a client.
+2. FerrisKey resolves which scopes apply: the client's default scopes, plus any optional ones the request asked for.
+3. The mappers on each active scope run.
+4. Their output becomes JWT claims, alongside the standard ones.
+5. The token is signed with the realm's key.
 
-:::callout{variant="info" title="Scope = claim contract"}
-Think of a scope as a contract between the client and the authorization server: "If you grant me the `profile` scope, I expect to receive the user's name and username in the token."
+:::callout{variant="info" title="A scope is a claim contract"}
+Read a scope as an agreement between the client and the authorization server: grant me `profile`, and I expect the user's name and username to come back in the token.
 :::
diff --git a/apps/docs/src/content/docs/discover/default/en/core-concepts/clients.mdx b/apps/docs/src/content/docs/discover/default/en/core-concepts/clients.mdx
index b2b245b..2c4ad72 100644
--- a/apps/docs/src/content/docs/discover/default/en/core-concepts/clients.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/core-concepts/clients.mdx
@@ -7,23 +7,23 @@ order: 11
 
 # Clients
 
-A client represents an application that uses FerrisKey for authentication. Every OAuth2/OIDC flow starts with a client, it identifies which application is requesting access and determines what authentication methods and token configurations apply.
+A client represents an application that authenticates through FerrisKey. Every OAuth2 and OIDC flow starts with one: it says which application is asking for access, and it determines which authentication methods and token settings apply.
 
-## Client Types
+## Client types
 
-FerrisKey supports three client types:
+There are three:
 
-| Type | Secret | Use Case |
+| Type | Secret | Use case |
 |---|---|---|
-| **Confidential** | Yes | Server-side applications that can securely store a client secret |
-| **Public** | No | Single-page applications (SPAs), mobile apps, or CLI tools |
-| **System** | None | Internal FerrisKey clients (auto-created, not user-managed) |
+| Confidential | Yes | Server-side applications that can keep a secret |
+| Public | No | Single-page apps, mobile apps, CLI tools |
+| System | None | Internal FerrisKey clients, created automatically and not user-managed |
 
 :::callout{variant="info" title="Choosing a client type"}
-Use **Confidential** when your application has a backend that can keep the client secret safe. Use **Public** for browser-based or mobile applications where the secret would be exposed to the user.
+Pick confidential when your application has a backend that can hold the secret safely. Pick public for anything running in a browser or on a device, where the secret would end up in the user's hands anyway.
 :::
 
-## Client Properties
+## Client properties
 
 | Property | Description |
 |---|---|
@@ -35,9 +35,9 @@ Use **Confidential** when your application has a backend that can keep the clien
 | `direct_access_grants_enabled` | Allow the password grant type |
 | `service_account_enabled` | Enable client credentials grant |
 
-## Token Lifetime Overrides
+## Token lifetime overrides
 
-By default, clients inherit token lifetimes from their realm. You can override these per-client for fine-grained control:
+Clients inherit token lifetimes from their realm. Override them per client when one application needs a different window:
 
 | Override | Description |
 |---|---|
@@ -46,14 +46,14 @@ By default, clients inherit token lifetimes from their realm. You can override t
 | `id_token_lifetime` | ID token TTL in seconds |
 | `temporary_token_lifetime` | Temporary token TTL in seconds |
 
-When set, the client's value takes precedence over the realm default. When `null`, the realm default applies.
+A value set on the client wins over the realm default. Leave it `null` and the realm default applies.
 
-## Direct Access Grants
+## Direct access grants
 
-When enabled, a client can use the **Resource Owner Password Credentials** grant, sending username and password directly to the token endpoint. This is useful for trusted first-party applications and testing, but should not be used for third-party clients.
+With this enabled, a client can use the resource owner password credentials grant, sending a username and password straight to the token endpoint. It is handy for trusted first-party applications and for testing. Do not enable it for third-party clients.
 
-## Service Accounts
+## Service accounts
 
-A client with `service_account_enabled` can authenticate using the **Client Credentials** grant, no user involved. FerrisKey creates a linked service account user for the client, which can be assigned roles and permissions just like a regular user.
+A client with `service_account_enabled` can authenticate through the client credentials grant, with no user involved. FerrisKey creates a linked service account user for it, and that user takes roles and permissions like any other.
 
-This is the standard pattern for machine-to-machine communication.
+This is the usual pattern for machine to machine calls.
diff --git a/apps/docs/src/content/docs/discover/default/en/core-concepts/credentials.mdx b/apps/docs/src/content/docs/discover/default/en/core-concepts/credentials.mdx
index babc640..18eeec3 100644
--- a/apps/docs/src/content/docs/discover/default/en/core-concepts/credentials.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/core-concepts/credentials.mdx
@@ -7,13 +7,13 @@ order: 13
 
 # Credentials
 
-A credential is proof of identity. FerrisKey supports multiple credential types that can be combined for multi-factor authentication.
+A credential is proof of identity. A user can hold several at once, which is what makes multi-factor authentication possible.
 
-## Credential Types
+## Credential types
 
 ### Password
 
-The most common credential type. Passwords are hashed using **Argon2**: a memory-hard algorithm designed to resist brute-force and GPU attacks.
+Passwords are hashed with Argon2, a memory-hard algorithm chosen because it makes GPU-accelerated brute forcing expensive.
 
 Stored data:
 - `hash_iterations`. Argon2 iteration count
@@ -22,24 +22,19 @@ Stored data:
 
 Passwords are never stored in plaintext and cannot be retrieved, only verified.
 
-### TOTP (Time-based One-Time Password)
+### TOTP
 
-A shared secret used with authenticator apps (Google Authenticator, Authy, 1Password). Configuration includes:
-
-- **Algorithm**: Hash function (SHA-1, SHA-256, SHA-512)
-- **Digits**: Code length (typically 6)
-- **Period**: Time step in seconds (typically 30)
-- **Issuer**: Display name in authenticator apps
+A shared secret paired with an authenticator app such as Google Authenticator, Authy, or 1Password. The credential records the hash function (SHA-1, SHA-256, or SHA-512), the code length, usually 6 digits, the time step, usually 30 seconds, and the issuer name the app displays.
 
 TOTP credentials are managed by the [Trident](/en/modules/trident/overview) module.
 
-### WebAuthn (FIDO2 Passkeys)
+### WebAuthn passkeys
 
-Hardware security keys and platform authenticators (Touch ID, Windows Hello, Android biometrics). WebAuthn credentials store the public key and credential metadata, the private key never leaves the user's device.
+Hardware security keys and platform authenticators: Touch ID, Windows Hello, Android biometrics. FerrisKey stores the public key and the credential metadata. The private key never leaves the user's device.
 
-### Recovery Codes
+### Recovery codes
 
-One-time backup codes generated when MFA is configured. Each code can be used exactly once to bypass the normal MFA challenge. Recovery codes are hashed before storage.
+Backup codes generated when MFA is set up. Each one works exactly once in place of the normal MFA challenge, and they are hashed before storage like any other secret.
 
 ### Federated
 
@@ -48,17 +43,12 @@ Credentials linked to an external identity provider (Google, GitHub, etc.) throu
 - `provider_id`. External provider identifier
 - `provider_type`. Provider type (OAuth2, OIDC)
 
-## Temporary Credentials
-
-A credential can be marked as **temporary**. Temporary credentials (typically passwords) trigger the `UpdatePassword` required action, the user must set a new permanent password before gaining full access.
+## Temporary credentials
 
-## Credential Lifecycle
+A credential can be flagged temporary. That is almost always a password, and it triggers the `update_password` required action: the user has to set a permanent one before getting full access.
 
-Users can have multiple credentials of different types simultaneously. A typical setup might include:
+## Credential lifecycle
 
-1. One **password** credential
-2. One **TOTP** credential (after MFA setup)
-3. One set of **recovery codes** (generated with TOTP)
-4. One or more **WebAuthn** passkeys
+A user typically ends up with a password, a TOTP credential once MFA is set up, the set of recovery codes generated alongside it, and possibly one or more WebAuthn passkeys.
 
-Each credential type can be added, updated, or removed independently through the admin console or user self-service endpoints.
+Each can be added, replaced, or removed on its own, either from the admin console or through the user's self-service endpoints.
diff --git a/apps/docs/src/content/docs/discover/default/en/core-concepts/realms.mdx b/apps/docs/src/content/docs/discover/default/en/core-concepts/realms.mdx
index 93a3a25..771ca13 100644
--- a/apps/docs/src/content/docs/discover/default/en/core-concepts/realms.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/core-concepts/realms.mdx
@@ -9,7 +9,7 @@ order: 10
 
 A realm is the top-level isolation boundary in FerrisKey. Users, clients, roles, credentials, scopes, and sessions each belong to exactly one realm. Realms make multi-tenancy possible: one FerrisKey deployment can serve many independent organizations.
 
-## What a Realm Isolates
+## What a realm isolates
 
 Each realm is a self-contained identity domain:
 
@@ -21,7 +21,7 @@ Each realm is a self-contained identity domain:
 - **Sessions**: active user sessions
 - **Configuration**: token lifetimes, registration policies, feature toggles
 
-There is no data leakage between realms. A user in realm A cannot authenticate to a client in realm B.
+Nothing leaks between realms. A user in realm A cannot authenticate against a client in realm B.
 
 ```mermaid
 graph TD
@@ -42,37 +42,74 @@ graph TD
     R3 --> C3[Staging Clients]
 ```
 
-## The Master Realm
+## The master realm
 
-Every FerrisKey deployment includes a **master** realm. This is a protected realm that:
-
-- Is created automatically on first boot
-- Contains the initial admin user
-- Cannot be deleted
-- Manages cross-realm administration
+Every deployment has a `master` realm. It is created on first boot, holds the initial admin user, cannot be deleted, and is where cross-realm administration happens.
 
 :::callout{variant="warning" title="Do not use master for applications"}
-The master realm is for administration only. Create dedicated realms for your applications.
+Keep `master` for administration. Give each application its own realm.
 :::
 
-## Realm Settings
+## Realm settings
+
+Every realm carries its own settings. They control how sign-in behaves, how long tokens live, and which optional features are on.
 
-Each realm has configurable settings that control authentication behavior:
+### Sign-in and registration
 
 | Setting | Default | Description |
 |---|---|---|
-| `default_signing_algorithm` | `RS256` | JWT signing algorithm |
-| `user_registration_enabled` | `false` | Allow self-service user registration |
-| `forgot_password_enabled` | `false` | Enable password reset flow |
+| `user_registration_enabled` | `false` | Allow self-service registration |
+| `forgot_password_enabled` | `false` | Enable the password reset flow |
 | `remember_me_enabled` | `false` | Support remember-me sessions |
-| `magic_link_enabled` | `false` | Enable email-based magic link login |
-| `magic_link_ttl` | `15` min | Magic link expiration time |
-| `compass_enabled` | `true` | Enable the Compass authentication flow engine |
-| `access_token_lifetime` | `300`s (5 min) | Default access token TTL |
-| `refresh_token_lifetime` | `86400`s (24 hr) | Default refresh token TTL |
-| `id_token_lifetime` | `300`s (5 min) | Default ID token TTL |
-| `temporary_token_lifetime` | `300`s (5 min) | Temporary token TTL (for required actions) |
+| `magic_link_enabled` | `false` | Enable magic link sign-in by email |
+| `magic_link_ttl_minutes` | `15` | How long a magic link stays valid |
+| `passkey_enabled` | `false` | Allow passkey (WebAuthn) sign-in |
+| `require_mfa` | `false` | Force every user in the realm to enroll in MFA |
+| `login_aliases` | `[email, username]` | Ordered list of identifiers accepted at login. Must be non-empty and free of duplicates |
+| `edit_username_enabled` | `false` | Let users change their own username |
+| `email_verification_enabled` | `false` | Require users to verify their email |
+| `email_verification_ttl_hours` | `24` | How long a verification link stays valid |
+| `compass_enabled` | `true` | Record authentication flows with Compass |
+
+### Token lifetimes
+
+| Setting | Default | Description |
+|---|---|---|
+| `default_signing_algorithm` | `RS256` | JWT signing algorithm |
+| `access_token_lifetime_secs` | `300` | Access token TTL |
+| `refresh_token_lifetime_secs` | `86400` | Refresh token TTL |
+| `id_token_lifetime_secs` | `300` | ID token TTL |
+| `temporary_token_lifetime_secs` | `300` | Temporary token TTL, used while required actions are pending |
+
+### Lockout
+
+After too many failed attempts, an account is locked for a fixed window.
+
+| Setting | Default | Description |
+|---|---|---|
+| `lockout_threshold` | `10` | Failed attempts before the account locks |
+| `lockout_duration_seconds` | `900` | How long the lock lasts |
+
+### Audit privacy
+
+SeaWatch can strip or pseudonymise personal data before an event is stored.
+
+| Setting | Default | Description |
+|---|---|---|
+| `seawatch_pii_mode` | `off` | One of `off`, `mask`, `pseudonymise` |
+| `seawatch_pseudo_key` | unset | HMAC key used when the mode is `pseudonymise` |
+
+### Branding and email templates
+
+| Setting | Default | Description |
+|---|---|---|
+| `portal_theme_id` | unset | Theme applied to the login portal |
+| `reset_password_template_id` | unset | Template used for password reset emails |
+| `magic_link_template_id` | unset | Template used for magic link emails |
+| `email_verification_template_id` | unset | Template used for verification emails |
+
+Leave a template id unset and FerrisKey falls back to the built-in default for that email type.
 
-## SMTP Configuration
+## SMTP configuration
 
-Each realm can configure its own SMTP settings for email delivery (magic links, password resets, email verification). This allows different realms to use different mail providers or sender addresses.
+SMTP lives on the realm too, so two realms in the same deployment can send from different providers and different addresses. The [Email & Templates guide](/en/discover/guides/email) covers the fields and the API.
diff --git a/apps/docs/src/content/docs/discover/default/en/core-concepts/roles.mdx b/apps/docs/src/content/docs/discover/default/en/core-concepts/roles.mdx
index 13598c5..3176499 100644
--- a/apps/docs/src/content/docs/discover/default/en/core-concepts/roles.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/core-concepts/roles.mdx
@@ -7,9 +7,9 @@ order: 14
 
 # Roles & Permissions
 
-FerrisKey uses a **bitwise permission system** where each permission is a single bit in a 64-bit integer. Roles are named bundles of permissions. Authorization checks reduce to fast bitwise AND operations.
+Permissions in FerrisKey are bits in a 64-bit integer. A role is a named bundle of them, and an authorization check is a single bitwise AND.
 
-## How It Works
+## How it works
 
 Each permission maps to a unique power of two:
 
@@ -28,58 +28,65 @@ fn has_permission(user_permissions: u64, required: u64) -> bool {
 }
 ```
 
-## Permissions Reference
+## Permissions reference
 
-### Manage Permissions
+The API and the CLI both take permissions by their snake_case name, so `manage_realm`, not `ManageRealm` and not `realm:manage`. An unrecognized name is dropped silently when a role is saved, which is worth remembering when a role looks like it granted nothing.
+
+### Manage
 
 | Permission | Description |
 |---|---|
-| `CreateClient` | Create new OAuth2 clients |
-| `ManageAuthorization` | Manage authorization policies |
-| `ManageClients` | Update and delete clients |
-| `ManageEvents` | Manage audit event configuration |
-| `ManageIdentityProviders` | Configure external identity providers |
-| `ManageRealm` | Update realm settings |
-| `ManageUsers` | Create, update, and delete users |
-| `ManageRoles` | Create, update, and delete roles |
-| `ManageWebhooks` | Configure webhook subscriptions |
-| `ManageClientScopes` | Manage client scopes and protocol mappers |
-
-### Query Permissions
+| `create_client` | Create new OAuth2 clients |
+| `manage_authorization` | Manage authorization policies |
+| `manage_clients` | Update and delete clients |
+| `manage_events` | Manage audit event configuration |
+| `manage_identity_providers` | Configure external identity providers |
+| `manage_realm` | Update realm settings |
+| `manage_users` | Create, update, and delete users |
+| `manage_roles` | Create, update, and delete roles |
+| `manage_webhooks` | Configure webhook subscriptions |
+| `manage_client_scopes` | Manage client scopes and protocol mappers |
+| `manage_email_templates` | Create, update, and delete email templates |
+
+### Query
 
 | Permission | Description |
 |---|---|
-| `QueryClients` | List and search clients |
-| `QueryGroups` | List and search groups |
-| `QueryRealms` | List and search realms |
-| `QueryUsers` | List and search users |
-| `QueryWebhooks` | List and search webhooks |
-| `QueryClientScopes` | List and search client scopes |
+| `query_clients` | List and search clients |
+| `query_groups` | List and search groups |
+| `query_realms` | List and search realms |
+| `query_users` | List and search users |
+| `query_webhooks` | List and search webhooks |
+| `query_client_scopes` | List and search client scopes |
 
-### View Permissions
+### View
 
 | Permission | Description |
 |---|---|
-| `ViewAuthorization` | View authorization details |
-| `ViewClients` | View client details |
-| `ViewEvents` | View audit events |
-| `ViewIdentityProviders` | View identity provider details |
-| `ViewRealm` | View realm details |
-| `ViewUsers` | View user details |
-| `ViewRoles` | View role details |
-| `ViewWebhooks` | View webhook details |
-| `ViewClientScopes` | View client scope details |
+| `view_authorization` | View authorization details |
+| `view_clients` | View client details |
+| `view_events` | View audit events |
+| `view_identity_providers` | View identity provider details |
+| `view_realm` | View realm details |
+| `view_users` | View user details |
+| `view_roles` | View role details |
+| `view_webhooks` | View webhook details |
+| `view_client_scopes` | View client scope details |
+| `view_email_templates` | View email templates |
+
+## Role mappings
+
+Roles are attached to users, including service account users, through role mappings. A user's effective permissions are the bitwise OR of every role bitmask assigned to them.
 
-## Role Mappings
+Take a user with two roles:
 
-Roles are assigned to users (or service account users) through role mappings. A user's effective permissions are the **union** (bitwise OR) of all assigned role bitmasks.
+- Viewer, holding `view_users | view_clients` = `0b...10100`
+- User Manager, holding `manage_users | query_users` = `0b...01010`
 
-For example, if a user has two roles:
-- **Viewer** with permissions `ViewUsers | ViewClients` = `0b...10100`
-- **User Manager** with permissions `ManageUsers | QueryUsers` = `0b...01010`
+The effective mask is `0b...11110`: they can view and manage users, view clients, and query users.
 
-Their effective bitmask is `0b...11110`, they can view and manage users, view clients, and query users.
+## Realm and client roles
 
-## Realm-Scoped Roles
+A realm role is defined on the realm and applies across all its clients. A client role is scoped to one client and only means something in that client's context. Both are assigned to users the same way, and role ids are unique across the two scopes.
 
-Roles are defined within a realm and apply to all clients in that realm. When a user authenticates, their roles are resolved and included in the access token as claims (via protocol mappers), allowing resource servers to make authorization decisions without calling back to FerrisKey.
+When a user authenticates, their roles are resolved and written into the access token as claims through protocol mappers, so a resource server can authorize a request without calling back to FerrisKey.
diff --git a/apps/docs/src/content/docs/discover/default/en/core-concepts/tokens.mdx b/apps/docs/src/content/docs/discover/default/en/core-concepts/tokens.mdx
index d1419f7..8010de9 100644
--- a/apps/docs/src/content/docs/discover/default/en/core-concepts/tokens.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/core-concepts/tokens.mdx
@@ -7,65 +7,68 @@ order: 17
 
 # Tokens
 
-FerrisKey issues JSON Web Tokens (JWTs) as the result of successful authentication. Each token type serves a specific purpose in the OAuth2/OIDC protocol.
+A successful authentication produces JSON Web Tokens. Each type has one job in the OAuth2 and OIDC protocol.
 
-## Token Types
+## Token types
 
-| Token | Purpose | Typical Lifetime |
+| Token | Purpose | Default lifetime |
 |---|---|---|
-| **Access Token** | Authorize API requests to resource servers | 300s (5 min) |
-| **Refresh Token** | Obtain new access tokens without re-authentication | 86400s (24 hr) |
-| **ID Token** | Convey user identity to the client (OIDC) | 300s (5 min) |
-| **Temporary Token** | Authorize required action completion only | 300s (5 min) |
+| Access token | Authorize API requests against a resource server | 300s |
+| Refresh token | Get new access tokens without asking the user again | 86400s |
+| ID token | Carry the user's identity to the client, per OIDC | 300s |
+| Temporary token | Authorize the completion of required actions, nothing else | 300s |
 
-## JWT Structure
+## JWT structure
 
-Every FerrisKey token is a signed JWT with three parts: header, payload, and signature.
+Every token is a signed JWT: header, payload, signature.
 
-### Standard Claims
+### Standard claims
 
 | Claim | Description |
 |---|---|
-| `sub` | Subject, the user's unique ID |
-| `aud` | Audience, the client ID |
-| `iss` | Issuer, the realm's token endpoint URL |
+| `sub` | Subject, the user's id |
+| `aud` | Audience, a list of client ids |
+| `azp` | Authorized party, the client that requested the token |
+| `iss` | Issuer, the realm URL |
+| `typ` | Token type |
 | `exp` | Expiration timestamp |
 | `iat` | Issued-at timestamp |
-| `nbf` | Not-before timestamp |
-| `jti` | JWT ID, unique token identifier |
+| `jti` | Unique token identifier |
 | `scope` | Space-separated list of granted scopes |
+| `sid` | OIDC session id, the user session this token was issued against |
 
-### Custom Claims
+`sid` is absent for flows that establish no SSO session, `client_credentials` among them. Treat a missing `sid` as "not session-bound", not as an invalid token.
 
-Protocol mappers (configured through [client scopes](/en/discover/core-concepts/client-scopes)) inject additional claims:
+### Identity and mapper claims
+
+`preferred_username` and `email` are written directly when the matching scope is granted. Everything else comes from protocol mappers configured on [client scopes](/en/discover/core-concepts/client-scopes), and is flattened into the payload:
 
 | Claim | Source |
 |---|---|
-| `realm_roles` | User's realm role names |
-| `client_roles` | User's client-specific role names |
-| `permissions` | Resolved permission bitmask |
-| `preferred_username` | Username |
-| `email` | Email address |
-| `given_name` | First name |
-| `family_name` | Last name |
+| `preferred_username` | `profile` scope |
+| `given_name`, `family_name` | `profile` scope |
+| `email`, `email_verified` | `email` scope |
+| `realm_access.roles` | `roles` scope, through `oidc-usermodel-realm-role-mapper` |
+
+Because mappers are configurable, the exact claim set depends on the scopes assigned to the client.
 
-## Token Lifetimes
+## Token lifetimes
 
-Token lifetimes are configured at two levels:
+Lifetimes come from two places:
 
-1. **Realm defaults**: Apply to all clients in the realm
-2. **Client overrides**: Take precedence when set
+1. Realm defaults, which apply to every client in the realm.
+2. Client overrides, which win when they are set.
 
-| Token | Realm Default | Client Override |
+| Token | Realm default | Client override |
 |---|---|---|
-| Access Token | `access_token_lifetime` (300s) | `access_token_lifetime` |
-| Refresh Token | `refresh_token_lifetime` (86400s) | `refresh_token_lifetime` |
-| ID Token | `id_token_lifetime` (300s) | `id_token_lifetime` |
-| Temporary Token | `temporary_token_lifetime` (300s) | `temporary_token_lifetime` |
+| Access token | `access_token_lifetime_secs` (300s) | `access_token_lifetime` |
+| Refresh token | `refresh_token_lifetime_secs` (86400s) | `refresh_token_lifetime` |
+| ID token | `id_token_lifetime_secs` (300s) | `id_token_lifetime` |
+| Temporary token | `temporary_token_lifetime_secs` (300s) | `temporary_token_lifetime` |
 
-The resolution rule is simple: if the client defines an override, use it. Otherwise, fall back to the realm default.
+The rule: if the client sets an override, use it, otherwise fall back to the realm.
 
-## Token Generation Chain
+## Token generation chain
 
 ```mermaid
 graph LR
@@ -83,9 +86,9 @@ graph LR
 5. The token is signed using the realm's signing key and algorithm
 6. Access, refresh, and (optionally) ID tokens are returned
 
-## Token Introspection
+## Token introspection
 
-Resource servers can validate tokens by calling the introspection endpoint:
+A resource server validates a token by calling the introspection endpoint:
 
 ```bash
 curl -X POST http://localhost:3333/realms/{realm}/protocol/openid-connect/token/introspect \
@@ -95,4 +98,4 @@ curl -X POST http://localhost:3333/realms/{realm}/protocol/openid-connect/token/
   -d "client_secret=my-secret"
 ```
 
-The response includes `active: true/false` and the full set of token claims when active.
+The response carries `active: true` or `active: false`, plus the full claim set when the token is still live.
diff --git a/apps/docs/src/content/docs/discover/default/en/core-concepts/users.mdx b/apps/docs/src/content/docs/discover/default/en/core-concepts/users.mdx
index 472af84..893bc34 100644
--- a/apps/docs/src/content/docs/discover/default/en/core-concepts/users.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/core-concepts/users.mdx
@@ -9,11 +9,11 @@ order: 12
 
 A user represents an identity within a [realm](/en/discover/core-concepts/realms). Users authenticate through [clients](/en/discover/core-concepts/clients), prove who they are with [credentials](/en/discover/core-concepts/credentials), receive [tokens](/en/discover/core-concepts/tokens), and are authorized through [role](/en/discover/core-concepts/roles) assignments.
 
-Everything that happens at runtime — login, token issuance, authorization — ultimately resolves to a user.
+Login, token issuance, authorization: at runtime it all resolves back to a user.
 
-## Anatomy of a User
+## Anatomy of a user
 
-A user is a small record. The core fields describe who they are; everything else (credentials, roles, sessions) lives in related objects.
+The user record itself is small. It describes who someone is; credentials, roles, and sessions live in related objects.
 
 | Property | Description |
 |---|---|
@@ -46,9 +46,9 @@ A representative JSON payload returned by the admin API:
 Use `id` to reference a user from other resources (role assignments, audit logs, tokens). `username` is a human-facing handle and may change; `id` is immutable.
 :::
 
-## Realm Scoping
+## Realm scoping
 
-Users are fully scoped to their realm. The same email address can exist in multiple realms as completely independent accounts. There is no cross-realm user resolution — authentication always happens within a single realm context.
+Users belong to exactly one realm. The same email address can exist in several realms as entirely separate accounts. There is no cross-realm lookup: authentication always happens inside one realm.
 
 ```mermaid
 graph LR
@@ -61,11 +61,11 @@ graph LR
     U1 -. no shared state .- U2
 ```
 
-If you need a single identity that spans multiple realms, federate it through the [Abyss](/en/modules/abyss/overview) module — each realm keeps its own user record, linked to the same external provider.
+For one identity across several realms, federate it through the [Abyss](/en/modules/abyss/overview) module. Each realm still keeps its own user record, linked to the same external provider.
 
-## User Lifecycle
+## User lifecycle
 
-From creation to deletion, a user moves through a small number of states.
+A user moves through a small number of states between creation and deletion.
 
 ```mermaid
 stateDiagram-v2
@@ -78,20 +78,24 @@ stateDiagram-v2
     Deleted --> [*]
 ```
 
-- **Provisioned** — The account exists but may have pending [required actions](#required-actions) (verify email, set a permanent password, configure MFA). Authentication produces only a temporary token until the user clears them.
-- **Active** — Authentication produces full tokens. Roles and group memberships apply.
-- **Disabled** — `enabled = false`. The account is preserved but cannot authenticate. Tokens already issued continue to be valid until they expire; revoke sessions if you need immediate cutoff.
-- **Deleted** — The user record is removed. Sessions and refresh tokens linked to it are invalidated.
+**Provisioned.** The account exists but may still have pending [required actions](#required-actions): verify an email, set a permanent password, enroll in MFA. Until those are cleared, authentication only produces a temporary token.
 
-## Required Actions
+**Active.** Authentication produces full tokens, and role assignments apply.
 
-Required actions are tasks a user must complete before full authentication is granted. When a user has pending required actions, the authentication chain returns a **temporary token** instead of full access tokens.
+**Disabled.** `enabled = false`. The account is kept but cannot authenticate. Tokens already issued stay valid until they expire, so revoke sessions when you need an immediate cutoff.
+
+**Deleted.** The record is removed, and the sessions and refresh tokens attached to it are invalidated.
+
+## Required actions
+
+A required action is something a user has to finish before full authentication is granted. While any are pending, the authentication chain hands back a temporary token instead of a full token set.
 
 | Action | When it is added | What the user must do |
 |---|---|---|
-| `VerifyEmail` | Email changes, or realm policy requires verification | Click the link sent by the [Trident](/en/modules/trident/overview) module |
-| `UpdatePassword` | Admin marks the credential as temporary, or password expires | Set a new password |
-| `ConfigureOtp` | Realm requires MFA and the user has no TOTP credential yet | Enroll a TOTP authenticator |
+| `verify_email` | The email changed, or realm policy requires verification | Click the link sent by the [Trident](/en/modules/trident/overview) module |
+| `update_password` | An admin marked the credential temporary, or the password expired | Set a new password |
+| `configure_otp` | The realm requires MFA and the user has no TOTP credential yet | Enroll a TOTP authenticator |
+| `configure_passkey` | The realm requires a passkey and the user has none registered | Register a WebAuthn passkey |
 
 ### How they flow
 
@@ -114,23 +118,23 @@ sequenceDiagram
 ```
 
 :::callout{variant="info" title="Temporary tokens"}
-A temporary token is a short-lived JWT that authorizes **only** the required-action completion endpoints. It cannot be used to access protected resources, call userinfo, or refresh into a full session.
+A temporary token is a short-lived JWT that authorizes the required-action endpoints and nothing else. It cannot reach a protected resource, call userinfo, or refresh into a full session.
 :::
 
 :::callout{variant="warning" title="Order matters"}
-Required actions are evaluated in a fixed order. `VerifyEmail` typically runs first, then `UpdatePassword`, then `ConfigureOtp`. The client should always read the `required_actions` array rather than hard-coding the order.
+Required actions are evaluated in a fixed order, usually `verify_email`, then `update_password`, then the MFA enrollment actions. Read the `required_actions` array in the response rather than hard-coding that order in a client.
 :::
 
-## Service Account Users
+## Service account users
 
-When a [client](/en/discover/core-concepts/clients) has `service_account_enabled`, FerrisKey automatically creates a linked service account user. This user is just a regular user record, with a few distinctions:
+When a [client](/en/discover/core-concepts/clients) has `service_account_enabled`, FerrisKey creates a linked service account user. It is an ordinary user record with a few distinguishing traits:
 
 - `username` is derived from the client (`service-account-<client_id>`).
 - `client_id` points back to the owning client.
-- It has no password — it authenticates exclusively through the `client_credentials` grant.
+- It has no password, and authenticates only through the `client_credentials` grant.
 - It can be assigned roles and permissions like any other user.
 
-It exists so that machine-to-machine calls have a real subject for authorization decisions and audit logs.
+It exists so machine to machine calls have a real subject for authorization decisions and audit logs.
 
 ### Example
 
@@ -145,11 +149,11 @@ curl -X POST https://sso.example.com/realms/home/protocol/openid-connect/token \
 
 The resulting access token has `sub` set to the service account user's `id`, and carries the `billing:read` role. The billing API can authorize the call exactly as it would for a human user.
 
-See [Authentication → Client Credentials](/en/discover/core-concepts/authentication#client-credentials) for the full grant.
+See [Authentication, client credentials](/en/discover/core-concepts/authentication#client-credentials) for the full grant.
 
 ## Sessions
 
-A user can have multiple concurrent sessions — one per browser, device, or service that holds a valid refresh token.
+A user can hold several sessions at once, one per browser, device, or service holding a valid refresh token.
 
 | Concept | Lifetime | What it represents |
 |---|---|---|
@@ -157,21 +161,25 @@ A user can have multiple concurrent sessions — one per browser, device, or ser
 | **User session** | Hours to days | An authenticated session. Backed by a refresh token. |
 | **Access token** | Minutes | Short-lived bearer token derived from a user session. |
 
-Revoking a refresh token ends the user session immediately; access tokens issued from it cannot be refreshed and will simply expire. For full details see [Tokens](/en/discover/core-concepts/tokens) and [Authentication → Auth Sessions](/en/discover/core-concepts/authentication#auth-sessions).
+Revoking a refresh token ends the user session immediately. Access tokens issued from it cannot be refreshed and simply expire on their own. [Tokens](/en/discover/core-concepts/tokens) and [Authentication, auth sessions](/en/discover/core-concepts/authentication#auth-sessions) have the details.
+
+## Security considerations
+
+**Disable rather than delete.** Disabling keeps the audit history and the role assignments. Delete only when you are certain the identity will never come back.
+
+**Force a password rotation** by marking the password credential temporary. The next login triggers the `update_password` required action.
+
+**Force MFA enrollment** by setting `require_mfa` on the realm. Existing users without a TOTP credential get `configure_otp` on their next login.
 
-## Security Considerations
+**Revoke active sessions.** Disabling a user leaves already-issued access tokens working. Revoke the refresh tokens to cut access straight away.
 
-- **Disable, don't delete** — Disabling preserves audit history and role assignments. Delete only when you are sure the identity will never return.
-- **Force a password rotation** — Mark the password credential as temporary; the next login will trigger the `UpdatePassword` required action.
-- **Force MFA enrollment** — Configure the realm to require MFA. Existing users without TOTP will receive `ConfigureOtp` on next login.
-- **Revoke active sessions** — Disabling a user does not invalidate already-issued access tokens. Revoke the user's refresh tokens to cut access immediately.
-- **Audit identifiers** — Reference users by `id` in logs and external systems. Usernames and emails can change; `id` cannot.
+**Reference users by `id`** in logs and external systems. Usernames and emails change; the id does not.
 
-## Related Concepts
+## Related concepts
 
-- [Realms](/en/discover/core-concepts/realms) — the boundary a user lives in.
-- [Clients](/en/discover/core-concepts/clients) — what users authenticate through.
-- [Credentials](/en/discover/core-concepts/credentials) — how users prove identity.
-- [Roles](/en/discover/core-concepts/roles) — how users get authorized.
-- [Tokens](/en/discover/core-concepts/tokens) — what users receive after login.
-- [Authentication](/en/discover/core-concepts/authentication) — the full chain that ties it together.
+- [Realms](/en/discover/core-concepts/realms): the boundary a user lives in.
+- [Clients](/en/discover/core-concepts/clients): what users authenticate through.
+- [Credentials](/en/discover/core-concepts/credentials): how users prove identity.
+- [Roles](/en/discover/core-concepts/roles): how users get authorized.
+- [Tokens](/en/discover/core-concepts/tokens): what users receive after login.
+- [Authentication](/en/discover/core-concepts/authentication): the chain that ties it together.
diff --git a/apps/docs/src/content/docs/discover/default/en/getting-started.mdx b/apps/docs/src/content/docs/discover/default/en/getting-started.mdx
index a4ed028..af6d470 100644
--- a/apps/docs/src/content/docs/discover/default/en/getting-started.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/getting-started.mdx
@@ -7,7 +7,7 @@ order: 2
 
 # Getting Started
 
-This guide gets you to a working FerrisKey instance with your first authenticated user. You will start the Docker stack, create a realm, register a client, create a user, and request tokens.
+This guide takes you from nothing to a working FerrisKey instance with an authenticated user. You will start the Docker stack, create a realm, register a client, create a user, and request tokens.
 
 ## Prerequisites
 
@@ -46,7 +46,7 @@ Open `http://localhost:5555` in your browser and sign in with the default creden
 - **Username:** `admin`
 - **Password:** `admin`
 
-You'll land in the **master** realm, the built-in realm that manages all other realms.
+You land in the `master` realm, the built-in realm that manages all the others.
 :::
 ::::
 
@@ -54,9 +54,9 @@ You'll land in the **master** realm, the built-in realm that manages all other r
 The default admin credentials are for local development only. Change them immediately in any non-local environment by setting the `ADMIN_USERNAME`, `ADMIN_PASSWORD`, and `ADMIN_EMAIL` environment variables.
 :::
 
-## Deploy Without Cloning the Repository
+## Deploy without cloning the repository
 
-The quickstart above clones the repository, but you don't need the source code to run FerrisKey. The API, web app, and database migrations all ship as published images on `ghcr.io/ferriskey`. To deploy on a server, save the following as `docker-compose.yml` and start it directly — no checkout required:
+The quickstart above clones the repository, but you don't need the source to run FerrisKey. The API, web app, and database migrations all ship as published images on `ghcr.io/ferriskey`. To deploy on a server, save the following as `docker-compose.yml` and start it directly, with no checkout involved:
 
 ```yaml title="docker-compose.yml"
 services:
@@ -122,12 +122,39 @@ docker compose up -d
 The migration files are baked into the `ferriskey-api` image (under `/usr/local/src/ferriskey/migrations`), so the `db-migrations` service applies the schema without any checked-out source. These are the same images the repository's `registry` profile uses, extracted into a self-contained file you can drop onto any host or convert to a Docker Swarm stack.
 
 :::callout{variant="info" title="Pin a version for production"}
-The images above track the latest tag. For reproducible deployments, pin an explicit tag — for example `ghcr.io/ferriskey/ferriskey-api:vX.Y.Z` — on both the `api` and `db-migrations` services so they always run the same binary and schema.
+The images above track the latest tag. For reproducible deployments, pin an explicit tag (for example `ghcr.io/ferriskey/ferriskey-api:v0.7.0`) on both the `api` and `db-migrations` services, so they always run the same binary and schema.
 :::
 
+## Run everything in one container
+
+There is a third image, `ghcr.io/ferriskey/ferriskey-standalone`, that bundles the API and the web app behind a single nginx process. It is the quickest way to get an instance up on one host, and it is what the repository's `standalone` profile starts:
+
+```bash
+docker compose --profile standalone-registry up -d
+```
+
+Everything is served from `http://localhost:8090`, with the API mounted under `/api`:
+
+```yaml title="Standalone service"
+standalone:
+  image: ghcr.io/ferriskey/ferriskey-standalone
+  environment:
+    DATABASE_HOST: db
+    DATABASE_NAME: ferriskey
+    DATABASE_USER: ferriskey
+    DATABASE_PASSWORD: ferriskey
+    SERVER_ROOT_PATH: /api
+    ALLOWED_ORIGINS: http://localhost:8090
+    WEBAPP_URL: http://localhost:8090
+  ports:
+    - 8090:80
+```
+
+The standalone image runs its own migrations at startup, so there is no separate migration service. It still needs an external PostgreSQL.
+
 ## Upgrading FerrisKey
 
-Schema changes ship inside the API image, so upgrading a running stack is "pull, migrate, restart":
+Schema changes ship inside the API image, so upgrading a running stack means pull, migrate, restart.
 
 ::::step-group
 :::step{title="Pull the new images"}
@@ -137,7 +164,7 @@ docker compose pull
 :::
 
 :::step{title="Apply new migrations"}
-The `db-migrations` service runs `sqlx migrate run`, which only applies migrations that have not run yet — so it is safe to run on every upgrade:
+The `db-migrations` service runs `sqlx migrate run`, which only applies migrations that have not run yet, so it is safe on every upgrade:
 
 ```bash
 docker compose up -d db-migrations
@@ -154,10 +181,10 @@ docker compose up -d api webapp
 ::::
 
 :::callout{variant="warning" title="Keep api and migrations on the same tag"}
-Always pull the `api` and `db-migrations` services from the **same image tag**. Running a newer API against an older schema — or an older API against a newer schema — can fail at startup.
+Always pull the `api` and `db-migrations` services from the same image tag. A newer API against an older schema, or an older API against a newer one, can fail at startup.
 :::
 
-## Create Your First Realm
+## Create your first realm
 
 A realm is an isolated tenant. Users, clients, roles, and credentials all live inside a realm.
 
@@ -171,7 +198,7 @@ Use the realm selector in the sidebar to switch to `my-app`. All subsequent oper
 :::
 ::::
 
-## Register a Client
+## Register a client
 
 A client represents an application that uses FerrisKey for authentication.
 
@@ -191,7 +218,7 @@ If you want to test authentication directly via the API (password grant), enable
 :::
 ::::
 
-## Create a User
+## Create a user
 
 ::::step-group
 :::step{title="Create a user"}
@@ -223,15 +250,15 @@ curl -X POST http://localhost:3333/realms/my-app/protocol/openid-connect/token \
   -d "password=your-password"
 ```
 
-The response contains an `access_token`, `refresh_token`, and optionally an `id_token`. That means the user authenticated successfully.
+A response containing an `access_token`, a `refresh_token`, and optionally an `id_token` means the user authenticated.
 
-## Connect a Real Application
+## Connect a real application
 
-The password grant above is useful for a quick API test. For real applications, use browser-based SSO with the OpenID Connect authorization code flow.
+The password grant above is fine for a quick API test. Real applications should use browser-based SSO with the OpenID Connect authorization code flow.
 
-If you want to connect a dashboard, internal service, or self-hosted tool, follow the application SSO guide next. It shows which dashboard screens to use, what values to copy, and how to debug common setup mistakes.
+To connect a dashboard, an internal service, or a self-hosted tool, follow the application SSO guide next. It walks through which console screens to use, what values to copy, and how to debug the usual setup mistakes.
 
-## What's Next?
+## What's next?
 
 ::::card-group{cols=2}
 :::card{label="Core Concepts" icon="lucide:layers" href="/en/discover/core-concepts/realms"}
diff --git a/apps/docs/src/content/docs/discover/default/en/guides/application-sso.mdx b/apps/docs/src/content/docs/discover/default/en/guides/application-sso.mdx
index 368882a..ad349ce 100644
--- a/apps/docs/src/content/docs/discover/default/en/guides/application-sso.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/guides/application-sso.mdx
@@ -7,9 +7,9 @@ order: 19
 
 # Connect an Application with SSO
 
-Use this guide when an application supports OpenID Connect and you want FerrisKey to handle sign-in.
+Use this guide when an application speaks OpenID Connect and you want FerrisKey to handle sign-in.
 
-By the end, you will have:
+By the end you will have:
 
 - One FerrisKey realm dedicated to the application or organization
 - One OpenID Connect client
@@ -17,7 +17,7 @@ By the end, you will have:
 - The redirect URI registered in FerrisKey
 - The issuer URL and discovery endpoint your application needs
 
-## Before You Start
+## Before you start
 
 Before opening FerrisKey, find these values in the application you want to connect:
 
@@ -31,7 +31,7 @@ Before opening FerrisKey, find these values in the application you want to conne
 The redirect URI must match what the application sends during login. If the application says the callback is `/identity/connect/oidc-signin`, do not replace it with the application homepage.
 :::
 
-## Example Values
+## Example values
 
 The walkthrough uses these values. Replace them with your own domains and realm name.
 
@@ -44,7 +44,7 @@ The walkthrough uses these values. Replace them with your own domains and realm
 | Redirect URI | `https://vault.example.com/identity/connect/oidc-signin` |
 | Scopes | `openid profile email` |
 
-## Create or Select the Realm
+## Create or select the realm
 
 A realm keeps users, clients, roles, and scopes together. Avoid using `master` for applications.
 
@@ -60,7 +60,7 @@ After switching, check the realm indicator before creating the client. The clien
 :::
 ::::
 
-## Create the Client
+## Create the client
 
 The client is the application entry in FerrisKey. It tells FerrisKey which app is asking users to sign in.
 
@@ -85,7 +85,7 @@ Enable **Client Authentication** for server-side applications. FerrisKey will tr
 :::
 ::::
 
-## Configure the Redirect URI
+## Configure the redirect URI
 
 The redirect URI is where FerrisKey sends the browser after a successful login.
 
@@ -109,7 +109,7 @@ Keep **Direct Access Grants** disabled unless the application explicitly asks fo
 :::
 ::::
 
-## Copy the Client Secret
+## Copy the client secret
 
 ::::step-group
 :::step{title="Open Credentials"}
@@ -127,7 +127,7 @@ Copy the **Client Secret** and put it in the application's OIDC configuration. T
 If a client secret is pasted into a public issue, log, screenshot, or repository, rotate it and update the application immediately.
 :::
 
-## Check the Client Scopes
+## Check the client scopes
 
 Most OIDC applications need `openid`, `profile`, and `email`.
 
@@ -149,7 +149,7 @@ If the application needs roles, also assign `roles`.
 :::
 ::::
 
-## Configure the Application
+## Configure the application
 
 Paste these values into the application.
 
@@ -162,9 +162,9 @@ Paste these values into the application.
 | Scopes | `openid profile email` |
 | Redirect URI | `https://vault.example.com/identity/connect/oidc-signin` |
 
-### What the Discovery Endpoint Does
+### What the discovery endpoint does
 
-The discovery endpoint is the URL an OpenID Connect application uses to learn how to talk to FerrisKey.
+The discovery endpoint is where an OpenID Connect application learns how to talk to FerrisKey.
 
 ```text
 https://sso.example.com/realms/home/.well-known/openid-configuration
@@ -178,13 +178,13 @@ When the application opens that URL, FerrisKey returns a JSON document with the
 - Where to fetch the public keys used to verify token signatures
 - Which scopes and response types are supported
 
-This is why many applications only ask for an **issuer**, **authority**, or **discovery URL** instead of asking you to configure every endpoint manually.
+That is why so many applications only ask for an issuer, an authority, or a discovery URL, instead of making you fill in every endpoint by hand.
 
-:::callout{variant="info" title="Authority vs discovery endpoint"}
-Some applications ask for the issuer or authority URL. Others ask directly for the discovery endpoint. If the application asks for the authority, usually use the realm URL without `/.well-known/openid-configuration`.
+:::callout{variant="info" title="Authority or discovery endpoint"}
+Some applications ask for the issuer or authority URL, others for the discovery endpoint. When it asks for the authority, give it the realm URL without the `/.well-known/openid-configuration` suffix.
 :::
 
-## Test the Login
+## Test the login
 
 1. Open the application in a private browser window.
 2. Click the SSO or OpenID Connect login button.
@@ -192,7 +192,7 @@ Some applications ask for the issuer or authority URL. Others ask directly for t
 4. Sign in with a user from the same realm.
 5. Confirm that FerrisKey redirects back to the application.
 
-If the user can sign in but the application says the account is not allowed, check the application's own signup, domain, group, or role rules. FerrisKey has authenticated the user, but the application can still decide whether that user may enter.
+If the user signs in but the application says the account is not allowed, look at the application's own signup, domain, group, or role rules. FerrisKey authenticated the user; the application still gets to decide whether that user is welcome.
 
 ## Troubleshooting
 
diff --git a/apps/docs/src/content/docs/discover/default/en/guides/architecture.mdx b/apps/docs/src/content/docs/discover/default/en/guides/architecture.mdx
index 4c7efb7..c9125ec 100644
--- a/apps/docs/src/content/docs/discover/default/en/guides/architecture.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/guides/architecture.mdx
@@ -7,7 +7,7 @@ order: 22
 
 # Architecture
 
-FerrisKey follows a **hexagonal architecture** (ports & adapters) that cleanly separates business logic from infrastructure. This design makes the system testable, modular, and resilient to change.
+FerrisKey follows a hexagonal architecture, also called ports and adapters. Business logic sits in the middle and knows nothing about HTTP, SQL, or SMTP. Everything else plugs into it. That is what keeps the domain testable and lets infrastructure change without rewriting rules.
 
 ## Layers
 
@@ -28,73 +28,101 @@ graph TD
     APP --> INF
 ```
 
-### Domain Layer
+### Domain layer
 
-The core of FerrisKey. Contains pure business logic with no dependencies on frameworks, databases, or HTTP. Each domain module defines:
+Pure business logic, with no dependency on a framework, a database, or a transport. Each domain module is laid out the same way:
 
-- **Entities**: Immutable value objects representing domain concepts
-- **Ports**: Trait definitions (interfaces) that declare what the domain needs
-- **Services**: Business logic that operates on entities through ports
-- **Value Objects**: DTOs for use cases and data transfer
-- **Policies**: Authorization rules
+- `entities.rs` for the immutable value objects that represent domain concepts
+- `ports.rs` for the traits the domain needs someone else to implement
+- `services.rs` for the logic that operates on entities through those ports
+- `value_objects.rs` for the use case inputs and outputs
+- `policies.rs` for authorization rules, where a module has them
 
-### Application Layer
+### Application layer
 
-Orchestrates domain services. The `ApplicationService` struct wires together all domain services with their concrete implementations through dependency injection.
+Orchestration. `ApplicationService` wires every domain service to a concrete implementation through dependency injection, and is the single place where the object graph is assembled.
 
-### Infrastructure Layer
+### Infrastructure layer
 
-Implements the ports defined by the domain:
+The implementations behind the ports: repositories backed by SeaORM and PostgreSQL, plus the outbound integrations for SMTP, webhook delivery, and identity provider calls.
 
-- **Repositories**: Database access via SeaORM (PostgreSQL)
-- **External services**: SMTP, webhook delivery, identity provider communication
+### API layer
 
-### API Layer
+The HTTP surface, built with Axum. Each feature mirrors a domain module and brings its own router, handlers, validators, and error types. OpenAPI documentation is generated from `utoipa` attributes on the handlers and served at `/swagger-ui`, `/redoc`, `/rapidoc`, and `/scalar`.
 
-HTTP interface built with Axum. Each feature mirrors a domain module with its own router, handlers, validators, and error types. OpenAPI documentation is generated automatically via `utoipa`.
-
-## Domain Modules
+## Domain modules
 
 ```
 core/src/domain/
-├── authentication/    # OAuth2/OIDC flows
-├── user/             # User lifecycle
-├── client/           # OAuth2 clients
-├── realm/            # Multi-tenant realms
-├── credential/       # Password, OTP, WebAuthn
-├── role/             # Bitwise permissions
-├── session/          # User sessions
-├── jwt/              # Token generation & validation
-├── seawatch/         # Audit logging
-├── abyss/            # Identity provider federation
-└── webhook/          # Event-driven hooks
+├── authentication/       # OAuth2 / OIDC flows
+├── user/                 # User lifecycle and required actions
+├── account/              # Self-service account operations
+├── client/               # OAuth2 clients
+├── realm/                # Multi-tenant realms and settings
+├── credential/           # Passwords, OTP, WebAuthn
+├── password_policy/      # Password strength rules
+├── role/                 # Bitwise permissions
+├── session/              # User and auth sessions
+├── jwt/                  # Token issuance and validation
+├── crypto/               # Key material and signing
+├── saml/                 # SAML 2.0 identity provider
+├── trident/              # MFA
+├── seawatch/             # Audit logging
+├── compass/              # Authentication flow recording
+├── abyss/                # Identity provider federation
+├── aegis/                # Client scopes and protocol mappers
+├── organization/         # B2B tenancy
+├── email_template/       # Transactional email templates
+├── email_verification/   # Email verification flow
+├── portal_theme/         # Login portal theming
+├── portal_layouts/       # Login portal layouts
+├── webhook/              # Event-driven hooks
+├── health/               # Liveness and readiness
+└── maintenance/          # Maintenance mode
 ```
 
-Standalone library crates extend the core:
+## Workspace crates
+
+The workspace is being pulled apart into focused crates. Two families live under `libs/`.
+
+Feature crates hold domain and infrastructure logic for one module:
 
 ```
 libs/
-├── ferriskey-domain/     # Shared domain types (Realm, Client, User, Token)
-├── ferriskey-trident/    # MFA (TOTP, WebAuthn, magic links, recovery codes)
-├── ferriskey-compass/    # Authentication flow engine
-└── ferriskey-aegis/      # Client scopes & protocol mappers
+├── ferriskey-domain/           # Shared domain types
+├── ferriskey-security/         # Hashing and crypto primitives
+├── ferriskey-trident/          # MFA
+├── ferriskey-abyss/            # Identity provider federation
+├── ferriskey-aegis/            # Scopes and protocol mappers
+├── ferriskey-compass/          # Authentication flow engine
+├── ferriskey-saml/             # SAML 2.0
+├── ferriskey-seawatch/         # Audit events
+├── ferriskey-organization/     # Organizations
+├── ferriskey-password-policy/  # Password policies
+├── ferriskey-portal-theme/     # Portal theming
+├── ferriskey-portal-layouts/   # Portal layouts
+├── ferriskey-webhook/          # Webhook delivery
+├── ferriskey-mail/             # SMTP transport
+└── ferriskey-migrate/          # Migration runner
 ```
 
-## Dependency Flow
+`ferriskey-api-*` crates carry the HTTP layer for the matching feature, so a module's routes and handlers can move out of the monolithic API crate one at a time. `ferriskey-api-core` holds the shared pieces: CLI arguments, application state, and error conversion.
+
+## Dependency flow
 
-The dependency rule is strict: **inner layers never depend on outer layers**.
+The rule is strict: inner layers never depend on outer layers.
 
-- Domain depends on nothing
-- Application depends on domain (uses ports/traits)
-- Infrastructure implements domain ports
-- API depends on application
+- The domain depends on nothing
+- The application depends on the domain, through ports
+- The infrastructure implements the domain's ports
+- The API depends on the application
 
-This means you can swap PostgreSQL for another database, replace Axum with a different HTTP framework, or test domain logic entirely in memory, without touching business rules.
+Which means you can swap PostgreSQL for another store, replace Axum with a different HTTP framework, or run domain tests entirely in memory, without touching a business rule.
 
-## Error Propagation
+## Error propagation
 
-Errors flow outward through automatic conversions:
+Errors travel outward through automatic conversions:
 
-1. **`CoreError`**: Domain-level errors (not found, validation, conflict)
-2. **`ApiError`**: HTTP response format with status codes
-3. **`From<CoreError> for ApiError`**: Automatic conversion at the boundary
+1. `CoreError` for domain failures: not found, validation, conflict.
+2. `ApiError` for the HTTP response, with a status code attached.
+3. `From<CoreError> for ApiError` at the boundary, so handlers can use `?` and get the right status for free.
diff --git a/apps/docs/src/content/docs/discover/default/en/guides/configuration.mdx b/apps/docs/src/content/docs/discover/default/en/guides/configuration.mdx
index 5547dd3..4817c2b 100644
--- a/apps/docs/src/content/docs/discover/default/en/guides/configuration.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/guides/configuration.mdx
@@ -7,12 +7,16 @@ order: 20
 
 # Configuration
 
-FerrisKey is configured through environment variables. Every setting has a sensible default for local development, override only what you need.
+The FerrisKey API is configured entirely through command-line flags, each of which has a matching environment variable. Every setting has a default that works for local development, so you only override what your deployment needs.
 
-## Environment Variables
+Run `ferriskey-api --help` to see the flags and their long descriptions straight from the binary.
+
+## Environment variables
 
 ### Admin
 
+The admin account is created on first boot in the `master` realm.
+
 | Variable | Default | Description |
 |---|---|---|
 | `ADMIN_USERNAME` | `admin` | Initial admin username |
@@ -36,29 +40,57 @@ FerrisKey is configured through environment variables. Every setting has a sensi
 |---|---|---|
 | `SERVER_HOST` | `0.0.0.0` | Bind address |
 | `SERVER_PORT` | `3333` | HTTP port |
-| `SERVER_ROOT_PATH` | None | URL path prefix (for reverse proxies) |
-| `ALLOWED_ORIGINS` | None | Comma-separated CORS origins |
-| `WEBAPP_URL` | None | Frontend URL (used for redirects) |
+| `SERVER_ROOT_PATH` | empty | URL path prefix, for deployments behind a reverse proxy. A leading `/` is added if you omit it |
+| `SERVER_PUBLIC_URL` | unset | The origin browsers and service providers reach this deployment at, as `scheme://host[:port]` |
+| `ALLOWED_ORIGINS` | empty | Comma-separated browser origins allowed on every route |
+| `WEBAPP_URL` | `http://localhost:5555` | URL of the admin console, used when building links |
+| `ENV` | `development` | Deprecated. Kept for compatibility and ignored by new code |
+
+`ALLOWED_ORIGINS` deserves a note of its own. Each entry must be a serialized origin (`scheme://host[:port]`), with no path and no wildcard. It applies to every route, including the ones that carry no realm: `/config`, the health probes, and the API documentation. Clients also declare their own web origins per realm, but those only cover realm-scoped routes, so a console served from a different origin than the API still needs its origin listed here.
+
+:::callout{variant="warning" title="SERVER_PUBLIC_URL and SAML"}
+Leave `SERVER_PUBLIC_URL` unset and FerrisKey derives the public origin from each request's `Host` header, which is the historical behaviour. SAML needs it set: the entity id is signed into every assertion, so it must not change when a request arrives through a different hostname.
+:::
 
 ### TLS
 
+Both variables are required together. Set neither to serve plain HTTP and terminate TLS at your proxy.
+
 | Variable | Default | Description |
 |---|---|---|
-| `TLS_CERT_PATH` | None | Path to TLS certificate |
-| `TLS_KEY_PATH` | None | Path to TLS private key |
+| `SERVER_TLS_CERT` | unset | Path to the certificate file, in PEM format |
+| `SERVER_TLS_KEY` | unset | Path to the private key file, in PEM format |
 
 ### Logging
 
 | Variable | Default | Description |
 |---|---|---|
-| `LOG_FILTER` | `info` | Log level filter (trace, debug, info, warn, error) |
-| `LOG_JSON` | `false` | Output logs in JSON format |
+| `LOG_FILTER` | `info` | [`EnvFilter`](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives) directives, for example `info,ferriskey_core=debug` |
+| `LOG_JSON` | `false` | Emit structured JSON logs instead of human-readable lines |
 
-## Deployment Examples
+### Observability
 
-### Docker Compose
+| Variable | Default | Description |
+|---|---|---|
+| `ACTIVE_OBSERVABILITY` | `false` | Turn on tracing and metrics export |
+| `OTLP_ENDPOINT` | unset | OTLP collector endpoint for traces |
+| `METRICS_ENDPOINT` | unset | Collector endpoint for metrics |
+
+Prometheus metrics are also exposed directly on `/metrics`, with no collector needed.
 
-Configure FerrisKey by setting environment variables in your `docker-compose.yaml`:
+## Generating the OpenAPI spec
+
+The API binary carries a subcommand that prints its OpenAPI document without touching the database:
+
+```bash
+ferriskey-api gen-api --output openapi.json
+```
+
+Omit `--output` to write the spec to stdout.
+
+## Deployment examples
+
+### Docker Compose
 
 ```yaml title="docker-compose.override.yaml"
 services:
@@ -73,12 +105,13 @@ services:
       - ADMIN_PASSWORD=a-strong-admin-password
       - ADMIN_EMAIL=admin@yourorg.com
       - ALLOWED_ORIGINS=https://iam.yourorg.com
+      - WEBAPP_URL=https://iam.yourorg.com
       - LOG_FILTER=info
 ```
 
-### Bare Metal
+### Bare metal
 
-Set environment variables directly or use a `.env` file alongside the binary:
+Set the variables directly, or drop a `.env` file next to the binary:
 
 ```bash title=".env"
 DATABASE_HOST=localhost
@@ -90,25 +123,21 @@ ADMIN_USERNAME=admin
 ADMIN_PASSWORD=a-strong-admin-password
 ADMIN_EMAIL=admin@yourorg.com
 ALLOWED_ORIGINS=https://iam.yourorg.com
+WEBAPP_URL=https://iam.yourorg.com
 SERVER_PORT=3333
 LOG_FILTER=info
 ```
 
-Then run the API server:
+Then run the server:
 
 ```bash
 ./ferriskey-api
 ```
 
-## SMTP Configuration
-
-Email delivery (magic links, password reset, email verification) is configured per-realm through the admin console. Navigate to **Realm Settings → Email** and configure:
+## SMTP configuration
 
-- **SMTP Host** and **Port**
-- **From address**
-- **Authentication credentials** (if required)
-- **TLS/STARTTLS** settings
+Email delivery for magic links, password resets, and email verification is configured per realm, in the database, not through environment variables. Open the admin console, go to **Realm Settings → Email**, and fill in the host, port, sender address, credentials, and encryption mode.
 
 :::callout{variant="info" title="No global SMTP"}
-SMTP is configured at the realm level, not globally. Each realm can use a different mail provider.
+Every realm carries its own SMTP configuration and can point at a different mail provider. The [Email & Templates guide](/en/discover/guides/email) has the full field reference and the API endpoints.
 :::
diff --git a/apps/docs/src/content/docs/discover/default/en/guides/contributing.mdx b/apps/docs/src/content/docs/discover/default/en/guides/contributing.mdx
index c8e29a4..8275310 100644
--- a/apps/docs/src/content/docs/discover/default/en/guides/contributing.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/guides/contributing.mdx
@@ -7,11 +7,11 @@ order: 23
 
 # Contributing
 
-FerrisKey is open source and welcomes contributions of every size: bug reports, documentation fixes, examples, tests, design feedback, and code changes.
+FerrisKey is open source and takes contributions of every size: bug reports, documentation fixes, examples, tests, design feedback, and code changes.
 
-The main rule is simple: **keep pull requests small and reviewable**. A contribution should be easy to understand, test, and merge without forcing maintainers to review unrelated layers at the same time.
+One rule matters more than the rest: keep pull requests small and reviewable. A contribution should be easy to understand, test, and merge, without forcing a maintainer to review four unrelated layers in one sitting.
 
-## Before You Start
+## Before you start
 
 - Check the [GitHub repository](https://github.com/ferriskey/ferriskey) for existing issues or pull requests related to your change.
 - Open an issue first for large features, architecture changes, security-sensitive behavior, or breaking changes.
@@ -22,7 +22,7 @@ The main rule is simple: **keep pull requests small and reviewable**. A contribu
 Do not report vulnerabilities in public issues. Use the repository's private security reporting flow when available, or contact the maintainers before sharing exploit details.
 :::
 
-## Contribution Process
+## Contribution process
 
 Every pull request must have a reduced scope. Avoid submitting one large PR that changes every layer of the product at once.
 
@@ -50,7 +50,7 @@ Each PR should stand on its own when possible. If a PR depends on a previous one
 Maintainers may ask you to split a pull request before reviewing it. This is not about blocking the contribution; it keeps review quality high and reduces the chance of regressions.
 :::
 
-## How to Split a Change
+## How to split a change
 
 Use these rules when deciding what belongs in the same PR:
 
@@ -70,13 +70,13 @@ Good PR descriptions include:
 - How the change was tested.
 - Screenshots or recordings for visible UI changes.
 
-## Set Up the Documentation Website
+## Set up the documentation website
 
-The documentation, website, and blog live in a pnpm workspace.
+The documentation, marketing site, and blog live in their own repository, [`ferriskey/website`](https://github.com/ferriskey/website), as a pnpm workspace driven by Turborepo. The Rust code stays in [`ferriskey/ferriskey`](https://github.com/ferriskey/ferriskey).
 
 ```bash title="Clone and install"
-git clone https://github.com/ferriskey/ferriskey.git
-cd ferriskey
+git clone https://github.com/ferriskey/website.git
+cd website
 pnpm install --frozen-lockfile
 ```
 
@@ -103,9 +103,9 @@ order: 10
 ---
 ```
 
-## Writing Documentation
+## Writing documentation
 
-Good documentation should help readers complete a task or understand a concept without guessing.
+Good documentation helps a reader finish a task or understand a concept without guessing.
 
 - Start with the outcome the reader wants.
 - Use concrete examples, URLs, environment variables, and commands.
@@ -122,13 +122,13 @@ apps/docs/src/content/docs/discover/default/en/guides/
 
 Navigation order is controlled by the `order` field in page frontmatter and by `_meta.json` files for groups.
 
-## Code Contributions
+## Code contributions
 
-Before changing code, read the nearby implementation and follow the existing patterns. FerrisKey uses a modular architecture: domain logic, infrastructure, API boundaries, and documentation should stay separated.
+Before changing code, read the surrounding implementation and follow the patterns already there. FerrisKey is modular by design: domain logic, infrastructure, API boundaries, and documentation stay separate.
 
 For user-facing changes, update the relevant docs in the same pull request. For bug fixes, add or update tests when the behavior can regress.
 
-## Validate Your Changes
+## Validate your changes
 
 Run formatting before opening a pull request:
 
@@ -148,7 +148,7 @@ For documentation-only changes, you can also build only the docs app:
 pnpm --filter @explainer/docs build
 ```
 
-## Pull Request Checklist
+## Pull request checklist
 
 Before requesting review, check that:
 
@@ -159,9 +159,9 @@ Before requesting review, check that:
 - Formatting and build commands pass locally.
 - The PR does not include unrelated rewrites, generated noise, or local environment files.
 
-## Review Process
+## Review process
 
-Maintainers review for correctness, maintainability, security, and consistency with FerrisKey's direction. Expect questions and requested changes, especially for public APIs, authentication flows, deployment behavior, and documentation that affects production usage.
+Maintainers review for correctness, maintainability, security, and fit with where FerrisKey is going. Expect questions and requested changes, particularly on public APIs, authentication flows, deployment behavior, and documentation people will follow in production.
 
 When feedback arrives:
 
@@ -170,6 +170,6 @@ When feedback arrives:
 - Keep the conversation focused on the technical decision.
 - Ask for another review when the PR is ready.
 
-## Community Standards
+## Community standards
 
-Be direct, respectful, and specific. Assume contributors are trying to improve the project, and keep discussions grounded in reproducible behavior, code, documentation, or user impact.
+Be direct, respectful, and specific. Assume the person on the other side is trying to improve the project, and keep the discussion anchored in reproducible behavior, code, documentation, or user impact.
diff --git a/apps/docs/src/content/docs/discover/default/en/guides/email.mdx b/apps/docs/src/content/docs/discover/default/en/guides/email.mdx
index 8a7bf34..abb29dd 100644
--- a/apps/docs/src/content/docs/discover/default/en/guides/email.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/guides/email.mdx
@@ -7,24 +7,24 @@ order: 21
 
 # Email & Templates
 
-FerrisKey sends transactional emails for password resets, magic link authentication, and email verification. Delivery is configured per realm through a dedicated SMTP setup, and each email type can be customized with your own HTML template.
+FerrisKey sends transactional email for password resets, magic link sign-in, and email verification. Delivery is configured per realm, and each email type can be pointed at a template of your own.
 
 ## Configure SMTP
 
-SMTP is stored in the database at the realm level — not as a global environment variable. Each realm can use a different mail provider independently.
+SMTP settings live in the database, on the realm, not in a global environment variable. Two realms in the same deployment can use completely different mail providers.
 
 :::callout{variant="info" title="No global SMTP"}
 SMTP is configured per realm, not globally. See the [Configuration guide](/en/discover/guides/configuration) for the short overview. This page covers the full field reference and API.
 :::
 
-### SMTP Fields
+### SMTP fields
 
 | Field | Type | Notes |
 |---|---|---|
 | `host` | String | SMTP server hostname |
 | `port` | u16 | Port number (1–65535) |
 | `username` | String | SMTP authentication username |
-| `password` | String | SMTP authentication password — write-only, never returned by the API |
+| `password` | String | SMTP authentication password. Write-only: the API never returns it |
 | `from_email` | String | Sender address, must be a valid email |
 | `from_name` | String | Sender display name |
 | `encryption` | Enum | `tls` \| `starttls` \| `none` |
@@ -33,11 +33,11 @@ SMTP is configured per realm, not globally. See the [Configuration guide](/en/di
 
 | Mode | Port | When to use |
 |---|---|---|
-| `tls` | 465 | Implicit TLS from the first byte — preferred for modern providers |
-| `starttls` | 587 | Plain connection upgraded to TLS — common in corporate relays |
-| `none` | 25 / any | No encryption — use only on a trusted local network or for testing |
+| `tls` | 465 | Implicit TLS from the first byte. What most modern providers want |
+| `starttls` | 587 | Plain connection upgraded to TLS. Common on corporate relays |
+| `none` | 25 / any | No encryption. Only on a trusted local network, or for testing |
 
-### SMTP API Endpoints
+### SMTP API endpoints
 
 All endpoints are scoped to a realm and require authentication.
 
@@ -47,9 +47,9 @@ All endpoints are scoped to a realm and require authentication.
 | `PUT` | `/realms/{realm_name}/smtp-config` | Create or replace the config |
 | `DELETE` | `/realms/{realm_name}/smtp-config` | Remove the config |
 
-**Required permissions:** reading SMTP config requires view access to the realm. Creating, updating, or deleting requires `ManageRealm`. There are no dedicated SMTP permissions beyond the realm permission gates.
+**Required permissions:** reading the SMTP config requires view access to the realm. Creating, updating, or deleting it requires `ManageRealm`. There are no SMTP-specific permissions beyond the realm gates.
 
-### Configure SMTP in the Console
+### Configure SMTP in the console
 
 ::::step-group
 :::step{title="Open Realm Settings"}
@@ -84,9 +84,9 @@ The API never returns the SMTP password. If you need to rotate credentials, subm
 
 ---
 
-## Transactional Emails
+## Transactional emails
 
-FerrisKey sends exactly three types of transactional email. Each is tied to a realm feature toggle.
+There are three types of transactional email, each gated by a realm toggle.
 
 | Email type | Identifier | Sent when | Realm toggle required |
 |---|---|---|---|
@@ -94,29 +94,29 @@ FerrisKey sends exactly three types of transactional email. Each is tied to a re
 | Magic link | `magic_link` | A user requests passwordless email login | `magic_link_enabled` |
 | Email verification | `email_verification` | A user must verify their email address | `email_verification_enabled` |
 
-Enabling these toggles in Realm Settings activates the corresponding flow. FerrisKey will use the default built-in template unless you assign a custom one.
+Turning a toggle on in Realm Settings activates the matching flow. Until you assign a template of your own, FerrisKey uses the built-in default.
 
 ---
 
-## Customizing Templates
+## Customizing templates
 
-### Template Engine
+### Template engine
 
-FerrisKey uses a lightweight custom interpolation engine — not Handlebars or Tera. Placeholders use double-brace syntax:
+Templates are rendered by a small interpolation engine written for the purpose, not Handlebars or Tera. Placeholders use double braces:
 
 ```text
 {{variable_name}}
 ```
 
-All interpolated values are HTML-escaped before insertion (`&`, `<`, `>`, `"`, `'`), which prevents injection attacks in the rendered email.
+Every interpolated value is HTML-escaped before insertion (`&`, `<`, `>`, `"`, `'`), so a template cannot be turned into an injection vector.
 
 :::callout{variant="info" title="HTML escaping"}
-Values inserted via `{{...}}` are always HTML-escaped. If a user's name is `Alice <script>`, it renders as `Alice &lt;script&gt;` in the final email — safe to embed in HTML.
+Values inserted via `{{...}}` are always HTML-escaped. If a user's name is `Alice <script>`, it renders as `Alice &lt;script&gt;` in the final email, safe to embed in HTML.
 :::
 
 Templates are stored as a JSON `structure` that FerrisKey renders to MJML and then to HTML before sending.
 
-### Available Variables
+### Available variables
 
 These variables are available in every template:
 
@@ -157,7 +157,7 @@ Example response for `reset_password`:
 }
 ```
 
-### Template API Endpoints
+### Template API endpoints
 
 | Method | Path | Description |
 |---|---|---|
@@ -173,9 +173,9 @@ Example response for `reset_password`:
 
 **Required permissions:** `ViewEmailTemplates` to read. `ManageEmailTemplates` to create, update, or delete. `ManageRealm` also grants both.
 
-### Linking a Template to an Email Type
+### Linking a template to an email type
 
-Creating a template does not activate it automatically. You must link it to the realm by updating the realm settings:
+Creating a template does not activate it. Point the realm at it by updating realm settings:
 
 | Realm setting field | Applies to |
 |---|---|
diff --git a/apps/docs/src/content/docs/discover/default/en/what-is-ferriskey.mdx b/apps/docs/src/content/docs/discover/default/en/what-is-ferriskey.mdx
index 44c92c5..60b3d8c 100644
--- a/apps/docs/src/content/docs/discover/default/en/what-is-ferriskey.mdx
+++ b/apps/docs/src/content/docs/discover/default/en/what-is-ferriskey.mdx
@@ -7,29 +7,29 @@ order: 1
 
 # What is FerrisKey?
 
-FerrisKey is a modern, open-source Identity & Access Management (IAM) system built in Rust. It gives your applications authentication, authorization, and user management without the weight of legacy IAM platforms.
+FerrisKey is an open-source Identity & Access Management (IAM) system written in Rust. It handles authentication, authorization, and user management for your applications, without the operational weight of the older IAM platforms.
 
 ## What is IAM?
 
-Identity & Access Management answers two questions for every request your system receives:
+Identity & Access Management answers two questions about every request your system receives:
 
-- **Authentication**: _Who are you?_ Verifying identity through passwords, multi-factor authentication, passkeys, or federated providers.
-- **Authorization**: _What can you do?_ Determining which resources and actions an authenticated identity is permitted to access.
+- **Authentication**: who are you? Verified through passwords, multi-factor challenges, passkeys, or a federated provider.
+- **Authorization**: what are you allowed to do? Which resources and actions the authenticated identity can reach.
 
-Beyond these fundamentals, a modern IAM system handles token issuance (JWT), single sign-on (SSO), session management, audit logging, and integration with external identity providers.
+On top of those two, an IAM system issues and validates JWTs, ties applications together with single sign-on, tracks sessions, records an audit trail, and talks to external identity providers.
 
 ## Why FerrisKey?
 
-FerrisKey was built from scratch in Rust for teams that want a clear, modern IAM system:
+FerrisKey was written from scratch for teams who want an IAM they can actually read and reason about.
 
-- **Performance & Safety**: Rust gives FerrisKey a fast, reliable foundation with strong memory safety.
-- **Multi-Tenancy**: Realms isolate users, clients, roles, credentials, and configuration so one deployment can serve many organizations.
-- **Modular Architecture**: FerrisKey is split into focused modules. Enable the parts you need.
-- **Open Source**: FerrisKey is MIT-licensed, community-driven, and designed to be understood.
+- **Rust foundation**: memory safety and predictable performance, with async I/O throughout.
+- **Multi-tenancy**: realms isolate users, clients, roles, credentials, and configuration, so one deployment can serve many organizations.
+- **Modular**: the product is split into focused modules. Turn on the ones you need.
+- **Open source**: licensed under Apache-2.0, developed in the open.
 
 ## Modules
 
-FerrisKey is organized into modules, each focused on one part of identity management:
+Each module owns one part of identity management.
 
 ::::card-group{cols=3}
 :::card{label="Trident" icon="lucide:shield-check" href="/en/modules/trident/overview"}
@@ -51,11 +51,14 @@ Scopes and protocol mappers to control what goes into your tokens.
 Event-driven integrations for lifecycle events and external notifications.
 :::
 :::card{label="Organizations" icon="lucide:building-2" href="/en/modules/organization/overview"}
-B2B tenancy that groups users into organizations with shared membership and custom attributes.
+B2B tenancy: organizations, groups, membership, and custom attributes.
+:::
+:::card{label="SAML" icon="lucide:file-badge" href="/en/modules/saml/overview"}
+FerrisKey as a SAML 2.0 identity provider for applications that speak nothing else.
 :::
 ::::
 
-## Next Steps
+## Next steps
 
 ::::card-group{cols=3}
 :::card{label="Getting Started" icon="lucide:rocket" href="/en/discover/getting-started"}
diff --git a/apps/docs/src/content/docs/kubernetes/default/en/helm-chart.mdx b/apps/docs/src/content/docs/kubernetes/default/en/helm-chart.mdx
index 1d8f262..94bf780 100644
--- a/apps/docs/src/content/docs/kubernetes/default/en/helm-chart.mdx
+++ b/apps/docs/src/content/docs/kubernetes/default/en/helm-chart.mdx
@@ -7,107 +7,250 @@ order: 2
 
 # Helm Chart
 
-The official FerrisKey Helm chart is published as an OCI artifact. It deploys the API server, web UI, database migrations, and optionally an embedded PostgreSQL instance.
+The FerrisKey chart is published as an OCI artifact at `oci://ghcr.io/ferriskey/charts/ferriskey`. It deploys the API, the web console, the database migration job, and, unless you turn it off, an embedded PostgreSQL.
 
-## Installation
+## Install
 
 ::::step-group
 :::step{title="Install the chart"}
-The chart is available as an OCI artifact, no `helm repo add` needed:
+The chart is an OCI artifact, so there is no `helm repo add` step:
 
 ```bash
 helm install ferriskey oci://ghcr.io/ferriskey/charts/ferriskey \
   --namespace ferriskey \
   --create-namespace
 ```
+
+Out of the box this brings up an embedded PostgreSQL and generates the database and admin passwords into Secrets.
 :::
 
-:::step{title="Verify the deployment"}
+:::step{title="Check the rollout"}
 ```bash
 kubectl get pods -n ferriskey
 ```
 
-Wait for all pods to reach `Running` status and the migration job to complete.
+Wait for the migration job to complete and the API and webapp pods to reach `Running`.
 :::
 
-:::step{title="Access the UI"}
-Port-forward to the web UI:
+:::step{title="Reach the console"}
+The webapp service listens on port 80:
 
 ```bash
-kubectl port-forward -n ferriskey svc/ferriskey-webapp 5555:5555
+kubectl port-forward -n ferriskey svc/ferriskey-webapp 5555:80
 ```
 
-Open `http://localhost:5555` and log in with the default admin credentials.
+Open `http://localhost:5555` and sign in with the admin account.
 :::
 ::::
 
-## Configuration
+:::callout{variant="warning" title="The embedded PostgreSQL is for trying things out"}
+`postgresql.enabled` defaults to `true` so a fresh install works with no dependencies. Do not ship that to production. Point `database.host` at a managed instance and set `postgresql.enabled: false`.
+:::
 
-Override default values by creating a `values.yaml` file:
+## Install against an external PostgreSQL
 
-```yaml title="values.yaml"
-database:
-  host: "postgres.database.svc.cluster.local"
-  port: 5432
-  name: "ferriskey"
-  user: "ferriskey"
-  passwordSecret:
-    name: "ferriskey-db-credentials"
-    key: "password"
-
-common:
-  env:
-    - name: ADMIN_USERNAME
-      value: "admin"
-    - name: ADMIN_PASSWORD
-      valueFrom:
-        secretKeyRef:
-          name: ferriskey-admin
-          key: password
-    - name: ADMIN_EMAIL
-      value: "admin@yourorg.com"
-    - name: ALLOWED_ORIGINS
-      value: "https://iam.yourorg.com"
+```bash
+helm install ferriskey oci://ghcr.io/ferriskey/charts/ferriskey \
+  --namespace ferriskey --create-namespace \
+  --set postgresql.enabled=false \
+  --set database.host=postgres.database.svc.cluster.local \
+  --set database.passwordSecret.create=false \
+  --set database.passwordSecret.name=ferriskey-db-credentials
 ```
 
-Then install with your values:
+With `database.passwordSecret.create=false`, the chart reads the password from the Secret you name, at the key given by `database.passwordSecret.key` (`password` by default).
 
-```bash
-helm install ferriskey oci://ghcr.io/ferriskey/charts/ferriskey \
-  --namespace ferriskey \
-  --create-namespace \
-  -f values.yaml
+## Exposing the deployment
+
+The chart can render either an Ingress or a Gateway API HTTPRoute. Both need `publicHost`, which is the hostname the console and the API are reached at. Rendering fails with a clear message when it is missing.
+
+```yaml title="values.yaml, Ingress"
+publicHost: iam.yourorg.com
+
+ingress:
+  enabled: true
+  class: nginx
+  annotations:
+    cert-manager.io/cluster-issuer: letsencrypt
+  tls:
+    - hosts:
+        - iam.yourorg.com
+      secretName: ferriskey-tls
+```
+
+```yaml title="values.yaml, Gateway API"
+publicHost: iam.yourorg.com
+
+gatewayAPI:
+  httpRoute:
+    enabled: true
+    parentRefs:
+      - name: my-gateway
+        namespace: gateway-system
 ```
 
-## Values Reference
+Both route `/` to the webapp and `api.server.rootPath` (`/api` by default) to the API, on a single hostname. `api.webapp.url` and `webapp.api.url` are derived from that configuration, so you only set them when you serve the two on separate hosts.
+
+## Values reference
+
+The chart exposes the full Kubernetes surface for every workload: probes, security contexts, affinity, tolerations, topology spread, extra volumes, and so on. The table below covers the values specific to FerrisKey. The [chart README](https://github.com/ferriskey/ferriskey/blob/main/charts/ferriskey/README.md) has the exhaustive list.
+
+### Top level
+
+| Key | Default | Description |
+|---|---|---|
+| `nameOverride` | `nil` | Override the release-derived resource name |
+| `publicHost` | `nil` | Public hostname. Required when an Ingress or HTTPRoute is enabled |
 
 ### Database
 
 | Key | Default | Description |
 |---|---|---|
-| `database.host` | None | PostgreSQL host |
+| `database.host` | `nil` | PostgreSQL host. Defaults to the embedded instance when it is enabled |
 | `database.port` | `5432` | PostgreSQL port |
 | `database.name` | `ferriskey` | Database name |
 | `database.user` | `ferriskey` | Database user |
-| `database.passwordSecret.name` | None | Kubernetes Secret name containing the password |
-| `database.passwordSecret.key` | None | Key within the Secret |
+| `database.passwordSecret.create` | `true` | Generate the password Secret |
+| `database.passwordSecret.name` | `nil` | Existing Secret to read the password from |
+| `database.passwordSecret.key` | `password` | Key inside that Secret |
 
-### Common Settings
+### API
 
 | Key | Default | Description |
 |---|---|---|
-| `common.image.tag` | Chart appVersion | Container image tag |
-| `common.image.pullPolicy` | `IfNotPresent` | Image pull policy |
-| `common.env` | `[]` | Environment variables for all workloads |
-| `common.envFrom` | `[]` | Environment sources (ConfigMaps, Secrets) |
-| `common.volumeMounts` | `[]` | Volume mounts for all containers |
-| `common.volumes` | `[]` | Volumes for all pods |
-| `common.serviceAccount.create` | `true` | Create a ServiceAccount |
-| `common.serviceAccount.name` | None | ServiceAccount name override |
-| `common.affinity` | `{}` | Pod affinity rules |
-| `common.tolerations` | `[]` | Pod tolerations |
-| `common.topologySpreadConstraints` | `[]` | Topology spread |
-
-:::callout{variant="info" title="External PostgreSQL recommended"}
-For production, use a managed PostgreSQL service (RDS, Cloud SQL, Azure Database) rather than running PostgreSQL inside the cluster.
-:::
+| `api.replicas` | `1` | API replica count |
+| `api.image.repository` | `ghcr.io/ferriskey/ferriskey-api` | API image |
+| `api.image.tag` | chart appVersion | API image tag |
+| `api.admin.username` | `admin` | Initial admin username |
+| `api.admin.email` | `admin@cluster.local` | Initial admin email |
+| `api.admin.passwordSecret.create` | `true` | Generate the admin password Secret |
+| `api.admin.passwordSecret.name` | `nil` | Existing Secret holding the admin password |
+| `api.admin.passwordSecret.key` | `password` | Key inside that Secret |
+| `api.server.port` | `3333` | Port the API listens on |
+| `api.server.rootPath` | `/api` | Path prefix. Change it and the probes need updating too |
+| `api.server.allowedOrigins` | `[]` | Browser origins allowed on every route |
+| `api.webapp.url` | `nil` | Console URL. Computed from the exposure configuration when unset |
+| `api.log.filter` | `info` | Log filter directives |
+| `api.log.json` | `false` | JSON log output |
+| `api.serviceMonitor.enabled` | `false` | Create a Prometheus Operator ServiceMonitor |
+| `api.resources` | 128Mi request / 512Mi limit | API container resources |
+
+### Web console
+
+| Key | Default | Description |
+|---|---|---|
+| `webapp.replicas` | `1` | Console replica count |
+| `webapp.image.repository` | `ghcr.io/ferriskey/ferriskey-webapp` | Console image |
+| `webapp.api.url` | `nil` | API URL the browser calls. Computed from the exposure configuration when unset |
+| `webapp.resources` | 32Mi request / 64Mi limit | Console container resources |
+
+### Database migrations
+
+| Key | Default | Description |
+|---|---|---|
+| `databaseMigrations.image.repository` | API image | Image running `sqlx migrate run` |
+| `databaseMigrations.backoffLimit` | `nil` | Job backoff limit |
+| `databaseMigrations.ttlSecondsAfterFinished` | `nil` | Set to `0` outside of ArgoCD to clean the job up |
+
+Under Helm the migration job runs as a `post-install` and `pre-upgrade` hook, so it is recreated on every upgrade rather than patched in place.
+
+### Embedded PostgreSQL
+
+| Key | Default | Description |
+|---|---|---|
+| `postgresql.enabled` | `true` | Deploy the bundled PostgreSQL |
+| `postgresql.image.repository` | `postgres` | PostgreSQL image |
+| `postgresql.image.tag` | `17` | PostgreSQL image tag |
+| `postgresql.persistence.enabled` | `true` | Back the instance with a PVC |
+| `postgresql.persistence.resources.requests.storage` | `5Gi` | PVC size |
+| `postgresql.persistence.storageClass` | `nil` | Storage class |
+
+### Observability
+
+| Key | Default | Description |
+|---|---|---|
+| `opentelemetry.enabled` | `false` | Set `ACTIVE_OBSERVABILITY` and export traces |
+| `opentelemetry.otlpEndpoint` | `http://tempo:4317` | OTLP collector endpoint |
+
+## A production values file
+
+```yaml title="values.yaml"
+publicHost: iam.yourorg.com
+
+postgresql:
+  enabled: false
+
+database:
+  host: postgres.database.svc.cluster.local
+  name: ferriskey
+  user: ferriskey
+  passwordSecret:
+    create: false
+    name: ferriskey-db-credentials
+    key: password
+
+api:
+  replicas: 3
+  admin:
+    username: admin
+    email: admin@yourorg.com
+    passwordSecret:
+      create: false
+      name: ferriskey-admin
+      key: password
+  server:
+    allowedOrigins:
+      - https://iam.yourorg.com
+  log:
+    json: true
+  serviceMonitor:
+    enabled: true
+
+webapp:
+  replicas: 2
+
+databaseMigrations:
+  ttlSecondsAfterFinished: 0
+
+ingress:
+  enabled: true
+  class: nginx
+  tls:
+    - hosts:
+        - iam.yourorg.com
+      secretName: ferriskey-tls
+```
+
+```bash
+helm upgrade --install ferriskey oci://ghcr.io/ferriskey/charts/ferriskey \
+  --namespace ferriskey --create-namespace \
+  -f values.yaml
+```
+
+## Installing with ArgoCD
+
+ArgoCD does not run Helm hooks, so the ordering has to be expressed with sync waves. Give the Secrets and PostgreSQL wave 0 and the migration job wave 1:
+
+```yaml title="values.yaml, ArgoCD"
+database:
+  passwordSecret:
+    annotations:
+      argocd.argoproj.io/hook: PreSync
+      argocd.argoproj.io/sync-wave: "0"
+
+databaseMigrations:
+  annotations:
+    argocd.argoproj.io/hook: PreSync
+    argocd.argoproj.io/sync-wave: "1"
+```
+
+ArgoCD regenerates the admin password Secret on every sync, which shows up as permanent drift. Tell it to ignore that field:
+
+```yaml
+ignoreDifferences:
+  - group: ""
+    kind: Secret
+    name: ferriskey-api-admin
+    jsonPointers:
+      - /data/password
+```
diff --git a/apps/docs/src/content/docs/kubernetes/default/en/operator.mdx b/apps/docs/src/content/docs/kubernetes/default/en/operator.mdx
index db00794..3c7a65c 100644
--- a/apps/docs/src/content/docs/kubernetes/default/en/operator.mdx
+++ b/apps/docs/src/content/docs/kubernetes/default/en/operator.mdx
@@ -7,11 +7,11 @@ order: 3
 
 # FerrisKey Operator
 
-The FerrisKey Operator manages FerrisKey instances declaratively through a Kubernetes Custom Resource Definition (CRD). Define your desired state in a `FerrisKeyCluster` manifest and the operator handles the rest.
+The operator manages FerrisKey instances declaratively, through a custom resource. You describe the cluster you want in a `FerrisKeyCluster` manifest, and the operator reconciles towards it.
 
-## FerrisKeyCluster CRD
+## The FerrisKeyCluster resource
 
-The operator introduces the `FerrisKeyCluster` resource (API version `ferriskey.rs/v1alpha1`):
+The CRD is `ferriskeyclusters.ferriskey.rs`, API version `ferriskey.rs/v1alpha1`, namespaced, with the short name `fkcl`. `kubectl get fkcl` prints the version, the replica count, readiness, and the current phase.
 
 ```yaml title="ferriskey-cluster.yaml"
 apiVersion: ferriskey.rs/v1alpha1
@@ -22,7 +22,7 @@ metadata:
 spec:
   name: my-ferriskey
   replicas: 3
-  version: "latest"
+  version: "0.7.0"
   api:
     apiUrl: "https://api.iam.yourorg.com"
     webappUrl: "https://iam.yourorg.com"
@@ -36,35 +36,41 @@ spec:
     sslMode: require
 ```
 
-## Spec Reference
+## Spec reference
+
+Every field below is required unless the description says otherwise.
 
 ### Root
 
 | Field | Type | Description |
 |---|---|---|
 | `name` | `string` | Cluster name |
-| `replicas` | `integer` | Number of API pod replicas |
+| `replicas` | `integer` | Number of API replicas |
 | `version` | `string` | FerrisKey version to deploy |
+| `api` | `object` | API configuration |
+| `database` | `object` | Database configuration |
 
-### API Configuration (`spec.api`)
+### `spec.api`
 
 | Field | Type | Description |
 |---|---|---|
-| `apiUrl` | `string` | Public URL of the FerrisKey API |
-| `webappUrl` | `string` | Public URL of the web UI |
-| `allowedOrigins` | `string[]` | Allowed CORS origins |
+| `apiUrl` | `string` | Public URL of the API |
+| `webappUrl` | `string` | Public URL of the console |
+| `allowedOrigins` | `string[]` | Optional. Browser origins allowed on every route |
+
+As with the standalone deployment, per-client web origins only cover realm-scoped routes. `/config`, the health probes, and the API documentation carry no realm, so a console served from a different origin than the API has to keep its origin in `allowedOrigins`.
 
-### Database Configuration (`spec.database`)
+### `spec.database`
 
 | Field | Type | Description |
 |---|---|---|
-| `secretRef.name` | `string` | Kubernetes Secret containing database credentials |
-| `secretRef.namespace` | `string` | Secret namespace (optional, defaults to resource namespace) |
-| `databaseName` | `string` | Database name override |
-| `sslMode` | `string` | PostgreSQL SSL mode (`disable`, `require`, `verify-ca`, `verify-full`) |
+| `secretRef.name` | `string` | Secret holding the database credentials |
+| `secretRef.namespace` | `string` | Optional. Defaults to the resource's namespace |
+| `databaseName` | `string` | Optional. Overrides the database name from the Secret |
+| `sslMode` | `string` | Optional. `disable`, `prefer`, `require`, `verify-ca`, or `verify-full` |
 
 :::callout{variant="info" title="Database Secret format"}
-The referenced Secret should contain the standard PostgreSQL connection fields: `host`, `port`, `user`, `password`, and optionally `database`.
+The referenced Secret must carry `host`, `port`, `user`, and `password`. `database` is optional and can be supplied through `databaseName` instead.
 :::
 
 ## Status
@@ -101,8 +107,12 @@ status:
 
 ::::step-group
 :::step{title="Install the operator"}
+The operator ships as its own Helm chart, which installs the CRD, the operator Deployment, and the RBAC it needs:
+
 ```bash
-kubectl apply -f https://github.com/ferriskey/ferriskey/releases/latest/download/operator.yaml
+helm install ferriskey-operator oci://ghcr.io/ferriskey/charts/ferriskey-operator \
+  --namespace ferriskey-system \
+  --create-namespace
 ```
 :::
 
@@ -125,7 +135,25 @@ kubectl apply -f ferriskey-cluster.yaml
 
 :::step{title="Check status"}
 ```bash
-kubectl get ferriskeyclusters -n ferriskey
+kubectl get fkcl -n ferriskey
 ```
 :::
 ::::
+
+## CRD and RBAC ownership
+
+By default the chart installs the CRD and annotates it with `helm.sh/resource-policy: keep`, so `helm uninstall` leaves it, and your clusters, alone. It also creates a ClusterRole and ClusterRoleBinding letting the operator manage `FerrisKeyCluster` resources across namespaces.
+
+If either is managed elsewhere, for example through GitOps or a dedicated CRD chart, turn the chart's copy off:
+
+```yaml title="values.yaml"
+crds:
+  install: false
+
+rbac:
+  create: false
+```
+
+:::callout{variant="warning" title="Keep the CRD on uninstall"}
+Leave `crds.keep` at `true` in production. Deleting the CRD deletes every `FerrisKeyCluster` in the cluster along with it.
+:::
diff --git a/apps/docs/src/content/docs/kubernetes/default/en/overview.mdx b/apps/docs/src/content/docs/kubernetes/default/en/overview.mdx
index c3e813c..97bbbf7 100644
--- a/apps/docs/src/content/docs/kubernetes/default/en/overview.mdx
+++ b/apps/docs/src/content/docs/kubernetes/default/en/overview.mdx
@@ -7,14 +7,14 @@ order: 1
 
 # FerrisKey on Kubernetes
 
-FerrisKey is designed to run natively on Kubernetes. Choose between two deployment methods depending on your operational needs.
+FerrisKey runs natively on Kubernetes. There are two ways in, and which one fits depends on how you already operate clusters.
 
 ::::card-group{cols=2}
 :::card{label="Helm Chart" icon="lucide:package" href="/en/kubernetes/helm-chart"}
-Install FerrisKey with a standard Helm chart. Full control over values, familiar workflow.
+A standard Helm chart with the full Kubernetes surface exposed in its values. The familiar workflow.
 :::
 :::card{label="Operator" icon="lucide:bot" href="/en/kubernetes/operator"}
-Declarative management with the FerrisKey Operator and the `FerrisKeyCluster` CRD.
+Declarative management through the `FerrisKeyCluster` custom resource, itself installed with a Helm chart.
 :::
 ::::
 
@@ -34,14 +34,16 @@ graph TD
     MIG --> PG
 ```
 
-A typical FerrisKey deployment consists of:
+A deployment is four pieces:
 
-- **API pods**: The FerrisKey backend handling authentication, token issuance, and administration
-- **Web UI pods**: The React-based admin console
-- **Migration job**: Runs database migrations on deploy
-- **PostgreSQL**: The backing database (managed or self-hosted)
+- API pods, handling authentication, token issuance, and administration
+- Console pods, serving the React admin interface
+- A migration job that applies pending schema changes on deploy
+- PostgreSQL, managed or self-hosted
 
-## Next Steps
+The chart bundles a PostgreSQL StatefulSet so a first install works with nothing else in place. It is not meant for production.
+
+## Next steps
 
 ::::card-group{cols=2}
 :::card{label="Helm Chart" icon="lucide:package" href="/en/kubernetes/helm-chart"}
diff --git a/apps/docs/src/content/docs/kubernetes/default/en/production-guide.mdx b/apps/docs/src/content/docs/kubernetes/default/en/production-guide.mdx
index f06aba5..66a8b75 100644
--- a/apps/docs/src/content/docs/kubernetes/default/en/production-guide.mdx
+++ b/apps/docs/src/content/docs/kubernetes/default/en/production-guide.mdx
@@ -7,92 +7,84 @@ order: 4
 
 # Production Guide
 
-This checklist covers everything you need to harden a FerrisKey deployment for production use.
+What to change before a FerrisKey deployment carries real users.
 
 ## Database
 
-:::callout{variant="danger" title="Do not use embedded PostgreSQL in production"}
-Always use a managed PostgreSQL service or a properly operated PostgreSQL cluster.
+:::callout{variant="danger" title="Turn off the embedded PostgreSQL"}
+The chart ships with `postgresql.enabled: true` so a first install works with no prerequisites. It stores data in a single StatefulSet with no replication and no backup. Set `postgresql.enabled: false` and point at a real database.
 :::
 
-- **Use a managed PostgreSQL**: AWS RDS, Google Cloud SQL, Azure Database for PostgreSQL, or a self-managed HA cluster
-- **Enable SSL**: Set `sslMode: require` (or `verify-full` for certificate validation)
-- **Dedicated database**: Run FerrisKey in its own database, not a shared instance
-- **Regular backups**: Configure automated backups with point-in-time recovery
-- **Connection pooling**: Consider PgBouncer for high-traffic deployments
+- Use a managed service (RDS, Cloud SQL, Azure Database for PostgreSQL) or a PostgreSQL cluster someone actually operates.
+- Require TLS. `sslMode: require` at minimum, `verify-full` when you can validate the certificate chain.
+- Give FerrisKey its own database rather than a schema inside a shared one.
+- Set up automated backups with point-in-time recovery, and restore one at least once to prove it works.
+- Put PgBouncer in front of it if the deployment sees heavy traffic.
 
-## TLS & Ingress
+## TLS and exposure
 
-- **Terminate TLS at the ingress**: Use cert-manager with Let's Encrypt or your organization's CA
-- **Force HTTPS**: Redirect all HTTP traffic to HTTPS
-- **Set `ALLOWED_ORIGINS`**: Restrict CORS to your actual frontend domain(s)
+Let the chart render the routing. It puts `/` on the console and `api.server.rootPath` on the API, on one hostname, which is what the console expects by default.
 
-Example ingress configuration:
+```yaml title="values.yaml"
+publicHost: iam.yourorg.com
 
-```yaml title="ingress.yaml"
-apiVersion: networking.k8s.io/v1
-kind: Ingress
-metadata:
-  name: ferriskey
+ingress:
+  enabled: true
+  class: nginx
   annotations:
     cert-manager.io/cluster-issuer: letsencrypt-prod
-spec:
-  ingressClassName: nginx
+    nginx.ingress.kubernetes.io/ssl-redirect: "true"
   tls:
     - hosts:
         - iam.yourorg.com
       secretName: ferriskey-tls
-  rules:
-    - host: iam.yourorg.com
-      http:
-        paths:
-          - path: /
-            pathType: Prefix
-            backend:
-              service:
-                name: ferriskey-api
-                port:
-                  number: 3333
+
+api:
+  server:
+    allowedOrigins:
+      - https://iam.yourorg.com
 ```
 
-## Admin Credentials
+`allowedOrigins` applies to every route, including the ones that carry no realm: `/config`, the health probes, and the API documentation. Per-client web origins only cover realm-scoped routes, so a console served from a different origin than the API must have its origin listed here.
 
-- **Change default credentials immediately**: Set `ADMIN_USERNAME`, `ADMIN_PASSWORD`, and `ADMIN_EMAIL` via Kubernetes Secrets
-- **Use strong passwords**: Minimum 16 characters, generated randomly
-- **Rotate regularly**: Establish a rotation schedule for admin credentials
+If your cluster uses Gateway API, swap the Ingress block for `gatewayAPI.httpRoute` with the parent references of your gateway. `publicHost` is required either way.
 
-```yaml title="admin-secret.yaml"
-apiVersion: v1
-kind: Secret
-metadata:
-  name: ferriskey-admin
-  namespace: ferriskey
-type: Opaque
-stringData:
-  username: "admin"
-  password: "your-strong-random-password"
-  email: "admin@yourorg.com"
+## Admin credentials
+
+The chart generates an admin password into a Secret on first install. In production, create the Secret yourself so the value comes from wherever you keep secrets, and point the chart at it:
+
+```yaml title="values.yaml"
+api:
+  admin:
+    username: admin
+    email: admin@yourorg.com
+    passwordSecret:
+      create: false
+      name: ferriskey-admin
+      key: password
 ```
 
-## Resource Limits
+Generate the password randomly, at least 16 characters, and rotate it on a schedule you actually keep.
 
-Set CPU and memory requests/limits to prevent resource starvation:
+## Resources and scaling
+
+The API pods are stateless, so scaling out is a replica count. Resources are set per workload; there is no global override.
 
 ```yaml title="values.yaml"
-common:
+api:
+  replicas: 3
   resources:
     requests:
-      cpu: "250m"
-      memory: "256Mi"
+      cpu: 250m
+      memory: 256Mi
     limits:
-      cpu: "1000m"
-      memory: "512Mi"
-```
+      memory: 512Mi
 
-## Scaling
+webapp:
+  replicas: 2
+```
 
-- **Horizontal scaling**: Increase `replicas` to handle more concurrent requests. FerrisKey API pods are stateless.
-- **Pod disruption budgets**: Ensure availability during cluster maintenance:
+Add a PodDisruptionBudget so a node drain does not take every replica at once:
 
 ```yaml title="pdb.yaml"
 apiVersion: policy/v1
@@ -104,37 +96,54 @@ spec:
   minAvailable: 1
   selector:
     matchLabels:
-      app: ferriskey-api
+      app.kubernetes.io/name: ferriskey-api
 ```
 
+Check the label on your own pods with `kubectl get pod -n ferriskey --show-labels` before applying it.
+
 ## Monitoring
 
-FerrisKey exposes a Prometheus metrics endpoint at `/metrics`:
+The API serves Prometheus metrics on `/metrics`. With the Prometheus Operator installed, the chart can create the ServiceMonitor for you:
+
+```yaml title="values.yaml"
+api:
+  serviceMonitor:
+    enabled: true
+    interval: 30s
+```
+
+Alert on error rate, request latency, and database connection failures. For traces, turn on the OTLP exporter:
+
+```yaml title="values.yaml"
+opentelemetry:
+  enabled: true
+  otlpEndpoint: http://tempo.observability.svc.cluster.local:4317
+```
+
+That sets `ACTIVE_OBSERVABILITY` and `OTLP_ENDPOINT` on the API.
 
-- **Scrape configuration**: Point your Prometheus instance at the FerrisKey service on port `3333`, path `/metrics`
-- **Key metrics**: Request latency, error rates, active sessions, token issuance rates
-- **Alerting**: Set alerts for error rate spikes, high latency, and database connection failures
-- **Distributed tracing**: Enable OpenTelemetry OTLP export for end-to-end request tracing
+## Security hardening
 
-## Security Hardening
+The chart already runs every container as non-root with a read-only root filesystem, all capabilities dropped, and the `RuntimeDefault` seccomp profile. What is left to you:
 
-- **Network policies**: Restrict pod-to-pod traffic. FerrisKey API pods only need to reach PostgreSQL and external IdPs (if using Abyss)
-- **Pod security**: Run containers as non-root, read-only filesystem where possible
-- **Secret management**: Use an external secrets operator (AWS Secrets Manager, HashiCorp Vault) for sensitive values
-- **Image scanning**: Scan FerrisKey container images for vulnerabilities in your CI pipeline
-- **Audit logging**: Enable SeaWatch and forward events to your SIEM
+- Network policies. The API needs PostgreSQL, plus outbound access to external identity providers if you use Abyss and to your SMTP relay.
+- External secret management. Feed `database.passwordSecret` and `api.admin.passwordSecret` from Vault, an external secrets operator, or your cloud's secret manager, instead of letting the chart generate them.
+- Image scanning in CI, on the images you actually deploy.
+- Audit forwarding. Enable SeaWatch and ship its events to your SIEM.
+- Log format. Set `api.log.json: true` so structured logs land in your aggregator intact.
 
 ## Checklist
 
 | Item | Status |
 |---|---|
-| External PostgreSQL with SSL | |
-| TLS termination at ingress | |
-| Admin credentials changed from defaults | |
-| CORS origins restricted | |
-| Resource requests and limits set | |
-| Pod disruption budget configured | |
-| Prometheus scraping enabled | |
+| `postgresql.enabled: false`, external database with TLS | |
+| Database backups configured and a restore tested | |
+| TLS terminated, HTTP redirected | |
+| `api.server.allowedOrigins` restricted to real origins | |
+| Admin password supplied from an existing Secret | |
+| Resource requests and limits set per workload | |
+| PodDisruptionBudget applied | |
+| ServiceMonitor enabled and alerts wired up | |
 | Network policies applied | |
-| Secrets managed externally | |
-| Backup strategy documented and tested | |
+| Secrets sourced externally | |
+| SeaWatch events forwarded | |
diff --git a/apps/docs/src/content/docs/learn/default/en/ciam/overview.mdx b/apps/docs/src/content/docs/learn/default/en/ciam/overview.mdx
index 7c0fe47..e5c9e4e 100644
--- a/apps/docs/src/content/docs/learn/default/en/ciam/overview.mdx
+++ b/apps/docs/src/content/docs/learn/default/en/ciam/overview.mdx
@@ -11,7 +11,7 @@ CIAM stands for Customer Identity & Access Management. It's the IAM flavor aimed
 
 Same protocols underneath (OIDC, OAuth2, JWT). Wildly different problems on top.
 
-## CIAM vs Workforce IAM
+## CIAM and workforce IAM
 
 | | Workforce IAM | CIAM |
 | --- | --- | --- |
diff --git a/apps/docs/src/content/docs/learn/default/en/oauth2/flows.mdx b/apps/docs/src/content/docs/learn/default/en/oauth2/flows.mdx
index 8ef5f05..e5f9710 100644
--- a/apps/docs/src/content/docs/learn/default/en/oauth2/flows.mdx
+++ b/apps/docs/src/content/docs/learn/default/en/oauth2/flows.mdx
@@ -85,7 +85,7 @@ curl -X POST https://auth.example.com/realms/my-app/protocol/openid-connect/toke
 
 The resulting access token represents the client itself, not a user. Permissions are tied to the client, not to a person.
 
-## Device Authorization Flow
+## Device authorization flow
 
 Used by clients that cannot easily display a login form or accept typed passwords. Smart TVs, terminal CLIs, IoT devices.
 
diff --git a/apps/docs/src/content/docs/modules/default/en/abyss/federation-flow.mdx b/apps/docs/src/content/docs/modules/default/en/abyss/federation-flow.mdx
index dc3ac3a..1d78733 100644
--- a/apps/docs/src/content/docs/modules/default/en/abyss/federation-flow.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/abyss/federation-flow.mdx
@@ -74,7 +74,7 @@ When a user authenticates through an external provider, FerrisKey stores a **fed
 
 This links the local user to their external identity. A user can have federated credentials from multiple providers simultaneously, allowing them to sign in with Google one day and GitHub the next, both resolving to the same account.
 
-## Federation Types (Advanced)
+## Federation types
 
 Abyss also supports directory-based federation for enterprise use cases:
 
diff --git a/apps/docs/src/content/docs/modules/default/en/abyss/overview.mdx b/apps/docs/src/content/docs/modules/default/en/abyss/overview.mdx
index 8ccb9c1..58885ca 100644
--- a/apps/docs/src/content/docs/modules/default/en/abyss/overview.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/abyss/overview.mdx
@@ -9,22 +9,26 @@ order: 40
 
 Abyss connects FerrisKey to external identity providers. Users can authenticate through Google, GitHub, Discord, or any custom OAuth2/OIDC provider, and FerrisKey handles the token exchange, user provisioning, account linking, and attribute mapping.
 
-## Why Federation?
+## Why federation?
 
-Federation lets you meet users where they already have an identity. Instead of forcing users to create yet another account, let them sign in with their existing Google or corporate credentials. FerrisKey becomes the identity broker, normalizing different provider formats into a consistent internal model.
+Federation meets users where they already have an identity. Rather than making them create yet another account, let them sign in with the Google or corporate credentials they already carry. FerrisKey sits in the middle as the broker, normalizing each provider's format into one internal model.
 
-## Supported Provider Types
+## Supported provider types
 
 | Type | Status | Examples |
 |---|---|---|
-| **OAuth2** | Supported | Google, GitHub, Discord, any OAuth2 provider |
-| **OIDC** | Supported | Any OpenID Connect compliant provider |
-| **SAML** | Planned | Enterprise IdPs (Okta, Azure AD via SAML) |
-| **LDAP** | Planned | Active Directory, OpenLDAP |
+| OAuth2 | Supported | Google, GitHub, Discord, any OAuth2 provider |
+| OIDC | Supported | Any OpenID Connect compliant provider |
+| SAML | Planned | Enterprise IdPs such as Okta or Entra ID |
+| LDAP | Planned | Active Directory, OpenLDAP |
 
-## Provider Configuration
+:::callout{variant="info" title="SAML in the other direction already works"}
+Signing in *through* an external SAML provider is what is planned here. FerrisKey acting *as* a SAML identity provider, so other applications can trust it, is shipped: see the [SAML module](/en/modules/saml/overview).
+:::
+
+## Provider configuration
 
-Each provider is registered per realm with full OAuth2/OIDC configuration:
+Providers are registered per realm, each with its full OAuth2 or OIDC configuration:
 
 | Field | Description |
 |---|---|
@@ -43,9 +47,9 @@ Each provider is registered per realm with full OAuth2/OIDC configuration:
 Client secrets are encrypted before storage. They are never exposed through the admin API in plaintext.
 :::
 
-## Provider Mappings
+## Provider mappings
 
-Provider mappings define how external attributes map to internal FerrisKey user fields:
+Mappings say how the provider's attributes land on FerrisKey user fields:
 
 | External Field | Internal Field | Required |
 |---|---|---|
@@ -55,18 +59,18 @@ Provider mappings define how external attributes map to internal FerrisKey user
 | `given_name` | `firstname` | No |
 | `family_name` | `lastname` | No |
 
-Each mapping specifies whether it's required, if a required mapping is missing from the provider's response, the federation flow fails.
+A mapping can be marked required. When a required one is absent from the provider's response, the federation flow fails rather than creating a half-filled user.
 
-## Real-World Patterns
+## Common setups
 
-### "Sign in with Google" for a SaaS Product
+### Sign in with Google for a SaaS product
 Configure a Google OAuth2 provider with scopes `openid email profile`. Users click "Sign in with Google", authenticate at Google, and are redirected back to your app with FerrisKey tokens. New users are automatically provisioned.
 
-### Corporate SSO with Azure AD
-Configure an OIDC provider pointing to your Azure AD tenant's endpoints. Employees authenticate through their corporate identity and get FerrisKey tokens scoped to the correct realm.
+### Corporate SSO with Entra ID
+Configure an OIDC provider pointing at your tenant's endpoints. Employees authenticate with their corporate identity and receive FerrisKey tokens scoped to the right realm.
 
-### Multi-Provider Login
+### Several providers at once
 Configure Google, GitHub, and Discord as providers on the same realm. Users choose their preferred provider on the login page. All three paths converge into the same FerrisKey user model with unified roles and permissions.
 
-### Account Linking
-A user who first authenticated with Google can later link their GitHub account. Both external identities map to the same FerrisKey user, each tracked by a separate federated credential.
+### Account linking
+A user who first signed in with Google can link a GitHub account later. Both external identities point at the same FerrisKey user, each tracked by its own federated credential.
diff --git a/apps/docs/src/content/docs/modules/default/en/abyss/providers.mdx b/apps/docs/src/content/docs/modules/default/en/abyss/providers.mdx
index 57066f5..8c0a792 100644
--- a/apps/docs/src/content/docs/modules/default/en/abyss/providers.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/abyss/providers.mdx
@@ -80,7 +80,7 @@ Go to the [Discord Developer Portal](https://discord.com/developers/applications
 :::
 ::::
 
-## Custom OIDC Provider
+## Custom OIDC provider
 
 For any OpenID Connect compliant provider (Okta, Auth0, Azure AD, Keycloak):
 
diff --git a/apps/docs/src/content/docs/modules/default/en/aegis/custom-claims.mdx b/apps/docs/src/content/docs/modules/default/en/aegis/custom-claims.mdx
index cf2151d..aee4ced 100644
--- a/apps/docs/src/content/docs/modules/default/en/aegis/custom-claims.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/aegis/custom-claims.mdx
@@ -11,7 +11,7 @@ FerrisKey's default scopes cover standard OIDC claims. But real applications nee
 
 ## Common Patterns
 
-### Realm Roles in the Access Token
+### Realm roles in the access token
 
 Your API gateway needs to enforce role-based access control. Add a `user_realm_role_mapper` to include roles directly in the access token.
 
@@ -34,7 +34,7 @@ Your API gateway needs to enforce role-based access control. Add a `user_realm_r
 
 Your API gateway reads `roles` from the token and allows/denies routes without calling FerrisKey.
 
-### Tenant Identifier for Multi-Tenant SaaS
+### Tenant identifier for multi-tenant SaaS
 
 Each realm represents a tenant. Inject the realm name as a claim so your backend knows which tenant database to query.
 
@@ -72,7 +72,7 @@ FerrisKey uses bitwise permissions internally. Expose the resolved permission bi
 
 Your backend performs bitwise AND checks against the `permissions` integer, fast and efficient.
 
-### Audience for Multiple Resource Servers
+### Audience for several resource servers
 
 Your tokens need to be accepted by both `api.yourapp.com` and `admin.yourapp.com`:
 
@@ -103,7 +103,7 @@ Inject feature flags into tokens so your frontend knows which features to enable
 }
 ```
 
-## Scope Assignment Strategy
+## Scope assignment strategy
 
 ### Default vs Optional
 
@@ -113,7 +113,7 @@ Inject feature flags into tokens so your frontend knows which features to enable
 | The claim is needed for authorization decisions | The claim is large (increases token size) |
 | Missing the claim would break the client | Only specific flows need the data |
 
-### Per-Client Scope Overrides
+### Per-client scope overrides
 
 The same scope can have different types per client:
 
diff --git a/apps/docs/src/content/docs/modules/default/en/aegis/overview.mdx b/apps/docs/src/content/docs/modules/default/en/aegis/overview.mdx
index 43091ff..6c1a2c6 100644
--- a/apps/docs/src/content/docs/modules/default/en/aegis/overview.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/aegis/overview.mdx
@@ -7,15 +7,13 @@ order: 50
 
 # Aegis: Scopes & Protocol Mappers
 
-Aegis is the system that controls what information appears in your tokens. It manages **client scopes** (named collections of claims) and **protocol mappers** (rules that extract data and inject it into JWTs). Together, they form the contract between your application and FerrisKey: "Grant me this scope, and I guarantee these claims in the token."
+Aegis decides what information ends up in a token. It owns client scopes, which are named collections of claims, and protocol mappers, which are the rules that pull data out and write it into the JWT. Together they are the contract between an application and FerrisKey: grant me this scope, and these claims will be in the token.
 
-## Why Scopes Matter
+## Why scopes matter
 
-Without scopes, every token would contain the same set of claims for every client. Aegis gives you fine-grained control:
+Without them, every client would get identical claims. With them, a public mobile app gets `sub` and `email` while an internal admin tool gets roles, and neither sees more than it needs.
 
-- **Minimize data exposure**: A public mobile app gets `sub` and `email`. An internal admin tool gets `realm_roles` and `permissions`. Different clients, different claims.
-- **Standard compliance**: OIDC defines standard scopes (`openid`, `profile`, `email`). Aegis implements them out of the box.
-- **Custom claims**: Add your own business-specific claims (department, plan tier, feature flags) through custom protocol mappers.
+The standard OIDC scopes (`openid`, `profile`, `email`) are seeded into every realm. Anything specific to your business, a department, a plan tier, a feature flag, goes in through a custom protocol mapper.
 
 ## Architecture
 
@@ -28,22 +26,22 @@ graph TD
     U[User] --> PM
 ```
 
-The data flow:
+How data moves:
 
-1. A **client** has **client scope mappings**: links to specific scopes with a type (Default/Optional)
-2. Each **scope** contains one or more **protocol mappers**
-3. During token generation, mappers extract data from the **user** and produce **JWT claims**
-4. Claims are assembled into the final token
+1. A client carries client scope mappings, each linking it to a scope as default or optional.
+2. Each scope holds one or more protocol mappers.
+3. At token generation, the mappers read from the user and produce claims.
+4. The claims are assembled into the token.
 
-## Scope Types
+## Scope types
 
-| Type | Behavior | When to Use |
+| Type | Behavior | When to use |
 |---|---|---|
-| **Default** | Automatically included in every token for assigned clients | Core claims your app always needs (email, roles) |
-| **Optional** | Only included when requested via the `scope` parameter | Sensitive data the client requests on demand |
+| Default | Included in every token for the clients it is assigned to | Claims the app always needs, like email or roles |
+| Optional | Included only when the request asks for it in `scope` | Data the client should have to ask for |
 | **None** | Available in the system but not assigned to any client | Shared scope definitions waiting to be assigned |
 
-## Standard OIDC Scopes
+## Standard OIDC scopes
 
 FerrisKey ships with the standard OpenID Connect scopes pre-configured:
 
@@ -59,7 +57,7 @@ FerrisKey ships with the standard OpenID Connect scopes pre-configured:
 
 ## Real-World Patterns
 
-### API Gateway with Role-Based Access
+### API gateway with role-based access
 Create a custom scope `api_access` with a `user_realm_role_mapper` that includes `realm_roles` in the token. Your API gateway reads the roles claim and enforces route-level authorization without calling back to FerrisKey.
 
 ### Multi-Tenant SaaS
diff --git a/apps/docs/src/content/docs/modules/default/en/aegis/protocol-mappers.mdx b/apps/docs/src/content/docs/modules/default/en/aegis/protocol-mappers.mdx
index 213cec2..4a914d5 100644
--- a/apps/docs/src/content/docs/modules/default/en/aegis/protocol-mappers.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/aegis/protocol-mappers.mdx
@@ -115,7 +115,7 @@ Protocol mappers execute in the order they appear within their scope. When multi
 If two mappers target the same claim name, the later one overwrites the earlier one. Be intentional about claim names across scopes to avoid unintended overrides.
 :::
 
-## Token Generation Pipeline
+## Token generation pipeline
 
 When a token is generated, Aegis follows this pipeline:
 
@@ -126,7 +126,7 @@ When a token is generated, Aegis follows this pipeline:
 5. **Filter by token type**: Include only claims marked for the target token type (access token vs ID token)
 6. **Sign**: Sign the JWT with the realm's signing key
 
-## Creating Custom Mappers
+## Creating custom mappers
 
 To add a custom claim to your tokens:
 
diff --git a/apps/docs/src/content/docs/modules/default/en/compass/architecture.mdx b/apps/docs/src/content/docs/modules/default/en/compass/architecture.mdx
index a6b2669..2be1f40 100644
--- a/apps/docs/src/content/docs/modules/default/en/compass/architecture.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/compass/architecture.mdx
@@ -60,7 +60,7 @@ pub async fn start_flow(&self, ...) -> FlowId {
 }
 ```
 
-### Backpressure and Graceful Degradation
+### Backpressure and graceful degradation
 
 The channel has a bounded capacity. When the channel is full (the writer can't keep up):
 
diff --git a/apps/docs/src/content/docs/modules/default/en/compass/overview.mdx b/apps/docs/src/content/docs/modules/default/en/compass/overview.mdx
index 59244a8..659ecce 100644
--- a/apps/docs/src/content/docs/modules/default/en/compass/overview.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/compass/overview.mdx
@@ -7,20 +7,20 @@ order: 30
 
 # Compass: Authentication Flow Engine
 
-Compass is FerrisKey's authentication flow engine. It records every authentication attempt as a structured **flow**: a sequence of named steps with individual outcomes, timings, and error details. Compass gives you deep observability into how users authenticate, where failures occur, and how long each step takes.
+Compass records each authentication attempt as a flow: a sequence of named steps, each with its own outcome, duration, and error details. It is how you find out where a login actually went wrong.
 
-## Why Compass?
+## Why
 
-Authentication looks simple from the outside: the user logs in and gets a token. But inside, a single login request can involve redirect validation, credential hashing, MFA challenges, external IdP callbacks, session creation, and token signing. When something fails, you need to know *which step* broke and *why*.
+From outside, authentication is one request and one token. Inside, it is redirect validation, credential hashing, an MFA challenge, maybe an external IdP round trip, session creation, and token signing. When it fails, `401` tells you nothing about which of those broke.
 
-Without Compass, a failed login is just a `401`. With Compass, you see:
+With Compass you get this instead:
 
 > Flow `01914b3c-...` for client `my-frontend` via `authorization_code`:
 > ✓ authorize (12ms) → ✓ credential_validation (85ms) → ✗ mfa_challenge (0ms, error: `invalid_otp`) → Flow failed at 97ms
 
-## How It Works
+## How it works
 
-When Compass is enabled, every authentication request creates a `CompassFlow`. As the request progresses through credential validation, MFA challenges, token exchange, and finalization, each step is recorded as a `CompassFlowStep` with its own status and duration.
+With Compass on, every authentication request opens a `CompassFlow`. As the request moves through credential validation, the MFA challenge, token exchange, and finalization, each step is written as a `CompassFlowStep` with its own status and duration.
 
 ```mermaid
 graph TD
@@ -34,9 +34,7 @@ graph TD
     G --> H[Flow Completed]
 ```
 
-## Flow Lifecycle
-
-Each flow progresses through a clear lifecycle:
+## Flow lifecycle
 
 ::::step-group
 :::step{title="Flow Created"}
@@ -56,9 +54,9 @@ When authentication finishes (success or failure), the flow is marked as complet
 :::
 ::::
 
-## Flow Structure
+## Flow structure
 
-A `CompassFlow` captures the full picture of an authentication attempt:
+A `CompassFlow` holds the whole attempt:
 
 | Field | Type | Description |
 |---|---|---|
@@ -75,7 +73,7 @@ A `CompassFlow` captures the full picture of an authentication attempt:
 | `duration_ms` | `i64?` | Total flow duration in milliseconds |
 | `steps` | `Vec<FlowStep>` | Ordered list of step records |
 
-### Flow Status Values
+### Flow status values
 
 | Status | Meaning |
 |---|---|
@@ -84,22 +82,22 @@ A `CompassFlow` captures the full picture of an authentication attempt:
 | `failure` | Authentication failed at one of the steps |
 | `expired` | The auth session expired before completion (user took too long) |
 
-## Flow Steps
+## Flow steps
 
-Each step within a flow records:
+Each step records:
 
 | Field | Type | Description |
 |---|---|---|
 | `id` | `UUIDv7` | Unique step identifier |
 | `flow_id` | `UUID` | Parent flow reference |
-| `step_name` | `FlowStepName` | One of the 7 step types |
+| `step_name` | `FlowStepName` | One of the nine step types |
 | `status` | `StepStatus` | `success`, `failure`, or `skipped` |
 | `duration_ms` | `i64?` | Step execution time in milliseconds |
 | `error_code` | `String?` | Machine-readable error code (on failure) |
 | `error_message` | `String?` | Human-readable error description (on failure) |
 | `started_at` | `DateTime` | When the step began executing |
 
-### Step Types
+### Step types
 
 | Step | When It Executes | Typical Duration |
 |---|---|---|
@@ -110,8 +108,10 @@ Each step within a flow records:
 | `idp_redirect` | Building and recording the redirect to an external identity provider | &lt;5ms |
 | `idp_callback` | Processing the callback from an external IdP (token exchange + user lookup) | 100-500ms |
 | `finalize` | Session creation, SeaWatch event emission, and cleanup | 5-15ms |
+| `saml_authn_request` | Parsing an incoming SAML `AuthnRequest` and resolving the service provider | &lt;5ms |
+| `saml_assertion` | Building and signing the SAML assertion sent back to the service provider | 5-20ms |
 
-### Step Status Values
+### Step status values
 
 | Status | Meaning |
 |---|---|
@@ -125,8 +125,8 @@ Each step within a flow records:
 |---|---|---|
 | `compass_enabled` | `true` | Enable/disable flow recording per realm |
 
-When disabled, authentication works exactly the same, the flow recording is simply skipped. No flows are created, no steps are recorded, and no database writes occur. Toggle this off for realms where you don't need flow-level observability.
+Turn it off and authentication behaves identically, minus the recording: no flows, no steps, no database writes. Worth doing on realms where you do not need step-level observability.
 
-:::callout{variant="info" title="Zero performance impact when disabled"}
-When `compass_enabled` is `false`, the FlowRecorder short-circuits immediately. No channels are used, no database writes happen, no memory is allocated for flow objects.
+:::callout{variant="info" title="Off costs nothing"}
+With `compass_enabled` set to `false`, the FlowRecorder short-circuits on entry. No channel is used, no row is written, no flow object is allocated.
 :::
diff --git a/apps/docs/src/content/docs/modules/default/en/compass/querying.mdx b/apps/docs/src/content/docs/modules/default/en/compass/querying.mdx
index 3254274..1414d6d 100644
--- a/apps/docs/src/content/docs/modules/default/en/compass/querying.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/compass/querying.mdx
@@ -114,9 +114,9 @@ Fetch a single flow by ID to see all its steps:
 
 This tells the complete story: the user's password was correct (85ms for Argon2 verification), but the TOTP code was wrong.
 
-## Real-World Analytics Patterns
+## Analytics people actually build
 
-### Authentication Latency Dashboard
+### Authentication latency dashboard
 
 Build a Grafana or custom dashboard that queries Compass stats periodically:
 
@@ -136,7 +136,7 @@ export default class CompassMetrics extends BaseTask {
 }
 ```
 
-### Top Failure Reasons
+### Top failure reasons
 
 Query failed flows and group by `error_code` to find the most common failure patterns:
 
@@ -170,7 +170,7 @@ Common findings:
 - `invalid_redirect_uri`. Client misconfiguration
 - `idp_error`. External provider returned an error
 
-### Slow Flow Detection
+### Finding slow flows
 
 Find flows where a specific step took unusually long:
 
@@ -185,14 +185,14 @@ limit=100" \
   jq '.[] | select(.steps[] | select(.step_name == "credential_validation" and .duration_ms > 500))'
 ```
 
-### IdP Performance Monitoring
+### IdP performance monitoring
 
 When using [Abyss](/en/modules/abyss/overview) for external IdP federation, Compass tracks `idp_redirect` and `idp_callback` steps. These are particularly valuable because they involve network calls to third-party services:
 
 - **`idp_redirect`**: Should be < 5ms (just building a URL). If slow, check network/DNS.
 - **`idp_callback`**: Involves token exchange with the external provider. Typical: 100-500ms. If >1s, the external provider may be degraded.
 
-### User-Level Flow History
+### Per-user flow history
 
 Investigate a specific user's authentication patterns:
 
@@ -207,7 +207,7 @@ This shows their recent login attempts, useful for support tickets ("I can't log
 
 ## Data Maintenance
 
-### Purging Old Flows
+### Purging old flows
 
 Compass does not auto-delete flows. Over time, flow data grows. Use the `purge_old_flows` capability to clean up:
 
diff --git a/apps/docs/src/content/docs/modules/default/en/organization/attributes.mdx b/apps/docs/src/content/docs/modules/default/en/organization/attributes.mdx
index 3c18cc2..d6b1af7 100644
--- a/apps/docs/src/content/docs/modules/default/en/organization/attributes.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/organization/attributes.mdx
@@ -2,14 +2,16 @@
 title: Attributes
 description: "Custom key-value metadata on FerrisKey organizations."
 icon: tags
-order: 82
+order: 83
 ---
 
 # Attributes
 
-Attributes are custom key-value pairs attached to an organization. They let you store arbitrary metadata on an organization without extending the core schema — useful for subscription tiers, external system IDs, feature flags, and any other business data that belongs with the organization record.
+Attributes are key-value pairs hanging off an organization. They hold whatever business data belongs with a customer record, subscription tier, external system ids, feature flags, without anyone extending the core schema for it.
 
-## Attribute Endpoints
+Groups carry attributes too, with the same shape and the same upsert semantics, under `/groups/{group_id}/attributes`.
+
+## Attribute endpoints
 
 | Method | Endpoint | Description |
 |---|---|---|
@@ -17,9 +19,9 @@ Attributes are custom key-value pairs attached to an organization. They let you
 | `PUT` | `/realms/{realm_name}/organizations/{organization_id}/attributes/{key}` | Upsert an attribute by key |
 | `DELETE` | `/realms/{realm_name}/organizations/{organization_id}/attributes/{key}` | Delete an attribute by key |
 
-## Upsert Semantics
+## Upsert semantics
 
-The `PUT` endpoint upserts by key: if the key already exists, its value is overwritten; if it does not exist, a new attribute is created. There is no separate create endpoint.
+`PUT` upserts by key. An existing key has its value overwritten; a new key is created. There is no separate create endpoint.
 
 ```json title="PUT /realms/acme/organizations/{org_id}/attributes/plan"
 {
@@ -29,17 +31,17 @@ The `PUT` endpoint upserts by key: if the key already exists, its value is overw
 
 Both `key` and `value` are required. An empty or missing value is rejected.
 
-## Attribute Fields
+## Attribute fields
 
 | Field | Type | Constraints | Description |
 |---|---|---|---|
-| `id` | UUID v7 | — | Auto-generated identifier |
-| `organization_id` | UUID | — | The organization this attribute belongs to |
-| `key` | String | 1–255 characters, required | Attribute name |
-| `value` | String | Required | Attribute value |
-| `created_at` | DateTime (UTC) | — | Creation timestamp (set on first upsert, not updated on overwrites) |
+| `id` | UUID v7 | generated | Identifier |
+| `organization_id` | UUID | generated | The organization this attribute belongs to |
+| `key` | String | 1 to 255 characters, required | Attribute name |
+| `value` | String | required | Attribute value |
+| `created_at` | DateTime (UTC) | generated | Set on the first upsert, and left alone on overwrites |
 
-## Example: Multiple Attributes
+## Several attributes at once
 
 A typical organization might carry several attributes:
 
diff --git a/apps/docs/src/content/docs/modules/default/en/organization/groups.mdx b/apps/docs/src/content/docs/modules/default/en/organization/groups.mdx
new file mode 100644
index 0000000..b359aea
--- /dev/null
+++ b/apps/docs/src/content/docs/modules/default/en/organization/groups.mdx
@@ -0,0 +1,98 @@
+---
+title: Groups
+description: "Hierarchical groups inside a FerrisKey organization: nested membership, inherited roles, and group attributes."
+icon: network
+order: 82
+---
+
+# Groups
+
+Groups add structure inside an organization. They form a tree, and membership is recursive: a member of a group is effectively a member of every group above it, and inherits the roles mapped to each of them.
+
+That is what makes "everyone in Engineering can read the build logs, and the Platform sub-team can also deploy" expressible without assigning roles user by user.
+
+## The group tree
+
+A group belongs to one organization and points at a parent through `parent_group_id`. A `null` parent means the group sits at the top level.
+
+```
+Acme Corp (organization)
+└── Engineering              roles: build:read
+    ├── Platform             roles: deploy
+    └── Frontend
+```
+
+A user added to Platform is a member of Platform and of Engineering, and holds both `deploy` and `build:read`.
+
+## Group fields
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | UUID v7 | Identifier |
+| `organization_id` | UUID | The organization the group belongs to |
+| `parent_group_id` | UUID or null | Parent group. `null` for a top-level group |
+| `name` | String | Group name, required |
+| `description` | String | Free-text description |
+| `created_at` | DateTime (UTC) | Creation timestamp |
+| `updated_at` | DateTime (UTC) | Last-modified timestamp |
+
+Updating a group can move it: sending a new `parent_group_id` reparents it, and sending `null` promotes it to the top level.
+
+## Endpoints
+
+All of them are scoped to a realm and an organization.
+
+### Groups
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/realms/{realm_name}/organizations/{organization_id}/groups` | List the organization's groups |
+| `POST` | `/realms/{realm_name}/organizations/{organization_id}/groups` | Create a group |
+| `GET` | `/realms/{realm_name}/organizations/{organization_id}/groups/{group_id}` | Read one group |
+| `PUT` | `/realms/{realm_name}/organizations/{organization_id}/groups/{group_id}` | Update or reparent a group |
+| `DELETE` | `/realms/{realm_name}/organizations/{organization_id}/groups/{group_id}` | Delete a group |
+
+Listing returns the tree: each node carries the group's own fields plus a `children` array of the same shape.
+
+### Members
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `.../groups/{group_id}/members` | List the group's members, paginated |
+| `POST` | `.../groups/{group_id}/members` | Add a user to the group |
+| `DELETE` | `.../groups/{group_id}/members/{user_id}` | Remove a user from the group |
+
+The member list is enriched, so a client can render it without walking the user directory. Each entry carries `username`, `email`, `firstname`, `lastname`, and `enabled` alongside the membership ids, and the response wraps them with `total`, `limit`, and `offset` for server-side pagination.
+
+### Roles
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `.../groups/{group_id}/roles` | List the roles mapped to the group |
+| `POST` | `.../groups/{group_id}/roles` | Map a role to the group |
+| `DELETE` | `.../groups/{group_id}/roles/{role_id}` | Unmap a role |
+
+Every member of the group, and of every group below it, inherits the roles mapped here.
+
+### Attributes
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `.../groups/{group_id}/attributes` | List the group's attributes |
+| `PUT` | `.../groups/{group_id}/attributes/{key}` | Upsert an attribute |
+| `DELETE` | `.../groups/{group_id}/attributes/{key}` | Delete an attribute |
+
+Same key-value shape and same upsert behaviour as [organization attributes](/en/modules/organization/attributes).
+
+## Permissions
+
+Groups use the same realm-level gates as the rest of the organization module: `ManageRealm` or `ManageUsers` to write, and `ViewUsers` on top of those to read. There are no group-specific permissions.
+
+::::card-group{cols=2}
+:::card{label="Members" icon="lucide:users" href="/en/modules/organization/members"}
+Direct organization membership and the roles assigned to a member.
+:::
+:::card{label="Roles & Permissions" icon="lucide:shield-check" href="/en/discover/core-concepts/roles"}
+How roles and the bitwise permission system work.
+:::
+::::
diff --git a/apps/docs/src/content/docs/modules/default/en/organization/members.mdx b/apps/docs/src/content/docs/modules/default/en/organization/members.mdx
index e001f07..ebbb35c 100644
--- a/apps/docs/src/content/docs/modules/default/en/organization/members.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/organization/members.mdx
@@ -1,24 +1,24 @@
 ---
 title: Members
-description: "Manage organization membership in FerrisKey: add, remove, and list members, and look up a user's organizations."
+description: "Manage organization membership in FerrisKey: add, remove, and list members, assign roles inside an organization, and look up a user's organizations."
 icon: users
 order: 81
 ---
 
 # Members
 
-Membership connects a user to an organization. A user can belong to multiple organizations within the same realm, and an organization can have any number of members. Membership is flat: there are no per-member roles or permissions inside an organization.
+Membership connects a user to an organization. A user can belong to several organizations in the same realm, and an organization takes any number of members. Roles can then be assigned to a member within that organization, or inherited from a [group](/en/modules/organization/groups).
 
-## Membership Endpoints
+## Membership endpoints
 
 | Method | Endpoint | Description |
 |---|---|---|
-| `GET` | `/realms/{realm_name}/organizations/{organization_id}/members` | List all members of an organization |
+| `GET` | `/realms/{realm_name}/organizations/{organization_id}/members` | List the members of an organization |
 | `POST` | `/realms/{realm_name}/organizations/{organization_id}/members` | Add a user to an organization |
 | `DELETE` | `/realms/{realm_name}/organizations/{organization_id}/members/{user_id}` | Remove a user from an organization |
-| `GET` | `/realms/{realm_name}/users/{user_id}/organizations` | List all organizations a user belongs to |
+| `GET` | `/realms/{realm_name}/users/{user_id}/organizations` | List the organizations a user belongs to |
 
-## Adding a Member
+## Adding a member
 
 Send the target `user_id` in the request body:
 
@@ -39,7 +39,7 @@ A successful addition returns the new membership record:
 }
 ```
 
-## Adding a Member Step by Step
+## Adding a member step by step
 
 ::::step-group
 :::step{title="Confirm the organization is enabled"}
@@ -59,33 +59,53 @@ Confirm the user appears in `GET /realms/{realm_name}/organizations/{organizatio
 :::
 ::::
 
-## Behavior Rules
+## Behavior rules
 
 | Situation | Result |
 |---|---|
-| User already a member of this organization | `AlreadyExists` error — duplicate membership is rejected |
+| User already a member of this organization | `AlreadyExists`. Duplicate membership is rejected |
 | User is in a different realm than the organization | Request rejected |
 | Organization is disabled (`enabled: false`) | Request rejected |
-| Removing a user who is not a member | `NotFound` error |
+| Removing a user who is not a member | `NotFound` |
 
-## Listing a User's Organizations
+## Listing a user's organizations
 
-To find every organization a specific user belongs to across the realm:
+To find every organization a user belongs to within the realm:
 
 ```
 GET /realms/{realm_name}/users/{user_id}/organizations
 ```
 
-This returns an array of membership records — each carrying the `organization_id`, `user_id`, and `created_at` (the same `OrganizationMember` shape returned when adding a member), not full organization objects. Resolve each `organization_id` against `GET /realms/{realm_name}/organizations/{organization_id}` for full details. Use this to build a workspace switcher, enforce org-level feature access, or display the user's account context.
+The response is an array of membership records, each with `organization_id`, `user_id`, and `created_at`. That is the same `OrganizationMember` shape you get back when adding a member, not a full organization object, so resolve each `organization_id` against `GET /realms/{realm_name}/organizations/{organization_id}` when you need the details. It is what a workspace switcher is built on.
 
-## Removing a Member
+## Removing a member
 
 ```
 DELETE /realms/{realm_name}/organizations/{organization_id}/members/{user_id}
 ```
 
-Membership removal is immediate. If the user is not a member, the call returns `NotFound`. There is no cascading effect on the user's account — the user record itself is untouched.
+Removal takes effect immediately. If the user is not a member, the call returns `NotFound`. Nothing cascades to the user's account: the user record is untouched.
 
-:::callout{variant="info" title="Flat membership — org-scoped roles are roadmap"}
-Every member has the same standing inside an organization. There is no `role` field on a membership record, and no way to mark a member as owner, admin, or viewer at the organization level. Organization-scoped RBAC is planned but not yet implemented. For now, use realm-level roles to differentiate access.
+## Member roles
+
+A membership record itself has no role field. Roles are attached to the member through a separate set of endpoints, scoped to the organization.
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/realms/{realm_name}/organizations/{organization_id}/members/{user_id}/roles` | List the roles the member holds in this organization |
+| `POST` | `/realms/{realm_name}/organizations/{organization_id}/members/{user_id}/roles` | Assign a role to the member |
+| `DELETE` | `/realms/{realm_name}/organizations/{organization_id}/members/{user_id}/roles/{role_id}` | Revoke a role from the member |
+
+Assignment takes the role id in the body and answers `204 No Content`:
+
+```json title="POST .../members/{user_id}/roles"
+{
+  "role_id": "01936b2e-7777-7000-abcd-000000000004"
+}
+```
+
+`GET` returns the full role objects, so a client can read their names and permissions without a second lookup.
+
+:::callout{variant="info" title="Roles can also come from a group"}
+Groups inside an organization carry role mappings of their own, and membership in a group is recursive: a member of a group effectively belongs to all of its ancestors, and inherits their roles. See [Groups](/en/modules/organization/groups).
 :::
diff --git a/apps/docs/src/content/docs/modules/default/en/organization/overview.mdx b/apps/docs/src/content/docs/modules/default/en/organization/overview.mdx
index 8f8aef7..ae19ff7 100644
--- a/apps/docs/src/content/docs/modules/default/en/organization/overview.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/organization/overview.mdx
@@ -7,15 +7,15 @@ order: 80
 
 # Organizations
 
-Organizations are a B2B grouping layer inside a realm. A single realm can contain many organizations; a user can belong to many organizations simultaneously; and each organization can carry custom key-value metadata. Together, these primitives cover the most common multi-tenant SaaS pattern: customers are organizations, users are members.
+Organizations are a B2B grouping layer inside a realm. One realm holds many organizations, a user can belong to several at once, each organization carries custom key-value metadata, and members can be given roles scoped to the organization. That covers the usual multi-tenant SaaS shape: customers are organizations, users are members.
 
 :::callout{variant="info" title="New to B2B identity?"}
 For conceptual background on how customer-facing (B2B/CIAM) identity differs from workforce IAM, see [What is CIAM?](/en/learn/ciam/overview) and [Branding, Portals & Org Policies](/en/learn/ciam/org-policies) in the Learn section.
 :::
 
-## Why Organizations?
+## Why organizations?
 
-Realms provide isolation at the deployment level — one realm per product, or per environment. Organizations sit one level below that. They let you model the business structure of your customers without spinning up a new realm per customer.
+Realms isolate at the deployment level, one per product or per environment. Organizations sit a level below. They let you model your customers' business structure without spinning up a realm per customer.
 
 Use organizations when:
 
@@ -25,22 +25,22 @@ Use organizations when:
 
 Use a separate realm per tenant instead when you need complete credential isolation, different authentication policies, or different token lifetimes per tenant.
 
-## Organization Fields
+## Organization fields
 
 | Field | Type | Required | Description |
 |---|---|---|---|
-| `id` | UUID v7 | — | Auto-generated identifier |
-| `realm_id` | UUID | — | The realm this organization belongs to |
-| `name` | String (1–255) | Yes | Human-readable label |
-| `alias` | String (1–255) | Yes | URL-safe identifier — lowercase alphanumeric, `-`, and `_`. Unique per realm |
-| `domain` | String (≤255) | No | Optional email domain. Stored and validated but **not yet used** for automatic onboarding — see Roadmap below |
-| `redirect_url` | String | No | Optional callback URL |
-| `description` | String | No | Optional free-text description |
+| `id` | UUID v7 | generated | Identifier |
+| `realm_id` | UUID | generated | The realm this organization belongs to |
+| `name` | String (1 to 255) | Yes | Human-readable label |
+| `alias` | String (1 to 255) | Yes | URL-safe identifier: lowercase alphanumeric, `-`, and `_`. Unique per realm |
+| `domain` | String (up to 255) | No | Email domain. Stored and validated, but not yet used for automatic onboarding. See the roadmap below |
+| `redirect_url` | String | No | Callback URL |
+| `description` | String | No | Free-text description |
 | `enabled` | Boolean | No | Defaults to `true`. A disabled organization rejects new member additions |
-| `created_at` | DateTime (UTC) | — | Creation timestamp |
-| `updated_at` | DateTime (UTC) | — | Last-modified timestamp |
+| `created_at` | DateTime (UTC) | generated | Creation timestamp |
+| `updated_at` | DateTime (UTC) | generated | Last-modified timestamp |
 
-## Realm Scoping
+## Realm scoping
 
 Every organization belongs to exactly one realm. All API endpoints are realm-scoped:
 
@@ -52,9 +52,9 @@ A user and the organization they join must be in the same realm. Cross-realm mem
 
 The `alias` must be unique within the realm. Attempting to create or update an organization with a duplicate alias returns a `AlreadyExists` error.
 
-## The `enabled` Flag
+## The `enabled` flag
 
-Setting `enabled: false` on an organization freezes membership additions — the `POST /members` endpoint will reject new requests. Existing members are unaffected. Use this to suspend an organization without deleting it or removing all its members.
+Setting `enabled: false` freezes membership additions: `POST /members` starts rejecting requests. Existing members are left alone. It is how you suspend a customer without deleting the organization or emptying it.
 
 ## Permissions
 
@@ -68,15 +68,14 @@ Setting `enabled: false` on an organization freezes membership additions — the
 There are no organization-specific permissions. All access control uses the realm-level permissions above.
 
 :::callout{variant="info" title="Roadmap"}
-The following features are planned but not yet implemented:
+Still missing:
 
-- **Organization-scoped roles**: membership is currently flat — there is no per-member role or permission within an organization.
-- **Domain-based auto-onboarding**: the `domain` field is stored and validated, but FerrisKey does not yet automatically assign users to an organization based on their email domain.
-- **Organization policies**: forced SSO, domain-matching rules, and org-level authentication policies are aspirational and not shipped.
-- **Soft delete**: deletes are hard (permanent). There is no archive or restore flow.
+- Domain-based auto-onboarding. The `domain` field is stored and validated, but nothing assigns users to an organization from their email domain yet.
+- Organization policies. Forced SSO, domain-matching rules, and org-level authentication policies are not shipped.
+- Soft delete. Deletes are permanent, with no archive or restore.
 :::
 
-## When to Use Organizations vs. Separate Realms
+## Organizations or separate realms?
 
 | Scenario | Recommendation |
 |---|---|
@@ -85,11 +84,14 @@ The following features are planned but not yet implemented:
 | Internal multi-team product | Organizations within one realm |
 | Regulated multi-tenant isolation (data residency) | Separate realms |
 
-::::card-group{cols=2}
+::::card-group{cols=3}
 :::card{label="Members" icon="lucide:users" href="/en/modules/organization/members"}
-Add, remove, and list organization members, and look up which organizations a user belongs to.
+Add, remove, and list members, assign roles inside an organization, and look up a user's organizations.
+:::
+:::card{label="Groups" icon="lucide:network" href="/en/modules/organization/groups"}
+Nest members in a group tree and let them inherit roles from every ancestor.
 :::
 :::card{label="Attributes" icon="lucide:tags" href="/en/modules/organization/attributes"}
-Attach custom key-value metadata to an organization — plan tier, CRM IDs, feature flags.
+Attach key-value metadata to an organization: plan tier, CRM ids, feature flags.
 :::
 ::::
diff --git a/apps/docs/src/content/docs/modules/default/en/overview.mdx b/apps/docs/src/content/docs/modules/default/en/overview.mdx
index 5a5d103..4b090ed 100644
--- a/apps/docs/src/content/docs/modules/default/en/overview.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/overview.mdx
@@ -7,37 +7,37 @@ order: 1
 
 # Modules
 
-FerrisKey is built as a collection of purpose-built modules. Each module owns a specific aspect of identity management and can be understood, configured, and extended independently.
+FerrisKey is a collection of modules. Each one owns a piece of identity management and can be read, configured, and extended on its own.
 
 ::::card-group{cols=2}
 :::card{label="Trident" icon="lucide:shield-check" href="/en/modules/trident/overview"}
-**Multi-Factor Authentication**: TOTP, WebAuthn passkeys, magic links, and recovery codes.
+Multi-factor authentication: TOTP, WebAuthn passkeys, magic links, and recovery codes.
 :::
 :::card{label="SeaWatch" icon="lucide:eye" href="/en/modules/seawatch/overview"}
-**Audit & Security Events**: Track and query every critical action across your realms.
+Audit and security events: every critical action across your realms, queryable.
 :::
 :::card{label="Compass" icon="lucide:compass" href="/en/modules/compass/overview"}
-**Authentication Flow Engine**: Orchestrate multi-step authentication with conditional logic.
+Authentication flow recording: which step broke, and how long each one took.
 :::
 :::card{label="Abyss" icon="lucide:link" href="/en/modules/abyss/overview"}
-**Identity Provider Federation**: Connect Google, GitHub, Discord, and custom OIDC providers.
+Identity provider federation: Google, GitHub, Discord, and custom OIDC providers.
 :::
 :::card{label="Aegis" icon="lucide:lock" href="/en/modules/aegis/overview"}
-**Scopes & Protocol Mappers**: Control exactly what data flows into your tokens.
+Scopes and protocol mappers, deciding exactly what goes into a token.
 :::
 :::card{label="Webhooks" icon="lucide:webhook" href="/en/modules/webhooks/overview"}
-**Event-Driven Extensibility**: Subscribe to lifecycle events and push notifications to external systems.
+Event-driven integrations: subscribe to lifecycle events and push them outward.
 :::
 :::card{label="Organizations" icon="lucide:building-2" href="/en/modules/organization/overview"}
-**B2B Tenancy**: Group users into organizations with membership and custom attributes.
+B2B tenancy: organizations, groups, membership, roles, and custom attributes.
+:::
+:::card{label="SAML" icon="lucide:file-badge" href="/en/modules/saml/overview"}
+FerrisKey as a SAML 2.0 identity provider, for applications that speak nothing else.
 :::
 ::::
 
-## Module Architecture
-
-Each module is implemented as either:
+## How a module is built
 
-- **A domain module** within `core/src/domain/`, tightly integrated with the core domain
-- **A standalone library crate** in `libs/`, reusable and independently testable
+A module lives either as a domain module under `core/src/domain/`, close to the core, or as its own crate under `libs/` when it is worth testing and versioning separately. Several are in the middle of moving from the first to the second.
 
-All modules follow FerrisKey's hexagonal architecture: business logic is pure, dependencies are injected through ports (traits), and infrastructure concerns are handled at the boundary.
+Either way the shape is the same, and it follows the hexagonal architecture: the business logic is pure, its dependencies arrive through ports, and the infrastructure sits at the boundary. `ferriskey-api-*` crates carry the HTTP layer for the modules that have been extracted.
diff --git a/apps/docs/src/content/docs/modules/default/en/saml/_meta.json b/apps/docs/src/content/docs/modules/default/en/saml/_meta.json
new file mode 100644
index 0000000..4c36ca4
--- /dev/null
+++ b/apps/docs/src/content/docs/modules/default/en/saml/_meta.json
@@ -0,0 +1,6 @@
+{
+  "icon": "file-badge",
+  "title": "SAML",
+  "type": "group",
+  "order": 9
+}
diff --git a/apps/docs/src/content/docs/modules/default/en/saml/overview.mdx b/apps/docs/src/content/docs/modules/default/en/saml/overview.mdx
new file mode 100644
index 0000000..c022b72
--- /dev/null
+++ b/apps/docs/src/content/docs/modules/default/en/saml/overview.mdx
@@ -0,0 +1,144 @@
+---
+title: Overview
+description: "FerrisKey as a SAML 2.0 identity provider: the SSO endpoints, IdP metadata, and how an assertion is built."
+icon: file-badge
+order: 60
+---
+
+# SAML 2.0
+
+FerrisKey speaks SAML 2.0 as an identity provider. A service provider sends it an `AuthnRequest`, the user signs in through the normal FerrisKey login, and FerrisKey posts back a signed assertion.
+
+This is what gets an application that only supports SAML, and there are plenty of them, onto the same realm, the same users, and the same audit trail as everything else.
+
+:::callout{variant="info" title="Identity provider, not broker"}
+This module makes FerrisKey the IdP that other applications trust. Signing in *through* an external SAML provider is a different problem, handled by federation in [Abyss](/en/modules/abyss/overview), and it is not shipped yet.
+:::
+
+## Endpoints
+
+Every endpoint is realm-scoped, under the realm's protocol path.
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/realms/{realm_name}/protocol/saml` | SSO through the HTTP-Redirect binding |
+| `POST` | `/realms/{realm_name}/protocol/saml` | SSO through the HTTP-POST binding |
+| `GET` | `/realms/{realm_name}/protocol/saml/continue` | Resume the flow after the user has authenticated |
+| `GET` | `/realms/{realm_name}/protocol/saml/descriptor` | IdP metadata, for handing to a service provider |
+
+The descriptor is what most service providers want: point them at that URL, or download it and upload the XML, and they learn the entity id, the SSO endpoints, and the signing certificate on their own.
+
+## The entity id and SERVER_PUBLIC_URL
+
+The IdP entity id is derived from the public base URL and the realm name:
+
+```
+https://sso.example.com/realms/home
+```
+
+It is signed into every assertion, which means it cannot move. If it is derived from the request's `Host` header and a request arrives through a different hostname, the entity id changes and service providers reject the assertion.
+
+:::callout{variant="warning" title="Set SERVER_PUBLIC_URL before using SAML"}
+Leave `SERVER_PUBLIC_URL` unset and FerrisKey falls back to the `Host` header, which is fine for OIDC and wrong for SAML. Set it to the origin browsers and service providers actually reach, as `scheme://host[:port]`. See [Configuration](/en/discover/guides/configuration).
+:::
+
+## Registering a service provider
+
+A SAML service provider is a FerrisKey client carrying a SAML configuration.
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/realms/{realm_name}/clients/{client_id}/saml-config` | Read the client's SAML configuration |
+| `PUT` | `/realms/{realm_name}/clients/{client_id}/saml-config` | Create or replace it |
+
+| Field | Default | Description |
+|---|---|---|
+| `sp_entity_id` | required | The service provider's entity id. FerrisKey resolves incoming requests by their issuer, so this must match exactly |
+| `acs_url` | required | Assertion Consumer Service URL, where the signed response is posted |
+| `name_id_format` | `emailAddress` | Format of the subject identifier |
+| `sign_assertions` | | Sign the assertion element |
+| `sign_documents` | | Sign the response document |
+| `want_authn_requests_signed` | | Expect the service provider to sign its `AuthnRequest` |
+
+If an `AuthnRequest` names an ACS URL that does not match the registered one, the request is rejected rather than redirected. That is deliberate: an unchecked ACS URL in a request is an open redirect with an assertion attached.
+
+### Name ID formats
+
+| Value | URN |
+|---|---|
+| `emailAddress` | `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` |
+| `persistent` | `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` |
+| `transient` | `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` |
+| `unspecified` | `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified` |
+
+The short name and the full URN are both accepted when writing the config. A format the user cannot satisfy fails the flow: asking for `emailAddress` on a user with no email address produces an error rather than an empty subject.
+
+## Attribute mappers
+
+Beyond the subject, a service provider usually wants attributes. Mappers say which user field goes out under which SAML attribute name.
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/realms/{realm_name}/clients/{client_id}/saml-attribute-mappers` | List the client's mappers |
+| `POST` | `/realms/{realm_name}/clients/{client_id}/saml-attribute-mappers` | Create a mapper |
+| `DELETE` | `/realms/{realm_name}/clients/{client_id}/saml-attribute-mappers/{mapper_id}` | Delete a mapper |
+
+A mapper has a `name`, a `name_format`, and a `source`.
+
+Sources are written as prefixed strings:
+
+| Source | Value |
+|---|---|
+| User id | `user:id` |
+| Username | `user:username` |
+| Email | `user:email` |
+| First name | `user:first_name` |
+| Last name | `user:last_name` |
+| A custom user attribute | `attribute:<key>` |
+
+Name formats:
+
+| Value | URN |
+|---|---|
+| `basic` | `urn:oasis:names:tc:SAML:2.0:attrname-format:basic` |
+| `uri` | `urn:oasis:names:tc:SAML:2.0:attrname-format:uri` |
+| `unspecified` | `urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified` |
+
+```json title="POST .../saml-attribute-mappers"
+{
+  "name": "email",
+  "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
+  "source": "user:email"
+}
+```
+
+## The flow
+
+```mermaid
+sequenceDiagram
+    participant SP as Service Provider
+    participant B as Browser
+    participant FK as FerrisKey
+
+    SP->>B: Redirect with AuthnRequest
+    B->>FK: GET/POST /realms/{realm}/protocol/saml
+    FK->>FK: Parse request, resolve SP by issuer, check ACS URL
+    FK->>B: Login portal
+    B->>FK: Credentials, MFA if required
+    FK->>B: Redirect to /protocol/saml/continue
+    B->>FK: GET /protocol/saml/continue
+    FK->>FK: Build and sign the assertion
+    FK->>B: Auto-submitting form to the ACS URL
+    B->>SP: POST SAMLResponse (+ RelayState)
+```
+
+The `RelayState` the service provider sent is carried through and returned untouched, which is how it recovers the page the user was heading to.
+
+## Assertion validity
+
+| Constant | Value |
+|---|---|
+| Assertion lifetime | 300 seconds |
+| Allowed clock skew | 60 seconds |
+
+The skew window exists because the service provider's clock is not yours. If assertions are being rejected as not-yet-valid or expired, check NTP on both sides before anything else.
diff --git a/apps/docs/src/content/docs/modules/default/en/seawatch/event-types.mdx b/apps/docs/src/content/docs/modules/default/en/seawatch/event-types.mdx
index 71242ef..0849af1 100644
--- a/apps/docs/src/content/docs/modules/default/en/seawatch/event-types.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/seawatch/event-types.mdx
@@ -1,13 +1,13 @@
 ---
 title: Event Types
-description: "Complete reference of the 16 SeaWatch security event types in FerrisKey."
+description: "Complete reference of the SeaWatch security event types in FerrisKey."
 icon: list
 order: 21
 ---
 
 # Event Types
 
-SeaWatch tracks 16 security event types organized into five categories. Each event type captures a specific action with its success or failure status.
+SeaWatch writes 24 event types, grouped below by what they are about. Each carries a success or failure status alongside its details.
 
 ## Authentication
 
@@ -53,9 +53,10 @@ These three events trace the full password reset lifecycle. A `password_reset_re
 | Event | Description | Actor | Target |
 |---|---|---|---|
 | `user_created` | New user account created | Admin or System | User |
+| `user_email_verified` | A user confirmed their email address | User | User |
 | `user_deleted` | User account deleted | Admin | User |
 
-User creation events include whether the user was created by an admin, through self-registration, or as a service account for a client.
+User creation events record whether the account came from an admin, from self-registration, or from a client's service account.
 
 ## Role
 
@@ -75,8 +76,40 @@ Role events are critical for access control audits. They answer: "Who granted th
 | `client_created` | New OAuth2 client registered | Admin | Client |
 | `client_deleted` | Client removed | Admin | Client |
 | `client_secret_rotated` | Client secret was regenerated | Admin | Client |
+| `client_secret_viewed` | Someone read a client's secret | Admin | Client |
 
-**`client_secret_rotated`** is particularly important, it means the old secret is invalidated. If this happens unexpectedly, it could indicate a compromised admin account.
+`client_secret_rotated` invalidates the old secret, so an unexpected one is worth a look. `client_secret_viewed` is the quieter sibling: nothing changed, but a credential left the system, and that is exactly the trail you want during an incident.
+
+## Sessions
+
+| Event | Description | Actor | Target |
+|---|---|---|---|
+| `session_created` | A user session was established | User | User |
+| `session_revoked` | A session was revoked | Admin or User | User |
+
+## Maintenance
+
+| Event | Description | Actor | Target |
+|---|---|---|---|
+| `client_maintenance_enabled` | Maintenance mode was turned on | Admin | Client |
+| `client_maintenance_disabled` | Maintenance mode was turned off | Admin | Client |
+
+Maintenance mode blocks access while it is on, subject to a whitelist. Both transitions are recorded, so a window that stayed open longer than intended is visible after the fact.
+
+## Email
+
+| Event | Description | Actor | Target |
+|---|---|---|---|
+| `email_sent` | A transactional email was handed to the SMTP server | System | User |
+| `email_not_sent` | Delivery failed | System | User |
+
+`email_not_sent` is the one to alert on. A password reset that never left the building looks identical to a user ignoring it, unless you are watching this event.
+
+## Federation
+
+| Event | Description | Actor | Target |
+|---|---|---|---|
+| `identity_provider_link_removed` | A federated identity was unlinked from a user | Admin or User | User |
 
 ## Configuration
 
@@ -84,4 +117,8 @@ Role events are critical for access control audits. They answer: "Who granted th
 |---|---|---|---|
 | `realm_config_changed` | Realm settings were modified | Admin | Realm |
 
-Configuration changes can have wide-reaching effects (enabling/disabling registration, changing token lifetimes). SeaWatch captures the full details of what changed.
+Configuration changes reach far: turning registration on, changing a token lifetime, lowering a lockout threshold. SeaWatch records what changed, not just that something did.
+
+:::callout{variant="info" title="The `unknown` type"}
+Reading an event whose stored type matches no known variant yields `unknown` rather than a guess. A row written by a newer version, or a corrupt one, can never be misread as a successful login.
+:::
diff --git a/apps/docs/src/content/docs/modules/default/en/seawatch/overview.mdx b/apps/docs/src/content/docs/modules/default/en/seawatch/overview.mdx
index 7e9a7e9..0c04277 100644
--- a/apps/docs/src/content/docs/modules/default/en/seawatch/overview.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/seawatch/overview.mdx
@@ -7,18 +7,11 @@ order: 20
 
 # SeaWatch: Audit & Security Events
 
-SeaWatch records every security-relevant action in FerrisKey. Every login, password reset, user creation, role assignment, and configuration change produces a structured event with full context, who did it, what they did, when, from where, and why it succeeded or failed.
+SeaWatch records the security-relevant actions in FerrisKey. A login, a password reset, a user creation, a role assignment, a settings change: each produces a structured event carrying who did it, what they touched, when, from where, and why it worked or did not.
 
-## Why Audit Logging Matters
+Without it, a compromised account is a mystery. With it, you can trace one back to the exact login attempt, IP address, and user agent. The same trail is what SOC 2, ISO 27001, GDPR, and HIPAA audits ask for, and what makes "repeated failures from one IP" a query rather than a hunch.
 
-Without audit logs, you're blind to what's happening inside your identity system. SeaWatch gives you:
-
-- **Incident investigation**: Trace a compromised account back to the exact login attempt, IP address, and user agent
-- **Compliance**: SOC 2, ISO 27001, GDPR, and HIPAA all require audit trails for access management systems
-- **Anomaly detection**: Spot patterns like repeated login failures from the same IP, or unexpected configuration changes
-- **Operational visibility**: Know when admins create clients, rotate secrets, or modify realm settings
-
-## Event Structure
+## Event structure
 
 Every SeaWatch event captures a complete picture:
 
@@ -58,7 +51,7 @@ Every SeaWatch event captures a complete picture:
 | `details` | Event-specific JSON payload |
 | `timestamp` | When the event occurred (UTC) |
 
-## Actor Types
+## Actor types
 
 | Actor | When Used |
 |---|---|
@@ -67,13 +60,22 @@ Every SeaWatch event captures a complete picture:
 | `admin` | An administrator performed the action via the admin console |
 | `system` | FerrisKey itself (automated processes, scheduled tasks) |
 
-## Real-World Patterns
+## What people do with it
+
+**Security operations.** Forward events to your SIEM, Splunk, Elastic, Datadog, and correlate them with the rest of your signals. `trace_id` is what links an authentication event to the API requests that followed it.
+
+**Compliance reporting.** Query by time range and event type. The structured format makes "every admin action on the identity system in Q1" a query result rather than a project.
 
-### Security Operations
-Forward SeaWatch events to your SIEM (Splunk, Elastic, Datadog) for correlation with other security signals. Use `trace_id` to link authentication events to downstream API requests.
+**Alerting.** Pair SeaWatch with [Webhooks](/en/modules/webhooks/overview) to fire on the patterns that matter: repeated `login_failure` from one IP, a `client_secret_rotated` outside a maintenance window, a `realm_config_changed` from an actor nobody expected.
 
-### Compliance Reporting
-Query events by time range and event type to generate compliance reports. SeaWatch's structured format makes it straightforward to produce SOC 2 evidence. "here are all admin actions on the identity system in Q1".
+## Privacy
+
+Events carry IP addresses and user agents, which are personal data in some jurisdictions. The realm setting `seawatch_pii_mode` decides what is stored:
+
+| Mode | Behaviour |
+|---|---|
+| `off` | Store events as they are. The default |
+| `mask` | Truncate the IP address and reduce the user agent before storing |
+| `pseudonymise` | Replace the identifying fields with an HMAC, keyed by `seawatch_pseudo_key` |
 
-### Anomaly Alerting
-Combine SeaWatch with [Webhooks](/en/modules/webhooks/overview) to trigger alerts on suspicious patterns, multiple `login_failure` events from the same IP, `client_secret_rotated` events outside of maintenance windows, or `realm_config_changed` events from unexpected actors.
+Pseudonymisation keeps events correlatable, the same source produces the same value, without keeping the raw address. Set `seawatch_pseudo_key` on the realm when you use that mode.
diff --git a/apps/docs/src/content/docs/modules/default/en/seawatch/querying.mdx b/apps/docs/src/content/docs/modules/default/en/seawatch/querying.mdx
index 66071bb..adf5f1f 100644
--- a/apps/docs/src/content/docs/modules/default/en/seawatch/querying.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/seawatch/querying.mdx
@@ -26,21 +26,21 @@ The admin API exposes endpoints to list and filter security events within a real
 | `ip_address` | Events from a specific IP |
 | Time range | Events within a date/time window |
 
-### Example: Find All Login Failures for a User
+### Example: every login failure for one user
 
 ```bash
 curl -X GET "http://localhost:3333/admin/realms/my-app/events?event_type=login_failure&target_id=USER_UUID" \
   -H "Authorization: Bearer $ADMIN_TOKEN"
 ```
 
-### Example: Recent Admin Actions
+### Example: recent admin actions
 
 ```bash
 curl -X GET "http://localhost:3333/admin/realms/my-app/events?actor_type=admin" \
   -H "Authorization: Bearer $ADMIN_TOKEN"
 ```
 
-## Integration with External Systems
+## Integration with external systems
 
 ### SIEM Forwarding
 
@@ -67,7 +67,7 @@ Use [Webhooks](/en/modules/webhooks/overview) to react to SeaWatch-tracked event
 - Notify a Slack channel on `user_created` events
 - Lock accounts after N consecutive `login_failure` events (via an external service)
 
-## Compliance Use Cases
+## Compliance use cases
 
 ### SOC 2 Type II
 SeaWatch provides the audit trail required for the "Security" and "Availability" trust service criteria. Export events by time range to produce evidence for auditors.
diff --git a/apps/docs/src/content/docs/modules/default/en/trident/magic-links.mdx b/apps/docs/src/content/docs/modules/default/en/trident/magic-links.mdx
index 7ef4992..a697f1b 100644
--- a/apps/docs/src/content/docs/modules/default/en/trident/magic-links.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/trident/magic-links.mdx
@@ -9,7 +9,7 @@ order: 13
 
 Magic links provide passwordless login via email. Instead of typing a password, the user receives an email with a unique link. Clicking the link authenticates them immediately.
 
-## How It Works
+## How it works
 
 ::::step-group
 :::step{title="User requests a magic link"}
@@ -65,7 +65,7 @@ The security of magic links depends on the security of the user's email inbox. I
 ### Consumer Onboarding
 Send a magic link as part of the registration flow. The user signs up with their email, receives a link, clicks it, and they're authenticated with a verified email in one step. No password to create, no email verification step needed separately.
 
-### Low-Friction Internal Tools
+### Low-friction internal tools
 For internal dashboards where users already have corporate email, magic links eliminate password management entirely. Users click "Send me a link", check their inbox, and they're in.
 
 ### Passwordless Fallback
diff --git a/apps/docs/src/content/docs/modules/default/en/trident/overview.mdx b/apps/docs/src/content/docs/modules/default/en/trident/overview.mdx
index 2c9ecc6..c3c96ed 100644
--- a/apps/docs/src/content/docs/modules/default/en/trident/overview.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/trident/overview.mdx
@@ -7,15 +7,15 @@ order: 10
 
 # Trident: Multi-Factor Authentication
 
-Trident is FerrisKey's MFA module. It adds second-factor verification to the authentication chain, turning a password-only login into a multi-step proof of identity. Trident supports four authentication methods that can be combined depending on your security requirements.
+Trident is the MFA module. It sits in the authentication chain between a valid password and a token, and turns a single-factor login into a multi-step one. Four methods are available, and they combine.
 
-## Why MFA Matters
+## Why bother
 
-Passwords alone are not enough. Credential stuffing, phishing, and brute-force attacks make single-factor authentication a liability. MFA ensures that even if a password is compromised, an attacker cannot access the account without the second factor.
+Credential stuffing and phishing make a password on its own a liability. A second factor means a stolen password is not enough on its own to get in.
 
-FerrisKey enforces MFA through the **required actions** system. When a user has `ConfigureOtp` as a required action, they must set up a TOTP credential before gaining full access. This makes MFA enrollment mandatory rather than optional.
+Enrollment is enforced through required actions. Set `require_mfa` on the realm and users without a TOTP credential pick up `configure_otp` on their next login, which they have to clear before they get a real token.
 
-## Available Methods
+## Available methods
 
 ::::card-group{cols=2}
 :::card{label="TOTP" icon="lucide:clock" href="/en/modules/trident/totp"}
@@ -32,9 +32,9 @@ One-time backup codes for account recovery when the primary MFA device is lost.
 :::
 ::::
 
-## How Trident Fits in the Authentication Chain
+## Where Trident sits
 
-Trident operates between credential validation and token issuance:
+Between credential validation and token issuance:
 
 ```mermaid
 graph LR
@@ -46,24 +46,21 @@ graph LR
     E -->|No| F[Authentication Failed]
 ```
 
-When a user authenticates with valid credentials:
+Once the credentials check out:
 
-1. FerrisKey checks if the user has any MFA credentials (TOTP, WebAuthn)
-2. If yes, the response status is `requires_otp_challenge` with a **temporary token**
-3. The client uses the temporary token to submit the second factor
-4. On success, full access/refresh/ID tokens are issued
+1. FerrisKey looks for MFA credentials on the user, TOTP or WebAuthn.
+2. If there are any, the response comes back as `requires_otp_challenge` with a temporary token.
+3. The client submits the second factor using that temporary token.
+4. On success, the real access, refresh, and ID tokens are issued.
 
 :::callout{variant="info" title="Temporary tokens"}
-The temporary token returned during the MFA challenge is short-lived (default: 300 seconds) and can only be used to complete the MFA step or other required actions. It cannot access protected resources.
+The temporary token handed out during the challenge lives 300 seconds by default and only authorizes the MFA step and other required actions. It cannot touch a protected resource.
 :::
 
-## Real-World Deployment Patterns
+## Three ways teams use it
 
-### SaaS Application with Mandatory MFA
-Set `ConfigureOtp` as a required action for all new users in the realm. Users must configure TOTP on first login before they can access your application.
+**Mandatory MFA on a SaaS product.** Turn on `require_mfa` for the realm. Every user configures TOTP on first login before reaching the application.
 
-### Enterprise with Passwordless
-Configure WebAuthn as the primary authenticator and disable password-based login on the client. Users sign in with Touch ID or a YubiKey, no passwords to phish.
+**Passwordless in an enterprise.** Make WebAuthn the primary authenticator and turn off password login on the client. People sign in with Touch ID or a YubiKey, and there is no password left to phish.
 
-### Consumer App with Optional MFA
-Let users opt in to TOTP or WebAuthn through a self-service settings page. Don't set required actions. MFA is available but not enforced.
+**Optional MFA on a consumer app.** Leave `require_mfa` off and let users enroll TOTP or a passkey from their settings page. Available, not enforced.
diff --git a/apps/docs/src/content/docs/modules/default/en/trident/recovery-codes.mdx b/apps/docs/src/content/docs/modules/default/en/trident/recovery-codes.mdx
index 1650ca7..9760ef7 100644
--- a/apps/docs/src/content/docs/modules/default/en/trident/recovery-codes.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/trident/recovery-codes.mdx
@@ -9,7 +9,7 @@ order: 14
 
 Recovery codes are one-time backup credentials generated when MFA is first configured. They serve as a last resort when the user loses access to their primary MFA device, a lost phone, a broken hardware key, or a wiped authenticator app.
 
-## How They Work
+## How they work
 
 When a user configures TOTP or WebAuthn for the first time, FerrisKey generates a set of recovery codes. Each code is a random byte sequence that can be used exactly once to bypass the normal MFA challenge.
 
@@ -53,7 +53,7 @@ Recovery codes grant full account access. Users should store them with the same
 ### Prompt Regeneration
 After a user consumes a recovery code, prompt them to generate a fresh set. Each used code reduces the safety net.
 
-### Display Code Count
+### Show how many are left
 Show users how many recovery codes they have remaining. If the count is low (1-2 remaining), warn them to regenerate.
 
 ### Secure Display
diff --git a/apps/docs/src/content/docs/modules/default/en/trident/totp.mdx b/apps/docs/src/content/docs/modules/default/en/trident/totp.mdx
index db0ce5b..7bcd945 100644
--- a/apps/docs/src/content/docs/modules/default/en/trident/totp.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/trident/totp.mdx
@@ -9,7 +9,7 @@ order: 11
 
 TOTP generates a 6-digit code that changes every 30 seconds using a shared secret between FerrisKey and the user's authenticator app. It follows [RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238) and is compatible with Google Authenticator, Authy, 1Password, Bitwarden, and any TOTP-compliant app.
 
-## How It Works
+## How it works
 
 TOTP relies on two ingredients: a **shared secret** (a 20-byte key) and **time**. Both FerrisKey and the authenticator app derive the same code from the secret and the current 30-second time window. Because both sides share the secret and agree on the time, the codes match.
 
@@ -46,7 +46,7 @@ On successful verification, the TOTP credential is saved. The credential include
 :::
 ::::
 
-## Verification During Login
+## Verification during login
 
 After password validation, if the user has a TOTP credential:
 
@@ -65,8 +65,8 @@ TOTP depends on both FerrisKey and the authenticator app agreeing on the current
 ### Changing the Issuer
 The issuer name displayed in authenticator apps comes from the TOTP credential configuration. Customize it per realm to show your application's name instead of "FerrisKey".
 
-### Enforcing TOTP for All Users
+### Enforcing TOTP for every user
 Add `ConfigureOtp` to the list of required actions for every new user created in the realm. This makes MFA enrollment mandatory, users cannot get full tokens until they set up TOTP.
 
-### Time Window Tolerance
+### Time window tolerance
 FerrisKey accepts codes from the current and adjacent time windows to account for minor clock skew. This means a code from the previous or next 30-second window may also be accepted.
diff --git a/apps/docs/src/content/docs/modules/default/en/trident/webauthn.mdx b/apps/docs/src/content/docs/modules/default/en/trident/webauthn.mdx
index 4e50531..dde8308 100644
--- a/apps/docs/src/content/docs/modules/default/en/trident/webauthn.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/trident/webauthn.mdx
@@ -9,7 +9,7 @@ order: 12
 
 WebAuthn enables passwordless authentication using hardware security keys, platform biometrics (Touch ID, Face ID, Windows Hello), or synced passkeys (iCloud Keychain, Google Password Manager). The private key never leaves the user's device. FerrisKey only stores the public key.
 
-## How It Works
+## How it works
 
 WebAuthn uses public-key cryptography. During registration, the user's device creates a key pair. The public key is sent to FerrisKey; the private key stays on the device. During authentication, the device signs a challenge with the private key, and FerrisKey verifies the signature with the stored public key.
 
@@ -67,7 +67,7 @@ FerrisKey verifies the signed assertion against the stored public key. If valid,
 ### Passwordless Login
 Combine WebAuthn with the authorization code flow. The user clicks "Sign in with passkey", authenticates with their device, and receives tokens, no password involved. This is the most phishing-resistant flow available.
 
-### Second Factor with Hardware Keys
+### Second factor with hardware keys
 For high-security environments (finance, healthcare, government), require a hardware security key as the second factor after password authentication. Users carry a YubiKey and tap it when prompted.
 
 ### Progressive Enhancement
diff --git a/apps/docs/src/content/docs/modules/default/en/webhooks/overview.mdx b/apps/docs/src/content/docs/modules/default/en/webhooks/overview.mdx
index 22c1e2e..55e5fb3 100644
--- a/apps/docs/src/content/docs/modules/default/en/webhooks/overview.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/webhooks/overview.mdx
@@ -7,18 +7,15 @@ order: 60
 
 # Webhooks: Event-Driven Extensibility
 
-Webhooks let you react to events in FerrisKey by pushing HTTP notifications to external systems. When something happens, a user is created, a role is assigned, a client secret is rotated. FerrisKey sends an HTTP POST to your registered endpoints with a structured payload.
+Webhooks push HTTP notifications outward when something happens in FerrisKey. A user is created, a role is assigned, a client is deleted: FerrisKey POSTs a structured payload to the endpoints you registered.
 
-## Why Webhooks?
+## Why
 
-FerrisKey manages identity, but your application lives outside of it. Webhooks bridge the gap:
+FerrisKey owns identity. Your application does not live inside it. Webhooks are the seam between the two.
 
-- **Real-time sync**: Keep external systems (CRM, data warehouse, email marketing) in sync with user changes without polling
-- **Automation**: Trigger downstream workflows when specific events occur (welcome emails, Slack notifications, provisioning)
-- **Monitoring**: Forward events to alerting systems for security-sensitive actions
-- **Decoupling**: Your application reacts to events without being tightly coupled to FerrisKey's internals
+They keep a CRM, a warehouse, or a marketing platform current without anyone polling. They start downstream work, a welcome email, a Slack message, a provisioning job, at the moment the event happens. They push security-relevant actions into your alerting. And they do all of that without your application knowing anything about FerrisKey's internals.
 
-## How It Works
+## How it works
 
 ```mermaid
 graph LR
@@ -34,7 +31,7 @@ Create a webhook with a target endpoint URL, optional custom headers, and a name
 :::
 
 :::step{title="Subscribe to events"}
-Add subscribers to the webhook, each subscriber listens for a specific trigger event (e.g., `user.created`, `client.deleted`).
+Add subscribers to the webhook. Each one listens for a single trigger event, such as `user.created` or `client.deleted`.
 :::
 
 :::step{title="Events fire"}
@@ -42,9 +39,9 @@ When a matching event occurs in the realm, FerrisKey builds a payload and sends
 :::
 ::::
 
-## Webhook Structure
+## Webhook structure
 
-A webhook in FerrisKey consists of:
+A webhook holds:
 
 | Field | Description |
 |---|---|
@@ -57,19 +54,19 @@ A webhook in FerrisKey consists of:
 | `triggered_at` | Last time any subscriber fired |
 | `created_at` / `updated_at` | Timestamps |
 
-## Real-World Patterns
+## What people wire up
 
 ::::card-group{cols=2}
-:::card{label="User Onboarding" icon="lucide:user-plus"}
+:::card{label="User onboarding" icon="lucide:user-plus"}
 On `user.created`, send a welcome email, provision a trial account in your billing system, and notify the sales team in Slack.
 :::
-:::card{label="Security Monitoring" icon="lucide:alert-triangle"}
-Forward `auth.reset_password` and `client.secret_rotated` events to PagerDuty or Opsgenie for on-call alerting.
+:::card{label="Security monitoring" icon="lucide:alert-triangle"}
+Forward `auth.reset_password` and `client.maintenance.enabled` events to PagerDuty or Opsgenie for on-call alerting.
 :::
-:::card{label="Data Sync" icon="lucide:refresh-cw"}
+:::card{label="Data sync" icon="lucide:refresh-cw"}
 On `user.updated` and `user.deleted`, sync changes to your CRM, data warehouse, or marketing platform in real time.
 :::
-:::card{label="Audit Forwarding" icon="lucide:database"}
+:::card{label="Audit forwarding" icon="lucide:database"}
 Forward all events to Splunk, Elastic, or a custom SIEM for long-term storage and compliance reporting.
 :::
 ::::
diff --git a/apps/docs/src/content/docs/modules/default/en/webhooks/payload.mdx b/apps/docs/src/content/docs/modules/default/en/webhooks/payload.mdx
index 49d3aaa..8edf724 100644
--- a/apps/docs/src/content/docs/modules/default/en/webhooks/payload.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/webhooks/payload.mdx
@@ -101,7 +101,7 @@ Common patterns:
 - **HMAC signature**: Compute a signature over the payload for verification (implement in your handler)
 - **Custom identifiers**: Tag the source for routing in multi-webhook architectures
 
-## Handling Best Practices
+## Handling a delivery well
 
 ### Respond Quickly
 Return a `2xx` status code as fast as possible. Process the payload asynchronously, enqueue it for background processing rather than doing heavy work in the request handler.
@@ -112,7 +112,7 @@ Your handler may receive the same event more than once (retries, network issues)
 ### Validate the Source
 Check custom headers (e.g., a shared secret in `Authorization`) to verify the request comes from FerrisKey. Don't process payloads from unknown sources.
 
-### Handle Missing Data
+### Handle missing data
 The `data` field may be `null` for deletion events. Always check before accessing nested fields.
 
 ### Log Everything
diff --git a/apps/docs/src/content/docs/modules/default/en/webhooks/triggers.mdx b/apps/docs/src/content/docs/modules/default/en/webhooks/triggers.mdx
index 55d7daa..14ef013 100644
--- a/apps/docs/src/content/docs/modules/default/en/webhooks/triggers.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/webhooks/triggers.mdx
@@ -7,54 +7,65 @@ order: 61
 
 # Trigger Events
 
-Webhook subscribers listen for specific trigger events. FerrisKey supports 26 trigger events organized by resource type.
+A webhook subscribes to the triggers it cares about. There are 38, grouped here by the resource they concern.
 
-## User Events
+## User
 
 | Trigger | Description |
 |---|---|
 | `user.created` | A new user account was created |
 | `user.updated` | A user's profile was modified |
 | `user.deleted` | A user account was deleted |
-| `user.bulk_deleted` | Multiple users were deleted in a batch operation |
+| `user.bulk_deleted` | Several users were deleted in one batch |
+| `user.email_verified` | A user confirmed their email address |
 | `user.credentials.deleted` | A user's credentials were removed |
 | `user.role.assigned` | A role was assigned to a user |
 | `user.role.unassigned` | A role was removed from a user |
 
-## Authentication Events
+## Authentication
 
 | Trigger | Description |
 |---|---|
 | `auth.reset_password` | A password reset was performed |
+| `auth.device_flow.initiated` | A device authorization flow was started |
+| `auth.device_flow.denied` | The user refused a device authorization |
+| `auth.device_flow.expired` | A device code expired before anyone approved it |
 
-## Client Events
+## Client
 
 | Trigger | Description |
 |---|---|
 | `client.created` | A new OAuth2 client was registered |
 | `client.updated` | A client's configuration was modified |
 | `client.deleted` | A client was removed |
-| `client.role.created` | A client-specific role was created |
-| `client.role.updated` | A client-specific role was modified |
+| `client.role.created` | A client-scoped role was created |
+| `client.role.updated` | A client-scoped role was modified |
+| `client.maintenance.enabled` | Maintenance mode was turned on for the client |
+| `client.maintenance.disabled` | Maintenance mode was turned off |
+| `client.saml_config.updated` | The client's SAML configuration changed |
+| `client.saml_attribute_mapper.created` | A SAML attribute mapper was added |
+| `client.saml_attribute_mapper.deleted` | A SAML attribute mapper was removed |
 
-## Redirect URI Events
+## Redirect URIs and web origins
 
 | Trigger | Description |
 |---|---|
 | `redirect_uri.created` | A redirect URI was added to a client |
 | `redirect_uri.updated` | A redirect URI was modified |
 | `redirect_uri.deleted` | A redirect URI was removed |
+| `web_origin.created` | A web origin was added to a client |
+| `web_origin.deleted` | A web origin was removed |
 
-## Role Events
+## Roles
 
 | Trigger | Description |
 |---|---|
 | `role.created` | A new role was created |
 | `role.updated` | A role was modified |
 | `role.deleted` | A role was deleted |
-| `role.permission.updated` | A role's permissions bitmask was changed |
+| `role.permission.updated` | A role's permission bitmask changed |
 
-## Realm Events
+## Realms
 
 | Trigger | Description |
 |---|---|
@@ -63,7 +74,7 @@ Webhook subscribers listen for specific trigger events. FerrisKey supports 26 tr
 | `realm.deleted` | A realm was deleted |
 | `realm.settings.updated` | Realm settings were changed |
 
-## Webhook Events
+## Webhooks
 
 | Trigger | Description |
 |---|---|
@@ -71,17 +82,17 @@ Webhook subscribers listen for specific trigger events. FerrisKey supports 26 tr
 | `webhook.updated` | A webhook was modified |
 | `webhook.deleted` | A webhook was removed |
 
-:::callout{variant="info" title="Webhook events are meta"}
-Yes, you can subscribe to webhook lifecycle events, useful for auditing changes to your webhook configuration itself.
+:::callout{variant="info" title="Yes, webhooks about webhooks"}
+Subscribing to webhook lifecycle events is allowed, and it is the only way to audit changes to your webhook configuration from outside.
 :::
 
-## Choosing Which Events to Subscribe To
+## Choosing what to subscribe to
 
-### Start Narrow
-Subscribe only to the events you need. Each subscription adds a network call on every matching event. Start with the critical ones (`user.created`, `user.deleted`, `client.deleted`) and expand as needed.
+### Start narrow
+Subscribe to what you need and nothing more. Every subscription is a network call on every matching event. `user.created`, `user.deleted`, and `client.deleted` are a reasonable starting set.
 
-### Combine with SeaWatch
-Webhook triggers overlap with [SeaWatch event types](/en/modules/seawatch/event-types) but are not identical. SeaWatch tracks security audit events (login success/failure). Webhooks track resource lifecycle events. Use both for complete coverage.
+### Pair it with SeaWatch
+Triggers and [SeaWatch event types](/en/modules/seawatch/event-types) overlap without matching. SeaWatch records security audit events, including logins that failed. Webhooks push resource lifecycle events outward. You want both.
 
-### Event Ordering
-Events are delivered in the order they occur within the realm. However, network delivery is asynchronous, if your endpoint is slow, later events may arrive before earlier ones are acknowledged. Design your handlers to be idempotent.
+### Ordering
+Events fire in the order they happen within the realm, but delivery is asynchronous. A slow endpoint can receive a later event before it has acknowledged an earlier one, so write your handlers to be idempotent.
diff --git a/apps/docs/src/content/docs/modules/default/en/webhooks/use-cases.mdx b/apps/docs/src/content/docs/modules/default/en/webhooks/use-cases.mdx
index 7678769..029dd9c 100644
--- a/apps/docs/src/content/docs/modules/default/en/webhooks/use-cases.mdx
+++ b/apps/docs/src/content/docs/modules/default/en/webhooks/use-cases.mdx
@@ -9,7 +9,7 @@ order: 63
 
 Webhooks unlock powerful integrations between FerrisKey and external systems. Here are concrete patterns you can implement today.
 
-## Slack Notifications on User Registration
+## Slack notification on user registration
 
 Notify your team in Slack when a new user signs up.
 
@@ -131,7 +131,7 @@ export default class CrmSyncController {
 If your CRM has rate limits, queue webhook payloads and process them in batches rather than sending one API call per event. AdonisJS Jobs or Tokio tasks are good fits for this.
 :::
 
-## Security Alert on Secret Rotation
+## Security alert on secret rotation
 
 Alert your security team when a client is modified outside of scheduled maintenance.
 
@@ -187,7 +187,7 @@ async fn security_alert(
 ```
 :::
 
-## User Provisioning in External Systems
+## User provisioning in external systems
 
 When a user is created in FerrisKey, automatically provision them in other systems:
 
@@ -250,7 +250,7 @@ export default class ProvisioningController {
 }
 ```
 
-## Role Change Notifications
+## Role change notifications
 
 Notify users when their permissions change.
 
@@ -284,7 +284,7 @@ export default class RoleNotificationController {
 }
 ```
 
-## Realm Configuration Audit
+## Realm configuration audit
 
 Track all changes to realm settings for compliance.
 
diff --git a/apps/docs/src/layouts/base.astro b/apps/docs/src/layouts/base.astro
index 8d51820..43dfa32 100644
--- a/apps/docs/src/layouts/base.astro
+++ b/apps/docs/src/layouts/base.astro
@@ -23,7 +23,7 @@ const { title, description } = Astro.props
     <meta name="twitter:card" content="summary_large_image" />
     <meta name="twitter:title" content={title} />
     {description && <meta name="twitter:description" content={description} />}
-    <title>{title} — Ferriskey</title>
+    <title>{title} | Ferriskey</title>
     <ClientRouter />
     <script is:inline>
       (function () {
diff --git a/apps/docs/src/layouts/docs.astro b/apps/docs/src/layouts/docs.astro
index 563d21c..a724187 100644
--- a/apps/docs/src/layouts/docs.astro
+++ b/apps/docs/src/layouts/docs.astro
@@ -54,7 +54,7 @@ const contributors = sortContributors(
 )
 
 const showTabs = projects.length > 1
-// Thumbnails are served from the site root (dist/**/thumbnail.png), not under /assets — and
+// Thumbnails are served from the site root (dist/**/thumbnail.png), not under /assets, and
 // og:image/twitter:image must be absolute, since Discord and most link-preview bots won't
 // resolve a relative path.
 const thumbnailPath = thumbnail ?? `${Astro.url.pathname.replace(/\/$/, '')}/thumbnail.png`
@@ -82,7 +82,7 @@ const appUrlOverrides = {
     <meta name="twitter:title" content={title} />
     {description && <meta name="twitter:description" content={description} />}
     <meta name="twitter:image" content={thumbnailUrl} />
-    <title>{title} — Explainer</title>
+    <title>{title} | Explainer</title>
 
     <ClientRouter />
     <script is:inline>
diff --git a/apps/docs/src/pages/404.astro b/apps/docs/src/pages/404.astro
index d43989e..bc666f9 100644
--- a/apps/docs/src/pages/404.astro
+++ b/apps/docs/src/pages/404.astro
@@ -9,7 +9,7 @@ const appUrlOverrides = {
 }
 ---
 
-<Base title="404 — Page not found">
+<Base title="404 | Page not found">
   <Navbar
     currentApp="docs"
     appUrlOverrides={appUrlOverrides}
diff --git a/apps/website/src/components/audit-feed-section.astro b/apps/website/src/components/audit-feed-section.astro
index fa34e06..1f566ac 100644
--- a/apps/website/src/components/audit-feed-section.astro
+++ b/apps/website/src/components/audit-feed-section.astro
@@ -1,5 +1,5 @@
 ---
-// Live audit feed — a self-animating mock of FerrisKey audit events
+// Live audit feed: a self-animating mock of FerrisKey audit events
 // No backend; deterministic-ish rotation driven by a small JS loop.
 
 interface AuditEvent {
@@ -92,7 +92,7 @@ const stats = [
       <div data-anim="fade-up" style="transition-delay:120ms" class="relative">
         <div class="rounded-2xl border bg-card overflow-hidden shadow-xl">
 
-          <!-- Feed header — just 3 dots + connected indicator -->
+          <!-- Feed header: just 3 dots + connected indicator -->
           <div class="flex items-center justify-between px-5 py-3 border-b bg-muted/30">
             <div class="flex items-center gap-2">
               <span class="size-2.5 rounded-full bg-rose-400/70"></span>
@@ -154,7 +154,7 @@ const stats = [
     will-change: transform;
   }
 
-  /* Initial staggered entry of pre-rendered rows — pure fade, no layout shift */
+  /* Initial staggered entry of pre-rendered rows: pure fade, no layout shift */
   .audit-row {
     opacity: 0;
     animation: audit-fade-in 0.45s ease forwards;
diff --git a/apps/website/src/components/comparison-section.astro b/apps/website/src/components/comparison-section.astro
index f96da84..80d1878 100644
--- a/apps/website/src/components/comparison-section.astro
+++ b/apps/website/src/components/comparison-section.astro
@@ -1,6 +1,6 @@
 ---
 import SectionHeader from './section-header.astro'
-// Comparison section — FerrisKey vs Keycloak / Auth0 / Authentik
+// Comparison section: FerrisKey vs Keycloak / Auth0 / Authentik
 
 type Cell = string | { v: 'yes' | 'no' | 'partial' | 'planned'; label?: string }
 
diff --git a/apps/website/src/components/features-section.astro b/apps/website/src/components/features-section.astro
index 8dd4ee4..4fffdb3 100644
--- a/apps/website/src/components/features-section.astro
+++ b/apps/website/src/components/features-section.astro
@@ -1,11 +1,11 @@
 ---
-// Features section — key FerrisKey capabilities, one big panel per feature,
+// Features section: key FerrisKey capabilities, one big panel per feature,
 // with a sticky icon dock (bottom-left) to jump between them while scrolling.
 
 const cards = [
   {
     key: "sso",
-    // Same glyph as the "SSO" cell in the hero diagram — one identity, everywhere.
+    // Same glyph as the "SSO" cell in the hero diagram: one identity, everywhere.
     icon: `<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15.75 9V5.25A2.25 2.25 0 0013.5 3h-6a2.25 2.25 0 00-2.25 2.25v13.5A2.25 2.25 0 007.5 21h6a2.25 2.25 0 002.25-2.25V15M12 9l3 3m0 0l-3 3m3-3H3"/>`,
     title: "Single sign-on, everywhere.",
     description: "Give every user one identity across every application, service, and team. Standards-based federation means your engineers stop reinventing password storage and login screens for every new product.",
@@ -43,7 +43,7 @@ const cards = [
 
 // Per-variant palette for each panel's mosaic + connector lines. "navy" panels
 // are always dark (like the why-now diagrams); "orange" panels are always a
-// warm paper tone, independent of the site's light/dark theme — same fixed-look
+// warm paper tone, independent of the site's light/dark theme: same fixed-look
 // approach the navy variant already uses.
 const PANEL = {
   orange: {
@@ -69,10 +69,10 @@ const GRAD_MID = { from: "#fbb040", to: "#f2790a" };
 const GRAD_RIGHT = { from: "#fb923c", to: "#e2540a" };
 const MONO_FONT = 'ui-monospace, "SF Mono", "Roboto Mono", "JetBrains Mono", monospace';
 
-// Each card gets its own diagram layout — a shared visual language (sharp-cornered
+// Each card gets its own diagram layout: a shared visual language (sharp-cornered
 // gradient blocks, diamond joints, mono labels) rather than one template reused 4x.
 // `flows` are animated (the one thing each diagram actually says), `statics` are
-// still, decorative context — a diagram that continues to imply a bigger system.
+// still, decorative context: a diagram that continues to imply a bigger system.
 const DIAGRAMS = {
   // Two blocks joined by a single elbowed connector.
   sso: {
@@ -126,7 +126,7 @@ const DIAGRAMS = {
   },
 };
 
-// Deterministic "mosaic" texture — a grid of faintly tinted squares standing in for
+// Deterministic "mosaic" texture: a grid of faintly tinted squares standing in for
 // the busy neon dot-grid the panels used before. Same seed every build, no Math.random.
 function mosaicCells(cols: number, rows: number, cell: number) {
   const cells: { x: number; y: number; dark: boolean; o: number }[] = [];
@@ -236,7 +236,7 @@ const ICON_PATHS: Record<string, string> = {
               {(() => { const diagram = DIAGRAMS[card.key]; return (
               <>
               {/* Background layer: "slice" so the mosaic always fills the box edge-to-edge,
-                  regardless of the panel's aspect ratio at each breakpoint — a gap here would
+                  regardless of the panel's aspect ratio at each breakpoint. A gap here would
                   read as a bug, unlike the foreground diagram which must stay uncropped. */}
               <svg class="absolute inset-0 w-full h-full" viewBox="0 0 600 280" preserveAspectRatio="xMidYMid slice" aria-hidden="true">
                 <!-- Mosaic texture: deterministic tinted squares standing in for a busy neon grid -->
@@ -279,7 +279,7 @@ const ICON_PATHS: Record<string, string> = {
                   <path d={d} stroke={p.lineSoft} stroke-width="1.2" fill="none" />
                 ))}
 
-                <!-- Monitoring ring (audit only) — the one continuously-animated shape -->
+                <!-- Monitoring ring (audit only): the one continuously-animated shape -->
                 {diagram.ring && (
                   <ellipse class="diagram-flow" cx={diagram.ring.cx} cy={diagram.ring.cy} rx={diagram.ring.rx} ry={diagram.ring.ry} fill="none" stroke={p.line} stroke-width="1.3" />
                 )}
@@ -340,7 +340,7 @@ const ICON_PATHS: Record<string, string> = {
     color: var(--color-primary-foreground);
   }
 
-  /* Slow, quiet motion on the one connector/ring that actually carries meaning —
+  /* Slow, quiet motion on the one connector/ring that actually carries meaning -
      a data "current", not the old fast marching-ants. */
   .diagram-flow {
     stroke-dasharray: 3 7;
@@ -400,7 +400,7 @@ const ICON_PATHS: Record<string, string> = {
     })
 
     // Track how visible each block is and activate whichever one dominates the
-    // viewport — a single entry's isIntersecting isn't enough once several
+    // viewport: a single entry's isIntersecting isn't enough once several
     // tall blocks overlap the root at once.
     const visibility = new Map<string, number>(blocks.map((b) => [b.id, 0]))
 
diff --git a/apps/website/src/components/highlights-section.astro b/apps/website/src/components/highlights-section.astro
index b35b953..66ed97a 100644
--- a/apps/website/src/components/highlights-section.astro
+++ b/apps/website/src/components/highlights-section.astro
@@ -5,7 +5,7 @@ const highlights = [
   { icon: "mdi:rocket-launch", titleKey: "highlights.ship.title", descKey: "highlights.ship.description", title: "Ship docs in minutes, not days", description: "Clone the repo, write your Markdown, deploy. No complex setup, no build pipeline to configure. Your documentation is live before your coffee gets cold.", span: 4 },
   { icon: "mdi:palette-swatch-variant", titleKey: "highlights.brand.title", descKey: "highlights.brand.description", title: "Your brand, your way", description: "Tailwind CSS design tokens let you match your documentation to your product identity with a few CSS variable changes.", span: 2 },
   { icon: "mdi:puzzle-outline", titleKey: "highlights.extensible.title", descKey: "highlights.extensible.description", title: "Extensible by design", description: "Drop in React, Vue, or Svelte components directly in your Markdown. Build interactive examples, live demos, and API playgrounds.", span: 2 },
-  { icon: "mdi:chart-line", titleKey: "highlights.growth.title", descKey: "highlights.growth.description", title: "Built for growth", description: "From a single getting-started guide to hundreds of pages — the architecture scales with your project. Multi-collection docs, versioning-ready structure, and automatic navigation.", span: 4 },
+  { icon: "mdi:chart-line", titleKey: "highlights.growth.title", descKey: "highlights.growth.description", title: "Built for growth", description: "From one getting-started guide to hundreds of pages, the architecture scales with the project. Multi-collection docs, versioning-ready structure, and automatic navigation.", span: 4 },
 ];
 ---
 
diff --git a/apps/website/src/components/oss-section.astro b/apps/website/src/components/oss-section.astro
index e91caa2..02bfc27 100644
--- a/apps/website/src/components/oss-section.astro
+++ b/apps/website/src/components/oss-section.astro
@@ -48,7 +48,7 @@ try {
     const match = link.match(/page=(\d+)>; rel="last"/)
     contributorCount = match ? parseInt(match[1]) * 100 : data.length
 
-    // Build avatar list — pad to exactly 39 for the grid layout
+    // Build avatar list, padded to exactly 39 for the grid layout
     // Layout: rows 1-2 corners + 6 middle | rows 3-5 full (27) | rows 6-7 corners + 6 middle
     const contributors: Contributor[] = data
       .filter((c: any) => !c.login?.includes('[bot]'))
diff --git a/apps/website/src/components/testimonials-section.astro b/apps/website/src/components/testimonials-section.astro
index 782aae7..3c56b54 100644
--- a/apps/website/src/components/testimonials-section.astro
+++ b/apps/website/src/components/testimonials-section.astro
@@ -25,7 +25,7 @@ const testimonials = [
     name: "Tom Müller",
     username: "@tmueller",
     bodyKey: "testimonials.4.body",
-    body: "Dark mode, code highlighting, view transitions — it has everything out of the box. No plugins needed.",
+    body: "Dark mode, code highlighting, view transitions: it all works out of the box, with no plugins to add.",
     img: "https://i.pravatar.cc/150?u=tom",
   },
   {
diff --git a/apps/website/src/components/why-now-section.astro b/apps/website/src/components/why-now-section.astro
index 9442382..0efe65f 100644
--- a/apps/website/src/components/why-now-section.astro
+++ b/apps/website/src/components/why-now-section.astro
@@ -1,6 +1,6 @@
 ---
 import SectionHeader from './section-header.astro'
-// Why Now section — fragmented IAM vs FerrisKey, side-by-side comparison
+// Why Now section: fragmented IAM vs FerrisKey, side-by-side comparison
 
 const withoutServices = [
   { key: 'passwords', label: 'Password hashing' },
@@ -12,7 +12,7 @@ const withoutServices = [
   { key: 'rbac',      label: 'Permission rules' },
 ]
 
-// Keycloak variant — extensions / themes you'll wire or maintain for common needs
+// Keycloak variant: extensions / themes you'll wire or maintain for common needs
 const keycloakExtensions = [
   { key: 'magiclink', label: 'Magic link login (SPI)' },
   { key: 'email',     label: 'Email templates (theme)' },
@@ -22,7 +22,7 @@ const keycloakExtensions = [
   { key: 'ratelimit', label: 'Rate limiting (proxy)' },
 ]
 
-// Auth0 variant — what you delegate to the vendor
+// Auth0 variant: what you delegate to the vendor
 const auth0Facts = [
   { key: 'hosted',   label: 'Hosted by the vendor' },
   { key: 'mau',      label: 'Pricing scales with MAU' },
@@ -120,7 +120,7 @@ const ARROW_FILL    = 'rgba(255,255,255,0.55)'
               </marker>
             </defs>
 
-            {/* Big "Your App" container — holds every identity concern internally */}
+            {/* Big "Your App" container: holds every identity concern internally */}
             <rect x="22" y="30" width="430" height="320" rx="14"
                   fill="rgba(255,255,255,0.02)"
                   stroke="rgba(255,255,255,0.22)"
@@ -133,7 +133,7 @@ const ARROW_FILL    = 'rgba(255,255,255,0.55)'
             </g>
             <text x="38" y="78" fill="rgba(255,255,255,0.55)" font-size="11" font-family={SVG_FONT} data-t="whyNow.without.subtitle">handles every identity concern itself:</text>
 
-            {/* Internal module boxes — code paths inside the app, scanned in sequence */}
+            {/* Internal module boxes: code paths inside the app, scanned in sequence */}
             {withoutServices.map((svc, i) => {
               const y = 96 + i * 34
               return (
@@ -215,7 +215,7 @@ const ARROW_FILL    = 'rgba(255,255,255,0.55)'
               <animateMotion dur="1.6s" repeatCount="indefinite" path="M 132 190 L 184 190" />
             </circle>
 
-            {/* Big "Keycloak" container — core + extensions to wire (spans 190→450) */}
+            {/* Big "Keycloak" container: core + extensions to wire (spans 190→450) */}
             <rect x="190" y="30" width="260" height="320" rx="14"
                   fill="rgba(255,255,255,0.02)"
                   stroke="rgba(255,255,255,0.22)"
@@ -230,7 +230,7 @@ const ARROW_FILL    = 'rgba(255,255,255,0.55)'
             </g>
             <text x="206" y="80" fill="rgba(255,255,255,0.55)" font-size="11" font-family={SVG_FONT} data-t="whyNow.keycloak.subtitle">common needs handled by extensions:</text>
 
-            {/* Extension boxes — fit inside the narrower container, scanned in sequence */}
+            {/* Extension boxes: fit inside the narrower container, scanned in sequence */}
             {keycloakExtensions.map((ext, i) => {
               const y = 100 + i * 38
               return (
@@ -248,7 +248,7 @@ const ARROW_FILL    = 'rgba(255,255,255,0.55)'
               )
             })}
 
-            {/* Arrow Keycloak → Users — now 52px, symmetric with the left arrow */}
+            {/* Arrow Keycloak → Users: now 52px, symmetric with the left arrow */}
             <path class="flow-arrow" d="M 450 190 L 502 190" fill="none" stroke="rgba(255,255,255,0.5)" stroke-width="1.2" marker-end="url(#kc-arrow-head)" />
             <circle class="flow-dot" r="3" fill="rgba(255,255,255,0.9)">
               <animateMotion dur="1.6s" begin="0.4s" repeatCount="indefinite" path="M 450 190 L 502 190" />
@@ -308,7 +308,7 @@ const ARROW_FILL    = 'rgba(255,255,255,0.55)'
               </pattern>
             </defs>
 
-            {/* "Outside your network" zone — centered on x=320 */}
+            {/* "Outside your network" zone: centered on x=320 */}
             <rect x="160" y="20" width="320" height="340" rx="18" fill="url(#a0-outside)" stroke="rgba(255,255,255,0.12)" stroke-width="1" stroke-dasharray="2 6" />
             <text x="320" y="46" text-anchor="middle" fill="rgba(255,255,255,0.45)" font-size="10" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" letter-spacing="1.4" data-t="whyNow.auth0.zone">OUTSIDE YOUR NETWORK</text>
 
@@ -322,21 +322,21 @@ const ARROW_FILL    = 'rgba(255,255,255,0.55)'
               <animateMotion dur="1.6s" repeatCount="indefinite" path="M 132 190 L 196 190" />
             </circle>
 
-            {/* Auth0 SaaS box — centered on x=320 (spans 204→436) */}
+            {/* Auth0 SaaS box: centered on x=320 (spans 204→436) */}
             <rect x="204" y="110" width="232" height="160" rx="14" fill="rgba(255,255,255,0.04)" stroke="rgba(255,255,255,0.32)" stroke-width="1.4" />
 
-            {/* Cloud icon centered at (320, 146) — Heroicons cloud */}
+            {/* Cloud icon centered at (320, 146): Heroicons cloud */}
             <g transform="translate(320 146)">
               <path d="M4.5 9.75a6 6 0 0111.573-2.226 3.75 3.75 0 014.133 4.303A4.5 4.5 0 0118 20.25H6.75a5.25 5.25 0 01-2.25-10.5z"
                     transform="translate(-12 -14)"
                     fill="rgba(255,255,255,0.08)" stroke="rgba(255,255,255,0.6)" stroke-width="1.4" stroke-linejoin="round" />
             </g>
 
-            {/* "Auth0" title — centered on x=320 */}
+            {/* "Auth0" title: centered on x=320 */}
             <text x="320" y="190" text-anchor="middle" fill="rgba(255,255,255,0.95)" font-size="15" font-weight="700" font-family={SVG_FONT}>Auth0</text>
             <text x="320" y="208" text-anchor="middle" fill="rgba(255,255,255,0.55)" font-size="11" font-family={SVG_FONT} data-t="whyNow.auth0.subtitle">managed identity service</text>
 
-            {/* Pricing tag — wider, more padding (centered on x=320, y=240) */}
+            {/* Pricing tag: wider, more padding (centered on x=320, y=240) */}
             <g transform="translate(320 240)">
               <rect x="-96" y="-14" width="192" height="28" rx="6" fill="rgba(255,255,255,0.04)" stroke="rgba(255,255,255,0.2)" stroke-width="0.9" />
               <text x="0" y="4" text-anchor="middle" fill="rgba(255,255,255,0.7)" font-size="10" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" letter-spacing="0.6" data-t="whyNow.auth0.billing">per MAU · billed monthly</text>
@@ -415,11 +415,11 @@ const ARROW_FILL    = 'rgba(255,255,255,0.55)'
             <rect x="508" y="170" width="110" height="40" rx="8" fill={ANCHOR_FILL} stroke={ANCHOR_STROKE} stroke-width="1" />
             <text x="563" y="195" text-anchor="middle" fill={TEXT_COLOR} font-size="13" font-family={SVG_FONT} data-t="whyNow.diagram.users">Users</text>
 
-            {/* Occluder: hides the traveling dot behind the hub — the hub's own fill is
+            {/* Occluder: hides the traveling dot behind the hub: the hub's own fill is
                 a near-transparent glow, so without this the dot would show straight through it */}
             <rect x="190" y="120" width="260" height="140" rx="16" fill="#09090b" />
 
-            {/* FerrisKey hub — one solid block, presented as ONE thing, breathing gently */}
+            {/* FerrisKey hub: one solid block, presented as ONE thing, breathing gently */}
             <rect x="190" y="120" width="260" height="140" rx="16" fill={HUB_FILL} stroke={HUB_STROKE} stroke-width="1.8" />
 
             {/* Soft inner glow, pulsing like a heartbeat to feel always-on */}
diff --git a/apps/website/src/layouts/base.astro b/apps/website/src/layouts/base.astro
index 0ea11bf..bfecd4e 100644
--- a/apps/website/src/layouts/base.astro
+++ b/apps/website/src/layouts/base.astro
@@ -10,7 +10,7 @@ interface Props {
 
 const { title, description = 'Explainer v2', thumbnail } = Astro.props
 const thumbnailPath = thumbnail ?? '/thumbnail.png'
-// og:image/twitter:image must be absolute — Discord and most link-preview bots won't resolve a relative path.
+// og:image/twitter:image must be absolute: Discord and most link-preview bots won't resolve a relative path.
 const thumbnailUrl = Astro.site ? new URL(thumbnailPath, Astro.site).toString() : thumbnailPath
 ---
 
diff --git a/apps/website/src/lib/release-notes.ts b/apps/website/src/lib/release-notes.ts
index a610049..9c9bbf2 100644
--- a/apps/website/src/lib/release-notes.ts
+++ b/apps/website/src/lib/release-notes.ts
@@ -50,7 +50,7 @@ export const releaseNotes: ReleaseNote[] = [
       'Adds CIAM application management, resume-OAuth-after-password-reset, basic auth support, and several OIDC discovery and nonce compliance fixes.',
     ],
     transition:
-      'With operational control settled in 0.6, the 0.7 line turns toward developer-facing protocol coverage and end-user branding — making FerrisKey both more standards-complete and more customizable.',
+      'With operational control settled in 0.6, the 0.7 line turns toward developer-facing protocol coverage and end-user branding, making FerrisKey both more standards-complete and more customizable.',
   },
   {
     version: 'v0.6.1',
@@ -74,16 +74,16 @@ export const releaseNotes: ReleaseNote[] = [
     publishedAt: '2026-05-06T00:00:00Z',
     title: 'Maintenance mode, user attributes, and OpenTelemetry tracing',
     summary:
-      'FerrisKey 0.6.0 introduces two major platform capabilities — a built-in maintenance mode and extensible user attributes — alongside full OpenTelemetry tracing support for production observability.',
+      'FerrisKey 0.6.0 introduces two major platform capabilities, a built-in maintenance mode and extensible user attributes, alongside full OpenTelemetry tracing support for production observability.',
     kind: 'major',
     githubUrl: 'https://github.com/ferriskey/ferriskey/releases/tag/v0.6.0',
     highlights: [
       'Ships a first-class maintenance mode across the full stack, letting administrators halt user-facing operations gracefully during upgrades or incidents while retaining admin access.',
       'Adds user attributes support so realms can store arbitrary key-value metadata on users and propagate them into tokens via protocol mappers.',
-      'Integrates OpenTelemetry tracing and OTLP log bridge for seamless compatibility with observability stacks such as Grafana Tempo and Jaeger.',
+      'Integrates OpenTelemetry tracing and an OTLP log bridge, so traces and logs land in observability stacks such as Grafana Tempo and Jaeger without extra glue.',
     ],
     transition:
-      'Building on the passwordless and multi-tenant foundations of 0.5.0, this release shifts focus to operational control and extensibility — giving platform teams the tools to manage identity infrastructure with greater confidence.',
+      'Building on the passwordless and multi-tenant foundations of 0.5.0, this release shifts focus to operational control and extensibility, giving platform teams the tools to manage identity infrastructure with more confidence.',
   },
   {
     version: 'v0.5.0',
@@ -280,7 +280,7 @@ export const releaseNoteTranslations: Record<string, Record<string, ReleaseNoteT
         "Ajoute la gestion des applications CIAM, la reprise du flow OAuth après reset de mot de passe, le support basic auth et plusieurs correctifs de conformité OIDC (discovery et nonce).",
       ],
       transition:
-        "Le contrôle opérationnel étant posé en 0.6, la ligne 0.7 se tourne vers la couverture protocolaire côté développeurs et le branding côté utilisateurs finaux — rendant FerrisKey à la fois plus conforme aux standards et plus personnalisable.",
+        "Le contrôle opérationnel étant posé en 0.6, la ligne 0.7 se tourne vers la couverture protocolaire côté développeurs et le branding côté utilisateurs finaux, rendant FerrisKey à la fois plus conforme aux standards et plus personnalisable.",
     },
     'v0.6.1': {
       title: "Correctifs des flows d'authentification et finitions passkey",
@@ -297,7 +297,7 @@ export const releaseNoteTranslations: Record<string, Record<string, ReleaseNoteT
     'v0.6.0': {
       title: "Mode maintenance, attributs utilisateur et tracing OpenTelemetry",
       summary:
-        "FerrisKey 0.6.0 introduit deux grandes capacités plateforme — un mode maintenance natif et des attributs utilisateur extensibles — ainsi qu'un support complet du tracing OpenTelemetry pour l'observabilité en production.",
+        "FerrisKey 0.6.0 introduit deux grandes capacités plateforme, un mode maintenance natif et des attributs utilisateur extensibles, ainsi qu'un support complet du tracing OpenTelemetry pour l'observabilité en production.",
       highlights: [
         "Livre un mode maintenance de bout en bout permettant aux administrateurs de suspendre les opérations utilisateur de façon contrôlée lors d'une mise à jour ou d'un incident, tout en conservant l'accès admin.",
         "Ajoute le support des attributs utilisateur pour stocker des métadonnées clé-valeur arbitraires sur les utilisateurs et les propager dans les tokens via les protocol mappers.",
diff --git a/apps/website/src/pages/modules/[module].astro b/apps/website/src/pages/modules/[module].astro
index a7866e2..89bc1e6 100644
--- a/apps/website/src/pages/modules/[module].astro
+++ b/apps/website/src/pages/modules/[module].astro
@@ -29,18 +29,18 @@ const modules: Module[] = [
     slug: 'trident',
     name: 'Trident',
     tagline: 'Multi-Factor Authentication',
-    description: 'Adds second-factor verification to the authentication chain. Supports TOTP, FIDO2 passkeys, magic links, and recovery codes — configurable per realm.',
+    description: 'Adds second-factor verification to the authentication chain. Supports TOTP, FIDO2 passkeys, magic links, and recovery codes, configurable per realm.',
     color: 'blue',
     iconPath: 'M9 12.75L11.25 15 15 9.75m-3-7.036A11.959 11.959 0 013.598 6 11.99 11.99 0 003 9.749c0 5.592 3.824 10.29 9 11.623 5.176-1.332 9-6.03 9-11.622 0-1.31-.21-2.571-.598-3.751h-.152c-3.196 0-6.1-1.248-8.25-3.285z',
     docsHref: '/docs/modules/default/en/trident/overview',
     pills: ['TOTP', 'WebAuthn', 'Passkeys', 'Magic Links', 'Recovery Codes', 'YubiKey', 'Face ID', 'Touch ID', 'RFC 6238', 'FIDO2'],
     features: [
       { title: 'TOTP',          desc: 'Time-based one-time passwords compatible with Google Authenticator, Authy, 1Password, and any RFC 6238 app.' },
-      { title: 'WebAuthn',      desc: 'FIDO2 passkeys — hardware keys (YubiKey), Touch ID, Face ID, Windows Hello, and synced passkeys.' },
-      { title: 'Magic Links',   desc: 'Passwordless email login. A unique short-lived link is sent to the inbox — click to authenticate.' },
+      { title: 'WebAuthn',      desc: 'FIDO2 passkeys: hardware keys (YubiKey), Touch ID, Face ID, Windows Hello, and synced passkeys.' },
+      { title: 'Magic Links',   desc: 'Passwordless email login. A unique short-lived link lands in the inbox, and clicking it signs the user in.' },
       { title: 'Recovery Codes', desc: 'One-time backup codes for account recovery when the primary MFA device is unavailable.' },
-      { title: 'Required Actions', desc: 'Enforce MFA enrollment for all new users — MFA becomes mandatory rather than optional.' },
-      { title: 'Temporary Tokens', desc: 'Short-lived tokens issued during the MFA challenge phase — cannot access protected resources.' },
+      { title: 'Required Actions', desc: 'Enforce MFA enrollment on every new user, so it is mandatory rather than optional.' },
+      { title: 'Temporary Tokens', desc: 'Short-lived tokens issued during the MFA challenge. They cannot reach a protected resource.' },
     ],
     steps: [
       { title: 'Credentials validated',   desc: 'User submits their username and password. FerrisKey validates and checks for configured MFA credentials.' },
@@ -53,7 +53,7 @@ const modules: Module[] = [
     slug: 'seawatch',
     name: 'SeaWatch',
     tagline: 'Audit & Security Events',
-    description: 'Records every security-relevant action in FerrisKey — logins, password resets, role assignments, config changes — with full context for compliance and incident investigation.',
+    description: 'Records every security-relevant action: logins, password resets, role assignments, config changes, each with the context compliance and incident work needs.',
     color: 'emerald',
     iconPath: 'M2.036 12.322a1.012 1.012 0 010-.639C3.423 7.51 7.36 4.5 12 4.5c4.638 0 8.573 3.007 9.963 7.178.07.207.07.431 0 .639C20.577 16.49 16.64 19.5 12 19.5c-4.638 0-8.573-3.007-9.963-7.178z M15 12a3 3 0 11-6 0 3 3 0 016 0z',
     docsHref: '/docs/modules/default/en/seawatch/overview',
@@ -64,12 +64,12 @@ const modules: Module[] = [
       { title: 'Actor Classification', desc: 'Events distinguish between user, service account, admin, and system actions for clear accountability.' },
       { title: 'OTel Integration',     desc: 'Trace IDs link SeaWatch events to spans in Jaeger, Datadog, or any OpenTelemetry-compatible system.' },
       { title: 'SIEM Ready',          desc: 'Forward events to Splunk, Elastic, or Datadog. The structured format maps directly to common SIEM schemas.' },
-      { title: 'Compliance Evidence', desc: 'Generate SOC 2, ISO 27001, and GDPR audit evidence — query by time range, actor, or event type.' },
+      { title: 'Compliance Evidence', desc: 'Generate SOC 2, ISO 27001, and GDPR audit evidence by querying on time range, actor, or event type.' },
     ],
     steps: [
       { title: 'Action occurs',           desc: 'A user logs in, an admin changes a realm setting, or a service account requests a token.' },
       { title: 'Event constructed',       desc: 'SeaWatch builds a structured event capturing who, what, when, where, and why with full context.' },
-      { title: 'Persisted asynchronously', desc: 'Events are written to storage without blocking the main request path — zero latency impact on authentication.' },
+      { title: 'Persisted asynchronously', desc: 'Events are written to storage off the main request path, so authentication takes no latency hit.' },
       { title: 'Query & export',          desc: 'Query events through the admin API by type, actor, or time range. Forward to your SIEM via webhooks.' },
     ],
   },
@@ -77,22 +77,22 @@ const modules: Module[] = [
     slug: 'compass',
     name: 'Compass',
     tagline: 'Authentication Flow Engine',
-    description: 'Records every authentication attempt as a structured flow — a sequence of named steps with outcomes, timings, and error details. Deep observability into how users authenticate.',
+    description: 'Records every authentication attempt as a structured flow: named steps with their own outcomes, timings, and error details. You see how users actually authenticate.',
     color: 'amber',
     iconPath: 'M9 6.75V15m6-6v8.25m.503 3.498l4.875-2.437c.381-.19.622-.58.622-1.006V4.82c0-.836-.88-1.38-1.628-1.006l-3.869 1.934c-.317.159-.69.159-1.006 0L9.503 3.252a1.125 1.125 0 00-1.006 0L3.622 5.689C3.24 5.88 3 6.27 3 6.695V19.18c0 .836.88 1.38 1.628 1.006l3.869-1.934c.317-.159.69-.159 1.006 0l4.994 2.497c.317.158.69.158 1.006 0z',
     docsHref: '/docs/modules/default/en/compass/overview',
     pills: ['Flow Tracing', 'Step Timings', 'Error Codes', 'Auth Debugging', 'Observability', 'Pending / Success / Failure', 'Duration ms', 'Grant Types', 'PKCE', 'Authorization Code'],
     features: [
-      { title: 'Flow Recording',    desc: 'Each authentication request creates a CompassFlow — a complete record from first request to token issuance or failure.' },
-      { title: 'Step-Level Detail', desc: '7 step types tracked individually: authorize, credential validation, MFA, token exchange, IdP redirect/callback, and finalize.' },
+      { title: 'Flow Recording',    desc: 'Each authentication request opens a CompassFlow, a complete record from the first request to the token or the failure.' },
+      { title: 'Step-Level Detail', desc: 'Nine step types tracked individually: authorize, credential validation, MFA, token exchange, IdP redirect and callback, the two SAML steps, and finalize.' },
       { title: 'Per-Step Timings',  desc: 'Every step records its duration in milliseconds. Spot slow Argon2 rounds, external IdP latency, or database bottlenecks.' },
-      { title: 'Rich Error Context', desc: 'Failures include machine-readable error codes and human-readable messages — not just a 401.' },
-      { title: 'Zero Overhead Off', desc: 'When disabled, the FlowRecorder short-circuits immediately — no channels, no writes, no allocations.' },
+      { title: 'Rich Error Context', desc: 'Failures carry a machine-readable error code and a human-readable message, instead of a bare 401.' },
+      { title: 'Zero Overhead Off', desc: 'Disabled, the FlowRecorder short-circuits on entry: no channels, no writes, no allocations.' },
       { title: 'Queryable',         desc: 'Query flows by user, client, grant type, status, or time range through the admin API.' },
     ],
     steps: [
       { title: 'Flow created',         desc: 'Authentication request arrives. Compass creates a flow with realm, client, grant type, IP, and user agent.' },
-      { title: 'Steps recorded',       desc: 'Each phase of authentication — authorize, credential check, MFA, token exchange — is recorded with timing and outcome.' },
+      { title: 'Steps recorded',       desc: 'Every phase of authentication (authorize, credential check, MFA, token exchange) is recorded with its timing and outcome.' },
       { title: 'User identified',      desc: 'After successful credential validation, the user ID is attached to the flow, linking it for future queries.' },
       { title: 'Flow completed',       desc: 'Authentication finishes. The flow is marked success, failure, or expired with total duration in milliseconds.' },
     ],
@@ -101,15 +101,15 @@ const modules: Module[] = [
     slug: 'abyss',
     name: 'Abyss',
     tagline: 'Identity Provider Federation',
-    description: 'Connects FerrisKey to external identity providers. Users authenticate via Google, GitHub, Discord, or any OAuth2/OIDC provider — FerrisKey handles provisioning, linking, and attribute mapping.',
+    description: 'Connects FerrisKey to external identity providers. Users authenticate via Google, GitHub, Discord, or any OAuth2 and OIDC provider, and FerrisKey handles provisioning, linking, and attribute mapping.',
     color: 'purple',
     iconPath: 'M13.19 8.688a4.5 4.5 0 011.242 7.244l-4.5 4.5a4.5 4.5 0 01-6.364-6.364l1.757-1.757m13.35-.622l1.757-1.757a4.5 4.5 0 00-6.364-6.364l-4.5 4.5a4.5 4.5 0 001.242 7.244',
     docsHref: '/docs/modules/default/en/abyss/overview',
     pills: ['Google SSO', 'GitHub SSO', 'Discord SSO', 'OIDC', 'OAuth2', 'Account Linking', 'Auto Provisioning', 'Attribute Mapping', 'Azure AD', 'Corporate SSO'],
     features: [
-      { title: 'OAuth2 & OIDC',       desc: 'Connect any OAuth2 or OpenID Connect provider — Google, GitHub, Discord, Azure AD, or a custom corporate IdP.' },
-      { title: 'Auto Provisioning',   desc: 'New users are automatically created in FerrisKey on first federation login — no manual user creation required.' },
-      { title: 'Account Linking',     desc: 'A user can link multiple providers to the same FerrisKey account — Google and GitHub pointing to one identity.' },
+      { title: 'OAuth2 & OIDC',       desc: 'Connect any OAuth2 or OpenID Connect provider: Google, GitHub, Discord, Entra ID, or a custom corporate IdP.' },
+      { title: 'Auto Provisioning',   desc: 'New users are created in FerrisKey on their first federated login, with nobody provisioning them by hand.' },
+      { title: 'Account Linking',     desc: 'A user can link several providers to one FerrisKey account, with Google and GitHub pointing at the same identity.' },
       { title: 'Attribute Mapping',   desc: 'Map external claims (email, name, preferred_username) to FerrisKey user fields with required/optional rules.' },
       { title: 'Secret Encryption',   desc: 'Client secrets are encrypted at rest and never exposed in plaintext through the admin API.' },
       { title: 'Per-Realm Config',    desc: 'Each realm has its own provider registry. Isolate SSO configuration between tenants or environments.' },
@@ -131,17 +131,17 @@ const modules: Module[] = [
     docsHref: '/docs/modules/default/en/aegis/overview',
     pills: ['JWT Claims', 'Custom Scopes', 'Protocol Mappers', 'OIDC Standard Scopes', 'openid', 'email', 'profile', 'Role Claims', 'Custom Claims', 'Token Control'],
     features: [
-      { title: 'Client Scopes',       desc: 'Named collections of claims assigned per client. Different apps get different token contents — no one-size-fits-all.' },
+      { title: 'Client Scopes',       desc: 'Named collections of claims, assigned per client, so different apps get different token contents.' },
       { title: 'Protocol Mappers',    desc: 'Rules that extract data from the user and inject it as JWT claims. Map roles, attributes, or hardcoded values.' },
-      { title: 'Standard OIDC',       desc: 'Ships with openid, profile, email, address, phone, offline_access, and introspect scopes pre-configured.' },
+      { title: 'Standard OIDC',       desc: 'Ships with openid, profile, email, roles, address, phone, and offline_access seeded into every realm.' },
       { title: 'Default vs Optional', desc: 'Default scopes are always included. Optional scopes are only included when the client explicitly requests them.' },
-      { title: 'Custom Claims',       desc: 'Add business-specific claims — department, plan tier, feature flags — through custom protocol mapper rules.' },
+      { title: 'Custom Claims',       desc: 'Add business-specific claims (department, plan tier, feature flags) through custom protocol mapper rules.' },
       { title: 'Minimal Exposure',    desc: 'Public mobile apps get sub and email. Internal admin tools get realm_roles. Fine-grained data minimization.' },
     ],
     steps: [
       { title: 'Client requests scopes',  desc: 'During authentication, the client specifies which scopes it needs (e.g., openid email profile).' },
       { title: 'Scopes resolved',         desc: 'Aegis looks up the client\'s default scopes and merges in any requested optional scopes.' },
-      { title: 'Mappers executed',        desc: 'Each protocol mapper in the resolved scopes runs — extracting data from the user object and producing claims.' },
+      { title: 'Mappers executed',        desc: 'Each protocol mapper in the resolved scopes runs, reading the user object and producing claims.' },
       { title: 'Claims assembled',        desc: 'All claims are merged into the final JWT payload and signed. Only the requested data is included.' },
     ],
   },
@@ -149,37 +149,37 @@ const modules: Module[] = [
     slug: 'webhooks',
     name: 'Webhooks',
     tagline: 'Event-Driven Extensibility',
-    description: 'Pushes HTTP notifications to external systems when events occur in FerrisKey — user created, role assigned, secret rotated. Bridge your identity layer to the rest of your stack.',
+    description: 'Pushes HTTP notifications to external systems when something happens in FerrisKey: a user created, a role assigned, a secret rotated. It bridges the identity layer to the rest of your stack.',
     color: 'cyan',
     iconPath: 'M13.5 16.875h3.375m0 0h3.375m-3.375 0V13.5m0 3.375v3.375M6 10.5h2.25a2.25 2.25 0 002.25-2.25V6a2.25 2.25 0 00-2.25-2.25H6A2.25 2.25 0 003.75 6v2.25A2.25 2.25 0 006 10.5zm0 9.75h2.25A2.25 2.25 0 0010.5 18v-2.25a2.25 2.25 0 00-2.25-2.25H6a2.25 2.25 0 00-2.25 2.25V18A2.25 2.25 0 006 20.25zm9.75-9.75H18a2.25 2.25 0 002.25-2.25V6A2.25 2.25 0 0018 3.75h-2.25A2.25 2.25 0 0013.5 6v2.25a2.25 2.25 0 002.25 2.25z',
     docsHref: '/docs/modules/default/en/webhooks/overview',
     pills: ['HTTP POST', 'Event Subscriptions', 'Custom Headers', 'Auth Header', 'Real-Time Sync', 'CRM Integration', 'Slack Notifications', 'PagerDuty', 'SIEM Forwarding', 'Lifecycle Events'],
     features: [
-      { title: 'Event Subscriptions',  desc: 'Subscribe to specific events per webhook — user.created, auth.login, client.secret_rotated, and more.' },
+      { title: 'Event Subscriptions',  desc: 'Subscribe each webhook to the events it cares about: user.created, user.role.assigned, client.deleted, and 35 more.' },
       { title: 'Custom Headers',       desc: 'Add Authorization, X-Webhook-Secret, or any custom header to authenticate deliveries at the receiving end.' },
       { title: 'Per-Realm Scope',      desc: 'Webhooks are scoped to a realm. Each tenant can have its own set of endpoints and subscriptions.' },
       { title: 'Multiple Endpoints',   desc: 'Register as many webhooks as needed. The same event fans out to all registered subscribers in parallel.' },
-      { title: 'Last Triggered At',    desc: 'Each webhook tracks when it last fired — useful for debugging and operational monitoring.' },
+      { title: 'Last Triggered At',    desc: 'Each webhook records when it last fired, which is what you want when debugging a silent integration.' },
       { title: 'Decoupled Design',     desc: 'Your app reacts to identity events without polling FerrisKey. Clean event-driven integration.' },
     ],
     steps: [
       { title: 'Register webhook',       desc: 'Create a webhook with a target URL, optional custom headers, and a name. Scoped to a realm.' },
-      { title: 'Subscribe to events',    desc: 'Add event subscriptions — choose which lifecycle events should trigger the webhook.' },
+      { title: 'Subscribe to events',    desc: 'Add event subscriptions, choosing which lifecycle events should trigger the webhook.' },
       { title: 'Event fires',            desc: 'A matching event occurs in the realm. FerrisKey builds the payload and dispatches an HTTP POST.' },
-      { title: 'Your system responds',   desc: 'Your endpoint receives the structured payload and reacts — send an email, sync a CRM, trigger a workflow.' },
+      { title: 'Your system responds',   desc: 'Your endpoint receives the structured payload and reacts: send an email, sync a CRM, trigger a workflow.' },
     ],
   },
 ]
 
 export function getStaticPaths() {
-  // modules must be re-declared here — getStaticPaths runs in an isolated context
+  // modules must be re-declared here: getStaticPaths runs in an isolated context
   const allModules: Module[] = [
-    { slug: 'trident',  name: 'Trident',  tagline: 'Multi-Factor Authentication',  color: 'blue',    iconPath: 'M9 12.75L11.25 15 15 9.75m-3-7.036A11.959 11.959 0 013.598 6 11.99 11.99 0 003 9.749c0 5.592 3.824 10.29 9 11.623 5.176-1.332 9-6.03 9-11.622 0-1.31-.21-2.571-.598-3.751h-.152c-3.196 0-6.1-1.248-8.25-3.285z', docsHref: '/docs/modules/default/en/trident/overview',  pills: ['TOTP','WebAuthn','Passkeys','Magic Links','Recovery Codes','YubiKey','Face ID','Touch ID','RFC 6238','FIDO2'], features: [{ title:'TOTP', desc:'Time-based one-time passwords compatible with Google Authenticator, Authy, 1Password, and any RFC 6238 app.' },{ title:'WebAuthn', desc:'FIDO2 passkeys — hardware keys (YubiKey), Touch ID, Face ID, Windows Hello, and synced passkeys.' },{ title:'Magic Links', desc:'Passwordless email login. A unique short-lived link is sent to the inbox — click to authenticate.' },{ title:'Recovery Codes', desc:'One-time backup codes for account recovery when the primary MFA device is unavailable.' },{ title:'Required Actions', desc:'Enforce MFA enrollment for all new users — MFA becomes mandatory rather than optional.' },{ title:'Temporary Tokens', desc:'Short-lived tokens issued during the MFA challenge phase — cannot access protected resources.' }], steps: [{ title:'Credentials validated', desc:'User submits their username and password. FerrisKey validates and checks for configured MFA credentials.' },{ title:'MFA challenge issued', desc:'If MFA is configured, a temporary token and challenge are returned. The client prompts for the second factor.' },{ title:'Second factor verified', desc:'The user submits the OTP, passkey assertion, or clicks the magic link. Trident validates the response.' },{ title:'Full tokens issued', desc:'On success, FerrisKey issues access, refresh, and ID tokens. The session is fully established.' }] },
-    { slug: 'seawatch', name: 'SeaWatch', tagline: 'Audit & Security Events',       color: 'emerald', iconPath: 'M2.036 12.322a1.012 1.012 0 010-.639C3.423 7.51 7.36 4.5 12 4.5c4.638 0 8.573 3.007 9.963 7.178.07.207.07.431 0 .639C20.577 16.49 16.64 19.5 12 19.5c-4.638 0-8.573-3.007-9.963-7.178z M15 12a3 3 0 11-6 0 3 3 0 016 0z', docsHref: '/docs/modules/default/en/seawatch/overview', pills: ['Audit Logs','SIEM Export','SOC 2','ISO 27001','GDPR','IP Tracking','Trace IDs','OpenTelemetry','Incident Response','Anomaly Detection'], features: [{ title:'Structured Events', desc:'Every event captures actor, target, IP address, user agent, trace ID, and event-specific details in a consistent JSON schema.' },{ title:'UUIDv7 Identifiers', desc:'Time-ordered IDs make events naturally sortable and allow efficient range queries without full-table scans.' },{ title:'Actor Classification', desc:'Events distinguish between user, service account, admin, and system actions for clear accountability.' },{ title:'OTel Integration', desc:'Trace IDs link SeaWatch events to spans in Jaeger, Datadog, or any OpenTelemetry-compatible system.' },{ title:'SIEM Ready', desc:'Forward events to Splunk, Elastic, or Datadog. The structured format maps directly to common SIEM schemas.' },{ title:'Compliance Evidence', desc:'Generate SOC 2, ISO 27001, and GDPR audit evidence — query by time range, actor, or event type.' }], steps: [{ title:'Action occurs', desc:'A user logs in, an admin changes a realm setting, or a service account requests a token.' },{ title:'Event constructed', desc:'SeaWatch builds a structured event capturing who, what, when, where, and why with full context.' },{ title:'Persisted asynchronously', desc:'Events are written to storage without blocking the main request path — zero latency impact on authentication.' },{ title:'Query & export', desc:'Query events through the admin API by type, actor, or time range. Forward to your SIEM via webhooks.' }] },
-    { slug: 'compass',  name: 'Compass',  tagline: 'Authentication Flow Engine',   color: 'amber',   iconPath: 'M9 6.75V15m6-6v8.25m.503 3.498l4.875-2.437c.381-.19.622-.58.622-1.006V4.82c0-.836-.88-1.38-1.628-1.006l-3.869 1.934c-.317.159-.69.159-1.006 0L9.503 3.252a1.125 1.125 0 00-1.006 0L3.622 5.689C3.24 5.88 3 6.27 3 6.695V19.18c0 .836.88 1.38 1.628 1.006l3.869-1.934c.317-.159.69-.159 1.006 0l4.994 2.497c.317.158.69.158 1.006 0z', docsHref: '/docs/modules/default/en/compass/overview', pills: ['Flow Tracing','Step Timings','Error Codes','Auth Debugging','Observability','Pending / Success / Failure','Duration ms','Grant Types','PKCE','Authorization Code'], features: [{ title:'Flow Recording', desc:'Each authentication request creates a CompassFlow — a complete record from first request to token issuance or failure.' },{ title:'Step-Level Detail', desc:'7 step types tracked individually: authorize, credential validation, MFA, token exchange, IdP redirect/callback, and finalize.' },{ title:'Per-Step Timings', desc:'Every step records its duration in milliseconds. Spot slow Argon2 rounds, external IdP latency, or database bottlenecks.' },{ title:'Rich Error Context', desc:'Failures include machine-readable error codes and human-readable messages — not just a 401.' },{ title:'Zero Overhead Off', desc:'When disabled, the FlowRecorder short-circuits immediately — no channels, no writes, no allocations.' },{ title:'Queryable', desc:'Query flows by user, client, grant type, status, or time range through the admin API.' }], steps: [{ title:'Flow created', desc:'Authentication request arrives. Compass creates a flow with realm, client, grant type, IP, and user agent.' },{ title:'Steps recorded', desc:'Each phase of authentication — authorize, credential check, MFA, token exchange — is recorded with timing and outcome.' },{ title:'User identified', desc:'After successful credential validation, the user ID is attached to the flow, linking it for future queries.' },{ title:'Flow completed', desc:'Authentication finishes. The flow is marked success, failure, or expired with total duration in milliseconds.' }] },
-    { slug: 'abyss',    name: 'Abyss',    tagline: 'Identity Provider Federation', color: 'purple',  iconPath: 'M13.19 8.688a4.5 4.5 0 011.242 7.244l-4.5 4.5a4.5 4.5 0 01-6.364-6.364l1.757-1.757m13.35-.622l1.757-1.757a4.5 4.5 0 00-6.364-6.364l-4.5 4.5a4.5 4.5 0 001.242 7.244', docsHref: '/docs/modules/default/en/abyss/overview', pills: ['Google SSO','GitHub SSO','Discord SSO','OIDC','OAuth2','Account Linking','Auto Provisioning','Attribute Mapping','Azure AD','Corporate SSO'], features: [{ title:'OAuth2 & OIDC', desc:'Connect any OAuth2 or OpenID Connect provider — Google, GitHub, Discord, Azure AD, or a custom corporate IdP.' },{ title:'Auto Provisioning', desc:'New users are automatically created in FerrisKey on first federation login — no manual user creation required.' },{ title:'Account Linking', desc:'A user can link multiple providers to the same FerrisKey account — Google and GitHub pointing to one identity.' },{ title:'Attribute Mapping', desc:'Map external claims (email, name, preferred_username) to FerrisKey user fields with required/optional rules.' },{ title:'Secret Encryption', desc:'Client secrets are encrypted at rest and never exposed in plaintext through the admin API.' },{ title:'Per-Realm Config', desc:'Each realm has its own provider registry. Isolate SSO configuration between tenants or environments.' }], steps: [{ title:'User chooses provider', desc:'On the login page, the user selects an external provider (e.g. "Sign in with Google").' },{ title:'Redirected to IdP', desc:'FerrisKey builds the OAuth2 authorization URL and redirects the user to the external provider.' },{ title:'Callback processed', desc:'The IdP redirects back with an authorization code. Abyss exchanges it for tokens and fetches user attributes.' },{ title:'User provisioned', desc:"Abyss matches or creates a FerrisKey user, applies attribute mappings, and issues FerrisKey tokens." }] },
-    { slug: 'aegis',    name: 'Aegis',    tagline: 'Scopes & Protocol Mappers',    color: 'rose',    iconPath: 'M16.5 10.5V6.75a4.5 4.5 0 10-9 0v3.75m-.75 11.25h10.5a2.25 2.25 0 002.25-2.25v-6.75a2.25 2.25 0 00-2.25-2.25H6.75a2.25 2.25 0 00-2.25 2.25v6.75a2.25 2.25 0 002.25 2.25z', docsHref: '/docs/modules/default/en/aegis/overview', pills: ['JWT Claims','Custom Scopes','Protocol Mappers','OIDC Standard Scopes','openid','email','profile','Role Claims','Custom Claims','Token Control'], features: [{ title:'Client Scopes', desc:'Named collections of claims assigned per client. Different apps get different token contents — no one-size-fits-all.' },{ title:'Protocol Mappers', desc:'Rules that extract data from the user and inject it as JWT claims. Map roles, attributes, or hardcoded values.' },{ title:'Standard OIDC', desc:'Ships with openid, profile, email, address, phone, offline_access, and introspect scopes pre-configured.' },{ title:'Default vs Optional', desc:'Default scopes are always included. Optional scopes are only included when the client explicitly requests them.' },{ title:'Custom Claims', desc:'Add business-specific claims — department, plan tier, feature flags — through custom protocol mapper rules.' },{ title:'Minimal Exposure', desc:'Public mobile apps get sub and email. Internal admin tools get realm_roles. Fine-grained data minimization.' }], steps: [{ title:'Client requests scopes', desc:'During authentication, the client specifies which scopes it needs (e.g., openid email profile).' },{ title:'Scopes resolved', desc:"Aegis looks up the client's default scopes and merges in any requested optional scopes." },{ title:'Mappers executed', desc:'Each protocol mapper in the resolved scopes runs — extracting data from the user object and producing claims.' },{ title:'Claims assembled', desc:'All claims are merged into the final JWT payload and signed. Only the requested data is included.' }] },
-    { slug: 'webhooks', name: 'Webhooks', tagline: 'Event-Driven Extensibility',   color: 'cyan',    iconPath: 'M13.5 16.875h3.375m0 0h3.375m-3.375 0V13.5m0 3.375v3.375M6 10.5h2.25a2.25 2.25 0 002.25-2.25V6a2.25 2.25 0 00-2.25-2.25H6A2.25 2.25 0 003.75 6v2.25A2.25 2.25 0 006 10.5zm0 9.75h2.25A2.25 2.25 0 0010.5 18v-2.25a2.25 2.25 0 00-2.25-2.25H6a2.25 2.25 0 00-2.25 2.25V18A2.25 2.25 0 006 20.25zm9.75-9.75H18a2.25 2.25 0 002.25-2.25V6A2.25 2.25 0 0018 3.75h-2.25A2.25 2.25 0 0013.5 6v2.25a2.25 2.25 0 002.25 2.25z', docsHref: '/docs/modules/default/en/webhooks/overview', pills: ['HTTP POST','Event Subscriptions','Custom Headers','Auth Header','Real-Time Sync','CRM Integration','Slack Notifications','PagerDuty','SIEM Forwarding','Lifecycle Events'], features: [{ title:'Event Subscriptions', desc:'Subscribe to specific events per webhook — user.created, auth.login, client.secret_rotated, and more.' },{ title:'Custom Headers', desc:'Add Authorization, X-Webhook-Secret, or any custom header to authenticate deliveries at the receiving end.' },{ title:'Per-Realm Scope', desc:'Webhooks are scoped to a realm. Each tenant can have its own set of endpoints and subscriptions.' },{ title:'Multiple Endpoints', desc:'Register as many webhooks as needed. The same event fans out to all registered subscribers in parallel.' },{ title:'Last Triggered At', desc:'Each webhook tracks when it last fired — useful for debugging and operational monitoring.' },{ title:'Decoupled Design', desc:'Your app reacts to identity events without polling FerrisKey. Clean event-driven integration.' }], steps: [{ title:'Register webhook', desc:'Create a webhook with a target URL, optional custom headers, and a name. Scoped to a realm.' },{ title:'Subscribe to events', desc:'Add event subscriptions — choose which lifecycle events should trigger the webhook.' },{ title:'Event fires', desc:'A matching event occurs in the realm. FerrisKey builds the payload and dispatches an HTTP POST.' },{ title:'Your system responds', desc:'Your endpoint receives the structured payload and reacts — send an email, sync a CRM, trigger a workflow.' }] },
+    { slug: 'trident',  name: 'Trident',  tagline: 'Multi-Factor Authentication',  color: 'blue',    iconPath: 'M9 12.75L11.25 15 15 9.75m-3-7.036A11.959 11.959 0 013.598 6 11.99 11.99 0 003 9.749c0 5.592 3.824 10.29 9 11.623 5.176-1.332 9-6.03 9-11.622 0-1.31-.21-2.571-.598-3.751h-.152c-3.196 0-6.1-1.248-8.25-3.285z', docsHref: '/docs/modules/default/en/trident/overview',  pills: ['TOTP','WebAuthn','Passkeys','Magic Links','Recovery Codes','YubiKey','Face ID','Touch ID','RFC 6238','FIDO2'], features: [{ title:'TOTP', desc:'Time-based one-time passwords compatible with Google Authenticator, Authy, 1Password, and any RFC 6238 app.' },{ title:'WebAuthn', desc:'FIDO2 passkeys: hardware keys (YubiKey), Touch ID, Face ID, Windows Hello, and synced passkeys.' },{ title:'Magic Links', desc:'Passwordless email login. A unique short-lived link lands in the inbox, and clicking it signs the user in.' },{ title:'Recovery Codes', desc:'One-time backup codes for account recovery when the primary MFA device is unavailable.' },{ title:'Required Actions', desc:'Enforce MFA enrollment on every new user, so it is mandatory rather than optional.' },{ title:'Temporary Tokens', desc:'Short-lived tokens issued during the MFA challenge. They cannot reach a protected resource.' }], steps: [{ title:'Credentials validated', desc:'User submits their username and password. FerrisKey validates and checks for configured MFA credentials.' },{ title:'MFA challenge issued', desc:'If MFA is configured, a temporary token and challenge are returned. The client prompts for the second factor.' },{ title:'Second factor verified', desc:'The user submits the OTP, passkey assertion, or clicks the magic link. Trident validates the response.' },{ title:'Full tokens issued', desc:'On success, FerrisKey issues access, refresh, and ID tokens. The session is fully established.' }] },
+    { slug: 'seawatch', name: 'SeaWatch', tagline: 'Audit & Security Events',       color: 'emerald', iconPath: 'M2.036 12.322a1.012 1.012 0 010-.639C3.423 7.51 7.36 4.5 12 4.5c4.638 0 8.573 3.007 9.963 7.178.07.207.07.431 0 .639C20.577 16.49 16.64 19.5 12 19.5c-4.638 0-8.573-3.007-9.963-7.178z M15 12a3 3 0 11-6 0 3 3 0 016 0z', docsHref: '/docs/modules/default/en/seawatch/overview', pills: ['Audit Logs','SIEM Export','SOC 2','ISO 27001','GDPR','IP Tracking','Trace IDs','OpenTelemetry','Incident Response','Anomaly Detection'], features: [{ title:'Structured Events', desc:'Every event captures actor, target, IP address, user agent, trace ID, and event-specific details in a consistent JSON schema.' },{ title:'UUIDv7 Identifiers', desc:'Time-ordered IDs make events naturally sortable and allow efficient range queries without full-table scans.' },{ title:'Actor Classification', desc:'Events distinguish between user, service account, admin, and system actions for clear accountability.' },{ title:'OTel Integration', desc:'Trace IDs link SeaWatch events to spans in Jaeger, Datadog, or any OpenTelemetry-compatible system.' },{ title:'SIEM Ready', desc:'Forward events to Splunk, Elastic, or Datadog. The structured format maps directly to common SIEM schemas.' },{ title:'Compliance Evidence', desc:'Generate SOC 2, ISO 27001, and GDPR audit evidence by querying on time range, actor, or event type.' }], steps: [{ title:'Action occurs', desc:'A user logs in, an admin changes a realm setting, or a service account requests a token.' },{ title:'Event constructed', desc:'SeaWatch builds a structured event capturing who, what, when, where, and why with full context.' },{ title:'Persisted asynchronously', desc:'Events are written to storage off the main request path, so authentication takes no latency hit.' },{ title:'Query & export', desc:'Query events through the admin API by type, actor, or time range. Forward to your SIEM via webhooks.' }] },
+    { slug: 'compass',  name: 'Compass',  tagline: 'Authentication Flow Engine',   color: 'amber',   iconPath: 'M9 6.75V15m6-6v8.25m.503 3.498l4.875-2.437c.381-.19.622-.58.622-1.006V4.82c0-.836-.88-1.38-1.628-1.006l-3.869 1.934c-.317.159-.69.159-1.006 0L9.503 3.252a1.125 1.125 0 00-1.006 0L3.622 5.689C3.24 5.88 3 6.27 3 6.695V19.18c0 .836.88 1.38 1.628 1.006l3.869-1.934c.317-.159.69-.159 1.006 0l4.994 2.497c.317.158.69.158 1.006 0z', docsHref: '/docs/modules/default/en/compass/overview', pills: ['Flow Tracing','Step Timings','Error Codes','Auth Debugging','Observability','Pending / Success / Failure','Duration ms','Grant Types','PKCE','Authorization Code'], features: [{ title:'Flow Recording', desc:'Each authentication request opens a CompassFlow, a complete record from the first request to the token or the failure.' },{ title:'Step-Level Detail', desc:'Nine step types tracked individually: authorize, credential validation, MFA, token exchange, IdP redirect and callback, the two SAML steps, and finalize.' },{ title:'Per-Step Timings', desc:'Every step records its duration in milliseconds. Spot slow Argon2 rounds, external IdP latency, or database bottlenecks.' },{ title:'Rich Error Context', desc:'Failures carry a machine-readable error code and a human-readable message, instead of a bare 401.' },{ title:'Zero Overhead Off', desc:'Disabled, the FlowRecorder short-circuits on entry: no channels, no writes, no allocations.' },{ title:'Queryable', desc:'Query flows by user, client, grant type, status, or time range through the admin API.' }], steps: [{ title:'Flow created', desc:'Authentication request arrives. Compass creates a flow with realm, client, grant type, IP, and user agent.' },{ title:'Steps recorded', desc:'Every phase of authentication (authorize, credential check, MFA, token exchange) is recorded with its timing and outcome.' },{ title:'User identified', desc:'After successful credential validation, the user ID is attached to the flow, linking it for future queries.' },{ title:'Flow completed', desc:'Authentication finishes. The flow is marked success, failure, or expired with total duration in milliseconds.' }] },
+    { slug: 'abyss',    name: 'Abyss',    tagline: 'Identity Provider Federation', color: 'purple',  iconPath: 'M13.19 8.688a4.5 4.5 0 011.242 7.244l-4.5 4.5a4.5 4.5 0 01-6.364-6.364l1.757-1.757m13.35-.622l1.757-1.757a4.5 4.5 0 00-6.364-6.364l-4.5 4.5a4.5 4.5 0 001.242 7.244', docsHref: '/docs/modules/default/en/abyss/overview', pills: ['Google SSO','GitHub SSO','Discord SSO','OIDC','OAuth2','Account Linking','Auto Provisioning','Attribute Mapping','Azure AD','Corporate SSO'], features: [{ title:'OAuth2 & OIDC', desc:'Connect any OAuth2 or OpenID Connect provider: Google, GitHub, Discord, Entra ID, or a custom corporate IdP.' },{ title:'Auto Provisioning', desc:'New users are created in FerrisKey on their first federated login, with nobody provisioning them by hand.' },{ title:'Account Linking', desc:'A user can link several providers to one FerrisKey account, with Google and GitHub pointing at the same identity.' },{ title:'Attribute Mapping', desc:'Map external claims (email, name, preferred_username) to FerrisKey user fields with required/optional rules.' },{ title:'Secret Encryption', desc:'Client secrets are encrypted at rest and never exposed in plaintext through the admin API.' },{ title:'Per-Realm Config', desc:'Each realm has its own provider registry. Isolate SSO configuration between tenants or environments.' }], steps: [{ title:'User chooses provider', desc:'On the login page, the user selects an external provider (e.g. "Sign in with Google").' },{ title:'Redirected to IdP', desc:'FerrisKey builds the OAuth2 authorization URL and redirects the user to the external provider.' },{ title:'Callback processed', desc:'The IdP redirects back with an authorization code. Abyss exchanges it for tokens and fetches user attributes.' },{ title:'User provisioned', desc:"Abyss matches or creates a FerrisKey user, applies attribute mappings, and issues FerrisKey tokens." }] },
+    { slug: 'aegis',    name: 'Aegis',    tagline: 'Scopes & Protocol Mappers',    color: 'rose',    iconPath: 'M16.5 10.5V6.75a4.5 4.5 0 10-9 0v3.75m-.75 11.25h10.5a2.25 2.25 0 002.25-2.25v-6.75a2.25 2.25 0 00-2.25-2.25H6.75a2.25 2.25 0 00-2.25 2.25v6.75a2.25 2.25 0 002.25 2.25z', docsHref: '/docs/modules/default/en/aegis/overview', pills: ['JWT Claims','Custom Scopes','Protocol Mappers','OIDC Standard Scopes','openid','email','profile','Role Claims','Custom Claims','Token Control'], features: [{ title:'Client Scopes', desc:'Named collections of claims, assigned per client, so different apps get different token contents.' },{ title:'Protocol Mappers', desc:'Rules that extract data from the user and inject it as JWT claims. Map roles, attributes, or hardcoded values.' },{ title:'Standard OIDC', desc:'Ships with openid, profile, email, roles, address, phone, and offline_access seeded into every realm.' },{ title:'Default vs Optional', desc:'Default scopes are always included. Optional scopes are only included when the client explicitly requests them.' },{ title:'Custom Claims', desc:'Add business-specific claims (department, plan tier, feature flags) through custom protocol mapper rules.' },{ title:'Minimal Exposure', desc:'Public mobile apps get sub and email. Internal admin tools get realm_roles. Fine-grained data minimization.' }], steps: [{ title:'Client requests scopes', desc:'During authentication, the client specifies which scopes it needs (e.g., openid email profile).' },{ title:'Scopes resolved', desc:"Aegis looks up the client's default scopes and merges in any requested optional scopes." },{ title:'Mappers executed', desc:'Each protocol mapper in the resolved scopes runs, reading the user object and producing claims.' },{ title:'Claims assembled', desc:'All claims are merged into the final JWT payload and signed. Only the requested data is included.' }] },
+    { slug: 'webhooks', name: 'Webhooks', tagline: 'Event-Driven Extensibility',   color: 'cyan',    iconPath: 'M13.5 16.875h3.375m0 0h3.375m-3.375 0V13.5m0 3.375v3.375M6 10.5h2.25a2.25 2.25 0 002.25-2.25V6a2.25 2.25 0 00-2.25-2.25H6A2.25 2.25 0 003.75 6v2.25A2.25 2.25 0 006 10.5zm0 9.75h2.25A2.25 2.25 0 0010.5 18v-2.25a2.25 2.25 0 00-2.25-2.25H6a2.25 2.25 0 00-2.25 2.25V18A2.25 2.25 0 006 20.25zm9.75-9.75H18a2.25 2.25 0 002.25-2.25V6A2.25 2.25 0 0018 3.75h-2.25A2.25 2.25 0 0013.5 6v2.25a2.25 2.25 0 002.25 2.25z', docsHref: '/docs/modules/default/en/webhooks/overview', pills: ['HTTP POST','Event Subscriptions','Custom Headers','Auth Header','Real-Time Sync','CRM Integration','Slack Notifications','PagerDuty','SIEM Forwarding','Lifecycle Events'], features: [{ title:'Event Subscriptions', desc:'Subscribe each webhook to the events it cares about: user.created, user.role.assigned, client.deleted, and 35 more.' },{ title:'Custom Headers', desc:'Add Authorization, X-Webhook-Secret, or any custom header to authenticate deliveries at the receiving end.' },{ title:'Per-Realm Scope', desc:'Webhooks are scoped to a realm. Each tenant can have its own set of endpoints and subscriptions.' },{ title:'Multiple Endpoints', desc:'Register as many webhooks as needed. The same event fans out to all registered subscribers in parallel.' },{ title:'Last Triggered At', desc:'Each webhook records when it last fired, which is what you want when debugging a silent integration.' },{ title:'Decoupled Design', desc:'Your app reacts to identity events without polling FerrisKey. Clean event-driven integration.' }], steps: [{ title:'Register webhook', desc:'Create a webhook with a target URL, optional custom headers, and a name. Scoped to a realm.' },{ title:'Subscribe to events', desc:'Add event subscriptions, choosing which lifecycle events should trigger the webhook.' },{ title:'Event fires', desc:'A matching event occurs in the realm. FerrisKey builds the payload and dispatches an HTTP POST.' },{ title:'Your system responds', desc:'Your endpoint receives the structured payload and reacts: send an email, sync a CRM, trigger a workflow.' }] },
   ]
   return allModules.map(m => ({ params: { module: m.slug }, props: { mod: m, otherModules: allModules.filter(x => x.slug !== m.slug) } }))
 }
@@ -197,7 +197,7 @@ const colorMap: Record<string, { bg: string; border: string; text: string; pill:
 const c = colorMap[mod.color]
 ---
 
-<Base title={`${mod.name} — ${mod.tagline} | Ferriskey`} description={mod.description}>
+<Base title={`${mod.name}: ${mod.tagline} | Ferriskey`} description={mod.description}>
   <WebsiteNavbar appUrlOverrides={appUrlOverrides} client:load transition:persist />
 
   <main>
@@ -273,14 +273,14 @@ const c = colorMap[mod.color]
                 <text x="180" y="68" text-anchor="middle" fill="#10b981" fill-opacity="0.45" font-size="9" font-family="monospace" letter-spacing="1">audit.log</text>
                 <g class="sea-row" style="animation-delay:0.1s">
                   <circle cx="68" cy="103" r="3.5" fill="#10b981" fill-opacity="0.7"/>
-                  <text x="81" y="107" fill="#34d399" font-size="9.5" font-family="monospace">auth.login</text>
+                  <text x="81" y="107" fill="#34d399" font-size="9.5" font-family="monospace">user.role.assigned</text>
                   <text x="244" y="107" fill="#10b981" fill-opacity="0.4" font-size="9" font-family="monospace">12:41:03</text>
                   <text x="81" y="119" fill="#10b981" fill-opacity="0.4" font-size="8.5" font-family="monospace">user@corp.io · realm/main</text>
                 </g>
                 <line x1="60" y1="127" x2="300" y2="127" stroke="#10b981" stroke-opacity="0.08" stroke-width="0.5" class="sea-row" style="animation-delay:0.1s"/>
                 <g class="sea-row" style="animation-delay:0.7s">
                   <circle cx="68" cy="141" r="3.5" fill="#fbbf24" fill-opacity="0.7"/>
-                  <text x="81" y="145" fill="#34d399" font-size="9.5" font-family="monospace">client.secret_rotated</text>
+                  <text x="81" y="145" fill="#34d399" font-size="9.5" font-family="monospace">client.updated</text>
                   <text x="244" y="145" fill="#10b981" fill-opacity="0.4" font-size="9" font-family="monospace">12:41:07</text>
                   <text x="81" y="157" fill="#10b981" fill-opacity="0.4" font-size="8.5" font-family="monospace">admin · client/api-gateway</text>
                 </g>
diff --git a/apps/website/src/pages/modules/index.astro b/apps/website/src/pages/modules/index.astro
index 2b62df9..a3958aa 100644
--- a/apps/website/src/pages/modules/index.astro
+++ b/apps/website/src/pages/modules/index.astro
@@ -27,7 +27,7 @@ const colorMap: Record<string, { bg: string; border: string; text: string }> = {
 }
 ---
 
-<Base title="Modules — Ferriskey" description="Purpose-built systems for authentication, audit, federation, and more.">
+<Base title="Modules | Ferriskey" description="Purpose-built systems for authentication, audit, federation, and more.">
   <WebsiteNavbar appUrlOverrides={appUrlOverrides} client:load transition:persist />
 
   <main class="w-full pt-32 pb-24">
diff --git a/apps/website/src/pages/release-notes.astro b/apps/website/src/pages/release-notes.astro
index c46e538..dc5f70a 100644
--- a/apps/website/src/pages/release-notes.astro
+++ b/apps/website/src/pages/release-notes.astro
@@ -16,7 +16,7 @@ const translations = ui.fr
 const firstRelease = releaseNotes[releaseNotes.length - 1]
 
 // One flat, chronological list (newest first) instead of a nested
-// milestone/patch grouping — every release gets the same card shape, told
+// milestone/patch grouping: every release gets the same card shape, told
 // apart only by its badge, title weight, and a colored accent for milestones.
 const kindKey = {
   patch: 'releaseNotes.patch',
@@ -46,7 +46,7 @@ function formatDate(date: string, locale = 'en-US') {
 ---
 
 <Base
-  title="Release Notes — Ferriskey"
+  title="Release Notes | Ferriskey"
   description="A curated timeline of Ferriskey releases, from the first stable baseline to federation, observability, and recovery flows."
 >
   <WebsiteNavbar appUrlOverrides={appUrlOverrides} client:load transition:persist />
diff --git a/apps/website/src/pages/roadmap.astro b/apps/website/src/pages/roadmap.astro
index f196114..1c15710 100644
--- a/apps/website/src/pages/roadmap.astro
+++ b/apps/website/src/pages/roadmap.astro
@@ -29,7 +29,7 @@ const columnAccent = {
 ---
 
 <Base
-  title="Roadmap — Ferriskey"
+  title="Roadmap | Ferriskey"
   description="A directional roadmap for Ferriskey, showing what is being worked on now, what comes next, and what is being explored later."
 >
   <WebsiteNavbar appUrlOverrides={appUrlOverrides} client:load transition:persist />