tina4-nodejs 3.13.135 → 3.13.137

package/CLAUDE.md

@@ -13,13 +13,13 @@ Even if the skill text is not currently loaded, these are non-negotiable:
 
 The full discipline lives in `.claude/skills/tina4-maintainer/SKILL.md`; this block is the always-on floor.
 
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.135)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.137)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.135 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.137 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.135",
+  "version": "3.13.137",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - native TypeScript conventions and shared Tina4 contracts",
   "keywords": [

package/packages/cli/dist/bin.js

@@ -12388,6 +12388,10 @@ async function recordApplied(db, name, batch, passed = 1) {
     insertCols.push("migration_id");
     values.push(name);
   }
+  if (cols.has("name")) {
+    insertCols.push("name");
+    values.push(name);
+  }
   if (isFirebirdAdapter(db)) {
     const rows = await adapterQuery(
       db,
@@ -37955,13 +37959,37 @@ function swaggerEnabled() {
   return ["true", "1", "yes", "on"].includes(raw);
 }
 function createSwaggerRoutes(getSpec) {
+  const serveUi = async (_req, res) => {
+    res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
+  };
   return [
     {
       method: "GET",
       pattern: "/swagger",
-      handler: async (_req, res) => {
-        res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
-      }
+      handler: serveUi
+    },
+    {
+      // The trailing-slash form, registered rather than left to fall through.
+      //
+      // Matching "/foo/" against a "/foo" route is opt-in via
+      // TINA4_TRAILING_SLASH_REDIRECT and OFF by default, so /swagger/ missed
+      // this route and was answered by the framework-bundled
+      // public/swagger/index.html instead. That mattered twice over. It used to
+      // be a 200 carrying a permanently empty UI, because the bundled file asked
+      // for an unsubstituted {SWAGGER_ROUTE}/swagger.json -- fixed in that file.
+      // And it is a SECOND Swagger UI implementation: the bundled one hardcodes
+      // cdnjs, while the page this handler renders loads from
+      // TINA4_SWAGGER_UI_CDN, so an air-gapped deployment pointing that at a
+      // local mirror silently kept reaching cdnjs on this one path.
+      //
+      // Registering it keeps the fix inside swagger rather than changing how
+      // every route treats trailing slashes, satisfies the shared contract that
+      // already requires a 200 here, and matches python and ruby, which both
+      // serve /swagger and /swagger/ with no env var set. Excluded from the
+      // generated document by INTERNAL_PREFIXES like /swagger itself.
+      method: "GET",
+      pattern: "/swagger/",
+      handler: serveUi
     },
     {
       method: "GET",
@@ -44682,13 +44710,14 @@ var init_aiClient = __esm({
       }
       static config(capability, options) {
         const provider = (options.provider ?? process.env.TINA4_AI_PROVIDER ?? "local").trim().toLowerCase();
-        if (provider !== "local" && provider !== "openai" && provider !== "anthropic") throw new AiConfigError("TINA4_AI_PROVIDER must be local, openai, or anthropic");
+        if (provider !== "local" && provider !== "openai" && provider !== "anthropic" && provider !== "gemini") throw new AiConfigError("TINA4_AI_PROVIDER must be local, openai, anthropic, or gemini");
         const key = process.env.TINA4_AI_KEY || null;
-        if ((provider === "openai" || provider === "anthropic") && !key) throw new AiConfigError(`TINA4_AI_KEY is required for the ${provider} provider`);
+        if ((provider === "openai" || provider === "anthropic" || provider === "gemini") && !key) throw new AiConfigError(`TINA4_AI_KEY is required for the ${provider} provider`);
         const defaults = {
           local: ["http://localhost:11437", "llama3.2"],
           openai: ["https://api.openai.com/v1", "gpt-4o-mini"],
-          anthropic: ["https://api.anthropic.com/v1", "claude-3-5-haiku-latest"]
+          anthropic: ["https://api.anthropic.com/v1", "claude-3-5-haiku-latest"],
+          gemini: ["https://generativelanguage.googleapis.com/v1beta/openai", "gemini-2.5-flash"]
         };
         const rawUrl = capability === "embed" && process.env.TINA4_EMBED_URL ? process.env.TINA4_EMBED_URL : process.env.TINA4_AI_URL ?? defaults[provider][0];
         const model = (options.model ?? process.env.TINA4_AI_MODEL ?? defaults[provider][1]).trim();
@@ -44706,7 +44735,7 @@ var init_aiClient = __esm({
         }
         if (url.protocol !== "http:" && url.protocol !== "https:") throw new AiConfigError("AI URL must be an http or https URL");
         const path10 = url.pathname.replace(/\/+$/, "");
-        if (path10 === "" || path10 === "/v1" || path10 === "/api") {
+        if (path10 === "" || path10 === "/v1" || path10 === "/api" || path10 === "/v1beta/openai") {
           const suffix = provider === "anthropic" ? "/messages" : capability === "embed" ? "/embeddings" : "/chat/completions";
           url.pathname = (path10 || "/v1") + suffix;
         }
@@ -44714,7 +44743,7 @@ var init_aiClient = __esm({
       }
       static headers(config) {
         const headers = { "content-type": "application/json", accept: "application/json" };
-        if (config.provider === "openai") headers.authorization = `Bearer ${config.key}`;
+        if (config.provider === "openai" || config.provider === "gemini") headers.authorization = `Bearer ${config.key}`;
         if (config.provider === "anthropic") {
           headers["x-api-key"] = config.key;
           headers["anthropic-version"] = "2023-06-01";

package/packages/core/dist/index.js

@@ -12387,6 +12387,10 @@ async function recordApplied(db, name, batch, passed = 1) {
     insertCols.push("migration_id");
     values.push(name);
   }
+  if (cols.has("name")) {
+    insertCols.push("name");
+    values.push(name);
+  }
   if (isFirebirdAdapter(db)) {
     const rows = await adapterQuery(
       db,
@@ -37934,13 +37938,37 @@ function swaggerEnabled() {
   return ["true", "1", "yes", "on"].includes(raw);
 }
 function createSwaggerRoutes(getSpec) {
+  const serveUi = async (_req, res) => {
+    res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
+  };
   return [
     {
       method: "GET",
       pattern: "/swagger",
-      handler: async (_req, res) => {
-        res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
-      }
+      handler: serveUi
+    },
+    {
+      // The trailing-slash form, registered rather than left to fall through.
+      //
+      // Matching "/foo/" against a "/foo" route is opt-in via
+      // TINA4_TRAILING_SLASH_REDIRECT and OFF by default, so /swagger/ missed
+      // this route and was answered by the framework-bundled
+      // public/swagger/index.html instead. That mattered twice over. It used to
+      // be a 200 carrying a permanently empty UI, because the bundled file asked
+      // for an unsubstituted {SWAGGER_ROUTE}/swagger.json -- fixed in that file.
+      // And it is a SECOND Swagger UI implementation: the bundled one hardcodes
+      // cdnjs, while the page this handler renders loads from
+      // TINA4_SWAGGER_UI_CDN, so an air-gapped deployment pointing that at a
+      // local mirror silently kept reaching cdnjs on this one path.
+      //
+      // Registering it keeps the fix inside swagger rather than changing how
+      // every route treats trailing slashes, satisfies the shared contract that
+      // already requires a 200 here, and matches python and ruby, which both
+      // serve /swagger and /swagger/ with no env var set. Excluded from the
+      // generated document by INTERNAL_PREFIXES like /swagger itself.
+      method: "GET",
+      pattern: "/swagger/",
+      handler: serveUi
     },
     {
       method: "GET",
@@ -44643,13 +44671,14 @@ var init_aiClient = __esm({
       }
       static config(capability, options) {
         const provider = (options.provider ?? process.env.TINA4_AI_PROVIDER ?? "local").trim().toLowerCase();
-        if (provider !== "local" && provider !== "openai" && provider !== "anthropic") throw new AiConfigError("TINA4_AI_PROVIDER must be local, openai, or anthropic");
+        if (provider !== "local" && provider !== "openai" && provider !== "anthropic" && provider !== "gemini") throw new AiConfigError("TINA4_AI_PROVIDER must be local, openai, anthropic, or gemini");
         const key = process.env.TINA4_AI_KEY || null;
-        if ((provider === "openai" || provider === "anthropic") && !key) throw new AiConfigError(`TINA4_AI_KEY is required for the ${provider} provider`);
+        if ((provider === "openai" || provider === "anthropic" || provider === "gemini") && !key) throw new AiConfigError(`TINA4_AI_KEY is required for the ${provider} provider`);
         const defaults = {
           local: ["http://localhost:11437", "llama3.2"],
           openai: ["https://api.openai.com/v1", "gpt-4o-mini"],
-          anthropic: ["https://api.anthropic.com/v1", "claude-3-5-haiku-latest"]
+          anthropic: ["https://api.anthropic.com/v1", "claude-3-5-haiku-latest"],
+          gemini: ["https://generativelanguage.googleapis.com/v1beta/openai", "gemini-2.5-flash"]
         };
         const rawUrl = capability === "embed" && process.env.TINA4_EMBED_URL ? process.env.TINA4_EMBED_URL : process.env.TINA4_AI_URL ?? defaults[provider][0];
         const model = (options.model ?? process.env.TINA4_AI_MODEL ?? defaults[provider][1]).trim();
@@ -44667,7 +44696,7 @@ var init_aiClient = __esm({
         }
         if (url.protocol !== "http:" && url.protocol !== "https:") throw new AiConfigError("AI URL must be an http or https URL");
         const path10 = url.pathname.replace(/\/+$/, "");
-        if (path10 === "" || path10 === "/v1" || path10 === "/api") {
+        if (path10 === "" || path10 === "/v1" || path10 === "/api" || path10 === "/v1beta/openai") {
           const suffix = provider === "anthropic" ? "/messages" : capability === "embed" ? "/embeddings" : "/chat/completions";
           url.pathname = (path10 || "/v1") + suffix;
         }
@@ -44675,7 +44704,7 @@ var init_aiClient = __esm({
       }
       static headers(config) {
         const headers = { "content-type": "application/json", accept: "application/json" };
-        if (config.provider === "openai") headers.authorization = `Bearer ${config.key}`;
+        if (config.provider === "openai" || config.provider === "gemini") headers.authorization = `Bearer ${config.key}`;
         if (config.provider === "anthropic") {
           headers["x-api-key"] = config.key;
           headers["anthropic-version"] = "2023-06-01";

package/packages/core/public/swagger/index.html

@@ -71,7 +71,7 @@
 
         // Build a system
         const ui = SwaggerUIBundle({
-            url: "{SWAGGER_ROUTE}/swagger.json",
+            url: "/swagger/openapi.json",
             dom_id: '#swagger-ui',
             deepLinking: true,
             presets: [

package/packages/core/src/aiClient.ts

@@ -87,7 +87,7 @@ export interface AiChatOptions {
   maxTokens?: number;
   stream?: boolean;
   timeout?: number;
-  provider?: "local" | "openai" | "anthropic";
+  provider?: "local" | "openai" | "anthropic" | "gemini";
   /** Tools the model may call. ADR-0061 — translated per provider. */
   tools?: AiToolDeclaration[];
   /**
@@ -97,10 +97,10 @@ export interface AiChatOptions {
    */
   toolChoice?: AiToolChoice;
 }
-export interface AiEmbedOptions { model?: string; timeout?: number; provider?: "local" | "openai" | "anthropic" }
+export interface AiEmbedOptions { model?: string; timeout?: number; provider?: "local" | "openai" | "anthropic" | "gemini" }
 
 interface Config {
-  provider: "local" | "openai" | "anthropic";
+  provider: "local" | "openai" | "anthropic" | "gemini";
   url: string;
   model: string;
   key: string | null;
@@ -288,13 +288,16 @@ export class Ai {
 
   private static config(capability: "chat" | "embed", options: AiChatOptions | AiEmbedOptions): Config {
     const provider = (options.provider ?? process.env.TINA4_AI_PROVIDER ?? "local").trim().toLowerCase();
-    if (provider !== "local" && provider !== "openai" && provider !== "anthropic") throw new AiConfigError("TINA4_AI_PROVIDER must be local, openai, or anthropic");
+    if (provider !== "local" && provider !== "openai" && provider !== "anthropic" && provider !== "gemini") throw new AiConfigError("TINA4_AI_PROVIDER must be local, openai, anthropic, or gemini");
     const key = process.env.TINA4_AI_KEY || null;
-    if ((provider === "openai" || provider === "anthropic") && !key) throw new AiConfigError(`TINA4_AI_KEY is required for the ${provider} provider`);
+    if ((provider === "openai" || provider === "anthropic" || provider === "gemini") && !key) throw new AiConfigError(`TINA4_AI_KEY is required for the ${provider} provider`);
+    // Gemini speaks the OpenAI wire format at its OpenAI-compatible base, so it rides the openai
+    // body/parse/stream path - only the base URL, the endpoint suffix append, and the Bearer key differ.
     const defaults: Record<Config["provider"], [string, string]> = {
       local: ["http://localhost:11437", "llama3.2"],
       openai: ["https://api.openai.com/v1", "gpt-4o-mini"],
       anthropic: ["https://api.anthropic.com/v1", "claude-3-5-haiku-latest"],
+      gemini: ["https://generativelanguage.googleapis.com/v1beta/openai", "gemini-2.5-flash"],
     };
     const rawUrl = capability === "embed" && process.env.TINA4_EMBED_URL ? process.env.TINA4_EMBED_URL : (process.env.TINA4_AI_URL ?? defaults[provider][0]);
     const model = (options.model ?? process.env.TINA4_AI_MODEL ?? defaults[provider][1]).trim();
@@ -309,7 +312,11 @@ export class Ai {
     try { url = new URL(value); } catch { throw new AiConfigError("AI URL must be an http or https URL"); }
     if (url.protocol !== "http:" && url.protocol !== "https:") throw new AiConfigError("AI URL must be an http or https URL");
     const path = url.pathname.replace(/\/+$/, "");
-    if (path === "" || path === "/v1" || path === "/api") {
+    // "/v1beta/openai" is Gemini's OpenAI-compatible base; append the suffix onto it exactly as
+    // onto a bare host / "/v1" / "/api", so the default gemini base resolves to
+    // .../v1beta/openai/chat/completions (or /embeddings). A full endpoint URL the caller supplies
+    // (any other path) still passes through verbatim.
+    if (path === "" || path === "/v1" || path === "/api" || path === "/v1beta/openai") {
       const suffix = provider === "anthropic" ? "/messages" : capability === "embed" ? "/embeddings" : "/chat/completions";
       url.pathname = (path || "/v1") + suffix;
     }
@@ -318,7 +325,7 @@ export class Ai {
 
   private static headers(config: Config): Record<string, string> {
     const headers: Record<string, string> = { "content-type": "application/json", accept: "application/json" };
-    if (config.provider === "openai") headers.authorization = `Bearer ${config.key}`;
+    if (config.provider === "openai" || config.provider === "gemini") headers.authorization = `Bearer ${config.key}`;
     if (config.provider === "anthropic") { headers["x-api-key"] = config.key!; headers["anthropic-version"] = "2023-06-01"; }
     return headers;
   }

package/packages/orm/dist/index.js

@@ -26223,13 +26223,37 @@ function swaggerEnabled() {
   return ["true", "1", "yes", "on"].includes(raw);
 }
 function createSwaggerRoutes(getSpec) {
+  const serveUi = async (_req, res) => {
+    res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
+  };
   return [
     {
       method: "GET",
       pattern: "/swagger",
-      handler: async (_req, res) => {
-        res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
-      }
+      handler: serveUi
+    },
+    {
+      // The trailing-slash form, registered rather than left to fall through.
+      //
+      // Matching "/foo/" against a "/foo" route is opt-in via
+      // TINA4_TRAILING_SLASH_REDIRECT and OFF by default, so /swagger/ missed
+      // this route and was answered by the framework-bundled
+      // public/swagger/index.html instead. That mattered twice over. It used to
+      // be a 200 carrying a permanently empty UI, because the bundled file asked
+      // for an unsubstituted {SWAGGER_ROUTE}/swagger.json -- fixed in that file.
+      // And it is a SECOND Swagger UI implementation: the bundled one hardcodes
+      // cdnjs, while the page this handler renders loads from
+      // TINA4_SWAGGER_UI_CDN, so an air-gapped deployment pointing that at a
+      // local mirror silently kept reaching cdnjs on this one path.
+      //
+      // Registering it keeps the fix inside swagger rather than changing how
+      // every route treats trailing slashes, satisfies the shared contract that
+      // already requires a 200 here, and matches python and ruby, which both
+      // serve /swagger and /swagger/ with no env var set. Excluded from the
+      // generated document by INTERNAL_PREFIXES like /swagger itself.
+      method: "GET",
+      pattern: "/swagger/",
+      handler: serveUi
     },
     {
       method: "GET",
@@ -33463,13 +33487,14 @@ var init_aiClient = __esm({
       }
       static config(capability, options) {
         const provider = (options.provider ?? process.env.TINA4_AI_PROVIDER ?? "local").trim().toLowerCase();
-        if (provider !== "local" && provider !== "openai" && provider !== "anthropic") throw new AiConfigError("TINA4_AI_PROVIDER must be local, openai, or anthropic");
+        if (provider !== "local" && provider !== "openai" && provider !== "anthropic" && provider !== "gemini") throw new AiConfigError("TINA4_AI_PROVIDER must be local, openai, anthropic, or gemini");
         const key = process.env.TINA4_AI_KEY || null;
-        if ((provider === "openai" || provider === "anthropic") && !key) throw new AiConfigError(`TINA4_AI_KEY is required for the ${provider} provider`);
+        if ((provider === "openai" || provider === "anthropic" || provider === "gemini") && !key) throw new AiConfigError(`TINA4_AI_KEY is required for the ${provider} provider`);
         const defaults = {
           local: ["http://localhost:11437", "llama3.2"],
           openai: ["https://api.openai.com/v1", "gpt-4o-mini"],
-          anthropic: ["https://api.anthropic.com/v1", "claude-3-5-haiku-latest"]
+          anthropic: ["https://api.anthropic.com/v1", "claude-3-5-haiku-latest"],
+          gemini: ["https://generativelanguage.googleapis.com/v1beta/openai", "gemini-2.5-flash"]
         };
         const rawUrl = capability === "embed" && process.env.TINA4_EMBED_URL ? process.env.TINA4_EMBED_URL : process.env.TINA4_AI_URL ?? defaults[provider][0];
         const model = (options.model ?? process.env.TINA4_AI_MODEL ?? defaults[provider][1]).trim();
@@ -33487,7 +33512,7 @@ var init_aiClient = __esm({
         }
         if (url.protocol !== "http:" && url.protocol !== "https:") throw new AiConfigError("AI URL must be an http or https URL");
         const path10 = url.pathname.replace(/\/+$/, "");
-        if (path10 === "" || path10 === "/v1" || path10 === "/api") {
+        if (path10 === "" || path10 === "/v1" || path10 === "/api" || path10 === "/v1beta/openai") {
           const suffix = provider === "anthropic" ? "/messages" : capability === "embed" ? "/embeddings" : "/chat/completions";
           url.pathname = (path10 || "/v1") + suffix;
         }
@@ -33495,7 +33520,7 @@ var init_aiClient = __esm({
       }
       static headers(config) {
         const headers = { "content-type": "application/json", accept: "application/json" };
-        if (config.provider === "openai") headers.authorization = `Bearer ${config.key}`;
+        if (config.provider === "openai" || config.provider === "gemini") headers.authorization = `Bearer ${config.key}`;
         if (config.provider === "anthropic") {
           headers["x-api-key"] = config.key;
           headers["anthropic-version"] = "2023-06-01";
@@ -41775,6 +41800,10 @@ async function recordApplied(db, name, batch, passed = 1) {
     insertCols.push("migration_id");
     values.push(name);
   }
+  if (cols.has("name")) {
+    insertCols.push("name");
+    values.push(name);
+  }
   if (isFirebirdAdapter(db)) {
     const rows = await adapterQuery(
       db,

package/packages/orm/src/migration.ts

@@ -524,6 +524,19 @@ async function recordApplied(
     values.push(name);
   }
 
+  // A table created by an OLDER Node v3 (<= 3.13.54) carries `name VARCHAR(500)
+  // NOT NULL` (the pre-3.13.55 tracking DDL — see git history). upgradeMigrationTable()
+  // copies its values into migration_name and leaves the `name` column in place
+  // (SQLite cannot drop a NOT NULL column without a full rebuild). Exactly like the
+  // python#93 `migration_id` case above, an insert that omits `name` fails its
+  // NOT NULL constraint, wedging EVERY migration recorded after the upgrade — so
+  // populate it here too, mirroring migration_name. A fresh canonical table has no
+  // `name` column, so this only fires on an upgraded legacy table.
+  if (cols.has("name")) {
+    insertCols.push("name");
+    values.push(name);
+  }
+
   if (isFirebirdAdapter(db)) {
     // Firebird: generate the id from the sequence.
     const rows = await adapterQuery<{ next_id: number }>(db,

package/packages/swagger/dist/index.js

@@ -521,13 +521,37 @@ function swaggerEnabled() {
   return ["true", "1", "yes", "on"].includes(raw);
 }
 function createSwaggerRoutes(getSpec) {
+  const serveUi = async (_req, res) => {
+    res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
+  };
   return [
     {
       method: "GET",
       pattern: "/swagger",
-      handler: async (_req, res) => {
-        res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
-      }
+      handler: serveUi
+    },
+    {
+      // The trailing-slash form, registered rather than left to fall through.
+      //
+      // Matching "/foo/" against a "/foo" route is opt-in via
+      // TINA4_TRAILING_SLASH_REDIRECT and OFF by default, so /swagger/ missed
+      // this route and was answered by the framework-bundled
+      // public/swagger/index.html instead. That mattered twice over. It used to
+      // be a 200 carrying a permanently empty UI, because the bundled file asked
+      // for an unsubstituted {SWAGGER_ROUTE}/swagger.json -- fixed in that file.
+      // And it is a SECOND Swagger UI implementation: the bundled one hardcodes
+      // cdnjs, while the page this handler renders loads from
+      // TINA4_SWAGGER_UI_CDN, so an air-gapped deployment pointing that at a
+      // local mirror silently kept reaching cdnjs on this one path.
+      //
+      // Registering it keeps the fix inside swagger rather than changing how
+      // every route treats trailing slashes, satisfies the shared contract that
+      // already requires a 200 here, and matches python and ruby, which both
+      // serve /swagger and /swagger/ with no env var set. Excluded from the
+      // generated document by INTERNAL_PREFIXES like /swagger itself.
+      method: "GET",
+      pattern: "/swagger/",
+      handler: serveUi
     },
     {
       method: "GET",

package/packages/swagger/src/ui.ts

@@ -56,13 +56,38 @@ export function swaggerEnabled(): boolean {
 export function createSwaggerRoutes(
   getSpec: () => unknown
 ): RouteDefinition[] {
+  const serveUi = async (_req: Tina4Request, res: Tina4Response): Promise<void> => {
+    res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
+  };
+
   return [
     {
       method: "GET",
       pattern: "/swagger",
-      handler: async (_req: Tina4Request, res: Tina4Response) => {
-        res.html(SWAGGER_UI_HTML("/swagger/openapi.json"));
-      },
+      handler: serveUi,
+    },
+    {
+      // The trailing-slash form, registered rather than left to fall through.
+      //
+      // Matching "/foo/" against a "/foo" route is opt-in via
+      // TINA4_TRAILING_SLASH_REDIRECT and OFF by default, so /swagger/ missed
+      // this route and was answered by the framework-bundled
+      // public/swagger/index.html instead. That mattered twice over. It used to
+      // be a 200 carrying a permanently empty UI, because the bundled file asked
+      // for an unsubstituted {SWAGGER_ROUTE}/swagger.json -- fixed in that file.
+      // And it is a SECOND Swagger UI implementation: the bundled one hardcodes
+      // cdnjs, while the page this handler renders loads from
+      // TINA4_SWAGGER_UI_CDN, so an air-gapped deployment pointing that at a
+      // local mirror silently kept reaching cdnjs on this one path.
+      //
+      // Registering it keeps the fix inside swagger rather than changing how
+      // every route treats trailing slashes, satisfies the shared contract that
+      // already requires a 200 here, and matches python and ruby, which both
+      // serve /swagger and /swagger/ with no env var set. Excluded from the
+      // generated document by INTERNAL_PREFIXES like /swagger itself.
+      method: "GET",
+      pattern: "/swagger/",
+      handler: serveUi,
     },
     {
       method: "GET",

package/types/core/src/aiClient.d.ts

@@ -113,7 +113,7 @@ export interface AiChatOptions {
     maxTokens?: number;
     stream?: boolean;
     timeout?: number;
-    provider?: "local" | "openai" | "anthropic";
+    provider?: "local" | "openai" | "anthropic" | "gemini";
     /** Tools the model may call. ADR-0061 — translated per provider. */
     tools?: AiToolDeclaration[];
     /**
@@ -126,7 +126,7 @@ export interface AiChatOptions {
 export interface AiEmbedOptions {
     model?: string;
     timeout?: number;
-    provider?: "local" | "openai" | "anthropic";
+    provider?: "local" | "openai" | "anthropic" | "gemini";
 }
 export declare class Ai {
     static chat(messages: AiMessage[], options: AiChatOptions & {