---
name: release-notes-ux-only
description: Operator rules — release notes are succinct + UX-only (no code/env/incident specifics), no manual word-wrap, and use spt nomenclature (Psyche, never invented synonyms). Codified in RELEASE-RUNBOOK step 2; apply BEFORE publishing.
metadata: 
  node_type: memory
  type: feedback
  originSessionId: 5d2a1340-b3c4-46cb-8023-27f92b11fa90
---

Operator correction (2026-07-02, after the v0.10.4 release): my release notes were a wall of text carrying source paths, env vars, state-file layouts, endpoint/machine names, and the debugging story.

**Why:** Release notes are read by end users who never saw the source or the incident. Forensics live in docs/SPT-CORE-FINDINGS.md and commit messages; duplicating them in notes buries the one thing a user needs — what changes for them.

**How to apply:** When cutting a release, write each CHANGELOG entry as a few sentences of before/after user experience + the recovery step if one exists. No REQ ids, hazard codes, paths, env vars, hook names, node names, or narrative. The rule is codified in `docs/RELEASE-RUNBOOK.md` step 2 — reread it at every cut; the changelog section becomes the release body verbatim. v0.10.4 was amended post-publish via `gh release edit`; future releases must ship compliant. Related: [[f023-f024-crossnode-delivery]], [[v0120-checkpoint-race-project-names]].

**Use spt nomenclature (operator rule, 2026-07-03, after v0.12.1):** product terms — Psyche, live agent, perch, endpoint, node, subnet — ARE the user-facing language; never substitute an invented softer synonym ("companion" for Psyche was the miss). "No internal lingo" bans IMPLEMENTATION vocabulary (paths, env vars, module names), not the product's own names. Codified in RELEASE-RUNBOOK step 2; v0.12.1 body amended post-publish via `gh release edit`.

**No manual word-wrap (operator rule, 2026-07-03):** do NOT hardcode newlines to wrap a bullet/blockquote across physical lines — GitHub word-wraps the body itself, so a hand-wrap becomes a forced break in the rendered notes. Write each bullet/blockquote/paragraph as ONE physical line; only structural newlines belong (blank lines between subsections, `###` headers, `-` bullet boundaries). Codified in RELEASE-RUNBOOK step 2 ("No manual word-wrap" bullet). Fix an existing file: `python ci/publish/unwrap-changelog.py CHANGELOG.md` then re-push each body `gh release edit v<X> --notes-file <section-body>` (body = section verbatim minus its `## [<ver>]` header). Applied 2026-07-03: unwrapped ALL 21 CHANGELOG sections + re-pushed all 21 GitHub release bodies; operator also edited v0.12.0 language (Fixed title "Checkpoint waits until after the session clear to send the wake message"; dropped "Nothing you do changes").