Skip to content

Open the README with benefits, real notices and badges - #22

Merged
HugoLopes45 merged 2 commits into
mainfrom
docs/readme-polish
Nov 11, 2026
Merged

HugoLopes45 merged 2 commits into
mainfrom
docs/readme-polish

Conversation

@HugoLopes45

@HugoLopes45 HugoLopes45 commented Nov 11, 2026 •

Copy link
Copy Markdown
Owner

Why

The README is the landing page on GitHub and npm. Visitors had to read a glossary before they saw what the extension does and why it matters.

Changes

  • First screen: real badges (npm version, CI, Node.js engine, license), the tagline "Long Pi sessions that stay sharp.", one sentence with the search terms, the install command.
  • New "Why pi-context-kit" section: six benefits. Each one restates behavior that the reference sections document.
  • New "What the model sees" section: a diff with the exact notice strings from src/stale.ts:6, src/prune.ts:51 and src/shake.ts:106. Sizes and IDs are marked as illustrative.
  • Headings carry the search terms: "Why long Pi sessions need context management", "How it works during a session", "FAQ".
  • The glossary moves into a <details> block. The three-item list under "The problem" is removed, because the benefits replace it.
  • The reference sections (settings, recipes, limits) do not change.

Verification

  • Head fa1f7e2: npm run check passed (102 tests). Documentation only.
  • The four badge URLs return HTTP 200 with real values: npm v0.3.1, node >=22.19.0, license MIT, CI passing.
  • No link in README.md, CONTRIBUTING.md or SECURITY.md points to the renamed anchors (rg returned nothing).
  • Independent fact-check (hl-verify, reviewer subagent): 23 of 30 claims supported, 5 corrected, 2 unverified. All five corrections are applied in fa1f7e2: recall covers the current branch, notices apply above the threshold, a ready note must still fit, compaction still summarizes older messages, and /compact falls back to Pi's summary. The token ratio now cites Pi's 4-characters estimate. The diagram no longer shows read replacement before the threshold check, an older error that the check found. Still unverified: the Anthropic reasoning exception, which comes from the existing README and repo comments.
  • Not checked: how npm renders <details>. npm shows the new text only after the next publication.

Risk and rollback

Low: documentation only. Rollback: revert the squash commit. Owner: HugoLopes45.

Visitors had to read a glossary before they saw what the extension does. The first screen now shows the promise, the install command, the benefits, and the exact notices that replace old content, under headings that use the search terms.
@HugoLopes45 HugoLopes45 self-assigned this Nov 11, 2026
A fact-check found five overpromises in the new top section and a diagram that showed read replacement at every turn, although it happens only above the threshold.
@HugoLopes45
HugoLopes45 marked this pull request as ready for review November 11, 2026 21:51
@HugoLopes45
HugoLopes45 merged commit 6193870 into main Nov 11, 2026
6 checks passed
@HugoLopes45
HugoLopes45 deleted the docs/readme-polish branch November 11, 2026 21:53
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