docs: clarify Authelia access_control merge with before/after example

The duplicate-block pitfall (YAML silently ignores duplicate keys, causing
a white screen) is now called out explicitly in both the script's printed
output and the README. Added a before/after example showing the correct
merged result with the kiosk one_factor rule above the two_factor wildcard.
Also explains why one_factor is required (TOTP/WebAuthn need interactive
second step, impossible via API).

https://claude.ai/code/session_01EyjEQLWbTXcZgbMDarf7NU

Readme.md

@@ -158,19 +158,33 @@ kiosk:
 
 **Step 3 — MERGE into `~/docker/authelia/config/configuration.yml`** (do not replace your existing config):
 
-**access_control** — Add the kiosk rule **ABOVE** any existing `two_factor` rule. Authelia applies rules top-down — first match wins:
+**access_control** — Find your **existing** `access_control:` block and add the kiosk rule as the **first** rule inside it.
 
+> **Do NOT create a second `access_control:` block.** YAML silently ignores duplicate keys — Authelia will never see the kiosk rule and the kiosk will get a white screen.
+
+Authelia reads rules top-down — first match wins. The kiosk rule **must** sit above any `two_factor` wildcard rule, otherwise the wildcard matches first.
+
+**Why `one_factor`?** The kiosk authenticates via the API (`/api/firstfactor` — password only). TOTP and WebAuthn require an interactive second step that is impossible from a script, so the kiosk group must use `one_factor`.
+
+*Before (your existing config):*
 ```yaml
 access_control:
   default_policy: deny
   rules:
-    # ADD THIS — kiosk can only do one_factor (no TOTP/WebAuthn via API)
     - domain: '*.yourdomain.com'
+      policy: two_factor
+```
+
+*After (add kiosk rule above the two_factor rule — same block, not a new one):*
+```yaml
+access_control:
+  default_policy: deny
+  rules:
+    - domain: '*.yourdomain.com'   # kiosk first — one_factor only
       subject: 'group:kiosk'
       policy: one_factor
-    # Keep your existing rules below — e.g.:
-    # - domain: '*.yourdomain.com'
-    #   policy: two_factor
+    - domain: '*.yourdomain.com'   # existing rule stays below
+      policy: two_factor
 ```
 
 **session** — Keep your existing session block as-is; no changes needed. The kiosk re-authenticates via API on every startup so session expiry barely matters for it.

ubuntu-based-kiosk-v1.0.2.sh

@@ -10055,19 +10055,39 @@ process.stdout.write(Buffer.concat([iv,enc]).toString('base64'));
     echo "3. MERGE into ~/docker/authelia/config/configuration.yml:"
     echo
     echo "   ── access_control ─────────────────────────────────────"
-    echo "   Add the kiosk rule ABOVE any existing two_factor rule."
-    echo "   Authelia applies rules top-down — first match wins."
+    echo "   Find your EXISTING access_control block and add the"
+    echo "   kiosk rule as the FIRST rule inside it."
     echo
+    echo "   !! DO NOT create a second access_control: block !!"
+    echo "   YAML silently ignores duplicate keys — the kiosk rule"
+    echo "   will be invisible to Authelia and you will get a white"
+    echo "   screen on the kiosk."
+    echo
+    echo "   Authelia reads rules top-down, first match wins."
+    echo "   The kiosk rule MUST be above any two_factor rule or"
+    echo "   the two_factor wildcard will match first."
+    echo
+    echo "   ── EXAMPLE — before (your existing config): ──────────"
     echo "   access_control:"
     echo "     default_policy: deny"
     echo "     rules:"
-    echo "       # ADD THIS — kiosk can only do one_factor (no TOTP/WebAuthn via API)"
     echo "       - domain: '*.yourdomain.com'"
+    echo "         policy: two_factor"
+    echo
+    echo "   ── EXAMPLE — after (add kiosk rule above two_factor): ─"
+    echo "   access_control:"
+    echo "     default_policy: deny"
+    echo "     rules:"
+    echo "       - domain: '*.yourdomain.com'       # <-- kiosk first"
     echo "         subject: 'group:kiosk'"
     echo "         policy: one_factor"
-    echo "       # Keep your existing rules below — e.g.:"
-    echo "       # - domain: '*.yourdomain.com'"
-    echo "       #   policy: two_factor"
+    echo "       - domain: '*.yourdomain.com'       # <-- existing"
+    echo "         policy: two_factor"
+    echo
+    echo "   Why one_factor? The kiosk authenticates via the API"
+    echo "   (/api/firstfactor — password only). TOTP and WebAuthn"
+    echo "   require a second interactive step that is impossible"
+    echo "   from a script, so the kiosk group must use one_factor."
     echo
     echo "   ── session ─────────────────────────────────────────────"
     echo "   Keep your existing session block — no changes needed."