@orchagent/cli 0.3.100 → 0.3.102

package/dist/commands/agent-keys.js

@@ -9,18 +9,14 @@ const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const errors_1 = require("../lib/errors");
 const key_store_1 = require("../lib/key-store");
+const resolve_agent_1 = require("../lib/resolve-agent");
 /**
  * Resolve an agent reference ("org/agent" or just "agent") to an agent ID.
- * Uses the authenticated list-agents endpoint and finds the latest version.
+ * Uses the shared resolveAgentContext() for parsing and org/workspace resolution,
+ * then finds the latest version via the authenticated list-agents endpoint.
  */
 async function resolveAgentId(config, ref) {
-    const parts = ref.split('/');
-    const agentName = parts.length >= 2 ? parts[1] : parts[0];
-    const orgSlug = parts.length >= 2 ? parts[0] : undefined;
-    // Resolve workspace context from org slug or config
-    const configFile = await (0, config_1.loadConfig)();
-    const resolvedOrg = orgSlug ?? configFile.workspace ?? config.defaultOrg;
-    const workspaceId = resolvedOrg ? await (0, api_1.resolveWorkspaceIdForOrg)(config, resolvedOrg) : undefined;
+    const { org, agent: agentName, workspaceId } = await (0, resolve_agent_1.resolveAgentContext)(ref, config);
     const agents = await (0, api_1.listMyAgents)(config, workspaceId);
     const matching = agents.filter(a => a.name === agentName);
     if (matching.length === 0) {
@@ -28,7 +24,7 @@ async function resolveAgentId(config, ref) {
     }
     // Use the latest version
     const latest = matching.sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime())[0];
-    return { agent: latest, agentId: latest.id, orgSlug: latest.org_slug ?? resolvedOrg ?? '', workspaceId };
+    return { agent: latest, agentId: latest.id, orgSlug: latest.org_slug ?? org, workspaceId };
 }
 function registerAgentKeysCommand(program) {
     const agentKeys = program

package/dist/commands/diff.js

@@ -246,8 +246,10 @@ function parseSecondRef(value, firstOrg, firstName) {
         const parsed = (0, agent_ref_1.parseAgentRef)(value);
         return { org: parsed.org ?? firstOrg, agent: parsed.agent, version: parsed.version };
     }
-    // Otherwise treat as a version shorthand for the same agent
-    return { org: firstOrg, agent: firstName, version: value };
+    // Otherwise treat as a version shorthand for the same agent.
+    // Strip leading '@' — users naturally type `@v2` since the full form is `org/agent@v2`.
+    const version = value.startsWith('@') ? value.slice(1) : value;
+    return { org: firstOrg, agent: firstName, version };
 }
 // ── Command ────────────────────────────────────────────────────
 function registerDiffCommand(program) {

package/dist/commands/docs.js

@@ -10,16 +10,21 @@ const DOCS_ROUTES = {
     '': '/',
     'cli': '/using-agents/cli-commands',
     'agents': '/building-agents/agent-types',
+    'orchestration': '/building-agents/orchestration',
     'skills': '/building-agents/orchestration',
     'sdk': '/building-agents/sdk',
     'api': '/api-reference/overview',
     'quickstart': '/quickstart',
+    'scheduling': '/using-agents/scheduling',
+    'services': '/using-agents/services',
+    'security': '/concepts/security',
+    'billing': '/concepts/billing',
 };
 function registerDocsCommand(program) {
     program
         .command('docs')
         .description('Open documentation in browser')
-        .argument('[topic]', 'Topic: cli, agents, skills, sdk, api, quickstart')
+        .argument('[topic]', 'Topic: cli, agents, orchestration, skills, sdk, api, quickstart, scheduling, services, security, billing')
         .action(async (topic) => {
         if (topic && !(topic in DOCS_ROUTES)) {
             const validTopics = Object.keys(DOCS_ROUTES).filter(k => k).join(', ');

package/dist/commands/fork.js

@@ -81,8 +81,9 @@ Examples:
             throw new errors_1.CliError('Missing org. Use org/agent format or set default org.');
         }
         const { agent, version } = parsed;
+        const workspaceId = await (0, api_1.resolveWorkspaceIdForOrg)(config, org);
         write('Resolving source agent...\n');
-        const source = await (0, api_1.getAgentWithFallback)(config, org, agent, version);
+        const source = await (0, api_1.getAgentWithFallback)(config, org, agent, version, workspaceId);
         if (!source.id) {
             throw new errors_1.CliError(`Could not resolve source agent ID for '${org}/${agent}@${version}'.`);
         }

package/dist/commands/init.js

@@ -58,7 +58,7 @@ Reads JSON input from stdin, processes it, and writes JSON output to stdout.
 This is the standard orchagent tool protocol.
 
 Usage:
-  echo '{"input": "hello"}' | python main.py
+  echo '{"input": "hello"}' | python3 main.py
 """
 
 import json
@@ -136,7 +136,7 @@ IMPORTANT: Port 8080 is reserved by the platform health server.
            Use a different port (default: 3000).
 
 Local development:
-  python main.py
+  python3 main.py
 """
 
 import json
@@ -405,7 +405,7 @@ orchagent fan-out orchestrator.
 Calls multiple agents in parallel, combines their results.
 
 Usage:
-  echo '{"task": "analyze this"}' | python main.py
+  echo '{"task": "analyze this"}' | python3 main.py
 """
 
 import asyncio
@@ -497,7 +497,7 @@ orchagent pipeline orchestrator.
 Calls agents sequentially — each step's output feeds into the next.
 
 Usage:
-  echo '{"task": "process this data"}' | python main.py
+  echo '{"task": "process this data"}' | python3 main.py
 """
 
 import asyncio
@@ -584,7 +584,7 @@ orchagent map-reduce orchestrator.
 Splits input into chunks, processes each in parallel (map), then aggregates (reduce).
 
 Usage:
-  echo '{"items": ["item1", "item2", "item3"]}' | python main.py
+  echo '{"items": ["item1", "item2", "item3"]}' | python3 main.py
 """
 
 import asyncio
@@ -803,7 +803,7 @@ At least one platform token is required.
 
 \`\`\`sh
 pip install -r requirements.txt
-python main.py
+python3 main.py
 \`\`\`
 
 ### 5. Deploy
@@ -848,7 +848,7 @@ cp .env.example .env
 # Fill in DISCORD_BOT_TOKEN, ANTHROPIC_API_KEY, DISCORD_CHANNEL_IDS
 
 pip install -r requirements.txt
-python main.py
+python3 main.py
 \`\`\`
 
 ### 4. Deploy
@@ -1068,7 +1068,7 @@ Reads JSON input from stdin, processes the task, and writes JSON output to stdou
 This is a code-runtime agent — you control the logic and can call any LLM provider.
 
 Usage:
-  echo '{"task": "summarize this text"}' | python main.py
+  echo '{"task": "summarize this text"}' | python3 main.py
 """
 
 import json
@@ -1203,7 +1203,7 @@ Reads JSON input from stdin, calls dependency agents via the orchagent SDK,
 and writes JSON output to stdout.
 
 Usage:
-  echo '{"task": "do something"}' | python main.py
+  echo '{"task": "do something"}' | python3 main.py
 """
 
 import asyncio
@@ -1328,7 +1328,7 @@ Listens for messages in configured channels and responds using the Anthropic API
 Local development:
   1. Copy .env.example to .env and fill in your tokens
   2. pip install -r requirements.txt
-  3. python main.py
+  3. python3 main.py
 """
 
 import asyncio
@@ -1494,7 +1494,10 @@ function resolveInitFlavor(typeOption) {
     if (normalized === 'prompt') {
         return { type: 'prompt', flavor: 'direct_llm' };
     }
-    if (normalized === 'agent' || normalized === 'agentic') {
+    if (normalized === 'agent') {
+        return { type: 'agent', flavor: 'managed_loop' };
+    }
+    if (normalized === 'agentic') {
         return { type: 'agent', flavor: 'code_runtime' };
     }
     if (normalized === 'tool' || normalized === 'code') {
@@ -1511,7 +1514,7 @@ function registerInitCommand(program) {
         .option('--orchestrator', 'Create an orchestrator agent with dependency scaffolding and SDK boilerplate')
         .option('--run-mode <mode>', 'Run mode for agents: on_demand or always_on', 'on_demand')
         .option('--language <lang>', 'Language: python or javascript (default: python)', 'python')
-        .option('--loop', 'Use platform-managed LLM loop instead of code runtime (requires --type agent)')
+        .option('--loop', 'Use platform-managed LLM loop execution (explicit for --type agentic; default for --type agent)')
         .option('--template <name>', 'Start from a template (use --list-templates to see options)')
         .option('--list-templates', 'Show available templates with descriptions')
         .action(async (name, options) => {
@@ -1617,7 +1620,7 @@ function registerInitCommand(program) {
         const isJavaScript = ['javascript', 'js', 'typescript', 'ts'].includes(language);
         // Block unsupported JS flavors
         if (isJavaScript && initMode.flavor === 'managed_loop') {
-            throw new errors_1.CliError('JavaScript is not supported for --loop (managed loop). Use --type agent without --loop for a code-runtime agent.');
+            throw new errors_1.CliError('JavaScript is not supported for managed-loop agents. Use --type agentic for a code-runtime agent scaffold.');
         }
         // JS orchestrators are now supported via the orchagent-sdk npm package
         // Block --language for types that don't create runtime files
@@ -1683,7 +1686,7 @@ function registerInitCommand(program) {
                 type: 'agent',
                 description: 'Multi-platform support agent powered by Claude. Connects to Discord, Telegram, and/or Slack.',
                 run_mode: 'always_on',
-                runtime: { command: 'python main.py' },
+                runtime: { command: 'python3 main.py' },
                 entrypoint: 'main.py',
                 supported_providers: ['anthropic'],
                 default_models: { anthropic: 'claude-sonnet-4-5-20250929' },
@@ -1731,7 +1734,7 @@ function registerInitCommand(program) {
             process.stdout.write(`  ${s}. Edit config.py with your product name and description\n`);
             process.stdout.write(`  ${s + 1}. Replace knowledge/ files with your own docs\n`);
             process.stdout.write(`  ${s + 2}. Copy .env.example to .env and add platform tokens\n`);
-            process.stdout.write(`  ${s + 3}. Test locally: pip install -r requirements.txt && python main.py\n`);
+            process.stdout.write(`  ${s + 3}. Test locally: pip install -r requirements.txt && python3 main.py\n`);
             process.stdout.write(`  ${s + 4}. Deploy: orch publish && orch service deploy\n`);
             process.stdout.write(AGENT_BUILDER_HINT);
             return;
@@ -1901,7 +1904,7 @@ function registerInitCommand(program) {
                 type: 'agent',
                 description: `A ${templateLabel} orchestrator agent`,
                 run_mode: runMode,
-                runtime: { command: isJavaScript ? 'node main.js' : 'python main.py' },
+                runtime: { command: isJavaScript ? 'node main.js' : 'python3 main.py' },
                 manifest: {
                     manifest_version: 1,
                     dependencies,
@@ -1974,7 +1977,7 @@ function registerInitCommand(program) {
                 type: 'tool',
                 description: 'A scheduled job that runs on a cron schedule',
                 run_mode: 'on_demand',
-                runtime: { command: isJavaScript ? 'node main.js' : 'python main.py' },
+                runtime: { command: isJavaScript ? 'node main.js' : 'python3 main.py' },
                 required_secrets: [],
                 tags: ['scheduled', 'cron'],
             };
@@ -2015,7 +2018,7 @@ function registerInitCommand(program) {
                 process.stdout.write(`  1. cd ${name}\n`);
             }
             const mainFile = isJavaScript ? 'main.js' : 'main.py';
-            const testCmd = isJavaScript ? 'node main.js' : 'python main.py';
+            const testCmd = isJavaScript ? 'node main.js' : 'python3 main.py';
             process.stdout.write(`  ${stepNum}. Edit ${mainFile} with your job logic\n`);
             process.stdout.write(`  ${stepNum + 1}. Test: echo '{}' | ${testCmd}\n`);
             process.stdout.write(`  ${stepNum + 2}. Publish: orch publish\n`);
@@ -2037,7 +2040,7 @@ function registerInitCommand(program) {
             }
         }
         if (initMode.flavor !== 'code_runtime' && initMode.flavor !== 'orchestrator' && initMode.flavor !== 'discord' && runMode === 'always_on') {
-            throw new errors_1.CliError("run_mode=always_on requires runtime.command in orchagent.json (e.g. \"runtime\": { \"command\": \"python main.py\" }). Use --type tool for code-runtime agents.");
+            throw new errors_1.CliError("run_mode=always_on requires runtime.command in orchagent.json (e.g. \"runtime\": { \"command\": \"python3 main.py\" }). Use --type tool or --type agentic for code-runtime agents.");
         }
         // Create manifest and type-specific files
         const manifest = JSON.parse(MANIFEST_TEMPLATE);
@@ -2051,7 +2054,7 @@ function registerInitCommand(program) {
                 manifest.entrypoint = 'main.js';
             }
             else {
-                manifest.runtime = { command: 'python main.py' };
+                manifest.runtime = { command: 'python3 main.py' };
             }
             manifest.manifest = {
                 manifest_version: 1,
@@ -2070,7 +2073,7 @@ function registerInitCommand(program) {
         }
         else if (initMode.flavor === 'discord') {
             manifest.description = 'An always-on Discord bot powered by Claude';
-            manifest.runtime = { command: 'python main.py' };
+            manifest.runtime = { command: 'python3 main.py' };
             manifest.supported_providers = ['anthropic'];
             manifest.required_secrets = ['ANTHROPIC_API_KEY', 'DISCORD_BOT_TOKEN', 'DISCORD_CHANNEL_IDS'];
             manifest.tags = ['discord', 'always-on'];
@@ -2082,7 +2085,7 @@ function registerInitCommand(program) {
                 manifest.entrypoint = 'main.js';
             }
             else {
-                manifest.runtime = { command: 'python main.py' };
+                manifest.runtime = { command: 'python3 main.py' };
             }
             manifest.required_secrets = [];
         }
@@ -2199,7 +2202,7 @@ function registerInitCommand(program) {
             process.stdout.write(`  ${stepNum}. Create a Discord bot at https://discord.com/developers/applications\n`);
             process.stdout.write(`  ${stepNum + 1}. Enable Message Content Intent in bot settings\n`);
             process.stdout.write(`  ${stepNum + 2}. Copy .env.example to .env and fill in your tokens\n`);
-            process.stdout.write(`  ${stepNum + 3}. Test locally: pip install -r requirements.txt && python main.py\n`);
+            process.stdout.write(`  ${stepNum + 3}. Test locally: pip install -r requirements.txt && python3 main.py\n`);
             process.stdout.write(`  ${stepNum + 4}. Deploy: orch publish\n`);
         }
         else if (initMode.flavor === 'code_runtime') {
@@ -2209,7 +2212,7 @@ function registerInitCommand(program) {
             }
             if (runMode === 'always_on') {
                 const mainFile = isJavaScript ? 'main.js' : 'main.py';
-                const testCmd = isJavaScript ? 'node main.js' : 'python main.py';
+                const testCmd = isJavaScript ? 'node main.js' : 'python3 main.py';
                 process.stdout.write(`  ${stepNum}. Edit ${mainFile} with your service logic\n`);
                 process.stdout.write(`  ${stepNum + 1}. Test locally: ${testCmd}\n`);
                 process.stdout.write(`  ${stepNum + 2}. Publish: orch publish\n`);
@@ -2226,7 +2229,7 @@ function registerInitCommand(program) {
                 const inputField = initMode.type === 'agent' ? 'task' : 'input';
                 process.stdout.write(`  ${stepNum}. Edit main.py with your agent logic\n`);
                 process.stdout.write(`  ${stepNum + 1}. Edit schema.json with your input/output schemas\n`);
-                process.stdout.write(`  ${stepNum + 2}. Test: echo '{"${inputField}": "test"}' | python main.py\n`);
+                process.stdout.write(`  ${stepNum + 2}. Test: echo '{"${inputField}": "test"}' | python3 main.py\n`);
                 process.stdout.write(`  ${stepNum + 3}. Run: orchagent publish\n`);
             }
         }

package/dist/commands/install.js

@@ -10,24 +10,12 @@ const os_1 = __importDefault(require("os"));
 const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const errors_1 = require("../lib/errors");
+const resolve_agent_1 = require("../lib/resolve-agent");
 const analytics_1 = require("../lib/analytics");
 const adapters_1 = require("../adapters");
 const skill_resolve_1 = require("../lib/skill-resolve");
 const installed_1 = require("../lib/installed");
 const agents_md_utils_1 = require("../lib/agents-md-utils");
-const DEFAULT_VERSION = 'latest';
-function parseAgentRef(value) {
-    const [ref, versionPart] = value.split('@');
-    const version = versionPart?.trim() || DEFAULT_VERSION;
-    const segments = ref.split('/');
-    if (segments.length === 1) {
-        return { name: segments[0], version };
-    }
-    if (segments.length === 2) {
-        return { org: segments[0], name: segments[1], version };
-    }
-    throw new errors_1.CliError('Invalid agent reference. Use org/agent or agent format.');
-}
 async function downloadAgentWithFallback(config, org, name, version, workspaceId) {
     // Fetch public metadata first to check if paid
     let publicMeta;
@@ -135,19 +123,21 @@ function registerInstallCommand(program) {
             errors: [],
         };
         const resolved = await (0, config_1.getResolvedConfig)();
-        const parsed = parseAgentRef(agentArg);
-        const configFile = await (0, config_1.loadConfig)();
-        const org = parsed.org ?? configFile.workspace ?? resolved.defaultOrg;
-        if (!org) {
-            if (jsonMode) {
-                result.errors.push('Missing org. Use org/agent format or set default org.');
+        let agentCtx;
+        try {
+            agentCtx = await (0, resolve_agent_1.resolveAgentContext)(agentArg, resolved);
+        }
+        catch (err) {
+            if (jsonMode && err instanceof errors_1.CliError) {
+                result.errors.push(err.message);
                 process.stdout.write(JSON.stringify(result, null, 2) + '\n');
                 process.exit(errors_1.ExitCodes.INVALID_INPUT);
             }
-            throw new errors_1.CliError('Missing org. Use org/agent format or set default org.');
+            throw err;
         }
-        result.agent = `${org}/${parsed.name}`;
-        result.version = parsed.version;
+        const { org, agent: agentName, version, workspaceId } = agentCtx;
+        result.agent = `${org}/${agentName}`;
+        result.version = version;
         // Determine target formats
         let targetFormats = [];
         if (options.format) {
@@ -186,13 +176,11 @@ function registerInstallCommand(program) {
             throw new errors_1.CliError(errMsg);
         }
         result.scope = scope;
-        // Resolve workspace context for the target org
-        const workspaceId = await (0, api_1.resolveWorkspaceIdForOrg)(resolved, org);
         // Download agent
-        log(`Fetching ${org}/${parsed.name}@${parsed.version}...\n`);
+        log(`Fetching ${org}/${agentName}@${version}...\n`);
         let agent;
         try {
-            agent = await downloadAgentWithFallback(resolved, org, parsed.name, parsed.version, workspaceId);
+            agent = await downloadAgentWithFallback(resolved, org, agentName, version, workspaceId);
         }
         catch (err) {
             if (jsonMode) {
@@ -273,15 +261,15 @@ function registerInstallCommand(program) {
                     catch {
                         // File doesn't exist, will create new
                     }
-                    const agentRef = `${org}/${parsed.name}`;
+                    const agentRef = `${org}/${agentName}`;
                     file.content = (0, agents_md_utils_1.mergeAgentsMdContent)(existingContent, file.content, agentRef);
                 }
                 await promises_1.default.writeFile(fullPath, file.content);
                 filesWritten++;
                 // Track installation
                 const installedAgent = {
-                    agent: `${org}/${parsed.name}`,
-                    version: parsed.version,
+                    agent: `${org}/${agentName}`,
+                    version: version,
                     format: formatId,
                     scope: effectiveScope,
                     path: fullPath,
@@ -297,7 +285,7 @@ function registerInstallCommand(program) {
         if (!options.dryRun) {
             if (filesWritten > 0) {
                 await (0, analytics_1.track)('cli_agent_install', {
-                    agent: `${org}/${parsed.name}`,
+                    agent: `${org}/${agentName}`,
                     formats: targetFormats,
                     scope,
                 });

package/dist/commands/logs.js

@@ -182,7 +182,7 @@ async function listRuns(config, workspaceId, agentName, options) {
     if (result.total > result.runs.length) {
         process.stdout.write(chalk_1.default.gray(`\nShowing ${result.runs.length} of ${result.total} runs. Use --limit to see more.\n`));
     }
-    process.stdout.write(chalk_1.default.gray('\nView detailed logs for a run: orch logs <run-id>\n'));
+    process.stdout.write(chalk_1.default.gray('\nView detailed logs for a run: orch logs <run-id>  · Replay a run: orch replay <run-id>\n'));
 }
 // ============================================
 // SHOW RUN LOGS
@@ -229,5 +229,7 @@ async function showRunLogs(config, workspaceId, runId, json) {
         process.stdout.write(chalk_1.default.gray('\nNo sandbox output available for this run. ' +
             'Execution logs are captured for agents with a code runtime (tool/agent types with runtime.command).\n'));
     }
+    // Footer hints
+    process.stdout.write(chalk_1.default.gray(`\nReplay: orch replay ${runId.slice(0, 8)}  · Trace: orch trace ${runId.slice(0, 8)}\n`));
     process.stdout.write('\n');
 }

package/dist/commands/publish.js

@@ -42,6 +42,7 @@ exports.scanUndeclaredEnvVars = scanUndeclaredEnvVars;
 exports.scanReservedPort = scanReservedPort;
 exports.detectSdkCompatible = detectSdkCompatible;
 exports.checkDependencies = checkDependencies;
+exports.checkWorkspaceLlmKeys = checkWorkspaceLlmKeys;
 exports.batchPublish = batchPublish;
 exports.registerPublishCommand = registerPublishCommand;
 const promises_1 = __importDefault(require("fs/promises"));
@@ -394,7 +395,7 @@ function commandForEntrypoint(entrypoint) {
     if (entrypoint.endsWith('.js') || entrypoint.endsWith('.mjs') || entrypoint.endsWith('.cjs') || entrypoint.endsWith('.ts')) {
         return `node ${entrypoint}`;
     }
-    return `python ${entrypoint}`;
+    return `python3 ${entrypoint}`;
 }
 /**
  * Check if manifest dependencies are published and callable.
@@ -439,13 +440,71 @@ async function checkDependencies(config, dependencies, publishingOrgSlug, worksp
         }
         catch (err) {
             if (err?.status === 404) {
-                return { ref, status: 'not_found' };
+                // Could be unpublished OR published-but-private — we can't tell from a 404
+                return { ref, status: 'not_found_cross_org' };
             }
             // Network/unexpected error — don't false alarm
             return { ref, status: 'found_callable' };
         }
     }));
 }
+/**
+ * Provider names the platform supports for LLM vault keys.
+ * Must stay in sync with gateway's _PROVIDER_TO_SECRET_NAME (db.py).
+ */
+const PROVIDER_TO_SECRET_NAME = {
+    anthropic: 'ANTHROPIC_API_KEY',
+    openai: 'OPENAI_API_KEY',
+    gemini: 'GEMINI_API_KEY',
+};
+/**
+ * After a successful publish, check whether the target workspace has LLM vault
+ * keys that match the agent's supported_providers. If not, print a warning so
+ * the user knows cloud runs will fail.
+ *
+ * Best-effort: API errors are silently swallowed (the agent is already published).
+ */
+async function checkWorkspaceLlmKeys(config, workspaceId, workspaceSlug, executionEngine, supportedProviders) {
+    // Only direct_llm and managed_loop engines need LLM keys
+    if (executionEngine !== 'direct_llm' && executionEngine !== 'managed_loop') {
+        return;
+    }
+    let secrets;
+    try {
+        const result = await (0, api_1.request)(config, 'GET', `/workspaces/${workspaceId}/secrets`);
+        secrets = result.secrets;
+        if (!Array.isArray(secrets))
+            return;
+    }
+    catch {
+        return; // Can't reach API or unexpected response — skip warning silently
+    }
+    const llmKeys = secrets.filter(s => s.secret_type === 'llm_key' && s.llm_provider);
+    const availableProviders = new Set(llmKeys.map(s => s.llm_provider));
+    // Determine which providers the agent needs
+    const needsAny = supportedProviders.includes('any');
+    if (needsAny) {
+        // 'any' means any single provider works
+        if (availableProviders.size > 0)
+            return;
+    }
+    else {
+        // Check if at least one of the supported providers has a key
+        const hasMatch = supportedProviders.some(p => availableProviders.has(p));
+        if (hasMatch)
+            return;
+    }
+    // Build the warning message
+    const providerList = needsAny
+        ? Object.keys(PROVIDER_TO_SECRET_NAME).join(', ')
+        : supportedProviders.join(', ');
+    const exampleSecretName = needsAny
+        ? 'ANTHROPIC_API_KEY'
+        : (PROVIDER_TO_SECRET_NAME[supportedProviders[0]] || `${supportedProviders[0].toUpperCase()}_API_KEY`);
+    process.stderr.write(chalk_1.default.yellow(`\n⚠ No LLM vault keys found in workspace '${workspaceSlug}' for providers: ${providerList}\n`) +
+        `  Cloud runs will fail until you add keys.\n` +
+        `  Add a key: ${chalk_1.default.cyan(`orch secrets set ${exampleSecretName} <key>`)}\n`);
+}
 /**
  * Batch publish all agents found in subdirectories, in dependency order.
  * Discovers orchagent.json/SKILL.md in immediate subdirectories,
@@ -510,6 +569,8 @@ async function batchPublish(rootDir, options) {
         forwardArgs.push('--no-local-download');
     if (options.requiredSecrets === false)
         forwardArgs.push('--no-required-secrets');
+    if (options.verbose)
+        forwardArgs.push('--verbose');
     const results = [];
     for (let i = 0; i < sorted.length; i++) {
         const agent = sorted[i];
@@ -586,6 +647,7 @@ function registerPublishCommand(program) {
         .option('--no-local-download', 'Prevent users from downloading and running locally (default: allowed)')
         .option('--no-required-secrets', '(deprecated) No longer needed — required_secrets defaults to []')
         .option('--all', 'Publish all agents in subdirectories (dependency order)')
+        .option('--verbose', 'Show detailed bundle contents (file list)')
         .action(async (options) => {
         const cwd = process.cwd();
         // --all: batch publish all agents in subdirectories
@@ -696,6 +758,11 @@ function registerPublishCommand(program) {
                 process.stdout.write(`\n${chalk_1.default.green('✔')} Published ${org.slug}/${skillData.frontmatter.name}@${skillVersion} successfully!\n\n`);
                 if (hasMultipleFiles) {
                     process.stdout.write(`Files: ${skillFiles.length} files included\n`);
+                    if (options.verbose) {
+                        for (const f of skillFiles) {
+                            process.stdout.write(`  ${f.path}\n`);
+                        }
+                    }
                 }
                 process.stdout.write(`Visibility: private\n`);
                 process.stdout.write(`\nView analytics and usage: https://orchagent.io/dashboard\n`);
@@ -971,6 +1038,7 @@ function registerPublishCommand(program) {
         if (manifestDeps?.length) {
             const depResults = await checkDependencies(config, manifestDeps, org.slug, workspaceId);
             const notFound = depResults.filter(r => r.status === 'not_found');
+            const notFoundCrossOrg = depResults.filter(r => r.status === 'not_found_cross_org');
             const notCallable = depResults.filter(r => r.status === 'found_not_callable');
             if (notFound.length > 0) {
                 process.stderr.write(chalk_1.default.yellow(`\n⚠ Unpublished dependencies:\n`));
@@ -980,6 +1048,14 @@ function registerPublishCommand(program) {
                 process.stderr.write(`\n  These agents must be published before this orchestrator can call them.\n` +
                     `  Publish each dependency first, then re-run this publish.\n\n`);
             }
+            if (notFoundCrossOrg.length > 0) {
+                process.stderr.write(chalk_1.default.yellow(`\n⚠ Dependencies not found (unpublished or not accessible from this workspace):\n`));
+                for (const dep of notFoundCrossOrg) {
+                    process.stderr.write(chalk_1.default.yellow(`  - ${dep.ref}\n`));
+                }
+                process.stderr.write(`\n  If the dependency is published in another workspace, ensure it's in the same\n` +
+                    `  workspace as this orchestrator, or use agent access grants.\n\n`);
+            }
             if (notCallable.length > 0) {
                 process.stderr.write(chalk_1.default.yellow(`\n⚠ Dependencies have callable: false:\n`));
                 for (const dep of notCallable) {
@@ -990,6 +1066,23 @@ function registerPublishCommand(program) {
                     `  the field to use the default) and republish each dependency.\n\n`);
             }
         }
+        // UX-13-02: Warn when managed-loop orchestrator has dependencies but no custom_tools.
+        // Without custom_tools, the LLM has no way to call its declared dependencies.
+        if (executionEngine === 'managed_loop' && manifestDeps?.length) {
+            const mergedTools = Array.isArray(loopConfig?.custom_tools) ? loopConfig.custom_tools : [];
+            if (mergedTools.length === 0) {
+                process.stderr.write(chalk_1.default.yellow(`\n⚠ This managed-loop agent declares dependencies but no custom_tools.\n` +
+                    `  Without custom_tools, the LLM cannot call dependencies at runtime —\n` +
+                    `  it will waste turns exploring the filesystem instead.\n\n` +
+                    `  Use 'orch scaffold orchestration' to auto-generate the correct\n` +
+                    `  custom_tools configuration, or add them manually to your loop config:\n\n` +
+                    `    "loop": {\n` +
+                    `      "custom_tools": [\n` +
+                    `        { "name": "call_worker", "description": "...", "command": "python3 /home/user/helpers/orch_call.py org/worker@v1" }\n` +
+                    `      ]\n` +
+                    `    }\n\n`));
+            }
+        }
         // UX-2: Default required_secrets to [] when omitted for tool/agent types.
         // Prompt and skill types are exempt (prompt agents get LLM keys from platform,
         // skills don't run standalone).
@@ -1061,6 +1154,12 @@ function registerPublishCommand(program) {
                 process.stderr.write(`  Files:       ${bundlePreview.fileCount} files\n`);
                 process.stderr.write(`  Size:        ${(bundlePreview.totalSizeBytes / 1024).toFixed(1)} KB\n`);
                 process.stderr.write(`  Entrypoint:  ${bundlePreview.entrypoint}\n`);
+                if (options.verbose && bundlePreview.files?.length) {
+                    process.stderr.write(`  Bundled files:\n`);
+                    for (const f of bundlePreview.files) {
+                        process.stderr.write(`    ${f}\n`);
+                    }
+                }
             }
             process.stderr.write('\nAgent Preview:\n');
             process.stderr.write(`  Name:        ${manifest.name}\n`);
@@ -1324,6 +1423,12 @@ function registerPublishCommand(program) {
                     skipEntrypointCheck: false,
                 });
                 process.stdout.write(`  Created bundle: ${bundleResult.fileCount} files, ${(bundleResult.sizeBytes / 1024).toFixed(1)}KB\n`);
+                if (options.verbose && bundleResult.files?.length) {
+                    process.stdout.write(`  Bundled files:\n`);
+                    for (const f of bundleResult.files) {
+                        process.stdout.write(`    ${f}\n`);
+                    }
+                }
                 // Validate bundle size
                 const validation = await (0, bundle_1.validateBundle)(bundlePath);
                 if (!validation.valid) {
@@ -1389,6 +1494,8 @@ function registerPublishCommand(program) {
                 process.stderr.write(chalk_1.default.yellow(`⚠ ${warning}\n`));
             }
         }
+        // Warn if workspace has no LLM vault keys for this agent's providers (UX-13-01)
+        await checkWorkspaceLlmKeys(config, workspaceId || org.id, org.slug, executionEngine, supportedProviders);
         // Show required secrets with setup instructions (F-18)
         if (manifest.required_secrets?.length) {
             process.stdout.write(`\nRequired secrets:\n`);
@@ -1404,14 +1511,20 @@ function registerPublishCommand(program) {
         // Show security review result if available
         const secReview = result.security_review;
         if (secReview?.verdict) {
-            if (secReview.verdict === 'passed') {
+            if (secReview.verdict === 'approved') {
                 process.stdout.write(`Security: ${chalk_1.default.green('passed')}\n`);
             }
             else if (secReview.verdict === 'flagged') {
                 process.stdout.write(`Security: ${chalk_1.default.yellow('flagged')} — ${secReview.summary || 'review recommended'}\n`);
             }
+            else if (secReview.verdict === 'error') {
+                process.stdout.write(`Security: ${chalk_1.default.gray('review unavailable')} — publish succeeded, review will be retried\n`);
+            }
+            else if (secReview.verdict === 'skipped') {
+                process.stdout.write(`Security: ${chalk_1.default.gray('review skipped')} — ${secReview.summary || 'content not eligible for review'}\n`);
+            }
             else {
-                process.stdout.write(`Security: ${secReview.verdict}\n`);
+                process.stdout.write(`Security: ${chalk_1.default.gray(secReview.verdict)} — ${secReview.summary || ''}\n`);
             }
         }
         if (result.service_key) {