@@ -25,7 +25,16 @@ jobs:
         if: runner.os == 'Linux'
         run: |
           sudo apt-get update
-          sudo apt-get install --yes direnv expect jq
+          sudo apt-get install --yes expect jq
+          # Ubuntu's direnv 2.32.1 expands shell metacharacters in project paths.
+          # Pin a release containing the upstream path-escaping fix (2.32.2+).
+          curl --fail --location --silent --show-error \
+            https://github.com/direnv/direnv/releases/download/v2.37.1/direnv.linux-amd64 \
+            --output "$RUNNER_TEMP/direnv"
+          printf '%s  %s\n' \
+            1f1b93dd6f38523fde26dfac96151ef9d31a374e3005cd3345fb93555ae0c9b5 \
+            "$RUNNER_TEMP/direnv" | sha256sum --check
+          sudo install -m 0755 "$RUNNER_TEMP/direnv" /usr/local/bin/direnv
 
       - name: Install macOS dependencies
         if: runner.os == 'macOS'
 
@@ -56,10 +56,11 @@ The helper runs on macOS and Linux with Bash 3.2 or newer.
 
 | Use | Requirements |
 |---|---|
-| Run Codex from the terminal | Git, Codex CLI, `curl`, and `jq` |
-| Select an identity by project | Also install `direnv` |
+| Run Codex from the terminal | Git, Codex CLI, and `jq` |
+| Discover API models or generate a model snapshot | Also install `curl` 7.76.0 or newer |
+| Select an identity by project | Also install `direnv` 2.32.2 or newer |
 | Open labeled VS Code windows | Also install VS Code and the Codex extension |
-| Run the tests | Also install `direnv` and `expect` |
+| Run the tests | Also install `direnv` 2.32.2 or newer and `expect` |
 | Open projects from Finder | macOS only |
 
 ### macOS
@@ -70,8 +71,11 @@ With [Homebrew](https://brew.sh/):
 brew install git direnv jq
 ```
 
-macOS includes `curl` and normally includes `expect`. If `expect -v` fails, run
-`brew install expect`. Install or update the Codex CLI by following the
+macOS includes `curl`; check `curl --version` and use `brew install curl` if it
+is older than 7.76.0 and you need model discovery. Follow Homebrew's PATH
+instructions so `curl --version` reports the newer version. macOS normally
+includes `expect`; if `expect -v` fails, run `brew install expect`.
+Install or update the Codex CLI by following the
 [official Codex CLI guide](https://learn.chatgpt.com/docs/codex/cli). If you
 plan to use VS Code, install VS Code and follow the
 [official Codex IDE guide](https://learn.chatgpt.com/docs/codex/ide).
@@ -83,6 +87,13 @@ sudo apt update
 sudo apt install bash curl direnv expect git jq
 ```
 
+Check `curl --version` (7.76.0 or newer for model discovery) and
+`direnv version`. If `direnv` is older than 2.32.2, upgrade using the
+[official installation guide](https://direnv.net/docs/installation.html).
+Earlier releases incorrectly expand shell characters such as `$` in project
+paths; the launcher requires the upstream path-escaping fix.
+See the [direnv 2.32.2 release notes](https://github.com/direnv/direnv/releases/tag/v2.32.2).
+
 Then install or update the Codex CLI using the
 [official Codex CLI guide](https://learn.chatgpt.com/docs/codex/cli). Install
 VS Code and the Codex extension only if you want the IDE workflow.
@@ -139,8 +150,10 @@ creates disposable identities in a temporary directory and uses mock commands;
 it does not need your credentials or contact a provider. If the final pass line
 does not appear, see [Troubleshooting](docs/troubleshooting.md).
 
-The examples in this repository use `./bin/codex-home`, so adding the helper to
-`PATH` is optional. To run `codex-home` from any directory in future terminals,
+Run examples beginning with `./bin/codex-home` from the clone directory.
+Examples using bare `codex-home` require its `bin` directory on `PATH`, either
+from the shell setting below or from an approved generated project `.envrc`.
+To run `codex-home` from any directory in future terminals,
 add this line to `~/.zshrc` for zsh or `~/.bashrc` for Bash:
 
 ```bash
@@ -160,10 +173,10 @@ Choose the guide for the identity you need:
 - [Responses-compatible API providers and Azure](docs/api-providers.md)
 - [Optional U-M GPT setup](docs/umgpt.md)
 
-From the clone directory, run `./bin/codex-home run NAME`, replacing `NAME`
-with the identity you created. To select an identity automatically for a
-project or open a labeled VS Code window,
-[assign the identity to a project](docs/projects-vscode.md). On macOS, you can
+After creating the identity, [verify its configuration and sign-in](docs/commands.md#check-the-selected-identity).
+Then [assign it to a project](docs/projects-vscode.md): generate the files,
+review them, approve `.envrc`, and launch. This selects the identity automatically
+for that project or opens a labeled VS Code window. On macOS, you can
 also install the optional [Finder Quick Action](docs/macos-open-with.md):
 
 ```bash
 
@@ -10,6 +10,9 @@ and Linux, with optional `direnv`, VS Code, and macOS Finder integration.
 
 Developed at the [Fritsche Lab](https://fritschelab.org/), University of Michigan.
 
+**New here?** Follow [Installation](INSTALLATION.md) for the complete macOS or
+Linux setup, from prerequisites through your first identity and project.
+
 ## One account choice per project
 
 Each project's `.envrc` selects an identity and its `CODEX_HOME`. The account,
@@ -68,13 +71,8 @@ and session history. Each VS Code window shows the identity name, with a
 separate VS Code user-data directory per identity. In a configured project's
 terminal, start the selected context with `codex-home run`.
 
-On macOS, the helper opens a named editor copy: hover over its running Dock
-icon to read `VS Code - NAME`. Projects using the same identity reuse its
-instance. In Finder, use **Quick Actions > Open in Codex Project** for a
-configured folder. File managers with folder **Open With** menus can use the
-matching **VS Code - NAME** handler. You can also use `codex-home`; do not pin or directly open the
-generated editor copy, which needs the helper's launch environment. See
-[macOS Dock names](docs/projects-vscode.md#macos-dock-names).
+On macOS, the helper also gives each identity a [named Dock icon](docs/projects-vscode.md#macos-dock-names)
+and offers optional [Finder integration](docs/macos-open-with.md).
 
 The CLI launcher keeps **[CODEX: NAME]** in the terminal tab/window title.
 
@@ -85,44 +83,52 @@ sandbox. Keep credentials and identity homes private. See the
 
 ## Get started
 
-[Install the prerequisites and clone the repository](INSTALLATION.md).
-The helper runs without administrator rights; installing some prerequisites
-may require them.
+If the prerequisites are installed and the clone is ready, use this quick path.
+Otherwise, begin with [Installation](INSTALLATION.md). The helper runs without
+administrator rights; installing some prerequisites may require them.
 
 From the clone directory, create a ChatGPT identity and sign in:
 
 ```bash
 ./bin/codex-home create-subscription personal
 ./bin/codex-home login personal
+```
+
+Check the intended account and workspace in the browser during sign-in. Then
+check the CLI authentication method and launch a session:
+
+```bash
+./bin/codex-home run personal login status
 ./bin/codex-home run personal
 ```
 
+In the CLI, use `/status` to inspect the active model and session configuration.
+The identity name is a local label; see [verification for CLI and VS Code](docs/commands.md#check-the-selected-identity).
+
 For an API key, follow the [API provider](docs/api-providers.md) or
 [U-M GPT](docs/umgpt.md) guide. Each guide covers access, billing, and a test of
 Codex tool calls with your selected model.
 
-U-M GPT model recommendations are kept in the visible, version-controlled
-file [`config/umgpt-models.toml`](config/umgpt-models.toml). Users can keep
-different local defaults in `~/.codex-homes/umgpt-models.toml`; run
-`codex-home umgpt-defaults` to compare them. Neither file is a model catalog:
-`codex-home models umgpt` and `codex-home models umgpt-low` query the gateway's
-current scoped model lists. The dated
-[model snapshot](docs/umgpt-models-snapshot.md) records one credential's
-observed catalog for review only; it is not used at runtime or an approval
-list.
-
-To use your identity for a project in VS Code:
+After exiting Codex, use your identity for a project in VS Code:
 
 ```bash
 ./bin/codex-home project personal "/path/to/project"
+```
+
+Review the generated `.envrc` and `.vscode/<folder-name>.code-workspace`.
+The `.envrc` contains executable shell code and local paths. Then approve it
+and launch:
+
+```bash
 direnv allow "/path/to/project"
 ./bin/codex-home vscode personal "/path/to/project"
 ```
 
-Review `.envrc` before running `direnv allow`: it contains executable shell
-code and local paths. The helper preserves existing project files and uses
-local Git exclusions for the files it generates. Start a new Codex chat and
-check `/status` to confirm the account and provider.
+The helper preserves existing project files and uses local Git exclusions for
+the files it generates. Start a new Codex chat and [verify the extension's
+account and selected model](docs/commands.md#check-the-selected-identity).
+See [Projects and VS Code](docs/projects-vscode.md) for terminal use and
+existing project configuration.
 
 For right-click access on macOS, run `./bin/install-macos-open-with`, then
 choose **Quick Actions > Open in Codex Project** on a project folder. The
 
@@ -553,8 +553,14 @@ create_api_identity() {
   local key_env="$4"
   local api_version="${5:-}"
   local kind="${6:-api-key}"
+  local provider_label="Codex identity: $name"
   local home
 
+  case "$kind" in
+    umgpt-openai) provider_label="U-M GPT Toolkit ($name)" ;;
+    umgpt-low) provider_label="U-M GPT Toolkit ($name; LOW-SENSITIVITY DATA ONLY)" ;;
+  esac
+
   ensure_new_identity "$name"
   validate_provider_name "$name"
   validate_single_line "base URL" "$base_url"
@@ -574,7 +580,7 @@ create_api_identity() {
     printf 'model = %s\n' "$(toml_quote "$model")"
     printf 'model_provider = %s\n\n' "$(toml_quote "$name")"
     printf '[model_providers.%s]\n' "$name"
-    printf 'name = %s\n' "$(toml_quote "Codex identity: $name")"
+    printf 'name = %s\n' "$(toml_quote "$provider_label")"
     printf 'base_url = %s\n' "$(toml_quote "$base_url")"
     printf 'env_key = %s\n' "$(toml_quote "$key_env")"
     if [[ -n "$api_version" ]]; then
@@ -2059,15 +2065,29 @@ review_project_envrc() {
 }
 
 project_direnv_exec() {
-  env -u CODEX_IDENTITY -u CODEX_HOME \
+  local project_dir="$1" launch_status
+  shift
+  # Older direnv releases also silence log_error when this format is empty.
+  # Keep diagnostics visible and stream the command's output without buffering.
+  if env -u CODEX_IDENTITY -u CODEX_HOME \
     -u DIRENV_DIFF -u DIRENV_DIR -u DIRENV_FILE -u DIRENV_WATCHES \
-    direnv exec "$@"
+    DIRENV_LOG_FORMAT="${DIRENV_LOG_FORMAT:-direnv: %s}" \
+    direnv exec "$project_dir" "$@"; then
+    return 0
+  else
+    launch_status=$?
+  fi
+  printf 'codex-home: failed to launch project: %s (exit %s)\n' "$project_dir" "$launch_status" >&2
+  printf '%s\n' "codex-home: verify the project's .envrc, required commands, and VS Code CLI; see the diagnostic above" >&2
+  return "$launch_status"
 }
 
 launch_vscode_project_env() {
   local project_dir="$1" expected_name="$2"
   local project_abs helper vscode_cli extensions_dir homes_root
   command -v direnv >/dev/null 2>&1 || die "direnv is not installed"
+  direnv version 2.32.2 >/dev/null ||
+    die "direnv 2.32.2 or newer is required for project path escaping; upgrade direnv"
   [[ -d "$project_dir" ]] || die "project directory does not exist: $project_dir"
   project_abs="$(cd "$project_dir" && pwd -P)"
   validate_single_line "project path" "$project_abs"
 
@@ -4,6 +4,10 @@ Use a separate identity for each API provider or key. The helper can configure
 Responses-compatible APIs, direct Azure endpoints, and the U-M GPT gateway.
 Other providers supported by Codex need manual setup.
 
+After [installing prerequisites and cloning the repository](../INSTALLATION.md#1-install-prerequisites)
+(Installation steps 1–3), run `./bin/codex-home` examples from the clone
+directory; bare `codex-home` assumes it is on PATH.
+
 ## Support matrix
 
 | Provider | Codex support | Managed by this helper | Setup |
@@ -134,6 +138,30 @@ guardrails; they do not certify that any model, Codex workflow, or data type is
 institutionally approved. See [U-M GPT](umgpt.md) for setup and governance
 details.
 
+### Provider display names
+
+New U-M identities use `U-M GPT Toolkit (umgpt)` or
+`U-M GPT Toolkit (umgpt-low; LOW-SENSITIVITY DATA ONLY)` as the provider
+display name. Custom identity names replace `umgpt` or `umgpt-low` in those
+labels, so multiple keys remain distinguishable.
+
+For an existing identity, edit only the `name` value in its provider table in
+`$CODEX_HOME/config.toml`. For example, in
+`~/.codex-homes/umgpt/config.toml`:
+
+```toml
+[model_providers.umgpt]
+name = "U-M GPT Toolkit (umgpt)"
+# Keep the existing base_url, env_key, and wire_api entries here.
+```
+
+The [`name` field is Codex's provider display name](https://learn.chatgpt.com/docs/config-file/config-reference).
+Keep `model_provider = "umgpt"` and `[model_providers.umgpt]` unchanged:
+the helper uses the identity name as the provider ID and checks it at launch.
+Restart Codex to use the updated configuration. Display varies by client and
+version; CLI `/status` may still show the provider ID. Existing configuration
+files are not rewritten automatically when you update this repository.
+
 ## Generic bearer-token gateway
 
 ```bash
@@ -166,8 +194,9 @@ Create a home per key. The environment-variable names may be distinct:
 ./bin/codex-home set-key lab-b
 ```
 
-You can also reuse one variable name: only the selected identity's `.env` is
-loaded. Different names can make debugging outside `direnv` easier.
+You can also reuse one variable name: the helper loads the selected identity's
+`.env`. It does not clear unrelated variables or credentials inherited from
+your shell. Different names can make debugging outside `direnv` easier.
 
 ## OpenAI Platform API key
 
@@ -301,23 +330,28 @@ create a small marker file; replace
 `research-api` and the repository path as needed:
 
 ```bash
-CODEX_CONTEXTS="$HOME/Developer/codex-contexts"
-SMOKE_DIR="$(mktemp -d)"
-git -C "$SMOKE_DIR" init --quiet
 (
+  set -eu
+  CODEX_CONTEXTS="$HOME/Developer/codex-contexts"
+  SMOKE_DIR="$(mktemp -d)"
+  printf 'Smoke-test directory: %s\n' "$SMOKE_DIR"
+  git -C "$SMOKE_DIR" init --quiet
   cd "$SMOKE_DIR"
   "$CODEX_CONTEXTS/bin/codex-home" run research-api exec \
     --ephemeral \
     --sandbox workspace-write \
     "Create codex-smoke-test.txt containing exactly OK, using a tool."
+  test "$(cat codex-smoke-test.txt)" = "OK"
+  printf 'Tool-call smoke test passed: %s\n' "$SMOKE_DIR"
 )
-test "$(cat "$SMOKE_DIR/codex-smoke-test.txt")" = "OK"
-printf 'Tool-call smoke test passed: %s\n' "$SMOKE_DIR"
 ```
 
 This request may incur provider charges. Keep research data out of the test.
 Inspect the temporary directory, then delete it when you are done.
 
+After validation, [check the selected identity](commands.md#check-the-selected-identity)
+and [assign it to a project](projects-vscode.md).
+
 References:
 
 - [Codex custom model providers](https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers)