gorsee 0.2.7 → 0.2.8

package/README.md

@@ -95,6 +95,12 @@ npm create gorsee@latest my-app
 
 Open [http://localhost:3000](http://localhost:3000).
 
+For agent cold-start context:
+
+```bash
+bunx gorsee ai framework --format markdown
+```
+
 ## Why Gorsee
 
 Most modern frameworks optimize for flexibility, historical compatibility, or ecosystem breadth.
@@ -115,6 +121,7 @@ What that means in practice:
 - content collections with nested frontmatter parsing, schema validation, excerpts, block-scalar support, and locale-aware querying
 - deterministic plugin platform with capabilities, dependency ordering, config validation, and conformance testing
 - AI diagnostics, saved reactive-trace ingestion, context bundles, IDE projections, and MCP integration built into the framework lifecycle
+- canonical cold-start framework packets via `gorsee ai framework`
 - CLI enforcement through `gorsee check`, release gates, deploy contracts, and policy docs
 - machine-readable public API stability enforcement through `bun run api:policy`
 - machine-readable adoption and market-ready proof enforcement through `bun run adoption:policy`
@@ -255,7 +262,7 @@ npm create gorsee@latest my-app
 | `gorsee routes` | Show route table |
 | `gorsee generate <entity>` | Generate CRUD scaffold with typed routes, validated forms, and inferred `memory|sqlite|postgres` data mode |
 | `gorsee docs --format json --contracts` | Emit machine-readable route/docs contract artifact |
-| `gorsee upgrade --rewrite-imports --check --report docs/upgrade-report.json` | Audit migration drift, rewrite obvious import/loader aliases, and write a structured upgrade report |
+| `gorsee upgrade` | Upgrade to the latest published Gorsee version, rewrite obvious migration drift, write `docs/upgrade-report.json`, and run verification |
 | `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 |
@@ -269,7 +276,8 @@ Runtime debugging surface:
 Migration ergonomics:
 
 - `gorsee check --rewrite-imports --rewrite-loaders` can normalize obvious scoped-import and `loader -> load` drift before the audit runs.
-- `gorsee upgrade --rewrite-imports --check --report docs/upgrade-report.json` is the canonical migration cleanup flow.
+- `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.
 
 ## Product Standards
 

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

@@ -0,0 +1,42 @@
+export interface AIFrameworkDocRef {
+    path: string;
+    purpose: string;
+}
+export interface AIFrameworkPacket {
+    kind: "gorsee.framework";
+    schemaVersion: 1;
+    generatedAt: string;
+    cwd: string;
+    projectName: string;
+    product: {
+        name: "Gorsee";
+        version?: string;
+        identity: string;
+        maturity: string;
+    };
+    entrypoints: {
+        browser: string;
+        server: string;
+        compatibility: string;
+        scoped: string[];
+    };
+    routeGrammar: string[];
+    syntax: {
+        browserImports: string;
+        serverImports: string;
+        routeExample: string;
+    };
+    aiCommands: Array<{
+        command: string;
+        purpose: string;
+    }>;
+    docs: {
+        local: AIFrameworkDocRef[];
+        canonical: AIFrameworkDocRef[];
+    };
+    recommendedStart: string[];
+    frameworkReferencePath?: string;
+    frameworkReferenceMarkdown: string;
+}
+export declare function buildAIFrameworkPacket(cwd: string): Promise<AIFrameworkPacket>;
+export declare function renderAIFrameworkMarkdown(packet: AIFrameworkPacket): string;

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

@@ -0,0 +1,172 @@
+import { access, readFile } from "node:fs/promises";
+import { basename, join, relative } from "node:path";
+import { generateFrameworkMD } from "../cli/framework-md.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" },
+  { path: "README.md", purpose: "\u0411\u044B\u0441\u0442\u0440\u044B\u0439 \u0432\u0445\u043E\u0434 \u0438 \u043F\u0443\u0431\u043B\u0438\u0447\u043D\u0430\u044F \u043F\u043E\u0432\u0435\u0440\u0445\u043D\u043E\u0441\u0442\u044C" }
+], CANONICAL_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/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/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_SESSION_PACKS.md", purpose: "Cross-session handoff \u0434\u043B\u044F \u0430\u0433\u0435\u043D\u0442\u043E\u0432" },
+  { 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 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 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 ide-sync", purpose: "IDE-friendly projection \u0444\u0430\u0439\u043B\u043E\u0432" },
+  { 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) {
+  try {
+    await access(path);
+    return !0;
+  } catch {
+    return !1;
+  }
+}
+async function readJSON(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf-8"));
+  } catch {
+    return;
+  }
+}
+async function resolveFrameworkVersion() {
+  for (const candidate of [
+    join(import.meta.dir, "..", "..", "package.json"),
+    join(import.meta.dir, "..", "package.json")
+  ]) {
+    const pkg = await readJSON(candidate);
+    if (typeof pkg?.version === "string")
+      return pkg.version;
+  }
+  return;
+}
+async function resolveProjectName(cwd) {
+  const pkg = await readJSON(join(cwd, "package.json"));
+  if (typeof pkg?.name === "string" && pkg.name.trim().length > 0)
+    return pkg.name;
+  return basename(cwd);
+}
+async function collectDocRefs(cwd, refs) {
+  const result = [];
+  for (const ref of refs)
+    if (await pathExists(join(cwd, ref.path)))
+      result.push(ref);
+  return result;
+}
+function renderDocLines(docs) {
+  return docs.map((doc) => `- \`${doc.path}\` -- ${doc.purpose}`);
+}
+export async function buildAIFrameworkPacket(cwd) {
+  const projectName = await resolveProjectName(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);
+  return {
+    kind: "gorsee.framework",
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    cwd,
+    projectName,
+    product: {
+      name: "Gorsee",
+      version: await resolveFrameworkVersion(),
+      identity: "AI-first reactive full-stack framework for deterministic human and agent collaboration",
+      maturity: "Mature product framework with strict runtime, security, release, and AI workflow contracts"
+    },
+    entrypoints: {
+      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"]
+    },
+    routeGrammar: [
+      "default export -> page UI",
+      "load -> route data reads",
+      "action -> page-bound mutations",
+      "cache -> declarative cache policy",
+      "middleware -> request policy and cross-cutting guards",
+      "GET/POST/etc -> raw HTTP endpoints"
+    ],
+    syntax: {
+      browserImports: 'import { createSignal, Head, Link } from "gorsee/client"',
+      serverImports: 'import { middleware, type Context } from "gorsee/server"',
+      routeExample: "routes/users/[id].tsx -> /users/:id"
+    },
+    aiCommands: AI_COMMANDS,
+    docs: {
+      local: localDocs,
+      canonical: canonicalDocs
+    },
+    recommendedStart: [
+      "Read AGENTS.md first when it exists.",
+      "Read FRAMEWORK.md for the current app shape and syntax.",
+      "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.",
+      "Use gorsee ai export --bundle for incident/debug context, not for framework cold-start context."
+    ],
+    frameworkReferencePath,
+    frameworkReferenceMarkdown
+  };
+}
+export function renderAIFrameworkMarkdown(packet) {
+  return [
+    "# Gorsee AI Framework Packet",
+    "",
+    `Generated: ${packet.generatedAt}`,
+    `Project: ${packet.projectName}`,
+    packet.product.version ? `Framework Version: ${packet.product.version}` : void 0,
+    "",
+    "## Product",
+    "",
+    `- ${packet.product.identity}`,
+    `- ${packet.product.maturity}`,
+    "",
+    "## Canonical Entrypoints",
+    "",
+    `- browser: \`${packet.entrypoints.browser}\``,
+    `- server: \`${packet.entrypoints.server}\``,
+    `- compatibility: ${packet.entrypoints.compatibility}`,
+    `- scoped: ${packet.entrypoints.scoped.map((entry) => `\`${entry}\``).join(", ")}`,
+    "",
+    "## Route Grammar",
+    "",
+    ...packet.routeGrammar.map((entry) => `- ${entry}`),
+    "",
+    "## Syntax",
+    "",
+    `- ${packet.syntax.browserImports}`,
+    `- ${packet.syntax.serverImports}`,
+    `- ${packet.syntax.routeExample}`,
+    "",
+    "## Recommended Start",
+    "",
+    ...packet.recommendedStart.map((entry) => `- ${entry}`),
+    "",
+    "## AI Commands",
+    "",
+    ...packet.aiCommands.map((entry) => `- \`${entry.command}\` -- ${entry.purpose}`),
+    "",
+    "## Local Docs",
+    "",
+    ...packet.docs.local.length > 0 ? renderDocLines(packet.docs.local) : ["- No local AI/context docs detected in the current cwd."],
+    "",
+    "## Canonical Docs",
+    "",
+    ...packet.docs.canonical.length > 0 ? renderDocLines(packet.docs.canonical) : ["- Canonical repo docs are not present in the current cwd."],
+    "",
+    "## Framework Reference",
+    "",
+    packet.frameworkReferencePath ? `Source: \`${packet.frameworkReferencePath}\`` : "Source: generated built-in framework reference",
+    "",
+    packet.frameworkReferenceMarkdown
+  ].filter((line) => line !== void 0).join(`
+`);
+}

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

@@ -6,6 +6,7 @@ export { buildAIHealthReport, readAIDiagnosticsSnapshot, readReactiveTraceArtifa
 export { createAIMCPServer, createLineReader, type AIMCPServerOptions, } from "./mcp.js";
 export { createAIContextPacket, renderAIContextMarkdown, type AIContextPacket, } from "./summary.js";
 export { buildAIContextBundle, renderAIContextBundleMarkdown, type AIContextBundle, type AIContextSnippet, } from "./bundle.js";
+export { buildAIFrameworkPacket, renderAIFrameworkMarkdown, type AIFrameworkDocRef, type AIFrameworkPacket, } from "./framework-context.js";
 export { buildIDEProjection, resolveIDEProjectionPaths, writeIDEProjection, type IDEProjection, type IDEProjectionPaths, } from "./ide.js";
 export { createIDEProjectionWatcher, type IDEProjectionWatcher, type IDEProjectionWatcherOptions, } from "./watch.js";
 export { resolveAISessionPackConfig, resolveAISessionPackPaths, shouldGenerateAISessionPack, writeAISessionPack, type AISessionPackConfig, type AISessionPackPaths, } from "./session-pack.js";

package/dist-pkg/ai/index.js

@@ -37,6 +37,10 @@ export {
   buildAIContextBundle,
   renderAIContextBundleMarkdown
 } from "./bundle.js";
+export {
+  buildAIFrameworkPacket,
+  renderAIFrameworkMarkdown
+} from "./framework-context.js";
 export {
   buildIDEProjection,
   resolveIDEProjectionPaths,

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

@@ -2,6 +2,7 @@ import { createProjectContext } from "../runtime/project.js";
 import {
   buildAIHealthReport,
   buildAIContextBundle,
+  buildAIFrameworkPacket,
   buildIDEProjection,
   createIDEProjectionWatcher,
   createAIBridgeServer,
@@ -13,6 +14,7 @@ import {
   readReactiveTraceArtifact,
   renderAIContextMarkdown,
   renderAIContextBundleMarkdown,
+  renderAIFrameworkMarkdown,
   resolveAIStorePaths,
   resolveAISessionPackPaths,
   resolveIDEProjectionPaths,
@@ -22,6 +24,8 @@ import {
 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 "tail":
       return runAITail(paths.eventsPath, flags);
     case "doctor":
@@ -43,6 +47,14 @@ export async function runAI(args, options = {}) {
       printAIHelp();
   }
 }
+async function runAIFramework(cwd, flags) {
+  const packet = await buildAIFrameworkPacket(cwd);
+  if ((flags.format ?? "json") === "markdown") {
+    console.log(renderAIFrameworkMarkdown(packet));
+    return;
+  }
+  console.log(JSON.stringify(packet, null, 2));
+}
 async function runAITail(eventsPath, flags) {
   const events = await readAIEvents(eventsPath, { limit: flags.limit ?? 20 });
   if (flags.json) {
@@ -270,6 +282,7 @@ function printAIHelp() {
   gorsee ai <subcommand>
 `);
   console.log("  Subcommands:");
+  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");
   console.log("    replay     Replay correlated AI events in timeline order");

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

@@ -190,7 +190,7 @@ function checkImportContracts(cwd, astFacts) {
         code: "W916",
         file: rel,
         message: 'Route module still exports "loader" instead of canonical "load"',
-        fix: 'Rename exported "loader" to "load", or run `gorsee check --rewrite-loaders` / `gorsee upgrade --rewrite-imports` to rewrite obvious cases automatically'
+        fix: 'Rename exported "loader" to "load", or run `gorsee check --rewrite-loaders` / `gorsee upgrade` to rewrite obvious cases automatically'
       });
     for (const drift of collectCanonicalImportDrift(facts.imports)) {
       const entries = [...drift.replacements.entries()].map(([name, target]) => `${name} -> ${target}`).join(", "), targets = [...new Set(drift.replacements.values())].join(", ");

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

@@ -472,6 +472,7 @@ Use the Gorsee docs to pick one clear path before expanding architecture.
 | \`bun run build\` | Production build |
 | \`bun run start\` | Start production server |
 | \`bun run check\` | Type check + safety audit |
+| \`bunx gorsee ai framework --format markdown\` | Export canonical framework context for a new agent session |
 | \`bunx gorsee ai doctor\` | Summarize AI diagnostics and incidents |
 | \`bunx gorsee ai tail --limit 20\` | Inspect recent structured AI events |
 | \`bunx gorsee ai export --format markdown\` | Generate a compact AI context packet |

package/dist-pkg/cli/cmd-upgrade.d.ts

@@ -5,6 +5,10 @@ interface UpgradeFlags {
     report: string | null;
     rewriteImports: boolean;
 }
+export interface UpgradeStepResult {
+    command: string[];
+    exitCode: number;
+}
 export interface UpgradeIssue {
     code: string;
     file: string;
@@ -20,6 +24,14 @@ export interface UpgradeReport {
     upgradeAvailable: boolean;
     issues: UpgradeIssue[];
 }
+export interface UpgradeExecutionResult {
+    report: UpgradeReport;
+    installed: boolean;
+    installResult?: UpgradeStepResult;
+    checkResult?: UpgradeStepResult;
+    changedFiles: string[];
+    reportPath: string;
+}
 export declare function parseUpgradeFlags(args: string[]): UpgradeFlags;
 /** Compare semver strings: -1 (a < b), 0 (equal), 1 (a > b) */
 export declare function compareVersions(a: string, b: string): number;
@@ -32,6 +44,12 @@ export declare function collectUpgradeReport(cwd: string, versions: {
 export declare function writeUpgradeReport(cwd: string, reportPath: string, report: UpgradeReport): Promise<void>;
 export interface UpgradeCommandOptions extends RuntimeOptions {
 }
+export declare function performUpgrade(cwd: string, flags: UpgradeFlags, hooks?: {
+    fetchLatestVersion?: () => Promise<string | null>;
+    getCurrentVersion?: (cwd: string) => Promise<string | null>;
+    runInstallStep?: (cwd: string) => Promise<UpgradeStepResult>;
+    runCheckStep?: (cwd: string) => Promise<UpgradeStepResult>;
+}): Promise<UpgradeExecutionResult | null>;
 export declare function upgradeFramework(args: string[], options?: UpgradeCommandOptions): Promise<void>;
 /** @deprecated Use upgradeFramework() for programmatic access. */
 export declare function runUpgrade(args: string[], options?: UpgradeCommandOptions): Promise<void>;

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

@@ -39,6 +39,7 @@ async function getCurrentVersion(cwd) {
   }
 }
 export const NPM_REGISTRY_URL = "https://registry.npmjs.org/gorsee/latest";
+const DEFAULT_UPGRADE_REPORT_PATH = "docs/upgrade-report.json";
 async function fetchLatestVersion() {
   try {
     const res = await fetch(NPM_REGISTRY_URL);
@@ -124,7 +125,7 @@ export async function collectUpgradeIssues(cwd) {
       issues.push(issue(drift.source === "gorsee/server" ? "UG009" : "UG010", relative(cwd, file), `Domain APIs still come from "${drift.source}" instead of scoped stable subpaths: ${entries}`, drift.source === "gorsee/server" ? `Keep runtime primitives on "gorsee/server" and move domain imports to ${targets}` : `Keep browser runtime primitives on "gorsee/client" and move domain imports to ${targets}`, "info"));
     }
     if (facts.exportedNames.has("loader"))
-      issues.push(issue("UG011", relative(cwd, file), 'Route module still exports "loader" instead of canonical "load"', 'Rename exported "loader" to "load", or run `gorsee upgrade --rewrite-imports` to rewrite obvious cases automatically', "info"));
+      issues.push(issue("UG011", relative(cwd, file), 'Route module still exports "loader" instead of canonical "load"', 'Rename exported "loader" to "load", or run `gorsee upgrade` to rewrite obvious cases automatically', "info"));
   }
   return issues;
 }
@@ -145,87 +146,149 @@ export async function writeUpgradeReport(cwd, reportPath, report) {
   await writeFile(outputPath, JSON.stringify(report, null, 2) + `
 `, "utf-8");
 }
-export async function upgradeFramework(args, options = {}) {
-  const { cwd } = createProjectContext(options), flags = parseUpgradeFlags(args);
-  if (flags.rewriteImports) {
-    const importRewrite = await rewriteCanonicalImportsInProject(cwd), loaderRewrite = await rewriteLegacyLoadersInProject(cwd), changedFiles = [...new Set([...importRewrite.changedFiles, ...loaderRewrite.changedFiles])].sort();
-    if (changedFiles.length > 0) {
-      console.log(`
+async function runProcess(command, cwd) {
+  const exitCode = await Bun.spawn(command, {
+    cwd,
+    stdout: "inherit",
+    stderr: "inherit"
+  }).exited;
+  return { command, exitCode };
+}
+async function runInstallStep(cwd) {
+  return runProcess(["bun", "add", "gorsee@latest"], cwd);
+}
+async function runCheckStep(cwd) {
+  return runProcess(["bun", "run", "check"], cwd);
+}
+async function rewriteUpgradeDrift(cwd) {
+  const importRewrite = await rewriteCanonicalImportsInProject(cwd), loaderRewrite = await rewriteLegacyLoadersInProject(cwd);
+  return [...new Set([...importRewrite.changedFiles, ...loaderRewrite.changedFiles])].sort();
+}
+function printChangedFiles(changedFiles) {
+  if (changedFiles.length > 0) {
+    console.log(`
   Rewrote canonical imports and loader aliases:`);
-      for (const file of changedFiles)
-        console.log(`    - ${file}`);
-    } else
-      console.log(`
-  Canonical import and loader rewrite found no changes.`);
+    for (const file of changedFiles)
+      console.log(`    - ${file}`);
+    return;
   }
-  const current = await getCurrentVersion(cwd);
+  console.log(`
+  Canonical import and loader rewrite found no changes.`);
+}
+export async function performUpgrade(cwd, flags, hooks = {}) {
+  const getCurrentVersionImpl = hooks.getCurrentVersion ?? getCurrentVersion, fetchLatestVersionImpl = hooks.fetchLatestVersion ?? fetchLatestVersion, runInstallStepImpl = hooks.runInstallStep ?? runInstallStep, runCheckStepImpl = hooks.runCheckStep ?? runCheckStep, reportPath = flags.report ?? DEFAULT_UPGRADE_REPORT_PATH, current = await getCurrentVersionImpl(cwd);
   if (!current) {
     console.log(`
   Gorsee.js not found in node_modules. Run: bun add gorsee
 `);
-    return;
+    return null;
   }
   console.log(`
   Current version: v${current}`);
-  const latest = await fetchLatestVersion();
+  const latest = await fetchLatestVersionImpl();
   if (!latest) {
     console.log(`  Could not fetch latest version from npm registry.
 `);
-    return;
+    return null;
   }
-  const report = await collectUpgradeReport(cwd, {
+  console.log(`  Latest version:  v${latest}`);
+  const preflightReport = await collectUpgradeReport(cwd, {
     currentVersion: current,
     latestVersion: latest
   });
-  if (flags.report) {
-    await writeUpgradeReport(cwd, flags.report, report);
-    console.log(`  Upgrade report:  ${flags.report}`);
+  await writeUpgradeReport(cwd, reportPath, preflightReport);
+  console.log(`  Upgrade report:  ${reportPath}`);
+  if (preflightReport.issues.length > 0) {
+    console.log(`
+  Migration audit:`);
+    for (const entry of preflightReport.issues)
+      console.log(`    - [${entry.code}] ${entry.file}: ${entry.message}`);
   }
   if (compareVersions(current, latest) >= 0) {
     console.log(`  Already up to date (v${current})`);
-    if (report.issues.length > 0) {
+    if (flags.check) {
+      console.log();
+      return {
+        report: preflightReport,
+        installed: !1,
+        changedFiles: [],
+        reportPath
+      };
+    }
+    const changedFiles = await rewriteUpgradeDrift(cwd);
+    printChangedFiles(changedFiles);
+    console.log(`
+  Running upgrade verification (bun run check)...`);
+    const checkResult = await runCheckStepImpl(cwd);
+    if (checkResult.exitCode !== 0) {
       console.log(`
-  Migration audit:`);
-      for (const entry of report.issues)
-        console.log(`    - [${entry.code}] ${entry.file}: ${entry.message}`);
+  Post-upgrade verification failed (exit code ${checkResult.exitCode})
+`);
+      process.exit(checkResult.exitCode);
     }
-    console.log();
-    return;
-  }
-  console.log(`  Latest version:  v${latest}`);
-  console.log(`  Upgrade: v${current} -> v${latest}`);
-  if (report.issues.length > 0) {
     console.log(`
-  Migration audit:`);
-    for (const entry of report.issues)
-      console.log(`    - [${entry.code}] ${entry.file}: ${entry.message}`);
+  Upgrade verification passed.
+`);
+    return {
+      report: preflightReport,
+      installed: !1,
+      checkResult,
+      changedFiles,
+      reportPath
+    };
   }
+  console.log(`  Upgrade: v${current} -> v${latest}`);
   if (flags.check) {
     console.log();
-    return;
+    return {
+      report: preflightReport,
+      installed: !1,
+      changedFiles: [],
+      reportPath
+    };
   }
-  if (!flags.force) {
+  console.log(`
+  Installing gorsee@latest...`);
+  const installResult = await runInstallStepImpl(cwd);
+  if (installResult.exitCode !== 0) {
     console.log(`
-  Run with --force to install after reviewing the migration audit.
+  Install failed (exit code ${installResult.exitCode})
 `);
-    return;
+    process.exit(installResult.exitCode);
   }
+  const changedFiles = await rewriteUpgradeDrift(cwd);
+  printChangedFiles(changedFiles);
   console.log(`
-  Installing gorsee@latest...`);
-  const exitCode = await Bun.spawn(["bun", "add", "gorsee@latest"], {
-    cwd,
-    stdout: "inherit",
-    stderr: "inherit"
-  }).exited;
-  if (exitCode !== 0) {
+  Running upgrade verification (bun run check)...`);
+  const checkResult = await runCheckStepImpl(cwd);
+  if (checkResult.exitCode !== 0) {
     console.log(`
-  Install failed (exit code ${exitCode})
+  Upgrade verification failed (exit code ${checkResult.exitCode})
 `);
-    process.exit(exitCode);
+    process.exit(checkResult.exitCode);
   }
+  const installedVersion = await getCurrentVersionImpl(cwd), finalReport = await collectUpgradeReport(cwd, {
+    currentVersion: installedVersion,
+    latestVersion: latest
+  });
+  await writeUpgradeReport(cwd, reportPath, finalReport);
   console.log(`
-  Upgraded successfully to v${latest}
+  Upgraded successfully to v${installedVersion ?? latest}
 `);
+  return {
+    report: finalReport,
+    installed: !0,
+    installResult,
+    checkResult,
+    changedFiles,
+    reportPath
+  };
+}
+export async function upgradeFramework(args, options = {}) {
+  const { cwd } = createProjectContext(options), flags = parseUpgradeFlags(args);
+  if (flags.force)
+    console.log("\n  Note: --force is no longer required. `gorsee upgrade` installs by default unless --check is used.");
+  await performUpgrade(cwd, flags);
 }
 export async function runUpgrade(args, options = {}) {
   return upgradeFramework(args, options);

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

@@ -357,6 +357,7 @@ gorsee build        Production build
 gorsee check        Type + safety + structure check
 gorsee check --rewrite-imports --rewrite-loaders
                     Normalize canonical imports and loader aliases before auditing
+gorsee ai framework Export canonical framework context for cold-start agents
 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
@@ -367,7 +368,8 @@ gorsee migrate      Run database migrations
 gorsee generate X   Generate CRUD for entity X
 \`\`\`
 
-- For migration cleanup, prefer \`gorsee upgrade --rewrite-imports --check --report docs/upgrade-report.json\`.
+- 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.
 
 ## Error Codes
 

package/dist-pkg/cli/index.js

@@ -11,7 +11,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: tail, doctor, bridge, mcp",
+  ai: "AI-first tooling: framework, tail, doctor, 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.7",
+  "version": "0.2.8",
   "description": "AI-first reactive full-stack TypeScript framework for deterministic human and agent collaboration",
   "type": "module",
   "packageManager": "bun@1.3.9",