fix(docs): repair provider docs cleanup wave2 slice

CHANGELOG.md

@@ -31,11 +31,11 @@ Known evidence gaps:
   `npm view @hasna/codewith versions` currently starts at `0.1.2`.
 - `0.1.27`, `0.1.28`, and `0.1.46` live on release branches, not
   `origin/main`; `0.1.46` was cut from `fix/loops-runtime-0.1.46`.
-- `origin/main` remains at Codewith `0.1.45` until the `0.1.46` hotfix branch
-  is merged, cherry-picked, or superseded by a later release.
+- `origin/main` now carries the `rust-v0.1.66` release tag. Earlier notes about
+  `origin/main` lagging at `0.1.45` were superseded by later release trains.
 - The `rust-v0.1.46` GitHub Release is metadata-only and is not marked latest;
-  use `rust-v0.1.45` for the latest asset-bearing platform binary release until
-  a later full asset release supersedes it.
+  use a later full asset-bearing release once platform assets are available for
+  that tag.
 - This file intentionally excludes pre-fork alpha tags
   `rust-v0.1.0-alpha.*`, upstream high-version `rust-v*` tags, `python-v*`
   SDK tags, and `rusty-v8-v*` dependency artifact tags.

codex-rs/README.md

@@ -51,7 +51,7 @@ You can enable notifications by configuring a script that is run whenever the ag
 ### `codewith exec` to run Codewith programmatically/non-interactively
 
 To run Codewith non-interactively, run `codewith exec PROMPT` (you can also pass the prompt via `stdin`) and Codewith will work on your task until it decides that it is done and exits. If you provide both a prompt argument and piped stdin, Codewith appends stdin as a `<stdin>` block after the prompt so patterns like `echo "my output" | codewith exec "Summarize this concisely"` work naturally. Output is printed to the terminal directly. You can set the `RUST_LOG` environment variable to see more about what's going on.
-Use `codewith exec --ephemeral ...` to run without persisting session rollout files to disk.
+Headless `codewith exec` runs persist session rollout files by default so long-running automation can resume or inspect the thread later. Use `--durable` or `--persist` when a workflow needs to state that contract explicitly, and use `codewith exec --ephemeral ...` only for intentional one-off runs that should not be materialized on disk.
 
 ### Compact output defaults
 

codex-rs/known-provider-models/src/lib.rs

@@ -946,7 +946,7 @@ mod tests {
         assert_eq!(QWEN_PROVIDER_ID, "qwen");
         assert_eq!(
             QWEN_BASE_URL,
-            "https://dashscope-intl.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1"
+            "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
         );
         assert_eq!(XAI_PROVIDER_ID, "xai");
         assert_eq!(XAI_BASE_URL, "https://api.x.ai/v1");

codex-rs/protocol/src/provider_identity.rs

@@ -34,8 +34,7 @@ pub const OPENROUTER_PROVIDER_ID: &str = "openrouter";
 pub const OPENROUTER_BASE_URL: &str = "https://openrouter.ai/api/v1";
 
 pub const QWEN_PROVIDER_ID: &str = "qwen";
-pub const QWEN_BASE_URL: &str =
-    "https://dashscope-intl.aliyuncs.com/api/v2/apps/protocols/compatible-mode/v1";
+pub const QWEN_BASE_URL: &str = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1";
 
 pub const XAI_PROVIDER_ID: &str = "xai";
 pub const XAI_BASE_URL: &str = "https://api.x.ai/v1";

codex-rs/responses-api-proxy/README.md

@@ -77,16 +77,13 @@ codex-responses-api-proxy [--port <PORT>] [--server-info <FILE>] [--http-shutdow
 - `--http-shutdown`: If set, enables `GET /shutdown` to exit the process with code `0`.
 - `--upstream-url <URL>`: Absolute URL to forward requests to. Defaults to `https://api.openai.com/v1/responses`.
 - `--dump-dir <DIR>`: If set, writes one request JSON file and one response JSON file per accepted proxy call under this directory. Filenames use a shared sequence/timestamp prefix so each pair is easy to correlate.
-- Authentication is fixed to `Authorization: Bearer <key>` to match Codewith expectations.
+- Authentication is fixed to `Authorization: Bearer <key>` to match Codewith expectations. Upstreams that require an `api-key` header need a different proxy mode.
 
-For Azure, for example (ensure your deployment accepts `Authorization: Bearer <key>`):
+For Azure OpenAI, `--upstream-url` can point at the current v1 Responses endpoint. The v1 path is shaped as `https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses` and does not need a dated `api-version` query parameter.
 
-```shell
-printenv AZURE_OPENAI_API_KEY | env -u AZURE_OPENAI_API_KEY codex-responses-api-proxy \
-  --http-shutdown \
-  --server-info /tmp/server-info.json \
-  --upstream-url "https://YOUR_PROJECT_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT/responses?api-version=2025-04-01-preview"
-```
+Azure documents both Microsoft Entra bearer-token authentication and API-key authentication. This proxy always injects `Authorization: Bearer <stdin>` and its stdin parser is currently limited to OpenAI-style token bytes. Azure REST examples that use `api-key: $AZURE_OPENAI_API_KEY` and typical Entra JWT access tokens are not supported by this proxy yet; they need a separate Azure auth mode.
+
+Legacy dated endpoints remain selectable because `--upstream-url` accepts a full URL, including a query string, but they have the same authentication limitation.
 
 ## Notes
 

macos/upstream-codex-behavior-audit.md

@@ -0,0 +1,144 @@
+# Upstream Codex macOS Behavior Audit
+
+Task: PR0 wave2 provider docs and small cleanup, covering superseded PR #182.
+
+Compared on 2026-07-09 from CodeWith branch
+`repair/pr0-wave2-provider-docs-cleanup-20260709`.
+
+## Upstream Evidence
+
+- Refreshed `upstream` from `https://github.com/openai/codex.git`.
+- Current `upstream/main`: `dc23c7bcc8a1f90756a3bcb8e979339c9e35a3e3`.
+- `upstream/main` does not contain a `macos/` Swift app tree. A recursive path
+  scan for `^macos/` and `*.swift` on `upstream/main` found no app source.
+- A scan of fetched upstream refs found only
+  `upstream/dev/jm/devicecheck-app-server` with Swift under
+  `codex-rs/devicecheck-probe/DeviceCheckProbe.swift`; that is not desktop app
+  source.
+- The upstream macOS desktop behavior available on `main` is in
+  `codex-rs/cli/src/desktop_app/mac.rs`, plus release/signing support for
+  app-server binaries in `.github/scripts/macos-signing/` and
+  `.github/workflows/rust-release.yml`.
+
+## Current Upstream Behavior to Consider
+
+Upstream `codex-rs/cli/src/desktop_app/mac.rs`:
+
+- Opens an existing app from `/Applications/Codex.app` or
+  `~/Applications/Codex.app`.
+- If missing, downloads a default installer unless an explicit URL override is
+  supplied.
+- Chooses the default DMG URL by architecture:
+  `Codex.dmg` for Apple Silicon and `Codex-latest-x64.dmg` for Intel.
+- Detects Apple Silicon with `std::env::consts::ARCH == "aarch64"` plus macOS
+  `sysctlbyname` checks for Rosetta translation and arm64 hardware.
+- Launches with a deep link shaped as `codex://threads/new?path=<workspace>`.
+- Mounts the DMG read-only with `hdiutil`, finds `Codex.app`, copies it to
+  `/Applications` or `~/Applications`, detaches the DMG, and reports detach
+  failures as warnings after the install attempt.
+- Keeps tests around mount-point parsing and workspace-path URL encoding.
+
+## Current CodeWith Behavior
+
+CodeWith already has a native app under `macos/CodeWith`, not an upstream Swift
+tree to merge:
+
+- `macos/CodeWith/Package.swift` builds a SwiftPM executable named `CodeWith`
+  for macOS 26.
+- `macos/README.md` states the UI target: Codex visual parity with CodeWith
+  branding and fork-only Apps, Machines, Loops, Goals, Workflows, and Profiles.
+- `macos/CodeWith/Sources/CodeWith/App/CodeWithApp.swift` creates a regular
+  AppKit app, keeps a menu-bar status item, restores the window on reopen, and
+  dispatches URL opens through `CodeWithOpenURL`.
+- `AppModel` starts a bundled or installed `codewith app-server`, completes the
+  initialize handshake before marking the UI connected, and falls through to the
+  next CLI candidate if one candidate starts but cannot initialize.
+- The app-server client drives threads, turns, search, Apps, Machines, Loops,
+  Goals, Workflows, auth profiles, config, MCP, hooks, worktrees, account usage,
+  active sessions, agent runs, and pending approvals through JSON-RPC.
+- Machine selection scopes threads, projects, loops, goals, and workflows, and
+  blocks switching while server approval/user-input/elicitation prompts are
+  pending.
+- The app accepts both `codewith://` and `codex://` schemes for desktop URLs,
+  but the CodeWith CLI launch path emits `codewith://threads/new?path=...`.
+- `macos/scripts/run-on-apple03.sh` builds on apple03, bundles a standalone
+  `codewith` CLI into `CodeWith.app/Contents/Resources/codewith`, stamps the app
+  version from the bundled CLI, registers both `codewith` and `codex` URL
+  schemes, ad-hoc signs the bundle, and smoke-tests the bundled CLI.
+- `macos/scripts/shoot.sh` renders deterministic ImageRenderer snapshots and
+  verifies every reported PNG exists and is non-empty.
+
+CodeWith `codex-rs/cli/src/desktop_app/mac.rs` is already adapted for
+`CodeWith.app` and `codewith://`, but it differs from upstream in one important
+way: if the app is missing and no `download_url_override` is supplied, it bails
+with "Install CodeWith.app or pass an explicit desktop app download URL" instead
+of selecting a default installer URL.
+
+## Inherit Recommendations
+
+1. Inherit upstream's no-argument installer behavior after CodeWith has stable
+   default DMG locations. The implementation should keep `download_url_override`
+   precedence, add arm64/x64 CodeWith DMG constants, port the Apple Silicon
+   detection helper, and add unit coverage for architecture selection and URL
+   override precedence. Do not point CodeWith at upstream OpenAI DMG URLs.
+
+2. Keep upstream's install flow shape for macOS: read-only `hdiutil attach`,
+   `.app` discovery in the volume, install to `/Applications` then
+   `~/Applications`, best-effort detach warning, and URL encoding tests. The
+   current CodeWith code already follows most of this.
+
+3. Preserve the app-server-first architecture. Upstream ships app-server release
+   artifacts and signing entitlements; CodeWith's Swift app should continue to
+   treat `codewith app-server` as the functional backend rather than reimplement
+   agent/runtime behavior in Swift.
+
+4. Preserve dual deep-link compatibility. `codewith://` must remain the primary
+   emitted scheme, while `codex://` should continue to work for compatibility
+   with upstream-style links and existing bundle registrations.
+
+5. Preserve CodeWith fork features while importing parity behavior. Do not
+   rename Apps back to Plugins, remove Machines, Loops, Goals, Workflows, or
+   Profiles, or regress auth-profile switching and config surfaces.
+
+6. Keep update behavior fork-specific. The repo rules prohibit re-enabling
+   upstream automatic update checks, update notifications, or prompts; installer
+   defaults must be explicit CodeWith release plumbing, not an upstream updater.
+
+## Existing Follow-Up Coverage
+
+Existing open-codewith todos already cover most broad macOS implementation work:
+
+- `4ccc14a9-3c1c-48fb-8914-0826b81f7fa3`: build and smoke-test CodeWith macOS
+  app on apple03.
+- `c60c3cc7-a3b9-47ee-9b5f-b9dca6cdf2db`: fix macOS app implementation bugs
+  without UI redesign.
+- `d388f9f1-f7af-41ab-8c1c-763db21e7497`: reuse CodeWith CLI/app-server
+  harnesses in the macOS app.
+- `068cfd91-37b5-4a81-b9cd-cb2ba2bab9da`: wire macOS Goals and Loops creation
+  to app-server APIs.
+- `768a69f0-ec95-481d-9179-b0c61b950edc`: surface macOS goal plans and
+  activate-node actions.
+- `8deb5727-7acc-4ad2-a050-bd0096271d7f`: harden remaining inert macOS settings
+  and action controls.
+- `b77ee917-5e1e-42f4-b73c-691d4f9b63fd`: adversarially review macOS app fixes.
+
+New non-duplicate follow-up candidate:
+
+- Add CodeWith macOS default installer URL selection to `codewith app`.
+  Acceptance should require CodeWith-owned arm64/x64 DMG URLs, no fallback to
+  OpenAI-hosted Codex installers, existing explicit URL override behavior, and
+  Rust tests for architecture/default-url selection.
+
+## Validation Notes
+
+This audit intentionally does not build the Swift app because it changes
+documentation only. Suitable validation for this change is:
+
+- `git diff --check`
+- staged secrets scan before commit
+- `git status --short --branch`
+
+If a future change implements installer defaults in Rust, validate with
+`cd codex-rs && just fmt` and targeted `just test-fast -p codex-cli`. If Swift
+behavior changes, validate on an Xcode/macOS 26 host with `swift test` or the
+existing apple03 scripts.