SkateSpots/AGENTS.md

Project Overview

This project is a Nostr client application built with React 18.x, TailwindCSS 3.x, Vite, shadcn/ui, and Nostrify.

Technology Stack

• React 18.x: Stable version of React with hooks, concurrent rendering, and improved performance
• TailwindCSS 3.x: Utility-first CSS framework for styling
• Vite: Fast build tool and development server
• shadcn/ui: Unstyled, accessible UI components built with Radix UI and Tailwind
• Nostrify: Nostr protocol framework for Deno and web
• React Router: react-router-dom with HashRouter (routes live in the URL hash, e.g. /#/settings) and ScrollToTop functionality
• TanStack Query: For data fetching, caching, and state management
• TypeScript: For type-safe JavaScript development

🧠 This file is the ONLY persistent memory — keep it in sync

AGENTS.md is the single thing carried across sessions; a model starts every session with no other memory of this project. So:

• Write important things down here in the same session you learn them. If it isn't in this file, the next agent doesn't know it and will re-derive (or get) it wrong.
• Record the non-obvious: exact commands + flags, file paths, gotchas, environment quirks, verified facts, and why a decision was made. Skip what anyone can read from the code.
• Fix stale entries immediately. A wrong note here makes every future session go off the rails — check claims against the repo before trusting them.
• Keep it tight and factual: commands/paths over prose, no essays.
• When you change something this file describes (scripts, kinds, deploy, hooks), update that section as part of the same change. Date non-trivial claims: (verified 2026-09-26).

Project map (what exists right now)

• Router: react-router-dom HashRouter — real routes live in the URL hash (/#/settings, /#/marketplace). A bare /settings renders the homepage (this silently broke the boot smoke test once). src/AppRouter.tsx.
• Custom protocol: NIP.md is the source of truth for every custom/adopted kind; the constants live in src/lib/types.ts. Highlights:
  • 30818 skate spot · 30017 shop · 31923/31925 events + RSVP · 30823 tours
  • 30402 NIP-99 listing = marketplace item, and the Assertion Event for trades
  • 30403 marketplace offer (+ seller response) — see NIP.md
  • 31871 trade attestation (sale/purchase) · 31872 trade confirmation request · 31873 trusted-trader recommendation → src/hooks/useTradeAttestations.ts / useTraderRecommendations.ts; reputation UI in TradeReputationCard / TradeRecommendationsCard
  • 35000–35014 role profiles (skater/filmer/coach/…/event-organizer/barber) · 35006 crews · 30003 spot collections
  • Lab offer flows (/become/*): the 7 craft roles share CraftProfileForm; coach/filmer/editor/photographer/builder are bespoke but follow the same conventions. Forms prefill from the existing profile to edit, and preserve the g geohash + paid featured tag on edit. Bare domains (example.com) are coerced to https:// by normalizeUrlInput() (src/lib/sanitizeUrl.ts) before storage, so links aren't silently hidden by sanitizeUrl() at render (the extra-field url type used to be dropped outright). MIN_TITLE_LEN is 1: a profile title falls back to the display name, and a 1-char name must not fail validation and vanish. Contact fields are validated on submit: a non-empty email must satisfy isValidEmail(), and website/portfolio must resolve through sanitizeUrl(normalizeUrlInput(...)). Invalid input shows an inline hint and blocks publish (social is exempt — it may be a bare @handle).
  • Photos: PhotoDropzone (src/components/PhotoDropzone.tsx) is the shared image input — drag & drop + multi-select, emits File[] to its caller (which owns uploads/toasts). Used by CreateSpotPage, EditSpotPage and AddPhotoToSpot, replacing the old one-file-at-a-time inputs.
  • 24899 spot chat · 2259 spot status · 32671 Sasquatch Pro · 7103 event updates
• Marketplace: GearSwapPage (grid) + MarketplaceItemCard and a listing detail page at /listing/:pubkey/:identifier. Trade/escrow actions live in the shared ListingTradeActions (used by BOTH the card and the detail page — one implementation). Buyer/seller attestations build mutual, WoT-weighted reputation. Anti-collusion (2026-09-27): two accounts can fake mutual confirmations, so reputation leads with verifiedCounterparties (distinct people mutually confirmed with) instead of the raw verified count, weights by WoT with a per-partner cap of 3, and shows a warning when several confirmations all come from one account (TradeReputationCard). NIP.md → "Trust model, sybil/collusion limits" documents that attestations are a signal, not proof of payment — never present them as trustless. Confirming a trade also records an optional 1–10 deck rating (see rating tag). No payments are implemented — "Buy" is intentionally absent; buyers contact the seller and settle off-app. A /trades page ("My Trades") manages incoming requests, pending confirmations, and the user's trade records, and can revoke a record (s=revoked, excluded from reputation) for a dispute or mistake. Structured offers (kind 30403, useMarketplaceOffers + the ListingOffersPanel/OfferDialog) are a counter-offer negotiation thread (2026-09-29): every message is its own event with a unique d (append-only) carrying role (offer = buyer / response = seller), e = the message it answers, and status; either side can accept / decline / withdraw / counter and ListingOffersPanel shows the volley + whose turn it is. Legacy fixed-slot ds are still parsed (role inferred when the role tag is absent) — see NIP.md → "Marketplace Offers". Trade/offer steps also feed useTradeNotifications → the bell's All tab (TradeNotificationCard, counted in the badge against seenAt) and OS notifications (new trades category in notificationPrefs, wired in OsNotificationBridge). The bell also has a dedicated Trades tab (5th tab, Handshake) listing them, with its own count. Types cover every step: offer, counter, accepted, declined, withdrawn, trade-request (they asked you to confirm) and trade-confirm (they confirmed — usePendingTradeConfirmations, now carrying createdAt/eventId so it can be notified; confirming back is what makes the trade mutual and builds reputation). Barter is supported by design: trade attestations carry method (cash|lightning|trade|other — MarkSoldDialog picks it), so a swap feeds reputation exactly like a sale. Barter is first-class on the offer side too (2026-09-29): an offer/counter may carry an item tag (["item","my 8.25 deck"]) instead of or alongside amount — OfferDialog and the counter UI expose it, and the bell/OS text reads it ("offered 2,000 SATS + an 8.25 deck"). Listings already support price_type=trade ("Looking to swap"); LISTING_TYPES itself is still selling|wtb.
• Cashu escrow (marketplace): time-locked P2PK (lock to seller + buyer refund key + locktime) — see ESCROW.md and src/lib/cashuEscrow.ts (unit-tested). Protocol: cashu_token on the 31872; each user advertises a cashu_escrow pubkey in kind 0. UI wired: useCashuEscrow, EscrowKeyCard (Wallet), EscrowRequestDialog (listing card), EscrowPanel
  • redeem (DM request banner), Refund escrow (listing card). Native-only and UNVERIFIED on a device — verify with the on-device checklist in ESCROW.md (tiny amounts) before trusting it with real money.
• Wallet: useCashu (coco-cashu) is native-only — it returns early on web (mints are CORS-blocked). Zap rails are NWC + WebLN + Cashu melt (useZaps).
• Relays: NIP-65 read/write (kind 10002), NIP-17 DM inbox relays (kind 10050; set in the Relays UI, fetched on login by NostrSync, delivered to on send and read from in useDirectMessages), plus two app-local categories — localRelays (never published; added to reads+writes) and blockedRelays (excluded everywhere). resolveRelays() in src/lib/relays.ts applies them; NostrProvider uses it for its req/event routers. Deliberately not shipped: KeyPackage relays (10051, no MLS consumer yet), "Trusted" (no distinct behaviour — would be empty UI), and Amethyst's proxy/ broadcast/private-home (we don't have that relay-discovery model) — don't add UI for features we don't implement.
  • All relay consumers now go through useRelays() (read/write — blocklist applied, local included): listing reports, seller info, skate relays, zaps, Sasquatch purchase, collections, crew form, and DMs. AppProvider's empty-relays defaults check is the only intentional direct reader.
  • DM inbox relays (kind 10050) are also block-filtered now (reads and delivery), so the blocklist applies to DMs too.
• Group DMs: NIP-17 (useDirectMessages, GroupConversationPage).
  • ⚠️ Zod strips undeclared keys — it cost us the DM relay list (fixed 2026-09-27). AppProvider validates the persisted config with AppConfigSchema.partial().parse(...), and RelayMetadataSchema only declared relays + updatedAt. Zod's default behaviour is to drop unknown keys, so dmRelays, localRelays and blockedRelays were wiped on every load. The DM inbox relays (kind 10050) are usually NOT in a user's NIP-65 list, so with dmRelays gone the app read/wrote DMs only over NIP-65 relays — where the other side isn't listening — and inbox messages appeared to never arrive. Rule: any new RelayMetadata/AppConfig field MUST be added to the Zod schema or it silently won't persist. Verified end-to-end: before the fix the gift wrap reached only write relays (recipient found 0); after, it lands on the configured inbox relays (recipient and self-fetch both find it).
  • ⚠️ DM history read from the wrong relays — "No messages yet" with a full inbox (fixed 2026-09-28). All four DM read hooks built their relay list from config.relayMetadata.dmRelays (login-time sync only). If that was stale/empty, only the NIP-65 read relays were queried — and gift wraps almost never live there (real case: 94 addressed wraps on the user's inbox relay nostr.mom, 0–1 on their NIP-65 relays). Fix: useResolvedDmRelays() in useDirectMessages.ts discovers the user's own kind-10050 inbox relays at query time (per-relay, 6s each, over the read relays + INBOX_DISCOVERY_RELAYS) and unions them in — so a stale config can never silently hide history. Used by useConversation/useConversations/useGroupConversations/useGroupConversation. useConversations now returns ConversationsResult ({ conversations, undecryptable, wraps }) — consumers are DirectMessagesPage and ContactsPage — and the DM page shows "N encrypted messages couldn't be opened" so a decrypt failure is no longer indistinguishable from an empty inbox. Diagnostic recipe: count {#p:[pubkey], kinds:[1059]} per relay (per-relay, not one pool query) before assuming a code bug.
  • DM send/read robustness (same date): gift-wrap publishing and gift-wrap reading were both sequential with one shared timeout, so a single dead relay (e.g. wotr.relatr.xyz) or an auth-required one (auth.nostr1.com) stalled the send or aborted the remaining reads — hiding every message. Both are now parallel with per-relay timeouts; the send resolves on the first relay that accepts and continues the rest in the background, and a recipient with no discoverable 10050 falls back to their NIP-65 write relays (previously the NIP-65 fallback was effectively dead code because our own DM relays are always non-empty). NRelay1.event() DOES throw on OK:false, so per-relay failures are real; the composer only clears on success.
  • Sasquatch AI guide (src/components/SasquatchGuide.tsx): the chat queries public relays directly (useCVMClient.ts, 3 fixed relays) and does not use the ContextVM server. AI goes through our own server-side proxy — the Netlify Function netlify/functions/ai.mjs at /api/ai — which runs against Netlify's AI Gateway. No key is managed or shipped: Netlify injects OPENROUTER_API_KEY + OPENROUTER_BASE_URL into Functions, and the function reads the base URL (so it also works if you later set your own key). Model choice is a curated allowlist (the gateway enforces Zero Data Retention, so gemini/anthropic/gpt-4o-mini are not routable) — keep ALLOWED_MODELS in the function in sync with PROXY_MODELS in sasquatchBrain.ts. Keyless Pollinations is the fallback. The proxy has an env-gated Pro paywall and it is ENABLED in production (SASQUATCH_REQUIRE_PRO=1): /api/ai requires x-sasquatch-auth (a NIP-98 kind-27235 event) plus x-sasquatch-pro (the Pro zap receipt, verified offline incl. paid-amount→tier); platform owners bypass. Disable with netlify env:unset SASQUATCH_REQUIRE_PRO. The client (src/lib/proAuth.ts) signs NIP-98 once per session (no Amber pop per message) and attaches the receipt — used by BOTH SasquatchGuide and the crew agent (useCrewAgentChat). Callers without credentials 401 and fall back to keyless Pollinations. The pay-to address is single-sourced in src/lib/platform.ts. The upstream is provider-agnostic: SASQUATCH_AI_BASE + SASQUATCH_AI_KEY override the Netlify gateway (any OpenAI-compatible endpoint). For a sats-only provider use Routstr (SASQUATCH_AI_BASE=https://api.routstr.com/v1, key = a cashu…/sk- session token; SASQUATCH_MODELS must match PROXY_MODELS). ⚠️ The aggregator api.routstr.com is DOWN (404) — use a node. Nodes announce on Nostr as kind 38421 with the endpoint in a u tag. Live + working (2026-09-27): https://routstr.githappens.space (accepts the minibits mint; gemini-3-6-flash answers). Others were up too but ai.orangesync.tech issued an sk- key that its own inference endpoint rejected ("User not found") — always test inference before committing funds. Funding: POST <node>/lightning/invoice {amount_sats,model} → pay bolt11 → GET <node>/lightning/invoice/<id>/status → api_key (sk-…). Refund: POST <node>/v1/balance/refund → a Cashu token (recoverable/portable). Then set SASQUATCH_AI_BASE=<node>/v1, SASQUATCH_AI_KEY=sk-…, SASQUATCH_MODELS=<slugs> — Netlify snapshots env at deploy, so redeploy after changing it. The proxy substitutes its first allowed model when the client's slug isn't allowed, so the client list need not match. Owner Settings shows the upstream balance (SasquatchAiStatusCard) via the owner-only POST /api/ai/status (NIP-98 + owner pubkey → handleStatus), with a "low balance" warning below 500 sats — the top-up nudge (no webhook needed). The same balance shows as a chip in the Sasquatch panel header (owner-only, fetched only while the panel is open so it never prompts at startup). AI answers are Pro-only: free users get the static FAQ/glossary + local relay lookups only (if (isPro) gates the AI block in SasquatchGuide). Pro access (useSasquatchPro) is granted by a provider-authored zap receipt, and its expiry is derived from the paid amount → tier, never the user-signed pro-expiry tag.
    • Pro proofs STACK (fixed 2026-09-28). useSasquatchPro now collects ALL valid proofs and accumulates expiry = max(expiry, proofTime) + tierDays (renewal semantics) — before, it took the max of receipt.created_at + days, so buying again before expiry silently under-delivered ("Extend" did not extend). The proof sent to the proxy is now { receipts, grants } (base64) instead of one receipt; both servers (ai-proxy/server.ts and netlify/functions/ai.mjs) accept the new payload AND a bare receipt, so installed APKs keep working. ⚠️ Deploy the proxy before the web client (old proxy + new payload = 402).
    • Owner-grant fallback (NIP-32, same date): org.skatespots.pro kind-1985 labels authored by an owner pubkey, tagged p = user + expiry, are a trusted Pro source (useSasquatchPro + both servers honour them) — the safety net if the LN provider ever stops emitting zap receipts. Published by the owner-only GrantProCard (Settings → Advanced), written to getWriteRelays() and read via querySkateContent (community relay + user relays); the self-signed 32671 remains advisory-only.
    • Pro UX pass (same date): usePersonalContext now decrypts the Stash on demand — unlockStash() is called by getMyStash when the AI actually reads it (stashRef avoids the stale-closure trap) — so "what's in my stash?" is correct, while the globally-mounted guide still never decrypts on mount. New self-contained action draft wtb_gear ("wanted" ads, NIP-99 listing_type=wtb). The panel header shows ⚡ Pro · Nd days left; the tier picker shows live USD via useExchangeRate (the hardcoded ~$60k/BTC usd field was removed from PRO_TIERS). Copy now says skate status (not spot status) and states trip planning is free. sasquatchBrain.ts caps each request (15 s) and the whole attempt (35 s); the system prompt is a real system message; relay results are signature-verified (verifyEvent) before use. The first pass streams (streamSasquatchAI, OpenAI-style SSE) into a live bubble — raw JSON tool calls are suppressed so partial JSON never renders. Pollinations' mistral slug is dead (404); only openai (gpt-oss-20b) is live. findCoaches + getCommunityStats cover all Lab roles (kinds 35001–35014).
  • ContextVM (CVM) server (cvm-server/, Bun): standalone MCP-over-Nostr endpoint for external agents. Runs on this machine as a system service (/etc/systemd/system/skatespots-cvm.service, sudo systemctl restart skatespots-cvm) + a daily-restart timer. Re-publishes its discovery announcements on a heartbeat (CVM_HEARTBEAT_MS, default 15 min) so the owner Settings health card (stale after 45 min) stays green; LOG_LEVEL is now wired to the transport. Relays come from NOSTR_RELAYS in the gitignored cvm-server/.env — policy is single community relay (wss://goskatespots.nostr1.com). The tracked manifest is package.cvm.json. Tools: find_spots / find_events / find_coaches (all Lab kinds 35001–35014) / find_gear / find_crews / find_shops / find_tours + get_community_stats — kept at parity with the app's useCVMClient. Has a per-pubkey sliding-window + in-flight throttle, a global upstream semaphore and a short-TTL query cache (CVM_RATE_*, CVM_MAX_*, CVM_QUERY_CACHE_MS). Type-checked by cvm-server/tsconfig.json via the typecheck:cvm script (wired into npm test); check:cvm runs a Bun transpile. The server runs on one external host (not this box) — deploy with npm run deploy:cvm; the host/SSH values come from the never-committed ~/.config/skatespots/cvm.env (never put them in a tracked file — this repo is public). scripts/deploy-cvm.sh --rollback restores the newest backup. The discovery relay (relay.contextvm.org) is the real single point of failure, not the server.
• Routing / directions: RouteDialog is the single in-app router, opened from the map spot sheet, the food cards, and the spot / shop / event detail pages (MapPage's old external "Open with" Google/OSM/Waze menu was removed). Road modes (skate-walk / bike / moto / car) come from keyless OSRM (src/lib/routing.ts). ⚠️ Use the per-profile FOSSGIS servers, not the demo one: router.project-osrm.org hosts a SINGLE car dataset and ignores the profile in the URL, so foot/bike/car all returned identical distance+time (the "every transport option shows the same time" report). We now call https://routing.openstreetmap.de/routed-{foot|bike|car}/route/v1/{foot|bike| driving}/… (CORS *, direct first, proxy.shakespeare.diy proxy only as fallback), request steps=true and expose RouteStep[] (verified 2026-09-27: same trip = walk 13 min / bike 5 / drive 2). The demo server survives only as a last-resort fallback and its result is flagged approximate ("driving estimate") so we never pass driving numbers off as walking. Moto≈car is labelled honestly; the foot summary also shows a ~10 km/h skateTime cruise estimate ("~6 min on a board") next to the walking time. The dialog also remembers the last mode (localStorage: skatespots:route-mode), shows an ETA ("arrive ~08:10 PM"), and each step row is tappable (pans the map + highlights) with a "Whole route" re-fit button.
  • ⚠️ index.css has a global mobile rule button, [role=button] { min-height: 44px; min-width: 44px } for touch targets. Any dense list of <button> rows (like route steps) must add min-h-0 or every row becomes a 44px slab — a class beats the element selector, so min-h-0 is enough.
  • Follow mode / start point / offline (2026-09-27): the dialog also does follow mode (explicit Start → watchPosition in geolocation.ts, live dot, "NEXT · step N" banner with distance-to-turn + distance-to-go, current step highlighted), a start point choice (My location / Choose on map — tapping the Leaflet map sets it), and an offline route cache (src/lib/routeCache.ts, downsamples the line to ≤250 points, keeps the last 8 destination+mode entries; the failed fetch falls back to it and shows "Offline · saved route {age}"). Rules: never auto-start the watcher (battery — user action only) and always stop() it on close/unmount; a transient watch error (timeout/temporarily unavailable) must not tear down the watcher — only denied does (headless CDP testing made this obvious: moving the mocked position emits a transient error that recovered). Phone navigation (2026-09-29): while following we also keep the screen awake (navigator.wakeLock, re-acquired on visibilitychange), speak turns via device TTS (speechSynthesis, prefer a localService voice in the user's language — free/offline/no server) at ~150 m and ~40 m bands (announced once each, tracked in announcedRef), buzz haptics (navigator.vibrate), detect arrival (~30 m → "You've arrived", auto-stop), and show a bigger map while following with the planning step-list hidden. Voice has a mute toggle persisted in skatespots:route-voice; TTS is unlocked by the Start tap. Still deliberately absent: auto-reroute if you leave the route. True screen-off/background navigation needs a native foreground service — the app must stay foregrounded to guide.
  • Dialog layout (2026-09-29): app-like flex column — flex max-h-[calc(100dvh-2rem)] flex-col overflow-hidden. DOM order now matches the visual order (and order-* is set redundantly, so a dev-mode CSS-timing hiccup can't scramble it): header, then the map directly under it (it's the point of the screen), then the mode/vehicle row, then the "From" row, then the scrolling details, with the Start/Stop bar pinned at the bottom. The map is shrink-0 at h-[50vh] min-h-[300px] sm:h-[440px] (was 38vh), or h-[60vh]/sm:h-[62vh] while following. The summary is a compact one-line strip (distance · time · arrive) — StatTile was removed; the three ~90px tiles were eating the map's space. ⚠️ Don't go back to a single overflow-hidden content box: that made everything below the fold unreachable once the map grew. The map carries a metric L.control.scale. Transit mode uses Transitous (api.transitous.org, MOTIS 2, open CORS) — note origin/destination go to that service, unlike road modes. No external map-app handoff anywhere (product decision) and no scooter/moped profile. Speed (2026-09-27): RouteDialog seeds origin from getLastLocation() and skips the live GPS call entirely when that fix is < 2 min old; the blocking "Finding your location…" overlay shows only when there is no seed (with a seed it refines silently via a corner chip). The map "Near Me" button also flips the sort to proximity.
  • ⚠️ RouteDialog had a total-failure bug (fixed 2026-09-27), don't regress: (1) its Leaflet map is inside Radix Dialog content, which mounts AFTER the component's first effect pass, so a mapDivRef.current guard was null, the init effect bailed, and the map was never created (no route line ever appeared). The node is now held in state (const [mapDiv,setMapDiv]) with a callback ref, and mapDiv is in the effect deps so it runs when the node actually mounts. (2) Even once created, the global .leaflet-container { height: 100% } override in index.css beats h-64 on the map element; against a height-less parent it resolved to 0 (invisible map). Height now lives on the wrapper (<div className="relative h-64">) and the map is h-full. (3) On the map, Directions used to render the dialog INSIDE the spot Sheet (two stacked Radix modals; the sheet covered the route). The map now owns the dialog at page level (routeTarget state) and closes the sheet first.
  • OSRM is called directly (router.project-osrm.org sends Access-Control-Allow-Origin: *) with the proxy.shakespeare.diy CORS proxy only as a fallback — faster, and origin/destination never leave OSRM unless the direct call is blocked. Failures are distinguished: Routing service busy (429/TooManyRequests), No route found (NoRoute / invalid coords), else unreachable. Verify route rendering with scripts/-style CDP repros, not just the smoke test (which only checks mount).
• Layout is a router layout — AppRouter wraps every route (except /amber-callback and the * 404) in one <Route element={<Layout/>}> with an <Outlet/>, so the chrome (header, nav, notifications, Sasquatch) mounts once and survives navigation. Pages render fragments (<>…</>), never <Layout>. The map is full-bleed via a route check (isFullBleed in Layout), not a per-page noPadding prop. Don't reintroduce per-page <Layout> wrappers — remounting the chrome re-runs its hooks (and with Amber that means signer popups). Encrypted-on-mount hooks are also gated for interactive signers (staleTime/gcTime: Infinity, refetchOnMount: false) — see useSyncedAppData / useStash. Read-state is local-only for interactive signers: useReadState skips the encrypted publish when isInteractiveSigner is true, so merely opening the notification bell (which marks read) no longer pops Amber twice (encrypt + sign). Interactive signers only prompt for real signed actions.
  • ⚠️ staleTime: Infinity does NOT stop the FIRST decrypt (fixed 2026-09-27). That was the "Amber pops on every screen" report: the encrypted useSyncedAppData blobs (read-state, preferences) ran their queryFn once on mount for each racing consumer, and relay responses landing during navigation made it look per-page. useSyncedAppData now takes interactiveNetwork (default false): for an interactive signer the blob is local-only — the query is not even enabled and patch() is a no-op — so no decrypt on mount and no publish on a nav-tab change. localStorage is the session source of truth. Only set interactiveNetwork: true if a feature genuinely cannot work from localStorage. Diagnostic recipe: mock an x-amber login by writing localStorage['nostr:login'] before load, then wrap localStorage.setItem to log writes of amber_pending_operation (captures every prompt + a stack). Beware stale harness profiles — use a fresh --user-data-dir per run or the ops array is from a previous run.
  • ⚠️ Don't make read-state mutators (or any hook they flow from) unstable (fixed 2026-09-27). /newsletter was stuck in an infinite render loop (~100% CPU, React "Maximum update depth exceeded") because: useSyncedAppData returned a fresh object literal every render → useReadState.apply (dep synced) got a new identity → markNewsletterRead/markAllRead changed every render → page effects depending on them re-ran after every render → the mark set a new state object → re-render → loop. Same latent loop in NotificationBell while open. Fixes (keep them): useLocalStorage's setter is referentially stable (ref + functional update), useSyncedAppData returns a memoized object, useReadState.apply reads synced/interactive from refs so it's stable, and markAllRead/markNewsletterRead are idempotent (return the SAME object when the marker already covers now, so React bails). Page effects that mark read on open use a mount-once ref guard (NewsletterPage). Diagnose with CDP Performance.getMetrics TaskDuration over ~4 s idle (a looping route burns ~4 s; a healthy one ~30–100 ms).
  • Newsletter publish/read relay rule: issues (kind 30023, t=skatespotsnews) and the subscription marker (kind 30078, d=skatespots:newsletter:subscription) are read via useSkateRelays (querySkateContent) — i.e. the community relay + the reader's relays, and for logged-out visitors only the community relay. So they must be published to getWriteRelays() (community relay + the author's relays), NOT the default pool (useNostrPublish). The composer / backfill / subscribe hook do this and fail loudly if every relay rejects. useSpotChat is the reference pattern. (Before the fix, an admin whose own NIP-65 lacked goskatespots would publish issues nobody could find.)
• Nav parity (fixed 2026-09-27): the desktop header is max-w-[1700px] (wider than the page container's 1400px) and nav items are px-3 + whitespace-nowrap; the nav keeps min-w-0 overflow-x-auto scrollbar-hide, so if it ever overflows it clips the TRAILING item — i.e. the "More" menu (this is exactly how "More" vanished when MARKETPLACE replaced MINTS). Keep the header wide / padding tight; don't let the nav grow without room. The mobile burger menu (MOBILE_MENU_LISTED_HREFS) now appends catalog items that aren't hard-coded, so Marketplace/Mints (and any future section) are always reachable on mobile — don't re-hardcode only a subset.
• App Shop (/app-shop, src/pages/AppShopPage.tsx): SkateSpots merch, to be paid in sats only (Lightning or Cashu) — no cards/accounts — sold locally, on request: there is no cart, no checkout, no shipping. Buying is a conversation: "Request an item" deep-links to a DM with the owner (/messages/<owner npub>, owner = PLATFORM_OWNER_PUBKEYS[0]), the details are agreed in chat, and sats change hands at handover. Don't add shipping copy/rates or a cart without a decision to change that model. Registered in NAV_CATALOG as id app-shop (label "App Shop", ShoppingBag), which is what makes it appear in both the desktop "More" menu and the mobile burger menu (the mobile menu appends catalog items not in MOBILE_MENU_LISTED_HREFS). It is intentionally empty: no stock, no prices, no pre-orders and nothing for sale. That is carried by the "COMING SOON" badge, the "IN THE WORKS / not for sale yet" label on the teaser grid and the "sold locally, on request" hero copy (the page deliberately has no stock list, no subscribe band and no 'nothing is for sale' note — removed on request). Do not add prices/fake urgency/buy buttons until there is real stock; when items exist, model them as listings and take Lightning/Cashu payment. The page reads the live stock strip as 0/None/Nothing — keep it honest if that changes. It also serves two free printables (rendered INSIDE the 'Sticker packs' entry of the 'In the works' grid — deliberately not a separate section, per the owner: the free sticker + poster belong under their merch category) (public/images/print/skatespots-sticker.svg 55×86 mm, …-poster.svg A3), regenerated with node scripts/make-print-art.mjs (output is committed). Those SVGs are self-contained: brand fonts + logo embedded as data URIs and a real vector QR (verified decoding to https://skate-spots.org — if you regenerate, re-verify the QR scans with the logo in the middle; error-correction level H).
• Spot data quality (2026-09-27): three cheap defences against junk pins (test entries, airports, malls), because "the map looks endorsed" is the real risk. (1) CreateSpotPage requires ≥1 photo (guard in handleSubmit + the submit button is disabled) — a typo rarely has a photo. (2) The spot page shows a Community verified / Unverified badge computed from signals only other skaters can produce: community photos + useSpotStatus reporterCount (kind 2259). The weather score was renamed "Conditions · weather only" (in SpotDetailPage and the SpotMap popup) so it can't read as spot quality. (3) useNotASpotReport = one-tap NIP-56 (1984) report tagged not-a-skate-spot (NIP-56 other reason + our L/l/t taxonomy), used from the spot's "More" menu and the shared ReportDialog.
• Admin hide + review queue (2026-09-27): useAdminModeration always READ NIP-32 kind-1985 hidden labels, but nothing published one — the only working hide was device-local (useDeleteEntity → addLocalHidden). useAdminHide is the missing write side: kind 1985 + ['L', 'org.skatespots.moderation'] + ['l','hidden',NS] + ['a',coord]/['e',id], plus an optimistic local hide. /review (AdminReviewPage, admin-only, 404 otherwise) lists spots that trip cheap signals (suspicious title, name ≤3 chars, no photo, no description, no geohash) sorted by flag count, with one-tap Hide or Not a skate spot; entry point is the admin-only AdminReviewCard in Settings → Advanced. Hiding is soft and reversible — the event stays on relays (honest for a censorship-resistant network); nothing is deleted. /review is in the smoke-test route list.
  • Symmetric verdicts + richer signals (2026-09-27): MODERATION_LABEL_VERIFIED is the positive counterpart to hidden. useAdminModeration fetches both labels in ONE query and exposes verifiedCoords/verifiedIds/isVerified() (plus a local mirror via addLocalConfirmed/getLocalConfirmed), and useAdminVerify() (same file as useAdminHide) publishes it. Using it, the review queue can Confirm a spot — which clears it from the queue and shows a "Verified by SkateSpots" badge on the spot page — instead of only ever hiding things. Queue flags now also include mapper trust (useBatchTrustScores) and whether any skater has filed a status report (useBatchSpotStatus reporterCount) → 'mapper not in your web of trust' / 'no community signals'. The flag logic is shared in src/lib/spotQuality.ts (used by both the page and AdminReviewCard, so they can't drift) and is deliberately heuristic — 'no community signals' only fires alongside another flag, so a brand-new real spot isn't punished for being new. Community signals now include other skaters' photos: useBatchSpotPhotos (useSpotContributions.ts) does ONE #a query for every spot and ignores the mapper's own photos.
  • Verdicts are reversible — latest wins (2026-09-28): MODERATION_LABEL_CLEARED ('cleared') is the neutral undo verdict. useAdminModeration no longer unions labels; it keeps the newest verdict per target (by created_at, with device-local verdicts overlaid by timestamp), so publishing cleared supersedes an earlier hidden/verified. useAdminClear() publishes it. The local mirror is now a verdict map (skatespots_local_admin_verdicts_v1, key = coord or e:<id>, value {verdict, at}), migrating the legacy hidden/confirmed arrays on read. useSkateSpots(limit, { includeHidden: true }) is admin-tooling only — without it a hidden spot leaves the list and can never be un-hidden. The review queue keeps actioned rows (badge + Undo) so both verbiage and verdicts are reversible in the UI.
• Reports reach the admin, duplicates are caught, contributors are told (2026-09-28): three gaps closed in one pass.
  1. Reports were a void. ReportDialog publishes NIP-56 (1984) for spots/ events/tours/users/listings/comments, but the ONLY reader in the app was a count on marketplace cards — an admin never saw a report. Now useSpotReports batch-reads kinds:[1984], '#e': [all spot ids] in ONE query (via querySkateContent), and the review queue ranks reported spots ABOVE the heuristics (red REPORTED: … chip). useNotASpotReport now publishes to getWriteRelays() (community relay + the reporter's) rather than the default pool, because the admin reads from the community relay — the same relay-parity rule as the newsletter and DMs. Verified end-to-end by publishing a report from Node and seeing it surface in the queue.
  2. Duplicate guard in CreateSpotPage: on submit, any existing spot within 60 m (geohash-decoded, ≤3 candidates) shows an inline warning listing them with distances and links, plus "It's a different spot — publish anyway" (dupConfirmedRef bypass). Designed for the clone-spam failure mode.
  3. Contributor feedback: useSkateSpot no longer returns null for a hidden spot when the viewer is its author — otherwise a moderated spot silently 404s for the person who made it. SpotDetailPage shows an author-only banner ("Hidden by a moderator" / "Verified by SkateSpots"). The verdicts are public labels, so there is nothing secret being revealed.
• Review queue covers every content kind (2026-09-28): /review now has tabs for spots / shops / events / tours / gear. The hide/verify labels were always kind-agnostic (a/e tags), so the work was: (1) add { includeHidden } (admin-tooling only) to useSkateShops, useSkateEvents, useTours and useMarketplaceItems — same reason as spots; (2) generalise the flags with contentFlags() in src/lib/spotQuality.ts (spot-specific signals — trust/status/photos — stay in spotFlags); (3) one small component per kind so only the OPEN tab queries (five hooks in one component would fire five relay queries on every visit). Reports (useSpotReports) and trust (useBatchTrustScores) are kind-agnostic; status/photo signals are spot-only. Status/go-lab/crew queues are still out — profiles are less spam-prone and hiding a crew hides a community.
• Profile badges (2026-09-28): lib/badges.ts + components/ProfileBadges. Two sources: (1) the built-in SkateSpots badge — derived from a nip05 ending @skate-spots.org (app logo → https://skate-spots.org/), so every issued handle gets it with no storage and it works for existing users; (2) user badges from a kind-0 badges array ({label, url?}), rendered as clickable chips (external links). The legacy newline sponsors field is carried forward into badges (parseBadges reads it; EditProfileForm now writes badges and deletes sponsors). Shown on the profile page (NIP19Page): the app badge in the header, user badges in a "Badges" card. ⚠️ NostrMetadata has no badges field, so it's read via a cast (metadata as … & Record<string, unknown>), like sponsors/cordn before it.
• Report → action + a publish floor (2026-09-28): the one-tap "not a skate spot" report used to only land in the admin queue (invisible effect). It now shows on the spot page to everyone ("Reported as not a skate spot by N — under review"), and useAutoHiddenSpots hides a spot from the map when ≥3 DISTINCT accounts reported it and it has no community signals (no community photo, no status report). The "no signals" clause is the anti-brigade guard; it is reversible (a photo/status, or an admin cleared/verified verdict, brings it back). useSpotReports now exposes reporters (distinct accounts). Publish floor: a spot now needs a photo OR a non-empty description (title + type alone no longer publishes) — photo stays optional, per the earlier decision. And the flattering "Conditions … NN/100" block is hidden until the spot is confirmed (community or staff); on an unconfirmed pin it read as endorsement of the spot.
• Photo is recommended, not required (2026-09-28): the hard block in CreateSpotPage was removed — it punished an honest mapper with no photo on hand. Publishing with no photo is allowed; the spot stays Unverified (SpotDetailPage badge), the success toast says so, and the review queue's 'no photo' flag lets a human look later. The pre-submit checklist still nudges.
• Map pin rendering (perf, 2026-09-29): the spot/tour/event/crew marker effect in SpotMap.tsx used to clearLayers() + rebuild every marker whenever the parent handed it fresh arrays, and added each marker with a per-marker clusterGroup.addLayer() (each call re-clusters the whole set) — several synchronous full rebuilds per load on a few-hundred-pin map. Now: (1) a marker signature (group geohash + spot/listing event ids + weather colour/icon + layer toggles) short-circuits the effect when nothing that affects the rendered pins changed — ids are enough because spot/listing/tour/ event/crew are all addressable (a new id on every edit), so unrelated array churn (trust scores, comment/zap totals, re-sorts) no longer rebuilds the map; (2) markers are collected and added with the plugin's bulk addLayers() in requestAnimationFrame batches of 150, cancelled on effect re-run. One cluster refresh per batch, pins paint progressively, main thread stays free. If you change what a marker renders, add it to the signature or the update will be skipped. showSpots/showShops/showGear are now effect deps.
• On-device OS notifications (Phase 1, 2026-09-29): src/components/OsNotificationBridge.tsx (mounted once in Layout, inert until opted in) mirrors the in-app activity — social (useActivityNotifications), crews (useCrewNotifications), newsletter (useNewsletterIssues) and DM gift-wrap ENVELOPES (useDmEnvelopes, no decrypt) — to the OS shade. Delivery is src/lib/osNotify.ts: web Notification API, native @capacitor/local-notifications (lazily imported; the dep was added so cap sync registers it — an installed APK must be rebuilt to pick it up). Prefs are device-local (useNotificationPrefs, key skatespots:notifications:prefs, opt-in, default OFF); UI is Settings → Notifications (NotificationSettingsCard). Hard rules, don't regress: (1) never decrypt to notify — DM alerts are envelope-only, so Amber is never prompted just to say "you have a message"; (2) per-source silent PRIMING + a seen-id set (skatespots:notifications:seen, ×600) so opening the app never replays history as a flood; (3) suppressed while the document is visible (the bell already covers that). Delivery is local only — a fully closed app/browser is unreachable without a server push. Phase 1b — scheduled reminders (2026-09-29): lib/reminders.ts + useLocalReminders hand the OS an alarm 1 h before each upcoming event the user RSVP'd going/interested. Native-only; the hook is mounted from the bridge only when prefs.reminders AND isNativePlatform(). Because the OS holds the alarm it fires with the app fully closed — the only closed-app notification achievable without a server. Scheduled ids live in skatespots:notifications:reminders; the hook cancels them all on unmount (opt-out / logout). New pref key reminders (default on). Pro-expiry reminder deliberately skipped — it would pull in the heavy useSasquatchPro query. ❌ Phase 2 (background runner) is DEAD — don't attempt it (verified 2026-09-29): Capacitor's Background Runner supports fetch but NOT WebSocket (v8 docs), and Nostr relays are WebSocket-only, so a runner physically cannot query relays while backgrounded. On-device background relay polling is not possible. Closed-app DMs/invites therefore need either (a) a push gateway (FCM; a server learns metadata "this pubkey has something" — content/sender stay hidden by NIP-17, timestamps are randomised) or (b) a foreground service keeping a native WS alive (no server, but a permanent notification + battery + custom native code). Owner decision (2026-09-29): HOLD at Phase 1 + 1b — the zero-server design stands and closed-app DMs/crew are a documented limitation, revisited only if it becomes load-bearing. useResolvedDmRelays is exported for the envelope hook.
• Cordn coordinator support (client-side, 2026-09-29): Cordn is an MLS delivery coordinator exposed as a ContextVM server over Nostr relays (E2EE; it sees ciphertext + metadata — who/when/which group). SkateSpots is a Cordn client only — we do not embed a coordinator in the APK and we don't run the default one (liability/centralisation — deliberate). Formats are taken from Cordn itself, not invented: a coordinator is an nprofile (pubkey + relay hints); its canonical add-link is https://cordn.net/chat/coordinators?c=<nprofile> (Cordn packages/server/src/main.ts); default relay wss://relay.contextvm.org; self-host is the docker run … ghcr.io/cordn-msg/cordn:latest one-liner. Files: src/lib/coordinator.ts (parse/encode/add-url/name), src/hooks/useCoordinator.ts (device-local store key skatespots:coordinator
  • useCoordinatorHealth), src/components/CoordinatorSettingsCard.tsx, Settings → Coordinator (?section=coordinator). Health is a presence probe, not Cordn RPC: query the coordinator's relays for authors:[pubkey] (its ContextVM announcement/heartbeat) — so an unannounced/private coordinator honestly shows "Not seen". "Run your own" is a hand-off (link to Cordn + copy Docker + scan its QR), never an embedded runtime — the phone-hosting story belongs to Cordn's own app. ⚠️ CORDN_APP_URL currently points at cordn.net; the exact Android-app deep link is unconfirmed — fill it in when known. Profile discovery (built 2026-09-29): the carrier is the existing kind-0 cordn field (app convention, documented in NIP.md — not a new kind). EditProfileForm accepts a pointer (nprofile / cordn.net link / npub / hex / http URL), normalises a bare pointer to Cordn's canonical add-link before saving (coordinatorAddUrl), and has "Use my coordinator". NIP19Page renders it as a Coordinator row with a one-tap Add (sets the viewer's useCoordinator, with toast) plus an "Open in Cordn" link — falling back to the old plain-link row when the value doesn't parse. ⚠️ Crew-level Cordn chat ALREADY EXISTS — do NOT rebuild it (2026-09-29): src/lib/cordn/{client,crypto,endpoint,types}.ts + useCordnChat.ts + CrewChat.tsx + crew/CrewCoordinatorCard.tsx, driven by a crew's coordinator tag ['coordinator', <url>, <coordinatorPubkey?>, <operatorPubkey?>] (SkateCrew.coordinator, parsed in types.ts, resolveCordnEndpoint() → CordnEndpoint), documented in NIP.md ("Private Crew Chat (Cordn / MLS)"). Every crew already has built-in NIP-17 E2E chat; the tag upgrades it to sealed NIP-44 over ContextVM. The only gap bridged this session: the crew form accepted a URL only, so a coordinator run from Cordn's phone app (an nprofile, not a URL) was un-enterable — CrewForm now uses the shared parseCrewCoordinatorInput / crewCoordinatorInputValue (lib/coordinator.ts) and has a "Use my coordinator" button that prefills from Settings → Coordinator. ⚠️ Transport reality (do not overclaim): a crew's wss:// coordinator URL is used AS A RELAY (resolveCordnEndpoint → relayUrl); an https:// one falls back to the public wss://relay.contextvm.org. The app publishes sealed kind-4497 events and queries them back — it does not call Cordn's coordinator RPC (FetchGroupMessages/SubscribeGroupMessages), so a real Cordn coordinator is not yet engaged, and an https:// coordinator puts ciphertext + metadata (crew coord, timing) on a public relay. CrewCoordinatorCard + CrewForm now say this honestly (2026-09-29). Still future: real MLS (ts-mls) instead of group-key crypto, plus Cordn RPC interop. Lesson: grep src for the feature before building it — this was nearly duplicated.
• Map layout — controls float (2026-09-29): on mobile the MapPage toolbar is absolute over the map (pointer-events-none wrapper + gradient + pointer-events-auto inner) so the map fills the whole container; md:static restores the in-flow bar on desktop. The container height subtracts header + bottom nav only (the old desktop --footer-desktop subtraction is gone) and the desktop footer is hidden on full-bleed routes (Layout footer: isFullBleed ? 'hidden' : 'hidden md:block'). Result at 390×844: map starts under the header and is ~86% of the viewport (was ~78%). Don't re-add a stacked toolbar or the footer subtraction. The "New here?" welcome banner (logged-out only) still occupies ~69px in flow on first visit — it's dismissible and the dismissal is persisted (skatespots_welcome_dismissed). ⚠️ The floating toolbar sits over Leaflet's default top-left zoom control, so MapPage passes className="h-full ss-map-floating-toolbar" and index.css offsets .leaflet-top.leaflet-left by 4.25rem only under max-width:767px (desktop toolbar is in flow, no offset). Verified at 390×844: zoom top 135px vs search bottom 108px.
• Empty-map nudge (2026-09-28): MapPage distinguishes the two empties — the existing "No spots match" card is for filters (filteredSpots.length === 0 && allLocations.length > 0) and a new "No spots mapped yet — be the first" card covers a genuinely empty map (allLocations.length === 0) with Add-spot + Near-me CTAs. ⚠️ Don't key it off mapSpots: that is derived FROM filteredSpots, so it is 0 whenever filters hide everything.
• Report inbox + bulk undo + crews/Lab moderation (2026-09-28): finishing the moderation gaps. /review now defaults to a Reports tab: useRecentReports fetches recent NIP-56 (1984) reports and resolves the referenced event by id (one extra ids: query) so ANY report is actionable — including content that isn't flagged and comments/profiles that never appear in the heuristic queue. reportTargetMeta(kind) maps a kind to its label + route for the "Look at it" link. The queue also has crews and lab tabs (added includeHidden to useCrews/useLabProfiles); because hiding those removes a community or a person's listing rather than one pin, their Hide button goes through an AlertDialog confirmation (confirmHide/confirmHideNote on QueueList). When a tab holds more than one verdict, a toolbar offers Undo all N (also AlertDialog-gated, and it warns that each undo is a separate label publish — one Amber approval each). Verified in the browser: 8 tabs render, the inbox shows and resolves a real report, and the Spots tab shows the bulk-undo toolbar.
• App listing submitted (2026-09-28): SkateSpots was added to the community nostrapps.com directory by PR. Recipe (ngit has an active remote-signer session, so this works non-interactively — no browser needed): git clone https://relay.ngit.dev/npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkwsyjh6w6/nostrapps-com.git → edit apps.toml (one [app-id] table; keys seen in the file: name, categories, description, gallery?, features, npub, platforms, source?, thumb, url) → git remote add nostrapps nostr://<owner-npub>/nostrapps-com → git push -o 'title=…' -o 'description=…' -u nostrapps <branch>:pr/<branch>. Opening a PR = pushing a pr/-prefixed branch; ngit pr list|view|apply. Our PR: bbb27a91… "Add SkateSpots", open. The gallery images live at public/images/screenshots/{map,spot,marketplace}.png (1280×800, quantised — captured with headless Chromium; regenerate with a CDP harness if the UI changes materially).
• NIP-05 names — you@skate-spots.org (2026-09-28): SkateSpots hands out free handles so a new skater has a human name from minute one. The registry is the Netlify Function netlify/functions/nip05.mjs (/.well-known/nostr.json + /api/nip05/{check,claim,release}), backed by Netlify Blobs (@netlify/blobs, store nip05, one key per name) — no new vendor, no new secret. Rules: non-gating (a handle is a badge, never a key — the app works without one), proof by signature (a claim carries a NIP-98 kind-27235 event in the x-nip05-auth header, signed by the pubkey that will own the name), and onlyIfNew writes so two claims can't clobber each other. Platform names are seeded in code (skate-spots/skatespots → owner pubkey, skater → the second admin caba497f…) and cannot be claimed/released by users; a small RESERVED list blocks impersonation words. Any admin can wear a seeded handle by typing it in Edit Profile → NIP-05 (it verifies against the seed; no claim needed). Client: src/lib/skateNip05.ts (shared validation, deriveSkateNip05Handle, parseSkateNip05, skateApiBase() for the native absolute-URL rule), src/hooks/useSkateNip05.ts (check/claim/release), and src/components/SkateNip05Input.tsx (debounced availability + Claim). Wired into signup (SignupDialog profile step adds a "SkateSpots name" field, prefilled from the display name until edited; the handle is claimed best-effort before the kind-0 publish, and a failure never blocks signup — a profile only advertises nip05 once the registry confirms it) and into Edit Profile (Nip05Field gains a "claim a free handle" block). Settings → NIP-05 links to it. ⚠️ config.path DOES take precedence over the /* SPA redirect for /.well-known/* (verified on a draft deploy). Test functions with a free draft (netlify deploy --dir=dist), not a prod deploy. Verified end-to-end on a draft (2026-09-28): claim → resolves → a second key gets 409 → release → gone.
• Offline / dead-relay behaviour (2026-09-28): the app is a utility, so a relay outage must degrade, not blank. ⚠️ querySkateContent used to swallow every relay error and return [], so a dead relay looked like "no spots" AND overwrote good cached data with an empty list (which the persister then saved). Now:
  • querySkateContent / queryCanonical take an opt-in requireAny that throws when NO relay answered. Only the map's own feeds pass it (useSkateSpots, useShops, useMarketplaceItems, useTours); the other ~75 call sites keep the old behaviour, deliberately.
  • useSkateSpots / useSkateSpot catch that error and fall back to the Dexie spot cache (lib/offlineCache), so the map still works at the park; they only re-throw when nothing is cached (UI shows an offline card).
  • shouldDehydrateQuery never persists an empty array — otherwise one blip would wipe the persisted map for the next 24h.
  • MapPage shows "Offline · showing saved spots" + retry, and a "Can't reach the relays" card instead of the false "No spots mapped yet". ⚠️ Two distinct signals (fixed 2026-09-29): the saved-spots banner is driven by deviceOffline (!useOnlineStatus()) only — it used to also key off the single SKATE_RELAY probe, but the map reads from several relays, so it stuck around online while fresh data loaded fine, and its retry never re-probed. The banner is also dismissible (re-armed when the connection returns). The relay probe still gates the "nothing at all" card (relayUnreachable = !online || relay.status === 'offline'), and both retries now call refetchSpots() and relay.recheck().
  • Offline WRITE queue is now real (2026-09-29). lib/offlineCache already had a pendingPosts table + useSyncPendingPosts/useQueuePost + an OfflineIndicator badge, but nothing ever called queuePost — offline writes just threw. Now: useNostrPublish queues on isOffline() (skipping the 15s publish timeout) or when every relay fails, storing the already-SIGNED event (queueSignedEvent) so an interactive signer is never re-prompted at sync time; useSyncPendingPosts publishes it directly (nostr.event), not through useNostrPublish (which would re-queue and duplicate), re-signing only legacy unsigned entries. Rules: supersede — a new replaceable (0/3/10000+) or addressable (30000+) event drops the older queued one; TTL — ephemeral kinds (2259 spot status, 24899 spot chat) are pruned after 15 min (late "I'm here" is worse than none); cap 100; getPendingPosts returns pending and retryable failed (a single failure must not strand an action) and the count includes both; a module-level globalSyncing lock keeps ONE publisher even though OfflineIndicator (which owns the sync) is mounted twice; retries every 30s while offline→online. ⚠️ useNostrPublish now resolves (instead of throwing) when it queues — callers show their success toast, corrected by a global "Saved offline" toast + the badge.
  • Stash is readable offline + backed up (2026-09-29). The private stash (NIP-51 kind 30001, d=skatespots-stash, NIP-44 encrypted to self) was deny-listed from React Query persistence with NO local cache, so an offline/relay-outage cold start showed an EMPTY stash even though decryption needs no network. Now the encrypted CIPHERTEXT is cached in Dexie (offlineCache v2 stash table — cacheStashEvent/getCachedStashEvent), and both the read query and fetchLatestStash (the pre-write re-fetch) fall back to it — so the stash still loads at the park and an offline edit rebuilds from the real list instead of throwing. Only ciphertext is stored, never the decrypted list. Also added Export/Import on /stash (Backup & transfer card, desktop sidebar + mobile): export writes a JSON you control; import appends in ONE re-encrypt, skipping title+category+size duplicates (importItems).
  • Offline map tiles (done 2026-09-28): lib/tileCache.ts (Dexie SkateSpotsTilesDB, bounded: ≤3000 tiles, ≤500 KB each, oldest-used pruned)
    • lib/cachedTileLayer.ts (an L.TileLayer subclass that reads through it), used by both maps (SpotMap, RouteDialog). Deliberately NOT a service worker: a SW only helps the web build, while the Android app runs inside Capacitor's WebView where a SW never sees tile requests. Works on both. Still open: offline app shell (SW) — unnecessary for native, deferred for web.
• Photo redundancy (2026-09-28): useUploadFile now uses two Blossom hosts (blossom.primal.net, blossom.band) instead of three. ⚠️ BlossomUploader.upload signs ONE auth event then does Promise.any(servers.map(fetch)) — it PUTs to every server in parallel, so the old 3-host list was silently triple-uploading every photo (the code comment claiming "tries them in order" was wrong). Two hosts = less client data, still a single signature (no extra Amber prompt). The returned tags gain ['fallback', '<mirror-host>/<sha256>'], and lib/imageFallback.ts + ImageWithFallback retry the same hash on the other known Blossom host on error — one choke point covers every photo/logo call site (~20), so a dead host costs a moment, not a blank spot. Blossom is content-addressed, so the mirror URL is derived from the sha256 in the path (handles /<sha> and /<sha>.<ext>).
• AI proxy on our own host (ai-proxy/, 2026-09-28): the same proxy the Netlify Function runs, rebuilt as a standalone Bun service on the CVM host so AI calls stop spending Netlify compute/bandwidth credits and the Routstr key lives on our box. ai-proxy/server.ts (Bun.serve on 127.0.0.1:8787; NIP-98 + Pro gate + model allowlist + per-IP throttle), deployed with npm run deploy:ai (scripts/deploy-ai-proxy.sh) to /home/ubuntu/skatespots-ai, systemd unit skatespots-ai, type-checked by ai-proxy/tsconfig.json (typecheck:ai, wired into npm test); ai-proxy/ is eslint-ignored like cvm-server/. Env (SASQUATCH_*) copied from Netlify env to ~/skatespots-ai/.env (600); verified live (POST /api/ai/status → the real Routstr balance). The client picks the base in one place — src/lib/sasquatchAi.ts (sasquatchAiBase(), also used for the NIP-98 u tag). Live (2026-09-28): ai.skate-spots.org → the CVM host (an A record in Netlify DNS; ⚠️ the API silently dropped the first create — verify the NS actually serves a new record), TLS via Caddy (auto Let's Encrypt, installed on the host). Production builds now default to it (import.meta.env.PROD → https://ai.skate-spots.org/api/ai); dev uses local /api/ai. ⚠️ netlify/functions/ai.mjs is now a fallback only — revert with VITE_SASQUATCH_AI_BASE=https://skate-spots.org/api/ai.
• Mints directory: /mints page lists Cashu mints from the community MintRadar project. MintRadar has no CORS, so it's fetched same-origin at /api/mints/* — prod proxies via public/_redirects (/api/mints/* → https://mintradar.org/api/mints/:splat 200), dev via server.proxy in vite.config.ts. Data is unofficial/rate-limited; adding a mint is native-only. ⚠️ vite.config.ts's server.proxy also covers /api/nip05 → https://skate-spots.org and /api/ai → https://ai.skate-spots.org (2026-09-28). Without them the dev server answers those production-only endpoints with index.html, so the NIP-05 availability check showed "Could not check right now" on localhost and dev AI silently fell back to Pollinations. (Prod is unaffected — the functions are same-origin there.) ⚠️ Relative /api/* paths don't work in the native app (fixed 2026-09-27): the shell is served from https://localhost, so /api/mints/known hits the LOCAL asset server and returns index.html → Unexpected token '<' … not valid JSON. useMintDirectory now uses https://skate-spots.org/api/mints/known via CapacitorHttp on native (core plugin, no CORS) with a plain-fetch fallback, and turns an HTML body into a friendly message. Same pattern already used by sasquatchBrain.ts / useSasquatchAiStatus (Capacitor.isNativePlatform() ? 'https://skate-spots.org/api/…' : '/api/…') — follow it for any new /api call, and never let a raw JSON parse error reach the UI.
• Lazy routes: every route uses lazyWithRetry (src/lib/lazyWithRetry.ts) — retries, then one full reload per session, so a chunk-load failure self-heals instead of showing the error boundary.
• Baselines (verified 2026-09-27): npm test → 0 errors, 0 warnings, 101 tests, build ok. The gate also type-checks the CVM server (tsc -p cvm-server/tsconfig.json). package.json version 1.5.4.
  • ✅ Lint is clean: no-explicit-any = 0 · react-hooks/exhaustive-deps = 0 · no-unused-vars = 0 · react-refresh = 0. Non-component exports were split into their own modules (contexts/language.ts, lib/sortOptions.ts, lib/trustFilter.ts) and unused hooks/functions deleted — no blanket disables. Keep it at zero — don't reintroduce any.
  • ⚠️ Do not mass-fix no-unused-vars by name or blanket rename — shadowed names and typed shorthand destructuring make it unsafe. Fix position-precise. Renaming a component to _Name also trips rules-of-hooks — delete it or suppress instead.
• Untracked local junk — do NOT commit (add to .gitignore, not the repo): assets/, resources/, /bun.lock, cvm-server/bun.lock, cvm-server/package.json (local dev copy of the tracked package.cvm.json), *.bak. (cvm-server/ source IS tracked — only its locks/backups are junk.) Watch out: git add -A in the repo root sweeps these in.
• Never git add -A from the repo root without checking git status first.

Local Dev Environment, Build & Release (project-specific — read first)

Machine-specific, verified operational notes. Use these instead of re-deriving workflows from scratch.

Where things are

• Dev root / repo: /home/sovereignsk8/SkateSpots — the clone whose origin is the nostr:// remote.
• origin: nostr://npub1yrnuj56rnen08zp2h9h7p74ghgjx6ma39spmpj6w9hzxywutevsst7k5cx/git.shakespeare.diy/SkateSpots (browsable at nostrhub.io).
• Live site: https://skate-spots.org — served by Netlify, deployed via shakespeare.diy (which also hosts the git server).
• Backups: ~/.backups/ (nested clone, old lockfiles, keystore copies).

Toolchain (already installed on this machine)

Node 22 + npm 10 · Bun 1.3 · Java 21 · Android SDK at ~/Android/Sdk · ngit 3.0.3 (~/.cargo/bin) · zsp (~/.local/bin).

Run & validate

• npm run dev → http://localhost:8080. Note the script runs npm i first (see lockfile caveat).
• npm test = npm i + tsc + eslint + vitest + vite build. Must pass before committing.

⚠️ "This page slammed" on some routes in dev (dep optimizer cache)

Symptom: in the running dev server a few lazy routes (e.g. /settings, /stash, /collections, /stats) show the "This page slammed" error boundary while others work. The browser console shows Failed to fetch dynamically imported module and the network tab shows 504 for node_modules/.vite/deps/*.js?v=….

• Cause: Vite's dependency optimizer cache (node_modules/.vite/deps) went missing/was invalidated while the dev server stayed up (long-running servers re-optimize whenever the lockfile changes — and every npm i, which dev/test/build run, touches package-lock.json). The server keeps serving stale ?v= hashes → 504 → React.lazy rejects.
• Fix: restart the dev server (rm -rf node_modules/.vite then npm run dev) and hard-refresh the browser. npm i / vite build / vitest alone do not wipe the cache — it's the long-running server's re-optimize that races.
• Resilience: all routes use lazyWithRetry (src/lib/lazyWithRetry.ts) instead of bare lazy(). On a chunk-load failure it retries once, then performs a single full page reload per session, so a transient optimizer/deploy hiccup self-heals instead of dead-ending on the error boundary.

⚠️ Lockfile caveat (important)

The committed package-lock.json (from commit f25fc2b) had entries stripped of dependencies/bin metadata, so transitive packages were silently missing. Repaired in eb23ebc (654 → 902 packages).

• Regression symptoms: npx cap → "could not determine executable to run"; tsc → "Module '@nostrify/nostrify' has no exported member NostrEvent"; Vite → "Could not resolve @std/encoding/hex".
• Do NOT regenerate the lock blindly — a fresh resolve bumps ~300 packages incl. major @babel 7→8 and esbuild 0.25→0.28. Prefer npm ci. If broken, repair each entry's dependencies/bin from the installed node_modules/*/package.json, then npm install to fill only the gaps.

Android release build

• npm run android:build → android/app/build/outputs/apk/release/app-release.apk.
• Versioning: package.json version is the single source of truth; scripts/sync-android-version.mjs syncs it to versionName/versionCode (e.g. 1.4.5 → 10405) during the build. Bump only package.json.
• Signing: secrets live in the gitignored keystore.properties; scripts/inject-signing-config.mjs injects a managed block into android/app/build.gradle (runs in android:init/android:sync/android:build). The authoritative keystore is /home/sovereignsk8/skatespots-release.jks (alias skatespots). An older repo-root copy had a wrong password and was retired to ~/.backups/keystore/.
• android/ is generated and gitignored; recreate with npm run android:init.
• Preflight: cd android && ./gradlew :app:signingReport confirms the signing config resolves.

Version bump + release notes

1. Bump package.json version (Zapstore rejects an already-published version).
2. Update the top section of release-notes.txt (format: vX.Y.Z, blank line, notes, then --- before older versions).

⚠️ Production-bundle runtime ≠ dev (read before touching vite.config)

vite build only bundles; it never executes the output, and dev mode doesn't either. A build can compile cleanly and still crash at runtime — that's how the old custom manualChunks() shipped a white screen to production: ReferenceError: Cannot access 'X' before initialization (cross-chunk circular import TDZ, first in vendor-charts, then vendor-bitcoin). It only affected the web build; the Capacitor build uses inlineDynamicImports (single bundle) and was unaffected.

Rules:

• Do not re-introduce custom manualChunks without a boot test. Rollup's default splitting is cycle-safe.
• scripts/smoke-test.mjs boots the built dist/ in headless Chromium and fails if #root doesn't mount or if any route shows the "This page slammed" error boundary. It walks each route in the URL hash (HashRouter!): /, /marketplace, /leaderboards, /bounties, /settings, /stash, /collections, /stats, /messages/group/abc123. scripts/auto-deploy.sh runs it before every deploy and aborts the deploy if it fails.
• Any time the deploy output isn't verified by the smoke test, run node scripts/smoke-test.mjs manually before shipping.

Deploy

• Web (auto): a systemd user timer (skatespots-deploy.timer) runs scripts/auto-deploy.sh every ~3 min. When origin/main changes it builds and runs netlify deploy --prod --dir=dist. It deploys only committed code (skips if tracked files are modified) and never mutates a dirty tree. Doc/scripts-only commits are skipped (matches AGENTS.md/*.md/scripts//cvm-server//skills/) — Netlify bills 15 credits per production deploy, so don't spend them on non-site changes. One-time setup: netlify login + netlify link. Logs: journalctl --user -u skatespots-deploy. Manual run: scripts/auto-deploy.sh.
  • ⚠️ Deploy throttle (2026-09-28): production deploys are capped to one per 24h by default (after a week of 68 deploys ≈ 1,020 credits — a third of the monthly allowance). Batching a day's commits into one 15-credit deploy is the single biggest credit lever. Override with SKATESPOTS_DEPLOY_MIN_INTERVAL=<seconds> (0 disables); deploy on demand with scripts/auto-deploy.sh --force. A throttled tick deliberately records nothing, so the pending change still deploys on a later tick; a failed deploy doesn't set the clock, so it retries immediately.
  • ⚠️ Shakespeare's "Deploy" rebuilds its own workspace, which is NOT updated by git pushes — so pushing to the repo does not change what Shakespeare deploys. Prefer the auto-deploy timer (or drag dist/ to Netlify).
• Web (manual): npm run build produces the web dist/ (with _headers/_redirects); deploy by dragging dist/ to the Netlify site's Deploys tab.
• Zapstore (Android), from the repo root: SIGN_WITH='bunker://...' zsp publish zapstore.yaml
  • zsp publish --wizard is broken for this app (the wizard can't parse a nostrhub web repository — it supports only GitHub/GitLab/Gitea/F-Droid/local). Always pass zapstore.yaml.
  • No NIP-07 browser extension is installed, so SIGN_WITH=browser fails. Use bunker://… (Amber) or nsec1….
  • zapstore.yaml sets release_source → local APK, release_notes → release-notes.txt, icon → public/images/icon-1024.png.
  • Dry run (no upload): SIGN_WITH='<signer>' zsp publish --offline zapstore.yaml.

Relay archive (dataset backup)

• scripts/archive-relay.mjs snapshots the app's own content off the community relay to gzipped JSONL of the raw signed events (restorable to any relay, signatures intact). Default dir ~/.backups/relay (override with SKATESPOTS_ARCHIVE_DIR), keeps the last 12, and writes manifest-*.json + latest.json (counts by kind, author count, sha256, byte size).
• ⚠️ goskatespots.nostr1.com is a PUBLIC relay with general traffic (verified 2026-09-28): 15.7k kind-0 profiles, mostly non-skaters; 2k kind-30078 app-data (Armada/Plebs/Amethyst); 379 kind-30023 articles (Yakihonne); 408 NIP-99 listings (Shopstr). So the archive is deliberately scoped — exclusive kinds wholesale (30818/30017/30823/35xxx/…), shared kinds only with the app's own tags (t=skateboarding for events + listings, t=skatespots collections, t=skatespotsnews newsletters, d=skatespots* app data), org.skatespots.* labels, reports/RSVPs that reference archived content, and kind-0 profiles for archived authors only. Result: ~114 events / ~63 KiB. Never archive the whole relay — it is strangers' data, and a restore would republish it.
• ⚠️ Query ONE kind at a time, and stop on "no new events", not on a short page. A single filter covering many kinds comes back truncated (once kept only 3 of 54 spots), and querySync can resolve early on a large page (lost ~150 of 3.3k profiles). Paginate with until until a page adds nothing.
• scripts/restore-relay.mjs <archive.jsonl.gz> --dry-run re-verifies every signature; --to wss://relay republishes. There is no default target — restoring is deliberate, and the mistake to avoid is publishing a snapshot back to the live relay. Use scripts/drill-relay.mjs as the throwaway target.
• Offsite: scripts/backup-relay.sh runs the archive, then restic backup + forget --prune if ~/.config/skatespots/restic.env exists (template: scripts/restic.env.example). Configured (2026-09-28): the CVM host over SFTP, repo sftp:skatespots-cvm:/home/ubuntu/skatespots-backups/relay, via an ~/.ssh/config alias skatespots-cvm (HostName/User/IdentityFile from ~/.config/skatespots/cvm.env) so no key/host lives in tracked files. ~/.config/skatespots/restic.env (600, outside the repo) holds the repo URL + the generated RESTIC_PASSWORD — that password is required to restore; keep a copy in a password manager. A second offsite is supported: put another repo (e.g. Cloudflare R2 / Backblaze B2) in ~/.config/skatespots/restic-2.env and backup-relay.sh pushes to both — true 3-2-1 (local + CVM + object storage). Verified 2026-09-28 with a throwaway second repo.
  • ⚠️ Don't run restic under a restrictive umask. restic creates its cache dirs from the umask, and a mode-600 dir has no execute bit → "permission denied" on ~/.cache/restic/<repo>/version. If it happens: find ~/.cache/restic -type d ! -perm -u+x -exec chmod u+rwx {} +.
• Restore drill (proven 2026-09-28): node scripts/drill-relay.mjs [port] starts a throwaway in-memory NIP-01 relay (ws, no persistence); then node scripts/restore-relay.mjs <archive> --to ws://localhost:<port> and query it back. Latest run: 114/114 events restored, 0 missing. Re-run after any archive-format change, or quarterly.
• restic check --read-data-subset=10% was clean after the first offsite push (do this monthly to catch bitrot, not just existence).
• Weekly systemd user timer: scripts/install-archive-timer.sh copies scripts/systemd/skatespots-archive.{service,timer} into ~/.config/systemd/user and enables them. Logs: journalctl --user -u skatespots-archive.
• Commits touching only scripts/, *.md, cvm-server/, skills/, .agents/ are skipped by the deploy timer → no Netlify credits spent.

Git / ngit publishing

• Push: git push origin main (handled by git-remote-nostr; publishes a signed repo-state event).
• Login (once): ngit account login --interactive → scan the QR in Amber ("Add a new application → Connect app"). Plain ngit account login errors; the --interactive flag is required.
• The NIP-65 write list contains a dead relay (wss://wotr.relatr.xyz), which makes ngit repo edit fail unless run with --repo-relay-only. Local git config nostr.repo-relay-only true is set as a workaround. Fully fix by removing that relay in the app (Settings → Relays). Done in defaults 2026-09-28: removed from App.tsx defaultConfig, NostrSync NEW_USER_RELAYS, NostrProvider DEFAULT_RELAYS, TestApp, and the CVM DEPLOY.md example. ⚠️ Existing accounts keep it in their stored config until they remove it themselves (no migration applied).
• git push may print a benign cannot lock ref ... incorrect old value provided retry warning; verify with git fetch origin && git rev-list --left-right --count origin/main...HEAD.

Secrets — never commit or paste

keystore.properties, *.jks, .env*, and android/ are gitignored. Never paste the nsec or keystore password into chat, logs, or command history — keep them in a password manager.

Project Structure

• /skills/: Specialized implementation guides for specific features - each skill has a comprehensive SKILL.md file with complete patterns, code examples, and best practices. See the Skills Directory section below for details on available skills.
• /src/components/: UI components including NostrProvider for Nostr integration
  • /src/components/ui/: shadcn/ui components (48+ components available)
  • /src/components/auth/: Authentication-related components (LoginArea, LoginDialog, etc.)
  • Zap components: ZapButton, ZapDialog, WalletModal for Lightning payments
• /src/hooks/: Custom hooks including:
  • useNostr: Core Nostr protocol integration
  • useAuthor: Fetch user profile data by pubkey
  • useCurrentUser: Get currently logged-in user
  • useNostrPublish: Publish events to Nostr
  • useUploadFile: Upload files via Blossom servers
  • useAppContext: Access global app configuration
  • useTheme: Theme management
  • useToast: Toast notifications
  • useLocalStorage: Persistent local storage
  • useLoggedInAccounts: Manage multiple accounts
  • useLoginActions: Authentication actions
  • useIsMobile: Responsive design helper
  • useZaps: Lightning zap functionality with payment processing
  • useWallet: Unified wallet detection (WebLN + NWC)
  • useNWC: Nostr Wallet Connect connection management
  • useNWCContext: Access NWC context provider
• /src/pages/: ~50 route pages (MapPage is the homepage; see AppRouter.tsx)
• /src/lib/: shared logic — types.ts (custom kind constants), lazyWithRetry.ts, queryPersister.ts, helpers
• /src/contexts/: React context providers (AppContext, LanguageContext, NWCContext)
• NIP.md: source of truth for every custom/adopted Nostr kind and its schema
• AGENTS.md (this file): the only cross-session memory — keep it current
• UX_AUDIT.md, GROUP_MESSAGING.md, ESCROW.md: feature decision/backlog docs
• /src/test/: Testing utilities including TestApp component
• /public/: Static assets
• App.tsx: Main app component with provider setup (CRITICAL: this file is already configured with QueryClientProvider, NostrProvider, UnheadProvider and other important providers - read this file before making changes. Changes are usually not necessary unless adding new providers. Changing this file may break the application)
• AppRouter.tsx: React Router configuration

CRITICAL: Always read the files mentioned above before making changes, as they contain important setup and configuration for the application. Never directly write to these files without first reading their contents.

UI Components

The project uses shadcn/ui components located in @/components/ui. These are unstyled, accessible components built with Radix UI and styled with Tailwind CSS. Available components include:

• Accordion: Vertically collapsing content panels
• Alert: Displays important messages to users
• AlertDialog: Modal dialog for critical actions requiring confirmation
• AspectRatio: Maintains consistent width-to-height ratio
• Avatar: User profile pictures with fallback support
• Badge: Small status descriptors for UI elements
• Breadcrumb: Navigation aid showing current location in hierarchy
• Button: Customizable button with multiple variants and sizes
• Calendar: Date picker component
• Card: Container with header, content, and footer sections
• Carousel: Slideshow for cycling through elements
• Chart: Data visualization component
• Checkbox: Selectable input element
• Collapsible: Toggle for showing/hiding content
• Command: Command palette for keyboard-first interfaces
• ContextMenu: Right-click menu component
• Dialog: Modal window overlay
• Drawer: Side-sliding panel (using vaul)
• DropdownMenu: Menu that appears from a trigger element
• Form: Form validation and submission handling
• HoverCard: Card that appears when hovering over an element
• InputOTP: One-time password input field
• Input: Text input field
• Label: Accessible form labels
• Menubar: Horizontal menu with dropdowns
• NavigationMenu: Accessible navigation component
• Pagination: Controls for navigating between pages
• Popover: Floating content triggered by a button
• Progress: Progress indicator
• RadioGroup: Group of radio inputs
• Resizable: Resizable panels and interfaces
• ScrollArea: Scrollable container with custom scrollbars
• Select: Dropdown selection component
• Separator: Visual divider between content
• Sheet: Side-anchored dialog component
• Sidebar: Navigation sidebar component
• Skeleton: Loading placeholder
• Slider: Input for selecting a value from a range
• Switch: Toggle switch control
• Table: Data table with headers and rows
• Tabs: Tabbed interface component
• Textarea: Multi-line text input
• Toast: Toast notification component
• ToggleGroup: Group of toggle buttons
• Toggle: Two-state button
• Tooltip: Informational text that appears on hover

These components follow a consistent pattern using React's forwardRef and use the cn() utility for class name merging. Many are built on Radix UI primitives for accessibility and customized with Tailwind CSS.

Skills Directory

The project includes a skills/ directory containing specialized implementation guides for specific features. Each skill has a comprehensive SKILL.md file with complete patterns, code examples, and best practices. Always reference the appropriate SKILL.md file when implementing related functionality.

Wallet Skills

• skills/bitcoin-wallet/SKILL.md: Use when implementing Bitcoin wallet features - provides complete architecture for on-chain Bitcoin transactions, UTXO management, address derivation from Nostr keys, and transaction handling with proper security patterns. Read when building Bitcoin wallet functionality, adding on-chain transaction support, implementing UTXO management, or integrating Bitcoin with Nostr-based applications.

• skills/lightning-wallet/SKILL.md: Use when implementing a standalone Lightning wallet using Cashu mints - provides complete patterns for minting (receiving Lightning payments), melting (sending Lightning payments), mint management, transaction history, and integrating with Lightning addresses and invoices. Read when building a Lightning wallet with Cashu mints, implementing Lightning payment flows (send/receive), managing Cashu mints, processing Lightning invoices, or integrating Lightning address functionality with a custodial wallet.

• skills/cashu-wallet/SKILL.md: Use when implementing Cashu token wallet functionality - provides complete patterns for sending and receiving Cashu tokens, token QR codes, automatic mint management, and integrating with Lightning wallet operations. Read when building a Cashu token wallet, implementing token send/receive operations, handling Cashu token transfers, managing token QR codes, or building a full-featured wallet that combines both Lightning and token operations.

• skills/nostr-wallet-connect/SKILL.md: Use when implementing Nostr Wallet Connect (NIP-47) wallet service - provides complete patterns for generating NWC connection strings, publishing info events, listening for requests, processing wallet commands, and sending encrypted responses. Client-side patterns included for reference. Read when building wallet services that expose Lightning functionality via NWC, generating NWC connection URIs for clients, implementing NIP-47 wallet service functionality, or handling encrypted wallet communication over Nostr relays.

Lightning Integration Skills

• skills/lightning-address/SKILL.md: Use when implementing Lightning address functionality - provides complete patterns for resolving Lightning addresses to invoices, generating invoices from addresses, displaying Lightning addresses in UI, and integrating with QR codes. Read when adding Lightning address support, implementing LNURL-pay protocol, generating invoices from Lightning addresses, displaying Lightning addresses in wallet UIs, or integrating Lightning addresses with QR code functionality.

• skills/lightning-invoice-decoder/SKILL.md: Use when implementing BOLT11 Lightning invoice decoding - provides complete patterns for decoding invoice amounts, validating invoice format, and extracting satoshi values from Lightning invoices. Read when adding Lightning invoice parsing, validating BOLT11 invoices, extracting payment amounts from invoices, or implementing Lightning payment flows.

• skills/npub-cash-address/SKILL.md: Use when implementing npub.cash static Lightning address functionality - provides complete patterns for obtaining static Lightning addresses (username@npubx.cash), managing npub.cash account settings, syncing quotes from npub.cash, and integrating with Lightning wallets. Read when building Lightning wallet features that need static addresses, implementing npub.cash integration, managing user Lightning addresses, or syncing quotes from npub.cash to Cashu wallets.

Utility Skills

• skills/qr-code-generator/SKILL.md: Use when implementing QR code generation - provides complete patterns for generating QR codes from text/URLs, displaying QR codes in modals, and customizing QR code appearance. Read when adding QR code generation functionality, displaying QR codes for addresses/invoices, or generating QR codes for sharing content.

• skills/qr-code-scanner/SKILL.md: Use when implementing QR code scanning - provides complete patterns for camera-based scanning, classifying scanned content (Bitcoin addresses, Lightning invoices, npubs, Cashu tokens), handling camera permissions, and paste from clipboard functionality. Read when adding QR code scanning functionality, implementing camera-based scanning, classifying scanned QR content, or handling QR code input from users.

• skills/exchange-rates/SKILL.md: Use when implementing exchange rate functionality - provides complete patterns for fetching BTC/fiat exchange rates from Coinbase API, caching strategies, conversion utilities, and React hooks for displaying rates in UI. Read when adding exchange rate display, converting between BTC and fiat currencies, showing USD equivalents for Bitcoin amounts, or implementing currency conversion features.

Steganography Skills

• skills/emoji-encoder/SKILL.md: Use when implementing steganographic text encoding using Unicode Variation Selectors - allows encoding any message invisibly into emojis, letters, or any characters using Unicode Variation Selectors (U+FE00-U+FE0F and U+E0100-U+E01EF). Read when adding steganographic encoding, hiding data in plain text, encoding messages into emojis/characters, or implementing invisible data encoding using Unicode Variation Selectors.

• skills/lsb-steganography/SKILL.md: Use when implementing Least Significant Bit (LSB) steganography - allows hiding images or text within other images by encoding data in the least significant bits of pixel color channels. Read when adding steganographic image encoding, hiding images within images, encoding text into images, implementing invisible data storage in images, or building privacy-preserving image sharing features.

System Prompt Management

AGENTS.md is the assistant's system prompt and its only persistent memory. Future sessions start with nothing but this file, so treat it as the project's long-term memory:

1. Edit AGENTS.md directly when you learn something important or when a described detail has changed.
2. Changes take effect in the next session — so record now, not "later".
3. Re-read the relevant section before relying on it; if it's out of date, fix it in the same session rather than working around it.

Credits — no MKStack / Shakespeare (owner decision, 2026-09-28)

⚠️ This used to say: "include 'Vibed with MKStack' somewhere in the UI, linked to https://soapbox.pub/mkstack". The owner removed it on request — do NOT re-add it. /about → Credits no longer mentions MKStack or Shakespeare, and the "Nostr" credit links to the protocol repo (https://github.com/nostr-protocol/nostr), not nostr.com.

The credits should read (keep this shape when editing): Nostr (protocol) · Cordn (crew chat, cordn.net) · Cashu (ecash, cashu.space) · NWC (docs.nwc.dev) · Amber (Android signer) · BTCMap (btcmap.org) · Angor · Zapstore · ContextVM. (useShakespeare.ts, proxy.shakespeare.diy and similar are internal endpoints/hook names, not credits — leave them.)

Nostr Protocol Integration

This project comes with custom hooks for querying and publishing events on the Nostr network.

Nostr Implementation Guidelines

• Always check the full list of existing NIPs before implementing any Nostr features to see what kinds are currently in use across all NIPs.
• If any existing kind or NIP might offer the required functionality, read the relevant NIPs to investigate thoroughly. Several NIPs may need to be read before making a decision.
• Only generate new kind numbers if no existing suitable kinds are found after comprehensive research.

Knowing when to create a new kind versus reusing an existing kind requires careful judgement. Introducing new kinds means the project won't be interoperable with existing clients. But deviating too far from the schema of a particular kind can cause different interoperability issues.

Choosing Between Existing NIPs and Custom Kinds

When implementing features that could use existing NIPs, follow this decision framework:

1. Thorough NIP Review: Before considering a new kind, always perform a comprehensive review of existing NIPs and their associated kinds. Get an overview of all NIPs, and then read specific NIPs and kind documentation to investigate any potentially relevant NIPs or kinds in detail. The goal is to find the closest existing solution.

2. Prioritize Existing NIPs: Always prefer extending or using existing NIPs over creating custom kinds, even if they require minor compromises in functionality.

3. Interoperability vs. Perfect Fit: Consider the trade-off between:

   • Interoperability: Using existing kinds means compatibility with other Nostr clients
   • Perfect Schema: Custom kinds allow perfect data modeling but create ecosystem fragmentation

4. Extension Strategy: When existing NIPs are close but not perfect:

   • Use the existing kind as the base
   • Add domain-specific tags for additional metadata
   • Document the extensions in NIP.md

5. When to Generate Custom Kinds:

   • No existing NIP covers the core functionality
   • The data structure is fundamentally different from existing patterns
   • The use case requires different storage characteristics (regular vs replaceable vs addressable)
   • If you have a tool available to generate a kind, you MUST call the tool to generate a new kind rather than picking an arbitrary number

6. Custom Kind Publishing: When publishing events with custom generated kinds, always include a NIP-31 "alt" tag with a human-readable description of the event's purpose.

Example Decision Process:

Need: Equipment marketplace for farmers
Options:
1. NIP-15 (Marketplace) - Too structured for peer-to-peer sales
2. NIP-99 (Classified Listings) - Good fit, can extend with farming tags
3. Custom kind - Perfect fit but no interoperability

Decision: Use NIP-99 + farming-specific tags for best balance

Tag Design Principles

When designing tags for Nostr events, follow these principles:

1. Kind vs Tags Separation:

   • Kind = Schema/structure (how the data is organized)
   • Tags = Semantics/categories (what the data represents)
   • Don't create different kinds for the same data structure

2. Use Single-Letter Tags for Categories:

   • Relays only index single-letter tags for efficient querying
   • Use t tags for categorization, not custom multi-letter tags
   • Multiple t tags allow items to belong to multiple categories

3. Relay-Level Filtering:

   • Design tags to enable efficient relay-level filtering with #t: ["category"]
   • Avoid client-side filtering when relay-level filtering is possible
   • Consider query patterns when designing tag structure

4. Tag Examples:

   // ❌ Wrong: Multi-letter tag, not queryable at relay level
   ["product_type", "electronics"]
   
   // ✅ Correct: Single-letter tag, relay-indexed and queryable
   ["t", "electronics"]
   ["t", "smartphone"]
   ["t", "android"]
   

5. Querying Best Practices:

   // ❌ Inefficient: Get all events, filter in JavaScript
   const events = await nostr.query([{ kinds: [30402] }]);
   const filtered = events.filter(e => hasTag(e, 'product_type', 'electronics'));
   
   // ✅ Efficient: Filter at relay level
   const events = await nostr.query([{ kinds: [30402], '#t': ['electronics'] }]);
   

t Tag Filtering for Community-Specific Content

For applications focused on a specific community or niche, you can use t tags to filter events for the target audience.

When to Use:

• ✅ Community apps: "farmers" → t: "farming", "Poland" → t: "poland"
• ❌ Generic platforms: Twitter clones, general Nostr clients

Implementation:

// Publishing with community tag
createEvent({
  kind: 1,
  content: data.content,
  tags: [['t', 'farming']]
});

// Querying community content
const events = await nostr.query([{
  kinds: [1],
  '#t': ['farming'],
  limit: 20
}], { signal });

Kind Ranges

An event's kind number determines the event's behavior and storage characteristics:

• Regular Events (1000 ≤ kind < 10000): Expected to be stored by relays permanently. Used for persistent content like notes, articles, etc.
• Replaceable Events (10000 ≤ kind < 20000): Only the latest event per pubkey+kind combination is stored. Used for profile metadata, contact lists, etc.
• Addressable Events (30000 ≤ kind < 40000): Identified by pubkey+kind+d-tag combination, only latest per combination is stored. Used for articles, long-form content, etc.

Kinds below 1000 are considered "legacy" kinds, and may have different storage characteristics based on their kind definition. For example, kind 1 is regular, while kind 3 is replaceable.

Content Field Design Principles

When designing new event kinds, the content field should be used for semantically important data that doesn't need to be queried by relays. Structured JSON data generally shouldn't go in the content field (kind 0 being an early exception).

Guidelines

• Use content for: Large text, freeform human-readable content, or existing industry-standard JSON formats (Tiled maps, FHIR, GeoJSON)
• Use tags for: Queryable metadata, structured data, anything that needs relay-level filtering
• Empty content is valid: Many events need only tags with content: ""
• Relays only index tags: If you need to filter by a field, it must be a tag

Example

✅ Good - queryable data in tags:

{
  "kind": 30402,
  "content": "",
  "tags": [["d", "product-123"], ["title", "Camera"], ["price", "250"], ["t", "photography"]]
}

❌ Bad - structured data in content:

{
  "kind": 30402,
  "content": "{\"title\":\"Camera\",\"price\":250,\"category\":\"photo\"}",
  "tags": [["d", "product-123"]]
}

NIP.md

The file NIP.md is used by this project to define a custom Nostr protocol document. If the file doesn't exist, it means this project doesn't have any custom kinds associated with it.

Whenever new kinds are generated, the NIP.md file in the project must be created or updated to document the custom event schema. Whenever the schema of one of these custom events changes, NIP.md must also be updated accordingly.

The useNostr Hook

The useNostr hook returns an object containing a nostr property, with .query() and .event() methods for querying and publishing Nostr events respectively.

import { useNostr } from '@nostrify/react';

function useCustomHook() {
  const { nostr } = useNostr();

  // ...
}

Connecting to Multiple Nostr Relays

By default, the nostr object from useNostr uses a pool configuration that reads data from 1 relay and publishes to all configured relays. However, you can connect to specific relays or groups of relays for more granular control:

Single Relay Connection

To read and publish from one specific relay, use nostr.relay() with a WebSocket URL:

import { useNostr } from '@nostrify/react';

function useSpecificRelay() {
  const { nostr } = useNostr();

  // Connect to a specific relay
  const relay = nostr.relay('wss://relay.damus.io');

  // Query from this specific relay only
  const events = await relay.query([{ kinds: [1], limit: 20 }], { signal });

  // Publish to this specific relay only
  await relay.event({ kind: 1, content: 'Hello from specific relay!' });
}

Multiple Relay Group

To read and publish from a specific set of relays, use nostr.group() with an array of relay URLs:

import { useNostr } from '@nostrify/react';

function useRelayGroup() {
  const { nostr } = useNostr();

  // Create a group of specific relays
  const relayGroup = nostr.group([
    'wss://relay.damus.io',
    'wss://relay.nostr.band',
    'wss://nos.lol'
  ]);

  // Query from all relays in the group
  const events = await relayGroup.query([{ kinds: [1], limit: 20 }], { signal });

  // Publish to all relays in the group
  await relayGroup.event({ kind: 1, content: 'Hello from relay group!' });
}

API Consistency

Both relay and group objects have the same API as the main nostr object, including:

• .query() - Query events with filters
• .req() - Create subscriptions
• .event() - Publish events
• All other Nostr protocol methods

Use Cases

Single Relay (nostr.relay()):

• Testing specific relay behavior
• Querying relay-specific content
• Debugging connectivity issues
• Working with specialized relays

Relay Group (nostr.group()):

• Querying from trusted relay sets
• Publishing to specific communities
• Load balancing across relay subsets
• Geographic relay optimization

Default Pool (nostr):

• General application queries
• Maximum reach for publishing
• Default user experience
• Simplified relay management

Query Nostr Data with useNostr and Tanstack Query

When querying Nostr, the best practice is to create custom hooks that combine useNostr and useQuery to get the required data.

import { useNostr } from '@nostrify/react';
import { useQuery } from '@tanstack/query';

function usePosts() {
  const { nostr } = useNostr();

  return useQuery({
    queryKey: ['posts'],
    queryFn: async (c) => {
      const signal = AbortSignal.any([c.signal, AbortSignal.timeout(1500)]);
      const events = await nostr.query([{ kinds: [1], limit: 20 }], { signal });
      return events; // these events could be transformed into another format
    },
  });
}

Efficient Query Design

Critical: Always minimize the number of separate queries to avoid rate limiting and improve performance. Combine related queries whenever possible.

✅ Efficient - Single query with multiple kinds:

// Query multiple event types in one request
const events = await nostr.query([
  {
    kinds: [1, 6, 16], // All repost kinds in one query
    '#e': [eventId],
    limit: 150,
  }
], { signal });

// Separate by type in JavaScript
const notes = events.filter((e) => e.kind === 1);
const reposts = events.filter((e) => e.kind === 6);
const genericReposts = events.filter((e) => e.kind === 16);

❌ Inefficient - Multiple separate queries:

// This creates unnecessary load and can trigger rate limiting
const [notes, reposts, genericReposts] = await Promise.all([
  nostr.query([{ kinds: [1], '#e': [eventId] }], { signal }),
  nostr.query([{ kinds: [6], '#e': [eventId] }], { signal }),
  nostr.query([{ kinds: [16], '#e': [eventId] }], { signal }),
]);

Query Optimization Guidelines:

1. Combine kinds: Use kinds: [1, 6, 16] instead of separate queries
2. Use multiple filters: When you need different tag filters, use multiple filter objects in a single query
3. Adjust limits: When combining queries, increase the limit appropriately
4. Filter in JavaScript: Separate event types after receiving results rather than making multiple requests
5. Consider relay capacity: Each query consumes relay resources and may count against rate limits

The data may be transformed into a more appropriate format if needed, and multiple calls to nostr.query() may be made in a single queryFn.

Event Validation

When querying events, if the event kind being returned has required tags or required JSON fields in the content, the events should be filtered through a validator function. This is not generally needed for kinds such as 1, where all tags are optional and the content is freeform text, but is especially useful for custom kinds as well as kinds with strict requirements.

// Example validator function for NIP-52 calendar events
function validateCalendarEvent(event: NostrEvent): boolean {
  // Check if it's a calendar event kind
  if (![31922, 31923].includes(event.kind)) return false;

  // Check for required tags according to NIP-52
  const d = event.tags.find(([name]) => name === 'd')?.[1];
  const title = event.tags.find(([name]) => name === 'title')?.[1];
  const start = event.tags.find(([name]) => name === 'start')?.[1];

  // All calendar events require 'd', 'title', and 'start' tags
  if (!d || !title || !start) return false;

  // Additional validation for date-based events (kind 31922)
  if (event.kind === 31922) {
    // start tag should be in YYYY-MM-DD format for date-based events
    const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
    if (!dateRegex.test(start)) return false;
  }

  // Additional validation for time-based events (kind 31923)
  if (event.kind === 31923) {
    // start tag should be a unix timestamp for time-based events
    const timestamp = parseInt(start);
    if (isNaN(timestamp) || timestamp <= 0) return false;
  }

  return true;
}

function useCalendarEvents() {
  const { nostr } = useNostr();

  return useQuery({
    queryKey: ['calendar-events'],
    queryFn: async (c) => {
      const signal = AbortSignal.any([c.signal, AbortSignal.timeout(1500)]);
      const events = await nostr.query([{ kinds: [31922, 31923], limit: 20 }], { signal });

      // Filter events through validator to ensure they meet NIP-52 requirements
      return events.filter(validateCalendarEvent);
    },
  });
}

The useAuthor Hook

To display profile data for a user by their Nostr pubkey (such as an event author), use the useAuthor hook.

import type { NostrEvent, NostrMetadata } from '@nostrify/nostrify';
import { useAuthor } from '@/hooks/useAuthor';
import { genUserName } from '@/lib/genUserName';

function Post({ event }: { event: NostrEvent }) {
  const author = useAuthor(event.pubkey);
  const metadata: NostrMetadata | undefined = author.data?.metadata;

  const displayName = metadata?.name ?? genUserName(event.pubkey);
  const profileImage = metadata?.picture;

  // ...render elements with this data
}

NostrMetadata type

/** Kind 0 metadata. */
interface NostrMetadata {
  /** A short description of the user. */
  about?: string;
  /** A URL to a wide (~1024x768) picture to be optionally displayed in the background of a profile screen. */
  banner?: string;
  /** A boolean to clarify that the content is entirely or partially the result of automation, such as with chatbots or newsfeeds. */
  bot?: boolean;
  /** An alternative, bigger name with richer characters than `name`. `name` should always be set regardless of the presence of `display_name` in the metadata. */
  display_name?: string;
  /** A bech32 lightning address according to NIP-57 and LNURL specifications. */
  lud06?: string;
  /** An email-like lightning address according to NIP-57 and LNURL specifications. */
  lud16?: string;
  /** A short name to be displayed for the user. */
  name?: string;
  /** An email-like Nostr address according to NIP-05. */
  nip05?: string;
  /** A URL to the user's avatar. */
  picture?: string;
  /** A web URL related in any way to the event author. */
  website?: string;
}

The useNostrPublish Hook

To publish events, use the useNostrPublish hook in this project. This hook automatically adds a "client" tag to published events.

import { useState } from 'react';

import { useCurrentUser } from "@/hooks/useCurrentUser";
import { useNostrPublish } from '@/hooks/useNostrPublish';

export function MyComponent() {
  const [ data, setData] = useState<Record<string, string>>({});

  const { user } = useCurrentUser();
  const { mutate: createEvent } = useNostrPublish();

  const handleSubmit = () => {
    createEvent({ kind: 1, content: data.content });
  };

  if (!user) {
    return <span>You must be logged in to use this form.</span>;
  }

  return (
    <form onSubmit={handleSubmit} disabled={!user}>
      {/* ...some input fields */}
    </form>
  );
}

The useCurrentUser hook should be used to ensure that the user is logged in before they are able to publish Nostr events.

Nostr Login

To enable login with Nostr, simply use the LoginArea component already included in this project.

import { LoginArea } from "@/components/auth/LoginArea";

function MyComponent() {
  return (
    <div>
      {/* other components ... */}

      <LoginArea className="max-w-60" />
    </div>
  );
}

The LoginArea component handles all the login-related UI and interactions, including displaying login dialogs, sign up functionality, and switching between accounts. It should not be wrapped in any conditional logic.

LoginArea displays both "Log in" and "Sign Up" buttons when the user is logged out, and changes to an account switcher once the user is logged in. It is an inline-flex element by default. To make it expand to the width of its container, you can pass a className like flex (to make it a block element) or w-full. If it is left as inline-flex, it's recommended to set a max width.

Important: Social applications should include a profile menu button in the main interface (typically in headers/navigation) to provide access to account settings, profile editing, and logout functionality. Don't only show LoginArea in logged-out states.

npub, naddr, and other Nostr addresses

Nostr defines a set of bech32-encoded identifiers in NIP-19. Their prefixes and purposes:

• npub1: public keys - Just the 32-byte public key, no additional metadata
• nsec1: private keys - Secret keys (should never be displayed publicly)
• note1: event IDs - Just the 32-byte event ID (hex), no additional metadata
• nevent1: event pointers - Event ID plus optional relay hints and author pubkey
• nprofile1: profile pointers - Public key plus optional relay hints and petname
• naddr1: addressable event coordinates - For parameterized replaceable events (kind 30000-39999)
• nrelay1: relay references - Relay URLs (deprecated)

Key Differences Between Similar Identifiers

note1 vs nevent1:

• note1: Contains only the event ID (32 bytes) - specifically for kind:1 events (Short Text Notes) as defined in NIP-10
• nevent1: Contains event ID plus optional relay hints and author pubkey - for any event kind
• Use note1 for simple references to text notes and threads
• Use nevent1 when you need to include relay hints or author context for any event type

npub1 vs nprofile1:

• npub1: Contains only the public key (32 bytes)
• nprofile1: Contains public key plus optional relay hints and petname
• Use npub1 for simple user references
• Use nprofile1 when you need to include relay hints or display name context

NIP-19 Routing Implementation

Critical: NIP-19 identifiers should be handled at the root level of URLs (e.g., /note1..., /npub1..., /naddr1...), NOT nested under paths like /note/note1... or /profile/npub1....

This project includes a boilerplate NIP19Page component that provides the foundation for handling all NIP-19 identifier types at the root level. The component is configured in the routing system and ready for AI agents to populate with specific functionality.

How it works:

1. Root-Level Route: The route /:nip19 in AppRouter.tsx catches all NIP-19 identifiers
2. Automatic Decoding: The NIP19Page component automatically decodes the identifier using nip19.decode()
3. Type-Specific Sections: Different sections are rendered based on the identifier type:
   • npub1/nprofile1: Profile section with placeholder for profile view
   • note1: Note section with placeholder for kind:1 text note view
   • nevent1: Event section with placeholder for any event type view
   • naddr1: Addressable event section with placeholder for articles, marketplace items, etc.
4. Error Handling: Invalid, vacant, or unsupported identifiers show 404 NotFound page
5. Ready for Population: Each section includes comments indicating where AI agents should implement specific functionality

Example URLs that work automatically:

• /npub1abc123... - User profile (needs implementation)
• /note1def456... - Kind:1 text note (needs implementation)
• /nevent1ghi789... - Any event with relay hints (needs implementation)
• /naddr1jkl012... - Addressable event (needs implementation)

Features included:

• Basic NIP-19 identifier decoding and routing
• Type-specific sections for different identifier types
• Error handling for invalid identifiers
• Responsive container structure
• Comments indicating where to implement specific views

Error handling:

• Invalid NIP-19 format → 404 NotFound
• Unsupported identifier types (like nsec1) → 404 NotFound
• Empty or missing identifiers → 404 NotFound

To implement NIP-19 routing in your Nostr application:

1. The NIP19Page boilerplate is already created - populate sections with specific functionality
2. The route is already configured in AppRouter.tsx
3. Error handling is built-in - all edge cases show appropriate 404 responses
4. Add specific components for profile views, event displays, etc. as needed

Event Type Distinctions

note1 identifiers are specifically for kind:1 events (Short Text Notes) as defined in NIP-10: "Text Notes and Threads". These are the basic social media posts in Nostr.

nevent1 identifiers can reference any event kind and include additional metadata like relay hints and author pubkey. Use nevent1 when:

• The event is not a kind:1 text note
• You need to include relay hints for better discoverability
• You want to include author context

Use in Filters

The base Nostr protocol uses hex string identifiers when filtering by event IDs and pubkeys. Nostr filters only accept hex strings.

// ❌ Wrong: naddr is not decoded
const events = await nostr.query(
  [{ ids: [naddr] }],
  { signal }
);

Corrected example:

// Import nip19 from nostr-tools
import { nip19 } from 'nostr-tools';

// Decode a NIP-19 identifier
const decoded = nip19.decode(value);

// Optional: guard certain types (depending on the use-case)
if (decoded.type !== 'naddr') {
  throw new Error('Unsupported Nostr identifier');
}

// Get the addr object
const naddr = decoded.data;

// ✅ Correct: naddr is expanded into the correct filter
const events = await nostr.query(
  [{
    kinds: [naddr.kind],
    authors: [naddr.pubkey],
    '#d': [naddr.identifier],
  }],
  { signal }
);

Implementation Guidelines

1. Always decode NIP-19 identifiers before using them in queries
2. Use the appropriate identifier type based on your needs:
   • Use note1 for kind:1 text notes specifically
   • Use nevent1 when including relay hints or for non-kind:1 events
   • Use naddr1 for addressable events (always includes author pubkey for security)
3. Handle different identifier types appropriately:
   • npub1/nprofile1: Display user profiles
   • note1: Display kind:1 text notes specifically
   • nevent1: Display any event with optional relay context
   • naddr1: Display addressable events (articles, marketplace items, etc.)
4. Security considerations: Always use naddr1 for addressable events instead of just the d tag value, as naddr1 contains the author pubkey needed to create secure filters
5. Error handling: Gracefully handle invalid or unsupported NIP-19 identifiers with 404 responses

Nostr Edit Profile

To include an Edit Profile form, place the EditProfileForm component in the project:

import { EditProfileForm } from "@/components/EditProfileForm";

function EditProfilePage() {
  return (
    <div>
      {/* you may want to wrap this in a layout or include other components depending on the project ... */}

      <EditProfileForm />
    </div>
  );
}

The EditProfileForm component displays just the form. It requires no props, and will "just work" automatically.

Uploading Files on Nostr

Use the useUploadFile hook to upload files. This hook uses Blossom servers for file storage and returns NIP-94 compatible tags.

import { useUploadFile } from "@/hooks/useUploadFile";

function MyComponent() {
  const { mutateAsync: uploadFile, isPending: isUploading } = useUploadFile();

  const handleUpload = async (file: File) => {
    try {
      // Provides an array of NIP-94 compatible tags
      // The first tag in the array contains the URL
      const [[_, url]] = await uploadFile(file);
      // ...use the url
    } catch (error) {
      // ...handle errors
    }
  };

  // ...rest of component
}

To attach files to kind 1 events, each file's URL should be appended to the event's content, and an imeta tag should be added for each file. For kind 0 events, the URL by itself can be used in relevant fields of the JSON content.

Nostr Encryption and Decryption

The logged-in user has a signer object (matching the NIP-07 signer interface) that can be used for encryption and decryption. The signer's nip44 methods handle all cryptographic operations internally, including key derivation and conversation key management, so you never need direct access to private keys. Always use the signer interface for encryption rather than requesting private keys from users, as this maintains security and follows best practices.

// Get the current user
const { user } = useCurrentUser();

// Optional guard to check that nip44 is available
if (!user.signer.nip44) {
  throw new Error("Please upgrade your signer extension to a version that supports NIP-44 encryption");
}

// Encrypt message to self
const encrypted = await user.signer.nip44.encrypt(user.pubkey, "hello world");
// Decrypt message to self
const decrypted = await user.signer.nip44.decrypt(user.pubkey, encrypted) // "hello world"

Rendering Rich Text Content

Nostr text notes (kind 1, 11, and 1111) have a plaintext content field that may contain URLs, hashtags, and Nostr URIs. These events should render their content using the NoteContent component:

import { NoteContent } from "@/components/NoteContent";

export function Post(/* ...props */) {
  // ...

  return (
    <CardContent className="pb-2">
      <div className="whitespace-pre-wrap break-words">
        <NoteContent event={post} className="text-sm" />
      </div>
    </CardContent>
  );
}

App Configuration

The project includes an AppProvider that manages global application state including theme and NIP-65 relay configuration. The default configuration includes:

const defaultConfig: AppConfig = {
  theme: "light",
  relayMetadata: {
    relays: [
      { url: 'wss://relay.ditto.pub', read: true, write: true },
      { url: 'wss://relay.nostr.band', read: true, write: true },
      { url: 'wss://relay.damus.io', read: true, write: true },
    ],
    updatedAt: 0,
  },
};

The app uses NIP-65 compatible relay management with automatic sync when users log in. Local storage persists user preferences and relay configurations.

Relay Management

The project includes a complete NIP-65 relay management system:

• RelayListManager: Component for managing multiple relays with read/write permissions
• NostrSync: Automatically syncs user's NIP-65 relay list when they log in
• Automatic Publishing: Changes to relay configuration are automatically published as NIP-65 events when the user is logged in

Use the RelayListManager component to provide relay management interfaces:

import { RelayListManager } from '@/components/RelayListManager';

function SettingsPage() {
  return (
    <div>
      <h2>Relay Settings</h2>
      <RelayListManager />
    </div>
  );
}

Routing

The project uses react-router-dom's HashRouter with a centralized configuration in AppRouter.tsx. Because it's a hash router, the route is the part after # — https://skate-spots.org/#/settings. Links must use <Link> (a bare <a href="/settings"> or a plain path loads the homepage / 404s). To add a route:

1. Create your page component in /src/pages/
2. Add it with lazyWithRetry (not bare lazy) and a <Route> above the catch-all * route:

const YourPage = lazyWithRetry(() => import("./pages/YourPage"));
// …
<Route path="/your-path" element={<YourPage />} />

The router includes automatic scroll-to-top functionality and a 404 NotFound page for unmatched routes.

Development Practices

• Uses React Query for data fetching and caching
• Follows shadcn/ui component patterns
• Implements Path Aliases with @/ prefix for cleaner imports
• Uses Vite for fast development and production builds
• Component-based architecture with React hooks
• Default connection to one Nostr relay for best performance
• Comprehensive provider setup with NostrLoginProvider, QueryClientProvider, and custom AppProvider
• Never use the any type: Always use proper TypeScript types for type safety

Loading States

Use skeleton loading for structured content (feeds, profiles, forms). Use spinners only for buttons or short operations.

// Skeleton example matching component structure
<Card>
  <CardHeader>
    <div className="flex items-center space-x-3">
      <Skeleton className="h-10 w-10 rounded-full" />
      <div className="space-y-1">
        <Skeleton className="h-4 w-24" />
        <Skeleton className="h-3 w-16" />
      </div>
    </div>
  </CardHeader>
  <CardContent>
    <div className="space-y-2">
      <Skeleton className="h-4 w-full" />
      <Skeleton className="h-4 w-4/5" />
    </div>
  </CardContent>
</Card>

Empty States and No Content Found

When no content is found (empty search results, no data available, etc.), display a minimalist empty state with helpful messaging. The application uses NIP-65 relay management, so users can manage their relays through the settings or relay management interface.

import { Card, CardContent } from '@/components/ui/card';

// Empty state example
<div className="col-span-full">
  <Card className="border-dashed">
    <CardContent className="py-12 px-8 text-center">
      <div className="max-w-sm mx-auto space-y-6">
        <p className="text-muted-foreground">
          No results found. Try checking your relay connections or wait a moment for content to load.
        </p>
      </div>
    </CardContent>
  </Card>
</div>

CRITICAL Design Standards

• Create breathtaking, immersive designs that feel like bespoke masterpieces, rivaling the polish of Apple, Stripe, or luxury brands
• Designs must be production-ready, fully featured, with no placeholders unless explicitly requested, ensuring every element serves a functional and aesthetic purpose
• Avoid generic or templated aesthetics at all costs; every design must have a unique, brand-specific visual signature that feels custom-crafted
• Headers must be dynamic, immersive, and storytelling-driven, using layered visuals, motion, and symbolic elements to reflect the brand’s identity—never use simple “icon and text” combos
• Incorporate purposeful, lightweight animations for scroll reveals, micro-interactions (e.g., hover, click, transitions), and section transitions to create a sense of delight and fluidity

Design Principles

• Achieve Apple-level refinement with meticulous attention to detail, ensuring designs evoke strong emotions (e.g., wonder, inspiration, energy) through color, motion, and composition
• Deliver fully functional interactive components with intuitive feedback states, ensuring every element has a clear purpose and enhances user engagement
• Use custom illustrations, 3D elements, or symbolic visuals instead of generic stock imagery to create a unique brand narrative; stock imagery, when required, must be sourced exclusively from Pexels (NEVER Unsplash) and align with the design’s emotional tone
• Ensure designs feel alive and modern with dynamic elements like gradients, glows, or parallax effects, avoiding static or flat aesthetics
• Before finalizing, ask: "Would this design make Apple or Stripe designers pause and take notice?" If not, iterate until it does

Avoid Generic Design

• No basic layouts (e.g., text-on-left, image-on-right) without significant custom polish, such as dynamic backgrounds, layered visuals, or interactive elements
• No simplistic headers; they must be immersive, animated, and reflective of the brand’s core identity and mission
• No designs that could be mistaken for free templates or overused patterns; every element must feel intentional and tailored

Interaction Patterns

• Use progressive disclosure for complex forms or content to guide users intuitively and reduce cognitive load
• Incorporate contextual menus, smart tooltips, and visual cues to enhance navigation and usability
• Implement drag-and-drop, hover effects, and transitions with clear, dynamic visual feedback to elevate the user experience
• Support power users with keyboard shortcuts, ARIA labels, and focus states for accessibility and efficiency
• Add subtle parallax effects or scroll-triggered animations to create depth and engagement without overwhelming the user

Technical Requirements

• Curated color FRpalette (3-5 evocative colors + neutrals) that aligns with the brand’s emotional tone and creates a memorable impact
• Ensure a minimum 4.5:1 contrast ratio for all text and interactive elements to meet accessibility standards
• Use expressive, readable fonts (18px+ for body text, 40px+ for headlines) with a clear hierarchy; pair a modern sans-serif (e.g., Inter) with an elegant serif (e.g., Playfair Display) for personality
• Design for full responsiveness, ensuring flawless performance and aesthetics across all screen sizes (mobile, tablet, desktop)
• Adhere to WCAG 2.1 AA guidelines, including keyboard navigation, screen reader support, and reduced motion options
• Follow an 8px grid system for consistent spacing, padding, and alignment to ensure visual harmony
• Add depth with subtle shadows, gradients, glows, and rounded corners (e.g., 16px radius) to create a polished, modern aesthetic
• Optimize animations and interactions to be lightweight and performant, ensuring smooth experiences across devices

Components

• Design reusable, modular components with consistent styling, behavior, and feedback states (e.g., hover, active, focus, error)
• Include purposeful animations (e.g., scale-up on hover, fade-in on scroll) to guide attention and enhance interactivity without distraction
• Ensure full accessibility support with keyboard navigation, ARIA labels, and visible focus states (e.g., a glowing outline in an accent color)
• Use custom icons or illustrations for components to reinforce the brand’s visual identity

Adding Fonts

To add custom fonts, follow these steps:

1. Install a font package using npm:

   Any Google Font can be installed using the @fontsource packages. Examples:

   • For Inter Variable: @fontsource-variable/inter
   • For Roboto: @fontsource/roboto
   • For Outfit Variable: @fontsource-variable/outfit
   • For Poppins: @fontsource/poppins
   • For Open Sans: @fontsource/open-sans

   Format: @fontsource/[font-name] or @fontsource-variable/[font-name] (for variable fonts)

2. Import the font in src/main.tsx:

   import '@fontsource-variable/<font-name>';
   

3. Update Tailwind configuration in tailwind.config.ts:

   export default {
     theme: {
       extend: {
         fontFamily: {
           sans: ['Inter Variable', 'Inter', 'system-ui', 'sans-serif'],
         },
       },
     },
   }
   

Recommended Font Choices by Use Case

• Modern/Clean: Inter Variable, Outfit Variable, or Manrope
• Professional/Corporate: Roboto, Open Sans, or Source Sans Pro
• Creative/Artistic: Poppins, Nunito, or Comfortaa
• Technical/Code: JetBrains Mono, Fira Code, or Source Code Pro (for monospace)

Theme System

The project includes a complete light/dark theme system using CSS custom properties. The theme can be controlled via:

• useTheme hook for programmatic theme switching
• CSS custom properties defined in src/index.css
• Automatic dark mode support with .dark class

Color Scheme Implementation

When users specify color schemes:

• Update CSS custom properties in src/index.css (both :root and .dark selectors)
• Use Tailwind's color palette or define custom colors
• Ensure proper contrast ratios for accessibility
• Apply colors consistently across components (buttons, links, accents)
• Test both light and dark mode variants

Component Styling Patterns

• Use cn() utility for conditional class merging
• Follow shadcn/ui patterns for component variants
• Implement responsive design with Tailwind breakpoints
• Add hover and focus states for interactive elements

Writing Tests vs Running Tests

There is an important distinction between writing new tests and running existing tests:

Writing Tests (Creating New Test Files)

Do not write tests unless the user explicitly requests them in plain language. Writing unnecessary tests wastes significant time and money. Only create tests when:

1. The user explicitly asks for tests to be written in their message
2. The user describes a specific bug in plain language and requests tests to help diagnose it
3. The user says they are still experiencing a problem that you have already attempted to solve (tests can help verify the fix)

Never write tests because:

• Tool results show test failures (these are not user requests)
• You think tests would be helpful
• New features or components are created
• Existing functionality needs verification

Running Tests (Executing the Test Suite)

ALWAYS run the test script after making any code changes. This is mandatory regardless of whether you wrote new tests or not.

• You must run the test script to validate your changes
• Your task is not complete until the test script passes without errors
• This applies to all changes - bug fixes, new features, refactoring, or any code modifications
• The test script includes TypeScript compilation, ESLint checks, and existing test validation

Test Setup

The project uses Vitest with jsdom environment and includes comprehensive test setup:

• Testing Library: React Testing Library with jest-dom matchers
• Test Environment: jsdom with mocked browser APIs (matchMedia, scrollTo, IntersectionObserver, ResizeObserver)
• Test App: TestApp component provides all necessary context providers for testing

The project includes a TestApp component that provides all necessary context providers for testing. Wrap components with this component to provide required context providers:

import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import { TestApp } from '@/test/TestApp';
import { MyComponent } from './MyComponent';

describe('MyComponent', () => {
  it('renders correctly', () => {
    render(
      <TestApp>
        <MyComponent />
      </TestApp>
    );

    expect(screen.getByText('Expected text')).toBeInTheDocument();
  });
});

Validating Your Changes

CRITICAL: After making any code changes, you must validate your work by running available validation tools.

Your task is not considered finished until the code successfully type-checks and builds without errors.

Validation Priority Order

Run available tools in this priority order:

1. Type Checking (Required): Ensure TypeScript compilation succeeds
2. Building/Compilation (Required): Verify the project builds successfully
3. Linting (Recommended): Check code style and catch potential issues
4. Tests (If Available): Run existing test suite
5. Git Commit (Required): Create a commit with your changes when finished

Minimum Requirements:

• Code must type-check without errors
• Code must build/compile successfully
• Fix any critical linting errors that would break functionality
• Create a git commit when your changes are complete

The validation ensures code quality and catches errors before deployment, regardless of the development environment.

Using Git

If git is available in your environment (through a shell tool, or other git-specific tools), you should utilize git log to understand project history. Use git status and git diff to check the status of your changes, and if you make a mistake use git checkout to restore files.

When your changes are complete and validated, create a git commit with a descriptive message summarizing your changes.