@geraldmaron/construct 1.5.1 → 1.5.3

package/lib/doctor/index.mjs

@@ -29,11 +29,12 @@ import * as graphStaleness from './watchers/graph-staleness.mjs';
 import * as providerBreaker from './watchers/provider-breaker.mjs';
 import * as oracleLiveness from './watchers/oracle-liveness.mjs';
 import * as orchestrationRuns from './watchers/orchestration-runs.mjs';
+import * as sourceTargets from './watchers/source-targets.mjs';
 import { stateDir } from '../config/xdg.mjs';
 import { isMainModule } from '../roots.mjs';
 
 const STATE_PATH = join(stateDir(), 'doctor.json');
-const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs, consistency, mcpProtocol, cxBudget, graphStaleness, providerBreaker, oracleLiveness, orchestrationRuns];
+const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs, consistency, mcpProtocol, cxBudget, graphStaleness, providerBreaker, oracleLiveness, orchestrationRuns, sourceTargets];
 
 let running = false;
 let timers = [];

package/lib/doctor/source-target-health.mjs

@@ -0,0 +1,101 @@
+/**
+ * lib/doctor/source-target-health.mjs — health of registered source targets
+ * (bead construct-760c.8, epic closer for multi-project context targets).
+ *
+ * Filesystem- and env-only: it resolves the project's `sources.targets[]` and
+ * reports three classes of problem without ever opening a socket, so the default
+ * `construct doctor` keeps its zero-outbound-fetch invariant (deep connectivity
+ * probes stay behind `--probe-providers`):
+ *   - a directory target whose path does not resolve,
+ *   - a corpus target whose local cache is missing or older than its TTL
+ *     (actionable: `construct sources sync <id>`),
+ *   - a network-backed target whose credential env var is not present (a
+ *     presence check only, surfaced as a soft notice).
+ *
+ * With no targets configured it returns an empty finding set — the caller emits
+ * nothing, so a project that never registered a target sees no source-target
+ * noise (R2).
+ */
+
+import { statSync } from 'node:fs';
+
+import { loadProjectConfig } from '../config/project-config.mjs';
+import { getSourceTargetDescriptor } from '../config/source-target-registry.mjs';
+import { expandTilde, resolveEffectiveSourceTargetsFromConfig } from '../config/source-targets.mjs';
+import { isCorpusTarget, corpusFreshness, DEFAULT_CORPUS_TTL_MS } from '../sources/repo-cache.mjs';
+
+// Credential env var per network-backed provider — presence-only, never read for
+// its value. Directory targets need none and are absent from the map.
+const CREDENTIAL_ENV = {
+  github: 'GITHUB_TOKEN',
+  jira: 'JIRA_API_TOKEN',
+  confluence: 'CONFLUENCE_API_TOKEN',
+  slack: 'SLACK_BOT_TOKEN',
+  linear: 'LINEAR_API_KEY',
+};
+
+function directoryFinding(target) {
+  const descriptor = getSourceTargetDescriptor(target.provider);
+  const raw = target.selector?.[descriptor.selector.field];
+  const dir = expandTilde(String(raw ?? ''));
+  let ok = false;
+  try { ok = statSync(dir).isDirectory(); } catch { ok = false; }
+  return ok
+    ? { label: `Source target ${target.id} (directory) path resolves`, ok: true }
+    : { label: `Source target ${target.id} (directory) path missing: ${dir} — fix the path or run \`construct sources remove ${target.id}\``, ok: false };
+}
+
+function corpusFinding(target, { cwd, ttlMs, now }) {
+  const f = corpusFreshness(target, { projectRoot: cwd, ttlMs, now });
+  if (!f.cached) {
+    return { label: `Source target ${target.id} (corpus) not yet cached — run \`construct sources sync ${target.id}\``, ok: false, optional: true };
+  }
+  if (f.stale) {
+    return { label: `Source target ${target.id} (corpus) cache is stale — run \`construct sources sync ${target.id}\``, ok: false, optional: true };
+  }
+  return { label: `Source target ${target.id} (corpus) cache is fresh`, ok: true };
+}
+
+function credentialFinding(target, env) {
+  const varName = CREDENTIAL_ENV[target.provider];
+  if (!varName) return null;
+  const present = typeof env[varName] === 'string' && env[varName].trim() !== '';
+  return present
+    ? null
+    : { label: `Source target ${target.id} (${target.provider}) credential not detected (${varName}) — presence check only`, ok: false, optional: true };
+}
+
+/**
+ * Evaluate source-target health. Returns { configured, findings } where each
+ * finding is { label, ok, optional? }. An empty findings array (configured 0)
+ * means the caller should stay silent.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]
+ * @param {object} [opts.env]
+ * @param {number} [opts.ttlMs]  corpus staleness threshold
+ * @param {number} [opts.now]    injectable clock (ms) for testing
+ */
+export function checkSourceTargetHealth({ cwd = process.cwd(), env = process.env, ttlMs = DEFAULT_CORPUS_TTL_MS, now = Date.now() } = {}) {
+  // Read the DECLARED targets from raw config, not the validated `config` — a
+  // directory target whose path was deleted fails config validation and would
+  // otherwise be sanitized away to an empty set, hiding the very problem this
+  // watcher exists to flag. `raw` preserves what the user actually registered.
+  const loaded = loadProjectConfig(cwd, env);
+  const sourceConfig = loaded.raw ?? loaded.config;
+  const targets = resolveEffectiveSourceTargetsFromConfig(sourceConfig, env);
+  if (!targets.length) return { configured: 0, findings: [] };
+
+  const findings = [];
+  for (const target of targets) {
+    const descriptor = getSourceTargetDescriptor(target.provider);
+    if (descriptor?.selector?.existsAs === 'directory') {
+      findings.push(directoryFinding(target));
+    } else if (isCorpusTarget(target)) {
+      findings.push(corpusFinding(target, { cwd, ttlMs, now }));
+    }
+    const cred = credentialFinding(target, env);
+    if (cred) findings.push(cred);
+  }
+  return { configured: targets.length, findings };
+}

package/lib/doctor/watchers/source-targets.mjs

@@ -0,0 +1,44 @@
+/**
+ * lib/doctor/watchers/source-targets.mjs — registered source-target health watcher.
+ *
+ * Ticks hourly. Reuses lib/doctor/source-target-health.mjs (filesystem + env
+ * only, zero outbound fetch) to surface directory targets whose path vanished
+ * and corpus caches past their TTL, recording an audit action per hard problem
+ * so doctor reports source-target drift between Oracle ticks. A project with no
+ * registered targets returns a silent pass (no noise).
+ */
+
+import { record } from '../audit.mjs';
+import { checkSourceTargetHealth } from '../source-target-health.mjs';
+
+export const name = 'source-targets';
+export const intervalMs = 60 * 60 * 1000;
+
+function projectRoot() {
+  return process.env.CONSTRUCT_PROJECT_ROOT || process.cwd();
+}
+
+export async function tick() {
+  const actions = [];
+  const escalations = [];
+  const root = projectRoot();
+
+  const { configured, findings } = checkSourceTargetHealth({ cwd: root });
+  if (!configured) {
+    return { actions, escalations, notes: [{ configured: 0 }] };
+  }
+
+  const problems = findings.filter((f) => !f.ok && !f.optional);
+  for (const problem of problems) {
+    record({
+      kind: 'action',
+      watcher: name,
+      action: 'source-target-unhealthy',
+      target: 'sources.targets',
+      summary: problem.label,
+    });
+    actions.push({ type: 'source-target-unhealthy', target: 'sources.targets' });
+  }
+
+  return { actions, escalations, notes: [{ configured, problems: problems.length }] };
+}

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';
   }