scalemax 0.1.23 → 0.1.24

package/README.md

@@ -119,7 +119,9 @@ The helper uses the same stored key as the installer, verifies authentication, a
 npx scalemax@latest helper-bot --model fable-5 "Help me configure ScaleMax in Cursor"
 ```
 
-Recognized setup, repair, and verification requests execute the CLI's allowlisted client operations directly. For example, `setup vs code roo extension for claude` detects or installs the official Roo Code extension, writes its ScaleMax Claude profile with the stored key, verifies the handoff, and reports each step. The language model never generates or executes shell commands; only fixed ScaleMax client detection, configuration, verification, rollback, and the official Roo Code extension installer are available to the controller.
+Recognized setup, repair, and verification requests execute the CLI's allowlisted client operations directly. Requests such as `setup all providers`, `fix Hermes request failed`, `configure Claude Code`, `verify OpenCode`, and `setup vs code roo extension for claude` are handled by the controller before any model request. The controller detects the relevant client, runs a safe installer when the client has one, verifies existing ScaleMax configuration, repairs ScaleMax-managed files when verification fails, re-verifies, and reports each step.
+
+For Roo Code, helper-bot can install VS Code on Windows with the fixed Microsoft winget package, install the official Roo Code extension, write OpenAI and Claude ScaleMax profiles when the key exposes both families, and verify the import handoff. For general troubleshooting that cannot be completed by a fixed client action, helper-bot sends a small `gpt-5.4` request grounded with bundled ScaleMax documentation about stored authentication, credit/token base URLs, provider scope, client setup, and common errors. The language model never generates or executes shell commands; only fixed ScaleMax client detection, installation, configuration, verification, and rollback operations are available to the controller.
 
 The helper refuses unrelated requests and redacts ScaleMax-style secrets from prompts, provider output, errors, and progress notifications. Use `/status` for non-secret connection details, `/help` for commands, and `/quit` to exit.
 

package/dist/commands/helper-bot.js

@@ -3,11 +3,13 @@ import path from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { execa } from 'execa';
 import { clients } from '../clients.js';
+import { helperDocsContext } from './helper-docs.js';
 import { createChatCompletion, isAnthropicModel } from '../utils/api.js';
 import { redactApiKey } from '../utils/apiKey.js';
 import { loadApiKey } from '../utils/keyStore.js';
 import { homeDir } from '../utils/paths.js';
 import { validateApiKey } from '../utils/api.js';
+import { commandExists } from '../utils/exec.js';
 export const SCALEMAX_HELPER_REFUSAL = `I am the official ScaleMax Helper.
 
 I can only assist with installing, configuring, repairing, verifying, and troubleshooting ScaleMax.
@@ -295,6 +297,8 @@ Never stop after only giving instructions if you can continue solving the issue.
 
 Always prefer automatic configuration.
 
+When bundled ScaleMax documentation is supplied in the conversation, use it for exact ScaleMax configuration facts before relying on general model knowledge.
+
 Only ask the user to perform manual actions when automation is impossible.
 
 If multiple configuration methods exist:
@@ -534,14 +538,15 @@ const DEFAULT_MAX_TOKENS = 512;
 const SECRET_PATTERN = /\b(?:sm_(?:live|test)_[A-Za-z0-9_-]{8,}|sk-[A-Za-z0-9_-]{12,})\b/g;
 const PROMPT_INJECTION_PATTERN = /\b(?:ignore|override|bypass|disable|reveal|show|print|expose)\b.{0,80}\b(?:system|hidden|previous|developer|instruction|prompt|rule|secret)\b/i;
 const CLEARLY_UNRELATED_PATTERN = /\b(?:homework|poem|story|roleplay|translate|translation|medical|legal|politics|religion|dating|entertainment|game|malware|hacking|reverse\s+engineering|weather|sports|recipe|joke)\b/i;
-const SCALEMAX_TOPIC_PATTERN = /\b(?:scalemax|api\s*key|base\s*url|endpoint|provider|model|token|credit|billing|pricing|authentication|configuration|configure|install|update|repair|verify|health\s*check|environment\s*variable|vscode|visual\s+studio\s+code|cursor|codex(?:\s+cli)?|claude(?:\s+code)?|opencode|openclaw|roo\s+code|continue|windsurf|hermes|cherry\s+studio|api\s+code)\b/i;
+const SCALEMAX_TOPIC_PATTERN = /\b(?:scalemax|api\s*key|stored\s+key|customer\s+key|base\s*url|endpoint|provider|openai|anthropic|model|fable|token|credit|billing|pricing|authentication|login|log\s+in|configuration|configure|setup|set\s*up|install|update|repair|verify|health\s*check|environment\s*variable|vscode|visual\s+studio\s+code|vs\s*code\s+extension|cursor|codex(?:\s+cli)?|claude(?:\s+code)?|opencode|openclaw|roo(?:\s+code|\s+extension)?|continue|windsurf|hermes|cherry\s+studio|api\s+code)\b/i;
 const TROUBLESHOOTING_PATTERN = /\b(?:error|failed?|failure|broken|not\s+working|doesn['’]?t\s+work|cannot|can['’]?t|timeout|invalid|unauthorized|forbidden|help)\b/i;
 const GREETING_PATTERN = /^(?:hi|hello|hey|help|what can you do)[!.?\s]*$/i;
 const CLAUDE_DESKTOP_PATTERN = /\bclaude\s+desktop\b/i;
 const CLAUDE_DESKTOP_CONFIGURATION_PATTERN = /\b(?:configur(?:e|ation)|setup|set\s*up|gateway|base\s*url|api\s*key|connect(?:ion)?|third[- ]party|inference|field|install|verify)\b/i;
 const CODEX_CLI_PATTERN = /\bcodex(?:\s+cli)?\b/i;
 const CLIENT_CONFIGURATION_PATTERN = /\b(?:configur(?:e|ation)|setup|set\s*up|base\s*url|api\s*key|connect(?:ion)?|provider|install|repair|verify|update)\b/i;
-const HELPER_MUTATION_PATTERN = /(?:^|\b(?:please|can\s+you|could\s+you|help\s+me(?:\s+to)?|i\s+(?:want|need)\s+you\s+to|how\s+(?:do|can)\s+i)\s+)(?:set\s*up|setup|configure|connect|install|repair|fix|update|reconfigure)\b/i;
+const STORED_KEY_EXPLAIN_PATTERN = /\b(?:why\s+(?:did\s+)?i\s+(?:login|log\s+in)|helper\b.{0,80}\b(?:customer|stored)\s+key|(?:customer|stored)\s+key\b.{0,80}\bhelper|does\s+(?:it|helper)\s+use\s+(?:my\s+)?(?:api\s+)?key)\b/i;
+const HELPER_MUTATION_PATTERN = /(?:^|\b(?:please|can\s+you|could\s+you|help\s+me(?:\s+to)?|i\s+(?:want|need)\s+you\s+to|how\s+(?:do|can)\s+i)\s+)(?:set\s*up|setup|configure|connect|install|repair|fix|update|reconfigure|make\b.{0,80}\bwork)\b/i;
 const HELPER_VERIFICATION_PATTERN = /(?:^|\b(?:please|can\s+you|could\s+you|help\s+me(?:\s+to)?|i\s+(?:want|need)\s+you\s+to)\s+)(?:verify|check|test|diagnose)\b/i;
 const ALL_CLIENTS_PATTERN = /\b(?:all|every)\b.{0,30}\b(?:client|provider|integration|app)s?\b/i;
 const KNOWN_CONTEXT_REASK_PATTERN = /(?:\b(?:need|send|provide|share|tell)\b.{0,100}\b(?:api\s*(?:key|endpoint)|base\s*url|operating\s+system|\bos\b|model\s+(?:name|catalog))\b|YOUR-SCALEMAX-ENDPOINT|your-key)/is;
@@ -650,6 +655,18 @@ export function helperConnectionSummary(connection) {
  * field values matter more than generated prose.
  */
 export function localHelperReply(question, connection) {
+    if (STORED_KEY_EXPLAIN_PATTERN.test(question)) {
+        return `ScaleMax Helper uses the key saved by \`scalemax login\`.
+
+- The key is validated before Helper starts.
+- The Helper's own small replies use the stored customer key with the selected low-cost model, usually \`${connection.model}\`.
+- Client setup actions reuse the same stored key in the target client's private config.
+- The key is never pasted into the prompt, displayed in chat, or requested again after login.
+
+Authenticated base URL: ${connection.baseUrl}
+Billing mode: ${helperBillingMode(connection)}
+Provider scope: ${connection.providerScope || 'both'}`;
+    }
     if (CLAUDE_DESKTOP_PATTERN.test(question) && CLAUDE_DESKTOP_CONFIGURATION_PATTERN.test(question)) {
         const gatewayBaseUrl = claudeDesktopGatewayBaseUrl(connection.baseUrl);
         return `ScaleMax Helper detected and authenticated the stored ${helperBillingMode(connection)} key.
@@ -712,6 +729,7 @@ export async function requestHelperReply(question, history, connection, complete
     if (localReply)
         return localReply;
     const recentHistory = history.slice(-MAX_HISTORY_MESSAGES).map(message => ({ ...message, content: redactHelperSecrets(message.content, connection.apiKey) }));
+    const docsContext = helperDocsContext(cleanQuestion);
     const result = await complete({
         apiKey: connection.apiKey,
         baseUrl: connection.baseUrl,
@@ -720,6 +738,7 @@ export async function requestHelperReply(question, history, connection, complete
         messages: [
             { role: 'system', content: SCALEMAX_HELPER_SYSTEM_PROMPT },
             { role: 'system', content: helperRuntimeContext(connection) },
+            ...(docsContext ? [{ role: 'system', content: docsContext }] : []),
             ...recentHistory,
             { role: 'user', content: cleanQuestion }
         ]
@@ -739,7 +758,7 @@ For automatic configuration, exit with \`/quit\`, run \`scalemax update\`, then
     return reply;
 }
 const HELPER_CLIENT_PATTERNS = [
-    { id: 'roo-code', pattern: /\b(?:roo(?:\s+code)?|roo\s+(?:extension|plugin)|vscode\s+roo|vs\s+code\s+roo)\b/i },
+    { id: 'roo-code', pattern: /\b(?:roo(?:\s+code)?|roo\s+(?:extension|plugin)|vscode\s+roo|vs\s+code\s+roo|vs\s*code\s+extension|visual\s+studio\s+code\s+extension)\b/i },
     { id: 'openclaw', pattern: /\bopen\s*claw\b/i },
     { id: 'opencode', pattern: /\bopen\s*code\b/i },
     { id: 'cherry-studio', pattern: /\bcherry\s*studio\b/i },
@@ -748,9 +767,11 @@ const HELPER_CLIENT_PATTERNS = [
     { id: 'cursor', pattern: /\bcursor\b/i },
     { id: 'hermes', pattern: /\bhermes\b/i },
     { id: 'codex', pattern: /\bcodex(?:\s+cli)?\b/i },
-    { id: 'claude', pattern: /\bclaude\s+code\b/i }
+    { id: 'claude', pattern: /\bclaude(?:\s+code|\s+cli)?\b/i }
 ];
 function helperActionKind(question) {
+    if (/\b(?:repair|fix|troubleshoot|diagnose|not\s+working|doesn['’]?t\s+work|broken|failed?|invalid|timeout|rate\s*limit(?:ed)?)\b/i.test(question))
+        return 'repair';
     if (HELPER_MUTATION_PATTERN.test(question))
         return 'configure';
     if (HELPER_VERIFICATION_PATTERN.test(question))
@@ -760,9 +781,14 @@ function helperActionKind(question) {
 function helperActionTarget(question) {
     if (CLAUDE_DESKTOP_PATTERN.test(question))
         return undefined;
-    if (ALL_CLIENTS_PATTERN.test(question))
+    if (ALL_CLIENTS_PATTERN.test(question) || /\b(?:all|every)\b.{0,30}\bproviders?\b/i.test(question))
         return 'all';
-    return HELPER_CLIENT_PATTERNS.find(candidate => candidate.pattern.test(question))?.id;
+    const explicit = HELPER_CLIENT_PATTERNS.find(candidate => candidate.pattern.test(question))?.id;
+    if (explicit)
+        return explicit;
+    if (/\b(?:clients?|integrations?|apps?|providers?)\b/i.test(question) && /\b(?:scalemax|configure|setup|set\s*up|repair|fix|update)\b/i.test(question))
+        return 'all';
+    return undefined;
 }
 function requestedProviderScope(question, target) {
     if (/\b(?:both|openai\s*\+\s*claude|claude\s*\+\s*openai)\b/i.test(question))
@@ -781,13 +807,78 @@ function actionModels(connection, requestedScope) {
         return catalog;
     return catalog.filter(model => requestedScope === 'anthropic' ? isAnthropicModel(model) : !isAnthropicModel(model));
 }
+function helperClientAllowedForModels(clientId, models) {
+    if (!models.length)
+        return false;
+    const crossProtocolClients = new Set(['claude', 'cursor', 'roo-code', 'opencode', 'openclaw', 'hermes', 'cherry-studio', 'api-code']);
+    if (crossProtocolClients.has(clientId))
+        return true;
+    return models.some(model => !isAnthropicModel(model));
+}
 function hasRooCodeExtension(paths) {
     return paths.some(candidate => /^rooveterinaryinc\.roo-cline-/i.test(path.basename(candidate)));
 }
+function pathEnvKey(env) {
+    return Object.keys(env).find(key => key.toLowerCase() === 'path') || 'PATH';
+}
+function windowsVSCodeBinPaths(ctx) {
+    const localAppData = ctx.env.LOCALAPPDATA || path.win32.join(ctx.home, 'AppData', 'Local');
+    const programFiles = ctx.env.ProgramFiles || 'C:\\Program Files';
+    const programFilesX86 = ctx.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)';
+    return [
+        path.win32.join(localAppData, 'Programs', 'Microsoft VS Code', 'bin'),
+        path.win32.join(programFiles, 'Microsoft VS Code', 'bin'),
+        path.win32.join(programFilesX86, 'Microsoft VS Code', 'bin')
+    ];
+}
+function refreshWindowsVSCodePath(ctx) {
+    if (ctx.platform !== 'win32')
+        return;
+    const key = pathEnvKey(ctx.env);
+    const delimiter = ';';
+    const existing = new Set((ctx.env[key] || '').split(delimiter).filter(Boolean).map(item => item.toLowerCase()));
+    const additions = windowsVSCodeBinPaths(ctx).filter(candidate => !existing.has(candidate.toLowerCase()));
+    if (additions.length)
+        ctx.env[key] = [...additions, ctx.env[key] || ''].filter(Boolean).join(delimiter);
+}
+async function installVSCodeOnWindows(ctx, write) {
+    if (ctx.platform !== 'win32')
+        return;
+    refreshWindowsVSCodePath(ctx);
+    if (await commandExists('code', ctx.env))
+        return;
+    if (!(await commandExists('winget', ctx.env))) {
+        throw new Error('VS Code and the Roo Code extension were not detected. Install VS Code first, then retry this request.');
+    }
+    write('→ VS Code was not detected; installing Microsoft Visual Studio Code with winget…');
+    const result = await execa('winget', [
+        'install',
+        '--id',
+        'Microsoft.VisualStudioCode',
+        '--exact',
+        '--accept-package-agreements',
+        '--accept-source-agreements',
+        '--silent'
+    ], {
+        env: ctx.env,
+        reject: false,
+        all: true
+    });
+    if (result.exitCode !== 0)
+        throw new Error(`VS Code installation failed: ${result.all?.trim() || `winget exited with ${result.exitCode}`}`);
+    refreshWindowsVSCodePath(ctx);
+    if (!(await commandExists('code', ctx.env)))
+        throw new Error('VS Code installed, but the code command was not detected. Restart the terminal and retry this request.');
+    write('✓ VS Code installed and detected.');
+}
 async function installRooCodeExtension(ctx, client, write) {
     let detection = await client.detect(ctx);
     if (hasRooCodeExtension(detection.paths))
         return;
+    if (!detection.executable && ctx.platform === 'win32') {
+        await installVSCodeOnWindows(ctx, write);
+        detection = await client.detect(ctx);
+    }
     if (!detection.executable)
         throw new Error('VS Code and the Roo Code extension were not detected. Install VS Code first, then retry this request.');
     write('→ Installing the official Roo Code extension in VS Code…');
@@ -814,7 +905,7 @@ async function runOneHelperClientAction(kind, client, connection, home, requeste
     const ctx = {
         home,
         platform: connection.platform || process.platform,
-        env: process.env,
+        env: { ...process.env },
         apiKey: connection.apiKey,
         baseUrl: connection.baseUrl,
         providerScope: requestedScope || connection.providerScope || 'both',
@@ -822,15 +913,20 @@ async function runOneHelperClientAction(kind, client, connection, home, requeste
         interactive: false,
         allowAppModification: false
     };
+    if (kind !== 'verify' && client.install) {
+        write(`→ Checking ${client.name} installer…`);
+        const installed = await client.install({ home, platform: ctx.platform, env: ctx.env, interactive: Boolean(process.stdin.isTTY) });
+        write(`✓ ${client.name} ${installed.message}`);
+    }
     write(`→ Detecting ${client.name}…`);
     let detection = await client.detect(ctx);
-    if (kind === 'configure' && client.id === 'roo-code') {
+    if ((kind === 'configure' || kind === 'repair') && client.id === 'roo-code') {
         await installRooCodeExtension(ctx, client, write);
         detection = await client.detect(ctx);
     }
-    if (!detection.installed)
+    if (!detection.installed && client.id !== 'api-code')
         throw new Error(`${client.name} was not detected. No configuration was changed.`);
-    write(`✓ ${client.name} detected.`);
+    write(client.id === 'api-code' && !detection.installed ? `✓ ${client.name} output path is available.` : `✓ ${client.name} detected.`);
     if (kind === 'verify') {
         if (!client.verify) {
             if (!detection.configured)
@@ -841,6 +937,16 @@ async function runOneHelperClientAction(kind, client, connection, home, requeste
         const verified = await client.verify(ctx);
         return `✓ ${client.name} ${verified.message}`;
     }
+    if (kind === 'repair' && client.verify) {
+        write(`→ Diagnosing ${client.name} configuration…`);
+        try {
+            const verified = await client.verify(ctx);
+            return `✓ ${client.name} is already healthy: ${verified.message}`;
+        }
+        catch (error) {
+            write(`→ ${client.name} verification failed; repairing ScaleMax-managed configuration…`);
+        }
+    }
     write(`→ Configuring ${client.name} with the authenticated stored key…`);
     const configured = await client.configure(ctx);
     write(`✓ ${client.name} ${configured.message}`);
@@ -877,11 +983,14 @@ export async function executeHelperAction(question, connection, home, clientCata
     if (!kind || !target)
         return undefined;
     const scope = requestedProviderScope(cleanQuestion, target);
+    const scopedModels = actionModels(connection, scope);
     const selected = target === 'all'
-        ? clientCatalog.filter(client => client.id !== 'cursor')
+        ? clientCatalog.filter(client => client.id !== 'cursor' && helperClientAllowedForModels(client.id, scopedModels))
         : clientCatalog.filter(client => client.id === target);
     if (!selected.length)
         throw new Error('The requested ScaleMax integration is not supported by this CLI build.');
+    if (target !== 'all' && !helperClientAllowedForModels(selected[0].id, scopedModels))
+        throw new Error(`The authenticated key does not expose models compatible with ${selected[0].name}. No configuration was changed.`);
     write(`✓ Stored ${helperBillingMode(connection)} key is authenticated; secrets remain hidden.`);
     const completed = [];
     const failures = [];

package/dist/commands/helper-docs.d.ts

@@ -0,0 +1,9 @@
+export interface HelperDocSection {
+    id: string;
+    title: string;
+    keywords: string[];
+    content: string;
+}
+export declare const HELPER_DOC_SECTIONS: HelperDocSection[];
+export declare function selectHelperDocs(question: string, limit?: number): HelperDocSection[];
+export declare function helperDocsContext(question: string): string | undefined;

package/dist/commands/helper-docs.js

@@ -0,0 +1,70 @@
+export const HELPER_DOC_SECTIONS = [
+    {
+        id: 'stored-auth',
+        title: 'Stored ScaleMax authentication',
+        keywords: ['login', 'authenticate', 'authentication', 'stored key', 'api key', 'customer key', 'why login', 'base url'],
+        content: `After scalemax login succeeds, the CLI stores the customer's ScaleMax API key privately and validates it before helper-bot starts. The helper must not ask the user to paste the key, base URL, operating system, or model catalog again. The helper uses the stored customer key for its own small ScaleMax model requests and for supported client configuration files. The key is never inserted into prompts or displayed in chat.`
+    },
+    {
+        id: 'credit-token-urls',
+        title: 'API credit and API token base URLs',
+        keywords: ['credit', 'token', 'base url', 'endpoint', 'renew', 'billing', 'api credit', 'api token'],
+        content: `ScaleMax API credit keys use https://api.scalemax.pro/v1. ScaleMax API token budget keys use https://api.scalemax.pro/token/v1. Claude Desktop gateway configuration removes the trailing /v1, so credit keys use https://api.scalemax.pro and token keys use https://api.scalemax.pro/token. Do not mix credit and token base URLs; the authenticated key validation result is authoritative.`
+    },
+    {
+        id: 'provider-scope',
+        title: 'Provider scope and visible models',
+        keywords: ['provider', 'scope', 'openai', 'claude', 'anthropic', 'both', 'models', 'fable'],
+        content: `A ScaleMax key may be OpenAI only, Claude only, or both. OpenAI-only keys should configure OpenAI-compatible models only. Claude-only keys should configure Claude-compatible models only. Both-scope keys may configure both model families in clients that can switch profiles. Fable 5 is a Claude-family frontend model through ScaleMax and should only appear for Claude-capable or both-scope keys, not OpenAI-only keys.`
+    },
+    {
+        id: 'roo-code',
+        title: 'Roo Code setup through VS Code',
+        keywords: ['roo', 'roo code', 'vscode', 'vs code', 'extension', 'visual studio code'],
+        content: `For Roo Code, the ScaleMax CLI writes a private settings import file at ~/.scalemax/roo-code-import.json and sets roo-cline.autoImportSettingsPath in VS Code User settings. Roo imports that profile after VS Code is reloaded. The CLI can install the official Roo Code extension with code --install-extension RooVeterinaryInc.roo-cline when VS Code is detected. On Windows, helper-bot may install VS Code first with winget using the fixed Microsoft.VisualStudioCode package id, then install Roo, write the import handoff, and verify the files.`
+    },
+    {
+        id: 'codex-and-clients',
+        title: 'Supported client update flow',
+        keywords: ['codex', 'cursor', 'claude code', 'opencode', 'openclaw', 'hermes', 'cherry studio', 'update', 'doctor'],
+        content: `scalemax update detects supported clients and configures them from the stored key. scalemax doctor validates the stored key and performs a minimal ScaleMax request. Supported clients include Codex CLI, Cursor, Claude Code, OpenCode, OpenClaw, Hermes, Cherry Studio, Roo Code, and API Code. Recognized helper-bot setup and verification requests are executed by the CLI controller before any model fallback is used.`
+    },
+    {
+        id: 'troubleshooting',
+        title: 'Common troubleshooting',
+        keywords: ['error', 'failed', 'invalid', 'rate limit', 'timeout', 'kiro', 'request failed', 'provider returned invalid response'],
+        content: `If a provider response claims to be Kiro, Claude, ChatGPT, Codex, or says it cannot act as ScaleMax Helper, the helper must reject that response and not show the provider persona to the user. For timeouts or rate limits, retry with a tiny request and prefer the lowest-cost available helper model. For invalid key errors, re-run scalemax login and then scalemax doctor. For a client that still shows old settings, reload or restart that client after scalemax update.`
+    }
+];
+function words(value) {
+    return [...new Set(value.toLowerCase().match(/[a-z0-9]+(?:-[a-z0-9]+)?/g) || [])];
+}
+function scoreSection(questionWords, section) {
+    const haystack = words(`${section.title} ${section.keywords.join(' ')} ${section.content}`);
+    let score = 0;
+    for (const word of haystack)
+        if (questionWords.has(word))
+            score += section.keywords.includes(word) ? 4 : 1;
+    return score;
+}
+export function selectHelperDocs(question, limit = 3) {
+    const questionWords = new Set(words(question));
+    if (!questionWords.size)
+        return [];
+    return HELPER_DOC_SECTIONS
+        .map(section => ({ section, score: scoreSection(questionWords, section) }))
+        .filter(item => item.score > 1)
+        .sort((a, b) => b.score - a.score || a.section.id.localeCompare(b.section.id))
+        .slice(0, limit)
+        .map(item => item.section);
+}
+export function helperDocsContext(question) {
+    const sections = selectHelperDocs(question);
+    if (!sections.length)
+        return undefined;
+    return `# SCALEMAX DOCUMENTATION CONTEXT
+
+Use this bundled ScaleMax documentation for exact configuration facts. If it does not fully answer the request, continue from the authenticated runtime context and ScaleMax Helper rules.
+
+${sections.map(section => `## ${section.title}\n${section.content}`).join('\n\n')}`;
+}

package/dist/configure/roo-code.js

@@ -3,7 +3,7 @@ import fs from 'fs-extra';
 import JSON5 from 'json5';
 import { atomicWrite, backupFile } from '../utils/fs.js';
 import { clientConfigPath } from './paths.js';
-import { openAiBaseUrl, preferredChatCompletionsModel } from './models.js';
+import { anthropicModelIds, openAiBaseUrl, openAiModelIds, preferredAnthropicModel, preferredChatCompletionsModel, preferredOpenAiModel } from './models.js';
 import { isAnthropicModel } from '../utils/api.js';
 const id = 'roo-code';
 const name = 'Roo Code (VS Code)';
@@ -14,13 +14,31 @@ const claudeProfileName = 'ScaleMax Claude';
 const codexProfileId = 'scalemax-codex';
 const claudeProfileId = 'scalemax-claude';
 function importPath(home) { return path.join(home, '.scalemax', 'roo-code-import.json'); }
-function profileFor(ctx) {
+function fallbackProfileFor(ctx) {
     const model = preferredChatCompletionsModel(ctx);
     const metadata = (ctx.models || []).find(candidate => candidate.id === model) || { id: model };
     return isAnthropicModel(metadata)
         ? { name: claudeProfileName, id: claudeProfileId, model }
         : { name: codexProfileName, id: codexProfileId, model };
 }
+function profilesFor(ctx) {
+    const scope = ctx.providerScope || 'both';
+    const profiles = [];
+    if (scope !== 'anthropic' && openAiModelIds(ctx).length) {
+        profiles.push({ name: codexProfileName, id: codexProfileId, model: preferredOpenAiModel(ctx) });
+    }
+    if (scope !== 'openai' && anthropicModelIds(ctx).length) {
+        profiles.push({ name: claudeProfileName, id: claudeProfileId, model: preferredAnthropicModel(ctx) });
+    }
+    return profiles.length ? profiles : [fallbackProfileFor(ctx)];
+}
+function currentProfileFor(ctx, profiles = profilesFor(ctx)) {
+    if (ctx.providerScope === 'anthropic')
+        return profiles.find(profile => profile.id === claudeProfileId) || profiles[0];
+    if (ctx.providerScope === 'openai')
+        return profiles.find(profile => profile.id === codexProfileId) || profiles[0];
+    return profiles.find(profile => profile.id === codexProfileId) || profiles[0];
+}
 function parseSettings(text, file) {
     if (!text)
         return {};
@@ -35,21 +53,21 @@ function parseSettings(text, file) {
     }
 }
 function handoff(ctx) {
-    const profile = profileFor(ctx);
+    const profiles = profilesFor(ctx);
+    const current = currentProfileFor(ctx, profiles);
+    const apiConfigs = Object.fromEntries(profiles.map(profile => [profile.name, {
+            id: profile.id,
+            apiProvider: 'openai',
+            openAiBaseUrl: openAiBaseUrl(ctx.baseUrl),
+            openAiApiKey: ctx.apiKey,
+            openAiModelId: profile.model,
+            openAiStreamingEnabled: true,
+            includeMaxTokens: true
+        }]));
     return JSON.stringify({
         providerProfiles: {
-            currentApiConfigName: profile.name,
-            apiConfigs: {
-                [profile.name]: {
-                    id: profile.id,
-                    apiProvider: 'openai',
-                    openAiBaseUrl: openAiBaseUrl(ctx.baseUrl),
-                    openAiApiKey: ctx.apiKey,
-                    openAiModelId: profile.model,
-                    openAiStreamingEnabled: true,
-                    includeMaxTokens: true
-                }
-            },
+            currentApiConfigName: current.name,
+            apiConfigs,
             modeApiConfigs: {}
         },
         globalSettings: {}
@@ -90,14 +108,19 @@ export async function verify(ctx) {
     const profileFile = importPath(ctx.home);
     const settings = parseSettings(await fs.readFile(settingsFile, 'utf8'), settingsFile);
     const profile = await fs.readJson(profileFile).catch(() => undefined);
-    const expected = profileFor(ctx);
-    const config = profile?.providerProfiles?.apiConfigs?.[expected.name];
-    if (settings[importSetting] !== importSettingValue || profile?.providerProfiles?.currentApiConfigName !== expected.name
-        || config?.id !== expected.id || config?.apiProvider !== 'openai' || config?.openAiBaseUrl !== openAiBaseUrl(ctx.baseUrl)
-        || config?.openAiApiKey !== ctx.apiKey || config?.openAiModelId !== expected.model || config?.openAiStreamingEnabled !== true
-        || config?.includeMaxTokens !== true) {
+    const expectedProfiles = profilesFor(ctx);
+    const current = currentProfileFor(ctx, expectedProfiles);
+    if (settings[importSetting] !== importSettingValue || profile?.providerProfiles?.currentApiConfigName !== current.name) {
         throw new Error('Roo Code auto-import handoff is incomplete.');
     }
+    for (const expected of expectedProfiles) {
+        const config = profile?.providerProfiles?.apiConfigs?.[expected.name];
+        if (config?.id !== expected.id || config?.apiProvider !== 'openai' || config?.openAiBaseUrl !== openAiBaseUrl(ctx.baseUrl)
+            || config?.openAiApiKey !== ctx.apiKey || config?.openAiModelId !== expected.model || config?.openAiStreamingEnabled !== true
+            || config?.includeMaxTokens !== true) {
+            throw new Error('Roo Code auto-import handoff is incomplete.');
+        }
+    }
     if (ctx.platform !== 'win32' && ((await fs.stat(profileFile)).mode & 0o077) !== 0)
         throw new Error('Roo Code import handoff permissions are too broad.');
     return { id, name, changed: false, path: profileFile, message: 'verified supported auto-import handoff (runtime activation requires a VS Code reload)' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scalemax",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "Universal ScaleMax installer for AI coding clients",
   "type": "module",
   "bin": {