Skip to content

Lead the README with what the tool is, and fix the stale attribution text - #21

Merged
braden-seaborn merged 1 commit into
mainfrom
docs/fix-attribution-paragraph
Aug 26, 2026
Merged

braden-seaborn merged 1 commit into
mainfrom
docs/fix-attribution-paragraph

Conversation

@braden-seaborn

Copy link
Copy Markdown
Contributor

Release-night PR. Three things, all of which should land before the v0.1.0 tag.

1. Rewrite the top of the README

The old opening was a wall of prose. A reader had to work to find out what the tool was, and there was no route to the two non-CLI ways of running it — they were buried in a <details> block two thirds of the way down.

The new top has:

  • a centred title block, tagline and badge row (added a dependencies: none badge, since that is the tool's main selling point)
  • a Mermaid diagram of the pipeline and the six tests — GitHub renders it natively, no image asset to host
  • a worked example, three sentences that trip all six tests
  • a three-column table for the three entry points: CLI, Claude/agent skill, HELVE JSON-RPC tool, each with its install snippet and a wiki link

That last one is the point of the exercise: whichever way a reader arrived, their entry point is above the fold.

The example output is real

I originally hand-aligned the console block into neat columns. That was wrong — it made the tool's output look tidier than it is. It is now verbatim, with only the indented source-snippet line under each finding removed, and the prose says exactly that.

The Mermaid block deliberately avoids <b> tags and other markup that some renderers drop. A broken diagram at the top of the front page on launch night is worse than a plain one.

2. Fix the stale attribution paragraph — closes #20

#13 and #15 were written in parallel and merged in that order. #13's description of the attribution situation was accurate when written; #15 then changed the situation, leaving this on main:

The T2 vague-term, T3 hedge, and T6 filler and AI-tell tables record no source at all, per entry or per table.

The "per table" half is false — #15 added a sources block to all four files. The paragraph now says what is true: per-entry sources are still T1-only, the other tables carry provenance at table level, and --explain surfaces neither yet, linking #10 where that is tracked.

Also drops the "where the repository root carries one" hedge on THIRD-PARTY-LICENSES.md. It is unconditionally present now and ships in the wheel.

3. Release prep

  • CHANGELOG: [Unreleased] becomes [0.1.0] - 2026-08-25, with a fresh empty [Unreleased] above it. Added entries for the work that landed after that block was written — the attribution files, contributor docs, the wrapping regression suite, and the hard-wrap atomicity fix from Build sentence units from paragraphs, not from physical lines #12.
  • release.yml: the environment URL pointed at pypi.org/p/ste100. The package is ste100-linter. Cosmetic (it only affects the link on the deployment) but wrong.

Verification

  • All eight suites pass locally.
  • python ste_lint.py README.md exits 0 with zero error-tier findings. The rewrite introduced two error-tier findings (requirement → need, and an It is opener); both are fixed rather than tolerated.
  • Confirmed ste100-helve --helve-rpc actually starts and speaks JSON-RPC before documenting it, and matched the skill install snippet to the canonical steps on the wiki's Agent Skill page.

Not in this PR

README.md still carries the "The package is not on PyPI yet" note under Install. That is accurate until the publish actually succeeds. It should be removed in a follow-up once v0.1.0 is live on PyPI — see the release checklist I posted separately.

Closes #20

…text

Three changes, all needed before the first tagged release.

Rewrite the top of the README. It opened with a wall of prose that made a
reader work to find out what the tool does and offered no route to the two
non-CLI ways of running it. It now leads with a centred title block and
tagline, a Mermaid diagram of the six tests, a worked example, and a
three-column table covering the CLI, the Claude/agent skill and the HELVE
JSON-RPC tool -- so whichever way a reader arrived, their entry point is
above the fold.

The worked example is real output. Only the indented source-snippet line
under each finding is removed, and the text says so rather than quietly
reformatting the tool's output to look tidier than it is.

Fix the attribution paragraph (closes #20). #13 described the attribution
situation accurately when it was written; #15 then merged and changed it,
leaving the README claiming the T2/T3/T6 tables "record no source at all,
per entry or per table". They now carry a table-level `sources` block. The
paragraph now states what is true: per-entry sources remain T1-only, the
other tables carry provenance per table, and `--explain` surfaces neither
yet -- linking #10, where that gap is tracked. Also drops the "where the
repository root carries one" hedge on THIRD-PARTY-LICENSES.md, which is
unconditionally present now.

Add the 0.1.0 CHANGELOG section, covering the work that landed after the
Unreleased block was written: the attribution files, the contributor docs,
the wrapping regression suite, and the hard-wrap atomicity fix.

Point the release workflow's environment URL at pypi.org/p/ste100-linter.
The package is named ste100-linter in pyproject.toml; the URL said ste100,
which is a different (also unclaimed) name. Cosmetic -- it only affects the
link shown on the deployment -- but wrong.

Verified: all eight suites pass, and `ste_lint.py README.md` now exits 0
with zero error-tier findings. Two findings this rewrite introduced were
fixed rather than tolerated.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@braden-seaborn
braden-seaborn merged commit 5d91c1f into main Aug 26, 2026
12 checks passed
@braden-seaborn
braden-seaborn deleted the docs/fix-attribution-paragraph branch August 26, 2026 03:58
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.

README's attribution paragraph went stale when #15 merged after #13

1 participant