blender-knowledge-refresh

Run the [release refresh](../../../docs/maintenance/knowledge.md#release-refresh) for the next version. Read `AGENTS.md` and `docs/maintenance/knowledge.md` first. Run it once the version's scope is settled, as the only refresh in progress. This command opens one PR; it never merges it or the release PR. ## Prepare Match PRs by head branch, never by text search: release notes and PR bodies mention refresh commits too. 1. Find the next version from the title of the open PR whose head branch starts with `release-please--` (`gh pr list --state open --json number,title,headRefName`). If none is open, ask. 2. In the same list, look for a head branch starting with `docs/knowledge-refresh-`. If one exists, stop and report it. 3. `git fetch origin main`, then create `docs/knowledge-refresh-<version>` from `origin/main` in a separate worktree. Record `origin/main`'s full SHA: it is the `reviewed_revision` for every record you refresh. 4. Run `uv run --locked --no-env-file python tools/check_knowledge.py --base origin/main --json` and keep its `drift` list. Stop if it reports errors that this refresh did not cause. ## Review each drifted document Documents are independent. You may split them among helpers, one document each; give each helper this section and collect its edits. 1. Read `git diff <reviewed_revision>..<main SHA> -- <sources>` with the drift entry's `sources`, and the document. Paths also in `removed` were deleted. 2. Correct only what the changes made wrong, following "Keep it short" below. The user guide stays short, plain-language help with no internal terms or test results. 3. Update the record: add newly relevant sources, drop removed or irrelevant ones, keep the list sorted. Set `reviewed_revision` to the main SHA and `reviewed_at` to today's UTC date. Rewrite `limits` as the current boundaries in at most 60 words, with no dates or re-check history. Change `coverage` only when you reviewed the claims it covers. 4. If you cannot review a document properly, leave its record unchanged and list it as still drifted. ## Keep it short The refresh exists to keep documents accurate, not to record that it happened. A refresh that makes documents longer has failed unless new behavior needs it. - Replace or delete wrong sentences; do not append corrections, notes or "as of" paragraphs next to them. - Describe current behavior only. Never add dates, PR or issue numbers for history, test runs, platforms checked, "re-checked" or "verified" remarks. Those belong in the PR body, and only briefly. - Delete text that repeats another guide; link to the guide that owns it. - Do not restate what code or tests say line by line; name the behavior and link the source file. - One fact once: if two paragraphs say the same thing, keep the clearer one. - No new sections unless a new feature has no home; then add the fewest lines that describe it. Before publishing, run `git diff --stat origin/main` and check the Markdown line counts. Each refreshed document should shrink or stay the same size. If one grows, cut it again, or name the new behavior that needs the extra lines in the PR body. ## Validate and publish 1. Run `make knowledge`, `make lint` when Python changed, and `uv run --locked --no-env-file python -m pytest tests/unit/test_knowledge.py`. The checker must report no drift for the documents you refreshed. 2. Commit with `docs(docs): refresh documentation for <version>` and open the PR against `main` with the repository template. Keep the body short: the main SHA reviewed, a table of refreshed documents with their line change, and the documents still drifted with one-line reasons. No per-document narratives. 3. Report the PR URL. Do not merge it.