Update NEW_USER_SPEC.md to reflect implemented features

NEW_USER_SPEC.md

@@ -1,130 +1,54 @@
-# New User Experience — Build Spec
+# New User Experience
 
 ## Overview
-A new "home" page for the MeshCore Analyzer that serves as a **diagnostic companion** for new mesh users. The existing pages (packets, map, channels, nodes, observers, traces) remain untouched — this is a new front door.
+The home page (`#/` or `#/home`) is the front door to the analyzer — a diagnostic companion for mesh users to check if their node is being heard, and a dashboard for regulars to monitor favorites.
 
-## Architecture
+## Features
-- New page registered as `home` in the SPA router (hash `#/` or `#/home`)
-- New file: `public/home.js` — the page module
-- New file: `public/home.css` — styles (imported via `<link>` in index.html)
-- New server endpoints in `server.js` for node lookup
-- Default route changes from `#/packets` to `#/home`
 
-## Page Structure
+### Hero Search
+- Prefix search with auto-dropdown as you type (name or public key)
+- Quick stats bar: active nodes · packets today · observers online
+- Results link to node health card or node detail page
 
-### Section 1: Hero Search
+### Node Health Cards
-- Big centered search box with placeholder: "Search by node name or public key..."
+Shown after search or on home page for favorited nodes.
-- Subtitle: "Check if your packets are reaching the mesh"
-- Auto-suggest dropdown as user types (search nodes API)
-- Below search: quick stats bar — "X nodes active · Y packets today · Z observers online"
-- Clean, minimal. No nav clutter competing for attention.
 
-### Section 2: Node Health Card (shown after search)
+**Status logic:**
-Appears below search with a smooth transition. Contains:
+- 🟢 HEALTHY: heard by observers in the last hour
+- 🟡 DEGRADED: last heard 1-24h ago
+- 🔴 SILENT: not heard in 24+ hours
 
-**Status Banner:**
+**Contents:** last heard, observer count, avg SNR with quality label, hop count, packets today, status reasoning text.
-- 🟢 HEALTHY: "Heard by N observers in the last hour"
-- 🟡 DEGRADED: "Last heard 3 hours ago by 1 observer" 
-- 🔴 SILENT: "Not heard in 24+ hours"
-- Status logic: green (<1h), yellow (1-24h), red (>24h)
 
-**Mini Map:**
+### Favorites ("Your Nodes")
-- Small Leaflet map showing the node's position + observer positions that heard it
+- Star/unstar nodes from any node detail view
-- Lines from node to observers, thickness = signal strength
+- Stored in localStorage
-- Only if node has lat/lon
+- "Your Nodes" section on home page with live status cards
+- Quick access to node detail via click
 
-**Key Metrics (card grid):**
+### Quick Setup Checklist
-- Last heard: relative time
+Collapsible accordion for troubleshooting:
-- Observers: count + names
+1. Correct preset / frequency
-- Avg SNR: with plain-English quality label (Excellent >10, Good 0-10, Marginal -5-0, Poor <-5)
+2. Send a flood advert
-- Hop count: typical path length
+3. Check repeat count
-- Packets today: count
+4. Nearby repeaters (link to map)
+5. Frequency mismatch warning
 
-**Recent Activity Timeline:**
+### Navigation Footer
-- Last 10 packets from this node, shown as a simple timeline
+Links to full dashboard pages: Map, Channels, Packet Inspector, Observers
-- Each entry: time, type (ADVERT/GRP_TXT/etc), observers that heard it, hop count
-- Click any packet → links to `#/packets?id=X` (existing detail view)
 
-### Section 3: Packet Journey (expandable, one click)
+## API Endpoints
-When user clicks a specific packet from the timeline:
-- Visual representation: Node → Hop 1 → Hop 2 → Observer
-- Each step shows SNR, timing
-- Simple horizontal flow diagram using CSS (no canvas/SVG needed for v1)
-- Educational tooltips on hover:
-  - "ADVERT: This tells the network your node exists"
-  - "3 hops: Your packet traveled through 3 repeaters"
-  - "SNR -2 dB: Marginal signal — a better antenna would help"
-
-### Section 4: Quick Setup Checklist
-Always visible at bottom, collapsible accordion:
-
-**"Not seeing results? Check these:"**
-1. **Correct preset?** — Show recommended presets by region (US: 910.525 MHz, SF7, BW62.5, CR5)
-2. **Sent a flood advert?** — "In the MeshCore app, tap the signal icon → Flood Advert. This announces your node to the network."
-3. **See 'Heard N repeats'?** — "After sending a message, the app shows how many repeaters forwarded it. 0 repeats = no one heard you."
-4. **Repeaters near you?** — Link to `#/map` filtered to repeaters
-5. **Right frequency?** — "If you're on old settings (SF11, BW125), you can't talk to nodes on the new recommended preset"
-
-### Section 5: "Ready for more?" footer
-Links to the full dashboard pages:
-- 🗺️ Network Map — See all nodes and coverage
-- 💬 Channels — Read mesh chat messages  
-- 📦 Packet Inspector — Deep dive into raw packets
-- 📡 Observers — See who's listening
-
-## Server API Additions
 
 ### GET /api/nodes/search?q=<query>
-- Search nodes by name (partial match) or public_key (prefix match)
+Prefix search by name or public key, returns top 10 matches.
-- Returns top 10 matches: `{ nodes: [{ public_key, name, role, lat, lon, last_seen }] }`
+
+**Note:** Static path `/api/nodes/search` must be defined BEFORE parameterized `/api/nodes/:pubkey` in Express routes.
 
 ### GET /api/nodes/:pubkey/health
-- Returns health summary for a specific node:
+Returns health summary: node info, status, observer list with SNR/RSSI, stats, recent packets.
-```json
-{
-  "node": { "public_key": "...", "name": "...", "role": "...", "lat": ..., "lon": ..., "last_seen": "..." },
-  "status": "healthy|degraded|silent",
-  "observers": [{ "id": "...", "lastHeard": "...", "avgSnr": ..., "avgRssi": ..., "packetCount": ... }],
-  "stats": {
-    "packetsToday": 42,
-    "avgSnr": 3.2,
-    "avgHops": 2.1,
-    "lastHeard": "2026-03-17T14:30:00Z"
-  },
-  "recentPackets": [
-    { "id": 123, "timestamp": "...", "payload_type": 4, "hash": "...", "observer_id": "...", "snr": 3.1, "rssi": -82, "hopCount": 2 }
-  ]
-}
-```
 
-## DB Queries Needed (add to db.js)
+## Files
-
+- `public/home.js` + `public/home.css` — home page module
-### searchNodes(query, limit=10)
+- `server.js` — search + health endpoints
-```sql
+- `db.js` — `searchNodes()` + `getNodeHealth()` queries
-SELECT * FROM nodes WHERE name LIKE ? OR public_key LIKE ? ORDER BY last_seen DESC LIMIT ?
+- `public/app.js` — default route = home
-```
-
-### getNodeHealth(pubkey)
-Multiple queries:
-1. Get node by pubkey
-2. Get packets where decoded_json contains this pubkey (for ADVERTs) or observer patterns
-3. Aggregate observer stats
-4. Recent packets list
-
-Note: Since we don't have a `source_node` column on packets, for ADVERTs we can match by decoded_json containing the pubkey. For other packet types this is harder — we may need to add a `source_pubkey` column in a future iteration. For v1, focus on ADVERT packets as the primary "was I heard?" signal, since that's exactly what new users send first.
-
-## Styling Guidelines
-- Use existing CSS variables (--bg, --text, --accent, --border, --surface-0/1/2/3, etc.)
-- Dark mode must work (use var() everywhere, no hardcoded colors)
-- Mobile responsive (works at 640px)
-- Match existing design language but cleaner/more spacious for the landing page
-- Status colors: green=#22c55e, yellow=#eab308, red=#ef4444
-
-## File Locations
-All files in `/root/.openclaw/workspace/meshcore-analyzer/`
-- `public/home.js` — new
-- `public/home.css` — new  
-- `public/index.html` — add `<link>` for home.css, add `<script>` for home.js
-- `server.js` — add 2 new endpoints
-- `db.js` — add 2 new query methods
-- `public/app.js` — change default route from packets to home