@seanmars/tospec 0.19.0-beta.8 → 0.20.0

package/dist/commands/config.js

@@ -5,14 +5,31 @@ import { getGlobalConfigPath, getEffectiveConfigPath, getGlobalConfig, saveGloba
 import * as yaml from 'yaml';
 import { getNestedValue, setNestedValue, deleteNestedValue, coerceValue, validateConfigKeyPath, hasUnsafeKeySegment, validateConfig, DEFAULT_CONFIG, } from '../core/config-schema.js';
 import { ALL_WORKFLOWS, getProfileWorkflows } from '../core/profiles.js';
+import { describeWorkflowReferenceGaps, findWorkflowReferenceGaps, } from '../core/shared/skill-generation.js';
 import { TOSPEC_DIR_NAME } from '../core/config.js';
+import { stripBom } from '../core/parsers/requirement-text.js';
 import { UpdateCommand } from '../core/update.js';
-import { isPromptCancellationError, asErrorMessage, CliAbortError, emitSuccess, } from './shared-output.js';
-// Keyed by WorkflowId, not string: this map is a second hand-maintained list
-// parallel to WORKFLOW_DEFS, and with a `string` key a renamed or added workflow
-// drifted silently — the lookup below falls back instead of failing. Both apply
-// entries sat stale from the 0.13.0 verify change for exactly that reason.
-// Typing it shut turns the next rename into a compile error.
+import { isPromptCancellationError, asErrorMessage, CliAbortError, emitSuccess, emitFailureStatus, } from './shared-output.js';
+/**
+ * The `--json` null-shapes, one per subcommand, keyed by the data key each
+ * success payload carries. Shared by the commander-level failure table in
+ * cli/index.ts and the catch sites here, so a parse-time failure (`--bogus`)
+ * mirrors the same shape an action-time failure does.
+ */
+export const CONFIG_FAILURE_PAYLOADS = {
+    path: { path: null },
+    list: { config: null, profileSettings: null },
+    get: { get: null },
+    set: { set: null },
+    unset: { unset: null },
+    reset: { config: null },
+    profile: { profile: null },
+};
+/** The parent `config` command has no data of its own; its preAction abort reports this. */
+export const CONFIG_SCOPE_FAILURE_PAYLOAD = { config: null };
+// Keyed by WorkflowId, not string: this list runs parallel to WORKFLOW_DEFS, and
+// under a `string` key a renamed workflow drifts silently because the lookup
+// below falls back instead of failing. Typed, the next rename is a compile error.
 const WORKFLOW_PROMPT_META = {
     explore: {
         name: 'Explore ideas',
@@ -55,9 +72,6 @@ const WORKFLOW_PROMPT_META = {
         description: 'Run a spec/code sync when warranted, then finalize and archive',
     },
 };
-/**
- * Resolve the effective current profile state from global config defaults.
- */
 export function resolveCurrentProfileState(config) {
     const profile = config.profile || 'core';
     const workflows = [
@@ -65,28 +79,19 @@ export function resolveCurrentProfileState(config) {
     ];
     return { profile, workflows };
 }
-/**
- * Derive profile type from selected workflows.
- */
 export function deriveProfileFromWorkflowSelection(selectedWorkflows) {
     const isCoreMatch = selectedWorkflows.length === ALL_WORKFLOWS.length &&
         ALL_WORKFLOWS.every((w) => selectedWorkflows.includes(w));
     return isCoreMatch ? 'core' : 'custom';
 }
-/**
- * Format a compact workflow summary for the profile header.
- */
 export function formatWorkflowSummary(workflows, profile) {
     return `${workflows.length} selected (${profile})`;
 }
 /**
- * The finding that a stored `workflows` list will not be used, or null.
- *
- * Only the `custom` profile consults the list, so under any other profile it is
- * stored, validated, displayed — and ignored. `config set` warned about it once,
- * at the moment of setting; `config list` then showed the list again with
- * nothing to say it does not apply (round 4 report 16). Worded to match
- * `update`'s `update_workflows_ignored`, so the two commands say one thing.
+ * The finding that a stored `workflows` list will not be used, or null. Only the
+ * `custom` profile consults it, so under any other profile it is stored,
+ * validated, displayed — and ignored. Worded to match `update`'s
+ * `update_workflows_ignored`.
  */
 function ignoredWorkflowsDiagnostic(config) {
     const profile = config.profile ?? 'core';
@@ -101,6 +106,25 @@ function ignoredWorkflowsDiagnostic(config) {
         fix: 'Run "tospec config profile custom" to apply it, or "tospec config unset workflows" to drop it.',
     };
 }
+/**
+ * The finding that the selected workflows' own instructions name workflows the
+ * selection leaves out, or null. Raised here as well as at install time because
+ * this is where the selection is made: `config set workflows
+ * "propose,apply,archive"` otherwise reports success while the resulting
+ * `tospec-archive` still tells an agent to run an uninstalled `tospec-sync`.
+ */
+function workflowReferenceDiagnostic(config) {
+    const gaps = findWorkflowReferenceGaps(resolveListedWorkflows(config));
+    if (gaps.length === 0)
+        return null;
+    const missing = [...new Set(gaps.map((gap) => gap.missing))].sort();
+    return {
+        severity: 'warning',
+        code: 'config_workflow_reference_missing',
+        message: `Selected skills point at workflows this profile leaves out: ${describeWorkflowReferenceGaps(gaps)}.`,
+        fix: `Add them with "tospec config set workflows" (missing: ${missing.join(', ')}), or expect agents to hit instructions they cannot follow.`,
+    };
+}
 function stableWorkflowOrder(workflows) {
     const seen = new Set();
     const ordered = [];
@@ -120,9 +144,6 @@ function stableWorkflowOrder(workflows) {
     }
     return ordered;
 }
-/**
- * Build a user-facing diff summary between two profile states.
- */
 export function diffProfileState(before, after) {
     const lines = [];
     if (before.profile !== after.profile) {
@@ -150,33 +171,26 @@ export function diffProfileState(before, after) {
     };
 }
 /**
- * The config file's raw contents, used only to tell an explicit value from a
- * default — `getGlobalConfig()` has already merged the two and cannot answer it.
- *
- * Reads the file that was actually loaded, not the write target: the two differ
- * until a legacy install migrates.
+ * The config file's raw contents, only to tell an explicit value from a default —
+ * `getGlobalConfig()` has merged the two. Reads the file actually loaded, not
+ * the write target: the two differ until a legacy install migrates.
  */
 function rawGlobalConfig() {
     try {
         const configPath = getEffectiveConfigPath();
         if (fs.existsSync(configPath)) {
-            return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            return JSON.parse(stripBom(fs.readFileSync(configPath, 'utf-8')));
         }
     }
     catch {
-        // Unreadable or malformed: treat every value as a default rather than
-        // failing a read-only listing.
+        // Unreadable: treat every value as a default rather than fail a listing.
     }
     return {};
 }
 /**
  * The workflows a profile resolves to — `core` expands to the full set, any
- * other profile uses its explicit list.
- *
- * Shared by the text and JSON branches of `config list`. The JSON branch used to
- * report only the stored config, leaving a caller unable to turn
- * `profile: "core"` into the workflow names the text branch prints; deriving
- * both from here is what keeps the two answers the same.
+ * other profile uses its explicit list. Shared by both branches of `config
+ * list`, so a `--json` caller can turn `profile: "core"` into workflow names.
  */
 function resolveListedWorkflows(config) {
     if (config.profile === 'core')
@@ -186,34 +200,40 @@ function resolveListedWorkflows(config) {
 function printConfigProfileApplyGuidance() {
     console.log('Config updated. Run `tospec update` in your projects to apply.');
 }
-/**
- * Register the config command and all its subcommands.
- *
- * @param program - The Commander program instance
- */
 export function registerConfigCommand(program) {
     const configCmd = program
         .command('config')
         .description('View and modify global tospec configuration')
         .option('--scope <scope>', 'Config scope (only "global" supported currently)')
-        .hook('preAction', (thisCommand) => {
+        .hook('preAction', (thisCommand, actionCommand) => {
         const opts = thisCommand.opts();
         if (opts.scope && opts.scope !== 'global') {
-            console.error('Error: Project-local config is not yet implemented');
-            // Not `process.exit(1)`: this hook cannot stop the action by returning,
-            // but exiting here would kill the process before stderr is guaranteed
-            // to have flushed. runCli turns this into `process.exitCode = 1`.
-            throw new CliAbortError('Project-local config is not yet implemented');
+            const message = 'Project-local config is not yet implemented';
+            // The subcommand's --json, not the parent's: `config --scope project
+            // get x --json` used to abort with nothing on stdout, so an agent saw
+            // exit 1 and no document at all.
+            if (actionCommand.opts().json) {
+                emitFailureStatus(CONFIG_FAILURE_PAYLOADS[actionCommand.name()] ?? CONFIG_SCOPE_FAILURE_PAYLOAD, { severity: 'error', code: 'config_scope_unsupported', message, fix: 'Omit --scope, or pass --scope global.' });
+            }
+            else {
+                console.error(`Error: ${message}`);
+            }
+            // Not `process.exit(1)`: exiting here kills the process before stderr
+            // has flushed.
+            throw new CliAbortError(message);
         }
     });
-    // config path
     configCmd
         .command('path')
         .description('Show config file location')
-        .action(() => {
+        .option('--json', 'Output as JSON')
+        .action((options) => {
+        if (options.json) {
+            emitSuccess({ path: getGlobalConfigPath() });
+            return;
+        }
         console.log(getGlobalConfigPath());
     });
-    // config list
     configCmd
         .command('list')
         .description('Show all current settings')
@@ -221,22 +241,18 @@ export function registerConfigCommand(program) {
         .action((options) => {
         const config = getGlobalConfig();
         if (options.json) {
-            // Nested, not spread. `GlobalConfigSchema` is `.passthrough()` and
+            // Nested, not spread: the schema is `.passthrough()` and
             // `config set --allow-unknown` writes any top-level key, so spreading
-            // the config into the envelope let user data shadow the envelope's own
-            // reserved fields — `config set version 9 --allow-unknown` replaced the
-            // envelope `version`, and `root`/`status` were open the same way.
-            // Giving the config its own key is what makes that structurally
-            // impossible instead of patching one field name at a time.
-            // See tospec/decisions/20260916_121544-config-list-json-nests-under-config-key.md
+            // lets user data shadow the envelope's reserved fields (`version`,
+            // `root`, `status`).
+            // tospec/decisions/20260916_121544-config-list-json-nests-under-config-key.md
             //
-            // `profileSettings` mirrors what the human branch prints below. The JSON
-            // used to stop at the stored config, so a caller could read
-            // `profile: "core"` and still not know which workflows that resolves to
-            // — the one fact the human output spells out and the one an agent needs
-            // to know whether a skill it wants is installed. Resolved here, beside
-            // the text form, so the two cannot answer differently.
-            const ignored = ignoredWorkflowsDiagnostic(config);
+            // `profileSettings` mirrors the human branch below, the only other place
+            // saying which workflows `profile: "core"` resolves to.
+            const listStatus = [
+                ignoredWorkflowsDiagnostic(config),
+                workflowReferenceDiagnostic(config),
+            ].filter((entry) => entry !== null);
             emitSuccess({
                 config,
                 profileSettings: {
@@ -244,22 +260,19 @@ export function registerConfigCommand(program) {
                     explicit: rawGlobalConfig().profile !== undefined,
                     workflows: resolveListedWorkflows(config),
                 },
-                ...(ignored ? { status: [ignored] } : {}),
+                ...(listStatus.length ? { status: listStatus } : {}),
             });
         }
         else {
             const rawConfig = rawGlobalConfig();
             console.log(yaml.stringify(config).trimEnd());
-            // Round 4 report 16: the dump above is the stored config, so under a
-            // profile that ignores `workflows` this output gave two different
-            // answers for the same key — the stored list here and the profile's
-            // resolved one below — with nothing saying the first is not used.
-            // `config set` said so once, at the moment of setting, and never again.
+            // The dump above is the stored config, so under a profile that ignores
+            // `workflows` it and the resolved list below are two different answers
+            // for one key; this marks which is which.
             const ignored = ignoredWorkflowsDiagnostic(config);
             if (ignored) {
                 console.log(`  ^ ${ignored.message}`);
             }
-            // Annotate profile settings
             const profileSource = rawConfig.profile !== undefined ? '(explicit)' : '(default)';
             console.log(`\nProfile settings:`);
             console.log(`  profile: ${config.profile} ${profileSource}`);
@@ -275,41 +288,74 @@ export function registerConfigCommand(program) {
                 console.log();
                 console.log(ignored.fix);
             }
+            const referenceGap = workflowReferenceDiagnostic(config);
+            if (referenceGap) {
+                console.log();
+                console.log(`Warning: ${referenceGap.message}`);
+                if (referenceGap.fix)
+                    console.log(referenceGap.fix);
+            }
         }
     });
-    // config get
     configCmd
         .command('get <key>')
         .description('Get a specific value (raw, scriptable)')
         .option('--allow-unknown', 'Allow reading unknown keys')
+        .option('--json', 'Output as JSON')
         .action((key, options) => {
         const allowUnknown = Boolean(options.allowUnknown);
         const keyValidation = validateConfigKeyPath(key);
-        // Paired with the same flag on `set`, which without this was a one-way
-        // door: a key written with --allow-unknown showed up in `config list` and
-        // could be removed by `unset`, but `get` — the scriptable reader the flag
-        // exists to feed — refused to read it back.
-        //
-        // Relaxes the known-key check only, never the prototype-safety one; the
-        // same split `set` makes, for the same reason.
+        // Paired with the same flag on `set`: without it a key written with
+        // --allow-unknown could be listed and unset but never read back. Relaxes
+        // the known-key check only, never the prototype-safety one.
         const unsafeKey = hasUnsafeKeySegment(key);
         if (!keyValidation.valid && (!allowUnknown || unsafeKey)) {
             const reason = keyValidation.reason ? ` ${keyValidation.reason}.` : '';
-            console.error(`Error: Invalid configuration key "${key}".${reason}`);
-            console.error('Use "tospec config list" to see available keys.');
+            const fixLines = ['Use "tospec config list" to see available keys.'];
             if (!allowUnknown && !unsafeKey) {
-                console.error('Pass --allow-unknown to read a key set that way.');
+                fixLines.push('Pass --allow-unknown to read a key set that way.');
+            }
+            if (options.json) {
+                emitFailureStatus({ get: null }, {
+                    severity: 'error',
+                    code: 'config_error',
+                    message: `Invalid configuration key "${key}".${reason}`,
+                    fix: fixLines.join('\n'),
+                });
+                return;
             }
+            console.error(`Error: Invalid configuration key "${key}".${reason}`);
+            for (const line of fixLines)
+                console.error(line);
             process.exitCode = 1;
             return;
         }
         const config = getGlobalConfig();
         const value = getNestedValue(config, key);
         if (value === undefined) {
+            if (options.json) {
+                emitFailureStatus({ get: null }, {
+                    severity: 'error',
+                    code: 'config_error',
+                    message: `Key "${key}" is not set.`,
+                    // `workflows` is a list, so the generic `<value>` placeholder
+                    // hides the one thing a caller needs: the comma-separated form.
+                    fix: key === 'workflows'
+                        ? `tospec config set workflows "${ALL_WORKFLOWS.slice(0, 3).join(',')}"`
+                        : `tospec config set ${key} <value>`,
+                });
+                return;
+            }
             console.error(`Error: Key "${key}" is not set.`);
             process.exitCode = 1;
             return;
         }
+        if (options.json) {
+            // The value as stored, not stringified: the human branch below exists
+            // to be scriptable in a shell, which JSON does not need.
+            emitSuccess({ get: { key, value } });
+            return;
+        }
         if (typeof value === 'object' && value !== null) {
             console.log(JSON.stringify(value));
         }
@@ -317,13 +363,25 @@ export function registerConfigCommand(program) {
             console.log(String(value));
         }
     });
-    // config set
     configCmd
         .command('set <key> <value>')
         .description('Set a value (auto-coerce types)')
         .option('--string', 'Force value to be stored as string')
         .option('--allow-unknown', 'Allow setting unknown keys')
+        .option('--json', 'Output as JSON')
         .action((key, value, options) => {
+        /** Every rejection below shares this null-shape, per the envelope contract. */
+        const fail = (message, fix) => {
+            if (options.json) {
+                emitFailureStatus(CONFIG_FAILURE_PAYLOADS.set, { severity: 'error', code: 'config_error', message, ...(fix ? { fix } : {}) });
+                return;
+            }
+            console.error(`Error: ${message}`);
+            if (fix)
+                for (const line of fix.split('\n'))
+                    console.error(line);
+            process.exitCode = 1;
+        };
         const allowUnknown = Boolean(options.allowUnknown);
         const keyValidation = validateConfigKeyPath(key);
         // --allow-unknown relaxes the known-key check, but never the
@@ -331,86 +389,131 @@ export function registerConfigCommand(program) {
         const unsafeKey = hasUnsafeKeySegment(key);
         if (!keyValidation.valid && (!allowUnknown || unsafeKey)) {
             const reason = keyValidation.reason ? ` ${keyValidation.reason}.` : '';
-            console.error(`Error: Invalid configuration key "${key}".${reason}`);
-            console.error('Use "tospec config list" to see available keys.');
+            const fixLines = ['Use "tospec config list" to see available keys.'];
             if (!allowUnknown && !unsafeKey) {
-                console.error('Pass --allow-unknown to bypass this check.');
+                fixLines.push('Pass --allow-unknown to bypass this check.');
             }
-            process.exitCode = 1;
+            fail(`Invalid configuration key "${key}".${reason}`, fixLines.join('\n'));
             return;
         }
         const config = getGlobalConfig();
         const coercedValue = coerceValue(value, options.string || false, key);
-        // Create a copy to validate before saving
+        // Validate a copy before touching the config that is saved.
         const newConfig = JSON.parse(JSON.stringify(config));
         setNestedValue(newConfig, key, coercedValue);
-        // Validate the new config
         const validation = validateConfig(newConfig);
         if (!validation.success) {
-            console.error(`Error: Invalid configuration - ${validation.error}`);
-            process.exitCode = 1;
+            fail(`Invalid configuration - ${validation.error}`);
             return;
         }
         // The schema types `workflows` as string[], so a misspelled id passes it
-        // and is then dropped by `update`'s filter against ALL_WORKFLOWS —
-        // installing fewer skills than asked for, silently. Caught here because
-        // this is the only point that still has the word the user typed.
+        // and is later dropped by `update`'s filter against ALL_WORKFLOWS. This is
+        // the last point that still has the word the user typed.
         if (key === 'workflows' && Array.isArray(coercedValue)) {
             const unknown = coercedValue.filter((entry) => !ALL_WORKFLOWS.includes(String(entry)));
             if (unknown.length > 0) {
-                console.error(`Error: Unknown workflow(s): ${unknown.join(', ')}`);
-                console.error(`Available: ${ALL_WORKFLOWS.join(', ')}`);
-                process.exitCode = 1;
+                fail(`Unknown workflow(s): ${unknown.join(', ')}`, `Available: ${ALL_WORKFLOWS.join(', ')}`);
                 return;
             }
         }
-        // Apply changes and save
         setNestedValue(config, key, coercedValue);
         saveGlobalConfig(config);
+        // Only `custom` reads `workflows`; under `core` getProfileWorkflows
+        // discards it. Said alongside the confirmation, not instead of it: the
+        // value genuinely was stored, it is just not what `update` acts on.
+        const profile = config.profile ?? 'core';
+        const workflowsIgnored = key === 'workflows' && profile !== 'custom';
+        // The mirror image: `config profile custom` refuses without a list, but
+        // `set` is the raw write and stays permissive — so it has to say what
+        // that write means, or the next `init` installs zero skills unannounced.
+        const storedWorkflows = config.workflows;
+        const profileNeedsWorkflows = key === 'profile' &&
+            coercedValue === 'custom' &&
+            (!storedWorkflows || storedWorkflows.length === 0);
+        const warnings = [];
+        if (workflowsIgnored) {
+            warnings.push({
+                severity: 'warning',
+                code: 'config_workflows_ignored',
+                message: `Profile '${profile}' installs every workflow, so this list is not used.`,
+                fix: 'Run "tospec config profile custom" to make it take effect.',
+            });
+        }
+        if (profileNeedsWorkflows) {
+            warnings.push({
+                severity: 'warning',
+                code: 'config_profile_needs_workflows',
+                message: 'Profile "custom" needs a workflows list, and none is configured, so init and update install no skills.',
+                fix: `tospec config set workflows "${ALL_WORKFLOWS.slice(0, 3).join(',')}"`,
+            });
+        }
+        if (options.json) {
+            emitSuccess({
+                set: { key, value: coercedValue },
+                ...(warnings.length > 0 ? { status: warnings } : {}),
+            });
+            return;
+        }
         const displayValue = typeof coercedValue === 'string' ? `"${coercedValue}"` : String(coercedValue);
         console.log(`Set ${key} = ${displayValue}`);
-        // `workflows` is only read when the profile is `custom`; under `core`,
-        // getProfileWorkflows discards it and returns ALL_WORKFLOWS. Everything up
-        // to here — the key check, the workflow-name check, the "Set workflows =
-        // ..." line, and `config list` showing it — tells the user it took effect.
-        // Said after the confirmation rather than instead of it, because the value
-        // genuinely was stored; it just is not what `update` will act on.
-        if (key === 'workflows') {
-            const profile = config.profile ?? 'core';
-            if (profile !== 'custom') {
-                console.error(`Warning: profile '${profile}' installs every workflow, so this list is not used.`);
-                console.error('Run "tospec config profile custom" to make it take effect.');
-            }
+        for (const warning of warnings) {
+            console.error(`Warning: ${warning.message}`);
+            if (warning.fix)
+                console.error(warning.fix);
         }
     });
-    // config unset
     configCmd
         .command('unset <key>')
         .description('Remove a key (revert to default)')
-        .action((key) => {
+        .option('--json', 'Output as JSON')
+        .action((key, options) => {
         const config = getGlobalConfig();
         const existed = deleteNestedValue(config, key);
-        if (existed) {
+        if (existed)
             saveGlobalConfig(config);
-            console.log(`Unset ${key} (reverted to default)`);
-        }
-        else {
-            console.log(`Key "${key}" was not set`);
+        if (options.json) {
+            // Success either way: unsetting an absent key is the state the caller
+            // asked for. `existed` is what says whether anything changed.
+            emitSuccess({ unset: { key, existed } });
+            return;
         }
+        console.log(existed ? `Unset ${key} (reverted to default)` : `Key "${key}" was not set`);
     });
-    // config reset
     configCmd
         .command('reset')
         .description('Reset configuration to defaults')
         .option('--all', 'Reset all configuration (required)')
         .option('-y, --yes', 'Skip confirmation prompts')
+        .option('--json', 'Output as JSON (non-interactive; requires --all and --yes)')
         .action(async (options) => {
+        // `list`, `get` and `set` all speak --json, so reset must too.
         if (!options.all) {
+            if (options.json) {
+                emitFailureStatus({ config: null }, {
+                    severity: 'error',
+                    code: 'config_error',
+                    message: '--all flag is required for reset.',
+                    fix: 'tospec config reset --all --yes --json',
+                });
+                return;
+            }
             console.error('Error: --all flag is required for reset');
             console.error('Usage: tospec config reset --all [-y]');
             process.exitCode = 1;
             return;
         }
+        // --json is non-interactive by contract: a prompt would block a caller
+        // that cannot answer and put non-JSON on stdout. Refuse rather than reset
+        // unasked — the flag must not become a quieter `--yes`.
+        if (options.json && !options.yes) {
+            emitFailureStatus({ config: null }, {
+                severity: 'error',
+                code: 'config_error',
+                message: '--json cannot prompt for confirmation.',
+                fix: 'tospec config reset --all --yes --json',
+            });
+            return;
+        }
         if (!options.yes) {
             const { confirm } = await import('@inquirer/prompts');
             let confirmed;
@@ -434,9 +537,12 @@ export function registerConfigCommand(program) {
             }
         }
         saveGlobalConfig({ ...DEFAULT_CONFIG });
+        if (options.json) {
+            emitSuccess({ config: getGlobalConfig() });
+            return;
+        }
         console.log('Configuration reset to defaults');
     });
-    // config edit
     configCmd
         .command('edit')
         .description('Open config in $EDITOR')
@@ -450,13 +556,10 @@ export function registerConfigCommand(program) {
             return;
         }
         const configPath = getGlobalConfigPath();
-        // Ensure config file exists with defaults
         if (!fs.existsSync(configPath)) {
             saveGlobalConfig({ ...DEFAULT_CONFIG });
         }
-        // Spawn editor and wait for it to close
-        // Avoid shell parsing to correctly handle paths with spaces in both
-        // the editor path and config path
+        // shell: false so a space in the editor or config path is not re-parsed.
         const child = spawn(editor, [configPath], {
             stdio: 'inherit',
             shell: false,
@@ -474,7 +577,11 @@ export function registerConfigCommand(program) {
         });
         try {
             const rawConfig = fs.readFileSync(configPath, 'utf-8');
-            const parsedConfig = JSON.parse(rawConfig);
+            // `config edit` just handed this file to the user's editor, and a
+            // Windows editor saving it back adds a BOM nobody asked for. Rejecting
+            // the result as "Invalid JSON" would blame the user for an edit tospec
+            // invited.
+            const parsedConfig = JSON.parse(stripBom(rawConfig));
             const validation = validateConfig(parsedConfig);
             if (!validation.success) {
                 console.error(`Error: Invalid configuration - ${validation.error}`);
@@ -495,32 +602,71 @@ export function registerConfigCommand(program) {
             process.exitCode = 1;
         }
     });
-    // config profile [preset]
     configCmd
         .command('profile [preset]')
         .description('Configure workflow profile (interactive picker or preset shortcut)')
-        .action(async (preset) => {
-        // Preset shortcut: `tospec config profile core`
+        .option('--json', 'Output as JSON (non-interactive; requires a preset)')
+        .action(async (preset, options) => {
+        /** Every rejection below shares this null-shape, per the envelope contract. */
+        const fail = (message, fix) => {
+            if (options.json) {
+                emitFailureStatus(CONFIG_FAILURE_PAYLOADS.profile, { severity: 'error', code: 'config_error', message, ...(fix ? { fix } : {}) });
+                return;
+            }
+            console.error(`Error: ${message}`);
+            if (fix)
+                console.error(`Fix: ${fix}`);
+            process.exitCode = 1;
+        };
+        /** The resolved state, so a caller need not re-read it with `config list`. */
+        const reportApplied = (config) => {
+            if (options.json) {
+                emitSuccess({ profile: resolveCurrentProfileState(config) });
+                return;
+            }
+            printConfigProfileApplyGuidance();
+        };
+        // The stored list is dropped, not rewritten to ALL_WORKFLOWS: rewriting it
+        // manufactures the state `ignoredWorkflowsDiagnostic` warns about.
         if (preset === 'core') {
             const config = getGlobalConfig();
             config.profile = 'core';
-            config.workflows = [...ALL_WORKFLOWS];
+            delete config.workflows;
             saveGlobalConfig(config);
-            printConfigProfileApplyGuidance();
+            reportApplied(config);
+            return;
+        }
+        // The command `config set workflows` and `config list` both name as the
+        // way to make a workflow list take effect.
+        if (preset === 'custom') {
+            const config = getGlobalConfig();
+            // Without a list, `custom` resolves to zero workflows and the next
+            // `tospec update` deletes every installed skill directory.
+            if (!config.workflows || config.workflows.length === 0) {
+                fail('Profile "custom" needs a workflows list, and none is configured.', `tospec config set workflows "${ALL_WORKFLOWS.slice(0, 3).join(',')}"`);
+                return;
+            }
+            config.profile = 'custom';
+            saveGlobalConfig(config);
+            reportApplied(config);
             return;
         }
         if (preset) {
-            console.error(`Error: Unknown profile preset "${preset}". Available presets: core`);
-            process.exitCode = 1;
+            fail(`Unknown profile preset "${preset}". Available presets: core, custom`);
+            return;
+        }
+        // --json has no way to answer a picker, so it never opens one: the
+        // failure names the presets rather than hanging on a prompt no caller
+        // will see.
+        if (options.json) {
+            fail('Interactive profile selection is not available under --json.', 'tospec config profile core --json | tospec config profile custom --json');
             return;
         }
-        // Non-interactive check
         if (!process.stdout.isTTY) {
-            console.error('Interactive mode required. Use `tospec config profile core` or set config via environment/flags.');
+            console.error('Interactive mode required. Use `tospec config profile core|custom` or set config via environment/flags.');
             process.exitCode = 1;
             return;
         }
-        // Interactive picker
         const { select, checkbox, confirm } = await import('@inquirer/prompts');
         try {
             const config = getGlobalConfig();
@@ -554,9 +700,8 @@ export function registerConfigCommand(program) {
             };
             if (action === 'workflows') {
                 const formatWorkflowChoice = (workflow) => {
-                    // The map is complete by construction (Record<WorkflowId>); this
-                    // fallback is only for an id a user's custom config carries that
-                    // this build no longer ships.
+                    // The map is complete by construction; this only catches an id a
+                    // user's custom config carries that this build no longer ships.
                     const metadata = WORKFLOW_PROMPT_META[workflow] ?? {
                         name: workflow,
                         description: `Workflow: ${workflow}`,
@@ -594,9 +739,13 @@ export function registerConfigCommand(program) {
             }
             console.log();
             config.profile = nextState.profile;
-            config.workflows = nextState.workflows;
+            // Same rule as the `core` preset above: a list stored under `core` is an
+            // ignored key every later `config list` warns about.
+            if (nextState.profile === 'core')
+                delete config.workflows;
+            else
+                config.workflows = nextState.workflows;
             saveGlobalConfig(config);
-            // Check if inside an Tospec project
             const projectDir = process.cwd();
             const tospecDir = path.join(projectDir, TOSPEC_DIR_NAME);
             if (fs.existsSync(tospecDir)) {
@@ -606,9 +755,8 @@ export function registerConfigCommand(program) {
                 });
                 if (applyNow) {
                     try {
-                        // Run in-process instead of `npx tospec update`, which depends on
-                        // tospec/npx resolving on PATH and fails under global installs or
-                        // monorepos.
+                        // In-process, not `npx tospec update`: that depends on PATH and
+                        // fails under global installs and monorepos.
                         await new UpdateCommand().execute(projectDir);
                         console.log('Run `tospec update` in your other projects to apply.');
                     }