forgeos 0.1.0-alpha.0

package/src/forge/_generated/index.ts

@@ -0,0 +1,67 @@
+// @forge-generated generator=0.0.0 input=6c20676780d2128492bff9f4ba9f149b0cb26d7bf18f682568c96e4ef5a91a56 content=b122f97bc3d917dbc7dc48156b07b134d75446ffdcec0e1b46c8332ff9a53508
+export * from "./actionSubscriptions";
+export * from "./agentAdapterManifest";
+export * from "./agentContract";
+export * from "./aiContext";
+export * from "./aiModels";
+export * from "./aiProviders";
+export * from "./aiRegistry";
+export * from "./api";
+export * from "./appGraph";
+export * from "./artifactManifest";
+export * from "./authClaims";
+export * from "./authConfig";
+export * from "./authContext";
+export * from "./authRegistry";
+export * from "./buildInfo";
+export * from "./capabilityMap";
+export * from "./client";
+export * from "./clientApi";
+export * from "./clientManifest";
+export * from "./clientTypes";
+export * from "./configRegistry";
+export * from "./dataGraph";
+export * from "./db";
+export * from "./dbSecurityManifest";
+export * from "./dbSessionContext";
+export * from "./deployManifest";
+export * from "./devManifest";
+export * from "./envSchema";
+export * from "./frontendGraph";
+export * from "./importGuards";
+export * from "./liveProductionManifest";
+export * from "./liveProtocol";
+export * from "./liveQueryRegistry";
+export * from "./liveTransportConfig";
+export * from "./makeRegistry";
+export * from "./makeTemplates";
+export * from "./mockMap";
+export * from "./packageGraph";
+export * from "./packageUpgradeRegistry";
+export * from "./permissionMatrix";
+export * from "./policyRegistry";
+export * from "./queryRegistry";
+export * from "./react";
+export * from "./reactManifest";
+export * from "./releaseManifest";
+export * from "./rlsPolicies";
+export * from "./runtimeGraph";
+export * from "./runtimeMatrix";
+export * from "./runtimeRegistry";
+export * from "./secretRegistry";
+export * from "./secretsContext";
+export * from "./serverApi";
+export * from "./sourceMapManifest";
+export * from "./sqlPlan";
+export * from "./subscriptionManifest";
+export * from "./symbolicationManifest";
+export * from "./telemetryRegistry";
+export * from "./telemetrySinks";
+export * from "./tenantScope";
+export * from "./testGraph";
+export * from "./testPlanRegistry";
+export * from "./uiRoutes";
+export * from "./uiScenarios";
+export * from "./uiTestManifest";
+export * from "./workflowRegistry";
+export * from "./workflowSubscriptions";

package/src/forge/_generated/liveProductionManifest.json

@@ -0,0 +1,2 @@
+// @forge-generated generator=0.0.0 input=688a8f80ae64b3520539b60ed79d8f0dde426f02cd0d42dec906896865312d99 content=967f429b3fb0e3fbcef692494eb289adc5e9f1a733f54b93923473b52877be39
+{"dependencyGranularity":"table-tenant","invalidationSource":"durable-table","limits":{"heartbeatIntervalMs":15000,"maxPendingMessagesPerSubscription":5,"maxSnapshotBytes":1000000,"maxSubscriptionsPerClient":50,"maxSubscriptionsPerTenant":500,"rerunDebounceMs":50},"liveQueries":[],"mode":"production-hardened","schemaVersion":"0.1.0","transports":["sse"],"wakeupAdapters":["postgres-notify","polling"]}

package/src/forge/_generated/liveProductionManifest.ts

@@ -0,0 +1,23 @@
+// @forge-generated generator=0.0.0 input=688a8f80ae64b3520539b60ed79d8f0dde426f02cd0d42dec906896865312d99 content=0439047e248d49da4c0bad6c54d6accfbdd68738a961a52f373ffb440742f841
+export const liveProductionManifest = {
+  "dependencyGranularity": "table-tenant",
+  "invalidationSource": "durable-table",
+  "limits": {
+    "heartbeatIntervalMs": 15000,
+    "maxPendingMessagesPerSubscription": 5,
+    "maxSnapshotBytes": 1000000,
+    "maxSubscriptionsPerClient": 50,
+    "maxSubscriptionsPerTenant": 500,
+    "rerunDebounceMs": 50
+  },
+  "liveQueries": [],
+  "mode": "production-hardened",
+  "schemaVersion": "0.1.0",
+  "transports": [
+    "sse"
+  ],
+  "wakeupAdapters": [
+    "postgres-notify",
+    "polling"
+  ]
+} as const;

package/src/forge/_generated/liveProtocol.json

@@ -0,0 +1,2 @@
+// @forge-generated generator=0.0.0 input=688a8f80ae64b3520539b60ed79d8f0dde426f02cd0d42dec906896865312d99 content=2547500ca2a41f806de71a91fb967c7d242fadc9f669a903f44d48ae6447fb66
+{"messages":["hello","snapshot","error","heartbeat","reset"],"protocolVersion":"0.1.0","resume":{"queryParam":"lastRevision","sseLastEventId":true},"schemaVersion":"0.1.0","snapshot":{"fullSnapshotOnly":true,"includesReleaseId":true,"includesRevision":true}}

package/src/forge/_generated/liveProtocol.ts

@@ -0,0 +1,21 @@
+// @forge-generated generator=0.0.0 input=688a8f80ae64b3520539b60ed79d8f0dde426f02cd0d42dec906896865312d99 content=9893ba2b2189291fef35ab6ea0abea261f01415a078c25760333a00933c313ed
+export const liveProtocol = {
+  "messages": [
+    "hello",
+    "snapshot",
+    "error",
+    "heartbeat",
+    "reset"
+  ],
+  "protocolVersion": "0.1.0",
+  "resume": {
+    "queryParam": "lastRevision",
+    "sseLastEventId": true
+  },
+  "schemaVersion": "0.1.0",
+  "snapshot": {
+    "fullSnapshotOnly": true,
+    "includesReleaseId": true,
+    "includesRevision": true
+  }
+} as const;

package/src/forge/_generated/liveQueryRegistry.json

@@ -0,0 +1,2 @@
+// @forge-generated generator=0.0.0 input=eb8d78e749f083957f69f7f316aa4efc3faf5ccd81ff63e3cf32bf7fb7f705ac content=6c163d104c50a1c2df29828caf0f0295cb55bdfcb73258d203b2c3e510c20390
+{"analyzerVersion":"0.1.0","diagnostics":[],"generatorVersion":"0.0.0","inputHash":"dd356f5b886d56bc39e3633c018d348746ab64c4d5e7778b0ba47687e421f568","liveQueries":[],"schemaVersion":"0.1.0"}

package/src/forge/_generated/liveQueryRegistry.ts

@@ -0,0 +1,9 @@
+// @forge-generated generator=0.0.0 input=eb8d78e749f083957f69f7f316aa4efc3faf5ccd81ff63e3cf32bf7fb7f705ac content=7ffa554973eba85079d4ab97e057cf5e78aa35b527431dd59bd6b9b886da45a1
+export const liveQueryRegistry = {
+  "analyzerVersion": "0.1.0",
+  "diagnostics": [],
+  "generatorVersion": "0.0.0",
+  "inputHash": "dd356f5b886d56bc39e3633c018d348746ab64c4d5e7778b0ba47687e421f568",
+  "liveQueries": [],
+  "schemaVersion": "0.1.0"
+} as const;

package/src/forge/_generated/liveTransportConfig.json

@@ -0,0 +1,2 @@
+// @forge-generated generator=0.0.0 input=688a8f80ae64b3520539b60ed79d8f0dde426f02cd0d42dec906896865312d99 content=b8074453717d4c465dd2928bfd4ed51ecbf4d9ce9bff5d20e63c8a026f4b1cc8
+{"defaultTransport":"sse","schemaVersion":"0.1.0","selfHostEnv":{"FORGE_LIVE_HEARTBEAT_MS":"15000","FORGE_LIVE_INVALIDATION":"polling,postgres-notify","FORGE_LIVE_POLL_INTERVAL_MS":"1000","FORGE_LIVE_TRANSPORT":"sse"},"transports":{"sse":{"endpoint":"/live/:name","heartbeat":true,"multiplexEndpoint":"/live/stream","oneConnectionPerClientRecommended":true}}}

package/src/forge/_generated/liveTransportConfig.ts

@@ -0,0 +1,19 @@
+// @forge-generated generator=0.0.0 input=688a8f80ae64b3520539b60ed79d8f0dde426f02cd0d42dec906896865312d99 content=9166cbf6c2ee6161ea374ec2da35d146fc04efd6f2a1ca307eb3518c4f6c2046
+export const liveTransportConfig = {
+  "defaultTransport": "sse",
+  "schemaVersion": "0.1.0",
+  "selfHostEnv": {
+    "FORGE_LIVE_HEARTBEAT_MS": "15000",
+    "FORGE_LIVE_INVALIDATION": "polling,postgres-notify",
+    "FORGE_LIVE_POLL_INTERVAL_MS": "1000",
+    "FORGE_LIVE_TRANSPORT": "sse"
+  },
+  "transports": {
+    "sse": {
+      "endpoint": "/live/:name",
+      "heartbeat": true,
+      "multiplexEndpoint": "/live/stream",
+      "oneConnectionPerClientRecommended": true
+    }
+  }
+} as const;

package/src/forge/_generated/makeRegistry.json

@@ -0,0 +1,2 @@
+// @forge-generated generator=0.0.0 input=caf049950405a6022290d7ace56f44ae9b4892557c40e94a08bf463799a04c24 content=6869b097473d93b65249814c121887ba2c9b9ed211a25742defd99b2e0b29392
+{"commands":["forge make list --json","forge make explain <primitive> --json","forge make ui --framework vite --dry-run --json","forge make resource <name> --fields title:text,status:enum(open,closed) --dry-run --json","forge make resource <name> --fields title:text --with-ui --yes","forge make apply <planId>","forge make rollback <planId>"],"generatorVersion":"0.0.0","planDirectory":".forge/make-plans","primitives":[{"creates":[],"examples":["forge make table invoices --fields amount:number,status:text"],"modifies":["src/forge/schema.ts"],"name":"table","summary":"Add a schema table declaration."},{"creates":[],"examples":["forge make field invoices.status --type enum --values draft,paid"],"modifies":["src/forge/schema.ts"],"name":"field","summary":"Add a field to an existing table declaration."},{"creates":["src/policies.ts when missing"],"examples":["forge make policy invoices.read --roles owner,admin,member"],"modifies":["src/policies.ts"],"name":"policy","summary":"Add a named policy with allowed roles."},{"creates":["src/commands/<name>.ts"],"examples":["forge make command invoices.create --table invoices --policy invoices.create --emit invoice.created"],"modifies":[],"name":"command","summary":"Add a transactional command with policy and optional event emission."},{"creates":["src/queries/<name>.ts"],"examples":["forge make query invoices.list --table invoices --policy invoices.read"],"modifies":[],"name":"query","summary":"Add a read-only query."},{"creates":["src/queries/live<Name>.ts"],"examples":["forge make livequery invoices.live --table invoices --policy invoices.read"],"modifies":[],"name":"livequery","summary":"Add a read-only liveQuery for reactive clients."},{"creates":["src/actions/<name>.ts"],"examples":["forge make action captureInvoiceCreated --event invoice.created"],"modifies":[],"name":"action","summary":"Add an after-commit action subscribed to an event."},{"creates":["src/workflows/<name>.ts"],"examples":["forge make workflow invoiceWorkflow --table invoices --trigger invoice.created"],"modifies":[],"name":"workflow","summary":"Add a durable workflow triggered by an event."},{"creates":["web/components/<Component>.tsx"],"examples":["forge make component InvoiceList --table invoices"],"modifies":[],"name":"component","summary":"Add a React component that uses generated Forge client hooks."},{"creates":["web/app/<route>/page.tsx"],"examples":["forge make page invoices --table invoices --with-create-form"],"modifies":[],"name":"page","summary":"Add a minimal app page wired to generated components."},{"creates":["web/package.json","web/index.html","web/src/lib/forge.ts","web/src/main.tsx","web/src/App.tsx"],"examples":["forge make ui --framework vite --yes"],"modifies":[],"name":"ui","summary":"Add a Vite React frontend shell with ForgeProvider devAuth and a generated client bridge."},{"creates":["src/commands/*","src/queries/*","src/actions/*","web/components/*","web/app/*","tests/make-generated/*"],"examples":["forge make resource invoices --fields amount:number,status:enum(draft,paid) --with-ui --yes"],"modifies":["src/forge/schema.ts","src/policies.ts"],"name":"resource","summary":"Add schema, policies, CRUD, queries, liveQuery, optional UI, and tests."}],"schemaVersion":"0.1.0"}

package/src/forge/_generated/makeRegistry.ts

@@ -0,0 +1,163 @@
+// @forge-generated generator=0.0.0 input=caf049950405a6022290d7ace56f44ae9b4892557c40e94a08bf463799a04c24 content=983a7102a05fff669953a71b674b5e38d26dcca6c8beb120da6ea22efd5e43da
+export const makeRegistry = {
+  "commands": [
+    "forge make list --json",
+    "forge make explain <primitive> --json",
+    "forge make ui --framework vite --dry-run --json",
+    "forge make resource <name> --fields title:text,status:enum(open,closed) --dry-run --json",
+    "forge make resource <name> --fields title:text --with-ui --yes",
+    "forge make apply <planId>",
+    "forge make rollback <planId>"
+  ],
+  "generatorVersion": "0.0.0",
+  "planDirectory": ".forge/make-plans",
+  "primitives": [
+    {
+      "creates": [],
+      "examples": [
+        "forge make table invoices --fields amount:number,status:text"
+      ],
+      "modifies": [
+        "src/forge/schema.ts"
+      ],
+      "name": "table",
+      "summary": "Add a schema table declaration."
+    },
+    {
+      "creates": [],
+      "examples": [
+        "forge make field invoices.status --type enum --values draft,paid"
+      ],
+      "modifies": [
+        "src/forge/schema.ts"
+      ],
+      "name": "field",
+      "summary": "Add a field to an existing table declaration."
+    },
+    {
+      "creates": [
+        "src/policies.ts when missing"
+      ],
+      "examples": [
+        "forge make policy invoices.read --roles owner,admin,member"
+      ],
+      "modifies": [
+        "src/policies.ts"
+      ],
+      "name": "policy",
+      "summary": "Add a named policy with allowed roles."
+    },
+    {
+      "creates": [
+        "src/commands/<name>.ts"
+      ],
+      "examples": [
+        "forge make command invoices.create --table invoices --policy invoices.create --emit invoice.created"
+      ],
+      "modifies": [],
+      "name": "command",
+      "summary": "Add a transactional command with policy and optional event emission."
+    },
+    {
+      "creates": [
+        "src/queries/<name>.ts"
+      ],
+      "examples": [
+        "forge make query invoices.list --table invoices --policy invoices.read"
+      ],
+      "modifies": [],
+      "name": "query",
+      "summary": "Add a read-only query."
+    },
+    {
+      "creates": [
+        "src/queries/live<Name>.ts"
+      ],
+      "examples": [
+        "forge make livequery invoices.live --table invoices --policy invoices.read"
+      ],
+      "modifies": [],
+      "name": "livequery",
+      "summary": "Add a read-only liveQuery for reactive clients."
+    },
+    {
+      "creates": [
+        "src/actions/<name>.ts"
+      ],
+      "examples": [
+        "forge make action captureInvoiceCreated --event invoice.created"
+      ],
+      "modifies": [],
+      "name": "action",
+      "summary": "Add an after-commit action subscribed to an event."
+    },
+    {
+      "creates": [
+        "src/workflows/<name>.ts"
+      ],
+      "examples": [
+        "forge make workflow invoiceWorkflow --table invoices --trigger invoice.created"
+      ],
+      "modifies": [],
+      "name": "workflow",
+      "summary": "Add a durable workflow triggered by an event."
+    },
+    {
+      "creates": [
+        "web/components/<Component>.tsx"
+      ],
+      "examples": [
+        "forge make component InvoiceList --table invoices"
+      ],
+      "modifies": [],
+      "name": "component",
+      "summary": "Add a React component that uses generated Forge client hooks."
+    },
+    {
+      "creates": [
+        "web/app/<route>/page.tsx"
+      ],
+      "examples": [
+        "forge make page invoices --table invoices --with-create-form"
+      ],
+      "modifies": [],
+      "name": "page",
+      "summary": "Add a minimal app page wired to generated components."
+    },
+    {
+      "creates": [
+        "web/package.json",
+        "web/index.html",
+        "web/src/lib/forge.ts",
+        "web/src/main.tsx",
+        "web/src/App.tsx"
+      ],
+      "examples": [
+        "forge make ui --framework vite --yes"
+      ],
+      "modifies": [],
+      "name": "ui",
+      "summary": "Add a Vite React frontend shell with ForgeProvider devAuth and a generated client bridge."
+    },
+    {
+      "creates": [
+        "src/commands/*",
+        "src/queries/*",
+        "src/actions/*",
+        "web/components/*",
+        "web/app/*",
+        "tests/make-generated/*"
+      ],
+      "examples": [
+        "forge make resource invoices --fields amount:number,status:enum(draft,paid) --with-ui --yes"
+      ],
+      "modifies": [
+        "src/forge/schema.ts",
+        "src/policies.ts"
+      ],
+      "name": "resource",
+      "summary": "Add schema, policies, CRUD, queries, liveQuery, optional UI, and tests."
+    }
+  ],
+  "schemaVersion": "0.1.0"
+} as const;

package/src/forge/_generated/makeTemplates.json

@@ -0,0 +1,2 @@
+// @forge-generated generator=0.0.0 input=caf049950405a6022290d7ace56f44ae9b4892557c40e94a08bf463799a04c24 content=3ded5d373abd46034055220ea12a715a71c2f706cf4a87a75e7d66d72bf79f33
+{"schemaVersion":"0.1.0","templates":[{"name":"schema-table","outputPattern":"src/forge/schema.ts","sourceKind":"schema"},{"name":"policy","outputPattern":"src/policies.ts","sourceKind":"policy"},{"name":"command","outputPattern":"src/commands/<name>.ts","sourceKind":"runtime"},{"name":"query","outputPattern":"src/queries/<name>.ts","sourceKind":"runtime"},{"name":"livequery","outputPattern":"src/queries/live<Name>.ts","sourceKind":"runtime"},{"name":"action","outputPattern":"src/actions/<name>.ts","sourceKind":"runtime"},{"name":"workflow","outputPattern":"src/workflows/<name>.ts","sourceKind":"runtime"},{"name":"component","outputPattern":"web/components/<name>.tsx","sourceKind":"frontend"},{"name":"page","outputPattern":"web/app/<route>/page.tsx","sourceKind":"frontend"},{"name":"ui","outputPattern":"web/src/App.tsx","sourceKind":"frontend"},{"name":"placeholder-test","outputPattern":"tests/make-generated/<name>.test.ts","sourceKind":"test"}]}

package/src/forge/_generated/makeTemplates.ts

@@ -0,0 +1,61 @@
+// @forge-generated generator=0.0.0 input=caf049950405a6022290d7ace56f44ae9b4892557c40e94a08bf463799a04c24 content=bec3e76f4a2feb0f6a1f4e3fb74d038a13ce13c7da0796fe16f4567ca0594f6e
+export const makeTemplates = {
+  "schemaVersion": "0.1.0",
+  "templates": [
+    {
+      "name": "schema-table",
+      "outputPattern": "src/forge/schema.ts",
+      "sourceKind": "schema"
+    },
+    {
+      "name": "policy",
+      "outputPattern": "src/policies.ts",
+      "sourceKind": "policy"
+    },
+    {
+      "name": "command",
+      "outputPattern": "src/commands/<name>.ts",
+      "sourceKind": "runtime"
+    },
+    {
+      "name": "query",
+      "outputPattern": "src/queries/<name>.ts",
+      "sourceKind": "runtime"
+    },
+    {
+      "name": "livequery",
+      "outputPattern": "src/queries/live<Name>.ts",
+      "sourceKind": "runtime"
+    },
+    {
+      "name": "action",
+      "outputPattern": "src/actions/<name>.ts",
+      "sourceKind": "runtime"
+    },
+    {
+      "name": "workflow",
+      "outputPattern": "src/workflows/<name>.ts",
+      "sourceKind": "runtime"
+    },
+    {
+      "name": "component",
+      "outputPattern": "web/components/<name>.tsx",
+      "sourceKind": "frontend"
+    },
+    {
+      "name": "page",
+      "outputPattern": "web/app/<route>/page.tsx",
+      "sourceKind": "frontend"
+    },
+    {
+      "name": "ui",
+      "outputPattern": "web/src/App.tsx",
+      "sourceKind": "frontend"
+    },
+    {
+      "name": "placeholder-test",
+      "outputPattern": "tests/make-generated/<name>.test.ts",
+      "sourceKind": "test"
+    }
+  ]
+} as const;

package/src/forge/_generated/mockMap.json

@@ -0,0 +1,2 @@
+// @forge-generated generator=0.0.0 input=a364a2ec435f1ad252c1d418c40d3d787ffd94db8ab078dc670d129e1ab2d4fd content=ce79e45d4228d202a492670aa76f238986b5500c8bb53774b328c216a1ccc6d8
+{"entries":[{"mockFile":"src/forge/_generated/testkits/ai.anthropic.mock.ts","packageName":"@ai-sdk/anthropic"},{"mockFile":"src/forge/_generated/testkits/ai.openai.mock.ts","packageName":"@ai-sdk/openai"},{"mockFile":"src/forge/_generated/testkits/ai.gateway.mock.ts","packageName":"ai"},{"mockFile":"src/forge/_generated/testkits/zod.mock.ts","packageName":"zod"}]}

package/src/forge/_generated/mockMap.ts

@@ -0,0 +1,7 @@
+// @forge-generated generator=0.0.0 input=a364a2ec435f1ad252c1d418c40d3d787ffd94db8ab078dc670d129e1ab2d4fd content=4c569da5df387f6bb7fe7fd94d42b4cc6b05f5218ab0bc129d9637c184625057
+export const mockMap = {
+  "@ai-sdk/anthropic": "src/forge/_generated/testkits/ai.anthropic.mock.ts",
+  "@ai-sdk/openai": "src/forge/_generated/testkits/ai.openai.mock.ts",
+  "ai": "src/forge/_generated/testkits/ai.gateway.mock.ts",
+  "zod": "src/forge/_generated/testkits/zod.mock.ts"
+} as const;

package/src/forge/_generated/operationPlaybooks.md

@@ -0,0 +1,145 @@
+// @forge-generated generator=0.0.0 input=c66c98a8c537973af073e7571f522683b815b3f5adafa2cc9a3135b370a91b9e content=6dd405e3d1dbf89a38afa243593c1f4443d1ce9e86fb69fa12c16140ff3c5dad
+# Operation Playbooks
+
+## Choose the right workflow
+
+1. Run forge do "<objective>" --json when the next command is not obvious.
+2. Use forge do fix --json for failures, forge do verify --json before handoff, and forge do connect-ui --json for frontend wiring.
+3. Follow the returned plan, filesToInspect, risks, and nextAction before using lower-level commands directly.
+
+## Add a command
+
+1. Add a file under src/commands.
+2. Declare auth with can("policy.name") unless intentionally public/system.
+3. Use ctx.db for transactional writes.
+4. Use ctx.emit for side effects.
+5. Run forge generate.
+6. Run forge verify --strict.
+
+## Add a query
+
+1. Add a file under src/queries.
+2. Keep it read-only.
+3. Declare auth explicitly.
+4. Run forge generate.
+5. Run forge check.
+
+## Add a liveQuery
+
+1. Add a liveQuery under src/queries.
+2. Keep it read-only and tenant-scoped when reading tenant tables.
+3. Run forge generate.
+4. Use forge inspect client --json to confirm client exposure.
+
+## Debug a stale liveQuery
+
+1. Run forge live status --json.
+2. Run forge live invalidations list --json and confirm the table and tenant changed.
+3. Run forge live debug <subscriptionId> --json when a subscription id is available.
+4. Check that _forge_live_invalidations has revisions newer than the last sent snapshot.
+5. Reconnect with Last-Event-ID or ?lastRevision=<revision> to verify resume behavior.
+
+## Add a table
+
+1. Edit src/forge/schema.ts.
+2. Include tenantId for tenant-scoped data.
+3. Run forge generate.
+4. Run forge db diff.
+5. Run forge verify --strict.
+
+## Scaffold a resource
+
+1. Run forge make resource <name> --fields name:type,status:enum(open,closed) --dry-run --json.
+2. Review the plan and diagnostics.
+3. Run forge make resource <name> --fields name:type --with-ui --yes when the resource should be visible in the web app.
+4. Run forge generate.
+5. Run forge verify --strict.
+
+## Apply a feature blueprint
+
+1. Write a JSON blueprint under .forge/blueprints.
+2. Run forge feature validate <blueprint> --json.
+3. Run forge feature plan <blueprint>.
+4. Review the plan, impact, and risk.
+5. Run forge feature apply <blueprint> --yes.
+6. Run forge verify --strict.
+
+## Safely refactor a feature
+
+1. Run forge refactor rename field <table.field> <table.field> --dry-run --json.
+2. Rename codemods are AST-aware for extract-action, rename field, and rename table.
+3. Field renames are scoped to the target table, so tickets.priority only rewrites references linked to tickets.
+4. Review filesToModify, migrationPlan, diagnostics, and risk.
+5. Use --allow-high-risk only for intentional high-risk refactors.
+6. Apply with forge refactor rename field <table.field> <table.field> --yes.
+7. Run forge generate.
+8. Run forge verify --strict.
+
+## Plan impact-based tests
+
+1. Run forge impact --changed --json.
+2. Run forge test plan --changed --json.
+3. Run forge test run --changed --timeout-ms 120000 --json for targeted checks.
+4. Use forge verify --changed for the fast impact gate.
+5. Run forge verify --strict before final handoff.
+
+## Repair a failing check
+
+1. Run forge test run --changed --json.
+2. Run forge repair diagnose --from-last-test-run --json.
+3. Review the failureKind, likelyCause, suggestedRepairs, and confidence.
+4. Apply only high-confidence repairs automatically.
+5. Run forge verify --changed.
+6. Run forge verify --strict before final handoff.
+
+## Add a package
+
+1. Use forge add <alias>.
+2. Do not install packages manually unless the architecture exception is intentional.
+3. Run forge generate.
+4. Run forge check.
+
+## Upgrade a package
+
+1. Run forge deps upgrade-plan <package> --to latest.
+2. Read .forge/upgrades/.../plan.md.
+3. If risk is high, inspect affected files and generated adapters before applying.
+4. Apply with forge deps upgrade-apply <plan>.
+5. Finish with forge verify --strict.
+
+## Debug a policy error
+
+1. Capture the traceId from the response or frontend.
+2. Run forge telemetry inspect <traceId>.
+3. Run forge policy simulate <policy> --role <role>.
+
+## Run dev
+
+1. Run forge dev for the full local loop: generated checks, API runtime, web app, DB, worker, watch, and startup URLs.
+2. Run forge dev --once --json for a one-shot diagnostic cycle.
+3. Use --api-only, --web-only, --no-watch, or --no-worker only when narrowing the loop intentionally.
+4. When a web app exists, forge dev starts the API runtime and the web dev server together and prints both URLs.
+5. Use generated client and React hooks through web/lib/forge.ts.
+
+## Add or update frontend
+
+1. Run forge make ui --framework vite --dry-run --json when the app does not have a web root.
+2. Use web/lib/forge.ts as the generated client bridge.
+3. Mount ForgeProvider once in the web app provider/layout layer; use devAuth for local development.
+4. Use useQuery, useCommand, and useLiveQuery instead of raw /commands or /queries fetches.
+5. Run forge generate so frontendGraph and agentContract include routes and bindings.
+6. Run forge inspect capabilities --json to confirm UI actions map to runtime capabilities.
+7. Run forge dev --once --json and forge doctor --json.
+
+## Self-host
+
+1. Run forge self-host compose.
+2. Review deploy/.env.example.
+3. Run forge self-host check.
+
+## Debug a production stack trace
+
+1. Run forge release inspect <releaseId> --json.
+2. Run forge release sourcemaps symbolicate --input stacktrace.json --json.
+3. Open the original source file and line from the symbolicated frame.
+4. Use forge telemetry inspect <traceId> --with-release --json when a trace id is available.