> **Nostr Agent Onboarding** · [start here](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/start.md) · [index](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/llms.txt) · source: `Nostr-exp/README.md` · snapshot 2026-10-10
>
> Paths such as `~/Documents/…`, `~/Production Environment/…`, `repos/…` and services on `localhost` refer 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`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/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`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/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`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/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`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/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`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/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/`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/fiatjaf/README.md) — 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/`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/constant/README.md) — Constant (Wouter Constant,
  techno-ethica.com), owner of this workspace: teach the paradigm, relays
  for curation, identity ≠ key, TEPP, OpenTimestamps. `research.md` is the
  full corpus pass.
- [`voices/no-solutions/`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/voices/no-solutions/README.md) — Gigi & Pablo
  Fernandez's Sovereign Engineering podcast: no-global, rug-pull resistance,
  trade-offs out loud, the local relay, Nostr as AI substrate. `episodes.md`
  has 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`](https://npub1d70emggs6jzun5lhvqnfqsd9reqmaarn2qjf6q3r02gryyl4v8sqjn44xe.nsite.lol/docs/design/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.