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>
This commit is contained in:
Tom Boucher
2026-05-15 13:46:12 -04:00
parent 365340596d
commit 08848df839
5 changed files with 23 additions and 7 deletions

View File

@@ -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();
}

View File

@@ -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(