From 0aa79d08fd45fa693d8f90d3aaa7b8a1c5cd10b2 Mon Sep 17 00:00:00 2001
From: Jon Staab <jstaab@protonmail.com>
Date: Wed, 8 Apr 2026 15:20:56 -0700
Subject: [PATCH] Add building-nostr to ref, flesh out summary

---
 .agents/skills/research-chapter/SKILL.md | 23 +++++++--
 AGENTS.md                                | 15 +++++-
 book/SUMMARY.md                          | 64 +++++++++++++++++++++++-
 3 files changed, 95 insertions(+), 7 deletions(-)

diff --git a/.agents/skills/research-chapter/SKILL.md b/.agents/skills/research-chapter/SKILL.md
index 1f85b8f..d1d2744 100644
--- a/.agents/skills/research-chapter/SKILL.md
+++ b/.agents/skills/research-chapter/SKILL.md
@@ -14,10 +14,21 @@ Before doing any research, ask the user to provide a brief summary of what this
 should cover. What concepts, data structures, protocols, or functionality should the
 research focus on? Wait for their response before proceeding.
 
-## Step 2: Research Reference Implementations
+## Step 2: Research References
 
-Once you have the topic summary, spawn **one sub-agent per reference implementation** in
-`./ref/` to analyze them in parallel. Each sub-agent should:
+Once you have the topic summary, research the references in `./ref/` in parallel.
+
+### Philosophy Reference
+
+Spawn a sub-agent to read `ref/building-nostr` for content relevant to the chapter topic.
+This is not code — it's high-level ideas about what nostr is and how to work with it.
+Extract any philosophical framing, design principles, or conceptual guidance that should
+inform the chapter's narrative and approach.
+
+### Code References
+
+Spawn **one sub-agent per code reference implementation** to analyze them in parallel.
+Each sub-agent should:
 
 1. Search the reference implementation for code relevant to the chapter topic
 2. Analyze in depth:
@@ -29,7 +40,7 @@ Once you have the topic summary, spawn **one sub-agent per reference implementat
 3. Return a detailed summary focusing **only on functionality relevant to the chapter topic**
    — ignore unrelated parts of the library
 
-The six reference implementations to analyze:
+The six code reference implementations to analyze:
 - `ref/applesauce` (TypeScript — noStrudel ecosystem)
 - `ref/ndk` (TypeScript — Nostr Development Kit)
 - `ref/nostr-gadgets` (TypeScript — high-level utilities, JSR)
@@ -51,6 +62,10 @@ The research file should have this structure:
 
 <The topic summary provided by the user in Step 1>
 
+## Philosophy
+
+<Relevant ideas, principles, and framing from ref/building-nostr>
+
 ## Reference Implementation Analysis
 
 ### applesauce
diff --git a/AGENTS.md b/AGENTS.md
index 8ea6e95..d797280 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -54,9 +54,20 @@ Always run `just all` to validate changes.
 - The narrative should flow naturally — explain *why* before showing *what*
 - Write prose that a developer new to nostr could follow from start to finish
 
-## Reference Implementations
+## Reference Materials
 
-The `ref/` directory contains nostr library implementations used for research:
+The `ref/` directory contains resources used for research, split into two categories.
+
+### Philosophy
+
+| Directory | Description |
+|-----------|-------------|
+| `ref/building-nostr` | High-level ideas about what nostr is and how to work with it — philosophy, not code |
+
+This resource should inform the narrative voice, design philosophy, and conceptual framing
+of chapters, but is not a source of implementation patterns.
+
+### Implementations
 
 | Directory | Language | Description |
 |-----------|----------|-------------|
diff --git a/book/SUMMARY.md b/book/SUMMARY.md
index f37be86..5539927 100644
--- a/book/SUMMARY.md
+++ b/book/SUMMARY.md
@@ -1,4 +1,66 @@
 # Summary
 
 - [Introduction](01-introduction.md)
-- [Events](02-events.md)
+
+## Basics
+
+- [Keys](02-keys.md)
+- [Signing](03-signing.md)
+- [Encryption](04-encryption.md)
+- [Encryptables](xx.md)
+- [Events](xx.md)
+- [Tags](xx.md)
+- [Kinds](xx.md)
+- [Kind Ranges](xx.md)
+- [Addresses](xx.md)
+- [Proof of Work](xx.md)
+- [Filters](xx.md)
+
+## Domain
+
+- [Relay Selections](xx.md)
+- [Relay Metadata](xx.md)
+- [Relay Membership](xx.md)
+- [Profiles](xx.md)
+- [Follows](xx.md)
+- [Microblogging](xx.md)
+- [Reactions](xx.md)
+- [Reports](xx.md)
+- [Emojis](xx.md)
+- [Zaps](xx.md)
+- Split out each list kind into its own chapter
+- [Rooms](xx.md)
+
+## Networking
+
+- [Relay Connections](xx.md)
+- [Relay Authentication](xx.md)
+- [Relay Policies](xx.md)
+- [Server Authentication](xx.md)
+- [Relay Management API](xx.md)
+- [Blossom Media Storage](xx.md)
+
+## Signers
+
+- [Secret Signers](xx.md)
+- [Remote Signers](xx.md)
+- [Android Signers](xx.md)
+- [Browser Signers](xx.md)
+
+## Content
+
+- [Entities](xx.md)
+- [Relays](xx.md)
+- [Rooms](xx.md)
+- [Links](xx.md)
+- [Lightning](xx.md)
+- [Cashu](xx.md)
+- [Emojis](xx.md)
+- [Topics](xx.md)
+- [Code](xx.md)
+
+## Storage
+
+- [Event Repository](xx.md)
+- [In Memory Backend](xx.md)
+- [Sqlite Backend](xx.md)