@open-agent-toolkit/cli 0.3.9 → 0.3.11

package/assets/skills/subagent-orchestration/references/provider-codex.md

@@ -1,7 +1,7 @@
 ---
-guidance_version: 2026-09-24
-last_verified: 2026-09-24
-review_after: 2026-12-22
+guidance_version: 2026-10-01
+last_verified: 2026-10-01
+review_after: 2026-12-30
 ---
 
 # Codex and OpenAI Model Selection
@@ -13,16 +13,19 @@ model examples below. Launch mechanics for OAT dispatch live in
 
 ## Current Families
 
-Use verified GPT-6 Sol/Luna model IDs for routine new Codex work. GPT-6 Astra
+Use `gpt-6.1-sol` for new Sol routes and `gpt-6-luna` for bounded Luna work.
+This Sol selector migration preserves the existing task-class effort guidance;
+it does not claim a newly measured workload advantage. GPT-6 Astra
 is a supported Frontier candidate:
 
 - `gpt-6-astra`: Frontier candidate for especially demanding work; the bundled
   recommendation uses high and xhigh, while the supported catalogue also
   permits low, medium, and max;
-- `gpt-6-sol`: high-capability implementation and reasoning route;
+- `gpt-6.1-sol`: high-capability implementation and reasoning route;
 - `gpt-6-luna`: cost-sensitive, bounded work.
 
-Public engineering benchmarks show task-dependent Astra gains over Sol, with
+The earlier public engineering benchmarks show task-dependent Astra gains
+over GPT-6 Sol, with
 cost and runtime tradeoffs; they do not establish a universal replacement. The
 September frontier-release comparison remains review-pending in the separate
 model-selection vault, and no matched OAT workload evaluation has qualified a
@@ -30,8 +33,8 @@ routine default change. Astra's Frontier inclusion is a user-directed
 preference. Keep the Sol task-class defaults below while that evidence is
 reconciled and local task fit is evaluated.
 
-The GPT-5.6 Sol/Luna/Terra targets remain supported for explicit configurations
-and established workloads. Re-evaluate economics and qualitative routing on
+GPT-6 Sol (`gpt-6-sol`) and the GPT-5.6 Sol/Luna/Terra targets remain supported
+for explicit configurations and established workloads. Re-evaluate economics and qualitative routing on
 representative work before carrying over GPT-5.6-specific comparisons.
 
 Direct API specialist routes:
@@ -48,18 +51,24 @@ name includes `codex`.
 ## Dated Task-Class Matrix
 
 These are current task-class starting points, not an evaluated ordering across
-providers or a promise about relative GPT-6 latency and price. All shown
+providers or a promise about relative GPT-6 or GPT-6.1 latency and price. All shown
 model/effort pairs are in the local Codex catalogue.
 
-| Task class               | Default                                    | Escalation                                                            | Floor notes                                                                   |
-| ------------------------ | ------------------------------------------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `mechanical-recon`       | `gpt-6-luna`, high                         | `gpt-6-sol`, medium                                                   | Lower effort is suitable only when a miss is cheap and mechanically detected. |
-| `intelligent-recon`      | `gpt-6-sol`, medium                        | Sol high                                                              | Preserve verification for silent-miss-prone reconnaissance.                   |
-| `default-implementation` | `gpt-6-sol`, medium                        | Sol high                                                              | Luna is for independently bounded, strongly verified work.                    |
-| `hard-reasoning`         | `gpt-6-sol`, high                          | Sol xhigh                                                             | Narrow the problem before raising effort.                                     |
-| `consequential`          | `gpt-6-sol`, high, plus independent review | Sol xhigh for a reasoning-depth bottleneck; max only after evaluation | The root retains consequential authorization.                                 |
-
-The bundled Frontier ladder ends with Astra xhigh after Sol xhigh and Astra
+| Task class               | Default                                      | Escalation                                                            | Floor notes                                                                   |
+| ------------------------ | -------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `mechanical-recon`       | `gpt-6-luna`, high                           | `gpt-6.1-sol`, medium                                                 | Lower effort is suitable only when a miss is cheap and mechanically detected. |
+| `intelligent-recon`      | `gpt-6.1-sol`, medium                        | Sol high                                                              | Preserve verification for silent-miss-prone reconnaissance.                   |
+| `default-implementation` | `gpt-6.1-sol`, medium                        | Sol high                                                              | Luna is for independently bounded, strongly verified work.                    |
+| `hard-reasoning`         | `gpt-6.1-sol`, high                          | Sol xhigh                                                             | Narrow the problem before raising effort.                                     |
+| `consequential`          | `gpt-6.1-sol`, high, plus independent review | Sol xhigh for a reasoning-depth bottleneck; max only after evaluation | The root retains consequential authorization.                                 |
+
+[OpenAI's GPT-6.1 Sol model reference](https://developers.openai.com/api/docs/models/gpt-6.1-sol)
+identifies `gpt-6.1-sol` and the supported efforts `low`, `medium`, `high`,
+`xhigh`, and `max`. Do not emit `none` or `minimal` for this family. For direct
+API tool calls, use the Responses API. Verify the launching Codex runtime
+independently of API availability.
+
+The bundled Frontier ladder ends with Astra xhigh after Sol 6.1 xhigh and Astra
 high. The supported Astra and Sol effort sets both end at max, so Sol max
 remains available for explicit configuration even though it is no longer in
 the bundled Frontier recommendation.

package/assets/skills/subagent-orchestration/references/provider-cursor.md

@@ -1,12 +1,14 @@
 ---
-guidance_version: 2026-09-25
-last_verified: 2026-09-25
-review_after: 2026-12-24
+guidance_version: 2026-10-01
+last_verified: 2026-10-01
+review_after: 2026-12-30
 catalog_basis:
   Cursor desktop 3.21.18 resolved Grok 4.6 and Fable 5.1 effort selectors in
   native subagent hooks, and Grok 4.7 only as bare flat IDs; Cursor desktop
   3.20.14 resolved all five Opus 5.5 effort selectors; GPT-6 Sol/Luna were
-  absent from the observed Cursor catalog
+  absent from the observed Cursor catalog; the 2026-10-01 CLI catalog lists
+  Sonnet 5.5 flat IDs; Cursor desktop 3.22.12 matched five exact-ID Sonnet
+  5.5 pins while every bracket-form Sonnet 5.5 probe fell back
 ---
 
 # Cursor Model Selection
@@ -51,8 +53,8 @@ Cursor desktop 3.20.14 resolved all five `claude-opus-5-5[effort=...]`
 selectors to corresponding flat IDs in native hooks; on 2026-09-25, Cursor
 desktop 3.21.18 did the same for Grok 4.6 and Fable 5.1. See the
 probe records at `packages/cli/src/providers/cursor/codec/__fixtures__/README.md`.
-GPT-6 Sol/Luna were absent from the observed Cursor catalogue, so their Codex
-availability does not authorize Cursor routes.
+GPT-6 Sol/Luna and GPT-6.1 Sol were absent from the 2026-10-01 Cursor CLI
+catalogue, so their Codex availability does not authorize Cursor routes.
 
 | Task class               | Default                                                             | Economy                                            | Escalation                                                  | Floor notes                                                                                                      |
 | ------------------------ | ------------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
@@ -90,8 +92,34 @@ Grok 4.7 has no approved mapping. Every bracket spelling tried
 (`grok-4.7[effort=...]` with and without `fast`, `reasoning=`, and
 `grok-4-7[...]`) fell back to that same account default, which is easy to
 mistake for success because it is itself a Grok 4.7 model. Only bare flat IDs
-such as `grok-4.7-medium` resolved as requested, and the approved catalogue
-does not emit bare IDs. Do not pin Grok 4.7 until a mapping is approved.
+such as `grok-4.7-medium` resolved as requested, but Grok 4.7 still lacks
+its own approved registry entry and complete per-pin evidence. It stays outside
+the shipped catalogue. This is a family-specific admission gap, not a blanket
+prohibition of exact-ID pins.
+
+## Sonnet 5.5 Exact-ID Pin Evidence
+
+The 2026-10-01 Cursor CLI catalogue lists
+`claude-sonnet-5-5-low|medium|high|xhigh|max`. In Cursor desktop 3.22.12,
+every `claude-sonnet-5-5[effort=...]` probe fell back to the account default,
+`grok-4.7-high-fast`. Exact-ID pins
+`claude-sonnet-5-5-low|medium|high|xhigh|max` instead matched their requested
+rungs in `subagentStart`, Shell `preToolUse`, and `subagentStop`. The Opus 5.5
+low positive control matched its established mapping; unknown-family and
+Sonnet 5.5 `ultra` exact-ID controls both fell back to `grok-4.7-high-fast`.
+Catalog visibility or a subagent self-report does not establish those results.
+The 16 correlated summary rows and 64 native events from both rounds live in
+`packages/cli/src/providers/cursor/codec/__fixtures__/cursor-pin-probe-2026-10-01.jsonl`
+and `cursor-pin-probe-2026-10-01-events.jsonl`; the adjacent `README.md` records
+provenance and excludes unrelated discovery calls.
+
+Sonnet 5.5 mappings write the verified exact ID as frontmatter `model`.
+Existing Sonnet 5, Opus, Fable, GPT, and Grok mappings retain their independently
+verified selectors. Neither selector form is universally valid: every exact-ID
+mapping requires native hook evidence, non-default-rung and invalid-selector
+controls, and an explicit approved registry entry. There is no generic
+pass-through of flat CLI IDs. See the
+[probe runbook](../../../../apps/oat-docs/docs/contributing/verifying-cursor-pins.md).
 
 ## Historical Opus Cursor Probe Evidence (Retired)
 
@@ -177,8 +205,10 @@ and non-thinking variants.
 - `claude-fable-5-1-thinking-high`: eligible specialist for hard reasoning and
   the bundled Frontier terminal target; xhigh only for evaluated long-horizon
   work. Cursor lists Fable as "NO ZDR"; confirm retention eligibility.
-- `claude-sonnet-5-thinking-high`: strong provider-diversity alternative for
-  normal implementation and agentic work when available.
+- `claude-sonnet-5-5-high`: exact-ID provider-diversity option for normal
+  implementation and agentic work; qualify task performance separately.
+- `claude-sonnet-5-thinking-high`: supported compatibility option for
+  established workflows.
 - `gpt-5.4-mini-medium`: economical general tool and coding worker.
 - `gpt-5.4-nano-medium`: strict extraction, classification, ranking, and simple
   read-only tool calls. Not a semantic repository worker.

package/assets/templates/state.md

@@ -54,6 +54,7 @@ oat_workflow_origin: native # native | imported
 #   implementation_fingerprint: null # new generations use sha256:effective-delta-v2:<digest>; stored v1 values keep v1 semantics
 #   freshness_head: null # rolling accepted tree checkpoint
 #   freshness_fingerprint: null # full effective delta at freshness_head
+#   waivers: [] # append-only operator waivers {waived_by, reason, from_commit, to_commit, covered_fingerprint, waived_at}; never self-issued, never under OAT_AUTONOMOUS=1
 #   launch_state: not_started # not_started | intent_persisted | accepted | result_persisted | not_accepted
 #   launch_attempt_id: null
 #   launch_started_at: null

package/dist/commands/backlog/new.d.ts

@@ -1,4 +1,4 @@
-import { type PjmTemplateTier } from '../pjm/template-source.js';
+import { type TemplateTier } from '../shared/template-source.js';
 import { initializeBacklog } from './init.js';
 import { regenerateBacklogIndex, type RegenerateBacklogIndexResult } from './regenerate-index.js';
 export interface CreateBacklogItemOptions {
@@ -20,7 +20,7 @@ export interface CreateBacklogItemResult {
     backlogRoot: string;
     filePath: string;
     templatePath: string;
-    templateTier: PjmTemplateTier;
+    templateTier: TemplateTier;
     index: RegenerateBacklogIndexResult;
 }
 export interface CreateBacklogItemDependencies {

package/dist/commands/backlog/new.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/new.ts"],"names":[],"mappings":"AAQA,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EACL,sBAAsB,EACtB,KAAK,4BAA4B,EAClC,MAAM,oBAAoB,CAAC;AAS5B,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,eAAe,CAAC;IAC9B,KAAK,EAAE,4BAA4B,CAAC;CACrC;AAED,MAAM,WAAW,6BAA6B;IAC5C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CACvD;AAgKD,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,SAAS,GAAE,OAAO,CAAC,6BAA6B,CAAM,GACrD,OAAO,CAAC,uBAAuB,CAAC,CAwDlC"}
+{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/new.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EACL,sBAAsB,EACtB,KAAK,4BAA4B,EAClC,MAAM,oBAAoB,CAAC;AAS5B,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,YAAY,CAAC;IAC3B,KAAK,EAAE,4BAA4B,CAAC;CACrC;AAED,MAAM,WAAW,6BAA6B;IAC5C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CACvD;AAgKD,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,SAAS,GAAE,OAAO,CAAC,6BAA6B,CAAM,GACrD,OAAO,CAAC,uBAAuB,CAAC,CAwDlC"}

package/dist/commands/backlog/new.js

@@ -1,8 +1,8 @@
 import { access, readFile, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parseAssociatedIssues, serializeAssociatedIssues, } from '../pjm/remote/association.js';
-import { resolvePjmTemplate, } from '../pjm/template-source.js';
 import { stripTemplateFrontmatter } from '../shared/strip-template-frontmatter.js';
+import { resolveTemplate, } from '../shared/template-source.js';
 import YAML from 'yaml';
 import { initializeBacklog } from './init.js';
 import { regenerateBacklogIndex, } from './regenerate-index.js';
@@ -106,7 +106,7 @@ export async function createBacklogItem(options, overrides = {}) {
     if ((await pathExists(filePath)) || (await pathExists(archivedPath))) {
         throw new Error(`Backlog item ${id} already exists. Use a more specific title to disambiguate.`);
     }
-    const template = await resolvePjmTemplate({
+    const template = await resolveTemplate({
         name: 'backlog-item.md',
         assetsRoot: options.assetsRoot,
         templatesRoot: options.templatesRoot,

package/dist/commands/decision/new.d.ts

@@ -1,4 +1,4 @@
-import { type PjmTemplateTier } from '../pjm/template-source.js';
+import { type TemplateTier } from '../shared/template-source.js';
 export interface CreateDecisionRecordOptions {
     decisionsRoot: string;
     assetsRoot: string;
@@ -16,7 +16,7 @@ export interface CreateDecisionRecordResult {
     decisionsRoot: string;
     filePath: string;
     templatePath: string;
-    templateTier: PjmTemplateTier;
+    templateTier: TemplateTier;
 }
 export declare function createDecisionRecord(options: CreateDecisionRecordOptions): Promise<CreateDecisionRecordResult>;
 //# sourceMappingURL=new.d.ts.map

package/dist/commands/decision/new.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../../src/commands/decision/new.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,+BAA+B,CAAC;AAUvC,MAAM,WAAW,2BAA2B;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,eAAe,CAAC;CAC/B;AAkFD,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CAoDrC"}
+{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../../src/commands/decision/new.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,kCAAkC,CAAC;AAS1C,MAAM,WAAW,2BAA2B;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,YAAY,CAAC;CAC5B;AAkFD,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CAoDrC"}

package/dist/commands/decision/new.js

@@ -1,7 +1,7 @@
 import { access, mkdir, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { resolvePjmTemplate, } from '../pjm/template-source.js';
 import { stripTemplateFrontmatter } from '../shared/strip-template-frontmatter.js';
+import { resolveTemplate, } from '../shared/template-source.js';
 import YAML from 'yaml';
 import { assertDecisionIndexScaffold, regenerateDecisionIndex, } from './regenerate-index.js';
 import { generateDecisionId } from './shared/generate-id.js';
@@ -62,7 +62,7 @@ export async function createDecisionRecord(options) {
     if (await pathExists(filePath)) {
         throw new Error(`Decision record ${id} already exists. Use a more specific title to disambiguate.`);
     }
-    const template = await resolvePjmTemplate({
+    const template = await resolveTemplate({
         name: 'decision.md',
         assetsRoot: options.assetsRoot,
         templatesRoot: options.templatesRoot,

package/dist/commands/docs/nav/contents.d.ts

@@ -9,6 +9,15 @@ interface BuildDocsNavTreeOptions {
     dirRelativePath?: string;
     visitedDirectories?: Set<string>;
 }
+export declare function resolveEntryTarget(docsRoot: string, directoryPath: string, dirRelativePath: string, entry: DocsContentsEntry, 
+/**
+ * Page extensions a Contents link may target. MkDocs renders only `.md`;
+ * Fumadocs also renders `.mdx` pages.
+ */
+pageExtensions?: readonly string[]): Promise<{
+    kind: 'page' | 'section';
+    path: string;
+}>;
 export declare function buildDocsNavTree(options: BuildDocsNavTreeOptions): Promise<DocsNavTree>;
 export {};
 //# sourceMappingURL=contents.d.ts.map

package/dist/commands/docs/nav/contents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contents.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/contents.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAa,GACtB,iBAAiB,EAAE,CAqCrB;AAED,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;AAE/E,UAAU,uBAAuB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAClC;AAgFD,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CA8DtB"}
+{"version":3,"file":"contents.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/contents.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAa,GACtB,iBAAiB,EAAE,CAqCrB;AAED,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;AAE/E,UAAU,uBAAuB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAClC;AAMD,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EACvB,KAAK,EAAE,iBAAiB;AACxB;;;GAGG;AACH,cAAc,GAAE,SAAS,MAAM,EAAY,GAC1C,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAmErD;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,WAAW,CAAC,CA8DtB"}

package/dist/commands/docs/nav/contents.js

@@ -30,7 +30,12 @@ export function parseIndexContents(markdown, sourcePath = 'index.md') {
 function toPosixPath(path) {
     return path.replaceAll('\\', '/');
 }
-async function resolveEntryTarget(docsRoot, directoryPath, dirRelativePath, entry) {
+export async function resolveEntryTarget(docsRoot, directoryPath, dirRelativePath, entry, 
+/**
+ * Page extensions a Contents link may target. MkDocs renders only `.md`;
+ * Fumadocs also renders `.mdx` pages.
+ */
+pageExtensions = ['.md']) {
     const href = entry.href.split('#', 1)[0]?.trim() ?? '';
     if (!href) {
         throw new Error(`Invalid contents link "${entry.href}" in ${join(docsRoot, dirRelativePath, 'index.md')}`);
@@ -51,7 +56,7 @@ async function resolveEntryTarget(docsRoot, directoryPath, dirRelativePath, entr
     if (!(await fileExists(targetPath))) {
         throw new Error(`Contents link "${entry.href}" in ${join(docsRoot, dirRelativePath, 'index.md')} does not resolve to a Markdown file`);
     }
-    if (extname(targetPath) !== '.md') {
+    if (!pageExtensions.includes(extname(targetPath))) {
         throw new Error(`Contents link "${entry.href}" in ${join(docsRoot, dirRelativePath, 'index.md')} must point to a Markdown file or directory index`);
     }
     if (basename(targetPath) === 'index.md') {

package/dist/commands/docs/nav/fumadocs.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The `meta.json` keys nav sync owns. Every other key (`icon`, `defaultOpen`,
+ * `description`, ...) is left as the author wrote it.
+ */
+export interface FumadocsMeta {
+    title?: string;
+    pages: string[];
+}
+export interface FumadocsMetaFile {
+    /** Docs-relative POSIX path of the `meta.json` file. */
+    path: string;
+    meta: FumadocsMeta;
+    changed: boolean;
+}
+export interface SyncFumadocsNavigationResult {
+    metaFiles: FumadocsMetaFile[];
+    /** Docs-relative paths of the `meta.json` files this run wrote. */
+    written: string[];
+    /**
+     * Docs-relative paths of the `meta.json` files that were missing or differed
+     * by meaning before this run. Equal to `written` unless `check` was set.
+     */
+    stale: string[];
+    /**
+     * Docs-relative paths no Contents map places in the page tree. A folder is
+     * reported once as `folder/` instead of once per page inside it.
+     */
+    unlisted: string[];
+}
+/**
+ * Reduce a Markdown heading to the plain text a sidebar shows: images and
+ * links keep their text, code spans keep their content, and emphasis and
+ * strikethrough markers are dropped.
+ */
+export declare function stripInlineMarkdown(text: string): string;
+/** Folder title: frontmatter `title`, else the first H1 outside code fences. */
+export declare function resolveFolderTitle(markdown: string): string | undefined;
+/**
+ * Write one strict `meta.json` per docs directory that has an index.md,
+ * derived from that index's Contents map, and report every page the
+ * resulting page tree leaves out.
+ *
+ * Existing files are compared by meaning (parsed and deep-equal), so a run
+ * with no doc changes writes nothing even after a formatter rewrites them.
+ */
+export declare function syncFumadocsNavigation(options: {
+    docsRoot: string;
+    /** Compute and compare only; never write. */
+    check?: boolean;
+}): Promise<SyncFumadocsNavigationResult>;
+//# sourceMappingURL=fumadocs.d.ts.map

package/dist/commands/docs/nav/fumadocs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fumadocs.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/fumadocs.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAiDD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoCvE;AAoMD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAkExC"}