cli: migrate from pico-args to clap 4.x derive API

scripts/lint-project.sh

@@ -38,15 +38,18 @@ fi
 # Rule 2: Rust source file size warning
 # Threshold set just above the current maximum (vm.rs at ~5513 lines).
 MAX_LINES=6000
+RS_FILES=$(mktemp)
+find src -name '*.rs' -not -path '*/target/*' -not -path '*/.git/*' \
+    -not -name '*.gen.rs' -not -path '*/tests/*' > "$RS_FILES"
 while IFS= read -r file; do
     lines=$(wc -l < "$file" | tr -d ' ')
     if [ "$lines" -gt "$MAX_LINES" ]; then
         echo "ERROR: $file has $lines lines (threshold: $MAX_LINES)."
         echo "  Fix: Consider splitting this file into smaller modules."
         ERRORS=$((ERRORS + 1))
     fi
-done < <(find src -name '*.rs' -not -path '*/target/*' -not -path '*/.git/*' \
-    -not -name '*.gen.rs' -not -path '*/tests/*')
+done < "$RS_FILES"
+rm -f "$RS_FILES"
 
 # Rule 3: Copyright headers on all Rust and TypeScript source files
 # check-copyright.py writes one error per line to stdout; summary to stderr.

src/simlin-cli/CLAUDE.md

@@ -7,5 +7,22 @@ For build/test/lint commands, see [docs/dev/commands.md](/docs/dev/commands.md).
 
 ## Key Files
 
-- `src/main.rs` -- CLI entry point: argument parsing, model loading, simulation, format conversion. All compilation and simulation use the incremental salsa path (`SimlinDb` + `compile_project_incremental`); the monolithic `Project::from` path is not used.
+- `src/main.rs` -- CLI entry point: clap derive-based argument parsing, model loading, simulation, format conversion. All compilation and simulation use the incremental salsa path (`SimlinDb` + `compile_project_incremental`); the monolithic `Project::from` path is not used.
 - `src/gen_stdlib.rs` -- Standard library generation utility (generates `stdlib.gen.rs` for simlin-engine)
+
+## CLI Subcommands
+
+Uses [clap](https://docs.rs/clap) derive API. Each subcommand declares exactly the arguments it accepts.
+
+| Subcommand | Description | Key flags |
+|---|---|---|
+| `simulate` | Simulate a model, print TSV results | `--no-output`, `--ltm` |
+| `convert` | Convert between XMILE, Vensim MDL, protobuf | `--to <FORMAT>`, `--model-only`, `--output` |
+| `equations` | Print model equations as LaTeX | `--output` |
+| `debug` | Compare simulation with a reference run | `--reference FILE`, `--ltm` |
+| `gen-stdlib` | Generate Rust stdlib code | `--stdlib-dir`, `--output` |
+| `vdf-dump` | Pretty-print VDF file contents | positional `PATH` |
+
+Commands that read model files (`simulate`, `convert`, `equations`, `debug`) share `InputArgs` via `#[command(flatten)]`:
+- Positional `PATH` (optional for `simulate`, reads stdin)
+- `--format <xmile|vensim|protobuf>` -- auto-detected from file extension when omitted

src/simlin-cli/Cargo.toml

@@ -10,7 +10,7 @@ name = "simlin"
 path = "src/main.rs"
 
 [dependencies]
-pico-args = "0.5"
+clap = { version = "4", features = ["derive"] }
 stringreader = "0.1"
 sha2 = "0.10"
 simlin-engine = { version = "0.1", path = "../simlin-engine", features = ["file_io"] }