# Coracle Nostr Monorepo

## Project Overview

This is a literate programming monorepo for building nostr applications in Rust. The source of
truth is `book/`, which contains markdown files. Code blocks annotated with `{file=path}` are
extracted ("tangled") into Rust source files by `coracle-tangle`. The `src/` directories of
library crates are generated artifacts — never edit them directly.

The project serves three goals:
1. A complete learning resource for the nostr protocol
2. A production-ready nostr utility library for Rust, KMP, and web projects
3. An experiment in literate programming as both library and LLM context

## Crates

- `coracle-lib` — Core nostr types and stateless utilities
- `coracle-net` — Relay networking
- `coracle-signer` — Signing abstractions (NIP-07, NIP-46, local key)
- `coracle-domain` — Domain-specific nostr types (profiles, follows, reactions, zaps, etc.)
- `coracle-content` — Text parsing and rendering
- `coracle-storage` — Cross-platform storage adapters
- `coracle-tangle` — The tangle/weave build tool (not a library)

## Bindings

Platform bindings are provided via separate crates, keeping the core library free of
platform-specific annotations:

- `coracle-wasm` — Web bindings via `wasm-bindgen`, producing JS-friendly types
- `coracle-ffi` — C-compatible FFI via UniFFI, consumed by KMP (Kotlin Multiplatform)

These are separate crates (not feature flags in a single crate) because they have different
dependencies, build toolchains, and API surfaces.

## Build Commands

```sh
just tangle   # Extract code from markdown into .rs files
just build    # tangle + cargo build (excludes coracle-tangle)
just check    # tangle + cargo check
just weave    # tangle + mdbook build
just clean    # Remove all generated src/ and book output
just all      # build + weave — use this to validate work
```

Always run `just all` to validate changes.

## Literate Programming Conventions

- Each chapter in `book/` corresponds to a topic (events, keys, relays, etc.)
- Code blocks with `{file=crate/src/path.rs}` annotations are tangled into source files
- Multiple blocks targeting the same file are concatenated in document order
- Code blocks without annotations are illustrative only
- 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 Materials

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 |
|-----------|----------|-------------|
| `ref/applesauce` | TypeScript | Libraries for building nostr web clients (noStrudel) |
| `ref/ndk` | TypeScript | Nostr Development Kit with framework integrations |
| `ref/nostr-gadgets` | TypeScript | High-level nostr client utilities (JSR) |
| `ref/nostr-tools` | TypeScript | Low-level nostr tools, minimal dependencies |
| `ref/rust-nostr` | Rust | Full Rust implementation with multiple crates |
| `ref/welshman` | TypeScript | Nostr toolkit extracted from the Coracle client |

## Chapter Workflow

Chapters are developed in three phases using slash commands:

1. `/research-chapter <name>` — Asks the user for a topic summary, then spawns sub-agents to
   analyze how each reference implementation handles the topic. Only reports on functionality
   relevant to the chapter. Output: `book/research/<name>.md`

2. `/plan-chapter <name>` — Reads the research file and enters interactive Q&A with the user
   to develop a detailed chapter plan. Output: `book/plan/<name>.md`

3. `/write-chapter <name>` — Reads the chapter plan and writes the actual chapter markdown
   with tangled code blocks. Validates with `just all`.

## Code Style

- Rust code should be idiomatic and well-documented
- Prefer clarity over cleverness — this is a teaching resource
- Keep dependencies minimal
- All public items need doc comments that explain the *why*
- Code must compile and pass `just all` before a chapter is considered complete