forgeos 0.1.0-alpha.23 → 0.1.0-alpha.24

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.23 input=43fbd897d0f0a003e2f63e7048eb3281a5871034827653640e010161c0385d44 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,18 @@
 
 ## 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

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/changelog.md

@@ -6,6 +6,22 @@ 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:

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.23",
+  "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/",
@@ -18,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.23","releaseId":"forgeos@0.1.0-alpha.23+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.23 input=43fbd897d0f0a003e2f63e7048eb3281a5871034827653640e010161c0385d44 content=8b537f90580f28c1630850bc7b7199e17d0bc62d05e9565fdf84da4bdbf9f6dc
+// @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.23",
-  "releaseId": "forgeos@0.1.0-alpha.23+unknown",
+  "packageVersion": "0.1.0-alpha.24",
+  "releaseId": "forgeos@0.1.0-alpha.24+unknown",
   "schemaVersion": "0.1.0"
 } as const;

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/version.ts

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