@seanmars/tospec 0.19.0-beta.7 → 0.20.0

package/dist/core/init.js

@@ -1,8 +1,4 @@
-/**
- * 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';
@@ -12,109 +8,150 @@ import { AI_TOOLS, TOSPEC_DIR_NAME, fallbackToolIds, resolveToolSelection, } fro
 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 } from './codex-residue.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';
-/**
- * The canonical skills directory every dependent target is copied from. Named
- * once because two things now key off it — the loop that skips copying a
- * directory onto itself, and the summary line that only applies to targets
- * holding a copy.
- */
+/** The canonical skills directory every dependent target is copied from. */
 function agentsSkillsDirFor(projectPath) {
     return path.join(projectPath, '.agents', 'skills');
 }
-// -----------------------------------------------------------------------------
-// Init Command Class
-// -----------------------------------------------------------------------------
+/** 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) {
         const projectPath = path.resolve(targetPath);
         const tospecDir = TOSPEC_DIR_NAME;
         const tospecPath = path.join(projectPath, tospecDir);
         // Detect without writing: even the permission probe must follow rule preflight.
         const extendMode = await FileSystemUtils.directoryExists(tospecPath);
-        // Detect available tools in the project (task 7.1)
         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);
         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, tospecPath);
-        // The decision rule is always installed (only skipped when no agent dir exists).
-        const installRules = validatedTools.length > 0;
-        // Create directory structure and config
+        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);
+        // 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)));
-        // Display success message
+        await writeWorkflowRules(rulePlan.filter((entry) => successfulIds.has(entry.toolId)), {
+            silent: this.json,
+        });
         this.displaySuccessMessage(projectPath, validatedTools, results, configStatus);
-        // Last, so a run that dies in rule preflight never leaves this behind as
-        // advice about a state it did not reach.
+        // 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)) {
-            console.log(RESIDUAL_CODEX_NOTICE);
+            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;
     }
     /**
-     * Every row in the menu is now a real choice, so a row can still arrive
-     * uninvited — by being required by another. That has to be said *before* the
-     * prompt: an explanation reaching the user after they answered cannot inform
-     * the answer. Derived from the table so a future dependency documents itself.
+     * 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.
      *
-     * Which is also why it is called from the prompt path only. A run driven by
-     * `--tools` or `--interactive=false` has no answer to inform, so the same
-     * lines there are just an unprompted paragraph about targets the user may not
-     * have picked — `tospec init --tools agents` explaining Claude Code.
+     * Prompt path only: a `--tools` run has no answer to inform.
      */
     discloseToolDependencies() {
         for (const tool of AI_TOOLS) {
@@ -127,7 +164,7 @@ export class InitCommand {
                 continue;
             const names = required.map((candidate) => candidate.name).join(', ');
             const dirs = required.map((candidate) => `${candidate.skillsDir}/skills/`).join(', ');
-            console.log(`${tool.name} links its skills into ${dirs}, so selecting it also selects ${names}.`);
+            this.say(`${tool.name} copies its skills from ${dirs}, so selecting it also selects ${names}.`);
         }
     }
     canPromptInteractively() {
@@ -146,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;
@@ -162,11 +195,9 @@ export class InitCommand {
             .map(([toolId]) => toolId));
         const shouldPreselectDetected = !extendMode && configuredToolIds.size === 0;
         const canPrompt = this.canPromptInteractively();
-        // Non-interactive mode: whatever was detected, expanded along `requires`.
-        // Detecting nothing is not a failure — it is an absence of information, not
-        // a decision to write nothing, so it falls back to the base target rather
-        // than leaving a first-time non-interactive setup with no skills at all.
-        // (An explicitly cleared menu *is* a decision, and writes nothing.)
+        // 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) {
             const detected = [...detectedToolIds];
             return resolveToolSelection(detected.length > 0 ? detected : fallbackToolIds());
@@ -174,14 +205,11 @@ export class InitCommand {
         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');
-        // Every target with an output directory is offered, including the one
-        // others link into. What the list shows is what gets written; a row that is
-        // pulled in by another is pulled in by an expansion the user was told about
-        // before answering, not by a checkbox they cannot clear.
+        // 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();
-        // Build choices: pre-select configured tools; keep detected tools visible but unselected.
         const sortedChoices = offeredTools
             .map((toolId) => {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
@@ -197,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)
@@ -212,7 +240,7 @@ export class InitCommand {
             .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) && offeredTools.includes(tool.value))
@@ -221,14 +249,13 @@ export class InitCommand {
             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", the
-        // same as `--tools none`. Refusing it would reject an answer tospec can
-        // honour, and honouring it partially would make the list a suggestion.
+        // No minimum: clearing every checkbox means "write no agent content", as
+        // `--tools none` does.
         const selectedTools = await searchableMultiSelect({
             message: `Select tools to set up (${offeredTools.length} available)`,
             pageSize: 15,
@@ -270,7 +297,7 @@ export class InitCommand {
             throw new Error(`Invalid tool(s): ${invalidTokens.join(', ')}. Available values: ${availableList}`);
         }
         // Expansion deduplicates and orders dependencies first, so naming a tool
-        // whose skills link into another never produces links with no target.
+        // whose skills copy from another never produces a copy with no source.
         return resolveToolSelection(normalizedTokens);
     }
     validateTools(toolIds, toolStates) {
@@ -295,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);
@@ -317,71 +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
-        // every dependent target is copied from.
-        //
-        // Gated on the selection rather than unconditional, so an empty selection
-        // (and `--tools none`) really writes nothing. The condition is "any target
-        // at all" rather than "is .agents selected": dependency expansion already
-        // guarantees it is present whenever anything else is, and a selection that
-        // somehow omitted it would still need canonical content or its dependents
-        // would link at nothing.
+        // 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);
             }
         }
-        // Outside the gate: retiring a workflow tospec itself generated is not
-        // conditional on this run writing anything new. Gated, `--tools none` — the
-        // way a user stops tospec writing agent content — would leave a retired
-        // skill dir on disk and loadable by every agent that reads .agents/skills/,
-        // which is the opposite of what they asked for.
+        // 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 {
-                // Copy each skill dir out of .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);
-                // Independent copies, not links: see the header of utils/link.ts. The
-                // canonical target *is* .agents/skills, and copyDir clears its dest
-                // first, so pointing it at itself would delete the source.
+                // 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);
                 }
@@ -390,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 });
             }
         }
@@ -401,9 +407,6 @@ export class InitCommand {
             removedCommandCount,
         };
     }
-    // ═══════════════════════════════════════════════════════════
-    // CONFIG FILE
-    // ═══════════════════════════════════════════════════════════
     async createConfig(tospecPath, extendMode) {
         const configPath = path.join(tospecPath, 'config.yaml');
         if (resolveConfigFileInDir(tospecPath)) {
@@ -418,102 +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(', ')}`);
         }
-        // An empty selection is an answer tospec honours by writing nothing, so the
-        // report has to say that. Every block below is keyed off a non-empty
-        // selection, which left the run printing the "Setup Complete" banner and a
-        // config line with no statement anywhere that no skills exist — the user
-        // finds out by looking for them.
+        // 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) {
-            console.log('No tools selected: no skills, commands or rules were written.');
+            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);
             // 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(workflows).length;
-            console.log(`${skillCount} skills in ${toolDirs}`);
+            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 on its own. Saying so is what stops a user
-            // editing .agents/skills/ and wondering why the tool never changed.
+            // 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 (dependents.length > 0) {
-                console.log(`Copied from .agents/skills/: ${dependents.map((t) => t.name).join(', ')} — rerun 'tospec update' after editing the canonical skills`);
+            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`);
             }
         }
-        // Show failures
         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)`);
         }
-        // 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();
+        this.say();
         if (tools.length === 0) {
-            // `tospec-propose` is a skill, and this run wrote none — advising it here
-            // would send the user to invoke something that is not on disk.
-            console.log('Getting started:');
-            console.log("  Add agent skills: tospec init --tools <tool>  (or rerun 'tospec init')");
+            // `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')");
         }
         else if (activeWorkflows.includes('propose')) {
-            console.log('Getting started:');
-            console.log('  Start your first change: tospec-propose "your idea"');
+            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.");
         }
-        // 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) {