-**WebCodex lets ChatGPT, Claude, and other AI agents work directly with code and developer tools on your own machines.**
+
WebCodex
-Ask your assistant to inspect a repository, modify code, run tests, use Git, or investigate a failure. Your repository stays on the machine where it already lives; you do not need to move the project into a hosted workspace just to use an AI coding agent.
+
Give cloud AI agents a real development environment on your own machines.
+
Connect ChatGPT, Claude, and other MCP clients to the repositories, Git checkout, compilers, tests, and tools you already use.
-### Everyday development: full WebCodex (recommended)
+
+
+
+
+
+
-If you want ChatGPT to keep using your real development environment, start with a **regular Server + Runner**. This is the full development experience: durable access to multiple projects plus project exploration, editing, Git, commands, tests, long-running work, and code navigation. Public HTTPS, Cloudflare Tunnel, and OpenAI Secure MCP Tunnel are only ways for ChatGPT to reach the Server; they do not switch you into a different restricted experience.
+## Try one repository
-Follow the [Full Setup guide](docs/PERSONAL_SETUP.md) for installation, one-time login, project selection, Runner startup, and ChatGPT connection. You do not need to learn internal identity, registry, or token details before the first successful setup.
-
-### Just trying it for a few minutes: temporary share
-
-To quickly see whether WebCodex fits your workflow, run this inside one repository:
+From a repository you want an AI client to inspect:
```bash
cd /path/to/your/repository
npx --yes @yyjeqhc/webcodex share
```
-`share` starts a temporary, single-project, restricted WebCodex environment and prints the ChatGPT connection values. The endpoint and temporary credential stop working when the command exits. It is intended for trials and short-lived sharing, not as the default full daily setup. See the [Quick Trial](docs/QUICK_START.md) for the exact steps.
+This starts a **temporary, single-project, restricted trial**. Keep the command running, use the printed MCP connection values, and stop it to end the endpoint and credential. See the [Quick Trial](docs/QUICK_START.md) for prerequisites and ChatGPT connection steps.
+
+## Full setup
-## What can it do?
+For everyday development, run a regular **Server + Runner**. The Runner works where your repositories and toolchain already live; the Server gives your AI client an authenticated path to registered projects. This supports multiple projects and the full development workflow.
-- **Understand and edit code** — read, search, inspect, and make guarded changes inside configured projects.
-- **Use the real toolchain** — run commands, tests, formatters, compilers, and project-specific tooling on the machine that owns the repository.
-- **Work with Git** — inspect status and diffs while keeping repository operations visible and reviewable.
-- **Handle long-running work** — keep jobs observable instead of requiring one model turn to stay open indefinitely.
-- **Support human review** — use the Runtime Console and task workflow to guide, cancel, accept, or reject work where those actions are available.
+Install the CLI with `npm install -g @yyjeqhc/webcodex`, then follow the [Full Setup guide](docs/PERSONAL_SETUP.md). A public HTTPS endpoint or tunnel is a way to reach the Server, not a replacement for the regular setup.
-## Why WebCodex?
+## Why WebCodex
-- **Your code stays on your machine.** The repository does not need to be copied into the chat service.
-- **The agent gets a real development environment.** It can use the same files, Git checkout, compilers, tests, and tools you already use.
-- **Work survives beyond a single request.** Long-running execution and evidence remain observable through WebCodex.
-- **Start temporary or run it long-term.** Use one-command sharing for a quick session, or connect machines to a self-hosted Server for a durable setup.
+- **Work on the real repository.** The Runner operates in registered project directories on your machine, using the Git checkout you already have.
+- **Use the real toolchain.** Read and edit code, inspect Git, and run compilers, tests, formatters, and project commands within the configured boundaries.
+- **Keep long work observable.** Commands and checks that outlive a quick response continue as Jobs with bounded status and output you can inspect or stop.
+- **Keep work reviewable.** Project policy, guarded edits, Git diffs, validation results, and runtime evidence help you inspect what happened.
## How it works
-```text
-AI client
- |
- | MCP / HTTPS
- v
-WebCodex
- |
- v
-your machine
- |
- +-- repository
- +-- Git
- +-- compilers / tests / developer tools
-```
+WebCodex is a self-hosted execution bridge. The AI client calls its Server through MCP; the Server authenticates and routes the request, and a Runner on the repository machine performs the work. The Server does not scan your filesystem for projects. For the detailed model, see [Architecture](docs/ARCHITECTURE.md).
-For the internal Server/Runner architecture, protocol surfaces, and authority boundaries, see [Architecture](docs/ARCHITECTURE.md), [MCP](docs/MCP.md), and [Authentication](docs/AUTH_MODEL.md).
+## Security and control
-## Platforms
+Your repository stays on the machine that owns it. Tool results, including requested file excerpts, may be returned to the AI client. Register only projects you intend to expose, keep credentials private, and review changes before accepting them. WebCodex can read and modify files in registered projects and run powerful project commands; read the [security model](SECURITY.md) before connecting sensitive projects.
-- **Linux x64/arm64** — local `share`, Server, and Runner workflows.
-- **macOS x64/arm64** — local `share` and Runner workflows.
-- **Windows x64/arm64** — CLI + Runner, local foreground Server, and explicit `webcodex share --tunnel cloudflare|openai|none`. Windows x64 can auto-manage the pinned Cloudflare Quick Tunnel binary; OpenAI `tunnel-client` is managed on both x64 and arm64. Cloudflare does not publish a Windows ARM64 artifact for the pinned release, so Windows ARM64 Cloudflare sharing requires a trusted explicit/PATH `cloudflared`. WebCodex-managed Windows Server services remain unsupported.
+## Platforms
-Windows and long-lived deployments are covered in [Deployment](docs/DEPLOYMENT.md) and [MCP](docs/MCP.md).
+| Platform | Quick Trial | Everyday setup |
+| --- | --- | --- |
+| Linux x64 / arm64 | `share` | Server + Runner |
+| macOS x64 / arm64 | `share` | Runner connected to a Server |
+| Windows x64 | `share` | Foreground Server + Runner |
+| Windows arm64 | `share` with an explicit supported tunnel option | Foreground Server + Runner |
-## Existing Servers and advanced setup
+The default managed Cloudflare trial is available on Linux, macOS, and Windows x64. Windows arm64 tunnel details and service limitations are in [Deployment](docs/DEPLOYMENT.md) and [MCP](docs/MCP.md).
-If someone already provides the WebCodex Server and connection credential, use that existing Server. For a normal personal installation, follow the [Full Setup guide](docs/PERSONAL_SETUP.md). Use [Deployment](docs/DEPLOYMENT.md) later for production hosting, multiple users, systemd/Docker, OAuth, proxies, and private CAs.
+## Documentation
-Those are follow-up operating concerns, not concepts a first-time user should have to learn before WebCodex works.
+**Get started:** [Quick Trial](docs/QUICK_START.md) · [Full Setup](docs/PERSONAL_SETUP.md) · [AI-assisted setup](docs/AI_ONBOARDING.md)
-## Documentation
+**Connect clients:** [MCP](docs/MCP.md) · [CLI](docs/CLI.md)
-- [Full Setup](docs/PERSONAL_SETUP.md) — recommended daily use: a regular Server + Runner + your projects
-- [Quick Trial](docs/QUICK_START.md) — temporarily try one repository with `share`
-- [MCP](docs/MCP.md) — ChatGPT, Claude, authentication choices, and MCP reference
-- [Deployment](docs/DEPLOYMENT.md) — production, self-hosting, and advanced operations
-- [Troubleshooting](docs/TROUBLESHOOTING.md) — connection and runtime problems
-- [CLI](docs/CLI.md) — command and credential reference
-- [AI-assisted setup](docs/AI_ONBOARDING.md) — have an AI agent help configure WebCodex
-- [Security](SECURITY.md) — security model and operational guidance
-- [Documentation index](docs/INDEX.md) — all user and contributor documentation
+**Operate safely:** [Security](SECURITY.md) · [Deployment](docs/DEPLOYMENT.md) · [Troubleshooting](docs/TROUBLESHOOTING.md)
-## Security
+**Understand the system:** [Architecture](docs/ARCHITECTURE.md) · [Authentication](docs/AUTH_MODEL.md) · [All documentation](docs/INDEX.md)
-WebCodex can read and modify files and execute commands inside configured project boundaries. Use version control, keep credentials out of prompts/logs/Git, and register only project roots the assistant should access. Read [SECURITY.md](SECURITY.md) for the complete model.
+## Build and contribute
-## Build from source
+The npm package is the normal installation path. To build the binaries from source:
```bash
cargo build --release --workspace --bins
export PATH="$PWD/target/release:$PATH"
```
-## Contributing
-
-Contributions are welcome, including contributions created with WebCodex itself or other coding agents. For bug reports, development workflow, and pull request guidance, see [CONTRIBUTING.md](CONTRIBUTING.md).
+See [Contributing](CONTRIBUTING.md) for development and pull request guidance.
## Acknowledgements
-Thanks to the [LINUX DO](https://linux.do/) community for its welcoming space for technical discussion and support for open-source sharing.
+Thanks to the [LINUX DO](https://linux.do/) community for technical discussion and support for open-source sharing.
## License
-Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).
+Apache License 2.0. See [LICENSE](LICENSE).
diff --git a/README.zh-CN.md b/README.zh-CN.md
index dca27d180..2d664a662 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,109 +1,99 @@
-# WebCodex
+
+Ask your assistant to inspect a repository, modify code, run tests, use Git, or investigate a failure. Your repository stays on the machine where it already lives; you do not need to move the project into a hosted workspace just to use an AI coding agent.
+
+## Start using WebCodex
-## Try one repository
+### Just trying it for a few minutes: temporary share
-From a repository you want an AI client to inspect:
+To quickly see whether WebCodex fits your workflow, run this inside one repository:
```bash
cd /path/to/your/repository
npx --yes @yyjeqhc/webcodex share
```
-This starts a **temporary, single-project, restricted trial**. Keep the command running, use the printed MCP connection values, and stop it to end the endpoint and credential. See the [Quick Trial](docs/QUICK_START.md) for prerequisites and ChatGPT connection steps.
+`share` starts a temporary, single-project WebCodex environment and prints the ChatGPT connection values. The endpoint and credential stop working when the command exits. It is intended for trials and short-lived sharing, not as the default full daily setup. See the [Quick Trial](docs/QUICK_START.md) for the exact steps.
-## Full setup
+### Everyday development: full WebCodex (recommended)
-For everyday development, run a regular **Server + Runner**. The Runner works where your repositories and toolchain already live; the Server gives your AI client an authenticated path to registered projects. This supports multiple projects and the full development workflow.
+If you want ChatGPT to keep using your real development environment, start with a **regular Server + Runner**. This is the full development experience: durable access to multiple projects plus project exploration, editing, Git, commands, tests, long-running work, and code navigation. Public HTTPS, Cloudflare Tunnel, and OpenAI Secure MCP Tunnel are only ways for ChatGPT to reach the Server; they do not switch you into a different restricted experience.
-Install the CLI with `npm install -g @yyjeqhc/webcodex`, then follow the [Full Setup guide](docs/PERSONAL_SETUP.md). A public HTTPS endpoint or tunnel is a way to reach the Server, not a replacement for the regular setup.
+For Windows or macOS, the recommended first path is **WebCodex Desktop + the official OpenAI Secure Tunnel**. Follow the [upstream Desktop installation guide](https://github.com/yyjeqhc/webcodex/blob/main/docs/desktop-install.md). For CLI, an existing Server, self-hosting, or advanced setup, use the [Full Setup guide](docs/PERSONAL_SETUP.md).
-## Why WebCodex
+### Download a release
-- **Work on the real repository.** The Runner operates in registered project directories on your machine, using the Git checkout you already have.
-- **Use the real toolchain.** Read and edit code, inspect Git, and run compilers, tests, formatters, and project commands within the configured boundaries.
-- **Keep long work observable.** Commands and checks that outlive a quick response continue as Jobs with bounded status and output you can inspect or stop.
-- **Keep work reviewable.** Project policy, guarded edits, Git diffs, validation results, and runtime evidence help you inspect what happened.
+The links below are **official upstream v0.4.1 releases**. They are newer than the source currently on this fork's `main` branch. Choose a Desktop installer for ordinary Windows/macOS use, or a native CLI archive for Server/Runner workflows. [View the release and checksums](https://github.com/yyjeqhc/webcodex/releases/tag/v0.4.1).
-## How it works
+| Platform | Desktop | CLI / Server / Runner |
+| --- | --- | --- |
+| Windows x64 | [Installer](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-desktop-v0.4.1-win32-x64-setup.exe) | [Archive](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-win32-x64.tar.gz) |
+| Windows arm64 | — | [Archive](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-win32-arm64.tar.gz) |
+| macOS Apple Silicon | [DMG](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-desktop-v0.4.1-darwin-arm64.dmg) | [Archive](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-darwin-arm64.tar.gz) |
+| macOS Intel | [DMG](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-desktop-v0.4.1-darwin-x64.dmg) | [Archive](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-darwin-x64.tar.gz) |
+| Linux x64 | — | [Archive](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-linux-x64.tar.gz) |
+| Linux arm64 | — | [Archive](https://github.com/yyjeqhc/webcodex/releases/download/v0.4.1/webcodex-v0.4.1-linux-arm64.tar.gz) |
+
+The npm installation path remains `npm install -g @yyjeqhc/webcodex` (Node.js 18+).
+
+## What can it do?
+
+- **Understand and edit code** — read, search, inspect, and make guarded changes inside configured projects.
+- **Use the real toolchain** — run commands, tests, formatters, compilers, and project-specific tooling on the machine that owns the repository.
+- **Work with Git** — inspect status and diffs while keeping repository operations visible and reviewable.
+- **Handle long-running work** — keep jobs observable instead of requiring one model turn to stay open indefinitely.
+- **Support human review** — use the Runtime Console, Workflow Session evidence, Jobs, and Git/diff review without a separate task/result acceptance subsystem.
-WebCodex is a self-hosted execution bridge. The AI client calls its Server through MCP; the Server authenticates and routes the request, and a Runner on the repository machine performs the work. The Server does not scan your filesystem for projects. For the detailed model, see [Architecture](docs/ARCHITECTURE.md).
+## Why WebCodex?
-## Security and control
+- **Your code stays on your machine.** The repository does not need to be copied into the chat service.
+- **The agent gets a real development environment.** It can use the same files, Git checkout, compilers, tests, and tools you already use.
+- **Work survives beyond a single request.** Long-running execution and evidence remain observable through WebCodex.
+- **Start temporary or run it long-term.** Use one-command sharing for a quick session, or connect machines to a self-hosted Server for a durable setup.
-Your repository stays on the machine that owns it. Tool results, including requested file excerpts, may be returned to the AI client. Register only projects you intend to expose, keep credentials private, and review changes before accepting them. WebCodex can read and modify files in registered projects and run powerful project commands; read the [security model](SECURITY.md) before connecting sensitive projects.
+## How it works
+
+```text
+AI client
+ |
+ | MCP / HTTPS
+ v
+WebCodex
+ |
+ v
+your machine
+ |
+ +-- repository
+ +-- Git
+ +-- compilers / tests / developer tools
+```
+
+For the internal Server/Runner architecture, protocol surfaces, and authority boundaries, see [Architecture](docs/ARCHITECTURE.md), [MCP](docs/MCP.md), and [Authentication](docs/AUTH_MODEL.md).
## Platforms
-| Platform | Quick Trial | Everyday setup |
-| --- | --- | --- |
-| Linux x64 / arm64 | `share` | Server + Runner |
-| macOS x64 / arm64 | `share` | Runner connected to a Server |
-| Windows x64 | `share` | Foreground Server + Runner |
-| Windows arm64 | `share` with an explicit supported tunnel option | Foreground Server + Runner |
+The platform capabilities below describe the official upstream release linked above.
-The default managed Cloudflare trial is available on Linux, macOS, and Windows x64. Windows arm64 tunnel details and service limitations are in [Deployment](docs/DEPLOYMENT.md) and [MCP](docs/MCP.md).
+- **Linux x64/arm64** — local `share`, Server, and Runner workflows.
+- **macOS x64/arm64** — Desktop local Server + Runner, OpenAI Secure Tunnel, local `share`, and standalone Runner workflows.
+- **Windows x64** — Desktop local Server + Runner with the official OpenAI Secure Tunnel, plus CLI + Runner, local foreground Server, and explicit `webcodex share --tunnel cloudflare|openai|none`.
+- **Windows arm64** — CLI + Runner, local foreground Server, and `share`; managed OpenAI `tunnel-client` is supported. The pinned Cloudflare release has no official Windows ARM64 artifact, so Cloudflare requires a trusted explicit/PATH `cloudflared`. The Desktop installer is currently Windows x64 only. WebCodex-managed Windows Server services remain unsupported outside Desktop's owned foreground runtime.
-## Documentation
+Windows and long-lived deployments are covered in [Deployment](docs/DEPLOYMENT.md) and [MCP](docs/MCP.md).
+
+## Existing Servers and advanced setup
-**Get started:** [Quick Trial](docs/QUICK_START.md) · [Full Setup](docs/PERSONAL_SETUP.md) · [AI-assisted setup](docs/AI_ONBOARDING.md)
+If someone already provides the WebCodex Server and connection credential, use that existing Server and follow the [Full Setup guide](docs/PERSONAL_SETUP.md). For a normal Windows/macOS personal installation, use the [upstream Desktop guide](https://github.com/yyjeqhc/webcodex/blob/main/docs/desktop-install.md). Use [Deployment](docs/DEPLOYMENT.md) only for production hosting, multiple users, systemd/Docker, OAuth, proxies, and private CAs.
-**Connect clients:** [MCP](docs/MCP.md) · [CLI](docs/CLI.md)
+Those are follow-up operating concerns, not concepts a first-time user should have to learn before WebCodex works.
-**Operate safely:** [Security](SECURITY.md) · [Deployment](docs/DEPLOYMENT.md) · [Troubleshooting](docs/TROUBLESHOOTING.md)
+## Documentation
-**Understand the system:** [Architecture](docs/ARCHITECTURE.md) · [Authentication](docs/AUTH_MODEL.md) · [All documentation](docs/INDEX.md)
+- [Upstream Desktop installation](https://github.com/yyjeqhc/webcodex/blob/main/docs/desktop-install.md) — recommended Windows/macOS path: Desktop + official OpenAI Secure Tunnel
+- [Using upstream Desktop](https://github.com/yyjeqhc/webcodex/blob/main/docs/desktop-guide.md) — projects, connections, activity, and background operation
+- [Full Setup](docs/PERSONAL_SETUP.md) — CLI, existing Server, Linux, and advanced regular Server + Runner setup
+- [Quick Trial](docs/QUICK_START.md) — temporarily try one repository with `share`
+- [MCP](docs/MCP.md) — ChatGPT, Claude, authentication choices, and MCP reference
+- [Deployment](docs/DEPLOYMENT.md) — production, self-hosting, and advanced operations
+- [Troubleshooting](docs/TROUBLESHOOTING.md) — connection and runtime problems
+- [CLI](docs/CLI.md) — command and credential reference
+- [AI-assisted setup](docs/AI_ONBOARDING.md) — have an AI agent help configure WebCodex
+- [Security](SECURITY.md) — security model and operational guidance
+- [Documentation index](docs/INDEX.md) — all user and contributor documentation
-## Build and contribute
+## Security
-The npm package is the normal installation path. To build the binaries from source:
+WebCodex can read and modify files and execute commands inside configured project boundaries. Use version control, keep credentials out of prompts/logs/Git, and register only project roots the assistant should access. Tool results, including requested file excerpts, may be returned to the AI client. Read [SECURITY.md](SECURITY.md) for the complete model.
+
+## Build from source
```bash
cargo build --release --workspace --bins
export PATH="$PWD/target/release:$PATH"
```
-See [Contributing](CONTRIBUTING.md) for development and pull request guidance.
+## Contributing
+
+Contributions are welcome, including contributions created with WebCodex itself or other coding agents. For bug reports, development workflow, and pull request guidance, see [CONTRIBUTING.md](CONTRIBUTING.md).
## Acknowledgements
-Thanks to the [LINUX DO](https://linux.do/) community for technical discussion and support for open-source sharing.
+Thanks to the [LINUX DO](https://linux.do/) community for its welcoming space for technical discussion and support for open-source sharing.
## License
-Apache License 2.0. See [LICENSE](LICENSE).
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 2d664a662..4f3e709cf 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -10,8 +10,8 @@
Ask your assistant to inspect a repository, modify code, run tests, use Git, or investigate a failure. Your repository stays on the machine where it already lives; you do not need to move the project into a hosted workspace just to use an AI coding agent.
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 4f3e709cf..9d4a3def3 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -14,9 +14,9 @@
+ 
+ 
