## Why
Response body reads could outlive the manual download timeout or fail outside the existing fallback and retry handlers.
## What changed
- Read successful manual response bodies within the fetch timeout and transport fallback so stalled or failed reads fall back to `curl`. Leave `HEAD` responses unconsumed.
- Await model metadata response bodies inside the retry handler so read failures use the existing three-attempt retry loop.
## Testing
Add regression tests for manual body timeouts and truncated bodies falling back to `curl` before caching, plus model metadata body failures succeeding on retry or stopping after three attempts. All four tests pass with `node --test codex-rs/skills/tests/openai_docs_downloads.test.mjs`.
GitOrigin-RevId: 528595307ef86ad2522dc8ae488baadc001ad961
Share outline generation and status construction in `fetchCodexManual` after
loading a verified cached manual or fetching and validating a fresh copy.
Preserve cache status reporting and SHA-256 checks while removing the duplicated
cache-hit return path.
GitOrigin-RevId: 2dd2046a65e9a3adbca4d269827501d5ab175f36
`nearestExistingParent` already checks whether the cache path exists and is a directory. Remove the duplicate `stat` check from `usableCacheDir` in the OpenAI docs manual fetcher, retaining the existing parent lookup and write/execute permission checks.
GitOrigin-RevId: 42583353bfdd06881171d8b24fa2b2d5b6fb3135
## What changed
- Return qualified skill names such as `team:deploy` and parsed `dependencies` and `policy` instead of a separate namespace and raw metadata file. Share `agents/openai.yaml` parsing and validation between skill loaders and executor discovery.
- Include each standalone skill's search-root ID and path in `discoveryRoot`, while accepting responses from older executors that omit it.
- Add plugin `displayName`, falling back to the manifest name or installation directory.
- Materialize inline MCP declarations in `mcpConfig` with the manifest as their source path, and report incomplete discovery when declared MCP or Apps configuration files have no returned contents.
## Testing
Add coverage for JSON round trips, omitted `discoveryRoot`, optional and invalid skill metadata, qualified names, display-name fallbacks, and inline MCP configuration. Verify standalone search roots survive cached discovery and sandboxed RPC responses.
GitOrigin-RevId: 4124972444ad7c2fb8c6418acbf9a589d797fad2
## What changed
Update the OpenAI docs sample resolver to return only `model`, `migrationGuideUrl`, and `promptingGuideUrl`, and remove the model-to-slug conversion helper.
GitOrigin-RevId: d7cea29ff8121b1a4df3b062d54dcbed6a1589bd
## What changed
- Reformat Markdown tables and lists, login pages, inline visualization HTML, and sample JavaScript scripts.
- Escape union-type pipes in Python SDK API tables so they render within their cells.
- Keep the formatting-recipe test focused on the working directory and formatter commands by removing assertions on comment text.
GitOrigin-RevId: ae46d5b40fd013553de8b5ccf2c41d76be65aba8
## What changed
Update the bundled `openai-docs` references to cover GPT-6 Astra, GPT-6.1 Sol, GPT-6 Sol, and GPT-6 Luna with model-specific reasoning, tool-calling, parameter, and data residency guidance.
Require verification of the exact target's availability and compatibility, preserve explicitly requested models, and use live guidance for model selection. Replace fixed role mappings with verified targets and clarify when to load migration and prompting fallbacks.
GitOrigin-RevId: 59067d0fc97af36d2e5b6508c45488181c6a4ace
## Why
Skill selection and disabled-path matching need to recognize equivalent Windows paths across case and separator differences while preserving literal spaces, `%`, and `#` in native filenames.
## What changed
- Carry `PathUri` through skill metadata, discovery mappings, filesystem lookups, disabled-path sets, and invocation analytics.
- Match linked skill mentions and TUI selections by parsed path identity.
- Use `LegacyAppPathString` for app-server skill paths and regenerate schemas and SDK types, preserving native path strings on the wire.
- Preserve native catalog display paths and ordering. Keep host filesystem probes and configuration writes restricted to host-compatible paths.
## Testing
Add regression tests for Windows path identity and disabled-skill matching, literal filename characters, catalog resource reads, native path ordering, and foreign-path analytics normalization.
GitOrigin-RevId: c212916dc9fef0e7616542726e107f0d6a313267
## What changed
- Delete the `plugin-creator` skill, its assets, reference docs, helper scripts, and associated Python tests.
- Update the app-server skills context budget warning test to expect six omitted skills instead of seven.
GitOrigin-RevId: 005b1ab7f2f7c2933e6c297d01541746cc489f68
## What changed
- Replace the bundled GPT-5.6 Sol migration guide with GPT-6 Astra guidance and update model metadata, migration routes, and official documentation links.
- Document GPT-6 migration compatibility checks for reasoning effort, tool calling, unsupported parameters, fast mode, and prompt caching while preserving model roles for Terra and Luna.
- Refresh the prompting fallback with guidance on autonomy, instruction following, writing style, subagent delegation, and testing. Prefer live official guidance and use the bundled prompting copy only when it is unavailable.
GitOrigin-RevId: d1f298b8e7517687acbf4de5cfb0cd914d3861f5
## Why
Selected plugin MCP servers may be skipped after the optional startup grace
period. When a user explicitly mentions a plugin or MCP server, the turn should
continue waiting so the requested tools are available to the model.
## What changed
- Track explicitly mentioned plugin IDs and MCP servers across later samples,
steered input, and same-turn restarts.
- Require matching selected-plugin MCP servers to finish startup before
capturing the tool catalog, while leaving unmentioned servers optional.
- Match `plugin://` identities independently of display names and ignore
targeting query parameters such as `app` and `browserFamily`.
## Testing
Added coverage for linked and structured plugin mentions, direct and batched
capability discovery, delayed environment attachment, steering, and same-turn
restarts.
GitOrigin-RevId: c509ef8df45df1a7edb0da6afdb2682dc53a4de8
## Why
The root Python formatting pass only covered `scripts/`, leaving Python utilities elsewhere in the repository outside `just fmt` and `just fmt-check`.
## What changed
- Run the scripts Ruff formatter from the repository root.
- Exclude `sdk/python`, which has its own formatter pass, and `codex-rs/vendor`.
- Apply Ruff formatting to the newly covered Python files and update the formatter coverage test.
GitOrigin-RevId: 73ac82b8bb9c713d589724f6c4f926399febb513
## What changed
- Require selected skill paths to resolve within the cloned repository and reject
symlinked path components.
- Reject special files and symlinks that escape the selected skill or resolve to
anything other than a regular file.
- Add regression tests showing that escaping symlinks are rejected while links
to regular files within the skill are installed as file contents.
GitOrigin-RevId: d4c3f09fb630dea96b34ea5552de571b36f1ceca
## Why
Plugin and marketplace names can flow into generated install commands, so the
plugin creator must reject names outside the supported identifier syntax before
using them or changing files.
## What changed
- Centralize validation for plugin names, including dotted names, and marketplace
names.
- Apply validation when reading marketplaces, validating manifests, updating
cachebusters, and scaffolding plugins.
- Validate existing marketplace state before scaffold writes so invalid or
duplicate entries leave plugin and marketplace files unchanged.
## Testing
Add regression tests for accepted identifiers, unsafe and malformed names,
dotted plugin names, and failure paths that must not modify files.
GitOrigin-RevId: 9db68c2313a1539c5ab44d777966e33b460ceb71
## What changed
- Stop parsing and exposing the `model` field from skill frontmatter.
- Remove the skill model delegation types and instruction generation.
GitOrigin-RevId: 01198c68c095da5062e8abec417cc3539099d9d5
## What changed
- Add `SkillModelDelegationInstruction` for skills that request Luna while running on Sol or Terra.
- Resolve Luna only when it is available in the current provider namespace.
- Bound and validate model identifiers, skill names, and the rendered instruction before exposing it to callers.
## Testing
- Cover supported parent models, provider namespace matching, unavailable or unsafe targets, instruction rendering, and size limits.
GitOrigin-RevId: 188a88c36ca32689cbf1e53465283dff4137cb15
## What changed
- Add an optional `model` field to parsed and loaded skill metadata.
- Recognize `model: luna` while ignoring unsupported model values without
preventing the rest of the skill metadata from loading.
## Testing
- Cover supported, absent, unsupported, and repaired frontmatter model values.
GitOrigin-RevId: 376b65555e81d29a5eae93cc4c2633aacf7cd7c8
## What changed
- Add `oauth.callback_port` to MCP server configuration and preserve it when
serializing configuration edits.
- Accept `oauth.callbackPort` from plugin MCP declarations and skill dependency
metadata.
- Prefer the server-specific callback port over `mcp_oauth_callback_port` for
CLI login, app-server, plugin installation, executor, and skill dependency
OAuth flows.
## Testing
- Cover configuration parsing, serialization, and fallback behavior.
- Verify plugin, executor, and skill OAuth registrations use their configured
callback ports instead of the global port.
GitOrigin-RevId: 7f65e5e7869358307e49779f1b75e8672b607736
## What changed
- Classify simple PowerShell `Get-Content` commands, including `gc` and `type` aliases, as file reads while preserving Windows paths.
- Reuse the shared classification for implicit skill invocation detection on Windows and render recognized commands as `Read <file>` in the TUI.
- Leave commands with unsupported flags, multiple operands, wildcards, or expressions unclassified.
## Testing
- Cover supported and rejected PowerShell forms, Windows executor skill detection, and the TUI read summary.
GitOrigin-RevId: 4e8f5470f2ae31c08d74091f9634c2926e516ccf
## What changed
- Rework the bundled `skill-creator` guidance around concise, scoped instructions, progressive disclosure, optional resources, invocation policy, and risk-based forward-testing.
- Simplify generated skill and reference templates so new skills start with only the placeholders and resources they need.
- Reject unfinished `[TODO: ...]` placeholders in skill descriptions and instruction bodies while allowing examples inside fenced code blocks.
GitOrigin-RevId: b0871aaeeb768c12b1a467d48037eecc8db5d52b
## What changed
- Recognize `Get-Content` reads of indexed `SKILL.md` files as implicit skill invocations.
- Support the optional `-Raw` flag, quoted paths containing spaces, and Windows paths without stripping backslashes.
## Testing
- Add unit coverage for the supported `Get-Content` forms and Windows path parsing.
GitOrigin-RevId: 681f2e2fff9a597326bc94b97a31e311ef21b949
## What changed
- Detect executor-owned skill document reads and script executions across native and URI-based working directories.
- Match skills only within the active execution environment while preserving host skill detection for local commands.
- Emit resource-backed implicit invocation events and deduplicate repeated accesses within a turn.
## Testing
- Add unit coverage for document reads, script executions, and environment-scoped matching.
- Add an integration test for environment selection, resource-backed analytics, and repeated-access deduplication.
GitOrigin-RevId: f78a48c3a4766fe8775bd88926b45a76761f6af8
## What changed
- Direct the built-in `image_gen` path to request transparent backgrounds and
preserve the generated alpha channel.
- Remove the built-in chroma-key generation and local background-removal
workflow from the skill guidance and examples.
- Keep CLI model fallback explicit, including confirmation before switching
from `gpt-image-2` to `gpt-image-1.5` for transparent CLI output.
GitOrigin-RevId: 1a6fbbb632bbf3f95146347d66da5382313b32a2
## What changed
- Define skill config selectors, ordered rules, and layer-stack parsing in `codex-config`.
- Resolve disabled skill paths from generic skill name/path pairs, so configuration logic no longer depends on `SkillMetadata`.
- Update plugin and host skill consumers to use the `codex-config` API and consolidate the rule tests with the skill config tests.
GitOrigin-RevId: 3fe67869708df2652befe28d58cdeba933256f84
## What changed
- Use `HostSkillRoot` throughout host root resolution and loading, including plugin roots.
- Remove the duplicate loader, root snapshot, and product-filtering implementation from `core-skills` now that loading is owned by the skills extension.
- Move and expand loader coverage for discovery, namespaces, filesystem routing, root merging, symlinks, and frontmatter parsing.
## Testing
- Added focused unit and integration tests under `ext/skills` and `skills` for the consolidated loader behavior.
GitOrigin-RevId: 214d06d59bf3033ee0f220ea5959ee4feff66782
## What changed
- Add `SkillRootLoader` and its request/result types to `codex-skills` so skill roots can be loaded through a shared, object-safe interface.
- Add owner-managed snapshot cache handles that support reuse and use cache allocation identity for equality and hashing.
- Move `SkillError` into `codex-skills` and re-export the new loading API.
## Testing
- Verify snapshot sharing and identity semantics.
- Verify loaders can be used as shared trait objects.
GitOrigin-RevId: a26a8101008a6c862824a7346cdbe6d05f4bcc01
## What changed
- Add `ExplicitSkillLookup` to decouple explicit mention selection from the
core skill-loading model.
- Export `collect_explicit_skill_mentions` from `codex-skills` and implement
the lookup interface for `SkillLoadOutcome`.
- Move the selection tests into `codex-skills` while keeping the prompt-size
boundary test with prompt injection.
GitOrigin-RevId: 21105af31c9b519c231c5ea02464da560705c293
## What changed
- Move tool mention parsing, skill-name counting, and implicit invocation detection into `codex-skills` and expose them through its public API.
- Decouple implicit invocation detection from `SkillLoadOutcome` with an `ImplicitSkillLookup` trait, while preserving the existing `core-skills` interface through re-exports.
- Cover remote plugin attribution for both implicit `SKILL.md` reads and skill script runs.
GitOrigin-RevId: f3da85c9821868638ccfd2fc2e01e0869d2fd437
## What changed
- Move `resolve_disabled_skill_paths` into `codex-skills` and expose it from the crate.
- Re-export the resolver from `core-skills` to preserve existing callers.
- Split config-layer and policy-resolution coverage into focused unit tests, including ordered path and name overrides.
GitOrigin-RevId: 6528ff99285925132bf80eb33eafb1b62118e033
## What changed
- Move skill interface validation and asset-path resolution into `codex-skills` so both skill loaders share the same behavior.
- Populate host-loaded skills with validated display metadata, prompts, brand colors, and local icons from `agents/openai.yaml`.
- Allow plugin skills to reference icons under the plugin's shared `assets` directory while rejecting absolute paths and paths that escape permitted asset roots.
## Testing
- Add resolver tests for valid, invalid, local, and plugin-shared interface assets.
- Add host loader coverage for interface fields and asset-path restrictions.
GitOrigin-RevId: 3f316191752eeebd15d11ac0bee82201574320ec
## What changed
- Move parsing of pre-discovered executor skill bundles from `core-skills` to
the skills extension.
- Expose shared `SKILL.md` frontmatter parsing from `codex-skills` so direct
and pre-discovered loading use the same validation and repair behavior.
## Testing
- Add parity coverage for direct and pre-discovered executor skill catalogs,
including plugin namespaces, metadata, product policy, and warnings.
- Add a snapshot for the resulting pre-discovered executor catalog.
GitOrigin-RevId: c5f888226fa5600bd8b90f5682400da39a5db5ff
## What changed
- Make targeted official documentation search and page retrieval the default first step, while retaining a manual-first path for broad Codex orientation and setup questions.
- Split Codex self-knowledge, documentation integration diagnostics, model migration, model selection, and general official documentation guidance into focused references, with at most one primary route loaded per request.
- Preserve explicitly requested model targets, reserve the latest-model resolver for dynamic migrations, and treat bundled model guidance as a disclosed fallback to current official sources.
- Expand the skill metadata and interface description to cover Codex self-knowledge, ChatGPT Work, and OpenAI model and API workflows.
GitOrigin-RevId: 22aba3fc6f58dac8a6cef637504b1fe6d2aaf0d0
## What changed
- Carry a plugin's local and remote identities together from plugin loading into
`SkillMetadata`.
- Resolve remote IDs from the installed-plugin snapshot when available, falling
back to persisted install metadata only when no snapshot exists.
- Include plugin identity in skill cache keys so identity changes refresh cached
skill metadata.
## Testing
- Cover snapshot and persisted identity resolution, local marketplace isolation,
cached skill refreshes, and propagation through plugin skill snapshots.
GitOrigin-RevId: aabeeb631a43361fe817358ace7f1ea8ba5db708
## What changed
- Define and export skill metadata, policy, dependency, interface, and configuration rule types from `codex-skills`.
- Update core, plugin, and extension consumers to use the shared models while retaining compatibility re-exports from `codex-core-skills`.
- Share product-restriction handling between host and environment skill metadata.
## Testing
- Add unit coverage for default and explicit implicit-invocation and product policies.
GitOrigin-RevId: 9093469f8fff8e2d902dc9781235f64709827a87
## Why
Detached reviews should behave like ordinary forked turns so clients get the normal steering, tool, permission, and item-stream behavior.
## What changed
- Add a bundled `$review-agent` skill with read-only, defect-first review guidance.
- Start detached reviews through `AgentRunner` with a target-specific prompt that explicitly references the bundled skill. Keep inline reviews on the existing review-mode flow.
- Continue emitting the detached review thread and turn identifiers through the app-server API.
## Testing
- Update the detached review integration test to verify the forked turn prompt, ordinary turn completion, and selection of the bundled skill when a user skill has the same name.
GitOrigin-RevId: 979664cd80800fb0d51eabdc4e3211da90c12db9
## What changed
- Recommend simplifying prompts incrementally and evaluating each change while preserving product requirements.
- Document `text.verbosity` as the default response-detail control and clarify how prompts should specify task-specific content and tone.
- Clarify autonomy and approval boundaries for multi-step work.
- Narrow Programmatic Tool Calling guidance to bounded reduction workflows and call out validation of both `program_output` and the final assistant `message`.
GitOrigin-RevId: 2334a1cfba9ead53d2002a097920d1306bcae0d4
## Summary
Updates Codex's bundled OpenAI Docs skill for GPT-5.6.
- resolves latest/current/default-model requests through the
machine-readable `latest-model.md` contract
- fetches the exact prompting and migration guide URLs returned by the
live docs
- preserves explicitly named GPT-5 model targets
- adds bundled GPT-5.6 Sol, Terra, and Luna migration judgment
- adds a POSIX resolver wrapper plus a CommonJS entry point for Windows
- skips incompatible Node.js runtimes before trying Codex's
bundled/system fallbacks
## Developer impact
The bundled system skill follows the live GPT-5.6 docs contract and can
resolve current guidance after installation on POSIX and Windows
environments.
## Validation
- skill validator: passed
- live resolver smoke test returned `gpt-5.6-sol` and both standalone
guide URLs
- CommonJS and POSIX shell syntax checks: passed
- non-executable installed-wrapper invocation through `sh`: passed
- incompatible `$NODE` fallback to the bundled Node.js runtime: passed
- `git diff --check`: passed
- migration eval: 30/30 passed, 0 critical failures
- latest-model/prompting routing eval: 33/33 passed, 0 critical failures
`just fmt` was not run because `just` is unavailable in this
environment; the change only touches bundled Markdown and
JavaScript/shell assets.
## Summary
- Update the bundled skill installer's post-install guidance to say the
skill will be available on the user's next turn.
- Remove the obsolete instruction to restart Codex.
## Why
Codex refreshes its skill catalog between turns. The existing bundled
instruction predates that behavior and causes the model to recommend an
unnecessary restart.
## Impact
Released Codex builds will materialize accurate post-install guidance
for the bundled system skill.
## Related
- Canonical skill change: https://github.com/openai/skills/pull/507
## Validation
- `just fmt`
- `git diff --check`
- `just test -p codex-app-server
skills_changed_notification_is_emitted_after_skill_change` (passed
during investigation)
No test code was added because the existing live-refresh path and
focused integration test already verify that skill changes are picked up
without restarting.
Adds additive dark-mode plugin logo metadata across manifests, remote
catalogs, and the app-server protocol while keeping uninstalled Git
listings free of synthetic local paths.
Supersedes #28945. This replacement uses an upstream branch so trusted
CI can use the repository-provided remote Bazel configuration.
## Current state
Plugin interfaces expose only the default logo asset. Clients therefore
cannot select a dedicated dark-mode logo even when a plugin provides
one.
## What this PR changes
- Adds nullable `logoDark` and `logoUrlDark` fields to
`PluginInterface`.
- Resolves local `interface.logoDark` assets and maps remote
`logo_url_dark` values.
- Removes path-backed interface assets, including `logoDark`, from
uninstalled Git fallback listings until the plugin has a real local
root.
- Updates the bundled plugin validator and manifest reference.
- Regenerates the app-server JSON schemas and TypeScript types.
Local manifests expose `interface.logoDark` as a package-relative asset
path. Remote catalog responses expose `logo_url_dark`. These values map
into separate app-server fields so clients can preserve local-path and
remote-URL handling.
## Risk
The fields are additive and nullable, so existing clients retain their
current logo behavior. The main risks are an incomplete mapping path or
exposing a synthetic local path for an uninstalled Git plugin.
Local-manifest, remote-catalog, fallback-listing, protocol
serialization, and app-server integration tests cover those paths.
Spiciness: 2/5
## Testing
- `just write-app-server-schema`
- `just fmt`
- Regression test first failed with `logo_dark` resolved to
`/assets/logo-dark.png`, then passed after the fallback-listing fix.
- `just test -p codex-core-plugins` (267 tests passed)
- `just test -p codex-app-server 'suite::v2::plugin'` (114 tests passed)
- `just test -p codex-app-server-protocol -p codex-core-plugins -p
codex-plugin -p codex-skills` (517 tests passed before the follow-up)
- `just test -p codex-tui plugin` (47 tests passed)
- Validated a local plugin manifest containing `interface.logoDark` with
the bundled validator.
## Manual verification
Create a local plugin with both `interface.logo` and
`interface.logoDark`, then call `plugin/list` or `plugin/read`. Confirm
the response contains separate `logo` and `logoDark` paths. For a remote
catalog entry, confirm `logoUrlDark` is populated from `logo_url_dark`.
For an uninstalled Git marketplace entry, confirm path-backed interface
assets remain absent until installation.
Issue: N/A - coordinated maintainer change.
## Summary
This fixes plugin manifest parsing for MCP servers declared as an object
directly in `plugin.json`.
Before this change, Codex modeled `mcpServers` as only a string path,
for example:
```json
{
"name": "counter-sample",
"version": "1.1.1",
"mcpServers": "./.mcp.json"
}
```
Some migrated plugins instead provide the server map directly in the
manifest:
```json
{
"name": "counter-sample",
"version": "1.1.1",
"description": "Plugin that declares MCP servers in the manifest",
"mcpServers": {
"counter": {
"type": "http",
"url": "https://sample.example/counter/mcp"
}
}
}
```
That object form previously failed during install/load with an error
like:
```text
failed to parse plugin manifest: invalid type: map, expected a string
```
## What changed
- Add a manifest representation for `mcpServers` as either
`Path(Resource)` or `Object(map)`.
- Parse `plugin.json` `mcpServers` as either a string path or an object.
- Route object-valued MCP server maps through the existing plugin MCP
config parser instead of adding a second parser.
- Apply existing per-plugin MCP server policy to object-valued MCP
servers the same way as file-backed MCP servers.
- Include object-valued MCP server names in plugin telemetry/capability
metadata.
- Support object-valued MCP config for executor plugins without
requiring a `.mcp.json` filesystem read.
- Update the bundled plugin-creator validator and `plugin-json-spec.md`
so generated-plugin validation accepts the same object-valued shape.
## Compatibility
Existing plugin manifests that use `"mcpServers": "./.mcp.json"`
continue to work. Plugins can now also use the object shape shown above.
## Tests
Added coverage for the new manifest attribute shape at the install,
normal load, telemetry, and executor-provider layers:
- `install_accepts_manifest_mcp_server_objects`
- `load_plugins_loads_manifest_mcp_server_objects`
- `plugin_telemetry_metadata_uses_manifest_mcp_server_objects`
- `reads_manifest_object_config_without_executor_file_system_access`
Also smoke-tested the plugin-creator validator against both supported
forms:
- `mcpServers` as a direct object in `plugin.json`
- `mcpServers` as `"./.mcp.json"` with a companion `.mcp.json`
## Validation
- `just test -p codex-plugin`
- `just test -p codex-core-plugins`
- `just test -p codex-mcp-extension`
- `just bazel-lock-update`
- `just bazel-lock-check`
- `just fmt`
- `git diff --check`
- Focused rename/object-form rerun: `just test -p codex-core-plugins
manager::tests::load_plugins_loads_manifest_mcp_server_objects
manager::tests::plugin_telemetry_metadata_uses_manifest_mcp_server_objects
store::tests::install_accepts_manifest_mcp_server_objects`
- Focused executor rerun: `just test -p codex-mcp-extension
executor_plugin::provider::tests::reads_manifest_object_config_without_executor_file_system_access`
- `python3
codex-rs/skills/src/assets/samples/plugin-creator/scripts/validate_plugin.py
/private/tmp/codex-validator-object`
- `python3
codex-rs/skills/src/assets/samples/plugin-creator/scripts/validate_plugin.py
/private/tmp/codex-validator-path`
## Intent
Keep Bazel and Starlark files consistently formatted without requiring
contributors to install or version buildifier themselves.
## Implementation
- Add a SHA-256-pinned, cross-platform DotSlash manifest for buildifier
v8.5.1.
- Run buildifier from the shared `just fmt` and `just fmt-check` driver,
with Windows-safe explicit DotSlash invocation.
- Provision DotSlash in formatting CI and contributor devcontainers, and
document the source-build prerequisite.
- Apply the initial mechanical buildifier formatting baseline.
## What
- Parse optional `.app.json` `category` overrides for plugin apps.
- Add nullable `category` to `AppSummary` and `AppTemplateSummary` in
the app-server protocol.
- Fall back from `branding.category` to the first non-empty
`app_metadata.categories` value when building app/template summaries.
- Regenerate schema/type fixtures and update plugin read/install tests.
## Why
The plugin details UI needs a normalized per-app category. Some apps
only provide their default category in metadata, while others need a
local `.app.json` override.
## Summary
- update the bundled `openai-docs` system skill to match the latest
`openai-docs-plus` content from `skills-internal`
- add the cached Codex manual fetch helper and expand the skill routing
for Codex self-knowledge
- keep the stable local skill identity and labels as `openai-docs`
## Why
The built-in OpenAI Docs skill needed to reflect the current upstream
guidance from `skills-internal` while preserving the local system-skill
name used by Codex.
## Impact
Codex now ships the newer OpenAI Docs skill behavior for Codex
self-knowledge and manual-first documentation lookups.
## Validation
- `just test -p codex-skills`
- exact directory diff against transformed `skills-internal`
`origin/main` was clean
## Summary
Creates a personal-marketplace update flow for the plugin-creator skill
when iterating on an existing local plugin.
## Context
Plugin creation already had a scaffold path, but the follow-up story for
updating an existing local plugin during development was not explicit.
The goal of this change is to make that default personal-marketplace
update loop legible at the point of use instead of leaving it implied or
hidden behind a larger helper.
## Decision
Keep the scaffold flow intact, add a dedicated update/reinstall
reference centered on the personal marketplace, document the actual
`codex plugin add` and marketplace-check commands directly, and keep
helper automation narrowly scoped to the repetitive local-update steps.
## Changes
- update plugin-creator to point existing-plugin iteration at a
personal-marketplace update flow
- add `references/installing-and-updating.md` with the explicit
marketplace check and reinstall sequence
- add small helper scripts for reading marketplace names and updating
plugin versions during local iteration
## Tests
- `python3
codex-rs/skills/src/assets/samples/skill-creator/scripts/quick_validate.py
codex-rs/skills/src/assets/samples/plugin-creator`
- `python3 -m py_compile
codex-rs/skills/src/assets/samples/plugin-creator/scripts/create_basic_plugin.py
codex-rs/skills/src/assets/samples/plugin-creator/scripts/read_marketplace_name.py
codex-rs/skills/src/assets/samples/plugin-creator/scripts/update_plugin_cachebuster.py`
# Summary
Before this change, the sample plugin creator could emit
placeholder-heavy manifests that fail workspace sharing, and it chose a
repo-local marketplace implicitly whenever it ran from inside a git
checkout.
This PR makes generated plugins share-ready by default. It switches
creation to the personal marketplace unless the caller explicitly opts
into repo-local paths, adds a validator that mirrors the workspace
plugin ingestion contract, and updates the skill prompt and docs to
describe the real flow.
The goal is to stop malformed generated plugins before they reach
sharing and to make the default placement match the personal marketplace
behavior users expect.
## Changes
- Generate share-safe plugin manifests instead of `[TODO: ...]`
placeholder payloads.
- Default plugin and marketplace creation to `~/plugins` and
`~/.agents/plugins/marketplace.json`.
- Keep repo-local marketplace creation available through explicit
`--path` and `--marketplace-path` arguments.
- Add `validate_plugin.py` to check manifests, companion files, skill
frontmatter, skill agent YAML, asset paths, and backend-shaped contracts
before sharing.
- Refresh the plugin creator skill text, reference docs, and default
prompt to describe validation and the personal default.
## Design decisions
- The validator tracks the workspace ingestion schema directly,
including the required `defaultPrompt` alias handling and skill
`agents/openai.yaml` checks.
- The validator keeps one intentional extra preflight rule: leftover
`[TODO: ...]` placeholders are rejected before sharing even when a
single placeholder would not independently violate backend type
validation.
- Repo-local creation stays possible, but it is now explicit instead of
cwd-sensitive.
## Testing
Tests: targeted Python syntax checks, plugin skill validation, staged
diff whitespace validation, 15 generated plugin smoke runs, backend
manifest-schema acceptance for all 15 generated bundles, and a git-repo
cwd regression proving the creator still writes to the personal
marketplace by default.
## Summary
Plugin Creator now documents the shorter local-plugin handoff URL that
the app can interpret directly.
[#22221](https://github.com/openai/codex/pull/22221) teaches the skill
to end marketplace-backed creation flows with named View and Share
links; this follow-up updates those examples so the skill only emits the
normalized plugin name, the absolute marketplace path, and optional
share mode.
The documented shape is:
```txt
codex://plugins/<normalized-plugin-name>?marketplacePath=<absolute-marketplace-json-path>
codex://plugins/<normalized-plugin-name>?marketplacePath=<absolute-marketplace-json-path>&mode=share
```
The skill text now states exactly where the normalized plugin name
belongs, exactly where the absolute marketplace path belongs, and that
it should not add `pluginName` or `hostId` query parameters.
## Testing
Tests: plugin-creator skill validation.
## Summary
Plugin creation now defaults to the personal marketplace path and ends
with a readable handoff back into Codex after a marketplace-backed
scaffold.
Before this change, `plugin-creator` centered repo-local marketplace
updates and did not clearly guide the agent to return the user to the
created plugin afterward. This PR updates the bundled system skill so
marketplace-backed scaffolds default to `~/plugins/<plugin-name>` plus
`~/.agents/plugins/marketplace.json`, ask for user intent only when an
existing repo marketplace makes personal vs team scope ambiguous, and
end with named Markdown deeplinks labeled `View <plugin-name>` and
`Share <plugin-name>`.
## What changed
- default marketplace-backed creation to the personal plugin location
- document the explicit repo/team override path for codebases that
should own the plugin entry
- ask personal vs team only when the current Git repo already has
`.agents/plugins/marketplace.json` and the user has not stated scope
- require named Markdown deeplinks after marketplace-backed creation so
the final response returns the user to the exact plugin cleanly
- keep the deeplink targets precise with real absolute `marketplacePath`
and normalized `pluginName` values
- align the bundled prompt, scaffold help text, and marketplace
reference spec with the new default
## Testing
Tests: targeted skill validation, Python compile checks,
personal-default scaffold smoke, repo-override scaffold smoke, and
whitespace checks.
## Summary
- Add the same API key setup coordination guidance to the embedded
OpenAI Docs sample skill in `codex-rs/skills`.
- Keep the skill description/frontmatter unchanged; the coordination
lives only in the body.
- Preserve direct OpenAI Docs routing for docs-only questions,
citations, model/API guidance, conceptual explanations, and non-building
examples.
## Why
The Codex repo carries its own OpenAI Docs skill variant under
`codex-rs/skills/src/assets/samples`. This keeps that embedded sample
aligned with the other OpenAI Docs variants patched in the related PRs.
## Validation
- `cargo test -p codex-skills`
- `git diff --check`
Konstantine Kahadze