docs: add AGENTS.md agent guidelines aligned with repo conventions

[Fahad090NP]

📝 What does this change?

Adds AGENTS.md at the repo root — the machine-readable agent contract that GitHub natively surfaces to Copilot and other AI coding agents. It codifies this repo's existing automation rules (never push/PR/merge without permission, feature branches, Conventional Commits, strict-lint verification) and encodes the review standards we've converged on, all aligned with the codebase's actual style rather than a generic template.

Docs-only — no runtime code.

🧪 How did you test it?

• prettier --check passes on AGENTS.md
• markdownlint-cli2 (repo config) passes — 0 issues
• Pre-commit husky gate (staged-lint + lint-staged) passed on the commit
• CI runs on this PR

✅ Checklist

• npm run compile passes (docs-only — no code change)
• npm run lint passes (docs-only — markdown/prettier verified)
• npm test passes (docs-only — no code change)
• npm run package produces a VSIX (N/A — docs-only)
• I tested it works (N/A — docs-only)
• I updated docs/CHANGELOG if needed (CHANGELOG left for release-time per repo convention)

---

✨ PEACE BE UPON YOU 🤲

[Fahad090NP]

Hi @ltmoerdani — opening this up with the reasoning for why AGENTS.md earns its place alongside CONTRIBUTING.md, not instead of it.

1. It's the file agents actually read.
GitHub natively loads AGENTS.md and feeds it to Copilot and other coding agents on every prompt. CONTRIBUTING.md is a great human-facing doc, but AI tools don't reliably traverse it — AGENTS.md is the standard, guaranteed entry point. Right now an agent working in this repo gets no repo-specific guidance unless a human tells it to read CONTRIBUTING.md. This file closes that gap for free.

2. It encodes standards we already enforce by hand.
Going back through our merged PRs, most review cycles came down to the same handful of lessons: the PR body must match the actual diff (#138, #129), config reads must use the correct section (#125), model lists must stay in sync (#136), numbers in the description must be verified (#110, #136), fixes must cover every branch of a conditional (#138), webview data must be escaped (#138). Putting those in AGENTS.md means future AI contributions land closer to review-ready — fewer round-trips, less of your review time spent on the same recurring feedback.

3. No duplication, no drift.
Rather than re-writing your automation rules, the file references CONTRIBUTING.md as the single source of truth and keeps the agent-specific guidance (workflow, verification, comments) in one small, focused file. It's additive, not competing.

4. It matches this repo, not a generic template.
I deliberately stripped the parts of a stock agent template that don't fit here — the "single-line comments only" rule (this codebase uses JSDoc CONTRACT headers), the "never run lint yourself" rule (this repo's npm run lint is the single gate that includes the tests), and the design-system bullet. What's left mirrors how this repo actually works: Conventional Commits, husky-enforced verification, JSDoc conventions, feature-branch workflow.

5. Zero risk.
Docs-only, prettier + markdownlint clean, husky gate passed on commit, CI runs on the PR. If you decide it's not worth keeping, it's one file to delete — nothing depends on it.

Happy to trim, rewrite, or drop any section you don't agree with. The goal is a file you'd be glad an AI contributor read before opening its first PR.

[Fahad090NP]

You will feel the value of AGENTS when you use it in real life's coding sessions.

PEACE BE UPON YOU.

[ltmoerdani]

Nice one @Fahad090NP, thanks for this. AGENTS.md is a solid addition and I verified the claims myself: the lint single-gate framing is accurate (scripts/lint.ts really runs all 7 checks), prettier and markdownlint pass clean with the repo config, and the automation rules line up with what's already in CONTRIBUTING.md.

One thing before this lands: this repo also ships a more specific agent config plus the automation rules in CONTRIBUTING.md, so I'd rather AGENTS.md stay a short pointer to those instead of restating them, otherwise the rules drift apart over time. I'll also add a line about the merge policy (always merge commit, never squash, it's a hard rule here) since that's the one operational thing AGENTS.md doesn't cover.

I can handle those tweaks after merge, no need for you to rework the PR. CI is green either way.