snipara-companion 2.3.0 → 2.3.1

package/dist/index.d.ts

@@ -3365,6 +3365,7 @@ interface AdaptiveWorkProfile {
     contextBudget: string;
     reasoningDepth: string;
     evidenceRequirements?: string[];
+    preferredProfileStrengths?: string[];
     notes?: string[];
 }
 interface AdaptiveModelRequirements {
@@ -3377,6 +3378,7 @@ interface AdaptiveModelRequirements {
     capabilities: string[];
     forbiddenCapabilities: string[];
     writeScope: string[];
+    structuredOutputRequired?: boolean;
     preferredEndpointTypes?: string[];
     allowedEndpointTypes?: string[];
     catalogLimit?: number;
@@ -3394,13 +3396,13 @@ interface AdaptiveRoutingCard {
     requirements: AdaptiveModelRequirements;
     recommendedWorkerClass: string;
     costEstimate: AdaptiveRoutingCostEstimate;
-    humanApprovalRequired: true;
+    humanApprovalRequired: boolean;
     fallback: "main_agent";
     reasons: string[];
     warnings: string[];
 }
 interface AdaptiveRoutingGatewayStatus {
-    source: "hosted_mcp";
+    source: "hosted_mcp" | "local_orchestrator";
     success: boolean;
     resolutionStatus?: string;
     candidateCount: number;
@@ -3409,14 +3411,32 @@ interface AdaptiveRoutingGatewayStatus {
 }
 interface AdaptiveRoutingRuntimeCatalog {
     version?: string;
+    source?: string;
+    provider?: string;
+    baseUrl?: string;
+    models?: string[];
+    apiPaths?: Record<string, unknown>;
+    workerEndpoints?: Record<string, Record<string, unknown>>;
+    workerProfiles?: Record<string, Record<string, unknown>>;
     candidates: Array<Record<string, unknown>>;
 }
+interface AdaptiveRoutingResolution {
+    status?: string;
+    selected?: Record<string, unknown>;
+    policyDecision?: Record<string, unknown>;
+    evaluatedCount?: number;
+    rejectedCount?: number;
+    fallback?: string;
+    reasons?: string[];
+    warnings?: string[];
+}
 interface AdaptiveWorkRoutingRecommendation {
     workProfile: AdaptiveWorkProfile;
     requirements: AdaptiveModelRequirements;
     routingCard: AdaptiveRoutingCard;
     gateway?: AdaptiveRoutingGatewayStatus;
     runtimeCatalog?: AdaptiveRoutingRuntimeCatalog;
+    resolution?: AdaptiveRoutingResolution;
 }
 interface AdaptiveWorkRoutingOptions {
     query: string;
@@ -3426,6 +3446,8 @@ interface AdaptiveWorkRoutingOptions {
     allowedEndpointTypes?: string[];
     workerRole?: string;
     plannerRetainsReasoning?: boolean;
+    preferredProfileStrengths?: string[];
+    structuredOutputRequired?: boolean;
     catalogLimit?: number;
     dailyBudgetCents?: number;
     monthlyBudgetCents?: number;
@@ -3458,6 +3480,7 @@ interface OrchestratorHandoffArtifact {
         routingCard?: AdaptiveRoutingCard;
         gateway?: AdaptiveRoutingGatewayStatus;
         runtimeCatalog?: AdaptiveRoutingRuntimeCatalog;
+        resolution?: AdaptiveRoutingResolution;
     };
     task: {
         title: string;

package/dist/index.js

@@ -14627,7 +14627,8 @@ function buildOrchestratorHandoff(options) {
         requirements: options.adaptiveRouting.requirements,
         routingCard: options.adaptiveRouting.routingCard,
         ...options.adaptiveRouting.gateway ? { gateway: options.adaptiveRouting.gateway } : {},
-        ...options.adaptiveRouting.runtimeCatalog ? { runtimeCatalog: options.adaptiveRouting.runtimeCatalog } : {}
+        ...options.adaptiveRouting.runtimeCatalog ? { runtimeCatalog: options.adaptiveRouting.runtimeCatalog } : {},
+        ...options.adaptiveRouting.resolution ? { resolution: options.adaptiveRouting.resolution } : {}
       } : {}
     },
     task: {
@@ -14680,8 +14681,12 @@ function buildAdaptiveWorkRoutingRecommendation(options) {
   const reasoningDepth = inferAdaptiveReasoningDepth(risk, taskType);
   const workerRole = options.workerRole ?? inferAdaptiveWorkerRole(taskType);
   const plannerRetainsReasoning = options.plannerRetainsReasoning ?? preferredEndpointTypes.includes("local");
+  const preferredProfileStrengths = normalizeProfileStrengths(
+    options.preferredProfileStrengths ?? inferAdaptivePreferredProfileStrengths(taskType, options.query, changedFiles, workerRole)
+  );
   const capabilities = inferAdaptiveCapabilities(taskType, workerRole);
   const forbiddenCapabilities = risk === "high" ? ["secrets", "prod_write"] : ["secrets"];
+  const structuredOutputRequired = options.structuredOutputRequired ?? inferAdaptiveStructuredOutputRequirement(taskType, options.query, changedFiles, workerRole);
   const workProfile = compactObject2({
     taskType,
     risk,
@@ -14689,6 +14694,7 @@ function buildAdaptiveWorkRoutingRecommendation(options) {
     contextBudget,
     reasoningDepth,
     evidenceRequirements: inferAdaptiveEvidenceRequirements(options.query, risk),
+    preferredProfileStrengths,
     notes: [
       "Generated by snipara-companion as recommendation-only routing metadata.",
       "snipara-orchestrator must resolve the worker against the runtime catalog before execution."
@@ -14704,6 +14710,7 @@ function buildAdaptiveWorkRoutingRecommendation(options) {
     capabilities,
     forbiddenCapabilities,
     writeScope: changedFiles,
+    structuredOutputRequired: structuredOutputRequired ? true : void 0,
     preferredEndpointTypes,
     allowedEndpointTypes,
     catalogLimit: options.catalogLimit,
@@ -14820,6 +14827,54 @@ function inferAdaptiveCapabilities(taskType, workerRole) {
   }
   return ["execution"];
 }
+function inferAdaptivePreferredProfileStrengths(taskType, query, changedFiles, workerRole) {
+  const normalizedQuery = query.toLowerCase();
+  const strengths = /* @__PURE__ */ new Set();
+  const codeLikeScope = workerRole === "coding" || workerRole === "testing" || taskType === "coding" || taskType === "critical_code" || changedFiles.some((file) => /\.(ts|tsx|js|jsx|py|go|rs|java|kt|swift|rb|php)$/i.test(file));
+  if (codeLikeScope) {
+    strengths.add("code");
+  }
+  if (/\b(structured|json|schema|signature|serialization|contract|patch|file operations?)\b/i.test(
+    normalizedQuery
+  ) || codeLikeScope) {
+    strengths.add("structured_output");
+  }
+  if (/\b(refactor|rewrite|rename|sweep|cross-file|multi-file)\b/i.test(normalizedQuery) || changedFiles.length > 8) {
+    strengths.add("refactor");
+  }
+  if (/\b(repo|repository|codebase|explore|scan|survey|context|continuity|architecture)\b/i.test(
+    normalizedQuery
+  ) || changedFiles.length > 5) {
+    strengths.add("long_context");
+    strengths.add("repo_scan");
+  }
+  if (/\b(agent|workflow|checkpoint|handoff|delegate|orchestrat)\b/i.test(normalizedQuery)) {
+    strengths.add("agentic_exploration");
+  }
+  if (taskType === "release" || taskType === "critical_code" || workerRole === "validation") {
+    strengths.add("execution_safe");
+  }
+  return Array.from(strengths).sort();
+}
+function inferAdaptiveStructuredOutputRequirement(taskType, query, changedFiles, workerRole) {
+  if (workerRole === "documentation" && taskType === "documentation") {
+    return false;
+  }
+  if (workerRole === "coding" || workerRole === "testing") {
+    return true;
+  }
+  if (taskType === "coding" || taskType === "critical_code" || taskType === "tests") {
+    return true;
+  }
+  if (/\b(structured|json|schema|signature|serialization|contract|patch|file operations?)\b/i.test(
+    query
+  )) {
+    return true;
+  }
+  return changedFiles.some(
+    (file) => /\.(ts|tsx|js|jsx|py|go|rs|java|kt|swift|rb|php)$/i.test(file)
+  );
+}
 function inferAdaptiveEvidenceRequirements(query, risk) {
   const evidence = /* @__PURE__ */ new Set();
   if (/\b(test|tests|pytest|unit|integration|e2e|smoke|verify|verification)\b/i.test(query)) {
@@ -14833,6 +14888,13 @@ function inferAdaptiveEvidenceRequirements(query, risk) {
   }
   return Array.from(evidence).sort();
 }
+function normalizeProfileStrengths(values) {
+  return Array.from(
+    new Set(
+      (values ?? []).map((value) => stringValue8(value)?.toLowerCase()).filter((value) => Boolean(value))
+    )
+  ).sort();
+}
 function normalizeEndpointTypes(values) {
   return Array.from(
     new Set(
@@ -18236,6 +18298,7 @@ var FINAL_COMMIT_RETRY_TIMEOUT_MS = 45e3;
 var FINAL_COMMIT_SUMMARY_MAX_CHARS = 1200;
 var FINAL_COMMIT_RETRY_SUMMARY_MAX_CHARS = 600;
 var DEFAULT_ADAPTIVE_ROUTING_CATALOG_LIMIT = 20;
+var DEFAULT_LOCAL_ORCHESTRATOR_TIMEOUT_MS = 8e3;
 var ADAPTIVE_ROUTING_POLICY_RELATIVE_PATH = path21.join(".snipara", "adaptive-routing.json");
 var SHARED_CONTEXT_INTENT_PATTERN = /\b(standard|standards|convention|conventions|guideline|guidelines|best practice|best practices|policy|policies|compliance|compliant|security rules|team rules|style guide|playbook|checklist)\b/i;
 var DOCUMENT_SYNC_FORMATS = {
@@ -20777,10 +20840,21 @@ function printAdaptiveRoutingRecommendation(routing) {
   }
   if (routing.gateway) {
     printKeyValue(
-      "Hosted catalog:",
+      routing.gateway.source === "local_orchestrator" ? "Local route:" : "Hosted catalog:",
       routing.gateway.success ? `${routing.gateway.candidateCount} candidate(s), ${routing.gateway.resolutionStatus ?? "ready"}` : "unavailable"
     );
   }
+  const selectedCandidate = adaptiveRoutingSelectedCandidate(routing.resolution);
+  if (selectedCandidate) {
+    printKeyValue("Selected candidate:", selectedCandidate.candidateId);
+    if (selectedCandidate.endpointType) {
+      printKeyValue("Selected endpoint:", selectedCandidate.endpointType);
+    }
+  }
+  const selectedWorkerEndpoint = selectedCandidate && routing.runtimeCatalog?.workerEndpoints ? routing.runtimeCatalog.workerEndpoints[selectedCandidate.candidateId] : void 0;
+  if (selectedWorkerEndpoint?.model) {
+    printKeyValue("Selected model:", String(selectedWorkerEndpoint.model));
+  }
   if (routing.routingCard.reasons.length > 0) {
     console.log("Reasons:");
     for (const reason of routing.routingCard.reasons) {
@@ -20965,11 +21039,191 @@ function normalizeAdaptiveRoutingCatalog(value) {
   const candidates = Array.isArray(record.candidates) ? record.candidates.filter(
     (candidate) => Boolean(candidate) && typeof candidate === "object" && !Array.isArray(candidate)
   ) : [];
+  const models = Array.isArray(record.models) ? record.models.map((item) => stringValue9(item)).filter((item) => Boolean(item)) : void 0;
+  const workerEndpoints = isRecord12(record.workerEndpoints) ? Object.fromEntries(
+    Object.entries(record.workerEndpoints).filter(
+      ([key, value2]) => Boolean(stringValue9(key)) && isRecord12(value2)
+    )
+  ) : void 0;
+  const workerProfiles = isRecord12(record.workerProfiles) ? Object.fromEntries(
+    Object.entries(record.workerProfiles).filter(
+      ([key, value2]) => Boolean(stringValue9(key)) && isRecord12(value2)
+    )
+  ) : void 0;
   return {
     version: stringValue9(record.version),
+    source: stringValue9(record.source),
+    provider: stringValue9(record.provider),
+    baseUrl: stringValue9(record.baseUrl),
+    ...models && models.length > 0 ? { models } : {},
+    ...isRecord12(record.apiPaths) ? { apiPaths: record.apiPaths } : {},
+    ...workerEndpoints ? { workerEndpoints } : {},
+    ...workerProfiles ? { workerProfiles } : {},
     candidates
   };
 }
+function adaptiveRoutingSelectedCandidate(resolution) {
+  if (!resolution || !isRecord12(resolution.selected)) {
+    return void 0;
+  }
+  const candidate = isRecord12(resolution.selected.candidate) ? resolution.selected.candidate : void 0;
+  const candidateId = stringValue9(candidate?.candidateId);
+  if (!candidateId) {
+    return void 0;
+  }
+  return {
+    candidateId,
+    workerClass: stringValue9(candidate?.workerClass),
+    endpointType: stringValue9(candidate?.endpointType),
+    catalogSource: stringValue9(candidate?.catalogSource)
+  };
+}
+function normalizeAdaptiveRoutingResolution(value) {
+  if (!isRecord12(value)) {
+    return void 0;
+  }
+  const selected = isRecord12(value.selected) ? value.selected : void 0;
+  const candidate = selected && isRecord12(selected.candidate) ? selected.candidate : void 0;
+  const selectedPayload = selected && candidate ? {
+    candidate,
+    ...numberValue6(selected.score) !== void 0 ? { score: numberValue6(selected.score) } : {},
+    ...isRecord12(selected.scoreBreakdown) ? { scoreBreakdown: selected.scoreBreakdown } : {},
+    ...normalizeStringArray3(selected.reasons) ? { reasons: normalizeStringArray3(selected.reasons) } : {}
+  } : void 0;
+  const reasons = normalizeStringArray3(value.reasons);
+  const warnings = normalizeStringArray3(value.warnings);
+  return {
+    status: stringValue9(value.status),
+    ...selectedPayload ? { selected: selectedPayload } : {},
+    ...isRecord12(value.policyDecision) ? { policyDecision: value.policyDecision } : {},
+    ...numberValue6(value.evaluatedCount) !== void 0 ? { evaluatedCount: numberValue6(value.evaluatedCount) } : {},
+    ...numberValue6(value.rejectedCount) !== void 0 ? { rejectedCount: numberValue6(value.rejectedCount) } : {},
+    ...stringValue9(value.fallback) ? { fallback: stringValue9(value.fallback) } : {},
+    ...reasons ? { reasons } : {},
+    ...warnings ? { warnings } : {}
+  };
+}
+function shouldResolveAdaptiveRoutingLocally(options, routing) {
+  if (!routing) {
+    return false;
+  }
+  if (!options.routeLocalWorkers && !options.routingLocalBaseUrl && !options.routingLocalModel && !options.routingLocalPreferModel && !options.routingLocalProvider) {
+    return false;
+  }
+  const preferred = routing.requirements.preferredEndpointTypes ?? [];
+  const allowed = routing.requirements.allowedEndpointTypes ?? [];
+  return preferred.includes("local") || allowed.length === 0 || allowed.includes("local");
+}
+function runOrchestratorJsonCommand(args, cwd = process.cwd()) {
+  const output = (0, import_node_child_process8.execFileSync)("snipara-orchestrator", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: DEFAULT_LOCAL_ORCHESTRATOR_TIMEOUT_MS
+  }).trim();
+  return output ? parseJsonRecord(output, "snipara-orchestrator JSON output") : {};
+}
+function enrichAdaptiveRoutingWithLocalOrchestrator(routing, options, cwd = process.cwd()) {
+  try {
+    const catalogArgs = [
+      "local-model-catalog",
+      "--json",
+      "--worker-role",
+      routing.requirements.workerRole
+    ];
+    for (const writeScope of routing.requirements.writeScope ?? []) {
+      catalogArgs.push("--write-scope", writeScope);
+    }
+    if (options.routingLocalBaseUrl) {
+      catalogArgs.push("--base-url", options.routingLocalBaseUrl);
+    }
+    if (options.routingLocalModel) {
+      catalogArgs.push("--model", options.routingLocalModel);
+    } else if (options.routingLocalPreferModel) {
+      catalogArgs.push("--prefer-model", options.routingLocalPreferModel);
+    } else if (options.routeLocalWorkers) {
+      catalogArgs.push("--all-models");
+    }
+    if (options.routingLocalProvider) {
+      catalogArgs.push("--provider", options.routingLocalProvider);
+    }
+    const runtimeCatalog = normalizeAdaptiveRoutingCatalog(
+      runOrchestratorJsonCommand(catalogArgs, cwd)
+    );
+    const routeArgs = [
+      "route",
+      "--dry-run",
+      "--json",
+      "--work-profile-json",
+      JSON.stringify(routing.workProfile),
+      "--requirements-json",
+      JSON.stringify(routing.requirements)
+    ];
+    for (const candidate of runtimeCatalog.candidates) {
+      routeArgs.push("--candidate-json", JSON.stringify(candidate));
+    }
+    const resolution = normalizeAdaptiveRoutingResolution(
+      runOrchestratorJsonCommand(routeArgs, cwd)
+    );
+    const selectedCandidate = adaptiveRoutingSelectedCandidate(resolution);
+    const selectedEndpoint = selectedCandidate && runtimeCatalog.workerEndpoints ? runtimeCatalog.workerEndpoints[selectedCandidate.candidateId] : void 0;
+    const resolutionWarnings = normalizeStringArray3(resolution?.warnings) ?? [];
+    const resolutionReasons = normalizeStringArray3(resolution?.reasons) ?? [];
+    const approvalRequired = booleanValue2(
+      isRecord12(resolution?.policyDecision) ? resolution.policyDecision.approvalRequired : void 0
+    );
+    const gatewayWarnings = uniqueStrings5([
+      ...resolutionWarnings,
+      ...selectedCandidate ? [] : ["Local orchestrator did not select a worker candidate and will fail closed."]
+    ]);
+    const gateway = {
+      source: "local_orchestrator",
+      success: stringValue9(resolution?.status) === "resolved",
+      resolutionStatus: stringValue9(resolution?.status),
+      candidateCount: runtimeCatalog.candidates.length,
+      fallback: stringValue9(resolution?.fallback) ?? routing.requirements.fallback,
+      warnings: gatewayWarnings
+    };
+    return {
+      ...routing,
+      gateway,
+      runtimeCatalog,
+      ...resolution ? { resolution } : {},
+      routingCard: {
+        ...routing.routingCard,
+        ...selectedCandidate?.workerClass ? { recommendedWorkerClass: selectedCandidate.workerClass } : {},
+        ...approvalRequired !== void 0 ? { humanApprovalRequired: approvalRequired } : {},
+        reasons: uniqueStrings5([
+          ...routing.routingCard.reasons,
+          ...resolutionReasons,
+          ...selectedCandidate ? [
+            `local orchestrator resolved worker candidate ${selectedCandidate.candidateId}`,
+            ...selectedCandidate.endpointType ? [`selected worker endpoint is ${selectedCandidate.endpointType}`] : [],
+            ...stringValue9(selectedEndpoint?.model) ? [`selected local model ${String(selectedEndpoint?.model)}`] : []
+          ] : ["local orchestrator could not resolve a concrete worker candidate"]
+        ]),
+        warnings: uniqueStrings5([...routing.routingCard.warnings, ...gatewayWarnings])
+      }
+    };
+  } catch (error) {
+    const warning = `Local orchestrator routing unavailable; keeping current routing metadata (${toPreview(error)}).`;
+    return {
+      ...routing,
+      gateway: {
+        source: "local_orchestrator",
+        success: false,
+        resolutionStatus: "unavailable",
+        candidateCount: 0,
+        fallback: routing.requirements.fallback,
+        warnings: [warning]
+      },
+      routingCard: {
+        ...routing.routingCard,
+        warnings: uniqueStrings5([...routing.routingCard.warnings, warning])
+      }
+    };
+  }
+}
 function printUploadResult(path23, result) {
   printKeyValue("Uploaded:", path23);
   printCompactObject(result, ["message", "document_id", "documentId", "version", "status"]);
@@ -22456,7 +22710,8 @@ async function workflowRunCommand(options) {
     hostedConfigured
   );
   const adaptiveRoutingDryRun = adaptiveRoutingIntent.shouldBuild ? buildWorkflowAdaptiveRouting(options, adaptiveRoutingPolicy, adaptiveRoutingIntent.warnings) : null;
-  const adaptiveRouting = adaptiveRoutingDryRun && adaptiveRoutingIntent.shouldUseHostedCatalog && client ? await enrichAdaptiveRoutingWithHostedCatalog(client, adaptiveRoutingDryRun) : adaptiveRoutingDryRun;
+  const adaptiveRoutingWithCatalog = adaptiveRoutingDryRun && adaptiveRoutingIntent.shouldUseHostedCatalog && client ? await enrichAdaptiveRoutingWithHostedCatalog(client, adaptiveRoutingDryRun) : adaptiveRoutingDryRun;
+  const adaptiveRouting = shouldResolveAdaptiveRoutingLocally(options, adaptiveRoutingWithCatalog) ? enrichAdaptiveRoutingWithLocalOrchestrator(adaptiveRoutingWithCatalog, options) : adaptiveRoutingWithCatalog;
   const orchestratorRecommendation = getOrchestratorRecommendation(options.query, options.mode, {
     policyAutoRoute: options.autoRouteOrchestrator,
     policySource: options.orchestratorPolicySource,
@@ -22679,7 +22934,7 @@ async function workflowRunCommand(options) {
 }
 function shouldBuildAdaptiveRouting(options) {
   return Boolean(
-    options.adaptiveRoutingDryRun || options.routeLocalWorkers || options.routingWorkerRole || options.routingPreferredEndpoints?.length || options.routingAllowedEndpoints?.length || options.plannerRetainsReasoning
+    options.adaptiveRoutingDryRun || options.routeLocalWorkers || options.routingWorkerRole || options.routingPreferredEndpoints?.length || options.routingAllowedEndpoints?.length || options.routingLocalBaseUrl || options.routingLocalModel || options.routingLocalPreferModel || options.routingLocalProvider || options.plannerRetainsReasoning
   );
 }
 function buildWorkflowAdaptiveRouting(options, policy = null, intentWarnings = []) {
@@ -24794,6 +25049,12 @@ workflow.command("run").description("Run a LITE/STANDARD/FULL/orchestrate workfl
   collectOption,
   []
 ).option(
+  "--routing-local-base-url <url>",
+  "Local OpenAI-compatible runtime base URL for explicit worker routing"
+).option("--routing-local-model <id>", "Explicit local model id for worker routing").option(
+  "--routing-local-prefer-model <text>",
+  "Prefer a local /v1/models entry containing this text during worker routing"
+).option("--routing-local-provider <provider>", "Provider label for local worker routing").option(
   "--planner-retains-reasoning",
   "Mark the main planner as retaining deep reasoning while the worker executes scoped work"
 ).option("--write-plan-file <file>", "Write the generated FULL-mode plan as workflow JSON").option(
@@ -24816,6 +25077,10 @@ workflow.command("run").description("Run a LITE/STANDARD/FULL/orchestrate workfl
     routingWorkerRole: options.routingWorkerRole,
     routingPreferredEndpoints: options.routingPreferredEndpoint,
     routingAllowedEndpoints: options.routingAllowedEndpoint,
+    routingLocalBaseUrl: options.routingLocalBaseUrl,
+    routingLocalModel: options.routingLocalModel,
+    routingLocalPreferModel: options.routingLocalPreferModel,
+    routingLocalProvider: options.routingLocalProvider,
     plannerRetainsReasoning: options.plannerRetainsReasoning ? true : void 0,
     writePlanFile: options.writePlanFile,
     startWorkflowFromPlan: Boolean(options.startWorkflowFromPlan),

package/docs/FULL_REFERENCE.md

@@ -273,6 +273,62 @@ Project credentials stay server-side behind the hosted gateway; local endpoints
 such as Ollama, LM Studio, AnythingLLM, or other OpenAI-compatible servers must
 be reachable from the worker execution environment.
 
+For a local LM Studio or OpenAI-compatible worker, use Companion to emit the
+handoff, then let `snipara-orchestrator` resolve that handoff against an explicit
+local runtime catalog. In the Codex workflow, Codex remains the chief architect,
+lead orchestrator, and quality verifier; Qwen and Devstral are bounded local
+worker candidates whose outputs still need Codex review and proof gates.
+
+Use Qwen for reflection, architecture, and documentation:
+
+```bash
+snipara-companion workflow run \
+  --mode full \
+  --adaptive-routing-dry-run \
+  --route-local-workers \
+  --routing-worker-role documentation \
+  --routing-preferred-endpoint local \
+  --routing-allowed-endpoint local \
+  --planner-retains-reasoning \
+  "Update a scoped docs surface"
+
+snipara-orchestrator local-model-catalog \
+  --base-url http://127.0.0.1:1234 \
+  --model qwen/qwen3-30b-a3b-2507 \
+  --worker-role documentation \
+  --capability documentation \
+  --capability architecture_review \
+  --capability planning \
+  --json > .snipara/local-qwen-docs-runtime-catalog.json
+
+snipara-orchestrator route --dry-run \
+  --work-profile-json '{"taskType":"documentation","risk":"low","scope":["docs/**"],"contextBudget":"small","reasoningDepth":"low"}' \
+  --requirements-json '{"workerRole":"documentation","plannerRetainsReasoning":true,"preferredEndpointTypes":["local"],"allowedEndpointTypes":["local"],"writeScope":["docs/**"],"capabilities":["documentation"]}' \
+  --catalog-file .snipara/local-qwen-docs-runtime-catalog.json \
+  --json
+```
+
+Use Devstral for development and refactoring work:
+
+```bash
+snipara-orchestrator local-model-catalog \
+  --base-url http://127.0.0.1:1234 \
+  --prefer-model devstral \
+  --worker-role coding \
+  --capability code_edit \
+  --capability refactor \
+  --json > .snipara/local-devstral-runtime-catalog.json
+```
+
+The local catalog records the OpenAI-compatible routes exposed by LM Studio:
+`GET /v1/models`, `POST /v1/responses`, `POST /v1/chat/completions`,
+`POST /v1/completions`, and `POST /v1/embeddings`. `--prefer-model devstral`
+selects the first `/v1/models` id containing `devstral`; use `--model <id>` to
+pin Qwen or any other exact local model id. This makes Qwen, Devstral, or
+another local model routable through the Companion/Orchestrator contract while
+keeping execution fail-closed: the selected candidate is a receipt-backed worker
+target, not an automatically launched process.
+
 For the open package without Snipara SaaS, add a local policy file:
 
 ```json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Local-first CLI that asks your repo what breaks before an AI coding agent edits it.",
   "main": "dist/index.js",
   "bin": {