forgeos 0.1.0-alpha.21 → 0.1.0-alpha.23

package/src/forge/delta/store.ts

@@ -1,4 +1,4 @@
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative } from "node:path";
 import { createPgliteAdapter } from "../runtime/db/pglite-adapter.ts";
 import type { DbAdapter } from "../runtime/db/adapter.ts";
@@ -160,6 +160,10 @@ export interface DeltaSemanticTimelineFilter extends DeltaTimelineFilter {
   until?: string;
 }
 
+export interface DeltaSemanticTimelineReadOptions {
+  refresh?: boolean;
+}
+
 export interface DeltaSemanticTimelineResult {
   entity?: DeltaTimelineEntityRef;
   currentState: Record<string, unknown>;
@@ -219,6 +223,27 @@ export interface DeltaStatusDetails {
     agentMemoryEvents: number;
     semanticEvents: number;
   };
+  operational: {
+    storeExists: boolean;
+    storeSizeBytes?: number;
+    queuePath: string;
+    queueExists: boolean;
+    queueSizeBytes: number;
+    queuePendingEvents: number;
+    queueRedaction: "none" | "redacted" | "legacy-raw-present" | "mixed" | "unknown";
+    queueHistoryPath: string;
+    queueHistoryExists: boolean;
+    queueHistorySizeBytes: number;
+    queueHistoryLines: number;
+    lastCompactionAt?: string;
+    oldestOperationAt?: string;
+    newestOperationAt?: string;
+    estimatedOverhead: "low" | "medium" | "high";
+  };
+  health: {
+    status: "ok" | "warning";
+    checks: Array<{ name: string; status: "ok" | "warning"; message: string }>;
+  };
 }
 
 export type DeltaWorkSessionKind = "auto" | "agent" | "human" | "ci" | "git" | "manual-corrected";
@@ -952,12 +977,59 @@ export class DeltaStore {
       this.adapter.query(`SELECT COUNT(*)::int AS count FROM agent_memory_events`),
       this.adapter.query(`SELECT COUNT(*)::int AS count FROM timeline_events`),
     ]);
+    const operationWindow = await this.adapter.query(
+      `SELECT MIN(timestamp) AS oldest, MAX(timestamp) AS newest FROM operations`,
+    );
     const countAt = (index: number) => Number(countQueries[index]?.rows[0]?.count ?? 0);
     const lockPath = getDeltaLockPath(this.workspaceRoot);
     const postmasterPath = join(this.storePath, "postmaster.pid");
+    const queuePath = join(this.workspaceRoot, ".forge", "agent", "events.ndjson");
+    const queueHistoryPath = join(this.workspaceRoot, ".forge", "agent", "events.ndjson.history");
+    const queueExists = existsSync(queuePath);
+    const queueSizeBytes = queueExists ? statSync(queuePath).size : 0;
+    const queueHistoryExists = existsSync(queueHistoryPath);
+    const queueHistoryStat = queueHistoryExists ? statSync(queueHistoryPath) : undefined;
+    const queueHistorySizeBytes = queueHistoryStat?.size ?? 0;
+    const operationCount = countAt(1);
+    const queueRedaction = inspectAgentQueueRedaction(queuePath);
+    const queuePendingEvents = countNdjsonLines(queuePath);
+    const queueHistoryLines = countNdjsonLines(queueHistoryPath);
     const storedVersion = meta.get("schemaVersion");
     const lastOperationId = meta.get("semantic.lastOperationId");
     const lastRebuildAt = meta.get("semantic.lastRebuildAt");
+    const checks: DeltaStatusDetails["health"]["checks"] = [
+      {
+        name: "schema",
+        status: !storedVersion || storedVersion === DELTA_SCHEMA_VERSION ? "ok" : "warning",
+        message: storedVersion
+          ? `schema ${storedVersion}, expected ${DELTA_SCHEMA_VERSION}`
+          : `schema will initialize as ${DELTA_SCHEMA_VERSION}`,
+      },
+      {
+        name: "locks",
+        status: existsSync(lockPath) ? "warning" : "ok",
+        message: existsSync(lockPath) ? `${normalizePath(relative(this.workspaceRoot, lockPath))} is present` : "no Forge writer lock present",
+      },
+      {
+        name: "queue-redaction",
+        status: queueRedaction === "legacy-raw-present" || queueRedaction === "mixed" ? "warning" : "ok",
+        message: queueRedaction === "none"
+          ? "agent queue is empty or absent"
+          : queueRedaction === "redacted"
+            ? "agent queue contains redacted hook entries"
+            : queueRedaction === "mixed"
+              ? "agent queue contains both redacted and legacy raw hook entries"
+              : queueRedaction === "legacy-raw-present"
+                ? "agent queue contains legacy raw hook entries; drain/compact it"
+                : "agent queue redaction status is unknown",
+      },
+      {
+        name: "semantic-projection",
+        status: lastOperationId ? "ok" : operationCount > 0 ? "warning" : "ok",
+        message: lastOperationId ? `projected through ${lastOperationId}` : operationCount > 0 ? "semantic timeline has not projected operations yet" : "no operations recorded yet",
+      },
+    ];
+    const storeStat = existsSync(this.storePath) ? statSync(this.storePath) : undefined;
     return {
       schema: {
         expectedVersion: DELTA_SCHEMA_VERSION,
@@ -976,7 +1048,7 @@ export class DeltaStore {
       },
       counts: {
         sessions: countAt(0),
-        operations: countAt(1),
+        operations: operationCount,
         fileChanges: countAt(2),
         commandRuns: countAt(3),
         runtimeCalls: countAt(4),
@@ -986,6 +1058,27 @@ export class DeltaStore {
         agentMemoryEvents: countAt(8),
         semanticEvents: countAt(9),
       },
+      operational: {
+        storeExists: existsSync(this.storePath),
+        ...(storeStat && storeStat.isFile() ? { storeSizeBytes: storeStat.size } : {}),
+        queuePath: normalizePath(relative(this.workspaceRoot, queuePath)),
+        queueExists,
+        queueSizeBytes,
+        queuePendingEvents,
+        queueRedaction,
+        queueHistoryPath: normalizePath(relative(this.workspaceRoot, queueHistoryPath)),
+        queueHistoryExists,
+        queueHistorySizeBytes,
+        queueHistoryLines,
+        ...(queueHistoryStat ? { lastCompactionAt: queueHistoryStat.mtime.toISOString() } : {}),
+        ...(typeof operationWindow.rows[0]?.oldest === "string" ? { oldestOperationAt: String(operationWindow.rows[0].oldest) } : {}),
+        ...(typeof operationWindow.rows[0]?.newest === "string" ? { newestOperationAt: String(operationWindow.rows[0].newest) } : {}),
+        estimatedOverhead: estimatedDeltaOverhead(operationCount, queueSizeBytes),
+      },
+      health: {
+        status: checks.some((check) => check.status === "warning") ? "warning" : "ok",
+        checks,
+      },
     };
   }
 
@@ -1034,8 +1127,13 @@ export class DeltaStore {
     return result.rows.reverse().map(rowToTimelineEntry);
   }
 
-  async semanticTimeline(filter: DeltaSemanticTimelineFilter = {}): Promise<DeltaSemanticTimelineResult> {
-    await this.ensureSemanticTimelineFresh();
+  async semanticTimeline(
+    filter: DeltaSemanticTimelineFilter = {},
+    options: DeltaSemanticTimelineReadOptions = {},
+  ): Promise<DeltaSemanticTimelineResult> {
+    if (options.refresh !== false) {
+      await this.ensureSemanticTimelineFresh();
+    }
     const limit = Math.max(1, Math.min(filter.limit ?? 50, 200));
     const entity = parseTimelineEntityTarget(filter.target);
     const params: unknown[] = [];
@@ -2254,6 +2352,9 @@ function semanticEventKindForOperation(
   if (context.kind === "git.commit.detected" || context.kind === "git.mapping.detected") {
     return "git.exported";
   }
+  if (context.kind.startsWith("cair.")) {
+    return context.kind;
+  }
   if (context.kind.startsWith("agent.") || context.kind.startsWith("approval.")) {
     return context.kind;
   }
@@ -2304,6 +2405,15 @@ function semanticTitleForOperation(
   if (eventKind === "git.exported") {
     return "Exported to Git";
   }
+  if (eventKind.startsWith("cair.")) {
+    const verb = typeof context.data.actionVerb === "string"
+      ? context.data.actionVerb
+      : typeof context.data.queryVerb === "string"
+        ? context.data.queryVerb
+        : undefined;
+    const label = eventKind.replace(/^cair\./, "").replace(/\./g, " ");
+    return `CAIR ${label}${verb ? `: ${verb}` : ""}`;
+  }
   if (eventKind === "agent.prompt.submitted") {
     return `${agentNameFromContext(context) ?? "Agent"} submitted a prompt`;
   }
@@ -2323,7 +2433,7 @@ function semanticSeverity(eventKind: string): string {
   if (eventKind === "failed" || eventKind === "denied" || eventKind === "proof.failed" || eventKind.endsWith(".failed") || eventKind.endsWith(".denied")) {
     return "error";
   }
-  if (eventKind === "proof.passed" || eventKind === "executed" || eventKind.endsWith(".completed")) {
+  if (eventKind === "proof.passed" || eventKind === "executed" || eventKind.endsWith(".completed") || eventKind === "cair.plan.applied") {
     return "success";
   }
   if (eventKind === "policy.changed" || eventKind === "dependency.added" || eventKind === "dependency.upgraded") {
@@ -2372,6 +2482,12 @@ function timelineEntitiesFromContext(
   }
   add("agent", agentNameFromContext(context), "source", 0.95);
   add("agent-tool", context.data.toolName, eventKind.startsWith("agent.tool") ? "primary" : "affected", 0.95);
+  if (context.kind.startsWith("cair.")) {
+    add("cair", "protocol", "source", 0.95);
+    add("cair-action", context.data.actionVerb, eventKind.includes("action") || eventKind.includes("plan") ? "primary" : "affected", 0.9);
+    add("cair-query", context.data.queryVerb, eventKind === "cair.query.run" ? "primary" : "affected", 0.9);
+    add("file", context.data.inputPath, "source", 0.75);
+  }
   for (const service of context.services) {
     add("external-service", service, eventKind === "imported" ? "primary" : "source", 0.88);
   }
@@ -2582,6 +2698,89 @@ function latestEventTimestamp(events: DeltaSemanticTimelineEvent[], kinds: strin
   return [...events].reverse().find((event) => kinds.includes(event.kind))?.timestamp;
 }
 
+function inspectAgentQueueRedaction(queuePath: string): DeltaStatusDetails["operational"]["queueRedaction"] {
+  if (!existsSync(queuePath)) {
+    return "none";
+  }
+  try {
+    const size = statSync(queuePath).size;
+    if (size === 0) {
+      return "none";
+    }
+    const fd = openSync(queuePath, "r");
+    let sample = "";
+    try {
+      const buffer = Buffer.alloc(Math.min(size, 64_000));
+      const bytesRead = readSync(fd, buffer, 0, buffer.length, 0);
+      sample = buffer.subarray(0, bytesRead).toString("utf8");
+    } finally {
+      closeSync(fd);
+    }
+    if (!sample.trim()) {
+      return "none";
+    }
+    const hasRedacted = sample.includes("\"payloadRedacted\":true") || sample.includes("\"rawStored\":false");
+    const hasLegacyRaw = sample.includes("\"raw\":") || sample.includes("\"rawStored\":true");
+    if (hasRedacted && hasLegacyRaw) {
+      return "mixed";
+    }
+    if (hasLegacyRaw) {
+      return "legacy-raw-present";
+    }
+    return hasRedacted ? "redacted" : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function countNdjsonLines(path: string): number {
+  if (!existsSync(path)) {
+    return 0;
+  }
+  try {
+    const size = statSync(path).size;
+    if (size === 0) {
+      return 0;
+    }
+    const fd = openSync(path, "r");
+    let count = 0;
+    let previous = "";
+    try {
+      const buffer = Buffer.alloc(64_000);
+      let position = 0;
+      for (;;) {
+        const bytesRead = readSync(fd, buffer, 0, buffer.length, position);
+        if (bytesRead === 0) {
+          break;
+        }
+        const text = previous + buffer.subarray(0, bytesRead).toString("utf8");
+        const lines = text.split(/\r?\n/u);
+        previous = lines.pop() ?? "";
+        count += lines.filter((line) => line.trim().length > 0).length;
+        position += bytesRead;
+      }
+      if (previous.trim().length > 0) {
+        count += 1;
+      }
+    } finally {
+      closeSync(fd);
+    }
+    return count;
+  } catch {
+    return 0;
+  }
+}
+
+function estimatedDeltaOverhead(operationCount: number, queueSizeBytes: number): "low" | "medium" | "high" {
+  if (operationCount > 50_000 || queueSizeBytes > 20_000_000) {
+    return "high";
+  }
+  if (operationCount > 5_000 || queueSizeBytes > 2_000_000) {
+    return "medium";
+  }
+  return "low";
+}
+
 function semanticOpenQuestions(
   entity: DeltaTimelineEntityRef | undefined,
   currentState: Record<string, unknown>,
@@ -2610,6 +2809,12 @@ function scoreWorkSessionCandidate(
 ): { score: number; signals: DeltaWorkSessionSignal[] } {
   const signals: DeltaWorkSessionSignal[] = [];
   const metadata = candidate.metadata;
+  if (isObservationOnlyContext(context) && !isObservationOnlyWorkSession(metadata)) {
+    return {
+      score: 0.15,
+      signals: [{ signal: "observation-only", weight: 0.15, value: context.commands[0] }],
+    };
+  }
   addSignalIfOverlap(signals, "sameTraceId", 0.4, context.traces, metadata.traces);
   addSignalIfOverlap(signals, "sameManifestService", 0.35, context.services, metadata.services);
   addSignalIfOverlap(signals, "sameRuntimeEntry", 0.3, context.entries, metadata.entries);
@@ -2752,6 +2957,9 @@ function normalizeWorkSessionMetadata(value: Record<string, unknown>): DeltaWork
 }
 
 function inferWorkSessionTitle(context: DeltaOperationContext, metadata: DeltaWorkSessionMetadata): string {
+  if (isObservationOnlyWorkSession(metadata)) {
+    return "Observe project context";
+  }
   if (context.kind === "manifest.imported" && metadata.services[0]) {
     return `Import ${metadata.services[0]} external service`;
   }
@@ -2780,6 +2988,9 @@ function inferWorkSessionTitle(context: DeltaOperationContext, metadata: DeltaWo
 }
 
 function inferIntent(context: DeltaOperationContext, metadata: DeltaWorkSessionMetadata): string {
+  if (isObservationOnlyWorkSession(metadata)) {
+    return "context-gathering";
+  }
   if (context.kind === "manifest.imported" || metadata.fileClusters.includes("manifest.change")) {
     return "external-runtime-import";
   }
@@ -2800,6 +3011,9 @@ function inferIntent(context: DeltaOperationContext, metadata: DeltaWorkSessionM
 
 function summarizeWorkSession(metadata: DeltaWorkSessionMetadata): string {
   const parts: string[] = [];
+  if (isObservationOnlyWorkSession(metadata)) {
+    return `Observed project context with ${metadata.commands.slice(0, 3).join(", ")}.`;
+  }
   if (metadata.services[0]) {
     parts.push(`worked on ${metadata.services[0]}`);
   }
@@ -2819,6 +3033,9 @@ function summarizeWorkSession(metadata: DeltaWorkSessionMetadata): string {
 }
 
 function initialWorkSessionConfidence(context: DeltaOperationContext): number {
+  if (isObservationOnlyContext(context)) {
+    return 0.36;
+  }
   if (context.kind === "manifest.imported") {
     return 0.78;
   }
@@ -2844,6 +3061,65 @@ function isDiagnosticRepairChain(context: DeltaOperationContext, metadata: Delta
   );
 }
 
+const OBSERVATION_COMMAND_PREFIXES = [
+  "agent context",
+  "agent print-context",
+  "agent timeline",
+  "cair query",
+  "cair snapshot",
+  "changed",
+  "delta status",
+  "doctor",
+  "explain",
+  "handoff",
+  "inspect",
+  "live status",
+  "status",
+  "timeline",
+];
+
+function isObservationOnlyContext(context: DeltaOperationContext): boolean {
+  return (
+    context.commands.length > 0 &&
+    context.files.length === 0 &&
+    context.entries.length === 0 &&
+    context.diagnostics.length === 0 &&
+    context.proofs.length === 0 &&
+    context.services.length === 0 &&
+    context.traces.length === 0 &&
+    context.commands.every(isObservationCommand)
+  );
+}
+
+function isObservationOnlyWorkSession(metadata: DeltaWorkSessionMetadata): boolean {
+  return (
+    metadata.commands.length > 0 &&
+    metadata.files.length === 0 &&
+    metadata.entries.length === 0 &&
+    metadata.diagnostics.length === 0 &&
+    metadata.proofs.length === 0 &&
+    metadata.services.length === 0 &&
+    metadata.traces.length === 0 &&
+    metadata.commands.every(isObservationCommand)
+  );
+}
+
+function isObservationCommand(command: string): boolean {
+  const normalized = normalizeForgeCommand(command);
+  return OBSERVATION_COMMAND_PREFIXES.some((prefix) => normalized === prefix || normalized.startsWith(`${prefix} `));
+}
+
+function normalizeForgeCommand(command: string): string {
+  return command
+    .trim()
+    .replace(/^node\s+(?:\.\/)?bin\/forge\.mjs(?:\s+|$)/u, "")
+    .replace(/^bun\s+run\s+forge(?:\s+|$)/u, "")
+    .replace(/^npm\s+run\s+forge\s+--(?:\s+|$)/u, "")
+    .replace(/^forge(?:\s+|$)/u, "")
+    .replace(/\s+/gu, " ")
+    .trim();
+}
+
 function hasAnyOverlap(...groups: string[][]): boolean {
   for (let index = 0; index < groups.length; index += 2) {
     if (intersects(groups[index] ?? [], groups[index + 1] ?? [])) {

package/src/forge/delta/timeline.ts

@@ -5,7 +5,16 @@ export interface DeltaTimelineResult {
   session?: string;
   target?: string;
   rebuilt?: boolean;
+  causal?: boolean;
+  staleProofs?: boolean;
   timeline: DeltaSemanticTimelineResult;
+  summary: {
+    events: number;
+    causalEdges: number;
+    proofStatus?: string;
+    staleProofs: Array<{ proof: string; lastRunAt?: string; lastRelevantChangeAt?: string }>;
+    causalChains: Array<{ kind: string; from: string; to: string; confidence: number; reason?: Record<string, unknown> }>;
+  };
   exitCode: 0;
 }
 
@@ -16,18 +25,24 @@ export async function runDeltaTimeline(input: {
   session?: string;
   limit?: number;
   rebuild?: boolean;
+  causal?: boolean;
+  staleProofs?: boolean;
 }): Promise<DeltaTimelineResult> {
   const store = await DeltaStore.open(input.workspaceRoot, { access: input.rebuild ? "write" : "read" });
   try {
     if (input.rebuild) {
       await store.rebuildSemanticTimeline();
     }
+    const timeline = await store.semanticTimeline({ target: input.target, kind: input.kind, workSessionId: input.session, limit: input.limit });
     return {
       ok: true,
       session: input.session,
       target: input.target,
       rebuilt: input.rebuild || undefined,
-      timeline: await store.semanticTimeline({ target: input.target, kind: input.kind, workSessionId: input.session, limit: input.limit }),
+      causal: input.causal || undefined,
+      staleProofs: input.staleProofs || undefined,
+      timeline,
+      summary: summarizeTimeline(timeline),
       exitCode: 0,
     };
   } finally {
@@ -35,6 +50,55 @@ export async function runDeltaTimeline(input: {
   }
 }
 
+function summarizeTimeline(timeline: DeltaSemanticTimelineResult): DeltaTimelineResult["summary"] {
+  const eventById = new Map(timeline.events.map((event) => [event.id, event]));
+  const proofStatus = typeof timeline.currentState.proofStatus === "string" ? timeline.currentState.proofStatus : undefined;
+  const rawProofEntities = uniqueStrings(
+    timeline.events.flatMap((event) =>
+      event.entities
+        .filter((entity) => entity.kind === "proof")
+        .map((entity) => entity.name)
+    ),
+  );
+  const proofEntities = timeline.entity?.kind === "proof"
+    ? [timeline.entity.name]
+    : rawProofEntities.filter((proof) => !/^forge\s/u.test(proof));
+  const lastProofRun = latestTimestamp(timeline.events.filter((event) => event.kind === "proof.passed" || event.kind === "proof.failed"));
+  const lastRelevantChange = latestTimestamp(timeline.events.filter((event) =>
+    event.kind === "modified" ||
+    event.kind === "policy.changed" ||
+    event.kind === "generated" ||
+    event.kind === "imported"
+  ));
+  return {
+    events: timeline.events.length,
+    causalEdges: timeline.causalEdges.length,
+    ...(proofStatus ? { proofStatus } : {}),
+    staleProofs: proofStatus === "stale"
+      ? (proofEntities.length > 0 ? proofEntities : ["unknown"]).map((proof) => ({
+        proof,
+        ...(lastProofRun ? { lastRunAt: lastProofRun } : {}),
+        ...(lastRelevantChange ? { lastRelevantChangeAt: lastRelevantChange } : {}),
+      }))
+      : [],
+    causalChains: timeline.causalEdges.slice(0, 12).map((edge) => ({
+      kind: edge.kind,
+      from: eventById.get(edge.from)?.title ?? edge.from,
+      to: eventById.get(edge.to)?.title ?? edge.to,
+      confidence: edge.confidence,
+      ...(edge.reason ? { reason: edge.reason } : {}),
+    })),
+  };
+}
+
+function latestTimestamp(events: DeltaSemanticTimelineResult["events"]): string | undefined {
+  return [...events].sort((left, right) => right.timestamp.localeCompare(left.timestamp))[0]?.timestamp;
+}
+
+function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values)].sort();
+}
+
 export function formatDeltaTimelineHuman(result: DeltaTimelineResult): string {
   const timeline = result.timeline;
   if (timeline.events.length === 0) {
@@ -76,6 +140,16 @@ export function formatDeltaTimelineHuman(result: DeltaTimelineResult): string {
     }
     lines.push("");
   }
+  if (result.summary.proofStatus || result.summary.staleProofs.length > 0) {
+    lines.push("Proof status");
+    if (result.summary.proofStatus) {
+      lines.push(`  status: ${result.summary.proofStatus}`);
+    }
+    for (const proof of result.summary.staleProofs) {
+      lines.push(`  stale: ${proof.proof}${proof.lastRelevantChangeAt ? ` after ${proof.lastRelevantChangeAt}` : ""}`);
+    }
+    lines.push("");
+  }
   if (timeline.causalEdges.length > 0) {
     lines.push("Causality");
     for (const edge of timeline.causalEdges.slice(0, 8)) {

package/src/forge/version.ts

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

package/templates/nuxt-web/.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+  "files.exclude": {
+    "**/.forge": true,
+    "**/node_modules": true,
+    "**/src/forge/_generated": true,
+    "**/forge.lock": true
+  },
+  "search.exclude": {
+    "**/.forge": true,
+    "**/node_modules": true,
+    "**/src/forge/_generated": true,
+    "**/forge.lock": true
+  }
+}

package/templates/nuxt-web/README.md

@@ -0,0 +1,30 @@
+# __FORGE_APP_TITLE__
+
+Nuxt + ForgeOS notes app.
+
+Run the full-stack loop:
+
+```bash
+__PACKAGE_MANAGER__ install
+__PACKAGE_MANAGER__ run generate
+__PACKAGE_MANAGER__ run dev
+```
+
+`forge dev` starts both the Forge runtime API and the Nuxt web UI.
+
+For agent/CI diagnostics:
+
+```bash
+__PACKAGE_MANAGER__ run forge -- dev --once --json
+```
+
+Generated files and local runtime state are gitignored and hidden from editor search by default. Recreate them with `forge generate`.
+
+The Nuxt app reads the Forge API URL from `runtimeConfig.public.forgeUrl`, overrideable with `NUXT_PUBLIC_FORGE_URL`.
+
+The web app includes:
+
+- `web/plugins/forge.client.ts` and `web/plugins/forge.server.ts` for hydration-safe Forge Vue plugin setup.
+- `web/composables/forge.ts` as the generated-client bridge.
+- `web/composables/useNotes.ts` as a domain composable using `useForgeCommand` and `useForgeLiveQuery`.
+- `web/server/api/forge-health.get.ts` as a minimal Nitro route that reads Nuxt runtime config.

package/templates/nuxt-web/forge.config.ts

@@ -0,0 +1,3 @@
+export default {
+  sourceRoots: ["src"],
+};

package/templates/nuxt-web/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "__FORGE_APP_NAME__",
+  "private": true,
+  "type": "module",
+  "workspaces": [
+    "web"
+  ],
+  "packageManager": "__PACKAGE_MANAGER_SPEC__",
+  "scripts": {
+    "forge": "forge",
+    "generate": "forge generate",
+    "check": "forge check",
+    "verify": "forge verify --smoke",
+    "dev": "forge dev",
+    "dev:api": "forge dev --api-only",
+    "dev:web": "cd web && __PACKAGE_MANAGER__ run dev",
+    "typecheck": "tsc --noEmit && cd web && __PACKAGE_MANAGER__ run typecheck"
+  },
+  "dependencies": {
+    "@electric-sql/pglite": "^0.2.17",
+    "forge": "__FORGE_PACKAGE_SPEC__"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.7.3"
+  },
+  "forge": {
+    "template": "nuxt-web",
+    "sourceRoots": [
+      "src"
+    ]
+  }
+}

package/templates/nuxt-web/src/actions/logNoteCreated.ts

@@ -0,0 +1,11 @@
+import { action } from "forge/server";
+
+export const logNoteCreated = action({
+  event: "note.created",
+  handler: async (_ctx, event) => {
+    return {
+      ok: true,
+      event,
+    };
+  },
+});

package/templates/nuxt-web/src/commands/createNote.ts

@@ -0,0 +1,26 @@
+import { can, command } from "forge/server";
+
+export const createNote = command({
+  auth: can("notes.create"),
+  handler: async (ctx, args) => {
+    const input = args as { title?: unknown; body?: unknown };
+    const title = typeof input.title === "string" ? input.title.trim() : "";
+    if (!title) {
+      throw new Error("title is required");
+    }
+
+    const note = await ctx.db.notes.insert({
+      title,
+      body: typeof input.body === "string" ? input.body : "",
+      status: "open",
+      createdAt: new Date().toISOString(),
+    });
+
+    await ctx.emit("note.created", {
+      id: note.id,
+      title: note.title,
+    });
+
+    return note;
+  },
+});

package/templates/nuxt-web/src/forge/schema.ts

@@ -0,0 +1,12 @@
+import { defineTable } from "forge/server";
+
+export const notes = defineTable({
+  name: "notes",
+  fields: {
+    id: "uuid",
+    title: "text",
+    body: "text",
+    status: "text",
+    createdAt: "timestamp",
+  },
+});

package/templates/nuxt-web/src/policies.ts

@@ -0,0 +1,6 @@
+import { canRole, definePolicies } from "forge/policy";
+
+export const policies = definePolicies({
+  "notes.read": canRole("owner", "admin", "member"),
+  "notes.create": canRole("owner", "admin", "member"),
+});

package/templates/nuxt-web/src/queries/listNotes.ts

@@ -0,0 +1,8 @@
+import { can, query } from "forge/server";
+
+export const listNotes = query({
+  auth: can("notes.read"),
+  handler: async (ctx) => {
+    return ctx.db.notes.all();
+  },
+});