refactor: Use better sections for E(zoe).offer

...and link to them from the Zoe Offers guide and the Glossary

main/glossary/README.md

@@ -230,10 +230,8 @@ See [`E()`](#e) above.
 
 ## Exit Rule
 
-Part of an [offer](#offer) specifying how the offer can be cancelled/exited. There are three values:
-- `onDemand: null`: (Default) The offering party can cancel on demand.
-- `waived: null`: The offering party can't cancel and relies entirely on the smart contract to promptly finish their offer.
-- `afterDeadline: {…}`: The offer is automatically cancelled after a deadline, as determined by its `timer` and `deadline` properties. See [Proposals and payments](/reference/zoe-api/zoe.md#proposals-and-payments).
+An object specifying how an [offer](#offer) can be cancelled, such as on demand or by a deadline.
+For details, see [`E(zoe).offer(...)`](/reference/zoe-api/zoe.md#proposals).
 
 ## Facet
 
@@ -412,7 +410,7 @@ to the amount in the proposal they're willing to give. The payments are automati
 according to the contract code. An offer gets a [payout](#payout) of some combination of what the party originally contributed
 and what others have contributed. The specific payout is determined by the contract code.
 
-See [`E(Zoe).offer(invitation, proposal, paymentKeywordRecord, offerArgs)`](/reference/zoe-api/zoe.md#e-zoe-offer-invitation-proposal-paymentkeywordrecord-offerargs).
+See [Offers](/guides/zoe/proposal.md).
 
 ## Offer Safety
 
@@ -463,18 +461,20 @@ For more information, see the [JavaScript Distributed Programming Guide](/guides
 
 ## Proposal
 
-Proposals are records with `give`, `want`, and `exit` properties. [Offers](#offer) must include a proposal, which states
-what asset you want, what asset you will give for it, and how/when the offer maker can cancel the offer
-(see [Exit Rule](#exit-rule) for details on the last). For example:
+Proposals are records with `give`, `want`, and/or `exit` properties respectively
+expressing [offer](#offer) conditions regarding what assets will be given, what
+must be received in exchange, and an [exit rule](#exit-rule) defining how/when
+the offer can be canceled. For example:
 ```js
 const myProposal = harden({
-  give: { Asset: AmountMath.make(quatloosBrand, 4)},
-  want: { Price: AmountMath.make(moolaBrand, 15) },
-  exit: { onDemand: null }
-})
+  give: { Asset: AmountMath.make(quatloosBrand, 4n) },
+  want: { Price: AmountMath.make(moolaBrand, 15n) },
+  exit: { onDemand: null },
+});
 ```
-`give` and `want` use [keywords](#keyword) defined by the contract. Each specifies via an [amount](#amount) a description of what
-they are willing to give or want to get.
+`give` and `want` each associate [Keywords](#keyword) defined by the contract with corresponding [Amounts](#amount) describing what will be respectively given or received.
+
+See [Offers](/guides/zoe/proposal.md).
 
 ## Purse
 

main/guides/zoe/proposal.md

@@ -23,46 +23,50 @@ There are two main ways for contract users to get an `invitation`:
 
 ## Proposals
 
-Proposals are records with **give**, **want**, and **exit** keys.
+Proposals are records with **give**, **want**, and/or **exit** keys.
 
 ```js
 const myProposal = harden({
-  give: { Asset: AmountMath.make(quatloosBrand, 4n)},
+  give: { Asset: AmountMath.make(quatloosBrand, 4n) },
   want: { Price: AmountMath.make(moolaBrand, 15n) },
   exit: { onDemand: null },
-})
+});
 ```
-**give** and **want** use keywords defined by the contract.
-Keywords are unique identifiers per contract, that tie together the proposal,
-payments to be escrowed, and payouts to the user.
-In the example above, **Asset** and **Price** are the keywords. However, in an auction contract,
-the keywords might be **Asset** and **Bid**.
-
-The `AmountMath.make(quatloosBrand, 4n)` is just making an ERTP `amount`, or description of digital assets.
-In this case, 4 of our imaginary Quatloos currency. `AmountMath.make(moolaBrand, 15n)` is making 
-an `amount` of 15 of our imaginary Moola currency. (The appended "n" indicates that the numbers are
-represented as `BigInts` rather than `Numbers`)
-
-**Note**: It's important to understand that `amounts` are just descriptions of assets with no
-intrinsic value. `payments` hold actual digital assets.
-
-`exit` determines how an offer can be can cancelled:
-- `onDemand: null`: (Default) The offering party can cancel on demand.
-- `waived: null`: The offering party can't cancel and relies entirely on the smart contract to promptly finish their offer.
-- `afterDeadline: {…}`: The offer is automatically cancelled after a deadline,
-  as determined by its `timer` and `deadline` properties. See
-  [Proposals and payments](/reference/zoe-api/zoe.md#proposals-and-payments).
+**give** and **want** use [Keywords](/reference/zoe-api/zoe-data-types.md#keyword) defined by the contract.
+Keywords are unique identifiers per contract, that tie together proposals,
+payments to be escrowed, and payouts to users.
+In the example above, "Asset" and "Price" are the Keywords. However, in an auction contract,
+the Keywords might be "Asset" and "Bid".
+
+Each `AmountMath.make` call above is just making an ERTP [Amount](/reference/ertp-api/ertp-data-types.html#amount), or description of digital assets.
+In this case, `AmountMath.make(quatloosBrand, 4n)` creates a description of 4 units
+of our imaginary Quatloos currency and `AmountMath.make(moolaBrand, 15n)` creates a description
+of 15 units of our imaginary Moola currency. (The "n" appended after each number indicates that
+it is represented as a [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)
+rather than a [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))
+
+::: warning Note
+It's important to understand that Amounts are just descriptions of assets with no
+intrinsic value. [Payments](/reference/ertp-api/payment.html) hold actual digital assets.
+:::
+
+**exit** specifies how the offer can be can cancelled. It must conform to one of three shapes:
+- `{ onDemand: null }`: (Default) The offering party can cancel on demand.
+- `{ waived: null }`: The offering party can't cancel and relies entirely on the smart contract to promptly finish their offer.
+- `{ afterDeadline: deadlineDetails }`: The offer is automatically cancelled after a deadline,
+  as determined by its `timer` and `deadline` properties.
+
+For more details, see [Proposals](/reference/zoe-api/zoe.md#proposals).
 
 ## Escrowed Payments
 
-Using the same keywords as your `proposal`, you must specify a [PaymentKeywordRecord](/reference/zoe-api/zoe-data-types.md#keywordrecord).
-This is a record with the keywords as keys, and `payments` containing digital assets as
-values. Zoe escrows these `payments` on behalf of this offer until the offer is completed
-or rejected or the assets are reassigned to another offer. 
+Using the same Keywords as the **give** object in your **proposal**, you must specify a [PaymentKeywordRecord](/reference/zoe-api/zoe-data-types.md#keywordrecord) containing [Payments](/reference/ertp-api/payment.html) of the corresponding digital assets.
+Zoe escrows these payments on behalf of your offer until it is completed
+or rejected or the assets are reassigned to another offer.
 ```js
-const paymentKeywordRecord = { 
-  'Asset' : quatloosPayment, 
-  'Price' : moolaPayment 
+const payments = {
+  Asset: quatloosPayment,
+  Price: moolaPayment,
 };
 ```
 
@@ -80,7 +84,5 @@ before being used since they are coming directly from the user and may have mali
 
 ## Returned Value
 
-`offer()` returns a `UserSeat` object. Its name comes from the concept of "having a seat at the table" 
-for the contract's execution. 
-
-
+`E(zoe).offer(...)` returns a promise for a `UserSeat` object. Its name comes from the concept of
+"having a seat at the table" for the contract's execution.

main/reference/zoe-api/zoe.md

@@ -293,66 +293,56 @@ const { creatorFacet, publicFacet, creatorInvitation } = await E(Zoe).startInsta
 - **offerArgs**: **[CopyRecord](/glossary/#passable)** - Optional.
 - Returns: **Promise<[UserSeat](./user-seat.md)>**
 
-Used to make an offer to the contract that created the **Invitation** that is
-provided as the first argument.
+Used to make an offer to the contract that created the **invitation**.
 
-### Proposals and Payments
+<a name="proposals-and-payments"></a>
+### Proposals
 
-The invocation normally includes a **proposal** (the
-rules under which they want to exercise the offer) and **payments** that correspond 
-to the **give** property of the **proposal**. The payments will be escrowed by Zoe. If
-either the **proposal** or **payments** are empty, indicate this by
-omitting that argument or passing **undefined**, instead of passing an
-empty record.
-
-The optional **exit**'s value should be an **exitRule**, an object with three possible keys for
-key:value pairs:
-
-- **onDemand: null**: (Default) The offering party can cancel on demand.
-- **waived: null**: The offering party can't cancel and relies entirely on the smart contract to promptly finish their offer.
-- **afterDeadline**: The offer is automatically cancelled after a deadline, as determined 
-  by its **timer** and **deadline** properties.
-  **timer** must be a timer, and **deadline** must be a [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) value interpreted with respect to the timer.
-  Some example timers use Unix epoch time, while others count block height.
+**proposal** must be either `undefined` or a record with **give**, **want**, and/or **exit** properties
+respectively expressing conditions regarding what assets will be given, what must be
+received in exchange, and an exit rule defining how/when the offer can be canceled.
 
 ```js
 const myProposal = harden({
-  give: { Asset: quatloos(4n)},
-  want: { Price: moola(15n) },
-  exit: { afterDeadline: {
-    timer,
-    deadline: 100n
-  }}
-})
+  give: { Asset: AmountMath.make(quatloosBrand, 4n) },
+  want: { Price: AmountMath.make(moolaBrand, 15n) },
+  exit: { onDemand: null },
+});
 ```
 
-**paymentKeywordRecord** is a record with **[Keywords](./zoe-data-types.md#keyword)** as keys and with
- values of the actual **payments** to be escrowed. A **payment** is
- expected for every entry under **give**.
+**give** and **want** use **[Keywords](./zoe-data-types.md#keyword)** defined by the contract.
+In the example above, "Asset" and "Price" are the Keywords. However, in an auction contract,
+the Keywords might be "Asset" and "Bid".
 
- **offer()** returns a promise for a **UserSeat**.
-
-```js
-const paymentKeywordRecord = {
-  Asset : quatloosPayment,
-  Price : moolaPayment
-};
-```
+**exit** specifies how the offer can be can cancelled. It must conform to one of three shapes:
+- `{ onDemand: null }`: (Default) The offering party can cancel on demand.
+- `{ waived: null }`: The offering party can't cancel and relies entirely on the smart contract to promptly finish their offer.
+- `{ afterDeadline: deadlineDetails }`: The offer is automatically cancelled after a deadline,
+  as determined by its **timer** and **deadline** properties.
+  **timer** must be a timer, and **deadline** must be a [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) value interpreted with respect to the timer.
+  Some timers use Unix epoch time, while others count block height.
+  For more details, see [Timer Services](/reference/repl/timerServices.md).
+
+### Payments
 
-### OfferArgs
+**paymentKeywordRecord** must be either `undefined` or a **[PaymentKeywordRecord](./zoe-data-types.md#keywordrecord)**
+containing the actual **payments** to be escrowed by Zoe.
+Every **Keyword** in **give** must also have a corresponding **payment**.
 
-*offerArgs* is an object that can be used to pass
-additional arguments to the **offerHandler** contract code associated
-with the invitation. Which arguments should be included within *offerArgs* is determined by the
-contract in question; each contract can define whatever additional arguments it requires. If no
-additional arguments are defined for a particular contract, then the *offerArgs* argument can be
-omitted entirely. It is up to the contract code how it chooses to handle any unexpected or missing
-arguments within *offerArgs*.
+```js
+const paymentKeywordRecord = harden({
+  Asset: quatloosPayment,
+  Price: moolaPayment,
+});
+```
 
+<a href="offerargs"></a>
+### Offer Arguments
 
-Contract code should be careful interacting with *offerArgs*. These values need input validation
-before being used by the contract code since they are coming directly from the user and may
-have malicious behavior.
+**offerArgs** is an object that can be used to pass additional arguments to the
+**offerHandler** contract code associated with the invitation by
+[`zcf.makeInvitation(...)`](./zoe-contract-facet.md#zcf-makeinvitation-offerhandler-description-customproperties-proposalshape).
+Each contract can define the properties it supports and which are required.
 
 ## E(Zoe).installBundleID(bundleId)
 - bundleId: **BundleId**