dsh-codex-connect 0.1.0-alpha.4.3 → 0.1.0-alpha.4.30

package/INSTALL.md

@@ -1,5 +1,7 @@
 # Installation Runbook for CLI Agents
 
+Alpha 4.29 is verified with DSH `0.1.2-rc.1` and its declared pi-ai range `^0.84.2`.
+
 Install `dsh-codex-connect` into one requested DeepSeek Harness profile without changing its current default model, search route, global configuration, or OAuth state.
 
 ## Safety requirements
@@ -12,26 +14,88 @@ Install `dsh-codex-connect` into one requested DeepSeek Harness profile without
 
 ## Install and validate
 
-1. Check `dsh --version` or `dsh --help`. From a Harness checkout use `pnpm dsh`.
-2. Install the package:
+### Select an exact version before installation
+
+Check `dsh --version` before changing the requested profile. Use `dsh --help` to locate the CLI if needed; from a Harness checkout use `pnpm dsh --version`. Select an exact pair from [verified-compatibility.json](verified-compatibility.json):
+
+| Installed DSH version | Codex Connect version to pin |
+| --- | --- |
+| `0.1.0-rc.7` | `0.1.0-alpha.4.14` |
+| `0.1.1-rc.2` | `0.1.0-alpha.4.21` |
+| `0.1.2-alpha.2` | `0.1.0-alpha.4.23` |
+| `0.1.2-rc.1` | `0.1.0-alpha.4.29` |
+| `0.1.2-alpha.5` | `0.1.0-alpha.4.25` |
+
+If your exact DSH version is unknown or not listed, stop and verify the combination before installing. Do not blindly install `dsh-codex-connect@alpha`: `alpha` is a moving tag, not a compatibility guarantee. Do not infer support for newer DSH versions from these rows.
+
+Alpha 4.29's verified contract is DSH plugin API packages `0.1.2-rc.1`, `@earendil-works/pi-ai` `^0.84.2`, and Node.js `^22.19.0 || >=24.0.0`. Alpha 4.25 remains the verified choice for DSH `0.1.2-alpha.5`, Alpha 4.23 remains the verified choice for DSH `0.1.2-alpha.2`, Alpha 4.21 remains the verified choice for DSH `0.1.1-rc.2`, and staying on DSH `0.1.0-rc.7` means selecting Alpha 4.14. Upgrading DSH is a separate decision: upgrade the DSH API packages and pi-ai together, then rerun `dsh-codex-connect doctor --json` and `pnpm --silent run check:compatibility` for the selected combination.
+
+The Alpha 4.29 row reflects a fresh isolated installation and runtime probe. Historical rows remain the repository's existing verification record. This guidance does not change upstream DSH behavior or resolve [Issue #64](https://github.com/franksong2702/dsh-codex-connect/issues/64).
+
+### Install the selected version and validate
+
+1. Complete the version selection above. The commands below use `web`; substitute only the requested profile.
+2. Install the selected exact version. For DSH `0.1.0-rc.7`:
 
    ```sh
-   dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.3'
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.14
    ```
 
-3. Run `dsh --profile web --dump-config` and require exactly one `llm-openai-codex` row loading `dsh-codex-connect`.
-4. Confirm the effective `agent-default-model` and `web.searchProvider` values are unchanged from before installation.
-5. Run secret-free diagnostics:
+   For DSH `0.1.1-rc.2`, use Alpha 4.21:
+
+   ```sh
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.21
+   ```
+
+   For DSH `0.1.2-alpha.2`, use Alpha 4.23:
+
+   ```sh
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.23
+   ```
+
+   For DSH `0.1.2-rc.1`, use Alpha 4.29:
+
+   ```sh
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.29
+   ```
+
+   For DSH `0.1.2-alpha.5`, use Alpha 4.25:
+
+   ```sh
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.25
+   ```
+
+   If npm is unavailable after the matching GitHub prerelease is created, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.21'` only for the DSH `0.1.1-rc.2` combination, `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.23'` only for the DSH `0.1.2-alpha.2` combination, `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.25'` only for the DSH `0.1.2-alpha.5` combination, or `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.29'` only for the DSH `0.1.2-rc.1` combination.
+
+3. Run `dsh web --help` once to compose the installed profile without starting the server. DSH `0.1.2-rc.1` prepares profile plugin dependency fallback during this step.
+4. Run `dsh --profile web --dump-config` and require exactly one `llm-openai-codex` row loading `dsh-codex-connect`.
+5. Confirm the effective `agent-default-model` and `web.searchProvider` values are unchanged from before installation.
+6. Run secret-free diagnostics:
 
    ```sh
    dsh plugin --profile web exec dsh-codex-connect doctor
    ```
 
-6. If the user explicitly requests login, open **Settings → Plugins → Plugin configuration → Codex Connect**, or check `status` and then use `login` or `login --device-code`. OAuth approval belongs to the user.
+7. If the user explicitly requests login, open **Settings → Plugins → Plugin configuration → Codex Connect**, or check `status` and then use `login` or `login --device-code`. OAuth approval belongs to the user.
+
+   Alpha 4.25 offers the same account actions in **Settings → Models → Openai-Codex**, plus a shared **More settings** dialog for model visibility, proxy, search, image, context-budget, and Auto-review controls. The original Plugin settings entry remains available; neither entry automatically starts login or changes model/search defaults.
+
+   When signed out, select **Authorize**. When signed in, use **Sign out** or **View quota**; use **More settings** for plugin options. If authorization is abandoned, use **Reopen authorization** or **Cancel sign-in** and retry; cancellation does not delete an existing account. Pending authorization expires after 10 minutes by default (`oauthTimeoutMs` in plugin configuration, applied on load).
+
+### Remote browser access
+
+The default Web OAuth boundary is loopback-only. When DSH runs on one device and you open it from another device on a trusted network through an IP address or domain, run the following on the device that runs DSH with the exact origin from the browser address bar:
+
+```sh
+dsh plugin --profile web exec dsh-codex-connect trust-origin http://192.168.1.20:3080
+dsh plugin --profile web exec dsh-codex-connect trusted-origins
+```
+
+The value is a full `http://` or `https://` origin including its port, not a bare device IP and not a path/query/fragment. Use `untrust-origin <origin>` to remove it. Restrict this to a trusted network and never expose the route publicly; use an SSH tunnel when that is safer. The Web client does not edit this list.
 
 ## Optional configuration
 
-Use **Settings → Plugins → Plugin configuration → Codex Connect** for live, staged Save/Discard edits. The package row accepts the same `enableSearch` and `enableImageTool` fields as its composition base, both defaulting to `false`. Enabling search registers a provider but does not select it; selecting `web.searchProvider: openai-codex` is a second explicit profile change. Setting `agent-default-model` to `openai-codex` is also a separate explicit change.
+Use **Settings → Plugins → Plugin configuration → Codex Connect** for live, staged Save/Discard edits organized under Account & quota, Models, Network, and Capabilities. Switching modules preserves the draft. The same settings control `enableSearch`, `enableImageTool`, `enableImageGeneration`, and `enableAutoReview`; all four default to `false`. Enabling Auto-review permits bounded approval context, tool arguments, working directory, and the planned action to be sent to `chatgpt.com`; failures return to human approval. Enabling image generation uses the image generation capability included with the current GPT subscription and saves results as DSH attachments. Enabling search registers the provider and selects it while the capability remains enabled; disabling restores the previous provider before unregistering Codex Search. Setting `agent-default-model` to `openai-codex` remains a separate explicit change.
 
 Apply only requested choices and preserve unrelated keys:
 
@@ -40,19 +104,17 @@ Apply only requested choices and preserve unrelated keys:
   config:
     enableSearch: true
     enableImageTool: false
+    enableImageGeneration: false
+    enableAutoReview: false
     searchMode: live
 
-- id: web
-  config:
-    searchProvider: openai-codex
-
 - id: agent-default-model
   config:
     provider: openai-codex
     model: gpt-5.6-sol
 ```
 
-Do not add the last two rows unless the user separately requested those routing changes.
+Do not add a separate `web` row for this UI action. Do not add the `agent-default-model` row unless the user separately requested that default.
 
 ## Conflict handling
 
@@ -60,11 +122,15 @@ Do not add the last two rows unless the user separately requested those routing
 
 ## Update and removal
 
+Before updating, repeat the exact-version selection above. Use `@alpha` only after verifying that the version it currently resolves to is compatible with the installed DSH; otherwise pin the selected version in the update command.
+
 ```sh
-dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#<new-release-tag>'
+dsh plugin --profile web update dsh-codex-connect@alpha
 dsh plugin --profile web remove dsh-codex-connect
 ```
 
+Use an exact npm version when a reproducible update is required; use a GitHub tag only as the npm-unavailable fallback.
+
 Removal of the package and removal of its separate OAuth file are different actions. Run `dsh plugin --profile web exec dsh-codex-connect logout` only with explicit credential-deletion authorization.
 
 ## Completion report

package/MIGRATION.md

@@ -10,3 +10,21 @@
 6. Run `--dump-config`, then `dsh-codex-connect doctor`. Do not run OAuth again when `status` already reports signed in.
 
 Rollback is the inverse package swap. Do not delete or copy the separate OAuth file during either direction. If Harness reports a duplicate `openai-codex` adapter, the old bundle or a manual provider row is still active; resolve that one row instead of changing credentials.
+
+## Repairing search history written by Alpha 4.10
+
+Alpha 4.10 briefly wrote `web/openai-codex-search-llm-request` as a required private Session event. Because an external plugin cannot extend the Host persistence vocabulary across independent module instances, a newer Harness can refuse to read those histories after the event writer is removed.
+
+Upgrade Codex Connect, then inspect the default `$DSH_HOME/sessions` root without changing it:
+
+```sh
+dsh plugin --profile web exec dsh-codex-connect migrate-history --json
+```
+
+If the dry run reports affected events, stop every DSH process that can write this Session root and apply the migration. `--confirm-stopped` is required together with `--apply`:
+
+```sh
+dsh plugin --profile web exec dsh-codex-connect migrate-history --apply --confirm-stopped --json
+```
+
+The migration changes only that retired event's envelope by adding `"ignorable": true`. It preserves event data, sequence, time, and the concatenated Zstandard frame layout, and creates `session.jsonl.zstd.pre-codex-search-history-migration` beside every changed artifact before replacing it. Keep that backup until you have reopened and verified the repaired Session. Re-running the command is safe. For a non-default JSONL persistence root, pass `--root /absolute/path/to/sessions`. SQLite and uncompressed JSONL stores are not modified by this command. Applying fails closed when the filesystem cannot create the required same-directory hard-link backup. Applying is also fail-closed on Windows; Windows users can run the dry-run only.

package/NOTICE

@@ -13,3 +13,8 @@ release validation.
 
 The upstream material and the Codex Connect modifications are distributed
 under the Apache License, Version 2.0 included in LICENSE.
+
+This product also includes OAuth login and refresh code from earendil-works/pi
+(@earendil-works/pi-ai 0.84.4), under the MIT license reproduced in
+docs/licenses/pi-ai-oauth.txt. JWT payload decoding, callback connection cleanup
+and structured refresh rejection handling are modified.

package/README.i18n.yaml

@@ -1,6 +1,6 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# Bilingual-pair consistency record: the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   git hash-object README.md README.zh.md
-README.md: e7a63add3ad36f0291b42190cdbf16e2c655a3b8
-README.zh.md: bae8717ef5c8c8221d7576ec5b889b9a206991f3
+#   git hash-object README.md docs/README.zh.md
+README.md: a46589829b432cfcb97af069f7d7a7b3080e42af
+docs/README.zh.md: c42807c90ad4fcc4a4850d1228cfd6330b2bc184

package/README.md

@@ -1,110 +1,128 @@
 # Codex Connect
 
-English | [中文](README.zh.md)
+[![npm version](https://img.shields.io/npm/v/dsh-codex-connect/alpha?label=npm%20alpha&color=cb3837)](https://www.npmjs.com/package/dsh-codex-connect)
 
-Connect your ChatGPT subscription to DeepSeek Harness with OAuth, user-controlled defaults, Harness-native approvals, diagnostics, and reliable session recovery.
+English | [中文](docs/README.zh.md)
 
-`dsh-codex-connect` adds the `openai-codex` model catalog and a separate ChatGPT OAuth login. Models run through Harness's normal LLM service, so streaming, tool calls, reasoning replay, compaction, filesystem controls, permission gates, and approval prompts remain Harness-owned. It does not turn a ChatGPT subscription into an OpenAI Platform API credential.
+Connect your ChatGPT subscription to DeepSeek Harness with OAuth, optional GPT Image generation, user-controlled defaults, Harness-native approvals, diagnostics, and reliable session recovery.
 
-Installation is additive. The bundle does not replace the current default model or search route, and its standalone search provider and `view_image` tool are disabled until explicitly enabled.
+Community Alpha — not affiliated with or endorsed by OpenAI, ChatGPT, Codex, DeepSeek, or DeepSeek Harness.
 
-## Install
+Codex Connect adds the `openai-codex` model provider to the normal Harness agent loop. Harness continues to manage tools, permissions, approvals, attachments, session persistence, compaction, and recovery. Installing the plugin does not change your default model or search route, and it does not turn a ChatGPT subscription into an OpenAI Platform API key.
+
+## Quick start
+
+This guide describes the published pairing below. Check `dsh --version` first; for another DSH version, use [Installation and upgrades](INSTALL.md). A moving npm tag such as `alpha` is not a compatibility guarantee.
+
+| Requirement | Verified pairing |
+|---|---|
+| Codex Connect | `0.1.0-alpha.4.29` |
+| DeepSeek Harness | `0.1.2-rc.1` |
+| Node.js | `^22.19.0 \|\| >=24.0.0` |
+| Account | ChatGPT OAuth with access to the requested Codex model; availability is decided by OpenAI |
+
+### 1. Install
 
 ```sh
-dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.3'
+dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.29
 dsh web
 ```
 
-This installs the current alpha directly from its tagged GitHub release using Harness's supported Git package path. From a DeepSeek Harness source checkout, prefix commands with `pnpm`. For a local checkout, install `link:/absolute/path/to/dsh-codex-connect`.
+Replace `web` with your existing profile name; use that same profile when starting Harness. From a DSH source checkout, prefix commands with `pnpm`. See [INSTALL.md](INSTALL.md) for other profiles and installation checks.
+
+### 2. Authorize and select a model
 
-Sign in from **Settings → Plugins → Plugin configuration → Codex Connect → Sign in with ChatGPT**, or use the CLI:
+Open **Settings → Models → Openai-Codex → Authorize**, then complete approval yourself in the browser. If an embedded window is blocked, select **Open ChatGPT sign-in page**. Choose an `openai-codex` model in the normal Harness model picker.
+
+Never paste an authorization URL, code, token, or account identifier into an issue, log, chat, or configuration file. For a browser on another device, follow [Remote browser authorization](docs/reference.md#remote-browser-authorization).
+
+### 3. Check the installation
 
 ```sh
-dsh plugin --profile web exec dsh-codex-connect login
-dsh plugin --profile web exec dsh-codex-connect status
-dsh plugin --profile web exec dsh-codex-connect doctor
+dsh plugin --profile web exec dsh-codex-connect status --json
+dsh plugin --profile web exec dsh-codex-connect doctor --json
 ```
 
-The doctor command reads process and filesystem metadata only. It never opens the OAuth document or prints a token, authorization URL, authorization code, account id, or auth-file content.
+`status --json` exits `0` when signed in and `1` when signed out, without starting OAuth. `doctor --json` reports local installation diagnostics without a network request or raw credentials. A passing diagnostic is not proof of model access; verify that with an actual request.
 
-## Explicit configuration
+<p align="center">
+  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/en/hero.jpg" alt="Codex Connect — ChatGPT OAuth for DeepSeek Harness" width="100%">
+</p>
 
-Open **Settings → Plugins → Plugin configuration → Codex Connect** to manage the ChatGPT account and optional capabilities in one card. Changes use Harness's revision-fenced settings store and apply live. **Save changes** affects only this plugin's capability section; it never selects a default model or global search route.
+## Core capabilities
 
-The installed bundle row remains the composition base and is intentionally inert beyond model-provider registration:
+- **Accounts:** save up to 16 accounts on the DSH host and manually select the active account for subsequent requests. Account selection is not a per-session binding. Requests keep their captured account; the plugin does not rotate accounts or silently fail over.
+- **Models and Astra support:** the currently verified DSH and plugin combination supports `gpt-6-astra`. The plugin supplies the Astra model definition missing from the current dependency catalog, so users can select it without separately upgrading the underlying library. When the installed dependency catalog includes Astra, the plugin prefers its native definition. A model appearing in the list does not mean the current account has permission to use it; overall compatibility with new dependency versions still requires separate verification.
+- **Fast Mode:** request priority service for one conversation, off by default. Actual speed and quota consumption depend on the service; no fixed speed multiplier is guaranteed.
+- **Quota:** show the server-returned `5h` and `7d` windows and reset times, normally refreshed every 60 seconds while signed in. Missing windows are not invented; Spark uses its separate quota bucket.
+- **Update guidance:** compare the installed DSH/plugin pair with the public verification record without installing an upgrade.
 
-```yaml
-- id: llm-openai-codex
-  config:
-    enableSearch: false
-    enableImageTool: false
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/franksong2702/dsh-codex-connect/main/docs/assets/composer-capabilities.jpg" alt="Fast Mode and quota controls in the DeepSeek Harness Composer" width="820">
+</p>
 
-To make a Codex model the default for new agents, add or update the separate Harness row yourself:
+## Optional capabilities
 
-```yaml
-- id: agent-default-model
-  config:
-    provider: openai-codex
-    model: gpt-5.6-sol
-```
+All options below are off on a fresh installation. Edit them in **Settings → Plugins → Plugin configuration → Codex Connect** or **Settings → Models → Openai-Codex → More settings**, then select **Save changes**. A conflict or failed save preserves your draft.
 
-The card can enable Codex standalone search. Selecting it as the profile's global search provider remains a separate explicit choice:
+| Capability | Enable with | Important behavior |
+|---|---|---|
+| Proxy | `enableProxy` | Credential-free HTTP(S), scoped to this plugin's traffic. A failed proxy request does not silently retry directly. |
+| Codex Search | `enableSearch` | Selects Codex for the entire profile's search route; disabling restores the previously active route. |
+| Image viewing | `enableImageTool` | Adds `view_image` to vision-capable models for local files and validated public HTTP(S) images. |
+| GPT Image generation | `enableImageGeneration` | Prompt-only generation; availability, dimensions, and quota remain account- and service-controlled. |
+| Auto-review | `enableAutoReview` | Sends bounded approval context, tool arguments, working directory, and the planned action to `chatgpt.com`, with confirmation on first enablement. Failures return to human approval. |
 
-```yaml
-- id: llm-openai-codex
-  config:
-    enableSearch: true
-    searchMode: live
-    searchContextSize: medium
+Use the image generation capability included with your current GPT subscription. Generated originals are stored separately from attachment previews; disabling the capability or uninstalling the plugin does not delete them. See [Configuration and recovery](docs/reference.md#search-and-image-tools) for storage and access rules.
 
-- id: web
-  config:
-    searchProvider: openai-codex
-```
+Auto-review operates after Harness policy requires approval; it does not bypass that policy. See [Auto-review behavior](docs/auto-review.md) before enabling it.
 
-To add the image-loading tool, set `enableImageTool: true` on `llm-openai-codex`. Browser paste/drop remains a Harness attachment feature and does not depend on this tool.
+## FAQ and important limits
 
-| Field | Default | Values |
-|---|---:|---|
-| `enableSearch` | `false` | boolean |
-| `enableImageTool` | `false` | boolean |
-| `searchModel` | `gpt-5.6-sol` | Codex model id |
-| `searchMode` | `cached` | `cached`, `indexed`, `live` |
-| `searchContextSize` | `medium` | `low`, `medium`, `high` |
-| `searchMaxOutputTokens` | `10000` | positive integer |
+### Where are my credentials stored?
 
-## Credentials, diagnostics, and conflicts
+OAuth credentials are stored on the host running DSH and used there to authenticate and send requests to OpenAI. Normal browser account responses return account summaries, not raw tokens. A remote browser device is not necessarily the DSH host.
 
-- OAuth is stored separately at `$DSH_HOME/.openai-codex-auth.json` (`~/.dsh` by default); `~/.codex/auth.json` is never copied or modified.
-- The parent directory and file are created with owner-only permissions where supported. Writes are atomic, and refresh writes use a cross-process file lock.
-- Status and diagnostics return only non-sensitive state. OAuth flow output is confined to an explicit `login` operation.
-- Browser OAuth routes accept only loopback clients and loopback Host/Origin values; sign-in fails closed when no valid HTTPS authorization URL arrives within 30 seconds.
-- A second adapter cannot own `openai-codex`. Startup fails with a focused hint when the legacy `dsh-codex` bundle or a manual provider row conflicts.
-- Removing the package does not delete OAuth state. Run `logout` only when credential removal is intended.
+### Does uninstalling sign me out?
 
-## Compatibility and security boundary
+No. OAuth state is stored separately at `$DSH_HOME/.openai-codex-auth.json` (`~/.dsh` by default). The plugin does not copy or modify `~/.codex/auth.json`. Use **Sign out all accounts**, or `logout` before uninstalling, only when deleting credentials is intentional.
 
-- Alpha compatibility targets the current Harness `0.1.0-rc.5` main-line composition and compatible `0.1.0-rc.6` plugin APIs, Node.js `^22.19.0 || >=24.0.0`, and the pinned `@earendil-works/pi-ai` Codex provider.
-- ChatGPT plan eligibility, model access, quotas, and backend behavior are controlled by OpenAI and may change.
-- The Codex endpoint does not enforce the ordinary Responses `max_output_tokens` field. Harness compaction still works, but that summary cap cannot be imposed server-side on this route.
-- Shell, filesystem, skills, MCP, subagents, approvals, permissions, attachments, session persistence, compaction, and recovery continue to come from the active Harness profile.
-- Remote `view_image` URLs are limited to public HTTP(S) destinations. Every DNS result and redirect is checked, and the connection is pinned to the validated address so localhost, private networks, link-local services, and cloud metadata endpoints remain unreachable.
-- No real OAuth operation is required for installation, build, tests, doctor, or package validation.
+### Can I switch accounts for different conversations?
 
-See [INSTALL.md](INSTALL.md) for the idempotent agent runbook, [MIGRATION.md](MIGRATION.md) for migration from `dsh-codex`, and [docs/design.md](docs/design.md) for architecture details.
+Subsequent Codex requests use the selected active account; conversations do not bind their own accounts. Fast Mode is conversation-scoped. Cancelling a new authorization preserves existing accounts; an explicit revoked-refresh response asks for reauthorization, while temporary failures preserve the account for retry. See [Account behavior](docs/reference.md#accounts-models-and-quota).
 
-## Development
+### Why does a listed model fail?
+
+Account permissions, plugin/host compatibility, and network conditions all affect availability. Access on another client does not guarantee this integration will work. OpenAI controls model access, quota, context capacity, and service behavior; catalog entries are not proof of entitlement.
+
+### Can I keep the original `dsh-codex` plugin installed?
+
+Not in the same effective configuration: both register `openai-codex`. Follow [MIGRATION.md](MIGRATION.md); remove only the confirmed conflicting entry, not credentials or unrelated providers.
+
+### What do diagnostics prove?
+
+`doctor` is local. Capability and reviewer probes may make network requests and consume quota when their preconditions are met. `auto-review-probe` checks only the reviewer route and structured response, not the full Harness approval integration or execution of the reviewed action. Commands, limits, and exit codes are in the [diagnostics reference](docs/reference.md#capability-probes).
+
+A missing entry in [verified-compatibility.json](verified-compatibility.json) means a DSH/plugin combination is unverified, not known to be broken. Do not infer support for newer hosts from an older pairing.
+
+## Documentation and development
+
+- [Installation and upgrades](INSTALL.md)
+- [Configuration, diagnostics, and recovery](docs/reference.md)
+- [Migration from `dsh-codex`](MIGRATION.md)
+- [Architecture and security details](docs/design.md)
+- [Auto-review behavior](docs/auto-review.md)
+- [Release runbook](RELEASING.md), [Contributing](CONTRIBUTING.md), and [Security policy](SECURITY.md)
 
 ```sh
 pnpm install --frozen-lockfile
 pnpm run check
+pnpm run test:browser
+pnpm run check:dsh-install
 ```
 
-## Legal / Acknowledgements
-
-Copyright 2026 Frank Song for the modifications and additional work in Codex Connect. This project includes software derived from [Yan-Zero/dsh-codex](https://github.com/Yan-Zero/dsh-codex); Copyright 2026 Yan-Zero is retained for the upstream material. Both are distributed under Apache-2.0, with details in [NOTICE](NOTICE). This project is not affiliated with or endorsed by OpenAI, ChatGPT, Codex, DeepSeek, or DeepSeek Harness.
+`check` covers static checks, unit tests, build, compatibility, and packaging. Browser regression and isolated DSH installation are separate commands. These checks use no real OAuth authorization and do not replace real-account acceptance.
 
-## License
+## License and acknowledgements
 
-Apache-2.0
+Copyright 2026 Frank Song for Codex Connect modifications and additional work. This project contains software derived from [Yan-Zero/dsh-codex](https://github.com/Yan-Zero/dsh-codex); Copyright 2026 Yan-Zero is retained for upstream material. Both are distributed under Apache-2.0; see [NOTICE](NOTICE).

package/VERSIONING.md

@@ -0,0 +1,65 @@
+# Versioning policy
+
+English | [中文](docs/VERSIONING.zh.md)
+
+Codex Connect versions identify plugin releases independently of DeepSeek Harness. Show the plugin version and its verified DSH pairing together; do not infer one from the other.
+
+## Release identity and phase
+
+The current release series is `0.1.0-alpha.4.x`. Increment the final counter for another release in this series; a DSH update does not reset it. This policy does not rename any existing release or select a new version.
+
+The publishing workflow accepts `MAJOR.MINOR.PATCH-alpha.NUMBER[.NUMBER…]`, with nonnegative integer components and no leading zeroes. Build metadata is not a release counter: SemVer ignores `+build.n` when comparing versions, and the pinned npm publishing implementation removes it. Use a distinct, higher-precedence version for every new package. Never overwrite a published package or move its release tag to different content.
+
+The plugin's public behavior includes configuration, tools, commands, and stored data. In the `0.y.z` development period, incompatible changes require explicit release notes and migration guidance; intentionally starting a new incompatible release line increments the plugin minor version. Routine iterations within the current Alpha line increment its prerelease counter. Copying a host's version is not a substitute for deciding the plugin's change scope.
+
+Alpha, Beta, RC, and a non-prerelease version describe the plugin's readiness, not DSH's. Phase promotion is a separate maintainer decision backed by recorded verification, including real-account and upgrade acceptance where relevant. A stable DSH release does not make the plugin stable. The current workflow remains Alpha-only; Beta, RC, and stable publishing need a separately reviewed workflow/channel change.
+
+## Compatibility evidence
+
+| Information | Maintained in | Meaning |
+|---|---|---|
+| Plugin build version | `package.json.version` | Identity embedded in the build and CLI |
+| Host dependency requirements | `compatibility.json` and dependency declarations | Intended supported runtime constraints, checked for consistency |
+| Verified exact combinations | `verified-compatibility.json` | Evidence from checks of each explicit DSH/plugin pair |
+| User-visible changes | GitHub Release notes and `update-highlights.json` | What changed between plugin releases |
+
+Keep the compatibility catalog's `schemaVersion: 1`, `checkedAt`, `latestDshVersion`, and `pluginVersions[].{version,verifiedDshVersions}` fields at the existing URL. Preserve historical entries. An unlisted pair is unverified, not necessarily incompatible. Neither a target dependency nor a green test on a different pairing proves compatibility.
+
+Record a new exact pair only after verification. A candidate's verification record does not prove npm publication. Before recommending it publicly, confirm both that the version exists on npm with its matching release tag and that the pair is recorded. The offline lint check verifies the recorded pair and bilingual agreement; it does not contact npm or certify publication.
+
+Do not replace V1 in place with a version-keyed object or infer a range from a single successful version. Any future incompatible format needs a versioned endpoint and continued output for installed V1 clients.
+
+## Channels and recommendations
+
+- `alpha` is the moving channel written by the current release workflow.
+- `latest` is promoted separately and intentionally. Before the first stable release it may point to a verified Alpha; afterward it must point only to stable releases. Publishing an Alpha does not authorize or perform this promotion.
+- Exact installation commands identify a plugin release; dist-tags do not guarantee compatibility.
+- Keep the public README recommendation on a confirmed published pair while preparing a newer candidate. The recommendation may therefore differ from `package.json.version`.
+
+The project newest version and the newest verified plugin for a user's existing DSH are different questions. More precise host-specific recommendations and generated installation sections are follow-up work; this policy does not claim the current update UI computes that choice from every historical record.
+
+## Update highlights
+
+Keep V1 highlight entries in increasing SemVer order, with unique versions and known capability kinds. Preserve the existing history. New documentation-only or maintenance releases may be omitted; existing empty `highlights` arrays remain valid. Release notes still describe fixes. Do not invent capabilities or require a contiguous counter sequence just to validate the catalog.
+
+## A future numbering cleanup
+
+A shorter independent series, such as `0.2.0-alpha.1`, is a possible later migration, not the next version selected by this change. Do not reset to `0.1.0-alpha.1`: it sorts below the current `0.1.0-alpha.4.x` releases.
+
+Before a migration, verify that installed clients recognize the new version as an update, preserve compatibility and highlight history, and check package, workflow, tag, and channel agreement. For a phase change, also update the Alpha-only gates and publication/readback path. Keep host upgrades, schema changes, and numbering migration separately reviewable.
+
+## Release checks
+
+Follow [RELEASING.md](RELEASING.md) for the complete procedure. Run the frozen install and existing checks separately:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run check
+pnpm run test:browser
+pnpm run check:dsh-install
+npm pack --dry-run
+```
+
+`check` does not include the browser suite or isolated DSH installation. Regenerate the lockfile only when dependency changes require it; do not refresh the dependency tree for a documentation or localization release. Automated checks do not replace real OAuth acceptance. Merge, publish, and `latest` promotion remain distinct operations.
+
+Normative references: [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html) and the pinned [npm 11.6.4 publishing implementation](https://github.com/npm/cli/blob/v11.6.4/workspaces/libnpmpublish/lib/publish.js).

package/compatibility.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": 1,
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "dshPluginApi": {
+    "version": "0.1.2-rc.1",
+    "packages": [
+      "@deepseek-ai/dsh-agent",
+      "@deepseek-ai/dsh-atomic-write",
+      "@deepseek-ai/dsh-attachment",
+      "@deepseek-ai/dsh-home-paths",
+      "@deepseek-ai/dsh-host-webserver",
+      "@deepseek-ai/dsh-invariants",
+      "@deepseek-ai/dsh-llm",
+      "@deepseek-ai/dsh-llm-pi-ai",
+      "@deepseek-ai/dsh-fs",
+      "@deepseek-ai/dsh-session",
+      "@deepseek-ai/dsh-settings",
+      "@deepseek-ai/dsh-tools",
+      "@deepseek-ai/dsh-util-values",
+      "@deepseek-ai/dsh-web"
+    ]
+  },
+  "piAi": {
+    "package": "@earendil-works/pi-ai",
+    "version": "^0.84.2"
+  }
+}

package/cordis.patch.yml

@@ -4,5 +4,8 @@
     - id: llm-openai-codex
       name: dsh-codex-connect
       config:
+        enableProxy: false
         enableSearch: false
         enableImageTool: false
+        enableImageGeneration: false
+        enableAutoReview: false