From b2843bf7dcbc80fb8791ddedf3a42385579fe8c1 Mon Sep 17 00:00:00 2001
From: "Mark S. Miller" <erights@users.noreply.github.com>
Date: Tue, 12 Mar 2024 15:18:46 -0700
Subject: [PATCH] doc(ses-ava): update README (#2137)

---
 packages/ses-ava/README.md | 45 ++++++++++++++++++++++++++++++--------
 1 file changed, 36 insertions(+), 9 deletions(-)

diff --git a/packages/ses-ava/README.md b/packages/ses-ava/README.md
index 5f0250f5eb..1ebe278a53 100644
--- a/packages/ses-ava/README.md
+++ b/packages/ses-ava/README.md
@@ -1,19 +1,46 @@
-# ses-ava
+# `@endo/ses-ava`
 
-*SES-Ava* can wrap Ava `test` functions such that errors are reported to the
-console in full detail.
-This compensates for how SES, with full error taming, only reveals stack traces
-to debugging tools.
+*SES-Ava* wraps Ava `test` functions and initializes the SES-shim with options
+suitable for debugging tests. This includes logging errors to the console with
+- deep stacks of prior turns
+- unredacted stack traces
+- unredacted error messages
 
-To use this module, create an Ava module wrapper in your target project.
+To use this module, in your Ava test files, replace
 
 ```js
+import 'ses'; // or however you initialize the SES-shim
+import test from 'ava';
+```
+with
+```js
+import test from '@endo/ses-ava/prepare-endo.js';
+```
+and add
+```json
+  "devDependencies": {
+    // ...
+    "@endo/ses-ava": "...", // for the current version of @endo/ses-ava
+    // ...
+  },
+```
+specifically to "devDependencies". @endo/ses-ava itself depends on Ava as
+a regular dependency, so it you include @endo/ses-ava as a regular
+dependency, bundlers might bundle your code with all of Ava.
+
+SES-Ava rhymes with Nineveh.
+
+## Compat note
+
+If you were already using `@endo/ses-ava` by doing
+
+```js
+import 'ses'; // or however you initialize the SES-shim
 import rawTest from 'ava';
 import { wrapTest } from '@endo/ses-ava';
 
 const test = wrapTest(rawTest);
 ```
 
-Then, import your test wrapper instead of Ava in your tests.
-
-SES-Ava rhymes with Nineveh.
+that code will continue to work. But it should be upgraded to the above
+pattern if possible.