docs(skills): refresh the skill files for 0.36

skills/dune-auth.md

@@ -31,31 +31,31 @@ Dune owns the session lifecycle. Credential verification is delegated to OAuth p
 # site.yaml
 auth:
   mode: dune               # default — can be omitted
-  userStore: session        # identity embedded in the session record — no data/users/ files
-  sessionLifetime: 604800   # seconds (7 days) — flat field, default 2592000 (30 days)
+  user_store: session       # identity embedded in the session record — no data/users/ files
+  session_lifetime: 604800  # seconds (7 days) — flat field, default 2592000 (30 days)
   providers:
     github:
-      clientId: "${GITHUB_CLIENT_ID}"
-      clientSecret: "${GITHUB_CLIENT_SECRET}"
+      client_id: "${GITHUB_CLIENT_ID}"
+      client_secret: "${GITHUB_CLIENT_SECRET}"
 ```
 
-**There is no `session.secret`/`SESSION_SECRET` config anywhere in the real auth system.** Sessions are opaque server-tracked IDs, not signed/encrypted cookies — nothing reads a signing secret. By default they're stored under `{admin.runtimeDir}/site-sessions/`, using the same `SessionStore` mechanism (local/KV/Redis) admin sessions use — set `system.session_store` to switch backends; see `src/session/mod.ts`. See Gotchas.
+**There is no `session.secret`/`SESSION_SECRET` config anywhere in the real auth system.** Sessions are opaque server-tracked IDs, not signed/encrypted cookies — nothing reads a signing secret. By default they're stored under `{runtime_dir}/site-sessions/` (`system.runtime_dir`, default `.dune/admin`), using the same `SessionStore` mechanism (local/KV/Redis) admin sessions use — set `system.session_store` to switch backends; see `src/session/mod.ts`. See Gotchas.
 
 ### With persistent user records + magic link
 
 ```yaml
 auth:
   mode: dune
-  userStore: local          # JSON files at data/users/ + by-email/ index — the same store @dune/plugin-admin's admin accounts live in
+  user_store: local         # JSON files at data/users/ + by-email/ index — the same store @dune/plugin-admin's admin accounts live in
   providers:
     github:
-      clientId: "${GITHUB_CLIENT_ID}"
-      clientSecret: "${GITHUB_CLIENT_SECRET}"
-    magicLink:
+      client_id: "${GITHUB_CLIENT_ID}"
+      client_secret: "${GITHUB_CLIENT_SECRET}"
+    magic_link:
       enabled: true          # passwordless — requires email config (see dune-email skill)
 ```
 
-**There is no `providers.localUsers` config, at any userStore tier** — self-service signup is still only OAuth or magic link. But an admin *can* now pre-provision an account ahead of the person's first login: `dune users:create <email> [--role x[,y]] [--name "..."]` creates a `User` record directly (`provider: "invited"`). The invited person's first login via magic link matches it by email and just works; a first login via OAuth 409s instead (no linked provider yet on a record nobody's ever actually authenticated as) — see "Linking an additional provider" below for the fix.
+**There is no `providers.localUsers` config, at any user_store tier** — self-service signup is still only OAuth or magic link. But an admin *can* now pre-provision an account ahead of the person's first login: `dune users:create <email> [--role x[,y]] [--name "..."]` creates a `User` record directly (`provider: "invited"`). The invited person's first login via magic link matches it by email and just works; a first login via OAuth 409s instead (no linked provider yet on a record nobody's ever actually authenticated as) — see "Linking an additional provider" below for the fix.
 
 ### Routes generated by mode 1
 
@@ -100,15 +100,15 @@ auth:
   jwt:
     issuer: "https://your-app.clerk.accounts.dev"
     audience: "your-app"
-    jwksUrl: "https://your-app.clerk.accounts.dev/.well-known/jwks.json"
-    userIdClaim: sub      # default "sub" — flat fields, not a nested userClaims: {} map
-    emailClaim: email     # default "email"
-    rolesClaim: roles     # default "roles"
+    jwks_url: "https://your-app.clerk.accounts.dev/.well-known/jwks.json"
+    user_id_claim: sub      # default "sub" — flat fields, not a nested userClaims: {} map
+    email_claim: email     # default "email"
+    roles_claim: roles     # default "roles"
 ```
 
-There is no `userClaims: { id, email, name }` nested map — `userIdClaim`/`emailClaim`/`rolesClaim` are flat fields on `jwt:`, all optional with the defaults shown, and there is no name-claim option at all (name isn't extracted from the JWT in this mode). `issuer` and `audience` are required — `mountDuneAuth()` refuses to start without both. Without them, any token signed by the same JWKS endpoint is accepted, including tokens minted for a different tenant on a shared IdP.
+There is no `userClaims: { id, email, name }` nested map — `user_id_claim`/`email_claim`/`roles_claim` are flat fields on `jwt:`, all optional with the defaults shown, and there is no name-claim option at all (name isn't extracted from the JWT in this mode). `issuer` and `audience` are required — `mountDuneAuth()` refuses to start without both. Without them, any token signed by the same JWKS endpoint is accepted, including tokens minted for a different tenant on a shared IdP.
 
-No routes generated. No sessions. No user records in Dune. Clients pass `Authorization: Bearer {token}`. Optionally, `auth.webhook` (only active with `mode: external-jwt` + `authzStore: local`) registers `POST /auth/webhook` to handle `user.deleted` events and revoke authz tuples — role changes don't need a webhook, they're reconciled per-request from the JWT claims automatically.
+No routes generated. No sessions. No user records in Dune. Clients pass `Authorization: Bearer {token}`. Optionally, `auth.webhook` (only active with `mode: external-jwt` + `authz_store: local`) registers `POST /auth/webhook` to handle `user.deleted` events and revoke authz tuples — role changes don't need a webhook, they're reconciled per-request from the JWT claims automatically.
 
 ---
 
@@ -118,7 +118,7 @@ No routes generated. No sessions. No user records in Dune. Clients pass `Authori
 
 ```ts
 interface User {
-  id: string;                 // UUID (dune mode) or the JWT's userIdClaim value (external-jwt)
+  id: string;                 // UUID (dune mode) or the JWT's user_id_claim value (external-jwt)
   email: string;
   name?: string;
   avatarUrl?: string;
@@ -137,11 +137,17 @@ interface User {
 // ctx.state.siteUser is null on unauthenticated requests — never undefined
 ```
 
-(`src/auth/types.ts`.) In `external-jwt` mode, `roles` comes from the JWT's `rolesClaim` on every request — there's no persistent record. In `dune` mode, `roles` is a field stored directly on the `User` record.
+(`src/auth/types.ts`.) In `external-jwt` mode, `roles` comes from the JWT's `roles_claim` on every request — there's no persistent record. In `dune` mode, `roles` is a field stored directly on the `User` record.
 
 ### Reading it outside a Fresh handler
 
-Generated CRUD route handlers (from `dune codegen`) and other code that only has a raw `Request` (not a Fresh context) can't read `ctx.state` directly. The auth middleware also serializes the resolved user into an internal `x-dune-site-user` request header (JSON, stripped at the edge — never externally settable) for exactly this case: `requireAuth(req, mode)` from `@dune/core/auth/api-guard` reads it. **Hand-written TSX content pages have no automatic `page.siteUser` prop** — if you need the user there, read the header yourself the same way `api-guard.ts` does.
+Generated CRUD route handlers (from `dune codegen`) and other code that only has a raw `Request` (not a Fresh context) can't read `ctx.state` directly. The auth middleware also serializes the resolved user into an internal `x-dune-user` request header (JSON, stripped at the edge — never externally settable) for exactly this case: `requireAuth(req, mode)` from `@dune/core/auth/api-guard` reads it. **Hand-written TSX content pages have no automatic `page.siteUser` prop** — if you need the user there, read the header yourself the same way `api-guard.ts` does.
+
+---
+
+## Site users can edit
+
+A signed-in site user whose `roles` include `admin`, `editor` or `author` may edit pages in place (the editing bar and `/api/inline-edit/*` from `@dune/plugin-inline-edit`), with no admin plugin installed: core checks `pages.update` for them like for an admin account. Their role is also a group membership, kept in step with `roles[]` live, so changing a user's roles takes effect on their next request. Content-gating tags (`member`, `subscriber`) never grant editing. An `author` edits only the pages it created (`createdBy`); `admin` and `editor` edit any page. **Do not use `editor` or `author` as a content tier** (in `roles:` frontmatter, a payment product's `role`, a sign-up default): holding the name is what grants editing. Granting them on purpose, for example to paid contributors, is fine; core logs `auth.automatic_admin_tier_grant` at start and `dune doctor --boot` lists where the config does it. Responses for any signed-in user bypass the shared page cache.
 
 ---
 
@@ -165,28 +171,22 @@ export async function handler(req: Request, ctx: FreshContext) {
 
 ### Require a specific role
 
-**There is no `ctx.state.authz`.** `mountDuneAuth(app, ctx)` returns `{ resolveUser, authz }`, but Dune doesn't inject `authz` into request state — how you reach it differs by mode:
+**There is no `ctx.state.authz`.** `mountDuneAuth(app, ctx)` returns `{ resolveUser, authz }`; `createDuneApp()` keeps the `authz` for core's own checks (the inline-edit gate, the bar) but does not put it in request state. In your own code:
 
-**Default/full mode** (the normal `dune serve` path — `createDuneApp()` calls `mountDuneAuth()` for you and discards the return value): you never call `mountDuneAuth()` yourself, so there's no `authCtx` to stash. Use the project-local `getAuthz()` pattern from the **dune-authz** skill instead (`dune add polizy` scaffolds `src/auth/authz.ts`) — it's a separate `AuthSystem` instance, but reads/writes the same underlying tuple files in `data/permissions/`, so checks stay consistent with what `mountDuneAuth()`'s own instance sees.
-
-**Headless mode** (site calls `mountDuneAuth()` itself): stash the returned context when you call it:
-
-```ts
-// main.ts
-export const authCtx = await mountDuneAuth(app, ctx); // authCtx.authz, authCtx.resolveUser
-```
+- **A plugin**: use `services.authz` / `runtime.authz` (see the plugin-authoring skill).
+- **A site's own route or middleware**: use the project-local `getAuthz()` pattern from the **dune-authz** skill (`dune add polizy` scaffolds `src/auth/authz.ts`). It is a separate `AuthSystem` instance, but reads/writes the same tuple files in `data/permissions/`, so checks stay consistent.
+- **Headless mode** (the site calls `mountDuneAuth()` itself): stash the returned context.
 
 ```ts
 // routes/_middleware.ts
 import type { FreshContext } from "fresh";
-import { authCtx } from "../main.ts"; // however you exposed it
+import { getAuthz } from "../src/auth/authz.ts";
 
 export async function handler(req: Request, ctx: FreshContext) {
   if (!ctx.state.siteUser) {
     return Response.redirect(new URL("/auth/login", req.url));
   }
-  if (!authCtx.authz) return new Response(null, { status: 403 }); // null in external-jwt mode
-  const allowed = await authCtx.authz.check({
+  const allowed = await getAuthz().check({
     who: { type: "user", id: ctx.state.siteUser.id },
     canThey: "access",
     onWhat: { type: "group", id: "member" },
@@ -196,13 +196,13 @@ export async function handler(req: Request, ctx: FreshContext) {
 }
 ```
 
-`authz` is `null` in `external-jwt` mode — check `ctx.state.siteUser.roles` (from the JWT) directly instead; there's no polizy authz system to call there.
+`authz` is `null` in `external-jwt` mode unless `authz_store: local` is set — check `ctx.state.siteUser.roles` (from the JWT) directly instead.
 
 For content gating via frontmatter `roles:`, this check runs automatically in the page middleware — no manual wiring needed. See **dune-authz** skill.
 
 ---
 
-## `userStore` tiers (mode: dune only)
+## `user_store` tiers (mode: dune only)
 
 | Value | User records | When to use |
 |-------|-------------|-------------|
@@ -216,7 +216,7 @@ For content gating via frontmatter `roles:`, this check runs automatically in th
 
 **No passwords, still no `providers.localUsers`.** Password auth is out of scope for public-site accounts. Self-service signup is still only OAuth or magic link — but `dune users:create` (CLI) *can* pre-provision an account ahead of someone's first login; see "With persistent user records + magic link" above.
 
-**Account linking only works for `userStore: local`/`db`, not `userStore: session`.** `GET /auth/{provider}/link` 400s under `userStore: session` — there's no persistent record to attach a linked identity to (identity there is synthesized fresh from OAuth claims every login).
+**Account linking only works for `user_store: local`/`db`, not `user_store: session`.** `GET /auth/{provider}/link` 400s under `user_store: session` — there's no persistent record to attach a linked identity to (identity there is synthesized fresh from OAuth claims every login).
 
 **`ctx.state.siteUser`, not `ctx.state.user`.** This is the single most common way to break every example in this file — the field is `siteUser`.
 
@@ -226,10 +226,10 @@ For content gating via frontmatter `roles:`, this check runs automatically in th
 
 **There is no session-signing secret to configure.** No `SESSION_SECRET`, no `session.secret` YAML key — sessions are opaque IDs looked up server-side, not self-contained signed cookies.
 
-**`external-jwt` eliminates user storage entirely.** `ctx.state.siteUser.roles` comes from the JWT's `rolesClaim` on every request, not from authz tuples — `authz` is `null` in this mode.
+**`external-jwt` eliminates user storage entirely.** `ctx.state.siteUser.roles` comes from the JWT's `roles_claim` on every request, not from authz tuples — `authz` is `null` in this mode.
 
 **Magic link routes are `/auth/magic/send` and `/auth/magic`** — not `/auth/magic-link/send`/`/auth/magic-link/verify`. `POST /auth/magic/send` has a fixed-window rate limit owned by Dune (`src/auth/routes.ts`); if you build a custom magic-link flow that calls it directly (or bypasses it entirely), you own your own rate limiting.
 
 **`/auth/logout` is `GET`, not `POST`.** A plain link/redirect works.
 
-**TSX content pages don't get `page.siteUser` for free.** Read the `x-dune-site-user` header yourself if you need the user in a hand-written TSX page — see "Reading it outside a Fresh handler" above.
+**TSX content pages don't get `page.siteUser` for free.** Read the `x-dune-user` header yourself if you need the user in a hand-written TSX page — see "Reading it outside a Fresh handler" above.