[LinuxDevil]

What

README.md goes from 805 to 257 lines. It is now a front page with this order:

1. A pitch paragraph and the three differentiators from AUDIT §7, limited to what the code does today: durable sessions and approvals on any host; record/replay plus trajectory evals; Node and Cloudflare Workers with OTel GenAI tracing.
2. Installation. It says plainly that the package is not on npm yet (npm view returns 404). It shows how to scaffold from a checkout with node bin/loushy.js init ../my-agent --sdk-path . (tested), then the 5-line createAgent({ model, instructions }) quickstart.
3. Features: one line per feature, each linking to its docs page.
4. Three examples, each at most 25 lines and type-checked: a tool-using agent with streaming, an approval followed by resume, and durable sessions on SqliteStore.
5. A documentation index (every docs page with a one-line description), an examples index, a CLI table and a one-line deployment summary.
6. Status (alpha, pre-1.0), contributing and license.

Everything the old README had now lives in docs/:

• New pages: tools.md, approvals.md, providers.md, cli.md, flows.md, guardrails.md (guardrails and sandboxed tools), utilities.md (encryption, storage, templates).
• Extended pages:
  • api-overview.md: the architecture diagram, rows for the approval, checkpoint and SQLite stores, budget, and links to the new pages.
  • configuration.md: the full createAgent() options table. Its CLI section now points to cli.md.
  • installation.md and quick-start.md: a note that the package is not on npm yet, with the local-build route.
  • sub-agents.md: the createDelegateTool() example.
• Fixed:
  • Links into README anchors that no longer exist (api-overview, sessions, streaming) now point to approvals.md.
  • workspace-tools.md no longer says createAgent() has no approval store (stale since LOU-D21).
  • The duplicate ## Stores heading in sessions.md is renamed to ## Choosing a store.
• llms.txt and llms-full.txt are regenerated. CHANGELOG gets a one-line Docs entry.

No source code changed.

Why

The repo owner asked for this (LOU-D52): the README was too long and scattered. The new one follows the length and tone of the eve and open-harness READMEs, and no information is lost.

Acceptance criteria

• README is about 200-300 lines (257) in the required order: pitch, install and quickstart, features, three examples, docs/examples/CLI/deploy, status/contributing/license
• Differentiator claims match the current code. Stale claims were dropped: providers loading eagerly, Workers being mock-only, and "Drizzle support"
• Every dropped detail has a home in docs/, and the README links to it
• api-overview.md stays the API index; the README links to it instead of duplicating it
• Every ts block in the README and docs type-checks; the quick-start snippets still run against the packed tarball
• Links checked (docs/docs-links.test.ts, plus a local anchor check over the README and all docs pages: 0 bad)
• llms.txt and llms-full.txt regenerated and committed
• No source changes

How verified

• npm run build: success
• npm run build --workspace=packages/create-loushy-agent: success
• npm run docs:verify-snippets -- --skip-build: all 95 snippet(s) type-check against src/; 6 also run cleanly
• npm run docs:llms:check: exit 0
• npx vitest run docs examples scripts: 10 files, 73 tests passed
• npx tsc --noEmit: exit 0
• npm run lint: 0 errors, 433 warnings. This matches main, since no source changed.
• npm run test:types: no errors
• npx vitest run: 140 files passed, 2056 tests passed, 3 skipped. A first run before building the create-loushy-agent workspace had 4 failures in that package's tests; they pass after the build.
• npm run test:coverage && npm run fallow: ✓ No issues found, exit 0

🤖 Generated with Claude Code

https://claude.ai/code/session_016bY29ibQgv3MDdjAbUT4YR

---

Generated by Claude Code