@geraldmaron/construct 1.5.0 → 1.5.2

package/lib/document-ingest.mjs

@@ -15,6 +15,7 @@ import { purgeExpiredData } from './storage/admin.mjs';
 import { stampFrontmatter } from './doc-stamp.mjs';
 import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS } from './knowledge/layout.mjs';
 import { loadProjectConfig } from './config/project-config.mjs';
+import { resolveEffectiveSourceTargetsFromConfig } from './config/source-targets.mjs';
 import { resolveIngestStrategy, INGEST_STRATEGIES, INGEST_ORCHESTRATION_STRATEGIES } from './ingest/strategy.mjs';
 import { extractViaProvider } from './ingest/provider-extract.mjs';
 import { extractViaDoclingRemote } from './ingest/docling-remote.mjs';
@@ -261,6 +262,7 @@ export async function ingestDocuments(inputPaths, {
   outputPath = null,
   outputDir = null,
   target = 'knowledge/internal',
+  as = null,
   sync = false,
   strict = false,
   highFidelity = true,
@@ -281,6 +283,23 @@ export async function ingestDocuments(inputPaths, {
   }
 
   const { config } = loadProjectConfig(cwd, env);
+
+  // `--as=<targetId>` binds ingested knowledge to a registered source target so
+  // the written files carry re-verifiable provenance (origin_target_id /
+  // origin_provider in the stamp) rather than landing unattributed. An unknown
+  // id is a hard error — silently dropping the binding would defeat the point.
+  let originFields = null;
+  if (as) {
+    const targets = resolveEffectiveSourceTargetsFromConfig(config, env);
+    const bound = targets.find((t) => t.id === as);
+    if (!bound) {
+      const known = targets.map((t) => t.id).join(', ') || '(none registered)';
+      const err = new Error(`ingest --as: unknown source target "${as}". Known targets: ${known}`);
+      err.code = 'INGEST_UNKNOWN_TARGET';
+      throw err;
+    }
+    originFields = { origin_target_id: bound.id, origin_provider: bound.provider };
+  }
   const resolvedStrategy = resolveIngestStrategy({ config, env, override: strategy, orchestrationOverride: orchestration, cwd });
 
   const results = [];
@@ -318,7 +337,7 @@ export async function ingestDocuments(inputPaths, {
       cwd,
       metadata,
     });
-    writeFileSync(finalPath, stampFrontmatter(markdown, { generator: 'construct/ingest' }));
+    writeFileSync(finalPath, stampFrontmatter(markdown, { generator: 'construct/ingest', extraFields: originFields }));
     results.push({
       sourcePath,
       outputPath: finalPath,
@@ -390,6 +409,7 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
   let outputPath = null;
   let outputDir = null;
   let target = 'knowledge/internal';
+  let as = null;
   let sync = false;
   let strict = false;
   let fidelity = 'high';
@@ -400,6 +420,7 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
     if (arg.startsWith('--out=')) outputPath = arg.split('=').slice(1).join('=');
     else if (arg.startsWith('--out-dir=')) outputDir = arg.split('=').slice(1).join('=');
     else if (arg.startsWith('--target=')) target = arg.split('=').slice(1).join('=');
+    else if (arg.startsWith('--as=')) as = arg.split('=').slice(1).join('=');
     else if (arg.startsWith('--strategy=')) strategy = arg.split('=').slice(1).join('=');
     else if (arg === '--strategy') strategy = '';
     else if (arg.startsWith('--orchestration=')) orchestration = arg.split('=').slice(1).join('=');
@@ -421,7 +442,8 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
   if (inputs.length === 0) {
     throw new Error(
       `Usage: construct ingest <file-or-dir> [more paths] [--out=FILE] [--out-dir=DIR] ` +
-      `[--target=sibling|knowledge/<subdir>] [--strategy=adapter|provider] [--orchestration=prompt-only|orchestrated] [--sync] [--strict] [--fidelity=fast|high]\n` +
+      `[--target=sibling|knowledge/<subdir>] [--as=<targetId>] [--strategy=adapter|provider] [--orchestration=prompt-only|orchestrated] [--sync] [--strict] [--fidelity=fast|high]\n` +
+      `  --as: bind ingested knowledge to a registered source target; stamps origin provenance\n` +
       `  --strategy: extraction strategy override (adapter = local extractors; provider = configured provider/model)\n` +
       `  --orchestration: prompt-only (deterministic extraction) or orchestrated (engage the specialist chain)\n` +
       `  --strict: exit non-zero if any extraction drops occur\n` +
@@ -443,5 +465,5 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
     );
   }
 
-  return ingestDocuments(inputs, { cwd, outputPath, outputDir, target, sync, strict, highFidelity, strategy: strategy || null, orchestration: orchestration || null, env });
+  return ingestDocuments(inputs, { cwd, outputPath, outputDir, target, as: as || null, sync, strict, highFidelity, strategy: strategy || null, orchestration: orchestration || null, env });
 }

package/lib/embed/demand-fetch.mjs

@@ -28,7 +28,7 @@ import {
   resolveEffectiveSourceTargetsFromConfig,
   resolveKnownSourcesFromTargets,
 } from '../config/source-targets.mjs';
-import { getSourceTargetDescriptor, renderTemplate } from '../config/source-target-registry.mjs';
+import { getSourceTargetDescriptor, listSourceTargetDescriptors, renderTemplate } from '../config/source-target-registry.mjs';
 
 // ─── Self-query detection ────────────────────────────────────────────────────
 
@@ -79,41 +79,22 @@ export function resolveKnownSources(env = process.env, cwd = process.cwd()) {
     return resolveKnownSourcesFromTargets(targets);
   }
 
+  // No configured or legacy-env targets resolved — which means every list-valued
+  // legacy var (GITHUB_REPOS, JIRA_PROJECTS, LINEAR_TEAMS, SLACK_CHANNELS) was
+  // empty, so the descriptor path above already covered those. What remains is a
+  // credential-only source: a provider reachable via a bare credential env
+  // (JIRA_BASE_URL, LINEAR_API_KEY) with no explicit list. Each such provider
+  // declares that gate as aliases.catchAllCredentialEnv on its manifest, so this
+  // stays descriptor-driven — no provider name, env var, or display prefix is
+  // hardcoded here, and a provider whose descriptor omits the gate (slack) is
+  // deliberately not advertised without an explicit channel.
   const sources = [];
-
-  // GitHub repos
-  const repos = (env.GITHUB_REPOS ?? '').split(',').map(r => r.trim()).filter(Boolean);
-  for (const repo of repos) {
-    const short = repo.split('/').pop(); // "project-iverson" from "hashicorp/project-iverson"
-    sources.push({ id: repo.toLowerCase(), provider: 'github', ref: repo, display: repo });
-    sources.push({ id: short.toLowerCase(), provider: 'github', ref: repo, display: repo });
-    // Normalised: "projectiverson", "iverson"
-    sources.push({ id: short.replace(/-/g, '').toLowerCase(), provider: 'github', ref: repo, display: repo });
-    // Last word: "iverson" from "project-iverson"
-    const words = short.split('-');
-    if (words.length > 1) {
-      sources.push({ id: words[words.length - 1].toLowerCase(), provider: 'github', ref: repo, display: repo });
-    }
-  }
-
-  // Jira projects
-  const jiraUrl = (env.JIRA_BASE_URL ?? '').trim();
-  if (jiraUrl) {
-    // JIRA_PROJECTS=PLAT,INF,ENG — optional explicit list
-    const projects = (env.JIRA_PROJECTS ?? '').split(',').map(p => p.trim()).filter(Boolean);
-    for (const proj of projects) {
-      sources.push({ id: proj.toLowerCase(), provider: 'jira', ref: proj, display: `Jira/${proj}` });
-    }
-    // Always add a generic "jira" entry
-    sources.push({ id: 'jira', provider: 'jira', ref: null, display: 'Jira' });
-  }
-
-  // Linear
-  if (env.LINEAR_API_KEY) {
-    sources.push({ id: 'linear', provider: 'linear', ref: null, display: 'Linear' });
-    const teams = (env.LINEAR_TEAMS ?? '').split(',').map(t => t.trim()).filter(Boolean);
-    for (const team of teams) {
-      sources.push({ id: team.toLowerCase(), provider: 'linear', ref: team, display: `Linear/${team}` });
+  for (const descriptor of listSourceTargetDescriptors()) {
+    const gate = descriptor.aliases?.catchAllCredentialEnv;
+    if (!descriptor.aliases?.catchAll || !Array.isArray(gate)) continue;
+    const credentialed = gate.some((name) => String(env[name] ?? '').trim());
+    if (credentialed) {
+      sources.push({ id: descriptor.provider, provider: descriptor.provider, ref: null, display: descriptor.aliases.displayPrefix });
     }
   }
 
@@ -413,9 +394,21 @@ async function demandFetchAll({ query, rootDir, env, cwd } = {}) {
   const targets = resolveEffectiveSourceTargetsFromConfig(config, env);
   const scoped = targets.length > 0;
 
+  // The unscoped fallback ("pull everything fresh") only drives providers that
+  // can be discovered from env/poll config — those whose descriptor declares an
+  // `embed` or `legacyEnv` block. A target-only provider (directory) has no
+  // env-derived default source, so it is excluded here rather than fetched with
+  // an empty selector; it participates through the scoped path once a target is
+  // configured. Dispatch is on the descriptor, never a provider name.
+
+  const envFetchable = new Set(
+    listSourceTargetDescriptors()
+      .filter((d) => d.embed || d.legacyEnv)
+      .map((d) => d.provider),
+  );
   const providerNames = scoped
     ? [...new Set(targets.map((t) => t.provider))].filter((name) => registry.get(name))
-    : registry.names();
+    : [...envFetchable].filter((name) => registry.get(name));
 
   if (!providerNames.length) {
     return {
@@ -579,6 +572,7 @@ function buildReadCalls(match, env, cwd = process.cwd()) {
   }
 
   if (df.queryOptsKind === 'scalar') {
+    if (match.ref == null && !df.queryOptsNullable) return [];
     const value = df.queryOptsNullable ? (match.ref ?? null) : match.ref;
     return [{ ref: df.queryRefs[0], opts: { [df.queryOptsField]: value, limit: df.queryDefaultLimit }, display: match.display }];
   }

package/lib/embed/providers/directory.mjs

@@ -0,0 +1,117 @@
+/**
+ * lib/embed/providers/directory.mjs — local directory provider for embed mode.
+ *
+ * Reads markdown/doc files from a registered local directory target so a
+ * checked-out repository or docs folder can act as a context source. Purely
+ * local: it walks the filesystem and never opens a socket, satisfying the
+ * directory-targets-never-touch-the-network invariant (bead construct-760c.1
+ * R6). Requires no credentials, so ProviderRegistry always registers it.
+ *
+ * Supported refs:
+ *   docs     Doc/markdown files under the path (bounded depth, doc extensions)
+ *   readme   The top-level README, when present
+ *   meta     A one-line summary of the directory (path + doc file count)
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, extname, join, relative } from 'node:path';
+
+import { expandTilde } from '../../config/source-targets.mjs';
+
+const DOC_EXTS = new Set(['.md', '.mdx', '.markdown', '.txt', '.rst', '.adoc']);
+
+// Directories that are noise for a docs corpus: version-control internals,
+// dependency trees, and build output dwarf the actual documentation.
+const SKIP_DIRS = new Set(['.git', 'node_modules', '.construct', '.cx', 'dist', 'build', 'coverage', '.next', 'vendor']);
+
+const DOC_CONTENT_LIMIT = 8_000;
+const MAX_DEPTH = 10;
+
+function isReadme(name) {
+  return /^readme(\.\w+)?$/i.test(name);
+}
+
+function collectDocFiles(rootDir) {
+  const files = [];
+  const stack = [{ dir: rootDir, depth: 0 }];
+  while (stack.length > 0) {
+    const { dir, depth } = stack.pop();
+    if (depth >= MAX_DEPTH) continue;
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') && entry.isDirectory()) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        stack.push({ dir: full, depth: depth + 1 });
+        continue;
+      }
+      if (entry.isFile() && DOC_EXTS.has(extname(entry.name).toLowerCase())) files.push(full);
+    }
+  }
+  return files.sort((a, b) => a.localeCompare(b));
+}
+
+function readDoc(rootDir, filePath) {
+  const rel = relative(rootDir, filePath);
+  let content = '';
+  try { content = readFileSync(filePath, 'utf8').slice(0, DOC_CONTENT_LIMIT); } catch { return null; }
+  return {
+    type: 'doc',
+    source: 'directory',
+    path: rel,
+    content,
+    summary: `Doc ${rel}`,
+  };
+}
+
+export class DirectoryProvider {
+  /**
+   * @param {string} ref   - 'docs' | 'readme' | 'meta'
+   * @param {object} opts  - { path, limit }
+   * @returns {Promise<Item[]>}
+   */
+  async read(ref, opts = {}) {
+    const rawPath = opts.path ?? opts.dir;
+    if (!rawPath) throw new Error('Directory source requires a "path" field');
+    const rootDir = expandTilde(String(rawPath));
+
+    let stat;
+    try { stat = statSync(rootDir); } catch {
+      return [{ type: 'error', source: 'directory', path: rootDir, ref, message: `path not found: ${rootDir}` }];
+    }
+    if (!stat.isDirectory()) {
+      return [{ type: 'error', source: 'directory', path: rootDir, ref, message: `not a directory: ${rootDir}` }];
+    }
+
+    const limit = Number(opts.limit ?? 100);
+
+    if (ref === 'meta') {
+      const count = collectDocFiles(rootDir).length;
+      return [{
+        type: 'meta',
+        source: 'directory',
+        path: rootDir,
+        description: `Local directory ${basename(rootDir)} (${count} doc file(s))`,
+        summary: `Directory ${rootDir}: ${count} doc file(s)`,
+      }];
+    }
+
+    const files = collectDocFiles(rootDir);
+
+    if (ref === 'readme') {
+      const readme = files.find((f) => isReadme(basename(f)));
+      if (!readme) return [];
+      const rec = readDoc(rootDir, readme);
+      return rec ? [rec] : [];
+    }
+
+    const records = [];
+    for (const file of files.slice(0, limit)) {
+      const rec = readDoc(rootDir, file);
+      if (rec) records.push(rec);
+    }
+    return records;
+  }
+}

package/lib/embed/providers/registry.mjs

@@ -37,8 +37,15 @@ import { loadManifestsFromDir, mergeManifests, resolveManifestDirs } from '../..
  * `credentials` is one of:
  *   { anyOf: [...] }  — usable if at least one listed env var is set (GitHub)
  *   { allOf: [...] }  — usable only if every listed env var is set (Jira)
+ *   null              — no credentials required, always usable (directory)
  */
 const ADAPTERS = {
+  directory: {
+    aliases: ['directory', 'dir'],
+    credentials: null,
+    load: () => import('./directory.mjs'),
+    build: (mod) => new mod.DirectoryProvider(),
+  },
   github: {
     aliases: ['github', 'gh'],
     credentials: { anyOf: ['GITHUB_TOKEN', 'GITHUB_PERSONAL_ACCESS_TOKEN', 'GH_TOKEN'] },

package/lib/extensions/manifests/atlassian-jira.manifest.json

@@ -20,7 +20,7 @@
     },
     "signature": { "template": "jira:project:{value}", "valueMode": "upperOrEmpty" },
     "legacyEnv": { "vars": ["JIRA_PROJECTS"], "parse": "csv", "valueTransform": "upper" },
-    "aliases": { "strategy": "simple", "displayPrefix": "Jira", "catchAll": true },
+    "aliases": { "strategy": "simple", "displayPrefix": "Jira", "catchAll": true, "catchAllCredentialEnv": ["JIRA_BASE_URL"] },
     "embed": {
       "mode": "perTarget",
       "valueField": "project",

package/lib/extensions/manifests/directory.manifest.json

@@ -8,5 +8,28 @@
   "securityClassification": "trusted",
   "owner": "construct-core",
   "compatVersion": 1,
-  "installSource": "builtin"
+  "installSource": "builtin",
+  "sourceTarget": {
+    "provider": "directory",
+    "selector": {
+      "field": "path",
+      "hint": "required existing directory path (tilde-expanded)",
+      "normalize": "trim",
+      "expand": "tilde",
+      "existsAs": "directory",
+      "existsHint": "path must exist and be a directory"
+    },
+    "signature": { "template": "directory:path:{value}", "valueMode": "path" },
+    "aliases": { "strategy": "path", "displayPrefix": null, "catchAll": false },
+    "demandFetch": {
+      "targetRefs": ["docs"],
+      "targetOptsField": "path",
+      "targetOptsKind": "scalar",
+      "targetDefaultLimit": 100,
+      "queryRefs": ["docs"],
+      "queryOptsField": "path",
+      "queryOptsKind": "scalar",
+      "queryDefaultLimit": 100
+    }
+  }
 }

package/lib/extensions/manifests/github.manifest.json

@@ -19,6 +19,16 @@
       "normalize": "trim"
     },
     "signature": { "template": "github:repo:{value}", "valueMode": "optionalLower" },
+    "content": {
+      "field": "content",
+      "modeField": "mode",
+      "modeValue": "corpus",
+      "refField": "ref",
+      "defaultRef": "main",
+      "remoteField": "remote",
+      "remoteTemplate": "https://github.com/{value}.git",
+      "clone": "git"
+    },
     "legacyEnv": { "vars": ["GITHUB_REPOS", "GITHUB_REPO"], "parse": "csv" },
     "aliases": { "strategy": "repoWords", "displayPrefix": null, "catchAll": false },
     "embed": {

package/lib/extensions/manifests/linear.manifest.json

@@ -20,7 +20,7 @@
     },
     "signature": { "template": "linear:team:{value}", "valueMode": "lowerOrEmpty" },
     "legacyEnv": { "vars": ["LINEAR_TEAMS"], "parse": "csv" },
-    "aliases": { "strategy": "simple", "displayPrefix": "Linear", "catchAll": true },
+    "aliases": { "strategy": "simple", "displayPrefix": "Linear", "catchAll": true, "catchAllCredentialEnv": ["LINEAR_API_KEY"] },
     "embed": {
       "mode": "perTarget",
       "valueField": "team",

package/lib/hooks/session-start.mjs

@@ -269,19 +269,26 @@ let embedStatusNote = '';
 try {
   const { loadProjectConfig } = await import('../config/project-config.mjs');
   const { resolveEffectiveSourceTargetsFromConfig } = await import('../config/source-targets.mjs');
+  const { listSourceTargetDescriptors } = await import('../config/source-target-registry.mjs');
   const { config } = loadProjectConfig(process.cwd(), process.env);
   const targets = resolveEffectiveSourceTargetsFromConfig(config, process.env);
-  const repos = targets.filter((t) => t.provider === 'github').map((t) => t.selector.repo);
-  const jiraTargets = targets.filter((t) => t.provider === 'jira');
-  const linearTargets = targets.filter((t) => t.provider === 'linear');
-  const slackTargets = targets.filter((t) => t.provider === 'slack');
-  const hasSources = targets.length > 0;
-  if (hasSources) {
-    const parts = [];
-    if (repos.length > 0) parts.push(`GitHub repos: ${repos.join(', ')}`);
-    if (jiraTargets.length > 0) parts.push(`Jira projects: ${jiraTargets.map((t) => t.selector.project).join(', ')}`);
-    if (linearTargets.length > 0) parts.push(`Linear teams: ${linearTargets.map((t) => t.selector.team).join(', ')}`);
-    if (slackTargets.length > 0) parts.push(`Slack channels: ${slackTargets.map((t) => t.selector.channel).join(', ')}`);
+
+  // Iterate the manifest-declared descriptors instead of naming providers here,
+  // so a newly manifest-registered provider_fetch source appears in the hint
+  // automatically rather than being silently dropped (construct-j745). Gate on
+  // `embed`: the network provider_fetch targets declare it, while a content-only
+  // `directory` target does not — and `provider_fetch` does not apply to it.
+
+  const parts = [];
+  for (const d of listSourceTargetDescriptors()) {
+    const field = d.embed ? d.selector?.field : null;
+    if (!field) continue;
+    const values = targets.filter((t) => t.provider === d.provider).map((t) => t.selector?.[field]).filter(Boolean);
+    if (values.length === 0) continue;
+    const label = d.aliases?.displayPrefix || (d.provider.charAt(0).toUpperCase() + d.provider.slice(1));
+    parts.push(`${label} ${field}s: ${values.join(', ')}`);
+  }
+  if (parts.length > 0) {
     sourcesNote = '\nProvider sources wired: ' + parts.join(' · ') +
       '. Use `provider_fetch` for any question about them.\n';
   }

package/lib/init-unified.mjs

@@ -1234,15 +1234,10 @@ async function main() {
     try {
       const { startServices } = await import('./service-manager.mjs');
       const { homedir } = await import('node:os');
-      const { detectDockerCompose } = await import('./setup.mjs');
-      
-      const homeDir = homedir();
-      const composeRunner = detectDockerCompose();
-      
+
       const { results } = await startServices({
         rootDir: target,
-        homeDir,
-        detectDockerComposeFn: () => composeRunner,
+        homeDir: homedir(),
       });
       
       if (!quiet) {

package/lib/knowledge/rag.mjs

@@ -68,27 +68,47 @@ function loadObservationChunks(rootDir) {
   }
 }
 
+// The host project is the reserved origin: no target id, a `self` project key.
+// Registered content targets carry their own origin (targetId, provider,
+// projectKey, ref); the corpus builder stamps per-file `relPath` onto both.
+
+const SELF_ORIGIN = Object.freeze({ targetId: null, provider: 'self', projectKey: 'self', ref: null });
+
+function withOrigin(chunk, origin, relPath) {
+  return { ...chunk, origin: { ...origin, relPath: relPath ?? chunk.origin?.relPath ?? null } };
+}
+
 /**
- * Load markdown files from a directory tree as indexable chunks.
+ * Load markdown files from a directory tree as indexable chunks. `origin`, when
+ * given, tags every chunk with its source project and per-file relative path so
+ * cross-project retrieval can attribute and filter the result; `baseDir`
+ * anchors the relative path (defaults to `dir`).
  */
-function loadMarkdownChunks(dir, source) {
+function loadMarkdownChunks(dir, source, { origin = null, baseDir = dir } = {}) {
   if (!fs.existsSync(dir)) return [];
   const chunks = [];
   const walk = (d) => {
     for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
       const full = path.join(d, entry.name);
-      if (entry.isDirectory()) { walk(full); continue; }
+      if (entry.isDirectory()) {
+        if (entry.name === '.git' || entry.name === 'node_modules') continue;
+        walk(full);
+        continue;
+      }
       if (!entry.name.endsWith('.md')) continue;
       try {
         const content = fs.readFileSync(full, 'utf8');
         const titleMatch = content.match(/^#\s+(.+)/m);
+        const relPath = path.relative(baseDir, full);
+        const idScope = origin?.targetId ? `${origin.targetId}:` : '';
         chunks.push({
-          id: `${source}:${path.relative(process.cwd(), full)}`,
+          id: `${source}:${idScope}${path.relative(process.cwd(), full)}`,
           source,
           title: titleMatch ? titleMatch[1].trim() : entry.name,
           body: content,
           filePath: full,
           createdAt: fs.statSync(full).mtime.toISOString(),
+          ...(origin ? { origin: { ...origin, relPath } } : {}),
         });
       } catch { /* skip unreadable */ }
     }
@@ -174,15 +194,33 @@ function loadKnowledgeChunks(rootDir) {
 
 /**
  * Build a full in-memory corpus from all sources.
- * Each chunk gets an embedding vector for cosine scoring.
+ * Each chunk gets an embedding vector for cosine scoring and an `origin` tag.
+ *
+ * The single-`rootDir` signature is preserved for existing callers: passing a
+ * string (or nothing) indexes only the host project, whose chunks carry the
+ * reserved self origin. Passing `roots` — content-capable target roots resolved
+ * via lib/sources/content-roots.mjs — folds each registered project's markdown
+ * into the same corpus, every chunk attributed to its source project so
+ * retrieval can cite and filter across projects (bead construct-760c.2).
+ *
+ * @param {string} [rootDir]
+ * @param {object} [opts]
+ * @param {{dir: string, origin: object}[]} [opts.roots] — extra content roots
  */
-export function buildCorpus(rootDir = process.cwd()) {
-  const chunks = [
+export function buildCorpus(rootDir = process.cwd(), { roots = [] } = {}) {
+  const hostChunks = [
     ...loadObservationChunks(rootDir),
     ...loadArtifactChunks(rootDir),
     ...loadSnapshotChunks(rootDir),
     ...loadKnowledgeChunks(rootDir),
-  ];
+  ].map((chunk) => withOrigin(chunk, SELF_ORIGIN, chunk.filePath ? path.relative(rootDir, chunk.filePath) : null));
+
+  const rootChunks = [];
+  for (const { dir, origin } of roots) {
+    rootChunks.push(...loadMarkdownChunks(dir, 'target', { origin, baseDir: dir }));
+  }
+
+  const chunks = [...hostChunks, ...rootChunks];
 
   // Embed each chunk
   return chunks.map((chunk) => ({
@@ -261,8 +299,11 @@ export function assembleContext(chunks) {
 
   for (const chunk of chunks) {
     const preview = chunk.body?.slice(0, CHUNK_PREVIEW) || '';
+    const projectKey = chunk.origin?.projectKey;
     const meta = [
       chunk.source && `source:${chunk.source}`,
+      projectKey && projectKey !== 'self' && `project:${projectKey}`,
+      chunk.origin?.relPath && `path:${chunk.origin.relPath}`,
       chunk.role && `role:${chunk.role}`,
       chunk.category && `category:${chunk.category}`,
       chunk.createdAt && `date:${chunk.createdAt.slice(0, 10)}`,
@@ -302,7 +343,7 @@ export async function ask(question, { rootDir = process.cwd(), corpus, dryRun =
   if (dryRun) {
     return {
       answer: null,
-      sources: chunks.map((c) => ({ id: c.id, source: c.source, title: c.title, score: c.score })),
+      sources: chunks.map((c) => ({ id: c.id, source: c.source, title: c.title, score: c.score, origin: c.origin ?? null })),
       query: question,
     };
   }
@@ -333,7 +374,7 @@ export async function ask(question, { rootDir = process.cwd(), corpus, dryRun =
       .join('\n\n');
     return {
       answer: `[Claude CLI unavailable — showing retrieved context]\n\n${fallback}`,
-      sources: chunks.map((c) => ({ id: c.id, source: c.source, title: c.title, score: c.score })),
+      sources: chunks.map((c) => ({ id: c.id, source: c.source, title: c.title, score: c.score, origin: c.origin ?? null })),
       query: question,
       cliMissing: true,
     };
@@ -341,7 +382,7 @@ export async function ask(question, { rootDir = process.cwd(), corpus, dryRun =
 
   return {
     answer: (result.stdout || '').trim(),
-    sources: chunks.map((c) => ({ id: c.id, source: c.source, title: c.title, score: c.score })),
+    sources: chunks.map((c) => ({ id: c.id, source: c.source, title: c.title, score: c.score, origin: c.origin ?? null })),
     query: question,
   };
 }