docs: scrub README + add AGENTS.md

[manojp99]

Summary

This docs-only PR addresses two longstanding gaps:

1. README scrubbed of accumulated drift — verified against the live engine through comprehensive CLI probe battery
2. New AGENTS.md added — establishes canonical per-repo contributor conventions per foundation guidance

No code changes, no behavior changes, no version bumps.

Verification

Changes verified against live DTU instance aaa-readme-scrub (now destroyed) using uv tool install . from local source with full probe battery against Anthropic API:

• --help flag
• run --help flag
• doctor command
• config show command
• Live turns against Anthropic API
• Protocol compatibility
• Flag conflict rejection
• Embedding example imports
• Python wrapper SDK examples

README Drift Corrections

Area	Was	Now
Engine version	0.3.0	0.6.0 (PR #55)
Wire protocol	0.2.0	0.3.0 (PR #56)
TS wrapper version	0.4.0	0.7.0 (PR #55)
Python wrapper	amplifier_agent_client in wrappers/python/	amplifier-agent-py@0.3.0 in wrappers/python-py/ (PR #56)
Storage paths	$XDG_CACHE_HOME / $XDG_STATE_HOME	$AMPLIFIER_AGENT_HOME (defaults to ~/.amplifier-agent/) — design 2026-06-11-drop-xdg-and-flag-cleanup.md
--output default	json	text (PR #51)
Quick start examples	bare run "prompt"	run -y "prompt" — headless runs now require explicit -y/-n/approval.mode; no more silent auto-deny
Admin commands	missing migrate, models, update, version	now included; migrate is user-invoked (PR #52)
run flag table	listed dropped flags --mcp-config-path, --host-capabilities	drops both; adds --display, --cwd, --workspace, --config
Embedding example	imports valid but approval mode was "no"	updated to "yes" to reflect mandatory approval policy
Mode A / Mode B framing	"Modes" table, "Wire protocol (Mode A)" header, explicit Mode B mention	all removed per maintainer direction — there is only one mode now

AGENTS.md

Brand new file (~175 lines) establishing canonical contributor conventions:

• Repository structure and directory purposes
• Build, lint, and test commands (uv run, bun run, pnpm test)
• Cross-component invariants (6 constraints on protocol bumps, wrapper coordination, etc.)
• Design-doc-driven development convention (docs/designs/YYYY-MM-DD-slug.md)
• Conventional commit scopes observed in recent history
• Common pitfalls and definition of done checklist

References

Related design documents and PRs:

• Design: 2026-06-11-drop-xdg-and-flag-cleanup.md
• Design: 2026-05-24-aaa-v2-mode-a-pivot-amendment.md
• PR feat(cli): default --output to text, reject conflicting flag combinations #51 — --output default change
• PR refactor(migration): make migrations user-invoked via 'amplifier-agent migrate' #52 — user-invoked migrate command
• PR chore(release): bump engine to 0.6.0 and TS wrapper to 0.7.0 #55 — engine 0.6.0, TS wrapper 0.7.0
• PR feat(wrapper-py): replace amplifier-agent-client with amplifier-agent-py at protocol 0.3.0 #56 — wire protocol 0.3.0, Python wrapper updates