Add planning docs for Nostr place reviews

.agents/skills/nak/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: nak
+description: Interact with Nostr protocol using the nak CLI tool. Use to generate Nostr secret keys, encode and decode Nostr identifiers (hex/npub/nsec/nip05/etc), fetch events from relays, sign and publish Nostr events, and more.
+license: CC-BY-SA-4.0
+---
+
+# nak - Nostr Army Knife
+
+Work with the Nostr protocol using the `nak` CLI tool.
+
+GitHub: https://github.com/fiatjaf/nak
+
+## Installation
+
+To install (or upgrade) nak:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/fiatjaf/nak/master/install.sh | sh
+```
+
+## Core Concepts
+
+Based on analyzing extensive real-world usage, here are the fundamental concepts distilled down, then branched out:
+
+---
+
+### CONCEPT 1: Query & Discovery
+*"Finding events and data on Nostr"*
+
+**Basic:**
+- Fetch by identifier: "Get event/profile without knowing relays"
+  - `nak fetch nevent1...` (uses embedded relay hints)
+  - `nak fetch alex@gleasonator.dev` (NIP-05 resolution)
+- Query by event ID: "I want THIS specific event from a relay"
+  - `nak req -i <event_id> <relay>`
+- Query by author: "Show me everything from this person"
+  - `nak req -a <pubkey> <relay>`
+- Query by kind: "Show me all profiles/notes/videos"
+  - `nak req -k <kind> <relay>`
+
+**Intermediate:**
+- Fetch addressable events: "Get event by naddr/nprofile"
+  - `nak fetch naddr1...` (kind, author, identifier encoded)
+  - `nak fetch -r relay.primal.net naddr1...` (override relays)
+- Filter by multiple criteria: "Find posts by author X of kind Y"
+  - `nak req -k 1 -a <pubkey> <relay>`
+- Tag-based queries: "Find events tagged with bitcoin"
+  - `nak req --tag t=bitcoin <relay>`
+
+**Advanced:**
+- Search with ranking: "Find trending/top content"
+  - `nak req --search "sort:hot" <relay>`
+  - `nak req --search "popular:24h" <relay>`
+- Live monitoring: "Watch events in real-time"
+  - `nak req --stream <relay>`
+- Cross-protocol queries: "Find bridged Bluesky content"
+  - `nak req --tag "proxy=at://..." <relay>`
+
+**Use cases:** Discovering content, debugging relay data, testing search algorithms, monitoring live feeds
+
+---
+
+### CONCEPT 2: Broadcast & Migration
+*"Moving/copying events between relays"*
+
+**Basic:**
+- Publish a single event: "Put this on relay X"
+  - `cat event.json | nak event <relay>`
+- Query and republish: "Copy event from relay A to relay B"
+  - `nak req -i <id> relay1 | nak event relay2`
+
+**Intermediate:**
+- Batch migration: "Copy all events of kind X"
+  - `nak req -k 30717 source_relay | nak event dest_relay`
+- Paginated backup: "Download everything from a relay"
+  - `nak req --paginate source_relay | nak event backup_relay`
+- Multi-relay broadcast: "Publish to multiple relays at once"
+  - `cat event.json | nak event relay1 relay2 relay3`
+
+**Advanced:**
+- Selective migration: "Copy follow list members' data"
+  - Loop through follow list, query each author, republish to new relay
+- Filter and migrate: "Copy only tagged/searched content"
+  - `nak req --tag client=X relay1 | nak event relay2`
+- Cross-relay synchronization: "Keep two relays in sync"
+  - `nak sync source_relay dest_relay`
+
+**Use cases:** Seeding new relays, backing up data, migrating content between relays, bridging Mostr/Fediverse content
+
+---
+
+### CONCEPT 3: Identity & Encoding
+*"Working with Nostr identifiers and keys"*
+
+**Basic:**
+- Decode identifiers: "What's inside this npub/nevent?"
+  - `nak decode npub1...`
+  - `nak decode user@domain.com`
+- Encode identifiers: "Turn this pubkey into npub"
+  - `nak encode npub <hex_pubkey>`
+
+**Intermediate:**
+- Generate keys: "Create a new identity"
+  - `nak key generate`
+  - `nak key generate | nak key public | nak encode npub`
+- Extract hex from NIP-05: "Get the raw pubkey from an address"
+  - `nak decode user@domain.com | jq -r .pubkey`
+- Create shareable references: "Make a nevent with relay hints"
+  - `nak encode nevent <event_id> --relay <relay>`
+
+**Advanced:**
+- Complex naddr creation: "Create addressable event reference with metadata"
+  - `nak encode naddr -k 30717 -a <author> -d <identifier> -r <relay>`
+- Multi-relay nprofile: "Create profile with multiple relay hints"
+  - `nak encode nprofile <pubkey> -r relay1 -r relay2 -r relay3`
+
+**Use cases:** Converting between formats, sharing references with relay hints, managing multiple identities, extracting pubkeys for scripting
+
+---
+
+### CONCEPT 4: Event Creation & Publishing
+*"Creating and signing new events"*
+
+**Basic:**
+- Interactive creation: "Create an event with prompts"
+  - `nak event --prompt-sec <relay>`
+- Simple note: "Publish a text note"
+  - `nak event -k 1 -c "Hello Nostr" <relay>`
+
+**Intermediate:**
+- Events with tags: "Create tagged content"
+  - `nak event -k 1 -t t=bitcoin -t t=nostr <relay>`
+- Event deletion: "Delete a previous event"
+  - `nak event -k 5 -e <event_id> --prompt-sec <relay>`
+- Replaceable events: "Create/update a profile or app data"
+  - `nak event -k 10019 -t mint=<url> -t pubkey=<key> <relay>`
+
+**Advanced:**
+- Remote signing with bunker: "Sign without exposing keys"
+  - `nak event --connect "bunker://..." <relay>`
+- Batch event creation: "Generate many events via script"
+  - `for i in {1..100}; do nak event localhost:8000; done`
+- Complex events from JSON: "Craft specific event structure"
+  - Modify JSON, then `cat event.json | nak event <relay>`
+
+**Use cases:** Testing event creation, developing apps (kind 31990, 37515), wallet integration (kind 10019), moderation (kind 5), bunker/remote signing implementation
+
+---
+
+### CONCEPT 5: Development & Testing
+*"Building on Nostr"*
+
+**Basic:**
+- Local relay testing: "Test against dev relay"
+  - `nak req localhost:8000`
+  - `nak event ws://127.0.0.1:7777`
+
+**Intermediate:**
+- Inspect JSON: "Examine event structure"
+  - `nak req -i <id> <relay> | jq .`
+- Test search: "Verify search functionality"
+  - `nak req --search "<query>" localhost:8000`
+- Admin operations: "Manage relay content"
+  - `nak admin --prompt-sec banevent --id <id> <relay>`
+
+**Advanced:**
+- Protocol bridging: "Query/test ATProto integration"
+  - `nak req --tag "proxy=at://..." eclipse.pub/relay`
+- Git over Nostr: "Use git with Nostr transport"
+  - `nak git clone nostr://...`
+  - `nak req -k 30617 git.shakespeare.diy`
+- Performance testing: "Measure query speed"
+  - `time nak req -k 0 -a <pubkey> <relay>`
+- Custom event kinds: "Test proprietary event types"
+  - `nak req -k 37515 -a <author> -d <id> ditto.pub/relay`
+
+**Use cases:** Relay development (Ditto), testing bridges (Mostr/Bluesky), developing video platforms, implementing Git-over-Nostr, testing search ranking algorithms, performance benchmarking
+
+---
+
+### CONCEPT 6: Analytics & Monitoring
+*"Understanding Nostr data"*
+
+**Basic:**
+- Count results: "How many events match?"
+  - `nak req -k 1 <relay> | wc -l`
+  - `nak count -k 7 -e <event_id> <relay>`
+
+**Intermediate:**
+- Live monitoring: "Watch relay activity"
+  - `nak req --stream <relay>`
+  - `nak req -l 0 --stream relay1 relay2 relay3`
+- Client analytics: "What apps are posting?"
+  - `nak req --tag client=<app> <relay>`
+
+**Advanced:**
+- Event chain analysis: "Track engagement"
+  - `nak count -k 7 -e <event_id> <relay>` (reactions)
+  - `nak req -k 6 -k 7 -e <event_id> <relay>` (reposts + reactions)
+- Content ranking: "Find top/hot content"
+  - `nak req --search "sort:top" <relay>`
+- Cross-relay comparison: "Compare event availability"
+  - Query same event from multiple relays, compare results
+
+**Use cases:** Monitoring relay health, tracking client usage (Ditto, noStrudel, moStard), analyzing engagement, testing ranking algorithms
+
+---
+
+## Summary: The 6 Core Mental Models
+
+1. **Query & Discovery**: "How do I find things?"
+2. **Broadcast & Migration**: "How do I move things?"
+3. **Identity & Encoding**: "How do I represent things?"
+4. **Event Creation**: "How do I make things?"
+5. **Development & Testing**: "How do I build things?"
+6. **Analytics & Monitoring**: "How do I measure things?"
+
+---
+
+## Command Shapes and Edge-Cases
+
+Non-obvious patterns and edge cases for nak commands.
+
+### Signing Methods
+
+**Using environment variable:**
+```bash
+export NOSTR_SECRET_KEY=<hex_key>
+nak event -c "hello"  # Automatically uses $NOSTR_SECRET_KEY
+```
+
+**Reading key from file:**
+```bash
+nak event -c "hello" --sec $(cat /path/to/key.txt)
+```
+
+### Content from File
+
+**Using @ prefix to read content from file:**
+```bash
+echo "hello world" > content.txt
+nak event -c @content.txt
+```
+
+### Tag Syntax
+
+**Tag with multiple values (semicolon-separated):**
+```bash
+nak event -t custom="value1;value2;value3"
+# Creates: ["custom", "value1", "value2", "value3"]
+```
+
+### Filter Output Modes
+
+**Print bare filter (JSON only):**
+```bash
+nak req -k 1 -l 5 --bare
+# Output: {"kinds":[1],"limit":5}
+```
+
+**Filter from stdin can be modified with flags:**
+```bash
+echo '{"kinds": [1]}' | nak req -l 5 -k 3 --bare
+```
+
+**Unlimited stream:**
+```bash
+nak req -l 0 --stream wss://relay.example.com
+```
+
+### Relay Specification
+
+**Local relays and WebSocket schemes:**
+```bash
+nak req localhost:8000
+nak req ws://127.0.0.1:7777
+nak req relay.example.com  # Assumes wss:// if not specified
+```
+
+### Encoding
+
+**Encode from JSON stdin (auto-detects type):**
+```bash
+echo '{"pubkey":"<hex>","relays":["wss://relay.example.com"]}' | nak encode
+```
+
+### Key Operations
+
+**Complete key generation pipeline:**
+```bash
+nak key generate | tee secret.key | nak key public | nak encode npub
+# Saves private key to file AND prints the public npub
+```
+
+### Verification
+
+**Verify and pipe:**
+```bash
+nak event -c "test" --sec <key> | nak verify && echo "Valid"
+```
+
+### Fetch vs Req
+
+**nak fetch uses relay hints from identifiers:**
+```bash
+nak fetch nevent1...  # Uses relays encoded in nevent
+nak fetch naddr1...   # Uses relays encoded in naddr  
+nak fetch alex@gleasonator.dev  # Resolves NIP-05
+nak fetch -r relay.primal.net naddr1...  # Override relays
+```
+
+**nak req requires explicit relay specification:**
+```bash
+nak req -i <event_id> wss://relay.example.com
+```
+
+### Edge Cases
+
+**No relays specified (prints event without publishing):**
+```bash
+nak event -c "test" --sec <key>  # Just prints the event JSON
+```
+
+**Tag order matters for addressable events:**
+```bash
+# The first 'd' tag is the identifier
+nak event -k 30023 -d first -d second  # "first" is the identifier
+```
+
+**Timestamp override:**
+```bash
+nak event --ts 1700000000 -c "backdated" --sec <key>
+nak event --ts 0 -c "genesis" --sec <key>  # Event at Unix epoch
+```
+
+**Kind 0 (profile) requires JSON content:**
+```bash
+nak event -k 0 -c '{"name":"Alice","about":"Developer"}' --sec <key>
+```
+
+**POW (Proof of Work):**
+```bash
+nak event --pow 20 -c "mined event" --sec <key>
+# Will compute hash until difficulty target is met
+```
+
+**NIP-42 AUTH:**
+```bash
+nak req --auth -k 1 wss://relay.example.com
+nak event --auth -c "test" --sec <key> wss://relay.example.com
+# Automatically handles AUTH challenges
+```
+
+**Stdin takes precedence over flags:**
+```bash
+echo '{"content":"from stdin"}' | nak event -c "from flag" --sec <key>
+# Uses "from stdin" (stdin overrides flags)
+```
+

.agents/skills/nostr/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: nostr
+description: Knowledge about the Nostr protocol. Use to view up-to-date NIPs, discover capabilities of the Nostr protocol, and to implement Nostr functionality correctly.
+license: CC-BY-SA-4.0
+---
+
+# Nostr Protocol
+
+Nostr is a simple, open protocol that enables truly censorship-resistant and global social networks using cryptographic keys and signatures.
+
+## Finding Nostr Documentation
+
+All Nostr protocol documentation is maintained in the NIPs (Nostr Implementation Possibilities) repository. To access this information:
+
+### Reading Individual NIPs
+
+Individual NIPs can be fetched from:
+```
+https://github.com/nostr-protocol/nips/blob/master/{NIP}.md
+```
+
+For example, NIP-01 (the basic protocol specification) is available at:
+```
+https://github.com/nostr-protocol/nips/blob/master/01.md
+```
+
+### Finding Event Kinds
+
+Documentation for Nostr event kinds is spread across one or more NIPs. **There is no direct relationship between the NIP number and the kind number.**
+
+To find which NIPs document a specific event kind:
+
+1. First, fetch the README:
+   ```
+   https://github.com/nostr-protocol/nips/blob/master/README.md
+   ```
+
+2. Reference the "Event Kinds" table in the README to find which NIP(s) document the kind you're looking for
+
+### Discovering Existing Capabilities
+
+The README should be consulted to:
+
+- **View the list of NIPs** - Use this to discover what capabilities already exist on the Nostr network
+- **Review client and relay messages** - Understand the communication protocol
+- **Check the list of tags** - See what standardized tags are available
+- **Decide on using existing NIPs** - Before implementing a feature, check if an existing NIP already covers it
+
+### Best Practices
+
+Always start by fetching and reviewing the README to understand the current state of the protocol and avoid reinventing existing functionality.

AGENTS.md

@@ -0,0 +1,49 @@
+# Agent Instructions for Marco
+
+Marco is a privacy-respecting, unhosted maps application that allows users to connect their own remote storage to sync place bookmarks across apps and devices.
+
+## Relevant Commands
+
+All commands must be executed using `pnpm`. Never use `npm`.
+
+- **Install dependencies:** `pnpm install`
+- **Start development server:** `pnpm start` (Runs Vite)
+- **Run tests:** `pnpm test` (Builds and runs via Testem)
+- **Linting:**
+  - `pnpm lint` (Runs ESLint, Stylelint, Prettier, and ember-template-lint concurrently)
+  - `pnpm lint:fix` (Automatically fixes linting and formatting errors)
+
+### NEVER RUN
+
+- `pnpm build` (only run for releases by the devs)
+- `git add`, `git commit`, or any other commands that modify git history or the staging area
+
+## Application Architecture & Frameworks
+
+### Core Stack
+
+- **Framework:** Ember.js (Octane / Polaris editions). The project heavily uses modern Ember paradigms including `.gjs` (template-tag format), `@glimmer/component`, and `@glimmer/tracking`.
+- **Build System:** Vite coupled with Embroider (`@embroider/vite`) for fast, modern asset compilation.
+
+### Mapping & Geocoding
+
+- **Maps:** Uses OpenLayers (`ol` and `ol-mapbox-style`) for rendering the map interface.
+- **Search:** Uses the Photon API (via `app/services/photon.js`) for geocoding and search functionality.
+- **Data Source:** OpenStreetMap (OSM) data is fetched and parsed to display rich place details.
+
+### Storage & Authentication
+
+- **RemoteStorage:** The app is "unhosted" meaning user data isn't locked in a central database. It uses `remotestoragejs` and `@remotestorage/module-places` to sync bookmarks to a user's chosen storage provider. (Managed in `app/services/storage.js`).
+- **OSM Auth:** Allows users to log into OpenStreetMap using OAuth 2.0 PKCE (`oauth2-pkce`) to fetch user info and potentially interact with OSM directly (Managed in `app/services/osm-auth.js`).
+
+### Directory Structure Highlights
+
+- `app/components/`: UI components using `.gjs` (Glimmer JS with embedded `<template>` tags).
+- `app/services/`: Core business logic, state management, and API integrations.
+- `app/utils/`: Helper functions for geohashing, parsing OSM tags, icon mapping, and link formatting.
+- `tests/`: Comprehensive QUnit test suite containing unit, integration, and acceptance tests.
+
+### Key Libraries
+
+- `ember-concurrency` / `ember-lifeline`: Managing async tasks and debouncing.
+- `remotestorage-widget`: The UI widget for connecting to a RemoteStorage provider.

doc/nostr/nip-place-reviews.md

@@ -0,0 +1,343 @@
+# NIP-XX: Place Reviews
+
+## Abstract
+
+This NIP defines a standardized event format for decentralized place reviews using Nostr. Reviews are tied to real-world locations (e.g. OpenStreetMap POIs) via tags, and include structured, multi-aspect ratings, a binary recommendation signal, and optional contextual metadata.
+
+The design prioritizes:
+
+* Small event size
+* Interoperability across clients
+* Flexibility for different place types
+* Efficient geospatial querying using geohashes
+
+---
+
+## Event Kind
+
+`kind: 30315` (suggested; subject to coordination)
+
+---
+
+## Tags
+
+Additional tags MAY be included by clients but are not defined by this specification.
+
+This NIP reuses and builds upon existing Nostr tag conventions:
+
+* `i` tag: see NIP-73 (External Content Identifiers)
+* `g` tag: geohash-based geotagging (community conventions)
+
+Where conflicts arise, this NIP specifies the behavior for review events.
+
+### Required
+
+#### `i` — Entity Identifier
+
+Identifies the reviewed place using an external identifier. OpenStreetMap data is the default:
+
+```
+["i", "osm:<type>:<id>"]
+```
+
+Requirements:
+
+* For OSM POIs, `<type>` MUST be one of: `node`, `way`, `relation`
+
+Examples:
+
+```
+["i", "osm:node:123456"]
+["i", "osm:way:987654"]
+```
+
+---
+
+### Geospatial Tags
+
+#### `g` — Geohash
+
+Geohash tags are used for spatial indexing and discovery.
+
+##### Requirements
+
+* Clients MUST include at least one high-precision geohash (length ≥ 9)
+
+##### Recommendations
+
+Clients SHOULD include geohashes at the following resolutions:
+
+* length 4 — coarse (city-scale discovery)
+* length 6 — medium (default query level, ~1 km)
+* length 7 — fine (neighborhood, ~150 m)
+
+Example:
+
+```
+["g", "thrr"]
+["g", "thrrn5"]
+["g", "thrrn5k"]
+["g", "thrrn5kxyz"]
+```
+
+##### Querying
+
+Geospatial queries are performed using the `g` tag.
+
+* Clients SHOULD query using a single geohash precision level per request
+* Clients MAY include multiple geohash values in a filter to cover a bounding box
+* Clients SHOULD limit the number of geohash values per query (e.g. ≤ 30)
+* Clients MAY reduce precision or split queries when necessary
+
+Note: Other queries (e.g. fetching reviews for a specific place) are performed using the `i` tag and are outside the scope of geospatial querying.
+
+---
+
+## Content (JSON)
+
+The event `content` MUST be valid JSON matching the following schema.
+
+### Schema
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": ["version", "ratings"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1
+    },
+    "ratings": {
+      "type": "object",
+      "required": ["quality"],
+      "additionalProperties": false,
+      "properties": {
+        "quality": { "$ref": "#/$defs/score" },
+        "value": { "$ref": "#/$defs/score" },
+        "experience": { "$ref": "#/$defs/score" },
+        "accessibility": { "$ref": "#/$defs/score" },
+        "aspects": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 20,
+          "additionalProperties": { "$ref": "#/$defs/score" },
+          "propertyNames": {
+            "pattern": "^[a-z][a-z0-9_]{1,31}$"
+          }
+        }
+      }
+    },
+    "recommend": {
+      "type": "boolean"
+    },
+    "familiarity": {
+      "type": "string",
+      "enum": ["low", "medium", "high"],
+      "description": "User familiarity: low = first visit; medium = occasional; high = frequent"
+    },
+    "context": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "visited_at": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "duration_minutes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 1440
+        },
+        "party_size": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100
+        }
+      }
+    },
+    "review": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "text": {
+          "type": "string",
+          "maxLength": 1000
+        },
+        "language": {
+          "type": "string",
+          "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "score": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 10
+    }
+  }
+}
+```
+
+---
+
+## Example
+
+### Restaurant Review Event
+
+#### Tags
+
+```
+[
+  ["i", "osm:node:123456"],
+  ["g", "thrr"],
+  ["g", "thrrn5"],
+  ["g", "thrrn5k"],
+  ["g", "thrrn5kxyz"]
+]
+```
+
+#### Content
+
+```json
+{
+  "version": 1,
+  "ratings": {
+    "quality": 9,
+    "value": 8,
+    "experience": 9,
+    "accessibility": 7,
+    "aspects": {
+      "food": 9,
+      "service": 6,
+      "ambience": 8,
+      "wait_time": 5
+    }
+  },
+  "recommend": true,
+  "familiarity": "medium",
+  "context": {
+    "visited_at": 1713200000,
+    "duration_minutes": 90,
+    "party_size": 2
+  },
+  "review": {
+    "text": "Excellent food with bold flavors. Service was a bit slow, but the atmosphere made up for it.",
+    "language": "en"
+  }
+}
+```
+
+---
+
+## Semantics
+
+### Ratings
+
+* Scores are integers from 1 to 10
+* `quality` is required and represents the core evaluation of the place
+* Other fields are optional and context-dependent
+
+### Aspects
+
+* Free-form keys allow domain-specific ratings
+* Clients MAY define and interpret aspect keys
+* Clients SHOULD reuse commonly established aspect keys where possible
+
+---
+
+## Recommendation Signal
+
+The `recommend` field represents a binary verdict:
+
+* `true` → user recommends the place
+* `false` → user does not recommend the place
+
+Clients SHOULD strongly encourage users to provide this value.
+
+---
+
+## Familiarity
+
+Represents user familiarity with the place:
+
+* `low` → first visit or limited exposure
+* `medium` → occasional visits
+* `high` → frequent or expert-level familiarity
+
+Clients MAY use this signal for weighting during aggregation.
+
+---
+
+## Context
+
+Optional metadata about the visit.
+
+* `visited_at` is a Unix timestamp
+* `duration_minutes` represents time spent
+* `party_size` indicates group size
+
+---
+
+## Interoperability
+
+This specification defines a content payload only.
+
+* In Nostr: place identity is conveyed via tags
+* In other protocols (e.g. ActivityPub, AT Protocol): identity MUST be mapped to the equivalent field (e.g. `object`)
+
+Content payloads SHOULD NOT include place identifiers.
+
+---
+
+## Rationale
+
+### No Place Field in Content
+
+Avoids duplication and inconsistency with tags.
+
+### Multi-Aspect Ratings
+
+Separates concerns (e.g. quality vs service), improving signal quality.
+
+### Recommendation vs Score
+
+Binary recommendation avoids averaging pitfalls and improves ranking.
+
+### Familiarity
+
+Provides a human-friendly proxy for confidence without requiring numeric input.
+
+### Geohash Strategy
+
+Multiple resolutions balance:
+
+* efficient querying
+* small event size
+* early-stage discoverability
+
+---
+
+## Future Work
+
+* Standardized aspect vocabularies
+* Reputation and weighting models
+* Indexing/aggregation services
+* Cross-protocol mappings
+
+---
+
+## Security Considerations
+
+* Clients SHOULD validate all input
+* Malicious or spam reviews may require external moderation or reputation systems
+
+---
+
+## Copyright
+
+This NIP is public domain.

doc/nostr/notes.md

@@ -0,0 +1,6 @@
+# Notes
+
+- NIP-73 for external IDs ("osm:node:123456"): https://github.com/nostr-protocol/nips/blob/744bce8fcae0aca07b936b6662db635c8b4253dd/73.md
+- Places NIP-XX draft PR: https://github.com/nostr-protocol/nips/pull/927
+- NPM package for generating multi-resolution geotags: https://sandwichfarm.github.io/nostr-geotags/#md:nostr-geotags
+- AppleSauce docs for AI agents: https://applesauce.build/introduction/mcp-server.html

doc/nostr/ranking.md

@@ -0,0 +1,251 @@
+# Ranking Algorithm
+
+Your inputs:
+
+* many users
+* partial ratings
+* different priorities
+
+Your output:
+
+> “Best place *for this user right now*”
+
+---
+
+## Step 1: Normalize scores
+
+Convert 1–10 → 0–1:
+
+```text
+normalized_score = (score - 1) / 9
+```
+
+Why:
+
+* easier math
+* comparable across aspects
+
+---
+
+## Step 2: Per-aspect aggregation (avoid averages trap)
+
+Instead of mean, compute:
+
+### A. Positive ratio
+
+```text
+positive = score >= 7
+negative = score <= 4
+```
+
+Then:
+
+```text
+positive_ratio = positive_votes / total_votes
+```
+
+---
+
+### B. Confidence-weighted score
+
+Use something like a **Wilson score interval** (this is key):
+
+* prevents small-sample abuse
+* avoids “1 review = #1 place”
+
+---
+
+## Step 3: Build aspect scores
+
+For each aspect:
+
+```text
+aspect_score = f(
+  positive_ratio,
+  confidence,
+  number_of_reviews
+)
+```
+
+You can approximate with:
+
+```text
+aspect_score = positive_ratio * log(1 + review_count)
+```
+
+(Simple, works surprisingly well)
+
+---
+
+## Step 4: User preference weighting
+
+User defines:
+
+```json
+{
+  "quality": 0.5,
+  "value": 0.2,
+  "service": 0.2,
+  "speed": 0.1
+}
+```
+
+Then:
+
+```text
+final_score = Σ (aspect_score × weight)
+```
+
+---
+
+## Step 5: Context filtering (this is your unfair advantage)
+
+Filter reviews before scoring:
+
+* time-based:
+
+  * “last 6 months”
+* context-based:
+
+  * lunch vs dinner
+  * solo vs group
+
+This is something centralized platforms barely do.
+
+---
+
+## Step 6: Reviewer weighting (later, but powerful)
+
+Weight reviews by:
+
+* consistency
+* similarity to user preferences
+* past agreement
+
+This gives you:
+
+> “people like you liked this”
+
+---
+
+# 3. Example end-to-end
+
+### Raw reviews:
+
+| User | Food | Service |
+| ---- | ---- | ------- |
+| A    | 9    | 4       |
+| B    | 8    | 5       |
+| C    | 10   | 3       |
+
+---
+
+### Derived:
+
+* food → high positive ratio (~100%)
+* service → low (~33%)
+
+---
+
+### User preferences:
+
+```json
+{
+  "food": 0.8,
+  "service": 0.2
+}
+```
+
+→ ranks high
+
+Another user:
+
+```json
+{
+  "food": 0.3,
+  "service": 0.7
+}
+```
+
+→ ranks low
+
+👉 Same data, different truth
+That’s your killer feature.
+
+---
+
+# 4. Critical design choices (don’t skip these)
+
+## A. No global score in protocol
+
+Let clients compute it.
+
+---
+
+## B. Embrace incomplete data
+
+Most reviews will have:
+
+* 1–3 aspects only
+
+That’s fine.
+
+---
+
+## C. Time decay (important)
+
+Recent reviews should matter more:
+
+```text
+weight = e^(-λ × age)
+```
+
+---
+
+## D. Anti-gaming baseline
+
+Even in nostr:
+
+* spam will happen
+
+Mitigation later:
+
+* require minimum interactions
+* reputation layers
+
+---
+
+# 5. What you’ve built (zooming out)
+
+This is not a review system.
+
+It’s:
+
+> A decentralized, multi-dimensional reputation graph for real-world places
+
+That’s much bigger.
+
+---
+
+# 6. Next step (if you want to go deeper)
+
+We can design:
+
+### A. Query layer
+
+* how clients fetch & merge nostr reviews efficiently
+
+### B. Anti-spam / trust model
+
+* web-of-trust
+* staking / reputation
+
+### C. OSM integration details
+
+* handling duplicates
+* POI identity conflicts
+
+---
+
+If I had to pick one next:
+👉 **trust/reputation system** — because without it, everything you built *will* get gamed.

doc/nostr/ratings.md

@@ -0,0 +1,110 @@
+# Canonical Aspect Vocabulary (v0.1)
+
+You want a **soft standard**, not a rigid schema.
+
+Think:
+
+* “recommended keys” (clients SHOULD use)
+* not “required keys” (protocol enforces)
+
+---
+
+## A. Core universal aspects (keep this small)
+
+These should work for *any* place:
+
+```json
+[
+  "quality",      // core offering (food, repair, exhibits, etc.)
+  "value",        // value for money/time
+  "experience",   // comfort, usability, vibe
+  "accessibility" // ease of access, inclusivity
+]
+```
+
+### Why these work
+
+* **quality** → your “product” abstraction (critical)
+* **value** → universally meaningful signal
+* **experience** → captures everything “soft”
+* **accessibility** → often ignored but high utility
+
+👉 Resist adding more. Every extra “universal” weakens the concept.
+
+---
+
+## B. Common cross-domain aspects (recommended pool)
+
+Not universal, but widely reusable:
+
+```json
+[
+  "service",       // human interaction
+  "speed",         // waiting time / turnaround
+  "cleanliness",
+  "safety",
+  "reliability",
+  "atmosphere"
+]
+```
+
+These apply to:
+
+* restaurants, garages, clinics, parks, etc.
+
+---
+
+## C. Domain-specific examples (NOT standardized)
+
+Let clients define freely:
+
+```json
+{
+  "restaurant": ["food", "drinks"],
+  "bar": ["drinks", "music"],
+  "garage": ["work_quality", "honesty"],
+  "park": ["greenery", "amenities"],
+  "museum": ["exhibits", "crowding"]
+}
+```
+
+---
+
+## D. Key rule (this prevents chaos)
+
+👉 **Aspect keys MUST be lowercase snake_case**
+
+👉 **Meaning is defined socially, not technically**
+
+To reduce fragmentation:
+
+* publish a **public registry (GitHub repo)**
+* clients can:
+
+  * suggest additions
+  * map synonyms
+
+---
+
+## E. Optional normalization hint (important later)
+
+Allow this:
+
+```json
+"aspect_aliases": {
+  "food": "quality",
+  "work_quality": "quality"
+}
+```
+
+Not required, but useful for aggregation engines.
+
+---
+
+## Notes
+
+Map familiarity in UI to:
+
+* high: “I know this place well”
+* medium: “Been a few times”
+* low: “First visit”

doc/nostr/review-schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.org/schemas/place-review.json",
+  "title": "Decentralized Place Review (Nostr/Event Content)",
+  "type": "object",
+  "required": ["version", "place", "ratings"],
+  "additionalProperties": false,
+
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1
+    },
+
+    "ratings": {
+      "type": "object",
+      "required": ["quality"],
+      "additionalProperties": false,
+      "properties": {
+        "quality": { "$ref": "#/$defs/score" },
+        "value": { "$ref": "#/$defs/score" },
+        "experience": { "$ref": "#/$defs/score" },
+        "accessibility": { "$ref": "#/$defs/score" },
+
+        "aspects": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 20,
+          "additionalProperties": { "$ref": "#/$defs/score" },
+          "propertyNames": {
+            "pattern": "^[a-z][a-z0-9_]{1,31}$"
+          }
+        }
+      }
+    },
+
+    "recommend": {
+      "type": "boolean",
+      "description": "Whether the user recommends this place to others"
+    },
+
+    "familiarity": {
+      "type": "string",
+      "enum": ["low", "medium", "high"],
+      "description": "User familiarity with the place. Suggested interpretation: 'low' = first visit or very limited experience; 'medium' = visited a few times or moderate familiarity; 'high' = frequent visitor or strong familiarity."
+    },
+
+    "context": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "visited_at": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "duration_minutes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 1440
+        },
+        "party_size": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100
+        }
+      }
+    },
+
+    "review": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "text": {
+          "type": "string",
+          "maxLength": 1000
+        },
+        "language": {
+          "type": "string",
+          "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
+        }
+      }
+    }
+  },
+
+  "$defs": {
+    "score": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 10
+    }
+  }
+}

skills-lock.json

@@ -5,6 +5,16 @@
       "source": "nullvoxpopuli/agent-skills",
       "sourceType": "github",
       "computedHash": "7909c3def6c4ddefb358d1973cf724269ede9f6cdba1dd2888e4e6072a897f3e"
+    },
+    "nak": {
+      "source": "soapbox-pub/nostr-skills",
+      "sourceType": "github",
+      "computedHash": "710d3f3945ff421ed2b7f40ecd32c5e263bc029d43fe8f4fd1491a8013c7389a"
+    },
+    "nostr": {
+      "source": "soapbox-pub/nostr-skills",
+      "sourceType": "github",
+      "computedHash": "e1e6834c18d18a5deef4cd9555f6eee0fc0b968acf1c619253999eda76beab8e"
     }
   }
 }