Audit-13 docs sweep: reproducibility, brew, --fresh

README.md

@@ -30,6 +30,14 @@ dlm --version
 dlm doctor
 ```
 
+> **Reproducibility caveat.** "Reproducible" in the headline means
+> *bit-exact* on Linux + CUDA with the deterministic kernel set, and
+> *best-effort* on Apple Silicon (MPS) — same seed produces stable
+> training dynamics but not bit-identical adapter weights, because
+> Metal kernels for some ops are nondeterministic. `dlm doctor` reports
+> your tier as `determinism_class: strong | best-effort | advisory`.
+> Full discussion: [docs/determinism.md](./docs/determinism.md).
+
 ### Extras
 
 ```sh

docs/troubleshooting.md

@@ -153,6 +153,22 @@ Then commit the updated goldens. If the token count is off for
 multiple dialects, investigate the Go template in
 `src/dlm/export/ollama/templates/`.
 
+## Install
+
+### `No such command 'repl'` (or `metrics`, `synth`, `serve`, etc.)
+
+**Cause:** the `dlm` on your `PATH` is older than the released binary
+— most often a third-party Homebrew tap that hasn't bumped to the
+current release. The commands `repl`, `metrics`, `templates`, `push`,
+`pull`, `serve`, `verify`, `preference`, `synth`, and `cache` were all
+added after 0.9.0.
+
+**Fix:** install from PyPI (`pip install --upgrade
+document-language-model`) or run from a checkout via `uv run dlm`.
+Confirm the version with `dlm --version`; trunk advertises 0.10.0+.
+The brew formula is community-maintained and not auto-bumped on every
+DLM release.
+
 ## Hardware / doctor
 
 ### `dlm doctor: no viable plan`

src/dlm/cli/commands.py

@@ -439,7 +439,19 @@ def train_cmd(
         ),
     ],
     resume: Annotated[bool, typer.Option("--resume", help="Resume from last checkpoint.")] = False,
-    fresh: Annotated[bool, typer.Option("--fresh", help="Discard prior adapter state.")] = False,
+    fresh: Annotated[
+        bool,
+        typer.Option(
+            "--fresh",
+            help=(
+                "Start from base weights for this run (discard the "
+                "currently-resumable training state). Prior adapter "
+                "versions in the store are kept — the next run lands "
+                "as v0002, v0003, etc. Use ``rm -rf <store>`` if you "
+                "want to wipe history entirely."
+            ),
+        ),
+    ] = False,
     seed: Annotated[int | None, typer.Option("--seed", help="Override training seed.")] = None,
     max_steps: Annotated[int | None, typer.Option("--max-steps", help="Cap step count.")] = None,
     phase: Annotated[