@fro.bot/systematic 2.12.3 → 2.13.1

package/README.md

@@ -326,7 +326,7 @@ Configuration is loaded from multiple locations and merged (later sources overri
 | `bootstrap.enabled` | `boolean` | `true` | Inject the `using-systematic` guide into system prompts |
 | `bootstrap.file` | `string` | — | Custom bootstrap file path (overrides default) |
 
-Agent overlays support `model`, `variant`, `temperature`, `top_p`, `permission`, `mode`, `color`, `steps`, `hidden`, exact-agent-only `disable`, and managed `skills`. `color` accepts `#RGB`, `#RRGGBB`, or OpenCode named color tokens matching `[a-zA-Z][a-zA-Z0-9-]*`; whitespace/freeform numeric strings are rejected. `skills` uses bundled skill frontmatter names like `ce:review`; it is a shortcut that writes OpenCode `permission.skill` rules, not a native OpenCode agent field. Because `model` and `variant` control provider routing/cost/privacy and `permission`/`skills` control tool access, those fields are only accepted from user config or `$OPENCODE_CONFIG_DIR/systematic.json`. Project config may tune non-sensitive presentation and runtime fields such as `temperature`, `top_p`, `mode`, `color`, `steps`, `hidden`, or exact-agent `disable`, but it cannot choose model/provider routing, tune `variant`, or loosen permission/capability policy.
+Agent overlays support `model`, `variant`, `temperature`, `top_p`, `permission`, `mode`, `color`, `steps`, `hidden`, exact-agent-only `disable`, and managed `skills`. `color` accepts `#RRGGBB` hex colors or OpenCode theme tokens: `primary`, `secondary`, `accent`, `success`, `warning`, `error`, and `info`. `skills` uses bundled skill frontmatter names like `ce:review`; it is a shortcut that writes OpenCode `permission.skill` rules, not a native OpenCode agent field. Because `model` and `variant` control provider routing/cost/privacy and `permission`/`skills` control tool access, those fields are only accepted from user config or `$OPENCODE_CONFIG_DIR/systematic.json`. Project config may tune non-sensitive presentation and runtime fields such as `temperature`, `top_p`, `mode`, `color`, `steps`, `hidden`, or exact-agent `disable`, but it cannot choose model/provider routing, tune `variant`, or loosen permission/capability policy.
 
 Systematic separates config-source precedence from overlay precedence. Config files merge in this order: user config, project config, then `$OPENCODE_CONFIG_DIR/systematic.json` if set. Higher-priority `agents.<key>` and `categories.<id>` entries replace lower-priority entries wholesale, while unrelated keys survive. Project overlays are the exception for trust-sensitive fields: same-key project overlays preserve user-level `model`, `variant`, `permission`, and `skills` fields instead of erasing them. After the effective config is built, Systematic applies agent overlay precedence for bundled agents:
 
@@ -338,20 +338,20 @@ Systematic separates config-source precedence from overlay precedence. Config fi
 
 Source category model defaults are primary model choices only — they are not fallback chains. Systematic does not support `fallback_models`, inherited retry semantics, runtime fallback behavior, or fallback to the parent model when a source model is unavailable. Explicit and source model IDs are structurally validated and may still fail at OpenCode runtime if the provider or model is unavailable.
 
-Source category model defaults are now ordered preference arrays per category rather than single strings. At plugin load, Systematic reads OpenCode's authentication state from `auth.json` and selects the first array entry whose provider is authenticated. For example, the `review` category defaults to `['anthropic/claude-sonnet-4-6', 'openai/gpt-5.3-codex']` — a user authenticated only to OpenAI receives `openai/gpt-5.5` (first match), while a user authenticated to Anthropic (or both) receives the more preferred `anthropic/claude-sonnet-4-6`. If no array entry's provider is authenticated, the first entry is used as the default. The arrays are an ordered preference list, not a runtime fallback chain — `fallback_models` is still not supported.
+Source category model defaults are ordered provider/model preference chains per category. At plugin load, Systematic asks OpenCode for connected providers through `client.config.providers()` and selects the first provider/model entry OpenCode reports as available. If the live provider query fails, Systematic falls back to OpenCode's `models.json` cache; if both sources fail, it skips source-default emission so bundled agents inherit the parent OpenCode model instead of pinning an unavailable model. The chains are ordered preference lists, not runtime fallback chains — `fallback_models` is still not supported.
 
 If you want to restore OpenCode parent-model inheritance for a bundled agent or category (opting out of the source default), set `"model": null` in high-trust user or `$OPENCODE_CONFIG_DIR/systematic.json` config. Project config cannot use `model: null` — project config cannot set, erase, or shadow `model` at any value.
 
 The source defaults are:
 
-| Category | Default `model` | Rationale |
-|----------|-----------------|-----------|
-| `design` | `github-copilot/gemini-3.1-pro-preview` | High-judgment UX/product/design work benefits from a strong general reasoning model. |
-| `docs` | `github-copilot/gemini-3.1-pro-preview` | Documentation and summarization should start cheaper/faster. |
-| `document-review` | `anthropic/claude-opus-4-7` | Requirements and plan critique benefit from strongest nuanced reasoning. |
-| `research` | `openai/gpt-5.4-mini` | Tool-heavy synthesis and source evaluation benefit from a strong general reasoning model. |
-| `review` | `anthropic/claude-sonnet-4-6` | Code/security/adversarial review benefits from strongest reasoning. |
-| `workflow` | `openai/gpt-5.4-mini` | Orchestration and bounded implementation should default cheaper/faster. |
+| Category | Chain | Rationale | When to Override |
+| --- | --- | --- | --- |
+| `design` | `github-copilot/gemini-3.1-pro-preview`, `openai/gpt-5.5` (`high`), `anthropic/claude-opus-4-7` (`max`), … | High-judgment UX, product, and design work benefits from a strong general reasoning model with broad creative capability. | Override to a faster/cheaper model when design tasks are primarily templating or low-stakes layout work. |
+| `docs` | `github-copilot/gemini-3.1-pro-preview`, `openai/gpt-5.4-mini`, `anthropic/claude-haiku-4-5`, … | Documentation and summarization tasks should start cheaper and faster; quality is sufficient at mid-tier models. | — |
+| `document-review` | `anthropic/claude-opus-4-7` (`max`), `openai/gpt-5.5` (`high`), `github-copilot/gemini-3.1-pro-preview`, … | Requirements and plan critique benefit from the strongest nuanced reasoning to surface non-obvious gaps and contradictions. | — |
+| `research` | `openai/gpt-5.4-mini`, `anthropic/claude-sonnet-4-6`, `github-copilot/gemini-3.1-pro-preview`, … | Tool-heavy synthesis and source evaluation benefit from a strong general reasoning model with broad knowledge. | — |
+| `review` | `anthropic/claude-sonnet-4-6`, `openai/gpt-5.3-codex`, `github-copilot/gemini-3.1-pro-preview`, … | Code, security, and adversarial review benefits from the strongest reasoning to catch subtle bugs and security issues. | Override to a faster model when review tasks are primarily style or formatting checks rather than correctness or security analysis. |
+| `workflow` | `openai/gpt-5.4-mini`, `anthropic/claude-sonnet-4-6`, `opencode/claude-haiku-4-5`, … | Orchestration and bounded implementation tasks should default cheaper and faster; strong reasoning is rarely needed for routing decisions. | — |
 
 These defaults are owned by Systematic code and emitted for bundled agents in each category when no stronger high-trust exact or category `model` override exists. Uncategorized bundled agents receive no source default and continue inheriting the parent OpenCode model. Native OpenCode agents with the same emitted key are full replacements and receive no Systematic source model default.
 

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   findCommandsInDir,
   findSkillsInDir,
   getConfigPaths
-} from "./index-gb1v2n3m.js";
+} from "./index-4qhjf4tb.js";
 
 // src/cli.ts
 import fs from "fs";

package/dist/{index-gb1v2n3m.js → index-4qhjf4tb.js}

@@ -12324,7 +12324,7 @@ function finalize(ctx, schema) {
     result.$schema = "http://json-schema.org/draft-07/schema#";
   } else if (ctx.target === "draft-04") {
     result.$schema = "http://json-schema.org/draft-04/schema#";
-  } else if (ctx.target === "openapi-3.0") {} else {}
+  } else if (ctx.target === "openapi-3.0") {}
   if (ctx.external?.uri) {
     const id = ctx.external.registry.get(schema)?.id;
     if (!id)
@@ -12568,7 +12568,7 @@ var literalProcessor = (schema, ctx, json, _params) => {
     if (val === undefined) {
       if (ctx.unrepresentable === "throw") {
         throw new Error("Literal `undefined` cannot be represented in JSON Schema");
-      } else {}
+      }
     } else if (typeof val === "bigint") {
       if (ctx.unrepresentable === "throw") {
         throw new Error("BigInt literals cannot be represented in JSON Schema");
@@ -15163,7 +15163,7 @@ var modelSchema = exports_external.string().min(1).regex(MODEL_FORMAT_REGEX, MOD
   description: "Model identifier in provider/model format, or null to inherit parent model",
   examples: ["anthropic/claude-sonnet-4", null]
 });
-var variantSchema = exports_external.string().min(1).regex(/^\S+$/, "must be a non-empty string without whitespace").meta({
+var variantSchema = exports_external.string().min(1).max(128, "variant must be at most 128 characters").regex(/^\S+$/, "must be a non-empty string without whitespace").meta({
   description: "Model variant identifier",
   examples: ["v2", "extended"]
 });
@@ -15296,13 +15296,6 @@ var SystematicConfigSchema = exports_external.object({
   description: "Systematic user configuration file (systematic.json / systematic.jsonc)",
   examples: [{ disabled_skills: ["ce:plan"], bootstrap: { enabled: false } }]
 });
-var SourceCategoryModelDefaultsSchema = exports_external.record(exports_external.string(), exports_external.array(exports_external.string().min(1).regex(MODEL_FORMAT_REGEX, MODEL_FORMAT_MESSAGE)).min(1)).meta({
-  description: "Validates source category model defaults shape",
-  examples: [{ design: ["openai/gpt-5.5", "anthropic/claude-opus-4-7"] }]
-});
-function assertSourceCategoryModelDefaults(defaults) {
-  SourceCategoryModelDefaultsSchema.parse(defaults);
-}
 var SECURITY_OVERLAY_FIELDS = [
   "model",
   "variant",
@@ -16101,4 +16094,4 @@ function findSkillsInDir(dir, maxDepth = 3) {
   return skills;
 }
 
-export { parseFrontmatter, AgentOverlaySchema, CategoryOverlaySchema, assertSourceCategoryModelDefaults, loadConfig, loadConfigWithSources, getConfigPaths, isRecord2 as isRecord, findAgentsInDir, extractAgentFrontmatter, findCommandsInDir, extractCommandFrontmatter, convertContent, convertFileWithCache, findSkillsInDir };
+export { parseFrontmatter, exports_external, AgentOverlaySchema, CategoryOverlaySchema, loadConfig, loadConfigWithSources, getConfigPaths, isRecord2 as isRecord, findAgentsInDir, extractAgentFrontmatter, findCommandsInDir, extractCommandFrontmatter, convertContent, convertFileWithCache, findSkillsInDir };

package/dist/index.js

@@ -2,8 +2,8 @@
 import {
   AgentOverlaySchema,
   CategoryOverlaySchema,
-  assertSourceCategoryModelDefaults,
   convertFileWithCache,
+  exports_external,
   extractAgentFrontmatter,
   extractCommandFrontmatter,
   findAgentsInDir,
@@ -13,12 +13,12 @@ import {
   loadConfig,
   loadConfigWithSources,
   parseFrontmatter
-} from "./index-gb1v2n3m.js";
+} from "./index-4qhjf4tb.js";
 
 // src/index.ts
-import fs4 from "fs";
-import path5 from "path";
-import { fileURLToPath } from "url";
+import fs5 from "fs";
+import path7 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/lib/bootstrap.ts
 import fs from "fs";
@@ -107,38 +107,232 @@ ${toolMapping}
 
 // src/lib/agent-overlays.ts
 import fs2 from "fs";
-import os2 from "os";
-import path2 from "path";
+import path3 from "path";
+
+// src/lib/source-model-defaults.ts
+import * as path2 from "path";
+import { fileURLToPath } from "url";
+var __filename2 = fileURLToPath(import.meta.url);
+var __dirname2 = path2.dirname(__filename2);
+var packageRoot = path2.resolve(__dirname2, "..", "..");
+var bundledAgentsDir = path2.join(packageRoot, "agents");
+var ProviderID = exports_external.union([
+  exports_external.literal("vercel"),
+  exports_external.literal("opencode"),
+  exports_external.literal("github-copilot"),
+  exports_external.literal("opencode-go"),
+  exports_external.literal("openai"),
+  exports_external.literal("anthropic"),
+  exports_external.literal("google")
+]);
+var variantSchema = exports_external.string().min(1, "variant must be a non-empty string").max(128, "variant must be at most 128 characters").regex(/^\S+$/, "variant must not contain whitespace");
+var tableCellSchema = exports_external.string().min(1, "must be a non-empty string").regex(/^[^|\r\n]+$/, "must not contain pipe (|) or newline characters \u2014 these break Markdown table generation");
+var ModelEntrySchema = exports_external.object({
+  model: exports_external.string().min(1, "model must be a non-empty string"),
+  variant: variantSchema.optional()
+}).strict();
+var ProviderEntrySchema = exports_external.object({
+  provider: ProviderID,
+  models: exports_external.array(ModelEntrySchema).min(1, "models must be non-empty \u2014 every provider entry must list at least one model")
+}).strict().refine((entry) => {
+  const seen = new Set;
+  for (const m of entry.models) {
+    const key = `${m.model}::${m.variant ?? ""}`;
+    if (seen.has(key))
+      return false;
+    seen.add(key);
+  }
+  return true;
+}, {
+  message: "duplicate (model, variant) pair within a provider entry \u2014 each model+variant combination must be unique"
+});
+var CategoryDefaultSchema = exports_external.object({
+  rationale: tableCellSchema,
+  whenToOverride: tableCellSchema.optional(),
+  providers: exports_external.array(ProviderEntrySchema).min(1, "providers must be non-empty \u2014 every category must list at least one provider")
+}).strict().refine((cat) => {
+  const seen = new Set;
+  for (const p of cat.providers) {
+    if (seen.has(p.provider))
+      return false;
+    seen.add(p.provider);
+  }
+  return true;
+}, {
+  message: "duplicate provider ID within a category \u2014 each provider must appear at most once per category"
+});
+var SourceCategoryDefaultsSchema = exports_external.record(exports_external.string(), CategoryDefaultSchema);
 var SOURCE_CATEGORY_MODEL_DEFAULTS = {
-  design: [
-    "github-copilot/gemini-3.1-pro-preview",
-    "openai/gpt-5.5",
-    "anthropic/claude-opus-4-7"
-  ],
-  docs: [
-    "github-copilot/gemini-3.1-pro-preview",
-    "openai/gpt-5.4-mini",
-    "anthropic/claude-haiku-4-5"
-  ],
-  "document-review": ["anthropic/claude-sonnet-4-6", "openai/gpt-5.4-mini"],
-  research: ["openai/gpt-5.4-mini", "anthropic/claude-sonnet-4-6"],
-  review: ["anthropic/claude-sonnet-4-6", "openai/gpt-5.3-codex"],
-  workflow: ["openai/gpt-5.4-mini", "anthropic/claude-sonnet-4-6"]
+  design: {
+    rationale: "High-judgment UX, product, and design work benefits from a strong general reasoning model with broad creative capability.",
+    whenToOverride: "Override to a faster/cheaper model when design tasks are primarily templating or low-stakes layout work.",
+    providers: [
+      {
+        provider: "github-copilot",
+        models: [{ model: "gemini-3.1-pro-preview" }]
+      },
+      {
+        provider: "openai",
+        models: [{ model: "gpt-5.5", variant: "high" }]
+      },
+      {
+        provider: "anthropic",
+        models: [{ model: "claude-opus-4-7", variant: "max" }]
+      },
+      {
+        provider: "vercel",
+        models: [{ model: "v0-1.5-md" }]
+      }
+    ]
+  },
+  docs: {
+    rationale: "Documentation and summarization tasks should start cheaper and faster; quality is sufficient at mid-tier models.",
+    providers: [
+      {
+        provider: "github-copilot",
+        models: [{ model: "gemini-3.1-pro-preview" }]
+      },
+      {
+        provider: "openai",
+        models: [{ model: "gpt-5.4-mini" }]
+      },
+      {
+        provider: "anthropic",
+        models: [{ model: "claude-haiku-4-5" }]
+      },
+      {
+        provider: "opencode",
+        models: [{ model: "claude-haiku-4-5" }]
+      }
+    ]
+  },
+  "document-review": {
+    rationale: "Requirements and plan critique benefit from the strongest nuanced reasoning to surface non-obvious gaps and contradictions.",
+    providers: [
+      {
+        provider: "anthropic",
+        models: [{ model: "claude-opus-4-7", variant: "max" }]
+      },
+      {
+        provider: "openai",
+        models: [{ model: "gpt-5.5", variant: "high" }]
+      },
+      {
+        provider: "github-copilot",
+        models: [{ model: "gemini-3.1-pro-preview" }]
+      },
+      {
+        provider: "opencode",
+        models: [{ model: "claude-sonnet-4-6" }]
+      }
+    ]
+  },
+  research: {
+    rationale: "Tool-heavy synthesis and source evaluation benefit from a strong general reasoning model with broad knowledge.",
+    providers: [
+      {
+        provider: "openai",
+        models: [{ model: "gpt-5.4-mini" }]
+      },
+      {
+        provider: "anthropic",
+        models: [{ model: "claude-sonnet-4-6" }]
+      },
+      {
+        provider: "github-copilot",
+        models: [{ model: "gemini-3.1-pro-preview" }]
+      },
+      {
+        provider: "opencode",
+        models: [{ model: "claude-sonnet-4-6" }]
+      }
+    ]
+  },
+  review: {
+    rationale: "Code, security, and adversarial review benefits from the strongest reasoning to catch subtle bugs and security issues.",
+    whenToOverride: "Override to a faster model when review tasks are primarily style or formatting checks rather than correctness or security analysis.",
+    providers: [
+      {
+        provider: "anthropic",
+        models: [{ model: "claude-sonnet-4-6" }]
+      },
+      {
+        provider: "openai",
+        models: [{ model: "gpt-5.3-codex" }]
+      },
+      {
+        provider: "github-copilot",
+        models: [{ model: "gemini-3.1-pro-preview" }]
+      },
+      {
+        provider: "opencode",
+        models: [{ model: "claude-sonnet-4-6" }]
+      }
+    ]
+  },
+  workflow: {
+    rationale: "Orchestration and bounded implementation tasks should default cheaper and faster; strong reasoning is rarely needed for routing decisions.",
+    providers: [
+      {
+        provider: "openai",
+        models: [{ model: "gpt-5.4-mini" }]
+      },
+      {
+        provider: "anthropic",
+        models: [{ model: "claude-sonnet-4-6" }]
+      },
+      {
+        provider: "opencode",
+        models: [{ model: "claude-haiku-4-5" }]
+      },
+      {
+        provider: "opencode-go",
+        models: [{ model: "claude-haiku-4-5" }]
+      }
+    ]
+  }
 };
+function resolveSourceModel(category, availabilitySet) {
+  const categoryDefault = SOURCE_CATEGORY_MODEL_DEFAULTS[category];
+  if (!categoryDefault) {
+    throw new Error(`resolveSourceModel: unknown category "${category}". Valid categories: ${Object.keys(SOURCE_CATEGORY_MODEL_DEFAULTS).join(", ")}`);
+  }
+  for (const providerEntry of categoryDefault.providers) {
+    for (const modelEntry of providerEntry.models) {
+      const key = `${providerEntry.provider}/${modelEntry.model}`;
+      if (availabilitySet.has(key)) {
+        return {
+          provider: providerEntry.provider,
+          model: modelEntry.model,
+          variant: modelEntry.variant
+        };
+      }
+    }
+  }
+  const firstProvider = categoryDefault.providers[0];
+  const firstModel = firstProvider.models[0];
+  return {
+    provider: firstProvider.provider,
+    model: firstModel.model,
+    variant: firstModel.variant
+  };
+}
+
+// src/lib/agent-overlays.ts
 function buildBundledAgentInventory(agentsDir, disabledAgents) {
   const categories = readCategoryDirs(agentsDir);
   const agentsByQualifiedId = {};
   const stemCategories = new Map;
   const disabledSet = new Set(disabledAgents);
   for (const category of categories) {
-    for (const fileName of readMarkdownFiles(path2.join(agentsDir, category))) {
+    for (const fileName of readMarkdownFiles(path3.join(agentsDir, category))) {
       const key = fileName.replace(/\.md$/, "");
       const id = `${category}/${key}`;
       agentsByQualifiedId[id] = {
         id,
         key,
         category,
-        file: path2.join(agentsDir, category, fileName),
+        file: path3.join(agentsDir, category, fileName),
         disabled: disabledSet.has(key) || disabledSet.has(id)
       };
       const existing = stemCategories.get(key) ?? [];
@@ -191,62 +385,12 @@ function inferBuiltInTemperature(name, description) {
   }
   return 0.3;
 }
-function getAuthenticatedProviders(rootDirOverride) {
-  const xdgDataHome = process.env.XDG_DATA_HOME?.trim();
-  const rootDir = rootDirOverride || (xdgDataHome && path2.isAbsolute(xdgDataHome) ? xdgDataHome : path2.join(os2.homedir(), ".local/share"));
-  const authPath = path2.join(rootDir, "opencode", "auth.json");
-  let raw;
-  try {
-    raw = fs2.readFileSync(authPath, "utf8");
-  } catch (err) {
-    if (isSystemError(err) && err.code === "ENOENT") {
-      return new Set;
-    }
-    console.warn(`[systematic] auth.json unreadable at ${authPath}; ignoring`);
-    return new Set;
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    console.warn(`[systematic] auth.json malformed at ${authPath}; ignoring`);
-    return new Set;
-  }
-  if (!isRecord(parsed)) {
-    console.warn(`[systematic] auth.json malformed at ${authPath}; ignoring`);
-    return new Set;
-  }
-  return new Set(Object.keys(parsed));
-}
-function getSourceCategoryModel(category, authedProviders) {
-  if (!category)
-    return;
-  const candidates = SOURCE_CATEGORY_MODEL_DEFAULTS[category];
-  if (!candidates || candidates.length === 0)
-    return;
-  if (!authedProviders || authedProviders.size === 0)
-    return candidates[0];
-  for (const entry of candidates) {
-    const slashIndex = entry.indexOf("/");
-    if (slashIndex <= 0)
-      continue;
-    const providerId = entry.slice(0, slashIndex);
-    if (authedProviders.has(providerId)) {
-      return entry;
-    }
-  }
-  return candidates[0];
-}
 function assertSourceCategoryModelCoverage(categories) {
-  validateSourceCategoryModelDefaults();
   const missingCategories = categories.filter((category) => !Object.hasOwn(SOURCE_CATEGORY_MODEL_DEFAULTS, category));
   if (missingCategories.length > 0) {
     throw new Error(`Source category model defaults missing intentional coverage for: ${missingCategories.join(", ")}`);
   }
 }
-function validateSourceCategoryModelDefaults(defaults = SOURCE_CATEGORY_MODEL_DEFAULTS) {
-  assertSourceCategoryModelDefaults(defaults);
-}
 function validateExactAgentOverlays(inventory, overlays, nativeAgents, enabledSkills) {
   const result = [];
   const seenTargets = new Map;
@@ -347,12 +491,158 @@ function validAgentKeys(inventory) {
 function throwConfigError(sourcePath, keyPath, message) {
   throw new Error(`Invalid Systematic config in ${sourcePath}: ${keyPath} ${message}`);
 }
-function isSystemError(err) {
-  return typeof err === "object" && err !== null && "code" in err && typeof err.code === "string";
+
+// src/lib/model-availability.ts
+import { createHash } from "crypto";
+import fs3 from "fs";
+import os2 from "os";
+import path4 from "path";
+function emptyAvailability() {
+  return { status: "unknown", models: new Set };
+}
+var MAX_CACHE_FILE_BYTES = 16 * 1024 * 1024;
+var DEFAULT_API_TIMEOUT_MS = 1500;
+var MODELS_JSON_FILENAME = "models.json";
+function resolveCacheDir() {
+  const xdgCacheHome = process.env.XDG_CACHE_HOME?.trim();
+  const cacheBase = xdgCacheHome && path4.isAbsolute(xdgCacheHome) ? xdgCacheHome : path4.join(os2.homedir(), ".cache");
+  return path4.join(cacheBase, "opencode");
+}
+function fastHash(input) {
+  return createHash("sha1").update(input).digest("hex");
+}
+function isProviderRecord(value) {
+  if (!isRecord(value))
+    return false;
+  for (const entry of Object.values(value)) {
+    if (!isRecord(entry))
+      return false;
+    if (!isRecord(entry.models))
+      return false;
+  }
+  return true;
+}
+function readModelsFromCache(filePath) {
+  let fd;
+  try {
+    fd = fs3.openSync(filePath, "r");
+  } catch {
+    return null;
+  }
+  let raw;
+  try {
+    let stat;
+    try {
+      stat = fs3.fstatSync(fd);
+    } catch {
+      return null;
+    }
+    if (!stat.isFile())
+      return null;
+    if (stat.size === 0)
+      return null;
+    if (stat.size > MAX_CACHE_FILE_BYTES) {
+      console.warn(`[systematic] models.json at ${filePath} is ${stat.size} bytes (>${MAX_CACHE_FILE_BYTES}); treating as cache miss.`);
+      return null;
+    }
+    const buffer = Buffer.alloc(stat.size);
+    let bytesRead;
+    try {
+      bytesRead = fs3.readSync(fd, buffer, 0, stat.size, 0);
+    } catch {
+      return null;
+    }
+    if (bytesRead !== stat.size)
+      return null;
+    raw = buffer.toString("utf8");
+  } finally {
+    try {
+      fs3.closeSync(fd);
+    } catch {}
+  }
+  if (raw.trim().length === 0)
+    return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isProviderRecord(parsed)) {
+    console.warn(`[systematic] models.json schema mismatch at ${filePath}; treating as cache miss. Upstream shape may have drifted.`);
+    return null;
+  }
+  const result = new Set;
+  for (const [providerId, providerData] of Object.entries(parsed)) {
+    for (const modelId of Object.keys(providerData.models)) {
+      result.add(`${providerId}/${modelId}`);
+    }
+  }
+  return result;
+}
+function readFallbackCache() {
+  const cacheDir = resolveCacheDir();
+  const openCodeModelsUrl = process.env.OPENCODE_MODELS_URL?.trim();
+  if (openCodeModelsUrl) {
+    const urlDerivedPath = path4.join(cacheDir, `models-${fastHash(openCodeModelsUrl)}.json`);
+    const urlResult = readModelsFromCache(urlDerivedPath);
+    if (urlResult !== null) {
+      return { status: "cache", models: urlResult };
+    }
+  }
+  const defaultPath = path4.join(cacheDir, MODELS_JSON_FILENAME);
+  const defaultResult = readModelsFromCache(defaultPath);
+  if (defaultResult !== null) {
+    return { status: "cache", models: defaultResult };
+  }
+  return emptyAvailability();
+}
+function buildSetFromProviders(providers) {
+  const result = new Set;
+  for (const provider of providers) {
+    for (const modelId of Object.keys(provider.models)) {
+      result.add(`${provider.id}/${modelId}`);
+    }
+  }
+  return result;
+}
+async function getAvailableModels(client, options = {}) {
+  const timeoutMs = options.apiTimeoutMs === undefined ? DEFAULT_API_TIMEOUT_MS : options.apiTimeoutMs;
+  if (typeof client.config?.providers !== "function") {
+    return readFallbackCache();
+  }
+  const apiCall = client.config.providers();
+  let response;
+  try {
+    if (timeoutMs === null) {
+      response = await apiCall;
+    } else {
+      const TIMEOUT_SENTINEL = Symbol("timeout");
+      const timeoutPromise = new Promise((resolve2) => {
+        const timer = setTimeout(() => resolve2(TIMEOUT_SENTINEL), timeoutMs);
+        timer.unref?.();
+      });
+      const raced = await Promise.race([apiCall, timeoutPromise]);
+      if (raced === TIMEOUT_SENTINEL) {
+        console.warn(`[systematic] client.config.providers() exceeded ${timeoutMs}ms; falling back to models.json cache.`);
+        return readFallbackCache();
+      }
+      response = raced;
+    }
+  } catch {
+    return readFallbackCache();
+  }
+  if (response.error !== undefined || response.data === undefined) {
+    return readFallbackCache();
+  }
+  return {
+    status: "api",
+    models: buildSetFromProviders(response.data.providers)
+  };
 }
 
 // src/lib/skill-loader.ts
-import path3 from "path";
+import path5 from "path";
 var SKILL_PREFIX = "systematic:";
 var SKILL_DESCRIPTION_PREFIX = "(Systematic - Skill) ";
 function formatSkillCommandName(name) {
@@ -369,7 +659,7 @@ function formatSkillDescription(description, fallbackName) {
   return `${SKILL_DESCRIPTION_PREFIX}${desc}`;
 }
 function wrapSkillTemplate(skillPath, body) {
-  const skillDir = path3.dirname(skillPath);
+  const skillDir = path5.dirname(skillPath);
   return `<skill-instruction>
 Base directory for this skill: ${skillDir}/
 File references (@path) in this skill are relative to this directory.
@@ -519,7 +809,7 @@ function loadSkillAsCommand(loaded) {
     config.subtask = loaded.subtask;
   return config;
 }
-function collectAgents(dir, disabledAgents, nativeAgents, overlays, authedProviders) {
+function collectAgents(dir, disabledAgents, nativeAgents, overlays, availabilitySet) {
   const agents = {};
   const agentList = findAgentsInDir(dir);
   const disabledSet = new Set(disabledAgents);
@@ -534,12 +824,12 @@ function collectAgents(dir, disabledAgents, nativeAgents, overlays, authedProvid
       continue;
     const config = loadAgentAsConfig(agentInfo);
     if (config) {
-      agents[agentInfo.name] = applyAgentOverlays(config, agentInfo, overlays, authedProviders);
+      agents[agentInfo.name] = applyAgentOverlays(config, agentInfo, overlays, availabilitySet);
     }
   }
   return agents;
 }
-function applyAgentOverlays(config, agentInfo, overlays, authedProviders) {
+function applyAgentOverlays(config, agentInfo, overlays, availabilitySet) {
   const id = agentInfo.category ? `${agentInfo.category}/${agentInfo.name}` : agentInfo.name;
   const categoryOverlay = agentInfo.category ? overlays.categoriesByKey.get(agentInfo.category) : undefined;
   const exactOverlay = overlays.agentsByTargetId.get(id);
@@ -550,17 +840,20 @@ function applyAgentOverlays(config, agentInfo, overlays, authedProviders) {
     addPermissionRules(permissionRules, config.permission);
   }
   result.temperature = inferBuiltInTemperature(agentInfo.name, result.description);
-  if (agentInfo.category) {
-    const sourceModel = getSourceCategoryModel(agentInfo.category, authedProviders);
-    if (sourceModel) {
-      result.model = sourceModel;
+  if (agentInfo.category && availabilitySet !== undefined) {
+    const resolved = resolveSourceModel(agentInfo.category, availabilitySet);
+    result.model = `${resolved.provider}/${resolved.model}`;
+    if (resolved.variant !== undefined) {
+      result.variant = resolved.variant;
+    } else {
+      delete result.variant;
     }
   }
   if (categoryOverlay) {
-    applyOverlayObject(result, categoryOverlay.value, permissionRules);
+    applyOverlayObjectWithVariantClearing(result, categoryOverlay.value, permissionRules);
   }
   if (exactOverlay) {
-    applyOverlayObject(result, exactOverlay.value, permissionRules);
+    applyOverlayObjectWithVariantClearing(result, exactOverlay.value, permissionRules);
   }
   if (hasPermissionOverlay) {
     const permission = permissionFromRules(permissionRules);
@@ -585,7 +878,12 @@ var OVERLAY_ASSIGN_FIELDS = [
   "steps",
   "hidden"
 ];
-function applyOverlayObject(target, overlay, permissionRules) {
+function applyOverlayObjectWithVariantClearing(target, overlay, permissionRules) {
+  const overlayHasModel = Object.hasOwn(overlay, "model");
+  const overlayHasVariant = Object.hasOwn(overlay, "variant");
+  if (overlayHasModel && !overlayHasVariant) {
+    delete target.variant;
+  }
   for (const field of OVERLAY_ASSIGN_FIELDS) {
     if (Object.hasOwn(overlay, field)) {
       if (field === "model" && overlay[field] === null) {
@@ -680,15 +978,14 @@ function collectEnabledSkillNames(dir, disabledSkills) {
   return findSkillsInDir(dir).filter((skillInfo) => !disabledSet.has(skillInfo.name)).map((skillInfo) => skillInfo.name);
 }
 function createConfigHandler(deps) {
-  const { directory, bundledSkillsDir, bundledAgentsDir, bundledCommandsDir } = deps;
-  const readAuthProviders = deps.getAuthenticatedProviders ?? getAuthenticatedProviders;
+  const { directory, bundledSkillsDir, bundledAgentsDir: bundledAgentsDir2, bundledCommandsDir } = deps;
   return async (config) => {
     const { config: systematicConfig, overlays } = loadConfigWithSources(directory);
     const existingAgents = { ...config.agent ?? {} };
     const existingCommands = { ...config.command ?? {} };
     const bundledSkills = collectSkillsAsCommands(bundledSkillsDir, systematicConfig.disabled_skills);
     const enabledSkillNames = collectEnabledSkillNames(bundledSkillsDir, systematicConfig.disabled_skills);
-    const inventory = buildBundledAgentInventory(bundledAgentsDir, systematicConfig.disabled_agents);
+    const inventory = buildBundledAgentInventory(bundledAgentsDir2, systematicConfig.disabled_agents);
     assertSourceCategoryModelCoverage(inventory.categories);
     const validatedOverlays = validateAgentOverlays({
       inventory,
@@ -697,8 +994,9 @@ function createConfigHandler(deps) {
       enabledSkills: enabledSkillNames
     });
     const resolvedOverlays = resolveAgentOverlaySet(validatedOverlays);
-    const authedProviders = readAuthProviders();
-    const bundledAgents = collectAgents(bundledAgentsDir, systematicConfig.disabled_agents, existingAgents, resolvedOverlays, authedProviders);
+    const availability = deps.client ? await getAvailableModels(deps.client) : undefined;
+    const availabilitySet = availability && availability.status !== "unknown" ? availability.models : undefined;
+    const bundledAgents = collectAgents(bundledAgentsDir2, systematicConfig.disabled_agents, existingAgents, resolvedOverlays, availabilitySet);
     const bundledCommands = collectCommands(bundledCommandsDir, systematicConfig.disabled_commands);
     config.agent = {
       ...bundledAgents,
@@ -723,8 +1021,8 @@ function registerSkillsPaths(config, skillsDir) {
 }
 
 // src/lib/skill-tool.ts
-import fs3 from "fs";
-import path4 from "path";
+import fs4 from "fs";
+import path6 from "path";
 import { pathToFileURL } from "url";
 import { tool } from "@opencode-ai/plugin/tool";
 function formatSkillsXml(skills) {
@@ -750,17 +1048,17 @@ function discoverSkillFiles(dir, limit = 10) {
   function handleEntry(entry, currentDir) {
     if (entry.isDirectory()) {
       if (!shouldSkipDirectory(entry.name)) {
-        recurse(path4.resolve(currentDir, entry.name));
+        recurse(path6.resolve(currentDir, entry.name));
       }
     } else if (shouldIncludeFile(entry.name)) {
-      files.push(path4.resolve(currentDir, entry.name));
+      files.push(path6.resolve(currentDir, entry.name));
     }
   }
   function recurse(currentDir) {
     if (files.length >= limit)
       return;
     try {
-      const entries = fs3.readdirSync(currentDir, { withFileTypes: true });
+      const entries = fs4.readdirSync(currentDir, { withFileTypes: true });
       for (const entry of entries) {
         if (files.length >= limit)
           break;
@@ -841,7 +1139,7 @@ function createSkillTool(options) {
         throw new Error(`Skill "${requestedName}" not found. Available systematic skills: ${availableSystematic.join(", ")}`);
       }
       const body = extractSkillBody(matchedSkill.wrappedTemplate);
-      const dir = path4.dirname(matchedSkill.skillFile);
+      const dir = path6.dirname(matchedSkill.skillFile);
       const base = pathToFileURL(dir).href;
       const files = discoverSkillFiles(dir);
       await context.ask({
@@ -878,17 +1176,17 @@ function createSkillTool(options) {
 }
 
 // src/index.ts
-var __dirname2 = path5.dirname(fileURLToPath(import.meta.url));
-var packageRoot = path5.resolve(__dirname2, "..");
-var bundledSkillsDir = path5.join(packageRoot, "skills");
-var bundledAgentsDir = path5.join(packageRoot, "agents");
-var bundledCommandsDir = path5.join(packageRoot, "commands");
-var packageJsonPath = path5.join(packageRoot, "package.json");
+var __dirname3 = path7.dirname(fileURLToPath2(import.meta.url));
+var packageRoot2 = path7.resolve(__dirname3, "..");
+var bundledSkillsDir = path7.join(packageRoot2, "skills");
+var bundledAgentsDir2 = path7.join(packageRoot2, "agents");
+var bundledCommandsDir = path7.join(packageRoot2, "commands");
+var packageJsonPath = path7.join(packageRoot2, "package.json");
 var getPackageVersion = () => {
   try {
-    if (!fs4.existsSync(packageJsonPath))
+    if (!fs5.existsSync(packageJsonPath))
       return "unknown";
-    const content = fs4.readFileSync(packageJsonPath, "utf8");
+    const content = fs5.readFileSync(packageJsonPath, "utf8");
     const parsed = JSON.parse(content);
     return parsed.version ?? "unknown";
   } catch {
@@ -902,8 +1200,9 @@ var initializePlugin = async ({ client, directory }) => {
   const configHandler = createConfigHandler({
     directory,
     bundledSkillsDir,
-    bundledAgentsDir,
-    bundledCommandsDir
+    bundledAgentsDir: bundledAgentsDir2,
+    bundledCommandsDir,
+    client
   });
   return {
     config: configHandler,

package/dist/lib/agent-overlays.d.ts

@@ -42,27 +42,4 @@ export declare function buildBundledAgentInventory(agentsDir: string, disabledAg
 export declare function validateAgentOverlays({ inventory, overlays, nativeAgents, enabledSkills, }: ValidateAgentOverlaysOptions): ValidatedAgentOverlays;
 export declare function resolveAgentOverlaySet(overlays: ValidatedAgentOverlays): ResolvedAgentOverlaySet;
 export declare function inferBuiltInTemperature(name: string, description?: string): number;
-/**
- * Read which providers are authenticated from OpenCode's auth.json.
- *
- * Reads only top-level keys (provider IDs). Nested values are NEVER
- * inspected, logged, persisted, or transmitted. This is a hard contract:
- * the auth file holds API keys and OAuth tokens, and Systematic must
- * never expose them via stderr, telemetry, or any other channel.
- *
- * Intended for one invocation per plugin config(cfg) cycle. Repeated
- * calls trigger repeated file reads and, on malformed input, repeated
- * stderr diagnostics.
- *
- * @param rootDirOverride - Optional path override for tests. When
- *   non-empty, the auth file is resolved as
- *   `path.join(rootDirOverride, 'opencode', 'auth.json')`. When
- *   omitted, resolution follows XDG_DATA_HOME -> ~/.local/share
- *   convention.
- * @returns A readonly set of authenticated provider IDs (empty set on
- *   any failure).
- */
-export declare function getAuthenticatedProviders(rootDirOverride?: string): ReadonlySet<string>;
-export declare function getSourceCategoryModel(category: string | undefined, authedProviders?: ReadonlySet<string>): string | undefined;
 export declare function assertSourceCategoryModelCoverage(categories: string[]): void;
-export declare function validateSourceCategoryModelDefaults(defaults?: Record<string, unknown>): void;

package/dist/lib/config-handler.d.ts

@@ -1,11 +1,12 @@
 import type { Config } from '@opencode-ai/plugin';
+import { type OpencodeClientLike } from './model-availability.js';
 export interface ConfigHandlerDeps {
     directory: string;
     bundledSkillsDir: string;
     bundledAgentsDir: string;
     bundledCommandsDir: string;
-    /** Override for authenticated provider reader; for testing. */
-    getAuthenticatedProviders?: (rootDirOverride?: string) => ReadonlySet<string>;
+    /** OpenCode client for availability lookup. When omitted, availability falls back to empty set (last-resort resolution). */
+    client?: OpencodeClientLike;
 }
 export declare function toTitleCase(name: string): string;
 export declare function formatAgentDescription(name: string, description: string | undefined): string;

package/dist/lib/config-schema.d.ts

@@ -166,7 +166,6 @@ export type ValidationResult = {
     errors: readonly z.ZodIssue[];
 };
 export declare function validateConfig(input: unknown): ValidationResult;
-export declare function assertSourceCategoryModelDefaults(defaults: Record<string, unknown>): void;
 /**
  * Overlay fields that require a project-or-higher trust source.
  *

package/dist/lib/model-availability.d.ts

@@ -0,0 +1,77 @@
+interface ConnectedProvider {
+    id: string;
+    models: Record<string, unknown>;
+}
+interface ProvidersResponse {
+    providers: ConnectedProvider[];
+    default: Record<string, string>;
+}
+interface ClientConfigApi {
+    providers: () => Promise<{
+        data: ProvidersResponse;
+        error: undefined;
+    } | {
+        data: undefined;
+        error: unknown;
+    }>;
+}
+export interface OpencodeClientLike {
+    config: ClientConfigApi;
+}
+/**
+ * Outcome of model availability discovery.
+ *
+ * - `api`: The OpenCode server's `/config/providers` endpoint responded with
+ *   a connected-providers payload. `models` may be empty if no providers
+ *   are authenticated; that is authoritative.
+ * - `cache`: The API call failed (error envelope, thrown, or timed out) and
+ *   the local `models.json` cache was readable. `models` reflects whatever
+ *   OpenCode last wrote to disk.
+ * - `unknown`: Both the API call and the cache fallback failed (cache
+ *   missing, unreadable, corrupt, or schema-mismatched). Resolution should
+ *   degrade gracefully — callers should treat `unknown` as a signal to
+ *   skip source-default model pinning so users do not get agents pinned
+ *   to inaccessible models. `models` is the empty set.
+ */
+export type DiscoveryStatus = 'api' | 'cache' | 'unknown';
+export interface ModelAvailability {
+    status: DiscoveryStatus;
+    /**
+     * Set of `${providerId}/${modelId}` strings. Typed `ReadonlySet` because
+     * callers must not mutate the returned collection — mutation would corrupt
+     * future calls in the same process. Each `ModelAvailability` is a fresh
+     * instance (see `emptyAvailability()`), so mutation via cast cannot
+     * propagate, but the type makes intent explicit.
+     */
+    models: ReadonlySet<string>;
+}
+interface AvailabilityOptions {
+    /**
+     * Maximum time to wait for `client.config.providers()` before falling
+     * back to the local cache. Defaults to 1500ms — a startup-budget value
+     * that prevents a slow/half-open OpenCode server from holding the plugin
+     * indefinitely.
+     *
+     * Set to `null` to disable the timeout entirely (not recommended).
+     */
+    apiTimeoutMs?: number | null;
+}
+/**
+ * Discover the set of `provider/model` keys the OpenCode server considers
+ * connected (or, on API failure, the set last written to the on-disk
+ * `models.json` cache).
+ *
+ * The returned `status` lets callers distinguish three discovery outcomes:
+ * - `api`: live answer; safe to pin source-default models against it
+ * - `cache`: degraded but informed; the cached `provider/model` keys are
+ *   plausibly still authoritative
+ * - `unknown`: both the API and the cache failed; callers should fall back
+ *   to OpenCode's parent-model inheritance rather than pinning a source
+ *   default the user may not have access to
+ *
+ * The API call is bounded by `apiTimeoutMs` (default 1500ms). On timeout,
+ * thrown error, error-envelope response, or undefined data, the cache
+ * fallback runs. The function never rejects.
+ */
+export declare function getAvailableModels(client: OpencodeClientLike, options?: AvailabilityOptions): Promise<ModelAvailability>;
+export {};

package/dist/lib/source-model-defaults.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Provider-grouped source category model defaults for Systematic bundled agents.
+ *
+ * This module owns the canonical shape, Zod schema, and constant for the
+ * per-category model resolution chain. The resolution algorithm walks
+ * the provider list in order and picks the first available provider/model pair.
+ *
+ * Provider catalog is constrained to the 7 IDs with empirical OMO usage-frequency
+ * justification: vercel=80, opencode=55, github-copilot=39, opencode-go=26,
+ * openai=20, anthropic=18, google=10.
+ */
+import { z } from 'zod';
+/**
+ * Zod literal union of the 7 supported provider IDs.
+ * Ordered by OMO empirical usage frequency (highest first).
+ */
+export declare const ProviderID: z.ZodUnion<readonly [z.ZodLiteral<"vercel">, z.ZodLiteral<"opencode">, z.ZodLiteral<"github-copilot">, z.ZodLiteral<"opencode-go">, z.ZodLiteral<"openai">, z.ZodLiteral<"anthropic">, z.ZodLiteral<"google">]>;
+export type ProviderID = z.infer<typeof ProviderID>;
+/**
+ * Zod schema for the full source category model defaults map.
+ *
+ * Schema is **pure** — it validates only structural correctness:
+ * - Shape correctness (CategoryDefaultSchema per value)
+ * - Provider lists non-empty (enforced by CategoryDefaultSchema)
+ * - Model lists non-empty (enforced by ProviderEntrySchema)
+ * - (model, variant) pairs unique within a provider entry
+ * - Provider IDs unique within a category
+ * - variant is non-empty, whitespace-free, max 128 chars
+ * - `rationale` and `whenToOverride` reject pipe (`|`) and newline characters
+ *   so the generator produces well-formed Markdown tables
+ *
+ * Filesystem coverage (every key resolves to a real `agents/<category>/`
+ * directory) is NOT checked here. Use `assertCategoryCoverageOnDisk` to
+ * enforce that invariant from tests where it matters; the production
+ * runtime path uses `assertSourceCategoryModelCoverage` from
+ * `agent-overlays.ts` against an in-memory inventory rather than reading
+ * disk again.
+ */
+export declare const SourceCategoryDefaultsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    rationale: z.ZodString;
+    whenToOverride: z.ZodOptional<z.ZodString>;
+    providers: z.ZodArray<z.ZodObject<{
+        provider: z.ZodUnion<readonly [z.ZodLiteral<"vercel">, z.ZodLiteral<"opencode">, z.ZodLiteral<"github-copilot">, z.ZodLiteral<"opencode-go">, z.ZodLiteral<"openai">, z.ZodLiteral<"anthropic">, z.ZodLiteral<"google">]>;
+        models: z.ZodArray<z.ZodObject<{
+            model: z.ZodString;
+            variant: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>>;
+/**
+ * Verify that every category key in `categories` maps to a real
+ * `agents/<category>/` directory on disk under `agentsDir` (defaulting to
+ * the package's bundled-agents directory). Throws with a useful message if
+ * any keys are unrecognized.
+ *
+ * Use from tests to lock the SOURCE_CATEGORY_MODEL_DEFAULTS ↔ agents/
+ * directory layout contract. The production runtime path validates the
+ * inverse direction (every bundled-agent category has a source default)
+ * via `assertSourceCategoryModelCoverage` in `agent-overlays.ts`.
+ */
+export declare function assertCategoryCoverageOnDisk(categories: readonly string[], agentsDir?: string): void;
+export interface ModelEntry {
+    model: string;
+    variant?: string;
+}
+export interface ProviderEntry {
+    provider: ProviderID;
+    models: ModelEntry[];
+}
+export interface CategoryDefault {
+    rationale: string;
+    whenToOverride?: string;
+    providers: ProviderEntry[];
+}
+export type SourceCategoryDefaults = Record<string, CategoryDefault>;
+/**
+ * Provider-grouped source model defaults for the 6 Systematic agent categories.
+ *
+ * Provider chains are ordered by OMO category-fit reasoning. The resolver
+ * walks providers in order and picks the first available provider/model pair.
+ * If no provider is available, the first entry of the first provider is used as
+ * the last-resort fallback.
+ *
+ * Model choices translate the existing flat-string-array constant in agent-overlays.ts
+ * to the new provider-grouped shape, with variant annotations where applicable.
+ */
+export declare const SOURCE_CATEGORY_MODEL_DEFAULTS: SourceCategoryDefaults;
+/**
+ * Format the SOURCE_CATEGORY_MODEL_DEFAULTS as a GitHub-flavored markdown table
+ * for injection into documentation.
+ *
+ * Columns: Category | Chain | Rationale | When to Override
+ *
+ * Chain format: comma-separated `provider/model[+variant]` for the first 2–3
+ * provider entries (first model per provider). Appends `, …` when there are
+ * more than 3 provider entries.
+ *
+ * Returns a string ending with `\n` for clean concatenation.
+ */
+export declare function formatForDocs(): string;
+/**
+ * Walk the provider-grouped shape for a category and return the first available
+ * provider/model pair from the availability set.
+ *
+ * Algorithm:
+ * 1. Look up the category. Unknown category is a programmer error — throw.
+ * 2. Walk providers in declared order. For each provider, walk its models in
+ *    declared order and test `${provider}/${model}` membership in availabilitySet.
+ * 3. On first hit, return { provider, model, variant? }.
+ * 4. Last-resort fallback (no available model anywhere): return the first model
+ *    entry of the first provider entry, including its variant if present.
+ */
+export declare function resolveSourceModel(category: string, availabilitySet: ReadonlySet<string>): {
+    provider: ProviderID;
+    model: string;
+    variant?: string;
+};

package/dist/schemas/systematic-config.schema.json

@@ -46,6 +46,7 @@
           "variant": {
             "type": "string",
             "minLength": 1,
+            "maxLength": 128,
             "pattern": "^\\S+$",
             "description": "Model variant identifier",
             "examples": ["v2", "extended"],
@@ -204,6 +205,7 @@
           "variant": {
             "type": "string",
             "minLength": 1,
+            "maxLength": 128,
             "pattern": "^\\S+$",
             "description": "Model variant identifier",
             "examples": ["v2", "extended"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "2.12.3",
+  "version": "2.13.1",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "homepage": "https://fro.bot/systematic",