From a31c92047fedc2ffa2727aa19928c8e7c55895bd Mon Sep 17 00:00:00 2001 From: Rahul Rajaram Date: Thu, 26 Mar 2026 23:24:26 -0400 Subject: [PATCH] docs: add health/paths/--use-relations to README, backfill CHANGELOG NXT-035: Document yore health, yore paths, and assemble --use-relations in the README command reference (sections 7.25, 7.26, and updated 7.5). NXT-040: Backfill CHANGELOG entries for v0.5.0 (MCP stdio server) and v0.6.0 (query text in JSON output). Add v0.7.0 eval metrics entries. --- CHANGELOG.md | 21 ++++++++++++++++++ README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 80 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 453e163..659aed5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,27 @@ `--depth`, `--kind` filter, and `--json` output. - Add `--use-relations` flag to `assemble` for graph-aware cross-reference expansion from persisted relation edges. +- Add ranked retrieval metrics to `yore eval`: precision@k, recall@k, + MRR, and nDCG@k over initial BM25 retrieval ranking. +- Add `--k` flag to `eval` for configurable k values (default: 5,10). +- Add `relevant_docs` field to eval JSONL format for per-question + relevance judgments (backward compatible). +- Fix `found`/`missing` in eval JSON output to match against the + assembled digest instead of the query text. + +## 0.6.0 +- Add `query` field to each result object in `--json` output so callers + can correlate results with the query that produced them. +- Add `query` field to the top-level `--explain --json` wrapper alongside + `results` and `diagnostics`. + +## 0.5.0 +- Add bounded MCP retrieval flow with `yore mcp search-context` and + `yore mcp fetch-context` for preview-first, explicit expansion. +- Add `yore mcp serve` to expose the bounded contract over MCP stdio + for editor and agent clients. +- Harden MCP behavior with cwd-independent source resolution, read-only-safe + handle storage fallback, and explicit truncation metadata. ## 0.4.0 - Add missing command coverage in the help and README command reference (`similar`, `diff`, `stats`, `repl`, `policy`) for full CLI parity. diff --git a/README.md b/README.md index 4e5386a..3843d3e 100644 --- a/README.md +++ b/README.md @@ -424,6 +424,7 @@ yore assemble --index * `--format, -f` – Output format (`markdown` is the default) * `--doc-terms` – Show top N distinctive terms per source document (0 disables) * `--from-files` – Assemble from explicit files instead of a query (supports `@list.txt`) +* `--use-relations` – Use the persisted relation graph (`relations.json`) for cross‑reference expansion instead of on‑the‑fly link scanning **Example** @@ -435,7 +436,9 @@ yore assemble "How does the authentication system work?" \ # Assemble from explicit files yore assemble --from-files docs/adr/ADR-0010.md docs/adr/ADR-0011.md --index docs/.index -yore assemble --from-files @file-list.txt --index docs/.index + +# Use relation graph for smarter cross-reference expansion +yore assemble "deployment process" --use-relations --index docs/.index ``` --- @@ -1157,6 +1160,61 @@ yore policy --config --index yore policy --config .yore-policy.yaml --index docs/.index --json ``` +### 7.25 `yore health` + +Detect structural document‑health issues from build‑time metrics. + +```bash +yore health [FILE] --index +yore health --all --index +``` + +Uses persisted document and section metrics emitted by `yore build` to flag oversized docs, accumulator‑style section growth, stale completed sections, and changelog sprawl. + +**Key options** + +* `FILE` – Specific file to inspect (omit for `--all`) +* `--all` – Evaluate every indexed document +* `--max-lines` – Line count threshold for bloated files (default: 500) +* `--max-part-sections` – Maximum "Part N" headings before accumulator risk (default: 8) +* `--max-completed-lines` – Maximum retained lines in completion‑marked sections (default: 50) +* `--max-changelog-entries` – Maximum changelog list items (default: 15) +* `--json` – Emit JSON output + +**Examples** + +```bash +yore health docs/plan.md --index .yore +yore health --all --index .yore --json +``` + +--- + +### 7.26 `yore paths` + +Show relation paths between documents via the persisted relation graph. + +```bash +yore paths --index +``` + +Displays how a source document connects to other documents through links, section links, and ADR references. Requires `relations.json` from `yore build`. + +**Key options** + +* `` – Source file to show paths from +* `--depth, -d` – Traversal depth (1 = direct edges, 2 = two hops; default: 1) +* `--kind` – Filter by edge kind: `links_to`, `section_links_to`, `adr_reference` +* `--json` – Emit JSON output + +**Examples** + +```bash +yore paths docs/architecture.md --index .yore +yore paths docs/architecture.md --depth 2 --json --index .yore +yore paths docs/architecture.md --kind links_to --index .yore +``` + --- ## 8. Configuration and Profiles