fix(schema): refresh llm-compacted context (#1894)

* fix(schema): refresh llm-compacted context

* fix(deps): patch audited transitive dependencies

* docs: include insights in project schema summary

Author: tejaskash

src/assets/AGENTS.md

@@ -57,4 +57,4 @@ For Container builds, `BaseRenderer.render()` automatically copies the `containe
 
 - These assets are rendered by the CLI's template renderer in `src/cli/templates/`
 - The `README.md` and `agents/AGENTS.md` are copied verbatim (no template rendering) during project creation
-- The `.llm-context/` files are sourced from `src/schema/llm-compacted/` and written during init
+- The `.llm-context/` files are sourced from `src/schema/llm-compacted/` and written during project creation

src/assets/README.md

@@ -13,8 +13,7 @@ my-project/
 │   ├── .env.local          # Secrets — API keys (gitignored)
 │   ├── .llm-context/       # TypeScript type definitions for AI assistants
 │   │   ├── agentcore.ts    # AgentCoreProjectSpec types
-│   │   ├── aws-targets.ts  # Deployment target types
-│   │   └── mcp.ts          # Gateway and MCP tool types
+│   │   └── aws-targets.ts  # Deployment target types
 │   └── cdk/                # CDK infrastructure (@aws/agentcore-cdk)
 ├── app/                    # Agent application code
 └── evaluators/             # Custom evaluator code (if any)

src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap

@@ -7336,7 +7336,7 @@ For Container builds, \`BaseRenderer.render()\` automatically copies the \`conta
 
 - These assets are rendered by the CLI's template renderer in \`src/cli/templates/\`
 - The \`README.md\` and \`agents/AGENTS.md\` are copied verbatim (no template rendering) during project creation
-- The \`.llm-context/\` files are sourced from \`src/schema/llm-compacted/\` and written during init
+- The \`.llm-context/\` files are sourced from \`src/schema/llm-compacted/\` and written during project creation
 "
 `;
 
@@ -7356,8 +7356,7 @@ my-project/
 │   ├── .env.local          # Secrets — API keys (gitignored)
 │   ├── .llm-context/       # TypeScript type definitions for AI assistants
 │   │   ├── agentcore.ts    # AgentCoreProjectSpec types
-│   │   ├── aws-targets.ts  # Deployment target types
-│   │   └── mcp.ts          # Gateway and MCP tool types
+│   │   └── aws-targets.ts  # Deployment target types
 │   └── cdk/                # CDK infrastructure (@aws/agentcore-cdk)
 ├── app/                    # Agent application code
 └── evaluators/             # Custom evaluator code (if any)
@@ -7494,8 +7493,7 @@ myProject/
 │   ├── .llm-context/       # TypeScript type definitions for AI assistants
 │   │   ├── README.md       # Guide to using schema files
 │   │   ├── agentcore.ts    # AgentCoreProjectSpec types
-│   │   ├── aws-targets.ts  # AWS deployment target types
-│   │   └── mcp.ts          # Gateway and MCP tool types
+│   │   └── aws-targets.ts  # AWS deployment target types
 │   └── cdk/                # AWS CDK project (@aws/agentcore-cdk L3 constructs)
 ├── app/                    # Agent application code
 └── evaluators/             # Custom evaluator code (if any)
@@ -7509,12 +7507,11 @@ file maps to a JSON config file and includes validation constraints as comments
 | JSON Config | Schema File | Root Type |
 | --- | --- | --- |
 | \`agentcore/agentcore.json\` | \`agentcore/.llm-context/agentcore.ts\` | \`AgentCoreProjectSpec\` |
-| \`agentcore/agentcore.json\` (gateways) | \`agentcore/.llm-context/mcp.ts\` | \`AgentCoreMcpSpec\` |
 | \`agentcore/aws-targets.json\` | \`agentcore/.llm-context/aws-targets.ts\` | \`AwsDeploymentTarget[]\` |
 
 ### Key Types
 
-- **AgentCoreProjectSpec**: Root config with \`runtimes\`, \`memories\`, \`credentials\`, \`agentCoreGateways\`, \`evaluators\`, \`onlineEvalConfigs\`, \`onlineInsightsConfigs\`, \`knowledgeBases\`, \`harnesses\`, \`policyEngines\`, \`policies\`, \`payments\` (managers + connectors), \`configBundles\`, \`datasets\`, \`runtimeEndpoints\` arrays
+- **AgentCoreProjectSpec**: Root config with runtimes, memories, knowledge bases, credentials, evaluators, online evals and insights, gateways, policy engines, config bundles, A/B tests, harness registrations, datasets, and payment managers
 - **AgentEnvSpec**: Agent configuration (build type, entrypoint, code location, runtime version, network mode)
 - **Memory**: Memory resource with strategies (SEMANTIC, SUMMARIZATION, USER_PREFERENCE, EPISODIC) and expiry
 - **Credential**: API key or OAuth credential provider

src/assets/agents/AGENTS.md

@@ -38,8 +38,7 @@ myProject/
 │   ├── .llm-context/       # TypeScript type definitions for AI assistants
 │   │   ├── README.md       # Guide to using schema files
 │   │   ├── agentcore.ts    # AgentCoreProjectSpec types
-│   │   ├── aws-targets.ts  # AWS deployment target types
-│   │   └── mcp.ts          # Gateway and MCP tool types
+│   │   └── aws-targets.ts  # AWS deployment target types
 │   └── cdk/                # AWS CDK project (@aws/agentcore-cdk L3 constructs)
 ├── app/                    # Agent application code
 └── evaluators/             # Custom evaluator code (if any)
@@ -53,12 +52,11 @@ file maps to a JSON config file and includes validation constraints as comments
 | JSON Config | Schema File | Root Type |
 | --- | --- | --- |
 | `agentcore/agentcore.json` | `agentcore/.llm-context/agentcore.ts` | `AgentCoreProjectSpec` |
-| `agentcore/agentcore.json` (gateways) | `agentcore/.llm-context/mcp.ts` | `AgentCoreMcpSpec` |
 | `agentcore/aws-targets.json` | `agentcore/.llm-context/aws-targets.ts` | `AwsDeploymentTarget[]` |
 
 ### Key Types
 
-- **AgentCoreProjectSpec**: Root config with `runtimes`, `memories`, `credentials`, `agentCoreGateways`, `evaluators`, `onlineEvalConfigs`, `onlineInsightsConfigs`, `knowledgeBases`, `harnesses`, `policyEngines`, `policies`, `payments` (managers + connectors), `configBundles`, `datasets`, `runtimeEndpoints` arrays
+- **AgentCoreProjectSpec**: Root config with runtimes, memories, knowledge bases, credentials, evaluators, online evals and insights, gateways, policy engines, config bundles, A/B tests, harness registrations, datasets, and payment managers
 - **AgentEnvSpec**: Agent configuration (build type, entrypoint, code location, runtime version, network mode)
 - **Memory**: Memory resource with strategies (SEMANTIC, SUMMARIZATION, USER_PREFERENCE, EPISODIC) and expiry
 - **Credential**: API key or OAuth credential provider

src/cli/templates/__tests__/schema-assets.test.ts

@@ -0,0 +1,35 @@
+import { AgentCoreProjectSpecSchema, AgentCoreRegionSchema } from '../../../schema';
+import { LLM_CONTEXT_FILES } from '../schema-assets';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+
+function projectSpecFields(source: string): string[] {
+  const match = /interface AgentCoreProjectSpec \{([\s\S]*?)\n\}/.exec(source);
+  if (!match?.[1]) {
+    throw new Error('Missing AgentCoreProjectSpec interface');
+  }
+
+  return [...match[1].matchAll(/^ {2}([$A-Za-z_][$\w]*)\??:/gm)].map(field => field[1]!);
+}
+
+describe('LLM_CONTEXT_FILES', () => {
+  it('vends only the current project context files', () => {
+    expect(Object.keys(LLM_CONTEXT_FILES).sort()).toEqual(['README.md', 'agentcore.ts', 'aws-targets.ts']);
+    expect(LLM_CONTEXT_FILES['README.md']).not.toContain('mcp.ts');
+  });
+
+  it('documents every supported agentcore.json top-level field', () => {
+    const jsonSchema = z.toJSONSchema(AgentCoreProjectSpecSchema, { target: 'draft-07' });
+    const schemaFields = Object.keys(jsonSchema.properties ?? {}).filter(field => field !== 'httpGateways');
+
+    expect(projectSpecFields(LLM_CONTEXT_FILES['agentcore.ts']!)).toEqual(schemaFields);
+  });
+
+  it('documents every supported AgentCore region', () => {
+    const regionSource = LLM_CONTEXT_FILES['aws-targets.ts']!;
+    const regionType = /type AgentCoreRegion =([\s\S]*?);/.exec(regionSource)?.[1];
+    const documentedRegions = [...(regionType ?? '').matchAll(/'([^']+)'/g)].map(match => match[1]);
+
+    expect(documentedRegions).toEqual(AgentCoreRegionSchema.options);
+  });
+});

src/cli/templates/schema-assets.ts

@@ -1,10 +1,10 @@
 /**
  * LLM-compacted schema files embedded at build time.
- * Written to agentcore/.llm-context/ during init to provide
+ * Written to agentcore/.llm-context/ during project creation to provide
  * AI coding assistants with compact, readable type definitions.
  *
  * When running from built bundle: text-loader plugin embeds contents.
- * When running from source (bun): files are read at runtime.
+ * When running from source without the text loader: files are read at runtime.
  */
 // @ts-expect-error - text import handled by build plugin
 import llmContextReadmeSrc from '../../schema/llm-compacted/README.md';

src/schema/llm-compacted/AGENTS.md

@@ -4,20 +4,18 @@ This directory contains **manually maintained** TypeScript type definitions opti
 
 ## How It Works
 
-1. The CLI embeds these `.ts` files as text at build time (via Bun's text import)
-2. During `init`, they're written to the user's `agentcore/.llm-context/` directory
+1. The CLI embeds these `.ts` files as text through the esbuild text-loader plugin
+2. During `create`, they're written to the user's `agentcore/.llm-context/` directory
 3. AI coding assistants read these files when editing AgentCore JSON configs
 
 ## Keeping In Sync With Zod Schemas
 
 When Zod schemas in `schemas/` are updated, manually update the corresponding file here:
 
-| Compacted File   | Zod Source Files                               |
-| ---------------- | ---------------------------------------------- |
-| `agentcore.ts`   | `schemas/agentcore-project.ts`                 |
-| `agent-env.ts`   | `schemas/agent-env.ts`, `schemas/primitives/*` |
-| `mcp.ts`         | `schemas/mcp.ts`, `schemas/mcp-defs.ts`        |
-| `aws-targets.ts` | `schemas/aws-targets.ts`                       |
+| Compacted File   | Zod Source Files                                                                                     |
+| ---------------- | ---------------------------------------------------------------------------------------------------- |
+| `agentcore.ts`   | `schemas/agentcore-project.ts`, `schemas/agent-env.ts`, `schemas/mcp.ts`, and `schemas/primitives/*` |
+| `aws-targets.ts` | `schemas/aws-targets.ts`                                                                             |
 
 ## Critical: Enum and Regex Accuracy
 

src/schema/llm-compacted/README.md

@@ -4,13 +4,13 @@
 
 ## Files
 
-| File             | JSON Config        | Purpose                                   |
-| ---------------- | ------------------ | ----------------------------------------- |
-| `agentcore.ts`   | `agentcore.json`   | Project, agent, memory, credential config |
-| `mcp.ts`         | `agentcore.json`   | Gateways, targets, MCP runtime tools      |
-| `aws-targets.ts` | `aws-targets.json` | Deployment targets (account + region)     |
+| File             | JSON Config        | Purpose                               |
+| ---------------- | ------------------ | ------------------------------------- |
+| `agentcore.ts`   | `agentcore.json`   | Project resources, including gateways |
+| `aws-targets.ts` | `aws-targets.json` | Deployment targets (account + region) |
 
 ## Usage
 
-When editing schema JSON files, reference the corresponding `.ts` file here for type definitions and validation
-constraints (marked with `@regex`, `@min`, `@max`).
+When editing AgentCore JSON config files, reference the corresponding `.ts` file here for type definitions, exact enum
+values, defaults, and validation constraints (marked with `@regex`, `@min`, and `@max`). Run `agentcore validate` after
+making changes.