@hyperscale0/hsx 2.1.1 → 2.2.1

package/docs/reference/std/conditional_disbursement.md

@@ -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. -->
 
 # conditional_disbursement
 
@@ -10,13 +10,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
 
@@ -24,10 +92,10 @@ 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` |

package/docs/reference/std/credit_facility.md

@@ -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. -->
 
 # credit_facility
 
@@ -10,15 +10,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
 
@@ -26,10 +99,10 @@ 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` |

package/docs/reference/std/held_payment.md

@@ -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. -->
 
 # held_payment
 
@@ -10,22 +10,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
 
@@ -33,41 +133,41 @@ 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` |

package/docs/reference/std/instant_transfer.md

@@ -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. -->
 
 # instant_transfer
 
@@ -10,11 +10,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
 
@@ -22,9 +89,9 @@ 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` |