forgeos 0.1.0-alpha.4 → 0.1.0-alpha.40

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

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { nodeFileSystem } from "../fs/index.ts";
 import type { ApiSurface } from "../api-surface/build.ts";
 import type { ClassifiedPackage } from "../classifier/runtime-matrix.ts";
@@ -7,6 +7,7 @@ import { detectSecrets } from "../classifier/secrets.ts";
 import { GENERATOR_VERSION } from "../emitter/constants.ts";
 import { stripDeterministicHeader } from "../primitives/header.ts";
 import { canonicalJson, normalizeNewlines, serializeCanonical } from "../primitives/serialize.ts";
+import { toSnakeCase } from "../data-graph/sql/naming.ts";
 import { resolveByPackageName } from "../recipes/registry.ts";
 import {
   defaultRuntimeCompatibility,
@@ -34,18 +35,30 @@ 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";
@@ -53,6 +66,7 @@ import type {
 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;
@@ -74,6 +88,7 @@ export interface AgentContractInput {
   apiSurface: ApiSurface;
   clientManifest: ClientManifest;
   frontendGraph: FrontendGraph;
+  externalServices?: ForgeExternalServiceGraph;
 }
 
 export interface AgentContractArtifacts {
@@ -87,6 +102,7 @@ export interface AgentContractArtifacts {
   runtimeRulesMd: string;
   operationPlaybooksMd: string;
   agentQuickstartMd: string;
+  agentCairGuideMd: string;
   diagnostics: Diagnostic[];
 }
 
@@ -170,17 +186,188 @@ function sourceText(workspaceRoot: string, file: string | undefined): string {
   return nodeFileSystem.readText(absolute) ?? "";
 }
 
+function normalizeProjectPath(path: string): string {
+  return path.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+function isWorkspaceChild(workspaceRoot: string, absolutePath: string): boolean {
+  const relativePath = relative(resolve(workspaceRoot), absolutePath);
+  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+
+function localImportSpecifiers(text: string): string[] {
+  const specifiers: string[] = [];
+  const importPattern =
+    /\b(?:import|export)\s+(type\s+)?(?:[^"'`]*?\s+from\s+)?["'`](\.{1,2}\/[^"'`]+)["'`]/g;
+  for (const match of text.matchAll(importPattern)) {
+    if (match[1]) {
+      continue;
+    }
+    const specifier = match[2] ?? "";
+    if (specifier) {
+      specifiers.push(specifier);
+    }
+  }
+  return uniqueSorted(specifiers);
+}
+
+function resolveLocalImport(workspaceRoot: string, fromFile: string, specifier: string): string | undefined {
+  const basePath = normalizeProjectPath(join(dirname(fromFile), specifier));
+  const candidates = extname(basePath)
+    ? [basePath]
+    : [
+        `${basePath}.ts`,
+        `${basePath}.tsx`,
+        `${basePath}.js`,
+        `${basePath}.jsx`,
+        `${basePath}.mjs`,
+        `${basePath}.cjs`,
+        join(basePath, "index.ts"),
+        join(basePath, "index.tsx"),
+        join(basePath, "index.js"),
+      ];
+  for (const candidate of candidates.map(normalizeProjectPath)) {
+    if (candidate.includes("/node_modules/") || candidate.startsWith("node_modules/")) {
+      continue;
+    }
+    if (candidate.startsWith("src/forge/_generated/")) {
+      continue;
+    }
+    const absolute = resolve(workspaceRoot, candidate);
+    if (!isWorkspaceChild(workspaceRoot, absolute) || !nodeFileSystem.exists(absolute)) {
+      continue;
+    }
+    return normalizeProjectPath(relative(resolve(workspaceRoot), absolute));
+  }
+  return undefined;
+}
+
+function sourceTextWithLocalImports(
+  workspaceRoot: string,
+  file: string | undefined,
+  maxDepth = 2,
+): string {
+  if (!file) {
+    return "";
+  }
+  const chunks: string[] = [];
+  const visited = new Set<string>();
+
+  const visit = (currentFile: string, depth: number): void => {
+    const normalizedFile = normalizeProjectPath(currentFile);
+    if (visited.has(normalizedFile)) {
+      return;
+    }
+    visited.add(normalizedFile);
+    const text = sourceText(workspaceRoot, normalizedFile);
+    if (!text) {
+      return;
+    }
+    chunks.push(text);
+    if (depth >= maxDepth) {
+      return;
+    }
+    for (const specifier of localImportSpecifiers(text)) {
+      const imported = resolveLocalImport(workspaceRoot, normalizedFile, specifier);
+      if (imported) {
+        visit(imported, depth + 1);
+      }
+    }
+  };
+
+  visit(file, 0);
+  return chunks.join("\n");
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function toSnakeCaseName(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/[-\s]+/g, "_")
+    .toLowerCase();
+}
+
+function toCamelCaseName(name: string): string {
+  return name.replace(/[_-]([a-zA-Z0-9])/g, (_match, char: string) => char.toUpperCase());
+}
+
+function dbTableLookup(dataGraph: AgentContractInput["dataGraph"]): Map<string, string> {
+  const lookup = new Map<string, string>();
+  for (const table of dataGraph.tables) {
+    lookup.set(table.name, table.name);
+    lookup.set(table.exportName, table.name);
+    lookup.set(toSnakeCaseName(table.name), table.name);
+    lookup.set(toSnakeCaseName(table.exportName), table.name);
+    lookup.set(toCamelCaseName(table.name), table.name);
+    lookup.set(toCamelCaseName(table.exportName), table.name);
+  }
+  return lookup;
+}
+
+function addDbAliasesForText(
+  text: string,
+  tableLookup: Map<string, string>,
+  aliases: Map<string, string>,
+): void {
+  for (const match of text.matchAll(
+    /\b(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*ctx\.db(?:\.([A-Za-z_$][A-Za-z0-9_$]*)|\[\s*["'`]([^"'`]+)["'`]\s*\])/g,
+  )) {
+    const alias = match[1] ?? "";
+    const table = match[2] ?? match[3] ?? "";
+    const canonicalTable = tableLookup.get(table);
+    if (alias && canonicalTable) {
+      aliases.set(alias, canonicalTable);
+    }
+  }
+
+  for (const match of text.matchAll(/\b(?:const|let|var)\s*\{([^}]+)\}\s*=\s*ctx\.db/g)) {
+    const body = match[1] ?? "";
+    for (const part of body.split(",")) {
+      const [rawTable, rawAlias] = part.split(":").map((value) => value.trim());
+      const table = rawTable?.replace(/["'`]/g, "") ?? "";
+      const alias = (rawAlias ?? rawTable ?? "").replace(/\s*=.*$/, "").trim();
+      const canonicalTable = tableLookup.get(table);
+      if (canonicalTable && alias) {
+        aliases.set(alias, canonicalTable);
+      }
+    }
+  }
+}
+
 function dbTablesForText(
   text: string,
-  tableNames: Set<string>,
+  tableLookup: Map<string, string>,
   ops: Set<string>,
 ): string[] {
   const tables: string[] = [];
   for (const match of text.matchAll(/ctx\.db\.([A-Za-z_$][A-Za-z0-9_$]*)\s*\.\s*([A-Za-z_$][A-Za-z0-9_$]*)/g)) {
     const table = match[1] ?? "";
     const op = match[2] ?? "";
-    if (tableNames.has(table) && ops.has(op)) {
-      tables.push(table);
+    const canonicalTable = tableLookup.get(table);
+    if (canonicalTable && ops.has(op)) {
+      tables.push(canonicalTable);
+    }
+  }
+  for (const match of text.matchAll(/ctx\.db\s*\[\s*["'`]([^"'`]+)["'`]\s*\]\s*\.\s*([A-Za-z_$][A-Za-z0-9_$]*)/g)) {
+    const table = match[1] ?? "";
+    const op = match[2] ?? "";
+    const canonicalTable = tableLookup.get(table);
+    if (canonicalTable && ops.has(op)) {
+      tables.push(canonicalTable);
+    }
+  }
+  const aliases = new Map<string, string>();
+  addDbAliasesForText(text, tableLookup, aliases);
+  for (const [alias, table] of aliases) {
+    const aliasPattern = new RegExp(`\\b${escapeRegExp(alias)}\\s*\\.\\s*([A-Za-z_$][A-Za-z0-9_$]*)`, "g");
+    for (const match of text.matchAll(aliasPattern)) {
+      const op = match[1] ?? "";
+      if (ops.has(op)) {
+        tables.push(table);
+      }
     }
   }
   return uniqueSorted(tables);
@@ -189,14 +376,14 @@ function dbTablesForText(
 function dbTablesForFile(
   workspaceRoot: string,
   file: string | undefined,
-  tableNames: Set<string>,
+  tableLookup: Map<string, string>,
   ops: Set<string>,
 ): string[] {
-  return dbTablesForText(sourceText(workspaceRoot, file), tableNames, ops);
+  return dbTablesForText(sourceTextWithLocalImports(workspaceRoot, file), tableLookup, ops);
 }
 
 function emittedEventsForFile(workspaceRoot: string, file: string | undefined): string[] {
-  const text = sourceText(workspaceRoot, file);
+  const text = sourceTextWithLocalImports(workspaceRoot, file);
   return uniqueSorted(
     [...text.matchAll(/ctx\.emit\s*\(\s*["'`]([^"'`]+)["'`]/g)]
       .map((match) => match[1] ?? ""),
@@ -248,7 +435,7 @@ function runtimeRules(): AgentRuntimeRule[] {
     {
       context: "command",
       allowed: ["ctx.db writes", "ctx.emit", "ctx.telemetry buffered events"],
-      forbidden: ["network packages", "ctx.secrets", "ctx.ai", "ctx.ai.runAgent", "ctx.agent.run", "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",
@@ -273,6 +460,104 @@ function runtimeRules(): AgentRuntimeRule[] {
   ];
 }
 
+type TenantTableInfo = {
+  tenantIdColumn: string;
+  tenantField: string;
+};
+
+function buildTenantTableLookup(tenantScope: TenantScope, dataGraph: DataGraph): Map<string, TenantTableInfo> {
+  const lookup = new Map<string, TenantTableInfo>();
+  for (const scoped of tenantScope.tables) {
+    const table = dataGraph.tables.find((candidate) =>
+      candidate.name === scoped.table ||
+      candidate.exportName === scoped.exportName ||
+      toSnakeCase(candidate.name) === scoped.table ||
+      toSnakeCase(candidate.exportName) === scoped.table
+    );
+    const tenantField = table?.fields.find((field) => toSnakeCase(field.name) === scoped.tenantIdColumn)?.name ??
+      scoped.tenantIdColumn;
+    const info = { tenantIdColumn: scoped.tenantIdColumn, tenantField };
+    for (const key of uniqueSorted([
+      scoped.table,
+      scoped.exportName,
+      table?.name,
+      table?.exportName,
+    ].filter((key): key is string => typeof key === "string" && key.length > 0))) {
+      lookup.set(key, info);
+    }
+  }
+  return lookup;
+}
+
+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 [
     {
@@ -341,7 +626,7 @@ function playbooks(): AgentPlaybook[] {
         "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 all --json and confirm agentContract.ai.agents lists the agent.",
+        "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.",
       ],
     },
@@ -358,7 +643,7 @@ function playbooks(): AgentPlaybook[] {
     {
       title: "Scaffold a resource",
       steps: [
-        "Run forge make resource <name> --fields name:type,status:enum(open,closed) --dry-run --json.",
+        "Run forge make resource <name> --fields name:type,status:enum=open+closed --dry-run --json.",
         "Review the plan and diagnostics.",
         "Run forge make resource <name> --fields name:type --with-ui --yes when the resource should be visible in the web app.",
         "Run forge generate.",
@@ -447,17 +732,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.",
+        "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 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.",
+        "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.",
@@ -536,7 +821,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.",
+        ],
       });
     }
   }
@@ -557,7 +846,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.",
+        ],
       });
     }
   }
@@ -703,9 +996,15 @@ function buildAgentToolRegistry(contract: AgentContract): AgentToolRegistry {
       dependencies: [],
       readOnly: false,
       risk: "write" as const,
-      needsApproval: true,
+      needsApproval: command.source === "external"
+        ? command.external?.needsApproval ?? (command.external?.risk !== "read")
+        : true,
       requiresAuth: command.policy !== undefined && command.policy !== "public",
-      execution: "forge-runtime-endpoint" as const,
+      ...(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),
@@ -723,7 +1022,11 @@ function buildAgentToolRegistry(contract: AgentContract): AgentToolRegistry {
       risk: "read" as const,
       needsApproval: false,
       requiresAuth: query.policy !== undefined && query.policy !== "public",
-      execution: "forge-runtime-endpoint" as const,
+      ...(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),
@@ -741,6 +1044,7 @@ function buildAgentToolRegistry(contract: AgentContract): AgentToolRegistry {
       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));
@@ -794,6 +1098,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",
@@ -901,9 +1238,7 @@ export function buildAgentContractArtifacts(
   input: AgentContractInput,
 ): AgentContractArtifacts {
   const project = readPackageInfo(input.workspaceRoot);
-  const tenantTables = new Map(
-    input.tenantScope.tables.map((table) => [table.table, table.tenantIdColumn]),
-  );
+  const tenantTables = buildTenantTableLookup(input.tenantScope, input.dataGraph);
   const commandAuth = new Map(
     input.policyRegistry.commandAuth.map((binding) => [binding.commandName, binding.auth]),
   );
@@ -915,16 +1250,18 @@ 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 tableLookup = dbTableLookup(input.dataGraph);
+  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),
+      tablesRead: dbTablesForFile(input.workspaceRoot, file, tableLookup, DB_READ_OPS),
+      tablesWritten: dbTablesForFile(input.workspaceRoot, file, tableLookup, DB_WRITE_OPS),
       emits: emittedEventsForFile(input.workspaceRoot, file),
       allowedPackages: entry ? packageNamesForModule(input.appGraph, entry.moduleId) : [],
       forbiddenCapabilities: forbiddenForContext(input.classified, "command"),
@@ -932,21 +1269,62 @@ 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,
-    tablesRead: dbTablesForFile(input.workspaceRoot, query.file, tableNames, DB_READ_OPS),
+    tablesRead: dbTablesForFile(input.workspaceRoot, query.file, tableLookup, DB_READ_OPS),
     allowedPackages: packageNamesForModule(input.appGraph, query.moduleId),
     forbiddenCapabilities: forbiddenForContext(input.classified, "query"),
     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);
+      const tablesRead = dbTablesForFile(input.workspaceRoot, liveQuery.file, tableLookup, DB_READ_OPS);
       return {
         name: liveQuery.name,
         file: liveQuery.file,
@@ -968,6 +1346,7 @@ export function buildAgentContractArtifacts(
     queries: queryInfos,
     liveQueries: liveQueryInfos,
   });
+  const protocols = agentProtocols(input.workspaceRoot);
   const contract: AgentContract = {
     schemaVersion: "0.1.0",
     generatorVersion: GENERATOR_VERSION,
@@ -1003,18 +1382,22 @@ export function buildAgentContractArtifacts(
       }),
     ),
     data: {
-      tables: sorted(input.dataGraph.tables, (table) => table.name).map((table) => ({
-        name: table.name,
-        file: table.file,
-        tenantScoped: tenantTables.has(table.name),
-        ...(tenantTables.has(table.name) ? { tenantField: tenantTables.get(table.name) } : {}),
-        fields: uniqueSorted(table.fields.map((field) => field.name)),
-      })),
+      tables: sorted(input.dataGraph.tables, (table) => table.name).map((table) => {
+        const tenantInfo = tenantTables.get(table.name);
+        return {
+          name: table.name,
+          file: table.file,
+          tenantScoped: Boolean(tenantInfo),
+          ...(tenantInfo ? { tenantField: tenantInfo.tenantField } : {}),
+          fields: uniqueSorted(table.fields.map((field) => field.name)),
+        };
+      }),
     },
     policies: sorted(input.policyRegistry.policies, (policy) => policy.name).map((policy) => ({
       name: policy.name,
       kind: policy.kind,
       roles: uniqueSorted(policy.roles),
+      permissions: uniqueSorted(policy.permissions ?? []),
       file: policy.file,
     })),
     packages: sorted(input.packageGraph.packages, (pkg) => pkg.name).map((pkg) => {
@@ -1028,6 +1411,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,
@@ -1141,10 +1537,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"]),
     },
   };
 
@@ -1153,7 +1550,7 @@ 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);
@@ -1161,7 +1558,8 @@ export function buildAgentContractArtifacts(
   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,
@@ -1170,6 +1568,7 @@ export function buildAgentContractArtifacts(
     runtimeRulesMd,
     operationPlaybooksMd,
     agentQuickstartMd,
+    agentCairGuideMd,
   ]);
 
   return {
@@ -1183,6 +1582,7 @@ export function buildAgentContractArtifacts(
     runtimeRulesMd,
     operationPlaybooksMd,
     agentQuickstartMd,
+    agentCairGuideMd,
     diagnostics: [...diagnostics, ...capabilityMap.diagnostics],
   };
 }
@@ -1229,7 +1629,22 @@ export function serializeAgentToolRegistryTs(registry: AgentToolRegistry): strin
   return `export const agentTools = ${JSON.stringify(parsed, null, 2)} as const;\n`;
 }
 
-function renderAgentsMd(contract: AgentContract, userNotes: string): string {
+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}`);
@@ -1244,7 +1659,7 @@ function renderAgentsMd(contract: AgentContract, userNotes: string): string {
     `${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 -->
 
@@ -1252,23 +1667,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
@@ -1296,7 +1739,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.
@@ -1310,8 +1753,10 @@ 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
@@ -1328,12 +1773,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
@@ -1388,9 +1834,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
@@ -1413,16 +1859,17 @@ 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
 
 Use:
 
 \`\`\`bash
-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 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
 \`\`\`
 
@@ -1439,7 +1886,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
 
@@ -1479,7 +1926,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
 
@@ -1498,7 +1945,8 @@ Use:
 
 \`\`\`bash
 forge generate
-forge inspect all --json
+forge inspect ai --json
+forge agent print-context --json
 forge ai check --json
 forge ai trace <traceId> --json
 \`\`\`
@@ -1537,7 +1985,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.
@@ -1558,10 +2006,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 {
@@ -1922,21 +2371,27 @@ 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
 \`\`\`
@@ -1954,7 +2409,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.
+`));
 }