[codex] consolidate release documentation (#40)

Author: ThomasK33

.agents/skills/release-maintainer/SKILL.md

@@ -6,7 +6,7 @@ advertise: false
 
 # agent-tty release maintainer SOP
 
-This is a project-local maintainer skill for `agent-tty` releases. The canonical human policy lives in [`docs/RELEASE-PROCESS.md`](../../../docs/RELEASE-PROCESS.md); use this skill as the execution checklist when an agent is asked to cut or publish a release from this repository.
+This is a project-local maintainer skill for `agent-tty` releases. The canonical process lives in [`docs/RELEASE-PROCESS.md`](../../../docs/RELEASE-PROCESS.md); use this skill as an agent wrapper around that document, not as a second copy of the release recipe.
 
 ## When to use this skill
 
@@ -20,189 +20,38 @@ Use this skill when you are asked to:
 
 ## Core guardrails
 
+- Re-read and follow `docs/RELEASE-PROCESS.md` before making release changes.
 - Do **not** release from an unmerged branch. The release tag must reference a commit already merged into `main`.
 - Keep the version bump minimal unless the user explicitly asks for additional release-related changes.
 - Follow the repo's PR body/footer requirements from `AGENTS.md` when creating the release PR.
 - Treat `gh auth status` as advisory only. When access looks suspicious, verify with a real API call instead.
 - Run post-publish verification under Node 24. If the ambient shell is older, point `NODE_BIN` at an explicit Node 24 binary.
 - For `doctor --json`, the health signal is `.result.ok`; the outer `.ok` field only says the CLI command envelope succeeded.
+- If this skill conflicts with `docs/RELEASE-PROCESS.md`, stop and update the skill or ask for direction before continuing.
 
 ## Preflight
 
 1. Re-read `RELEASE.md`, `ROADMAP.md`, and `docs/RELEASE-PROCESS.md`.
 2. Confirm the workspace is clean and based on up-to-date `main`.
-3. Verify GitHub CLI access with a real API call:
+3. Confirm release-note automation prerequisites from `docs/RELEASE-PROCESS.md` are available.
+4. Verify GitHub CLI access with a real API call:
 
 ```bash
 gh api graphql -f query='query { viewer { login } }'
 ```
 
-4. Prefer `mise run ci` when `mise` is available; otherwise use `npm run verify`.
+5. Prefer `mise run ci` when `mise` is available; otherwise use `npm run verify`.
 
-## Prepare the version bump
+## Execution Checklist
 
-Start from fresh `main`:
+- Follow the current version-bump, changelog, PR, merge, tag, publish, and verification steps in `docs/RELEASE-PROCESS.md`.
+- Keep release PR commits narrowly scoped to release metadata, changelog updates, and required lockfile or release-process updates.
+- After opening a release PR, account for the `Release Changelog` workflow possibly pushing a `CHANGELOG.md` commit back to the branch.
+- Use structured `gh run view ... --json status,conclusion,jobs` output for agent-driven CI waiting.
+- After merging the release PR, tag the merged `main` commit only.
+- Verify both npm installation and GitHub Release asset installation before announcing the release.
 
-```bash
-git checkout main
-git pull origin main
-```
-
-Create a release branch and bump without tagging.
-
-Stable patch release example:
-
-```bash
-git switch -c release/0.1.1
-npm version patch --no-git-tag-version
-```
-
-First beta on the next patch line:
-
-```bash
-git switch -c release/0.1.1-beta.0
-npm version prepatch --preid beta --no-git-tag-version
-```
-
-Next beta on the same line:
-
-```bash
-npm version prerelease --preid beta --no-git-tag-version
-```
-
-Then validate and commit the pure version bump:
-
-```bash
-npm run verify
-npm run version:json
-git add package.json package-lock.json
-git commit -m "chore(release): <version>"
-```
-
-## Create the release PR
-
-```bash
-git push -u origin <release-branch>
-gh pr create --base main --head <release-branch> --title "chore(release): <version>"
-```
-
-Before creating the PR, check whether one already exists for the release branch:
-
-```bash
-gh pr list --head <release-branch> --state all
-```
-
-## Wait for CI and merge the PR
-
-Interactive waiting is fine with:
-
-```bash
-gh pr checks <pr-number> --watch
-```
-
-For automation or agent-driven waiting, prefer structured workflow inspection:
-
-```bash
-gh pr checks <pr-number>
-gh run list --branch <release-branch> --event pull_request --limit 5
-gh run view <run-id> --json status,conclusion,jobs
-```
-
-Merge the PR only after the required checks succeed.
-
-Normal merge path:
-
-```bash
-gh pr merge <pr-number> --squash --delete-branch
-```
-
-If branch policy still blocks the merge after checks pass and an authorized releaser is allowed to override it:
-
-```bash
-gh pr merge <pr-number> --squash --admin --delete-branch
-```
-
-If remote refs look stale after the merge, refresh them before checking `origin/main` or deleted release branches:
-
-```bash
-git fetch origin --prune
-```
-
-## Tag and publish the release
-
-Default to the documented tag flow unless the user explicitly asks for the GitHub CLI shortcut.
-
-Documented flow:
-
-```bash
-git checkout main
-git pull origin main
-git tag -a vX.Y.Z -m "vX.Y.Z"
-git push origin vX.Y.Z
-```
-
-If you are explicitly asked to create the tag and GitHub Release with `gh`, use the merged `main` commit SHA:
-
-```bash
-MERGED_SHA=<merge-commit-on-main>
-gh release create vX.Y.Z \
-  --target "$MERGED_SHA" \
-  --title vX.Y.Z \
-  --notes-file <notes-file>
-```
-
-For prereleases, also add:
-
-```bash
---prerelease --latest=false
-```
-
-The release workflow should publish the verified tarball to both GitHub Releases and npm.
-
-## Verify the published npm package
-
-Run the installed CLI under Node 24:
-
-```bash
-PACKAGE_NAME='agent-tty'
-PACKAGE_VERSION='<version>'
-NODE_BIN=${NODE_BIN:-node}
-INSTALL_PREFIX=$(mktemp -d)
-AGENT_TTY_HOME=$(mktemp -d)
-
-npm view "$PACKAGE_NAME" dist-tags --json
-npm install -g --prefix "$INSTALL_PREFIX" "$PACKAGE_NAME@$PACKAGE_VERSION"
-"$NODE_BIN" "$INSTALL_PREFIX/bin/agent-tty" version --json | jq -r '.result.cliVersion'
-"$NODE_BIN" "$INSTALL_PREFIX/bin/agent-tty" --home "$AGENT_TTY_HOME" doctor --json | jq '.result.ok'
-```
-
-For prereleases, also confirm the expected dist-tag points at the exact version.
-
-## Verify the published GitHub Release assets
-
-```bash
-VERSION=<version>
-RELEASE_TAG="v${VERSION}"
-RELEASE_TGZ="agent-tty-${VERSION}.tgz"
-NODE_BIN=${NODE_BIN:-node}
-
-DOWNLOAD_DIR=$(mktemp -d)
-INSTALL_PREFIX=$(mktemp -d)
-AGENT_TTY_HOME=$(mktemp -d)
-
-gh release download "$RELEASE_TAG" --repo coder/agent-tty --dir "$DOWNLOAD_DIR" --pattern "$RELEASE_TGZ"
-gh release download "$RELEASE_TAG" --repo coder/agent-tty --dir "$DOWNLOAD_DIR" --pattern "${RELEASE_TGZ}.sha256"
-(
-  cd "$DOWNLOAD_DIR"
-  sha256sum -c "${RELEASE_TGZ}.sha256"
-)
-
-npm install -g --prefix "$INSTALL_PREFIX" "$DOWNLOAD_DIR/$RELEASE_TGZ"
-"$NODE_BIN" "$INSTALL_PREFIX/bin/agent-tty" version --json | jq -r '.result.cliVersion'
-"$NODE_BIN" "$INSTALL_PREFIX/bin/agent-tty" --home "$AGENT_TTY_HOME" doctor --json | jq '.result.ok'
-```
-
-## Failure recovery checklist
+## Failure Recovery Reminders
 
 - If a release tag was pushed before the PR merged, cancel the workflow run, delete the remote tag, delete the local tag, and redo the release through the PR-first flow.
 - If the GitHub Release exists but assets or npm publish are missing, inspect the `Release` workflow run before attempting any manual repair.

README.md

@@ -110,7 +110,7 @@ agent-tty --home "$AGENT_HOME" destroy "$SESSION_ID" --json
 
 ## Documentation map
 
-- [`RELEASE.md`](./RELEASE.md) — the current `0.1.0` release contract.
+- [`RELEASE.md`](./RELEASE.md) — the supported release contract for the `0.1.x` line.
 - [`ROADMAP.md`](./ROADMAP.md) — intentionally deferred work and post-release direction.
 - [`design/README.md`](./design/README.md) — architecture references plus archived week-by-week planning.
 - [`dogfood/CATALOG.md`](./dogfood/CATALOG.md) — curated proof bundles and recommended review paths.
@@ -124,10 +124,10 @@ agent-tty --home "$AGENT_HOME" destroy "$SESSION_ID" --json
 - Recording export to asciicast (`.cast`) or WebM for artifact bundles.
 - Failure recovery via reconciliation, stale-session cleanup, and retained manifests/artifacts.
 
-## 0.1.0 release focus
+## Release contract
 
-`agent-tty` `0.1.0` is the first release aimed at reliable, isolated, reviewable TUI automation.
-For the explicit shipping contract, see [`RELEASE.md`](./RELEASE.md). For intentionally deferred work, see [`ROADMAP.md`](./ROADMAP.md).
+The `0.1.x` release line is centered on reliable, isolated, reviewable TUI automation.
+For the explicit support contract, see [`RELEASE.md`](./RELEASE.md). For intentionally deferred work, see [`ROADMAP.md`](./ROADMAP.md).
 Reviewer-facing proof bundles are curated in [`dogfood/CATALOG.md`](./dogfood/CATALOG.md), with current release-signoff evidence in `dogfood/20260326-week9-release-readiness/` and evergreen workflow coverage such as `dogfood/run-command/`.
 
 ## TUI Workflow

RELEASE.md

@@ -1,11 +1,12 @@
-# agent-tty 0.1.0 release contract
+# agent-tty release contract
 
-`agent-tty` `0.1.0` is the first release that explicitly targets isolated, reviewable terminal automation for real TUI workflows.
-The contract below is the bar for what maintainers should feel comfortable supporting at release time.
-If a workflow depends on behavior outside this document, treat it as future-scope or best-effort rather than a guaranteed `0.1.0` capability.
-For intentionally deferred work, see [`ROADMAP.md`](./ROADMAP.md). For reviewer-facing proof bundles, start with [`dogfood/CATALOG.md`](./dogfood/CATALOG.md).
+This document defines the supported product contract for the current `0.1.x` release line.
+The original `0.1.0` release established the baseline for isolated, reviewable terminal automation for real TUI workflows; later `0.1.x` releases may add compatible fixes and features without widening this core support contract.
+If a workflow depends on behavior outside this document, treat it as future-scope or best-effort rather than a guaranteed capability.
 
-## What 0.1.0 delivers
+For per-release changes, see [`CHANGELOG.md`](./CHANGELOG.md). For release mechanics, use [`docs/RELEASE-PROCESS.md`](./docs/RELEASE-PROCESS.md). For intentionally deferred work, see [`ROADMAP.md`](./ROADMAP.md). For reviewer-facing proof bundles, start with [`dogfood/CATALOG.md`](./dogfood/CATALOG.md).
+
+## Supported capabilities
 
 - Reliable isolated session lifecycle management: `create`, `inspect`, `destroy`, and `gc` all work against isolated agent-tty homes.
 - Renderer-backed screenshots, semantic snapshots, and WebM export for reviewer-visible proof artifacts.
@@ -14,7 +15,7 @@ For intentionally deferred work, see [`ROADMAP.md`](./ROADMAP.md). For reviewer-
 - An append-only event log that remains the canonical replay/export source of truth.
 - Schema-locked JSON envelopes across the public CLI surface.
 
-## What 0.1.0 explicitly does not deliver
+## Explicitly out of scope
 
 - Native renderer backends such as Ghostty native or kitty.
 - Mouse input support.
@@ -33,6 +34,5 @@ For intentionally deferred work, see [`ROADMAP.md`](./ROADMAP.md). For reviewer-
 
 ## Validation
 
-- Current release bar: 602 tests across 56 test files.
 - Reviewer-facing proof bundles are cataloged in [`dogfood/CATALOG.md`](./dogfood/CATALOG.md), including `dogfood/20260326-week9-release-readiness/`, `dogfood/run-command/`, and `dogfood/20260325-week8-contract-locks/`.
-- Run `npm run verify` for the full validation bar.
+- The maintainer release process in [`docs/RELEASE-PROCESS.md`](./docs/RELEASE-PROCESS.md) defines the current validation bar.

docs/CONTRIBUTING.md

@@ -49,7 +49,7 @@ npm run intent:validate
 
 ## Documentation and proof expectations
 
-- Keep the root docs split clear: `README.md` for overview, `RELEASE.md` for current scope, `ROADMAP.md` for future scope.
+- Keep the root docs split clear: `README.md` for overview, `RELEASE.md` for supported scope, `ROADMAP.md` for future scope.
 - Update [`design/README.md`](../design/README.md) when the active vs archived design split changes.
 - Keep the skill split clear in docs and packaging notes: `skills/` contains the thin public bootstrap, while `skill-data/` contains the canonical runtime skills served by `agent-tty skills get`.
 - Update [`dogfood/CATALOG.md`](../dogfood/CATALOG.md) when you add or promote a reviewer-facing proof bundle.

docs/README.md

@@ -3,10 +3,10 @@
 Use this directory when you need project workflow guidance rather than product-facing documentation.
 
 - [`../README.md`](../README.md) — product overview and quick start.
-- [`../RELEASE.md`](../RELEASE.md) — current shipping contract.
+- [`../RELEASE.md`](../RELEASE.md) — supported product contract.
 - [`../ROADMAP.md`](../ROADMAP.md) — deferred work and post-release direction.
 - [`../design/README.md`](../design/README.md) — architecture and design references.
 - [`CONTRIBUTING.md`](./CONTRIBUTING.md) — setup, validation, and day-to-day contribution flow.
 - [`RELEASE-PROCESS.md`](./RELEASE-PROCESS.md) — maintainer release checklist and proof expectations.
-- [`../.agents/skills/release-maintainer/SKILL.md`](../.agents/skills/release-maintainer/SKILL.md) — internal agent SOP for version bumps, release PRs, tagging, and publish verification.
+- [`../.agents/skills/release-maintainer/SKILL.md`](../.agents/skills/release-maintainer/SKILL.md) — thin internal agent wrapper around the canonical release process.
 - [`../dogfood/CATALOG.md`](../dogfood/CATALOG.md) — curated proof bundles for review.

docs/RELEASE-PROCESS.md

@@ -1,6 +1,6 @@
 # Release process
 
-`RELEASE.md` defines the shipping contract. This document describes how maintainers should validate, version, tag, and publish that contract on GitHub Releases and npm.
+[`../RELEASE.md`](../RELEASE.md) defines the supported product contract. This document is the canonical maintainer process for validating, versioning, tagging, and publishing that contract on GitHub Releases and npm.
 
 ## One-time npm trusted publishing setup
 
@@ -146,7 +146,14 @@ Versions containing a hyphen, such as `-beta.0` or `-rc.0`, are published by the
 
 ### Open the release PR
 
-Release branches named `release/*` are watched by the `Release Changelog` workflow. When `package.json` changes the package version and `CHANGELOG.md` does not already contain that version, the workflow runs:
+Release branches named `release/*` are watched by the `Release Changelog` workflow. The default path is to commit only the version bump, then let that workflow add `CHANGELOG.md` if needed:
+
+```bash
+git add package.json package-lock.json
+git commit -m "chore(release): <version>"
+```
+
+When `package.json` changes the package version and `CHANGELOG.md` does not already contain that version, the workflow runs:
 
 ```bash
 communique generate "v<version>" --changelog --repo coder/agent-tty
@@ -157,7 +164,7 @@ When it pushes that bot commit, it dispatches the CI and skill-validation
 workflows for the updated release branch so protected-branch checks can run
 against the new head commit.
 
-If you want to inspect or update the changelog before opening the PR, run the same command locally after `npm version ... --no-git-tag-version` and include `CHANGELOG.md` in the release commit:
+If you want to inspect or update the changelog before opening the PR, run the same command locally after `npm version ... --no-git-tag-version` and include `CHANGELOG.md` in the release commit instead:
 
 ```bash
 VERSION=$(node --input-type=module -e "import pkg from './package.json' with { type: 'json' }; process.stdout.write(pkg.version)")
@@ -166,7 +173,7 @@ git add package.json package-lock.json CHANGELOG.md
 git commit -m "chore(release): ${VERSION}"
 ```
 
-After the version bump is committed:
+After committing either the default version bump or the local changelog variant:
 
 ```bash
 git push -u origin <release-branch>