nexakit 0.1.0 → 0.2.0

package/src/skill-recommendations.js

@@ -1,10 +1,17 @@
+import { ownedReviewInstructions, removeReviewInstructions } from './review-instructions.js';
 import { createHash } from 'node:crypto';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { acquireLock } from './install-lock.js';
+import { isRegistered, readRegistry, recordEntries } from './install-registry.js';
+import { classifyLink, relinkIfUnchanged } from './link-states.js';
 import { IS_WINDOWS } from './platform.js';
+import { detectSignals, SIGNAL_LABELS } from './project-signals.js';
+import { resolveProjectRoot } from './project-root.js';
 import { loadSkillCatalog } from './skill-catalog.js';
-import { TOOLKIT_ROOT } from './toolkit-setup.js';
+import { actualRoot, ensureStableInstall, nexakitDir } from './stable-install.js';
+import { TOOLKIT_ROOT, globalSkillTarget, resolveRoots } from './toolkit-setup.js';
 
 const MAX_MANIFEST_BYTES = 512 * 1024;
 const MAX_SKILL_FILES = 256;
@@ -13,6 +20,14 @@ const VALID_CLIENTS = new Set(['codex', 'claude']);
 const VALID_INSTALL_MODES = new Set(['symlink', 'copy']);
 const VALID_GIT_IGNORE = new Set(['gitignore', 'git-exclude', 'none']);
 const SKILL_NAME_RE = /^[a-z0-9-]+$/u;
+// Antigravity reads project skills from `.agents/skills`, the folder Codex uses: one link serves both.
+const projectClientsFor = agent => (agent === 'all' ? ['codex', 'claude'] : [agent === 'antigravity' ? 'codex' : agent]);
+const servesFor = (client, agent) => (client === 'claude' ? ['claude'] : agent === 'all' ? ['codex', 'antigravity'] : [agent === 'antigravity' ? 'antigravity' : 'codex']);
+// The coarse vocabulary the rest of the code reads; `linkState` keeps the detailed one.
+const COARSE_STATE = Object.freeze({
+  falta: 'missing', efimero: 'replace', 'roto-propio': 'replace', instalado: 'installed',
+  'otra-copia': 'installed', conflicto: 'conflict', 'roto-ajeno': 'conflict'
+});
 
 export const PROJECT_TOOLKIT_DIR = '.agent-toolkit';
 const PROJECT_MANIFEST_FILE = 'manifest.json';
@@ -22,75 +37,7 @@ const IGNORE_BLOCK_END = '# <<< agent-toolkit (managed) <<<';
 const LEVEL_AGENT_HEADER = '# Generado por `agent-toolkit-inbox agentes`.';
 const LEVEL_AGENT_NAMES = ['nivel_ligero.toml', 'nivel_normal.toml', 'nivel_exigente.toml', 'nivel_alto.toml'];
 
-const SIGNAL_LABELS = Object.freeze({
-  nodejs: 'Node.js',
-  typescript: 'TypeScript',
-  'mcp-sdk': 'MCP SDK',
-  react: 'React',
-  nextjs: 'Next.js',
-  tailwindcss: 'Tailwind CSS',
-  astro: 'Astro',
-  vue: 'Vue',
-  svelte: 'Svelte',
-  supabase: 'Supabase',
-  postgres: 'PostgreSQL',
-  express: 'Express',
-  fastify: 'Fastify',
-  hono: 'Hono',
-  playwright: 'Playwright',
-  vitest: 'Vitest'
-});
-
-const PACKAGE_TO_SIGNAL = Object.freeze({
-  '@modelcontextprotocol/sdk': 'mcp-sdk',
-  '@modelcontextprotocol/server': 'mcp-sdk',
-  '@modelcontextprotocol/client': 'mcp-sdk',
-  fastmcp: 'mcp-sdk',
-  next: 'nextjs',
-  react: 'react',
-  'react-dom': 'react',
-  tailwindcss: 'tailwindcss',
-  '@tailwindcss/postcss': 'tailwindcss',
-  '@tailwindcss/vite': 'tailwindcss',
-  typescript: 'typescript',
-  astro: 'astro',
-  vue: 'vue',
-  nuxt: 'vue',
-  svelte: 'svelte',
-  '@sveltejs/kit': 'svelte',
-  '@supabase/supabase-js': 'supabase',
-  '@supabase/ssr': 'supabase',
-  pg: 'postgres',
-  postgres: 'postgres',
-  '@neondatabase/serverless': 'postgres',
-  'drizzle-orm': 'postgres',
-  '@prisma/client': 'postgres',
-  express: 'express',
-  fastify: 'fastify',
-  hono: 'hono',
-  '@hono/node-server': 'hono',
-  playwright: 'playwright',
-  '@playwright/test': 'playwright',
-  vitest: 'vitest'
-});
-
-const FRAMEWORK_CONFIG_HINTS = Object.freeze([
-  ['next.config.js', 'nextjs'],
-  ['next.config.mjs', 'nextjs'],
-  ['next.config.ts', 'nextjs'],
-  ['tailwind.config.js', 'tailwindcss'],
-  ['tailwind.config.ts', 'tailwindcss'],
-  ['astro.config.mjs', 'astro'],
-  ['svelte.config.js', 'svelte']
-]);
-
-const OUT_OF_COVERAGE_MANIFESTS = Object.freeze([
-  'Cargo.toml',
-  'pyproject.toml',
-  'go.mod',
-  'composer.json',
-  'Gemfile'
-]);
+export { SIGNAL_LABELS };
 
 const normalizedPath = value => (IS_WINDOWS ? value.toLowerCase() : value);
 const lstatOrNull = target => fs.lstat(target).catch(err => {
@@ -234,84 +181,36 @@ async function inspectProjectSkills(projectRoot, toolkitRoot, catalogByName, cli
   }));
 }
 
-export async function inspectSkillProject(projectRoot, { client, toolkitRoot = TOOLKIT_ROOT, catalog } = {}) {
+async function rootPackageName(root) {
+  const info = await lstatOrNull(path.join(root, 'package.json'));
+  if (!info?.isFile() || info.isSymbolicLink() || info.size > MAX_MANIFEST_BYTES) return null;
+  try {
+    const name = JSON.parse(await fs.readFile(path.join(root, 'package.json'), 'utf8'))?.name;
+    return typeof name === 'string' && name.trim() ? name.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function inspectSkillProject(projectRoot, { client, toolkitRoot = TOOLKIT_ROOT, catalog, homeDirectory } = {}) {
   if (client !== undefined && !VALID_CLIENTS.has(client)) {
     throw new Error('El filtro --client solo admite codex o claude.');
   }
-  const root = await fs.realpath(projectRoot);
+  // The project is the whole Git repository, even when nexakit runs from one of its subfolders.
+  const project = await resolveProjectRoot(projectRoot, homeDirectory ? { homeDirectory } : {});
+  const root = project.root;
   const resolvedToolkit = await fs.realpath(toolkitRoot);
   const activeCatalog = catalog ?? await loadSkillCatalog();
   const catalogByName = new Map(activeCatalog.skills.map(s => [s.name, s]));
-
-  const signalSources = new Map();
-  const addSignal = (id, source) => {
-    const list = signalSources.get(id) ?? [];
-    if (!list.includes(source)) list.push(source);
-    signalSources.set(id, list);
-  };
-
-  const limits = [];
-  let projectName = path.basename(root);
-
-  const pkgPath = path.join(root, 'package.json');
-  const pkgInfo = await lstatOrNull(pkgPath);
-  if (pkgInfo) {
-    if (!pkgInfo.isFile() || pkgInfo.isSymbolicLink() || pkgInfo.size > MAX_MANIFEST_BYTES) {
-      limits.push('package.json excede el límite o no es un archivo regular; no se inspeccionó.');
-    } else {
-      let pkg = null;
-      try {
-        pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
-      } catch {
-        limits.push('package.json no contiene JSON válido; no se dedujeron dependencias Node.');
-      }
-      if (pkg && typeof pkg === 'object' && !Array.isArray(pkg)) {
-        if (typeof pkg.name === 'string' && pkg.name.trim()) projectName = pkg.name.trim();
-        addSignal('nodejs', 'package.json');
-        for (const field of ['dependencies', 'devDependencies', 'peerDependencies']) {
-          const deps = pkg[field];
-          if (!deps || typeof deps !== 'object' || Array.isArray(deps)) continue;
-          for (const depName of Object.keys(deps)) {
-            const mapped = PACKAGE_TO_SIGNAL[depName];
-            if (mapped) addSignal(mapped, `package.json (${depName})`);
-          }
-        }
-      }
-    }
-  }
-
-  const tsconfigInfo = await lstatOrNull(path.join(root, 'tsconfig.json'));
-  if (tsconfigInfo?.isFile() && !tsconfigInfo.isSymbolicLink()) {
-    addSignal('typescript', 'tsconfig.json');
-  }
-
-  for (const [configFile, expectedSignal] of FRAMEWORK_CONFIG_HINTS) {
-    const info = await lstatOrNull(path.join(root, configFile));
-    if (info?.isFile() && !info.isSymbolicLink() && !signalSources.has(expectedSignal)) {
-      limits.push(`Configuración observada sin dependencia confirmada en package.json: ${configFile}.`);
-    }
-  }
-
-  for (const foreignManifest of OUT_OF_COVERAGE_MANIFESTS) {
-    const info = await lstatOrNull(path.join(root, foreignManifest));
-    if (info && !info.isSymbolicLink()) {
-      limits.push(`Stack fuera de cobertura automática observada: ${foreignManifest}.`);
-    }
-  }
-
-  if (!pkgInfo && signalSources.size === 0 && limits.length === 0) {
-    limits.push('No se detectó package.json en la raíz; cobertura automática inicial enfocada en Node.js.');
-  }
-
-  const signals = [...signalSources.entries()]
-    .map(([id, sources]) => ({ id, label: SIGNAL_LABELS[id] ?? id, sources }))
-    .sort((a, b) => a.id.localeCompare(b.id));
+  const { signals, limits } = await detectSignals(root, { git: project.git });
+  const projectName = await rootPackageName(root) ?? project.displayName;
 
   const installed = await inspectProjectSkills(root, resolvedToolkit, catalogByName, client);
   const coupling = await inspectProjectCoupling(root, resolvedToolkit);
 
   return {
     projectRoot: root,
+    project,
     projectName,
     signals,
     installed,
@@ -595,6 +494,7 @@ export function recommendSkills({ catalog, inspection, profile, client, clients
       revision: skill.revision,
       installedPath: skill.installedPath,
       reasons,
+      matchedSignals,
       overlapsWith: [...skill.overlapsWith],
       reviewStatus: skill.review.status,
       reviewNotes: skill.review.notes,
@@ -627,6 +527,10 @@ export function recommendSkills({ catalog, inspection, profile, client, clients
   }
 
   optional.sort((a, b) => a.name.localeCompare(b.name));
+  // The skills that match more of what was detected come first; ties by name.
+  const byMatches = (a, b) => b.matchedSignals.length - a.matchedSignals.length || a.name.localeCompare(b.name);
+  recommended.sort(byMatches);
+  candidates.sort(byMatches);
 
   const externalCandidates = [];
   for (const ref of catalog.externalReferences) {
@@ -701,8 +605,8 @@ async function projectTargetState(source, target, mode, catalogEntry) {
       throw err;
     }
   }
-  // mode === 'copy'
-  if (info.isSymbolicLink()) return 'replace';
+  // mode === 'copy': links are classified by the planner; here one is never assumed replaceable.
+  if (info.isSymbolicLink()) return 'conflict';
   if (info.isDirectory() && catalogEntry) {
     const integrity = await verifyCatalogIntegrity(target, catalogEntry);
     return integrity === 'verified' ? 'installed' : 'conflict';
@@ -717,10 +621,12 @@ export async function planProjectSkillInstall({
   mode = 'symlink',
   gitIgnore = 'gitignore',
   catalog,
-  toolkitRoot = TOOLKIT_ROOT
+  toolkitRoot = TOOLKIT_ROOT,
+  linkRoot,
+  homeDirectory = os.homedir()
 } = {}) {
-  if (!['codex', 'claude', 'all'].includes(agent)) {
-    throw new Error('El agente debe ser codex, claude o all.');
+  if (!['codex', 'claude', 'antigravity', 'all'].includes(agent)) {
+    throw new Error('El agente debe ser codex, claude, antigravity o all.');
   }
   if (!VALID_INSTALL_MODES.has(mode)) {
     throw new Error('El modo de instalación debe ser symlink o copy.');
@@ -728,13 +634,33 @@ export async function planProjectSkillInstall({
   if (!VALID_GIT_IGNORE.has(gitIgnore)) {
     throw new Error('La estrategia gitIgnore debe ser gitignore, git-exclude o none.');
   }
-  const clients = agent === 'all' ? ['codex', 'claude'] : [agent];
+  const clients = projectClientsFor(agent);
   const root = await fs.realpath(projectRoot);
   const resolvedToolkit = await fs.realpath(toolkitRoot);
+  const home = await fs.realpath(homeDirectory).catch(() => path.resolve(homeDirectory));
+  const roots = await resolveRoots({ toolkitRoot: resolvedToolkit, homeDirectory: home });
+  // An explicit linkRoot means the caller chose where to link, so no stable copy is made.
+  const linkRootPath = linkRoot ? path.resolve(linkRoot) : roots.linkRoot;
+  const ephemeral = !linkRoot && roots.ephemeral;
   const activeCatalog = catalog ?? await loadSkillCatalog();
   const catalogByName = new Map(activeCatalog.skills.map(s => [s.name, s]));
   const uniqueSkills = [...new Set(skillNames ?? [])].sort();
 
+  // A broken link is nexakit's only with proof: the install registry (the exact link), or this project's
+  // manifest. An entry written by this version records the exact link too; one from 0.1.0 only has the path,
+  // so its link must at least have nexakit's own shape: `<root>/<where this skill lives in nexakit>`.
+  const registry = await readRegistry(nexakitDir(home));
+  const previousManifest = await readProjectToolkitManifest(root);
+  const manifested = new Map((previousManifest?.entries ?? []).filter(entry => entry?.relativePath).map(entry => [entry.relativePath, entry]));
+  const ownedBy = suffix => (target, literal) => {
+    if (isRegistered(registry, target, literal)) return true;
+    const entry = manifested.get(path.relative(root, target).split(path.sep).join('/'));
+    if (!entry) return false;
+    if (typeof entry.apunta === 'string') return entry.apunta === literal;
+    return path.resolve(path.dirname(target), literal).endsWith(path.sep + path.normalize(suffix));
+  };
+  const activeRoots = [linkRootPath, resolvedToolkit, actualRoot(home)];
+
   const links = [];
   const verifiedCatalogEntries = new Map();
 
@@ -759,8 +685,29 @@ export async function planProjectSkillInstall({
     for (const client of clients) {
       const target = path.join(root, client === 'codex' ? '.agents' : '.claude', 'skills', skillName);
       await ensureSafeProjectParents(root, target, false);
+      const serves = servesFor(client, agent);
+      const suffix = path.relative(resolvedToolkit, source);
+      if (mode === 'symlink') {
+        const info = await classifyLink({ target, suffix, activeRoots, isOwned: ownedBy(suffix) });
+        links.push({
+          client, serves, name: skillName, source: path.join(linkRootPath, suffix), target, mode,
+          state: COARSE_STATE[info.state], linkState: info.state,
+          ...(info.literal && { literal: info.literal }), ...(info.root && { root: info.root })
+        });
+        continue;
+      }
+      if ((await lstatOrNull(target))?.isSymbolicLink()) {
+        // A link where a copy goes is replaced only when it is provably nexakit's; any other link is the user's.
+        const info = await classifyLink({ target, suffix, activeRoots, isOwned: ownedBy(suffix) });
+        const ours = ['instalado', 'otra-copia', 'efimero', 'roto-propio'].includes(info.state);
+        links.push({
+          client, serves, name: skillName, source, target, mode, state: ours ? 'replace' : 'conflict',
+          linkState: info.state, ...(info.literal && { literal: info.literal })
+        });
+        continue;
+      }
       const state = await projectTargetState(source, target, mode, catalogEntry);
-      links.push({ client, name: skillName, source, target, state, mode });
+      links.push({ client, serves, name: skillName, source, target, state, mode });
     }
   }
 
@@ -800,6 +747,10 @@ export async function planProjectSkillInstall({
     gitIgnore,
     projectRoot: root,
     toolkitRoot: resolvedToolkit,
+    linkRoot: linkRootPath,
+    ephemeral,
+    homeDirectory: home,
+    agent,
     links,
     stateDirPath,
     manifestPath,
@@ -822,7 +773,8 @@ export async function planProjectSkillInstall({
   };
 }
 
-async function copyVerifiedSkillDirectory(sourceDir, targetDir, catalogEntry) {
+async function copyVerifiedSkillDirectory(sourceDir, targetDir, catalogEntry, lock) {
+  await lock?.assertHeld();
   await fs.mkdir(targetDir, { recursive: true, mode: 0o755 });
   if (catalogEntry) {
     for (const file of catalogEntry.files) {
@@ -833,15 +785,18 @@ async function copyVerifiedSkillDirectory(sourceDir, targetDir, catalogEntry) {
       if (actualHash !== file.sha256) {
         throw new Error(`Integridad SHA-256 rechazada durante la copia de ${catalogEntry.name} (${file.path}).`);
       }
+      await lock?.assertHeld();
       await fs.mkdir(path.dirname(dstFile), { recursive: true, mode: 0o755 });
       await fs.writeFile(dstFile, bytes, { mode: 0o644 });
     }
   } else {
+    await lock?.assertHeld();
     await fs.cp(sourceDir, targetDir, { recursive: true, dereference: false });
   }
 }
 
-async function writeSkillsLockfile(lockfilePath, activeEntriesBySkill) {
+async function writeSkillsLockfile(lockfilePath, activeEntriesBySkill, lock) {
+  await lock?.assertHeld();
   await fs.mkdir(path.dirname(lockfilePath), { recursive: true, mode: 0o755 });
   const existingInfo = await lstatOrNull(lockfilePath);
   if (existingInfo && (!existingInfo.isFile() || existingInfo.isSymbolicLink())) {
@@ -882,6 +837,7 @@ async function writeSkillsLockfile(lockfilePath, activeEntriesBySkill) {
     generatedBy: 'nexakit',
     skills: sortedSkills
   };
+  await lock?.assertHeld();
   await fs.writeFile(lockfilePath, JSON.stringify(payload, null, 2) + '\n', { mode: 0o644 });
   return true;
 }
@@ -891,13 +847,16 @@ async function writeProjectManifestAndIgnore({
   mode,
   gitIgnore,
   prevManifest,
-  coupledEntriesMap
+  coupledEntriesMap,
+  lock,
+  answers = prevManifest?.answers
 }) {
   const stateDir = path.join(projectRoot, PROJECT_TOOLKIT_DIR);
   const stateStat = await lstatOrNull(stateDir);
   if (stateStat && (!stateStat.isDirectory() || stateStat.isSymbolicLink())) {
     return { manifestWritten: false, gitIgnoreUpdated: false };
   }
+  await lock?.assertHeld();
   await fs.mkdir(stateDir, { recursive: true, mode: 0o755 });
 
   const entries = [...coupledEntriesMap.values()].sort((a, b) =>
@@ -910,17 +869,20 @@ async function writeProjectManifestAndIgnore({
   if (gitIgnore !== 'none') {
     const info = await inspectGitIgnoreTarget(projectRoot, gitIgnore);
     if (!info.conflict && !info.unavailable && info.targetPath) {
+      await lock?.assertHeld();
       await fs.mkdir(path.dirname(info.targetPath), { recursive: true, mode: 0o755 });
       const currentStat = await lstatOrNull(info.targetPath);
       if (!currentStat) {
         if (gitIgnore === 'gitignore') createdIgnoreFile = true;
         const nextText = upsertManagedIgnoreBlock('', entries.map(e => e.relativePath));
+        await lock?.assertHeld();
         await fs.writeFile(info.targetPath, nextText, { mode: 0o644 });
         gitIgnoreUpdated = true;
       } else if (currentStat.isFile() && !currentStat.isSymbolicLink()) {
         const prevText = await fs.readFile(info.targetPath, 'utf8');
         const nextText = upsertManagedIgnoreBlock(prevText, entries.map(e => e.relativePath));
         if (nextText !== prevText) {
+          await lock?.assertHeld();
           await fs.writeFile(info.targetPath, nextText, { mode: 0o644 });
         }
         gitIgnoreUpdated = true;
@@ -935,6 +897,7 @@ async function writeProjectManifestAndIgnore({
           const otherText = await fs.readFile(otherInfo.targetPath, 'utf8');
           const cleaned = removeManagedIgnoreBlock(otherText);
           if (cleaned.changed) {
+            await lock?.assertHeld();
             if (!cleaned.content && otherStrategy === 'gitignore' && prevManifest?.createdIgnoreFile) {
               await fs.unlink(otherInfo.targetPath).catch(() => {});
               createdIgnoreFile = false;
@@ -953,20 +916,71 @@ async function writeProjectManifestAndIgnore({
     mode,
     gitIgnoreStrategy: gitIgnore,
     createdIgnoreFile,
-    entries
+    entries,
+    ...(answers && { answers })
   };
-  await fs.writeFile(
-    path.join(stateDir, PROJECT_MANIFEST_FILE),
-    JSON.stringify(manifestPayload, null, 2) + '\n',
-    { mode: 0o644 }
-  );
+  // A manifest that is a link or not a regular file is not nexakit's: it is never written through.
+  const manifestPath = path.join(stateDir, PROJECT_MANIFEST_FILE);
+  const manifestStat = await lstatOrNull(manifestPath);
+  if (manifestStat && (!manifestStat.isFile() || manifestStat.isSymbolicLink())) {
+    return { manifestWritten: false, gitIgnoreUpdated };
+  }
+  const temporary = `${manifestPath}.${process.pid}.tmp`;
+  await fs.writeFile(temporary, JSON.stringify(manifestPayload, null, 2) + '\n', { mode: 0o644, flag: 'wx' });
+  try {
+    await lock?.assertHeld();
+    await fs.rename(temporary, manifestPath);
+  } finally {
+    await fs.rm(temporary, { force: true }); // ours: created exclusively above
+  }
   return { manifestWritten: true, gitIgnoreUpdated };
 }
 
-export async function applyProjectSkillInstall(plan) {
+// Links are written under the install lock: it prepares the stable copy when running from an npx cache,
+// re-checks the hashes where the links will point, and records every link so a broken one can be proven ours.
+export async function applyProjectSkillInstall(plan, { runNpm, packageSpec, lockOptions, acquire = acquireLock } = {}) {
   if (!plan || !Array.isArray(plan.links) || !plan.projectRoot) {
     throw new Error('Se requiere una vista previa válida de instalación de skills.');
   }
+  const mode = plan.mode ?? 'symlink';
+  const gitIgnore = plan.gitIgnore ?? 'gitignore';
+  // Anything that writes (links, copies, the manifest, ignore rules or the lockfile) runs under the lock.
+  // With nothing to write, nothing is written, so a run that changes nothing never creates ~/.nexakit.
+  const pending = plan.links.some(l => ['missing', 'replace'].includes(l.state));
+  const previous = await readProjectToolkitManifest(plan.projectRoot);
+  const settingsChanged = Boolean(previous) && (previous.mode !== mode || previous.gitIgnoreStrategy !== gitIgnore);
+  if (!pending && !settingsChanged) return applyProjectSkillInstallLocked(plan, { registryEntries: [], lock: null, writeMetadata: false });
+
+  const home = plan.homeDirectory ?? os.homedir();
+  const lock = await acquire(nexakitDir(home), lockOptions);
+  const registryEntries = [];
+  try {
+    if (mode === 'symlink' && pending) {
+      if (plan.ephemeral) {
+        const { version } = JSON.parse(await fs.readFile(path.join(plan.toolkitRoot ?? TOOLKIT_ROOT, 'package.json'), 'utf8'));
+        await ensureStableInstall({
+          homeDirectory: home, version, lock, ...(runNpm && { runNpm }), ...(packageSpec && { packageSpec })
+        });
+      }
+      const linkRoot = plan.linkRoot ?? plan.toolkitRoot ?? TOOLKIT_ROOT;
+      if (path.resolve(linkRoot) !== path.resolve(plan.toolkitRoot ?? TOOLKIT_ROOT)) {
+        // The files that get linked are the ones in linkRoot, so their hashes must hold there too.
+        for (const entry of Object.values(plan.verifiedCatalogEntries ?? {})) {
+          const check = await verifyBundledSkillHashes({ skillEntry: entry, toolkitRoot: linkRoot });
+          if (!check.ok) throw new Error(check.reason);
+        }
+      }
+    }
+    const result = await applyProjectSkillInstallLocked(plan, { registryEntries, lock, writeMetadata: true });
+    await recordEntries(nexakitDir(home), registryEntries, lock);
+    return result;
+  } finally {
+    await lock.release();
+  }
+}
+
+// `lock` is null only when nothing will be written; every write checks it still holds the lock just before.
+async function applyProjectSkillInstallLocked(plan, { registryEntries, lock, writeMetadata }) {
   const mode = plan.mode ?? 'symlink';
   const gitIgnore = plan.gitIgnore ?? 'gitignore';
   const catalogEntries = plan.verifiedCatalogEntries ?? {};
@@ -1008,35 +1022,49 @@ export async function applyProjectSkillInstall(plan) {
       continue;
     }
 
+    await lock?.assertHeld();
     await ensureSafeProjectParents(plan.projectRoot, item.target, true);
-    const currentState = await projectTargetState(item.source, item.target, mode, catalogEntry);
-    if (currentState === 'conflict') {
-      updatedLinks.push({ ...item, state: 'conflict' });
-      continue;
-    }
-    if (currentState === 'installed') {
-      if (coupledEntriesMap.has(`${item.client}:${item.name}`)) {
-        const list = installedClientsBySkill.get(item.name) ?? [];
-        list.push(item.client);
-        installedClientsBySkill.set(item.name, list);
-      }
-      updatedLinks.push({ ...item, state: 'installed' });
-      continue;
-    }
-    if (currentState === 'replace') {
-      const currentInfo = await lstatOrNull(item.target);
-      if (!currentInfo?.isSymbolicLink()) {
-        updatedLinks.push({ ...item, state: 'conflict' });
+    let literal;
+    if (mode === 'symlink') {
+      // Re-reads the link right before writing: if it is no longer what the plan saw, it is left alone.
+      await lock?.assertHeld();
+      const outcome = await relinkIfUnchanged({
+        target: item.target, expectedLiteral: item.linkState === 'falta' ? null : item.literal, source: item.source, relative: true
+      });
+      if (outcome === 'cambio') {
+        updatedLinks.push({ ...item, state: 'conflict', changed: true });
         continue;
       }
-      await fs.unlink(item.target);
-    }
-
-    if (mode === 'symlink') {
-      const linkTarget = IS_WINDOWS ? path.resolve(item.source) : path.relative(path.dirname(item.target), item.source);
-      await fs.symlink(linkTarget, item.target, IS_WINDOWS ? 'junction' : 'dir');
+      // The registry and the manifest keep what readlink returns, the value that is compared later.
+      literal = await fs.readlink(item.target);
+      registryEntries.push({ destino: item.target, apunta: literal, raiz: plan.linkRoot ?? plan.toolkitRoot });
     } else {
-      await copyVerifiedSkillDirectory(item.source, item.target, catalogEntry);
+      const current = await lstatOrNull(item.target);
+      if (current?.isSymbolicLink()) {
+        // Only a link the plan proved to be nexakit's becomes a copy, and only if it did not change since.
+        if (item.state !== 'replace' || !item.literal || await fs.readlink(item.target) !== item.literal) {
+          updatedLinks.push({ ...item, state: 'conflict', changed: true });
+          continue;
+        }
+        await lock?.assertHeld();
+        await fs.unlink(item.target);
+      } else {
+        const currentState = await projectTargetState(item.source, item.target, mode, catalogEntry);
+        if (currentState === 'conflict') {
+          updatedLinks.push({ ...item, state: 'conflict' });
+          continue;
+        }
+        if (currentState === 'installed') {
+          if (coupledEntriesMap.has(`${item.client}:${item.name}`)) {
+            const list = installedClientsBySkill.get(item.name) ?? [];
+            list.push(item.client);
+            installedClientsBySkill.set(item.name, list);
+          }
+          updatedLinks.push({ ...item, state: 'installed' });
+          continue;
+        }
+      }
+      await copyVerifiedSkillDirectory(item.source, item.target, catalogEntry, lock);
     }
 
     created++;
@@ -1045,6 +1073,7 @@ export async function applyProjectSkillInstall(plan) {
       name: item.name,
       relativePath: relPath,
       mode,
+      ...(literal && { apunta: literal }),
       ...(catalogEntry?.revision && { revision: catalogEntry.revision })
     });
     const list = installedClientsBySkill.get(item.name) ?? [];
@@ -1054,7 +1083,7 @@ export async function applyProjectSkillInstall(plan) {
   }
 
   let lockfileWritten = false;
-  if (mode === 'copy' && !plan.stateDirConflict && !plan.lockfileConflict && installedClientsBySkill.size > 0) {
+  if (writeMetadata && mode === 'copy' && !plan.stateDirConflict && !plan.lockfileConflict && installedClientsBySkill.size > 0) {
     const activeMap = new Map();
     for (const [skillName, clients] of installedClientsBySkill.entries()) {
       const catalogEntry = catalogEntries[skillName];
@@ -1063,20 +1092,22 @@ export async function applyProjectSkillInstall(plan) {
     if (activeMap.size > 0) {
       lockfileWritten = await writeSkillsLockfile(
         plan.lockfilePath ?? path.join(plan.projectRoot, PROJECT_TOOLKIT_DIR, PROJECT_LOCKFILE_NAME),
-        activeMap
+        activeMap,
+        lock
       );
     }
   }
 
   let manifestWritten = false;
   let gitIgnoreUpdated = false;
-  if (!plan.stateDirConflict && (coupledEntriesMap.size > 0 || lockfileWritten)) {
+  if (writeMetadata && !plan.stateDirConflict && (coupledEntriesMap.size > 0 || lockfileWritten)) {
     const res = await writeProjectManifestAndIgnore({
       projectRoot: plan.projectRoot,
       mode,
       gitIgnore,
       prevManifest,
-      coupledEntriesMap
+      coupledEntriesMap,
+      lock
     });
     manifestWritten = res.manifestWritten;
     gitIgnoreUpdated = res.gitIgnoreUpdated;
@@ -1108,6 +1139,38 @@ export async function applyProjectSkillLinks(plan) {
   return applyProjectSkillInstall({ ...plan, mode: 'symlink' });
 }
 
+// The answers given to `npx nexakit` (skills chosen and discarded, agents, memory), kept in the project manifest
+// so a second run knows what was decided and does not ask again.
+const isNameList = value => Array.isArray(value) && value.every(item => typeof item === 'string' && SKILL_NAME_RE.test(item));
+function validSetupAnswers(answers) {
+  return Boolean(answers && answers.version === 1 &&
+    isNameList(answers.skills?.chosen) && isNameList(answers.skills?.discarded) &&
+    Array.isArray(answers.agents) && answers.agents.every(agent => ['claude', 'codex', 'antigravity'].includes(agent)) &&
+    (answers.memory?.decision === 'later' ||
+      (answers.memory?.decision === 'path' && typeof answers.memory.path === 'string' && path.isAbsolute(answers.memory.path))));
+}
+
+export async function readSetupAnswers(projectRoot) {
+  const manifest = await readProjectToolkitManifest(projectRoot);
+  return validSetupAnswers(manifest?.answers) ? manifest.answers : null;
+}
+
+export async function writeSetupAnswers(projectRoot, answers, lock) {
+  if (!validSetupAnswers(answers)) throw new Error('Respuestas de nexakit no válidas.');
+  await lock.assertHeld();
+  const prevManifest = await readProjectToolkitManifest(projectRoot);
+  const result = await writeProjectManifestAndIgnore({
+    projectRoot,
+    mode: prevManifest?.mode ?? 'symlink',
+    gitIgnore: prevManifest?.gitIgnoreStrategy ?? 'gitignore',
+    prevManifest,
+    coupledEntriesMap: new Map((prevManifest?.entries ?? []).map(entry => [entry.relativePath, entry])),
+    lock,
+    answers
+  });
+  if (!result.manifestWritten) throw new Error(`${PROJECT_TOOLKIT_DIR} no es una carpeta normal; no se guardaron las respuestas.`);
+}
+
 export async function planToolkitDetach({
   projectRoot,
   includeGlobal = false,
@@ -1115,13 +1178,21 @@ export async function planToolkitDetach({
   catalog,
   toolkitRoot = TOOLKIT_ROOT,
   homeDirectory = os.homedir(),
-  codexHome
+  codexHome,
+  environment = {},
+  skillNames
 } = {}) {
-  if (!['codex', 'claude', 'all'].includes(agent)) {
-    throw new Error('El agente debe ser codex, claude o all.');
+  if (!['codex', 'claude', 'antigravity', 'all'].includes(agent)) {
+    throw new Error('El agente debe ser codex, claude, antigravity o all.');
   }
-  const clients = agent === 'all' ? ['codex', 'claude'] : [agent];
+  const clients = agent === 'all' ? ['codex', 'claude', 'antigravity'] : [agent];
+  // Antigravity shares Codex's project folder, so removing one's project links removes the other's.
+  const projectClients = [...new Set(clients.map(c => (c === 'antigravity' ? 'codex' : c)))];
   const resolvedToolkit = await fs.realpath(toolkitRoot);
+  const homeReal = await fs.realpath(homeDirectory).catch(() => path.resolve(homeDirectory));
+  // Links made from an npx run point into the stable copy, which is nexakit's too.
+  const stableVersions = path.join(nexakitDir(homeReal), 'versiones');
+  const registry = await readRegistry(nexakitDir(homeReal));
   const activeCatalog = catalog ?? await loadSkillCatalog();
   const catalogByName = new Map(activeCatalog.skills.map(s => [s.name, s]));
 
@@ -1141,17 +1212,19 @@ export async function planToolkitDetach({
 
     let candidateEntries = [];
     if (manifest) {
-      candidateEntries = manifest.entries.filter(e => clients.includes(e.client));
-      remainingManifestEntries = manifest.entries.filter(e => !clients.includes(e.client));
+      // With skillNames only those skills go; the rest of the entries stay in the manifest.
+      const removing = e => projectClients.includes(e.client) && (!skillNames || skillNames.includes(e.name));
+      candidateEntries = manifest.entries.filter(removing);
+      remainingManifestEntries = manifest.entries.filter(e => !removing(e));
     } else {
-      const extLinks = await findFallbackExternalToolkitLinks(root, resolvedToolkit, clients, homeDirectory);
+      const extLinks = await findFallbackExternalToolkitLinks(root, resolvedToolkit, projectClients, homeDirectory);
       const seenKeys = new Set(extLinks.map(e => `${e.client}:${e.name}`));
       candidateEntries = [...extLinks];
       if (legacyLock) {
         for (const [skillName, meta] of Object.entries(legacyLock.skills ?? {})) {
           const lockClients = Array.isArray(meta?.clients) ? meta.clients : ['codex', 'claude'];
           for (const client of lockClients) {
-            if (!clients.includes(client) || seenKeys.has(`${client}:${skillName}`)) continue;
+            if (!projectClients.includes(client) || seenKeys.has(`${client}:${skillName}`)) continue;
             candidateEntries.push({
               client,
               name: skillName,
@@ -1163,6 +1236,7 @@ export async function planToolkitDetach({
       }
     }
 
+    if (skillNames) candidateEntries = candidateEntries.filter(entry => skillNames.includes(entry.name));
     for (const entry of candidateEntries) {
       if (!SKILL_NAME_RE.test(entry.name)) continue;
       const target = path.join(root, entry.client === 'codex' ? '.agents' : '.claude', 'skills', entry.name);
@@ -1174,7 +1248,7 @@ export async function planToolkitDetach({
         let safeToUnlink = Boolean(manifest);
         try {
           const real = await fs.realpath(target);
-          safeToUnlink = isWithinRoot(real, resolvedToolkit) && !isWithinRoot(real, root);
+          safeToUnlink = (isWithinRoot(real, resolvedToolkit) || isWithinRoot(real, stableVersions)) && !isWithinRoot(real, root);
         } catch (err) {
           if (err.code !== 'ENOENT') throw err;
         }
@@ -1249,7 +1323,7 @@ export async function planToolkitDetach({
   const manualCommands = [];
   if (includeGlobal) {
     const home = await fs.realpath(homeDirectory);
-    const resolvedCodexHome = codexHome ?? path.join(home, '.codex');
+    const resolvedCodexHome = codexHome ?? environment.CODEX_HOME ?? path.join(home, '.codex');
     const bundledSkillsDir = path.join(resolvedToolkit, 'skills');
     const bundledNames = (await fs.readdir(bundledSkillsDir, { withFileTypes: true }).catch(() => []))
       .filter(e => e.isDirectory() && SKILL_NAME_RE.test(e.name))
@@ -1258,24 +1332,25 @@ export async function planToolkitDetach({
 
     for (const client of clients) {
       for (const name of bundledNames) {
-        const expectedSource = path.join(resolvedToolkit, 'skills', name);
-        const target = path.join(home, client === 'codex' ? '.agents' : '.claude', 'skills', name);
+        const target = globalSkillTarget(home, client, name);
         const info = await lstatOrNull(target);
         if (!info?.isSymbolicLink()) continue;
-        try {
-          const [actual, expected] = await Promise.all([fs.realpath(target), fs.realpath(expectedSource)]);
-          if (normalizedPath(actual) === normalizedPath(expected)) {
-            items.push({
-              scope: 'global',
-              client,
-              name,
-              target,
-              relativePath: target,
-              action: 'remove-global-link',
-              reason: 'enlace global de Agent Toolkit'
-            });
-          }
-        } catch {}
+        // Only links that are provably nexakit's: into this copy, the stable copy, an npx cache, or recorded broken.
+        const link = await classifyLink({
+          target, suffix: `skills/${name}`, activeRoots: [resolvedToolkit, actualRoot(home)],
+          isOwned: (at, literal) => isRegistered(registry, at, literal)
+        });
+        if (['instalado', 'efimero', 'roto-propio'].includes(link.state)) {
+          items.push({
+            scope: 'global',
+            client,
+            name,
+            target,
+            relativePath: target,
+            action: 'remove-global-link',
+            reason: 'enlace global de Agent Toolkit'
+          });
+        }
       }
     }
 
@@ -1305,6 +1380,16 @@ export async function planToolkitDetach({
   }
 
   return {
+    reviewInstructions: includeGlobal && !skillNames
+      ? await ownedReviewInstructions({
+          homeDirectory: homeReal,
+          codexHome: codexHome ?? environment.CODEX_HOME ?? path.join(homeReal, '.codex'),
+          agents: clients
+        })
+      : [],
+    homeDirectory: homeReal,
+    reviewCodexHome: codexHome ?? environment.CODEX_HOME ?? path.join(homeReal, ".codex"),
+    reviewAgents: clients,
     applied: false,
     projectRoot: root,
     toolkitRoot: resolvedToolkit,
@@ -1363,6 +1448,18 @@ export async function applyToolkitDetach(plan) {
     throw new Error('Se requiere una vista previa válida de desacoplado.');
   }
 
+  if (plan.reviewInstructions?.length) {
+    const lock = await acquireLock(nexakitDir(plan.homeDirectory));
+    try {
+      await removeReviewInstructions({
+        homeDirectory: plan.homeDirectory,
+        codexHome: plan.reviewCodexHome,
+        agents: plan.reviewAgents
+      }, lock);
+    } finally {
+      await lock.release();
+    }
+  }
   let removedCount = 0;
   let conflicts = 0;
   const updatedItems = [];
@@ -1556,5 +1653,21 @@ export function formatDetachReport(report) {
     for (const cmd of report.manualCommands) lines.push(`  $ ${cmd}`);
   }
 
+  if (report.reviewInstructions?.length) lines.push(`  - Quitar solo el bloque de revisión de ${report.reviewInstructions.join(', ')}`);
   return lines.join('\n') + '\n';
 }
+
+// Generic signals: almost every project has them, and the useful skill is the framework's.
+const GENERIC_SIGNALS = new Set(['nodejs', 'typescript']);
+
+// The technologies found in the project that no catalog skill (nor external reference) covers. Only reported:
+// finding a skill for one is a request the person makes to revisar-skill, never a search nexakit starts alone.
+export function uncoveredSignals({ signals = [], catalog }) {
+  const covered = new Set([
+    ...(catalog?.skills ?? []).flatMap((skill) => skill.matching?.anySignals ?? []),
+    ...(catalog?.externalReferences ?? []).flatMap((ref) => ref.anySignals ?? []),
+  ]);
+  return signals
+    .filter((signal) => !GENERIC_SIGNALS.has(signal.id) && !covered.has(signal.id))
+    .map((signal) => ({ id: signal.id, label: signal.label }));
+}