docs: restructure B20 guides and rewrite execution architecture (base-std@be6d045)

docs/specifications/b20/reference/constants-addresses.mdx

@@ -45,7 +45,7 @@ These addresses are identical on every network where B20 is active.
 | Name | Value |
 |---|---|
 | `ALWAYS_ALLOW` | `0` |
-| `ALWAYS_BLOCK` | `(uint64(uint8(IPolicyRegistry.PolicyType.ALLOWLIST)) << 56) \| 1` |
+| `ALWAYS_BLOCK` | `(uint64(uint8(IPolicyRegistry.PolicyType.ALLOWLIST)) << 56) \| 1` |
 
 Custom policy IDs use this layout:
 

docs/specifications/b20/reference/interfaces/i-policy-registry/composite-policy-child-ids.mdx

@@ -1,10 +1,8 @@
 ---
 title: "IPolicyRegistry.compositePolicyChildIds"
-description: "Generated B20 reference for compositePolicyChildIds(uint64)."
+description: "Returns the child-policy set of a composite policy."
 ---
 
-
-
 ## Signature
 
 ```solidity IPolicyRegistry.sol
@@ -18,26 +16,31 @@ function compositePolicyChildIds(uint64 policyId) external view returns (uint64[
 
 ## Description
 
-Returns the child-policy set of the composite `policyId`.
-Dev: Child-policies are listed in the order they were last written.
-Dev: Returns an empty array for simple policies, built-in sentinels, unknown IDs, and
-malformed IDs. Never reverts.
-Dev: An empty return unambiguously means "not a composite".
-Dev: The registry preserves the caller's ordering verbatim and neither sorts nor
-de-duplicates.
-Param: policyId Policy to query.
-Return: Child policy IDs, or an empty array.
+Returns the ordered child-policy ID set of the composite identified by `policyId`.
 
-## Access Control
+- Child policies are returned in the order they were last written; the registry preserves caller ordering verbatim without sorting or de-duplicating.
+- Returns an empty array for simple policies, built-in sentinels (`ALWAYS_ALLOW`, `ALWAYS_BLOCK`), unknown IDs, and malformed IDs.
+- Never reverts.
+- An empty return unambiguously means "not a composite".
+
+## Parameters
 
-Read-only or ERC-20-standard access rules unless the NatSpec states otherwise.
+| Name | Type | Description |
+|---|---|---|
+| `policyId` | `uint64` | The composite policy to query. |
 
-## Policy Interaction
+## Returns
+
+| Type | Description |
+|---|---|
+| `uint64[] memory` | Child policy IDs, or an empty array if `policyId` is not a composite. |
+
+## Access Control
 
-This is part of the singleton PolicyRegistry surface used by B20 policy scopes.
+Read-only. Always callable regardless of whether the PolicyRegistry feature is active.
 
 ## Example
 
 ```solidity Usage Example
-IPolicyRegistry(target).compositePolicyChildIds(arg0);
+uint64[] memory children = IPolicyRegistry(registry).compositePolicyChildIds(policyId);
 ```

docs/specifications/b20/reference/interfaces/i-policy-registry/create-composite-policy.mdx

@@ -1,10 +1,8 @@
 ---
 title: "IPolicyRegistry.createCompositePolicy"
-description: "Generated B20 reference for createCompositePolicy(address,uint8,uint64[])."
+description: "Creates a new composite policy combining existing simple policies under a logic gate."
 ---
 
-
-
 ## Signature
 
 ```solidity IPolicyRegistry.sol
@@ -18,33 +16,49 @@ function createCompositePolicy(address admin, PolicyType policyType, uint64[] ca
 
 ## Description
 
-Creates a new composite policy that combines existing simple policies under a logic
-gate.
-Dev: Child policies must be simple policies (ALLOWLIST or BLOCKLIST), never another composite.
-The child-policy set is capped at 4.
-Dev: Reverts with `IncompatiblePolicyType` when `policyType` is not UNION or INTERSECT.
-Dev: Reverts with `ZeroAddress` when `admin` is `address(0)`.
-Dev: Reverts with `ChildPoliciesOutsideOfRange` when `childPolicyIds.length` is not in
-`[MIN_COMPOSITE_CHILD_POLICIES, MAX_COMPOSITE_CHILD_POLICIES]`.
-Dev: Reverts with `PolicyNotFound` when any child policy does not exist.
-Dev: Reverts with `InvalidChildPolicy` when any child policy is not a simple policy or a built-in policy.
-Dev: Panics with arithmetic overflow (Panic 0x11) when the policy counter has reached its maximum value.
-Param: admin          Initial admin authorized to update child policies and transfer or renounce
-administration.
-Param: policyType     UNION or INTERSECT.
-Param: childPolicyIds Existing simple policy IDs to combine.
-Return: newPolicyId The newly assigned composite policy ID.
+Creates a new composite policy that combines 2–4 existing simple (`ALLOWLIST` or `BLOCKLIST`) policies under a `UNION` (OR) or `INTERSECT` (AND) logic gate. The composite references its children live: `isAuthorized` reads current child membership on every call, so updating a child's membership immediately affects what the composite authorizes.
+
+The new policy is assigned a `uint64` ID whose top byte encodes `PolicyType`; the low 56 bits come from a global counter.
+
+## Parameters
+
+| Name | Type | Description |
+|---|---|---|
+| `admin` | `address` | Initial admin authorized to update child policies and transfer or renounce administration. Must not be `address(0)`. |
+| `policyType` | `PolicyType` (`uint8`) | Must be `UNION` or `INTERSECT`. |
+| `childPolicyIds` | `uint64[]` | Existing simple policy IDs to combine. Must contain 2–4 entries (`MIN_COMPOSITE_CHILD_POLICIES` to `MAX_COMPOSITE_CHILD_POLICIES`). No composites and no built-in sentinels (`ALWAYS_ALLOW` / `ALWAYS_BLOCK`). |
+
+## Returns
+
+| Name | Type | Description |
+|---|---|---|
+| `newPolicyId` | `uint64` | The newly assigned composite policy ID. |
+
+## Revert Conditions
+
+| Error | Condition |
+|---|---|
+| `ZeroAddress` | `admin` is `address(0)`. |
+| `IncompatiblePolicyType` | `policyType` is not `UNION` or `INTERSECT`. |
+| `ChildPoliciesOutsideOfRange` | `childPolicyIds.length` is outside `[MIN_COMPOSITE_CHILD_POLICIES, MAX_COMPOSITE_CHILD_POLICIES]` (2–4 inclusive). |
+| `PolicyNotFound` | Any child policy ID does not exist. |
+| `InvalidChildPolicy` | Any child is a composite policy or a built-in sentinel. |
+| `Panic(0x11)` | The global policy counter has reached its maximum value (arithmetic overflow). |
 
 ## Access Control
 
-Permissionless creation, but state-changing registry calls require the feature to be active.
+Permissionless creation, but this call reverts with `FeatureNotActivated` while the PolicyRegistry feature is inactive.
+
+## Events Emitted
 
-## Policy Interaction
+On success, three events are emitted:
 
-This is part of the singleton PolicyRegistry surface used by B20 policy scopes.
+- `PolicyCreated(newPolicyId, creator, policyType)`
+- `PolicyAdminUpdated(newPolicyId, address(0), admin)`
+- `CompositePolicyUpdated(newPolicyId, creator, childPolicyIds)`
 
 ## Example
 
 ```solidity Usage Example
-IPolicyRegistry(target).createCompositePolicy(arg0, arg1, arg2);
+IPolicyRegistry(target).createCompositePolicy(admin, PolicyType.UNION, childPolicyIds);
 ```

docs/specifications/b20/reference/interfaces/i-policy-registry/create-policy.mdx

@@ -1,10 +1,8 @@
 ---
 title: "IPolicyRegistry.createPolicy"
-description: "Generated B20 reference for createPolicy(address,uint8)."
+description: "Creates a new simple (ALLOWLIST or BLOCKLIST) policy with no initial members."
 ---
 
-
-
 ## Signature
 
 ```solidity IPolicyRegistry.sol
@@ -18,20 +16,34 @@ function createPolicy(address admin, PolicyType policyType) external returns (ui
 
 ## Description
 
-Creates a new simple policy with no initial members. Permissionless.
-Dev: Reverts with `ZeroAddress` when `admin` is `address(0)`.
-Dev: Reverts with `IncompatiblePolicyType` when `policyType` is a composite gate.
-Param: admin      Initial admin authorized to modify membership and transfer or renounce administration.
-Param: policyType BLOCKLIST or ALLOWLIST.
-Return: newPolicyId The newly assigned policy ID.
+Creates a new simple policy with no initial members. Any caller may invoke this function. The newly created policy has an empty member set and the specified `admin`.
+
+To seed an initial member set in the same call, use `createPolicyWithAccounts` instead.
+
+## Parameters
+
+| Name | Type | Description |
+|---|---|---|
+| `admin` | `address` | Initial admin authorized to modify membership and transfer or renounce administration. Must not be `address(0)`. |
+| `policyType` | `PolicyType` | `ALLOWLIST` or `BLOCKLIST`. Composite gate types (`UNION`, `INTERSECT`) are not accepted here. |
+
+## Returns
+
+| Name | Type | Description |
+|---|---|---|
+| `newPolicyId` | `uint64` | The newly assigned policy ID. The top byte encodes the `PolicyType`; the low 56 bits are a global counter. |
 
 ## Access Control
 
-Permissionless creation, but state-changing registry calls require the feature to be active.
+Permissionless creation. This is a state-changing call, so it reverts with `FeatureNotActivated` while the PolicyRegistry feature is inactive.
 
-## Policy Interaction
+## Revert Conditions
 
-This is part of the singleton PolicyRegistry surface used by B20 policy scopes.
+| Error | Condition |
+|---|---|
+| `ZeroAddress` | `admin` is `address(0)`. |
+| `IncompatiblePolicyType` | `policyType` is a composite gate (`UNION` or `INTERSECT`). |
+| `FeatureNotActivated` | The PolicyRegistry feature has not been activated. |
 
 ## Example
 

docs/specifications/b20/reference/interfaces/i-policy-registry/finalize-update-admin.mdx

@@ -1,10 +1,8 @@
 ---
 title: "IPolicyRegistry.finalizeUpdateAdmin"
-description: "Generated B20 reference for finalizeUpdateAdmin(uint64)."
+description: "Completes a two-step admin transfer on a PolicyRegistry policy."
 ---
 
-
-
 ## Signature
 
 ```solidity IPolicyRegistry.sol
@@ -18,22 +16,31 @@ function finalizeUpdateAdmin(uint64 policyId) external;
 
 ## Description
 
-Completes a two-step admin transfer. Promotes the caller to active admin and clears the pending slot.
-Dev: Reverts with `PolicyNotFound` when `policyId` does not exist.
-Dev: Reverts with `NoPendingAdmin` when no transfer is in flight.
-Dev: Reverts with `Unauthorized` when the caller is not the staged pending admin.
-Param: policyId Policy whose admin transfer is being finalized.
+Completes a two-step admin transfer. The caller must be the staged pending admin. On success, the caller becomes the active admin and the pending slot is cleared.
+
+This function is gated by the `ActivationRegistry`; it reverts with `FeatureNotActivated` while the feature is inactive.
+
+## Parameters
+
+| Name | Type | Description |
+|---|---|---|
+| `policyId` | `uint64` | ID of the policy whose pending admin transfer is being finalized. |
 
 ## Access Control
 
-Callable only by the staged pending admin for the target policy; finalization promotes the caller to active admin.
+Callable only by the staged pending admin for the target policy.
 
-## Policy Interaction
+## Revert Conditions
 
-This is part of the singleton PolicyRegistry surface used by B20 policy scopes.
+| Error | Condition |
+|---|---|
+| `FeatureNotActivated` | The PolicyRegistry feature is not yet active. |
+| `PolicyNotFound` | `policyId` does not exist. |
+| `NoPendingAdmin` | No transfer is in flight for this policy. |
+| `Unauthorized` | Caller is not the staged pending admin. |
 
 ## Example
 
 ```solidity Usage Example
-IPolicyRegistry(target).finalizeUpdateAdmin(arg0);
+IPolicyRegistry(target).finalizeUpdateAdmin(policyId);
 ```

docs/specifications/b20/reference/interfaces/i-policy-registry/is-authorized.mdx

@@ -3,8 +3,6 @@ title: "IPolicyRegistry.isAuthorized"
 description: "Generated B20 reference for isAuthorized(uint64,address)."
 ---
 
-
-
 ## Signature
 
 ```solidity IPolicyRegistry.sol
@@ -18,21 +16,30 @@ function isAuthorized(uint64 policyId, address account) external view returns (b
 
 ## Description
 
-Returns whether `account` is authorized under `policyId`. Never reverts; unknown
-or malformed IDs collapse to empty-member-set semantics (ALLOWLIST -> false,
-BLOCKLIST -> true).
-Dev: Callers that store policy IDs MUST validate `policyExists(policyId)` at write time.
-Param: policyId Policy to query.
-Param: account  Account to check.
-Return: Whether `account` is authorized.
+Returns whether `account` is authorized under `policyId`. Never reverts; unknown or malformed IDs collapse to empty-member-set semantics (`ALLOWLIST` → `false`, `BLOCKLIST` → `true`).
+
+Callers that store policy IDs **must** validate `policyExists(policyId)` at write time. A typo'd `BLOCKLIST` ID silently behaves as `ALWAYS_ALLOW` because an unknown ID collapses to an empty member set.
+
+## Parameters
+
+| Name | Type | Description |
+|---|---|---|
+| `policyId` | `uint64` | Policy to query. |
+| `account` | `address` | Account to check. |
+
+## Returns
+
+| Type | Description |
+|---|---|
+| `bool` | `true` if `account` is authorized under `policyId`, `false` otherwise. |
 
 ## Access Control
 
-Read-only or ERC-20-standard access rules unless the NatSpec states otherwise.
+Always callable. This function is never gated by the `ActivationRegistry`, regardless of whether the PolicyRegistry feature is active.
 
 ## Policy Interaction
 
-This is part of the singleton PolicyRegistry surface used by B20 policy scopes.
+Part of the singleton `PolicyRegistry` surface used by B20 policy scopes. For composite policies (`UNION`/`INTERSECT`), this function reads current child-policy membership on every call, so updating a child's membership immediately affects what the composite authorizes.
 
 ## Example
 

docs/specifications/b20/reference/interfaces/i-policy-registry/max-composite-child-policies.mdx

@@ -23,7 +23,7 @@ Return: Maximum permitted child-policy count.
 
 ## Access Control
 
-Read-only or ERC-20-standard access rules unless the NatSpec states otherwise.
+Read-only. Always callable regardless of activation state.
 
 ## Policy Interaction
 

docs/specifications/b20/reference/interfaces/i-policy-registry/pending-policy-admin.mdx

@@ -21,16 +21,22 @@ function pendingPolicyAdmin(uint64 policyId) external view returns (address);
 Returns the currently-staged pending admin for `policyId`, or `address(0)` when
 no transfer is in flight or for built-in sentinels, unknown IDs, and malformed IDs.
 Never reverts.
-Param: policyId Policy to query.
-Return: Pending admin, or `address(0)`.
 
-## Access Control
+**Parameters**
+
+| Name | Type | Description |
+|---|---|---|
+| `policyId` | `uint64` | Policy to query. |
 
-Read-only or ERC-20-standard access rules unless the NatSpec states otherwise.
+**Returns**
 
-## Policy Interaction
+| Type | Description |
+|---|---|
+| `address` | Pending admin, or `address(0)` if no transfer is in flight. |
+
+## Access Control
 
-This is part of the singleton PolicyRegistry surface used by B20 policy scopes.
+Read-only. Always callable regardless of whether the PolicyRegistry feature is active.
 
 ## Example
 

docs/specifications/b20/reference/interfaces/i-policy-registry/policy-admin.mdx

@@ -1,10 +1,8 @@
 ---
 title: "IPolicyRegistry.policyAdmin"
-description: "Generated B20 reference for policyAdmin(uint64)."
+description: "Returns the current admin of a policy in the PolicyRegistry."
 ---
 
-
-
 ## Signature
 
 ```solidity IPolicyRegistry.sol
@@ -18,21 +16,26 @@ function policyAdmin(uint64 policyId) external view returns (address);
 
 ## Description
 
-Returns the current admin of `policyId`, or `address(0)` for built-in sentinels,
-renounced policies, unknown IDs, and malformed IDs. Never reverts.
-Param: policyId Policy to query.
-Return: Current admin, or `address(0)`.
+Returns the current admin of `policyId`. Returns `address(0)` for built-in sentinels (`ALWAYS_ALLOW`, `ALWAYS_BLOCK`), renounced policies, unknown IDs, and malformed IDs. Never reverts.
 
-## Access Control
+## Parameters
+
+| Name | Type | Description |
+|---|---|---|
+| `policyId` | `uint64` | The policy to query. |
 
-Read-only or ERC-20-standard access rules unless the NatSpec states otherwise.
+## Returns
 
-## Policy Interaction
+| Type | Description |
+|---|---|
+| `address` | Current admin, or `address(0)` if none. |
+
+## Access Control
 
-This is part of the singleton PolicyRegistry surface used by B20 policy scopes.
+Always callable. This read-only function is not gated by the ActivationRegistry.
 
 ## Example
 
 ```solidity Usage Example
-IPolicyRegistry(target).policyAdmin(arg0);
+address admin = IPolicyRegistry(target).policyAdmin(policyId);
 ```