@dotdotgod/cli 0.6.5 → 0.6.7

package/README.md

@@ -1,5 +1,10 @@
 # @dotdotgod/cli
 
+Without an explicit project or global `embedding` profile, search uses keywords
+without loading/downloading models or creating vector indexes. Configured profiles
+enable hybrid retrieval; `--search keyword` always skips embeddings and unconfigured
+`--search vector` fails with setup guidance. Graph impact follows the same opt-in.
+
 [![npm version](https://img.shields.io/npm/v/@dotdotgod/cli.svg)](https://www.npmjs.com/package/@dotdotgod/cli) [![GitHub](https://img.shields.io/badge/GitHub-dotdotgod%2Fdotdotgod--kit-181717?logo=github)](https://github.com/dotdotgod/dotdotgod-kit/tree/main/packages/cli) [![License: Elastic 2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://github.com/dotdotgod/dotdotgod-kit/blob/main/LICENSE)
 
 Command-line tools for dotdotgod project memory.
@@ -45,7 +50,7 @@ dotdotgod graph serve . --changed <path>
 - `init` creates `AGENTS.md`, thin agent entrypoints, docs indexes, active-plan space, archive map, local cache ignores, and the complete editable default config.
 - `validate` checks docs/project-memory rules; `--check-index` also checks graph and outline freshness without parsing, embedding or repair.
 - `index` builds graph shards and `.dotdotgod/outlines.json` with source hashes, declarations, comments and exact ranges.
-- `query` defaults to hybrid vector/keyword search over full Markdown and code outlines/comments, not implementation bodies. Use `--scope docs|code|all`, `--search hybrid|keyword|vector` and `--limit 30`. Keyword mode works without embeddings; hybrid reports vector failures and retains keyword results. Remote code-metadata embedding requires `--allow-code-embedding`. Local E5 remains the default when its optional runtime is installed. Tree-sitter coverage and boundaries: [CODE_OUTLINES.md](../../docs/spec/cli/CODE_OUTLINES.md).
+- `query` defaults to hybrid vector/keyword search over full Markdown and code outlines/comments, not implementation bodies. Use `--scope docs|code|all`, `--search hybrid|keyword|vector` and `--limit 30`. Keyword mode works without embeddings; hybrid reports vector failures and retains keyword results. Selecting a remote embedding provider authorizes sending documentation and code metadata (names, signatures, and comments), without implementation bodies or an additional consent flag. Local E5 remains the default when its optional runtime is installed. Tree-sitter coverage and boundaries: [CODE_OUTLINES.md](../../docs/spec/cli/CODE_OUTLINES.md).
 - `resolve` and `expand` map explicit or high-signal prompt references to project files and can include related impact evidence.
 - `graph impact` ranks likely related specs, tests, docs, commands, and source files for one or more changed paths, with a combined ranking and per-file top five. Non-seed scores use fixed weighted PPR connection `80` plus memory policy `20`. A bounded request-local multilingual vector overlay participates in PPR when the query cache is available; vector preparation failures degrade to structural-only results.
 - `graph serve` starts a local read-only explorer rooted at one or more changed files. It keeps only connected shared structural nodes, lays them out by minimum structural hop, and supports persisted instant, layer, or one-by-one reveal modes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/cli",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "CLI for dotdotgod validation, hybrid document/code-outline search, and graph indexing.",
   "type": "module",
   "license": "Elastic-2.0",

package/src/claude-plans.mjs

@@ -0,0 +1,41 @@
+import { existsSync, lstatSync, readFileSync, realpathSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join, relative, resolve, isAbsolute } from 'node:path';
+
+// Preflight before initialization writes anything. Never follow settings symlinks.
+export function prepareClaudePlans(root, documentationRoot) {
+  const path = join(root, '.claude', 'settings.json');
+  for (const target of [join(root, '.claude'), path]) {
+    try {
+      if (lstatSync(target).isSymbolicLink()) throw new Error(`Refusing symlink: ${target}`);
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  const base = resolve(root);
+  if (existsSync(dirname(path))) {
+    const rel = relative(realpathSync(base), realpathSync(dirname(path)));
+    if (rel.startsWith('..') || isAbsolute(rel)) throw new Error('Claude settings must stay inside the project.');
+  }
+  const current = existsSync(path) ? readFileSync(path, 'utf8') : null;
+  const settings = current === null ? {} : JSON.parse(current);
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) throw new Error('Claude settings must be a JSON object.');
+  const value = `./${documentationRoot}/plan`;
+  if (Object.hasOwn(settings, 'plansDirectory')) return {
+    status: 'skipped', path, reason: 'Existing plansDirectory preserved.', value: settings.plansDirectory,
+  };
+  return { status: current === null ? 'created' : 'updated', path, value, current,
+    content: `${JSON.stringify({ ...settings, plansDirectory: value }, null, 2)}\n` };
+}
+
+export function applyClaudePlans(prepared, dryRun) {
+  const { content, current, ...result } = prepared;
+  if (!content) return result;
+  if (dryRun) return { ...result, status: `would_${result.status === 'created' ? 'create' : 'update'}` };
+  for (const target of [dirname(prepared.path), prepared.path]) {
+    try { if (lstatSync(target).isSymbolicLink()) throw new Error(`Refusing symlink: ${target}`); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  const latest = existsSync(prepared.path) ? readFileSync(prepared.path, 'utf8') : null;
+  if (latest !== current) throw new Error('Claude settings changed during initialization; retry without overwriting them.');
+  mkdirSync(dirname(prepared.path), { recursive: true });
+  writeFileSync(prepared.path, content, { flag: current === null ? 'wx' : 'w' });
+  return result;
+}

package/src/cli/usage.mjs

@@ -11,9 +11,10 @@ export function commandUsage(command = 'root') {
   dotdotgod validate <root> [--include-local-memory] [--check-index] [--max-lines n] [--max-chars n] [--no-link-check] [--json]`;
     case 'init':
       return `Usage:
-  dotdotgod init <root> [--project-name NAME] [--template NAME] [--documentation-root PATH] [--dotdot-setting] [--dry-run] [--json]
+  dotdotgod init <root> [--project-name NAME] [--template NAME] [--documentation-root PATH] [--dotdot-setting] [--claude-plans] [--dry-run] [--json]
 
-Create AGENTS.md, agent entrypoints, docs indexes, a project config from an initialization template, and local memory gitignore entries.`;
+Create AGENTS.md, agent entrypoints, docs indexes, a project config from an initialization template, and local memory gitignore entries.
+Use --claude-plans only after opting into project-local native plan storage; existing Claude settings are preserved.`;
     case 'index':
       return `Usage:
   dotdotgod index <root> [--json]`;
@@ -33,9 +34,9 @@ Create dotdotgod.config.json from a bundled or user template. Without --template
   dotdotgod status <root> [--json]`;
     case 'query':
       return `Usage:
-  dotdotgod query <root> <query> [--limit n] [--scope docs|code|all] [--search hybrid|keyword|vector] [--allow-code-embedding] [--json]
+  dotdotgod query <root> <query> [--limit n] [--scope docs|code|all] [--search hybrid|keyword|vector] [--json]
 
-Search full documentation and code outlines/comments. Default: hybrid docs+code. Remote code metadata requires explicit consent.`;
+Search full documentation and code outlines/comments. Default: hybrid docs+code. Selecting a remote embedding profile authorizes code metadata transmission.`;
     case 'embedding':
       return `Usage:
   dotdotgod embedding status [<root>] [--json]
@@ -167,4 +168,3 @@ export function parseCommon(argv) {
   options.root = resolve(options.root);
   return options;
 }
-

package/src/commands/config.mjs

@@ -42,7 +42,7 @@ function formatConfigOutput(payload) {
   lines.push(`- path: ${payload.path ?? 'none'}`);
   lines.push(`- documentation root: ${payload.config.documentation.root}`);
   lines.push(`- memory areas: ${payload.config.areas.length}`);
-  lines.push(`- embedding: ${payload.embedding.profile.provider}/${payload.embedding.profile.model} (${payload.embedding.source})`);
+  lines.push(`- embedding: ${payload.embedding.profile ? `${payload.embedding.profile.provider}/${payload.embedding.profile.model}` : 'not configured; keyword search'} (${payload.embedding.source})`);
   lines.push(`- traceability required: ${(payload.config.traceability.required ?? []).join(', ') || 'none'}`);
   lines.push(`- traceability exclude: ${(payload.config.traceability.exclude ?? []).join(', ') || 'none'}`);
   lines.push('- traceability keys:');
@@ -92,7 +92,7 @@ export function runConfig(argv) {
     embedding = { source: resolved.source, path: resolved.path, profile: sanitizeEmbeddingProfile(resolved.profile) };
   } catch (error) {
     errors.push({ file: 'embedding config', code: 'EMBEDDING_CONFIG_INVALID', message: error instanceof Error ? error.message : String(error) });
-    embedding = { source: 'invalid', path: null, profile: sanitizeEmbeddingProfile({ provider: 'local', model: 'Xenova/multilingual-e5-small' }) };
+    embedding = { source: 'invalid', path: null, profile: null };
   }
   const payload = { ok: errors.length === 0, command: 'config', root: options.root, source: config.source ?? 'default', path: config.source && config.source !== 'default' ? join(options.root, config.source) : null, embedding, config: memoryConfigSummary(config), errors };
   if (options.json) console.log(JSON.stringify(payload, null, 2));

package/src/commands/embedding.mjs

@@ -19,6 +19,12 @@ export function runEmbedding(argv, options = {}) {
   const parsed = parse(argv);
   if (!['status', 'install'].includes(parsed.action)) usage(`Unknown embedding command: ${parsed.action}`, 'embedding');
   const resolved = resolveEmbeddingProfile(parsed.root, options);
+  if (!resolved.profile) {
+    if (parsed.action === 'install') throw new Error('Configure an explicit local embedding profile before installing its runtime.');
+    const result = { ok: true, command: 'embedding status', provider: null, required: false, installed: false, installAvailable: false, source: 'not-configured' };
+    console.log(parsed.json ? JSON.stringify(result, null, 2) : 'Embedding is not configured; keyword search is used.');
+    return result;
+  }
   if (resolved.profile.provider !== 'local') {
     const result = { ok: true, command: `embedding ${parsed.action}`, provider: resolved.profile.provider, required: false, installed: false, installAvailable: false };
     console.log(parsed.json ? JSON.stringify(result, null, 2) : 'Local embedding runtime is not required for the configured remote provider.');

package/src/commands/query.mjs

@@ -1,18 +1,20 @@
 import { resolve } from 'node:path';
+import { vectorCacheSession } from '../query/cache-session.mjs';
 import { usage } from '../cli/usage.mjs';
 import { readMemoryConfig } from '../memory/config.mjs';
 import { collectDocumentationChunks } from '../query/chunks.mjs';
 import { resolveEmbedder } from '../query/embedder.mjs';
-import { isValidNormalizedVectorValues, profileFingerprint, readVectorCache, writeVectorCache } from '../query/store.mjs';
+import { resolveEmbeddingProfile } from '../query/embedding-config.mjs';
+import { isValidNormalizedVectorValues, profileFingerprint, writeVectorCache } from '../query/store.mjs';
 
-import { projectCorpus, keywordCandidates, fuseCandidates, attachRelationships, assertCodeEmbeddingConsent } from '../query/hybrid.mjs';
+import { projectCorpus, keywordCandidates, fuseCandidates, attachRelationships } from '../query/hybrid.mjs';
 
 const DEFAULT_LIMIT = 30;
 const MAX_LIMIT = 100;
 const EMBED_BATCH_SIZE = 16;
 
 export function parseQueryOptions(argv) {
-  const options = { root: '.', query: '', limit: DEFAULT_LIMIT, json: false, scope: 'all', search: 'hybrid', allowCodeEmbedding: false };
+  const options = { root: '.', query: '', limit: DEFAULT_LIMIT, json: false, scope: 'all', search: 'hybrid' };
   let rootSet = false;
   const queryParts = [];
   for (let i = 0; i < argv.length; i += 1) {
@@ -20,7 +22,6 @@ export function parseQueryOptions(argv) {
     if (arg === '--json') options.json = true;
     else if (arg === '--scope') { options.scope = argv[++i]; if (!['docs', 'code', 'all'].includes(options.scope)) usage('--scope must be docs, code or all.', 'query'); }
     else if (arg === '--search') { options.search = argv[++i]; if (!['hybrid', 'keyword', 'vector'].includes(options.search)) usage('--search must be hybrid, keyword or vector.', 'query'); }
-    else if (arg === '--allow-code-embedding') options.allowCodeEmbedding = true;
     else if (arg === '--limit') { const value = Number(argv[++i]); if (!Number.isInteger(value) || value < 1 || value > MAX_LIMIT) usage(`--limit must be an integer from 1 to ${MAX_LIMIT}.`, 'query'); options.limit = value; }
     else if (arg.startsWith('-')) usage(`Unknown option: ${arg}`, 'query');
     else if (!rootSet) { options.root = resolve(arg); rootSet = true; }
@@ -69,7 +70,12 @@ export async function buildVectorIndex(root, embedOrOptions = {}) {
   const config = readMemoryConfig(root);
   const exclude = config.load?.documentationSummary?.exclude ?? ['docs/plan', 'docs/archive'];
   const chunks = options.chunks ?? collectDocumentationChunks(root, exclude, config.documentation?.root ?? 'docs');
-  const cached = readVectorCache(root, resolved.identity);
+  return vectorCacheSession(root, resolved.identity, async (state, save, diagnostics) => {
+  const selectedFingerprints = new Set(chunks.map((chunk) => chunk.fingerprint));
+  state.pending = state.pending.filter((row) => selectedFingerprints.has(row.chunk.fingerprint));
+  const recovered = new Set(state.pending.map((row) => row.chunk.fingerprint));
+  const cacheRows = [...state.docs, ...state.code, ...state.pending];
+  const cached = state.dimensions ? { chunks: cacheRows.map((row) => row.chunk), vectors: Float32Array.from(cacheRows.flatMap((row) => row.vector)), manifest: { dimensions: state.dimensions } } : null;
   const cachedOffsets = new Map((cached?.chunks ?? []).map((chunk, index) => [chunk.fingerprint, index]));
   const rows = new Array(chunks.length);
   const missing = []; let reused = 0;
@@ -77,16 +83,38 @@ export async function buildVectorIndex(root, embedOrOptions = {}) {
   for (let offset = 0; offset < missing.length; offset += EMBED_BATCH_SIZE) {
     const batch = missing.slice(offset, offset + EMBED_BATCH_SIZE);
     const embedded = await resolved.embed(batch.map(({ chunk }) => chunk.passage), 'document');
-    embedded.forEach((vector, index) => { rows[batch[index].index] = vector; });
+    if (!Array.isArray(embedded) || embedded.length !== batch.length) throw new Error('Embedder returned an unexpected vector count.');
+    embedded.forEach((vector, index) => {
+      const dimensions = state.dimensions ?? vector.length;
+      assertVector(vector, dimensions, 'Passage vector');
+      state.dimensions = dimensions;
+      rows[batch[index].index] = vector;
+      const { passage, ...chunk } = batch[index].chunk;
+      state.pending.push({ chunk, vector: Array.from(vector) });
+    });
+    save();
   }
   const dimensions = rows[0]?.length ?? cached?.manifest?.dimensions;
-  if (!dimensions) throw new Error('No documentation chunks were available to establish vector dimensions.');
+  if (!dimensions && chunks.length) throw new Error('No documentation chunks were available to establish vector dimensions.');
   if (rows.some((row) => !row || row.length !== dimensions)) throw new Error('Embedder returned inconsistent passage-vector dimensions.');
   const vectors = new Float32Array(chunks.length * dimensions);
   rows.forEach((row, index) => { assertVector(row, dimensions, 'Passage vector'); vectors.set(row, index * dimensions); });
   const storedChunks = chunks.map(({ passage, ...chunk }) => chunk);
-  const manifest = writeVectorCache(root, storedChunks, vectors, { provider: resolved.profile.provider, model: resolved.profile.model, dimensions, profileFingerprint: profileFingerprint(resolved.identity), excluded: exclude, embedded: missing.length, reused });
+  const refreshed = options.corpora ?? (options.chunks ? [...new Set(chunks.map((chunk) => chunk.kind === 'symbol' ? 'code' : 'docs'))] : ['docs']);
+  const counters = {};
+  for (const corpus of refreshed) {
+    const positions = chunks.map((chunk, index) => ({ chunk, index })).filter(({ chunk }) => (chunk.kind === 'symbol' ? 'code' : 'docs') === corpus);
+    state[corpus] = positions.map(({ index }) => ({ chunk: storedChunks[index], vector: Array.from(rows[index]) }));
+    counters[corpus] = { chunks: positions.length, embedded: missing.filter(({ chunk }) => (chunk.kind === 'symbol' ? 'code' : 'docs') === corpus).length, recovered: positions.filter(({ chunk }) => recovered.has(chunk.fingerprint)).length };
+    counters[corpus].reused = positions.length - counters[corpus].embedded;
+  }
+  state.pending = [];
+  save();
+  const metadata = { provider: resolved.profile.provider, model: resolved.profile.model, dimensions, profileFingerprint: profileFingerprint(resolved.identity), excluded: exclude, embedded: missing.length, reused, diagnostics: { ...diagnostics, corpora: counters } };
+  // Keep the legacy export readable; authoritative snapshots remain atomic above.
+  const manifest = dimensions ? writeVectorCache(root, storedChunks, vectors, metadata) : { chunks: 0, ...metadata };
   return { chunks: storedChunks, vectors, manifest, embedding: resolved };
+  });
 }
 
 export async function queryDocumentation(root, query, options = {}) {
@@ -107,11 +135,16 @@ export async function queryProject(root, query, options = {}) {
   const corpus = await projectCorpus(root, scope);
   const keyword = search === 'vector' ? [] : keywordCandidates(query, corpus.chunks);
   let vector = []; let index; let vectorError;
-  if (search !== 'keyword' && corpus.chunks.length) {
+  let configured = false;
+  if (search !== 'keyword') {
+    try { configured = Boolean(options.profile || options.embed || resolveEmbeddingProfile(root, options).profile); }
+    catch (error) { if (search === 'vector') throw error; vectorError = error.message; }
+    if (!configured && !vectorError && search === 'vector') throw new Error('Embedding is not configured. Set embedding in project or global configuration to use vector search.');
+  }
+  if (search !== 'keyword' && configured) {
     try {
-      assertCodeEmbeddingConsent(root, options, corpus.chunks);
-      index = await buildVectorIndex(root, { ...options, chunks: corpus.chunks });
-      const [queryVector] = await index.embedding.embed([query], 'query');
+      index = await buildVectorIndex(root, { ...options, chunks: corpus.chunks, corpora: scope === 'all' ? ['docs', 'code'] : [scope] });
+      const [queryVector] = index.chunks.length ? await index.embedding.embed([query], 'query') : [];
       vector = index.chunks.map((chunk, position) => ({ ...chunk, vectorScore: cosineScore(queryVector, index.vectors, position * index.manifest.dimensions, index.manifest.dimensions) }))
         .sort((a, b) => b.vectorScore - a.vectorScore || a.id.localeCompare(b.id));
     } catch (error) {

package/src/impact/vector-overlay.mjs

@@ -1,4 +1,5 @@
 import { buildVectorIndex, rankVectorFiles } from '../commands/query.mjs';
+import { resolveEmbeddingProfile } from '../query/embedding-config.mjs';
 
 import { buildChangedFileProfile, canonicalizeChangedPath } from './vector-profile.mjs';
 
@@ -16,6 +17,7 @@ export async function buildVectorImpactOverlay(root, index, changedPaths, option
   const threshold = semantic.threshold ?? 0.5;
   const topK = semantic.topKPerFile ?? 5;
   try {
+    if (!options.profile && !options.embed && !options.buildIndex && !resolveEmbeddingProfile(root, options).profile) return { status: 'disabled', edges: [], diagnostics: { enabled: false, reason: 'Embedding is not configured.' } };
     const vectorIndex = await (options.buildIndex ?? buildVectorIndex)(root, options);
     const edges = [];
     const normalizedChangedPaths = [...new Set(changedPaths.map((path) => canonicalizeChangedPath(root, path)).filter(Boolean))];

package/src/init.mjs

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'no
 import { basename, dirname, join, resolve } from 'node:path';
 import { builtInTemplateData, builtInTemplateScaffold, resolveInitializationTemplate } from './config/templates.mjs';
 import { isValidDocumentationRoot, normalizeDocumentationRoot, readMemoryConfig } from './memory/config.mjs';
+import { prepareClaudePlans, applyClaudePlans } from './claude-plans.mjs';
 
 function action(status, path, extra = {}) {
   return { status, path, ...extra };
@@ -19,6 +20,7 @@ function parseInitOptions(argv) {
     if (arg === '--json') options.json = true;
     else if (arg === '--dotdot-setting') options.dotdotSetting = true;
     else if (arg === '--dry-run') options.dryRun = true;
+    else if (arg === '--claude-plans') options.claudePlans = true;
     else if (arg === '--project-name' || arg === '--template' || arg === '--documentation-root') {
       const value = argv[i + 1];
       if (!value || value.startsWith('-')) throw new Error(`${arg} requires a value`);
@@ -310,6 +312,15 @@ export function runInit(argv, usage) {
     }
   }
 
+  if (options.claudePlans && !options.documentationRootExplicit && existsSync(join(options.root, 'dotdotgod.config.json'))) {
+    options.documentationRoot = readMemoryConfig(options.root).documentation.root;
+  }
+  let claudePlans;
+  if (options.claudePlans) {
+    try { claudePlans = prepareClaudePlans(options.root, options.documentationRoot); }
+    catch (error) { initError(options, 'CLAUDE_SETTINGS_INVALID', error.message); }
+  }
+
   if (!options.dryRun) mkdirSync(options.root, { recursive: true });
 
   const configExists = existsSync(join(options.root, 'dotdotgod.config.json'));
@@ -335,6 +346,11 @@ export function runInit(argv, usage) {
 
   for (const entry of [`${options.documentationRoot}/plan`, `${options.documentationRoot}/archive`, '.dotdotgod']) ensureGitignoreEntry(options, entry, actions);
 
+  if (claudePlans) {
+    try { actions.push(applyClaudePlans(claudePlans, options.dryRun)); }
+    catch (error) { initError(options, 'CLAUDE_SETTINGS_CHANGED', error.message); }
+  }
+
   const payload = { ok: true, command: 'init', root: options.root, projectName: options.projectName, documentationRoot: options.documentationRoot, dryRun: options.dryRun, dotdotSetting: options.dotdotSetting, template: template ? { name: template.name, source: template.source, selectedBy: template.selectedBy } : null, actions };
   if (options.json) console.log(JSON.stringify(payload, null, 2));
   else {

package/src/query/cache-session.mjs

@@ -0,0 +1,82 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, openSync, closeSync, readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { isValidNormalizedVectorValues, readVectorCache, profileFingerprint } from './store.mjs';
+
+// One atomic state file keeps completed snapshots and unfinished batches consistent.
+export async function vectorCacheSession(root, identity, action) {
+  const directory = join(root, '.dotdotgod', 'vectors');
+  mkdirSync(directory, { recursive: true });
+  const lock = join(directory, 'build.lock');
+  const token = randomUUID();
+  const started = Date.now();
+  let waited = false;
+  while (true) {
+    try {
+      const fd = openSync(lock, 'wx');
+      try { writeFileSync(fd, JSON.stringify({ pid: process.pid, token })); } finally { closeSync(fd); }
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      waited = true;
+      if (Date.now() - started >= 30000) throw new Error('Vector cache lock timed out; another build may be running or the lock needs inspection.');
+      try {
+        const owner = JSON.parse(readFileSync(lock, 'utf8'));
+        if (!Number.isInteger(owner.pid) || owner.pid < 1) throw new Error('Invalid lock owner.');
+        try { process.kill(owner.pid, 0); }
+        catch (probe) {
+          if (probe.code !== 'ESRCH') throw probe;
+          const recovery = `${lock}.recovery`;
+          try { mkdirSync(recovery); }
+          catch (claim) { if (claim.code === 'EEXIST') { await sleep(50); continue; } throw claim; }
+          try {
+            const current = JSON.parse(readFileSync(lock, 'utf8'));
+            if (current.token === owner.token && current.pid === owner.pid) rmSync(lock);
+          } finally { rmSync(recovery, { recursive: true, force: true }); }
+          continue;
+        }
+      } catch (probe) { if (probe.code === 'ENOENT') continue; }
+      await sleep(50);
+    }
+  }
+  try {
+    const path = join(directory, 'snapshots.json');
+    const fingerprint = profileFingerprint(identity);
+    let state; let reason = 'missing';
+    try {
+      state = JSON.parse(readFileSync(path, 'utf8'));
+      if (state.schema !== 1) { reason = 'schema-mismatch'; state = null; }
+      else if (state.profile !== fingerprint) { reason = 'profile-mismatch'; state = null; }
+      else {
+        if (state.dimensions !== null && (!Number.isInteger(state.dimensions) || state.dimensions < 1)) throw new Error('Invalid cache dimensions.');
+        for (const rows of [state.docs, state.code, state.pending]) {
+          if (!Array.isArray(rows) || rows.some((row) => typeof row.chunk?.fingerprint !== 'string' || !Array.isArray(row.vector) || row.vector.length !== state.dimensions || !isValidNormalizedVectorValues(row.vector, state.dimensions))) throw new Error('Invalid cache rows.');
+        }
+        reason = 'valid';
+      }
+    } catch (error) { state = null; reason = error.code === 'ENOENT' ? 'missing' : 'corrupt'; }
+    if (!state) {
+      state = { schema: 1, profile: fingerprint, dimensions: null, docs: [], code: [], pending: [] };
+      if (reason === 'missing') {
+        const legacyDiagnostics = {};
+        const legacy = readVectorCache(root, identity, legacyDiagnostics);
+        reason = legacyDiagnostics.reason;
+        if (legacy) {
+          state.dimensions = legacy.manifest.dimensions;
+          legacy.chunks.forEach((chunk, i) => state[chunk.kind === 'symbol' ? 'code' : 'docs'].push({ chunk, vector: Array.from(legacy.vectors.subarray(i * state.dimensions, (i + 1) * state.dimensions)) }));
+          reason = 'legacy-migrated';
+        }
+      }
+    }
+    const save = () => {
+      const temporary = `${path}.tmp-${token}`;
+      try { writeFileSync(temporary, JSON.stringify(state)); renameSync(temporary, path); }
+      finally { rmSync(temporary, { force: true }); }
+    };
+    return await action(state, save, { reason, lockWaitMs: waited ? Date.now() - started : 0 });
+  } finally {
+    try { if (JSON.parse(readFileSync(lock, 'utf8')).token === token) rmSync(lock); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+}

package/src/query/embedder.mjs

@@ -1,4 +1,4 @@
-import { embeddingInputFormat, embeddingProfileIdentity, resolveEmbeddingProfile } from './embedding-config.mjs';
+import { DEFAULT_EMBEDDING_PROFILE, embeddingInputFormat, embeddingProfileIdentity, resolveEmbeddingProfile } from './embedding-config.mjs';
 import { importTransformers } from './embedding-runtime.mjs';
 
 const localPipelines = new Map();
@@ -93,7 +93,8 @@ export async function createEmbedder(profile) {
 }
 
 export async function resolveEmbedder(root, options = {}) {
-  const resolved = options.profile ? { profile: options.profile, source: options.source ?? 'injected', path: null } : resolveEmbeddingProfile(root, options);
+  const resolved = options.profile || options.embed ? { profile: options.profile ?? DEFAULT_EMBEDDING_PROFILE, source: options.source ?? 'injected', path: null } : resolveEmbeddingProfile(root, options);
+  if (!resolved.profile) throw new Error('Embedding is not configured. Set embedding in project or global configuration to use vector search.');
   return { ...resolved, identity: embeddingProfileIdentity(resolved.profile), embed: options.embed ? withInputFormat(options.embed, resolved.profile) : await createEmbedder(resolved.profile) };
 }
 

package/src/query/embedding-config.mjs

@@ -44,6 +44,7 @@ export function validateEmbeddingProfile(profile, label = 'embedding') {
 }
 
 export function sanitizeEmbeddingProfile(profile) {
+  if (!profile) return null;
   const { apiKey, ...safe } = profile;
   return { ...safe, ...(apiKey ? { apiKey: '[redacted]' } : {}) };
 }
@@ -64,5 +65,5 @@ export function resolveEmbeddingProfile(root = '.', options = {}) {
   if (projectConfig && Object.hasOwn(projectConfig, 'embedding')) return { profile: validateEmbeddingProfile(projectConfig.embedding, 'project embedding'), source: 'project', path: projectPath };
   const globalConfig = readJson(globalPath, 'global config');
   if (globalConfig && Object.hasOwn(globalConfig, 'embedding')) return { profile: validateEmbeddingProfile(globalConfig.embedding, 'global embedding'), source: 'global', path: globalPath };
-  return { profile: { ...DEFAULT_EMBEDDING_PROFILE }, source: 'default', path: null };
+  return { profile: null, source: 'not-configured', path: null };
 }

package/src/query/hybrid.mjs

@@ -1,6 +1,5 @@
 import { collectDocumentationChunks } from './chunks.mjs';
 import { readMemoryConfig } from '../memory/config.mjs';
-import { resolveEmbeddingProfile } from './embedding-config.mjs';
 import { buildOutlines, outlineChunks } from '../symbols/store.mjs';
 import { addOutlineGraph } from '../symbols/graph.mjs';
 
@@ -47,11 +46,6 @@ export async function projectCorpus(root, scope) {
   const outlines = scope === 'docs' ? null : await buildOutlines(root);
   return { chunks: [...docs, ...(outlines ? outlineChunks(outlines) : [])], outlines };
 }
-export function assertCodeEmbeddingConsent(root, options, chunks) {
-  if (!chunks.some((chunk) => chunk.kind === 'symbol')) return;
-  const profile = options.profile ?? resolveEmbeddingProfile(root).profile;
-  if (profile.provider !== 'local' && options.allowCodeEmbedding !== true) throw new Error('Remote code-metadata embedding requires --allow-code-embedding; use --search keyword or --scope docs instead.');
-}
 export function attachRelationships(results, outlines) {
   if (!outlines) return results;
   const graph = addOutlineGraph({ nodes: [], edges: [] }, outlines);

package/src/query/store.mjs

@@ -29,20 +29,25 @@ export function vectorCachePaths(root) {
   return { directory, manifest: join(directory, 'manifest.json'), chunks: join(directory, 'chunks.jsonl'), embeddings: join(directory, 'embeddings.f32') };
 }
 
-export function readVectorCache(root, identity = null) {
+export function readVectorCache(root, identity = null, diagnostics = {}) {
+  diagnostics.reason = 'missing';
   const paths = vectorCachePaths(root);
   if (!existsSync(paths.manifest) || !existsSync(paths.chunks) || !existsSync(paths.embeddings)) return null;
   try {
     const manifest = JSON.parse(readFileSync(paths.manifest, 'utf8'));
+    diagnostics.reason = 'schema-mismatch';
     if (manifest.schemaVersion !== VECTOR_SCHEMA_VERSION || !Number.isInteger(manifest.dimensions) || manifest.dimensions < 1) return null;
+    diagnostics.reason = 'profile-mismatch';
     if (identity && manifest.profileFingerprint !== profileFingerprint(identity)) return null;
+    diagnostics.reason = 'corrupt';
     const chunks = readFileSync(paths.chunks, 'utf8').split('\n').filter(Boolean).map((line) => JSON.parse(line));
     const buffer = readFileSync(paths.embeddings);
     if (buffer.byteLength !== chunks.length * manifest.dimensions * 4) return null;
     const vectors = new Float32Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 4);
     if (!isValidNormalizedVectorValues(vectors, manifest.dimensions)) return null;
+    diagnostics.reason = 'valid';
     return { manifest, chunks, vectors: new Float32Array(vectors) };
-  } catch { return null; }
+  } catch { diagnostics.reason = 'corrupt'; return null; }
 }
 
 function atomicWrite(path, data) {

package/src/symbols/languages.mjs

@@ -11,7 +11,7 @@ export const SOURCE_EXTENSIONS = new Set([
   ...Object.values(LANGUAGE_EXTENSIONS).flat(), '.c', '.h', '.kt', '.kts', '.swift',
   '.scala', '.clj', '.cljs', '.ex', '.exs', '.erl', '.hrl', '.lua', '.pl', '.pm', '.r', '.R', '.sql', '.m', '.mm', '.zsh', '.fish',
 ]);
-export const EXTRACTOR_ID = 'outline-v3:vscode-tree-sitter-wasm-0.3.1';
+export const EXTRACTOR_ID = 'outline-v4:vscode-0.3.1:typescript-import-types-1';
 export function languageForPath(path) {
   return Object.entries(LANGUAGE_EXTENSIONS).find(([, extensions]) => extensions.includes(extname(path)))?.[0] ?? null;
 }

package/src/symbols/parser.mjs

@@ -1,5 +1,5 @@
-import { dirname, join } from 'node:path';
-import { parserEntry, loadParserApi } from './runtime.mjs';
+import { dirname } from 'node:path';
+import { parserEntry, loadParserApi, languageAsset } from './runtime.mjs';
 import { createHash } from 'node:crypto';
 import { COMMENT_TYPES, DECLARATIONS } from './languages.mjs';
 
@@ -13,7 +13,7 @@ async function parserFor(language) {
     return { api, directory: dirname(entry) };
   })();
   const { api, directory } = await runtime;
-  if (!languages.has(language)) languages.set(language, api.Language.load(join(directory, `tree-sitter-${language}.wasm`)));
+  if (!languages.has(language)) languages.set(language, api.Language.load(languageAsset(language)));
   const loaded = await languages.get(language);
   const parser = new api.Parser();
   parser.setLanguage(loaded);

package/src/symbols/parsers/README.md

@@ -0,0 +1,24 @@
+# Patched TypeScript Grammars
+
+TypeScript and TSX WASM are generated from tree-sitter-typescript 0.23.2
+(npm integrity sha512-e04JUUKxTT53/x3Uq1zIL45DoYKVfHH4CZqwgZhPg5qYROl5nQjV+85ruFzFGZxu+QeFVbRTPDRnqL9UbU4VeA==),
+with tree-sitter-javascript 0.23.1, tree-sitter-cli 0.25.10, and emsdk 4.0.4.
+The MIT license is retained as TYPESCRIPT_LICENSE.
+
+The small source patch in ../typescript-import-grammar.mjs adds import types as
+primary types and typeof operands with their own conflict/precedence handling.
+It fixes generic typeof-import calls and qualified import-type arrays without
+changing application text or hiding tree-sitter error nodes.
+
+To regenerate, extract the pinned npm grammar into a disposable directory, install
+its exact JavaScript dependency without lifecycle scripts
+(`npm install --ignore-scripts --omit=dev --no-package-lock tree-sitter-javascript@0.23.1`), then run from checkout:
+
+```sh
+TREE_SITTER_CLI=/path/to/tree-sitter-0.25.10 node scripts/build-typescript-parsers.mjs /path/to/extracted/package --docker
+pnpm run generate
+```
+
+Docker builds use emscripten/emsdk:4.0.4. Other language grammars and the runtime
+remain supplied by @vscode/tree-sitter-wasm 0.3.1. Runtime and grammar hashes
+participate in outline cache identity; adapters copy these same patched assets.

package/src/symbols/parsers/TYPESCRIPT_LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Max Brunsfeld
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/symbols/runtime.mjs

@@ -6,6 +6,10 @@ import { createHash } from 'node:crypto';
 import { LANGUAGE_EXTENSIONS } from './languages.mjs';
 
 const require = createRequire(import.meta.url);
+export function languageAsset(language) {
+  const patched = fileURLToPath(new URL(`./parsers/tree-sitter-${language}.wasm`, import.meta.url));
+  return existsSync(patched) ? patched : join(dirname(parserEntry()), `tree-sitter-${language}.wasm`);
+}
 export function parserEntry() {
   const bundled = fileURLToPath(new URL('./parsers/tree-sitter.cjs', import.meta.url));
   return existsSync(bundled) ? bundled : require.resolve('@vscode/tree-sitter-wasm');
@@ -15,7 +19,8 @@ export function parserIdentity() {
   if (!identity) {
     const entry = parserEntry();
     const hash = createHash('sha256').update(readFileSync(entry));
-    for (const name of ['tree-sitter.wasm', ...Object.keys(LANGUAGE_EXTENSIONS).map((language) => `tree-sitter-${language}.wasm`)]) hash.update(name).update(readFileSync(join(dirname(entry), name)));
+    hash.update(readFileSync(join(dirname(entry), 'tree-sitter.wasm')));
+    for (const language of Object.keys(LANGUAGE_EXTENSIONS)) hash.update(language).update(readFileSync(languageAsset(language)));
     identity = hash.digest('hex');
   }
   return identity;

package/src/symbols/typescript-import-grammar.mjs

@@ -0,0 +1,13 @@
+// Applied to pinned tree-sitter-typescript 0.23.2 before parser generation.
+export function patchTypescriptGrammar(source) {
+  const replacements = [
+    ['conflicts: ($, previous) => previous.concat([', 'conflicts: ($, previous) => previous.concat([\n      [$.import, $.import_type],'],
+    ['primary_type: $ => choice(', 'primary_type: $ => choice(\n        $.import_type,'],
+    ["      type_query: $ => prec.right(seq(\n        'typeof',\n        choice(", "      import_type: $ => prec.right('call', seq(\n        'import', '(', $.string, ')',\n        repeat(seq('.', $._type_identifier)),\n        optional($.type_arguments),\n      )),\n\n      type_query: $ => prec.right(seq(\n        'typeof',\n        choice(\n          $.import_type,"],
+  ];
+  for (const [before, after] of replacements) {
+    if (!source.includes(before)) throw new Error('Unsupported TypeScript grammar source.');
+    source = source.replace(before, after);
+  }
+  return source;
+}