@jskit-ai/agent-docs 0.1.131 → 0.1.133

package/patterns/filters.md

@@ -19,9 +19,9 @@ Ask first:
 - whether there are presets such as "Today", "Last 7 Days", or "Only Archived"
 
 Default JSKIT client pattern:
-1. Generated CRUD list pages include a page-local `listFilters.js` file next to `index.vue`.
+1. CRUD list pages use a page-local `listFilters.js` file next to `index.vue`.
 2. Put client filter definitions in that file with `defineCrudListFilters(...)`.
-3. The generated `index.vue` passes `listFilters` into `useCrudListScreen(...)`; the shared list screen builds `useCrudListFilters(listFilters)`, passes `filterRuntime.queryParams` into the list request, and renders `CrudListFilterSurface`.
+3. The app-owned `index.vue` passes `listFilters` into `useCrudListScreen(...)`; the shared list screen builds `useCrudListFilters(listFilters)`, passes `filterRuntime.queryParams` into the list request, and renders `CrudListFilterSurface`.
 4. If `listFilters` is empty, the filter surface renders nothing and the page behaves like a normal searchable list.
 5. The AI/app author is responsible for ensuring the server accepts and applies the query params declared in `listFilters.js`.
 6. For lookup-backed filters, use `useCrudListFilterLookups(...)` when the page needs remote options or readable chip labels.
@@ -47,7 +47,7 @@ const listFilters = defineCrudListFilters({
 });
 ```
 
-Generated client shape:
+Client shape:
 - `src/pages/<surface>/<resource>/listFilters.js`
 - `const listFilters = defineCrudListFilters({ ... })`
 - `useCrudListScreen({ ..., listFilters })`
@@ -77,8 +77,8 @@ Exact file checklist:
   `listFilterQueryValidator`
 - update the provider's `createJsonRestResourceScopeOptions(...)` call so `searchSchema: listFilterContract.jsonRestSearchSchema` is merged into the internal JSON REST resource
 - update `packages/<crud>/src/server/repository.js` so list queries pass `listFilterContract.toJsonRestQuery(query)` into `buildJsonRestQueryParams(...)`
-- update the generated page-local `listFilters.js` first; only edit `index.vue` if a specialist lookup label/runtime integration is needed
-- for lookup-backed filters, wire `useCrudListFilterLookups(...)` beside the existing generated filter runtime instead of replacing `CrudListFilterSurface`
+- update the page-local `listFilters.js` first; only edit `index.vue` if a specialist lookup label/runtime integration is needed
+- for lookup-backed filters, wire `useCrudListFilterLookups(...)` beside the existing filter runtime instead of replacing `CrudListFilterSurface`
 
 Standard route and action query composition:
 
@@ -154,7 +154,7 @@ Avoid:
 - appending a list-filter validator after `createStandardCrudListQueryValidators(...)` when it belongs in the dedicated `listFilterQueryValidator` option
 - hand-rolled preset apply/reset/active-state helpers when `useCrudListFilters(..., { presets })`, `applyPreset(...)`, and `matchesPreset(...)` fit
 - per-screen `useList()` wrappers for lookup-backed filters when `useCrudListFilterLookups(...)` fits
-- editing generated `.vue` files just to add basic filter controls; use the page-local `listFilters.js` seam first
+- editing `.vue` files just to add basic filter controls; use the page-local `listFilters.js` seam first
 - overloading `q` with structured filter meaning
 - inline filter-definition objects passed into `useCrudListFilters(...)`, `createCrudListFilters(...)`, or `createCrudListFilterContract(...)`; keep definitions in a named module
 - assigning a default to `filterRuntime.values` after `useCrudListScreen(...)` has started; that changes the query after construction and can issue a second initial request
@@ -162,7 +162,7 @@ Avoid:
 Good shape:
 - `src/pages/home/customers/listFilters.js`
 - `const listFilters = defineCrudListFilters({ status: { type: "enum", ... } })`
-- generated page passes `listFilters` into `useCrudListScreen(...)`
+- page passes `listFilters` into `useCrudListScreen(...)`
 - shared screen runtime passes `filterRuntime.queryParams` into the list request
 - `packages/receivals/src/shared/receivalListFilters.js`
 - `createCrudListFilterContract(RECEIVAL_LIST_FILTER_DEFINITIONS, { columns, invalidValues: "reject" })`
@@ -178,7 +178,7 @@ Preset contract notes:
 - if the URL contains `status=archived&status=bogus`, a preset for only `archived` should not render as active while the `bogus` chip is still visible
 
 Review checks:
-- one filter definition source of truth: generated page-local `listFilters.js` for client-only filters, or a shared CRUD-package module when server code imports the same definitions
+- one filter definition source of truth: page-local `listFilters.js` for client-only filters, or a shared CRUD-package module when server code imports the same definitions
 - server validator, JSON REST search schema, and repository query projection derived from that source through `createCrudListFilterContract(...)`
 - route and action boundaries independently compose
   `createStandardCrudListQueryValidators(...)`, using the dedicated

package/patterns/live-actions.md

@@ -12,26 +12,13 @@ Rules:
 - Prefer `useCommand()` for live actions.
 - Prefer form runtimes such as `useCrudAddEdit()` or `useAddEdit()` for real forms.
 - Prefer `useCrudList()` and `useCrudView()` for routed CRUD loading and URL resolution.
-- For ordinary routed CRUD record deletion, generate the supported lane instead
-  of rebuilding it page by page:
-
-  ```bash
-  npx --no-install jskit generate crud-ui-generator crud notes \
-    --resource-file packages/notes/src/shared/noteResource.js \
-    --id-param noteId \
-    --display-fields title,body \
-    --parent-title contextual \
-    --navigation-role primary \
-    --delete-confirmation
-  ```
-
-  `--delete-confirmation` requires generated list and view pages plus a shared
-  resource with a `DELETE` operation. It extends the view through the public
-  `CrudViewScreen` `actions` slot with `CrudDeleteAction` and wires it to
+- For ordinary routed CRUD record deletion, start from the package-owned CRUD
+  UI pattern instead of rebuilding it page by page. Its view screen uses the
+  public `CrudViewScreen` `actions` slot with `CrudDeleteAction` and wires it to
   `useCrudDeleteAction()`: the shared component owns the alert dialog,
   `useCommand()` owns the request state, the shared resource owns the DELETE
   contract, and successful deletion invalidates the list query and navigates
-  to the generated list route.
+  to the list route.
 
 Good live-action pattern:
 
@@ -51,5 +38,5 @@ Avoid:
 
 - manually hand-rolling fetch logic for a standard live action when `useCommand()` fits
 - inspecting private `http-web` internals or creating a page-local transport
-  for generated record deletion
+  for standard record deletion
 - pushing derived write rules into the client just because the action is small

package/patterns/minimal-foundation/PATTERN.md

@@ -0,0 +1,98 @@
+---
+id: app/minimal-foundation
+title: Minimal JSKIT application foundation
+summary: A concrete Fastify, Vue, and JSKIT application foundation for products that do not yet need the full adaptive shell.
+keywords: app, fastify, foundation, minimal, server, vite, vue
+requires: @jskit-ai/http-runtime, @jskit-ai/kernel
+---
+
+# Minimal JSKIT application foundation
+
+## Use when
+
+Use this pattern when establishing a new JSKIT web application in an existing
+project repository and the product does not yet need the full adaptive shell,
+settings navigation, or placement topology. It provides a working server,
+client bootstrap, app-local provider package, one public surface, linting, unit
+tests, browser tests, and the normal build entrypoints.
+
+The example is a concrete application named `reading-room`. Copy the useful
+files into the project root, rename the application in normal source and
+package metadata, and then edit the product-facing page. The files become
+ordinary application source immediately.
+
+## Do not use when
+
+Do not use this pattern when the application already has an established
+server/client foundation. Do not replace a working app merely to make it
+resemble the example. Prefer the shell foundation when responsive navigation,
+settings, or placement contributions are already clear requirements.
+
+## Product decisions
+
+Decide the application name, first useful route, public versus authenticated
+surface access, and whether the product needs the adaptive shell. These are
+product decisions for the user and agent; this pattern does not ask a
+questionnaire or infer tenancy, authentication, or database requirements.
+
+## Invariants
+
+- Preserve `.git` and all unrelated project and agent context.
+- Refuse or resolve real destination-file collisions before copying.
+- Keep `packages/main` limited to app composition and lightweight glue.
+- Use package public APIs; do not deep-import package internals.
+- Keep one server entry, one client bootstrap, and explicit surface access.
+- Keep one app-owned `npm run develop` entry that runs the API on loopback and
+  Vite on the host-supplied preview port; do not require a host to infer or
+  supervise framework-specific processes.
+- Treat copied files as app-owned source. Do not add provenance, ownership
+  markers, receipts, ledgers, or operation-history state.
+- Keep browser dependencies aligned with the execution environment that will
+  run the tests. Vibe64 supplies its exact managed Playwright version.
+
+## Framework APIs
+
+The example composes `@jskit-ai/kernel` for provider/runtime composition and
+`@jskit-ai/http-runtime` for the web runtime. `packages/main` demonstrates the
+app-local provider boundary. Vite, Vue Router, Pinia, Vuetify, Fastify, and Vue
+Query remain normal application dependencies.
+
+## Example files
+
+`example/` is a complete concrete application tree. Copy only after inspecting
+collisions. Rename `example/gitignore` to `.gitignore` in the application;
+the neutral filename ensures npm publishes the reference asset. Managed preview
+identity belongs to the authentication surface pattern, not the neutral
+foundation.
+
+Important starting points are:
+
+- `example/package.json`
+- `example/server.js`, `example/bin/server.js`, and `example/bin/develop.js`
+- `example/src/main.js` and `example/src/App.vue`
+- `example/config/public.js`
+- `example/packages/main/`
+- `example/tests/`
+
+## Variation points
+
+Rename the package and title, replace the home page with the first real
+product surface, add capabilities through their owning packages, and change
+surface access deliberately. Add authentication, database, CRUD, shell, or
+mobile patterns only when chosen. Do not pre-emptively include them.
+
+## Verification
+
+After adapting the example, install the declared packages once and run
+`npm run develop` for the live application. Then run the application's lint,
+server tests, client tests, production build, and focused browser smoke.
+Confirm `/api/health` and the first product route.
+
+## Avoid
+
+- Do not run a scaffold questionnaire.
+- Do not create a temporary app and copy its result over the project.
+- Do not force-overwrite an existing repository.
+- Do not keep `reading-room` names that no longer describe the product.
+- Do not add a hidden file recording that this pattern was copied.
+- Do not turn the example into a field interpolation language.

package/patterns/minimal-foundation/example/.nvmrc

@@ -0,0 +1 @@
+26

package/patterns/minimal-foundation/example/AGENTS.md

@@ -0,0 +1,17 @@
+# App Agent Instructions
+
+Use current project context, JSKIT public APIs, and the installed JSKIT pattern
+index as the source of truth for application work.
+
+Recommended references:
+
+- `node_modules/@jskit-ai/agent-docs/guide/agent/index.md`
+- `node_modules/@jskit-ai/agent-docs/patterns/INDEX.md`
+
+Before database, schema, CRUD, repository, or persistence work, inspect the
+relevant package-owned pattern from
+`node_modules/@jskit-ai/agent-docs/reference/autogen/PATTERN_INDEX.md`.
+
+Copied pattern source is ordinary application source. Do not add generator
+provenance, receipts, completion ledgers, or tooling-operation history. Keep
+changes scoped to the user request and verify runtime behavior directly.

package/patterns/minimal-foundation/example/Procfile

@@ -0,0 +1,2 @@
+release: npm run db:migrate
+web: npm run start

package/patterns/minimal-foundation/example/app.json

@@ -0,0 +1,14 @@
+{
+  "name": "reading-room",
+  "healthchecks": {
+    "web": [
+      {
+        "type": "startup",
+        "name": "web-ready",
+        "description": "Application responds to /api/health",
+        "path": "/api/health",
+        "attempts": 6
+      }
+    ]
+  }
+}

package/patterns/minimal-foundation/example/bin/develop.js

@@ -0,0 +1,71 @@
+import { spawn } from "node:child_process";
+import { startServer } from "../server.js";
+
+const LOOPBACK_HOST = "127.0.0.1";
+
+function requiredPort(value, fallback = 3000) {
+  const normalized = String(value || "").trim();
+  const parsed = Number.parseInt(normalized || String(fallback), 10);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65_535) {
+    throw new Error(`Invalid development port: ${normalized || "(empty)"}.`);
+  }
+  return parsed;
+}
+
+function waitForChild(child) {
+  return new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code, signal) => resolve({ code, signal }));
+  });
+}
+
+const previewHost = String(process.env.HOST || "").trim() || "0.0.0.0";
+const previewPort = requiredPort(process.env.PORT);
+let apiServer = null;
+let viteProcess = null;
+let requestedSignal = "";
+
+function requestShutdown(signal) {
+  requestedSignal = signal;
+  if (viteProcess && !viteProcess.killed) {
+    viteProcess.kill(signal);
+  }
+}
+
+process.once("SIGINT", () => requestShutdown("SIGINT"));
+process.once("SIGTERM", () => requestShutdown("SIGTERM"));
+
+try {
+  apiServer = await startServer({ host: LOOPBACK_HOST, port: 0 });
+  const apiPort = requiredPort(apiServer.server.address()?.port);
+  const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+  viteProcess = spawn(
+    npmCommand,
+    ["run", "dev", "--", "--host", previewHost, "--port", String(previewPort), "--strictPort"],
+    {
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        HOST: previewHost,
+        PORT: String(previewPort),
+        VITE_API_PROXY_TARGET: `http://${LOOPBACK_HOST}:${apiPort}`,
+        VITE_DEV_PORT: String(previewPort)
+      },
+      stdio: "inherit"
+    }
+  );
+
+  const result = await waitForChild(viteProcess);
+  if (!requestedSignal && result.code !== 0) {
+    throw new Error(
+      `Vite development server stopped unexpectedly (${result.signal || `exit ${result.code ?? "unknown"}`}).`
+    );
+  }
+} catch (error) {
+  console.error("Failed to start the development application:", error);
+  process.exitCode = 1;
+} finally {
+  if (apiServer) {
+    await apiServer.close().catch(() => {});
+  }
+}

package/patterns/minimal-foundation/example/bin/server.js

@@ -0,0 +1,8 @@
+import { startServer } from "../server.js";
+
+try {
+  await startServer();
+} catch (error) {
+  console.error("Failed to start reading-room server:", error);
+  process.exitCode = 1;
+}

package/patterns/minimal-foundation/example/config/public.js

@@ -0,0 +1,40 @@
+import { surfaceAccessPolicies } from "./surfaceAccessPolicies.js";
+
+export const config = {};
+
+config.surfaceModeAll = "all";
+config.surfaceDefaultId = "home";
+config.webRootAllowed = "no";
+config.surfaceAccessPolicies = surfaceAccessPolicies;
+config.mobile = {
+  enabled: false,
+  strategy: "",
+  appId: "",
+  appName: "",
+  assetMode: "bundled",
+  devServerUrl: "",
+  apiBaseUrl: "",
+  auth: {
+    callbackPath: "/auth/login",
+    customScheme: "",
+    appLinkDomains: []
+  },
+  android: {
+    packageName: "",
+    minSdk: 26,
+    targetSdk: 35,
+    versionCode: 1,
+    versionName: "1.0.0"
+  }
+};
+config.surfaceDefinitions = {};
+config.surfaceDefinitions.home = {
+  id: "home",
+  label: "Home",
+  pagesRoot: "home",
+  enabled: true,
+  requiresAuth: false,
+  requiresWorkspace: false,
+  accessPolicyId: "public",
+  origin: ""
+};

package/patterns/minimal-foundation/example/config/server.js

@@ -0,0 +1 @@
+export const config = {};

package/patterns/minimal-foundation/example/config/surfaceAccessPolicies.js

@@ -0,0 +1,3 @@
+export const surfaceAccessPolicies = {};
+
+surfaceAccessPolicies.public = {};

package/patterns/minimal-foundation/example/eslint.config.mjs

@@ -0,0 +1,19 @@
+import { baseConfig, nodeConfig, vueConfig, webConfig } from "@jskit-ai/config-eslint/server";
+
+export default [
+  {
+    ignores: ["dist/**", "node_modules/**", "coverage/**", "test-results/**", ".jskit/**"]
+  },
+  {
+    files: ["src/pages/**/*.vue"],
+    languageOptions: {
+      globals: {
+        definePage: "readonly"
+      }
+    }
+  },
+  ...baseConfig,
+  ...vueConfig,
+  ...webConfig,
+  ...nodeConfig
+];

package/patterns/minimal-foundation/example/favicon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="12" fill="#111827" />
+  <path
+    d="M20 16h24v8H28v20c0 6-4 10-10 10h-2v-8h2c2 0 2-1 2-3V16z"
+    fill="#22d3ee"
+  />
+</svg>

package/patterns/minimal-foundation/example/gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+coverage/
+test-results/
+# Generated by vue-router/vite on the first dev or build scan.
+src/typed-router.d.ts
+.env
+.env.*
+!.env.example

package/patterns/minimal-foundation/example/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <title>Reading Room</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

package/patterns/minimal-foundation/example/jsconfig.json

@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  }
+}

package/patterns/minimal-foundation/example/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "reading-room",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Minimal JSKIT base app (Fastify + Vue)",
+  "engines": {
+    "node": "26.x"
+  },
+  "scripts": {
+    "server": "node ./bin/server.js",
+    "server:all": "node ./bin/server.js",
+    "server:home": "SERVER_SURFACE=home node ./bin/server.js",
+    "start": "node ./bin/server.js",
+    "develop": "node ./bin/develop.js",
+    "dev": "vite",
+    "dev:all": "vite",
+    "dev:home": "VITE_SURFACE=home vite",
+    "build": "vite build",
+    "build:all": "vite build",
+    "build:home": "VITE_SURFACE=home vite build",
+    "preview": "vite preview",
+    "lint": "eslint .",
+    "test": "node --test",
+    "test:client": "vitest run tests/client",
+    "test:e2e": "playwright test tests/e2e",
+    "verify": "npm run lint && npm run test && npm run test:client && npm run build"
+  },
+  "dependencies": {
+    "@local/main": "file:packages/main",
+    "@fastify/static": "^10.1.3",
+    "@jskit-ai/kernel": "0.1.161",
+    "@tanstack/vue-query": "^5.101.0",
+    "fastify": "^5.8.5",
+    "json-rest-schema": "^1.0.17",
+    "pinia": "^3.0.4",
+    "vue": "^3.5.38",
+    "vue-router": "^5.1.0",
+    "vuetify": "^4.1.2",
+    "@jskit-ai/http-runtime": "0.1.159"
+  },
+  "devDependencies": {
+    "@jskit-ai/agent-docs": "0.1.133",
+    "@jskit-ai/config-eslint": "0.1.158",
+    "@playwright/test": "1.61.1",
+    "@vitejs/plugin-vue": "^6.0.7",
+    "eslint": "^10.8.0",
+    "vite": "^8.2.1",
+    "vite-plugin-vuetify": "^2.1.3",
+    "vitest": "^4.1.9"
+  },
+  "allowScripts": {
+    "fsevents@2.3.2": true,
+    "fsevents@2.3.3": true,
+    "vue-demi@0.14.10": true
+  }
+}

package/patterns/minimal-foundation/example/packages/main/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@local/main",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./shared": "./src/shared/index.js"
+  },
+  "description": "App-local runtime composition and lightweight glue.",
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [],
+      "requires": []
+    },
+    "metadata": {
+      "jskit": {
+        "ownershipGuidance": {
+          "title": "App-local main lane",
+          "summary": "Keep @local/main focused on app composition and lightweight glue. Substantial server features should become dedicated packages instead of growing inside packages/main.",
+          "responsibilities": [
+            "packages/main server code: bootstraps app-local configuration and lightweight wiring only",
+            "substantial server features: author a dedicated app-local package from the relevant framework pattern",
+            "packages/main: do not add service/controller/route/repository feature trees here"
+          ],
+          "examples": [
+            "packages/booking-engine owns booking operations",
+            "packages/availability-engine owns availability orchestration"
+          ]
+        }
+      },
+      "server": {
+        "routes": []
+      },
+      "ui": {
+        "routes": [],
+        "elements": [],
+        "overrides": []
+      }
+    }
+  }
+}

package/patterns/minimal-foundation/example/packages/main/src/shared/index.js

@@ -0,0 +1,10 @@
+/**
+ * Shared entrypoint for code used by both client and server.
+ *
+ * Keep this for genuinely app-local shared glue only.
+ *
+ * Example:
+ * export * from "./schemas/index.js";
+ * export * from "./constants/index.js";
+ */
+export {};

package/patterns/minimal-foundation/example/packages/main/src/shared/schemas/index.js

@@ -0,0 +1,22 @@
+/**
+ * App-local shared transport validators/resources live here.
+ * Dedicated feature packages should keep their own schemas with the feature.
+ *
+ * Example:
+ * import { createSchema } from "json-rest-schema";
+ *
+ * export const helloQuerySchema = createSchema({
+ *   name: { type: "string", minLength: 1, maxLength: 80 }
+ * });
+ *
+ * export const helloResponseSchema = {
+ *   type: "object",
+ *   additionalProperties: false,
+ *   required: ["ok", "message"],
+ *   properties: {
+ *     ok: { type: "boolean" },
+ *     message: { type: "string", minLength: 1 }
+ *   }
+ * };
+ */
+export {};

package/patterns/minimal-foundation/example/playwright.config.mjs

@@ -0,0 +1,31 @@
+import { defineConfig } from "@playwright/test";
+
+const managedBaseUrl = String(process.env.PLAYWRIGHT_BASE_URL || "")
+  .trim()
+  .replace(/\/+$/u, "");
+const baseURL = managedBaseUrl || "http://127.0.0.1:4173";
+const storageState = String(process.env.VIBE64_PLAYWRIGHT_STORAGE_STATE || "").trim();
+
+export default defineConfig({
+  testDir: "./tests/e2e",
+  timeout: 60_000,
+  expect: {
+    timeout: 10_000
+  },
+  use: {
+    baseURL,
+    headless: true,
+    ...(storageState ? { storageState } : {})
+  },
+  ...(managedBaseUrl ? {} : {
+    webServer: {
+      command: "npm run build && node ./bin/server.js",
+      env: {
+        PORT: "4173"
+      },
+      url: `${baseURL}/api/health`,
+      reuseExistingServer: true,
+      timeout: 180_000
+    }
+  })
+});

package/patterns/minimal-foundation/example/server/lib/runtimeEnv.js

@@ -0,0 +1,45 @@
+import { createRequire } from "node:module";
+import { surfaceRuntime } from "./surfaceRuntime.js";
+
+const require = createRequire(import.meta.url);
+
+function toPort(value, fallback = 3000) {
+  const parsed = Number.parseInt(String(value || "").trim(), 10);
+  if (Number.isInteger(parsed) && parsed > 0) {
+    return parsed;
+  }
+  return fallback;
+}
+
+let envLoaded = false;
+
+function ensureRuntimeEnvLoaded() {
+  if (envLoaded) {
+    return;
+  }
+  try {
+    const dotenvModule = require("dotenv");
+    const loadDotEnv = dotenvModule?.config;
+    if (typeof loadDotEnv === "function") {
+      loadDotEnv();
+    }
+  } catch {
+    // dotenv is optional in base-shell; bundles can add it when needed.
+  }
+  envLoaded = true;
+}
+
+function resolveRuntimeEnv() {
+  ensureRuntimeEnvLoaded();
+  const serverSurface = surfaceRuntime.normalizeSurfaceMode(
+    process.env.JSKIT_SERVER_SURFACE || process.env.SERVER_SURFACE
+  );
+  return {
+    ...process.env,
+    SERVER_SURFACE: serverSurface,
+    PORT: toPort(process.env.PORT, 3000),
+    HOST: String(process.env.HOST || "").trim() || "0.0.0.0"
+  };
+}
+
+export { resolveRuntimeEnv };

package/patterns/minimal-foundation/example/server/lib/surfaceRuntime.js

@@ -0,0 +1,10 @@
+import { createSurfaceRuntime } from "@jskit-ai/kernel/shared/surface/runtime";
+import { config } from "../../config/public.js";
+
+const surfaceRuntime = createSurfaceRuntime({
+  allMode: config.surfaceModeAll,
+  surfaces: config.surfaceDefinitions,
+  defaultSurfaceId: config.surfaceDefaultId
+});
+
+export { surfaceRuntime };