docs: README overhaul with architecture diagram

[vreshch]

What

README overhaul plus a hand-authored architecture diagram, aligned to master after #238-#245. Ready as the npm landing page.

Touches only README.md and docs/** - no src/, package.json, or workflows.

Changes

• docs/architecture.svg - hand-written SVG (no render tooling). Neutral background with dark text on light boxes, so it reads in both light and dark GitHub themes and on npm. Shows AI tools -> MCP (stdio agentage mcp + daemon HTTP /mcp on 127.0.0.1:4243) -> CLI + local daemon (single writer) -> local vaults (git-per-vault, @agentage/memory-core) -> sync out to git remotes and account sync (labeled protocol-neutrally, no internal tech named).
• README.md restructured for a first-time reader: What is this -> Install -> Quickstart (local-only first, then optional agentage setup) -> Architecture (diagram) -> Command reference -> Sync -> MCP integration -> Daemon -> Env vars -> Development.
• docs/architecture.md - short walk-through of the diagram.

Reality-check vs master

Built the CLI (npm run build) and verified every command and flag against the live --help output. Corrected drift from the merged PRs:

• vault add now defaults to an account vault; --local [path], --git <remote>, --path <dir> are the alternatives.
• vault sync [name] now covers git and the account channel; progress prints per vault.
• Documented the update command and --no-daemon global flag.
• Daemon section notes the loopback-only, token-guarded, cross-origin-rejecting API and port-in-use reporting (fix(daemon): harden local API against CSRF and DNS rebinding #243, fix(daemon): lifecycle races and port-in-use handling #244).
• Friendly memory errors + non-zero exits (fix(memory): edge cases, friendly errors, fail-fast lock perms #240); 64 KB read clamp and secret refusal.
• Describes no specific src/ file paths (a sibling PR is moving src/sync/ paths).

Verification

• npm run verify green: 405 unit tests pass, type-check + lint + format:check + build clean.
• Ran the offline quickstart end-to-end against the built dist/cli.js (vault add --local, write via stdin, list, search, read @vault/path) - all pass.
• Rendered docs/architecture.svg to PNG and eyeballed legibility.

Note: format:check only globs {src,e2e}/**/*.ts, so it does not lint markdown; README changes are prose-only.

[github-actions]

🎉 PR Validation ✅ PASSED

Commit: 54c529d9bb1ceb12ba0b0a992fc434e0d0930ea1
Branch: docs/readme-architecture

Checks:

• ✅ Release guard (no version/changelog changes)
• ✅ Dependencies installed
• ✅ Type check passed
• ✅ Linting passed
• ✅ Format check passed
• ✅ Tests + coverage passed
• ✅ Build successful

Ready to merge! ✨

---

🔗 View workflow run
⏰ Generated at: 2026-07-07T22:29:33.087Z