docs(config): add [rebuilder] section to CONFIG.md (#720)

[robotrocketscience]

Closes #720.

Summary

Adds [rebuilder] and [rebuild_floor] reference sections to docs/CONFIG.md. The doc gap was surfaced during review of PR #719 (#718 flip): the operator-tunable knobs query_strategy (just defaulted to stack-r1-r3 for v3.0), floor_session, and floor_l1 had no entry in the user-facing config reference.

Diff

Two atomic SSH-signed commits:

1. docs(config): document [rebuilder] section in CONFIG.md (#720) — adds the schema-block entries and prose-block subsections for [rebuilder] query_strategy, [rebuild_floor] session, and [rebuild_floor] l1. Also amends the introductory list on line 12 of CONFIG.md so [rebuilder] is named alongside [noise] and [retrieval].
2. docs(changelog): #720 CONFIG.md [rebuilder] section entry under v3.0.0 — entry under ### Documentation in ## [3.0.0] - Unreleased.

Touched files: docs/CONFIG.md (+50), CHANGELOG.md (+4). No code changes, no test changes.

Verification

• git log --format='%h %G? %s' github/main..HEAD — both commits signed (G).
• Discretion grep on the diff: empty.
• Branch is FF on github/main (rebased before PR open).
• No new tests required (docs-only).

Correction note

The original #720 body listed the floor knobs as [rebuilder] floor_session / floor_l1 defaulting to 0.0. Verifying against src/aelfrice/context_rebuilder.py during implementation revealed they actually live under [rebuild_floor] (keys session / l1) with defaults 0.10 / 0.40 — the 0.0 in the issue body was the function-signature default on rebuild_v14, not the operator-facing RebuilderConfig default. The PR documents what load_rebuilder_config actually parses. Correction left in the issue thread for the trail.

Summary by Sourcery

Document the existing [rebuilder] and [rebuild_floor] configuration sections and reference them in the changelog for the upcoming 3.0.0 release.

Documentation:

• Expand docs/CONFIG.md to describe the [rebuilder] query strategy options and [rebuild_floor] token-budget floors, including defaults and fail-soft behaviour.
• Update the introductory config section list to mention the [rebuilder] TOML section alongside existing sections.
• Add a 3.0.0 changelog entry noting the new [rebuilder] and [rebuild_floor] documentation coverage.

Summary by CodeRabbit

• Documentation
  • Added docs for optional context-rebuilding configuration: query strategy selection (default: stack-r1-r3), a legacy "legacy-bm25" escape hatch, and token-budget floor controls for sessions and L1 contexts. Clarified default behavior and graceful fallback when values are malformed, and added standalone sections for these settings alongside existing noise/retrieval docs.

[sourcery-ai]

Reviewer's Guide

Documents the previously undocumented [rebuilder] and [rebuild_floor] TOML configuration sections in docs/CONFIG.md, including the query_strategy selector and token-budget floor knobs, and adds a corresponding documentation entry to the v3.0.0 section of CHANGELOG.md.

File-Level Changes

Change	Details	Files
Extend CONFIG reference to cover [rebuilder] and [rebuild_floor] configuration sections and their behavior.	Add [rebuilder] to the top-level list of documented config sections alongside [noise] and [retrieval]. Introduce a new [rebuilder] schema block with the query_strategy key and inline comments describing default (stack-r1-r3), legacy (legacy-bm25) behavior, and deprecation plan. Introduce a new [rebuild_floor] schema block with session and l1 numeric floor keys, including defaults, semantics, and fail-soft behavior on malformed values. Add a new prose section ## [rebuilder] and [rebuild_floor] (v1.7+) detailing allowed values, defaults, effects, failure-handling, and log semantics for query_strategy, session, and l1. Clarify that malformed or out-of-range values for these sections fall back to documented defaults with stderr tracing rather than raising.	docs/CONFIG.md
Record the new configuration documentation in the unreleased v3.0.0 changelog.	Add a ### Documentation subsection under ## [3.0.0] - Unreleased. Document the addition of [rebuilder] and [rebuild_floor] sections in docs/CONFIG.md, including their purpose, defaults, escape hatch, and fail-soft behavior. Note that the CONFIG intro was updated to list [rebuilder] alongside the existing sections.	CHANGELOG.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#720	Add a [rebuilder] section to docs/CONFIG.md documenting the query_strategy knob and the rebuild-floor knobs (session and L1) with their current defaults and behavior, referencing the query-understanding contract and fail-soft behavior on malformed config.	✅
#720	Ensure the new documentation sections follow the prose conventions of existing config blocks (e.g., [retrieval]), including version tagging, default values, and appropriate behavioral notes.	✅
#720	Add a CHANGELOG entry under the unreleased v3.0.0 section describing the addition of the [rebuilder] (and associated rebuild-floor) documentation to docs/CONFIG.md, with no code or test changes.	✅

Possibly linked issues

• docs(config): add [rebuilder] section to CONFIG.md (query_strategy + rebuild-floor knobs) #720: They are the same task: add [rebuilder]/[rebuild_floor] config documentation and related CHANGELOG entry as described.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c1e0875a-2bcf-431f-a540-e54f4170a143

📥 Commits

Reviewing files that changed from the base of the PR and between 01f5489 and aaed314.

⛔ Files ignored due to path filters (1)

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

📒 Files selected for processing (1)

• docs/CONFIG.md

---

📝 Walkthrough

Walkthrough

docs/CONFIG.md now documents the [rebuilder] TOML configuration table (v1.7+) with query_strategy selection and [rebuild_floor] token-budget floor settings (session and l1), covering defaults, the legacy-bm25 escape hatch, and stderr-trace fallback behavior for malformed values.

Changes

Rebuilder configuration documentation

Layer / File(s)	Summary
Rebuilder TOML configuration documentation docs/CONFIG.md	Overview, schema example, and detailed keys documentation for [rebuilder] with query_strategy (stack-r1-r3 default and legacy-bm25 escape hatch) and [rebuild_floor] with session and l1 token-budget floor thresholds. Includes malformed-value fallback behavior (stderr trace, no exception).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related issues

• #718 — Documents the query_strategy default flip and rebuilder knobs; this PR adds the [rebuilder] and [rebuild_floor] docs referenced by that issue.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: documenting the [rebuilder] section in CONFIG.md with issue reference #720.
Description check	✅ Passed	The description includes summary, linked issues, type of change (docs), verification steps, and detailed implementation notes covering the two commits and corrections.
Linked Issues check	✅ Passed	The PR fully addresses issue #720 by documenting [rebuilder] query_strategy, [rebuild_floor] session/l1 knobs with defaults, and adding CHANGELOG entry as required.
Out of Scope Changes check	✅ Passed	All changes are in-scope: docs/CONFIG.md documentation of [rebuilder] and [rebuild_floor] sections, and CHANGELOG.md entry. No extraneous code or test changes 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-720-config-rebuilder-section

---

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.}

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[robotrocketscience]

[claim:review:Schwarzchild:2026-05-12T19:57:52Z]

[robotrocketscience]

Review — Schwarzchild

Docs-only PR closing #720. Adds the missing [rebuilder] / [rebuild_floor] reference sections to docs/CONFIG.md and a CHANGELOG entry under [3.0.0] - Unreleased § Documentation.

Verification

• [rebuild_floor] session = 0.10 and l1 = 0.40 defaults match the source-of-truth constants in src/aelfrice/context_rebuilder.py:153 (DEFAULT_FLOOR_SESSION) and :160 (DEFAULT_FLOOR_L1).
• query_strategy = "stack-r1-r3" matches DEFAULT_STRATEGY post-feat(retrieval): flip query_strategy default legacy-bm25 → stack-r1-r3 (#291 PR-3) #718. Note: this PR presupposes PR feat(retrieval): flip query_strategy default legacy-bm25 → stack-r1-r3 (#718) #719 (default flip) has landed — body says "default stack-r1-r3 since v3.0". If feat(retrieval): flip query_strategy default legacy-bm25 → stack-r1-r3 (#718) #719 slips, this entry's tense is wrong.
• Intro paragraph on line 12 correctly extends the [noise] / [retrieval] enumeration to include [rebuilder].
• The fail-soft "malformed value → field default + stderr trace" contract is documented and matches the existing _resolve_* helpers.

Discretion grep

Clean.

Verdict

LGTM. Docs-only, no code paths touched, no test changes required. Add ready-to-merge once #719 (the PR this doc references) is also queued, or merge as-is and accept the brief tense lead-time.

[robotrocketscience]

[release:review:Schwarzchild:2026-05-12T19:58:31Z]

[robotrocketscience]

[claim:review:schwartzchild:2026-05-12T22:45:40Z]

[robotrocketscience]

LGTM. Both commits signed, FF on main, CI green, no unresolved threads, discretion-clean. Docs match the source on the key facts I spot-checked:

• DEFAULT_FLOOR_SESSION = 0.10 and DEFAULT_FLOOR_L1 = 0.40 in src/aelfrice/context_rebuilder.py:153,160 — matches.
• [rebuild_floor] is the actual config section name (REBUILD_FLOOR_SECTION = "rebuild_floor" at line 149) — matches. Good catch on the issue-body correction; the 0.0 in docs(config): add [rebuilder] section to CONFIG.md (query_strategy + rebuild-floor knobs) #720 was the rebuild_v14 signature default, not the RebuilderConfig default.

One sequencing nit, non-blocking. The doc and CHANGELOG both state query_strategy = "stack-r1-r3" is the default "since v3.0". On github/main right now (src/aelfrice/query_understanding/strategy.py:41), DEFAULT_STRATEGY = LEGACY_STRATEGY = "legacy-bm25". The flip is PR #719 (still OPEN). If #722 lands before #719, the docs document a future state for the v3.0-Unreleased window. That's fine because v3.0 isn't out yet — internal-dev divergence resolves itself when #719 merges. Worth noting so operators reading current main don't get tripped up; explicitly referencing PR #719 in the entry mitigates it. If #719 stalls, this entry needs an edit before tagging v3.0.

Approving + adding ready-to-merge.

[robotrocketscience]

[release:review:schwartzchild:2026-05-12T22:47:32Z]

[github-actions]

merge-train: blocked

branch is not fast-forward on main (branch base 1098c33ce205090c2d91d624d4794fd5fadf36ab, current main c793a5d2dbce34e40a45987101a557fc1aa34940). Rebase locally (git rebase github/main), force-push, and re-add the label.

The ready-to-merge label has been removed. Address the issue above and re-add the label when you're ready for another attempt.

[github-actions]

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