@@ -0,0 +1,12 @@
+---
+'@objectstack/skills': patch
+---
+
+docs(skills): objectstack-data's security rules name the risk of renaming or removing a shipped access item in a later package version
+
+Clause-②: no
+Metadata-protocol: none
+
+`skills/objectstack-data/rules/security.md` gains a closing section, "Renaming or removing a shipped access item". Administrators act on a package's permission sets, positions, sharing rules and capabilities by name: they switch them off, clone them, and name the package's objects, fields and capabilities in their own sets. The section says what a rename, a removal or an added field deny does to those choices on upgrade, asks authors to keep shipped names stable and, when such a change is genuinely needed, to say in the release notes what changed and what an administrator should re-check. It is guidance only: no gate and no behaviour change.
+
+The file stays under its token ceiling. The new text is paid for by deleting restatements elsewhere in the same file: the stack-key bullet that repeated the code sample's comment, the assignment payload that repeated the row's columns, a code comment that repeated the sentence above it, the `viewAllRecords` corollary sentence, and the callout's repeats of the Layer 0 bullets and of a citation made two paragraphs earlier. No rule changes meaning.
@@ -20,11 +20,9 @@ export const salesUser = definePermissionSet({
 // defineStack({ permissions: [salesUser], ... })
 ```
 
-- **Stack key: `permissions`** (named for the metadata kind, not the factory).
-  `permissionSets:` is **refused at load** — the strict top level fails with an
-  `Unrecognized key(s) on this stack definition` error naming the key, never a
-  silent drop; `ObjectStackDefinitionSchema`
-  (`node_modules/@objectstack/spec/src/stack.zod.ts`) is the enumeration of record.
+- `permissionSets:` is **refused at load** with an `Unrecognized key(s) on this
+  stack definition` error naming the key; `ObjectStackDefinitionSchema`
+  (`node_modules/@objectstack/spec/src/stack.zod.ts`) enumerates the keys.
 - Bits: `allowCreate` / `allowRead` / `allowEdit` / `allowDelete`, plus
   `allowTransfer` (ownership change), `viewAllRecords` / `modifyAllRecords`
   (super-user, bypass sharing).
@@ -43,13 +41,11 @@ optional `organization_id` (`null` = every org context). Optional `valid_from` /
 `valid_until` bound a half-open window; `granted_by` is stamped by the gate on
 insert — never author it.
 
-⚠️ **`permission_set` takes the set's `name`, never a record id** — a name the
-security catalog does not hold is refused `400 VALIDATION_FAILED`
-(`reference_not_found`), and a row with no name is refused `required`.
+⚠️ **Never a record id** — a `permission_set` the security catalog does not hold
+is refused `400 VALIDATION_FAILED` (`reference_not_found`); none at all, `required`.
 One grant per user, set and organization: enforced by the `unique: 'organization'` index.
 
-Assignment is one call: `POST /api/v1/data/sys_user_permission_set` with
-`{ user_id, permission_set: '<name>', organization_id }`. Only a tenant admin —
+Assignment is one `POST /api/v1/data/sys_user_permission_set`. Only a tenant admin —
 or a delegated `adminScope` carrying `manageAssignments` for that set and user
 (ADR-0090 D12) — may write it; plain CRUD bits on the table are not enough.
 
@@ -144,7 +140,7 @@ over permission-set field grants.
 fields: {
   ssn: {
     type: 'text',
-    requiredPermissions: ['view_pii'],  // mask on read / deny on write without it
+    requiredPermissions: ['view_pii'],
   },
 }
 ```
@@ -188,9 +184,7 @@ none — e.g. identity tables a plugin writes via its own adapter
   better-auth-managed identity table). It never crosses the Layer 0 wall —
   crossing takes a *true platform admin* (the superuser bit **and** a
   platform-exclusive capability: `manage_metadata`, `manage_platform_settings`,
-  `studio.access`, `manage_users`) on one of those same postures. So an org
-  admin with the superuser bit stays org-scoped; on an ordinary tenant object
-  nobody crosses (the admin sees 0 rows too).
+  `studio.access`, `manage_users`) on one of those same postures.
 
 **Recipe — env-global, admin-only object that admins can fully see:**
 
@@ -205,9 +199,21 @@ requiredPermissions: ['manage_platform_settings'], // capability AND-gate → me
 > reads every row env-wide — the shipped `viewer_readonly` still carries one, as
 > may an app-declared default profile or a customer-authored set. (The
 > `member_default` baseline is **not** one of them: it is explicit-allow and
-> grants only the objects it names.) `requiredPermissions` *by itself* leaves the
-> object a tenant object, so the wall keeps denying the untagged rows and even a
-> platform admin sees nothing. The pair is the correct combo; `requiredPermissions`
-> is the half that holds however permissive the caller's grants are (an AND-gate
-> checked **before** the CRUD grant). Posture model: ADR-0066; tenant wall:
-> ADR-0095 D1.
+> grants only the objects it names.) `requiredPermissions` *by itself* leaves a
+> tenant object, whose untagged rows the wall denies to everyone (above); it is
+> the half that holds however permissive the caller's grants are. Posture model:
+> ADR-0066.
+
+## Renaming or removing a shipped access item
+
+Administrators act on a package's access items by **name**: they switch a
+permission set, position or sharing rule off, clone a set, and name its objects,
+fields and capabilities in their own sets. A later version can quietly undo them
+on upgrade:
+
+- **Rename** → the old switch-off stops matching; the renamed item arrives switched **on**.
+- **Remove** an object, field or capability → a customer's clone or own set names something that no longer exists.
+- **Add a field deny** to a shipped set → a customer's clone does not carry it.
+
+Keep shipped names stable. When such a change is genuinely needed, say so in the
+release notes: what changed, and what an administrator should re-check after upgrading.