fix(ci): refresh agent metadata budget baselines

fix(config): harden doctor checks and enable Codex full access
fix(agents): align research tools and clarify role boundaries
2026-10-08 16:09:11 +02:00 · 2026-10-08 15:58:47 +02:00 · 2026-10-08 15:43:30 +02:00 · 2026-10-08 15:37:03 +02:00 · 2026-10-08 15:30:23 +02:00 · 2026-10-08 15:25:33 +02:00
190 changed files with 4503 additions and 2591 deletions
@@ -64,23 +64,23 @@ jobs:
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - name: Check PowerShell runtime
+      - name: Install PowerShell runtime
        shell: bash
        run: |
-          if command -v pwsh >/dev/null 2>&1; then
-            echo 'POWERSHELL_AVAILABLE=true' >> "$GITHUB_ENV"
-            exit 0
-          fi
-          if sudo apt-get update && sudo apt-get install --yes --no-install-recommends powershell; then
-            echo 'POWERSHELL_AVAILABLE=true' >> "$GITHUB_ENV"
-          else
-            echo 'POWERSHELL_AVAILABLE=false' >> "$GITHUB_ENV"
-            echo '::warning::PowerShell is unavailable; PowerShell checks skipped for this runner.'
+          set -euo pipefail
+          if ! command -v pwsh >/dev/null 2>&1; then
+            # Microsoft's signed apt repository; the job fails when PowerShell cannot be installed.
+            . /etc/os-release
+            wget -q -O "$RUNNER_TEMP/packages-microsoft-prod.deb" "https://packages.microsoft.com/config/$ID/$VERSION_ID/packages-microsoft-prod.deb"
+            sudo dpkg -i "$RUNNER_TEMP/packages-microsoft-prod.deb"
+            sudo apt-get update
+            sudo apt-get install --yes --no-install-recommends powershell
          fi
+          pwsh -NoLogo -NoProfile -NonInteractive -Command '$PSVersionTable.PSVersion.ToString()'
      - name: Run PowerShell tests
        shell: bash
        run: |
-          if [ "${POWERSHELL_AVAILABLE:-false}" != true ]; then exit 0; fi
+          set -euo pipefail
          pwsh -NoLogo -NoProfile -NonInteractive -File ./scripts/commands/check-capabilities.ps1
          pwsh -NoLogo -NoProfile -NonInteractive -File ./scripts/commands/build.ps1 -Summary
          for file in scripts/tests/test-*.ps1; do
@@ -172,29 +172,23 @@ jobs:
          AI_CONFIG_REQUIRE_CLIENTS: '1'
        run: timeout 900 python scripts/tests/test-client-smoke.py -v

-  retrieval:
-    name: Qwen retrieval integration
+  qmd:
+    name: QMD unit tests
    runs-on: ubuntu-latest
-    timeout-minutes: 30
+    timeout-minutes: 10
    needs: [python]
+    env:
+      QMD_PACKAGE_DIR: ${{ runner.temp }}/qmd-tests
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v22.16.0
        with:
-          python-version: '3.12'
-          cache: pip
-          cache-dependency-path: shared/retrieval/requirements.txt
-      - name: Install retrieval dependencies
-        run: python -m pip install -r shared/retrieval/requirements.txt
-      - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        with:
-          path: .cache/huggingface
-          key: qwen-retrieval-${{ runner.os }}-${{ hashFiles('shared/retrieval/requirements.txt') }}
-      - name: Run retrieval tests with real models
-        env:
-          QWEN_TEST_MODEL_CACHE: ${{ github.workspace }}/.cache/huggingface
-          HF_HUB_DISABLE_XET: '1'
-        run: python scripts/tests/test-retrieval-server.py
+          node-version: '24'
+      # CI runs model-free tests only; real-model integration requires a suitable local machine.
+      - name: Install QMD test dependency
+        run: npm install --prefix "$QMD_PACKAGE_DIR" --ignore-scripts --no-package-lock --no-audit --no-fund yaml@2.9.0
+      - name: Run QMD unit tests
+        run: node --test scripts/tests/test-qmd-lib.mjs scripts/tests/test-qmd-daemon.mjs scripts/tests/test-qmd-search.mjs scripts/tests/test-qmd-warm.mjs scripts/tests/test-qmd-benchmark.mjs

  security:
    name: CI configuration security checks
@@ -1,4 +1,7 @@
 generated/
+generated.build-*/
+generated.old-*/
+generated.lock
 .superpowers/
 *.log
 *.tmp
@@ -12,3 +15,7 @@ credentials.json
 secrets.json
 !.env.example
 .idea
+__pycache__/
+*.pyc
+bin/
+obj/
@@ -30,7 +30,7 @@ Bash:
 ## Quickstart

 With the [requirements](#requirements) installed, clone the repository, build it, then install it.
-Stop if any command fails. Installation asks for the shell, client, Flashbang, status line, Qwen retrieval, and extension choices.
+Stop if any command fails. Installation asks for the shell, client, Flashbang, status line, local QMD search models, and extension choices.

 PowerShell:

@@ -96,11 +96,10 @@ Install and update also rebuild internally; the explicit build above lets you ch
 - Separate install, update, and uninstall scripts: install refuses to run against an already-installed destination,
  update refuses to run against one that is not installed yet, and uninstall refuses to run against one that was
  never installed.
- User-level extension installation for Ponytail, i-have-adhd, Superpowers, Context7, Caveman, QMD, MCPorter,
+- User-level extension installation for Ponytail, i-have-adhd, Superpowers, Context7, Caveman, MCPorter,
  Humanizer, Impeccable, and Anthropic Frontend Design, with an interactive extension toggle during both install and update. Only extensions
  installed and recorded by this setup can be removed through deselection.
- Optional local semantic retrieval for both clients using Qwen3-Embedding-0.6B embeddings and Qwen3-Reranker-0.6B
-  reranking, disabled by default and removable through the install/update choice.
+- Optional local search for both clients through QMD with Qwen3-Embedding-0.6B, Qwen3-Reranker-0.6B, and QMD Query Expansion 1.7B (Yes/No/Auto; Auto benchmarks GPU, then CPU).

 ## Requirements

@@ -108,8 +107,7 @@ Install and update also rebuild internally; the explicit build above lets you ch
 - Bash 4.3 or newer, with standard utilities such as `awk`, `sed`, and `sha256sum`.
 - Python 3.11 or newer for configuration validation and task-state hooks/helpers (`python` for PowerShell scripts, `python3` for Bash scripts).
 - `jq` for Claude's Bash status line; without it, that status line produces no output.
- Python `venv` and `pip` when the optional semantic retrieval layer is enabled.
- Node.js 22 or newer and `npm` when QMD or MCPorter is selected.
+- Node.js 22 or newer and `npm` when local QMD search or MCPorter is selected.

 Core Bash setup scripts do not require PowerShell. The credential commands use Windows Credential Manager and require
 PowerShell, including when invoked through their Bash wrappers. The PowerShell scripts remain compatible with
@@ -129,6 +127,11 @@ shared definitions -> client adapters -> generated packages -> user installation
 | [`scripts/`](docs/scripts.md) | Build, installation, update, diagnosis, and validation scripts. |
 | `docs/` | Focused documentation about the configuration design. |

+Client settings start in `adapters/codex/config/config.toml` and
+`adapters/claude/config/settings.json`. Shared Markdown and metadata define behavior;
+adapters supply client-specific formats and placeholders resolved during build or installation.
+Generated output is not a source to edit.
+
 The build creates:

 ```text
@@ -143,16 +146,13 @@ generated/

 | Document | Contents |
 | --- | --- |
-| [Architecture](docs/architecture.md) | Shared sources, adapters, generated packages, and installation. |
 | [Scripts](docs/scripts.md) | Commands, checks, tests, and internal script layout. |
-| [Configuration](docs/configuration.md) | Client settings, permission defaults, status displays, and verification. |
+| [Configuration](docs/configuration.md) | Client settings, permissions, status displays, local QMD search, and verification. |
 | [Extending the configuration](docs/extending-configuration.md) | Add shared rules, skills, and agents. |
 | [Plugins](docs/plugins.md) | Plugin sources, selection, installation, updates, and removal. |
 | [Hooks](docs/hooks.md) | Registered events, session-state helpers, notifications, and optional utilities. |
 | [Agents](docs/agents.md) | Agent roles and when delegation is useful. |
 | [Skills](docs/skills.md) | Skill categories and conditional rule loading. |
-| [Codex adapter](adapters/codex/README.md) | Codex-specific configuration files. |
-| [Claude Code adapter](adapters/claude/README.md) | Claude-specific configuration files. |
 | [Hook package](shared/hooks/README.md) | Overview shipped with the hook scripts. |
 | [Repository instructions](AI-Instructions.md) | Rules for maintaining this repository. |

@@ -172,7 +172,9 @@ Bash:

 Rebuild when shared definitions, adapters, or generation logic change. Choose other verification according to the
 change's risk; documentation-only edits do not require a build. Building writes reproducible packages below
-`generated/` and may use temporary validation files; it does not install global user configuration.
+`generated/` and may use temporary validation files; it does not install global user configuration. Each build writes
+into its own `generated.build-*` directory and replaces `generated/` only after validation, so a failed or parallel
+build never leaves it partial.

 ## Installation Script

@@ -224,15 +226,17 @@ Every managed file, including `config.toml`, `settings.json`, and the manifest,
 file and then renamed over the target, so an interrupted run never leaves a partly written file. Each destination is
 locked through `.ai-config.lock` while it syncs; a parallel install or update fails instead of interleaving writes.
 A lock left by an exited process of the same shell on the same host is replaced automatically.
+Before its first write, each sync records its planned changes in `.ai-config-transaction.json`; if a run is interrupted,
+the next install or update first rolls that destination back from the backups (`ROLLBACK <destination> <stamp>`).
 Dry runs still rebuild `generated/`, but do not modify installation destinations.

 Selecting Codex also installs shared skills to `.agents/skills`. An interactive extension list includes plugins and
 Codex skills; unchecked extensions are skipped on installation. Normal install and update ask whether to enable
-Flashbang, apply the custom status line, and enable Qwen3 semantic retrieval. Choices are saved for Quickupdate.
+Flashbang, apply the custom status line, and enable local QMD search. Choices are saved for Quickupdate.
 The shared skill catalog includes development skills and focused writing, image, site structure, psychology, and
-conversion skills. All retained skills are included in both generated clients.
+conversion skills. All retained skills are included in both generated clients; installation includes `semantic-search` only when local QMD search is enabled.
 The status line defaults to enabled to preserve existing behavior. Disabling it removes the custom client setting and,
-for Claude, the setup-owned status line script. Disabling retrieval on update removes its setup-owned runtime and index.
+for Claude, the setup-owned status line script. Disabling local QMD search removes its setup-owned package, models, and repository collections once no client still uses it. See [Local QMD search](docs/configuration.md#local-qmd-search) for storage and removal details.
 Dry runs preview changes without updating extensions or retrieval. See [Plugins](docs/plugins.md) for client-specific behavior.

 ## Update Script
@@ -259,7 +263,7 @@ setup; pre-existing or manually installed extensions are retained. Quickupdate r
 ## Uninstall Script

 Remove everything this setup previously installed for the selected client(s): managed files tracked in each
-destination's manifest, extensions and skills recorded in the extension ledger, an enabled semantic retrieval setup,
+destination's manifest, extensions and skills recorded in the extension ledger, an enabled local QMD search setup,
 and the saved Quickupdate selection (once no destination remains installed for any client).

 PowerShell:
@@ -285,8 +289,8 @@ touched. Codex skill backups are kept under `.agents/.ai-config-skill-backups/`.
 deleted once it is fully empty; backups already on disk are always kept.
 Extensions and skills recorded in the ledger are removed the same way `update` removes a deselected extension:
 pre-existing or manually installed ones outside the ledger are left alone, and a skill file modified since it was
-installed is kept with a warning. An enabled semantic retrieval setup is disabled and its setup-owned runtime and
-index removed for the selected client(s). The saved Quickupdate selection (`~/.my-ai-configuration/selection.json`)
+installed is kept with a warning. Local QMD search is disabled for the selected client(s). Its shared runtime,
+owned models, and recorded repository collections are removed only when no client still uses it; the shared QMD database and foreign collections are retained. The saved Quickupdate selection (`~/.my-ai-configuration/selection.json`)
 is only removed once uninstalling leaves no client installed at all, so uninstalling just one client out of a
 `Both` installation keeps the saved choices for the client that remains.

@@ -297,7 +301,9 @@ keep outside this setup's ledger, or files this setup never installed.

 Codex and Claude Code receive the same shared rules, skills, agents, hooks, and status data. Codex loads applicable rules from generated files, while Claude Code exposes technology- and situation-specific rules as generated skills.

-Codex defaults to workspace-write sandboxing and automatic review for eligible escalation requests. Claude uses
+Codex defaults to full access under the account that launches it, with unrestricted command network access.
+Launch Codex as the repository owner; Codex does not switch to that owner automatically. Full access removes
+Codex's filesystem sandbox boundaries. Eligible approval requests still use automatic review. Claude uses
 automatic permissions and enables its sandbox where the platform supports it; explicit deny rules still apply where it
 does not. Both clients include the same logical agent roles and compact status displays. See
 [Configuration](docs/configuration.md) for settings, permissions, and limitations.
@@ -1,3 +0,0 @@
-# Claude Code adapter
-
-Claude Code uses global `CLAUDE.md`, `settings.json`, skills, and agents under the user profile. This adapter supplies client metadata; semantic content remains in `shared/`.
@@ -1,6 +1,6 @@
 role	tools
-architect	Read,Grep,Glob,WebFetch,WebSearch
-researcher	Read,Grep,Glob,WebFetch,WebSearch
+architect	Read,Grep,Glob,WebFetch,WebSearch,__SHELL__
+researcher	Read,Grep,Glob,WebFetch,WebSearch,__SHELL__
 reviewer	Read,Grep,Glob,__SHELL__
 verifier	Read,Grep,Glob,__SHELL__
 implementer	Read,Grep,Glob,Edit,Write,__SHELL__
@@ -16,7 +16,10 @@
  },
  "hooks": {
    "PreCompact": [{"hooks": [{"type": "command", "command": "__HOOK_COMMAND__ \"__AI_CONFIG_ROOT__/hooks/scripts/__COMPACT_SCRIPT__\"", "timeout": 4}]}],
-    "SessionStart": [{"hooks": [{"type": "command", "command": "__HOOK_COMMAND__ \"__AI_CONFIG_ROOT__/hooks/scripts/__SESSION_POINTER_SCRIPT__\"", "timeout": 4}]}],
+    "SessionStart": [
+      {"hooks": [{"type": "command", "command": "__HOOK_COMMAND__ \"__AI_CONFIG_ROOT__/hooks/scripts/__SESSION_POINTER_SCRIPT__\"", "timeout": 4}]},
+      {"hooks": [{"type": "command", "command": "__HOOK_COMMAND__ \"__AI_CONFIG_ROOT__/hooks/scripts/__QMD_WARM_SCRIPT__\"", "timeout": 4}]}
+    ],
    "Stop": [
      {
        "hooks": [
@@ -1,3 +0,0 @@
-# Codex adapter
-
-Codex uses global `AGENTS.md`, `config.toml`, skills, and agent configuration under the user profile. This adapter supplies client metadata; semantic content remains in `shared/`.
@@ -1,15 +1,9 @@
 approval_policy = "on-request"
 approvals_reviewer = "auto_review"
-sandbox_mode = "workspace-write"
-
-[sandbox_workspace_write]
-network_access = true
-
-[windows]
-sandbox = "unelevated"
+sandbox_mode = "danger-full-access"

 [tui]
-status_line = ["model", "reasoning", "approval-mode", "project-name", "git-branch", "context-window-size", "context-used", "used-tokens"]
+status_line = ["model", "reasoning", "fast-mode", "approval-mode", "five-hour-limit", "weekly-limit", "project-name", "git-branch", "context-window-size", "context-used", "used-tokens"]

 [agents]
 enabled = true
@@ -18,6 +12,7 @@ max_depth = 1

 [features]
 hooks = true
+api_key_model_discovery = true

 [[hooks.Stop]]
 [[hooks.Stop.hooks]]
@@ -25,3 +20,10 @@ type = "command"
 command = '__HOOK_COMMAND__ "__AI_CONFIG_ROOT__/hooks/__HOOK_SCRIPT__"'
 command_windows = '__POWERSHELL_HOOK_COMMAND__ "__AI_CONFIG_ROOT__/hooks/__POWERSHELL_HOOK_SCRIPT__"'
 timeout = 8
+
+[[hooks.SessionStart]]
+[[hooks.SessionStart.hooks]]
+type = "command"
+command = '__HOOK_COMMAND__ "__AI_CONFIG_ROOT__/hooks/scripts/__QMD_WARM_SCRIPT__"'
+command_windows = '__POWERSHELL_HOOK_COMMAND__ "__AI_CONFIG_ROOT__/hooks/scripts/__QMD_WARM_SCRIPT__"'
+timeout = 4
@@ -4,7 +4,6 @@ i-have-adhd	ayghri/i-have-adhd	i-have-adhd@i-have-adhd	ayghri/i-have-adhd	i-have
 Superpowers	anthropics/claude-plugins-official	superpowers@claude-plugins-official	openai-curated-remote	superpowers@openai-curated-remote	plugin	-	-
 Context7	upstash/context7	context7@context7-marketplace	upstash/context7	context7@context7-marketplace	plugin	-	-	context7	https://mcp.context7.com/mcp
 Caveman	JuliusBrussee/caveman	caveman@caveman	thinkhome-org/caveman-codex	caveman@thinkhome-caveman	plugin	-	-
-QMD	tobi/qmd	qmd@qmd	-	-	qmd	@tobilu/qmd	qmd
 MCPorter	-	mcporter	-	mcporter	cli	mcporter	-
 Humanizer	blader/humanizer	humanizer@humanizer	-	-	skill	blader/humanizer	humanizer
 Impeccable	pbakaus/impeccable	impeccable@impeccable	pbakaus/impeccable	impeccable	skill	pbakaus/impeccable	impeccable
@@ -24,8 +24,8 @@
      "codex": 8510
    },
    "agent_metadata_tokens": {
-      "claude": 126,
-      "codex": 52
+      "claude": 204,
+      "codex": 124
    }
  }
 }
@@ -9,5 +9,5 @@ auto_loaded_rule_tokens	claude	678
 auto_loaded_rule_tokens	codex	678
 rule_catalog_tokens	claude	28818
 rule_catalog_tokens	codex	8510
-agent_metadata_tokens	claude	126
-agent_metadata_tokens	codex	52
+agent_metadata_tokens	claude	204
+agent_metadata_tokens	codex	124
@@ -2,14 +2,20 @@

 The five shared agents are logical roles, not mandatory steps.

- `implementer` executes the smallest complete engineering change and performs self-review.
- `researcher` investigates code, patterns, evidence, alternatives, and unknowns without modifying implementation code by default.
- `architect` evaluates technical boundaries, dependencies, interfaces, constraints, and design options.
+- `implementer` implements scoped features and fixes with proportionate tests and self-review.
+- `researcher` answers questions about repository behavior, external documentation, and unknowns with source evidence, without modifying implementation code by default.
+- `architect` compares design options and recommends technical boundaries and interfaces before implementation; implementation changes require an explicit assignment.
 - `verifier` supplies execution evidence from relevant tests, builds, checks, generated output, and behavior reproduction. It inspects implementation only to choose checks and does not review the diff for general correctness.
 - `reviewer` starts with the actual diff and changed symbols, then examines necessary callers, dependencies, tests, and contracts for analytical correctness. It does not run tests, builds, or runtime checks; it reports missing execution evidence.

 Use only the roles that are likely to improve the outcome. Choose `researcher`, `reviewer`, and `verifier` based on the task's uncertainty, complexity, risk, blast radius, and verification value; none runs automatically. The agent may make evidence-based, reversible technical decisions. Ask the user when technical choices remain materially uncertain or when business behavior, user-visible behavior, UI, UX, APIs, database models, configuration formats, compatibility behavior, or other high-impact decisions are ambiguous or open to interpretation.

+## Research tools
+
+Claude's [capability manifest](../adapters/claude/capabilities.tsv) gives `architect` and `researcher` file inspection, web research, and the package's shell tool (`PowerShell` or `Bash`). Shell access supports mandatory semantic search and Context7 research through MCPorter. Their role instructions scope shell use to inspection and research; this is an instruction-level boundary, not a read-only shell sandbox.
+
+The `reviewer` may inspect Git diffs and run required research commands through its shell tool. Tests, builds, and behavior reproduction belong to the `verifier` or parent. Missing execution evidence remains an explicit review gap. Codex receives the same role instructions; the Claude tool manifest is client-specific.
+
 ## Coordination

 The main agent owns task state, decisions, and progress. Subagents report to their parent. The parent forwards only relevant conclusions, references, risks, and constraints; direct peer communication requires a concrete dependency and parent coordination. Subagents cannot create further subagents.
@@ -1,5 +0,0 @@
-# Architecture
-
-Shared Markdown and metadata define meaning once. Codex and Claude adapters contain only client-specific paths, filenames, and serialization details. The build script renders those inputs into `generated/`. Installation is a separate, explicit step that copies generated files into global user-level locations with backups.
-
-Generated output is ignored because it is reproducible build output. The source files are the reviewable record.
@@ -1,6 +1,19 @@
 # Configuration

-Codex receives a generated global `AGENTS.md`, agent TOML files, skills, rule files, and a `config.toml` adapter. It sets workspace sandboxing with network access for shell commands (so MCPorter calls such as Context7 work without approval), automatic approval review, `agents.enabled = true`, `agents.max_concurrent_threads_per_session = 5`, and `agents.max_depth = 1`. Claude Code receives a generated global `CLAUDE.md`, agent Markdown files, skills, and `settings.json` with `auto` permissions, explicit `Agent` and `mcporter call context7.*` shell permissions, `mcp.context7.com` as the only allowed sandbox domain where the Claude sandbox is enabled, a five-operation concurrency default, at most five concurrent subagents (`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`), and a subagent spawn depth of one (`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`), so subagents cannot start further subagents. Installation resolves user paths at runtime; the repository contains no machine-specific paths.
+Source templates are [`adapters/codex/config/config.toml`](../adapters/codex/config/config.toml)
+and [`adapters/claude/config/settings.json`](../adapters/claude/config/settings.json).
+Installation targets `~/.codex` and `~/.claude`; Codex skills go to `~/.agents/skills`.
+Choose the PowerShell or Bash package independently of the client.
+
+Codex receives a generated global `AGENTS.md`, agent TOML files, skills, rule files, and a `config.toml` adapter.
+It sets full access for commands, automatic approval review, `agents.enabled = true`,
+`agents.max_concurrent_threads_per_session = 5`, and `agents.max_depth = 1`.
+
+Claude Code receives a generated global `CLAUDE.md`, agent Markdown files, skills, and `settings.json` with
+`auto` permissions and explicit `Agent` and `mcporter call context7.*` shell permissions. Where enabled, its sandbox
+allows the `mcp.context7.com` domain. The adapter sets a five-operation concurrency default, at most five concurrent
+subagents (`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`), and a spawn depth of one (`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`).
+Installation resolves user paths at runtime. Active session policy can further restrict these defaults.

 Both clients embed `shared/rules/general.md` and the rule-loading conditions from `shared/global-instructions.md`. Rules for languages and frameworks live in their own directories, with an `index.md` entry point and focused Markdown rules under `references/`. Security has its own directory with a baseline entry point and focused rules for authentication, web, APIs, data, files, network, cryptography, and supply chains. Git, Microsoft, and cross-cutting rules remain directly under `shared/rules/`. Codex receives the full directory tree; Claude generates a skill for each rule and copies supporting references alongside the index skill.

@@ -12,11 +25,30 @@ Client settings remain thin adapters. Shared semantics remain in `shared/`. User

 ## Permission defaults

-Codex sets `approval_policy = "on-request"`, `approvals_reviewer = "auto_review"`, and `sandbox_mode = "workspace-write"`. Eligible approval requests go through automatic review. Claude sets `permissions.defaultMode = "auto"` and shell-specific deny rules. Its sandbox is enabled on supported macOS, Linux, and WSL2 environments and disabled where unavailable, including native Windows. These are generated defaults, not a guarantee that a running session, account policy, or explicit launch override uses the same mode.
+Codex sets `sandbox_mode = "danger-full-access"`, `approval_policy = "on-request"`, and
+`approvals_reviewer = "auto_review"`. All Codex commands run without Codex filesystem or network sandbox
+restrictions, under the account that launches Codex. Launch Codex as the repository owner to use that identity;
+this configuration does not impersonate another user or change filesystem ownership. OS permissions, firewalls,
+and managed organization policies still apply. Eligible approval requests retain automatic review, which does
+not restore a filesystem boundary. See the [official OpenAI security documentation](https://learn.chatgpt.com/docs/agent-approvals-security).
+
+The adapter no longer selects the Windows sandbox or workspace writable roots. This avoids using the dedicated
+`CodexSandboxOnline` account, whose identity differs from the repository owner and can trigger Git's ownership
+check. Old `[windows]` and `[sandbox_workspace_write]` tables may survive an update as preserved local settings;
+they do not activate sandboxing while `sandbox_mode` is `danger-full-access`.
+
+Apply the generated configuration through the normal update process, then start a new Codex session under the
+repository owner's account. Existing sessions keep their active permissions. Check `whoami` and
+`git rev-parse --show-toplevel` there; package validation cannot prove the identity or network access of a future
+session. Launch overrides and managed policies may restrict or reject the configured mode.
+
+Claude retains `permissions.defaultMode = "auto"` and shell-specific deny rules. Its sandbox is enabled on
+supported macOS, Linux, and WSL2 environments and disabled where unavailable, including native Windows.
+These are generated defaults; active session or account policy may differ.

 ## Status displays

-Codex's native `tui.status_line` contains `model`, `reasoning`, `approval-mode`, `project-name`, `git-branch`, `context-window-size`, `context-used`, and `used-tokens`, in that order. `approval-mode` reports the active command review mode. Rendering and colors are controlled by Codex; the adapter does not define custom colors per field.
+Codex's native `tui.status_line` contains `model`, `reasoning`, `fast-mode`, `approval-mode`, `five-hour-limit`, `weekly-limit`, `project-name`, `git-branch`, `context-window-size`, `context-used`, and `used-tokens`, in that order. `fast-mode` shows `Fast on` or `Fast off` for supported models; it does not change the selected mode. `five-hour-limit` and `weekly-limit` show remaining usage in the primary and secondary quota windows, typically five hours and one week, and are omitted when Codex has no quota data. `approval-mode` reports the active command review mode. Rendering and colors are controlled by Codex; the adapter does not define custom colors per field. These native fields are supported by [Codex 0.161.0](https://github.com/openai/codex/blob/rust-v0.161.0/codex-rs/tui/src/chatwidget/status_surfaces.rs).

 Claude runs `shared/statusline/statusline.ps1` for PowerShell or `statusline.sh` for Bash. Its two-line display is:

@@ -31,6 +63,79 @@ Model and context-window size are cyan, effort and cumulative tokens magenta, re

 Claude's status line displays `permission_mode` or `permissionMode` when Claude provides it, and otherwise shows the configured `auto` review mode.

+## Local QMD search
+
+Install and update offer **Yes / No / Auto**, with No as the initial default. This option is separate
+from the extension selector. The saved `semantic_retrieval` key keeps its name for compatibility.
+Quickupdate reuses the saved choice and device; it does not rerun the benchmark.
+
+- **Yes:** install `@tobilu/qmd@2.8.3` if QMD is absent, copy the shared runtime scripts, configure
+  and download the three models, and choose GPU when detected or CPU otherwise. An existing QMD
+  installation is reused, not upgraded by this step.
+- **Auto:** prepare the same dependencies, then benchmark GPU when available and CPU if needed.
+  Both thresholds must pass: median warm search latency at most 5 seconds and embedding throughput
+  at least 20 chunks/second. Each device has a 10-minute timeout. No passing device disables search
+  and triggers setup-owned resource cleanup. Auto can download models while answering the setup prompt.
+- **No:** omit the search skill and its instruction line, remove the warm-up hook registration,
+  and disable search for the selected clients. Dry runs do not download, benchmark, or remove QMD resources.
+
+The models are Qwen3-Embedding-0.6B, Qwen3-Reranker-0.6B, and QMD Query Expansion 1.7B.
+Exact model URIs live in [`shared/qmd/qmd-lib.mjs`](../shared/qmd/qmd-lib.mjs).
+Auto thresholds can be overridden with `QMD_BENCHMARK_MAX_QUERY_SECONDS` and
+`QMD_BENCHMARK_MIN_CHUNKS_PER_SECOND`. The benchmark uses a temporary database and a deterministic
+100-document fixture; its measurements are not an end-to-end estimate for a user's repository.
+
+### Search and storage
+
+The `semantic-search` skill calls the installed wrapper from the current Git repository:
+
+```text
+node "$HOME/.my-ai-configuration/qmd/qmd-search.mjs" --query "Where are temporary upload failures retried?" --top-k 5
+```
+
+This command works in PowerShell and Bash. `--root` selects a repository explicitly. Results are JSON
+objects with `path`, `line`, `score`, and `snippet`; repository hits use relative paths and other collections
+use `qmd://` URIs. Known identifiers still use direct reads or `rg`; unknown identifiers use semantic retrieval first.
+
+A token-protected daemon listens on `127.0.0.1`, refreshes changed repository collections, skips git-ignored
+paths, and searches the current repository together with the user's default QMD collections. Repository
+collections use `repo-` followed by a 12-character path hash. A SessionStart hook warms the daemon and index
+in the background. Models stay loaded until the daemon stops after 30 idle minutes, configurable with
+`QMD_IDLE_MINUTES`.
+
+On daemon failure the wrapper tries the QMD CLI against the current repository collection only. This fallback
+requires an existing index; it does not create or refresh the collection. If the wrapper fails, the skill
+reports the limitation and continues with `rg`.
+
+| Location | Contents |
+| --- | --- |
+| `~/.my-ai-configuration/qmd/` | Runtime scripts, daemon state, locks, collection ownership, and `warm.log`. |
+| `~/.my-ai-configuration/qmd.json` | Selected device, enabled clients, and setup ownership records. |
+| `$XDG_CACHE_HOME/qmd/` (default `~/.cache/qmd/`) | Shared `index.sqlite` and model cache. |
+| `$QMD_CONFIG_DIR/index.yml` | Configuration when `QMD_CONFIG_DIR` is set; otherwise `$XDG_CONFIG_HOME/qmd/index.yml`, defaulting to `~/.config/qmd/index.yml`. |
+
+With the default Codex full-access configuration, QMD uses the launching account's filesystem and network
+permissions, including custom cache and configuration paths. If a session overrides this with a sandbox,
+permit writes to the runtime directory, resolved cache, and QMD configuration directory. QMD writes configuration
+when registering collections and persisting ignore lists.
+
+Disabling search or uninstalling one client keeps the shared runtime while another client remains enabled.
+After the last client disables it, cleanup stops the daemon, removes recorded repository collections and
+setup-owned models/package, restores the previous `models:` block, and removes the runtime scripts.
+It preserves foreign QMD installations, models, collections, and the shared database. Failed cleanup can leave
+resources behind; inspect reported warnings rather than deleting the whole cache. Updates also migrate the
+old setup-owned Python retrieval directory and QMD extension ownership records.
+
+### Verification and troubleshooting
+
+Check `~/.my-ai-configuration/qmd/warm.log` for background warm-up errors. First startup or changed repositories
+can take longer than a warm query. An older session still using the Windows sandbox can fail Git ownership
+checks or child-process pipe operations. Apply the configuration and start a new session as described in
+[Permission defaults](#permission-defaults).
+
+Model-free unit tests do not verify downloads, GPU support, sandbox access, or real search quality.
+See [QMD tests](scripts.md#qmd-tests) for the separate test commands and dependency setup.
+
 ## Verification and installation

 The agent chooses the smallest sufficient checks based on behavior, affected callers, risk, reversibility, and uncertainty. Inspection can suffice for a small change. Full builds, broad test suites, and independent reviews are not automatic; explicit user and project requirements remain binding.
@@ -9,10 +9,13 @@ The adapters register these events:
 | Codex and Claude | `Stop` | Run the finish notification (`flashbang`). |
 | Claude | `PreCompact` | Record the compaction timestamp under the installed configuration root and point to existing workspace task state. |
 | Claude | `SessionStart` | Print an absolute pointer if the workspace's `.ai-session/state.json` exists. |
+| Codex and Claude | `SessionStart` | Warm the QMD index and search daemon in the background (only while local QMD search is enabled). |

-The main agent alone maintains canonical task state. Hooks never write or summarize it, print its contents, or infer completed verification. They use the hook event's `cwd`, falling back to the process working directory when no workspace is supplied. Malformed event data does not fall back to another project. An absent state file is a successful no-op. Legacy state under the installed configuration root is not automatically adopted; confirm its task before migrating it. The scripts do not grant permissions, bypass approvals, or replace client permission systems.
+The main agent alone maintains canonical task state. Hooks never write or summarize it, print its contents, or infer completed verification. The task-state hooks use the hook event's `cwd`, falling back to the process working directory when no workspace is supplied. Malformed event data does not fall back to another project. An absent state file is a successful no-op. Legacy state under the installed configuration root is not automatically adopted; confirm its task before migrating it. The scripts do not grant permissions, bypass approvals, or replace client permission systems.

-When enabled during installation or update, Flashbang runs on `Stop`, after the main agent finishes responding. The default flash lasts about 500 milliseconds. The PowerShell command omits `-WindowStyle Hidden`, which can hide or minimize the shared terminal. The PowerShell hook creates a low-opacity click-through overlay without activating another window when its native GUI APIs are available; unsupported runtimes exit safely. The Bash hook uses Python's `tkinter`, uses `xrandr` for multi-monitor bounds when available, and falls back to `notify-send` when the overlay is unavailable. Registered hooks are best effort: errors do not fail a Claude session.
+The QMD warm-up hook uses the process working directory and starts only inside a Git repository when Node.js and the installed wrapper are available. It runs detached; wrapper errors are recorded in `~/.my-ai-configuration/qmd/warm.log`. Disabling local search removes its hook registration. See [Local QMD search](configuration.md#local-qmd-search) for daemon behavior and storage.
+
+When enabled during installation or update, Flashbang runs on `Stop`, after the main agent finishes responding. The default flash lasts about 500 milliseconds. The PowerShell command omits `-WindowStyle Hidden`, which can hide or minimize the shared terminal. The PowerShell hook creates a low-opacity click-through overlay without activating another window when its native GUI APIs are available; unsupported runtimes exit safely. Its native DLL cache is optional: a missing `LOCALAPPDATA` environment variable or an unusable cache falls back to in-process compilation instead of suppressing the notification. The Bash hook uses Python's `tkinter`, uses `xrandr` for multi-monitor bounds when available, and falls back to `notify-send` when the overlay is unavailable. Registered hooks are best effort: errors do not fail a Claude session.

 `Validate-CommandSafety`/`validate-command-safety.sh` and `Invoke-PostChangeVerification`/`invoke-post-change-verification.sh` are unregistered utilities. The safety utilities check command text for selected dangerous patterns; the PowerShell variant also checks some absolute paths. Neither is a complete security boundary. The verification utilities explicitly run the repository build when invoked; they are not an automatic requirement after each change.

@@ -2,10 +2,39 @@

 The user-level plugin manifest is `adapters/plugins.tsv`. It maps each logical extension to the client-specific plugin, skill, or MCP installation method.

-The current baseline includes Ponytail, i-have-adhd, Superpowers, Context7, Caveman, QMD, MCPorter, Humanizer, Impeccable, and Anthropic Frontend Design. Both scripts operate at user scope and show an extension selector unless running a dry run. Selections are collected before configuration changes. Both rebuild generated packages first.
+The current baseline includes Ponytail, i-have-adhd, Superpowers, Context7, Caveman, MCPorter, Humanizer, Impeccable, and Anthropic Frontend Design. Install and update operate at user scope and show an extension selector unless running a dry run or Quickupdate. Selections are collected before configuration changes. Both rebuild generated packages before synchronizing client files and extensions. Choosing Auto for local search can prepare and benchmark QMD earlier, during option selection.
+
+### Automatic workflow integration
+
+The always-loaded general rules route both clients to the shared `plugin-workflow` skill at session start/resume and task or phase changes. The policy requires Superpowers at development phase boundaries, Ponytail for implementation and review, Impeccable for UI planning through verification, and i-have-adhd response structure with Caveman's concise style when available. Superpowers owns process; Ponytail constrains implementation to the smallest complete, verified change; Impeccable owns UI decisions; Frontend Design supplements uncovered needs without starting another workflow. User authorization, research gates, and proportionate checks retain precedence.
+
+The installed i-have-adhd 0.4.1 skill declares `disable-model-invocation: true`. The shared policy therefore supplies automatic response guidance without forcing a manual-only skill invocation or relying on its optional hook. It does not diagnose the user. Style stop commands persist through task changes and resume; `normal mode` disables i-have-adhd, Caveman, and Ponytail for the session. Explicit mode levels override defaults. Missing plugins are reported once and do not trigger installation. These are instruction-level requirements, not runtime interception or a guarantee of model compliance. Existing installations receive them through the normal configuration update; builds do not modify local plugin caches or hook trust.
+
+### Context7 routing

 Selecting Context7 with MCPorter registers the server in MCPorter. Selecting Context7 without MCPorter installs its native client plugin; that explicit selection permits the native MCP route under the global instructions.

+Both clients receive a mandatory Context7-first research gate through the shared general rules and `technical-research` skill. It triggers whenever answers, planning, coding, reviews, debugging, tests, configuration, or upgrades rely on external technology behavior, without requiring the user to mention Context7. The agent checks project versions, resolves the library, queries the relevant behavior, and verifies the original source. Matching evidence from the same task can be reused across phases and handoffs; repository-only facts need no external call. Missing coverage, version mismatches, and service failures require an explicit fallback to authoritative sources. [Phase checkpoints](skills.md) apply inside plugin workflows as well as the focused shared skills. These are agent instructions, not a runtime enforcement hook.
+
+### Optional Context7 health check
+
+For a configured MCPorter route, run these commands in PowerShell or Bash. They make live requests using a public Angular question; they do not install or change configuration. Routine builds and doctor runs do not run this check.
+
+```text
+mcporter list context7 --schema
+mcporter call context7.resolve-library-id 'libraryName=Angular' 'query=How do Angular computed signals track dependencies?' --timeout 30000
+```
+
+Check that discovery lists `resolve-library-id` and `query-docs` and resolution returns the official Angular documentation. Then query the returned ID (the example assumes `/websites/angular_dev` was returned):
+
+```text
+mcporter call context7.query-docs 'libraryId=/websites/angular_dev' 'query=How do Angular computed signals track dependencies?' --timeout 30000
+```
+
+The check passes only if documentation retrieval returns relevant content with an original Angular source link. Empty results, error text, or merely a zero process exit code are insufficient. This checks connectivity and one library, not general coverage or agent compliance. For a native plugin installation, run the equivalent discovery and tool calls inside that client; do not add an MCPorter registration just for this check.
+
+### Installation and updates
+
 `install.ps1`/`install.sh` starts every plugin checked by default; unchecking one skips it. It refuses to run against an already-installed destination (`Already installed, use the update script.`).

 `update.ps1`/`update.sh` lets you revise the saved extension selection. Checking an extension installs it if missing or updates it if owned; existing foreign installations are preserved. Deselection removes only extensions that this setup installed and recorded as owned. Pre-existing or manually installed plugins and skills are retained. Extensions removed from the manifest are also removed when recorded as owned; unrelated installations are retained. Update refuses to run if any selected destination lacks an installation manifest (`Not installed, use the install script.`).
@@ -16,11 +45,17 @@ Codex receives Caveman through its native plugin adapter. Humanizer, Impeccable,

 On Windows, installation and update repair the known Caveman 1.0.0 hook launcher in setup-owned Codex installations so it resolves the plugin path under PowerShell as well as Command Prompt. Custom commands and foreign installations are preserved. Review the changed hook definitions in Codex `/hooks`; setup does not grant hook trust automatically.

-[QMD](https://github.com/tobi/qmd) requires Node.js 22 or newer and `npm`. Selecting it installs `@tobilu/qmd` globally. Claude receives QMD's official `qmd@qmd` plugin; Codex can use the `qmd` CLI. Deselecting QMD removes setup-owned integrations and uninstalls the global package when the Codex-owned QMD record is removed.

-Normal installation and update ask whether to enable Flashbang, apply the custom status line, and enable the optional Qwen3-Embedding-0.6B semantic retrieval layer. Retrieval uses a per-user virtual environment and index and is invoked through the installed `server.py search` CLI, disabled by default. Quickupdate reuses the saved shell, client, status line, Flashbang, retrieval, and extension choices without opening menus. Disabling the status line removes its custom setting and setup-owned Claude script; disabling retrieval removes its setup-owned runtime and index. Only successful runs save selections; dry runs do not update extensions or retrieval. Install and update do not modify the Codex or Claude CLI installations.
+### Setup options outside the extension selector

-The `server.py search`/`rebuild` CLI transparently reuses a background daemon (spawned automatically on first use per `--data-dir`) that keeps the embedding and reranking models loaded in memory, so only the first query after a cold start or an idle period pays the model-loading cost; every call falls back to loading the models directly in-process if the daemon cannot be reached or started. The daemon exits on its own after 30 minutes of inactivity. Search requires a Git repository and indexes tracked files plus untracked files that Git does not ignore. Indexing skips files larger than 512 KB and, per repository, stops after 2000 indexable files by default; set `SEMANTIC_RETRIEVAL_MAX_FILES` to raise that cap for larger monorepos. When the cap is reached, the CLI prints an explicit warning to stderr rather than silently omitting files.
+Flashbang, the custom status line, and local QMD search have separate prompts during install and update.
+Quickupdate reuses their saved choices together with the shell, client, and extension selection. Only successful
+runs save selections; dry runs do not update extensions or local search. Disabling the status line removes its
+custom setting and setup-owned Claude script.
+
+QMD is managed by the local-search option, not as a plugin. See [Local QMD search](configuration.md#local-qmd-search)
+for models, Auto thresholds, runtime behavior, sandbox paths, and ownership-aware removal.
+Install and update do not modify the Codex or Claude CLI installations.

 Plugin installation requires the corresponding client CLI, network access, and any authentication required by the plugin. Context7 may open an OAuth flow. Codex or plugin hooks may require a trust review in `/hooks`. The scripts never install plugins during a build or doctor run and never install them when `--dry-run` or `-DryRun` is used.

@@ -23,7 +23,7 @@ Run scripts from the repository root. PowerShell and Bash commands have equivale
 | `commands/doctor.ps1`, `commands/doctor.sh` | Check generated output and installed configuration. |
 | `commands/prompt-budget.ps1`, `commands/prompt-budget.sh` | Track permanent context, skill metadata, the rule catalog, and agent metadata; warn above 10,000 permanent-context tokens, fail when any token estimate exceeds its baseline by 10%, or permanent context exceeds 15,000 tokens. |
 | `commands/context-report.ps1`, `commands/context-report.sh` | Report the context installed Claude and Codex actually load, from Claude `/context`, `/skill-doctor`, and its init event, and Codex `debug prompt-input`: categories, active plugins, listed skills, installed skills missing from the listing, and skills listed without description context. `--check` fails on missing or description-less skills. No model request is made. |
-| `commands/benchmark.ps1`, `commands/benchmark.sh` | Run the ten tasks under `scripts/benchmarks/tasks/` with and without the installed setup and compare pass rate, rework turns, duration, tokens, tool calls, cost, and workflow checks (no planning ceremony for a small change, targeted verification for a bugfix, bounded delegation for a larger change). Starts real model sessions; use `--dry-run` to list runs. The Codex baseline needs one `codex login` with `CODEX_HOME` set to `--codex-baseline-home`. |
+| `commands/benchmark.ps1`, `commands/benchmark.sh` | Compare real Claude/Codex sessions with and without the setup. See [Session benchmarks](#session-benchmarks) for isolation, costs, and the search comparison. |
 | `commands/repository-context.ps1`, `commands/repository-context.sh` | Refresh the local repository-context cache. |
 | `commands/session-state.ps1`, `commands/session-state.sh` | Read or update the local agent session state. |
 | `commands/telemetry.ps1`, `commands/telemetry.sh` | Append a local telemetry event. |
@@ -32,26 +32,38 @@ Run scripts from the repository root. PowerShell and Bash commands have equivale
 | `commands/add-credentials.ps1`, `commands/add-credentials.sh` | Store a client-scoped tool credential in the operating-system credential store. |
 | `commands/remove-credentials.ps1`, `commands/remove-credentials.sh` | Delete a selected client-scoped credential from the operating-system credential store. |

-Prompt KPIs estimate tokens as UTF-8 bytes divided by four, using the larger shell package per client. Skill metadata counts `SKILL.md` frontmatter outside rule skills; the rule catalog counts all generated rule entry files but excludes references, so it measures the available catalog size rather than rules loaded in a typical session; agent metadata counts frontmatter for Claude and `name`/`description` for Codex. All metrics fail CI above baseline +10%; permanent context also warns above 10,000 tokens and fails above 15,000 tokens. The baseline covers the retained skill catalog. Project-specific instructions, external plugin prompt bodies, and live MCP/tool schemas are not measured.
+Prompt KPIs estimate tokens as UTF-8 bytes divided by four, using the larger shell package per client.
+Skill metadata counts every `SKILL.md` frontmatter, including Claude's generated rule skills. Permanent context
+combines global instructions, skill and agent metadata, and the security baseline loaded for development tasks.
+The rule catalog counts Codex rule files outside `references/` and Claude's generated `rules-*/SKILL.md` entries;
+it measures available guidance, not all rules loaded in a typical session. Agent metadata counts Claude frontmatter
+and Codex `name`/`description` fields. All metrics fail above baseline +10%; permanent context also warns above
+10,000 tokens and fails above 15,000. Project instructions, external plugin bodies, and live MCP/tool schemas
+are excluded. `context-report` complements this estimate with installed-client discovery.

-Custom instructions are read before generated rules, skills, and plugins. They remain under `~/.my-ai-configuration/instructions/`, so installation and update scripts never manage or reset them.
+Custom instructions remain under `~/.my-ai-configuration/instructions/`; installation and update scripts never reset their contents. Only clients with a nonempty instruction file receive a startup rule in their installed `AGENTS.md` or `CLAUDE.md`. That rule requires immediate loading before any response or task work and keeps the instructions active throughout the session, including after compaction. Adding or removing instructions refreshes the rule in an existing installation; empty or missing instruction files leave no rule. Generated packages contain no personal instruction rule. Changes apply when the client next loads its global instructions.
 To undo an added instruction, pass the same text to `remove-instruction` with `-Client`/`--client` and `-Instruction`/`--instruction`. It removes the last exact matching block per selected client and preserves other text. A missing match leaves the file unchanged.

 Credential commands currently require PowerShell and Windows Credential Manager, including their Bash wrappers. Use `~/.my-ai-configuration/bin/with-credential.ps1` or `.sh` to run a tool with a stored key available only in that child process. The key must be a valid environment-variable name; its value is never written to configuration.
 Use `remove-credentials` with `-Client`/`--client` and `-Key`/`--key` to delete only that credential. The shared `with-credential` helpers remain installed for other keys.

-The A/B benchmark measures whole sessions. Qwen Auto selection uses `shared/retrieval/benchmark.py`; run it through `scripts/lib/semantic-retrieval.py benchmark --root . --home <home-directory>`. This warm-model check uses synthetic, repeated short documents. Its result does not measure model startup, first indexing, real code chunks, CLI latency, or memory use; do not use it as an end-to-end performance estimate.
+The A/B benchmark measures whole sessions. Auto selection of local QMD search uses `shared/qmd/qmd-benchmark.mjs`, run through `scripts/lib/qmd.py`. It measures median search latency and embedding throughput on GPU, then CPU, and is not an end-to-end performance estimate.

 ## Checks and tests

 Gitea Actions runs the repository checks from `.gitea/workflows/ci.yml`.

+Doctor captures native-command diagnostics and checks exit codes. A warning on stderr does not abort the
+PowerShell 5.1 script; failed version or configuration checks contribute to the final failure summary.
+On Windows, an unavailable profile-folder lookup falls back to PowerShell's home path.
+
 | Script | Purpose |
 | --- | --- |
 | `checks/validate-config.py` | Validate generated Codex TOML and Claude JSON. |
 | `tests/test-build-validation.ps1`, `tests/test-build-validation.sh` | Validate build failures and generated output. |
 | `tests/test-capabilities.ps1` | Guard PowerShell capability detection. |
 | `tests/test-install-guards.ps1`, `tests/test-install-guards.sh` | Validate install and update guard conditions. |
+| `tests/test-config-effects.py` | Check that generated limits and permissions take effect: Codex keeps the V1 multi-agent implementation that honors `agents.max_depth`; with `AI_CONFIG_LIVE_TESTS=1`, short Haiku sessions confirm that Claude withholds the Agent tool from subagents, refuses subagents above the concurrency limit, and blocks `git reset --hard` in every shell tool. |
 | `tests/test-client-smoke.py` | Install a package into a temporary home with foreign settings and ask the installed Claude and Codex CLIs which skills, agents, and hooks they discover, without completing a model request. Skips a client whose CLI is unavailable unless `AI_CONFIG_REQUIRE_CLIENTS=1`, which the CI `client-smoke` job sets. |
 | `tests/test-install-options.py` | Validate interactive option handling and generated manifest changes. |
 | `tests/test-managed-extensions.py` | Validate plugin, skill, and CLI ownership handling. |
@@ -62,16 +74,64 @@ Gitea Actions runs the repository checks from `.gitea/workflows/ci.yml`.
 | `tests/test-quick-update.py` | Validate saved Quickupdate choices. |
 | `tests/test-remove-customizations.py` | Validate targeted instruction and credential removal without accessing the real credential store. |
 | `tests/test-quick-update.ps1`, `tests/test-quick-update.sh` | Run the Quickupdate test through the relevant shell. |
-| `tests/test-retrieval-server.py` | Validate retrieval indexing, ranking, and optional real-model execution. |
-| `tests/test-semantic-retrieval.py` | Validate retrieval installation and removal. |
+| `tests/test-qmd-lib.mjs`, `test-qmd-daemon.mjs`, `test-qmd-search.mjs`, `test-qmd-warm.mjs`, `test-qmd-benchmark.mjs` | Model-free QMD unit tests; require the YAML dependency. |
+| `tests/test-qmd-integration.mjs` | Manual integration test using real QMD and downloaded models; excluded from CI. |
+| `tests/test-qmd-setup.py` | Validate QMD installation, migration, and removal. |
 | `tests/test-session-state.py` | Validate session-state helpers. |
 | `tests/test-shell-packages.ps1`, `tests/test-shell-packages.sh` | Validate generated package contents and client settings. |
 | `tests/test-runtime-status.ps1`, `tests/test-runtime-status.sh` | Validate build summaries and status-line output. |
 | `tests/test-install-selections.ps1`, `tests/test-install-selections.sh` | Validate dry-run shell and client selections. |
 | `tests/test-command-summaries.ps1`, `tests/test-command-summaries.sh` | Validate doctor, install, and update summary output. |
 | `tests/test-telemetry.py` | Validate telemetry output. |
+| `tests/test-personal-instructions.py` | Validate startup instruction pointers and preservation of personal instruction files. |
 | `tests/test-user-customizations.py` | Validate user instruction overlays and credential helpers. |

+## QMD tests
+
+The CI `qmd` job installs only `yaml@2.9.0` into an isolated directory, sets `QMD_PACKAGE_DIR` to that directory,
+and runs these five files. It does not install QMD or download models. With a complete global QMD installation,
+the same tests resolve YAML from QMD automatically:
+
+```text
+node --test scripts/tests/test-qmd-lib.mjs scripts/tests/test-qmd-daemon.mjs scripts/tests/test-qmd-search.mjs scripts/tests/test-qmd-warm.mjs scripts/tests/test-qmd-benchmark.mjs
+```
+
+Without QMD installed, use the dependency setup from [the CI workflow](../.gitea/workflows/ci.yml).
+`QMD_PACKAGE_DIR` must point to the directory containing the test dependency's `node_modules` directory.
+A missing YAML dependency fails `test-qmd-lib.mjs` before its tests load.
+
+Run the integration test separately, only with a complete QMD installation and resources for model downloads.
+Unset `QMD_CONFIG_DIR` first so the test uses its temporary configuration rather than an inherited user path.
+Clear a unit-test-only `QMD_PACKAGE_DIR` override as well:
+
+```text
+node --test scripts/tests/test-qmd-integration.mjs
+```
+
+The integration test creates a temporary home and repository, downloads models, searches through the daemon,
+and stops it after successful assertions.
+Its temporary data is not automatically removed. `QMD_TEST_CACHE` can select an existing QMD cache parent;
+the test uses its `qmd/` subdirectory, so avoid pointing it at a cache containing unrelated data.
+
+## Session benchmarks
+
+The A/B benchmark runs Python, C#/ASP.NET, and TypeScript tasks under `scripts/benchmarks/tasks/`.
+These are real model sessions and can incur usage charges; `--dry-run` lists planned runs.
+Both arms use the same model and reasoning effort for each client. Preflight records loaded configuration in
+`provenance.json` and normally stops when the arms are not comparable. Reports compare pass rate, rework turns,
+time, tokens, tool calls, cost, and workflow checks per task category.
+
+For Claude's semantic-search comparison, pass these arguments to the shell's benchmark command:
+
+```text
+--clients claude --arms setup setup-no-search --tasks 11-* 12-* 13-* --warm-index
+```
+
+`setup-no-search` is Claude-only. Warm-up starts QMD and indexes the fixture before timing setup-arm sessions.
+The Codex baseline requires a separate login under `--codex-baseline-home`; set `CODEX_HOME` to that path for
+`codex login`. Supply `--codex-model` if the installed configuration does not select a model.
+Benchmark fixture READMEs describe the starting task state and are retained as test inputs.
+
 ## Internal helpers

 | Script | Purpose |
@@ -87,6 +147,6 @@ Gitea Actions runs the repository checks from `.gitea/workflows/ci.yml`.
 | `lib/remove-instruction.py` | Remove an exact client-specific instruction block. |
 | `lib/selection-state.ps1`, `lib/selection-state.sh` | Persist choices used by Quickupdate. |
 | `lib/selection-state.py` | Read and write Quickupdate state. |
-| `lib/semantic-retrieval.ps1`, `lib/semantic-retrieval.sh` | Invoke semantic retrieval from the installation flow. |
-| `lib/semantic-retrieval.py` | Install, index, benchmark, and remove the local retrieval service. |
-| `shared/retrieval/benchmark.py` | Check warm Qwen embedding and reranking speed for Auto selection; not an end-to-end benchmark. |
+| `lib/qmd.sh`, `lib/qmd.ps1` | Invoke local QMD search from the installation flow. |
+| `lib/qmd.py` | Install, migrate, benchmark, and remove local QMD search. |
+| [`shared/qmd/`](../shared/qmd/) (repository root) | Installed QMD scripts: search CLI, daemon, warm-up, benchmark, and shared library. |
@@ -5,20 +5,23 @@ Skills are reusable workflows. Rules are persistent constraints and agents are s
 The current structure is organized by purpose:

 - `planning/`: impact analysis and work-item definition
- `research/`: technical and repository research
+- `research/`: mandatory `research` gate for every search, with technical and repository specialists, plus `semantic-search`, which is installed only while local QMD search is enabled
 - `reviews/`: security, performance, WPF, UI/UX, business, API, and EF Core reviews
 - `implementation/`: SQL, unit-test, and integration-test writing
 - `verification/`: facts and work-item verification
 - `git/`: pull request reviews
 - `content-strategy/`, `copy-editing/`, `copywriting/`: planning, editing, and writing text
- `image/`, `site-architecture/`: visuals and website structure
+- `image/`: image assets, screenshots, SEO and performance, social-preview metadata, practical marketing workflows, design tools, and common mistakes
+- `site-architecture/`: website structure
 - `marketing-psychology/`, `offers/`, `product-marketing/`, `cro/`: audience understanding, value framing, and conversion

 General planning, debugging, code review, and completion verification workflows come from Superpowers, so the catalog does not duplicate their triggers. The remaining skills cover focused domains Superpowers does not.

+The shared `plugin-workflow` skill coordinates automatic plugin use: Superpowers for process, Ponytail for implementation and review, Impeccable for UI, and i-have-adhd with Caveman for responses. Global instructions require it at session start/resume and task or phase changes. It routes to installed skills, preserves explicit opt-outs, and handles missing or manual-only plugins without replacing upstream workflows.
+
 Each skill defines a focused workflow with the investigation, decision points, and output expected for that task. Keep guidance specific to the skill; shared repository constraints belong in the rules.

-The single catalog in `shared/skills/` includes development skills and focused skills for writing, images, content and site structure, positioning, psychology, and conversion. Builds include every retained skill for both clients. Updating a managed installation backs up and removes unchanged setup-owned skills deleted from the catalog; local changes are backed up and retained.
+The single catalog in `shared/skills/` includes development skills and focused skills for writing, image assets, content and site structure, positioning, psychology, and conversion. The image skill has a short core and five focused references loaded only when relevant: optimization, OG metadata, marketing workflows, design tools, and common mistakes. AI-generation guides, model comparisons, prompting recipes, and fixed social-platform size catalogs are omitted. Builds include every retained skill for both clients. Updating a managed installation backs up and removes unchanged setup-owned skills deleted from the catalog; local changes are backed up and retained.

 Claude discovers only `skills/<name>/SKILL.md`, so its generated package flattens the categorized catalog to one directory per skill name, together with the skill's `references/`; the build fails on duplicate names or a `name` that differs from its directory. Claude's package additionally has a `rules-*` skill for each focused rule file or directory in
 `shared/rules/`. The rule-to-skill loading conditions live in `shared/global-instructions.md`, so full rule text loads
@@ -26,6 +29,10 @@ only when Claude invokes a matching skill instead of sitting permanently in cont
 files directly. Both clients embed the general rules in their global instructions.
 Language, framework, library, and security rules use directory indexes plus focused topic files. Their generated Claude skills expose each focused rule separately; the index skills also include the references for contextual lookup. See [Configuration](configuration.md).

-Skills guide a task when needed; their availability does not require a full review, build, or test suite after every
+Every search or lookup must use `research` and the applicable specialist, including direct reads, exact matches, familiar areas, and follow-up queries during implementation or verification. Loaded instructions can be reused; their checks apply to each search. Semantic retrieval runs first for unknown repository identifiers; known identifiers still use direct reads or `rg` within the research workflow. Disabling QMD does not disable the research requirement. These are agent instructions, not a runtime tool interceptor.
+
+Context7 phase checkpoints are defined once in `research/technical-research/SKILL.md`. Focused planning, SQL and test-writing, and verification skills call them explicitly, as do the architect, implementer, and verifier roles. The global rule applies the same checkpoints inside Superpowers and other plugin workflows without modifying upstream plugin caches or duplicating general workflow skills. Planning verifies external assumptions before accepting a design; implementation checks them against actual versions before coding; verification requires both applicable source evidence and proportionate execution results. Evidence travels in the existing plan or handoff and is reused across phases when the behavior, version, and environment match. Queries contain only public, sanitized concepts, use bounded timeouts and refinement, and report source fallback or unresolved gaps explicitly. This enforces an instruction contract; it does not guarantee model compliance or add network calls to builds and tests.
+
+Other skills guide a task when needed; their availability does not require a full review, build, or test suite after every
 change. The shared Verification rules govern proportional checking, including when generic skill workflows call
 for more work than the change needs.
@@ -8,9 +8,14 @@ Arms:
  setup     the installed configuration (CLAUDE.md, settings, plugins, skills, MCP servers).
  baseline  Claude with --setting-sources "" --strict-mcp-config (no user settings, plugins,
            user skills, CLAUDE.md, or MCP servers); Codex with CODEX_HOME set to --codex-baseline-home,
-            an empty home where you ran `codex login` once.
+            an empty home where you ran `codex login` once, with every user and plugin skill disabled.
+
+Both arms of a client use the same pinned model and reasoning effort. Before any run, a preflight
+records what each arm actually loads (model, effort, skills by source, plugins, MCP servers,
+instructions) in <out>/provenance.json and stops if the arms are not comparable.
 """
 import argparse
+import fnmatch
 from concurrent.futures import ThreadPoolExecutor
 import json
 import os
@@ -28,7 +33,8 @@ import time
 TASKS = Path(__file__).resolve().parent / 'tasks'
 CHECK = [sys.executable, '-m', 'unittest', 'discover', '-s', 'bench_hidden', '-t', '.']
 CLAUDE_TOOLS = ['Read', 'Edit', 'Write', 'Glob', 'Grep', 'Agent', 'Skill', 'TodoWrite', 'Bash(python *)', 'Bash(git *)',
-                'Bash(ls *)', 'PowerShell(python *)', 'PowerShell(git *)', 'PowerShell(Get-ChildItem *)']
+                'Bash(ls *)', 'Bash(dotnet *)', 'Bash(node *)', 'PowerShell(python *)', 'PowerShell(git *)', 'PowerShell(Get-ChildItem *)',
+                'PowerShell(dotnet *)', 'PowerShell(node *)']


 def clean_env(**values):
@@ -45,11 +51,15 @@ def kill_tree(process):
    process.wait(timeout=30)


-def run_jsonl(command, cwd, env, timeout):
-    """Run a client, return (events, seconds, timed_out); output is read on a thread so the deadline holds."""
+def run_jsonl(command, cwd, env, timeout, prompt):
+    """Run a client, return (events, seconds, timed_out); output is read on a thread so the deadline holds.
+
+    The prompt goes through stdin: on Windows the clients start through .cmd shims that cut arguments at newlines.
+    """
    start = time.monotonic()
-    process = subprocess.Popen(command, cwd=cwd, env=env, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
+    process = subprocess.Popen(command, cwd=cwd, env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
                               stderr=subprocess.DEVNULL, text=True, encoding='utf-8', errors='replace')
+    threading.Thread(target=lambda: (process.stdin.write(prompt), process.stdin.close()), daemon=True).start()
    lines = queue.Queue()
    threading.Thread(target=lambda: ([lines.put(line) for line in process.stdout], lines.put(None)), daemon=True).start()
    events, timed_out = [], False
@@ -69,14 +79,27 @@ def run_jsonl(command, cwd, env, timeout):
    return events, time.monotonic() - start, timed_out


-def claude_turn(prompt, cwd, arm, model, session, timeout):
-    command = [shutil.which('claude'), '-p', prompt, '--output-format', 'stream-json', '--verbose', '--model', model,
-               '--permission-mode', 'auto', '--allowedTools', *CLAUDE_TOOLS]
+def claude_flags(arm, args):
+    flags = ['--model', args.claude_model, '--effort', args.claude_effort]
    if arm == 'baseline':
-        command += ['--setting-sources', '', '--strict-mcp-config']
+        flags += ['--setting-sources', '', '--strict-mcp-config']
+    if arm == 'setup-no-search':
+        flags += ['--disallowedTools', 'Skill(semantic-search)', 'Bash(*qmd-search*)', 'PowerShell(*qmd-search*)',
+                  '--append-system-prompt', 'The semantic-search skill and the QMD search wrapper are unavailable in this session.']
+    return flags
+
+
+def codex_env(arm, args):
+    return clean_env(CODEX_HOME=str(args.codex_baseline_home)) if arm == 'baseline' else clean_env()
+
+
+def claude_turn(prompt, cwd, arm, args, session):
+    command = [shutil.which('claude'), '-p', '--output-format', 'stream-json', '--verbose',
+               '--permission-mode', 'auto', '--allowedTools', *CLAUDE_TOOLS, *claude_flags(arm, args)]
    if session:
        command += ['--resume', session]
-    events, seconds, timed_out = run_jsonl(command, cwd, clean_env(), timeout)
+    timeout = args.timeout
+    events, seconds, timed_out = run_jsonl(command, cwd, clean_env(), timeout, prompt)
    result = next((event for event in reversed(events) if event.get('type') == 'result'), {})
    usage = result.get('usage', {})
    calls = [block for event in events if event.get('type') == 'assistant'
@@ -89,21 +112,22 @@ def claude_turn(prompt, cwd, arm, model, session, timeout):
        'tool_calls': len(calls), 'agents': sum(call.get('name') == 'Agent' for call in calls),
        'skills': [str(call.get('input', {}).get('skill', '')) for call in calls if call.get('name') == 'Skill'],
        'commands': commands, 'final': str(result.get('result', '')),
+        'models': sorted({str(event['message']['model']) for event in events
+                          if event.get('type') == 'assistant' and event.get('message', {}).get('model')}),
        'error': str(result.get('result', '') or 'no result event')[:300] if result.get('is_error') or not result else '',
    }


-def codex_turn(prompt, cwd, arm, model, session, timeout, baseline_home):
+def codex_turn(prompt, cwd, arm, args, session):
    command = [shutil.which('codex'), 'exec']
    if session:
        command += ['resume', session]
-    command += ['--json', '--skip-git-repo-check', '--sandbox', 'workspace-write']
-    if model:
-        command += ['-m', model]
+    # `exec resume` rejects --sandbox; the config key works for both forms.
+    command += ['--json', '--skip-git-repo-check', '-c', 'sandbox_mode="workspace-write"',
+                '-m', args.codex_model, '-c', f'model_reasoning_effort="{args.codex_effort}"']
    command += ['-C', str(cwd)] if not session else []
-    command.append(prompt)
-    env = clean_env(CODEX_HOME=str(baseline_home)) if arm == 'baseline' else clean_env()
-    events, seconds, timed_out = run_jsonl(command, cwd, env, timeout)
+    command.append('-')
+    events, seconds, timed_out = run_jsonl(command, cwd, codex_env(arm, args), args.timeout, prompt)
    items = [event.get('item', {}) for event in events if event.get('type') == 'item.completed']
    tools = [item for item in items if item.get('type') not in ('agent_message', 'reasoning', 'error')]
    usage = [event.get('usage', {}) for event in events if event.get('type') == 'turn.completed']
@@ -115,16 +139,186 @@ def codex_turn(prompt, cwd, arm, model, session, timeout, baseline_home):
        'tool_calls': len(tools), 'agents': sum(item.get('type') == 'collab_tool_call' for item in tools),
        'skills': [], 'commands': [str(item.get('command', '')) for item in tools if item.get('type') == 'command_execution'],
        'final': next((str(item.get('text', '')) for item in reversed(items) if item.get('type') == 'agent_message'), ''),
+        'models': [args.codex_model],
        'error': next((str(event.get('message', event.get('error', '')))[:300] for event in events if event.get('type') in ('error', 'turn.failed')
-                       and not str(event.get('message', '')).startswith('Reconnecting')), '') if not usage else '',
+                       and not str(event.get('message', '')).startswith('Reconnecting')), 'no turn.completed event') if not usage else '',
    }


+class AppServer:
+    """Minimal JSON-RPC client for `codex app-server`; every wait has a deadline."""
+
+    def __init__(self, env, cwd):
+        self.process = subprocess.Popen([shutil.which('codex'), 'app-server'], cwd=cwd, env=env, stdin=subprocess.PIPE,
+                                        stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding='utf-8')
+        self.lines, self.next_id = queue.Queue(), 0
+        threading.Thread(target=lambda: [self.lines.put(line) for line in self.process.stdout], daemon=True).start()
+        self.call('initialize', {'clientInfo': {'name': 'ai-config-benchmark', 'version': '1'}})
+        self.process.stdin.write(json.dumps({'jsonrpc': '2.0', 'method': 'initialized'}) + '\n')
+
+    def call(self, method, params):
+        self.next_id += 1
+        self.process.stdin.write(json.dumps({'jsonrpc': '2.0', 'id': self.next_id, 'method': method, 'params': params}) + '\n')
+        self.process.stdin.flush()
+        while True:
+            message = json.loads(self.lines.get(timeout=120))
+            if message.get('id') == self.next_id:
+                if 'error' in message:
+                    raise RuntimeError(f'{method}: {message["error"]}')
+                return message['result']
+
+    def close(self):
+        kill_tree(self.process)
+
+
+def codex_configured(env, cwd):
+    server = AppServer(env, cwd)
+    try:
+        return server.call('config/read', {})['config']
+    finally:
+        server.close()
+
+
+def codex_provenance(arm, args, cwd):
+    server = AppServer(codex_env(arm, args), cwd)
+    try:
+        config = server.call('config/read', {})['config']
+        listing = lambda: server.call('skills/list', {'cwds': [str(cwd)], 'forceReload': True})['data'][0]['skills']
+        skills = listing()
+        if arm == 'baseline':
+            # Codex reads ~/.agents/skills from the real profile even with another CODEX_HOME; disable those skills there.
+            for skill in skills:
+                if skill.get('enabled', True) and (skill.get('scope') == 'user' or skill.get('pluginId')):
+                    server.call('skills/config/write', {'path': skill['path'], 'enabled': False})
+            skills = listing()
+    finally:
+        server.close()
+    prompt = subprocess.run([shutil.which('codex'), 'debug', 'prompt-input', '-c', f'model="{args.codex_model}"',
+                             '-c', f'model_reasoning_effort="{args.codex_effort}"', 'provenance probe'],
+                            cwd=cwd, env=codex_env(arm, args), capture_output=True, text=True, encoding='utf-8', timeout=180).stdout
+    setup_agents = Path.home() / '.codex' / 'AGENTS.md'
+    marker = next((line.strip() for line in setup_agents.read_text(encoding='utf-8-sig').splitlines() if line.strip()), '') if setup_agents.is_file() else ''
+    enabled = [skill for skill in skills if skill.get('enabled', True)]
+    return {
+        'model': args.codex_model, 'effort': args.codex_effort,
+        'configured_model': config.get('model'), 'configured_effort': config.get('model_reasoning_effort'),
+        'sandbox_mode': config.get('sandbox_mode'), 'approval_policy': config.get('approval_policy'),
+        'skills_by_scope': {scope: sum(skill.get('scope') == scope and not skill.get('pluginId') for skill in enabled)
+                            for scope in sorted({skill.get('scope') for skill in enabled})},
+        'plugin_skills': sorted(skill['name'] for skill in enabled if skill.get('pluginId')),
+        'user_skills': sorted(skill['name'] for skill in enabled if skill.get('scope') == 'user' and not skill.get('pluginId')),
+        'mcp_servers': sorted(config.get('mcp_servers') or {}),
+        'global_instructions_loaded': bool(marker) and marker in prompt,
+        'prompt_input_tokens_estimate': len(prompt.encode('utf-8')) // 4,
+    }
+
+
+def claude_provenance(arm, args, cwd):
+    claude = shutil.which('claude')
+    process = subprocess.Popen([claude, '-p', 'provenance probe', '--output-format', 'stream-json', '--verbose', *claude_flags(arm, args)],
+                               cwd=cwd, env=clean_env(), stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+                               text=True, encoding='utf-8')
+    lines = queue.Queue()
+    threading.Thread(target=lambda: [lines.put(line) for line in process.stdout], daemon=True).start()
+    try:
+        init = {}
+        while init.get('subtype') != 'init':
+            init = json.loads(lines.get(timeout=180))
+    finally:
+        kill_tree(process)
+    context = json.loads(subprocess.run([claude, '-p', '/context', '--output-format', 'json', *claude_flags(arm, args)], cwd=cwd, env=clean_env(),
+                                        capture_output=True, text=True, encoding='utf-8', timeout=180).stdout).get('result', '')
+
+    def rows(heading):
+        section = re.search(rf'(?ms)^### {re.escape(heading)}\s*$(.*?)(?=^### |\Z)', context)
+        cells = [[cell.strip() for cell in line.strip().strip('|').split('|')] for line in (section.group(1) if section else '').splitlines() if line.startswith('|')]
+        return [row for row in cells[2:] if row and row[0]]
+
+    sources = {}
+    for row in rows('Skills'):
+        source = row[1].split(' (')[0] if len(row) > 1 else '?'
+        sources[source] = sources.get(source, 0) + 1
+    model = re.search(r'\*\*Model:\*\*\s*(\S+)', context)
+    return {
+        'model': init.get('model') or (model.group(1) if model else None), 'effort': args.claude_effort,
+        'permission_mode': init.get('permissionMode'),
+        'skills_by_source': sources, 'skills_listed': len(init.get('skills', [])),
+        'plugins': sorted(plugin.get('name', str(plugin)) if isinstance(plugin, dict) else str(plugin) for plugin in init.get('plugins', [])),
+        'mcp_servers': sorted(server.get('name', str(server)) if isinstance(server, dict) else str(server) for server in init.get('mcp_servers', [])),
+        'memory_files': [row[1] for row in rows('Memory Files') if len(row) > 1],
+    }
+
+
+def preflight(args, clients, arms):
+    """Record what each arm loads and return the problems that make the comparison invalid."""
+    provenance, problems = {}, []
+    with tempfile.TemporaryDirectory(prefix='ai-bench-preflight-', ignore_cleanup_errors=True) as directory:
+        subprocess.run(['git', 'init', '-q'], cwd=directory, check=True, timeout=60)
+        for client in clients:
+            for arm in arms:
+                if client == 'codex' and arm == 'setup-no-search':
+                    continue
+                data = (claude_provenance if client == 'claude' else codex_provenance)(arm, args, Path(directory))
+                provenance[f'{client}/{arm}'] = data
+                if client == 'claude' and arm == 'baseline':
+                    if set(data['skills_by_source']) - {'Built-in'}:
+                        problems.append(f'claude baseline loads non-built-in skills: {data["skills_by_source"]}')
+                    if data['memory_files'] or data['mcp_servers']:
+                        problems.append(f'claude baseline loads memory files {data["memory_files"]} or MCP servers {data["mcp_servers"]}')
+                if client == 'codex' and arm == 'baseline':
+                    if data['user_skills'] or data['plugin_skills']:
+                        problems.append(f'codex baseline still enables user or plugin skills: {data["user_skills"] + data["plugin_skills"]}')
+                    if data['global_instructions_loaded'] or data['mcp_servers']:
+                        problems.append('codex baseline loads the global AGENTS.md or MCP servers')
+            models = {provenance[key]['model'] for key in provenance if key.startswith(client + '/')}
+            if len(models) > 1:
+                problems.append(f'{client} arms resolve to different models: {sorted(models)}')
+    return provenance, problems
+
+
+QMD_SCRIPTS = Path.home() / '.my-ai-configuration/qmd'
+FILLER_TOPICS = [
+    ('statement', 'download', 'Render a statement download for the export queue.'),
+    ('trial', 'banner', 'Show the trial banner text in the marketing header.'),
+    ('upload', 'progress', 'Track upload progress for the dashboard widget.'),
+    ('network', 'status', 'Describe the network status shown in the footer.'),
+    ('invoice', 'label', 'Format the invoice label printed on envelopes.'),
+    ('retry', 'hint', 'Return the retry hint shown next to a failed form field.'),
+    ('cent', 'display', 'Format a cent amount for the price badge.'),
+    ('customer', 'greeting', 'Pick the greeting for a customer newsletter.'),
+]
+
+
+def generate_filler(work, count):
+    """Write deterministic distractor modules that share vocabulary with the task prompts but not their logic."""
+    for number in range(count):
+        noun, verb, doc = FILLER_TOPICS[number % len(FILLER_TOPICS)]
+        name = f'{noun}_{verb}_{number:03d}'
+        path = work / 'app' / 'modules' / f'{name}.py'
+        path.parent.mkdir(parents=True, exist_ok=True)
+        body = [f'def {name}(value, locale="en"):', f'    """{doc}"""', '    text = str(value).strip()',
+                f'    return f"{{locale}}:{noun}:{verb}:{{text}}"', '']
+        path.write_text('\n'.join(body), encoding='utf-8')
+    (work / 'app' / 'modules' / '__init__.py').write_text('', encoding='utf-8')
+
+
+def warm_index(work):
+    """Index the fixture and start the QMD daemon before the session, as in a repository that was searched before."""
+    script = QMD_SCRIPTS / 'qmd-warm.mjs'
+    if script.is_file():
+        subprocess.run(['node', str(script), '--root', str(work)], capture_output=True, timeout=1800)
+
+
 def check(work, task):
    hidden = work / 'bench_hidden'
    shutil.rmtree(hidden, ignore_errors=True)
    shutil.copytree(task / 'hidden', hidden)
-    result = subprocess.run(CHECK, cwd=work, capture_output=True, text=True, timeout=300)
+    spec = json.loads((task / 'task.json').read_text(encoding='utf-8'))
+    command = CHECK
+    if spec.get('check'):
+        program, *arguments = spec['check']
+        command = [sys.executable if program == 'python' else shutil.which(program) or program, *arguments]
+    result = subprocess.run(command, cwd=work, capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=600)
    shutil.rmtree(hidden, ignore_errors=True)
    return result.returncode == 0, (result.stdout + result.stderr)[-3000:]

@@ -152,14 +346,15 @@ def run_one(job, args):
    with tempfile.TemporaryDirectory(prefix=f'ai-bench-{task.name[:2]}-', ignore_cleanup_errors=True) as directory:
        work = Path(directory)
        shutil.copytree(task / 'repo', work, dirs_exist_ok=True)
+        if spec.get('generate', {}).get('filler_modules'):
+            generate_filler(work, spec['generate']['filler_modules'])
        for git in (['init', '-q'], ['add', '-A'], ['-c', 'user.name=bench', '-c', 'user.email=bench@example.invalid', 'commit', '-qm', 'fixture']):
            subprocess.run(['git', '-c', 'core.autocrlf=false', *git], cwd=work, check=True, timeout=60)
+        if args.warm_index and arm == 'setup':
+            warm_index(work)
        turns, prompt, session = [], spec['prompt'], None
        for round_number in range(1 + args.rework):
-            if client == 'claude':
-                turn = claude_turn(prompt, work, arm, args.claude_model, session, args.timeout)
-            else:
-                turn = codex_turn(prompt, work, arm, args.codex_model, session, args.timeout, args.codex_baseline_home)
+            turn = (claude_turn if client == 'claude' else codex_turn)(prompt, work, arm, args, session)
            turns.append(turn)
            session = turn['session']
            if turn['error']:
@@ -180,6 +375,9 @@ def run_one(job, args):
        'cost_usd': round(sum(turn['cost_usd'] for turn in turns), 4), 'tool_calls': sum(turn['tool_calls'] for turn in turns),
        'agents': sum(turn['agents'] for turn in turns), 'skills': [skill for turn in turns for skill in turn['skills']],
        'commands': [command for turn in turns for command in turn['commands']],
+        'models': sorted({model for turn in turns for model in turn['models']}),
+        'searches': sum('qmd-search' in command for turn in turns for command in turn['commands'])
+                    + sum(skill == 'semantic-search' for turn in turns for skill in turn['skills']),
        'timed_out': any(turn['timed_out'] for turn in turns), 'workflow_kind': spec['workflow'].get('kind'),
        'workflow_violations': workflow_violations(spec['workflow'], turns), 'check_output': '' if passed else output,
    }
@@ -188,14 +386,18 @@ def run_one(job, args):
 def summarize(results):
    errors = [result for result in results if result.get('error')]
    results = [result for result in results if not result.get('error')]
-    lines = [f'Excluded {len(errors)} runs that ended with a client or API error (for example a usage limit).', '','| client | arm | runs | pass | first try | rework turns | median s | median input tok | median output tok | median tool calls | cost USD | workflow ok |',
-             '|---|---|---|---|---|---|---|---|---|---|---|---|']
+    lines = [f'Excluded {len(errors)} runs that ended with a client or API error (for example a usage limit).',
+             'Rows are per task category; an overall average would hide a category where one arm is worse.', '',
+             '| category | client | arm | runs | pass | first try | rework turns | median s | median input tok | median output tok | median tool calls | cost USD | workflow ok |',
+             '|---|---|---|---|---|---|---|---|---|---|---|---|---|']
    groups = {}
    for result in results:
-        groups.setdefault((result['client'], result['arm']), []).append(result)
-    for (client, arm), runs in sorted(groups.items()):
+        spec = TASKS / result['task'] / 'task.json'
+        category = json.loads(spec.read_text(encoding='utf-8')).get('category', '?') if spec.is_file() else '?'
+        groups.setdefault((category, result['client'], result['arm']), []).append(result)
+    for (category, client, arm), runs in sorted(groups.items()):
        median = lambda key: statistics.median(run[key] for run in runs)
-        lines.append(f'| {client} | {arm} | {len(runs)} | {sum(run["passed"] for run in runs) / len(runs):.0%} | '
+        lines.append(f'| {category} | {client} | {arm} | {len(runs)} | {sum(run["passed"] for run in runs) / len(runs):.0%} | '
                     f'{sum(run["first_try"] for run in runs) / len(runs):.0%} | {sum(run["rework_turns"] for run in runs)} | '
                     f'{median("seconds"):.0f} | {median("input_tokens"):.0f} | {median("output_tokens"):.0f} | {median("tool_calls"):.0f} | '
                     f'{sum(run["cost_usd"] for run in runs):.2f} | {sum(not run["workflow_violations"] for run in runs) / len(runs):.0%} |')
@@ -209,15 +411,20 @@ def summarize(results):
 def main():
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0], formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__)
    parser.add_argument('--clients', nargs='+', choices=('claude', 'codex'), default=['claude', 'codex'])
-    parser.add_argument('--arms', nargs='+', choices=('setup', 'baseline'), default=['setup', 'baseline'])
-    parser.add_argument('--tasks', nargs='+', help='task directory names (default: all)')
+    parser.add_argument('--arms', nargs='+', choices=('setup', 'baseline', 'setup-no-search'), default=['setup', 'baseline'],
+                        help='setup-no-search is the setup with the semantic-search skill and CLI blocked (Claude only)')
+    parser.add_argument('--warm-index', action='store_true', help='start the QMD daemon and index the fixture before setup-arm sessions, outside the timing')
+    parser.add_argument('--tasks', nargs='+', help='task directory names or patterns such as 11-* (default: all)')
    parser.add_argument('--repetitions', type=int, default=3)
    parser.add_argument('--first-repetition', type=int, default=1, help='number of the first repetition, to rerun selected repetitions')
    parser.add_argument('--rework', type=int, default=1, help='rework turns after a failed check')
    parser.add_argument('--jobs', type=int, default=2)
    parser.add_argument('--timeout', type=int, default=900, help='seconds per client turn')
    parser.add_argument('--claude-model', default='sonnet')
-    parser.add_argument('--codex-model', help='default: the CLI default, identical for both arms')
+    parser.add_argument('--claude-effort', default='medium', choices=('low', 'medium', 'high', 'xhigh', 'max'))
+    parser.add_argument('--codex-model', help="default: the setup's configured model, pinned for both arms")
+    parser.add_argument('--codex-effort', help="default: the setup's configured reasoning effort, pinned for both arms")
+    parser.add_argument('--allow-unisolated', action='store_true', help='run even when the preflight finds the arms not comparable')
    parser.add_argument('--codex-baseline-home', type=Path, default=Path.home() / '.my-ai-configuration/benchmark/codex-home')
    parser.add_argument('--out', type=Path, default=Path(tempfile.gettempdir()) / f'ai-config-ab-{time.strftime("%Y%m%d-%H%M%S")}')
    parser.add_argument('--dry-run', action='store_true', help='list the runs without starting clients')
@@ -234,14 +441,30 @@ def main():
                    merged[key] = result
        print(summarize(list(merged.values())))
        return 0
-    tasks = [TASKS / name for name in args.tasks] if args.tasks else sorted(path for path in TASKS.iterdir() if path.is_dir())
+    tasks = [path for path in sorted(TASKS.iterdir()) if path.is_dir() and (not args.tasks or any(fnmatch.fnmatch(path.name, pattern) for pattern in args.tasks))]
    for client in args.clients:
        if not shutil.which(client):
            parser.error(f'{client} CLI unavailable')
    if 'codex' in args.clients and 'baseline' in args.arms and not (args.codex_baseline_home / 'auth.json').is_file():
        parser.error(f'Codex baseline needs a login: run CODEX_HOME="{args.codex_baseline_home}" codex login')
    jobs = [(client, arm, task, repetition) for repetition in range(args.first_repetition, args.first_repetition + args.repetitions)
-            for task in tasks for client in args.clients for arm in args.arms]
+            for task in tasks for client in args.clients for arm in args.arms if not (client == 'codex' and arm == 'setup-no-search')]
+    if 'codex' in args.clients and not (args.codex_model and args.codex_effort):
+        configured = codex_configured(clean_env(), Path.cwd())
+        args.codex_model = args.codex_model or configured.get('model')
+        args.codex_effort = args.codex_effort or configured.get('model_reasoning_effort') or 'medium'
+        if not args.codex_model:
+            parser.error('the setup configures no Codex model; pass --codex-model')
+    provenance, problems = preflight(args, args.clients, args.arms)
+    args.out.mkdir(parents=True, exist_ok=True)
+    (args.out / 'provenance.json').write_text(json.dumps({'provenance': provenance, 'problems': problems}, indent=2), encoding='utf-8')
+    for key, data in provenance.items():
+        print(f'{key}: model={data["model"]} effort={data["effort"]} ' + ' '.join(f'{name}={value}' for name, value in data.items()
+                                                                                if name in ('skills_by_source', 'skills_by_scope', 'plugins', 'mcp_servers')))
+    for problem in problems:
+        print(f'NOT COMPARABLE: {problem}')
+    if problems and not args.allow_unisolated:
+        return 2
    print(f'{len(jobs)} runs -> {args.out}')
    if args.dry_run:
        for client, arm, task, repetition in jobs:
@@ -43,7 +43,8 @@ def skill_names(root):


 def tokens(text):
-    text = text.strip().lstrip('~')
+    # Claude prints "< 20" for small nonzero counts; count it as its upper bound.
+    text = text.strip().lstrip('~<').strip()
    if text in ('', '-'):
        return 0
    return round(float(text[:-1]) * 1000) if text.endswith('k') else round(float(text))
@@ -1,4 +1,5 @@
 {
+  "category": "small change",
  "prompt": "Change the default request timeout from 30 to 60 seconds.",
  "workflow": {
    "kind": "small change without planning ceremony",
@@ -1,4 +1,5 @@
 {
+  "category": "small change",
  "prompt": "Users report that the last item is missing on the final page returned by paginate(). Fix the bug.",
  "workflow": {
    "kind": "bugfix with targeted verification",
@@ -1,4 +1,5 @@
 {
+  "category": "larger implementation",
  "prompt": "Implement the three independent parsers in app/parsers (csv_parser, json_parser, ini_parser) according to their docstrings, and add unit tests for each. They share no code.",
  "workflow": {
    "kind": "larger change with justified delegation",
@@ -1,4 +1,5 @@
 {
+  "category": "small change",
  "prompt": "find_user() fails for user names that contain an apostrophe, such as O'Brien. Fix it.",
  "workflow": {
    "kind": "security-relevant bugfix"
@@ -1,4 +1,5 @@
 {
+  "category": "larger implementation",
  "prompt": "Add unittest-based unit tests for app/slug.py under tests/ that cover its edge cases.",
  "workflow": {
    "kind": "test writing"
@@ -1,4 +1,5 @@
 {
+  "category": "larger implementation",
  "prompt": "Remove the duplicated formatting logic in app/report.py without changing its output.",
  "workflow": {
    "kind": "behavior-preserving refactor"
@@ -1,4 +1,5 @@
 {
+  "category": "small change",
  "prompt": "save_settings() loses keys it does not know about when it updates the settings file. Fix it so unknown keys survive.",
  "workflow": {
    "kind": "data-preserving bugfix"
@@ -1,4 +1,5 @@
 {
+  "category": "small change",
  "prompt": "Rename the retries parameter of app.api.fetch to max_retries.",
  "workflow": {
    "kind": "API change with directly affected documentation"
@@ -1,4 +1,5 @@
 {
+  "category": "small change",
  "prompt": "Make read_upload() safe against path traversal. Legitimate names in nested folders must keep working.",
  "workflow": {
    "kind": "security hardening"
@@ -1,4 +1,5 @@
 {
+  "category": "small change",
  "prompt": "dedupe() is far too slow for 100,000 items. Make it fast while keeping its behavior and the order of first occurrences.",
  "workflow": {
    "kind": "performance fix"
@@ -0,0 +1,14 @@
+import unittest
+from datetime import date
+from app.accounts import Account
+from app.ledger.archive import render_period_summary
+
+
+class Hidden(unittest.TestCase):
+    def test_expired_evaluation_blocked(self):
+        with self.assertRaises(PermissionError):
+            render_period_summary(Account('evaluation', date(2026, 1, 1)), '2026-01', today=date(2026, 2, 1))
+
+    def test_running_evaluation_and_paid_allowed(self):
+        self.assertIsInstance(render_period_summary(Account('evaluation', date(2026, 3, 1)), '2026-01', today=date(2026, 2, 1)), bytes)
+        self.assertIsInstance(render_period_summary(Account('paid'), '2026-01', today=date(2026, 2, 1)), bytes)
@@ -0,0 +1,9 @@
+from dataclasses import dataclass, field
+from datetime import date
+
+
+@dataclass
+class Account:
+    tier: str  # "evaluation" or "paid"
+    evaluation_until: date | None = None
+    entries: list = field(default_factory=list)
@@ -0,0 +1,8 @@
+from datetime import date
+
+
+def render_period_summary(account, period, today=None):
+    """Build the period summary document for an account."""
+    today = today or date.today()
+    lines = [f"{entry.label}: {entry.amount:.2f}" for entry in account.entries if entry.period == period]
+    return "\n".join(lines).encode()
@@ -0,0 +1,10 @@
+{
+  "category": "search",
+  "prompt": "Customers whose free trial has ended can still download their monthly statements. Block that by raising PermissionError, and keep it working for paying customers and for customers whose trial is still running.",
+  "generate": {
+    "filler_modules": 250
+  },
+  "workflow": {
+    "kind": "concept search in a large repository"
+  }
+}
@@ -0,0 +1,32 @@
+import unittest
+from app.transport.courier import dispatch
+
+
+class Channel:
+    def __init__(self, failures, error=ConnectionResetError):
+        self.failures, self.error, self.calls = failures, error, 0
+
+    def send(self, blob):
+        self.calls += 1
+        if self.calls <= self.failures:
+            raise self.error('flaky')
+        return 'receipt'
+
+
+class Hidden(unittest.TestCase):
+    def test_retries_transient(self):
+        channel = Channel(2)
+        self.assertEqual(dispatch(b'x', channel), 'receipt')
+        self.assertEqual(channel.calls, 3)
+
+    def test_gives_up_after_three(self):
+        channel = Channel(5)
+        with self.assertRaises(ConnectionResetError):
+            dispatch(b'x', channel)
+        self.assertEqual(channel.calls, 3)
+
+    def test_no_retry_for_other_errors(self):
+        channel = Channel(1, ValueError)
+        with self.assertRaises(ValueError):
+            dispatch(b'x', channel)
+        self.assertEqual(channel.calls, 1)
@@ -0,0 +1,3 @@
+def dispatch(blob, channel):
+    """Hand a blob to the channel and return the receipt."""
+    return channel.send(blob)
@@ -0,0 +1,10 @@
+{
+  "category": "search",
+  "prompt": "Fix the upload code: uploads that fail with a temporary network error are never retried. They should make at most three attempts in total before giving up with the last error; other errors must not be retried.",
+  "generate": {
+    "filler_modules": 250
+  },
+  "workflow": {
+    "kind": "concept search in a large repository"
+  }
+}
@@ -0,0 +1,10 @@
+import unittest
+from app.fin.tally import consolidate
+
+
+class Hidden(unittest.TestCase):
+    def test_half_up(self):
+        self.assertEqual(float(consolidate([1.005])), 1.01)
+        self.assertEqual(float(consolidate([2.675])), 2.68)
+        self.assertEqual(float(consolidate([1.0, 0.004])), 1.0)
+        self.assertEqual(float(consolidate([0.1, 0.2])), 0.3)
@@ -0,0 +1,3 @@
+def consolidate(lines):
+    """Sum line amounts and return the figure for the document footer."""
+    return round(sum(lines), 2)
@@ -0,0 +1,10 @@
+{
+  "category": "search",
+  "prompt": "Invoice totals are sometimes one cent too low, for example 1.005 shows as 1.00. Round half amounts up to the next cent.",
+  "generate": {
+    "filler_modules": 250
+  },
+  "workflow": {
+    "kind": "concept search in a large repository"
+  }
+}
@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+    <ProjectReference Include="..\..\src\Shop\Shop.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,24 @@
+using System.Net;
+using System.Text;
+using Microsoft.AspNetCore.Hosting.Server;
+using Microsoft.AspNetCore.Hosting.Server.Features;
+using Microsoft.Extensions.DependencyInjection;
+
+var app = Shop.AppHost.Build(new[] { "--urls", "http://127.0.0.1:0" });
+await app.StartAsync();
+var address = app.Services.GetRequiredService<IServer>().Features.Get<IServerAddressesFeature>()!.Addresses.First();
+using var client = new HttpClient { BaseAddress = new Uri(address) };
+var failures = new List<string>();
+async Task Expect(string json, int status)
+{
+    var response = await client.PostAsync("/orders", new StringContent(json, Encoding.UTF8, "application/json"));
+    if ((int)response.StatusCode != status) failures.Add($"{json} -> {(int)response.StatusCode}, expected {status}");
+    else if (status == 400 && response.Content.Headers.ContentType?.MediaType != "application/problem+json") failures.Add($"{json} -> 400 without problem details");
+}
+await Expect("{\"sku\":\"A1\",\"quantity\":2}", 201);
+await Expect("{\"sku\":\"A1\",\"quantity\":0}", 400);
+await Expect("{\"sku\":\"A1\",\"quantity\":-3}", 400);
+await Expect("{\"sku\":\"\",\"quantity\":1}", 400);
+await app.StopAsync();
+foreach (var failure in failures) Console.Error.WriteLine("FAIL " + failure);
+return failures.Count == 0 ? 0 : 1;
@@ -0,0 +1,20 @@
+namespace Shop;
+
+public static class AppHost
+{
+    // Integration tests start the application through Build.
+    public static WebApplication Build(string[] args)
+    {
+        var builder = WebApplication.CreateBuilder(args);
+        var app = builder.Build();
+        var orders = new List<Order>();
+        app.MapPost("/orders", (Order order) =>
+        {
+            orders.Add(order);
+            return Results.Created($"/orders/{orders.Count}", order);
+        });
+        return app;
+    }
+}
+
+public record Order(string Sku, int Quantity);
@@ -0,0 +1 @@
+Shop.AppHost.Build(args).Run();
@@ -0,0 +1,7 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+</Project>
@@ -0,0 +1,14 @@
+{
+  "category": "larger implementation",
+  "prompt": "POST /orders accepts orders with a zero or negative quantity and orders with an empty SKU. Reject those with HTTP 400 and a validation problem response; valid orders must still return 201.",
+  "check": [
+    "dotnet",
+    "run",
+    "--project",
+    "bench_hidden/Check",
+    "--nologo"
+  ],
+  "workflow": {
+    "kind": "C#/ASP.NET change"
+  }
+}
@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Reports\Reports.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,20 @@
+using System.Diagnostics;
+using Reports;
+
+var failures = new List<string>();
+var builder = new ReportBuilder();
+var complete = await builder.BuildAsync(new[] { "a", "b" });
+if (complete != "## a\n## b") failures.Add($"unexpected output {complete}");
+using var source = new CancellationTokenSource(TimeSpan.FromMilliseconds(150));
+var watch = Stopwatch.StartNew();
+try
+{
+    await builder.BuildAsync(Enumerable.Range(0, 50).Select(number => number.ToString()), source.Token);
+    failures.Add("no cancellation");
+}
+catch (OperationCanceledException)
+{
+    if (watch.ElapsedMilliseconds > 1000) failures.Add($"cancelled only after {watch.ElapsedMilliseconds} ms");
+}
+foreach (var failure in failures) Console.Error.WriteLine("FAIL " + failure);
+return failures.Count == 0 ? 0 : 1;
@@ -0,0 +1,15 @@
+namespace Reports;
+
+public sealed class ReportBuilder
+{
+    public async Task<string> BuildAsync(IEnumerable<string> sections, CancellationToken cancellationToken = default)
+    {
+        var parts = new List<string>();
+        foreach (var section in sections)
+        {
+            await Task.Delay(100);
+            parts.Add($"## {section}");
+        }
+        return string.Join("\n", parts);
+    }
+}
@@ -0,0 +1,7 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+</Project>
@@ -0,0 +1,14 @@
+{
+  "category": "larger implementation",
+  "prompt": "Cancelling a report build does nothing: BuildAsync keeps running until every section is rendered. Make it honor cancellation promptly by throwing OperationCanceledException.",
+  "check": [
+    "dotnet",
+    "run",
+    "--project",
+    "bench_hidden/Check",
+    "--nologo"
+  ],
+  "workflow": {
+    "kind": "C#/ASP.NET change"
+  }
+}
@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+    <ProjectReference Include="..\..\src\Crm\Crm.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,18 @@
+using System.Net;
+using System.Text;
+using Microsoft.AspNetCore.Hosting.Server;
+using Microsoft.AspNetCore.Hosting.Server.Features;
+using Microsoft.Extensions.DependencyInjection;
+
+var app = Crm.AppHost.Build(new[] { "--urls", "http://127.0.0.1:0" });
+await app.StartAsync();
+var address = app.Services.GetRequiredService<IServer>().Features.Get<IServerAddressesFeature>()!.Addresses.First();
+using var client = new HttpClient { BaseAddress = new Uri(address) };
+var failures = new List<string>();
+var known = await client.GetAsync("/customers/1");
+if (known.StatusCode != HttpStatusCode.OK || !(await known.Content.ReadAsStringAsync()).Contains("Ada")) failures.Add($"known customer -> {(int)known.StatusCode}");
+var unknown = await client.GetAsync("/customers/42");
+if (unknown.StatusCode != HttpStatusCode.NotFound) failures.Add($"unknown customer -> {(int)unknown.StatusCode}");
+await app.StopAsync();
+foreach (var failure in failures) Console.Error.WriteLine("FAIL " + failure);
+return failures.Count == 0 ? 0 : 1;
@@ -0,0 +1,16 @@
+namespace Crm;
+
+public static class AppHost
+{
+    // Integration tests start the application through Build.
+    public static WebApplication Build(string[] args)
+    {
+        var builder = WebApplication.CreateBuilder(args);
+        var app = builder.Build();
+        var customers = new Dictionary<int, Customer> { [1] = new(1, "Ada") };
+        app.MapGet("/customers/{id:int}", (int id) => customers[id]);
+        return app;
+    }
+}
+
+public record Customer(int Id, string Name);
@@ -0,0 +1,7 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+</Project>
@@ -0,0 +1 @@
+Crm.AppHost.Build(args).Run();
@@ -0,0 +1,14 @@
+{
+  "category": "small change",
+  "prompt": "Requesting an unknown customer with GET /customers/{id} returns HTTP 500. Return 404 instead, and keep known customers working.",
+  "check": [
+    "dotnet",
+    "run",
+    "--project",
+    "bench_hidden/Check",
+    "--nologo"
+  ],
+  "workflow": {
+    "kind": "C#/ASP.NET change"
+  }
+}
@@ -0,0 +1,14 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { overlaps } from '../src/booking.ts';
+
+test('back-to-back bookings do not overlap', () => {
+  assert.equal(overlaps({ start: 9, end: 10 }, { start: 10, end: 11 }), false);
+  assert.equal(overlaps({ start: 10, end: 11 }, { start: 9, end: 10 }), false);
+});
+
+test('real overlaps are detected', () => {
+  assert.equal(overlaps({ start: 9, end: 11 }, { start: 10, end: 12 }), true);
+  assert.equal(overlaps({ start: 9, end: 12 }, { start: 10, end: 11 }), true);
+  assert.equal(overlaps({ start: 9, end: 10 }, { start: 11, end: 12 }), false);
+});
@@ -0,0 +1,5 @@
+{
+  "name": "booking",
+  "type": "module",
+  "private": true
+}
@@ -0,0 +1,8 @@
+export interface Booking {
+  start: number;
+  end: number;
+}
+
+export function overlaps(a: Booking, b: Booking): boolean {
+  return a.start <= b.end && b.start <= a.end;
+}
@@ -0,0 +1,14 @@
+{
+  "category": "small change",
+  "prompt": "Back-to-back bookings, where one ends exactly when the next starts, are wrongly reported as overlapping. Fix overlaps() without breaking real overlaps.",
+  "check": [
+    "node",
+    "--experimental-strip-types",
+    "--no-warnings",
+    "--test",
+    "bench_hidden/check.test.ts"
+  ],
+  "workflow": {
+    "kind": "TypeScript change"
+  }
+}
@@ -0,0 +1,17 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mergeConfig } from '../src/config.ts';
+
+test('nested objects merge deeply', () => {
+  const base = { server: { host: 'a', port: 1, tls: { on: true } }, tags: ['x'] };
+  const override = { server: { port: 2, tls: { cert: 'c' } }, tags: ['y', 'z'] };
+  assert.deepEqual(mergeConfig(base, override), { server: { host: 'a', port: 2, tls: { on: true, cert: 'c' } }, tags: ['y', 'z'] });
+});
+
+test('inputs are not mutated', () => {
+  const base = { a: { b: 1 } };
+  const override = { a: { c: 2 } };
+  mergeConfig(base, override);
+  assert.deepEqual(base, { a: { b: 1 } });
+  assert.deepEqual(override, { a: { c: 2 } });
+});
@@ -0,0 +1,5 @@
+{
+  "name": "config",
+  "type": "module",
+  "private": true
+}
@@ -0,0 +1,5 @@
+export type Config = { [key: string]: unknown };
+
+export function mergeConfig(base: Config, override: Config): Config {
+  return { ...base, ...override };
+}
@@ -0,0 +1,14 @@
+{
+  "category": "larger implementation",
+  "prompt": "mergeConfig() drops nested settings from the base configuration when the override sets only some keys of a nested object. Merge nested objects deeply; arrays from the override replace base arrays, and neither input may be mutated.",
+  "check": [
+    "node",
+    "--experimental-strip-types",
+    "--no-warnings",
+    "--test",
+    "bench_hidden/check.test.ts"
+  ],
+  "workflow": {
+    "kind": "TypeScript change"
+  }
+}
@@ -0,0 +1,18 @@
+import { test, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { debounce } from '../src/debounce.ts';
+
+test('trailing call uses the latest arguments', () => {
+  mock.timers.enable({ apis: ['setTimeout'] });
+  const calls: number[][] = [];
+  const run = debounce((value: number) => calls.push([value]), 50);
+  run(1); run(2); run(3);
+  mock.timers.tick(49);
+  assert.deepEqual(calls, []);
+  mock.timers.tick(1);
+  assert.deepEqual(calls, [[3]]);
+  run(4);
+  mock.timers.tick(50);
+  assert.deepEqual(calls, [[3], [4]]);
+  mock.timers.reset();
+});
@@ -0,0 +1,5 @@
+{
+  "name": "timing",
+  "type": "module",
+  "private": true
+}
@@ -0,0 +1,15 @@
+export function debounce<T extends unknown[]>(fn: (...args: T) => void, wait: number): (...args: T) => void {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let pending: T | undefined;
+  return (...args: T) => {
+    if (pending === undefined) {
+      pending = args;
+    }
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      const call = pending as T;
+      pending = undefined;
+      fn(...call);
+    }, wait);
+  };
+}
@@ -0,0 +1,14 @@
+{
+  "category": "small change",
+  "prompt": "debounce() calls the wrapped function with the arguments of the first call in a burst instead of the last one. Fix it so the trailing call uses the latest arguments.",
+  "check": [
+    "node",
+    "--experimental-strip-types",
+    "--no-warnings",
+    "--test",
+    "bench_hidden/check.test.ts"
+  ],
+  "workflow": {
+    "kind": "TypeScript change"
+  }
+}
@@ -19,5 +19,7 @@ foreach ($target in $(if ($Client -eq 'Both') { @('codex','claude') } else { @($
    $path = Join-Path $directory "$target.md"
    $prefix = if ((Test-Path -LiteralPath $path) -and (Get-Item -LiteralPath $path).Length -gt 0 -and -not (Get-Content -LiteralPath $path -Raw).EndsWith([Environment]::NewLine)) { [Environment]::NewLine } else { '' }
    [System.IO.File]::AppendAllText($path, $prefix + $Instruction.TrimEnd() + [Environment]::NewLine, [System.Text.UTF8Encoding]::new($false))
+    & python (Join-Path $root 'scripts/lib/personal_instructions.py') --home $HomePath --client $target
+    if ($LASTEXITCODE -ne 0) { throw 'Could not refresh the personal instruction rule.' }
    Write-Output "Instruction added for $target."
 }
@@ -33,10 +33,14 @@ if [ -z "${instruction//[[:space:]]/}" ] || [ ${#instruction} -gt 65536 ]; then
 case "$home_path" in /*|[A-Za-z]:[\\/]*) ;; *) printf 'Home path must be absolute.\n' >&2; exit 1 ;; esac

 directory="$home_path/.my-ai-configuration/instructions"
+script_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+python_command=$(command -v python || command -v python3 || true)
+[ -n "$python_command" ] || { printf 'Python is required to add instructions.\n' >&2; exit 1; }
 mkdir -p -- "$directory"
 for target in "${targets[@]}"; do
  path="$directory/$target.md"
  [ ! -s "$path" ] || [ "$(tail -c 1 -- "$path" | wc -l)" -eq 1 ] || printf '\n' >> "$path"
  printf '%s\n' "$instruction" >> "$path"
+  "$python_command" "$script_dir/../lib/personal_instructions.py" --home "$home_path" --client "$target"
  printf 'Instruction added for %s.\n' "$target"
 done
@@ -3,7 +3,11 @@ param([switch]$Summary)
 $ErrorActionPreference = 'Stop'
 $root = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
 $shared = Join-Path $root 'shared'
-$output = Join-Path $root 'generated'
+$final = Join-Path $root 'generated'
+# Keep the name short: it lengthens every generated path, and Windows PowerShell 5.1 fails beyond 260 characters.
+$output = Join-Path $root ("generated.build-ps$PID-" + [Guid]::NewGuid().ToString('N').Substring(0, 6))
+# A trap covers the whole script scope, so every terminating error discards this run's tree.
+trap { Remove-Item -LiteralPath $output -Recurse -Force -ErrorAction SilentlyContinue; break }
 $sandboxSupported = [Environment]::OSVersion.Platform -eq [PlatformID]::Unix
 if ($sandboxSupported) {
    $kernel = (& uname -r 2>$null | Out-String).Trim()
@@ -32,8 +36,16 @@ foreach ($entry in @(Import-Csv -LiteralPath $capabilityManifest -Delimiter ([ch
    $agentTools[$entry.role] = $entry.tools
 }

-Remove-Item $output -Recurse -Force -ErrorAction SilentlyContinue
-New-Item $output -ItemType Directory -Force | Out-Null
+# Build into a private sibling directory and swap it into place only after validation, so a failed
+# or parallel build never leaves generated/ partial. Leftovers of crashed runs are removed here:
+# old trees always, build trees only when their PowerShell owner process has exited.
+# ponytail: Bash-owned leftovers are left to the Bash build, since PIDs are not comparable across shells.
+foreach ($leftover in @(Get-ChildItem -LiteralPath $root -Directory -Filter 'generated.*')) {
+    if ($leftover.Name -like 'generated.old-*' -or ($leftover.Name -match '^generated\.build-ps(\d+)-' -and -not (Get-Process -Id ([int]$Matches[1]) -ErrorAction SilentlyContinue))) {
+        Remove-Item -LiteralPath $leftover.FullName -Recurse -Force -ErrorAction SilentlyContinue
+    }
+}
+New-Item $output -ItemType Directory | Out-Null

 function Copy-Directory($source, $destination) {
    New-Item $destination -ItemType Directory -Force | Out-Null
@@ -190,17 +202,15 @@ foreach ($shell in @('powershell','bash')) {
        $script = if ($shell -eq 'powershell') { 'flashbang.ps1' } else { 'flashbang.sh' }
        $statusLineScript = if ($shell -eq 'powershell') { 'statusline.ps1' } else { 'statusline.sh' }
        $content = Get-Content -LiteralPath $path -Raw
-        $denyRules = if ($shell -eq 'powershell') {
-            @('PowerShell(git reset --hard*)','PowerShell(git clean*)','PowerShell(Remove-Item *-Recurse*)')
-        } else {
-            @('Bash(git reset --hard*)','Bash(git clean*)','Bash(rm -rf*)')
-        }
+        # Claude can offer both shell tools on Windows, so every package denies the destructive commands in both.
+        $denyRules = @('PowerShell(git reset --hard*)','PowerShell(git clean*)','PowerShell(Remove-Item *-Recurse*)','Bash(git reset --hard*)','Bash(git clean*)','Bash(rm -rf*)')
        $denyRulesJson = ConvertTo-Json -InputObject $denyRules -Compress
        $shellTool = if ($shell -eq 'powershell') { 'PowerShell' } else { 'Bash' }
        $allowRulesJson = ConvertTo-Json -InputObject @('Agent', "$shellTool(mcporter call context7.*)") -Compress
        $compactScript = if ($shell -eq 'powershell') { 'Record-Compact.ps1' } else { 'record-compact.sh' }
        $pointerScript = if ($shell -eq 'powershell') { 'Show-SessionStatePointer.ps1' } else { 'show-session-state-pointer.sh' }
-        $content = $content.Replace('__HOOK_COMMAND__', $command).Replace('__POWERSHELL_HOOK_COMMAND__', $command).Replace('__HOOK_SCRIPT__', $script).Replace('__POWERSHELL_HOOK_SCRIPT__', $script).Replace('__COMPACT_SCRIPT__', $compactScript).Replace('__SESSION_POINTER_SCRIPT__', $pointerScript).Replace('__STATUSLINE_COMMAND__', $command).Replace('__STATUSLINE_SCRIPT__', $statusLineScript).Replace('__CLAUDE_SANDBOX__', $claudeSandbox).Replace('__CLAUDE_DENY_RULES__', $denyRulesJson).Replace('__CLAUDE_ALLOW_RULES__', $allowRulesJson)
+        $qmdWarmScript = if ($shell -eq 'powershell') { 'Start-QmdWarm.ps1' } else { 'qmd-warm.sh' }
+        $content = $content.Replace('__HOOK_COMMAND__', $command).Replace('__POWERSHELL_HOOK_COMMAND__', $command).Replace('__HOOK_SCRIPT__', $script).Replace('__POWERSHELL_HOOK_SCRIPT__', $script).Replace('__COMPACT_SCRIPT__', $compactScript).Replace('__SESSION_POINTER_SCRIPT__', $pointerScript).Replace('__QMD_WARM_SCRIPT__', $qmdWarmScript).Replace('__STATUSLINE_COMMAND__', $command).Replace('__STATUSLINE_SCRIPT__', $statusLineScript).Replace('__CLAUDE_SANDBOX__', $claudeSandbox).Replace('__CLAUDE_DENY_RULES__', $denyRulesJson).Replace('__CLAUDE_ALLOW_RULES__', $allowRulesJson)
        Set-Content -LiteralPath $path -Value $content -Encoding UTF8
    }

@@ -220,5 +230,30 @@ $leftoverPlaceholders = @(Get-ChildItem $output -File -Recurse | ForEach-Object
 })
 if ($leftoverPlaceholders.Count) { throw "Unresolved template placeholders in: $($leftoverPlaceholders -join ', ')" }

+$lockPath = Join-Path $root 'generated.lock'
+$lockDeadline = (Get-Date).AddSeconds(30)
+while ($true) {
+    try { [System.IO.File]::Open($lockPath, [System.IO.FileMode]::CreateNew, [System.IO.FileAccess]::Write, [System.IO.FileShare]::None).Dispose(); break }
+    catch [System.IO.IOException], [System.UnauthorizedAccessException] {
+        if ((Get-Date) -gt $lockDeadline) { throw "Another build holds $lockPath; wait for it to finish, or remove the file if no build is running." }
+        Start-Sleep -Milliseconds 200
+    }
+}
+$retired = $null
+try {
+    if (Test-Path -LiteralPath $final) {
+        $retired = Join-Path $root ("generated.old-ps$PID-" + [Guid]::NewGuid().ToString('N').Substring(0, 6))
+        [System.IO.Directory]::Move($final, $retired)
+    }
+    try { [System.IO.Directory]::Move($output, $final) }
+    catch {
+        if ($retired) { [System.IO.Directory]::Move($retired, $final); $retired = $null }
+        throw
+    }
+} finally {
+    [System.IO.File]::Delete($lockPath)
+}
+if ($retired) { Remove-Item -LiteralPath $retired -Recurse -Force -ErrorAction SilentlyContinue }
+
 if ($Summary) { Write-Output 'Build: PASS | 4 packages' } else { Write-Output 'PASS build: codex-powershell, claude-powershell, codex-bash, claude-bash' }
 exit 0
@@ -10,7 +10,7 @@ done

 root=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd)
 shared="$root/shared"
-output="$root/generated"
+final="$root/generated"
 sandbox_supported=false
 platform=$(uname -s 2>/dev/null || true)
 case "$platform" in
@@ -66,7 +66,27 @@ if [ "$summary" = true ]; then
 else
  printf '%s\n' "$session_output"
 fi
-rm -rf -- "$output"
+# Build into a private sibling directory and swap it into place only after validation, so a failed
+# or parallel build never leaves generated/ partial. Leftovers of crashed runs are removed here:
+# old trees always, build trees only when their Bash owner process has exited.
+# ponytail: PowerShell-owned leftovers are left to the PowerShell build, since PIDs are not comparable across shells.
+for leftover in "$root"/generated.old-* "$root"/generated.build-sh*; do
+  [ -d "$leftover" ] || continue
+  if [[ "$leftover" == */generated.build-sh* ]]; then
+    leftover_pid=${leftover##*/generated.build-sh}
+    leftover_pid=${leftover_pid%%-*}
+    ! kill -0 "$leftover_pid" 2>/dev/null || continue
+  fi
+  rm -rf -- "$leftover"
+done
+lock="$root/generated.lock"
+locked=false
+retired=''
+output=''
+trap 'rm -rf -- ${output:+"$output"}; [ "$locked" != true ] || rm -f -- "$lock"' EXIT
+# Keep the name short: it lengthens every generated path, which matters on Windows.
+output=$(mktemp -d "$root/generated.build-sh$$-XXXXXX")
+chmod "$(printf '%o' $((0777 & ~$(umask))))" "$output"

 agent_dirs=("$shared"/agents/*/)
 declare -A agent_seen
@@ -175,20 +195,22 @@ for client in codex claude; do
  statusline_script=statusline.sh
  compact_script=record-compact.sh
  pointer_script=show-session-state-pointer.sh
+  qmd_warm_script=qmd-warm.sh
  if [ "$shell" = powershell ]; then
    command='__POWERSHELL_COMMAND__'
    script=flashbang.ps1
    statusline_script=statusline.ps1
    compact_script=Record-Compact.ps1
    pointer_script=Show-SessionStatePointer.ps1
+    qmd_warm_script=Start-QmdWarm.ps1
  fi
  path="$output/$client-$shell/$file"
  content=$(<"$path")
+  # Claude can offer both shell tools on Windows, so every package denies the destructive commands in both.
+  deny_rules='["PowerShell(git reset --hard*)","PowerShell(git clean*)","PowerShell(Remove-Item *-Recurse*)","Bash(git reset --hard*)","Bash(git clean*)","Bash(rm -rf*)"]'
  if [ "$shell" = powershell ]; then
-    deny_rules='["PowerShell(git reset --hard*)","PowerShell(git clean*)","PowerShell(Remove-Item *-Recurse*)"]'
    allow_rules='["Agent","PowerShell(mcporter call context7.*)"]'
  else
-    deny_rules='["Bash(git reset --hard*)","Bash(git clean*)","Bash(rm -rf*)"]'
    allow_rules='["Agent","Bash(mcporter call context7.*)"]'
  fi
  content=${content//__HOOK_COMMAND__/$command}
@@ -197,6 +219,7 @@ for client in codex claude; do
  content=${content//__POWERSHELL_HOOK_SCRIPT__/$script}
  content=${content//__COMPACT_SCRIPT__/$compact_script}
  content=${content//__SESSION_POINTER_SCRIPT__/$pointer_script}
+  content=${content//__QMD_WARM_SCRIPT__/$qmd_warm_script}
  content=${content//__STATUSLINE_COMMAND__/$command}
  content=${content//__STATUSLINE_SCRIPT__/$statusline_script}
  content=${content//__CLAUDE_SANDBOX__/$sandbox}
@@ -231,4 +254,21 @@ if [ -n "$leftover_tokens" ]; then
  exit 1
 fi

+for ((attempt = 0; attempt < 150; attempt++)); do
+  if (set -o noclobber; : > "$lock") 2>/dev/null; then locked=true; break; fi
+  sleep 0.2
+done
+[ "$locked" = true ] || { printf 'Another build holds %s; wait for it to finish, or remove the file if no build is running.\n' "$lock" >&2; exit 1; }
+if [ -e "$final" ]; then
+  retired="$root/generated.old-sh$$-$RANDOM"
+  mv -- "$final" "$retired"
+fi
+if ! mv -- "$output" "$final"; then
+  [ -z "$retired" ] || mv -- "$retired" "$final"
+  exit 1
+fi
+rm -f -- "$lock"
+locked=false
+[ -z "$retired" ] || rm -rf -- "$retired"
+
 if [ "$summary" = true ]; then printf 'Build: PASS | 4 packages\n'; else printf 'PASS build: codex-powershell, claude-powershell, codex-bash, claude-bash\n'; fi
@@ -4,6 +4,7 @@ $ErrorActionPreference = 'Stop'
 $root = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
 . (Join-Path $root 'scripts/lib/manifest.ps1')
 $homePath = [Environment]::GetFolderPath('UserProfile')
+if ([string]::IsNullOrWhiteSpace($homePath)) { $homePath = $HOME }
 $script:fail = $false
 $script:checkCount = 0
 function Result($state, $message) {
@@ -14,7 +15,27 @@ function Result($state, $message) {
    }
 }

-foreach ($tool in @('codex','claude')) { if (Get-Command $tool -ErrorAction SilentlyContinue) { $version = & $tool --version 2>&1 | Select-Object -First 1; Result 'PASS' "$tool available ($version)" } else { Result 'WARN' "$tool unavailable" } }
+function Invoke-DoctorCommand {
+    param([string]$Command, [string[]]$Arguments)
+    # PowerShell 5.1 turns native stderr into error records, even when the process succeeds.
+    $ErrorActionPreference = 'Continue'
+    $PSNativeCommandUseErrorActionPreference = $false
+    try {
+        $executable = Get-Command $Command -ErrorAction Stop
+        $output = @(& $executable @Arguments 2>&1)
+        return [pscustomobject]@{ Output = $output; ExitCode = $LASTEXITCODE }
+    } catch {
+        return [pscustomobject]@{ Output = @($_); ExitCode = 1 }
+    }
+}
+
+foreach ($tool in @('codex','claude')) {
+    if (Get-Command $tool -ErrorAction SilentlyContinue) {
+        $probe = Invoke-DoctorCommand -Command $tool -Arguments @('--version')
+        if ($probe.ExitCode -eq 0) { Result 'PASS' "$tool available ($($probe.Output -join ' '))" }
+        else { Result 'FAIL' "$tool --version failed (exit $($probe.ExitCode)): $($probe.Output -join ' ')" }
+    } else { Result 'WARN' "$tool unavailable" }
+}
 if (Get-Command jq -ErrorAction SilentlyContinue) { Result 'PASS' 'jq available for Claude Bash status line' } else { Result 'WARN' 'jq unavailable; Claude Bash status line is disabled' }

 $sourceAgentCount = @(Get-ChildItem (Join-Path $root 'shared/agents') -Directory -ErrorAction SilentlyContinue).Count
@@ -50,14 +71,14 @@ if (Test-Path -LiteralPath $settingsPath) {
 }
 $configTomlPath = Join-Path $homePath '.codex/config.toml'
 if (Test-Path -LiteralPath $configTomlPath) {
-    $parseResult = & python -c "import sys,tomllib,pathlib; tomllib.loads(pathlib.Path(sys.argv[1]).read_text(encoding='utf-8-sig'))" $configTomlPath 2>&1
-    if ($LASTEXITCODE -eq 0) { Result 'PASS' 'installed .codex/config.toml parses as TOML' } else { Result 'FAIL' "installed .codex/config.toml is invalid TOML: $parseResult" }
+    $parseResult = Invoke-DoctorCommand -Command 'python' -Arguments @('-c', "import sys,tomllib,pathlib; tomllib.loads(pathlib.Path(sys.argv[1]).read_text(encoding='utf-8-sig'))", $configTomlPath)
+    if ($parseResult.ExitCode -eq 0) { Result 'PASS' 'installed .codex/config.toml parses as TOML' } else { Result 'FAIL' "installed .codex/config.toml is invalid TOML: $($parseResult.Output -join ' ')" }
    if (Get-Command codex -ErrorAction SilentlyContinue) {
        $previousCodexHome = $env:CODEX_HOME
        try {
            $env:CODEX_HOME = Split-Path $configTomlPath -Parent
-            $schemaResult = & codex --strict-config --help 2>&1
-            if ($LASTEXITCODE -eq 0) { Result 'PASS' 'installed .codex/config.toml matches the installed Codex schema' } else { Result 'FAIL' "installed .codex/config.toml has unsupported Codex settings: $schemaResult" }
+            $schemaResult = Invoke-DoctorCommand -Command 'codex' -Arguments @('--strict-config', '--help')
+            if ($schemaResult.ExitCode -eq 0) { Result 'PASS' 'installed .codex/config.toml matches the installed Codex schema' } else { Result 'FAIL' "installed .codex/config.toml has unsupported Codex settings: $($schemaResult.Output -join ' ')" }
        } finally { $env:CODEX_HOME = $previousCodexHome }
    } else { Result 'WARN' 'Codex CLI unavailable; skipped installed Codex schema validation' }
 }
@@ -24,7 +24,13 @@ result() {
 }

 for tool in codex claude; do
-  if command -v "$tool" >/dev/null; then result PASS "$tool available ($($tool --version 2>&1 | head -n 1))"; else result WARN "$tool unavailable"; fi
+  if command -v "$tool" >/dev/null; then
+    if version=$("$tool" --version 2>&1); then result PASS "$tool available ($version)"
+    else
+      status=$?
+      result FAIL "$tool --version failed (exit $status): $version"
+    fi
+  else result WARN "$tool unavailable"; fi
 done
 command -v jq >/dev/null && result PASS 'jq available for Claude Bash status line' || result WARN 'jq unavailable; Claude Bash status line is disabled'

@@ -12,7 +12,7 @@ $root = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
 . (Join-Path $root 'scripts/lib/install-targets.ps1')
 . (Join-Path $root 'scripts/lib/selection-state.ps1')
 . (Join-Path $root 'scripts/lib/install-options.ps1')
-. (Join-Path $root 'scripts/lib/semantic-retrieval.ps1')
+. (Join-Path $root 'scripts/lib/qmd.ps1')

 $Shell = Read-InstallShell -Shell $Shell
 $shell = $Shell.ToLowerInvariant()
@@ -41,11 +41,11 @@ $plugins = Select-ConfiguredPlugins -RepositoryRoot $root -HomePath $homePath -C

 foreach ($item in (Get-InstallTargets -Generated $generated -HomePath $homePath -Shell $shell -Client $Client)) {
    Sync-ManagedDestination -Source $item.Source -Destination $item.Destination -Stamp $stamp `
-        -AiConfigRoot $item.Destination.Replace('\','/') -ShellCommand $shellCommand -PowerShellCommand $powerShellCommand -ClaudeConcurrency $claudeConcurrency -FlashbangEnabled $options.flashbang -StatusLineEnabled $options.statusline -DryRun:$DryRun -Summary:$Summary
+        -AiConfigRoot $item.Destination.Replace('\','/') -ShellCommand $shellCommand -PowerShellCommand $powerShellCommand -ClaudeConcurrency $claudeConcurrency -FlashbangEnabled $options.flashbang -StatusLineEnabled $options.statusline -SemanticRetrievalEnabled $options.semantic_retrieval -DryRun:$DryRun -Summary:$Summary
 }

+Sync-Qmd -RepositoryRoot $root -HomePath $homePath -Client $Client -Enabled $options.semantic_retrieval -DryRun:$DryRun -Summary:$Summary
 Sync-ConfiguredPlugins -RepositoryRoot $root -HomePath $homePath -Client $Client -DryRun:$DryRun -Summary:$Summary -Entries $plugins.Selected
-Sync-SemanticRetrieval -RepositoryRoot $root -HomePath $homePath -Client $Client -Enabled $options.semantic_retrieval -DryRun:$DryRun -Summary:$Summary
 if (-not $DryRun) { Save-UpdateSelection -HomePath $homePath -RepositoryRoot $root -Shell $Shell -Client $Client -Plugins $plugins -Flashbang $options.flashbang -StatusLine $options.statusline -SemanticRetrieval $options.semantic_retrieval }
 if ($Summary) { Write-Output "Install: PASS | $Client, $Shell$(if ($DryRun) { ', dry-run' })" } else { Write-Output ($(if ($DryRun) { 'PASS install dry-run' } else { 'PASS install' })) }
 exit 0
@@ -21,7 +21,7 @@ root=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd)
 . "$root/scripts/lib/install-targets.sh"
 . "$root/scripts/lib/selection-state.sh"
 . "$root/scripts/lib/install-options.sh"
-. "$root/scripts/lib/semantic-retrieval.sh"
+. "$root/scripts/lib/qmd.sh"

 shell=$(read_install_shell "$shell")
 client=$(read_install_client "$client")
@@ -58,11 +58,11 @@ select_configured_plugins "$root" "$client" Install "$dry_run" selected_plugins
 while IFS='|' read -r source destination; do
  ai_config_root=$destination
  command -v cygpath >/dev/null && ai_config_root=$(cygpath -m "$destination")
-  sync_managed_destination "$source" "$destination" "$stamp" "$ai_config_root" "$shell_command" "$powershell_command" "$dry_run" "$summary" "$flashbang" "$claude_concurrency" "$statusline"
+  sync_managed_destination "$source" "$destination" "$stamp" "$ai_config_root" "$shell_command" "$powershell_command" "$dry_run" "$summary" "$flashbang" "$claude_concurrency" "$statusline" "$semantic_retrieval"
 done < <(get_install_targets "$generated" "$home_path" "$shell" "$client")

+sync_qmd "$root" "$client" "$home_path" "$semantic_retrieval" "$dry_run" false "$summary"
 sync_configured_plugins "$root" "$client" "$home_path" "$dry_run" false selected_plugins "$summary"
-sync_semantic_retrieval "$root" "$client" "$home_path" "$semantic_retrieval" "$dry_run" false "$summary"
 if [ "$dry_run" = false ]; then save_update_selection; fi

 if [ "$summary" = true ]; then
@@ -10,7 +10,7 @@ $root = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
 . (Join-Path $root 'scripts/lib/plugins.ps1')
 . (Join-Path $root 'scripts/lib/manifest.ps1')
 . (Join-Path $root 'scripts/lib/install-targets.ps1')
-. (Join-Path $root 'scripts/lib/semantic-retrieval.ps1')
+. (Join-Path $root 'scripts/lib/qmd.ps1')

 $Client = Read-InstallClient -Client $Client
 $homePath = [Environment]::GetFolderPath('UserProfile')
@@ -24,7 +24,7 @@ if (-not $DryRun -and -not $Force) {
    if ([Console]::IsInputRedirected -or $env:CI -eq 'true' -or $env:AI_CONFIG_NO_INTERACTIVE -eq '1') {
        throw 'Refusing to uninstall without confirmation in a non-interactive session. Pass -Force to proceed.'
    }
-    Write-Host "This removes the managed configuration, extensions, and semantic retrieval setup for $Client under $homePath."
+    Write-Host "This removes the managed configuration, extensions, and QMD local search setup for $Client under $homePath."
    Write-Host 'Backups already on disk are kept; anything this setup never installed is left untouched.'
    $confirm = Read-Host -Prompt 'Continue? [y/N]'
    if ($null -eq $confirm) { $confirm = '' }
@@ -57,7 +57,7 @@ try {
 }

 Sync-ConfiguredPlugins -RepositoryRoot $root -HomePath $homePath -Client $Client -DryRun:$DryRun -Summary:$Summary -Entries @()
-Sync-SemanticRetrieval -RepositoryRoot $root -HomePath $homePath -Client $Client -Enabled $false -DryRun:$DryRun -Summary:$Summary
+Sync-Qmd -RepositoryRoot $root -HomePath $homePath -Client $Client -Enabled $false -DryRun:$DryRun -Summary:$Summary

 if (-not $DryRun) {
    $remaining = @($targets | Where-Object { Test-Path -LiteralPath (Get-ManagedManifestPath $_.Destination) })
@@ -19,7 +19,7 @@ root=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd)
 . "$root/scripts/lib/plugins.sh"
 . "$root/scripts/lib/manifest.sh"
 . "$root/scripts/lib/install-targets.sh"
-. "$root/scripts/lib/semantic-retrieval.sh"
+. "$root/scripts/lib/qmd.sh"

 client=$(read_install_client "$client")
 home_path=${HOME:?HOME is required}
@@ -40,7 +40,7 @@ if [ "$dry_run" = false ] && [ "$force" = false ]; then
    printf 'Refusing to uninstall without confirmation in a non-interactive session. Pass --force to proceed.\n' >&2
    exit 1
  fi
-  printf 'This removes the managed configuration, extensions, and semantic retrieval setup for %s under %s.\n' "$client" "$home_path"
+  printf 'This removes the managed configuration, extensions, and QMD local search setup for %s under %s.\n' "$client" "$home_path"
  printf 'Backups already on disk are kept; anything this setup never installed is left untouched.\n'
  read -r -p "Continue? [y/N]: " confirm || confirm=""
  case "$confirm" in
@@ -75,7 +75,7 @@ done
 # shellcheck disable=SC2034
 selected_plugins=()
 sync_configured_plugins "$root" "$client" "$home_path" "$dry_run" false selected_plugins "$summary"
-sync_semantic_retrieval "$root" "$client" "$home_path" false "$dry_run" false "$summary"
+sync_qmd "$root" "$client" "$home_path" false "$dry_run" false "$summary"

 if [ "$dry_run" = false ]; then
  remaining=0
@@ -13,7 +13,7 @@ $root = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
 . (Join-Path $root 'scripts/lib/install-targets.ps1')
 . (Join-Path $root 'scripts/lib/selection-state.ps1')
 . (Join-Path $root 'scripts/lib/install-options.ps1')
-. (Join-Path $root 'scripts/lib/semantic-retrieval.ps1')
+. (Join-Path $root 'scripts/lib/qmd.ps1')

 $homePath = [Environment]::GetFolderPath('UserProfile')
 if ($Quick) {
@@ -51,9 +51,10 @@ $plugins = if ($Quick) {

 foreach ($item in (Get-InstallTargets -Generated $generated -HomePath $homePath -Shell $shell -Client $Client)) {
    Sync-ManagedDestination -Source $item.Source -Destination $item.Destination -Stamp $stamp `
-        -AiConfigRoot $item.Destination.Replace('\','/') -ShellCommand $shellCommand -PowerShellCommand $powerShellCommand -FlashbangEnabled $options.flashbang -StatusLineEnabled $options.statusline -DryRun:$DryRun -Summary:$Summary
+        -AiConfigRoot $item.Destination.Replace('\','/') -ShellCommand $shellCommand -PowerShellCommand $powerShellCommand -FlashbangEnabled $options.flashbang -StatusLineEnabled $options.statusline -SemanticRetrievalEnabled $options.semantic_retrieval -DryRun:$DryRun -Summary:$Summary
 }

+Sync-Qmd -RepositoryRoot $root -HomePath $homePath -Client $Client -Enabled $options.semantic_retrieval -DryRun:$DryRun -Update -Summary:$Summary
 $previousPluginNonInteractive = $script:PluginNonInteractive
 $previousCI = $env:CI
 try {
@@ -64,7 +65,6 @@ try {
    $script:PluginNonInteractive = $previousPluginNonInteractive
    $env:CI = $previousCI
 }
-Sync-SemanticRetrieval -RepositoryRoot $root -HomePath $homePath -Client $Client -Enabled $options.semantic_retrieval -DryRun:$DryRun -Update -Summary:$Summary
 if (-not $DryRun) { Save-UpdateSelection -HomePath $homePath -RepositoryRoot $root -Shell $Shell -Client $Client -Plugins $plugins -Flashbang $options.flashbang -StatusLine $options.statusline -SemanticRetrieval $options.semantic_retrieval }
 if ($Summary) { Write-Output "Update: PASS | $Client, $Shell$(if ($DryRun) { ', dry-run' })" } else { Write-Output ($(if ($DryRun) { 'PASS update dry-run' } else { 'PASS update' })) }
 exit 0
@@ -23,7 +23,7 @@ root=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd)
 . "$root/scripts/lib/install-targets.sh"
 . "$root/scripts/lib/selection-state.sh"
 . "$root/scripts/lib/install-options.sh"
-. "$root/scripts/lib/semantic-retrieval.sh"
+. "$root/scripts/lib/qmd.sh"

 home_path=${HOME:?HOME is required}
 selected_plugins=()
@@ -63,15 +63,15 @@ fi
 while IFS='|' read -r source destination; do
  ai_config_root=$destination
  command -v cygpath >/dev/null && ai_config_root=$(cygpath -m "$destination")
-  sync_managed_destination "$source" "$destination" "$stamp" "$ai_config_root" "$shell_command" "$powershell_command" "$dry_run" "$summary" "$flashbang" 5 "$statusline"
+  sync_managed_destination "$source" "$destination" "$stamp" "$ai_config_root" "$shell_command" "$powershell_command" "$dry_run" "$summary" "$flashbang" 5 "$statusline" "$semantic_retrieval"
 done < <(get_install_targets "$generated" "$home_path" "$shell" "$client")

+sync_qmd "$root" "$client" "$home_path" "$semantic_retrieval" "$dry_run" true "$summary"
 if [ "$quick" = true ]; then
  CI=true sync_configured_plugins "$root" "$client" "$home_path" "$dry_run" true selected_plugins "$summary" </dev/null
 else
  sync_configured_plugins "$root" "$client" "$home_path" "$dry_run" true selected_plugins "$summary"
 fi
-sync_semantic_retrieval "$root" "$client" "$home_path" "$semantic_retrieval" "$dry_run" true "$summary"
 if [ "$dry_run" = false ]; then save_update_selection; fi

 if [ "$summary" = true ]; then
@@ -32,14 +32,14 @@ function Read-SemanticRetrievalOption {
    param([bool]$Default,[string]$RepositoryRoot,[string]$HomePath)
    $hint = if ($Default) { 'Y/n/a' } else { 'y/N/a' }
    while ($true) {
-        Write-Host "Enable Qwen3 embedding and reranking semantic retrieval? [$hint] " -NoNewline
+        Write-Host "Enable local QMD search models (Qwen3 embedding, Qwen3 reranker, QMD query expansion)? [$hint] " -NoNewline
        $answer = [Console]::ReadLine()
        if ($null -eq $answer) { throw 'Input ended before semantic retrieval was confirmed.' }
        switch ($answer.Trim().ToLowerInvariant()) {
            '' { return $Default }
            { $_ -in @('y', 'yes') } { return $true }
            { $_ -in @('n', 'no') } { return $false }
-            { $_ -in @('a', 'auto') } { return Test-SemanticRetrievalDevice -RepositoryRoot $RepositoryRoot -HomePath $HomePath }
+            { $_ -in @('a', 'auto') } { return Test-QmdDevice -RepositoryRoot $RepositoryRoot -HomePath $HomePath }
        }
    }
 }
@@ -5,13 +5,35 @@ import re
 import sys
 import tomllib

+from personal_instructions import CLIENT_FILES, render
+

 def is_flashbang(hook):
    return any(re.search(r'(?:[/\\\s"\x27]|^)flashbang\.(?:ps1|sh)(?:[\s"\x27]|$)', str(hook.get(key, '')), re.I)
               for key in ('command', 'command_windows'))


-def filter_options(path, flashbang_enabled=True, statusline_enabled=True):
+def is_qmd_warm(hook):
+    return any(re.search(r'(?:[/\\\s"\x27]|^)(?:qmd-warm\.sh|Start-QmdWarm\.ps1)(?:[\s"\x27]|$)', str(hook.get(key, '')), re.I)
+               for key in ('command', 'command_windows'))
+
+
+def without_hooks(groups, predicate):
+    remaining = []
+    for group in groups:
+        hooks = [hook for hook in group.get('hooks', []) if not predicate(hook)]
+        if hooks:
+            remaining.append(dict(group, hooks=hooks))
+    return remaining
+
+
+def filter_instructions(text, semantic_retrieval_enabled):
+    if semantic_retrieval_enabled:
+        return text
+    return ''.join(line for line in text.splitlines(keepends=True) if '`semantic-search`' not in line)
+
+
+def filter_options(path, flashbang_enabled=True, statusline_enabled=True, semantic_retrieval_enabled=True):
    content = path.read_text(encoding='utf-8-sig')
    if path.name == 'settings.json':
        settings = json.loads(content)
@@ -26,6 +48,12 @@ def filter_options(path, flashbang_enabled=True, statusline_enabled=True):
                settings['hooks']['Stop'] = remaining
            elif 'Stop' in settings.get('hooks', {}):
                del settings['hooks']['Stop']
+        if not semantic_retrieval_enabled:
+            remaining = without_hooks(settings.get('hooks', {}).get('SessionStart', []), is_qmd_warm)
+            if remaining:
+                settings['hooks']['SessionStart'] = remaining
+            else:
+                settings.get('hooks', {}).pop('SessionStart', None)
        if not statusline_enabled:
            settings.pop('statusLine', None)
        return json.dumps(settings, indent=2, ensure_ascii=False) + '\n'
@@ -44,6 +72,17 @@ def filter_options(path, flashbang_enabled=True, statusline_enabled=True):
            filtered.append(section)
        result = ''.join(filtered)
        result = re.sub(r'(?m)^\[\[hooks\.Stop\]\][ \t]*\r?\n\s*(?=\[|\Z)(?!\[\[hooks\.Stop\.hooks\]\])', '', result)
+    if not semantic_retrieval_enabled:
+        sections = re.split(r'(?m)(?=^\s*\[\[?[^\r\n]+\]\]?\s*$)', result)
+        kept = []
+        for section in sections:
+            if re.match(r'\s*\[\[hooks\.SessionStart\.hooks\]\]', section):
+                hook = tomllib.loads(section)['hooks']['SessionStart']['hooks'][0]
+                if is_qmd_warm(hook):
+                    continue
+            kept.append(section)
+        result = ''.join(kept)
+        result = re.sub(r'(?m)^\[\[hooks\.SessionStart\]\][ \t]*\r?\n\s*(?=\[|\Z)(?!\[\[hooks\.SessionStart\.hooks\]\])', '', result)
    if not statusline_enabled:
        sections = re.split(r'(?m)(?=^\s*\[\[?[^\r\n]+\]\]?\s*$)', result)
        for index, section in enumerate(sections):
@@ -69,7 +108,7 @@ def merge_json(current, managed):
    for key, value in managed.items():
        if key == 'hooks' and isinstance(value, dict) and isinstance(result.get(key), dict):
            hooks = dict(result[key])
-            for event in set(value) | {'Stop'}:
+            for event in set(value) | {'Stop', 'SessionStart'}:
                groups = value.get(event, [])
                old_groups = hooks.get(event, [])
                if isinstance(groups, list) and isinstance(old_groups, list):
@@ -79,7 +118,7 @@ def merge_json(current, managed):
                            retained.append(group)
                            continue
                        foreign = [hook for hook in group['hooks'] if not (isinstance(hook, dict) and re.search(
-                            r'(?:flashbang|statusline|record-compact|session-state-pointer)\.(?:ps1|sh)',
+                            r'(?:flashbang|statusline|record-compact|session-state-pointer|qmd-warm|Start-QmdWarm)\.(?:ps1|sh)',
                            str(hook.get('command', '')) + str(hook.get('command_windows', '')), re.I))]
                        if foreign:
                            retained.append(dict(group, hooks=foreign))
@@ -128,10 +167,21 @@ def merge_toml(current_text, managed_text, statusline_enabled=True):
    managed_headers = {header for header, _ in managed_sections}
    extras = []
    fields_by_header = {}
-    for header, block in current_sections:
+    owned_pattern = r'(?:flashbang|statusline|record-compact|session-state-pointer|qmd-warm|Start-QmdWarm)\.(?:ps1|sh)'
+    for index, (header, block) in enumerate(current_sections):
        plugin_table = re.match(r'^\[(?:plugins|marketplaces)(?:\.|\])', header)
        array_table = header.startswith('[[')
-        owned_hook = any(re.search(r'(?:flashbang|statusline|record-compact|session-state-pointer)\.(?:ps1|sh)', line, re.I) for line in block)
+        owned_hook = any(re.search(owned_pattern, line, re.I) for line in block)
+        group = re.fullmatch(r'\[\[hooks\.(\w+)\]\]', header)
+        if group:
+            # A hook group header is owned when every hook table that follows it is owned (or none follows).
+            child = f'[[hooks.{group.group(1)}.hooks]]'
+            children = []
+            for name, lines in current_sections[index + 1:]:
+                if name != child:
+                    break
+                children.append(any(re.search(owned_pattern, line, re.I) for line in lines))
+            owned_hook = all(children)
        if plugin_table and header in managed_headers:
            raise ValueError('Cannot merge conflicting managed plugin tables.')
        if (header not in managed_headers and not array_table) or (array_table and not owned_hook):
@@ -173,17 +223,24 @@ def merge_toml(current_text, managed_text, statusline_enabled=True):

 if __name__ == '__main__':
    parser = argparse.ArgumentParser()
-    parser.add_argument('action', choices=('filter', 'merge-json', 'merge-toml'))
+    parser.add_argument('action', choices=('filter', 'filter-instructions', 'merge-json', 'merge-toml'))
    parser.add_argument('--path', type=Path)
    parser.add_argument('--current', type=Path)
    parser.add_argument('--flashbang', choices=('true', 'false'))
    parser.add_argument('--statusline', choices=('true', 'false'), default='true')
+    parser.add_argument('--semantic-retrieval', choices=('true', 'false'), default='true')
    parser.add_argument('--managed', type=Path)
    parser.add_argument('--output', type=Path)
+    parser.add_argument('--destination', type=Path)
    args = parser.parse_args()
    try:
        if args.action == 'filter':
-            result = filter_options(args.path, args.flashbang == 'true', args.statusline == 'true')
+            result = filter_options(args.path, args.flashbang == 'true', args.statusline == 'true', args.semantic_retrieval == 'true')
+        elif args.action == 'filter-instructions':
+            result = filter_instructions(args.path.read_text(encoding='utf-8-sig'), args.semantic_retrieval == 'true')
+            if args.destination and args.path.name in CLIENT_FILES.values():
+                client = next(client for client, name in CLIENT_FILES.items() if name == args.path.name)
+                result = render(result, args.destination.parent, client)
        else:
            managed = args.managed.read_text(encoding='utf-8-sig') if args.managed else sys.stdin.buffer.read().decode('utf-8-sig')
            current = args.current.read_text(encoding='utf-8-sig')
@@ -41,7 +41,7 @@ read_semantic_retrieval_option() {
  local default=$1 hint=y/N/a answer
  [ "$default" = false ] || hint=Y/n/a
  while :; do
-    printf 'Enable Qwen3 embedding and reranking semantic retrieval? [%s] ' "$hint" >&2
+    printf 'Enable local QMD search models (Qwen3 embedding, Qwen3 reranker, QMD query expansion)? [%s] ' "$hint" >&2
    IFS= read -r answer || { printf 'Input ended before semantic retrieval was confirmed.\n' >&2; return 1; }
    answer=${answer%$'\r'}
    case "$answer" in
@@ -49,7 +49,7 @@ read_semantic_retrieval_option() {
      y|Y|yes|Yes|YES) printf 'true\n'; return ;;
      n|N|no|No|NO) printf 'false\n'; return ;;
      a|A|auto|Auto|AUTO)
-        if test_semantic_retrieval_device "$root" "$home_path"; then printf 'true\n'; return; else status=$?; fi
+        if test_qmd_device "$root" "$home_path"; then printf 'true\n'; return; else status=$?; fi
        [ "$status" -eq 1 ] && { printf 'false\n'; return; }
        return "$status"
        ;;
@@ -304,9 +304,6 @@ class Manager:
        if entry['codex_method'] == 'cli':
            self.ensure_cli(client, entry)
            return
-        if entry['codex_method'] == 'qmd':
-            self.ensure_qmd(client, entry)
-            return
        skill = client == 'codex' and entry['codex_method'] != 'plugin'
        kind = 'skill' if skill else 'plugin'
        record = next((r for r in self.state['resources'] if r['client'] == client and r['name'] == entry['name']), None)
@@ -417,28 +414,6 @@ class Manager:
            atomic_write(path, (json.dumps(content, indent=2) + '\n').encode('utf-8'))
            print('Repaired Caveman Windows hook commands; review the changed hooks in Codex /hooks.')

-    def ensure_qmd(self, client, entry):
-        package = entry['codex_source']
-        if package != '@tobilu/qmd':
-            raise ValueError('Invalid QMD package.')
-        record = next((r for r in self.state['resources'] if r['client'] == 'shared' and r['name'] == entry['name']), None)
-        installed = package in self.global_packages()
-        if record is not None:
-            record['clients'] = sorted(set(record.get('clients', ['claude', 'codex'])) | {client})
-            self.save()
-        if record is None and installed and not self.summary:
-            print(f'PASS Preserving pre-existing global package: {package}')
-        if (record is not None or not installed) and (not installed or (self.update and package not in self.updated_packages)):
-            self.command(['npm', 'update' if installed else 'install', '--global', package])
-            self.global_packages().add(package)
-            self.updated_packages.add(package)
-            if record is None:
-                self.state['resources'].append(dict(client='shared', name=entry['name'], kind='qmd', package=package, clients=[client]))
-                self.save()
-        if client == 'claude':
-            entry = dict(entry, codex_method='plugin')
-            self.ensure(client, entry)
-
    def ensure_mcporter(self, entry, clients):
        server, url = entry['mcporter_name'], entry['mcporter_url']
        if not re.fullmatch(r'[a-z0-9-]+', server) or not re.fullmatch(r'https://[^\s]+', url):
@@ -142,6 +142,7 @@ function Sync-ManagedDestination {
        [string]$ClaudeConcurrency = '5',
        [bool]$FlashbangEnabled = $true,
        [bool]$StatusLineEnabled = $true,
+        [bool]$SemanticRetrievalEnabled = $true,
        [switch]$DryRun,
        [switch]$Summary
    )
@@ -169,6 +170,7 @@ function Invoke-ManagedSync {
        [string]$ClaudeConcurrency = '5',
        [bool]$FlashbangEnabled = $true,
        [bool]$StatusLineEnabled = $true,
+        [bool]$SemanticRetrievalEnabled = $true,
        [switch]$DryRun,
        [switch]$Summary
    )
@@ -178,6 +180,34 @@ function Invoke-ManagedSync {
    $oldManifest = Read-ManagedManifest $manifestPath
    $newManifest = @{}
    $backupRoot = Get-ManagedBackupRoot $Destination
+    $tally = @{ Created = 0; Updated = 0; Unchanged = 0; Removed = 0; Warned = 0 }
+    $journalPath = Resolve-ManagedPath -Destination $Destination -Relative '.ai-config-transaction.json'
+    if (Test-Path -LiteralPath $journalPath) {
+        # An earlier run was interrupted after it started writing; undo its changes before syncing.
+        $journal = [System.IO.File]::ReadAllText($journalPath, (New-Object System.Text.UTF8Encoding($false))) | ConvertFrom-Json
+        if ($DryRun) {
+            Write-Output "DRYRUN ROLLBACK $Destination $($journal.stamp)"
+        } else {
+            foreach ($entry in @($journal.files)) {
+                $target = Resolve-ManagedPath -Destination $Destination -Relative $entry.path
+                if ($entry.action -eq 'create') {
+                    if (-not (Test-Path -LiteralPath $target)) { continue }
+                    if ((Get-Sha256Hash $target) -eq "$($entry.sha256)".ToLowerInvariant()) { [System.IO.File]::Delete($target) }
+                    else { Write-Output "WARN $target was created by an interrupted run and has changed since; it was left in place."; $tally.Warned++ }
+                } elseif ($entry.action -in @('update', 'remove')) {
+                    # A missing backup means the interrupted run never reached this file.
+                    $backup = Resolve-ManagedPath -Destination $backupRoot -Relative $entry.backup
+                    if (-not (Test-Path -LiteralPath $backup)) { continue }
+                    New-Item (Split-Path $target -Parent) -ItemType Directory -Force | Out-Null
+                    Write-ManagedFileAtomically -Path $target -Bytes ([System.IO.File]::ReadAllBytes($backup))
+                } else {
+                    throw "Invalid transaction journal action in ${journalPath}: $($entry.action)"
+                }
+            }
+            Write-Output "ROLLBACK $Destination $($journal.stamp)"
+            [System.IO.File]::Delete($journalPath)
+        }
+    }
    $oldBackupRoot = Resolve-ManagedPath -Destination $Destination -Relative 'backups'
    if ($backupRoot -ne $oldBackupRoot -and (Test-Path -LiteralPath $oldBackupRoot)) {
        if ($DryRun) {
@@ -187,21 +217,27 @@ function Invoke-ManagedSync {
            Move-Item -LiteralPath $oldBackupRoot -Destination (Join-Path $backupRoot ('legacy-' + [Guid]::NewGuid().ToString('N')))
        }
    }
-    $tally = @{ Created = 0; Updated = 0; Unchanged = 0; Removed = 0; Warned = 0 }

+    # Plan every change before writing anything, so the journal can describe the whole run.
+    $plan = New-Object System.Collections.ArrayList
    Get-ChildItem $Source -File -Recurse | ForEach-Object {
        $relative = $_.FullName.Substring($Source.Length).TrimStart([char[]]@('\','/')).Replace('\','/')
        if ((Split-Path $Destination -Leaf) -eq '.codex' -and $relative.StartsWith('skills/')) { return }
        if ((Split-Path $Destination -Leaf) -eq '.claude' -and -not $StatusLineEnabled -and $relative.StartsWith('statusline/')) { return }
+        if (-not $SemanticRetrievalEnabled -and $relative -match '(^|/)semantic-search/') { return }
        $target = Resolve-ManagedPath -Destination $Destination -Relative $relative
        $rawContent = Get-Content -LiteralPath $_.FullName -Raw -Encoding UTF8
-        $filterOptions = ((-not $FlashbangEnabled) -or (-not $StatusLineEnabled)) -and $relative -in @('settings.json', 'config.toml')
+        $filterOptions = ((-not $FlashbangEnabled) -or (-not $StatusLineEnabled) -or (-not $SemanticRetrievalEnabled)) -and $relative -in @('settings.json', 'config.toml')
        if ($filterOptions) {
            $flashbangOption = if ($FlashbangEnabled) { 'true' } else { 'false' }
            $statusLineOption = if ($StatusLineEnabled) { 'true' } else { 'false' }
-            $rawContent = Invoke-InstallOptions -Arguments @('filter', '--path', $_.FullName, '--flashbang', $flashbangOption, '--statusline', $statusLineOption) -ErrorMessage 'Could not configure install options.'
+            $rawContent = Invoke-InstallOptions -Arguments @('filter', '--path', $_.FullName, '--flashbang', $flashbangOption, '--statusline', $statusLineOption, '--semantic-retrieval', $(if ($SemanticRetrievalEnabled) { 'true' } else { 'false' })) -ErrorMessage 'Could not configure install options.'
        }
-        $needsSubstitution = $filterOptions -or $rawContent.Contains('__AI_CONFIG_ROOT__') -or $rawContent.Contains('__HOOK_COMMAND__') -or $rawContent.Contains('__POWERSHELL_HOOK_COMMAND__') -or $rawContent.Contains('__POWERSHELL_COMMAND__') -or $rawContent.Contains('__CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY__')
+        $filterInstructions = $relative -in @('CLAUDE.md', 'AGENTS.md') -or ((-not $SemanticRetrievalEnabled) -and $relative -eq 'rules/general.md')
+        if ($filterInstructions) {
+            $rawContent = Invoke-InstallOptions -Arguments @('filter-instructions', '--path', $_.FullName, '--destination', $Destination, '--semantic-retrieval', $(if ($SemanticRetrievalEnabled) { 'true' } else { 'false' })) -ErrorMessage 'Could not configure install options.'
+        }
+        $needsSubstitution = $filterOptions -or $filterInstructions -or $rawContent.Contains('__AI_CONFIG_ROOT__') -or $rawContent.Contains('__HOOK_COMMAND__') -or $rawContent.Contains('__POWERSHELL_HOOK_COMMAND__') -or $rawContent.Contains('__POWERSHELL_COMMAND__') -or $rawContent.Contains('__CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY__')
        if ($needsSubstitution) {
            $finalContent = $rawContent.Replace('__AI_CONFIG_ROOT__', $AiConfigRoot).Replace('__HOOK_COMMAND__', $ShellCommand).Replace('__POWERSHELL_HOOK_COMMAND__', $PowerShellCommand).Replace('__POWERSHELL_COMMAND__', $PowerShellCommand).Replace('__CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY__', $ClaudeConcurrency).Replace('__HOOK_SCRIPT__', 'flashbang.ps1').Replace('__POWERSHELL_HOOK_SCRIPT__', 'flashbang.ps1')
            $newBytes = [System.Text.Encoding]::UTF8.GetBytes($finalContent)
@@ -221,42 +257,67 @@ function Invoke-ManagedSync {
        $newManifest[$relative] = $newHash

        $exists = Test-Path -LiteralPath $target
-        if ($exists -and (Get-Sha256Hash $target) -eq $newHash) { $tally.Unchanged++; if (-not $Summary) { Write-Output "UNCHANGED $target" }; return }
-
-        $action = if ($exists) { 'UPDATE' } else { 'CREATE' }
-        if ($DryRun) { if (-not $Summary) { Write-Output "DRYRUN $action $target" }; if ($action -eq 'CREATE') { $tally.Created++ } else { $tally.Updated++ }; return }
-        if ($exists) {
-            $wasManaged = $oldManifest.ContainsKey($relative)
-            $backup = Resolve-ManagedPath -Destination $backupRoot -Relative "$Stamp/$relative"
-            New-Item (Split-Path $backup -Parent) -ItemType Directory -Force | Out-Null
-            Copy-Item -LiteralPath $target $backup -Force
-            if (-not $Summary) { Write-Output "BACKUP $target -> $backup" }
-            if (-not $wasManaged) { Write-Output "WARN $target existed before this installation but was not tracked by a previous run; it was backed up before being overwritten."; $tally.Warned++ }
+        $action = if (-not $exists) { 'CREATE' } elseif ((Get-Sha256Hash $target) -eq $newHash) { 'UNCHANGED' } else { 'UPDATE' }
+        $null = $plan.Add([pscustomobject]@{ Relative = $relative; Target = $target; Action = $action; Bytes = $newBytes; Hash = $newHash })
    }
-        New-Item (Split-Path $target -Parent) -ItemType Directory -Force | Out-Null
-        Write-ManagedFileAtomically -Path $target -Bytes $newBytes
-        if (-not $Summary) { Write-Output "$action $target" }
-        if ($action -eq 'CREATE') { $tally.Created++ } else { $tally.Updated++ }
-    }
-
    foreach ($relative in @($oldManifest.Keys | Where-Object { -not $newManifest.ContainsKey($_) })) {
        $target = Resolve-ManagedPath -Destination $Destination -Relative $relative
        if (-not (Test-Path -LiteralPath $target)) { continue }
-        if ($DryRun) { if (-not $Summary) { Write-Output "DRYRUN REMOVE $target" }; $tally.Removed++; continue }
-        $backup = Resolve-ManagedPath -Destination $backupRoot -Relative "$Stamp/$relative"
+        # A stale file changed locally is backed up but kept; only an unmodified one is removed.
+        $action = if ((Get-Sha256Hash $target) -eq $oldManifest[$relative]) { 'REMOVE' } else { 'KEEP' }
+        $null = $plan.Add([pscustomobject]@{ Relative = $relative; Target = $target; Action = $action; Bytes = $null; Hash = $null })
+    }
+
+    if (-not $DryRun) {
+        $journalEntries = @(foreach ($item in $plan) {
+            switch ($item.Action) {
+                'CREATE' { [ordered]@{ path = $item.Relative; action = 'create'; sha256 = $item.Hash } }
+                'UPDATE' { [ordered]@{ path = $item.Relative; action = 'update'; backup = "$Stamp/$($item.Relative)"; sha256 = $item.Hash } }
+                'REMOVE' { [ordered]@{ path = $item.Relative; action = 'remove'; backup = "$Stamp/$($item.Relative)" } }
+            }
+        })
+        $journalJson = ConvertTo-Json -InputObject ([ordered]@{ stamp = $Stamp; files = $journalEntries }) -Depth 4
+        New-Item $Destination -ItemType Directory -Force | Out-Null
+        Write-ManagedFileAtomically -Path $journalPath -Bytes ((New-Object System.Text.UTF8Encoding($false)).GetBytes($journalJson + "`n"))
+    }
+
+    foreach ($item in $plan) {
+        $target = $item.Target
+        if ($item.Action -eq 'UNCHANGED') { $tally.Unchanged++; if (-not $Summary) { Write-Output "UNCHANGED $target" }; continue }
+        $isRemoval = $item.Action -in @('REMOVE', 'KEEP')
+        if ($DryRun) {
+            if ($isRemoval) { if (-not $Summary) { Write-Output "DRYRUN REMOVE $target" }; $tally.Removed++ }
+            else { if (-not $Summary) { Write-Output "DRYRUN $($item.Action) $target" }; if ($item.Action -eq 'CREATE') { $tally.Created++ } else { $tally.Updated++ } }
+            continue
+        }
+        if ($item.Action -ne 'CREATE') {
+            $backup = Resolve-ManagedPath -Destination $backupRoot -Relative "$Stamp/$($item.Relative)"
            New-Item (Split-Path $backup -Parent) -ItemType Directory -Force | Out-Null
-        Copy-Item -LiteralPath $target $backup -Force
+            # Atomic, so a rollback after an interruption never restores a truncated backup.
+            Write-ManagedFileAtomically -Path $backup -Bytes ([System.IO.File]::ReadAllBytes($target))
            if (-not $Summary) { Write-Output "BACKUP $target -> $backup" }
-        if ((Get-Sha256Hash $target) -eq $oldManifest[$relative]) {
+        }
+        if ($item.Action -eq 'REMOVE') {
            Remove-Item -LiteralPath $target -Force
            if (-not $Summary) { Write-Output "REMOVE $target" }
            $tally.Removed++
-        } else {
+            continue
+        }
+        if ($item.Action -eq 'KEEP') {
            Write-Output "WARN $target was managed by a previous installation and has changed locally; it was backed up but left in place instead of being removed."
            $tally.Warned++
+            continue
        }
+        if ($item.Action -eq 'UPDATE' -and -not $oldManifest.ContainsKey($item.Relative)) { Write-Output "WARN $target existed before this installation but was not tracked by a previous run; it was backed up before being overwritten."; $tally.Warned++ }
+        New-Item (Split-Path $target -Parent) -ItemType Directory -Force | Out-Null
+        Write-ManagedFileAtomically -Path $target -Bytes $item.Bytes
+        if (-not $Summary) { Write-Output "$($item.Action) $target" }
+        if ($item.Action -eq 'CREATE') { $tally.Created++ } else { $tally.Updated++ }
    }

-    if (-not $DryRun) { Write-ManagedManifest $manifestPath $newManifest }
+    if (-not $DryRun) {
+        Write-ManagedManifest $manifestPath $newManifest
+        [System.IO.File]::Delete($journalPath)
+    }
    if ($Summary) { Write-Output ("SYNC {0}: {1} created, {2} updated, {3} unchanged, {4} removed, {5} warnings" -f $Destination, $tally.Created, $tally.Updated, $tally.Unchanged, $tally.Removed, $tally.Warned) }
 }
@@ -76,6 +76,12 @@ write_managed_file() {
  { cat -- "$content_file" > "$temporary" && chmod "$mode" "$temporary" && mv -f -- "$temporary" "$target"; } || { rm -f -- "$temporary"; return 1; }
 }

+# json_string <value>: print value as a JSON string. Managed paths and stamps never contain control characters.
+json_string() {
+  local value=${1//\\/\\\\}
+  printf '"%s"' "${value//\"/\\\"}"
+}
+
 # write_managed_manifest <manifest-file> <assoc-array-name>
 write_managed_manifest() {
  local path=$1 content
@@ -120,9 +126,9 @@ sync_managed_destination() {
  return "$status"
 }

-# run_managed_sync <source-dir> <destination-dir> <stamp> <ai-config-root> <shell-command> <powershell-command> <dry-run: true|false> [summary: true|false] [flashbang] [claude-concurrency] [statusline]
+# run_managed_sync <source-dir> <destination-dir> <stamp> <ai-config-root> <shell-command> <powershell-command> <dry-run: true|false> [summary: true|false] [flashbang] [claude-concurrency] [statusline] [semantic-retrieval]
 run_managed_sync() {
-  local source=$1 destination=$2 stamp=$3 ai_config_root=$4 shell_command=$5 powershell_command=$6 dry_run=$7 summary=${8:-false} flashbang_enabled=${9:-true} claude_concurrency=${10:-5} statusline_enabled=${11:-true}
+  local source=$1 destination=$2 stamp=$3 ai_config_root=$4 shell_command=$5 powershell_command=$6 dry_run=$7 summary=${8:-false} flashbang_enabled=${9:-true} claude_concurrency=${10:-5} statusline_enabled=${11:-true} semantic_retrieval_enabled=${12:-true}
  [ "$summary" = true ] || printf 'SOURCE %s -> %s\n' "$source" "$destination"
  local manifest
  manifest=$(manifest_path "$destination")
@@ -133,6 +139,52 @@ run_managed_sync() {
  local created=0 updated=0 unchanged=0 removed=0 warned=0
  local backup_root old_backup_root
  backup_root=$(managed_backup_root "$destination") || return 1
+  local journal
+  journal=$(managed_target "$destination" '.ai-config-transaction.json') || return 1
+  if [ -f "$journal" ]; then
+    # An earlier run was interrupted after it started writing; undo its changes before syncing.
+    local entries entry entry_action entry_path entry_backup entry_hash entry_target
+    local -a journal_lines
+    # One stamp line, then one unit-separated line per file (an empty field must survive read).
+    entries=$(python3 -c '
+import json, sys
+journal = json.load(open(sys.argv[1], encoding="utf-8-sig"))
+lines = [str(journal["stamp"])]
+for entry in journal.get("files") or []:
+    lines.append("\x1f".join([entry["action"], entry["path"], entry.get("backup", ""), entry.get("sha256", "")]))
+sys.stdout.buffer.write(("\n".join(lines) + "\n").encode("utf-8"))
+' "$journal") || { printf 'Could not read transaction journal %s\n' "$journal" >&2; return 1; }
+    mapfile -t journal_lines <<< "$entries"
+    if [ "$dry_run" = true ]; then
+      printf 'DRYRUN ROLLBACK %s %s\n' "$destination" "${journal_lines[0]}"
+    else
+      for entry in "${journal_lines[@]:1}"; do
+        IFS=$'\x1f' read -r entry_action entry_path entry_backup entry_hash <<< "$entry"
+        entry_target=$(managed_target "$destination" "$entry_path") || return 1
+        case "$entry_action" in
+          create)
+            [ -f "$entry_target" ] || continue
+            if [ "$(sha256_of_file "$entry_target")" = "$(printf '%s' "$entry_hash" | tr '[:upper:]' '[:lower:]')" ]; then
+              rm -f -- "$entry_target"
+            else
+              printf 'WARN %s was created by an interrupted run and has changed since; it was left in place.\n' "$entry_target"
+              warned=$((warned + 1))
+            fi
+            ;;
+          update|remove)
+            # A missing backup means the interrupted run never reached this file.
+            entry_backup=$(managed_target "$backup_root" "$entry_backup") || return 1
+            [ -f "$entry_backup" ] || continue
+            mkdir -p -- "$(dirname -- "$entry_target")"
+            write_managed_file "$entry_target" "$entry_backup" "$entry_backup" || return 1
+            ;;
+          *) printf 'Invalid transaction journal action in %s: %s\n' "$journal" "$entry_action" >&2; return 1 ;;
+        esac
+      done
+      printf 'ROLLBACK %s %s\n' "$destination" "${journal_lines[0]}"
+      rm -f -- "$journal"
+    fi
+  fi
  old_backup_root=$(managed_target "$destination" backups) || return 1
  if [ "$backup_root" != "$old_backup_root" ] && [ -e "$old_backup_root" ]; then
    if [ "$dry_run" = true ]; then
@@ -146,17 +198,25 @@ run_managed_sync() {
    fi
  fi

+  # Plan every change before writing anything, so the journal can describe the whole run.
+  local -a plan_relative=() plan_target=() plan_action=() plan_hash=() plan_source=() plan_sub=() plan_content=()
  while IFS= read -r -d '' source_file; do
-    local relative target content needs_sub new_hash exists current_hash action backup
+    local relative target content needs_sub new_hash current_hash action backup
    relative=${source_file#"$source/"}
    if [ "${destination##*/}" = .codex ] && [[ "$relative" = skills/* ]]; then continue; fi
    if [ "${destination##*/}" = .claude ] && [ "$statusline_enabled" = false ] && [[ "$relative" = statusline/* ]]; then continue; fi
+    if [ "$semantic_retrieval_enabled" = false ] && [[ "$relative" =~ (^|/)semantic-search/ ]]; then continue; fi
    target=$(managed_target "$destination" "$relative") || return 1
    content=$(cat -- "$source_file" && printf '\034') || return
    content=${content%$'\034'}
    needs_sub=false
-    if { [ "$flashbang_enabled" = false ] || [ "$statusline_enabled" = false ]; } && [[ "$relative" = settings.json || "$relative" = config.toml ]]; then
-      content=$(python3 "$(dirname -- "${BASH_SOURCE[0]}")/install-options.py" filter --path "$source_file" --flashbang "$flashbang_enabled" --statusline "$statusline_enabled" && printf '\034') || return
+    if { [ "$flashbang_enabled" = false ] || [ "$statusline_enabled" = false ] || [ "$semantic_retrieval_enabled" = false ]; } && [[ "$relative" = settings.json || "$relative" = config.toml ]]; then
+      content=$(python3 "$(dirname -- "${BASH_SOURCE[0]}")/install-options.py" filter --path "$source_file" --flashbang "$flashbang_enabled" --statusline "$statusline_enabled" --semantic-retrieval "$semantic_retrieval_enabled" && printf '\034') || return
+      content=${content%$'\034'}
+      needs_sub=true
+    fi
+    if [[ "$relative" = CLAUDE.md || "$relative" = AGENTS.md ]] || { [ "$semantic_retrieval_enabled" = false ] && [ "$relative" = rules/general.md ]; }; then
+      content=$(python3 "$(dirname -- "${BASH_SOURCE[0]}")/install-options.py" filter-instructions --path "$source_file" --destination "$destination" --semantic-retrieval "$semantic_retrieval_enabled" && printf '\034') || return
      content=${content%$'\034'}
      needs_sub=true
    fi
@@ -185,47 +245,15 @@ run_managed_sync() {
    fi
    new_manifest[$relative]=$new_hash

-    exists=false
-    [ -f "$target" ] && exists=true
-    if [ "$exists" = true ]; then
-      current_hash=$(sha256_of_file "$target")
-      if [ "$current_hash" = "$new_hash" ]; then
-        unchanged=$((unchanged + 1))
-        [ "$summary" = true ] || printf 'UNCHANGED %s\n' "$target"
-        continue
-      fi
-      action=UPDATE
-    else
    action=CREATE
+    if [ -f "$target" ]; then
+      action=UPDATE
+      current_hash=$(sha256_of_file "$target")
+      [ "$current_hash" != "$new_hash" ] || action=UNCHANGED
    fi
-
-    if [ "$dry_run" = true ]; then
-      [ "$summary" = true ] || printf 'DRYRUN %s %s\n' "$action" "$target"
-      [ "$action" = CREATE ] && created=$((created + 1)) || updated=$((updated + 1))
-      continue
-    fi
-
-    if [ "$exists" = true ]; then
-      backup=$(managed_target "$backup_root" "$stamp/$relative") || return 1
-      mkdir -p "$(dirname -- "$backup")"
-      cp -- "$target" "$backup"
-      [ "$summary" = true ] || printf 'BACKUP %s -> %s\n' "$target" "$backup"
-      if [ -z "${old_manifest[$relative]+x}" ]; then
-        printf 'WARN %s existed before this installation but was not tracked by a previous run; it was backed up before being overwritten.\n' "$target"
-        warned=$((warned + 1))
-      fi
-    fi
-    mkdir -p "$(dirname -- "$target")"
-    if [ "$needs_sub" = true ]; then
-      local rendered
-      rendered=$(mktemp) || return 1
-      printf '%s' "$content" > "$rendered" && write_managed_file "$target" "$rendered" "$source_file" || { rm -f -- "$rendered"; return 1; }
-      rm -f -- "$rendered"
-    else
-      write_managed_file "$target" "$source_file" "$source_file" || return 1
-    fi
-    [ "$summary" = true ] || printf '%s %s\n' "$action" "$target"
-    [ "$action" = CREATE ] && created=$((created + 1)) || updated=$((updated + 1))
+    [ "$needs_sub" = true ] || content=''
+    plan_relative+=("$relative"); plan_target+=("$target"); plan_action+=("$action"); plan_hash+=("$new_hash")
+    plan_source+=("$source_file"); plan_sub+=("$needs_sub"); plan_content+=("$content")
  done < <(find "$source" -type f -print0)

  local relative target current_hash backup
@@ -233,27 +261,91 @@ run_managed_sync() {
    [ -z "${new_manifest[$relative]+x}" ] || continue
    target=$(managed_target "$destination" "$relative") || return 1
    [ -f "$target" ] || continue
-    if [ "$dry_run" = true ]; then
-      [ "$summary" = true ] || printf 'DRYRUN REMOVE %s\n' "$target"
-      removed=$((removed + 1))
+    # A stale file changed locally is backed up but kept; only an unmodified one is removed.
+    action=KEEP
+    [ "$(sha256_of_file "$target")" != "${old_manifest[$relative]}" ] || action=REMOVE
+    plan_relative+=("$relative"); plan_target+=("$target"); plan_action+=("$action"); plan_hash+=('')
+    plan_source+=(''); plan_sub+=(false); plan_content+=('')
+  done
+
+  local index entry journal_content first_entry=true
+  if [ "$dry_run" != true ]; then
+    journal_content=$(mktemp) || return 1
+    {
+      printf '{"stamp": %s, "files": [' "$(json_string "$stamp")"
+      for index in "${!plan_action[@]}"; do
+        case "${plan_action[$index]}" in
+          CREATE) entry=$(printf '{"path": %s, "action": "create", "sha256": "%s"}' "$(json_string "${plan_relative[$index]}")" "${plan_hash[$index]}") ;;
+          UPDATE) entry=$(printf '{"path": %s, "action": "update", "backup": %s, "sha256": "%s"}' "$(json_string "${plan_relative[$index]}")" "$(json_string "$stamp/${plan_relative[$index]}")" "${plan_hash[$index]}") ;;
+          REMOVE) entry=$(printf '{"path": %s, "action": "remove", "backup": %s}' "$(json_string "${plan_relative[$index]}")" "$(json_string "$stamp/${plan_relative[$index]}")") ;;
+          *) continue ;;
+        esac
+        [ "$first_entry" = true ] || printf ', '
+        first_entry=false
+        printf '%s' "$entry"
+      done
+      printf ']}\n'
+    } > "$journal_content" && mkdir -p -- "$destination" && write_managed_file "$journal" "$journal_content" || { rm -f -- "$journal_content"; return 1; }
+    rm -f -- "$journal_content"
+  fi
+
+  for index in "${!plan_action[@]}"; do
+    relative=${plan_relative[$index]} target=${plan_target[$index]} action=${plan_action[$index]}
+    if [ "$action" = UNCHANGED ]; then
+      unchanged=$((unchanged + 1))
+      [ "$summary" = true ] || printf 'UNCHANGED %s\n' "$target"
      continue
    fi
+    if [ "$dry_run" = true ]; then
+      case "$action" in
+        REMOVE|KEEP) [ "$summary" = true ] || printf 'DRYRUN REMOVE %s\n' "$target"; removed=$((removed + 1)) ;;
+        *) [ "$summary" = true ] || printf 'DRYRUN %s %s\n' "$action" "$target"; [ "$action" = CREATE ] && created=$((created + 1)) || updated=$((updated + 1)) ;;
+      esac
+      continue
+    fi
+    if [ "$action" != CREATE ]; then
      backup=$(managed_target "$backup_root" "$stamp/$relative") || return 1
      mkdir -p "$(dirname -- "$backup")"
-    cp -- "$target" "$backup"
+      # Atomic, so a rollback after an interruption never restores a truncated backup.
+      write_managed_file "$backup" "$target" "$target" || return 1
      [ "$summary" = true ] || printf 'BACKUP %s -> %s\n' "$target" "$backup"
-    current_hash=$(sha256_of_file "$target")
-    if [ "$current_hash" = "${old_manifest[$relative]}" ]; then
+    fi
+    case "$action" in
+      REMOVE)
        rm -f -- "$target"
        [ "$summary" = true ] || printf 'REMOVE %s\n' "$target"
        removed=$((removed + 1))
-    else
+        continue
+        ;;
+      KEEP)
        printf 'WARN %s was managed by a previous installation and has changed locally; it was backed up but left in place instead of being removed.\n' "$target"
        warned=$((warned + 1))
+        continue
+        ;;
+      UPDATE)
+        if [ -z "${old_manifest[$relative]+x}" ]; then
+          printf 'WARN %s existed before this installation but was not tracked by a previous run; it was backed up before being overwritten.\n' "$target"
+          warned=$((warned + 1))
        fi
+        ;;
+    esac
+    mkdir -p "$(dirname -- "$target")"
+    if [ "${plan_sub[$index]}" = true ]; then
+      local rendered
+      rendered=$(mktemp) || return 1
+      printf '%s' "${plan_content[$index]}" > "$rendered" && write_managed_file "$target" "$rendered" "${plan_source[$index]}" || { rm -f -- "$rendered"; return 1; }
+      rm -f -- "$rendered"
+    else
+      write_managed_file "$target" "${plan_source[$index]}" "${plan_source[$index]}" || return 1
+    fi
+    [ "$summary" = true ] || printf '%s %s\n' "$action" "$target"
+    [ "$action" = CREATE ] && created=$((created + 1)) || updated=$((updated + 1))
  done

-  if [ "$dry_run" != true ]; then write_managed_manifest "$manifest" new_manifest || return 1; fi
+  if [ "$dry_run" != true ]; then
+    write_managed_manifest "$manifest" new_manifest || return 1
+    rm -f -- "$journal"
+  fi
  if [ "$summary" = true ]; then
    printf 'SYNC %s: %s created, %s updated, %s unchanged, %s removed, %s warnings\n' "$destination" "$created" "$updated" "$unchanged" "$removed" "$warned"
  fi
@@ -0,0 +1,99 @@
+"""Keep the client startup rule in sync with its personal instructions."""
+
+import argparse
+import hashlib
+import os
+from pathlib import Path
+import stat
+import tempfile
+
+
+CLIENT_FILES = {'codex': 'AGENTS.md', 'claude': 'CLAUDE.md'}
+START = '<!-- ai-config:personal-instructions -->'
+END = '<!-- /ai-config:personal-instructions -->'
+
+
+def checked_path(home, *parts):
+    path = home
+    for part in parts:
+        path = path / part
+        if path.is_symlink() or (hasattr(path, 'is_junction') and path.is_junction()):
+            raise ValueError(f'Personal instruction path must not be a link: {path}')
+    return path
+
+
+def render(text, home, client):
+    reference = f'~/.my-ai-configuration/instructions/{client}.md'
+    # Migrate the two previously generated unconditional loaders.
+    for legacy in (
+        f"Read `{reference}` first when present; it is the user's direct instruction. System and developer requirements still apply.",
+        f"Optional personal instructions: first check whether `{reference}` is a file (`Test-Path -LiteralPath ... -PathType Leaf` in PowerShell; `test -f ...` in Bash). Read it only if it exists; otherwise continue silently. Its contents are the user's direct instructions. System and developer requirements still apply.",
+    ):
+        text = text.replace(legacy + '\r\n\r\n', '').replace(legacy + '\n\n', '')
+    if START in text:
+        start = text.index(START)
+        end = text.find(END, start)
+        if end < 0:
+            raise ValueError('Personal instruction rule is missing its closing marker.')
+        end += len(END)
+        tail = text[end:]
+        for separator in ('\r\n\r\n', '\n\n'):
+            if tail.startswith(separator):
+                tail = tail[len(separator):]
+                break
+        text = text[:start] + tail
+    overlay = checked_path(home, '.my-ai-configuration', 'instructions', f'{client}.md')
+    if not overlay.is_file() or not overlay.read_text(encoding='utf-8-sig').strip():
+        return text
+    rule = (f'Read `{reference}` immediately, before any response or task work. '
+            'Keep its instructions active throughout the session, including after compaction. '
+            "These are the user's direct instructions. System and developer requirements still apply.")
+    return f'{START}\n{rule}\n{END}\n\n{text}'
+
+
+def write_atomic(path, updated):
+    temporary = None
+    try:
+        with tempfile.NamedTemporaryFile(dir=path.parent, prefix='.instruction-', delete=False) as file:
+            temporary = Path(file.name)
+            file.write(updated)
+        os.chmod(temporary, stat.S_IMODE(path.stat().st_mode))
+        os.replace(temporary, path)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+
+
+def refresh(home, client):
+    path = checked_path(home, f'.{client}', CLIENT_FILES[client])
+    if not path.is_file():
+        return
+    raw = path.read_bytes()
+    encoding = 'utf-8-sig' if raw.startswith(b'\xef\xbb\xbf') else 'utf-8'
+    updated = render(raw.decode(encoding), home, client).encode(encoding)
+    if updated == raw:
+        return
+    manifest = checked_path(home, f'.{client}', '.ai-config-manifest.tsv')
+    manifest_raw = manifest.read_bytes() if manifest.is_file() else b''
+    old_entry = f'{path.name}\t{hashlib.sha256(raw).hexdigest()}'.encode()
+    new_entry = f'{path.name}\t{hashlib.sha256(updated).hexdigest()}'.encode()
+    # Keep setup-owned files removable; preserve the stale hash of any preexisting user edits.
+    manifest_updated = b''.join(new_entry + line[len(old_entry):]
+                                if line.rstrip(b'\r\n').lower() == old_entry.lower() else line
+                                for line in manifest_raw.splitlines(keepends=True))
+    write_atomic(path, updated)
+    if manifest_updated != manifest_raw:
+        write_atomic(manifest, manifest_updated)
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--home', type=Path, required=True)
+    parser.add_argument('--client', choices=CLIENT_FILES, required=True)
+    args = parser.parse_args()
+    if not args.home.is_absolute():
+        parser.error('Home path must be absolute.')
+    try:
+        refresh(args.home, args.client)
+    except (OSError, ValueError) as error:
+        parser.exit(1, f'Personal instructions: {error}\n')
@@ -125,9 +125,7 @@ function Select-ConfiguredPlugins {
        } else { $false }
        foreach ($referenceClient in $referenceClients) {
            $selector = if ($referenceClient -eq 'Claude') { $entry.claude_plugin } else { $entry.codex_plugin }
-            if ($referenceClient -eq 'Codex' -and $entry.codex_method -eq 'qmd') {
-                $found = $found -or ($null -ne (Get-Command qmd -ErrorAction SilentlyContinue))
-            } elseif ($referenceClient -eq 'Codex' -and $entry.codex_method -ne 'plugin') {
+            if ($referenceClient -eq 'Codex' -and $entry.codex_method -ne 'plugin') {
                $found = $found -or (Test-Path -LiteralPath (Join-Path $HomePath ('.agents/skills/' + $entry.codex_skill))) -or (Test-Path -LiteralPath (Join-Path $HomePath ('.codex/skills/' + $entry.codex_skill)))
            } else {
                $idField = if ($referenceClient -eq 'Claude') { 'id' } else { 'pluginId' }
@@ -161,9 +161,7 @@ select_configured_plugins() {
    fi
    for reference_client in "${reference_clients[@]}"; do
      if [ "$reference_client" = claude ]; then selector=$(plugin_field "$root" "$name" claude_plugin); else selector=$(plugin_field "$root" "$name" codex_plugin); fi
-      if [ "$reference_client" = codex ] && [ "$(plugin_field "$root" "$name" codex_method)" = qmd ]; then
-        command -v qmd >/dev/null 2>&1 && found=true
-      elif [ "$reference_client" = codex ] && [ "$(plugin_field "$root" "$name" codex_method)" != plugin ]; then
+      if [ "$reference_client" = codex ] && [ "$(plugin_field "$root" "$name" codex_method)" != plugin ]; then
        local skill_name
        skill_name=$(plugin_field "$root" "$name" codex_skill)
        { [ -d "$HOME/.agents/skills/$skill_name" ] || [ -d "$HOME/.codex/skills/$skill_name" ]; } && found=true
@@ -0,0 +1,18 @@
+function Sync-Qmd {
+    param([Parameter(Mandatory=$true)][string]$RepositoryRoot,[Parameter(Mandatory=$true)][string]$HomePath,[ValidateSet('Codex','Claude','Both')][Parameter(Mandatory=$true)][string]$Client,[Parameter(Mandatory=$true)][bool]$Enabled,[switch]$DryRun,[switch]$Update,[switch]$Summary)
+    $arguments = @((Join-Path $PSScriptRoot 'qmd.py'), 'sync', '--root', $RepositoryRoot, '--home', $HomePath, '--client', $Client.ToLowerInvariant(), '--enabled', $Enabled.ToString().ToLowerInvariant())
+    if ($DryRun) { $arguments += '--dry-run' }; if ($Update) { $arguments += '--update' }
+    if ($Summary) { $arguments += '--summary' }
+    & python @arguments
+    if ($LASTEXITCODE -ne 0) { throw 'QMD local search reconciliation failed.' }
+}
+
+function Test-QmdDevice {
+    param([Parameter(Mandatory=$true)][string]$RepositoryRoot,[Parameter(Mandatory=$true)][string]$HomePath,[switch]$Summary)
+    $arguments = @((Join-Path $PSScriptRoot 'qmd.py'), 'benchmark', '--root', $RepositoryRoot, '--home', $HomePath)
+    if ($Summary) { $arguments += '--summary' }
+    & python @arguments | Write-Host
+    if ($LASTEXITCODE -eq 0) { return $true }
+    if ($LASTEXITCODE -eq 2) { return $false }
+    throw 'QMD benchmark failed.'
+}