peaks-loop 4.1.1 → 4.1.3

package/scripts/install-skills-ide.mjs

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

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

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

package/scripts/install-skills-output-styles.mjs

@@ -0,0 +1,121 @@
+// scripts/install-skills-output-styles.mjs
+//
+// The output-style install: the style FILES, reconciled into the one IDE directory that
+// reads them. Single-target on purpose — the DISPATCH STRATEGY note below is the reason,
+// and the other two dispatch paths are named there for the comparison.
+//
+// Split out of `scripts/install-skills.mjs` (rid-043). Every line below was moved
+// VERBATIM from that file; only this header, the import block, and the `export`
+// keyword on names a sibling imports are new.
+
+import { existsSync, lstatSync, mkdirSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { reconcileCanonicalFileEntry } from './canonical-store-link.mjs';
+import { pruneBundledEntries } from './canonical-store-prune.mjs';
+import { createInstallRootValidator, resolvePackageRoot } from './install-skills-fs.mjs';
+import { createInstallResult } from './install-skills-report.mjs';
+import { resolveBundleTargetRoot } from './install-skills-ide.mjs';
+
+/**
+ * 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 the other two families,
+  // resolved by the same helper (`resolveBundleTargetRoot`).
+  const targetRoot = resolveBundleTargetRoot(options, {
+    profileField: 'outputStylesDir',
+    envVar: 'PEAKS_CLAUDE_OUTPUT_STYLES_DIR',
+    fallback: '.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 };
+}

package/scripts/install-skills-report.mjs

@@ -0,0 +1,42 @@
+// scripts/install-skills-report.mjs
+//
+// A fallback is not a failure but must not LOOK like one, and a `skipped` entry is a
+// half migration that must not be invisible. Both are reported here, and the shared
+// empty result shape lives beside them.
+//
+// Split out of `scripts/install-skills.mjs` (rid-043). Every line below was moved
+// VERBATIM from that file; only this header, the import block, and the `export`
+// keyword on names a sibling imports are new.
+
+export function createInstallResult() {
+  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.
+ */
+export 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.
+ */
+export 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`
+  );
+}