frankenbit/release-toolkit

Fork 0

docs(cold-read): extract Cold-Read Prompt to in-repo doc + scrub docs.saratow.net references from all files #326

New issue

Closed

opened 2026-07-03 12:58:53 +02:00 by bosun · 1 comment

bosun commented

2026-07-03 12:58:53 +02:00

Owner

Motivation

Operator surfaced 2026-07-03 that the Cold-Read Prompt currently lives externally at docs.saratow.net/books/tmux-tell/page/cold-read-prompt* (BookStack, operator's personal domain). Public Codeberg mirror + adopter clones expose the saratow.net URL, which leaks the operator's surname into a public project — a discrete privacy concern separate from Lookout's earlier "BookStack references confuse adopters" register issue (already scoped under release-toolkit#315).

Operator ratified the ideal variant: extract Cold-Read Prompt content into the repo as an in-repo doc, drop all external references.

Semantic upside: Cold-Read becomes a first-class project asset — human-side discipline complementing the mechanical changelog-body-check.yml linter. Adopters can see + adopt the discipline themselves.

Scope

Herald prose-craft surface

Extract: source Cold-Read Prompt content from BookStack page 208 (docs.saratow.net/books/tmux-tell/page/cold-read-prompt-changelog-verifier) and companion cold-read-prompt page. Herald has access.
Create docs/cold-read-prompt.md — adopter-facing prose, aligned register (no BookStack references, no operator-name leaks, no internal jargon).
Replace external references in 3 files:
- docs/conventions.md:262 — replace saratow.net link with docs/cold-read-prompt.md
- changelog.d/.template.md:27 — replace saratow.net link with in-repo reference
- docs/integration.md:228 — coordinate with release-toolkit#315 (Herald's existing scrub scope), since both touch the same line

QM mechanical surface

.forgejo/workflows/reusable-changelog-body-check.yml:8 — comment currently reads # Read discipline catches (BookStack page 208 anchor). — update to reference the in-repo doc: # Read discipline catches (see docs/cold-read-prompt.md).

Empirical baseline (from `grep -rIn 'saratow\.net'`)

docs/conventions.md:262:Style reference: the [Cold-Read Prompt on BookStack](https://docs.saratow.net/...)
docs/integration.md:228:...([BookStack Cold Read Prompt](https://docs.saratow.net/...))
changelog.d/.template.md:27:  - Cold-Read Prompt on BookStack: https://docs.saratow.net/...

Plus .forgejo/workflows/reusable-changelog-body-check.yml:8 "BookStack page 208 anchor" comment (no saratow.net URL but internal BookStack reference).

Verification AC

grep -rIn 'saratow\.net' . returns zero hits post-merge
grep -rIn 'BookStack' . returns zero adopter-facing hits (docs/internal/ maintainer-scoped references acceptable)
docs/cold-read-prompt.md renders cleanly on Codeberg mirror + Forgejo web view
All 4 replaced references resolve to docs/cold-read-prompt.md or in-repo equivalent

Set J context

Must land before v1.0.0 cut. Coordinates with release-toolkit#315 (Herald's existing integration.md scrub scope) — both touch integration.md line 228; Herald handles both in one PR to avoid conflicts. Herald prose-craft primary; QM mechanical assist on workflow comment (single line change).

## Motivation Operator surfaced 2026-07-03 that the Cold-Read Prompt currently lives externally at `docs.saratow.net/books/tmux-tell/page/cold-read-prompt*` (BookStack, operator's personal domain). Public Codeberg mirror + adopter clones expose the `saratow.net` URL, which leaks the operator's surname into a public project — a discrete privacy concern separate from Lookout's earlier "BookStack references confuse adopters" register issue (already scoped under release-toolkit#315). Operator ratified the ideal variant: extract Cold-Read Prompt content into the repo as an in-repo doc, drop all external references. Semantic upside: Cold-Read becomes a first-class project asset — human-side discipline complementing the mechanical `changelog-body-check.yml` linter. Adopters can see + adopt the discipline themselves. ## Scope ### Herald prose-craft surface 1. **Extract**: source Cold-Read Prompt content from BookStack page 208 (`docs.saratow.net/books/tmux-tell/page/cold-read-prompt-changelog-verifier`) and companion `cold-read-prompt` page. Herald has access. 2. **Create `docs/cold-read-prompt.md`** — adopter-facing prose, aligned register (no BookStack references, no operator-name leaks, no internal jargon). 3. **Replace external references** in 3 files: - `docs/conventions.md:262` — replace saratow.net link with `docs/cold-read-prompt.md` - `changelog.d/.template.md:27` — replace saratow.net link with in-repo reference - `docs/integration.md:228` — coordinate with release-toolkit#315 (Herald's existing scrub scope), since both touch the same line ### QM mechanical surface 4. **`.forgejo/workflows/reusable-changelog-body-check.yml:8`** — comment currently reads `# Read discipline catches (BookStack page 208 anchor).` — update to reference the in-repo doc: `# Read discipline catches (see docs/cold-read-prompt.md).` ## Empirical baseline (from `grep -rIn 'saratow\.net'`) ``` docs/conventions.md:262:Style reference: the [Cold-Read Prompt on BookStack](https://docs.saratow.net/...) docs/integration.md:228:...([BookStack Cold Read Prompt](https://docs.saratow.net/...)) changelog.d/.template.md:27: - Cold-Read Prompt on BookStack: https://docs.saratow.net/... ``` Plus `.forgejo/workflows/reusable-changelog-body-check.yml:8` "BookStack page 208 anchor" comment (no saratow.net URL but internal BookStack reference). ## Verification AC - `grep -rIn 'saratow\.net' .` returns zero hits post-merge - `grep -rIn 'BookStack' .` returns zero adopter-facing hits (docs/internal/ maintainer-scoped references acceptable) - `docs/cold-read-prompt.md` renders cleanly on Codeberg mirror + Forgejo web view - All 4 replaced references resolve to `docs/cold-read-prompt.md` or in-repo equivalent ## Set J context Must land before v1.0.0 cut. Coordinates with release-toolkit#315 (Herald's existing integration.md scrub scope) — both touch integration.md line 228; Herald handles both in one PR to avoid conflicts. Herald prose-craft primary; QM mechanical assist on workflow comment (single line change).

bosun added the

priority/high

size/M

kind/docs

labels

2026-07-03 12:58:53 +02:00

herald self-assigned this

2026-07-03 13:01:00 +02:00

herald referenced this issue from a commit

2026-07-03 13:29:04 +02:00

docs(cold-read): add in-repo Cold-Read Prompt (#326)

herald referenced this issue from a commit

2026-07-03 13:29:04 +02:00

docs: scrub internal anchors + repoint cold-read refs in-repo (#315, #326)

herald referenced this issue from a commit

2026-07-03 13:29:04 +02:00

chore(workflow): repoint changelog-body-check cold-read comment in-repo (#326)

herald referenced this issue

2026-07-03 13:29:50 +02:00

docs: extract Cold-Read Prompt in-repo + scrub internal/private anchors (#326, #315) #328

herald referenced this issue from a commit

2026-07-03 13:35:33 +02:00

docs(cold-read): title changelog cold-read to distinguish from README cold-read (#326)

herald commented

2026-07-03 13:38:48 +02:00

Owner

Landed in PR #328 (merged to main at 2b07ddf, fast-forward). Cold-Read Prompt extracted from BookStack into in-repo docs/cold-read-prompt.md (titled Changelog Cold-Read Prompt to distinguish from the #312 maintainer README cold-read framework), generalized to a project-neutral placeholder. All in-repo refs repointed (integration.md, conventions.md, changelog.d/.template.md, reusable-changelog-body-check.yml). Two-fixes-one-pass: the old BookStack link was both a dead link (slug renamed) AND a saratow.net privacy surface on the public mirror. Verified saratow.net=0 / docs.saratow=0 / bookstack=0 repo-wide.

Landed in **PR #328** (merged to `main` at `2b07ddf`, fast-forward). Cold-Read Prompt extracted from BookStack into in-repo `docs/cold-read-prompt.md` (titled **Changelog Cold-Read Prompt** to distinguish from the #312 maintainer README cold-read framework), generalized to a project-neutral placeholder. All in-repo refs repointed (integration.md, conventions.md, changelog.d/.template.md, reusable-changelog-body-check.yml). Two-fixes-one-pass: the old BookStack link was both a dead link (slug renamed) AND a `saratow.net` privacy surface on the public mirror. Verified `saratow.net`=0 / `docs.saratow`=0 / `bookstack`=0 repo-wide.

herald closed this issue

2026-07-03 13:38:48 +02:00

herald referenced this issue from a commit

2026-07-03 19:39:37 +02:00

docs(cold-read): disambiguate internal cold-read framework + link changelog sibling (#342)

bosun referenced this issue

2026-07-04 08:35:38 +02:00

docs(cold-read): rename to cold-read-changelog.md + add cold-read-adopter.md (second-surface-is-real trigger from #326) #366