docs: README landing-page refresh + bump-control documentation #108

New issue

Closed

opened 2026-06-26 14:16:40 +02:00 by quartermaster · 0 comments

quartermaster commented

2026-06-26 14:16:40 +02:00

Owner

Why now

The current README is stale + the bump-control mechanism is under-documented. Both surface gaps a consumer would hit on first encounter.

Stale state in current README

## Status
**v0.1.0 shipped** 2026-06-24. **v0.2.0 imminent** — runs-on parameterization
+ defensive fragment newline normalization; tracker: #3.

We're cutting v0.7.0 (PR #105 open as I write this). The §10 arc-convergence happened. ADR-0006 (c) settled. The README's status section is many releases behind.

Bump-control documentation gap

The README mentions cc-commits + fragments as "two CHANGELOG sources, composable" but says nothing about:

bump_override workflow_dispatch input — the explicit one-off override mechanism (currently undocumented in README; lives only in workflow file comments)
Future label-based bump — separately tracked, but the README structure should anticipate the addition
How bump signals compose — when multiple sources disagree, which wins? Currently no doc explains this

Scope (sketch — Herald is welcome to reshape)

Refresh "Status" section — current state (v0.6.2 just shipped; §10 arc-convergence reached; ADR-0006 (c) settled; pre-v1.0 readiness sweep underway)
Refresh "What it provides" section — preserve the (cc + fragments) story; add the bump-control narrative; cross-reference to ADRs
Add a "Bump signals" section — narrative explanation of the four sources: cc-subject, fragment frontmatter, bump_override, future label. Composition rule (highest-bump wins).
Refresh "Status" or "Roadmap" subsection — point at the pre-v1.0 readiness sweep tracker + named-pattern progression
Cross-reference architecture — link to AGENTS.md §10 (convergence milestone), ADR-0006 (RNA decision), ADR-0004 (push-trigger).
Tone calibration — Herald's narrative-eye on whether the README reads cleanly for a consumer who's never seen the toolkit before. The §10 narrative is dense + load-bearing-internally; the README should be readable + outwards-facing.

What this issue does NOT cover

Does NOT define the label-based bump mechanism — that's its own tracker
Does NOT do the pre-v1.0 surface audit — that's its own tracker
Does NOT change the _release.yml or release.yml files — README is documentation only

Delegation note

Per operator 2026-06-26: this work is delegated to Herald — narrative-chamber's domain, expected to need iterations. Herald has standing approval to engage; she'll route review through her usual cadence + bus-ping me at PR-open and merge-ready.

Refs

Operator framing 2026-06-26: "we should eventually either document it on the README.md landing page, or at least point the reader to the documentation"
Sibling trackers: pre-v1.0 readiness sweep, label-based bump-control
Current README state: out-of-date (claims v0.1.0/v0.2.0); cut is v0.7.0
Architecture cross-refs: AGENTS.md §10, ADR-0006 (c), ADR-0004
Herald's β-refined naming pattern (banked 2026-06-26): "name the NATURE, not the action" — applies broadly to README copy

## Why now The current README is stale + the bump-control mechanism is under-documented. Both surface gaps a consumer would hit on first encounter. ## Stale state in current README ``` ## Status **v0.1.0 shipped** 2026-06-24. **v0.2.0 imminent** — runs-on parameterization + defensive fragment newline normalization; tracker: #3. ``` We're cutting **v0.7.0** ([PR #105](../pulls/105) open as I write this). The §10 arc-convergence happened. ADR-0006 (c) settled. The README's status section is many releases behind. ## Bump-control documentation gap The README mentions cc-commits + fragments as "two CHANGELOG sources, composable" but says nothing about: - **`bump_override` workflow_dispatch input** — the explicit one-off override mechanism (currently undocumented in README; lives only in workflow file comments) - **Future label-based bump** — separately tracked, but the README structure should anticipate the addition - **How bump signals compose** — when multiple sources disagree, which wins? Currently no doc explains this ## Scope (sketch — Herald is welcome to reshape) 1. **Refresh "Status" section** — current state (v0.6.2 just shipped; §10 arc-convergence reached; ADR-0006 (c) settled; pre-v1.0 readiness sweep underway) 2. **Refresh "What it provides" section** — preserve the (cc + fragments) story; add the bump-control narrative; cross-reference to ADRs 3. **Add a "Bump signals" section** — narrative explanation of the four sources: cc-subject, fragment frontmatter, `bump_override`, future label. Composition rule (highest-bump wins). 4. **Refresh "Status" or "Roadmap" subsection** — point at the pre-v1.0 readiness sweep tracker + named-pattern progression 5. **Cross-reference architecture** — link to AGENTS.md §10 (convergence milestone), ADR-0006 (RNA decision), ADR-0004 (push-trigger). 6. **Tone calibration** — Herald's narrative-eye on whether the README reads cleanly for a consumer who's never seen the toolkit before. The §10 narrative is dense + load-bearing-internally; the README should be readable + outwards-facing. ## What this issue does NOT cover - Does NOT define the label-based bump mechanism — that's its own tracker - Does NOT do the pre-v1.0 surface audit — that's its own tracker - Does NOT change the `_release.yml` or `release.yml` files — README is documentation only ## Delegation note Per operator 2026-06-26: this work is delegated to Herald — narrative-chamber's domain, expected to need iterations. Herald has standing approval to engage; she'll route review through her usual cadence + bus-ping me at PR-open and merge-ready. ## Refs - **Operator framing 2026-06-26**: "we should eventually either document it on the README.md landing page, or at least point the reader to the documentation" - **Sibling trackers**: pre-v1.0 readiness sweep, label-based bump-control - **Current README state**: out-of-date (claims v0.1.0/v0.2.0); cut is v0.7.0 - **Architecture cross-refs**: AGENTS.md §10, ADR-0006 (c), ADR-0004 - **Herald's β-refined naming pattern** (banked 2026-06-26): "name the NATURE, not the action" — applies broadly to README copy