@aws/agentcore 1.0.0-preview.2 → 1.0.0-preview.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/agentcore",
-  "version": "1.0.0-preview.2",
+  "version": "1.0.0-preview.21",
   "description": "CLI for Amazon Bedrock AgentCore",
   "license": "Apache-2.0",
   "repository": {
@@ -41,6 +41,7 @@
   "files": [
     "dist",
     "scripts",
+    "npm-shrinkwrap.json",
     "!dist/mcp-harness"
   ],
   "scripts": {
@@ -52,11 +53,11 @@
     "build:assets": "node scripts/copy-assets.mjs",
     "build:harness": "BUILD_HARNESS=1 node esbuild.config.mjs",
     "cli": "npx tsx src/cli/index.ts",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
-    "lint:fix": "eslint src/ --fix",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit --incremental",
+    "lint": "eslint --cache src/",
+    "lint:fix": "eslint --cache src/ --fix",
+    "format": "prettier --cache --write .",
+    "format:check": "prettier --cache --check .",
     "secrets:check": "secretlint '**/*'",
     "security:audit": "npm audit --audit-level=high --omit=dev",
     "clean": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true})\"",
@@ -64,35 +65,44 @@
     "test": "vitest run --project unit",
     "test:all": "vitest run",
     "test:watch": "vitest --project unit",
-    "test:integ": "vitest run --project integ",
+    "test:integ": "npm run build && vitest run --project integ",
     "test:unit": "vitest run --project unit --coverage",
     "test:e2e": "vitest run --project e2e",
     "test:update-snapshots": "vitest run --project unit --update",
     "test:tui": "npm run build:harness && vitest run --project tui",
+    "test:browser": "npx playwright test --config browser-tests/playwright.config.ts",
     "bundle": "node scripts/bundle.mjs"
   },
   "dependencies": {
-    "@aws-cdk/toolkit-lib": "^1.16.0",
+    "@aws-cdk/cdk-assets-lib": "^1.4.10",
+    "@aws-cdk/toolkit-lib": "^1.28.0",
     "@aws-sdk/client-application-signals": "^3.1003.0",
     "@aws-sdk/client-bedrock": "^3.1012.0",
     "@aws-sdk/client-bedrock-agent": "^3.1012.0",
-    "@aws-sdk/client-bedrock-agentcore": "^3.1020.0",
-    "@aws-sdk/client-bedrock-agentcore-control": "^3.1020.0",
+    "@aws-sdk/client-bedrock-agentcore": "^3.1061.0",
+    "@aws-sdk/client-bedrock-agentcore-control": "^3.1061.0",
     "@aws-sdk/client-bedrock-runtime": "^3.893.0",
     "@aws-sdk/client-cloudformation": "^3.893.0",
     "@aws-sdk/client-cloudwatch-logs": "^3.893.0",
+    "@aws-sdk/client-efs": "^3.1067.0",
     "@aws-sdk/client-resource-groups-tagging-api": "^3.893.0",
     "@aws-sdk/client-s3": "^3.1012.0",
+    "@aws-sdk/client-s3files": "^3.1067.0",
     "@aws-sdk/client-sts": "^3.893.0",
     "@aws-sdk/client-xray": "^3.1003.0",
     "@aws-sdk/credential-providers": "^3.893.0",
-    "@aws/agent-inspector": "0.2.1",
+    "@aws-sdk/region-config-resolver": "^3.972.13",
+    "@aws/agent-inspector": "0.6.1",
     "@commander-js/extra-typings": "^14.0.0",
-    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.215.0",
     "@opentelemetry/otlp-transformer": "^0.213.0",
+    "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-metrics": "^2.6.1",
     "@smithy/shared-ini-file-loader": "^4.4.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",
+    "fast-json-stable-stringify": "^2.1.0",
     "fflate": "^0.8.2",
     "handlebars": "^4.7.8",
     "ink": "^6.6.0",
@@ -100,29 +110,35 @@
     "ink-spinner": "^5.0.0",
     "js-yaml": "^4.1.1",
     "react": "^19.2.3",
+    "ws": "^8.21.0",
     "yaml": "^2.8.3",
     "zod": "^4.3.5"
   },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "^1.3.0"
+  },
   "peerDependencies": {
-    "aws-cdk-lib": "^2.248.0",
+    "aws-cdk-lib": "^2.258.0",
     "constructs": "^10.0.0"
   },
   "devDependencies": {
     "@aws-sdk/client-cognito-identity-provider": "^3.1018.0",
     "@eslint/js": "^9.39.2",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@secretlint/secretlint-rule-preset-recommend": "^11.3.0",
+    "@playwright/test": "^1.59.1",
+    "@secretlint/secretlint-rule-preset-recommend": "^12.2.0",
     "@trivago/prettier-plugin-sort-imports": "^6.0.2",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.0.3",
     "@types/react": "^19.2.7",
+    "@types/ws": "^8.18.1",
     "@typescript-eslint/eslint-plugin": "^8.50.0",
     "@typescript-eslint/parser": "^8.50.0",
     "@vitest/coverage-v8": "^4.0.18",
     "@xterm/headless": "^6.0.0",
-    "aws-cdk-lib": "^2.248.0",
+    "aws-cdk-lib": "^2.258.0",
     "constructs": "^10.4.4",
-    "esbuild": "^0.27.2",
+    "esbuild": "^0.28.0",
     "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.4",
@@ -133,10 +149,12 @@
     "eslint-plugin-security": "^4.0.0",
     "husky": "^9.1.7",
     "ink-testing-library": "^4.0.0",
+    "jose": "^6.2.3",
     "lint-staged": "^16.2.7",
     "node-pty": "^1.1.0",
     "prettier": "^3.7.4",
-    "secretlint": "^11.3.0",
+    "secretlint": "^12.2.0",
+    "strip-ansi": "^7.2.0",
     "tsx": "^4.21.0",
     "typescript": "^5",
     "typescript-eslint": "^8.50.1",
@@ -144,23 +162,27 @@
   },
   "overridesComments": {
     "minimatch": "GHSA-7r86-cg39-jmmj, GHSA-23c5-xmqv-rm74: minimatch 10.0.0-10.2.2 has ReDoS vulnerabilities. Multiple transitive deps (eslint, typescript-eslint, eslint-plugin-import, eslint-plugin-react, prettier-plugin-sort-imports, aws-cdk-lib) pin older versions. Remove this override once upstream packages update their minimatch dependency to >=10.2.3.",
+    "glob": "glob <12 is deprecated and emits npm install warnings (https://github.com/isaacs/node-glob). Pulled in transitively via archiver-utils@5.0.2 (latest), which still pins glob@^10.0.0. archiver-utils only uses glob.sync(pattern, options), which remains compatible in glob@13. Remove this override once archiver-utils updates its glob dependency.",
     "fast-xml-parser": "GHSA-8gc5-j5rx-235r, GHSA-jp2q-39xq-3w4g: fast-xml-parser <=5.5.6 has entity expansion bypass (CVE-2026-33036, CVE-2026-33349). Transitive via @aws-sdk/xml-builder. Remove once @aws-sdk updates to fast-xml-parser >=5.5.7.",
-    "@aws-sdk/xml-builder": "aws/aws-sdk-js-v3#7867: @aws-sdk/xml-builder <3.972.14 does not configure maxTotalExpansions on fast-xml-parser, causing 'Entity expansion limit exceeded' on large CloudFormation responses. Remove once @aws-sdk/client-* deps are bumped past 3.972.14."
+    "@aws-sdk/xml-builder": "aws/aws-sdk-js-v3#7867: @aws-sdk/xml-builder <3.972.14 does not configure maxTotalExpansions on fast-xml-parser, causing 'Entity expansion limit exceeded' on large CloudFormation responses. Remove once @aws-sdk/client-* deps are bumped past 3.972.14.",
+    "protobufjs": "GHSA-f38q-mgvj-vph7, GHSA-wcpc-wj8m-hjx6, GHSA-94rc-8x27-4472: protobufjs <=7.6.2 / 8.0.0-8.5.0 has property shadowing and DoS vulnerabilities. Transitive via @opentelemetry/otlp-transformer. Remove once @opentelemetry updates to protobufjs >=7.6.3 or >=8.5.1."
   },
   "overrides": {
     "minimatch": "10.2.4",
+    "glob": "^13.0.0",
     "fast-xml-parser": "5.5.7",
-    "@aws-sdk/xml-builder": "3.972.15"
+    "@aws-sdk/xml-builder": "3.972.15",
+    "protobufjs": ">=7.6.3"
   },
   "engines": {
     "node": ">=20"
   },
   "lint-staged": {
     "*.{ts,tsx}": [
-      "eslint --max-warnings=10"
+      "eslint --cache --max-warnings=10"
     ],
     "*.{ts,tsx,js,jsx,json,md,css,html,yml,yaml}": [
-      "prettier --check"
+      "prettier --cache --check"
     ],
     "*": [
       "secretlint"

package/scripts/bump-version.ts

@@ -183,7 +183,7 @@ function getGitLog(sinceTag?: string): string {
     } else {
       // Try to get the last tag
       try {
-        const lastTag = execSync('git describe --tags --abbrev=0', { encoding: 'utf-8' }).trim();
+        const lastTag = execSync("git describe --tags --abbrev=0 --match 'v*'", { encoding: 'utf-8' }).trim();
         cmd += ` ${lastTag}..HEAD`;
       } catch {
         // No tags exist, get last 20 commits
@@ -218,11 +218,11 @@ function categorizeCommits(gitLog: string): CategorizedChanges {
 
     const msg = trimmed.slice(2).trim();
 
-    if (msg.startsWith('feat:') || msg.startsWith('feature:')) {
+    if (/^(feat|feature)(\(.*?\))?:/.test(msg)) {
       result.features.push(msg);
-    } else if (msg.startsWith('fix:') || msg.startsWith('bugfix:')) {
+    } else if (/^(fix|bugfix)(\(.*?\))?:/.test(msg)) {
       result.fixes.push(msg);
-    } else if (msg.startsWith('docs:') || msg.startsWith('doc:')) {
+    } else if (/^docs?(\(.*?\))?:/.test(msg)) {
       result.docs.push(msg);
     } else {
       result.other.push(msg);

package/scripts/bundle.mjs

@@ -1,5 +1,5 @@
 /**
- * bundle.mjs — Single command to build CLI + CDK constructs + frontend into one tarball.
+ * bundle.mjs — Single command to build CLI + CDK constructs into one tarball.
  *
  * This is a testing-only workflow. It does NOT modify the default build or
  * deployment flow. The normal `npm run build` + `npm pack` pipeline is unchanged.
@@ -9,16 +9,19 @@
  * At `agentcore create` time, CDKRenderer detects this tarball and installs it
  * after the normal `npm install`, overriding the registry version.
  *
- * It also builds the @aws/agent-inspector frontend and copies its dist-assets
- * into the CLI's dist/agent-inspector/ directory, overriding the npm registry version.
- *
  * Usage:
  *   node scripts/bundle.mjs
  *   npm run bundle
  *
  * Environment variables:
- *   AGENTCORE_CDK_PATH       — absolute path to the agentcore-l3-cdk-constructs repo
- *   AGENT_INSPECTOR_PATH     — absolute path to the agent-inspector repo
+ *   AGENTCORE_CDK_PATH              — path to the agentcore-l3-cdk-constructs repo.
+ *                                     Falls back to ../agentcore-l3-cdk-constructs, then clones from GitHub.
+ *   AGENTCORE_INSPECTOR_PATH         — path to the agent-inspector repo.
+ *                                     Falls back to ../agent-inspector. If found, builds and bundles
+ *                                     the local version instead of the npm-installed one.
+ *   AGENTCORE_TARBALL_OUTPUT        — output path (without .tgz) for the tarball. Relative to cwd.
+ *   AGENTCORE_TARBALL_VERSION_SUFFIX — version prerelease suffix (e.g. "abc12-def34").
+ *                                     Defaults to a timestamp if not set.
  */
 import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs';
@@ -80,18 +83,19 @@ function resolveCdkPath() {
 }
 
 /**
- * Resolve the agent-inspector repo path. Priority:
- * 1. AGENT_INSPECTOR_PATH env var
+ * Resolve a local agent-inspector repo path. Priority:
+ * 1. AGENTCORE_INSPECTOR_PATH env var
  * 2. Sibling directory ../agent-inspector
+ * 3. null (use npm-installed version)
  */
 function resolveInspectorPath() {
-  if (process.env.AGENT_INSPECTOR_PATH) {
-    const p = path.resolve(process.env.AGENT_INSPECTOR_PATH);
+  if (process.env.AGENTCORE_INSPECTOR_PATH) {
+    const p = path.resolve(process.env.AGENTCORE_INSPECTOR_PATH);
     if (fs.existsSync(path.join(p, 'package.json'))) {
-      log(`Using agent-inspector from AGENT_INSPECTOR_PATH: ${p}`);
+      log(`Using agent-inspector from AGENTCORE_INSPECTOR_PATH: ${p}`);
       return p;
     }
-    console.warn(`  WARNING: AGENT_INSPECTOR_PATH=${p} does not contain package.json, ignoring.`);
+    console.warn(`  WARNING: AGENTCORE_INSPECTOR_PATH=${p} does not contain package.json, ignoring.`);
   }
 
   const sibling = path.resolve(cliRoot, '..', 'agent-inspector');
@@ -109,8 +113,14 @@ function resolveInspectorPath() {
 
 log('Starting bundle process...');
 
-const timestamp = Math.floor(Date.now() / 1000);
-log(`Bundle timestamp: ${timestamp}`);
+const now = new Date();
+const timestamp = now.toISOString().replace(/[-:T]/g, '').slice(0, 14);
+const versionSuffix = process.env.AGENTCORE_TARBALL_VERSION_SUFFIX || timestamp;
+if (!/^[\w.-]+$/.test(versionSuffix)) {
+  console.error(`ERROR: Invalid version suffix: ${versionSuffix}`);
+  process.exit(1);
+}
+log(`Bundle version suffix: ${versionSuffix}`);
 
 // Helper to bump a package version with a unique e2e timestamp tag.
 // Saves the original version so it can be restored after packing.
@@ -119,7 +129,9 @@ function bumpVersion(pkgDir) {
   const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
   const originalVersion = pkg.version;
   const baseVersion = originalVersion.split('-')[0];
-  pkg.version = `${baseVersion}-${timestamp}`;
+  const prerelease = originalVersion.includes('-') ? originalVersion.split('-').slice(1).join('-') : '';
+  const tag = prerelease ? `${prerelease}-${versionSuffix}` : versionSuffix;
+  pkg.version = `${baseVersion}-${tag}`;
   fs.writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2) + '\n');
   log(`Bumped ${pkg.name} version: ${originalVersion} -> ${pkg.version}`);
   return { pkgJsonPath, originalVersion, bumpedVersion: pkg.version };
@@ -131,6 +143,17 @@ function restoreVersion({ pkgJsonPath, originalVersion }) {
   fs.writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2) + '\n');
 }
 
+/**
+ * If AGENTCORE_TARBALL_OUTPUT is set, return a resolved path using it as base.
+ * Always appends .tgz.
+ */
+function resolveTarballPath(tarballPath) {
+  const envPath = process.env.AGENTCORE_TARBALL_OUTPUT;
+  if (!envPath) return tarballPath;
+  const base = envPath.replace(/\.tgz$/, '');
+  return path.resolve(`${base}.tgz`);
+}
+
 // Step 1: Resolve and build CDK constructs
 const cdkPath = resolveCdkPath();
 
@@ -164,12 +187,7 @@ run('npm', ['install'], { cwd: cliRoot });
 log('Building CLI...');
 run('npm', ['run', 'build'], { cwd: cliRoot });
 
-// Step 4: Copy CDK tarball into dist/assets/ so CDKRenderer can detect it
-const bundledTarballDest = path.join(cliRoot, 'dist', 'assets', 'bundled-agentcore-cdk.tgz');
-fs.copyFileSync(cdkTarballSrc, bundledTarballDest);
-log(`Placed CDK tarball at ${bundledTarballDest}`);
-
-// Step 5: Build and bundle agent-inspector frontend (overrides the npm version)
+// Step 3.5: If local agent-inspector is available, build and overwrite dist/agent-inspector/
 const inspectorPath = resolveInspectorPath();
 if (inspectorPath) {
   log('Installing agent-inspector dependencies...');
@@ -178,24 +196,26 @@ if (inspectorPath) {
   log('Building agent-inspector...');
   run('npm', ['run', 'build'], { cwd: inspectorPath });
 
-  const inspectorDistSrc = path.join(inspectorPath, 'dist-assets');
-  const inspectorDistDest = path.join(cliRoot, 'dist', 'agent-inspector');
-
-  if (fs.existsSync(inspectorDistSrc)) {
-    if (fs.existsSync(inspectorDistDest)) {
-      fs.rmSync(inspectorDistDest, { recursive: true });
-    }
-    fs.cpSync(inspectorDistSrc, inspectorDistDest, { recursive: true });
-    log(`Copied agent-inspector frontend to ${inspectorDistDest}`);
-  } else {
-    console.error(`ERROR: agent-inspector build did not produce dist-assets/ at ${inspectorDistSrc}`);
+  const inspectorDistAssets = path.join(inspectorPath, 'dist-assets');
+  if (!fs.existsSync(inspectorDistAssets)) {
+    console.error(`ERROR: agent-inspector build did not produce dist-assets/ at ${inspectorDistAssets}`);
     process.exit(1);
   }
-} else {
-  log('No local agent-inspector found — using npm registry version.');
+
+  const inspectorDest = path.join(cliRoot, 'dist', 'agent-inspector');
+  if (fs.existsSync(inspectorDest)) {
+    fs.rmSync(inspectorDest, { recursive: true });
+  }
+  fs.cpSync(inspectorDistAssets, inspectorDest, { recursive: true });
+  log(`Replaced dist/agent-inspector/ with local build from ${inspectorPath}`);
 }
 
-// Step 6: Bump CLI version and pack into final tarball (includes the bundled CDK tarball + frontend)
+// Step 4: Copy CDK tarball into dist/assets/ so CDKRenderer can detect it
+const bundledTarballDest = path.join(cliRoot, 'dist', 'assets', 'bundled-agentcore-cdk.tgz');
+fs.copyFileSync(cdkTarballSrc, bundledTarballDest);
+log(`Placed CDK tarball at ${bundledTarballDest}`);
+
+// Step 5: Bump CLI version and pack into final tarball (includes the bundled CDK tarball)
 const cliVersionInfo = bumpVersion(cliRoot);
 try {
   log('Packing CLI tarball...');
@@ -207,10 +227,19 @@ try {
 const cliTarballName = `aws-agentcore-${cliVersionInfo.bumpedVersion}.tgz`;
 const cliTarballPath = path.join(cliRoot, cliTarballName);
 
-if (fs.existsSync(cliTarballPath)) {
-  log(`Done! Tarball: ${cliTarballPath}`);
-  log(`Install with: npm install ${cliTarballPath}`);
-  log('When you run agentcore create, the bundled CDK constructs will be installed automatically.');
-} else {
-  log(`Done! Check ${cliRoot} for the .tgz file.`);
+if (!fs.existsSync(cliTarballPath)) {
+  console.error(`ERROR: Expected tarball at ${cliTarballPath} but not found.`);
+  process.exit(1);
+}
+
+const finalTarballPath = resolveTarballPath(cliTarballPath);
+if (finalTarballPath !== cliTarballPath) {
+  fs.mkdirSync(path.dirname(finalTarballPath), { recursive: true });
+  fs.renameSync(cliTarballPath, finalTarballPath);
+  log(`Renamed tarball to: ${finalTarballPath}`);
 }
+
+// Final output
+log(`Done! Tarball:   ${finalTarballPath}`);
+log(`Install with:    npm install -g ${finalTarballPath}`);
+log('When you run agentcore create, the bundled CDK constructs will be installed automatically.');

package/scripts/extract-cli-model.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+// =============================================================================
+// extract-cli-model.mjs  —  agentcore CLI -> doc-model JSON
+// =============================================================================
+// Runs `agentcore <cmd> --help` for every command, parses the Commander.js help
+// output, and emits the SAME shared doc-model schema (v1) as the SDK extractors
+// so the one shared renderer (_shared/render_adoc.py) produces consistent .adoc.
+//
+// Why --help scraping (not AST): it is 1:1 with what users actually see, and it
+// survives refactors of the command source. Commander.js help is
+// stable and easy to parse (Usage / Arguments / Options blocks).
+//
+// Decision: ALL ~30 commands, arranged into groups (one group == one .adoc).
+//
+// NOTE: if these workflows are later consolidated into a single shared reusable
+// workflow, this script is vendored there and selected via `language: cli`.
+// Standalone here for the draft.
+// =============================================================================
+import { execFileSync } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { argv } from 'node:process';
+
+// Command grouping (arranged properly, per the request). Mirrors the sections
+// in agentcore-cli/docs/commands.md. Any command discovered from the binary but
+// not listed here lands in the "Other" group so nothing is silently dropped.
+const GROUPS = [
+  {
+    id: 'project-lifecycle',
+    title: 'Project Lifecycle',
+    commands: ['create', 'deploy', 'dev', 'package', 'export', 'update', 'validate'],
+  },
+  {
+    id: 'invocation',
+    title: 'Invocation & Runtime',
+    commands: ['invoke', 'exec', 'run', 'logs', 'traces', 'status', 'fetch', 'view'],
+  },
+  {
+    id: 'resources',
+    title: 'Resource Management',
+    commands: ['add', 'remove', 'import'],
+  },
+  {
+    id: 'evaluation',
+    title: 'Evaluation & Datasets',
+    commands: ['evals', 'batch-evaluations', 'dataset'],
+  },
+  {
+    id: 'optimization',
+    title: 'Optimization & Config Bundles',
+    commands: ['config-bundle', 'promote', 'archive'],
+  },
+  {
+    id: 'operations',
+    title: 'Operations & Settings',
+    commands: ['pause', 'resume', 'stop', 'config', 'telemetry', 'feedback'],
+  },
+];
+
+// AGENTCORE_BIN may be a single command ("agentcore") OR a multi-token
+// invocation ("node /path/to/index.mjs"). Split into [executable, ...prefixArgs]
+// so execFileSync gets a real executable and forwards the rest as args —
+// passing the whole string as argv[0] would make execFileSync look for an
+// executable literally named "node /path/...", which fails silently to empty.
+const BIN_TOKENS = (process.env.AGENTCORE_BIN || 'agentcore').split(/\s+/);
+const BIN = BIN_TOKENS[0];
+const BIN_PREFIX_ARGS = BIN_TOKENS.slice(1);
+
+function getArg(flag) {
+  const i = argv.indexOf(flag);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+
+function help(args) {
+  try {
+    return execFileSync(BIN, [...BIN_PREFIX_ARGS, ...args, '--help'], {
+      encoding: 'utf8',
+      // CLI launches a TUI without args; --help forces non-interactive text.
+      env: { ...process.env, NO_COLOR: '1', CI: '1' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (e) {
+    // Commander exits non-zero for some help paths; stdout still holds text.
+    return (e.stdout && e.stdout.toString()) || '';
+  }
+}
+
+// Parse a Commander.js help blob into { summary, signature, params, options }.
+function parseHelp(text, name) {
+  const lines = text.split('\n');
+  const out = { summary: '', signature: '', args: [], options: [] };
+  let section = 'head';
+  const descLines = [];
+
+  for (const raw of lines) {
+    const line = raw.replace(/\s+$/, '');
+    if (/^Usage:/.test(line)) {
+      out.signature = line.replace(/^Usage:\s*/, '').trim();
+      section = 'desc';
+      continue;
+    }
+    if (/^Arguments:/.test(line)) {
+      section = 'args';
+      continue;
+    }
+    if (/^Options:/.test(line)) {
+      section = 'options';
+      continue;
+    }
+    if (/^Commands:/.test(line)) {
+      section = 'commands';
+      continue;
+    }
+
+    if (section === 'desc') {
+      if (line.trim()) descLines.push(line.trim());
+    } else if (section === 'args') {
+      const m = line.match(/^\s+(\S+)\s{2,}(.*)$/);
+      if (m) out.args.push({ name: m[1], type: null, required: true, description: m[2].trim() });
+    } else if (section === 'options') {
+      const m = line.match(/^\s+(-[^\s].*?)\s{2,}(.*)$/);
+      if (m) out.options.push({ name: m[1].trim(), type: null, required: false, description: m[2].trim() });
+    }
+  }
+  out.summary = descLines.join(' ');
+  return out;
+}
+
+function entryForCommand(name) {
+  const raw = help([name]);
+  // Fail loudly on phantom commands / drift. A real command's help names itself
+  // in the usage line (`Usage: agentcore <name> ...`); an unknown command falls
+  // back to the root usage (`Usage: agentcore [options] [command]`), which does
+  // NOT contain the name. Without this guard such commands would silently render
+  // as empty stubs (synthesized signature, no description/params).
+  if (!new RegExp(`^Usage:\\s+agentcore\\s+${name}\\b`, 'm').test(raw)) {
+    throw new Error(
+      `Command "${name}" produced no self-describing help output — it is likely ` +
+        `not a real CLI command (phantom/renamed). Remove it from GROUPS or fix the name.`
+    );
+  }
+  const parsed = parseHelp(raw, name);
+  // subcommands (e.g. `add agent`, `remove tool`) show under "Commands:"—
+  // we surface the top-level command; nested ones can be expanded later.
+  return {
+    kind: 'command',
+    name: `agentcore ${name}`,
+    signature: parsed.signature || `agentcore ${name} [options]`,
+    summary: parsed.summary,
+    description: '',
+    // reuse params for both positional args and flags, flagged by required.
+    // The renderer already wraps param names in backticks, so don't add our
+    // own (that produced double-backticks). Drop the ubiquitous help flag.
+    params: [...parsed.args, ...parsed.options.filter(o => !/^-h,?\s|--help\b/.test(o.name))],
+    returns: null,
+    raises: [],
+    examples: [],
+    members: [],
+  };
+}
+
+function discoverCommands() {
+  // Parse the root help "Commands:" block so we don't miss anything new.
+  // In Commander output, a command entry starts at EXACTLY 2 spaces of indent
+  // (e.g. "  deploy|dp [options]  ...") while wrapped description lines are
+  // indented much deeper (~36 spaces). Matching only the 2-space indent avoids
+  // scraping the first word of a wrapped description ("locally", "past", ...).
+  // We also strip the "|alias" and trailing "[options]"/"<arg>" tokens.
+  const text = help([]);
+  const found = [];
+  let inCmds = false;
+  for (const line of text.split('\n')) {
+    if (/^Commands:/.test(line)) {
+      inCmds = true;
+      continue;
+    }
+    if (!inCmds) continue;
+    // stop if we hit a new top-level section (e.g. a footer) — non-indented text
+    if (line.trim() && !/^ {2}\S/.test(line) && !/^ {3,}/.test(line)) break;
+    const m = line.match(/^ {2}([a-z][a-z0-9-]*)(?:\|[a-z0-9-]+)?\b/);
+    if (m) found.push(m[1]);
+  }
+  return found;
+}
+
+function main() {
+  const outPath = getArg('--out');
+  const version = getArg('--version') || 'unknown';
+
+  const discovered = new Set(discoverCommands());
+  const placed = new Set();
+  const groups = [];
+
+  for (const g of GROUPS) {
+    const entries = [];
+    for (const cmd of g.commands) {
+      entries.push(entryForCommand(cmd));
+      placed.add(cmd);
+    }
+    groups.push({ id: g.id, title: g.title, summary: '', entries });
+  }
+
+  // Built-in meta-commands we intentionally don't document as API surface.
+  const IGNORED = new Set(['help']);
+
+  // Catch anything the binary exposes that we didn't group — no silent drops.
+  const leftovers = [...discovered].filter(c => !placed.has(c) && !IGNORED.has(c));
+  if (leftovers.length) {
+    process.stderr.write(`WARNING: ungrouped commands -> "Other": ${leftovers.join(', ')}\n`);
+    groups.push({
+      id: 'other',
+      title: 'Other Commands',
+      summary: '',
+      entries: leftovers.map(entryForCommand),
+    });
+  }
+
+  const model = {
+    source: 'cli',
+    package: '@aws/agentcore',
+    version,
+    language: 'cli',
+    groups,
+  };
+  writeFileSync(outPath, JSON.stringify(model, null, 2));
+  process.stderr.write(`Wrote doc-model: ${groups.length} groups, version ${version}\n`);
+}
+
+main();