1# Nostr Protocol Manual — Page Authoring Guide23You are authoring ONE chapter of a static site: a complete dictionary of Nostr NIPs styled4as an early-2000s printed game manual. Follow this guide exactly. The finished exemplar is5`site/nips/01.html` — **read it first and match it precisely** (structure, classes, tone).67## Hard rules891. **The character `·` (middle dot) is BANNED. Use `-` instead.** Check your output.102. Filenames are lowercase: `site/nips/<num-lowercase>.html` (e.g. `5a.html`, `a0.html`, `f4.html`).113. Cross-links to other NIPs are relative: `<a href="19.html">NIP-19</a>`. Link every NIP mention.124. Full coverage: EVERY normative rule, kind, tag, field, message type, and error code in the13 source markdown must appear on the page, restated. Never drop a table row or a defined kind.14 Restate in your own STE prose; do not paste raw markdown.155. No new CSS files and no `<style>` blocks except tiny page-specific SVG tweaks if truly needed.16 Use only `../assets/manual.css` classes. No JavaScript.176. Escape `<` and `>` as `<` `>` inside code blocks.1819## Writing style: Simplified Technical English (STE)2021- Short sentences: at most ~20 words. One idea per sentence.22- Active voice, present tense. "The relay stores the event." Not "the event will be stored".23- Imperative mood for procedures: "Serialize the event. Hash it with sha256."24- One term per concept, always the same term: event, relay, client, publish, subscribe, sign,25 kind, tag, filter. Never vary for elegance.26- Define each term at first use. No idioms, no filler, no marketing language.27- The playful 2000s-manual flavor lives ONLY in callout labels, figure captions, and the28 cartridge/credits framing — never in the technical prose itself.2930## Page anatomy (in order)3132Copy the skeleton from `01.html`:33341. `<head>`: title `NIP-XX - <Title> — Nostr Instruction Manual`, meta description,35 the 7 font `<link rel="preload">` lines (copy verbatim from 01.html), favicon link36 (`../assets/favicon.svg`), stylesheet `../assets/manual.css`. Before `</body>`:37 `<script src="../assets/webmcp.js" defer></script>` (the one allowed script — it38 registers WebMCP tools for browser agents; page content itself stays JS-free).39 After creating or editing a page, run `python3 tools/build_nip_index.py` to refresh40 the agent-facing index.412. The hidden `<svg><defs>` block with the `arr`/`arrb` arrow markers (copy verbatim from 01.html).423. `.page` wrapper with two `.staple` spans.434. `.band` header: logo links to `../index.html`; `.booklet-note` = `Chapter XX - <short category>`44 (pick a 1-3 word category: Core, Social, Payments, Encryption, Relay Ops, Media, Commerce, ...).455. `.tabs` nav: Contents, Overview, Spec, Examples, History (anchor links).466. `.chapter` header: `.nipno` with `data-n="XX"` (uppercase), kicker47 `Nostr Implementation Possibility - Hex № XX`, `<h1>` title, one-sentence `.sub`.48 - Deprecated NIP: add `<div class="stamp">Deprecated</div>` inside `.chapter`.49 - Merged NIP: add `<div class="stamp merged">Merged</div>`.507. `<main class="spread">` grid (a real `<main>` element, closed with `</main>` after the51 `</aside>`): `.main` content div + `<aside>` with the `.cartridge` spec card.52 Card headings inside `.cartridge` and `.credits` are `<h3 class="cardhead">` — never `<h5>`.538. Numbered sections as `<h2 class="bar"><span class="num">N</span> Title</h2>`:54 - **1 Overview** — what problem this NIP solves, for whom, in plain STE. 2-4 paragraphs.55 - **2..n Spec sections** — the full specification: event formats in `.crt` terminals,56 field/tag/kind reference in `table.ref`, flows as diagrams. Structure follows the57 source NIP's own structure.58 - **Worked Example(s)** — at least one realistic end-to-end example: full JSON events59 and/or a client-relay session transcript in a `.crt` block (use `.send`/`.recv`/`.c` spans).60 - **Version History** — `.patchnotes` list, newest first, 4-10 notable entries, condensed61 from git history. Last entry = origin (author + date).62 - **See Also** — related NIPs with one-line reasons. Always link back to NIP-01 dependencies.639. `.credits` box: Author (from first commit), First commit date + subject, PR number linked as64 `https://github.com/nostr-protocol/nips/pull/<N>` if the first commit subject contains `(#N)`,65 Status chips, link to `https://github.com/nostr-protocol/nips/blob/master/XX.md` and its66 `/commits/master/XX.md` history.6710. `.navbtns`: prev / next NIP in hex order (lowercase hrefs, real titles). First page's prev and68 last page's next go to `../index.html`.6911. `.pagefoot`: left link to `../index.html` labeled `Nostr Protocol Manual`,70 right `<span class="pageno">NIP XX / F4</span>`.7172## Component catalog7374- Callouts: `<div class="box hint|warn|danger|tech"><span class="tag">Hint!|Warning!|Deprecated|Tech Note</span> <p>…</p></div>`75- Code/terminal: `.crt` with `.titlebar` and `<pre>`; span classes `k` (keys), `s` (strings),76 `c` (comments/placeholders), `send` (client→relay lines), `recv` (relay→client lines).77- Tables: `<div class="tscroll"><table class="ref">…</table></div>` with `<caption>`; the78 `.tscroll` wrapper is mandatory (it gives wide tables horizontal scroll on small screens).79 Wrap key names in `<td class="btn">` or `<span class="kbd">` for the chunky-button look.80- Chips: `<span class="chip draft|final|mandatory|unrecommended">…</span>`.81- Diagrams: `<figure class="diagram"><div class="frame"><svg viewBox="…" role="img" aria-label="…">`82 with classes `d-actor`, `d-actor-label`, `d-wire`, `d-msg` (orange, arrowhead) / `d-msg blue`,83 `d-flow` (animated marching ants), `d-label` (mono), `d-note`. Animate packets with SMIL:84 `<circle r="4" fill="#f26a00"><animateMotion dur="2.6s" repeatCount="indefinite" path="…"/></circle>`.85 Caption: `<figcaption>Fig. X-N — <b>Name.</b> One STE sentence.</figcaption>`.86 Add a diagram wherever a flow, structure, or state machine exists (aim for 1-3 per page;87 0 is fine only for trivial NIPs). Sequence diagrams: copy Fig. 1-4 pattern from 01.html.88- `.stamp` for deprecated/merged, `hr.tear` as a section divider if needed.8990## Status handling9192- **Deprecated** (`unrecommended` warning in source): full page anyway. Stamp + a93 `.box danger` with tag `Deprecated` right after the Overview bar, stating the reason from the94 source warning and linking the replacement NIP. In the cartridge use95 `<span class="led err"></span>` leds and an `unrecommended` chip.96- **Merged** (12, 16, 20, 33 — "Moved to NIP-01"): a SHORT page. Stamp `merged`, explain what the97 NIP defined, when and why it merged into NIP-01, where that content lives now (link the 01.html98 anchor), short history, credits. No fabricated spec content.99- Note any issues you find (contradictions, dead references, unclear rules) in a100 `.box tech` with tag `Tech Note` — do not silently fix or omit them.101102## Data sources (all local)103104- Spec text: `source-nips/XX.md` (uppercase filename). Read ALL of it.105- History: `cd source-nips && git log --follow --format='%as|%an|%s' -- XX.md`106 (LAST line = origin). Do NOT add `--reverse` — combined with `--follow` it can jump into an107 unrelated file's history via rename detection. Sanity-check that commit subjects actually108 relate to your NIP's topic; if they look foreign, drop `--follow`.109 Condense; group typo fixes as one `class="minor"` entry or skip them.110- Dates/tags/status: `manifest.json` (fields: num, title, status, note, tags, created, updated).111- Do not use the network. Everything needed is local. GitHub URLs are constructed, not fetched.112113## Cartridge spec card114115`dt/dd` rows (adapt to the NIP): Status (chips from manifest tags), Defines (kinds/tags/messages116introduced), Kind(s) (numbers), Requires (NIP deps as links), Transport/Crypto if relevant,117First commit, Last updated. LEDs: 3 `led on` for active, `led on`+2 `led warn` for draft-ish,1183 `led err` for deprecated.119120## QA checklist before finishing121122- [ ] No `·` character anywhere in the file.123- [ ] Every kind, tag, message, and error code from the source appears on the page.124- [ ] All NIP cross-references are links to lowercase local pages.125- [ ] prev/next links point to the correct hex neighbors with correct titles.126- [ ] Valid HTML, all tags closed; `<`/`>` escaped in code blocks.127- [ ] Diagrams have `viewBox`, `role="img"`, `aria-label`, and a figcaption.