Skip to content

Commit 283d5e8

Browse files
committed
docs(permissions): align the Provenance clause and the admin guide with the packaged lock
Two more places still said a shipped permission set can be overlaid in the environment. The Provenance paragraph's clause pointed "see below" at the corrected bullet, which now says the opposite; administrator-guide Step 5 and its FAQ answer told admins to overlay a shipped set. Both now state the lock with the same population as the corrected bullet: a set shipped in code (by an installed app, or a platform default) refuses an environment edit with 403 NOT_OVERRIDABLE, and the remedy is clone and adjust. Sets created here, clones and writable-runtime-package sets stay editable in place. Step 5 keeps its order of preference, and the FAQ keeps "or simply left unassigned". Claude-Session: https://claude.ai/code/session_0115N1oNnQS5WqofZ2DzaT3q Co-authored-by: Claude <noreply@anthropic.com>
1 parent e601c03 commit 283d5e8

2 files changed

Lines changed: 10 additions & 6 deletions

File tree

‎content/docs/permissions/administrator-guide.mdx‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -159,10 +159,13 @@ is a structured spreadsheet — you never hand-write JSON:
159159
- **Capabilities** — named grants like `manage_users` or `studio.access`.
160160

161161
Prefer the smallest change that works, in this order: **bind an existing set
162-
to a position** → **clone and adjust** → **author a new set**. Editing a set
163-
that shipped with an app creates an *environment overlay* — your change wins,
164-
survives upgrades, and can be reset back to the vendor baseline; the API name
165-
is immutable after creation. And keep the additive model in mind: author
162+
to a position** → **clone and adjust** → **author a new set**. A set shipped
163+
in code — by an app you installed, or as a platform default such as
164+
`member_default` — can't be edited in the environment (a save answers
165+
`403 NOT_OVERRIDABLE`): clone it and adjust the clone, which is your own set
166+
while upgrades keep reaching the original. Sets created here, clones, and sets
167+
saved into a writable runtime package are edited in place. The API name is
168+
immutable after creation. And keep the additive model in mind: author
166169
coherent capability bundles, never "subtraction sets".
167170
Full model: [Permission Sets](/docs/permissions/permission-sets).
168171

@@ -193,7 +196,8 @@ org structure, it's a business unit.
193196

194197
**Can I delete the built-in permission sets?** No — sets like
195198
`member_default` and `organization_admin` are the platform baseline. Shipped
196-
sets can be overlaid (Step 5) or simply left unassigned.
199+
sets can't be edited in place either, but they can be cloned and adjusted
200+
(Step 5) or simply left unassigned.
197201

198202
## Where is everything
199203

‎content/docs/permissions/permission-sets.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -309,7 +309,7 @@ A package ships its own sets (`managedBy: 'package'` + `packageId`), seeded
309309
idempotently at boot and re-seeded on upgrade; environment-authored sets
310310
(`platform`/`user`) are never clobbered. The data layer refuses forging package
311311
provenance through the admin door (two-doors separation, evolved by ADR-0094 —
312-
ordinary edits of a packaged set become environment overlays, see below), which
312+
an edit of a set shipped in code is refused; clone it instead, see below), which
313313
is what makes package uninstall well-defined — and enforced: uninstalling a
314314
package (`DELETE /api/v1/packages/:id`) revokes its own sets, their
315315
position/user bindings, and its pending audience-binding suggestions in the

0 commit comments

Comments
 (0)