@solidactions/cli 1.5.0 → 1.7.0

package/README.md

@@ -11,10 +11,11 @@ npm install -g @solidactions/cli
 ## Quick Start
 
 ```bash
-solidactions init <api-key>                          # Initialize (prompts for workspace)
-solidactions init <api-key> --workspace <name>       # Initialize with workspace
-solidactions project deploy <project> <path>         # Deploy a project
-solidactions run start <project> <workflow>           # Trigger a workflow
+solidactions login <api-key>                          # Authenticate (prompts for workspace)
+solidactions init my-project                          # Scaffold a new project (files + AI skills)
+cd my-project
+solidactions project deploy my-project -e production  # Deploy it
+solidactions run start my-project <workflow>          # Trigger a workflow
 solidactions run view <run-id>                        # Inspect a run
 ```
 
@@ -35,13 +36,13 @@ For each field (`host`, `apiKey`, `workspaceId`), the CLI resolves independently
 
 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
+### `solidactions login` 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.
+In interactive shells, `login` without `--local`/`--global` prompts for a location. In non-interactive contexts, one of the flags is required.
 
 ### `solidactions logout` flags
 
@@ -57,7 +58,7 @@ Set `SOLIDACTIONS_DEBUG=1` on any command to print the resolved configuration an
 
 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
+- Run `solidactions login <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
@@ -68,9 +69,10 @@ Use `solidactions <command> --help` for full flag details on any command.
 
 | Command | Description |
 |---------|-------------|
-| `init <api-key>` | Initialize CLI with API key |
+| `login <api-key>` | Authenticate CLI with API key |
 | `logout` | Remove saved credentials |
 | `whoami` | Show current configuration |
+| `init [directory]` | Scaffold a new project (files + AI skills) |
 | `dev <file>` | Run a workflow locally (no deploy needed) |
 
 ### project
@@ -127,16 +129,20 @@ Use `solidactions <command> --help` for full flag details on any command.
 
 | Command | Key Flags | Description |
 |---------|-----------|-------------|
-| `ai init` | `--claude`, `--agents`, `--no-skills` | Install AI helper docs |
+| `ai init` | `--claude`, `--agents` | Install AI skills and SDK reference into an **existing** project (use `init` for new projects) |
 | `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.
+`ai init` installs three auto-activating SolidActions skills and a
+full SDK reference into your project:
+
+- Skills go to `.claude/skills/` (for `--claude` / Claude Code) or
+  `.agents/skills/` (for `--agents` / Codex, Cursor, Gemini, Windsurf).
+  Codex auto-discovers the `.agents/skills/` path — see
+  https://developers.openai.com/codex/skills.
+- The SDK reference is saved to `.solidactions/sdk-reference.md`.
+- A slim pointer section is injected into `CLAUDE.md` or `AGENTS.md`
+  listing the skills and inlining the highest-cost hard rules
+  (determinism, step discipline, messaging) as a safety net.
 
 ## Development
 

package/dist/commands/ai-init.js

@@ -14,7 +14,7 @@ const markers_1 = require("../utils/markers");
 const skills_1 = require("../utils/skills");
 async function aiInit(options = {}) {
     try {
-        // Determine target file
+        // Determine target file.
         let targetFile;
         if (options.claude && options.agents) {
             console.error(chalk_1.default.red('Please specify only one of --claude or --agents'));
@@ -32,8 +32,8 @@ async function aiInit(options = {}) {
                 name: 'file',
                 message: 'Which AI helper file?',
                 choices: [
-                    { title: 'CLAUDE.md', value: 'CLAUDE.md' },
-                    { title: 'AGENTS.md', value: 'AGENTS.md' },
+                    { title: 'CLAUDE.md (Claude Code)', value: 'CLAUDE.md' },
+                    { title: 'AGENTS.md (Codex, Cursor, Gemini, etc.)', value: 'AGENTS.md' },
                 ],
             });
             if (!response.file) {
@@ -42,58 +42,27 @@ 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 CLAUDE.md content (slim pointer if skills installed, else full)
-        const aiContent = await (0, skills_1.fetchClaudeMdContent)(skillTargets.length > 0);
-        // Fetch SDK reference (always)
+        // Fetch slim helper content for the chosen target.
+        const aiContent = await (0, skills_1.fetchAiHelperContent)(targetFile);
+        // 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
+        // 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)}`));
-            }
+        // Always install skills — no prompt. The user chose `ai init <target>`,
+        // so they want AI tooling set up.
+        const targetDir = (0, skills_1.skillTargetDir)(targetFile);
+        console.log(chalk_1.default.blue(`Installing SolidActions skills to ${path_1.default.relative(process.cwd(), targetDir)}/ ...`));
+        const { written } = await (0, skills_1.installSkills)(targetDir);
+        for (const f of written) {
+            console.log(chalk_1.default.green(`✓ ${path_1.default.relative(process.cwd(), f)}`));
         }
-        // Upsert main AI helper section
+        // Upsert the AI helper marker section.
         (0, markers_1.upsertMarkerSection)(targetFile, 'SolidActions', aiContent);
-        // Upsert SDK reference pointer section
-        const sdkReferenceNote = `## SolidActions SDK Reference
-
-The full SDK API reference is available at \`.solidactions/sdk-reference.md\`. Refer to it for detailed function signatures, error classes, retry configuration, and advanced patterns like forking, streaming, and signal URLs.`;
-        (0, markers_1.upsertMarkerSection)(targetFile, 'SolidActions SDK Reference', sdkReferenceNote);
         console.log(chalk_1.default.green(`✓ AI helper installed to ${targetFile}`));
+        console.log(chalk_1.default.gray('  Existing files may still contain a separate "SolidActions SDK Reference" marker block from older CLI versions. That content is now redundant and can be deleted manually.'));
     }
     catch (error) {
         if (error.message?.includes('rate limit')) {

package/dist/commands/init.js

@@ -3,209 +3,89 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getConfig = getConfig;
-exports.saveConfig = saveConfig;
-exports.clearConfig = clearConfig;
 exports.init = init;
-exports.logout = logout;
-exports.whoami = whoami;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-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_1 = require("../utils/config");
-function getConfig() {
-    const resolved = (0, config_1.resolveConfig)();
-    return resolved ? resolved.config : null;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const github_1 = require("../utils/github");
+const ai_init_1 = require("./ai-init");
+const EXAMPLES_OWNER = 'SolidActions';
+const EXAMPLES_REPO = 'solidactions-examples';
+const TEMPLATE_PREFIX = 'templates/minimal';
+// Tuples of [remote-path-suffix-under-template-prefix, local-path-relative-to-target].
+const TEMPLATE_FILES = [
+    ['package.json', 'package.json'],
+    ['tsconfig.json', 'tsconfig.json'],
+    ['solidactions.yaml', 'solidactions.yaml'],
+    ['.env.example', '.env.example'],
+    ['src/hello.ts', 'src/hello.ts'],
+];
+function firstNonDotEntry(target) {
+    if (!fs_1.default.existsSync(target))
+        return null;
+    const entries = fs_1.default.readdirSync(target);
+    for (const entry of entries) {
+        if (entry.startsWith('.'))
+            continue;
+        return entry;
+    }
+    return 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 });
+async function init(directory, options = {}) {
     try {
-        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)."));
+        const cwd = process.cwd();
+        const installSkills = options.skills !== false; // default true
+        const targetDir = directory ? path_1.default.resolve(cwd, directory) : cwd;
+        const projectName = path_1.default.basename(targetDir);
+        if (directory) {
+            fs_extra_1.default.ensureDirSync(targetDir);
         }
-    }
-    finally {
-        rl.close();
-    }
-}
-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
+        const offender = firstNonDotEntry(targetDir);
+        if (offender) {
+            console.error(chalk_1.default.red(`Target directory "${targetDir}" is not empty (contains "${offender}").`));
+            console.error(chalk_1.default.gray('Run in a fresh directory, or use `solidactions ai init` to add AI tooling to an existing project.'));
+            process.exit(1);
         }
-    }
-    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}.`));
+        console.log(chalk_1.default.blue(`Scaffolding "${projectName}" in ${targetDir}...`));
+        for (const [remoteSuffix, localSuffix] of TEMPLATE_FILES) {
+            const remotePath = `${TEMPLATE_PREFIX}/${remoteSuffix}`;
+            let content = await (0, github_1.fetchRawFile)(EXAMPLES_OWNER, EXAMPLES_REPO, remotePath);
+            content = content.replace(/__PROJECT_NAME__/g, projectName);
+            const outPath = path_1.default.join(targetDir, localSuffix);
+            fs_extra_1.default.ensureDirSync(path_1.default.dirname(outPath));
+            fs_1.default.writeFileSync(outPath, content, 'utf8');
+            console.log(chalk_1.default.green(`✓ ${path_1.default.relative(cwd, outPath)}`));
+        }
+        if (installSkills) {
+            console.log('');
+            process.chdir(targetDir);
+            await (0, ai_init_1.aiInit)({ claude: options.claude, agents: options.agents });
+        }
+        console.log('');
+        console.log(chalk_1.default.green(`✓ Project "${projectName}" scaffolded.`));
+        console.log('');
+        console.log(chalk_1.default.blue('Next steps:'));
+        if (directory) {
+            console.log(chalk_1.default.gray(`  cd ${directory}`));
+        }
+        console.log(chalk_1.default.gray(`  # Fill in WEBHOOK_SECRET and any other env vars in solidactions.yaml:`));
+        console.log(chalk_1.default.gray(`  solidactions env set ${projectName} WEBHOOK_SECRET <your-secret> -e production`));
+        console.log(chalk_1.default.gray(`  solidactions project deploy ${projectName} -e production`));
     }
     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) {
-    let host;
-    if (options.host) {
-        host = options.host;
-    }
-    else if (options.dev) {
-        host = 'http://localhost:8000';
-    }
-    else {
-        host = 'https://app.solidactions.com';
-    }
-    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}`));
-    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(),
-    };
-    (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 ${targetPath}`));
-    console.log('');
-    // Workspace selection — ensureWorkspaceSelected writes to the right file via the resolver.
-    try {
-        if (options.workspace) {
-            await (0, workspaces_1.workspaceSet)(options.workspace);
+        if (err.message?.includes('rate limit')) {
+            console.error(chalk_1.default.red(err.message));
         }
-        else {
-            await (0, api_1.ensureWorkspaceSelected)(config);
+        else if (err.message?.includes('not found')) {
+            console.error(chalk_1.default.red(err.message));
         }
-    }
-    catch {
-        console.log(chalk_1.default.yellow('Could not set workspace. Run `solidactions workspace set` later.'));
-    }
-    console.log('');
-    console.log(chalk_1.default.blue('Quick start:'));
-    console.log(chalk_1.default.gray('  solidactions project deploy <name>    Deploy current directory'));
-    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'));
-}
-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 (err.message?.includes('Failed to fetch')) {
+            console.error(chalk_1.default.red('Network error: Could not reach GitHub to fetch the template. Check your internet connection.'));
+        }
+        else {
+            console.error(chalk_1.default.red('Error:'), err.message);
         }
-    }
-    else if (options.global) {
-        targetPath = globalPath;
-    }
-    else {
-        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}).`));
-    }
-}
-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.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/login.js

@@ -0,0 +1,215 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConfig = getConfig;
+exports.saveConfig = saveConfig;
+exports.clearConfig = clearConfig;
+exports.login = login;
+exports.logout = logout;
+exports.whoami = whoami;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+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_1 = require("../utils/config");
+function getConfig() {
+    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 {
+        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)."));
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+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
+        }
+    }
+    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 login(apiKey, options) {
+    let host;
+    if (options.host) {
+        host = options.host;
+    }
+    else if (options.dev) {
+        host = 'http://localhost:8000';
+    }
+    else {
+        host = 'https://app.solidactions.com';
+    }
+    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}`));
+    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(),
+    };
+    (0, config_1.writeConfigFile)(targetPath, config);
+    if (target === 'local') {
+        await ensureGitignoreCovers(process.cwd(), !!options.gitignore);
+    }
+    console.log(chalk_1.default.green('Logged in successfully!'));
+    console.log(chalk_1.default.gray(`Configuration saved to ${targetPath}`));
+    console.log('');
+    // Workspace selection — ensureWorkspaceSelected writes to the right file via the resolver.
+    try {
+        if (options.workspace) {
+            await (0, workspaces_1.workspaceSet)(options.workspace);
+        }
+        else {
+            await (0, api_1.ensureWorkspaceSelected)(config);
+        }
+    }
+    catch {
+        console.log(chalk_1.default.yellow('Could not set workspace. Run `solidactions workspace set` later.'));
+    }
+    console.log('');
+    console.log(chalk_1.default.blue('Next step — scaffold a new project (includes AI tooling):'));
+    console.log(chalk_1.default.gray('  solidactions init <project-name>      Creates ./<project-name>/ with scaffold + AI skills'));
+    console.log(chalk_1.default.gray('  solidactions init                     Scaffolds in the current (empty) directory'));
+    console.log('');
+    console.log(chalk_1.default.blue('Quick start:'));
+    console.log(chalk_1.default.gray('  solidactions project deploy <name>    Deploy current directory'));
+    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'));
+}
+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 {
+        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}).`));
+    }
+}
+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.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/index.js

@@ -7,6 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const chalk_1 = __importDefault(require("chalk"));
 const commander_1 = require("commander");
 const deploy_1 = require("./commands/deploy");
+const login_1 = require("./commands/login");
 const init_1 = require("./commands/init");
 const pull_1 = require("./commands/pull");
 const project_list_1 = require("./commands/project-list");
@@ -61,8 +62,8 @@ program
 // Top-level commands
 // =============================================================================
 program
-    .command('init')
-    .description('Initialize the CLI with your API key')
+    .command('login')
+    .description('Authenticate the CLI with your API key')
     .argument('<api-key>', 'Your SolidActions API key')
     .option('--dev', 'Use local development server (http://localhost:8000)')
     .option('--host <url>', 'Custom API host URL')
@@ -71,7 +72,17 @@ program
     .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);
+    await (0, login_1.login)(apiKey, options);
+});
+program
+    .command('init')
+    .description('Scaffold a new SolidActions project (files + AI skills)')
+    .argument('[directory]', 'Directory to create (omit to scaffold in the current empty directory)')
+    .option('--no-skills', 'Skip AI skills/SDK reference install (scaffold files only)')
+    .option('--claude', 'Use CLAUDE.md for the AI helper file')
+    .option('--agents', 'Use AGENTS.md for the AI helper file (Codex, Cursor, Gemini, Windsurf)')
+    .action(async (directory, options) => {
+    await (0, init_1.init)(directory, options);
 });
 program
     .command('logout')
@@ -79,13 +90,13 @@ program
     .option('--local', 'Remove only the nearest local ./.solidactions/config.json')
     .option('--global', 'Remove only ~/.solidactions/config.json')
     .action((options) => {
-    (0, init_1.logout)(options);
+    (0, login_1.logout)(options);
 });
 program
     .command('whoami')
     .description('Show current configuration')
     .action(() => {
-    (0, init_1.whoami)();
+    (0, login_1.whoami)();
 });
 program
     .command('dev')
@@ -311,10 +322,9 @@ workspace
 const ai = program.command('ai').description('AI helper tools');
 ai
     .command('init')
-    .description('Install AI helper documentation (CLAUDE.md or AGENTS.md) for AI-assisted workflow development')
+    .description('Install SolidActions AI skills and SDK reference for AI-assisted 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)')
+    .option('--agents', 'Use AGENTS.md (for Codex, Cursor, Gemini, Windsurf, etc.)')
     .action((options) => { (0, ai_init_1.aiInit)(options); });
 ai
     .command('examples')

package/dist/utils/skills.js

@@ -3,9 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.detectSkillTargets = detectSkillTargets;
+exports.skillTargetDir = skillTargetDir;
 exports.installSkills = installSkills;
-exports.fetchClaudeMdContent = fetchClaudeMdContent;
+exports.fetchAiHelperContent = fetchAiHelperContent;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
@@ -19,53 +19,41 @@ 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.
+ * Resolve the skills directory for an AI helper target.
  *
- * 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.
+ * - `CLAUDE.md` → `<cwd>/.claude/skills/` (Claude Code convention)
+ * - `AGENTS.md` → `<cwd>/.agents/skills/` (Codex auto-discovers this path;
+ *   Cursor/Gemini read via AGENTS.md pointers)
  *
- * Detection rules:
- * - If `.claude/` exists in cwd → include `.claude/skills/`
- * - If neither exists → return empty (caller should prompt)
+ * The directory does not need to exist — the caller creates it.
  */
-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'));
+function skillTargetDir(targetFile, cwd = process.cwd()) {
+    if (targetFile === 'CLAUDE.md') {
+        return path_1.default.join(cwd, '.claude', 'skills');
     }
-    return targets;
+    return path_1.default.join(cwd, '.agents', 'skills');
 }
 /**
  * Fetch all SolidActions skill files from the examples repo and write
- * them into each target directory. Overwrites existing files (skills
+ * them into the target directory. Overwrites existing files (skills
  * are versioned upstream).
  */
-async function installSkills(targetDirs) {
+async function installSkills(targetDir) {
     const written = [];
-    for (const dir of targetDirs) {
-        fs_extra_1.default.ensureDirSync(dir);
-    }
+    fs_extra_1.default.ensureDirSync(targetDir);
     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);
-        }
+        const filePath = path_1.default.join(targetDir, `${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)
+ * Fetch the slim AI-helper content for the target file from the examples
+ * repo. Single source per target — no legacy fallback.
  */
-async function fetchClaudeMdContent(skillsInstalled) {
-    const file = skillsInstalled ? 'CLAUDE-skills-pointer.md' : 'CLAUDE.md';
-    return (0, github_1.fetchRawFile)(EXAMPLES_OWNER, EXAMPLES_REPO, file);
+async function fetchAiHelperContent(targetFile) {
+    return (0, github_1.fetchRawFile)(EXAMPLES_OWNER, EXAMPLES_REPO, targetFile);
 }

package/package.json

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