From da7f62a3727b98ebf0f50ea3b8b0ce6b3dfa1684 Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Sun, 18 Jan 2026 11:30:43 -0500
Subject: [PATCH] Add signer adapter documentation

---
 README.md                   | 18 ++++++++++++++++++
 docs/auth-architecture.md   |  6 ++++++
 docs/nostr-event-schemas.md | 14 ++++++++++----
 3 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 2ee835c6..38a400f1 100644
--- a/README.md
+++ b/README.md
@@ -218,6 +218,24 @@ The legacy `js/nostr.js` shim has been removed. Update any remaining
 `import { ... } from './nostr.js';` calls to use the facades above so upgrades
 stay painless.
 
+### Signer Adapters
+
+bitvid exposes a stable signer API through `js/nostrClientFacade.js`, which
+wraps the shared client created in `js/nostr/defaultClient.js` and registers
+signer adapters in `js/nostr/client.js`. Import the facade whenever you need to
+sign events or encrypt payloads so the adapter registry can select the active
+signer, fall back to supported capabilities, and surface permission prompts.
+
+Use the facade for the common, stable entry points:
+
+```js
+import { nostrClient, requestDefaultExtensionPermissions } from "./nostrClientFacade.js";
+```
+
+Custom auth providers should still register their signer object through the
+adapter registry in `js/nostr/client.js`, but downstream modules should only
+call the facade to keep API surfaces consistent.
+
 ### Nostr video fetch limits
 
 `nostrClient.fetchVideos(options)` now accepts an optional `options.limit` to
diff --git a/docs/auth-architecture.md b/docs/auth-architecture.md
index 1aa4149c..33ea4077 100644
--- a/docs/auth-architecture.md
+++ b/docs/auth-architecture.md
@@ -125,6 +125,12 @@ implementation on the `nostrClient`. Remote signers and extensions must support
 those encryption methods for DM features to work, while local `nsec` signers can
 provide the primitives directly.
 
+Signing/encryption requests always flow through the signer adapter registry in
+`js/nostr/client.js` (accessed via `js/nostrClientFacade.js`). The registry
+selects the active signer, falls back to the strongest supported capability, and
+triggers permission prompts (for example, the NIP-07 extension handshake) before
+attempting privileged calls.
+
 ## Related docs
 
 - [`docs/nostr-auth.md`](nostr-auth.md)
diff --git a/docs/nostr-event-schemas.md b/docs/nostr-event-schemas.md
index 8344fb31..976ec556 100644
--- a/docs/nostr-event-schemas.md
+++ b/docs/nostr-event-schemas.md
@@ -67,10 +67,16 @@ await nostrClient.ensureExtensionPermissions();
 `setActiveSigner` accepts any object that implements the subset of capabilities
 you support. `nostrClient` (imported from the
 [NIP-07](https://github.com/nostr-protocol/nips/blob/master/07.md)-aligned
-`nostrClientFacade.js`) will prefer the registered signer for signing and
-encryption before falling back to session actors. Call `clearActiveSigner()` on
-logout if your integration manages session state manually; the built-in logout
-handler already does this for the default extension flow.
+`nostrClientFacade.js`) routes signing and encryption through the adapter
+registry in `js/nostr/client.js`, prefers the registered signer, and falls back
+to the strongest available capability (or session actors for telemetry) when a
+method is unavailable. Permission prompts are surfaced via
+`nostrClient.ensureExtensionPermissions()` or the
+`requestDefaultExtensionPermissions()` helper from
+`js/nostr/defaultClient.js`, so features can ask for access before issuing
+sign/encrypt calls. Call `clearActiveSigner()` on logout if your integration
+manages session state manually; the built-in logout handler already does this
+for the default extension flow.
 
 ### Accessing raw events