gorsee 0.2.4 → 0.2.5

package/README.md

@@ -1,267 +1,315 @@
 # Gorsee.js
 
-Full-stack TypeScript framework with features no one else has.
+AI-first reactive full-stack TypeScript framework for deterministic collaboration between humans and coding agents.
+
+Gorsee is not a pet project, not a research toy, and not a bundle of optional recipes. It is a product-grade framework with strict runtime contracts, built-in security boundaries, fine-grained reactivity, and AI-native developer tooling.
+
+## Product Direction
+
+Gorsee is built around four non-negotiable product goals:
+
+- AI-first development: the framework must be predictable for coding agents, not only ergonomic for humans.
+- Deterministic architecture: one clear way beats many inconsistent ways.
+- Reactive execution: fine-grained reactivity, islands, and minimal client JavaScript over VDOM-heavy legacy models.
+- Built-in guarantees: auth, request policy, cache boundaries, diagnostics, and deploy contracts are framework properties, not scattered ecosystem recipes.
+
+Read the strategic docs:
+
+- [Product Vision](./docs/PRODUCT_VISION.md)
+- [Framework Doctrine](./docs/FRAMEWORK_DOCTRINE.md)
+- [Security Model](./docs/SECURITY_MODEL.md)
+- [Top-Tier Roadmap](./docs/TOP_TIER_ROADMAP.md)
+- [Canonical Language Plan](./docs/CANONICAL_LANGUAGE_PLAN.md)
+- [Canonical Recipes](./docs/CANONICAL_RECIPES.md)
+- [Canonical Examples](./examples/README.md)
+- [Examples Policy](./docs/EXAMPLES_POLICY.md)
+- [Reactive Runtime](./docs/REACTIVE_RUNTIME.md)
+- [Reactive Benchmarks](./docs/REACTIVE_BENCHMARKS.md)
+- [Reactive Patterns](./docs/REACTIVE_PATTERNS.md)
+- [Reactive Hydration](./docs/REACTIVE_HYDRATION.md)
+- [Reactive Debugging](./docs/REACTIVE_DEBUGGING.md)
+- [Reactive Measurement Gaps](./docs/REACTIVE_MEASUREMENT_GAPS.md)
+- [Benchmark Policy](./docs/BENCHMARK_POLICY.md)
+- [Benchmark Methodology](./docs/BENCHMARK_METHODOLOGY.md)
+- [SSR Benchmark Proof](./docs/SSR_BENCHMARK_PROOF.md)
+- [DOM Benchmark Proof](./docs/DOM_BENCHMARK_PROOF.md)
+- [Benchmark Artifacts](./docs/BENCHMARK_ARTIFACTS.md)
+- [Benchmark Release Discipline](./docs/BENCHMARK_RELEASE_DISCIPLINE.md)
+- [Build Diagnostics](./docs/BUILD_DIAGNOSTICS.md)
+- [Runtime Failures](./docs/RUNTIME_FAILURES.md)
+- [Cache Invalidation](./docs/CACHE_INVALIDATION.md)
+- [Streaming and Hydration Failures](./docs/STREAMING_HYDRATION_FAILURES.md)
+- [Runtime Triage](./docs/RUNTIME_TRIAGE.md)
+- [Starter Failures](./docs/STARTER_FAILURES.md)
+- [AI Workflows](./docs/AI_WORKFLOWS.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)
+- [AI Tool Builders](./docs/AI_TOOL_BUILDERS.md)
+- [AI Surface Stability](./docs/AI_SURFACE_STABILITY.md)
+- [AI Session Packs](./docs/AI_SESSION_PACKS.md)
+- [AI Debugging Workflows](./docs/AI_DEBUGGING_WORKFLOWS.md)
+- [Starter Onboarding](./docs/STARTER_ONBOARDING.md)
+- [Market-Ready Proof](./docs/MARKET_READY_PROOF.md)
+- [Migration Guide](./docs/MIGRATION_GUIDE.md)
+- [Upgrade Playbook](./docs/UPGRADE_PLAYBOOK.md)
+- [Deploy Target Guide](./docs/DEPLOY_TARGET_GUIDE.md)
+- [First Production Rollout](./docs/FIRST_PRODUCTION_ROLLOUT.md)
+- [Auth / Cache / Data Paths](./docs/AUTH_CACHE_DATA_PATHS.md)
+- [Recipe Boundaries](./docs/RECIPE_BOUNDARIES.md)
+- [Workspace Adoption](./docs/WORKSPACE_ADOPTION.md)
+- [Downstream Testing](./docs/DOWNSTREAM_TESTING.md)
+- [Team Failures](./docs/TEAM_FAILURES.md)
+- [Maturity Policy](./docs/MATURITY_POLICY.md)
+- [Dependency Policy](./docs/DEPENDENCY_POLICY.md)
+- [Compatibility Guardrails](./docs/COMPATIBILITY_GUARDRAILS.md)
+- [Ambiguity Policy](./docs/AMBIGUITY_POLICY.md)
+- [DX Feedback Loop](./docs/DX_FEEDBACK_LOOP.md)
+- [Evidence Policy](./docs/EVIDENCE_POLICY.md)
+- [Roadmap Completion Policy](./docs/ROADMAP_COMPLETION_POLICY.md)
 
 ## Quick Start
 
 ```bash
-bunx gorsee create my-app
+bunx gorsee create my-app --template secure-saas
 cd my-app
 bun install
 bun run dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000).
+Alternative bootstrap paths:
 
-## Why Gorsee.js?
+```bash
+npx create-gorsee my-app
+npm create gorsee@latest my-app
+```
 
-| Feature | Gorsee.js | Next.js | Nuxt | SvelteKit |
-|---------|:---------:|:-------:|:----:|:---------:|
-| Islands (partial hydration) | ✅ | ❌ | ❌ | ❌ |
-| Reactive WebSocket signals | ✅ | ❌ | ❌ | ❌ |
-| Optimistic mutations + rollback | ✅ | ❌ | ❌ | ❌ |
-| Server-Sent Events (reactive) | ✅ | manual | manual | manual |
-| Route-level cache (SWR) | ✅ | ISR only | partial | ❌ |
-| Built-in auth (HMAC sessions) | ✅ | manual | manual | manual |
-| Guards (declarative ACL) | ✅ | manual | partial | ❌ |
-| Middleware pipe/compose | ✅ | ❌ | ❌ | ❌ |
-| Validated forms (client+server) | ✅ | ❌ | ❌ | ❌ |
-| Type-safe routes (generated) | ✅ | experimental | partial | ❌ |
-| Branded types (SafeSQL/HTML/URL) | ✅ | ❌ | ❌ | ❌ |
+Open [http://localhost:3000](http://localhost:3000).
 
-**Zero-cost architecture** — every feature is a separate module. Don't use it? It's not in your bundle. Base client bundle: ~2-3 KB per route.
+## Why Gorsee
 
-## Features
+Most modern frameworks optimize for flexibility, historical compatibility, or ecosystem breadth.
+Gorsee optimizes for deterministic delivery by humans and AI agents working in the same codebase.
 
-### Islands — partial hydration
+What that means in practice:
 
-```tsx
-import { island, createSignal } from "gorsee/client"
+- strict client/server import boundaries
+- explicit request classification and security policy
+- fail-closed production origin model
+- small reactive runtime without VDOM baggage
+- route-scoped hydration through islands
+- optimized image rendering with remote allowlists, srcset generation, and format-aware loaders
+- structured form actions with field/form error handling and typed coercion
+- explicit data queries and mutations with keyed invalidation over the reactive runtime
+- typed route builders with params, query strings, and reusable route definitions
+- locale negotiation, fallback dictionaries, Intl formatting, and locale-aware route helpers
+- 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
+- CLI enforcement through `gorsee check`, release gates, deploy contracts, and policy docs
 
-// Only THIS component gets JavaScript. Rest of the page = zero JS.
-export default island(function LikeButton({ postId }) {
-  const [count, setCount] = createSignal(0)
-  return <button on:click={() => setCount(c => c + 1)}>Like {count()}</button>
-})
-```
+## Core Ideas
 
-### Reactive WebSocket
+### AI-first development
 
-```tsx
-import { createLive } from "gorsee/client"
-
-function StockPrice() {
-  const { value: price, connected } = createLive({
-    url: "wss://api.example.com/btc",
-    initialValue: 0,
-    reconnect: true,  // auto-reconnect with exponential backoff
-  })
-  return <span>{connected() ? price() : "..."}</span>
-}
-```
+The framework must be easy for an agent to reason about:
 
-### Optimistic Mutations
+- deterministic project layout
+- narrow public surfaces
+- explicit runtime contracts
+- strong defaults over open-ended composition
+- observability artifacts that can be consumed by tools and models
 
-```tsx
-import { createSignal, createMutation } from "gorsee/client"
+### Reactive-first runtime
 
-const [todos, setTodos] = createSignal(["Buy milk"])
-const addTodo = createMutation({
-  mutationFn: async (text) => fetch("/api/todos", { method: "POST", body: text }),
-})
+Gorsee follows a fine-grained reactive model closer to Solid than to React:
 
-// UI updates instantly. Rolls back automatically on server error.
-await addTodo.optimistic(todos, setTodos, (list, text) => [...list, text], "New todo")
-```
-
-### Built-in Auth
+- signals instead of VDOM diffing
+- direct SSR rendering
+- explicit hydration model
+- islands for minimal client JavaScript
 
 ```tsx
-import { createAuth } from "gorsee/server"
-
-const auth = createAuth({ secret: process.env.SESSION_SECRET })
+import { island, createSignal } from "gorsee/client"
 
-// In middleware:
-export default auth.middleware      // parses session
-export default auth.requireAuth    // redirects to /login if not authenticated
+export default island(function LikeButton() {
+  const [count, setCount] = createSignal(0)
+  return <button on:click={() => setCount((value) => value + 1)}>Like {count()}</button>
+})
 ```
 
-### File-Based Routing
+### Built-in guarantees
 
-```
-routes/
-  index.tsx           → /
-  about.tsx           → /about
-  users/[id].tsx      → /users/:id
-  blog/[...slug].tsx  → /blog/*
-  (admin)/
-    dashboard.tsx     → /dashboard  (group — no /admin prefix)
-  _layout.tsx         → wraps all pages
-  _middleware.ts      → runs before all routes
-  _error.tsx          → error boundary
-  _loading.tsx        → loading state
-  404.tsx             → custom 404
-```
+Capabilities are not bolt-on features. They are part of the framework contract:
 
-### Middleware Pipe
+- auth and session stores
+- request policy and security validation
+- route cache with explicit intent
+- type-safe route generation
+- validated forms
+- deploy adapters with provider assumptions
+- AI observability and bridge tooling
 
-```tsx
-import { pipe, forPaths, forMethods } from "gorsee/server"
-import { cors } from "gorsee/security"
+## Canonical Route Grammar
 
-export default pipe(
-  forPaths(["/api"], cors({ origin: "https://app.com" })),
-  forMethods(["POST"], rateLimit(100, "1m")),
-  auth.middleware,
-)
-```
+For greenfield route modules, prefer this structure:
 
-## CLI Commands
+- `default export` for page UI
+- `load` for route data reads
+- `action` for page-bound mutations
+- `cache` for declarative cache policy
+- `middleware` for cross-cutting request policy
+- `GET` / `POST` / other method handlers for raw HTTP endpoints
+- route contracts from `gorsee/routes` for typed links and navigation
 
-| Command | Description |
-|---------|-------------|
-| `gorsee create <name>` | Scaffold new project |
-| `gorsee dev` | Dev server with HMR |
-| `gorsee build` | Production build |
-| `gorsee start` | Production server |
-| `gorsee check` | Type check + safety audit |
-| `gorsee routes` | Show route table |
-| `gorsee generate <entity>` | CRUD scaffold |
-| `gorsee typegen` | Generate typed routes |
-| `gorsee migrate` | Run DB migrations |
+Compatibility note: `loader` remains supported as a migration alias, but canonical route modules should use `load`.
 
-## Recommended Imports
+## Public Entrypoints
 
 ```tsx
-// Route components, islands, navigation, forms, browser-safe reactivity
 import { createSignal, island, Link, Head } from "gorsee/client"
-
-// Middleware, loaders, auth, db, security, logging
-import { createAuth, createDB, cors, log } from "gorsee/server"
+import { createAuth } from "gorsee/auth"
+import { createDB } from "gorsee/db"
+import { cors } from "gorsee/security"
+import { log } from "gorsee/log"
+import { defineForm, useFormAction } from "gorsee/forms"
+import { createTypedRoute } from "gorsee/routes"
 ```
 
-- Use `gorsee/client` for route components and anything that must stay browser-safe.
-- Use `gorsee/server` for loaders, middleware, API routes, auth, db, security, env, and logging.
-- Keep root `gorsee` only for backward compatibility. New code should not depend on it.
-- If you need explicit legacy semantics during migration, use `gorsee/compat`.
-
-## Adapter Utilities
-
 ```tsx
-import {
-  createAuth,
-  createMemorySessionStore,
-  createNamespacedSessionStore,
-  createRedisSessionStore,
-  createSQLiteSessionStore,
-  createMemoryCacheStore,
-  createNamespacedCacheStore,
-  createRedisCacheStore,
-  createSQLiteCacheStore,
-  createMemoryRPCRegistry,
-  createScopedRPCRegistry,
-} from "gorsee/server"
-
-const sharedSessions = createMemorySessionStore()
-const tenantSessions = createNamespacedSessionStore(sharedSessions, "tenant-a")
-const auth = createAuth({ secret: process.env.SESSION_SECRET!, store: tenantSessions })
-
-const sharedCache = createMemoryCacheStore()
-const tenantCache = createNamespacedCacheStore(sharedCache, "tenant-a")
-
-const sessionStore = createSQLiteSessionStore("./data/auth.sqlite")
-const cacheStore = createSQLiteCacheStore("./data/cache.sqlite")
-
-const redisSessionStore = createRedisSessionStore(redisClient, { prefix: "gorsee:sessions" })
-const redisCacheStore = createRedisCacheStore(redisClient, { prefix: "gorsee:cache" })
-
-const sharedRPC = createMemoryRPCRegistry()
-const tenantRPC = createScopedRPCRegistry(sharedRPC, "tenant-a")
+const userRoute = createTypedRoute("/users/[id]")
+
+<Link href={userRoute} params={{ id: "42" }}>Profile</Link>
 ```
 
-- `createNamespacedSessionStore` isolates auth sessions over one shared backing store.
-- `createNamespacedCacheStore` isolates route cache keys per app, tenant, or test worker.
-- `createSQLiteSessionStore` and `createSQLiteCacheStore` provide persistent local adapters without adding external infrastructure.
-- `createSQLiteSessionStore` prunes expired rows automatically on hot paths and also exposes `deleteExpired()` for explicit maintenance.
-- `createSQLiteCacheStore` supports retention policy via `maxEntryAgeMs` and also exposes `deleteExpired()` for explicit cache pruning.
-- `createRedisSessionStore` and `createRedisCacheStore` work with any client that supports `get/set/del/keys`, so you can plug in `redis` or `ioredis` without framework lock-in.
-- RPC handlers remain intentionally process-local. The stable extension point is injected request-time registry resolution, not pretending closures can live in Redis.
-- `createScopedRPCRegistry` isolates RPC registrations without forking the entire server runtime.
+- Use `gorsee/client` for route components and browser-safe APIs.
+- Use `gorsee/server` for `load`, `action`, middleware, API routes, cache, request policy, and server runtime orchestration.
+- Prefer scoped stable subpaths such as `gorsee/auth`, `gorsee/db`, `gorsee/security`, `gorsee/ai`, `gorsee/forms`, `gorsee/routes`, `gorsee/i18n`, and `gorsee/content` when the concern is already clear.
+- Keep root `gorsee` only for compatibility. New code should not depend on it.
+- Use `gorsee/compat` only for explicit legacy migration semantics.
+- `Link` prefetch is explicit: `prefetch={true}` is eager, `prefetch="hover"` is pointer/focus triggered, and `prefetch="viewport"` is IntersectionObserver-driven. Links without `prefetch` do not prefetch implicitly.
 
-## Redis Recipes
+## Package Distribution
 
-### node-redis
+- workspace development stays Bun-first and source-first
+- production build output includes `dist/prod.js` for Bun, `dist/prod-node.js` for Node, and matching Bun/Node server-handler entries for adapter runtimes
+- process deploy generators keep Bun-first defaults while also supporting explicit Node runtime profiles for Docker and Fly
+- published packages are normalized at `npm pack` / publish time to compiled `dist-pkg/*.js` and `dist-pkg/*.d.ts` artifacts
+- packed `gorsee` validates CLI install, starter creation, `check`, `typegen`, `docs`, `build`, and deploy generator paths before release
+- published runtime dependencies are treated as product surface and must stay pinned exactly
 
-```tsx
-import { createClient } from "redis"
-import {
-  createAuth,
-  createRedisSessionStore,
-  createRedisCacheStore,
-  createNodeRedisLikeClient,
-  routeCache,
-} from "gorsee/server"
-
-const redis = createClient({ url: process.env.REDIS_URL })
-await redis.connect()
-const redisClient = createNodeRedisLikeClient(redis)
-
-const auth = createAuth({
-  secret: process.env.SESSION_SECRET!,
-  store: createRedisSessionStore(redisClient, { prefix: "app:sessions" }),
-})
+## Starter Templates
 
-export const cache = routeCache({
-  maxAge: 60,
-  staleWhileRevalidate: 300,
-  store: createRedisCacheStore(redisClient, {
-    prefix: "app:cache",
-    maxEntryAgeMs: 360_000,
-  }),
-})
-```
+`gorsee create` ships with one generic baseline and four first-party product starters:
 
-### ioredis
+- `basic` for the minimal canonical scaffold
+- `secure-saas` for authenticated SaaS apps with protected route groups
+- `content-site` for public content and marketing sites
+- `agent-aware-ops` for internal tools with AI-first workflows enabled
+- `workspace-monorepo` for workspace layouts with one app package and one shared package
 
-```tsx
-import Redis from "ioredis"
-import {
-  createAuth,
-  createRedisSessionStore,
-  createRedisCacheStore,
-  createIORedisLikeClient,
-  routeCache,
-} from "gorsee/server"
-
-const redis = new Redis(process.env.REDIS_URL!)
-const redisClient = createIORedisLikeClient(redis)
-
-const auth = createAuth({
-  secret: process.env.SESSION_SECRET!,
-  store: createRedisSessionStore(redisClient, { prefix: "app:sessions" }),
-})
+Examples:
 
-export const cache = routeCache({
-  maxAge: 60,
-  staleWhileRevalidate: 300,
-  store: createRedisCacheStore(redisClient, {
-    prefix: "app:cache",
-    maxEntryAgeMs: 360_000,
-  }),
-})
+```bash
+bunx gorsee create my-saas --template secure-saas
+bunx gorsee create my-site --template content-site
+bunx gorsee create my-ops --template agent-aware-ops
+bunx gorsee create my-workspace --template workspace-monorepo
+npx create-gorsee my-app
+npm create gorsee@latest my-app
 ```
 
-### Notes
-
-- For multi-instance deployments, keep the same Redis prefixes across all app replicas.
-- Session expiry is enforced by store TTL and validated again by `createAuth()`.
-- Cache retention is controlled by `maxEntryAgeMs`; `routeCache()` still decides HIT/STALE/MISS at request time.
-- `createNodeRedisLikeClient()` and `createIORedisLikeClient()` let you pass real Redis SDK clients without writing framework-specific glue.
-
-## Requirements
+## CLI
 
-- [Bun](https://bun.sh) >= 1.0
-
-## License
-
-MIT
+| Command | Description |
+|---------|-------------|
+| `gorsee create <name> [--template <name>]` | Scaffold a new project from the canonical starter set |
+| `gorsee dev` | Start development server with HMR |
+| `gorsee build` | Build client and server output |
+| `gorsee start` | Start production runtime |
+| `gorsee start --runtime node` | Start the built Node production 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 |
+| `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 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 |
+
+Runtime debugging surface:
+
+- `createRuntimeDevtoolsSnapshot()` for a versioned inspector snapshot spanning router, hydration, and reactive diagnostics
+- `renderRuntimeDevtoolsHTML()` / `renderRuntimeDevtoolsOverlay()` for a human-readable devtools view built from the same canonical artifacts
+
+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.
+
+## Product Standards
+
+- Production behavior must remain deterministic across dev and prod.
+- Security-sensitive behavior must be explicit, testable, and fail-closed.
+- New APIs must strengthen the framework contract, not widen ambiguity.
+- Performance claims must be backed by benchmarks and reproducible examples.
+- Gorsee is developed as a mature product. Regressions in policy, runtime contracts, or release discipline are product failures.
+
+## Additional References
+
+- [API Stability Policy](./docs/API_STABILITY.md)
+- [AI Artifact Contract](./docs/AI_ARTIFACT_CONTRACT.md)
+- [Reactive Runtime](./docs/REACTIVE_RUNTIME.md)
+- [Reactive Benchmarks](./docs/REACTIVE_BENCHMARKS.md)
+- [Reactive Patterns](./docs/REACTIVE_PATTERNS.md)
+- [Reactive Hydration](./docs/REACTIVE_HYDRATION.md)
+- [Reactive Debugging](./docs/REACTIVE_DEBUGGING.md)
+- [Reactive Measurement Gaps](./docs/REACTIVE_MEASUREMENT_GAPS.md)
+- [Benchmark Policy](./docs/BENCHMARK_POLICY.md)
+- [Benchmark Methodology](./docs/BENCHMARK_METHODOLOGY.md)
+- [SSR Benchmark Proof](./docs/SSR_BENCHMARK_PROOF.md)
+- [DOM Benchmark Proof](./docs/DOM_BENCHMARK_PROOF.md)
+- [Benchmark Artifacts](./docs/BENCHMARK_ARTIFACTS.md)
+- [Benchmark Release Discipline](./docs/BENCHMARK_RELEASE_DISCIPLINE.md)
+- [Build Diagnostics](./docs/BUILD_DIAGNOSTICS.md)
+- [Runtime Failures](./docs/RUNTIME_FAILURES.md)
+- [Cache Invalidation](./docs/CACHE_INVALIDATION.md)
+- [Streaming and Hydration Failures](./docs/STREAMING_HYDRATION_FAILURES.md)
+- [Runtime Triage](./docs/RUNTIME_TRIAGE.md)
+- [Starter Failures](./docs/STARTER_FAILURES.md)
+- [AI Workflows](./docs/AI_WORKFLOWS.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)
+- [AI Tool Builders](./docs/AI_TOOL_BUILDERS.md)
+- [AI Surface Stability](./docs/AI_SURFACE_STABILITY.md)
+- [AI Session Packs](./docs/AI_SESSION_PACKS.md)
+- [AI Debugging Workflows](./docs/AI_DEBUGGING_WORKFLOWS.md)
+- [Starter Onboarding](./docs/STARTER_ONBOARDING.md)
+- [Migration Guide](./docs/MIGRATION_GUIDE.md)
+- [Upgrade Playbook](./docs/UPGRADE_PLAYBOOK.md)
+- [Deploy Target Guide](./docs/DEPLOY_TARGET_GUIDE.md)
+- [First Production Rollout](./docs/FIRST_PRODUCTION_ROLLOUT.md)
+- [Auth / Cache / Data Paths](./docs/AUTH_CACHE_DATA_PATHS.md)
+- [Recipe Boundaries](./docs/RECIPE_BOUNDARIES.md)
+- [Workspace Adoption](./docs/WORKSPACE_ADOPTION.md)
+- [Downstream Testing](./docs/DOWNSTREAM_TESTING.md)
+- [Team Failures](./docs/TEAM_FAILURES.md)
+- [Maturity Policy](./docs/MATURITY_POLICY.md)
+- [Dependency Policy](./docs/DEPENDENCY_POLICY.md)
+- [Compatibility Guardrails](./docs/COMPATIBILITY_GUARDRAILS.md)
+- [Ambiguity Policy](./docs/AMBIGUITY_POLICY.md)
+- [DX Feedback Loop](./docs/DX_FEEDBACK_LOOP.md)
+- [Evidence Policy](./docs/EVIDENCE_POLICY.md)
+- [Roadmap Completion Policy](./docs/ROADMAP_COMPLETION_POLICY.md)
+- [Canonical Recipes](./docs/CANONICAL_RECIPES.md)
+- [Canonical Examples](./examples/README.md)
+- [Examples Policy](./docs/EXAMPLES_POLICY.md)
+- [Support Matrix](./docs/SUPPORT_MATRIX.md)
+- [Deprecation Policy](./docs/DEPRECATION_POLICY.md)
+- [Secure Patterns](./docs/SECURE_PATTERNS.md)
+- [Adapter Security](./docs/ADAPTER_SECURITY.md)
+- [CI Policy](./docs/CI_POLICY.md)
+- [Release Policy](./docs/RELEASE_POLICY.md)
+- [Release Checklist](./docs/RELEASE_CHECKLIST.md)

package/dist-pkg/ai/artifact-lifecycle.d.ts

@@ -0,0 +1,25 @@
+export interface ArtifactLifecycleEventInput {
+    cwd: string;
+    source: "deploy" | "cli" | "build";
+    phase: "deploy" | "release" | "build";
+    kind: string;
+    severity: "info" | "warn" | "error";
+    message: string;
+    code?: string;
+    data?: Record<string, unknown>;
+}
+export declare function writeArtifactLifecycleEvent(input: ArtifactLifecycleEventInput): Promise<void>;
+export declare function writeArtifactSuccessPack(cwd: string): Promise<void>;
+export declare function writeArtifactFailurePack(cwd: string, source: "deploy" | "cli" | "build", kind: string, code: string, message: string): Promise<void>;
+export declare function runArtifactLifecycleStep<T>(input: {
+    cwd: string;
+    source: "deploy" | "cli" | "build";
+    phase: "deploy" | "release" | "build";
+    step: string;
+    version?: string;
+    code?: string;
+    startMessage: string;
+    finishMessage: string;
+    data?: Record<string, unknown>;
+    run: () => Promise<T>;
+}): Promise<T>;

package/dist-pkg/ai/artifact-lifecycle.js

@@ -0,0 +1,98 @@
+import { appendFile, mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export async function writeArtifactLifecycleEvent(input) {
+  const gorseeDir = join(input.cwd, ".gorsee");
+  await mkdir(gorseeDir, { recursive: !0 });
+  const ts = new Date().toISOString();
+  await appendFile(join(gorseeDir, "ai-events.jsonl"), `${JSON.stringify({
+    id: crypto.randomUUID(),
+    kind: input.kind,
+    severity: input.severity,
+    ts,
+    source: input.source,
+    message: input.message,
+    code: input.code,
+    phase: input.phase,
+    data: input.data
+  })}
+`, "utf-8");
+}
+export async function writeArtifactSuccessPack(cwd) {
+  const repoCliEntry = join(import.meta.dir, "..", "cli", "index.ts");
+  try {
+    await Bun.$`bun run ${repoCliEntry} ai pack`.cwd(cwd).quiet();
+  } catch {}
+}
+export async function writeArtifactFailurePack(cwd, source, kind, code, message) {
+  const gorseeDir = join(cwd, ".gorsee");
+  await mkdir(gorseeDir, { recursive: !0 });
+  const ts = new Date().toISOString();
+  await appendFile(join(gorseeDir, "ai-events.jsonl"), `${JSON.stringify({
+    id: crypto.randomUUID(),
+    kind,
+    severity: "error",
+    ts,
+    source,
+    message,
+    code
+  })}
+`, "utf-8");
+  await writeFile(join(gorseeDir, "ai-diagnostics.json"), JSON.stringify({
+    updatedAt: ts,
+    latest: {
+      code,
+      message,
+      severity: "error",
+      source
+    }
+  }, null, 2), "utf-8");
+  await writeArtifactSuccessPack(cwd);
+}
+export async function runArtifactLifecycleStep(input) {
+  await writeArtifactLifecycleEvent({
+    cwd: input.cwd,
+    source: input.source,
+    phase: input.phase,
+    kind: `${input.step}.start`,
+    severity: "info",
+    message: input.startMessage,
+    data: {
+      version: input.version,
+      ...input.data ?? {}
+    }
+  });
+  try {
+    const result = await input.run();
+    await writeArtifactLifecycleEvent({
+      cwd: input.cwd,
+      source: input.source,
+      phase: input.phase,
+      kind: `${input.step}.finish`,
+      severity: "info",
+      message: input.finishMessage,
+      data: {
+        version: input.version,
+        ...input.data ?? {}
+      }
+    });
+    await writeArtifactSuccessPack(input.cwd);
+    return result;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    await writeArtifactLifecycleEvent({
+      cwd: input.cwd,
+      source: input.source,
+      phase: input.phase,
+      kind: `${input.step}.error`,
+      severity: "error",
+      message,
+      code: input.code,
+      data: {
+        version: input.version,
+        ...input.data ?? {}
+      }
+    });
+    await writeArtifactFailurePack(input.cwd, input.source, `${input.step}.failure`, input.code ?? "ARTIFACT_STEP", message);
+    throw error;
+  }
+}