add a demo mode and setup readme

Author: rossnoah

README.md

@@ -1,66 +1,79 @@
 <h1 align="center">codeburn-rs</h1>
 
-See where your AI coding tokens go but **600x faster**
+<p align="center">See where your AI coding tokens go — <b>600× faster</b></p>
 
-Benchmarked against the published JS version (`npx codeburn`) with hyperfine on MacBook Pro (M1 Pro, 16GB, 1TB).
+<p align="center">
+  <img src="demo.png" alt="codeburn dashboard screenshot" width="800">
+</p>
 
-| Rust cache state | JS              | Rust (`cburn`) | JS (`npx codeburn`) | Speedup |
-| ---------------- | --------------- | -------------- | ------------------- | ------- |
-| cached output    | cached          | 6.0 ms         | 3.66 s              | ~610×   |
-| cached sources   | cached          | 10.9 ms        | 3.66 s              | ~335×   |
-| cold (bo cache)  | cold (no cache) | 76 ms          | 7.71 s              | ~101×   |
+A Rust rewrite of [codeburn](https://github.com/AgentSeal/codeburn). Supports Claude, Codex, Opencode, Pi, and Copilot.
 
-Supported providers: Claude, Codex, Opencode, Pi, Copilot.
+## Benchmarks
+
+Measured with hyperfine on a MacBook Pro (M1 Pro, 16GB, 1TB) against `npx codeburn`.
+
+| Scenario        | `cburn` | `npx codeburn` | Speedup |
+| --------------- | ------- | -------------- | ------- |
+| Cached output   | 6.0 ms  | N/A            | ~610×   |
+| Cached sources  | 10.9 ms | 3.66 s         | ~335×   |
+| Cold (no cache) | 76 ms   | 7.71 s         | ~101×   |
 
 ## Install
 
-### Homebrew
+**Homebrew**
 
 ```sh
 brew install rossnoah/tap/cburn
 ```
 
-### Shell installer
+## Usage
+
+Launch the interactive dashboard:
 
 ```sh
-curl --proto '=https' --tlsv1.2 -LsSf https://github.com/rossnoah/codeburn-rs/releases/latest/download/cburn-installer.sh | sh
+cburn
 ```
 
-### From source
+**Shell installer**
 
 ```sh
-cargo install --git https://github.com/rossnoah/codeburn-rs
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/rossnoah/codeburn-rs/releases/latest/download/cburn-installer.sh | sh
 ```
 
-## Usage
-
-Open the interactive dashboard:
+**Install from source**
 
 ```sh
-cburn
+cargo install --git https://github.com/rossnoah/codeburn-rs
 ```
 
-### Other commands
+Other commands:
 
 ```sh
 cburn today                     # jump to today's usage
 cburn month                     # jump to this month's usage
 cburn report --period 30days    # report over a custom period
 cburn report --provider claude  # filter to a single provider
-cburn status                    # compact terminal snapshot (today + week + month)
-cburn export --format csv       # export usage data to CSV or JSON
+cburn status                    # compact snapshot (today + week + month)
+cburn export --format csv       # export usage data (csv or json)
 cburn currency GBP              # change display currency
 ```
 
-For full options, see `cburn --help` or `cburn <subcommand> --help`. The binary is named `cburn` to avoid colliding with the npm `codeburn` package — if you don't have the npm version installed and prefer the full name, alias it.
+Run `cburn --help` or `cburn <subcommand> --help` for full options.
+
+The binary is named `cburn` to avoid colliding with the npm `codeburn` package. If you don't have the npm version installed and prefer the full name, add an alias to your shell config:
+
+```sh
+echo 'alias codeburn=cburn' >> ~/.zshrc # update profile
+alias codeburn=cburn # update current shell
+```
+
+or
 
 ```sh
-alias codeburn=cburn
+echo 'alias codeburn=cburn' >> ~/.bashrc # update profile
+alias codeburn=cburn # update current shell
 ```
 
-> Cursor support is currently disabled: Cursor stopped writing per-call token
-> counts to its local `state.vscdb` in early 2026, so any parse of that DB
-> now reports $0 regardless of actual usage. The parser code is retained in
-> case the data layout is restored upstream.
+## Notes
 
-Original JS version: (https://github.com/AgentSeal/codeburn).
+> **Cursor support is currently disabled.** Cursor stopped writing per-call token counts to its local `state.vscdb` in early 2026, so parsing that DB now reports $0 regardless of actual usage. The parser code is retained in case the data layout is restored upstream.

demo.png

@@ -36,6 +36,11 @@ pub struct Cli {
     /// full parse pipeline without the output replay short-circuit.
     #[arg(long, global = true)]
     pub no_output_cache: bool,
+
+    /// Render the real usage data, but replace every project path with a
+    /// stable fake name. Useful for screenshots and demos.
+    #[arg(long, global = true)]
+    pub demo: bool,
 }
 
 #[derive(Subcommand)]

src/cli.rs

@@ -47,6 +47,7 @@ fn main() -> Result<()> {
 
     parser::set_cache_bypass(cli.no_cache);
     parser::set_output_cache_bypass(cli.no_output_cache);
+    parser::set_demo_mode(cli.demo);
 
     let command = cli.command.unwrap_or(Commands::Report {
         period: Period::Week,

src/main.rs

@@ -59,10 +59,63 @@ pub fn is_output_cache_bypassed() -> bool {
     OUTPUT_CACHE_BYPASS.load(std::sync::atomic::Ordering::Acquire)
 }
 
+/// `--demo` mode: keep the real numbers but rename every project to a
+/// stable fake string before it surfaces in the UI / export.
+static DEMO_MODE: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
+
+pub fn set_demo_mode(on: bool) {
+    DEMO_MODE.store(on, std::sync::atomic::Ordering::Release);
+}
+
+pub fn is_demo_mode() -> bool {
+    DEMO_MODE.load(std::sync::atomic::Ordering::Acquire)
+}
+
 fn unsanitize_path(dir_name: &str) -> String {
     dir_name.replace('-', "/")
 }
 
+/// Stable, plausible-looking fake project names used when `--demo` is on.
+/// The display name is `<base>-<hh>` where `base` is picked by hashing
+/// the real path against this list and `hh` is a 2-char hex disambiguator
+/// from a separate hash bit-mix. ~9000 distinct names, so collisions
+/// between real projects in one report are very rare.
+const DEMO_NAMES: &[&str] = &[
+    "atlas-engine", "nimbus-api", "phoenix-cli", "obsidian-store",
+    "emerald-runner", "comet-parser", "velvet-router", "meridian-graph",
+    "onyx-vault", "harbor-sync", "granite-cache", "copper-stream",
+    "juniper-bot", "meadow-app", "horizon-tools", "twilight-db",
+    "crystal-edge", "ember-spark", "crater-loop", "spectra-ui",
+    "voyager-task", "aurora-feed", "mosaic-grid", "tidewater-job",
+    "riverstone-svc", "lighthouse-pkg", "silverleaf-fmt", "canvas-flow",
+    "prism-codec", "summit-link", "breeze-deploy", "glacier-store",
+    "forge-runtime", "sandstone-app", "thicket-mod",
+];
+
+fn fake_project_name(real: &str) -> String {
+    use std::hash::Hasher;
+    let mut h1 = rustc_hash::FxHasher::default();
+    h1.write(real.as_bytes());
+    let n = h1.finish();
+    // Mix differently for the suffix so name-pick and suffix don't
+    // co-vary; otherwise two paths landing on the same base name would
+    // also collide on the suffix.
+    let suffix_byte = ((n.rotate_left(17) ^ 0x9E37_79B9_7F4A_7C15) & 0xFF) as u8;
+    let base = DEMO_NAMES[(n as usize) % DEMO_NAMES.len()];
+    format!("~/Code/{}-{:02x}", base, suffix_byte)
+}
+
+/// Convert a sanitized provider directory name to the path string the UI
+/// renders. Returns the real path normally; under `--demo` returns a
+/// stable fake name so screenshots don't leak local directory names.
+fn display_project_path(raw: &str) -> String {
+    let real = unsanitize_path(raw);
+    if !is_demo_mode() {
+        return real;
+    }
+    fake_project_name(&real)
+}
+
 /// Compute cache-invalidation metadata for every known source and fold
 /// the results into a single `u64` hash plus a per-path `(mtime, size)`
 /// map. The hash is the output cache's "session-files signature" — any
@@ -742,7 +795,7 @@ fn finalize_projects(
             let total_cost: f64 = sessions.iter().map(|s| s.total_cost_usd).sum();
             let total_calls: u64 = sessions.iter().map(|s| s.api_calls).sum();
             ProjectSummary {
-                project_path: unsanitize_path(&project),
+                project_path: display_project_path(&project),
                 sessions,
                 total_cost_usd: total_cost,
                 total_api_calls: total_calls,
@@ -1024,7 +1077,7 @@ fn aggregate_static_from_summary(
         .into_iter()
         .filter(|(_, a)| a.calls > 0)
         .map(|(p, a)| StaticProjectAggregate {
-            project_path: unsanitize_path(&p),
+            project_path: display_project_path(&p),
             total_cost_usd: a.cost,
             total_api_calls: a.calls,
         })

src/parser.rs

@@ -129,6 +129,14 @@ where
     let bypass = crate::parser::is_cache_bypassed();
     let output_cache_bypass = crate::parser::is_output_cache_bypassed();
 
+    // Keep demo and real outputs on separate cache entries by stealing
+    // the top bit of `extra` for the demo flag.
+    let extra = if crate::parser::is_demo_mode() {
+        extra | (1u64 << 63)
+    } else {
+        extra
+    };
+
     let (pre_stats, session_sig) = if !bypass && !output_cache_bypass {
         crate::parser::stat_all_sources()
     } else {