Add signer adapter documentation

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

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)

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