Upgrade Codex capability boundary

.agents/skills/gpt-image-cn-router/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: gpt-image-cn-router
+description: Use when the user asks in Chinese for GPT Image 2 prompt-atlas patterns, poster or UI mockup prompt drafting, reference-image edit planning, or an explicitly approved `gpt-image` live call within the current Codex or Hermes workflow.
+---
+
+# gpt-image 中文路由器
+
+## Overview
+
+This workspace skill is the Chinese entrypoint for the vendored `gpt-image` capability.
+
+Use it to decide among three routes:
+1. prompt-only / reference mode;
+2. ChatGPT UI manual handoff mode;
+3. live OpenAI API generation/edit mode through the vendored `gpt-image` CLI.
+
+Read the full operating guide here:
+
+`/Users/yangshu/Codex/docs/gpt-image-skill-usage.md`
+
+## Route selection
+
+### A. Prompt-only / reference mode
+
+Choose this when any of the following is true:
+- the user says not to call the API;
+- `OPENAI_API_KEY` is missing;
+- the user only wants inspiration, prompt drafting, style exploration, UI mockup prompt patterns, poster prompt patterns, or reference-image edit planning.
+
+What to use:
+- `/Users/yangshu/Codex/vendor/skills/gpt-image/references/gallery.md`
+- the relevant category files under `references/`
+- `/Users/yangshu/Codex/vendor/skills/gpt-image/references/craft.md`
+
+### B. ChatGPT UI manual handoff mode
+
+Choose this when the user wants the final bitmap image but does not want API billing.
+
+What to do:
+- write a copy-ready prompt;
+- point to `/Users/yangshu/Codex/docs/templates/chatgpt-image-handoff.md` when useful;
+- require a returned asset path or screenshot before claiming visual completion.
+
+### C. Live OpenAI API mode
+
+Choose this only when:
+- the user explicitly approves OpenAI image API usage;
+- `OPENAI_API_KEY` is present;
+- an output path is defined or agreed;
+- the task actually benefits from the upstream prompt atlas or edit workflow.
+
+Canonical command:
+
+```bash
+uv run /Users/yangshu/Codex/vendor/skills/gpt-image/scripts/generate.py -p "PROMPT" [-f OUT] [-i REF...] [-m MASK] [options]
+```
+
+## Hard rules
+
+- Do not assume `OPENAI_API_KEY` exists.
+- Do not write `.env` files or API keys.
+- Do not use browser cookies, ChatGPT login state, or hidden browser automation as a fallback.
+- Do not claim an image exists unless an output file path or screenshot exists.
+- Do not widen this skill into a default image route; it is an explicit Chinese router for `gpt-image` workflows.
+- If the user only wants general OpenAI image generation and does not need the upstream prompt atlas, prefer the existing `imagegen` route.
+
+## Quality and cost guidance
+
+- `low`: cheap drafts, many variants, rough exploration.
+- `medium`: normal exploration.
+- `high`: exact text, posters, Chinese typography, diagrams, final assets.
+
+If the user asks for many variants or cheap exploration, steer to `low` or `medium`.
+If the user asks for a final shipping-facing asset, steer to `high`.
+
+## Error reporting
+
+Use these terms consistently:
+- `missing_api_key`
+- `missing_image_path`
+- `missing_mask_path`
+- `api_rejected`
+- `browser_evidence_missing`
+
+## Verification
+
+```bash
+uv run /Users/yangshu/Codex/vendor/skills/gpt-image/scripts/generate.py -p 'Codex gpt-image smoke check'
+/Users/yangshu/Codex/scripts/manage-vendored-skill.sh status gpt-image
+```
+
+Without `OPENAI_API_KEY`, the expected result is a missing-key error rather than an import/path failure.

.agents/skills/repo-ui-postcheck-summary/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: repo-ui-postcheck-summary
+description: Use when finishing or reviewing a frontend, UI, design-system, product-shell, or visual-polish change in a repository and the result needs state coverage, browser evidence, responsive notes, accessibility notes, and PR-ready handoff.
+---
+
+# Repo UI Postcheck Summary
+
+Use this skill after UI implementation or review, before claiming that a frontend or UX change is complete.
+
+## Required inputs
+
+Collect the strongest available design context:
+
+1. nearest `DESIGN.md`;
+2. repo components, tokens, or design-system docs;
+3. Figma node, screenshot, product spec, or acceptance criteria;
+4. changed routes/components;
+5. local dev URL or preview URL.
+
+If a source is missing, state the gap rather than inventing design intent.
+
+## Postcheck flow
+
+1. State the visual thesis, content plan, and interaction thesis for visually led work.
+2. Fill or summarize `/Users/yangshu/Codex/docs/templates/ui-state-matrix.md` for relevant surfaces.
+3. Run the narrowest real browser or visual check available:
+   - project Playwright test;
+   - `agent-browser` smoke;
+   - browser screenshot;
+   - manual page check with exact URL and observation.
+4. Check responsive behavior where relevant: 375, 768, 1024, and 1440 widths.
+5. Check accessibility basics: semantics, keyboard reachability, focus-visible, contrast, tap targets, and motion purpose.
+6. Report console/network errors if browser tooling exposes them.
+
+## Required summary format
+
+Include these sections in the final handoff or PR notes:
+
+- Design inputs used
+- Visual thesis
+- UI layers checked: layout, components, states, responsive behavior
+- State coverage: default, hover, focus-visible, active, loading, empty, error, disabled, success
+- Browser / visual evidence: command, URL, screenshot path, and observed result
+- Accessibility notes
+- Remaining gaps
+- Product shell status: `Product Shell Ready`, `Core Flow Ready`, `Skeleton Only`, or `Mock / Stubs Remaining`
+
+## Hard rules
+
+- Do not claim visual completion without browser, Playwright, screenshot, agent-browser, or explicit manual page evidence.
+- Do not treat a static code diff as visual verification.
+- Do not copy external brand references directly; translate them into repo-native components, tokens, spacing, density, hierarchy, and interaction rules.
+- If runtime pressure is high, prefer one targeted browser pass over broad concurrent agent exploration.
+
+## Useful commands
+
+```bash
+/Users/yangshu/Codex/scripts/codex-ui-capability-smoke.sh /path/to/repo
+/Users/yangshu/Codex/scripts/agent-browser-smoke.sh http://127.0.0.1:3000 /tmp/ui-check
+```

.codex/agents/browser-debugger.toml

@@ -0,0 +1,12 @@
+name = "browser_debugger"
+description = "Browser/UI debugger that reproduces frontend behavior, captures screenshots/console/network evidence, and reports before any code fix."
+model = "gpt-5.5"
+model_reasoning_effort = "high"
+sandbox_mode = "workspace-write"
+developer_instructions = """
+Reproduce the UI behavior before proposing fixes.
+Use browser tooling, screenshots, console output, and network evidence when available.
+Do not edit application code; hand evidence to the parent or ui_fixer.
+State viewport, URL, steps, observed behavior, expected behavior, and screenshot paths.
+"""
+nickname_candidates = ["Lens", "Pixel", "Probe"]

.codex/agents/docs-researcher.toml

@@ -0,0 +1,17 @@
+name = "docs_researcher"
+description = "Read-only documentation researcher that verifies current APIs, models, framework behavior, and release notes using official docs or primary sources."
+model = "gpt-5.4-mini"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+developer_instructions = """
+Use official documentation and primary sources first.
+Do not edit files. Do not rely on memory for unstable facts.
+Return exact source links, version/date context, and whether each claim is fact, inference, or recommendation.
+When sources conflict, call out the conflict and stop before recommending broad changes.
+"""
+nickname_candidates = ["Archivist", "Cite", "Source"]
+
+[mcp_servers.openaiDeveloperDocs]
+url = "https://developers.openai.com/mcp"
+startup_timeout_sec = 20.0
+tool_timeout_sec = 120.0

.codex/agents/pr-explorer.toml

@@ -0,0 +1,12 @@
+name = "pr_explorer"
+description = "Read-only codebase explorer that maps affected files, ownership, execution paths, and verification surface before review or implementation."
+model = "gpt-5.4-mini"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+developer_instructions = """
+Stay in exploration mode. Do not edit files.
+Map the real execution path, changed files, entry points, tests, and risky boundaries.
+Prefer targeted search and cite absolute file paths plus symbols.
+Return concise evidence, unknowns, and recommended next verification commands.
+"""
+nickname_candidates = ["Mapper", "Scout", "Trace"]

.codex/agents/reviewer.toml

@@ -0,0 +1,13 @@
+name = "reviewer"
+description = "Read-only reviewer focused on correctness, security, regressions, missing tests, and whether completed work meets done criteria."
+model = "gpt-5.5"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+developer_instructions = """
+Review like a strict owner. Do not edit files.
+Prioritize correctness, security, behavior regressions, missing tests, data loss, and unsupported claims.
+Ignore style-only issues unless they hide a real risk.
+For each finding, include impact, evidence, and the smallest safe fix or verification command.
+If there are no high-signal findings, say so and list what was verified.
+"""
+nickname_candidates = ["Atlas", "Delta", "Verifier"]

.codex/agents/ui-fixer.toml

@@ -0,0 +1,12 @@
+name = "ui_fixer"
+description = "Implementation-focused UI fixer for small targeted frontend changes after the issue has browser evidence and design constraints."
+model = "gpt-5.5"
+model_reasoning_effort = "high"
+sandbox_mode = "workspace-write"
+developer_instructions = """
+Only edit after the issue is understood and browser evidence or a concrete design target exists.
+Make the smallest defensible change using repo-native components and tokens.
+Cover relevant UI states and run visual/browser verification before claiming completion.
+Avoid unrelated refactors.
+"""
+nickname_candidates = ["Patch", "Polish", "Fixer"]

AGENTS.md

@@ -37,10 +37,14 @@
 - Keep `skills-lock.json` in sync with installed or vendored marketplace skills.
 - Prefer preparing a safe upgrade plan and verification steps before changing binaries under `/Applications`.
 - Keep changes reproducible: if a version check or migration step is useful twice, put it into `scripts/`.
-- Keep `/Users/yangshu/Codex/docs/codex-latest-practices-2026-04-14.md` as the local record of the current stable Codex model/config/plugin/skill decisions.
+- Keep `/Users/yangshu/Codex/docs/codex-latest-practices-2026-05-17.md` as the current local record of stable Codex model/config/plugin/skill decisions; keep older dated docs as historical snapshots.
 - Keep `/Users/yangshu/Codex/docs/codex-github-skill-watchlist-2026-04-14.md` as the on-demand third-party skill candidate list; do not global-install those candidates without a focused review.
 - Use explicit workspace skills for high-stakes lanes when needed: `architecture-decision-review`, `backend-api-contract-review`, and `product-ux-flow-review`.
 - Use `/Users/yangshu/Codex/docs/codex-quality-lanes.md` to route requirements, architecture, front-end, backend/API, code review, and research tasks through the correct quality lane.
+- For complex work, use the current official-style task contract: Goal, Context, Constraints, Non-goals, Done when / Done criteria, and Verification. `/goal` is for long-running progress tracking only and does not replace the task contract or final evidence.
+- Prefer MCP/plugins when context is external, OAuth-protected, or frequently changing; prefer local skills/scripts when the workflow is repeatable and can be kept inside the repo.
+- For mobile/remote Codex work, keep host readiness explicit: the Mac host must stay awake, Codex must remain running, and no unauthenticated app-server listener should be exposed publicly. Use `/Users/yangshu/Codex/scripts/codex-remote-readiness.sh` before relying on remote sessions.
+- For auto-review, remember it is a reviewer swap rather than a permission grant. Keep sandbox boundaries narrow, avoid top-level `approval_policy = "never"` for reviewed workflows, and use `/Users/yangshu/Codex/scripts/codex-auto-review-safety-audit.sh` before relaxing rules.
 - For repositories in this workspace, prefer the GitHub flow: create a short-lived branch, run `requesting-code-review`, open a pull request, and merge only after the required review gate is satisfied or intentionally bypassed as the repository admin.
 - Treat `CODEOWNERS` as the routing layer for review responsibility. When a repository needs owner-based review, update `CODEOWNERS` rather than relying on chat memory.
 - For this solo-maintained Codex meta-workspace, use `/Users/yangshu/Codex/docs/solo-maintainer-branch-protection-policy.md` before changing branch protection or merging without an independent reviewer.

docs/codex-capability-boundary-upgrade-2026-04-23.md

@@ -0,0 +1,79 @@
+# Codex capability boundary upgrade — 2026-04-23
+
+Purpose: record the latest Codex usage findings and local capability changes applied to this machine/workspace after checking OpenAI docs, openai/codex release notes, npm tags, X/OpenAIDevs public signals, and high-signal GitHub skill catalogs.
+
+## Source summary
+
+- OpenAI Codex best practices: use task context, `AGENTS.md`, config, MCP, skills, automations, session controls, and test/review loops.
+- OpenAI Codex customization docs: build in this order — `AGENTS.md`, plugins/skills, MCP, then subagents.
+- OpenAI Codex skills docs: keep skills focused, use progressive disclosure, prefer `$HOME/.agents/skills` for personal skills and `.agents/skills` for repo skills, set `allow_implicit_invocation: false` for explicit-only skills.
+- OpenAI Codex models docs: start with `gpt-5.5` when available; use `gpt-5.4` if not; use `gpt-5.4-mini` for light tasks and subagents.
+- OpenAI Codex subagents docs: custom agents now support role-specific TOML files; use subagents only when explicitly asked and keep depth/concurrency bounded.
+- OpenAI Codex release `rust-v0.124.0`: stable hooks, quick reasoning controls, multi-environment app-server sessions, Bedrock support, better MCP/plugin behavior, Fast service tier default for eligible ChatGPT plans.
+- GitHub skill catalogs reviewed as discovery signals only: `openai/skills`, `ComposioHQ/awesome-codex-skills`, and `shinpr/awesome-codex-workflows`.
+- X/OpenAIDevs public signal: Codex is expanding beyond code into Mac apps, tools, image creation, memory, and repeatable tasks; this repo keeps high-risk features gated until validated locally.
+
+## Local baseline before this pass
+
+- Active CLI: `/Users/yangshu/.local/bin/codex`
+- Installed CLI before upgrade: `codex-cli 0.122.0-alpha.5`
+- Latest stable checked via npm/GitHub: `0.124.0`
+- Desktop app: `26.422.21637`, matching the official installer at the time of the check.
+- Existing repo had unrelated dirty changes for creative/UI and local storage scripts; this pass avoids staging those unless explicitly requested.
+
+## Applied changes
+
+1. Upgraded standalone Codex CLI from alpha `0.122.0-alpha.5` to stable `0.124.0`.
+2. Updated user config for current official model guidance:
+   - default `model = "gpt-5.5"`
+   - default `model_reasoning_effort = "high"`
+   - `/review` model now `gpt-5.5`
+   - `deep`, `research`, and new `frontier` profile use `gpt-5.5`
+   - `frontier` profile keeps `xhigh` reasoning for maximum-depth tasks
+   - `guarded` profile enables `approvals_reviewer = "auto_review"` for high-risk approval review workflows
+   - `features.memories = false` is explicit because Memories are still experimental locally; manual audited memory remains the default.
+3. Added project-scoped custom agents in `.codex/agents/`:
+   - `pr_explorer`: read-only codebase mapping
+   - `reviewer`: read-only correctness/security/test reviewer
+   - `docs_researcher`: read-only official docs verifier
+   - `browser_debugger`: browser/UI evidence collector
+   - `ui_fixer`: small targeted UI fixer after evidence exists
+4. Added `scripts/codex-boundary-smoke.sh` to verify the version/config/agent boundary in one command.
+
+## Recommended routing after this pass
+
+| Task | Default route | Escalation |
+|---|---|---|
+| Simple explanation or small edit | `--profile quick` | default if quality drops |
+| Normal engineering | default `gpt-5.5/high` | `--profile frontier` for hard reasoning |
+| Architecture / product planning | Plan mode + task card | `--profile frontier` |
+| Current external facts | `--profile research` | docs_researcher subagent when explicitly asked |
+| PR review / quality gate | `/review` + `docs/code_review.md` | pr_explorer + reviewer + docs_researcher subagents |
+| UI bug / frontend regression | frontend-design-review + browser evidence | browser_debugger + ui_fixer subagents |
+| High-risk shell/MCP/app action | default approvals | `--profile guarded` with auto-review |
+| Long-term memory | audited Markdown/JSONL | enable official Memories only after a separate privacy review |
+
+## Skill adoption decisions
+
+- Adopt now: no broad third-party skill install.
+- Keep using existing curated/plugin skills: OpenAI curated `playwright`, `figma`, `gh-fix-ci`, `gh-address-comments`, `security-*`, and existing Vercel/Cloudflare/GitHub plugin skills.
+- Watchlist only: Composio `create-plan`, `webapp-testing`, `mcp-builder`, `sentry-triage`, `codebase-migrate`, `developer-growth-analysis`.
+- Reject default global install for broad packs or toolkits that add large action surfaces, app connectors, or crawler/browser-cookie behavior.
+
+## Rollback
+
+- CLI: restore the backup under `/Users/yangshu/.local/bin/codex-backups/`.
+- Config: restore `/Users/yangshu/.codex/config.toml.bak-20260423-capability-boundary`.
+- Custom agents: remove `.codex/agents/*.toml` added in this pass.
+- Repo docs/scripts: revert this document and `scripts/codex-boundary-smoke.sh`.
+
+## Verification commands
+
+```bash
+codex --version
+codex features list
+codex mcp list
+/Users/yangshu/Codex/scripts/check-codex-upgrade.sh
+/Users/yangshu/Codex/scripts/codex-boundary-smoke.sh
+git diff --check
+```