1.9.4

Install

Drop the attached .zip at your repo root without extracting it — the agent unpacks it as the first step. Then type this shortcut phrase as a chat message to your AI agent (Claude Code, Cursor, Codex, Junie, GitHub Copilot, Windsurf, Air, or Warp):

Install Wavefoundry

That is the only operator-typed command — the agent runs the rest of the install. Prerequisites: Python 3.11+, an MCP-aware agent host. Full walkthrough and host-specific notes in the README.

Upgrade

Already running Wavefoundry? Drop the attached .zip at your repo root without extracting it and type this shortcut phrase to your agent:

Upgrade Wavefoundry

The agent unpacks the zip, advances the framework, runs any required migrations and index rebuilds, and reloads the MCP server. Review the version notes below for anything that re-indexes or changes behavior on this upgrade.

---

Added

• New wf subcommands for agent-run framework scripts. wf codebase-map, wf render-surfaces, and wf secrets-scan join the cross-OS wf dispatcher so operators and agents stop guessing raw python3 .wavefoundry/framework/scripts/*.py invocations. Framework upgrade cleanup stays a manual python3 .wavefoundry/framework/scripts/prune_framework.py step — it needs the pre-upgrade MANIFEST that only the operator running the upgrade holds.
• Upgrade-time retired-surface reconciliation. A minor-or-major wf upgrade now scans the repository for stale references to retired framework surfaces (such as the per-command .wavefoundry/bin/* wrappers replaced by the cross-OS wf dispatcher) and reports an actionable file:line → suggested wf form list in place of generic recommend-only prose. The scan is report-only and exclusion-aware (it skips the framework pack, the generated index, historical records, and tests) and matches both forward-slash and backslash path references. Reconciliation guidance also names host permission/allow-rule files (for example .claude/settings.local.json) as a surface to flag for the operator rather than self-edit, and clarifies the gate-before-reload window during upgrade.
• Structured wave_upgrade summary. wave_upgrade now returns a parsed summary block (from/to version, files pruned, docs-gate result, index-update state, failed phase, and the reconciliation findings) plus a top-level next_step and next_tools, so agents read computed fields instead of scraping the raw output. The existing output and exit_code are unchanged and parsing is fail-safe.

Changed

• Committed MCP configs standardize on python3. Every generated host MCP config launches the server with command: "python3" and the repo-relative server.py, byte-identical across macOS, Linux, and native Windows. wf setup verifies python3 resolves to Python 3.11+ and, when it does not, fails closed with platform-aware guidance (install via Scoop/Microsoft Store on Windows, or your package manager / a symlink on macOS/Linux) plus the no-PATH per-machine fallback config. Setup does not modify your Python installation or PATH.

Fixed

• MCP helper subprocesses no longer contend with the host's JSON-RPC stdio. Server-side helper processes (docs-lint, gardener, sync-surfaces, upgrade phases, sensors) now run with stdin detached and intentional stdout/stderr handling — fixing wave_validate/docs-lint-over-MCP timeouts seen on some hosts — and suppress their console window on native Windows.
• Setup fails loudly instead of silently shipping a dead MCP config. When wf setup finds python3 does not resolve to Python 3.11+ on PATH, it reports the exact problem and exits non-zero with platform-aware guidance (make python3 resolve — Scoop/Microsoft Store on Windows, your package manager or a symlink on macOS/Linux — or use the per-machine absolute-venv-path fallback) rather than reporting success for a command: "python3" config the host cannot launch. Setup does not modify your Python installation or PATH.