agdex 0.6.1 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # agdex
 
-Embed compressed documentation indexes into `AGENTS.md` or `CLAUDE.md` for AI coding agents.
+Embed compressed documentation indexes into local agent instruction files.
 
 This package helps AI coding agents (Claude, Cursor, etc.) work with version-matched framework documentation by embedding a compressed docs index directly into your project's markdown file. Based on [Vercel's research](https://vercel.com/blog/teaching-ai-agents-how-to-use-nextjs) showing that embedded docs achieve 100% pass rates compared to 79% for skills.
 
@@ -10,8 +10,9 @@ AI coding agents rely on training data that becomes outdated. When agents don't
 
 1. Downloads version-matched documentation from GitHub
 2. Creates a compressed index (~8KB for Next.js)
-3. Embeds it in your `AGENTS.md` or `CLAUDE.md`
-4. Agents can then retrieve specific docs on demand
+3. Stores the docs in local `.agdex/` cache
+4. Embeds an index in your local agent instruction file
+5. Agents can then retrieve specific docs on demand
 
 The key instruction embedded tells agents to **prefer retrieval-led reasoning over pre-training-led reasoning**.
 
@@ -38,7 +39,7 @@ Create a `.agdexrc.json` file in your project root:
 
 ```json
 {
-  "output": "CLAUDE.md"
+  "output": "CLAUDE.local.md"
 }
 ```
 
@@ -50,7 +51,7 @@ Add an `agdex` field to your `package.json`:
 {
   "name": "my-project",
   "agdex": {
-    "output": "CLAUDE.md"
+    "output": "CLAUDE.local.md"
   }
 }
 ```
@@ -61,7 +62,7 @@ Add an `agdex` field to your `package.json`:
 
 | Option   | Type   | Default     | Description |
 |----------|--------|-------------|-------------|
-| `output` | string | `CLAUDE.md` | Default output file for indexes |
+| `output` | string | `CLAUDE.local.md` | Default output file for indexes |
 
 ## CLI Usage
 
@@ -112,10 +113,10 @@ npx agdex --provider nextjs --description "Project uses App Router only"
 ```bash
 -p, --provider <name>     Documentation provider (nextjs, react, etc.)
 --fw-version <version>    Framework version (auto-detected if not provided)
--o, --output <file>       Target file (default: from config or CLAUDE.md)
+-o, --output <file>       Target file (default: from config or CLAUDE.local.md)
 -d, --description <text>  Additional description to include in the index
--g, --global              Use global cache ~/.cache/agdex/ (default)
--l, --local               Use local .agdex/ instead
+-g, --global              Use global cache ~/.cache/agdex/ instead of local .agdex/
+-l, --local               Use local .agdex/ (default)
 ```
 
 ### Custom GitHub Repository
@@ -209,6 +210,35 @@ npx agdex remove --docs
 npx agdex remove --skills
 ```
 
+### Maintaining Indexes
+
+Successful embeds write local maintenance state to `.agdex/agdex.lock`. The lockfile records the target agent instruction file, marker, source metadata, cache path, and display command for each last-known-good index. It is generated local state and should stay unversioned with `.agdex/`.
+
+Inspect index health:
+
+```bash
+npx agdex status
+npx agdex status --check
+npx agdex status --json
+npx agdex status --output AGENTS.md
+```
+
+Refresh lockfile-backed indexes:
+
+```bash
+npx agdex refresh
+npx agdex refresh --force
+npx agdex refresh --repair
+npx agdex refresh --provider nextjs
+```
+
+Create lockfile entries for existing embedded docs markers when agdex can safely infer marker and cache metadata:
+
+```bash
+npx agdex migrate
+npx agdex migrate --output AGENTS.md
+```
+
 ### List Available Providers
 
 ```bash
@@ -224,7 +254,7 @@ import { embed, nextjsProvider, createProvider } from 'agdex'
 const result = await embed({
   cwd: process.cwd(),
   provider: nextjsProvider,
-  output: 'AGENTS.md'
+  output: 'CLAUDE.local.md'
 })
 
 // Create custom provider
@@ -240,7 +270,7 @@ await embed({
   cwd: process.cwd(),
   provider: myProvider,
   version: '1.0.0',
-  output: 'CLAUDE.md'
+  output: 'CLAUDE.local.md'
 })
 ```
 

package/dist/cli/index.js

@@ -6,11 +6,14 @@ import {
   collectAllSkills,
   collectDocFiles,
   convexProvider,
+  createIndexId,
   createProvider,
+  createStatusReport,
   deltaRsProvider,
   discoverSkillsShRepo,
   embed,
   embedSkills,
+  ensureGitignoreEntry,
   fetchSkillsShSearch,
   ffmpegProvider,
   generateIndex,
@@ -32,19 +35,21 @@ import {
   pixiProvider,
   polarsProvider,
   rattlerBuildProvider,
+  readIndexLockfile,
   removeDocsIndex,
   removeSkillsIndex,
   ruffProvider,
   svelteProvider,
   tailwindProvider,
   tauriProvider,
-  tyProvider
-} from "../index-cm3qmz9v.js";
+  tyProvider,
+  upsertIndexLockEntry
+} from "../index-38fpcrpr.js";
 import {
   __commonJS,
   __require,
   __toESM
-} from "../index-dtcewfnz.js";
+} from "../url-scraper-fme0jdje.js";
 
 // node_modules/commander/lib/error.js
 var require_error = __commonJS((exports) => {
@@ -2109,7 +2114,7 @@ var require_clear = __commonJS((exports, module) => {
         if (it)
           o = it;
         var i = 0;
-        var F = function F2() {};
+        var F = function F() {};
         return { s: F, n: function n() {
           if (i >= o.length)
             return { done: true };
@@ -4441,7 +4446,7 @@ var require_dist = __commonJS((exports, module) => {
         if (it)
           o = it;
         var i = 0;
-        var F = function F2() {};
+        var F = function F() {};
         return { s: F, n: function n() {
           if (i >= o.length)
             return { done: true };
@@ -4544,7 +4549,7 @@ In order to be iterable, non-array objects must have a [Symbol.iterator]() metho
           }
           return question2.format ? yield question2.format(answer2, answers) : answer2;
         });
-        return function getFormattedAnswer2(_x, _x2) {
+        return function getFormattedAnswer(_x, _x2) {
           return _ref.apply(this, arguments);
         };
       }();
@@ -7048,12 +7053,21 @@ function onCancel() {
 Cancelled.`));
   process.exit(0);
 }
+function resolveGlobalCacheOption(options) {
+  if (options.global && options.local) {
+    console.error(import_picocolors2.default.red("Choose either --global or --local, not both."));
+    process.exit(1);
+  }
+  return options.global ? true : false;
+}
 async function runEmbed(options) {
   const cwd = process.cwd();
+  const globalCache = resolveGlobalCacheOption(options);
   if (options.url) {
     await runUrl(options.url, {
       output: options.output,
-      name: options.description
+      name: options.description,
+      global: globalCache
     });
     return;
   }
@@ -7085,8 +7099,7 @@ async function runEmbed(options) {
       provider = result.provider;
       version = result.version;
       output = result.output;
-      const useGlobal = options.local ? false : undefined;
-      await executeEmbed(cwd, provider, version, output, useGlobal, result.description);
+      await executeEmbed(cwd, provider, version, output, globalCache, result.description, version ? "auto" : "unknown");
       return;
     }
   } else {
@@ -7094,8 +7107,7 @@ async function runEmbed(options) {
     provider = result.provider;
     version = result.version;
     output = result.output;
-    const useGlobal = options.local ? false : undefined;
-    await executeEmbed(cwd, provider, version, output, useGlobal, result.description);
+    await executeEmbed(cwd, provider, version, output, globalCache, result.description, version ? "auto" : "unknown");
     return;
   }
   output = options.output || getDefaultOutput();
@@ -7103,10 +7115,9 @@ async function runEmbed(options) {
     console.error(import_picocolors2.default.red(`Provider ${provider.displayName} requires --version flag since auto-detection is not supported.`));
     process.exit(1);
   }
-  const useGlobalCache = options.local ? false : undefined;
-  await executeEmbed(cwd, provider, version, output, useGlobalCache, options.description);
+  await executeEmbed(cwd, provider, version, output, globalCache, options.description, options.fwVersion ? "pinned" : version ? "auto" : "unknown");
 }
-async function executeEmbed(cwd, provider, version, output, globalCache, description) {
+async function executeEmbed(cwd, provider, version, output, globalCache, description, versionMode) {
   let resolvedVersion = version;
   let usingDefaultBranch = false;
   if (!resolvedVersion && provider.urlConfig) {
@@ -7122,8 +7133,10 @@ async function executeEmbed(cwd, provider, version, output, globalCache, descrip
 `));
       resolvedVersion = fallbackBranch;
       usingDefaultBranch = true;
+      versionMode = versionMode || "default-branch";
     } else {
       resolvedVersion = detected.version;
+      versionMode = versionMode || "auto";
     }
   }
   const versionLabel = usingDefaultBranch ? "latest" : resolvedVersion;
@@ -7133,6 +7146,7 @@ Embedding ${import_picocolors2.default.cyan(provider.displayName)} ${import_pico
     cwd,
     provider,
     version: resolvedVersion,
+    versionMode,
     output,
     globalCache,
     description
@@ -7347,15 +7361,17 @@ No providers selected.
   const output = await promptForOutputFile();
   for (const item of selected) {
     const provider = getProvider(item.value);
-    await executeEmbed(cwd, provider, item.version, output, undefined, item.description || undefined);
+    await executeEmbed(cwd, provider, item.version, output, undefined, item.description || undefined, item.version ? "pinned" : "auto");
   }
   process.exit(0);
 }
 async function promptForOutputFile() {
   const defaultOutput = getDefaultOutput();
   const choices = [
-    { title: "AGENTS.md", value: "AGENTS.md" },
+    { title: "CLAUDE.local.md", value: "CLAUDE.local.md" },
+    { title: "AGENTS.local.md", value: "AGENTS.local.md" },
     { title: "CLAUDE.md", value: "CLAUDE.md" },
+    { title: "AGENTS.md", value: "AGENTS.md" },
     { title: "Custom...", value: "__custom__" }
   ];
   const defaultIndex = choices.findIndex((c) => c.value === defaultOutput);
@@ -7562,6 +7578,21 @@ Building index from ${import_picocolors2.default.cyan(docsPath)}...`);
   const newContent = injectIndex(existingContent, indexContent, providerName);
   fs.writeFileSync(targetPath, newContent, "utf-8");
   const sizeAfter = Buffer.byteLength(newContent, "utf-8");
+  upsertIndexLockEntry(cwd, {
+    id: createIndexId("docs", providerName, output),
+    kind: "docs",
+    source: {
+      type: "local-docs",
+      name: providerName,
+      displayName: name,
+      docsPath,
+      versionMode: "unknown"
+    },
+    targetFile: output,
+    marker: providerName,
+    cachePath: absoluteDocsPath,
+    command: `npx agdex local ${docsPath} --name "${name}" --output ${output}`
+  });
   const action = isNewFile ? "Created" : "Updated";
   const sizeInfo = isNewFile ? formatSize(sizeAfter) : `${formatSize(sizeBefore)} → ${formatSize(sizeAfter)}`;
   console.log(`${import_picocolors2.default.green("✓")} ${action} ${import_picocolors2.default.bold(output)} (${sizeInfo})`);
@@ -7569,13 +7600,15 @@ Building index from ${import_picocolors2.default.cyan(docsPath)}...`);
 }
 async function runUrl(url, options) {
   const cwd = process.cwd();
-  const { createUrlProvider } = await import("../url-scraper-5sj8c56t.js");
-  const { pullDocsFromUrl } = await import("../url-scraper-5sj8c56t.js");
+  const { createUrlProvider } = await import("../url-scraper-fme0jdje.js");
+  const { pullDocsFromUrl } = await import("../url-scraper-fme0jdje.js");
   const name = options.name || new URL(url).hostname.replace(/^docs\./, "").replace(/\.\w+$/, "");
   const providerName = name.toLowerCase().replace(/\s+/g, "-");
   const output = options.output || getDefaultOutput();
-  const cacheBase = path.join(os.homedir(), ".cache", "agdex");
-  const docsPath = path.join(cacheBase, providerName);
+  const globalCache = resolveGlobalCacheOption(options);
+  const docsDir = globalCache ? path.join(os.homedir(), ".cache", "agdex", providerName) : path.join(".agdex", providerName);
+  const docsPath = path.isAbsolute(docsDir) ? docsDir : path.join(cwd, docsDir);
+  const docsLinkPath = globalCache ? docsPath : `./${docsDir}`;
   console.log(`
 Scraping documentation from ${import_picocolors2.default.cyan(url)}...`);
   const cacheHit = fs.existsSync(docsPath) && fs.readdirSync(docsPath).length > 0;
@@ -7614,19 +7647,41 @@ ${import_picocolors2.default.green("✓")} Downloaded docs to ${import_picocolor
   const docFiles = collectDocFiles(docsPath, { extensions: [".md"] });
   const sections = buildDocTree(docFiles);
   const indexContent = generateIndex({
-    docsPath,
+    docsPath: docsLinkPath,
     sections,
     outputFile: output,
     providerName: name,
     instruction: `IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any ${name} tasks.`,
-    regenerateCommand: `npx agdex url "${url}" --name "${name}" --output ${output}`
+    regenerateCommand: `npx agdex url "${url}" --name "${name}" --output ${output}${globalCache ? " --global" : ""}`
   });
   const newContent = injectIndex(existingContent, indexContent, providerName);
   fs.writeFileSync(targetPath, newContent, "utf-8");
   const sizeAfter = Buffer.byteLength(newContent, "utf-8");
+  upsertIndexLockEntry(cwd, {
+    id: createIndexId("docs", providerName, output),
+    kind: "docs",
+    source: {
+      type: "url-docs",
+      name: providerName,
+      displayName: name,
+      url,
+      version: "latest",
+      versionMode: "default-branch"
+    },
+    targetFile: output,
+    marker: providerName,
+    cachePath: docsPath,
+    command: `npx agdex url "${url}" --name "${name}" --output ${output}${globalCache ? " --global" : ""}`
+  });
   const action = isNewFile ? "Created" : "Updated";
   const sizeInfo = isNewFile ? formatSize(sizeAfter) : `${formatSize(sizeBefore)} → ${formatSize(sizeAfter)}`;
   console.log(`${import_picocolors2.default.green("✓")} ${action} ${import_picocolors2.default.bold(output)} (${sizeInfo})`);
+  if (!globalCache) {
+    const gitignoreResult = ensureGitignoreEntry(cwd, ".agdex");
+    if (gitignoreResult.updated) {
+      console.log(`${import_picocolors2.default.green("✓")} Added ${import_picocolors2.default.bold(".agdex")} to .gitignore`);
+    }
+  }
   console.log("");
 }
 function runList() {
@@ -7675,10 +7730,191 @@ Sources you can index:
   • Claude Code skills
 
 Run 'agdex' without arguments for interactive mode.`).version("0.4.2");
-program2.command("embed", { isDefault: true }).description("Embed documentation index into AGENTS.md/CLAUDE.md").option("-p, --provider <name>", "Documentation provider (nextjs, react, etc.)").option("--fw-version <version>", "Framework version (auto-detected if not provided)").option("-o, --output <file>", "Target file (default: from config or CLAUDE.md)").option("--repo <owner/repo>", "Custom GitHub repository").option("--docs-path <path>", "Path to docs folder in repository").option("-g, --global", "Store docs in global cache (~/.cache/agdex/) (default)").option("-l, --local", "Store docs in local .agdex/ instead of global cache").option("-d, --description <text>", "Additional description to include in the index").option("-u, --url <url>", "Scrape documentation from a website URL").action(runEmbed);
-program2.command("local <docs-path>").description("Build index from local documentation directory").option("-n, --name <name>", "Display name for the documentation").option("-o, --output <file>", "Target file (default: from config or CLAUDE.md)").option("-e, --extensions <exts>", "File extensions to include (comma-separated, default: .md,.mdx)").action(runLocal);
-program2.command("url <url>").description("Scrape documentation from a website URL and build index").option("-n, --name <name>", "Display name for the documentation (default: derived from URL)").option("-o, --output <file>", "Target file (default: from config or CLAUDE.md)").option("-s, --selector <css>", "CSS selector for main content (default: main#main-content, main, article)").option("-c, --concurrency <n>", "Max concurrent fetches (default: 5)").option("--delay <ms>", "Delay between fetch batches in ms (default: 200)").action(runUrl);
+program2.command("embed", { isDefault: true }).description("Embed documentation index into AGENTS.md/CLAUDE.md").option("-p, --provider <name>", "Documentation provider (nextjs, react, etc.)").option("--fw-version <version>", "Framework version (auto-detected if not provided)").option("-o, --output <file>", "Target file (default: from config or CLAUDE.local.md)").option("--repo <owner/repo>", "Custom GitHub repository").option("--docs-path <path>", "Path to docs folder in repository").option("-g, --global", "Store docs in global cache (~/.cache/agdex/) instead of local .agdex/").option("-l, --local", "Store docs in local .agdex/ (default)").option("-d, --description <text>", "Additional description to include in the index").option("-u, --url <url>", "Scrape documentation from a website URL").action(runEmbed);
+program2.command("local <docs-path>").description("Build index from local documentation directory").option("-n, --name <name>", "Display name for the documentation").option("-o, --output <file>", "Target file (default: from config or CLAUDE.local.md)").option("-e, --extensions <exts>", "File extensions to include (comma-separated, default: .md,.mdx)").action(runLocal);
+program2.command("url <url>").description("Scrape documentation from a website URL and build index").option("-n, --name <name>", "Display name for the documentation (default: derived from URL)").option("-o, --output <file>", "Target file (default: from config or CLAUDE.local.md)").option("-s, --selector <css>", "CSS selector for main content (default: main#main-content, main, article)").option("-c, --concurrency <n>", "Max concurrent fetches (default: 5)").option("--delay <ms>", "Delay between fetch batches in ms (default: 200)").option("-g, --global", "Store docs in global cache (~/.cache/agdex/) instead of local .agdex/").option("-l, --local", "Store docs in local .agdex/ (default)").action(runUrl);
 program2.command("list").description("List available documentation providers").action(runList);
+function runStatus(options) {
+  const report = createStatusReport({
+    cwd: process.cwd(),
+    targetFile: options.output
+  });
+  const unhealthy = report.indexes.filter((index) => index.health !== "ok");
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    printStatusReport(report.indexes, report.scannedFiles);
+  }
+  if (options.check && unhealthy.length > 0) {
+    process.exit(1);
+  }
+}
+function printStatusReport(indexes, scannedFiles) {
+  console.log(import_picocolors2.default.cyan(`
+agdex status
+`));
+  console.log(import_picocolors2.default.gray(`  Scanned: ${scannedFiles.length > 0 ? scannedFiles.join(", ") : "no agent instruction files found"}`));
+  if (indexes.length === 0) {
+    console.log(import_picocolors2.default.yellow(`
+  No indexes found.
+`));
+    return;
+  }
+  console.log("");
+  for (const index of indexes) {
+    const symbol = index.health === "ok" ? import_picocolors2.default.green("✓") : import_picocolors2.default.yellow("!");
+    const source = index.source?.displayName || index.source?.name || index.marker;
+    console.log(`  ${symbol} ${import_picocolors2.default.bold(index.kind)} ${source} ${import_picocolors2.default.gray(`(${index.targetFile})`)}`);
+    console.log(`    health: ${formatHealth(index.health)}`);
+    if (index.cachePath) {
+      console.log(`    cache: ${index.cachePath}`);
+    }
+    if (index.health !== "ok") {
+      console.log(`    action: ${index.suggestedAction}`);
+    }
+  }
+  console.log("");
+}
+function formatHealth(health) {
+  if (health === "ok")
+    return import_picocolors2.default.green(health);
+  return import_picocolors2.default.yellow(health);
+}
+program2.command("status").description("Inspect lockfile-backed index health").option("-o, --output <file>", "Scope status to one agent instruction file").option("--json", "Print machine-readable JSON").option("--check", "Exit non-zero when any discovered index is unhealthy").action(runStatus);
+async function runRefresh(options) {
+  const cwd = process.cwd();
+  const lockfile = readIndexLockfile(cwd);
+  const repairIds = options.repair ? new Set(createStatusReport({ cwd, targetFile: options.output }).indexes.filter((index) => index.lockfileEntry && index.health !== "ok").map((index) => index.id)) : null;
+  const entries = lockfile.indexes.filter((entry) => {
+    if (options.output && entry.targetFile !== options.output)
+      return false;
+    if (options.kind && entry.kind !== options.kind)
+      return false;
+    if (options.provider && entry.source.name !== options.provider && entry.marker !== options.provider)
+      return false;
+    if (repairIds && !repairIds.has(entry.id))
+      return false;
+    return true;
+  });
+  if (entries.length === 0) {
+    console.log(import_picocolors2.default.yellow(`
+No lockfile-backed indexes matched refresh filters.
+`));
+    return;
+  }
+  for (const entry of entries) {
+    if (options.force && entry.kind === "docs") {
+      const cachePath = path.isAbsolute(entry.cachePath) ? entry.cachePath : path.join(cwd, entry.cachePath);
+      if (fs.existsSync(cachePath)) {
+        fs.rmSync(cachePath, { recursive: true, force: true });
+      }
+    }
+    if (entry.kind === "skills") {
+      if (entry.source.type === "skills-sh" && entry.source.repo) {
+        await runSkillsEmbed({ repo: entry.source.repo, output: entry.targetFile });
+      } else {
+        await runSkillsEmbed({ output: entry.targetFile });
+      }
+      continue;
+    }
+    if (entry.source.type === "local-docs" && entry.source.docsPath) {
+      await runLocal(entry.source.docsPath, {
+        name: entry.source.displayName || entry.source.name,
+        output: entry.targetFile
+      });
+      continue;
+    }
+    if (entry.source.type === "url-docs" && entry.source.url) {
+      await runUrl(entry.source.url, {
+        name: entry.source.displayName || entry.source.name,
+        output: entry.targetFile,
+        global: path.isAbsolute(entry.cachePath)
+      });
+      continue;
+    }
+    const provider = entry.source.type === "builtin-provider" ? getProvider(entry.source.name) : entry.source.repo && entry.source.docsPath ? createProvider({
+      name: entry.source.name,
+      displayName: entry.source.displayName || entry.source.name,
+      repo: entry.source.repo,
+      docsPath: entry.source.docsPath
+    }) : null;
+    if (!provider) {
+      console.log(import_picocolors2.default.yellow(`Skipped ${entry.id}: source metadata is incomplete.`));
+      continue;
+    }
+    const version = entry.source.versionMode === "pinned" ? entry.source.version : undefined;
+    await executeEmbed(cwd, provider, version, entry.targetFile, path.isAbsolute(entry.cachePath), undefined, entry.source.versionMode);
+  }
+}
+program2.command("refresh").description("Refresh lockfile-backed indexes").option("-o, --output <file>", "Refresh indexes in one agent instruction file").option("-p, --provider <name>", "Refresh one provider or marker name").option("--kind <kind>", "Refresh only docs or skills indexes").option("--force", "Delete existing documentation caches before refreshing").option("--repair", "Refresh only unhealthy lockfile-backed indexes").action(runRefresh);
+function runMigrate(options) {
+  const cwd = process.cwd();
+  const targets = options.output ? [options.output] : ["AGENTS.md", "AGENTS.local.md", "CLAUDE.md", "CLAUDE.local.md"];
+  const migrated = [];
+  const skipped = [];
+  for (const targetFile of targets) {
+    const targetPath = path.join(cwd, targetFile);
+    if (!fs.existsSync(targetPath))
+      continue;
+    const content = fs.readFileSync(targetPath, "utf-8");
+    const regex = /<!-- AGENTS-MD-EMBED-START:(\S+?) -->\n([\s\S]*?)\n<!-- AGENTS-MD-EMBED-END:\1 -->/g;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+      const marker = match[1];
+      const block = match[2];
+      const rootMatch = block.match(/(?:^|\|)root:\s*([^|]+)/);
+      if (!rootMatch) {
+        skipped.push({ targetFile, marker, reason: "missing root metadata" });
+        continue;
+      }
+      const cachePath = rootMatch[1].trim().replace(/^\.\//, "");
+      const provider = getProvider(marker);
+      const source = provider ? {
+        type: "builtin-provider",
+        name: provider.name,
+        displayName: provider.displayName,
+        repo: provider.repo,
+        docsPath: provider.docsPath,
+        versionMode: "unknown"
+      } : {
+        type: "local-docs",
+        name: marker,
+        displayName: marker,
+        docsPath: cachePath,
+        versionMode: "unknown"
+      };
+      const entry = upsertIndexLockEntry(cwd, {
+        id: createIndexId("docs", marker, targetFile),
+        kind: "docs",
+        source,
+        targetFile,
+        marker,
+        cachePath,
+        command: `npx agdex --provider ${marker} --output ${targetFile}`
+      });
+      migrated.push(entry.id);
+    }
+  }
+  const result = { migrated, skipped };
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(import_picocolors2.default.cyan(`
+agdex migrate
+`));
+  for (const id of migrated) {
+    console.log(`${import_picocolors2.default.green("✓")} Created lockfile entry ${import_picocolors2.default.bold(id)}`);
+  }
+  for (const item of skipped) {
+    console.log(`${import_picocolors2.default.yellow("!")} Skipped ${item.marker} in ${item.targetFile}: ${item.reason}`);
+  }
+  if (migrated.length === 0 && skipped.length === 0) {
+    console.log(import_picocolors2.default.yellow("  No migratable indexes found."));
+  }
+  console.log("");
+}
+program2.command("migrate").description("Create lockfile entries from existing embedded markers when safe").option("-o, --output <file>", "Migrate one agent instruction file").option("--json", "Print machine-readable JSON").action(runMigrate);
 async function runRemove(options) {
   const cwd = process.cwd();
   const output = options.output || getDefaultOutput();
@@ -7778,7 +8014,7 @@ No indices found to remove.
   console.log(import_picocolors2.default.gray(`  (${formatSize(sizeBefore)} → ${formatSize(sizeAfter)})`));
   console.log("");
 }
-program2.command("remove").description("Remove embedded indices from AGENTS.md/CLAUDE.md").option("-o, --output <file>", "Target file (default: from config or CLAUDE.md)").option("--docs", "Remove only docs index").option("--skills", "Remove only skills index").option("-p, --provider <name>", "Remove only a specific provider's docs index").action(runRemove);
+program2.command("remove").description("Remove embedded indices from AGENTS.md/CLAUDE.md").option("-o, --output <file>", "Target file (default: from config or CLAUDE.local.md)").option("--docs", "Remove only docs index").option("--skills", "Remove only skills index").option("-p, --provider <name>", "Remove only a specific provider's docs index").action(runRemove);
 var skillsCommand = program2.command("skills").description("Manage Claude Code skills indexing");
 async function runSkillsEmbed(options) {
   const cwd = process.cwd();
@@ -7838,6 +8074,21 @@ Fetching skills from ${import_picocolors2.default.cyan(repoName)}...`);
     const newContent = injectSkillsIndex(existingContent, indexContent);
     fs.writeFileSync(targetPath, newContent, "utf-8");
     const sizeAfter = Buffer.byteLength(newContent, "utf-8");
+    upsertIndexLockEntry(cwd, {
+      id: createIndexId("skills", `skills-sh:${repoName}`, output),
+      kind: "skills",
+      source: {
+        type: "skills-sh",
+        name: `skills-sh:${repoName}`,
+        displayName: repoName,
+        repo: repoName,
+        versionMode: "default-branch"
+      },
+      targetFile: output,
+      marker: "skills",
+      cachePath: cacheDir,
+      command: `npx agdex skills embed --repo ${repoName}`
+    });
     const action2 = isNewFile ? "Created" : "Updated";
     const sizeInfo2 = isNewFile ? formatSize(sizeAfter) : `${formatSize(sizeBefore)} → ${formatSize(sizeAfter)}`;
     console.log(`${import_picocolors2.default.green("✓")} ${action2} ${import_picocolors2.default.bold(output)} (${sizeInfo2})`);
@@ -7860,6 +8111,20 @@ Discovering skills from ${import_picocolors2.default.cyan(sources.length.toStrin
   const sizeInfo = result.isNewFile ? formatSize(result.sizeAfter) : `${formatSize(result.sizeBefore)} → ${formatSize(result.sizeAfter)}`;
   console.log(`${import_picocolors2.default.green("✓")} ${action} ${import_picocolors2.default.bold(result.targetFile)} (${sizeInfo})`);
   console.log(`${import_picocolors2.default.green("✓")} Indexed ${import_picocolors2.default.bold(result.skillCount.toString())} skills`);
+  upsertIndexLockEntry(cwd, {
+    id: createIndexId("skills", "local-skills", output),
+    kind: "skills",
+    source: {
+      type: "skills-local",
+      name: "local-skills",
+      displayName: "Local skills",
+      versionMode: "unknown"
+    },
+    targetFile: output,
+    marker: "skills",
+    cachePath: cwd,
+    command: "npx agdex skills embed"
+  });
   if (result.sourceBreakdown) {
     const breakdown = [];
     if (result.sourceBreakdown.plugin > 0) {
@@ -8015,8 +8280,8 @@ Selected ${import_picocolors2.default.bold(selected.name)} from ${import_picocol
     process.exit(1);
   }
 }
-skillsCommand.command("embed").description("Embed skills index into AGENTS.md").option("-o, --output <file>", "Target file (default: from config or CLAUDE.md)").option("--plugin <path...>", "Additional plugin repo paths (with plugins/ structure)").option("--plugins", "Include enabled plugins from settings.json (default: true)").option("--no-plugins", "Exclude enabled plugins from settings.json").option("--user", "Include ~/.claude/skills (default: true)").option("--no-user", "Exclude ~/.claude/skills").option("--project", "Include .claude/skills (default: true)").option("--no-project", "Exclude .claude/skills").option("--repo <owner/repo>", "Fetch and index skills from a skills.sh-compatible GitHub repository").action(runSkillsEmbed);
+skillsCommand.command("embed").description("Embed skills index into AGENTS.md").option("-o, --output <file>", "Target file (default: from config or CLAUDE.local.md)").option("--plugin <path...>", "Additional plugin repo paths (with plugins/ structure)").option("--plugins", "Include enabled plugins from settings.json (default: true)").option("--no-plugins", "Exclude enabled plugins from settings.json").option("--user", "Include ~/.claude/skills (default: true)").option("--no-user", "Exclude ~/.claude/skills").option("--project", "Include .claude/skills (default: true)").option("--no-project", "Exclude .claude/skills").option("--repo <owner/repo>", "Fetch and index skills from a skills.sh-compatible GitHub repository").action(runSkillsEmbed);
 skillsCommand.command("list").description("List discovered skills").option("--plugin <path...>", "Additional plugin repo paths (with plugins/ structure)").option("--plugins", "Include enabled plugins from settings.json (default: true)").option("--no-plugins", "Exclude enabled plugins from settings.json").option("--user", "Include ~/.claude/skills (default: true)").option("--no-user", "Exclude ~/.claude/skills").option("--project", "Include .claude/skills (default: true)").option("--no-project", "Exclude .claude/skills").action(runSkillsList);
-skillsCommand.command("local <skills-path>").description("Index skills from a local path").option("-o, --output <file>", "Target file (default: from config or CLAUDE.md)").option("-n, --name <name>", "Label for this skill source").action(runSkillsLocal);
+skillsCommand.command("local <skills-path>").description("Index skills from a local path").option("-o, --output <file>", "Target file (default: from config or CLAUDE.local.md)").option("-n, --name <name>", "Label for this skill source").action(runSkillsLocal);
 skillsCommand.command("find [query]").description("Search skills.sh for agent skills").option("-l, --limit <n>", "Max results (default: 20)", parseInt).option("-o, --output <file>", "Target file for embedding").action(runSkillsFind);
 program2.parse();