cognitive-modules-cli 2.2.12 → 2.2.14

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this package are documented in this file.
 
+## 2.2.14 - 2026-03-08
+
+- Release: add docs build to `release:check`, so docs regressions fail before npm publish.
+- Hardening: `packages/cogn` now runs the primary runtime release gate before alias-package publish checks.
+- Providers: preserve Anthropic streaming input/output token accounting correctly.
+- Test coverage: add request-shaping tests for the full stable provider set (`openai`, `anthropic`, `gemini`, `minimax`, `deepseek`, `qwen`).
+
+## 2.2.13 - 2026-02-08
+
+- Fix: do not repair/convert successful envelopes into error envelopes when output validation is disabled (`--profile core`/`validate=off`).
+
 ## 2.2.12 - 2026-02-08
 
 - Conformance: add `runtime` suite (offline, deterministic vectors) to validate publish-grade JSON parsing and profile gates.

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://badge.fury.io/js/cognitive-modules-cli.svg)](https://www.npmjs.com/package/cognitive-modules-cli)
 
-Node.js/TypeScript 版本的 Cognitive Modules CLI。文档统一使用明确入口 `npx cogn@2.2.12 ...`，避免 PATH/命令冲突。
+Node.js/TypeScript 版本的 Cognitive Modules CLI。文档统一使用明确入口 `npx cogn@2.2.14 ...`，避免 PATH/命令冲突。
 
 > 这是 [cognitive-modules](../../README.md) monorepo 的一部分。
 
@@ -10,11 +10,11 @@ Node.js/TypeScript 版本的 Cognitive Modules CLI。文档统一使用明确入
 
 ```bash
 # 零安装（推荐）
-npx cogn@2.2.12 --help
+npx cogn@2.2.14 --help
 
 # 全局安装（可选）
-npm install -g cogn@2.2.12
-# 或：npm install -g cognitive-modules-cli@2.2.12
+npm install -g cogn@2.2.14
+# 或：npm install -g cognitive-modules-cli@2.2.14
 ```
 
 ## 快速开始
@@ -24,43 +24,56 @@ npm install -g cogn@2.2.12
 export OPENAI_API_KEY=sk-xxx
 
 # 查看 providers 能力矩阵（结构化输出/流式）
-npx cogn@2.2.12 providers --pretty
+npx cogn@2.2.14 providers --pretty
 
 # 运行模块
-npx cogn@2.2.12 run code-reviewer --args "def login(u,p): return db.query(f'SELECT * FROM users WHERE name={u}')" --pretty
+npx cogn@2.2.14 run code-reviewer --args "def login(u,p): return db.query(f'SELECT * FROM users WHERE name={u}')" --pretty
 
 # 列出模块
-npx cogn@2.2.12 list
+npx cogn@2.2.14 list
 
 # 管道模式
-echo "review this code" | npx cogn@2.2.12 pipe --module code-reviewer
+echo "review this code" | npx cogn@2.2.14 pipe --module code-reviewer
 ```
 
 ## 支持的 Provider
 
-| Provider | 环境变量 | 说明 |
+对外“稳定支持面”收敛为 6 个 provider（减少认知负担与维护成本）：
+
+| Provider（Stable） | 环境变量 | 说明 |
 |----------|----------|------|
-| OpenAI | `OPENAI_API_KEY` | OpenAI API |
-| Anthropic | `ANTHROPIC_API_KEY` | Claude |
+| OpenAI (ChatGPT) | `OPENAI_API_KEY` | OpenAI API |
+| Anthropic (Claude) | `ANTHROPIC_API_KEY` | Claude |
 | Gemini | `GEMINI_API_KEY` | Google Gemini |
-| DeepSeek | `DEEPSEEK_API_KEY` | DeepSeek |
 | MiniMax | `MINIMAX_API_KEY` | MiniMax |
-| Moonshot | `MOONSHOT_API_KEY` | Kimi |
-| Qwen | `DASHSCOPE_API_KEY` / `QWEN_API_KEY` | 通义千问 |
-| Ollama | `OLLAMA_HOST` | 本地模型 |
+| DeepSeek | `DEEPSEEK_API_KEY` | DeepSeek API |
+| Qwen (DashScope) | `DASHSCOPE_API_KEY` / `QWEN_API_KEY` | 通义千问 |
+
+实验/社区 provider 仍保留实现，但默认不在文档/能力矩阵中承诺稳定性（需要显式指定 `--provider`）：
+
+| Provider（Experimental/Community） | 环境变量 | 说明 |
+|----------|----------|------|
+| Moonshot (Kimi) | `MOONSHOT_API_KEY` | experimental |
+| Ollama (local) | `OLLAMA_HOST` | community |
+
+查看全部 provider（含实验/社区）：
+
+```bash
+npx cogn@2.2.14 providers --pretty --all
+```
 
 ## 命令
 
 ```bash
 # Core（单文件极简路径）
-npx cogn@2.2.12 core new                       # 生成 demo.md
-npx cogn@2.2.12 core run demo.md --args "..."  # 运行单文件模块
-npx cogn@2.2.12 core promote demo.md           # 升级为 v2 模块目录
+npx cogn@2.2.14 core new                       # 生成 demo.md
+npx cogn@2.2.14 core run demo.md --args "..."  # 运行单文件模块
+npx cogn@2.2.14 core promote demo.md           # 升级为 v2 模块目录
 
 # 渐进复杂度（Profiles）
-npx cogn@2.2.12 run code-reviewer --args "..." --profile core       # 极简：跳过校验
-npx cogn@2.2.12 run code-reviewer --args "..." --profile standard   # 推荐：日常默认
-npx cogn@2.2.12 run code-reviewer --args "..." --profile certified  # 最严格：v2.2 + 审计 + registry provenance/完整性门禁
+npx cogn@2.2.14 run code-reviewer --args "..." --profile core       # 极简：跳过校验
+npx cogn@2.2.14 run code-reviewer --args "..." --profile standard   # 推荐：日常默认
+npx cogn@2.2.14 run code-reviewer --args "..." --profile certified  # 最严格：v2.2 + 审计 + registry provenance/完整性门禁
 # 兼容别名（不推荐写进新文档）：
 # - default -> standard
 # - strict  -> standard（deprecated preset）
@@ -70,41 +83,41 @@ npx cogn@2.2.12 run code-reviewer --args "..." --profile certified  # 最严格
 # - --audit（写入 ~/.cognitive/audit/）
 
 # 模块操作
-npx cogn@2.2.12 list                      # 列出模块
-npx cogn@2.2.12 run <module> --args "..." # 运行模块
-npx cogn@2.2.12 add <url> -m <module>     # 从 GitHub 添加模块
-npx cogn@2.2.12 update <module>           # 更新模块
-npx cogn@2.2.12 remove <module>           # 删除模块
-npx cogn@2.2.12 versions <url>            # 查看可用版本
-npx cogn@2.2.12 init <name>               # 创建新模块
-npx cogn@2.2.12 pipe --module <name>      # 管道模式
+npx cogn@2.2.14 list                      # 列出模块
+npx cogn@2.2.14 run <module> --args "..." # 运行模块
+npx cogn@2.2.14 add <url> -m <module>     # 从 GitHub 添加模块
+npx cogn@2.2.14 update <module>           # 更新模块
+npx cogn@2.2.14 remove <module>           # 删除模块
+npx cogn@2.2.14 versions <url>            # 查看可用版本
+npx cogn@2.2.14 init <name>               # 创建新模块
+npx cogn@2.2.14 pipe --module <name>      # 管道模式
 
 # 组合执行
-npx cogn@2.2.12 compose <module> --args "..."
-npx cogn@2.2.12 compose-info <module>
+npx cogn@2.2.14 compose <module> --args "..."
+npx cogn@2.2.14 compose-info <module>
 
 # 校验与迁移
-npx cogn@2.2.12 validate <module> --v22
-npx cogn@2.2.12 validate --all
-npx cogn@2.2.12 migrate <module> --dry-run
-npx cogn@2.2.12 migrate --all --no-backup
+npx cogn@2.2.14 validate <module> --v22
+npx cogn@2.2.14 validate --all
+npx cogn@2.2.14 migrate <module> --dry-run
+npx cogn@2.2.14 migrate --all --no-backup
 
 # 服务器
-npx cogn@2.2.12 serve --port 8000         # 启动 HTTP API 服务
-npx cogn@2.2.12 mcp                       # 启动 MCP 服务（Claude Code / Cursor）
+npx cogn@2.2.14 serve --port 8000         # 启动 HTTP API 服务
+npx cogn@2.2.14 mcp                       # 启动 MCP 服务（Claude Code / Cursor）
 
 # 环境检查
-npx cogn@2.2.12 doctor
+npx cogn@2.2.14 doctor
 
 # Registry（索引与分发）
 # 默认 registry index（latest）：
 #   https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json
 # 可通过环境变量或全局参数覆盖：
-COGNITIVE_REGISTRY_URL=... npx cogn@2.2.12 search
-COGNITIVE_REGISTRY_TIMEOUT_MS=15000 COGNITIVE_REGISTRY_MAX_BYTES=2097152 npx cogn@2.2.12 search
-npx cogn@2.2.12 search --registry https://github.com/Cognary/cognitive/releases/download/vX.Y.Z/cognitive-registry.v2.json
-npx cogn@2.2.12 registry verify --remote --index https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json
-npx cogn@2.2.12 registry verify --remote --concurrency 2
+COGNITIVE_REGISTRY_URL=... npx cogn@2.2.14 search
+COGNITIVE_REGISTRY_TIMEOUT_MS=15000 COGNITIVE_REGISTRY_MAX_BYTES=2097152 npx cogn@2.2.14 search
+npx cogn@2.2.14 search --registry https://github.com/Cognary/cognitive/releases/download/vX.Y.Z/cognitive-registry.v2.json
+npx cogn@2.2.14 registry verify --remote --index https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json
+npx cogn@2.2.14 registry verify --remote --concurrency 2
 ```
 
 ## 开发

package/dist/cli.js

@@ -62,14 +62,39 @@ async function main() {
             process.exit(1);
         }
     }
-    // Get provider
+    const commandRequiresProvider = (() => {
+        if (command === 'core')
+            return positionals[0] === 'run';
+        switch (command) {
+            case 'run':
+            case 'pipe':
+            case 'compose':
+            case 'test':
+            case 'conformance':
+            case 'serve':
+            case 'mcp':
+                return true;
+            default:
+                return false;
+        }
+    })();
+    // Get provider (only required for commands that actually invoke an LLM).
+    // For non-provider commands (list/validate/registry/docs helpers), we keep the CLI usable even
+    // when no API keys are configured by using a placeholder provider that should not be invoked.
     let provider;
-    try {
-        provider = getProvider(values.provider, values.model);
+    if (commandRequiresProvider) {
+        try {
+            provider = getProvider(values.provider, values.model);
+        }
+        catch (e) {
+            console.error(`Error: ${e instanceof Error ? e.message : e}`);
+            process.exit(1);
+        }
     }
-    catch (e) {
-        console.error(`Error: ${e instanceof Error ? e.message : e}`);
-        process.exit(1);
+    else {
+        // If the user explicitly asked for a provider, respect it even if unconfigured.
+        // Otherwise, pick a stable placeholder.
+        provider = getProvider(values.provider ?? 'openai', values.model);
     }
     let policy;
     try {
@@ -248,7 +273,7 @@ async function main() {
                 console.log('');
                 // 2. Provider configuration
                 console.log('LLM Providers:');
-                const providers = listProviders();
+                const providers = listProviders({ all: Boolean(values.all) });
                 let hasConfiguredProvider = false;
                 for (const p of providers) {
                     const status = p.configured ? '✓' : '–';
@@ -257,6 +282,7 @@ async function main() {
                     console.log(`      Model: ${p.model}`);
                     console.log(`      Structured output: ${p.structuredOutput}`);
                     console.log(`      Streaming: ${p.streaming ? 'yes' : 'no'}`);
+                    console.log(`      Support: ${p.support}`);
                     console.log(`      Status: ${apiKeyStatus}`);
                     if (p.configured)
                         hasConfiguredProvider = true;
@@ -270,7 +296,8 @@ async function main() {
                 }
                 catch {
                     console.log('  ✗ None configured');
-                    console.log('    → Set one of: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.');
+                    console.log('    → Set one of: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, MINIMAX_API_KEY, DEEPSEEK_API_KEY, DASHSCOPE_API_KEY/QWEN_API_KEY');
+                    console.log('    → Experimental providers require explicit --provider (see: cog providers --all)');
                 }
                 console.log('');
                 // 4. Module scan
@@ -355,7 +382,7 @@ async function main() {
                 break;
             }
             case 'providers': {
-                const providers = listProviders();
+                const providers = listProviders({ all: Boolean(values.all) });
                 console.log(JSON.stringify({ providers }, null, values.pretty ? 2 : 0));
                 break;
             }
@@ -1008,7 +1035,7 @@ OPTIONS:
   -t, --tag <version>   Git tag/version (for add/update)
   -b, --branch <name>   Git branch (for add)
   -M, --model <name>    LLM model (e.g., gpt-4o, gemini-2.0-flash)
-  -p, --provider <name> LLM provider (gemini, openai, anthropic, deepseek, minimax, moonshot, qwen, ollama)
+  -p, --provider <name> LLM provider (stable: openai, anthropic, gemini, minimax, deepseek, qwen)
   --pretty              Pretty-print JSON output
   -V, --verbose         Verbose output
   --no-validate         Skip schema validation
@@ -1022,7 +1049,7 @@ OPTIONS:
   --v22                 Use strict v2.2 validation (for validate)
   --dry-run             Show what would be done without changes (for migrate)
   --no-backup           Skip backup before migration (for migrate)
-  --all                 Process all modules (for validate/migrate)
+  --all                 Process all modules (validate/migrate/test) OR include experimental providers (providers/doctor)
   --conformance         Run official spec vectors (for test)
   --suite <name>        Conformance suite: envelope|runtime|stream|registry|all
   --level <n>           Conformance level: 1|2|3
@@ -1100,15 +1127,17 @@ ENVIRONMENT:
   GEMINI_API_KEY      Google Gemini
   OPENAI_API_KEY      OpenAI
   ANTHROPIC_API_KEY   Anthropic Claude
-  DEEPSEEK_API_KEY    DeepSeek
   MINIMAX_API_KEY     MiniMax
-  MOONSHOT_API_KEY    Moonshot (Kimi)
+  DEEPSEEK_API_KEY    DeepSeek
   DASHSCOPE_API_KEY   Alibaba Qwen (通义千问)
-  OLLAMA_HOST         Ollama local (default: localhost:11434)
   COG_MODEL           Override default model for any provider
   COGNITIVE_REGISTRY_URL  Override registry index URL
   COGNITIVE_REGISTRY_TIMEOUT_MS  Registry index fetch timeout (ms)
   COGNITIVE_REGISTRY_MAX_BYTES   Registry index max bytes
+
+EXPERIMENTAL/COMMUNITY (not in the stable support promise; use --provider explicitly):
+  MOONSHOT_API_KEY    Moonshot (Kimi)
+  OLLAMA_HOST         Ollama local (default: localhost:11434)
 `);
 }
 main().catch(e => {

package/dist/modules/runner.js

@@ -1798,8 +1798,9 @@ export async function runModule(module, provider, options = {}) {
                 }
             }
         }
-        else if (enableRepair) {
-            // Repair error envelopes to ensure they have proper meta fields
+        else if (!response.ok && enableRepair) {
+            // Repair error envelopes to ensure they have proper meta fields.
+            // Important: do not run this on successful envelopes when validation is disabled.
             response = repairErrorEnvelope(response);
             response.version = ENVELOPE_VERSION;
         }

package/dist/modules/subagent.d.ts

@@ -19,6 +19,8 @@ export interface CallDirective {
     module: string;
     args: string;
     match: string;
+    start: number;
+    end: number;
 }
 export interface SubagentRunOptions {
     input?: ModuleInput;
@@ -47,7 +49,9 @@ export declare function parseCalls(text: string): CallDirective[];
  * Replace @call directives with their results
  */
 export declare function substituteCallResults(text: string, callResults: Array<{
-    match: string;
+    match?: string;
+    start?: number;
+    end?: number;
     module: string;
     result: unknown;
 }>): string;

package/dist/modules/subagent.js

@@ -65,7 +65,9 @@ export function parseCalls(text) {
         calls.push({
             module: match[1],
             args: match[2] || '',
-            match: match[0]
+            match: match[0],
+            start: match.index,
+            end: match.index + match[0].length
         });
     }
     return calls;
@@ -74,14 +76,38 @@ export function parseCalls(text) {
  * Replace @call directives with their results
  */
 export function substituteCallResults(text, callResults) {
-    let result = text;
-    for (const entry of callResults) {
+    const buildReplacement = (entry) => {
         const resultStr = typeof entry.result === 'object'
             ? JSON.stringify(entry.result, null, 2)
             : String(entry.result);
-        const replacement = `[Result from ${entry.module}]:\n${resultStr}`;
+        return `[Result from ${entry.module}]:\n${resultStr}`;
+    };
+    const hasRanges = callResults.every((entry) => typeof entry.start === 'number' && typeof entry.end === 'number');
+    if (hasRanges) {
+        const sorted = [...callResults].sort((a, b) => (a.start ?? 0) - (b.start ?? 0));
+        let cursor = 0;
+        let result = '';
+        for (const entry of sorted) {
+            const start = entry.start;
+            const end = entry.end;
+            if (start < cursor) {
+                continue;
+            }
+            result += text.slice(cursor, start);
+            result += buildReplacement(entry);
+            cursor = end;
+        }
+        result += text.slice(cursor);
+        return result;
+    }
+    let result = text;
+    for (const entry of callResults) {
+        if (!entry.match) {
+            continue;
+        }
         const idx = result.indexOf(entry.match);
         if (idx !== -1) {
+            const replacement = buildReplacement(entry);
             result = result.slice(0, idx) + replacement + result.slice(idx + entry.match.length);
         }
     }
@@ -147,10 +173,22 @@ export class SubagentOrchestrator {
                 }, childContext);
                 // Store result
                 if (childResult.ok && 'data' in childResult) {
-                    callResults.push({ match: call.match, module: call.module, result: childResult.data });
+                    callResults.push({
+                        match: call.match,
+                        start: call.start,
+                        end: call.end,
+                        module: call.module,
+                        result: childResult.data
+                    });
                 }
                 else if ('error' in childResult) {
-                    callResults.push({ match: call.match, module: call.module, result: { error: childResult.error } });
+                    callResults.push({
+                        match: call.match,
+                        start: call.start,
+                        end: call.end,
+                        module: call.module,
+                        result: { error: childResult.error }
+                    });
                 }
             }
             // Substitute call results into prompt

package/dist/providers/anthropic.d.ts

@@ -20,6 +20,7 @@ export declare class AnthropicProvider extends BaseProvider {
      * Build request body for Anthropic API
      */
     private buildRequestBody;
+    private mergeUsage;
     invoke(params: InvokeParams): Promise<InvokeResult>;
     /**
      * Stream-based invoke using Anthropic's streaming API.

package/dist/providers/anthropic.js

@@ -53,6 +53,17 @@ export class AnthropicProvider extends BaseProvider {
         }
         return { body, systemContent: systemMessage?.content };
     }
+    mergeUsage(current, next) {
+        if (!next)
+            return current;
+        const promptTokens = next.input_tokens ?? current?.promptTokens ?? 0;
+        const completionTokens = next.output_tokens ?? current?.completionTokens ?? 0;
+        return {
+            promptTokens,
+            completionTokens,
+            totalTokens: promptTokens + completionTokens,
+        };
+    }
     async invoke(params) {
         if (!this.isConfigured()) {
             throw new Error('Anthropic API key not configured. Set ANTHROPIC_API_KEY environment variable.');
@@ -140,20 +151,11 @@ export class AnthropicProvider extends BaseProvider {
                             }
                             // Extract usage info (message_delta or message_stop event)
                             if (data.type === 'message_delta' && data.usage) {
-                                usage = {
-                                    promptTokens: data.usage.input_tokens || 0,
-                                    completionTokens: data.usage.output_tokens || 0,
-                                    totalTokens: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0),
-                                };
+                                usage = this.mergeUsage(usage, data.usage);
                             }
                             // Also check message_start for input tokens
                             if (data.type === 'message_start' && data.message?.usage) {
-                                const inputTokens = data.message.usage.input_tokens || 0;
-                                usage = {
-                                    promptTokens: inputTokens,
-                                    completionTokens: usage?.completionTokens || 0,
-                                    totalTokens: inputTokens + (usage?.completionTokens || 0),
-                                };
+                                usage = this.mergeUsage(usage, data.message.usage);
                             }
                         }
                         catch {
@@ -179,19 +181,10 @@ export class AnthropicProvider extends BaseProvider {
                             }
                         }
                         if (data.type === 'message_delta' && data.usage) {
-                            usage = {
-                                promptTokens: data.usage.input_tokens || 0,
-                                completionTokens: data.usage.output_tokens || 0,
-                                totalTokens: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0),
-                            };
+                            usage = this.mergeUsage(usage, data.usage);
                         }
                         if (data.type === 'message_start' && data.message?.usage) {
-                            const inputTokens = data.message.usage.input_tokens || 0;
-                            usage = {
-                                promptTokens: inputTokens,
-                                completionTokens: usage?.completionTokens || 0,
-                                totalTokens: inputTokens + (usage?.completionTokens || 0),
-                            };
+                            usage = this.mergeUsage(usage, data.message.usage);
                         }
                     }
                     catch {

package/dist/providers/gemini.js

@@ -9,7 +9,10 @@ export class GeminiProvider extends BaseProvider {
     apiKey;
     model;
     baseUrl = 'https://generativelanguage.googleapis.com/v1beta';
-    constructor(apiKey, model = 'gemini-3-flash') {
+    // Default model is intentionally overrideable via `--model`.
+    // If this model is not available for a user's account/API version, they should pass an
+    // explicit model id (or switch providers) rather than relying on implicit defaults.
+    constructor(apiKey, model = 'gemini-3-pro-preview') {
         super();
         this.apiKey = apiKey || process.env.GEMINI_API_KEY || '';
         this.model = model;

package/dist/providers/index.d.ts

@@ -15,9 +15,13 @@ export { DeepSeekProvider } from './deepseek.js';
 export { MoonshotProvider } from './moonshot.js';
 export { QwenProvider } from './qwen.js';
 export { OllamaProvider } from './ollama.js';
+export type ProviderSupportTier = 'stable' | 'experimental' | 'community';
 export declare function getProvider(name?: string, model?: string): Provider;
-export declare function listProviders(): Array<{
+export declare function listProviders(opts?: {
+    all?: boolean;
+}): Array<{
     name: string;
+    support: ProviderSupportTier;
     configured: boolean;
     model: string;
     structuredOutput: StructuredOutputMode;

package/dist/providers/index.js

@@ -22,6 +22,14 @@ export { DeepSeekProvider } from './deepseek.js';
 export { MoonshotProvider } from './moonshot.js';
 export { QwenProvider } from './qwen.js';
 export { OllamaProvider } from './ollama.js';
+// Public promise: these providers are the "supported surface" for the open-source npm runtime.
+// Everything else is intentionally treated as experimental/community to reduce user confusion and
+// avoid over-promising stability across a long tail of provider quirks.
+const STABLE_PROVIDERS = ['openai', 'anthropic', 'gemini', 'minimax', 'deepseek', 'qwen'];
+const EXPERIMENTAL_PROVIDERS = ['moonshot', 'ollama'];
+function isStableProvider(name) {
+    return STABLE_PROVIDERS.includes(name);
+}
 const providers = {
     gemini: (model) => new GeminiProvider(undefined, model),
     openai: (model) => new OpenAIProvider(undefined, model),
@@ -39,24 +47,27 @@ const providers = {
 export function getProvider(name, model) {
     // Check for model override from environment
     const modelOverride = model || process.env.COG_MODEL;
-    // Auto-detect if not specified
+    // Auto-detect if not specified.
+    //
+    // Important: we only auto-select within the "stable" provider set.
+    // Experimental/community providers can still be used, but require explicit `--provider`,
+    // so users don't accidentally end up on a provider they didn't intend (or that isn't
+    // part of the stable support promise).
     if (!name) {
-        if (process.env.GEMINI_API_KEY)
-            return new GeminiProvider(undefined, modelOverride);
         if (process.env.OPENAI_API_KEY)
             return new OpenAIProvider(undefined, modelOverride);
         if (process.env.ANTHROPIC_API_KEY)
             return new AnthropicProvider(undefined, modelOverride);
-        if (process.env.DEEPSEEK_API_KEY)
-            return new DeepSeekProvider(undefined, modelOverride);
+        if (process.env.GEMINI_API_KEY)
+            return new GeminiProvider(undefined, modelOverride);
         if (process.env.MINIMAX_API_KEY)
             return new MiniMaxProvider(undefined, modelOverride);
-        if (process.env.MOONSHOT_API_KEY)
-            return new MoonshotProvider(undefined, modelOverride);
+        if (process.env.DEEPSEEK_API_KEY)
+            return new DeepSeekProvider(undefined, modelOverride);
         if (process.env.DASHSCOPE_API_KEY || process.env.QWEN_API_KEY)
             return new QwenProvider(undefined, modelOverride);
-        // Ollama is always available as fallback if nothing else is configured
-        return new OllamaProvider(modelOverride);
+        throw new Error(`No stable provider configured. Set one of: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, MINIMAX_API_KEY, DEEPSEEK_API_KEY, DASHSCOPE_API_KEY/QWEN_API_KEY. ` +
+            `To use experimental providers, pass --provider (e.g. --provider moonshot).`);
     }
     const factory = providers[name.toLowerCase()];
     if (!factory) {
@@ -70,13 +81,14 @@ function safeCapabilities(p) {
         return caps;
     return { structuredOutput: 'prompt', streaming: p.supportsStreaming?.() ?? false };
 }
-function providerRow(name, configured, model, make) {
+function providerRow(name, configured, model, make, support) {
     const caps = safeCapabilities(make());
     const structuredJsonSchema = caps.structuredOutput === 'native' && (caps.nativeSchemaDialect ?? 'json-schema') !== 'json-schema'
         ? 'prompt'
         : caps.structuredOutput;
     return {
         name,
+        support,
         configured,
         model,
         structuredOutput: caps.structuredOutput,
@@ -86,15 +98,20 @@ function providerRow(name, configured, model, make) {
         streaming: caps.streaming,
     };
 }
-export function listProviders() {
-    return [
-        providerRow('gemini', !!process.env.GEMINI_API_KEY, 'gemini-3-flash', () => new GeminiProvider('')),
-        providerRow('openai', !!process.env.OPENAI_API_KEY, 'gpt-5.2', () => new OpenAIProvider('')),
-        providerRow('anthropic', !!process.env.ANTHROPIC_API_KEY, 'claude-sonnet-4.5', () => new AnthropicProvider('')),
-        providerRow('deepseek', !!process.env.DEEPSEEK_API_KEY, 'deepseek-v3.2', () => new DeepSeekProvider('')),
-        providerRow('minimax', !!process.env.MINIMAX_API_KEY, 'MiniMax-M2.1', () => new MiniMaxProvider('')),
-        providerRow('moonshot', !!process.env.MOONSHOT_API_KEY, 'kimi-k2.5', () => new MoonshotProvider('')),
-        providerRow('qwen', !!(process.env.DASHSCOPE_API_KEY || process.env.QWEN_API_KEY), 'qwen3-max', () => new QwenProvider('')),
-        providerRow('ollama', true, 'llama4 (local)', () => new OllamaProvider()),
+export function listProviders(opts) {
+    const stable = [
+        providerRow('openai', !!process.env.OPENAI_API_KEY, 'gpt-5.2', () => new OpenAIProvider(''), 'stable'),
+        providerRow('anthropic', !!process.env.ANTHROPIC_API_KEY, 'claude-sonnet-4.5', () => new AnthropicProvider(''), 'stable'),
+        providerRow('gemini', !!process.env.GEMINI_API_KEY, 'gemini-3-pro-preview', () => new GeminiProvider(''), 'stable'),
+        providerRow('minimax', !!process.env.MINIMAX_API_KEY, 'MiniMax-M2.1', () => new MiniMaxProvider(''), 'stable'),
+        providerRow('deepseek', !!process.env.DEEPSEEK_API_KEY, 'deepseek-chat', () => new DeepSeekProvider(''), 'stable'),
+        providerRow('qwen', !!(process.env.DASHSCOPE_API_KEY || process.env.QWEN_API_KEY), 'qwen3-max', () => new QwenProvider(''), 'stable'),
+    ];
+    if (!opts?.all)
+        return stable;
+    const experimental = [
+        providerRow('moonshot', !!process.env.MOONSHOT_API_KEY, 'kimi-k2.5', () => new MoonshotProvider(''), 'experimental'),
+        providerRow('ollama', !!process.env.OLLAMA_HOST, 'llama4 (local)', () => new OllamaProvider(), 'community'),
     ];
+    return [...stable, ...experimental];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-modules-cli",
-  "version": "2.2.12",
+  "version": "2.2.14",
   "description": "Cognitive Modules - Structured AI Task Execution with version management",
   "type": "module",
   "main": "dist/index.js",
@@ -25,7 +25,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "pack:check": "npm pack --dry-run --json --cache ../../.npm-cache",
-    "release:check": "npm run build && npm test && npm run pack:check",
+    "release:check": "node ../../scripts/release/check-docs-build.js && npm run build && npm test && npm run pack:check",
     "prepublishOnly": "npm run release:check"
   },
   "keywords": [