[sabind]

Why

The repository and its plugin were documented for the people who build them, not for someone arriving to decide whether to use it. In the author's words when this work started: "look at https://github.com/freethinkingit/inline-email notice the readme, the guides, the style... we have some work to do". The work follows the spec in .freethinking/specs/newcomer-docs/.

What

A newcomer landing on the repository now gets the author's pitch, the install, a real session image, a "when to use it" comparison with plain Claude Code and Kiro, and links to task-shaped guides, a reference page and an evidence page. The plugin README becomes a short page that stands on its own in the plugin listing, and the version rises to 0.17.0 so installed copies receive it.

Changes

• Front door. README.md rewritten: pitch, Docs line, install, hero capture, what it does with a hand-off diagram, when to use it, how it is tested, what it does not do, develop the plugin, license. The old layout list, "Add or change a skill or rule" and "Testing" moved into .github/CONTRIBUTING.md. Why: the author's request quoted above.
• Listing page and its companions. plugins/freethinking/README.md cut to the pitch, install, one line per skill, agent and rule, "What the plugin runs and sends" and absolute links; llms.txt added at the root; both manifest descriptions set to the pitch's first sentence; plugin.json at 0.17.0. Reason not provided by the author.
• Reference. docs/reference.md holds the per-skill, per-agent, per-rule and per-hook detail that left the listing page, with a table of contents. Reason not provided by the author.
• Guides. docs/guides/build-a-feature.md, fix-a-bug.md and make-a-small-change.md, each built from real session captures, with sequence diagrams for the multi-agent jobs. Reason not provided by the author.
• Evidence. docs/evidence.md shows the four rule targets run with and without the plugin on 2026-10-22, says which comparisons are fair, and lists what is not measured; evals/README.md's passage on how Skill graders are scored under --ablation with-without corrected to match the run data. Why, in the author's words: "we can use our evals right? with deltas?"
• Session captures. docs/captures/render.py (standard library) extracts a range of a Claude Code transcript and renders it as a terminal SVG; checks/test_capture_render.py tests determinism and that the text survives; 14 capture sources under docs/captures/, with their generated SVGs under docs/images/. Reason not provided by the author.
• Bugfix read-back eval case. evals/skills/bugfix/reads-back-without-ticket/ checks that bugfix states Symptom, Expected and Context back before running anything, from a session where it did not. Why, in the author's words: "add an eval case".
• Spec. .freethinking/specs/newcomer-docs/ requirements, design and tasks. Reason not provided by the author.

Testing

Recorded in the session that built this branch; the author has not yet walked the changes.

• make validate: 31 tests OK, and all three claude plugin validate --strict runs passed.
• The four rule targets with --ablation with-without, 2026-10-22, plugin 0.17.0 from this branch: tables in docs/evidence.md. Mean Δ: collaboration +0.44, code-changes +0.27, workflow +0.48 (mostly skill existence, as the page explains), communication 0.00.
• The new bugfix case, make eval-skill-bugfix EVAL_ARGS="--case reads-back-without-ticket --keep-temp", 2026-10-22:

CASE                       SCORE PASS% RUNS COST    NOTES
reads-back-without-ticket  1.00  100%  3    $0.80   

The kept traces held no copy of the skill's text, so the graders matched Claude's own read-back.

Risk and rollout

• Draft: two guides (docs/guides/plan-a-year.md, docs/guides/tune-a-template.md) are not written yet, so their links from the README, the listing page and llms.txt do not resolve. They wait on two sessions the author runs.
• The listing page and plugin.json's description ship with the plugin at 0.17.0; the listing page links absolute blob/main URLs, which resolve only after merge.
• No skill, agent, rule or hook changes behaviour.

Notes for reviewers

• This is a draft to keep the work and its context on GitHub. The author will run the pr walkthrough before marking it ready; the bullets marked "Reason not provided by the author" get the author's reasons then.
• Still to come under the spec: the plan-a-year and tune-a-template captures and guides, the integrity check (checks/test_docs.py) and its tests, and the GitHub description and topics, set on the author's yes.