@open-agent-toolkit/cli 0.0.10 → 0.0.18

package/assets/skills/oat-project-complete/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-complete
-version: 1.3.3
+version: 1.3.5
 description: Use when all implementation work is finished and the project is ready to close. Marks the OAT project lifecycle as complete.
 disable-model-invocation: true
 user-invocable: true
@@ -300,35 +300,30 @@ The archive-side effects in this step are CLI-owned. Follow the canonical behavi
 
 ```bash
 ARCHIVED_ROOT=".oat/projects/archived"
-MAIN_WORKTREE_PATH=$(git worktree list --porcelain 2>/dev/null | awk '
-  /^worktree / { wt=$2 }
-  /^branch refs\\/heads\\/main$/ { print wt; exit }
-')
-MAIN_REPO_ARCHIVE=""
-if [[ -n "$MAIN_WORKTREE_PATH" ]]; then
-  MAIN_REPO_ARCHIVE="${MAIN_WORKTREE_PATH}/.oat/projects/archived"
-fi
+PRIMARY_REPO_ARCHIVE=""
 LOCAL_ARCHIVED_ROOT=".oat/projects/archived"
-USE_MAIN_REPO_ARCHIVE="false"
+USE_PRIMARY_REPO_ARCHIVE="false"
 
-# Heuristic: if this checkout is a worktree and the main repo archive parent exists,
-# use the main repo archive as the canonical archive destination.
+# Heuristic: if this checkout is a worktree and the primary repo archive parent
+# exists, use that durable archive path as the canonical archive destination.
 if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   GIT_COMMON_DIR=$(git rev-parse --git-common-dir 2>/dev/null || true)
   GIT_DIR=$(git rev-parse --git-dir 2>/dev/null || true)
   if [[ -n "$GIT_COMMON_DIR" && -n "$GIT_DIR" && "$GIT_COMMON_DIR" != "$GIT_DIR" ]]; then
-    if [[ -d "$(dirname "$MAIN_REPO_ARCHIVE")" ]]; then
-      USE_MAIN_REPO_ARCHIVE="true"
-      ARCHIVED_ROOT="$MAIN_REPO_ARCHIVE"
+    PRIMARY_REPO_ROOT=$(cd "$(dirname "$GIT_COMMON_DIR")" && pwd)
+    PRIMARY_REPO_ARCHIVE="${PRIMARY_REPO_ROOT}/.oat/projects/archived"
+    if [[ -d "$(dirname "$PRIMARY_REPO_ARCHIVE")" ]]; then
+      USE_PRIMARY_REPO_ARCHIVE="true"
+      ARCHIVED_ROOT="$PRIMARY_REPO_ARCHIVE"
     else
-      echo "Warning: Running in a worktree, but main repo archive path is unavailable: $MAIN_REPO_ARCHIVE"
+      echo "Warning: Running in a worktree, but the primary repo archive path is unavailable: $PRIMARY_REPO_ARCHIVE"
       echo "A worktree-local archive may be deleted when the worktree is removed and is not a durable archive."
       echo "Require explicit confirmation before proceeding with local-only archive."
     fi
   fi
 fi
 
-if [[ "$USE_MAIN_REPO_ARCHIVE" != "true" ]]; then
+if [[ "$USE_PRIMARY_REPO_ARCHIVE" != "true" ]]; then
   ARCHIVED_ROOT="$LOCAL_ARCHIVED_ROOT"
 fi
 
@@ -347,17 +342,17 @@ echo "Project archived to $ARCHIVE_PATH"
 **Canonical helper behaviors (required):**
 
 - Always archive locally first. The local archive is the authoritative completion artifact even when remote sync is also configured.
-- If `archive.summaryExportPath` is configured and `summary.md` exists after archive, copy it to `{repoRoot}/{archive.summaryExportPath}/{PROJECT_NAME}.md`.
+- If `archive.summaryExportPath` is configured and `summary.md` exists after archive, copy it to `{repoRoot}/{archive.summaryExportPath}/YYYYMMDD-{PROJECT_NAME}.md`.
 - If `archive.s3SyncOnComplete=true` and `archive.s3Uri` is configured, sync the archived project to `{archive.s3Uri}/{repo-slug}/{PROJECT_NAME}/`.
 - If AWS CLI is missing or unusable for that S3 sync, warn and continue. Completion must not fail after the local archive succeeds.
 - If `archive.s3SyncOnComplete` is false or `archive.s3Uri` is unset, skip remote sync without prompting.
 
 **Worktree durability guard (required):**
 
-- If running in a worktree and `MAIN_REPO_ARCHIVE` is unavailable, do not silently continue with a local-only archive.
-- Ask the user explicitly: "Main repo archive path is unavailable, so this archive may be lost when the worktree is deleted. Continue with local-only archive anyway?"
+- If running in a worktree and the primary repo archive path is unavailable, do not silently continue with a local-only archive.
+- Ask the user explicitly: "Primary repo archive path is unavailable, so this archive may be lost when the worktree is deleted. Continue with local-only archive anyway?"
 - If the user declines, skip archiving and continue the completion flow without archive.
-- If your repository does not use `main` as the default branch, use `git worktree list --porcelain` to identify the primary worktree path by another stable rule (for example the non-ephemeral root checkout), then append `/.oat/projects/archived`.
+- Resolve the durable repo root from `git rev-parse --git-common-dir` and `git rev-parse --git-dir`, matching the CLI helper in `packages/cli/src/commands/project/archive/archive-utils.ts`. Do not rely on a `main` checkout or default-branch naming.
 
 **Git handling after archive:**
 
@@ -376,18 +371,17 @@ If running from a git worktree, the primary repo archive directory is the canoni
 Reference path:
 
 ```bash
-MAIN_WORKTREE_PATH=$(git worktree list --porcelain | awk '
-  /^worktree / { wt=$2 }
-  /^branch refs\\/heads\\/main$/ { print wt; exit }
-')
-MAIN_REPO_ARCHIVE="${MAIN_WORKTREE_PATH}/.oat/projects/archived"
+GIT_COMMON_DIR=$(git rev-parse --git-common-dir)
+PRIMARY_REPO_ROOT=$(cd "$(dirname "$GIT_COMMON_DIR")" && pwd)
+PRIMARY_REPO_ARCHIVE="${PRIMARY_REPO_ROOT}/.oat/projects/archived"
 ```
 
 Guidance:
 
-- In a worktree, prefer moving directly to `MAIN_REPO_ARCHIVE` instead of archiving locally and copying later.
+- In a worktree, only prefer `PRIMARY_REPO_ARCHIVE` when the archive destination is local-only/gitignored in the current checkout. If `.oat/projects/archived/` is version controlled on the current branch, archive in the current checkout instead.
 - Do not treat the worktree-local archive as durable.
 - If forced to use a local-only archive, warn and require explicit user confirmation.
+- Always write the dated `archive.summaryExportPath` copy into the current checkout (`repoRoot`), even when the project archive itself is written to the primary checkout.
 - Do not hardcode user-specific absolute paths.
 
 ### Step 9: Regenerate Dashboard

package/assets/skills/oat-project-document/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-document
-version: 1.0.0
+version: 1.0.1
 description: Run when implementation is complete and documentation needs updating. Analyzes project artifacts to produce documentation update recommendations, then applies approved changes before project completion.
 argument-hint: '[project-path] [--auto]'
 disable-model-invocation: true
@@ -222,7 +222,7 @@ Scan the repository for all documentation and instruction surfaces.
 
 4. **Reference files:**
    - Check `.oat/repo/reference/` directory
-   - Read: `current-state.md`, `backlog.md`, `roadmap.md`, `decision-record.md` (whichever exist)
+   - Read: `current-state.md`, `backlog/index.md`, `backlog/completed.md`, `roadmap.md`, `decision-record.md`, and relevant `backlog/items/*.md` files as needed (whichever exist)
 
 **3b. Instruction surfaces (secondary — strong signals only):**
 

package/dist/app/create-program.js

@@ -1,7 +1,7 @@
 import { Command, Option } from 'commander';
 const PROGRAM_NAME = 'oat';
 const PROGRAM_DESCRIPTION = 'Open Agent Toolkit CLI for provider interoperability';
-const PROGRAM_VERSION = '0.0.7';
+const PROGRAM_VERSION = '0.0.18';
 const SCOPE_CHOICES = ['project', 'user', 'all'];
 export function createProgram() {
     return new Command()

package/dist/commands/docs/index-generate/index.d.ts

@@ -6,6 +6,7 @@ interface IndexGenerateFileDependencies {
     writeFile: (path: string, content: string, encoding: BufferEncoding) => Promise<void>;
     readOatConfig: (repoRoot: string) => Promise<import('../../../config/oat-config.js').OatConfig>;
     writeOatConfig: (repoRoot: string, config: import('../../../config/oat-config.js').OatConfig) => Promise<void>;
+    resolveRepoRoot: (cwd: string) => Promise<string>;
 }
 interface IndexGenerateDependencies {
     buildCommandContext: (options: GlobalOptions) => CommandContext;

package/dist/commands/docs/index-generate/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAS5C,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CACb,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,OAAO,oBAAoB,EAAE,SAAS,CAAC,CAAC;IACrD,cAAc,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,oBAAoB,EAAE,SAAS,KAC3C,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAsED,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsBT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAS5C,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CACb,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,OAAO,oBAAoB,EAAE,SAAS,CAAC,CAAC;IACrD,cAAc,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,oBAAoB,EAAE,SAAS,KAC3C,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACnD;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAwED,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsBT"}

package/dist/commands/docs/index-generate/index.js

@@ -3,6 +3,7 @@ import { join, relative } from 'node:path';
 import { buildCommandContext, } from '../../../app/command-context.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { readOatConfig, writeOatConfig } from '../../../config/oat-config.js';
+import { resolveProjectRoot } from '../../../fs/paths.js';
 import { Command, Option } from 'commander';
 import { generateIndex, renderIndex } from './generator.js';
 const DEFAULT_FILE_DEPS = {
@@ -11,6 +12,7 @@ const DEFAULT_FILE_DEPS = {
     writeFile,
     readOatConfig,
     writeOatConfig,
+    resolveRepoRoot: resolveProjectRoot,
 };
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
@@ -24,12 +26,13 @@ async function runIndexGenerate(context, options, deps) {
     const entries = await deps.generateIndex(docsDir);
     const content = deps.renderIndex(entries);
     await deps.writeFile(outputPath, content, 'utf8');
-    const config = await deps.readOatConfig(context.cwd);
+    const repoRoot = await deps.resolveRepoRoot(context.cwd);
+    const config = await deps.readOatConfig(repoRoot);
     config.documentation = {
         ...config.documentation,
-        index: relative(context.cwd, outputPath) || 'index.md',
+        index: relative(repoRoot, outputPath) || 'index.md',
     };
-    await deps.writeOatConfig(context.cwd, config);
+    await deps.writeOatConfig(repoRoot, config);
     if (context.json) {
         context.logger.json({
             status: 'ok',

package/dist/commands/docs/init/index.d.ts

@@ -1,6 +1,7 @@
 import { type CommandContext, type GlobalOptions } from '../../../app/command-context.js';
 import { type UpsertSectionResult } from '../../shared/agents-md.js';
 import { type PromptContext, type SelectChoice } from '../../shared/shared.prompts.js';
+import { type OatConfig } from '../../../config/oat-config.js';
 import { Command } from 'commander';
 import { type DocsInitResolvedOptions } from './resolve-options.js';
 interface DocsInitDependencies {
@@ -11,6 +12,8 @@ interface DocsInitDependencies {
     selectWithAbort: <T extends string>(message: string, choices: SelectChoice<T>[], ctx: PromptContext) => Promise<T | null>;
     runDocsInit: (context: CommandContext, options: DocsInitResolvedOptions, assetsRoot: string) => Promise<void>;
     upsertAgentsMdSection: (repoRoot: string, key: string, body: string) => Promise<UpsertSectionResult>;
+    readOatConfig: (repoRoot: string) => Promise<OatConfig>;
+    confirmAction: (message: string, ctx: PromptContext) => Promise<boolean>;
 }
 export declare function buildDocsSectionBody(options: DocsInitResolvedOptions): string;
 export declare function createDocsInitCommand(overrides?: Partial<DocsInitDependencies>): Command;

package/dist/commands/docs/init/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,iCAAiC,CAAC;AAIzC,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAE5C,OAAO,EAIL,KAAK,uBAAuB,EAI7B,MAAM,mBAAmB,CAAC;AAa3B,UAAU,oBAAoB;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,gBAAgB,CAAC,CAAC;IAC9E,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,SAAS,MAAM,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,EAC1B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,WAAW,EAAE,CACX,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,uBAAuB,EAChC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,qBAAqB,EAAE,CACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACnC;AA+CD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAc7E;AAyDD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CAgCT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAE5C,OAAO,EAIL,KAAK,uBAAuB,EAK7B,MAAM,mBAAmB,CAAC;AAa3B,UAAU,oBAAoB;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,gBAAgB,CAAC,CAAC;IAC9E,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,SAAS,MAAM,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,EAC1B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,WAAW,EAAE,CACX,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,uBAAuB,EAChC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,qBAAqB,EAAE,CACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClC,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AAiDD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAc7E;AA8GD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CAsCT"}

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

@@ -1,11 +1,11 @@
 import { buildCommandContext, } from '../../../app/command-context.js';
 import { upsertAgentsMdSection, } from '../../shared/agents-md.js';
-import { inputWithDefault, selectWithAbort, } from '../../shared/shared.prompts.js';
+import { confirmAction, inputWithDefault, selectWithAbort, } from '../../shared/shared.prompts.js';
 import { readGlobalOptions } from '../../shared/shared.utils.js';
-import { readOatConfig, writeOatConfig } from '../../../config/oat-config.js';
+import { readOatConfig, writeOatConfig, } from '../../../config/oat-config.js';
 import { resolveAssetsRoot } from '../../../fs/assets.js';
 import { Command, Option } from 'commander';
-import { DEFAULT_DOCS_REPO_SHAPE_DEPENDENCIES, detectDocsRepoShape, resolveDocsInitOptions, } from './resolve-options.js';
+import { DEFAULT_DOCS_REPO_SHAPE_DEPENDENCIES, detectDocsRepoShape, getDefaultDocsAppName, resolveDocsInitOptions, } from './resolve-options.js';
 import { scaffoldDocsApp } from './scaffold.js';
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
@@ -41,6 +41,8 @@ const DEFAULT_DEPENDENCIES = {
         context.logger.info(`  Format: ${options.format}`);
     },
     upsertAgentsMdSection,
+    readOatConfig,
+    confirmAction,
 };
 const FRAMEWORK_LABELS = {
     fumadocs: 'Fumadocs (Next.js + MDX)',
@@ -83,6 +85,32 @@ async function runDocsInitCommand(context, options, dependencies) {
             process.exitCode = 0;
             return;
         }
+        const existingConfig = await dependencies.readOatConfig(context.cwd);
+        if (existingConfig.documentation?.root) {
+            const configDesc = `root: ${existingConfig.documentation.root}, tooling: ${existingConfig.documentation.tooling ?? 'unknown'}`;
+            if (context.json) {
+                // JSON mode: include warning in output, proceed only with --yes
+                if (!options.yes) {
+                    context.logger.json({
+                        status: 'error',
+                        message: `Existing docs config found (${configDesc}). Use --yes to replace.`,
+                    });
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+            else {
+                context.logger.warn(`Existing docs config detected (${configDesc}). This will replace the current setup.`);
+                if (!options.yes) {
+                    const proceed = await dependencies.confirmAction('Replace existing docs setup?', { interactive: context.interactive });
+                    if (!proceed) {
+                        context.logger.info('Docs init cancelled.');
+                        process.exitCode = 1;
+                        return;
+                    }
+                }
+            }
+        }
         const assetsRoot = await dependencies.resolveAssetsRoot();
         await dependencies.runDocsInit(context, resolved, assetsRoot);
         const sectionBody = buildDocsSectionBody(resolved);
@@ -90,6 +118,23 @@ async function runDocsInitCommand(context, options, dependencies) {
         if (!context.json && sectionResult.action !== 'no-change') {
             context.logger.info(`AGENTS.md docs section ${sectionResult.action}.`);
         }
+        if (!context.json) {
+            context.logger.info('');
+            context.logger.info('Next steps:');
+            if (resolved.repoShape === 'single-package') {
+                context.logger.info(`  cd ${resolved.targetDir} && pnpm install`);
+                context.logger.info('  pnpm build');
+            }
+            else {
+                context.logger.info('  pnpm install');
+                context.logger.info(`  pnpm --filter ${resolved.appName} build`);
+                const defaultName = getDefaultDocsAppName(context.cwd, resolved.repoShape);
+                if (resolved.appName !== defaultName) {
+                    context.logger.info('');
+                    context.logger.info(`Note: Your docs app is named "${resolved.appName}" — if you have root scripts or CI filters referencing "${defaultName}", update them to match.`);
+                }
+            }
+        }
         process.exitCode = 0;
     }
     catch (error) {
@@ -117,6 +162,10 @@ export function createDocsInitCommand(overrides = {}) {
         .addOption(new Option('--app-name <name>', 'Docs app name'))
         .addOption(new Option('--target-dir <path>', 'Target directory for the docs app'))
         .addOption(new Option('--description <text>', 'Site description'))
+        .addOption(new Option('--lint <mode>', 'Markdown lint mode').choices([
+        'none',
+        'markdownlint-cli2',
+    ]))
         .addOption(new Option('--format <mode>', 'Markdown format mode').choices([
         'oxfmt',
         'none',

package/dist/commands/docs/init/resolve-options.d.ts

@@ -1,7 +1,7 @@
 import type { PromptContext, SelectChoice } from '../../shared/shared.prompts.js';
 export type DocsRepoShape = 'monorepo' | 'single-package';
 export type DocsFramework = 'fumadocs' | 'mkdocs';
-export type DocsLintMode = 'none';
+export type DocsLintMode = 'none' | 'markdownlint-cli2';
 export type DocsFormatMode = 'oxfmt' | 'none';
 export interface DocsInitResolvedOptions {
     repoRoot: string;

package/dist/commands/docs/init/resolve-options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-options.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/resolve-options.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACb,MAAM,iCAAiC,CAAC;AAGzC,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAC1D,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,QAAQ,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC;AAClC,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9C,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;IACzB,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,iBAAiB,CAAC,EAAE,aAAa,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,SAAS,MAAM,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,EAC1B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACvE;AAgBD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,aAAa,GACvB,MAAM,CAMR;AAED,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,MAAM,GACd,MAAM,CAMR;AAoBD,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,yBAAyB,GACtC,OAAO,CAAC,aAAa,CAAC,CAqBxB;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,aAAa,GAAG,MAAM,CAE/D;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CA+EzC;AAED,eAAO,MAAM,oCAAoC,EAAE,yBAOlD,CAAC"}
+{"version":3,"file":"resolve-options.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/resolve-options.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACb,MAAM,iCAAiC,CAAC;AAGzC,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAC1D,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,QAAQ,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,mBAAmB,CAAC;AACxD,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9C,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;IACzB,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,iBAAiB,CAAC,EAAE,aAAa,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,SAAS,MAAM,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,EAC1B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACvE;AAiBD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,aAAa,GACvB,MAAM,CAMR;AAED,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,MAAM,GACd,MAAM,CAMR;AAoBD,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,yBAAyB,GACtC,OAAO,CAAC,aAAa,CAAC,CAqBxB;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,aAAa,GAAG,MAAM,CAE/D;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CA+EzC;AAED,eAAO,MAAM,oCAAoC,EAAE,yBAOlD,CAAC"}

package/dist/commands/docs/init/resolve-options.js

@@ -6,6 +6,7 @@ const FRAMEWORK_CHOICES = [
 ];
 const LINT_CHOICES = [
     { label: 'none', value: 'none' },
+    { label: 'markdownlint-cli2', value: 'markdownlint-cli2' },
 ];
 const FORMAT_CHOICES = [
     { label: 'oxfmt', value: 'oxfmt' },

package/dist/commands/docs/init/scaffold.d.ts

@@ -10,6 +10,7 @@ export interface ScaffoldDocsAppResult {
 }
 export interface OatDepContext {
     isOatRepo: boolean;
+    localPackages: Set<string>;
     oatPackageVersions: Record<string, string>;
 }
 export declare function detectIsOatRepo(repoRoot: string): Promise<boolean>;

package/dist/commands/docs/init/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/scaffold.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAGjE,OAAO,KAAK,EAGV,uBAAuB,EAExB,MAAM,mBAAmB,CAAC;AA+E3B,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAWD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE;AAsCD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAYxB;AAiID,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAoChC"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/scaffold.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAGjE,OAAO,KAAK,EAGV,uBAAuB,EAExB,MAAM,mBAAmB,CAAC;AA+E3B,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAWD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE;AAgDD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAaxB;AA4ID,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAoChC"}

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

@@ -71,7 +71,7 @@ const OAT_DEP_PACKAGES = [
     'docs-theme',
     'docs-transforms',
 ];
-const DEFAULT_OAT_PUBLISHED_VERSION = '0.0.8';
+const DEFAULT_OAT_PUBLISHED_VERSION = '0.0.18';
 const PUBLIC_PACKAGE_VERSIONS_FILE = 'public-package-versions.json';
 export async function detectIsOatRepo(repoRoot) {
     for (const pkg of OAT_DEP_PACKAGES) {
@@ -105,17 +105,27 @@ async function readBundledOatPackageVersions(assetsRoot) {
 function buildFallbackOatPackageVersions(version) {
     return Object.fromEntries(OAT_DEP_PACKAGES.map((name) => [name, version]));
 }
+async function detectLocalOatPackages(repoRoot) {
+    const found = new Set();
+    for (const pkg of OAT_DEP_PACKAGES) {
+        if (await fileExists(join(repoRoot, 'packages', pkg, 'package.json'))) {
+            found.add(pkg);
+        }
+    }
+    return found;
+}
 export async function resolveOatDepContext(repoRoot, assetsRoot) {
-    const isOatRepo = await detectIsOatRepo(repoRoot);
+    const localPackages = await detectLocalOatPackages(repoRoot);
+    const isOatRepo = localPackages.size === OAT_DEP_PACKAGES.length;
     if (isOatRepo) {
-        return { isOatRepo, oatPackageVersions: {} };
+        return { isOatRepo, localPackages, oatPackageVersions: {} };
     }
     const cliVersion = await readCliVersion(assetsRoot);
     const oatPackageVersions = {
         ...buildFallbackOatPackageVersions(cliVersion),
         ...(await readBundledOatPackageVersions(assetsRoot)),
     };
-    return { isOatRepo, oatPackageVersions };
+    return { isOatRepo, localPackages, oatPackageVersions };
 }
 function humanizeAppName(appName) {
     return appName
@@ -126,6 +136,9 @@ function humanizeAppName(appName) {
 }
 function buildDevDependencies(lint, format) {
     const entries = [];
+    if (lint === 'markdownlint-cli2') {
+        entries.push('    "markdownlint-cli2": "^0.13.0"');
+    }
     if (format === 'oxfmt') {
         entries.push('    "oxfmt": "^0.36.0"');
     }
@@ -133,6 +146,9 @@ function buildDevDependencies(lint, format) {
 }
 function buildFumaDevDependencies(lint, format) {
     const entries = [];
+    if (lint === 'markdownlint-cli2') {
+        entries.push('    "markdownlint-cli2": "^0.13.0"');
+    }
     if (format === 'oxfmt') {
         entries.push('    "oxfmt": "^0.36.0"');
     }
@@ -145,10 +161,10 @@ function buildGenerateIndexCmd(isOatRepo, targetDir) {
     if (isOatRepo) {
         return `pnpm -w run cli -- docs generate-index --docs-dir ${targetDir}/docs --output ${targetDir}/index.md`;
     }
-    return '(oat docs generate-index --docs-dir docs --output index.md || true)';
+    return 'oat docs generate-index --docs-dir docs --output index.md';
 }
 function oatDepVersion(depContext, packageName) {
-    if (depContext.isOatRepo) {
+    if (depContext.localPackages.has(packageName)) {
         return 'workspace:*';
     }
     return `^${depContext.oatPackageVersions[packageName] ?? DEFAULT_OAT_PUBLISHED_VERSION}`;
@@ -161,7 +177,9 @@ function renderTemplate(template, options, depContext) {
         '{{PACKAGE_NAME}}': options.appName,
         '{{SITE_NAME}}': siteName,
         '{{SITE_DESCRIPTION}}': options.siteDescription,
-        '{{DOCS_LINT_SCRIPT}}': "echo 'docs lint disabled'",
+        '{{DOCS_LINT_SCRIPT}}': options.lint === 'markdownlint-cli2'
+            ? "markdownlint-cli2 'docs/**/*.md'"
+            : "echo 'docs lint disabled'",
         '{{DOCS_FORMAT_SCRIPT}}': options.format === 'oxfmt'
             ? "oxfmt 'docs/**/*.md'"
             : "echo 'docs formatting disabled'",
@@ -185,7 +203,7 @@ function buildDocumentationConfig(framework, targetDir) {
         return {
             root: targetDir,
             tooling: 'fumadocs',
-            index: join(targetDir, 'index.md'),
+            index: join(targetDir, 'docs', 'index.md'),
         };
     }
     return {

package/dist/commands/internal/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/internal/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,wBAAgB,qBAAqB,IAAI,OAAO,CAI/C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/internal/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,wBAAgB,qBAAqB,IAAI,OAAO,CAK/C"}

package/dist/commands/internal/index.js

@@ -1,7 +1,9 @@
 import { Command } from 'commander';
 import { createValidateOatSkillsCommand } from './validate-oat-skills.js';
+import { createValidateSkillVersionBumpsCommand } from './validate-skill-version-bumps.js';
 export function createInternalCommand() {
     return new Command('internal')
         .description('Internal OAT maintenance commands')
-        .addCommand(createValidateOatSkillsCommand());
+        .addCommand(createValidateOatSkillsCommand())
+        .addCommand(createValidateSkillVersionBumpsCommand());
 }

package/dist/commands/internal/validate-oat-skills.d.ts

@@ -1,9 +1,9 @@
 import { type CommandContext, type GlobalOptions } from '../../app/command-context.js';
-import { type ValidateOatSkillsResult } from '../../validation/index.js';
+import { type ValidateOatSkillsOptions, type ValidateOatSkillsResult } from '../../validation/index.js';
 import { Command } from 'commander';
 interface ValidateOatSkillsDependencies {
     buildCommandContext: (options: GlobalOptions) => CommandContext;
-    validateOatSkills: (repoRoot: string) => Promise<ValidateOatSkillsResult>;
+    validateOatSkills: (repoRoot: string, options?: ValidateOatSkillsOptions) => Promise<ValidateOatSkillsResult>;
 }
 export declare function createValidateOatSkillsCommand(overrides?: Partial<ValidateOatSkillsDependencies>): Command;
 export {};

package/dist/commands/internal/validate-oat-skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-oat-skills.d.ts","sourceRoot":"","sources":["../../../src/commands/internal/validate-oat-skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,UAAU,6BAA6B;IACrC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,iBAAiB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC3E;AAiED,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,6BAA6B,CAAM,GACrD,OAAO,CAcT"}
+{"version":3,"file":"validate-oat-skills.d.ts","sourceRoot":"","sources":["../../../src/commands/internal/validate-oat-skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,UAAU,6BAA6B;IACrC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,iBAAiB,EAAE,CACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,wBAAwB,KAC/B,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACvC;AAkED,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,6BAA6B,CAAM,GACrD,OAAO,CAkBT"}

package/dist/commands/internal/validate-oat-skills.js

@@ -21,9 +21,9 @@ function reportFindings(context, result) {
     }
     context.logger.error('\nFix the issues above, then re-run: pnpm oat:validate-skills');
 }
-async function runValidateOatSkills(context, dependencies) {
+async function runValidateOatSkills(context, options, dependencies) {
     try {
-        const result = await dependencies.validateOatSkills(context.cwd);
+        const result = await dependencies.validateOatSkills(context.cwd, options);
         if (result.findings.length > 0) {
             reportFindings(context, result);
             process.exitCode = 1;
@@ -59,8 +59,9 @@ export function createValidateOatSkillsCommand(overrides = {}) {
     };
     return new Command('validate-oat-skills')
         .description('Validate required structure of oat-* workflow skills')
-        .action(async (_options, command) => {
+        .option('--base-ref <ref>', 'Also require changed canonical skills to bump version relative to this git ref')
+        .action(async (options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
-        await runValidateOatSkills(context, dependencies);
+        await runValidateOatSkills(context, options, dependencies);
     });
 }

package/dist/commands/internal/validate-skill-version-bumps.d.ts

@@ -0,0 +1,10 @@
+import { type CommandContext, type GlobalOptions } from '../../app/command-context.js';
+import { type ValidateChangedSkillVersionBumpsOptions, type ValidateChangedSkillVersionBumpsResult } from '../../validation/index.js';
+import { Command } from 'commander';
+interface ValidateSkillVersionBumpsDependencies {
+    buildCommandContext: (options: GlobalOptions) => CommandContext;
+    validateChangedSkillVersionBumps: (repoRoot: string, options: ValidateChangedSkillVersionBumpsOptions) => Promise<ValidateChangedSkillVersionBumpsResult>;
+}
+export declare function createValidateSkillVersionBumpsCommand(overrides?: Partial<ValidateSkillVersionBumpsDependencies>): Command;
+export {};
+//# sourceMappingURL=validate-skill-version-bumps.d.ts.map

package/dist/commands/internal/validate-skill-version-bumps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-skill-version-bumps.d.ts","sourceRoot":"","sources":["../../../src/commands/internal/validate-skill-version-bumps.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAEL,KAAK,uCAAuC,EAC5C,KAAK,sCAAsC,EAC5C,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,UAAU,qCAAqC;IAC7C,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,gCAAgC,EAAE,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,uCAAuC,KAC7C,OAAO,CAAC,sCAAsC,CAAC,CAAC;CACtD;AA8ED,wBAAgB,sCAAsC,CACpD,SAAS,GAAE,OAAO,CAAC,qCAAqC,CAAM,GAC7D,OAAO,CAyBT"}

package/dist/commands/internal/validate-skill-version-bumps.js

@@ -0,0 +1,74 @@
+import { buildCommandContext, } from '../../app/command-context.js';
+import { readGlobalOptions } from '../shared/shared.utils.js';
+import { validateChangedSkillVersionBumps as defaultValidateChangedSkillVersionBumps, } from '../../validation/index.js';
+import { Command } from 'commander';
+const DEFAULT_DEPENDENCIES = {
+    buildCommandContext,
+    validateChangedSkillVersionBumps: defaultValidateChangedSkillVersionBumps,
+};
+function reportFindings(context, baseRef, result) {
+    if (context.json) {
+        context.logger.json({
+            status: 'failed',
+            baseRef,
+            validatedSkillCount: result.validatedSkillCount,
+            findings: result.findings,
+        });
+        return;
+    }
+    context.logger.error('Canonical skill version validation failed:\n');
+    for (const finding of result.findings) {
+        context.logger.error(`- ${finding.file}: ${finding.message}`);
+    }
+    context.logger.error(`\nFix the issues above, then re-run: oat internal validate-skill-version-bumps --base-ref ${baseRef}`);
+}
+async function runValidateSkillVersionBumps(context, options, dependencies) {
+    try {
+        const result = await dependencies.validateChangedSkillVersionBumps(context.cwd, options);
+        if (result.findings.length > 0) {
+            reportFindings(context, options.baseRef, result);
+            process.exitCode = 1;
+            return;
+        }
+        if (context.json) {
+            context.logger.json({
+                status: 'ok',
+                baseRef: options.baseRef,
+                validatedSkillCount: result.validatedSkillCount,
+                findings: result.findings,
+            });
+        }
+        else {
+            if (result.validatedSkillCount === 0) {
+                context.logger.info(`OK: 0 canonical skills changed relative to ${options.baseRef} - nothing to validate`);
+            }
+            else {
+                context.logger.info(`OK: validated ${result.validatedSkillCount} changed canonical skill version bump checks against ${options.baseRef}`);
+            }
+        }
+        process.exitCode = 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (context.json) {
+            context.logger.json({ status: 'error', message });
+        }
+        else {
+            context.logger.error(message);
+        }
+        process.exitCode = 2;
+    }
+}
+export function createValidateSkillVersionBumpsCommand(overrides = {}) {
+    const dependencies = {
+        ...DEFAULT_DEPENDENCIES,
+        ...overrides,
+    };
+    return new Command('validate-skill-version-bumps')
+        .description('Validate that changed canonical skills bump version relative to a git base ref')
+        .requiredOption('--base-ref <ref>', 'Git ref used as the comparison base for changed canonical skills')
+        .action(async (options, command) => {
+        const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        await runValidateSkillVersionBumps(context, options, dependencies);
+    });
+}