docs: fork-with-fallback ships — record mode, the new civic kinds, and the keyless smoke test

MaxBrych · MaxBrych · commit 32f85acc4215 · 2026-08-02T16:05:19.000+02:00
diff --git a/docs/FORKING_GUIDE.md b/docs/FORKING_GUIDE.md
@@ -5,16 +5,18 @@ towns who want to **fork the platform** for themselves. If you just asked *"is t
 a staging environment / how do I test this easily?"* — start with
 [Testing against staging](#testing-against-staging).
 
+- **Just want to see it run, zero setup?** → [Ohne Supabase starten (record mode)](#ohne-supabase-starten-record-mode)
 - **Contributor?** → [Prerequisites](#prerequisites) → [Testing against staging](#testing-against-staging)
 - **Maintainer provisioning staging?** → [docs/STAGING_ENVIRONMENT.md](STAGING_ENVIRONMENT.md)
 - **Forking for your own town?** → [Fork for your own town](#fork-for-your-own-town)
 
 ---
 
-## TL;DR — the three ways to test
+## TL;DR — the four ways to test
 
 | Goal | What to do | Setup effort |
 |---|---|---|
+| Clone and run the **web** app with zero backend | `pnpm install`, run `apps/web` with no env | none |
 | Just look at / click through the app | Open **https://stage.roebel.app** | none |
 | Develop the **web** app | Run `apps/web` locally, point at staging Supabase | ~2 min |
 | Develop the **mobile** app | Run `apps/expo` in Expo Go, point at staging Supabase | ~5 min |
@@ -24,6 +26,64 @@ You only fork if you want your *own town's* independent instance.
 
 ---
 
+## Ohne Supabase starten (record mode)
+
+The fastest way to see the app run at all: **no Supabase project, no env file, no
+credentials.** `apps/web` reads the town's public record straight off the node's
+HTTP index instead of PostgREST, so every public page renders with real data even
+when `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_ANON_KEY` are absent.
+
+```bash
+git clone https://github.com/Roebel-Labs/Roebel-App.git
+cd Roebel-App
+pnpm install
+cd apps/web
+pnpm dev        # → http://localhost:3000, no .env.local needed
+```
+
+Open it and you'll see **Röbel's actual public record** — the default index is
+`https://index.roebel.app`, the same node the production app talks to, just
+through its read-only public interface instead of the database.
+
+To point the app at a **different community's node** instead, set one variable:
+
+```bash
+NEXT_PUBLIC_NODE_INDEX_URL=https://index.example-town.app pnpm dev
+```
+
+That's the whole seam — [`apps/web/src/lib/record.ts`](../apps/web/src/lib/record.ts)
+constructs the index client from that single env var, defaulting to Röbel's own
+node when it's unset.
+
+**What works in record mode** — all public reading: the feed, events, news,
+cinema programme, organisations, marketplace, business deals, restaurant menus,
+governance proposals, civic notices, and the map.
+
+**What does not** — anything that needs a backend to write or to know who you
+are: login, posting, likes/comments, any form, DMs, notifications, the points
+card, the mini-app runtime, QR ordering. A navy banner across the top says so
+plainly: *"Öffentlicher Datensatz – nur Lesen. Diese Instanz läuft ohne Backend
+und zeigt das öffentliche Register der Stadt."* — and every write affordance is
+hidden rather than shown-then-failing.
+
+This is genuinely read-only, not a demo mode with fake data — it's Röbel's live
+public record, sourced the same way an outside client would. See
+[Public data on Nostr](PUBLIC_DATA_ON_NOSTR.md) for what's published and why, and
+[Roadmap and deferred work §13a](ROADMAP_AND_DEFERRED.md) for how this shipped.
+
+**The acceptance test is [`apps/web/scripts/keyless-smoke.sh`](../apps/web/scripts/keyless-smoke.sh)** —
+it builds and boots the app with the Supabase env genuinely absent (not just
+unread) and asserts all eight public routes (`/`, `/news`, `/app`,
+`/app/marktplatz`, `/proposals`, `/karte`, `/app/events`, `/unternehmen`) return
+HTTP 200 with the record-mode banner present. Run it yourself with:
+
+```bash
+cd apps/web
+./scripts/keyless-smoke.sh
+```
+
+---
+
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/) v20+
diff --git a/docs/PUBLIC_DATA_ON_NOSTR.md b/docs/PUBLIC_DATA_ON_NOSTR.md
@@ -35,6 +35,14 @@ public datasets onto the relay every 5 minutes — first live pass: 41 events ac
 | **images** — mirrored content-addressed at `/media/<sha256>` (Blossom-shaped reads); the hash in the signed event is the integrity check | |
 | **the manifest** — `/manifest` on the index: chain id + every contract address, so governance and Münzen are discoverable on-chain without asking anyone | |
 
+As of 2026-08-02, the **web app itself** reads this table's left column back out, not just the
+publisher writing it: any public route renders from the node's index when Supabase is absent,
+which is the other end of this migration — [Forking Guide → Ohne Supabase
+starten](FORKING_GUIDE.md#ohne-supabase-starten-record-mode) and
+[Roadmap §13a](ROADMAP_AND_DEFERRED.md) cover the read side. The remaining "not yet" row —
+per-person opt-in content — is the only genuinely missing public dataset; everything else a
+keyless fork needs to render is already in the left column above.
+
 **The withdrawal path shipped before the publish path**, exactly as §3.4 demands — and the
 first kind-30018 events on the record were four withdrawal tombstones, published before any
 active listing (their sellers had not opted in, so the gate held them back). The index honours
diff --git a/docs/ROADMAP_AND_DEFERRED.md b/docs/ROADMAP_AND_DEFERRED.md
@@ -185,15 +185,35 @@ media: calendar data should use NIP-52 kinds rather than invented ones, and medi
 served from a Blossom server next to strfry — NIP-96 is officially deprecated in its
 favour. **Trigger:** publishing the events/cinema/org datasets, or any media, to the relay.
 
-### 13a. Fork-with-fallback: the app reads Nostr when Supabase is absent
-
-The end state of the dual system: someone forks the Röbel web or expo repo, configures no
-Supabase, and the app still shows the whole public record by reading the node's index/relay —
-same data, slightly slower. The pieces exist (every public dataset is on the record, the
-consumer contract is documented in the Netizen repo's CONSUMING_THE_RECORD.md); what is
-missing is a data-layer seam in the apps that falls back from PostgREST to `/events` queries
-per dataset. **Trigger:** the first real fork, or the Atlas proving a full read-only client —
-whichever comes first.
+### 13a. ~~Fork-with-fallback: the app reads Nostr when Supabase is absent~~ — DONE 2026-08-02
+
+The end state of the dual system: someone forks the Röbel web repo, configures no Supabase,
+and the app still shows the whole public record by reading the node's index — same data,
+read-only. **Shipped for web**: all three Supabase client factories return a throw-on-access
+Proxy when keyless (construction never crashes SSR), every public read path branches on
+`hasSupabase` and falls back to `@netizen-labs/record-client` against the node's
+`/events` index, and a sweep removed render-time Supabase access from every public route. A
+navy banner marks the instance as read-only and hides write affordances rather than letting
+them fail. `NEXT_PUBLIC_NODE_INDEX_URL` repoints a fork at a different community's node;
+default is Röbel's own (`https://index.roebel.app`).
+
+**Proof:** [`apps/web/scripts/keyless-smoke.sh`](../apps/web/scripts/keyless-smoke.sh) builds
+and boots the app with the Supabase env genuinely absent and asserts all 8 public routes (`/`,
+`/news`, `/app`, `/app/marktplatz`, `/proposals`, `/karte`, `/app/events`, `/unternehmen`)
+return HTTP 200 with the record-mode notice present — not just a 200, the actual record-mode
+banner, so the test fails if a route silently falls back to empty data instead of reading the
+index. See [Forking Guide → Ohne Supabase starten](FORKING_GUIDE.md#ohne-supabase-starten-record-mode).
+
+**Honest gaps, not swept under this:**
+- **~60 of the ~127 handlers under `apps/web/src/app/api/**` are unaudited** for keyless
+  behaviour. A page rendering does not imply every API route it might call degrades
+  gracefully — an unaudited handler that assumes Supabase will 500, which is a broken
+  endpoint, not a broken page. The smoke test only exercises page routes.
+- **Interaction counts (likes, comments, reposts) are advisory in record mode.** The index
+  reflects what the relay has mirrored, not a live tally, so a count shown to a keyless reader
+  can lag the authoritative Supabase-backed number by up to one publisher cycle.
+- **Expo is out of scope.** This shipped for `apps/web` only; the mobile app still requires
+  Supabase env to run at all.
 
 ### 13. ~~The index does not honour replaceable events~~ — DONE 2026-07-30
 
diff --git a/docs/STATE_OF_NOSTR.md b/docs/STATE_OF_NOSTR.md
@@ -107,9 +107,14 @@ Two rails, distinguished by **who holds the key**:
 - **Node-signed** (node-held per-organisation keys, since 2026-07-30): the public CMS
   datasets, mirrored by `@netizen-labs/publisher` (`services.publisher` in the manifest).
   Events and cinema as NIP-52 `31923`, organisation profiles as kind 0 — the cinema's
-  screenings signed by the cinema's derived key, an org's events by that org's key. relay-sync
-  merges the publisher's pubkeys into the allow-list each pass (`EXTRA_KEYS_FILE`). Details
-  and the privacy boundary: [Public data on Nostr](PUBLIC_DATA_ON_NOSTR.md) §1.
+  screenings signed by the cinema's derived key, an org's events by that org's key. Three
+  civic kinds round out the CMS datasets: town news as NIP-23 `30023` (`d=news:<uuid>`),
+  restaurant menus as **kind `32101`** (one replaceable event per restaurant, `d=restaurant:<id>`),
+  civic notices as **kind `32102`** (town-signed, a resolved alert is an edit, never a
+  deletion), and governance proposals as **kind `32100`** — a discoverable pointer only, body
+  stays on Irys and tallies stay on-chain. relay-sync merges the publisher's pubkeys into the
+  allow-list each pass (`EXTRA_KEYS_FILE`). Details and the privacy boundary: [Public data on
+  Nostr](PUBLIC_DATA_ON_NOSTR.md) §1.
 
 On delete the app publishes a NIP-09 kind 5 request and says plainly in the UI that erasure
 on Nostr is **advisory** — relays may ignore it, and clients that already fetched an event
@@ -201,6 +206,16 @@ history, and **provenance** — which node an event came from.
 
 `GET /events?q=&kinds=&authors=&since=&until=&node=&limit=` · `GET /stats` · `GET /health`
 
+**`/events` also takes `e`, `p` and `d` tag filters**, added 2026-08-02 for the fork-with-fallback
+read path (§13a of the roadmap): `e`/`p` match via a GIN-indexed `tags @> …` JSONB containment
+query (`idx_nostr_events_tags`), so replies and reactions to a given event or author are
+queryable without a full scan; `d` filters on the `d_tag` column directly — the same column the
+replaceable-event collapse ([Roadmap §13](ROADMAP_AND_DEFERRED.md)) already maintains — so a
+client can ask for one stable record (a restaurant's menu, a proposal pointer) by its `d` tag
+alone. This is what lets
+`@netizen-labs/record-client` (and so a keyless `apps/web`) fetch a specific parameterised
+replaceable event instead of paging through everything of a kind.
+
 Public read by design. Everything in it came off world-readable relays, so publishing leaks
 nothing new, and it is what lets a **peer's** agent query this node.
 
@@ -209,6 +224,33 @@ event whose signature is re-verified on ingest rather than trusted from a peer,
 store is rebuildable by re-reading the relays. Drop the database and nothing is lost — that is
 what keeps query efficiency from turning into lock-in.
 
+## 6a. Fork-with-fallback: the web app reads the index — live 2026-08-02
+
+The other end of publishing is consuming. **`apps/web` now has a record-mode read path**: every
+public route reads through `@netizen-labs/record-client` against a node's `/events` index
+instead of PostgREST whenever Supabase credentials are absent, so a fork with no backend at all
+still renders the town's real public record — read-only, slightly slower, same data. This closes
+[Roadmap §13a](ROADMAP_AND_DEFERRED.md), previously the largest gap in §8/§9 below: until now,
+publishing to the relay proved the record was *public*, not that an outside app could actually
+*consume* it end to end.
+
+The mechanism: the three Supabase client factories construct a throw-on-access `Proxy` when
+keyless rather than crash on import, every public data-fetching function branches on
+`hasSupabase` and falls back to the record-client, and `NEXT_PUBLIC_NODE_INDEX_URL` (default
+Röbel's own `https://index.roebel.app`) is the one variable a fork sets to point at a different
+node. A navy banner marks the instance read-only and every write affordance is hidden rather
+than left to fail. [`apps/web/scripts/keyless-smoke.sh`](../apps/web/scripts/keyless-smoke.sh)
+is the acceptance test — it builds and boots the app with the Supabase env genuinely absent and
+asserts all 8 public routes return HTTP 200 with the record-mode notice present. See [Forking
+Guide → Ohne Supabase starten](FORKING_GUIDE.md#ohne-supabase-starten-record-mode) for how to
+run it yourself.
+
+Scoped to `apps/web` only — Expo still requires Supabase env to run — and honest gaps remain:
+roughly 60 of the ~127 `apps/web/src/app/api/**` handlers are unaudited for keyless behaviour
+(a page rendering does not prove every API route it might call degrades gracefully), and
+interaction counts (likes, comments, reposts) shown in record mode are advisory, reflecting
+whatever the index last mirrored rather than a live tally.
+
 ## 7. Agents on the record (slice 4) — live 2026-07-28
 
 An agent has no wallet, so it cannot derive a key from a wallet signature the way a Citizen
