docs: abilities (scopes)

[stsepelin]

Documents lukk 0.6's abilities feature. Server: stsepelin/lukk#29 · Client: stsepelin/lukk-js#50.

Covers setup, the two route gates, wildcards, the TokenContext argument, derived vs pinned grants, lukk's own gated routes, response codes and the TokenAbilityDenied event, the client composable, multi-guard, and the feature flag.

Two things get the strongest wording

Name abilities after resources, never after facts about a person. An ability name travels in the scope claim past every proxy, gateway and APM on the path, is published on the user resource, and appears as a literal string in the app's public JavaScript bundle. hiv_clinic.records.read is a special-category disclosure at each hop; clinic_a.records.read is not. lukk validates the syntax of a name and can say nothing about its meaning — so this is the one control that actually works, and it's the integrator's to apply.

Scope says what a token may do, never which records it may touch. Per-object authorization stays the app's Policies and Gates. Confusing the two is OWASP API1 (BOLA).

Roadmap

Abilities moves from Planned to Shipped. The personal-access-token entry is updated: pinned grants supply the half it was waiting on — a fixed, per-token set of permissions that survives rotation — so what remains is naming, listing and individual revocation.

Note

Every claim on the page was executed rather than read. That check caught two real defects: a documented ability that nothing granted, and a TokenContext field that is always false in the callback that receives it. Both are fixed in the server PR; the page describes actual behaviour.

Greptile Summary

The PR documents the abilities/scopes functionality introduced for lukk 0.6 and updates the site navigation and roadmap accordingly.

• Adds setup guidance, route gates, wildcard rules, token context, derived and pinned grants, built-in route protections, responses, client helpers, multi-guard behavior, and feature flags.
• Adds the abilities page to the VitePress sidebar.
• Moves abilities from Planned to Shipped and updates the remaining personal-access-token roadmap work.

Confidence Score: 5/5

The documentation-only PR appears safe to merge with no actionable defects identified.

The new page uses supported documentation syntax, its local links and navigation target resolve, and the roadmap changes remain consistent with the documented abilities feature.

Important Files Changed

Filename	Overview
docs/abilities.md	Adds comprehensive abilities documentation with internally coherent examples, security guidance, lifecycle behavior, and client integration details.
docs/.vitepress/config.mts	Adds the new abilities page to the authentication sidebar using an existing valid route.
docs/roadmap.md	Moves abilities to Shipped and consistently revises the personal-access-token dependency and remaining scope.

_{Reviews (1): Last reviewed commit: "docs: abilities (scopes)" | Re-trigger Greptile}