Apply codex-kit v1.5.0

.agents/skills/docs-site-ui/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: docs-site-ui
+description: >-
+  Implement or review appearance, layout, responsive behavior, accessibility,
+  or interaction changes in the common-utils-pkg Docusaurus documentation site.
+  Use for docs UI and visual-regression work, not utility source changes or
+  prose-only documentation edits.
+---
+
+# Documentation Site UI
+
+Before editing, inspect the closest same-purpose shipped Docusaurus feature and
+reuse its patterns. The site uses Docusaurus classic and Infima; configuration
+lives in `docusaurus.config.ts` and `sidebars.ts`, global theme overrides live in
+`css/custom.css`, content lives in `docs-md`, and static assets live in `static`.
+Prefer those existing extension points over swizzling or adding dependencies.
+
+Identify the analogue's tokens, spacing, typography, responsive behavior,
+interaction states, and light/dark-mode treatment. Preserve semantic HTML,
+accessible names and instructions, keyboard operation, logical focus, visible
+focus, readable contrast, and non-color status cues. Use ARIA only when native
+semantics are insufficient.
+
+Ask before deliberate divergence from an established analogue, changing a
+written convention, or proceeding when precedents conflict or no trustworthy
+analogue exists. Keep independently changeable UI concerns feature-local and
+leave page or configuration entrypoints focused on composition.
+
+Run the narrowest relevant checks, then `pnpm run format:check` and
+`pnpm run docusaurus:build`. When browser or screenshot tooling is available,
+compare the changed view with its analogue at relevant sizes, themes, and states;
+otherwise report that rendered comparison was unavailable. For visual-regression
+tests under `src`, also use `$verify-source-changes` and follow its test-only
+branch.

.agents/skills/verify-source-changes/SKILL.md

@@ -1,36 +1,28 @@
 ---
 name: verify-source-changes
 description: >-
-  Determine the next semantic version, update the changelog, regenerate derived
-  documentation and exports, then validate source changes in common-utils-pkg.
-  Use whenever files under src are added, updated, moved, or removed.
+  Test and validate changes under src in common-utils-pkg, adding release
+  preparation only when production source changes. Use whenever files under src
+  are added, updated, moved, or removed.
 ---
 
 # Verify Source Changes
 
-## Workflow
+Classify pending `src` changes by behavior, not merely path:
 
-1. Confirm public utilities follow
-   `src/<kebab-case-name>/<kebab-case-name>.ts`, use a camelCase named export,
-   include JSDoc, and have a colocated `.test.ts` file when behavior changes.
-2. Inspect all pending source changes and classify the highest-impact SemVer
-   bump:
-   - **major**: any backward-incompatible public API or behavior change
-   - **minor**: a new public method or substantial backward-compatible update
-   - **patch**: a smaller backward-compatible fix, refactor, or code update
-3. Calculate the next version from `package.json`. Update
-   `docs-md/changelog.md` with a concise entry under that version, merging into
-   an existing unreleased entry when present. Do not change the package version,
-   create a tag, or publish unless explicitly requested.
-4. Run `pnpm run docusaurus:generate`. It rewrites `docs-md/api` and regenerates
-   `src/index.ts`.
-5. Inspect changelog and generated changes. Keep only updates caused by the
-   source change.
-6. Run the relevant focused Vitest test, then:
-   - `pnpm exec biome check .`
-   - `pnpm run test:ci`
-   - `pnpm run build`
-7. Run `pnpm run docusaurus:build`.
-8. Report the recommended version, changelog and generated files, and validation
-   results. If pnpm or a security policy blocks validation, do not bypass it or
-   change dependency policy; report the exact blocker.
+- For test-only changes, read
+  [references/focused-source-testing.md](references/focused-source-testing.md)
+  and follow only that workflow.
+- For production-source changes, read both
+  [references/focused-source-testing.md](references/focused-source-testing.md)
+  and
+  [references/production-release-preparation.md](references/production-release-preparation.md).
+- For mixed test and production changes, follow both references.
+
+Test-only work does not require a SemVer recommendation, changelog entry,
+documentation generation, export generation, build, or release checks unless
+the test changes expose a required production change.
+
+Do not publish, tag, change the package version, alter dependency or security
+policy, or bypass a policy failure unless explicitly requested. Report blockers
+instead.

.agents/skills/verify-source-changes/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Verify Source Changes"
-  short_description: "Version, document, and verify source changes"
-  default_prompt: "Use $verify-source-changes to version, document, and validate pending source changes."
+  short_description: "Test source changes and prepare releases when needed"
+  default_prompt: "Use $verify-source-changes to test pending source changes and prepare production changes for release."

.agents/skills/verify-source-changes/references/focused-source-testing.md

@@ -0,0 +1,13 @@
+# Focused Source Testing
+
+Read this reference for every change under `src`.
+
+1. Inspect the changed contract and nearby tests. Preserve existing assertions
+   unless behavior intentionally changes.
+2. Add or update only focused colocated Vitest coverage for changed observable
+   behavior, regressions, meaningful boundaries, and costly failures. Use one
+   representative case per equivalent behavior; skip implementation details and
+   redundant permutations.
+3. Run the narrowest relevant Vitest command. For broader production changes,
+   also run the repository checks required by the release-preparation reference.
+4. Report the tests run and any unavailable or blocked validation.

.agents/skills/verify-source-changes/references/production-release-preparation.md

@@ -0,0 +1,23 @@
+# Production Release Preparation
+
+Read this reference only when production files under `src` are added, updated,
+moved, or removed.
+
+1. Confirm public utilities follow
+   `src/<kebab-case-name>/<kebab-case-name>.ts`, use a camelCase named export,
+   include JSDoc, and have a colocated `.test.ts` file when behavior changes.
+2. Classify the highest-impact SemVer recommendation:
+   - **major**: backward-incompatible public API or behavior change
+   - **minor**: new public API or substantial backward-compatible update
+   - **patch**: smaller backward-compatible fix, refactor, or code update
+3. Calculate the next version from `package.json`. Update
+   `docs-md/changelog.md` under that version, merging with an existing unreleased
+   entry when present. Do not change the package version unless explicitly
+   requested.
+4. Run `pnpm run docusaurus:generate`, which replaces `docs-md/api` and
+   regenerates `src/index.ts`. Inspect generated and changelog changes, keeping
+   only changes caused by the production source work.
+5. After the focused test, run `pnpm exec biome check .`, `pnpm run test:ci`,
+   `pnpm run build`, and `pnpm run docusaurus:build`.
+6. Report the recommended version, changelog and generated changes, validation
+   results, and exact blockers.

.codex-kit-state.json

@@ -1,9 +1,9 @@
 {
   "version": 1,
   "template": {
-    "availableHash": "f6a02cb2b17078ae108000975e2c2105b6e208e8f7cfeeb19e1765fb52d39b81",
-    "availableVersion": "1.1.5",
-    "appliedHash": "f6a02cb2b17078ae108000975e2c2105b6e208e8f7cfeeb19e1765fb52d39b81",
-    "appliedAt": "2026-08-14T05:46:22.901Z"
+    "availableHash": "6b9dffb93c7ef2e775904edd18de29d3f80cb21604b9aa2c0bf554d3ce5933a9",
+    "availableVersion": "1.5.0",
+    "appliedHash": "6b9dffb93c7ef2e775904edd18de29d3f80cb21604b9aa2c0bf554d3ce5933a9",
+    "appliedAt": "2026-09-16T07:28:37.117Z"
   }
 }

AGENTS.md

@@ -34,16 +34,21 @@
 
 ## Changes And Verification
 
+- Before work, classify the requested behavior and load only the project skills
+  and skill-owned references needed for that work and its validation.
 - Match existing structure and reuse existing types and helpers. Keep changes
   minimal, localized, and limited to the requested behavior.
+- Keep shared configuration and behavior in one source of truth at the narrowest
+  shared scope. Do not change architecture, core module boundaries, or project
+  paradigms without explicit approval.
 - Add or update focused colocated Vitest tests for changed contracts,
   regressions, and meaningful boundaries, using one representative case per
   equivalent behavior. Preserve existing assertions unless behavior
   intentionally changes; skip redundant and implementation-detail cases.
-- After adding, updating, moving, or removing source code, use the project
-  `$verify-source-changes` skill to determine the next SemVer version, update
-  `docs-md/changelog.md`, regenerate documentation and exports, then inspect
-  generated changes and run the required checks.
+- For changes under `src`, use `$verify-source-changes`; it routes test-only
+  work to focused testing and production-source work to testing plus release
+  preparation.
+- For Docusaurus appearance or interaction work, use `$docs-site-ui`.
 - Do not use `format` or `fix` scripts for read-only validation because they
   rewrite files. Inspect generated changes after build or documentation
   generation.
@@ -62,7 +67,13 @@
 
 - `TEMPLATE_AGENTS.md` is a staged reusable reference; active guidance lives in
   this file and applicable project skills under `.agents/skills`.
+- Read and preserve `PLANS.md` when it exists. Create it only for real durable
+  product context, decisions, roadmap/status, or resume-worthy milestones; do
+  not invent history or use it as a per-change changelog.
 - When `codex-kit project status` reports `reconciliation required`, use the
   global `$codex-kit-reconcile-agents` skill. Preserve local rules, merge only
-  applicable reusable guidance, validate changes, and run
-  `codex-kit project mark-applied` only after validation succeeds.
+  applicable reusable guidance, and validate changes. Never run
+  `codex-kit project sync` on the user's behalf. Run
+  `codex-kit project mark-applied` only after an eligible user-run init or sync,
+  an initial `reconciliation required` status, and successful reconciliation
+  and validation.

TEMPLATE_AGENTS.md

@@ -12,8 +12,29 @@ product context, and local conventions in the project's active `AGENTS.md`.
   priorities, deferred requirements, product or implementation decisions, and
   major completed milestones.
 
+## PLANS.md Maintenance
+
+- Read and preserve an existing `PLANS.md` during initialization and template
+  reconciliation; semantically merge durable content instead of replacing it.
+- Create `PLANS.md` only when repository evidence contains real roadmap items,
+  durable decisions, or resume-worthy completed work. Never invent or backfill
+  speculative history.
+- Keep it concise, using sections such as current context, decisions,
+  roadmap/status, and major milestones. It is not a per-change changelog.
+- Move roadmap or history misplaced in `AGENTS.md` into `PLANS.md` when the
+  content is durable, and keep `AGENTS.md` focused on always-on instructions.
+
 ## Instructions And Skills
 
+- Before planning, classify the requested work and select only the project
+  skills and supporting references required for that work and its necessary
+  validation. Do not load every available or linked guide preemptively.
+- Route every task by narrow relevance. Representative examples: testing work
+  uses applicable testing guidance; UI appearance or interaction work uses
+  styling/UI guidance; visual-regression work may require both; unrelated
+  tooling uses neither. Load release or deployment guidance only when that
+  operation is requested or required. Apply the same classification to any
+  other project-specific workflow.
 - Keep `AGENTS.md` focused on durable, always-applicable repository context:
   architecture, conventions, commands, safety and authorization boundaries,
   verification expectations, and concise pointers to specialized workflows.
@@ -33,6 +54,9 @@ product context, and local conventions in the project's active `AGENTS.md`.
   skill.
 - Each project skill must use valid YAML frontmatter with a clear `name` and a
   `description` that states when the skill should trigger.
+- Put substantial conditional detail in a skill-owned Markdown reference only
+  when it improves selective loading. The owning `SKILL.md` must state exactly
+  when to read it; never replace actionable guidance with a bare link.
 
 ## Template Maintenance
 
@@ -77,6 +101,9 @@ including local/template conflicts and any generalized template-worthy
 promotion. Keep critical safety, authorization, secrets, database, deployment,
 and destructive-operation rules always-on in `AGENTS.md`; extract only concrete
 conditional procedures into validated project skills.
+Classify both existing and incoming guidance by task relevance, keep the
+always-on baseline concise, and route conditional detail through narrowly
+triggered skills and selectively read references.
 
 ## Core Behavior
 
@@ -89,9 +116,12 @@ conditional procedures into validated project skills.
 - Work within imperfect architecture. If it prevents safe completion, stop,
   explain the limitation, propose the smallest viable design change, and wait
   for approval. Escalate blockers instead of bypassing them.
-- Reuse existing constants, schemas, enums, shared types, and components before
-  creating duplicates. Add reusable domain values at their existing source of
-  truth instead of scattering magic strings.
+- Keep identical configuration and behavior in one source of truth at the
+  narrowest shared scope. Reuse that owner across callers or features; create a
+  separate implementation or instance only when scope, lifecycle, or behavior
+  genuinely differs. Reuse existing constants, schemas, enums, shared types,
+  and components before creating duplicates. Add reusable domain values at
+  their existing source of truth instead of scattering magic strings.
 - Replace numeric literals that encode domain rules, limits, durations, units,
   or protocol values with descriptively named constants. Universally obvious
   structural values, such as basic indexes or empty-state values, may remain