@aperant/framework 0.9.0 → 0.10.0

package/drivers/tauri/manifest.json

@@ -0,0 +1,37 @@
+{
+	"driverId": "tauri",
+	"version": "0.1.0",
+	"targets": ["tauri@>=1"],
+	"capabilities": [
+		"click",
+		"type",
+		"key",
+		"navigate",
+		"screenshot",
+		"assert_visible",
+		"assert_text",
+		"wait_for_idle",
+		"execute_js",
+		"dump_state"
+	],
+	"evidence_capabilities": ["screenshot", "dom_dump", "capture_logs"],
+	"frameworkApiRange": "^1.0.0",
+	"priority": 85,
+	"stability": "ga",
+	"trust": {
+		"tier": "first_party_signed",
+		"publisher": {
+			"name": "Aperant",
+			"npm_scope": "@aperant",
+			"github_org": "Mikalsen-AI",
+			"verified": true
+		}
+	},
+	"security": {
+		"sandbox_profile": "workspace_write",
+		"network": "deny",
+		"requires_user_approval": false
+	},
+	"audit": { "log_invocations": true, "log_manifest_hash": true },
+	"transport": { "mcp_server_id": "tauri" }
+}

package/drivers/tauri/scripts/tauri-mcp.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Launches the tauri-plugin-mcp-server with the project's .env injected.
+# Generated by `apt-tools init` (Aperant Framework) and referenced from the
+# host CLI's MCP config as: { command: "bash", args: ["./scripts/tauri-mcp.sh"] }
+#
+# This launcher exists because the tauri-plugin-mcp-server npm bin ships
+# WITHOUT a shebang, so `npx -y tauri-plugin-mcp-server` runs the .js as a
+# shell script and fails. We invoke the bin via `node` with a stable path.
+#
+# Idempotent: this file is never overwritten once present (edit it freely).
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+# Load .env (gitignored) WITHOUT executing it. We do NOT dot-source the file
+# (that would run any `$(...)`, backticks, or function defs it contains as
+# shell). Instead parse it line-by-line: skip blank/comment lines, and export
+# only well-formed `KEY=VALUE` assignments whose key is a valid shell name.
+if [[ -f "$ROOT/.env" ]]; then
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    # Strip a leading `export ` prefix if present.
+    line="${line#export }"
+    # Skip blank lines and comments.
+    [[ -z "$line" || "$line" == \#* ]] && continue
+    # Only accept lines of the form NAME=VALUE (bash-style identifier name).
+    if [[ "$line" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; then
+      key="${line%%=*}"
+      value="${line#*=}"
+      export "$key=$value"
+    fi
+  done < "$ROOT/.env"
+fi
+
+export TAURI_MCP_CONNECTION_TYPE="${TAURI_MCP_CONNECTION_TYPE:-ipc}"
+export TAURI_MCP_IPC_PATH="${TAURI_MCP_IPC_PATH:-$HOME/.{{PROJECT_SOCKET}}-mcp.sock}"
+
+# Install the transport package as a devDependency first:
+#   pnpm add -D tauri-plugin-mcp-server
+# and add the tauri-plugin-mcp Rust plugin to your app (see drivers/tauri/README.md).
+exec node "$ROOT/node_modules/tauri-plugin-mcp-server/build/index.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aperant/framework",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
   "author": "Mikalsen AI <hello@mikalsen.ai>",
   "type": "module",

package/skills/apt-pr-review/SKILL.md

@@ -469,6 +469,55 @@ fi
 
 After this point, the per-round artifact root is `.aperant/pr-reviews/pr-${PR_NUMBER}/rounds/${ROUND}/` (the `${REVIEW_ID}` is still used for the git worktree branch and temporary files). Subsequent `git diff` invocations within the round use `${PINNED_HEAD_SHA}` as the head ref.
 
+### Step 4c: Mergeability Pre-Check (PR reviews only)
+
+**Why this exists.** The review diff is `git diff {BASE}...{HEAD}` (three-dot — from the *merge-base*), so it shows the PR's own changes relative to where it branched. It is **blind to drift on `{BASE}` since then** and therefore says nothing about whether the PR still merges cleanly. A PR can pass a glowing review and be unmergeable. This step closes that gap: it is **informational, never blocking** (the review still runs in full), but a conflicting/stale state MUST be surfaced so the reader doesn't trust a review of a diff that no longer applies.
+
+```bash
+# PR-mode only. Query GitHub's authoritative mergeability + measure drift.
+if [ -n "$PR_NUMBER" ]; then
+  MERGE_JSON=$(gh pr view ${PR_NUMBER} --json mergeable,mergeStateStatus,baseRefName 2>/dev/null)
+  MERGEABLE=$(echo "$MERGE_JSON" | jq -r '.mergeable // "UNKNOWN"')
+  MERGE_STATE=$(echo "$MERGE_JSON" | jq -r '.mergeStateStatus // "UNKNOWN"')
+  BASE_REF=$(echo "$MERGE_JSON" | jq -r '.baseRefName // "main"')
+  git fetch origin "${BASE_REF}" 2>/dev/null
+  BEHIND=$(git rev-list --count ${PINNED_HEAD_SHA}..origin/${BASE_REF} 2>/dev/null || echo "?")
+  AHEAD=$(git rev-list --count origin/${BASE_REF}..${PINNED_HEAD_SHA} 2>/dev/null || echo "?")
+
+  # If GitHub reports a conflict (or hasn't computed yet), enumerate the conflicting
+  # files locally without touching any working tree (git >= 2.38):
+  CONFLICT_FILES=""
+  if [ "$MERGEABLE" = "CONFLICTING" ] || [ "$MERGE_STATE" = "DIRTY" ]; then
+    CONFLICT_FILES=$(git merge-tree --write-tree --name-only origin/${BASE_REF} ${PINNED_HEAD_SHA} 2>/dev/null \
+                     | tail -n +2 | sed '/^$/d' | grep '/' )
+  fi
+fi
+```
+
+Record the result in `metadata.json` under a `mergeability` key:
+
+```json
+{
+  "mergeability": {
+    "mergeable": "CONFLICTING | MERGEABLE | UNKNOWN",
+    "merge_state_status": "DIRTY | CLEAN | BLOCKED | BEHIND | ...",
+    "base_ref": "main",
+    "commits_behind_base": 101,
+    "commits_ahead_base": 91,
+    "conflicting_files": ["apps/.../App.tsx", "..."]
+  }
+}
+```
+
+**How to use the result:**
+
+- `MERGEABLE` ∈ {`CONFLICTING`} OR `MERGE_STATE` = `DIRTY` → the PR has conflicts. Surface a **⚠️ Mergeability** block in the Phase 5 intermediate report AND the Phase 8 final report, listing `commits_behind_base` and the `conflicting_files`. In **external / comment-only** mode, include the same block in the Phase 6b comment. State plainly that the branch needs a rebase/merge from `{BASE}` and that **the reviewed diff may be stale** with respect to current `{BASE}`.
+- `MERGE_STATE` = `BEHIND` (mergeable but behind) → note the drift (`commits_behind_base`) as a softer advisory; no conflict, but the diff predates recent `{BASE}` commits.
+- `MERGEABLE` = `UNKNOWN` (GitHub hasn't finished computing, common right after a push) → record `UNKNOWN`; optionally re-poll once after a few seconds. Do not block.
+- `MERGEABLE` = `MERGEABLE`, `MERGE_STATE` = `CLEAN` → record it and move on silently.
+
+This step never changes the review's findings or assessment — a conflicting PR with zero code findings is still `approve` on its own merits. Mergeability is reported as a **separate** signal so the reader knows whether the approval can actually land.
+
 ### Step 5: Read All Changed Files
 
 For every file in the changed file list, read it in full using the Read tool **from the worktree**:
@@ -1058,6 +1107,10 @@ Review Synthesis (Before Auto-Fix)
 Auto-Checks: {PASS/FAIL}
   lint: {P/F} | typecheck: {P/F} | tests: {P/F}
 
+Mergeability (PR reviews — from Step 4c): {MERGEABLE/CONFLICTING/UNKNOWN}
+  {if CONFLICTING/DIRTY: "⚠️ conflicts with {BASE} — {behind} commits behind — needs rebase — reviewed diff may be stale"}
+  {if conflicting_files: list them}
+
 Validated Findings:
   CRITICAL: {N}
   HIGH: {N}
@@ -1630,6 +1683,7 @@ Output the human-readable summary:
 
   Review ID: {REVIEW_ID}
   Assessment: {APPROVE / REQUEST CHANGES / COMMENT}
+  Mergeability: {MERGEABLE / CONFLICTING (N behind {BASE}, needs rebase) / UNKNOWN}   # PR reviews — from Step 4c / metadata.json.mergeability
 
   Scores:
     Security:      {score}/10

package/skills/apt-verify/SKILL.md

@@ -60,7 +60,7 @@ Before spawning any verifier subagent or running scoring against acceptance crit
 </locked_decisions>
 ```
 
-Verifiers apply this digest when interpreting "completeness" and "correctness" — if a decision explicitly deferred a behavior, its absence is NOT a verification failure.
+Verifiers apply this digest when interpreting "completeness" and "correctness" — if a decision explicitly deferred a behavior AND the deferred finding has severity below critical or major, its absence is NOT a verification failure. A deferred critical or major finding IS a Completeness gap — score accordingly and note it in the issues list.
 </decision_ledger_inject>
 
 <process>

package/skills/apt-verify-proof/SKILL.md

@@ -20,6 +20,7 @@ gates: []
 config_keys:
   - verification.open_report
   - verification.report_formats
+  - verification.provision_mcp
 ---
 
 # Proof Verification
@@ -104,13 +105,36 @@ disable the walk entirely (root-only behaviour, backwards compat).
 The `verification.runtimes[]` override stays the final escape hatch
 and is now usually unnecessary because the walk runs by default.
 
-### Bundled drivers (4)
+### Bundled drivers (5)
 
 - **browser** (priority=100, ga) — Next.js / vanilla web frontends.
 - **electron** (priority=90, ga) — Electron desktop apps.
+- **tauri** (priority=85, ga) — Tauri desktop apps.
 - **cli** (priority=60, ga) — headless CI, output-shape assertions.
 - **api** (priority=50, ga) — HTTP / JSON-API regression tests.
 
+### Install-time MCP provisioning (verification.provision_mcp)
+
+`apt-tools init` (and `/apt:update`, which routes through the same path)
+auto-provisions the MCP transport a driver needs into each SELECTED host
+CLI's config, so verify-proof works at the prompt with no manual MCP
+setup. It detects the project runtime and, per host:
+
+- **claude** → JSON-merges the server into the project-root `.mcp.json`
+  (`mcpServers.<id>`).
+- **codex** → upserts a `[mcp_servers.<id>]` table into the project-root
+  `.codex/config.toml`.
+
+Electron and Tauri projects get the matching MCP server; web frontends
+get the browser driver's declared `agent-browser` skill copied into the
+host skill dir (`.claude/skills/` / `.agents/skills/`) — its `agent-browser`
+CLI is a documented one-time prereq, the same class as the
+`electron-mcp-server` / `tauri-plugin-mcp-server` npm packages (see each
+driver's README). All writes are **TOFU/non-clobbering**: a pre-existing
+server id, config table, or skill file is never overwritten. Opt out with
+`verification.provision_mcp: false` (default `true`) — then init/update
+writes no host MCP config and no skill.
+
 ### Driver authors
 
 Third-party driver authors should run `apt-tools driver doctor .` before

package/src/cli/commands/init.mjs

@@ -32,6 +32,7 @@ import { deriveSidecar } from '../bootstrap/product-context-sidecar.mjs'
 import { assertConfigWriteAllowed } from '../config/guard.mjs'
 import {
 	AUDIT_001_LOCAL_FIELDS,
+	loadMergedProjectConfig,
 	migrateDeferredFieldsToLocalConfig,
 	writeLocalConfigField,
 } from '../config/load.mjs'
@@ -42,6 +43,7 @@ import { detectPublicRemote } from '../git/remote.mjs'
 import { detectArchetype } from '../install/archetype.mjs'
 import { installKernel } from '../install/install-kernel.mjs'
 import { MANIFEST_FILENAME } from '../install/manifest.mjs'
+import { provisionMcpConfig } from '../install/mcp-provision.mjs'
 import {
 	discoverCanonicalFiles,
 	runInstall,
@@ -1304,6 +1306,23 @@ export async function cmdInit(projectDir, extraArgs = []) {
 		if (envelope?.__earlyExit) {
 			return envelope.__earlyExit
 		}
+
+		// Auto-provision host MCP-server config + the agent-browser skill for
+		// the detected runtime (C38). Runs on BOTH the fresh install AND the
+		// no-drift /apt:update upgrade path (both reach finishInit). finishInit
+		// has already written .aperant/config.json from the template, so the
+		// merged config carries verification.provision_mcp (default true) — the
+		// opt-out gate. TOFU/non-clobbering; never throws.
+		const mergedConfig = loadMergedProjectConfig(installTarget)
+		const mcpProvision = provisionMcpConfig({
+			targetDir: installTarget,
+			selectedRuntimes: effectiveAnswers.runtimes,
+			config: mergedConfig,
+			frameworkRoot: canonicalRoot,
+			version,
+		})
+		envelope.mcp_provision = mcpProvision
+
 		if (interactiveTty) {
 			await renderOutro(effectiveAnswers, results, version, kernelResult)
 			// TTY mode: envelope was persisted to disk + suppressed from stdout

package/src/cli/consistency/parse-review.mjs

@@ -97,9 +97,11 @@ function normalizeStatus(f) {
 		if (STATUS_MAP[s]) return STATUS_MAP[s]
 		// BUG-009: reviewer-skill writes `deferred-per-spec`, `deferred-followup`,
 		// etc. for findings that are intentionally not being fixed in the
-		// current scope. Collapse the variant prefix back to canonical
-		// `deferred` so downstream gates (review-clean, ship) treat them
-		// the same as a bare `status: "deferred"`.
+		// current scope. Collapse the variant prefix back to canonical `deferred`.
+		// Note: for blocking severities (critical/major), `deferred` no longer
+		// clears review-clean or R5 (G42 Phase 1). Only `status: "fixed"` clears
+		// those gates. Non-blocking severities (suggestion/note) are dropped by
+		// normalizeSeverity and never reach the blocking filter.
 		if (s.startsWith('deferred-')) return 'deferred'
 	}
 	return 'open'

package/src/cli/consistency/rules/r5-verdict-consistency.mjs

@@ -3,12 +3,13 @@
  * consistency/rules/r5-verdict-consistency.mjs — R5 (C15).
  *
  * Fails when:
- *   - qa.verdict === 'approved' AND review has >=1 unresolved critical finding
+ *   - qa.verdict === 'approved' or 'approved-with-notes' AND review has >=1
+ *     unresolved critical or major finding
  *   - qa.verdict === 'rejected' AND qa has no findings at all AND review has
  *     zero unresolved findings (rejected-without-evidence)
  *
- * `approved-with-notes` is the escape hatch — passes regardless of unresolved
- * criticals in review.json.
+ * `approved-with-notes` no longer escapes unresolved critical or major
+ * findings (G42 Phase 1). It still passes for lower-severity issues.
  *
  * Severity: error. Stages: verify, ship.
  */
@@ -26,23 +27,27 @@ const rule = {
 		}
 		const verdict = parsed.qa.verdict ?? 'unknown'
 		const reviewFindings = parsed?.review?.findings ?? []
-		const unresolvedCritical = reviewFindings.filter(
-			(f) => f.severity === 'critical' && f.status !== 'fixed',
+		const unresolvedBlocking = reviewFindings.filter(
+			(f) => (f.severity === 'critical' || f.severity === 'major') && f.status !== 'fixed',
 		)
-		if (verdict === 'approved' && unresolvedCritical.length > 0) {
+		if (
+			(verdict === 'approved' || verdict === 'approved-with-notes') &&
+			unresolvedBlocking.length > 0
+		) {
 			return {
 				status: 'fail',
 				drift: [
 					{
 						verdict,
-						blockers: unresolvedCritical.map((f) => ({
+						blockers: unresolvedBlocking.map((f) => ({
 							id: f.id,
 							title: f.title,
 						})),
-						reason: 'approved verdict with unresolved critical finding(s)',
+						reason:
+							'approved/approved-with-notes verdict with unresolved critical or major finding(s) (G42 Phase 1)',
 					},
 				],
-				reason: `approved verdict contradicts ${unresolvedCritical.length} unresolved critical finding(s)`,
+				reason: `approved/approved-with-notes verdict contradicts ${unresolvedBlocking.length} unresolved critical/major finding(s)`,
 			}
 		}
 		if (verdict === 'rejected') {

package/src/cli/gate/gates/review-clean.mjs

@@ -8,7 +8,9 @@
  * shapes the reviewer skill writes: `fixed: true`, `resolved: true`,
  * `status: "fixed"` (string), and `status: "deferred-*"` variants
  * (BUG-009). Fails if any post-normalization finding is severity
- * critical|major AND status is neither `fixed` nor `deferred`.
+ * critical|major AND status is not `fixed`. `deferred` no longer clears
+ * blocking findings (G42 Phase 1 — only `--force --reason` override may
+ * bypass blocking severity deferrals).
  */
 
 import { existsSync, readFileSync } from 'node:fs'
@@ -55,7 +57,7 @@ const gate = {
 		// hole and picks up `deferred-*` variants for free.
 		const { findings: normalized } = parseReview(doc)
 		const unresolved = normalized.filter(
-			(f) => POST_NORM_BLOCKING.has(f.severity) && f.status !== 'fixed' && f.status !== 'deferred',
+			(f) => POST_NORM_BLOCKING.has(f.severity) && f.status !== 'fixed',
 		)
 		if (unresolved.length > 0) {
 			return {

package/src/cli/install/mcp-provision.mjs

@@ -0,0 +1,293 @@
+/**
+ * install/mcp-provision.mjs — TOFU install-time MCP-server + skill provisioner.
+ *
+ * Called from cmdInit (the only call site — the QUICK fast-path never invokes
+ * init, so the Fast Path Guarantee is structurally untouched). Detects the
+ * project's runtime, then for each selected host CLI that supports the action:
+ *
+ *   - kind 'mcp-server' (electron/tauri) → write the server into the host's
+ *     MCP config (claude → .mcp.json JSON merge; codex → .codex/config.toml
+ *     TOML upsert).
+ *   - kind 'skill' (agent-browser) → copy the vendored SKILL.md into the
+ *     host's skill dir (claude → .claude/skills/; codex → .agents/skills/).
+ *
+ * Every write is TOFU/idempotent (ID-05): if the target server id / table /
+ * skill file already exists, SKIP (never diff/merge/overwrite) — this is the
+ * must-not-clobber invariant for a hand-authored electron
+ * SCREENSHOT_ENCRYPTION_KEY (US-3) and a user-edited agent-browser skill
+ * (US-6). Each action appends one audit line to .aperant/events/{date}.jsonl.
+ *
+ * Gated behind config.verification.provision_mcp (default true) so users can
+ * opt out. Never throws — wraps the body in try/catch → {status:'error'}.
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+import { appendJsonl, atomicWriteJson, atomicWriteText } from '../util/atomic-write.mjs'
+import { dailyEventsPath } from '../util/events-path.mjs'
+import { capabilityToProvisionIds, PROVISION_SPECS } from './mcp-server-specs.mjs'
+import { loadRuntimeCapabilities } from './runtime-detect.mjs'
+import { upsertMcpServerToml } from './toml-merge.mjs'
+
+/**
+ * Per-host writer registry (ID-07, ID-08). v1 = claude + codex. The MCP
+ * config path AND skill dir are EXPLICIT per host — neither is derived from
+ * the runtime's installRoot (Codex's MCP path .codex/config.toml diverges
+ * from its skill dir .agents/skills/). Adding gemini/opencode later = one
+ * entry each.
+ *
+ * @type {Record<string, {mcpFormat: 'json'|'toml', mcpConfigPath: string, skillDir: string}>}
+ */
+const HOST_PROVISION_WRITERS = {
+	claude: { mcpFormat: 'json', mcpConfigPath: '.mcp.json', skillDir: '.claude/skills' },
+	codex: { mcpFormat: 'toml', mcpConfigPath: '.codex/config.toml', skillDir: '.agents/skills' },
+}
+
+/**
+ * Substitute the per-project socket basename into the tauri launcher
+ * template, deriving uniqueness from the project dir basename.
+ *
+ * @param {string} template
+ * @param {string} targetDir
+ * @returns {string}
+ */
+function renderTauriLauncher(template, targetDir) {
+	const slug =
+		basename(resolve(targetDir))
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, '-')
+			.replace(/^-+|-+$/g, '') || 'tauri'
+	return template.replaceAll('{{PROJECT_SOCKET}}', slug)
+}
+
+/**
+ * Write the electron/tauri MCP server into a Claude `.mcp.json`. JSON merge:
+ * read-or-{}, ensure mcpServers, SKIP if the server id already exists, else
+ * insert {type:'stdio', command, args, env?} preserving all sibling keys.
+ *
+ * TOFU non-clobber (ID-05): if the existing file fails to parse OR parses to
+ * a non-plain-object root (array / null / primitive), do NOT overwrite it —
+ * return `skipped_unsafe` with a reason so the caller can audit it and leave
+ * the file byte-identical. (`typeof [] === 'object'` is why arrays must be
+ * excluded explicitly: a `.mcp.json` containing `[]` would otherwise pass the
+ * object guard, drop the user's content on stringify, and report `written`.)
+ *
+ * @param {string} configPath — absolute path to .mcp.json
+ * @param {string} serverId
+ * @param {import('./mcp-server-specs.mjs').McpServerSpec} spec
+ * @returns {{action: 'written'|'skipped'|'skipped_unsafe', reason?: string}}
+ */
+function writeClaudeMcpServer(configPath, serverId, spec) {
+	let config = {}
+	if (existsSync(configPath)) {
+		try {
+			config = JSON.parse(readFileSync(configPath, 'utf-8'))
+		} catch {
+			// Malformed JSON: overwriting would erase every hand-authored MCP
+			// server. Leave the file untouched and surface it.
+			return { action: 'skipped_unsafe', reason: 'malformed_json' }
+		}
+		if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+			// Non-plain-object root (array / null / primitive): same non-clobber
+			// rule — never overwrite content we cannot safely merge into.
+			return { action: 'skipped_unsafe', reason: 'non_object_root' }
+		}
+	}
+	if (config.mcpServers === null || typeof config.mcpServers !== 'object') {
+		config.mcpServers = {}
+	}
+	// TOFU: never clobber a hand-authored server id.
+	if (Object.hasOwn(config.mcpServers, serverId)) return { action: 'skipped' }
+
+	const entry = { type: 'stdio', command: spec.command, args: spec.args ?? [] }
+	if (spec.env && Object.keys(spec.env).length > 0) entry.env = spec.env
+	config.mcpServers[serverId] = entry
+	atomicWriteJson(configPath, config)
+	return { action: 'written' }
+}
+
+/**
+ * Write the electron/tauri MCP server into a Codex `.codex/config.toml`.
+ *
+ * @param {string} configPath — absolute path to .codex/config.toml
+ * @param {string} serverId
+ * @param {import('./mcp-server-specs.mjs').McpServerSpec} spec
+ * @returns {{action: 'written'|'skipped'}}
+ */
+function writeCodexMcpServer(configPath, serverId, spec) {
+	const existing = existsSync(configPath) ? readFileSync(configPath, 'utf-8') : ''
+	const { content, action } = upsertMcpServerToml(existing, serverId, {
+		command: spec.command,
+		args: spec.args ?? [],
+		...(spec.env && Object.keys(spec.env).length > 0 ? { env: spec.env } : {}),
+	})
+	if (action === 'written') atomicWriteText(configPath, content)
+	return { action }
+}
+
+/**
+ * Copy the vendored skill into a host skill dir. TOFU: never overwrite an
+ * existing agent-browser/SKILL.md (a user may have edited it).
+ *
+ * @param {string} skillDestPath — absolute <skillDir>/<skillId>/SKILL.md
+ * @param {string} vendoredSkillPath — absolute source path
+ * @returns {'written'|'skipped'}
+ */
+function copySkill(skillDestPath, vendoredSkillPath) {
+	if (existsSync(skillDestPath)) return 'skipped'
+	mkdirSync(dirname(skillDestPath), { recursive: true })
+	// copyFileSync is fine here — atomicWriteText would re-read; the dest is
+	// guaranteed absent (TOFU check above) so there is no clobber risk.
+	copyFileSync(vendoredSkillPath, skillDestPath)
+	return 'written'
+}
+
+/**
+ * Provision MCP servers + skills for the selected host CLIs.
+ *
+ * @param {Object} opts
+ * @param {string} opts.targetDir — project root being installed into
+ * @param {string[]} opts.selectedRuntimes — the runtimes the user selected
+ * @param {object} opts.config — the effective merged project config
+ * @param {string} opts.frameworkRoot — absolute path to packages/framework (for vendored skill resolution)
+ * @returns {{status: 'ok'|'disabled'|'error', writes?: Array<{host:string, spec_id:string, kind:string, action:string}>, reason?: string}}
+ */
+export function provisionMcpConfig(opts) {
+	const targetDir = resolve(opts.targetDir)
+	const config = opts.config ?? {}
+	const selected = Array.isArray(opts.selectedRuntimes) ? opts.selectedRuntimes : []
+	const frameworkRoot = opts.frameworkRoot
+
+	try {
+		// (1) Opt-out gate (default true).
+		if (config?.verification?.provision_mcp === false) {
+			appendEvent(targetDir, 'mcp-provision.disabled', {
+				reason: 'verification.provision_mcp=false',
+			})
+			return { status: 'disabled' }
+		}
+
+		// (2) Detect runtime → derive spec ids.
+		const runtimeCaps = loadRuntimeCapabilities(targetDir)
+		const specIds = capabilityToProvisionIds(runtimeCaps)
+
+		/** @type {Array<{host:string, spec_id:string, kind:string, action:string}>} */
+		const writes = []
+
+		// Iterate every (selected host, spec) pair.
+		for (const host of selected) {
+			const writer = HOST_PROVISION_WRITERS[host]
+			if (!writer) {
+				// Selected host with no writer (gemini/opencode/... in v1) — record
+				// once as unsupported_host, no write.
+				writes.push({ host, spec_id: '*', kind: '*', action: 'unsupported_host' })
+				appendEvent(targetDir, 'mcp-provision.unsupported_host', { host })
+				continue
+			}
+
+			for (const specId of specIds) {
+				const spec = PROVISION_SPECS[specId]
+				if (!spec) continue
+
+				if (spec.kind === 'mcp-server') {
+					const configPath = join(targetDir, writer.mcpConfigPath)
+					const { action, reason } =
+						writer.mcpFormat === 'json'
+							? writeClaudeMcpServer(configPath, specId, spec)
+							: writeCodexMcpServer(configPath, specId, spec)
+					writes.push({ host, spec_id: specId, kind: 'mcp-server', action })
+					appendEvent(targetDir, `mcp-provision.${action}`, {
+						host,
+						spec_id: specId,
+						config_path: writer.mcpConfigPath,
+						...(reason ? { reason } : {}),
+					})
+					// (5) tauri needs its launcher script — only provision it once the
+					// MCP config entry is actually written, so a TOFU-skipped or
+					// skipped_unsafe config never leaves an orphan launcher + a
+					// misleading audit line.
+					if (spec.requiresLauncherScript && frameworkRoot && action === 'written') {
+						provisionTauriLauncher(targetDir, frameworkRoot, writes)
+					}
+				} else if (spec.kind === 'skill') {
+					if (!frameworkRoot) continue
+					const vendoredSkillPath = resolve(frameworkRoot, spec.vendoredSkillRelPath)
+					const skillDestPath = join(targetDir, writer.skillDir, spec.skillId, 'SKILL.md')
+					const action = copySkill(skillDestPath, vendoredSkillPath)
+					writes.push({ host, spec_id: specId, kind: 'skill', action })
+					appendEvent(
+						targetDir,
+						`skill-provision.${action}`,
+						{
+							host,
+							spec_id: specId,
+							skill_dir: writer.skillDir,
+						},
+						'skill_provision',
+					)
+				}
+			}
+		}
+
+		return { status: 'ok', writes }
+	} catch (e) {
+		return { status: 'error', reason: e instanceof Error ? e.message : String(e) }
+	}
+}
+
+/**
+ * Copy the tauri launcher template into the project's scripts/ dir (TOFU).
+ * Records its own audit line; appends to `writes` with a synthetic host.
+ *
+ * @param {string} targetDir
+ * @param {string} frameworkRoot
+ * @param {Array<{host:string, spec_id:string, kind:string, action:string}>} writes
+ */
+function provisionTauriLauncher(targetDir, frameworkRoot, writes) {
+	const destPath = join(targetDir, 'scripts', 'tauri-mcp.sh')
+	// Already recorded a launcher write/skip for this run? Only provision once.
+	if (writes.some((w) => w.kind === 'launcher')) return
+	if (existsSync(destPath)) {
+		writes.push({ host: '-', spec_id: 'tauri', kind: 'launcher', action: 'skipped' })
+		appendEvent(targetDir, 'mcp-provision.skipped', {
+			host: '-',
+			spec_id: 'tauri',
+			launcher: 'scripts/tauri-mcp.sh',
+		})
+		return
+	}
+	const templatePath = resolve(frameworkRoot, 'drivers/tauri/scripts/tauri-mcp.sh')
+	const template = readFileSync(templatePath, 'utf-8')
+	atomicWriteText(destPath, renderTauriLauncher(template, targetDir))
+	writes.push({ host: '-', spec_id: 'tauri', kind: 'launcher', action: 'written' })
+	appendEvent(targetDir, 'mcp-provision.written', {
+		host: '-',
+		spec_id: 'tauri',
+		launcher: 'scripts/tauri-mcp.sh',
+	})
+}
+
+/**
+ * Append one audit line to .aperant/events/{date}.jsonl, mirroring the
+ * daily-events shape. `kind` discriminates the provisioning channel:
+ * `mcp_provision` for MCP-server + launcher events, `skill_provision` for
+ * skill-copy events.
+ *
+ * @param {string} targetDir
+ * @param {string} op — e.g. mcp-provision.written, skill-provision.skipped
+ * @param {Record<string, unknown>} [extra]
+ * @param {string} [kind] — audit channel (default `mcp_provision`)
+ */
+function appendEvent(targetDir, op, extra = {}, kind = 'mcp_provision') {
+	try {
+		const path = dailyEventsPath(targetDir)
+		appendJsonl(path, {
+			ts: new Date().toISOString(),
+			kind,
+			op,
+			...extra,
+		})
+	} catch {
+		// Audit is best-effort — never fail provisioning on a log write error.
+	}
+}