@stratusagent/cli 0.6.0 → 0.7.0

package/dist/index.js

@@ -8,16 +8,17 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { readdir, readFile } from 'node:fs/promises';
+import { mkdtemp, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
-import { AgentRunner, AllowAllApprovalPolicy, EventBus, ToolRegistry, } from '@stratusagent/core';
+import { AgentRunner, AllowAllApprovalPolicy, EventBus, SkillRegistry, ToolRegistry, matchesSkillAllowlist, missingSkillRequirements, } from '@stratusagent/core';
 import { createLocalCommandExecutor, } from '@stratusagent/executor-local';
 import { loadPlugins } from '@stratusagent/plugins';
 import { createFileCommandWhitelist, createPermissionPolicy, describeCommandScope, } from '@stratusagent/permissions';
 import { DEFAULT_ANTHROPIC_MODEL, redactAnthropicRawTurns, } from '@stratusagent/provider-anthropic';
 import { createRememberTool, defineAgent, formatSoul, generateAgentName, parseSoul, } from '@stratusagent/agents';
-import { agentsDirPath, claimSoulFile, collectAvailableModels as collectModels, createDemoTool, createFileMemoryStore, createRuntimeProvider, credentialsPath, defaultApiKeyEnvName, DEFAULT_ANTHROPIC_BASE_URL, DEFAULT_OPENAI_BASE_URL, DEFAULT_OPENAI_MODEL, DEFAULT_STRATUS_AGENT, discoverActiveConfig, globalConfigPath, loadChannelCredentials, loadCredentials, loadRosterSouls, listAgentSummaries, loadSoulFile, memoryFilePath, migrateLegacyMemory, parseProviderName, readNonEmptyString, readProcessEnv, logsDirPath, readWorkingDirectory, resolveAgentApprovals, DEFAULT_CONFIG_FILENAME, LEGACY_CONFIG_FILENAME, loadConfigFile, resolveConfigLocation, resolveRuntimeConfig as resolveStateRuntimeConfig, saveChannelCredentials, saveConfigFile, readTrustedConfigBlock, saveCredentials, servedRuntimes, verifyProviderKey, withLegacyDefaultMemories, workspacesDirPath, gatewayInfoPath, gatewayTokenPath, } from '@stratusagent/state';
+import { agentsDirPath, claimSoulFile, collectAvailableModels as collectModels, createDemoTool, createFileMemoryStore, createRuntimeProvider, credentialsPath, defaultApiKeyEnvName, DEFAULT_ANTHROPIC_BASE_URL, DEFAULT_OPENAI_BASE_URL, DEFAULT_OPENAI_MODEL, DEFAULT_STRATUS_AGENT, discoverActiveConfig, globalConfigPath, loadChannelCredentials, loadCredentials, installSkillsFromDirectory, loadOperatorSkills, loadRosterSouls, skillsDirPath, listAgentSummaries, loadSoulFile, memoryFilePath, migrateLegacyMemory, parseProviderName, readNonEmptyString, readProcessEnv, logsDirPath, readWorkingDirectory, resolveAgentApprovals, DEFAULT_CONFIG_FILENAME, loadConfigFile, resolveConfigLocation, resolveRuntimeConfig as resolveStateRuntimeConfig, saveChannelCredentials, saveConfigFile, readTrustedConfigBlock, saveCredentials, servedRuntimes, verifyProviderKey, withLegacyDefaultMemories, workspacesDirPath, gatewayInfoPath, gatewayTokenPath, } from '@stratusagent/state';
 import { installService, readServiceStatus, servicePlatform, serviceUnitPath, startService, stopService, uninstallService, } from "./service.js";
 export { installService, launchdPlist, readServiceStatus, servicePlatform, serviceUnitPath, startService, stopService, systemdUnit, uninstallService, SERVICE_LABEL, } from "./service.js";
 import { createLogWriter, currentLogPosition, truncateRedirectLogs, formatLogRecord, readRecentRecords, tailLog, } from "./logs.js";
@@ -26,7 +27,50 @@ export { createLogWriter, currentLogPosition, truncateRedirectLogs, formatLogRec
 // provider wiring now (the gateway uses the same code); the CLI re-exports
 // its historical surface so existing importers keep working.
 export { createFileMemoryStore } from '@stratusagent/state';
-export const CLI_VERSION = '0.6.0';
+/**
+ * Whether spawning npm needs a shell on this platform.
+ *
+ * On Windows npm is `npm.cmd`, a batch file: a bare `npm` does not exist as
+ * an executable there (PATHEXT is a shell's job, not spawn's), and naming
+ * the `.cmd` directly has thrown EINVAL since the fix for CVE-2024-27980 —
+ * both land in the caller's error handler, so a Windows setup would report
+ * that it could not install and leave Slack and the dashboard missing.
+ *
+ * Every package name reaching the shell is a constant in this file, so
+ * there is nothing user-supplied here for it to re-parse.
+ */
+export const npmNeedsShell = (platform) => platform === 'win32';
+const defaultPackageInstaller = async (packages) => {
+    const { spawn } = await import('node:child_process');
+    return new Promise((resolve) => {
+        // npm's own output is inherited rather than captured: a global install
+        // runs for tens of seconds, and a silent one is indistinguishable from
+        // a setup that has hung. stdin is NOT inherited — the setup prompter
+        // owns it, and two readers on one stream race for the same bytes.
+        const child = spawn('npm', ['install', '-g', ...packages], {
+            stdio: ['ignore', 'inherit', 'inherit'],
+            shell: npmNeedsShell(process.platform),
+        });
+        // `error` and `close` can both fire — a spawn that fails still closes.
+        let settled = false;
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            resolve(result);
+        };
+        child.once('error', (error) => {
+            finish({ ok: false, message: error.message });
+        });
+        child.once('close', (code) => {
+            finish(code === 0
+                ? { ok: true, message: '' }
+                : { ok: false, message: `npm exited with code ${code ?? 'unknown'}` });
+        });
+    });
+};
+export const CLI_VERSION = '0.7.0';
 const DASHBOARD_TITLE = 'Stratus Agent Dashboard';
 /**
  * The range every package declares in its `engines` field. Two floors, not
@@ -80,6 +124,9 @@ Usage:
   stratus run --config ./stratus.config.json --provider openai "Say hello"
   stratus agents
   stratus agents --gateway http://127.0.0.1:4123
+  stratus skill add stratuslabs/skill-code-review
+  stratus skill add ./my-skills --skill code-review --agent ava
+  stratus skills
   stratus doctor
   stratus service install
   stratus service status
@@ -93,7 +140,9 @@ Commands:
                    subscription or API key), create your agent, connect it to
                    Slack, and test it — settings go to ~/.stratus/config.json,
                    sign-ins and channel tokens to ~/.stratus/credentials.json
-                   (0600)
+                   (0600). Save & finish offers to install any optional
+                   package your answers imply (the Slack channel, the control
+                   API and dashboard) before it starts the daemon
   chat             Talk with your agent — the conversation persists across turns
                    and remembered facts accumulate; /exit or Ctrl+C to leave
   run              Execute one local Stratus Agent session
@@ -115,6 +164,15 @@ Commands:
   logs             Read the daemon's log from any terminal: -f to follow,
                    -n <count> for backlog, --agent / --session to filter,
                    --format json for the raw records
+  skill add        Install skills from a GitHub repo (owner/repo or URL) or a
+                   local path into ~/.stratus/skills — whole directories, one
+                   per skill; works with skills published for other agents
+                   (skills.sh-style repos). Installed is not enabled: a soul
+                   opts in via skills:, or pass --agent <id> to enable now.
+                   --skill <id> picks from a multi-skill repo (repeatable),
+                   --force replaces an already-installed id
+  skills           List installed skills and which agents enable each
+                   (also: stratus skill list)
   agent new        Create an agent identity (generates a human-ish name + avatar theme)
   agents           List your agents: who they are, where their souls live, what
                    they run on, what they remember (also: stratus agent list).
@@ -163,7 +221,6 @@ Config file:
   The CLI looks for ./stratus.config.json first, then a path from --config / STRATUS_CONFIG,
   then the global ~/.stratus/config.json written by \`stratus setup\`.
   A "soul" key (or STRATUS_SOUL) points at a soul file so every run uses that agent.
-  Legacy STRATUSCLAW_* env vars and stratusclaw.config.json are still supported for compatibility.
 
 Plugins (tools):
   Capability is optional: install a package, then list it under "plugins" in a
@@ -183,10 +240,13 @@ Plugins (tools):
   Installing one grants no agent anything — each soul lists what it may call.
 
 Soul files:
-  A soul file is markdown with frontmatter (name, provider, model, tools, credentials)
+  A soul file is markdown with frontmatter (name, provider, model, tools, skills, credentials)
   followed by the agent's persona in prose. See examples/souls/ava.md.
   "tools" takes exact names or a whole toolset: tools: [fs.read, fs.search] or
   tools: [fs.*]. Omitted means every registered tool.
+  "skills" is the same allowlist shape over installed skills (see stratus
+  skills), except omitted means none — a skill is enabled per agent, never
+  by being installed.
 `;
 const writeLine = (stream, line = '') => {
     stream.write(`${line}\n`);
@@ -548,6 +608,69 @@ export const parseCommand = (argv, env = {}) => {
             ...(sessionId ? { sessionId } : {}),
         };
     }
+    if (command === 'skills' || (command === 'skill' && rest[0] === 'list')) {
+        const skillsRest = command === 'skills' ? rest : rest.slice(1);
+        for (const token of skillsRest) {
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            throw new Error(`Unknown option: ${token}`);
+        }
+        return { command: 'skills' };
+    }
+    if (command === 'skill') {
+        const [subcommand, ...skillRest] = rest;
+        if (subcommand === '--help' || subcommand === '-h') {
+            return { command: 'help' };
+        }
+        if (subcommand !== 'add') {
+            throw new Error(`Unknown skill subcommand: ${subcommand ?? '(missing)'}. Try: stratus skill add <source>, stratus skills`);
+        }
+        let source;
+        const skillIds = [];
+        let force = false;
+        let agentId;
+        for (let index = 0; index < skillRest.length; index += 1) {
+            const token = skillRest[index];
+            if (!token) {
+                continue;
+            }
+            if (token === '--help' || token === '-h') {
+                return { command: 'help' };
+            }
+            if (token === '--skill') {
+                skillIds.push(readOptionValue(skillRest, index, '--skill'));
+                index += 1;
+                continue;
+            }
+            if (token === '--agent') {
+                agentId = readOptionValue(skillRest, index, '--agent');
+                index += 1;
+                continue;
+            }
+            if (token === '--force') {
+                force = true;
+                continue;
+            }
+            if (token.startsWith('--')) {
+                throw new Error(`Unknown option: ${token}`);
+            }
+            if (source !== undefined) {
+                throw new Error(`skill add takes one source; got both ${JSON.stringify(source)} and ${JSON.stringify(token)}.`);
+            }
+            source = token;
+        }
+        if (source === undefined) {
+            throw new Error('skill add needs a source: a GitHub owner/repo, a git URL, or a local path.');
+        }
+        return {
+            command: 'skill-add',
+            source,
+            ...(skillIds.length > 0 ? { skillIds } : {}),
+            ...(force ? { force } : {}),
+            ...(agentId !== undefined ? { agentId } : {}),
+        };
+    }
     if (command === 'agent') {
         const [subcommand, ...agentRest] = rest;
         if (subcommand === '--help' || subcommand === '-h') {
@@ -824,9 +947,8 @@ export const warnOnCredentialOverride = async (runtime, streams, env = {}) => {
         return;
     }
     // The resolver records the variable that actually won — guessing it here
-    // would name the wrong one whenever a custom apiKeyEnv or the legacy
-    // STRATUSCLAW_ prefix supplied the key, sending the reader to unset
-    // something that was never the cause.
+    // would name the wrong one whenever a custom apiKeyEnv supplied the key,
+    // sending the reader to unset something that was never the cause.
     const primary = runtime.provider === 'anthropic' && runtime.apiKey ? runtime.apiKeyEnvVar : undefined;
     // A fallback demoted the same way costs exactly as much, and only bites
     // once the primary is already failing — the worst moment to discover it.
@@ -897,6 +1019,15 @@ const createAgentRuntime = async (streams, options) => {
     const tools = new ToolRegistry();
     tools.register(createDemoTool());
     tools.register(createRememberTool(memory));
+    // The same skills the daemon would serve, from the same directory, for
+    // the same reason the plugins below match: a skill that routes in
+    // `stratus run` routes in `stratus serve`, and one that is broken is
+    // broken (and warned about) in both. The runner registers `skill.read`
+    // itself, gated on the soul enabling any skill.
+    const skills = new SkillRegistry();
+    await loadOperatorSkills(runEnv, skills, (line) => {
+        writeLine(streams.stderr, `Warning: ${line}`);
+    });
     const bus = new EventBus({
         onError: (error) => {
             writeLine(streams.stderr, `Warning: event handler failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -932,6 +1063,7 @@ const createAgentRuntime = async (streams, options) => {
                 import: (specifier) => import(__rewriteRelativeImportExtension(specifier)),
             },
             tools,
+            skills,
             bus,
             workspaceRoot: workspacesDirPath(runEnv),
         });
@@ -959,6 +1091,7 @@ const createAgentRuntime = async (streams, options) => {
         executor: createLocalCommandExecutor(),
         approvals: createApprovalPolicy(options.approvals ?? 'always', streams, options.env ?? {}, options.askApproval),
         bus,
+        skills,
         memory,
         ...(options.maxTurns !== undefined ? { maxTurns: options.maxTurns } : {}),
     });
@@ -967,6 +1100,13 @@ const createAgentRuntime = async (streams, options) => {
     // A soul is a full identity — without one, every provider serves the
     // same built-in Stratus persona.
     const agent = options.runtime.soul?.agent ?? DEFAULT_STRATUS_AGENT;
+    // The same advisory the daemon gives at roster load, from the same
+    // kernel check: a soul enabling a skill whose `requires:` its `tools:`
+    // does not cover must warn here too, or the local test stays silent
+    // about a configuration `stratus serve` flags.
+    for (const { skill, missing } of missingSkillRequirements(agent, skills)) {
+        writeLine(streams.stderr, `Warning: agent ${agent.id} enables skill ${skill.id}, which expects tools the agent is not allowed: ${missing.join(', ')}`);
+    }
     const metadata = options.runtime.provider === 'demo'
         ? { provider: 'demo', executor: 'local-command' }
         : {
@@ -1668,15 +1808,11 @@ const DEFAULT_SOUL_STARTER = [
 export const runSetup = async (command, streams, env = {}) => {
     const cwd = readWorkingDirectory(env);
     const processEnv = readProcessEnv(env);
-    // Config target: --config, then STRATUS_CONFIG / STRATUSCLAW_CONFIG, then
-    // the global ~/.stratus/config.json — the file `stratus run` falls back to
-    // from any directory, which is what makes setup a one-time step.
-    const envConfigVar = readNonEmptyString(processEnv.STRATUS_CONFIG)
-        ? 'STRATUS_CONFIG'
-        : readNonEmptyString(processEnv.STRATUSCLAW_CONFIG)
-            ? 'STRATUSCLAW_CONFIG'
-            : undefined;
-    const envConfigPath = envConfigVar ? String(processEnv[envConfigVar]).trim() : undefined;
+    // Config target: --config, then STRATUS_CONFIG, then the global
+    // ~/.stratus/config.json — the file `stratus run` falls back to from any
+    // directory, which is what makes setup a one-time step.
+    const envConfigVar = readNonEmptyString(processEnv.STRATUS_CONFIG) ? 'STRATUS_CONFIG' : undefined;
+    const envConfigPath = envConfigVar ? String(processEnv.STRATUS_CONFIG).trim() : undefined;
     const configPath = command.configPath
         ? path.resolve(cwd, command.configPath)
         : envConfigPath
@@ -1989,7 +2125,6 @@ export const runSetup = async (command, streams, env = {}) => {
         }
         const keyEnvSelector = provider === state.provider
             ? readNonEmptyString(processEnv.STRATUS_API_KEY_ENV)
-                ?? readNonEmptyString(processEnv.STRATUSCLAW_API_KEY_ENV)
                 ?? state.apiKeyEnv
             : undefined;
         return state.credentials[provider] !== undefined
@@ -2246,11 +2381,9 @@ export const runSetup = async (command, streams, env = {}) => {
         // stored key's bound endpoint is authoritative — so the inline test
         // exercises precisely what a real run will use.
         const keyEnv = readNonEmptyString(processEnv.STRATUS_API_KEY_ENV)
-            ?? readNonEmptyString(processEnv.STRATUSCLAW_API_KEY_ENV)
             ?? state.apiKeyEnv
             ?? defaultKeyEnvFor(state.provider);
         const envKey = readNonEmptyString(processEnv.STRATUS_API_KEY)
-            ?? readNonEmptyString(processEnv.STRATUSCLAW_API_KEY)
             ?? readNonEmptyString(processEnv[String(keyEnv)]);
         const credential = envKey ? undefined : state.credentials[state.provider];
         const boundUrl = credential?.type === 'api_key' ? credential.baseUrl : undefined;
@@ -2409,8 +2542,7 @@ export const runSetup = async (command, streams, env = {}) => {
         // Listing the config soul while `stratus serve` registers the env one
         // would store tokens against an id the adapter then skips.
         const processEnv = readProcessEnv(env);
-        const envSoul = readNonEmptyString(processEnv.STRATUS_SOUL)
-            ?? readNonEmptyString(processEnv.STRATUSCLAW_SOUL);
+        const envSoul = readNonEmptyString(processEnv.STRATUS_SOUL);
         if (typeof envSoul === 'string' && state.soulPath && envSoul !== state.soulPath) {
             warnOnce(`STRATUS_SOUL points at ${envSoul}, which outranks the configured ${state.soulPath} — Channels lists what a run would actually use`);
         }
@@ -2595,25 +2727,126 @@ export const runSetup = async (command, streams, env = {}) => {
             }
         }
     };
-    const detectEnvOverride = (primary, legacy, chosen, flagName) => {
-        const envVar = readNonEmptyString(processEnv[primary])
-            ? primary
-            : readNonEmptyString(processEnv[legacy])
-                ? legacy
-                : undefined;
-        if (!envVar) {
+    const detectEnvOverride = (primary, chosen, flagName) => {
+        if (!readNonEmptyString(processEnv[primary])) {
             return undefined;
         }
-        const envValue = String(processEnv[envVar]).trim();
+        const envValue = String(processEnv[primary]).trim();
         if (envValue === chosen) {
             return undefined;
         }
         return {
-            envVar,
+            envVar: primary,
             envValue,
             ...(flagName ? { flag: `${flagName} ${quoteShellArg(chosen)}` } : {}),
         };
     };
+    /**
+     * Whether `stratus dashboard` can work. Read before the offer and set by
+     * it, so the closing suggestions never name a command this machine cannot
+     * run — the failure that sends someone to the logs to find out why.
+     */
+    let dashboardReady = packageInstalled('@stratusagent/control-api', env)
+        && packageInstalled('@stratusagent/dashboard', env);
+    const missingPackageGroups = () => {
+        const groups = [];
+        const slackAgents = Object.keys(state.channels.slack ?? {}).length;
+        if (slackAgents > 0 && !packageInstalled('@stratusagent/channel-slack', env)) {
+            groups.push({
+                id: 'slack',
+                label: 'Slack channel',
+                why: `Slack tokens are stored for ${slackAgents} agent(s), but nothing connects to Slack without it`,
+                packages: ['@stratusagent/channel-slack'],
+            });
+        }
+        // Both, because the dashboard is what was offered: the control API is
+        // the port and the dashboard is the page served on it. Only the missing
+        // half is installed, so accepting this on a machine that already has
+        // the API does not reinstall it.
+        const dashboardPackages = ['@stratusagent/control-api', '@stratusagent/dashboard']
+            .filter((name) => !packageInstalled(name, env));
+        if (dashboardPackages.length > 0) {
+            groups.push({
+                id: 'dashboard',
+                label: 'Web dashboard',
+                why: '`stratus dashboard` needs it, and it opens an authenticated port on 127.0.0.1',
+                packages: dashboardPackages,
+            });
+        }
+        return groups;
+    };
+    /**
+     * Offers the packages above. Declining is a real answer and prints the
+     * command; the control API in particular binds a port, and installing it
+     * is how an operator says they want one open, so this asks rather than
+     * deciding for them.
+     */
+    const offerOptionalPackages = async () => {
+        const groups = missingPackageGroups();
+        if (groups.length === 0) {
+            return;
+        }
+        writeLine(streams.stdout);
+        writeLine(streams.stdout, groups.length === 1
+            ? 'One optional package is not installed:'
+            : `${groups.length} optional packages are not installed:`);
+        for (const group of groups) {
+            writeLine(streams.stdout, `  ${group.packages.join(' ')}`);
+            writeLine(streams.stdout, `    ${group.why}.`);
+        }
+        const answer = await prompter.select('Install now with npm install -g?', groups.length === 1
+            ? ['Install it now', 'Skip']
+            : ['Install all of them now', ...groups.map((group) => `Install the ${group.label} only`), 'Skip']);
+        const chosen = (() => {
+            if (answer.kind !== 'index') {
+                return [];
+            }
+            if (groups.length === 1) {
+                return answer.index === 0 ? groups : [];
+            }
+            if (answer.index === 0) {
+                return groups;
+            }
+            const only = groups[answer.index - 1];
+            return only ? [only] : [];
+        })();
+        // Held before the install rather than derived after it: picking one
+        // group is not a decision about the other, and the daemon starts a few
+        // lines below and warns about exactly what is still missing — the
+        // notice this whole offer exists to pre-empt.
+        const declined = groups.filter((group) => !chosen.includes(group));
+        if (chosen.length > 0) {
+            const packages = chosen.flatMap((group) => group.packages);
+            writeLine(streams.stdout, `Running: npm install -g ${packages.join(' ')}`);
+            // Never fails setup, for the same reason the service install does not:
+            // the config and credentials are already written, and a package that
+            // did not install is a warning at the next start, not a broken machine.
+            const result = await (env.packageInstaller ?? defaultPackageInstaller)(packages)
+                .catch((error) => ({
+                ok: false,
+                message: error instanceof Error ? error.message : String(error),
+            }));
+            if (result.ok) {
+                writeLine(streams.stdout, `Installed ${packages.join(' ')}.`);
+                // npm's exit code, not a second resolve: a package written into the
+                // global prefix a moment ago need not be resolvable from THIS
+                // process, whose module resolution was fixed when it started.
+                if (chosen.some((group) => group.id === 'dashboard')) {
+                    dashboardReady = true;
+                }
+            }
+            else {
+                writeLine(streams.stderr, `Could not install: ${result.message}`);
+                writeLine(streams.stderr, `Setup is saved either way — run \`npm install -g ${packages.join(' ')}\` yourself.`);
+            }
+        }
+        if (declined.length > 0) {
+            const rest = declined.flatMap((group) => group.packages).join(' ');
+            writeLine(streams.stdout, chosen.length > 0
+                ? `Still missing. Install with: npm install -g ${rest}`
+                : `Skipped. Install them yourself with: npm install -g ${rest}`);
+        }
+    };
     const save = async () => {
         const config = { provider: state.provider };
         if (state.provider !== 'demo') {
@@ -2650,19 +2883,16 @@ export const runSetup = async (command, streams, env = {}) => {
         // bare runs started here — say so, and make the suggested command pick
         // the file that was just written.
         if (configPath === globalConfigPath(env)) {
-            for (const shadow of [DEFAULT_CONFIG_FILENAME, LEGACY_CONFIG_FILENAME]) {
-                const shadowPath = path.join(cwd, shadow);
-                try {
-                    await readFile(shadowPath, 'utf8');
-                    writeLine(streams.stdout, `Note: ${shadowPath} exists and takes precedence over the global config for runs started in this directory.`);
-                    writeLine(streams.stdout, 'The suggested commands below include --config so they use what you just saved.');
-                    shadowConfigFlag = ` --config ${quoteShellArg(configPath)}`;
-                    break;
-                }
-                catch (error) {
-                    if (error.code !== 'ENOENT') {
-                        throw error;
-                    }
+            const shadowPath = path.join(cwd, DEFAULT_CONFIG_FILENAME);
+            try {
+                await readFile(shadowPath, 'utf8');
+                writeLine(streams.stdout, `Note: ${shadowPath} exists and takes precedence over the global config for runs started in this directory.`);
+                writeLine(streams.stdout, 'The suggested commands below include --config so they use what you just saved.');
+                shadowConfigFlag = ` --config ${quoteShellArg(configPath)}`;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT') {
+                    throw error;
                 }
             }
         }
@@ -2679,6 +2909,13 @@ export const runSetup = async (command, streams, env = {}) => {
                 ? `Saved Slack tokens for ${connected} agent${connected === 1 ? '' : 's'} to ${credentialsPath(env)} — run \`${serveCommand()}\` to bring them online.`
                 : `Removed the stored Slack tokens from ${credentialsPath(env)}.`);
         }
+        // Before the service block below, deliberately. A package installed
+        // after the daemon starts is invisible to it — installing does not
+        // reload a running process — so offering here is what makes the
+        // LaunchAgent come up with the Slack channel and the control API
+        // already present, instead of warning about them in a log nobody reads
+        // until the dashboard fails.
+        await offerOptionalPackages();
         // Last, so the daemon starts against the config and credentials that
         // were just written rather than the ones it would have found a moment
         // ago. A service failure is reported and never fails setup: the
@@ -2734,14 +2971,14 @@ export const runSetup = async (command, streams, env = {}) => {
         // Exported STRATUS_* variables outrank the config file, so warn when one
         // would make `stratus run` behave differently from what was just saved.
         const conflicts = [
-            detectEnvOverride('STRATUS_PROVIDER', 'STRATUSCLAW_PROVIDER', state.provider, '--provider'),
+            detectEnvOverride('STRATUS_PROVIDER', state.provider, '--provider'),
             ...(state.provider !== 'demo'
-                ? [detectEnvOverride('STRATUS_MODEL', 'STRATUSCLAW_MODEL', state.model ?? defaultModelFor(state.provider), '--model')]
+                ? [detectEnvOverride('STRATUS_MODEL', state.model ?? defaultModelFor(state.provider), '--model')]
                 : []),
             ...(state.provider === 'openai'
-                ? [detectEnvOverride('STRATUS_BASE_URL', 'STRATUSCLAW_BASE_URL', state.baseUrl ?? DEFAULT_OPENAI_BASE_URL, '--base-url')]
-                : [detectEnvOverride('STRATUS_BASE_URL', 'STRATUSCLAW_BASE_URL', '')]),
-            detectEnvOverride('STRATUS_SYSTEM_PROMPT', 'STRATUSCLAW_SYSTEM_PROMPT', state.systemPrompt ?? ''),
+                ? [detectEnvOverride('STRATUS_BASE_URL', state.baseUrl ?? DEFAULT_OPENAI_BASE_URL, '--base-url')]
+                : [detectEnvOverride('STRATUS_BASE_URL', '')]),
+            detectEnvOverride('STRATUS_SYSTEM_PROMPT', state.systemPrompt ?? ''),
         ].filter((conflict) => conflict !== undefined);
         for (const conflict of conflicts) {
             writeLine(streams.stdout, `Note: ${conflict.envVar}=${conflict.envValue} is exported and takes precedence over the config file (run \`unset ${conflict.envVar}\` to clear it).`);
@@ -2775,7 +3012,9 @@ export const runSetup = async (command, streams, env = {}) => {
             }
         }
         writeLine(streams.stdout, `  stratus run${extraFlags}${runConfigFlag}${shadowConfigFlag} "say hello"`);
-        writeLine(streams.stdout, '  stratus dashboard');
+        if (dashboardReady) {
+            writeLine(streams.stdout, '  stratus dashboard');
+        }
     };
     try {
         if (!interactive) {
@@ -2949,23 +3188,20 @@ export const collectDoctorReport = async (command, warn, env = {}) => {
     // Config discovery, spelled out rather than delegated: doctor has to
     // report the files that LOST as well as the one in use, which is the
     // whole point when a stray project config is the answer.
-    // Which of the three named it, not just that one did: telling someone to
-    // fix STRATUS_CONFIG when STRATUSCLAW_CONFIG is what is set leaves the
-    // real override in place — the same mistake as provider and key
-    // attribution, in the one place a typo is most likely.
+    // Which of the two named it, not just that one did: telling someone to
+    // fix STRATUS_CONFIG when --config is what is set leaves the real
+    // override in place — the same mistake as provider and key attribution,
+    // in the one place a typo is most likely.
     const explicitSource = command.configPath !== undefined
         ? { name: '--config', value: command.configPath }
         : readNonEmptyString(processEnv.STRATUS_CONFIG)
             ? { name: 'STRATUS_CONFIG', value: String(processEnv.STRATUS_CONFIG) }
-            : readNonEmptyString(processEnv.STRATUSCLAW_CONFIG)
-                ? { name: 'STRATUSCLAW_CONFIG', value: String(processEnv.STRATUSCLAW_CONFIG) }
-                : undefined;
+            : undefined;
     const explicit = explicitSource?.value;
     const candidates = explicitSource
         ? [{ path: path.resolve(cwd, explicitSource.value), label: explicitSource.name }]
         : [
             { path: path.join(cwd, DEFAULT_CONFIG_FILENAME), label: 'project' },
-            { path: path.join(cwd, LEGACY_CONFIG_FILENAME), label: 'project (legacy)' },
             { path: globalConfigPath(env), label: 'global' },
         ];
     const present = [];
@@ -3018,16 +3254,10 @@ export const collectDoctorReport = async (command, warn, env = {}) => {
     }
     // Which variable supplied a value, not just the value: naming the wrong
     // one sends the reader to unset something that was never the cause,
-    // leaving the real override in place. The legacy STRATUSCLAW_ prefix is
-    // still honored by the resolver, so it has to be reportable too.
-    const envPick = (...names) => {
-        for (const name of names) {
-            const value = readNonEmptyString(processEnv[name]);
-            if (typeof value === 'string') {
-                return { name, value };
-            }
-        }
-        return undefined;
+    // leaving the real override in place.
+    const envPick = (name) => {
+        const value = readNonEmptyString(processEnv[name]);
+        return typeof value === 'string' ? { name, value } : undefined;
     };
     /**
      * The verdict comes from the resolver, not from a second copy of its
@@ -3036,7 +3266,7 @@ export const collectDoctorReport = async (command, warn, env = {}) => {
      * while whether a run works at all, and what it bills, is whatever
      * resolveRuntimeConfig actually returns or throws.
      */
-    const envSoul = envPick('STRATUS_SOUL', 'STRATUSCLAW_SOUL');
+    const envSoul = envPick('STRATUS_SOUL');
     const soulValue = envSoul?.value ?? fileConfig.soul;
     const soulSource = envSoul ? envSoul.name : (winner ? winner.path : '');
     const soulPath = typeof soulValue === 'string' ? path.resolve(cwd, soulValue) : undefined;
@@ -3059,7 +3289,7 @@ export const collectDoctorReport = async (command, warn, env = {}) => {
             }
         }
     }
-    const envProviderPick = envPick('STRATUS_PROVIDER', 'STRATUSCLAW_PROVIDER');
+    const envProviderPick = envPick('STRATUS_PROVIDER');
     const providerSource = envProviderPick
         ? envProviderPick.name
         : soul?.provider
@@ -3089,7 +3319,7 @@ export const collectDoctorReport = async (command, warn, env = {}) => {
     }
     let model;
     if (resolved && resolved.provider !== 'demo') {
-        const envModel = envPick('STRATUS_MODEL', 'STRATUSCLAW_MODEL');
+        const envModel = envPick('STRATUS_MODEL');
         // A soul's model belongs to the soul's provider, and the config's model
         // to the config's provider — either can be stranded by an override.
         const soulModelApplies = soul?.provider === undefined || soul.provider === resolved.provider;
@@ -3442,8 +3672,7 @@ export const runService = async (command, streams, env = {}) => {
     // install directory and can come up on a different roster entirely.
     const processEnv = readProcessEnv(env);
     const selectedConfig = command.configPath
-        ?? readNonEmptyString(processEnv.STRATUS_CONFIG)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_CONFIG);
+        ?? readNonEmptyString(processEnv.STRATUS_CONFIG);
     if (command.action === 'install') {
         // A config the daemon cannot parse kills it during gateway.start(),
         // and the manager — having accepted the start — restarts it on a
@@ -3497,6 +3726,159 @@ export const runService = async (command, streams, env = {}) => {
     }
     return result.ok ? 0 : 1;
 };
+/**
+ * What a `skill add` source string means, in order: a directory on this
+ * machine, a GitHub `owner/repo` shorthand, or a URL git can clone. The
+ * shorthand is the form skills.sh and its CLI print, so a skill published
+ * there installs by the name its listing shows.
+ */
+const resolveSkillSource = async (source, env) => {
+    const localPath = path.resolve(readWorkingDirectory(env), source);
+    try {
+        if ((await stat(localPath)).isDirectory()) {
+            return { kind: 'local', directory: localPath };
+        }
+    }
+    catch {
+        // Not a local directory; read it as a remote source.
+    }
+    if (/^[\w.-]+\/[\w.-]+$/.test(source)) {
+        return { kind: 'git', url: `https://github.com/${source}` };
+    }
+    if (/^(https?|git|ssh|file):\/\//.test(source) || /^git@[\w.-]+:/.test(source)) {
+        return { kind: 'git', url: source };
+    }
+    throw new Error(`Cannot read ${JSON.stringify(source)} as a skill source. Pass a GitHub owner/repo, a git URL, or a local path.`);
+};
+/** Shallow-clone a skills source. Git owns every transport we would otherwise re-implement. */
+const cloneSkillSource = async (url, destination) => {
+    await new Promise((resolve, reject) => {
+        const child = spawn('git', ['clone', '--depth', '1', '--quiet', url, destination], {
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on('error', (error) => {
+            reject(new Error(`Could not run git to fetch ${url}: ${error.message}`));
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`git clone failed for ${url}: ${stderr.trim() || `exit code ${code}`}`));
+            }
+        });
+    });
+};
+export const runSkillAdd = async (command, streams, env = {}) => {
+    const resolved = await resolveSkillSource(command.source, env);
+    let sourceDir;
+    let cleanup;
+    if (resolved.kind === 'local') {
+        sourceDir = resolved.directory;
+    }
+    else {
+        const scratch = await mkdtemp(path.join(os.tmpdir(), 'stratus-skill-add-'));
+        cleanup = () => rm(scratch, { recursive: true, force: true });
+        writeLine(streams.stdout, `Fetching ${resolved.url} …`);
+        try {
+            await cloneSkillSource(resolved.url, scratch);
+        }
+        catch (error) {
+            await cleanup();
+            throw error;
+        }
+        sourceDir = scratch;
+    }
+    try {
+        const result = await installSkillsFromDirectory(env, sourceDir, {
+            ...(command.skillIds ? { only: command.skillIds } : {}),
+            ...(command.force ? { force: true } : {}),
+        });
+        for (const skill of result.installed) {
+            writeLine(streams.stdout, `installed ${skill.id} — ${skill.description}`);
+        }
+        for (const skip of result.skipped) {
+            writeLine(streams.stderr, `Warning: skipped ${skip.id}: ${skip.reason}`);
+        }
+        if (result.installed.length === 0) {
+            writeLine(streams.stderr, result.skipped.length > 0
+                ? 'Error: nothing was installed.'
+                : `Error: no skills found in ${command.source}. A skill is a directory with a SKILL.md.`);
+            return 1;
+        }
+        // Installed is not enabled: a soul opts in through its skills:
+        // allowlist, and that stays true when the install came through a
+        // command. --agent is the explicit way to say both at once.
+        const ids = result.installed.map((skill) => skill.id);
+        if (command.agentId === undefined) {
+            writeLine(streams.stdout);
+            writeLine(streams.stdout, 'Installed, not yet enabled. Add to an agent\'s soul frontmatter:');
+            writeLine(streams.stdout, '  skills:');
+            for (const id of ids) {
+                writeLine(streams.stdout, `    - ${id}`);
+            }
+            writeLine(streams.stdout, `(or rerun with --agent <id>, or list them: stratus skills)`);
+            return 0;
+        }
+        const roster = await loadRosterSouls(env, (line) => writeLine(streams.stderr, `Warning: ${line}`));
+        const entry = roster.find((candidate) => candidate.soul.agent.id === command.agentId);
+        if (!entry) {
+            writeLine(streams.stderr, `Error: no agent with id ${command.agentId} in ${agentsDirPath(env)}. The skills are installed; enable them by editing a soul.`);
+            return 1;
+        }
+        const existing = entry.soul.agent.skills ?? [];
+        const additions = ids.filter((id) => !matchesSkillAllowlist(id, existing));
+        if (additions.length === 0) {
+            writeLine(streams.stdout, `${entry.soul.agent.name} already has all of these enabled.`);
+            return 0;
+        }
+        // A field edit renders through formatSoul, which canonicalizes the
+        // file — same trade the control API's field edits make.
+        const next = {
+            ...entry.soul,
+            agent: { ...entry.soul.agent, skills: [...existing, ...additions] },
+        };
+        await writeFile(entry.path, formatSoul(next));
+        writeLine(streams.stdout, `enabled for ${next.agent.name} (${entry.path}): ${additions.join(', ')}`);
+        return 0;
+    }
+    finally {
+        await cleanup?.();
+    }
+};
+export const runSkills = async (streams, env = {}) => {
+    const registry = new SkillRegistry();
+    const skills = await loadOperatorSkills(env, registry, (line) => {
+        writeLine(streams.stderr, `Warning: ${line}`);
+    });
+    if (skills.length === 0) {
+        writeLine(streams.stdout, `No skills installed in ${skillsDirPath(env)}.`);
+        writeLine(streams.stdout, 'Install some: stratus skill add <owner/repo | git url | path>');
+        return 0;
+    }
+    // Who has each skill enabled, so the listing answers the question that
+    // follows "what is installed" — read from the same roster a dispatch
+    // serves. Plugin-contributed skills are the daemon's to list
+    // (/catalog/tools); this command reads the operator directory.
+    const roster = await loadRosterSouls(env, () => { }).catch(() => []);
+    for (const skill of skills) {
+        const enabledBy = roster
+            .filter((entry) => {
+            const allowlist = entry.soul.agent.skills;
+            return allowlist !== undefined
+                && allowlist.length > 0
+                && matchesSkillAllowlist(skill.id, allowlist);
+        })
+            .map((entry) => entry.soul.agent.name);
+        const suffix = enabledBy.length > 0 ? ` — enabled by ${enabledBy.join(', ')}` : ' — enabled by nobody yet';
+        writeLine(streams.stdout, `${skill.id.padEnd(24)}${skill.description}${suffix}`);
+    }
+    return 0;
+};
 export const runAgentNew = async (command, streams, env = {}) => {
     // On a real terminal, creating an agent is the same guided experience as
     // setup: a headed screen, a prefilled (editable) name, a personality, and
@@ -3533,14 +3915,12 @@ export const runAgentNew = async (command, streams, env = {}) => {
                 writeLine(streams.stdout, `Note: ${message}.`);
             });
             const soulProvider = readNonEmptyString(processEnv.STRATUS_PROVIDER, (value) => parseProviderName(value, 'STRATUS_PROVIDER'))
-                ?? readNonEmptyString(processEnv.STRATUSCLAW_PROVIDER, (value) => parseProviderName(value, 'STRATUSCLAW_PROVIDER'))
                 ?? activeConfig.provider
                 ?? 'demo';
             // The active config's model was written for the provider named in
             // that config; it only travels into the soul when they still match.
             const configModelApplies = (activeConfig.provider ?? 'openai') === soulProvider;
             const soulModel = readNonEmptyString(processEnv.STRATUS_MODEL)
-                ?? readNonEmptyString(processEnv.STRATUSCLAW_MODEL)
                 ?? (configModelApplies ? activeConfig.model : undefined)
                 ?? (soulProvider === 'openai' ? DEFAULT_OPENAI_MODEL : DEFAULT_ANTHROPIC_MODEL);
             const soulPin = soulProvider !== 'demo' ? { provider: soulProvider, model: soulModel } : {};
@@ -3787,6 +4167,31 @@ export const runDashboard = async (command, streams, env = {}) => {
     }
     return serving;
 };
+/**
+ * Resolution and loading are separate questions, and only the first one
+ * means "not installed". Inspecting an import's error message cannot tell
+ * them apart: a package that IS installed but is missing one of its own
+ * dependencies throws ERR_MODULE_NOT_FOUND naming that dependency and the
+ * importer — so a broken install would read as an absent one, silently
+ * disabling a channel whose stored tokens say it should be running, or
+ * leaving a daemon without the API an operator installed it to have.
+ */
+const defaultPackageResolver = (specifier) => {
+    try {
+        import.meta.resolve(specifier);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Whether an optional package is installed. The resolver is injectable
+ * because what is installed is a property of the machine: a test asserting
+ * on the real one would be asserting on its own node_modules, which is why
+ * every optional package is a devDependency here in the first place.
+ */
+const packageInstalled = (specifier, env = {}) => (env.packageResolver ?? defaultPackageResolver)(specifier);
 /**
  * Loads the optional Slack channel package, or undefined when it is not
  * installed. Only that package being absent is tolerated: an adapter that
@@ -3795,17 +4200,7 @@ export const runDashboard = async (command, streams, env = {}) => {
  * whose stored tokens say it should be running.
  */
 const loadSlackAdapter = async () => {
-    // Resolution and loading are separate questions, and only the first one
-    // means "not installed". Inspecting the import's error message cannot
-    // tell them apart: a package that IS installed but is missing one of
-    // its own dependencies throws ERR_MODULE_NOT_FOUND naming that
-    // dependency and this package as the importer — a broken install would
-    // read as an absent one, silently disabling a channel whose tokens say
-    // it should be running.
-    try {
-        import.meta.resolve('@stratusagent/channel-slack');
-    }
-    catch {
+    if (!packageInstalled('@stratusagent/channel-slack')) {
         return undefined;
     }
     // Resolvable: any failure from here is a real problem with the
@@ -3822,10 +4217,7 @@ const loadSlackAdapter = async () => {
  * without the API an operator installed it to have.
  */
 const loadControlApi = async () => {
-    try {
-        import.meta.resolve('@stratusagent/control-api');
-    }
-    catch {
+    if (!packageInstalled('@stratusagent/control-api')) {
         return undefined;
     }
     return (await import('@stratusagent/control-api')).createControlApi;
@@ -4245,6 +4637,12 @@ export const runCli = async ({ argv, streams = process, env = {} }) => {
         if (command.command === 'agents') {
             return await runAgents(command, streams, resolvedEnv);
         }
+        if (command.command === 'skill-add') {
+            return await runSkillAdd(command, streams, resolvedEnv);
+        }
+        if (command.command === 'skills') {
+            return await runSkills(streams, resolvedEnv);
+        }
         if (command.command === 'doctor') {
             return await runDoctor(command, streams, resolvedEnv);
         }