@seanmars/tospec 0.19.0-beta.0 → 0.19.0-beta.13

package/dist/core/init.js

@@ -1,90 +1,171 @@
-/**
- * Init Command
- *
- * Sets up tospec Agent Skills for Claude Code and Codex.
- */
+/** Sets up tospec Agent Skills for Claude Code and Codex. */
 import path from 'path';
 import * as fs from 'fs';
 import { createRequire } from 'module';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { ensureDirectoryAnchor, tospecLayoutDirs } from './project-layout.js';
-import { AI_TOOLS, TOSPEC_DIR_NAME, } from './config.js';
+import { AI_TOOLS, TOSPEC_DIR_NAME, fallbackToolIds, resolveToolSelection, } from './config.js';
 import { isInteractive } from '../utils/interactive.js';
 import { serializeConfig } from './config-prompts.js';
 import { copyDir } from '../utils/link.js';
-import { removeLegacySkillDirs, removeLegacyToolSkillLayout, getToolsWithSkillsDir, getToolStates, getSkillTemplates, writeSkillDir, writeToolCommands, writeToolRules, } from './shared/index.js';
+import { removeLegacySkillDirs, removeUnselectedSkillDirs, removeLegacyToolSkillLayout, getToolsWithSkillsDir, getToolStates, getSkillTemplates, writeSkillDir, writeToolCommands, findWorkflowReferenceGaps, describeWorkflowReferenceGaps, } from './shared/index.js';
 import { getGlobalConfig } from './global-config.js';
 import { runLegacyUserStateMigration } from './user-state-migration.js';
 import { getProfileWorkflows, ALL_WORKFLOWS } from './profiles.js';
 import { getAvailableTools } from './available-tools.js';
 import { resolveConfigFileInDir } from './project-config.js';
+import { planWorkflowRules, writeWorkflowRules } from './shared/rules-generation.js';
+import { hasResidualCodexOutput, RESIDUAL_CODEX_NOTICE, RESIDUAL_CODEX_FIX } from './codex-residue.js';
+import { emitSuccess } from '../commands/shared-output.js';
 const require = createRequire(import.meta.url);
 const { version: TOSPEC_VERSION } = require('../../package.json');
-// -----------------------------------------------------------------------------
-// Constants
-// -----------------------------------------------------------------------------
 const DEFAULT_SCHEMA = 'sdd';
-// -----------------------------------------------------------------------------
-// Init Command Class
-// -----------------------------------------------------------------------------
+/** The canonical skills directory every dependent target is copied from. */
+function agentsSkillsDirFor(projectPath) {
+    return path.join(projectPath, '.agents', 'skills');
+}
+/** The `--json` null-shape; mirrors the success payload with `init` nulled. */
+export const INIT_FAILURE_PAYLOAD = { init: null, root: null };
 export class InitCommand {
     toolsArg;
     force;
     interactiveOption;
     profileOverride;
+    json;
     constructor(options = {}) {
         this.toolsArg = options.tools;
         this.force = options.force ?? false;
         this.interactiveOption = options.interactive;
         this.profileOverride = options.profile;
+        this.json = options.json ?? false;
     }
+    /**
+     * Progress prose, suppressed under `--json`: the envelope contract allows only
+     * one document on stdout.
+     */
+    say(...args) {
+        if (!this.json)
+            console.log(...args);
+    }
+    /**
+     * Unlike `say`, a warning has no other carrier — dropping it under `--json`
+     * would leave an agent caller less informed than a human.
+     */
+    warn(code, message, fix) {
+        this.jsonWarnings.push({ severity: 'warning', code, message, ...(fix ? { fix } : {}) });
+        if (!this.json) {
+            console.log(`Warning: ${message}`);
+            if (fix)
+                console.log(fix);
+        }
+    }
+    /** Emitted alongside the success payload; empty means the key is omitted. */
+    jsonWarnings = [];
     async execute(targetPath) {
-        // Above every getGlobalConfig() below, so this run reads the migrated file
-        // rather than the legacy fallback.
-        await runLegacyUserStateMigration();
         const projectPath = path.resolve(targetPath);
         const tospecDir = TOSPEC_DIR_NAME;
         const tospecPath = path.join(projectPath, tospecDir);
-        // Validation happens silently in the background
-        const extendMode = await this.validate(projectPath, tospecPath);
-        // Detect available tools in the project (task 7.1)
+        // Detect without writing: even the permission probe must follow rule preflight.
+        const extendMode = await FileSystemUtils.directoryExists(tospecPath);
         const detectedTools = getAvailableTools(projectPath);
-        // Show animated welcome screen (interactive mode only)
         const canPrompt = this.canPromptInteractively();
         if (canPrompt) {
             const { showWelcomeScreen } = await import('../ui/welcome-screen.js');
             await showWelcomeScreen();
         }
-        // Validate profile override early so invalid values fail before tool setup.
-        // The resolved value is consumed later when generation reads effective config.
+        // Validated early so an invalid value fails before tool setup; the resolved
+        // value is read again later, when generation needs the effective config.
         this.resolveProfileOverride();
-        // Get tool states before processing
         const toolStates = getToolStates(projectPath);
-        // Get tool selection (pass detected tools for pre-selection)
         const selectedToolIds = await this.getSelectedTools(toolStates, extendMode, detectedTools, projectPath);
-        // Validate selected tools
         const validatedTools = this.validateTools(selectedToolIds, toolStates);
-        // The decision rule is always installed (only skipped when no agent dir exists).
-        const installRules = validatedTools.length > 0;
-        // Create directory structure and config
+        const rulePlan = await planWorkflowRules(projectPath, validatedTools.map((tool) => tool.value));
+        // Migration remains before every getGlobalConfig(), but after conflict checks.
+        await runLegacyUserStateMigration();
+        await this.validate(projectPath);
         await this.createDirectoryStructure(tospecPath, extendMode);
-        // Create config.yaml if needed — must run before skill/command generation.
+        // Must run before skill/command generation.
         const configStatus = await this.createConfig(tospecPath, extendMode);
-        // Generate skills and commands for each tool
-        const results = await this.generateSkillsAndCommands(projectPath, validatedTools, installRules);
-        // Display success message
+        // A profile left at `custom` with nothing picked resolves to zero workflows,
+        // so init would report both tools `created` with no skill on disk. Raised
+        // before the write, and only when a tool was asked for — "no tools selected"
+        // has its own line and is not a profile problem.
+        const initConfig = getGlobalConfig();
+        const initProfile = this.profileOverride ?? initConfig.profile ?? 'core';
+        if (validatedTools.length > 0 &&
+            getProfileWorkflows(initProfile, initConfig.workflows).length === 0) {
+            this.warn('init_profile_selects_no_workflows', `Profile '${initProfile}' selects no workflows, so this init writes no tospec skills.`, 'Run "tospec config profile core" then "tospec init" to install them.');
+        }
+        // The same check `update` runs, for the same reason: the skills about to be
+        // written name their siblings in fixed prose, so a partial selection
+        // installs instructions that point at workflows this project will not have.
+        if (validatedTools.length > 0) {
+            const referenceGaps = findWorkflowReferenceGaps(getProfileWorkflows(initProfile, initConfig.workflows));
+            if (referenceGaps.length > 0) {
+                const missing = [...new Set(referenceGaps.map((gap) => gap.missing))].sort();
+                this.warn('init_workflow_reference_missing', `Installed skills point at workflows this profile leaves out: ${describeWorkflowReferenceGaps(referenceGaps)}.`, `Add them with "tospec config set workflows" (missing: ${missing.join(', ')}), or expect agents to hit instructions they cannot follow.`);
+            }
+        }
+        const results = await this.generateSkillsAndCommands(projectPath, validatedTools);
+        const successfulIds = new Set([...results.createdTools, ...results.refreshedTools].map((tool) => tool.value));
+        await writeWorkflowRules(rulePlan.filter((entry) => successfulIds.has(entry.toolId)), {
+            silent: this.json,
+        });
         this.displaySuccessMessage(projectPath, validatedTools, results, configStatus);
+        // After every write, so a run that dies in rule preflight never leaves
+        // advice about a state it did not reach; before the JSON envelope, or the
+        // warning is recorded into a document already on stdout.
+        if (hasResidualCodexOutput(projectPath)) {
+            this.warn('codex_residue', RESIDUAL_CODEX_NOTICE, RESIDUAL_CODEX_FIX);
+        }
+        if (this.json) {
+            const globalCfg = getGlobalConfig();
+            const activeProfile = this.profileOverride ?? globalCfg.profile ?? 'core';
+            const activeWorkflows = [...getProfileWorkflows(activeProfile, globalCfg.workflows)];
+            emitSuccess({
+                init: {
+                    profile: activeProfile,
+                    workflows: activeWorkflows,
+                    created: results.createdTools.map((t) => ({ tool: t.value, dir: t.skillsDir })),
+                    refreshed: results.refreshedTools.map((t) => ({ tool: t.value, dir: t.skillsDir })),
+                    failed: results.failedTools.map((f) => ({ name: f.name, error: f.error.message })),
+                    // `created` only records that a tool was configured, so this is the
+                    // only field saying what was installed, and it must count what
+                    // reached a tool directory: `--tools none` writes nothing anywhere.
+                    skills: results.createdTools.length + results.refreshedTools.length > 0
+                        ? getSkillTemplates(activeWorkflows).length
+                        : 0,
+                    config: configStatus,
+                },
+                ...(this.jsonWarnings.length ? { status: this.jsonWarnings } : {}),
+            }, { path: projectPath, source: 'explicit' });
+        }
     }
-    // ═══════════════════════════════════════════════════════════
-    // VALIDATION & SETUP
-    // ═══════════════════════════════════════════════════════════
-    async validate(projectPath, tospecPath) {
-        const extendMode = await FileSystemUtils.directoryExists(tospecPath);
-        // Check write permissions
+    async validate(projectPath) {
         if (!(await FileSystemUtils.ensureWritePermissions(projectPath))) {
             throw new Error(`Insufficient permissions to write to ${projectPath}`);
         }
-        return extendMode;
+    }
+    /**
+     * A row can arrive uninvited by being required by another, which has to be
+     * said *before* the prompt to inform the answer. Derived from the table so a
+     * future dependency documents itself.
+     *
+     * Prompt path only: a `--tools` run has no answer to inform.
+     */
+    discloseToolDependencies() {
+        for (const tool of AI_TOOLS) {
+            if (!tool.requires?.length)
+                continue;
+            const required = tool.requires
+                .map((id) => AI_TOOLS.find((candidate) => candidate.value === id))
+                .filter((candidate) => Boolean(candidate));
+            if (required.length === 0)
+                continue;
+            const names = required.map((candidate) => candidate.name).join(', ');
+            const dirs = required.map((candidate) => `${candidate.skillsDir}/skills/`).join(', ');
+            this.say(`${tool.name} copies its skills from ${dirs}, so selecting it also selects ${names}.`);
+        }
     }
     canPromptInteractively() {
         if (this.interactiveOption === false)
@@ -102,11 +183,7 @@ export class InitCommand {
         }
         throw new Error(`Invalid profile "${this.profileOverride}". Available profiles: core, custom`);
     }
-    // ═══════════════════════════════════════════════════════════
-    // TOOL SELECTION
-    // ═══════════════════════════════════════════════════════════
     async getSelectedTools(toolStates, extendMode, detectedTools, projectPath) {
-        // Check for --tools flag first
         const nonInteractiveSelection = this.resolveToolsArg();
         if (nonInteractiveSelection !== null) {
             return nonInteractiveSelection;
@@ -118,20 +195,22 @@ export class InitCommand {
             .map(([toolId]) => toolId));
         const shouldPreselectDetected = !extendMode && configuredToolIds.size === 0;
         const canPrompt = this.canPromptInteractively();
-        // Non-interactive mode: use detected tools as fallback (task 7.8)
+        // Detecting nothing is an absence of information, not a decision to write
+        // nothing, so it falls back to the base target. (A cleared menu *is* a
+        // decision.)
         if (!canPrompt) {
-            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,codex.`);
+            const detected = [...detectedToolIds];
+            return resolveToolSelection(detected.length > 0 ? detected : fallbackToolIds());
         }
         if (validTools.length === 0) {
             throw new Error(`No tools available for skill generation.`);
         }
-        // Interactive mode: show searchable multi-select
         const { searchableMultiSelect } = await import('../prompts/searchable-multi-select.js');
-        // Build choices: pre-select configured tools; keep detected tools visible but unselected.
-        const sortedChoices = validTools
+        // Every target with an output directory is offered, including the one others
+        // copy from: what the list shows is what gets written, and a row pulled in
+        // by another comes from a disclosed expansion, not a locked checkbox.
+        const offeredTools = getToolsWithSkillsDir();
+        const sortedChoices = offeredTools
             .map((toolId) => {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
             const status = toolStates.get(toolId);
@@ -146,7 +225,7 @@ export class InitCommand {
             };
         })
             .sort((a, b) => {
-            // Configured tools first, then detected (not configured), then everything else.
+            // Configured first, then detected-but-unconfigured, then the rest.
             if (a.configured && !b.configured)
                 return -1;
             if (!a.configured && b.configured)
@@ -157,31 +236,32 @@ export class InitCommand {
                 return 1;
             return 0;
         });
-        const configuredNames = validTools
+        const configuredNames = offeredTools
             .filter((toolId) => configuredToolIds.has(toolId))
             .map((toolId) => AI_TOOLS.find((t) => t.value === toolId)?.name || toolId);
         if (configuredNames.length > 0) {
-            console.log(`tospec configured: ${configuredNames.join(', ')} (pre-selected)`);
+            this.say(`tospec configured: ${configuredNames.join(', ')} (pre-selected)`);
         }
         const detectedOnlyNames = detectedTools
-            .filter((tool) => !configuredToolIds.has(tool.value))
+            .filter((tool) => !configuredToolIds.has(tool.value) && offeredTools.includes(tool.value))
             .map((tool) => tool.name);
         if (detectedOnlyNames.length > 0) {
             const detectionLabel = shouldPreselectDetected
                 ? 'pre-selected for first-time setup'
                 : 'not pre-selected';
-            console.log(`Detected tool directories: ${detectedOnlyNames.join(', ')} (${detectionLabel})`);
+            this.say(`Detected tool directories: ${detectedOnlyNames.join(', ')} (${detectionLabel})`);
         }
+        // Last thing before the question, so the dependency is on screen while it
+        // can still change the answer.
+        this.discloseToolDependencies();
+        // No minimum: clearing every checkbox means "write no agent content", as
+        // `--tools none` does.
         const selectedTools = await searchableMultiSelect({
-            message: `Select tools to set up (${validTools.length} available)`,
+            message: `Select tools to set up (${offeredTools.length} available)`,
             pageSize: 15,
             choices: sortedChoices,
-            validate: (selected) => selected.length > 0 || 'Select at least one tool',
         });
-        if (selectedTools.length === 0) {
-            throw new Error('At least one tool must be selected');
-        }
-        return selectedTools;
+        return resolveToolSelection(selectedTools);
     }
     resolveToolsArg() {
         if (typeof this.toolsArg === 'undefined') {
@@ -196,7 +276,7 @@ export class InitCommand {
         const availableList = ['all', 'none', ...availableTools].join(', ');
         const lowerRaw = raw.toLowerCase();
         if (lowerRaw === 'all') {
-            return availableTools;
+            return resolveToolSelection(availableTools);
         }
         if (lowerRaw === 'none') {
             return [];
@@ -216,14 +296,9 @@ export class InitCommand {
         if (invalidTokens.length > 0) {
             throw new Error(`Invalid tool(s): ${invalidTokens.join(', ')}. Available values: ${availableList}`);
         }
-        // Deduplicate while preserving order
-        const deduped = [];
-        for (const token of normalizedTokens) {
-            if (!deduped.includes(token)) {
-                deduped.push(token);
-            }
-        }
-        return deduped;
+        // Expansion deduplicates and orders dependencies first, so naming a tool
+        // whose skills copy from another never produces a copy with no source.
+        return resolveToolSelection(normalizedTokens);
     }
     validateTools(toolIds, toolStates) {
         const validatedTools = [];
@@ -247,20 +322,14 @@ export class InitCommand {
         }
         return validatedTools;
     }
-    // ═══════════════════════════════════════════════════════════
-    // DIRECTORY STRUCTURE
-    // ═══════════════════════════════════════════════════════════
     /**
-     * Anchoring runs on every init, not only the first: a project that predates
-     * the rule reaches the same state by re-running the command it already runs
-     * to refresh generated files, with no separate migration step.
-     *
-     * extendMode differs only in staying quiet — the work itself is identical, so
-     * it is a pair of guards rather than a second copy of the loop.
+     * Anchoring runs on every init, not only the first, so a project predating the
+     * rule reaches the same state without a migration step. `extendMode` differs
+     * only in staying quiet.
      */
     async createDirectoryStructure(tospecPath, extendMode) {
         if (!extendMode)
-            console.log('Creating tospec structure...');
+            this.say('Creating tospec structure...');
         const layout = tospecLayoutDirs(tospecPath);
         for (const dir of [tospecPath, ...layout]) {
             await FileSystemUtils.createDirectory(dir);
@@ -269,58 +338,56 @@ export class InitCommand {
             await ensureDirectoryAnchor(dir);
         }
         if (!extendMode)
-            console.log('Created tospec structure');
+            this.say('Created tospec structure');
     }
-    // ═══════════════════════════════════════════════════════════
-    // SKILL GENERATION
-    // ═══════════════════════════════════════════════════════════
-    async generateSkillsAndCommands(projectPath, tools, installRules) {
+    async generateSkillsAndCommands(projectPath, tools) {
         const createdTools = [];
         const refreshedTools = [];
         const failedTools = [];
         let removedCommandCount = 0;
-        // Read global config for profile settings (use --profile override if set)
         const globalConfig = getGlobalConfig();
         const profile = this.resolveProfileOverride() ?? globalConfig.profile ?? 'core';
         const workflows = getProfileWorkflows(profile, globalConfig.workflows);
         const skillTemplates = getSkillTemplates(workflows);
-        // Write canonical files once to .agents/ — the single source of truth
-        // for every tool. Tool directories below get a link into these where a
-        // tool's on-disk shape allows it, or a real generated copy where it
-        // can't (see the per-tool loop's comments).
-        const agentsSkillsDir = path.join(projectPath, '.agents', 'skills');
-        for (const { template, dirName } of skillTemplates) {
-            await writeSkillDir(agentsSkillsDir, dirName, template, TOSPEC_VERSION);
+        // Canonical files, written once to .agents/. Gated on "any target at all" so
+        // `--tools none` writes nothing; dependency expansion guarantees .agents is
+        // present whenever anything else is.
+        const agentsSkillsDir = agentsSkillsDirFor(projectPath);
+        if (tools.length > 0) {
+            for (const { template, dirName } of skillTemplates) {
+                await writeSkillDir(agentsSkillsDir, dirName, template, TOSPEC_VERSION);
+            }
         }
+        // Both sweeps sit outside that gate: retiring a workflow is not conditional
+        // on this run writing anything. Gated, `--tools none` would leave a retired
+        // skill dir loadable by every agent reading .agents/skills/, and a dropped
+        // workflow would come back on the next copy from the canonical directory.
         await removeLegacySkillDirs(agentsSkillsDir);
+        await removeUnselectedSkillDirs(agentsSkillsDir, workflows);
         removedCommandCount += await this.removeLegacyCommands(projectPath);
-        // Process each tool
         for (const tool of tools) {
-            console.log(`Setting up ${tool.name}...`);
+            this.say(`Setting up ${tool.name}...`);
             try {
-                // Link (or copy) each skill dir from .agents/skills/ into the tool's
-                // standard `skills/` dir. Project-scope skills can't live in a nested
-                // sub-folder, so skills stay flat and prefixed:
-                // `<tool>/skills/tospec-<workflow>/SKILL.md`. Clean up the intermediate
-                // grouped/bare layouts (and the retired verify skill) from older builds first.
+                // Project-scope skills cannot live in a nested sub-folder, so they stay
+                // flat and prefixed: `<tool>/skills/tospec-<workflow>/SKILL.md`.
                 const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');
                 await removeLegacyToolSkillLayout(path.join(projectPath, tool.skillsDir));
                 await removeLegacySkillDirs(skillsDir);
-                // Every tool gets a plain copy of each skill dir; copies don't track
-                // .agents/ edits — `tospec update` regenerates them.
-                for (const { dirName } of skillTemplates) {
-                    const src = path.join(agentsSkillsDir, dirName);
-                    const dest = path.join(skillsDir, dirName);
-                    await copyDir(src, dest);
+                // Independent copies, not links: see the header of utils/link.ts.
+                // copyDir clears its dest, so copying .agents/skills onto itself would
+                // delete the source.
+                if (path.resolve(skillsDir) !== path.resolve(agentsSkillsDir)) {
+                    for (const { dirName } of skillTemplates) {
+                        await copyDir(path.join(agentsSkillsDir, dirName), path.join(skillsDir, dirName));
+                    }
                 }
-                // Commands: for tools with a registered adapter (Claude Code), write
-                // `.claude/commands/tosx/<id>.md` so they can be invoked as `/tosx:<id>`.
+                // Per-tool prune. The canonical sweep above cannot reach a copy that a
+                // previous, wider profile left in this tool's directory.
+                await removeUnselectedSkillDirs(skillsDir, workflows);
+                // Tools with a registered adapter (Claude Code) get
+                // `.claude/commands/tosx/<id>.md`, invokable as `/tosx:<id>`.
                 await writeToolCommands(projectPath, tool.value, workflows);
-                // Rules: opt-in static guidance under `<tool>/rules/tospec/`.
-                if (installRules) {
-                    await writeToolRules(projectPath, tool.skillsDir);
-                }
-                console.log(`Setup complete for ${tool.name}`);
+                this.say(`Setup complete for ${tool.name}`);
                 if (tool.wasConfigured) {
                     refreshedTools.push(tool);
                 }
@@ -329,7 +396,7 @@ export class InitCommand {
                 }
             }
             catch (error) {
-                console.log(`Failed for ${tool.name}`);
+                this.say(`Failed for ${tool.name}`);
                 failedTools.push({ name: tool.name, error: error });
             }
         }
@@ -340,9 +407,6 @@ export class InitCommand {
             removedCommandCount,
         };
     }
-    // ═══════════════════════════════════════════════════════════
-    // CONFIG FILE
-    // ═══════════════════════════════════════════════════════════
     async createConfig(tospecPath, extendMode) {
         const configPath = path.join(tospecPath, 'config.yaml');
         if (resolveConfigFileInDir(tospecPath)) {
@@ -357,82 +421,86 @@ export class InitCommand {
             return 'skipped';
         }
     }
-    // ═══════════════════════════════════════════════════════════
-    // UI & OUTPUT
-    // ═══════════════════════════════════════════════════════════
     displaySuccessMessage(projectPath, tools, results, configStatus) {
-        console.log();
-        console.log('tospec Setup Complete');
-        console.log();
-        // Show created vs refreshed tools
+        const globalConfig = getGlobalConfig();
+        const activeProfile = this.profileOverride ?? globalConfig.profile ?? 'core';
+        const activeWorkflows = [...getProfileWorkflows(activeProfile, globalConfig.workflows)];
+        this.say();
+        this.say('tospec Setup Complete');
+        this.say();
         if (results.createdTools.length > 0) {
-            console.log(`Created: ${results.createdTools.map((t) => t.name).join(', ')}`);
+            this.say(`Created: ${results.createdTools.map((t) => t.name).join(', ')}`);
         }
         if (results.refreshedTools.length > 0) {
-            console.log(`Refreshed: ${results.refreshedTools.map((t) => t.name).join(', ')}`);
+            this.say(`Refreshed: ${results.refreshedTools.map((t) => t.name).join(', ')}`);
+        }
+        // Every block below is keyed off a non-empty selection, so an empty one
+        // needs its own line saying no skills exist.
+        if (tools.length === 0) {
+            this.say('No tools selected: no skills, commands or rules were written.');
         }
-        // Show counts (respecting profile filter)
         const successfulTools = [...results.createdTools, ...results.refreshedTools];
         if (successfulTools.length > 0) {
-            const globalConfig = getGlobalConfig();
-            const profile = this.profileOverride ?? globalConfig.profile ?? 'core';
-            const workflows = getProfileWorkflows(profile, globalConfig.workflows);
-            const toolDirs = [...new Set(successfulTools.map((t) => t.skillsDir))].join(', ');
-            const skillCount = getSkillTemplates(workflows).length;
-            console.log(`${skillCount} skills in ${toolDirs}/`);
-        }
-        // Show failures
+            // Trailing slash per directory, not once at the end: with more than one
+            // target ".agents, .claude/" reads as a single odd path.
+            const toolDirs = [...new Set(successfulTools.map((t) => `${t.skillsDir}/`))].join(', ');
+            const skillCount = getSkillTemplates(activeWorkflows).length;
+            this.say(`${skillCount} skills in ${toolDirs}`);
+            // Dependent targets hold independent copies, so an edit to the canonical
+            // skill does not reach them. Only when something was copied: under an
+            // empty profile this would claim a copy from a directory holding none.
+            const dependents = successfulTools.filter((t) => path.resolve(projectPath, t.skillsDir, 'skills') !== path.resolve(agentsSkillsDirFor(projectPath)));
+            if (skillCount > 0 && dependents.length > 0) {
+                this.say(`Copied from .agents/skills/: ${dependents.map((t) => t.name).join(', ')} — rerun 'tospec update' after editing the canonical skills`);
+            }
+        }
         if (results.failedTools.length > 0) {
-            console.log(`Failed: ${results.failedTools.map((f) => `${f.name} (${f.error.message})`).join(', ')}`);
+            this.say(`Failed: ${results.failedTools.map((f) => `${f.name} (${f.error.message})`).join(', ')}`);
         }
         if (results.removedCommandCount > 0) {
-            console.log(`Removed: ${results.removedCommandCount} legacy command entries`);
+            this.say(`Removed: ${results.removedCommandCount} legacy command entries`);
         }
-        // Config status
         if (configStatus === 'created') {
-            console.log(`Config: tospec/config.yaml (schema: ${DEFAULT_SCHEMA})`);
+            this.say(`Config: tospec/config.yaml (schema: ${DEFAULT_SCHEMA})`);
         }
         else if (configStatus === 'exists') {
-            // Show actual filename (config.yaml or config.yml)
+            // Name the file that is actually there: config.yaml or config.yml.
             const configFile = resolveConfigFileInDir(path.join(projectPath, TOSPEC_DIR_NAME));
             const configName = configFile ? path.basename(configFile) : 'config.yaml';
-            console.log(`Config: tospec/${configName} (exists)`);
+            this.say(`Config: tospec/${configName} (exists)`);
         }
         else {
-            console.log(`Config: skipped (non-interactive mode)`);
+            this.say(`Config: skipped (non-interactive mode)`);
+        }
+        this.say();
+        if (tools.length === 0) {
+            // `tospec-propose` is a skill and this run wrote none, so advising it
+            // would name something not on disk.
+            this.say('Getting started:');
+            this.say("  Add agent skills: tospec init --tools <tool>  (or rerun 'tospec init')");
         }
-        // Getting started (task 7.6: show propose if in profile)
-        const globalCfg = getGlobalConfig();
-        const activeProfile = this.profileOverride ?? globalCfg.profile ?? 'core';
-        const activeWorkflows = [...getProfileWorkflows(activeProfile, globalCfg.workflows)];
-        console.log();
-        if (activeWorkflows.includes('propose')) {
-            console.log('Getting started:');
-            console.log('  Start your first change: tospec-propose "your idea"');
+        else if (activeWorkflows.includes('propose')) {
+            this.say('Getting started:');
+            this.say('  Start your first change: tospec-propose "your idea"');
         }
         else {
-            console.log("Done. Run 'tospec config profile' to configure your workflows.");
+            this.say("Done. Run 'tospec config profile' to configure your workflows.");
         }
-        // Links
-        console.log();
-        console.log(`Documentation: README.md`);
-        // Restart instruction if any tools were configured
         if (results.createdTools.length > 0 || results.refreshedTools.length > 0) {
-            console.log();
-            console.log('Restart your agent for skills to take effect.');
+            this.say();
+            this.say('Restart your agent for skills to take effect.');
         }
-        console.log();
+        this.say();
     }
     async removeLegacyCommands(projectPath) {
         let removed = 0;
-        // Commands now live under `.claude/commands/tosx/` (managed by
-        // writeToolCommands). These are unused/legacy command locations — including
-        // the old `.claude/commands/tospec/` namespace this replaced.
+        // Commands live under `.claude/commands/tosx/` now (writeToolCommands);
+        // these are the locations it replaced.
         const legacyPaths = [
             path.join(projectPath, '.agents', 'commands', 'tospec'),
             path.join(projectPath, '.claude', 'commands', 'tospec'),
-            // Cursor support was removed; this cleanup stays so existing users'
-            // stale .cursor command files still get swept away on init/update.
+            // Cursor support was removed; this stays so stale .cursor command files
+            // are still swept away.
             ...ALL_WORKFLOWS.map((workflow) => path.join(projectPath, '.cursor', 'commands', `tospec-${workflow}.md`)),
         ];
         for (const legacyPath of legacyPaths) {