ci: add API reference docs generation workflow

[notgitika]

Adds a workflow that auto-generates the CLI command reference as AsciiDoc on each release (by scraping agentcore <cmd> --help, grouped by category) and uploads it as a build artifact for the docs team to publish.

Files: workflow + extractor (scripts/extract-cli-model.mjs) + renderer (scripts/render_adoc.py). Runs on release and workflow_dispatch.

[github-actions]

Package Tarball

aws-agentcore-0.22.0.tgz

How to install

gh release download pr-1694-tarball --repo aws/agentcore-cli --pattern "*.tgz" --dir /tmp/pr-tarball
npm install -g /tmp/pr-tarball/aws-agentcore-0.22.0.tgz

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-cli-automation]

Overall the pipeline is straightforward and the shared doc-model design is clean. However, I ran the scripts against the current CLI (mentally, using the source) and found three issues that will materially affect the generated docs. All three are fixable with small changes.

I've left inline comments on the specific lines.

[agentcore-cli-automation]

Bug: this installs @latest, not the version being released.

The release-main-and-preview.yml workflow publishes preview releases with npm publish --tag preview (not latest). This publish-api-docs workflow triggers on release: [published], which fires for both GA and preview GitHub releases. So when a preview release triggers this workflow, npm install -g @aws/agentcore will pull down the previous GA (latest) version, and the docs will be generated for the wrong version — while the --version step below happily reports whatever was installed, giving false confidence.

Options:

1. Install the exact tag from the release event, e.g. npm install -g @aws/agentcore@${{ github.event.release.tag_name }} (strip a leading v if your tags carry one).
2. Only run on GA releases: if: github.event.release.prerelease == false (and drop preview docs entirely).
3. Look up the correct dist-tag from the event and install that.

Option 1 is the most robust.

[agentcore-cli-automation]

Bug: discoverCommands() will always return [] because top-level --help is intercepted.

src/cli/cli.ts attaches a custom program.on('option:help', ...) handler that renders an Ink/React TUI (renderHelp(program)) and then calls process.exit(0). That runs before Commander's default text-based help, so agentcore --help never emits the Commands: block this regex is looking for. Even with CI=1 / no TTY, Ink writes React output, not Commander's formatted text.

Net effect: discoverCommands() returns an empty list, so the "leftovers → Other" safety net at line 186 is a no-op — commands added to the CLI but not added to GROUPS here will be silently dropped, exactly what the comment says this code is trying to prevent.

Options:

1. Invoke discovery via a channel that isn't intercepted — e.g. agentcore help commands or a small AST/program.commands-based dump exposed by the CLI itself.
2. Remove discoverCommands() and instead hard-fail in CI if any command from GROUPS produces empty help output (see other comment) — that's a stricter contract and doesn't rely on top-level help at all.
3. Change the CLI's option:help handler to fall through to the default text help when stdout isn't a TTY, so scripted consumers work.

[agentcore-cli-automation]

Bug: 'eval' and 'recommendations' are phantom commands and will render empty stubs.

Checked against src/cli/cli.ts:

• There is no agentcore eval — the eval subtree is registered under program.command('evals') in src/cli/commands/eval/command.tsx. evals is already listed on the same line, so eval is a duplicate/typo.
• registerRecommendations is defined in src/cli/commands/recommendations/command.tsx but is not imported or called from src/cli/cli.ts. agentcore recommendations doesn't exist as a runnable command today.

Because help() in this script swallows execFileSync errors and returns '' (extract-cli-model.mjs:82–86), and entryForCommand falls back to a synthesized signature agentcore <cmd> [options] (line 127), both of these will produce entries in the generated .adoc with a fake signature and no description, parameters, or examples — silently broken output rather than a build failure.

Options:

1. Remove 'eval' from the evaluation group and remove 'recommendations' from the optimization group (and, separately, decide whether registerRecommendations should be wired up in cli.ts).
2. Make help() fail loudly when the command produces no output containing Usage: — this would have caught both today and will catch future drift automatically.

Ideally, do both — (2) alone would just turn the current silent breakage into a workflow failure at the next release, but (1) fixes it now.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	38.72%	14399 / 37181
🔵	Statements	38.02%	15345 / 40352
🔵	Functions	33.27%	2474 / 7436
🔵	Branches	32.5%	9607 / 29554

Generated in workflow #3993 for commit cc51892 by the Vitest Coverage Report Action

[notgitika]

Thanks for the careful review — addressed in the latest push:

Version pin (workflow): Fixed. Now installs the exact release tag (@aws/agentcore@<tag>) instead of @latest, with a fallback to @latest only for manual workflow_dispatch runs.

eval / recommendations phantoms: Confirmed against the installed CLI and removed both from GROUPS. Also added a fail-loud guard in entryForCommand: if a command's --help doesn't produce a self-describing usage line (Usage: agentcore <name> ...), the extractor throws instead of emitting an empty stub — so phantoms/drift break the build rather than silently generating bad docs.

discoverCommands() returning []: I couldn't reproduce this against the published binary — agentcore --help does emit the Commands: block, and the discovery correctly surfaced evals/help as leftovers in my run. It looks like the built artifact falls through to Commander's text help in a non-TTY/CI context even though the source wires an Ink handler. Given that, plus the new fail-loud guard as a stronger backstop, I've left discovery as-is. Happy to switch to agentcore help commands if you'd prefer to not rely on top-level --help at all.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)