NDDev-it-com · rldyourmnd · Jul 19, 2026 · Jul 19, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,30 @@
 
 All notable changes to this project are documented here.
 
+## [0.3.12] - 2026-07-19
+
+### Added
+
+- New `codex-onboarding` skill: a guided first run that routes a newcomer from
+  zero to a checked Codex artifact through the add-one, build-a-plugin, and
+  marketplace paths. `codex-builder-orientation` now points newcomers to it. The
+  builder plugin exposes 29 skills.
+
+### Fixed
+
+- The `config` checker now accepts the full Codex 0.144.6 reasoning-effort ladder
+  for `model_reasoning_effort` and `plan_mode_reasoning_effort`. `max` and `ultra`
+  (and `none`) map to the same `ReasoningEffort` type as an agent role's effort,
+  but a stricter config-only allowlist rejected them as false positives.
+
+### Changed
+
+- The contracts reference notes that current capability toggles are centralized
+  in `[features]` and points at the checker and `$openai-docs` as the authority,
+  rather than freezing the fast-moving flag list.
+- The builder plugin advances to 0.3.7 so an in-place `install-builder`
+  re-materializes the cache.
+
 ## [0.3.11] - 2026-07-19
 
 ### Fixed

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-0.3.11
+0.3.12
diff --git a/build/manifest.json b/build/manifest.json
@@ -5,7 +5,7 @@
     "location": "sibling .<target-name>.nddev-codex-backups",
     "slots": 10
   },
-  "build_version": "0.3.11",
+  "build_version": "0.3.12",
   "command_policy": {
     "json_supported": [
       "list",

diff --git a/build/release-evidence.json b/build/release-evidence.json
@@ -2,15 +2,15 @@
   "schema_version": 2,
   "module": {
     "repository": "NDDev-it-com/nddev-codex-app",
-    "setup_digest": "sha256:47c123ec6af139298ec37c82157511cb231a95e8de9b1a8db18884c85c8fd8d2"
+    "setup_digest": "sha256:cf9ea19a63c751b3cc12962da675e11bcaa8b494d1ae0edb5660499b4541dc68"
   },
   "harness": {
     "repository": "NDDev-it-com/nddev-harnesses",
-    "commit": "c10983fa2094e1052b3d69413d391a2e8bb9391b"
+    "commit": "adc96b1eea357d6130f5b916f182625b87b5ea5a"
   },
   "adapter": {
     "id": "codex",
-    "version": "0.3.11"
+    "version": "0.3.12"
   },
   "vendor": {
     "cli_version": "0.144.6",
@@ -29,8 +29,8 @@
     }
   ],
   "lanes": [],
-  "generated_at_utc": "2026-07-19T07:40:21Z",
-  "expires_at_utc": "2027-01-15T07:40:21Z",
+  "generated_at_utc": "2026-07-19T11:21:55Z",
+  "expires_at_utc": "2027-01-15T11:21:55Z",
   "promotion": {
     "decision": "pending",
     "waivers": []

diff --git a/build/version.json b/build/version.json
@@ -1,8 +1,8 @@
 {
-  "build_version": "0.3.11",
+  "build_version": "0.3.12",
   "codex_permission_profiles_since": "0.138.0",
   "codex_cli_tested": "0.144.6",
-  "nddev_builder_plugin_version": "0.3.6",
+  "nddev_builder_plugin_version": "0.3.7",
   "python_requires": ">=3.10",
   "runtime_baseline_ref": "references/codex-baseline.json",
   "schema_version": 2

diff --git a/plugins/nddev-builder/.codex-plugin/plugin.json b/plugins/nddev-builder/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "nddev-builder",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Create and validate native Codex skills, plugins, marketplaces, agents, hooks, MCP servers, app mappings, configuration, instructions, execpolicy rules, and managed requirements.",
   "author": {
     "name": "Danil Silantyev / NDDev",

diff --git a/plugins/nddev-builder/README.md b/plugins/nddev-builder/README.md
@@ -12,8 +12,8 @@ The artifact contracts used by every workflow are documented in
 
 ## Skill inventory
 
-The plugin exposes exactly 28 skills: eleven creator/checker pairs, one
-cross-artifact reviewer, and five workflow/lifecycle skills.
+The plugin exposes exactly 29 skills: eleven creator/checker pairs, one
+cross-artifact reviewer, and six workflow/lifecycle skills.
 
 | Artifact | Creator | Checker |
 | --- | --- | --- |
@@ -30,11 +30,12 @@ cross-artifact reviewer, and five workflow/lifecycle skills.
 | Managed requirements | `codex-requirements-creator` | `codex-requirements-checker` |
 | Cross-artifact review | `codex-artifact-reviewer` | — |
 
-The five workflow/lifecycle skills orchestrate the artifacts above into a
+The six workflow/lifecycle skills orchestrate the artifacts above into a
 complete build cycle:
 
 | Workflow | Skill |
 | --- | --- |
+| Guided first run | `codex-onboarding` |
 | Orientation and routing | `codex-builder-orientation` |
 | Scaffold a whole plugin | `codex-plugin-scaffolder` |
 | Local dev-mode test loop | `codex-plugin-devtest` |

diff --git a/plugins/nddev-builder/references/codex-artifact-contracts.md b/plugins/nddev-builder/references/codex-artifact-contracts.md
@@ -54,3 +54,14 @@ legacy top-level `mcpServers` wrapper. Keep the documentation-correct direct
 map as the generator default, record the validator discrepancy when it occurs,
 and require pinned-runtime discovery rather than rewriting the artifact solely
 to satisfy the stale validator.
+
+Current capability toggles are centralized in the top-level `[features]` table
+(and a few dedicated tables it fronts). Rather than freeze the fast-moving flag
+list here, treat `scripts/check_codex_artifact.py` (which pins the exact
+top-level config surface) and the built-in `$openai-docs` skill as the
+authority for names and defaults. Powerful surfaces an author reaches this way
+include Code Mode, agent memories, tool search, guardian approvals,
+browser/computer use, and multi-agent orchestration; enable only what the task
+needs and prove each at runtime. One stable consequence: web search is on by
+default, so the `features.web_search*` toggles are legacy — the config checker
+rejects them, mirroring Codex's own deprecation notice.
diff --git a/plugins/nddev-builder/scripts/check_codex_artifact.py b/plugins/nddev-builder/scripts/check_codex_artifact.py
@@ -169,8 +169,11 @@
 }
 
 MCP_APPROVAL_MODES = {"auto", "prompt", "writes", "approve"}
-CONFIG_REASONING_EFFORTS = {"minimal", "low", "medium", "high", "xhigh"}
-PLAN_REASONING_EFFORTS = CONFIG_REASONING_EFFORTS | {"none"}
+# The Codex 0.144.6 reasoning-effort ladder (protocol/src/openai_models.rs).
+# config.schema.json types `ReasoningEffort` as a non-empty string, and
+# `model_reasoning_effort`/`plan_mode_reasoning_effort` share the same type as an
+# agent role's effort, so accept the full known ladder for all three (a stricter
+# config set wrongly rejected `max`/`ultra`).
 AGENT_REASONING_EFFORTS = {
     "none",
     "minimal",
@@ -181,6 +184,8 @@
     "max",
     "ultra",
 }
+CONFIG_REASONING_EFFORTS = AGENT_REASONING_EFFORTS
+PLAN_REASONING_EFFORTS = AGENT_REASONING_EFFORTS
 
 DEPRECATED_CONFIG_KEYS = {
     "codex_hooks",

diff --git a/plugins/nddev-builder/skills/codex-builder-orientation/SKILL.md b/plugins/nddev-builder/skills/codex-builder-orientation/SKILL.md
@@ -9,6 +9,8 @@ Resolve every ../../scripts and ../../references path relative to this SKILL.md
 
 The first skill to read for any nddev-builder task: index the artifact families, point at the schema and currency source of truth, and route to the skill that owns the work.
 
+New to the toolkit? Start with `$codex-onboarding` — a guided first run that walks a newcomer from zero to a checked artifact through the paths below.
+
 ## Workflow
 
 1. Name the artifact family the task targets. The generator and checker own the authoritative family list; read it rather than trusting any copy:

diff --git a/plugins/nddev-builder/skills/codex-onboarding/SKILL.md b/plugins/nddev-builder/skills/codex-onboarding/SKILL.md
@@ -0,0 +1,80 @@
+---
+name: codex-onboarding
+description: A guided first run of the nddev-builder toolkit — from zero to a working, checked Codex artifact in ordered steps. Use when new to nddev-builder, onboarding, or unsure which builder skill to start with.
+---
+
+# Codex Onboarding
+
+Resolve every ../../scripts and ../../references path relative to this SKILL.md directory, never the caller working directory.
+
+The fastest correct path from nothing to a working, validated Codex artifact.
+Read `$codex-builder-orientation` once for the family map, pick a path below,
+and let each step hand off to the focused creator, checker, or workflow skill.
+
+## The one thing to understand first
+
+Choose the **smallest native surface** the task needs, because Codex validates
+and loads each one differently:
+
+- `AGENTS.md` for durable repository guidance; a **skill** for a reusable
+  workflow; a **plugin** to distribute skills/hooks/MCP/apps; **MCP or an app**
+  for a live external capability; a **hook** for lifecycle enforcement; a
+  **rule** for outside-sandbox command policy; and a **config/permission
+  profile** for model and safety posture.
+- Codex has **no first-class authored slash commands** — a reusable command
+  workflow is authored as a skill.
+- Custom-agent TOML is a **standalone config-scope file**
+  (`$CODEX_HOME/agents/<name>.toml` or `<repo>/.codex/agents/<name>.toml`), not
+  a plugin-bundled component.
+
+The family list, schemas, and current (Beta/experimental/under-development)
+surfaces live in ../../references/codex-artifact-contracts.md and the two script
+`--help` outputs — read them, never a frozen copy.
+
+## Path 1 — add one artifact to an existing repo or config
+
+1. Name the family (`skill`, `config`, `hook`, `mcp`, `agent`, `rule`,
+   `instructions`, `app`, `requirements`).
+2. Author with the owning creator: `$codex-<family>-creator` (for example
+   `$codex-skill-creator`). It stages a conservative skeleton.
+3. Complete the content, then validate with `$codex-<family>-checker` (or
+   `python3 ../../scripts/check_codex_artifact.py <family> <path>`).
+4. Prove behavior with the runtime step in that family's contract, using a
+   temporary `HOME`/`CODEX_HOME` — a static PASS proves shape only.
+
+## Path 2 — build a whole plugin from an idea
+
+1. `$codex-plugin-scaffolder` — compose the bundle (manifest plus the skills,
+   hooks, MCP servers, and app mapping the idea needs) from intent.
+2. `$codex-plugin-devtest` — register through a temporary marketplace with
+   isolated `CODEX_HOME` and confirm discovery and install.
+3. `$codex-release-review` — gate the whole bundle for release readiness.
+4. `$codex-plugin-publish` — version, catalog, and publish when others install
+   it.
+
+## Path 3 — start or distribute a marketplace
+
+1. `$codex-marketplace-creator` — scaffold the catalog (`local`, `url`,
+   `git-subdir`, or `npm` plugin sources via `--source-type`).
+2. Add plugins with Path 2, then `$codex-release-review`.
+3. `$codex-plugin-publish` for distribution; register and inspect only with the
+   exact target-owned Codex CLI.
+
+## Golden rules (from day one)
+
+- Read `$codex-builder-orientation` first; author with exactly one owning skill
+  and defer to its description.
+- A static generate or check proves shape only — always run the matching
+  checker and then the contract's runtime step in isolated state.
+- Full `agent` and `config` TOML validation needs Python 3.11+; on 3.10 the
+  checker fails closed rather than returning an unchecked PASS.
+- Keep credentials, OAuth tokens, trust hashes, and machine-local paths out of
+  every artifact; reference secrets through the environment.
+- English only. Never mix permission profiles with legacy `sandbox_mode` in one
+  loaded layer.
+
+## Where to go deeper
+
+`$codex-builder-orientation` for the full family map and ownership boundaries,
+and ../../references/codex-artifact-contracts.md for every artifact's exact
+contract, runtime check, and current maturity.
diff --git a/plugins/nddev-builder/skills/codex-onboarding/agents/openai.yaml b/plugins/nddev-builder/skills/codex-onboarding/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Codex Onboarding"
+  short_description: "Guided first run from zero to a checked Codex artifact"
+  default_prompt: "Use $codex-onboarding for a guided first build with the Codex builder toolkit."