From d61ba8aec2057760b5e5159b7a05688d123adc8d Mon Sep 17 00:00:00 2001
From: Wong Ding Feng <dingfengwong@gmail.com>
Date: Tue, 11 Aug 2026 00:28:57 +0800
Subject: [PATCH] Add README.md and make the template workflow explicit in
 CLAUDE.md

README covers the copy-clone-rename-build flow and the simple cargo/nix
run commands. CLAUDE.md now states the intended workflow up front
(rename script, then build whatever the user actually wants) instead
of only implying it via the rename-script section.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ALEXkc7pTro7tF1WcUuKb
---
 CLAUDE.md |  8 +++++++-
 README.md | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+), 1 deletion(-)
 create mode 100644 README.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 0d93ee0..8adde68 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -8,7 +8,13 @@ A minimal Rust project template: a `clap`-based CLI (`src/main.rs`) backed by a
 (`src/lib.rs`), with unit tests, an integration test, and a `criterion` benchmark already wired
 up. It also carries a full Nix flake (crane + fenix) so the same build/test/lint pipeline runs
 identically with plain `cargo` or with `nix`. The intent is to eventually turn this into a `nix
-flake init` template — see `scripts/rename-project.sh`.
+flake init` template.
+
+**Workflow for someone starting a new project from this template:** copy/clone the repo, run
+`scripts/rename-project.sh <your_snake_case_name>` to replace the `rust_template` placeholder
+everywhere, `mv` the directory itself (the script prints the exact command), confirm with
+`nix flake check` (or `cargo test`), then build whatever you actually came here to build —
+replace `greet` in `src/lib.rs`, extend the CLI in `src/main.rs`, add real tests/benches as you go.
 
 ## Two ways to work in this repo
 
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fd8fc19
--- /dev/null
+++ b/README.md
@@ -0,0 +1,37 @@
+# rust_template
+
+A minimal Rust project template: a `clap` CLI backed by a library crate, with unit tests, an
+integration test, a `criterion` benchmark, and a Nix flake (crane + fenix) — so it builds the same
+way with plain `cargo` or with `nix`.
+
+## Using this template
+
+1. Copy/clone this repo.
+2. Rename the placeholder crate name:
+   ```bash
+   ./scripts/rename-project.sh my_project
+   cd .. && mv rust_template my_project && cd my_project
+   ```
+3. Build whatever you actually came here for — replace `greet` in `src/lib.rs`, extend the CLI in
+   `src/main.rs`, add your own tests and benchmarks.
+
+## Building and running
+
+**With Cargo** (needs Rust installed, or run inside `nix develop`):
+```bash
+cargo run -- Zeke        # build + run, prints "Hello, Zeke!"
+cargo build --release
+cargo test                 # unit + integration tests
+cargo bench                 # criterion benchmark
+```
+
+**With Nix** (no local Rust install needed):
+```bash
+nix develop              # dev shell with the pinned toolchain + tools
+nix build                 # produces ./result/bin/rust_template
+nix run -- Zeke             # build + run
+nix flake check              # clippy, fmt, doc, audit, tests — all in one go
+nix fmt                       # format Rust, Nix, and TOML files
+```
+
+See `CLAUDE.md` for more detail on the project layout and how the pieces fit together.