prep for v0.4.1: docs update

README.md

@@ -43,6 +43,44 @@ pnpm test:e2e   # Playwright end-to-end tests
 pnpm benchmark:solve
 ```
 
+## Solver Analysis CLI
+
+`pnpm benchmark:solve` is the unified batch solver-analysis command. It scans
+`dataset/public` and local `dataset/private` manifests by default, runs each
+puzzle once, and writes timestamped text and TSV analysis artifacts under
+`benchmark-results/<dataset-id>/<timestamp>/`.
+
+Target specific datasets or puzzle IDs while developing:
+
+```bash
+pnpm benchmark:solve --dataset dataset/public/masyu.json --ids masyu-20x20-8268975,masyu-25x25-988309
+```
+
+Useful options:
+
+```text
+--dataset <path>       Repeatable manifest path
+--ids <a,b,c>          Repeatable puzzle-ID filter
+--max-steps <n>        Default: 2000
+--timeout-ms <n>       Per-puzzle timeout, default: 60000
+--telemetry <level>    off | summary, default: summary
+--format <mode>        text | tsv | both | json, default: both
+--out-dir <path>       Default: benchmark-results
+```
+
+The default `both` mode prints and saves `summary.txt`, then writes
+`puzzles.tsv`, `rule-attempts.tsv`, and `strong-inference.tsv`. These long-form
+tables are intended for spreadsheets, pivot tables, and scripts. With
+`--telemetry off`, only `puzzles.tsv` is generated. JSON is reserved for
+complete debugging output and is written only when explicitly requested with
+`--format json`.
+
+Summary telemetry reports rule attempts, misses, durations, and supported
+strong-inference work. Reports also list strong-inference rules whose detailed
+telemetry interface has not been implemented, so empty Strong data is not
+mistaken for a rule that never ran. Generated artifacts have no compatibility
+guarantee.
+
 ## App Surfaces
 
 - **Solver** (`/`): import a puzzle, run one deduction at a time, jump through the replay timeline, inspect explanations and strong-inference branches, view stats, and export supported states.

dataset/public/masyu.json

@@ -498,6 +498,15 @@
       "height": 15,
       "tags": ["easy", "Medium"],
       "source": "example.txt"
+    },
+    {
+      "id": "masyu-25x25-1202688",
+      "puzzleType": "masyu",
+      "sourceUrl": "https://puzz.link/p?mashu/25/25/00k900o0j0la9a1120000000312la7b1i9036g6ii900110l303600i42102c953163101f179344169f01309119i300aa909221502f080c3f3079m20163l39f10a03p00300400163fi593j031039kj1i01600000c713b0e09190e23632f6099b040c0f999c020909p00",
+      "width": 25,
+      "height": 25,
+      "tags": ["hard", "Large"],
+      "source": "example.txt"
     }
   ]
 }

docs/PROJECT_GUIDE_EN.md

@@ -142,15 +142,45 @@ Run:
 pnpm benchmark:solve
 ```
 
-The benchmark runner scans public/private manifests, runs each puzzle with the default plugin rule order, and writes reports to `benchmark-results/<dataset-id>.report.json`.
+The unified solver-analysis runner scans public/private manifests, runs each
+puzzle once with the default plugin rule order, and writes timestamped analysis
+artifacts under `benchmark-results/<dataset-id>/<YYYYMMDD-HHmmss>/`.
 
 Default benchmark settings:
 
 - `maxSteps = 2000`
 - `timeoutMs = 60000`
 - `ruleProfile = "default"`
+- `telemetry = "summary"`
 
-Reports include per-puzzle status, step count, duration, terminal completion report, `ruleUsage`, and compact `ruleSteps`. Full `steps` are intentionally omitted to keep reports small.
+Targeted development runs can select explicit manifests and puzzle IDs:
+
+```bash
+pnpm benchmark:solve --dataset dataset/public/masyu.json --ids masyu-20x20-8268975,masyu-25x25-988309
+```
+
+CLI options:
+
+- `--dataset <path>` is repeatable; without it, public/private manifests are scanned.
+- `--ids <a,b,c>` is repeatable and filters selected manifests.
+- `--max-steps <n>` and `--timeout-ms <n>` set per-puzzle limits.
+- `--telemetry off | summary` controls observer collectors.
+- `--format text | tsv | both | json` controls generated artifacts; default
+  `both` means text plus TSV and never includes JSON.
+- `--out-dir <path>` changes the artifact output directory.
+
+The default run prints and saves `summary.txt`, plus three long-form tables:
+`puzzles.tsv` for one-row-per-puzzle outcomes, `rule-attempts.tsv` for per-rule
+cost and hit behavior, and `strong-inference.tsv` for detailed Strong work.
+When telemetry is off, only the puzzle table is generated. JSON retains the
+complete schema-v2 report for urgent debugging and is written only by explicit
+`--format json`.
+
+Rule attempt telemetry includes misses and the final no-hit scan. Strong
+inference telemetry includes explicit plugin-declared coverage, so unsupported
+collection interfaces are distinguishable from a run that produced no Strong
+events. Generated artifacts are development outputs with no compatibility
+guarantee. Full replay steps and rule-step locations are intentionally omitted.
 
 ## 8. AI Agent Quick Start
 
@@ -168,6 +198,7 @@ For targeted work:
 
 - Slitherlink rules: start at `src/domain/rules/slither/rules.ts`.
 - Masyu rules: start at `docs/MASYU_AGENT_BRIEF.md`, then inspect `src/domain/rules/masyu/rules.ts`.
+- Rule documentation: follow `docs/RULE_DOCUMENTATION_AGENT_WORKFLOW.md`.
 - Editor/UI work: inspect the relevant `src/features/*` component plus page tests.
 - Benchmark work: read `src/domain/benchmark/runner.ts` and `scripts/benchmark-solve.ts`.
 - Historical Masyu plans: check `docs/legacy/` only when old design context is useful.