docs(launch): reposition README + cookbook + sanitization docs

[faculopezscala]

Summary

The 5 code PRs (#2-#6) deliver the engineering for the launch. This PR delivers everything user-facing: the README pitch, the package metadata, the docs/ folder, and the CHANGELOG.

⚠ Merge order: this PR depends on PRs #2, #3, #4, #5, and #6. The new README references commands that those PRs add (sow sandbox, sow doctor <connector>, --allow-unsafe, the sub-second reset). Land them first, rebase this against main, then merge.

What changes for the user

Before: GitHub repo says "Safe test databases from production Postgres." Generic developer-productivity pitch. No mention of Claude, Cursor, agents, or the anxiety reduction story.

After: GitHub repo says "Stop letting Claude touch your prod database." Body explains the moment of pain (your coding agent is about to do something database-adjacent and you feel that quiet pang) and positions sow as the safety layer. The "Why sow" section leads with "Built for coding agents." The docs link to a 3-workflow cookbook.

Files changed

README.md

• Hero rewritten around the new positioning
• New "Why sow" section emphasizing agent-first design (22 MCP tools, sub-second reset, fail-closed sanitization, 100% local)
• New "How It Works" diagram showing the template-DB shape (one container per connector, N branch DBs inside)
• New "Cookbook" section linking to docs/cookbook.md
• New "Documentation" section indexing docs/
• Quick Start updated to lead with sow sandbox

packages/cli/package.json

• Description: "Stop letting Claude touch your prod database. PII-safe local Postgres sandbox for coding agents."
• Keywords: added ai-agents, coding-agents, claude-code, cursor, sandbox, mcp

packages/core/package.json

• Description repositioned to mention coding-agent sandboxes
• Keywords: added ai-agents, coding-agents, sandbox

packages/mcp/package.json

• Bug fix: description said "15 tools", actual count is 22 (verified with grep -c "defineTool" packages/mcp/src/index.ts)
• Description: "sow MCP server — 22 tools for coding agents (Claude Code, Cursor, Codex) to safely manage Postgres sandboxes"
• Keywords: added claude-code, cursor, codex, coding-agents, sandbox

docs/sandbox.md (new, ~80 lines)

• The sow sandbox flagship command, full flag table, .env.local backup/revert flow, when not to use it

docs/sanitization.md (new, ~140 lines)

• The PII type table (what gets sanitized automatically)
• JSONB walking with concrete before/after example
• The fail-closed gate and --allow-unsafe escape hatch
• Custom rules via .sow.yml
• What sow does NOT do (free-text NER, encryption, cloud relay)
• Read-only on the source guarantee with the security audit reference

docs/cookbook.md (new, ~120 lines)

Three end-to-end workflows with copy-pasteable prompts:

1. Let Claude refactor your schema without fear — drop a column, verify, reset, retry
2. Let Cursor generate seed data for a new feature — 100 users, 30 teams, realistic distributions
3. Let your coding agent debug a failing migration — replay against the sandbox, fix, verify

Plus the "agent reset loop" pattern diagram and operational tips.

CHANGELOG.md (new)

Scaffold with three sections:

• [Unreleased] documenting the planned PR refactor(core): Postgres template databases for sub-second branch reset #2-refactor(core): sampler warnings + dynamic skip + batched fetch (Lane A rest) #6 features under Added / Changed
• [0.1.14] documenting the SQL injection security fix that shipped earlier this session
• [0.1.13] one-line summary of the initial public release

Tests

No source code changed. Sanity check: bunx vitest run → 89/89 passing. bunx turbo build → 3/3 packages built. bunx eslint clean on touched files (none of which are source).

Pre-Landing Review

This PR is documentation only. No security surface, no data flow, no new dependencies. The review checklist is N/A.

Known forward-looking claims in the README

The new README mentions features that ship in PRs #2-#6. If those PRs don't merge before this one, the README will document commands that don't exist on main yet. The dependency note at the top of this PR makes that explicit. Recommended merge order:

1. PR chore(ci): tag-driven release workflow #5 (release workflow) — small, isolated, no dependencies
2. PR refactor(core): sampler warnings + dynamic skip + batched fetch (Lane A rest) #6 (sampler warnings + skip + batching) — Lane A rest
3. PR feat(cli): add sow sandbox command + env-patch module #4 (sow sandbox + env-patch) — adds the flagship command
4. PR fix(core): sanitize JSONB + fail-closed gate + Postgres type coverage #3 (JSONB + fail-closed gate) — adds --allow-unsafe
5. PR refactor(core): Postgres template databases for sub-second branch reset #2 (template DB reset) — biggest change, lands last
6. This PR (docs(launch): reposition README + cookbook + sanitization docs #7) — rebase against main and merge

After this PR lands, run gh release view v1.0.0 (cut via the new version-bump.yml from PR #5) and the launch is ready.

Test plan

• README parses cleanly (no leftover XML, 137 lines)
• Three docs/ files exist and link from the README
• CHANGELOG.md has three sections (Unreleased, 0.1.14, 0.1.13)
• All three package.json descriptions updated
• MCP tool count is correct (22, verified with grep)
• bunx vitest run 89/89
• bunx turbo build clean
• Post-rebase: verify README still references only commands that exist on main
• Post-merge: verify the GitHub repo page renders the new pitch correctly

🤖 Generated with Claude Code