Yoetz v0.2.2 — install paths that work on any machine

Yoetz 0.2.2 is a patch release in the 0.2 public-alpha line. It removes the ways a
fresh install could fail or mislead: the website's PyPI button named a version that did not
exist, npx yoetz bound agent connections to a cache that uv may prune, the prompt-loop
first run could crash, and setup asked people to type a Codex home path by hand. It also ships
typed recovery directives on public errors (#743) and the product-wording pass (#773) that merged
after 0.2.1. Nothing about the ledger, checks, receipts, or the wire schemas changes; this release
is about getting to first run and past the first error (#766).

Python and npm packages both use 0.2.2. The public protocol namespace remains 0.1;
package releases and immutable wire-schema versions advance independently.

Highlights

• Any machine, any Pythons. The documented command,
  uv tool install --managed-python --python 3.14.6 yoetz, downloads the exact Python 3.14 it
  needs and is unaffected by pyenv, Homebrew, system, or project Pythons. The docs now say so,
  name the two uv settings that block the download, and say that pip or pipx on an older
  Python cannot install Yoetz (#766, #768).
• npx yoetz connections survive uv cache clean. The npm launcher makes the exact version a
  persistent uv tool install first (a no-op once present) and then runs that installed
  environment, so hooks and MCP entries bind a launcher that stays where it is. The launcher
  still bundles and downloads nothing itself (#766, #768).
• The website's install buttons work. The PyPI button is unpinned, so it can never name a
  release PyPI lacks again; both popups say uv is required and give its one-line installer
  (#766, #770).
• Setup asks less. The Codex home is offered from CODEX_HOME or ~/.codex for confirmation,
  yoetz setup run --codex-path works without --codex-home, the prompt-loop first run opens the
  wizard instead of exiting internal_error, each Codex installation is listed once, and a
  console script that cannot prove itself reports launcher_unproven (#766, #768).
• Errors say what to do next. A public error on the MCP or CLI surface carries a typed
  continuation token, and each surface renders the directive, guidance pointer, and nudge from a
  checked-in registry, so a flow such as vault_initialization_required no longer dead-ends an
  agent. Directive text never travels on the wire, so the egress fence is unchanged
  (ADR-030;
  #739, #740, #669, #743).
• One vocabulary. Receipts, the terminal interface, CLI and MCP descriptions, guidance, skills,
  and docs all say "local checks" and "AI-powered review"; the
  product vocabulary table
  maps those words to the unchanged wire identifiers (#769, #773).

What this release does not claim

• First run still connects Codex only. Claude Code and Cursor are connected afterwards with
  yoetz integrate claude ... and yoetz integrate cursor ...; detecting and connecting them
  during first run is tracked as #767.
• yoetz 0.0.1 on PyPI is a name reservation. Until it is yanked, pip or pipx on a
  Python older than 3.14 can still resolve it and install nothing usable (#771).
• Everything listed under "What this release does not claim" in
  v0.2.1
  still applies: real WSL 2 is untested, Linux Claude Code and Cursor native-host acceptance is
  incomplete, and privacy-receipt CLI bugs #731 and #732 remain open. See
  docs/public-claims.json
  and
  docs/OPEN_QUESTIONS.md.

Install

uv tool install --managed-python --python 3.14.6 "yoetz==0.2.2"

For a one-off run: uvx --python 3.14 "yoetz==0.2.2". With uv already installed:
npx yoetz@0.2.2 (the npm package is a dependency-free launcher that makes the same persistent
uv tool install of the exact PyPI distribution).

Release integrity

Verify the artifacts against the attached SHA256SUMS, NPM_SHA256SUMS, SBOM, support matrix,
known limitations, release-evidence bundle, and VERIFY.md.

Full changelog

Curated notes above; the complete list of merged changes since v0.2.1:

• #743: typed recovery directives on MCP
  and CLI error surfaces (ADR-030).
• #768: make the documented install paths
  work and stop asking for typed paths.
• #770: unpin the landing page's PyPI
  install command and say what uv does.
• #772: prepare the 0.2.2 release.
• #773: say "local checks" and
  "AI-powered review" everywhere people read.
• Product Hunt featured badge on the website's hero (direct commit).

Compare: v0.2.1...v0.2.2