fix(cli): correct inaccurate --help text across all commands

Audit and fix help text for all CLI commands and primitives:

- Fix agent name constraints: "max 64 chars" → "max 48 chars",
  add "underscores" to allowed characters
- Fix project name constraint: "max 36 chars" → "max 23 chars"
- Remove CrewAI from framework lists (not user-accessible)
- Fix "Remove a agent" → "Remove an agent" grammar
- Add missing resource types (evaluator, online-eval) to status --type
- Remove phantom 'edit' command from COMMAND_DESCRIPTIONS
- Remove false --agent-arn claim from evals description
- Add [non-interactive] markers to all options missing them in
  EvaluatorPrimitive, GatewayPrimitive, GatewayTargetPrimitive,
  and PolicyEnginePrimitive
- Improve gateway and gateway-target help descriptions for clarity
- Update AGENTS.md to match current CLI reality

Constraint: Help text and Zod schemas are defined in separate files with no shared constant
Confidence: high
Scope-risk: narrow
Not-tested: Interactive TUI mode (only CLI --help verified)

Author: aidandaly24

AGENTS.md

@@ -24,14 +24,17 @@ Note: CDK L3 constructs are in a separate package `@aws/agentcore-cdk`.
 ## CLI Commands
 
 - `create` - Create new AgentCore project
-- `add` - Add resources (agent, memory, identity, evaluator, online-eval, target)
-- `remove` - Remove resources (agent, memory, identity, evaluator, online-eval, target, all)
+- `add` - Add resources (agent, memory, identity, evaluator, online-eval, gateway, gateway-target, policy-engine,
+  policy)
+- `remove` - Remove resources (agent, memory, identity, evaluator, online-eval, gateway, gateway-target, policy-engine,
+  policy, all)
 - `deploy` - Deploy infrastructure to AWS
 - `status` - Check deployment status
 - `dev` - Local development server (CodeZip: uvicorn with hot-reload; Container: Docker build + run with volume mount)
 - `invoke` - Invoke agents (local or deployed)
 - `run eval` - Run on-demand evaluation against agent sessions
 - `evals history` - View past eval run results
+- `fetch access` - Fetch access info for a deployed gateway
 - `pause online-eval` - Pause (disable) a deployed online eval config
 - `resume online-eval` - Resume (enable) a paused online eval config
 - `logs` - Stream or search agent runtime logs
@@ -45,8 +48,7 @@ Note: CDK L3 constructs are in a separate package `@aws/agentcore-cdk`.
 
 ### Agent Types
 
-- **Template agents**: Created from framework templates (Strands, LangChain_LangGraph, CrewAI, GoogleADK, OpenAIAgents,
-  AutoGen)
+- **Template agents**: Created from framework templates (Strands, LangChain_LangGraph, GoogleADK, OpenAIAgents)
 - **BYO agents**: Bring your own code with `agentcore add agent --type byo`
 - **Imported agents**: Import from Bedrock Agents with `agentcore add agent --type import`
 
@@ -58,10 +60,10 @@ Note: CDK L3 constructs are in a separate package `@aws/agentcore-cdk`.
 
 ## Primitives Architecture
 
-All resource types (agent, memory, identity, evaluator, online-eval, gateway, mcp-tool) are modeled as **primitives** --
-self-contained classes in `src/cli/primitives/` that own the full add/remove lifecycle for their resource type.
-Resources support config-driven tagging via `agentcore.json` and `mcp.json`, with tags flowing through to deployed
-CloudFormation resources.
+All resource types (agent, memory, identity, evaluator, online-eval, gateway, gateway-target, policy-engine, policy) are
+modeled as **primitives** -- self-contained classes in `src/cli/primitives/` that own the full add/remove lifecycle for
+their resource type. Resources support config-driven tagging via `agentcore.json` and `mcp.json`, with tags flowing
+through to deployed CloudFormation resources.
 
 Each primitive extends `BasePrimitive` and implements: `add()`, `remove()`, `previewRemove()`, `getRemovable()`,
 `registerCommands()`, and `addScreen()`.
@@ -73,8 +75,10 @@ Current primitives:
 - `CredentialPrimitive` — credential/identity creation, .env management, removal
 - `EvaluatorPrimitive` — custom evaluator creation/removal with cross-reference validation
 - `OnlineEvalConfigPrimitive` — online eval config creation/removal
-- `GatewayPrimitive` — MCP gateway creation/removal
-- `GatewayTargetPrimitive` — MCP tool creation/removal with code generation
+- `GatewayPrimitive` — gateway creation/removal
+- `GatewayTargetPrimitive` — gateway target creation/removal with code generation
+- `PolicyEnginePrimitive` — Cedar policy engine creation/removal
+- `PolicyPrimitive` — Cedar policy creation/removal within policy engines
 
 Singletons are created in `registry.ts` and wired into CLI commands via `cli.ts`. See `src/cli/AGENTS.md` for details on
 adding new primitives.

src/cli/commands/create/command.tsx

@@ -159,14 +159,14 @@ export const registerCreate = (program: Command) => {
   program
     .command('create')
     .description(COMMAND_DESCRIPTIONS.create)
-    .option('--name <name>', 'Project name (start with letter, alphanumeric only, max 36 chars) [non-interactive]')
+    .option('--name <name>', 'Project name (start with letter, alphanumeric only, max 23 chars) [non-interactive]')
     .option('--no-agent', 'Skip agent creation [non-interactive]')
     .option('--defaults', 'Use defaults (Python, Strands, Bedrock, no memory) [non-interactive]')
     .option('--build <type>', 'Build type: CodeZip or Container (default: CodeZip) [non-interactive]')
     .option('--language <language>', 'Target language (default: Python) [non-interactive]')
     .option(
       '--framework <framework>',
-      'Agent framework (Strands, LangChain_LangGraph, CrewAI, GoogleADK, OpenAIAgents) [non-interactive]'
+      'Agent framework (Strands, LangChain_LangGraph, GoogleADK, OpenAIAgents) [non-interactive]'
     )
     .option('--model-provider <provider>', 'Model provider (Bedrock, Anthropic, OpenAI, Gemini) [non-interactive]')
     .option('--api-key <key>', 'API key for non-Bedrock providers [non-interactive]')

src/cli/commands/status/command.tsx

@@ -56,7 +56,10 @@ export const registerStatus = (program: Command) => {
     .description(COMMAND_DESCRIPTIONS.status)
     .option('--agent-runtime-id <id>', 'Look up a specific agent runtime by ID')
     .option('--target <name>', 'Select deployment target')
-    .option('--type <type>', 'Filter by resource type (agent, memory, credential, gateway, policy-engine, policy)')
+    .option(
+      '--type <type>',
+      'Filter by resource type (agent, memory, credential, gateway, evaluator, online-eval, policy-engine, policy)'
+    )
     .option('--state <state>', 'Filter by deployment state (deployed, local-only, pending-removal)')
     .option('--agent <name>', 'Filter to a specific agent')
     .option('--json', 'Output as JSON')

src/cli/primitives/AgentPrimitive.tsx

@@ -75,6 +75,7 @@ export interface AddAgentOptions extends VpcOptions {
 export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableResource> {
   readonly kind = 'agent';
   readonly label = 'Agent';
+  protected override readonly article = 'an';
   readonly primitiveSchema = AgentEnvSpecSchema;
 
   /** Local instance to avoid circular dependency with registry. */
@@ -195,14 +196,14 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
     addCmd
       .command('agent')
       .description('Add an agent to the project')
-      .option('--name <name>', 'Agent name (start with letter, alphanumeric only, max 64 chars) [non-interactive]')
+      .option(
+        '--name <name>',
+        'Agent name (start with letter, alphanumeric and underscores only, max 48 chars) [non-interactive]'
+      )
       .option('--type <type>', 'Agent type: create, byo, or import [non-interactive]', 'create')
       .option('--build <type>', 'Build type: CodeZip or Container (default: CodeZip) [non-interactive]')
       .option('--language <lang>', 'Language: Python (create), or Python/TypeScript/Other (BYO) [non-interactive]')
-      .option(
-        '--framework <fw>',
-        'Framework: Strands, LangChain_LangGraph, CrewAI, GoogleADK, OpenAIAgents [non-interactive]'
-      )
+      .option('--framework <fw>', 'Framework: Strands, LangChain_LangGraph, GoogleADK, OpenAIAgents [non-interactive]')
       .option('--model-provider <provider>', 'Model provider: Bedrock, Anthropic, OpenAI, Gemini [non-interactive]')
       .option('--api-key <key>', 'API key for non-Bedrock providers [non-interactive]')
       .option('--memory <mem>', 'Memory: none, shortTerm, longAndShortTerm (create path only) [non-interactive]')

src/cli/primitives/EvaluatorPrimitive.ts

@@ -124,19 +124,22 @@ export class EvaluatorPrimitive extends BasePrimitive<AddEvaluatorOptions, Remov
     addCmd
       .command(this.kind)
       .description('Add a custom evaluator to the project')
-      .option('--name <name>', 'Evaluator name')
-      .option('--level <level>', 'Evaluation level: SESSION, TRACE, TOOL_CALL')
-      .option('--model <model>', 'Bedrock model ID for LLM-as-a-Judge')
+      .option('--name <name>', 'Evaluator name [non-interactive]')
+      .option('--level <level>', 'Evaluation level: SESSION, TRACE, TOOL_CALL [non-interactive]')
+      .option('--model <model>', 'Bedrock model ID for LLM-as-a-Judge [non-interactive]')
       .option(
         '--instructions <text>',
-        'Evaluation prompt instructions (must include level-appropriate placeholders, e.g. {context})'
+        'Evaluation prompt instructions (must include level-appropriate placeholders, e.g. {context}) [non-interactive]'
+      )
+      .option(
+        '--rating-scale <preset>',
+        `Rating scale preset: ${presetIds.join(', ')} (default: 1-5-quality) [non-interactive]`
       )
-      .option('--rating-scale <preset>', `Rating scale preset: ${presetIds.join(', ')} (default: 1-5-quality)`)
       .option(
         '--config <path>',
-        'Path to evaluator config JSON file (overrides --model, --instructions, --rating-scale)'
+        'Path to evaluator config JSON file (overrides --model, --instructions, --rating-scale) [non-interactive]'
       )
-      .option('--json', 'Output as JSON')
+      .option('--json', 'Output as JSON [non-interactive]')
       .action(
         async (cliOptions: {
           name?: string;

src/cli/primitives/GatewayPrimitive.ts

@@ -158,23 +158,27 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
   registerCommands(addCmd: Command, removeCmd: Command): void {
     addCmd
       .command('gateway')
-      .description('Add a gateway to the project')
-      .option('--name <name>', 'Gateway name')
-      .option('--description <desc>', 'Gateway description')
-      .option('--authorizer-type <type>', 'Authorizer type: NONE or CUSTOM_JWT')
-      .option('--discovery-url <url>', 'OIDC discovery URL (for CUSTOM_JWT)')
-      .option('--allowed-audience <audience>', 'Comma-separated allowed audiences (for CUSTOM_JWT)')
-      .option('--allowed-clients <clients>', 'Comma-separated allowed client IDs (for CUSTOM_JWT)')
-      .option('--allowed-scopes <scopes>', 'Comma-separated allowed scopes (for CUSTOM_JWT)')
-      .option('--custom-claims <json>', 'Custom claim validations as JSON array (for CUSTOM_JWT)')
-      .option('--client-id <id>', 'OAuth client ID for gateway bearer token')
-      .option('--client-secret <secret>', 'OAuth client secret')
-      .option('--agents <agents>', 'Comma-separated agent names')
-      .option('--no-semantic-search', 'Disable semantic search for tool discovery')
-      .option('--exception-level <level>', 'Exception verbosity level', 'NONE')
-      .option('--policy-engine <name>', 'Policy engine name for Cedar-based authorization')
-      .option('--policy-engine-mode <mode>', 'Policy engine mode: LOG_ONLY or ENFORCE')
-      .option('--json', 'Output as JSON')
+      .description('Add an API gateway that routes requests to agent targets')
+      .option('--name <name>', 'Gateway name [non-interactive]')
+      .option('--description <desc>', 'Gateway description [non-interactive]')
+      .option('--agents <agents>', 'Comma-separated agent names to expose through this gateway [non-interactive]')
+      .option('--authorizer-type <type>', 'Authorizer type: NONE or CUSTOM_JWT [non-interactive]')
+      .option('--discovery-url <url>', 'OIDC discovery URL (for CUSTOM_JWT) [non-interactive]')
+      .option('--allowed-audience <audience>', 'Comma-separated allowed audiences (for CUSTOM_JWT) [non-interactive]')
+      .option('--allowed-clients <clients>', 'Comma-separated allowed client IDs (for CUSTOM_JWT) [non-interactive]')
+      .option('--allowed-scopes <scopes>', 'Comma-separated allowed scopes (for CUSTOM_JWT) [non-interactive]')
+      .option('--custom-claims <json>', 'Custom claim validations as JSON array (for CUSTOM_JWT) [non-interactive]')
+      .option('--client-id <id>', 'OAuth client ID for fetching gateway bearer tokens [non-interactive]')
+      .option('--client-secret <secret>', 'OAuth client secret for fetching gateway bearer tokens [non-interactive]')
+      .option('--no-semantic-search', 'Disable semantic search for gateway target tool discovery [non-interactive]')
+      .option(
+        '--exception-level <level>',
+        'Exception detail level in error responses: NONE, ALL [non-interactive]',
+        'NONE'
+      )
+      .option('--policy-engine <name>', 'Policy engine name for Cedar-based authorization [non-interactive]')
+      .option('--policy-engine-mode <mode>', 'Policy engine mode: LOG_ONLY or ENFORCE [non-interactive]')
+      .option('--json', 'Output as JSON [non-interactive]')
       .action(async (rawOptions: Record<string, string | boolean | undefined>) => {
         const cliOptions = rawOptions as unknown as CLIAddGatewayOptions;
         try {
@@ -238,9 +242,9 @@ export class GatewayPrimitive extends BasePrimitive<AddGatewayOptions, Removable
     removeCmd
       .command('gateway')
       .description('Remove a gateway from the project')
-      .option('--name <name>', 'Name of resource to remove')
-      .option('--force', 'Skip confirmation prompt')
-      .option('--json', 'Output as JSON')
+      .option('--name <name>', 'Name of resource to remove [non-interactive]')
+      .option('--force', 'Skip confirmation prompt [non-interactive]')
+      .option('--json', 'Output as JSON [non-interactive]')
       .action(async (cliOptions: { name?: string; force?: boolean; json?: boolean }) => {
         try {
           if (!findConfigRoot()) {

src/cli/primitives/GatewayTargetPrimitive.ts

@@ -245,35 +245,50 @@ export class GatewayTargetPrimitive extends BasePrimitive<AddGatewayTargetOption
   registerCommands(addCmd: Command, removeCmd: Command): void {
     addCmd
       .command('gateway-target')
-      .description('Add a gateway target to the project')
-      .option('--name <name>', 'Target name')
-      .option('--description <desc>', 'Target description')
+      .description('Add a target (API, MCP server, Lambda) to a gateway for tool routing')
+      .option('--name <name>', 'Target name [non-interactive]')
+      .option('--description <desc>', 'Target description [non-interactive]')
+      .option('--gateway <name>', 'Gateway to attach this target to [non-interactive]')
       .option(
         '--type <type>',
-        'Target type (required): mcp-server, api-gateway, open-api-schema, smithy-model, lambda-function-arn'
+        'Target type (required): mcp-server, api-gateway, open-api-schema, smithy-model, lambda-function-arn [non-interactive]'
       )
-      .option('--endpoint <url>', 'MCP server endpoint URL')
-      .option('--language <lang>', 'Language: Python, TypeScript, Other')
-      .option('--gateway <name>', 'Gateway name')
-      .option('--host <host>', 'Compute host: Lambda or AgentCoreRuntime')
-      .option('--outbound-auth <type>', 'Outbound auth type: oauth, api-key, or none')
-      .option('--credential-name <name>', 'Existing credential name for outbound auth')
-      .option('--oauth-client-id <id>', 'OAuth client ID (creates credential inline)')
-      .option('--oauth-client-secret <secret>', 'OAuth client secret (creates credential inline)')
-      .option('--oauth-discovery-url <url>', 'OAuth discovery URL (creates credential inline)')
-      .option('--oauth-scopes <scopes>', 'OAuth scopes, comma-separated')
-      .option('--rest-api-id <id>', 'API Gateway REST API ID (required for api-gateway type)')
-      .option('--stage <stage>', 'API Gateway deployment stage (required for api-gateway type)')
-      .option('--tool-filter-path <path>', 'Tool filter path pattern, e.g. /pets/*')
-      .option('--tool-filter-methods <methods>', 'Comma-separated HTTP methods, e.g. GET,POST')
+      .option('--endpoint <url>', 'Server endpoint URL (for mcp-server type) [non-interactive]')
+      .option('--language <lang>', 'Language of target code: Python, TypeScript, Other [non-interactive]')
+      .option('--host <host>', 'Where to run the target: Lambda or AgentCoreRuntime [non-interactive]')
+      .option('--outbound-auth <type>', 'Outbound auth type: oauth, api-key, or none [non-interactive]')
+      .option('--credential-name <name>', 'Existing credential name for outbound auth [non-interactive]')
+      .option(
+        '--oauth-client-id <id>',
+        'OAuth client ID — creates credential inline (for oauth auth) [non-interactive]'
+      )
+      .option(
+        '--oauth-client-secret <secret>',
+        'OAuth client secret — creates credential inline (for oauth auth) [non-interactive]'
+      )
+      .option(
+        '--oauth-discovery-url <url>',
+        'OAuth discovery URL — creates credential inline (for oauth auth) [non-interactive]'
+      )
+      .option('--oauth-scopes <scopes>', 'OAuth scopes, comma-separated (for oauth auth) [non-interactive]')
+      .option('--rest-api-id <id>', 'REST API ID (for api-gateway type) [non-interactive]')
+      .option('--stage <stage>', 'Deployment stage (for api-gateway type) [non-interactive]')
+      .option('--tool-filter-path <path>', 'Tool filter path pattern, e.g. /pets/* [non-interactive]')
+      .option('--tool-filter-methods <methods>', 'Comma-separated HTTP methods, e.g. GET,POST [non-interactive]')
       .option(
         '--schema <path>',
-        'Path to schema file (relative to project root) or S3 URI (for open-api-schema / smithy-model)'
+        'Schema file path or S3 URI (for open-api-schema / smithy-model type) [non-interactive]'
+      )
+      .option(
+        '--schema-s3-account <id>',
+        'S3 bucket owner account ID for cross-account access (for schema on S3) [non-interactive]'
+      )
+      .option('--lambda-arn <arn>', 'Lambda function ARN (for lambda-function-arn type) [non-interactive]')
+      .option(
+        '--tool-schema-file <path>',
+        'Tool schema JSON file path (for lambda-function-arn type) [non-interactive]'
       )
-      .option('--schema-s3-account <id>', 'S3 bucket owner account ID (for cross-account access)')
-      .option('--lambda-arn <arn>', 'Lambda function ARN (required for lambda-function-arn type)')
-      .option('--tool-schema-file <path>', 'Path to tool schema JSON file (required for lambda-function-arn type)')
-      .option('--json', 'Output as JSON')
+      .option('--json', 'Output as JSON [non-interactive]')
       .action(async (rawOptions: Record<string, string | boolean | undefined>) => {
         // Commander camelCases --outbound-auth to outboundAuth, but our types use outboundAuthType
         if (rawOptions.outboundAuth && !rawOptions.outboundAuthType) {
@@ -464,9 +479,9 @@ export class GatewayTargetPrimitive extends BasePrimitive<AddGatewayTargetOption
     removeCmd
       .command('gateway-target')
       .description('Remove a gateway target from the project')
-      .option('--name <name>', 'Name of resource to remove')
-      .option('--force', 'Skip confirmation prompt')
-      .option('--json', 'Output as JSON')
+      .option('--name <name>', 'Name of resource to remove [non-interactive]')
+      .option('--force', 'Skip confirmation prompt [non-interactive]')
+      .option('--json', 'Output as JSON [non-interactive]')
       .action(async (cliOptions: { name?: string; force?: boolean; json?: boolean }) => {
         try {
           if (!findConfigRoot()) {

src/cli/primitives/PolicyEnginePrimitive.ts

@@ -205,8 +205,11 @@ export class PolicyEnginePrimitive extends BasePrimitive<AddPolicyEngineOptions,
       .option('--name <name>', 'Policy engine name [non-interactive]')
       .option('--description <desc>', 'Policy engine description [non-interactive]')
       .option('--encryption-key-arn <arn>', 'KMS encryption key ARN [non-interactive]')
-      .option('--attach-to-gateways <gateways>', 'Comma-separated gateway names to attach this engine to')
-      .option('--attach-mode <mode>', 'Enforcement mode for attached gateways: LOG_ONLY or ENFORCE')
+      .option(
+        '--attach-to-gateways <gateways>',
+        'Comma-separated gateway names to attach this engine to [non-interactive]'
+      )
+      .option('--attach-mode <mode>', 'Enforcement mode for attached gateways: LOG_ONLY or ENFORCE [non-interactive]')
       .option('--json', 'Output as JSON [non-interactive]')
       .action(
         async (cliOptions: {