Expand README and refresh development docs

README.md

@@ -1,7 +1,75 @@
 # ACP adapter for Codex CLI
+
 [![npm version](https://img.shields.io/npm/v/%40agentclientprotocol%2Fcodex-acp)](https://www.npmjs.com/package/@agentclientprotocol/codex-acp)
 
+Use [OpenAI Codex](https://github.com/openai/codex) from [Agent Client Protocol](https://agentclientprotocol.com/) clients.
+
+`codex-acp` is a stdio ACP agent server. It starts the Codex App Server, translates ACP requests into Codex operations, and maps Codex events back into the client.
+
+## Features
+
+- ChatGPT, API key, and client-provided custom gateway authentication.
+- Model, reasoning effort, fast mode, approval, and sandbox mode configuration.
+- Text prompts, embedded context, images, resource links, and additional workspace directories.
+- Shell command, file change, permission request, MCP tool call, terminal output, reasoning, plan, web search, image generation, image view, token usage, and review events.
+- Client-provided MCP servers over command-based stdio config and HTTP transport.
+- Slash commands: `/status`, `/mcp`, `/skills`, `/review`, `/review-branch`, `/review-commit`, `/compact`, and `/logout`, as well as configured skills.
+
+## Installation
+
+Run the published package directly:
+
+```bash
+npx -y @agentclientprotocol/codex-acp
+```
+
+Or install it globally:
+
+```bash
+npm install -g @agentclientprotocol/codex-acp
+codex-acp --version
+```
+
+The npm package includes a compatible `@openai/codex` dependency. Set `CODEX_PATH` only when you want the adapter to run a different Codex binary:
+
+```bash
+CODEX_PATH=/path/to/codex npx -y @agentclientprotocol/codex-acp
+```
+
+## Authentication
+
+The adapter advertises ACP auth methods during initialization. Clients can authenticate with:
+
+- ChatGPT login.
+- OpenAI API key.
+- A custom OpenAI-compatible gateway, when the client opts in to the gateway auth capability.
+
+## Runtime options
+
+- `CODEX_PATH` - run a specific Codex executable instead of the bundled package dependency.
+- `CODEX_CONFIG` - JSON object merged into the Codex session config.
+- `MODEL_PROVIDER` - model provider to pass to Codex for new sessions.
+- `DEFAULT_AUTH_REQUEST` - ACP auth request JSON used when Codex requires authentication.
+- `INITIAL_AGENT_MODE` - initial mode id: `read-only`, `agent`, or `agent-full-access`.
+- `APP_SERVER_LOGS` - directory for adapter logs.
+
+## Development
+
+```bash
+npm install
+npm run start
+npm run typecheck
+npm test
+```
+
+Build standalone binaries in `dist/bin` with:
+
+```bash
+npm run bundle:all
+```
+
+See [readme-dev.md](readme-dev.md) for local client configuration, binary packaging, and Codex type regeneration.
 
-## Documentation
+## License
 
-- **[Development Guide](readme-dev.md)** - Setup, configuration, and building binaries
+By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.

readme-dev.md

@@ -1,28 +1,25 @@
-This package lists codex only as a dev dependency and requires the codex binary.
-It may not work with versions other than the one specified in package.json.
+This package uses the bundled `@openai/codex` dependency by default.
+Set `CODEX_PATH` to run a different Codex binary; versions other than the one specified in `package.json` may not be compatible.
 
 ### Quick start
 
 #### Develop on Windows?
+
 - Download and install [C++ redistributable package](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#latest-supported-redistributable-version)
 
-#### Adjust acp config for IDE
+#### Adjust ACP client config
 
 Run from sources
+
 1. Install dependencies `npm install`
-2. Adjust acp config for IDE
+2. Adjust ACP client config
+
 ```json
 {
   "agent_servers": {
     "Codex (app-server)": {
-      "command": "npx",
-      "args": [
-        "npm",
-        "run",
-        "start",
-        "--prefix",
-        "/path/to/project/"
-      ],
+      "command": "npm",
+      "args": ["run", "start", "--prefix", "/path/to/project/"],
       "env": {
         "CODEX_PATH": "node_modules/.bin/codex",
         "APP_SERVER_LOGS": "optional/path/to/existing/log/directory"
@@ -33,17 +30,19 @@ Run from sources
 ```
 
 Run from binaries
-1. Download acp-server binary archive from https://github.com/JetBrains/codex-acp/tags
+
+1. Download a `codex-acp-<platform>.zip` archive from https://github.com/agentclientprotocol/codex-acp/releases
 2. Unzip the archive:
    ```bash
    unzip codex-acp-<platform>.zip
    ```
-3. Adjust acp config for IDE
+3. Adjust ACP client config
+
 ```json
 {
   "agent_servers": {
     "Codex (app-server)": {
-      "command": "/path/to/acp-server",
+      "command": "/path/to/codex-acp",
       "env": {
         "CODEX_PATH": "/path/to/codex"
       }