docs(3562): pin minimum Codex CLI version (0.130.0) and explain the seam

Rationale for the version pin (the timeline that produced the oscillation):

  2026-05-08  Codex CLI 0.130.0 ships, dropping extra-skills-roots
              discovery via openai/codex#21485 (scans only ~/.codex/skills,
              cwd .codex/skills, and registered plugin roots).
  2026-05-14  GSD PR #3512 lands, removing ~/.codex/skills/gsd-* under the
              assumption Codex would auto-discover from extra roots.
              That assumption was already obsolete in shipped Codex.
  2026-05-15  #3562 filed — Codex CLI 0.130.0 users have zero $gsd-*
              commands after install.

The previous fix (#3427) was for Codex Desktop's official-skills surface,
which is a different product; that surface still exists on Desktop and
remains harmless duplication when both root scans see the gsd-* dirs.

Documents the supported version inline at the Codex sections of both
USER-GUIDE.md and CONFIGURATION.md, plus a one-line note in README's
Troubleshooting block. No runtime version-detection added — out of scope
and brittle against future Codex changes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

README.md

@@ -222,6 +222,8 @@ For the full configuration reference — all settings, git branching strategies,
 
 **Commands not showing up?** Restart your runtime after install. GSD installs to `~/.claude/skills/gsd-*/` (Claude Code), `~/.codex/skills/gsd-*/` (Codex), or the equivalent for your runtime.
 
+**Codex users — minimum supported CLI version is `0.130.0`.** Codex CLI 0.130.0 ([release notes](https://github.com/openai/codex/releases/tag/rust-v0.130.0)) removed extra-skill-roots discovery via [openai/codex#21485](https://github.com/openai/codex/pull/21485); from that version onward Codex only discovers skills from `~/.codex/skills/<name>/SKILL.md`. GSD installs there directly. Earlier Codex CLI versions may show duplicate `gsd-*` entries (one from extra-roots discovery, one from `~/.codex/skills/`); restart Codex after install and either upgrade or accept the duplicate listing.
+
 **Something broken?** Re-run the installer — it's idempotent:
 ```bash
 npx get-shit-done-cc@latest

docs/CONFIGURATION.md

@@ -968,6 +968,10 @@ The `dynamic_routing` block is **disabled by default** — `enabled: false` (or
 
 ### Non-Claude Runtimes (Codex, OpenCode, Gemini CLI, Kilo)
 
+> **Codex CLI minimum supported version: `0.130.0`** (issue [#3562](https://github.com/gsd-build/get-shit-done/issues/3562)).
+>
+> [Codex CLI 0.130.0](https://github.com/openai/codex/releases/tag/rust-v0.130.0) (released 2026-05-08) removed extra-skills-roots discovery via [openai/codex#21485](https://github.com/openai/codex/pull/21485). From this version forward, Codex CLI only scans `~/.codex/skills/<name>/SKILL.md`, `<project>/.codex/skills/`, and registered plugin roots for invocable skills. GSD installs the `$gsd-*` surface as `~/.codex/skills/gsd-<name>/SKILL.md` so commands resolve after a Codex restart. Earlier Codex CLI versions can show a duplicate listing (the legacy extra-roots scan plus the user-root copies) — restart Codex and either upgrade to ≥ 0.130.0 or accept the duplicates until you do.
+
 When GSD is installed for a non-Claude runtime, the installer automatically sets `resolve_model_ids: "omit"` in `~/.gsd/defaults.json`. This causes GSD to return an empty model parameter for all agents, so each agent uses whatever model the runtime is configured with. No additional setup is needed for the default case.
 
 If you want different agents to use different models, use `model_overrides` with fully-qualified model IDs that your runtime recognizes:

docs/USER-GUIDE.md

@@ -1219,6 +1219,12 @@ For the full audit, harness reference, and the composition note with `model_prof
 
 ### Using Non-Claude Runtimes (Codex, OpenCode, Gemini CLI, Kilo)
 
+> **Codex CLI minimum supported version: `0.130.0`** (issue [#3562](https://github.com/gsd-build/get-shit-done/issues/3562)).
+>
+> Codex CLI [0.130.0](https://github.com/openai/codex/releases/tag/rust-v0.130.0) (released 2026-05-08) removed extra-skills-roots discovery via [openai/codex#21485](https://github.com/openai/codex/pull/21485). From that version onward, Codex only discovers commands from `~/.codex/skills/<name>/SKILL.md` (user root), `<project>/.codex/skills/` (cwd root), and registered plugin roots. The GSD installer writes `~/.codex/skills/gsd-<name>/SKILL.md` directly so `$gsd-help`, `$gsd-new-project`, etc. are discoverable after restart.
+>
+> **Earlier Codex CLI versions** (pre-0.130.0) had additional skill-root scanning that discovered the GSD agent/workflow files in alternate locations. GSD still installs the `~/.codex/skills/gsd-*` copies on those versions, which can show a duplicate listing alongside the legacy auto-discovered surface — restart Codex after install and either upgrade to ≥ 0.130.0 or accept the duplicate entries until you do.
+
 If you installed GSD for a non-Claude runtime, the installer already configured model resolution so all agents use the runtime's default model. No manual setup is needed. Specifically, the installer sets `resolve_model_ids: "omit"` in your config, which tells GSD to skip Anthropic model ID resolution and let the runtime choose its own default model.
 
 To assign different models to different agents on a non-Claude runtime, add `model_overrides` to `.planning/config.json` with fully-qualified model IDs that your runtime recognizes:

tests/install-minimal-all-runtimes.test.cjs

@@ -180,8 +180,12 @@ function expectedSkillSet() {
 }
 
 function expectedManifestSkillSet(runtime) {
-  // Codex no longer materializes gsd-* skill files in minimal mode.
-  if (runtime === 'codex') return new Set();
+  // Codex CLI 0.130.0 does not auto-discover commands from workflow / agent
+  // files (#3562) — it only registers commands from skills/<name>/SKILL.md.
+  // Codex installs therefore materialize the same minimal-allowlist skill
+  // surface as the other runtimes; the prior "Codex discovers official
+  // skills directly" assumption (which led to an empty Codex skill set
+  // here) does not hold in practice.
   return expectedSkillSet();
 }
 

tests/installer-migration-install-integration.test.cjs

@@ -209,11 +209,11 @@ function assertFreshInstallContract(runtime, targetDir) {
   );
 
   if (contract.surface === 'flat-skills') {
-    if (runtime === 'codex') {
-      assertNoGsdDirectoryEntries(targetDir, 'skills');
-    } else {
-      assertHasGsdDirectory(targetDir, 'skills');
-    }
+    // Pre-#3562: codex was special-cased to expect zero gsd-* skill dirs
+    // (assumption: Codex auto-discovers from workflows). That assumption
+    // does not hold for Codex CLI 0.130.0 — fresh installs now materialize
+    // the same flat-skills surface as the other runtimes.
+    assertHasGsdDirectory(targetDir, 'skills');
   } else if (contract.surface === 'hermes-skills') {
     assertHasGsdDirectory(targetDir, path.join('skills', 'gsd'));
     assert.ok(