Define CODE and CODEX compatibility policy

AGENTS.md

@@ -22,7 +22,9 @@ read-only local mirror of `openai/codex:main`; edit Rust sources under
 `CODE_HOME` / `~/.code` are the primary config and state locations.
 `CODEX_HOME` / `~/.codex` are compatibility fallbacks. Keep `CODEX_*` names when
 they are part of external, backend, or upstream compatibility; add `CODE_*`
-aliases or rename only through a scoped migration.
+aliases or rename only through a scoped migration. See
+`docs/upstream-import-policy.md#code-and-codex-compatibility-policy` before
+changing environment variable behavior.
 
 Rust implementation lives under `code-rs`:
 

docs/auto-drive.md

@@ -46,6 +46,10 @@ What Auto Drive is, how to start it, and how it behaves in Every Code.
 - Optionally set `CODEX_TUI_SESSION_LOG_PATH=/absolute/path/session.jsonl` to choose the output file; otherwise Every Code writes under its normal log directory (typically `~/.code/debug_logs/`, and `code-dev` defaults to `~/.code/debug_logs/code-dev/`).
 - When the TUI panics, Every Code now records the panic payload and captured backtrace in both the session JSONL log and the regular error log.
 
+These debug variables keep their `CODEX_TUI_*` names for now. They are
+dev-only rename candidates; add `CODE_TUI_*` aliases and focused tests before
+changing the documented spelling.
+
 ## Models
 - Defaults: model `gpt-5.1`, reasoning effort `high`.
 - Toggle “use chat model” in settings to reuse your current chat model/effort instead of the dedicated Auto Drive model.

docs/config.md

@@ -13,7 +13,7 @@ Every Code supports several mechanisms for setting config values:
   - If `value` cannot be parsed as a valid TOML value, it is treated as a string value. This means that `-c model='"o3"'` and `-c model=o3` are equivalent.
     - In the first case, the value is the TOML string `"o3"`, while in the second the value is `o3`, which is not valid TOML and therefore treated as the TOML string `"o3"`.
     - Because quotes are interpreted by one's shell, `-c key="true"` will be correctly interpreted in TOML as `key = true` (a boolean) and not `key = "true"` (a string). If for some reason you needed the string `"true"`, you would need to use `-c key='"true"'` (note the two sets of quotes).
-- The `$CODE_HOME/config.toml` configuration file. `CODE_HOME` defaults to `~/.code`; Every Code (Code) also reads from `$CODEX_HOME`/`~/.codex` for backwards compatibility but only writes to `~/.code`. (Logs and other state use the same directory.)
+- The `$CODE_HOME/config.toml` configuration file. `CODE_HOME` defaults to `~/.code`; Every Code also reads from `$CODEX_HOME`/`~/.codex` for backwards compatibility but only writes to `~/.code`. (Logs and other state use the same directory.) See [CODE and CODEX compatibility policy](./upstream-import-policy.md#code-and-codex-compatibility-policy) for naming and fallback rules.
 
 - https://developers.openai.com/codex/config-reference
 

docs/exec.md

@@ -110,3 +110,8 @@ CODEX_API_KEY=your-api-key-here code exec "Fix merge conflict"
 ```
 
 NOTE: `CODEX_API_KEY` is only supported in `code exec`.
+
+`CODEX_API_KEY` is intentionally preserved as a compatibility name. New Every
+Code-owned environment variables should use `CODE_*`, but compatibility and
+upstream-facing names are kept unless a scoped migration documents aliases and
+tests both spellings.

docs/upstream-import-policy.md

@@ -29,6 +29,36 @@ long-running feature branch overlay.
   backend, or upstream compatibility requires them; add `CODE_*` aliases or
   rename only through scoped migrations.
 
+## CODE And CODEX Compatibility Policy
+
+Use `CODE_*` names for new Every Code-owned environment variables, config paths,
+automation metadata, and locally-authored integration contracts. Use
+`EVERY_CODE_*` only when the variable needs to be unmistakably product-branded
+outside this repo, such as cross-repo remote inbox metadata.
+
+Keep `CODE_HOME` / `~/.code` as the primary config and state location. Keep
+`CODEX_HOME` / `~/.codex` as a compatibility fallback. The lookup order is
+`CODE_HOME`, then `CODEX_HOME`, then default `~/.code`, with legacy `~/.codex`
+read only where the specific subsystem supports migration or compatibility.
+Every Code-owned writes should go to `~/.code` / `CODE_HOME` unless a scoped
+compatibility feature explicitly says otherwise.
+
+Preserve `CODEX_*` names when they are part of an external contract, upstream
+merge surface, backend/API behavior, or documented compatibility behavior. This
+includes names such as `CODEX_HOME`, `CODEX_API_KEY`, cloud/backend variables,
+Bazel/upstream CI variables, and protocol/security names until a dedicated
+migration adds `CODE_*` aliases with tests.
+
+Dev-only or test-only `CODEX_TUI_*` variables are rename candidates, not silent
+cleanup. A change should add a `CODE_TUI_*` alias first, keep the old
+`CODEX_TUI_*` spelling for a compatibility window, document the precedence, and
+include focused tests for both names before any removal.
+
+Do not mass-rename deep Rust identifiers, telemetry prefixes, generated schema
+types, model names, or `codex-rs` mirror paths just to remove `codex`. Those
+names often preserve upstream compatibility, historical provenance, or external
+dashboard continuity.
+
 The pre-cutover `origin/main` history was archived at
 `archive/pre-every-code-main-2026-05-24` before `main` was repointed to the Every
 Code product branch. Treat `local/cbusillo-overlay` as a retired branch name;