docs(skills): document permission-set assignment, and name permissions as its defineStack key

[qq9340100]

Fixes #10318
Fixes #10327

Two members of one family from the new-developer first-run journey audit (#10264), both on the permission-set surface of the published skills bundle. One commit per member; each is independently verifiable.

skills/** only. Governed surface — draft, human merge only; no ready flip, no queue, no auto-merge.

---

Member 1 — #10327: name permissions as the defineStack key

Commit ee6bd9ec9.

Premise: partially stale, and the correction changes where the fix lands. The card's body says the bundle's enumerated defineStack keys omit permissions. Swept against origin/main: the bundle contains exactly one full defineStack key enumeration — skills/objectstack-platform/SKILL.md:176-184 — and it already names permissions (line 180, between positions and capabilities). So the ruled instruction "add permissions to every enumeration" is a no-op: the acceptance criterion "permissions present in every enumeration" is already satisfied, and no enumeration was edited.

Sweep method (both re-runnable): a window scan over every skills/**/*.md for co-occurring stack-collection keys in backticks (≥4 distinct per 3-line window), and a second scan for the audit's specific 9-key list shape. Only the platform enumeration and two deliberately-elided illustrative lists surfaced — the barrel-import example (manifest/objects/apps/views/flows) and the CRM blueprint's src/{objects,views,pages,actions,flows,...} directory hint. Neither claims completeness.

The card's title, however, is exactly right and still reproducible: "No skill names permissions as the defineStack key for permission sets." defineStack({ permissions appears nowhere in the bundle. That is the real defect and it explains the audit's stumble better than the enumeration does: every other authoring factory in the bundle is paired with its registration key at the point of authoring — defineStack({ translations: [...] }) in objectstack-i18n, { apps } / { pages } / { actions } in objectstack-ui, { flows } in objectstack-automation, { hooks } and { objectExtensions } in objectstack-data itself. definePermissionSet was the one exception, so a dev who authored a set correctly had nothing to read and guessed permissionSets from the factory name.

So the fix lands at the authoring site instead: skills/objectstack-data/SKILL.md "Object-level permissions (RBAC)" now carries the registration comment in the code block (mirroring the objectExtensions convention already used at line 565) plus a bullet naming the key, why it is named for the metadata kind rather than the factory, and that the top level is strict.

The error-text claim is grounded, not recalled: ObjectStackDefinitionSchema is built with strictObject({ surface: 'this stack definition', … }) (packages/spec/src/stack.zod.ts:202), and the message builder emits Unrecognized key(s) on {surface}: `k1` (packages/spec/src/shared/suggestions.zod.ts:392). The doc states the error prefix and that the key is named, and does not reproduce the near-miss suggestion line verbatim.

Member 2 — #10318: document assigning a permission set to a user

Commit c43df0067. Premise valid — verified before writing: sys_user_permission_set appears exactly once anywhere in the bundle, in a objectstack-platform troubleshooting row that names the table without any how-to. Nothing teaches the assignment path.

New subsection "Assigning a permission set to a user" in the objectstack-data security section, placed immediately after the set-authoring subsection — the narrative point where the audit's dev stalled. Every claim was read out of the platform source on this checkout, not taken from the card:

Claim in the doc	Source read
sys_user_permission_set is the join object; field list, organization_id null semantics, uniqueness (user_id, permission_set_id, organization_id)	packages/plugins/plugin-security/src/objects/sys-user-permission-set.object.ts
A set declared in permissions is upserted into sys_permission_set by name with a generated id on kernel:ready (ADR-0086 D5)	plugin-security/src/bootstrap-declared-permissions.ts (upsertPackagePermissionSet, genId('ps'))
permission_set_id takes the record id, not the name — a name matches nothing and grants nothing, silently	packages/core/src/security/resolve-authz-context.ts:419-497: grant rows are read by user_id, permission_set_id collected, then sys_permission_set loaded by id $in; ps.name is what lands in ExecutionContext.permissions[]
Validity window is half-open [from, until), enforced at resolution time, no background job	the object's own field docs + isGrantActive filtering ahead of every derivation
granted_by is stamped by the gate on insert — do not author it	delegated-admin-gate.ts:673 (assertDirectGrantWrite)
id may be omitted; the driver mints one	packages/drivers/driver-sql/src/sql-driver.ts:4965 (nanoid fallback in create)
Who may write the row: tenant admin, or a delegated adminScope with manageAssignments + set allowlisted + BU subtree covering the target (ADR-0090 D12); CRUD bits are not enough	delegated-admin-gate.ts — quoted phrase is the gate's own denial text
A deactivated set keeps its assignments and grants nothing	resolve-authz-context.ts §6b isRowActive filter
POST /api/v1/data/{object} and POST /api/v1/data/{object}/query (QueryAST in body; the path object is written last)	packages/rest/src/rest-server.ts:6721-6765, and the route table already published in objectstack-api
GET /api/v1/security/explain?object=&operation=&userId= answers "why" from the enforcement code path; explaining another user needs manage_users or a covering adminScope	rest-server.ts:8886-8910
System objects are not exposed over MCP unless allowSystemObjects is set	packages/mcp/src/mcp-http-tools.ts:314-320
Grants also arrive via position bindings; every authenticated principal implicitly holds everyone	resolve-authz-context.ts §5b, §6a

Also included: the minimal two-user prove-the-deny flow the audit ran (grant to A, 200 as A, 403 as B, revoke, A denied), and an ordered inert-grant checklist (name-in-id-field, deactivated set, validity window, org mismatch) so the next reader diagnoses instead of guessing.

objectstack-platform same-gap check (ruled scope): that skill has no security-authoring section at all — it covers project setup, plugins and ops — so duplicating the how-to there would create the stale-second-copy class the bundle already suffers from. It gets one pointer row in "Common ops pitfalls", next to the existing row that already sends operators to this table.

Exclusions honoured

• The MCP-exposure question for sys_user_permission_set is not touched. The doc states the current behaviour (system objects are off-MCP unless opted in) because that is what stops the next stranger asking the agent and getting nothing; whether that boundary should change is a product call and stays a decision-inbox candidate, noted in the dev report, never implemented here.
• The territory of [finding] objectstack-platform skill still teaches that an unknown top-level defineStack key is silently stripped — #8687 made it throw #9907 (the stale "unknown key is silently stripped" teaching) is untouched — that half already landed there, and this PR addresses none of it.
• No unrelated doc polish.

---

Verification

All gates run at c43df0067, the final commit and current head of this branch. Gate list re-derived from the actual diff with node scripts/pm/dispatch-gates.mjs (no paths passed; the script takes its own change set from the merge base) — it named exactly the two gates the dispatch clue carried, no additions.

Exit codes captured before any pipe; verdicts quoted from each gate's own output line.

• check:role-word — self-test 0, gate 0.
  check-role-word: OK, no new occurrences of the reserved word. / Scanned: 217 .md/.mdx file(s) read across 2 root(s) — content/docs 181, skills 36.
  Both edited files are baselined at fixed counts and the ratchet fails in both directions, so the added prose was written to keep the count exact: skills/objectstack-data/SKILL.md 4 → 4, skills/objectstack-platform/SKILL.md 2 → 2. The reserved word does not appear in any added line.
• check:pm-governed-merges — self-test 0 (81 assertions). Predicate --test on both paths exits 3 = GOVERNED:
  governed-surface predicate: 2 of 2 path(s) hit the register / skills/** ×2 — the published skills catalog.
  Hence draft, human merge only.
• check:nul-bytes — self-test 0, gate 0: OK (scanned 6117 text file(s) … no raw ASCII control bytes). Also self-scanned the two files directly with grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' — no match.
• check:doc-authoring — self-test 0, gate 0: ✓ doc authoring guard: 381 files clean — no bare metadata literals. Run because the diff adds fenced blocks to the skills corpus, though the derivation scored it silent.

Not run locally: check:doc-anchors — it imports github-slugger and this docs-only worktree has no node_modules (ERR_MODULE_NOT_FOUND), an environment gap rather than a tree result. It is not implicated by this diff: the added lines introduce no ](…#fragment) link, confirmed by grepping the added side of the diff. CI runs it.

No changeset: skills/** publishes nothing to npm — skip-changeset.

Docs-only; no code paths change.

---

Generated by Claude Code