diff --git a/diigo-cache/src/pm-save.ts b/diigo-cache/src/pm-save.ts
index 6d71131..edcfb13 100644
--- a/diigo-cache/src/pm-save.ts
+++ b/diigo-cache/src/pm-save.ts
@@ -1,13 +1,4 @@
-/**
- * @file the password-manager save — ids reach the browser's storage only by
- * this gesture-gated path (or copy), never localStorage/IndexedDB, which
- * are ambient and XSS-reachable. It runs in the *browser*: pages embed it
- * via `pmSave.toString()`, so it must be self-contained (no imports, no
- * closure, no inner named functions — wrangler's keepNames would wrap
- * those in an `__name` helper the browser doesn't have). Its powers
- * (the petname field, the credential store, the console) are passed in,
- * so tests can stand in for the browser.
- */
+/** @file the password-manager save, run in the browser (embedded via `pmSave.toString()`). */
 
 /** the browser powers pmSave uses */
 export type PmPowers = {
@@ -22,7 +13,14 @@ export type PmButton = { textContent: string | null; disabled: boolean };
 
 /**
  * gesture-gated save of `value` under the holder's petname (the PM
- * username).
+ * username). Ids reach the browser's storage only this way (or by copy),
+ * never localStorage/IndexedDB, which are ambient and XSS-reachable.
+ *
+ * Pages embed it with `pmSave.toString()`, so it must be self-contained:
+ * no imports, no closures, no inner named functions (wrangler's keepNames
+ * would wrap those in an `__name` helper the browser lacks). Its powers
+ * (petname field, credential store, console) are passed in, so tests can
+ * stand in for the browser.
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/CredentialsContainer/store
  */
diff --git a/diigo-cache/src/webkeys.ts b/diigo-cache/src/webkeys.ts
index 1df46ba..d9b0194 100644
--- a/diigo-cache/src/webkeys.ts
+++ b/diigo-cache/src/webkeys.ts
@@ -1,30 +1,4 @@
-/**
- * @file webkeys: URL-borne bearer permissions, per Tyler Close's
- * ["web-key: Mashing with permission"](https://waterken.sourceforge.net/web-key/)
- * (IEEE W2SP 2008); the design abstract lives in
- * [docs/webkeys.md](../../docs/webkeys.md), with the Waterken precursor
- * code in `kpreid/e-on-java` as provenance (YURL32 = `org.waterken.uri.
- * Base32` / `BigIntegerSugar.toYURL32`; bearer invariant = `EARL.java`;
- * identity-without-authority = `SwissTable`'s swissHash).
- *
- * A webkey separates secret from address:
- * - the **secret bits**: supplied directly by the caller as a Worker
- *   unique ID (e.g. `DurableObjectId` from `ns.newUniqueId()`), or raw
- *   bytes (`Uint8Array`). Per [OCap discipline]
- *   (.opencode/skills/ocap-discipline/SKILL.md), functions here are pure:
- *   no ambient RNG calls, no callback indirection. The caller holds the
- *   minting authority at the application boundary and supplies the result.
- * - the **encoding**: YURL32 — lowercase `a–z` + `2–7`, 5 bits/char,
- *   URL-safe by construction (no `-`, no `_`, no case to misread).
- *
- * Cloudflare Worker `DurableObjectId`s are 256 bits (32 bytes), rendered
- * as 64 hex characters by `id.toString()`. {@link toWebkey} encodes that
- * ID into 52 YURL32 glyphs; {@link idFromWebkey} decodes it back to the
- * 64-hex string expected by `ns.idFromString()`.
- *
- * {@link shashKey} gives the identity-without-authority twin (the
- * swissHash discipline) for log-correlation: one-way, on SHA-256.
- */
+/** @file webkeys: URL-borne bearer keys, YURL32-encoded; see {@link toWebkey}. */
 
 /** the YURL32 alphabet: `a–z` then `2–7` (32 glyphs, 5 bits each) */
 const YURL32_ALPHABET = "abcdefghijklmnopqrstuvwxyz234567" as const;
@@ -125,6 +99,20 @@ export type WorkerUniqueId = DurableObjectIdLike | Uint8Array;
 /**
  * Convert a Worker unique ID (or raw bytes) to a YURL32 webkey string.
  *
+ * A webkey separates secret from address. The secret bits are supplied by
+ * the caller (a `DurableObjectId` from `ns.newUniqueId()`, or raw bytes):
+ * these functions are pure, with no ambient RNG; the caller holds the
+ * minting authority. The encoding is YURL32: lowercase `a–z` + `2–7`,
+ * 5 bits per glyph, URL-safe by construction. A 256-bit `DurableObjectId`
+ * (64 hex characters) becomes 52 glyphs; {@link idFromWebkey} decodes it
+ * back for `ns.idFromString()`.
+ *
+ * Provenance: Tyler Close's web-key (IEEE W2SP 2008) and the Waterken code
+ * in `kpreid/e-on-java` (YURL32 = `org.waterken.uri.Base32`); the design
+ * abstract is docs/webkeys.md.
+ *
+ * @see https://waterken.sourceforge.net/web-key/
+ *
  * @param id A `DurableObjectId` (from `ns.newUniqueId()`), a 64-char hex ID,
  * or raw bytes (`Uint8Array`).
  * @returns A YURL32 webkey string (52 glyphs for 256-bit `DurableObjectId`,