Nostr Agent Onboarding · start here · index · source:
Nostr-exp/README.md· snapshot 2026-10-10Paths such as
~/Documents/…,~/Production Environment/…,repos/…and services onlocalhostrefer to the author's workstation and are not available to you — read them as worked examples of a setup you can recreate.
Nostr-exp — a Nostr knowledge environment
A curated, opinionated description of what Nostr is, how it should work, how to develop for it, and how to design on it — synthesized from the primary voices of the protocol and kept honest about where they disagree.
Built 2026-08-31 from four research streams: fiatjaf's complete web essays
(21 annotated), fiatjaf's on-Nostr publications (24 articles + 425 notes
sampled from his relays), Constant's public Nostr corpus (721 notes, 19
long-form articles, plus web presence), and the No Solutions podcast (37
episodes, 8 analyzed from full transcripts) — layered on top of the
knowledge already codified in the sibling ~/Documents/nostr-dev workspace
(Hodlbod's Building Nostr read in full, NIP-01, the NIPs registry, the
outbox literature, nostrdesign.org, the OpenSats report, Nostr Rising).
Read this first: core/
The synthesis, in reading order:
| Doc | Question it answers |
|---|---|
core/01-what-nostr-is.md |
What is Nostr? Events, kinds, relays, NIPs, what it is not, why not the alternatives. |
core/02-how-it-should-work.md |
The intended architecture: the routing problem, outbox and its limits, hints, spam, no-global, the local relay, the failure model. |
core/03-how-to-develop.md |
The practitioner's layer: build pieces not platforms, the dev loop, keys and signing, fault tolerance, onboarding, anti-patterns, definition of done. |
core/04-how-to-design.md |
The design methodology: schema → class → routing → failure model, kind allocation, privacy, communities, value-for-value, trust, the arbitrating principles. |
core/05-current-frontier.md |
Where the live edge is (late 2026): relay feeds, Blossom/nsites/Zapstore, signers, TEPP, FIPS, the AI convergence, open problems. |
The voices: voices/
Primary-source research with distillations — including where the principals disagree, which is the most instructive part:
voices/fiatjaf/— the creator. Relay-centric, anti-super-peer, "censorship-resistance is emergent client behavior."essays.md(web bibliography) +on-nostr.md(his relay publications).voices/constant/— Constant (Wouter Constant, techno-ethica.com), owner of this workspace: teach the paradigm, relays for curation, identity ≠ key, TEPP, OpenTimestamps.research.mdis the full corpus pass.voices/no-solutions/— Gigi & Pablo Fernandez's Sovereign Engineering podcast: no-global, rug-pull resistance, trade-offs out loud, the local relay, Nostr as AI substrate.episodes.mdhas the full episode table + transcript notes.
Key live disagreements to know about: keys-vs-relays as "the point" (Hodlbod vs fiatjaf), spam filtering relay-side vs client-side (fiatjaf vs Malmi), teach-the-paradigm vs hide-the-complexity (Constant vs much of the client scene), whether the NIPs repo should exist (fiatjaf vs Hodlbod), and whether DMs belong on Nostr at all (Constant/hzrd149 vs Malmi).
Reference: sources/
Vendored and summarized source docs, seeded from nostr-dev/docs/sources/:
NIP-01 (full text), the NIPs kind registry, the outbox model, Blossom,
fiatjaf's "vision" essay, Hodlbod's book pointer, nostrdesign.org
principles, the OpenSats client report, Nostr Rising episodes, video
pointers. Machine-local paths inside these files (e.g.
repos/building-nostr/) refer to the ~/Documents/nostr-dev workspace,
which also holds the tooling (nak, ngit, local relay/GRASP/Blossom stack)
for putting any of this into practice.
nostr-dev/docs/sources/ is canonical — these are copies, last synced
2026-09-21, and it also carries sources this directory does not (fips.md,
zapstore.md). Refresh there, then copy across; the refresh recipe is in
nostr-dev/docs/README.md. Likewise, the how layer lives there: the
patterns/ directory (signer login, nsite publishing, the Go baseline,
Zapstore publishing) and known-issues.md are where this synthesis turns
into working code.
The one-paragraph version
Nostr is a description, not a system: signed JSON events plus dumb, plural, interchangeable relays. Signatures move authenticity into the data itself, which frees identity from platforms and storage from trust; the price is that there is no global view, no consistency, and no guarantees — only routing heuristics, redundancy, and webs of trust. Everything good about it (credible exit, rug-pull resistance, permissionless building) and everything hard about it (discovery, spam, key loss, sync) follows from that one trade. To work on Nostr is to accept the trade explicitly: build small interoperable pieces, route events deliberately, state your trade-offs out loud, and keep the barrier to entry for the next client low — because the number of independent clients, not the user count, is the protocol's real health metric.