@solidactions/cli 1.2.0 → 1.5.0

package/README.md

@@ -18,6 +18,48 @@ solidactions run start <project> <workflow>           # Trigger a workflow
 solidactions run view <run-id>                        # Inspect a run
 ```
 
+## Configuration
+
+The CLI stores `host`, `apiKey`, and `workspaceId` in a JSON config file. Two locations are supported:
+
+- **Global** — `~/.solidactions/config.json`. Used by default, shared across all folders for a single user.
+- **Local** — `./.solidactions/config.json`. Scoped to a project folder; takes precedence over the global file when running commands from inside that folder (or any subdirectory — the CLI walks up looking for it).
+
+### Resolution order
+
+For each field (`host`, `apiKey`, `workspaceId`), the CLI resolves independently in this order:
+
+1. Environment variables: `SOLIDACTIONS_HOST`, `SOLIDACTIONS_API_KEY`, `SOLIDACTIONS_WORKSPACE_ID`
+2. Nearest local `./.solidactions/config.json` (walking up from cwd)
+3. Global `~/.solidactions/config.json`
+
+You can mix: e.g., set only `SOLIDACTIONS_WORKSPACE_ID` in the environment while letting `host` and `apiKey` come from a file.
+
+### `solidactions init` flags
+
+- `--local` — write config to `./.solidactions/config.json` in the current folder.
+- `--global` — write config to `~/.solidactions/config.json` (today's default).
+- `--gitignore` — with `--local`, auto-add `.solidactions/` to `.gitignore` without prompting.
+
+In interactive shells, `init` without `--local`/`--global` prompts for a location. In non-interactive contexts, one of the flags is required.
+
+### `solidactions logout` flags
+
+- `--local` — remove only the nearest local config (walks up from cwd).
+- `--global` — remove only the global config.
+- Bare `logout` — removes the nearest local if present, otherwise removes global.
+
+### Debugging resolution
+
+Set `SOLIDACTIONS_DEBUG=1` on any command to print the resolved configuration and per-field sources to stderr before the command runs. `solidactions whoami` also shows this information.
+
+### Use case: multiple AI agents in parallel
+
+If you run multiple AI coding agents in different project folders simultaneously, either:
+
+- Run `solidactions init <key> --local` in each folder so each has its own config, or
+- Set `SOLIDACTIONS_API_KEY` / `SOLIDACTIONS_WORKSPACE_ID` in the environment each agent uses (no files to share or stomp).
+
 ## Commands
 
 Use `solidactions <command> --help` for full flag details on any command.
@@ -85,9 +127,17 @@ Use `solidactions <command> --help` for full flag details on any command.
 
 | Command | Key Flags | Description |
 |---------|-----------|-------------|
-| `ai init` | `--claude`, `--agents` | Install AI helper docs |
+| `ai init` | `--claude`, `--agents`, `--no-skills` | Install AI helper docs |
 | `ai examples [names...]` | `--all`, `--overwrite` | Install example workflows |
 
+By default, `ai init` also installs three lazy-loaded SolidActions skills
+into `.claude/skills/`. These activate automatically when you scaffold a
+project, write workflow code, or deploy. The CLAUDE.md injection becomes
+a slim pointer to keep always-loaded context light.
+
+Pass `--no-skills` to skip the skill install and get the legacy full
+CLAUDE.md content instead.
+
 ## Development
 
 ```bash

package/dist/commands/ai-init.js

@@ -8,8 +8,10 @@ const fs_1 = __importDefault(require("fs"));
 const chalk_1 = __importDefault(require("chalk"));
 const prompts_1 = __importDefault(require("prompts"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
 const github_1 = require("../utils/github");
 const markers_1 = require("../utils/markers");
+const skills_1 = require("../utils/skills");
 async function aiInit(options = {}) {
     try {
         // Determine target file
@@ -40,15 +42,50 @@ async function aiInit(options = {}) {
             }
             targetFile = response.file;
         }
+        // Decide whether to install skills (default true; --no-skills opts out)
+        const installSkillsEnabled = options.skills !== false;
+        // Determine skill targets if installing.
+        // Skills are Claude Code-specific (.claude/skills/) and not meaningful for other AI tools.
+        let skillTargets = [];
+        if (installSkillsEnabled && targetFile === 'CLAUDE.md') {
+            skillTargets = (0, skills_1.detectSkillTargets)();
+            if (skillTargets.length === 0) {
+                const resp = await (0, prompts_1.default)({
+                    type: 'confirm',
+                    name: 'create',
+                    message: 'No `.claude/` directory found. Create `.claude/skills/` for SolidActions skills?',
+                    initial: true,
+                });
+                if (resp.create === undefined) {
+                    // User cancelled (Ctrl+C) — treat as abort, not decline
+                    console.log(chalk_1.default.yellow('Cancelled.'));
+                    process.exit(0);
+                }
+                else if (resp.create) {
+                    skillTargets = [path_1.default.join(process.cwd(), '.claude', 'skills')];
+                }
+                else {
+                    console.log(chalk_1.default.yellow('Skipping skill install. Run with --no-skills to silence this prompt.'));
+                }
+            }
+        }
         console.log(chalk_1.default.blue('Fetching AI helper content...'));
-        // Fetch AI helper content from examples repo
-        const aiContent = await (0, github_1.fetchRawFile)('SolidActions', 'solidactions-examples', 'CLAUDE.md');
-        // Fetch SDK reference
+        // Fetch CLAUDE.md content (slim pointer if skills installed, else full)
+        const aiContent = await (0, skills_1.fetchClaudeMdContent)(skillTargets.length > 0);
+        // Fetch SDK reference (always)
         const sdkContent = await (0, github_1.fetchRawFile)('SolidActions', 'solidactions-ts-sdk', 'docs/sdk-reference.md');
         // Save SDK reference to .solidactions/sdk-reference.md
         fs_extra_1.default.ensureDirSync('.solidactions');
         fs_1.default.writeFileSync('.solidactions/sdk-reference.md', sdkContent, 'utf8');
         console.log(chalk_1.default.green('✓ SDK reference saved to .solidactions/sdk-reference.md'));
+        // Install skills if enabled and targets exist
+        if (skillTargets.length > 0) {
+            console.log(chalk_1.default.blue('Installing SolidActions skills...'));
+            const { written } = await (0, skills_1.installSkills)(skillTargets);
+            for (const f of written) {
+                console.log(chalk_1.default.green(`✓ ${path_1.default.relative(process.cwd(), f)}`));
+            }
+        }
         // Upsert main AI helper section
         (0, markers_1.upsertMarkerSection)(targetFile, 'SolidActions', aiContent);
         // Upsert SDK reference pointer section

package/dist/commands/deploy.js

@@ -114,11 +114,51 @@ async function pushYamlDeclarations(config, projectSlug, yamlConfig) {
 async function deploy(projectName, sourcePath, options = {}) {
     const config = await (0, api_1.requireConfigWithWorkspace)();
     const sourceDir = sourcePath ? path_1.default.resolve(sourcePath) : process.cwd();
-    const environment = options.env || 'dev';
+    // Capture whether -e was explicitly passed by the caller. Commander leaves
+    // options.env as undefined when no default is set and the flag is omitted.
+    const explicitEnv = options.env;
     if (!fs_1.default.existsSync(sourceDir)) {
         console.error(chalk_1.default.red(`Source directory not found: ${sourceDir}`));
         process.exit(1);
     }
+    // -------------------------------------------------------------------------
+    // Production-existence check — must happen BEFORE we apply any env default
+    // so that first-time deploys without -e get a helpful error instead of
+    // silently creating a dev-only project with no production root.
+    // -------------------------------------------------------------------------
+    let productionExists = null; // null = unknown (error path)
+    let productionSlug = null;
+    try {
+        const prodResponse = await axios_1.default.get(`${config.host}/api/v1/projects/${projectName}`, {
+            headers: (0, api_1.getApiHeaders)(config),
+        });
+        productionExists = true;
+        productionSlug = prodResponse.data.slug || prodResponse.data.name;
+    }
+    catch (error) {
+        if (error.response?.status === 404) {
+            productionExists = false;
+        }
+        else {
+            // 5xx, network error, auth failure, etc. — fail conservatively rather
+            // than treating the project as non-existent and potentially creating it.
+            console.error(chalk_1.default.red('Failed to check project existence:'), error.response?.data?.message || error.message);
+            process.exit(1);
+        }
+    }
+    // Decision: if production does not exist and no -e flag was given, the user
+    // must pick an environment explicitly to avoid creating a broken dev-only project.
+    if (productionExists === false && explicitEnv === undefined) {
+        console.error(chalk_1.default.red(`\nThis is the first deploy of "${projectName}" — please pick an environment explicitly:\n`));
+        console.error(`  solidactions project deploy ${projectName} <path> -e production    # most projects start here`);
+        console.error(`  solidactions project deploy ${projectName} <path> -e dev            # dev-only (uncommon; no production root will exist)`);
+        console.error(`  solidactions project deploy ${projectName} <path> -e staging        # staging-only (uncommon)`);
+        console.error(chalk_1.default.gray('\nTip: most projects should start with `-e production`. A project needs a production root before dev/staging children can attach to it.'));
+        process.exit(1);
+    }
+    // Apply default: if production already exists and the user didn't pass -e,
+    // use 'dev' — this preserves existing behavior for mature projects.
+    const environment = explicitEnv ?? 'dev';
     const envLabel = environment !== 'production' ? ` (${environment})` : '';
     console.log(chalk_1.default.blue(`Deploying to project "${projectName}"${envLabel}...`));
     console.log(chalk_1.default.gray(`Source: ${sourceDir}`));
@@ -149,24 +189,36 @@ async function deploy(projectName, sourcePath, options = {}) {
         process.exit(1);
     }
     console.log(chalk_1.default.green('✓ Project structure validated'));
-    // Check if project exists, create if not
+    // Check if the target environment's project record exists; create if needed.
+    // For production deploys where we already confirmed existence above, reuse
+    // the cached slug to avoid a duplicate GET.
     let projectSlug = projectName;
     try {
-        // For non-production environments, append the environment to the slug for lookup
-        const lookupSlug = environment === 'production'
-            ? projectName
-            : `${projectName}-${environment}`;
-        const checkResponse = await axios_1.default.get(`${config.host}/api/v1/projects/${lookupSlug}`, {
-            headers: (0, api_1.getApiHeaders)(config),
-        });
-        projectSlug = checkResponse.data.slug || checkResponse.data.name;
+        if (environment === 'production' && productionExists === true && productionSlug !== null) {
+            // Already confirmed — skip the re-lookup.
+            projectSlug = productionSlug;
+        }
+        else {
+            // For non-production environments, append the environment to the slug for lookup
+            const lookupSlug = environment === 'production'
+                ? projectName
+                : `${projectName}-${environment}`;
+            const checkResponse = await axios_1.default.get(`${config.host}/api/v1/projects/${lookupSlug}`, {
+                headers: (0, api_1.getApiHeaders)(config),
+            });
+            projectSlug = checkResponse.data.slug || checkResponse.data.name;
+        }
     }
     catch (error) {
         if (error.response?.status === 404) {
-            // For non-production environments, check if we should create
+            // For non-production environments, require --create or give a clear hint
             if (environment !== 'production' && !options.create) {
-                console.log(chalk_1.default.yellow(`Project "${projectName}" doesn't have a ${environment} environment.`));
-                console.log(chalk_1.default.gray('Use --create to create it, or deploy to production first.'));
+                console.error(chalk_1.default.red(`\nProject "${projectName}" doesn't have a ${environment} environment.\n`));
+                console.error(`  If production is the intended target:`);
+                console.error(`    solidactions project deploy ${projectName} <path> -e production`);
+                console.error('');
+                console.error(`  If you really want a new ${environment} environment:`);
+                console.error(`    solidactions project deploy ${projectName} <path> -e ${environment} --create`);
                 process.exit(1);
             }
             console.log(chalk_1.default.yellow(`Project "${projectName}"${envLabel} not found. Creating...`));

package/dist/commands/init.js

@@ -11,41 +11,83 @@ exports.logout = logout;
 exports.whoami = whoami;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const os_1 = __importDefault(require("os"));
+const readline_1 = __importDefault(require("readline"));
 const chalk_1 = __importDefault(require("chalk"));
 const api_1 = require("../utils/api");
 const workspaces_1 = require("./workspaces");
-const CONFIG_DIR = path_1.default.join(os_1.default.homedir(), '.solidactions');
-const CONFIG_FILE = path_1.default.join(CONFIG_DIR, 'config.json');
+const config_1 = require("../utils/config");
 function getConfig() {
-    if (!fs_1.default.existsSync(CONFIG_FILE)) {
-        return null;
-    }
+    const resolved = (0, config_1.resolveConfig)();
+    return resolved ? resolved.config : null;
+}
+function saveConfig(config) {
+    const resolved = (0, config_1.resolveConfig)();
+    const targetPath = resolved ? resolved.activePath : (0, config_1.getGlobalConfigPath)();
+    (0, config_1.writeConfigFile)(targetPath, config);
+}
+function clearConfig() {
+    (0, config_1.removeConfigFile)((0, config_1.getGlobalConfigPath)());
+}
+async function promptLocation() {
+    const rl = readline_1.default.createInterface({ input: process.stdin, output: process.stdout });
     try {
-        const config = JSON.parse(fs_1.default.readFileSync(CONFIG_FILE, 'utf-8'));
-        // Handle legacy config format (token -> apiKey)
-        if (config.token && !config.apiKey) {
-            config.apiKey = config.token;
+        while (true) {
+            const answer = await new Promise((resolve) => {
+                rl.question(chalk_1.default.blue('Save config locally (./.solidactions) or globally (~/.solidactions)? [global] '), resolve);
+            });
+            const normalized = answer.trim().toLowerCase();
+            if (normalized === '' || normalized === 'global' || normalized === 'g')
+                return 'global';
+            if (normalized === 'local' || normalized === 'l')
+                return 'local';
+            console.log(chalk_1.default.yellow("Please answer 'local' or 'global' (or press Enter for global)."));
         }
-        return config;
     }
-    catch {
-        return null;
+    finally {
+        rl.close();
     }
 }
-function saveConfig(config) {
-    if (!fs_1.default.existsSync(CONFIG_DIR)) {
-        fs_1.default.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+async function ensureGitignoreCovers(targetDir, auto) {
+    const gitignorePath = path_1.default.join(targetDir, '.gitignore');
+    const patternToAdd = '.solidactions/';
+    let existing = '';
+    if (fs_1.default.existsSync(gitignorePath)) {
+        existing = fs_1.default.readFileSync(gitignorePath, 'utf-8');
+        const lines = existing.split('\n').map((l) => l.trim());
+        const isCovered = lines.some((line) => {
+            const normalized = line
+                .replace(/^\*\*\//, '')
+                .replace(/^\//, '')
+                .replace(/\/(\*\*|\*)?$/, '');
+            return normalized === '.solidactions';
+        });
+        if (isCovered) {
+            return; // already covered
+        }
     }
-    fs_1.default.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
-}
-function clearConfig() {
-    if (fs_1.default.existsSync(CONFIG_FILE)) {
-        fs_1.default.unlinkSync(CONFIG_FILE);
+    let shouldAdd = auto;
+    if (!shouldAdd && process.stdin.isTTY) {
+        const rl = readline_1.default.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise((resolve) => {
+            rl.question(chalk_1.default.yellow(`Local config contains an API key. Add \`.solidactions/\` to ${gitignorePath}? [Y/n] `), resolve);
+        });
+        rl.close();
+        shouldAdd = !(answer.trim().toLowerCase().startsWith('n'));
+    }
+    if (!shouldAdd) {
+        console.log(chalk_1.default.yellow(`Skipping .gitignore update. Remember: ${path_1.default.join(targetDir, '.solidactions', 'config.json')} contains your API key.`));
+        return;
+    }
+    const prefix = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+    try {
+        fs_1.default.writeFileSync(gitignorePath, `${existing}${prefix}${patternToAdd}\n`);
+        console.log(chalk_1.default.green(`Added \`${patternToAdd}\` to ${gitignorePath}.`));
+    }
+    catch (err) {
+        console.log(chalk_1.default.yellow(`Could not update ${gitignorePath}: ${err.message}. Add \`.solidactions/\` to it manually — ${path_1.default.join(targetDir, '.solidactions', 'config.json')} contains your API key.`));
     }
 }
 async function init(apiKey, options) {
-    // Determine host
     let host;
     if (options.host) {
         host = options.host;
@@ -56,24 +98,48 @@ async function init(apiKey, options) {
     else {
         host = 'https://app.solidactions.com';
     }
-    // Validate API key format (should be a Sanctum token)
     if (!apiKey || apiKey.trim().length === 0) {
         console.error(chalk_1.default.red('Error: API key is required.'));
         console.log(chalk_1.default.gray('Generate an API key at: ') + chalk_1.default.blue(`${host}/settings/api-keys`));
         process.exit(1);
     }
+    // Determine target location.
+    let target;
+    if (options.local && options.global) {
+        console.error(chalk_1.default.red('Error: --local and --global are mutually exclusive.'));
+        process.exit(1);
+    }
+    else if (options.local) {
+        target = 'local';
+    }
+    else if (options.global) {
+        target = 'global';
+    }
+    else if (process.stdin.isTTY) {
+        target = await promptLocation();
+    }
+    else {
+        console.error(chalk_1.default.red('Refusing to init non-interactively. Pass --local or --global.'));
+        process.exit(1);
+    }
+    const targetPath = target === 'local' ? (0, config_1.getLocalConfigPath)() : (0, config_1.getGlobalConfigPath)();
     console.log(chalk_1.default.blue(`Initializing SolidActions CLI...`));
     console.log(chalk_1.default.gray(`Host: ${host}`));
-    // Save the configuration
+    if ((0, config_1.readConfigFile)(targetPath)) {
+        console.log(chalk_1.default.yellow(`Existing config at ${targetPath} will be overwritten.`));
+    }
     const config = {
         host,
         apiKey: apiKey.trim(),
     };
-    saveConfig(config);
+    (0, config_1.writeConfigFile)(targetPath, config);
+    if (target === 'local') {
+        await ensureGitignoreCovers(process.cwd(), !!options.gitignore);
+    }
     console.log(chalk_1.default.green('CLI initialized successfully!'));
-    console.log(chalk_1.default.gray(`Configuration saved to ${CONFIG_FILE}`));
+    console.log(chalk_1.default.gray(`Configuration saved to ${targetPath}`));
     console.log('');
-    // Set workspace — explicit flag or interactive prompt
+    // Workspace selection — ensureWorkspaceSelected writes to the right file via the resolver.
     try {
         if (options.workspace) {
             await (0, workspaces_1.workspaceSet)(options.workspace);
@@ -91,23 +157,55 @@ async function init(apiKey, options) {
     console.log(chalk_1.default.gray('  solidactions run start <proj> <wf>    Run a workflow'));
     console.log(chalk_1.default.gray('  solidactions run list                 List recent runs'));
 }
-async function logout() {
-    if (fs_1.default.existsSync(CONFIG_FILE)) {
-        clearConfig();
-        console.log(chalk_1.default.green('Logged out successfully.'));
+function logout(options = {}) {
+    if (options.local && options.global) {
+        console.error(chalk_1.default.red('Error: --local and --global are mutually exclusive.'));
+        process.exit(1);
+    }
+    const globalPath = (0, config_1.getGlobalConfigPath)();
+    const localPath = (0, config_1.findLocalConfigPath)(process.cwd());
+    let targetPath;
+    if (options.local) {
+        targetPath = localPath;
+        if (!targetPath) {
+            console.error(chalk_1.default.red(`No local config found in ${process.cwd()} or any parent directory.`));
+            process.exit(1);
+        }
+    }
+    else if (options.global) {
+        targetPath = globalPath;
     }
     else {
-        console.log(chalk_1.default.gray('Not logged in.'));
+        targetPath = localPath ?? globalPath;
+    }
+    const removed = (0, config_1.removeConfigFile)(targetPath);
+    if (removed) {
+        console.log(chalk_1.default.green(`Logged out. Removed ${targetPath}`));
+    }
+    else {
+        console.log(chalk_1.default.gray(`Not logged in (no config at ${targetPath}).`));
     }
 }
-async function whoami() {
-    const config = getConfig();
-    if (!config) {
+function whoami() {
+    const resolved = (0, config_1.resolveConfig)();
+    if (!resolved || !resolved.config.apiKey) {
         console.log(chalk_1.default.yellow('Not initialized.'));
         console.log(chalk_1.default.gray('Run "solidactions init <api-key>" to configure.'));
         process.exit(1);
     }
+    const { config, sources } = resolved;
+    const maskedKey = config.apiKey.length > 12
+        ? `${config.apiKey.substring(0, 8)}...${config.apiKey.slice(-4)}`
+        : config.apiKey;
+    const fmt = (src) => {
+        if (src === 'env')
+            return chalk_1.default.gray('(from $SOLIDACTIONS_* env var)');
+        if (src === null)
+            return chalk_1.default.gray('(unset)');
+        return chalk_1.default.gray(`(from ${src})`);
+    };
     console.log(chalk_1.default.blue('Current configuration:'));
-    console.log(`  Host: ${config.host}`);
-    console.log(`  API Key: ${config.apiKey.substring(0, 8)}...${config.apiKey.slice(-4)}`);
+    console.log(`  Host:        ${config.host.padEnd(40)} ${fmt(sources.host)}`);
+    console.log(`  API Key:     ${maskedKey.padEnd(40)} ${fmt(sources.apiKey)}`);
+    console.log(`  Workspace:   ${(config.workspaceId ?? '').padEnd(40)} ${fmt(sources.workspaceId)}`);
 }

package/dist/commands/workspaces.js

@@ -8,7 +8,7 @@ exports.workspaceSet = workspaceSet;
 const axios_1 = __importDefault(require("axios"));
 const chalk_1 = __importDefault(require("chalk"));
 const api_1 = require("../utils/api");
-const init_1 = require("./init");
+const config_1 = require("../utils/config");
 async function workspacesList() {
     const config = (0, api_1.requireConfig)();
     try {
@@ -53,8 +53,13 @@ async function workspacesList() {
     }
 }
 async function workspaceSet(workspaceId) {
-    const config = (0, api_1.requireConfig)();
-    // Validate the workspace exists and user has access
+    if (process.env.SOLIDACTIONS_WORKSPACE_ID) {
+        console.error(chalk_1.default.red('SOLIDACTIONS_WORKSPACE_ID is set in the environment; the change would not take effect. ' +
+            'Unset the env var or edit the config file directly.'));
+        process.exit(1);
+    }
+    const resolved = (0, api_1.requireResolvedConfig)();
+    const config = resolved.config;
     try {
         const response = await axios_1.default.get(`${config.host}/api/v1/workspaces`, {
             headers: {
@@ -62,7 +67,6 @@ async function workspaceSet(workspaceId) {
                 'Accept': 'application/json',
             },
         });
-        // Flatten grouped response
         const grouped = response.data.workspaces || response.data.data || response.data;
         let allWorkspaces = [];
         if (typeof grouped === 'object' && !Array.isArray(grouped)) {
@@ -78,9 +82,10 @@ async function workspaceSet(workspaceId) {
             console.error(chalk_1.default.red(`Workspace "${workspaceId}" not found. Run \`solidactions workspace list\` to list available workspaces.`));
             process.exit(1);
         }
-        config.workspaceId = workspace.id;
-        (0, init_1.saveConfig)(config);
+        const updated = { ...config, workspaceId: workspace.id };
+        (0, config_1.writeConfigFile)(resolved.activePath, updated);
         console.log(chalk_1.default.green(`Workspace set to: ${workspace.name} (${workspace.id})`));
+        console.log(chalk_1.default.gray(`Saved to ${resolved.activePath}`));
     }
     catch (error) {
         console.error(chalk_1.default.red('Failed to set workspace:'), error.response?.data?.message || error.message);

package/dist/index.js

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+const chalk_1 = __importDefault(require("chalk"));
 const commander_1 = require("commander");
 const deploy_1 = require("./commands/deploy");
 const init_1 = require("./commands/init");
@@ -27,6 +31,28 @@ const workspaces_1 = require("./commands/workspaces");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const pkg = require('../package.json');
 const program = new commander_1.Command();
+if (process.env.SOLIDACTIONS_DEBUG === '1') {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { resolveConfig } = require('./utils/config');
+    const resolved = resolveConfig();
+    if (resolved) {
+        const fmt = (src) => {
+            if (src === 'env')
+                return '(from $SOLIDACTIONS_* env var)';
+            if (src === null)
+                return '(unset)';
+            return `(from ${src})`;
+        };
+        process.stderr.write('[SOLIDACTIONS_DEBUG] resolved configuration:\n');
+        process.stderr.write(`  host:        ${resolved.config.host} ${fmt(resolved.sources.host)}\n`);
+        process.stderr.write(`  apiKey:      <redacted> ${fmt(resolved.sources.apiKey)}\n`);
+        process.stderr.write(`  workspaceId: ${resolved.config.workspaceId ?? ''} ${fmt(resolved.sources.workspaceId)}\n`);
+        process.stderr.write(`  activePath:  ${resolved.activePath}\n`);
+    }
+    else {
+        process.stderr.write('[SOLIDACTIONS_DEBUG] no config resolvable\n');
+    }
+}
 program
     .name('solidactions')
     .description('SolidActions CLI - Deploy and manage workflow automation')
@@ -41,14 +67,19 @@ program
     .option('--dev', 'Use local development server (http://localhost:8000)')
     .option('--host <url>', 'Custom API host URL')
     .option('--workspace <name-or-id>', 'Set workspace by name, slug, or ID (skips interactive prompt)')
-    .action((apiKey, options) => {
-    (0, init_1.init)(apiKey, options);
+    .option('--local', 'Save config to ./.solidactions/config.json in the current folder')
+    .option('--global', 'Save config to ~/.solidactions/config.json (default if prompted)')
+    .option('--gitignore', 'With --local, add .solidactions/ to .gitignore without prompting')
+    .action(async (apiKey, options) => {
+    await (0, init_1.init)(apiKey, options);
 });
 program
     .command('logout')
     .description('Remove saved credentials')
-    .action(() => {
-    (0, init_1.logout)();
+    .option('--local', 'Remove only the nearest local ./.solidactions/config.json')
+    .option('--global', 'Remove only ~/.solidactions/config.json')
+    .action((options) => {
+    (0, init_1.logout)(options);
 });
 program
     .command('whoami')
@@ -73,7 +104,7 @@ project
     .description('Deploy a project to SolidActions')
     .argument('<project-name>', 'Project name (will be created if it doesn\'t exist)')
     .argument('[path]', 'Source directory to deploy (defaults to current directory)')
-    .option('-e, --env <environment>', 'Target environment (production/staging/dev)', 'dev')
+    .option('-e, --env <environment>', 'Target environment (production/staging/dev). Required on first deploy of a new project.')
     .option('--create', 'Create environment project if it doesn\'t exist')
     .option('--config-only', 'Sync YAML env declarations without building/deploying')
     .action((projectName, path, options) => {
@@ -283,6 +314,7 @@ ai
     .description('Install AI helper documentation (CLAUDE.md or AGENTS.md) for AI-assisted workflow development')
     .option('--claude', 'Use CLAUDE.md (for Claude Code)')
     .option('--agents', 'Use AGENTS.md (for Cursor, Windsurf, etc.)')
+    .option('--no-skills', 'Skip installing SolidActions skill files (uses legacy full CLAUDE.md injection)')
     .action((options) => { (0, ai_init_1.aiInit)(options); });
 ai
     .command('examples')
@@ -291,4 +323,7 @@ ai
     .option('--all', 'Install all available examples')
     .option('--overwrite', 'Overwrite existing examples without warning')
     .action((names, options) => { (0, ai_examples_1.aiExamples)(names, options); });
-program.parse();
+program.parseAsync().catch((err) => {
+    console.error(chalk_1.default.red(err.message ?? String(err)));
+    process.exit(1);
+});

package/dist/utils/api.js

@@ -4,40 +4,46 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getApiHeaders = getApiHeaders;
-exports.ensureWorkspaceSelected = ensureWorkspaceSelected;
+exports.requireResolvedConfig = requireResolvedConfig;
 exports.requireConfig = requireConfig;
+exports.ensureWorkspaceSelected = ensureWorkspaceSelected;
 exports.requireConfigWithWorkspace = requireConfigWithWorkspace;
 const axios_1 = __importDefault(require("axios"));
 const chalk_1 = __importDefault(require("chalk"));
 const readline_1 = __importDefault(require("readline"));
-const init_1 = require("../commands/init");
-/**
- * Get standard API headers including X-Workspace-Id if configured.
- */
+const config_1 = require("./config");
 function getApiHeaders(config, contentType) {
     const headers = {
         'Authorization': `Bearer ${config.apiKey}`,
         'Accept': 'application/json',
     };
-    if (contentType) {
+    if (contentType)
         headers['Content-Type'] = contentType;
-    }
-    if (config.workspaceId) {
+    if (config.workspaceId)
         headers['X-Workspace-Id'] = config.workspaceId;
-    }
     return headers;
 }
 /**
- * Ensure a workspace is selected. If not configured, fetches workspaces and auto-selects
- * (if only one) or prompts the user to choose.
- *
- * Returns the config with workspaceId set, or exits if no workspaces available.
+ * Get the full resolution (config + sources + activePath). Exits if nothing resolvable.
  */
+function requireResolvedConfig() {
+    const resolved = (0, config_1.resolveConfig)();
+    if (!resolved || !resolved.config.apiKey) {
+        console.error(chalk_1.default.red('Not initialized. Run `solidactions init <api-key>` first.'));
+        process.exit(1);
+    }
+    return resolved;
+}
+function requireConfig() {
+    return requireResolvedConfig().config;
+}
 async function ensureWorkspaceSelected(config) {
     if (config.workspaceId) {
         return config;
     }
-    // Fetch workspaces from API (this endpoint doesn't require X-Workspace-Id)
+    // Re-resolve so we know whether a save would be redundant (env-provided) or meaningful (file-backed).
+    const resolved = (0, config_1.resolveConfig)();
+    const workspaceSource = resolved?.sources.workspaceId ?? null;
     let workspaces;
     try {
         const response = await axios_1.default.get(`${config.host}/api/v1/workspaces`, {
@@ -46,8 +52,6 @@ async function ensureWorkspaceSelected(config) {
                 'Accept': 'application/json',
             },
         });
-        // API returns { workspaces: { "Org Name": [{ id, name, role, tenant_name, ... }] } }
-        // Flatten the grouped structure into a flat array
         const grouped = response.data.workspaces || response.data.teams || response.data.data || response.data;
         if (typeof grouped === 'object' && !Array.isArray(grouped)) {
             workspaces = [];
@@ -85,7 +89,6 @@ async function ensureWorkspaceSelected(config) {
         console.log(chalk_1.default.gray(`Auto-selected workspace: ${selected.name}`));
     }
     else {
-        // Prompt user to select
         console.log(chalk_1.default.blue('\nSelect a workspace:\n'));
         workspaces.forEach((ws, i) => {
             console.log(`  ${chalk_1.default.white(`${i + 1}.`)} ${ws.name} ${chalk_1.default.gray(`(${ws.org_name}, ${ws.role})`)}`);
@@ -103,26 +106,14 @@ async function ensureWorkspaceSelected(config) {
         }
         selected = workspaces[index];
     }
-    // Save workspace selection to config
     config.workspaceId = selected.id;
-    (0, init_1.saveConfig)(config);
-    console.log(chalk_1.default.green(`Workspace set: ${selected.name}`));
-    return config;
-}
-/**
- * Get config and ensure it's initialized. Exits if not.
- */
-function requireConfig() {
-    const config = (0, init_1.getConfig)();
-    if (!config?.apiKey) {
-        console.error(chalk_1.default.red('Not initialized. Run `solidactions init <api-key>` first.'));
-        process.exit(1);
+    if (workspaceSource !== 'env') {
+        const targetPath = resolved?.activePath ?? (0, config_1.getGlobalConfigPath)();
+        (0, config_1.writeConfigFile)(targetPath, config);
     }
+    console.log(chalk_1.default.green(`Workspace set: ${selected.name}`));
     return config;
 }
-/**
- * Get config with workspace selected. Use this for any command that needs workspace context.
- */
 async function requireConfigWithWorkspace() {
     const config = requireConfig();
     return ensureWorkspaceSelected(config);

package/dist/utils/config.js

@@ -0,0 +1,138 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGlobalConfigPath = getGlobalConfigPath;
+exports.getLocalConfigPath = getLocalConfigPath;
+exports.findLocalConfigPath = findLocalConfigPath;
+exports.readConfigFile = readConfigFile;
+exports.writeConfigFile = writeConfigFile;
+exports.removeConfigFile = removeConfigFile;
+exports.resolveConfig = resolveConfig;
+// src/utils/config.ts
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const GLOBAL_DIR = path_1.default.join(os_1.default.homedir(), '.solidactions');
+const GLOBAL_FILE = path_1.default.join(GLOBAL_DIR, 'config.json');
+const LOCAL_DIR_NAME = '.solidactions';
+const LOCAL_FILE_NAME = 'config.json';
+function getGlobalConfigPath() {
+    return GLOBAL_FILE;
+}
+function getLocalConfigPath(cwd = process.cwd()) {
+    return path_1.default.join(cwd, LOCAL_DIR_NAME, LOCAL_FILE_NAME);
+}
+/**
+ * Walk up from startDir looking for `.solidactions/config.json`.
+ * Stops at filesystem root. **Skips `$HOME` itself** so the global config
+ * at `~/.solidactions/config.json` is never matched as a local hit.
+ * Returns the absolute path of the nearest local config, or null.
+ */
+function findLocalConfigPath(startDir = process.cwd()) {
+    const home = os_1.default.homedir();
+    let dir = path_1.default.resolve(startDir);
+    while (true) {
+        if (dir !== home) {
+            const candidate = path_1.default.join(dir, LOCAL_DIR_NAME, LOCAL_FILE_NAME);
+            if (fs_1.default.existsSync(candidate)) {
+                return candidate;
+            }
+        }
+        const parent = path_1.default.dirname(dir);
+        if (parent === dir) {
+            return null;
+        }
+        dir = parent;
+    }
+}
+/**
+ * Read a config file. Normalizes the legacy `token` field into `apiKey`.
+ * Returns null if the file does not exist or cannot be parsed.
+ */
+function readConfigFile(filePath) {
+    if (!fs_1.default.existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const raw = JSON.parse(fs_1.default.readFileSync(filePath, 'utf-8'));
+        if (raw.token && !raw.apiKey) {
+            raw.apiKey = raw.token;
+        }
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Atomic write: writes to `<filePath>.tmp` and renames into place.
+ * Creates parent directory with mode 0o700 if missing.
+ * File is written with mode 0o600.
+ */
+function writeConfigFile(filePath, config) {
+    const dir = path_1.default.dirname(filePath);
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    const tmp = `${filePath}.tmp`;
+    fs_1.default.writeFileSync(tmp, JSON.stringify(config, null, 2), { mode: 0o600 });
+    fs_1.default.renameSync(tmp, filePath);
+}
+function removeConfigFile(filePath) {
+    if (!fs_1.default.existsSync(filePath)) {
+        return false;
+    }
+    fs_1.default.unlinkSync(filePath);
+    return true;
+}
+function readEnvOverrides() {
+    const env = {};
+    if (process.env.SOLIDACTIONS_HOST)
+        env.host = process.env.SOLIDACTIONS_HOST;
+    if (process.env.SOLIDACTIONS_API_KEY)
+        env.apiKey = process.env.SOLIDACTIONS_API_KEY;
+    if (process.env.SOLIDACTIONS_WORKSPACE_ID)
+        env.workspaceId = process.env.SOLIDACTIONS_WORKSPACE_ID;
+    return env;
+}
+/**
+ * Resolve config by merging three layers field-by-field (env > local > global).
+ * Returns null only when no source contributes an apiKey AND host (i.e. nothing usable).
+ * `activePath` is the file a write-mutating command should target: nearest local if present, else global.
+ */
+function resolveConfig(cwd = process.cwd()) {
+    const env = readEnvOverrides();
+    const localPath = findLocalConfigPath(cwd);
+    const local = localPath ? readConfigFile(localPath) : null;
+    const global = readConfigFile(getGlobalConfigPath());
+    const pick = (key) => {
+        if (env[key] !== undefined)
+            return { value: env[key], source: 'env' };
+        if (local && local[key] !== undefined)
+            return { value: local[key], source: localPath };
+        if (global && global[key] !== undefined)
+            return { value: global[key], source: getGlobalConfigPath() };
+        return { value: undefined, source: null };
+    };
+    const host = pick('host');
+    const apiKey = pick('apiKey');
+    const workspaceId = pick('workspaceId');
+    if (!host.value && !apiKey.value) {
+        return null;
+    }
+    return {
+        config: {
+            host: (host.value ?? ''),
+            apiKey: (apiKey.value ?? ''),
+            workspaceId: workspaceId.value,
+        },
+        sources: {
+            host: host.source,
+            apiKey: apiKey.source,
+            workspaceId: workspaceId.source,
+        },
+        activePath: localPath ?? getGlobalConfigPath(),
+    };
+}

package/dist/utils/skills.js

@@ -0,0 +1,71 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectSkillTargets = detectSkillTargets;
+exports.installSkills = installSkills;
+exports.fetchClaudeMdContent = fetchClaudeMdContent;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const github_1 = require("./github");
+const SKILL_NAMES = [
+    'solidactions-getting-started',
+    'solidactions-workflow-coding',
+    'solidactions-deploy-and-config',
+];
+const EXAMPLES_OWNER = 'SolidActions';
+const EXAMPLES_REPO = 'solidactions-examples';
+const SKILLS_PATH_PREFIX = 'skills';
+/**
+ * Detect which AI-tool skill directories should receive skills.
+ * Returns absolute paths to the target skills/ subdirectories.
+ *
+ * v1 supports Claude Code only. Codex was resolved as user-global
+ * (~/.codex/skills) with no project-local equivalent, so it is
+ * intentionally NOT a target here.
+ *
+ * Detection rules:
+ * - If `.claude/` exists in cwd → include `.claude/skills/`
+ * - If neither exists → return empty (caller should prompt)
+ */
+function detectSkillTargets(cwd = process.cwd()) {
+    const targets = [];
+    if (fs_1.default.existsSync(path_1.default.join(cwd, '.claude'))) {
+        targets.push(path_1.default.join(cwd, '.claude', 'skills'));
+    }
+    return targets;
+}
+/**
+ * Fetch all SolidActions skill files from the examples repo and write
+ * them into each target directory. Overwrites existing files (skills
+ * are versioned upstream).
+ */
+async function installSkills(targetDirs) {
+    const written = [];
+    for (const dir of targetDirs) {
+        fs_extra_1.default.ensureDirSync(dir);
+    }
+    for (const skillName of SKILL_NAMES) {
+        const remotePath = `${SKILLS_PATH_PREFIX}/${skillName}.md`;
+        const content = await (0, github_1.fetchRawFile)(EXAMPLES_OWNER, EXAMPLES_REPO, remotePath);
+        for (const dir of targetDirs) {
+            const filePath = path_1.default.join(dir, `${skillName}.md`);
+            fs_1.default.writeFileSync(filePath, content, 'utf8');
+            written.push(filePath);
+        }
+    }
+    return { written };
+}
+/**
+ * Pick the right CLAUDE.md content variant from the examples repo
+ * based on whether skills are being installed.
+ *
+ * - skillsInstalled = true  → fetches CLAUDE-skills-pointer.md (slim)
+ * - skillsInstalled = false → fetches CLAUDE.md (full, legacy)
+ */
+async function fetchClaudeMdContent(skillsInstalled) {
+    const file = skillsInstalled ? 'CLAUDE-skills-pointer.md' : 'CLAUDE.md';
+    return (0, github_1.fetchRawFile)(EXAMPLES_OWNER, EXAMPLES_REPO, file);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@solidactions/cli",
-    "version": "1.2.0",
+    "version": "1.5.0",
     "description": "SolidActions CLI - Deploy and manage workflow automation",
     "main": "dist/index.js",
     "bin": {