feat(demo): read-only DEMO mode + clone-friction polish

- DEMO=true + DEMO_ADDR=sent1... boots a watch-only session on any
  operator address. Bech32 validated at boot. POST/PUT/DELETE return
  403 with a friendly "clone the repo" message so nothing can be
  signed by accident.
- /api/wallet/status now exposes demo:true; UI shows a topbar banner
  pointing visitors at the GitHub repo when running in demo.
- README: drop the npm-global install path (we are not publishing),
  replace docker-compose .env clobber with cp .env.example, add
  npx degit one-liner, and put a "just want to look around"
  demo-mode quickstart at the top.
- engines.node >=20 in package.json so older Node fails fast.
- gitignore: privy-wallets.json, .servererr.txt, .serverlog*.txt,
  social/ — runtime artifacts that should never be tracked.

Author: Sentinel-Autonomybuilder

.env.example

@@ -1,6 +1,13 @@
 MNEMONIC=your twelve or twenty four word cosmos sdk mnemonic here
 PORT=3003
 
+# Demo mode (optional). Set DEMO=true to boot the UI in read-only watch-only
+# mode mounted on DEMO_ADDR. Every TX-broadcasting endpoint returns 403 — no
+# mnemonic is read, no wallet is loaded. Ideal for "I just want to look at it"
+# previews you can publish to a public URL without exposing keys.
+DEMO=
+DEMO_ADDR=
+
 # Privy embedded-wallet login (optional). When both are set, the email/Privy
 # auth card on /login is enabled and /api/wallet/privy-login accepts access
 # tokens. Get these from https://dashboard.privy.io after creating an app.

.gitignore

@@ -5,11 +5,16 @@ wallet.json
 .session-key
 my-plans.json
 nodes-cache.json
+privy-wallets.json
 sellers.json
 an.json
 server.log
 boot.log
 *.log
+.servererr.txt
+.serverlog.txt
+.serverlog.err.txt
+social/
 *.jpg
 *.png
 CLAUDE.md

README.md

@@ -47,20 +47,31 @@ See [PLANS.md](./PLANS.md) for the full breakdown: plan lifecycle, plan-based vs
 
 > **This tool operates on Sentinel mainnet. Every transaction costs real P2P tokens. There is no testnet mode.**
 
-### Option A — npm (recommended, one-shot)
+### Just want to look around?
+
+Boot a read-only demo mounted on any operator address — no wallet, no tokens, no commitment. Every TX-broadcasting endpoint returns 403 so nothing can be signed by accident.
 
 ```bash
-npm install -g sentinel-plan-manager
-plans --help                                # verify install
-echo "MNEMONIC=word1 word2 ... word24" > .env
-npx sentinel-plan-manager                   # or: node $(npm root -g)/sentinel-plan-manager/server.js
+git clone https://github.com/Sentinel-Bluebuilder/sentinel-plan-manager.git
+cd sentinel-plan-manager
+npm install
+DEMO=true DEMO_ADDR=sent1...operator-address... npm start
+# → http://localhost:3003 with a demo banner across the top
 ```
 
-### Option B — git clone (for contributors)
+Pick any plan-creating operator address from a chain explorer, paste it into `DEMO_ADDR`, and the dashboard renders that operator's plans, nodes, and subscribers.
+
+### Run your own — Option A: clone
 
 ```bash
+# Without git history (fastest):
+npx degit Sentinel-Bluebuilder/sentinel-plan-manager plan-manager
+cd plan-manager
+
+# Or with full git history:
 git clone https://github.com/Sentinel-Bluebuilder/sentinel-plan-manager.git
 cd sentinel-plan-manager
+
 npm install
 cp .env.example .env    # then edit .env and paste your mnemonic
 npm start
@@ -70,7 +81,7 @@ npm start
 
 Open http://localhost:3003.
 
-### Option C — Docker
+### Run your own — Option B: Docker
 
 ```bash
 # one-liner
@@ -83,13 +94,13 @@ docker run -d --name plan-manager \
   sentinel-plan-manager
 
 # or with compose (includes named volume + auto-restart)
-echo "MNEMONIC=word1 word2 ... word24" > .env
+cp .env.example .env    # then edit .env and paste your mnemonic
 docker compose up -d
 ```
 
 State (`.wallet.json`, `my-plans.json`, `nodes-cache.json`) lives in the `/data` volume so it survives container recreations. Leave `MNEMONIC` unset to create a wallet from the UI on first boot instead.
 
-### Option D — Multi-user deploy (public domain)
+### Option C — Multi-user deploy (public domain)
 
 Want to deploy this to a domain and let anyone sign in with their own mnemonic? Set `MULTI_USER=true`:
 

package.json

@@ -40,6 +40,9 @@
     "rpc"
   ],
   "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {
     "@cosmjs/encoding": "^0.38.1",
     "@cosmjs/proto-signing": "^0.32.4",

public/index.html

@@ -1222,6 +1222,31 @@
 }
 html[data-theme="light"] .topbar { background: rgba(246, 247, 251, 0.82); }
 
+.demo-banner {
+  display: flex; align-items: center; gap: 12px;
+  padding: 10px 28px;
+  background: linear-gradient(90deg, rgba(245, 158, 11, 0.14), rgba(245, 158, 11, 0.06));
+  border-bottom: 1px solid rgba(245, 158, 11, 0.32);
+  font-size: 13px; color: var(--text);
+}
+.demo-banner-dot {
+  width: 8px; height: 8px; border-radius: 50%;
+  background: #f59e0b; box-shadow: 0 0 0 3px rgba(245, 158, 11, 0.18);
+  flex: 0 0 auto;
+}
+.demo-banner-text { flex: 1; min-width: 0; line-height: 1.5; }
+.demo-banner-text code {
+  background: rgba(0,0,0,0.3); padding: 1px 5px; border-radius: 4px;
+  font-size: 12px; font-family: ui-monospace, Menlo, Consolas, monospace;
+}
+html[data-theme="light"] .demo-banner-text code { background: rgba(0,0,0,0.06); }
+.demo-banner-cta {
+  flex: 0 0 auto;
+  font-size: 13px; font-weight: 600; color: #f59e0b;
+  text-decoration: none; white-space: nowrap;
+}
+.demo-banner-cta:hover { text-decoration: underline; }
+
 .topbar-title {
   font-size: 16px;
   font-weight: 600;
@@ -4801,6 +4826,13 @@ <h3 id="securityFaqTitle">
         </button>
       </div>
     </header>
+    <div id="demoBanner" class="demo-banner" style="display:none">
+      <div class="demo-banner-dot"></div>
+      <div class="demo-banner-text">
+        <strong>Demo mode</strong> — read-only preview on a public operator. Clone the repo and set <code>MNEMONIC</code> in <code>.env</code> to run your own.
+      </div>
+      <a class="demo-banner-cta" href="https://github.com/Sentinel-Bluebuilder/sentinel-plan-manager" target="_blank" rel="noopener">Get the source →</a>
+    </div>
     <div id="app">
       <div class="loading-state"><div class="loading-spinner"></div><div class="loading-text">Connecting to Sentinel network...</div></div>
     </div>
@@ -5668,6 +5700,8 @@ <h3 id="securityFaqTitle">
       S.wallet = d;
       S.dvpnPrice = d.dvpnPriceUsd;
       if (typeof d.multiUser === 'boolean') S.multiUser = d.multiUser;
+      const demoBanner = $('demoBanner');
+      if (demoBanner) demoBanner.style.display = d.kind === 'demo' ? 'flex' : 'none';
       walletAddress = d.address || '';
       ADDR_SHORT = walletAddress ? walletAddress.slice(0, 10) + '...' + walletAddress.slice(-6) : '?';
       if (walletAddress) {

server.js

@@ -66,6 +66,30 @@ const DATA_DIR = process.env.DATA_DIR || __dirname;
 try { mkdirSync(DATA_DIR, { recursive: true }); } catch {}
 initSession(DATA_DIR);
 
+// ─── Demo Mode ────────────────────────────────────────────────────────────────
+// Read-only browse: any visitor sees the UI mounted on a watch-only address
+// without supplying a mnemonic. Every TX-broadcasting endpoint returns 403.
+// Set DEMO_ADDR to any sent1... operator address you want visitors to view.
+const DEMO_MODE = String(process.env.DEMO || '').toLowerCase() === 'true';
+const DEMO_ADDR = (process.env.DEMO_ADDR || '').trim();
+if (DEMO_MODE) {
+  if (!DEMO_ADDR || !DEMO_ADDR.startsWith('sent1')) {
+    console.error('[demo] DEMO=true requires DEMO_ADDR=sent1... (operator address to display).');
+    process.exit(1);
+  }
+  // Validate bech32 checksum so a typo fails fast at boot instead of crashing
+  // on first request (keplrSessionFromAddress throws on invalid checksum).
+  try {
+    const { fromBech32 } = await import('@cosmjs/encoding');
+    const { prefix } = fromBech32(DEMO_ADDR);
+    if (prefix !== 'sent') throw new Error(`expected sent prefix, got ${prefix}`);
+  } catch (err) {
+    console.error(`[demo] DEMO_ADDR is not a valid sentinel address: ${err.message}`);
+    process.exit(1);
+  }
+  console.log(`[demo] Read-only mode enabled — mounted on ${DEMO_ADDR}. Writes return 403.`);
+}
+
 const app = express();
 app.use(express.json({ limit: '32kb' }));
 // Suppress fingerprinting header.
@@ -135,11 +159,20 @@ app.use(express.static(join(__dirname, 'public'), {
 // the rest of the request chain inside that session's AsyncLocalStorage
 // context. Handlers call `getAddr()` / `getSigningClient()` as before;
 // those helpers automatically resolve to the per-request wallet.
+//
+// In DEMO_MODE, every request without a real auth cookie is mounted on the
+// configured DEMO_ADDR as a watch-only session (kind: 'demo'). The write
+// gate below rejects POST/PUT/DELETE before any TX can be broadcast.
 app.use(async (req, res, next) => {
   const cookies = parseCookies(req.headers.cookie);
   const mnemonicToken = cookies[COOKIE_NAME];
   const keplrToken = cookies[KEPLR_COOKIE_NAME];
 
+  if (DEMO_MODE && !mnemonicToken && !keplrToken) {
+    const session = keplrSessionFromAddress(DEMO_ADDR, null, 'demo');
+    return runWithSession(session, () => next());
+  }
+
   if (mnemonicToken) {
     try {
       const mnemonic = decryptMnemonic(mnemonicToken);
@@ -174,6 +207,15 @@ app.use(async (req, res, next) => {
   next();
 });
 
+// ─── Demo Write Gate ──────────────────────────────────────────────────────────
+// Demo sessions can read but not write. Reject any state-changing method
+// (POST/PUT/DELETE/PATCH) with a clear 403 so the UI can surface a banner.
+app.use((req, res, next) => {
+  if (req.method === 'GET' || req.method === 'HEAD' || req.method === 'OPTIONS') return next();
+  if (currentSession()?.kind !== 'demo') return next();
+  return res.status(403).json({ error: 'Demo mode is read-only — clone the repo and set MNEMONIC to make transactions.', demo: true });
+});
+
 // ─── Plan ID Persistence ──────────────────────────────────────────────────────
 // Keyed by wallet address so multi-user deploys keep each operator's plan
 // list separate. Legacy flat-array files (single-user installs) are migrated
@@ -1089,7 +1131,13 @@ setInterval(() => {
 }, 60_000).unref();
 
 app.get('/api/wallet/status', (req, res) => {
-  res.json({ loaded: !!getAddr(), address: getAddr() || null, multiUser: isMultiUser() });
+  const isDemo = currentSession()?.kind === 'demo';
+  res.json({
+    loaded: !!getAddr(),
+    address: getAddr() || null,
+    multiUser: isMultiUser(),
+    demo: isDemo,
+  });
 });
 
 app.post('/api/wallet/generate', rateLimit('wgen', 10, 60_000), async (req, res) => {