docs: resync the documentation with FerrisKey 0.8.0

[LeadcodeDev]

Why

The documentation's API inventory was built from the committed openapi.json. That file is 36 operations behind the code (193 vs 229), reports 0.7.0, and still describes one path that has since moved — so anything derived from it inherits the drift.

This pass rebuilds the inventory from ferriskey-api gen-api, the spec the binary prints from its own utoipa annotations, with no database needed. Every claim below was checked against the source in ferriskey and ferriskey-cli.

Pages that no longer matched the code

Page	What was wrong
aegis/protocol-mappers, aegis/custom-claims	An invented config schema (claim_name, add_to_access_token, claim_type). The mapper engine reads dotted Keycloak keys — claim.name, access.token.claim, jsonType.label. Since config is free-form JSON the API accepted the documented payloads and then ignored them, so every example produced a mapper that silently did nothing. client-scopes.mdx already had the right schema.
abyss/providers	Told you to register /broker/{alias}/callback at Google, GitHub and Discord. FerrisKey sends /broker/{alias}/endpoint, so the documented setup failed with redirect_uri_mismatch on all three.
seawatch/querying, compass/querying	Pointed at an invented /admin/realms/… prefix; real paths carry /v1. Filters that do not exist, responses documented unwrapped when they are enveloped in data, and a time range on Compass flows that the handler hardcodes to None.
core-concepts/realms	Five settings documented under their SQL column names (access_token_lifetime_secs, …). The payload has no deny_unknown_fields, so those calls return 200 and change nothing.
core-concepts/roles	manage_organizations and view_organizations missing; the permission model now resolves through a 95-entry action catalogue.
maintenance	The realm whitelist moved from /clients/settings/… to /settings/….

Plus smaller ones: scopes_supported documented in a discovery document that does not emit it, the operator example pinned to an old version, and an AuthZen claim that contradicted its own page.

Features that had no page

• LDAP user federation — announced as "planned" while shipped, with ldap3, seven endpoints, sync modes and connection testing. The most costly gap: an evaluator looking for Active Directory concluded the product did not do it.
• Portal themes and layouts — 18 endpoints, zero mention.
• Self-service account under /users/me — 12 endpoints, including a well-designed elevation model where a second factor cannot rotate the factor set it belongs to.
• Maintenance mode, password policy, webhook deliveries and retries, the export/import family, and the Supabase import source from ferriskey-cli.

Structure

SAML moves out of Modules and in beside Authentication as the second protocol FerrisKey speaks. The authentication page now presents both and makes explicit that they share one chain — same login, MFA, lockout and audit — with Compass recording saml_authn_request and saml_assertion as their own steps.

Also fixes the CLI commands index hoisting a duplicate Overview to the section root (Astro drops the index segment from the id, so the page landed outside its own group), and capitalises the command page titles.

Screenshots

All retaken against the 0.8.0 console as light/dark pairs, swapped by two classes added to globals.css — plain CSS rather than Tailwind dark: utilities, which are not guaranteed to be generated from .mdx sources. 24 pairs, matched dimensions, no orphans.

Verification

• astro build green — 89 pages.
• Every internal link and every #anchor resolved against the ids in the built HTML.
• Every referenced image exists; every -light has its -dark.
• Endpoint coverage: 229/229, each remaining matcher miss verified by hand as a false negative from abbreviated path notation.

Left for the upstream repo

Three findings belong in ferriskey, not here, and are deliberately not touched: openapi.json should be generated in CI and fail on drift; the /users/me credential operations write no audit event; and check_breached, Kerberos federation and RFC 8693 token exchange are modelled but not served — the docs now say so rather than implying they work.

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: e2c23547-76d4-4366-8d1f-abcc014dd143

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}