docs(readme): benchmark improvements from repo audit

[sabbah13]

Summary

Applied 15 specific improvements from a benchmark analysis against browser-use, claude-task-master, E2B, AgentOps, Firecrawl, n8n, and Dify:

• Fix duplicate "How it works" heading (renamed to "What gets captured" + "Architecture")
• Rename "Cursor-driven" to "Delta-only polling" (avoids Cursor IDE confusion — high-priority fix)
• Add CI badge + npm version badge; drop low-signal Discussions badge
• Shorten sub-tagline to 3 punchy clauses
• Update GIF alt text to describe what demo actually shows
• Demote demo link from h3 to bold inline; add sub-caption
• Add "Who this is for" sentence after intro
• Surface "No API key needed" + "local-first" in first 300 words (top two visitor objections)
• Replace > Why this exists. blockquote with plain prose paragraphs
• Add requirements block before install
• Combine CLI install into single command with &&
• Split features table into Core / Technical tiers (9 equal-weight rows -> 2 clear groups)
• Collapse shipped roadmap checkboxes into single "Shipped:" line
• Remove Discord/Newsletter star-threshold placeholders (signals project is unready)
• Remove Star History chart (flat line at 4 stars actively undermines credibility)
• Add "Used by maintainer daily" honest social proof

Test plan

• README renders correctly on GitHub
• All links resolve (demo, docs, contributing, badges)
• Mermaid diagram renders in GitHub preview

🤖 Generated with Claude Code

[sabbah13]

Automated Code Review

Verdict: ⚠️ REQUEST CHANGES

Summary

A README overhaul benchmarked against comparable open-source AI tools: fixes a duplicate "How it works" heading, renames "Cursor-driven" to "Delta-only polling" (removes the Cursor IDE ambiguity), adds CI and npm version badges, splits the feature table into Core/Technical tiers, removes unready social-proof placeholders (star-threshold Discord/Newsletter, flat star-history chart), and adds a requirements block before install. The edits are well-reasoned and measurably improve first-impression clarity.

---

Issues (must fix before merge)

1. Code changes bundled into a docs(readme) PR

   Despite the commit prefix, this PR also modifies:

   • .github/workflows/ci.yml — moves pnpm build before pnpm typecheck
   • packages/artifact/src/App.tsx — adds ColumnType return annotation, as SourceType cast
   • packages/artifact/src/__tests__/storage.test.ts — as unknown as cast, non-null assertion on result[0]!.title

   These appear to be the same TypeScript strict-mode fixes present in PR feat(0.4.14): VSCode-kanban feature parity (restore_task, rename_label, undo, column-aware new task, TASKS_DIR) #35, likely carried along from a shared base commit. They do not belong in a docs PR. Options:

   • Drop these files from this branch and rebase on clean main (preferred if PR feat(0.4.14): VSCode-kanban feature parity (restore_task, rename_label, undo, column-aware new task, TASKS_DIR) #35 is landing first)
   • Or extract them into a separate fix(types): PR

2. README merge conflict with PR feat(0.4.14): VSCode-kanban feature parity (restore_task, rename_label, undo, column-aware new task, TASKS_DIR) #35

   Both this branch and feat/vscode-features (PR feat(0.4.14): VSCode-kanban feature parity (restore_task, rename_label, undo, column-aware new task, TASKS_DIR) #35) make identical edits to README.md against the same main base. Whichever merges second will produce conflicts. Coordinate with PR feat(0.4.14): VSCode-kanban feature parity (restore_task, rename_label, undo, column-aware new task, TASKS_DIR) #35 — rebase one branch on the other.

3. PR template checklist missing

   The PR has a test plan section but no Type checkboxes and no Checklist confirming that pnpm typecheck / pnpm lint / pnpm test are N/A for docs. PR docs: contributor experience + PR review process #33 modelled the correct docs-only pattern with explicit N/A callouts.

---

Suggestions (optional)

• The &&-chained CLI install command is a nice improvement. The install section could also show a one-liner for Code CLI users who don't have the Desktop app — they currently have to infer this from context.
• Removing the star history chart is the right call; consider opening a tracking issue to re-add it once the project has meaningful history, so it isn't forgotten.

---

This review was generated automatically. A maintainer will follow up.

---

Generated by Claude Code