codexgpt 1.0.0

package/DOMAIN_SETUP.md

@@ -0,0 +1,275 @@
+# CodexGPT: Windows + Cloudflare Tunnel + Custom Domain
+
+This guide describes the preferred self-hosted deployment for CodexGPT:
+
+```text
+ChatGPT
+  -> HTTPS
+mcp.example.com
+  -> Cloudflare DNS / TLS / Tunnel
+127.0.0.1:8787
+  -> CodexGPT
+  -> one local repository
+```
+
+The design does not require WSL or a third-party Remote MCP relay. Cloudflare provides DNS, TLS, and inbound tunnel transport only. Authorization and workspace policy remain enforced by CodexGPT on the Windows machine.
+
+## Security properties
+
+The recommended deployment has these properties:
+
+- CodexGPT listens on `127.0.0.1`, not a LAN or public interface.
+- `cloudflared` creates an outbound connection to Cloudflare.
+- TCP port 8787 is not opened on the router or exposed directly through Windows Firewall.
+- ChatGPT uses a stable HTTPS hostname such as `mcp.example.com`.
+- The `/mcp` endpoint requires a CodexGPT token.
+- The Cloudflare Tunnel credential and CodexGPT MCP token are separate secrets.
+- The ingress configuration has a final deny rule.
+- Logs and screenshots must not contain the complete tokenized Server URL.
+
+Cloudflare Tunnel does not replace CodexGPT authorization, permission profiles, local approvals, or operating-system isolation. Safe Bash is a command filter, not a sandbox.
+
+## Requirements
+
+- A domain managed by Cloudflare DNS
+- Windows 10 or Windows 11
+- Node.js 20+
+- CodexGPT installed globally
+- `cloudflared` installed by CodexGPT or available on `PATH`
+
+```powershell
+npm install -g codexgpt
+codexgpt install-cloudflared
+codexgpt doctor
+```
+
+CodexGPT installs the verified `cloudflared.exe` under `%USERPROFILE%\.codexgpt\bin` for the supported default path.
+
+## Option A: locally managed named tunnel
+
+This path stores a tunnel credentials JSON file on the local machine.
+
+### 1. Authenticate Cloudflare
+
+```powershell
+cloudflared tunnel login
+```
+
+A browser opens. Select the Cloudflare zone that contains your domain.
+
+### 2. Create the tunnel
+
+```powershell
+cloudflared tunnel create codexgpt
+```
+
+Record the tunnel UUID printed by `cloudflared`.
+
+### 3. Route DNS
+
+```powershell
+cloudflared tunnel route dns codexgpt mcp.example.com
+```
+
+Use a dedicated subdomain. Do not use the apex domain for the MCP endpoint.
+
+### 4. Create the Cloudflare configuration
+
+Create `%USERPROFILE%\.cloudflared\config.yml`:
+
+```yaml
+tunnel: YOUR-TUNNEL-UUID
+credentials-file: C:\Users\YOUR-NAME\.cloudflared\YOUR-TUNNEL-UUID.json
+
+ingress:
+  - hostname: mcp.example.com
+    service: http://127.0.0.1:8787
+    originRequest:
+      httpHostHeader: mcp.example.com
+      connectTimeout: 10s
+      noHappyEyeballs: false
+  - service: http_status:404
+```
+
+The final `http_status:404` rule is mandatory. It prevents unmatched hostnames from being forwarded to the local service.
+
+Validate the configuration:
+
+```powershell
+cloudflared tunnel ingress validate
+cloudflared tunnel ingress rule https://mcp.example.com/mcp
+```
+
+### 5. Start CodexGPT
+
+Generate a long random CodexGPT token. One PowerShell option is:
+
+```powershell
+$bytes = New-Object byte[] 32
+[System.Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
+$token = [Convert]::ToHexString($bytes).ToLowerInvariant()
+```
+
+Start the stable endpoint:
+
+```powershell
+codexgpt stable `
+  --root D:\Dev\your-repo `
+  --hostname mcp.example.com `
+  --tunnel-name codexgpt `
+  --cloudflare-config "$env:USERPROFILE\.cloudflared\config.yml" `
+  --token $token `
+  --bash safe
+```
+
+CodexGPT binds the origin to loopback by default. Do not pass `--host 0.0.0.0` for this deployment.
+
+### 6. Add the connection to ChatGPT
+
+CodexGPT attempts to copy a complete URL similar to the following, but keeps the credential-bearing URL out of startup logs by default:
+
+```text
+https://mcp.example.com/mcp?codexgpt_token=...
+```
+
+If clipboard integration is unavailable, press `u` in the CodexGPT terminal to display the secret URL explicitly.
+
+In ChatGPT Developer Mode, create the Plugin/App connection with:
+
+```text
+Name: CodexGPT
+Connection: Server URL
+Server URL: paste the complete copied URL
+Authentication: No Authentication / None
+```
+
+The current personal compatibility flow authenticates through the query credential in the complete Server URL. Do not remove the query string, share it, publish it, commit it, or place it in issue reports. Treat browser history, clipboard contents, screenshots, logs, and copied links as possible exposure paths.
+
+## Option B: dashboard-managed tunnel token
+
+Cloudflare can also provide a connector token from the dashboard. Store that token in a local file rather than a command line or saved CodexGPT profile.
+
+Create the secret file:
+
+```powershell
+$dir = Join-Path $env:USERPROFILE ".codexgpt"
+New-Item -ItemType Directory -Force -Path $dir | Out-Null
+notepad (Join-Path $dir "cloudflare-tunnel-token")
+```
+
+Put only the Cloudflare connector token in the file. Then start:
+
+```powershell
+codexgpt stable `
+  --root D:\Dev\your-repo `
+  --hostname mcp.example.com `
+  --cloudflare-token-file "$env:USERPROFILE\.codexgpt\cloudflare-tunnel-token" `
+  --token <long-random-codexgpt-token> `
+  --bash safe
+```
+
+Do not confuse the credentials:
+
+```text
+Cloudflare Tunnel credential  authorizes cloudflared to connect the machine to Cloudflare.
+CodexGPT MCP token            authorizes requests reaching the local /mcp endpoint.
+```
+
+## Host-header and DNS-rebinding controls
+
+Use all of these controls together:
+
+1. Keep CodexGPT bound to `127.0.0.1`.
+2. Configure one exact Cloudflare ingress hostname.
+3. Add the final `http_status:404` ingress rule.
+4. Set `originRequest.httpHostHeader` to the expected public hostname.
+5. Do not create wildcard DNS records pointing at the tunnel.
+6. Do not allow arbitrary user-supplied hostnames in wrapper scripts or saved profiles.
+7. Keep the CodexGPT token mandatory even when Cloudflare Access is also used.
+
+Cloudflare Access may be useful as an additional layer, but it must be tested against the ChatGPT connector flow before being made mandatory. It does not replace the CodexGPT token or local authorization.
+
+## Token rotation
+
+### Rotate the CodexGPT token
+
+1. Stop CodexGPT.
+2. Generate a new random token.
+3. Restart CodexGPT with the new `--token` value.
+4. Replace the complete Server URL in ChatGPT.
+5. Remove the old URL from notes, browser history where practical, screenshots, clipboard managers, and shell history.
+
+A stable hostname does not make the old token valid after rotation.
+
+### Rotate the Cloudflare Tunnel credential
+
+Rotate or recreate the tunnel credential through Cloudflare, update the local credentials JSON or token file, and restart `cloudflared`/CodexGPT. This does not rotate the CodexGPT MCP token.
+
+## Logging rules
+
+- Do not use the complete tokenized URL in documentation, screenshots, issues, PR descriptions, or shell transcripts.
+- Prefer `codexgpt doctor` and redacted status output for diagnostics.
+- Enable `--log-requests` only for bounded troubleshooting; supported output is redacted, but logs should still be treated as sensitive.
+- Never enable shell tracing around commands containing tokens.
+- Prefer token files for persistent Cloudflare connector credentials.
+- Do not store raw tunnel tokens in workspace profiles or Git repositories.
+
+## Windows Firewall and router
+
+No inbound firewall or router rule is required. Confirm that port 8787 is loopback-only:
+
+```powershell
+Get-NetTCPConnection -LocalPort 8787 -State Listen |
+  Select-Object LocalAddress, LocalPort, OwningProcess
+```
+
+The expected local address is `127.0.0.1` or `::1`. A listener on `0.0.0.0`, a LAN address, or `[::]` is outside the recommended deployment.
+
+## Verification
+
+Run local diagnostics:
+
+```powershell
+codexgpt doctor
+```
+
+Check the tunnel:
+
+```powershell
+cloudflared tunnel info codexgpt
+cloudflared tunnel ingress validate
+```
+
+Test the public health endpoint without printing the MCP token:
+
+```powershell
+Invoke-WebRequest https://mcp.example.com/healthz
+```
+
+Then use `codexgpt connection-test --root D:\Dev\your-repo` when ChatGPT cannot create or call the connection. Connection-test disables writes, Bash, and tool cards while preserving request-arrival diagnostics.
+
+## Operational checklist
+
+Before daily use:
+
+- The intended repository path is correct.
+- CodexGPT is bound to loopback.
+- The named tunnel uses the exact hostname.
+- The final ingress deny rule is present.
+- The complete ChatGPT Server URL contains the current CodexGPT token.
+- Bash mode matches the repository trust level.
+- `--no-bash` is used for untrusted repositories.
+- Advanced V3/V4 contracts are enabled only with their required policy, audit, permission-profile, and local-approval controls.
+
+## Other URL modes
+
+CodexGPT also supports:
+
+```text
+codexgpt start --tunnel cloudflare                 disposable quick tunnel
+codexgpt ngrok --hostname name.ngrok-free.dev      stable ngrok hostname
+codexgpt tailscale --hostname device.tailnet.ts.net
+codexgpt start --tunnel none                       local-only HTTP
+```
+
+For the stated self-hosted Windows requirement, the named Cloudflare Tunnel with a custom subdomain is the preferred path.

package/FAQ.md

@@ -0,0 +1,366 @@
+# CodexGPT FAQ
+
+## Which ChatGPT account should I use?
+
+Use a ChatGPT account whose current UI exposes Apps, Developer Mode, or the connection-management page. Availability can vary with account, workspace policy, and rollout; use the current ChatGPT UI as the source of truth.
+
+CodexGPT does not unlock Developer Mode, unlock models, bypass account limits, or provide account access. It connects to the ChatGPT app surface your account already has.
+
+Account access and model tool support are separate. An eligible account can have Apps / Developer Mode, while a specific model surface may still be unable to call connectors or MCP tools directly. If CodexGPT actions are unavailable in that chat, use another tool-capable ChatGPT surface or the Pro context fallback for that session.
+
+## How is CodexGPT different from generic workspace bridges?
+
+They can look similar at the transport layer because both use a local MCP-style bridge and a workspace root.
+
+CodexGPT is more focused: it is built around one clear product loop for ChatGPT users:
+
+```text
+install -> setup in one repo -> paste Server URL into ChatGPT -> inspect/edit/verify/review that repo
+```
+
+The main differences are:
+
+- CodexGPT is ChatGPT Developer Mode first, not a generic workspace bridge.
+- Bash, write/edit, tool mode, Codex session reads, and handoff execution are separate safety controls.
+- Durable context is repo-backed through `AGENTS.md` and `.ai-bridge/*`, so important project memory stays reviewable in files.
+- The normal workflow emphasizes compact cards, diffs, `show_changes`, smoke tests, and handoff status files.
+- CodexGPT keeps a strict boundary: no model proxying, account pooling, third-party Pro site scraping, quota bypassing, or OS sandbox claims.
+
+CodexGPT connects ChatGPT to a user-approved local repository over MCP. Repository access, command permissions, and change review remain explicit.
+
+## What does Repository Analysis understand?
+
+Repository Analysis builds a local repository map from bounded, inspectable evidence:
+
+- project and package manifests
+- source/test/config/documentation paths
+- common declarations, imports, includes, and internal module relationships
+- Git changes and existing project verification scripts
+
+It supports TypeScript/JavaScript, Python, Go, Rust, Swift, Java, C#, C, and C++ declaration patterns. Unsupported languages still participate in safe inventory and lexical search.
+
+Relationships are labeled `exact`, `strong`, or `inferred`. The repository map does not replace a compiler or language server. CodexGPT does not require a language server, daemon, embedding service, or vector database.
+
+Analysis is process-local and cached by a bounded workspace fingerprint. Direct CodexGPT writes, edits, and patches invalidate that cache. If limits are reached, results say `partial` and retain normal tree/search/read/review fallback behavior.
+
+Set `CODEXGPT_ANALYSIS=0` to disable this layer while keeping the standard file, search, Git, and review tools available.
+
+Terminal users can inspect the same facts without ChatGPT:
+
+```bash
+codexgpt inspect --json
+codexgpt review --json
+```
+
+## What is the `codexgpt` supertool?
+
+Note: this FAQ follows GitHub `main`. Check the npm badge/version before assuming a `main` feature is in `codexgpt@latest`.
+
+`codexgpt` is a stable wrapper tool for advanced setups. It accepts:
+
+```json
+{ "action": "search", "args": { "query": "needle", "path": "src" } }
+```
+
+Call it with `action=list_actions` to see what the current server mode actually allows. It cannot call tools that are hidden by `--tool-mode`, `--no-bash`, or non-workspace write mode.
+
+Use explicit tools such as `read`, `search`, `edit`, `bash`, and `show_changes` for normal work. Use the supertool when ChatGPT connector caching, custom workflows, or stable wrapper-style integrations matter more than separate visible tool descriptors.
+
+## How do project guidance and Skills work?
+
+Normal `standard` mode enables project guidance by default. Workspace open returns bounded root `AGENTS.md` text and a compact catalog of workspace Skills that are eligible for implicit use. Before the first mutation, and again after switching to another subtree, ChatGPT should call `codex_context(target_path)` to obtain the exact root-to-target instruction chain and target-scoped Skill catalog.
+
+A matching Skill is loaded lazily and remains instruction text only. Skill scripts do not run automatically, declared dependencies are not installed or treated as verified, and neither AGENTS nor Skills can enable tools, widen roots, approve mutations, or bypass Policy, Approval, Audit, blocked paths, or execution modes. User/plugin Skills remain excluded unless a call explicitly opts into global discovery.
+
+`--tool-mode minimal` does not expose `codex_context`. When guidance mode is omitted, minimal mode therefore uses the exact `legacy` compatibility projection; explicitly requesting `CODEXGPT_GUIDANCE_MODE=standard` with minimal mode fails at startup. Apps created before the Phase 6 tool update may need one **Scan Tools** refresh or recreation.
+
+## What is the recommended install path?
+
+Install globally once:
+
+```bash
+npm install -g codexgpt
+```
+
+Then run setup from the repo you want ChatGPT to work on:
+
+```bash
+codexgpt setup
+```
+
+After setup, daily startup from that same repo is:
+
+```bash
+codexgpt start
+```
+
+`npx codexgpt@latest start` still works as a no-install fallback, but the global install is easier for normal users.
+
+## What do I enable in ChatGPT?
+
+Open ChatGPT's current Apps/Plugins connection-management page. If the UI offers Developer Mode, enable it:
+
+```text
+Settings -> Plugins / Apps -> + / Create
+```
+
+When creating the plugin, use the supported personal ChatGPT compatibility flow:
+
+```text
+Name: CodexGPT
+Description: Local workspace bridge for ChatGPT coding
+Connection: Server URL
+Server URL: paste the complete URL copied by CodexGPT, including codexgpt_token
+Authentication: No Authentication / None (if shown)
+```
+
+The complete Server URL contains the query-token credential. Treat it as a password-equivalent secret because it can leak through browser history, clipboard contents, screenshots, logs, and copied links. Do not share, publish, or commit it. The unreleased source checkout now includes locally verified Phase 8 Tasks 8A1–8A9, live Gate G8-U Journeys U2–U7, and local G8-X through a separate OAuth App and token-free URL; exact-head CI and publication remain incomplete. This section documents only the retained Legacy compatibility App. Do not mix the two Apps or replace either flow with manual static-Bearer configuration.
+
+## Should CSP stay enabled?
+
+If the Developer Mode page displays an Enforce CSP toggle, keep it enabled.
+
+CodexGPT widgets are built for the CSP-enabled path. They do not need unrestricted network access, external fonts, remote scripts, iframes, or third-party images.
+
+## Does CodexGPT bypass rate limits?
+
+No.
+
+CodexGPT does not bypass, avoid, increase, pool, resell, or modify ChatGPT, Codex, OpenAI, or third-party model limits. Every request still runs through the user's own ChatGPT session and whatever limits that account has.
+
+The useful part is that Codex and ChatGPT are different product surfaces. If one workflow is unavailable and another product surface you already have access to is still available, CodexGPT lets you work against the same local repo without changing either product's limits.
+
+## Can CodexGPT use GPT-5.5?
+
+Only if your ChatGPT account already exposes that exact model, or a similar stronger model, in the ChatGPT web product surface you are using, and that model surface can call Developer Mode apps.
+
+Some GPT-5.5 Pro or other model surfaces may not expose app actions in a given chat. If CodexGPT actions are unavailable there, CodexGPT cannot make that request reach the local server. CodexGPT does not provide, proxy, resell, or unlock models. It gives compatible ChatGPT sessions local repo tools.
+
+For models that cannot call tools, generate a repo context bundle instead:
+
+```bash
+codexgpt pro-bundle --root /path/to/repo --copy
+```
+
+## What can ChatGPT see through CodexGPT?
+
+ChatGPT can see explicit workspace context exposed by tools:
+
+- `AGENTS.md`
+- `.ai-bridge` plans and status files
+- git status
+- git diff
+- selected source files
+- file tree and search results
+
+It cannot read hidden Codex runtime memory or anything outside the allowed workspace unless you explicitly allow that root.
+
+## What can ChatGPT edit?
+
+In normal coding mode, ChatGPT can write and exact-edit files inside the configured workspace.
+
+Safety defaults block common sensitive paths:
+
+- `.env`
+- private keys
+- `.git`
+- `node_modules`
+- generated build/cache folders
+- symlink escapes
+- paths outside the workspace
+
+Use handoff mode if you want ChatGPT to write a plan only and let Codex execute locally. In handoff mode, generic `write` and `edit` tools are not advertised to ChatGPT.
+
+Use `CODEXGPT_WRITE_MODE=off` when you want direct `write` and `edit` tools removed from the advertised MCP tool list while still allowing bounded handoff/context files.
+
+## Are workspace IDs shared across ChatGPT sessions?
+
+No. A `workspace_id` is now a random opaque handle owned by one MCP server session: one HTTP transport session, or one STDIO process session. Opening the same root inside the same active session reuses that session's handle, but another session receives a different handle and cannot use or list the first session's workspaces.
+
+Use `close_workspace` to invalidate a handle immediately. Reopening the root creates a new handle. Idle handles expire after `CODEXGPT_WORKSPACE_TTL_MS`; the default is the HTTP session TTL, normally 30 minutes, and successful use refreshes the idle deadline.
+
+For one compatibility cycle, an omitted `workspace_id` still selects only that session's configured default root. It does not restore cross-session sharing.
+
+## Can CodexGPT bind bash to a specific session id?
+
+CodexGPT cannot attach to, read, or execute inside a specific Codex app conversation or terminal session.
+
+The MCP `bash` tool runs from the CodexGPT server process you started for the configured workspace. MCP session ids are HTTP transport state between ChatGPT and CodexGPT; they are not Codex conversation ids.
+
+What CodexGPT can do is require a matching local bash session label before it runs shell commands:
+
+```bash
+codexgpt start --bash-session main --require-bash-session
+```
+
+Then `bash` calls must include `session_id: "main"`. This helps avoid accidental shell execution in the wrong CodexGPT terminal, but it is not remote control of an existing Codex app chat.
+
+CodexGPT can list local Codex session ids and titles when you explicitly opt in:
+
+```bash
+codexgpt start --codex-sessions metadata
+```
+
+This reads local Codex JSONL history under `~/.codex/sessions` and `~/.codex/archived_sessions` and returns metadata plus `codex resume <session-id>` commands. Use `--codex-sessions read` only if you also want bounded transcript reads. It does not attach to a live Codex app conversation.
+
+If you do not want ChatGPT to trigger shell commands while you work in Codex, start CodexGPT with bash disabled:
+
+```bash
+codexgpt start --no-bash
+```
+
+This removes the `bash` MCP tool from the advertised tool list. ChatGPT can still use non-bash CodexGPT tools such as workspace open, read, search, and show_changes. Direct `write`/`edit` are advertised only in workspace write mode.
+
+If you only want ChatGPT to plan and leave execution to Codex or another local agent:
+
+```bash
+codexgpt start --mode handoff --no-bash
+```
+
+## Which tunnel should I choose?
+
+Use this rule:
+
+```text
+Fast demo:              Cloudflare quick tunnel
+Recommended stable URL: ngrok free dev domain
+Custom domain:          Cloudflare named tunnel
+Tailnet users:           Tailscale Funnel
+No public tunnel:       local-only mode, only for clients that can reach localhost
+```
+
+Cloudflare quick tunnel URLs change on restart. If you put a quick-mode URL into ChatGPT, you must edit the ChatGPT app Server URL every time you restart the tunnel.
+
+For most users, the better path is a free ngrok dev domain. Create a free ngrok account, find your assigned dev domain under Universal Gateway -> Domains, and save that hostname during `codexgpt setup`.
+
+If you own a domain, use Cloudflare named tunnels and route DNS to a hostname like `codexgpt.example.com`.
+
+## Why does ChatGPT show “Something went wrong” when I create a connector?
+
+Usually ChatGPT could not reach the public MCP URL. A generated `trycloudflare.com` URL is not proof that `cloudflared` stayed connected.
+
+Run the connection test:
+
+```bash
+codexgpt connection-test --root /path/to/repo
+```
+
+This keeps `read`, `tree`, `search`, and `load_skill`, but disables file writes,
+bash, and tool cards. In ChatGPT, create the development plugin under
+`Settings -> Plugins`, paste the complete Server URL including its `codexgpt_token`
+query string, and, if shown, choose `Authentication: No Authentication / None`.
+
+The terminal output separates the failure boundary:
+
+- No `POST /mcp received`: the request did not reach CodexGPT. Check the ChatGPT Plugins page and the tunnel.
+- `POST /mcp -> 401`: the complete URL was not used, the query token was removed, or the credential no longer matches the running CodexGPT process.
+- `POST /mcp -> 2xx`: ChatGPT reached CodexGPT and the MCP endpoint responded.
+
+Keep CodexGPT running while testing. A Cloudflare quick-tunnel URL changes on every restart. If Cloudflare returns `530` / `Error 1033`, check DNS or proxy-client DNS handling on the machine running `cloudflared`.
+
+ChatGPT now manages development apps under Plugins. The browser error `Failed to execute 'removeChild' on 'Node'` occurs in the ChatGPT page, before CodexGPT can handle an MCP request. Remove or recreate the stale plugin entry from the Plugins page, then retry with the current URL. CodexGPT cannot repair that browser-side entry.
+
+Official references:
+
+- OpenAI: connect an MCP server to ChatGPT: https://developers.openai.com/apps-sdk/deploy/connect-chatgpt
+- OpenAI: MCP server authentication: https://developers.openai.com/apps-sdk/build/auth
+- ngrok dev domains: https://ngrok.com/docs/universal-gateway/domains
+- Cloudflare Tunnel routing: https://developers.cloudflare.com/tunnel/routing/
+- Cloudflare Tunnel DNS records: https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/routing-to-tunnel/dns/
+
+## Can I use the same ChatGPT app URL every day?
+
+Yes, if you use a stable hostname.
+
+Recommended simple path:
+
+```bash
+codexgpt setup
+# choose ngrok
+# enter your ngrok free dev domain
+```
+
+After that:
+
+```bash
+codexgpt start
+```
+
+The same hostname and CodexGPT token are reused for that workspace. Keep the complete credential-bearing Server URL private, and replace it in ChatGPT whenever you rotate the token.
+
+## What if I run CodexGPT in two repos at once?
+
+Use different local ports and different tunnel hostnames.
+
+Example:
+
+```text
+repo A: port 8787, hostname A
+repo B: port 8788, hostname B
+```
+
+Run `codexgpt setup` in each repo and save a profile per workspace.
+
+## Why not use codexgpt.github.io?
+
+GitHub Pages gives `owner.github.io` only to the GitHub user or organization named `owner`.
+
+The `codexgpt` GitHub username already exists, so this repo cannot use `codexgpt.github.io` from the `rebel0789` account.
+
+The clean GitHub Pages URL for this project is:
+
+```text
+https://rebel0789.github.io/codexgpt/
+```
+
+## Is CodexGPT production safe?
+
+CodexGPT is a local developer bridge, not an OS sandbox.
+
+Use it with repos you trust. Keep token auth enabled for public tunnels. Keep safe bash on unless you know why you need full bash. Read [SECURITY.md](SECURITY.md) before exposing it through a public tunnel.
+
+## Where are saved settings stored?
+
+CodexGPT stores local state under `~/.codexgpt` by default. On Windows that is usually `C:\Users\<you>\.codexgpt`.
+
+Workspace profiles are JSON files saved under:
+
+```text
+~/.codexgpt/profiles/
+```
+
+Current runtime connection files are saved under:
+
+```text
+~/.codexgpt/runtime/
+```
+
+Strict Policy Kernel Permission Profiles are saved under:
+
+```text
+~/.codexgpt/permissions/
+```
+
+When shared-secret Policy identities are used, CodexGPT keeps an installation-local HMAC key at `~/.codexgpt/policy/identity-hmac.key`. Treat it as private local state: do not share or hand-edit it. Replacing it changes future credential references.
+
+Set `CODEXGPT_HOME` to move the complete CodexGPT state directory.
+
+Use:
+
+```bash
+codexgpt settings
+codexgpt settings list
+codexgpt settings delete --yes
+```
+
+Saved tokens are redacted when profiles are displayed.
+
+## What are `legacy`, `shadow`, and `enforce` Policy Kernel modes?
+
+`legacy` is the migration-cycle default and preserves the existing execution path. `shadow` preserves that path while calculating only redacted comparison decisions. `enforce` makes the compiled Policy Kernel authoritative and fails closed when policy or required enforcement facts are unavailable.
+
+Contracts V1 and V2 keep the original restrictive behavior and never create pending approvals. Explicit Contract V3 adds a local-only approval CLI for confirmed roots and trusted-code Windows process execution; the remote MCP client cannot approve its own request. `full_access` still has the ambient authority of the current Windows user and is not a sandbox. The reserved `workspace` profile remains unavailable because the AppContainer/LPAC isolation gate did not pass.
+
+Permission Profiles are strict local JSON files under `~/.codexgpt/permissions/`. They are separate from saved runtime connection profiles. `toolMode` changes discovery only and does not expand a Permission Profile, hard policy, identity scope, or enforcement capability. See the Contract V3 section in [README.md](README.md) for the activation and local approval flow.
+
+Rollback during this migration cycle may return to reviewed `legacy` behavior, the generated compatibility profile, or a narrower read-only profile. A Policy Kernel startup or profile error never falls through to unguarded execution.