Add optional permission scopes to API tokens

A token may carry a scopes list: it then grants only those permissions,
intersected with what the owner holds at use time, with the admin role
bypass suspended and role-gated routes denied - a scoped token from an
admin account is genuinely limited. Scope ceiling enforced at
create/update too (only permissions the owner holds; 400 lists
violations) and the picker only offers what you hold. Token management
itself now requires the new apitokens.create permission (admin by
default, grantable via roles). Unscoped tokens keep the exact prior
act-as-owner behavior; imports need an unscoped admin token.
Migration 7d22.

756 tests pass; live-verified scoped 201/403 matrix.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/CONFIG.md

@@ -231,6 +231,15 @@ is stored; the secret is shown once at creation. This is the recommended
 credential for long-running imports (see `docs/IMPORT-API.md`). There is no env
 var to configure; PATs are managed entirely through the API/UI.
 
+Creating or managing a PAT requires the `apitokens.create` permission (admins
+hold it by default; grant it to other roles from Settings > Users & Roles). By
+default a PAT is unscoped and acts with the full authority of its owner. A PAT
+may optionally carry a scopes list (a subset of the owner's permissions, capped
+at what the owner actually holds): a scoped token grants ONLY those permissions,
+intersected with the owner's live permissions at use time, and suspends the
+admin bypass, so it is denied on role-gated (admin-only) endpoints and on import
+mode. Use an unscoped token for admin-only work and imports.
+
 ### identifiers (dynamic)
 
 One boolean key per asset identifier per asset type, keyed

docs/IMPORT-API.md

@@ -55,6 +55,13 @@ mode) as its owning admin, exactly as a login JWT would, but without the hourly
 expiry. Revoke it from the same Settings page (or `DELETE /api/apitokens/<id>`)
 when the import is done.
 
+Use an **unscoped** token for imports. A token may optionally carry a scopes
+list that limits it to specific permissions; a scoped token suspends the admin
+bypass and is denied on role-gated endpoints AND on import mode, so it cannot
+run an import. Leave the "Restrict permissions" option off (the default) so the
+token acts with the full authority of its admin owner. Minting a token itself
+requires the `apitokens.create` permission (admins have it by default).
+
 A short-lived login JWT still works for quick one-off calls if you prefer.
 
 ### Import mode: the `X-Import-Mode` header