Polish: CI workflows + 3 Codex lints + Codex-tailored docs + logo

CI workflows (vendored from cursor-lua-agent-builder, adapted):
  - .github/workflows/ci.yml: matrix [macos-14, ubuntu-22.04, windows-2022]
    × [node 18, 20], plus standalone mcp build/test job
  - .github/workflows/release-prod.yml: tag prefix `codex-v` (vs Cursor's
    `cursor-v` and CC's `v`); skip-not-fail when tag exists; tarball
    name corrected to codex-lua-plugin-<v>.tar.gz

Three new Codex-specific lints:
  - lint-codex-manifest.mjs: validates .codex-plugin/plugin.json against
    Codex's documented schema (required: name + version + description;
    name kebab-case; semver version; only known optional fields).
  - lint-codex-mcp-config.mjs: validates .mcp.json's source tree
    references resolve (mirrors Cursor port pattern — checks source not
    built artifact, since dist/ is gitignored).
  - lint-codex-no-claude-root.mjs: catches stray ${CLAUDE_PLUGIN_ROOT}
    OR ${CURSOR_PLUGIN_ROOT} refs that didn't get converted (Codex
    auto-resolves bundled-asset paths from the plugin root, no host
    variable needed).

Docs rewritten for Codex (were vendored Cursor content):
  - docs/USER_GUIDE.md: install via `codex plugin marketplace add` +
    `codex plugin install`; troubleshooting tailored to Codex; subagent
    section explains TOML format + natural-language dispatch.
  - docs/TESTERS.md: 5-min setup with Codex-CLI prereq, sanity check
    aimed at tester audience, "what we're watching for" section
    highlights Codex-specific seams (TOML agent parsing, plugin install
    success, hook event coverage).
  - SECURITY.md: scope updated for Codex paths; safety-contract table
    correct; hook safety model section explains Codex's protocol
    (Claude-Code-shaped, exit 2 + JSON envelope) + the matcher self-
    filtering proactive defense.

Logo: 400×400 official Lua logo at repo root for marketplace listings.

All 12 lints pass, 248/248 tests pass locally. Ready to ship to testers.

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

Author: lua-stefan-kruger

.github/workflows/ci.yml

@@ -6,12 +6,15 @@ on:
   pull_request:
     branches: [main, staging]
 
-# Single-plugin repo (no plugins/ subdir, unlike claude-code-lua-plugin which is
-# a marketplace catalog). Working directory is the repo root.
+# Single-plugin repo (no plugins/ subdir, unlike claude-code-lua-plugin which
+# is a marketplace catalog). Working directory is the repo root.
 #
-# Cross-platform matrix because the plugin must work on macOS, Linux, and
-# Windows — the same coverage as the Claude Code plugin (Node ESM hooks,
-# AbortSignal.timeout, path handling all need verification per cell).
+# Cross-platform matrix: the plugin's hook scripts and MCP server must work
+# on macOS, Linux, and Windows — same coverage discipline as the Claude Code
+# and Cursor ports (Node ESM hooks, AbortSignal.timeout, path handling all
+# need verification per cell). Codex CLI itself is not exercised in CI;
+# the install script's preflight checks for `codex` on PATH at user-install
+# time, but CI tests the bundled hooks/MCP/lints in isolation.
 
 jobs:
   plugin:

.github/workflows/release-prod.yml

@@ -8,8 +8,8 @@ on:
 # package.json version was bumped. If the tag already exists (no version
 # bump), the release step is skipped — lints + tests still run.
 #
-# Tag prefix is `cursor-v` (claude-code-lua-plugin uses `v`) to keep the two
-# repos' tags from colliding when cross-referenced.
+# Tag prefix is `codex-v` (Cursor port uses `cursor-v`, claude-code-lua-plugin
+# uses `v`) to keep the four repos' tags from colliding when cross-referenced.
 
 permissions:
   contents: write
@@ -61,7 +61,7 @@ jobs:
             echo "::error::Production release requires a stable version in package.json (no -beta/-rc/-alpha suffix). Got: ${VERSION}"
             exit 1
           fi
-          echo "tag=cursor-v${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "tag=codex-v${VERSION}" >> "$GITHUB_OUTPUT"
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
           echo "Production version: ${VERSION}"
 
@@ -79,7 +79,7 @@ jobs:
         if: steps.tag_check.outputs.skip != 'true'
         run: |
           node scripts/pack.mjs
-          TARBALL="cursor-lua-agent-builder-${{ steps.version.outputs.version }}.tar.gz"
+          TARBALL="codex-lua-plugin-${{ steps.version.outputs.version }}.tar.gz"
           ls -lh "${TARBALL}"
           echo "TARBALL=${TARBALL}" >> "$GITHUB_ENV"
 

SECURITY.md

@@ -10,28 +10,28 @@ We aim to acknowledge within 2 business days and ship a fix within 30 days for h
 
 This plugin's surface includes:
 
-- **Skills** (`skills/<name>/SKILL.md`) — Markdown prompts that Cursor loads as `/lua-*` slash commands. Symlinked into `~/.cursor/skills-cursor/` by `scripts/install.mjs`.
-- **Subagents** (`agents/*.md`) — referenced by skills; specialised assistants for architect/build/debug/deploy/QA flows.
-- **Hooks** (`hooks/*.mjs`) — run as Node subprocesses on `sessionStart`, `beforeSubmitPrompt`, `beforeShellExecution`, `afterShellExecution` events. Registered in `~/.cursor/hooks.json` by the install script.
-- **MCP server** (`mcp/lua-platform/dist/server.js`) — a stdio MCP server exposing 5 read-only tools. Talks to `https://api.heylua.ai` over HTTPS using the user's API key. Registered in `~/.cursor/mcp.json`.
+- **Skills** (`skills/<name>/SKILL.md`) — Markdown prompts that Codex loads as `/lua-*` slash commands. Bundled via the plugin manifest at `.codex-plugin/plugin.json`.
+- **Subagents** (`agents/*.toml`) — Codex TOML-format subagent definitions with `name`, `description`, `developer_instructions`. Bundled with the plugin.
+- **Hooks** (`hooks/*.mjs`) — run as Node subprocesses on `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse` events. Registered in `hooks/hooks.json` (Claude-Code-shaped schema; Codex consumes it natively).
+- **MCP server** (`mcp/lua-platform/dist/server.js`) — a stdio MCP server exposing 5 read-only tools. Talks to `https://api.heylua.ai` over HTTPS using the user's API key. Registered in `.mcp.json`.
 - **Rules** (`rules/*.mdc`) — knowledge files attached to the architect agent's context via `@-mention`.
-- **Install script** (`scripts/install.mjs`) — modifies `~/.cursor/mcp.json` and `~/.cursor/hooks.json` (always with backup). Runs only when explicitly invoked by the user.
+- **Install script** (`scripts/install.mjs`) — runs `codex plugin marketplace add` + `codex plugin install`. Does not modify any user files outside Codex's plugin cache (`~/.codex/plugins/cache/`).
 
 In scope for security reports:
 
 - Credential exposure (API keys leaking into transcripts, logs, environment, or external systems)
 - Safety-gate bypasses (deploys or destructive operations succeeding without the documented confirmation)
 - Hook payload injection (a maliciously-shaped command triggering unintended hook behavior)
 - MCP server auth bypass
-- Install script writing outside `~/.cursor/` or executing without explicit user invocation
-- Symlink-target manipulation (an installed skill resolving to a path outside the cloned plugin)
+- Symlink-target manipulation (a bundled component resolving to a path outside the cloned plugin)
 
 Out of scope:
 
-- Bugs in `lua-cli` itself (report to the lua-cli repo or via security@heylua.ai with `[lua-cli]` in the subject)
+- Bugs in `lua-cli` itself (report to security@heylua.ai with `[lua-cli]` in the subject)
 - Bugs in `lua-api` (report to security@heylua.ai with `[lua-api]` in the subject)
+- Bugs in Codex CLI itself (report to OpenAI)
 - Issues in user-installed third-party MCP servers
-- Social-engineering / phishing of an Lua API key from a user
+- Social-engineering / phishing of a Lua API key from a user
 
 ## Safety-critical contracts
 
@@ -41,25 +41,26 @@ The plugin enforces several safety contracts. Bypasses count as security issues.
 |---|---|
 | **§3.3 deploy gate**: bare `lua deploy` is denied | `hooks/before-shell-execution.mjs` (umbrella) + `hooks/confirm-deploy.mjs` (dedicated) |
 | **§3.3 auto-deploy block**: `--auto-deploy` is denied | `hooks/before-shell-execution.mjs` + `hooks/block-auto-deploy.mjs` |
-| **Credential isolation**: API key never enters chat transcript | `hooks/before-shell-execution.mjs` denies `lua auth key*` invocations + `commands/lua-doctor.md` Step 4 uses an authenticated metadata probe (`lua agents --json --ci`), not a key-printing command |
-| **§3.7 single-permission contract**: each skill asks at most one prompt per invocation | Convention enforced in skill bodies; not yet machine-checked in the Cursor port (was lint-checked in the Claude Code plugin via `scripts/lint-single-permission.mjs`) |
+| **Credential isolation**: API key never enters chat transcript | `hooks/before-shell-execution.mjs` denies `lua auth key*` invocations + `skills/lua-doctor/SKILL.md` Step 4 uses an authenticated metadata probe (`lua agents --json --ci`), not a key-printing command |
+| **§3.7 single-permission contract**: each skill asks at most one prompt per invocation | Convention enforced in skill bodies |
 
 If you find a way to bypass any of these without an explicit user prompt, please report.
 
-### Hook safety model under Cursor
+### Hook safety model under Codex
 
-Cursor sends `beforeShellExecution` hooks structured stdin JSON `{command, cwd, ...}` and accepts either an exit code (2 = block) or a JSON return `{permission: "deny", user_message, agent_message}`. The plugin's hooks self-filter on `command` content rather than relying on Cursor's `matcher` field — a bug fix landed in `a85cff7` after the matcher proved unreliable in the wild and caused every shell command to be denied.
+Codex sends `PreToolUse` hooks structured stdin JSON `{tool_input: {command, ...}, tool_name, hook_event_name, ...}` (the same shape as Claude Code) and accepts either an exit code (2 = block) or a JSON envelope `{hookSpecificOutput: {hookEventName, permissionDecision}}`. The plugin's hooks self-filter on `command` content rather than relying on Codex's `matcher` field — defense-in-depth in case Codex's matcher behaviour ever drifts (a bug-class we hit on the Cursor port; same mitigation applied here proactively).
 
-The runtime adapter (`lib/hook-runtime.mjs`) detects whether it's running under Claude Code or Cursor (via `CURSOR_TRACE_ID` env or input shape) and emits the host-appropriate output protocol. The same hook scripts run unchanged on either host.
+The runtime adapter (`lib/hook-runtime.mjs`) detects whether it's running under Claude Code, Cursor, or Codex (via env vars or input shape) and emits the host-appropriate output protocol. The same hook scripts run unchanged on all three hosts.
 
 ## Audit history
 
-This plugin is a port of [`claude-code-lua-plugin`](https://github.com/lua-ai-global/claude-code-lua-plugin), which underwent 13 iterations of structured audit (commits prefixed with `iteration-`) before public release, fixing 78 documented bugs across the plugin / hook / MCP / knowledge-file surfaces. See the iteration-history comments in each lint script (`scripts/lint-*.mjs`) for the rationale behind each structural guard.
+This plugin is the third in a family ported from [`claude-code-lua-plugin`](https://github.com/lua-ai-global/claude-code-lua-plugin), which underwent 13 iterations of structured audit (commits prefixed with `iteration-`) before public release, fixing 78 documented bugs across the plugin / hook / MCP / knowledge-file surfaces. See the iteration-history comments in each lint script (`scripts/lint-*.mjs`) for the rationale behind each structural guard.
 
-The Cursor port adds:
+The Codex port adds:
 
 - A new `before-shell-execution.mjs` umbrella hook covering all three §3.3 deny patterns
-- Cursor-runtime detection + input/output normalisation in `lib/hook-runtime.mjs`
-- Cursor-specific lints: `lint-cursor-manifest`, `lint-cursor-mcp-config`, `lint-cursor-no-claude-root`
-- Test coverage for the Cursor branches (248/248 tests passing as of v1.0.0)
-- A regression-test bundle covering the `confirm-deploy.mjs` matcher-leak bug fix in `a85cff7`
+- Codex-runtime detection in `lib/hook-runtime.mjs` (falls through to Claude Code's protocol since Codex's hook input/output match)
+- Codex-specific lints: `lint-codex-manifest`, `lint-codex-mcp-config`, `lint-codex-no-claude-root`
+- Marketplace-based install via `codex plugin marketplace add` + `codex plugin install` (no symlink dance like Cursor needed)
+- Conversion of subagent files from Markdown frontmatter to Codex's TOML schema
+- 248/248 tests passing as of v1.0.0