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

package/.npmignore

@@ -5,5 +5,9 @@ node_modules/
 .forge/
 tests/
 examples/
+src/forge/_generated/**
+!src/forge/_generated/
+!src/forge/_generated/releaseManifest.json
+!src/forge/_generated/releaseManifest.ts
 *.tgz
 npm-debug.log*

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.2 input=2ce189e4d3555acfca07eb3bb3d103b22a8da52f3c26f9ac2197254f0563234f content=e0bf36433d915daf5ad06ac6265b3ac6f2cd1706269c69618bbbc1cb1f44e465
+// @forge-generated generator=0.1.0-alpha.21 input=e2f2a360a9fd4118a2d21dd1353365628fe3927c40f9f9ce870f448f3e221f90 content=0d493cf0e41b71cb652d5e0e1b0c1f83d2a1281b748321f0b00f0773ba93074e
 # AGENTS.md
 
 <!-- forge-generated:start -->
@@ -7,23 +7,51 @@
 
 This is a ForgeOS application named `forgeos`.
 
+## CLI entrypoint
+
+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.
+
 ## Required workflow
 
 Before editing:
 
 ```bash
-forge do inspect --json
-forge dev --once --json
-forge inspect all --json
-forge check --json
+node bin/forge.mjs agent onboard --target codex --json
+node bin/forge.mjs status --json
+node bin/forge.mjs changed --json
+node bin/forge.mjs handoff --json
+node bin/forge.mjs do inspect --json
+node bin/forge.mjs dev --once --json
+node bin/forge.mjs agent print-context --json
+node bin/forge.mjs check --json
+```
+
+## CAIR first
+
+Before reading large files or hand-writing patches, prefer the generated CAIR guide:
+
+```bash
+node bin/forge.mjs cair snapshot
+node bin/forge.mjs cair query "Q ST"
+node bin/forge.mjs cair query "Q S name=<symbol>"
+node bin/forge.mjs cair query "Q D S#1"
+node bin/forge.mjs cair query "Q R S#1"
+node bin/forge.mjs cair query "Q I S#1"
+```
+
+Use `src/forge/_generated/agentCairGuide.md` for the full compact protocol. Plan CAIR mutations before applying them:
+
+```bash
+node bin/forge.mjs cair action --plan "A RN t=S#1 nn=<newName>"
+node bin/forge.mjs cair action "A APPLY plan=<returned-plan-path>"
 ```
 
 After editing:
 
 ```bash
-forge generate
-forge check
-forge verify --strict
+node bin/forge.mjs generate
+node bin/forge.mjs check
+node bin/forge.mjs verify framework
 ```
 
 ## Do not edit
@@ -34,7 +62,7 @@ Do not:
 - `forge.lock`
 - `deploy/docker-compose.yml`, unless changing deployment config intentionally
 
-Template apps may ignore `src/forge/_generated/**` and `forge.lock` in git to reduce visual noise. Recreate them with `forge generate` before checking, testing, or handing work off.
+Template apps may ignore `src/forge/_generated/**` and `forge.lock` in git to reduce visual noise. Recreate them with `node bin/forge.mjs generate` before checking, testing, or handing work off.
 
 ## Runtime model
 
@@ -44,14 +72,14 @@ Template apps may ignore `src/forge/_generated/**` and `forge.lock` in git to re
 - Workflows orchestrate durable steps.
 - Production liveQuery uses a durable invalidation log; polling/notify are wakeups only.
 - Production API calls use `Authorization: Bearer <JWT>` in `jwt` or `oidc` auth mode.
-- `dev-headers` auth is for `forge dev`, tests, and local agent workflows only.
+- `dev-headers` auth is for `node bin/forge.mjs dev`, tests, and local agent workflows only.
 - AI is only allowed in actions, workflows, endpoints, and server code.
 - Secrets are accessed through `ctx.secrets`.
 
 ## 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.
@@ -60,31 +88,38 @@ Template apps may ignore `src/forge/_generated/**` and `forge.lock` in git to re
 ## Useful commands
 
 ```bash
-forge do "<objective>" --json
-forge do fix --json
-forge do verify --json
-forge dev --once --json
-forge dev
-forge inspect app --json
-forge inspect all --json
-forge inspect frontend --json
-forge inspect capabilities --json
-forge deps inspect <package> --json
-forge deps api <package> <symbol> --json
-forge deps trace <package> --json
-forge auth check --json
-forge inspect runtime-matrix --json
-forge inspect policies --json
-forge inspect client --json
-forge inspect live-production --json
-forge live status --json
-forge doctor
-forge doctor windows --json
-forge setup windows --json
-forge agent print-context --json
-forge verify --smoke
-forge verify --standard
-forge verify --strict
+node bin/forge.mjs do "<objective>" --json
+node bin/forge.mjs do fix --json
+node bin/forge.mjs do verify --json
+node bin/forge.mjs dev --once --json
+node bin/forge.mjs dev
+node bin/forge.mjs handoff --json
+node bin/forge.mjs inspect app --json
+node bin/forge.mjs inspect all --json
+node bin/forge.mjs inspect all --full --json
+node bin/forge.mjs inspect frontend --json
+node bin/forge.mjs inspect capabilities --json
+node bin/forge.mjs inspect agent-tools --json
+node bin/forge.mjs deps inspect <package> --json
+node bin/forge.mjs deps api <package> <symbol> --json
+node bin/forge.mjs deps trace <package> --json
+node bin/forge.mjs auth check --json
+node bin/forge.mjs inspect runtime-matrix --json
+node bin/forge.mjs inspect policies --json
+node bin/forge.mjs inspect client --json
+node bin/forge.mjs inspect live-production --json
+node bin/forge.mjs live status --json
+node bin/forge.mjs doctor
+node bin/forge.mjs doctor windows --json
+node bin/forge.mjs setup windows --json
+node bin/forge.mjs agent print-context --json
+node bin/forge.mjs agent doctor --target codex --json
+node bin/forge.mjs ai tools --json
+node bin/forge.mjs ai agents --json
+node bin/forge.mjs ai trace <traceId> --json
+node bin/forge.mjs verify --smoke
+node bin/forge.mjs verify --standard
+node bin/forge.mjs verify framework
 ```
 
 ## Data
@@ -103,6 +138,21 @@ Tenant-scoped tables:
 - ANTHROPIC_API_KEY (required)
 - OPENAI_API_KEY (required)
 
+## AI Tools And Agents
+
+- AI SDK engine: Vercel AI SDK v6.
+- Forge layer: generated registry, runtime rules, telemetry, secrets, tenant/auth context, and agent contract.
+- Use `ctx.agent.run` or `ctx.ai.runAgent` only in actions, workflows, endpoints, and server code.
+- Do not create custom tool loops; use Forge tools and AI SDK `ToolLoopAgent` through the Forge runtime.
+
+Tools:
+
+- none
+
+Agents:
+
+- none
+
 ## Auth
 
 - Modes: dev-headers, jwt, oidc, disabled
@@ -123,9 +173,9 @@ Tenant-scoped tables:
 
 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
@@ -135,29 +185,31 @@ Rules:
 Use:
 
 ```bash
-forge do "<objective>" --json
-forge do fix --json
-forge do connect-ui --json
-forge do verify --json
+node bin/forge.mjs do "<objective>" --json
+node bin/forge.mjs do fix --json
+node bin/forge.mjs do connect-ui --json
+node bin/forge.mjs do verify --json
 ```
 
-`forge do` returns intent, plan, filesToInspect, filesToChange, risks, concrete commands, and nextAction. Prefer it before choosing lower-level CLI commands manually.
+`node bin/forge.mjs do` returns intent, plan, filesToInspect, filesToChange, risks, concrete commands, and nextAction. Prefer it before choosing lower-level CLI commands manually.
 
 ### Add a command
 
 1. Add file in `src/commands`.
 2. Declare `auth: can("...")`.
-3. Run `forge generate`.
-4. Run `forge verify --strict`.
+3. Run `node bin/forge.mjs generate`.
+4. Run `node bin/forge.mjs verify framework`.
 
 ### 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 ui --framework vite --dry-run --json
+node bin/forge.mjs make resource <name> --fields title:text,status:enum(open,closed) --dry-run --json
+node bin/forge.mjs make resource <name> --fields title:text,status:enum(open,closed) --with-ui --yes
+node bin/forge.mjs make ui --framework vite --dry-run --json
+node bin/forge.mjs make ui --framework nuxt --dry-run --json
+node bin/forge.mjs make ai-chat support --dry-run --json
 ```
 
 Review the plan before applying when the resource touches schema or policies.
@@ -167,22 +219,22 @@ Review the plan before applying when the resource touches schema or policies.
 Use:
 
 ```bash
-forge dev --once --json
-forge dev
-forge inspect frontend --json
-forge inspect capabilities --json
+node bin/forge.mjs dev --once --json
+node bin/forge.mjs dev
+node bin/forge.mjs inspect frontend --json
+node bin/forge.mjs 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.
+`node bin/forge.mjs dev` starts the API runtime and web app together when `web/` exists. `node bin/forge.mjs 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
 
 Use:
 
 ```bash
-forge feature validate .forge/blueprints/<name>.json --json
-forge feature plan .forge/blueprints/<name>.json
-forge feature apply .forge/blueprints/<name>.json --yes
+node bin/forge.mjs feature validate .forge/blueprints/<name>.json --json
+node bin/forge.mjs feature plan .forge/blueprints/<name>.json
+node bin/forge.mjs feature apply .forge/blueprints/<name>.json --yes
 ```
 
 Review high-risk plans before applying. Use `--allow-high-risk` only when intentional.
@@ -192,47 +244,63 @@ Review high-risk plans before applying. Use `--allow-high-risk` only when intent
 Use:
 
 ```bash
-forge refactor rename field tickets.priority tickets.urgency --dry-run --json
-forge refactor rename field tickets.priority tickets.urgency --yes
+node bin/forge.mjs refactor rename field tickets.priority tickets.urgency --dry-run --json
+node bin/forge.mjs refactor rename field tickets.priority tickets.urgency --yes
+node bin/forge.mjs refactor rename command createTicket openTicket --dry-run --json
+node bin/forge.mjs refactor rename command createTicket openTicket --yes
 ```
 
-These codemods are AST-aware for `extract-action`, `rename field`, and `rename table`. Field renames are scoped to the target table, so `tickets.priority` only rewrites references linked to `tickets`.
+These codemods are AST-aware for `extract-action`, `rename command`, `rename field`, and `rename table`. Command renames update runtime registries, generated client references, frontend hooks, tests, and string references where safe. Field renames are scoped to the target table, so `tickets.priority` only rewrites references linked to `tickets`.
 
-Never edit `src/forge/_generated/**` directly. Review migration hints before applying field or table renames.
+Never edit `src/forge/_generated/**` directly. Review migration hints before applying command, field, or table renames.
 
 ### Plan impact-based tests
 
 Use:
 
 ```bash
-forge impact --changed --json
-forge test plan --changed --json
-forge test run --changed --timeout-ms 120000 --json
-forge verify --standard
+node bin/forge.mjs impact --changed --json
+node bin/forge.mjs test plan --changed --json
+node bin/forge.mjs test run --changed --timeout-ms 120000 --json
+node bin/forge.mjs verify --standard
 ```
 
-Use `forge verify --standard` for the normal agent development loop. Finish handoffs with `forge verify --strict` when the change is ready.
+Use `node bin/forge.mjs verify --standard` for the normal agent development loop. Finish handoffs with `node bin/forge.mjs verify framework` when the change is ready.
 
 ### Repair a failing check
 
 When a Forge check fails, do not guess. Use:
 
 ```bash
-forge repair diagnose --from-last-test-run --json
-forge repair plan --from-last-test-run --write
+node bin/forge.mjs repair diagnose --from-last-test-run --json
+node bin/forge.mjs repair plan --from-last-test-run --write
 ```
 
 Apply only high-confidence deterministic repairs automatically. Review medium or low confidence repairs before changing code.
 
+### Add AI tools or agents
+
+Use:
+
+```bash
+node bin/forge.mjs generate
+node bin/forge.mjs inspect ai --json
+node bin/forge.mjs agent print-context --json
+node bin/forge.mjs ai check --json
+node bin/forge.mjs ai trace <traceId> --json
+```
+
+Define tools with `aiTool({ inputSchema, outputSchema, risk, needsApproval, handler })` and agents with `agent({ provider, model, instructions, tools, stopWhen })`. Execute agents with `ctx.agent.run` or `ctx.ai.runAgent` only from actions, workflows, endpoints, or server code. In dev, POST `/ai/agents/run` returns JSON for automation and POST `/ai/agents/chat` returns an AI SDK UIMessage stream for React `useChat`; both accept `agent: "<exportedAgentName>"` and use generated auto-tools from `agentTools.json`.
+
 ### Export agent adapters
 
 Use:
 
 ```bash
-forge agent export --target generic
-forge agent export --target codex
-forge agent export --target cursor
-forge agent export --target claude
+node bin/forge.mjs agent export --target generic
+node bin/forge.mjs agent export --target codex
+node bin/forge.mjs agent export --target cursor
+node bin/forge.mjs agent export --target claude
 ```
 
 Adapter files are derived from `agentContract.json`, `appMap.md`, `runtimeRules.md`, `operationPlaybooks.md`, and this `AGENTS.md`. Do not treat Codex, Cursor, Claude, or custom adapter files as the source of truth.
@@ -242,7 +310,7 @@ Adapter files are derived from `agentContract.json`, `appMap.md`, `runtimeRules.
 Use:
 
 ```bash
-forge add <alias>
+node bin/forge.mjs add <alias>
 ```
 
 Do not install packages manually unless intentional.
@@ -252,11 +320,11 @@ Do not install packages manually unless intentional.
 Use:
 
 ```bash
-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
+node bin/forge.mjs deps upgrade-plan <package> --to latest
+node bin/forge.mjs deps inspect <package> --json
+node bin/forge.mjs deps api <package> <symbol> --json
+node bin/forge.mjs deps upgrade-apply <plan>
+node bin/forge.mjs verify framework
 ```
 
 Do not manually edit `package.json` for package upgrades unless necessary.
@@ -266,9 +334,9 @@ Do not manually edit `package.json` for package upgrades unless necessary.
 Use:
 
 ```bash
-forge live status --json
-forge live invalidations list --json
-forge live debug <subscriptionId> --json
+node bin/forge.mjs live status --json
+node bin/forge.mjs live invalidations list --json
+node bin/forge.mjs live debug <subscriptionId> --json
 ```
 
 Durable invalidations live in `_forge_live_invalidations`.
@@ -279,4 +347,23 @@ Durable invalidations live in `_forge_live_invalidations`.
 
 Project-specific notes can go here.
 
+## Cursor Cloud specific instructions
+
+This repo is the ForgeOS framework/compiler itself (package `forgeos`), not a generated app. The development toolchain is Node.js (>= 22.14, present) plus **Bun**, which is the repo's test runner and canonical package manager (`bun.lock`). The Cloud VM snapshot has Bun pre-installed at `~/.bun/bin/bun` (added to `PATH` via `~/.bashrc`); if `bun` is not on `PATH` in a non-login shell, use `~/.bun/bin/bun` or `export PATH="$HOME/.bun/bin:$PATH"`.
+
+Standard commands (see `package.json`, `CONTRIBUTING.md`, `.github/workflows/ci.yml`):
+
+- Install deps: `bun install --ignore-scripts` (the update script runs this). `--ignore-scripts` matches CI; native deps like `tree-sitter` are not built and tests do not need them.
+- Lint: `npm run lint` (runs `node --import tsx ./src/forge/cli/lint-forge.ts`).
+- Typecheck: `npm run typecheck` (`tsc --noEmit`).
+- Tests: `bun test` (~2 min, 650 tests). 4 tests are skipped by design unless extra tooling/env is set (`FORGE_SMOKE_REAL=1`, a real Postgres, `FORGE_MAVEN`).
+- Generate + verify: `bun run forge generate` then `bun run forge verify --standard --script-timeout-ms 120000`.
+
+Non-obvious gotchas:
+
+- `bun run forge generate` rewrites `src/forge/_generated/**`, `forge.lock`, and the `// @forge-generated` header `input=` hash in `AGENTS.md`. These regenerated diffs are environment-dependent and should NOT be committed (per "Do not edit" above). `forge verify` regenerates internally, so `generate-check` can pass even while `git status` shows these as dirty. Run `git checkout -- .` to discard them before committing unrelated work.
+- The CLI runs under Node via `tsx` (`node ./bin/forge.mjs ...` or `npm run forge -- ...`); only the test runner needs Bun.
+- To run an actual Forge app end-to-end, scaffold one from a template and run the dev servers. From a temp dir: `node /workspace/bin/forge.mjs new notes-app --template minimal-web --package-manager npm --forge-spec "file:/workspace" --install --no-git`, then `cd notes-app && npm run dev`. `forge dev` starts the API runtime (pglite, default `http://127.0.0.1:3765`) and the Vite web app (default `http://127.0.0.1:5173`); use `forge dev --api-only` for backend only.
+- Hitting the runtime directly: POST `/commands/<name>` and `/queries/<name>` with body shaped as `{ "args": { ... } }`. In `dev-headers` auth mode pass `x-forge-user-id` and `x-forge-role` (e.g. `owner`) headers; `<ForgeProvider devAuth>` defaults to user `dev-user`, tenant `dev-tenant`, role `owner`.
+
 <!-- user-notes:end -->

package/CHANGELOG.md

@@ -1,5 +1,216 @@
 # forgeos
 
+## 0.1.0-alpha.21
+
+### Patch Changes
+
+- Harden Codex hook queue privacy and brownfield import classification.
+
+  - Queue new Codex hook events as redacted payloads instead of storing raw prompts, tool inputs, tool responses, or transcripts in `.forge/agent/events.ndjson`.
+  - Compact consumed hook queue history into redacted `.history` lines so old raw queue entries are not copied forward during drain retention.
+  - Scope brownfield route classification to the detected route handler, so read-only GET handlers are not marked command-like because a sibling route in the same file writes state.
+  - Mark read-shaped `POST /search`, `/query`, `/filter`, `/lookup`, and `/graphql` routes as `command-candidate` with `ambiguous-post-query` risk instead of treating them as normal writes.
+  - Sync the public docs changelog/CLI reference and clarify the alpha/latest npm dist-tag policy.
+
+## 0.1.0-alpha.20
+
+### Patch Changes
+
+- Fix generated-change diagnostics, Codex hook queue handling, and external stdio command parsing.
+
+  - Classify generated `AGENTS.md` blocks and `.forge/agent/context.json` as derived artifacts in `forge changed`/`forge status`.
+  - Skip probe, invalid, and out-of-workspace queued hook events during Agent Memory drain, and bound queue inspection for large hook queues.
+  - Preserve empty stdio command arguments, diagnose malformed command strings, and support structured `service.commandArgs` in external manifests.
+  - Include the basic example client demo in typecheck coverage.
+
+## Unreleased
+
+## 0.1.0-alpha.19
+
+Alpha hardening:
+
+- Added the `agent-workroom` app template for Forge Studio style demos: external
+  agents edit the app, while ForgeOS shows preview URL, agent signals, check
+  runs, and handoff evidence through generated commands and liveQuery bindings.
+- Added `forge studio attach` for Studio-style observer apps: writes `.forge/studio/attachment.json`, prepares external-agent adapters/hooks, and returns the target preview URL.
+- Added `summary.preview` and `summary.urls.suggestedPreview` to `forge dev --once --json` so observer UIs can target the app under construction instead of pointing at themselves.
+- Improved `forge dev` port-busy failures with a `port_busy` JSON failure kind and suggested recovery commands, including the common "Is port X in use?" startup error shape.
+- `forge dev` now resolves the web app port before startup and automatically moves to the next available port when the default web port is busy, keeping the printed/JSON web URL truthful.
+- Improved `forge check --json` next actions by surfacing diagnostic-specific repair/inspect commands instead of a generic last-test-run repair hint.
+- Added `forge doctor agent --target <agent>` as the top-level agent readiness check.
+- Added explicit `forge agent ingest <source> --watch --file <events.ndjson>` support for opt-in hook/export file ingestion.
+- Added human-friendly verifier aliases: `forge verify quick`, `forge verify agent`, and `forge verify release`.
+- Made `forge status --human` an explicit accepted spelling and documented `forge add <npm-package> --workspace web` as the normal package-add path.
+- Made bare `forge inspect` default to the compact `summary` target instead of returning a usage error.
+- Added `forge release doctor`, `release check --allow-missing-local-release`, and `self-host check --prepared-only` so release readiness can distinguish hard failures from not-yet-prepared local artifacts.
+- Hardened the public packed-package smoke with dry-run mode, per-step JSON evidence, step timeouts, installed-global CLI coverage, hook smoke readiness, Studio open coverage, and preview-port cleanup checks.
+- Expanded `forge docs check` with YAML shape checks, internal Markdown link validation, optional ReadTheDocs-style venv installation, and strict MkDocs build execution.
+- Added authored-only review paths through `forge changed --authored` and `forge diff authored`, keeping generated artifacts collapsed unless explicitly requested.
+- Added `forge delta status --verbose --json` for schema, lock, path, and aggregate-count diagnostics without expanding the default status payload.
+- Added explicit hook readiness levels (`none`, `canary`, `trusted-native`) and documented `.codex/hooks.json` as versioned adapter configuration while keeping `.forge/agent/**` as local operational state.
+
+## 0.1.0-alpha.18
+
+Codex hook memory hardening:
+
+- Hardened Codex hook ingestion by deriving useful tool-call metadata from the documented hook wire format while keeping raw prompts, tool inputs, tool responses, transcripts, and secrets out of Agent Memory.
+- Added safe command summaries, tool-call ids, result status, exit codes, response summaries, inferred files, and inferred runtime entries for Codex `PreToolUse`, `PermissionRequest`, and `PostToolUse` events.
+- Updated the Codex hook installer with hook timeouts and status messages, and added a local wrapper so repo hooks can use the checkout implementation.
+- Documented the safe Codex hook metadata surface and added regression coverage for real hook payload shapes.
+
+## 0.1.0-alpha.17
+
+External runtime timeline metadata:
+
+- Enriched DeltaDB runtime call recording for imported Go/Java/external services by reading generated `externalServices.json` metadata during `forge run` and `forge query`.
+- `forge timeline` and `forge explain` now report external runtime `service`, `language`, `risk`, `policy`, `tenantScoped`, and `needsApproval` state instead of falling back to null/false values after successful external calls.
+- Added a DeltaDB schema migration for `runtime_calls.needs_approval` and bumped the local DeltaDB schema to `0.3.1`.
+- Added regression coverage for the real CLI recorder path so manifest-imported external commands keep semantic metadata in timelines.
+- Promotes this release on npm as both `alpha` and `latest`.
+
+## 0.1.0-alpha.16
+
+Stability alignment:
+
+- Fixed H47 `forge timeline` and `forge explain` crashes after large `artifact.generated` payloads by replacing unsafe JSON string truncation with a safe summary/hash envelope.
+- Summarized generated artifact batches in the Semantic Timeline with count, hash, sample, and omitted count instead of embedding every artifact in timeline event data.
+- Fixed H49 brownfield import detection for root-level Next.js App Router and Pages API routes such as `app/api/.../route.ts` and `pages/api/...`.
+- Updated public CLI and DeltaDB docs for timeline/session/explain/MCP/agent-memory commands and clarified that `.forge/delta/delta.db` is a PGlite/Postgres data directory.
+- Verified the release against a public GitHub `main` smoke app using `generate`, `check`, `delta status`, `timeline`, `explain`, `import analyze`, and `inspect imported`.
+
+## 0.1.0-alpha.15
+
+Brownfield import analysis:
+
+- Added H49 `forge import analyze` and `forge import inspect` for static brownfield TypeScript/JavaScript app inventory.
+- Detects Next.js App Router routes, Pages API routes, Express/Nest-style handlers, frontend `fetch`/`axios` calls, env usage, framework/data/external package signals, and conservative candidate command/query entries.
+- Writes `.forge/import` artifacts including inventory, routes, frontend calls, candidate entries, risk report, migration plan, and imported agent contract.
+- Keeps imported entries hidden from agents by default with `origin: imported`, `assurance: static-scan`, `reviewStatus: needs-review`, `visibleToAgent: false`, and approval required for command-like or risky entries.
+- Added `forge inspect imported --json` plus focused H49 CLI and scanner coverage.
+
+## 0.1.0-alpha.14
+
+Java and Nuxt/Vue support:
+
+- Added the Java external runtime adapter with a lightweight JDK HTTP bridge, manifest export, typed handlers, tenant/auth context, diagnostics, and command/query registration.
+- Added a Spring Boot starter for Java services that want annotation-based Forge command/query exposure.
+- Added the `java-billing` conformance example and packaged it with the public alpha line.
+- Added generated Vue bindings and a `forgeos/vue` export with `provideForge`, `ForgeVuePlugin`, `useForgeQuery`, `useForgeCommand`, and `useForgeLiveQuery`.
+- Added Nuxt UI scaffolding through `forge make ui --framework nuxt`, including plugin wiring, composable bridge files, and frontend graph detection for `.vue` routes/components.
+- Updated docs, agent adapter guidance, generated manifests, and focused Java/Vue/Nuxt tests.
+- Kept H44-H48 memory, sessions, timeline, grouping, and MCP surfaces intact while merging the Java/Nuxt work into `main`.
+
+## 0.1.0-alpha.13
+
+Agent Memory Bridge:
+
+- Added the H48 Agent Memory Bridge alpha with redacted external agent event ingestion and normalized `forge.agent-event.v1` envelopes.
+- Added Codex and Claude Code hook installers plus Cursor MCP/rules setup, all with raw prompts, completions, tool args, transcripts, and cloud sync off by default.
+- Added `forge mcp serve` with context, memory, timeline, and inspect tools for external agents.
+- Added `forge agent install`, `forge agent ingest`, `forge agent context`, and `forge agent memory` commands.
+- Persisted external agent activity in DeltaDB and linked agent/tool/file events into the semantic timeline.
+- Added focused privacy, ingest, MCP, installer, and CLI parse coverage for the H48 bridge.
+
+## 0.1.0-alpha.12
+
+Semantic Timeline:
+
+- Added the H47 Semantic Timeline projection for DeltaDB with rebuildable timeline events, entity indexes, causal edges, and projection state.
+- Upgraded `forge timeline` from a raw operation log view into an entity-oriented semantic timeline for runtime entries, policies, diagnostics, proofs, services, files, and sessions.
+- Added proof staleness detection and causal links for denial -> policy repair -> successful execution flows.
+- Updated `forge explain` to include semantic timeline context and current-state summaries when available.
+- Documented the timeline projection/rebuild model and added focused DeltaDB coverage for runtime, policy, diagnostic, proof, and deterministic rebuild scenarios.
+
+## 0.1.0-alpha.11
+
+Strict verify performance:
+
+- Reduced the validated `forge verify --strict` wall time from roughly 358-454s to about 116s on the current Windows test machine.
+- Added stable repo-local `tsx` CLI caching under `node_modules/.cache/forge-tsx-cli` so spawned CLI tests reuse the warm compiler path.
+- Balanced TestGraph strict execution across shared and isolated lanes, bringing the slowest files down from roughly 50s to under 10s in the updated profile.
+- Moved heavy refactor/impact/external runtime suites onto faster shared paths where safe and kept isolation for process-sensitive tests.
+- Documented and guarded the cache behavior so future test helpers preserve the speedup without checking cache contents into git.
+- Added guarded alpha release workflow support for promoting the public `latest` dist-tag when npm token auth is configured.
+
+## 0.1.0-alpha.10
+
+Launch polish:
+
+- Fixed `forge run <external-command> --args ...` so CLI arguments reach the external runtime bridge.
+- Added direct external query CLI support through `forge query <service.query> --args ...`.
+- Emit generated `.json` artifacts as pure JSON while keeping deterministic headers on code/text artifacts.
+- Relaxed the `minimal-web` template verify script to `forge verify --smoke` and added the missing `check` script to `b2b-support-web`.
+- Updated public protocol/changelog docs for the external runtime and Go adapter alpha line.
+- Bumped the create-app wrapper package line to `create-forgeos-app@0.1.0-alpha.4`.
+
+## 0.1.0-alpha.9
+
+### Patch Changes
+
+- Added the Forge external runtime protocol bridge for manifest-backed commands and queries.
+- Added the Go adapter MVP with a real `go-billing` conformance example.
+- Emitted external service metadata into inspect/API/agent artifacts, including `needsApproval` for agent tools.
+- Reuse compiler classifier package signals across export classification, dropping repeated package signal scans.
+- Reuse serialized graph JSON when rendering the largest generated TypeScript graph artifacts.
+- Keep generated Forge artifacts aligned with the `0.1.0-alpha.9` compiler/runtime version.
+
+## 0.1.0-alpha.8
+
+### Patch Changes
+
+- [`7568756`](https://github.com/Stahldavid/forge/commit/756875688873dd60d3d6cf700a7bb7c211968c69) Thanks [@Stahldavid](https://github.com/Stahldavid)! - Publish prerelease packages through the ForgeOS alpha publisher so npm dist-tags stay aligned.
+
+## 0.1.0-alpha.7
+
+### Patch Changes
+
+- [`4ace311`](https://github.com/Stahldavid/forge/commit/4ace3113e3298b5c306000870922fcfbae9c1861) Thanks [@Stahldavid](https://github.com/Stahldavid)! - Keep npm prerelease publishing on the public alpha dist-tag.
+
+## 0.1.0-alpha.6
+
+### Patch Changes
+
+- [`c30f906`](https://github.com/Stahldavid/forge/commit/c30f9069c99ac747ce143ab5fbcbf13912ed8760) Thanks [@Stahldavid](https://github.com/Stahldavid)! - Add CLI version output, align create-app help with package metadata, and add release dependency audit evidence.
+
+## 0.1.0-alpha.5
+
+Release alignment for the public alpha channel:
+
+- Added `forge ai redteam --model-level --json` with deterministic prompt-injection, secret-exfiltration, approval-bypass, cross-tenant, and indirect tool-injection probes.
+- Added `forge security prove --full --json` support for source checkouts, with graceful structural-proof fallback when packaged apps do not include ForgeOS test fixtures.
+- Strengthened npm publish workflows to run `security prove --db postgres --full --json`.
+- Added public registry smoke coverage for `forgeos@alpha` and `create-forgeos-app@alpha`.
+- Bumped the create-app wrapper package line to `create-forgeos-app@0.1.0-alpha.1`.
+
+## 0.1.0-alpha.4
+
+Security assurance and release evidence hardening:
+
+- Added value-aware telemetry redaction for known secret values in safe-looking fields, messages, details, outputs, and stack traces.
+- Added webhook signature, timestamp, and replay protection helpers with Stripe/GitHub/generic HMAC coverage.
+- Added HTTP tenant-isolation tests that exercise the dev server/API boundary, not only the internal runtime executor.
+- Added `forge rls mutate-test --json` to kill dangerous generated RLS mutations such as missing FORCE RLS, missing policies, unconditional predicates, and `BYPASSRLS`.
+- Extended `forge security prove --json` with RLS mutation proof and invariant-level evidence metadata.
+- Added scripts to split security evidence by invariant and emit basic release supply-chain evidence plus CycloneDX SBOM.
+- Strengthened publish/security workflows so release gates use Postgres-backed security proof, RLS mutation proof, release evidence, and SBOM generation.
+
+## 0.1.0-alpha.3
+
+Native Forge AI agents on top of Vercel AI SDK v6:
+
+- Added `aiTool` and `agent` primitives with generated `agentTools.json` / `agentTools.md`.
+- Added `ctx.agent.run` and `ctx.ai.runAgent` using AI SDK `ToolLoopAgent`.
+- Added auto-tools for commands, queries, and liveQueries with read-only vs approval-required writes.
+- Added dev agent endpoints: `POST /ai/agents/run` and `POST /ai/agents/chat`.
+- Extended `forge ai` CLI with `tools`, `agents`, and `trace` subcommands.
+- Added `forge inspect agent-tools` and agent tool metadata in `agentContract.json`.
+- Upgraded runtime dependency to AI SDK v6 for tool calling, streaming UI, and MCP compatibility.
+
+Documentation:
+
+- Added public [AI](https://forgeos.readthedocs.io/en/latest/ai/) page and AST-aware `rename command` codemod docs.
+- Expanded ReadTheDocs to full agent-native coverage: agent workflow (`forge do`), frontend/liveQuery, security/data, authoring, testing/repair, self-host, templates, Material theme, and changelog page.
+
 ## 0.1.0-alpha.2
 
 Windows and generated-app hardening: