docs: verify Codex marketplace readiness (#1931)

.agents/plugins/marketplace.json

@@ -9,7 +9,7 @@
       "version": "2.0.0-rc.1",
       "source": {
         "source": "local",
-        "path": "../.."
+        "path": "./"
       },
       "policy": {
         "installation": "AVAILABLE",

.codex-plugin/README.md

@@ -18,18 +18,28 @@ This directory contains the **Codex plugin manifest** for Everything Claude Code
 
 ## Installation
 
-Codex plugin support is currently in preview. Once generally available:
+Codex plugin support is currently marketplace-backed. The repo exposes a
+repo-scoped marketplace at `.agents/plugins/marketplace.json`; Codex can add and
+track that marketplace source from the CLI:
 
 ```bash
-# Install from Codex CLI
+# Add the public repo marketplace
-codex plugin install affaan-m/everything-claude-code
+codex plugin marketplace add affaan-m/everything-claude-code
 
-# Or reference locally during development
+# Or add a local checkout while developing
-codex plugin install ./
+codex plugin marketplace add /absolute/path/to/everything-claude-code
-
-Run this from the repository root so `./` points to the repo root and `.mcp.json` resolves correctly.
 ```
 
+The marketplace entry points at the repository root so `.codex-plugin/plugin.json`,
+`skills/`, and `.mcp.json` resolve from one shared source of truth. After adding
+or updating the marketplace, restart Codex and install or enable `ecc` from the
+plugin directory.
+
+Official Plugin Directory publishing is coming soon in Codex. Until self-serve
+publishing exists, treat the public repo marketplace as the supported Codex
+distribution path and keep release copy framed as repo-marketplace/manual
+installation.
+
 The installed plugin registers under the short slug `ecc` so tool and command names
 stay below provider length limits.
 

docs/releases/2.0.0-rc.1/naming-and-publication-matrix.md

@@ -44,6 +44,7 @@ Reason:
 | Claude marketplace entry | `ecc` | `.claude-plugin/marketplace.json` | Version and repo point at current rc.1 surface | Keep |
 | Codex plugin slug | `ecc` | `node -p "require('./.codex-plugin/plugin.json').name"` | `ecc` | Keep |
 | Codex plugin version | `2.0.0-rc.1` | `node tests/docs/ecc2-release-surface.test.js` | Release surface test passed | Ready for Codex marketplace/manual marketplace gate |
+| Codex repo marketplace | `ecc` | `.agents/plugins/marketplace.json`; `codex plugin marketplace add --help` | Repo marketplace add supports GitHub shorthand and local roots; local temp-home add smoke passed | Use as rc.1 Codex distribution path |
 | OpenCode package | `ecc-universal` | `node -p "require('./.opencode/package.json').name"` | `ecc-universal` | Keep |
 | OpenCode build | Generated package output | `npm run build:opencode` | Passed | Ready for package dry-run gate |
 | npm pack surface | Reduced runtime package | `npm pack --dry-run --json` | Produced `ecc-universal-2.0.0-rc.1.tgz`, 969 entries, about 5.0 MB unpacked | Needs final release-commit rerun |
@@ -56,7 +57,7 @@ Reason:
 | npm | `ecc-universal` local package version is `2.0.0-rc.1`; registry latest is `1.10.0` | Publish rc with `npm publish --tag next` after final `npm pack --dry-run` and release tests | Do not publish before final release commit |
 | Claude plugin | `claude plugin validate .claude-plugin/plugin.json` passed; `claude plugin tag --help` confirms the release tag flow creates `{name}--v{version}` tags and can push them | Run `claude plugin tag .claude-plugin --dry-run` from the clean release commit, then tag/push only after release approval | No plugin release tag created in this pass |
 | Claude marketplace | `.claude-plugin/marketplace.json` points at `ecc` and the public repo | Verify marketplace update/install path after tag exists | External marketplace propagation not verified |
-| Codex plugin | `codex plugin marketplace` supports add/upgrade/remove; `.codex-plugin/plugin.json` is present and release-surface tests pass | Confirm marketplace source format, then test add/upgrade from the public repo or marketplace source | No public Codex marketplace submission path verified in this pass |
+| Codex plugin | `codex plugin marketplace` supports add/upgrade/remove; `.codex-plugin/plugin.json` is present; `.agents/plugins/marketplace.json` exposes `ecc` from the repo root; temp-home local `codex plugin marketplace add` passed | Publish rc.1 docs with the repo-marketplace command, then monitor OpenAI's official Plugin Directory self-serve path | Official Plugin Directory publishing is documented as coming soon |
 | OpenCode package | `.opencode/package.json` builds from source and ships inside npm package | Re-run `npm run build:opencode` and package dry-run from release commit | OpenCode CLI 1.2.21 does not expose a separate plugin publication command in this pass |
 | ECC Tools billing claim | README and launch copy mention ECC Tools / marketplace context | ECC-Tools #73 adds `/api/billing/readiness` `announcementGate`; run it against a Marketplace-managed test account before any payment announcement | Billing announcement code gate exists; live Marketplace account readback still pending |
 | Social and longform copy | X thread, LinkedIn copy, article outline, GitHub release copy exist | Replace any stale URLs, then publish only after release/npm/plugin URLs work | Public URLs not final until release actions complete |
@@ -116,4 +117,12 @@ Passed.
 
 npm pack --dry-run --json
 Produced ecc-universal-2.0.0-rc.1.tgz, 969 entries, about 5.0 MB unpacked.
+
+codex plugin marketplace add --help
+Supports GitHub shorthand, HTTP(S) Git URLs, SSH URLs, local marketplace roots,
+--ref, and Git-only --sparse.
+
+HOME="$(mktemp -d)" codex plugin marketplace add <local-checkout>
+Added marketplace ecc and recorded the installed marketplace root as
+<local-checkout> without touching the real Codex config.
 ```

docs/releases/2.0.0-rc.1/preview-pack-manifest.md

@@ -85,7 +85,8 @@ surfaces exist and are recorded in a final evidence file:
 - GitHub prerelease `v2.0.0-rc.1`;
 - npm `ecc-universal@2.0.0-rc.1` on the `next` dist-tag;
 - Claude plugin tag / marketplace propagation for `ecc@ecc`;
-- Codex plugin publication or owner-approved manual submission path;
+- Codex repo-marketplace distribution evidence plus official Plugin Directory
+  availability status;
 - final announcement URLs in X, LinkedIn, GitHub release, and longform copy;
 - ECC Tools billing/product readiness evidence before any native-payments
   announcement copy is published.

docs/releases/2.0.0-rc.1/publication-evidence-2026-05-15.md

@@ -112,13 +112,35 @@ merge.
 The preview pack is assembled for final clean-checkout gating, but it is still
 not a publication action.
 
+## Codex Marketplace Evidence
+
+OpenAI's current Codex plugin docs now distinguish repo/personal marketplace
+distribution from the official Plugin Directory. Repo marketplaces live at
+`.agents/plugins/marketplace.json`; `codex plugin marketplace add <source>`
+can add GitHub shorthand, Git URLs, SSH URLs, or local marketplace roots.
+Official Plugin Directory publishing and self-serve management are documented
+as coming soon:
+
+- <https://developers.openai.com/codex/plugins/build#add-a-marketplace-from-the-cli>
+- <https://developers.openai.com/codex/plugins/build#how-codex-uses-marketplaces>
+- <https://developers.openai.com/codex/plugins/build#publish-official-public-plugins>
+
+| Surface | Evidence |
+| --- | --- |
+| CLI shape | `codex plugin marketplace add --help` supports GitHub shorthand, Git URLs, SSH URLs, local marketplace roots, `--ref`, and Git-only `--sparse` |
+| Repo marketplace | `.agents/plugins/marketplace.json` exposes `ecc@2.0.0-rc.1` with `source.path: "./"` from the marketplace root |
+| Local add smoke | `HOME="$(mktemp -d)" codex plugin marketplace add <local-checkout>` added marketplace `ecc` and recorded the installed marketplace root as `<local-checkout>` without touching the real Codex config |
+| README alignment | `.codex-plugin/README.md` now uses `codex plugin marketplace add`, not the stale `codex plugin install` command |
+| Public-directory status | The supported Codex distribution path for rc.1 is repo-marketplace/manual install; official Plugin Directory submission remains blocked on OpenAI self-serve publishing availability |
+
 ## Current Publication Blockers
 
 - GitHub prerelease `v2.0.0-rc.1` is still not created in this pass.
 - npm `ecc-universal@2.0.0-rc.1` is still not published to the `next` dist-tag.
 - Claude plugin tag and marketplace propagation remain approval-gated.
-- Codex plugin public marketplace/manual submission path still needs final
+- Codex plugin repo-marketplace distribution is verified for rc.1, but official
-  owner verification.
+  Plugin Directory publishing is still blocked on OpenAI's coming-soon
+  self-serve publishing surface.
 - ECC Tools PR #73 added a fail-closed `/api/billing/readiness`
   `announcementGate` for native GitHub payments claims, and ECC Tools PR #74
   added `npm run billing:announcement-gate` as the operator verifier, but the

docs/releases/2.0.0-rc.1/publication-readiness.md

@@ -31,6 +31,7 @@ follow-up evidence refresh after PR #1921, see
 | Claude plugin slug | `ecc` / `ecc@ecc` install path | `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` | `node tests/hooks/hooks.test.js` | `publication-evidence-2026-05-12.md` | Plugin owner | Evidence recorded |
 | Claude plugin manifest | `2.0.0-rc.1`, no unsupported `agents` or explicit `hooks` fields | `.claude-plugin/plugin.json`, `.claude-plugin/PLUGIN_SCHEMA_NOTES.md` | `claude plugin validate .claude-plugin/plugin.json` | `publication-evidence-2026-05-12.md` | Plugin owner | Evidence recorded |
 | Codex plugin manifest | `2.0.0-rc.1` with shared skill source | `.codex-plugin/plugin.json` | `node tests/docs/ecc2-release-surface.test.js` | `publication-evidence-2026-05-12.md` | Plugin owner | Evidence recorded |
+| Codex repo marketplace | `ecc@2.0.0-rc.1` exposed through `.agents/plugins/marketplace.json` | `.agents/plugins/marketplace.json`, `.codex-plugin/README.md` | `HOME="$(mktemp -d)" codex plugin marketplace add <local-checkout>` | `publication-evidence-2026-05-15.md` | Plugin owner | Repo-marketplace path verified; official Plugin Directory publishing coming soon |
 | OpenCode package | `ecc-universal` plugin module | `.opencode/package.json`, `.opencode/index.ts` | `npm run build:opencode` | `publication-evidence-2026-05-12.md` | Package owner | Evidence recorded |
 | Agent metadata | `2.0.0-rc.1` | `agent.yaml`, `.agents/plugins/marketplace.json` | `node tests/scripts/catalog.test.js` | `publication-evidence-2026-05-12.md` | Release owner | Evidence recorded |
 | Migration copy | rc.1 upgrade path, not GA claim | `release-notes.md`, `quickstart.md`, `HERMES-SETUP.md` | `npx markdownlint-cli '**/*.md' --ignore node_modules` | `publication-evidence-2026-05-13.md` | Docs owner | Evidence recorded |
@@ -42,7 +43,7 @@ follow-up evidence refresh after PR #1921, see
 | GitHub release | Tag exists, release notes use final URLs, assets attached if needed | `gh release view v2.0.0-rc.1 --json tagName,url,isPrerelease` | `Blocker: release not found on 2026-05-12` | Release owner | Pending approval |
 | npm package | `npm pack --dry-run` has expected files, version matches, rc goes to `next` | `npm pack --dry-run` and `npm publish --tag next --dry-run` where supported | `Blocker: actual publish requires approval; dry run passed with next tag` | Package owner | Dry-run passed |
 | Claude plugin | Manifest validates, marketplace JSON points to public repo, install docs match slug | `claude plugin validate .claude-plugin/plugin.json`; `claude plugin tag .claude-plugin --dry-run`; isolated temp-home install smoke | `Blocker: real tag creation/push requires approval` | Plugin owner | Clean-checkout dry-run and install smoke recorded |
-| Codex plugin | Manifest version matches package and docs, hook limitations are explicit | `node tests/docs/ecc2-release-surface.test.js` | `Blocker: marketplace submission path still manual/owner-gated` | Plugin owner | Evidence recorded |
+| Codex plugin | Manifest version matches package and docs, repo marketplace points at the plugin root, and OpenAI's current official Plugin Directory status is recorded | `node tests/docs/ecc2-release-surface.test.js`; `node tests/plugin-manifest.test.js`; `codex plugin marketplace add --help`; temp-home `codex plugin marketplace add <local-checkout>` | `Blocker: official Plugin Directory publishing and self-serve management are documented as coming soon` | Plugin owner | Repo-marketplace distribution verified; official directory pending |
 | OpenCode package | Build output is regenerated from source and package metadata is current | `npm run build:opencode` | `Blocker: none for local build; public distribution still follows npm/plugin release` | Package owner | Evidence recorded |
 | ECC Tools billing reference | Any billing claim links to verified Marketplace/App state | `env -u GITHUB_TOKEN gh repo view ECC-Tools/ECC-Tools --json nameWithOwner,isPrivate,viewerPermission` plus internal `/api/billing/readiness?accountLogin=<marketplace-test-account>` readback | `Blocker: ECC-Tools #73 added announcementGate; live Marketplace test-account readback must return announcementGate.ready === true before payment announcement` | ECC Tools owner | Code gate recorded; live billing readback pending |
 | Announcement copy | X, LinkedIn, GitHub release, and longform copy point to live URLs | `rg -n "TODO" docs/releases/2.0.0-rc.1` and repeat for `TBD` | `Blocker: final live release/npm/plugin URLs do not exist yet` | Release owner | Pending |

tests/docs/ecc2-release-surface.test.js

@@ -181,7 +181,7 @@ test('preview pack manifest assembles release, Hermes, and publication gates', (
     'GitHub prerelease `v2.0.0-rc.1`',
     'npm `ecc-universal@2.0.0-rc.1`',
     'Claude plugin tag',
-    'Codex plugin publication',
+    'Codex repo-marketplace distribution evidence',
     'ECC Tools billing/product readiness',
   ]) {
     assert.ok(manifest.includes(blocker), `preview pack manifest missing blocker ${blocker}`);
@@ -254,6 +254,7 @@ test('publication readiness checklist gates public release actions on evidence',
     'npm package',
     'Claude plugin',
     'Codex plugin',
+    'Codex repo marketplace',
     'OpenCode package',
     'ECC Tools billing reference',
     'Announcement copy',
@@ -265,8 +266,12 @@ test('publication readiness checklist gates public release actions on evidence',
   assert.ok(may15Evidence.includes('PR #1921'));
   assert.ok(may15Evidence.includes('AgentShield PR #83'));
   assert.ok(may15Evidence.includes('ECC Tools PR #73'));
+  assert.ok(may15Evidence.includes('## Codex Marketplace Evidence'));
+  assert.ok(may15Evidence.includes('codex plugin marketplace add <local-checkout>'));
+  assert.ok(may15Evidence.includes('Plugin Directory publishing is still blocked'));
   assert.ok(may15Evidence.includes('announcementGate.ready === true'));
   assert.ok(source.includes('ECC-Tools #73 added announcementGate'));
+  assert.ok(source.includes('official Plugin Directory publishing and self-serve management are documented as coming soon'));
   assert.ok(may15Evidence.includes('| Trunk discussions | GraphQL discussion count and maintainer-touch sweep | 58 total discussions;'));
   assert.ok(source.includes('58 trunk discussions, 0 without maintainer touch'));
   assert.ok(may15Evidence.includes('env -u GITHUB_TOKEN'));

tests/plugin-manifest.test.js

@@ -433,11 +433,15 @@ test('marketplace local plugin path resolves to the repo-root Codex bundle', ()
       continue;
     }
 
-    const resolvedRoot = path.resolve(path.dirname(marketplacePath), plugin.source.path);
+    assert.ok(
+      plugin.source.path.startsWith('./'),
+      `Codex marketplace source.path must be ./-prefixed: ${plugin.source.path}`,
+    );
+    const resolvedRoot = path.resolve(repoRoot, plugin.source.path);
     assert.strictEqual(
       resolvedRoot,
       repoRoot,
-      `Expected local marketplace path to resolve to repo root, got: ${plugin.source.path}`,
+      `Expected local marketplace path to resolve to repo root from marketplace root, got: ${plugin.source.path}`,
     );
     assert.ok(
       fs.existsSync(path.join(resolvedRoot, '.codex-plugin', 'plugin.json')),
@@ -512,6 +516,22 @@ test('user-facing docs do not use the legacy non-URL marketplace add form', () =
   );
 });
 
+test('.codex-plugin README uses current marketplace add flow', () => {
+  const readme = fs.readFileSync(path.join(repoRoot, '.codex-plugin', 'README.md'), 'utf8');
+  assert.ok(
+    readme.includes('codex plugin marketplace add'),
+    'Expected .codex-plugin README to document codex plugin marketplace add',
+  );
+  assert.ok(
+    readme.includes('Official Plugin Directory publishing is coming soon'),
+    'Expected .codex-plugin README to document current official directory status',
+  );
+  assert.ok(
+    !/\bcodex plugin install\b/.test(readme),
+    'codex plugin install is not a current Codex CLI command',
+  );
+});
+
 test('docs/zh-CN/README.md version row matches package.json', () => {
   const readme = fs.readFileSync(zhCnReadmePath, 'utf8');
   const match = readme.match(new RegExp(`^\\| \\*\\*版本\\*\\* \\| 插件 \\| 插件 \\| 参考配置 \\| (${semverPattern}) \\|$`, 'm'));