diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4f0072eb..fe34220d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,14 @@ The latest `## [X.Y.Z]` header must match the `version` field in `punkproject.to
 Entries are newest-first; one bullet per notable change. See the root `AGENTS.md`
 "Project Versioning" section for the bump policy.
 
+## [0.2.3] - 2026-07-06
+
+- shellrun: removed `-tcl` from `sh_run`, `sh_runout`, `sh_runerr`, `sh_runx` (was silently swallowed with no useful effect because `sh -c` is always an external shell; now rejected with a usage message).
+- shellrun: migrated `runx` from the legacy `get_run_opts` parser to `punk::args::parse` with a full PUNKARGS spec; `runx` now honours `-debug` and `--timeout=` (previously accepted but silently ignored).
+- shellrun: expanded PUNKARGS documentation for `run`, `runconsole`, `runout`, `runerr`, and `runx` with `@cmd` metadata and `-help` text on all opts/values.
+- shellrun: migrated `sh_run`, `sh_runout`, `sh_runerr`, `sh_runx` from `get_run_opts` to `punk::args::parse` with dedicated PUNKARGS specs.
+- shellrun: removed the internal `get_run_opts` proc; all callers now use `punk::args`.
+
 ## [0.2.2] - 2026-07-06
 
 - punk::console: terminal queries fired while an 8.6-based shell waits at an idle line-mode prompt now fail fast with a discriminable errorcode (`PUNK CONSOLE QUERY HOSTAGE_COOKED_READ`) and emit nothing, instead of timing out (~500ms) and later corrupting input with the swallowed response (idle-reader hostage guard; raw mode and mid-command queries unaffected). Owner-routed queries preserve the owner-side errorcode.
diff --git a/punkproject.toml b/punkproject.toml
index 8200647f..9e827eb2 100644
--- a/punkproject.toml
+++ b/punkproject.toml
@@ -1,3 +1,3 @@
 [project]
 name = "punkshell"
-version = "0.2.2"
+version = "0.2.3"