docs: make release notes user-facing

.agents/skills/labkit-documentation-maintainer/SKILL.md

@@ -70,6 +70,18 @@ scope, behavior, documentation/boundary decisions, delivery state, and data
 hygiene. Never place sensitive lab data or local absolute paths in an Issue or
 PR.
 
+## Release notes
+
+Treat a GitHub Release as a user interface for deciding whether and how to
+upgrade. Preserve historical facts, breaking changes, safety warnings, and
+required migration actions, but express them through user-visible workflows
+and supported contracts. Do not turn the note into a delivery log: omit commit
+and run identifiers, shell commands, test inventories, CI routing, internal
+package moves, hashes, byte counts, and asset-verification procedure. Summarize
+validation only at the level useful to a user, such as supported MATLAB and OS
+coverage or completed interactive checks. Keep exact evidence in the PR,
+workflow record, structured component history, and release verification.
+
 ## Workflow
 
 1. Change authored sources or renderer code. After moving or retiring

.github/RELEASE_NOTES_TEMPLATE.md

@@ -0,0 +1,19 @@
+<!-- Rewrite every section for the actual release and remove all comments. -->
+<!-- Describe user-visible workflows, compatibility, and required actions. -->
+<!-- Keep delivery logs and maintainer evidence out of the public note. -->
+
+## Highlights
+
+<!-- What can a user now do, or what meaningfully improved? -->
+
+## Fixes
+
+<!-- Which user-visible problems were corrected? Omit if none. -->
+
+## Upgrade Note
+
+<!-- State compatibility and any action users or custom App authors must take. -->
+
+## Validation
+
+<!-- Summarize supported MATLAB/OS coverage and relevant interactive checks. -->

.github/workflows/release.yml

@@ -120,7 +120,7 @@ jobs:
             --repo "$GITHUB_REPOSITORY" \
             --verify-tag \
             --title "V${RELEASE_TAG#v}" \
-            --generate-notes \
+            --notes-file .github/RELEASE_NOTES_TEMPLATE.md \
             --draft
           local_digest="sha256:$(cut -d' ' -f1 \
             "artifacts/release/${RELEASE_TAG}/asset.sha256")"
@@ -141,5 +141,5 @@ jobs:
             echo "::error::Remote launcher byte count does not match the tag blob."
             exit 1
           fi
-          echo "Review and complete the release notes, asset, and validation evidence before publishing the draft." \
+          echo "Rewrite the release notes for users, then review the asset and validation evidence before publishing the draft." \
             >> "$GITHUB_STEP_SUMMARY"

AGENTS.md

@@ -314,6 +314,12 @@ explicit compliant squash subject; do not rely on GitHub defaults.
 - New release tags are `vX.Y.Z`; do not rename published legacy tags. Release
   titles contain only `VX.Y.Z` with an uppercase `V` and relevant `Highlights`,
   `Fixes`, `Upgrade Note`, and `Validation` sections.
+- Treat release notes as a user-facing product summary, not a release audit.
+  Describe observable behavior, affected workflows, compatibility, and actions
+  a user may need to take. Do not publish commit or run identifiers, commands,
+  test inventories, CI architecture, internal package movement, hashes, byte
+  counts, or maintainer-only evidence; keep those in the PR, workflow record,
+  structured history, or release asset verification.
 - Start the manual `Release` workflow only after developer-led interactive App
   validation, successful required PR validation, and a successful lightweight
   `Continuous Integration` main-push run for the exact squash commit. It then

docs/development/maintain-and-release/release.md

@@ -105,7 +105,23 @@ Use this note structure:
 ```
 
 Omit an empty section when it does not apply. Keep validation factual: name the
-commands or CI workflow that passed and the commit used for the release.
+supported MATLAB and operating-system coverage, relevant interactive checks,
+or other assurance a user can interpret.
+
+Release notes are a user-facing product summary, not a release audit or a
+shortened PR description. Each statement should help a reader understand what
+changed in a supported workflow, whether an issue they experienced was fixed,
+whether existing work remains compatible, or what action an upgrade requires.
+Use App and workflow names that users recognize. Preserve safety warnings and
+breaking-change guidance even when they affect only custom App authors.
+
+Do not publish commit or workflow-run identifiers, pull-request links, shell
+commands, test inventories, CI routing, internal package movement, file hashes,
+byte counts, or asset-verification procedure in release notes. Those details
+remain available in the PR review record, structured component history,
+workflow record, and release asset checks. The
+`.github/RELEASE_NOTES_TEMPLATE.md` draft prompts the required reader-facing
+sections and must be rewritten for the actual release before publication.
 
 After it verifies the required CI run, the workflow exports
 `labkit_launcher.m` from the annotated tag blob, verifies its SHA-256 against
@@ -116,8 +132,8 @@ by that Base MATLAB CI run; a later advance of `main` does not move it.
 Automation deliberately stops at a draft. Before publishing, rewrite or
 complete the generated notes with the required sections above, confirm the
 version and tag target, inspect the launcher asset, and record the final manual
-and CI evidence. Publishing the draft is a developer release decision, not a
-side effect of ordinary CI.
+and CI evidence outside the public note. Publishing the draft is a developer
+release decision, not a side effect of ordinary CI.
 
 Attach `labkit_launcher.m` to each GitHub release. The root README download
 link points at the latest release asset so browsers download the launcher

docs/history/records/2026/08/LK-20260806-reader-facing-release-notes.md

@@ -0,0 +1,60 @@
+# Release notes describe the product for users
+
+```labkit-change
+id: LK-20260806-reader-facing-release-notes
+date: 2026-08-06
+sequence: 177
+type: docs
+compatibility: compatible
+scope: Release communication
+scope: GitHub Release history
+```
+
+## Context
+
+Release notes had gradually accumulated delivery evidence and implementation
+detail that belonged in pull requests, workflow records, and asset checks. That
+made it harder for readers to understand what a release changed for them.
+
+## Decision and rationale
+
+Treat every GitHub Release as a user-facing product summary. Notes describe
+recognizable workflows, corrected behavior, compatibility, safety warnings,
+and required upgrade actions. Maintainer evidence remains available at its
+own source instead of competing with the release summary.
+
+## Changes
+
+- Historical Release notes were rewritten around user-visible outcomes.
+- The release manual and agent guidance now exclude delivery logs and internal
+  implementation evidence from public notes.
+- New draft Releases start from a reader-facing section template instead of an
+  automatically generated commit list.
+
+## User and data impact
+
+Users can compare releases without interpreting repository or CI details. No
+App behavior, scientific data, projects, results, or public API changed.
+
+## Compatibility and migration
+
+Published tags, release titles, dates, assets, and version identities remain
+unchanged. Existing downloads require no action.
+
+## Validation
+
+All published Release bodies were reviewed for the required reader-facing
+structure and scanned for maintainer-only delivery evidence. Repository tests
+cover the draft template and release workflow contract.
+
+## Evidence
+
+- Every published Release retains its original tag and title.
+- The online notes contain no commit hashes, workflow-run links, commands, or
+  asset digests.
+- Focused release and documentation checks are required before integration.
+
+## Known limitations and follow-up
+
+Historical notes remain summaries of their original releases; they do not
+retroactively add behavior that was not delivered at the time.

tests/specs/tests/labkittest/TestCatalogSpec.m

@@ -587,6 +587,8 @@ function releaseAssetIntegrityUsesDigestAndByteCount(testCase)
             root = labkittest.setup();
             workflow = string(fileread(fullfile( ...
                 root, ".github", "workflows", "release.yml")));
+            notes = string(fileread(fullfile( ...
+                root, ".github", "RELEASE_NOTES_TEMPLATE.md")));
 
             testCase.verifySubstring(workflow, ...
                 "Remote launcher digest does not match the tag blob.");
@@ -600,8 +602,14 @@ function releaseAssetIntegrityUsesDigestAndByteCount(testCase)
                 "gh release verify-asset"));
             testCase.verifySubstring(workflow, ...
                 '--title "V${RELEASE_TAG#v}"');
+            testCase.verifySubstring(workflow, ...
+                "--notes-file .github/RELEASE_NOTES_TEMPLATE.md");
+            testCase.verifyFalse(contains(workflow, "--generate-notes"));
             testCase.verifyFalse(contains(workflow, ...
                 '--title "LabKit MATLAB Workbench'));
+            testCase.verifySubstring(notes, "## Highlights");
+            testCase.verifySubstring(notes, "## Upgrade Note");
+            testCase.verifySubstring(notes, "## Validation");
         end
 
         function explainChangedReportsClassificationAndExactEvidence(testCase)