docs: refresh user-facing docs for the features shipped since 0.8.0

Documentation had drifted behind the post-0.8.0 work. Adds a CHANGELOG [Unreleased] section, documents the three new feature flags in the config reference (and removes the retired ROBOCO_RAG_USE_HYDE), a new Architectural Conventions Standard page, the provider-overload break in CLAUDE.md, the >=3.13 Python floor + feature flags in the README, and the toolchain/conventions delivery gates + structured-note model across the developer / QA / PR-reviewer role docs and the task-model doc.

docs/rag/architecture/config-reference.md

@@ -48,7 +48,6 @@ Environment variables for RoboCo (prefix: `ROBOCO_`).
 | `ROBOCO_RAG_CHUNK_SIZE_DOCS` | `1536` | Chunk size for docs |
 | `ROBOCO_RAG_CHUNK_SIZE_JOURNALS` | `1024` | Chunk size for journals |
 | `ROBOCO_RAG_CHUNK_OVERLAP` | `128` | Chunk overlap |
-| `ROBOCO_RAG_USE_HYDE` | `true` | Use HyDE for queries |
 | `ROBOCO_RAG_USE_HYBRID_SEARCH` | `true` | BM25 + vector search |
 | `ROBOCO_RAG_USE_CROSS_ENCODER` | `true` | Neural reranking |
 | `ROBOCO_RAG_AUTO_UPDATE_ENABLED` | `true` | Auto-update indexes |
@@ -75,6 +74,18 @@ Agents whose provider is `GROK` run xAI's official `grok` CLI. Auth is the host
 | `ROBOCO_GROK_IDLE_KILL_SECONDS` | `900` | Kill + evict a Grok container that has been ACTIVE-yet-idle (no gateway verb) this long |
 | `ROBOCO_GROK_MAX_COST_USD` | `0.0` | Per-agent Grok cost ceiling (USD); `0` disables |
 
+## Feature flags
+
+Env-gated subsystems, default-off except the overload break. Each takes effect on the next backend restart; the panel's Settings → Feature Flags card toggles them without hand-editing env.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ROBOCO_CONVENTIONS_ENABLED` | `false` | Architectural Conventions Standard: auto-scaffold `.roboco/conventions.yml`, inject the architecture map, attach baseline constraints, and block `i_am_done` / `pr_pass` on block-level placement and hygiene violations. Off = fully inert. |
+| `ROBOCO_TOOLCHAIN_MATCH_ENABLED` | `false` | Provision each agent workspace with the target project's Python (resolved from its `requires-python` / `.python-version`) and block delivery gates when the suite cannot be executed under it. Off = today's behavior. |
+| `ROBOCO_OVERLOAD_BREAK_ENABLED` | `true` | Park a provider on a persistent model-API overload (HTTP 529 / 500 / 503) the same way a 429 is parked — queue its spawns and probe until it recovers — instead of crash-retrying into the overload. Off = crash-retry behavior. |
+
+The company-in-a-box subsystems toggle the same way and are all default-off: web research (`ROBOCO_RESEARCH_ENABLED`), the strategy engine (`ROBOCO_STRATEGY_ENGINE_ENABLED`), and pitch provisioning (`ROBOCO_PROVISIONING_ENABLED`).
+
 ## Self-Healing CI loop
 
 RoboCo watching its own repo's CI. All default-off / dormant.

docs/rag/architecture/task-model.md

@@ -63,6 +63,12 @@ When a parent task is decomposed, each subtask declares which parent criteria it
 | `dev_notes` | Developer notes |
 | `qa_notes` | QA feedback |
 
+### Structured notes & toolchain marker
+
+Each role's handoff note is stored as a validated structured model in `notes_structured`. The legacy text columns (`dev_notes`, `qa_notes`, `doc_notes`, `pr_reviewer_notes`, `quick_context`) are DERIVED mirrors regenerated from it through a single chokepoint — never hand-authored.
+
+When toolchain matching is enabled, the agent's workspace clone carries a `.git/.roboco-toolchain` marker recording the resolved Python and a status (`ok` / `broken` / `unknown`), and the WorkSession records the toolchain columns. A `broken` status blocks the delivery gates.
+
 ## Timestamps
 
 | Field | Description |

docs/rag/roles/developer.md

@@ -80,6 +80,12 @@ There is **no** `roboco_git_commit / _push / _create_pr / _merge_pr / _checkout`
 5. **Reflect:** `note(text="...", scope="reflect")` on what changed and why — useful for QA's diff review.
 6. `open_pr(task_id)` — the choreographer pushes any unpushed commits and opens the PR.
 
+## Delivery gates
+
+When toolchain matching is enabled, `i_am_done` is refused if the project's test suite cannot be collected under the interpreter the workspace was provisioned with (a "broken" toolchain). The fix is to call `i_am_blocked(reason='toolchain')` so the environment is rebuilt — never to pass on a source read.
+
+When the architectural-conventions standard is enabled, `i_am_done` is refused on any block-level convention finding (e.g. a model defined in a router), reported with the offending `file:line` and a fix hint. A genuine false positive is cleared by committing a waiver in `.roboco/conventions.yml`.
+
 ## A2A Collaboration
 
 ```python

docs/rag/roles/pr-reviewer.md

@@ -19,6 +19,10 @@ The org's own in-flight integration PRs are skipped by the **inbound** poll abov
 
 The `pr_reviewer` role also runs the **in-path gate** on the org's OWN assembled delivery PRs — the merge-level review QA does not do. When a cell PM bubbles up its cell→root PR (`submit_up`) or the Main PM opens the root→master PR (`submit_root`), the task enters `awaiting_pr_review`. The cell reviewer (be/fe/ux-pr-reviewer) reviews its cell's assembled PR; pr-reviewer-1 reviews the root→master PR for the cross-cell integration seam (the bug class that lives where the FE and BE meet). Workflow: `claim_gate_review(task_id)` → review the assembled diff against the parent objective + every acceptance criterion + the FE↔BE contract → `note(scope="learning", ...)` → `pr_pass(task_id, notes)` (moves it on to the PM merge) or `pr_fail(task_id, issues)` (sends it back to `needs_revision`, like a QA fail). Either verdict is also posted on the assembled PR itself as a GitHub review (server-side, via the bot account) so the decision is visible on the PR the PM merges: `pr_pass` posts an APPROVE and `pr_fail` a REQUEST_CHANGES — except on the root→master PR, which only ever gets a plain COMMENT because only the CEO acts on `master`. This gate gives the merge level the reject teeth the PM otherwise lacks. Leaf dev tasks and branchless coordination roots skip the gate.
 
+### Gate enforcement
+
+When the architectural-conventions standard is enabled, `pr_pass` is refused on any block-level convention finding, the same way the developer's `i_am_done` is. When toolchain matching is enabled, `pr_pass` is likewise refused on a "broken" toolchain status. Your verdict note is a mandatory structured field (`pr_reviewer_notes`) written at `pr_pass` / `pr_fail`; it is persisted structured with a derived text mirror.
+
 ## What You CAN Do
 
 - Pull an inbound-PR review task via `give_me_work()` and claim it via `claim_pr_review(task_id)`.

docs/rag/roles/qa.md

@@ -83,6 +83,12 @@ pass(
 
 `notes` must be substantive — the enforcement layer rejects empty or near-empty notes. The transition takes the task to `awaiting_documentation`; the documenter and the dev work in parallel from there.
 
+Your pass/fail note is a mandatory structured note (a QaNote) carrying substantive findings, not an empty string. It is persisted structured, and the legacy `qa_notes` text column is derived from it.
+
+## Conventions in Review Evidence
+
+When the architectural-conventions standard is enabled, the evidence returned on `claim_review` includes `convention_findings` for the work under review — surface them in your verdict alongside the acceptance-criteria check.
+
 ## Failing QA
 
 ```python

docs/rag/standards/conventions.md

@@ -0,0 +1,73 @@
+# Architectural Conventions Standard
+
+A per-project, repo-canonical standard for *where code lives* and basic house-style hygiene — the layer above the `make`-style gates (which check syntax, types, and tests, not placement). It exists so an agent cannot land a model defined inside a router, a helper in a route file, or a lint suppression, even when the code compiles and the tests pass.
+
+The standard is gated by `ROBOCO_CONVENTIONS_ENABLED` (default off) and is fully inert when off.
+
+## How a project declares it
+
+Each project carries a repo-canonical `.roboco/conventions.yml`. It is auto-scaffolded into a project's clone the first time the project is worked on, editable from the per-project **Conventions** tab in the panel, and committed like any other repo file.
+
+Consumers always read the *effective* map: auto-derived defaults (from a repo scan plus the built-in rules) overlaid by the committed file. Behaviour is identical whether the file is present, absent, or partial — a missing file just means "defaults only".
+
+```yaml
+# .roboco/conventions.yml
+version: 1
+languages: [python, typescript]
+
+# Which definition KINDS each module may and may not contain.
+modules:
+  - path: app/routers
+    purpose: HTTP routing only
+    forbidden: [model, helper]      # no Pydantic models or helpers in routers
+  - path: app/models
+    purpose: data models
+  - path: app/services
+    purpose: business logic + side effects
+
+# Toggle or re-level the built-in rules.
+rules:
+  no_models_in_routers: { level: block }   # block | warn | off
+  no_inline_comments: { level: warn }
+
+# Project-specific regex rules.
+custom:
+  - name: no_print
+    pattern: "\\bprint\\("
+    level: warn
+    message: "Use the logger, not print()."
+
+# Reviewed escapes for a genuine false positive.
+waivers:
+  - rule: no_models_in_routers
+    path: app/routers/legacy.py
+    reason: "Legacy shim, scheduled for removal."
+```
+
+## The validator
+
+A single Python CLI classifies every changed definition with tree-sitter (Python and TypeScript grammars, shipped in the agent image) and reports forbidden placements, hygiene violations, and custom-rule matches as JSONL findings, after waiver filtering:
+
+```bash
+python -m roboco.conventions check --root <repo> --files <a> <b> ...
+```
+
+It favours precision over recall — it abstains when it cannot classify a definition, so a `block` gate can never strand a task on a guess — and it fails loud: a validator that cannot run exits non-zero so the gate blocks rather than silently passing.
+
+## Where it is enforced
+
+Enforcement is deterministic and reaches the work two ways: an ambient "Architectural Standard" block injected into an agent's context at spawn, and an auto-attached `## Constraints` section on every project task.
+
+- **Developer pre-submit** — a `block`-level finding refuses `i_am_done` with the offending `file:line` and a fix hint.
+- **In-path PR gate** — the same finding refuses the reviewer's `pr_pass`.
+- **QA review** — findings surface as `convention_findings` in the evidence QA sees when it claims a review.
+
+A `warn`-level finding is reported but never blocks.
+
+## Clearing a false positive
+
+A false positive is relieved by a **waiver** the developer commits in their branch — so the escape is accountable and reviewed in the PR, not a silent in-code suppression (`# noqa` / `# type: ignore` are themselves hygiene violations the standard flags). Add the waiver to `.roboco/conventions.yml`, commit it, and the finding is filtered on the next check.
+
+## Panel
+
+The per-project **Conventions** tab (in the edit-project dialog) shows the effective architecture map and its health, and offers **Save** (commit an edited map back to the repo via a PR) and **Restore** (re-scaffold the canonical file).