Prepare CmdForge 0.2.0 for PyPI

RELEASING.md

@@ -0,0 +1,64 @@
+# Publishing CmdForge to PyPI
+
+PyPI releases are public and immutable. A release version must never be reused
+for different bytes, even if an upload contains a mistake.
+
+## One-time account setup
+
+1. Create or sign in to an account at <https://pypi.org/>.
+2. Verify the account email address.
+3. Enable two-factor authentication and store the recovery codes in the
+   password manager and an offline recovery location.
+4. For the first upload only, create an account-scoped API token. PyPI cannot
+   create a project-scoped token until the project exists.
+5. Do not put a PyPI token in Git, `.pypirc`, chat, command arguments, or shell
+   history. Let Twine prompt for it interactively.
+
+After the first successful upload, immediately revoke the account-scoped token
+and create a new token restricted to the `cmdforge` project.
+
+## Prepare and validate a release
+
+Update the version in both `pyproject.toml` and `src/cmdforge/__init__.py`, then
+add the release to `CHANGELOG.md`. From a clean checkout:
+
+```bash
+python -m pip install -e '.[release]'
+pytest tests/ -m "not integration"
+python -m build
+python -m twine check dist/*
+```
+
+Inspect the wheel and source archive, then install the wheel into a clean
+temporary virtual environment and exercise both entry points. Do not upload an
+artifact that was built before the release commit.
+
+## Upload
+
+Run Twine interactively so the token is not recorded in shell history:
+
+```bash
+python -m twine upload dist/*
+```
+
+When prompted, use `__token__` as the username and paste the API token as the
+password. Once uploaded, verify the public project and install from PyPI in a
+new environment:
+
+```bash
+python -m venv /tmp/cmdforge-pypi-check
+/tmp/cmdforge-pypi-check/bin/pip install 'cmdforge[mcp,pty]'
+/tmp/cmdforge-pypi-check/bin/cmdforge --version
+/tmp/cmdforge-pypi-check/bin/cmdforge --help
+```
+
+Tag and push only the commit whose artifacts were published:
+
+```bash
+git tag -a v0.2.0 -m "CmdForge 0.2.0"
+git push origin main
+git push origin v0.2.0
+```
+
+If an upload is wrong, fix it, increment the version, rebuild, and publish a
+new release. Never delete and reuse the version number.