@jqntn/agentdoctor 0.1.2 → 0.1.3

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 the agentdoctor authors
+Copyright (c) 2026 Julien QUENTIN
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -63,17 +63,24 @@ CLAUDE.md
                  (~$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
+Summary  Grade F  3 errors, 1 warning  (72 rules, 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>`.
+Findings fall into five categories. The bar for a rule is that it catches a failure that
+actually happens **and** stays quiet on legitimate config: a correctly configured project
+reports nothing, which the test suite asserts against a fixture. False positives are treated
+as more severe than missed findings, because a linter that cries wolf gets uninstalled and
+then catches nothing at all.
 
-### Security (22 rules)
+Every rule states what is wrong, why it matters, and what to change instead, and every rule
+has a test. There are 72 today; the current catalogue is always in the
+[rule reference](docs/rules.md), or `agentdoctor --list-rules`.
+
+### Security
 
 The config surface is an execution surface. Blanket `Bash(*)` allows; destructive commands
 pre-approved without confirmation (`sudo`, `rm -rf`, force push, `terraform destroy`,
@@ -83,7 +90,7 @@ Slack, Stripe keys, JWTs, private keys — always reported **redacted**); MCP se
 unpinned packages or carrying tokens in URLs; `bypassPermissions` committed to shared repos;
 loader-hijacking env vars; world-writable config.
 
-### Correctness (26 rules)
+### Correctness
 
 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
@@ -92,7 +99,7 @@ that block nothing (an **error**, because it is a guardrail that only looks like
 malformed hooks and invalid matcher regexes; duplicate agent/skill names; MCP servers with no
 way to start.
 
-### Cost (8 rules)
+### Cost
 
 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
@@ -100,13 +107,13 @@ file with an estimated monthly cost — the estimate assumes the file stays prom
 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)
+### Hygiene
 
 `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)
+### Policy
 
 Team standards, enforced mechanically across every repo. Commit an
 `agentdoctor.policy.json` and these activate — no flag, no account:
@@ -151,7 +158,7 @@ unrelated edits never invalidate them:
 
 ```sh
 agentdoctor --write-baseline .agentdoctor-baseline.json   # once
-agentdoctor --baseline .agentdoctor-baseline.json          # in CI
+agentdoctor --baseline .agentdoctor-baseline.json         # in CI
 ```
 
 [CI guide](docs/ci.md) · [Baselines](docs/baselines.md)
@@ -164,13 +171,18 @@ deterministic ordering, redacted secrets safe for model context, pipe-safe outpu
 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:
+[config-audit skill](plugin/skills/config-audit/SKILL.md) (audit -> fix loop, with fix recipes) and
+invokable as `/agentdoctor:config-audit`. 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
+# in Claude Code, then: /plugin install agentdoctor
+/plugin marketplace add jqntn/agentdoctor
+
+# copies the skill into this project only
+npx @jqntn/agentdoctor --init-skill
+
+# by hand, from an installed package
+cp -r node_modules/@jqntn/agentdoctor/plugin/skills/config-audit .claude/skills/
 ```
 
 [Agent guide](docs/agents.md)
@@ -192,7 +204,7 @@ cp -r node_modules/@jqntn/agentdoctor/skills/config-audit .claude/skills/   # ma
 |---|---|
 | [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 |
+| [Rule reference](docs/rules.md) | Every rule, with the reasoning behind it |
 | [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 |
@@ -212,4 +224,4 @@ invariants (every rule tested, zero findings on the clean fixture, zero dependen
 
 ## License
 
-[MIT](LICENSE). All 72 rules, every output format, no accounts, no telemetry, no paid tier.
+[MIT](LICENSE). Every rule, every output format, no accounts, no telemetry, no paid tier.

package/docs/agents.md

@@ -48,9 +48,11 @@ When an agent decides this tool belongs in a project (for example after an audit
 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
+npx @jqntn/agentdoctor --init-ci     # writes .github/workflows/agentdoctor.yml
+npx @jqntn/agentdoctor --init-skill  # writes .claude/skills/config-audit/SKILL.md
+
+# only if the project already has findings today
+npx @jqntn/agentdoctor --write-baseline .agentdoctor-baseline.json
 ```
 
 Each `--init-*` command writes exactly one well-known file, refuses to overwrite, and exits 2
@@ -65,7 +67,7 @@ agent that can run a shell command can use agentdoctor. What differs per tool is
 
 | Agent | Mechanism | Install |
 |---|---|---|
-| Claude Code | Skill + plugin (`/agentdoctor:audit`) | `/plugin marketplace add jqntn/agentdoctor` or `npx @jqntn/agentdoctor --init-skill` |
+| Claude Code | Skill + plugin (`/agentdoctor:config-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` |
@@ -87,13 +89,16 @@ 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
+# project instructions, read by Codex
+npx @jqntn/agentdoctor --init-agents
+
+# optional: a reusable /audit-config prompt, user-scoped across projects
+cp node_modules/@jqntn/agentdoctor/plugin/skills/config-audit/SKILL.md ~/.codex/prompts/audit-config.md
 ```
 
 ## The standalone skill and plugin
 
-The canonical skill lives at [`skills/config-audit/`](https://github.com/jqntn/agentdoctor/tree/main/skills/config-audit)
+The canonical skill lives at [`plugin/skills/config-audit/`](https://github.com/jqntn/agentdoctor/tree/main/plugin/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
@@ -103,9 +108,9 @@ 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`) |
+| Claude Code plugin | `/plugin marketplace add jqntn/agentdoctor` then `/plugin install agentdoctor` | everywhere, invokable as `/agentdoctor:config-audit` |
 | CLI | `npx @jqntn/agentdoctor --init-skill` | this project |
-| Manual | `cp -r node_modules/@jqntn/agentdoctor/skills/config-audit .claude/skills/` | anywhere |
+| Manual | `cp -r node_modules/@jqntn/agentdoctor/plugin/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).

package/docs/getting-started.md

@@ -16,7 +16,7 @@ npx @jqntn/agentdoctor
 Or install it:
 
 ```sh
-npm install -g @jqntn/agentdoctor     # global CLI
+npm install -g @jqntn/agentdoctor    # global CLI
 npm install -D @jqntn/agentdoctor    # per-project, for CI
 ```
 
@@ -96,4 +96,4 @@ score card (rule ids and counts only - safe to share from private repos), and
 - [CI setup](ci.md) — SARIF annotations, exit-code gating
 - [Baselines](baselines.md) — adopting agentdoctor on a repo that already has findings
 - [Team policy](policy.md) — holding many repos to one standard
-- [Rule reference](rules.md) — all 72 rules and the reasoning behind each
+- [Rule reference](rules.md) — every rule and the reasoning behind it

package/docs/privacy.md

@@ -0,0 +1,60 @@
+# Privacy
+
+**agentdoctor collects nothing, transmits nothing, and has no servers.**
+
+That claim is easy to make and hard to trust, so here is exactly what the tool does, and how
+you can verify each point yourself.
+
+## What it reads
+
+Only files in the project you point it at, plus your user-level configuration in `~/.claude`
+unless you pass `--no-user`:
+
+`.claude/settings.json`, `.claude/settings.local.json`, `~/.claude/settings.json`, `.mcp.json`,
+`CLAUDE.md` / `CLAUDE.local.md` / `AGENTS.md`, `.claude/agents/*.md`,
+`.claude/skills/*/SKILL.md`, `.claude/commands/*.md`, `.claude/hooks/*`,
+`.claude/keybindings.json`, and `.gitignore`.
+
+## What it never reads
+
+Credential files are excluded **by path, before anything opens them**:
+`.credentials.json`, `credentials.json`, `.netrc`, `id_rsa`, `id_ed25519`. The report tells you
+how many files were skipped for this reason. A test in the suite plants a tripwire value inside
+a credentials file and asserts it can never appear in any output.
+
+## What leaves your machine
+
+Nothing. There is no telemetry, no analytics, no crash reporting, no licence check, no update
+check, and no phone-home of any kind. The tool makes **zero network requests**. You can confirm
+this by running it with the network disabled, or by reading the source — there is no HTTP client
+in it, and it has zero dependencies, so there is no transitive code that could add one.
+
+## What it writes
+
+Nothing, unless you explicitly ask:
+
+- `--write-baseline <file>` writes a list of accepted finding fingerprints
+- `--init-ci`, `--init-skill`, `--init-agents`, `--init-policy` each create one well-known file
+  and refuse to overwrite an existing one
+
+It never edits your configuration. Findings tell you what to change; the change is yours.
+
+## Secrets in output
+
+When a rule detects a credential-shaped value, the finding shows a short prefix and suffix with
+`(redacted)` — never the value. This holds in every output format, so reports are safe to paste
+into an issue, a CI log, or a model's context.
+
+`--share` goes further: it emits only rule ids and counts, never file paths, messages, or
+snippets, so a score card is safe to post publicly from a private repository.
+
+## This website
+
+Static files served by GitHub Pages. No analytics, no cookies, no trackers, no fonts or scripts
+loaded from third parties. The one exception is a linked badge image hosted by openhunts.com in
+the footer; requesting it reveals your IP address to that host, as any remote image does.
+
+## Contact
+
+Questions or a discrepancy between this page and the code:
+<https://github.com/jqntn/agentdoctor/issues>

package/docs/rules.md

@@ -1,6 +1,7 @@
 # Rule reference
 
-72 rules. `agentdoctor --explain <rule-id>` prints any of these from the CLI.
+Every rule, with the reasoning behind it - 72 in total. `agentdoctor --explain <rule-id>`
+prints any of these from the CLI, and `--list-rules` prints the catalogue.
 
 ## Correctness
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jqntn/agentdoctor",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Lint and grade your AI coding-agent configuration: permissions, hooks, MCP servers, skills, subagents and CLAUDE.md. Catches silent failures, security holes and context waste, with fixes. Zero dependencies, no telemetry.",
   "keywords": [
     "agent",
@@ -57,7 +57,7 @@
     "LICENSE",
     "docs",
     "schemas",
-    "skills"
+    "plugin"
   ],
   "scripts": {
     "test": "node --test",

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "agentdoctor",
+  "description": "Audit and fix AI coding-agent configuration: permissions, hooks, MCP servers, skills and memory files. Adds the config-audit skill, invokable as /agentdoctor:config-audit. The linter itself runs via npx - nothing else to install.",
+  "version": "0.1.3",
+  "author": {
+    "name": "Julien QUENTIN",
+    "url": "https://github.com/jqntn"
+  },
+  "homepage": "https://jqntn.github.io/agentdoctor/",
+  "repository": "https://github.com/jqntn/agentdoctor",
+  "license": "MIT",
+  "keywords": [
+    "lint",
+    "audit",
+    "security",
+    "agent-config",
+    "mcp",
+    "hooks",
+    "permissions"
+  ]
+}

package/plugin/README.md

@@ -0,0 +1,10 @@
+# agentdoctor (Claude Code plugin)
+
+This directory is the installable plugin: a manifest and the `config-audit` skill, and nothing
+else. It is deliberately separate from the repository root so that installing the plugin fetches
+only these files — not the linter's source, its test fixtures, or the site generator.
+
+The skill shells out to `npx @jqntn/agentdoctor`, so the plugin itself installs no binary.
+
+- Source and issues: <https://github.com/jqntn/agentdoctor>
+- Documentation: <https://jqntn.github.io/agentdoctor/>

package/{skills → plugin/skills}/config-audit/SKILL.md

@@ -5,8 +5,8 @@ description: Audit and fix AI coding-agent configuration with agentdoctor. Use w
 
 # Audit agent configuration with agentdoctor
 
-agentdoctor is a zero-dependency linter for agent config (72 rules: security, correctness,
-cost, hygiene, team policy). It makes no network calls and never opens credential files, so it
+agentdoctor is a zero-dependency linter for agent config, covering security, correctness,
+cost, hygiene and team policy. It makes no network calls and never opens credential files, so it
 is safe to run unattended in any project.
 
 ## Run the audit

package/src/adopt.js

@@ -54,11 +54,11 @@ jobs:
 export const SKILL_PATH = '.claude/skills/config-audit';
 
 /**
- * The canonical skill ships inside the package at skills/config-audit/ - the
- * same files served by the plugin marketplace - so an installed skill can
- * never drift from the published one.
+ * The canonical skill ships inside the package at plugin/skills/config-audit/ -
+ * the same files the plugin marketplace serves - so a skill installed either
+ * way can never drift from the published one.
  */
-const PACKAGED_SKILL = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', 'config-audit');
+const PACKAGED_SKILL = join(dirname(fileURLToPath(import.meta.url)), '..', 'plugin', 'skills', 'config-audit');
 
 /** Writes a file if absent. Returns a { written, path, message } outcome. */
 function writeOnce(root, relative, contents) {

package/src/index.js

@@ -3,7 +3,7 @@ import { lint, fingerprint, helpers } from './engine.js';
 import { allRules, CATEGORIES } from './rules/index.js';
 import { loadPolicy } from './rules/policy.js';
 
-export const VERSION = '0.1.2';
+export const VERSION = '0.1.3';
 
 /**
  * One-call entry point: discover config, load any team policy, run every rule.

package/src/report/terminal.js

@@ -120,7 +120,7 @@ function summaryLine(s, counts, input) {
   const summary = parts.length ? parts.join(', ') : s.green('clean');
   const grade = computeGrade(input.findings);
   const gradeColor = grade.startsWith('A') ? s.green : (grade === 'B' || grade === 'C' ? s.yellow : s.red);
-  lines.push(`${s.bold('Summary')}  ${s.bold(gradeColor(`Grade ${grade}`))}  ${summary}  ${s.dim(`- ${input.ran.length} rules in ${input.elapsedMs}ms`)}`);
+  lines.push(`${s.bold('Summary')}  ${s.bold(gradeColor(`Grade ${grade}`))}  ${summary}  ${s.dim(`(${input.ran.length} rules, ${input.elapsedMs}ms)`)}`);
 
   if (input.suppressed > 0) {
     const word = input.suppressed === 1 ? 'finding' : 'findings';
@@ -128,8 +128,9 @@ function summaryLine(s, counts, input) {
   }
   const skipped = input.workspace.skipped ?? [];
   if (skipped.length > 0) {
-    lines.push(s.dim(`         ${skipped.length} file(s) skipped - credential files are never read`));
+    const fileWord = skipped.length === 1 ? 'file' : 'files';
+    lines.push(s.dim(`         ${skipped.length} ${fileWord} skipped: credential files are never read`));
   }
-  lines.push(s.dim(`         Share the grade: agentdoctor --share  -  gate it in CI: agentdoctor --init-ci`));
+  lines.push(s.dim('         Share the grade with `agentdoctor --share`, or gate it in CI with `--init-ci`.'));
   return lines.join('\n');
 }