peaks-loop 4.1.2 → 4.1.4

package/scripts/install-skills-fs.mjs

@@ -0,0 +1,148 @@
+// scripts/install-skills-fs.mjs
+//
+// The guarded filesystem and path vocabulary the installers share: every read that must
+// not follow a symlink, every write that must be atomic, and the two containments
+// (a path stays inside a root; a lock root does not move under a write).
+//
+// Split out of `scripts/install-skills.mjs` (rid-043). Every line below was moved
+// VERBATIM from that file; only this header, the import block, and the `export`
+// keyword on names a sibling imports are new.
+
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fchmodSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync
+} from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function getPathStats(path) {
+  try {
+    return lstatSync(path);
+  } catch {
+    return null;
+  }
+}
+
+export function validateOpenFile(fd, path, errorMessage) {
+  const fdStats = fstatSync(fd);
+  const pathStats = lstatSync(path);
+  if (
+    !fdStats.isFile() ||
+    !pathStats.isFile() ||
+    fdStats.dev !== pathStats.dev ||
+    fdStats.ino !== pathStats.ino
+  ) {
+    throw new Error(errorMessage);
+  }
+  if (fdStats.nlink !== 1 || pathStats.nlink !== 1) {
+    throw new Error(`${errorMessage}: hardlinked file`);
+  }
+}
+
+export function getSafeReadOpenFlags() {
+  return typeof constants.O_NOFOLLOW === 'number'
+    ? constants.O_RDONLY | constants.O_NOFOLLOW
+    : constants.O_RDONLY;
+}
+
+export function readFileSafely(path, errorMessage) {
+  const fd = openSync(path, getSafeReadOpenFlags());
+  try {
+    validateOpenFile(fd, path, errorMessage);
+    return readFileSync(fd, 'utf8');
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export function validateInstallRoot(targetRoot, label) {
+  const rootStats = lstatSync(targetRoot);
+  if (rootStats.isSymbolicLink()) {
+    throw new Error(`${label} install root must not be a symlink`);
+  }
+  if (!rootStats.isDirectory()) {
+    throw new Error(`${label} install root must be a directory`);
+  }
+  return rootStats;
+}
+
+export function createInstallRootValidator(targetRoot, label) {
+  const expectedStats = validateInstallRoot(targetRoot, label);
+  return () => {
+    const rootStats = validateInstallRoot(targetRoot, label);
+    if (rootStats.dev !== expectedStats.dev || rootStats.ino !== expectedStats.ino) {
+      throw new Error(`${label} install root changed during write`);
+    }
+  };
+}
+
+export function resolvePackageRoot(options = {}) {
+  return resolve(options.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..'));
+}
+
+export function isInsidePath(childPath, parentPath) {
+  const relativePath = relative(parentPath, childPath);
+  return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
+}
+
+export function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function getSafeTempOpenFlags() {
+  const baseFlags = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL;
+  return typeof constants.O_NOFOLLOW === 'number' ? baseFlags | constants.O_NOFOLLOW : baseFlags;
+}
+
+export function writeFileAtomically(configPath, content, errorMessage, validateBeforeWrite) {
+  validateBeforeWrite();
+
+  const tempPath = `${configPath}.${process.pid}.${randomUUID()}.tmp`;
+  let fd = openSync(tempPath, getSafeTempOpenFlags(), 0o600);
+  let renamed = false;
+  let closeError = null;
+  try {
+    validateOpenFile(fd, tempPath, errorMessage);
+    fchmodSync(fd, 0o600);
+    writeFileSync(fd, content, 'utf8');
+    const writeFd = fd;
+    fd = null;
+    closeSync(writeFd);
+    validateBeforeWrite();
+    const readFd = openSync(tempPath, getSafeReadOpenFlags());
+    try {
+      validateOpenFile(readFd, tempPath, errorMessage);
+    } finally {
+      closeSync(readFd);
+    }
+    renameSync(tempPath, configPath);
+    renamed = true;
+  } finally {
+    if (fd !== null) {
+      try {
+        closeSync(fd);
+      } catch (error) {
+        closeError = error;
+      }
+    }
+    try {
+      if (!renamed && existsSync(tempPath)) {
+        unlinkSync(tempPath);
+      }
+    } finally {
+      if (closeError) {
+        throw closeError;
+      }
+    }
+  }
+}

package/scripts/install-skills-ide.mjs

@@ -0,0 +1,279 @@
+// scripts/install-skills-ide.mjs
+//
+// Who is installed FOR, and where each one keeps its assets. The profile table bakes
+// `homedir()` at module load, so a caller that redirects `$HOME`/$`USERPROFILE` must do it
+// BEFORE this module is imported.
+//
+// Split out of `scripts/install-skills.mjs` (rid-043). Every line below was moved
+// VERBATIM from that file; only this header, the import block, and the `export`
+// keyword on names a sibling imports are new.
+
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+export function resolveProjectRoot(options) {
+  const projectRoot = options.projectRoot ?? process.env.PEAKS_PROJECT_ROOT ?? process.env.INIT_CWD;
+  return projectRoot ? resolve(projectRoot) : null;
+}
+
+/**
+ * Slice #011: Detect the installed IDE for the postinstall dispatch layer.
+ *
+ * Mirrors `src/services/ide/ide-detector.ts:detectInstalledIde` (cwd heuristic)
+ * but inlined here because `install-skills.mjs` is a plain `.mjs` script and
+ * cannot import the TS service at runtime. The dispatch:
+ *   - Look for `.claude`, `.trae`, `.codex`, `.cursor`, `.qoder`,
+ *     `.tongyi-lingma` in the project root in that insertion order
+ *     (matches the registry's adapter order in `src/services/ide/ide-registry.ts`).
+ *   - Returns the first match, or `null` if no adapter's directory is present.
+ *
+ * If the resolved IDE has no `skillInstall` declared (Trae in slice 1.3.2),
+ * the caller falls back to the legacy `~/.claude/{skills,output-styles}` path
+ * + emits a stderr warning. The dispatch is conservative: the env-var
+ * overrides `PEAKS_CLAUDE_SKILLS_DIR` / `PEAKS_CLAUDE_OUTPUT_STYLES_DIR`
+ * continue to work, and the legacy default is preserved.
+ *
+ * 2026-09-15 (D12 fix): `hermes` and `openclaw` have install profiles in
+ * `IDE_SKILL_INSTALL_PROFILES` but were absent from this table. A profile
+ * that no detector can ever return is reachable only through the
+ * every-platform fan-out — i.e. it is installed for users who do NOT have
+ * the tool and skipped for nobody. Both are listed here now, so detection
+ * and installation answer the same question with the same table.
+ *
+ * This table is ALSO the presence oracle for `isPlatformPresent` below: a
+ * directory here in the project root means the user has that tool.
+ */
+export const IDE_DETECTION_DIRS = [
+  { id: 'claude-code', dir: '.claude' },
+  { id: 'trae', dir: '.trae' },
+  { id: 'trae-cn', dir: '.trae-cn' },
+  { id: 'codex', dir: '.codex' },
+  { id: 'cursor', dir: '.cursor' },
+  { id: 'qoder', dir: '.qoder' },
+  { id: 'tongyi-lingma', dir: '.tongyi-lingma' },
+  { id: 'zcode', dir: '.zcode' },
+  { id: 'hermes', dir: '.hermes' },
+  { id: 'openclaw', dir: '.openclaw' }
+];
+
+/**
+ * Per-IDE skill install paths. Per peaks-loop tenet
+ * "minimal-user-operation" (2026-06-11), the user should
+ * never have to run a per-platform install command — the
+ * `npm i -g peaks-loop` postinstall iterates the platforms
+ * the user HAS and symlinks the peaks-* skill family into each
+ * (see `isPlatformPresent`; D9/2026-09-15 made "has" load-bearing).
+ *
+ * 1.x had only `claude-code` (the other 5 entries were
+ * `null`); real Trae users reported the Trae skill
+ * directory was never populated. 2.0 fixes this by giving
+ * every platform a canonical install path.
+ */
+export const IDE_SKILL_INSTALL_PROFILES = {
+  'claude-code': {
+    // `alwaysPresent` — see `isPlatformPresent`. Declared HERE, in the
+    // vendor's own row, rather than as an `ideId === 'claude-code'` branch in
+    // the consumer: the guard at
+    // `tests/unit/runtime/vendor-neutral-identity-guard.test.ts` pins identity
+    // DECISIONS to the vendor declarations, and a comparison in the consumer
+    // is exactly the re-injection shape it exists to catch. A future vendor
+    // opts into the same policy by setting this field.
+    alwaysPresent: true,
+    skillsDir: join(homedir(), '.claude', 'skills'),
+    outputStylesDir: join(homedir(), '.claude', 'output-styles'),
+    agentsDir: join(homedir(), '.claude', 'agents'),
+    envVar: 'PEAKS_CLAUDE_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_CLAUDE_OUTPUT_STYLES_DIR',
+    agentsEnvVar: 'PEAKS_CLAUDE_AGENTS_DIR'
+  },
+  trae: {
+    skillsDir: join(homedir(), '.trae', 'skills'),
+    outputStylesDir: join(homedir(), '.trae', 'output-styles'),
+    agentsDir: join(homedir(), '.trae', 'agents'),
+    envVar: 'PEAKS_TRAE_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_TRAE_OUTPUT_STYLES_DIR',
+    agentsEnvVar: 'PEAKS_TRAE_AGENTS_DIR'
+  },
+  'trae-cn': {
+    skillsDir: join(homedir(), '.trae-cn', 'skills'),
+    outputStylesDir: join(homedir(), '.trae-cn', 'output-styles'),
+    agentsDir: join(homedir(), '.trae-cn', 'agents'),
+    envVar: 'PEAKS_TRAE_CN_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_TRAE_CN_OUTPUT_STYLES_DIR',
+    agentsEnvVar: 'PEAKS_TRAE_CN_AGENTS_DIR'
+  },
+  codex: {
+    skillsDir: join(homedir(), '.codex', 'skills'),
+    outputStylesDir: join(homedir(), '.codex', 'output-styles'),
+    agentsDir: join(homedir(), '.codex', 'agents'),
+    envVar: 'PEAKS_CODEX_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_CODEX_OUTPUT_STYLES_DIR',
+    agentsEnvVar: 'PEAKS_CODEX_AGENTS_DIR'
+  },
+  cursor: {
+    skillsDir: join(homedir(), '.cursor', 'skills'),
+    outputStylesDir: join(homedir(), '.cursor', 'output-styles'),
+    agentsDir: join(homedir(), '.cursor', 'agents'),
+    envVar: 'PEAKS_CURSOR_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_CURSOR_OUTPUT_STYLES_DIR',
+    agentsEnvVar: 'PEAKS_CURSOR_AGENTS_DIR'
+  },
+  qoder: {
+    skillsDir: join(homedir(), '.qoder', 'skills'),
+    outputStylesDir: join(homedir(), '.qoder', 'output-styles'),
+    envVar: 'PEAKS_QODER_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_QODER_OUTPUT_STYLES_DIR'
+  },
+  'tongyi-lingma': {
+    skillsDir: join(homedir(), '.tongyi-lingma', 'skills'),
+    outputStylesDir: join(homedir(), '.tongyi-lingma', 'output-styles'),
+    envVar: 'PEAKS_TONGYI_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_TONGYI_OUTPUT_STYLES_DIR'
+  },
+  hermes: {
+    skillsDir: join(homedir(), '.hermes', 'skills'),
+    outputStylesDir: join(homedir(), '.hermes', 'output-styles'),
+    envVar: 'PEAKS_HERMES_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_HERMES_OUTPUT_STYLES_DIR'
+  },
+  openclaw: {
+    skillsDir: join(homedir(), '.openclaw', 'skills'),
+    outputStylesDir: join(homedir(), '.openclaw', 'output-styles'),
+    envVar: 'PEAKS_OPENCLAW_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_OPENCLAW_OUTPUT_STYLES_DIR'
+  },
+  zcode: {
+    skillsDir: join(homedir(), '.zcode', 'skills'),
+    outputStylesDir: join(homedir(), '.zcode', 'output-styles'),
+    agentsDir: join(homedir(), '.zcode', 'agents'),
+    envVar: 'PEAKS_ZCODE_SKILLS_DIR',
+    outputStylesEnvVar: 'PEAKS_ZCODE_OUTPUT_STYLES_DIR',
+    agentsEnvVar: 'PEAKS_ZCODE_AGENTS_DIR'
+  }
+};
+
+export function detectInstalledIdeId(projectRoot) {
+  if (!projectRoot) return null;
+  for (const { id, dir } of IDE_DETECTION_DIRS) {
+    if (existsSync(join(projectRoot, dir))) {
+      return id;
+    }
+  }
+  return null;
+}
+
+export function resolveIdeSkillInstallProfile(ideId) {
+  if (ideId === null) return null;
+  return IDE_SKILL_INSTALL_PROFILES[ideId] ?? null;
+}
+
+/**
+ * Is this platform actually installed FOR? (D9 fix, 2026-09-15.)
+ *
+ * Before this gate, the postinstall ran `mkdirSync(targetRoot, {recursive:
+ * true})` for ALL 10 profiles unconditionally, so `npm i -g peaks-loop` created
+ * `~/.hermes`, `~/.openclaw`, `~/.qoder`, `~/.tongyi-lingma` and `~/.zcode` in
+ * the home of a user who has never installed those tools. The peaks-loop tenet
+ * is "the user never has to run a per-platform install command" — it is NOT
+ * "peaks-loop guesses which tools you have". Creating a directory for a tool
+ * the user does not own is the tenet misread, and it is visible on disk.
+ *
+ * Present means EITHER:
+ *   - the tool's marker directory exists in the project root (the same
+ *     directory `detectInstalledIdeId` consults above), OR
+ *   - the tool's own home directory (`~/.<tool>`, derived from its profile)
+ *     already exists on this machine.
+ *
+ * `claude-code` is unconditionally present: it is peaks-loop's primary runtime
+ * and the documented legacy install target, so a machine with no `~/.claude`
+ * yet still gets the trees the user is installing peaks-loop for. That fact is
+ * declared as `alwaysPresent: true` IN THE VENDOR'S OWN PROFILE ROW — not as an
+ * `ideId === 'claude-code'` branch here. This file sits outside the adapter
+ * layer, so an identity comparison in it is the re-injection shape
+ * `tests/unit/runtime/vendor-neutral-identity-guard.test.ts` pins; reading the
+ * vendor's declaration keeps the policy in one place and vendor-neutral.
+ *
+ * A named target bypasses this gate entirely — `options.targetRoot`,
+ * `options.ideId`, and the `PEAKS_<TOOL>_SKILLS_DIR` env vars are callers who
+ * have already said which platform they mean; guessing a second time there
+ * would break the 1.x back-compat contract that slice 2026-06-12 restored.
+ */
+export function isPlatformPresent(ideId, profile, projectRoot) {
+  if (profile.alwaysPresent === true) return true;
+  const detection = IDE_DETECTION_DIRS.find((entry) => entry.id === ideId);
+  if (
+    detection !== undefined &&
+    projectRoot !== null &&
+    existsSync(join(projectRoot, detection.dir))
+  ) {
+    return true;
+  }
+  return existsSync(dirname(profile.skillsDir));
+}
+
+export function warnUnverifiedIde(ideId, projectRoot) {
+  process.stderr.write(
+    `peaks install-skills: IDE '${ideId}' has no skillInstall profile declared; ` +
+      `falling back to the legacy Claude Code path (~/.claude/skills + ~/.claude/output-styles) ` +
+      `for project '${projectRoot}'. This is a slice #011 follow-up gap; ` +
+      `see .peaks/memory/ide-adapter-resource-profile-framework.md.\n`
+  );
+}
+
+export function warnNoIdeDetected(projectRoot) {
+  process.stderr.write(
+    `peaks install-skills: no IDE detected in '${projectRoot ?? '(project root unknown)'}'; ` +
+      `installing to the legacy Claude Code path (~/.claude/skills + ~/.claude/output-styles). ` +
+      `Set PEAKS_CLAUDE_SKILLS_DIR / PEAKS_CLAUDE_OUTPUT_STYLES_DIR to override.\n`
+  );
+}
+
+/**
+ * THE ONE DISPATCH PRECEDENCE — the three families that resolve a target root
+ * (skills, agents, output-styles) each stated it separately before rid-043. Highest
+ * first:
+ *
+ *   1. explicit `options.targetRoot`              (test / hook override)
+ *   2. `options.ideId`'s `spec.profileField`      (per-IDE dispatch)
+ *   3. `spec.envVar`                              (legacy 1.x back-compat)
+ *   4. the DETECTED ide's `spec.profileField`     (auto-detect from projectRoot)
+ *   5. `join(homedir(), spec.fallback)`           (no-IDE fallback)
+ *
+ * `spec.warn` is the ONE declared difference between the callers, and it is a field
+ * rather than a branch at each call site: the SKILLS installer is the only family
+ * that tells the user an IDE was seen without a profile, or that none was seen at
+ * all. Output styles and agents resolve identically in silence.
+ *
+ * The two warn arms are mutually exclusive (`detectedIdeId` cannot be both null and
+ * non-null), so the `else if` below is the same set of messages the two separate
+ * `if`s produced.
+ *
+ * @param {Record<string, unknown>} options
+ * @param {{ profileField: string, envVar: string, fallback: string, warn?: boolean }} spec
+ * @returns {string} the resolved, absolute target root
+ */
+export function resolveBundleTargetRoot(options, spec) {
+  const projectRoot = resolveProjectRoot(options);
+  const detectedIdeId = detectInstalledIdeId(projectRoot);
+  const detectedProfile = resolveIdeSkillInstallProfile(detectedIdeId);
+
+  if (spec.warn === true && options.targetRoot === undefined && options.ideId === undefined) {
+    if (detectedProfile === null && detectedIdeId !== null) {
+      warnUnverifiedIde(detectedIdeId, projectRoot ?? '(project root unknown)');
+    } else if (detectedIdeId === null && projectRoot !== null) {
+      warnNoIdeDetected(projectRoot);
+    }
+  }
+
+  const profileDir = detectedProfile?.[spec.profileField] ?? null;
+  return resolve(
+    options.targetRoot ??
+      (options.ideId !== undefined
+        ? (resolveIdeSkillInstallProfile(options.ideId)?.[spec.profileField] ?? null)
+        : null) ??
+      process.env[spec.envVar] ??
+      profileDir ??
+      join(homedir(), spec.fallback)
+  );
+}

package/scripts/install-skills-output-style-default.mjs

@@ -0,0 +1,196 @@
+// scripts/install-skills-output-style-default.mjs
+//
+// `settings.json` registration: after the style file lands, Claude Code still loads no
+// Peaks style until `outputStyle` names it. Soft-fails on every error path, because the
+// bundled file is already on disk by the time this runs.
+//
+// Split out of `scripts/install-skills.mjs` (rid-043). Every line below was moved
+// VERBATIM from that file; only this header, the import block, and the `export`
+// keyword on names a sibling imports are new.
+
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import {
+  getPathStats,
+  isPlainObject,
+  readFileSafely,
+  writeFileAtomically
+} from './install-skills-fs.mjs';
+
+/**
+ * Slice 2026-08-02 — auto-register bundled output style.
+ *
+ * Real user feedback (2026-08-02): `npm i -g peaks-loop@latest` on a
+ * fresh 0-1 project copied `peaks-skill-swarm.md` into
+ * `~/.claude/output-styles/` but never wrote
+ * `outputStyle: 'peaks-skill-swarm'` into `~/.claude/settings.json`.
+ * Result: Claude Code loaded no Peaks output style in new sessions.
+ *
+ * The fix: when `peaks-skill-swarm.md` is present in the bundled output
+ * styles directory AND `~/.claude/settings.json` does NOT yet declare
+ * `outputStyle`, merge in `outputStyle: 'peaks-skill-swarm'` while
+ * preserving every other key. If the user already set `outputStyle`,
+ * leave it alone — the user is the source of truth.
+ *
+ * Resolution precedence:
+ *   1. options.settingsFile  (explicit override / test hook)
+ *   2. PEAKS_CLAUDE_SETTINGS_FILE env var  (CI override)
+ *   3. homedir-relative `<homedir>/.claude/settings.json`  (default)
+ *
+ * Soft-fail contract: every error path (missing file, malformed JSON,
+ * missing bundled style file, permission denied) is logged to stderr
+ * and returns `{ skipped: true, ... }` instead of throwing. The
+ * postinstall must never fail on this step because the bundled file
+ * itself was already written successfully.
+ */
+export function resolveSettingsFilePath(options = {}) {
+  if (typeof options.settingsFile === 'string' && options.settingsFile.length > 0) {
+    return resolve(options.settingsFile);
+  }
+  const envOverride = process.env.PEAKS_CLAUDE_SETTINGS_FILE;
+  if (typeof envOverride === 'string' && envOverride.length > 0) {
+    return resolve(envOverride);
+  }
+  return resolve(homedir(), '.claude', 'settings.json');
+}
+
+/** Is `targetPath` a plain single-linked regular file — not a link, not a directory? */
+function isRegularFile(targetPath) {
+  const stats = getPathStats(targetPath);
+  return stats !== null && stats.isFile() && !stats.isSymbolicLink() && stats.nlink === 1;
+}
+
+/**
+ * The existing `settings.json` as an object, or the refusal that stops the write.
+ *
+ * Read FIRST so a malformed file surfaces as a parse error — more actionable to the
+ * user than the generic "bundled style not present" message — and because malformed
+ * JSON is a user-authored file this must never clobber.
+ *
+ * @param {string} settingsPath
+ * @returns {{ existing: Record<string, unknown> | null } | { refusal: { skipped: true, reason: string } }}
+ */
+function readExistingSettings(settingsPath) {
+  if (!existsSync(settingsPath)) return { existing: null };
+  if (!isRegularFile(settingsPath)) {
+    process.stderr.write(
+      `peaks install-skills: refusing to overwrite non-regular settings.json at ${settingsPath}\n`
+    );
+    return { refusal: { skipped: true, reason: 'settings.json is not a regular file' } };
+  }
+  try {
+    const parsed = JSON.parse(
+      readFileSafely(settingsPath, 'Claude settings.json path changed during read')
+    );
+    if (!isPlainObject(parsed)) {
+      process.stderr.write(
+        `peaks install-skills: refusing to overwrite settings.json that is not a JSON object at ${settingsPath}\n`
+      );
+      return { refusal: { skipped: true, reason: 'settings.json is not a JSON object' } };
+    }
+    return { existing: parsed };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(
+      `peaks install-skills: failed to parse settings.json at ${settingsPath}: ${message}; leaving untouched\n`
+    );
+    return { refusal: { skipped: true, reason: 'settings.json parse error' } };
+  }
+}
+
+/**
+ * The atomic write, with the same soft-fail shape as the read: the refusal is RETURNED
+ * rather than thrown, and the message is written here so both callers cannot drift.
+ *
+ * @param {string} settingsPath
+ * @param {string} nextJson
+ * @returns {string | null} the error message on failure, `null` on success
+ */
+function writeSettingsAtomically(settingsPath, nextJson) {
+  try {
+    writeFileAtomically(
+      settingsPath,
+      nextJson,
+      'Claude settings.json path changed during write',
+      () => {
+        if (existsSync(settingsPath) && !isRegularFile(settingsPath)) {
+          throw new Error('Claude settings.json path is not a regular file');
+        }
+      }
+    );
+    return null;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(
+      `peaks install-skills: failed to write settings.json at ${settingsPath}: ${message}\n`
+    );
+    return message;
+  }
+}
+
+export function installBundledOutputStyleDefault(options = {}) {
+  if (
+    process.env.PEAKS_SKIP_SKILL_INSTALL === '1' ||
+    process.env.PEAKS_SKIP_OUTPUT_STYLE_DEFAULT === '1'
+  ) {
+    return { skipped: true, reason: 'PEAKS_SKIP_OUTPUT_STYLE_DEFAULT=1' };
+  }
+
+  const bundledStylesDir = resolve(
+    options.targetRoot ??
+      process.env.PEAKS_CLAUDE_OUTPUT_STYLES_DIR ??
+      join(homedir(), '.claude', 'output-styles')
+  );
+  const settingsPath = resolveSettingsFilePath(options);
+  const bundledStyleName = 'peaks-skill-swarm.md';
+  const bundledStylePath = join(bundledStylesDir, bundledStyleName);
+
+  const read = readExistingSettings(settingsPath);
+  if (read.refusal !== undefined) return read.refusal;
+  const existing = read.existing;
+
+  // Pre-condition: the bundled style file must be present in the
+  // dispatched target. If it's not, we MUST NOT inject
+  // `outputStyle: 'peaks-skill-swarm'` — Claude Code would then fail
+  // to load the style and fall back to default anyway, leaving the
+  // user with broken state. Skipping is the safe default.
+  if (!existsSync(bundledStylePath)) {
+    return { skipped: true, reason: `bundled output style not present at ${bundledStylePath}` };
+  }
+
+  // User-authored outputStyle wins — never overwrite.
+  if (
+    existing !== null &&
+    typeof existing.outputStyle === 'string' &&
+    existing.outputStyle.length > 0
+  ) {
+    return {
+      skipped: true,
+      reason: `user-defined outputStyle already set: ${existing.outputStyle}`
+    };
+  }
+
+  const next =
+    existing === null
+      ? { outputStyle: 'peaks-skill-swarm' }
+      : { ...existing, outputStyle: 'peaks-skill-swarm' };
+
+  const existingJson = existing === null ? null : `${JSON.stringify(existing, null, 2)}\n`;
+  const nextJson = `${JSON.stringify(next, null, 2)}\n`;
+  if (existingJson === nextJson) {
+    return { skipped: true, reason: 'no change' };
+  }
+
+  const writeError = writeSettingsAtomically(settingsPath, nextJson);
+  if (writeError !== null) return { skipped: true, reason: 'write error', error: writeError };
+
+  return {
+    installed: true,
+    created: existing === null,
+    updated: existing !== null,
+    settingsPath,
+    outputStyle: 'peaks-skill-swarm'
+  };
+}