docs: tighten agent operating guide

[thymikee]

Summary

Tighten AGENTS.md as the repo's README-for-agents by replacing brittle static file inventories with durable source-owner lookup guidance.

Preserve the high-value operating rules for routing, testing, device hygiene, diagnostics, PR review, and validation expectations.

Validation

Docs-only change. Verified the patch is scoped to AGENTS.md, ran git diff --check, and grepped for removed stale inventory sections.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.5 MB	1.5 MB	0 B
JS gzip	491.3 kB	491.3 kB	0 B
npm tarball	590.3 kB	590.3 kB	0 B
npm unpacked	2.1 MB	2.1 MB	0 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	26.7 ms	27.2 ms	+0.5 ms
CLI --help	52.2 ms	52.5 ms	+0.3 ms

Top changed chunks: no changes in the largest emitted chunks.

[thymikee]

Ready for human review from my pass. This is docs-only (AGENTS.md), rebased cleanly onto current main, and all PR checks are green.

I reviewed the final diff after the rebase: it keeps the high-value non-obvious rules/testing/routing guidance, removes the brittle static file inventory, and uses the agents.md-style “README for agents” framing without making the repo guide depend on the external site. Local sanity checks on the rebased branch:

git diff --check origin/main...HEAD
rg -n '<<<<<<<|=======|>>>>>>>' AGENTS.md
rg -n 'src/utils/cli-help|src/utils/cli-flags|src/utils/__tests__/args\.test\.ts' AGENTS.md

The rg checks returned no matches. I also attempted the requested independent claude -p review earlier, but this environment's Claude CLI is not logged in, so that signal is unavailable here.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-05 06:17 UTC