Improve release notes workflow

.github/release-notes/TEMPLATE.md

@@ -0,0 +1,26 @@
+<!-- release-notes-template
+Remove this comment when preparing a release.
+
+Start with one to three short paragraphs that explain:
+- the problem or goal behind the release;
+- the headline change;
+- what the release means for users.
+
+Do not lead with commit or pull-request titles. Link to them only when they add useful supporting detail.
+-->
+
+## Highlights
+
+- **Change** — Explain what changed, why it changed, and how users benefit.
+
+<!-- Add focused sections for other meaningful areas of the release. -->
+
+## Installation or upgrade
+
+Explain how to install or upgrade and call out any required user action.
+
+## Compatibility
+
+Document breaking changes, migrations, known limitations, or remove this section when none apply.
+
+**Full Changelog**: https://github.com/nleononline/codex-context-window/compare/PREVIOUS_TAG...RELEASE_TAG

.github/release-notes/v0.1.0.md

@@ -0,0 +1,41 @@
+Codex cannot normally see how much of its context window remains. In long conversations, compaction can arrive without warning and reduce important constraints, intermediate findings, or unfinished work before the model has a chance to preserve them.
+
+Codex Context Window v0.1.0 closes that blind spot. It gives the model compact, model-visible signals about its current context usage and lifecycle, so it can take approaching compaction into account while working.
+
+## Context awareness
+
+- **Live usage after prompts and tools** — `UserPromptSubmit` and `PostToolUse` report used tokens, the model context-window limit, and the percentage currently occupied.
+- **Lifecycle signals** — the model is told when its session starts, its context has just been compacted or cleared, and a subagent session begins.
+- **Debug mode** — setting `CODEX_CONTEXT_WINDOW_DEBUG=1` adds the originating hook to each signal and writes handler errors to `stderr`.
+- **Safe fallback behavior** — missing, ambiguous, or unreadable session data produces no model-visible output instead of injecting misleading information.
+
+A typical signal looks like this:
+
+```text
+<meta>YOUR CONTEXT WINDOW: 193800 / 258400 (75%)</meta>
+```
+
+## Lightweight and local
+
+The hook handler is a short-lived Rust process that reads Codex session files locally and makes no network requests. It scans the active transcript backwards in 64 KiB blocks and stops as soon as it finds the newest token-count event.
+
+In a 500-run reference benchmark on Apple Silicon macOS with a 7.8 MB transcript, a complete usage-hook invocation took 9.2 ms median and 12.3 ms p95, including launcher and process startup.
+
+Prebuilt, self-contained binaries are included for macOS, Linux, and Windows on Arm64 and x86-64. The launcher selects the correct binary automatically, so no additional runtime or dependencies are required after installation.
+
+## Installation
+
+Install the marketplace and plugin from a terminal:
+
+```bash
+codex plugin marketplace add nleononline/codex-context-window --ref marketplace
+codex plugin add codex-context-window@codex-context-window
+```
+
+In Codex Desktop, open the installed plugin and select **Trust all** in its hooks list. Then open a new chat or restart Codex so the hooks are loaded.
+
+## Compatibility
+
+The plugin reads Codex session files whose internal structure may change between Codex versions. If the expected token data is unavailable, the hook exits successfully without adding anything to the model context.
+
+**Full Changelog**: https://github.com/nleononline/codex-context-window/commits/v0.1.0

.github/workflows/release.yml

@@ -8,6 +8,32 @@ permissions:
   contents: read
 
 jobs:
+  release-notes:
+    name: Validate release notes
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - name: Validate versioned release notes
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          manifest_version="$(
+            python3 -c \
+              'import json; print(json.load(open(".codex-plugin/plugin.json"))["version"])'
+          )"
+          release_notes_file=".github/release-notes/v${manifest_version}.md"
+
+          if [[ ! -s "${release_notes_file}" ]]; then
+            echo "release notes file ${release_notes_file} is missing or empty" >&2
+            exit 1
+          fi
+
+          if grep -q "release-notes-template" "${release_notes_file}"; then
+            echo "release notes file ${release_notes_file} still contains the template marker" >&2
+            exit 1
+          fi
+
   build:
     name: Build ${{ matrix.target }}
     runs-on: ${{ matrix.os }}
@@ -74,7 +100,9 @@ jobs:
   publish:
     name: Publish marketplace
     if: github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/master'
-    needs: build
+    needs:
+      - build
+      - release-notes
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -91,11 +119,13 @@ jobs:
               'import json; print(json.load(open(".codex-plugin/plugin.json"))["version"])'
           )"
           release_tag="v${manifest_version}"
+          release_notes_file=".github/release-notes/${release_tag}.md"
           if git ls-remote --exit-code --tags origin "refs/tags/${release_tag}" >/dev/null 2>&1; then
             echo "tag ${release_tag} already exists" >&2
             exit 1
           fi
           echo "RELEASE_TAG=${release_tag}" >> "$GITHUB_ENV"
+          echo "RELEASE_NOTES_FILE=${release_notes_file}" >> "$GITHUB_ENV"
       - name: Stage marketplace
         shell: bash
         run: |
@@ -166,4 +196,4 @@ jobs:
         run: >-
           gh release create "${RELEASE_TAG}"
           --target "${GITHUB_SHA}"
-          --generate-notes
+          --notes-file "${RELEASE_NOTES_FILE}"

CONTRIBUTING.md

@@ -16,7 +16,10 @@ The local release binary is accepted by the launcher, so hooks can be tested dir
 ## Releasing
 
 1. Update the version in `Cargo.toml` and `.codex-plugin/plugin.json`.
-2. Run the local checks.
-3. Create and push a matching tag such as `v0.1.0`.
+2. Copy `.github/release-notes/TEMPLATE.md` to `.github/release-notes/vX.Y.Z.md`, remove the template marker and guidance, and write the user-facing release notes.
+3. Explain the problem, the meaningful changes, and their impact. Pull requests and commits may be linked as supporting detail, but should not be the release summary.
+4. Run the local checks and open a pull request.
+5. Merge only after the release build matrix and release-notes validation pass.
+6. Run the `Release` workflow manually from `master`.
 
-The release workflow builds all supported targets, publishes the complete plugin marketplace to the generated `marketplace` branch, and creates a GitHub release with release notes. Do not edit the `marketplace` branch manually.
+The release workflow builds all supported targets, publishes the complete plugin marketplace to the generated `marketplace` branch, creates the version tag, and uses the matching versioned file as the GitHub release description. Do not create the tag or edit the `marketplace` branch manually.