Skip to content

docs: rewrite the README for a reader deciding whether to use the package - #23

Merged
ryanleecode merged 2 commits into
mainfrom
docs/readme-skill
Nov 11, 2026
Merged

ryanleecode merged 2 commits into
mainfrom
docs/readme-skill

Conversation

@systemfsoftware-maker

Copy link
Copy Markdown
Contributor

Replaces #21, which was closed. This branch starts from a fresh worktree off origin/main, and the three files below were staged by name; the staged diff held no .sfs-deps/, .deps/ or *.tgz path.

Files

  • README.md: rewritten.
  • docs/front-ends.md: new. The front-end detail moved verbatim from the old README (one link made relative to docs/).
  • CONTRIBUTING.md: new. The development setup, the profile reproduction steps and the provenance paragraph moved from the old README.

How it was written (write-readme-md)

Shape: library, in a flagship monorepo, so the root is the product README with a short map of the private apps. References opened: readme-library.md, readme-monorepo.md, structure.md, readme-root-design.md, readme-templates.md.

The README leads with a real verdict. I wrote two versions of a small package (a function whose E channel gains a Timeout), ran FrontEnd.readPackage, FrontEnd.analyse and Verdict.cell.run in this repository's workspace, and pasted the output verbatim (major, E_WIDENED and EXPORT_ADDED, corpus 1.1.0). The scratch script and fixtures were deleted afterwards.

Other claims checked against the repo: Node >=24 and the effect ^4.1.2 peer (packages/api-extractor/package.json); 61 rules over 33 change kinds and the four E-channel rules (corpus.v1.json); the flake exposes api-extractor and workspace-tarballs; no workflow here pushes to the registry, so the Install section says Nix builds this package from source; v0.1.0 is the latest GitHub Release and its changelog names the front-ends. Install goes through the flake and the pnpm-release-management route, never npm.

Scripts

  • score_readme.ts: 6/13 (sections, contributing, relative links, tables pass; prose density 4.48 words per line and the emoji, details and blockquote criteria do not).
  • triage_readme.ts: one tier-3 finding, that the two badge images are not theme-aware. Rendered through GitHub's markdown API in Chromium in light and dark, both badges load (66x20 and 78x20) and the h1 and positioning sentence sit above 130px. A first run also flagged a flat heading hierarchy (tier 2); subsections were added and it cleared.
  • check_mechanisms.ts: one finding, Example, which is a false positive. The script judges design references, and it matched must inside the verdict's own next_action text, quoted verbatim from real output.

…kage

The README now leads with a real verdict (two package versions in, canonical JSON out), then install through the flake, the verdict, the status and a user FAQ. The front-end detail moves to docs/front-ends.md, and the development setup, profile reproduction and provenance move to CONTRIBUTING.md. Claims were checked against the source, the manifests and a run of the example.
@ryanleecode
ryanleecode merged commit 03d4370 into main Nov 11, 2026
1 of 2 checks passed
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.

2 participants