codex: require toml config and drop yaml support

docs/manual/modules/programs/codex.md

@@ -0,0 +1,107 @@
+# Codex {#opt-programs.codex}
+
+The Codex module configures the terminal AI assistant and writes its settings to
+`config.toml`. Only Codex >= 0.2.0 is supported.
+
+## Enabling
+
+```nix
+programs.codex.enable = true;
+```
+
+When `home.preferXdgDirectories = true;`, files are placed in
+`~/.config/codex/`; otherwise in `~/.codex/`. The variable `CODEX_HOME` is set
+automatically in the XDG case.
+
+## Basic settings
+
+```nix
+programs.codex.settings = {
+  model = "gpt-5.1";
+  model_provider = "openai";
+  model_reasoning_effort = "medium";
+  approval_policy = "on-request";
+  sandbox_mode = "workspace-write";
+};
+```
+
+All keys map directly to `config.toml`; see the upstream reference at
+<https://github.com/openai/codex/blob/main/codex-rs/config.md> for the full list
+of options.
+
+## Custom instructions
+
+Provide repo- or user-specific guidance via an AGENTS file:
+
+```nix
+programs.codex.custom-instructions = ''
+  - Run `nix flake check` before suggesting commands
+  - Avoid network access unless requested
+'';
+```
+
+This is written to `AGENTS.md` in the same directory as `config.toml`.
+
+## Version guard
+
+Set `programs.codex.package` to a 0.2.0+ build if you override the package. The
+module asserts the version to avoid accidental YAML-era configurations.
+
+## Example full configuration
+
+```nix
+programs.codex = {
+  enable = true;
+  package = pkgs.codex; # ensures >= 0.2.0
+  settings = {
+    model = "gpt-5.1";
+    model_provider = "openai";
+    model_providers = {
+      openai = {
+        name = "OpenAI";
+        baseURL = "https://api.openai.com/v1";
+        envKey = "OPENAI_API_KEY";
+      };
+    };
+    model_reasoning_effort = "medium";
+    model_reasoning_summary = "auto";
+    approval_policy = "on-request";
+    sandbox_mode = "workspace-write";
+    sandbox_workspace_write = {
+      network_access = false;
+      writable_roots = [ "${config.home.homeDirectory}/.cache" ];
+    };
+    features = {
+      web_search_request = false;
+      apply_patch_freeform = true;
+      view_image_tool = true;
+      unified_exec = true;
+    };
+    tools.view_image = true;
+    shell_environment_policy = {
+      inherit = "core";
+      set = { CI = "1"; };
+      exclude = [ "AWS_*" "GCP_*" ];
+    };
+    # Real MCP server example: filesystem server from the official MCP catalog.
+    # Provides read/write tools within the specified roots.
+    mcp_servers = {
+      filesystem = {
+        command = "npx";
+        args = [
+          "-y"
+          "@modelcontextprotocol/server-filesystem"
+          "${config.home.homeDirectory}/projects"
+        ];
+        enabled = true;
+        tool_timeout_sec = 30;
+      };
+    };
+    otel.exporter = "none";
+  };
+  custom-instructions = ''
+    - Run `nix flake check` before suggesting commands
+    - Avoid network access unless explicitly requested
+  '';
+};
+```

modules/misc/news/2025/11/2025-11-25_15-00-00.nix

@@ -0,0 +1,11 @@
+{ config, ... }:
+
+{
+  time = "2025-11-25T15:00:00+00:00";
+  condition = config.programs.codex.enable;
+  message = ''
+    programs.codex now targets Codex >= 0.2.0 and always writes config.toml.
+
+    YAML (<0.2.0) support was removed; set programs.codex.package accordingly if you need a newer build.
+  '';
+}

modules/programs/codex.nix

@@ -10,11 +10,6 @@ let
   cfg = config.programs.codex;
 
   tomlFormat = pkgs.formats.toml { };
-  yamlFormat = pkgs.formats.yaml { };
-
-  packageVersion = if cfg.package != null then lib.getVersion cfg.package else "0.2.0";
-  isTomlConfig = lib.versionAtLeast packageVersion "0.2.0";
-  settingsFormat = if isTomlConfig then tomlFormat else yamlFormat;
 in
 {
   meta.maintainers = [
@@ -27,13 +22,12 @@ in
     package = lib.mkPackageOption pkgs "codex" { nullable = true; };
 
     settings = lib.mkOption {
-      # NOTE: `yaml` type supports null, using `nullOr` for backwards compatibility period
-      type = lib.types.nullOr tomlFormat.type;
+      type = tomlFormat.type;
       description = ''
-        Configuration written to {file}`CODEX_HOME/config.toml` (0.2.0+)
-        or {file}`~/.codex/config.yaml` (<0.2.0). Per default {env}`CODEX_HOME`
-        defaults to ~/.codex.
-        See <https://github.com/openai/codex/blob/main/codex-rs/config.md> for supported values.
+        Configuration is written to {file}`CODEX_HOME/config.toml`. By default {env}`CODEX_HOME`
+        points to {file}`~/.codex`; when {option}`home.preferXdgDirectories` is enabled it
+        switches to {file}`~/.config/codex/`.
+        See <https://github.com/openai/codex/blob/main/codex-rs/config.md> for supported keys.
       '';
       default = { };
       defaultText = lib.literalExpression "{ }";
@@ -66,17 +60,23 @@ in
 
   config =
     let
-      useXdgDirectories = (config.home.preferXdgDirectories && isTomlConfig);
+      useXdgDirectories = config.home.preferXdgDirectories;
       xdgConfigHome = lib.removePrefix config.home.homeDirectory config.xdg.configHome;
       configDir = if useXdgDirectories then "${xdgConfigHome}/codex" else ".codex";
-      configFileName = if isTomlConfig then "config.toml" else "config.yaml";
     in
     mkIf cfg.enable {
+      assertions = [
+        {
+          assertion = cfg.package == null || lib.versionAtLeast (lib.getVersion cfg.package) "0.2.0";
+          message = "programs.codex requires codex >= 0.2.0 (TOML config only)";
+        }
+      ];
+
       home = {
         packages = mkIf (cfg.package != null) [ cfg.package ];
         file = {
-          "${configDir}/${configFileName}" = lib.mkIf (cfg.settings != { }) {
-            source = settingsFormat.generate "codex-config" cfg.settings;
+          "${configDir}/config.toml" = lib.mkIf (cfg.settings != { }) {
+            source = tomlFormat.generate "codex-config" cfg.settings;
           };
           "${configDir}/AGENTS.md" = lib.mkIf (cfg.custom-instructions != "") {
             text = cfg.custom-instructions;

tests/modules/programs/codex/default.nix

@@ -1,7 +1,6 @@
 {
   codex-settings-toml = ./settings-toml.nix;
   codex-settings-toml-prefer-xdg-directories = ./settings-toml-prefer-xdg-directories.nix;
-  codex-settings-yaml = ./settings-yaml.nix;
   codex-empty-settings = ./empty-settings.nix;
   codex-custom-instructions = ./custom-instructions.nix;
   codex-custom-instructions-prefer-xdg-directories = ./custom-instructions-prefer-xdg-directories.nix;