lcp 0.1.0

data/docs/reference/permissions.md

@@ -0,0 +1,715 @@
+# Permissions Reference
+
+File: `config/lcp_ruby/permissions/<name>.yml`
+
+Permission YAML defines role-based access control: who can perform which CRUD operations, which fields they can read and write, which custom actions they can execute, which records they can see, and which presenters they can access.
+
+## Top-Level Attributes
+
+Every permissions file **must** have `permissions:` as the top-level YAML key. Omitting it raises `MetadataError` at boot. Inside `permissions:`, the `model` and `roles` keys are required.
+
+```yaml
+permissions:
+  model: <model_name>
+  roles: {}
+  default_role: <role_name>
+  field_overrides: {}
+  record_rules: []
+  inherits_from: <parent_model>   # optional — cascade visibility from a parent
+```
+
+> **Common mistake:** Writing `model: deal` at the top level without wrapping it in `permissions:` will fail. The correct minimal file is:
+> ```yaml
+> permissions:
+>   model: deal
+>   roles:
+>     default:
+>       crud: [index, show]
+> ```
+
+### `model`
+
+| | |
+|---|---|
+| **Required** | yes |
+| **Type** | string |
+
+Name of the [model](models.md) these permissions apply to. Use `_default` to define fallback permissions applied when no model-specific permission file exists.
+
+**Fallback chain:** When resolving permissions for a model, the platform looks up: model-specific → STI parent (if the model is an [STI child](models.md#single-table-inheritance-sti)) → `_default`.
+
+> **Coverage merge by default** — when a per-model permission file exists, missing entries (`roles:`, `field_overrides:`, `record_rules:`) are filled in from the `_default` permission entry automatically. Per-model entries replace `_default`'s on collision (whole-entry replacement, no key-by-key blending). To opt out and use full-shadow semantics, declare `extends: "none"` on the per-model file. See [`extends:`](#extends) below and the [Permissions guide](../guides/permissions.md) for the full pattern catalog.
+
+```yaml
+# Model-specific permissions
+permissions:
+  model: deal
+
+# Default fallback permissions
+permissions:
+  model: _default
+```
+
+### `roles`
+
+| | |
+|---|---|
+| **Required** | yes |
+| **Type** | hash of role configs |
+
+Each key is a role name (matched against the values returned by `user.<role_method>`). A user can have multiple roles — see [Multiple Roles](#multiple-roles). See [Role Configuration](#role-configuration) below.
+
+> **DB-Backed Roles:** When `role_source` is set to `:model`, role names are validated against a database-backed registry before permission evaluation. Unknown roles are filtered out and logged. See [Role Source Reference](role-source.md) for setup details.
+
+### `default_role`
+
+| | |
+|---|---|
+| **Default** | `"viewer"` |
+| **Type** | string |
+
+The role assigned to users whose `role_method` does not match any key in `roles`, or when no user is present. This ensures every request has a defined permission set.
+
+### Role Resolution Order
+
+When the platform evaluates a request, it resolves permissions in **two stages**: first it picks which permission file applies to the model, then it picks which role config inside that file applies to the user.
+
+**Stage 1 — pick the permission definition (per-model lookup):**
+
+| Step | Lookup | Source |
+|------|--------|--------|
+| 1 | `permissions/<model>.yml` | model-specific file |
+| 2 | `permissions/<sti_parent>.yml` (only if model is an [STI child](models.md#single-table-inheritance-sti)) | parent's file |
+| 3 | `permissions/_default.yml` | shared fallback |
+
+If none of the three exists, the request is denied.
+
+**Stage 2 — pick the role config inside that file (per-user lookup):**
+
+| Step | Lookup | Notes |
+|------|--------|-------|
+| 1 | `roles[role_name]` for each role returned by `user.<role_method>` | If user has multiple roles, configs are merged with most-permissive semantics — see [Multiple Roles](#multiple-roles). |
+| 2 | `roles[default_role]` | Used when the user has no matching role, or when no user is present. |
+| 3 | `{}` (empty config) | Returned only when neither the user's role nor `default_role` exists in the file. Equivalent to denying every CRUD action. |
+
+**Worked example.** A user with `lcp_role: ["editor"]` accesses `Deal`. Files:
+
+```yaml
+# config/lcp_ruby/permissions/_default.yml
+permissions:
+  model: _default
+  roles:
+    viewer: { crud: [index, show] }
+  default_role: viewer
+```
+
+```yaml
+# config/lcp_ruby/permissions/deal.yml
+permissions:
+  model: deal
+  roles:
+    admin:  { crud: [index, show, create, update, destroy] }
+    editor: { crud: [index, show, update] }
+  default_role: viewer  # <-- but no `viewer` key in this file!
+```
+
+- Stage 1 → `deal.yml` (model match).
+- Stage 2 → `roles["editor"]` matches → `crud: [index, show, update]`.
+
+If the same user had `lcp_role: ["guest"]`:
+
+- Stage 1 → still `deal.yml`.
+- Stage 2 → no `roles["guest"]` → fall to `roles[default_role]` = `roles["viewer"]` → after coverage merge, `viewer` is inherited from `_default` (assuming `_default` defines it) → request resolves with `_default`'s `viewer` config.
+
+> **Default behavior is coverage merge.** Roles missing from `deal.yml` are filled in from the `_default` permission entry. The platform's [`extends:`](#extends) keyword controls this: absent or `"_default"` (the default) means merge; `"none"` means full shadow. The post-merge validator warns if `default_role` references a role that's still missing after merge — typo and `extends: "none"` opt-out cases are caught at boot.
+
+### `field_overrides`
+
+| | |
+|---|---|
+| **Default** | `{}` |
+| **Type** | hash |
+
+Per-field access overrides that take precedence over the role's general `fields` setting. See [Field Overrides](#field-overrides).
+
+### `record_rules`
+
+| | |
+|---|---|
+| **Default** | `[]` |
+| **Type** | array |
+
+Rules that deny CRUD operations on records matching a condition, with optional role exceptions. See [Record Rules](#record-rules).
+
+### `extends`
+
+| | |
+|---|---|
+| **Default** | absent (= `"_default"`, coverage merge active) |
+| **Type** | string |
+| **Allowed values** | `"_default"`, `"none"` |
+
+Controls whether the per-model permission file coverage-merges with the `_default` permission entry. With merge active (the default), missing entries in `roles:`, `field_overrides:`, and `record_rules:` are filled in from `_default`. With `"none"`, the per-model file fully shadows `_default` — useful for models with a fundamentally different role taxonomy (e.g., public-facing or security-sensitive boundaries).
+
+```yaml
+# Default — coverage merge with _default; redundant to declare explicitly
+permissions:
+  model: deal
+  # extends: "_default"   # omitted; merge is the default
+  roles:
+    admin: { ... }   # editor/viewer/etc. inherited from _default
+
+# Full opt-out — security boundary or unique role taxonomy
+permissions:
+  model: secret_vault_entry
+  extends: "none"
+  roles:
+    vault_admin: { ... }   # no merge with _default
+```
+
+Whole-entry replacement applies — per-model entries replace `_default`'s entirely (no key-by-key blending of e.g. `crud` from `_default` with `fields` from per-model). For a single inherited rule that you need to neutralize without losing the rest of the merge, override it with the same `name:` and an inert `effect:` (see the [Permissions guide](../guides/permissions.md#a7-disable-a-specific-inherited-record_rule)).
+
+**Note vs. `inherits_from:`** — `extends:` is file-level merge of role/override/rule definitions; `inherits_from:` (below) is record-level visibility cascade through `belongs_to`. The two are orthogonal and can both appear in the same file. Validator hints fire on the most likely typo cases (`extends: <model_name>` → "did you mean `inherits_from:`?", and vice versa).
+
+The `_default` permission entry itself **must not** declare `extends:` (it is the merge source) or `inherits_from:` (it would auto-wire create-time validators across every model that lacks its own `inherits_from:`). Both restrictions are enforced at boot.
+
+See the [Permissions guide](../guides/permissions.md) for the full pattern catalog and the design doc at [docs/design/permissions_default_role_coverage.md](../design/permissions_default_role_coverage.md).
+
+### `inherits_from`
+
+| | |
+|---|---|
+| **Default** | none |
+| **Type** | string \| array \| object |
+
+Cascades record visibility from one or more **parent** permission definitions. A child record is visible iff its parent record (resolved via `belongs_to`) is visible under the parent's `policy_scope` — and the parent's per-record `:show?` passes. Lets you write the access rule once on the ancestor and reuse it for every leaf model.
+
+**Three forms:**
+
+```yaml
+# Single parent, auto-detected via belongs_to
+inherits_from: student
+
+# Multiple parents (default mode: intersection — all must permit)
+inherits_from: [student, course]
+
+# Object form: explicit via and mode
+inherits_from:
+  parent: student
+  via: primary_student        # required when ambiguous belongs_to
+  mode: intersection          # or "union"
+```
+
+**Override per role.** A role's `scope:` overrides inheritance for that role:
+
+| Role-level `scope:` | Effect |
+|---|---|
+| key absent | inherit from `inherits_from` |
+| `scope: all` | opt out — see all records |
+| `scope: { type: ..., ... }` | role-level override, no inheritance |
+| `scope: ~` (explicit nil) | **rejected by validator** — write `scope: all` |
+
+**Composition with `record_rules`.** The child's local `record_rules` apply on top of inheritance. Order: `can?(action)` → parent's `:show?` (via the inheritance walk) → local `record_rules`. A child can only be **stricter** than its parent, never more permissive.
+
+**Create-time validation auto-wires.** When YAML declares `inherits_from:`, the platform additionally wires `LcpRuby::Authorization::InheritedParentValidator` onto the model so `record.save` rejects a child whose declared FK points at a parent the current user cannot see. No per-controller boilerplate. See [Inherited Permissions guide — Create-time parent validation](../guides/inherited-permissions.md#create-time-parent-validation) for the full behavior table (when it fires, when it skips, known bypass paths).
+
+**Limitations:**
+- `belongs_to` only — no polymorphic, no `has_many`. Polymorphic belongs_to is rejected by the validator; `has_many` traversal stays in `record_rules` with `collection:` quantifiers.
+- Self-inheritance (`inherits_from: <self>`) is rejected. Org-tree hierarchies stay in the host app's user-method scope (`accessible_*_ids`).
+- Cycle detection runs at boot; `Set#dup` per branch keeps diamond shapes (A→B, A→C, B→D, C→D) from false-positiving.
+- Maximum cascade depth is `LcpRuby.configuration.max_inheritance_depth` (default `6`). Each `inherits_from` hop adds a nested IN sub-query at scope-resolve time; deep chains stress DB planners (especially SQLite). Realistic domains rarely exceed 4 hops (factory → line → machine → reading); raise the bound only when justified.
+
+See the [Inherited Permissions guide](../guides/inherited-permissions.md) for end-to-end examples and the design at [docs/design/hierarchical_record_permissions.md](../design/hierarchical_record_permissions.md).
+
+## Role Configuration
+
+Each role is a hash with the following attributes:
+
+```yaml
+roles:
+  admin:
+    crud: [index, show, create, update, destroy]
+    fields:
+      readable: all
+      writable: all
+    actions: all
+    scope: all
+    presenters: all
+```
+
+### `crud`
+
+| | |
+|---|---|
+| **Required** | yes |
+| **Type** | array of strings |
+| **Allowed values** | `index`, `show`, `create`, `update`, `destroy`, `restore`, `permanently_destroy` |
+
+CRUD operations this role can perform. The permission system automatically resolves action aliases:
+
+| Alias | Resolves To |
+|-------|-------------|
+| `edit` | `update` |
+| `new` | `create` |
+
+You only need to list `create` and `update` — `new` and `edit` are inferred.
+
+The `restore` and `permanently_destroy` values are used with [soft delete](models.md#soft_delete) models. Include them in the CRUD list for roles that should be able to restore discarded records or permanently delete them from archive presenters.
+
+```yaml
+# Full access
+crud: [index, show, create, update, destroy]
+
+# Full access with soft delete management
+crud: [index, show, create, update, destroy, restore, permanently_destroy]
+
+# Read-only
+crud: [index, show]
+
+# Create and read, but no update or delete
+crud: [index, show, create]
+```
+
+### `fields`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | hash with `readable` and `writable` keys |
+
+Controls field-level access.
+
+```yaml
+fields:
+  readable: all          # Can read all fields
+  writable: all          # Can write all fields
+
+fields:
+  readable: [title, stage, value]   # Can only read these fields
+  writable: [title, stage]          # Can only write these fields
+
+fields:
+  readable: all
+  writable: []           # Read-only: can read everything, write nothing
+```
+
+- `"all"` — grants access to every field defined in the model (including `custom_data` if the model has `custom_fields: true`)
+- Array of field names — grants access to only those fields
+- `[]` (empty array) — no access
+
+> **Custom Fields:** For models with `custom_fields: true`, the virtual field name `custom_data` controls access to all custom fields. Include `custom_data` in the `readable`/`writable` list to grant access, or use `all` which includes it automatically. See [Custom Fields Reference](custom-fields.md#permissions) for details.
+
+> **Positioning:** For models with [`positioning`](models.md#positioning), the position field (e.g., `position`) must be included in the `writable` list for the user to reorder records via drag-and-drop. Reordering requires **both** `update` in `crud` **and** the position field in `writable`. This allows roles that can edit record data but cannot change ordering:
+>
+> ```yaml
+> roles:
+>   manager:
+>     crud: [index, show, create, update, destroy]
+>     fields:
+>       writable: [name, description, position]    # can reorder
+>   editor:
+>     crud: [index, show, update]
+>     fields:
+>       writable: [name, description]              # can edit but NOT reorder
+>   viewer:
+>     crud: [index, show]
+>     fields:
+>       readable: all                              # no drag handles (no update permission)
+> ```
+
+### `actions`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Type** | string or hash |
+
+Controls which custom actions and non-CRUD built-in actions the role can execute. This includes custom actions defined on the presenter as well as built-in non-CRUD actions like `export`.
+
+```yaml
+# Can execute all actions (including export)
+actions: all
+
+# Granular control
+actions:
+  allowed: [export, close_won, reopen]
+  denied: [force_delete]
+
+# Allow all except specific ones
+actions:
+  allowed: all
+  denied: [force_delete]
+
+# No actions (export button hidden)
+actions:
+  allowed: []
+```
+
+The `denied` list takes precedence: if an action appears in both `allowed` and `denied`, it is denied.
+
+**Note:** The `export` action is a built-in non-CRUD action. It is gated through the `actions` config rather than the `crud` list. See [Export Reference](export.md) for details.
+
+### `scope`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | all records visible |
+| **Type** | string or hash |
+
+Controls which records the role can see (row-level security). Set to `"all"` for unrestricted access, or use one of four scope types.
+
+**Quick comparison:**
+
+| Type | Use case | Required attrs | Example |
+|---|---|---|---|
+| [`field_match`](#scope-type-field_match) | Per-user records (owner/assignee) | `field`, `value` | `owner_id == current_user.id` |
+| [`association`](#scope-type-association) | Multi-group / multi-tenant access | `field`, `method` | `team_id IN user.team_ids` |
+| [`where`](#scope-type-where) | Static role-based filter | `conditions` | `active: true` |
+| [`custom`](#scope-type-custom) | Complex / custom logic | `method` | model's `visible_to_user(user)` scope |
+
+#### Scope Type: `field_match`
+
+Filters records where a field matches a value derived from the current user.
+
+```yaml
+scope:
+  type: field_match
+  field: owner_id
+  value: current_user.id
+```
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `field` | string | Column name to filter on |
+| `value` | string | Value reference (see below) |
+
+**Value references:**
+- `current_user.id` — resolves to `user.id`
+- `current_user.<method>` — resolves to `user.<method>` (e.g., `current_user.department_id` calls `user.department_id`)
+- Any other string — used as a literal value
+
+See [Dynamic References](dynamic-references.md) for the full grammar (including `record.<field>`, `current_date`, etc.) and how typos are caught at boot.
+
+#### Scope Type: `association`
+
+Filters records where a field's value is in a collection returned by a user method.
+
+```yaml
+scope:
+  type: association
+  field: department_id
+  method: department_ids
+```
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `field` | string | Column name to filter on |
+| `method` | string | Method on the user object that returns an array of allowed values |
+
+Use this when users belong to multiple groups (e.g., departments, teams) and should see records from any of their groups.
+
+#### Scope Type: `where`
+
+Applies a static `WHERE` clause.
+
+```yaml
+scope:
+  type: where
+  conditions: { active: true }
+```
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `conditions` | hash | Hash of column/value pairs passed to `ActiveRecord::Base.where` |
+
+Use this for role-based static filtering (e.g., viewers can only see active records).
+
+#### Scope Type: `custom`
+
+Delegates to a named scope method on the model, passing the current user as an argument.
+
+```yaml
+scope:
+  type: custom
+  method: visible_to_user
+```
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `method` | string | Scope method name on the model class |
+
+The model must define this scope accepting a user parameter. For LCP-managed (dynamic) models, register the scope from a `LcpRuby.on_models_loaded` block in `config/initializers/lcp_extensions.rb`:
+
+```ruby
+# config/initializers/lcp_extensions.rb
+LcpRuby.on_models_loaded do |loader|
+  LcpRuby::Dynamic::Student.scope :visible_to_user, ->(user) {
+    where(region: user.region)
+  }
+end
+```
+
+For host AR models bound via `bind_to:`, the scope is defined on the host class normally:
+
+```ruby
+# app/models/student.rb
+class Student < ApplicationRecord
+  scope :visible_to_user, ->(user) { where(region: user.region) }
+end
+```
+
+The boot-time [invariant_check](invariant_check.md) (`AUTH-001`) verifies that every `type: custom` scope's `method` is registered on the dynamic model class — typos surface at `bin/rails s` boot rather than as a silent fail-open at the first request.
+
+Use this for complex filtering logic that cannot be expressed with the other scope types.
+
+### `presenters`
+
+| | |
+|---|---|
+| **Required** | no |
+| **Default** | all presenters accessible (unrestricted) |
+| **Type** | string or array |
+
+Controls which presenters the role can access. This affects both direct URL access and **menu visibility**. Use this when a model has multiple presenters and different roles should see different UI views.
+
+```yaml
+# Omit to allow all presenters (default — no restriction)
+# presenters: ...
+
+# Explicitly allow all presenters (same as omitting)
+presenters: all
+
+# Restrict to specific presenters
+presenters: [deal, deal_pipeline]
+```
+
+When `presenters` is omitted (or `null`), the role can access all presenters for this model. Specify a list only when you need to **restrict** which presenters the role can see.
+
+## Field Overrides
+
+Override field-level access per role, independent of the role's general `fields` setting. These take precedence over the `readable`/`writable` lists in the role config.
+
+**YAML tree placement** — `field_overrides:` sits at the **same level as `roles:`**, directly under `permissions:`. It is not nested inside any single role; the keys inside it are field names (not role names), and each field's value lists which roles get which access.
+
+```yaml
+permissions:
+  model: deal
+  roles:               # ← roles live here …
+    admin: { … }
+    sales_rep: { … }
+  field_overrides:     # ← … and field_overrides is a sibling, not a child of roles
+    value:             # ← key is a FIELD name
+      readable_by: [admin, sales_rep]   # ← values are ROLE lists
+      writable_by: [admin]
+    ssn:
+      readable_by: [admin]
+      masked_for: [sales_rep, viewer]
+```
+
+A common mistake is to nest `field_overrides:` inside a role block — that is silently ignored because the role schema does not accept this key.
+
+### Override Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `readable_by` | array of role names | Only these roles can read this field |
+| `writable_by` | array of role names | Only these roles can write this field |
+| `masked_for` | array of role names | These roles see a masked value instead of the actual data |
+
+**How it works:**
+- If `readable_by` is set on a field, the role must be in that list to read it — even if the role's `fields.readable` is set to `all`.
+- If `writable_by` is set, the role must be in that list to write it.
+- `masked_for` is a display-level flag. The `PermissionEvaluator.field_masked?` method returns `true` for roles in the list, and the UI layer can choose how to mask (e.g., show "***").
+
+## Record Rules
+
+Rules that conditionally deny CRUD operations based on record field values.
+
+```yaml
+record_rules:
+  - name: closed_deals_readonly
+    condition: { field: stage, operator: in, value: [closed_won, closed_lost] }
+    effect:
+      deny_crud: [update, destroy]
+      except_roles: [admin]
+```
+
+### Record Rule Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Human-readable rule identifier |
+| `condition` | object | [Condition](condition-operators.md) evaluated against each record |
+| `effect` | object | What happens when the condition matches |
+
+### Effect Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `deny_crud` | array | CRUD operations to deny (e.g., `[update, destroy]`) |
+| `except_roles` | array | Roles exempt from the denial |
+
+**AND semantics.** A user can perform action X on record R if and only if **both** conditions hold:
+
+1. The role's `crud` list includes X (`can?(action)`), **AND**
+2. No matching record rule denies X for R (`can_for_record?(action, record)`).
+
+If the role-level CRUD check fails, the engine never evaluates record rules — there is nothing to "narrow" because the action was never granted in the first place. Record rules can only **subtract** from what the role's `crud` already allows; they cannot grant access.
+
+**Evaluation order:**
+1. The role's `crud` list is checked first (`can?`)
+2. Then each record rule's condition is evaluated against the specific record (`can_for_record?`) using [all 12 condition operators](condition-operators.md)
+3. If the condition matches and the action is in `deny_crud` and the role is not in `except_roles`, the action is denied
+
+Action aliases are resolved before checking `deny_crud`: `edit` maps to `update` and `new` maps to `create`. A rule with `deny_crud: [update]` also denies `edit`.
+
+This enables patterns like "closed deals are read-only for everyone except admins."
+
+**Action button visibility:** Record rules automatically hide action buttons on index pages. When `can_for_record?` denies `update` or `destroy` for a record, the corresponding `edit`/`destroy` buttons are hidden for that row — no need to duplicate the condition in the presenter's `visible_when`. The `show` action is not affected by record rules (if a record is visible in the list, its show link remains clickable).
+
+Both record rules and `visible_when` apply simultaneously (AND semantics). Use `visible_when` for additional UI-only conditions beyond what record rules cover.
+
+## Complete Example
+
+```yaml
+permissions:
+  model: deal
+
+  roles:
+    admin:
+      crud: [index, show, create, update, destroy]
+      fields: { readable: all, writable: all }
+      actions: all
+      scope: all
+      presenters: all
+
+    sales_rep:
+      crud: [index, show, create, update]
+      fields:
+        readable: all
+        writable: [title, stage, company_id, contact_id]
+      actions:
+        allowed: [close_won]
+        denied: []
+      scope: all
+      presenters: [deal]
+
+    viewer:
+      crud: [index, show]
+      fields: { readable: [title, stage, value], writable: [] }
+      actions: { allowed: [] }
+      scope: all
+      presenters: [deal_pipeline]
+
+  default_role: viewer
+
+  field_overrides:
+    value:
+      writable_by: [admin]
+      readable_by: [admin, sales_rep]
+
+  record_rules:
+    - name: closed_deals_readonly
+      condition: { field: stage, operator: in, value: [closed_won, closed_lost] }
+      effect:
+        deny_crud: [update, destroy]
+        except_roles: [admin]
+```
+
+## Multiple Roles
+
+Users can have multiple roles simultaneously. The `role_method` (default: `lcp_role`) must return an **array of role name strings** (e.g., `["admin", "sales_rep"]`).
+
+When a user has multiple roles, permissions are merged using **union (most-permissive) semantics**:
+
+| Aspect | Merge Rule |
+|--------|------------|
+| `crud` | Union of all roles' CRUD lists |
+| `fields.readable` | Union — if any role has `"all"`, result is `"all"` |
+| `fields.writable` | Union — if any role has `"all"`, result is `"all"` |
+| `actions.allowed` | Union — if any role has `"all"`, result is `"all"` |
+| `actions.denied` | Intersection — denied only if denied by all roles |
+| `scope` | If any role has `"all"`, result is `"all"`; otherwise OR-union of all roles' scopes (see note below) |
+| `presenters` | Union — if any role has `"all"`, result is `"all"` |
+
+**Scope merge note:** When multiple roles define different non-"all" scopes (e.g., one role uses `field_match` and another uses `where`), the resulting query is the **OR-union** of all per-role scopes — a record is visible if any of the user's roles would grant visibility. Internally this is expressed as a synthesized `type: union` scope spec that `ScopeBuilder` lowers to `relation_a.or(relation_b).or(...)`. Each per-role scope is built on the same base relation, so the SQL shape is `WHERE (scope_a) OR (scope_b) OR ...`. This composes with `inherits_from` (a role with no `scope:` contributes the inherited sub-query as its branch of the union) and with `scope: all` short-circuiting the merge to unrestricted access.
+
+**Field overrides** with multiple roles:
+- `readable_by` / `writable_by` — access granted if the user has **any** matching role
+- `masked_for` — masked only if **all** of the user's roles are in the `masked_for` list
+
+**Record rules** with multiple roles:
+- `except_roles` — the user is exempt if **any** of their roles is in the exception list
+
+```ruby
+# User model example
+class User < ApplicationRecord
+  def lcp_role
+    roles.pluck(:name)  # => ["admin", "sales_rep"]
+  end
+end
+```
+
+## Menu Filtering
+
+The navigation menu automatically filters out presenters the current user cannot access. If a role's `presenters` list does not include a given presenter, that presenter's menu item is hidden. This uses the same `can_access_presenter?` check as the controller-level authorization.
+
+## Audit Logging
+
+Every authorization denial is logged with details including the user ID, roles, action, resource, and IP address:
+
+```
+[LcpRuby::Auth] Access denied: user=42 roles=viewer action=update resource=deal detail=not authorized
+```
+
+Additionally, an `ActiveSupport::Notifications` event is published for each denial:
+
+```ruby
+ActiveSupport::Notifications.subscribe("authorization.lcp_ruby") do |name, start, finish, id, payload|
+  # payload contains: user_id, roles, action, resource, detail, ip
+  AuditLog.create!(
+    user_id: payload[:user_id],
+    action: "access_denied",
+    details: payload.except(:ip)
+  )
+end
+```
+
+This allows host applications to implement custom audit logging, alerting, or metrics collection.
+
+## Custom Field Permissions
+
+When a model has `custom_fields: true`, individual custom field names can be used in `fields.readable`, `fields.writable`, and `field_overrides`.
+
+The aggregate `custom_data` key still works as a catch-all for all custom fields. Individual field names provide per-field granularity:
+
+```yaml
+permissions:
+  model: project
+  roles:
+    admin:
+      fields:
+        readable: all           # all fields including all custom fields
+        writable: all
+    editor:
+      fields:
+        readable: [name, website, phone]  # specific custom fields
+        writable: [name, website]          # only website writable
+    support:
+      fields:
+        readable: [name, custom_data]      # name + ALL custom fields
+        writable: []
+  field_overrides:
+    internal_notes:                         # per-custom-field override
+      readable_by: [admin, manager]
+      writable_by: [admin]
+```
+
+See [Custom Fields Reference](custom-fields.md#permissions) for details.
+
+## DB-Backed Permissions
+
+Permissions can be stored in a database model instead of YAML files, enabling runtime editing. See [Permission Source Reference](permission-source.md) for setup and configuration.
+
+Source: `lib/lcp_ruby/metadata/permission_definition.rb`, `lib/lcp_ruby/authorization/permission_evaluator.rb`, `lib/lcp_ruby/authorization/scope_builder.rb`