docs(permissions): declaring package `capabilities:` has no page — the permissions docs only cover consuming them

[os-elon]

Part of #10206

The gap

capability is a metadata kind (CapabilityDeclarationSchema, ADR-0066 D1), authorable as defineStack({ capabilities }). AppPlugin registers stack-declared capabilities under that name and bootstrapDeclaredCapabilities reads them back to seed sys_capability.

The permissions section is thorough about consuming capabilities — permission-sets.mdx, authorization.mdx, permission-metadata.mdx, access-recipes.mdx, administrator-guide.mdx all reference them. Nothing tells a package author how to declare one. The only shape documentation is a section inside the generated references/security/misc.mdx, a page titled "misc" that a developer will never search for.

This is an authorization surface: systemPermissions / requiredPermissions resolve capabilities by name string, so a declared capability lands in the same namespace a permission set grants from. #5961 closed the enforcement half (before it, PUT /meta/capability/:name accepted any JSON); the authoring half is still undocumented.

File surface

• content/docs/permissions/capabilities.mdx — new
• content/docs/permissions/index.mdx — edit (Cards + overview)
• content/docs/permissions/meta.json — one added entry

⛔ Nothing outside content/docs/permissions/.

What to write

Read CapabilityDeclarationSchema (packages/spec/src/security/capabilities.ts), the capabilities: docblock in stack.zod.ts, the DEFAULT_METADATA_TYPE_REGISTRY entry, and bootstrapDeclaredCapabilities:

• What a declared capability is and its lifecycle: declared in a package → registered by AppPlugin → seeded into sys_capability → granted through a permission set → checked by requiredPermissions. One diagram or one ordered list; the reader needs the whole loop, because every existing page shows only its own segment.
• The declaration shape with a worked example.
• The name is the contract. Resolution is by string, so naming and namespacing decide whether a grant lands where you meant it.
• capability is code-only: allowRuntimeCreate: false — validated on the artifact route, refused at the runtime write door. State it, so the 403 is legible.
• ⚠️ The trap, and the reason this page has to be careful: the requires: array on a stack is a different namespace — canonical kebab-case tokens from PLATFORM_CAPABILITY_TOKENS, declaring what the package needs from the platform, fail-fast at startup if missing. capabilities: declares authorization capabilities the package offers. Two arrays, similar words, unrelated vocabularies. Disambiguate them explicitly and early — a reader who conflates them will write something that validates and does nothing.
• Cross-link permission-sets.mdx and authorization.mdx for the consuming half.

⛔ Non-goals

• ⛔ Do not document role / profile / policy as declarable kinds. capability 无 DEFAULT_METADATA_TYPE_REGISTRY / schema 条目 —— PUT /api/v1/meta/capability/:name 接受任意 JSON 且 /meta/types 报 allowRuntimeCreate:true(与 #5271 的 api 同形) #5961 ruled them explicitly out: no PLURAL_TO_SINGULAR mapping, no declaration schema, no read-back seam. (permissions/profiles.mdx is titled "Profiles (removed)" — leave it alone.)
• Do not touch packages/spec/**.
• Do not weaken or reinterpret any existing authorization statement in the permissions section. If something there now looks wrong to you, report it; a permissions page is not the place to fix a suspicion.

Gates (derived at dispatch time via node scripts/pm/dispatch-gates.mjs, not recalled)

check:doc-anchors, check:docs-audit-scope, check:docs-redirects, check:published-readme-links, check:role-word, check:cross-package-test-inputs, and the spec liveness set (check:empty-state, check:liveness, check:strictness-ledger, check:variant-docs). Re-derive against your actual diff; ADR anchor checks apply once you cite ADR-0066 decision letters.

Acceptance

• A package author can declare a capability, grant it, and check it, from one page.
• capabilities: versus requires: is impossible to confuse after reading it.
• Named gates green.

[os-elon]

Claim: PM loop round 2 (epic #10206)
Session: session_01GawRwpD44VwBDVy3hs77AX
Branch: claude/issue-10216-declaring-capabilities
Worktree: objectstack-issue-10216
Domain: domain:devx
File surface: content/docs/permissions/capabilities.mdx (new), index.mdx, meta.json, plus .claude/workflows/docs-accuracy-audit.js (the --write regeneration — declared) (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — no path-derived mandate; tier is this seat's call. Held at the judgment tier because the page sits on an authorization surface: systemPermissions / requiredPermissions resolve capabilities by name string, so a declared capability lands in the same namespace a permission set grants from, and the card's central trap is the capabilities: / requires: namespace confusion.
Clause-②: no — documentation only. The card forbids touching packages/spec/** and forbids reinterpreting any existing authorization statement.
Serial constraints cleared: content/docs/permissions/** — no in-flight claim, no open PR. Batch-2 siblings #10213 (data-modeling/**) and #10215 (api/**) are disjoint by section; see the shared .claude/ note on #10213's claim.

---

Generated by Claude Code