fix(cli): Author docs/insights.md per recommendations.md shape and ... (#1578)

[aidandaly24]

Refs aws#1578

Issues

• docs: write docs/insights.md aws/agentcore-cli#1578 — Nothing functionally breaks. The Insights feature works end to end, but it has no dedicated docs/insights.md guide even though the README Insights [preview] section and docs index point readers toward per-feature docs (as recommendations.md has). Users exploring the feature get the command table in the README but no walkthrough, options reference, or output-schema doc. Separately, the TUI copy (copy.ts) advertised run-insights flags -i and --lookback that the command never registers.

Root cause

Verified directly: docs/insights.md absent (ls/find), docs/recommendations.md present, README.md:156-168/318 state confirmed, PR aws#1577 (954b97b) git show --stat shows only README.md + AGENTS.md, all cited command/primitive/operation files read and confirmed real at HEAD e92c79a. The copy.ts run-insights examples used -i FailureAnalysis and --lookback 7, but run insights registers --insights and -d, --lookback-days only.

The fix

Author docs/insights.md per recommendations.md shape and add README docs-index link; correct the real flags to --insights Builtin.Insight.FailureAnalysis and --lookback-days in copy.ts; add a regression test guarding the corrected copy.

Files touched: NEW docs/insights.md (model: docs/recommendations.md); README.md docs index ~line 318 (Evaluation & quality block); src/cli/tui/copy.ts:130-148; NEW src/cli/tui/tests/run-insights-copy.test.ts

Validation evidence

The fix was verified by reproducing the original symptom and re-running after the change:

BEFORE (original copy.ts run-insights examples used -i FailureAnalysis and --lookback 7): running the advertised example against the real built CLI -> node dist/cli/index.mjs run insights -r MyAgent -i FailureAnalysis --lookback 7 returns error: unknown option '-i' (and --lookback is also unregistered). The TUI copy/docs drift advertised flags the run insights command never registers. AFTER (fixed copy uses --insights Builtin.Insight.FailureAnalysis --lookback-days 7): node dist/cli/index.mjs run insights -r MyAgent --insights Builtin.Insight.FailureAnalysis --lookback-days 7 produces NO unknown-option error; the real parser accepts every flag. run insights --help confirms registered flags are --insights and -d, --lookback-days (no -i, no --lookback). Adversarial test proof: temporarily reverting copy.ts to the broken examples makes the new regression test src/cli/tui/tests/run-insights-copy.test.ts FAIL on BOTH assertions (unknown -i token + --lookback token), and it PASSES once restored — so the test genuinely guards the symptom.

Test suite: green.

---

Staged on the fork as a draft for human review. Promote to aws/agentcore-cli after vetting.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	37.16%	13593 / 36577
🔵	Statements	36.43%	14452 / 39667
🔵	Functions	31.8%	2333 / 7336
🔵	Branches	31.1%	9000 / 28932

Generated in workflow #115 for commit 1c60760 by the Vitest Coverage Report Action