diff --git a/README.md b/README.md
index ad3bece..d8d9413 100644
--- a/README.md
+++ b/README.md
@@ -7,22 +7,76 @@
 ## Quick start
 
 ```bash
-# Build everything
-cargo build
+# Install the CLI
+cargo install misses
 
-# Run a bundled example (compare .mrs source with generated Rust)
-cargo run --example make_id_type
-cargo run --example derive_builder
-cargo run --example derive_getters
-cargo run --example declare_table
-cargo run --example component
+# Scaffold a new proc-macro crate (binary mode)
+misses init my-macros
+
+# Scaffold a library-friendly crate (generated code committed, no misses required downstream)
+misses init --lib my-macros
 
 # Compile a .mrs file to Rust
-cargo run --bin misses -- path/to/my_macro.mrs > src/generated.rs
+misses path/to/my_macro.mrs > src/generated.rs
+misses path/to/my_macro.mrs src/generated.rs
 ```
 
 ---
 
+## `misses init` — project scaffolding
+
+`misses init` creates a ready-to-build proc-macro crate. Two modes are available depending on whether you're shipping a binary or a library.
+
+### Binary mode (default)
+
+```bash
+misses init my-macros
+```
+
+Use this when you control the build environment (e.g. an application binary). The `.mrs` sources are compiled to Rust at build time via `build.rs`; the generated code lives in Cargo's `$OUT_DIR` and is **never committed**.
+
+```
+my-macros/
+├── Cargo.toml            # misses as a plain [build-dependencies]
+├── build.rs              # compiles src/macros/*.mrs → $OUT_DIR/*.rs
+└── src/
+    ├── lib.rs            # include!(concat!(env!("OUT_DIR"), "/hello.rs"))
+    └── macros/
+        └── hello.mrs     # your macro source (committed)
+```
+
+Users only need `misses` installed to build from source, which is fine for an app you control.
+
+### Library mode (`--lib`)
+
+```bash
+misses init --lib my-macros
+```
+
+Use this when you're publishing a library crate. Downstream users of your crate should not be forced to install misses. The generated Rust code is committed to `generated/` and shipped on crates.io.
+
+```
+my-macros/
+├── Cargo.toml            # misses behind [features] misses-source = ["dep:misses"]
+├── build.rs              # no-op unless --features misses-source
+├── generated/
+│   └── hello.rs          # pre-generated, committed to git
+└── src/
+    ├── lib.rs            # include!(concat!(env!("CARGO_MANIFEST_DIR"), "/generated/hello.rs"))
+    └── macros/
+        └── hello.mrs     # your macro source (committed)
+```
+
+When you modify a `.mrs` file, regenerate with:
+
+```bash
+cargo build --features misses-source
+```
+
+The `misses-source` feature makes `misses` an optional build-dependency and gates regeneration in `build.rs`. Downstream users build normally with no misses dependency.
+
+---
+
 ## The `.mrs` syntax
 
 A `.mrs` file contains one or more macro definitions:
@@ -137,6 +191,16 @@ macro declare_table! {
 }
 ```
 
+Run the bundled examples to compare `.mrs` source with generated Rust:
+
+```bash
+cargo run --example make_id_type
+cargo run --example derive_builder
+cargo run --example derive_getters
+cargo run --example declare_table
+cargo run --example component
+```
+
 ---
 
 ## The `misses-rt` runtime library
@@ -194,13 +258,14 @@ let val = kv.get("name");
 
 ```
 misses/
-├── misses-compiler/       # The .mrs → Rust transpiler
+├── misses-compiler/       # The .mrs → Rust transpiler and CLI
 │   ├── src/
 │   │   ├── ast.rs         # Full AST types
 │   │   ├── parser.rs      # Hand-written recursive descent parser
 │   │   ├── codegen.rs     # AST → Rust source string
+│   │   ├── init.rs        # `misses init` scaffolding logic
 │   │   ├── lib.rs         # Library API (parse + codegen)
-│   │   └── main.rs        # CLI binary
+│   │   └── main.rs        # CLI binary (compile + init subcommands)
 │   └── examples/          # Runnable .mrs demonstrations
 │       ├── make_id_type.{mrs,rs}
 │       ├── derive_builder.{mrs,rs}
@@ -226,4 +291,6 @@ For each `.mrs` macro, the compiler generates:
 4. A `quote::quote! { … }` call whose body mirrors the `T~{}` template, with spread iterators for variadic bindings.
 5. The `quote!` result is returned as `proc_macro::TokenStream`.
 
+Parse errors are surfaced as proper Rust compiler diagnostics via `syn::Error::into_compile_error()` rather than panicking.
+
 The generated file is formatted with [prettyplease](https://github.com/dtolnay/prettyplease) for readable output.