gorsee 0.2.14 → 0.2.15

package/README.md

@@ -20,6 +20,7 @@ Read the strategic docs:
 - [Application Modes](./docs/APPLICATION_MODES.md)
 - [Security Model](./docs/SECURITY_MODEL.md)
 - [Top-Tier Roadmap](./docs/TOP_TIER_ROADMAP.md)
+- [Top-Tier Competition Plan](./docs/TOP_TIER_COMPETITION_PLAN.md)
 - [Canonical Language Plan](./docs/CANONICAL_LANGUAGE_PLAN.md)
 - [Canonical Recipes](./docs/CANONICAL_RECIPES.md)
 - [Canonical Examples](./examples/README.md)
@@ -47,6 +48,8 @@ Read the strategic docs:
 - [Runtime Triage](./docs/RUNTIME_TRIAGE.md)
 - [Starter Failures](./docs/STARTER_FAILURES.md)
 - [AI Workflows](./docs/AI_WORKFLOWS.md)
+- [AI Artifact Contract](./docs/AI_ARTIFACT_CONTRACT.md)
+- [CLI Contract](./docs/CLI_CONTRACT.json)
 - [AI IDE Sync Workflow](./docs/AI_IDE_SYNC_WORKFLOW.md)
 - [AI MCP Workflow](./docs/AI_MCP_WORKFLOW.md)
 - [AI Bridge Workflow](./docs/AI_BRIDGE_WORKFLOW.md)
@@ -314,6 +317,7 @@ npm create gorsee@latest my-app
 | `gorsee build` | Build client and server output |
 | `gorsee start` | Start production runtime |
 | `gorsee start --runtime node` | Start the built Node production runtime entry |
+| `gorsee worker` | Run the canonical server-mode worker/service runtime entry |
 | `gorsee check [--rewrite-imports] [--rewrite-loaders]` | Type, structure, TSX contract, and safety audit, with optional canonical autofix |
 | `gorsee routes` | Show route table |
 | `gorsee generate <entity>` | Generate CRUD scaffold with typed routes, validated forms, and inferred `memory|sqlite|postgres` data mode |
@@ -322,7 +326,8 @@ npm create gorsee@latest my-app
 | `gorsee typegen` | Generate typed routes |
 | `gorsee migrate` | Run database migrations |
 | `gorsee deploy` | Generate deploy config for supported targets, with `--runtime bun|node` on process-based adapters |
-| `gorsee ai` | AI diagnostics, bridge, IDE sync, export, and MCP tooling |
+| `gorsee test` | Run the framework-aware test command surface |
+| `gorsee ai` | AI bootstrap, diagnostics, checkpoints, context export, bridge, IDE sync, and MCP tooling |
 
 Runtime debugging surface:
 
@@ -335,6 +340,13 @@ Migration ergonomics:
 - `gorsee upgrade` is the canonical end-to-end upgrade flow for installed apps.
 - `gorsee upgrade --check --report docs/upgrade-report.json` is the dry-run migration audit flow when you want review before installation.
 
+AI bootstrap and handoff:
+
+- `gorsee ai init` scaffolds `.gorsee/rules.md`, `GORSEE.md`, and `.gorsee/agent/checkpoints` for repositories that enable AI workflows.
+- `gorsee ai checkpoint --mode inspect|propose|apply|operate` records explicit operator checkpoints for mutating and non-mutating sessions.
+- `gorsee ai pack` writes the latest grounded handoff bundle to `.gorsee/agent/latest.{json,md}` plus deploy/release/incident briefs.
+- `gorsee ai framework --format markdown` remains the canonical cold-start packet for agents and operators.
+
 ## Product Standards
 
 - Production behavior must remain deterministic across dev and prod.

package/dist-pkg/ai/bundle.d.ts

@@ -1,6 +1,7 @@
 import type { AIDiagnostic, AIEvent } from "./index.js";
 import type { AIStorePaths, AIHealthReport } from "./store.js";
 import { type AIContextPacket } from "./summary.js";
+import { type AIOperationMode } from "./rules.js";
 export interface AIContextSnippet {
     file: string;
     startLine: number;
@@ -43,5 +44,6 @@ export declare function buildAIContextBundle(cwd: string, paths: AIStorePaths, o
     limit?: number;
     snippetRadius?: number;
     maxSnippets?: number;
+    mode?: AIOperationMode;
 }): Promise<AIContextBundle>;
 export declare function renderAIContextBundleMarkdown(bundle: AIContextBundle): string;

package/dist-pkg/ai/bundle.js

@@ -3,8 +3,12 @@ import { join, isAbsolute } from "node:path";
 import { buildAIHealthReport, readAIDiagnosticsSnapshot, readAIEvents, readReactiveTraceArtifact } from "./store.js";
 import { createAIContextPacket, renderAIContextMarkdown } from "./summary.js";
 import { GORSEE_AI_CONTEXT_SCHEMA_VERSION } from "./contracts.js";
+import { resolveAIRulesFile } from "./rules.js";
 export async function buildAIContextBundle(cwd, paths, options = {}) {
-  const events = await readAIEvents(paths.eventsPath, { limit: options.limit ?? 200 }), diagnostics = await readAIDiagnosticsSnapshot(paths.diagnosticsPath), reactiveTrace = await readReactiveTraceArtifact(paths.reactiveTracePath), report = await buildAIHealthReport(paths, { limit: options.limit ?? 200 }), packet = createAIContextPacket(report, events, diagnostics?.latest, reactiveTrace), rootCauses = buildRootCauseRanking(report, diagnostics?.latest, events), snippets = await collectSnippets(cwd, diagnostics?.latest, report, events, rootCauses, {
+  const events = await readAIEvents(paths.eventsPath, { limit: options.limit ?? 200 }), diagnostics = await readAIDiagnosticsSnapshot(paths.diagnosticsPath), reactiveTrace = await readReactiveTraceArtifact(paths.reactiveTracePath), report = await buildAIHealthReport(paths, { limit: options.limit ?? 200 }), rules = await resolveAIRulesFile(cwd), packet = createAIContextPacket(report, events, diagnostics?.latest, reactiveTrace, {
+    currentMode: options.mode ?? "inspect",
+    rules
+  }), rootCauses = buildRootCauseRanking(report, diagnostics?.latest, events), snippets = await collectSnippets(cwd, diagnostics?.latest, report, events, rootCauses, {
     snippetRadius: options.snippetRadius ?? 6,
     maxSnippets: options.maxSnippets ?? 5
   });

package/dist-pkg/ai/checkpoint.d.ts

@@ -0,0 +1,33 @@
+import { type AIContextBundle } from "./bundle.js";
+import type { AIStorePaths } from "./store.js";
+import { type AIOperationMode, type AITransportContract } from "./rules.js";
+export interface AICheckpointMetadata {
+    schemaVersion: string;
+    createdAt: string;
+    name: string;
+    slug: string;
+    mode: AIOperationMode;
+    bundleJsonPath: string;
+    bundleMarkdownPath: string;
+    rulesPath?: string;
+    transport: AITransportContract;
+}
+export interface AICheckpointPaths {
+    checkpointsDir: string;
+    bundleJsonPath: string;
+    bundleMarkdownPath: string;
+    metadataPath: string;
+    latestPointerPath: string;
+}
+export declare function slugifyCheckpointName(input: string): string;
+export declare function resolveAICheckpointPaths(cwd: string, name: string): AICheckpointPaths;
+export declare function writeAICheckpoint(cwd: string, storePaths: AIStorePaths, options: {
+    name?: string;
+    mode: AIOperationMode;
+    limit?: number;
+    maxSnippets?: number;
+}): Promise<{
+    bundle: AIContextBundle;
+    metadata: AICheckpointMetadata;
+    paths: AICheckpointPaths;
+}>;

package/dist-pkg/ai/checkpoint.js

@@ -0,0 +1,50 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { buildAIContextBundle, renderAIContextBundleMarkdown } from "./bundle.js";
+import { GORSEE_AI_CONTEXT_SCHEMA_VERSION } from "./contracts.js";
+import { resolveAISessionPackPaths } from "./session-pack.js";
+import {
+  AI_TRANSPORT_CONTRACT,
+  resolveAIRulesFile
+} from "./rules.js";
+export function slugifyCheckpointName(input) {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "checkpoint";
+}
+export function resolveAICheckpointPaths(cwd, name) {
+  const sessionPackPaths = resolveAISessionPackPaths(cwd), checkpointsDir = join(sessionPackPaths.outDir, "checkpoints"), slug = slugifyCheckpointName(name);
+  return {
+    checkpointsDir,
+    bundleJsonPath: join(checkpointsDir, `${slug}.json`),
+    bundleMarkdownPath: join(checkpointsDir, `${slug}.md`),
+    metadataPath: join(checkpointsDir, `${slug}.meta.json`),
+    latestPointerPath: join(checkpointsDir, "latest.json")
+  };
+}
+export async function writeAICheckpoint(cwd, storePaths, options) {
+  const createdAt = new Date().toISOString(), name = options.name?.trim().length ? options.name.trim() : createdAt.replace(/[:.]/g, "-"), paths = resolveAICheckpointPaths(cwd, name), bundle = await buildAIContextBundle(cwd, storePaths, {
+    limit: options.limit,
+    maxSnippets: options.maxSnippets
+  }), rules = await resolveAIRulesFile(cwd);
+  await mkdir(paths.checkpointsDir, { recursive: !0 });
+  const metadata = {
+    schemaVersion: GORSEE_AI_CONTEXT_SCHEMA_VERSION,
+    createdAt,
+    name,
+    slug: slugifyCheckpointName(name),
+    mode: options.mode,
+    bundleJsonPath: paths.bundleJsonPath,
+    bundleMarkdownPath: paths.bundleMarkdownPath,
+    rulesPath: rules?.path,
+    transport: AI_TRANSPORT_CONTRACT
+  }, markdown = [
+    `<!-- gorsee-ai-schema: ${GORSEE_AI_CONTEXT_SCHEMA_VERSION} -->`,
+    `<!-- gorsee-ai-mode: ${options.mode} -->`,
+    renderAIContextBundleMarkdown(bundle)
+  ].join(`
+`);
+  await writeFile(paths.bundleJsonPath, JSON.stringify(bundle, null, 2), "utf-8");
+  await writeFile(paths.bundleMarkdownPath, markdown, "utf-8");
+  await writeFile(paths.metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
+  await writeFile(paths.latestPointerPath, JSON.stringify(metadata, null, 2), "utf-8");
+  return { bundle, metadata, paths };
+}

package/dist-pkg/ai/framework-context.d.ts

@@ -1,4 +1,5 @@
 import { type AppMode } from "../runtime/app-config.js";
+import { type AIOperationModeDefinition, type AITransportContract } from "./rules.js";
 export interface AIFrameworkDocRef {
     path: string;
     purpose: string;
@@ -32,6 +33,12 @@ export interface AIFrameworkPacket {
         command: string;
         purpose: string;
     }>;
+    operationModes: AIOperationModeDefinition[];
+    transport: AITransportContract;
+    rules?: {
+        path: string;
+        content: string;
+    };
     docs: {
         local: AIFrameworkDocRef[];
         canonical: AIFrameworkDocRef[];

package/dist-pkg/ai/framework-context.js

@@ -2,6 +2,11 @@ import { access, readFile } from "node:fs/promises";
 import { basename, join, relative } from "node:path";
 import { generateFrameworkMD } from "../cli/framework-md.js";
 import { loadAppConfig, resolveAppMode } from "../runtime/app-config.js";
+import {
+  AI_OPERATION_MODES,
+  AI_TRANSPORT_CONTRACT,
+  resolveAIRulesFile
+} from "./rules.js";
 const LOCAL_DOCS = [
   { path: "AGENTS.md", purpose: "\u041F\u0440\u043E\u0435\u043A\u0442\u043D\u044B\u0439 operating contract \u0434\u043B\u044F \u0430\u0433\u0435\u043D\u0442\u043E\u0432" },
   { path: "FRAMEWORK.md", purpose: "AI-friendly reference \u0434\u043B\u044F \u0442\u0435\u043A\u0443\u0449\u0435\u0433\u043E \u043F\u0440\u0438\u043B\u043E\u0436\u0435\u043D\u0438\u044F" },
@@ -10,21 +15,32 @@ const LOCAL_DOCS = [
   { path: "docs/FRAMEWORK_DOCTRINE.md", purpose: "\u0410\u0440\u0445\u0438\u0442\u0435\u043A\u0442\u0443\u0440\u043D\u0430\u044F \u0434\u043E\u043A\u0442\u0440\u0438\u043D\u0430 \u0438 \u0438\u043D\u0432\u0430\u0440\u0438\u0430\u043D\u0442\u044B" },
   { path: "docs/APPLICATION_MODES.md", purpose: "\u041A\u0430\u043D\u043E\u043D\u0438\u0447\u0435\u0441\u043A\u0438\u0435 \u0440\u0435\u0436\u0438\u043C\u044B frontend/fullstack/server \u0438 \u0433\u0440\u0430\u043D\u0438\u0446\u044B \u043C\u0435\u0436\u0434\u0443 \u043D\u0438\u043C\u0438" },
   { path: "docs/API_STABILITY.md", purpose: "\u0421\u0442\u0430\u0431\u0438\u043B\u044C\u043D\u044B\u0435 \u043F\u0443\u0431\u043B\u0438\u0447\u043D\u044B\u0435 entrypoints \u0438 migration semantics" },
+  { path: "docs/PUBLIC_SURFACE_MAP.md", purpose: "\u041A\u0430\u043D\u043E\u043D\u0438\u0447\u0435\u0441\u043A\u0430\u044F import map \u0438 bounded public surfaces" },
+  { path: "docs/CLI_CONTRACT.json", purpose: "Machine-readable CLI command matrix \u0438 AI subcommand surface" },
   { path: "docs/SECURITY_MODEL.md", purpose: "Runtime/security guarantees \u0438 fail-closed \u043C\u043E\u0434\u0435\u043B\u044C" },
   { path: "docs/AI_WORKFLOWS.md", purpose: "\u041A\u0430\u043D\u043E\u043D\u0438\u0447\u0435\u0441\u043A\u0438\u0439 human+agent workflow" },
   { path: "docs/AI_SURFACE_STABILITY.md", purpose: "\u0421\u0442\u0430\u0431\u0438\u043B\u044C\u043D\u043E\u0441\u0442\u044C AI-facing surface" },
+  { path: "docs/AI_ARTIFACT_CONTRACT.md", purpose: "Versioned AI artifacts, checkpoints, and handoff expectations" },
   { path: "docs/AI_SESSION_PACKS.md", purpose: "Cross-session handoff \u0434\u043B\u044F \u0430\u0433\u0435\u043D\u0442\u043E\u0432" },
+  { path: "docs/REACTIVE_RUNTIME.md", purpose: "\u0420\u0435\u0430\u043A\u0442\u0438\u0432\u043D\u0430\u044F \u043C\u043E\u0434\u0435\u043B\u044C, diagnostics, resources, mutations, islands" },
+  { path: "docs/SUPPORT_MATRIX.md", purpose: "\u041F\u043E\u0434\u0434\u0435\u0440\u0436\u0438\u0432\u0430\u0435\u043C\u044B\u0435 runtime targets, CLI surfaces, and CI-validated contract" },
+  { path: "docs/DEPLOY_TARGET_GUIDE.md", purpose: "Mode-aware deploy target guidance \u0438 runtime profiles" },
   { path: "docs/STARTER_ONBOARDING.md", purpose: "\u0421\u0442\u0430\u0440\u0442\u043E\u0432\u044B\u0435 app-\u043A\u043B\u0430\u0441\u0441\u044B \u0438 onboarding path" },
   { path: "docs/MIGRATION_GUIDE.md", purpose: "\u041F\u0435\u0440\u0435\u0445\u043E\u0434 \u0441 compatibility imports \u043D\u0430 canonical surfaces" },
   { path: "docs/RUNTIME_TRIAGE.md", purpose: "\u0422\u0440\u0438\u0430\u0436 runtime/regression \u043F\u0440\u043E\u0431\u043B\u0435\u043C" },
   { path: "docs/STARTER_FAILURES.md", purpose: "\u0427\u0430\u0441\u0442\u044B\u0435 \u043E\u0448\u0438\u0431\u043A\u0438 \u0443\u0441\u0442\u0430\u043D\u043E\u0432\u043A\u0438 \u0438 scaffold" }
 ], AI_COMMANDS = [
+  { command: "gorsee ai init", purpose: "Bootstrap local AI rules, operator guide, and checkpoint directory" },
   { command: "gorsee ai framework --format markdown", purpose: "\u041A\u0430\u043D\u043E\u043D\u0438\u0447\u0435\u0441\u043A\u0438\u0439 cold-start packet \u043F\u043E \u0444\u0440\u0435\u0439\u043C\u0432\u043E\u0440\u043A\u0443" },
+  { command: "gorsee ai tail --limit 20", purpose: "\u041F\u0440\u043E\u0441\u043C\u043E\u0442\u0440 \u043F\u043E\u0441\u043B\u0435\u0434\u043D\u0438\u0445 structured AI events" },
+  { command: "gorsee ai replay", purpose: "\u0412\u043E\u0441\u0441\u0442\u0430\u043D\u043E\u0432\u043B\u0435\u043D\u0438\u0435 \u043A\u043E\u0440\u0440\u0435\u043B\u0438\u0440\u043E\u0432\u0430\u043D\u043D\u043E\u0433\u043E AI/runtime event timeline" },
+  { command: "gorsee ai doctor", purpose: "\u0421\u0432\u043E\u0434\u043A\u0430 diagnostics/incidents/artifact regressions" },
   { command: "gorsee ai export --format markdown", purpose: "\u041A\u043E\u043C\u043F\u0430\u043A\u0442\u043D\u044B\u0439 packet \u043F\u043E \u0442\u0435\u043A\u0443\u0449\u0435\u043C\u0443 AI/runtime \u0441\u043E\u0441\u0442\u043E\u044F\u043D\u0438\u044E" },
   { command: "gorsee ai export --bundle --format markdown", purpose: "Runtime packet \u0441 \u0440\u0430\u043D\u0436\u0438\u0440\u043E\u0432\u0430\u043D\u043D\u044B\u043C\u0438 code snippets" },
-  { command: "gorsee ai doctor", purpose: "\u0421\u0432\u043E\u0434\u043A\u0430 diagnostics/incidents/artifact regressions" },
   { command: "gorsee ai pack", purpose: "\u0417\u0430\u043F\u0438\u0441\u044C session pack \u0432 .gorsee/agent" },
+  { command: "gorsee ai checkpoint --mode inspect", purpose: "\u042F\u0432\u043D\u044B\u0439 checkpoint \u0442\u0435\u043A\u0443\u0449\u0435\u0433\u043E AI session state \u0441 metadata \u043F\u043E \u0440\u0435\u0436\u0438\u043C\u0443" },
   { command: "gorsee ai ide-sync", purpose: "IDE-friendly projection \u0444\u0430\u0439\u043B\u043E\u0432" },
+  { command: "gorsee ai bridge", purpose: "\u041B\u043E\u043A\u0430\u043B\u044C\u043D\u044B\u0439 ingest bridge \u0434\u043B\u044F trusted IDE/agent tooling" },
   { command: "gorsee ai mcp", purpose: "stdio MCP \u0441\u0435\u0440\u0432\u0435\u0440 \u043F\u043E\u0432\u0435\u0440\u0445 \u043B\u043E\u043A\u0430\u043B\u044C\u043D\u043E\u0433\u043E AI state" }
 ];
 async function pathExists(path) {
@@ -70,7 +86,7 @@ function renderDocLines(docs) {
   return docs.map((doc) => `- \`${doc.path}\` -- ${doc.purpose}`);
 }
 export async function buildAIFrameworkPacket(cwd) {
-  const projectName = await resolveProjectName(cwd), appMode = resolveAppMode(await loadAppConfig(cwd)), localDocs = await collectDocRefs(cwd, LOCAL_DOCS), canonicalDocs = await collectDocRefs(cwd, CANONICAL_DOCS), frameworkReferencePath = await pathExists(join(cwd, "FRAMEWORK.md")) ? relative(cwd, join(cwd, "FRAMEWORK.md")) || "FRAMEWORK.md" : void 0, frameworkReferenceMarkdown = frameworkReferencePath ? await readFile(join(cwd, frameworkReferencePath), "utf-8") : generateFrameworkMD(projectName);
+  const projectName = await resolveProjectName(cwd), appMode = resolveAppMode(await loadAppConfig(cwd)), localDocs = await collectDocRefs(cwd, LOCAL_DOCS), canonicalDocs = await collectDocRefs(cwd, CANONICAL_DOCS), frameworkReferencePath = await pathExists(join(cwd, "FRAMEWORK.md")) ? relative(cwd, join(cwd, "FRAMEWORK.md")) || "FRAMEWORK.md" : void 0, frameworkReferenceMarkdown = frameworkReferencePath ? await readFile(join(cwd, frameworkReferencePath), "utf-8") : generateFrameworkMD(projectName), rules = await resolveAIRulesFile(cwd);
   return {
     kind: "gorsee.framework",
     schemaVersion: 1,
@@ -88,7 +104,19 @@ export async function buildAIFrameworkPacket(cwd) {
       browser: "gorsee/client",
       server: "gorsee/server",
       compatibility: "gorsee and gorsee/compat are compatibility-only for new code",
-      scoped: ["gorsee/auth", "gorsee/db", "gorsee/security", "gorsee/log", "gorsee/forms", "gorsee/routes", "gorsee/ai"]
+      scoped: [
+        "gorsee/auth",
+        "gorsee/db",
+        "gorsee/security",
+        "gorsee/ai",
+        "gorsee/forms",
+        "gorsee/routes",
+        "gorsee/i18n",
+        "gorsee/content",
+        "gorsee/env",
+        "gorsee/log",
+        "gorsee/testing"
+      ]
     },
     routeGrammar: [
       "default export -> page UI",
@@ -104,6 +132,12 @@ export async function buildAIFrameworkPacket(cwd) {
       routeExample: "routes/users/[id].tsx -> /users/:id"
     },
     aiCommands: AI_COMMANDS,
+    operationModes: AI_OPERATION_MODES,
+    transport: AI_TRANSPORT_CONTRACT,
+    rules: rules ? {
+      path: rules.path,
+      content: rules.content
+    } : void 0,
     docs: {
       local: localDocs,
       canonical: canonicalDocs
@@ -111,9 +145,14 @@ export async function buildAIFrameworkPacket(cwd) {
     recommendedStart: [
       "Read AGENTS.md first when it exists.",
       "Read FRAMEWORK.md for the current app shape and syntax.",
+      "Read docs/PUBLIC_SURFACE_MAP.md for the canonical import map and scoped stable surfaces.",
+      "Read docs/SUPPORT_MATRIX.md when runtime, packaging, or deploy assumptions matter.",
+      "Prefer inspect/propose modes before apply/operate when the task is still ambiguous.",
       `Respect the current app.mode contract: ${appMode}.`,
       "Use gorsee/client for browser-safe code and gorsee/server for runtime/server boundaries.",
-      "Prefer scoped stable subpaths when auth, db, security, forms, routes, ai, or log is the primary concern.",
+      "Prefer scoped stable subpaths when auth, db, security, forms, routes, ai, i18n, content, env, log, or testing is the primary concern.",
+      "Keep model traffic provider-direct or self-hosted; treat the AI bridge as diagnostics transport, not as the production request path.",
+      "Use gorsee ai init when local AI workflows are enabled but the repository has no explicit local rules scaffold yet.",
       "Use gorsee ai export --bundle for incident/debug context, not for framework cold-start context."
     ],
     frameworkReferencePath,
@@ -159,6 +198,16 @@ export function renderAIFrameworkMarkdown(packet) {
     "",
     ...packet.aiCommands.map((entry) => `- \`${entry.command}\` -- ${entry.purpose}`),
     "",
+    "## AI Operation Modes",
+    "",
+    ...packet.operationModes.map((entry) => `- \`${entry.mode}\` -- ${entry.purpose}`),
+    "",
+    "## AI Transport Contract",
+    "",
+    `- Model traffic: ${packet.transport.modelTraffic}`,
+    `- Bridge role: ${packet.transport.bridgeRole}`,
+    `- Production role: ${packet.transport.productionRole}`,
+    "",
     "## Local Docs",
     "",
     ...packet.docs.local.length > 0 ? renderDocLines(packet.docs.local) : ["- No local AI/context docs detected in the current cwd."],
@@ -171,6 +220,14 @@ export function renderAIFrameworkMarkdown(packet) {
     "",
     packet.frameworkReferencePath ? `Source: \`${packet.frameworkReferencePath}\`` : "Source: generated built-in framework reference",
     "",
+    ...packet.rules ? [
+      "## AI Rules",
+      "",
+      `Source: \`${packet.rules.path}\``,
+      "",
+      packet.rules.content,
+      ""
+    ] : [],
     packet.frameworkReferenceMarkdown
   ].filter((line) => line !== void 0).join(`
 `);

package/dist-pkg/ai/ide.d.ts

@@ -1,5 +1,6 @@
 import { type AIContextPacket } from "./summary.js";
 import { type AIStorePaths } from "./store.js";
+import { type AIOperationMode } from "./rules.js";
 export interface IDEProjectionPaths {
     diagnosticsPath: string;
     eventsPath: string;
@@ -8,6 +9,7 @@ export interface IDEProjectionPaths {
 export interface IDEProjection {
     schemaVersion: string;
     updatedAt: string;
+    agent: AIContextPacket["agent"];
     app?: AIContextPacket["app"];
     diagnostics: Array<{
         code?: string;
@@ -34,5 +36,7 @@ export interface IDEProjection {
 export declare function resolveIDEProjectionPaths(cwd: string): IDEProjectionPaths;
 export declare function buildIDEProjection(storePaths: AIStorePaths, options?: {
     limit?: number;
+    cwd?: string;
+    mode?: AIOperationMode;
 }): Promise<IDEProjection>;
 export declare function writeIDEProjection(projectionPaths: IDEProjectionPaths, projection: IDEProjection): Promise<void>;

package/dist-pkg/ai/ide.js

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { createAIContextPacket, renderAIContextMarkdown } from "./summary.js";
 import { buildAIHealthReport, readAIDiagnosticsSnapshot, readAIEvents, readReactiveTraceArtifact } from "./store.js";
 import { GORSEE_AI_CONTEXT_SCHEMA_VERSION } from "./contracts.js";
+import { resolveAIRulesFile } from "./rules.js";
 export function resolveIDEProjectionPaths(cwd) {
   const base = join(cwd, ".gorsee", "ide");
   return {
@@ -12,10 +13,14 @@ export function resolveIDEProjectionPaths(cwd) {
   };
 }
 export async function buildIDEProjection(storePaths, options = {}) {
-  const events = await readAIEvents(storePaths.eventsPath, { limit: options.limit ?? 100 }), diagnosticsSnapshot = await readAIDiagnosticsSnapshot(storePaths.diagnosticsPath), reactiveTrace = await readReactiveTraceArtifact(storePaths.reactiveTracePath), report = await buildAIHealthReport(storePaths, { limit: options.limit ?? 200 }), context = createAIContextPacket(report, events, diagnosticsSnapshot?.latest, reactiveTrace);
+  const events = await readAIEvents(storePaths.eventsPath, { limit: options.limit ?? 100 }), diagnosticsSnapshot = await readAIDiagnosticsSnapshot(storePaths.diagnosticsPath), reactiveTrace = await readReactiveTraceArtifact(storePaths.reactiveTracePath), report = await buildAIHealthReport(storePaths, { limit: options.limit ?? 200 }), rules = options.cwd ? await resolveAIRulesFile(options.cwd) : void 0, context = createAIContextPacket(report, events, diagnosticsSnapshot?.latest, reactiveTrace, {
+    currentMode: options.mode ?? "inspect",
+    rules
+  });
   return {
     schemaVersion: GORSEE_AI_CONTEXT_SCHEMA_VERSION,
     updatedAt: new Date().toISOString(),
+    agent: context.agent,
     app: context.app,
     diagnostics: diagnosticsSnapshot?.latest ? [{
       code: diagnosticsSnapshot.latest.code,
@@ -45,12 +50,14 @@ export async function writeIDEProjection(projectionPaths, projection) {
   await writeFile(projectionPaths.diagnosticsPath, JSON.stringify({
     schemaVersion: projection.schemaVersion,
     updatedAt: projection.updatedAt,
+    agent: projection.agent,
     app: projection.app,
     diagnostics: projection.diagnostics
   }, null, 2), "utf-8");
   await writeFile(projectionPaths.eventsPath, JSON.stringify({
     schemaVersion: projection.schemaVersion,
     updatedAt: projection.updatedAt,
+    agent: projection.agent,
     app: projection.app,
     events: projection.recentEvents,
     artifactRegressions: projection.artifactRegressions

package/dist-pkg/ai/index.d.ts

@@ -1,5 +1,7 @@
 import { type AISessionPackConfig } from "./session-pack.js";
 export { GORSEE_AI_CONTEXT_SCHEMA_VERSION, } from "./contracts.js";
+export { AI_OPERATION_MODES, AI_TRANSPORT_CONTRACT, renderDefaultAIRulesMarkdown, renderDefaultAIGuideMarkdown, resolveAIRulesFile, type AIOperationMode, type AIOperationModeDefinition, type AIRulesFile, type AITransportContract, } from "./rules.js";
+export { resolveAICheckpointPaths, slugifyCheckpointName, writeAICheckpoint, type AICheckpointMetadata, type AICheckpointPaths, } from "./checkpoint.js";
 export { writeArtifactFailurePack, writeArtifactLifecycleEvent, writeArtifactSuccessPack, runArtifactLifecycleStep, type ArtifactLifecycleEventInput, } from "./artifact-lifecycle.js";
 export { createAIBridgeHandler, createAIBridgeServer, type AIBridgeHandler, type AIBridgeServer, type AIBridgeServerOptions, type AIBridgeSnapshot, } from "./bridge.js";
 export { buildAIHealthReport, readAIDiagnosticsSnapshot, readReactiveTraceArtifact, readAIEvents, resolveAIStorePaths, type AIHealthReport, type AIStorePaths, } from "./store.js";

package/dist-pkg/ai/index.js

@@ -8,6 +8,18 @@ import {
 export {
   GORSEE_AI_CONTEXT_SCHEMA_VERSION
 } from "./contracts.js";
+export {
+  AI_OPERATION_MODES,
+  AI_TRANSPORT_CONTRACT,
+  renderDefaultAIRulesMarkdown,
+  renderDefaultAIGuideMarkdown,
+  resolveAIRulesFile
+} from "./rules.js";
+export {
+  resolveAICheckpointPaths,
+  slugifyCheckpointName,
+  writeAICheckpoint
+} from "./checkpoint.js";
 export {
   writeArtifactFailurePack,
   writeArtifactLifecycleEvent,

package/dist-pkg/ai/rules.d.ts

@@ -0,0 +1,28 @@
+import type { AppMode } from "../runtime/app-config.js";
+export type AIOperationMode = "inspect" | "propose" | "apply" | "operate";
+export interface AIOperationModeDefinition {
+    mode: AIOperationMode;
+    purpose: string;
+    mutatesFiles: boolean;
+    mutatesRuntime: boolean;
+}
+export interface AIRulesFile {
+    path: string;
+    content: string;
+}
+export interface AITransportContract {
+    modelTraffic: "provider-direct-or-self-hosted";
+    bridgeRole: "diagnostics-and-ingestion-only";
+    productionRole: "must-not-sit-on-the-runtime-request-path";
+}
+export declare const AI_OPERATION_MODES: AIOperationModeDefinition[];
+export declare const AI_TRANSPORT_CONTRACT: AITransportContract;
+export declare function renderDefaultAIRulesMarkdown(input: {
+    projectName: string;
+    appMode: AppMode;
+}): string;
+export declare function renderDefaultAIGuideMarkdown(input: {
+    projectName: string;
+    appMode: AppMode;
+}): string;
+export declare function resolveAIRulesFile(cwd: string): Promise<AIRulesFile | undefined>;

package/dist-pkg/ai/rules.js

@@ -0,0 +1,118 @@
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+export const AI_OPERATION_MODES = [
+  {
+    mode: "inspect",
+    purpose: "Read code, diagnostics, and contracts without mutating files or runtime state.",
+    mutatesFiles: !1,
+    mutatesRuntime: !1
+  },
+  {
+    mode: "propose",
+    purpose: "Prepare change plans, patches, or remediation guidance without applying them.",
+    mutatesFiles: !1,
+    mutatesRuntime: !1
+  },
+  {
+    mode: "apply",
+    purpose: "Write code or config changes in the repository without operating long-running runtime surfaces.",
+    mutatesFiles: !0,
+    mutatesRuntime: !1
+  },
+  {
+    mode: "operate",
+    purpose: "Perform runtime-facing actions such as deploy, worker, bridge, or incident operations with explicit operator intent.",
+    mutatesFiles: !0,
+    mutatesRuntime: !0
+  }
+], AI_TRANSPORT_CONTRACT = {
+  modelTraffic: "provider-direct-or-self-hosted",
+  bridgeRole: "diagnostics-and-ingestion-only",
+  productionRole: "must-not-sit-on-the-runtime-request-path"
+};
+export function renderDefaultAIRulesMarkdown(input) {
+  return [
+    "# AI Rules",
+    "",
+    `Project: ${input.projectName}`,
+    `App Mode: ${input.appMode}`,
+    "",
+    "## Defaults",
+    "",
+    "- Start in `inspect` mode unless the task clearly requires mutation.",
+    "- Prefer `propose` before `apply` when requirements are still ambiguous.",
+    "- Use `operate` only for deploy, worker, bridge, incident, or other runtime-facing actions.",
+    "- Before `apply` or `operate`, write an explicit checkpoint with `gorsee ai checkpoint --mode <mode>`.",
+    "- Treat `gorsee/client` and `gorsee/server` boundaries as framework contracts, not convenience suggestions.",
+    "- Prefer scoped stable subpaths (`gorsee/auth`, `gorsee/forms`, `gorsee/routes`, etc.) when the concern is already domain-specific.",
+    "",
+    "## Safety",
+    "",
+    "- Keep model traffic provider-direct or self-hosted when integrating external models.",
+    "- Do not place AI bridge transport on the production request path.",
+    "- Prefer structured artifacts in `.gorsee/` over scraped logs.",
+    "- Run `gorsee check` after mutating AI workflows.",
+    "",
+    "## Local Notes",
+    "",
+    "- Record project-specific constraints here instead of repeating them in every prompt.",
+    "- Add product, security, deploy, or incident rules here when this repo develops stronger local requirements.",
+    ""
+  ].join(`
+`);
+}
+export function renderDefaultAIGuideMarkdown(input) {
+  return [
+    "# Gorsee AI Local Guide",
+    "",
+    `Project: ${input.projectName}`,
+    `App Mode: ${input.appMode}`,
+    "",
+    "This file is the local operator-facing AI guide for the repository.",
+    "",
+    "## Canonical Files",
+    "",
+    "- `.gorsee/rules.md` is the canonical local rules file consumed by Gorsee AI workflows.",
+    "- `AGENTS.md` remains the primary repository contract when present.",
+    "- `FRAMEWORK.md` remains the app/framework reference when present.",
+    "",
+    "## Recommended Workflow",
+    "",
+    "1. Run `gorsee ai framework --format markdown` for cold-start context.",
+    "2. Keep the session in `inspect` or `propose` until mutation is justified.",
+    "3. Before `apply` or `operate`, run `gorsee ai checkpoint --mode <mode>`.",
+    "4. Use `gorsee ai pack` for handoff and `gorsee ai doctor` for diagnostics-first triage.",
+    "5. Run `gorsee check` after mutating work.",
+    "",
+    "## Local Customization",
+    "",
+    "- Extend `.gorsee/rules.md` with repo-specific constraints.",
+    "- Add team-specific AI operating notes here only when they are broader than per-task instructions.",
+    ""
+  ].join(`
+`);
+}
+const RULES_CANDIDATES = [
+  ".gorsee/rules.md",
+  "GORSEE.md"
+];
+async function pathExists(path) {
+  try {
+    await access(path);
+    return !0;
+  } catch {
+    return !1;
+  }
+}
+export async function resolveAIRulesFile(cwd) {
+  for (const candidate of RULES_CANDIDATES) {
+    const absolutePath = join(cwd, candidate);
+    if (!await pathExists(absolutePath))
+      continue;
+    return {
+      path: candidate,
+      content: await readFile(absolutePath, "utf-8")
+    };
+  }
+  return;
+}

package/dist-pkg/ai/session-pack.d.ts

@@ -1,5 +1,6 @@
 import type { AIStorePaths } from "./store.js";
 import { type AIContextBundle } from "./bundle.js";
+import type { AIOperationMode } from "./rules.js";
 export interface AISessionPackConfig {
     enabled?: boolean;
     outDir?: string;
@@ -8,6 +9,7 @@ export interface AISessionPackConfig {
     limit?: number;
     maxSnippets?: number;
     formats?: Array<"json" | "markdown">;
+    mode?: AIOperationMode;
 }
 export interface AISessionPackPaths {
     outDir: string;

package/dist-pkg/ai/session-pack.js

@@ -45,7 +45,8 @@ export function resolveAISessionPackPaths(cwd, config) {
 export async function writeAISessionPack(cwd, storePaths, config) {
   const resolved = resolveAISessionPackConfig(cwd, { enabled: !0, ...config ?? {} }), paths = resolveAISessionPackPaths(cwd, resolved), bundle = await buildAIContextBundle(cwd, storePaths, {
     limit: resolved.limit,
-    maxSnippets: resolved.maxSnippets
+    maxSnippets: resolved.maxSnippets,
+    mode: resolved.mode
   });
   await mkdir(paths.historyDir, { recursive: !0 });
   const stamp = bundle.generatedAt.replace(/[:.]/g, "-"), deploySummary = createAIDeploySummary(bundle.packet), releaseBrief = createAIReleaseBrief(bundle.packet), incidentBrief = createAIIncidentBrief(bundle.packet), incidentSnapshot = createAIIncidentSnapshot(bundle.packet), json = JSON.stringify(bundle, null, 2), markdown = [

package/dist-pkg/ai/summary.d.ts

@@ -1,9 +1,28 @@
 import type { AIDiagnostic, AIEvent } from "./index.js";
 import type { AIHealthReport } from "./store.js";
 import type { ReactiveTraceArtifact } from "../reactive/diagnostics.js";
+import { type AIOperationMode, type AIRulesFile } from "./rules.js";
 export interface AIContextPacket {
     schemaVersion: string;
     generatedAt: string;
+    agent: {
+        currentMode: AIOperationMode;
+        availableModes: Array<{
+            mode: AIOperationMode;
+            purpose: string;
+            mutatesFiles: boolean;
+            mutatesRuntime: boolean;
+        }>;
+        transport: {
+            modelTraffic: string;
+            bridgeRole: string;
+            productionRole: string;
+        };
+        rules?: {
+            path: string;
+            content: string;
+        };
+    };
     app?: {
         mode: "frontend" | "fullstack" | "server";
         runtimeTopology: "single-instance" | "multi-instance";
@@ -133,7 +152,10 @@ export interface AIIncidentSnapshot {
     hotspots: AIContextPacket["hotspots"];
     recommendations: string[];
 }
-export declare function createAIContextPacket(report: AIHealthReport, events: AIEvent[], latestDiagnostic?: Partial<AIDiagnostic>, reactiveTrace?: ReactiveTraceArtifact | null): AIContextPacket;
+export declare function createAIContextPacket(report: AIHealthReport, events: AIEvent[], latestDiagnostic?: Partial<AIDiagnostic>, reactiveTrace?: ReactiveTraceArtifact | null, agentInput?: {
+    currentMode?: AIOperationMode;
+    rules?: AIRulesFile;
+}): AIContextPacket;
 export declare function renderAIContextMarkdown(packet: AIContextPacket): string;
 export declare function createAIReleaseBrief(packet: AIContextPacket): AIReleaseBrief;
 export declare function renderAIReleaseBriefMarkdown(brief: AIReleaseBrief): string;

package/dist-pkg/ai/summary.js

@@ -1,5 +1,9 @@
 import { GORSEE_AI_CONTEXT_SCHEMA_VERSION } from "./contracts.js";
-export function createAIContextPacket(report, events, latestDiagnostic, reactiveTrace) {
+import {
+  AI_OPERATION_MODES,
+  AI_TRANSPORT_CONTRACT
+} from "./rules.js";
+export function createAIContextPacket(report, events, latestDiagnostic, reactiveTrace, agentInput = {}) {
   const readiness = report.readiness ?? {
     deploy: { status: "ready", reasons: [] },
     scaling: { status: "not-applicable", reasons: [] }
@@ -7,6 +11,15 @@ export function createAIContextPacket(report, events, latestDiagnostic, reactive
   return {
     schemaVersion: GORSEE_AI_CONTEXT_SCHEMA_VERSION,
     generatedAt: new Date().toISOString(),
+    agent: {
+      currentMode: agentInput.currentMode ?? "inspect",
+      availableModes: AI_OPERATION_MODES,
+      transport: AI_TRANSPORT_CONTRACT,
+      rules: agentInput.rules ? {
+        path: agentInput.rules.path,
+        content: agentInput.rules.content
+      } : void 0
+    },
     app: report.app,
     summary: {
       headline: buildHeadline(report),
@@ -74,6 +87,13 @@ export function renderAIContextMarkdown(packet) {
       `- Runtime topology: ${packet.app.runtimeTopology}`,
       ""
     ] : [],
+    "## AI Agent",
+    "",
+    `- Current mode: ${packet.agent.currentMode}`,
+    `- Model traffic: ${packet.agent.transport.modelTraffic}`,
+    `- Bridge role: ${packet.agent.transport.bridgeRole}`,
+    `- Production role: ${packet.agent.transport.productionRole}`,
+    ...packet.agent.rules ? [`- Rules: ${packet.agent.rules.path}`, ""] : [""],
     "## Summary",
     "",
     `- ${packet.summary.headline}`,
@@ -140,6 +160,8 @@ export function renderAIContextMarkdown(packet) {
     if (packet.reactiveTrace.latestEventKind)
       lines.push(`- Latest event: ${packet.reactiveTrace.latestEventKind}`);
   }
+  if (packet.agent.rules)
+    lines.push("", "## AI Rules", "", `Source: ${packet.agent.rules.path}`, "", packet.agent.rules.content);
   if (packet.recommendations.length > 0) {
     lines.push("", "## Recommendations", "");
     for (const recommendation of packet.recommendations)

package/dist-pkg/ai/watch.d.ts

@@ -1,10 +1,13 @@
 import type { AIStorePaths } from "./store.js";
 import type { IDEProjection, IDEProjectionPaths } from "./ide.js";
+import type { AIOperationMode } from "./rules.js";
 export interface IDEProjectionWatcherOptions {
     storePaths: AIStorePaths;
     projectionPaths: IDEProjectionPaths;
     intervalMs?: number;
     limit?: number;
+    cwd?: string;
+    mode?: AIOperationMode;
     onSync?: (projection: IDEProjection) => void | Promise<void>;
 }
 export interface IDEProjectionWatcher {

package/dist-pkg/ai/watch.js

@@ -6,7 +6,11 @@ export function createIDEProjectionWatcher(options) {
     async syncOnce() {
       syncing = !0;
       try {
-        const projection = await buildIDEProjection(options.storePaths, { limit: options.limit ?? 100 });
+        const projection = await buildIDEProjection(options.storePaths, {
+          limit: options.limit ?? 100,
+          cwd: options.cwd,
+          mode: options.mode
+        });
         await writeIDEProjection(options.projectionPaths, projection);
         if (options.onSync)
           await options.onSync(projection);

package/dist-pkg/cli/cmd-ai.js

@@ -1,4 +1,12 @@
 import { createProjectContext } from "../runtime/project.js";
+import {
+  mkdir,
+  writeFile
+} from "node:fs/promises";
+import {
+  basename,
+  join
+} from "node:path";
 import {
   buildAIHealthReport,
   buildAIContextBundle,
@@ -11,9 +19,13 @@ import {
   createAIReleaseBrief,
   createAIMCPServer,
   createLineReader,
+  AI_OPERATION_MODES,
+  renderDefaultAIGuideMarkdown,
+  renderDefaultAIRulesMarkdown,
   readAIDiagnosticsSnapshot,
   readAIEvents,
   readReactiveTraceArtifact,
+  resolveAIRulesFile,
   renderAIIncidentBriefMarkdown,
   renderAIContextMarkdown,
   renderAIContextBundleMarkdown,
@@ -22,24 +34,30 @@ import {
   resolveAIStorePaths,
   resolveAISessionPackPaths,
   resolveIDEProjectionPaths,
+  writeAICheckpoint,
   writeAISessionPack,
   writeIDEProjection
 } from "../ai/index.js";
+import { loadAppConfig, resolveAppMode } from "../runtime/app-config.js";
 export async function runAI(args, options = {}) {
   const subcommand = args[0] ?? "help", flags = parseAIFlags(args.slice(1)), { cwd } = createProjectContext(options), paths = resolveAIStorePaths(cwd);
   switch (subcommand) {
     case "framework":
       return runAIFramework(cwd, flags);
+    case "init":
+      return runAIInit(cwd, flags);
     case "tail":
       return runAITail(paths.eventsPath, flags);
     case "doctor":
-      return runAIDoctor(paths, flags);
+      return runAIDoctor(cwd, paths, flags);
     case "replay":
       return runAIReplay(paths.eventsPath, flags);
     case "export":
       return runAIExport(cwd, paths, flags);
     case "pack":
       return runAIPack(cwd, paths, flags);
+    case "checkpoint":
+      return runAICheckpoint(cwd, paths, flags);
     case "ide-sync":
       return runAIIDESync(cwd, paths, flags);
     case "bridge":
@@ -59,6 +77,50 @@ async function runAIFramework(cwd, flags) {
   }
   console.log(JSON.stringify(packet, null, 2));
 }
+async function runAIInit(cwd, flags) {
+  const appMode = resolveAppMode(await loadAppConfig(cwd)), projectName = basename(cwd), gorseeDir = join(cwd, ".gorsee"), agentDir = join(gorseeDir, "agent"), checkpointsDir = join(agentDir, "checkpoints"), rulesPath = join(gorseeDir, "rules.md"), guidePath = join(cwd, "GORSEE.md");
+  await mkdir(checkpointsDir, { recursive: !0 });
+  const writes = [], rulesExists = Boolean(await resolveAIRulesFile(cwd));
+  if (!rulesExists || flags.force) {
+    await writeFile(rulesPath, renderDefaultAIRulesMarkdown({ projectName, appMode }), "utf-8");
+    writes.push({ path: ".gorsee/rules.md", status: rulesExists ? "updated" : "created" });
+  } else
+    writes.push({ path: ".gorsee/rules.md", status: "kept" });
+  const guideExists = await Bun.file(guidePath).exists();
+  if (!guideExists || flags.force) {
+    await writeFile(guidePath, renderDefaultAIGuideMarkdown({ projectName, appMode }), "utf-8");
+    writes.push({ path: "GORSEE.md", status: guideExists ? "updated" : "created" });
+  } else
+    writes.push({ path: "GORSEE.md", status: "kept" });
+  if (flags.json) {
+    console.log(JSON.stringify({
+      projectName,
+      appMode,
+      scaffolded: writes,
+      checkpointsDir: ".gorsee/agent/checkpoints",
+      nextSteps: [
+        "gorsee ai framework --format markdown",
+        "gorsee ai checkpoint --mode inspect",
+        "gorsee check"
+      ]
+    }, null, 2));
+    return;
+  }
+  console.log(`
+  Gorsee AI Init
+`);
+  console.log(`  project     -> ${projectName}`);
+  console.log(`  app mode    -> ${appMode}`);
+  for (const entry of writes)
+    console.log(`  ${entry.status.padEnd(11, " ")}-> ${entry.path}`);
+  console.log("  prepared    -> .gorsee/agent/checkpoints");
+  console.log();
+  console.log("  Next:");
+  console.log("    1. Review .gorsee/rules.md and tailor it to the repository.");
+  console.log("    2. Review GORSEE.md for local operator guidance.");
+  console.log("    3. Run `gorsee ai checkpoint --mode inspect` before the first tracked AI session.");
+  console.log();
+}
 async function runAITail(eventsPath, flags) {
   const events = await readAIEvents(eventsPath, { limit: flags.limit ?? 20 });
   if (flags.json) {
@@ -79,11 +141,15 @@ async function runAITail(eventsPath, flags) {
   }
   console.log();
 }
-async function runAIDoctor(paths, flags) {
-  const report = await buildAIHealthReport(paths, { limit: flags.limit ?? 200 }), reactiveTrace = await readReactiveTraceArtifact(paths.reactiveTracePath);
+async function runAIDoctor(cwd, paths, flags) {
+  const report = await buildAIHealthReport(paths, { limit: flags.limit ?? 200 }), reactiveTrace = await readReactiveTraceArtifact(paths.reactiveTracePath), rules = await resolveAIRulesFile(cwd);
   if (flags.json) {
     console.log(JSON.stringify({
       ...report,
+      agent: {
+        currentMode: flags.mode ?? "inspect",
+        rulesPath: rules?.path
+      },
       reactiveTrace: reactiveTrace ? {
         schemaVersion: reactiveTrace.schemaVersion,
         nodes: reactiveTrace.nodes.length,
@@ -101,6 +167,9 @@ async function runAIDoctor(paths, flags) {
   console.log(`  Diagnostics: ${report.diagnostics.total}`);
   console.log(`  Errors: ${report.diagnostics.errors}`);
   console.log(`  Warnings: ${report.diagnostics.warnings}`);
+  console.log(`  AI mode: ${flags.mode ?? "inspect"}`);
+  if (rules?.path)
+    console.log(`  Rules: ${rules.path}`);
   console.log(`  Deploy readiness: ${report.readiness.deploy.status}`);
   console.log(`  Scaling readiness: ${report.readiness.scaling.status}`);
   if (report.events.latest)
@@ -186,7 +255,7 @@ async function runAIReplay(eventsPath, flags) {
 }
 async function runAIExport(cwd, paths, flags) {
   if (flags.bundle) {
-    const bundle = await buildAIContextBundle(cwd, paths, { limit: flags.limit ?? 200 });
+    const bundle = await buildAIContextBundle(cwd, paths, { limit: flags.limit ?? 200, mode: flags.mode ?? "inspect" });
     if ((flags.format ?? "json") === "markdown") {
       console.log(renderAIContextBundleMarkdown(bundle));
       return;
@@ -194,7 +263,10 @@ async function runAIExport(cwd, paths, flags) {
     console.log(JSON.stringify(bundle, null, 2));
     return;
   }
-  const events = await readAIEvents(paths.eventsPath, { limit: flags.limit ?? 200 }), diagnostics = await readAIDiagnosticsSnapshot(paths.diagnosticsPath), reactiveTrace = await readReactiveTraceArtifact(paths.reactiveTracePath), report = await buildAIHealthReport(paths, { limit: flags.limit ?? 200 }), packet = createAIContextPacket(report, events, diagnostics?.latest, reactiveTrace);
+  const events = await readAIEvents(paths.eventsPath, { limit: flags.limit ?? 200 }), diagnostics = await readAIDiagnosticsSnapshot(paths.diagnosticsPath), reactiveTrace = await readReactiveTraceArtifact(paths.reactiveTracePath), report = await buildAIHealthReport(paths, { limit: flags.limit ?? 200 }), rules = await resolveAIRulesFile(cwd), packet = createAIContextPacket(report, events, diagnostics?.latest, reactiveTrace, {
+    currentMode: flags.mode ?? "inspect",
+    rules
+  });
   if (flags.brief === "release") {
     const brief = createAIReleaseBrief(packet);
     if ((flags.format ?? "json") === "markdown") {
@@ -223,7 +295,8 @@ async function runAIPack(cwd, paths, flags) {
   const result = await writeAISessionPack(cwd, paths, {
     enabled: !0,
     outDir: resolveAISessionPackPaths(cwd).outDir,
-    limit: flags.limit ?? 200
+    limit: flags.limit ?? 200,
+    mode: flags.mode ?? "inspect"
   });
   if (flags.json) {
     console.log(JSON.stringify({
@@ -260,15 +333,52 @@ async function runAIPack(cwd, paths, flags) {
   console.log(`  snippets    -> ${result.bundle.snippets.length}`);
   console.log();
 }
+async function runAICheckpoint(cwd, paths, flags) {
+  const result = await writeAICheckpoint(cwd, paths, {
+    name: flags.name,
+    mode: flags.mode ?? "inspect",
+    limit: flags.limit ?? 200,
+    maxSnippets: 6
+  });
+  if (flags.json) {
+    console.log(JSON.stringify({
+      createdAt: result.metadata.createdAt,
+      name: result.metadata.name,
+      mode: result.metadata.mode,
+      bundleJsonPath: result.paths.bundleJsonPath,
+      bundleMarkdownPath: result.paths.bundleMarkdownPath,
+      metadataPath: result.paths.metadataPath,
+      latestPointerPath: result.paths.latestPointerPath,
+      rulesPath: result.metadata.rulesPath,
+      snippets: result.bundle.snippets.length
+    }, null, 2));
+    return;
+  }
+  console.log(`
+  Gorsee AI Checkpoint
+`);
+  console.log(`  name        -> ${result.metadata.name}`);
+  console.log(`  mode        -> ${result.metadata.mode}`);
+  console.log(`  bundle json -> ${result.paths.bundleJsonPath}`);
+  console.log(`  bundle md   -> ${result.paths.bundleMarkdownPath}`);
+  console.log(`  metadata    -> ${result.paths.metadataPath}`);
+  console.log(`  latest      -> ${result.paths.latestPointerPath}`);
+  if (result.metadata.rulesPath)
+    console.log(`  rules       -> ${result.metadata.rulesPath}`);
+  console.log(`  snippets    -> ${result.bundle.snippets.length}`);
+  console.log();
+}
 async function runAIIDESync(cwd, paths, flags) {
-  const projection = await buildIDEProjection(paths, { limit: flags.limit ?? 100 }), projectionPaths = resolveIDEProjectionPaths(cwd);
+  const projection = await buildIDEProjection(paths, { limit: flags.limit ?? 100, cwd, mode: flags.mode ?? "inspect" }), projectionPaths = resolveIDEProjectionPaths(cwd);
   await writeIDEProjection(projectionPaths, projection);
   if (flags.watch) {
     createIDEProjectionWatcher({
       storePaths: paths,
       projectionPaths,
       limit: flags.limit ?? 100,
-      intervalMs: flags.intervalMs ?? 1000
+      intervalMs: flags.intervalMs ?? 1000,
+      cwd,
+      mode: flags.mode ?? "inspect"
     }).start();
     console.log(`
   Gorsee AI IDE Sync --watch
@@ -310,11 +420,13 @@ async function runAIMCP(paths, flags) {
   }).serve(createLineReader(process.stdin), process.stdout);
 }
 function parseAIFlags(args) {
-  const flags = { json: !1, bundle: !1, watch: !1 };
+  const flags = { json: !1, bundle: !1, watch: !1, force: !1 };
   for (let i = 0;i < args.length; i++) {
     const arg = args[i];
     if (arg === "--json")
       flags.json = !0;
+    if (arg === "--force")
+      flags.force = !0;
     if (arg === "--bundle")
       flags.bundle = !0;
     if (arg === "--watch")
@@ -339,6 +451,13 @@ function parseAIFlags(args) {
       if (brief === "release" || brief === "incident")
         flags.brief = brief;
     }
+    if (arg === "--mode") {
+      const mode = args[i + 1];
+      if (AI_OPERATION_MODES.some((entry) => entry.mode === mode))
+        flags.mode = mode;
+    }
+    if (arg === "--name")
+      flags.name = args[i + 1];
   }
   return flags;
 }
@@ -347,6 +466,7 @@ function printAIHelp() {
   gorsee ai <subcommand>
 `);
   console.log("  Subcommands:");
+  console.log("    init       Create local AI rules and operator scaffold files");
   console.log("    framework  Export canonical framework context for cold-start agents");
   console.log("    tail       Read recent structured AI events");
   console.log("    doctor     Summarize diagnostics and recent incidents");
@@ -354,6 +474,7 @@ function printAIHelp() {
   console.log("    export     Export a compact AI context packet or bundle");
   console.log("               Use --brief release|incident for verdict-oriented summaries");
   console.log("    pack       Write the latest agent-ready session pack to disk");
+  console.log("    checkpoint Write an explicit AI checkpoint with operation-mode metadata");
   console.log("    ide-sync   Write IDE-friendly diagnostics/events/context files");
   console.log("    bridge     Start local HTTP bridge for IDE/agent ingestion");
   console.log("    mcp        Start stdio MCP server over local AI state");
@@ -365,5 +486,8 @@ function printAIHelp() {
   console.log("    --bundle            Include ranked code snippets in export output");
   console.log("    --watch             Keep IDE projection files in sync");
   console.log("    --interval <ms>     Watch/poll interval for ide-sync --watch");
+  console.log("    --mode <mode>       inspect | propose | apply | operate");
+  console.log("    --name <value>      Human-readable checkpoint name");
+  console.log("    --force             Overwrite AI scaffold files when they already exist");
   console.log();
 }

package/dist-pkg/cli/cmd-check.js

@@ -9,7 +9,8 @@ import { rewriteCanonicalImportsInProject, rewriteLegacyLoadersInProject } from
 import {
   configureAIObservability,
   emitAIDiagnostic,
-  emitAIEvent
+  emitAIEvent,
+  resolveAIRulesFile
 } from "../ai/index.js";
 import { loadAppConfig, resolveAIConfig, resolveAppMode, resolveRuntimeTopology } from "../runtime/app-config.js";
 const MAX_FILE_LINES = 500;
@@ -502,6 +503,35 @@ async function checkOriginPlaceholderPolicy(cwd) {
   }
   return issues;
 }
+async function checkAIContracts(cwd) {
+  const issues = [], aiEnabled = (await loadAppConfig(cwd)).ai?.enabled ?? !1, rules = await resolveAIRulesFile(cwd);
+  if (aiEnabled && !rules)
+    issues.push({
+      code: "W928",
+      file: "app.config.ts",
+      message: "AI observability is enabled but no local AI rules file was found",
+      fix: "Add .gorsee/rules.md (preferred) or GORSEE.md so agents and operator workflows share an explicit local contract"
+    });
+  const latestAgentPacketSource = await tryReadFile(join(cwd, ".gorsee", "agent", "latest.json")), latestCheckpointSource = await tryReadFile(join(cwd, ".gorsee", "agent", "checkpoints", "latest.json"));
+  try {
+    const latestPacket = latestAgentPacketSource ? JSON.parse(latestAgentPacketSource) : null, latestCheckpoint = latestCheckpointSource ? JSON.parse(latestCheckpointSource) : null, currentMode = latestPacket?.agent?.currentMode, mutatingMode = currentMode === "apply" || currentMode === "operate", hasMatchingCheckpoint = latestCheckpoint?.mode === currentMode;
+    if (mutatingMode && !hasMatchingCheckpoint)
+      issues.push({
+        code: "W929",
+        file: ".gorsee/agent/latest.json",
+        message: `Latest AI packet reports mutating mode "${currentMode}" without a matching explicit checkpoint`,
+        fix: `Run \`gorsee ai checkpoint --mode ${currentMode}\` before or during mutating AI workflows so the session state is preserved explicitly`
+      });
+  } catch {
+    issues.push({
+      code: "W929",
+      file: ".gorsee/agent/latest.json",
+      message: "Could not parse latest AI packet or checkpoint metadata for mutating-mode enforcement",
+      fix: "Regenerate AI packet/checkpoint artifacts so mutating-mode workflows stay inspectable"
+    });
+  }
+  return issues;
+}
 async function projectUsesServerFunctions(files, astFacts) {
   for (const file of files) {
     const ast = astFacts.get(file);
@@ -635,6 +665,9 @@ export async function checkProject(options = {}) {
   const placeholderIssues = await checkOriginPlaceholderPolicy(cwd);
   for (const issue of placeholderIssues)
     pushIssue(result, issue, strictSecurity);
+  const aiIssues = await checkAIContracts(cwd);
+  for (const issue of aiIssues)
+    pushIssue(result, issue, strictSecurity);
   if (runTypeScript) {
     const tsc = Bun.spawn(["bun", "x", "tsc", "--noEmit"], {
       cwd,

package/dist-pkg/cli/framework-md.js

@@ -372,11 +372,17 @@ gorsee check        Type + safety + structure check
 gorsee worker       Run canonical server-mode worker entry
 gorsee check --rewrite-imports --rewrite-loaders
                     Normalize canonical imports and loader aliases before auditing
+gorsee ai init      Scaffold local AI rules, operator guide, and checkpoints
 gorsee ai framework Export canonical framework context for cold-start agents
+gorsee ai tail      Inspect recent structured AI events
 gorsee ai doctor    Summarize AI diagnostics and incidents
 gorsee ai replay    Reconstruct recent correlated AI event timeline
 gorsee ai export    Export a compact agent-ready context packet
+gorsee ai pack      Write the latest grounded AI session pack to disk
+gorsee ai checkpoint
+                    Record an explicit named AI workflow checkpoint
 gorsee ai ide-sync  Write IDE-friendly diagnostics/events/context files
+gorsee ai bridge    Accept trusted local AI event ingestion
 gorsee ai mcp       Expose local AI state as a stdio MCP server
 gorsee routes       List all routes
 gorsee migrate      Run database migrations
@@ -385,6 +391,7 @@ gorsee generate X   Generate CRUD for entity X
 
 - For installed apps, prefer \`gorsee upgrade\` for the full version bump + rewrite + verification flow.
 - Use \`gorsee upgrade --check --report docs/upgrade-report.json\` for a dry-run audit without installation.
+- When AI workflows are enabled, run \`gorsee ai init\` once and tailor \`.gorsee/rules.md\` before the first tracked session.
 
 ## Error Codes
 

package/dist-pkg/cli/index.js

@@ -12,7 +12,7 @@ const args = process.argv.slice(2), command = args[0], COMMANDS = {
   deploy: "Generate deploy config (vercel/fly/cloudflare/netlify/docker)",
   test: "Run tests (unit/integration/e2e)",
   docs: "Generate API documentation from routes",
-  ai: "AI-first tooling: framework, tail, doctor, bridge, mcp",
+  ai: "AI-first tooling: init, framework, tail, doctor, export, pack, checkpoint, ide-sync, bridge, mcp",
   upgrade: "Upgrade Gorsee.js with migration audit and canonical rewrites",
   help: "Show this help message"
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gorsee",
-  "version": "0.2.14",
+  "version": "0.2.15",
   "description": "AI-first reactive full-stack TypeScript framework for deterministic human and agent collaboration",
   "type": "module",
   "packageManager": "bun@1.3.9",
@@ -74,6 +74,7 @@
     "dependency:policy": "node scripts/dependency-contract-check.mjs",
     "deploy:policy": "node scripts/deploy-contract-check.mjs",
     "api:policy": "node scripts/api-stability-check.mjs",
+    "cli:policy": "node scripts/cli-contract-check.mjs",
     "adoption:policy": "node scripts/adoption-proof-check.mjs",
     "ai:policy": "node scripts/ai-policy-check.mjs",
     "dx:policy": "node scripts/dx-policy-check.mjs",
@@ -105,7 +106,7 @@
     "coverage:audit": "node scripts/coverage-audit-check.mjs",
     "repo:policy": "node scripts/repo-policy-check.mjs",
     "ci:policy": "node scripts/ci-policy-check.mjs",
-    "verify:security": "bun run check && bun run product:policy && bun run dependency:policy && bun run deploy:policy && bun run api:policy && bun run adoption:policy && bun run ai:policy && bun run dx:policy && bun run maturity:policy && bun run top-tier:exit && bun run runtime:policy && bun run runtime:security:policy && bun run benchmarks:policy && bun run benchmarks:realworld:check && bun run examples:policy && bun run proof:policy && bun run critical:surface && bun run coverage:audit && bun run repo:policy && bun run ci:policy && bun run compiler:promotion:check && bun run build:promotion:check && bun run backend:switch:evidence:check && bun run backend:default-switch:review:check && bun run backend:candidate:rollout:check && bun run compiler:default:rehearsal:check && bun run build:default:rehearsal:check && bun run test:security && bun run test:critical-surface && bun run test:confidence",
+    "verify:security": "bun run check && bun run product:policy && bun run dependency:policy && bun run deploy:policy && bun run api:policy && bun run cli:policy && bun run adoption:policy && bun run ai:policy && bun run dx:policy && bun run maturity:policy && bun run top-tier:exit && bun run runtime:policy && bun run runtime:security:policy && bun run benchmarks:policy && bun run benchmarks:realworld:check && bun run examples:policy && bun run proof:policy && bun run critical:surface && bun run coverage:audit && bun run repo:policy && bun run ci:policy && bun run compiler:promotion:check && bun run build:promotion:check && bun run backend:switch:evidence:check && bun run backend:default-switch:review:check && bun run backend:candidate:rollout:check && bun run compiler:default:rehearsal:check && bun run build:default:rehearsal:check && bun run test:security && bun run test:critical-surface && bun run test:confidence",
     "check": "tsc --noEmit",
     "install:matrix": "node scripts/install-matrix-check.mjs",
     "dev": "bun run src/dev.ts",