gorsee 0.2.13 → 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;