feat(cli): annotate PBN trees in place, and only where analysis is missing

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bridge-solver"
-version = "0.4.0"
+version = "0.5.0"
 edition = "2021"
 license = "GPL-2.0-only"
 description = "Bridge Double-Dummy Solver - Port of macroxue/bridge-solver"
@@ -43,6 +43,11 @@ name = "bench_fixtures"
 path = "examples/bench_fixtures.rs"
 required-features = ["play-analysis"]
 
+[[example]]
+name = "time_optimal_line"
+path = "examples/time_optimal_line.rs"
+required-features = ["play-analysis"]
+
 [dependencies]
 bridge-types = { git = "https://github.com/bridge-craftwork/bridge-types" }
 clap = { version = "4", features = ["derive"], optional = true }

README.md

@@ -26,3 +26,37 @@ The following are original work with no upstream counterpart:
 - `wasm/` — WebAssembly bindings and LIN parsing
 - `web/` — the browser application
 - PBN input/output, and the `bin/bridge-solver` PBN-processing binary
+
+## Annotating PBN files
+
+The `bridge-solver` binary (build with `--features cli`) fills in double-dummy
+and par analysis on PBN files, writing Bridge Composer compatible tags:
+`DoubleDummyTricks`, `OptimumResultTable`, and — when the board states its
+vulnerability — `OptimumScore` and `ParContract`.
+
+```sh
+bridge-solver -i deals.pbn                 # analyze one file to stdout
+bridge-solver -i deals.pbn -o out.pbn      # ...or to another file
+bridge-solver -w -i Curated/               # annotate a tree in place
+```
+
+Directories are searched recursively for `*.pbn`, so a build can annotate a
+whole collection in one command with no scripting around it. The pass is
+designed to be safe to run over source material:
+
+- **Only what is missing.** A board that already has a `DoubleDummyTricks` tag
+  is passed through byte-for-byte. Use `--recalculate` to redo those too.
+- **Nothing else is touched.** Files are edited line by line rather than
+  reparsed and rewritten, so `%` directives (Bridge Composer's fonts, page
+  setup and colours), `;` comments, and hand-authored `{...}` commentary all
+  survive exactly as written. Annotating a collection only ever adds lines.
+- **Incomplete deals are skipped.** Auction-only teaching boards, written as
+  `[Deal "N:... ... ... ..."]`, parse into empty hands; they are left alone
+  rather than stamped with a fabricated all-zero table.
+- **`--mark-verified`** sets bit `0x00080000` ("double-dummy data has been
+  verified") in each annotated board's `[BCFlags]`, adding the tag if absent and
+  preserving every bit already there. This records provenance only — no
+  documented BCFlags bit controls whether the DD table is *displayed*, and
+  Bridge Composer does not set this bit itself when it computes a table.
+- **Re-runs are no-ops.** Unchanged files are not rewritten, so mtimes do not
+  churn. In-place writes go through a temporary file and a rename.