Nostr Protocol Manual — Page Authoring Guide

You are authoring ONE chapter of a static site: a complete dictionary of Nostr NIPs styled as an early-2000s printed game manual. Follow this guide exactly. The finished exemplar is site/nips/01.html — read it first and match it precisely (structure, classes, tone).

Hard rules

1. The character · (middle dot) is BANNED. Use - instead. Check your output.
2. Filenames are lowercase: site/nips/<num-lowercase>.html (e.g. 5a.html, a0.html, f4.html).
3. Cross-links to other NIPs are relative: <a href="19.html">NIP-19</a>. Link every NIP mention.
4. Full coverage: EVERY normative rule, kind, tag, field, message type, and error code in the source markdown must appear on the page, restated. Never drop a table row or a defined kind. Restate in your own STE prose; do not paste raw markdown.
5. No new CSS files and no <style> blocks except tiny page-specific SVG tweaks if truly needed. Use only ../assets/manual.css classes. No JavaScript.
6. Escape < and > as < > inside code blocks.

Writing style: Simplified Technical English (STE)

• Short sentences: at most ~20 words. One idea per sentence.
• Active voice, present tense. "The relay stores the event." Not "the event will be stored".
• Imperative mood for procedures: "Serialize the event. Hash it with sha256."
• One term per concept, always the same term: event, relay, client, publish, subscribe, sign, kind, tag, filter. Never vary for elegance.
• Define each term at first use. No idioms, no filler, no marketing language.
• The playful 2000s-manual flavor lives ONLY in callout labels, figure captions, and the cartridge/credits framing — never in the technical prose itself.

Page anatomy (in order)

Copy the skeleton from 01.html:

1. <head>: title NIP-XX - <Title> — Nostr Instruction Manual, meta description, the 7 font <link rel="preload"> lines (copy verbatim from 01.html), favicon link (../assets/favicon.svg), stylesheet ../assets/manual.css. Before </body>: <script src="../assets/webmcp.js" defer></script> (the one allowed script — it registers WebMCP tools for browser agents; page content itself stays JS-free). After creating or editing a page, run python3 tools/build_nip_index.py to refresh the agent-facing index.
2. The hidden <svg><defs> block with the arr/arrb arrow markers (copy verbatim from 01.html).
3. .page wrapper with two .staple spans.
4. .band header: logo links to ../index.html; .booklet-note = Chapter XX - <short category> (pick a 1-3 word category: Core, Social, Payments, Encryption, Relay Ops, Media, Commerce, ...).
5. .tabs nav: Contents, Overview, Spec, Examples, History (anchor links).
6. .chapter header: .nipno with data-n="XX" (uppercase), kicker Nostr Implementation Possibility - Hex № XX, <h1> title, one-sentence .sub.
   • Deprecated NIP: add <div class="stamp">Deprecated</div> inside .chapter.
   • Merged NIP: add <div class="stamp merged">Merged</div>.
7. <main class="spread"> grid (a real <main> element, closed with </main> after the </aside>): .main content div + <aside> with the .cartridge spec card. Card headings inside .cartridge and .credits are <h3 class="cardhead"> — never <h5>.
8. Numbered sections as <h2 class="bar"><span class="num">N</span> Title</h2>:
   • 1 Overview — what problem this NIP solves, for whom, in plain STE. 2-4 paragraphs.
   • 2..n Spec sections — the full specification: event formats in .crt terminals, field/tag/kind reference in table.ref, flows as diagrams. Structure follows the source NIP's own structure.
   • Worked Example(s) — at least one realistic end-to-end example: full JSON events and/or a client-relay session transcript in a .crt block (use .send/.recv/.c spans).
   • Version History — .patchnotes list, newest first, 4-10 notable entries, condensed from git history. Last entry = origin (author + date).
   • See Also — related NIPs with one-line reasons. Always link back to NIP-01 dependencies.
9. .credits box: Author (from first commit), First commit date + subject, PR number linked as https://github.com/nostr-protocol/nips/pull/<N> if the first commit subject contains (#N), Status chips, link to https://github.com/nostr-protocol/nips/blob/master/XX.md and its /commits/master/XX.md history.
10. .navbtns: prev / next NIP in hex order (lowercase hrefs, real titles). First page's prev and last page's next go to ../index.html.
11. .pagefoot: left link to ../index.html labeled Nostr Protocol Manual, right <span class="pageno">NIP XX / F4</span>.

Component catalog

• Callouts: <div class="box hint|warn|danger|tech"><span class="tag">Hint!|Warning!|Deprecated|Tech Note</span> <p>…</p></div>
• Code/terminal: .crt with .titlebar and <pre>; span classes k (keys), s (strings), c (comments/placeholders), send (client→relay lines), recv (relay→client lines).
• Tables: <div class="tscroll"><table class="ref">…</table></div> with <caption>; the .tscroll wrapper is mandatory (it gives wide tables horizontal scroll on small screens). Wrap key names in <td class="btn"> or <span class="kbd"> for the chunky-button look.
• Chips: <span class="chip draft|final|mandatory|unrecommended">…</span>.
• Diagrams: <figure class="diagram"><div class="frame"><svg viewBox="…" role="img" aria-label="…"> with classes d-actor, d-actor-label, d-wire, d-msg (orange, arrowhead) / d-msg blue, d-flow (animated marching ants), d-label (mono), d-note. Animate packets with SMIL: <circle r="4" fill="#f26a00"><animateMotion dur="2.6s" repeatCount="indefinite" path="…"/></circle>. Caption: <figcaption>Fig. X-N — <b>Name.</b> One STE sentence.</figcaption>. Add a diagram wherever a flow, structure, or state machine exists (aim for 1-3 per page; 0 is fine only for trivial NIPs). Sequence diagrams: copy Fig. 1-4 pattern from 01.html.
• .stamp for deprecated/merged, hr.tear as a section divider if needed.

Status handling

• Deprecated (unrecommended warning in source): full page anyway. Stamp + a .box danger with tag Deprecated right after the Overview bar, stating the reason from the source warning and linking the replacement NIP. In the cartridge use <span class="led err"></span> leds and an unrecommended chip.
• Merged (12, 16, 20, 33 — "Moved to NIP-01"): a SHORT page. Stamp merged, explain what the NIP defined, when and why it merged into NIP-01, where that content lives now (link the 01.html anchor), short history, credits. No fabricated spec content.
• Note any issues you find (contradictions, dead references, unclear rules) in a .box tech with tag Tech Note — do not silently fix or omit them.

Data sources (all local)

• Spec text: source-nips/XX.md (uppercase filename). Read ALL of it.
• History: cd source-nips && git log --follow --format='%as|%an|%s' -- XX.md (LAST line = origin). Do NOT add --reverse — combined with --follow it can jump into an unrelated file's history via rename detection. Sanity-check that commit subjects actually relate to your NIP's topic; if they look foreign, drop --follow. Condense; group typo fixes as one class="minor" entry or skip them.
• Dates/tags/status: manifest.json (fields: num, title, status, note, tags, created, updated).
• Do not use the network. Everything needed is local. GitHub URLs are constructed, not fetched.

Cartridge spec card

dt/dd rows (adapt to the NIP): Status (chips from manifest tags), Defines (kinds/tags/messages introduced), Kind(s) (numbers), Requires (NIP deps as links), Transport/Crypto if relevant, First commit, Last updated. LEDs: 3 led on for active, led on+2 led warn for draft-ish, 3 led err for deprecated.

QA checklist before finishing

• [ ] No · character anywhere in the file.
• [ ] Every kind, tag, message, and error code from the source appears on the page.
• [ ] All NIP cross-references are links to lowercase local pages.
• [ ] prev/next links point to the correct hex neighbors with correct titles.
• [ ] Valid HTML, all tags closed; </> escaped in code blocks.
• [ ] Diagrams have viewBox, role="img", aria-label, and a figcaption.