codex-configurator 0.2.3 → 0.2.5

package/README.md

@@ -1,7 +1,9 @@
 # Codex Configurator
 
 Codex Configurator is a terminal user interface (TUI) built with Node.js, React, and Ink.
-It shows the current contents of a Codex TOML configuration file and can reload it on demand.
+It shows the current contents of Codex TOML configuration files and can edit them inline.
+The TUI uses a fixed full-screen shell so row/list geometry does not shift as modes change.
+While running, it uses the terminal’s alternate screen buffer so the session is rendered as a full-screen interface without scrollback history during interaction.
 
 ## Requirements
 
@@ -19,10 +21,10 @@ npm i -g codex-configurator
 codex-configurator
 ```
 
-Optional config-path override:
+Optional workspace override:
 
 ```bash
-codex-configurator --config /path/to/config.toml
+codex-configurator --codex-dir /path/to/workspace
 ```
 
 For local development in this repository:
@@ -37,12 +39,15 @@ npm start
 - `↑` `↓` : move selection
 - `PgUp` `PgDn`: move one page up/down
 - `Home` `End`: jump to first/last item
-- `Enter`: open selected table; for boolean settings, toggle directly; for string settings, open inline input; for other preset values, open picker
-- `/`: start fuzzy filter mode for the current list
+- `Enter`: open selected table; for mixed scalar/object settings, choose a preset first (object presets open nested settings); for boolean settings, toggle directly; for string settings, open inline input; for other preset values, open picker
 - `Del`: unset selected value or remove selected custom `<id>` entry from `config.toml`
 - `←` / `Backspace`: move up one level (to parent table)
-- `r`: reload the active config file
-- `q`: quit
+- `:`: enter command mode
+- `:filter`: start fuzzy filter mode for the current list
+- `:file`: switch between TOML config files in the current workspace
+- `:reload`: reload the active config file
+- `:help`: toggle quick help overlay
+- `:quit` (or `:q`): quit
 
 The right-hand pane shows what each setting means, plus a picker when a value has preset options.
 Deprecated settings are marked with a `[!]` warning marker; only that marker is highlighted.
@@ -80,13 +85,20 @@ By default the app reads from:
 ~/.codex/config.toml
 ```
 
-You can override this path with either:
+You can override the workspace with either:
 
-- CLI: `--config /absolute/or/relative/path.toml`
-- Env: `CODEX_CONFIGURATOR_CONFIG_PATH`
+- CLI: `--codex-dir /absolute/or/relative/path`
+- Env: `CODEX_CONFIGURATOR_CODEX_DIR`
 
 Precedence is CLI first, then environment variable, then the default path.
-If the file is missing or unreadable, the TUI displays the read error and the resolved path.
+The resolved workspace is normalized and `/path/.codex/config.toml` is used as the config file.
+If the active file is missing or unreadable, the TUI displays the read error and resolved path.
+
+The active config file can also be changed at runtime with `:file`:
+
+- `main config` is always the resolved workspace main file (`~/.codex/config.toml` by default).
+- each `agents.<name>.config_file` entry contributes an additional editable file.
+  If that file does not exist yet, saving `agents.<name>.config_file` in the main file creates it as an empty TOML file before the main update is written.
 Configuration writes are atomic and create the target file (and parent directories) when missing.
 
 ## Error logging
@@ -119,15 +131,22 @@ This uses the `npm` command from `PATH` (or `CODEX_CONFIGURATOR_NPM_BIN` if set)
 
 ## Upstream reference
 
-- Codex configuration reference: https://developers.openai.com/codex/config-reference/
+- Canonical config schema: https://developers.openai.com/codex/config-schema.json
+- The local menu reads directly from `src/reference/config-schema.json`, which is downloaded from the canonical schema.
+- To refresh the reference snapshot after a new stable Codex release:
+  - `npm run sync:reference`
+- Snapshot currently synced against Codex stable reference updates published on 2026-02-25.
+- Release notes and change history: `CHANGELOG.md`
 
 ## Scripts
 
-- `npm start`: run the TUI
-- `npm run dev`: same as `npm start`
+- `npm run dev`: run the TUI in a temporary workspace (`.codex-configurator.scratch`) without resetting it
+- `npm run dev:reset`: reset the temporary workspace (`.codex-configurator.scratch`) and run the TUI
+- `npm start`: run the TUI directly (no scratch isolation)
 - `npm run lint`: ESLint static analysis for `index.js`, `src`, and `test`
 - `npm run build`: validates the npm package archive (`npm pack --dry-run --ignore-scripts --cache .npm-cache`)
 - `npm test`: runs the Node.js unit test suite (`node --test`)
+- `npm run sync:reference`: downloads the latest `config-schema.json` into `src/reference/config-schema.json`
 
 ## Continuous integration
 
@@ -147,6 +166,6 @@ GitHub Actions runs production dependency audit (`npm audit --omit=dev --audit-l
 - `src/configHelp.js`: user-facing copy for key explanations
 - `src/layout.js`: pane width and path-key helpers
 - `src/interaction.js`: input helpers
-- `src/reference/config-reference.json`: source-of-truth schema extracted from upstream config reference and used to drive which UI settings are shown
+- `src/reference/config-schema.json`: downloaded canonical schema used directly by the UI menu
 - `.gitignore`: ignore list for Node/TUI artifacts
 - `package.json`: package metadata and scripts