Skip to content

docs: restructure README so users can judge fit first - #460

Merged
bubbleptr merged 1 commit into
mainfrom
chore/readme-funnel
Oct 11, 2026
Merged

bubbleptr merged 1 commit into
mainfrom
chore/readme-funnel

Conversation

@bubbleptr

@bubbleptr bubbleptr commented Oct 11, 2026 •

Copy link
Copy Markdown
Owner

Summary

Rewrite of the README, following better-readme: user-facing content goes first, and contributor material moves out (moved, not deleted).

  • README / README.zh-CN now run: pitch → highlights → "When Pace is not a fit" (moved before install) → install table → first session → 4 short design principles → Packages page + 3-line roadmap → local data → support → contributing pointer → license. The two languages have the same headings (11 each) and the same 4 badges.
  • Moved to docs/architecture.md (Chinese, matching the rest of docs/): full design principles, mermaid pipeline, layer bullets, prompt flow, the "Where things live" table, extension points, repo layout, stack, storage-compat rule.
  • Moved to CONTRIBUTING.md: test:e2e / test:release, packaging commands, the Validate macOS ARM64 note, /design and UI Intent Picker, and the documentation map.
  • Pointers updated: AGENTS.md now names docs/architecture.md as the code map and CONTRIBUTING.md for the full command list; .cursor/skills/verify-pace points to CONTRIBUTING "Setup".
  • Factual corrections: surface-registry.ts allows only the 4 built-in surface ids and has no provider field, and the extension UI request appears only in pi-sdk-spike.ts, not the gateway. The README no longer says extensions can contribute Dock panels today.
  • Removed duplication: "no Windows/Intel Mac" now appears in the badge and the not-a-fit list, down from 3 places; run-from-source now lives only in CONTRIBUTING.

Test plan

  • No test or CI job reads README/CONTRIBUTING wording (grep)
  • Link/anchor checker over README.md, README.zh-CN.md, CONTRIBUTING.md, docs/architecture.md, AGENTS.md, verify-pace SKILL.md: 89 targets, 0 failures (including CJK anchors)
  • Heading parity en/zh: 11 vs 11, same order and levels
  • README claims checked against code (Packages page features, preflight login recheck, shared ~/.pi/agent, macOS 12 minimum in electron-builder.yml)

Devin Review

…tail

Move architecture, prompt flow and code map to docs/architecture.md and
dev/packaging commands to CONTRIBUTING.md; correct claims that extensions
can already contribute Dock panels. Repoint AGENTS.md and verify-pace.

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

@bubbleptr
bubbleptr merged commit d7fe95c into main Oct 11, 2026
2 checks passed
@bubbleptr
bubbleptr deleted the chore/readme-funnel branch October 11, 2026 08:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant