fix: better handling of dev brain

docs/USER_GUIDE.md

@@ -98,16 +98,16 @@ To set it up:
 
 Useful requests include “Build Dev Brain for these projects,” “Refresh Dev
 Brain after my recent changes,” “What does Dev Brain know about the cache
-invariants?”, and “Check the wiki, then verify this against the source.” Search
-and reads use a disposable local SQLite full-text index. The index checks vault
-files and cited project evidence before use, so no separate indexing service or
-manual refresh button is needed.
+invariants?”, and “Check the wiki, then verify this against the source.” The
+agent gets the real vault folder from Dev Brain, then uses its normal list,
+read, search, write, and edit tools on the Markdown. A dedicated validation tool
+checks the result and refreshes the disposable local SQLite search index.
 
 The vault remains ordinary Obsidian Markdown:
 
 - **purpose.md** records its scope, priorities, and recurring questions.
 - **schema.md** is the detailed contract the agent follows when maintaining it.
-- **index.md** catalogs every managed topic page.
+- **index.md** is a generated catalog of every managed topic page.
 - **log.md** is an append-only history of material updates.
 - Topic pages live under **projects/**, **subsystems/**, **concepts/**,
   **decisions/**, **invariants/**, and **workflows/** as needed.
@@ -115,17 +115,20 @@ The vault remains ordinary Obsidian Markdown:
 Every topic cites exact project files and a Git revision or content hash.
 **Verified** pages may support answers. **Stale** pages are navigation leads
 whose evidence changed, and **needs-review** pages contain visible uncertainty;
-the agent must recheck project sources before relying on either. Wiki updates
-are validated as a complete batch before publication, so a broken link,
-out-of-bounds path, invalid citation, or stale verified claim leaves the last
-valid wiki untouched.
+the agent must recheck project sources before relying on either. After editing,
+the agent runs validation. Unsafe paths and invalid page structure or provenance
+are errors to repair in place. Broken links are reported as warnings: the valid
+page stays on disk, so the agent can make a small edit or create the missing
+page without regenerating its work. Validation rebuilds **index.md**
+deterministically instead of asking the model to keep it synchronized.
 
 DS4Server may modify only the four contract files and topic pages explicitly
-marked as Dev Brain-managed. It does not modify Obsidian settings, attachments,
-trash, hidden files, or unrelated notes. You can inspect, edit, link, and
-version the managed Markdown normally; invalid manual edits are reported rather
-than silently trusted. Disabling Dev Brain removes its tools and instructions
-from the built-in coding agent without deleting the vault.
+marked as Dev Brain-managed. Standard agent file tools can access the vault but
+cannot modify Obsidian settings, hidden files, or unrelated notes. You can
+inspect, edit, link, and version the managed Markdown normally; invalid manual
+edits are reported rather than silently trusted. Disabling Dev Brain removes its
+folder, search, and validation guidance from the built-in coding agent without
+deleting the vault.
 
 ## Views and sidebar