feat(scaffold): mdvs scaffold + hook handle for cross-harness integration

AGENTS.md

@@ -55,3 +55,20 @@ These survive across refactors; reach for them when in doubt:
 - Dependencies and their roles: comments in `crates/mdvs/Cargo.toml`.
 - Skills (agent workflows): `.claude/skills/` — invoke via `Skill` for `commit`, `todo`, `rust`, `spec`, `code-editing`, etc.
 - TODOs (in-flight + done): `docs/spec/todos/index.md`.
+
+<!-- mdvs project-rules snippet — paste into AGENTS.md or CLAUDE.md.
+     Generated by `mdvs scaffold snippet`. -->
+
+## mdvs knowledge base
+
+This project uses [mdvs](https://github.com/edochi/mdvs) to manage a markdown knowledge base with a schema defined in `mdvs.toml`. When working with files in this KB:
+
+- **Prefer `mdvs search "<query>"` over `Grep` / `Glob` for semantic lookups.** mdvs runs semantic / hybrid / SQL-filtered search over the KB — usually a better fit than literal pattern matching for finding notes by meaning. Filter by frontmatter with `--where "field = 'value'"` and pick the mode with `--mode semantic|fulltext|hybrid`.
+- **`mdvs check` validates frontmatter against the schema.** A `PostToolUse` hook may surface violations to you automatically as a markdown block under `additionalContext` in the hook output. Treat that block as **a warning, not a block** — the agent's edit already landed; the warning is for you to act on next.
+- **When a violation reaches you, decide:**
+  1. **Mistake** (a typo, the wrong type by accident, a dropped required field) → fix the file in the next turn.
+  2. **Intentional deviation** (the KB is evolving, a category genuinely needs a new variant, a field is shifting type) → surface the deviation to the user and propose updating `mdvs.toml` to absorb the change. **Do not silently fix the file**; the user decides whether the schema or the file is wrong.
+
+The schema is meant to evolve with the KB. Enforcement follows the KB's shape, it does not freeze it. Whenever you propose a schema update, also explain *why* — which file(s) drove the change and what convention the user might want to standardise on.
+
+Full mdvs documentation: <https://edochi.github.io/mdvs/>.