@open-agent-toolkit/cli 0.2.15 → 0.2.17

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -85,7 +85,7 @@ For full project-management repo-reference setup, use [`oat pjm init`](tool-pack
 
 Use the `oat decision` group for file-per-record decisions under `.oat/repo/reference/decisions/`. Each decision is its own file with a deterministic `DR-YYMMDD-slug` ID (the slug is capped at 30 characters at the last whole-word boundary, with trailing stop-words trimmed), and the human-facing index is a committed generated view.
 
-- `oat decision init` - scaffold `.oat/repo/reference/decisions/` and the managed decision index
+- `oat decision init` - scaffold `.oat/repo/reference/decisions/`, the managed decision index, decision-scoped `AGENTS.md` guidance, and an idempotent `OAT decisions` section in the repository-root `AGENTS.md`
 - `oat decision new <title>` - create a new decision record; supports `--status`, `--context`, `--decision`, `--consequences`, and `--created-at`
 - `oat decision regenerate-index` - rebuild the managed decision index table from record frontmatter
 - `oat decision migrate` - convert a legacy single `decision-record.md` into file-per-record decisions, preserving each old `ADR-NNN`/`DR-NNN` ID as `legacy_id`; applies by default, so pass `--dry-run` to preview the legacy-to-new mappings without writing, and `--delete-legacy` to remove the source file after a verified migration (unlike `oat pjm migrate`, which defaults to dry-run)
@@ -94,6 +94,8 @@ Pass `--context`, `--decision`, and `--consequences` together when creating a re
 
 The decision index uses managed marker pairs and is deterministic, so an index merge conflict can be resolved by re-running `oat decision regenerate-index` and staging the result. Decision records replace the legacy single `decision-record.md`; repos still on the old layout migrate with `oat decision migrate` (or the broader `oat pjm migrate`).
 
+`oat decision init` is the lightweight standalone setup path. It does not require the `project-management` tool pack and does not create current state, roadmap, or backlog artifacts. Its AGENTS guidance uses `oat decision` directly while also recognizing `oat-pjm-decision` when that optional skill is installed later.
+
 ## `oat local ...`
 
 `oat local` manages local-only, gitignored paths that still need to follow you between the main repo and worktrees.

package/assets/docs/cli-utilities/tool-packs.md

@@ -140,6 +140,8 @@ The canonical surface splits active operational state (under `pjm/`) from durabl
 
 Decisions are now file-per-record under `reference/decisions/` (created and indexed with the [`oat decision`](config-and-local-state.md#oat-decision-) command group), replacing the legacy single `decision-record.md`. Repos still on the old `reference/` layout can migrate with `oat pjm migrate`.
 
+For decision records without the broader PJM surface, run `oat decision init` directly. It creates only the decision directory, generated index, and decision-specific AGENTS guidance; it does not require the `project-management` pack or create current state, roadmap, and backlog artifacts. If the pack is installed later, its root guidance is maintained as a separate managed section so the decision instructions remain independently reusable.
+
 `oat pjm init` is idempotent and non-destructive. Existing reference docs are skipped and left unchanged, so curated repo state is not overwritten on repeated runs.
 
 Run `oat pjm doctor` to check an existing surface after the `project-management` pack is enabled: it reports missing canonical files, leftover template frontmatter, and legacy/loose/second-roadmap drift, and accepts `--json` for machine-readable output. When the pack is disabled or not configured, doctor reports PJM as disabled and skips drift checks. The same gated checks also run under project-scope `oat doctor`.

package/assets/docs/reference/oat-directory-structure.md

@@ -246,12 +246,16 @@ operational layer (`pjm/`) from durable references (`reference/`):
   reference/
     AGENTS.md
     decisions/
+      AGENTS.md
+      index.md
 ```
 
 Decisions are file-per-record under `reference/decisions/` (managed with the
 `oat decision` command group), replacing the legacy single
 `reference/decision-record.md`. Repos still on the old single-`reference/`
-layout migrate with `oat pjm migrate`.
+layout migrate with `oat pjm migrate`. Running `oat decision init` by itself
+creates the `decisions/` subtree and decision-specific AGENTS guidance without
+creating the broader `pjm/` surface.
 
 ## User scope (`~/.oat/`)
 

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.15",
-  "docs-config": "0.2.15",
-  "docs-theme": "0.2.15",
-  "docs-transforms": "0.2.15"
+  "cli": "0.2.17",
+  "docs-config": "0.2.17",
+  "docs-theme": "0.2.17",
+  "docs-transforms": "0.2.17"
 }

package/dist/app/global-cli-installer.d.ts

@@ -5,12 +5,13 @@ export interface GlobalCliInstallerOptions {
     platform: NodeJS.Platform;
     nodeExecutable: string;
     fileExists: (path: string) => boolean;
+    readFile?: (path: string) => string;
 }
 export interface GlobalCliInstallerInvocation {
     file: string;
     args: string[];
 }
 export declare function detectGlobalCliPackageManager(argv: string[], env: NodeJS.ProcessEnv): GlobalCliPackageManager;
-export declare function formatGlobalCliInstallCommand(packageSpec: string, argv: string[], env: NodeJS.ProcessEnv): string;
+export declare function formatGlobalCliInstallCommand(packageSpec: string, argv: string[], env: NodeJS.ProcessEnv, fileExists?: (path: string) => boolean, readFile?: (path: string) => string): string;
 export declare function resolveGlobalCliInstallerInvocation(packageSpec: string, options: GlobalCliInstallerOptions): GlobalCliInstallerInvocation | null;
 //# sourceMappingURL=global-cli-installer.d.ts.map

package/dist/app/global-cli-installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"global-cli-installer.d.ts","sourceRoot":"","sources":["../../src/app/global-cli-installer.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,uBAAuB,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAEtE,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACvC;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAqCD,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,uBAAuB,CAyBzB;AA0ED,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,MAAM,CAYR;AAED,wBAAgB,mCAAmC,CACjD,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,yBAAyB,GACjC,4BAA4B,GAAG,IAAI,CAUrC"}
+{"version":3,"file":"global-cli-installer.d.ts","sourceRoot":"","sources":["../../src/app/global-cli-installer.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,uBAAuB,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAEtE,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAqCD,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,uBAAuB,CAyBzB;AA6JD,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,UAAU,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAqB,EACnD,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAClC,MAAM,CAmBR;AAQD,wBAAgB,mCAAmC,CACjD,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,yBAAyB,GACjC,4BAA4B,GAAG,IAAI,CAmBrC"}

package/dist/app/global-cli-installer.js

@@ -1,4 +1,5 @@
-import { win32 } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { join, win32 } from 'node:path';
 function normalizePathForDetection(path) {
     return path.replaceAll('\\', '/').toLowerCase().replace(/\/+$/, '');
 }
@@ -39,12 +40,56 @@ export function detectGlobalCliPackageManager(argv, env) {
     }
     return 'npm';
 }
-function installArgsForManager(manager, packageSpec) {
+function readPnpmStoreDir(argv, env, fileExists, readFile) {
+    const modulesYamlPath = resolvePnpmGlobalModulesYamlPath(argv, env, fileExists);
+    if (!modulesYamlPath) {
+        return null;
+    }
+    try {
+        const match = readFile(modulesYamlPath).match(/^storeDir:\s*(.+)$/m);
+        return match?.[1]?.trim() ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolvePnpmGlobalModulesYamlPath(argv, env, fileExists) {
+    for (const arg of argv.slice(0, 3)) {
+        const normalized = arg.replaceAll('\\', '/');
+        const match = normalized.match(/^(.*\/global\/\d+)\//);
+        if (match?.[1]) {
+            const candidate = `${match[1]}/node_modules/.modules.yaml`;
+            if (fileExists(candidate)) {
+                return candidate;
+            }
+        }
+    }
+    const pnpmHome = env.PNPM_HOME?.trim();
+    if (pnpmHome) {
+        const candidate = join(pnpmHome, 'global', '5', 'node_modules', '.modules.yaml');
+        if (fileExists(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function resolvePnpmInstallContext(argv, env, fileExists, readFile) {
+    const read = readFile ?? ((path) => readFileSync(path, 'utf8'));
+    return {
+        storeDir: readPnpmStoreDir(argv, env, fileExists, read),
+    };
+}
+function installArgsForManager(manager, packageSpec, pnpmStoreDir) {
     switch (manager) {
         case 'npm':
             return ['install', '--global', packageSpec];
-        case 'pnpm':
-            return ['add', '-g', packageSpec];
+        case 'pnpm': {
+            const args = ['add', '-g', packageSpec];
+            if (pnpmStoreDir) {
+                args.push('--store-dir', pnpmStoreDir);
+            }
+            return args;
+        }
         case 'yarn':
             return ['global', 'add', packageSpec];
         case 'bun':
@@ -58,6 +103,9 @@ function resolveWindowsManagerInvocation(manager, packageSpec, options) {
     if (manager === 'npm') {
         return resolveNpmWindowsInvocation(packageSpec, options);
     }
+    const pnpmStoreDir = manager === 'pnpm'
+        ? resolvePnpmInstallContext(options.argv, options.env, options.fileExists, options.readFile).storeDir
+        : null;
     const comspec = options.env.ComSpec?.trim() || 'cmd.exe';
     return {
         file: comspec,
@@ -66,7 +114,7 @@ function resolveWindowsManagerInvocation(manager, packageSpec, options) {
             '/s',
             '/c',
             manager,
-            ...installArgsForManager(manager, packageSpec),
+            ...installArgsForManager(manager, packageSpec, pnpmStoreDir),
         ],
     };
 }
@@ -86,26 +134,38 @@ function resolveNpmWindowsInvocation(packageSpec, options) {
         args: [npmCliPath, ...npmArgs],
     };
 }
-export function formatGlobalCliInstallCommand(packageSpec, argv, env) {
+export function formatGlobalCliInstallCommand(packageSpec, argv, env, fileExists = () => false, readFile) {
     const manager = detectGlobalCliPackageManager(argv, env);
+    const pnpmStoreDir = manager === 'pnpm'
+        ? resolvePnpmInstallContext(argv, env, fileExists, readFile).storeDir
+        : null;
+    const pnpmStoreFlag = pnpmStoreDir === null ? '' : ` --store-dir ${quoteShellWord(pnpmStoreDir)}`;
     switch (manager) {
         case 'npm':
             return `npm install --global ${packageSpec}`;
         case 'pnpm':
-            return `pnpm add -g ${packageSpec}`;
+            return `pnpm add -g ${packageSpec}${pnpmStoreFlag}`;
         case 'yarn':
             return `yarn global add ${packageSpec}`;
         case 'bun':
             return `bun install -g ${packageSpec}`;
     }
 }
+function quoteShellWord(value) {
+    return /[\s"'`$\\]/.test(value)
+        ? `'${value.replaceAll("'", `'"'"'`)}'`
+        : value;
+}
 export function resolveGlobalCliInstallerInvocation(packageSpec, options) {
     const manager = detectGlobalCliPackageManager(options.argv, options.env);
+    const pnpmStoreDir = manager === 'pnpm'
+        ? resolvePnpmInstallContext(options.argv, options.env, options.fileExists, options.readFile).storeDir
+        : null;
     if (options.platform === 'win32') {
         return resolveWindowsManagerInvocation(manager, packageSpec, options);
     }
     return {
         file: executableForManager(manager),
-        args: installArgsForManager(manager, packageSpec),
+        args: installArgsForManager(manager, packageSpec, pnpmStoreDir),
     };
 }

package/dist/app/tool-bundle-update-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-bundle-update-guard.d.ts","sourceRoot":"","sources":["../../src/app/tool-bundle-update-guard.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAI/D,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,aAAa,GAAG,YAAY,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,4BAA6B,SAAQ,qBAAqB;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,mBAAmB,CAAC;CACnC;AAED,UAAU,gBAAgB;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,MAAM,WAAW,iCAAiC;IAChD,yBAAyB,EAAE,CACzB,OAAO,EAAE,qBAAqB,KAC3B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QAAE,WAAW,EAAE,OAAO,CAAA;KAAE,KAC9B,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,UAAU,EAAE,CACV,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACvC;AA6CD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAE1D;AAgBD,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EAAE,EACd,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,mBAAmB,CAOrB;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAMtE;AAED,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,4BAA4B,EACrC,SAAS,GAAE,OAAO,CAAC,iCAAiC,CAAM,GACzD,OAAO,CAAC,OAAO,CAAC,CA6ElB"}
+{"version":3,"file":"tool-bundle-update-guard.d.ts","sourceRoot":"","sources":["../../src/app/tool-bundle-update-guard.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAI/D,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,aAAa,GAAG,YAAY,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,4BAA6B,SAAQ,qBAAqB;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,mBAAmB,CAAC;CACnC;AAED,UAAU,gBAAgB;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,SAAS,CAAC;CAClB;AAED,MAAM,WAAW,iCAAiC;IAChD,yBAAyB,EAAE,CACzB,OAAO,EAAE,qBAAqB,KAC3B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QAAE,WAAW,EAAE,OAAO,CAAA;KAAE,KAC9B,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,UAAU,EAAE,CACV,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACvC;AA6CD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAE1D;AAgBD,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EAAE,EACd,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,mBAAmB,CAOrB;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAMtE;AAED,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,4BAA4B,EACrC,SAAS,GAAE,OAAO,CAAC,iCAAiC,CAAM,GACzD,OAAO,CAAC,OAAO,CAAC,CA8ElB"}

package/dist/app/tool-bundle-update-guard.js

@@ -81,7 +81,7 @@ export async function guardBundledToolMutation(options, overrides = {}) {
         'can only install its own bundled tool versions. The available CLI may ' +
         'bundle newer tool versions.');
     const packageSpec = `${CLI_PACKAGE}@${availableVersion}`;
-    const installCommand = formatGlobalCliInstallCommand(packageSpec, options.argv, options.env);
+    const installCommand = formatGlobalCliInstallCommand(packageSpec, options.argv, options.env, dependencies.fileExists);
     let accepted = false;
     try {
         accepted = await dependencies.confirmAction(`Update the OAT CLI to ${availableVersion} before running ${options.commandPath}?`, { interactive: options.interactive });
@@ -114,7 +114,7 @@ export async function guardBundledToolMutation(options, overrides = {}) {
     }
     catch {
         throw new CliError(`Failed to update the OAT CLI to ${availableVersion}. ` +
-            `No tools were changed. Fix the npm installation issue and run: ${installCommand}`, 2);
+            `No tools were changed. Fix the package manager installation issue and run: ${installCommand}`, 2);
     }
     options.logger.info(`Updated the OAT CLI to ${availableVersion}. To let the new CLI install ` +
         `its bundled tools, rerun in ${options.rerunCommand.shell}:\n${options.rerunCommand.command}`);

package/dist/commands/decision/agents-guidance.d.ts

@@ -0,0 +1,15 @@
+import { type UpsertSectionResult } from '../shared/agents-md.js';
+export declare const DECISION_AGENTS_SECTION_KEY = "decisions";
+export declare function buildDecisionAgentsSectionBody(decisionsPath?: string): string;
+export declare function buildScopedDecisionAgentsSectionBody(): string;
+export interface InitializeDecisionAgentsGuidanceOptions {
+    projectRoot: string;
+    decisionsRoot: string;
+}
+export interface DecisionAgentsGuidanceResult {
+    root: UpsertSectionResult['action'];
+    scoped: UpsertSectionResult['action'];
+}
+export declare function initializeScopedDecisionAgentsGuidance(decisionsRoot: string): Promise<UpsertSectionResult>;
+export declare function initializeDecisionAgentsGuidance(options: InitializeDecisionAgentsGuidanceOptions): Promise<DecisionAgentsGuidanceResult>;
+//# sourceMappingURL=agents-guidance.d.ts.map

package/dist/commands/decision/agents-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-guidance.d.ts","sourceRoot":"","sources":["../../../src/commands/decision/agents-guidance.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,4BAA4B,CAAC;AAEpC,eAAO,MAAM,2BAA2B,cAAc,CAAC;AAwBvD,wBAAgB,8BAA8B,CAC5C,aAAa,SAAyB,GACrC,MAAM,CAUR;AAED,wBAAgB,oCAAoC,IAAI,MAAM,CAU7D;AAED,MAAM,WAAW,uCAAuC;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;CACvC;AAED,wBAAsB,sCAAsC,CAC1D,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,CAAC,CAO9B;AAED,wBAAsB,gCAAgC,CACpD,OAAO,EAAE,uCAAuC,GAC/C,OAAO,CAAC,4BAA4B,CAAC,CAgBvC"}

package/dist/commands/decision/agents-guidance.js

@@ -0,0 +1,51 @@
+import { mkdir } from 'node:fs/promises';
+import { isAbsolute, relative, sep } from 'node:path';
+import { upsertAgentsMdSection, } from '../shared/agents-md.js';
+export const DECISION_AGENTS_SECTION_KEY = 'decisions';
+const DEFAULT_DECISIONS_PATH = '.oat/repo/reference/decisions';
+function portablePath(path) {
+    return path.split(sep).join('/');
+}
+function displayDecisionsPath(projectRoot, decisionsRoot) {
+    const relativePath = relative(projectRoot, decisionsRoot);
+    if (relativePath.length > 0 &&
+        !relativePath.startsWith('..') &&
+        !isAbsolute(relativePath)) {
+        return portablePath(relativePath);
+    }
+    return portablePath(decisionsRoot);
+}
+export function buildDecisionAgentsSectionBody(decisionsPath = DEFAULT_DECISIONS_PATH) {
+    return [
+        '### Decision Records',
+        '',
+        `- Durable repository decisions live under \`${decisionsPath}/\`; read \`${decisionsPath}/AGENTS.md\` before working with them.`,
+        `- Before finalizing a durable repository decision, review \`${decisionsPath}/index.md\` and any relevant records.`,
+        '- When the user asks to record a durable decision or confirms a proposed capture, use `oat-pjm-decision` when that skill is installed; otherwise use `oat decision new`.',
+        '- Do not hand-edit the generated decision index; run `oat decision regenerate-index` after record changes or to resolve index conflicts.',
+        '- If the decision surface is missing, initialize it with `oat decision init`.',
+    ].join('\n');
+}
+export function buildScopedDecisionAgentsSectionBody() {
+    return [
+        '# Decision Record Guidance',
+        '',
+        '- This directory stores one Markdown file per durable repository decision plus a generated `index.md`.',
+        '- Review the index and relevant existing records before finalizing a decision.',
+        '- Create records with `oat decision new`; do not create IDs or filenames by hand.',
+        '- Keep context, the chosen decision, and consequences in the decision record.',
+        '- Do not hand-edit the generated table in `index.md`. Run `oat decision regenerate-index` after record changes or to resolve index conflicts.',
+    ].join('\n');
+}
+export async function initializeScopedDecisionAgentsGuidance(decisionsRoot) {
+    await mkdir(decisionsRoot, { recursive: true });
+    return upsertAgentsMdSection(decisionsRoot, DECISION_AGENTS_SECTION_KEY, buildScopedDecisionAgentsSectionBody());
+}
+export async function initializeDecisionAgentsGuidance(options) {
+    const scoped = await initializeScopedDecisionAgentsGuidance(options.decisionsRoot);
+    const root = await upsertAgentsMdSection(options.projectRoot, DECISION_AGENTS_SECTION_KEY, buildDecisionAgentsSectionBody(displayDecisionsPath(options.projectRoot, options.decisionsRoot)));
+    return {
+        root: root.action,
+        scoped: scoped.action,
+    };
+}

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

@@ -2,6 +2,7 @@ import { buildCommandContext } from '../../app/command-context.js';
 import { resolveAssetsRoot } from '../../fs/assets.js';
 import { resolveProjectRoot } from '../../fs/paths.js';
 import { Command } from 'commander';
+import { initializeDecisionAgentsGuidance } from './agents-guidance.js';
 import { initializeDecisionRecords } from './init.js';
 import { migrateDecisionRecords } from './migrate.js';
 import { createDecisionRecord } from './new.js';
@@ -10,6 +11,7 @@ interface DecisionCommandDependencies {
     buildCommandContext: typeof buildCommandContext;
     resolveProjectRoot: typeof resolveProjectRoot;
     resolveAssetsRoot: typeof resolveAssetsRoot;
+    initializeDecisionAgentsGuidance: typeof initializeDecisionAgentsGuidance;
     initializeDecisionRecords: typeof initializeDecisionRecords;
     regenerateDecisionIndex: typeof regenerateDecisionIndex;
     createDecisionRecord: typeof createDecisionRecord;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/decision/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,yBAAyB,EAAE,MAAM,QAAQ,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAyB7D,UAAU,2BAA2B;IACnC,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,yBAAyB,EAAE,OAAO,yBAAyB,CAAC;IAC5D,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,oBAAoB,EAAE,OAAO,oBAAoB,CAAC;IAClD,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CACvD;AA8CD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAmMT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/decision/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,gCAAgC,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,QAAQ,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAyB7D,UAAU,2BAA2B;IACnC,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,gCAAgC,EAAE,OAAO,gCAAgC,CAAC;IAC1E,yBAAyB,EAAE,OAAO,yBAAyB,CAAC;IAC5D,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,oBAAoB,EAAE,OAAO,oBAAoB,CAAC;IAClD,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CACvD;AA+CD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAoNT"}

package/dist/commands/decision/index.js

@@ -4,6 +4,7 @@ import { readGlobalOptions } from '../shared/shared.utils.js';
 import { resolveAssetsRoot } from '../../fs/assets.js';
 import { resolveProjectRoot } from '../../fs/paths.js';
 import { Command } from 'commander';
+import { initializeDecisionAgentsGuidance } from './agents-guidance.js';
 import { initializeDecisionRecords } from './init.js';
 import { migrateDecisionRecords } from './migrate.js';
 import { createDecisionRecord } from './new.js';
@@ -12,6 +13,7 @@ const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
     resolveProjectRoot,
     resolveAssetsRoot,
+    initializeDecisionAgentsGuidance,
     initializeDecisionRecords,
     regenerateDecisionIndex,
     createDecisionRecord,
@@ -55,8 +57,19 @@ export function createDecisionCommand(overrides = {}) {
             const projectRoot = await dependencies.resolveProjectRoot(context.cwd);
             const decisionsRoot = await resolveDecisionsRoot(context, projectRoot, options.decisionsRoot);
             const result = await dependencies.initializeDecisionRecords(decisionsRoot);
+            let guidance;
+            try {
+                guidance = await dependencies.initializeDecisionAgentsGuidance({
+                    projectRoot,
+                    decisionsRoot,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`Decision index initialized at ${result.decisionsRoot}, but AGENTS.md guidance could not be written: ${message}. Fix the guidance write error and rerun \`oat decision init\`.`, { cause: error });
+            }
             if (context.json) {
-                context.logger.json({ status: 'ok', ...result });
+                context.logger.json({ status: 'ok', ...result, guidance });
             }
             else {
                 context.logger.info(`Initialized decision scaffold at ${result.decisionsRoot}`);
@@ -66,6 +79,7 @@ export function createDecisionCommand(overrides = {}) {
                 if (result.skipped.length > 0) {
                     context.logger.info(`Skipped existing: ${result.skipped.join(', ')}`);
                 }
+                context.logger.info(`AGENTS.md guidance: root=${guidance.root}, decisions=${guidance.scoped}`);
             }
             process.exitCode = 0;
         }

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/init/tools/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/init/tools/index.ts"],"names":[],"mappings":"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"}

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

@@ -1,6 +1,7 @@
 import { rm, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { buildCommandContext, } from '../../../app/command-context.js';
+import { buildDecisionAgentsSectionBody, DECISION_AGENTS_SECTION_KEY, } from '../../decision/agents-guidance.js';
 import { copyDirWithStatus } from '../../init/tools/shared/copy-helpers.js';
 import { applyGitignore } from '../../local/apply.js';
 import { addLocalPaths } from '../../local/manage.js';
@@ -858,6 +859,9 @@ export async function runInitTools(context, dependencies) {
         const projectManagementSectionResult = selectedPacks.includes('project-management')
             ? await dependencies.upsertAgentsMdSection(projectRoot, PROJECT_MANAGEMENT_AGENTS_SECTION_KEY, buildProjectManagementAgentsSectionBody())
             : null;
+        const decisionSectionResult = selectedPacks.includes('project-management')
+            ? await dependencies.upsertAgentsMdSection(projectRoot, DECISION_AGENTS_SECTION_KEY, buildDecisionAgentsSectionBody())
+            : null;
         // Migrate: remove legacy <!-- OAT workflows --> section if present
         await dependencies.removeAgentsMdSection(projectRoot, 'workflows');
         if (!context.json && sectionResult.action !== 'no-change') {
@@ -868,6 +872,11 @@ export async function runInitTools(context, dependencies) {
             projectManagementSectionResult.action !== 'no-change') {
             context.logger.info(`AGENTS.md project-management section ${projectManagementSectionResult.action}.`);
         }
+        if (!context.json &&
+            decisionSectionResult !== null &&
+            decisionSectionResult.action !== 'no-change') {
+            context.logger.info(`AGENTS.md decisions section ${decisionSectionResult.action}.`);
+        }
         const affectedScopesList = [...affectedScopes];
         lastRunInitToolsMetadata = {
             affectedScopes: affectedScopesList,

package/dist/commands/init/tools/project-management/agents-guidance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents-guidance.d.ts","sourceRoot":"","sources":["../../../../../src/commands/init/tools/project-management/agents-guidance.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qCAAqC,uBAAuB,CAAC;AAE1E,wBAAgB,uCAAuC,IAAI,MAAM,CAehE"}
+{"version":3,"file":"agents-guidance.d.ts","sourceRoot":"","sources":["../../../../../src/commands/init/tools/project-management/agents-guidance.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qCAAqC,uBAAuB,CAAC;AAE1E,wBAAgB,uCAAuC,IAAI,MAAM,CAShE"}

package/dist/commands/init/tools/project-management/agents-guidance.js

@@ -7,11 +7,5 @@ export function buildProjectManagementAgentsSectionBody() {
         '- Consult it when prioritizing or planning work, checking the backlog, starting or closing tracked work, or looking for established repository context.',
         '- Start with `.oat/repo/AGENTS.md`; it routes to `pjm/` for active state and `reference/` for durable records.',
         '- If the surface is missing, initialize it with `oat pjm init`.',
-        '',
-        '### Decision Records',
-        '',
-        '- Before finalizing a durable repository decision, review `.oat/repo/reference/decisions/index.md` and any relevant records.',
-        '- When the user asks to record a durable decision or confirms a proposed capture, use `oat-pjm-decision`; use `oat decision new` for the CLI path.',
-        '- Do not hand-edit the generated decision index; run `oat decision regenerate-index` after record changes.',
     ].join('\n');
 }

package/dist/commands/init/tools/project-management/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/commands/init/tools/project-management/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAY9B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,OAAO,EAEL,KAAK,+BAA+B,EACpC,KAAK,8BAA8B,EACpC,MAAM,8BAA8B,CAAC;AAMtC,UAAU,sCAAsC;IAC9C,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,wBAAwB,EAAE,CACxB,OAAO,EAAE,+BAA+B,KACrC,OAAO,CAAC,8BAA8B,CAAC,CAAC;CAC9C;AASD,wBAAgB,uCAAuC,CACrD,SAAS,GAAE,OAAO,CAAC,sCAAsC,CAAM,GAC9D,OAAO,CAsHT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/commands/init/tools/project-management/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAgB9B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,OAAO,EAEL,KAAK,+BAA+B,EACpC,KAAK,8BAA8B,EACpC,MAAM,8BAA8B,CAAC;AAMtC,UAAU,sCAAsC;IAC9C,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,wBAAwB,EAAE,CACxB,OAAO,EAAE,+BAA+B,KACrC,OAAO,CAAC,8BAA8B,CAAC,CAAC;CAC9C;AASD,wBAAgB,uCAAuC,CACrD,SAAS,GAAE,OAAO,CAAC,sCAAsC,CAAM,GAC9D,OAAO,CAwIT"}

package/dist/commands/init/tools/project-management/index.js

@@ -1,4 +1,5 @@
 import { buildCommandContext, } from '../../../../app/command-context.js';
+import { buildDecisionAgentsSectionBody, DECISION_AGENTS_SECTION_KEY, } from '../../../decision/agents-guidance.js';
 import { upsertAgentsMdSection, } from '../../../shared/agents-md.js';
 import { readGlobalOptions } from '../../../shared/shared.utils.js';
 import { canonicalPathsForPack, setInstalledCanonicalPaths, } from '../../../tools/shared/install-sync-context.js';
@@ -52,11 +53,15 @@ export function createInitToolsProjectManagementCommand(overrides = {}) {
                 force: options.force,
             });
             didInstall = true;
-            let agentsGuidanceAction;
+            let projectManagementGuidanceAction;
+            let decisionGuidanceAction;
             let agentsGuidanceWarning;
             try {
-                const agentsGuidanceResult = await upsertAgentsMdSection(targetRoot, PROJECT_MANAGEMENT_AGENTS_SECTION_KEY, buildProjectManagementAgentsSectionBody());
-                agentsGuidanceAction = agentsGuidanceResult.action;
+                const projectManagementGuidanceResult = await upsertAgentsMdSection(targetRoot, PROJECT_MANAGEMENT_AGENTS_SECTION_KEY, buildProjectManagementAgentsSectionBody());
+                projectManagementGuidanceAction =
+                    projectManagementGuidanceResult.action;
+                const decisionGuidanceResult = await upsertAgentsMdSection(targetRoot, DECISION_AGENTS_SECTION_KEY, buildDecisionAgentsSectionBody());
+                decisionGuidanceAction = decisionGuidanceResult.action;
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -79,9 +84,13 @@ export function createInitToolsProjectManagementCommand(overrides = {}) {
                 context.logger.info(`Target root: ${targetRoot}`);
                 context.logger.info(`Skills: copied=${result.copiedSkills.length}, updated=${result.updatedSkills.length}, skipped=${result.skippedSkills.length}`);
                 context.logger.info(`Templates: copied=${result.copiedTemplates.length}, updated=${result.updatedTemplates.length}, skipped=${result.skippedTemplates.length}`);
-                if (agentsGuidanceAction !== undefined &&
-                    agentsGuidanceAction !== 'no-change') {
-                    context.logger.info(`AGENTS.md project-management section ${agentsGuidanceAction}.`);
+                if (projectManagementGuidanceAction !== undefined &&
+                    projectManagementGuidanceAction !== 'no-change') {
+                    context.logger.info(`AGENTS.md project-management section ${projectManagementGuidanceAction}.`);
+                }
+                if (decisionGuidanceAction !== undefined &&
+                    decisionGuidanceAction !== 'no-change') {
+                    context.logger.info(`AGENTS.md decisions section ${decisionGuidanceAction}.`);
                 }
                 if (agentsGuidanceWarning !== undefined) {
                     context.logger.warn(agentsGuidanceWarning);

package/dist/commands/pjm/init.d.ts

@@ -9,6 +9,6 @@ export interface RepoReferenceInitResult {
     skipped: string[];
 }
 export declare const INSTRUCTIONS_SYNC_HINT: string;
-export declare const CANONICAL_REPO_REFERENCE_PATHS: readonly [...("AGENTS.md" | "README.md" | "pjm/AGENTS.md" | "pjm/current-state.md" | "pjm/handoffs/README.md" | "pjm/roadmap.md" | "reference/AGENTS.md")[], "pjm/backlog/index.md", "pjm/backlog/completed.md", "pjm/backlog/items/.gitkeep", "pjm/backlog/archived/.gitkeep", "reference/decisions/index.md"];
+export declare const CANONICAL_REPO_REFERENCE_PATHS: readonly [...("AGENTS.md" | "README.md" | "pjm/AGENTS.md" | "pjm/current-state.md" | "pjm/handoffs/README.md" | "pjm/roadmap.md" | "reference/AGENTS.md")[], "pjm/backlog/index.md", "pjm/backlog/completed.md", "pjm/backlog/items/.gitkeep", "pjm/backlog/archived/.gitkeep", "reference/decisions/AGENTS.md", "reference/decisions/index.md"];
 export declare function initializeRepoReference(options: InitializeRepoReferenceOptions): Promise<RepoReferenceInitResult>;
 //# sourceMappingURL=init.d.ts.map

package/dist/commands/pjm/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/init.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAoBD,eAAO,MAAM,sBAAsB,QAEiD,CAAC;AAWrF,eAAO,MAAM,8BAA8B,iTAIjC,CAAC;AAyEX,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC,CAgElC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/init.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAoBD,eAAO,MAAM,sBAAsB,QAEiD,CAAC;AAerF,eAAO,MAAM,8BAA8B,kVAIjC,CAAC;AAyEX,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC,CAqElC"}

package/dist/commands/pjm/init.js

@@ -1,6 +1,7 @@
 import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { initializeBacklog } from '../backlog/init.js';
+import { initializeScopedDecisionAgentsGuidance } from '../decision/agents-guidance.js';
 import { initializeDecisionRecords } from '../decision/init.js';
 import { stripTemplateFrontmatter } from '../shared/strip-template-frontmatter.js';
 const TEMPLATE_TARGETS = [
@@ -23,7 +24,11 @@ const BACKLOG_PATHS = [
     'pjm/backlog/items/.gitkeep',
     'pjm/backlog/archived/.gitkeep',
 ];
-const DECISION_PATHS = ['reference/decisions/index.md'];
+const DECISION_AGENTS_PATH = 'reference/decisions/AGENTS.md';
+const DECISION_PATHS = [
+    DECISION_AGENTS_PATH,
+    'reference/decisions/index.md',
+];
 export const CANONICAL_REPO_REFERENCE_PATHS = [
     ...TEMPLATE_TARGETS.map((target) => target.target),
     ...BACKLOG_PATHS,
@@ -119,6 +124,9 @@ export async function initializeRepoReference(options) {
         }
     }
     await initializeDecisionRecords(join(options.repoRoot, 'reference', 'decisions'));
+    if (!existingDecisionPaths.has(DECISION_AGENTS_PATH)) {
+        await initializeScopedDecisionAgentsGuidance(join(options.repoRoot, 'reference', 'decisions'));
+    }
     for (const relativePath of DECISION_PATHS) {
         if (existingDecisionPaths.has(relativePath)) {
             skipped.push(relativePath);

package/package.json

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