From 0fec9c4182f837cfdd09d28a25ca461e1ebea7ed Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Tue, 4 Aug 2026 09:41:17 -0400
Subject: [PATCH] Demo guide and llms.txt: document the extension sign-in
 method

The integration guide's bitlogin-login example now shows detail.method and
detail.capabilities, a callout explains the one-surface model and what an
extension session does and doesn't get, and the window.nostr claiming
section states the exception up front: NIP-07 sessions leave the slot to
the extension. Same facts mirrored in llms.txt.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/demo/public/docs.html | 18 ++++++++++++++++++
 packages/demo/public/llms.txt  | 13 ++++++++++++-
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/packages/demo/public/docs.html b/packages/demo/public/docs.html
index 2d0c46a..981294a 100644
--- a/packages/demo/public/docs.html
+++ b/packages/demo/public/docs.html
@@ -63,11 +63,25 @@
 
 bl.addEventListener('bitlogin-login', (e) => {
   console.log('signed in as', e.detail.publicKey);
+  console.log('via', e.detail.method); // 'bitlogin' | 'nip07'
+  console.log('supports', e.detail.capabilities); // { nip44, nip04, getRelays }
 });
 
 bl.addEventListener('bitlogin-logout', () => {
   console.log('signed out');
 });</code></pre>
+      <div class="callout">
+        <strong>One login surface, several methods.</strong> If the visitor's browser has a NIP-07 signer
+        extension (Alby, nos2x, …), the widget's welcome screen offers "Use your Nostr extension instead"
+        below the primary username/password sign-in — you embed one element and both kinds of users are
+        covered. <code>detail.method</code> tells you which way the user came in, and
+        <code>detail.capabilities</code> what the active signer supports (some extensions lack
+        <code>nip44</code>). Extension sessions are signer-only: signing and encryption work through the
+        element exactly the same, but BitLogin account features — wallet connections, password rotation,
+        identity export, cross-device persistence — belong to BitLogin accounts, and
+        <code>requestNwcConnection()</code> resolves <code>null</code>. A page reload ends an extension
+        session; the extension is simply asked again next visit.
+      </div>
     </li>
     <li>
       <h3>Sign events from anywhere on the page</h3>
@@ -171,6 +185,10 @@ if (window.bitlogin?.isActiveSigner()) {
         (as this demo does).
       </div>
       <h4 style="margin-top:20px">Letting a user switch away from BitLogin without reloading</h4>
+      <p>One exception first: when a user signs in <em>through</em> a NIP-07 extension from the widget's own
+      welcome screen, BitLogin deliberately leaves <code>window.nostr</code> alone — the extension already owns
+      the slot and is the session's actual backend, so there is nothing to claim or release. Everything below
+      concerns BitLogin-account sessions, where the widget's own provider competes for the slot.</p>
       <p>By default, once <code>&lt;bitlogin-auth&gt;</code> mounts it claims <code>window.nostr</code> and keeps it —
       even after the user logs out of BitLogin, since they might just be about to log back in with the same widget.
       If your site offers a signer picker and the user switches to a different method, call
diff --git a/packages/demo/public/llms.txt b/packages/demo/public/llms.txt
index 58db2bf..958a1c2 100644
--- a/packages/demo/public/llms.txt
+++ b/packages/demo/public/llms.txt
@@ -28,6 +28,16 @@ deployment above.
 - A `<bitlogin-auth>` custom element (Shadow DOM, no CSS collisions) handling
   create account, sign in, forgot-password recovery via a 12-word phrase, and
   password rotation.
+- One login surface, several methods: if the visitor's browser has a NIP-07
+  signer extension, the welcome screen offers "Use your Nostr extension
+  instead" below the primary username/password path, and the element routes
+  `getPublicKey`/`signEvent`/`nip44*`/`nip04*` through the extension for that
+  session. Extension sessions are signer-only: no vault
+  (`requestNwcConnection` resolves null), no persistence (a reload ends the
+  session), and `window.nostr` is left to the extension. `bitlogin-login`'s
+  `detail.method` (`'bitlogin' | 'nip07'`) and `detail.capabilities`
+  (`{ nip44, nip04, getRelays }`) tell your app which backend is active and
+  what it supports.
 - A `window.nostr` provider shaped like the de facto NIP-07 interface
   (`getPublicKey`, `signEvent`, `getRelays`, `nip44.encrypt`/`decrypt`) —
   existing Nostr app code that already calls `window.nostr` works unmodified,
@@ -62,7 +72,8 @@ deployment above.
   'saved' | 'declined' | 'already-saved' (same wallet+secret exists; origin
   binding refreshed, no UI) | 'unavailable' (no session/vault — treat as
   no-op). Safe to fire after every successful connect.
-- Events on the element: `bitlogin-login` (`detail.publicKey`),
+- Events on the element: `bitlogin-login` (`detail.publicKey`,
+  `detail.method`, `detail.capabilities`),
   `bitlogin-logout`, `bitlogin-signer-claimed`, `bitlogin-signer-released`
   (the last also fires on `window` when triggered via
   `window.bitlogin.releaseSigner()`), `bitlogin-connection-granted`