@luquimbo/bi-superpowers 3.1.1 → 4.1.0

package/bin/lib/generators/claude-plugin.js

@@ -20,10 +20,12 @@ const {
 } = require('../microsoft-mcp');
 const { parseSkillMetadata, getSkillPurpose } = require('./shared');
 
-// Currently the plugin ships 2 skills, both interactive wizards.
+// Currently the plugin ships 4 skills (bi-start, project-kickoff,
+// pbi-connect, report-design). bi-start is the session-opener that
+// routes to the other three; the rest are specialists.
 // The old reference-skills split is kept as an empty set so that any
 // downstream code that checks `REFERENCE_SKILLS.has(x)` still works.
-const COMMAND_SKILLS = new Set(['project-kickoff', 'pbi-connect']);
+const COMMAND_SKILLS = new Set(['bi-start', 'project-kickoff', 'pbi-connect', 'report-design']);
 
 const REFERENCE_SKILLS = new Set();
 
@@ -38,6 +40,36 @@ function ensureDirectory(directory) {
   }
 }
 
+/**
+ * Recursively copy a directory tree from `source` to `target`.
+ * Follows the Node built-in cp() semantics: overwrites existing files,
+ * preserves directory structure. No-op if source does not exist.
+ *
+ * Used to propagate `references/` and `scripts/` subfolders from
+ * folder-based source skills into the generated plugin so the agent can
+ * load on-demand material and run bundled helper scripts.
+ *
+ * @param {string} source - Source directory (must exist to do anything)
+ * @param {string} target - Target directory (created if missing)
+ */
+function copyDirectory(source, target) {
+  if (!fs.existsSync(source)) {
+    return;
+  }
+  ensureDirectory(target);
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const sourcePath = path.join(source, entry.name);
+    const targetPath = path.join(target, entry.name);
+    if (entry.isDirectory()) {
+      copyDirectory(sourcePath, targetPath);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(sourcePath, targetPath);
+    }
+    // Ignore symlinks / other entry types to match the conservative
+    // behaviour of readSkillDirectory().
+  }
+}
+
 /**
  * Rewrite library references for generated plugin targets.
  *
@@ -92,16 +124,57 @@ function toFrontmatterValue(value) {
   return JSON.stringify(value);
 }
 
+// ---------------------------------------------------------------------------
+// Update-check preamble
+// ---------------------------------------------------------------------------
+// Cross-agent "auto-update" mechanism (see ROADMAP item 4 / gstack pattern).
+// The preamble is prepended to every generated SKILL.md and command Markdown
+// so the agent reading the skill content runs the version check at the top
+// of each conversation, surfaces an update notice if available, and then
+// proceeds with the skill. The check caches for 24h on disk and degrades to
+// no-output on network failure — it must never block the skill invocation.
+//
+// The update-check.js script is shipped alongside each skill's `scripts/`
+// folder at generation time (see copyUpdateCheckScript) so `{skillBundleDir}`
+// resolves correctly regardless of the install path (npm-based `super
+// install` OR Claude Code plugin marketplace).
+
+const UPDATE_CHECK_PREAMBLE = `<!-- bi-superpowers update-check preamble (auto-generated, do not edit) -->
+## ⬆ Update check
+
+Before handling the user's request below, run this command **once per conversation** and interpret the output:
+
+\`\`\`bash
+node "{skillBundleDir}/scripts/update-check.js" --silent-if-uptodate --silent-if-snoozed
+\`\`\`
+
+- Empty output or \`UPTODATE\` — proceed with the skill silently. No message.
+- \`UPDATE_AVAILABLE <installed> <latest>\` — tell the user exactly once this conversation, before diving into the skill:
+  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con \`super upgrade\` (o \`/plugin update bi-superpowers\` en Claude Code) cuando te venga bien."
+
+  Then continue with the skill below.
+- \`SNOOZED <iso>\` — proceed silently.
+
+If the command fails (missing binary, permissions, offline), ignore the error and proceed with the skill. The update check must never block the user's request.
+
+---
+<!-- /bi-superpowers update-check preamble -->
+
+`;
+
 /**
  * Build command markdown with Claude Code frontmatter.
  *
  * @param {Object} skill - Skill definition object
  * @param {string} libraryPrefix - Library prefix used in generated target
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.skipPreamble] - Omit the update-check preamble (tests)
  * @returns {string} Command markdown
  */
-function buildCommandMarkdown(skill, libraryPrefix) {
+function buildCommandMarkdown(skill, libraryPrefix, options = {}) {
   const description = getSkillPurpose(skill.name);
   const content = rewriteLibraryReferences(skill.content, libraryPrefix);
+  const preamble = options.skipPreamble ? '' : UPDATE_CHECK_PREAMBLE;
 
   return `---
 description: ${toFrontmatterValue(description)}
@@ -109,7 +182,7 @@ description: ${toFrontmatterValue(description)}
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/${skill.name}.md instead. -->
 
-${content}`;
+${preamble}${content}`;
 }
 
 /**
@@ -118,10 +191,13 @@ ${content}`;
  * @param {Object} skill - Skill definition object
  * @param {string} version - Package version
  * @param {string} libraryPrefix - Library prefix used in generated target
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.skipPreamble] - Omit the update-check preamble (tests)
  * @returns {string} Skill markdown
  */
-function buildSkillMarkdown(skill, version, libraryPrefix) {
+function buildSkillMarkdown(skill, version, libraryPrefix, options = {}) {
   const content = rewriteLibraryReferences(skill.content, libraryPrefix);
+  const preamble = options.skipPreamble ? '' : UPDATE_CHECK_PREAMBLE;
 
   return `---
 name: ${toFrontmatterValue(skill.name)}
@@ -131,7 +207,29 @@ version: ${toFrontmatterValue(version)}
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/${skill.name}.md instead. -->
 
-${content}`;
+${preamble}${content}`;
+}
+
+/**
+ * Copy bin/commands/update-check.js into each generated skill's scripts/
+ * directory so the preamble's `{skillBundleDir}/scripts/update-check.js`
+ * invocation works under both install paths (npm-based `super install` and
+ * Claude Code plugin marketplace). The file is bundled with the npm tarball
+ * via bin/, so this is purely a generation-time copy into skills/.
+ *
+ * @param {string} packageDir - npm package root (source of the canonical script)
+ * @param {string} targetDir - plugin target root (contains skills/<name>/)
+ * @param {Object[]} skills - Skills to wire the script into
+ */
+function copyUpdateCheckScript(packageDir, targetDir, skills) {
+  if (!packageDir) return;
+  const src = path.join(packageDir, 'bin', 'commands', 'update-check.js');
+  if (!fs.existsSync(src)) return;
+  for (const skill of skills) {
+    const scriptsDir = path.join(targetDir, 'skills', skill.name, 'scripts');
+    ensureDirectory(scriptsDir);
+    fs.copyFileSync(src, path.join(scriptsDir, 'update-check.js'));
+  }
 }
 
 /**
@@ -178,6 +276,25 @@ async function generate(targetDir, skills, options = {}) {
   ensureDirectory(commandsDir);
   ensureDirectory(skillsDir);
 
+  // Pull discoverable metadata from the installed package.json when available
+  // so the generated plugin.json has the same repo/license/keywords/homepage
+  // fields as the published npm package. Falls back to bare identity fields
+  // if options.packageDir is missing (unit tests, detached generation).
+  let pkgMetadata = {};
+  if (options.packageDir) {
+    try {
+      const pkg = require(path.join(options.packageDir, 'package.json'));
+      pkgMetadata = {
+        repository: pkg.repository,
+        homepage: pkg.homepage,
+        license: pkg.license,
+        keywords: Array.isArray(pkg.keywords) ? pkg.keywords : undefined,
+      };
+    } catch (_) {
+      // Package.json unreadable — generate a minimal manifest and move on.
+    }
+  }
+
   const pluginManifest = {
     name: 'bi-superpowers',
     description:
@@ -186,6 +303,10 @@ async function generate(targetDir, skills, options = {}) {
     author: {
       name: 'Lucas Sanchez',
     },
+    ...(pkgMetadata.repository !== undefined ? { repository: pkgMetadata.repository } : {}),
+    ...(pkgMetadata.homepage !== undefined ? { homepage: pkgMetadata.homepage } : {}),
+    ...(pkgMetadata.license !== undefined ? { license: pkgMetadata.license } : {}),
+    ...(pkgMetadata.keywords !== undefined ? { keywords: pkgMetadata.keywords } : {}),
   };
 
   fs.writeFileSync(
@@ -312,6 +433,9 @@ async function generate(targetDir, skills, options = {}) {
   }
 
   // ALL skills → skills/*/SKILL.md (universal, discoverable by all Claude tools)
+  // Folder-based skills additionally get their `references/` and `scripts/`
+  // subfolders copied verbatim so the agent can load on-demand material and
+  // invoke helper scripts bundled with the skill.
   for (const skill of skills) {
     const skillDir = path.join(skillsDir, skill.name);
     ensureDirectory(skillDir);
@@ -319,8 +443,18 @@ async function generate(targetDir, skills, options = {}) {
       path.join(skillDir, 'SKILL.md'),
       buildSkillMarkdown(skill, version, libraryPrefix)
     );
+
+    if (skill.bundleDir) {
+      copyDirectory(path.join(skill.bundleDir, 'references'), path.join(skillDir, 'references'));
+      copyDirectory(path.join(skill.bundleDir, 'scripts'), path.join(skillDir, 'scripts'));
+    }
   }
 
+  // Ship the update-check helper alongside every skill so the SKILL.md
+  // preamble can invoke it via `{skillBundleDir}/scripts/update-check.js`
+  // regardless of install path.
+  copyUpdateCheckScript(options.packageDir, targetDir, skills);
+
   console.log('  ✓ Created Claude Code plugin manifest');
   console.log('  ✓ Created .mcp.json with official Microsoft MCP servers');
   console.log(`  ✓ Created ${commandSkills.length} plugin commands`);
@@ -331,6 +465,10 @@ module.exports = {
   name: 'Claude Code Plugin',
   description: 'Native Claude Code plugin (recommended)',
   generate,
+  buildCommandMarkdown,
+  buildSkillMarkdown,
+  copyUpdateCheckScript,
+  UPDATE_CHECK_PREAMBLE,
   COMMAND_SKILLS,
   REFERENCE_SKILLS,
 };

package/bin/lib/generators/shared.js

@@ -29,12 +29,19 @@ function parseSkillMetadata(content) {
   const titleMatch = content.match(/^#\s+(.+)/m);
   if (titleMatch) metadata.title = titleMatch[1];
 
-  // Get triggers
+  // Get triggers — collect every double-quoted fragment in the Trigger
+  // section. This handles all three shapes our skills use:
+  //   - Bare-quote bullets:    - "connect Power BI", "PBI connection"
+  //   - Prose bullets:         - User mentions: "analizar proyecto", "new project"
+  //   - Asterisk bullets:      * "pattern"
+  // The regex intentionally doesn't anchor to bullet syntax — that's
+  // what broke extraction for project-kickoff (prose) and under-counted
+  // pbi-connect (first quote per bullet only) before this change.
   const triggerSection = content.match(/##\s+Trigger[\s\S]*?(?=##|$)/i);
   if (triggerSection) {
-    const triggers = triggerSection[0].match(/[-*]\s+"([^"]+)"/g);
-    if (triggers) {
-      metadata.triggers = triggers.map((t) => t.replace(/[-*]\s+"/, '').replace('"', ''));
+    const quotedFragments = triggerSection[0].match(/"([^"]+)"/g);
+    if (quotedFragments) {
+      metadata.triggers = quotedFragments.map((t) => t.slice(1, -1));
     }
   }
 
@@ -47,41 +54,29 @@ function parseSkillMetadata(content) {
   return metadata;
 }
 
+/**
+ * Map of skill name → one-line purpose description used in generated
+ * commands/*.md frontmatter and the CLI's `super powers` output.
+ *
+ * Keep this map in lock-step with `src/content/skills/`. Adding a skill
+ * without an entry here makes the generated description fall back to the
+ * generic `'Specialized BI assistance'` string and breaks the parity
+ * test in shared.test.js.
+ */
+const SKILL_PURPOSES = {
+  'bi-start': 'Session opener — environment snapshot, update check, and routing to other skills',
+  'project-kickoff': 'Project analysis and planning',
+  'pbi-connect': 'Power BI Desktop connection',
+  'report-design': '3-page PBIR report generation for Power BI Desktop (Windows)',
+};
+
 /**
  * Get skill purpose description for table
  * @param {string} skillName - Name of the skill
  * @returns {string} Purpose description
  */
 function getSkillPurpose(skillName) {
-  const purposes = {
-    dax: 'DAX writing and optimization',
-    'power-query': 'Power Query / M language patterns',
-    'data-modeling': 'Star schema design',
-    'data-model-design': 'Interactive model builder',
-    'excel-formulas': 'Modern Excel 365 formulas',
-    'project-kickoff': 'Project analysis and planning',
-    'theme-tweaker': 'Power BI theme customization',
-    'rls-design': 'Row-level security design',
-    'query-performance': 'Performance optimization',
-    'data-quality': 'Data validation and profiling',
-    'fabric-scripts': 'Fabric automation scripts',
-    'fast-standard': 'FAST spreadsheet standard',
-    'testing-validation': 'Testing and validation patterns',
-    'pbi-connect': 'Power BI Desktop connection',
-    contributions: 'Contribution validation',
-    // New command skills
-    'dax-doctor': 'DAX debugging and optimization wizard',
-    'model-documenter': 'Semantic model documentation generator',
-    'migration-assistant': 'Migration and upgrade assistant',
-    'report-layout': 'Report page layout planner',
-    // New reference skills
-    governance: 'Naming conventions, standards, and governance',
-    'semantic-model': 'Semantic model best practices and patterns',
-    'report-design': 'Report design and visualization principles',
-    deployment: 'CI/CD and deployment patterns for BI',
-    'dax-udf': 'DAX user-defined functions (UDFs)',
-  };
-  return purposes[skillName] || 'Specialized BI assistance';
+  return SKILL_PURPOSES[skillName] || 'Specialized BI assistance';
 }
 
 /**
@@ -243,6 +238,7 @@ ${footer}`;
 module.exports = {
   parseSkillMetadata,
   getSkillPurpose,
+  SKILL_PURPOSES,
   generateSkillsSection,
   getCodeStandards,
   getFormatHeader,

package/bin/lib/mcp-config.js

@@ -29,7 +29,7 @@ const path = require('path');
 const os = require('os');
 
 const MICROSOFT_LEARN_URL = 'https://learn.microsoft.com/api/mcp';
-const MODELING_SERVER_NAME = 'powerbi-modeling';
+const MODELING_SERVER_NAME = 'powerbi-modeling-mcp';
 const LEARN_SERVER_NAME = 'microsoft-learn';
 
 /**
@@ -42,6 +42,11 @@ function getLauncherAbsolutePath(packageDir) {
 
 /**
  * Safely read a JSON file. Returns null if missing or unparseable.
+ *
+ * NOTE: this swallows parse errors. Do NOT use it before a write — a
+ * silent null on a corrupt user config means a spread merge ends up
+ * replacing the whole config with our 2 servers (data loss). Use
+ * `readJsonStrict` for write paths instead.
  */
 function readJsonSafe(filePath) {
   if (!fs.existsSync(filePath)) return null;
@@ -52,6 +57,36 @@ function readJsonSafe(filePath) {
   }
 }
 
+/**
+ * Read a JSON file for write paths. Returns null only if the file is
+ * absent or empty. Throws an actionable error if the file exists with
+ * non-empty content but is not parseable — silently overwriting a
+ * user's corrupt config (especially `~/.claude.json`) destroys data.
+ *
+ * @throws {Error} if the file exists but is unreadable or unparseable
+ */
+function readJsonStrict(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `Could not read ${filePath}: ${err.message}. ` + 'Check file permissions and retry.'
+    );
+  }
+  if (raw.trim() === '') return null;
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `Refusing to overwrite ${filePath}: file exists but is not valid JSON ` +
+        `(${err.message}). Inspect or move it manually before retrying. ` +
+        `If a previous-install backup exists at ${filePath}.bak, restore from there.`
+    );
+  }
+}
+
 /**
  * Reject symlink attacks before writing to a file. We use lstatSync so
  * we detect the link itself (not what it points to). If a user home has
@@ -69,16 +104,132 @@ function assertNotSymlink(filePath) {
 }
 
 /**
- * Write a JSON file, creating parent dirs if needed.
- * Refuses to overwrite symbolic links for safety.
+ * Walk the ancestors of `filePath` up to (but not including) the user's
+ * home directory and reject if any ancestor is a symbolic link. Needed
+ * because `assertNotSymlink` only checks the leaf — a symlink at a
+ * parent (e.g. `~/.copilot` → `/tmp/attacker/`) would still redirect
+ * every `.tmp` / `.bak` / final rename through the link, bypassing the
+ * leaf-only hardening.
+ *
+ * Trust boundaries:
+ * - We stop walking at `os.homedir()` itself. If the user's home is a
+ *   symlink, that's their machine setup, not something we can police.
+ * - We also stop if, after `realpathSync`, the ancestor resolves
+ *   outside the home subtree — defensive, covers the case where an
+ *   earlier ancestor already redirected us elsewhere.
+ * - We stop at filesystem root (`path.dirname(x) === x`).
+ *
+ * Known Windows gap: this uses `lstatSync().isSymbolicLink()`. NTFS
+ * junctions are NOT classified as symlinks by Node, so a junction at
+ * `~/.copilot` would pass this check. Documented as a residual risk
+ * in `coordination/TO_CODEX_REVIEW.md`; addressing it needs
+ * `fs.readlinkSync` with reparse-point inspection and is out of scope
+ * for this commit.
+ *
+ * @throws {Error} if any ancestor of filePath (up to home) is a symlink
  */
-function writeJson(filePath, data) {
+function assertNoSymlinkedAncestor(filePath) {
+  const home = os.homedir();
+  const homeResolved = fs.existsSync(home) ? fs.realpathSync(home) : home;
+
+  let current = path.dirname(filePath);
+  const visited = new Set();
+
+  while (current && !visited.has(current)) {
+    visited.add(current);
+
+    // Stop at the user's home — trust boundary.
+    if (current === home || current === homeResolved) return;
+
+    if (fs.existsSync(current)) {
+      if (fs.lstatSync(current).isSymbolicLink()) {
+        throw new Error(
+          `Refusing to write MCP config: parent directory ${current} is a symbolic link. ` +
+            'Remove the symlink (or redirect super install at a different path) and retry.'
+        );
+      }
+
+      // Defensive: if realpath has already pulled us outside the home
+      // subtree, stop walking — we're in territory we can't reason about.
+      const currentResolved = fs.realpathSync(current);
+      if (!currentResolved.startsWith(homeResolved)) return;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) return; // filesystem root
+    current = parent;
+  }
+}
+
+/**
+ * Full pre-write safety check: leaf must not be a symlink, and no
+ * ancestor up to `os.homedir()` may be a symlink either. Use this
+ * instead of `assertNotSymlink` on every write path inside the user
+ * home directory.
+ */
+function assertPathSafeForWrite(filePath) {
   assertNotSymlink(filePath);
+  assertNoSymlinkedAncestor(filePath);
+}
+
+/**
+ * Write any text content to a file using a safe pattern:
+ *
+ *   1. Refuse if the target is a symbolic link (assertNotSymlink).
+ *   2. If the target exists, copy it to `<target>.bak` first. This
+ *      gives the user a one-slot recovery file overwritten on each
+ *      install — enough to recover from a bad merge without
+ *      accumulating stale backups across many install runs.
+ *   3. Write to `<target>.tmp` then atomically rename to the final
+ *      path. `fs.renameSync` is atomic on POSIX and functionally
+ *      atomic for same-volume renames on NTFS, which is the only
+ *      shape we hit when writing into the user home (~/...).
+ *   4. On any error mid-process, best-effort cleanup of the .tmp
+ *      file so we never leave half-written turds behind.
+ *
+ * The atomic + backup pattern matters most for `~/.claude.json` —
+ * Claude Code's primary user config holds project pointers, OAuth
+ * state, conversation history. A crash mid-write or a bad merge
+ * would brick the user's Claude install otherwise.
+ */
+function writeFileAtomic(filePath, content) {
+  assertPathSafeForWrite(filePath);
   const dir = path.dirname(filePath);
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n');
+
+  if (fs.existsSync(filePath)) {
+    try {
+      fs.copyFileSync(filePath, `${filePath}.bak`);
+    } catch (err) {
+      throw new Error(
+        `Could not back up ${filePath} before writing: ${err.message}. ` +
+          'Aborting to avoid losing the existing file.'
+      );
+    }
+  }
+
+  const tmpPath = `${filePath}.tmp`;
+  try {
+    fs.writeFileSync(tmpPath, content);
+    fs.renameSync(tmpPath, filePath);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch (_) {
+      // Best-effort cleanup; ignore if there is nothing to remove.
+    }
+    throw err;
+  }
+}
+
+/**
+ * Write a JSON file using the atomic + backup pattern.
+ * Refuses to overwrite symbolic links for safety.
+ */
+function writeJson(filePath, data) {
+  writeFileAtomic(filePath, JSON.stringify(data, null, 2) + '\n');
 }
 
 /**
@@ -124,11 +275,19 @@ function escapeRegex(str) {
 //
 // We describe each agent in a single table and build the writer functions
 // from it so adding a new JSON agent is a one-line change.
+//
+// IMPORTANT: every entry below has a source URL pointing at the official
+// docs where the path/format comes from. If you change any of these,
+// verify the new value against the linked source first. Silent drift is
+// the hardest class of bug in this file because the writes succeed even
+// when the agent never reads the file.
 
 const JSON_AGENT_CONFIGS = {
   'claude-code': {
-    // Claude Code user-scope MCP config lives in ~/.claude.json under
-    // mcpServers. stdio entries omit `type`, HTTP entries include it.
+    // Source: https://code.claude.com/docs/en/mcp
+    // "User-scoped servers are stored in ~/.claude.json"
+    // Note: ~/.claude/settings.json does NOT work for MCPs (known docs bug).
+    // stdio entries omit `type` here; HTTP entries include it.
     configPath: () => path.join(os.homedir(), '.claude.json'),
     wrapperKey: 'mcpServers',
     stdioIncludesType: false,
@@ -136,7 +295,9 @@ const JSON_AGENT_CONFIGS = {
     httpField: 'url',
   },
   'github-copilot': {
-    // Copilot CLI uses `servers` (NOT mcpServers) and every server needs
+    // Source: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers
+    // "MCP servers are saved to ~/.copilot/mcp-config.json"
+    // Copilot uses `servers` (NOT mcpServers) and every server needs
     // an explicit `type` field.
     configPath: () => path.join(os.homedir(), '.copilot', 'mcp-config.json'),
     wrapperKey: 'servers',
@@ -145,6 +306,8 @@ const JSON_AGENT_CONFIGS = {
     httpField: 'url',
   },
   'gemini-cli': {
+    // Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
+    // "MCP config goes in ~/.gemini/settings.json under mcpServers"
     // Gemini uses `httpUrl` (NOT `url`) for HTTP transports and omits
     // `type` — it's inferred from which key is present.
     configPath: () => path.join(os.homedir(), '.gemini', 'settings.json'),
@@ -154,10 +317,12 @@ const JSON_AGENT_CONFIGS = {
     httpField: 'httpUrl',
   },
   kilo: {
+    // Source: https://kilo.ai/docs/automate/mcp/using-in-kilo-code
     // Kilo Code uses ~/.kilo/ as the user config root (consistent with
     // ~/.kilo/skills/). The global MCP settings live at the natural
     // neighbor path — mcp_settings.json — which is what the Kilo VS Code
-    // extension and CLI both read.
+    // extension and CLI both read. (NOT ~/.kilocode/ — that path is
+    // project-level only.)
     configPath: () => path.join(os.homedir(), '.kilo', 'mcp_settings.json'),
     wrapperKey: 'mcpServers',
     stdioIncludesType: false,
@@ -212,7 +377,10 @@ function makeJsonWriter(agentId) {
   const agentConfig = JSON_AGENT_CONFIGS[agentId];
   return function jsonWriter(packageDir) {
     const configPath = agentConfig.configPath();
-    const existing = readJsonSafe(configPath) || {};
+    // Use strict reader on the write path: a silent parse failure here
+    // would discard the user's other config keys (history, OAuth, etc.)
+    // when the empty {} fallback is spread into the new write.
+    const existing = readJsonStrict(configPath) || {};
     const wrapperKey = agentConfig.wrapperKey;
 
     const newServers = buildJsonServers(agentConfig, packageDir);
@@ -226,12 +394,17 @@ function makeJsonWriter(agentId) {
 // ============================================
 // CODEX (OpenAI) — TOML format
 // ============================================
+// Source: https://developers.openai.com/codex/mcp
+// Also: https://github.com/openai/codex/blob/main/docs/config.md
+// "Codex CLI reads MCP server config from ~/.codex/config.toml, where
+//  each server gets its own section with format [mcp_servers.my-server]"
+//
 // Writes ~/.codex/config.toml, appending [mcp_servers.*] sections.
 // Preserves existing content by removing only our own sections before
 // appending the fresh ones.
 function writeCodexConfig(packageDir) {
   const configPath = path.join(os.homedir(), '.codex', 'config.toml');
-  assertNotSymlink(configPath);
+  assertPathSafeForWrite(configPath);
   const launcher = getLauncherAbsolutePath(packageDir);
 
   let existing = '';
@@ -259,11 +432,9 @@ function writeCodexConfig(packageDir) {
 
   const content = existing.trimEnd() + newSections;
 
-  const dir = path.dirname(configPath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-  fs.writeFileSync(configPath, content);
+  // Use the same atomic + backup pattern as the JSON writers — a crash
+  // mid-write to ~/.codex/config.toml would brick the user's Codex install.
+  writeFileAtomic(configPath, content);
   return configPath;
 }
 
@@ -303,9 +474,13 @@ module.exports = {
   MICROSOFT_LEARN_URL,
   // Exported for testing
   readJsonSafe,
+  readJsonStrict,
   writeJson,
+  writeFileAtomic,
   tomlEscape,
   escapeRegex,
   assertNotSymlink,
+  assertNoSymlinkedAncestor,
+  assertPathSafeForWrite,
   getLauncherAbsolutePath,
 };