docs(permissions): curated capabilities are registry declarations with no sys_capability row

Claude-Session: https://claude.ai/code/session_0113mDBBZPBFzvZqbJqfaFMv
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

content/docs/permissions/authorization.mdx

@@ -204,10 +204,10 @@ to write into another package's capability.
 
 This **replaces the implicit back-door** where a capability existed only as an
 untitled placeholder derived from whatever a permission set happened to reference
-in `systemPermissions[]`. That derivation still runs for back-compat (a
-reference with no declaration keeps resolving as a `managed_by:'platform'`
-placeholder), but an explicit `defineCapability` takes precedence and — for a
-pre-existing derived placeholder — **claims** it, upgrading the row to package
+in `systemPermissions[]`. That derivation is retired: a reference with no
+declaration still matches by name at runtime but gets no `sys_capability` row.
+An explicit `defineCapability` takes precedence and — for a derived placeholder
+an older database still holds — **claims** it, upgrading the row to package
 provenance with the authored label/description/scope. This is the ADR-0066 D1
 direction: retire the implicit `managed_by`-guessing back-doors in favour of
 explicit, attributable declarations.
@@ -537,15 +537,17 @@ The complete, prioritized gap map lives in issue **#2561** (the production
 
 - **Deny/muting layer** (ADR-0066 ⑦⑧) — union-only grants can't take access
   away; needed for large-org governance and packaged-set adjustment.
-- **Capability registry** (ADR-0066 D1) — **landed**: capabilities are seeded
-  as first-class `sys_capability` records from the canonical list in
+- **Capability registry** (ADR-0066 D1, ADR-0131 D3) — **landed**: the
+  platform's curated capabilities, from the canonical list in
   `@objectstack/spec` (`security/capabilities.ts` → `PLATFORM_CAPABILITIES`),
-  seeded by `packages/plugins/plugin-security/src/bootstrap-system-capabilities.ts`.
+  are declared `capability` metadata served by the registry
+  (`registerBuiltinCapabilities`, `GET /api/v1/meta/capability`), with no
+  `sys_capability` row.
   A **package** now DEFINES its own capabilities explicitly via
   [`defineCapability` / `stack.capabilities`](#package-capability-declaration-adr-0066-d1),
   seeded with `managed_by:'package'` + `package_id` provenance by
   `bootstrap-declared-capabilities.ts` — replacing the implicit
-  derive-from-`systemPermissions` back-door (which stays for back-compat).
+  derive-from-`systemPermissions` back-door (now retired).
   The authoring lint (ADR-0066 ⑨) is also **landed**: `validateCapabilityReferences`
   (`@objectstack/lint`) warns at author time (`os validate` / `os lint`) when a
   `requiredPermissions` names a capability registered nowhere — no built-in, no

content/docs/permissions/capabilities.mdx

@@ -218,7 +218,7 @@ behind that behaviour are set out in
 the scope and the provenance that make a capability reviewable, attributable and
 uninstallable — but no authorization check reads it. Permission-set grants and
 resource `requiredPermissions` match capability names **as strings**; the only
-production readers of the table are the two boot seeders. The row's `active`
+production reader of the table is the declared-capability boot seeder. The row's `active`
 flag is a catalogue/visibility flag with no authorization effect: clearing it
 revokes nothing. Withdraw a capability by withdrawing the **grant**.
 </Callout>

content/docs/permissions/permission-sets.mdx

@@ -40,7 +40,7 @@ export const SalesUser = definePermissionSet({
   // Tab/app visibility
   tabPermissions: { app_crm: 'default_on', app_admin: 'hidden' },
 
-  // System capabilities (flat strings, resolved against sys_capability)
+  // System capabilities (flat strings, matched by capability name)
   systemPermissions: ['export_reports'],
 });
 ```
@@ -147,8 +147,12 @@ the anchor decides *which* unit `unit*` means.
 
 ## Capabilities & required permissions (ADR-0066)
 
-- **Capabilities** are first-class `sys_capability` records — named privileges
-  such as `manage_users`, `manage_metadata`, `setup.access`, `studio.access`.
+- **Capabilities** are named privileges such as `manage_users`,
+  `manage_metadata`, `setup.access`, `studio.access`. The platform's curated
+  ones are declared `capability` metadata served by the registry
+  (`GET /api/v1/meta/capability`) and have no `sys_capability` row; a
+  capability a package declares with `defineCapability` is also seeded as a
+  `sys_capability` row.
   Grant them via `systemPermissions`; declare them as prerequisites via an
   object/field/app `requiredPermissions` (an **AND**-gate checked before any
   CRUD grant).