peaks-loop 4.1.2 → 4.1.3

package/scripts/install-skills.mjs

@@ -1,1071 +1,41 @@
-#!/usr/bin/env node
-import {
-  closeSync,
-  constants,
-  existsSync,
-  fchmodSync,
-  fstatSync,
-  lstatSync,
-  mkdirSync,
-  openSync,
-  readFileSync,
-  realpathSync,
-  readdirSync,
-  renameSync,
-  unlinkSync,
-  writeFileSync
-} from 'node:fs';
-import { randomUUID } from 'node:crypto';
+// scripts/install-skills.mjs
+//
+// The npm postinstall entry. What stays HERE, and why it cannot move:
+//
+//   1. The two per-platform fan-outs. Their `ideId === 'claude-code'` branches are the
+//      env-var override the 1.x-compat contract is written on, and they are pinned BY
+//      FILE NAME by `tests/unit/runtime/vendor-neutral-identity-guard.test.ts` — moving
+//      them would either drop a pinned decision or add one to a file the ratchet does
+//      not know about. Their bodies are unchanged.
+//   2. The CLI entry block. It identifies its own path (`import.meta.url` against
+//      `process.argv[1]`), which is exactly what the module's own location means, so it
+//      cannot live anywhere else.
+//
+// Everything else moved to a sibling by responsibility; the public surface below is a
+// re-export, so no importer changes.
+//
 import { homedir } from 'node:os';
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-// The canonical store — `~/.peaks/{skills,agents,output-styles}`. Skills are
-// linked to it instead of to `<packageRoot>/skills/<name>`; see the loop in
-// `installBundledSkills` for why the target moved and why repair is now
-// unconditional. `canonical-store-link.mjs` is the same contract for the two
-// families whose entry is a single FILE rather than a tree, and it is where the
-// "the symlink was refused, here is the report" fallback lives. MUST both stay in
-// `package.json#files`: this file IS the npm postinstall, and an unpublished
-// sibling import breaks every user's install.
-import { reconcileCanonicalEntry } from './canonical-store.mjs';
-import { reconcileCanonicalFileEntry } from './canonical-store-link.mjs';
-import { pruneBundledEntries } from './canonical-store-prune.mjs';
-
-function getPathStats(path) {
-  try {
-    return lstatSync(path);
-  } catch {
-    return null;
-  }
-}
-
-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`);
-  }
-}
-
-function getSafeReadOpenFlags() {
-  return typeof constants.O_NOFOLLOW === 'number'
-    ? constants.O_RDONLY | constants.O_NOFOLLOW
-    : constants.O_RDONLY;
-}
-
-function readFileSafely(path, errorMessage) {
-  const fd = openSync(path, getSafeReadOpenFlags());
-  try {
-    validateOpenFile(fd, path, errorMessage);
-    return readFileSync(fd, 'utf8');
-  } finally {
-    closeSync(fd);
-  }
-}
-
-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;
-}
-
-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`);
-    }
-  };
-}
-
-function createInstallResult() {
-  return { installed: [], skipped: [], pruned: [], fallbacks: [] };
-}
-
-function resolvePackageRoot(options = {}) {
-  return resolve(options.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..'));
-}
-
-function readPackageVersion(packageRoot = resolvePackageRoot()) {
-  const packageJson = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
-  if (typeof packageJson.version !== 'string' || packageJson.version.length === 0) {
-    throw new Error('package.json version must be a non-empty string');
-  }
-
-  return packageJson.version;
-}
-
-function createConfigDefaults(packageRoot) {
-  return {
-    version: readPackageVersion(packageRoot),
-    currentWorkspace: null,
-    workspaces: [],
-    language: 'en',
-    economyMode: true,
-    swarmMode: true,
-    tokens: {},
-    proxy: {}
-  };
-}
-
-function createConfigResult(overrides = {}) {
-  return { created: false, updated: false, skipped: false, ...overrides };
-}
-
-function isInsidePath(childPath, parentPath) {
-  const relativePath = relative(parentPath, childPath);
-  return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
-}
-
-function isPlainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
-function mergeMissingConfigValues(existing, defaults) {
-  return Object.entries(defaults).reduce(
-    (next, [key, defaultValue]) => {
-      if (!(key in next)) {
-        return { ...next, [key]: defaultValue };
-      }
-
-      const existingValue = next[key];
-      if (isPlainObject(existingValue) && isPlainObject(defaultValue)) {
-        return { ...next, [key]: mergeMissingConfigValues(existingValue, defaultValue) };
-      }
-
-      return next;
-    },
-    { ...existing }
-  );
-}
-
-function readConfigFile(configPath, label) {
-  if (!existsSync(configPath)) {
-    return null;
-  }
-
-  try {
-    const parsed = JSON.parse(
-      readFileSafely(configPath, `${label} config path changed during read`)
-    );
-    if (!isPlainObject(parsed)) {
-      throw new Error(`${label} config must contain a JSON object`);
-    }
-
-    return parsed;
-  } catch (error) {
-    const message =
-      error instanceof SyntaxError
-        ? `${label} config must contain valid JSON`
-        : error instanceof Error
-          ? error.message
-          : String(error);
-    throw new Error(message);
-  }
-}
-
-function validateConfigPath(root, peaksRoot, configPath, label) {
-  const rootReal = realpathSync(root);
-  const peaksStats = lstatSync(peaksRoot);
-  const peaksReal = realpathSync(peaksRoot);
-  if (
-    !peaksStats.isDirectory() ||
-    peaksStats.isSymbolicLink() ||
-    peaksReal !== resolve(rootReal, '.peaks')
-  ) {
-    throw new Error(`${label} config path must stay inside the ${label.toLowerCase()} root`);
-  }
-
-  const configStats = getPathStats(configPath);
-  if (configStats?.isSymbolicLink()) {
-    throw new Error(`${label} config path must not be a symlink`);
-  }
-  if (configStats && !configStats.isFile()) {
-    throw new Error(`${label} config path must be a file`);
-  }
-  if (configStats) {
-    if (configStats.nlink !== 1) {
-      throw new Error(`${label} config path must not be hardlinked`);
-    }
-    const configReal = realpathSync(configPath);
-    if (!isInsidePath(configReal, rootReal) || !isInsidePath(configReal, peaksReal)) {
-      throw new Error(`${label} config path must stay inside the ${label.toLowerCase()} root`);
-    }
-  }
-}
-
-function validateUserConfigPaths(userRoot, peaksRoot, configPath) {
-  validateConfigPath(userRoot, peaksRoot, configPath, 'User');
-}
-
-function getSafeTempOpenFlags() {
-  const baseFlags = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL;
-  return typeof constants.O_NOFOLLOW === 'number' ? baseFlags | constants.O_NOFOLLOW : baseFlags;
-}
-
-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;
-      }
-    }
-  }
-}
-
-function writeUserConfig(userRoot, peaksRoot, configPath, content) {
-  writeFileAtomically(configPath, content, 'User config path changed during write', () =>
-    validateUserConfigPaths(userRoot, peaksRoot, configPath)
-  );
-}
-
-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'
-  }
-};
-
-function detectInstalledIdeId(projectRoot) {
-  if (!projectRoot) return null;
-  for (const { id, dir } of IDE_DETECTION_DIRS) {
-    if (existsSync(join(projectRoot, dir))) {
-      return id;
-    }
-  }
-  return null;
-}
-
-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.
- */
-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));
-}
-
-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`
-  );
-}
-
-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`
-  );
-}
-
-function writeMergedConfig(configPath, label, defaults, writeConfig) {
-  const existing = readConfigFile(configPath, label);
-  const next = {
-    ...(existing === null ? defaults : mergeMissingConfigValues(existing, defaults)),
-    version: defaults.version
-  };
-  const currentJson = existing === null ? null : `${JSON.stringify(existing, null, 2)}\n`;
-  const nextJson = `${JSON.stringify(next, null, 2)}\n`;
-
-  if (currentJson === nextJson) {
-    return createConfigResult();
-  }
-
-  writeConfig(nextJson);
-  return createConfigResult(existing === null ? { created: true } : { updated: true });
-}
-
-export function installUserConfig(options = {}) {
-  if (
-    process.env.PEAKS_SKIP_SKILL_INSTALL === '1' ||
-    process.env.PEAKS_SKIP_USER_CONFIG_INSTALL === '1'
-  ) {
-    return createConfigResult({ skipped: true });
-  }
-
-  const userRoot = resolve(options.userRoot ?? homedir());
-  const peaksRoot = resolve(userRoot, '.peaks');
-  const configPath = resolve(peaksRoot, 'config.json');
-  if (!isInsidePath(configPath, userRoot)) {
-    throw new Error('User config path must stay inside the user root');
-  }
-
-  if (!existsSync(peaksRoot)) {
-    mkdirSync(peaksRoot, { recursive: true });
-  }
-  validateUserConfigPaths(userRoot, peaksRoot, configPath);
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
-  return writeMergedConfig(
-    configPath,
-    'User',
-    createConfigDefaults(options.packageRoot),
-    (content) => writeUserConfig(userRoot, peaksRoot, configPath, content)
-  );
-}
-
-/*
- * D11 (2026-09-15): `installProjectConfig` — plus its two private helpers
- * `writeProjectConfig` and `validateProjectConfigPaths` — was DELETED here.
- *
- * It was dead: definition + `export`, and zero call sites in the whole repo
- * (verified by a repo-wide grep for the identifier, excluding node_modules
- * and dist). The `PEAKS_SKIP_PROJECT_CONFIG_INSTALL` env var existed only to
- * disable it.
- *
- * Deleted rather than wired, because wiring it would be the bigger defect:
- * `npm i -g peaks-loop` executed from inside a user's repo would write
- * `<project>/.peaks/config.json` as a side effect of a GLOBAL install. The
- * project-level config is owned by `peaks workspace init` and the config
- * service at runtime; a postinstall reaching into the current working
- * directory to create project state is the opposite of the "minimal user
- * operation" tenet — an operation the user never asked for.
- *
- * The user-config sibling (`installUserConfig`, below) is live and is what
- * the postinstall actually calls.
- */
-
-export function installBundledSkills(options = {}) {
-  const packageRoot = resolvePackageRoot(options);
-  const skillsRoot = join(packageRoot, 'skills');
-
-  if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || !existsSync(skillsRoot)) {
-    return createInstallResult();
-  }
-
-  // Slice #011: IDE-aware dispatch. Precedence (highest first):
-  //   1. explicit options.targetRoot            (test / hook override)
-  //   2. options.ideId skillInstall.skillsDir   (per-IDE dispatch)
-  //   3. PEAKS_CLAUDE_SKILLS_DIR env var        (legacy back-compat)
-  //   4. detected IDE's skillInstall.skillsDir  (auto-detect from projectRoot)
-  //   5. legacy default (~/.claude/skills)      (no-IDE fallback)
-  const projectRoot = resolveProjectRoot(options);
-  const detectedIdeId = detectInstalledIdeId(projectRoot);
-  const detectedProfile = resolveIdeSkillInstallProfile(detectedIdeId);
-
-  if (
-    options.targetRoot === undefined &&
-    options.ideId === undefined &&
-    detectedProfile === null &&
-    detectedIdeId !== null
-  ) {
-    warnUnverifiedIde(detectedIdeId, projectRoot ?? '(project root unknown)');
-  }
-  if (
-    options.targetRoot === undefined &&
-    options.ideId === undefined &&
-    detectedIdeId === null &&
-    projectRoot !== null
-  ) {
-    warnNoIdeDetected(projectRoot);
-  }
-
-  const profileSkillsDir = detectedProfile?.skillsDir ?? null;
-  const targetRoot = resolve(
-    options.targetRoot ??
-      (options.ideId !== undefined
-        ? (resolveIdeSkillInstallProfile(options.ideId)?.skillsDir ?? null)
-        : null) ??
-      process.env.PEAKS_CLAUDE_SKILLS_DIR ??
-      profileSkillsDir ??
-      join(homedir(), '.claude', 'skills')
-  );
-
-  const installed = [];
-  const skipped = [];
-  mkdirSync(targetRoot, { recursive: true });
-  const validateSkillsRoot = createInstallRootValidator(targetRoot, 'Peaks skills');
-
-  // After the v2.13.0 bee-demote (commit de0872b), the role skills
-  // (peaks-prd, peaks-rd, peaks-qa, peaks-ui, peaks-sc, peaks-txt)
-  // moved under `skills/bee/<role>/` while user-facing helpers stayed
-  // at `skills/<name>/`. Build the install candidate list by walking
-  // top-level entries (user-facing helpers) AND `skills/bee/<role>`
-  // (demoted role skills). Each candidate is installed under its
-  // basename so the postinstall links `~/.claude/skills/peaks-rd`
-  // to `skills/bee/peaks-rd` (rather than `skills/bee`).
-  const beeRoot = join(skillsRoot, 'bee');
-  /** @type {Array<{ skillName: string, sourcePath: string }>} */
-  const candidates = [];
-  for (const skillName of readdirSync(skillsRoot)) {
-    if (skillName === 'bee') continue;
-    const sourcePath = join(skillsRoot, skillName);
-    const skillFile = join(sourcePath, 'SKILL.md');
-    if (!lstatSync(sourcePath).isDirectory() || !existsSync(skillFile)) continue;
-    candidates.push({ skillName, sourcePath });
-  }
-  if (existsSync(beeRoot) && lstatSync(beeRoot).isDirectory()) {
-    for (const skillName of readdirSync(beeRoot)) {
-      const sourcePath = join(beeRoot, skillName);
-      const skillFile = join(sourcePath, 'SKILL.md');
-      if (!lstatSync(sourcePath).isDirectory() || !existsSync(skillFile)) continue;
-      // De-dupe: a top-level helper with the same name wins (preserves
-      // the existing install contract for any helper that shares a name
-      // with a demoted role skill, e.g. legacy overlap).
-      if (candidates.some((c) => c.skillName === skillName)) continue;
-      candidates.push({ skillName, sourcePath });
-    }
-  }
-
-  for (const { skillName, sourcePath } of candidates) {
-    const targetPath = join(targetRoot, skillName);
-
-    // Slice 2 (`agents-canonical-store`) — the entry points at the CANONICAL
-    // STORE (`~/.peaks/skills/<name>`), not at `<packageRoot>/skills/<name>`,
-    // because `<packageRoot>` changes on every `npm i -g peaks-loop@latest` and
-    // the links must bind to a PATH peaks-loop owns, not to a VERSION. Repair is
-    // the only behaviour: an entry peaks-loop owns (sidecar matches, or the link
-    // dangles) is relinked onto the store; only a real directory the user authored
-    // is left alone and reported `skipped`. `options.reconcileJunctions` is
-    // therefore READ NOWHERE here — still accepted (`sync-service.ts` forwards it)
-    // so passing it changes nothing, and removing it is a CLI-surface change this
-    // slice does not own.
-    validateSkillsRoot();
-    const reconciled = reconcileCanonicalEntry({
-      kind: 'skills',
-      name: skillName,
-      sourcePath,
-      linkPath: targetPath
-    });
-    validateSkillsRoot();
-
-    if (reconciled.linkAction === 'skipped') {
-      skipped.push(skillName);
-      continue;
-    }
-    installed.push(skillName);
-  }
-
-  // Slice 3 — PRUNE. The loop above only ever ADDS. A skill removed from the
-  // package left its canonical copy, every IDE link and every sidecar on the
-  // user's machine forever, because nothing walked the DESTINATIONS. This does,
-  // and deletes only what `isManagedEntry` proves is ours.
-  const { pruned } = pruneBundledEntries({
-    kind: 'skills',
-    keepNames: candidates.map((candidate) => candidate.skillName),
-    linkDirs: [targetRoot]
-  });
-
-  return { installed, skipped, pruned };
-}
-
-/**
- * DISPATCH STRATEGY — the three paths in this file, and why they differ
- * (D10, written down 2026-09-15).
- *
- * This script installs three kinds of asset, and each one resolves its target
- * by a different rule. That was undocumented and untested; it is now
- * documented here and each rule is stated with its reason.
- *
- *   1. SKILLS  (`installBundledSkillsForAllPlatforms`)
- *      Fan out to every platform the user HAS (`isPlatformPresent`).
- *      Reason: a skill directory is per-tool; the same skill is legitimately
- *      wanted in several tools at once, and peaks cannot know which tool the
- *      user will open next. Fan-out is the tenet; presence is the licence.
- *
- *   2. AGENTS  (`installBundledAgentsForAllPlatforms`)
- *      Fan out to present platforms, INTERSECTED with the profiles that
- *      declare `agentsDir`. Reason: sub-agent loaders are not a universal
- *      concept — only 6 of 10 profiles have one. The intersection is the fan
- *      of (1) with a capability filter, not a third rule.
- *
- *   3. OUTPUT STYLES (`installBundledOutputStyles`, this function)
- *      ONE target: the IDE detected in the project root, else the legacy
- *      `~/.claude/output-styles`. Reason: an output style is not a
- *      per-tool asset — it is registered as THE active style for the
- *      session by writing a single `outputStyle` key into
- *      `~/.claude/settings.json` (`installBundledOutputStyleDefault`). A
- *      second copy in `~/.trae/output-styles` would be a file nothing reads
- *      and a setting no one consults; fanning it out would be storing the
- *      same answer in ten places and reading it from one.
- *
- * So: (1) and (2) share one predicate and differ only by capability; (3) is
- * deliberately single-target, and this comment is the reason the brief asked
- * for. If a future platform needs a different rule, state it here.
- */
-export function installBundledOutputStyles(options = {}) {
-  const packageRoot = resolvePackageRoot(options);
-  const outputStylesRoot = join(packageRoot, 'output-styles');
-
-  if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || !existsSync(outputStylesRoot)) {
-    return createInstallResult();
-  }
-
-  // Slice #011: IDE-aware dispatch. Same precedence as installBundledSkills.
-  const projectRoot = resolveProjectRoot(options);
-  const detectedIdeId = detectInstalledIdeId(projectRoot);
-  const detectedProfile = resolveIdeSkillInstallProfile(detectedIdeId);
-
-  const profileOutputStylesDir = detectedProfile?.outputStylesDir ?? null;
-  const targetRoot = resolve(
-    options.targetRoot ??
-      (options.ideId !== undefined
-        ? (resolveIdeSkillInstallProfile(options.ideId)?.outputStylesDir ?? null)
-        : null) ??
-      process.env.PEAKS_CLAUDE_OUTPUT_STYLES_DIR ??
-      profileOutputStylesDir ??
-      join(homedir(), '.claude', 'output-styles')
-  );
-
-  const installed = [];
-  const skipped = [];
-  const fallbacks = [];
-  mkdirSync(targetRoot, { recursive: true });
-  const validateOutputStylesRoot = createInstallRootValidator(targetRoot, 'Peaks output styles');
-
-  // Slice 4 (`agents-canonical-store`) — same move slice 2 made for skills, with the
-  // one difference the brief calls out: a style is a FILE, so the link is a file
-  // symlink, which Windows only grants with developer mode or Administrator.
-  // `reconcileCanonicalFileEntry` is the whole policy — canonical copy, link, and the
-  // reported fallback to a real copy when the host refuses the link. The loop below
-  // no longer decides ownership, and that is deliberate: the decision it used to make
-  // was `resolve(marker.sourcePath) === resolve(sourcePath)`, a string comparison
-  // against a version-scoped package path that went false forever on the first
-  // upgrade and silently froze the style.
-  const bundledStyleNames = [];
-  for (const outputStyleName of readdirSync(outputStylesRoot)) {
-    const sourcePath = join(outputStylesRoot, outputStyleName);
-    if (!lstatSync(sourcePath).isFile() || !outputStyleName.endsWith('.md')) continue;
-    bundledStyleNames.push(outputStyleName);
-
-    validateOutputStylesRoot();
-    const reconciled = reconcileCanonicalFileEntry({
-      kind: 'output-styles',
-      name: outputStyleName,
-      sourcePath,
-      linkPath: join(targetRoot, outputStyleName),
-      createFileLink: options.createFileLink
-    });
-    validateOutputStylesRoot();
-
-    if (reconciled.linkAction === 'skipped') {
-      skipped.push(outputStyleName);
-      continue;
-    }
-    installed.push(outputStyleName);
-    if (reconciled.fallback !== null) {
-      fallbacks.push({ name: outputStyleName, ...reconciled.fallback });
-    }
-  }
-
-  // The delete half, for the same reason skills have one: the loop above only ever
-  // adds. A style removed from the package used to leave its canonical copy, its IDE
-  // link and both sidecars behind forever.
-  const { pruned } = pruneBundledEntries({
-    kind: 'output-styles',
-    keepNames: bundledStyleNames,
-    linkDirs: [targetRoot]
-  });
-
-  return { installed, skipped, pruned, fallbacks };
-}
-
-/**
- * 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.
- */
-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');
-}
-
-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);
-
-  // Read the existing settings.json (if any) FIRST so a malformed file
-  // surfaces as a parse error (more actionable to the user than the
-  // generic "bundled style not present" message). Malformed JSON is a
-  // user-authored file we MUST NOT clobber — log and skip.
-  let existing = null;
-  if (existsSync(settingsPath)) {
-    const stats = getPathStats(settingsPath);
-    if (!stats || !stats.isFile() || stats.isSymbolicLink() || stats.nlink !== 1) {
-      process.stderr.write(
-        `peaks install-skills: refusing to overwrite non-regular settings.json at ${settingsPath}\n`
-      );
-      return { skipped: true, reason: 'settings.json is not a regular file' };
-    }
-    try {
-      const raw = readFileSafely(settingsPath, 'Claude settings.json path changed during read');
-      const parsed = JSON.parse(raw);
-      if (!isPlainObject(parsed)) {
-        process.stderr.write(
-          `peaks install-skills: refusing to overwrite settings.json that is not a JSON object at ${settingsPath}\n`
-        );
-        return { skipped: true, reason: 'settings.json is not a JSON object' };
-      }
-      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 { skipped: true, reason: 'settings.json parse error' };
-    }
-  }
-
-  // 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' };
-  }
-
-  try {
-    writeFileAtomically(
-      settingsPath,
-      nextJson,
-      'Claude settings.json path changed during write',
-      () => {
-        if (!existsSync(settingsPath)) return;
-        const stats = getPathStats(settingsPath);
-        if (!stats || !stats.isFile() || stats.isSymbolicLink() || stats.nlink !== 1) {
-          throw new Error('Claude settings.json path is not a regular file');
-        }
-      }
-    );
-  } 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 { skipped: true, reason: 'write error', error: message };
-  }
-
-  return {
-    installed: true,
-    created: existing === null,
-    updated: existing !== null,
-    settingsPath,
-    outputStyle: 'peaks-skill-swarm'
-  };
-}
-
-/**
- * Slice 7/7 — bundled agents (Claude Code sub-agent prompts).
- *
- * Writes into the IDE's sub-agent loader directory (`~/.claude/agents/` for Claude
- * Code, and whatever `agentsDir` the detected profile declares). The bytes live in
- * the canonical store (`~/.peaks/agents/<name>`) and the IDE entry is a link to it.
- *
- * Ownership policy — ONE predicate, in `canonical-store-link.mjs::isOwnedFileEntry`,
- * and it is deliberately not a string comparison:
- *   - entry resolves to the canonical copy              → leave it (idempotent run)
- *   - entry is a link we wrote (sidecar agrees, dangles) → relink onto the store
- *   - entry is a real file with OUR sidecar beside it    → re-point it at the store
- *   - entry is a real file with a LEGACY sidecar whose
- *     recorded package path no longer resolves           → same: repair it
- *   - entry is a real file we never wrote (no sidecar)   → skip (user-authored)
- *   - entry is a real file whose sidecar names a path
- *     that STILL resolves                                → skip (a second live install)
- *
- * The two "skip" arms above are the ones the old code got wrong in opposite
- * directions: it skipped whenever the package path merely DIFFERED, which froze
- * every entry on the first upgrade, silently and permanently. See
- * `isOwnedFileEntry` for why a vanished package path is proof of an earlier install.
- */
-export function installBundledAgents(options = {}) {
-  const packageRoot = resolvePackageRoot(options);
-  const agentsRoot = join(packageRoot, 'agents');
-
-  // Per-IDE env-var override (claude-code only today): PEAKS_CLAUDE_AGENTS_DIR.
-  // Universal escape hatch: PEAKS_SKIP_AGENT_INSTALL=1 (parallel to
-  // PEAKS_SKIP_SKILL_INSTALL).
-  if (
-    process.env.PEAKS_SKIP_SKILL_INSTALL === '1' ||
-    process.env.PEAKS_SKIP_AGENT_INSTALL === '1' ||
-    !existsSync(agentsRoot)
-  ) {
-    return createInstallResult();
-  }
-
-  // Slice #011: IDE-aware dispatch. Same precedence as installBundledOutputStyles.
-  const projectRoot = resolveProjectRoot(options);
-  const detectedIdeId = detectInstalledIdeId(projectRoot);
-  const detectedProfile = resolveIdeSkillInstallProfile(detectedIdeId);
-
-  const profileAgentsDir = detectedProfile?.agentsDir ?? null;
-  const targetRoot = resolve(
-    options.targetRoot ??
-      (options.ideId !== undefined
-        ? (resolveIdeSkillInstallProfile(options.ideId)?.agentsDir ?? null)
-        : null) ??
-      process.env.PEAKS_CLAUDE_AGENTS_DIR ??
-      profileAgentsDir ??
-      join(homedir(), '.claude', 'agents')
-  );
-
-  const installed = [];
-  const skipped = [];
-  const fallbacks = [];
-  mkdirSync(targetRoot, { recursive: true });
-  const validateAgentsRoot = createInstallRootValidator(targetRoot, 'Peaks agents');
-
-  // Slice 4 (`agents-canonical-store`) — the canonical store owns the bytes and the
-  // IDE entry points at it. Everything this loop used to decide about ownership is
-  // now `reconcileCanonicalFileEntry`'s, and the reason is the defect the brief
-  // names as this slice's core: the old test was
-  // `resolve(marker.sourcePath) === resolve(sourcePath)`, a STRING comparison against
-  // the package path of the installing version — a path with a node version inside it
-  // (`…\nvm\v24.21.0\node_modules\peaks-loop\agents\…`). It went false the first time
-  // the package moved and stayed false, so the agent silently never updated again.
-  const bundledAgentNames = [];
-  for (const agentFileName of readdirSync(agentsRoot)) {
-    const sourcePath = join(agentsRoot, agentFileName);
-    if (!lstatSync(sourcePath).isFile() || !agentFileName.endsWith('.md')) continue;
-    bundledAgentNames.push(agentFileName);
-
-    validateAgentsRoot();
-    const reconciled = reconcileCanonicalFileEntry({
-      kind: 'agents',
-      name: agentFileName,
-      sourcePath,
-      linkPath: join(targetRoot, agentFileName),
-      createFileLink: options.createFileLink
-    });
-    validateAgentsRoot();
-
-    if (reconciled.linkAction === 'skipped') {
-      skipped.push(agentFileName);
-      continue;
-    }
-    installed.push(agentFileName);
-    if (reconciled.fallback !== null) {
-      fallbacks.push({ name: agentFileName, ...reconciled.fallback });
-    }
-  }
-
-  // The delete half: an agent the package stops shipping used to leave its canonical
-  // copy, its IDE entry and both sidecars on the machine forever.
-  const { pruned } = pruneBundledEntries({
-    kind: 'agents',
-    keepNames: bundledAgentNames,
-    linkDirs: [targetRoot]
-  });
-
-  return { installed, skipped, pruned, fallbacks };
-}
-
-/**
- * A fallback is not a failure — but it must never LOOK like a plain success. The
- * entry is a real copy instead of a link, and the postinstall says so, naming each
- * one. Silence here would be the same shape as the defect this slice fixes: an
- * outcome nobody can observe from the outside.
- */
-function reportCopyFallbacks(label, fallbacks) {
-  if (fallbacks.length === 0) return;
-  process.stderr.write(
-    `Peaks ${label}: ${fallbacks.map((entry) => entry.name).join(', ')} ` +
-      'installed as REAL COPIES because this host refused a symlink ' +
-      `(${fallbacks[0].code ?? 'no code returned'})\n`
-  );
-}
-
-/**
- * The other half of the same rule, for the other bucket. A `skipped` entry means the
- * canonical copy WAS written and the IDE entry was NOT — a half migration. Whatever the
- * cause (a file the user authored, or an entry whose sidecar names a second live
- * installation), it must not be invisible: the whole defect this slice fixes was an
- * outcome nobody could observe from outside.
- */
-function reportLeftAlone(label, skipped) {
-  if (skipped.length === 0) return;
-  process.stderr.write(
-    `Peaks ${label}: left alone, not peaks-loop's to replace: ${skipped.join(', ')}\n`
-  );
-}
+import { installBundledAgents, installBundledSkills } from './install-skills-bundles.mjs';
+import {
+  IDE_SKILL_INSTALL_PROFILES,
+  isPlatformPresent,
+  resolveProjectRoot
+} from './install-skills-ide.mjs';
+import { installBundledOutputStyles } from './install-skills-output-styles.mjs';
+import { installBundledOutputStyleDefault } from './install-skills-output-style-default.mjs';
+import { reportCopyFallbacks, reportLeftAlone } from './install-skills-report.mjs';
+import { createConfigResult, installUserConfig } from './install-skills-user-config.mjs';
+
+// THE PUBLIC SURFACE, re-exported so no importer changes. IDE_DETECTION_DIRS is
+// not read here, so it is re-exported without a local binding.
+export { IDE_DETECTION_DIRS } from './install-skills-ide.mjs';
+export { IDE_SKILL_INSTALL_PROFILES };
+export { installBundledSkills, installBundledAgents };
+export { installUserConfig };
+export { installBundledOutputStyles, installBundledOutputStyleDefault };
 
 /**
  * Per-platform fan-out — iterate the platforms the user HAS and call