docs: simplify README setup and usage

[michael-denyer]

Summary

The README leads with port history and implementation details before showing readers how to use pstack. Reorganize it around a quick start, concrete skill examples, runtime-specific installation, and dependencies. Link to existing contributor and audit documents for deeper detail.

Preserve the generator's slash-command table, skill counts, upstream pin, and documented runtime limitations. Only README.md changes.

Validation

• bun tools/generate.mjs passed without generated changes.
• TMPDIR=/private/tmp bun test tests/: 165 passed, 0 failed. The initial run hit 11 worktree-test failures caused by macOS /var versus /private/var temporary-path differences; using the canonical temporary path resolved them.
• npx --yes markdownlint-cli2@0.18.1 README.md: no errors.
• lychee --offline --include-fragments README.md: 16 links checked, no errors.
• git diff --check passed.

[coldtea-pr-lens]

◈ PR Lens

🟢 +0 new · 🟠 ~1 changed · 🔴 -0 removed · 0 flows · 1 file · commit 2009183

Architecture

1 component touched across 4 lanes.

Open the interactive canvas

Data flow

No data-flow sequence changed in this PR.

View

• Architecture lens
• Data flow lens
• Expand every detail

Tip

Push a commit and the comment redraws for the new head. A slow older run never overwrites a newer one.

🪧 More tips

• Run npx skills add coldteadotai/pr-lens, then tell your coding agent: "Diagram the change you just made with PR Lens and attach it to the pull request."
• Run npx @coldtea/pr-lens-cli analyze --base origin/main on a branch, then npx @coldtea/pr-lens-cli render .pr-lens/graph.json. Same lenses, your own model key, before the pull request exists.
• Untick Architecture lens or Data flow lens under View to hide a diagram, or tick Expand every detail to open every section. The comment redraws in a few seconds.
• Click the link under each diagram to open it on a canvas you can zoom, pan and step through.
• The diagrams are links. Click one to open it on the canvas, then press W or click play to walk through the change.
• Open a diagram on the canvas, then press W or click play to walk through the change one step at a time.
• The CLI's render reads .github/pr-lens.yml and applies your renames, exclusions and lane pins at draw time.
• Set github.comment.collapsed: true in .github/pr-lens.yml to fold the comment behind one View architecture and data flow row. Drawing still runs on every push.
• Add .github/workflows/pr-lens.yml with coldteadotai/pr-lens/packages/action@v0 and your model provider's key as its api-key to run PR Lens from your own CI. Any /chat/completions endpoint works.
• Switch GitHub to dark mode and the diagrams follow. The moving dots are this pull request's data in motion.

---

Thanks for using PR Lens! It's built by Coldtea, free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn