@dotdotgod/cli 0.2.28 → 0.3.1

package/package.json

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

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] [--template NAME] [--dotdot-setting] [--dry-run] [--json]
+  dotdotgod init <root> [--project-name NAME] [--template NAME] [--documentation-root PATH] [--dotdot-setting] [--dry-run] [--json]
 
 Create AGENTS.md, agent entrypoints, docs indexes, a project config from an initialization template, and local memory gitignore entries.`;
     case 'index':
@@ -36,6 +36,11 @@ Create dotdotgod.config.json from a bundled or user template. Without --template
   dotdotgod query <root> <query> [--limit n] [--json]
 
 Search shared project documentation with the resolved local or remote embedding provider.`;
+    case 'map':
+      return `Usage:
+  dotdotgod map <root> [--depth <positive-integer>] [--json]
+
+Render the configured shared Markdown documentation map without modifying the project.`;
     case 'resolve':
       return `Usage:
   dotdotgod resolve <root> <ref> [--max-results n] [--include-archive] [--json]`;
@@ -73,6 +78,7 @@ Commands:
   init                  Initialize project memory files.
   config                Inspect or initialize project configuration.
   query                 Search project documentation.
+  map                   Render the project documentation map.
   resolve               Resolve a project reference.
   expand                Expand references in a prompt.
   validate              Validate project memory and documentation.

package/src/commands/config.mjs

@@ -40,6 +40,7 @@ function formatConfigOutput(payload) {
   const errors = payload.errors ?? [];
   const lines = [`dotdotgod config: ${payload.source}${errors.length > 0 ? ' (invalid; using defaults)' : ''}`];
   lines.push(`- path: ${payload.path ?? 'none'}`);
+  lines.push(`- documentation root: ${payload.config.documentation.root}`);
   lines.push(`- memory areas: ${payload.config.areas.length}`);
   lines.push(`- embedding: ${payload.embedding.profile.provider}/${payload.embedding.profile.model} (${payload.embedding.source})`);
   lines.push(`- traceability required: ${(payload.config.traceability.required ?? []).join(', ') || 'none'}`);

package/src/commands/map.mjs

@@ -0,0 +1,41 @@
+import { resolve } from 'node:path';
+import { buildDocumentationMap } from '../memory/documentation-map.mjs';
+
+function fail(json, code, message) {
+  if (json) console.log(JSON.stringify({ ok: false, error: { code, message } }, null, 2));
+  else console.error(message);
+  process.exit(2);
+}
+
+function parseMapOptions(argv) {
+  const options = { root: '.', depth: 5, json: false };
+  let rootSet = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--json') options.json = true;
+  }
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--json') continue;
+    if (arg === '--depth') {
+      const value = argv[index + 1];
+      if (!value || !/^\d+$/.test(value) || Number(value) < 1) fail(options.json, 'INVALID_DEPTH', '--depth requires a positive integer.');
+      options.depth = Number(value);
+      index += 1;
+    } else if (!arg.startsWith('-') && !rootSet) {
+      options.root = arg;
+      rootSet = true;
+    } else if (!arg.startsWith('-')) fail(options.json, 'UNEXPECTED_ARGUMENT', `Unexpected argument: ${arg}`);
+    else fail(options.json, 'UNKNOWN_OPTION', `Unknown option: ${arg}`);
+  }
+  options.root = resolve(options.root);
+  return options;
+}
+
+export function runMap(argv) {
+  const options = parseMapOptions(argv);
+  const result = buildDocumentationMap(options.root, { depth: options.depth });
+  if (!result.ok) fail(options.json, result.error.code, result.error.message);
+  if (options.json) console.log(JSON.stringify(result, null, 2));
+  else console.log(result.tree);
+}

package/src/commands/query.mjs

@@ -63,7 +63,7 @@ export async function buildVectorIndex(root, 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 chunks = collectDocumentationChunks(root, exclude, config.documentation?.root ?? 'docs');
   const cached = readVectorCache(root, resolved.identity);
   const cachedOffsets = new Map((cached?.chunks ?? []).map((chunk, index) => [chunk.fingerprint, index]));
   const rows = new Array(chunks.length);

package/src/config/templates.mjs

@@ -42,11 +42,11 @@ const BUILT_IN_TEMPLATE_SCAFFOLDS = {
   ],
 };
 
-export function builtInTemplateScaffold(name) {
+export function builtInTemplateScaffold(name, { documentationRoot = 'docs' } = {}) {
   const entries = BUILT_IN_TEMPLATE_SCAFFOLDS[name];
   if (!entries) return null;
   return entries.map(([path, heading, description]) => ({
-    path,
+    path: path.replace(/^docs(?=\/|$)/, documentationRoot),
     type: heading ? 'file' : 'directory',
     ...(heading ? { content: `# ${heading}\n\n${description}` } : {}),
   }));
@@ -122,7 +122,13 @@ function withPolicy(areas, required, definitionsList) {
   return config;
 }
 
-export function builtInTemplateData(name) {
+function rebaseBuiltIn(value, root) {
+  if (Array.isArray(value)) return value.map(item => rebaseBuiltIn(item, root));
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, rebaseBuiltIn(item, root)]));
+  return typeof value === 'string' ? value.replace(/^docs(?=\/|$)/, root) : value;
+}
+
+function rawBuiltInTemplateData(name) {
   if (name === 'software') return defaultDotdotgodConfigData();
   if (name === 'research') return withPolicy([
     area('spec', 'Research Specifications', ['docs/spec/**'], 'research-contract', 85),
@@ -162,8 +168,13 @@ export function builtInTemplateData(name) {
   return null;
 }
 
-export function builtInTemplateText(name) {
-  const data = builtInTemplateData(name);
+export function builtInTemplateData(name, { documentationRoot = 'docs' } = {}) {
+  const data = rawBuiltInTemplateData(name);
+  return data ? rebaseBuiltIn(data, documentationRoot) : null;
+}
+
+export function builtInTemplateText(name, options) {
+  const data = builtInTemplateData(name, options);
   return data ? `${JSON.stringify(data, null, 2)}\n` : null;
 }
 

package/src/core.mjs

@@ -4,6 +4,7 @@ import { runValidate } from './validate/run.mjs';
 import { runIndex, runStatus } from './index/cache.mjs';
 import { runConfig } from './commands/config.mjs';
 import { runQuery } from './commands/query.mjs';
+import { runMap } from './commands/map.mjs';
 import { runResolve, runExpand } from './reference/resolve.mjs';
 import { runTraceability } from './commands/traceability.mjs';
 import { runGraph } from './commands/graph.mjs';
@@ -13,12 +14,13 @@ export { commandUsage, hasHelpToken, helpCommandFromArgs, isHelpToken, isVersion
 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 { DEFAULT_IMPACT_RANKING_POLICY, DEFAULT_LOAD_POLICY, DEFAULT_VALIDATION_POLICY, SEMANTIC_RELATIONS, cloneImpactRankingPolicy, cloneLoadPolicy, cloneReferenceExpansionPolicy, cloneValidationPolicy, defaultDotdotgodConfigData, defaultDotdotgodConfigText, defaultMemoryConfig, isValidDocumentationRoot, normalizeDocumentationRoot, 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';
 export { buildMemoryAreas, detectCommandGuidance, detectPackageManager } from './memory/summary.mjs';
+export { buildDocumentationMap, formatDocumentationTree } from './memory/documentation-map.mjs';
 export { isReadmeIndexPath, retrievalMetadataForPath } from './graph/metadata.mjs';
 export { buildGraph } from './graph/extract.mjs';
 export { addDeterministicSemanticEdges } from './graph/semantic.mjs';
@@ -29,6 +31,7 @@ export { buildChangedFileProfile, MAX_VECTOR_PROFILE_CHARS, MAX_VECTOR_PROFILE_F
 export { buildVectorImpactOverlay, VECTOR_RELATION_WEIGHT } from './impact/vector-overlay.mjs';
 export { formatCompactImpactOutput, formatYmlGraphImpactError, formatYmlImpactOutput } from './impact/format.mjs';
 export { runConfig } from './commands/config.mjs';
+export { runMap } from './commands/map.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, profileFingerprint, vectorCachePaths, writeVectorCache } from './query/store.mjs';
@@ -51,6 +54,7 @@ export async function runCli(argv = process.argv.slice(2)) {
   else if (command === 'config') runConfig(args);
   else if (command === 'status') runStatus(args);
   else if (command === 'query') await runQuery(args);
+  else if (command === 'map') runMap(args);
   else if (command === 'resolve') runResolve(args);
   else if (command === 'expand') runExpand(args);
   else if (command === 'traceability') runTraceability(args);

package/src/graph/communities.mjs

@@ -1,17 +1,15 @@
 import { Graph, leiden } from 'leiden-ts';
+import { resolveMemoryArea } from '../memory/config.mjs';
 
 const DURABLE_COMMUNITY_NODE_TYPES = new Set(['file', 'memory_area', 'package_resource', 'package', 'script', 'binary']);
 
-function docsArea(path = '') {
-  if (path.startsWith('docs/spec/')) return 'spec';
-  if (path.startsWith('docs/test/')) return 'test';
-  if (path.startsWith('docs/arch/')) return 'architecture';
-  if (path.startsWith('docs/plan/')) return 'active-plan';
-  if (path.startsWith('docs/archive/')) return 'archive';
-  return null;
+function docsArea(path = '', config) {
+  const area = resolveMemoryArea(path, config);
+  const roles = { 'behavior-truth': 'spec', 'verification-knowledge': 'test', 'architecture-rationale': 'architecture', 'active-task-intent': 'active-plan', 'historical-memory-map': 'archive', 'historical-memory-body': 'archive', 'project-documentation': 'docs' };
+  return roles[area?.role] ?? null;
 }
 
-function communityKeyForNode(node) {
+function communityKeyForNode(node, config) {
   if (node.type === 'memory_area') return `memory-${node.area}`;
   const path = node.path ?? node.id?.replace(/^file:/, '').replace(/^test:/, '') ?? '';
   if (path.startsWith('packages/pi/extensions/plan-mode/')) return 'pi-plan-mode';
@@ -21,7 +19,7 @@ function communityKeyForNode(node) {
   if (path.startsWith('packages/claude-code/')) return 'claude-code-adapter';
   if (path.startsWith('packages/codex/')) return 'codex-adapter';
   if (path.startsWith('packages/shared/')) return 'shared-adapter-resources';
-  const area = docsArea(path);
+  const area = docsArea(path, config);
   if (area) return `docs-${area}`;
   if (node.type === 'package' || node.type === 'script' || node.type === 'binary' || node.type === 'dependency' || node.type === 'package_resource') return 'package-metadata';
   if (node.type === 'command') return `command-${node.name}`;
@@ -47,11 +45,11 @@ export function relationWeight(relation) {
   return 1;
 }
 
-function addCommunityDetails(community, node, itemLimit) {
+function addCommunityDetails(community, node, itemLimit, config) {
   community.nodeCount += 1;
   const path = node.path ?? node.id?.replace(/^file:/, '').replace(/^test:/, '');
   if (node.type === 'file') {
-    const area = docsArea(path);
+    const area = docsArea(path, config);
     community.omitted += addBounded(area ? community.docs : community.files, path, itemLimit);
   } else if (node.type === 'heading' && node.path) community.omitted += addBounded(community.docs, node.path, itemLimit);
   else if (node.type === 'memory_area') community.omitted += addBounded(community.docs, `memory_area:${node.area}`, itemLimit);
@@ -65,14 +63,14 @@ function makeCommunity(id, label = communityLabel(id)) {
   return { id, label, files: [], docs: [], commands: [], events: [], tests: [], packageResources: [], nodeCount: 0, edgeCount: 0, omitted: 0 };
 }
 
-function deterministicCommunities(graph, maxCommunities, itemLimit, fallback = false) {
+function deterministicCommunities(graph, maxCommunities, itemLimit, config, fallback = false) {
   const map = new Map();
   for (const node of graph.nodes) {
-    const id = communityKeyForNode(node);
+    const id = communityKeyForNode(node, config);
     if (!map.has(id)) map.set(id, makeCommunity(id));
-    addCommunityDetails(map.get(id), node, itemLimit);
+    addCommunityDetails(map.get(id), node, itemLimit, config);
   }
-  const nodeToCommunity = new Map(graph.nodes.map((node) => [node.id, communityKeyForNode(node)]));
+  const nodeToCommunity = new Map(graph.nodes.map((node) => [node.id, communityKeyForNode(node, config)]));
   for (const edge of graph.edges) {
     const source = nodeToCommunity.get(edge.source);
     const target = nodeToCommunity.get(edge.target);
@@ -112,18 +110,19 @@ function buildLeidenProjection(graph) {
   return { durable, edges: [...adjacency.entries()].map(([key, weight]) => [...key.split(':').map(Number), weight]) };
 }
 
-function labelForLeidenCommunity(nodes) {
+function labelForLeidenCommunity(nodes, config) {
   const counts = new Map();
-  for (const node of nodes) counts.set(communityKeyForNode(node), (counts.get(communityKeyForNode(node)) ?? 0) + 1);
+  for (const node of nodes) counts.set(communityKeyForNode(node, config), (counts.get(communityKeyForNode(node, config)) ?? 0) + 1);
   return [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))[0]?.[0] ?? 'community';
 }
 
 export function buildCommunities(index, limits = {}) {
+  const config = index?.memoryConfig;
   const graph = index?.graph ?? { nodes: [], edges: [] };
   const maxCommunities = limits.communities ?? 8;
   const itemLimit = limits.items ?? 8;
   const projection = buildLeidenProjection(graph);
-  if (projection.durable.length < 3 || projection.edges.length === 0) return deterministicCommunities(graph, maxCommunities, itemLimit, true);
+  if (projection.durable.length < 3 || projection.edges.length === 0) return deterministicCommunities(graph, maxCommunities, itemLimit, config, true);
 
   try {
     const result = leiden(Graph.fromEdgeList(projection.durable.length, projection.edges), { seed: 42, resolution: limits.resolution ?? 1.0 });
@@ -133,9 +132,9 @@ export function buildCommunities(index, limits = {}) {
       byCommunity.get(communityId).push(projection.durable[index]);
     });
     const communities = [...byCommunity.entries()].map(([communityId, nodes]) => {
-      const labelKey = labelForLeidenCommunity(nodes);
+      const labelKey = labelForLeidenCommunity(nodes, config);
       const community = makeCommunity(`leiden-${communityId}`, communityLabel(labelKey));
-      for (const node of nodes.sort((a, b) => a.id.localeCompare(b.id))) addCommunityDetails(community, node, itemLimit);
+      for (const node of nodes.sort((a, b) => a.id.localeCompare(b.id))) addCommunityDetails(community, node, itemLimit, config);
       return community;
     });
     const nodeToCommunity = new Map();
@@ -148,6 +147,6 @@ export function buildCommunities(index, limits = {}) {
     const all = communities.sort((a, b) => (b.nodeCount + b.edgeCount) - (a.nodeCount + a.edgeCount) || a.id.localeCompare(b.id));
     return { communities: all.slice(0, maxCommunities), omitted: Math.max(0, all.length - maxCommunities), total: all.length, method: 'leiden', fallback: false, modularity: result.modularity };
   } catch {
-    return deterministicCommunities(graph, maxCommunities, itemLimit, true);
+    return deterministicCommunities(graph, maxCommunities, itemLimit, config, true);
   }
 }

package/src/impact/report.mjs

@@ -96,13 +96,13 @@ function buildCombinedImpactReport(index, changedPaths, limits = {}) {
     const retrieval = node.retrieval ?? retrievalMetadataForPath(path);
     const reasonSignals = reasonList.map((reason) => `reason:${reason}`);
     const hasCuratedEvidence = reasonList.some((reason) => curatedRelations.has(reason.replace(/^incoming:/, '')));
-    const scored = scoreImpactItem({ ...node, reasons: reasonList, retrieval }, seedSet, changedPaths, policy, pprScores);
+    const scored = scoreImpactItem({ ...node, reasons: reasonList, retrieval }, seedSet, changedPaths, policy, pprScores, config);
     return { ...node, reasons: reasonList, hasCuratedEvidence, ...(vectorEvidence.has(id) ? { vectorEvidence: vectorEvidence.get(id) } : {}), retrieval: { ...retrieval, signals: [...new Set([...(retrieval.signals ?? []), ...reasonSignals])] }, ...scored };
   }).sort(compareImpactItems(seeds));
   const related = selectImpactItems(relatedAll, maxRelated, seeds);
   for (const item of related) {
     if (item.type === 'file') {
-      const area = docsArea(item.path);
+      const area = docsArea(item.path, config);
       if (area) addImpactItem(groups.docs, { ...item, area }, limits.docs ?? 10);
       else if (isTestPath(item.path)) addImpactItem(groups.tests, item, limits.tests ?? 10);
       else addImpactItem(groups.files, item, limits.files ?? 10);

package/src/impact/scoring.mjs

@@ -1,18 +1,14 @@
-import { SEMANTIC_RELATIONS } from '../memory/config.mjs';
+import { SEMANTIC_RELATIONS, resolveMemoryArea } from '../memory/config.mjs';
 import { relationWeight } from '../graph/communities.mjs';
 
 export function isTestPath(path = '') {
   return /(^|\/)(test|tests)\//.test(path) || /\.(test|spec)\.(mjs|cjs|js|jsx|ts|tsx)$/.test(path);
 }
 
-export function docsArea(path = '') {
-  if (path.startsWith('docs/spec/')) return 'spec';
-  if (path.startsWith('docs/arch/')) return 'arch';
-  if (path.startsWith('docs/test/')) return 'test-docs';
-  if (path.startsWith('docs/plan/')) return 'plan';
-  if (path.startsWith('docs/archive/')) return 'archive-index';
-  if (path.startsWith('docs/')) return 'docs';
-  return undefined;
+export function docsArea(path = '', config) {
+  const area = resolveMemoryArea(path, config);
+  const byRole = { 'behavior-truth': 'spec', 'architecture-rationale': 'arch', 'verification-knowledge': 'test-docs', 'active-task-intent': 'plan', 'historical-memory-map': 'archive-index', 'historical-memory-body': 'archive-index', 'project-documentation': 'docs', 'documentation-routing-map': 'docs' };
+  return byRole[area?.role] ?? (area?.id === 'spec' ? 'spec' : area?.id === 'architecture' ? 'arch' : area?.id === 'test' ? 'test-docs' : undefined);
 }
 
 function clamp(value, min, max) {
@@ -61,10 +57,10 @@ export function buildPersonalizedPageRank(graph, seeds, policy) {
   return ranks;
 }
 
-export function scoreImpactItem(item, seeds, changedPaths, policy, pprScores) {
+export function scoreImpactItem(item, seeds, changedPaths, policy, pprScores, config) {
   const seedSet = seeds instanceof Set ? seeds : new Set(Array.isArray(seeds) ? seeds : [seeds]);
   const paths = Array.isArray(changedPaths) ? changedPaths : [changedPaths];
-  const archiveSeeded = paths.some((path) => path.startsWith('docs/archive/'));
+  const archiveSeeded = paths.some((path) => resolveMemoryArea(path, config)?.role?.startsWith('historical-memory'));
   if (seedSet.has(item.id)) return { impactScore: 100, scoreBreakdown: { seed: 100, connection: { ppr: 80, reference: policy.ppr.reference }, memory: { priority: 20, policyAdjustments: 0 } } };
   const retrieval = item.retrieval ?? {};
   const probability = pprScores.get(item.id) ?? 0;

package/src/init.mjs

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
-import { builtInTemplateScaffold, resolveInitializationTemplate } from './config/templates.mjs';
+import { builtInTemplateData, builtInTemplateScaffold, resolveInitializationTemplate } from './config/templates.mjs';
+import { isValidDocumentationRoot, normalizeDocumentationRoot, readMemoryConfig } from './memory/config.mjs';
 
 function action(status, path, extra = {}) {
   return { status, path, ...extra };
@@ -12,17 +13,18 @@ function formatAction(item) {
 }
 
 function parseInitOptions(argv) {
-  const options = { root: null, projectName: '', dotdotSetting: false, dryRun: false, json: false, template: null };
+  const options = { root: null, projectName: '', dotdotSetting: false, dryRun: false, json: false, template: null, documentationRoot: 'docs', documentationRootExplicit: 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 === '--dry-run') options.dryRun = true;
-    else if (arg === '--project-name' || arg === '--template') {
+    else if (arg === '--project-name' || arg === '--template' || arg === '--documentation-root') {
       const value = argv[i + 1];
       if (!value || value.startsWith('-')) throw new Error(`${arg} requires a value`);
       if (arg === '--project-name') options.projectName = value;
-      else options.template = value;
+      else if (arg === '--template') options.template = value;
+      else { options.documentationRoot = normalizeDocumentationRoot(value); options.documentationRootExplicit = true; }
       i += 1;
     } else if (!arg.startsWith('-') && !options.root) {
       options.root = arg;
@@ -33,6 +35,7 @@ function parseInitOptions(argv) {
     }
   }
   if (!options.root) throw new Error('Missing required argument: <root>');
+  if (!isValidDocumentationRoot(options.documentationRoot)) throw new Error('Invalid --documentation-root: expected a safe repository-relative directory');
   options.root = resolve(options.root);
   if (!options.projectName) options.projectName = basename(options.root);
   return options;
@@ -287,7 +290,7 @@ function initFiles(options) {
     files.push(['docs/arch/DOCS_STRUCTURE.md', docsStructureContent()]);
     files.push(['docs/arch/CODE_CONVENTIONS.md', codeConventionsContent()]);
   }
-  return files;
+  return files.map(([path, content]) => [path.replace(/^docs(?=\/|$)/, options.documentationRoot), content.replaceAll('docs/', `${options.documentationRoot}/`).replaceAll('`docs`', `\`${options.documentationRoot}\``)]);
 }
 
 export function runInit(argv, usage) {
@@ -310,13 +313,19 @@ 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 (configExists && options.documentationRootExplicit) {
+    const existingRoot = readMemoryConfig(options.root).documentation.root;
+    if (existingRoot !== options.documentationRoot) initError(options, 'DOCUMENTATION_ROOT_CONFLICT', `Existing config uses documentation root ${existingRoot}; initialization does not migrate documentation.`);
+  }
+  let template = configExists ? null : resolveInitializationTemplate(options.template);
   if (template && !template.ok) initError(options, template.error.code, template.error.message);
+  if (template?.source === 'custom' && normalizeDocumentationRoot(template.data.documentation?.root ?? 'docs') !== options.documentationRoot) initError(options, 'DOCUMENTATION_ROOT_CONFLICT', 'Custom template documentation.root conflicts with --documentation-root; custom policy paths are never rewritten.');
+  if (template?.source === 'bundled') { const data = builtInTemplateData(template.name, { documentationRoot: options.documentationRoot }); template = { ...template, data, text: `${JSON.stringify(data, null, 2)}\n` }; }
 
   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) ?? []) {
+    for (const item of builtInTemplateScaffold(template.name, { documentationRoot: options.documentationRoot }) ?? []) {
       if (item.type === 'directory') ensureInitDirectory(options, item.path, actions);
       else writeInitFile(options, item.path, item.content, actions);
     }
@@ -324,9 +333,9 @@ export function runInit(argv, usage) {
 
   writeInitFile(options, 'dotdotgod.config.json', template?.text ?? '', actions);
 
-  for (const entry of ['docs/plan', 'docs/archive', '.dotdotgod']) ensureGitignoreEntry(options, entry, actions);
+  for (const entry of [`${options.documentationRoot}/plan`, `${options.documentationRoot}/archive`, '.dotdotgod']) ensureGitignoreEntry(options, entry, 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 };
+  const payload = { ok: true, command: 'init', root: options.root, projectName: options.projectName, documentationRoot: options.documentationRoot, dryRun: options.dryRun, dotdotSetting: options.dotdotSetting, template: template ? { name: template.name, source: template.source, selectedBy: template.selectedBy } : null, actions };
   if (options.json) console.log(JSON.stringify(payload, null, 2));
   else {
     if (template) console.log(`template      ${template.source}:${template.name} (${template.selectedBy})`);

package/src/memory/config.mjs

@@ -5,6 +5,7 @@ import { isKebabCase } from '../docs/markdown.mjs';
 import { validateEmbeddingProfile } from '../query/embedding-config.mjs';
 
 const MEMORY_CONFIG_FILE = 'dotdotgod.config.json';
+export const DEFAULT_DOCUMENTATION_ROOT = 'docs';
 const MEMORY_SCOPES = new Set(['shared', 'local']);
 const MEMORY_FRESHNESS = new Set(['fresh', 'stale']);
 export const DEFAULT_TRACEABILITY_KEYS = [
@@ -65,7 +66,9 @@ const DEFAULT_FUZZY_LOW_SIGNAL_TERMS = [
   'a', 'an', 'and', 'are', 'as', 'by', 'docs', 'document', 'for', 'from', 'it', 'of', 'on', 'plan', 'test', 'the', 'to', 'update', 'version', 'with',
   '계획', '문서', '수정', '업데이트', '버전', '정보', '확인', '테스트',
 ];
-const DEFAULT_MEMORY_AREAS = [
+function memoryAreasForRoot(documentationRoot = DEFAULT_DOCUMENTATION_ROOT) {
+  const d = (path = '') => path ? `${documentationRoot}/${path}` : documentationRoot;
+  return [
   { id: 'rules', label: 'Agent Rules', paths: ['AGENTS.md'], scope: 'shared', freshness: 'fresh', role: 'agent-working-rules', priority: 100, includeBodiesByDefault: true },
   { id: 'agent-entrypoint', label: 'Agent Entrypoints', paths: ['CLAUDE.md', 'CODEX.md'], scope: 'shared', freshness: 'fresh', role: 'agent-specific-entrypoint', priority: 85, includeBodiesByDefault: true },
   { id: 'project-overview', label: 'Project Overview', paths: ['README.md'], scope: 'shared', freshness: 'fresh', role: 'project-map', priority: 85, includeBodiesByDefault: true },
@@ -76,8 +79,10 @@ const DEFAULT_MEMORY_AREAS = [
   { id: 'active-plan', label: 'Active Plans', paths: ['docs/plan/**'], scope: 'local', freshness: 'fresh', role: 'active-task-intent', priority: 95, includeBodiesByDefault: true },
   { id: 'archive-map', label: 'Archive Map', paths: ['docs/archive/README.md'], scope: 'local', freshness: 'stale', role: 'historical-memory-map', priority: 65, includeBodiesByDefault: true },
   { id: 'archive-body', label: 'Archive Body', paths: ['docs/archive/**'], excludePaths: ['docs/archive/README.md'], scope: 'local', freshness: 'stale', role: 'historical-memory-body', priority: 20, includeBodiesByDefault: false },
-  { id: 'docs', label: 'Project Documentation', paths: ['docs/**'], scope: 'shared', freshness: 'fresh', role: 'project-documentation', priority: 60, includeBodiesByDefault: true },
-];
+  { id: 'docs', label: 'Project Documentation', paths: [d('**')], scope: 'shared', freshness: 'fresh', role: 'project-documentation', priority: 60, includeBodiesByDefault: true },
+  ].map(area => ({ ...area, paths: area.paths.map(path => path.replace(/^docs(?=\/|$)/, documentationRoot)), excludePaths: (area.excludePaths ?? []).map(path => path.replace(/^docs(?=\/|$)/, documentationRoot)) }));
+}
+const DEFAULT_MEMORY_AREAS = memoryAreasForRoot();
 
 function cloneClarifyGuidance(clarify) {
   if (!clarify || typeof clarify !== 'object' || Array.isArray(clarify)) return undefined;
@@ -198,8 +203,19 @@ export function clonePlanModePolicy(policy = DEFAULT_PLAN_MODE_POLICY) {
   return { writablePaths: [...(policy.writablePaths ?? DEFAULT_PLAN_MODE_POLICY.writablePaths)] };
 }
 
-export function defaultMemoryConfig() {
-  return { source: 'default', areas: DEFAULT_MEMORY_AREAS.map(cloneArea), traceability: cloneTraceabilityPolicy(), validation: cloneValidationPolicy(), impactRanking: cloneImpactRankingPolicy(), referenceExpansion: cloneReferenceExpansionPolicy(), load: cloneLoadPolicy(), planMode: clonePlanModePolicy() };
+export function normalizeDocumentationRoot(value = DEFAULT_DOCUMENTATION_ROOT) {
+  return String(value).trim().replaceAll('\\', '/').replace(/^\.\//, '').replace(/\/{2,}/g, '/').replace(/^\/+|\/+$/g, '');
+}
+export function isValidDocumentationRoot(value) {
+  if (typeof value !== 'string' || !value.trim() || /^[A-Za-z]:[\\/]/.test(value) || /^[/\\]{2}/.test(value) || value.trim().startsWith('/')) return false;
+  const root = normalizeDocumentationRoot(value);
+  if (!root || root === '.' || root.split('/').some(part => part === '..' || !part || /[*?\[\]{}]/.test(part)) || isSecretLikePathPattern(root)) return false;
+  const first = root.split('/')[0];
+  return first !== 'dotdotgod.config.json' && first !== '.dotdotgod';
+}
+export function defaultMemoryConfig({ documentationRoot = DEFAULT_DOCUMENTATION_ROOT } = {}) {
+  const root = normalizeDocumentationRoot(documentationRoot);
+  return { source: 'default', documentation: { root }, areas: memoryAreasForRoot(root).map(cloneArea), traceability: cloneTraceabilityPolicy({ ...DEFAULT_TRACEABILITY_POLICY, required: [`${root}/spec/**`] }), validation: cloneValidationPolicy(), impactRanking: cloneImpactRankingPolicy(), referenceExpansion: cloneReferenceExpansionPolicy(), load: cloneLoadPolicy({ ...DEFAULT_LOAD_POLICY, documentationSummary: { exclude: [`${root}/plan`, `${root}/archive`] } }), planMode: clonePlanModePolicy({ writablePaths: [`${root}/plan/**`, `${root}/archive/**`] }) };
 }
 
 export function normalizePathPattern(value = '') {
@@ -336,6 +352,10 @@ export function validateMemoryConfigData(data, root = '.', file = 'dotdotgod.con
     add('MEMORY_CONFIG_INVALID', null, 'Config must be a JSON object.');
     return errors;
   }
+  if (data.documentation !== undefined) {
+    if (!data.documentation || typeof data.documentation !== 'object' || Array.isArray(data.documentation)) add('DOCUMENTATION_CONFIG_INVALID', 'documentation', 'Expected an object.');
+    else if (!isValidDocumentationRoot(data.documentation.root)) add('DOCUMENTATION_CONFIG_INVALID_ROOT', 'documentation.root', 'Expected a safe repository-relative directory without traversal, glob syntax, secrets, or reserved config/cache overlap.');
+  }
   if (data.embedding !== undefined) {
     try { validateEmbeddingProfile(data.embedding, 'embedding'); }
     catch (error) { add('EMBEDDING_CONFIG_INVALID', 'embedding', error instanceof Error ? error.message : String(error)); }
@@ -420,7 +440,7 @@ export function validateMemoryConfigData(data, root = '.', file = 'dotdotgod.con
     } else if (planMode.writablePaths !== undefined) {
       const paths = planMode.writablePaths;
       if (!Array.isArray(paths)) add('PLAN_MODE_CONFIG_INVALID_WRITABLE_PATHS', 'planMode.writablePaths', 'Expected an array of documentation path strings.');
-      else if (paths.some((value) => !isValidPathPattern(value) || typeof value !== 'string' || value.trim().startsWith('/') || (!normalizePathPattern(value).startsWith('docs/') && normalizePathPattern(value) !== 'docs') || normalizePathPattern(value).startsWith('docs/.') || isSecretLikePathPattern(value))) add('PLAN_MODE_CONFIG_INVALID_WRITABLE_PATHS', 'planMode.writablePaths', 'Expected safe repository-relative paths under docs/ using exact paths or /** subtree patterns.');
+      else if (paths.some((value) => !isValidPathPattern(value) || typeof value !== 'string' || value.trim().startsWith('/') || (!normalizePathPattern(value).startsWith(`${normalizeDocumentationRoot(data.documentation?.root ?? DEFAULT_DOCUMENTATION_ROOT)}/`)) || normalizePathPattern(value).startsWith(`${normalizeDocumentationRoot(data.documentation?.root ?? DEFAULT_DOCUMENTATION_ROOT)}/.`) || isSecretLikePathPattern(value))) add('PLAN_MODE_CONFIG_INVALID_WRITABLE_PATHS', 'planMode.writablePaths', 'Expected safe repository-relative paths under documentation.root using exact paths or /** subtree patterns.');
     }
   }
   const referenceExpansion = data.referenceExpansion;
@@ -493,14 +513,16 @@ export function readMemoryConfig(root = '.') {
     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 documentationRoot = normalizeDocumentationRoot(data.documentation?.root ?? DEFAULT_DOCUMENTATION_ROOT);
+    const defaults = defaultMemoryConfig({ documentationRoot });
     const configuredAreas = data.memory?.areas?.map(normalizeMemoryArea) ?? [];
-    const traceability = data.traceability === undefined ? cloneTraceabilityPolicy() : normalizeTraceabilityPolicy(data.traceability);
+    const traceability = data.traceability === undefined ? defaults.traceability : normalizeTraceabilityPolicy(data.traceability);
     const validation = data.validation === undefined ? cloneValidationPolicy() : normalizeValidationPolicy(data.validation);
     const impactRanking = normalizeImpactRankingPolicy(data.impactRanking);
     const referenceExpansion = normalizeReferenceExpansionPolicy(data.referenceExpansion);
-    const load = normalizeLoadPolicy(data.load);
-    const planMode = normalizePlanModePolicy(data.planMode);
-    return configuredAreas.length > 0 ? { source: MEMORY_CONFIG_FILE, areas: configuredAreas, traceability, validation, impactRanking, referenceExpansion, load, planMode, errors: [] } : { ...defaultMemoryConfig(), traceability, validation, impactRanking, referenceExpansion, load, planMode, source: MEMORY_CONFIG_FILE, errors: [] };
+    const load = data.load === undefined ? defaults.load : normalizeLoadPolicy(data.load);
+    const planMode = data.planMode === undefined ? defaults.planMode : normalizePlanModePolicy(data.planMode);
+    return configuredAreas.length > 0 ? { source: MEMORY_CONFIG_FILE, documentation: { root: documentationRoot }, areas: configuredAreas, traceability, validation, impactRanking, referenceExpansion, load, planMode, errors: [] } : { ...defaults, traceability, validation, impactRanking, referenceExpansion, 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>\`.` }] };
   }
@@ -520,9 +542,10 @@ function serializableMemoryArea(area) {
   }, area);
 }
 
-export function defaultDotdotgodConfigData() {
-  const config = defaultMemoryConfig();
+export function defaultDotdotgodConfigData({ documentationRoot = DEFAULT_DOCUMENTATION_ROOT } = {}) {
+  const config = defaultMemoryConfig({ documentationRoot });
   return {
+    documentation: { ...config.documentation },
     memory: {
       areas: (config.areas ?? []).map(serializableMemoryArea),
     },
@@ -542,6 +565,7 @@ export function defaultDotdotgodConfigText() {
 export function memoryConfigSummary(config) {
   return {
     source: config.source ?? 'default',
+    documentation: { root: config.documentation?.root ?? DEFAULT_DOCUMENTATION_ROOT },
     areas: (config.areas ?? []).map((area) => withOptionalAreaMetadata({
       id: area.id,
       label: area.label,

package/src/memory/documentation-map.mjs

@@ -0,0 +1,111 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isSecretLikePathPattern, matchPathPattern, readMemoryConfig } from './config.mjs';
+
+const SKIPPED_DIRECTORIES = new Set(['node_modules', 'dist', 'build', 'coverage', '.git', '.dotdotgod']);
+
+function node() {
+  return { directories: new Map(), files: [] };
+}
+
+function buildTree(paths) {
+  const root = node();
+  for (const path of [...new Set(paths)].sort()) {
+    const parts = path.split('/');
+    let current = root;
+    for (const part of parts.slice(0, -1)) {
+      if (!current.directories.has(part)) current.directories.set(part, node());
+      current = current.directories.get(part);
+    }
+    current.files.push(parts.at(-1));
+  }
+  return root;
+}
+
+function descendantCounts(current) {
+  let directories = 0;
+  let files = current.files.length;
+  for (const child of current.directories.values()) {
+    directories += 1;
+    const nested = descendantCounts(child);
+    directories += nested.directories;
+    files += nested.files;
+  }
+  return { directories, files };
+}
+
+function plural(count, singular, pluralForm = `${singular}s`) {
+  return `${count} ${count === 1 ? singular : pluralForm}`;
+}
+
+export function formatDocumentationTree(paths, documentationRoot = 'docs', maxDepth = 5) {
+  const tree = buildTree(paths);
+  let docs = tree;
+  for (const part of documentationRoot.split('/')) {
+    docs = docs.directories.get(part);
+    if (!docs) return `- ${documentationRoot}/: missing`;
+  }
+  const lines = [`${documentationRoot}/`];
+  const render = (current, depth, indent) => {
+    for (const file of current.files.sort()) lines.push(`${indent}- ${file}`);
+    if (depth >= maxDepth && current.directories.size > 0) {
+      for (const [name, child] of [...current.directories.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        const counts = descendantCounts(child);
+        lines.push(`${indent}- ${name}/`);
+        lines.push(`${indent}  - … ${plural(counts.directories, 'directory', 'directories')}, ${plural(counts.files, 'Markdown file')}`);
+      }
+      return;
+    }
+    for (const [name, child] of [...current.directories.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      lines.push(`${indent}- ${name}/`);
+      render(child, depth + 1, `${indent}  `);
+    }
+  };
+  render(docs, 1, '  ');
+  return lines.join('\n');
+}
+
+function discoverMarkdown(root, documentationRoot, exclude) {
+  const paths = [];
+  const walk = (relativeDirectory) => {
+    let entries;
+    try {
+      entries = readdirSync(join(root, relativeDirectory), { withFileTypes: true, encoding: 'utf8' });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const path = `${relativeDirectory}/${entry.name}`.replaceAll('\\', '/');
+      if (entry.name.startsWith('.') || isSecretLikePathPattern(path) || exclude.some(pattern => matchPathPattern(path, pattern))) continue;
+      if (entry.isDirectory()) {
+        if (!SKIPPED_DIRECTORIES.has(entry.name)) walk(path);
+      } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) paths.push(path);
+    }
+  };
+  walk(documentationRoot);
+  return paths.sort();
+}
+
+export function buildDocumentationMap(projectRoot = '.', { depth = 5 } = {}) {
+  const root = resolve(projectRoot);
+  if (!existsSync(root)) return { ok: false, error: { code: 'ROOT_NOT_FOUND', message: `Project root not found: ${root}` } };
+  try {
+    if (!statSync(root).isDirectory()) return { ok: false, error: { code: 'ROOT_NOT_FOUND', message: `Project root not found: ${root}` } };
+  } catch {
+    return { ok: false, error: { code: 'ROOT_NOT_FOUND', message: `Project root not found: ${root}` } };
+  }
+  const config = readMemoryConfig(root);
+  const documentationRoot = config.documentation?.root ?? 'docs';
+  const exclude = [...(config.load?.documentationSummary?.exclude ?? [])].sort();
+  const paths = discoverMarkdown(root, documentationRoot, exclude);
+  return {
+    ok: true,
+    root,
+    documentationRoot,
+    depth,
+    exclude,
+    paths,
+    tree: formatDocumentationTree(paths, documentationRoot, depth),
+  };
+}

package/src/query/chunks.mjs

@@ -10,8 +10,8 @@ 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');
+export function collectDocumentationMarkdown(root, exclude = ['docs/plan', 'docs/archive'], documentationRoot = 'docs') {
+  const docsRoot = join(root, documentationRoot);
   const files = [];
   const walk = (directory) => {
     let entries;
@@ -84,8 +84,8 @@ export function chunkMarkdown(path, content, maxChars = MAX_CHUNK_CHARS) {
   return sections;
 }
 
-export function collectDocumentationChunks(root, exclude) {
-  return collectDocumentationMarkdown(root, exclude).flatMap((path) => {
+export function collectDocumentationChunks(root, exclude, documentationRoot = 'docs') {
+  return collectDocumentationMarkdown(root, exclude, documentationRoot).flatMap((path) => {
     const content = readFileSync(join(root, path), 'utf8');
     return chunkMarkdown(path, content);
   });

package/src/reference/extract.mjs

@@ -54,8 +54,12 @@ export function referencePathForNode(node) {
   return '';
 }
 
-export function isArchiveBodyPath(path = '') {
-  return path.startsWith('docs/archive/') && path !== 'docs/archive/README.md';
+export function isArchiveBodyPath(path = '', memoryConfig) {
+  const area = memoryConfig?.areas?.find((candidate) => candidate.id === 'archive-body' || candidate.role === 'historical-memory-body');
+  if (!area) return path.startsWith('docs/archive/') && path !== 'docs/archive/README.md';
+  const normalize = (value) => value.replace(/\/\*\*$/, '');
+  return (area.paths ?? []).some((pattern) => path === normalize(pattern) || path.startsWith(`${normalize(pattern)}/`))
+    && !(area.excludePaths ?? []).some((excluded) => path === excluded);
 }
 
 function aliasEntriesForPath(path = '') {
@@ -112,7 +116,7 @@ export function extractFuzzyReferences(prompt = '', index = null, options = {})
     for (const node of graph.nodes ?? []) {
       if (!['file', 'heading'].includes(node.type)) continue;
       const path = referencePathForNode(node);
-      if (options.includeArchive !== true && isArchiveBodyPath(path)) continue;
+      if (options.includeArchive !== true && isArchiveBodyPath(path, options.memoryConfig ?? index?.memoryConfig)) continue;
       for (const entry of referenceCandidateAliases(node)) {
         const alias = String(entry.alias ?? '').replace(/\.md$/i, '').replace(/[_-]+/g, ' ').trim();
         if (!fuzzyPhraseAllowed(alias, lowSignalTerms)) continue;

package/src/reference/resolve.mjs

@@ -16,6 +16,7 @@ function exactReferenceScore(ref, alias, kind) {
 export function resolveReferenceCandidates(index, ref, options = {}) {
   const graph = index?.graph ?? { nodes: [], edges: [] };
   const includeArchive = options.includeArchive === true;
+  const memoryConfig = options.memoryConfig ?? index?.memoryConfig;
   const limit = Number.isFinite(options.maxResults) ? options.maxResults : DEFAULT_REFERENCE_LIMIT;
   const query = String(ref ?? '').trim().replace(/^\[\[/, '').replace(/\]\]$/, '').split('|')[0].trim();
   const normalized = normalizeReferenceAlias(query);
@@ -23,7 +24,7 @@ export function resolveReferenceCandidates(index, ref, options = {}) {
   for (const node of graph.nodes ?? []) {
     if (!['file', 'heading'].includes(node.type)) continue;
     const path = referencePathForNode(node);
-    if (!includeArchive && isArchiveBodyPath(path)) continue;
+    if (!includeArchive && isArchiveBodyPath(path, memoryConfig)) continue;
     let best = null;
     for (const entry of referenceCandidateAliases(node)) {
       const aliasKey = normalizeReferenceAlias(entry.alias);
@@ -95,7 +96,7 @@ export function runResolve(argv) {
   const ref = options.rootArgv?.join(' ');
   if (!ref) usage('Missing required argument: <ref>.', 'resolve');
   const { status, index, metadata } = readFreshIndex(options.root);
-  const refs = [resolveReferenceCandidates(index, ref, options)];
+  const refs = [resolveReferenceCandidates(index, ref, { ...options, memoryConfig: readMemoryConfig(options.root) })];
   const payload = { ok: status.ok, command: 'resolve', root: options.root, status, metadata, refs, omitted: refs.reduce((sum, item) => sum + item.omitted, 0) };
   if (options.json) console.log(JSON.stringify(payload, null, 2));
   else console.log(formatReferenceOutput(payload));
@@ -110,8 +111,8 @@ export function runExpand(argv) {
   const { status, index, metadata } = readFreshIndex(options.root);
   const fuzzyRefs = options.fuzzy ? extractFuzzyReferences(prompt, index, { ...options, memoryConfig: readMemoryConfig(options.root), existingTargets: refsInPrompt.map((item) => item.target) }) : [];
   let refs = [
-    ...refsInPrompt.map((item) => ({ ...resolveReferenceCandidates(index, item.target, options), source: 'explicit', raw: item.raw, label: item.label })),
-    ...fuzzyRefs.map((item) => ({ ...resolveReferenceCandidates(index, item.target, options), source: 'fuzzy', raw: item.raw, confidence: item.confidence, reasons: item.reasons })),
+    ...refsInPrompt.map((item) => ({ ...resolveReferenceCandidates(index, item.target, { ...options, memoryConfig: readMemoryConfig(options.root) }), source: 'explicit', raw: item.raw, label: item.label })),
+    ...fuzzyRefs.map((item) => ({ ...resolveReferenceCandidates(index, item.target, { ...options, memoryConfig: readMemoryConfig(options.root) }), source: 'fuzzy', raw: item.raw, confidence: item.confidence, reasons: item.reasons })),
   ];
   if (options.withImpact) refs = refs.map((item) => {
     const topPath = item.top?.path;

package/src/validate/run.mjs

@@ -24,7 +24,9 @@ export function runValidate(argv) {
   }
 
   const root = resolve(options.root);
-  const docs = join(root, 'docs');
+  const memoryConfig = readMemoryConfig(root);
+  const documentationRoot = memoryConfig.documentation?.root ?? 'docs';
+  const docs = join(root, documentationRoot);
   const errors = [];
   const warnings = [];
   const markdownFiles = [];
@@ -37,7 +39,7 @@ export function runValidate(argv) {
     if (path.includes('/node_modules') || path === 'node_modules') return true;
     if (path.includes('/.git') || path === '.git') return true;
     if (path === CACHE_DIR || path.startsWith(`${CACHE_DIR}/`)) return true;
-    if (!options.includeLocalMemory && (path === 'docs/plan' || path.startsWith('docs/plan/') || path === 'docs/archive' || path.startsWith('docs/archive/'))) return true;
+    if (!options.includeLocalMemory && (resolveMemoryArea(path, memoryConfig)?.scope === 'local')) return true;
     return false;
   };
   const walk = (dir) => {
@@ -55,7 +57,6 @@ export function runValidate(argv) {
   };
 
   if (!existsSync(docs)) usage(`docs directory not found: ${docs}`);
-  const memoryConfig = readMemoryConfig(root);
   const validationPolicy = cloneValidationPolicy(memoryConfig.validation ?? DEFAULT_VALIDATION_POLICY);
   const maxLines = options.maxLines ?? validationPolicy.markdown.maxLines;
   const maxChars = options.maxChars ?? validationPolicy.markdown.maxChars;
@@ -78,10 +79,10 @@ export function runValidate(argv) {
     (memoryConfig.areas ?? [])
       .filter(area => area.scope === 'shared')
       .flatMap(area => area.paths ?? [])
-      .map(p => { const m = p.match(/^docs\/([^/*]+)\/\*\*$/); return m ? m[1] : null; })
+      .map(p => { const prefix = `${documentationRoot}/`; return p.startsWith(prefix) && p.endsWith('/**') ? p.slice(prefix.length, -3) : null; })
       .filter(Boolean)
   );
-  const filenameQualityScope = [...FILENAME_QUALITY_AREAS].sort().map(area => `docs/${area}`).join(', ') || 'configured shared documentation areas';
+  const filenameQualityScope = [...FILENAME_QUALITY_AREAS].sort().map(area => `${documentationRoot}/${area}`).join(', ') || 'configured shared documentation areas';
   const FILENAME_QUALITY_PROMPT =
     'Filenames and paths are LLM/agent context signals used for impact ranking, search, and retrieval.\n' +
     `Use meaning-based filenames in ${filenameQualityScope}. A filename should identify its primary endpoint, screen, policy, state, response type, or domain subject. ` +
@@ -191,15 +192,15 @@ export function runValidate(argv) {
         if (!entry.isDirectory()) continue;
         if (!isKebabCase(entry.name)) addError(join(areaRoot, entry.name), 'SLUG_NAMING', `Archive/plan/report slug must be kebab-case: ${entry.name}`, null, 'rename the task/report directory to kebab-case and update any README index links that reference it.');
         const readme = join(areaRoot, entry.name, 'README.md');
-        if (!existsSync(readme)) addError(readme, 'MISSING_README', `Expected README.md in docs/${area}/${entry.name}/`, null, 'add a README.md that summarizes the task/report and links any supporting files.');
+        if (!existsSync(readme)) addError(readme, 'MISSING_README', `Expected README.md in ${documentationRoot}/${area}/${entry.name}/`, null, 'add a README.md that summarizes the task/report and links any supporting files.');
       }
     }
   }
   const gitignore = join(root, '.gitignore');
-  if (!existsSync(gitignore)) addError(gitignore, 'MISSING_GITIGNORE', 'Expected .gitignore', null, 'create .gitignore and include docs/plan, docs/archive, and .dotdotgod entries.');
+  if (!existsSync(gitignore)) addError(gitignore, 'MISSING_GITIGNORE', 'Expected .gitignore', null, `create .gitignore and include ${documentationRoot}/plan, ${documentationRoot}/archive, and .dotdotgod entries.`);
   else {
     const content = readFileSync(gitignore, 'utf8').split('\n').map((line) => line.trim());
-    for (const required of ['docs/plan', 'docs/archive', CACHE_DIR]) if (!content.includes(required)) addError(gitignore, 'MISSING_GITIGNORE_ENTRY', `Expected .gitignore entry: ${required}`, null, `add ${required} to .gitignore so local plans, archives, and cache files stay untracked.`);
+    for (const required of [`${documentationRoot}/plan`, `${documentationRoot}/archive`, CACHE_DIR]) if (!content.includes(required)) addError(gitignore, 'MISSING_GITIGNORE_ENTRY', `Expected .gitignore entry: ${required}`, null, `add ${required} to .gitignore so local plans, archives, and cache files stay untracked.`);
   }
   if (options.json) console.log(JSON.stringify({ ok: errors.length === 0, errors, warnings }, null, 2));
   else {