@diffci.com/diffci 0.2.2 → 0.2.3

package/README.md

@@ -3,16 +3,21 @@
 
 [![npm version](https://img.shields.io/npm/v/@diffci.com/diffci.svg)](https://www.npmjs.com/package/@diffci.com/diffci)
 [![npm provenance](https://img.shields.io/badge/npm-provenance-blue)](https://docs.npmjs.com/generating-provenance-statements)
+[![MCP server](https://img.shields.io/badge/MCP-server-5f6fff)](docs/mcp.md)
+[![Agent safe](https://img.shields.io/badge/agent--safe-observation--only-0f766e)](docs/ai-agents.md)
 [![GitHub Action](https://img.shields.io/badge/action-DiffCI%2FDiffCI.com%40v0.1.4-blue)](https://github.com/DiffCI/DiffCI.com)
 
-**Find test-selection opportunities in your CI before changing what it runs.** DiffCI analyzes a
-commit's changes and dependency graph, then reports which test files it would select, why it falls
-back to a full run, and whether it can propose a test command. `check` also runs paired full and
-selected commands when it can infer them. The `observe` command and Action remain observation-only.
+**Find test-selection opportunities in your CI before changing what it runs.** DiffCI analyzes a
+commit's changes and dependency graph, then reports which test files it would select, why it falls
+back to a full run, and whether it can propose a test command. `check` also runs paired full and
+selected commands when it can infer them. The `observe` command and Action remain observation-only.
 
 **For AI coding agents:** DiffCI gives Codex, Claude Code, Cursor, GitHub Copilot, Grok, and similar
 tools a safe default CI/CD validation command.
 
+AI-readable documentation: [DiffCI CLI on Context7](https://context7.com/diffci/diffci.com) and
+[DiffCI Core on Context7](https://context7.com/diffci/core).
+
 From an existing repository checkout, with Node.js 22.5+ and Git installed:
 
 ```bash
@@ -25,23 +30,23 @@ For AI coding agents, seed the repository with default instructions:
 npx @diffci.com/diffci@latest init
 ```
 
-For a self-serve runtime comparison, run one command from the repository root:
-
-```bash
-npx @diffci.com/diffci@latest check
-```
+For a self-serve runtime comparison, run one command from the repository root:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
 
 On Windows PowerShell, quote the package name:
 
 ```powershell
-npx '@diffci.com/diffci@latest' check
-```
-
-`check` infers a full test command, runs it and DiffCI's selected command, and prints gross test-time
-and net runtime changes when both pass. It writes observation and savings reports outside the checkout.
-Test commands may create files or change the checkout. One paired run is preliminary evidence; repeat
-comparisons and account for cache effects before claiming CI savings. On a full-validation fallback,
-`check` runs the full command once and reports 0% reduction.
+npx '@diffci.com/diffci@latest' check
+```
+
+`check` infers a full test command, runs it and DiffCI's selected command, and prints gross test-time
+and net runtime changes when both pass. It writes observation and savings reports outside the checkout.
+Test commands may create files or change the checkout. One paired run is preliminary evidence; repeat
+comparisons and account for cache effects before claiming CI savings. On a full-validation fallback,
+`check` runs the full command once and reports 0% reduction.
 
 **Upgrade from 0.1.3:** tests excluded by a source-only `tsconfig.json` could be discovered without
 their dependency edges, producing an incomplete selection. This is fixed in **0.1.4**. Revalidate
@@ -54,9 +59,9 @@ comparison, add `--base <base-sha> --head <head-sha>`. DiffCI prints the selecti
 and the path to a JSON report outside your checkout. `REFUSED` or `ERROR` is not a successful analysis;
 check the reported status even when the command exits successfully. See the
 [support matrix](docs/language-support.md) for setup requirements and supported workloads.
-`check` runs inferred full and selected commands in the checkout and sends nothing by default.
-The commands may write generated files. Use `observe --no-send` for analysis without execution.
-See [`docs/ai-agents.md`](docs/ai-agents.md) for Claude Code, Codex,
+`check` runs inferred full and selected commands in the checkout and sends nothing by default.
+The commands may write generated files. Use `observe --no-send` for analysis without execution.
+See [`docs/ai-agents.md`](docs/ai-agents.md) for Claude Code, Codex,
 Cursor, GitHub Copilot, and similar tools.
 
 **Measured example:** a controlled Cal.com replay showed **44.2% net reduction in a job-equivalent
@@ -64,8 +69,8 @@ install + pretest + test workload**, including analysis overhead. This is one sa
 not Cal.com's production savings or a prediction for your repository.
 [Read the timings and method](docs/research/2026-08-24-calcom-execution-observability/11-frozen-identity-and-complete-job-savings.md).
 
-Selection counts alone do not establish runtime savings. `check` reports a measured percentage only
-when both commands pass; `observe` does not execute tests.
+Selection counts alone do not establish runtime savings. `check` reports a measured percentage only
+when both commands pass; `observe` does not execute tests.
 
 For an advanced paired runtime check, you can still run `observe` first and then run `verify-savings`
 against the observation report. It compares your normal full command with
@@ -108,7 +113,7 @@ DiffCI's hosted service requires an explicitly configured endpoint and token.
 | [`@diffci.com/diffci`](https://www.npmjs.com/package/@diffci.com/diffci) | Try `observe` locally, run an opt-in runtime pilot, or install the GitHub Action from this repository | Published npm CLI and Action |
 
 The CLI bundles a pinned revision of the [Core engine](https://github.com/DiffCI/core) from GitHub. Users install only
-`@diffci.com/diffci`; the `check` command above uses it directly. Core performs Git analysis,
+`@diffci.com/diffci`; the `check` command above uses it directly. Core performs Git analysis,
 dependency graphs, impact, path baseline, and selected-command planning. The report format and
 non-interfering GitHub Action remain in this repository. See
 [`docs/package-relationship.md`](docs/package-relationship.md) for the source relationship.
@@ -140,13 +145,18 @@ Live discovery files:
 [`llms.txt`](https://diffci.com/llms.txt) ·
 [`AI agents`](https://diffci.com/docs/ai-agents.html).
 
+Adoption materials:
+[`outreach copy`](docs/adoption-outreach.md) ·
+[`metrics`](docs/adoption-metrics.md) ·
+[`targets`](docs/agent-adoption-targets.md).
+
 For native agent integrations, DiffCI also ships a stdio MCP server:
 
 ```bash
 npx -p @diffci.com/diffci@latest diffci-mcp
 ```
 
-See [`docs/mcp.md`](docs/mcp.md).
+See [`docs/mcp.md`](docs/mcp.md) for Claude, Cursor, Codex, and generic MCP config snippets.
 
 ## Project background
 
@@ -162,7 +172,7 @@ This repository was transferred to `DiffCI/DiffCI.com` on 2026-09-16.
 | DiffCI Cloud | Hosted infrastructure, billing, enterprise dashboard, organization management, proprietary data/services, and managed acceleration | Proprietary |
 | Optional enterprise code | Separately scoped, visible and auditable enterprise capabilities | Source available, with commercial production rights controlled by DiffCI |
 
-**This mixed repository remains private.** Only the reviewed Core extraction was published, with
+**This mixed repository is public.** The reviewed Core extraction was published separately, with
 fresh Git history. This repository retains its existing engine snapshot while package integration is
 migrated separately. No blanket AGPL license applies to this repository. Public Core is advisory-only;
 energy/carbon/cost are modeled estimates, not verified environmental savings. The exact extraction is

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

@@ -10,6 +10,7 @@
  *
  * Commands:
  *   init               seed a repository with AI-agent instructions for using DiffCI
+ *   mcp                run the stdio MCP server
  *   check              analysis plus automatic paired runtime measurement
  *   observe            analyse the checkout and write an observation report
  *   verify-savings     run a paired full-versus-selected timing check
@@ -23,7 +24,7 @@
  * the observed checkout) - nothing was observed, and the caller has to change the call. `verify-workflow`
  * exits 1 on a BLOCKING finding - it is a pre-install check run by a human, not a step inside a build.
  */
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
@@ -201,6 +202,19 @@ function runInit(flags, env) {
     console.log("\nDefault agent command: npx @diffci.com/diffci@latest check");
     return 0;
 }
+function runMcp() {
+    const result = spawnSync(process.execPath, [join(dirname(import.meta.filename), "mcp.js")], {
+        cwd: process.cwd(),
+        env: process.env,
+        stdio: "inherit",
+        windowsHide: true,
+    });
+    if (typeof result.status === "number")
+        return result.status;
+    if (result.error)
+        throw result.error;
+    return 0;
+}
 function formatFinding(finding) {
     const where = finding.job ? `${finding.workflow}#${finding.job}` : finding.workflow;
     return `  [${finding.severity}] ${finding.code} (${where})\n      ${finding.message}`;
@@ -573,8 +587,9 @@ async function runPilot(flags, env) {
 }
 const USAGE = `diffci - change-aware CI analysis and paired timing
 
-Usage:
-  diffci init [--repo <path>] [--workflow] [--force]
+Usage:
+  diffci init [--repo <path>] [--workflow] [--force]
+  diffci mcp
   diffci check [--repo <path>] [--out <file>] [--base <sha> --head <sha>]
                [--redact-paths] [--json] [--quiet] [--fail-on-error] [--timeout-ms <ms>]
   diffci pilot --full <command> [--repo <path>] [--out-dir <dir>] [--label <name>]
@@ -587,7 +602,8 @@ Usage:
   diffci verify-workflow [--repo <path>]
   diffci version
 
-init writes AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions, and diffci.config.json.
+init writes AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions, and diffci.config.json.
+mcp runs the stdio MCP server for native agent integrations.
 check analyzes the change, runs inferred full and selected commands, and shows measured savings.
 pilot runs observe and verify-savings together, writing reports to ../diffci-output by default.
 observe analyses the checkout and writes one JSON report. It runs nothing and changes nothing.
@@ -610,6 +626,9 @@ async function main() {
         case "init":
             process.exitCode = runInit(flags, env);
             return;
+        case "mcp":
+            process.exitCode = runMcp();
+            return;
         case "check":
             process.exitCode = await runCheck(flags, env);
             return;

package/docs/adoption-metrics.md

@@ -0,0 +1,39 @@
+# DiffCI Adoption Metrics
+
+Track adoption weekly after each outreach batch.
+
+## Package
+
+- npm latest version: `npm view "@diffci.com/diffci" version`
+- npm weekly downloads: `npm view "@diffci.com/diffci" downloads`
+- MCP binary presence: `npm view "@diffci.com/diffci" bin --json`
+
+## Repository
+
+- GitHub stars, forks, watchers, and release views.
+- Issues or PRs opened by users asking about `diffci check`, `diffci init`, or `diffci-mcp`.
+- External PRs merged that mention DiffCI agent validation.
+
+## Site
+
+- Visits to `https://diffci.com/docs/ai-agents.html`.
+- Visits to `https://diffci.com/llms.txt`.
+- Clicks from the homepage agent and MCP links.
+- Referrers from MCP directories, awesome lists, and agent-template repositories.
+
+## Outreach
+
+Record each submission in `docs/agent-adoption-targets.md` or a dated note:
+
+| Date | Target | Type | Link | Status | Follow-up |
+| --- | --- | --- | --- | --- | --- |
+| 2026-09-22 | agentsmd/agents.md | Issue | https://github.com/agentsmd/agents.md/issues/245 | Open | Watch for maintainer preference: issue, PR, or no listing. |
+| 2026-09-22 | FerroxLabs/agents-md | Issue | https://github.com/FerroxLabs/agents-md/issues/2 | Open | Offer a PR if maintainer wants exact wording. |
+| 2026-09-22 | ciembor/agent-rules-books | Issue | https://github.com/ciembor/agent-rules-books/issues/8 | Open | Offer a PR if maintainer wants exact wording. |
+| 2026-09-22 | jbarbier/CLAUDE.md | Issue | https://github.com/jbarbier/CLAUDE.md/issues/12 | Open | Offer a PR if maintainer wants exact wording. |
+| 2026-09-22 | Official MCP Registry | Directory | TBD | Planned | Prepare publisher metadata. |
+| 2026-09-22 | Glama | Directory | TBD | Planned | Submit repository URL. |
+| 2026-09-22 | Smithery | Directory | TBD | Blocked | Needs Smithery account/API key. |
+
+Use merged PRs and accepted directory listings as the primary adoption signal. Use stars, downloads,
+and page views as supporting indicators, not proof that agents are actually using DiffCI.

package/docs/adoption-outreach.md

@@ -0,0 +1,84 @@
+# DiffCI Adoption Outreach
+
+Use this page as the canonical copy source for directory submissions, issues, and pull requests.
+
+## One-Line Description
+
+DiffCI is an observation-only CI/CD validation tool and MCP server for AI coding agents.
+
+## Short Description
+
+DiffCI gives coding agents a safe validation lens before they call work PR-ready. It analyzes the
+current checkout, explains affected tests, can run inferred local validation through `diffci check`,
+and leaves required CI authoritative.
+
+## Links
+
+- Website: https://diffci.com/
+- Agent docs: https://diffci.com/docs/ai-agents.html
+- MCP docs: https://github.com/DiffCI/DiffCI.com/blob/main/docs/mcp.md
+- LLM discovery: https://diffci.com/llms.txt
+- npm: https://www.npmjs.com/package/@diffci.com/diffci
+- GitHub: https://github.com/DiffCI/DiffCI.com
+
+## Commands
+
+CLI:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+MCP:
+
+```bash
+npx -p @diffci.com/diffci@latest diffci-mcp
+```
+
+## Issue Template
+
+Title:
+
+```text
+Add DiffCI as an optional AI-agent CI validation tool
+```
+
+Body:
+
+```md
+DiffCI now ships an npm CLI and stdio MCP server for AI coding agents:
+
+- CLI: `npx @diffci.com/diffci@latest check`
+- MCP: `npx -p @diffci.com/diffci@latest diffci-mcp`
+
+It is intended as an optional validation lens before agents mark work PR-ready. DiffCI analyzes the
+current checkout, explains affected tests, can run inferred local validation through `diffci check`,
+and does not skip, cancel, reorder, or modify required CI.
+
+Docs:
+
+- https://diffci.com/docs/ai-agents.html
+- https://github.com/DiffCI/DiffCI.com/blob/main/docs/mcp.md
+
+Would you be open to adding DiffCI as an optional validation command/example for AI coding agents?
+```
+
+## PR Snippet
+
+~~~md
+### Optional AI-agent validation
+
+Before marking changes PR-ready, agents can run:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+Agents with MCP support can configure:
+
+```bash
+npx -p @diffci.com/diffci@latest diffci-mcp
+```
+
+DiffCI is a validation lens: it explains affected tests and keeps required CI authoritative.
+~~~

package/docs/agent-adoption-targets.md

@@ -1,52 +1,62 @@
-# 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.
-```
+# 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. Proposal opened: [#245](https://github.com/agentsmd/agents.md/issues/245). |
+| [`FerroxLabs/agents-md`](https://github.com/FerroxLabs/agents-md) | Explicitly targets Claude Code, Codex, Gemini, Cursor, and verification loops. Proposal opened: [#2](https://github.com/FerroxLabs/agents-md/issues/2). |
+| [`ciembor/agent-rules-books`](https://github.com/ciembor/agent-rules-books) | Curated rules for AI coding agents; proposal opened: [#8](https://github.com/ciembor/agent-rules-books/issues/8). |
+| [`jbarbier/CLAUDE.md`](https://github.com/jbarbier/CLAUDE.md) | Drop-in Claude/Codex/Cursor instruction file; proposal opened: [#12](https://github.com/jbarbier/CLAUDE.md/issues/12). |
+| [`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. |
+
+## MCP Directory Targets
+
+| Directory | Submission path | Status |
+| --- | --- | --- |
+| [Official MCP Registry](https://github.com/modelcontextprotocol/registry) | Use the official `mcp-publisher` flow; do not open a seed-data PR. | Ready after registry package metadata is prepared. |
+| [Glama](https://glama.ai/) | Submit the GitHub repository URL and short description; optional `glama.json` metadata can improve indexing. | Ready to submit. |
+| [Smithery](https://smithery.ai/) | Publish through Smithery's server release flow/API. | Needs Smithery account/API key. |
+| [PulseMCP](https://www.pulsemcp.com/) | Submit/list the MCP server if their current listing flow accepts third-party servers. | Review current submission rules first. |
+| [MCP Central](https://mcpcentral.io/) | Follow the interactive server submission flow. | Ready to submit. |
+
+## 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 by default and changes no CI behavior.
+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

@@ -1,88 +1,102 @@
-# DiffCI for AI Coding Agents
-
-DiffCI is the default CI/CD validation lens agents can run before proposing, committing, or opening a
-pull request.
-
-The default command is:
-
-```bash
-npx @diffci.com/diffci@latest check
-```
-
-`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
-
-From a repository root:
-
-```bash
-npx @diffci.com/diffci@latest init
-```
-
-This writes:
-
-- `AGENTS.md`
-- `CLAUDE.md`
-- `.cursor/rules/diffci.mdc`
-- `.github/copilot-instructions.md`
-- `diffci.config.json`
-
-Existing files are kept. Pass `--force` only when you intentionally want to replace them.
-
-To also add a non-blocking GitHub Actions observer job:
-
-```bash
-npx @diffci.com/diffci@latest init --workflow
-```
-
-Then verify the workflow:
-
-```bash
-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:
-
-- run `diffci check` before PR-ready answers when Git and Node.js are available;
-- read the printed verdict, selected tests, fallback reasons, and report path;
-- use DiffCI output to choose focused follow-up validation;
-- keep the repository's required CI commands authoritative.
-
-Agents should not:
-
-- skip required CI because DiffCI selected fewer tests;
-- treat `REFUSED` or `ERROR` as a passing validation;
-- configure hosted report sending unless the user explicitly supplies an endpoint and token.
-
-## Open Core Boundary
-
-The agent-facing layer belongs in the open-source core: CLI, local reports, JSON output, instruction
-files, and the non-blocking GitHub Action. Hosted history, organization dashboards, PR bots, policies,
-team analytics, managed runners, and support belong to commercial DiffCI.
+# DiffCI for AI Coding Agents
+
+DiffCI is the default CI/CD validation lens agents can run before proposing, committing, or opening a
+pull request.
+
+The default command is:
+
+```bash
+npx @diffci.com/diffci@latest check
+```
+
+`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
+
+From a repository root:
+
+```bash
+npx @diffci.com/diffci@latest init
+```
+
+This writes:
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- `.cursor/rules/diffci.mdc`
+- `.github/copilot-instructions.md`
+- `diffci.config.json`
+
+Existing files are kept. Pass `--force` only when you intentionally want to replace them.
+
+To also add a non-blocking GitHub Actions observer job:
+
+```bash
+npx @diffci.com/diffci@latest init --workflow
+```
+
+Then verify the workflow:
+
+```bash
+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).
+
+Minimal MCP config:
+
+```json
+{
+  "mcpServers": {
+    "diffci": {
+      "command": "npx",
+      "args": ["-p", "@diffci.com/diffci@latest", "diffci-mcp"]
+    }
+  }
+}
+```
+
+## Agent Policy
+
+Agents should:
+
+- run `diffci check` before PR-ready answers when Git and Node.js are available;
+- call `diffci_check` when connected through MCP;
+- read the printed verdict, selected tests, fallback reasons, and report path;
+- use DiffCI output to choose focused follow-up validation;
+- keep the repository's required CI commands authoritative.
+
+Agents should not:
+
+- skip required CI because DiffCI selected fewer tests;
+- treat `REFUSED` or `ERROR` as a passing validation;
+- configure hosted report sending unless the user explicitly supplies an endpoint and token.
+
+## Open Core Boundary
+
+The agent-facing layer belongs in the open-source core: CLI, local reports, JSON output, instruction
+files, and the non-blocking GitHub Action. Hosted history, organization dashboards, PR bots, policies,
+team analytics, managed runners, and support belong to commercial DiffCI.