agent-context-md 0.1.0__py3-none-any.whl

agent_context_md-0.1.0.dist-info/METADATA

@@ -0,0 +1,317 @@
+Metadata-Version: 2.4
+Name: agent-context-md
+Version: 0.1.0
+Summary: Generate short, useful AGENTS.md files without repeating what the repo already says.
+Author: Osmane B.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/osmaneb23/agents-md
+Project-URL: Issues, https://github.com/osmaneb23/agents-md/issues
+Keywords: agents.md,ai,cli,codex,claude,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.76; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=2.9; extra == "openai"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.52; extra == "gemini"
+Provides-Extra: dev
+Requires-Dist: build>=1.3; extra == "dev"
+Requires-Dist: pytest>=9.0; extra == "dev"
+Dynamic: license-file
+
+# agents-md
+
+Generate `AGENTS.md` context files that actually help AI coding agents.
+
+[![CI](https://github.com/osmaneb23/agents-md/actions/workflows/ci.yml/badge.svg)](https://github.com/osmaneb23/agents-md/actions)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+![agents-md terminal demo](docs/demo.svg)
+
+*Demo runs on a JS/TS repo. Simpler repos generate shorter files.*
+
+---
+
+ETH Zurich [tested AI coding agents](https://arxiv.org/abs/2602.11988) across 8 benchmarks with auto-generated context files, hand-written files, and nothing. Auto-generated files made performance worse in 5 of 8 cases. Inference cost jumped 20-23%. Tasks took more steps.
+
+The cause: generators write what agents can already read. Your README, your folder structure, your lint rules — the agent figures all of this out on its own. Putting it in AGENTS.md means reading it again on every task and paying for it each time.
+
+`agents-md` reads your existing docs before writing anything. Everything the agent can discover on its own gets filtered out. What's left — exact commands with real flags, conventions the agent would get wrong, hard limits — is what ends up in the file.
+
+This repo's own AGENTS.md was generated by `agents-md`.
+
+---
+
+## Contents
+
+- [Install](#install)
+- [Usage](#usage)
+- [Sample output](#sample-output)
+- [How deduplication works](#how-deduplication-works)
+- [Quality scoring](#quality-scoring)
+- [GitHub Action](#github-action)
+- [What gets detected](#what-gets-detected)
+- [Alternatives](#alternatives)
+- [Development](#development)
+
+---
+
+## Install
+
+```bash
+# Until the first PyPI release is live:
+python -m pip install "git+https://github.com/osmaneb23/agents-md.git"
+
+# After PyPI publication:
+pip install agent-context-md
+```
+
+Zero runtime dependencies. No Node.js, no Docker.
+
+LLM provider SDKs are optional extras — the tool works fully offline without them. From a source checkout:
+
+```bash
+python -m pip install -e .[anthropic]
+python -m pip install -e .[openai]
+python -m pip install -e .[gemini]
+```
+
+After PyPI publication, use `pip install agent-context-md[anthropic]` or run it with uv:
+
+```bash
+uvx --from agent-context-md agents-md init
+```
+
+---
+
+## Usage
+
+**Generate:**
+
+```bash
+# Static analysis only, no API key needed
+agents-md init --no-llm
+
+# With LLM synthesis (picks up key from env)
+ANTHROPIC_API_KEY=sk-...  agents-md init
+OPENAI_API_KEY=sk-...     agents-md init
+GEMINI_API_KEY=...        agents-md init
+
+# Explicit provider + model
+agents-md init --provider anthropic --model <model-id>
+
+# Preview without writing anything
+agents-md init --no-llm --dry-run --verbose
+
+# Append managed sections to a hand-written file
+agents-md init --merge
+```
+
+**Lint** — works on any AGENTS.md, including hand-written ones:
+
+```bash
+agents-md lint                         # score ./AGENTS.md
+agents-md lint path/to/AGENTS.md       # specific file
+agents-md lint --check --threshold 70  # exit 1 if score < 70
+agents-md lint --fix                   # remove duplicate and style-rule lines
+agents-md lint --json                  # machine-readable output
+```
+
+**Keep it current:**
+
+```bash
+agents-md update   # refresh managed sections, leave your notes alone
+agents-md diff     # show what changed in the repo since last generation
+```
+
+---
+
+## Sample output
+
+`agents-md init --no-llm` on a Next.js + TypeScript repo:
+
+```markdown
+## Stack
+- CI: GitHub Actions
+- Framework: Next.js 15.3
+- Language: TypeScript (strict mode)
+- Package Manager: pnpm 10.0.0
+- Test Runner: vitest 3.0.0
+
+## Commands
+- install: `pnpm install`
+- run: `pnpm dev`
+- build: `pnpm build`
+- test: `pnpm test`
+- lint: `pnpm lint`
+
+## Testing
+- Full suite: `pnpm test`
+- Single test: `pnpm vitest run src/auth/login.test.ts -t "should reject expired tokens"`
+- Prefer the narrowest test while iterating. Run the full suite before handing off.
+
+## Boundaries
+### Always Do
+- Run the narrowest relevant test before handing off a code change.
+### Ask First
+- Ask before running `pnpm db:migrate` — it touches migrations.
+- Ask before deleting files, rewriting history, or changing release metadata.
+### Never Do
+- Never commit secrets, tokens, or `.env` files.
+- Never overwrite a hand-written AGENTS.md without `--force` or explicit confirmation.
+```
+
+Sections are wrapped in `<!-- agents-md:start/end:section-name -->` markers. `agents-md update` uses them to refresh individual sections without touching anything you added by hand.
+
+---
+
+## How deduplication works
+
+Before writing anything, the tool reads every Markdown file in your project root and `docs/`. It extracts facts from them — commands, framework mentions, structural notes. Then for each candidate line from the extractors, it asks: does this add anything the agent can't get from those docs?
+
+```
+README says:  "We use pnpm. Run `pnpm install` to get started."
+Extractor:    install: pnpm install
+
+→ Removed. The agent can read the README.
+
+README says:  "Run the tests before pushing."
+Extractor:    single test: pytest tests/test_auth.py::test_login -xvs
+
+→ Kept. The README is vague. The exact command with flags is new.
+```
+
+Boundaries and security lines are always kept, even when they overlap with the README.
+
+Pass `--verbose` to see the full list of what was removed and why.
+
+---
+
+## Quality scoring
+
+`agents-md lint` scores any AGENTS.md out of 100 and tells you exactly what to fix.
+
+| Criterion | Points |
+|---|---|
+| Commands section with 2+ exact commands | 10 |
+| Commands include real flags (`-x`, `--watch`, etc.) | 15 |
+| Single-test command targeting one file or function | 10 |
+| Three-tier boundaries (Always / Ask First / Never) | 20 |
+| Dedicated testing section | 10 |
+| File under 150 lines | 15 |
+| No README duplication | 15 |
+| No linter-owned style rules | 5 |
+
+Score guide:
+
+- **85-100** — This file will improve agent performance.
+- **65-84** — A few improvements would help.
+- **45-64** — Key sections are missing or there's redundant content.
+- **0-44** — This file is likely slowing agent sessions down.
+
+---
+
+## GitHub Action
+
+Fail PRs when the score drops below a threshold:
+
+```yaml
+- uses: actions/checkout@v6
+- uses: actions/setup-python@v6
+  with:
+    python-version: "3.13"
+- uses: osmaneb23/agents-md/.github/actions/agents-md-lint@main
+  with:
+    path: AGENTS.md
+    threshold: "70"
+```
+
+Pin to a release tag once you cut the first release.
+
+---
+
+## What gets detected
+
+<details>
+<summary><strong>Commands</strong></summary>
+
+Scripts and tasks from `package.json`, `Makefile`, `pyproject.toml` (taskipy, poe), `Justfile`, `Taskfile.yml`. Single-test commands are inferred for pytest, unittest, Jest, Vitest, Mocha, Cargo, and Go.
+
+</details>
+
+<details>
+<summary><strong>Stack</strong></summary>
+
+Package manager detected from lock files, never guessed. Framework, language, TypeScript strict mode (from tsconfig), runtime, test runner, linter, type checker, CI system.
+
+</details>
+
+<details>
+<summary><strong>Conventions</strong></summary>
+
+`src/` layout, test naming patterns, TypeScript path aliases, named-export-only modules, barrel files with their import alias, `Result<T,E>` error-as-value patterns, centralized HTTP wrappers, catch blocks that intentionally return fallback values, `.env.example` variables, test fixture and factory directories. Only things an agent would plausibly get wrong on the first attempt.
+
+</details>
+
+<details>
+<summary><strong>Fingerprint</strong></summary>
+
+SHA-256 hashes of key manifests stored in a comment at the bottom of the file. `agents-md diff` compares them against the current state and tells you whether an update is worth running.
+
+</details>
+
+Supported: **Python**, **JavaScript/TypeScript**, **Go**, **Rust**.
+
+---
+
+## Alternatives
+
+| Tool | What it does | Where it falls short |
+|---|---|---|
+| `agents-init` (npm) | Sets up AGENTS.md + MCP config + subagents | No dedup filter. Generates the kind of bloated file the ETH study warns against. |
+| `GenerateAgents.md` (PyPI) | DSPy-based generation, any model | DSPy is a heavy dependency. No dedup. |
+| `AGENTS.md_generator` (Python) | Safe-by-default skeleton | Intentionally minimal. You still fill it in manually. |
+| Hand-written | Full control | Drifts with the codebase. No quality feedback. |
+
+---
+
+## Design decisions
+
+- **Zero runtime dependencies.** The core package installs in seconds. LLM SDKs are opt-in extras.
+- **Non-destructive updates.** `agents-md update` only touches content inside managed markers. `lint --fix` creates a `.bak` before writing. `init` prompts before overwriting.
+- **No guessing.** If the package manager can't be determined from lock files, it's left blank. A wrong command is worse than a missing one.
+- **Short over padded.** The LLM synthesis prompt explicitly tells the model to refuse to pad. A 30-line file beats a 150-line one if the repo is simple.
+- **No Node.js required.** Python only, works anywhere Python runs.
+
+---
+
+## Development
+
+The project's own [AGENTS.md](AGENTS.md) has the authoritative commands, conventions, and boundaries. Check it before changing code or opening a PR.
+
+Before changing scoring weights, deduplication rules, or managed marker formats, open an issue. These are product decisions, not implementation details.
+
+Releases go through PyPI Trusted Publishing via `.github/workflows/publish.yml`. To publish: set up a pending publisher for project `agent-context-md`, repository `osmaneb23/agents-md`, workflow `publish.yml`, environment `pypi`, then run the publish workflow.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for PR expectations.
+
+---
+
+## Sources
+
+- ETH Zurich study: [arxiv.org/abs/2602.11988](https://arxiv.org/abs/2602.11988)
+- AGENTS.md open format: [github.com/agentsmd/agents.md](https://github.com/agentsmd/agents.md)
+- GitHub's analysis of 2,500+ AGENTS.md files: [github.blog](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)
+- Augment Code guide: [augmentcode.com/guides/how-to-build-agents-md](https://www.augmentcode.com/guides/how-to-build-agents-md)

agent_context_md-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+agent_context_md-0.1.0.dist-info/licenses/LICENSE,sha256=jbvVU3M4way6up9Qw6caHhsZbNLTfm8kbOHgvcxCDw8,1066
+agents_md/__init__.py,sha256=P1GcRsT9UCVBKj2k4HpeqKTxV-WDUhmQ4hh0js1FTXc,48
+agents_md/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+agents_md/cli.py,sha256=S2TnauY14CKKHJtp7-4p-waVKKAEiINU1-XP7UjlSvQ,11921
+agents_md/dedup.py,sha256=R-SlWf6nS3g_5kPKVxT6Ihg9KdbAa6nV8TjE4pPVs70,2359
+agents_md/fingerprint.py,sha256=CJBrDW_tH-55DClAib-jbgBxgF5AeHoNoghM9544D_4,2431
+agents_md/generator.py,sha256=4IarPJicFAoTiCQZQaq6gqVQy93j1ZP1wtcwd6QdcFk,7247
+agents_md/llm.py,sha256=NWD4N58rrMu_1KqN3cQOMuzs6OYnLURtiNeakZi6QWA,5111
+agents_md/quality.py,sha256=fMJ4q663CJClpSuK8ftjpImO6PZ6H78aLc55WR94e-o,9115
+agents_md/scanner.py,sha256=I396vYn2yOgVgdFZW5WD9-mjyXPmsNK4F9e08o9u5C4,30699
+agents_md/types.py,sha256=t9Kk1rys9wO_-RLcmGLO_TRPo3oZ2b4er9j-nL3ybaE,1275
+agent_context_md-0.1.0.dist-info/METADATA,sha256=edmqMGgMgbc2A6rjeQck8nyJuJnAlpysilvHBL1s4cs,11419
+agent_context_md-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agent_context_md-0.1.0.dist-info/entry_points.txt,sha256=HpHOJY8cLzsepWtKcyQxYGb0T-nW9nxDea9FMLE4vf4,49
+agent_context_md-0.1.0.dist-info/top_level.txt,sha256=1Z2RjMz96fTECkGK-CK-4h1PTGGadOllGbEQFVZz7QU,10
+agent_context_md-0.1.0.dist-info/RECORD,,

agent_context_md-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_context_md-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agents-md = agents_md.cli:main

agent_context_md-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Osmane B.
+
+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.

agent_context_md-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agents_md

agents_md/__init__.py

@@ -0,0 +1,3 @@
+"""agents-md package."""
+
+__version__ = "0.1.0"

agents_md/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agents_md/cli.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .fingerprint import compare_fingerprints, extract_fingerprint, fingerprint_repo
+from .generator import has_managed_sections, line_count, render_document, render_sections, replace_managed_sections
+from .llm import LlmError, detect_provider, missing_key_message, synthesize_with_llm
+from .quality import apply_fix, format_human, format_json, lint_file
+from .scanner import scan_repo
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not hasattr(args, "handler"):
+        parser.print_help()
+        return 0
+    try:
+        return args.handler(args)
+    except KeyboardInterrupt:
+        print("Interrupted.", file=sys.stderr)
+        return 130
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="agents-md", description="Generate and lint focused AGENTS.md files.")
+    parser.add_argument("--version", action="version", version=f"agents-md {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    init = sub.add_parser("init", help="Analyze the current repo and generate AGENTS.md.")
+    init.add_argument("--no-llm", action="store_true", help="Generate from static extractors only.")
+    init.add_argument("--provider", choices=["anthropic", "openai", "ollama", "gemini"], help="LLM provider for synthesis.")
+    init.add_argument("--model", help="Override the provider default model.")
+    init.add_argument("--output", default="AGENTS.md", help="Output filename.")
+    init.add_argument("--no-symlink", action="store_true", help="Do not create CLAUDE.md symlink.")
+    init.add_argument("--dry-run", action="store_true", help="Print generated content without writing files.")
+    init.add_argument("--force", action="store_true", help="Overwrite existing output without prompting.")
+    init.add_argument("--merge", action="store_true", help="Append managed sections to an existing hand-written file.")
+    init.add_argument("--no-dedup", action="store_true", help="Skip README/docs deduplication.")
+    init.add_argument("--verbose", action="store_true", help="Print scanner diagnostics.")
+    init.set_defaults(handler=cmd_init)
+
+    update = sub.add_parser("update", help="Refresh managed sections of an existing AGENTS.md.")
+    update.add_argument("path", nargs="?", default="AGENTS.md")
+    update.add_argument("--no-llm", action="store_true", help="Do not call an LLM.")
+    update.add_argument("--provider", choices=["anthropic", "openai", "ollama", "gemini"], help="LLM provider for synthesis.")
+    update.add_argument("--model", help="Override the provider default model.")
+    update.add_argument("--no-dedup", action="store_true", help="Skip README/docs deduplication.")
+    update.add_argument("--init-fingerprint", action="store_true", help="Add a fingerprint when updating managed sections.")
+    update.set_defaults(handler=cmd_update)
+
+    lint = sub.add_parser("lint", help="Score an AGENTS.md file.")
+    lint.add_argument("path", nargs="?", default="AGENTS.md")
+    lint.add_argument("--check", action="store_true", help="Exit non-zero if score is below threshold.")
+    lint.add_argument("--threshold", type=int, default=60, help="Minimum score for --check.")
+    lint.add_argument("--fix", action="store_true", help="Remove duplicate/style-rule lines after confirmation.")
+    lint.add_argument("--yes", action="store_true", help="Confirm --fix without prompting.")
+    lint.add_argument("--json", action="store_true", help="Output JSON.")
+    lint.set_defaults(handler=cmd_lint)
+
+    diff = sub.add_parser("diff", help="Show repo changes since AGENTS.md was generated.")
+    diff.add_argument("path", nargs="?", default="AGENTS.md")
+    diff.set_defaults(handler=cmd_diff)
+
+    return parser
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    root = Path.cwd()
+    output = root / args.output
+    existing = output.read_text(encoding="utf-8") if output.exists() else None
+    if existing is not None and args.merge and has_managed_sections(existing):
+        print(f"{output.name} already has managed sections. Run `agents-md update` instead.", file=sys.stderr)
+        return 1
+    if output.exists() and not args.force and not args.dry_run and not args.merge:
+        if not _confirm(f"{output.name} already exists. Overwrite it?"):
+            print("Aborted; existing file was not changed.", file=sys.stderr)
+            return 1
+
+    if args.merge and not args.no_llm:
+        print("LLM synthesis skipped in --merge mode to preserve hand-written content.", file=sys.stderr)
+        args.no_llm = True
+
+    if not args.no_llm:
+        provider = detect_provider(args.provider)
+        if not provider:
+            print(missing_key_message(args.provider), file=sys.stderr)
+            if _confirm("Run once in --no-llm mode instead?"):
+                args.no_llm = True
+            else:
+                return 2
+
+    _progress("Scanning repo")
+    scan = scan_repo(root, output_name=output.name)
+    if args.verbose:
+        _print_scan(scan)
+    if not args.no_dedup:
+        if scan.docs_read:
+            _progress(f"Deduplicating against {', '.join(scan.docs_read)}")
+        else:
+            _progress("Deduplicating against existing docs")
+    _progress("Rendering AGENTS.md")
+    content = render_document(scan, no_dedup=args.no_dedup)
+    if args.verbose:
+        _print_dedup(scan)
+    if existing is not None and args.merge:
+        content = existing.rstrip() + "\n\n" + _managed_body(content)
+    if not args.no_llm:
+        provider = detect_provider(args.provider)
+        if provider:
+            _progress(f"Synthesizing with {provider}")
+            try:
+                content = synthesize_with_llm(content, provider=provider, model=args.model)
+            except LlmError as exc:
+                print(f"LLM synthesis failed: {exc}", file=sys.stderr)
+                return 2
+            if not has_managed_sections(content):
+                print("LLM output omitted managed markers; refusing to write it.", file=sys.stderr)
+                return 2
+
+    if args.dry_run:
+        print(content, end="")
+        _summary(content, output, len(scan.dedup.removed), dry_run=True)
+        return 0
+
+    output.write_text(content, encoding="utf-8")
+    if output.name == "AGENTS.md" and not args.no_symlink:
+        _ensure_claude_symlink(root, output)
+    _summary(content, output, len(scan.dedup.removed), dry_run=False)
+    return 0
+
+
+def cmd_update(args: argparse.Namespace) -> int:
+    path = Path(args.path)
+    if not path.is_file():
+        print(f"{path} does not exist. Run `agents-md init` first.", file=sys.stderr)
+        return 1
+    existing = path.read_text(encoding="utf-8")
+    if not has_managed_sections(existing):
+        print("No managed sections found. Run `agents-md init --merge` to add managed sections without overwriting your file.")
+        return 1
+
+    scan = scan_repo(path.parent.resolve(), output_name=path.name)
+    sections = render_sections(scan, no_dedup=args.no_dedup)
+    updated, changed = replace_managed_sections(existing, sections)
+    if args.init_fingerprint and "agents-md:fingerprint" not in updated:
+        from .fingerprint import encode_fingerprint
+
+        updated = updated.rstrip() + "\n" + encode_fingerprint(fingerprint_repo(path.parent.resolve())) + "\n"
+        changed.append("fingerprint")
+
+    if not args.no_llm:
+        provider = detect_provider(args.provider)
+        if provider:
+            try:
+                updated = synthesize_with_llm(updated, provider=provider, model=args.model)
+            except LlmError as exc:
+                print(f"LLM synthesis failed: {exc}", file=sys.stderr)
+                return 2
+        else:
+            print(f"{missing_key_message(args.provider)} Proceeding with static update.", file=sys.stderr)
+    path.write_text(updated, encoding="utf-8")
+    if changed:
+        print(f"Updated: {', '.join(changed)}.")
+    else:
+        print("No managed section changes detected.")
+    print("Preserved: content outside managed markers.")
+    return 0
+
+
+def cmd_lint(args: argparse.Namespace) -> int:
+    path = Path(args.path)
+    if not path.is_file():
+        if args.check:
+            return 1
+        print(f"{path} does not exist.", file=sys.stderr)
+        return 1
+    result = lint_file(path)
+    if args.fix:
+        if not result.issues:
+            print("No auto-fixable issues detected.")
+            return 0
+        if not args.yes and not _confirm(f"Create {path.name}.bak and remove auto-fixable lines?"):
+            print("Aborted; file was not changed.", file=sys.stderr)
+            return 1
+        backup = apply_fix(path, result)
+        print(f"Fixed {path}; backup written to {backup}.")
+        return 0
+    if args.check:
+        return 0 if result.score >= args.threshold else 1
+    print(format_json(result) if args.json else format_human(result), end="")
+    return 0
+
+
+def cmd_diff(args: argparse.Namespace) -> int:
+    path = Path(args.path)
+    if not path.is_file():
+        print(f"{path} does not exist.", file=sys.stderr)
+        return 1
+    old = extract_fingerprint(path.read_text(encoding="utf-8"))
+    if not old:
+        print("No fingerprint found. Run `agents-md init` or `agents-md update --init-fingerprint`.")
+        return 1
+    current = fingerprint_repo(path.parent.resolve())
+    diff = compare_fingerprints(old, current)
+    for label in ("added", "removed", "changed"):
+        values = diff[label]
+        if values:
+            print(f"{label}: {', '.join(values)}")
+    if not diff["added"] and not diff["removed"] and not diff["changed"]:
+        print("No relevant manifest/config changes detected.")
+    else:
+        print("Recommendation: run `agents-md update` to sync managed sections.")
+    return 0
+
+
+def _confirm(message: str) -> bool:
+    if not sys.stdin.isatty():
+        return False
+    answer = input(f"{message} [y/N] ").strip().lower()
+    return answer in {"y", "yes"}
+
+
+def _progress(message: str) -> None:
+    print(f"{message}...", file=sys.stderr)
+
+
+def _summary(content: str, output: Path, removed: int, *, dry_run: bool) -> None:
+    result = None
+    if output.exists() and not dry_run:
+        result = lint_file(output)
+    score = f"{result.score}/100" if result else "not scored in dry-run"
+    action = "Would write" if dry_run else "Wrote"
+    print(f"{action} {output}: {line_count(content)} lines, quality {score}, dedup removed {removed} item(s).")
+
+
+def _ensure_claude_symlink(root: Path, output: Path) -> None:
+    link = root / "CLAUDE.md"
+    if link.exists() or link.is_symlink():
+        if link.is_symlink() and link.resolve() == output.resolve():
+            return
+        print("CLAUDE.md exists and was left unchanged.", file=sys.stderr)
+        return
+    try:
+        link.symlink_to(output.name)
+    except OSError as exc:
+        print(f"Could not create CLAUDE.md symlink: {exc}", file=sys.stderr)
+
+
+def _print_scan(scan) -> None:
+    print("Detected stack:", file=sys.stderr)
+    for fact in scan.stack:
+        print(f"  - {fact.kind}: {fact.label()} ({fact.source})", file=sys.stderr)
+    print("Detected commands:", file=sys.stderr)
+    for command in scan.commands:
+        print(f"  - {command.category}: {command.command} ({command.source})", file=sys.stderr)
+    if scan.docs_read:
+        print(f"Docs read for dedup: {', '.join(scan.docs_read)}", file=sys.stderr)
+
+
+def _print_dedup(scan) -> None:
+    if scan.dedup.removed:
+        print("Dedup removed:", file=sys.stderr)
+        for item in scan.dedup.removed:
+            print(f"  - {item}", file=sys.stderr)
+    else:
+        print("Dedup removed 0 item(s).", file=sys.stderr)
+
+
+def _managed_body(content: str) -> str:
+    marker = "<!-- agents-md:start:"
+    start = content.find(marker)
+    return content[start:] if start >= 0 else content