@dotdotgod/cli 0.2.4 → 0.2.6

package/README.md

@@ -4,7 +4,7 @@
 
 Command-line tools for dotdotgod project memory.
 
-Use this package when you want to initialize a docs-first project scaffold, validate project-memory docs, build a local graph/cache, load bounded context snapshots, expand project references, or ask what should be checked after a file changes.
+Use this package when you want to initialize a docs-first project scaffold, validate project-memory docs, build a local graph/cache, search shared documentation locally, expand project references, or ask what should be checked after a file changes.
 
 These commands implement dotdotgod's project-memory loop — init, load, plan, impact — for shells, scripts, CI, and any agent without a dedicated adapter.
 
@@ -27,16 +27,16 @@ Common first commands:
 ```bash
 dotdotgod init .
 dotdotgod validate .
-dotdotgod load-snapshot .
+dotdotgod query . "project documentation"
 dotdotgod graph impact . --changed <path> --compact
 ```
 
 ## What It Does
 
-- `init` creates `AGENTS.md`, thin agent entrypoints, docs indexes, active-plan space, archive map, and local cache ignores.
+- `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 the dotdotgod docs/project-memory structure, local links, traceability blocks, config validity, and optional index freshness.
 - `index` builds `.dotdotgod/manifest.json` and compact graph shards from maintained project files.
-- `load-snapshot` returns a bounded first-pass project map for AI agents, including files pinned through the `load.pinnedPaths`/`load.pinnedBodies` config so context such as code conventions stays visible on every load.
+- `query` locally embeds shared Markdown with `Xenova/multilingual-e5-small`, incrementally stores vectors under `.dotdotgod/vectors/`, and returns the best-ranked chunk from each relevant Markdown file.
 - `resolve` and `expand` map explicit or high-signal prompt references to project files.
 - `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.
 - `traceability links` checks or repairs generated Markdown traceability-link sections.
@@ -56,7 +56,7 @@ dotdotgod config .
 dotdotgod config init .
 dotdotgod status .
 dotdotgod index .
-dotdotgod load-snapshot .
+dotdotgod query . "plan mode tools"
 dotdotgod resolve . PLAN_MODE
 dotdotgod expand . "Update [[PLAN_MODE]] and [[HOOKS]]"
 dotdotgod expand . "PLAN_MODE 수정하자" --fuzzy
@@ -80,7 +80,7 @@ dotdotgod graph communities .
 | Add the dotdotgod scaffold to a repository | `dotdotgod init .` |
 | Check docs, links, config, traceability, and optional index freshness | `dotdotgod validate . --check-index` |
 | Refresh the local graph/cache | `dotdotgod index .` |
-| Give an agent a bounded project map | `dotdotgod load-snapshot .` |
+| Search shared project documentation locally | `dotdotgod query . "project documentation"` |
 | Resolve `[[...]]` references from a prompt | `dotdotgod expand . "Update [[PLAN_MODE]]"` |
 | Repair generated traceability-link sections | `dotdotgod traceability links . --write` |
 | Validate an active plan before execution | `dotdotgod plan validate docs/plan/<task>/README.md` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dotdotgod/cli",
-  "version": "0.2.4",
-  "description": "CLI for dotdotgod validation, project memory snapshots, and graph indexing.",
+  "version": "0.2.6",
+  "description": "CLI for dotdotgod validation, local documentation search, and graph indexing.",
   "type": "module",
   "license": "Elastic-2.0",
   "publishConfig": {
@@ -29,6 +29,7 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@huggingface/transformers": "^4.2.0",
     "leiden-ts": "^0.1.0"
   },
   "homepage": "https://github.com/dotdotgod/dotdotgod-kit/tree/main/packages/cli#readme",

package/src/cli/usage.mjs

@@ -11,7 +11,7 @@ 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] [--dotdot-setting] [--force] [--dry-run] [--json]
+  dotdotgod init <root> [--project-name NAME] [--dotdot-setting] [--dry-run] [--json]
 
 Create AGENTS.md, agent entrypoints, docs indexes, and local memory gitignore entries.`;
     case 'index':
@@ -20,20 +20,22 @@ Create AGENTS.md, agent entrypoints, docs indexes, and local memory gitignore en
     case 'config':
       return `Usage:
   dotdotgod config <root> [--json]
-  dotdotgod config init <root> [--force] [--json]
+  dotdotgod config init <root> [--json]
 
 Inspect or initialize the project-level dotdotgod config file.`;
     case 'config init':
       return `Usage:
-  dotdotgod config init <root> [--force] [--json]
+  dotdotgod config init <root> [--json]
 
 Create dotdotgod.config.json with the built-in default memory, traceability, validation, and impact ranking policy.`;
     case 'status':
       return `Usage:
   dotdotgod status <root> [--json]`;
-    case 'load-snapshot':
+    case 'query':
       return `Usage:
-  dotdotgod load-snapshot <root> [--json]`;
+  dotdotgod query <root> <query> [--limit n] [--json]
+
+Search shared project documentation with the local multilingual E5 vector index.`;
     case 'plan':
       return `Usage:
   dotdotgod plan validate docs/plan/<task-slug>/README.md [--stage stage] [--json]
@@ -97,12 +99,12 @@ Ranks nodes related to one or more changed files. <root> is the project root; re
   dotdotgod [--version|-v]
   dotdotgod help [command]
   dotdotgod validate <root> [--include-local-memory] [--check-index] [--max-lines n] [--max-chars n] [--no-link-check] [--json]
-  dotdotgod init <root> [--project-name NAME] [--dotdot-setting] [--force] [--dry-run] [--json]
+  dotdotgod init <root> [--project-name NAME] [--dotdot-setting] [--dry-run] [--json]
   dotdotgod index <root> [--json]
   dotdotgod config <root> [--json]
-  dotdotgod config init <root> [--force] [--json]
+  dotdotgod config init <root> [--json]
   dotdotgod status <root> [--json]
-  dotdotgod load-snapshot <root> [--json]
+  dotdotgod query <root> <query> [--limit n] [--json]
   dotdotgod resolve <root> <ref> [--max-results n] [--include-archive] [--json]
   dotdotgod expand <root> <prompt> [--max-results n] [--include-archive] [--with-impact] [--fuzzy] [--json]
   dotdotgod traceability links <root> [--check|--write] [--json]

package/src/commands/config.mjs

@@ -3,13 +3,12 @@ import { join, resolve } from 'node:path';
 import { usage } from '../cli/usage.mjs';
 import { defaultDotdotgodConfigText, memoryConfigSummary, readMemoryConfig } from '../memory/config.mjs';
 
-function parseConfigOptions(argv, allowForce = false, usageKey = 'config') {
-  const options = { root: '.', json: false, force: false };
+function parseConfigOptions(argv, usageKey = 'config') {
+  const options = { root: '.', json: false };
   let rootSet = false;
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--json') options.json = true;
-    else if (allowForce && arg === '--force') options.force = true;
     else if (!arg.startsWith('-') && !rootSet) {
       options.root = arg;
       rootSet = true;
@@ -20,12 +19,8 @@ function parseConfigOptions(argv, allowForce = false, usageKey = 'config') {
   return options;
 }
 
-function configSourcePath(root, source) {
-  return source && source !== 'default' ? join(root, source) : null;
-}
-
 function configInitError(options, code, message, path = null) {
-  const payload = { ok: false, command: 'config init', root: options.root, path, created: false, overwritten: false, error: { code, message } };
+  const payload = { ok: false, command: 'config init', root: options.root, path, created: false, error: { code, message } };
   if (options.json) {
     console.log(JSON.stringify(payload, null, 2));
     process.exit(2);
@@ -60,7 +55,7 @@ function formatConfigOutput(payload) {
 
 export function runConfig(argv) {
   const isInit = argv[0] === 'init';
-  const options = parseConfigOptions(isInit ? argv.slice(1) : argv, isInit, isInit ? 'config init' : 'config');
+  const options = parseConfigOptions(isInit ? argv.slice(1) : argv, isInit ? 'config init' : 'config');
   if (isInit) {
     if (!existsSync(options.root)) configInitError(options, 'ROOT_NOT_FOUND', `Project root not found: ${options.root}`);
     try {
@@ -69,20 +64,17 @@ export function runConfig(argv) {
       configInitError(options, 'ROOT_NOT_FOUND', `Project root not found: ${options.root}`);
     }
     const target = join(options.root, 'dotdotgod.config.json');
-    const rcPath = join(options.root, '.dotdotgodrc.json');
-    if (existsSync(rcPath)) configInitError(options, 'CONFIG_RC_EXISTS', `.dotdotgodrc.json already exists; remove or migrate it before initializing dotdotgod.config.json.`, rcPath);
-    const existed = existsSync(target);
-    if (existed && !options.force) configInitError(options, 'CONFIG_EXISTS', `dotdotgod.config.json already exists. Re-run with --force to overwrite it.`, target);
+    if (existsSync(target)) configInitError(options, 'CONFIG_EXISTS', 'dotdotgod.config.json already exists.', target);
     writeFileSync(target, defaultDotdotgodConfigText());
-    const payload = { ok: true, command: 'config init', root: options.root, path: target, created: !existed, overwritten: existed };
+    const payload = { ok: true, command: 'config init', root: options.root, path: target, created: true };
     if (options.json) console.log(JSON.stringify(payload, null, 2));
-    else console.log(`dotdotgod config init: ${existed ? 'overwrote' : 'created'} ${target}`);
+    else console.log(`dotdotgod config init: created ${target}`);
     return;
   }
 
   const config = readMemoryConfig(options.root);
   const errors = config.errors ?? [];
-  const payload = { ok: errors.length === 0, command: 'config', root: options.root, source: config.source ?? 'default', path: configSourcePath(options.root, config.source), config: memoryConfigSummary(config), errors };
+  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, config: memoryConfigSummary(config), errors };
   if (options.json) console.log(JSON.stringify(payload, null, 2));
   else console.log(formatConfigOutput(payload));
   if (errors.length > 0) process.exit(1);

package/src/commands/query.mjs

@@ -0,0 +1,122 @@
+import { resolve } from 'node:path';
+import { usage } from '../cli/usage.mjs';
+import { readMemoryConfig } from '../memory/config.mjs';
+import { collectDocumentationChunks } from '../query/chunks.mjs';
+import { embedTexts } from '../query/embedder.mjs';
+import { readVectorCache, VECTOR_DIMENSIONS, VECTOR_MODEL, writeVectorCache } from '../query/store.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 };
+  let rootSet = false;
+  const queryParts = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') options.json = 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;
+    } else queryParts.push(arg);
+  }
+  options.query = queryParts.join(' ').trim();
+  if (!options.query) usage('query requires search text.', 'query');
+  return options;
+}
+
+function cosine(left, vectors, offset) {
+  let score = 0;
+  for (let index = 0; index < VECTOR_DIMENSIONS; index += 1) score += left[index] * vectors[offset + index];
+  return score;
+}
+
+function lexicalBoost(query, chunk) {
+  const queryTerms = new Set(query.toLowerCase().split(/[^\p{L}\p{N}_.:/-]+/u).filter((term) => term.length > 1));
+  if (queryTerms.size === 0) return 0;
+  const haystack = `${chunk.path} ${chunk.heading}`.toLowerCase();
+  let matches = 0;
+  for (const term of queryTerms) if (haystack.includes(term)) matches += 1;
+  return Math.min(0.08, (matches / queryTerms.size) * 0.08);
+}
+
+export async function buildVectorIndex(root, embed = embedTexts) {
+  const config = readMemoryConfig(root);
+  const exclude = config.load?.documentationSummary?.exclude ?? ['docs/plan', 'docs/archive'];
+  const chunks = collectDocumentationChunks(root, exclude);
+  const cached = readVectorCache(root);
+  const cachedOffsets = new Map((cached?.chunks ?? []).map((chunk, index) => [chunk.fingerprint, index * VECTOR_DIMENSIONS]));
+  const vectors = new Float32Array(chunks.length * VECTOR_DIMENSIONS);
+  const missing = [];
+  let reused = 0;
+  chunks.forEach((chunk, index) => {
+    const oldOffset = cachedOffsets.get(chunk.fingerprint);
+    if (oldOffset === undefined || !cached) missing.push({ chunk, index });
+    else {
+      vectors.set(cached.vectors.subarray(oldOffset, oldOffset + VECTOR_DIMENSIONS), index * VECTOR_DIMENSIONS);
+      reused += 1;
+    }
+  });
+  for (let offset = 0; offset < missing.length; offset += EMBED_BATCH_SIZE) {
+    const batch = missing.slice(offset, offset + EMBED_BATCH_SIZE);
+    const embedded = await embed(batch.map(({ chunk }) => `passage: ${chunk.passage}`));
+    embedded.forEach((vector, index) => vectors.set(vector, batch[index].index * VECTOR_DIMENSIONS));
+  }
+  const storedChunks = chunks.map(({ passage, ...chunk }) => chunk);
+  const manifest = writeVectorCache(root, storedChunks, vectors, {
+    excluded: exclude,
+    embedded: missing.length,
+    reused,
+  });
+  return { chunks: storedChunks, vectors, manifest };
+}
+
+export async function queryDocumentation(root, query, options = {}) {
+  const embed = options.embed ?? embedTexts;
+  const limit = options.limit ?? DEFAULT_LIMIT;
+  const index = await buildVectorIndex(root, embed);
+  const [queryVector] = await embed([`query: ${query}`]);
+  const rankedChunks = index.chunks.map((chunk, position) => {
+    const vectorScore = cosine(queryVector, index.vectors, position * VECTOR_DIMENSIONS);
+    return { ...chunk, score: Number((vectorScore + lexicalBoost(query, chunk)).toFixed(6)), vectorScore: Number(vectorScore.toFixed(6)) };
+  }).sort((left, right) => right.score - left.score || left.path.localeCompare(right.path));
+  const results = [];
+  const seenPaths = new Set();
+  for (const chunk of rankedChunks) {
+    if (seenPaths.has(chunk.path)) continue;
+    seenPaths.add(chunk.path);
+    results.push(chunk);
+    if (results.length === limit) break;
+  }
+  return { ok: true, command: 'query', root, query, model: VECTOR_MODEL, dimensions: VECTOR_DIMENSIONS, limit, index: index.manifest, results };
+}
+
+function formatQueryResult(payload) {
+  const lines = [`dotdotgod query: ${payload.query}`, `- model: ${payload.model}`, `- results: ${payload.results.length}`];
+  payload.results.forEach((result, index) => {
+    lines.push(`${index + 1}. ${result.path}${result.heading ? ` — ${result.heading}` : ''} (${result.score.toFixed(3)})`);
+    const excerpt = result.text.replace(/\s+/g, ' ').trim().slice(0, 240);
+    if (excerpt) lines.push(`   ${excerpt}${result.text.length > 240 ? '…' : ''}`);
+  });
+  return lines.join('\n');
+}
+
+export async function runQuery(argv) {
+  const options = parseQueryOptions(argv);
+  try {
+    const payload = await queryDocumentation(options.root, options.query, options);
+    if (options.json) console.log(JSON.stringify(payload, null, 2));
+    else console.log(formatQueryResult(payload));
+  } catch (error) {
+    const message = `dotdotgod query failed: ${error instanceof Error ? error.message : String(error)}`;
+    if (options.json) console.log(JSON.stringify({ ok: false, command: 'query', root: options.root, query: options.query, error: message }, null, 2));
+    else console.error(message);
+    process.exitCode = 1;
+  }
+}

package/src/core.mjs

@@ -3,7 +3,7 @@ import { commandUsage, hasHelpToken, helpCommandFromArgs, isHelpToken, isVersion
 import { runValidate } from './validate/run.mjs';
 import { runIndex, runStatus } from './index/cache.mjs';
 import { runConfig } from './commands/config.mjs';
-import { runLoadSnapshot } from './commands/load-snapshot.mjs';
+import { runQuery } from './commands/query.mjs';
 import { runResolve, runExpand } from './reference/resolve.mjs';
 import { runTraceability } from './commands/traceability.mjs';
 import { runGraph } from './commands/graph.mjs';
@@ -19,7 +19,7 @@ export { DEFAULT_IMPACT_RANKING_POLICY, DEFAULT_INTEGRATIONS_POLICY, DEFAULT_LOA
 export { buildCommunities, relationWeight } from './graph/communities.mjs';
 export { addEdge, addNode, compactGraph, expandGraph, graphStats, jsonSize, shardFile, writeJson } from './graph/store.mjs';
 export { cacheFile, collectIndexFiles, fingerprint, shouldIndexPath } from './index/files.mjs';
-export { buildMemoryAreas, buildPinnedFiles, detectCommandGuidance, detectPackageManager } from './load-snapshot/summary.mjs';
+export { buildMemoryAreas, buildPinnedFiles, detectCommandGuidance, detectPackageManager } from './memory/summary.mjs';
 export { isReadmeIndexPath, retrievalMetadataForPath } from './graph/metadata.mjs';
 export { buildGraph } from './graph/extract.mjs';
 export { addDeterministicSemanticEdges } from './graph/semantic.mjs';
@@ -28,7 +28,9 @@ export { runValidate } from './validate/run.mjs';
 export { buildImpactReport, buildCompactImpactReport } from './impact/report.mjs';
 export { formatCompactImpactOutput, formatYmlGraphImpactError, formatYmlImpactOutput } from './impact/format.mjs';
 export { runConfig } from './commands/config.mjs';
-export { runLoadSnapshot } from './commands/load-snapshot.mjs';
+export { buildVectorIndex, parseQueryOptions, queryDocumentation, runQuery } from './commands/query.mjs';
+export { chunkMarkdown, collectDocumentationChunks, collectDocumentationMarkdown, textFingerprint } from './query/chunks.mjs';
+export { readVectorCache, VECTOR_DIMENSIONS, VECTOR_MODEL, VECTOR_SCHEMA_VERSION, vectorCachePaths, writeVectorCache } from './query/store.mjs';
 export { extractBracketReferences, extractFuzzyReferences, normalizeReferenceAlias } from './reference/extract.mjs';
 export { resolveReferenceCandidates, runResolve, runExpand } from './reference/resolve.mjs';
 export { parseTraceabilityOptions, runTraceability } from './commands/traceability.mjs';
@@ -53,7 +55,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   else if (command === 'index') runIndex(args);
   else if (command === 'config') runConfig(args);
   else if (command === 'status') runStatus(args);
-  else if (command === 'load-snapshot') runLoadSnapshot(args);
+  else if (command === 'query') await runQuery(args);
   else if (command === 'resolve') runResolve(args);
   else if (command === 'expand') runExpand(args);
   else if (command === 'traceability') runTraceability(args);

package/src/index/files.mjs

@@ -14,7 +14,7 @@ const INDEX_TEXT_EXTENSIONS = new Set([
 ]);
 const INDEX_TEXT_FILENAMES = new Set([
   'AGENTS.md', 'CLAUDE.md', 'CODEX.md', 'README', 'README.md', 'LICENSE', 'NOTICE', 'CHANGELOG', 'CHANGELOG.md', 'CONTRIBUTING.md', 'SECURITY.md', 'AUTHORS', 'CODEOWNERS', '.gitignore', '.editorconfig',
-  'dotdotgod.config.json', '.dotdotgodrc.json', 'package.json', 'pnpm-workspace.yaml', 'tsconfig.json', 'jsconfig.json',
+  'dotdotgod.config.json', 'package.json', 'pnpm-workspace.yaml', 'tsconfig.json', 'jsconfig.json',
   'Dockerfile', 'Containerfile', 'Makefile', 'Justfile', 'Procfile', 'Rakefile', 'Gemfile', 'go.mod', 'go.sum', 'Cargo.toml', 'Cargo.lock', 'pyproject.toml', 'requirements.txt', 'Pipfile', 'Pipfile.lock', 'poetry.lock', 'deno.json', 'deno.jsonc', 'bunfig.toml',
   '.env.example', '.env.sample', '.env.template',
 ]);

package/src/init.mjs

@@ -1,24 +1,22 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
+import { defaultDotdotgodConfigText } from './memory/config.mjs';
 
 function action(status, path, extra = {}) {
   return { status, path, ...extra };
 }
 
 function formatAction(item) {
-  const extras = [];
-  if (item.backup) extras.push(`backup=${item.backup}`);
-  if (item.add) extras.push(`add=${item.add}`);
-  return `${item.status.padEnd(13)} ${item.path}${extras.length > 0 ? ` ${extras.join(' ')}` : ''}`;
+  const extra = item.add ? ` add=${item.add}` : '';
+  return `${item.status.padEnd(13)} ${item.path}${extra}`;
 }
 
 function parseInitOptions(argv) {
-  const options = { root: null, projectName: '', dotdotSetting: false, force: false, dryRun: false, json: false };
+  const options = { root: null, projectName: '', dotdotSetting: false, dryRun: false, json: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--json') options.json = true;
     else if (arg === '--dotdot-setting') options.dotdotSetting = true;
-    else if (arg === '--force') options.force = true;
     else if (arg === '--dry-run') options.dryRun = true;
     else if (arg === '--project-name') {
       const value = argv[i + 1];
@@ -50,25 +48,19 @@ function initError(options, code, message) {
 
 function writeInitFile(options, relativePath, content, actions) {
   const target = join(options.root, relativePath);
-  if (existsSync(target) && !options.force) {
+  if (existsSync(target)) {
     actions.push(action('skipped', target));
     return;
   }
 
-  let backup = '';
-  if (existsSync(target) && options.force) {
-    backup = `${target}.bak.${new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z')}`;
-    if (!options.dryRun) renameSync(target, backup);
-  }
-
   if (options.dryRun) {
-    actions.push(action(backup ? 'would_replace' : 'would_create', target, backup ? { backup } : {}));
+    actions.push(action('would_create', target));
     return;
   }
 
   mkdirSync(dirname(target), { recursive: true });
-  writeFileSync(target, `${content}\n`);
-  actions.push(action(backup ? 'replaced' : 'created', target, backup ? { backup } : {}));
+  writeFileSync(target, content.endsWith('\n') ? content : `${content}\n`);
+  actions.push(action('created', target));
 }
 
 function ensureGitignoreEntry(options, entry, actions) {
@@ -298,9 +290,12 @@ export function runInit(argv, usage) {
 
   const actions = [];
   for (const [relativePath, content] of initFiles(options)) writeInitFile(options, relativePath, content, actions);
+
+  writeInitFile(options, 'dotdotgod.config.json', defaultDotdotgodConfigText(), actions);
+
   for (const entry of ['docs/plan', 'docs/archive', '.dotdotgod']) ensureGitignoreEntry(options, entry, actions);
 
-  const payload = { ok: true, command: 'init', root: options.root, projectName: options.projectName, dryRun: options.dryRun, force: options.force, dotdotSetting: options.dotdotSetting, actions };
+  const payload = { ok: true, command: 'init', root: options.root, projectName: options.projectName, dryRun: options.dryRun, dotdotSetting: options.dotdotSetting, actions };
   if (options.json) console.log(JSON.stringify(payload, null, 2));
   else for (const item of actions) console.log(formatAction(item));
 }

package/src/memory/config.mjs

@@ -3,7 +3,7 @@ import { join, resolve } from 'node:path';
 import { rel } from '../common/paths.mjs';
 import { isKebabCase } from '../docs/markdown.mjs';
 
-const MEMORY_CONFIG_FILES = ['dotdotgod.config.json', '.dotdotgodrc.json'];
+const MEMORY_CONFIG_FILE = 'dotdotgod.config.json';
 const MEMORY_SCOPES = new Set(['shared', 'local']);
 const MEMORY_FRESHNESS = new Set(['fresh', 'stale']);
 export const DEFAULT_TRACEABILITY_POLICY = {
@@ -533,27 +533,24 @@ export function validateMemoryConfigData(data, root = '.', file = 'dotdotgod.con
 }
 
 export function readMemoryConfig(root = '.') {
-  for (const name of MEMORY_CONFIG_FILES) {
-    const path = join(root, name);
-    if (!existsSync(path)) continue;
-    try {
-      const data = JSON.parse(readFileSync(path, 'utf8'));
-      const errors = validateMemoryConfigData(data, root, name);
-      if (errors.length > 0) return { ...defaultMemoryConfig(), source: name, errors };
-      const configuredAreas = data.memory?.areas?.map(normalizeMemoryArea) ?? [];
-      const traceability = data.traceability === undefined ? cloneTraceabilityPolicy() : normalizeTraceabilityPolicy(data.traceability);
-      const validation = data.validation === undefined ? cloneValidationPolicy() : normalizeValidationPolicy(data.validation);
-      const impactRanking = normalizeImpactRankingPolicy(data.impactRanking);
-      const referenceExpansion = normalizeReferenceExpansionPolicy(data.referenceExpansion);
-      const integrations = normalizeIntegrationsPolicy(data.integrations);
-      const load = normalizeLoadPolicy(data.load);
-      const planMode = normalizePlanModePolicy(data.planMode);
-      return configuredAreas.length > 0 ? { source: name, areas: configuredAreas, traceability, validation, impactRanking, referenceExpansion, integrations, load, planMode, errors: [] } : { ...defaultMemoryConfig(), traceability, validation, impactRanking, referenceExpansion, integrations, load, planMode, source: name, errors: [] };
-    } catch (error) {
-      return { ...defaultMemoryConfig(), source: name, errors: [{ file: name, code: 'MEMORY_CONFIG_INVALID_JSON', message: `Invalid JSON: ${error instanceof Error ? error.message : String(error)}\nFix: repair ${name} so it is valid JSON, or regenerate the default config with \`dotdotgod config init <root> --force\` if you want to reset it.` }] };
-    }
+  const path = join(root, MEMORY_CONFIG_FILE);
+  if (!existsSync(path)) return defaultMemoryConfig();
+  try {
+    const data = JSON.parse(readFileSync(path, 'utf8'));
+    const errors = validateMemoryConfigData(data, root, MEMORY_CONFIG_FILE);
+    if (errors.length > 0) return { ...defaultMemoryConfig(), source: MEMORY_CONFIG_FILE, errors };
+    const configuredAreas = data.memory?.areas?.map(normalizeMemoryArea) ?? [];
+    const traceability = data.traceability === undefined ? cloneTraceabilityPolicy() : normalizeTraceabilityPolicy(data.traceability);
+    const validation = data.validation === undefined ? cloneValidationPolicy() : normalizeValidationPolicy(data.validation);
+    const impactRanking = normalizeImpactRankingPolicy(data.impactRanking);
+    const referenceExpansion = normalizeReferenceExpansionPolicy(data.referenceExpansion);
+    const integrations = normalizeIntegrationsPolicy(data.integrations);
+    const load = normalizeLoadPolicy(data.load);
+    const planMode = normalizePlanModePolicy(data.planMode);
+    return configuredAreas.length > 0 ? { source: MEMORY_CONFIG_FILE, areas: configuredAreas, traceability, validation, impactRanking, referenceExpansion, integrations, load, planMode, errors: [] } : { ...defaultMemoryConfig(), traceability, validation, impactRanking, referenceExpansion, integrations, load, planMode, source: MEMORY_CONFIG_FILE, errors: [] };
+  } catch (error) {
+    return { ...defaultMemoryConfig(), source: MEMORY_CONFIG_FILE, errors: [{ file: MEMORY_CONFIG_FILE, code: 'MEMORY_CONFIG_INVALID_JSON', message: `Invalid JSON: ${error instanceof Error ? error.message : String(error)}\nFix: repair ${MEMORY_CONFIG_FILE} so it is valid JSON, or remove it before regenerating the default config with \`dotdotgod config init <root>\`.` }] };
   }
-  return defaultMemoryConfig();
 }
 
 function serializableMemoryArea(area) {

package/src/{load-snapshot → memory}/summary.mjs

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { rel } from '../common/paths.mjs';
 import { isExcludedIndexDir } from '../index/files.mjs';
-import { defaultMemoryConfig, isSecretLikePathPattern, matchPathPattern, memoryAreaForPath } from '../memory/config.mjs';
+import { defaultMemoryConfig, isSecretLikePathPattern, matchPathPattern, memoryAreaForPath } from './config.mjs';
 
 export function detectPackageManager(root) {
   const packageFile = join(root, 'package.json');
@@ -43,7 +43,7 @@ export function detectCommandGuidance(root) {
     packageManager,
     install: source === 'missing-install' ? 'npm install -D @dotdotgod/cli' : null,
     validate: source === 'local-source' ? `${prefix} validate . --include-local-memory` : `${prefix} validate .`,
-    loadSnapshot: `${prefix} load-snapshot . --json`,
+    query: `${prefix} query . \"<focus>\" --json`,
     index: `${prefix} index . --json`,
     status: `${prefix} status . --json`,
     verify: packageJson?.scripts?.verify ? `${packageManager} run verify` : null,

package/src/query/chunks.mjs

@@ -0,0 +1,92 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { createHash } from 'node:crypto';
+import { isSecretLikePathPattern, matchPathPattern } from '../memory/config.mjs';
+
+const MAX_CHUNK_CHARS = 1600;
+const SKIPPED_DIRECTORIES = new Set(['node_modules', 'dist', 'build', 'coverage', '.git', '.dotdotgod']);
+
+export function textFingerprint(text) {
+  return createHash('sha256').update(text).digest('hex');
+}
+
+export function collectDocumentationMarkdown(root, exclude = ['docs/plan', 'docs/archive']) {
+  const docsRoot = join(root, 'docs');
+  const files = [];
+  const walk = (directory) => {
+    let entries;
+    try {
+      entries = readdirSync(directory, { withFileTypes: true, encoding: 'utf8' });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const absolute = join(directory, entry.name);
+      const path = relative(root, absolute).replaceAll('\\', '/');
+      if (isSecretLikePathPattern(path) || exclude.some((pattern) => matchPathPattern(path, pattern) || path === pattern || path.startsWith(`${pattern}/`))) continue;
+      if (entry.isDirectory()) {
+        if (!SKIPPED_DIRECTORIES.has(entry.name)) walk(absolute);
+      } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) files.push(path);
+    }
+  };
+  walk(docsRoot);
+  return files.sort();
+}
+
+function splitSection(text, maxChars = MAX_CHUNK_CHARS) {
+  if (text.length <= maxChars) return [text];
+  const paragraphs = text.split(/\n\s*\n/);
+  const chunks = [];
+  let current = '';
+  for (const paragraph of paragraphs) {
+    if (current && current.length + paragraph.length + 2 > maxChars) {
+      chunks.push(current.trim());
+      current = '';
+    }
+    if (paragraph.length > maxChars) {
+      for (let offset = 0; offset < paragraph.length; offset += maxChars) chunks.push(paragraph.slice(offset, offset + maxChars).trim());
+    } else current += `${current ? '\n\n' : ''}${paragraph}`;
+  }
+  if (current.trim()) chunks.push(current.trim());
+  return chunks.filter(Boolean);
+}
+
+export function chunkMarkdown(path, content, maxChars = MAX_CHUNK_CHARS) {
+  const lines = content.split('\n');
+  const sections = [];
+  let headings = [];
+  let body = [];
+  const flush = () => {
+    const text = body.join('\n').trim();
+    if (!text && headings.length === 0) return;
+    const heading = headings.length > 0 ? headings.join(' > ') : path;
+    const pieces = splitSection(text || heading, maxChars);
+    pieces.forEach((piece, index) => {
+      const passage = `Path: ${path}\nSection: ${heading}\n\n${piece}`;
+      const fingerprint = textFingerprint(passage);
+      sections.push({ id: `${path}#${fingerprint.slice(0, 16)}`, path, heading, part: index + 1, text: piece, passage, fingerprint });
+    });
+  };
+  for (const line of lines) {
+    const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+    if (!match) {
+      body.push(line);
+      continue;
+    }
+    flush();
+    body = [];
+    const level = match[1].length;
+    headings = [...headings.slice(0, level - 1), match[2]];
+  }
+  flush();
+  return sections;
+}
+
+export function collectDocumentationChunks(root, exclude) {
+  return collectDocumentationMarkdown(root, exclude).flatMap((path) => {
+    const content = readFileSync(join(root, path), 'utf8');
+    return chunkMarkdown(path, content);
+  });
+}

package/src/query/embedder.mjs

@@ -0,0 +1,24 @@
+import { VECTOR_DIMENSIONS, VECTOR_MODEL } from './store.mjs';
+
+let extractorPromise;
+
+async function extractor() {
+  if (!extractorPromise) {
+    extractorPromise = import('@huggingface/transformers').then(async ({ env, pipeline }) => {
+      env.allowLocalModels = true;
+      return pipeline('feature-extraction', VECTOR_MODEL);
+    });
+  }
+  return extractorPromise;
+}
+
+export async function embedTexts(texts) {
+  if (texts.length === 0) return [];
+  const model = await extractor();
+  const output = await model(texts, { pooling: 'mean', normalize: true });
+  const rows = output.tolist();
+  if (!Array.isArray(rows) || rows.some((row) => !Array.isArray(row) || row.length !== VECTOR_DIMENSIONS)) {
+    throw new Error(`Unexpected ${VECTOR_MODEL} embedding shape.`);
+  }
+  return rows;
+}

package/src/query/store.mjs

@@ -0,0 +1,60 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const VECTOR_SCHEMA_VERSION = 1;
+export const VECTOR_MODEL = 'Xenova/multilingual-e5-small';
+export const VECTOR_DIMENSIONS = 384;
+
+export function vectorCachePaths(root) {
+  const directory = join(root, '.dotdotgod', 'vectors');
+  return {
+    directory,
+    manifest: join(directory, 'manifest.json'),
+    chunks: join(directory, 'chunks.jsonl'),
+    embeddings: join(directory, 'embeddings.f32'),
+  };
+}
+
+export function readVectorCache(root) {
+  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'));
+    if (manifest.schemaVersion !== VECTOR_SCHEMA_VERSION || manifest.model !== VECTOR_MODEL || manifest.dimensions !== VECTOR_DIMENSIONS) return null;
+    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 * VECTOR_DIMENSIONS * 4) return null;
+    const vectors = new Float32Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 4);
+    return { manifest, chunks, vectors: new Float32Array(vectors) };
+  } catch {
+    return null;
+  }
+}
+
+function atomicWrite(path, data) {
+  const temporary = `${path}.tmp-${process.pid}`;
+  writeFileSync(temporary, data);
+  renameSync(temporary, path);
+}
+
+export function writeVectorCache(root, chunks, vectors, metadata = {}) {
+  const paths = vectorCachePaths(root);
+  mkdirSync(paths.directory, { recursive: true });
+  if (vectors.length !== chunks.length * VECTOR_DIMENSIONS) throw new Error('Vector count does not match chunk metadata.');
+  const manifest = {
+    schemaVersion: VECTOR_SCHEMA_VERSION,
+    model: VECTOR_MODEL,
+    dimensions: VECTOR_DIMENSIONS,
+    chunks: chunks.length,
+    generatedAt: new Date().toISOString(),
+    ...metadata,
+  };
+  atomicWrite(paths.chunks, `${chunks.map((chunk) => JSON.stringify(chunk)).join('\n')}\n`);
+  atomicWrite(paths.embeddings, Buffer.from(vectors.buffer, vectors.byteOffset, vectors.byteLength));
+  atomicWrite(paths.manifest, `${JSON.stringify(manifest, null, 2)}\n`);
+  return manifest;
+}
+
+export function removeVectorCache(root) {
+  rmSync(vectorCachePaths(root).directory, { recursive: true, force: true });
+}

package/src/validate/run.mjs

@@ -169,7 +169,7 @@ export function runValidate(argv) {
   }
   if (options.checkIndex) {
     const index = readIndex(root);
-    if (!index) addError(cacheFile(root), 'INDEX_MISSING', 'Expected .dotdotgod index cache.', null, 'run `dotdotgod index <root>` or a lazy-refreshing command such as `dotdotgod load-snapshot <root> --json`.');
+    if (!index) addError(cacheFile(root), 'INDEX_MISSING', 'Expected .dotdotgod index cache.', null, 'run `dotdotgod index <root>` to build the graph index.');
     else {
       const schemaVersion = index.schemaVersion ?? index.version ?? null;
       if (schemaVersion !== CACHE_VERSION) addError(cacheFile(root), 'INDEX_SCHEMA_MISMATCH', `Index schema is ${String(schemaVersion)}; expected ${CACHE_VERSION}.`, null, 'run `dotdotgod index <root>` to rebuild the cache with the current schema.');
@@ -181,7 +181,7 @@ export function runValidate(argv) {
         const indexedHash = indexed.get(path);
         const currentHash = fingerprint(file);
         if (!indexedHash) addError(file, 'INDEX_MISSING_FILE', 'Markdown file is not present in the current graph index.', null, 'run `dotdotgod index <root>` to refresh the graph index.');
-        else if (indexedHash !== currentHash) addError(file, 'INDEX_STALE', 'Markdown fingerprint differs from the current graph index.', null, 'run `dotdotgod index <root>` or a lazy-refreshing command such as `dotdotgod load-snapshot <root> --json`.');
+        else if (indexedHash !== currentHash) addError(file, 'INDEX_STALE', 'Markdown fingerprint differs from the current graph index.', null, 'run `dotdotgod index <root>` to refresh the graph index.');
       }
     }
   }

package/src/commands/load-snapshot.mjs

@@ -1,46 +0,0 @@
-import { parseCommon } from '../cli/usage.mjs';
-import { buildCommunities } from '../graph/communities.mjs';
-import { memoryConfigSummary, readMemoryConfig } from '../memory/config.mjs';
-import { buildMemoryAreas, buildPinnedFiles, detectCommandGuidance } from '../load-snapshot/summary.mjs';
-import { graphSummary, readFreshIndex } from '../index/cache.mjs';
-
-export function runLoadSnapshot(argv) {
-  const options = parseCommon(argv);
-  const { status, index, metadata } = readFreshIndex(options.root);
-  const summary = graphSummary(index);
-  const communities = buildCommunities(index, { communities: 5, items: 5 });
-  const memoryAreas = buildMemoryAreas(index, { items: 4 });
-  const resolvedConfig = readMemoryConfig(options.root);
-  const memoryConfig = index.memoryConfig ?? memoryConfigSummary(resolvedConfig);
-  const pinnedFiles = buildPinnedFiles(options.root, resolvedConfig);
-  const memoryPolicy = {
-    source: memoryConfig.source ?? 'default',
-    sharedAreas: (memoryConfig.areas ?? []).filter((area) => area.scope === 'shared').map((area) => area.id),
-    localAreas: (memoryConfig.areas ?? []).filter((area) => area.scope === 'local').map((area) => area.id),
-    freshAreas: (memoryConfig.areas ?? []).filter((area) => area.freshness === 'fresh').map((area) => area.id),
-    staleAreas: (memoryConfig.areas ?? []).filter((area) => area.freshness === 'stale').map((area) => area.id),
-  };
-  const bounds = { communities: 5, communityItems: 5, memoryAreaItems: 4, pinnedPathItems: pinnedFiles.bounds.maxPaths, pinnedBodyItems: pinnedFiles.bounds.maxBodies, pinnedBodyChars: pinnedFiles.bounds.maxBodyChars, fullGraphIncluded: false, archiveBodiesIncluded: status.archiveBodiesIncluded, archiveMapIncluded: true };
-  const quality = {
-    indexedFiles: status.indexedFiles,
-    currentFiles: status.currentFiles,
-    shownCommunities: communities.communities.length,
-    totalCommunities: communities.total,
-    omittedCommunities: communities.omitted,
-    omittedCommunityItems: communities.communities.reduce((sum, community) => sum + (community.omitted ?? 0), 0),
-    memoryAreas: memoryAreas.total,
-    omittedMemoryAreaItems: memoryAreas.areas.reduce((sum, area) => sum + (area.omitted ?? 0), 0),
-    pinnedPaths: pinnedFiles.paths.length,
-    omittedPinnedPaths: pinnedFiles.omittedPaths,
-    pinnedBodies: pinnedFiles.bodies.length,
-    omittedPinnedBodies: pinnedFiles.omittedBodies,
-    graphNodes: summary.nodes,
-    graphEdges: summary.edges,
-  };
-  const commandGuidance = detectCommandGuidance(options.root);
-  let payload = { root: options.root, cache: status, metadata, graph: summary, memoryConfig, memoryPolicy, memoryAreas, pinnedFiles, communities, bounds, quality, commandGuidance };
-  const serialized = JSON.stringify(payload);
-  payload = { ...payload, quality: { ...quality, snapshotBytes: Buffer.byteLength(serialized), approxSnapshotTokens: Math.ceil(serialized.length / 4) } };
-  if (options.json) console.log(JSON.stringify(payload, null, 2));
-  else console.log(`dotdotgod load snapshot\n- cache: ${status.status}${metadata.cacheRefreshed ? ' (refreshed)' : ''}\n- indexed files: ${status.indexedFiles}\n- current files: ${status.currentFiles}\n- archive bodies included: ${status.archiveBodiesIncluded ? 'yes' : 'no'}\n- graph: ${summary.nodes} nodes, ${summary.edges} edges\n- memory areas: ${memoryAreas.areas.length}/${memoryAreas.total} shown\n- pinned files: ${pinnedFiles.paths.length} paths (${pinnedFiles.omittedPaths} omitted), ${pinnedFiles.bodies.length} bodies (${pinnedFiles.omittedBodies} omitted)\n- communities: ${communities.communities.length}/${communities.total} shown, ${communities.omitted} omitted`);
-}