gorsee 0.2.15 → 0.2.17

package/README.md

@@ -21,6 +21,13 @@ Read the strategic docs:
 - [Security Model](./docs/SECURITY_MODEL.md)
 - [Top-Tier Roadmap](./docs/TOP_TIER_ROADMAP.md)
 - [Top-Tier Competition Plan](./docs/TOP_TIER_COMPETITION_PLAN.md)
+- [Competition Closure Plan](./docs/COMPETITION_CLOSURE_PLAN.md)
+- [External Proof Intake](./docs/EXTERNAL_PROOF_INTAKE.md)
+- [External Proof Claims](./docs/EXTERNAL_PROOF_CLAIMS.json)
+- [External Proof Execution](./docs/EXTERNAL_PROOF_EXECUTION.md)
+- [External Proof Outreach](./docs/EXTERNAL_PROOF_OUTREACH.json)
+- [External Proof Pipeline](./docs/EXTERNAL_PROOF_PIPELINE.json)
+- [External Proof Review](./docs/EXTERNAL_PROOF_REVIEW.md)
 - [Canonical Language Plan](./docs/CANONICAL_LANGUAGE_PLAN.md)
 - [Canonical Recipes](./docs/CANONICAL_RECIPES.md)
 - [Canonical Examples](./examples/README.md)
@@ -31,6 +38,7 @@ Read the strategic docs:
 - [Reactive Hydration](./docs/REACTIVE_HYDRATION.md)
 - [Reactive Debugging](./docs/REACTIVE_DEBUGGING.md)
 - [Reactive Measurement Gaps](./docs/REACTIVE_MEASUREMENT_GAPS.md)
+- [Reactive Evidence Summary](./docs/REACTIVE_EVIDENCE_SUMMARY.md)
 - [Benchmark Policy](./docs/BENCHMARK_POLICY.md)
 - [Benchmark Contract](./docs/BENCHMARK_CONTRACT.json)
 - [Benchmark Methodology](./docs/BENCHMARK_METHODOLOGY.md)
@@ -50,6 +58,9 @@ Read the strategic docs:
 - [AI Workflows](./docs/AI_WORKFLOWS.md)
 - [AI Artifact Contract](./docs/AI_ARTIFACT_CONTRACT.md)
 - [CLI Contract](./docs/CLI_CONTRACT.json)
+- [Product Surface Audit](./docs/PRODUCT_SURFACE_AUDIT.md)
+- [AI Integration Contract](./docs/AI_INTEGRATION_CONTRACT.json)
+- [Third-Party Editor Integrations](./docs/THIRD_PARTY_EDITOR_INTEGRATIONS.md)
 - [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)
@@ -60,6 +71,8 @@ Read the strategic docs:
 - [Starter Onboarding](./docs/STARTER_ONBOARDING.md)
 - [Market-Ready Proof](./docs/MARKET_READY_PROOF.md)
 - [Adoption Proof Manifest](./docs/ADOPTION_PROOF_MANIFEST.json)
+- [Competition Backlog](./docs/COMPETITION_BACKLOG.json)
+- [External Proof Registry](./docs/EXTERNAL_PROOF_REGISTRY.json)
 - [Release Contract](./docs/RELEASE_CONTRACT.json)
 - [Migration Guide](./docs/MIGRATION_GUIDE.md)
 - [Upgrade Playbook](./docs/UPGRADE_PLAYBOOK.md)
@@ -68,6 +81,7 @@ Read the strategic docs:
 - [Auth / Cache / Data Paths](./docs/AUTH_CACHE_DATA_PATHS.md)
 - [Recipe Boundaries](./docs/RECIPE_BOUNDARIES.md)
 - [Workspace Adoption](./docs/WORKSPACE_ADOPTION.md)
+- [Node and npm Adoption](./docs/NODE_NPM_ADOPTION.md)
 - [Downstream Testing](./docs/DOWNSTREAM_TESTING.md)
 - [Test Coverage Audit](./docs/TEST_COVERAGE_AUDIT.md)
 - [Team Failures](./docs/TEAM_FAILURES.md)
@@ -148,6 +162,12 @@ For agent cold-start context:
 bunx gorsee ai framework --format markdown
 ```
 
+For the first real external proof draft:
+
+```bash
+npm run external-proof:scaffold -- --type reference --id first-public-reference
+```
+
 ## Why Gorsee
 
 Most modern frameworks optimize for flexibility, historical compatibility, or ecosystem breadth.
@@ -365,6 +385,7 @@ AI bootstrap and handoff:
 - [Reactive Hydration](./docs/REACTIVE_HYDRATION.md)
 - [Reactive Debugging](./docs/REACTIVE_DEBUGGING.md)
 - [Reactive Measurement Gaps](./docs/REACTIVE_MEASUREMENT_GAPS.md)
+- [Reactive Measurement Contract](./docs/REACTIVE_MEASUREMENT_CONTRACT.json)
 - [Benchmark Policy](./docs/BENCHMARK_POLICY.md)
 - [Benchmark Methodology](./docs/BENCHMARK_METHODOLOGY.md)
 - [SSR Benchmark Proof](./docs/SSR_BENCHMARK_PROOF.md)

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

@@ -29,6 +29,18 @@ export interface AIFrameworkPacket {
         serverImports: string;
         routeExample: string;
     };
+    cli: {
+        topLevelCommands: Array<{
+            command: string;
+            stability: string;
+            purpose: string;
+        }>;
+        aiSubcommands: Array<{
+            command: string;
+            stability: string;
+            purpose: string;
+        }>;
+    };
     aiCommands: Array<{
         command: string;
         purpose: string;

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

@@ -16,14 +16,29 @@ const LOCAL_DOCS = [
   { 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/PRODUCT_SURFACE_AUDIT.md", purpose: "\u041A\u0440\u0430\u0442\u043A\u0438\u0439 \u0438\u043D\u0434\u0435\u043A\u0441 \u0437\u0430\u043A\u0440\u044B\u0442\u044B\u0445 \u0438 \u0447\u0430\u0441\u0442\u0438\u0447\u043D\u043E \u0437\u0440\u0435\u043B\u044B\u0445 product surfaces" },
   { path: "docs/CLI_CONTRACT.json", purpose: "Machine-readable CLI command matrix \u0438 AI subcommand surface" },
+  { path: "docs/AI_INTEGRATION_CONTRACT.json", purpose: "Machine-readable local editor/tool integration contract for AI artifacts" },
+  { path: "docs/THIRD_PARTY_EDITOR_INTEGRATIONS.md", purpose: "Artifact-first guidance for VS Code/Cursor and other editor consumers" },
   { 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/REACTIVE_MEASUREMENT_CONTRACT.json", purpose: "Machine-readable reactive benchmark backlog and remaining evidence gaps" },
+  { path: "docs/REACTIVE_EVIDENCE_SUMMARY.md", purpose: "Release-facing summary of promoted realistic reactive benchmark metrics" },
+  { path: "docs/COMPETITION_CLOSURE_PLAN.md", purpose: "\u041E\u043F\u0435\u0440\u0430\u0442\u043E\u0440\u0441\u043A\u0438\u0439 \u043F\u043B\u0430\u043D \u0437\u0430\u043A\u0440\u044B\u0442\u0438\u044F remaining external competition gaps" },
+  { path: "docs/COMPETITION_BACKLOG.json", purpose: "Machine-readable backlog \u0434\u043B\u044F remaining external competition work" },
+  { path: "docs/EXTERNAL_PROOF_CLAIMS.json", purpose: "Machine-readable normalized claim ids for future external proof entries" },
+  { path: "docs/EXTERNAL_PROOF_EXECUTION.md", purpose: "\u041E\u043F\u0435\u0440\u0430\u0442\u043E\u0440\u0441\u043A\u0438\u0439 playbook \u0434\u043B\u044F \u043F\u043E\u0438\u0441\u043A\u0430 \u0438 \u043A\u0432\u0430\u043B\u0438\u0444\u0438\u043A\u0430\u0446\u0438\u0438 \u043F\u0435\u0440\u0432\u043E\u0433\u043E accepted external proof" },
+  { path: "docs/EXTERNAL_PROOF_OUTREACH.json", purpose: "Machine-readable sourcing and outreach queue for external proof leads" },
+  { path: "docs/EXTERNAL_PROOF_INTAKE.md", purpose: "\u041A\u0430\u043D\u043E\u043D\u0438\u0447\u0435\u0441\u043A\u0438\u0439 intake workflow \u0434\u043B\u044F \u0432\u043D\u0435\u0448\u043D\u0438\u0445 migration/reference \u043A\u0435\u0439\u0441\u043E\u0432" },
+  { path: "docs/EXTERNAL_PROOF_PIPELINE.json", purpose: "Pending queue for external proof candidates before acceptance" },
+  { path: "docs/EXTERNAL_PROOF_REVIEW.md", purpose: "Review workflow \u0434\u043B\u044F \u043F\u0435\u0440\u0435\u0432\u043E\u0434\u0430 external proof \u0438\u0437 pending \u0432 accepted" },
+  { path: "docs/EXTERNAL_PROOF_REGISTRY.json", purpose: "Accepted registry for public external proof entries" },
   { 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/NODE_NPM_ADOPTION.md", purpose: "Explicit Bun-first versus Node/npm adoption framing" },
   { 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" },
@@ -69,12 +84,31 @@ async function resolveFrameworkVersion() {
   }
   return;
 }
+function normalizeCLICommands(value) {
+  if (!Array.isArray(value))
+    return [];
+  return value.flatMap((entry) => {
+    if (!entry || typeof entry !== "object")
+      return [];
+    const command = typeof entry.command === "string" ? entry.command : void 0, stability = typeof entry.stability === "string" ? entry.stability : void 0, purpose = typeof entry.purpose === "string" ? entry.purpose : void 0;
+    if (!command || !stability || !purpose)
+      return [];
+    return [{ command, stability, purpose }];
+  });
+}
 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 resolveCLIContract() {
+  const contract = await readJSON(join(import.meta.dir, "..", "..", "docs", "CLI_CONTRACT.json"));
+  return {
+    topLevelCommands: normalizeCLICommands(contract?.topLevelCommands),
+    aiSubcommands: normalizeCLICommands(contract?.aiSubcommands)
+  };
+}
 async function collectDocRefs(cwd, refs) {
   const result = [];
   for (const ref of refs)
@@ -86,7 +120,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), rules = await resolveAIRulesFile(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), rules = await resolveAIRulesFile(cwd), cliContract = await resolveCLIContract();
   return {
     kind: "gorsee.framework",
     schemaVersion: 1,
@@ -131,6 +165,7 @@ export async function buildAIFrameworkPacket(cwd) {
       serverImports: 'import { middleware, type Context } from "gorsee/server"',
       routeExample: "routes/users/[id].tsx -> /users/:id"
     },
+    cli: cliContract,
     aiCommands: AI_COMMANDS,
     operationModes: AI_OPERATION_MODES,
     transport: AI_TRANSPORT_CONTRACT,
@@ -146,7 +181,18 @@ export async function buildAIFrameworkPacket(cwd) {
       "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/PRODUCT_SURFACE_AUDIT.md for the current closed-vs-partial maturity snapshot before making broad product claims.",
+      "Read docs/NODE_NPM_ADOPTION.md before making package-manager or runtime adoption claims.",
+      "Read docs/AI_INTEGRATION_CONTRACT.json when editor tooling, MCP, bridge, or session-handoff integration boundaries matter.",
+      "Read docs/THIRD_PARTY_EDITOR_INTEGRATIONS.md when wiring editor tooling beyond the packaged VS Code/Cursor extension.",
       "Read docs/SUPPORT_MATRIX.md when runtime, packaging, or deploy assumptions matter.",
+      "Read docs/REACTIVE_MEASUREMENT_CONTRACT.json before making broad benchmark or reactivity evidence claims.",
+      "Read docs/REACTIVE_EVIDENCE_SUMMARY.md for release-facing reactive evidence and docs/REACTIVE_MEASUREMENT_GAPS.md for the broader remaining backlog.",
+      "Read docs/COMPETITION_CLOSURE_PLAN.md and docs/COMPETITION_BACKLOG.json before making market-competition or adoption claims.",
+      "Read docs/EXTERNAL_PROOF_CLAIMS.json before writing or reviewing validatedClaims for external proof candidates.",
+      "Read docs/EXTERNAL_PROOF_EXECUTION.md and docs/EXTERNAL_PROOF_OUTREACH.json before sourcing or qualifying external proof leads.",
+      "Use npm run external-proof:scaffold -- --type migration|reference --id <candidate-id> when a real external proof lead needs a local draft bundle.",
+      "Use the external-proof intake/review/registry docs for real public migration stories and external references; do not treat pending entries as accepted proof.",
       "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.",
@@ -198,6 +244,14 @@ export function renderAIFrameworkMarkdown(packet) {
     "",
     ...packet.aiCommands.map((entry) => `- \`${entry.command}\` -- ${entry.purpose}`),
     "",
+    "## CLI Commands",
+    "",
+    ...packet.cli.topLevelCommands.map((entry) => `- \`${entry.command}\` [${entry.stability}] -- ${entry.purpose}`),
+    "",
+    "## CLI AI Subcommands",
+    "",
+    ...packet.cli.aiSubcommands.map((entry) => `- \`${entry.command}\` [${entry.stability}] -- ${entry.purpose}`),
+    "",
     "## AI Operation Modes",
     "",
     ...packet.operationModes.map((entry) => `- \`${entry.mode}\` -- ${entry.purpose}`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gorsee",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "AI-first reactive full-stack TypeScript framework for deterministic human and agent collaboration",
   "type": "module",
   "packageManager": "bun@1.3.9",
@@ -76,6 +76,8 @@
     "api:policy": "node scripts/api-stability-check.mjs",
     "cli:policy": "node scripts/cli-contract-check.mjs",
     "adoption:policy": "node scripts/adoption-proof-check.mjs",
+    "competition:policy": "node scripts/competition-backlog-check.mjs",
+    "external-proof:scaffold": "node scripts/external-proof-scaffold.mjs",
     "ai:policy": "node scripts/ai-policy-check.mjs",
     "dx:policy": "node scripts/dx-policy-check.mjs",
     "maturity:policy": "node scripts/maturity-policy-check.mjs",
@@ -106,7 +108,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 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",
+    "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 competition: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",