peaks-loop 4.1.1 → 4.1.3

package/scripts/install-skills.mjs

@@ -1,1283 +1,41 @@
-#!/usr/bin/env node
-import {
-  closeSync,
-  constants,
-  existsSync,
-  fchmodSync,
-  fstatSync,
-  lstatSync,
-  mkdirSync,
-  openSync,
-  readFileSync,
-  readlinkSync,
-  realpathSync,
-  readdirSync,
-  renameSync,
-  symlinkSync,
-  unlinkSync,
-  writeFileSync
-} from 'node:fs';
-import { createHash, 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 { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-function getPathStats(path) {
-  try {
-    return lstatSync(path);
-  } catch {
-    return null;
-  }
-}
-
-function isBrokenSymlink(stats, targetPath) {
-  return stats.isSymbolicLink() && !existsSync(targetPath);
-}
-
-function validateManagedMarkerPath(markerPath) {
-  const markerStats = getPathStats(markerPath);
-  if (!markerStats) return;
-  if (markerStats.isSymbolicLink()) {
-    throw new Error('Peaks managed marker path must not be a symlink');
-  }
-  if (!markerStats.isFile()) {
-    throw new Error('Peaks managed marker path must be a file');
-  }
-  if (markerStats.nlink !== 1) {
-    throw new Error('Peaks managed marker path must not be hardlinked');
-  }
-}
-
-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 createFileIdentity(path) {
-  const stats = lstatSync(path);
-  if (!stats.isFile() || stats.isSymbolicLink() || stats.nlink !== 1) {
-    return null;
-  }
-  return { dev: stats.dev, ino: stats.ino };
-}
-
-function isSameFileIdentity(path, identity) {
-  if (identity === null) return false;
-  const stats = getPathStats(path);
-  return Boolean(
-    stats?.isFile() &&
-    !stats.isSymbolicLink() &&
-    stats.nlink === 1 &&
-    stats.dev === identity.dev &&
-    stats.ino === identity.ino
-  );
-}
-
-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 getManagedTarget(targetPath) {
-  const markerPath = `${targetPath}.peaks-managed`;
-  validateManagedMarkerPath(markerPath);
-  if (!existsSync(markerPath)) {
-    return null;
-  }
-  return readFileSafely(markerPath, 'Peaks managed marker path changed during read').trim();
-}
-
-function markManagedPeaksLink(targetPath, sourcePath) {
-  const markerPath = `${targetPath}.peaks-managed`;
-  validateManagedMarkerPath(markerPath);
-  writeFileAtomically(
-    markerPath,
-    `${sourcePath}\n`,
-    'Peaks managed marker path changed during write',
-    () => validateManagedMarkerPath(markerPath)
-  );
-}
-
-function readPackageSourceFile(path) {
-  const stats = lstatSync(path);
-  if (!stats.isFile() || stats.isSymbolicLink()) {
-    throw new Error('Peaks package source path must be a file');
-  }
-  return readFileSync(path, 'utf8');
-}
-
-function hashContent(content) {
-  return createHash('sha256').update(content).digest('hex');
-}
-
-function hashFileContent(path) {
-  return hashContent(readFileSafely(path, 'Peaks managed file path changed during read'));
-}
-
-function createManagedOutputStyleMarker(sourcePath, outputStyleName) {
-  const content = readPackageSourceFile(sourcePath);
-  return `${JSON.stringify({ version: 1, kind: 'output-style', outputStyleName, sourcePath, contentSha256: hashContent(content) })}\n`;
-}
-
-function parseManagedOutputStyleMarker(managedTarget) {
-  if (managedTarget === null) return null;
-  try {
-    const marker = JSON.parse(managedTarget);
-    if (
-      marker?.version !== 1 ||
-      marker?.kind !== 'output-style' ||
-      typeof marker.outputStyleName !== 'string' ||
-      typeof marker.sourcePath !== 'string' ||
-      typeof marker.contentSha256 !== 'string'
-    ) {
-      return null;
-    }
-    return marker;
-  } catch {
-    return null;
-  }
-}
-
-function isTrustedOutputStyleSource(marker, sourcePath, outputStyleName) {
-  return (
-    marker.outputStyleName === outputStyleName &&
-    resolve(marker.sourcePath) === resolve(sourcePath) &&
-    basename(resolve(marker.sourcePath)) === outputStyleName
-  );
-}
-
-function getManagedPeaksOutputStyleIdentity(
-  managedTarget,
-  targetPath,
-  sourcePath,
-  outputStyleName
-) {
-  const marker = parseManagedOutputStyleMarker(managedTarget);
-  const sourceHash = hashContent(readPackageSourceFile(sourcePath));
-  if (
-    marker === null ||
-    !isTrustedOutputStyleSource(marker, sourcePath, outputStyleName) ||
-    !existsSync(targetPath) ||
-    hashFileContent(targetPath) !== sourceHash ||
-    marker.contentSha256 !== sourceHash
-  ) {
-    return null;
-  }
-  return createFileIdentity(targetPath);
-}
-
-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: [] };
-}
-
-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 writeFileExclusively(path, content, errorMessage, validateBeforeWrite) {
-  validateBeforeWrite();
-  let fd = openSync(path, getSafeTempOpenFlags(), 0o600);
-  let closeError = null;
-  let identity = null;
-  try {
-    validateOpenFile(fd, path, errorMessage);
-    validateBeforeWrite();
-    validateOpenFile(fd, path, errorMessage);
-    identity = createFileIdentity(path);
-    if (identity === null) {
-      throw new Error(errorMessage);
-    }
-    fchmodSync(fd, 0o600);
-    writeFileSync(fd, content, 'utf8');
-    const writeFd = fd;
-    fd = null;
-    closeSync(writeFd);
-    return identity;
-  } finally {
-    if (fd !== null) {
-      try {
-        closeSync(fd);
-      } catch (error) {
-        closeError = error;
-      }
-    }
-    if (closeError) {
-      throw closeError;
-    }
-  }
-}
-
-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);
-
-  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');
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 
-  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);
-
-    const current = getPathStats(targetPath);
-    if (current) {
-      const managedTarget = getManagedTarget(targetPath);
-      const linkTarget = current.isSymbolicLink() ? readlinkSync(targetPath) : null;
-      const linkTargetExists = typeof linkTarget === 'string' && existsSync(linkTarget);
-      if (linkTarget === sourcePath && linkTargetExists) {
-        installed.push(skillName);
-        continue;
-      }
-      // Managed Junctions may point into an ephemeral host worktree. If that
-      // worktree was removed, Windows keeps the Junction entry but its target
-      // no longer resolves. Repair only when reconciliation was explicitly
-      // requested; normal postinstall keeps its existing ownership behavior.
-      if (
-        (current.isSymbolicLink() || isBrokenSymlink(current, targetPath)) &&
-        (managedTarget === linkTarget ||
-          (options.reconcileJunctions === true && managedTarget !== null && !linkTargetExists))
-      ) {
-        validateSkillsRoot();
-        unlinkSync(targetPath);
-        validateSkillsRoot();
-        unlinkSync(`${targetPath}.peaks-managed`);
-      } else {
-        skipped.push(skillName);
-        continue;
-      }
-    }
-
-    validateSkillsRoot();
-    symlinkSync(sourcePath, targetPath, process.platform === 'win32' ? 'junction' : 'dir');
-    try {
-      validateSkillsRoot();
-      markManagedPeaksLink(targetPath, sourcePath);
-    } catch (error) {
-      validateSkillsRoot();
-      const created = getPathStats(targetPath);
-      if (created?.isSymbolicLink() && readlinkSync(targetPath) === sourcePath) {
-        unlinkSync(targetPath);
-      }
-      throw error;
-    }
-    installed.push(skillName);
-  }
-
-  return { installed, skipped };
-}
-
-/**
- * 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 = [];
-  mkdirSync(targetRoot, { recursive: true });
-  const validateOutputStylesRoot = createInstallRootValidator(targetRoot, 'Peaks output styles');
-
-  for (const outputStyleName of readdirSync(outputStylesRoot)) {
-    const sourcePath = join(outputStylesRoot, outputStyleName);
-    const targetPath = join(targetRoot, outputStyleName);
-
-    if (!lstatSync(sourcePath).isFile() || !outputStyleName.endsWith('.md')) {
-      continue;
-    }
-
-    const current = getPathStats(targetPath);
-    if (current) {
-      const managedTarget = getManagedTarget(targetPath);
-      const managedTargetIdentity = getManagedPeaksOutputStyleIdentity(
-        managedTarget,
-        targetPath,
-        sourcePath,
-        outputStyleName
-      );
-      if (isSameFileIdentity(targetPath, managedTargetIdentity)) {
-        validateOutputStylesRoot();
-        if (!isSameFileIdentity(targetPath, managedTargetIdentity)) {
-          throw new Error('Peaks output style path changed during unlink');
-        }
-        unlinkSync(targetPath);
-        validateOutputStylesRoot();
-        unlinkSync(`${targetPath}.peaks-managed`);
-      } else {
-        skipped.push(outputStyleName);
-        continue;
-      }
-    }
-
-    const markerPath = `${targetPath}.peaks-managed`;
-    validateManagedMarkerPath(markerPath);
-    if (!current && existsSync(markerPath)) {
-      validateOutputStylesRoot();
-      unlinkSync(markerPath);
-    }
-    const createdTargetIdentity = writeFileExclusively(
-      targetPath,
-      readPackageSourceFile(sourcePath),
-      'Peaks output style path changed during write',
-      validateOutputStylesRoot
-    );
-    try {
-      writeFileExclusively(
-        markerPath,
-        createManagedOutputStyleMarker(sourcePath, outputStyleName),
-        'Peaks managed marker path changed during write',
-        () => {
-          validateOutputStylesRoot();
-          validateManagedMarkerPath(markerPath);
-        }
-      );
-    } catch (error) {
-      validateOutputStylesRoot();
-      if (isSameFileIdentity(targetPath, createdTargetIdentity)) {
-        unlinkSync(targetPath);
-      }
-      throw error;
-    }
-    installed.push(outputStyleName);
-  }
-
-  return { installed, skipped };
-}
-
-/**
- * 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).
- *
- * Mirrors `installBundledOutputStyles` but writes to
- * `~/.claude/agents/` (Claude Code's sub-agent loader directory). Each
- * agent file ships under `agents/*.md` in the peaks-loop tarball and is
- * copied on `npm i -g peaks-loop@latest` with content-hash drift detection
- * via a `.peaks-managed` marker (SHA-256 of the source content).
- *
- * Drift policy (mirrors output-styles):
- *   - file missing, marker missing       → install (write file + marker)
- *   - file missing, marker present       → install (replace stale marker)
- *   - file present, marker present,
- *     SHA matches, sourcePath matches    → skip (idempotent re-install)
- *   - file present, marker present,
- *     SHA matches, sourcePath differs    → skip (stale package path;
- *                                            preserve user's local file)
- *   - file present, marker present,
- *     SHA differs                        → overwrite (package upgrade)
- *   - file present, no marker            → skip (user-authored file;
- *                                            preserve)
- */
-function createManagedAgentMarker(sourcePath, agentName) {
-  const content = readPackageSourceFile(sourcePath);
-  return `${JSON.stringify({ version: 1, kind: 'agent', agentName, sourcePath, contentSha256: hashContent(content) })}\n`;
-}
-
-function parseManagedAgentMarker(managedTarget) {
-  if (managedTarget === null) return null;
-  try {
-    const marker = JSON.parse(managedTarget);
-    if (
-      marker?.version !== 1 ||
-      marker?.kind !== 'agent' ||
-      typeof marker.agentName !== 'string' ||
-      typeof marker.sourcePath !== 'string' ||
-      typeof marker.contentSha256 !== 'string'
-    ) {
-      return null;
-    }
-    return marker;
-  } catch {
-    return null;
-  }
-}
-
-function isTrustedAgentSource(marker, sourcePath, agentName) {
-  return (
-    marker.agentName === agentName &&
-    resolve(marker.sourcePath) === resolve(sourcePath) &&
-    basename(resolve(marker.sourcePath)) === agentName
-  );
-}
-
-function getManagedPeaksAgentIdentity(managedTarget, targetPath, sourcePath, agentName) {
-  const marker = parseManagedAgentMarker(managedTarget);
-  const sourceHash = hashContent(readPackageSourceFile(sourcePath));
-  if (
-    marker === null ||
-    !isTrustedAgentSource(marker, sourcePath, agentName) ||
-    !existsSync(targetPath) ||
-    hashFileContent(targetPath) !== sourceHash ||
-    marker.contentSha256 !== sourceHash
-  ) {
-    return null;
-  }
-  return createFileIdentity(targetPath);
-}
-
-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 = [];
-  mkdirSync(targetRoot, { recursive: true });
-  const validateAgentsRoot = createInstallRootValidator(targetRoot, 'Peaks agents');
-
-  for (const agentFileName of readdirSync(agentsRoot)) {
-    const sourcePath = join(agentsRoot, agentFileName);
-    const targetPath = join(targetRoot, agentFileName);
-
-    if (!lstatSync(sourcePath).isFile() || !agentFileName.endsWith('.md')) {
-      continue;
-    }
-
-    const current = getPathStats(targetPath);
-    if (current) {
-      const managedTarget = getManagedTarget(targetPath);
-      const managedTargetIdentity = getManagedPeaksAgentIdentity(
-        managedTarget,
-        targetPath,
-        sourcePath,
-        agentFileName
-      );
-      if (isSameFileIdentity(targetPath, managedTargetIdentity)) {
-        validateAgentsRoot();
-        if (!isSameFileIdentity(targetPath, managedTargetIdentity)) {
-          throw new Error('Peaks agent path changed during unlink');
-        }
-        unlinkSync(targetPath);
-        validateAgentsRoot();
-        unlinkSync(`${targetPath}.peaks-managed`);
-      } else {
-        skipped.push(agentFileName);
-        continue;
-      }
-    }
-
-    const markerPath = `${targetPath}.peaks-managed`;
-    validateManagedMarkerPath(markerPath);
-    if (!current && existsSync(markerPath)) {
-      validateAgentsRoot();
-      unlinkSync(markerPath);
-    }
-    const createdTargetIdentity = writeFileExclusively(
-      targetPath,
-      readPackageSourceFile(sourcePath),
-      'Peaks agent path changed during write',
-      validateAgentsRoot
-    );
-    try {
-      writeFileExclusively(
-        markerPath,
-        createManagedAgentMarker(sourcePath, agentFileName),
-        'Peaks managed marker path changed during write',
-        () => {
-          validateAgentsRoot();
-          validateManagedMarkerPath(markerPath);
-        }
-      );
-    } catch (error) {
-      validateAgentsRoot();
-      if (isSameFileIdentity(targetPath, createdTargetIdentity)) {
-        unlinkSync(targetPath);
-      }
-      throw error;
-    }
-    installed.push(agentFileName);
-  }
-
-  return { installed, skipped };
-}
+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
@@ -1320,11 +78,14 @@ export function installBundledAgentsForAllPlatforms(options = {}) {
             ? { ...options, ideId, targetRoot: options.targetRoot }
             : { ...options, ideId };
       const result = installBundledAgents(platformOpts);
+      reportCopyFallbacks(`agents in ${profile.agentsDir}`, result.fallbacks);
+      reportLeftAlone(`agents in ${profile.agentsDir}`, result.skipped);
       perPlatform.push({
         ideId,
         agentsDir: profile.agentsDir,
         installed: result.installed,
-        skipped: result.skipped
+        skipped: result.skipped,
+        fallbacks: result.fallbacks
       });
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -1465,6 +226,7 @@ if (
         `Peaks output styles skipped because local files already exist: ${outputStylesResult.skipped.join(', ')}\n`
       );
     }
+    reportCopyFallbacks('output styles', outputStylesResult.fallbacks);
 
     // Slice 2026-08-02 — auto-register bundled output style.
     //