repo hygiene + docs: templates, dependabot, AGENTS MCP section, troubleshooting, examples/

[DrBaher]

Summary

One PR bundling six small polish items from the "what's left to polish the CLI" review. No code change, no version bump, no locked-surface touch.

What changes

.github/

• ISSUE_TEMPLATE/bug_report.md — structured bug-report fields (what happened, what you expected, repro, environment, exit code).
• ISSUE_TEMPLATE/feature_request.md — feature template that reminds reporters of the deterministic-by-design contract and lists sibling-CLI alternatives so requests don't reinvent draft-cli / nda-review-cli / sign-cli / etc.
• ISSUE_TEMPLATE/config.yml — disables blank issues; surfaces security-advisory + suite-discussion links.
• pull_request_template.md — standardizes PR bodies (summary, what changes, why this design, test plan, schema impact, version impact).
• dependabot.yml — weekly npm bumps grouped patch/minor for root + mcp/; monthly github-actions bumps. Majors stay separate so e.g. pdfjs-dist majors get explicit review.

AGENTS.md

• New "Invoking via MCP" section right above "Failure diagnosis". Documents the three tools, the install incantation, Claude Desktop / Claude Code config block, and the success-with-content posture. Cross-cites mcp/README.md and docs/mcp.md.

GETTING_STARTED.md

• New "Troubleshooting" section above "Next steps". Covers:
  • The npx bin-name pitfall (npm 10.x quirk → use -p compare-cli@latest -- compare).
  • Scanned-PDF zero-text extraction (point at ocrmypdf; we don't bundle OCR).
  • --demo's deliberate exit 2 (it's a fixture, not a bug).
  • The EPEERINVALID warning for compare-cli-mcp@0.1.0 against compare-cli@0.3.0+ (fixed in MCP 0.1.1).
  • "no agreed round found" → the three-tier resolution.
  • CI gate patterns and how 0/2/3/4 map to publish-blocking decisions.

examples/

• base.md — sample negotiated NDA. Five clauses, plain markdown.
• cand-clean.md — byte-equivalent to base.md. Exit 0.
• cand-substantive.md — Term clause changed (two → three years), Confidentiality weakened. Exit 2.
• cand-cosmetic.md — curly quotes + paragraph re-wrapping only. Exit 3.
• negotiation.json — canonical nda-review-cli state-file shape (status: converged, populated signoffs).
• README.md — explains each file and shows commands for every public flag against them (--check, --sarif, --only-clauses, --from-negotiation, etc.). Notes examples/ doesn't ship in the npm tarball.

All four expected exit codes verified locally before commit:

• compare base.md cand-clean.md → 0 ✓
• compare base.md cand-substantive.md → 2 ✓
• compare base.md cand-cosmetic.md → 3 ✓
• compare --from-negotiation negotiation.json cand-clean.md → 0 ✓

Numbers

• 13 files changed (8 new, 2 modified, +584 / -2 by line count)
• No tests added (templates / docs / fixtures)
• No code change in compare-cli.mjs or mcp/
• No version bump
• Locked surfaces (exit_class, --json shape, clause-detection rule) unchanged

Test plan

• npm test — 206/206 passing (unchanged)
• cd mcp && npm test — 22/22 passing (unchanged)
• Manual: all four example commands produce documented exit codes
• CI on push

Out of scope (deliberate)

• Husky / pre-commit hooks — CI matrix already catches issues; pre-commit is overkill for a single-author repo.
• Coverage badge from an external service — the 80% gate in CI is sufficient.
• Funding / Sponsors file — not the user's revenue model.
• Asciinema demo recording — ages badly; the --demo flag is interactive enough.

🤖 Generated with Claude Code