docs(security): document scope-depth (ADR-0057 D1) + open/paid boundary (ADR-0016) (#2118)

scope-depth (readScope/writeScope = own/own_and_reports/unit/unit_and_below/org)
is the core declarative ERP authz axis, but it was undocumented in both the
objectstack-data skill and the security guide — so an AI author wouldn't know it
exists (and would fall back to hand-written RLS, exactly what ADR-0057 removes),
and wouldn't know the open/paid boundary (using `unit` in open-source silently
fails closed to `own`).

- skills/objectstack-data: new "Access depth (scope-depth)" section before RLS —
  the 5-value table + a usage example + the ADR-0016 open-core boundary
  (hierarchy-relative scopes need @objectstack/security-enterprise; fail closed to
  `own` without it; defineStack requires ['hierarchy-security']).
- guides/security.mdx: matching scope-depth section under Object Permission Levels.

Doc/skill-only. check:skill-docs in sync; docs build green (1113 pages).
showcase deliberately NOT touched — it's open-source, so a `unit` scope there
would fail-closed to `own` and mislead; the showcase-scope-depth dogfood already
proves the capability with a reference resolver.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

content/docs/guides/security.mdx

@@ -118,6 +118,36 @@ export const SalesRepProfile: PermissionSet = {
 | `viewAllRecords` | View ALL records regardless of ownership |
 | `modifyAllRecords` | Edit ALL records regardless of ownership |
 
+### Access depth — `readScope` / `writeScope` (ADR-0057 D1)
+
+Beyond the boolean grants above, an owner-scoped object grant can carry a
+**`readScope` / `writeScope`** that widens the owner-match *declaratively* — the
+ERP "see my own / my reports / my unit / my unit and below / the whole org" axis,
+without hand-writing one RLS policy per object:
+
+| Scope | Owner-match widens to |
+|------------|-------------|
+| `own` | the caller (baseline; unset = this) |
+| `own_and_reports` | the caller + their `sys_user.manager_id` report chain |
+| `unit` | owners in the caller's business unit (`sys_business_unit`) |
+| `unit_and_below` | the caller's BU + all descendant BUs (BFS) |
+| `org` | the whole tenant (≈ `viewAllRecords` / `modifyAllRecords`) |
+
+```typescript
+objects: {
+  account: { allowRead: true, allowEdit: true, readScope: 'unit_and_below', writeScope: 'own' },
+}
+```
+
+It resolves to an `owner_id IN (…)` set at request time and AND-injects alongside
+RLS (no compiler change; ADR-0055). Sharing rules still widen on top.
+
+> **Open-core boundary (ADR-0016).** `own` and `org` are open-source. The
+> hierarchy-relative scopes (`own_and_reports` / `unit` / `unit_and_below`) require
+> the paid `@objectstack/security-enterprise` plugin (BU-subtree + manager-chain
+> resolver); without it they **fail closed to `own`** (never fail-open), and
+> `defineStack` errors if a grant uses one without `requires: ['hierarchy-security']`.
+
 ### Standard Profiles
 
 #### Sales Representative

skills/objectstack-data/SKILL.md

@@ -424,6 +424,44 @@ permissions: {
 - Source: `node_modules/@objectstack/spec/src/security/permission.zod.ts`
 - Combine with `enable.apiMethods` to also restrict the HTTP surface.
 
+### Access depth (scope-depth) — the ERP "see my unit / my unit and below" axis
+
+For owner-scoped (`private`) objects, a per-object grant on a permission set can
+carry **`readScope` / `writeScope`** that *widens the owner-match declaratively* —
+the ERP "my own / my reports / my unit / my unit and below / whole org" axis
+(ADR-0057 D1). It saves hand-writing one RLS policy per object.
+
+```typescript
+// in a permission set's `objects` map
+objects: {
+  account: {
+    allowRead: true, allowEdit: true,
+    readScope: 'unit_and_below',  // see accounts owned by my BU + descendant BUs
+    writeScope: 'own',            // but only edit my own
+  },
+}
+```
+
+| Scope | Who you can see / write |
+|:--|:--|
+| `own` | `owner == me` (baseline; unset = this) |
+| `own_and_reports` | me + everyone below me on the `sys_user.manager_id` chain |
+| `unit` | owners in my business unit (`sys_business_unit`) |
+| `unit_and_below` | my BU + all descendant BUs (BFS) |
+| `org` | the whole tenant (≈ `viewAllRecords` / `modifyAllRecords`) |
+
+Resolves at request time into an `owner_id IN (…)` set and AND-injects like RLS
+(no compiler change; ADR-0055). Sharing rules still widen on top.
+
+> ⚠️ **Open-core boundary (ADR-0016).** `own` and `org` work in open-source. The
+> **hierarchy-relative** scopes — `own_and_reports` / `unit` / `unit_and_below` —
+> need the **paid** `@objectstack/security-enterprise` plugin (BU-subtree +
+> manager-chain resolver). Without it they **fail closed to `own`** (never
+> fail-open), and `defineStack` errors if a grant uses one without
+> `requires: ['hierarchy-security']`. In an open-source app, author `own` / `org`
+> + explicit sharing rules; reach for `unit*` only when the enterprise plugin is
+> present.
+
 ### Row-Level Security (RLS)
 
 The **enforced** RLS surface is a list of `rowLevelSecurity` policies on a