fix: align name constraints with API docs (#701)

- CredentialNameSchema: max 255→128, min 3→1, remove dots (matches CreateApiKeyCredentialProvider API)
- Fix agent name max 64→48 in docs/commands.md, AgentPrimitive.tsx, LLM context files
- Fix credential constraints in docs/configuration.md (3-255→1-128)
- Add API doc links as comments on AgentNameSchema, GatewayNameSchema, CredentialNameSchema, MemoryNameSchema
- Regenerate JSON schema
- Update unit tests for new credential constraints

Author: Hweinstock

docs/commands.md

@@ -195,7 +195,7 @@ agentcore add agent \
 
 | Flag                      | Description                                                                                                                       |
 | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `--name <name>`           | Agent name (alphanumeric, starts with letter, max 64 chars)                                                                       |
+| `--name <name>`           | Agent name (alphanumeric + underscores, starts with letter, max 48 chars)                                                         |
 | `--type <type>`           | `create` (default), `byo`, or `import`                                                                                            |
 | `--build <type>`          | `CodeZip` (default) or `Container` (see [Container Builds](container-builds.md))                                                  |
 | `--language <lang>`       | `Python` (create); `Python`, `TypeScript`, `Other` (BYO)                                                                          |

docs/configuration.md

@@ -272,7 +272,7 @@ Strategy configuration:
 | Field  | Required | Description                         |
 | ------ | -------- | ----------------------------------- |
 | `type` | Yes      | Always `"ApiKeyCredentialProvider"` |
-| `name` | Yes      | Credential name (3-255 chars)       |
+| `name` | Yes      | Credential name (1-128 chars)       |
 
 ### OAuth Credential
 
@@ -288,7 +288,7 @@ Strategy configuration:
 | Field          | Required | Description                                            |
 | -------------- | -------- | ------------------------------------------------------ |
 | `type`         | Yes      | Always `"OAuthCredentialProvider"`                     |
-| `name`         | Yes      | Credential name (3-255 chars)                          |
+| `name`         | Yes      | Credential name (1-128 chars)                          |
 | `discoveryUrl` | Yes      | OIDC discovery URL (must be a valid URL)               |
 | `scopes`       | No       | Array of OAuth scopes                                  |
 | `vendor`       | No       | Credential provider vendor (default: `"CustomOauth2"`) |

src/cli/primitives/AgentPrimitive.tsx

@@ -75,7 +75,6 @@ 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. */
@@ -198,12 +197,15 @@ export class AgentPrimitive extends BasePrimitive<AddAgentOptions, RemovableReso
       .description('Add an agent to the project')
       .option(
         '--name <name>',
-        'Agent name (start with letter, alphanumeric and underscores only, max 48 chars) [non-interactive]'
+        'Agent name (start with letter, alphanumeric + underscores, 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, GoogleADK, OpenAIAgents [non-interactive]')
+      .option(
+        '--framework <fw>',
+        'Framework: Strands, LangChain_LangGraph, CrewAI, 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/schema/llm-compacted/AGENTS.md

@@ -44,7 +44,7 @@ Incorrect enums or regex will cause agents to generate invalid JSON that fails v
 ### Constraint Comments
 
 ```typescript
-name: string; // @regex ^[a-zA-Z][a-zA-Z0-9]{0,63}$ @max 64
+name: string; // @regex ^[a-zA-Z][a-zA-Z0-9]{0,63}$ @max 48
 eventExpiryDuration: number; // @min 7 @max 365 (days)
 targets: Target[]; // @min 1 - at least one required
 ```

src/schema/llm-compacted/agentcore.ts

@@ -91,5 +91,5 @@ interface MemoryStrategy {
 
 interface Credential {
   type: 'ApiKeyCredentialProvider';
-  name: string; // @regex ^[A-Za-z0-9_.-]+$ @min 3 @max 255
+  name: string; // @regex ^[a-zA-Z0-9\-_]+$ @min 1 @max 128
 }

src/schema/schemas/__tests__/agentcore-project.test.ts

@@ -224,17 +224,25 @@ describe('MemorySchema', () => {
 describe('CredentialNameSchema', () => {
   it('accepts valid credential names', () => {
     expect(CredentialNameSchema.safeParse('MyProjectGemini').success).toBe(true);
-    expect(CredentialNameSchema.safeParse('api-key.v2').success).toBe(true);
+    expect(CredentialNameSchema.safeParse('api-key-v2').success).toBe(true);
     expect(CredentialNameSchema.safeParse('my_cred_123').success).toBe(true);
   });
 
-  it('rejects names shorter than 3 characters', () => {
-    expect(CredentialNameSchema.safeParse('ab').success).toBe(false);
-    expect(CredentialNameSchema.safeParse('a').success).toBe(false);
+  it('accepts single character name (min 1)', () => {
+    expect(CredentialNameSchema.safeParse('a').success).toBe(true);
   });
 
-  it('accepts name with exactly 3 characters', () => {
-    expect(CredentialNameSchema.safeParse('abc').success).toBe(true);
+  it('rejects empty name', () => {
+    expect(CredentialNameSchema.safeParse('').success).toBe(false);
+  });
+
+  it('rejects names longer than 128 characters', () => {
+    expect(CredentialNameSchema.safeParse('a'.repeat(128)).success).toBe(true);
+    expect(CredentialNameSchema.safeParse('a'.repeat(129)).success).toBe(false);
+  });
+
+  it('rejects names with dots', () => {
+    expect(CredentialNameSchema.safeParse('api-key.v2').success).toBe(false);
   });
 
   it('rejects names with spaces', () => {

src/schema/schemas/agent-env.ts

@@ -22,6 +22,7 @@ export type { PythonRuntime, NodeRuntime, RuntimeVersion, NetworkMode, ProtocolM
 // Name Schemas
 // ============================================================================
 
+// https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateAgentRuntime.html
 export const AgentNameSchema = z
   .string()
   .min(1, 'Name is required')
@@ -40,6 +41,7 @@ export const EnvVarNameSchema = z
     'Must start with a letter or underscore, contain only letters, digits, and underscores'
   );
 
+// https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateGateway.html
 export const GatewayNameSchema = z
   .string()
   .min(1)

src/schema/schemas/agentcore-project.ts

@@ -56,6 +56,8 @@ export { AgentCoreGatewaySchema, AgentCoreGatewayTargetSchema, AgentCoreMcpRunti
 // Project Name Schema
 // ============================================================================
 
+// Project name is a CLI-only concept (combined with agent name to form the runtime name).
+// Max 23 so that projectName + "_" + agentName fits within the 48-char runtime name limit.
 export const ProjectNameSchema = z
   .string()
   .min(1, 'Project name is required')
@@ -75,6 +77,8 @@ export const ProjectNameSchema = z
 export const MemoryTypeSchema = z.literal('AgentCoreMemory');
 export type MemoryType = z.infer<typeof MemoryTypeSchema>;
 
+// Memory names follow the same constraints as agent runtime names.
+// https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateMemory.html
 export const MemoryNameSchema = z
   .string()
   .min(1, 'Name is required')
@@ -108,14 +112,12 @@ export type Memory = z.infer<typeof MemorySchema>;
 // Credential Schema
 // ============================================================================
 
+// https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateApiKeyCredentialProvider.html
 export const CredentialNameSchema = z
   .string()
-  .min(3, 'Credential name must be at least 3 characters')
-  .max(255)
-  .regex(
-    /^[A-Za-z0-9_.-]+$/,
-    'Must contain only alphanumeric characters, underscores, dots, and hyphens (3-255 chars)'
-  );
+  .min(1, 'Credential name is required')
+  .max(128, 'Credential name must be 128 characters or less')
+  .regex(/^[a-zA-Z0-9\-_]+$/, 'Must contain only alphanumeric characters, hyphens, and underscores (1-128 chars)');
 
 export const CredentialTypeSchema = z.enum(['ApiKeyCredentialProvider', 'OAuthCredentialProvider']);
 export type CredentialType = z.infer<typeof CredentialTypeSchema>;