docs(roles): add argument_specs and README for traefik, authentik, drawio, garage, nextcloud

Each of the five roles touched in this branch now ships:

* meta/argument_specs.yml: typed schema for every variable in
  defaults/main.yml plus the optional inputs surfaced via this
  branch (traefik_extra_hosts, authentik_host_rewrite_domains,
  authentik_proxy_apps.mode / .allowed_groups, drawio_extra_domains,
  drawio_authentik_forward_auth*, garage_webui_authentik_forward_auth*).
  All five specs load cleanly through ansible-core's
  ArgumentSpecValidator.

* README.md: replaces the ansible-galaxy boilerplate (where it was
  still in place) with a focused write-up — service vars, required
  secrets, ForwardAuth/idempotency notes, dependencies, and a working
  example playbook. authentik and garage READMEs are rewritten to cover
  the new knobs while preserving their existing content.

roles/authentik/README.md

@@ -1,28 +1,131 @@
 # Authentik
 
-Deploys Authentik identity provider with Docker Compose.
+Deploys [authentik](https://goauthentik.io) (server + worker + Postgres)
+as a Docker Compose stack behind Traefik, with all resources provisioned
+via templated blueprints.
+
+## What this role does
+
+- Renders the Compose stack with traefik labels and an optional
+  split-horizon host rewrite (see below)
+- Provisions local users, groups, OIDC apps, Proxy/ForwardAuth apps,
+  LDAP apps and outposts, and Entra ID OAuth sources via blueprints
+- Configures the login screen (visible sources, local login fields)
+- Supports declarative cleanup via `authentik_removed_*` lists
 
 ## Variables
 
-See `defaults/main.yml` for all available variables.
+Full spec with types and defaults: `meta/argument_specs.yml`. The most
+common overrides:
 
-## Blueprints
+### Service
+
+- `authentik_domains` (required, list): FQDNs the router accepts. First
+  entry is the canonical hostname; further entries cover internal
+  `*.int.*` names for server-to-server traffic.
+- `authentik_secret_key` (required): PG fernet / signing secret.
+  Generate with `openssl rand -base64 60`.
+- `authentik_postgres_password` (required).
+- `authentik_image`, `authentik_port`, `authentik_log_level`.
+
+### Split-horizon host rewrite
+
+`authentik_host_rewrite_domains` lists hostnames that should reach the
+authentik container but make it generate URLs (OIDC issuer, password
+reset links, etc.) as if the request had arrived on
+`authentik_domains[0]`.
+
+For each entry the role:
+
+- Creates a dedicated traefik router on that hostname
+- Routes it to a URL-based loadbalancer service that disables
+  `passHostHeader`, so the upstream Host header becomes the canonical
+  FQDN
+- Pins `X-Forwarded-Host` via middleware so the iss claim stays aligned
+  with the public hostname browsers see
+
+Use case: an internal `auth.int.example.com` keeps server-to-server
+traffic in the LAN, but Keycloak/Nextcloud/etc. still receive issuer
+URLs matching `auth.example.com`.
+
+### Blueprints
 
 The role renders blueprints for:
+
 - Local users (`authentik_local_users`)
+- Groups (`authentik_groups`)
 - OIDC applications (`authentik_oidc_apps`)
 - Proxy applications (`authentik_proxy_apps`)
 - Proxy outposts (`authentik_proxy_outposts`)
+- LDAP applications (`authentik_ldap_apps`)
+- LDAP outpost (`authentik_ldap_outpost`)
 - Entra ID sources (`authentik_entra_sources`)
-- Login screen sources (`authentik_login_source_ids`)
+- Login-screen source visibility (`authentik_login_sources`)
 
-Secrets are passed via `authentik_blueprint_env` using environment variable references.
+Secrets are passed via the `authentik_blueprint_env` env-var indirection
+so they never land in rendered blueprint YAML on disk.
+
+#### Proxy apps: mode and group restrictions
+
+Each entry in `authentik_proxy_apps` supports:
+
+- `mode` (default `forward_single`): one of `proxy`, `forward_single`,
+  `forward_domain`
+- `allowed_groups`: when set, a `PolicyBinding` is emitted per group on
+  the application. authentik OR-evaluates bindings, so users in any
+  listed group pass and users in none are denied.
+
+Example:
+
+```yaml
+authentik_proxy_apps:
+  - slug: drawio
+    name: drawio
+    external_host: "https://drawio.example.com"
+    mode: forward_single
+    allowed_groups:
+      - drawio-users
+      - admins
+```
 
 ## Removing resources
 
-To remove resources from Authentik, move slugs to the removal lists:
+Move slugs from the active list to the matching removal list:
+
 - `authentik_removed_oidc_apps`
 - `authentik_removed_proxy_apps`
 - `authentik_removed_local_users`
 
-After confirming deletion, remove the slug from the list.
+After authentik has applied the deletion blueprint, remove the slug
+from the list to keep state clean.
+
+## Dependencies
+
+- Traefik network (`authentik_traefik_network`, default `proxy`)
+- Internal backend network (`authentik_backend_network`, default `backend`)
+
+## Example playbook
+
+```yaml
+- hosts: identity_servers
+  roles:
+    - role: digitalboard.core.authentik
+      vars:
+        authentik_domains:
+          - "auth.example.com"
+          - "auth.int.example.com"
+        authentik_host_rewrite_domains:
+          - "auth.int.example.com"
+        authentik_secret_key: "{{ vault_authentik_secret_key }}"
+        authentik_postgres_password: "{{ vault_authentik_pg_password }}"
+        authentik_proxy_apps:
+          - slug: drawio
+            name: drawio
+            external_host: "https://drawio.example.com"
+            mode: forward_single
+            allowed_groups: [drawio-users]
+```
+
+## License
+
+MIT-0

roles/authentik/meta/argument_specs.yml

@@ -0,0 +1,193 @@
+---
+argument_specs:
+  main:
+    short_description: Deploy authentik (server + worker + Postgres) via Docker Compose.
+    description:
+      - Renders a Compose stack for authentik with traefik labels, optional
+        TLS and a configurable split-horizon host-rewrite that keeps the OIDC
+        issuer URL on the canonical public hostname even when traffic enters
+        on an internal FQDN.
+      - Provisions resources through templated blueprints
+        (local users, groups, OIDC/Proxy/LDAP apps, outposts, OAuth sources).
+    options:
+      docker_compose_base_dir:
+        type: path
+        default: /etc/docker/compose
+      docker_volume_base_dir:
+        type: path
+        default: /srv/data
+      authentik_service_name:
+        type: str
+        default: authentik
+      authentik_docker_compose_dir:
+        type: path
+        description: Defaults to C({{ docker_compose_base_dir }}/{{ authentik_service_name }}).
+      authentik_docker_volume_dir:
+        type: path
+        description: Defaults to C({{ docker_volume_base_dir }}/{{ authentik_service_name }}).
+
+      authentik_domains:
+        type: list
+        elements: str
+        required: true
+        description:
+          - FQDNs the authentik router accepts. The first entry is the
+            canonical (public) hostname and is used for the network alias,
+            the X-Forwarded-Host rewrite target, and as the default OIDC
+            issuer. Further entries cover internal C(*.int.*) names used
+            for server-to-server traffic.
+      authentik_host_rewrite_domains:
+        type: list
+        elements: str
+        default: []
+        description:
+          - Hostnames that should reach authentik but make it generate URLs
+            (OIDC issuer, password reset links, etc.) as if the request had
+            arrived on C(authentik_domains[0]).
+          - Each entry gets its own traefik router and a URL-based
+            loadbalancer service that disables passHostHeader and pins
+            X-Forwarded-Host via middleware. Used for split-horizon setups
+            where the LAN keeps server-to-server traffic but the iss claim
+            must match the public hostname browsers see.
+      authentik_image:
+        type: str
+        default: ghcr.io/goauthentik/server:2026.2.2
+      authentik_port:
+        type: int
+        default: 9000
+      authentik_secret_key:
+        type: str
+        required: true
+        description: PG fernet key / signing secret. Generate with C(openssl rand -base64 60).
+
+      authentik_postgres_image:
+        type: str
+        default: postgres:16-alpine
+      authentik_postgres_db:
+        type: str
+        default: authentik
+      authentik_postgres_user:
+        type: str
+        default: authentik
+      authentik_postgres_password:
+        type: str
+        required: true
+
+      authentik_traefik_network:
+        type: str
+        default: proxy
+      authentik_backend_network:
+        type: str
+        default: backend
+      authentik_use_ssl:
+        type: bool
+        default: true
+
+      authentik_log_level:
+        type: str
+        choices: [trace, debug, info, warning, error]
+        default: info
+      authentik_error_reporting_enabled:
+        type: bool
+        default: false
+
+      authentik_proxy_apps:
+        type: list
+        elements: dict
+        default: []
+        description:
+          - Proxy/ForwardAuth applications rendered via the
+            C(blueprint-proxy-app.yaml.j2) template.
+        options:
+          slug:
+            type: str
+            required: true
+          name:
+            type: str
+            required: true
+          internal_host:
+            type: str
+            description: Required when C(mode=proxy).
+          external_host:
+            type: str
+            required: true
+          mode:
+            type: str
+            choices: [proxy, forward_single, forward_domain]
+            default: forward_single
+            description:
+              - "C(proxy): the outpost itself proxies traffic to internal_host."
+              - "C(forward_single): a single app behind an external reverse
+                proxy via ForwardAuth."
+              - "C(forward_domain): wildcard mode — one provider guards every
+                host on a cookie domain."
+          allowed_groups:
+            type: list
+            elements: str
+            description:
+              - If set, PolicyBindings are emitted (one per group, OR-evaluated).
+                Users in none of the listed groups are denied.
+          skip_path_regex:
+            type: str
+          flows:
+            type: dict
+            description: Authentication / authorization / invalidation flow slugs.
+
+      authentik_proxy_outposts:
+        type: list
+        elements: dict
+        default: []
+
+      authentik_ldap_apps:
+        type: list
+        elements: dict
+        default: []
+      authentik_ldap_outpost:
+        type: dict
+        default: {}
+
+      authentik_oidc_apps:
+        type: list
+        elements: dict
+        default: []
+
+      authentik_entra_sources:
+        type: list
+        elements: dict
+        default: []
+      authentik_login_sources:
+        type: list
+        elements: dict
+        default: []
+      authentik_identification_stage_name:
+        type: str
+        default: default-authentication-identification
+      authentik_login_user_fields:
+        type: list
+        elements: str
+        choices: [username, email, upn]
+        default: [username, email]
+        description: Local login fields shown on the login screen. Empty list hides local login.
+
+      authentik_groups:
+        type: list
+        elements: dict
+        default: []
+      authentik_local_users:
+        type: list
+        elements: dict
+        default: []
+
+      authentik_removed_oidc_apps:
+        type: list
+        elements: str
+        default: []
+        description: OIDC application slugs scheduled for deletion.
+      authentik_removed_proxy_apps:
+        type: list
+        elements: str
+        default: []
+      authentik_removed_local_users:
+        type: list
+        elements: str
+        default: []