@open-agent-toolkit/cli 0.3.26 → 0.3.27

package/dist/commands/docs/init/scaffold.js

@@ -2,10 +2,15 @@ import { readdir, readFile, writeFile } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, relative, resolve, } from 'node:path';
 import { dirExists, ensureDir, fileExists } from '../../../fs/io.js';
 import { OAT_VERSION } from '../../../shared/oat-version.js';
-import { buildDocsCommands } from './docs-commands.js';
+import { buildDocsCommands, shellQuote } from './docs-commands.js';
 import { applyMarkdownDocsPlan, planMarkdownDocs } from './markdown.js';
 import { getTemplateDir } from './resolve-options.js';
 const MKDOCS_TEMPLATE_FILES = [
+    { source: 'AGENTS.md', destination: 'AGENTS.md' },
+    ...['index.md', 'docs-toolchain.md'].map((name) => ({
+        source: join('docs', 'contributing', name),
+        destination: join('docs', 'contributing', name),
+    })),
     { source: '.gitignore', destination: '.gitignore' },
     { source: 'mkdocs.yml', destination: 'mkdocs.yml' },
     { source: 'package.json.template', destination: 'package.json' },
@@ -22,6 +27,15 @@ const MKDOCS_TEMPLATE_FILES = [
     },
 ];
 const FUMA_TEMPLATE_FILES = [
+    { source: 'AGENTS.md', destination: 'AGENTS.md' },
+    ...['index.md', 'docs-toolchain.md'].map((name) => ({
+        source: join('docs', 'contributing', name),
+        destination: join('docs', 'contributing', name),
+    })),
+    ...['llms.txt', 'llms-full.txt', 'llms/[...slug]'].map((route) => ({
+        source: join('app', route, 'route.ts'),
+        destination: join('app', route, 'route.ts'),
+    })),
     { source: '.gitignore', destination: '.gitignore' },
     { source: 'next.config.js', destination: 'next.config.js' },
     { source: 'postcss.config.mjs', destination: 'postcss.config.mjs' },
@@ -148,11 +162,6 @@ function buildFumaDevDependencies(lint, format) {
     }
     return `,\n${entries.join(',\n')}`;
 }
-function shellQuote(value) {
-    return /^[a-zA-Z0-9_./-]+$/.test(value)
-        ? value
-        : `'${value.replaceAll("'", "'\\''")}'`;
-}
 function jsonStringContent(value) {
     return JSON.stringify(value).slice(1, -1);
 }
@@ -224,9 +233,10 @@ async function buildPackageManagerField(options, appRoot, dependencies) {
     const version = normalizePnpmVersion(await dependencies.detectPnpmVersion());
     return `,\n  "packageManager": ${JSON.stringify(`pnpm@${version}`)}`;
 }
-function renderTemplate(template, options, depContext, packageManagerField, nodeRequirement) {
+function renderTemplate(template, options, depContext, packageManagerField, nodeRequirement, packageJson) {
     const repoName = basename(options.repoRoot);
     const commands = buildDocsCommands(options.repoShape, options.targetDir, options.appName);
+    const command = packageJson ? jsonStringContent : (value) => value;
     const replacements = {
         '// {{TURBOPACK_ROOT_IMPORTS}}\n': options.repoShape === 'nested-standalone'
             ? "import { dirname } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n"
@@ -260,8 +270,12 @@ function renderTemplate(template, options, depContext, packageManagerField, node
         '{{FUMA_DEV_DEPENDENCIES}}': buildFumaDevDependencies(options.lint, options.format),
         '{{REPO_NAME}}': repoName,
         '{{APP_DIR}}': options.targetDir,
-        '{{GENERATE_INDEX_CMD}}': jsonStringContent(buildGenerateIndexCmd(depContext.isOatRepo, options.targetDir)),
-        '{{NAV_SYNC_CHECK_CMD}}': jsonStringContent(buildNavSyncCheckCmd(depContext.isOatRepo, options.targetDir)),
+        '{{APP_CWD}}': shellQuote(options.targetDir),
+        '{{LINT_STATUS}}': options.lint === 'none' ? 'disabled' : 'enabled (markdownlint-cli2)',
+        '{{FORMAT_STATUS}}': options.format === 'none' ? 'disabled' : 'enabled (oxfmt)',
+        '{{NAV_SYNC_CMD}}': command(buildNavSyncCheckCmd(depContext.isOatRepo, options.targetDir).replace(/ --check$/, '')),
+        '{{GENERATE_INDEX_CMD}}': command(buildGenerateIndexCmd(depContext.isOatRepo, options.targetDir)),
+        '{{NAV_SYNC_CHECK_CMD}}': command(buildNavSyncCheckCmd(depContext.isOatRepo, options.targetDir)),
         '{{OAT_DOCS_CONFIG_DEP}}': oatDepVersion(depContext, 'docs-config'),
         '{{OAT_DOCS_THEME_DEP}}': oatDepVersion(depContext, 'docs-theme'),
         '{{OAT_DOCS_TRANSFORMS_DEP}}': oatDepVersion(depContext, 'docs-transforms'),
@@ -361,7 +375,7 @@ export async function scaffoldDocsApp(options, overrides = {}) {
         const source = join(templateRoot, templateFile.source);
         const destination = join(appRoot, templateFile.destination);
         const template = await readFile(source, 'utf8');
-        const rendered = renderTemplate(template, options, depContext, packageManagerField, nodeRequirement);
+        const rendered = renderTemplate(template, options, depContext, packageManagerField, nodeRequirement, templateFile.destination === 'package.json');
         await ensureDir(dirname(destination));
         await writeFile(destination, rendered, 'utf8');
         createdFiles.push(templateFile.destination);

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

@@ -1 +1 @@
-{"version":3,"file":"fumadocs.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/fumadocs.ts"],"names":[],"mappings":"AAoBA;;;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;AA6DD;;;;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;AA8BD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAkMD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAuExC"}
+{"version":3,"file":"fumadocs.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/nav/fumadocs.ts"],"names":[],"mappings":"AAoBA;;;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;AA6DD;;;;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;AAsCD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAqND;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GAAG,OAAO,CAAC,4BAA4B,CAAC,CA8ExC"}

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

@@ -104,7 +104,7 @@ export function resolveFolderTitle(markdown) {
  * slugs plugin with the scaffolded `baseUrl: '/'`: group folders are dropped,
  * segments are URI-encoded, and an `index` file maps to its folder.
  */
-function pageUrl(pagePath) {
+function pageUrl(pagePath, nonIndexUrls = new Set()) {
     const slugs = parentDir(pagePath)
         .split('/')
         .filter((segment) => segment.length > 0 && segment !== '.')
@@ -114,7 +114,12 @@ function pageUrl(pagePath) {
     if (name !== 'index') {
         slugs.push(encodeURI(name));
     }
-    return `/${slugs.join('/')}`;
+    const url = `/${slugs.join('/')}`;
+    // core16.10.2 defers index slugs and appends /index when a non-index
+    // page has already claimed the folder URL.
+    return name === 'index' && nonIndexUrls.has(url)
+        ? `${url.replace(/\/$/, '')}/index`
+        : url;
 }
 /** Whether the Fumadocs page-tree builder reads `item` as a directive, not a path. */
 function isFumadocsDirective(item) {
@@ -139,9 +144,11 @@ function hrefFragment(href) {
 /**
  * Build one folder's `pages` from its index.md Contents map.
  *
- * A page in this folder or an immediate subfolder is referenced by name. Any
- * other target becomes a Fumadocs link entry, so no page is claimed by two
- * folders. There is never a `"..."` rest entry: pages the Contents map does
+ * A page in this folder or an immediate subfolder is referenced by name.
+ * Local same-name page/folder collisions use a precise source-file item, as
+ * does `../contributing.md` from its own contributing/ map: pinned core16.10.2
+ * selects the folder first for an extensionless reference. Other non-local
+ * targets become link entries. There is never a `"..."` rest entry: pages the Contents map does
  * not list stay out of the tree and are reported instead.
  */
 /**
@@ -162,7 +169,7 @@ function hasImplicitIndex(relativeDir, existing) {
     const pagesIndex = existing?.pagesIndex;
     return pagesIndex === undefined || pagesIndex === 'index';
 }
-async function buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex, matcher) {
+async function buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex, matcher, inventory, nonIndexUrls) {
     const indexPath = join(docsRoot, relativeDir, 'index.md');
     const entries = parseIndexContents(markdown, indexPath);
     // A folder the loader gives no implicit index (the docs root, a `root: true`
@@ -177,7 +184,16 @@ async function buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex,
             continue;
         const targetDir = parentDir(target.path);
         let item;
-        if (target.kind === 'section' && targetDir === relativeDir) {
+        if (target.kind === 'page' &&
+            (targetDir === relativeDir ||
+                target.path.slice(0, -extname(target.path).length) === relativeDir) &&
+            inventory.directories.includes(target.path.slice(0, -extname(target.path).length))) {
+            // An extensionless reference selects the same-name folder first.
+            // Keep source identity only in local/owning placement. A nonlocal map
+            // needs an authored URL link: core16.10.2 globally dedups source refs.
+            item = toFumadocsPageItem(posix.relative(relativeDir, target.path));
+        }
+        else if (target.kind === 'section' && targetDir === relativeDir) {
             continue;
         }
         else if (target.kind === 'section' &&
@@ -188,7 +204,7 @@ async function buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex,
             item = toFumadocsPageItem(basename(target.path, extname(target.path)));
         }
         else {
-            item = `[${entry.title}](${pageUrl(target.path)}${hrefFragment(entry.href)})`;
+            item = `[${entry.title}](${pageUrl(target.path, nonIndexUrls)}${hrefFragment(entry.href)})`;
         }
         if (!pages.includes(item)) {
             if (entry.group !== currentGroup) {
@@ -228,6 +244,7 @@ function mergeMeta(existing, meta) {
     };
 }
 function collectUnlisted(inventory, metas, implicitIndexDirs) {
+    const pagePaths = new Set(inventory.pages);
     const reachableDirs = new Set();
     const reachablePages = new Set();
     const pagesByFlattenPath = new Map(inventory.pages.map((page) => [
@@ -257,7 +274,9 @@ function collectUnlisted(inventory, metas, implicitIndexDirs) {
                 visit(itemPath);
                 continue;
             }
-            const page = pagesByFlattenPath.get(itemPath);
+            const page = pagePaths.has(itemPath)
+                ? itemPath
+                : pagesByFlattenPath.get(itemPath);
             if (page) {
                 reachablePages.add(page);
             }
@@ -291,6 +310,9 @@ export async function syncFumadocsNavigation(options) {
     const { docsRoot } = options;
     const matcher = createExclusionMatcher(options.nonReaderPaths ?? []);
     const inventory = await inventoryDocs(docsRoot, matcher);
+    const nonIndexUrls = new Set(inventory.pages
+        .filter((page) => basename(page, extname(page)) !== 'index')
+        .map((page) => pageUrl(page)));
     const metas = new Map();
     const existingMetas = new Map();
     const implicitIndexDirs = new Set();
@@ -312,7 +334,7 @@ export async function syncFumadocsNavigation(options) {
         const title = resolveFolderTitle(markdown);
         metas.set(relativeDir, {
             ...(title === undefined ? {} : { title }),
-            pages: await buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex, matcher),
+            pages: await buildFolderPages(docsRoot, relativeDir, markdown, implicitIndex, matcher, inventory, nonIndexUrls),
         });
     }
     if (!metas.has('.')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.3.26",
+  "version": "0.3.27",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -35,7 +35,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.3.26"
+    "@open-agent-toolkit/control-plane": "0.3.27"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/assets/skills/oat-docs-bootstrap/assets/AGENTS.md.template

@@ -1,64 +0,0 @@
-<!-- Framework docs-app bridge only: Fumadocs/MkDocs. Never render this template into a plain Markdown content root; use managed root Documentation guidance and the contributing page there. -->
-# AGENTS — {{SITE_NAME}}
-
-This file tells agents how to work inside `{{APP_DIR}}`, the documentation app for `{{REPO_NAME}}`. It is not bootstrap documentation. If you're looking for how this app was scaffolded, see `docs/getting-started.md` or the root-level `AGENTS.md` section on documentation.
-
-## Purpose and scope
-
-`{{APP_DIR}}` is the documentation surface for `{{REPO_NAME}}`. Humans read the rendered site; agents read the Markdown source and the navigation structure. This file tells agents the conventions that keep both audiences served, and points at the tooling that enforces those conventions. Everything here is about ongoing work inside the docs app — adding, restructuring, auditing, and bulk-editing content.
-
-## When you need to add a new page
-
-1. Create the Markdown file under `docs/` at the directory that best matches the page's topic. Every content directory is an `index.md` map — find the right one before picking a path. **Prefer `.md`** for plain content pages; reach for `.mdx` only when the page actually needs embedded JSX (a custom component, an interactive widget, a specialized layout). Plain `.md` is the default because agents, linters, and grep rules all handle it more reliably than `.mdx`.
-2. Add frontmatter with at minimum `title:` and `description:`. The title drives nav display and page `<title>`; the description drives search previews, social cards, and sibling summaries. Empty descriptions hurt all three.
-3. Update the nearest `index.md`'s `## Contents` section to include a link to the new page. Use `.md`-suffixed relative links: `[Title](page.md)` for leaf pages, `[Section](subdir/index.md)` for subdirectories. The `@open-agent-toolkit/docs-transforms` remark-links plugin normalizes these for Fumadocs routing at build time (strips `.md`, collapses `dir/index.md` → `dir`), so the suffixed form renders correctly **and** lets agents follow links to the target file without path inference. The `## Contents` section is the machine-readable local map — anything not listed there is effectively invisible to the navigation tooling.
-4. If the new page introduces a new subdirectory, create an `index.md` in that subdirectory with its own `## Contents` section. Every Markdown-bearing content directory must have an `index.md`; asset-only directories are exempt. Preserve useful audience/scope context and honor configured excludes and existing local instructions.
-5. Regenerate the derived navigation artifacts for this framework. For Fumadocs, run `oat docs nav sync` (from the app directory, or with `--target-dir <app-dir>`) so the committed `docs/**/meta.json` sidebar files follow authored `## Contents`, and run the generated-index command (`{{GENERATE_INDEX_CMD}}`) so the app-root `index.md` manifest reflects the current Markdown file tree. Fumadocs nav sync is strict: a page no `## Contents` map lists stays out of the sidebar and is reported, so list the new page rather than editing `meta.json`. For MkDocs, run `oat docs nav sync` or the local equivalent so `mkdocs.yml` `nav:` reflects authored `## Contents`. Derived artifacts never replace the authored `## Contents`; keep authored maps current and compare generated output against them when checking freshness.
-
-## When you need to restructure navigation
-
-1. Make changes in the authored `## Contents` sections of each affected `index.md`. That is the authoritative local map.
-2. Do **not** hand-edit generated navigation artifacts. The Fumadocs app-root `index.md` manifest, Fumadocs `meta.json` files, `mkdocs.yml` `nav:` (for MkDocs), and any other derived nav file is rewritten by the local generation workflow.
-3. After editing `## Contents`, run `oat docs nav sync` and the framework's generation command to refresh derived artifacts.
-4. If you're moving pages between directories, update both source and destination `index.md` `## Contents` entries in the same commit so the site isn't broken mid-way through history.
-5. If you're reparenting an entire subtree, consider whether the moved directory's own `index.md` needs a revised "scope" paragraph.
-
-## When you need to audit or bulk-edit docs
-
-1. Use `oat-docs-analyze` to audit the docs surface against the `## Contents` contract and surface gaps, drift, and coverage opportunities. This is read-only; it produces a report artifact under `.oat/repo/analysis/`.
-2. Review the report with the user. The analyze output is a set of ordered recommendations — apply them selectively, not wholesale.
-3. Use `oat-docs-apply` to execute approved recommendations. Apply creates a branch, performs the approved changes, runs nav sync, and optionally opens a PR. It will not make unapproved changes or invent new conventions.
-4. Do not bypass analyze/apply for sweeping content changes. The branch-and-review discipline catches mistakes that would otherwise land silently and accumulate over time.
-
-## When you're unsure where content belongs
-
-1. Start at `docs/index.md` and read its `## Contents` section. That's the top-level map. Follow the link that best matches the topic.
-2. Repeat at each directory level — every `index.md` has its own `## Contents`. Descend until you find the right scope.
-3. If none of the existing sections fit, the content probably belongs in a new subdirectory. Create it with an `index.md` (see "When you need to add a new page").
-4. If in doubt, match existing siblings' style and depth rather than inventing a new pattern. Consistency across neighboring pages matters more than exact placement.
-
-## When you need project-level documentation updates
-
-1. Use the `oat-project-document` skill during OAT project workflows. It reads project artifacts (`discovery.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`) and proposes evidence-backed doc updates — no speculation, no content that doesn't trace back to the source artifacts.
-2. The skill generates recommendations; you approve them before they land. Treat it like analyze/apply but scoped to a single project's documentation delta.
-3. Do not hand-write project-derived docs that bypass this flow. Bypassing means future runs of the skill will re-surface the same content as "missing" because the provenance chain is broken.
-
-## What not to do
-
-- **Don't hand-edit generated files.** For Fumadocs, the root-level `index.md` generated by `{{GENERATE_INDEX_CMD}}` is rewritten on every build. For MkDocs, generated or synchronized navigation lives in `mkdocs.yml` `nav:`. Edits to derived artifacts are silently clobbered. Edit the authored source (`docs/index.md` and its `## Contents`), then regenerate.
-- **Don't default to `.mdx` when `.md` would do.** MDX adds JSX-in-Markdown capability (embedded components), which breaks simple link rewrites, confuses agent tooling, and requires imports that plain `.md` doesn't. Reach for `.mdx` only when a page actually needs a component it can't express in plain Markdown.
-- **Don't author `## Contents` links without `.md` extensions.** Extension-less links (`[Title](page)` instead of `[Title](page.md)`) force agents to infer the target file type, break simple grep-based navigation, and diverge from the convention used throughout `{{REPO_NAME}}`. The build pipeline (`@open-agent-toolkit/docs-transforms` remark-links) strips `.md` for Fumadocs routing — so suffixed authored links render correctly and stay agent-friendly.
-- **Don't invent new navigation conventions outside `## Contents`.** A sidebar config in a framework file, a hand-rolled TOC, a separate nav YAML — all of these diverge from the contract and break the tooling. Extend via `## Contents`.
-- **Don't bypass `oat-docs-apply` for bulk content changes.** The analyze/apply flow exists to catch mistakes. Bulk edits done by hand or by a one-off script skip the safety net and often regress something unexpected.
-- **Don't create `overview.md` files.** They're deprecated in favor of `index.md` with a `## Contents` section.
-- **Don't edit the scaffolded `{{SITE_NAME}}` value in isolation.** The site name flows to multiple files (layout branding, metadata, page headings). If you're renaming the docs site, update all locations in the same commit or you'll get inconsistent chrome.
-
-## Reference
-
-- `docs/getting-started.md` — first-run setup instructions for contributors joining this docs app.
-- `docs/contributing.md` — authoring conventions (frontmatter requirements, Markdown features like GFM alerts / mermaid / code blocks, nav contract summary).
-- Root `AGENTS.md` `## Documentation` section in `{{REPO_NAME}}` — repo-wide pointer telling any agent "docs live at `{{APP_DIR}}`."
-- `oat-docs-analyze` — read-only audit command.
-- `oat-docs-apply` — apply approved audit recommendations.
-- `oat-project-document` skill — propose evidence-backed doc updates from project artifacts.
-- `{{GENERATE_INDEX_CMD}}` — for Fumadocs, regenerates the machine-readable root `index.md` from `docs/`. Runs automatically on `predev` / `prebuild`; don't hand-edit its output.