From 7b4f0063979d2fbf292164edd417cec565560d02 Mon Sep 17 00:00:00 2001
From: Chris Hibbert <hibbert@agoric.com>
Date: Tue, 21 Jan 2025 12:49:27 -0800
Subject: [PATCH 1/2] docs: update on zoe.installBundle and zoe.installBundleId

---
 main/reference/zoe-api/zoe.md | 32 ++++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/main/reference/zoe-api/zoe.md b/main/reference/zoe-api/zoe.md
index b7dedae38..709c20fea 100644
--- a/main/reference/zoe-api/zoe.md
+++ b/main/reference/zoe-api/zoe.md
@@ -141,13 +141,16 @@ const invitation = await invitationIssuer.claim(untrustedInvitation);
 const invitationValue = await E(Zoe).getInvitationDetails(invitation);
 ```
 
-## E(Zoe).install(bundle)
+## E(Zoe).install(bundle, bundleLabel?)
 
 - **bundle**: **SourceBundle**
+- **bundleLabel**: string - Optional
 - Returns: **Promise&lt;Installation>**
 
-Takes bundled source code for a Zoe contract as an argument and installs the code on Zoe.
-Returns a **Promise** for an **Installation** object.
+Takes bundled source code for a Zoe contract as an argument and
+installs the code with Zoe. The _bundleLabel_ will be accessible on the
+**Installation** object. Returns a **Promise** for an **Installation**
+object.
 
 ```js
 // bundleSource takes source code files and
@@ -157,6 +160,22 @@ const bundle = await bundleSource(pathResolve(`./src/contract.js`));
 const installationP = await E(Zoe).install(bundle);
 ```
 
+## E(Zoe).installBundleID(bundleId, bundleLabel?)
+
+- **bundleId**: **BundleId**
+- **bundleLabel**: string - Optional
+- Returns: **Promise&lt;Installation>**
+
+Takes a bundleId for a Zoe contract (often generated in a [coreEval
+proposal](/guides/coreeval/local-testnet.html#deploying-contracts-using-core-eval-proposals)
+as an argument and installs the code with Zoe. The _bundleLabel_ will be
+accessible on the **Installation** object. Returns a **Promise** for
+an **Installation** object.
+
+```js
+const installationP = await E(Zoe).installBundleID(bundleId, bundleLabel);
+```
+
 ## E(Zoe).getConfiguration()
 
 - Returns: **Promise&lt;Object>**
@@ -406,13 +425,6 @@ const paymentKeywordRecord = harden({ Asset: quatloosPayment });
 [`zcf.makeInvitation(...)`](./zoe-contract-facet#zcf-makeinvitation-offerhandler-description-customdetails-proposalshape).
 Each contract can define the properties it supports and which are required.
 
-## E(Zoe).installBundleID(bundleId)
-
-- bundleId: **BundleId**
-- Returns: **Promise&lt;Installation>**
-
-Reserved for future use.
-
 ## E(Zoe).getBundleIDFromInstallation(installation)
 
 - **installation**: **Installation**

From a21365f47452ec796fba03a7742540e1b3524ba5 Mon Sep 17 00:00:00 2001
From: Chris Hibbert <hibbert@agoric.com>
Date: Tue, 21 Jan 2025 17:27:14 -0800
Subject: [PATCH 2/2] docs: improved wording and links

---
 main/reference/zoe-api/zoe.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/main/reference/zoe-api/zoe.md b/main/reference/zoe-api/zoe.md
index 709c20fea..30076a021 100644
--- a/main/reference/zoe-api/zoe.md
+++ b/main/reference/zoe-api/zoe.md
@@ -147,10 +147,11 @@ const invitationValue = await E(Zoe).getInvitationDetails(invitation);
 - **bundleLabel**: string - Optional
 - Returns: **Promise&lt;Installation>**
 
-Takes bundled source code for a Zoe contract as an argument and
-installs the code with Zoe. The _bundleLabel_ will be accessible on the
-**Installation** object. Returns a **Promise** for an **Installation**
-object.
+Create an installation by safely evaluating the code and registering it with Zoe. Returns a **Promise** for an
+**Installation** object. The _bundleLabel_ will be accessible on the Installation using
+`E(anInstallation).getBundleLabel()`.
+
+`E(zoe).install()` is seldom used outside of test contexts. Consider using `E(zoe).installBundleID()` instead.
 
 ```js
 // bundleSource takes source code files and
@@ -166,11 +167,10 @@ const installationP = await E(Zoe).install(bundle);
 - **bundleLabel**: string - Optional
 - Returns: **Promise&lt;Installation>**
 
-Takes a bundleId for a Zoe contract (often generated in a [coreEval
-proposal](/guides/coreeval/local-testnet.html#deploying-contracts-using-core-eval-proposals)
-as an argument and installs the code with Zoe. The _bundleLabel_ will be
-accessible on the **Installation** object. Returns a **Promise** for
-an **Installation** object.
+Takes a bundleId for a Zoe contract (generated using a [builder
+script](/guides/zoe/contract-walkthru#bundling-a-contract) as an argument and installs the code with Zoe.
+Returns a **Promise** for an **Installation** object. The _bundleLabel_ will be accessible on the Installation using
+`E(anInstallation).getBundleLabel()`.
 
 ```js
 const installationP = await E(Zoe).installBundleID(bundleId, bundleLabel);