docs: vowTools

packages/vow/README.md

@@ -27,7 +27,7 @@ Here they are: {
 ```
 
 You can use `heapVowE` exported from `@agoric/vow`, which converts a chain of
-promises and vows to a promise for its final fulfilment, by unwrapping any
+promises and vows to a promise for its final fulfillment, by unwrapping any
 intermediate vows:
 
 ```js
@@ -77,6 +77,67 @@ const { watch, makeVowKit } = prepareVowTools(vowZone);
 // Vows and resolvers you create can be saved in durable stores.
 ```
 
+## VowTools
+
+VowTools are a set of utility functions for working with Vows in Agoric smart contracts and vats. These tools help manage asynchronous operations in a way that's resilient to vat upgrades, ensuring your smart contract can handle long-running processes reliably.
+
+### Usage
+
+VowTools are typically prepared in the start function of a smart contract or vat and passed in as a power to exos.
+
+
+```javascript
+import { prepareVowTools } from '@agoric/vow/vat.js';
+import { makeDurableZone } from '@agoric/zone/durable.js';
+
+export const start = async (zcf, privateArgs, baggage) => {
+  const zone = makeDurableZone(baggage);
+  const vowTools = prepareVowTools(zone.subZone('vows'));  
+
+  // Use vowTools here...
+}
+```
+
+### Available Tools
+
+#### `when(vowOrPromise)`
+Waits for a Vow or Promise to resolve and returns its value.  It can't handle disconnections due to vat upgrades.
+
+#### `watch(promiseOrVow, [watcher], [context])`
+Watch a Vow and optionally provide a `watcher` with `onFulfilled`/`onRejected` handlers and a `context` value for the handlers. When handlers are not provided the fulfillment or rejection will simply pass through.
+
+Also converts a Promise into a Vow which can survive vat upgrades.
+
+#### `all(arrayOfVowsOrPassables, [watcher], [context])`
+Vow-tolerant implementation of Promise.all that takes an iterable of vows and other Passables and returns a single Vow.  It resolves with an array of values when all of the input's promises or vows are fulfilled and rejects when any of the input's promises or vows are rejected with the first rejection reason.
+
+#### `allSettled(arrayOfVowsOrPassables, [watcher], [context])`
+Vow-tolerant implementation of Promise.allSettled that takes an iterable of vows and other Passables and returns a single Vow.  It resolves when all of the input's promises or vows are settled with an array of settled outcome objects.
+
+#### `asVow(fn)`
+Takes a function that might return synchronously, throw an Error, or return a Promise or Vow and returns a Vow.
+
+#### `asPromise(vow)`
+Converts a Vow back into a Promise.
+
+### Example
+
+```javascript
+const { when, watch, all, allSettled } = vowTools;
+
+// Using watch to create a Vow
+const myVow = watch(someAsyncOperation());
+
+// Using when to resolve a Vow
+const result = await when(myVow);
+
+// Using all
+const results = await when(all([vow, vowForVow, promise]));
+
+// Using allSettled
+const outcomes = await when(allSettled([vow, vowForVow, promise]));
+```
+
 ## Internals
 
 The current "version 0" vow internals expose a `shorten()` method, returning a