docs: refresh configuration guides and remove obsolete plans

docs/configuration.md

@@ -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 workspace sandboxing with shell network access, 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.
 
@@ -33,6 +46,78 @@ 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`. |
+
+Codex's adapter grants writable roots for `~/.my-ai-configuration/qmd` and `~/.cache/qmd`.
+A custom cache location needs a matching writable root. QMD also writes its configuration when registering
+collections and persisting ignore lists; the resolved configuration directory must be writable under the
+active sandbox. These adapter roots do not themselves grant access to `~/.config/qmd`.
+
+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. Windows sandbox setup and child-process pipe restrictions can prevent
+repository discovery or daemon startup; see [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.