regress/DESIGN.md

# Regress — Design Notes (v0)

A location-based capture game in the spirit of *Ingress*, running as a nostr-native
app on Archipelago. Instead of Niantic's fictional "portals," Regress uses real
Bitcoin-accepting merchant locations pulled from [BTC Map](https://btcmap.org) as
the capturable objects. First scope: **Madeira, Portugal**.

---

## 1. What Ingress actually does (researched)

- **Portals** are real-world landmarks agents physically travel to and interact
  with via the app. In Regress, a **BTC Map place** (merchant/ATM/etc.) is the
  portal-equivalent.
- **XM (Exotic Matter)** is the fictional currency/fuel players collect by
  walking around; spent on all actions. Needs a Regress equivalent (see open
  questions below — sats? a synthetic in-app resource? nothing at all?).
- **Capturing a neutral portal**: deploying a **resonator** claims it instantly
  for your faction. Up to 8 resonators per portal ("fully resonated").
- **Mods**: optional items that buff a portal's defense/utility.
- **Keys & Links**: hacking a portal yields a *key* to it. That key, used at a
  *different* fully-resonated friendly portal, creates a **link** between the
  two — you cannot link a portal to itself.
- **Control fields**: three mutually-linked portals form a triangle that
  "fills in" — this is the actual territory-capture unit, not the portals
  themselves.
- **Factions**: Enlightened (green) vs. Resistance (blue); an AI-controlled
  third faction, Machina (red), exists in later content.
- **Attack/defense**: XMP bursters and Ultra Strikes destroy enemy resonators;
  a portal with zero resonators reverts to neutral and can be recaptured.
- **Anomalies**: live, time-boxed global events tied to real Ingress
  storyline/lore — probably out of scope for v0.

Sources: [ingress.com](https://ingress.com/en), [Fev Games Ingress guide](https://fevgames.net/ingress/ingress-guide/ingress-overview/), [Fev Games glossary](https://fevgames.net/ingress/ingress-guide/glossary/)

## 2. BTC Map as the location data source (researched, live-tested)

BTC Map (`teambtcmap/btcmap-api`) is a real, actively maintained, crowdsourced
map of Bitcoin-accepting places, backed by OpenStreetMap tag data. It has a
public, unauthenticated **REST API v4** at `https://api.btcmap.org/`.

Key endpoints we'd actually use:

- `GET /v4/places?fields=...` — chronological sync of every place, with
  `updated_since`/`limit` for incremental sync (bring-your-own cache pattern,
  good fit for a self-hosted Archipelago app that wants an offline-resilient
  local copy).
- `GET /v4/places/search/?lat=&lon=&radius_km=` — places within a radius. This
  is what a "load the map around me" or "load this island" view would use.
- `GET /v4/places/{id}` — single place detail (name, address, phone, website,
  socials, `osm_id`/`osm_url`, `verified_at`, icon).
- `GET /v4/places/{id}/comments`, `/v4/places/{id}/areas` — community
  comments and country/community area membership.
- `GET /v4/areas?lat=&lon=` — which named areas (country/community) contain a
  point; `GET /v4/areas/{id|alias}` — area metadata + icon image.

No API key needed for reads. Write/RPC endpoints exist for community editing
but aren't needed for a read-only game client.

**Live-tested against Madeira right now:** a 45 km radius search centered on
Funchal (32.7607, -16.9595) returns **167 real, currently-tracked places** —
comfortably covers the whole island (~57 km × 22 km). Category breakdown from
the actual data:

| Count | Category (icon) |
|---|---|
| 35 | restaurant |
| 14 | café |
| 13 | storefront (general retail) |
| 10 | pharmacy |
| 7 | hotel |
| 6 | bakery |
| 5 each | fitness, hair/barber, "business", medical |
| ... | long tail: bars, dentists, spas, tour operators, ice cream, a boat charter, a surf shop, a music venue, a bike rental, etc. |

This is real, not a mock — it's what the live API returns today. Full raw
dump saved at `data/madeira-btcmap-2026-08-04.json` for reference (167
records: id, lat, lon, name, icon, osm_id, verified_at).

Source: [btcmap-api docs](https://github.com/teambtcmap/btcmap-api/tree/master/docs/rest/v4)

## 3. Proposed Regress concept (draft — needs your input)

Every BTC Map place in scope starts **unclaimed** (Ingress's "neutral grey").
Players claim it, link claimed places together, and linked triangles form a
**control field** over that territory — same core loop as Ingress, but the
portals are real Bitcoin-accepting businesses instead of public art/landmarks.

### Open questions before I design further

1. **What does "claiming" cost/require?** Ingress ties everything to XM
   gathered by physically walking near portals. Options for Regress:
   - **Physical presence required** (GPS check-in via phone, like Ingress) —
     most faithful to the genre, but means players must actually be in
     Madeira.
   - **Sats/Lightning-gated** — claiming costs a small zap/payment (fits the
     Bitcoin theme hard, ties into podsteadr's existing Cashu/Lightning
     plumbing you already have running).
   - **Nostr-native "proof of visit"** — e.g. NFC/QR at the merchant, or a
     merchant-signed nostr event, so it's cryptographically real rather than
     GPS-spoofable.
   - Some combination.
2. **Factions or free-for-all?** Ingress's whole metagame is two-faction
   conflict. Do you want teams, or is this more like an individual/community
   "claim businesses you actually support" thing?
3. **Does "unclaimed" ever mean anything to the real business owner?** i.e.
   is there a path for the actual merchant to claim their own listing (like
   podsteadr's owner-exemption pattern), or is Regress entirely player-vs-
   player over data about businesses that don't participate?
4. **Archipelago integration shape** — same fork as podsteadr had: does
   Regress run standalone on its own domain (external, identity-aware via the
   `nostr-provider.js` shim like we just wired for podsteadr), or does it need
   full orchestrator-managed packaging? I'd default to the podsteadr pattern
   (external + identity-aware) unless you want it embedded differently.
5. **Nostr event shape for claims/links?** Worth defining a custom kind (or
   piggybacking parameterized replaceable events) early since that's the
   actual interop surface other clients could read.

## 4. Next steps once the above is answered

- Pull the full Madeira dataset via `/v4/places` (chronological sync
  endpoint) rather than the radius search, so we get a clean incremental-sync
  foundation instead of a one-off snapshot.
- Define the Regress data model: place (from BTC Map, cached locally) →
  claim → link → field, plus whatever resource economy answers question 1.
- Stand up the repo skeleton (backend + frontend, matching the podsteadr
  stack unless you want something different) and wire BTC Map sync as the
  first real feature.