@jqntn/agentdoctor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the agentdoctor authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jqntn/agentdoctor/main/assets/logo-dark.svg">
+    <img src="https://raw.githubusercontent.com/jqntn/agentdoctor/main/assets/logo-light.svg" alt="agentdoctor" width="420">
+  </picture>
+
+  <p><strong>Lint your AI coding agent's configuration before it bites.</strong></p>
+
+  <p>
+    <a href="https://github.com/jqntn/agentdoctor/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/jqntn/agentdoctor/actions/workflows/ci.yml/badge.svg"></a>
+    <a href="https://www.npmjs.com/package/@jqntn/agentdoctor"><img alt="npm" src="https://img.shields.io/npm/v/%40jqntn%2Fagentdoctor"></a>
+    <img alt="zero dependencies" src="https://img.shields.io/badge/dependencies-0-34D399">
+    <img alt="node >=20" src="https://img.shields.io/badge/node-%3E%3D20-64748B">
+    <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  </p>
+
+  <p>
+    <a href="https://jqntn.github.io/agentdoctor/">Website</a> ·
+    <a href="docs/getting-started.md">Getting started</a> ·
+    <a href="docs/rules.md">Rule reference</a> ·
+    <a href="docs/ci.md">CI setup</a> ·
+    <a href="docs/agents.md">For agents</a>
+  </p>
+</div>
+
+---
+
+Agent harnesses read a surprising amount of config: permission rules, hooks that execute
+automatically, MCP servers that run third-party code, and memory files re-sent on every
+request. Almost none of it is validated, and the failures are **silent**. A misspelled hook
+event never fires. A deny rule naming a tool that does not exist blocks nothing — while
+looking exactly like a guardrail. `Bash(*)` in an allow list means every command the model
+proposes runs without asking you.
+
+`agentdoctor` reads that config and tells you what is actually wrong with it:
+
+```sh
+npx @jqntn/agentdoctor
+```
+
+```
+agentdoctor scanned 8 config files in /work/api
+
+.claude/settings.json
+  4:7     error  "Bash(*)" auto-approves every shell command, including ones you have not seen.
+                 | Bash(*)
+                 -> Replace the wildcard with the specific commands you actually want
+                    unattended, e.g. "Bash(npm test:*)" or "Bash(git status)".
+                 security/unrestricted-bash
+
+  27:43   error  PreToolUse hook uses curl | sh; the remote content is executed unreviewed on
+                 every trigger.
+                 | curl -sSL https://example.com/guard.sh | bash
+                 -> Vendor the script into the repo and run it from a pinned path.
+                 security/hook-remote-code
+
+  35:21   error  "PostToolUsee" is not a hook event. Did you mean "PostToolUse"? As written,
+                 this hook never runs.
+                 correctness/unknown-hook-event
+
+CLAUDE.md
+  1       warn   CLAUDE.md is ~14,200 tokens of always-on context, sent with every request
+                 (~$25/month at 3,300 requests, assuming it stays prompt-cached).
+                 cost/memory-file-too-large
+
+Summary  Grade F  3 errors, 1 warning  - 72 rules in 41ms
+```
+
+Zero dependencies. No network calls. Credential files are never opened. MIT — all of it.
+
+## What it checks
+
+**72 rules across five categories.** Full reasoning for every rule:
+[rule reference](docs/rules.md), or `agentdoctor --explain <rule-id>`.
+
+### Security (22 rules)
+
+The config surface is an execution surface. Blanket `Bash(*)` allows; destructive commands
+pre-approved without confirmation (`sudo`, `rm -rf`, force push, `terraform destroy`,
+`DROP TABLE`, …); hooks piping remote content into a shell (`curl | sh`,
+`eval "$(curl …)"`); live credentials committed in config (Anthropic, OpenAI, GitHub, AWS,
+Slack, Stripe keys, JWTs, private keys — always reported **redacted**); MCP servers running
+unpinned packages or carrying tokens in URLs; `bypassPermissions` committed to shared repos;
+loader-hijacking env vars; world-writable config.
+
+### Correctness (26 rules)
+
+Config that is silently ignored is worse than config that errors, because you believe it is
+working. Invalid JSON (which voids the whole file, permission rules included); misspelled
+settings keys, hook events, tool names, and models — each with a did-you-mean; deny rules
+that block nothing (an **error**, because it is a guardrail that only looks like one);
+malformed hooks and invalid matcher regexes; duplicate agent/skill names; MCP servers with no
+way to start.
+
+### Cost (8 rules)
+
+Memory files and MCP tool schemas ride along on every request. Token counts for every memory
+file with an estimated monthly cost — the estimate assumes the file stays prompt-cached
+(that is exactly the content that caches) and states its assumptions; the same instruction
+duplicated across files; pasted code blocks that belong behind a file path; skill
+descriptions too vague for the model to ever load them.
+
+### Hygiene (8 rules)
+
+`settings.local.json` not gitignored; machine-specific absolute paths in committed config;
+local settings silently shadowing project settings; empty skill/agent bodies; duplicate
+keybindings.
+
+### Policy (8 rules)
+
+Team standards, enforced mechanically across every repo. Commit an
+`agentdoctor.policy.json` and these activate — no flag, no account:
+
+```sh
+agentdoctor --init-policy
+```
+
+`requiredDeny`, `forbiddenAllow`, `allowedMcpServers`, `requiredHooks`, `maxMemoryTokens`,
+`forbiddenPermissionModes`, plus drift detection when local settings quietly widen the
+committed permission set. [Policy guide](docs/policy.md).
+
+## Adopt it in one command
+
+```sh
+npx @jqntn/agentdoctor --init-ci      # GitHub Actions: SARIF annotations on PRs + error gate
+npx @jqntn/agentdoctor --init-skill   # Claude Code skill: findings -> fixes, automatically
+npx @jqntn/agentdoctor --init-agents  # AGENTS.md section: same loop for Codex, Cursor, Gemini CLI
+npx @jqntn/agentdoctor --badge        # README badge with your current grade
+npx @jqntn/agentdoctor --share        # paste-ready score card (rule ids + counts only)
+```
+
+Every audit ends in a grade - `A+` down to `F`, formula stated in the docs. The badge and the
+share card contain rule ids and counts only, never messages, paths, or snippets, so they are
+safe to post from private repos.
+
+[![agentdoctor: A+](https://img.shields.io/badge/agentdoctor-A%2B-34D399)](https://jqntn.github.io/agentdoctor/)
+
+## CI
+
+```yaml
+- run: npx @jqntn/agentdoctor --no-user --sarif > agentdoctor.sarif
+  continue-on-error: true
+- uses: github/codeql-action/upload-sarif@v3
+  with: { sarif_file: agentdoctor.sarif }
+- run: npx @jqntn/agentdoctor --no-user --quiet   # exit 1 on errors
+```
+
+Findings annotate the PR diff via SARIF. Adopting on a repo with existing findings? Record
+them once and fail only on new ones — baselines are anchored to content, not line numbers, so
+unrelated edits never invalidate them:
+
+```sh
+agentdoctor --write-baseline .agentdoctor-baseline.json   # once
+agentdoctor --baseline .agentdoctor-baseline.json          # in CI
+```
+
+[CI guide](docs/ci.md) · [Baselines](docs/baselines.md)
+
+## Built for agents, audited by agents
+
+Every capability is non-interactive and machine-readable: `--json` (stable schema, shipped as
+[JSON Schema](schemas/report.schema.json)), `--sarif`, `--explain`, `--list-rules --json`,
+deterministic ordering, redacted secrets safe for model context, pipe-safe output. The docs
+site serves `llms.txt` and raw markdown.
+
+The repo is also a **Claude Code plugin**: it ships the
+[config-audit skill](skills/config-audit/SKILL.md) (audit -> fix loop, with fix recipes) and
+an `/agentdoctor:audit` command. Install it any of three ways:
+
+```
+/plugin marketplace add jqntn/agentdoctor    # in Claude Code, then: /plugin install agentdoctor
+npx @jqntn/agentdoctor --init-skill                      # copies the skill into this project
+cp -r node_modules/@jqntn/agentdoctor/skills/config-audit .claude/skills/   # manual
+```
+
+[Agent guide](docs/agents.md)
+
+## What it will not do
+
+- **Never reads credential files.** `.credentials.json`, `.netrc`, private keys are excluded
+  by path before anything opens them — asserted by tests.
+- **No network calls.** No telemetry, no update checks, nothing leaves the machine.
+- **No dependencies.** A tool that warns about supply-chain risk should not install one.
+- **Never edits your config.** Findings say what to change and why; the change is yours.
+
+[Architecture and design principles](docs/architecture.md) · [FAQ](docs/faq.md) ·
+[Security policy](SECURITY.md)
+
+## Documentation
+
+| | |
+|---|---|
+| [Getting started](docs/getting-started.md) | Install, first run, reading findings, exit codes |
+| [Configuration](docs/configuration.md) | Every flag, suppression, disabling rules |
+| [Rule reference](docs/rules.md) | All 72 rules with reasoning |
+| [CI setup](docs/ci.md) | GitHub Actions, SARIF, exit-code gating |
+| [Baselines](docs/baselines.md) | Adopting on an existing repo |
+| [Team policy](docs/policy.md) | One standard across many repos |
+| [Output formats](docs/output.md) | JSON, SARIF, terminal |
+| [Programmatic API](docs/api.md) | `run()`, custom rules, embedding |
+| [For agents](docs/agents.md) | The machine-readable contract + fix loop |
+| [Architecture](docs/architecture.md) | How it works, design principles |
+| [FAQ](docs/faq.md) | |
+
+## Contributing
+
+False positives are treated as more severe than missed findings — if a rule fires on your
+legitimate config, [that is a bug](.github/ISSUE_TEMPLATE/false-positive.yml). Adding a rule
+takes one object and two tests: see [CONTRIBUTING.md](CONTRIBUTING.md). The suite enforces the
+invariants (every rule tested, zero findings on the clean fixture, zero dependencies), so if
+`npm test` is green, the PR is reviewable.
+
+## License
+
+[MIT](LICENSE). All 72 rules, every output format, no accounts, no telemetry, no paid tier.

package/bin/agentdoctor.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { run, VERSION, allRules, CATEGORIES } from '../src/index.js';
+import { fingerprint } from '../src/engine.js';
+import { renderTerminal, shouldUseColor } from '../src/report/terminal.js';
+import { renderJson } from '../src/report/json.js';
+import { renderSarif } from '../src/report/sarif.js';
+import { initCi, initSkill, initAgents, shareCard, badgeMarkdown } from '../src/adopt.js';
+
+const HELP = `agentdoctor ${VERSION} - lint your AI coding-agent configuration
+
+Usage
+  agentdoctor [path]                 Audit a project (defaults to the current directory)
+  agentdoctor --explain <rule-id>    Show what a rule checks and why
+  agentdoctor --list-rules           List every rule
+
+Output
+  --json                   Machine-readable findings on stdout
+  --sarif                  SARIF 2.1.0, for GitHub code scanning and other CI
+  --quiet                  Print nothing; rely on the exit code
+  --no-color               Disable ANSI colour (also honours NO_COLOR)
+
+Scope
+  --no-user                Skip user-level config in ~/.claude
+  --only <cat,...>         Run only these categories (${CATEGORIES.join(', ')})
+  --disable <id,...>       Skip specific rules or whole categories
+  --min-severity <level>   error | warning | info (default: info)
+
+CI
+  --max-warnings <n>       Fail if more than n warnings are found
+  --baseline <file>        Ignore findings recorded in this file
+  --write-baseline <file>  Record current findings as the accepted baseline
+
+Team policy
+  --policy <file>          Team policy file (default: agentdoctor.policy.json)
+  --init-policy            Write a starter agentdoctor.policy.json
+
+Adopt & share
+  --init-ci                Write a ready-made GitHub Actions workflow (SARIF + gate)
+  --init-skill             Write a Claude Code skill that audits and fixes config
+  --init-agents            Add an audit section to AGENTS.md (Codex, Cursor, Gemini CLI,
+                           and every other tool that reads it)
+  --badge                  Print a README badge showing this project's current grade
+  --share                  Print a paste-ready score card (rule ids and counts only,
+                           never messages or paths - safe to share from private repos)
+
+Exit codes
+  0  no errors
+  1  at least one error (or warnings over --max-warnings)
+  2  bad usage
+
+Suppress a rule for one file by adding a comment:  agentdoctor-disable <rule-id>
+`;
+
+function parseArgs(argv) {
+  const flags = {
+    positional: [],
+    json: false, sarif: false, quiet: false, color: null,
+    noUser: false, only: [], disable: [], minSeverity: 'info',
+    maxWarnings: null, baseline: null, writeBaseline: null,
+    policy: null, explain: null, listRules: false,
+    initPolicy: false, initCi: false, initSkill: false, initAgents: false,
+    share: false, badge: false, help: false, version: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const next = () => {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith('--')) {
+        throw new UsageError(`${arg} requires a value`);
+      }
+      i += 1;
+      return value;
+    };
+    switch (arg) {
+      case '--json': flags.json = true; break;
+      case '--sarif': flags.sarif = true; break;
+      case '--quiet': case '-q': flags.quiet = true; break;
+      case '--no-color': flags.color = false; break;
+      case '--color': flags.color = true; break;
+      case '--no-user': flags.noUser = true; break;
+      case '--only': flags.only.push(...next().split(',').map((s) => s.trim()).filter(Boolean)); break;
+      case '--disable': flags.disable.push(...next().split(',').map((s) => s.trim()).filter(Boolean)); break;
+      case '--min-severity': flags.minSeverity = next(); break;
+      case '--max-warnings': flags.maxWarnings = Number(next()); break;
+      case '--baseline': flags.baseline = next(); break;
+      case '--write-baseline': flags.writeBaseline = next(); break;
+      case '--policy': flags.policy = next(); break;
+      case '--explain': flags.explain = next(); break;
+      case '--list-rules': flags.listRules = true; break;
+      case '--init-policy': flags.initPolicy = true; break;
+      case '--init-ci': flags.initCi = true; break;
+      case '--init-skill': flags.initSkill = true; break;
+      case '--init-agents': flags.initAgents = true; break;
+      case '--share': flags.share = true; break;
+      case '--badge': flags.badge = true; break;
+      case '--help': case '-h': flags.help = true; break;
+      case '--version': case '-v': flags.version = true; break;
+      default:
+        if (arg.startsWith('-')) throw new UsageError(`Unknown option "${arg}"`);
+        flags.positional.push(arg);
+    }
+  }
+  return flags;
+}
+
+class UsageError extends Error {}
+
+/**
+ * Piping into `head`, `less` or a closed pager is ordinary usage. Without this,
+ * the closed pipe surfaces as an unhandled EPIPE and a Node stack trace.
+ */
+function ignoreBrokenPipe() {
+  for (const stream of [process.stdout, process.stderr]) {
+    stream.on('error', (error) => {
+      if (error.code === 'EPIPE') process.exit(0);
+      throw error;
+    });
+  }
+}
+
+const STARTER_POLICY = {
+  $comment: 'agentdoctor team policy. Commit this next to your repo root.',
+  $wildcards: 'A single * is literal. Use ** to mean "anything here".',
+  requiredDeny: ['Read(./.env*)', 'Read(**/.ssh/**)', 'Read(**/*.pem)', 'Read(**/.aws/credentials)'],
+  forbiddenAllow: ['Bash(*)', 'Bash(:*)', 'Bash()', 'WebFetch(*)', 'Bash(**sudo**)', 'Bash(**rm -rf**)'],
+  forbiddenPermissionModes: ['bypassPermissions'],
+  allowedMcpServers: [],
+  requiredHooks: [],
+  maxMemoryTokens: 6000,
+};
+
+function main() {
+  let flags;
+  try {
+    flags = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`${error.message}\n\nRun agentdoctor --help\n`);
+    return 2;
+  }
+
+  if (flags.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (flags.version) {
+    process.stdout.write(`${VERSION}\n`);
+    return 0;
+  }
+  if (flags.listRules) return listRules(flags);
+  if (flags.explain) return explainRule(flags.explain);
+
+  const root = resolve(flags.positional[0] ?? process.cwd());
+  if (!existsSync(root)) {
+    process.stderr.write(`No such directory: ${root}\n`);
+    return 2;
+  }
+
+  if (flags.initPolicy) return initPolicy(root);
+  if (flags.initCi || flags.initSkill || flags.initAgents) {
+    let failed = false;
+    for (const [enabled, init, next] of [
+      [flags.initCi, initCi, 'Findings will annotate PRs and errors will fail the build on the next push.'],
+      [flags.initSkill, initSkill, 'Claude Code will now offer config audits; try asking it to "audit my agent config".'],
+      [flags.initAgents, initAgents, 'Codex, Cursor, Gemini CLI and other AGENTS.md readers will now audit config after editing it.'],
+    ]) {
+      if (!enabled) continue;
+      const outcome = init(root);
+      process[outcome.written ? 'stdout' : 'stderr'].write(`${outcome.message}\n`);
+      if (outcome.written) process.stdout.write(`${next}\n`);
+      else failed = true;
+    }
+    return failed ? 2 : 0;
+  }
+
+  if (!['error', 'warning', 'info'].includes(flags.minSeverity)) {
+    process.stderr.write(`--min-severity must be error, warning or info\n`);
+    return 2;
+  }
+
+  let baseline = new Set();
+  if (flags.baseline) {
+    if (!existsSync(flags.baseline)) {
+      process.stderr.write(`Baseline file not found: ${flags.baseline}\n`);
+      return 2;
+    }
+    try {
+      const parsed = JSON.parse(readFileSync(flags.baseline, 'utf8'));
+      baseline = new Set(Array.isArray(parsed.fingerprints) ? parsed.fingerprints : []);
+    } catch (error) {
+      process.stderr.write(`Baseline file is not readable: ${error.message}\n`);
+      return 2;
+    }
+  }
+
+  const result = run(root, {
+    includeUserScope: !flags.noUser,
+    policyPath: flags.policy,
+    disabled: flags.disable,
+    minSeverity: flags.minSeverity,
+    only: flags.only,
+    baseline,
+  });
+
+  if (flags.writeBaseline) {
+    const payload = {
+      version: 1,
+      generatedBy: `agentdoctor ${VERSION}`,
+      fingerprints: result.findings.map((f) => fingerprint(f)),
+    };
+    writeFileSync(flags.writeBaseline, `${JSON.stringify(payload, null, 2)}\n`);
+    if (!flags.quiet) {
+      process.stdout.write(`Wrote ${payload.fingerprints.length} accepted findings to ${flags.writeBaseline}\n`);
+    }
+    return 0;
+  }
+
+  const payload = { ...result, version: VERSION };
+  if (flags.share) {
+    process.stdout.write(shareCard(result));
+    return 0;
+  }
+  if (flags.badge) {
+    process.stdout.write(badgeMarkdown(result));
+    return 0;
+  }
+  if (flags.json) {
+    process.stdout.write(`${renderJson(payload)}\n`);
+  } else if (flags.sarif) {
+    process.stdout.write(`${renderSarif(payload)}\n`);
+  } else if (!flags.quiet) {
+    const color = flags.color ?? shouldUseColor(process.stdout, process.env);
+    process.stdout.write(`${renderTerminal({ ...payload, color })}\n`);
+  }
+
+  const errors = result.findings.filter((f) => f.severity === 'error').length;
+  const warnings = result.findings.filter((f) => f.severity === 'warning').length;
+  if (errors > 0) return 1;
+  if (flags.maxWarnings !== null && Number.isFinite(flags.maxWarnings) && warnings > flags.maxWarnings) return 1;
+  return 0;
+}
+
+function listRules(flags) {
+  const wanted = flags.only.length ? new Set(flags.only) : null;
+  const rows = allRules
+    .filter((rule) => !wanted || wanted.has(rule.category) || wanted.has(rule.id))
+    .map((rule) => ({
+      id: rule.id,
+      severity: rule.severity,
+      title: rule.title,
+    }));
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
+    return 0;
+  }
+  const width = Math.max(...rows.map((r) => r.id.length));
+  for (const row of rows) {
+    process.stdout.write(`${row.id.padEnd(width)}  ${row.severity.padEnd(7)}  ${row.title}\n`);
+  }
+  process.stdout.write(`\n${rows.length} rules\n`);
+  return 0;
+}
+
+function explainRule(id) {
+  const rule = allRules.find((r) => r.id === id);
+  if (!rule) {
+    const near = allRules.filter((r) => r.id.includes(id) || r.category === id).map((r) => r.id);
+    process.stderr.write(`No rule "${id}".${near.length ? `\n\nDid you mean:\n  ${near.join('\n  ')}\n` : '\n'}`);
+    return 2;
+  }
+  process.stdout.write([
+    rule.id,
+    '',
+    `  Title      ${rule.title}`,
+    `  Category   ${rule.category}`,
+    `  Severity   ${rule.severity}`,
+    '',
+    '  Why it matters',
+    ...wrap(rule.help ?? '', 72).map((line) => `    ${line}`),
+    '',
+    `  Suppress with a comment in the offending file:`,
+    `    agentdoctor-disable ${rule.id}`,
+    '',
+  ].join('\n'));
+  return 0;
+}
+
+function initPolicy(root) {
+  const target = resolve(root, 'agentdoctor.policy.json');
+  if (existsSync(target)) {
+    process.stderr.write(`${target} already exists; not overwriting.\n`);
+    return 2;
+  }
+  writeFileSync(target, `${JSON.stringify(STARTER_POLICY, null, 2)}\n`);
+  process.stdout.write(`Wrote ${target}\nEdit it, commit it, then run agentdoctor in CI.\n`);
+  return 0;
+}
+
+function wrap(text, width) {
+  const words = String(text).split(/\s+/).filter(Boolean);
+  const lines = [];
+  let current = '';
+  for (const word of words) {
+    if (current === '') current = word;
+    else if (current.length + 1 + word.length > width) { lines.push(current); current = word; }
+    else current += ` ${word}`;
+  }
+  if (current) lines.push(current);
+  return lines.length ? lines : [''];
+}
+
+ignoreBrokenPipe();
+process.exitCode = main();

package/docs/agents.md

@@ -0,0 +1,119 @@
+# Using agentdoctor with AI agents
+
+agentdoctor is built to be operated *by* agents, not just to audit their config. Every
+capability is reachable non-interactively, every output has a machine-readable form, and every
+finding carries enough context to act on without a human in the loop.
+
+## The contract, in one table
+
+| Need | Command | Output |
+|---|---|---|
+| Audit a project | `agentdoctor <path> --no-user --json` | Findings JSON ([shape](output.md)) |
+| Gate a change | `agentdoctor <path> --no-user --quiet` | Exit code only: 0 clean, 1 errors, 2 usage |
+| Understand a rule | `agentdoctor --explain <rule-id>` | Rationale + suppression syntax, plain text |
+| Enumerate rules | `agentdoctor --list-rules --json` | `[{ id, severity, title }]` |
+| Accept a backlog | `agentdoctor --write-baseline <file>` | Fingerprint list, plain JSON |
+| CI annotations | `agentdoctor --sarif` | SARIF 2.1.0 |
+
+Guarantees an agent can rely on:
+
+- **Deterministic**: same input tree → same findings, same order (severity, file, line).
+- **Non-interactive**: no prompts, no TTY requirements, no network. Safe in any sandbox.
+- **Stable JSON**: shape version `1` only ever gains fields. A JSON Schema ships in the
+  package at `schemas/report.schema.json`.
+- **Redaction**: detected secrets never appear unredacted in any output format, so findings
+  are safe to pass through logs and model context.
+- **Pipe-safe**: output through `head`, `less`, or a closed pipe exits cleanly.
+
+## The fix loop
+
+The intended agentic workflow:
+
+```
+1. agentdoctor . --no-user --json          -> findings
+2. for each finding (already sorted most-severe-first):
+     read finding.help                     -> the fix, in prose
+     edit finding.file at finding.line     -> configPath names the exact key
+3. agentdoctor . --no-user --quiet         -> exit 0 = verified fixed
+```
+
+`configPath` (e.g. `permissions.allow[2]`) plus `snippet` (the offending value) identify the
+exact edit target without re-parsing the report message. If a finding is intentional, write
+the file-scoped suppression comment instead of deleting the rule:
+`agentdoctor-disable <rule-id>` ([syntax](configuration.md)).
+
+## Adopting it for a user, in three commands
+
+When an agent decides this tool belongs in a project (for example after an audit surfaces
+findings), the full adoption is three non-interactive, idempotent-safe commands:
+
+```sh
+npx @jqntn/agentdoctor --init-ci      # writes .github/workflows/agentdoctor.yml (SARIF + gate)
+npx @jqntn/agentdoctor --init-skill   # writes .claude/skills/config-audit/SKILL.md
+npx @jqntn/agentdoctor --write-baseline .agentdoctor-baseline.json   # only if findings exist today
+```
+
+Each `--init-*` command writes exactly one well-known file, refuses to overwrite, and exits 2
+if the file already exists - so re-running is always safe. `--badge` prints README markdown
+showing the current grade if the user wants it displayed.
+
+## Works with every coding agent
+
+The CLI contract above is vendor-neutral - plain commands, JSON out, exit codes - so any
+agent that can run a shell command can use agentdoctor. What differs per tool is where the
+*instructions* live:
+
+| Agent | Mechanism | Install |
+|---|---|---|
+| Claude Code | Skill + plugin (`/agentdoctor:audit`) | `/plugin marketplace add jqntn/agentdoctor` or `npx @jqntn/agentdoctor --init-skill` |
+| OpenAI Codex | `AGENTS.md` | `npx @jqntn/agentdoctor --init-agents` |
+| Cursor | `AGENTS.md` | `npx @jqntn/agentdoctor --init-agents` |
+| Gemini CLI / Jules | `AGENTS.md` | `npx @jqntn/agentdoctor --init-agents` |
+| Anything else | `AGENTS.md`, or just the CLI contract | `npx @jqntn/agentdoctor --init-agents` |
+
+`--init-agents` writes a short marked section (`<!-- agentdoctor:start -->` ...
+`<!-- agentdoctor:end -->`) into `AGENTS.md` - creating the file if absent, appending if
+present, refusing if the section already exists - telling the agent to audit after any config
+edit and how to run the fix loop. It is deliberately ~15 lines: AGENTS.md is always-on
+context for these tools, and bloating it is exactly what agentdoctor's cost rules exist to
+prevent.
+
+Note the skill and the AGENTS.md section install *instructions*, not the binary: both invoke
+`npx @jqntn/agentdoctor`, which prefers a project-local install and otherwise fetches on demand. Pin
+it permanently with `npm install -D @jqntn/agentdoctor`.
+
+For Codex specifically, a reusable custom prompt is one copy away (user-scope, so it works
+across projects):
+
+```sh
+mkdir -p ~/.codex/prompts
+npx @jqntn/agentdoctor --init-agents   # project instructions
+cp node_modules/@jqntn/agentdoctor/skills/config-audit/SKILL.md ~/.codex/prompts/audit-config.md   # optional /audit-config
+```
+
+## The standalone skill and plugin
+
+The canonical skill lives at [`skills/config-audit/`](https://github.com/jqntn/agentdoctor/tree/main/skills/config-audit)
+in the repo and inside the npm package. It contains the audit -> fix workflow plus
+`references/fix-recipes.md` with per-rule fix patterns, and its `description` frontmatter is
+written to trigger on config-audit requests, edits to `.claude/` files, and "my hook isn't
+firing" symptoms.
+
+Three ways to install it:
+
+| Method | Command | Scope |
+|---|---|---|
+| Claude Code plugin | `/plugin marketplace add jqntn/agentdoctor` then `/plugin install agentdoctor` | everywhere (also adds `/agentdoctor:audit`) |
+| CLI | `npx @jqntn/agentdoctor --init-skill` | this project |
+| Manual | `cp -r node_modules/@jqntn/agentdoctor/skills/config-audit .claude/skills/` | anywhere |
+
+All three install the same files - `--init-skill` copies them out of the package, so the
+installed skill cannot drift from the published one (test-enforced).
+
+## For agents working on this repository
+
+The repo root carries an `AGENTS.md` (mirrored by `CLAUDE.md`) with the build/test commands,
+the architectural invariants, and the rules for adding rules. The docs site serves
+[`llms.txt`](https://jqntn.github.io/agentdoctor/llms.txt) and a concatenated
+`llms-full.txt`, and every docs page is also available as raw markdown at the same URL with
+`.md` — agents should prefer those over scraping HTML.