docs: focus public documentation on product usage

docs/install/authentik.md

@@ -1,37 +1,42 @@
-# Authentik provider setup
+# Configurazione del provider Authentik
 
-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.
+Il protocollo browser di ThothII è OIDC generico. Authentik fornisce il catalogo gruppi e il
+provider di identità senza introdurre un percorso di login proprietario.
 
-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
-   ```
+## Provider OIDC
 
-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. Creare applicazione e provider OAuth2/OIDC.
+2. Registrare esattamente `PUBLIC_URL/api/auth/oidc/callback`.
+3. Abilitare gli scope `openid`, `profile` ed `email`.
+4. Configurare un claim diretto `groups` come array di stringhe.
 
-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.
+## Catalogo gruppi
 
-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.
+Creare un account di servizio dedicato con sola lettura dei gruppi. Conservare il token nel
+bundle protetto come `THT_AUTHENTIK_API_TOKEN`.
+
+Mappare in `auth.yaml` i nomi esatti dei gruppi aziendali ai ruoli ThothII `user` e `admin`.
+Gruppi non mappati vengono ignorati; un gruppo configurato ma assente genera un errore chiuso.
+
+## Diagnostica
+
+`tht auth check` controlla discovery, issuer, JWKS, accesso al catalogo e presenza dei gruppi
+configurati. L'opzione `--interactive` aggiunge la verifica dell'identità tramite device flow,
+quando il provider la supporta.
+
+Ruotare separatamente secret OIDC e token del catalogo gruppi. Nessuno dei due deve comparire in
+YAML, cronologia shell, log o output diagnostico.