release: prepare v0.2.0

.github/workflows/ci.yml

@@ -16,6 +16,12 @@ jobs:
       - uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
+      - name: Install runtime dependencies
+        run: |
+          python -m pip install -r launcher/requirements.txt
+          python -m pip check
+      - name: Import runtime
+        run: python -c "import launcher.wake_launcher"
       - name: Compile Python
         run: python -m compileall -q launcher scripts
       - name: Run state and configuration tests

.gitignore

@@ -9,6 +9,11 @@
 __pycache__/
 *.pyc
 
+# Model weights and downloaded archives must never enter source or Releases.
+models/
+*.onnx
+*.tar.bz2
+
 # User-specific local configuration.
 config.json
 .DS_Store

CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## [0.2.0] - 2026-07-25
+
+First public release of Wake for Codex.
+
+### Included
+
+- Local Chinese and English keyword spotting on Windows and macOS.
+- Microphone release before the user-configured Codex Voice Chat hotkey.
+- Voice-session lifecycle observation and automatic listener re-arm.
+- Optional, merge-safe Codex `SessionStart` Hook.
+- Read-only diagnostics, strict configuration validation, bounded JSON logs,
+  and single-instance protection.
+- Source-only distribution under Apache-2.0. Model weights remain upstream-only
+  and are downloaded with a pinned SHA-256 check.
+
+### Release hardening
+
+- CI installs and imports the exact runtime dependencies on Windows and macOS
+  with Python 3.11 and 3.12.
+- The dependency set uses a NumPy version compatible with both supported Python
+  versions.
+- `doctor` uses the effective repository configuration, validates the KWS
+  runtime and microphone stream format, and rejects a stale Hook path.
+- Unknown configuration fields fail with their full path.
+- Background startup failures are written to the structured event log.

README.md

@@ -36,19 +36,19 @@ missing hands-free entry point:
 
 ## Status
 
-The target release is `v0.2.0-alpha.1`.
+The current release is `v0.2.0`. See [CHANGELOG.md](CHANGELOG.md).
 
 | Platform | Status | Verified scope |
 |---|---|---|
-| Windows 10/11 | alpha | Local KWS, hotkey handoff, Codex microphone lifecycle, re-arm, singleton, diagnostics, optional Hook |
-| macOS | alpha | Local KWS, CGEvent hotkey handoff, CoreAudio lifecycle, re-arm, diagnostics, optional cooldown |
+| Windows 10/11 | v0.2.0 | Local KWS, hotkey handoff, Codex microphone lifecycle, re-arm, singleton, diagnostics, optional Hook |
+| macOS | v0.2.0 | Local KWS, CGEvent hotkey handoff, CoreAudio lifecycle, re-arm, diagnostics, optional cooldown |
 
 The legacy TypeWhisper Voice Bridge is not part of this project.
 
 ## Requirements
 
 - Codex desktop with a Voice Chat shortcut configured in **Settings → Voice**;
-- Python 3.11 or newer;
+- Python 3.11 or 3.12 (the versions exercised by CI);
 - PowerShell 7 on Windows;
 - Microphone permission;
 - Accessibility permission on macOS for the process that starts the launcher.
@@ -61,30 +61,44 @@ Codex.
 ### Windows
 
 ```powershell
-git clone https://github.com/playing/wake-for-codex.git
+git clone --branch v0.2.0 https://github.com/playing/wake-for-codex.git
 Set-Location .\wake-for-codex
 pwsh -NoProfile -File .\scripts\install-windows.ps1 -DownloadModel
-Copy-Item .\config.example.json .\config.json
 pwsh -NoProfile -File .\run-wake-launcher.ps1 -Check
 pwsh -NoProfile -File .\run-wake-launcher.ps1
 ```
 
 ### macOS
 
 ```sh
-git clone https://github.com/playing/wake-for-codex.git
+git clone --branch v0.2.0 https://github.com/playing/wake-for-codex.git
 cd wake-for-codex
 /bin/sh ./scripts/install-macos.sh --download-model
-cp ./config.example.json ./config.json
 /bin/sh ./run-wake-launcher.sh --check
 /bin/sh ./run-wake-launcher.sh
 ```
 
+The defaults work without `config.json`. Copy `config.example.json` only when
+you want to customize the hotkey, microphone, sensitivity, lifecycle, or paths.
+
 Before the first macOS run, allow the terminal or launcher process under
 **System Settings → Privacy & Security → Microphone** and
 **Accessibility**. The read-only doctor reports missing Accessibility
 permission but never changes it.
 
+## Upgrade
+
+Stop the background launcher, fetch the desired release tag, rerun the platform
+installer, and start it again:
+
+```text
+git fetch --tags
+git checkout v0.2.0
+```
+
+The installer reuses an existing verified model directory. Reinstall the
+optional Hook only if the repository path changed.
+
 ## Default wake phrases
 
 - `Hey Codex`
@@ -151,6 +165,10 @@ Read-only environment check:
 ./.venv-kws/bin/python -m launcher.doctor
 ```
 
+`doctor` automatically uses the repository's `config.json` when present and
+reports the effective file, runtime imports, exact microphone stream format,
+platform lifecycle signal, and optional Hook path.
+
 Detect one wake phrase without sending the hotkey:
 
 ```powershell
@@ -258,6 +276,7 @@ unclear; review [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) before use.
 ## Development
 
 ```powershell
+.\.venv-kws\Scripts\python.exe -m pip install -r launcher\requirements.txt
 .\.venv-kws\Scripts\python.exe -m compileall -q launcher scripts
 .\.venv-kws\Scripts\python.exe -m launcher.self_test
 .\.venv-kws\Scripts\python.exe -m launcher.sync_phrase_manifest

README.zh-CN.md

@@ -34,19 +34,19 @@ Codex 已经负责完整的实时语音对话，本项目只补充缺少的免
 
 ## 当前状态
 
-目标版本为 `v0.2.0-alpha.1`。
+当前版本为 `v0.2.0`，变更记录见 [CHANGELOG.md](CHANGELOG.md)。
 
 | 平台 | 状态 | 已验证范围 |
 |---|---|---|
-| Windows 10/11 | alpha | 本地 KWS、热键交接、Codex 麦克风生命周期、恢复监听、单实例、诊断、可选 Hook |
-| macOS | alpha | 本地 KWS、CGEvent 热键交接、CoreAudio 生命周期、恢复监听、诊断、可选 cooldown |
+| Windows 10/11 | v0.2.0 | 本地 KWS、热键交接、Codex 麦克风生命周期、恢复监听、单实例、诊断、可选 Hook |
+| macOS | v0.2.0 | 本地 KWS、CGEvent 热键交接、CoreAudio 生命周期、恢复监听、诊断、可选 cooldown |
 
 旧 TypeWhisper Voice Bridge 不属于本项目。
 
 ## 环境要求
 
 - Codex 桌面端，并在 **Settings → Voice** 中配置 Voice Chat 热键；
-- Python 3.11 或更高版本；
+- Python 3.11 或 3.12（CI 实际覆盖的版本）；
 - Windows 需要 PowerShell 7；
 - 麦克风权限；
 - macOS 需要为启动 Launcher 的进程授予辅助功能权限。
@@ -58,29 +58,42 @@ Wake for Codex 中配置的热键必须与 Codex Voice Chat 热键一致。
 ### Windows
 
 ```powershell
-git clone https://github.com/playing/wake-for-codex.git
+git clone --branch v0.2.0 https://github.com/playing/wake-for-codex.git
 Set-Location .\wake-for-codex
 pwsh -NoProfile -File .\scripts\install-windows.ps1 -DownloadModel
-Copy-Item .\config.example.json .\config.json
 pwsh -NoProfile -File .\run-wake-launcher.ps1 -Check
 pwsh -NoProfile -File .\run-wake-launcher.ps1
 ```
 
 ### macOS
 
 ```sh
-git clone https://github.com/playing/wake-for-codex.git
+git clone --branch v0.2.0 https://github.com/playing/wake-for-codex.git
 cd wake-for-codex
 /bin/sh ./scripts/install-macos.sh --download-model
-cp ./config.example.json ./config.json
 /bin/sh ./run-wake-launcher.sh --check
 /bin/sh ./run-wake-launcher.sh
 ```
 
+默认配置无需 `config.json` 即可运行。只有需要修改热键、麦克风、灵敏度、生命周期或
+路径时，才复制 `config.example.json`。
+
 macOS 首次运行前，请在
 **系统设置 → 隐私与安全性 → 麦克风/辅助功能** 中允许启动脚本所使用的终端或
 Launcher 进程。只读 `doctor` 会报告缺失的辅助功能授权，但不会替你修改系统权限。
 
+## 升级
+
+先停止后台 Launcher，获取并切换到目标 Release tag，重新运行对应平台安装器，再次
+启动：
+
+```text
+git fetch --tags
+git checkout v0.2.0
+```
+
+安装器会复用已有模型目录。只有仓库路径变化时，才需要重新安装可选 Hook。
+
 ## 默认唤醒词
 
 - `Hey Codex`
@@ -144,6 +157,9 @@ sherpa-onnx 使用声学关键词检测，修改后必须重新编译：
 ./.venv-kws/bin/python -m launcher.doctor
 ```
 
+存在 `config.json` 时，`doctor` 会自动使用它，并报告实际配置文件、runtime import、
+精确麦克风流格式、平台生命周期信号和可选 Hook 路径。
+
 只检测一次唤醒词，不发送热键：
 
 ```powershell
@@ -244,6 +260,7 @@ sherpa-onnx 上游下载 KWS 模型并校验固定 SHA-256。上游尚未明确
 ## 开发验证
 
 ```powershell
+.\.venv-kws\Scripts\python.exe -m pip install -r launcher\requirements.txt
 .\.venv-kws\Scripts\python.exe -m compileall -q launcher scripts
 .\.venv-kws\Scripts\python.exe -m launcher.self_test
 .\.venv-kws\Scripts\python.exe -m launcher.sync_phrase_manifest

docs/configuration.md

@@ -6,6 +6,10 @@ Wake for Codex works without a configuration file. To customize it, copy
 `config.example.json` to the repository root as `config.json`. The local file is
 ignored by Git.
 
+Unknown fields are rejected with their full configuration path instead of being
+silently ignored. `doctor` automatically uses the repository's `config.json`
+when it is present.
+
 ## Precedence
 
 Values are resolved in this order:

docs/configuration.zh-CN.md

@@ -6,6 +6,9 @@ Wake for Codex 不需要配置文件也能运行。需要自定义时，将
 `config.example.json` 复制到仓库根目录并命名为 `config.json`。该本地文件已被
 Git 忽略。
 
+未知字段会报告完整配置路径并终止，不会被静默忽略。仓库中存在 `config.json` 时，
+`doctor` 会自动使用它。
+
 ## 优先级
 
 配置按以下顺序覆盖：