forgeos 0.1.0-alpha.3 → 0.1.0-alpha.31

package/CHANGELOG.md

@@ -1,5 +1,337 @@
 # forgeos
 
+## 0.1.0-alpha.31
+
+### Patch Changes
+
+- Smooth the ForgeOS field-demo DX after the alpha.30 app-server and WorkOS exercises.
+
+  - Add `forge baseline create` and `forge baseline status` so non-git template workspaces can establish a local baseline and get useful `forge changed` / `forge handoff` diffs instead of noisy filesystem inventories.
+  - Add `forge auth status` and production-focused `forge auth prove --prod` output so `dev-headers` is clearly labeled as local-only while JWT/OIDC proofs show production auth posture.
+  - Expand `forge doctor windows` with local PGlite store posture and cleanup guidance, including safer PGlite abort inspection that does not poison the surrounding process exit code.
+  - Add `forge ui audit` and run it during `forge verify --smoke` when a web app is present, catching missing UI scenarios, missing stable Forge test IDs, and missing policy-denied coverage for sensitive routes.
+
+## 0.1.0-alpha.30
+
+### Patch Changes
+
+- Harden the WorkOS/AuthKit adapter and dev telemetry after the alpha.29 field app test.
+
+  - Normalize WorkOS AuthKit `User` objects before generated auth routes pass them to Forge session and organization-resolution helpers, so apps typecheck against the WorkOS SDK without unsafe direct `Record<string, unknown>` casts.
+  - Keep telemetry best-effort when a database adapter applies `INSERT ... RETURNING` but omits returned rows, preventing telemetry from surfacing as `FORGE_DEV_SERVER_ERROR`.
+  - Add regression coverage for generated WorkOS adapter typechecking and telemetry inserts that return no rows.
+
+## 0.1.0-alpha.29
+
+### Patch Changes
+
+- Add the first WorkOS/AuthKit adapter and local auth metadata tooling.
+
+  - Add `forge add auth workos`, generated WorkOS seed/config/docs, AuthKit routes, webhook handling, JWT/OIDC claim mapping, and permission-derived Forge policies.
+  - Add `forge authmd generate` and `forge authmd check`, including `/auth.md` and OAuth protected-resource metadata served by `forge dev`.
+  - Add a local WorkOS/FGA testkit, resource-graph helpers, cross-tenant guards, FGA cache/fallback telemetry, and mock multi-tenant regression coverage.
+  - Teach Forge auth and policies to understand permission claims alongside roles.
+  - Add `forge version --json` as a command alias and capture local helper table reads in the generated agent contract/capability map.
+
+## 0.1.0-alpha.28
+
+### Patch Changes
+
+- Accept visible Codex hook canaries as sufficient for local editing while reporting native Codex provenance separately through `nativeTrustStatus`.
+
+## 0.1.0-alpha.27
+
+### Patch Changes
+
+- Stabilize `forge add convex` and generated integration artifacts.
+
+  - Re-emit integration adapters, docs, and testkits from the main generator so `forge generate --check` and `forge verify --smoke` stay clean after `forge add`.
+  - Keep partial `forge add` plans from deleting unrelated generated files before the full generator can reconcile the workspace.
+  - Include changed package-manager files such as `package.json` and lockfiles in `forge add --json` handoffs.
+  - Replace stale fast-check manifest hashes instead of merging them, and invalidate old manifest schemas to avoid phantom generated drift.
+  - Skip Bun module mock registration when the active Bun runtime does not expose `Bun.mock.module`, while still applying mock secret env vars.
+  - Filter generated and operational filesystem noise from `forge changed --authored` in non-git workspaces.
+  - Keep Java build outputs such as `target/`, `.class`, and `.jar` files out of the published npm tarball.
+
+## 0.1.0-alpha.26
+
+### Patch Changes
+
+- Harden the field-demo loop after the Team Onboarding app exercise.
+
+  - Let `forge changed` and `forge handoff` summarize non-git workspaces with a filesystem inventory instead of reporting zero useful changes.
+  - Keep `forge make resource` global by default unless a tenants table exists or `--tenant-scoped` is explicit.
+  - Expand capability-map table detection for aliased `ctx.db` usage.
+  - Wait through short-lived DeltaDB writer locks before reporting `FORGE_DELTA_BUSY`.
+
+## Unreleased
+
+## 0.1.0-alpha.25
+
+### Patch Changes
+
+- Harden DeltaDB and Agent Memory under real `forge dev` concurrency.
+
+  - Stop long-running dev recorders from holding the DeltaDB writer lock between events.
+  - Retry short transient DeltaDB writer conflicts before reporting `FORGE_DELTA_BUSY`.
+  - Keep Codex hook queue checkpoints unchanged when Agent Memory ingest is blocked by a busy DeltaDB writer, then retry safely instead of losing queued events.
+  - Add watcher backoff metadata for lock recovery and document the safe queue/DeltaDB behavior.
+
+- Fix tenant-scope reporting in the generated agent contract and capability map.
+
+  - Match tenant-scoped tables by both authored/camelCase table names and generated SQL snake_case table names.
+  - Report camelCase liveQuery dependencies such as `onboardingTasks` as `tenant` scoped when `tenantScope.json` confirms `tenant_id`.
+  - Add regression coverage for the Team Onboarding style liveQuery/capability-map path.
+
+## 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
+
+- Improve the post-alpha.21 agent workflow without adding new MCP tools.
+
+  - Add `forge agent context` scopes for entry, change, proof, and handoff context packs.
+  - Add DeltaDB verbose health details for queue redaction, operation age, semantic projection state, and overhead posture.
+  - Add `forge delta compact`, `forge delta prune`, and redacted `forge delta export` for local Delta maintenance and support bundles.
+  - Add `forge doctor delta` for recorder writability, queue drain, redaction, and gitignore checks.
+  - Add Semantic Timeline summary data for stale proofs and causal chains.
+  - Record CAIR snapshot/query/action activity as Delta timeline events without adding new MCP tools.
+  - Add a Studio snapshot handoff block and a dedicated CAIR Protocol documentation page.
+  - Add an official `nuxt-web` template with a Forge notes backend, client/server Nuxt plugins, a `useNotes` composable, a Nitro runtime-config route, and generated Vue composables.
+
+## 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.
+
+## 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:

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,10 +1,14 @@
 # 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 H42. The core compiler, local runtime, frontend SDK, production auth, RLS compiler, repair/review loops, UI test bridge, guided intent router, full-stack capability map, clean templates, faster generated checks, showcase app, Windows-safe Bun resolution, native Windows diagnostics/setup, Node-compatible CLI/runtime paths, observable verify timeouts, multi-OS Node CI smoke, release packaging smoke, npm alpha publishing, Trusted Publisher/OIDC release wiring, ReadTheDocs-ready public docs, package/version-aligned generator metadata, AST-aware codemods for `extract-action`, `rename command`, `rename field`, and `rename table`, broader field-test automation, and quieter template workspaces are present. Public release hardening is still focused on deeper semantic codemods and more real-project field reports.
+**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.
 
-Public docs are configured for ReadTheDocs with `.readthedocs.yaml` and `mkdocs.yml`. The local docs entrypoint is `docs/index.md`.
+Public docs live at [forgeos.readthedocs.io](https://forgeos.readthedocs.io/). The repo builds them with `.readthedocs.yaml`, `mkdocs.yml`, and `docs/index.md`.
+
+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/), [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
 
@@ -47,7 +51,7 @@ These files describe the app surface, runtime rules, generated files, policies,
 Public one-command app creation:
 
 ```bash
-npm create forge-app@alpha notes-app -- --template minimal-web
+npm create forgeos-app@alpha notes-app -- --template minimal-web
 cd notes-app
 npm run dev
 ```
@@ -89,6 +93,39 @@ npm run field:test -- --package-managers npm --templates minimal-web --forge-spe
 
 The scheduled/manual `Field Tests` workflow expands that coverage across Linux, macOS, Windows, Node 22, Node 24, and npm/pnpm/yarn/bun.
 
+## External Runtimes And Adapters
+
+ForgeOS can import services written outside TypeScript through the Forge Protocol.
+External runtimes publish a `forge.manifest.json` that describes commands, queries,
+transport, policies, risk metadata, tenant scope, and schemas. Forge then emits
+the same machine-readable app/API/agent artifacts and exposes runtime bridge
+endpoints for those entries.
+
+The Go example starts a manifest-backed service:
+
+```bash
+cd examples/go-billing
+go run . --manifest --base-url http://127.0.0.1:8787 > forge.manifest.json
+go run . --addr 127.0.0.1:8787 --base-url http://127.0.0.1:8787
+```
+
+In a Forge app:
+
+```bash
+forge manifest validate ./forge.manifest.json --json
+forge manifest import ./forge.manifest.json --json
+forge generate
+forge run billing.createInvoice --args '{"title":"Invoice"}' --user-id u1 --tenant-id tenant-a --role admin
+forge query billing.listInvoices --args '{}' --user-id u1 --tenant-id tenant-a --role admin
+```
+
+For Java, see [`adapters/java`](adapters/java/README.md),
+[`adapters/java-spring-boot-starter`](adapters/java-spring-boot-starter/README.md),
+and [`examples/java-billing`](examples/java-billing/README.md).
+
+See [`docs/forge-protocol.md`](docs/forge-protocol.md), [`schemas/forge-manifest.schema.json`](schemas/forge-manifest.schema.json),
+and [`adapters/go`](adapters/go/README.md).
+
 ## What ForgeOS Generates
 
 ```txt
@@ -138,14 +175,17 @@ forge.lock
 | Auth | dev headers, JWT, OIDC discovery/JWKS verification via `jose`, production-mode guardrails |
 | RLS | Postgres RLS SQL compiler/checks for DB-enforced tenant isolation |
 | Secrets/env | secret registry, env schema, redaction, strict `process.env` checks |
-| AI | Vercel AI SDK v6 engine, provider registry, `ctx.ai`, `ctx.agent.run`, `aiTool`, `agent`, `/ai/agents/run` JSON automation, `/ai/agents/chat` UIMessage streaming, `forge ai trace`, mock mode, telemetry without prompt/output retention by default |
+| AI | Vercel AI SDK v6 engine, provider registry, `ctx.ai`, `ctx.agent.run`, `aiTool`, `agent`, `/ai/agents/run` JSON automation, `/ai/agents/chat` UIMessage streaming, `forge ai trace`, structural and model-level redteam probes, mock mode, telemetry without prompt/output retention by default |
 | Frontend | generated client SDK, React/Next hooks, template app, liveQuery client support |
 | LiveQuery | durable invalidation log, reconnect/resume semantics, production hardening checks |
+| DeltaDB | ambient local recorder plus inferred work sessions and semantic timelines for Forge commands, dev file saves, generated artifacts, runtime calls, policies, proofs, diagnostics, `forge timeline`, `forge explain`, and optional `forge session` correction |
+| Agent memory | opt-in Codex and Claude Code hooks, Cursor MCP/rules setup, normalized external agent events, redacted local memory, and `forge mcp serve` |
+| Brownfield import | static TypeScript/JavaScript app inventory with routes, frontend calls, env usage, candidate entries, risk report, migration plan, and hidden-by-default imported agent contract |
 | Self-host | compose/deploy artifacts and self-host checks |
 | Agent contract | `AGENTS.md`, `agentContract.json`, app maps, runtime rules, playbooks, inspect/doctor |
 | Authoring | `forge make`, feature blueprints, safe refactor plans, package upgrade plans |
 | Testing/repair | impact-based test planner, repair loop, structured review, UI/browser test bridge |
-| Adapters | agent adapter export for external AI tools |
+| Adapters | Forge Protocol manifest import plus Go, Java, and Spring Boot adapter support for executable external commands and queries |
 | Intent router | `forge do` maps objectives like fix, verify, connect UI, and add feature into plans, files, risks, and next commands |
 | Full-stack map | `frontendGraph` + `capabilityMap` connect routes, components, hooks, runtime entries, tables, policies, and gaps |
 | Dev loop | `forge dev` prints API/Web URLs, phase health, capability coverage, cache status, diagnostics, and next action |
@@ -166,6 +206,16 @@ forge dev
 forge inspect all --json
 forge inspect framework --json
 forge inspect capabilities --json
+forge delta status
+forge timeline
+forge timeline --session current
+forge explain <thing>
+forge explain session current
+forge session list
+forge agent memory --json
+forge mcp serve
+forge import analyze --json
+forge inspect imported --json
 forge doctor
 forge verify --standard
 forge verify --strict
@@ -187,8 +237,10 @@ Common command groups:
 | `forge check --json` | Validate guardrails and emit diagnostics with fix hints |
 | `forge verify --smoke` | Fast local gate: generated drift, Forge checks, typecheck when present, no tests/lint |
 | `forge verify --standard` | Agent development gate: generated drift, Forge/security checks, typecheck, and impact-selected tests |
-| `forge verify --strict` | Full handoff/CI gate: generated drift, Forge/security checks, typecheck, full test script, lint |
+| `forge verify --strict` | Full handoff/CI gate: generated drift, Forge/security checks, typecheck, full TestGraph in bounded parallel/isolated chunks, lint |
 | `forge verify --script-timeout-ms <ms>` | Run package scripts with a predictable timeout and machine-readable timeout diagnostics |
+| `forge verify --test-jobs <n>` | Tune strict TestGraph chunk parallelism; `FORGE_VERIFY_TEST_JOBS` is also supported |
+| `forge verify --strict --test-plan --json` | Print the strict TestGraph scheduler plan without running tests |
 | `forge do "<objective>" --json` | Guided intent router: choose the right workflow, files, risks, and next action |
 | `forge inspect <target> --json` | Inspect generated app/data/runtime/policy/client/agent/UI surfaces |
 | `forge inspect framework --json` | Inspect ForgeOS framework modules, CLI commands, templates, examples, tests, and preferred entrypoints |
@@ -208,7 +260,10 @@ Common command groups:
 | `forge ui` | Browser/UI smoke, scenario, route, snapshot, doctor, and reports |
 | `forge deps` | Package upgrade planning and application |
 | `forge release` | Release/source-map bridge and symbolication |
-| `forge agent`, `forge agent-contract` | Agent-facing contract and adapter exports |
+| `forge agent`, `forge agent-contract` | Agent-facing contract, adapter exports, context, install, ingest, and memory commands |
+| `forge mcp serve` | MCP server for external agents to read Forge context, memory, timeline, and inspect surfaces |
+| `forge import analyze`, `forge import inspect` | Brownfield TypeScript/JavaScript app inventory and reviewed migration planning |
+| `forge inspect imported --json` | Inspect `.forge/import` analysis artifacts |
 | `forge self-host` | Self-host packaging and checks |
 
 Refactor codemods are AST-aware where safety matters most:
@@ -243,12 +298,23 @@ See [`examples/showcase-forge-app`](examples/showcase-forge-app/README.md).
 
 ```bash
 cd examples/showcase-forge-app
-bun install
-bun run generate
-bun run dev
+npm install
+npm run generate
+npm run dev
 ```
 
-Examples are source-only where practical: generated artifacts, `forge.lock`, package lockfiles, and operational `.forge/**` state are recreated locally. The showcase demonstrates tenant-scoped data, policies, commands, queries, liveQueries, outbox actions, workflows, mock AI, telemetry trace IDs, generated React hooks, `agentContract`, `frontendGraph`, and `capabilityMap`.
+For the reproducible public proof path:
+
+```bash
+npm run proof:inspect
+npm run proof:dev
+npm run proof:capabilities
+npm run proof:verify
+```
+
+Read [`examples/showcase-forge-app/PUBLIC_PROOF.md`](examples/showcase-forge-app/PUBLIC_PROOF.md) for the full walkthrough.
+
+Examples are source-only where practical: generated artifacts, `forge.lock`, package lockfiles, and operational `.forge/**` state are recreated locally. The showcase demonstrates tenant-scoped data, policies, commands, queries, liveQueries, outbox actions, workflows, mock AI, telemetry trace IDs, generated React hooks, `agentContract`, `frontendGraph`, `capabilityMap`, and the standard agent handoff loop.
 
 ## Platform Support
 
@@ -347,7 +413,7 @@ Configure npm Trusted Publisher for package `forgeos`:
 | Environment | blank |
 | Allowed action | `npm publish` |
 
-Do not add `NPM_TOKEN` for normal releases. Alpha releases publish with the `alpha` dist-tag so prerelease builds do not become `latest` accidentally. Use `release:publish-local-alpha -- --dry-run` only to validate the staged tarball locally; real npm publishing should go through `release:publish-alpha`, which dispatches `publish.yml` and uses npm OIDC Trusted Publisher. The workflow checks whether the package version already exists before installing dependencies or running tests, then uses `id-token: write`, Node 24/npm 11+, and provenance for the actual publish. `npm run release:smoke` runs `npm pack`, creates a fresh app with the packed tarball, installs dependencies, runs `forge dev --once --json`, and verifies the app smoke path.
+Do not add `NPM_TOKEN` for normal alpha publishes. Alpha releases publish with the `alpha` dist-tag through npm OIDC Trusted Publisher so prerelease builds do not become `latest` accidentally. Configure `NPM_TOKEN` only when maintainers intentionally want the workflow to promote `latest` with `npm dist-tag add forgeos@<version> latest`; otherwise that step is skipped and `latest` may lag behind `alpha` during hardening. Use `release:publish-local-alpha -- --dry-run` only to validate the staged tarball locally; real npm publishing should go through `release:publish-alpha`, which dispatches `publish.yml` and uses npm OIDC Trusted Publisher. The workflow checks whether the package version already exists before installing dependencies or running tests, then uses `id-token: write`, Node 24/npm 11+, and provenance for the actual publish. `npm run release:smoke` runs `npm pack`, creates a fresh app with the packed tarball, installs dependencies, runs `forge dev --once --json`, and verifies the app smoke path.
 
 ## Milestone History
 
@@ -394,6 +460,13 @@ H39  Showcase app
 H40  Windows/runtime hardening
 H41  Node-compatible CLI/runtime
 H42  Verify observability and quieter app workspaces
+H43  Native AI tools and agent loop
+H44  Ambient DeltaDB recorder
+H45  Automatic work-session inference
+H46  Automatic change grouping
+H47  Semantic timeline
+H48  Agent Memory Bridge
+H49  Brownfield import analysis
 ```
 
 ## Remaining Hardening Before Public Release

package/adapters/go/README.md

@@ -0,0 +1,23 @@
+# Forge Go Adapter
+
+`adapters/go` is the minimal Go SDK for external Forge runtimes. It registers
+commands and queries, emits `forge.manifest.json`, and exposes a Forge-compatible
+HTTP handler.
+
+```go
+app := forge.New("billing", forge.BaseURL("http://127.0.0.1:8787"))
+
+app.Command("createInvoice", forge.Handle(createInvoice),
+    forge.Policy("billing.manage"),
+    forge.TenantScoped(true),
+    forge.NeedsApproval(true),
+)
+
+app.Query("listInvoices", forge.Handle(listInvoices),
+    forge.Policy("billing.manage"),
+    forge.TenantScoped(true),
+)
+```
+
+The HTTP handler accepts Forge runtime envelopes on `/commands/:name` and
+`/queries/:name`, then returns `{ "ok": true, "result": ... }` envelopes.

package/adapters/go/go.mod

@@ -0,0 +1,3 @@
+module github.com/Stahldavid/forge/adapters/go
+
+go 1.22