@open-agent-toolkit/cli 0.2.7 → 0.2.9

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

@@ -188,6 +188,8 @@ Key behavior:
 - Non-interactive installs (including `--scope project`, `--scope user`, and the default pack set) are strictly additive and never remove a pack from a scope. Removal is interactive-only
 - Tracks installed vs bundled skill versions and reports outdated skills
 - Records installed pack state in shared repo config as `tools.<pack>: true` so other OAT workflows can detect installed capabilities without relying on filesystem heuristics
+- Refreshes the managed `OAT tools` section in the repository-root `AGENTS.md`.
+- Installing the `project-management` pack—through either the aggregate picker or `oat tools install project-management`—also upserts a managed `OAT project-management` section. It points agents to `.oat/repo/AGENTS.md` for active PJM and durable-reference routing, summarizes when to consult it, and gives decision-specific guidance for reviewing and creating durable records without hand-editing the generated index.
 - Interactive runs can prompt to update selected outdated skills
 - Successful installs report the final scope chosen for each pack, including `project + user` when a pack is installed in both, and auto-sync only the scopes actually changed by the install so untouched scopes are never re-synced or pruned
 - Install-triggered auto-sync limits removal planning to the canonical entries from the pack that was just installed, so stale manifest drift in unrelated packs does not delete other provider views

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.7",
-  "docs-config": "0.2.7",
-  "docs-theme": "0.2.7",
-  "docs-transforms": "0.2.7"
+  "cli": "0.2.9",
+  "docs-config": "0.2.9",
+  "docs-theme": "0.2.9",
+  "docs-transforms": "0.2.9"
 }

package/assets/skills/explainer-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: explainer-kit
-version: 1.0.0
+version: 1.0.1
 description: Use when building destination-neutral visual explainer artifacts from explicit, versioned inputs.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent, mcp__*
@@ -55,6 +55,8 @@ discovery, theme resolution, rendering, QA, and manifest/build-record
 persistence. It runs without OAT files or ambient configuration. Supplied fact
 bases receive only lightweight consistency/freshness checks. Federated inputs
 require a provider-neutral critic callback and invoke it exactly once.
+Optional claim `sections` tags route facts to matching recipe narrative
+sections; untagged claims remain shared context for every required section.
 
 Unattended calls use explicit, already-approved source artifacts, persist their
 review provenance in `source/content-approval.json`, and never prompt.

package/assets/skills/explainer-kit/references/contracts.md

@@ -36,7 +36,10 @@ contract.
   performs only the lightweight consistency and freshness check and never
   invokes the critic.
 - `factBase.mode: federated` names explicit source bindings. File locators
-  contain JSON with a `claims` array of `{ "id", "text", "locator"? }`.
+  contain JSON with a `claims` array of
+  `{ "id", "text", "locator"?, "sections"? }`. Optional `sections` values
+  are recipe `requiredNarrative` IDs; untagged claims remain shared across
+  every required section.
   Non-file bindings require a caller-supplied `sourceLoader(source)` callback.
   Every binding names its recipe `role` and `sourceSetId`. Multiple documents
   may share one source-set ID; recipe cardinality counts distinct sets, not

package/assets/skills/explainer-kit/references/fact-base-contract.md

@@ -58,12 +58,17 @@ Each source document contains a schema-compatible source and extracted claims:
       observedAt,
       authoritativeFor,
     },
-    claims: [{ id, text, locator }],
+    claims: [{ id, text, locator, sections }],
   }],
   overrides: [{ claimId, decision, confirmedAt }],
 }
 ```
 
+Optional `sections` entries are recipe `requiredNarrative` IDs. Tagged claims
+are routed only to those sections; untagged claims remain shared context for
+every required section. Federated reconciliation preserves shared scope when
+any agreeing selected observation is untagged.
+
 For conflicting text under one claim ID, an `authoritativeFor` declaration
 wins first. Otherwise the newest `observedAt` wins. A tie remains
 `contradictory`. Operator overrides take final precedence, produce an

package/assets/skills/explainer-kit/schemas/fact-base.schema.json

@@ -46,6 +46,15 @@
       "type": "string",
       "pattern": "^sha256:[a-f0-9]{64}$"
     },
+    "sectionIds": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+      },
+      "minItems": 1,
+      "uniqueItems": true
+    },
     "source": {
       "type": "object",
       "additionalProperties": false,
@@ -85,6 +94,7 @@
         "id": { "type": "string", "minLength": 1 },
         "text": { "type": "string", "minLength": 1 },
         "status": { "enum": ["confirmed", "overridden"] },
+        "sections": { "$ref": "#/$defs/sectionIds" },
         "citations": {
           "type": "array",
           "items": { "$ref": "#/$defs/citation" },
@@ -108,6 +118,7 @@
             "needs-confirmation"
           ]
         },
+        "sections": { "$ref": "#/$defs/sectionIds" },
         "citations": {
           "type": "array",
           "items": { "$ref": "#/$defs/citation" },

package/assets/skills/explainer-kit/scripts/lib/durability.mjs

@@ -166,10 +166,10 @@ export async function verifyRebuildability(artifact, runRoot) {
       await writeFileAtomic(runRoot, artifact.renderedPath, original);
     }
     return { verified: true, reason: null };
-  } catch (error) {
+  } catch (caught) {
     return {
       verified: false,
-      reason: `Deterministic replay failed: ${errorMessage(error)}`,
+      reason: `Deterministic replay failed: ${errorMessage(caught)}`,
     };
   }
 }

package/assets/skills/explainer-kit/scripts/lib/fact-base.mjs

@@ -2,6 +2,7 @@ import { canonicalHash, validateContract } from './contracts.mjs';
 
 const FACT_BASE_VERSION = 'explainer-kit.fact-base/v1';
 const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const SECTION_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const FINDING_REASONS = new Set([
   'contradictory',
   'stale',
@@ -107,6 +108,7 @@ async function processFederated(binding, { critic, now }) {
         text: override.decision,
         status: 'overridden',
         citations: citationsFor(entries),
+        ...sectionMetadata(entries),
       });
       continue;
     }
@@ -251,7 +253,8 @@ function collectObservations(documents, sourceById) {
         typeof claim.id !== 'string' ||
         claim.id.length === 0 ||
         typeof claim.text !== 'string' ||
-        claim.text.length === 0
+        claim.text.length === 0 ||
+        !validSections(claim.sections)
       ) {
         throw new Error(
           `Source ${document.source.id} contains an invalid claim.`,
@@ -263,6 +266,7 @@ function collectObservations(documents, sourceById) {
         text: claim.text,
         source: sourceById.get(document.source.id),
         locator: claim.locator ?? document.source.locator,
+        ...(claim.sections && { sections: [...claim.sections] }),
       });
       observations.set(claim.id, entries);
     }
@@ -307,6 +311,7 @@ function resolveObservations(claimId, entries) {
         text: entries[0].text,
         status: 'confirmed',
         citations: citationsFor(entries),
+        ...sectionMetadata(entries),
       },
     };
   }
@@ -341,6 +346,9 @@ function resolveObservations(claimId, entries) {
         citations: citationsFor(
           entries.filter(({ text }) => text === winner.entry.text),
         ),
+        ...sectionMetadata(
+          entries.filter(({ text }) => text === winner.entry.text),
+        ),
       },
     };
   }
@@ -352,6 +360,7 @@ function resolveObservations(claimId, entries) {
       text: `Conflicting values: ${[...byText.keys()].sort().join(' | ')}`,
       reason: 'contradictory',
       citations: citationsFor(entries),
+      ...sectionMetadata(entries),
     },
   };
 }
@@ -441,6 +450,7 @@ function integrateCriticFindings({
     }
 
     const claimIndex = claims.findIndex(({ id }) => id === finding.claimId);
+    const existingClaim = claimIndex >= 0 ? claims[claimIndex] : null;
     if (claimIndex >= 0) {
       claims.splice(claimIndex, 1);
     }
@@ -449,6 +459,7 @@ function integrateCriticFindings({
       text: finding.text,
       reason: finding.classification,
       citations,
+      ...(existingClaim?.sections && { sections: existingClaim.sections }),
     });
   }
 }
@@ -489,6 +500,29 @@ function uniqueCitations(citations) {
   ];
 }
 
+function validSections(sections) {
+  return (
+    sections === undefined ||
+    (Array.isArray(sections) &&
+      sections.length > 0 &&
+      new Set(sections).size === sections.length &&
+      sections.every(
+        (section) =>
+          typeof section === 'string' && SECTION_ID_PATTERN.test(section),
+      ))
+  );
+}
+
+function sectionMetadata(entries) {
+  if (entries.some(({ sections }) => sections === undefined)) {
+    return {};
+  }
+  const sections = [
+    ...new Set(entries.flatMap((entry) => entry.sections ?? [])),
+  ].sort();
+  return sections.length > 0 ? { sections } : {};
+}
+
 function byId(left, right) {
   return left.id.localeCompare(right.id);
 }

package/assets/skills/explainer-kit/scripts/lib/records.mjs

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
+import { readFile, readdir, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { validateContract } from './contracts.mjs';
@@ -70,6 +70,7 @@ export async function initializeRun(request) {
     request: normalizedRequest,
   };
 
+  await clearRunRoot(run);
   await writeJsonAtomic(run.runRoot, 'build-record.json', buildRecord);
   await writeJsonAtomic(
     run.runRoot,
@@ -226,6 +227,58 @@ function assertRun(run) {
   }
 }
 
+async function clearRunRoot(run) {
+  const entries = await readdir(run.runRoot, { withFileTypes: true });
+  if (entries.length === 0) return;
+  await assertOwnedRunRoot(run);
+  const removable = [];
+  for (const entry of entries) {
+    const path = join(run.runRoot, entry.name);
+    if (!(await containsSymlink(path, entry))) {
+      removable.push(path);
+    }
+  }
+  await Promise.all(
+    removable.map((path) => rm(path, { recursive: true, force: true })),
+  );
+}
+
+async function assertOwnedRunRoot(run) {
+  try {
+    const [persistedRequest, persistedRecord] = await Promise.all([
+      readJson(join(run.runRoot, 'run-request.json')),
+      readJson(join(run.runRoot, 'build-record.json')),
+    ]);
+    assertValidContract('run-request', persistedRequest);
+    assertValidContract('build-record', persistedRecord);
+    if (
+      persistedRequest.slug !== run.slug ||
+      persistedRequest.outputRoot !== run.outputRoot
+    ) {
+      throw new Error('Prior run identity does not match this slug.');
+    }
+  } catch {
+    throw new Error(
+      'Existing slug directory is not a prior Explainer Kit run; refusing to clear it.',
+    );
+  }
+}
+
+async function containsSymlink(path, entry) {
+  if (entry.isSymbolicLink()) return true;
+  if (!entry.isDirectory()) return false;
+  for (const child of await readdir(path, { withFileTypes: true })) {
+    if (await containsSymlink(join(path, child.name), child)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
 function isObject(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/assets/skills/explainer-kit/scripts/run.mjs

@@ -227,7 +227,9 @@ async function loadResumableRun(request) {
     persistedRequest.slug !== normalized.slug ||
     persistedRequest.recipe?.id !== normalized.recipe.id ||
     persistedRequest.recipe?.version !== normalized.recipe.version ||
-    persistedRequest.mode !== normalized.mode
+    persistedRequest.mode !== normalized.mode ||
+    canonicalHash(persistedRequest.factBase) !==
+      canonicalHash(normalized.factBase)
   ) {
     throw codedError(
       'E_APPROVAL_RESUME',
@@ -551,12 +553,25 @@ function manifestFor(state, buildRecord, createdAt, immutableHashes) {
 
 function createContentModel(recipe, artifact, slug, factBase) {
   const facts = [
-    ...factBase.claims.map(({ text }) => text),
-    ...factBase.unresolvedClaims.map(
-      ({ text }) => `Needs confirmation: ${text}`,
+    ...factBase.claims.map(({ text, sections }) => ({ text, sections })),
+    ...factBase.unresolvedClaims.map(({ text, sections }) => ({
+      text: `Needs confirmation: ${text}`,
+      sections,
+    })),
+  ];
+  const unknownSections = [
+    ...new Set(
+      facts
+        .flatMap(({ sections }) => sections ?? [])
+        .filter((section) => !recipe.requiredNarrative.includes(section)),
     ),
   ];
-  const summary = facts.length > 0 ? facts.join(' ') : 'No confirmed facts.';
+  if (unknownSections.length > 0) {
+    throw codedError(
+      'E_CONTENT',
+      `Unknown narrative section tags: ${unknownSections.join(', ')}`,
+    );
+  }
   return {
     artifactId: artifact.id,
     slug,
@@ -564,11 +579,19 @@ function createContentModel(recipe, artifact, slug, factBase) {
     description: `Approved-source ${humanize(recipe.id).toLowerCase()}.`,
     eyebrow: 'Explainer Kit',
     footer: 'Generated from the retained reconciled fact base.',
-    sections: recipe.requiredNarrative.map((id) => ({
-      id,
-      title: humanize(id),
-      content: summary,
-    })),
+    sections: recipe.requiredNarrative.map((id) => {
+      const sectionFacts = facts
+        .filter(({ sections }) => !sections || sections.includes(id))
+        .map(({ text }) => text);
+      return {
+        id,
+        title: humanize(id),
+        content:
+          sectionFacts.length > 0
+            ? sectionFacts.join(' ')
+            : 'No confirmed facts.',
+      };
+    }),
     artifactLinks: [],
   };
 }

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

@@ -23,6 +23,7 @@ import { createInitToolsIdeasCommand } from './ideas/index.js';
 import { installIdeas as defaultInstallIdeas, } from './ideas/install-ideas.js';
 import { buildPackInstallStateMap, } from './install-state.js';
 import { createInitToolsProjectManagementCommand } from './project-management/index.js';
+import { buildProjectManagementAgentsSectionBody, PROJECT_MANAGEMENT_AGENTS_SECTION_KEY, } from './project-management/agents-guidance.js';
 import { installProjectManagement as defaultInstallProjectManagement, } from './project-management/install-project-management.js';
 import { createInitToolsResearchCommand } from './research/index.js';
 import { installResearch as defaultInstallResearch, } from './research/install-research.js';
@@ -863,11 +864,19 @@ export async function runInitTools(context, dependencies) {
         }));
         const sectionBody = buildToolPacksSectionBody(packScopeInfo);
         const sectionResult = await dependencies.upsertAgentsMdSection(projectRoot, 'tools', sectionBody);
+        const projectManagementSectionResult = selectedPacks.includes('project-management')
+            ? await dependencies.upsertAgentsMdSection(projectRoot, PROJECT_MANAGEMENT_AGENTS_SECTION_KEY, buildProjectManagementAgentsSectionBody())
+            : null;
         // Migrate: remove legacy <!-- OAT workflows --> section if present
         await dependencies.removeAgentsMdSection(projectRoot, 'workflows');
         if (!context.json && sectionResult.action !== 'no-change') {
             context.logger.info(`AGENTS.md tool packs section ${sectionResult.action}.`);
         }
+        if (!context.json &&
+            projectManagementSectionResult !== null &&
+            projectManagementSectionResult.action !== 'no-change') {
+            context.logger.info(`AGENTS.md project-management section ${projectManagementSectionResult.action}.`);
+        }
         const config = await dependencies.readOatConfig(projectRoot);
         const tools = buildInstalledToolsConfig(selectedPacks, initialPackStates, config.tools);
         await dependencies.writeOatConfig(projectRoot, { ...config, tools });

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

@@ -0,0 +1,3 @@
+export declare const PROJECT_MANAGEMENT_AGENTS_SECTION_KEY = "project-management";
+export declare function buildProjectManagementAgentsSectionBody(): string;
+//# sourceMappingURL=agents-guidance.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,17 @@
+export const PROJECT_MANAGEMENT_AGENTS_SECTION_KEY = 'project-management';
+export function buildProjectManagementAgentsSectionBody() {
+    return [
+        '### Project Management',
+        '',
+        '- Repository planning and durable context live under `.oat/repo/`.',
+        '- 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;AAQ9B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,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,CAyFT"}
+{"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"}

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

@@ -1,9 +1,11 @@
 import { buildCommandContext, } from '../../../../app/command-context.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';
 import { resolveAssetsRoot } from '../../../../fs/assets.js';
 import { resolveProjectRoot } from '../../../../fs/paths.js';
 import { Command } from 'commander';
+import { buildProjectManagementAgentsSectionBody, PROJECT_MANAGEMENT_AGENTS_SECTION_KEY, } from './agents-guidance.js';
 import { installProjectManagement as defaultInstallProjectManagement, } from './install-project-management.js';
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
@@ -49,6 +51,17 @@ export function createInitToolsProjectManagementCommand(overrides = {}) {
                 targetRoot,
                 force: options.force,
             });
+            didInstall = true;
+            let agentsGuidanceAction;
+            let agentsGuidanceWarning;
+            try {
+                const agentsGuidanceResult = await upsertAgentsMdSection(targetRoot, PROJECT_MANAGEMENT_AGENTS_SECTION_KEY, buildProjectManagementAgentsSectionBody());
+                agentsGuidanceAction = agentsGuidanceResult.action;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                agentsGuidanceWarning = `Could not update AGENTS.md project-management guidance: ${message}`;
+            }
             if (context.json) {
                 context.logger.json({
                     status: 'ok',
@@ -56,6 +69,9 @@ export function createInitToolsProjectManagementCommand(overrides = {}) {
                     targetRoot,
                     assetsRoot,
                     result,
+                    ...(agentsGuidanceWarning === undefined
+                        ? {}
+                        : { warnings: [agentsGuidanceWarning] }),
                 });
             }
             else {
@@ -63,9 +79,15 @@ 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 (agentsGuidanceWarning !== undefined) {
+                    context.logger.warn(agentsGuidanceWarning);
+                }
                 context.logger.info('Run: oat sync --scope project');
             }
-            didInstall = true;
             process.exitCode = 0;
         }
         catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "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.7"
+    "@open-agent-toolkit/control-plane": "0.2.9"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",