Skip to content

feat(catalog): config-first routed catalog row defaults - #8797

Merged
lidge-jun merged 2 commits into
devfrom
feat/routed-catalog-defaults-6872
Nov 16, 2026
Merged

lidge-jun merged 2 commits into
devfrom
feat/routed-catalog-defaults-6872

Conversation

@lidge-jun

@lidge-jun lidge-jun commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Summary

Operators can now set defaults for generated routed (non-native) Codex catalog rows in config.json, so ocx sync stops discarding hand edits of these fields (owner decision on #6872: the three instruction flags plus verbosity, config-first, provider limits always win, no Dashboard UI yet).

{
  "routedCatalogDefaults": {
    "includeSkillsUsageInstructions": true,
    "includeAppsUsageInstructions": true,
    "includePluginUsageInstructions": false,
    "defaultVerbosity": "low"
  }
}
  • Allowlist only. The four camelCase fields map to include_skills_usage_instructions, include_apps_usage_instructions, include_plugin_usage_instructions and default_verbosity. Verbosity support is not a setting: supportVerbosity is rejected, so support always stays the provider's, model's or template's own value. The schema is strict: an unknown key (including snake_case spellings or other row fields) or a bad value drops the whole block with a load warning and a diagnostics entry, and config writes reject it (the workflowBudget pattern). Tool mode, search, truncation, auto review and identity contracts are untouched.
  • Precedence. Defaults are applied after routed normalization and before provider/model metadata: provider or model declaration > routedCatalogDefaults > native template value > strict-field fallback. defaultVerbosity only reaches rows that already support verbosity: the final strict pass removes default_verbosity whenever support_verbosity is false, and a test pins that a default on a model without verbosity support advertises nothing.
  • Scope. Ordinary routed rows only, on both derivation paths (with and without a native template), in catalog sync (convergence.ts), retained sync and the Codex-shaped /v1/models list. Native rows, account-bound native clones and Codex-forward native-capability aliases (custom openai/<native> rows that mirror the native contract) are left alone. Rows retained during a provider outage keep their values until they are regenerated. The Ultra Fast retention from fix(catalog): retain operator Ultra Fast declarations across regeneration #6819 is unchanged.
  • Captured once per build. Each writer resolves the block once into a frozen snapshot and passes it in; derivation never reads config. Omitting the block, or leaving it empty, reproduces today's rows exactly, and explicit false stays false.

Choices worth a look:

Docs: a new "Routed row defaults" section in reference/configuration/catalog.md (EN, ES; Spanish is the only locale with that page), and a new structure/catalog-routed-defaults.md registered in the manifest with INDEX.md regenerated. structure/catalog.md and structure/config.md sit at their 600-line budget, so they gain only cross-references on existing lines.

Closes #6872

Verification

  • The new tests tests/config/config-routed-catalog-defaults.test.ts and tests/codex-integration/catalog-routed-defaults.test.ts failed before the implementation (missing module; 10 catalog cases red, 3 no-op controls green). They cover unset vs explicit false, each flag, verbosity enum validation, a provider that disowns verbosity winning, native and native-alias non-interference, no-template derivation, idempotent repeated regeneration, clearing the block and strict-schema rejection.
  • After rebasing onto origin/dev 595de1e: the new tests, both layout guards, the file-size ratchet and the Spanish docs guard pass (86 pass, 0 fail). Existing catalog/verbosity suites (codex-catalog, catalog-verbosity-default, ollama-native, kiro-adapter) pass 494, 0 fail. bun run structure:check and bun run privacy:scan pass.
  • Before the rebase: bun run typecheck reported no errors.
  • bun run test:changed hit the runner's 15-minute limit on a heavily loaded shared host (exit 124) after every selected file reported: 55,915 pass, 60 fail. An isolated rerun of the 16 files with failures left 24 failing, mostly npm/subprocess, filesystem-watch, image and live-relay timeouts that varied between runs, in files that never set the block. That they are load-related is inferred, not proven against the base commit. CI's test shards on this head are the authoritative check.
  • supportVerbosity removal (cf31cfc8e4, after the merge-manager review): the routed-defaults config and catalog tests pass (19 pass, 0 fail). Against the previous source the new rejection case fails. codex-catalog, catalog-verbosity-default, the Spanish docs guard, the layout guard and the file-size ratchet pass (385 pass, 0 fail). bun run typecheck, structure:check and privacy:scan pass.
  • CI on the previous head 555b574d1c passed all 32 checks; CI is re-running on cf31cfc8e4.
  • NOT RUN: full local bun run test (host load); the CI shards above cover the suite.

Checklist

  • Scope stays focused and avoids unrelated cleanup.
  • Docs or release notes were updated when needed.
  • Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Summary by CodeRabbit

  • New Features
    • Added an optional configuration for default settings on routed catalog rows, including skills, apps, plugin instructions, and verbosity.
    • Defaults respect explicit provider or model settings, apply only to supported routed rows, and preserve existing values when omitted. Invalid settings trigger a warning when loaded and are rejected when saving.
  • Documentation
    • Expanded configuration guidance with details on supported settings, how defaults apply, and their limitations.

Routed Codex catalog rows are regenerated on every sync, so a hand edit to
include_*_usage_instructions or the verbosity fields in opencodex-catalog.json
was lost on the next ocx sync. Add a typed top-level routedCatalogDefaults
block to config.json that sets exactly the owner-approved allowlist on every
freshly derived routed row:

- includeSkillsUsageInstructions -> include_skills_usage_instructions
- includeAppsUsageInstructions   -> include_apps_usage_instructions
- includePluginUsageInstructions -> include_plugin_usage_instructions
- supportVerbosity               -> support_verbosity
- defaultVerbosity ("low" | "medium" | "high") -> default_verbosity

Omitted fields keep today's derivation and explicit false stays false. The
strict schema rejects unknown fields and invalid enum values at the write
boundary; a malformed hand edit drops the whole block with a load warning
and a diagnostics entry.

Catalog writers capture the block once per build (resolveRoutedCatalogDefaults)
and pass it into buildCatalogEntriesFromObservedState; derivation never reads
config. deriveEntry applies it on both routed paths (template clone after
routed normalization, and the no-template fallback) before provider/model
metadata, so concrete provider declarations win and the final strict pass
still drops default_verbosity whenever support_verbosity is false. Native,
account-bound and Codex-forward native-capability rows are untouched, and
rows retained during a provider outage keep their values until regenerated.
Convergence, retained sync and Codex-shaped /v1/models discovery all pass
the captured value. No Dashboard UI in this change.

Closes #6872
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

Adds the routedCatalogDefaults configuration block for selected routed catalog row fields. Validated values flow through catalog generation and model-list construction. Native rows and retained rows are excluded from default application. Tests and documentation cover configuration, precedence, and catalog behavior.

Changes: Routed Catalog Defaults

Layer / File(s) Summary
Define and validate routed defaults
src/types/routed-catalog-defaults.ts, src/types/config.ts, src/config/schema/*, src/config/diagnostics.ts, src/config/load-degrade.ts, tests/config/config-routed-catalog-defaults.test.ts, scripts/test-layout/layout-config.json
Adds the optional configuration type and strict schema for three instruction flags and defaultVerbosity. Invalid values are dropped during schema parsing, warned about during loading and diagnostics, and rejected at the write boundary. Tests cover valid and invalid values, resolution, and frozen snapshots.
Apply defaults during catalog generation
src/codex/catalog/*, src/codex/convergence.ts, src/server/codex-model-list.ts, tests/codex-integration/catalog-routed-defaults.test.ts, scripts/test-layout/layout-codex-collision.json, tests/fixtures/test-layout-expected.json
Passes resolved defaults into routed row derivation and applies allowlisted values in templated and fallback paths. Provider/model metadata takes precedence; native aliases, native rows, and outage-retained rows are excluded. Tests cover derivation, convergence, retained sync, live model lists, repeat writes, and clearing the defaults.
Document the configuration and behavior
structure/catalog-routed-defaults.md, structure/INDEX.md, structure/catalog.md, structure/config.md, structure/manifest.json, docs-site/src/content/docs/reference/configuration/catalog.md
Documents the configuration fields, validation, precedence, affected catalog paths, excluded rows, and reload behavior. Adds the contract document to the structure index and links to it from related catalog and configuration references.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Config
  participant prepareCatalog
  participant buildCatalogEntriesFromObservedState
  participant deriveEntry
  participant applyRoutedCatalogDefaults
  Config->>prepareCatalog: provide routedCatalogDefaults
  prepareCatalog->>buildCatalogEntriesFromObservedState: pass resolved defaults
  buildCatalogEntriesFromObservedState->>deriveEntry: derive routed row
  deriveEntry->>applyRoutedCatalogDefaults: set allowlisted fields
Loading
Merge Risk: Minimal · up to cf31c

This adds an opt-in config block for routed catalog row defaults. Omitting the block leaves behavior unchanged. No concrete merge-blocking risk was found.

Pre-merge checks: Passed 3 · Inconclusive 1

Failed Failed checks: 1 inconclusive

Check name Status Explanation Resolution
Linked Issues check Inconclusive Only #6872 is directly linked, and it is open. Its config-side requirements are met at reviewed head cf31cfc.

Met:
- Config block: routedCatalogDefaults is added to OcxConfig (src/types/config…
Provide evidence of the owner decision that defers the Dashboard UI, such as a link to the #6872 comment. If the decision does not defer it, the PR must add a Dashboard section that reads and writes routedCatalogDefaults, with an inherit-…
Passed Passed checks: 3 passed

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title "feat(catalog): config-first routed catalog row defaults" matches the main change: a new config-driven routedCatalogDefaults block that sets instruction flags and defaultVerbosity on ord…
Out of Scope Changes check Passed Every changed area maps to #6872 or supports it:
- Config and types: src/types/routed-catalog-defaults.ts, src/types/config.ts, src/config/schema/routed-catalog-defaults.ts, src/config/schema/config-s…
Full details: Title check

Explanation

The title "feat(catalog): config-first routed catalog row defaults" matches the main change: a new config-driven routedCatalogDefaults block that sets instruction flags and defaultVerbosity on ordinary routed catalog rows. The changeset adds the config schema, types, derivation hooks in derive-entry.ts and routed-defaults.ts, catalog writer wiring, validation diagnostics, docs, and tests, all of which fit this title. The title is specific and concise, and it follows a conventional commit style. Nothing in the changeset falls outside what the title describes.

Full details: Out of Scope Changes check

Explanation

Every changed area maps to #6872 or supports it:

  • Config and types: src/types/routed-catalog-defaults.ts, src/types/config.ts, src/config/schema/routed-catalog-defaults.ts, src/config/schema/config-schema.ts. These define and validate the block.
  • Load and diagnostics: src/config/diagnostics.ts and src/config/load-degrade.ts warn on an invalid block. Config writes reject it.
  • Derivation and writers: src/codex/catalog/routed-defaults.ts, derive-entry.ts, build-entries.ts, retained-sync.ts, convergence.ts, and src/server/codex-model-list.ts apply the snapshot to ordinary routed rows only.
  • Tests: tests/config/config-routed-catalog-defaults.test.ts and tests/codex-integration/catalog-routed-defaults.test.ts cover the requirements.
  • Supporting files: layout JSON, the layout fixture, structure docs, manifest, and INDEX. These register the new files for the layout guards. The fixture also adds an existing responses test to its group. It is a registration change only, with no code effect.
  • Docs: EN and ES catalog reference pages describe the block and its limits.

No change adds unrelated behavior. Tool mode, search, truncation, auto review, and identity fields are not touched.

Full details: Linked Issues check

Explanation

Only #6872 is directly linked, and it is open. Its config-side requirements are met at reviewed head cf31cfc.

Met:

  • Config block: routedCatalogDefaults is added to OcxConfig (src/types/config.ts). A strict Zod schema (src/config/schema/routed-catalog-defaults.ts) accepts only the three include_*_usage_instructions flags and defaultVerbosity. Tool, search, truncation, and identity fields are not accepted.
  • Durable: applyRoutedCatalogDefaults (src/codex/catalog/routed-defaults.ts) writes the values during derivation. They are not stored in the generated catalog file.
  • Unset fields keep current behavior. Explicit false stays false, because the check is typeof === "boolean".
  • Precedence: the function runs after routed normalization and before provider/model metadata. This gives provider/model > defaults > template > strict fallback, as the issue asks.
  • Verbosity: the final ensureStrictCatalogFields pass removes default_verbosity when support_verbosity is false. supportVerbosity was removed as a setting, per the PR description.
  • Native rows, account-bound clones, and Codex-forward native aliases are excluded, per the PR description.
  • Writers: defaults reach convergence, retained sync, and buildCodexModelList through a snapshot captured once per build.

Not established:

  • #6872 asks for a Dashboard page or panel with an "inherit template" option per field. The PR adds no Dashboard surface. The PR and the supplied objectives say the owner deferred the UI. That decision is not in the linked issue text supplied, so it cannot be verified here.
  • The issue name routedDefaults became routedCatalogDefaults. This is a naming change only.
  • The author reports the cited tests as passing. I did not run them. Exact-head CI status is not established.

Resolution

Provide evidence of the owner decision that defers the Dashboard UI, such as a link to the #6872 comment. If the decision does not defer it, the PR must add a Dashboard section that reads and writes routedCatalogDefaults, with an inherit-template option for each field. Also confirm that CI passes on cf31cfc.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 595de1e and cf31cfc.

Files selected for processing: 24

  • docs-site/src/content/docs/es/reference/configuration/catalog.md
  • docs-site/src/content/docs/reference/configuration/catalog.md
  • scripts/test-layout/layout-codex-collision.json
  • scripts/test-layout/layout-config.json
  • src/codex/catalog/build-entries.ts
  • src/codex/catalog/derive-entry.ts
  • src/codex/catalog/retained-sync.ts
  • src/codex/catalog/routed-defaults.ts
  • src/codex/convergence.ts
  • src/config/diagnostics.ts
  • src/config/load-degrade.ts
  • src/config/schema/config-schema.ts
  • src/config/schema/routed-catalog-defaults.ts
  • src/server/codex-model-list.ts
  • src/types/config.ts
  • src/types/routed-catalog-defaults.ts
  • structure/INDEX.md
  • structure/catalog-routed-defaults.md
  • structure/catalog.md
  • structure/config.md
  • structure/manifest.json
  • tests/codex-integration/catalog-routed-defaults.test.ts
  • tests/config/config-routed-catalog-defaults.test.ts
  • tests/fixtures/test-layout-expected.json

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 4 remain after this review.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

✅ Deterministic PR hygiene checks passed.

@github-actions github-actions Bot added the enhancement New feature or request label Nov 16, 2026
@lidge-jun
lidge-jun marked this pull request as ready for review November 16, 2026 06:04
@lidge-jun
lidge-jun requested a review from Ingwannu as a code owner November 16, 2026 06:04
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T16:01:20.193182Z cf31cfc Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@lidge-jun

Copy link
Copy Markdown
Owner Author

Merge-manager review against the #6872 owner decision ("expose the three instruction flags plus verbosity as config-first routed-row defaults (provider limits always win). Dashboard UI later."): send back for one change.

The allowlist in src/codex/catalog/routed-defaults.ts writes five fields: the three instruction flags (includeSkillsUsageInstructions, includeAppsUsageInstructions, includePluginUsageInstructions), defaultVerbosity, and supportVerbosity. The decision names one verbosity default, and supportVerbosity is not a structural enable/scope key — it writes the row's support_verbosity capability flag. It also runs against "provider limits always win": defaults are applied before provider/model metadata, so an explicit provider declaration still wins, but for a provider that declares nothing, supportVerbosity: true turns on verbosity the row/provider never claimed. Because ensureStrictCatalogFields already strips default_verbosity whenever support_verbosity ends up false, the only thing supportVerbosity adds is the ability to override that limit.

Please drop supportVerbosity from the schema (src/config/schema/routed-catalog-defaults.ts), types, applyRoutedCatalogDefaults, docs (en + es), structure/catalog-routed-defaults.md and the tests, keeping defaultVerbosity so it applies only to rows that already support verbosity; add a test that defaultVerbosity on a row with support_verbosity: false advertises nothing. If the owner explicitly wants a support override, it needs its own decision. Everything else (no dashboard UI, routed rows only, native rows and Codex-forward native aliases untouched, invalid shapes ignored with a warning) matches the decision; the merge waits for the change, green exact-head CI and dev being green.

The #6872 decision exposes the three instruction flags plus a verbosity
default, with provider limits always winning. supportVerbosity let an
operator turn verbosity support on for a model whose provider declares
nothing, which goes past the decision. Remove it from the type, schema,
apply function, docs (en, es) and structure doc; the strict schema now
rejects it. defaultVerbosity only reaches rows that already support
verbosity: the final strict pass drops it elsewhere, and a new test pins
that a default on a model without verbosity support advertises nothing.
@lidge-jun

Copy link
Copy Markdown
Owner Author

Merge-manager re-review of 555b574..cf31cfc against the #6872 owner decision: cleared.

  • supportVerbosity is removed from the type, the strict schema, applyRoutedCatalogDefaults, the English and Spanish docs and the structure doc. The block now accepts exactly the three instruction flags plus defaultVerbosity, and {supportVerbosity: true|false} is rejected as an unknown key.
  • defaultVerbosity never turns verbosity support on. The new test "a default on a model without verbosity support advertises nothing" checks that a restrictive template row with a default is identical to the same row without one. A provider that declares supportsVerbosity: true still receives the configured level.
  • The block is new on this branch, so no saved config contains supportVerbosity and nothing needs migrating.

The PR merges after the repaired dev passes its batched lane=all and the full CI for this exact head is green.

@lidge-jun

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: cf31cfc8e4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@lidge-jun

Copy link
Copy Markdown
Owner Author

Maintainer integration of #8797 at cf31cfc (closes #6872, config-first routedCatalogDefaults), reviewed against the #6872 owner decision.

  • Scope: the block accepts exactly the three instruction flags plus defaultVerbosity. supportVerbosity was removed after the owner review, and the strict schema rejects it. defaultVerbosity reaches only rows that already support verbosity and never turns support on, which a test pins. Provider and model declarations always win, and there is no dashboard UI.
  • Gate: CI is green on this exact head, including enforce-target. Codex completed on this head with no unresolved findings, CodeRabbit reviewed this head with no actionable comments, and no thread is open. assert-mergeable-review: OK. The simulated merge onto the dev of this moment is clean, with no file over its size cap. Dev: batch lane=all 43896659099 on 8c948a4 was fully green, and only fix(images): enforce the resolved destination for video submit and poll #8838 has merged since.

@lidge-jun
lidge-jun merged commit d27aac5 into dev Nov 16, 2026
40 of 41 checks passed
@lidge-jun
lidge-jun deleted the feat/routed-catalog-defaults-6872 branch November 16, 2026 16:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Configurable defaults for routed catalog rows

1 participant