docs: publish English public documentation

docs/install/authentik.md

@@ -1,37 +1,41 @@
-# Authentik provider setup
+# Authentik provider configuration
 
-Authentik is the first certified provider for PSD acceptance. The ThothII browser protocol remains
-generic OIDC; these steps configure the provider-specific group catalog only.
+ThothII uses generic OIDC in the browser. Authentik provides the identity provider and group
+catalog without adding a proprietary login flow.
 
-1. Create an OAuth2/OIDC application and provider in Authentik. Register exactly
-   `<publicUrl>/api/auth/oidc/callback` as the callback and enable `openid`, `profile`, and `email`.
-2. Configure the provider so the ID token contains a direct `groups` array of strings. Verify the
-   claim with a disposable test identity before running acceptance.
-3. Create a dedicated API service account for the group catalog. Grant group-view-only privilege;
-   do not grant write, user-management, or directory-administration privilege. Put its bearer value
-   in the protected bundle under `THT_AUTHENTIK_API_TOKEN`.
-4. Create or confirm the exact groups `TOT Users` and `TOT Admin`. Map them explicitly in
-   `auth.yaml` to `user` and `admin`, respectively. Keep other upstream groups out of the mapping.
-5. Run Workspace Validate for static authentication validation. Then run live non-interactive
-   diagnosis, followed by the optional device-flow identity check:
+```mermaid
+sequenceDiagram
+    participant Browser
+    participant ThothII
+    participant Authentik
+    Browser->>ThothII: Sign in
+    ThothII->>Authentik: Authorization Code with PKCE
+    Authentik-->>Browser: Login and consent
+    Browser->>ThothII: Callback with code
+    ThothII->>Authentik: Token exchange
+    Authentik-->>ThothII: Identity and groups
+    ThothII-->>Browser: Opaque session
+```
 
-   ```sh
-   tht auth check
-   tht auth check --interactive
-   tht doctor --json
-   ```
+## OIDC provider
 
-6. Run Workspace Test for aggregate live workspace and authentication validation. It must prove
-   discovery/JWKS, catalog access, and every configured group. The diagnostic result must contain
-   no secret values. `tht doctor --json` reports `authentication` after `configuration` and before
-   `services` in its exact ordered checklist.
+1. Create an OAuth2/OIDC application and provider.
+2. Register exactly `PUBLIC_URL/api/auth/oidc/callback`.
+3. Enable the `openid`, `profile`, and `email` scopes.
+4. Configure a direct `groups` claim as an array of strings.
 
-Only configured exact group names are queried. Additional Authentik or directory groups are ignored
-silently, without a warning. A mapped group absent from Authentik fails closed with
-`oidc_mapped_group_missing`; an ambiguous exact-name result uses
-`oidc_mapped_group_ambiguous`. A group visible only in an upstream directory but not represented
-in Authentik is missing from ThothII’s catalog and must not be treated as present.
+## Group catalog
 
-Rotate the two credentials independently through the protected secret-file procedure, then repeat
-`tht auth check` and workspace Test. Never put either value in this guide, YAML, shell history,
-diagnostic output, or acceptance evidence.
+Create a dedicated service account with read-only access to groups. Store its token in the
+protected bundle as `THT_AUTHENTIK_API_TOKEN`.
+
+Map the exact enterprise group names to the ThothII `user` and `admin` roles in `auth.yaml`.
+Unmapped groups are ignored. A configured group that does not exist produces a closed error.
+
+## Diagnostics
+
+`tht auth check` checks discovery, the issuer, JWKS, catalog access, and the configured groups.
+The `--interactive` option also verifies identity through device flow when the provider supports it.
+
+Rotate the OIDC secret and group-catalog token separately. Neither may appear in YAML, shell
+history, logs, or diagnostic output.