docs: sync permissions / plugins / protocol docs with implementation (#1880 Wave 1, batch 5)

Commits the 23 permissions/plugins/protocol docs whose audit completed
cleanly this window. Highlights:
- plugins/*: removed the fabricated `definePlugin()` helper from examples —
  a plugin is a plain default-export object; no such helper exists.
- permissions/explain: corrected the explain `via` value to "direct grant"
  (adversarial-verify repair); permission-metadata, administrator-guide,
  authentication, field-level-security, sharing-rules: scope/flag/API fixes.
- protocol/diagram, protocol/kernel/config-resolution: path/reference fixes.

Some docs' verify pass was cut short by a weekly usage limit, so a subset is
audit-only (hand-scanned: no define*/scale/count regressions; MDX build-safe).
Two docs whose audit itself was interrupted (protocol/kernel/error-handling
and http-protocol) are reverted and deferred for a clean re-audit after the
limit resets.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012urEihGTAsQP2xizAqfCwt

Author: claude

content/docs/kernel/runtime-services/audit-service.mdx

@@ -33,4 +33,4 @@ services.audit.record(entry: {
 
 ## Typical Errors
 
-Implementations should avoid throwing into user paths. Callers should treat audit writes as best-effort unless strict compliance mode is enabled by host code.
+Sink implementations should avoid throwing into user paths: the runtime caller (for example `service-settings`) awaits `record()` without a surrounding `try`/`catch`, so a throwing sink propagates its error and fails the caller's write.

content/docs/kernel/services.mdx

@@ -85,7 +85,7 @@ The core ecosystem defines several standard service contracts:
 
 | Service Name | Interface | Provider Example |
 | :--- | :--- | :--- |
-| `http-server` | `IHttpServer` | `plugin-hono-server`, `adapter-nextjs` |
+| `http-server` | `IHttpServer` | `plugin-hono-server` |
 | `data` | `IDataEngine` | `@objectstack/objectql` (drivers implement `IDataDriver`) |
 | `auth` | `IAuthService` | `plugin-auth` |
 | `api-registry` | `ApiRegistry` | `@objectstack/core` |

content/docs/permissions/access-recipes.mdx

@@ -62,7 +62,7 @@ Keeping capability, assignment and requirement decoupled means resources stay st
 
 ## Runnable example
 
-- Built-in permission sets: [`default-permission-sets.ts`](https://github.com/objectstack-ai/framework/blob/main/packages/plugins/plugin-security/src/objects/default-permission-sets.ts) (`member_default` shows owner-scoped RLS + tenant isolation).
+- Built-in permission sets: [`default-permission-sets.ts`](https://github.com/objectstack-ai/framework/blob/main/packages/plugins/plugin-security/src/objects/default-permission-sets.ts) (`member_default` shows owner-scoped RLS; tenant isolation is now the Layer 0 tenant wall in `tenant-layer.ts`, ADR-0095 D1).
 - Security objects: [`packages/plugins/plugin-security/src/objects`](https://github.com/objectstack-ai/framework/tree/main/packages/plugins/plugin-security/src/objects).
 
 ## Anti-patterns

content/docs/permissions/administrator-guide.mdx

@@ -22,7 +22,7 @@ The one thing to internalize before anything else:
 
 | Concept | What it is | Who authors it | You touch it |
 |:--|:--|:--|:--|
-| **Permission set** | The only capability container — object CRUD, field security, access depth, system capabilities | Platform & app developers (in Studio) | Rarely — [Step 5](#step-5--configure-permissions-only-when-the-shipped-positions-dont-fit) |
+| **Permission set** | The only capability container — object CRUD, field security, access depth, system capabilities | Platform & app developers; ships with apps | Rarely — [Step 5](#step-5--configure-permissions-only-when-the-shipped-positions-dont-fit) |
 | **Position** (岗位) | A flat, named job function that binds permission sets; users hold positions | Ships with apps; you assign it | **Daily** |
 | **Business unit** | The *one* hierarchy — org tree that decides visibility depth and delegation boundaries | You, at onboarding and reorgs | Occasionally |
 | **User** | The person signing in | You | Daily |
@@ -144,12 +144,12 @@ report names the exact permission set and layer to fix.
 
 ## Step 5 — Configure permissions (only when the shipped positions don't fit)
 
-One rule of thumb: **permissions are *designed* in Studio, *assigned* in
-Setup.** If you are in this section, you've confirmed no shipped position
-covers the need.
+One rule of thumb: **capability ships with the apps you install — you rarely
+author a permission set by hand.** If you are in this section, you've confirmed
+no shipped position covers the need.
 
-The permission-set **matrix editor** (Studio → Access) is a structured
-spreadsheet — you never hand-write JSON:
+The permission-set **matrix editor** (Setup → Access Control → Permission Sets)
+is a structured spreadsheet — you never hand-write JSON:
 
 - **Object grid** — per object: Create / Read / Update / Delete, lifecycle
   bits (Transfer / Restore / Purge), and View All / Modify All, with per-row
@@ -180,9 +180,9 @@ Full model: [Permission Sets](/docs/permissions/permission-sets).
 
 ## FAQ
 
-**Do I need Studio?** Rarely. Setup is the administrator's home; Studio is
-where permission sets are *designed* — you enter it for Step 5 and for the
-Explain panel.
+**Do I need Studio?** Rarely. Setup is the administrator's home — the
+permission-set matrix editor (Step 5) lives there too. You enter Studio mainly
+for the **Explain** panel.
 
 **A new user sees almost nothing — broken?** No: that's the baseline working.
 Access arrives when you assign a position (Step 3).
@@ -207,7 +207,7 @@ sets can be overlaid (Step 5) or simply left unassigned.
 | Password policy, MFA, lockout, SSO | Setup → Configuration → Authentication |
 | Company info, localization, branding | Setup → Configuration |
 | Sessions, notification events, audit logs | Setup → Diagnostics |
-| Permission matrix editor, Explain access | Studio → Access |
+| Explain access | Studio → Access |
 
 ---
 

content/docs/permissions/attachments-access.mdx

@@ -36,11 +36,13 @@ Attachments panel renders only for such objects. Any other target is rejected:
 This is enforced by a `beforeInsert` hook on `sys_attachment` and is
 independent of the record-level checks below.
 
-## Create — read visibility (+ edit-on-parent) & provenance
+## Create — parent-edit access & provenance
 
-Creating a `sys_attachment` requires that the caller can **read** the parent
-record (verified with a caller-scoped `findOne`, so RLS / OWD / sharing of the
-parent object apply), and — for edit-on-parent parity — that they can edit it.
+Creating a `sys_attachment` requires that the caller can **edit** the parent
+record — Salesforce edit-on-parent parity — verified with the sharing service's
+`canEdit`, so RLS / OWD / sharing of the parent object apply (public-model
+parents are editable by any member by design). When no sharing service is
+wired, the gate degrades to caller-scoped read visibility (a `findOne`).
 `uploaded_by` is **server-stamped** from the session; a client-supplied value
 is ignored.
 
@@ -117,7 +119,7 @@ can be shared across records). Reclamation is handled by the platform LifecycleS
 | Operation | Requirement | Deny code |
 | --- | --- | --- |
 | Attach (create) | parent object opts in (`enable.files`) | `FILES_DISABLED` (403) |
-| Attach (create) | can read + edit the parent record | `ATTACHMENT_PARENT_ACCESS` (403) |
+| Attach (create) | can edit the parent record | `ATTACHMENT_PARENT_ACCESS` (403) |
 | List / read | inherits parent read visibility | *(filtered out)* |
 | Delete | uploader or parent editor (+ RBAC delete grant) | `ATTACHMENT_DELETE_DENIED` / `PERMISSION_DENIED` (403) |
 | Download | session + owner-or-parent-read (attachments scope) | `AUTH_REQUIRED` (401) / `ATTACHMENT_DOWNLOAD_DENIED` (403) |

content/docs/permissions/authentication.mdx

@@ -570,7 +570,7 @@ new AuthPlugin({
 #### Send Magic Link
 
 ```typescript
-const response = await fetch('http://localhost:3000/api/v1/auth/magic-link/send', {
+const response = await fetch('http://localhost:3000/api/v1/auth/sign-in/magic-link', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({
@@ -780,7 +780,9 @@ const response = await fetch('http://localhost:3000/api/v1/auth/sign-in/email',
 });
 
 const data = await response.json();
-const token = data.data.token;
+// better-auth returns the bearer token at the top level of a direct
+// `/sign-in/email` response (the client SDK re-wraps it under `data`).
+const token = data.token;
 
 // Use token in subsequent requests
 const protectedResponse = await fetch('http://localhost:3000/api/v1/data/task', {
@@ -830,7 +832,7 @@ All endpoints are available under `/api/v1/auth/*`:
 
 #### Magic Links
 
-- `POST /api/v1/auth/magic-link/send` - Send magic link email
+- `POST /api/v1/auth/sign-in/magic-link` - Send magic link email
 - `GET /api/v1/auth/magic-link/verify` - Verify magic link
 
 #### Phone Number (requires `plugins.phoneNumber`)

content/docs/permissions/authorization.mdx

@@ -377,13 +377,13 @@ The complete, prioritized gap map lives in issue **#2561** (the production
 | ADR | Owns |
 |---|---|
 | [0049](/adr/0049-no-unenforced-security-properties) | No unenforced security properties (enforce / mark / remove) |
-| [0054](/adr/0054-prove-it-runs) | Prove-it-runs — high-risk classes need runtime proofs |
+| [0054](/adr/0054-runtime-proof-for-authorable-surface) | Prove-it-runs — high-risk classes need runtime proofs |
 | [0056](/adr/0056-permission-model-landing-verification) | Permission-model landing: OWD, anonymous deny default, D10 matrix |
 | [0057](/adr/0057-erp-authorization-core-business-units-and-scope-depth) | Business units, scope depth, declarative RBAC seeding, platform-owned assignment |
 | [0066](/adr/0066-unified-authorization-model) | Unified model: capability registry, posture, precedence, future refinements |
-| [0068](/adr/0068-identity-roles) | Built-in identity positions (formerly "identity roles"), `EvalUser` |
+| [0068](/adr/0068-unified-user-context-and-built-in-identity-roles) | Built-in identity positions (formerly "identity roles"), `EvalUser` |
 | [0069](/adr/0069-enterprise-authentication-hardening) | Enterprise authentication hardening (phased) |
-| [0078](/adr/0078-no-inert-declarable-metadata) | No inert declarable metadata |
+| [0078](/adr/0078-no-silently-inert-metadata) | No inert declarable metadata |
 | [0086](/adr/0086-authz-metadata-config-boundary-and-cross-package-composition) | Metadata↔config boundary, package provenance, cross-package composition |
 | 0090 | Permission Model v2: position rename + vocabulary freeze, profile removal, fail-closed OWD default + external dial, audience anchors, principal taxonomy, publish linter, delegated administration, explain engine + access matrix |
 | 0091 | Grant lifecycle: validity windows + resolution-time filtering (L1, landed), delegation, break-glass, recertification substrate |

content/docs/permissions/explain.mdx

@@ -41,7 +41,7 @@ another user's private note reports:
   "layer": "vama_bypass",
   "verdict": "widens",
   "detail": "View/Modify All Data bypass held via [showcase_auditor] — ownership and sharing checks are skipped.",
-  "contributors": [{ "kind": "permission_set", "name": "showcase_auditor", "via": "position:auditor" }]
+  "contributors": [{ "kind": "permission_set", "name": "showcase_auditor", "via": "direct grant" }]
 }
 ```
 
@@ -95,9 +95,10 @@ A deployment without `@objectstack/plugin-security` answers 501.
 - **The [access-matrix snapshot gate](/docs/permissions/access-matrix)** —
   the publish-time matrix is the same evaluation run over representative
   (permission set × object) pairs; explain is the per-decision zoom lens.
-- **Delegated-administration audits** — explain reports both *who granted*
-  (the `granted_by` stamp) and, via contributor attribution, *who could
-  have* ([delegated administration](/docs/permissions/delegated-administration)).
+- **Delegated-administration audits** — via contributor attribution, each
+  layer's verdict names the permission set behind it and how the caller holds
+  it — including a position held *via delegation*
+  ([delegated administration](/docs/permissions/delegated-administration)).
 
 ## See also
 

content/docs/permissions/field-level-security.mdx

@@ -54,14 +54,14 @@ names in `details.forbiddenFields`:
 
 ```json
 {
-  "error": {
-    "code": "PERMISSION_DENIED",
-    "message": "[Security] Field write denied: not permitted to edit [salary, ssn] on 'employee'",
-    "details": {
-      "operation": "insert",
-      "object": "employee",
-      "forbiddenFields": ["salary", "ssn"]
-    }
+  "name": "PermissionDeniedError",
+  "code": "PERMISSION_DENIED",
+  "statusCode": 403,
+  "message": "[Security] Field write denied: not permitted to edit [salary, ssn] on 'employee'",
+  "details": {
+    "operation": "insert",
+    "object": "employee",
+    "forbiddenFields": ["salary", "ssn"]
   }
 }
 ```
@@ -100,4 +100,3 @@ writes.
 
 - [Permissions & Identity overview](/docs/permissions)
 - [Permission Sets](/docs/permissions/permission-sets)
-- [Permission Sets](/docs/permissions/permission-sets)

content/docs/permissions/permission-metadata.mdx

@@ -60,14 +60,14 @@ const salesUserPermission = {
 | :--- | :--- | :--- | :--- |
 | `name` | `string` | ✅ | Machine name (`snake_case`) |
 | `label` | `string` | optional | Display label |
-| `isDefault` | `boolean` | optional | [ADR-0090 D5] Install-time suggestion to bind this set to the `everyone` position (admin confirms; never auto-bound) |
+| `isDefault` | `boolean` | optional | [ADR-0090 D5] Baseline for the `everyone` position: an app-level default set is auto-bound at boot (guarded, idempotent); a package-shipped set instead becomes an install-time suggestion an admin confirms |
 | `adminScope` | `AdminScope` | optional | [ADR-0090 D12] Delegated-administration scope (BU subtree + assignable-set allowlist) |
 | `objects` | `Record<string, ObjectPermission>` | ✅ | Object-level permissions |
 | `fields` | `Record<string, FieldPermission>` | optional | Field-level security, keyed by `'object.field'` |
 | `systemPermissions` | `string[]` | optional | System-level capabilities |
 | `tabPermissions` | `Record<string, TabVisibility>` | optional | Tab/app visibility |
 | `rowLevelSecurity` | `RowLevelSecurityPolicy[]` | optional | Row-level security policies |
-| `contextVariables` | `Record<string, any>` | optional | RLS context variables |
+| `contextVariables` | `Record<string, any>` | optional | **Not implemented** — declared but ignored; the RLS engine reads only the `current_user.*` built-ins (see note below) |
 
 ## Object Permissions
 
@@ -129,19 +129,21 @@ Control which apps/tabs are visible to users:
 
 ```typescript
 tabPermissions: {
-  crm: 'visible',         // Always shown
-  admin: 'hidden',         // Never shown
-  reports: 'default_on',   // Shown by default, user can hide
-  analytics: 'default_off', // Hidden by default, user can show
+  crm: 'visible',           // Shown
+  admin: 'hidden',          // Hidden — removed from nav
+  reports: 'default_on',    // Shown today (per-user toggle default not yet implemented)
+  analytics: 'default_off', // Shown today (per-user toggle default not yet implemented)
 }
 ```
 
 | Visibility | Description |
 | :--- | :--- |
-| `visible` | Always visible, user cannot hide |
-| `hidden` | Always hidden, user cannot show |
-| `default_on` | Visible by default, user can toggle off |
-| `default_off` | Hidden by default, user can toggle on |
+| `visible` | Shown (also the effective behavior when a tab is left unset) |
+| `hidden` | Hidden — the app is removed from the user's navigation |
+| `default_on` | Shown today; reserved for a future per-user toggle default |
+| `default_off` | Shown today; reserved for a future per-user toggle default |
+
+**Note:** Only `hidden` currently affects runtime behavior — the app-visibility gate hides an app when its tab is set to `hidden` and treats every other value (including `default_off`) as visible. The per-user toggle / default-off semantics implied by `default_on`/`default_off` are not yet implemented.
 
 ## System Permissions
 
@@ -173,26 +175,21 @@ rowLevelSecurity: [
     using: "owner_id == current_user.id",
   },
   {
-    name: 'same_department',
+    name: 'same_organization',
     object: 'account',
     operation: 'select',
-    using: "department == current_user.department",
+    using: "organization_id == current_user.organization_id",
   },
 ]
 ```
 
 ### Context Variables
 
-Provide custom context values that RLS conditions can reference (in addition to
-the built-in `current_user.*` variables):
-
-```typescript
-contextVariables: {
-  allowed_regions: ['US', 'EU'],
-  access_level: 2,
-  custom_attribute: 'value',
-}
-```
+**Note:** The `contextVariables` field is **not yet implemented** — the RLS
+compiler never reads it, so custom context values are **not** injected into
+row-level conditions. Conditions can only reference the built-in `current_user.*`
+variables described below; authoring `contextVariables` raises a build-time
+liveness warning.
 
 The built-in context variables available in RLS `using`/`check` clauses include
 `current_user.id`, `current_user.organization_id`, and `current_user.positions`
@@ -274,10 +271,10 @@ const salesManagerPermission = {
 
   rowLevelSecurity: [
     {
-      name: 'team_accounts',
+      name: 'org_isolation',
       object: 'account',
       operation: 'select',
-      using: "team == current_user.team",
+      using: "organization_id == current_user.organization_id",
     },
   ],
 };