relmio 0.5.0 → 0.7.0

package/docs/getting-started.md

@@ -0,0 +1,38 @@
+# Getting started
+
+Relmio gives you two intentionally separate paths:
+
+| Need | Use | Credential |
+| --- | --- | --- |
+| An OpenAI-compatible local endpoint | Local OpenAI API gateway (`/v1`) | Your OpenAI Platform API key |
+| A trusted native Codex integration | Codex App Server (JSON-RPC over WebSocket) | ChatGPT sign-in and a local capability |
+| A small local chat backend | Codex Chat Adapter (`POST /chat`) | ChatGPT sign-in and a local bearer credential |
+| An n8n bridge on a VPS | The separate n8n sidecar | Your locally created ChatGPT sign-in file |
+
+ChatGPT sign-in is never converted into an OpenAI Platform API key. The Codex
+options are experimental and are not generic `/v1` services.
+
+## Install
+
+On macOS, Linux, WSL, or Git Bash, start the local wizard with:
+
+```bash
+npx --yes --ignore-scripts relmio@latest
+```
+
+The wizard prints a private loopback URL, verifies Docker before it changes
+anything, and asks for final confirmation before remote VPS writes. It binds
+local endpoints to `127.0.0.1`, never to a LAN interface.
+
+For installation options and prerequisites, see the [package
+README](https://www.npmjs.com/package/relmio). For a VPS/n8n walkthrough, see
+[VPS and n8n](./vps-and-n8n.md).
+
+## Choose the next guide
+
+- [Local endpoints](./local-endpoints.md) for the local gateway, Codex App
+  Server, or Chat Adapter.
+- [Troubleshooting](./troubleshooting.md) when Docker, authentication, or a
+  local image build stops the flow.
+- [Security](./security.md) for credential and trust boundaries.
+- [Reference](./reference.md) for test commands and protocol notes.

package/docs/local-endpoints-spec.md

@@ -2,7 +2,8 @@
 
 ## Status
 
-Approved for implementation on `codex/local-openai-endpoint` on 2026-08-13.
+Originally approved on 2026-08-13 and extended for the additive
+`codex/local-codex-chat-adapter` target on 2026-08-15.
 
 This spec is product and engineering guidance based on the current official
 OpenAI documentation. It is not a legal opinion. Relmio must not claim that
@@ -13,16 +14,19 @@ OpenAI has endorsed, certified, or pre-approved the project.
 Add a local Docker installation path to the Relmio browser wizard without
 weakening the existing VPS/n8n safety boundary.
 
-Relmio offers two intentionally different local providers:
+Relmio offers three intentionally different local client contracts:
 
 1. `openai-api` is an OpenAI-compatible HTTP gateway backed by the user's
    OpenAI Platform API key.
 2. `codex-chatgpt` is the official Codex App Server protocol backed by the
    user's ChatGPT/Codex sign-in.
+3. `codex-chat` is a small Relmio-specific HTTP chat adapter backed by the
+   same official App Server lifecycle and ChatGPT/Codex sign-in.
 
 Relmio must never exchange, translate, or present a ChatGPT/Codex credential as
-a general OpenAI API bearer credential. The Codex provider must not expose an
-OpenAI-shaped `/v1` compatibility surface.
+a general OpenAI API bearer credential. Neither Codex target may expose an
+OpenAI-shaped `/v1` compatibility surface. The adapter owns only its narrow
+`POST /chat` contract.
 
 ## Official-source boundary
 
@@ -53,7 +57,7 @@ The existing VPS/n8n wizard remains a separate legacy setup path. The wizard
 landing experience adds a prominent **Local endpoints** option which opens a
 dedicated local installer.
 
-The local installer starts with two provider cards:
+The local installer starts with three provider cards:
 
 ### OpenAI API
 
@@ -81,7 +85,21 @@ The local installer starts with two provider cards:
   - An explicit statement that this is Codex JSON-RPC, not OpenAI `/v1`
   - An explicit experimental/non-production notice
 
-Both flows show a review screen and require a final confirmation before any
+### Codex Chat Adapter
+
+- Label: **Codex Chat Adapter — development backends**
+- Default HTTP port: `14501`
+- Uses the same pinned official Codex CLI and official device-code sign-in.
+- Result:
+  - Endpoint: `http://127.0.0.1:<port>`
+  - A newly generated Relmio bearer token, displayed once
+  - A device-code sign-in action
+  - An explicit server-side-only statement
+  - An explicit statement that `POST /chat` is Relmio-specific, not OpenAI
+    `/v1`
+  - An explicit experimental/non-production notice
+
+All three flows show a review screen and require a final confirmation before any
 filesystem or Docker write.
 
 This release supports macOS, Linux, and Linux under WSL2. Native Windows is
@@ -94,6 +112,33 @@ say so, and the installer must reject native Windows before any write.
 Every wizard API route continues to require the existing `X-Setup-Token` and
 same-origin protections.
 
+### Chat Adapter tester APIs
+
+The tester is available only after a live `codex-chat` installation reaches the
+Ready screen. Sanitized preview mode rejects all three routes. Each route uses
+the same `POST` exact-Origin and `X-Setup-Token` protections as the rest of
+the local wizard.
+
+- `POST /api/local/chat-test/key` returns only `keyId`, an RSA public JWK,
+  `RSA-OAEP-256`, and an expiry. Its private key remains only in the local
+  server's bounded, in-memory tester-session map.
+- `POST /api/local/chat-test/message` accepts a literal loopback adapter base
+  URL, `keyId`, RSA-OAEP SHA-256 ciphertext, a bounded input, and an optional
+  bounded conversation ID. It returns only validated `conversationId` and
+  `output`.
+- `POST /api/local/chat-test/reset` invalidates the specified in-memory key.
+
+The browser sends no adapter request and stores no tester data in browser
+storage. It clears the plaintext credential input before it awaits key issuance
+or encryption, then retains ciphertext and key ID only in page memory. The
+server does not retain prompts or transcript beyond a single request.
+
+The local proxy accepts only `http://127.0.0.1:<1-65535>` with an optional
+trailing slash. It rejects DNS names, IPv6, credentials, query strings,
+fragments, paths, redirects, malformed JSON, oversized request/response data,
+expiry, and concurrent use. It appends `/chat`, uses a bounded timeout, sends
+no `Origin` header, and returns generic redacted failures.
+
 ### `GET /api/local/docker/status`
 
 Returns local Docker and Compose availability. It never returns filesystem
@@ -143,7 +188,9 @@ is released in a `finally` path after both success and failure.
 ### `POST /api/local/codex/login`
 
 Starts an official Codex App Server device-code login through a one-shot stdio
-App Server process attached to the same persistent Codex home volume.
+App Server process attached to the selected Codex target's persistent home
+volume. The request identifies either `codex-chatgpt` or `codex-chat`;
+every other target is rejected before process construction.
 
 Every login attempt resolves the managed Codex directory and attests its
 schema-2 marker and matching Docker resources, even in a fresh wizard process.
@@ -249,12 +296,77 @@ The host mapping is exactly `127.0.0.1:<selected-port>:4500`.
   The capability is therefore password-equivalent and limited to a trusted,
   same-owner native client.
 
+## Codex Chat Adapter contract
+
+The adapter container starts a dependency-free Node HTTP service and launches
+the pinned official `codex app-server --strict-config --stdio` process only
+for a bounded chat operation. It uses the target's private Codex home and
+workspace volumes and never exposes the App Server transport on the host.
+
+### Listener and authentication
+
+- Container listener: `0.0.0.0:14501`
+- Host publication: `127.0.0.1:<selected-port>:14501`
+- `GET /health` is the only unauthenticated, non-forwarding route.
+- Every route except `GET /health` requires exactly one
+  `Authorization: Bearer <Relmio capability>` header.
+- Only the SHA-256 verifier is persisted and comparison is constant-time.
+- Requests with an `Origin` header are rejected and no CORS permission is
+  emitted.
+
+### Request and response
+
+The accepted JSON object contains only:
+
+```json
+{
+  "input": "Required nonempty conversational input",
+  "conversationId": "Optional App Server thread ID"
+}
+```
+
+The successful response contains only:
+
+```json
+{
+  "conversationId": "The started or resumed thread ID",
+  "output": "The authoritative final agent message"
+}
+```
+
+The adapter performs `initialize`, `initialized`, `thread/start` or
+`thread/resume`, and `turn/start`. The turn is constrained to the empty
+private workspace with a read-only sandbox. Its filesystem policy denies root
+by default, permits only Codex's minimal runtime paths and `/workspace`, and
+explicitly denies `/home/node/.codex`; turn network access is disabled. The
+instruction not to inspect or modify files, run commands, call tools, or access
+external resources remains defense in depth, not the credential boundary.
+`item/completed` agent-message text is authoritative; bounded deltas are kept
+separate by `itemId`, with only the most recent item's text used as a
+compatibility fallback. Success requires `turn/completed` with
+`status: completed`.
+
+### Resource and failure bounds
+
+- Header, body, input, conversation ID, stdout, stderr, line, and output sizes
+  are bounded.
+- Concurrent chats, turn duration, child-process termination grace, and the
+  final wait for an unreaped process are bounded. The concurrency slot remains
+  occupied until the helper closes or that final bound expires.
+- Client disconnect, timeout, malformed protocol, overflow, and failed turns
+  terminate the helper.
+- HTTP errors are generic and never include App Server output, process errors,
+  ChatGPT credentials, or stderr.
+- Installation and credential rotation verify readiness/authentication without
+  starting a model turn or requiring sign-in before the device-code step.
+
 ## Local filesystem and process boundary
 
 Managed roots:
 
 - `~/.relmio/local/openai-api`
 - `~/.relmio/local/codex-chatgpt`
+- `~/.relmio/local/codex-chat`
 
 `RELMIO_HOME` may replace `~/.relmio` for testing or advanced use, but it must
 be an absolute path whose final component is `.relmio`.
@@ -282,7 +394,7 @@ Controls:
 
 ## Container hardening
 
-Both long-running endpoint services:
+All three long-running endpoint services:
 
 - run as a non-root user;
 - set `no-new-privileges`;
@@ -326,26 +438,29 @@ gateway; it is removed immediately after seeding.
 | LAN/public exposure | literal `127.0.0.1` Compose binding plus template and runtime inspection tests |
 | Local cross-site request | bearer capability, exact Origin allowlist, strict preflight, Host validation |
 | Upstream key disclosure | separate local/upstream credentials, stdin-seeded private named volume, redacted errors, no body logging |
-| ChatGPT token repurposing | official App Server only; no `/v1` adapter for Codex |
+| ChatGPT token repurposing | official App Server lifecycle only; the adapter is Relmio-specific and exposes no `/v1` route |
 | Command injection | validated scalar values, spawn argument arrays, no shell |
 | Managed-path takeover | refuse unmanaged roots and every symlinked component |
 | Streaming resource exhaustion | header/body/concurrency/time bounds and backpressure |
 | Docker privilege compromise | document Docker control as a privileged local boundary; mount no Docker socket into services |
 | Secret recovery from UI | show capabilities once; never use browser storage; rotate on reinstall |
-| Codex capability compromise | explicit credential-equivalent warning; trusted same-owner native clients only; private container volumes and no host mounts |
+| Codex capability compromise | explicit trust warning; target-specific least-privilege interfaces, private container volumes, no host mounts, and server-side-only adapter use |
+| Model-induced credential read | root-deny model filesystem profile, minimal runtime read allowlist, explicit `/home/node/.codex` deny, empty private workspace, and no turn network access |
 
 ## Acceptance criteria
 
-- The browser wizard visibly offers both local providers and the legacy VPS
+- The browser wizard visibly offers all three local contracts and the legacy VPS
   path remains separate.
-- Platform keys are accepted only by `openai-api`; ChatGPT auth is accepted only
-  by official App Server.
+- Platform keys are accepted only by `openai-api`; both Codex targets use only
+  official App Server-backed ChatGPT authentication.
 - Generated Compose files publish only literal loopback bindings.
 - Every non-health gateway operation that can reach OpenAI and every App Server
   WebSocket handshake is capability-authenticated; exact-origin CORS preflight
   is a non-forwarding metadata exception.
 - Gateway unit/integration tests cover auth, origins, Host validation,
   streaming, cancellation, upstream errors, and secret redaction.
+- Adapter tests cover auth, Origin rejection, request/protocol validation,
+  process cleanup, bounds, concurrency, final-output selection, and redaction.
 - Local installer tests prove confirmation, unmanaged-root refusal, symlink
   refusal, port collision behavior, exact Docker arguments, file modes, and
   absence of n8n commands.

package/docs/local-endpoints.md

@@ -1,33 +1,46 @@
 # Local Docker endpoints
 
 Relmio can install a provider endpoint in Docker on the same computer as your
-app. The local installer is deliberately split into two protocols with two
-different authentication methods:
+app. The local installer keeps three explicit client contracts across two
+different provider authentication methods:
 
 | Wizard option | Local interface | Upstream sign-in | Intended client |
 |---|---|---|---|
 | **OpenAI API: compatible clients** | OpenAI-compatible HTTP under `/v1` | Server-side OpenAI Platform API key only | A private local app, SDK, or same-owner development web app |
 | **Codex with ChatGPT: agent clients** | Official Codex App Server JSON-RPC over WebSocket | ChatGPT sign-in through Codex | A trusted native Codex/App Server client owned by the same person |
+| **Codex Chat Adapter: development backends** | Relmio-specific HTTP `POST /chat` | ChatGPT sign-in through Codex | A trusted local backend or development server owned by the same person |
 
 Relmio does not exchange or translate a ChatGPT OAuth/session credential into
-an OpenAI-compatible `/v1` bearer credential. The Codex option keeps Codex's
-thread, turn, approval, and streamed-event semantics instead of pretending to
-be the OpenAI API.
+an OpenAI-compatible `/v1` bearer credential. The native Codex option keeps
+Codex's thread, turn, approval, and streamed-event semantics. The adapter
+translates only a small Relmio-owned `/chat` contract into that official
+protocol; it does not imitate the OpenAI API.
 
 This is a documentation-backed engineering boundary, not legal advice or a
 guarantee that a particular account or use case is permitted. Review the
 agreements and policies that apply to your account.
 
+## ChatGPT/Codex sign-in lifetime
+
+ChatGPT/Codex sign-in tokens expire, but the official Codex client refreshes
+them automatically during active use before they expire, so active sessions
+usually continue without another browser login. The official [OpenAI
+authentication documentation](https://learn.chatgpt.com/docs/auth) does not
+publish a fixed 10-day lifetime; do not plan around one. This provider
+credential is separate from Relmio's local capability, which remains valid
+until you rotate it.
+
 ## Requirements
 
 - macOS, Linux, or Linux under WSL2. Native Windows is not supported because
   this release depends on POSIX owner-only directory and file permissions for
   local credentials.
 - Docker Engine or Docker Desktop with Docker Compose v2 on the local computer
-- A free loopback port (`12435` by default for OpenAI API or `14500` for Codex)
+- A free loopback port (`12435` for OpenAI API, `14500` for native Codex,
+  or `14501` for the Codex Chat Adapter by default)
 - One of these provider credentials:
   - an OpenAI Platform API key for the OpenAI-compatible endpoint; or
-  - a ChatGPT account eligible for Codex for the App Server endpoint
+  - a ChatGPT account eligible for Codex for either Codex target
 - A trusted local app that can keep the Relmio capability secret
 
 The local path does not need a VPS or SSH access and does not modify the
@@ -37,7 +50,8 @@ project on the local computer.
 ## Install with the browser wizard
 
 1. Start Relmio on the computer that will run the endpoint. Use one of the
-   commands in the [README](../README.md#quick-install), or run:
+   commands on the [hosted install page](https://relmio.vercel.app/install),
+   or run:
 
    ```bash
    npx --yes --ignore-scripts relmio@latest
@@ -45,8 +59,8 @@ project on the local computer.
 
 2. Open the one-time local wizard URL printed in the terminal and choose
    **Local endpoints**.
-3. Choose **OpenAI API: compatible clients** or **Codex with ChatGPT: agent
-   clients**.
+3. Choose **OpenAI API: compatible clients**, **Codex with ChatGPT: agent
+   clients**, or **Codex Chat Adapter: development backends**.
 4. Keep the default port or select another unused local port. For the OpenAI
    API option, add any browser origins that must be allowed and enter your
    Platform API key.
@@ -64,6 +78,7 @@ inside its managed path. Its local files live under:
 ```text
 ~/.relmio/local/openai-api
 ~/.relmio/local/codex-chatgpt
+~/.relmio/local/codex-chat
 ```
 
 Advanced or test environments can set `RELMIO_HOME` before starting the
@@ -81,8 +96,9 @@ To replace only the credential used by your local client, select **Rotate client
 credential** on the installed endpoint's Ready screen. Relmio first stages and
 shows the new one-time capability while the previous capability remains active.
 It then updates and validates the managed Compose configuration, recreates only
-the attested service, and verifies the new bearer against `/v1/models` or the
-authenticated Codex WebSocket handshake before reporting success.
+the attested service, and verifies the new bearer against `/v1/models`, the
+authenticated Codex WebSocket handshake, or the adapter's authenticated probe
+before reporting success.
 
 This client-only rotation preserves the upstream Platform API key in its private
 named volume and preserves the Codex home and workspace volumes. If activation
@@ -97,8 +113,8 @@ managed update. Relmio verifies the marker and Docker resource ownership and
 reuses the installation's unique Compose identity. For `openai-api`, provide the
 current or replacement Platform API key during that full update; Relmio reseeds
 its private named volume independently from the local client capability. A full
-`codex-chatgpt` update retains the private Codex home and workspace volumes unless
-you explicitly delete them.
+`codex-chatgpt` or `codex-chat` update retains the private Codex home and
+workspace volumes unless you explicitly delete them.
 
 Do not hand-edit the marker, Compose file, credential volume, or verifier. If
 the marker or resource labels do not attest as one Relmio installation, the
@@ -124,8 +140,9 @@ For a quick private test:
 
 ```bash
 export RELMIO_LOCAL_KEY="<capability shown once by the wizard>"
-curl http://127.0.0.1:12435/v1/models \
-  -H "Authorization: Bearer $RELMIO_LOCAL_KEY"
+printf 'Authorization: Bearer %s\n' "$RELMIO_LOCAL_KEY" |
+  curl http://127.0.0.1:12435/v1/models --header @-
+unset RELMIO_LOCAL_KEY
 ```
 
 The upstream key is passed only over stdin to a transient, network-disabled
@@ -174,12 +191,15 @@ official verification URL, enter the device code, and complete authentication.
 Relmio starts the login through the official Codex App Server account method;
 it never returns the resulting ChatGPT access or refresh tokens.
 
-A compatible Codex CLI can connect like this:
+A compatible Codex CLI can connect like this. Read the capability without
+putting it in the command line:
 
 ```bash
-export CODEX_REMOTE_TOKEN="<capability shown once by the wizard>"
+read -r -s CODEX_REMOTE_TOKEN
+printf '\n'
 codex --remote ws://127.0.0.1:14500 \
   --remote-auth-token-env CODEX_REMOTE_TOKEN
+unset CODEX_REMOTE_TOKEN
 ```
 
 This is not an OpenAI `/v1` endpoint. A client must implement the official
@@ -205,9 +225,87 @@ workspace and credential volume. The service receives no host directory,
 Docker socket, SSH key, browser profile, or host home-directory mount. This
 reduces host exposure; it does not make an untrusted App Server client safe.
 
+## Codex Chat Adapter: development backends
+
+The adapter result screen provides:
+
+```text
+Endpoint: http://127.0.0.1:14501
+Authorization: Bearer <the Relmio capability shown once by the wizard>
+Protocol: Relmio Codex Chat HTTP
+```
+
+After completing the same official Codex device-code sign-in, a local backend
+can start a conversation with. Read the bearer rather than placing it in a
+shell command:
+
+```bash
+read -r -s RELMIO_CODEX_CHAT_KEY
+printf '\n'
+printf 'Authorization: Bearer %s\n' "$RELMIO_CODEX_CHAT_KEY" |
+  curl --fail-with-body --silent --show-error \
+    --request POST http://127.0.0.1:14501/chat \
+    --header @- \
+    --header "Content-Type: application/json" \
+    --data '{"input":"Reply with a short hello."}'
+unset RELMIO_CODEX_CHAT_KEY
+```
+
+The response contains only the App Server thread ID and final conversational
+text:
+
+```json
+{
+  "conversationId": "thread-id-from-the-first-response",
+  "output": "Hello!"
+}
+```
+
+Send that `conversationId` with the next `input` to continue the same
+conversation. The adapter initializes the official App Server, starts or
+resumes the thread, runs a read-only conversational turn, and returns the
+authoritative final agent message. The model sandbox has no network access and
+uses a root-deny filesystem policy that reads only Codex's minimal runtime
+paths and the empty private workspace. It explicitly denies
+`/home/node/.codex`, the private volume containing the ChatGPT session.
+
+This route is deliberately not `/v1/chat/completions` or `/v1/responses`.
+OpenAI SDKs and tools that require those schemas still need the Platform-backed
+OpenAI API target. The adapter rejects every request carrying an `Origin`
+header and sends no CORS permission, so browser JavaScript must not call it
+directly. Keep the bearer in a trusted local backend or development server and
+let the browser call that server's own session-aware route.
+
+The adapter is experimental because it depends on the experimental App Server
+interface. It is loopback-only, single-owner development tooling, not a hosted,
+LAN, multi-user, or production service. It enforces bounded request bodies,
+output, concurrency, process lifetime, and sanitized failures, but those
+controls do not create a general-purpose API entitlement.
+
+### In-wizard Chat Adapter tester
+
+The Ready screen for an installed Chat Adapter includes a narrow local tester.
+It is intended for a literal `http://127.0.0.1:PORT` adapter address only. The
+browser never calls the adapter: it calls the local wizard's existing
+same-origin, `X-Setup-Token` protected APIs, and the wizard makes the
+server-side `POST /chat` request without an `Origin` header.
+
+When the user secures the displayed client credential, the browser clears the
+input and encrypts it with the tester's short-lived RSA-OAEP SHA-256 public
+key. The private key exists only in local server memory, expires after a few
+minutes, has a bounded session count, and can be invalidated with **Forget
+tester**. The browser retains only ciphertext and key ID for the test session;
+it keeps prompts and transcript only in current-page memory and DOM.
+
+This reduces accidental credential transit and storage exposure. It is not
+encryption at rest or end-to-end encryption, and it cannot protect against a
+compromised browser, extension, or local machine. The tester rejects redirects,
+non-loopback URLs, malformed or oversized data, concurrent key use, and
+adapter failures with redacted messages.
+
 ## Network and container boundary
 
-Both local Compose projects publish exactly one host mapping:
+Every local Compose project publishes exactly one host mapping:
 
 ```text
 127.0.0.1:<selected-port>:<container-port>
@@ -216,12 +314,13 @@ Both local Compose projects publish exactly one host mapping:
 They are not available through the computer's LAN address. Each long-running
 service runs as a non-root user, drops Linux capabilities, sets
 `no-new-privileges`, uses a read-only root filesystem, and has bounded
-temporary storage and resource limits. Neither service mounts the Docker
+temporary storage and resource limits. None of the services mounts the Docker
 socket or a general host directory. The one-shot OpenAI seed helper has no
 network, port, or logs and retains only `CHOWN` while running as root long
 enough to atomically set ownership on the volume entry.
 The OpenAI gateway receives only its private API-key named volume, mounted
-read-only; Codex receives no host path and uses separate private named volumes.
+read-only; both Codex targets receive no host path and use target-specific
+private named volumes.
 
 The loopback binding and capability are complementary controls. Other
 processes running as the same local user may still be able to reach a loopback
@@ -244,7 +343,8 @@ literal values only after confirming all of these conditions:
 In every example, manually replace each angle-bracket placeholder with the
 already-validated literal. Do not use `eval`, source the JSON, or construct a
 Docker command from unvalidated marker text. The only valid service name is
-`gateway` for `openai-api` or `codex` for `codex-chatgpt`.
+`gateway` for `openai-api`, `codex` for `codex-chatgpt`, or `codex-chat`
+for `codex-chat`.
 
 ### Recover from a failed install
 
@@ -285,7 +385,7 @@ service:
 docker --host <dockerHost> compose \
   --project-name <projectName> \
   --file <absolute-managed-compose> \
-  rm --stop --force <gateway-or-codex>
+  rm --stop --force <gateway-or-codex-or-codex-chat>
 ```
 
 This recovery command does not target other services, remove the project
@@ -344,7 +444,8 @@ docker --host <dockerHost> compose \
 `--volumes` irreversibly deletes the managed Codex home and workspace volumes,
 including the container's ChatGPT credentials. After Docker confirms the
 matching resources are gone, you may remove only the exact
-`~/.relmio/local/codex-chatgpt` managed directory through your file manager.
+`~/.relmio/local/codex-chatgpt` or `~/.relmio/local/codex-chat` managed
+directory for the target you verified through your file manager.
 
 ## Troubleshooting
 
@@ -358,8 +459,9 @@ matching resources are gone, you may remove only the exact
 - **Browser request rejected:** enter the exact page origin, including scheme
   and port, then update the managed endpoint. Wildcards are intentionally not
   supported.
-- **Browser cannot connect to Codex:** this is expected. App Server's raw
-  WebSocket is for trusted native clients, not browser-origin connections.
+- **Browser cannot connect to Codex:** this is expected. Both Codex targets
+  reject browser-origin requests. Use the raw App Server from a trusted native
+  client or keep the Chat Adapter bearer in a local backend.
 - **Codex reports signed out:** repeat the device-code sign-in in the local
   wizard. Never copy a Codex credential file between users.
 - **Native Windows:** this local Docker feature is unsupported. Run Relmio in a
@@ -373,6 +475,7 @@ credentials and Codex/ChatGPT authentication:
 
 - [OpenAI API authentication](https://developers.openai.com/api/reference/overview#authentication)
 - [Codex authentication](https://learn.chatgpt.com/docs/auth)
+- [Codex permission profiles](https://learn.chatgpt.com/docs/permissions)
 - [Codex App Server protocol and WebSocket limitations](https://learn.chatgpt.com/docs/app-server)
 - [Codex for Open Source program terms](https://learn.chatgpt.com/docs/codex-for-oss-terms)
 

package/docs/reference.md

@@ -0,0 +1,77 @@
+# Reference
+
+## Chat Adapter test commands
+
+The experimental Chat Adapter is a loopback-only, Relmio-specific `POST /chat`
+service for trusted local backends or development servers. It is not OpenAI
+`/v1` and it rejects browser `Origin` headers.
+
+Set the endpoint, then read the one-time credential without typing the literal
+credential into shell history:
+
+```bash
+export RELMIO_CHAT_BASE_URL="http://127.0.0.1:14501"
+read -r -s RELMIO_CHAT_CLIENT_CREDENTIAL
+printf '\n'
+```
+
+Start a conversation:
+
+```bash
+printf 'Authorization: Bearer %s\n' "$RELMIO_CHAT_CLIENT_CREDENTIAL" |
+  curl --fail-with-body --silent --show-error \
+    --request POST "$RELMIO_CHAT_BASE_URL/chat" \
+    --header @- \
+    --header "Content-Type: application/json" \
+    --data '{"input":"Reply with exactly: adapter works"}'
+```
+
+Copy the returned `conversationId`, then send a continuation:
+
+```bash
+export RELMIO_CONVERSATION_ID="CONVERSATION_ID_FROM_THE_PREVIOUS_RESPONSE"
+printf 'Authorization: Bearer %s\n' "$RELMIO_CHAT_CLIENT_CREDENTIAL" |
+  curl --fail-with-body --silent --show-error \
+    --request POST "$RELMIO_CHAT_BASE_URL/chat" \
+    --header @- \
+    --header "Content-Type: application/json" \
+    --data "{\"input\":\"Continue with one short sentence.\",\"conversationId\":\"$RELMIO_CONVERSATION_ID\"}"
+```
+
+Unset the shell credential when finished:
+
+```bash
+unset RELMIO_CHAT_CLIENT_CREDENTIAL
+```
+
+## Raw Codex App Server command
+
+The raw Codex App Server transport is JSON-RPC over WebSocket, experimental,
+and high-trust. It is for trusted native clients only; it is not an
+OpenAI-compatible `/v1` endpoint. Read the one-time local capability into a
+named environment variable rather than placing it in the command:
+
+```bash
+read -r -s RELMIO_CODEX_CLIENT_CREDENTIAL
+printf '\n'
+codex --remote ws://127.0.0.1:14500 \
+  --remote-auth-token-env RELMIO_CODEX_CLIENT_CREDENTIAL
+unset RELMIO_CODEX_CLIENT_CREDENTIAL
+```
+
+Keep that capability private. A trusted Codex client can control the isolated
+container and may be able to recover its ChatGPT session credential.
+
+## Local wizard tester API
+
+The browser never contacts the adapter directly. While the local wizard is
+running, its same-origin, `X-Setup-Token` protected APIs are:
+
+| Method | Route | Purpose |
+| --- | --- | --- |
+| `POST` | `/api/local/chat-test/key` | Issue one ephemeral RSA-OAEP public key |
+| `POST` | `/api/local/chat-test/message` | Send encrypted credential and one bounded chat turn |
+| `POST` | `/api/local/chat-test/reset` | Invalidate the tester key and clear the browser transcript |
+
+The local proxy accepts only a literal `http://127.0.0.1:PORT` adapter base
+URL and appends `/chat` itself.