@hyperscale0/hsx 2.1.1 → 2.2.1

package/docs/llms-full.txt

@@ -1,4 +1,4 @@
-<!-- Generated by scripts/docs/build.ts for HSX 2.1.1. Do not edit. -->
+<!-- Generated by scripts/docs/build.ts for HSX 2.2.1. Do not edit. -->
 
 # HSX full documentation
 
@@ -25,7 +25,7 @@ settlement tip = instant_transfer {
 
 A port declares a decision that an external caller may supply. The port names the parties allowed to answer and may define a typed input shape. Use a port only when the selected instrument accepts a condition parameter.
 
-After package installation, run `npx @hyperscale0/hsx check product.hsx` while editing and `npx @hyperscale0/hsx build product.hsx --out product.udl.json` when the program passes. In a repository checkout, run `bun install` once, then use `bun run bin/hsx.ts check product.hsx` and `bun run bin/hsx.ts build product.hsx --out product.udl.json`.
+After package installation, run `npx @hyperscale0/hsx check product.hsx` while editing and `npx @hyperscale0/hsx build product.hsx --out product.udl.json` when the program passes. In the full repository checkout, run `bun install` once from the repository root, then use `bun open/hsx/bin/hsx.ts check product.hsx` and `bun open/hsx/bin/hsx.ts build product.hsx --out product.udl.json`. In the standalone HSX package checkout, the entrypoint is `bin/hsx.ts`.
 
 # Money
 
@@ -82,11 +82,24 @@ When declaring fields of type `account<C>`, the HSX compiler automatically lower
 
 ```hsx
 fields {
-  customerAccountId: account<SAR>;
+  customerAccountId {
+    type: account<SAR>;
+    "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; };
+  }
   amount: money<SAR>;
 }
 ```
 
+The account type pins the currency and identifier shape. The reference filter
+pins the allowed ledger roles. Product admission requires every account field
+to declare a non-empty role list. Choose roles that match the accounts the
+program will use; `customer_balance` is the role in this example.
+
+Use the quoted `"x-hyperscale-reference-filter"` key inside the field block,
+with `column: role` and `values: [...]`. There is no shorter role annotation.
+A bare `customerAccountId: account<SAR>;` compiles as HSX but does not satisfy
+the host's account-role admission law.
+
 ## Port declarations and action clauses
 
 HSX supports two distinct port syntaxes depending on scope:
@@ -223,10 +236,14 @@ settlement plan = scheduled {
 }
 ```
 
-`scheduled` handles finite installments and obligation schedules. `recurring_collection` records collection periods without inventing money movement. `rotating_pool` expands a fixed roster and cycle count. `settlement_batch` closes on a stored date before calculation, approval, instruction, acknowledgement, and reconciliation actions.
+`scheduled` handles finite installments and obligation schedules. `rotating_pool` expands a fixed roster and cycle count. `settlement_batch` closes on a stored date before calculation, approval, instruction, acknowledgement, and reconciliation actions.
 
 General modules may use a comprehension over a compile-time integer or finite list. Runtime-dependent bounds are refused. An expansion may contain at most 256 generated rows.
 
+Finite obligation counts expand the same lifecycle for each slice. A lifecycle source may be a finite list; `without(states, state)` removes one state before expansion. This preserves rejection of a repeated delinquency marker for its current slice.
+
+Use `advance` with `dated: true` when each repayment has a signed date. `repayment_source` separates the borrower from the capital recipient; `profit_to` sends computed profit to a separate account. The caller partitions the principal and profit across stored repayments. These partitions do not enforce equal slices or ordered dates.
+
 # Composition
 
 One program can apply several instruments. Each instrument keeps its own lifecycle and fields. References connect them through typed ids instead of shared mutable state.
@@ -318,6 +335,54 @@ Imported exports carry the local declarations they reference. Identical declarat
 
 Publish a module only after compiling it directly and through an importing program. Compare the canonical UDL bytes from both paths when the exported application should be identical.
 
+## An authored action that moves money
+
+Declare each cash movement in `moves` with a unique `key`, an `operation`, and `bind` operands. This complete program comes from [payment.hsx](../../examples/05-authored-instrument/payment.hsx). The docs builder requires the snippet to match that file and compiles it with the packaged cost table.
+
+```hsx source=examples/05-authored-instrument/payment.hsx
+program authored_payment "Authored payment"
+
+instrument payment {
+  agent_description: "Collect a stored payment once from its payer."
+  title: "Payment"
+  summary: "A payment with fixed payer and payee accounts"
+  fields {
+    payerAccountId: account<SAR>;
+    payeeAccountId: account<SAR>;
+    amount: money<SAR>;
+  }
+  parties { payer: payerAccountId; beneficiary: payeeAccountId; }
+  lifecycle {
+    states pending paid;
+    initial pending;
+    on pay: pending -> paid;
+  }
+  action create {
+    agent_description: "Open a pending payment without moving money."
+    steps: [];
+    moves: [];
+  }
+  action pay {
+    agent_description: "Move the stored amount from payer to payee."
+    steps: [];
+    moves: [{
+      bind: {
+        amount: { from: "instance", path: "fields.amount" }
+        currency: { from: "const", value: "SAR" }
+        sourceAccountId: { from: "instance", path: "fields.payerAccountId" }
+        destinationAccountId: { from: "instance", path: "fields.payeeAccountId" }
+      }
+      key: "payment_transfer"
+      operation: "internal_transfer.create"
+    }];
+  }
+}
+```
+
+`from: "instance"` reads an immutable stored field. `from: "const"` supplies the literal currency. The four bindings supply the transfer's amount, currency, source account and destination account. `internal_transfer.create` names the transfer operation; `payment_transfer` identifies this move within the action. Account IDs come from account creation or discovery before creating the payment. They are never invented by the program.
+
+`create` opens a pending record without cash movement. `pay` moves the stored amount and transitions to `paid`; the lifecycle refuses a second payment under a new action request. The compiler emits these bindings into UDL. Execution still requires an engine that admits the operation and accounts.
+
 # Cost
 
 Compilation emits a deterministic cost manifest beside the UDL document. The manifest pins the cost-table version and effective digest. It records fixed structural cost, action effect rows, payer, settlement policy, meters, per-event prices, and any basis-point volume price.
@@ -374,12 +439,12 @@ Exit code `0` means the command accepted the program. Exit code `1` means compil
 # CLI
 
 ```text
-hsx 2.1.1, the HSX compiler
+hsx 2.2.1, the HSX compiler
 
 Usage:
-  hsx check <file.hsx> [--strict]
-  hsx build <file.hsx> [--out <file.json>] [--strict]
-  hsx cost <file.hsx> [--json] [--out <file.json>] [--strict]
+  hsx check <file.hsx> [--catalog <catalog.udl>] [--strict]
+  hsx build <file.hsx> [--catalog <catalog.udl>] [--out <file.json>] [--strict]
+  hsx cost <file.hsx> [--catalog <catalog.udl>] [--json] [--out <file.json>] [--strict]
   hsx explain <HSX####>
   hsx format <file.hsx>
   hsx lsp
@@ -395,6 +460,7 @@ Commands:
   lsp     Run the language server over stdin and stdout.
 
 Options:
+  --catalog <file>  Read the published instrument catalogue as canonical UDL JSON.
   --json        Print the cost manifest as JSON instead of a table.
   --out <file>  Write build or cost JSON to this path instead of stdout.
   --strict      Treat warning-severity diagnostics as failures.
@@ -444,7 +510,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 program second "Second"
 ```
@@ -475,7 +541,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 instrument probe { fields {}; lifecycle { states created; initial created; }; action create { steps: []; }; }
 ```
@@ -527,7 +593,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 subject vehicle { title: "Vehicle"; }
 ```
@@ -745,7 +811,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 const fee: money<SAR> = USD 1.00
 ```
@@ -766,7 +832,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 const fee: money<SAR> = SAR 1.001
 ```
@@ -886,7 +952,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 ```
 
@@ -922,7 +988,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 ```
 
@@ -942,7 +1008,7 @@ instrument probe {
     agent_description: "Create a probe instance.";
     steps: [];
   }
-
+  
 }
 ```
 
@@ -1299,7 +1365,7 @@ The parser is hand-written. This page records the exported lexer vocabulary, the
 
 ## Typed clause spellings
 
-`action library`, `agent description`, `calls`, `capture input`, `commit`, `quote`, `decided amount`, `deadline`, `decision`, `computes distribute`, `description`, `due`, `earnable`, `event name`, `examples`, `input`, `moves`, `payout`, `piece plan`, `piece stage`, `port`, `principal`, `public action`, `reconcile`, `computes remainder`, `requires aggregate`, `requires checks`, `requires drained`, `requires exposure`, `requires refs`, `sandbox failure point`, `sets at`, `computes signed_sum`, `steps`, `summary`, `updates`, `notify`, `agent description`, `aggregate invariants`, `caller parked states`, `description`, `dials`, `distinct parties`, `computes derived`, `computes fees`, `id prefix`, `journeys`, `nav`, `partitions`, `subject`, `summary`, `surface visibility`, `template id`, `title`, `update`
+`funding`, `receipt distribution`, `requires allocation`, `allocation`, `contributions`, `allocate`, `contribution stage`, `date order`, `unique`, `transitions refs`, `action library`, `agent description`, `calls`, `requires input`, `engine owned`, `capture engine`, `capture input`, `commit`, `quote`, `decided amount`, `deadline`, `decision`, `computes distribute`, `description`, `due`, `earnable`, `event name`, `examples`, `input`, `moves`, `payout`, `piece plan`, `piece stage`, `port`, `principal`, `public action`, `reconcile`, `computes remainder`, `requires aggregate`, `requires checks`, `requires drained`, `requires exposure`, `requires refs`, `sandbox failure point`, `sets at`, `computes signed_sum`, `steps`, `summary`, `updates`, `notify`, `agent description`, `aggregate invariants`, `caller parked states`, `description`, `dials`, `distinct parties`, `computes derived`, `computes fees`, `id prefix`, `nav`, `partitions`, `subject`, `summary`, `surface visibility`, `template binding`, `template id`, `title`, `update`, `request authority`
 
 ## Standard-library modules
 
@@ -1314,7 +1380,6 @@ The parser is hand-written. This page records the exported lexer vocabulary, the
 - `pooled_split`
 - `premium_forward`
 - `reconciled_payout`
-- `recurring_collection`
 - `rotating_pool`
 - `scheduled`
 - `security_deposit`
@@ -1333,14 +1398,91 @@ Source: [`std/money_flows/advance.hsx`](../../../std/money_flows/advance.hsx)
 
 ## Parameters
 
-- `funder: party`
-- `to: party`
-- `amount: money<C>`
-- `fee: optional<percent>`
-- `count: optional<integer>`
-- `every: optional<text>`
-- `first_due: optional<date>`
-- `against: optional<ref>`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `funder` | `party` | Yes | The party providing the upfront capital. |
+| `to` | `party` | Yes | The party receiving the advance and responsible for repayment. |
+| `amount` | `money<C>` | Yes | Total advanced principal in minor units of currency `C`. |
+| `fee` | `optional<percent>` | No | Optional markup percentage fee charged on the advance (basis points precision). |
+| `count` | `optional<integer>` | No | Optional number of scheduled installment repayments. |
+| `every` | `optional<text>` | No | Optional recurrence duration between installments (e.g. `"P30D"`). |
+| `first_due` | `optional<date>` | No | Optional date for the first installment repayment. |
+| `against` | `optional<ref>` | No | Optional reference to a hold instrument whose release will be carved to repay the advance. |
+| `repayment_source` | `optional<party>` | No | Optional party repaying when distinct from the capital recipient. |
+| `profit_to` | `optional<party>` | No | Optional recipient of profit, separated from principal repayments. |
+| `dated` | `optional<boolean>` | No | Require an explicit signed date for each repayment instead of duration offsets. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Upfront capital disbursement repaid by carving future held payment releases or over scheduled installments.
+
+### Purpose
+
+`advance` provides working capital, merchant cash advances, or contractor pre-funding from a funder to a recipient.
+Repayment occurs either automatically by intercepting (carving) releases from a linked escrow hold (`against`),
+or over calendar-anchored installment repayments (`count`, `every`, `first_due`).
+
+### Selection guidance
+
+- vs `credit_facility`: `advance` disburses a single upfront lump-sum principal that is repaid over time.
+  `credit_facility` establishes a reusable revolving credit line with multiple draws up to a limit,
+  where repayments restore available borrowing capacity.
+- vs `conditional_disbursement`: `advance` expects repayment of the advanced principal plus optional fees.
+  `conditional_disbursement` disburses non-repayable grants, claims, or milestone payments against external evidence.
+- vs `held_payment`: `held_payment` holds customer funds in escrow until delivery. An `advance` can carve repayments
+  directly out of a `held_payment`'s release using `against`.
+
+### Parameters
+
+- `funder`: The party providing the upfront capital.
+- `to`: The party receiving the advance and responsible for repayment.
+- `amount`: Total advanced principal in minor units of currency `C`.
+- `fee`: Optional markup percentage fee charged on the advance (basis points precision).
+- `count`: Optional number of scheduled installment repayments.
+- `every`: Optional recurrence duration between installments (e.g. `"P30D"`).
+- `first_due`: Optional date for the first installment repayment.
+- `repayment_source`: Optional party repaying when distinct from the capital recipient.
+- `profit_to`: Optional recipient of profit, separated from principal repayments.
+- `dated`: Require an explicit signed date for each repayment instead of duration offsets.
+- `against`: Optional reference to a hold instrument whose release will be carved to repay the advance.
+
+### Decision ports
+
+None. Repayment is driven by linked hold releases or scheduled calendar dates.
+
+### Example
+
+```hsx
+program advance_example "Advance example"
+import { advance } from "std/money_flows"
+party funder: business
+party recipient: business
+settlement advance_payment = advance {
+  funder: funder
+  to: recipient
+  amount: principal: money(SAR)
+  fee: 2.5%
+  count: 2
+  every: P30D
+  first_due: firstDueAt
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `description`
+- `due`
+- `id prefix`
+- `moves`
+- `partitions`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1348,14 +1490,14 @@ None.
 
 ## Actions and clauses
 
-| Action                | Clauses lowered                                  |
-| --------------------- | ------------------------------------------------ |
-| `create`              | `agent description`, `moves`, `steps`, `summary` |
-| `disburse`            | `agent description`, `moves`, `steps`, `summary` |
-| `settle`              | `agent description`, `moves`, `steps`, `summary` |
-| `create`              | `agent description`, `moves`, `steps`, `summary` |
-| `disburse`            | `agent description`, `moves`, `steps`, `summary` |
-| `collect_repayment_1` | `due`, `moves`, `steps`, `summary`               |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `disburse` | `agent description`, `moves`, `steps`, `summary` |
+| `settle` | `agent description`, `moves`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `disburse` | `agent description`, `moves`, `steps`, `summary` |
+| `collect_repayment_[i]` | `agent description`, `due`, `moves`, `steps`, `summary` |
 
 # cancellable_booking
 
@@ -1367,14 +1509,124 @@ Source: [`std/money_flows/cancellable_booking.hsx`](../../../std/money_flows/can
 
 ## Parameters
 
-- `guest: party`
-- `host: party`
-- `amount: money<C>`
-- `starts_at: date`
-- `late_penalty_bps: integer`
-- `late_within: text`
-- `early_penalty_bps: integer`
-- `offer_life: text`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `guest` | `optional<party>` | No | The booking customer paying the fee and receiving refunds. |
+| `host` | `optional<party>` | No | The service provider receiving the payout or retained cancellation penalty. |
+| `amount` | `optional<money<C>>` | No | Total booking price in minor units of currency `C`. |
+| `starts_at` | `optional<date>` | No | Stored ISO 8601 date when the booking begins. |
+| `late_penalty_bps` | `optional<integer>` | No | Penalty in basis points applied when cancelling within the late window. |
+| `late_within` | `optional<text>` | No | ISO 8601 duration defining the late window before `starts_at` (e.g. `"P2D"` for 2 days). |
+| `early_penalty_bps` | `optional<integer>` | No | Penalty in basis points applied when cancelling before the late window. |
+| `offer_life` | `optional<text>` | No | ISO 8601 duration defining how long a quoted cancellation offer remains valid (e.g. `"PT30M"`). |
+| `cancel_bands` | `optional<list<block>>` | No | Supply cancel_bands to select deposit/balance custody instead of quoted cancellation. |
+| `price_value` | `optional<text>` | No | price_value and supplier_cost fix the price; deposit_bps derives the deposit. |
+| `supplier_cost` | `optional<text>` | No | price_value and supplier_cost fix the price; deposit_bps derives the deposit. |
+| `departure` | `optional<text>` | No | balance_before and confirmation_window are positive fixed durations relative to departure. |
+| `balance_before` | `optional<text>` | No | balance_before and confirmation_window are positive fixed durations relative to departure. |
+| `confirmation_window` | `optional<text>` | No | balance_before and confirmation_window are positive fixed durations relative to departure. |
+| `unpaid_band` | `optional<integer>` | No | The unpaid_band index selects a retained deposit policy. |
+| `acceptance` | `optional<block>` | No | acceptance optionally supplies an aggregate gate. |
+| `deposit_bps` | `optional<integer>` | No | price_value and supplier_cost fix the price; deposit_bps derives the deposit. |
+| `tax_bps` | `optional<integer>` | No | tax_bps applies to margin after the supplier share. |
+| `authority_type` | `optional<text>` | No | authority_type and supplier_role bind release to a consumed confirmation decision. |
+| `supplier_role` | `optional<text>` | No | authority_type and supplier_role bind release to a consumed confirmation decision. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Time-anchored reservation holding booking funds in escrow with dynamically quoted cancellation penalties.
+
+### Purpose
+
+`cancellable_booking` holds booking fees in escrow from a guest for a host until a scheduled start date.
+It fits hospitality, travel reservations, studio rentals, event tickets, and appointments where guests
+can cancel prior to start, but cancellation penalties depend on how close to the start date cancellation occurs.
+
+### Selection guidance
+
+- vs `held_payment`: Both hold money in escrow and both quote a cancellation before it is spent.
+  `cancellable_booking` prices the penalty against the time left before `starts_at`, so the charge moves
+  as the start approaches; `held_payment` has no start date and quotes one flat charge.
+  Choose `cancellable_booking` whenever cancellation fees are time-sensitive.
+- vs `security_deposit`: `security_deposit` holds funds to cover damages claimed by the holder.
+  `cancellable_booking` holds the service fee itself and releases to the host upon `starts_at` or refunds net of penalty.
+
+### Parameters
+
+- `guest`: The booking customer paying the fee and receiving refunds.
+- `host`: The service provider receiving the payout or retained cancellation penalty.
+- `amount`: Total booking price in minor units of currency `C`.
+- `starts_at`: Stored ISO 8601 date when the booking begins.
+- `late_penalty_bps`: Penalty in basis points applied when cancelling within the late window.
+- `late_within`: ISO 8601 duration defining the late window before `starts_at` (e.g. `"P2D"` for 2 days).
+- `early_penalty_bps`: Penalty in basis points applied when cancelling before the late window.
+- `offer_life`: ISO 8601 duration defining how long a quoted cancellation offer remains valid (e.g. `"PT30M"`).
+
+### Decision ports
+
+None. Action transitions are driven by guest API calls (`take`, `cancel`, `confirm`) and scheduled completion (`complete` due at `starts_at`).
+
+### Example
+
+```hsx
+program studio_booking "Studio booking"
+import { cancellable_booking } from "std/money_flows"
+party guest: person
+party studio: business
+settlement studio_session = cancellable_booking {
+  guest: guest
+  host: studio
+  amount: sessionPrice: money(SAR)
+  starts_at: startsAt
+  late_penalty_bps: 5000
+  late_within: "P2D"
+  early_penalty_bps: 1000
+  offer_life: "PT30M"
+}
+```
+
+### Finite cancellation bands
+
+Supply cancel_bands to select deposit/balance custody instead of quoted cancellation.
+Each band has name, refund (full, balance or none), starts_at after the first band,
+and supplier_bps when money is retained. The unpaid_band index selects a retained
+deposit policy. Omit it to return the deposit; a full-refund band also returns it. price_value and supplier_cost fix the price; deposit_bps derives
+the deposit. balance_before and confirmation_window are positive fixed durations
+relative to departure. tax_bps applies to margin after the supplier share.
+authority_type and supplier_role bind release to a consumed confirmation decision.
+acceptance optionally supplies an aggregate gate. All actions are private until
+expose selects them. Ordered band starts and deadlines prevent a late sweep from
+extending an earlier band's cancellation rights. Full timeout refund returns price.
+Seven derivations suffice for three bands; larger finite policies use up to the
+UDL bound of 64 derived amounts. shift_date(date, duration, "before") subtracts a
+fixed duration; omitting the direction adds it. Invalid dates or durations refuse.
+
+## Declared clauses
+
+- `agent description`
+- `caller parked states`
+- `commit`
+- `deadline`
+- `description`
+- `distinct parties`
+- `due`
+- `id prefix`
+- `input`
+- `moves`
+- `partitions`
+- `port`
+- `quote`
+- `requires drained`
+- `sandbox failure point`
+- `steps`
+- `summary`
+- `title`
+- `unique`
+- `updates`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1382,14 +1634,25 @@ None.
 
 ## Actions and clauses
 
-| Action     | Clauses lowered                                                           |
-| ---------- | ------------------------------------------------------------------------- |
-| `create`   | `agent description`, `moves`, `steps`, `summary`                          |
-| `take`     | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `complete` | `due`, `moves`, `steps`, `summary`                                        |
-| `cancel`   | `agent description`, `moves`, `quote`, `steps`, `summary`                 |
-| `confirm`  | `agent description`, `commit`, `moves`, `steps`, `summary`                |
-| `retain`   | `agent description`, `moves`, `steps`, `summary`                          |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `take` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `complete` | `due`, `moves`, `steps`, `summary` |
+| `cancel` | `agent description`, `moves`, `quote`, `steps`, `summary` |
+| `confirm` | `agent description`, `commit`, `moves`, `steps`, `summary` |
+| `retain` | `agent description`, `moves`, `steps`, `summary` |
+| `create` | `agent description`, `deadline`, `steps`, `unique` |
+| `deposit` | `agent description`, `deadline`, `moves`, `port`, `steps` |
+| `expire` | `agent description`, `due`, `requires drained`, `steps` |
+| `[balance_action]` | `agent description`, `deadline`, `moves`, `port`, `steps` |
+| `[open_action]` | `agent description`, `due`, `steps` |
+| `[cancel_action]` | `agent description`, `deadline`, `moves`, `port`, `steps` |
+| `cancel_unpaid` | `agent description`, `due`, `moves`, `steps` |
+| `await_confirmation` | `agent description`, `due`, `steps` |
+| `confirm` | `agent description`, `deadline`, `input`, `steps`, `updates` |
+| `release` | `agent description`, `moves`, `steps` |
+| `refund_unconfirmed` | `agent description`, `due`, `moves`, `steps` |
 
 # captured_payment
 
@@ -1401,17 +1664,89 @@ Source: [`std/money_flows/captured_payment.hsx`](../../../std/money_flows/captur
 
 ## Parameters
 
-- `payer: party`
-- `payee: party`
-- `amount: money<C>`
-- `reserve_until: date`
-- `correction: condition`
-- `external_reversal: condition`
-- `capture_mode: text`
-- `correction_mode: text`
-- `negative_position: text`
-- `timeout: text`
-- `derived_amount: optional<block>`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `payer` | `party` | Yes | Party whose account balance is reserved during authorization. |
+| `payee` | `party` | Yes | Beneficiary party capturing authorized funds. |
+| `amount` | `money<C>` | Yes | Maximum authorized reservation in minor units of currency `C`. |
+| `reserve_until` | `date` | Yes | Expiration date for the authorization hold. |
+| `correction` | `condition` | Yes | Condition port allowing post-settlement amount corrections. |
+| `external_reversal` | `condition` | Yes | Condition port allowing external processor chargebacks/reversals. |
+| `derived_amount` | `optional<block>` | No | Optional block declaring percentage fee calculation. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Two-phase authorization and capture payment flow for card and merchant processing.
+
+### Purpose
+
+`captured_payment` reserves funds against a payer's account and allows the payee to capture the authorized
+balance in one or multiple slices before a reservation expiry date (`reserve_until`). It fits ecommerce checkouts,
+card processing, hotel authorizations, and pay-at-pump fuel payments where final amounts vary or settle later.
+
+### Selection guidance
+
+- vs `instant_transfer`: `instant_transfer` immediately transfers money from payer to payee in a single irreversible
+  step without reservation or settlement delays. `captured_payment` separates authorization from capture, allowing
+  incremental captures, voids, amount corrections via the `correction` port, and external network reversals via `external_reversal`.
+- vs `held_payment`: `held_payment` holds the full amount in third-party escrow pending release. `captured_payment`
+  reserves funds directly on payer balance and settles incrementally directly to payee.
+
+### Parameters
+
+- `payer`: Party whose account balance is reserved during authorization.
+- `payee`: Beneficiary party capturing authorized funds.
+- `amount`: Maximum authorized reservation in minor units of currency `C`.
+- `reserve_until`: Expiration date for the authorization hold.
+- `correction`: Condition port allowing post-settlement amount corrections.
+- `external_reversal`: Condition port allowing external processor chargebacks/reversals.
+- `derived_amount`: Optional block declaring percentage fee calculation.
+
+### Decision ports
+
+- `correction`: Condition allowing payee or processor to submit an amount correction after settlement.
+- `external_reversal`: Condition allowing bank or card network to execute an external reversal.
+
+### Example
+
+```hsx
+program captured_payment_example "Captured payment example"
+import { captured_payment } from "std/money_flows"
+party payer: person
+party payee: business
+settlement card_payment = captured_payment {
+  payer: payer
+  payee: payee
+  amount: authorizedAmount: money(SAR)
+  reserve_until: reserveUntil
+  correction: port correct_capture
+  external_reversal: port reverse_capture within P14D
+}
+port correct_capture { allowed: [payee] }
+port reverse_capture {
+  allowed: [payee]
+  shape: { externalReference: text }
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `capture input`
+- `deadline`
+- `description`
+- `due`
+- `input`
+- `moves`
+- `port`
+- `sandbox failure point`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1420,18 +1755,18 @@ Source: [`std/money_flows/captured_payment.hsx`](../../../std/money_flows/captur
 
 ## Actions and clauses
 
-| Action             | Clauses lowered                                                                                               |
-| ------------------ | ------------------------------------------------------------------------------------------------------------- |
-| `create`           | `agent description`, `moves`, `steps`, `summary`                                                              |
-| `authorize`        | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                                     |
-| `capture`          | `agent description`, `deadline`, `description`, `input`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `capture_more`     | `agent description`, `deadline`, `description`, `input`, `moves`, `steps`, `summary`                          |
-| `settle`           | `agent description`, `deadline`, `moves`, `steps`, `summary`                                                  |
-| `void`             | `agent description`, `moves`, `steps`, `summary`                                                              |
-| `expire`           | `due`, `moves`, `steps`, `summary`                                                                            |
-| `settle_on_expiry` | `due`, `moves`, `steps`, `summary`                                                                            |
-| `correction_name`  | `agent description`, `capture input`, `input`, `moves`, `port`, `steps`, `summary`                            |
-| `reversal_name`    | `agent description`, `capture input`, `deadline`, `input`, `moves`, `port`, `steps`, `summary`                |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `authorize` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `capture` | `agent description`, `deadline`, `description`, `input`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `capture_more` | `agent description`, `deadline`, `description`, `input`, `moves`, `steps`, `summary` |
+| `settle` | `agent description`, `deadline`, `moves`, `steps`, `summary` |
+| `void` | `agent description`, `moves`, `steps`, `summary` |
+| `expire` | `due`, `moves`, `steps`, `summary` |
+| `settle_on_expiry` | `due`, `moves`, `steps`, `summary` |
+| `[correction_name]` | `agent description`, `capture input`, `input`, `moves`, `port`, `steps`, `summary` |
+| `[reversal_name]` | `agent description`, `capture input`, `deadline`, `input`, `moves`, `port`, `steps`, `summary` |
 
 # conditional_disbursement
 
@@ -1443,13 +1778,81 @@ Source: [`std/money_flows/conditional_disbursement.hsx`](../../../std/money_flow
 
 ## Parameters
 
-- `source: party`
-- `destination: party`
-- `cap: money<C>`
-- `amount: money<C>`
-- `decision: condition`
-- `reopen_policy: text`
-- `recovery_policy: text`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `source` | `party` | Yes | The funding party providing the money. |
+| `destination` | `party` | Yes | The beneficiary party receiving approved disbursements. |
+| `cap` | `money<C>` | Yes | Maximum total amount that can be disbursed across all child approvals in minor units of currency `C`. |
+| `amount` | `money<C>` | Yes | Binding name for child approval amount values. |
+| `decision` | `condition` | Yes | Port conditioning approval, requiring evidence reference. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Capped disbursement from a source party to a destination party gated on stored external decision evidence.
+
+### Purpose
+
+`conditional_disbursement` manages evidence-contingent payouts subject to a cumulative cap.
+It fits insurance claim settlements, grant tranches, subsidy distributions, and escrow milestones
+where each approved payment requires explicit external evidence and the total paid must not exceed `cap`.
+
+### Selection guidance
+
+- vs `advance`: `conditional_disbursement` disburses non-repayable funds against external evidence
+  up to a declared cap. `advance` pays money up front with the expectation of repayment through carved
+  hold releases or scheduled installments.
+- vs `instant_transfer`: `instant_transfer` moves money immediately with no evidence gate or cap.
+  `conditional_disbursement` requires an external decision port and evidence reference before any child amount moves.
+
+### Parameters
+
+- `source`: The funding party providing the money.
+- `destination`: The beneficiary party receiving approved disbursements.
+- `cap`: Maximum total amount that can be disbursed across all child approvals in minor units of currency `C`.
+- `amount`: Binding name for child approval amount values.
+- `decision`: Port conditioning approval, requiring evidence reference.
+
+### Decision ports
+
+- `decision`: External port providing decision evidence required to approve child disbursement amounts.
+
+### Example
+
+```hsx
+program conditional_disbursement_example "Conditional disbursement example"
+import { conditional_disbursement } from "std/money_flows"
+party source: business
+party claimant: person
+settlement claim_payment = conditional_disbursement {
+  source: source
+  destination: claimant
+  cap: policyLimit: money(SAR)
+  amount: approvedAmount: money(SAR)
+  decision: port approve_claim
+}
+port approve_claim {
+  allowed: [source]
+  shape: { evidenceReference: text }
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `capture input`
+- `description`
+- `id prefix`
+- `input`
+- `moves`
+- `port`
+- `steps`
+- `summary`
+- `title`
+- `unique`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1457,13 +1860,13 @@ Source: [`std/money_flows/conditional_disbursement.hsx`](../../../std/money_flow
 
 ## Actions and clauses
 
-| Action    | Clauses lowered                                                                                   |
-| --------- | ------------------------------------------------------------------------------------------------- |
-| `create`  | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `deny`    | `agent description`, `capture input`, `input`, `moves`, `port`, `steps`, `summary`                |
-| `create`  | `agent description`, `moves`, `steps`, `summary`                                                  |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `deny` | `agent description`, `capture input`, `input`, `moves`, `port`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `steps`, `summary`, `unique` |
 | `approve` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
-| `pay`     | `agent description`, `moves`, `steps`, `summary`                                                  |
+| `pay` | `agent description`, `moves`, `steps`, `summary` |
 
 # credit_facility
 
@@ -1475,15 +1878,88 @@ Source: [`std/money_flows/credit_facility.hsx`](../../../std/money_flows/credit_
 
 ## Parameters
 
-- `lender: party`
-- `borrower: party`
-- `draw_destination: party`
-- `limit: money<C>`
-- `expires_at: date`
-- `obligation: ref`
-- `availability_policy: text`
-- `expiry_policy: text`
-- `close_policy: text`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `lender` | `party` | Yes | The financing institution or party providing the credit capacity. |
+| `borrower` | `party` | Yes | The borrowing party authorized to draw against the facility limit. |
+| `draw_destination` | `party` | Yes | Account or party receiving disbursed draw proceeds. |
+| `limit` | `money<C>` | Yes | Total revolving borrowing limit in minor units of currency `C`. |
+| `expires_at` | `date` | Yes | Expiration date after which new draws cannot be opened. |
+| `obligation` | `ref` | Yes | Reference to a scheduled obligation instrument handling draw repayments. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Revolving credit line providing reusable borrowing capacity up to a limit backed by scheduled obligations.
+
+### Purpose
+
+`credit_facility` manages revolving commercial credit, inventory financing, and overdraft facilities.
+A borrower can draw funds multiple times up to `limit` into `draw_destination`. Each draw creates a child
+record linked to a scheduled `obligation`. Repayments restore available borrowing capacity until `expires_at`.
+
+### Selection guidance
+
+- vs `advance`: `credit_facility` provides revolving, reusable credit lines where multiple draws can occur
+  and repayments restore capacity. `advance` is a single upfront lump-sum disbursement with a fixed repayment plan.
+- vs `scheduled`: `scheduled` defines repayment installments or recurring transfers. `credit_facility` delegates
+  draw repayments to a `scheduled` obligation while tracking total facility utilization and limit compliance.
+
+### Parameters
+
+- `lender`: The financing institution or party providing the credit capacity.
+- `borrower`: The borrowing party authorized to draw against the facility limit.
+- `draw_destination`: Account or party receiving disbursed draw proceeds.
+- `limit`: Total revolving borrowing limit in minor units of currency `C`.
+- `expires_at`: Expiration date after which new draws cannot be opened.
+- `obligation`: Reference to a scheduled obligation instrument handling draw repayments.
+
+### Decision ports
+
+None on the facility itself. Mandates and decision ports are declared on the linked `obligation` instrument.
+
+### Example
+
+```hsx
+program credit_facility_example "Credit facility example"
+import { credit_facility, scheduled } from "std/money_flows"
+party lender: business
+party borrower: business
+party draw_destination: business
+party repayment_source: business
+settlement repayment = scheduled {
+  mode: obligation
+  payer: repayment_source
+  payee: lender
+  debtor: borrower
+  amount: principal: money(SAR)
+  count: 2
+  every: P30D
+  first_due: firstDueAt
+}
+settlement facility = credit_facility {
+  lender: lender
+  borrower: borrower
+  draw_destination: draw_destination
+  limit: facilityLimit: money(SAR)
+  expires_at: expiresAt
+  obligation: repayment.obligation
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `description`
+- `due`
+- `id prefix`
+- `moves`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1491,12 +1967,12 @@ None.
 
 ## Actions and clauses
 
-| Action    | Clauses lowered                                  |
-| --------- | ------------------------------------------------ |
-| `create`  | `agent description`, `moves`, `steps`, `summary` |
-| `freeze`  | `due`, `moves`, `steps`, `summary`               |
-| `close`   | `agent description`, `moves`, `steps`, `summary` |
-| `create`  | `agent description`, `moves`, `steps`, `summary` |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `freeze` | `due`, `moves`, `steps`, `summary` |
+| `close` | `agent description`, `moves`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
 | `resolve` | `agent description`, `moves`, `steps`, `summary` |
 
 # held_payment
@@ -1509,22 +1985,122 @@ Source: [`std/money_flows/held_payment.hsx`](../../../std/money_flows/held_payme
 
 ## Parameters
 
-- `payer: party`
-- `payee: party`
-- `amount: money<C>`
-- `release: condition`
-- `fees: optional<block>`
-- `on_cancel: optional<block>`
-- `derived_amount: optional<block>`
-- `release_to: optional<party>`
-- `whole_amount: optional<block>`
-- `release_action: optional<text>`
-- `whole_fee: optional<money<C>>`
-- `reference: optional<text>`
-- `upstream: optional<ref>`
-- `id_prefix_override: optional<text>`
-- `cancel_charge_bps: optional<integer>`
-- `cancel_offer_life: optional<text>`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `payer` | `party` | Yes | The funding party providing the money. |
+| `payee` | `party` | Yes | The beneficiary party receiving the released funds. |
+| `amount` | `money<C>` | Yes | Total amount in minor units of currency `C`. |
+| `release` | `condition` | Yes | Condition required to release funds. Supports decision ports (`port <name>`), date deadlines (`at(<date>)`), or disjunctions (`port <name> &#124; at(<date>)`). |
+| `fees` | `optional<block>` | No | Optional block declaring percentage or fixed fee cuts, e.g. `{ buyer: 1%, seller: 2% }`. |
+| `on_cancel` | `optional<block>` | No | Optional block defining refund splits if cancelled while funded, e.g. `(funded) { buyer: 90%, seller: 10% }`. |
+| `derived_amount` | `optional<block>` | No | Optional block declaring machine-derived fees calculated as a percentage of another field. |
+| `release_to` | `optional<party>` | No | Optional third-party destination for release. |
+| `whole_amount` | `optional<block>` | No | Optional block enabling single-action funding and release of principal plus on-top fee. |
+| `release_action` | `optional<text>` | No | Optional custom name for the release action. |
+| `whole_fee` | `optional<money<C>>` | No | Optional money amount for the whole-amount fee. |
+| `reference` | `optional<text>` | No | Optional string reference stored on the instance. |
+| `upstream` | `optional<ref>` | No | Optional reference to a parent instrument. |
+| `id_prefix_override` | `optional<text>` | No | Optional custom prefix for generated instrument IDs. |
+| `cancel_charge_bps` | `optional<integer>` | No | Optional cancellation charge in basis points. Declaring it gives the settlement a quoted cancellation: `quote_cancellation` prices the charge and the refund and freezes both, `cancel` pays the refund to the payer, and `retain_cancellation_charge` pays the charge to the payee. A zero charge keeps the flow with a zero fee. |
+| `cancel_offer_life` | `optional<text>` | No | ISO 8601 duration a cancellation quote stays open, required with `cancel_charge_bps`. |
+| `private_actions` | `optional<boolean>` | No | Suppress automatic aliases. Publish chosen actions with `expose`. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Escrow settlement holding funds from a payer before releasing to a payee upon a verified condition or deadline.
+
+### Purpose
+
+`held_payment` holds customer funds in a dedicated product escrow account away from both payer and payee.
+It fits milestone-gated commerce, vehicle escrow, contractor holdbacks, and goods purchases where funds
+must remain reserved until delivery confirmation or inspection.
+
+### Selection guidance
+
+- vs `cancellable_booking`: Both hold funds in custody and both can quote a cancellation before it is
+  spent. `held_payment` quotes one flat charge declared by `cancel_charge_bps`, because it has no scheduled
+  start to price against, and `on_cancel` remains the way to unwind it on static splits instead.
+  Choose `cancellable_booking` when the charge must follow the time left before a scheduled start date.
+- vs `security_deposit`: `held_payment` releases or cancels the principal according to predefined splits.
+  Choose `security_deposit` when the holder must assess damages and claim an arbitrary partial amount
+  via a `decided amount` clause while returning the unspent remainder to the payer.
+- vs `swap`: `held_payment` is a one-way transfer from payer to payee. Choose `swap` for bilateral or
+  multi-party atomic exchanges where all parties must fund their legs into escrow before simultaneous release.
+- vs `premium_forward`: Choose `premium_forward` for insurance premium collection requiring carrier policy
+  binding conditions, broker commission retention, policy endorsements, and lapse schedules.
+
+### Parameters
+
+- `payer`: The funding party providing the money.
+- `payee`: The beneficiary party receiving the released funds.
+- `amount`: Total amount in minor units of currency `C`.
+- `release`: Condition required to release funds. Supports decision ports (`port <name>`), date deadlines
+  (`at(<date>)`), or disjunctions (`port <name> | at(<date>)`).
+- `fees`: Optional block declaring percentage or fixed fee cuts, e.g. `{ buyer: 1%, seller: 2% }`.
+- `on_cancel`: Optional block defining refund splits if cancelled while funded, e.g. `(funded) { buyer: 90%, seller: 10% }`.
+- `derived_amount`: Optional block declaring machine-derived fees calculated as a percentage of another field.
+- `release_to`: Optional third-party destination for release.
+- `whole_amount`: Optional block enabling single-action funding and release of principal plus on-top fee.
+- `release_action`: Optional custom name for the release action.
+- `whole_fee`: Optional money amount for the whole-amount fee.
+- `reference`: Optional string reference stored on the instance.
+- `upstream`: Optional reference to a parent instrument.
+- `id_prefix_override`: Optional custom prefix for generated instrument IDs.
+- `cancel_charge_bps`: Optional cancellation charge in basis points. Declaring it gives the settlement a
+  quoted cancellation: `quote_cancellation` prices the charge and the refund and freezes both,
+  `cancel` pays the refund to the payer, and `retain_cancellation_charge` pays the charge to the payee.
+  A zero charge keeps the flow with a zero fee.
+- `cancel_offer_life`: ISO 8601 duration a cancellation quote stays open, required with `cancel_charge_bps`.
+
+- `private_actions`: Suppress automatic aliases. Publish chosen actions with `expose`.
+
+### Decision ports
+
+- `release`: Port deciding release authorization, answered by allowed parties declared in the port.
+
+### Example
+
+```hsx
+program held_payment_example "Held payment example"
+import { held_payment } from "std/money_flows"
+party buyer: person
+party seller: business
+settlement sale = held_payment {
+  payer: buyer
+  payee: seller
+  amount: price: money(SAR)
+  fees { buyer: 1% }
+  on_cancel(funded) { buyer: 100% }
+  release: port confirm_delivery | at(releaseDueAt)
+}
+port confirm_delivery { allowed: [buyer] }
+```
+
+## Declared clauses
+
+- `agent description`
+- `caller parked states`
+- `commit`
+- `deadline`
+- `description`
+- `distinct parties`
+- `due`
+- `event name`
+- `id prefix`
+- `input`
+- `moves`
+- `partitions`
+- `port`
+- `quote`
+- `requires drained`
+- `sandbox failure point`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1532,44 +2108,44 @@ Source: [`std/money_flows/held_payment.hsx`](../../../std/money_flows/held_payme
 
 ## Actions and clauses
 
-| Action                       | Clauses lowered                                                                                        |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `fund_piece_2`               | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                              |
-| `fund_piece_3`               | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                              |
-| `collect_service_fee`        | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `release_piece_2`            | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `release_piece_3`            | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `refund_piece_2`             | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `refund_piece_3`             | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `unfund_piece_1`             | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `unfund_piece_2`             | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `unfund_piece_3`             | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `create`                     | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `fund_piece_1`               | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                              |
-| `release_name`               | `agent description`, `deadline`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
-| `release_on_deadline`        | `due`, `moves`, `steps`, `summary`                                                                     |
-| `cancel`                     | `agent description`, `deadline`, `moves`, `steps`, `summary`                                           |
-| `quote_cancellation`         | `agent description`, `deadline`, `moves`, `quote`, `steps`, `summary`                                  |
-| `cancel`                     | `agent description`, `commit`, `deadline`, `moves`, `steps`, `summary`                                 |
-| `retain_cancellation_charge` | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `fund_piece_2`               | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                              |
-| `release_piece_2`            | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `unfund_piece_1`             | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `fund_piece_2`               | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                              |
-| `release_piece_2`            | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `refund_piece_2`             | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `unfund_piece_1`             | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `abandon`                    | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `dispute`                    | `agent description`, `deadline`, `description`, `moves`, `steps`, `summary`                            |
-| `resume`                     | `agent description`, `description`, `moves`, `steps`, `summary`                                        |
-| `create`                     | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `fund`                       | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                              |
-| `release_action`             | `agent description`, `deadline`, `moves`, `port`, `sandbox failure point`, `steps`, `summary`          |
-| `release_on_deadline`        | `due`, `event name`, `moves`, `steps`, `summary`                                                       |
-| `cancel`                     | `agent description`, `deadline`, `event name`, `moves`, `steps`, `summary`                             |
-| `abandon`                    | `agent description`, `moves`, `steps`, `summary`                                                       |
-| `dispute`                    | `agent description`, `deadline`, `description`, `moves`, `steps`, `summary`                            |
-| `resume`                     | `agent description`, `description`, `moves`, `steps`, `summary`                                        |
+| Action | Clauses lowered |
+| --- | --- |
+| `fund_piece_2` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `fund_piece_3` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `collect_service_fee` | `agent description`, `moves`, `steps`, `summary` |
+| `release_piece_2` | `agent description`, `moves`, `steps`, `summary` |
+| `release_piece_3` | `agent description`, `moves`, `steps`, `summary` |
+| `refund_piece_2` | `agent description`, `moves`, `steps`, `summary` |
+| `refund_piece_3` | `agent description`, `moves`, `steps`, `summary` |
+| `unfund_piece_1` | `agent description`, `moves`, `steps`, `summary` |
+| `unfund_piece_2` | `agent description`, `moves`, `steps`, `summary` |
+| `unfund_piece_3` | `agent description`, `moves`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `fund_piece_1` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `[release_name]` | `agent description`, `deadline`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
+| `release_on_deadline` | `due`, `moves`, `steps`, `summary` |
+| `cancel` | `agent description`, `deadline`, `moves`, `steps`, `summary` |
+| `quote_cancellation` | `agent description`, `deadline`, `moves`, `quote`, `steps`, `summary` |
+| `cancel` | `agent description`, `commit`, `deadline`, `moves`, `steps`, `summary` |
+| `retain_cancellation_charge` | `agent description`, `moves`, `steps`, `summary` |
+| `fund_piece_2` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `release_piece_2` | `agent description`, `moves`, `steps`, `summary` |
+| `unfund_piece_1` | `agent description`, `moves`, `steps`, `summary` |
+| `fund_piece_2` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `release_piece_2` | `agent description`, `moves`, `steps`, `summary` |
+| `refund_piece_2` | `agent description`, `moves`, `steps`, `summary` |
+| `unfund_piece_1` | `agent description`, `moves`, `steps`, `summary` |
+| `abandon` | `agent description`, `moves`, `steps`, `summary` |
+| `dispute` | `agent description`, `deadline`, `description`, `moves`, `steps`, `summary` |
+| `resume` | `agent description`, `description`, `moves`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `fund` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `[release_action]` | `agent description`, `deadline`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
+| `release_on_deadline` | `due`, `event name`, `moves`, `steps`, `summary` |
+| `cancel` | `agent description`, `deadline`, `event name`, `moves`, `steps`, `summary` |
+| `abandon` | `agent description`, `moves`, `requires drained`, `steps`, `summary` |
+| `dispute` | `agent description`, `deadline`, `description`, `moves`, `steps`, `summary` |
+| `resume` | `agent description`, `description`, `moves`, `steps`, `summary` |
 
 # instant_transfer
 
@@ -1581,11 +2157,78 @@ Source: [`std/money_flows/instant_transfer.hsx`](../../../std/money_flows/instan
 
 ## Parameters
 
-- `payer: party`
-- `payee: party`
-- `amount: money<C>`
-- `fees: optional<block>`
-- `derived_amount: optional<block>`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `payer` | `party` | Yes | Funding party whose account is debited. |
+| `payee` | `party` | Yes | Recipient party whose account is credited. |
+| `amount` | `money<C>` | Yes | Transfer amount in minor units of currency `C`. |
+| `fees` | `optional<block>` | No | Optional fee configuration block specifying flat fees, percentage fees, or bracketed fee tiers for payer and/or payee. |
+| `derived_amount` | `optional<block>` | No | Optional block declaring derived platform fees calculated from the transfer amount. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Direct, single-step push transfer from payer to payee with optional tiered or percentage fees.
+
+### Purpose
+
+`instant_transfer` debits a payer and credits a payee immediately in a single execution step.
+It fits peer-to-peer transfers, direct disbursements, instant payouts, wallet reloads, and simple point-of-sale payments.
+
+### Selection guidance
+
+- vs `captured_payment`: `instant_transfer` moves money in one atomic step without prior authorization holds,
+  incremental captures, voids, or post-settlement correction ports. Use `captured_payment` when authorization must precede capture.
+- vs `conditional_disbursement`: `instant_transfer` executes immediately without external decision evidence
+  or cumulative cap tracking. Use `conditional_disbursement` when payments require evidence submission or aggregate milestone caps.
+- vs `held_payment`: `instant_transfer` never holds funds in an intermediary escrow account.
+
+### Parameters
+
+- `payer`: Funding party whose account is debited.
+- `payee`: Recipient party whose account is credited.
+- `amount`: Transfer amount in minor units of currency `C`.
+- `fees`: Optional fee configuration block specifying flat fees, percentage fees, or bracketed fee tiers for payer and/or payee.
+- `derived_amount`: Optional block declaring derived platform fees calculated from the transfer amount.
+
+### Decision ports
+
+None. Transfers execute immediately upon invocation.
+
+### Example
+
+```hsx
+program instant_transfer_example "Instant transfer example"
+import { instant_transfer } from "std/money_flows"
+party customer: person
+party merchant: business
+settlement transfer = instant_transfer {
+  payer: customer
+  payee: merchant
+  amount: transferAmount: money(SAR)
+  fees {
+    customer: checkoutFee: money(SAR)
+    merchant {
+      tier { from: 0, to: 10000, fee: 1% }
+      tier { from: 10000, fee: highValueFee: money(SAR) }
+    }
+  }
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `description`
+- `moves`
+- `partitions`
+- `sandbox failure point`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1593,12 +2236,12 @@ None.
 
 ## Actions and clauses
 
-| Action                | Clauses lowered                                                           |
-| --------------------- | ------------------------------------------------------------------------- |
-| `create`              | `agent description`, `moves`, `steps`, `summary`                          |
-| `pay_piece_1`         | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
-| `pay_piece_2`         | `agent description`, `moves`, `steps`, `summary`                          |
-| `collect_service_fee` | `agent description`, `moves`, `steps`, `summary`                          |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `pay_piece_1` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `pay_piece_2` | `agent description`, `moves`, `steps`, `summary` |
+| `collect_service_fee` | `agent description`, `moves`, `steps`, `summary` |
 
 # metered
 
@@ -1610,10 +2253,71 @@ Source: [`std/money_flows/metered.hsx`](../../../std/money_flows/metered.hsx)
 
 ## Parameters
 
-- `payer: party`
-- `payee: party`
-- `close_by: date`
-- `rates: unknown`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `payer` | `party` | Yes | The customer being billed for usage. |
+| `payee` | `party` | Yes | The service provider receiving usage revenue. |
+| `close_by` | `date` | Yes | Date when the metering period closes, preventing further usage charges. |
+| `rates` | `unknown` | Yes | Block mapping rate metric names to their per-unit money prices committed at period open. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Usage-based billing against a committed rate card over an open period until a stored close date.
+
+### Purpose
+
+`metered` bills customers for variable resource consumption such as API requests, compute hours,
+storage gigabytes, or utility consumption. The rate card is fixed when the period opens, and individual
+usage events are charged incrementally until the billing period closes on `close_by`.
+
+### Selection guidance
+
+- vs `scheduled`: `metered` charges variable amounts per event calculated from consumed units and committed
+  rate card prices. `scheduled` executes transfers on fixed calendar recurrence intervals (`every`, `first_due`)
+  with predetermined amounts or installments.
+
+### Parameters
+
+- `payer`: The customer being billed for usage.
+- `payee`: The service provider receiving usage revenue.
+- `close_by`: Date when the metering period closes, preventing further usage charges.
+- `rates`: Block mapping rate metric names to their per-unit money prices committed at period open.
+
+### Decision ports
+
+None. Charges are driven by caller billing actions and period closure.
+
+### Example
+
+```hsx
+program metered_example "Metered example"
+import { metered } from "std/money_flows"
+party customer: business
+party provider: business
+settlement usage = metered {
+  payer: customer
+  payee: provider
+  close_by: periodEnd
+  rates {
+    api_call: callRate: money(SAR)
+    storage_gib: storageRate: money(SAR)
+  }
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `description`
+- `due`
+- `moves`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1621,10 +2325,11 @@ None.
 
 ## Actions and clauses
 
-| Action         | Clauses lowered                         |
-| -------------- | --------------------------------------- |
-| `create`       | `agent description`, `steps`, `summary` |
-| `close_period` | `due`, `steps`, `summary`               |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `steps`, `summary` |
+| `charge_[item]` | `agent description`, `moves`, `steps`, `summary` |
+| `close_period` | `due`, `steps`, `summary` |
 
 # pooled_split
 
@@ -1636,10 +2341,77 @@ Source: [`std/money_flows/pooled_split.hsx`](../../../std/money_flows/pooled_spl
 
 ## Parameters
 
-- `payer: party`
-- `amount: money<C>`
-- `payout_due: date`
-- `split: block`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `payer` | `party` | Yes | The funding party providing the pooled amount. |
+| `amount` | `money<C>` | Yes | Total pooled amount in minor units of currency `C`. |
+| `payout_due` | `date` | Yes | Stored payout date when the pool distributes to all recipients. |
+| `split` | `block` | Yes | Block declaring each recipient's percentage share and `remainder_to` recipient for rounding remainders. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Fixed multi-recipient revenue or period pool funded share-by-share and released automatically on a due date.
+
+### Purpose
+
+`pooled_split` pools a period total from one payer and splits it across a fixed roster of recipients
+according to predetermined percentage shares (with integer division remainder assigned to `remainder_to`).
+Callers fund the pool share-by-share, and payouts disburse automatically to each recipient on `payout_due`.
+
+### Selection guidance
+
+- vs `weighted_distribution`: `pooled_split` hardcodes a fixed set of recipients and static percentage shares
+  directly in the contract. `weighted_distribution` handles dynamic recipient counts where arbitrary weights
+  are recorded as child records and frozen via a snapshot port before distribution.
+- vs `settlement_batch`: `settlement_batch` aggregates multiple payments from many sources into one net payout.
+  `pooled_split` takes one period total from one payer and partitions it out to multiple recipients.
+
+### Parameters
+
+- `payer`: The funding party providing the pooled amount.
+- `amount`: Total pooled amount in minor units of currency `C`.
+- `payout_due`: Stored payout date when the pool distributes to all recipients.
+- `split`: Block declaring each recipient's percentage share and `remainder_to` recipient for rounding remainders.
+
+### Decision ports
+
+None. Payout distribution triggers automatically from the stored `payout_due` date.
+
+### Example
+
+```hsx
+program pooled_split_example "Pooled split example"
+import { pooled_split } from "std/money_flows"
+party payer: business
+party first_recipient: business
+party second_recipient: business
+settlement pool = pooled_split {
+  payer: payer
+  amount: poolAmount: money(SAR)
+  payout_due: payoutDueAt
+  split {
+    first_recipient: 60%
+    second_recipient: 40%
+    remainder_to: first_recipient
+  }
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `description`
+- `due`
+- `id prefix`
+- `moves`
+- `partitions`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1647,9 +2419,11 @@ None.
 
 ## Actions and clauses
 
-| Action   | Clauses lowered                                  |
-| -------- | ------------------------------------------------ |
+| Action | Clauses lowered |
+| --- | --- |
 | `create` | `agent description`, `moves`, `steps`, `summary` |
+| `fund_share_[index]` | `agent description`, `moves`, `steps`, `summary` |
+| `distribute_share_[index]` | `due`, `moves`, `steps`, `summary` |
 
 # premium_forward
 
@@ -1661,14 +2435,94 @@ Source: [`std/money_flows/premium_forward.hsx`](../../../std/money_flows/premium
 
 ## Parameters
 
-- `payer: party`
-- `carrier: party`
-- `amount: money<C>`
-- `bind: condition`
-- `commission: percent`
-- `policy_ref: optional<text>`
-- `renewal_due: optional<date>`
-- `endorsement: optional<condition>`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `payer` | `party` | Yes | The policyholder paying the insurance premium. |
+| `carrier` | `party` | Yes | The insurance carrier underwriting the policy. |
+| `amount` | `money<C>` | Yes | Total gross premium in minor units of currency `C`. |
+| `bind` | `condition` | Yes | Condition port triggering policy binding and premium forwarding. |
+| `commission` | `percent` | Yes | Platform commission percentage retained from the gross premium. |
+| `policy_ref` | `optional<text>` | No | Optional policy identifier string. |
+| `renewal_due` | `optional<date>` | No | Optional date anchor when the policy is due for renewal. |
+| `endorsement` | `optional<condition>` | No | Optional condition port for recording policy endorsements. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Insurance premium escrow holding customer funds until policy binding, then partitioning net carrier premium and commission.
+
+### Purpose
+
+`premium_forward` manages insurance premium collection, broker commission retention, and carrier remittance.
+A policyholder funds the premium into dedicated escrow. The funds remain held until the policy binds via the `bind` port.
+Upon binding, the gross premium is automatically partitioned: the platform fee/commission is retained, and the net
+balance forwards to the carrier. It also supports policy endorsements and renewal schedules.
+
+### Selection guidance
+
+- vs `held_payment`: `premium_forward` is tailored for insurance lifecycles, featuring automatic commission splits
+  upon binding and policy endorsement tracking. `held_payment` is general commercial escrow without insurance
+  underwriting binding semantics or gross-to-net fee partitioning.
+- vs `conditional_disbursement`: `premium_forward` collects and forwards inbound policy premiums to carriers.
+  `conditional_disbursement` pays outbound claim settlements to claimants against stored evidence.
+
+### Parameters
+
+- `payer`: The policyholder paying the insurance premium.
+- `carrier`: The insurance carrier underwriting the policy.
+- `amount`: Total gross premium in minor units of currency `C`.
+- `bind`: Condition port triggering policy binding and premium forwarding.
+- `commission`: Platform commission percentage retained from the gross premium.
+- `policy_ref`: Optional policy identifier string.
+- `renewal_due`: Optional date anchor when the policy is due for renewal.
+- `endorsement`: Optional condition port for recording policy endorsements.
+
+### Decision ports
+
+- `bind`: Port authorizing policy binding, triggering carrier payout and commission retention.
+- `endorsement`: Port allowing carrier endorsement evidence to be recorded.
+
+### Example
+
+```hsx
+program premium_forward_example "Premium forward example"
+import { premium_forward } from "std/money_flows"
+party policyholder: person
+party carrier: business
+settlement premium = premium_forward {
+  payer: policyholder
+  carrier: carrier
+  amount: premiumAmount: money(SAR)
+  commission: 2%
+  bind: port bind_policy
+  policy_ref: policyReference
+  renewal_due: renewalDueAt
+  endorsement: port record_endorsement
+}
+port bind_policy { allowed: [policyholder, carrier] }
+port record_endorsement {
+  allowed: [carrier]
+  shape: { evidenceReference: text }
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `capture input`
+- `description`
+- `due`
+- `input`
+- `moves`
+- `partitions`
+- `port`
+- `sandbox failure point`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1677,17 +2531,17 @@ Source: [`std/money_flows/premium_forward.hsx`](../../../std/money_flows/premium
 
 ## Actions and clauses
 
-| Action            | Clauses lowered                                                                            |
-| ----------------- | ------------------------------------------------------------------------------------------ |
-| `create`          | `agent description`, `steps`, `summary`                                                    |
-| `fund_piece_1`    | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                  |
-| `fund_piece_2`    | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                  |
-| `bind`            | `agent description`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
-| `forward_piece_2` | `agent description`, `moves`, `steps`, `summary`                                           |
-| `unfund_piece_1`  | `agent description`, `moves`, `steps`, `summary`                                           |
-| `abandon`         | `agent description`, `steps`, `summary`                                                    |
-| `endorsement`     | `agent description`, `capture input`, `input`, `port`, `steps`, `summary`                  |
-| `lapse`           | `due`, `steps`, `summary`                                                                  |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `steps`, `summary` |
+| `fund_piece_1` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `fund_piece_2` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `[bind]` | `agent description`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
+| `forward_piece_2` | `agent description`, `moves`, `steps`, `summary` |
+| `unfund_piece_1` | `agent description`, `moves`, `steps`, `summary` |
+| `abandon` | `agent description`, `steps`, `summary` |
+| `[endorsement]` | `agent description`, `capture input`, `input`, `port`, `steps`, `summary` |
+| `lapse` | `due`, `steps`, `summary` |
 
 # reconciled_payout
 
@@ -1699,39 +2553,83 @@ Source: [`std/money_flows/reconciled_payout.hsx`](../../../std/money_flows/recon
 
 ## Parameters
 
-- `payer: party`
-- `beneficiary: party`
-- `amount: money<C>`
-- `beneficiary_ref: text`
-- `settle_by: date`
-- `matched_within: integer`
-- `matched_ceiling: integer`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `payer` | `party` | Yes | The funding party providing the payout. |
+| `beneficiary` | `party` | Yes | The beneficiary party receiving the external payout. |
+| `amount` | `money<C>` | Yes | Instructed payout amount in minor units of currency `C`. |
+| `beneficiary_ref` | `text` | Yes | Registered external beneficiary ID for bank routing. |
+| `settle_by` | `date` | Yes | Cut-off date when unmatched expectation amounts become formal break records. |
+| `matched_within` | `integer` | Yes | Match tolerance window in basis points or minor units. |
+| `matched_ceiling` | `integer` | Yes | Maximum acceptable tolerance ceiling between instructed amount and settled debit. |
 
-## Decision ports
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
 
-None.
+## Module guidance
 
-## Actions and clauses
+Outbound bank payout instruction with end-to-end reconciliation against external bank statement feeds.
 
-| Action     | Clauses lowered                                            |
-| ---------- | ---------------------------------------------------------- |
-| `create`   | `agent description`, `moves`, `steps`, `summary`           |
-| `instruct` | `agent description`, `moves`, `payout`, `steps`, `summary` |
-| `settle`   | `due`, `moves`, `reconcile`, `steps`, `summary`            |
-| `create`   | `agent description`, `moves`, `steps`, `summary`           |
-| `carry`    | `agent description`, `moves`, `steps`, `summary`           |
+### Purpose
 
-# recurring_collection
+`reconciled_payout` manages high-assurance payouts to external suppliers, partners, or customers where payment
+is not complete until confirmed by bank statement data. An instruction is dispatched to the beneficiary and an expectation
+record is opened. Incoming statement debit lines match against the expectation within configurable tolerance thresholds
+(`matched_within`, `matched_ceiling`). If the statement debit does not match before `settle_by`, a formal break row is raised.
 
-Source: [`std/money_flows/recurring_collection.hsx`](../../../std/money_flows/recurring_collection.hsx)
+### Selection guidance
 
-## Export
+- vs `settlement_batch`: `reconciled_payout` executes and reconciles an individual bank payout instruction.
+  `settlement_batch` aggregates periodic captures, fees, and signed adjustments to calculate a net payable batch.
+- vs `instant_transfer`: `instant_transfer` executes an immediate internal ledger transfer between platform accounts.
+  `reconciled_payout` dispatches funds across external banking rails with reconciliation tolerances and break tracking.
 
-`recurring_collection`
+### Parameters
 
-## Parameters
+- `payer`: The funding party providing the payout.
+- `beneficiary`: The beneficiary party receiving the external payout.
+- `amount`: Instructed payout amount in minor units of currency `C`.
+- `beneficiary_ref`: Registered external beneficiary ID for bank routing.
+- `settle_by`: Cut-off date when unmatched expectation amounts become formal break records.
+- `matched_within`: Match tolerance window in basis points or minor units.
+- `matched_ceiling`: Maximum acceptable tolerance ceiling between instructed amount and settled debit.
 
-- `marker: optional<text>`
+### Decision ports
+
+None. Payout dispatch and settlement matching follow the declared schedule, bank statement lines, and tolerance rules.
+
+### Example
+
+```hsx
+program reconciled_payout_example "Reconciled payout example"
+import { reconciled_payout } from "std/money_flows"
+party treasury: business
+party supplier: business
+settlement supplier_payout = reconciled_payout {
+  payer: treasury
+  beneficiary: supplier
+  amount: netPayable: money(SAR)
+  beneficiary_ref: supplierBeneficiaryId
+  settle_by: settleBy
+  matched_within: 100
+  matched_ceiling: 500
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `description`
+- `dials`
+- `due`
+- `id prefix`
+- `moves`
+- `payout`
+- `reconcile`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1739,11 +2637,13 @@ None.
 
 ## Actions and clauses
 
-| Action    | Clauses lowered                         |
-| --------- | --------------------------------------- |
-| `create`  | `agent description`, `steps`, `summary` |
-| `collect` | `agent description`, `steps`, `summary` |
-| `end`     | `agent description`, `steps`, `summary` |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `instruct` | `agent description`, `moves`, `payout`, `steps`, `summary` |
+| `settle` | `due`, `moves`, `reconcile`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `carry` | `agent description`, `moves`, `steps`, `summary` |
 
 # rotating_pool
 
@@ -1755,18 +2655,99 @@ Source: [`std/money_flows/rotating_pool.hsx`](../../../std/money_flows/rotating_
 
 ## Parameters
 
-- `members: optional<list<party>>`
-- `contribution: money<C>`
-- `count: integer`
-- `every: optional<text>`
-- `first_due: date`
-- `payout_order: optional<list<party>>`
-- `default_policy: optional<text>`
-- `guarantee_policy: optional<text>`
-- `guarantor: optional<party>`
-- `exit_policy: optional<text>`
-- `memo: optional<text>`
-- `membership: optional<block>`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `members` | `optional<list<party>>` | No | List of parties belonging to the rotating group. |
+| `contribution` | `money<C>` | Yes | Fixed contribution amount required from each member per cycle in minor units of currency `C`. |
+| `count` | `integer` | Yes | Total number of cycles in the rotation (matching the member count). |
+| `every` | `optional<text>` | No | Recurrence interval between contribution cycles (e.g. `"P30D"`). |
+| `first_due` | `date` | Yes | Due date for the first cycle's contribution. |
+| `payout_order` | `optional<list<party>>` | No | Ordered list of member parties defining the cycle payout sequence. |
+| `default_policy` | `optional<text>` | No | Policy for handling missed contributions (`due_condition`). |
+| `guarantee_policy` | `optional<text>` | No | Policy for backing defaulted contributions (`funded_only`). |
+| `guarantor` | `optional<party>` | No | Optional guarantor party covering member defaults. |
+| `exit_policy` | `optional<text>` | No | Policy governing member departures (`before_activation_only`). |
+| `memo` | `optional<text>` | No | Optional memo text stored on the pool. |
+| `membership` | `optional<block>` | No | Optional custom membership configuration block. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Rotating savings and credit association (ROSCA) pool where members contribute fixed amounts and take turns receiving the pot.
+
+### Purpose
+
+`rotating_pool` coordinates peer savings circles, chit funds, tandas, and committee savings groups.
+A fixed group of members contributes an identical contribution amount each cycle. In each cycle, one designated member
+receives the entire pooled pot according to a predefined `payout_order` until all members have taken their turn.
+
+### Selection guidance
+
+- vs `threshold_pool`: `rotating_pool` coordinates recurring multi-party peer savings with rotating payouts.
+  `threshold_pool` is all-or-nothing capital accumulation toward a single threshold for one beneficiary.
+- vs `scheduled`: `scheduled` coordinates a single payer to a single payee. `rotating_pool` orchestrates
+  a closed circular group of members taking sequential turns.
+
+### Parameters
+
+- `members`: List of parties belonging to the rotating group.
+- `contribution`: Fixed contribution amount required from each member per cycle in minor units of currency `C`.
+- `count`: Total number of cycles in the rotation (matching the member count).
+- `every`: Recurrence interval between contribution cycles (e.g. `"P30D"`).
+- `first_due`: Due date for the first cycle's contribution.
+- `payout_order`: Ordered list of member parties defining the cycle payout sequence.
+- `default_policy`: Policy for handling missed contributions (`due_condition`).
+- `guarantee_policy`: Policy for backing defaulted contributions (`funded_only`).
+- `guarantor`: Optional guarantor party covering member defaults.
+- `exit_policy`: Policy governing member departures (`before_activation_only`).
+- `memo`: Optional memo text stored on the pool.
+- `membership`: Optional custom membership configuration block.
+
+### Decision ports
+
+None. Cycle advancement and pot payouts follow the declared schedule and membership actions.
+
+### Example
+
+```hsx
+program rotating_pool_example "Rotating pool example"
+import { rotating_pool } from "std/money_flows"
+party member_a: person
+party member_b: person
+party member_c: person
+party guarantor: business
+settlement pool = rotating_pool {
+  members: [member_a, member_b, member_c]
+  contribution: contributionAmount: money(SAR)
+  count: 3
+  every: P30D
+  first_due: firstContributionAt
+  payout_order: [member_b, member_c, member_a]
+  default_policy: due_condition
+  guarantee_policy: funded_only
+  guarantor: guarantor
+  exit_policy: before_activation_only
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `aggregate invariants`
+- `caller parked states`
+- `description`
+- `due`
+- `examples`
+- `id prefix`
+- `moves`
+- `sandbox failure point`
+- `steps`
+- `summary`
+- `title`
+- `unique`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1774,17 +2755,24 @@ None.
 
 ## Actions and clauses
 
-| Action     | Clauses lowered                                   |
-| ---------- | ------------------------------------------------- |
-| `create`   | `agent description`, `moves`, `steps`, `summary`  |
-| `cancel`   | `agent description`, `moves`, `steps`, `summary`  |
-| `activate` | `agent description`, `moves`, `steps`, `summary`  |
-| `create`   | `agent description`, `moves`, `steps`, `summary`  |
-| `close`    | `agent description`, `moves`, `steps`, `summary`  |
-| `create`   | `agent description`, `examples`, `moves`, `steps` |
-| `activate` | `due`, `examples`, `moves`, `steps`               |
-| `disband`  | `agent description`, `examples`, `moves`, `steps` |
-| `close`    | `agent description`, `examples`, `moves`, `steps` |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `cancel` | `agent description`, `moves`, `steps`, `summary` |
+| `activate` | `agent description`, `moves`, `steps`, `summary` |
+| `ready_cycle_[cycle]` | `agent description`, `moves`, `steps`, `summary` |
+| `advance_cycle_[cycle]` | `agent description`, `moves`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `steps`, `summary`, `unique` |
+| `contribute_cycle_[cycle]` | `due`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `mark_default_cycle_[cycle]` | `due`, `moves`, `steps`, `summary` |
+| `guarantee_cycle_[cycle]` | `agent description`, `moves`, `steps`, `summary` |
+| `pay_cycle_[cycle]` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `pay_guaranteed_cycle_[cycle]` | `agent description`, `moves`, `steps`, `summary` |
+| `close` | `agent description`, `moves`, `steps`, `summary` |
+| `create` | `agent description`, `examples`, `moves`, `steps` |
+| `activate` | `due`, `examples`, `moves`, `steps` |
+| `disband` | `agent description`, `examples`, `moves`, `steps` |
+| `close` | `agent description`, `examples`, `moves`, `steps` |
 
 # scheduled
 
@@ -1796,21 +2784,104 @@ Source: [`std/money_flows/scheduled.hsx`](../../../std/money_flows/scheduled.hsx
 
 ## Parameters
 
-- `payer: party`
-- `payee: party`
-- `amount: money<C>`
-- `count: optional<integer>`
-- `every: text`
-- `first_due: date`
-- `mode: optional<text>`
-- `debtor: optional<party>`
-- `advance_to: optional<party>`
-- `until: optional<condition>`
-- `month_end: optional<text>`
-- `period_liability: optional<text>`
-- `termination_drain: optional<text>`
-- `mandate: optional<condition>`
-- `derived_amount: optional<unknown>`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `payer` | `party` | Yes | The paying party (or repayment source). |
+| `payee` | `party` | Yes | The beneficiary party receiving installment funds. |
+| `amount` | `money<C>` | Yes | Total amount to partition into installments or recurring charge amount in minor units of currency `C`. |
+| `count` | `optional<integer>` | No | Optional number of installments for installment or obligation modes. |
+| `every` | `text` | Yes | Recurrence cadence duration string (e.g. `"P30D"`, `"P1M"`). |
+| `first_due` | `date` | Yes | Stored date anchor for the first installment or charge. |
+| `mode` | `optional<text>` | No | Optional mode selector (`obligation`). Omit for standard installment plans. |
+| `debtor` | `optional<party>` | No | Optional debtor party when distinct from the payment source in obligation mode. |
+| `advance_to` | `optional<party>` | No | Optional third-party receiving upfront advance disbursements in obligation mode. |
+| `until` | `optional<condition>` | No | Optional condition port triggering cancellation of recurring subscription runs. |
+| `month_end` | `optional<text>` | No | Optional handling policy for calendar month-end adjustments. |
+| `period_liability` | `optional<text>` | No | Optional liability policy for billing periods. |
+| `termination_drain` | `optional<text>` | No | Optional policy for draining balances on early termination. |
+| `mandate` | `optional<condition>` | No | Optional condition port supplying formal debit mandate evidence. |
+| `derived_amount` | `optional<unknown>` | No | Optional calculated markup or fee rules. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Calendar-anchored payments supporting fixed installment plans, recurring subscriptions, or debt obligations.
+
+### Purpose
+
+`scheduled` automates time-anchored payment series between one payer and one payee.
+It supports three modes:
+
+1. Installment plan: Partitions a fixed total amount into `count` installments, each collected on its own stored date.
+2. Open recurring subscription: Charges a recurring amount on an interval `every` until an `until` port fires.
+3. Debt obligation: Manages legally binding multi-installment debt with delinquency tracking, mandate evidence, and child payment records.
+
+### Selection guidance
+
+- vs `metered`: `scheduled` executes calendar-based recurring charges or fixed installment plans.
+  `metered` bills variable usage per event based on a committed rate card.
+- vs `rotating_pool`: `scheduled` coordinates one payer to one payee on a calendar.
+  `rotating_pool` coordinates a multi-party peer circle where members rotate turns receiving the entire pot.
+
+### Parameters
+
+- `payer`: The paying party (or repayment source).
+- `payee`: The beneficiary party receiving installment funds.
+- `amount`: Total amount to partition into installments or recurring charge amount in minor units of currency `C`.
+- `count`: Optional number of installments for installment or obligation modes.
+- `every`: Recurrence cadence duration string (e.g. `"P30D"`, `"P1M"`).
+- `first_due`: Stored date anchor for the first installment or charge.
+- `mode`: Optional mode selector (`obligation`). Omit for standard installment plans.
+- `debtor`: Optional debtor party when distinct from the payment source in obligation mode.
+- `advance_to`: Optional third-party receiving upfront advance disbursements in obligation mode.
+- `until`: Optional condition port triggering cancellation of recurring subscription runs.
+- `month_end`: Optional handling policy for calendar month-end adjustments.
+- `period_liability`: Optional liability policy for billing periods.
+- `termination_drain`: Optional policy for draining balances on early termination.
+- `mandate`: Optional condition port supplying formal debit mandate evidence.
+- `derived_amount`: Optional calculated markup or fee rules.
+
+### Decision ports
+
+- `until`: Port terminating recurring subscriptions.
+- `mandate`: Port supplying mandate verification evidence for direct debit obligations.
+
+### Example
+
+```hsx
+program scheduled_example "Scheduled example"
+import { scheduled } from "std/money_flows"
+party payer: business
+party payee: business
+settlement installments = scheduled {
+  payer: payer
+  payee: payee
+  amount: totalAmount: money(SAR)
+  count: 3
+  every: P30D
+  first_due: firstDueAt
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `aggregate invariants`
+- `capture input`
+- `description`
+- `due`
+- `input`
+- `moves`
+- `partitions`
+- `port`
+- `sandbox failure point`
+- `sets at`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1819,22 +2890,24 @@ Source: [`std/money_flows/scheduled.hsx`](../../../std/money_flows/scheduled.hsx
 
 ## Actions and clauses
 
-| Action              | Clauses lowered                                                                                                            |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `create`            | `agent description`, `steps`, `summary`                                                                                    |
-| `create`            | `agent description`, `moves`, `steps`, `summary`                                                                           |
-| `approve`           | `agent description`, `steps`, `summary`                                                                                    |
-| `advance`           | `agent description`, `moves`, `steps`, `summary`                                                                           |
-| `delinquent_action` | `due`, `sets at`, `steps`, `summary`                                                                                       |
-| `complete`          | `due`, `steps`, `summary`                                                                                                  |
-| `write_off`         | `agent description`, `steps`, `summary`                                                                                    |
-| `create`            | `agent description`, `steps`, `summary`                                                                                    |
-| `repay`             | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary`                          |
-| `refund`            | `agent description`, `moves`, `steps`, `summary`                                                                           |
-| `create`            | `agent description`, `steps`, `summary`                                                                                    |
-| `open_period`       | `due`, `steps`, `summary`                                                                                                  |
-| `collect_period`    | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
-| `until`             | `agent description`, `capture input`, `input`, `port`, `steps`, `summary`                                                  |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `steps`, `summary` |
+| `pay_installment_[i]` | `due`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `approve` | `agent description`, `steps`, `summary` |
+| `advance` | `agent description`, `moves`, `steps`, `summary` |
+| `collect_installment_[i]` | `due`, `steps`, `summary` |
+| `[delinquent_action]` | `due`, `sets at`, `steps`, `summary` |
+| `complete` | `due`, `steps`, `summary` |
+| `write_off` | `agent description`, `steps`, `summary` |
+| `create` | `agent description`, `steps`, `summary` |
+| `repay` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
+| `refund` | `agent description`, `moves`, `steps`, `summary` |
+| `create` | `agent description`, `steps`, `summary` |
+| `open_period` | `due`, `steps`, `summary` |
+| `collect_period` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
+| `[until]` | `agent description`, `capture input`, `input`, `port`, `steps`, `summary` |
 
 # security_deposit
 
@@ -1846,20 +2919,112 @@ Source: [`std/money_flows/security_deposit.hsx`](../../../std/money_flows/securi
 
 ## Parameters
 
-- `payer: party`
-- `holder: party`
-- `amount: money<C>`
-- `claim: optional<condition>`
-- `return: optional<condition>`
-- `claim_amount: optional<block>`
-- `deadline: optional<date>`
-- `claim_to: optional<party>`
-- `return_to: optional<party>`
-- `memo: optional<text>`
-- `claim_input: optional<block>`
-- `claim_capture: optional<block>`
-- `fund_failure_point: optional<text>`
-- `id_prefix_override: optional<text>`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `payer` | `party` | Yes | The customer providing the deposit collateral. |
+| `holder` | `party` | Yes | The merchant or owner holding the deposit rights. |
+| `amount` | `money<C>` | Yes | Total reserved deposit amount in minor units of currency `C`. |
+| `claim` | `optional<condition>` | No | Optional condition port triggering a damage claim. |
+| `return` | `optional<condition>` | No | Optional condition port triggering full return of the deposit. |
+| `claim_amount` | `optional<block>` | No | Optional block defining partial claim logic (`field`, `bound`, `remainder`). |
+| `deadline` | `optional<date>` | No | Optional stored date anchor for automatic deposit release or expiry. |
+| `claim_to` | `optional<party>` | No | Optional alternate destination for claimed funds. |
+| `return_to` | `optional<party>` | No | Optional alternate destination for returned funds. |
+| `memo` | `optional<text>` | No | Optional memo text stored on the deposit record. |
+| `claim_input` | `optional<block>` | No | Optional custom input schema for the claim action. |
+| `claim_capture` | `optional<block>` | No | Optional capture mappings for claim evidence. |
+| `fund_failure_point` | `optional<text>` | No | Optional configuration for deposit funding failure. |
+| `id_prefix_override` | `optional<text>` | No | Optional custom prefix for generated instrument IDs. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Collateral deposit reserved against a payer's account in favor of a holder, returned in full or claimed against damages.
+
+### Purpose
+
+`security_deposit` reserves collateral funds for vehicle rentals, property leasing, equipment hire, and security bonds.
+Funds remain held until the rental or lease concludes. The holder can either return the deposit in full
+or assess damages, claim a decided partial amount, and return the exact unspent remainder.
+
+### Selection guidance
+
+- vs `held_payment`: `security_deposit` holds collateral where the standard outcome is returning 100% of the funds
+  to the payer, and claims are partial damage assessments. `held_payment` holds payment consideration where the
+  standard outcome is releasing 100% of the funds to the payee upon delivery.
+- vs `cancellable_booking`: `cancellable_booking` holds booking fees and applies time-based cancellation penalties.
+  `security_deposit` holds damage collateral and supports arbitrary damage claims with remainder refund.
+
+### Parameters
+
+- `payer`: The customer providing the deposit collateral.
+- `holder`: The merchant or owner holding the deposit rights.
+- `amount`: Total reserved deposit amount in minor units of currency `C`.
+- `claim`: Optional condition port triggering a damage claim.
+- `return`: Optional condition port triggering full return of the deposit.
+- `claim_amount`: Optional block defining partial claim logic (`field`, `bound`, `remainder`).
+- `deadline`: Optional stored date anchor for automatic deposit release or expiry.
+- `claim_to`: Optional alternate destination for claimed funds.
+- `return_to`: Optional alternate destination for returned funds.
+- `memo`: Optional memo text stored on the deposit record.
+- `claim_input`: Optional custom input schema for the claim action.
+- `claim_capture`: Optional capture mappings for claim evidence.
+- `fund_failure_point`: Optional configuration for deposit funding failure.
+- `id_prefix_override`: Optional custom prefix for generated instrument IDs.
+
+### Decision ports
+
+- `claim`: Port permitting the holder to submit a damage claim.
+- `return`: Port permitting the holder to return the deposit to the payer.
+
+### Example
+
+```hsx
+program deposit_example "Deposit example"
+import { security_deposit } from "std/money_flows"
+party renter: person
+party owner: business
+settlement security_deposit = security_deposit {
+  payer: renter
+  holder: owner
+  amount: depositAmount: money(SAR)
+  claim: port assess_damage
+  claim_amount: decided {
+    field: damageAmount
+    bound: depositAmount
+    remainder: return
+  }
+  return: port return_deposit
+}
+port assess_damage {
+  allowed: [owner]
+  shape: { damageAmount: money(SAR), evidence: text }
+}
+port return_deposit { allowed: [owner] }
+```
+
+## Declared clauses
+
+- `agent description`
+- `caller parked states`
+- `capture input`
+- `deadline`
+- `decided amount`
+- `description`
+- `dials`
+- `distinct parties`
+- `due`
+- `id prefix`
+- `input`
+- `moves`
+- `port`
+- `sandbox failure point`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1868,18 +3033,18 @@ Source: [`std/money_flows/security_deposit.hsx`](../../../std/money_flows/securi
 
 ## Actions and clauses
 
-| Action          | Clauses lowered                                                                                                                           |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `create`        | `agent description`, `moves`, `steps`, `summary`                                                                                          |
-| `place_deposit` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary`                                                                 |
-| `claim_name`    | `agent description`, `input`, `moves`, `port`, `steps`, `summary`                                                                         |
-| `return_name`   | `agent description`, `capture input`, `input`, `moves`, `port`, `steps`, `summary`                                                        |
-| `create`        | `agent description`, `deadline`, `moves`, `steps`, `summary`                                                                              |
-| `fund`          | `agent description`, `deadline`, `moves`, `sandbox failure point`, `steps`, `summary`                                                     |
-| `claim`         | `agent description`, `capture input`, `deadline`, `decided amount`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
-| `return`        | `agent description`, `deadline`, `moves`, `port`, `steps`, `summary`                                                                      |
-| `expire`        | `due`, `moves`, `steps`, `summary`                                                                                                        |
-| `cancel`        | `agent description`, `moves`, `steps`, `summary`                                                                                          |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `place_deposit` | `agent description`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `[claim_name]` | `agent description`, `input`, `moves`, `port`, `steps`, `summary` |
+| `[return_name]` | `agent description`, `capture input`, `input`, `moves`, `port`, `steps`, `summary` |
+| `create` | `agent description`, `deadline`, `moves`, `steps`, `summary` |
+| `fund` | `agent description`, `deadline`, `moves`, `sandbox failure point`, `steps`, `summary` |
+| `claim` | `agent description`, `capture input`, `deadline`, `decided amount`, `input`, `moves`, `port`, `sandbox failure point`, `steps`, `summary` |
+| `return` | `agent description`, `deadline`, `moves`, `port`, `steps`, `summary` |
+| `expire` | `due`, `moves`, `steps`, `summary` |
+| `cancel` | `agent description`, `moves`, `steps`, `summary` |
 
 # settlement_batch
 
@@ -1891,15 +3056,96 @@ Source: [`std/money_flows/settlement_batch.hsx`](../../../std/money_flows/settle
 
 ## Parameters
 
-- `settlement_account: party`
-- `source_capture_refs: text`
-- `fee_entries: text`
-- `external_reversal_offsets: text`
-- `close_trigger: date`
-- `payout_destination: party`
-- `negative_position: text`
-- `payout_acknowledgement: condition`
-- `payout_beneficiary_ref: text`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `settlement_account` | `party` | Yes | The source clearing account holding captured funds and paying the batch. |
+| `source_capture_refs` | `text` | Yes | Binding name for gross capture references included in the batch. |
+| `fee_entries` | `text` | Yes | Binding name for fee deductions applied to the batch. |
+| `external_reversal_offsets` | `text` | Yes | Binding name for reversal adjustments applied to the batch. |
+| `close_trigger` | `date` | Yes | Date when the batch closes and ceases accepting new transaction entries. |
+| `payout_destination` | `party` | Yes | The merchant or partner account receiving the net payout. |
+| `negative_position` | `text` | Yes | Policy when calculated net payable is zero or negative (`reject`). |
+| `payout_acknowledgement` | `condition` | Yes | Condition port confirming bank receipt of the payout. |
+| `payout_beneficiary_ref` | `text` | Yes | Beneficiary identifier for external bank dispatch. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Periodic aggregation of capture lineage, fee entries, and adjustments into a single net calculated payout.
+
+### Purpose
+
+`settlement_batch` settles merchant balances, marketplace vendor earnings, and partner clearing accounts.
+Individual payment captures, platform fees, and reversal adjustments accumulate into an open batch over a period.
+On `close_trigger`, the batch freezes. The platform calculates the signed net payable from gross captures plus credit
+adjustments minus debit adjustments. If positive, an outbound bank payout is instructed and acknowledged.
+
+### Selection guidance
+
+- vs `reconciled_payout`: `settlement_batch` aggregates multiple transactions and adjustments over a billing cycle
+  to compute a single net payable. `reconciled_payout` manages bank instruction dispatch and statement line reconciliation
+  for an individual payout amount.
+- vs `weighted_distribution`: `settlement_batch` consolidates many inbound transactions into one net outbound payout.
+  `weighted_distribution` splits one funding pool into many recipient payouts.
+
+### Parameters
+
+- `settlement_account`: The source clearing account holding captured funds and paying the batch.
+- `source_capture_refs`: Binding name for gross capture references included in the batch.
+- `fee_entries`: Binding name for fee deductions applied to the batch.
+- `external_reversal_offsets`: Binding name for reversal adjustments applied to the batch.
+- `close_trigger`: Date when the batch closes and ceases accepting new transaction entries.
+- `payout_destination`: The merchant or partner account receiving the net payout.
+- `negative_position`: Policy when calculated net payable is zero or negative (`reject`).
+- `payout_acknowledgement`: Condition port confirming bank receipt of the payout.
+- `payout_beneficiary_ref`: Beneficiary identifier for external bank dispatch.
+
+### Decision ports
+
+- `payout_acknowledgement`: Port recording external bank or partner receipt confirmation.
+
+### Example
+
+```hsx
+program settlement_batch_example "Settlement batch example"
+import { settlement_batch } from "std/money_flows"
+party settlement_account: business
+party payout_destination: business
+settlement batch = settlement_batch {
+  settlement_account: settlement_account
+  source_capture_refs: captureReference
+  fee_entries: feeReference
+  external_reversal_offsets: reversalReference
+  close_trigger: closeAt
+  payout_destination: payout_destination
+  negative_position: reject
+  payout_acknowledgement: port acknowledge_payout
+  payout_beneficiary_ref: payoutBeneficiaryId
+}
+port acknowledge_payout {
+  allowed: [payout_destination]
+  shape: { acknowledgementReference: text }
+}
+```
+
+## Declared clauses
+
+- `agent description`
+- `capture input`
+- `description`
+- `due`
+- `id prefix`
+- `input`
+- `moves`
+- `payout`
+- `port`
+- `reconcile`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1907,20 +3153,20 @@ Source: [`std/money_flows/settlement_batch.hsx`](../../../std/money_flows/settle
 
 ## Actions and clauses
 
-| Action                   | Clauses lowered                                                                                   |
-| ------------------------ | ------------------------------------------------------------------------------------------------- |
-| `create`                 | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `close`                  | `due`, `moves`, `steps`, `summary`                                                                |
-| `calculate`              | `agent description`, `computes signed_sum`, `moves`, `steps`, `summary`                           |
-| `approve`                | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `instruct`               | `agent description`, `moves`, `payout`, `steps`, `summary`                                        |
-| `payout_acknowledgement` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
-| `reconcile`              | `due`, `moves`, `reconcile`, `steps`, `summary`                                                   |
-| `create`                 | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `accrue`                 | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `create`                 | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `adjust`                 | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `correct`                | `agent description`, `moves`, `steps`, `summary`                                                  |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `close` | `due`, `moves`, `steps`, `summary` |
+| `calculate` | `agent description`, `moves`, `steps`, `summary` |
+| `approve` | `agent description`, `moves`, `steps`, `summary` |
+| `instruct` | `agent description`, `moves`, `payout`, `steps`, `summary` |
+| `[payout_acknowledgement]` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
+| `reconcile` | `due`, `moves`, `reconcile`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `accrue` | `agent description`, `moves`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `adjust` | `agent description`, `moves`, `steps`, `summary` |
+| `correct` | `agent description`, `moves`, `steps`, `summary` |
 
 # swap
 
@@ -1932,16 +3178,103 @@ Source: [`std/money_flows/swap.hsx`](../../../std/money_flows/swap.hsx)
 
 ## Parameters
 
-- `between: list<party>`
-- `amounts: block`
-- `fees: block`
-- `release: condition`
-- `dispute: condition`
-- `side_names: optional<block>`
-- `lifecycle_state_order: optional<list<text>>`
-- `action_bindings: optional<block>`
-- `parked_states: optional<block>`
-- `fixed_prefix: optional<text>`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `between` | `list<party>` | Yes | List containing exactly two trade participant parties (`[side_a, side_b]`). |
+| `amounts` | `block` | Yes | Block declaring the principal money amounts for each party. |
+| `fees` | `block` | Yes | Block declaring the platform fee money amounts for each party. |
+| `release` | `condition` | Yes | Condition port required to execute the atomic swap release. |
+| `dispute` | `condition` | Yes | Condition port triggering unwinding and refunding of both trade legs. |
+| `side_names` | `optional<block>` | No | Optional custom naming block for the two sides (`first`, `second`). |
+| `lifecycle_state_order` | `optional<list<text>>` | No | Optional custom ordering for lifecycle states. |
+| `action_bindings` | `optional<block>` | No | Optional custom action names. |
+| `parked_states` | `optional<block>` | No | Optional configuration for parked states. |
+| `fixed_prefix` | `optional<text>` | No | Optional custom prefix for generated instrument IDs. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Atomic two-sided trade between two parties where neither leg settles alone.
+
+### Purpose
+
+`swap` executes atomic delivery-versus-payment (DvP) or payment-versus-payment (PvP) exchanges between two named parties.
+Both sides fund their declared principal amounts and platform fees into a shared escrow. The exchange settles atomically
+upon triggering the `release` condition port, paying each party the other's funded amount. If a `dispute` occurs,
+both legs unwind and refund simultaneously. Half-funded or half-released states cannot occur.
+
+### Selection guidance
+
+- vs `held_payment`: `swap` is a bilateral trade where both sides must deposit funds into escrow and receive each other's
+  disbursements simultaneously. `held_payment` is unilateral escrow where a single payer funds a payment held for a payee.
+- vs `instant_transfer`: `instant_transfer` executes an immediate one-way transfer. `swap` coordinates two reciprocal transfers
+  held atomically in escrow until release confirmation.
+
+### Parameters
+
+- `between`: List containing exactly two trade participant parties (`[side_a, side_b]`).
+- `amounts`: Block declaring the principal money amounts for each party.
+- `fees`: Block declaring the platform fee money amounts for each party.
+- `release`: Condition port required to execute the atomic swap release.
+- `dispute`: Condition port triggering unwinding and refunding of both trade legs.
+- `side_names`: Optional custom naming block for the two sides (`first`, `second`).
+- `lifecycle_state_order`: Optional custom ordering for lifecycle states.
+- `action_bindings`: Optional custom action names.
+- `parked_states`: Optional configuration for parked states.
+- `fixed_prefix`: Optional custom prefix for generated instrument IDs.
+
+### Decision ports
+
+- `release`: Port authorizing atomic settlement of both trade legs.
+- `dispute`: Port triggering atomic cancellation and refund of both parties.
+
+### Example
+
+```hsx
+program swap_example "Swap example"
+import { swap } from "std/money_flows"
+party buyer: business
+party seller: business
+settlement exchange = swap {
+  between: [buyer, seller]
+  amounts {
+    buyer: buyerAmount: money(SAR)
+    seller: sellerAmount: money(SAR)
+  }
+  fees {
+    buyer: buyerFee: money(SAR)
+    seller: sellerFee: money(SAR)
+  }
+  release: port release_exchange
+  dispute: port dispute_exchange within P7D
+}
+port release_exchange { allowed: [buyer, seller] }
+port dispute_exchange { allowed: [buyer, seller] }
+```
+
+## Declared clauses
+
+- `agent description`
+- `caller parked states`
+- `capture input`
+- `deadline`
+- `description`
+- `distinct parties`
+- `due`
+- `event name`
+- `id prefix`
+- `input`
+- `moves`
+- `port`
+- `public action`
+- `sandbox failure point`
+- `sets at`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1950,22 +3283,22 @@ Source: [`std/money_flows/swap.hsx`](../../../std/money_flows/swap.hsx)
 
 ## Actions and clauses
 
-| Action    | Clauses lowered                                                                                                               |
-| --------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `abandon` | `agent description`, `moves`, `public action`, `steps`, `summary`                                                             |
-| `cancel`  | `agent description`, `moves`, `public action`, `steps`, `summary`                                                             |
-| `create`  | `agent description`, `moves`, `public action`, `steps`, `summary`                                                             |
-| `dispute` | `agent description`, `capture input`, `deadline`, `input`, `moves`, `port`, `public action`, `steps`, `summary`               |
-| `fund`    | `agent description`, `moves`, `public action`, `sandbox failure point`, `steps`, `summary`                                    |
-| `post`    | `due`, `moves`, `steps`, `summary`                                                                                            |
-| `release` | `agent description`, `moves`, `port`, `public action`, `sandbox failure point`, `sets at`, `steps`, `summary`                 |
-| `create`  | `agent description`, `moves`, `public action`, `steps`, `summary`                                                             |
-| `fund`    | `agent description`, `event name`, `moves`, `public action`, `sandbox failure point`, `steps`, `summary`                      |
-| `release` | `agent description`, `event name`, `moves`, `port`, `public action`, `sandbox failure point`, `sets at`, `steps`, `summary`   |
-| `post`    | `due`, `event name`, `moves`, `steps`, `summary`                                                                              |
+| Action | Clauses lowered |
+| --- | --- |
+| `abandon` | `agent description`, `moves`, `public action`, `steps`, `summary` |
+| `cancel` | `agent description`, `moves`, `public action`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `public action`, `steps`, `summary` |
+| `dispute` | `agent description`, `capture input`, `deadline`, `input`, `moves`, `port`, `public action`, `steps`, `summary` |
+| `fund` | `agent description`, `moves`, `public action`, `sandbox failure point`, `steps`, `summary` |
+| `post` | `due`, `moves`, `steps`, `summary` |
+| `release` | `agent description`, `moves`, `port`, `public action`, `sandbox failure point`, `sets at`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `public action`, `steps`, `summary` |
+| `fund` | `agent description`, `event name`, `moves`, `public action`, `sandbox failure point`, `steps`, `summary` |
+| `release` | `agent description`, `event name`, `moves`, `port`, `public action`, `sandbox failure point`, `sets at`, `steps`, `summary` |
+| `post` | `due`, `event name`, `moves`, `steps`, `summary` |
 | `dispute` | `agent description`, `capture input`, `deadline`, `event name`, `input`, `moves`, `port`, `public action`, `steps`, `summary` |
-| `cancel`  | `agent description`, `event name`, `moves`, `public action`, `steps`, `summary`                                               |
-| `abandon` | `agent description`, `event name`, `moves`, `public action`, `steps`, `summary`                                               |
+| `cancel` | `agent description`, `event name`, `moves`, `public action`, `steps`, `summary` |
+| `abandon` | `agent description`, `event name`, `moves`, `public action`, `steps`, `summary` |
 
 # threshold_pool
 
@@ -1977,20 +3310,111 @@ Source: [`std/money_flows/threshold_pool.hsx`](../../../std/money_flows/threshol
 
 ## Parameters
 
-- `contributor: optional<party>`
-- `beneficiary: optional<party>`
-- `target: money<C>`
-- `commitment: money<C>`
-- `max_contributors: optional<integer>`
-- `close_by: date`
-- `close_policy: optional<text>`
-- `overfund_policy: optional<text>`
-- `cancel_policy: optional<text>`
-- `fail_policy: optional<text>`
-- `beneficiary_account: optional<account<C>>`
-- `memo: optional<text>`
-- `contribution_instrument: optional<block>`
-- `wording: optional<block>`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `contributor` | `optional<party>` | No | The party representing individual contributors. |
+| `beneficiary` | `optional<party>` | No | The beneficiary party receiving the settled pool if the target is met. |
+| `target` | `money<C>` | Yes | Total target funding threshold in minor units of currency `C`. |
+| `commitment` | `money<C>` | Yes | Binding name for individual contributor commitment amounts. |
+| `max_contributors` | `optional<integer>` | No | Optional maximum count of admitted contributors. |
+| `close_by` | `date` | Yes | Stored date deadline by which the target must be met. |
+| `close_policy` | `optional<text>` | No | Policy determining pool close behavior (`threshold`). |
+| `overfund_policy` | `optional<text>` | No | Policy on commitments exceeding the target (`reject`). |
+| `cancel_policy` | `optional<text>` | No | Contributor withdrawal policy before close (`before_close`). |
+| `fail_policy` | `optional<text>` | No | Refund policy if the pool fails to hit target (`whole_commitment_refund`). |
+| `beneficiary_account` | `optional<account<C>>` | No | Optional direct account reference for the beneficiary. |
+| `memo` | `optional<text>` | No | Optional memo text stored on the pool. |
+| `contribution_instrument` | `optional<block>` | No | Optional custom contribution child instrument block. |
+| `wording` | `optional<block>` | No | Optional custom UI wording block. |
+| `funding_join` | `optional<block>` | No | funding_join configures the flat contribution-instrument mode for a priced obligation. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+All-or-nothing capital accumulation pool collecting commitments toward a target amount before a close deadline.
+
+### Purpose
+
+`threshold_pool` powers all-or-nothing crowdfunding, capital calls, collective purchasing, and consortium rounds.
+Multiple contributors pledge commitments toward a monetary `target`. Commitments sit in escrow until the pool
+reaches the target before `close_by` (activating and settling funds to the beneficiary), or fails (triggering full refunds).
+
+### Selection guidance
+
+- vs `rotating_pool`: `threshold_pool` is all-or-nothing fundraising where many contributors fund a single beneficiary.
+  `rotating_pool` is a peer savings circle where members contribute identically in each cycle and rotate who receives the pot.
+- vs `weighted_distribution`: `threshold_pool` pools funds inward from many contributors to one beneficiary.
+  `weighted_distribution` pays funds outward from one source pool to many weighted recipients.
+
+### Parameters
+
+- `contributor`: The party representing individual contributors.
+- `beneficiary`: The beneficiary party receiving the settled pool if the target is met.
+- `target`: Total target funding threshold in minor units of currency `C`.
+- `commitment`: Binding name for individual contributor commitment amounts.
+- `max_contributors`: Optional maximum count of admitted contributors.
+- `close_by`: Stored date deadline by which the target must be met.
+- `close_policy`: Policy determining pool close behavior (`threshold`).
+- `overfund_policy`: Policy on commitments exceeding the target (`reject`).
+- `cancel_policy`: Contributor withdrawal policy before close (`before_close`).
+- `fail_policy`: Refund policy if the pool fails to hit target (`whole_commitment_refund`).
+- `beneficiary_account`: Optional direct account reference for the beneficiary.
+- `memo`: Optional memo text stored on the pool.
+- `contribution_instrument`: Optional custom contribution child instrument block.
+- `wording`: Optional custom UI wording block.
+
+### Decision ports
+
+None. Lifecycle transitions (`activate`, `fail`, `close`) are driven by target threshold evaluation and the `close_by` date.
+
+### Example
+
+```hsx
+program capital_pool_example "Capital pool example"
+import { threshold_pool } from "std/money_flows"
+party contributor: person
+party company: business
+settlement round = threshold_pool {
+  contributor: contributor
+  beneficiary: company
+  target: targetAmount: money(SAR)
+  commitment: commitmentAmount: money(SAR)
+  max_contributors: 100
+  close_by: closeBy
+  close_policy: threshold
+  overfund_policy: reject
+  cancel_policy: before_close
+  fail_policy: whole_commitment_refund
+}
+```
+
+### Funding join
+
+funding_join configures the flat contribution-instrument mode for a priced
+obligation. Opening freezes minimum ticket, investor cap, profit and schedule
+terms. Closing binds the obligation, freezes committed ticket identities and
+moves the principal once into its funding account. A ticket's engine-owned
+collection action has no independent payment or clock trigger.
+
+## Declared clauses
+
+- `agent description`
+- `aggregate invariants`
+- `caller parked states`
+- `description`
+- `due`
+- `examples`
+- `funding`
+- `id prefix`
+- `input`
+- `moves`
+- `steps`
+- `summary`
+- `title`
+- `updates`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -1998,20 +3422,20 @@ None.
 
 ## Actions and clauses
 
-| Action     | Clauses lowered                                   |
-| ---------- | ------------------------------------------------- |
-| `create`   | `agent description`, `moves`, `steps`, `summary`  |
-| `activate` | `due`, `moves`, `steps`, `summary`                |
-| `fail`     | `due`, `moves`, `steps`, `summary`                |
-| `close`    | `agent description`, `moves`, `steps`, `summary`  |
-| `create`   | `agent description`, `moves`, `steps`, `summary`  |
-| `cancel`   | `agent description`, `moves`, `steps`, `summary`  |
-| `collect`  | `agent description`, `moves`, `steps`, `summary`  |
-| `refund`   | `agent description`, `moves`, `steps`, `summary`  |
-| `create`   | `agent description`, `examples`, `moves`, `steps` |
-| `activate` | `due`, `examples`, `moves`, `steps`               |
-| `fail`     | `due`, `examples`, `moves`, `steps`               |
-| `close`    | `agent description`, `examples`, `moves`, `steps` |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `activate` | `due`, `moves`, `steps`, `summary` |
+| `fail` | `due`, `moves`, `steps`, `summary` |
+| `close` | `agent description`, `moves`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `cancel` | `agent description`, `moves`, `steps`, `summary` |
+| `collect` | `agent description`, `moves`, `steps`, `summary` |
+| `refund` | `agent description`, `moves`, `steps`, `summary` |
+| `create` | `agent description`, `examples`, `moves`, `steps` |
+| `activate` | `due`, `examples`, `moves`, `steps` |
+| `fail` | `due`, `examples`, `moves`, `steps` |
+| `close` | `agent description`, `examples`, `funding`, `input`, `moves`, `steps`, `updates` |
 
 # weighted_distribution
 
@@ -2023,18 +3447,113 @@ Source: [`std/money_flows/weighted_distribution.hsx`](../../../std/money_flows/w
 
 ## Parameters
 
-- `source: party`
-- `recipient: party`
-- `amount: money<C>`
-- `record_at: date`
-- `weight: optional<money<C>>`
-- `max_recipients: optional<integer>`
-- `snapshot: optional<condition>`
-- `rounding_policy: optional<text>`
-- `withholding_policy: optional<text>`
-- `correction_policy: optional<text>`
-- `flat: optional<block>`
-- `id_prefix_override: optional<text>`
+| Parameter | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `source` | `optional<party>` | No | The funding party providing the distribution pool. |
+| `recipient` | `optional<party>` | No | The party representing entitled recipients. |
+| `amount` | `optional<money<C>>` | No | Total distribution pool in minor units of currency `C`. |
+| `record_at` | `optional<date>` | No | Date when entitlement eligibility is established. |
+| `weight` | `optional<money<C>>` | No | Binding name for individual recipient weight amounts. |
+| `max_recipients` | `optional<integer>` | No | Exact number of entitlement rows required before snapshotting. |
+| `snapshot` | `optional<condition>` | No | Port freezing the entitlement set against stored decision evidence. |
+| `rounding_policy` | `optional<text>` | No | Mathematical rounding policy (`largest_remainder`). |
+| `withholding_policy` | `optional<text>` | No | Tax or withholding policy (`refuse`). |
+| `correction_policy` | `optional<text>` | No | Error correction policy (`new_distribution`). |
+| `flat` | `optional<block>` | No | Optional flat distribution configuration block. |
+| `receipts` | `optional<block>` | No | receipts selects repeated distributions from immutable allocation receipts. |
+| `id_prefix_override` | `optional<text>` | No | Optional custom prefix for generated instrument IDs. |
+
+Required means required by the template signature. A selected mode may also need parameters marked optional; the guidance below describes those combinations.
+
+## Module guidance
+
+Frozen largest-remainder distribution splitting one pool across dynamic recipients by recorded weights.
+
+### Purpose
+
+`weighted_distribution` distributes dividend pools, creator royalties, liquidation proceeds, and investment returns.
+Child entitlement rows are recorded for each recipient with their respective weight. Once all recipients are recorded,
+an evidence-backed snapshot freezes the entitlement set. Each recipient is then paid their exact largest-remainder
+share such that all payouts sum exactly to `amount` without rounding leaks.
+
+### Selection guidance
+
+- vs `pooled_split`: `weighted_distribution` handles dynamic recipient rosters recorded as child rows and frozen
+  via snapshot. `pooled_split` hardcodes a fixed set of recipients and static percentages at definition time.
+- vs `settlement_batch`: `weighted_distribution` splits one funding pool out to many recipients.
+  `settlement_batch` aggregates many inbound charges and adjustments into a single net payout.
+
+### Parameters
+
+- `source`: The funding party providing the distribution pool.
+- `recipient`: The party representing entitled recipients.
+- `amount`: Total distribution pool in minor units of currency `C`.
+- `record_at`: Date when entitlement eligibility is established.
+- `weight`: Binding name for individual recipient weight amounts.
+- `max_recipients`: Exact number of entitlement rows required before snapshotting.
+- `snapshot`: Port freezing the entitlement set against stored decision evidence.
+- `rounding_policy`: Mathematical rounding policy (`largest_remainder`).
+- `withholding_policy`: Tax or withholding policy (`refuse`).
+- `correction_policy`: Error correction policy (`new_distribution`).
+- `flat`: Optional flat distribution configuration block.
+- `id_prefix_override`: Optional custom prefix for generated instrument IDs.
+
+### Decision ports
+
+- `snapshot`: Port freezing the entitlement set with an evidence reference, preventing further entries.
+
+### Example
+
+```hsx
+program weighted_distribution_example "Weighted distribution example"
+import { weighted_distribution } from "std/money_flows"
+party distribution_source: business
+party recipient: business
+settlement proceeds = weighted_distribution {
+  source: distribution_source
+  recipient: recipient
+  amount: distributableAmount: money(SAR)
+  weight: entitlementWeight: money(SAR)
+  max_recipients: 12
+  record_at: recordAt
+  snapshot: port snapshot_entitlements
+  rounding_policy: largest_remainder
+  withholding_policy: refuse
+  correction_policy: new_distribution
+}
+port snapshot_entitlements {
+  allowed: [distribution_source]
+  shape: { evidenceReference: text }
+}
+```
+
+### Receipt-backed distributions
+
+receipts selects repeated distributions from immutable allocation receipts.
+It names round, receipt, path, mode (cash or loss), fee_bps and vat_bps.
+The funding snapshot owns ticket weights and original wallet destinations.
+Cash floors each ratio after fee and fee VAT; a named account receives residual.
+Loss assigns principal by largest remainder without cash, fee or VAT.
+Each receipt is consumed once; a new receipt may fund a new distribution record.
+This mode does not use caller-entered weights or a once-only settled principal pool.
+
+## Declared clauses
+
+- `agent description`
+- `aggregate invariants`
+- `capture input`
+- `description`
+- `due`
+- `id prefix`
+- `input`
+- `moves`
+- `port`
+- `requires refs`
+- `steps`
+- `summary`
+- `title`
+
+This inventory covers all branches and nested instruments in the module. The selected parameters determine which clauses and actions the compiler emits. Indexed action names expand over the declared finite list.
 
 ## Decision ports
 
@@ -2042,42 +3561,67 @@ Source: [`std/money_flows/weighted_distribution.hsx`](../../../std/money_flows/w
 
 ## Actions and clauses
 
-| Action     | Clauses lowered                                                                                   |
-| ---------- | ------------------------------------------------------------------------------------------------- |
-| `create`   | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `snapshot` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
-| `create`   | `agent description`, `moves`, `steps`, `summary`                                                  |
-| `payout`   | `agent description`, `computes distribute`, `moves`, `steps`, `summary`                           |
-| `create`   | `agent description`, `moves`, `requires refs`, `steps`, `summary`                                 |
-| `payout`   | `computes distribute`, `due`, `moves`, `steps`, `summary`                                         |
+| Action | Clauses lowered |
+| --- | --- |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `[snapshot]` | `agent description`, `capture input`, `description`, `input`, `moves`, `port`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `steps`, `summary` |
+| `payout` | `agent description`, `moves`, `steps`, `summary` |
+| `create` | `agent description`, `moves`, `requires refs`, `steps`, `summary` |
+| `payout` | `due`, `moves`, `steps`, `summary` |
+| `create` | `agent description`, `steps` |
 
 # Types
 
 HSX checks types before it emits UDL. Money and account values carry a currency parameter, and no implicit currency conversion exists.
 
-| Kind        | Meaning                                                              |
-| ----------- | -------------------------------------------------------------------- |
-| `account`   | A currency-indexed ledger account reference.                         |
-| `boolean`   | A compile-time or stored true or false value.                        |
-| `bps`       | An integer basis-point value.                                        |
-| `condition` | A declared decision port.                                            |
-| `date`      | A stored date-time string checked by UDL.                            |
-| `integer`   | A bounded whole number.                                              |
-| `money`     | A currency-indexed minor-unit amount.                                |
-| `party`     | A declared program party.                                            |
-| `percent`   | An exact percentage with basis-point precision.                      |
-| `ref`       | A typed reference to another instrument.                             |
-| `text`      | A finite string value.                                               |
-| `unknown`   | An internal checker result that source must resolve before lowering. |
+| Kind | Meaning |
+| --- | --- |
+| `account` | A currency-indexed ledger account reference. |
+| `boolean` | A compile-time or stored true or false value. |
+| `bps` | An integer basis-point value. |
+| `condition` | A declared decision port. |
+| `date` | A stored date-time string checked by UDL. |
+| `integer` | A bounded whole number. |
+| `money` | A currency-indexed minor-unit amount. |
+| `party` | A declared program party. |
+| `percent` | An exact percentage with basis-point precision. |
+| `ref` | A typed reference to another instrument. |
+| `text` | A finite string value. |
+| `unknown` | An internal checker result that source must resolve before lowering. |
+
+## Account fields
+
+When declaring fields of type `account<C>`, the HSX compiler automatically lowers the field schema with the UDL2002 account pattern (`^acct_(sandbox|live)_[a-z0-9]{8,64}$`). Authors do not need to write an explicit `pattern` clause on account fields.
+
+```hsx
+fields {
+  customerAccountId {
+    type: account<SAR>;
+    "x-hyperscale-reference-filter": { column: role; values: [customer_balance]; };
+  }
+  amount: money<SAR>;
+}
+```
+
+The account type pins the currency and identifier shape. The reference filter
+pins the allowed ledger roles. Product admission requires every account field
+to declare a non-empty role list. Choose roles that match the accounts the
+program will use; `customer_balance` is the role in this example.
+
+Use the quoted `"x-hyperscale-reference-filter"` key inside the field block,
+with `column: role` and `values: [...]`. There is no shorter role annotation.
+A bare `customerAccountId: account<SAR>;` compiles as HSX but does not satisfy
+the host's account-role admission law.
 
 # UDL output
 
 An accepted compile returns three artifacts.
 
-| Artifact       | Contents                                                                            |
-| -------------- | ----------------------------------------------------------------------------------- |
-| `document`     | The canonical UDL object. Serialize it with `serializeUdl` from `@hyperscale0/udl`. |
-| `originMap`    | Canonical UDL paths mapped to authored HSX spans.                                   |
-| `costManifest` | The deterministic manifest pinned to the supplied rate card.                        |
+| Artifact | Contents |
+| --- | --- |
+| `document` | The canonical UDL object. Serialize it with `serializeUdl` from `@hyperscale0/udl`. |
+| `originMap` | Canonical UDL paths mapped to authored HSX spans. |
+| `costManifest` | The deterministic manifest pinned to the supplied rate card. |
 
 Canonical UDL sorts object keys, preserves array order, uses two-space JSON indentation, and ends with one line feed.