@solidactions/cli 1.23.0 → 1.24.0

package/README.md

@@ -44,6 +44,8 @@ You can mix: e.g., set only `SOLIDACTIONS_WORKSPACE_ID` in the environment while
 
 In interactive shells, `login` without `--local`/`--global` prompts for a location. In non-interactive contexts, one of the flags is required.
 
+If the target config file already exists and its contents would change, `login` writes a timestamped backup (e.g. `config.json.bak-2026-07-05T12-30-00Z`) alongside it before overwriting, and prints the backup path. Non-interactive runs proceed automatically (with the backup); an interactive TTY additionally asks a y/N confirmation first.
+
 ### `solidactions logout` flags
 
 - `--local` — remove only the nearest local config (walks up from cwd).

package/dist/commands/ai-init.js

@@ -3,6 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.NON_TTY_DEFAULT_NOTICE = void 0;
+exports.resolveAiHelperTarget = resolveAiHelperTarget;
 exports.aiInit = aiInit;
 const fs_1 = __importDefault(require("fs"));
 const chalk_1 = __importDefault(require("chalk"));
@@ -12,36 +14,49 @@ 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.
-        let targetFile;
-        if (options.claude && options.agents) {
-            console.error(chalk_1.default.red('Please specify only one of --claude or --agents'));
-            process.exit(1);
-        }
-        if (options.claude) {
-            targetFile = 'CLAUDE.md';
-        }
-        else if (options.agents) {
-            targetFile = 'AGENTS.md';
-        }
-        else {
-            const response = await (0, prompts_1.default)({
-                type: 'select',
-                name: 'file',
-                message: 'Which AI helper file?',
-                choices: [
-                    { title: 'CLAUDE.md (Claude Code)', value: 'CLAUDE.md' },
-                    { title: 'AGENTS.md (Codex, Cursor, Gemini, etc.)', value: 'AGENTS.md' },
-                ],
-            });
-            if (!response.file) {
-                console.log(chalk_1.default.yellow('Cancelled.'));
-                process.exit(0);
-            }
-            targetFile = response.file;
+exports.NON_TTY_DEFAULT_NOTICE = 'No --claude/--agents given and non-interactive — defaulting to CLAUDE.md; pass --agents for Codex/Cursor/Gemini.';
+/**
+ * Resolve which AI-helper file (CLAUDE.md vs AGENTS.md) to target, WITHOUT
+ * touching the filesystem or network. Callers that also scaffold template
+ * files (e.g. `init`) must call this BEFORE writing anything, so a shell
+ * that can't answer the interactive prompt never leaves a half-scaffolded
+ * project — see the `init` half-scaffold bug this closes.
+ */
+async function resolveAiHelperTarget(options = {}) {
+    if (options.claude && options.agents) {
+        console.error(chalk_1.default.red('Please specify only one of --claude or --agents'));
+        process.exit(1);
+    }
+    if (options.claude) {
+        return 'CLAUDE.md';
+    }
+    if (options.agents) {
+        return 'AGENTS.md';
+    }
+    if (process.stdin.isTTY) {
+        const response = await (0, prompts_1.default)({
+            type: 'select',
+            name: 'file',
+            message: 'Which AI helper file?',
+            choices: [
+                { title: 'CLAUDE.md (Claude Code)', value: 'CLAUDE.md' },
+                { title: 'AGENTS.md (Codex, Cursor, Gemini, etc.)', value: 'AGENTS.md' },
+            ],
+        });
+        if (!response.file) {
+            console.log(chalk_1.default.yellow('Cancelled.'));
+            process.exit(0);
         }
+        return response.file;
+    }
+    // Non-TTY (CI, pipes, an AI agent's non-interactive shell) with no flag:
+    // never block on an unanswerable prompt — default instead.
+    console.log(chalk_1.default.yellow(exports.NON_TTY_DEFAULT_NOTICE));
+    return 'CLAUDE.md';
+}
+async function aiInit(options = {}, resolvedTarget) {
+    try {
+        const targetFile = resolvedTarget ?? await resolveAiHelperTarget(options);
         console.log(chalk_1.default.blue('Fetching AI helper content...'));
         // Fetch slim helper content for the chosen target.
         const aiContent = await (0, skills_1.fetchAiHelperContent)(targetFile);

package/dist/commands/deploy.js

@@ -400,7 +400,7 @@ async function deploy(projectName, sourcePath, options = {}) {
                     if (status === 'deployed') {
                         clearInterval(poll);
                         console.log(chalk_1.default.green(`\n✓ Deployed to ${projectSlug}${envLabel}!`));
-                        // Always sync YAML declarations (registers env vars and their mappings)
+                        // Always sync YAML declarations (registers variables and their mappings)
                         if (yamlConfig) {
                             await pushYamlDeclarations(config, projectSlug, yamlConfig);
                         }

package/dist/commands/dev.js

@@ -270,10 +270,13 @@ async function runDev(opts) {
     // 3. Build ctx.vars from platform vars. A declared mapping is only readable
     //    on ctx.vars when it is an OAuth connection (with proxy fields) OR has a
     //    non-null resolved_value. Mappings with no value in this env are DROPPED
-    //    — and must NOT be counted in the summary (BUG #1).
+    //    — and must NOT be counted in the summary (BUG #1). A dropped SECRET is
+    //    reported separately (it's genuinely unavailable to local dev, not
+    //    merely "unset" — the platform never resolves secret values to the CLI).
     const vars = {};
     let connectionCount = 0;
     let droppedCount = 0;
+    let droppedSecretCount = 0;
     for (const pv of platformVars) {
         if (pv.source_type === 'oauth_connection' && pv.proxy_url && pv.proxy_token && pv.connection_key) {
             vars[pv.env_name] = {
@@ -286,6 +289,9 @@ async function runDev(opts) {
         else if (pv.resolved_value != null) {
             vars[pv.env_name] = pv.resolved_value;
         }
+        else if (pv.is_secret) {
+            droppedSecretCount++;
+        }
         else {
             droppedCount++;
         }
@@ -308,6 +314,9 @@ async function runDev(opts) {
         if (droppedCount > 0) {
             summary += ` (${droppedCount} declared ${droppedCount === 1 ? 'var' : 'vars'} had no value in this env and ${droppedCount === 1 ? 'was' : 'were'} skipped)`;
         }
+        if (droppedSecretCount > 0) {
+            summary += ` (${droppedSecretCount} secret ${droppedSecretCount === 1 ? 'var is' : 'vars are'} not available to local dev — set a test value in your dev environment with \`solidactions env set\`, or pass values via \`-i\`.)`;
+        }
         out(summary);
     }
     else {
@@ -326,7 +335,21 @@ async function runDev(opts) {
     const entryPath = path_1.default.resolve(opts.entry);
     const _require = (0, module_1.createRequire)(entryPath);
     // Resolve via the installed (or linked) @solidactions/sdk package.
-    const sdkTestingMain = _require.resolve('@solidactions/sdk/testing');
+    let sdkTestingMain;
+    try {
+        sdkTestingMain = _require.resolve('@solidactions/sdk/testing');
+    }
+    catch (e) {
+        if (e.code === 'MODULE_NOT_FOUND') {
+            err('Dependencies not installed — run `npm install` in the project directory first.');
+            return {
+                stdout: stdoutLines.join('\n'),
+                stderr: stderrLines.join('\n'),
+                result: { status: 'failed', error: e, phase: 'setup' },
+            };
+        }
+        throw e;
+    }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const { createMockServer } = _require(sdkTestingMain);
     const mockServer = await createMockServer();

package/dist/commands/docs-push.js

@@ -154,7 +154,7 @@ async function docsPushWithConfig(dir, options, config) {
             mcpResult = await (0, mcp_1.callDocsTool)(config, 'docs_vault', callArgs);
         }
         catch (e) {
-            process.stderr.write(chalk_1.default.red(`error: MCP request failed — ${e.message}\n`));
+            process.stderr.write(chalk_1.default.red(`error: ${e.message}\n`));
             process.exit(1);
         }
         if (!mcpResult.ok) {

package/dist/commands/env-delete.js

@@ -14,18 +14,20 @@ async function envDelete(keyOrProject, keyIfProject, options = {}) {
     const isProjectMode = keyIfProject !== undefined;
     const projectName = isProjectMode ? keyOrProject : undefined;
     const key = isProjectMode ? keyIfProject : keyOrProject;
+    const environment = options.env ?? 'dev';
+    const projectSlug = projectName && environment === 'production' ? projectName : `${projectName}-${environment}`;
     try {
         if (isProjectMode) {
-            // Delete project variable mapping
-            console.log(chalk_1.default.blue(`Deleting variable mapping "${key}" from project "${projectName}"...`));
-            // First, get the mapping to find its ID
-            const listResponse = await axios_1.default.get(`${config.host}/api/v1/projects/${projectName}/variable-mappings`, {
+            // Delete project variable
+            console.log(chalk_1.default.blue(`Deleting variable "${key}" from project "${projectName}" (${environment})...`));
+            // First, get the variable to find its ID
+            const listResponse = await axios_1.default.get(`${config.host}/api/v1/projects/${projectSlug}/variable-mappings`, {
                 headers: (0, api_1.getApiHeaders)(config),
             });
             const mappings = listResponse.data || [];
             const mapping = mappings.find((m) => m.env_name === key);
             if (!mapping) {
-                console.error(chalk_1.default.red(`Variable mapping "${key}" not found in project "${projectName}".`));
+                console.error(chalk_1.default.red(`Variable "${key}" not found in project "${projectName}" (${environment}).`));
                 process.exit(1);
             }
             // Confirm deletion unless --yes flag is provided
@@ -35,7 +37,7 @@ async function envDelete(keyOrProject, keyIfProject, options = {}) {
                     name: 'confirm',
                     message: mapping.is_yaml_declared
                         ? `Clear YAML-declared variable "${key}"? (The mapping will be preserved but value cleared)`
-                        : `Delete variable mapping "${key}" from project "${projectName}"?`,
+                        : `Delete variable "${key}" from project "${projectName}" (${environment})?`,
                     initial: false,
                 });
                 if (!response.confirm) {
@@ -44,14 +46,14 @@ async function envDelete(keyOrProject, keyIfProject, options = {}) {
                 }
             }
             // Delete the mapping
-            await axios_1.default.delete(`${config.host}/api/v1/projects/${projectName}/variable-mappings/${mapping.id}`, {
+            await axios_1.default.delete(`${config.host}/api/v1/projects/${projectSlug}/variable-mappings/${mapping.id}`, {
                 headers: (0, api_1.getApiHeaders)(config),
             });
             if (mapping.is_yaml_declared) {
-                console.log(chalk_1.default.green(`Variable mapping "${key}" cleared successfully.`));
+                console.log(chalk_1.default.green(`Variable "${key}" cleared successfully.`));
             }
             else {
-                console.log(chalk_1.default.green(`Variable mapping "${key}" deleted successfully.`));
+                console.log(chalk_1.default.green(`Variable "${key}" deleted successfully.`));
             }
         }
         else {
@@ -93,7 +95,13 @@ async function envDelete(keyOrProject, keyIfProject, options = {}) {
                 console.error(chalk_1.default.red('Authentication failed. Run "solidactions login <api-key>" to re-configure.'));
             }
             else if (error.response.status === 404) {
-                console.error(chalk_1.default.red(isProjectMode ? `Project "${projectName}" not found.` : `Variable "${key}" not found.`));
+                if (isProjectMode) {
+                    const envsList = await (0, api_1.describeProjectEnvironments)(config, projectName);
+                    console.error(chalk_1.default.red(`Project "${projectName}" has no ${environment} environment${envsList ? ` (exists in: ${envsList})` : ''}.`));
+                }
+                else {
+                    console.error(chalk_1.default.red(`Variable "${key}" not found.`));
+                }
             }
             else {
                 console.error(chalk_1.default.red(`Failed: ${error.response.status}`), error.response.data);

package/dist/commands/env-list.js

@@ -7,6 +7,7 @@ exports.envList = envList;
 const axios_1 = __importDefault(require("axios"));
 const chalk_1 = __importDefault(require("chalk"));
 const api_1 = require("../utils/api");
+const table_1 = require("../utils/table");
 /**
  * Format a value for display, with inherited badge if applicable.
  */
@@ -28,73 +29,77 @@ function formatEnvValue(value, source, isSecret) {
 }
 async function envList(projectName, options = {}) {
     const config = await (0, api_1.requireConfigWithWorkspace)();
+    const environment = options.env || 'dev';
     try {
         if (projectName) {
             // List project variable mappings
-            const environment = options.env || 'dev';
             const projectSlug = environment === 'production'
                 ? projectName
                 : `${projectName}-${environment}`;
-            console.log(chalk_1.default.blue(`Environment variables for project "${projectName}" (${environment}):`));
+            if (!options.json) {
+                console.log(chalk_1.default.blue(`Variables for project "${projectName}" (${environment}):`));
+            }
             const response = await axios_1.default.get(`${config.host}/api/v1/projects/${projectSlug}/variable-mappings`, {
                 headers: (0, api_1.getApiHeaders)(config),
             });
             const mappings = response.data || [];
+            if (options.json) {
+                console.log(JSON.stringify(mappings, null, 2));
+                return;
+            }
             if (mappings.length === 0) {
                 console.log(chalk_1.default.gray('No variable mappings found.'));
                 return;
             }
             console.log('');
-            console.log(chalk_1.default.gray('KEY'.padEnd(28) + 'VALUE'.padEnd(24) + 'TYPE'.padEnd(14) + 'SOURCE'));
-            console.log(chalk_1.default.gray('-'.repeat(90)));
-            for (const mapping of mappings) {
+            const rows = mappings.map((mapping) => {
                 const key = mapping.env_name || '?';
                 // Value display (resolved_value includes global/oauth resolution)
                 const rawValue = mapping.resolved_value ?? mapping.value;
-                let value;
-                if (mapping.is_secret) {
-                    value = chalk_1.default.yellow('••••••');
-                }
-                else if (rawValue) {
-                    value = rawValue.toString().substring(0, 22);
-                }
-                else {
-                    value = chalk_1.default.gray('-');
-                }
+                const value = mapping.is_secret ? '••••••' : rawValue ? rawValue.toString() : '-';
                 // Type & source (mirrors UI getMappingType)
                 let type;
                 let source;
                 if (mapping.source_type === 'oauth_connection' && mapping.oauth_connection_id) {
-                    type = chalk_1.default.blue('oauth');
-                    source = chalk_1.default.blue(mapping.oauth_connection_name || 'OAuth');
+                    type = 'oauth';
+                    source = mapping.oauth_connection_name || 'OAuth';
                 }
                 else if (mapping.global_variable_key) {
-                    type = chalk_1.default.green('global');
-                    source = chalk_1.default.green(mapping.global_variable_key);
+                    type = 'global';
+                    source = mapping.global_variable_key;
                 }
                 else if (mapping.has_value) {
-                    type = chalk_1.default.gray('project var');
-                    source = chalk_1.default.gray('local');
+                    type = 'project var';
+                    source = 'local';
                 }
                 else {
-                    type = chalk_1.default.gray('-');
-                    source = chalk_1.default.gray('-');
+                    type = '-';
+                    source = '-';
                 }
-                console.log(key.padEnd(28) +
-                    value.padEnd(24) +
-                    type.padEnd(14) +
-                    source);
+                return [key, value, type, source];
+            });
+            const lines = (0, table_1.renderTable)(['KEY', 'VALUE', 'TYPE', 'SOURCE'], rows, { minWidths: [28, 24, 14, 0] });
+            console.log(chalk_1.default.gray(lines[0]));
+            console.log(chalk_1.default.gray(lines[1]));
+            for (const line of lines.slice(2)) {
+                console.log(line);
             }
             console.log('');
             console.log(chalk_1.default.gray(`${mappings.length} variable(s)`));
         }
         else {
             // List global variables with per-environment values
-            console.log(chalk_1.default.blue('Global environment variables:'));
+            if (!options.json) {
+                console.log(chalk_1.default.blue('Global variables:'));
+            }
             const response = await axios_1.default.get(`${config.host}/api/v1/variables`, {
                 headers: (0, api_1.getApiHeaders)(config),
             });
             const variables = response.data?.data || [];
+            if (options.json) {
+                console.log(JSON.stringify(variables, null, 2));
+                return;
+            }
             if (variables.length === 0) {
                 console.log(chalk_1.default.gray('No global variables found.'));
                 return;
@@ -185,7 +190,13 @@ async function envList(projectName, options = {}) {
                 console.error(chalk_1.default.red('Authentication failed. Run "solidactions login <api-key>" to re-configure.'));
             }
             else if (error.response.status === 404) {
-                console.error(chalk_1.default.red(projectName ? `Project "${projectName}" not found for the specified environment.` : 'Resource not found.'));
+                if (projectName) {
+                    const envsList = await (0, api_1.describeProjectEnvironments)(config, projectName);
+                    console.error(chalk_1.default.red(`Project "${projectName}" has no ${environment} environment${envsList ? ` (exists in: ${envsList})` : ''}.`));
+                }
+                else {
+                    console.error(chalk_1.default.red('Resource not found.'));
+                }
             }
             else {
                 console.error(chalk_1.default.red(`Failed: ${error.response.status}`), error.response.data);

package/dist/commands/env-pull.js

@@ -35,7 +35,7 @@ async function envPull(projectName, options = {}) {
     // Determine output file
     const outputFile = options.output || (environment === 'production' ? '.env' : `.env.${environment}`);
     const outputPath = path_1.default.resolve(outputFile);
-    console.log(chalk_1.default.blue(`Pulling environment variables from "${projectName}" (${environment})...`));
+    console.log(chalk_1.default.blue(`Pulling variables from "${projectName}" (${environment})...`));
     try {
         // First, check if there are any secrets
         const checkResponse = await axios_1.default.get(`${config.host}/api/v1/projects/${projectSlug}/variable-mappings?resolve_oauth=true`, {
@@ -43,7 +43,7 @@ async function envPull(projectName, options = {}) {
         });
         const mappings = checkResponse.data || [];
         if (mappings.length === 0) {
-            console.log(chalk_1.default.yellow('No environment variables found for this project.'));
+            console.log(chalk_1.default.yellow('No variables found for this project.'));
             process.exit(0);
         }
         // Check for secrets (skip confirmation for --update-oauth since OAuth tokens are always secrets)
@@ -68,7 +68,7 @@ async function envPull(projectName, options = {}) {
                 console.log(chalk_1.default.yellow('No OAuth variables found for this project.'));
                 process.exit(0);
             }
-            // Build OAuth env var names set and their formatted lines
+            // Build OAuth variable names set and their formatted lines
             const oauthKeySet = new Set(oauthVars.map((v) => v.env_name));
             const oauthLines = [];
             for (const variable of oauthVars) {
@@ -146,7 +146,9 @@ async function envPull(projectName, options = {}) {
         }
         // Full pull: Build .env file content
         const lines = [];
-        lines.push(`# Environment variables for ${projectName} (${environment})`);
+        lines.push(`# Variables pulled from SolidActions for ${projectName} / ${environment}.`);
+        lines.push('# NOTE: this .env is NOT read by `solidactions dev`. Local dev vars come from');
+        lines.push('# the platform (dev fetches them with `-e <env>`); pass ad-hoc values with `-i`.');
         lines.push(`# Generated by solidactions env pull on ${new Date().toISOString()}`);
         lines.push('');
         let count = 0;

package/dist/commands/env-push.js

@@ -37,7 +37,7 @@ async function envPush(projectName, sourcePath, options = {}) {
     const envFilePath = path_1.default.join(sourceDir, envFileName);
     if (!fs_1.default.existsSync(envFilePath)) {
         console.error(chalk_1.default.red(`${envFileName} not found in ${sourceDir}`));
-        console.log(chalk_1.default.gray(`Create ${envFileName} with your environment variables, or use a different --env.`));
+        console.log(chalk_1.default.gray(`Create ${envFileName} with your variables, or use a different --env.`));
         process.exit(1);
     }
     // Parse the .env file
@@ -53,7 +53,7 @@ async function envPush(projectName, sourcePath, options = {}) {
     }
     else {
         if (declaredVars.size === 0) {
-            console.log(chalk_1.default.yellow('No environment variables declared in solidactions.yaml.'));
+            console.log(chalk_1.default.yellow('No variables declared in solidactions.yaml.'));
             console.log(chalk_1.default.gray('Use --include-undeclared to push all vars from the .env file.'));
             process.exit(0);
         }
@@ -85,7 +85,7 @@ async function envPush(projectName, sourcePath, options = {}) {
     const projectSlug = environment === 'production'
         ? projectName
         : `${projectName}-${environment}`;
-    console.log(chalk_1.default.blue(`Pushing env vars to "${projectName}" (${environment})...`));
+    console.log(chalk_1.default.blue(`Pushing variables to "${projectName}" (${environment})...`));
     // Fetch current server state
     let serverMappings = [];
     try {
@@ -200,7 +200,7 @@ async function envPush(projectName, sourcePath, options = {}) {
         console.log(chalk_1.default.gray(`  ${created} created, ${updated} updated` + (toSkip.length > 0 ? `, ${toSkip.length} skipped` : '')));
     }
     catch (error) {
-        console.error(chalk_1.default.red('Failed to push environment variables:'), error.response?.data?.message || error.message);
+        console.error(chalk_1.default.red('Failed to push variables:'), error.response?.data?.message || error.message);
         process.exit(1);
     }
 }

package/dist/commands/env-set.js

@@ -49,6 +49,10 @@ async function envSet(keyOrProject, valueOrKey, valueIfProject, options = {}) {
         const projectName = keyOrProject;
         const key = valueOrKey;
         const value = valueIfProject;
+        if (!(0, env_1.isValidEnvName)(key)) {
+            console.error(chalk_1.default.red((0, env_1.envNameError)(key)));
+            process.exit(1);
+        }
         if ((0, env_1.isReservedEnvName)(key)) {
             console.error(chalk_1.default.red((0, env_1.reservedEnvNameError)(key)));
             process.exit(1);
@@ -105,10 +109,11 @@ async function envSet(keyOrProject, valueOrKey, valueIfProject, options = {}) {
                     console.error(chalk_1.default.red('Authentication failed. Run "solidactions login <api-key>" to re-configure.'));
                 }
                 else if (error.response.status === 404) {
-                    console.error(chalk_1.default.red(`Project "${projectSlug}" not found.`));
+                    const envsList = await (0, api_1.describeProjectEnvironments)(config, projectName);
+                    console.error(chalk_1.default.red(`Project "${projectName}" has no ${environment} environment${envsList ? ` (exists in: ${envsList})` : ''}.`));
                 }
                 else if (error.response.status === 422) {
-                    console.error(chalk_1.default.red('Validation error:'), error.response.data);
+                    console.error(chalk_1.default.red((0, api_1.formatValidationError)(error.response.data)));
                 }
                 else {
                     console.error(chalk_1.default.red(`Failed: ${error.response.status}`), error.response.data);
@@ -124,6 +129,10 @@ async function envSet(keyOrProject, valueOrKey, valueIfProject, options = {}) {
         // Global mode: solidactions env set <key> <value>
         const key = keyOrProject;
         const value = valueOrKey;
+        if (!(0, env_1.isValidEnvName)(key)) {
+            console.error(chalk_1.default.red((0, env_1.envNameError)(key)));
+            process.exit(1);
+        }
         if ((0, env_1.isReservedEnvName)(key)) {
             console.error(chalk_1.default.red((0, env_1.reservedEnvNameError)(key)));
             process.exit(1);
@@ -218,7 +227,7 @@ async function envSet(keyOrProject, valueOrKey, valueIfProject, options = {}) {
                     console.error(chalk_1.default.red('Authentication failed. Run "solidactions login <api-key>" to re-configure.'));
                 }
                 else if (error.response.status === 422) {
-                    console.error(chalk_1.default.red('Validation error:'), error.response.data.message || error.response.data.errors);
+                    console.error(chalk_1.default.red((0, api_1.formatValidationError)(error.response.data)));
                 }
                 else {
                     console.error(chalk_1.default.red(`Failed: ${error.response.status}`), error.response.data);

package/dist/commands/init.js

@@ -49,6 +49,22 @@ async function init(directory, options = {}) {
             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);
         }
+        // Validate flags BEFORE any network fetch/write — previously this check
+        // lived only inside aiInit(), which runs after the template files are
+        // already fetched and written.
+        if (installSkills && options.claude && options.agents) {
+            console.error(chalk_1.default.red('Please specify only one of --claude or --agents'));
+            process.exit(1);
+        }
+        // Resolve the AI-helper target (CLAUDE.md vs AGENTS.md) UP FRONT, before
+        // writing any template file. Previously this decision was made inside
+        // aiInit(), AFTER the scaffold was already written — in a non-TTY shell
+        // with no --claude/--agents flag, the resulting unanswerable prompt left
+        // a half-scaffolded project (no CLAUDE.md/AGENTS.md, no .claude/skills/).
+        let aiHelperTarget;
+        if (installSkills) {
+            aiHelperTarget = await (0, ai_init_1.resolveAiHelperTarget)({ claude: options.claude, agents: options.agents });
+        }
         console.log(chalk_1.default.blue(`Scaffolding "${projectName}" in ${targetDir}...`));
         for (const [remoteSuffix, localSuffix] of exports.TEMPLATE_FILES) {
             const remotePath = `${TEMPLATE_PREFIX}/${remoteSuffix}`;
@@ -62,7 +78,7 @@ async function init(directory, options = {}) {
         if (installSkills) {
             console.log('');
             process.chdir(targetDir);
-            await (0, ai_init_1.aiInit)({ claude: options.claude, agents: options.agents });
+            await (0, ai_init_1.aiInit)({ claude: options.claude, agents: options.agents }, aiHelperTarget);
         }
         console.log('');
         console.log(chalk_1.default.green(`✓ Project "${projectName}" scaffolded.`));
@@ -71,6 +87,7 @@ async function init(directory, options = {}) {
         if (directory) {
             console.log(chalk_1.default.gray(`  cd ${directory}`));
         }
+        console.log(chalk_1.default.gray('  npm install'));
         console.log(chalk_1.default.gray(`  solidactions project deploy ${projectName} -e production`));
         console.log(chalk_1.default.gray(`  # If your workflow uses a webhook, retrieve its auto-generated secret`));
         console.log(chalk_1.default.gray(`  # and set that value in your sender (e.g. Telegram secret_token):`));