docs(hrr): CONFIG.md + COMMANDS.md + CHANGELOG bundle (#699, closes #553)

[robotrocketscience]

Closes #699.

Closes the #553 HRR persistence integration umbrella by landing the four-doc bundle held back from each code sub-issue.

What lands here

Four atomic commits, all docs-only — no production code change.

1. docs/CONFIG.md — adds the [retrieval] hrr_persist TOML key (default true) and the AELFRICE_HRR_PERSIST env var override under the existing ### use_hrr_structural section, plus a note in the top-of-file [retrieval] knobs summary. Documents the ephemeral-path auto-disable behaviour (/tmp/, /var/tmp/, /dev/shm/, /run/ → false unless overridden) and the resolution precedence (env > kwarg > TOML > default).

2. docs/COMMANDS.md — adds a new ## HRR persistence reporter section between Lifecycle and Help-flags, documenting the three aelf doctor rows (persist_enabled / on_disk_bytes / last_build_seconds) and the aelf status hrr.persist_state summary line. Doctor + status table cells gain a one-clause cross-reference pointing at the new section.

3. docs/feature-hrr-integration.md — checks off nine of ten acceptance criteria with PR cross-references (feat(hrr): HRRStructIndexCache persist-aware load+save+mmap (#691) #693, feat(hrr): ephemeral-path auto-disable for HRR persistence (#695) #701, feat(config): [retrieval] hrr_persist TOML key (#698) #703, feat(doctor): HRR persist/build reporter rows (#696) #704). The cold-start ≤1s gate stays unchecked: the bench-gate test code shipped via PR test(hrr): cold-start bench gate at N=50k (#697) #706, but capturing the actual numbers needs an operator run with AELFRICE_CORPUS_ROOT set; that's tracked on test(hrr): cold-start bench gate at N=50k (#553 sub-task) #697 under attn:bench-needed.

4. CHANGELOG.md — single umbrella-closure bullet at the top of v3.0.0 Added, cross-referencing the five sub-issue PRs (feat(hrr): HRRStructIndexCache persist-aware load+save+mmap (#691) #693, feat(hrr): ephemeral-path auto-disable for HRR persistence (#695) #701, feat(config): [retrieval] hrr_persist TOML key (#698) #703, feat(doctor): HRR persist/build reporter rows (#696) #704, test(hrr): cold-start bench gate at N=50k (#697) #706) and noting [v2.1] HRR integration: persistence default-ON + split-format migration + disk-cost opt-out #553 closes. The pre-existing per-sub-issue detail bullets in v3.0.0 stay intact so the granular implementation record isn't lost.

Why a separate docs PR

Per the issue body, splitting docs from the code work kept each code PR small and avoided doc churn when a sub-issue changed shape mid-flight. With all four code sub-issues now merged on github/main (#693, #701, #703, #704), the docs bundle is the umbrella's final piece.

Out of scope

• use_hrr_structural default-flip — still gated on labelled-corpus evidence per [retrieval] Pipeline composition tracker — unified retrieve() with feature-flag gate #154.
• Capturing the cold-start bench numbers — operator-side, tracked on test(hrr): cold-start bench gate at N=50k (#553 sub-task) #697.

Test plan

• pytest -q — passes (no code change; aelf-pr-open.sh runs the suite as a gate).
• release-docs-check — should pass; bundle adds a v3.0.0 CHANGELOG entry referencing all five sub-issue PRs.
• Discretion grep against github/main — clean.

Summary by CodeRabbit

• Documentation
  • Added status command alias for health diagnostics.
  • Introduced new HRR persistence configuration option with details on behavior and environment variable overrides.
  • Updated command documentation to reflect persistence-related status reporting.
  • Documented auto-disable behavior for ephemeral paths and cache invalidation processes.

[sourcery-ai]

Sorry @robotrocketscience, you have reached your weekly rate limit of 2500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR documents the HRR persistence feature across three files: docs/COMMANDS.md adds status/health alias and a new HRR persistence reporter section; docs/CONFIG.md documents the [retrieval] hrr_persist configuration key with defaults and precedence rules; docs/feature-hrr-integration.md marks related acceptance criteria as completed.

Changes

HRR Persistence Feature Documentation Bundle

Layer / File(s)	Summary
Commands documentation for HRR persistence reporter docs/COMMANDS.md	status is documented as an alias for health, and a new HRR persistence reporter section specifies the three HRR rows output by aelf doctor (hrr.persist_enabled, hrr.on_disk_bytes, hrr.last_build_seconds) and the single-line hrr.persist_state summary from aelf status with enumerated reason values.
Config documentation for hrr_persist option docs/CONFIG.md	The [retrieval] feature overview is expanded to describe placeholder flags, and a new hrr_persist configuration entry is documented with default true, persistence behavior, ephemeral-path auto-disable, and AELFRICE_HRR_PERSIST environment-variable override with precedence and operator guidance.
Feature acceptance criteria completion checklist docs/feature-hrr-integration.md	Multiple acceptance-criteria items are marked as completed, including split-format save/load, mmap-mode cache loading, aelf doctor reporter rows, NDCG verification, hrr_persist configuration disabling, ephemeral-path auto-disable with environment override, and cache invalidation; cold-start performance bench gate remains unchecked.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related issues

• [v2.1] HRR integration: persistence default-ON + split-format migration + disk-cost opt-out #553: The documentation additions directly document the HRR persistence feature, configuration keys, reporter fields, and command behaviors specified in the HRR integration epic.

Possibly related PRs

• robotrocketscience/aelfrice#556: Implements and documents HRR persistence behaviors, configuration keys, and diagnostic rows that are referenced and specified in these documentation updates.

Suggested labels

attn:review, docs

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change as a documentation bundle for HRR persistence (CONFIG.md + COMMANDS.md + CHANGELOG) with issue references, directly matching the changeset.
Description check	✅ Passed	The PR description follows the template with Summary, Linked issues, Type of change (docs), and detailed explanation of what lands; however, Verification and Test plan sections are incomplete.
Linked Issues check	✅ Passed	The PR successfully implements all documented objectives from #699: CONFIG.md added with [retrieval] hrr_persist and env var override, COMMANDS.md documented with HRR persistence reporter section and three doctor rows, feature-hrr-integration.md updated with nine acceptance criteria marked shipped with PR refs, and CHANGELOG.md bundled the five sub-issues.
Out of Scope Changes check	✅ Passed	All changes are documentation-only updates to CONFIG.md, COMMANDS.md, feature-hrr-integration.md, and CHANGELOG.md related to HRR persistence integration; no code changes or unrelated modifications present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/issue-699-hrr-integration-bundle

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

PR-size soft cap

This PR is over the advisory size threshold:

• 83 changed lines (limit: 200)
• 4 changed files (limit: 3)

Bigger PRs collide with more open work, which under the parallel-session workflow tends to produce repeated attn:merge-conflict cycles (see #602). When practical, split into smaller PRs that each touch a focused surface.

This is advisory only — nothing is blocked. If the size is intentional (large refactor, module removal, generated code), apply the size:override label and this comment will be removed on the next push.

[coderabbitai]

🧹 Nitpick comments (2)

docs/CONFIG.md (1)

334-336: ⚡ Quick win

Add language specifier to fenced code block.

The code block displaying the log message should specify a language for proper rendering.

📝 Proposed fix

-```
+```text
 aelfrice: HRR persistence disabled on ephemeral path <path>; set AELFRICE_HRR_PERSIST=1 to force.

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @docs/CONFIG.md around lines 334 - 336, The fenced code block containing the
log sample "aelfrice: HRR persistence disabled on ephemeral path ; set
AELFRICE_HRR_PERSIST=1 to force." should include a language specifier for proper
rendering; update the triple-backtick fence that surrounds that exact line to
use a language token such as text (e.g., change totext) so the snippet
is rendered correctly.

</details>

</blockquote></details>
<details>
<summary>docs/COMMANDS.md (1)</summary><blockquote>

`83-86`: _⚡ Quick win_

**Add language specifier to fenced code block.**

The code block displaying example output should specify a language for proper rendering.



<details>
<summary>📝 Proposed fix</summary>

```diff
-```
+```text
 hrr.persist_state: on <N> bytes, last build <X>s
 hrr.persist_state: off (<reason>)
 ```
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @docs/COMMANDS.md around lines 83 - 86, Update the fenced code block that
shows the hrr.persist_state output so it includes a language specifier (e.g.,
"text") after the opening to enable proper rendering; locate the block containing the lines "hrr.persist_state: on <N> bytes, last build <X>s" and "hrr.persist_state: off (<reason>)" and change the opening backticks totext.

</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In @docs/COMMANDS.md:

• Around line 83-86: Update the fenced code block that shows the
  hrr.persist_state output so it includes a language specifier (e.g., "text")
  after the opening to enable proper rendering; locate the block containing the lines "hrr.persist_state: on <N> bytes, last build <X>s" and "hrr.persist_state: off (<reason>)" and change the opening backticks totext.

In @docs/CONFIG.md:

• Around line 334-336: The fenced code block containing the log sample
  "aelfrice: HRR persistence disabled on ephemeral path ; set
  AELFRICE_HRR_PERSIST=1 to force." should include a language specifier for proper
  rendering; update the triple-backtick fence that surrounds that exact line to
  use a language token such as text (e.g., change totext) so the snippet
  is rendered correctly.

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: Path: .coderabbit.yaml

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `e35e0d72-d128-4790-9557-ba3f78889973`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 093c1e48088f2a9262bfb6e8104c0553366c7d23 and 1417172e457635ab50eeaa3dec40b4ad92f366bb.

</details>

<details>
<summary>⛔ Files ignored due to path filters (1)</summary>

* `CHANGELOG.md` is excluded by `!**/CHANGELOG.md`

</details>

<details>
<summary>📒 Files selected for processing (3)</summary>

* `docs/COMMANDS.md`
* `docs/CONFIG.md`
* `docs/feature-hrr-integration.md`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

[robotrocketscience]

[claim:review:noether:2026-05-12T04:37:06Z]

[robotrocketscience]

Review

Verified against github/main:

• All five referenced sub-PRs (feat(hrr): HRRStructIndexCache persist-aware load+save+mmap (#691) #693, feat(hrr): ephemeral-path auto-disable for HRR persistence (#695) #701, feat(config): [retrieval] hrr_persist TOML key (#698) #703, feat(doctor): HRR persist/build reporter rows (#696) #704, test(hrr): cold-start bench gate at N=50k (#697) #706) merged ✓
• aelf status actually emits hrr.persist_state line — cli.py:_format_hrr_persist_status_line invoked from the status command ✓
• aelf doctor row keys (hrr.persist_enabled, hrr.on_disk_bytes, hrr.last_build_seconds) present ✓
• Persist dir name <store_dir>/.hrr_struct_index/ matches _PERSIST_DIRNAME = ".hrr_struct_index" in hrr_index.py:414 ✓
• [retrieval] hrr_persist TOML key, AELFRICE_HRR_PERSIST env var, ephemeral-path auto-disable all wired per the doc ✓
• Honest about the cold-start bench: bullet stays unchecked, deferred to test(hrr): cold-start bench gate at N=50k (#553 sub-task) #697 with clear rationale ✓
• Discretion grep on diff: clean
• All CI green; CodeRabbit reviewed clean

One nit (non-blocking, can ship as-is or fix in a follow-up)

The two acceptance bullets that just got flipped to [x] (hrr_persist = false + ephemeral auto-disable) still reference .aelfrice/hrr/ as the persist directory:

subsequent runs show no .aelfrice/hrr/ directory created
creates no .aelfrice/hrr/ directory; … creates the directory normally

Implementation lives at <store_dir>/.hrr_struct_index/. The directory-name was wrong in the original spec text and just got carried through; not introduced by this PR. Worth a one-line follow-up if not folded in here.

Approve

Docs-only, all cross-references verified, umbrella close-out is accurate. Adding ready-to-merge.

[robotrocketscience]

[release:review:noether:2026-05-12T04:39:35Z]

[github-actions]

merge-train: merged 1417172 → main via FF push.