@diffci.com/diffci 0.1.11 → 0.2.0

package/dist-client/src/client/mcp.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+const SERVER_INFO = { name: "diffci-mcp", version: "0.1.0" };
+const tools = [
+    {
+        name: "diffci_check",
+        description: "Analyze the repository, run inferred full and selected test commands when available, and report paired runtime. Sends nothing to DiffCI Cloud.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                repo: { type: "string", description: "Repository path. Defaults to the MCP server working directory." },
+                base: { type: "string", description: "Optional base commit SHA." },
+                head: { type: "string", description: "Optional head commit SHA." },
+                json: { type: "boolean", description: "Print the full JSON observation report." },
+                quiet: { type: "boolean", description: "Suppress the human summary." },
+                redactPaths: { type: "boolean", description: "Replace paths with stable digests in the report." },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "diffci_init",
+        description: "Seed a repository with AI-agent instruction files for DiffCI.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                repo: { type: "string", description: "Repository path. Defaults to the MCP server working directory." },
+                workflow: { type: "boolean", description: "Also add the non-blocking GitHub Actions observer workflow." },
+                force: { type: "boolean", description: "Overwrite existing instruction files." },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "diffci_verify_workflow",
+        description: "Check that a DiffCI GitHub Actions job cannot affect the rest of CI.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                repo: { type: "string", description: "Repository path. Defaults to the MCP server working directory." },
+            },
+            additionalProperties: false,
+        },
+    },
+];
+function cliPath() {
+    return join(dirname(import.meta.filename), "cli.js");
+}
+function stringArg(args, name) {
+    const value = args[name];
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+function booleanArg(args, name) {
+    return args[name] === true;
+}
+function commandForTool(name, args) {
+    const repo = stringArg(args, "repo");
+    switch (name) {
+        case "diffci_check": {
+            const command = ["check"];
+            if (repo)
+                command.push("--repo", resolve(repo));
+            for (const flag of ["base", "head"]) {
+                const value = stringArg(args, flag);
+                if (value)
+                    command.push(`--${flag}`, value);
+            }
+            if (booleanArg(args, "json"))
+                command.push("--json");
+            if (booleanArg(args, "quiet"))
+                command.push("--quiet");
+            if (booleanArg(args, "redactPaths"))
+                command.push("--redact-paths");
+            return command;
+        }
+        case "diffci_init": {
+            const command = ["init"];
+            if (repo)
+                command.push("--repo", resolve(repo));
+            if (booleanArg(args, "workflow"))
+                command.push("--workflow");
+            if (booleanArg(args, "force"))
+                command.push("--force");
+            return command;
+        }
+        case "diffci_verify_workflow": {
+            const command = ["verify-workflow"];
+            if (repo)
+                command.push("--repo", resolve(repo));
+            return command;
+        }
+        default:
+            throw new Error(`unknown tool: ${name}`);
+    }
+}
+function runCli(args) {
+    return new Promise((resolveRun) => {
+        execFile(process.execPath, [cliPath(), ...args], {
+            cwd: process.cwd(),
+            env: { ...process.env, DIFFCI_MCP: "1" },
+            encoding: "utf8",
+            maxBuffer: 8 * 1024 * 1024,
+            windowsHide: true,
+        }, (error, stdout, stderr) => {
+            const code = error?.code;
+            const exitCode = typeof code === "number" ? code : error ? 1 : 0;
+            resolveRun({ exitCode, stdout, stderr });
+        });
+    });
+}
+function writeMessage(message) {
+    const body = JSON.stringify(message);
+    process.stdout.write(`Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n\r\n${body}`);
+}
+function success(id, result) {
+    if (id === undefined)
+        return;
+    writeMessage({ jsonrpc: "2.0", id, result });
+}
+function failure(id, code, message) {
+    if (id === undefined)
+        return;
+    writeMessage({ jsonrpc: "2.0", id, error: { code, message } });
+}
+async function handle(request) {
+    const id = request.id;
+    switch (request.method) {
+        case "initialize":
+            success(id, {
+                protocolVersion: "2024-11-05",
+                capabilities: { tools: {} },
+                serverInfo: SERVER_INFO,
+            });
+            return;
+        case "notifications/initialized":
+            return;
+        case "tools/list":
+            success(id, { tools });
+            return;
+        case "tools/call": {
+            const params = request.params;
+            if (!params?.name) {
+                failure(id, -32602, "tools/call requires params.name");
+                return;
+            }
+            const args = params.arguments ?? {};
+            const run = await runCli(commandForTool(params.name, args));
+            const text = [
+                run.stdout.trim(),
+                run.stderr.trim() ? `stderr:\n${run.stderr.trim()}` : "",
+                `exitCode: ${run.exitCode}`,
+            ].filter(Boolean).join("\n\n");
+            success(id, {
+                content: [{ type: "text", text }],
+                isError: run.exitCode !== 0,
+            });
+            return;
+        }
+        default:
+            failure(id, -32601, `unknown method: ${request.method ?? ""}`);
+    }
+}
+let buffer = Buffer.alloc(0);
+const decoder = new StringDecoder("utf8");
+function readMessages() {
+    while (true) {
+        const headerEnd = buffer.indexOf("\r\n\r\n");
+        if (headerEnd === -1)
+            return;
+        const header = decoder.write(buffer.subarray(0, headerEnd));
+        const match = /^Content-Length:\s*(\d+)\s*$/im.exec(header);
+        if (!match) {
+            buffer = buffer.subarray(headerEnd + 4);
+            continue;
+        }
+        const length = Number(match[1]);
+        const bodyStart = headerEnd + 4;
+        const bodyEnd = bodyStart + length;
+        if (buffer.length < bodyEnd)
+            return;
+        const body = buffer.subarray(bodyStart, bodyEnd).toString("utf8");
+        buffer = buffer.subarray(bodyEnd);
+        const request = JSON.parse(body);
+        void handle(request).catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            failure(request.id, -32603, message);
+        });
+    }
+}
+process.stdin.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    readMessages();
+});
+process.stdin.resume();

package/dist-client/src/client/observe.js

@@ -22,11 +22,7 @@
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { relative, resolve } from "node:path";
-import { analyzeGitDelta } from "@diffci.com/core/git/git-diff";
-import { classifyRepositoryProject, buildDependencyGraph } from "@diffci.com/core/repo/graph";
-import { ImpactAnalyzer } from "@diffci.com/core/repo/impact";
-import { runPathBaseline } from "@diffci.com/core/planner/path-baseline";
-import { commandSpecToString, planSelectiveTestCommands } from "@diffci.com/core/planner/test-command";
+import { economicsContext, evaluateEconomics } from "./economics.js";
 import { readCiEnvironment, resolveCommitRange, } from "./context.js";
 import { OBSERVATION_SCHEMA, redactPath, } from "./report.js";
 import { auditWorkflows } from "./workflow-guard.js";
@@ -72,6 +68,10 @@ export function isInsideRepository(repoPath, candidate) {
 }
 export async function observe(options) {
     const startedAt = Date.now();
+    const preObserveMs = Math.round(process.uptime() * 1000);
+    const phasesMs = {};
+    let phaseStart = performance.now();
+    const markPhase = (name) => { const now = performance.now(); phasesMs[name] = Math.round(now - phaseStart); phaseStart = now; };
     const repoPath = resolve(options.repoPath);
     const git = options.git ?? makeGitRunner(repoPath);
     const ci = readCiEnvironment(options.env);
@@ -81,6 +81,7 @@ export async function observe(options) {
     // Declared before `finish` closes over it: the range is part of every report, including the reports
     // produced by failures that happen after it was resolved.
     let range;
+    let economics;
     const finish = (status, stage, extra) => {
         const after = { head: headSha(git), worktree: worktreeDigest(git) };
         const nonInterference = {
@@ -95,6 +96,7 @@ export async function observe(options) {
             reportWrittenOutsideRepository: options.reportPath === undefined ? true : !isInsideRepository(repoPath, options.reportPath),
             workflowFindings: safeAuditWorkflows(repoPath),
         };
+        markPhase("finalization");
         return {
             schema: OBSERVATION_SCHEMA,
             producedAt: new Date().toISOString(),
@@ -125,6 +127,7 @@ export async function observe(options) {
             stage,
             reason: extra.reason,
             result: extra.result,
+            economics,
             payload: {
                 includesFilePaths: options.redactPaths !== true,
                 includesFileContents: false,
@@ -133,7 +136,7 @@ export async function observe(options) {
                 pathRedaction: options.redactPaths ? "sha256-12" : undefined,
             },
             nonInterference,
-            timings: { totalMs: Date.now() - startedAt },
+            timings: { totalMs: Date.now() - startedAt, preObserveMs, phasesMs },
         };
     };
     try {
@@ -146,12 +149,31 @@ export async function observe(options) {
         if (!resolved.ok)
             return finish("REFUSED", "context", { reason: resolved.reason });
         range = resolved.range;
+        markPhase("context");
+        if (options.economicsJobKey || options.economicsHistory) {
+            const remote = git(["remote", "get-url", "origin"]);
+            const repository = remote.ok ? /^(?:https:\/\/github\.com\/|git@github\.com:)([^/\s]+\/[^/\s]+?)(?:\.git)?$/.exec(remote.stdout.trim())?.[1] : undefined;
+            economics = evaluateEconomics(options.economicsHistory, { repository, jobKey: options.economicsJobKey, contextKey: economicsContext(repoPath), observerVersion: options.version });
+            if (economics.decision === "BYPASS_FULL") {
+                const samples = options.economicsHistory.samples;
+                if (options.forceAnalysis || samples.some(sample => !git(["merge-base", "--is-ancestor", sample.headSha, range.baseSha]).ok))
+                    economics = { ...economics, decision: "ANALYZE", reason: "Forced resampling or history is not ancestral to this change" };
+            }
+            markPhase("economics");
+            if (economics.decision === "BYPASS_FULL")
+                return finish("REFUSED", "eligibility", { reason: `ECONOMICS_FULL_BYPASS: ${economics.reason}. No selective command is authorized.` });
+        }
+        const [{ analyzeGitDelta }, { classifyRepositoryProject, buildDependencyGraph }, { ImpactAnalyzer }, { runPathBaseline }, { commandSpecToString, planSelectiveTestCommands }] = await Promise.all([
+            import("@diffci.com/core/git/git-diff"), import("@diffci.com/core/repo/graph"), import("@diffci.com/core/repo/impact"), import("@diffci.com/core/planner/path-baseline"), import("@diffci.com/core/planner/test-command"),
+        ]);
+        markPhase("engineLoad");
         // The eligibility gate is asked of the graph builder itself (classifyRepositoryProject), not of a
         // separate list of conditions that can drift away from it. Phase 01 F3 is what that drift costs.
         const capability = classifyRepositoryProject(repoPath);
+        markPhase("eligibility");
         if (!capability.capable) {
             return finish("REFUSED", "eligibility", {
-                reason: `DiffCI supports TypeScript/JavaScript projects, Vue components, and root Go modules: ${capability.reason}`,
+                reason: `DiffCI supports TypeScript/JavaScript projects, Vue components, root Go modules, and conventional Maven reactors: ${capability.reason}`,
             });
         }
         const deltaResult = await analyzeGitDelta({ baseSha: range.baseSha, headSha: range.headSha, repoPath });
@@ -159,10 +181,13 @@ export async function observe(options) {
             return finish("REFUSED", "delta", { reason: deltaResult.error });
         }
         const delta = deltaResult.delta;
-        const graphResult = await buildDependencyGraph({ repoPath, excludeDirs: EXCLUDE_DIRS });
+        markPhase("delta");
+        const graphResult = await buildDependencyGraph({ repoPath, excludeDirs: EXCLUDE_DIRS, vueAnalysisCache: options.vueAnalysisCacheDir ? { directory: options.vueAnalysisCacheDir, version: `${options.version}:${options.engineSha ?? ""}` } : undefined });
+        markPhase("graph");
         if (graphResult.graph.nodes.length === 0) {
             return finish("REFUSED", "graph", {
-                reason: "the dependency graph came back empty - DiffCI will not propose a selection from a graph that sees none of this repository",
+                reason: "the dependency graph came back empty - DiffCI will not propose a selection from a graph that sees none of this repository" +
+                    (graphResult.adapterBlockers?.length ? `; ${graphResult.adapterBlockers.join("; ")}` : ""),
             });
         }
         const profile = graphResult.profile;
@@ -177,6 +202,7 @@ export async function observe(options) {
         const commandPlan = impact.fallbackRequired
             ? undefined
             : planSelectiveTestCommands(profile, selectedTests);
+        markPhase("impactAndCommands");
         return finish("OBSERVED", "complete", {
             result: {
                 mode: impact.fallbackRequired ? "FULL" : "SELECTIVE",
@@ -187,6 +213,9 @@ export async function observe(options) {
                 totalTestCount: profile.testFilePaths.length,
                 fallbackReasons: impact.fallbackReasons,
                 proposedCommands: (commandPlan?.commands ?? []).map(commandSpecToString),
+                goScope: profile.diffciConfig?.go?.scope,
+                vueScope: profile.vueScope ? { packageRoot: hashPath(profile.vueScope.packageRoot), testConfig: hashPath(profile.vueScope.testConfig) } : undefined,
+                scopedTestFiles: profile.vueScope ? profile.testFilePaths.map(hashPath) : undefined,
                 commandRefusalReason: commandPlan?.refusalReason,
                 unroutedTestPaths: (commandPlan?.unroutedPaths ?? []).map(hashPath),
                 blindSpot: profile.testUniverse?.blindSpot === true,
@@ -197,6 +226,8 @@ export async function observe(options) {
                     confidence: graphResult.confidence,
                     effectiveConfidence: impact.effectiveGraphConfidence,
                     durationMs: Math.round(graphResult.performance.durationMs),
+                    phasesMs: graphResult.performance.phasesMs,
+                    adapterMetrics: graphResult.performance.adapterMetrics,
                 },
                 pathBaseline: {
                     mode: baseline.fallbackRequired ? "FULL" : "SELECTIVE",

package/dist-client/src/client/verify-savings.js

@@ -33,7 +33,7 @@ function resolveSelection(options) {
         throw new Error("--selected <command> or --selected-from-report <path> is required");
     return { command: options.selected, source: "manual" };
 }
-function measureCommand(command, options) {
+export function measureCommand(command, options) {
     const startedAt = new Date().toISOString();
     const started = Date.now();
     const shellCommand = process.platform === "win32" ? "powershell.exe" : "sh";
@@ -69,6 +69,7 @@ export function buildVerifySavingsReport(input) {
     const overhead = input.analysisOverheadMs ?? 0;
     const netSelectedMs = input.selected.wallMs + overhead;
     const deltaMs = input.full.wallMs - netSelectedMs;
+    const grossPercentChange = input.full.wallMs > 0 ? ((input.full.wallMs - input.selected.wallMs) / input.full.wallMs) * 100 : 0;
     const percentChange = input.full.wallMs > 0 ? (deltaMs / input.full.wallMs) * 100 : 0;
     const fullCommandSucceeded = input.full.exitCode === 0 && !input.full.timedOut;
     const selectedCommandSucceeded = input.selected.exitCode === 0 && !input.selected.timedOut;
@@ -100,6 +101,7 @@ export function buildVerifySavingsReport(input) {
             selectedWallMs: input.selected.wallMs,
             netSelectedMs,
             deltaMs,
+            grossPercentChange,
             percentChange,
             selectedCommandSucceeded,
             fullCommandSucceeded,
@@ -144,6 +146,7 @@ ${!report.comparison.fullCommandSucceeded || !report.comparison.selectedCommandS
 | --- | ---: |
 | Full runtime | ${formatMs(report.comparison.fullWallMs)} |
 | Selected runtime | ${formatMs(report.comparison.selectedWallMs)} |
+| Test execution change vs full | ${formatPercent(report.comparison.grossPercentChange)} |
 | DiffCI analysis overhead | ${overhead} |
 | Net selected runtime | ${formatMs(report.comparison.netSelectedMs)} |
 | Delta vs full | ${formatMs(report.comparison.deltaMs)} ${deltaLabel} |
@@ -191,7 +194,10 @@ export function formatVerifySavingsSummary(report) {
             (report.comparison.missedFailureSignal ? "\n  warning: full failed while selected passed; inspect outputs before claiming safety" : "");
     }
     const lines = [
-        `DiffCI verify-savings: ${report.comparison.deltaMs >= 0 ? "faster" : "slower"} by ${formatMs(Math.abs(report.comparison.deltaMs))}`,
+        `DiffCI verify-savings: test execution ${Math.abs(report.comparison.grossPercentChange).toFixed(1)}% ${report.comparison.grossPercentChange >= 0 ? "faster" : "slower"} in this paired run`,
+        `  full: ${formatMs(report.comparison.fullWallMs)}`,
+        `  selected: ${formatMs(report.comparison.selectedWallMs)} + analysis ${formatMs(report.analysisOverheadMs ?? 0)} = ${formatMs(report.comparison.netSelectedMs)}`,
+        `  net including analysis: ${Math.abs(report.comparison.percentChange).toFixed(1)}% ${report.comparison.deltaMs >= 0 ? "faster" : "slower"} (${formatMs(Math.abs(report.comparison.deltaMs))} ${report.comparison.deltaMs >= 0 ? "saved" : "added"})`,
     ];
     if (report.comparison.missedFailureSignal) {
         lines.push("  warning: full failed while selected passed; inspect outputs before claiming safety");

package/docs/agent-adoption-kit.md

@@ -0,0 +1,96 @@
+# DiffCI Agent Adoption Kit
+
+Use this when adding DiffCI to a repository or opening a small adoption PR.
+
+## One-Sentence Positioning
+
+DiffCI gives AI coding agents a safe default CI/CD validation command.
+
+## Maintainer Install Snippet
+
+```md
+## Add DiffCI for AI coding agents
+
+Run:
+
+```bash
+npx @diffci.com/diffci@latest init
+```
+
+Then ask your coding agent to run:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+DiffCI check analyzes the change and runs inferred full and selected test commands to measure time.
+It writes reports outside the checkout and sends nothing. Test commands may write generated files.
+Use `observe --no-send` for analysis only.
+```
+
+## Agent Instruction Snippet
+
+```md
+Before marking changes PR-ready, run:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+Use DiffCI output to understand which tests and CI paths are relevant. Do not treat a DiffCI selection
+as permission to skip required project CI.
+```
+
+## GitHub Search Queries
+
+Find repositories already prepared for coding agents:
+
+```text
+filename:AGENTS.md
+filename:CLAUDE.md
+path:.cursor/rules
+filename:copilot-instructions.md
+```
+
+Prioritize repositories that:
+
+- use JavaScript, TypeScript, Vue, or Go in a normal GitHub Actions workflow;
+- already accept small docs/config PRs;
+- have active maintainers and recent CI runs;
+- already document agent behavior.
+
+Avoid repositories where:
+
+- CI is security-sensitive and maintainers ask not to add tools;
+- there is no clear test command or GitHub Actions setup;
+- the project is inactive.
+
+## Small PR Template
+
+```md
+Title: Add optional DiffCI instructions for AI coding agents
+
+This adds an optional instruction for coding agents to run DiffCI before marking changes PR-ready.
+
+DiffCI check runs a paired test comparison when commands can be inferred:
+
+- it analyzes the change and writes a local report;
+- it sends nothing without explicit configuration;
+- it runs full and selected test commands but does not skip required CI;
+- the repository's existing required CI remains authoritative.
+
+Default command:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+This PR does not make DiffCI a required check.
+```
+
+## Links
+
+- Agent docs: https://diffci.com/docs/ai-agents.html
+- llms.txt: https://diffci.com/llms.txt
+- npm: https://www.npmjs.com/package/@diffci.com/diffci
+- GitHub release: https://github.com/DiffCI/DiffCI.com/releases/latest

package/docs/agent-adoption-targets.md

@@ -0,0 +1,52 @@
+# Agent Adoption Targets
+
+Generated 2026-09-21 from GitHub search for repositories already centered on `AGENTS.md`,
+`CLAUDE.md`, Cursor/Codex/Claude Code workflows, or agent instruction templates.
+
+Do not open drive-by PRs blindly. Review each repository's contribution policy first and use the
+small optional-instruction PR from [`agent-adoption-kit.md`](agent-adoption-kit.md).
+
+## Best First Targets
+
+| Repository | Why it fits |
+| --- | --- |
+| [`agentsmd/agents.md`](https://github.com/agentsmd/agents.md) | Defines the `AGENTS.md` convention. A DiffCI example would reach the broadest agent-instruction audience. |
+| [`FerroxLabs/agents-md`](https://github.com/FerroxLabs/agents-md) | Explicitly targets Claude Code, Codex, Gemini, Cursor, and verification loops. |
+| [`ciembor/agent-rules-books`](https://github.com/ciembor/agent-rules-books) | Curated rules for AI coding agents; good fit for a validation command snippet. |
+| [`jbarbier/CLAUDE.md`](https://github.com/jbarbier/CLAUDE.md) | Drop-in Claude/Codex/Cursor instruction file; likely accepts concise validation guidance. |
+| [`agent-sh/agnix`](https://github.com/agent-sh/agnix) | Linter/LSP for agent instruction files; possible future integration target. |
+| [`jsynowiec/node-typescript-boilerplate`](https://github.com/jsynowiec/node-typescript-boilerplate) | Real Node/TypeScript boilerplate with GitHub Actions and `AGENTS.md`, useful as a practical adoption example. |
+
+## Secondary Targets
+
+| Repository | Why it fits |
+| --- | --- |
+| [`BayramAnnakov/claude-reflect`](https://github.com/BayramAnnakov/claude-reflect) | Syncs learning into `CLAUDE.md` and `AGENTS.md`; validation-command guidance may fit. |
+| [`josix/awesome-claude-md`](https://github.com/josix/awesome-claude-md) | Curated collection; submit DiffCI as a validation-pattern example. |
+| [`TheDecipherist/claude-code-mastery`](https://github.com/TheDecipherist/claude-code-mastery) | Guide-style repo; useful place for the agent-safe validation command. |
+| [`microsoft/skills`](https://github.com/microsoft/skills) | Agent skills and MCP ecosystem. Higher bar; review contribution rules before proposing. |
+| [`mxyhi/ok-skills`](https://github.com/mxyhi/ok-skills) | Curated skills/playbooks for Codex, Claude Code, Cursor, and other tools. |
+
+## PR Order
+
+1. Start with documentation/example repos, not large application repos.
+2. Add only an optional validation instruction, never a required check.
+3. Link to `https://diffci.com/docs/ai-agents.html` and `https://diffci.com/llms.txt`.
+4. State that DiffCI sends nothing and changes no CI behavior by default.
+5. If maintainers ask for a workflow, suggest `npx @diffci.com/diffci@latest init --workflow`.
+
+## Minimal Patch Shape
+
+Add this to the repository's agent instruction file:
+
+```md
+Before marking changes PR-ready, run:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+DiffCI check analyzes the change and runs inferred full and selected test commands to measure time.
+It writes reports outside the checkout and sends nothing. Test commands may write generated files.
+Existing required CI remains authoritative; use `observe --no-send` for analysis only.
+```

package/docs/ai-agents.md

@@ -3,14 +3,15 @@
 DiffCI is the default CI/CD validation lens agents can run before proposing, committing, or opening a
 pull request.
 
-The safe default command is:
+The default command is:
 
 ```bash
 npx @diffci.com/diffci@latest check
 ```
 
-`check` is an alias for `observe --no-send`. It analyzes the change and prints a report summary without
-running tests, skipping tests, cancelling jobs, changing the checkout, or sending data to DiffCI Cloud.
+`check` analyzes the change and runs inferred full and selected test commands when possible. It
+prints paired runtime when both pass and sends nothing to DiffCI Cloud. Test commands may change
+the checkout. Use `observe --no-send` when you need analysis without running tests.
 
 ## Install Agent Instructions
 
@@ -42,6 +43,29 @@ Then verify the workflow:
 npx @diffci.com/diffci@latest verify-workflow
 ```
 
+## Copy-Paste Adoption
+
+For a maintainer-facing snippet, PR template, and GitHub search queries for repositories that already
+use agent instruction files, see [`agent-adoption-kit.md`](agent-adoption-kit.md).
+For a first-pass list of repositories to review before opening PRs, see
+[`agent-adoption-targets.md`](agent-adoption-targets.md).
+
+Examples:
+
+- [`examples/agent-node`](../examples/agent-node)
+- [`examples/agent-python`](../examples/agent-python)
+- [`examples/agent-monorepo`](../examples/agent-monorepo)
+
+## MCP
+
+Agents that support MCP can run DiffCI as a native stdio tool server:
+
+```bash
+npx -p @diffci.com/diffci@latest diffci-mcp
+```
+
+See [`mcp.md`](mcp.md).
+
 ## Agent Policy
 
 Agents should:

package/docs/claude-code.md

@@ -12,6 +12,7 @@ Default validation command:
 npx @diffci.com/diffci@latest check
 ```
 
-Use DiffCI before PR-ready answers. `check` is observation-only: it analyzes the change, writes a
-report outside the checkout, sends nothing by default, and does not run, skip, cancel, or reorder tests.
+Use DiffCI before PR-ready answers. `check` analyzes the change and runs inferred full and selected
+test commands to measure time. It writes reports outside the checkout and sends nothing by default.
+Test commands may write generated files. Use `observe --no-send` for analysis only.
 Keep the repository's required checks authoritative.

package/docs/codex.md

@@ -12,6 +12,7 @@ Default validation command:
 npx @diffci.com/diffci@latest check
 ```
 
-Use DiffCI before PR-ready answers. `check` is observation-only: it analyzes the change, writes a
-report outside the checkout, sends nothing by default, and does not run, skip, cancel, or reorder tests.
+Use DiffCI before PR-ready answers. `check` analyzes the change and runs inferred full and selected
+test commands to measure time. It writes reports outside the checkout and sends nothing by default.
+Test commands may write generated files. Use `observe --no-send` for analysis only.
 Keep the repository's required checks authoritative.

package/docs/copilot.md

@@ -12,7 +12,7 @@ Default validation command:
 npx @diffci.com/diffci@latest check
 ```
 
-Use DiffCI before PR-ready answers. `init` writes `.github/copilot-instructions.md`; `check` is
-observation-only: it analyzes the change, writes a report outside the checkout, sends nothing by
-default, and does not run, skip, cancel, or reorder tests. Keep the repository's required checks
-authoritative.
+Use DiffCI before PR-ready answers. `init` writes `.github/copilot-instructions.md`; `check`
+analyzes the change and runs inferred full and selected test commands to measure time. It sends
+nothing by default. Test commands may write generated files; use `observe --no-send` for analysis
+only. Keep the repository's required checks authoritative.

package/docs/cursor.md

@@ -12,7 +12,7 @@ Default validation command:
 npx @diffci.com/diffci@latest check
 ```
 
-Use DiffCI before PR-ready changes. `init` writes `.cursor/rules/diffci.mdc`; `check` is
-observation-only: it analyzes the change, writes a report outside the checkout, sends nothing by
-default, and does not run, skip, cancel, or reorder tests. Keep the repository's required checks
-authoritative.
+Use DiffCI before PR-ready changes. `init` writes `.cursor/rules/diffci.mdc`; `check` analyzes the
+change and runs inferred full and selected test commands to measure time. It sends nothing by
+default. Test commands may write generated files; use `observe --no-send` for analysis only. Keep
+the repository's required checks authoritative.

package/docs/grok.md

@@ -12,6 +12,7 @@ Default validation command:
 npx @diffci.com/diffci@latest check
 ```
 
-Use DiffCI before PR-ready answers. `check` is observation-only: it analyzes the change, writes a
-report outside the checkout, sends nothing by default, and does not run, skip, cancel, or reorder tests.
+Use DiffCI before PR-ready answers. `check` analyzes the change and runs inferred full and selected
+test commands to measure time. It writes reports outside the checkout and sends nothing by default.
+Test commands may write generated files. Use `observe --no-send` for analysis only.
 Keep the repository's required checks authoritative.