@dotdotgod/cli 0.2.19 → 0.2.21

package/README.md

@@ -51,6 +51,7 @@ dotdotgod validate .
 dotdotgod validate . --check-index
 dotdotgod config .
 dotdotgod config init .
+dotdotgod config init . --template research
 dotdotgod status .
 dotdotgod index .
 dotdotgod query . "plan mode tools"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdotgod/cli",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "description": "CLI for dotdotgod validation, local documentation search, and graph indexing.",
   "type": "module",
   "license": "Elastic-2.0",

package/src/cli/usage.mjs

@@ -11,23 +11,23 @@ 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] [--dry-run] [--json]
+  dotdotgod init <root> [--project-name NAME] [--template NAME] [--dotdot-setting] [--dry-run] [--json]
 
-Create AGENTS.md, agent entrypoints, docs indexes, and local memory gitignore entries.`;
+Create AGENTS.md, agent entrypoints, docs indexes, a project config from an initialization template, and local memory gitignore entries.`;
     case 'index':
       return `Usage:
   dotdotgod index <root> [--json]`;
     case 'config':
       return `Usage:
   dotdotgod config <root> [--json]
-  dotdotgod config init <root> [--json]
+  dotdotgod config init <root> [--template NAME] [--json]
 
 Inspect or initialize the project-level dotdotgod config file.`;
     case 'config init':
       return `Usage:
-  dotdotgod config init <root> [--json]
+  dotdotgod config init <root> [--template NAME] [--json]
 
-Create dotdotgod.config.json with the built-in default memory, traceability, validation, and impact ranking policy.`;
+Create dotdotgod.config.json from a bundled or user template. Without --template, use the global defaultTemplate and then software.`;
     case 'status':
       return `Usage:
   dotdotgod status <root> [--json]`;
@@ -35,7 +35,7 @@ Create dotdotgod.config.json with the built-in default memory, traceability, val
       return `Usage:
   dotdotgod query <root> <query> [--limit n] [--json]
 
-Search shared project documentation with the local multilingual E5 vector index.`;
+Search shared project documentation with the resolved local or remote embedding provider.`;
     case 'resolve':
       return `Usage:
   dotdotgod resolve <root> <ref> [--max-results n] [--include-archive] [--json]`;

package/src/commands/config.mjs

@@ -1,15 +1,22 @@
 import { existsSync, statSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { usage } from '../cli/usage.mjs';
-import { defaultDotdotgodConfigText, memoryConfigSummary, readMemoryConfig } from '../memory/config.mjs';
+import { memoryConfigSummary, readMemoryConfig } from '../memory/config.mjs';
+import { resolveInitializationTemplate } from '../config/templates.mjs';
+import { resolveEmbeddingProfile, sanitizeEmbeddingProfile } from '../query/embedding-config.mjs';
 
 function parseConfigOptions(argv, usageKey = 'config') {
-  const options = { root: '.', json: false };
+  const options = { root: '.', json: false, template: null };
   let rootSet = false;
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--json') options.json = true;
-    else if (!arg.startsWith('-') && !rootSet) {
+    else if (arg === '--template') {
+      const value = argv[i + 1];
+      if (!value || value.startsWith('-')) usage('--template requires a value', usageKey);
+      options.template = value;
+      i += 1;
+    } else if (!arg.startsWith('-') && !rootSet) {
       options.root = arg;
       rootSet = true;
     } else if (!arg.startsWith('-')) usage(`Unexpected argument: ${arg}`, usageKey);
@@ -34,6 +41,7 @@ function formatConfigOutput(payload) {
   const lines = [`dotdotgod config: ${payload.source}${errors.length > 0 ? ' (invalid; using defaults)' : ''}`];
   lines.push(`- path: ${payload.path ?? 'none'}`);
   lines.push(`- memory areas: ${payload.config.areas.length}`);
+  lines.push(`- embedding: ${payload.embedding.profile.provider}/${payload.embedding.profile.model} (${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:');
@@ -67,16 +75,26 @@ export function runConfig(argv) {
     }
     const target = join(options.root, 'dotdotgod.config.json');
     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: true };
+    const template = resolveInitializationTemplate(options.template);
+    if (!template.ok) configInitError(options, template.error.code, template.error.message, template.error.path ?? target);
+    writeFileSync(target, template.text);
+    const payload = { ok: true, command: 'config init', root: options.root, path: target, created: true, template: { name: template.name, source: template.source, selectedBy: template.selectedBy } };
     if (options.json) console.log(JSON.stringify(payload, null, 2));
-    else console.log(`dotdotgod config init: created ${target}`);
+    else console.log(`dotdotgod config init: created ${target} from ${template.source}:${template.name} (${template.selectedBy})`);
     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: config.source && config.source !== 'default' ? join(options.root, config.source) : null, config: memoryConfigSummary(config), errors };
+  let embedding;
+  try {
+    const resolved = resolveEmbeddingProfile(options.root);
+    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' }) };
+  }
+  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));
   else console.log(formatConfigOutput(payload));
   if (errors.length > 0) process.exit(1);

package/src/commands/query.mjs

@@ -2,8 +2,8 @@ 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 { isValidNormalizedVectorValues, readVectorCache, VECTOR_DIMENSIONS, VECTOR_MODEL, writeVectorCache } from '../query/store.mjs';
+import { resolveEmbedder } from '../query/embedder.mjs';
+import { isValidNormalizedVectorValues, profileFingerprint, readVectorCache, writeVectorCache } from '../query/store.mjs';
 
 const DEFAULT_LIMIT = 30;
 const MAX_LIMIT = 100;
@@ -16,137 +16,93 @@ export function parseQueryOptions(argv) {
   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);
+    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 assertNormalizedVector(vector, label) {
-  if (!vector || vector.length !== VECTOR_DIMENSIONS || !isValidNormalizedVectorValues(vector)) throw new Error(`${label} must be a finite normalized ${VECTOR_DIMENSIONS}-dimensional vector.`);
+function assertVector(vector, dimensions, label) {
+  if (!vector || vector.length !== dimensions || !isValidNormalizedVectorValues(vector, dimensions)) throw new Error(`${label} must be a finite normalized ${dimensions}-dimensional vector.`);
 }
 
-export function cosineScore(left, vectors, offset = 0) {
-  assertNormalizedVector(left, 'Query vector');
-  const right = vectors?.subarray ? vectors.subarray(offset, offset + VECTOR_DIMENSIONS) : vectors?.slice(offset, offset + VECTOR_DIMENSIONS);
-  assertNormalizedVector(right, 'Passage vector');
+export function cosineScore(left, vectors, offset = 0, dimensions = left?.length) {
+  assertVector(left, dimensions, 'Query vector');
+  const right = vectors?.subarray ? vectors.subarray(offset, offset + dimensions) : vectors?.slice(offset, offset + dimensions);
+  assertVector(right, dimensions, 'Passage vector');
   let score = 0;
-  for (let index = 0; index < VECTOR_DIMENSIONS; index += 1) score += left[index] * right[index];
-  if (!Number.isFinite(score) || score < -1.000001 || score > 1.000001) throw new Error('Cosine similarity was outside the finite normalized range.');
+  for (let index = 0; index < dimensions; index += 1) score += left[index] * right[index];
   return Math.max(-1, Math.min(1, score));
 }
 
 export function rankVectorFiles(queryVector, index) {
-  assertNormalizedVector(queryVector, 'Query vector');
-  if (!index || !Array.isArray(index.chunks) || index.vectors?.length !== index.chunks.length * VECTOR_DIMENSIONS || !isValidNormalizedVectorValues(index.vectors)) throw new Error('Vector index contains invalid passage vectors.');
-  const ranked = index.chunks.map((chunk, position) => ({ ...chunk, vectorScore: cosineScore(queryVector, index.vectors, position * VECTOR_DIMENSIONS) }))
+  const dimensions = index?.manifest?.dimensions ?? queryVector?.length;
+  assertVector(queryVector, dimensions, 'Query vector');
+  if (!index || !Array.isArray(index.chunks) || index.vectors?.length !== index.chunks.length * dimensions || !isValidNormalizedVectorValues(index.vectors, dimensions)) throw new Error('Vector index contains invalid passage vectors.');
+  const ranked = index.chunks.map((chunk, position) => ({ ...chunk, vectorScore: cosineScore(queryVector, index.vectors, position * dimensions, dimensions) }))
     .sort((left, right) => right.vectorScore - left.vectorScore || left.path.localeCompare(right.path) || left.id.localeCompare(right.id));
-  const results = [];
-  const seen = new Set();
-  for (const chunk of ranked) {
-    if (seen.has(chunk.path)) continue;
-    seen.add(chunk.path);
-    results.push(chunk);
-  }
+  const results = []; const seen = new Set();
+  for (const chunk of ranked) if (!seen.has(chunk.path)) { seen.add(chunk.path); results.push(chunk); }
   return results;
 }
 
 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 terms = new Set(query.toLowerCase().split(/[^\p{L}\p{N}_.:/-]+/u).filter((term) => term.length > 1));
+  if (!terms.size) 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);
+  let matches = 0; for (const term of terms) if (haystack.includes(term)) matches += 1;
+  return Math.min(0.08, (matches / terms.size) * 0.08);
 }
 
-export async function buildVectorIndex(root, embed = embedTexts) {
+export async function buildVectorIndex(root, embedOrOptions = {}) {
+  const options = typeof embedOrOptions === 'function' ? { embed: embedOrOptions } : embedOrOptions;
+  const resolved = await resolveEmbedder(root, options);
   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;
-    }
-  });
+  const cached = readVectorCache(root, resolved.identity);
+  const cachedOffsets = new Map((cached?.chunks ?? []).map((chunk, index) => [chunk.fingerprint, index]));
+  const rows = new Array(chunks.length);
+  const missing = []; let reused = 0;
+  chunks.forEach((chunk, index) => { const oldIndex = cachedOffsets.get(chunk.fingerprint); if (oldIndex === undefined || !cached) missing.push({ chunk, index }); else { const d = cached.manifest.dimensions; rows[index] = Array.from(cached.vectors.subarray(oldIndex * d, (oldIndex + 1) * d)); 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}`));
-    if (!Array.isArray(embedded) || embedded.length !== batch.length) throw new Error('Embedder returned an unexpected passage-vector count.');
-    embedded.forEach((vector, index) => {
-      assertNormalizedVector(vector, 'Passage vector');
-      vectors.set(vector, batch[index].index * VECTOR_DIMENSIONS);
-    });
+    const embedded = await resolved.embed(batch.map(({ chunk }) => `passage: ${chunk.passage}`));
+    embedded.forEach((vector, index) => { rows[batch[index].index] = vector; });
   }
+  const dimensions = rows[0]?.length ?? cached?.manifest?.dimensions;
+  if (!dimensions) 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, {
-    excluded: exclude,
-    embedded: missing.length,
-    reused,
-  });
-  return { chunks: storedChunks, vectors, manifest };
+  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 });
+  return { chunks: storedChunks, vectors, manifest, embedding: resolved };
 }
 
 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 embeddedQuery = await embed([`query: ${query}`]);
-  if (!Array.isArray(embeddedQuery) || embeddedQuery.length !== 1) throw new Error('Embedder returned an unexpected query-vector count.');
-  const [queryVector] = embeddedQuery;
-  assertNormalizedVector(queryVector, 'Query vector');
-  const rankedChunks = index.chunks.map((chunk, position) => {
-    const vectorScore = cosineScore(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 };
+  const index = await buildVectorIndex(root, options);
+  const [queryVector] = await index.embedding.embed([`query: ${query}`]);
+  const dimensions = index.manifest.dimensions;
+  assertVector(queryVector, dimensions, 'Query vector');
+  const results = rankVectorFiles(queryVector, index).map((chunk) => ({ ...chunk, score: Number((chunk.vectorScore + lexicalBoost(query, chunk)).toFixed(6)), vectorScore: Number(chunk.vectorScore.toFixed(6)) }))
+    .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path)).slice(0, limit);
+  return { ok: true, command: 'query', root, query, provider: index.embedding.profile.provider, model: index.embedding.profile.model, embeddingSource: index.embedding.source, 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 ? '…' : ''}`);
-  });
+  const lines = [`dotdotgod query: ${payload.query}`, `- embedding: ${payload.provider}/${payload.model} (${payload.embeddingSource})`, `- 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;
-  }
+  try { const payload = await queryDocumentation(options.root, options.query, options); console.log(options.json ? JSON.stringify(payload, null, 2) : 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/config/templates.mjs

@@ -0,0 +1,219 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { defaultDotdotgodConfigData, validateMemoryConfigData } from '../memory/config.mjs';
+import { isKebabCase } from '../docs/markdown.mjs';
+
+export const DEFAULT_TEMPLATE_NAME = 'software';
+export const BUILT_IN_TEMPLATE_NAMES = ['software', 'research', 'case-and-evidence', 'publication', 'portfolio', 'policy'];
+
+const BUILT_IN_TEMPLATE_SCAFFOLDS = {
+  software: [],
+  research: [
+    ['docs/research/README.md', 'Research', 'Use this area for research notes, sources, and findings.'],
+    ['docs/record/README.md', 'Research Records', 'Use this area for dated measurements, experiments, and execution records.'],
+    ['docs/report/README.md', 'Reports', 'Use this area for research diagnoses, analyses, results, and performance reports.'],
+    ['outputs', null, null],
+  ],
+  'case-and-evidence': [
+    ['docs/case/README.md', 'Case Records', 'Use this area for canonical case facts, questions, and decisions.'],
+    ['docs/evidence/README.md', 'Evidence', 'Use this area for factual, legal, and other supporting evidence.'],
+    ['docs/outputs/README.md', 'Case Outputs', 'Use this area for maintained case outputs.'],
+  ],
+  publication: [
+    ['docs/outline/README.md', 'Publication Outline', 'Use this area for publication structure and outlines.'],
+    ['docs/chapters/README.md', 'Chapter Plans', 'Use this area for chapter plans and direction.'],
+    ['docs/claims/README.md', 'Claims', 'Use this area for maintained claims and their support.'],
+    ['docs/research/README.md', 'Research Sources', 'Use this area for research sources and supporting notes.'],
+    ['book', null, null],
+  ],
+  portfolio: [
+    ['docs/strategy/README.md', 'Portfolio Strategy', 'Use this area for portfolio strategy and risk rules.'],
+    ['docs/positions/README.md', 'Position Theses', 'Use this area for position theses and investment conclusions.'],
+    ['docs/journal/README.md', 'Decision Journal', 'Use this area for dated investment decisions and reviews.'],
+    ['docs/report/README.md', 'Market Research', 'Use this area for maintained market research and analysis.'],
+    ['data', null, null],
+  ],
+  policy: [
+    ['docs/policy/README.md', 'Policy Documents', 'Use this area for integrated policy proposals and outputs.'],
+    ['docs/sections/README.md', 'Policy Sections', 'Use this area for source policy sections.'],
+    ['docs/evidence/README.md', 'Policy Evidence', 'Use this area for evidence supporting policy proposals.'],
+    ['docs/outputs/README.md', 'Submission Outputs', 'Use this area for maintained policy submission outputs.'],
+  ],
+};
+
+export function builtInTemplateScaffold(name) {
+  const entries = BUILT_IN_TEMPLATE_SCAFFOLDS[name];
+  if (!entries) return null;
+  return entries.map(([path, heading, description]) => ({
+    path,
+    type: heading ? 'file' : 'directory',
+    ...(heading ? { content: `# ${heading}\n\n${description}` } : {}),
+  }));
+}
+
+function area(id, label, paths, role, priority, includeBodiesByDefault = true, extra = {}) {
+  return { id, label, paths, excludePaths: [], scope: 'shared', freshness: 'fresh', role, priority, includeBodiesByDefault, ...extra };
+}
+
+function localAreas() {
+  return [
+    { ...area('active-plan', 'Active Plans', ['docs/plan/**'], 'active-task-intent', 95), scope: 'local' },
+    { ...area('archive-map', 'Archive Map', ['docs/archive/README.md'], 'historical-memory-map', 65), scope: 'local', freshness: 'stale' },
+    { ...area('archive-body', 'Archive Body', ['docs/archive/**'], 'historical-memory-body', 20, false), excludePaths: ['docs/archive/README.md'], scope: 'local', freshness: 'stale' },
+  ];
+}
+
+function baseAreas() {
+  return [
+    area('rules', 'Agent Rules', ['AGENTS.md'], 'agent-working-rules', 100),
+    area('agent-entrypoint', 'Agent Entrypoints', ['CLAUDE.md', 'CODEX.md'], 'agent-specific-entrypoint', 85),
+    area('project-overview', 'Project Overview', ['README.md'], 'project-map', 85),
+    area('docs-index', 'Docs Index', ['docs/README.md'], 'documentation-routing-map', 90),
+  ];
+}
+
+function traceability(required, keys) {
+  return { required, exclude: ['**/README.md'], keys };
+}
+
+const keys = {
+  software: [
+    ['implementedBy', 'Implemented by', 'Files that implement the behavior.', 'path', 'implemented_by', 4],
+    ['verifiedBy', 'Verified by', 'Tests or maintained verification documents.', 'path', 'verified_by', 4],
+    ['relatedDocs', 'Related docs', 'Documents needed to interpret the behavior.', 'path', 'related_doc', 3],
+    ['verificationCommands', 'Verification commands', 'Project-local verification commands.', 'command', 'verification_command', 3],
+  ],
+  research: [
+    ['informedBy', 'Informed by', 'Research sources or prior findings that justify the direction.', 'path', 'informed_by', 4],
+    ['assumptionsDefinedIn', 'Assumptions defined in', 'Documents defining assumptions that bound the claim.', 'path', 'assumptions_defined_in', 4],
+    ['evaluatedBy', 'Evaluated by', 'Evaluation protocols or measurement methods.', 'path', 'evaluated_by', 4],
+    ['evidenceRecordedIn', 'Evidence recorded in', 'Dated experiment, dataset, or validation records.', 'path', 'evidence_recorded_in', 4],
+  ],
+  case: [
+    ['basedOn', 'Based on', 'Canonical case records, evidence, or grounds supporting the document.', 'path', 'based_on', 4],
+    ['relatedDocs', 'Related docs', 'Documents needed to interpret the record.', 'path', 'related_doc', 2],
+  ],
+  publication: [
+    ['developedIn', 'Developed in', 'Outlines or manuscript drafts that develop this design.', 'path', 'developed_in', 4],
+    ['supportedBy', 'Supported by', 'Research notes and sources supporting the claims.', 'path', 'supported_by', 4],
+    ['framedBy', 'Framed by', 'Documents defining purpose, scope, or conceptual boundaries.', 'path', 'framed_by', 3],
+  ],
+  portfolio: [
+    ['supportedBy', 'Supported by', 'Data or research supporting the investment conclusion.', 'path', 'supported_by', 4],
+    ['recordedIn', 'Recorded in', 'Ledgers, snapshots, or journals recording the decision.', 'path', 'recorded_in', 4],
+    ['informs', 'Informs', 'Strategies, theses, or risk rules using this conclusion.', 'path', 'informs_decision', 3],
+  ],
+  policy: [
+    ['supportedBy', 'Supported by', 'Evidence, source sections, or research supporting the proposal.', 'path', 'supported_by', 4],
+    ['integratedInto', 'Integrated into', 'Integrated proposals or briefs that use this policy section.', 'path', 'integrated_into', 4],
+    ['relatedDocs', 'Related docs', 'Documents needed to interpret the policy.', 'path', 'related_doc', 2],
+  ],
+};
+
+function definitions(values) {
+  return values.map(([key, label, description, target, relation, weight]) => ({ key, label, description, target, relation, weight }));
+}
+
+function withPolicy(areas, required, definitionsList) {
+  const config = defaultDotdotgodConfigData();
+  config.memory.areas = [...baseAreas(), ...areas, ...localAreas(), area('docs', 'Project Documentation', ['docs/**'], 'project-documentation', 60)];
+  config.traceability = traceability(required, definitions(definitionsList));
+  return config;
+}
+
+export function builtInTemplateData(name) {
+  if (name === 'software') return defaultDotdotgodConfigData();
+  if (name === 'research') return withPolicy([
+    area('spec', 'Research Specifications', ['docs/spec/**'], 'research-contract', 85),
+    area('architecture', 'Architecture', ['docs/arch/**'], 'architecture-rationale', 82),
+    area('test', 'Verification', ['docs/test/**'], 'test-strategy', 78),
+    area('research', 'Research Notes', ['docs/research/**'], 'research-diary', 70),
+    area('record', 'Research Records', ['docs/record/**'], 'research-record', 68),
+    { ...area('report', 'Reports', ['docs/report/**'], 'report-background', 60), freshness: 'stale' },
+    { ...area('artifacts', 'Generated Artifacts', ['outputs/**'], 'artifact-body', 10, false), scope: 'local', freshness: 'stale' },
+  ], ['docs/spec/**', 'docs/report/**'], keys.research);
+  if (name === 'case-and-evidence') return withPolicy([
+    area('case', 'Case Record', ['docs/case/**'], 'case-truth-and-open-questions', 85),
+    area('evidence', 'Evidence and Grounds', ['docs/evidence/**'], 'factual-and-legal-support', 80),
+    area('outputs', 'Case Outputs', ['docs/outputs/**'], 'case-outputs', 75),
+  ], ['docs/case/**', 'docs/outputs/**'], keys.case);
+  if (name === 'publication') return withPolicy([
+    area('brief', 'Publication Brief', ['docs/BOOK_BRIEF.md'], 'publication-direction', 100),
+    area('outline', 'Publication Outline', ['docs/outline/**'], 'narrative-structure', 95),
+    area('chapters', 'Chapter Plans', ['docs/chapters/**'], 'chapter-direction', 90),
+    area('claims', 'Claims', ['docs/claims/**'], 'claim-registry', 90),
+    area('manuscript', 'Manuscript', ['book/**'], 'manuscript', 95),
+    area('research', 'Research Sources', ['docs/research/**'], 'evidence-library', 80),
+  ], ['docs/chapters/**'], keys.publication);
+  if (name === 'portfolio') return withPolicy([
+    area('strategy', 'Portfolio Strategy', ['docs/strategy/**'], 'portfolio-strategy', 95),
+    area('positions', 'Position Theses', ['docs/positions/**'], 'position-thesis', 95),
+    area('ledger', 'Trading Ledger', ['data/**'], 'trading-facts', 90, false, { excludePaths: ['data/raw/**'] }),
+    area('journal', 'Decision Journal', ['docs/journal/**'], 'decision-journal', 80),
+    { ...area('research', 'Research', ['docs/report/**'], 'market-research', 50), freshness: 'stale' },
+  ], ['docs/strategy/**', 'docs/positions/**'], keys.portfolio);
+  if (name === 'policy') return withPolicy([
+    area('policy', 'Policy Documents', ['docs/policy/**'], 'policy-output', 95),
+    area('sections', 'Policy Sections', ['docs/sections/**'], 'policy-source-sections', 90),
+    area('evidence', 'Policy Evidence', ['docs/evidence/**', 'docs/report/**'], 'policy-evidence', 80),
+    area('outputs', 'Submission Outputs', ['docs/outputs/**'], 'policy-submission-output', 75),
+  ], ['docs/sections/**', 'docs/outputs/**'], keys.policy);
+  return null;
+}
+
+export function builtInTemplateText(name) {
+  const data = builtInTemplateData(name);
+  return data ? `${JSON.stringify(data, null, 2)}\n` : null;
+}
+
+export function dotdotgodHome() {
+  return join(homedir(), '.dotdotgod');
+}
+
+function templateError(code, message, path = null) {
+  return { ok: false, error: { code, message, ...(path ? { path } : {}) } };
+}
+
+export function resolveInitializationTemplate(explicitName = null, home = dotdotgodHome()) {
+  let name = explicitName;
+  let selectedBy = explicitName ? 'explicit' : 'default';
+  const globalPath = join(home, 'config.json');
+  if (!name && existsSync(globalPath)) {
+    let globalConfig;
+    try {
+      globalConfig = JSON.parse(readFileSync(globalPath, 'utf8'));
+    } catch (error) {
+      return templateError('GLOBAL_CONFIG_INVALID_JSON', `Invalid global config JSON: ${error instanceof Error ? error.message : String(error)}`, globalPath);
+    }
+    if (!globalConfig || typeof globalConfig !== 'object' || Array.isArray(globalConfig)) {
+      return templateError('GLOBAL_CONFIG_INVALID', 'Global config must be a JSON object.', globalPath);
+    }
+    if (globalConfig.defaultTemplate !== undefined && !isKebabCase(globalConfig.defaultTemplate)) {
+      return templateError('GLOBAL_CONFIG_INVALID_DEFAULT_TEMPLATE', 'Global config defaultTemplate must be a kebab-case string.', globalPath);
+    }
+    if (globalConfig.defaultTemplate) {
+      name = globalConfig.defaultTemplate;
+      selectedBy = 'global';
+    }
+  }
+  name ??= DEFAULT_TEMPLATE_NAME;
+  if (!isKebabCase(name)) return templateError('TEMPLATE_INVALID_NAME', `Template name must be kebab-case: ${name}`);
+
+  const customPath = join(home, 'templates', `${name}.json`);
+  if (existsSync(customPath)) {
+    let data;
+    try {
+      data = JSON.parse(readFileSync(customPath, 'utf8'));
+    } catch (error) {
+      return templateError('TEMPLATE_INVALID_JSON', `Invalid template JSON: ${error instanceof Error ? error.message : String(error)}`, customPath);
+    }
+    const errors = validateMemoryConfigData(data, '.', customPath);
+    if (errors.length > 0) return { ok: false, error: { code: 'TEMPLATE_INVALID', message: `Custom template is invalid: ${name}`, path: customPath, errors } };
+    return { ok: true, name, source: 'custom', selectedBy, path: customPath, data, text: `${JSON.stringify(data, null, 2)}\n` };
+  }
+
+  const data = builtInTemplateData(name);
+  if (!data) return templateError('TEMPLATE_NOT_FOUND', `Template not found: ${name}`);
+  return { ok: true, name, source: 'bundled', selectedBy, path: null, data, text: `${JSON.stringify(data, null, 2)}\n` };
+}

package/src/core.mjs

@@ -14,6 +14,7 @@ export { rel } from './common/paths.mjs';
 export { extractAnchors, extractFirstHeading, extractLinks, headingToAnchor, isKebabCase, isNumberedSeriesFilename, isUpperSnakeMarkdown, removeCodeBlocks, suggestFilenameFromHeading } from './docs/markdown.mjs';
 export { extractDotdotgodTraceabilityBlocks, findTraceabilityLinksRegion, isLocalRelativeTraceabilityPath, renderCompactTraceabilityBlock, stripTraceabilityLinksRegion, syncTraceabilityLinksInContent, traceabilityExample, validateTraceabilityBlock, validateTraceabilityLinksRegion, validateTraceabilityPlacement } from './docs/traceability.mjs';
 export { DEFAULT_IMPACT_RANKING_POLICY, DEFAULT_LOAD_POLICY, DEFAULT_VALIDATION_POLICY, SEMANTIC_RELATIONS, cloneImpactRankingPolicy, cloneLoadPolicy, cloneReferenceExpansionPolicy, cloneValidationPolicy, defaultDotdotgodConfigData, defaultDotdotgodConfigText, defaultMemoryConfig, isMarkdownSizeExcluded, isSecretLikePathPattern, isValidPathPattern, matchPathPattern, memoryAreaForPath, memoryConfigSummary, normalizeLowSignalTerm, readMemoryConfig, requiresTraceability, resolveMemoryArea, validateMemoryConfigData } from './memory/config.mjs';
+export { BUILT_IN_TEMPLATE_NAMES, DEFAULT_TEMPLATE_NAME, builtInTemplateData, builtInTemplateScaffold, builtInTemplateText, dotdotgodHome, resolveInitializationTemplate } from './config/templates.mjs';
 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';
@@ -30,7 +31,9 @@ export { formatCompactImpactOutput, formatYmlGraphImpactError, formatYmlImpactOu
 export { runConfig } from './commands/config.mjs';
 export { buildVectorIndex, cosineScore, parseQueryOptions, queryDocumentation, rankVectorFiles, 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 { readVectorCache, VECTOR_DIMENSIONS, VECTOR_MODEL, VECTOR_SCHEMA_VERSION, profileFingerprint, vectorCachePaths, writeVectorCache } from './query/store.mjs';
+export { DEFAULT_EMBEDDING_PROFILE, EMBEDDING_PROVIDERS, embeddingProfileIdentity, resolveEmbeddingProfile, sanitizeEmbeddingProfile, validateEmbeddingProfile } from './query/embedding-config.mjs';
+export { createEmbedder, resolveEmbedder } from './query/embedder.mjs';
 export { extractBracketReferences, extractFuzzyReferences, normalizeReferenceAlias } from './reference/extract.mjs';
 export { resolveReferenceCandidates, runResolve, runExpand } from './reference/resolve.mjs';
 export { parseTraceabilityOptions, runTraceability } from './commands/traceability.mjs';

package/src/impact/vector-overlay.mjs

@@ -1,6 +1,5 @@
 import { buildVectorIndex, rankVectorFiles } from '../commands/query.mjs';
-import { embedTexts } from '../query/embedder.mjs';
-import { VECTOR_MODEL } from '../query/store.mjs';
+
 import { buildChangedFileProfile, canonicalizeChangedPath } from './vector-profile.mjs';
 
 export const VECTOR_RELATION_WEIGHT = 2;
@@ -14,16 +13,17 @@ function boundedEvidence(value, limit) {
 export async function buildVectorImpactOverlay(root, index, changedPaths, options = {}) {
   const semantic = index?.memoryConfig?.impactRanking?.semantic ?? {};
   if (semantic.enabled === false || semantic.topKPerFile === 0) return { status: 'disabled', edges: [], diagnostics: { enabled: false } };
-  const embed = options.embed ?? embedTexts;
   const threshold = semantic.threshold ?? 0.5;
   const topK = semantic.topKPerFile ?? 5;
   try {
-    const vectorIndex = await (options.buildIndex ?? buildVectorIndex)(root, embed);
+    const vectorIndex = await (options.buildIndex ?? buildVectorIndex)(root, options);
     const edges = [];
     const normalizedChangedPaths = [...new Set(changedPaths.map((path) => canonicalizeChangedPath(root, path)).filter(Boolean))];
     for (const changed of normalizedChangedPaths) {
       const profile = buildChangedFileProfile(root, changed, index?.graph);
       if (!profile) continue;
+      const embed = vectorIndex.embedding?.embed ?? options.embed;
+      if (!embed) throw new Error('Vector index did not provide an embedder.');
       const [queryVector] = await embed([`query: ${profile.text}`]);
       if (!queryVector) throw new Error('Changed-file embedding was empty.');
       const matches = rankVectorFiles(queryVector, vectorIndex)
@@ -42,7 +42,7 @@ export async function buildVectorImpactOverlay(root, index, changedPaths, option
         });
       }
     }
-    return { status: 'available', edges, diagnostics: { enabled: true, model: VECTOR_MODEL, corpusChunks: vectorIndex.chunks.length, threshold, topK, embedded: vectorIndex.manifest?.embedded, reused: vectorIndex.manifest?.reused } };
+    return { status: 'available', edges, diagnostics: { enabled: true, provider: vectorIndex.embedding?.profile?.provider ?? 'injected', model: vectorIndex.embedding?.profile?.model ?? 'injected', source: vectorIndex.embedding?.source ?? 'injected', corpusChunks: vectorIndex.chunks.length, threshold, topK, embedded: vectorIndex.manifest?.embedded, reused: vectorIndex.manifest?.reused } };
   } catch (error) {
     return { status: 'unavailable', edges: [], diagnostics: { enabled: true, reason: error instanceof Error ? error.message : String(error) } };
   }

package/src/init.mjs

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
-import { defaultDotdotgodConfigText } from './memory/config.mjs';
+import { builtInTemplateScaffold, resolveInitializationTemplate } from './config/templates.mjs';
 
 function action(status, path, extra = {}) {
   return { status, path, ...extra };
@@ -12,16 +12,17 @@ function formatAction(item) {
 }
 
 function parseInitOptions(argv) {
-  const options = { root: null, projectName: '', dotdotSetting: false, dryRun: false, json: false };
+  const options = { root: null, projectName: '', dotdotSetting: false, dryRun: false, json: false, template: null };
   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 === '--dry-run') options.dryRun = true;
-    else if (arg === '--project-name') {
+    else if (arg === '--project-name' || arg === '--template') {
       const value = argv[i + 1];
-      if (!value || value.startsWith('-')) throw new Error('--project-name requires a value');
-      options.projectName = value;
+      if (!value || value.startsWith('-')) throw new Error(`${arg} requires a value`);
+      if (arg === '--project-name') options.projectName = value;
+      else options.template = value;
       i += 1;
     } else if (!arg.startsWith('-') && !options.root) {
       options.root = arg;
@@ -63,6 +64,20 @@ function writeInitFile(options, relativePath, content, actions) {
   actions.push(action('created', target));
 }
 
+function ensureInitDirectory(options, relativePath, actions) {
+  const target = join(options.root, relativePath);
+  if (existsSync(target)) {
+    actions.push(action('skipped', target));
+    return;
+  }
+  if (options.dryRun) {
+    actions.push(action('would_create', target));
+    return;
+  }
+  mkdirSync(target, { recursive: true });
+  actions.push(action('created', target));
+}
+
 function ensureGitignoreEntry(options, entry, actions) {
   const target = join(options.root, '.gitignore');
   const existed = existsSync(target);
@@ -294,14 +309,27 @@ export function runInit(argv, usage) {
 
   if (!options.dryRun) mkdirSync(options.root, { recursive: true });
 
+  const configExists = existsSync(join(options.root, 'dotdotgod.config.json'));
+  const template = configExists ? null : resolveInitializationTemplate(options.template);
+  if (template && !template.ok) initError(options, template.error.code, template.error.message);
+
   const actions = [];
   for (const [relativePath, content] of initFiles(options)) writeInitFile(options, relativePath, content, actions);
+  if (template?.source === 'bundled') {
+    for (const item of builtInTemplateScaffold(template.name) ?? []) {
+      if (item.type === 'directory') ensureInitDirectory(options, item.path, actions);
+      else writeInitFile(options, item.path, item.content, actions);
+    }
+  }
 
-  writeInitFile(options, 'dotdotgod.config.json', defaultDotdotgodConfigText(), actions);
+  writeInitFile(options, 'dotdotgod.config.json', template?.text ?? '', 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, dotdotSetting: options.dotdotSetting, actions };
+  const payload = { ok: true, command: 'init', root: options.root, projectName: options.projectName, 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 for (const item of actions) console.log(formatAction(item));
+  else {
+    if (template) console.log(`template      ${template.source}:${template.name} (${template.selectedBy})`);
+    for (const item of actions) console.log(formatAction(item));
+  }
 }

package/src/memory/config.mjs

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { rel } from '../common/paths.mjs';
 import { isKebabCase } from '../docs/markdown.mjs';
+import { validateEmbeddingProfile } from '../query/embedding-config.mjs';
 
 const MEMORY_CONFIG_FILE = 'dotdotgod.config.json';
 const MEMORY_SCOPES = new Set(['shared', 'local']);
@@ -335,6 +336,10 @@ export function validateMemoryConfigData(data, root = '.', file = 'dotdotgod.con
     add('MEMORY_CONFIG_INVALID', null, 'Config must be a JSON object.');
     return errors;
   }
+  if (data.embedding !== undefined) {
+    try { validateEmbeddingProfile(data.embedding, 'embedding'); }
+    catch (error) { add('EMBEDDING_CONFIG_INVALID', 'embedding', error instanceof Error ? error.message : String(error)); }
+  }
   const traceability = data.traceability;
   if (traceability !== undefined) {
     if (!traceability || typeof traceability !== 'object' || Array.isArray(traceability)) {

package/src/query/embedder.mjs

@@ -1,24 +1,82 @@
-import { VECTOR_DIMENSIONS, VECTOR_MODEL } from './store.mjs';
+import { embeddingProfileIdentity, resolveEmbeddingProfile } from './embedding-config.mjs';
 
-let extractorPromise;
+const localPipelines = new Map();
 
-async function extractor() {
-  if (!extractorPromise) {
-    extractorPromise = import('@huggingface/transformers').then(async ({ env, pipeline }) => {
+function normalize(row) {
+  if (!Array.isArray(row) || row.length === 0 || row.some((value) => !Number.isFinite(value))) throw new Error('Embedding provider returned an invalid vector.');
+  const norm = Math.sqrt(row.reduce((sum, value) => sum + value * value, 0));
+  if (!Number.isFinite(norm) || norm === 0) throw new Error('Embedding provider returned a zero-length vector.');
+  return row.map((value) => value / norm);
+}
+
+async function localEmbedder(profile) {
+  if (!localPipelines.has(profile.model)) {
+    localPipelines.set(profile.model, import('@huggingface/transformers').then(async ({ env, pipeline }) => {
       env.allowLocalModels = true;
-      return pipeline('feature-extraction', VECTOR_MODEL);
-    });
+      return pipeline('feature-extraction', profile.model);
+    }));
   }
-  return extractorPromise;
+  const model = await localPipelines.get(profile.model);
+  return async (texts) => (await model(texts, { pooling: 'mean', normalize: true })).tolist().map(normalize);
+}
+
+function credential(profile) {
+  if (profile.apiKey) return profile.apiKey;
+  if (!profile.apiKeyEnv) return null;
+  const value = process.env[profile.apiKeyEnv];
+  if (!value) throw new Error(`Embedding credential environment variable is not set: ${profile.apiKeyEnv}`);
+  return value;
+}
+
+async function postJson(url, body, profile) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 30000);
+  try {
+    const key = credential(profile);
+    const response = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...(key ? { authorization: `Bearer ${key}` } : {}) }, body: JSON.stringify(body), signal: controller.signal });
+    if (!response.ok) {
+      const category = response.status === 401 || response.status === 403 ? 'authentication' : response.status === 429 ? 'rate limit' : `HTTP ${response.status}`;
+      throw new Error(`Remote embedding ${category} failure.`);
+    }
+    try { return await response.json(); } catch { throw new Error('Remote embedding returned malformed JSON.'); }
+  } catch (error) {
+    if (error?.name === 'AbortError') throw new Error('Remote embedding request timed out.');
+    throw error;
+  } finally { clearTimeout(timer); }
+}
+
+function remoteEmbedder(profile) {
+  if (profile.provider === 'ollama') return async (texts) => {
+    const data = await postJson(`${profile.baseUrl ?? 'http://localhost:11434'}/api/embed`, { model: profile.model, input: texts }, profile);
+    if (!Array.isArray(data.embeddings)) throw new Error('Ollama embedding response is missing embeddings.');
+    return data.embeddings.map(normalize);
+  };
+  return async (texts) => {
+    const data = await postJson(`${profile.baseUrl ?? 'https://api.openai.com/v1'}/embeddings`, { model: profile.model, input: texts }, profile);
+    if (!Array.isArray(data.data)) throw new Error('OpenAI-compatible embedding response is missing data.');
+    const ordered = [...data.data].sort((a, b) => a.index - b.index).map((item) => item.embedding);
+    return ordered.map(normalize);
+  };
+}
+
+export async function createEmbedder(profile) {
+  const embed = profile.provider === 'local' ? await localEmbedder(profile) : remoteEmbedder(profile);
+  return async (texts) => {
+    if (texts.length === 0) return [];
+    const rows = await embed(texts);
+    if (!Array.isArray(rows) || rows.length !== texts.length) throw new Error('Embedding provider returned an unexpected vector count.');
+    const dimensions = rows[0]?.length;
+    if (!dimensions || rows.some((row) => row.length !== dimensions)) throw new Error('Embedding provider returned inconsistent vector dimensions.');
+    return rows;
+  };
+}
+
+export async function resolveEmbedder(root, options = {}) {
+  const resolved = options.profile ? { profile: options.profile, source: options.source ?? 'injected', path: null } : resolveEmbeddingProfile(root, options);
+  return { ...resolved, identity: embeddingProfileIdentity(resolved.profile), embed: options.embed ?? await createEmbedder(resolved.profile) };
 }
 
 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;
+  const { embed } = await resolveEmbedder('.');
+  return embed(texts);
 }

package/src/query/embedding-config.mjs

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const DEFAULT_EMBEDDING_PROFILE = Object.freeze({ provider: 'local', model: 'Xenova/multilingual-e5-small' });
+export const EMBEDDING_PROVIDERS = Object.freeze(['local', 'openai-compatible', 'ollama']);
+
+function readJson(path, label) {
+  if (!existsSync(path)) return null;
+  try { return JSON.parse(readFileSync(path, 'utf8')); }
+  catch (error) { throw new Error(`Invalid ${label} JSON: ${error instanceof Error ? error.message : String(error)}`); }
+}
+
+export function validateEmbeddingProfile(profile, label = 'embedding') {
+  if (!profile || typeof profile !== 'object' || Array.isArray(profile)) throw new Error(`${label} must be an object.`);
+  const allowed = new Set(['provider', 'model', 'baseUrl', 'apiKey', 'apiKeyEnv']);
+  const unknown = Object.keys(profile).find((key) => !allowed.has(key));
+  if (unknown) throw new Error(`${label}.${unknown} is not supported.`);
+  if (!EMBEDDING_PROVIDERS.includes(profile.provider)) throw new Error(`${label}.provider must be local, openai-compatible, or ollama.`);
+  if (typeof profile.model !== 'string' || !profile.model.trim()) throw new Error(`${label}.model must be a non-empty string.`);
+  for (const key of ['baseUrl', 'apiKey', 'apiKeyEnv']) if (profile[key] !== undefined && (typeof profile[key] !== 'string' || !profile[key].trim())) throw new Error(`${label}.${key} must be a non-empty string.`);
+  if (profile.apiKey !== undefined && profile.apiKeyEnv !== undefined) throw new Error(`${label}.apiKey and ${label}.apiKeyEnv are mutually exclusive.`);
+  if (profile.provider === 'local' && ['baseUrl', 'apiKey', 'apiKeyEnv'].some((key) => profile[key] !== undefined)) throw new Error(`${label} local provider does not accept remote connection fields.`);
+  if (profile.baseUrl !== undefined) {
+    let url;
+    try { url = new URL(profile.baseUrl); } catch { throw new Error(`${label}.baseUrl must be an absolute HTTP(S) URL.`); }
+    if (!['http:', 'https:'].includes(url.protocol)) throw new Error(`${label}.baseUrl must use HTTP or HTTPS.`);
+    if (url.username || url.password) throw new Error(`${label}.baseUrl must not contain credentials.`);
+  }
+  return { ...profile, model: profile.model.trim(), ...(profile.baseUrl ? { baseUrl: profile.baseUrl.replace(/\/$/, '') } : {}) };
+}
+
+export function sanitizeEmbeddingProfile(profile) {
+  const { apiKey, ...safe } = profile;
+  return { ...safe, ...(apiKey ? { apiKey: '[redacted]' } : {}) };
+}
+
+export function embeddingProfileIdentity(profile) {
+  const { apiKey, apiKeyEnv, ...identity } = profile;
+  return identity;
+}
+
+export function resolveEmbeddingProfile(root = '.', options = {}) {
+  const home = options.home ?? homedir();
+  const globalPath = join(home, '.dotdotgod', 'config.json');
+  const projectPath = join(root, 'dotdotgod.config.json');
+  const projectConfig = readJson(projectPath, 'project config');
+  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 };
+}

package/src/query/store.mjs

@@ -1,15 +1,20 @@
+import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
-export const VECTOR_SCHEMA_VERSION = 1;
+export const VECTOR_SCHEMA_VERSION = 2;
 export const VECTOR_MODEL = 'Xenova/multilingual-e5-small';
 export const VECTOR_DIMENSIONS = 384;
 
-export function isValidNormalizedVectorValues(values) {
-  if (!values || values.length % VECTOR_DIMENSIONS !== 0) return false;
-  for (let offset = 0; offset < values.length; offset += VECTOR_DIMENSIONS) {
+export function profileFingerprint(identity) {
+  return createHash('sha256').update(JSON.stringify(identity)).digest('hex');
+}
+
+export function isValidNormalizedVectorValues(values, dimensions = VECTOR_DIMENSIONS) {
+  if (!Number.isInteger(dimensions) || dimensions < 1 || !values || values.length % dimensions !== 0) return false;
+  for (let offset = 0; offset < values.length; offset += dimensions) {
     let squaredNorm = 0;
-    for (let index = 0; index < VECTOR_DIMENSIONS; index += 1) {
+    for (let index = 0; index < dimensions; index += 1) {
       const value = values[offset + index];
       if (!Number.isFinite(value) || value < -1 || value > 1) return false;
       squaredNorm += value * value;
@@ -21,29 +26,23 @@ export function isValidNormalizedVectorValues(values) {
 
 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'),
-  };
+  return { directory, manifest: join(directory, 'manifest.json'), chunks: join(directory, 'chunks.jsonl'), embeddings: join(directory, 'embeddings.f32') };
 }
 
-export function readVectorCache(root) {
+export function readVectorCache(root, identity = null) {
   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;
+    if (manifest.schemaVersion !== VECTOR_SCHEMA_VERSION || !Number.isInteger(manifest.dimensions) || manifest.dimensions < 1) return null;
+    if (identity && manifest.profileFingerprint !== profileFingerprint(identity)) 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;
+    if (buffer.byteLength !== chunks.length * manifest.dimensions * 4) return null;
     const vectors = new Float32Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 4);
-    if (!isValidNormalizedVectorValues(vectors)) return null;
+    if (!isValidNormalizedVectorValues(vectors, manifest.dimensions)) return null;
     return { manifest, chunks, vectors: new Float32Array(vectors) };
-  } catch {
-    return null;
-  }
+  } catch { return null; }
 }
 
 function atomicWrite(path, data) {
@@ -54,23 +53,16 @@ function atomicWrite(path, data) {
 
 export function writeVectorCache(root, chunks, vectors, metadata = {}) {
   const paths = vectorCachePaths(root);
+  const dimensions = metadata.dimensions;
+  if (!Number.isInteger(dimensions) || dimensions < 1) throw new Error('Vector dimensions must be a positive integer.');
   mkdirSync(paths.directory, { recursive: true });
-  if (vectors.length !== chunks.length * VECTOR_DIMENSIONS) throw new Error('Vector count does not match chunk metadata.');
-  if (!isValidNormalizedVectorValues(vectors)) throw new Error('Vectors must contain finite normalized values.');
-  const manifest = {
-    schemaVersion: VECTOR_SCHEMA_VERSION,
-    model: VECTOR_MODEL,
-    dimensions: VECTOR_DIMENSIONS,
-    chunks: chunks.length,
-    generatedAt: new Date().toISOString(),
-    ...metadata,
-  };
+  if (vectors.length !== chunks.length * dimensions) throw new Error('Vector count does not match chunk metadata.');
+  if (!isValidNormalizedVectorValues(vectors, dimensions)) throw new Error('Vectors must contain finite normalized values.');
+  const manifest = { schemaVersion: VECTOR_SCHEMA_VERSION, 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 });
-}
+export function removeVectorCache(root) { rmSync(vectorCachePaths(root).directory, { recursive: true, force: true }); }