forgeos 0.1.0-alpha.65 → 0.1.0-alpha.67

package/README.md

@@ -1,525 +1,525 @@
-# ForgeOS
-
-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.
-
-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
-
-```bash
-bun install --ignore-scripts
-bun run forge generate
-bun run forge do inspect --json
-bun run forge dev
-bun run forge dev --once --json
-bun run forge inspect all --json
-bun run forge inspect framework --json
-bun run forge doctor
-bun run forge verify --standard
-bun run forge verify --strict
-```
-
-Node is supported for the CLI/runtime path as well:
-
-```bash
-npm install
-npm run forge:node -- generate
-npm run forge:node -- dev --once --json
-npm run forge:node -- inspect framework --json
-```
-
-When working as an AI coder, read:
-
-```txt
-AGENTS.md
-src/forge/_generated/agentContract.json
-src/forge/_generated/runtimeRules.md
-src/forge/_generated/appMap.md
-src/forge/_generated/operationPlaybooks.md
-```
-
-These files describe the app surface, runtime rules, generated files, policies, secrets, workflows, UI routes, commands to run, and common repair/refactor playbooks.
-
-## Create a Test App
-
-Public one-command app creation:
-
-```bash
-npm create forgeos-app@alpha notes-app -- --template minimal-web
-cd notes-app
-npm run dev
-```
-
-Equivalent lower-level command without installing ForgeOS globally:
-
-```bash
-npm exec --package forgeos@alpha -- forge new notes-app --template minimal-web --package-manager npm
-```
-
-If ForgeOS is already installed or you are inside this repository:
-
-```bash
-forge new notes-app --template minimal-web --package-manager npm
-cd notes-app
-npm run dev -- --open
-```
-
-`forge dev` starts the API runtime and the web dev server together when a `web/` app exists. The `--once --json` mode is the central agent/CI diagnostic entrypoint: it checks generated drift, guardrails, frontend routes/bindings, doctor status, impact, and the last test/UI reports in one deterministic response.
-
-Template apps ignore `src/forge/_generated/`, `forge.lock`, and operational `.forge/**` work dirs by default so a freshly created app does not flood git or the editor with generated files. Run `forge generate` after checkout or before verification to recreate the agent contract, client SDK, frontend graph, capability map, and runtime manifests.
-Templates also include workspace editor excludes for generated/runtime directories so source files stay visually prominent.
-
-## Production-Shaped Golden Path
-
-For a real multi-tenant app with WorkOS/AuthKit, start with the golden-path
-planner instead of piecing together commands from docs:
-
-```bash
-forge golden-path plan --auth workos --target docker --real --production --json
-```
-
-The canonical path is:
-
-```bash
-forge field-test create vendor-access --auth workos --template vendor-access --package-manager npm --install --git --json
-cd vendor-access
-npm run forge -- workos env --client-id client_... --write --json
-npm run forge -- workos setup --real --file workos-seed.yml --json
-npm run forge -- auth prove --provider workos --real --client-id client_... --file workos-seed.yml --json
-npm run forge -- field-test run --realistic --json
-npm run forge -- deploy readiness --production --json
-npm run forge -- deploy package --target docker
-```
-
-For an existing app, ask ForgeOS for the current blocking stage:
-
-```bash
-forge golden-path status --real --production --json
-```
-
-It reports whether the app can publish, which stage blocks publication, and the
-next command to run. WorkOS FGA is optional; ordinary B2B apps can ship with
-AuthKit, RBAC permission claims, Forge policies, and tenant isolation.
-
-If the AuthKit client id is already known, pass it to the status command so the
-next action is copy/paste exact instead of using `client_...` placeholders:
-
-```bash
-forge golden-path status --real --production --client-id client_... --json
-```
-
-When the WorkOS CLI can confirm a client id exists but cannot expose the value,
-`golden-path status` asks for `forge workos env --client-id client_... --write
---json`; ForgeOS then writes the OIDC/JWKS and web public env values without
-dashboard clicks or shell-specific env syntax. The higher-level
-`forge auth prove --provider workos --real --client-id client_... --file
-workos-seed.yml --json` wrapper performs the same env preparation before it
-proves hosted WorkOS setup.
-
-For release or external smoke testing, choose the Forge package source explicitly:
-
-```bash
-forge new smoke-app --template minimal-web --package-manager npm --forge-spec "npm:forgeos@alpha"
-forge new local-app --template minimal-web --package-manager npm --local-forge
-```
-
-`--forge-spec` writes that dependency spec into the generated app, while `--local-forge` keeps the monorepo/local package workflow. The npm package is published as `forgeos`, but generated apps keep the dependency key, CLI binary, and import surface as `forge` (`forge`, `forge/server`, `forge/react`) by using npm alias specs such as `"forge": "npm:forgeos@alpha"`. CI uses both `--forge-spec "file:$GITHUB_WORKSPACE"` and a packed tarball smoke to prove freshly created apps can install ForgeOS and run outside the framework workspace.
-
-For broader field testing:
-
-```bash
-npm run field:test -- --dry-run --json
-npm run field:test -- --package-managers npm --templates minimal-web --forge-spec "file:." --install --json
-```
-
-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
-src/forge/_generated/
-  api.ts/json
-  client.ts, clientTypes.ts, clientApi.ts
-  react.ts, reactManifest.ts/json
-  appGraph.ts/json
-  dataGraph.ts/json
-  runtimeGraph.ts/json
-  runtimeMatrix.ts/json
-  policyRegistry.ts/json
-  permissionMatrix.ts/json
-  tenantScope.ts/json
-  secretRegistry.ts/json
-  aiRegistry.ts/json
-  workflowRegistry.ts/json
-  liveQueryRegistry.ts/json
-  agentContract.ts/json
-  capabilityMap.ts/json/md
-  agentAdapterManifest.ts/json
-  testGraph.ts/json
-  uiTestManifest.ts/json
-  uiRoutes.ts/json
-  uiScenarios.ts/json
-```
-
-Project-level generated context:
-
-```txt
-AGENTS.md
-forge.lock
-.forge/test-plans/**
-.forge/repairs/**
-.forge/refactors/**
-.forge/ui-runs/**
-```
-
-## Core Capabilities
-
-| Area | What exists now |
-| --- | --- |
-| Compiler | AppGraph, DataGraph, RuntimeGraph, PackageGraph, deterministic generated artifacts, drift checks |
-| Runtime | commands, queries, liveQueries, actions, workflows, durable outbox, local dev server |
-| Data | schema compiler, SQL DDL, migrations, PGlite/Postgres adapter, tenant scope metadata |
-| Policies | RBAC policy registry, permission matrix, simulation, strict policy checks |
-| 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`, 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 | 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 |
-| Templates | source-only templates and showcase app avoid committing generated artifacts by default |
-| Verification | `forge verify --smoke`, `--standard`, and `--strict` report per-step duration/command metadata, use impact-selected tests for the standard loop, and time out package scripts predictably |
-
-## Command Map
-
-Prefer task-oriented commands first:
-
-```bash
-forge do "<objective>" --json
-forge do fix --json
-forge do connect-ui --json
-forge do verify --json
-forge dev --once --json
-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
-forge impact --changed --json
-forge test plan --changed --json
-forge test run --changed --timeout-ms 120000 --json
-forge repair diagnose --from-last-test-run --json
-forge repair diagnose --from-last-ui-run --json
-forge review run --changed --json
-forge ui smoke --json
-```
-
-Common command groups:
-
-| Command | Purpose |
-| --- | --- |
-| `forge generate` | Analyze source and emit generated artifacts |
-| `forge generate --check` | Fail on generated drift |
-| `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 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 |
-| `forge doctor --json` | Human/agent health check for project coherence |
-| `forge dev` | Interactive local loop: generated checks, API runtime, DB, worker, watch mode, frontend server, URLs, and next agent checks |
-| `forge dev --once --json` | One-shot diagnostic orchestrator for agents/CI: generated drift/cache hit, check, frontend, capability map, doctor, impact, reports, next actions |
-| `forge run`, `forge query`, `forge live` | Execute and inspect runtime entries locally |
-| `forge db`, `forge rls` | Diff/migrate/status and inspect/check RLS |
-| `forge policy`, `forge secrets`, `forge env`, `forge auth` | Security and configuration operations |
-| `forge make` | Scaffold resources, commands, queries, policies, actions, workflows |
-| `forge feature` | Validate/plan/apply feature blueprints |
-| `forge refactor` | Plan/apply/rollback safe refactors and targeted codemods |
-| `forge impact`, `forge test` | Compute change impact and run targeted checks |
-| `forge test run --timeout-ms <ms>` | Run impact-selected checks with a per-command timeout |
-| `forge repair` | Diagnose failures and produce repair plans |
-| `forge review` | Structured code review with findings and suggested commands |
-| `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, 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 and Java/Spring app inventory with 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:
-
-- `forge refactor extract-action` is binding-aware and preserves unrelated imports, type-only imports, and shadowed locals.
-- `forge refactor rename command <oldName> <newName>` rewrites command declarations, generated client references, React hook usage, tests, and safe string references while preserving unrelated symbols.
-- `forge refactor rename field <table.field> <table.field>` rewrites structured TS/JS/JSX/TSX and JSON references, preserves locals, and scopes the field change to files/objects linked to the target table. For example, `tickets.priority -> tickets.urgency` does not rewrite a generic `priority` prop in a component with no `tickets` binding.
-- `forge refactor rename table <from> <to>` rewrites table definitions, `ctx.db.<table>` access, policy strings, JSON/blueprints, and import/export specifiers while preserving unrelated locals with the same name.
-
-## Runtime Rules
-
-Commands are transactional and deterministic:
-
-- allowed: `ctx.db`, `ctx.emit`, buffered telemetry
-- forbidden: network packages, direct integrations, `ctx.secrets`, `ctx.ai`, direct `process.env`
-
-Queries and liveQueries are read-only:
-
-- allowed: scoped DB reads
-- forbidden: writes, emits, secrets, AI, network integrations
-
-Actions and workflows handle side effects after commit:
-
-- allowed: integrations, secrets, AI, network packages, retries
-- expected: idempotent behavior and traceable telemetry
-
-Use `src/forge/_generated/runtimeRules.md` as the canonical generated version.
-
-## Showcase App
-
-See [`examples/showcase-forge-app`](examples/showcase-forge-app/README.md).
-
-```bash
-cd examples/showcase-forge-app
-npm install
-npm run generate
-npm run dev
-```
-
-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
-
-| Platform | Support |
-| --- | --- |
-| Linux | Supported for MVP development |
-| macOS | Supported for MVP development |
-| Windows (WSL) | Supported for MVP development |
-| Windows (native) | Experimental, with `forge doctor windows` and `forge setup windows` |
-
-ForgeOS is Bun-first but no longer Bun-only. The package bin runs through Node via `tsx`, the dev server has a `node:http` fallback, package scripts use the detected package manager, and the Postgres adapter uses `Bun.SQL` when available or the `postgres` npm package under Node.
-
-Known Windows note: ForgeOS resolves Bun through a Windows-safe resolver and ignores known non-Bun `Kiro-Cli\bun` shims. If your shell still resolves a broken app association, invoke Bun from the real install path:
-
-```powershell
-& "$env:USERPROFILE\.bun\bin\bun.exe"
-```
-
-Native Windows diagnostics:
-
-```powershell
-node .\bin\forge.mjs doctor windows --json
-node .\bin\forge.mjs setup windows --json
-```
-
-`forge doctor windows` checks Node, npm, Git, safe Bun resolution, suspicious Bun shims, Git long-path support, PowerShell execution policy, and symlink support. `forge setup windows` is dry-run by default and only applies supported environment fixes with `--yes`.
-
-For Node-only local checks, use:
-
-```powershell
-node .\bin\forge.mjs dev --once --json
-node .\bin\forge.mjs inspect framework --json
-```
-
-## Verification
-
-Fast focused checks:
-
-```bash
-bun run typecheck
-bun run lint
-bun test tests/<area>
-bun run forge generate --check
-forge verify --changed
-```
-
-Full gate:
-
-```bash
-bun test --timeout 120000
-bun run forge verify --strict
-```
-
-UI bridge note: `forge ui` uses Playwright when installed. Without Playwright, `forge ui doctor --json` reports `FORGE_UI_PLAYWRIGHT_MISSING` with fix hints instead of silently failing.
-
-Frontend bridge note: `forge inspect frontend --json` and `forge dev --once --json` expose routes, components, `ForgeProvider`, generated client bindings, raw runtime fetch warnings, and fix hints. Agents should use this before editing UI wiring.
-
-CI note: the main GitHub Actions gate runs the full Bun-based verification path on Ubuntu. A separate Node breadth smoke matrix runs on Ubuntu, Windows, and macOS with Node 22 and 24, including template package-manager smoke for npm, pnpm, yarn, and Bun.
-
-## npm Release
-
-ForgeOS publishes to npm as `forgeos` and exposes the executable as `forge`.
-
-Release automation uses Changesets plus npm Trusted Publishing:
-
-```bash
-npm run changeset
-npm run version-packages
-npm run release:smoke
-```
-
-For the first prerelease publish, use the alpha dist-tag explicitly:
-
-```bash
-npm run release:publish-local-alpha -- --dry-run
-npm run release:publish-alpha
-```
-
-The normal path is:
-
-```txt
-merge feature PR with changeset
-  -> publish.yml opens/updates a version PR
-merge version PR
-  -> publish.yml publishes through npm OIDC Trusted Publisher
-```
-
-Configure npm Trusted Publisher for package `forgeos`:
-
-| Field | Value |
-| --- | --- |
-| Provider | GitHub Actions |
-| Organization/user | `Stahldavid` |
-| Repository | `forge` |
-| Workflow filename | `publish.yml` |
-| Environment | blank |
-| Allowed action | `npm publish` |
-
-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
-
-```txt
-H1   Hardening, CI, examples
-H2   Reference integration quality
-H3   DataGraph Compiler
-H4   Local command/action runtime
-H5   Local dev server
-H6   DataGraph-backed persistence runtime
-H7   Durable outbox worker
-H8   Lightweight workflow engine
-H9   Telemetry bridge
-H10  Auth, policy engine, tenant isolation
-H11  Secrets & environment runtime
-H12  AI workflow integration
-H13  Query runtime & typed API surface
-H14  Frontend client SDK core
-H15  LiveQuery/Reactivity MVP
-H16  React/Next hooks
-H17  Minimal frontend app template
-H18  Self-host packaging
-H19  Agent Contract & Project Introspection Layer
-H20  Production Auth / JWT & OIDC v1
-H21  Postgres RLS Compiler & DB-enforced tenant isolation
-H22  Package Upgrade Planner
-H23  Release / Source Map Bridge
-H24  Production LiveQuery Hardening
-H25  Authoring primitives: forge make
-H26  Feature Blueprint Compiler
-H27  Safe Refactor / Codemod Engine
-H28  Impact-Based Test Planner
-H29  Repair Loop
-H30  Agent Adapter Export
-H31  Forge Review / Structured Code Review
-H32  UI / Browser Test Bridge
-H33  Intent Router / Guided Dev Loop
-H34  Full-Stack App Contract v2
-H35  Capability Map
-H36  Template hygiene / git noise
-H37  Convex-style forge dev panel
-H38  Fast generated check visibility
-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
-
-- Keep expanding semantic codemods beyond the current AST-aware `extract-action`, `rename command`, `rename field`, and `rename table` paths.
-- Reduce command-selection risk with more task routers and richer inline diagnostics.
-- Keep hardening native Windows setup beyond diagnostics and safe automatic environment fixes.
-- Keep broadening package manager CI from template smoke toward install/build smoke for pnpm and yarn apps.
-- Broaden UI bridge coverage with installed Playwright browsers in CI.
+# ForgeOS
+
+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.
+
+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
+
+```bash
+bun install --ignore-scripts
+bun run forge generate
+bun run forge do inspect --json
+bun run forge dev
+bun run forge dev --once --json
+bun run forge inspect all --json
+bun run forge inspect framework --json
+bun run forge doctor
+bun run forge verify --standard
+bun run forge verify --strict
+```
+
+Node is supported for the CLI/runtime path as well:
+
+```bash
+npm install
+npm run forge:node -- generate
+npm run forge:node -- dev --once --json
+npm run forge:node -- inspect framework --json
+```
+
+When working as an AI coder, read:
+
+```txt
+AGENTS.md
+src/forge/_generated/agentContract.json
+src/forge/_generated/runtimeRules.md
+src/forge/_generated/appMap.md
+src/forge/_generated/operationPlaybooks.md
+```
+
+These files describe the app surface, runtime rules, generated files, policies, secrets, workflows, UI routes, commands to run, and common repair/refactor playbooks.
+
+## Create a Test App
+
+Public one-command app creation:
+
+```bash
+npm create forgeos-app@alpha notes-app -- --template minimal-web
+cd notes-app
+npm run dev
+```
+
+Equivalent lower-level command without installing ForgeOS globally:
+
+```bash
+npm exec --package forgeos@alpha -- forge new notes-app --template minimal-web --package-manager npm
+```
+
+If ForgeOS is already installed or you are inside this repository:
+
+```bash
+forge new notes-app --template minimal-web --package-manager npm
+cd notes-app
+npm run dev -- --open
+```
+
+`forge dev` starts the API runtime and the web dev server together when a `web/` app exists. The `--once --json` mode is the central agent/CI diagnostic entrypoint: it checks generated drift, guardrails, frontend routes/bindings, doctor status, impact, and the last test/UI reports in one deterministic response.
+
+Template apps ignore `src/forge/_generated/`, `forge.lock`, and operational `.forge/**` work dirs by default so a freshly created app does not flood git or the editor with generated files. Run `forge generate` after checkout or before verification to recreate the agent contract, client SDK, frontend graph, capability map, and runtime manifests.
+Templates also include workspace editor excludes for generated/runtime directories so source files stay visually prominent.
+
+## Production-Shaped Golden Path
+
+For a real multi-tenant app with WorkOS/AuthKit, start with the golden-path
+planner instead of piecing together commands from docs:
+
+```bash
+forge golden-path plan --auth workos --target docker --real --production --json
+```
+
+The canonical path is:
+
+```bash
+forge field-test create vendor-access --auth workos --template vendor-access --package-manager npm --install --git --json
+cd vendor-access
+npm run forge -- workos env --client-id client_... --write --json
+npm run forge -- workos setup --real --file workos-seed.yml --json
+npm run forge -- auth prove --provider workos --real --client-id client_... --file workos-seed.yml --json
+npm run forge -- field-test run --realistic --json
+npm run forge -- deploy readiness --production --json
+npm run forge -- deploy package --target docker
+```
+
+For an existing app, ask ForgeOS for the current blocking stage:
+
+```bash
+forge golden-path status --real --production --json
+```
+
+It reports whether the app can publish, which stage blocks publication, and the
+next command to run. WorkOS FGA is optional; ordinary B2B apps can ship with
+AuthKit, RBAC permission claims, Forge policies, and tenant isolation.
+
+If the AuthKit client id is already known, pass it to the status command so the
+next action is copy/paste exact instead of using `client_...` placeholders:
+
+```bash
+forge golden-path status --real --production --client-id client_... --json
+```
+
+When the WorkOS CLI can confirm a client id exists but cannot expose the value,
+`golden-path status` asks for `forge workos env --client-id client_... --write
+--json`; ForgeOS then writes the OIDC/JWKS and web public env values without
+dashboard clicks or shell-specific env syntax. The higher-level
+`forge auth prove --provider workos --real --client-id client_... --file
+workos-seed.yml --json` wrapper performs the same env preparation before it
+proves hosted WorkOS setup.
+
+For release or external smoke testing, choose the Forge package source explicitly:
+
+```bash
+forge new smoke-app --template minimal-web --package-manager npm --forge-spec "npm:forgeos@alpha"
+forge new local-app --template minimal-web --package-manager npm --local-forge
+```
+
+`--forge-spec` writes that dependency spec into the generated app, while `--local-forge` keeps the monorepo/local package workflow. The npm package is published as `forgeos`, but generated apps keep the dependency key, CLI binary, and import surface as `forge` (`forge`, `forge/server`, `forge/react`) by using npm alias specs such as `"forge": "npm:forgeos@alpha"`. CI uses both `--forge-spec "file:$GITHUB_WORKSPACE"` and a packed tarball smoke to prove freshly created apps can install ForgeOS and run outside the framework workspace.
+
+For broader field testing:
+
+```bash
+npm run field:test -- --dry-run --json
+npm run field:test -- --package-managers npm --templates minimal-web --forge-spec "file:." --install --json
+```
+
+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
+src/forge/_generated/
+  api.ts/json
+  client.ts, clientTypes.ts, clientApi.ts
+  react.ts, reactManifest.ts/json
+  appGraph.ts/json
+  dataGraph.ts/json
+  runtimeGraph.ts/json
+  runtimeMatrix.ts/json
+  policyRegistry.ts/json
+  permissionMatrix.ts/json
+  tenantScope.ts/json
+  secretRegistry.ts/json
+  aiRegistry.ts/json
+  workflowRegistry.ts/json
+  liveQueryRegistry.ts/json
+  agentContract.ts/json
+  capabilityMap.ts/json/md
+  agentAdapterManifest.ts/json
+  testGraph.ts/json
+  uiTestManifest.ts/json
+  uiRoutes.ts/json
+  uiScenarios.ts/json
+```
+
+Project-level generated context:
+
+```txt
+AGENTS.md
+forge.lock
+.forge/test-plans/**
+.forge/repairs/**
+.forge/refactors/**
+.forge/ui-runs/**
+```
+
+## Core Capabilities
+
+| Area | What exists now |
+| --- | --- |
+| Compiler | AppGraph, DataGraph, RuntimeGraph, PackageGraph, deterministic generated artifacts, drift checks |
+| Runtime | commands, queries, liveQueries, actions, workflows, durable outbox, local dev server |
+| Data | schema compiler, SQL DDL, migrations, PGlite/Postgres adapter, tenant scope metadata |
+| Policies | RBAC policy registry, permission matrix, simulation, strict policy checks |
+| 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`, 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 | 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 |
+| Templates | source-only templates and showcase app avoid committing generated artifacts by default |
+| Verification | `forge verify --smoke`, `--standard`, and `--strict` report per-step duration/command metadata, use impact-selected tests for the standard loop, and time out package scripts predictably |
+
+## Command Map
+
+Prefer task-oriented commands first:
+
+```bash
+forge do "<objective>" --json
+forge do fix --json
+forge do connect-ui --json
+forge do verify --json
+forge dev --once --json
+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
+forge impact --changed --json
+forge test plan --changed --json
+forge test run --changed --timeout-ms 120000 --json
+forge repair diagnose --from-last-test-run --json
+forge repair diagnose --from-last-ui-run --json
+forge review run --changed --json
+forge ui smoke --json
+```
+
+Common command groups:
+
+| Command | Purpose |
+| --- | --- |
+| `forge generate` | Analyze source and emit generated artifacts |
+| `forge generate --check` | Fail on generated drift |
+| `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 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 |
+| `forge doctor --json` | Human/agent health check for project coherence |
+| `forge dev` | Interactive local loop: generated checks, API runtime, DB, worker, watch mode, frontend server, URLs, and next agent checks |
+| `forge dev --once --json` | One-shot diagnostic orchestrator for agents/CI: generated drift/cache hit, check, frontend, capability map, doctor, impact, reports, next actions |
+| `forge run`, `forge query`, `forge live` | Execute and inspect runtime entries locally |
+| `forge db`, `forge rls` | Diff/migrate/status and inspect/check RLS |
+| `forge policy`, `forge secrets`, `forge env`, `forge auth` | Security and configuration operations |
+| `forge make` | Scaffold resources, commands, queries, policies, actions, workflows |
+| `forge feature` | Validate/plan/apply feature blueprints |
+| `forge refactor` | Plan/apply/rollback safe refactors and targeted codemods |
+| `forge impact`, `forge test` | Compute change impact and run targeted checks |
+| `forge test run --timeout-ms <ms>` | Run impact-selected checks with a per-command timeout |
+| `forge repair` | Diagnose failures and produce repair plans |
+| `forge review` | Structured code review with findings and suggested commands |
+| `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, 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 and Java/Spring app inventory with 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:
+
+- `forge refactor extract-action` is binding-aware and preserves unrelated imports, type-only imports, and shadowed locals.
+- `forge refactor rename command <oldName> <newName>` rewrites command declarations, generated client references, React hook usage, tests, and safe string references while preserving unrelated symbols.
+- `forge refactor rename field <table.field> <table.field>` rewrites structured TS/JS/JSX/TSX and JSON references, preserves locals, and scopes the field change to files/objects linked to the target table. For example, `tickets.priority -> tickets.urgency` does not rewrite a generic `priority` prop in a component with no `tickets` binding.
+- `forge refactor rename table <from> <to>` rewrites table definitions, `ctx.db.<table>` access, policy strings, JSON/blueprints, and import/export specifiers while preserving unrelated locals with the same name.
+
+## Runtime Rules
+
+Commands are transactional and deterministic:
+
+- allowed: `ctx.db`, `ctx.emit`, buffered telemetry
+- forbidden: network packages, direct integrations, `ctx.secrets`, `ctx.ai`, direct `process.env`
+
+Queries and liveQueries are read-only:
+
+- allowed: scoped DB reads
+- forbidden: writes, emits, secrets, AI, network integrations
+
+Actions and workflows handle side effects after commit:
+
+- allowed: integrations, secrets, AI, network packages, retries
+- expected: idempotent behavior and traceable telemetry
+
+Use `src/forge/_generated/runtimeRules.md` as the canonical generated version.
+
+## Showcase App
+
+See [`examples/showcase-forge-app`](examples/showcase-forge-app/README.md).
+
+```bash
+cd examples/showcase-forge-app
+npm install
+npm run generate
+npm run dev
+```
+
+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
+
+| Platform | Support |
+| --- | --- |
+| Linux | Supported for MVP development |
+| macOS | Supported for MVP development |
+| Windows (WSL) | Supported for MVP development |
+| Windows (native) | Experimental, with `forge doctor windows` and `forge setup windows` |
+
+ForgeOS is Bun-first but no longer Bun-only. The package bin runs through Node via `tsx`, the dev server has a `node:http` fallback, package scripts use the detected package manager, and the Postgres adapter uses `Bun.SQL` when available or the `postgres` npm package under Node.
+
+Known Windows note: ForgeOS resolves Bun through a Windows-safe resolver and ignores known non-Bun `Kiro-Cli\bun` shims. If your shell still resolves a broken app association, invoke Bun from the real install path:
+
+```powershell
+& "$env:USERPROFILE\.bun\bin\bun.exe"
+```
+
+Native Windows diagnostics:
+
+```powershell
+node .\bin\forge.mjs doctor windows --json
+node .\bin\forge.mjs setup windows --json
+```
+
+`forge doctor windows` checks Node, npm, Git, safe Bun resolution, suspicious Bun shims, Git long-path support, PowerShell execution policy, and symlink support. `forge setup windows` is dry-run by default and only applies supported environment fixes with `--yes`.
+
+For Node-only local checks, use:
+
+```powershell
+node .\bin\forge.mjs dev --once --json
+node .\bin\forge.mjs inspect framework --json
+```
+
+## Verification
+
+Fast focused checks:
+
+```bash
+bun run typecheck
+bun run lint
+bun test tests/<area>
+bun run forge generate --check
+forge verify --changed
+```
+
+Full gate:
+
+```bash
+bun test --timeout 120000
+bun run forge verify --strict
+```
+
+UI bridge note: `forge ui` uses Playwright when installed. Without Playwright, `forge ui doctor --json` reports `FORGE_UI_PLAYWRIGHT_MISSING` with fix hints instead of silently failing.
+
+Frontend bridge note: `forge inspect frontend --json` and `forge dev --once --json` expose routes, components, `ForgeProvider`, generated client bindings, raw runtime fetch warnings, and fix hints. Agents should use this before editing UI wiring.
+
+CI note: the main GitHub Actions gate runs the full Bun-based verification path on Ubuntu. A separate Node breadth smoke matrix runs on Ubuntu, Windows, and macOS with Node 22 and 24, including template package-manager smoke for npm, pnpm, yarn, and Bun.
+
+## npm Release
+
+ForgeOS publishes to npm as `forgeos` and exposes the executable as `forge`.
+
+Release automation uses Changesets plus npm Trusted Publishing:
+
+```bash
+npm run changeset
+npm run version-packages
+npm run release:smoke
+```
+
+For the first prerelease publish, use the alpha dist-tag explicitly:
+
+```bash
+npm run release:publish-local-alpha -- --dry-run
+npm run release:publish-alpha
+```
+
+The normal path is:
+
+```txt
+merge feature PR with changeset
+  -> publish.yml opens/updates a version PR
+merge version PR
+  -> publish.yml publishes through npm OIDC Trusted Publisher
+```
+
+Configure npm Trusted Publisher for package `forgeos`:
+
+| Field | Value |
+| --- | --- |
+| Provider | GitHub Actions |
+| Organization/user | `Stahldavid` |
+| Repository | `forge` |
+| Workflow filename | `publish.yml` |
+| Environment | blank |
+| Allowed action | `npm publish` |
+
+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
+
+```txt
+H1   Hardening, CI, examples
+H2   Reference integration quality
+H3   DataGraph Compiler
+H4   Local command/action runtime
+H5   Local dev server
+H6   DataGraph-backed persistence runtime
+H7   Durable outbox worker
+H8   Lightweight workflow engine
+H9   Telemetry bridge
+H10  Auth, policy engine, tenant isolation
+H11  Secrets & environment runtime
+H12  AI workflow integration
+H13  Query runtime & typed API surface
+H14  Frontend client SDK core
+H15  LiveQuery/Reactivity MVP
+H16  React/Next hooks
+H17  Minimal frontend app template
+H18  Self-host packaging
+H19  Agent Contract & Project Introspection Layer
+H20  Production Auth / JWT & OIDC v1
+H21  Postgres RLS Compiler & DB-enforced tenant isolation
+H22  Package Upgrade Planner
+H23  Release / Source Map Bridge
+H24  Production LiveQuery Hardening
+H25  Authoring primitives: forge make
+H26  Feature Blueprint Compiler
+H27  Safe Refactor / Codemod Engine
+H28  Impact-Based Test Planner
+H29  Repair Loop
+H30  Agent Adapter Export
+H31  Forge Review / Structured Code Review
+H32  UI / Browser Test Bridge
+H33  Intent Router / Guided Dev Loop
+H34  Full-Stack App Contract v2
+H35  Capability Map
+H36  Template hygiene / git noise
+H37  Convex-style forge dev panel
+H38  Fast generated check visibility
+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
+
+- Keep expanding semantic codemods beyond the current AST-aware `extract-action`, `rename command`, `rename field`, and `rename table` paths.
+- Reduce command-selection risk with more task routers and richer inline diagnostics.
+- Keep hardening native Windows setup beyond diagnostics and safe automatic environment fixes.
+- Keep broadening package manager CI from template smoke toward install/build smoke for pnpm and yarn apps.
+- Broaden UI bridge coverage with installed Playwright browsers in CI.