Set up literate programming structure

book/01-introduction.md

@@ -0,0 +1,49 @@
+# Introduction
+
+Nostr is a simple, open protocol for decentralized social networking. Unlike traditional
+platforms, nostr has no central server. Instead, users publish signed messages called
+**events** to a network of **relays** — simple WebSocket servers that store and forward
+events.
+
+The protocol's power comes from its simplicity. At its core, nostr defines just one data
+structure (the event) and a handful of message types for communicating with relays. Everything
+else — social graphs, encrypted messaging, long-form content, marketplace listings — is built
+on top of this foundation through a system of **NIPs** (Nostr Implementation Possibilities),
+which are community-authored specifications.
+
+## What this book covers
+
+This book is both a tutorial and the source code for the `coracle` family of Rust crates:
+
+- **coracle-lib** — Core types and stateless utilities: events, keys, tags, filters, and
+  serialization. Everything you need to understand and manipulate nostr data.
+- **coracle-net** — Networking: connecting to relays, managing subscriptions, publishing
+  events, and relay discovery.
+- **coracle-signer** — Signing abstractions: local key signing, NIP-46 remote signing,
+  and browser extension integration.
+- **coracle-content** — Content handling: parsing note text, rendering mentions, handling
+  media links, and working with NIP-27 references.
+- **coracle-storage** — Persistence: storing and querying events locally across different
+  platforms and backends.
+
+The chapters are ordered so that each concept builds on what came before. Code blocks marked
+with a file path are **tangled** — extracted and assembled into Rust source files that form the
+actual library. What you're reading *is* the source code.
+
+## How literate programming works here
+
+Throughout this book, you'll see code blocks annotated with an output file path like this:
+
+```text
+ ```rust {file=coracle-lib/src/lib.rs}
+ pub mod event;
+ ```
+```
+
+These blocks are the real source code. The `coracle-tangle` tool extracts them in document
+order and writes them to the indicated file paths. Multiple blocks targeting the same file are
+concatenated, so a struct can be introduced in one section and have methods added later in the
+narrative.
+
+Code blocks *without* a file annotation are illustrative — they show examples, intermediate
+states, or protocol concepts without contributing to the compiled output.