docs: rewrite README for non-technical readers

[vreshch]

Why

Owner feedback: the README read as too technical. It should serve non-technical, simple-to-setup readers first - "empower your agents with local memory that syncs across devices."

This rewrite reorders the README from simplest to deepest: a plain-language intro, a 3-step quickstart anyone can follow, outcome-framed bullets of what your AI can do, and a short sync section. All deep material is relocated (not deleted) into docs/reference.md.

Before -> after outline

Before: install, quickstart (5 verbs), architecture, full command reference (memory/vault/setup/daemon/update flag tables), sync deep-dive, MCP integration, the daemon internals, environment table, development, license.

After:

• Title + plain tagline: "Give every AI on your machine one shared memory - plain markdown you own, synced across your devices."
• 3-4 sentence plain intro (what it does for you, not how).
• Architecture diagram (image reference unchanged).
• Quickstart - 3 copy-paste steps: install -> agentage vault add notes --local -> claude mcp add --transport http agentage http://127.0.0.1:4243/mcp.
• "What your AI can do" - the 6 memory verbs as outcomes, not tool names.
• "Sync across devices" - agentage setup, background sync, files stay yours; git-remote option in one line.
• "Going deeper" - links to docs.
• Short Development + License.

Where technical content moved

New file docs/reference.md holds the full command reference (memory/vault/setup/status/daemon/update), the in-depth MCP integration section (HTTP transport + .mcp.json example), the daemon internals + security model, the sync deep-dive, and the environment-variable table. Nothing was lost - it was relocated. docs/architecture.md is unchanged.

Notes

• Connect step uses the daemon HTTP transport (claude mcp add --transport http ...). The stdio agentage mcp command no longer exists.
• No em dashes; hyphens throughout. Amber diagram untouched.
• npm run verify green (409 tests pass, build clean). No test greps the README.

[github-actions]

🎉 PR Validation ✅ PASSED

Commit: cb3122c0ad9630dcaebbda06ce2190faf2ae168c
Branch: feature/readme-simple

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-08T22:04:37.430Z