forgeos 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/forge/compiler/agent-contract/build.ts

@@ -34,24 +34,38 @@ import type { QueryRegistry } from "../types/query-registry.ts";
 import type { LiveQueryRegistry } from "../types/live-query-registry.ts";
 import type { ClientManifest } from "../client-sdk/build-manifest.ts";
 import type { FrontendGraph } from "../types/frontend-graph.ts";
+import type {
+  ForgeExternalServiceEntry,
+  ForgeExternalServiceGraph,
+} from "../external-manifest/types.ts";
 import { createDiagnostic } from "../diagnostics/create.ts";
+import { CAIR_SCHEMA_VERSION } from "../../cair/types.ts";
 import { AUTH_ENV, DEFAULT_AUTH_CLAIMS } from "../../runtime/auth/config.ts";
+import {
+  forgeCliCommandForWorkspace,
+  forgeCliCommandsForWorkspace,
+  shouldUseLocalForgeCli,
+} from "../../workspace/forge-cli.ts";
 import type {
   AgentCapabilityMap,
   AgentCapabilityMapEntry,
   AgentContract,
   AgentDependencyApiInfo,
+  AgentExternalEntryInfo,
   AgentFrontendRuntimeBindingInfo,
   AgentFrontendUsageInfo,
   AgentHttpEndpointInfo,
   AgentIntegrationInfo,
   AgentRuntimeRule,
+  AgentProtocolInfo,
+  AgentToolRegistry,
   AgentPlaybook,
 } from "./types.ts";
 
 const AGENTS_USER_START = "<!-- user-notes:start -->";
 const AGENTS_USER_END = "<!-- user-notes:end -->";
 const DEFAULT_USER_NOTES = "Project-specific notes can go here.";
+const AGENTS_USER_NOTES_TOKEN = "__FORGE_AGENTS_USER_NOTES__";
 
 export interface AgentContractInput {
   workspaceRoot: string;
@@ -73,17 +87,21 @@ export interface AgentContractInput {
   apiSurface: ApiSurface;
   clientManifest: ClientManifest;
   frontendGraph: FrontendGraph;
+  externalServices?: ForgeExternalServiceGraph;
 }
 
 export interface AgentContractArtifacts {
   contract: AgentContract;
   capabilityMap: AgentCapabilityMap;
+  toolRegistry: AgentToolRegistry;
   agentsMd: string;
   appMapMd: string;
   capabilityMapMd: string;
+  agentToolsMd: string;
   runtimeRulesMd: string;
   operationPlaybooksMd: string;
   agentQuickstartMd: string;
+  agentCairGuideMd: string;
   diagnostics: Diagnostic[];
 }
 
@@ -245,31 +263,100 @@ function runtimeRules(): AgentRuntimeRule[] {
     {
       context: "command",
       allowed: ["ctx.db writes", "ctx.emit", "ctx.telemetry buffered events"],
-      forbidden: ["network packages", "ctx.secrets", "ctx.ai", "process.env", "filesystem access"],
+      forbidden: ["network packages", "ctx.secrets", "ctx.ai", "ctx.ai.runAgent", "ctx.agent.run", "direct secret/env access", "filesystem access"],
     },
     {
       context: "query",
       allowed: ["ctx.db reads", "ctx.telemetry buffered events"],
-      forbidden: ["insert/update/delete", "ctx.emit", "ctx.secrets", "ctx.ai", "network integrations"],
+      forbidden: ["insert/update/delete", "ctx.emit", "ctx.secrets", "ctx.ai", "ctx.ai.runAgent", "ctx.agent.run", "network integrations"],
     },
     {
       context: "liveQuery",
       allowed: ["ctx.db reads", "tenant-scoped subscriptions"],
-      forbidden: ["insert/update/delete", "ctx.emit", "ctx.secrets", "ctx.ai", "network integrations"],
+      forbidden: ["insert/update/delete", "ctx.emit", "ctx.secrets", "ctx.ai", "ctx.ai.runAgent", "ctx.agent.run", "network integrations"],
     },
     {
       context: "action",
-      allowed: ["ctx.secrets", "integrations", "ctx.ai", "ctx.db reads/writes", "network packages"],
+      allowed: ["ctx.secrets", "integrations", "ctx.ai", "ctx.ai.runAgent", "ctx.agent.run", "AI SDK tools", "ctx.db reads/writes", "network packages"],
       forbidden: ["uncommitted transactional side effects"],
     },
     {
       context: "workflow",
-      allowed: ["durable steps", "ctx.secrets", "integrations", "ctx.ai", "retries"],
+      allowed: ["durable steps", "ctx.secrets", "integrations", "ctx.ai", "ctx.ai.runAgent", "ctx.agent.run", "AI SDK ToolLoopAgent", "retries"],
       forbidden: ["non-idempotent step behavior without guards"],
     },
   ];
 }
 
+function agentProtocols(workspaceRoot: string): AgentProtocolInfo[] {
+  return [
+    {
+      id: "cair",
+      kind: "agent-protocol",
+      version: CAIR_SCHEMA_VERSION,
+      guide: "src/forge/_generated/agentCairGuide.md",
+      commands: forgeCliCommandsForWorkspace(workspaceRoot, [
+        "forge cair snapshot",
+        "forge cair query \"Q ST\"",
+        "forge cair query \"Q S name=<symbol>\"",
+        "forge cair query \"Q D S#1\"",
+        "forge cair query \"Q R S#1\"",
+        "forge cair query \"Q I S#1\"",
+        "forge cair action --plan \"A RN t=S#1 nn=<newName>\"",
+        "forge cair action \"A APPLY plan=<P#|path>\"",
+        "forge cair action \"A ROLLBACK journal=<path>\"",
+      ]),
+      preferredFor: [
+        "compact repository orientation",
+        "symbol lookup before file reads",
+        "semantic code edits",
+        "guarded refactors",
+        "Forge-native feature creation",
+        "impact-aware test selection",
+        "token-efficient programming",
+      ],
+      readQueries: [
+        "Q ST",
+        "Q S name=<symbol>",
+        "Q D S#1",
+        "Q R S#1",
+        "Q I S#1",
+        "Q T S#1",
+        "Q DEP.API package=<pkg> symbol=<export>",
+      ],
+      mutationActions: [
+        "A RN t=S#1 nn=<newName>",
+        "A MV t=S#1 to=<path>",
+        "A OI f=M#1",
+        "A FMT f=M#1",
+        "A MC n=<command>",
+        "A MQ n=<query>",
+        "A MA n=<action>",
+        "A MT n=<table> fields=<fields>",
+        "A AT t=S#1 kind=unit",
+        "A WX t=S#1 file=src/index.ts",
+        "A APPLY plan=<P#|path>",
+        "A ROLLBACK journal=<path>",
+      ],
+      compactAliases: [
+        "Q ST=Q STATUS",
+        "Q S=Q SYMBOL",
+        "Q D=Q DEF",
+        "Q R=Q REFS",
+        "Q I=Q IMPACT",
+        "A RN=A RENAME.SYMBOL",
+        "A MV=A MOVE.SYMBOL",
+        "A OI=A ORGANIZE.IMPORTS",
+        "A FMT=A FORMAT",
+        "A MC=A MAKE.COMMAND",
+        "A MT=A MAKE.TABLE",
+        "A AT=A ADD.TEST",
+        "A WX=A WIRE.EXPORT",
+      ],
+    },
+  ];
+}
+
 function playbooks(): AgentPlaybook[] {
   return [
     {
@@ -320,6 +407,28 @@ function playbooks(): AgentPlaybook[] {
         "Reconnect with Last-Event-ID or ?lastRevision=<revision> to verify resume behavior.",
       ],
     },
+    {
+      title: "Add an AI tool",
+      steps: [
+        "Add a server-only file under src/ai or src/tools.",
+        "Export aiTool({ description, inputSchema, outputSchema, risk, needsApproval, handler }).",
+        "Use zod schemas for inputSchema and outputSchema.",
+        "Access secrets through the tool context, not process.env.",
+        "Mark destructive or external side effects with risk and needsApproval.",
+        "Run forge generate and inspect src/forge/_generated/aiRegistry.json.",
+      ],
+    },
+    {
+      title: "Add an agent",
+      steps: [
+        "Export agent({ provider, model, instructions, tools, stopWhen }) from server-only source.",
+        "Prefer AI SDK ToolLoopAgent semantics through ctx.agent.run or ctx.ai.runAgent instead of custom loops.",
+        "Use stopWhen with stepCount or terminal tool calls to prevent unbounded loops.",
+        "Run agents only in actions, workflows, endpoints, or server code.",
+        "Run forge inspect ai --json or forge agent print-context --json and confirm the generated context lists the agent.",
+        "Use forge ai trace <traceId> --json to inspect agent runs and tool calls.",
+      ],
+    },
     {
       title: "Add a table",
       steps: [
@@ -355,7 +464,8 @@ function playbooks(): AgentPlaybook[] {
       title: "Safely refactor a feature",
       steps: [
         "Run forge refactor rename field <table.field> <table.field> --dry-run --json.",
-        "Rename codemods are AST-aware for extract-action, rename field, and rename table.",
+        "Run forge refactor rename command <oldName> <newName> --dry-run --json when renaming runtime entrypoints.",
+        "Rename codemods are AST-aware for extract-action, rename command, rename field, and rename table.",
         "Field renames are scoped to the target table, so tickets.priority only rewrites references linked to tickets.",
         "Review filesToModify, migrationPlan, diagnostics, and risk.",
         "Use --allow-high-risk only for intentional high-risk refactors.",
@@ -421,16 +531,17 @@ function playbooks(): AgentPlaybook[] {
         "Run forge dev --once --json for a one-shot diagnostic cycle.",
         "Use --api-only, --web-only, --no-watch, or --no-worker only when narrowing the loop intentionally.",
         "When a web app exists, forge dev starts the API runtime and the web dev server together and prints both URLs.",
-        "Use generated client and React hooks through web/lib/forge.ts.",
+        "Use generated client bindings through web/lib/forge.ts, web/src/lib/forge.ts, or Nuxt web/composables/forge.ts.",
       ],
     },
     {
       title: "Add or update frontend",
       steps: [
-        "Run forge make ui --framework vite --dry-run --json when the app does not have a web root.",
-        "Use web/lib/forge.ts as the generated client bridge.",
-        "Mount ForgeProvider once in the web app provider/layout layer; use devAuth for local development.",
-        "Use useQuery, useCommand, and useLiveQuery instead of raw /commands or /queries fetches.",
+        "Run forge make ui --framework vite --dry-run --json or forge make ui --framework nuxt --dry-run --json when the app does not have a web root.",
+        "Run forge make ai-chat support --dry-run --json to add a chat surface backed by /ai/agents/chat streaming and /ai/agents/run JSON automation.",
+        "Use web/lib/forge.ts, web/src/lib/forge.ts, or web/composables/forge.ts as the generated client bridge.",
+        "Mount ForgeProvider or install the Nuxt Forge plugin once in the web app provider/layout layer; use devAuth for local development.",
+        "Use useQuery/useCommand/useLiveQuery or useForgeQuery/useForgeCommand/useForgeLiveQuery instead of raw /commands or /queries fetches.",
         "Run forge generate so frontendGraph and agentContract include routes and bindings.",
         "Run forge inspect capabilities --json to confirm UI actions map to runtime capabilities.",
         "Run forge dev --once --json and forge doctor --json.",
@@ -509,7 +620,11 @@ function runtimeEntriesWithoutFrontend(contract: AgentContract): AgentCapability
           emits: commandEntry.emits,
           dependencies: [],
         },
-        notes: ["Runtime entry is available to agents even though no frontend usage was detected."],
+        notes: [
+          commandEntry.source === "external"
+            ? "External runtime entry is imported from a Forge manifest; execution requires an external runtime bridge."
+            : "Runtime entry is available to agents even though no frontend usage was detected.",
+        ],
       });
     }
   }
@@ -530,7 +645,11 @@ function runtimeEntriesWithoutFrontend(contract: AgentContract): AgentCapability
           emits: [],
           dependencies: [],
         },
-        notes: ["Runtime entry is available to agents even though no frontend usage was detected."],
+        notes: [
+          queryEntry.source === "external"
+            ? "External runtime entry is imported from a Forge manifest; execution requires an external runtime bridge."
+            : "Runtime entry is available to agents even though no frontend usage was detected.",
+        ],
       });
     }
   }
@@ -656,6 +775,89 @@ function buildCapabilityMap(contract: AgentContract): AgentCapabilityMap {
   };
 }
 
+function autoToolName(kind: "command" | "query" | "liveQuery", name: string): string {
+  return `forge_${kind}_${name}`.replace(/[^A-Za-z0-9_$]/g, "_");
+}
+
+function buildAgentToolRegistry(contract: AgentContract): AgentToolRegistry {
+  const autoTools: AgentToolRegistry["autoTools"] = [
+    ...contract.commands.map((command) => ({
+      name: autoToolName("command", command.name),
+      sourceKind: "command" as const,
+      sourceName: command.name,
+      ...(command.policy ? { policy: command.policy } : {}),
+      file: command.file,
+      http: command.http,
+      frontend: command.frontend,
+      tablesRead: command.tablesRead,
+      tablesWritten: command.tablesWritten,
+      emits: command.emits,
+      dependencies: [],
+      readOnly: false,
+      risk: "write" as const,
+      needsApproval: command.source === "external"
+        ? command.external?.needsApproval ?? (command.external?.risk !== "read")
+        : true,
+      requiresAuth: command.policy !== undefined && command.policy !== "public",
+      ...(command.source ? { source: command.source } : {}),
+      ...(command.external ? { external: command.external } : {}),
+      execution: command.source === "external"
+        ? "external-runtime-endpoint" as const
+        : "forge-runtime-endpoint" as const,
+    })),
+    ...contract.queries.map((query) => ({
+      name: autoToolName("query", query.name),
+      sourceKind: "query" as const,
+      sourceName: query.name,
+      ...(query.policy ? { policy: query.policy } : {}),
+      file: query.file,
+      http: query.http,
+      frontend: query.frontend,
+      tablesRead: query.tablesRead,
+      tablesWritten: [],
+      emits: [],
+      dependencies: [],
+      readOnly: true,
+      risk: "read" as const,
+      needsApproval: false,
+      requiresAuth: query.policy !== undefined && query.policy !== "public",
+      ...(query.source ? { source: query.source } : {}),
+      ...(query.external ? { external: query.external } : {}),
+      execution: query.source === "external"
+        ? "external-runtime-endpoint" as const
+        : "forge-runtime-endpoint" as const,
+    })),
+    ...contract.liveQueries.map((liveQuery) => ({
+      name: autoToolName("liveQuery", liveQuery.name),
+      sourceKind: "liveQuery" as const,
+      sourceName: liveQuery.name,
+      ...(liveQuery.policy ? { policy: liveQuery.policy } : {}),
+      file: liveQuery.file,
+      http: liveQuery.http,
+      frontend: liveQuery.frontend,
+      tablesRead: liveQuery.tablesRead,
+      tablesWritten: [],
+      emits: [],
+      dependencies: liveQuery.dependencies,
+      readOnly: true,
+      risk: "read" as const,
+      needsApproval: false,
+      requiresAuth: liveQuery.policy !== undefined && liveQuery.policy !== "public",
+      source: "local" as const,
+      execution: "forge-runtime-endpoint" as const,
+    })),
+  ].sort((a, b) => a.name.localeCompare(b.name));
+
+  return {
+    schemaVersion: "0.1.0",
+    generatorVersion: GENERATOR_VERSION,
+    project: contract.project,
+    explicitTools: contract.ai.tools,
+    autoTools,
+    agents: contract.ai.agents,
+  };
+}
+
 function jsAccess(group: string, name: string): string {
   return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)
     ? `api.${group}.${name}`
@@ -695,6 +897,39 @@ function httpEndpointFor(
   };
 }
 
+function externalEndpointFor(entry: ForgeExternalServiceEntry): AgentHttpEndpointInfo {
+  const encodedService = encodeURIComponent(entry.service);
+  const encodedName = encodeURIComponent(entry.name);
+  const collection = entry.kind === "query" ? "queries" : "commands";
+  return {
+    method: entry.method ?? "POST",
+    path: entry.path ?? `/external/${encodedService}/${collection}/${encodedName}`,
+    exampleBody: { args: {} },
+  };
+}
+
+function externalEntryInfo(entry: ForgeExternalServiceEntry): AgentExternalEntryInfo {
+  return {
+    service: entry.service,
+    language: entry.language,
+    ...(entry.framework ? { framework: entry.framework } : {}),
+    transport: entry.transport,
+    ...(entry.transaction ? { transaction: entry.transaction } : {}),
+    ...(entry.risk ? { risk: entry.risk } : {}),
+    ...(typeof entry.needsApproval === "boolean" ? { needsApproval: entry.needsApproval } : {}),
+    effects: entry.effects ?? [],
+    ...(entry.description ? { description: entry.description } : {}),
+  };
+}
+
+function externalFrontendUsage(entry: ForgeExternalServiceEntry): AgentFrontendUsageInfo {
+  return {
+    hook: `external manifest '${entry.service}.${entry.name}'; runtime bridge required before client invocation`,
+    routes: [],
+    components: [],
+  };
+}
+
 function frontendUsageFor(
   frontendGraph: FrontendGraph,
   kind: "command" | "query" | "liveQuery" | "action",
@@ -817,12 +1052,14 @@ export function buildAgentContractArtifacts(
 
   const runtimeEntries = new Map(input.runtimeGraph.entries.map((entry) => [entry.name, entry]));
   const tableNames = new Set(input.dataGraph.tables.map((table) => table.name));
-  const commandInfos: AgentContract["commands"] = sorted(Object.keys(input.apiSurface.commands), (name) => name).map((name) => {
+  const externalEntries = input.externalServices?.services.flatMap((service) => service.entries) ?? [];
+  const localCommandInfos: AgentContract["commands"] = sorted(Object.keys(input.apiSurface.commands), (name) => name).map((name) => {
     const entry = runtimeEntries.get(name);
     const file = entry?.file ?? "";
     return {
       name,
       file,
+      source: "local" as const,
       policy: authPolicy(commandAuth.get(name)),
       tablesRead: dbTablesForFile(input.workspaceRoot, file, tableNames, DB_READ_OPS),
       tablesWritten: dbTablesForFile(input.workspaceRoot, file, tableNames, DB_WRITE_OPS),
@@ -833,9 +1070,30 @@ export function buildAgentContractArtifacts(
       frontend: frontendUsageFor(input.frontendGraph, "command", name),
     };
   });
-  const queryInfos: AgentContract["queries"] = sorted(input.queryRegistry.queries, (query) => query.name).map((query) => ({
+  const externalCommandInfos: AgentContract["commands"] = externalEntries
+    .filter((entry) => entry.kind === "command")
+    .map((entry) => ({
+      name: `${entry.service}.${entry.name}`,
+      file: `external:${entry.service}`,
+      source: "external" as const,
+      external: externalEntryInfo(entry),
+      ...(entry.policy ? { policy: entry.policy } : {}),
+      tablesRead: [],
+      tablesWritten: entry.transaction === "read-only" ? [] : [`external:${entry.service}`],
+      emits: entry.effects ?? [],
+      allowedPackages: [],
+      forbiddenCapabilities: [],
+      http: externalEndpointFor(entry),
+      frontend: externalFrontendUsage(entry),
+    }));
+  const commandInfos: AgentContract["commands"] = sorted(
+    [...localCommandInfos, ...externalCommandInfos],
+    (command) => command.name,
+  );
+  const localQueryInfos: AgentContract["queries"] = sorted(input.queryRegistry.queries, (query) => query.name).map((query) => ({
     name: query.name,
     file: query.file,
+    source: "local" as const,
     policy: authPolicy(queryAuth.get(query.name)),
     readOnly: true,
     tenantScoped: input.tenantScope.tables.length > 0,
@@ -845,6 +1103,26 @@ export function buildAgentContractArtifacts(
     http: httpEndpointFor("query", query.name),
     frontend: frontendUsageFor(input.frontendGraph, "query", query.name),
   }));
+  const externalQueryInfos: AgentContract["queries"] = externalEntries
+    .filter((entry) => entry.kind === "query")
+    .map((entry) => ({
+      name: `${entry.service}.${entry.name}`,
+      file: `external:${entry.service}`,
+      source: "external" as const,
+      external: externalEntryInfo(entry),
+      ...(entry.policy ? { policy: entry.policy } : {}),
+      readOnly: true as const,
+      tenantScoped: entry.tenantScoped ?? false,
+      tablesRead: [`external:${entry.service}`],
+      allowedPackages: [],
+      forbiddenCapabilities: [],
+      http: externalEndpointFor(entry),
+      frontend: externalFrontendUsage(entry),
+    }));
+  const queryInfos: AgentContract["queries"] = sorted(
+    [...localQueryInfos, ...externalQueryInfos],
+    (query) => query.name,
+  );
   const liveQueryInfos: AgentContract["liveQueries"] = sorted(input.liveQueryRegistry.liveQueries, (liveQuery) => liveQuery.name).map(
     (liveQuery) => {
       const tablesRead = dbTablesForFile(input.workspaceRoot, liveQuery.file, tableNames, DB_READ_OPS);
@@ -869,6 +1147,7 @@ export function buildAgentContractArtifacts(
     queries: queryInfos,
     liveQueries: liveQueryInfos,
   });
+  const protocols = agentProtocols(input.workspaceRoot);
   const contract: AgentContract = {
     schemaVersion: "0.1.0",
     generatorVersion: GENERATOR_VERSION,
@@ -929,6 +1208,19 @@ export function buildAgentContractArtifacts(
     }),
     dependencyApis: buildDependencyApis(input.packageGraph),
     integrations: buildIntegrations(input.classified),
+    externalServices: (input.externalServices?.services ?? []).map((service) => ({
+      name: service.name,
+      language: service.language,
+      ...(service.framework ? { framework: service.framework } : {}),
+      transport: service.transport,
+      ...(service.baseUrl ? { baseUrl: service.baseUrl } : {}),
+      ...(service.command ? { command: service.command } : {}),
+      ...(service.health ? { health: service.health } : {}),
+      commands: sorted(service.entries.filter((entry) => entry.kind === "command"), (entry) => entry.name)
+        .map((entry) => `${service.name}.${entry.name}`),
+      queries: sorted(service.entries.filter((entry) => entry.kind === "query"), (entry) => entry.name)
+        .map((entry) => `${service.name}.${entry.name}`),
+    })),
     secrets: sorted(input.secretRegistry.secrets, (secret) => secret.name).map((secret) => ({
       name: secret.name,
       integration: secret.integration,
@@ -951,6 +1243,23 @@ export function buildAgentContractArtifacts(
           ...(generation.purpose ? { purpose: generation.purpose } : {}),
         }))
         .sort((a, b) => `${a.file}:${a.method}:${a.model}`.localeCompare(`${b.file}:${b.method}:${b.model}`)),
+      tools: input.aiRegistry.tools.map((tool) => ({
+        name: tool.name,
+        file: tool.file,
+        ...(tool.description ? { description: tool.description } : {}),
+        risk: tool.risk,
+        strict: tool.strict,
+        needsApproval: tool.needsApproval,
+      })),
+      agents: input.aiRegistry.agents.map((agent) => ({
+        name: agent.name,
+        file: agent.file,
+        provider: agent.provider,
+        model: agent.model,
+        ...(agent.instructions ? { instructions: agent.instructions } : {}),
+        tools: agent.tools,
+        stopWhen: agent.stopWhen,
+      })),
     },
     client: {
       queries: input.clientManifest.queries,
@@ -1025,10 +1334,11 @@ export function buildAgentContractArtifacts(
     },
     rules: runtimeRules(),
     playbooks: playbooks(),
+    agentProtocols: protocols,
     commandsToRun: {
-      beforeEditing: ["forge do inspect --json", "forge dev --once --json", "forge inspect all --json", "forge check --json"],
-      afterEditing: ["forge generate", "forge check", "forge verify --standard", "forge verify --strict"],
-      dev: ["forge dev", "forge dev --once --json", "forge do fix --json", "forge do verify --json", "forge dev --api-only", "forge dev --web-only"],
+      beforeEditing: forgeCliCommandsForWorkspace(input.workspaceRoot, ["forge agent onboard --target codex --json", "forge status --json", "forge changed --json", "forge handoff --json", "forge do inspect --json", "forge cair snapshot", "forge cair query \"Q ST\"", "forge dev --once --json", "forge agent print-context --json", "forge check --json"]),
+      afterEditing: forgeCliCommandsForWorkspace(input.workspaceRoot, ["forge generate", "forge check", "forge verify --standard", finalVerifyCommand(input.workspaceRoot)]),
+      dev: forgeCliCommandsForWorkspace(input.workspaceRoot, ["forge dev", "forge dev --once --json", "forge handoff --json", "forge do fix --json", "forge do verify --json", "forge dev --api-only", "forge dev --web-only"]),
     },
   };
 
@@ -1037,31 +1347,39 @@ export function buildAgentContractArtifacts(
     ? (nodeFileSystem.readText(existingAgentsPath) ?? "")
     : null;
   const userNotes = extractUserNotes(existingAgents);
-  const agentsMd = renderAgentsMd(contract, userNotes);
+  const agentsMd = renderAgentsMd(contract, userNotes, input.workspaceRoot);
+  const toolRegistry = buildAgentToolRegistry(contract);
   const capabilityMap = buildCapabilityMap(contract);
   const capabilityMapMd = renderCapabilityMapMd(capabilityMap);
+  const agentToolsMd = renderAgentToolsMd(toolRegistry);
   const appMapMd = renderAppMapMd(contract);
   const runtimeRulesMd = renderRuntimeRulesMd(contract.rules);
   const operationPlaybooksMd = renderOperationPlaybooksMd(contract.playbooks);
-  const agentQuickstartMd = renderAgentQuickstartMd();
+  const agentQuickstartMd = renderAgentQuickstartMd(input.workspaceRoot);
+  const agentCairGuideMd = renderAgentCairGuideMd(contract, input.workspaceRoot);
   const diagnostics = scanAgentContractForLeaks(contract, [
     agentsMd,
+    agentToolsMd,
     capabilityMapMd,
     appMapMd,
     runtimeRulesMd,
     operationPlaybooksMd,
     agentQuickstartMd,
+    agentCairGuideMd,
   ]);
 
   return {
     contract,
     capabilityMap,
+    toolRegistry,
     agentsMd,
     appMapMd,
     capabilityMapMd,
+    agentToolsMd,
     runtimeRulesMd,
     operationPlaybooksMd,
     agentQuickstartMd,
+    agentCairGuideMd,
     diagnostics: [...diagnostics, ...capabilityMap.diagnostics],
   };
 }
@@ -1099,7 +1417,31 @@ export function serializeCapabilityMapTs(capabilityMap: AgentCapabilityMap): str
   return `export const capabilityMap = ${JSON.stringify(parsed, null, 2)} as const;\n`;
 }
 
-function renderAgentsMd(contract: AgentContract, userNotes: string): string {
+export function serializeAgentToolRegistryJson(registry: AgentToolRegistry): string {
+  return serializeCanonical(registry);
+}
+
+export function serializeAgentToolRegistryTs(registry: AgentToolRegistry): string {
+  const parsed = JSON.parse(serializeAgentToolRegistryJson(registry)) as unknown;
+  return `export const agentTools = ${JSON.stringify(parsed, null, 2)} as const;\n`;
+}
+
+function localizeForgeCliMarkdown(workspaceRoot: string, markdown: string): string {
+  return shouldUseLocalForgeCli(workspaceRoot)
+    ? markdown.replace(/\bforge (?=[a-z])/g, "node bin/forge.mjs ")
+    : markdown;
+}
+
+function finalVerifyCommand(workspaceRoot: string): string {
+  const command = shouldUseLocalForgeCli(workspaceRoot) ? "forge verify framework" : "forge verify --strict";
+  return forgeCliCommandForWorkspace(workspaceRoot, command);
+}
+
+function renderAgentsMd(contract: AgentContract, userNotes: string, workspaceRoot: string): string {
+  const finalVerify = finalVerifyCommand(workspaceRoot);
+  const cliEntrypoint = shouldUseLocalForgeCli(workspaceRoot)
+    ? "This is the ForgeOS framework checkout. Use `node bin/forge.mjs ...` so maintainer commands run against this source tree; reserve the global `forge` command for installed-package smoke tests."
+    : "Use the installed `forge` command for app workflows.";
   const tenantTables = contract.data.tables
     .filter((table) => table.tenantScoped)
     .map((table) => `${table.name} via ${table.tenantField}`);
@@ -1107,8 +1449,14 @@ function renderAgentsMd(contract: AgentContract, userNotes: string): string {
     `${policy.name}: ${policy.roles.length > 0 ? policy.roles.join(", ") : policy.kind}`,
   );
   const secrets = contract.secrets.map((secret) => `${secret.name}${secret.required ? " (required)" : " (optional)"}`);
+  const aiTools = contract.ai.tools.map((tool) =>
+    `${tool.name}: ${tool.description ?? "no description"} (${tool.risk}${tool.needsApproval ? ", approval" : ""})`,
+  );
+  const aiAgents = contract.ai.agents.map((agent) =>
+    `${agent.name}: ${agent.provider}/${agent.model} with ${agent.tools.length > 0 ? agent.tools.join(", ") : "no tools"}`,
+  );
 
-  return normalizeNewlines(`# AGENTS.md
+  const generated = localizeForgeCliMarkdown(workspaceRoot, `# AGENTS.md
 
 <!-- forge-generated:start -->
 
@@ -1116,23 +1464,51 @@ function renderAgentsMd(contract: AgentContract, userNotes: string): string {
 
 This is a ForgeOS application named \`${contract.project.name}\`.
 
+## CLI entrypoint
+
+${cliEntrypoint}
+
 ## Required workflow
 
 Before editing:
 
 \`\`\`bash
+forge agent onboard --target codex --json
+forge status --json
+forge changed --json
+forge handoff --json
 forge do inspect --json
 forge dev --once --json
-forge inspect all --json
+forge agent print-context --json
 forge check --json
 \`\`\`
 
+## CAIR first
+
+Before reading large files or hand-writing patches, prefer the generated CAIR guide:
+
+\`\`\`bash
+forge cair snapshot
+forge cair query "Q ST"
+forge cair query "Q S name=<symbol>"
+forge cair query "Q D S#1"
+forge cair query "Q R S#1"
+forge cair query "Q I S#1"
+\`\`\`
+
+Use \`src/forge/_generated/agentCairGuide.md\` for the full compact protocol. Plan CAIR mutations before applying them:
+
+\`\`\`bash
+forge cair action --plan "A RN t=S#1 nn=<newName>"
+forge cair action "A APPLY plan=<returned-plan-path>"
+\`\`\`
+
 After editing:
 
 \`\`\`bash
 forge generate
 forge check
-forge verify --strict
+${finalVerify}
 \`\`\`
 
 ## Do not edit
@@ -1160,7 +1536,7 @@ Template apps may ignore \`src/forge/_generated/**\` and \`forge.lock\` in git t
 ## Runtime rules
 
 - Do not import network packages inside \`command\`, \`query\`, or \`liveQuery\`.
-- Do not use \`process.env\` directly.
+- Do not read secrets or server runtime config through \`process.env\` in Forge runtime code; use \`ctx.secrets\` or generated config context. Public frontend bridge env such as \`NEXT_PUBLIC_*\` and \`NUXT_PUBLIC_*\` is allowed in web bridge files.
 - Do not access cross-tenant data.
 - Commands must use \`ctx.emit\` for side effects.
 - Actions and workflows handle side effects after commit.
@@ -1174,10 +1550,13 @@ forge do fix --json
 forge do verify --json
 forge dev --once --json
 forge dev
+forge handoff --json
 forge inspect app --json
 forge inspect all --json
+forge inspect all --full --json
 forge inspect frontend --json
 forge inspect capabilities --json
+forge inspect agent-tools --json
 forge deps inspect <package> --json
 forge deps api <package> <symbol> --json
 forge deps trace <package> --json
@@ -1191,9 +1570,13 @@ forge doctor
 forge doctor windows --json
 forge setup windows --json
 forge agent print-context --json
+forge agent doctor --target codex --json
+forge ai tools --json
+forge ai agents --json
+forge ai trace <traceId> --json
 forge verify --smoke
 forge verify --standard
-forge verify --strict
+${finalVerify}
 \`\`\`
 
 ## Data
@@ -1210,6 +1593,21 @@ ${renderList(policies)}
 
 ${renderList(secrets)}
 
+## AI Tools And Agents
+
+- AI SDK engine: Vercel AI SDK v6.
+- Forge layer: generated registry, runtime rules, telemetry, secrets, tenant/auth context, and agent contract.
+- Use \`ctx.agent.run\` or \`ctx.ai.runAgent\` only in actions, workflows, endpoints, and server code.
+- Do not create custom tool loops; use Forge tools and AI SDK \`ToolLoopAgent\` through the Forge runtime.
+
+Tools:
+
+${renderList(aiTools)}
+
+Agents:
+
+${renderList(aiAgents)}
+
 ## Auth
 
 - Modes: ${contract.auth.modes.join(", ")}
@@ -1233,9 +1631,9 @@ ${contract.frontend.dev ? `- Web URL: ${contract.frontend.dev.url}
 
 Rules:
 
-- Use the local \`web/**/lib/forge.ts\` bridge to generated hooks.
-- Mount \`<ForgeProvider devAuth>\` in local development.
-- Use \`useQuery\`, \`useCommand\`, and \`useLiveQuery\` instead of raw Forge endpoint fetches in React components.
+- Use the local \`web/**/lib/forge.ts\` or Nuxt \`web/composables/forge.ts\` bridge to generated bindings.
+- Mount \`<ForgeProvider devAuth>\` or install the Nuxt Forge plugin in local development.
+- Use \`useQuery\`/\`useCommand\`/\`useLiveQuery\` or \`useForgeQuery\`/\`useForgeCommand\`/\`useForgeLiveQuery\` instead of raw Forge endpoint fetches in components.
 - Keep frontend routes reflected in \`src/forge/_generated/frontendGraph.json\`.
 
 ## Common tasks
@@ -1258,7 +1656,7 @@ forge do verify --json
 1. Add file in \`src/commands\`.
 2. Declare \`auth: can("...")\`.
 3. Run \`forge generate\`.
-4. Run \`forge verify --strict\`.
+4. Run \`${finalVerify}\`.
 
 ### Scaffold a resource
 
@@ -1268,6 +1666,8 @@ Use:
 forge make resource <name> --fields title:text,status:enum(open,closed) --dry-run --json
 forge make resource <name> --fields title:text,status:enum(open,closed) --with-ui --yes
 forge make ui --framework vite --dry-run --json
+forge make ui --framework nuxt --dry-run --json
+forge make ai-chat support --dry-run --json
 \`\`\`
 
 Review the plan before applying when the resource touches schema or policies.
@@ -1283,7 +1683,7 @@ forge inspect frontend --json
 forge inspect capabilities --json
 \`\`\`
 
-\`forge dev\` starts the API runtime and web app together when \`web/\` exists. \`forge dev --once --json\` reports routes, components, \`ForgeProvider\`, bridge files, generated client bindings, direct runtime fetch warnings, capability-map parity warnings, and fix hints.
+\`forge dev\` starts the API runtime and web app together when \`web/\` exists. \`forge dev --once --json\` reports routes, components, providers/plugins, bridge files, generated client bindings, direct runtime fetch warnings, capability-map parity warnings, and fix hints.
 
 ### Apply a feature blueprint
 
@@ -1304,11 +1704,13 @@ Use:
 \`\`\`bash
 forge refactor rename field tickets.priority tickets.urgency --dry-run --json
 forge refactor rename field tickets.priority tickets.urgency --yes
+forge refactor rename command createTicket openTicket --dry-run --json
+forge refactor rename command createTicket openTicket --yes
 \`\`\`
 
-These codemods are AST-aware for \`extract-action\`, \`rename field\`, and \`rename table\`. Field renames are scoped to the target table, so \`tickets.priority\` only rewrites references linked to \`tickets\`.
+These codemods are AST-aware for \`extract-action\`, \`rename command\`, \`rename field\`, and \`rename table\`. Command renames update runtime registries, generated client references, frontend hooks, tests, and string references where safe. Field renames are scoped to the target table, so \`tickets.priority\` only rewrites references linked to \`tickets\`.
 
-Never edit \`src/forge/_generated/**\` directly. Review migration hints before applying field or table renames.
+Never edit \`src/forge/_generated/**\` directly. Review migration hints before applying command, field, or table renames.
 
 ### Plan impact-based tests
 
@@ -1321,7 +1723,7 @@ forge test run --changed --timeout-ms 120000 --json
 forge verify --standard
 \`\`\`
 
-Use \`forge verify --standard\` for the normal agent development loop. Finish handoffs with \`forge verify --strict\` when the change is ready.
+Use \`forge verify --standard\` for the normal agent development loop. Finish handoffs with \`${finalVerify}\` when the change is ready.
 
 ### Repair a failing check
 
@@ -1334,6 +1736,20 @@ forge repair plan --from-last-test-run --write
 
 Apply only high-confidence deterministic repairs automatically. Review medium or low confidence repairs before changing code.
 
+### Add AI tools or agents
+
+Use:
+
+\`\`\`bash
+forge generate
+forge inspect ai --json
+forge agent print-context --json
+forge ai check --json
+forge ai trace <traceId> --json
+\`\`\`
+
+Define tools with \`aiTool({ inputSchema, outputSchema, risk, needsApproval, handler })\` and agents with \`agent({ provider, model, instructions, tools, stopWhen })\`. Execute agents with \`ctx.agent.run\` or \`ctx.ai.runAgent\` only from actions, workflows, endpoints, or server code. In dev, POST \`/ai/agents/run\` returns JSON for automation and POST \`/ai/agents/chat\` returns an AI SDK UIMessage stream for React \`useChat\`; both accept \`agent: "<exportedAgentName>"\` and use generated auto-tools from \`agentTools.json\`.
+
 ### Export agent adapters
 
 Use:
@@ -1366,7 +1782,7 @@ forge deps upgrade-plan <package> --to latest
 forge deps inspect <package> --json
 forge deps api <package> <symbol> --json
 forge deps upgrade-apply <plan>
-forge verify --strict
+${finalVerify}
 \`\`\`
 
 Do not manually edit \`package.json\` for package upgrades unless necessary.
@@ -1387,10 +1803,11 @@ Durable invalidations live in \`_forge_live_invalidations\`.
 
 ${AGENTS_USER_START}
 
-${userNotes}
+${AGENTS_USER_NOTES_TOKEN}
 
 ${AGENTS_USER_END}
 `);
+  return normalizeNewlines(generated.replace(AGENTS_USER_NOTES_TOKEN, () => userNotes));
 }
 
 function renderAppMapMd(contract: AgentContract): string {
@@ -1471,6 +1888,48 @@ function renderAppMapMd(contract: AgentContract): string {
     lines.push(`### ${workflow.name}`, `Trigger: ${workflow.trigger ?? "manual"}`, "Steps:", ...renderList(workflow.steps).split("\n"), "");
   }
 
+  lines.push("## AI", "");
+  lines.push("### Providers", "", ...renderList(contract.ai.providers).split("\n"), "");
+  lines.push("### Generations", "");
+  for (const generation of contract.ai.generations) {
+    lines.push(
+      `- ${generation.method}: ${generation.provider}/${generation.model} in ${generation.file}${generation.purpose ? ` (${generation.purpose})` : ""}`,
+    );
+  }
+  if (contract.ai.generations.length === 0) {
+    lines.push("- none");
+  }
+  lines.push("", "### Tools", "");
+  for (const tool of contract.ai.tools) {
+    lines.push(
+      `#### ${tool.name}`,
+      `File: ${tool.file}`,
+      `Risk: ${tool.risk}`,
+      `Strict: ${tool.strict ? "yes" : "no"}`,
+      `Needs approval: ${String(tool.needsApproval)}`,
+      `Description: ${tool.description ?? "none"}`,
+      "",
+    );
+  }
+  if (contract.ai.tools.length === 0) {
+    lines.push("- none", "");
+  }
+  lines.push("### Agents", "");
+  for (const agent of contract.ai.agents) {
+    lines.push(
+      `#### ${agent.name}`,
+      `File: ${agent.file}`,
+      `Model: ${agent.provider}/${agent.model}`,
+      "Tools:",
+      ...renderList(agent.tools).split("\n"),
+      `Stop when: ${JSON.stringify(agent.stopWhen)}`,
+      "",
+    );
+  }
+  if (contract.ai.agents.length === 0) {
+    lines.push("- none", "");
+  }
+
   lines.push("## Frontend", "");
   lines.push(`Present: ${contract.frontend.present ? "yes" : "no"}`);
   lines.push(`Framework: ${contract.frontend.framework}`);
@@ -1631,6 +2090,72 @@ function renderCapabilityMapMd(capabilityMap: AgentCapabilityMap): string {
   return normalizeNewlines(lines.join("\n"));
 }
 
+function renderAgentToolsMd(registry: AgentToolRegistry): string {
+  const lines = [
+    "# Agent Tools",
+    "",
+    `Project: ${registry.project.name}`,
+    "",
+    "## Explicit AI Tools",
+    "",
+  ];
+
+  for (const tool of registry.explicitTools) {
+    lines.push(
+      `### ${tool.name}`,
+      `File: ${tool.file}`,
+      `Risk: ${tool.risk}`,
+      `Strict: ${tool.strict ? "yes" : "no"}`,
+      `Needs approval: ${String(tool.needsApproval)}`,
+      `Description: ${tool.description ?? "none"}`,
+      "",
+    );
+  }
+  if (registry.explicitTools.length === 0) {
+    lines.push("- none", "");
+  }
+
+  lines.push("## Auto Tools From Forge Runtime", "");
+  for (const tool of registry.autoTools) {
+    lines.push(
+      `### ${tool.name}`,
+      `Source: ${tool.sourceKind} ${tool.sourceName}`,
+      `File: ${tool.file}`,
+      `HTTP: ${tool.http.method} ${tool.http.path}`,
+      `Policy: ${tool.policy ?? "none"}`,
+      `Requires auth: ${tool.requiresAuth ? "yes" : "no"}`,
+      `Read-only: ${tool.readOnly ? "yes" : "no"}`,
+      `Risk: ${tool.risk}`,
+      `Needs approval: ${String(tool.needsApproval)}`,
+      `Frontend hook: \`${tool.frontend.hook}\``,
+      `Reads: ${tool.tablesRead.length > 0 ? tool.tablesRead.join(", ") : "none"}`,
+      `Writes: ${tool.tablesWritten.length > 0 ? tool.tablesWritten.join(", ") : "none"}`,
+      `Emits: ${tool.emits.length > 0 ? tool.emits.join(", ") : "none"}`,
+      "",
+    );
+  }
+  if (registry.autoTools.length === 0) {
+    lines.push("- none", "");
+  }
+
+  lines.push("## Agents", "");
+  for (const agent of registry.agents) {
+    lines.push(
+      `### ${agent.name}`,
+      `File: ${agent.file}`,
+      `Model: ${agent.provider}/${agent.model}`,
+      `Tools: ${agent.tools.length > 0 ? agent.tools.join(", ") : "none"}`,
+      `Stop when: ${JSON.stringify(agent.stopWhen)}`,
+      "",
+    );
+  }
+  if (registry.agents.length === 0) {
+    lines.push("- none", "");
+  }
+
+  return normalizeNewlines(lines.join("\n"));
+}
+
 function renderOperationPlaybooksMd(playbookEntries: AgentPlaybook[]): string {
   const lines = ["# Operation Playbooks", ""];
   for (const playbook of playbookEntries) {
@@ -1643,21 +2168,29 @@ function renderOperationPlaybooksMd(playbookEntries: AgentPlaybook[]): string {
   return normalizeNewlines(lines.join("\n"));
 }
 
-function renderAgentQuickstartMd(): string {
-  return normalizeNewlines(`# Agent Quickstart
+function renderAgentQuickstartMd(workspaceRoot: string): string {
+  const finalVerify = finalVerifyCommand(workspaceRoot);
+  return normalizeNewlines(localizeForgeCliMarkdown(workspaceRoot, `# Agent Quickstart
 
 Run:
 
 \`\`\`bash
+forge agent onboard --target codex --json
+forge status --json
+forge changed --json
+forge handoff --json
 forge do inspect --json
 forge do fix --json
 forge do verify --json
 forge dev --once --json
 forge dev
-forge inspect all --json
+forge agent print-context --json
 forge inspect frontend --json
 forge inspect capabilities --json
+forge inspect agent-tools --json
+forge inspect all --json
 forge check --json
+forge ai trace <traceId> --json
 \`\`\`
 
 Never edit:
@@ -1673,7 +2206,158 @@ Always finish with:
 
 \`\`\`bash
 forge generate
-forge verify --strict
+${finalVerify}
 \`\`\`
-`);
+`));
+}
+
+function renderAgentCairGuideMd(contract: AgentContract, workspaceRoot: string): string {
+  const cair = contract.agentProtocols.find((protocol) => protocol.id === "cair");
+  const finalVerify = finalVerifyCommand(workspaceRoot);
+  const summary = [
+    `commands=${contract.commands.length}`,
+    `queries=${contract.queries.length}`,
+    `liveQueries=${contract.liveQueries.length}`,
+    `actions=${contract.actions.length}`,
+    `workflows=${contract.workflows.length}`,
+    `tables=${contract.data.tables.length}`,
+  ].join(" ");
+  return normalizeNewlines(localizeForgeCliMarkdown(workspaceRoot, `# CAIR Agent Guide
+
+Project: ${contract.project.name}
+CAIR version: ${cair?.version ?? CAIR_SCHEMA_VERSION}
+Surface: ${summary}
+
+CAIR is the compact agent protocol for reading and changing this Forge workspace. Use it before opening whole files when symbol, module, dependency, test, or impact context is enough.
+
+## First commands
+
+\`\`\`bash
+forge cair snapshot
+forge cair query "Q ST"
+\`\`\`
+
+The snapshot emits compact ids:
+
+- \`M#\` modules/files
+- \`S#\` symbols
+- \`P#\` packages
+- \`API#\` dependency APIs
+- \`T#\` tests
+
+## Read before editing
+
+\`\`\`bash
+forge cair query "Q S name=<symbol>"
+forge cair query "Q D S#1"
+forge cair query "Q R S#1"
+forge cair query "Q I S#1"
+forge cair query "Q T S#1"
+forge cair query "Q DEP.API package=<pkg> symbol=<export>"
+\`\`\`
+
+Only open source files after CAIR shows that the exact file or body is needed.
+
+## Plan, apply, rollback
+
+Never apply semantic mutations first. Create a plan:
+
+\`\`\`bash
+forge cair action --plan "A RN t=S#1 nn=<newName>"
+\`\`\`
+
+Apply the returned plan path:
+
+\`\`\`bash
+forge cair action "A APPLY plan=<P#|.forge/cair/plans/...json>"
+\`\`\`
+
+Keep returned journal paths for rollback:
+
+\`\`\`bash
+forge cair action "A ROLLBACK journal=.forge/cair/journal/<journal>.json"
+\`\`\`
+
+## Semantic actions
+
+\`\`\`txt
+A RN t=S#1 nn=<newName>
+A MV t=S#1 to=src/target.ts
+A SIG t=S#1 signature="export function x(input: string): boolean"
+A PARAM t=S#1 name=tenantId type=string default="defaultTenant"
+A CALLS t=S#1 appendArg="defaultTenant"
+A OI f=M#1
+A FMT f=M#1
+\`\`\`
+
+For high-risk semantic actions, include expectations when available:
+
+\`\`\`txt
+expect.file=src/path.ts
+expect.kind=command
+expect.hash=<sha256>
+\`\`\`
+
+## Forge-native actions
+
+Prefer Forge-native CAIR actions over hand-writing boilerplate:
+
+\`\`\`txt
+A MC n=createTicket
+A MQ n=listTickets
+A MA n=chargeCustomer
+A MT n=tickets fields=title:text,status:text
+A AT t=S#1 kind=unit
+A WX t=S#1 file=src/index.ts
+\`\`\`
+
+## Compact aliases
+
+Queries:
+
+\`\`\`txt
+Q ST  = Q STATUS
+Q S   = Q SYMBOL
+Q D   = Q DEF
+Q R   = Q REFS
+Q I   = Q IMPACT
+Q M   = Q MODULE
+Q T   = Q TESTS
+Q API = Q DEP.API
+\`\`\`
+
+Actions:
+
+\`\`\`txt
+A RN  = A RENAME.SYMBOL
+A MV  = A MOVE.SYMBOL
+A OI  = A ORGANIZE.IMPORTS
+A FMT = A FORMAT
+A MC  = A MAKE.COMMAND
+A MQ  = A MAKE.QUERY
+A MA  = A MAKE.ACTION
+A MT  = A MAKE.TABLE
+A AT  = A ADD.TEST
+A WX  = A WIRE.EXPORT
+A AP  = A APPLY
+A RB  = A ROLLBACK
+\`\`\`
+
+## Verification
+
+After CAIR edits, run the narrowest useful checks:
+
+\`\`\`bash
+forge check --json
+forge verify --standard
+${finalVerify}
+\`\`\`
+
+## Constraints
+
+- Do not edit \`src/forge/_generated/**\` unless explicitly allowed.
+- Do not bypass \`--plan\` for semantic edits.
+- Do not use CAIR as blind text replacement when a semantic action exists.
+- Use TypeScript language service, ast-grep, ts-morph, or raw file reads only as implementation backends or fallbacks. CAIR is the agent-facing protocol.
+`));
 }