forgeos 0.1.0-alpha.22 → 0.1.0-alpha.24

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.22 input=d8837238db9cf8868eceae3e3cc5a7d9bb46a0955c55f0143caa802597d5a3a5 content=0d493cf0e41b71cb652d5e0e1b0c1f83d2a1281b748321f0b00f0773ba93074e
+// @forge-generated generator=0.1.0-alpha.24 input=1257771517e723f30d9c8c6bdc328f3a9d0bfde1e673d859837f93f0f1bd15c4 content=0d493cf0e41b71cb652d5e0e1b0c1f83d2a1281b748321f0b00f0773ba93074e
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## Unreleased
 
+## 0.1.0-alpha.24
+
+### Patch Changes
+
+- Consolidate the public alpha adoption surface and agent-contract positioning.
+
+  - Add an explicit MIT `LICENSE`, package license metadata, and a private GitHub Security Advisory disclosure path.
+  - Add stable-alpha, AI-coding, agent demo, Convex, and agent-eval documentation pages, plus a runner-agnostic eval task scaffold.
+  - Fix `forge new --json` so scaffold automation receives structured JSON instead of human next-step text.
+  - Add the first `forge add convex` app-contract recipe with runtime placement guardrails, optional Convex environment names, generated docs, and a mock testkit.
+  - Expand field-report expectations and package/release tests for license, security disclosure, docs, create-app help, Convex recipes, and JSON scaffold output.
+
+## 0.1.0-alpha.23
+
+### Patch Changes
+
+- Tighten the post-alpha.22 release surface and package evidence.
+
+  - Add a dedicated Nuxt template smoke workflow that installs `nuxt-web`, runs Forge generation/checks, runs Nuxt typecheck, and probes `forge dev --once`.
+  - Include `nuxt-web` in the default field-test template matrix.
+  - Add explicit `scopeTarget` metadata and human-readable target output for `forge agent context --change`, `--proof`, and `--handoff`.
+  - Teach `forge explain` to fall back to the current generated agent contract when DeltaDB has no runtime history, while marking the result as contract-defined instead of executed.
+  - Downgrade read-only observation commands such as `forge status`, `forge changed`, `forge handoff`, `forge explain`, `forge timeline`, and CAIR queries to low-confidence context-gathering sessions in DeltaDB.
+  - Package `docs/cair-protocol.md` in the npm tarball and expand the public security/threat-model docs for DeltaDB, agent memory, CAIR, Studio bridge, brownfield import, and Nuxt surfaces.
+
 ## 0.1.0-alpha.22
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeOS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # ForgeOS
 
-Agent-native application framework and compiler for building Forge apps without a mandatory dashboard. ForgeOS turns application source into deterministic runtime contracts, generated clients, safety checks, and machine-readable context that humans and AI coding agents can use safely.
+The contract layer for agentic software development. ForgeOS turns application source into deterministic runtime contracts, generated clients, safety checks, and machine-readable context that humans and AI coding agents can use safely.
 
 **Status:** private/public alpha MVP, implemented through H49. ForgeOS already includes the compiler, local runtime, frontend SDK, production auth, RLS compiler, liveQuery, self-host artifacts, generated agent contract, guided dev loop, repair/review/test tooling, AST-aware codemods, package intelligence, native AI tools/agents, DeltaDB work memory, external agent memory ingestion, brownfield import analysis, npm alpha publishing, and Read the Docs public docs. Public release hardening is still focused on deeper semantic codemods, broader field reports, and more production mileage.
 
@@ -8,7 +8,7 @@ Public docs live at [forgeos.readthedocs.io](https://forgeos.readthedocs.io/). T
 
 Start with [Why ForgeOS](https://forgeos.readthedocs.io/en/latest/why-forgeos/) to understand the agent-native design.
 
-For the short version, read [The Five-Minute ForgeOS Model](https://forgeos.readthedocs.io/en/latest/five-minute-model/) and [Alpha Golden Path](https://forgeos.readthedocs.io/en/latest/golden-path/). The important distinction is that external coding agents are the primary ForgeOS workflow; integrated AI SDK features are available for apps that need in-product AI, but they are not the main development loop.
+For the short version, read [The Five-Minute ForgeOS Model](https://forgeos.readthedocs.io/en/latest/five-minute-model/), [Alpha Golden Path](https://forgeos.readthedocs.io/en/latest/golden-path/), and [Stable Alpha Surface](https://forgeos.readthedocs.io/en/latest/stable-alpha/). The important distinction is that external coding agents are the primary ForgeOS workflow; integrated AI SDK features are available for apps that need in-product AI, but they are not the main development loop.
 
 ## Agent-First Quickstart
 

package/docs/cair-protocol.md

@@ -0,0 +1,103 @@
+# CAIR Protocol
+
+CAIR is ForgeOS' compact agent interface for reading code structure, querying symbols, and planning safe edits without loading the whole repository into an agent context window.
+
+CAIR is intentionally CLI-first. It does not add a second mutating tool surface. Agents should use CAIR to inspect structure and create reviewable plans, then apply those plans through the ForgeOS CLI with hash checks and rollback journals.
+
+## Read Workflow
+
+Start with a compact snapshot:
+
+```bash
+forge cair snapshot
+forge cair query "Q STATUS"
+forge cair query "Q ST"
+```
+
+Use symbol, definition, reference, impact, and dependency API queries before opening large files:
+
+```bash
+forge cair query "Q S name=createTicket"
+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 DEP.API package=zod symbol=object"
+```
+
+The goal is to make agent navigation evidence-backed: CAIR gives stable ids for modules, symbols, packages, APIs, and tests so an agent can select a small file set instead of scanning the whole project.
+
+## Action Safety
+
+Mutating CAIR actions should be planned first:
+
+```bash
+forge cair action --plan "A RN t=S#1 nn=openTicket"
+```
+
+The plan lives under `.forge/cair/plans/` and records the target files and expected hashes. Applying a plan checks those hashes before editing:
+
+```bash
+forge cair action "A APPLY plan=<P#|.forge/cair/plans/...json>"
+```
+
+Applied plans write rollback journals under `.forge/cair/journal/`:
+
+```bash
+forge cair action "A ROLLBACK journal=.forge/cair/journal/<journal>.json"
+```
+
+Use `--dry-run` when exploring an action shape without creating a plan:
+
+```bash
+forge cair action --dry-run "A CREATE.SYMBOL path=src/example.ts kind=function name=example export=true createFile=true"
+```
+
+Generated files stay protected by default. Use `--include-generated` only when the edit is intentionally about generated artifacts.
+
+## DeltaDB Evidence
+
+Successful CAIR CLI runs are recorded in DeltaDB as sanitized operational events:
+
+| CAIR command | Delta event |
+|--------------|-------------|
+| `forge cair snapshot` | `cair.snapshot.created` |
+| `forge cair query ...` | `cair.query.run` |
+| `forge cair action --plan ...` | `cair.plan.created` |
+| `forge cair action "A APPLY ..."` | `cair.plan.applied` |
+| `forge cair action --dry-run ...` | `cair.action.previewed` |
+
+The recorder stores compact verbs such as `Q ST` or `A APPLY`; it does not need to store full action bodies as first-class timeline data. Use:
+
+```bash
+forge timeline cair:protocol --json
+forge timeline --kind cair.plan.applied --json
+```
+
+This makes CAIR navigation and guarded edits visible beside file changes, proofs, and agent activity.
+
+## Compact Aliases
+
+| Long form | Compact |
+|-----------|---------|
+| `Q STATUS` | `Q ST` |
+| `Q SYMBOL` | `Q S` |
+| `Q DEF` | `Q D` |
+| `Q REFS` | `Q R` |
+| `Q IMPACT` | `Q I` |
+| `A RENAME.SYMBOL target=S#1 newName=x` | `A RN t=S#1 nn=x` |
+
+## Agent Posture
+
+Use this loop for code work:
+
+```bash
+forge cair snapshot
+forge cair query "Q ST"
+forge cair query "Q S name=<symbol>"
+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 check --json
+```
+
+Do not use CAIR as a bypass around ForgeOS rules. Commands remain transactional writes, queries and liveQueries remain read-only, side effects still belong in actions and workflows, and generated artifacts remain derived.

package/docs/changelog.md

@@ -6,6 +6,39 @@ The canonical source file in the repository is `CHANGELOG.md`.
 
 ## Unreleased
 
+## 0.1.0-alpha.24
+
+- Consolidated the public alpha adoption surface: MIT license, package license
+  metadata, private GitHub Security Advisory disclosure, stable-alpha status
+  matrix, AI-coding loop, three short agent demos, and repeatable agent eval
+  task specs.
+- `forge new --json` now returns structured JSON for scaffold automation
+  instead of human next-step text.
+- Added the initial `forge add convex` app-contract recipe with runtime
+  placement guardrails, optional Convex environment names, generated docs, and
+  a mock testkit. The deeper Convex schema/API importer is documented as
+  planned rather than implied.
+- Expanded field-report expectations and release/doc tests for license,
+  security disclosure, create-app help, Convex recipes, and public docs
+  navigation.
+
+## 0.1.0-alpha.23
+
+- Tightened the post-alpha.22 release surface and package evidence:
+  added a dedicated Nuxt template smoke workflow, included `nuxt-web` in the
+  default field-test template matrix, packaged `docs/cair-protocol.md`, and
+  expanded the security/threat-model docs for DeltaDB, agent memory, CAIR,
+  Studio bridge, brownfield import, and Nuxt surfaces.
+- `forge agent context` now returns explicit `scopeTarget` metadata and prints
+  the resolved context target for entry, change, proof, and handoff packs.
+- `forge explain` now falls back to the current generated agent contract when
+  DeltaDB has no runtime history, marking the entry as contract-defined rather
+  than executed.
+- DeltaDB work-session inference now treats read-only observation commands such
+  as `forge status`, `forge changed`, `forge handoff`, `forge explain`,
+  `forge timeline`, and CAIR queries as low-confidence context-gathering
+  sessions.
+
 ## 0.1.0-alpha.22
 
 - Added focused post-alpha.21 workflow improvements without expanding MCP tools:

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.22",
+  "version": "0.1.0-alpha.24",
   "description": "Agent-native application framework and compiler for building Forge apps without a mandatory dashboard.",
   "type": "module",
+  "license": "MIT",
   "files": [
     "adapters/",
     "bin/",
+    "docs/cair-protocol.md",
     "docs/forge-protocol.md",
     "examples/go-billing/",
     "examples/java-billing/",
@@ -17,6 +19,7 @@
     "src/forge/_generated/releaseManifest.ts",
     "templates/",
     "README.md",
+    "LICENSE",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "AGENTS.md",

package/src/forge/_generated/releaseManifest.json

@@ -1 +1 @@
-{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.22","releaseId":"forgeos@0.1.0-alpha.22+unknown","schemaVersion":"0.1.0"}
+{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.24","releaseId":"forgeos@0.1.0-alpha.24+unknown","schemaVersion":"0.1.0"}

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.22 input=d8837238db9cf8868eceae3e3cc5a7d9bb46a0955c55f0143caa802597d5a3a5 content=bb05ee3635ddeea2d84168f8bf728e07f82e896061e8494b17f56dea26000770
+// @forge-generated generator=0.1.0-alpha.24 input=1257771517e723f30d9c8c6bdc328f3a9d0bfde1e673d859837f93f0f1bd15c4 content=4170e33ff26cbaa55732ed4f507f83f2ece3812a1c2184614337c8be91110499
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.22",
-  "releaseId": "forgeos@0.1.0-alpha.22+unknown",
+  "packageVersion": "0.1.0-alpha.24",
+  "releaseId": "forgeos@0.1.0-alpha.24+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/agent-memory/bridge.ts

@@ -1021,6 +1021,7 @@ function formatAgentMemoryContextHuman(result: AgentMemoryContextPack): string {
   const lines = [
     `Forge Agent Context (${result.scope}${result.entry ? `: ${result.entry}` : ""})`,
     "",
+    `target: ${formatAgentContextTarget(result)}`,
     `events: ${summary.events}`,
     `sources: ${summary.sources.length > 0 ? summary.sources.join(", ") : "none"}`,
     `tools: ${summary.tools.length > 0 ? summary.tools.join(", ") : "none"}`,
@@ -1067,6 +1068,21 @@ function formatAgentMemoryContextHuman(result: AgentMemoryContextPack): string {
   return `${lines.join("\n")}\n`;
 }
 
+function formatAgentContextTarget(result: AgentMemoryContextPack): string {
+  const target = result.scopeTarget;
+  const parts: string[] = [target.kind];
+  if (target.value) {
+    parts.push(target.value);
+  }
+  if (target.semanticTarget && target.semanticTarget !== target.value) {
+    parts.push(`semantic=${target.semanticTarget}`);
+  }
+  if (target.currentSessionId) {
+    parts.push(`session=${target.currentSessionId}`);
+  }
+  return parts.join(" ");
+}
+
 function formatAgentMemoryEventsHuman(events: AgentMemoryEventRecord[]): string {
   const sources = uniqueStrings(events.map((event) => event.sourceName));
   const tools = uniqueStrings(events.flatMap((event) => {

package/src/forge/agent-memory/context-pack.ts

@@ -48,6 +48,7 @@ export async function buildAgentMemoryContext(input: {
     return {
       ok: true,
       scope,
+      scopeTarget: contextScopeTarget(input, scope, target, currentSession?.id),
       entry: input.entry,
       change: input.change,
       proof: input.proof,
@@ -117,6 +118,33 @@ function contextTarget(
   return undefined;
 }
 
+function contextScopeTarget(
+  input: { entry?: string; change?: string; proof?: string; handoff?: boolean },
+  scope: AgentMemoryContextPack["scope"],
+  semanticTarget: string | undefined,
+  currentSessionId: string | undefined,
+): AgentMemoryContextPack["scopeTarget"] {
+  if (scope === "entry") {
+    return { kind: "entry", value: input.entry, semanticTarget };
+  }
+  if (scope === "proof") {
+    return { kind: "proof", value: input.proof, semanticTarget };
+  }
+  if (scope === "change") {
+    const value = input.change ?? "current";
+    return {
+      kind: "change",
+      value,
+      ...(semanticTarget ? { semanticTarget } : {}),
+      ...(value === "current" && currentSessionId ? { currentSessionId } : {}),
+    };
+  }
+  if (scope === "handoff") {
+    return { kind: "handoff", value: "handoff", currentSessionId };
+  }
+  return { kind: "current-session", value: "current", currentSessionId };
+}
+
 function eventTarget(
   input: { entry?: string; change?: string; proof?: string },
   scope: AgentMemoryContextPack["scope"],

package/src/forge/agent-memory/types.ts

@@ -93,6 +93,12 @@ export interface AgentMemoryContextEvent {
 export interface AgentMemoryContextPack {
   ok: true;
   scope: "current" | "entry" | "change" | "proof" | "handoff";
+  scopeTarget: {
+    kind: "current-session" | "entry" | "change" | "proof" | "handoff";
+    value?: string;
+    semanticTarget?: string;
+    currentSessionId?: string;
+  };
   entry?: string;
   change?: string;
   proof?: string;

package/src/forge/cli/commands.ts

@@ -168,7 +168,7 @@ import {
   runSecretsCommand,
 } from "./secrets.ts";
 import { formatAiHuman, formatAiJson, runAiCommand } from "./ai.ts";
-import { formatNewHuman, runNewCommand } from "./new.ts";
+import { formatNewHuman, formatNewJson, runNewCommand } from "./new.ts";
 import { formatBuildHuman, runBuildCommand } from "./build.ts";
 import { runServeCommand } from "./serve.ts";
 import { runWorkerCommand } from "./worker.ts";
@@ -1559,7 +1559,7 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
         localForge: command.localForge,
         workspaceRoot: command.workspaceRoot,
       });
-      process.stdout.write(formatNewHuman(result));
+      process.stdout.write(command.json ? formatNewJson(result) : formatNewHuman(result));
       return result.exitCode;
     }
     case "build": {

package/src/forge/cli/new.ts

@@ -535,3 +535,11 @@ export function formatNewHuman(result: NewCommandResult): string {
     "",
   ].join("\n");
 }
+
+export function formatNewJson(result: NewCommandResult): string {
+  return `${JSON.stringify({
+    schemaVersion: "0.1.0",
+    ok: result.exitCode === 0,
+    ...result,
+  }, null, 2)}\n`;
+}

package/src/forge/cli/parse.ts

@@ -63,6 +63,7 @@ export type ForgeCommand =
       git: boolean;
       forgePackageSpec?: string;
       localForge: boolean;
+      json: boolean;
       workspaceRoot: string;
     }
   | { kind: "build"; json: boolean; workspaceRoot: string }
@@ -860,6 +861,7 @@ export function parseCli(argv: string[]): ParsedCli {
           git: !parseFlag(argv, "--no-git"),
           forgePackageSpec,
           localForge,
+          json: parseFlag(argv, "--json"),
           workspaceRoot,
         },
         workspaceRoot,

package/src/forge/compiler/integration/add.ts

@@ -549,7 +549,7 @@ export async function forgeAdd(
     const error = createDiagnostic({
       severity: "error",
       code: "FORGE_UNKNOWN_ALIAS",
-      message: `unknown integration alias '${alias}'; supported: stripe, posthog, sentry, zod, ai. For npm packages, use 'forge add package ${alias}' or 'forge add ${alias}'.`,
+      message: `unknown integration alias '${alias}'; supported: stripe, posthog, sentry, zod, convex, ai. For npm packages, use 'forge add package ${alias}' or 'forge add ${alias}'.`,
       suggestedCommands: [`forge add package ${alias} --dry-run --json`, "forge add --help"],
     });
     return finalizeAddResult({

package/src/forge/compiler/integration/templates/convex.ts

@@ -0,0 +1,70 @@
+import type { IntegrationTemplateInput } from "./types.ts";
+
+export function renderConvexTestkit(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated mock testkit for Convex app-contract evaluation. */",
+    "export interface ConvexFunctionRef {",
+    "  readonly kind: \"query\" | \"mutation\" | \"action\";",
+    "  readonly path: string;",
+    "}",
+    "",
+    "export function createConvexMock(functions: ConvexFunctionRef[] = []) {",
+    "  const calls: Array<{ path: string; args: unknown }> = [];",
+    "  return {",
+    "    functions,",
+    "    calls,",
+    "    call(path: string, args: unknown = {}) {",
+    "      calls.push({ path, args });",
+    "      return { ok: true, path, args } as const;",
+    "    },",
+    "  } as const;",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderConvexDoc(input: IntegrationTemplateInput): string {
+  return [
+    "# Convex integration",
+    "",
+    "Generated by Forge (recipe v1).",
+    "",
+    "Convex is treated as an agent-friendly backend package. ForgeOS treats it as an app-contract integration surface: package placement, frontend/backend usage, generated docs, and future function-map import.",
+    "",
+    "## Runtime placement",
+    "",
+    "- Use Convex client hooks and generated Convex APIs in frontend/client code.",
+    "- Use Convex server/admin clients only from server, action, workflow, or endpoint contexts.",
+    "- Do not import Convex runtime clients from Forge commands, queries, or liveQueries.",
+    "- Type-only imports are acceptable when the TypeScript compiler erases them.",
+    "",
+    "## App-contract import targets",
+    "",
+    "Future Convex import support should inspect:",
+    "",
+    "- `convex/schema.ts` for table names and fields;",
+    "- `convex/_generated/api.d.ts` for query, mutation, and action references;",
+    "- frontend `useQuery`, `useMutation`, and `useAction` calls for route/component capability mapping;",
+    "- auth and deployment notes from Convex config files.",
+    "",
+    "## Commands",
+    "",
+    "```bash",
+    "forge add convex",
+    "forge deps inspect convex --json",
+    "forge inspect runtime-matrix --json",
+    "forge check --json",
+    "```",
+    "",
+    "## Generated evidence",
+    "",
+    `Compatible contexts: ${input.compatible.join(", ")}`,
+    "",
+    `Incompatible contexts: ${input.incompatible.join(", ")}`,
+    "",
+    "Optional environment names:",
+    "",
+    ...input.secrets.map((secret) => `- ${secret.envVar}`),
+    "",
+  ].join("\n");
+}

package/src/forge/compiler/integration/templates/render.ts

@@ -1,5 +1,6 @@
 import type { IntegrationTemplateInput } from "./types.ts";
 import * as ai from "./ai.ts";
+import * as convex from "./convex.ts";
 import * as posthog from "./posthog.ts";
 import * as sentry from "./sentry.ts";
 import * as stripe from "./stripe.ts";
@@ -52,6 +53,7 @@ const TESTKIT_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
   stripe: { "stripe.mock.ts": stripe.renderStripeTestkit },
   posthog: { "posthog.mock.ts": posthog.renderPosthogTestkit },
   sentry: { "sentry.mock.ts": sentry.renderSentryTestkit },
+  convex: { "convex.mock.ts": convex.renderConvexTestkit },
   ai: { "ai.mock.ts": ai.renderAiTestkitLegacy },
 };
 
@@ -60,6 +62,7 @@ const DOC_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
   stripe: { "stripe.md": stripe.renderStripeDoc },
   posthog: { "posthog.md": posthog.renderPosthogDoc },
   sentry: { "sentry.md": sentry.renderSentryDoc },
+  convex: { "convex.md": convex.renderConvexDoc },
   ai: { "ai.md": ai.renderAiDoc },
 };
 

package/src/forge/compiler/recipes/definitions.ts

@@ -190,6 +190,30 @@ export const ZOD_RECIPE: IntegrationRecipe = {
   docs: ["zod.md"],
 };
 
+export const CONVEX_RECIPE: IntegrationRecipe = {
+  alias: "convex",
+  packages: [{ packageName: "convex" }],
+  supportedVersionRange: ">=1.0.0",
+  recipeVersion: "1.0.0",
+  contexts: {
+    allowed: ["client", "server", "action", "workflow", "endpoint", "test", "build"],
+    denied: ["shared", "query", "liveQuery", "command", "edge"],
+  },
+  capabilities: networkCapability(
+    ["*.convex.cloud", "*.convex.site"],
+    ["recipe:convex", "Convex client/server package connects to Convex deployments"],
+  ),
+  secrets: [
+    secret("NEXT_PUBLIC_CONVEX_URL", false),
+    secret("CONVEX_URL", false),
+    secret("CONVEX_DEPLOYMENT", false),
+    secret("CONVEX_DEPLOY_KEY", false),
+  ],
+  adapters: [],
+  testkits: ["convex.mock.ts"],
+  docs: ["convex.md"],
+};
+
 export const FORGE_RECIPE: IntegrationRecipe = {
   alias: "forge",
   packages: [{ packageName: "forge" }],
@@ -283,6 +307,7 @@ export const REFERENCE_ALIASES = [
   "posthog",
   "sentry",
   "zod",
+  "convex",
   "ai",
 ] as const;
 

package/src/forge/compiler/recipes/index.ts

@@ -15,6 +15,7 @@ export {
   POSTHOG_RECIPE,
   SENTRY_RECIPE,
   ZOD_RECIPE,
+  CONVEX_RECIPE,
   AI_RECIPE,
   AI_PROVIDER_RECIPES,
 } from "./definitions.ts";

package/src/forge/compiler/recipes/registry.ts

@@ -3,6 +3,7 @@ import type { PackageRecipe } from "../types/integration.ts";
 import {
   AI_PROVIDER_RECIPES,
   AI_RECIPE,
+  CONVEX_RECIPE,
   FORGE_RECIPE,
   POSTHOG_RECIPE,
   REFERENCE_ALIASES,
@@ -23,6 +24,7 @@ const REFERENCE_RECIPES: Record<string, IntegrationRecipe> = {
   posthog: POSTHOG_RECIPE,
   sentry: SENTRY_RECIPE,
   zod: ZOD_RECIPE,
+  convex: CONVEX_RECIPE,
   forge: FORGE_RECIPE,
   ai: AI_RECIPE,
 };
@@ -32,6 +34,7 @@ const ALL_RECIPES: IntegrationRecipe[] = [
   POSTHOG_RECIPE,
   SENTRY_RECIPE,
   ZOD_RECIPE,
+  CONVEX_RECIPE,
   FORGE_RECIPE,
   AI_RECIPE,
   ...AI_PROVIDER_RECIPES,

package/src/forge/delta/explain.ts

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { DeltaStore } from "./store.ts";
 
 export interface DeltaExplainResult {
@@ -13,10 +15,11 @@ export async function runDeltaExplain(input: {
 }): Promise<DeltaExplainResult> {
   const store = await DeltaStore.open(input.workspaceRoot, { access: "read" });
   try {
+    const explanation = await store.explain(input.thing);
     return {
       ok: true,
       thing: input.thing,
-      explanation: await store.explain(input.thing),
+      explanation: enrichWithCurrentAgentContract(input.workspaceRoot, input.thing, explanation),
       exitCode: 0,
     };
   } finally {
@@ -68,6 +71,9 @@ export function formatDeltaExplainHuman(result: DeltaExplainResult): string {
     lines.push("Runtime:");
     lines.push(`  kind: ${String(runtime.entry_kind ?? "unknown")}`);
     lines.push(`  result: ${String(runtime.result ?? "unknown")}`);
+    if (runtime.source) {
+      lines.push(`  source: ${String(runtime.source)}`);
+    }
     if (runtime.diagnostic_code) {
       lines.push(`  diagnostic: ${String(runtime.diagnostic_code)}`);
     }
@@ -94,6 +100,22 @@ export function formatDeltaExplainHuman(result: DeltaExplainResult): string {
       }
     }
   }
+  const currentContract = explanation.currentContract as Record<string, unknown> | null | undefined;
+  if (currentContract) {
+    lines.push("");
+    lines.push("Current contract:");
+    lines.push(`  kind: ${String(currentContract.kind ?? "unknown")}`);
+    lines.push(`  name: ${String(currentContract.name ?? result.thing)}`);
+    if (currentContract.auth) {
+      lines.push(`  auth: ${String(currentContract.auth)}`);
+    }
+    if (currentContract.policy) {
+      lines.push(`  policy: ${String(currentContract.policy)}`);
+    }
+    if (currentContract.sourceFile) {
+      lines.push(`  file: ${String(currentContract.sourceFile)}`);
+    }
+  }
   lines.push("");
   lines.push("Introduced in:");
   if (workSessions.length === 0) {
@@ -124,3 +146,93 @@ export function formatDeltaExplainHuman(result: DeltaExplainResult): string {
 export function formatDeltaExplainJson(result: DeltaExplainResult): string {
   return `${JSON.stringify(result, null, 2)}\n`;
 }
+
+function enrichWithCurrentAgentContract(
+  workspaceRoot: string,
+  thing: string,
+  explanation: Record<string, unknown>,
+): Record<string, unknown> {
+  const currentContract = currentContractForThing(workspaceRoot, thing);
+  if (!currentContract) {
+    return explanation;
+  }
+  const runtime = explanation.runtime && typeof explanation.runtime === "object"
+    ? explanation.runtime as Record<string, unknown>
+    : null;
+  return {
+    ...explanation,
+    type: explanation.type === "unknown" ? "runtime-entry" : explanation.type,
+    runtime: runtime ?? {
+      entry_name: currentContract.name,
+      entry_kind: currentContract.kind,
+      result: "defined",
+      source: "agentContract",
+      ...(currentContract.policy ? { policy: currentContract.policy } : {}),
+      ...(typeof currentContract.tenantScoped === "boolean" ? { tenant_scoped: currentContract.tenantScoped } : {}),
+      ...(typeof currentContract.needsApproval === "boolean" ? { needs_approval: currentContract.needsApproval } : {}),
+    },
+    currentContract,
+  };
+}
+
+function currentContractForThing(workspaceRoot: string, thing: string): Record<string, unknown> | undefined {
+  const contractPath = join(workspaceRoot, "src", "forge", "_generated", "agentContract.json");
+  if (!existsSync(contractPath)) {
+    return undefined;
+  }
+  try {
+    const contract = JSON.parse(readFileSync(contractPath, "utf8")) as Record<string, unknown>;
+    const collections: Array<[keyof typeof runtimeKinds, string]> = [
+      ["commands", "command"],
+      ["queries", "query"],
+      ["liveQueries", "liveQuery"],
+      ["actions", "action"],
+      ["workflows", "workflow"],
+    ];
+    for (const [collection, kind] of collections) {
+      const entries = Array.isArray(contract[collection]) ? contract[collection] as Record<string, unknown>[] : [];
+      for (const entry of entries) {
+        const name = runtimeEntryName(entry);
+        if (!name) {
+          continue;
+        }
+        if (name === thing || `${kind}:${name}` === thing || entry.id === thing || entry.exportName === thing) {
+          return {
+            source: "src/forge/_generated/agentContract.json",
+            kind,
+            name,
+            ...(stringValue(entry.auth) ? { auth: stringValue(entry.auth) } : {}),
+            ...(stringValue(entry.policy) ? { policy: stringValue(entry.policy) } : {}),
+            ...(typeof entry.tenantScoped === "boolean" ? { tenantScoped: entry.tenantScoped } : {}),
+            ...(typeof entry.needsApproval === "boolean" ? { needsApproval: entry.needsApproval } : {}),
+            ...(stringValue(entry.risk) ? { risk: stringValue(entry.risk) } : {}),
+            ...(stringValue(entry.file) ? { sourceFile: stringValue(entry.file) } : {}),
+            ...(stringValue(entry.path) ? { sourceFile: stringValue(entry.path) } : {}),
+          };
+        }
+      }
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+const runtimeKinds = {
+  commands: "command",
+  queries: "query",
+  liveQueries: "liveQuery",
+  actions: "action",
+  workflows: "workflow",
+} as const;
+
+function runtimeEntryName(entry: Record<string, unknown>): string | undefined {
+  return stringValue(entry.name)
+    ?? stringValue(entry.exportName)
+    ?? stringValue(entry.id)
+    ?? stringValue(entry.entryName);
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/src/forge/delta/store.ts

@@ -2809,6 +2809,12 @@ function scoreWorkSessionCandidate(
 ): { score: number; signals: DeltaWorkSessionSignal[] } {
   const signals: DeltaWorkSessionSignal[] = [];
   const metadata = candidate.metadata;
+  if (isObservationOnlyContext(context) && !isObservationOnlyWorkSession(metadata)) {
+    return {
+      score: 0.15,
+      signals: [{ signal: "observation-only", weight: 0.15, value: context.commands[0] }],
+    };
+  }
   addSignalIfOverlap(signals, "sameTraceId", 0.4, context.traces, metadata.traces);
   addSignalIfOverlap(signals, "sameManifestService", 0.35, context.services, metadata.services);
   addSignalIfOverlap(signals, "sameRuntimeEntry", 0.3, context.entries, metadata.entries);
@@ -2951,6 +2957,9 @@ function normalizeWorkSessionMetadata(value: Record<string, unknown>): DeltaWork
 }
 
 function inferWorkSessionTitle(context: DeltaOperationContext, metadata: DeltaWorkSessionMetadata): string {
+  if (isObservationOnlyWorkSession(metadata)) {
+    return "Observe project context";
+  }
   if (context.kind === "manifest.imported" && metadata.services[0]) {
     return `Import ${metadata.services[0]} external service`;
   }
@@ -2979,6 +2988,9 @@ function inferWorkSessionTitle(context: DeltaOperationContext, metadata: DeltaWo
 }
 
 function inferIntent(context: DeltaOperationContext, metadata: DeltaWorkSessionMetadata): string {
+  if (isObservationOnlyWorkSession(metadata)) {
+    return "context-gathering";
+  }
   if (context.kind === "manifest.imported" || metadata.fileClusters.includes("manifest.change")) {
     return "external-runtime-import";
   }
@@ -2999,6 +3011,9 @@ function inferIntent(context: DeltaOperationContext, metadata: DeltaWorkSessionM
 
 function summarizeWorkSession(metadata: DeltaWorkSessionMetadata): string {
   const parts: string[] = [];
+  if (isObservationOnlyWorkSession(metadata)) {
+    return `Observed project context with ${metadata.commands.slice(0, 3).join(", ")}.`;
+  }
   if (metadata.services[0]) {
     parts.push(`worked on ${metadata.services[0]}`);
   }
@@ -3018,6 +3033,9 @@ function summarizeWorkSession(metadata: DeltaWorkSessionMetadata): string {
 }
 
 function initialWorkSessionConfidence(context: DeltaOperationContext): number {
+  if (isObservationOnlyContext(context)) {
+    return 0.36;
+  }
   if (context.kind === "manifest.imported") {
     return 0.78;
   }
@@ -3043,6 +3061,65 @@ function isDiagnosticRepairChain(context: DeltaOperationContext, metadata: Delta
   );
 }
 
+const OBSERVATION_COMMAND_PREFIXES = [
+  "agent context",
+  "agent print-context",
+  "agent timeline",
+  "cair query",
+  "cair snapshot",
+  "changed",
+  "delta status",
+  "doctor",
+  "explain",
+  "handoff",
+  "inspect",
+  "live status",
+  "status",
+  "timeline",
+];
+
+function isObservationOnlyContext(context: DeltaOperationContext): boolean {
+  return (
+    context.commands.length > 0 &&
+    context.files.length === 0 &&
+    context.entries.length === 0 &&
+    context.diagnostics.length === 0 &&
+    context.proofs.length === 0 &&
+    context.services.length === 0 &&
+    context.traces.length === 0 &&
+    context.commands.every(isObservationCommand)
+  );
+}
+
+function isObservationOnlyWorkSession(metadata: DeltaWorkSessionMetadata): boolean {
+  return (
+    metadata.commands.length > 0 &&
+    metadata.files.length === 0 &&
+    metadata.entries.length === 0 &&
+    metadata.diagnostics.length === 0 &&
+    metadata.proofs.length === 0 &&
+    metadata.services.length === 0 &&
+    metadata.traces.length === 0 &&
+    metadata.commands.every(isObservationCommand)
+  );
+}
+
+function isObservationCommand(command: string): boolean {
+  const normalized = normalizeForgeCommand(command);
+  return OBSERVATION_COMMAND_PREFIXES.some((prefix) => normalized === prefix || normalized.startsWith(`${prefix} `));
+}
+
+function normalizeForgeCommand(command: string): string {
+  return command
+    .trim()
+    .replace(/^node\s+(?:\.\/)?bin\/forge\.mjs(?:\s+|$)/u, "")
+    .replace(/^bun\s+run\s+forge(?:\s+|$)/u, "")
+    .replace(/^npm\s+run\s+forge\s+--(?:\s+|$)/u, "")
+    .replace(/^forge(?:\s+|$)/u, "")
+    .replace(/\s+/gu, " ")
+    .trim();
+}
+
 function hasAnyOverlap(...groups: string[][]): boolean {
   for (let index = 0; index < groups.length; index += 2) {
     if (intersects(groups[index] ?? [], groups[index + 1] ?? [])) {

package/src/forge/version.ts

@@ -1,3 +1,3 @@
-export const FORGEOS_VERSION = "0.1.0-alpha.22";
+export const FORGEOS_VERSION = "0.1.0-alpha.24";
 export const GENERATOR_VERSION = FORGEOS_VERSION;
 export const CLI_VERSION = FORGEOS_VERSION;