docs: say what the WAL fix bounds — the log's resting size, never the index (#1431)

The 1.6.0 notes said the write-ahead log is "capped", which reads as a
limit on how much can be indexed. It bounds only the log's resting size
(64 MB default, CODEGRAPH_WAL_HEAL_MB) and folds a killed session's
leftover back into the index; a large repository's log still grows in
proportion to its index while it is built. Say so in both entries, and
document the two knobs in the README's troubleshooting section.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MC52FSFLtKtDCLqT81tZYG

CHANGELOG.md

@@ -22,7 +22,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **Better answers for your agent** — `codegraph_explore` no longer repeats code it already showed you, always brings back the files and symbols you asked for by name, and spends its space on the code that actually answers the question rather than look-alikes, generated files, and type shims.
 - **Your graph stays right as you keep coding** — a long-running index no longer drifts from a fresh one, and edits to `codegraph.json` (such as `exclude`) apply immediately without a restart.
 - **No more silent crashes or hangs** — deeply nested C/C++ files, Swift Vapor projects, and large sync batches that used to kill or stall indexing now finish cleanly.
-- **A disk-space leak is fixed** — force-killed sessions could leave the database log growing to tens of gigabytes; it's now capped and cleaned up automatically.
+- **A disk-space leak is fixed** — a force-killed session could leave the database's write-ahead log behind to grow without bound (tens of gigabytes was reported); the leftover log is now folded back into the index and trimmed automatically the next time the project opens. The index itself has no size limit.
 - **Works from a workspace or monorepo root** — the MCP server finds your indexed project when launched from a folder above it, and says so clearly when it can't find one.
 - **More accurate code graphs** for TypeScript, Rust, Erlang, C/C++, and Python projects — see the full list below.
 - **Also new**: per-project Codex setup (`codegraph install --location=local`), a `deprioritize` setting to keep helper folders from outranking your real code, the `codegraph context` command, and usage stats that now stay entirely on CodeGraph's own servers.
@@ -115,7 +115,7 @@ After upgrading, run `codegraph index` once in each project so your existing gra
 
 - Fixed a v1.5.0 regression where a perfectly valid file could be permanently recorded as having 0 symbols, with no error reported. When a file's first parse attempt was interrupted — a parsing worker crash or timeout, most likely on slow or heavily loaded machines — the automatic retry stored an empty result for any language on the native extraction path, so the file's functions and classes silently vanished from search, callers, and impact until the file was next edited. Retries now store the file's real symbols, and a file already recorded as symbol-free is detected and repaired automatically by the next sync or re-index after upgrading. Thanks @Baiae for the report. (#1541)
 
-- A CodeGraph process that gets force-killed — by the stuck-process watchdog, a crash, or the OS — no longer leaves the database's write-ahead log behind to grow without bound. Previously each killed session stacked more data onto the same log file and nothing ever shrank it, which on machines where sessions were killed regularly could quietly eat tens of gigabytes of disk. The log is now capped, and any oversized leftover is reclaimed automatically the next time the project is opened. Thanks @tiendungdev for the exceptional Windows report that pinned this down. (#1431)
+- A CodeGraph process that gets force-killed — by the stuck-process watchdog, a crash, or the OS — no longer leaves the database's write-ahead log behind to grow without bound. Previously each killed session stacked more data onto the same log file and nothing ever shrank it, which on machines where sessions were killed regularly could quietly eat tens of gigabytes of disk. The log's resting size is now bounded (64 MB by default; `CODEGRAPH_WAL_HEAL_MB` changes it), and any oversized leftover is folded back into the index and trimmed automatically the next time the project is opened. This bounds only the log — the index itself has no size limit, and a large repository's log is still allowed to grow in proportion to its index while it is being built. Thanks @tiendungdev for the exceptional Windows report that pinned this down. (#1431)
 
 - The background server's watchdog no longer kills a healthy server that is just waiting on a slow disk: like indexing already does, it now checks whether the database files are still making progress before concluding the process is stuck. Fewer spurious kills also means fewer leftover write-ahead logs. (#1431)
 

README.md

@@ -876,6 +876,8 @@ Framework routing is validated the same way, on a canonical app per framework: E
 
 **Sharing one checkout between Windows and WSL** — Don't point both at the same `.codegraph/`: the background-server lock and the SQLite index are tied to the OS that wrote them, and SQLite locking across the WSL2/Windows filesystem boundary is unreliable. Give each side its own index in the same tree by setting `CODEGRAPH_DIR` to a distinct name on one of them — e.g. `CODEGRAPH_DIR=.codegraph-win` on Windows, leaving WSL on the default `.codegraph`. CodeGraph skips any sibling `.codegraph-*` directory when indexing and watching, so the two never trip over each other.
 
+**Very large repositories (hundreds of thousands of files), or a large `.codegraph/codegraph.db-wal` file** — The `-wal` file is SQLite's write-ahead log: writes waiting to be folded into `codegraph.db`. While a big index is being built, CodeGraph lets it grow in proportion to the index (soft threshold = the larger of 256 MB and a quarter of the index size, up to 2 GB) before folding it back, because folding too often is what made large indexes slow on ordinary disks. At rest it is trimmed to 64 MB, and a leftover from a killed session is folded and trimmed the next time the project opens — the index itself has no size limit. Two environment variables tune this: `CODEGRAPH_WAL_VALVE_MB` (the soft threshold during indexing) and `CODEGRAPH_WAL_HEAL_MB` (the resting size and the trim threshold). `CODEGRAPH_WAL_VALVE_DEBUG=1` prints every decision to stderr.
+
 ## License
 
 MIT