From 2268a607d5c800f72be648f938c1826e898a36b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A2u=20Cao?= Date: Sat, 18 Apr 2026 18:35:45 +0400 Subject: [PATCH] Format docs --- doc/nostr/nip-place-photos.md | 12 ++--- doc/nostr/nip-place-reviews.md | 80 +++++++++++++++++----------------- doc/nostr/ranking.md | 57 ++++++++++++------------ doc/nostr/ratings.md | 37 ++++++++-------- 4 files changed, 93 insertions(+), 93 deletions(-) diff --git a/doc/nostr/nip-place-photos.md b/doc/nostr/nip-place-photos.md index 4994cf0..2c22c58 100644 --- a/doc/nostr/nip-place-photos.md +++ b/doc/nostr/nip-place-photos.md @@ -29,7 +29,8 @@ Identifies the exact place the media depicts using an external identifier (as de ```json ["i", "osm:node:123456"] ``` -* For OSM POIs, `` MUST be one of: `node`, `way`, `relation`. + +- For OSM POIs, `` MUST be one of: `node`, `way`, `relation`. #### 2. `g` — Geohash @@ -61,9 +62,9 @@ Clients SHOULD include `alt` (accessibility descriptions), `dim` (dimensions), ` ### Optional Tags -* `t`: Hashtags for categorization (e.g., `["t", "food"]`, `["t", "architecture"]`). -* `content-warning`: If the media contains NSFW or sensitive imagery. -* `published_at`: Unix timestamp of when the photo was originally taken or published. +- `t`: Hashtags for categorization (e.g., `["t", "food"]`, `["t", "architecture"]`). +- `content-warning`: If the media contains NSFW or sensitive imagery. +- `published_at`: Unix timestamp of when the photo was originally taken or published. ## Example Event @@ -80,7 +81,8 @@ Clients SHOULD include `alt` (accessibility descriptions), `dim` (dimensions), ` ["g", "xn0m7h"], ["g", "xn0m7hwq"], - ["imeta", + [ + "imeta", "url https://example.com/ramen.jpg", "m image/jpeg", "dim 1080x1080", diff --git a/doc/nostr/nip-place-reviews.md b/doc/nostr/nip-place-reviews.md index efe8861..177d6d9 100644 --- a/doc/nostr/nip-place-reviews.md +++ b/doc/nostr/nip-place-reviews.md @@ -8,10 +8,10 @@ This NIP defines a standardized event format for decentralized place reviews usi The design prioritizes: -* Small event size -* Interoperability across clients -* Flexibility for different place types -* Efficient geospatial querying using geohashes +- Small event size +- Interoperability across clients +- Flexibility for different place types +- Efficient geospatial querying using geohashes ## Event Kind @@ -23,8 +23,8 @@ Additional tags MAY be included by clients but are not defined by this specifica 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) +- `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. @@ -40,7 +40,7 @@ Identifies the reviewed place using an external identifier. OpenStreetMap data i Requirements: -* For OSM POIs, `` MUST be one of: `node`, `way`, `relation` +- For OSM POIs, `` MUST be one of: `node`, `way`, `relation` Examples: @@ -57,15 +57,15 @@ Geohash tags are used for spatial indexing and discovery. ##### Requirements -* Clients MUST include at least one high-precision geohash (length ≥ 9) +- 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) +- length 4 — coarse (city-scale discovery) +- length 6 — medium (default query level, ~1 km) +- length 7 — fine (neighborhood, ~150 m) Example: @@ -80,10 +80,10 @@ Example: 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 +- 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. @@ -228,22 +228,22 @@ The event `content` MUST be valid JSON matching the following schema. ### 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 +- 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 +- 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 +- `true` → user recommends the place +- `false` → user does not recommend the place Clients SHOULD strongly encourage users to provide this value. @@ -251,9 +251,9 @@ Clients SHOULD strongly encourage users to provide this value. Represents user familiarity with the place: -* `low` → first visit or limited exposure -* `medium` → occasional visits -* `high` → frequent or expert-level familiarity +- `low` → first visit or limited exposure +- `medium` → occasional visits +- `high` → frequent or expert-level familiarity Clients MAY use this signal for weighting during aggregation. @@ -261,16 +261,16 @@ Clients MAY use this signal for weighting during aggregation. Optional metadata about the visit. -* `visited_at` is a Unix timestamp -* `duration_minutes` represents time spent -* `party_size` indicates group size +- `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`) +- 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. @@ -296,18 +296,18 @@ Provides a human-friendly proxy for confidence without requiring numeric input. Multiple resolutions balance: -* efficient querying -* small event size -* early-stage discoverability +- efficient querying +- small event size +- early-stage discoverability ## Future Work -* Standardized aspect vocabularies -* Reputation and weighting models -* Indexing/aggregation services -* Cross-protocol mappings +- 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 +- Clients SHOULD validate all input +- Malicious or spam reviews may require external moderation or reputation systems diff --git a/doc/nostr/ranking.md b/doc/nostr/ranking.md index 7f5489e..f39bf33 100644 --- a/doc/nostr/ranking.md +++ b/doc/nostr/ranking.md @@ -2,13 +2,13 @@ Your inputs: -* many users -* partial ratings -* different priorities +- many users +- partial ratings +- different priorities Your output: -> “Best place *for this user right now*” +> “Best place _for this user right now_” --- @@ -22,8 +22,8 @@ normalized_score = (score - 1) / 9 Why: -* easier math -* comparable across aspects +- easier math +- comparable across aspects --- @@ -50,8 +50,8 @@ positive_ratio = positive_votes / total_votes Use something like a **Wilson score interval** (this is key): -* prevents small-sample abuse -* avoids “1 review = #1 place” +- prevents small-sample abuse +- avoids “1 review = #1 place” --- @@ -102,13 +102,12 @@ final_score = Σ (aspect_score × weight) Filter reviews before scoring: -* time-based: +- time-based: + - “last 6 months” - * “last 6 months” -* context-based: - - * lunch vs dinner - * solo vs group +- context-based: + - lunch vs dinner + - solo vs group This is something centralized platforms barely do. @@ -118,9 +117,9 @@ This is something centralized platforms barely do. Weight reviews by: -* consistency -* similarity to user preferences -* past agreement +- consistency +- similarity to user preferences +- past agreement This gives you: @@ -142,8 +141,8 @@ This gives you: ### Derived: -* food → high positive ratio (~100%) -* service → low (~33%) +- food → high positive ratio (~100%) +- service → low (~33%) --- @@ -186,7 +185,7 @@ Let clients compute it. Most reviews will have: -* 1–3 aspects only +- 1–3 aspects only That’s fine. @@ -206,12 +205,12 @@ weight = e^(-λ × age) Even in nostr: -* spam will happen +- spam will happen Mitigation later: -* require minimum interactions -* reputation layers +- require minimum interactions +- reputation layers --- @@ -233,19 +232,19 @@ We can design: ### A. Query layer -* how clients fetch & merge nostr reviews efficiently +- how clients fetch & merge nostr reviews efficiently ### B. Anti-spam / trust model -* web-of-trust -* staking / reputation +- web-of-trust +- staking / reputation ### C. OSM integration details -* handling duplicates -* POI identity conflicts +- handling duplicates +- POI identity conflicts --- If I had to pick one next: -👉 **trust/reputation system** — because without it, everything you built *will* get gamed. +👉 **trust/reputation system** — because without it, everything you built _will_ get gamed. diff --git a/doc/nostr/ratings.md b/doc/nostr/ratings.md index 9e69d02..593091e 100644 --- a/doc/nostr/ratings.md +++ b/doc/nostr/ratings.md @@ -2,23 +2,23 @@ ## A. Core universal aspects -These should work for *any* place: +These should work for _any_ place: ```json [ - "quality", // core offering (food, repair, exhibits, etc.) - "value", // value for money/time - "experience", // comfort, usability, vibe + "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 +- **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. @@ -30,8 +30,8 @@ Not universal, but widely reusable: ```json [ - "service", // human interaction - "speed", // waiting time / turnaround + "service", // human interaction + "speed", // waiting time / turnaround "cleanliness", "safety", "reliability", @@ -41,7 +41,7 @@ Not universal, but widely reusable: These apply to: -* restaurants, garages, clinics, parks, etc. +- restaurants, garages, clinics, parks, etc. --- @@ -69,11 +69,10 @@ Let clients define freely: To reduce fragmentation: -* publish a **public registry (GitHub repo)** -* clients can: - - * suggest additions - * map synonyms +- publish a **public registry (GitHub repo)** +- clients can: + - suggest additions + - map synonyms --- @@ -96,6 +95,6 @@ Not required, but useful for aggregation engines. Map familiarity in UI to: -* high: “I know this place well” -* medium: “Been a few times” -* low: “First visit” +- high: “I know this place well” +- medium: “Been a few times” +- low: “First visit”