diff --git a/README.md b/README.md
index 4132a71..ba1cd6f 100644
--- a/README.md
+++ b/README.md
@@ -89,7 +89,7 @@ export default {
 
 ```ts
 // The mobile app browses the game catalog before the user signs in.
-// auth: 'publishable' validates the apikey header against a publishable key —
+// auth: 'publishable' validates the apikey header against the 'default' publishable key —
 // gating the endpoint to your own clients while staying anonymous to the DB.
 export default {
   fetch: withSupabase({ auth: 'publishable' }, async (_req, ctx) => {
@@ -119,7 +119,8 @@ await fetch(catalogEndpoint, { headers: { apikey: publishableKey } })
 
 ```ts
 // An admin dashboard fetches the list of featured games to curate.
-// Secret key auth (not a user JWT) — supabaseAdmin bypasses RLS.
+// auth: 'secret' validates the apikey header against the 'default' secret key
+// (not a user JWT) — supabaseAdmin bypasses RLS.
 export default {
   fetch: withSupabase({ auth: 'secret' }, async (_req, ctx) => {
     const { data: featuredGames } = await ctx.supabaseAdmin
diff --git a/docs/auth-modes.md b/docs/auth-modes.md
index 4c819d8..f00e5ab 100644
--- a/docs/auth-modes.md
+++ b/docs/auth-modes.md
@@ -81,7 +81,7 @@ The caller must send:
 apikey: sb_publishable_abc123...
 ```
 
-By default, `publishable` mode validates against the `"default"` key in `SUPABASE_PUBLISHABLE_KEYS`. Use named key syntax to target a specific key or `publishable:*` to accept any key (see below).
+> **Bare `publishable` matches only the `default` key.** `auth: 'publishable'` validates **only** against the key named `default` in `SUPABASE_PUBLISHABLE_KEYS`. It does **not** fall back to your named keys, so if every key in the set is named, bare `publishable` never matches. Use `publishable:<name>` to target a named key, or `publishable:*` to accept any key in the set — see [Named key syntax](#named-key-syntax).
 
 ## Secret mode
 
@@ -105,7 +105,7 @@ The caller must send:
 apikey: sb_secret_xyz789...
 ```
 
-By default, `secret` mode validates against the `"default"` key in `SUPABASE_SECRET_KEYS`. Use named key syntax to target a specific key or `secret:*` to accept any key (see below).
+> **Bare `secret` matches only the `default` key.** `auth: 'secret'` validates **only** against the key named `default` in `SUPABASE_SECRET_KEYS`. It does **not** fall back to your named keys, so if every key in the set is named, bare `secret` never matches. Use `secret:<name>` to target a named key, or `secret:*` to accept any key in the set — see [Named key syntax](#named-key-syntax).
 
 ## None mode