Embed paste-ready Caddy snippets next to each access_control case

Each of the four cases in access_control.rules now carries an inline,
clearly-labeled "ALSO PASTE INTO CADDYFILE" block above the
uncommentable Authelia rule, so the user editing configuration.yml
sees both halves of the gate in one place. Case 2a additionally shows
the matching frigate_config/config.yml edit; case 4 has no Authelia
rule but still shows the Caddy block to make the absence explicit.

Caddy blocks use {env.DOMAIN}, Authelia rules use {{ env "DOMAIN" }} --
matching what's already in caddy/snippets.caddyfile and the
configuration.yml header.

https://claude.ai/code/session_013XZ1vmgk78k2PEQ5DmJhF3

authelia/configuration.yml

@@ -109,32 +109,103 @@ access_control:
     - domain: 'auth.{{ env "DOMAIN" }}'
       policy: 'bypass'
 
-    # -------------------------------------------------------------------
-    # CASE 1: No app auth -- Authelia is the only gate.
-    # The Pi doorbell PTT page has no built-in authentication.
-    # two_factor is appropriate -- this URL controls a speaker in your house.
-    # -------------------------------------------------------------------
+    # ===================================================================
+    # CASE 1 -- No app auth. Authelia is the only gate.
+    # Example: Pi doorbell PTT page (Flask server, no built-in auth).
+    # two_factor is right -- this URL controls a speaker in your house.
+    #
+    # ALSO PASTE INTO CADDYFILE (case 1 site block):
+    #   doorbell.{env.DOMAIN} {
+    #       import accesslog
+    #       import authelia
+    #       handle_path /frigate/* {
+    #           reverse_proxy 192.168.x.x:8971       # CHANGE: Frigate IP
+    #       }
+    #       handle {
+    #           reverse_proxy 192.168.x.x:5555       # CHANGE: Pi IP
+    #       }
+    #   }
+    # ===================================================================
     # - domain: 'doorbell.{{ env "DOMAIN" }}'
     #   policy: 'two_factor'
 
-    # -------------------------------------------------------------------
-    # CASE 2: App supports trusted-header proxy auth -- replace app login.
-    # Frigate: set auth.enabled: False and configure proxy: in
-    # frigate_config/config.yml (see README.md). Authelia handles login
-    # and passes Remote-User/Remote-Groups to Frigate for role mapping.
-    # -------------------------------------------------------------------
+    # ===================================================================
+    # CASE 2a -- App supports trusted-header proxy auth.
+    # Authelia replaces the app's login form. Single login; the app reads
+    # Remote-User from the upstream request for its own role mapping.
+    # Example: Frigate 0.14+.
+    #
+    # ALSO PASTE INTO CADDYFILE (case 2a site block):
+    #   cam.{env.DOMAIN} {
+    #       import accesslog
+    #       import authelia
+    #       reverse_proxy 192.168.x.x:8971 {         # CHANGE: Frigate IP
+    #           transport http { read_timeout 60s; write_timeout 60s }
+    #           # header_up X-Proxy-Secret "32-byte-hex"  # if Frigate auth_secret set
+    #       }
+    #   }
+    #
+    # ALSO EDIT frigate_config/config.yml IN THE FRIGATE REPO:
+    #   auth:
+    #     enabled: False
+    #     trusted_proxies: [172.18.0.0/16]            # caddy_net subnet
+    #   proxy:
+    #     header_map: {user: remote-user, role: remote-groups}
+    #     default_role: viewer
+    #     separator: '|'
+    # ===================================================================
     # - domain: 'cam.{{ env "DOMAIN" }}'
     #   policy: 'two_factor'
 
-    # -------------------------------------------------------------------
-    # CASE 3: App keeps its own auth; Authelia adds a 2FA gate in front.
-    # User authenticates with Authelia (2FA) then with the app itself.
-    # Add entries for any extra-gated domains here.
-    # -------------------------------------------------------------------
-    # - domain: 'nas.{{ env "DOMAIN" }}'
+    # ===================================================================
+    # CASE 2b -- App supports OIDC. Authelia is the OIDC provider.
+    # Caddy block is identical to case 2a; the difference is on the app
+    # side (token exchange, not header). REQUIRES additional setup of
+    # identity_providers.oidc below this access_control block, with one
+    # client per app -- see Authelia OIDC docs.
+    # Example: Audiobookshelf.
+    #
+    # ALSO PASTE INTO CADDYFILE (case 2b site block):
+    #   books.{env.DOMAIN} {
+    #       import accesslog
+    #       import authelia
+    #       reverse_proxy 192.168.x.x:13378           # CHANGE IP
+    #   }
+    # ===================================================================
+    # - domain: 'books.{{ env "DOMAIN" }}'
     #   policy: 'two_factor'
 
-    # CASE 4: No rule here, no `import authelia` in Caddy. App handles auth.
+    # ===================================================================
+    # CASE 3 -- App keeps its own login. Authelia adds a 2FA gate in
+    # front. User authenticates with Authelia (2FA), then with the app
+    # itself. Two logins, but Authelia's 2FA covers apps that don't
+    # support proxy headers OR OIDC OR native TOTP.
+    # Example: Uptime Kuma, Portainer (without OIDC), router admin.
+    #
+    # ALSO PASTE INTO CADDYFILE (case 3 site block):
+    #   uptime.{env.DOMAIN} {
+    #       import accesslog
+    #       import authelia
+    #       reverse_proxy 192.168.x.x:3001            # CHANGE IP
+    #   }
+    # ===================================================================
+    # - domain: 'uptime.{{ env "DOMAIN" }}'
+    #   policy: 'two_factor'
+
+    # ===================================================================
+    # CASE 4 -- App handles its own auth. NO rule needed here.
+    # Authelia is never consulted. Caddy still imports accesslog so
+    # fail2ban watches the subdomain for scanners.
+    # Example: Plex/Emby (native clients break with Authelia redirects),
+    # Syncthing, anything you've decided to leave alone.
+    #
+    # ONLY PASTE INTO CADDYFILE -- nothing here in configuration.yml:
+    #   plex.{env.DOMAIN} {
+    #       import accesslog                          # NO import authelia
+    #       reverse_proxy 192.168.x.x:32400           # CHANGE IP
+    #   }
+    # ===================================================================
+    # (no rule -- case 4 is the absence of one)
 
 session:
   # secret loaded via AUTHELIA_SESSION_SECRET_FILE