@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/dist/chunk-KZWGBUIO.js

@@ -0,0 +1,2659 @@
+import {
+  CANDIDATE_ITEM_ID_PREFIX,
+  CANDIDATE_SEARCH_PRIORITY,
+  MAX_UNRESOLVED_LINES,
+  QUERY_SAFE_EVIDENCE_CLASSES,
+  SERVICE_DOC_DOMAINS,
+  STACK_BLOCK_MARKERS,
+  acceptDetectedReality,
+  acknowledgeConflicts,
+  candidateSetSignature,
+  ciAdvisoryMessage,
+  computeStackFingerprint,
+  createIntentContract,
+  detectStack,
+  fingerprintDigest,
+  forgetDriftRecord,
+  isCandidateQuerySafe,
+  isQuerySafeHostname,
+  isSafeStackIdentifier,
+  legacyDeclaredStackPath,
+  listPendingDrift,
+  migrateLegacyDeclaration,
+  parseIntentSpec,
+  readDriftRecord,
+  readIntentContract,
+  readStoredFingerprint,
+  recordDelivery,
+  recordDriftRecords,
+  removeIntentContract,
+  renderAcknowledgedSdkPair,
+  renderStackAgentsBlock,
+  resolveIntent,
+  resolvedStackDetection,
+  retireContract,
+  serviceSignalForToken,
+  writeIntentContract,
+  writeStoredFingerprint
+} from "./chunk-VYI4DSZP.js";
+import {
+  CONTEXT_DIR,
+  KNOWLEDGE_BLOCK_BEGIN,
+  KNOWLEDGE_BLOCK_END,
+  KitItemSchema,
+  PURPOSE_BLOCK_MARKERS,
+  createManifest,
+  knowledgeManifestPath,
+  readKnowledgeManifest,
+  resolveBuildVersion,
+  writeKnowledgeManifest
+} from "./chunk-BQ3VAGXH.js";
+import {
+  runAsk
+} from "./chunk-YPDCLXNZ.js";
+import {
+  FRAMEWORK_RULES
+} from "./chunk-PFCXFO7A.js";
+import {
+  atomicWriteJson,
+  atomicWriteJsonSync,
+  atomicWriteText,
+  atomicWriteTextSync
+} from "./chunk-RFDVSI4N.js";
+import {
+  isCiEnvironment
+} from "./chunk-SKTFRFQ7.js";
+import {
+  getDefaultPaths
+} from "./chunk-56WPYDJH.js";
+import {
+  getPackageRoot
+} from "./chunk-STW7OFOA.js";
+
+// src/utils/managed-block.ts
+function upsertManagedBlock(existingContent, block, markers) {
+  const beginIndex = existingContent.indexOf(markers.begin);
+  const endIndex = existingContent.indexOf(markers.end);
+  if (beginIndex === -1 && endIndex === -1) {
+    if (existingContent.length === 0) return `${block}
+`;
+    const separator = existingContent.endsWith("\n\n") ? "" : existingContent.endsWith("\n") ? "\n" : "\n\n";
+    return `${existingContent}${separator}${block}
+`;
+  }
+  if (beginIndex === -1 || endIndex === -1 || endIndex < beginIndex) {
+    throw new Error(
+      `Document contains a malformed managed block (unpaired ${markers.begin} / ${markers.end} markers); refusing to modify it.`
+    );
+  }
+  const before = existingContent.slice(0, beginIndex);
+  const after = existingContent.slice(endIndex + markers.end.length);
+  return `${before}${block}${after}`;
+}
+function removeManagedBlock(existingContent, markers) {
+  const beginIndex = existingContent.indexOf(markers.begin);
+  const endIndex = existingContent.indexOf(markers.end);
+  if (beginIndex === -1 || endIndex === -1 || endIndex < beginIndex) {
+    return existingContent;
+  }
+  const before = existingContent.slice(0, beginIndex);
+  const after = existingContent.slice(endIndex + markers.end.length);
+  const trimmedBefore = before.endsWith("\n\n") ? before.slice(0, -1) : before;
+  return `${trimmedBefore}${after.startsWith("\n") ? after.slice(1) : after}`;
+}
+
+// src/core/knowledge/search.ts
+import { z } from "zod";
+
+// src/core/knowledge/framework-scope.ts
+function frameworkScopeClause(detection) {
+  if (detection.frameworks.length === 0) {
+    return " No application framework was detected in this repository, so keep results framework-neutral: cover the language, its standard library and its standard tooling, and leave out any resource that exists only for a specific framework.";
+  }
+  return ` Framework-specific resources are limited to the detected framework(s): ${detection.frameworks.join(", ")}. Leave out resources that exist only for other frameworks.`;
+}
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function buildEvidence() {
+  const evidence = /* @__PURE__ */ new Map();
+  for (const rule of FRAMEWORK_RULES) {
+    if (rule.dependencies === void 0) continue;
+    const entry = evidence.get(rule.label) ?? { patterns: [], hostLabels: [] };
+    for (const names of Object.values(rule.dependencies)) {
+      for (const raw of names ?? []) {
+        const name = raw.replace(/\*$/, "").replace(/:$/, "");
+        const slash = name.indexOf("/");
+        if (slash > 0) {
+          const owner = name.slice(0, slash);
+          entry.patterns.push(new RegExp(`(?<![a-z0-9._@-])${escapeRegExp(name)}(?![a-z0-9_-])`));
+          if (!owner.includes(".")) {
+            entry.patterns.push(new RegExp(`(?<![a-z0-9._-])${escapeRegExp(owner)}/`));
+            entry.hostLabels.push(owner.replace(/^@/, ""));
+          }
+        } else if (name.includes(".")) {
+          entry.patterns.push(new RegExp(`(?<![a-z0-9._-])${escapeRegExp(name)}(?![a-z0-9_-])`));
+        }
+      }
+    }
+    if (entry.patterns.length > 0) evidence.set(rule.label, entry);
+  }
+  return evidence;
+}
+var FRAMEWORK_EVIDENCE = buildEvidence();
+function hostLabelsOf(url) {
+  try {
+    return new URL(url).hostname.toLowerCase().split(".");
+  } catch {
+    return [];
+  }
+}
+function namesUndetectedFramework(row, detection) {
+  const detected = new Set(detection.frameworks.map((framework) => framework.toLowerCase()));
+  const text = `${row.sourceUrl} ${row.installHint ?? ""}`.toLowerCase();
+  const hostLabels = hostLabelsOf(row.sourceUrl);
+  for (const [label, evidence] of FRAMEWORK_EVIDENCE) {
+    if (detected.has(label)) continue;
+    if (evidence.patterns.some((pattern) => pattern.test(text))) return true;
+    if (evidence.hostLabels.some((owner) => hostLabels.includes(owner))) return true;
+  }
+  return false;
+}
+
+// src/core/knowledge/search.ts
+var DEFAULT_SEARCH_TIMEOUT_MS = 6e4;
+var DEFAULT_MAX_QUERIES = 4;
+var SourcePolicySchema = z.object({
+  allow: z.array(z.string().min(1)).default([]),
+  deny: z.array(z.string().min(1)).default([])
+});
+var OFFICIAL_DOC_DOMAINS = [
+  "apple.com",
+  "swift.org",
+  "developer.android.com",
+  "anthropic.com",
+  "modelcontextprotocol.io",
+  "nodejs.org",
+  "typescriptlang.org",
+  "react.dev",
+  "vuejs.org",
+  "angular.dev",
+  "svelte.dev",
+  "nextjs.org",
+  "python.org",
+  "go.dev",
+  "rust-lang.org",
+  "kotlinlang.org",
+  "dart.dev",
+  "flutter.dev",
+  "learn.microsoft.com",
+  // Curated external-service doc domains (service-signals.ts). Contributed here
+  // so a DETECTED service's docs carry `official` trust through the SAME gate —
+  // there is one trust system, not two.
+  ...SERVICE_DOC_DOMAINS
+];
+var DEFAULT_SOURCE_POLICY = { allow: [], deny: [] };
+function hostMatchesSuffix(host, suffix) {
+  const normalizedSuffix = suffix.toLowerCase().replace(/^\.+/, "");
+  return host === normalizedSuffix || host.endsWith(`.${normalizedSuffix}`);
+}
+function hostnameOf(url) {
+  try {
+    return new URL(url).hostname.toLowerCase();
+  } catch {
+    return void 0;
+  }
+}
+function isSourceAllowed(sourceUrl, policy) {
+  const host = hostnameOf(sourceUrl);
+  if (!host) return false;
+  if (policy.deny.some((suffix) => hostMatchesSuffix(host, suffix))) return false;
+  if (policy.allow.length === 0) return true;
+  return policy.allow.some((suffix) => hostMatchesSuffix(host, suffix));
+}
+function renderStackSummary(detection) {
+  const pairKeyed = /* @__PURE__ */ new Map();
+  for (const pair of detection.acknowledgedSdkPairs ?? []) {
+    pairKeyed.set(`${pair.platform}-${pair.sdkVersion}`, renderAcknowledgedSdkPair(pair));
+    pairKeyed.set(`${pair.platform}-${pair.deploymentVersion}`, "");
+  }
+  const sdkParts = [];
+  for (const target of detection.sdkTargets) {
+    if (pairKeyed.has(target)) {
+      const rendered = pairKeyed.get(target);
+      if (rendered) sdkParts.push(rendered);
+      continue;
+    }
+    sdkParts.push(target);
+  }
+  return [
+    detection.languages.filter((l) => l !== "unknown" && l !== "docs").join(", "),
+    detection.frameworks.join(", "),
+    sdkParts.join(", "),
+    (detection.tools ?? []).join(", "),
+    (detection.domains ?? []).join(", ")
+  ].filter((part) => part.length > 0).join("; ");
+}
+function buildSearchTasks(detection, maxQueries = DEFAULT_MAX_QUERIES, userGuidance) {
+  const stackSummary = renderStackSummary(detection);
+  if (!stackSummary) return [];
+  const guidance = userGuidance?.trim();
+  const querySuffix = frameworkScopeClause(detection) + (guidance ? ` The user gave this additional guidance about what they want: "${guidance}".` : "");
+  const tasks = [
+    {
+      id: "docs",
+      query: `Find the current best OFFICIAL documentation resources for coding agents working on this stack: ${stackSummary}. Prefer docs-as-markdown endpoints and official developer documentation MCP servers.${querySuffix}`
+    },
+    {
+      id: "mcp-skills",
+      query: `Find currently maintained MCP servers and official agent skills useful for a codebase using: ${stackSummary}. Include the exact install/registration command for each.${querySuffix}`
+    },
+    {
+      id: "rules",
+      query: `Find well-regarded community instruction/rule files (AGENTS.md snippets, cursor rules, agent guidelines) for: ${stackSummary}. Only include actively maintained sources.${querySuffix}`
+    },
+    {
+      id: "freshness",
+      query: `Find resources that cover APIs and SDK changes NEWER than typical LLM training data for: ${stackSummary} (release notes feeds, living changelogs, current API references).${querySuffix}`
+    }
+  ];
+  return tasks.slice(0, Math.max(0, maxQueries));
+}
+var CANDIDATE_QUERY_CHUNK_SIZE = 6;
+var CANDIDATE_SEARCH_TASK_ID_PREFIX = "candidate-docs";
+function evidenceClassPhrase(evidenceClass) {
+  switch (evidenceClass) {
+    case "env-template":
+      return "env key";
+    case "package":
+      return "package";
+    case "source":
+      return "source key";
+    case "script":
+      return "script key";
+    case "config":
+      return "config key";
+    case "hostname":
+      return "hostname";
+  }
+}
+function candidatePriorityRank(candidate) {
+  let best = CANDIDATE_SEARCH_PRIORITY.length;
+  for (const ev of candidate.evidence) {
+    const idx = CANDIDATE_SEARCH_PRIORITY.indexOf(ev.class);
+    if (idx !== -1 && idx < best) best = idx;
+  }
+  return best;
+}
+function renderCandidateEvidence(candidate) {
+  const seen = /* @__PURE__ */ new Set();
+  const hints = [];
+  const ordered = [...candidate.evidence].sort(
+    (a, b) => CANDIDATE_SEARCH_PRIORITY.indexOf(a.class) - CANDIDATE_SEARCH_PRIORITY.indexOf(b.class)
+  );
+  for (const ev of ordered) {
+    const querySafe = QUERY_SAFE_EVIDENCE_CLASSES.has(ev.class) || ev.class === "hostname" && isQuerySafeHostname(ev.matched.toLowerCase());
+    const hint = querySafe ? `${evidenceClassPhrase(ev.class)} ${ev.matched}` : evidenceClassPhrase(ev.class);
+    if (seen.has(hint)) continue;
+    seen.add(hint);
+    hints.push(hint);
+  }
+  const context = hints.length > 0 ? ` (${hints.join("; ")})` : "";
+  return `${candidate.token}${context}`;
+}
+function buildCandidateSearchTasks(candidates, maxQueries = DEFAULT_MAX_QUERIES, alreadyUsedQueries = 0) {
+  const remaining = Math.max(0, maxQueries - Math.max(0, alreadyUsedQueries));
+  const dispatchable = candidates.filter(isCandidateQuerySafe);
+  if (remaining === 0 || dispatchable.length === 0) {
+    return { tasks: [], coveredTokens: [] };
+  }
+  const ordered = [...dispatchable].sort(
+    (a, b) => candidatePriorityRank(a) - candidatePriorityRank(b)
+  );
+  const tasks = [];
+  const coveredTokens = [];
+  for (let chunkStart = 0; chunkStart < ordered.length; chunkStart += CANDIDATE_QUERY_CHUNK_SIZE) {
+    if (tasks.length >= remaining) break;
+    const chunk = ordered.slice(chunkStart, chunkStart + CANDIDATE_QUERY_CHUNK_SIZE);
+    const services = chunk.map(renderCandidateEvidence).join(", ");
+    tasks.push({
+      id: `${CANDIDATE_SEARCH_TASK_ID_PREFIX}:${chunk.map((c) => c.token).join("+")}`,
+      query: `The following external API services were detected in a codebase: ${services}. Find the OFFICIAL API documentation URL for each of these services; return one docs result per service.`
+    });
+    for (const c of chunk) coveredTokens.push(c.token);
+  }
+  return { tasks, coveredTokens };
+}
+async function dispatchCandidateSearch(tasks, options) {
+  if (tasks.length === 0) {
+    return { hits: [], allFailed: false, messages: [], queriesDispatched: 0 };
+  }
+  const timeoutMs = options.timeoutMs ?? DEFAULT_SEARCH_TIMEOUT_MS;
+  const policy = options.policy ?? DEFAULT_SOURCE_POLICY;
+  const messages = [];
+  const hitsByUrl = /* @__PURE__ */ new Map();
+  let failures = 0;
+  for (const task of tasks) {
+    let rows;
+    try {
+      rows = await withTimeout(
+        options.provider.search(task, { timeoutMs }),
+        timeoutMs,
+        `knowledge candidate search "${task.id}"`
+      );
+    } catch (error) {
+      failures += 1;
+      messages.push(
+        `Candidate search task "${task.id}" failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+      continue;
+    }
+    for (const row of rows) {
+      const parsed = RawSearchResultSchema.safeParse(row);
+      if (!parsed.success) continue;
+      const raw = parsed.data;
+      if (raw.kind !== "docs") continue;
+      if (!isSourceAllowed(raw.sourceUrl, policy)) continue;
+      const host = hostnameOf(raw.sourceUrl);
+      if (!host) continue;
+      const dedupKey = slugForUrl(raw.sourceUrl);
+      if (hitsByUrl.has(dedupKey)) continue;
+      hitsByUrl.set(dedupKey, {
+        kind: raw.kind,
+        sourceUrl: raw.sourceUrl,
+        hostname: host,
+        trust: clampTrust(raw),
+        description: raw.description,
+        installHint: raw.installHint
+      });
+    }
+  }
+  return {
+    hits: Array.from(hitsByUrl.values()),
+    allFailed: failures === tasks.length,
+    messages,
+    queriesDispatched: tasks.length
+  };
+}
+var RawSearchResultSchema = z.object({
+  kind: z.enum(["mcp", "skill", "instructions", "docs"]),
+  sourceUrl: z.string().url(),
+  trust: z.enum(["official", "community", "third-party"]),
+  description: z.string().min(1),
+  installHint: z.string().min(1).optional()
+});
+var PROVIDER_RESPONSE_INSTRUCTIONS = [
+  "Respond with ONLY a JSON array (no prose, no code fence). Each element:",
+  '{"kind":"mcp"|"skill"|"instructions"|"docs","sourceUrl":"https://...","trust":"official"|"community"|"third-party","description":"one line","installHint":"exact command (optional)"}',
+  "Include at most 6 results. Only include resources you are confident currently exist.",
+  "Write each description as a neutral third-person line about the resource itself. Do not use first person, and do not add notes about what you checked or could not confirm; leave out a resource you cannot vouch for."
+].join("\n");
+function extractJsonArray(text) {
+  const start = text.indexOf("[");
+  const end = text.lastIndexOf("]");
+  if (start === -1 || end <= start) return [];
+  try {
+    const parsed = JSON.parse(text.slice(start, end + 1));
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+function createAskSearchProvider(options) {
+  const ask = options.ask ?? runAsk;
+  return {
+    async search(task, { timeoutMs }) {
+      const result = await ask({
+        target: options.providerId,
+        question: `${task.query}
+
+${PROVIDER_RESPONSE_INSTRUCTIONS}`,
+        cwd: options.cwd,
+        timeoutMs
+      });
+      return extractJsonArray(result.answer);
+    }
+  };
+}
+var OFFLINE_FALLBACK_MESSAGE = "Knowledge search is unavailable (provider offline or unreachable). No recommendations were fetched; re-run when online, or add items manually.";
+function withTimeout(promise, timeoutMs, label) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const timer = setTimeout(() => {
+      rejectPromise(new Error(`${label} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolvePromise(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        rejectPromise(error);
+      }
+    );
+  });
+}
+function slugForUrl(url) {
+  const host = hostnameOf(url) ?? "unknown";
+  let pathname = "";
+  try {
+    pathname = new URL(url).pathname.replace(/\/+$/, "");
+  } catch {
+  }
+  return `${host}${pathname}`.toLowerCase();
+}
+function clampTrust(result) {
+  if (result.trust !== "official") return result.trust;
+  const host = hostnameOf(result.sourceUrl);
+  if (host && OFFICIAL_DOC_DOMAINS.some((suffix) => hostMatchesSuffix(host, suffix))) {
+    return "official";
+  }
+  return "community";
+}
+async function searchRecommendations(detection, options) {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_SEARCH_TIMEOUT_MS;
+  const maxQueries = options.maxQueries ?? DEFAULT_MAX_QUERIES;
+  const policy = options.policy ?? DEFAULT_SOURCE_POLICY;
+  const tasks = buildSearchTasks(detection, maxQueries, options.userGuidance);
+  if (tasks.length === 0) {
+    return { status: "ok", items: [], messages: [], queriesDispatched: 0, failedTasks: 0 };
+  }
+  const messages = [];
+  const itemsById = /* @__PURE__ */ new Map();
+  let failures = 0;
+  for (const task of tasks) {
+    let rows;
+    try {
+      rows = await withTimeout(
+        options.provider.search(task, { timeoutMs }),
+        timeoutMs,
+        `knowledge search "${task.id}"`
+      );
+    } catch (error) {
+      failures += 1;
+      messages.push(
+        `Search task "${task.id}" failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+      continue;
+    }
+    for (const row of rows) {
+      const parsed = RawSearchResultSchema.safeParse(row);
+      if (!parsed.success) continue;
+      const raw = parsed.data;
+      if (!isSourceAllowed(raw.sourceUrl, policy)) continue;
+      if (namesUndetectedFramework(raw, detection)) continue;
+      const trust = clampTrust(raw);
+      const id = `${raw.kind}:${slugForUrl(raw.sourceUrl)}`;
+      if (itemsById.has(id)) continue;
+      const candidate = KitItemSchema.safeParse({
+        id,
+        kind: raw.kind,
+        sourceUrl: raw.sourceUrl,
+        trust,
+        description: raw.description,
+        installHint: raw.installHint
+      });
+      if (candidate.success) itemsById.set(id, candidate.data);
+    }
+  }
+  if (failures === tasks.length) {
+    return {
+      status: "offline",
+      items: [],
+      messages: [OFFLINE_FALLBACK_MESSAGE, ...messages],
+      queriesDispatched: tasks.length,
+      failedTasks: tasks.length
+    };
+  }
+  return {
+    status: "ok",
+    items: Array.from(itemsById.values()),
+    messages,
+    queriesDispatched: tasks.length,
+    failedTasks: failures
+  };
+}
+
+// src/core/knowledge/apply.ts
+import { lstatSync, readFileSync as readFileSync2 } from "fs";
+import path2 from "path";
+
+// src/core/knowledge/cache.ts
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+import { z as z2 } from "zod";
+var DEFAULT_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
+var CACHE_DIR_NAME = "knowledge-cache";
+var CacheEntrySchema = z2.object({
+  schemaVersion: z2.literal(1),
+  stackFingerprint: z2.string().min(1),
+  buildVersion: z2.string().min(1),
+  /** ISO timestamp the recommendations were fetched. */
+  fetchedAt: z2.string().min(1),
+  items: z2.array(KitItemSchema),
+  /** Human-facing notes captured with the fetch (partial-failure messages). */
+  messages: z2.array(z2.string()).default([]),
+  /**
+   * Exact-set signature of the service candidates present when this entry was
+   * cached ({@link candidateSetSignature}). Absent on legacy entries written
+   * before generalized service discovery — the offer layer treats a missing
+   * signature as a miss whenever the current detection has candidates (so a
+   * stale entry never hides newly discovered services). Never carries the
+   * unresolved-candidate list: an unresolved token is NOT a cacheable "no docs"
+   * answer, only the resolved candidate docs items are persisted (in `items`).
+   */
+  candidateSignature: z2.string().optional()
+});
+function resolveCacheDir(options) {
+  return options.cacheDir ?? path.join(getDefaultPaths().userConfigDir, CACHE_DIR_NAME);
+}
+function cacheKey(stackFingerprint, buildVersion) {
+  const safeVersion = buildVersion.replace(/[^A-Za-z0-9._-]/g, "_");
+  return `${stackFingerprint}-v${safeVersion}.json`;
+}
+function entryPath(options, fingerprint, version) {
+  return path.join(resolveCacheDir(options), cacheKey(fingerprint, version));
+}
+function readCachedRecommendations(stackFingerprint, options = {}) {
+  const buildVersion = resolveBuildVersion();
+  const filePath = entryPath(options, stackFingerprint, buildVersion);
+  if (!existsSync(filePath)) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return void 0;
+  }
+  const result = CacheEntrySchema.safeParse(parsed);
+  if (!result.success) return void 0;
+  const entry = result.data;
+  if (entry.stackFingerprint !== stackFingerprint || entry.buildVersion !== buildVersion) {
+    return void 0;
+  }
+  const ttlMs = options.ttlMs ?? DEFAULT_CACHE_TTL_MS;
+  const now = (options.now?.() ?? /* @__PURE__ */ new Date()).getTime();
+  const fetchedAt = Date.parse(entry.fetchedAt);
+  if (!Number.isFinite(fetchedAt) || now - fetchedAt > ttlMs) return void 0;
+  return entry;
+}
+async function writeCachedRecommendations(stackFingerprint, items, messages = [], options = {}, candidateSignature) {
+  const buildVersion = resolveBuildVersion();
+  const entry = {
+    schemaVersion: 1,
+    stackFingerprint,
+    buildVersion,
+    fetchedAt: (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
+    items,
+    messages,
+    // Only persisted when candidates existed at fetch time; a signature of ''
+    // (no candidates) is meaningful too (exact-set equality), so store it
+    // whenever the caller supplies one.
+    ...candidateSignature !== void 0 ? { candidateSignature } : {}
+  };
+  try {
+    await atomicWriteText(
+      entryPath(options, stackFingerprint, buildVersion),
+      JSON.stringify(entry, null, 2),
+      { ensureDir: true, trailingNewline: true }
+    );
+  } catch {
+  }
+}
+var LIBRARY_CACHE_DIR_NAME = "libraries";
+var LibraryCacheEntrySchema = z2.object({
+  schemaVersion: z2.literal(1),
+  ecosystem: z2.string().min(1),
+  name: z2.string().min(1),
+  fetchedAt: z2.string().min(1),
+  item: KitItemSchema
+});
+function libraryEntryPath(options, ecosystem, name) {
+  const safe = name.replace(/[^a-z0-9.-]/g, (ch) => `%${ch.charCodeAt(0).toString(16)}`);
+  return path.join(resolveCacheDir(options), LIBRARY_CACHE_DIR_NAME, `${ecosystem}--${safe}.json`);
+}
+function readCachedLibraryDocs(ecosystem, name, options = {}) {
+  const filePath = libraryEntryPath(options, ecosystem, name);
+  if (!existsSync(filePath)) return void 0;
+  try {
+    const entry = LibraryCacheEntrySchema.parse(JSON.parse(readFileSync(filePath, "utf8")));
+    if (entry.ecosystem !== ecosystem || entry.name !== name) return void 0;
+    const now = (options.now?.() ?? /* @__PURE__ */ new Date()).getTime();
+    const fetchedAt = Date.parse(entry.fetchedAt);
+    if (!Number.isFinite(fetchedAt) || now - fetchedAt > (options.ttlMs ?? DEFAULT_CACHE_TTL_MS)) {
+      return void 0;
+    }
+    return entry.item;
+  } catch {
+    return void 0;
+  }
+}
+async function writeCachedLibraryDocs(ecosystem, name, item, options = {}) {
+  try {
+    await atomicWriteText(
+      libraryEntryPath(options, ecosystem, name),
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          ecosystem,
+          name,
+          fetchedAt: (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
+          item
+        },
+        null,
+        2
+      ),
+      { ensureDir: true, trailingNewline: true }
+    );
+  } catch {
+  }
+}
+
+// src/core/knowledge/candidate-matching.ts
+function candidateTokenVariants(token) {
+  const lower = token.toLowerCase();
+  const variants = /* @__PURE__ */ new Set([
+    lower,
+    lower.replace(/_/g, "-"),
+    lower.replace(/-/g, "_"),
+    lower.replace(/[-_]/g, ""),
+    // Host-derived tokens hyphenate dots (data.sec.gov -> sec-gov); a docs hit
+    // on the ORIGINAL dotted domain (sec.gov) must still match (Codex P2).
+    lower.replace(/[-_]/g, ".")
+  ]);
+  return [...variants].filter((v) => v.length > 0);
+}
+function boundaryMatch(haystack, needle) {
+  let from = 0;
+  while (true) {
+    const at = haystack.indexOf(needle, from);
+    if (at === -1) return false;
+    const before = at === 0 ? "" : haystack[at - 1];
+    const afterIdx = at + needle.length;
+    const after = afterIdx >= haystack.length ? "" : haystack[afterIdx];
+    const isBoundary = (ch) => ch === "" || !/[a-z0-9]/.test(ch);
+    if (isBoundary(before) && isBoundary(after)) return true;
+    from = at + 1;
+  }
+}
+function hitMentionsToken(hit, token) {
+  const haystacks = [hit.hostname, hit.description.toLowerCase()];
+  return candidateTokenVariants(token).some((v) => haystacks.some((h) => boundaryMatch(h, v)));
+}
+function hitMatchesCandidate(hit, candidate) {
+  if (hitMentionsToken(hit, candidate.token)) return true;
+  const hitTail = registrableTail(hit.hostname);
+  if (!hitTail) return false;
+  return candidate.evidence.some(
+    (ev) => ev.class === "hostname" && registrableTail(ev.matched.toLowerCase()) === hitTail
+  );
+}
+var PUBLIC_SUFFIX_SECOND_LABELS = /* @__PURE__ */ new Set([
+  "co",
+  "com",
+  "org",
+  "net",
+  "gov",
+  "ac",
+  "edu"
+]);
+function registrableTail(hostname) {
+  const labels = hostname.split(".").filter(Boolean);
+  if (labels.length < 2) return void 0;
+  const take = labels.length >= 3 && PUBLIC_SUFFIX_SECOND_LABELS.has(labels[labels.length - 2]) ? 3 : 2;
+  if (labels.length < take) return void 0;
+  return labels.slice(-take).join(".");
+}
+
+// src/core/knowledge/library-suggestions.ts
+var LIBRARY_ITEM_ID_PREFIX = "docs:library:";
+var REGISTRY_PHRASES = {
+  npm: "npm package",
+  pypi: "PyPI package",
+  go: "Go module",
+  cargo: "Rust crate",
+  maven: "Maven artifact",
+  nuget: "NuGet package",
+  rubygems: "Ruby gem",
+  packagist: "Composer package",
+  pub: "pub.dev package",
+  hex: "Hex package",
+  swiftpm: "Swift package"
+};
+function libraryToken(library) {
+  const tail = library.name.split(/[/:]/).pop() ?? library.name;
+  return tail.replace(/^@/, "");
+}
+function libraryNamespace(library) {
+  const segments = library.name.split("/");
+  let namespace;
+  if (library.ecosystem === "npm" && library.name.startsWith("@")) {
+    namespace = segments[0]?.slice(1);
+  } else if (library.ecosystem === "packagist" && segments.length === 2) {
+    namespace = segments[0];
+  } else if (library.ecosystem === "go" && segments.length >= 3) {
+    namespace = segments[segments.length - 2];
+  }
+  return namespace && namespace.length >= 2 ? namespace : void 0;
+}
+var COMMON_GROUP_PREFIXES = /* @__PURE__ */ new Set([
+  "com",
+  "org",
+  "io",
+  "net",
+  "edu",
+  "gov",
+  "dev",
+  "app",
+  "co",
+  "me",
+  "eu",
+  "uk",
+  "de"
+]);
+function hitMatchesLibrary(hit, library) {
+  if (library.ecosystem === "maven") {
+    const group = library.name.split(":")[0] ?? "";
+    return hitMentionsToken(hit, library.name) || hitMentionsToken(hit, libraryToken(library)) && group.split(".").some((segment) => !COMMON_GROUP_PREFIXES.has(segment) && hitMentionsToken(hit, segment));
+  }
+  const namespace = libraryNamespace(library);
+  return hitMentionsToken(hit, libraryToken(library)) && (namespace === void 0 || hitMentionsToken(hit, namespace));
+}
+function libraryOwningHit(hit, covered) {
+  const matching = covered.filter((library) => hitMatchesLibrary(hit, library));
+  return matching.length === 1 ? matching[0] : void 0;
+}
+function libraryItemId(library) {
+  return `${LIBRARY_ITEM_ID_PREFIX}${library.ecosystem}:${library.name}`;
+}
+function buildLibrarySearchTasks(libraries, maxTasks) {
+  const tasks = [];
+  const covered = [];
+  for (let start = 0; start < libraries.length && tasks.length < maxTasks; ) {
+    const chunk = libraries.slice(start, start + CANDIDATE_QUERY_CHUNK_SIZE);
+    start += CANDIDATE_QUERY_CHUNK_SIZE;
+    const listed = chunk.map((lib) => `${lib.name} (${REGISTRY_PHRASES[lib.ecosystem]})`);
+    tasks.push({
+      id: `library-docs:${chunk.map((lib) => `${lib.ecosystem}/${lib.name}`).join("+")}`,
+      query: `The following public libraries are direct dependencies of a codebase: ${listed.join(", ")}. Find the OFFICIAL documentation URL for each of these libraries; return one docs result per library.`
+    });
+    covered.push(...chunk);
+  }
+  return { tasks, covered };
+}
+function itemForHit(library, hit) {
+  return {
+    id: libraryItemId(library),
+    kind: "docs",
+    sourceUrl: hit.sourceUrl,
+    trust: hit.trust,
+    description: `${library.name} \u2014 searched docs (${REGISTRY_PHRASES[library.ecosystem]} dependency)`
+  };
+}
+function uncachedLibraries(libraries, cache) {
+  return libraries.filter((lib) => !readCachedLibraryDocs(lib.ecosystem, lib.name, cache));
+}
+function libraryQueriesNeeded(detection, cache, isCi = isCiEnvironment) {
+  const libraries = detection.libraryCandidates ?? [];
+  if (libraries.length === 0 || isCi()) return 0;
+  return Math.ceil(uncachedLibraries(libraries, cache).length / CANDIDATE_QUERY_CHUNK_SIZE);
+}
+async function suggestLibraryDocs(options) {
+  const libraries = options.detection.libraryCandidates ?? [];
+  if (libraries.length === 0 || (options.isCi ?? isCiEnvironment)()) return [];
+  const taken = new Set(options.existingItems.map((item) => item.id));
+  const takenUrls = new Set(options.existingItems.map((item) => item.sourceUrl.toLowerCase()));
+  const accept = (item) => {
+    if (taken.has(item.id) || takenUrls.has(item.sourceUrl.toLowerCase())) return false;
+    taken.add(item.id);
+    takenUrls.add(item.sourceUrl.toLowerCase());
+    return true;
+  };
+  const offered = [];
+  const misses = uncachedLibraries(libraries, options.cache);
+  for (const library of libraries) {
+    const cached = readCachedLibraryDocs(library.ecosystem, library.name, options.cache);
+    if (cached && accept(cached)) offered.push(cached);
+  }
+  if (misses.length === 0 || !options.allowSearch || options.remainingQueries <= 0) {
+    return offered;
+  }
+  const { tasks, covered } = buildLibrarySearchTasks(misses, options.remainingQueries);
+  const search = await dispatchCandidateSearch(tasks, {
+    provider: options.provider,
+    timeoutMs: options.timeoutMs,
+    policy: options.policy ?? DEFAULT_SOURCE_POLICY
+  });
+  for (const library of covered) {
+    const hit = search.hits.find((candidate) => libraryOwningHit(candidate, covered) === library);
+    if (!hit) continue;
+    const item = itemForHit(library, hit);
+    await writeCachedLibraryDocs(library.ecosystem, library.name, item, options.cache);
+    if (accept(item)) offered.push(item);
+  }
+  return offered;
+}
+
+// src/core/knowledge/apply.ts
+var DEGRADED_SEARCH_NOT_CACHED_MESSAGE = "Some search lanes failed or timed out; results were not cached and the next offer will search again.";
+function curatedServiceItems(detection, policy) {
+  const items = [];
+  const seenTokens = /* @__PURE__ */ new Set();
+  for (const service of detection.detectedServices ?? []) {
+    if (service.confidence === "low") continue;
+    const signal = serviceSignalForToken(service.token);
+    if (!signal) continue;
+    if (!isSourceAllowed(signal.docsUrl, policy)) continue;
+    seenTokens.add(signal.token);
+    items.push({
+      id: `docs:service:${signal.token}`,
+      kind: "docs",
+      sourceUrl: signal.docsUrl,
+      trust: "official",
+      description: `${signal.description} (detected: ${service.evidence.join("+")})`
+    });
+  }
+  for (const candidate of serviceCandidatesOf(detection)) {
+    if (candidate.confidence !== "confirmed") continue;
+    if (seenTokens.has(candidate.token)) continue;
+    const signal = serviceSignalForToken(candidate.token);
+    if (!signal) continue;
+    if (!isSourceAllowed(signal.docsUrl, policy)) continue;
+    seenTokens.add(signal.token);
+    items.push({
+      id: `docs:service:${signal.token}`,
+      kind: "docs",
+      sourceUrl: signal.docsUrl,
+      trust: "official",
+      description: `${signal.description} (detected: ${candidateEvidenceClasses(candidate).join("+")})`
+    });
+  }
+  return items;
+}
+function normalizeUrlForDedup(url) {
+  try {
+    const parsed = new URL(url);
+    const pathname = parsed.pathname.replace(/\/+$/, "");
+    return `${parsed.protocol}//${parsed.host}${pathname}${parsed.search}`.toLowerCase();
+  } catch {
+    return url.trim().replace(/\/+$/, "").toLowerCase();
+  }
+}
+function mergeServiceItems(baseItems, serviceItems) {
+  if (serviceItems.length === 0) return baseItems;
+  const serviceUrls = new Set(serviceItems.map((item) => normalizeUrlForDedup(item.sourceUrl)));
+  const serviceIds = new Set(serviceItems.map((item) => item.id));
+  const merged = baseItems.filter(
+    (item) => !serviceIds.has(item.id) && !serviceUrls.has(normalizeUrlForDedup(item.sourceUrl))
+  );
+  return [...serviceItems, ...merged];
+}
+function serviceCandidatesOf(detection) {
+  return detection.serviceCandidates ?? [];
+}
+function candidateEvidenceClasses(candidate) {
+  const seen = /* @__PURE__ */ new Set();
+  const classes = [];
+  for (const ev of candidate.evidence) {
+    if (seen.has(ev.class)) continue;
+    seen.add(ev.class);
+    classes.push(ev.class);
+  }
+  return classes;
+}
+function candidateEvidenceStrings(candidate) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const ev of candidate.evidence) {
+    const redact = ev.class === "source" || ev.class === "script";
+    const rendered = redact ? `${ev.class} key` : `${ev.class} ${ev.matched}`;
+    if (seen.has(rendered)) continue;
+    seen.add(rendered);
+    out.push(rendered);
+  }
+  return out;
+}
+function candidateResolvedByItems(token, items) {
+  const curatedId = `docs:service:${token}`;
+  const candidateId = `${CANDIDATE_ITEM_ID_PREFIX}${token}`;
+  if (items.some((item) => item.id === curatedId || item.id === candidateId)) return true;
+  const variants = candidateTokenVariants(token);
+  return items.some(
+    (item) => item.kind === "docs" && variants.some((v) => boundaryMatch(normalizeUrlForDedup(item.sourceUrl), v))
+  );
+}
+function unresolvedFrom(candidates, resolvingItems) {
+  const out = [];
+  for (const candidate of candidates) {
+    if (candidateResolvedByItems(candidate.token, resolvingItems)) continue;
+    out.push({ token: candidate.token, evidence: candidateEvidenceStrings(candidate) });
+  }
+  return out;
+}
+function attachCandidateHits(candidates, coveredTokens, hits, existingItems) {
+  const items = [];
+  const unresolved = [];
+  const seenIds = new Set(existingItems.map((item) => item.id));
+  const seenUrls = new Set(existingItems.map((item) => normalizeUrlForDedup(item.sourceUrl)));
+  for (const candidate of candidates) {
+    const token = candidate.token;
+    if (candidateResolvedByItems(token, existingItems)) continue;
+    const candidateItemId = `${CANDIDATE_ITEM_ID_PREFIX}${token}`;
+    if (seenIds.has(candidateItemId)) continue;
+    if (!coveredTokens.has(token)) {
+      unresolved.push({ token, evidence: candidateEvidenceStrings(candidate) });
+      continue;
+    }
+    const matching = hits.filter((hit) => hitMatchesCandidate(hit, candidate));
+    if (matching.length === 0) {
+      unresolved.push({ token, evidence: candidateEvidenceStrings(candidate) });
+      continue;
+    }
+    const pick = matching.find((hit) => !seenUrls.has(normalizeUrlForDedup(hit.sourceUrl)));
+    if (!pick) {
+      const resolvedByEmitted = candidateResolvedByItems(token, items);
+      if (!resolvedByEmitted) {
+        unresolved.push({ token, evidence: candidateEvidenceStrings(candidate) });
+      }
+      continue;
+    }
+    const item = {
+      id: candidateItemId,
+      kind: "docs",
+      sourceUrl: pick.sourceUrl,
+      trust: pick.trust,
+      description: `${token} \u2014 searched docs (detected via ${candidateEvidenceClasses(candidate).join(", ")})`
+    };
+    items.push(item);
+    seenIds.add(candidateItemId);
+    seenUrls.add(normalizeUrlForDedup(pick.sourceUrl));
+  }
+  return { items, unresolved };
+}
+function candidateSummaryMessage(candidateCount, unresolved) {
+  const resolved = candidateCount - unresolved.length;
+  let line = `Service discovery: ${resolved} resolved, ${unresolved.length} unresolved candidates.`;
+  if (unresolved.length > MAX_UNRESOLVED_LINES) {
+    const shown = unresolved.slice(0, MAX_UNRESOLVED_LINES).map((u) => u.token);
+    line += ` Unresolved: ${shown.join(", ")} +${unresolved.length - MAX_UNRESOLVED_LINES} more.`;
+  } else if (unresolved.length > 0) {
+    line += ` Unresolved: ${unresolved.map((u) => u.token).join(", ")}.`;
+  }
+  return line;
+}
+async function buildKitOffer(cwd, options) {
+  const detection = options.detection ?? detectStack(cwd);
+  const guidance = options.userGuidance?.trim() || void 0;
+  const policy = options.policy ?? DEFAULT_SOURCE_POLICY;
+  const maxQueries = options.maxQueries ?? DEFAULT_MAX_QUERIES;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_SEARCH_TIMEOUT_MS;
+  const serviceItems = curatedServiceItems(detection, policy);
+  const candidates = serviceCandidatesOf(detection);
+  const currentSignature = candidateSetSignature(candidates);
+  const libraryOptions = {
+    detection,
+    provider: options.provider,
+    policy,
+    timeoutMs,
+    cache: options.cache,
+    remainingQueries: 0,
+    existingItems: [],
+    allowSearch: false
+  };
+  if (!options.refresh && !guidance) {
+    const cached = readCachedRecommendations(detection.fingerprint, options.cache);
+    const signatureMatches = cached === void 0 ? false : cached.candidateSignature === void 0 ? candidates.length === 0 : cached.candidateSignature === currentSignature;
+    if (cached && signatureMatches) {
+      const stackItems2 = mergeServiceItems(cached.items, serviceItems);
+      const unresolvedCandidates2 = unresolvedFrom(candidates, stackItems2);
+      const items2 = [
+        ...stackItems2,
+        ...await suggestLibraryDocs({
+          ...libraryOptions,
+          allowSearch: false,
+          existingItems: stackItems2
+        })
+      ];
+      const messages2 = [
+        `Recommendations from cache (fetched ${cached.fetchedAt}); use refresh to search again.`,
+        ...cached.messages
+      ];
+      if (candidates.length > 0) {
+        messages2.push(candidateSummaryMessage(candidates.length, unresolvedCandidates2));
+      }
+      return { detection, items: items2, source: "cache", offline: false, messages: messages2, unresolvedCandidates: unresolvedCandidates2 };
+    }
+  }
+  const searchableCandidates = candidates.filter(
+    (c) => c.confidence === "confirmed" && isCandidateQuerySafe(c) && !candidateResolvedByItems(c.token, serviceItems)
+  );
+  const candidateChunks = Math.ceil(searchableCandidates.length / CANDIDATE_QUERY_CHUNK_SIZE);
+  const reservedForCandidates = maxQueries > 0 && candidateChunks > 0 ? Math.max(1, Math.min(Math.floor(maxQueries / 2), candidateChunks)) : 0;
+  const reservedForLibraries = maxQueries > 1 ? Math.min(libraryQueriesNeeded(detection, options.cache), 1) : 0;
+  const result = await searchRecommendations(detection, {
+    provider: options.provider,
+    timeoutMs,
+    maxQueries: Math.max(
+      maxQueries > 0 ? 1 : 0,
+      maxQueries - reservedForCandidates - reservedForLibraries
+    ),
+    policy,
+    userGuidance: guidance
+  });
+  if (result.status === "offline") {
+    const unresolvedCandidates2 = unresolvedFrom(candidates, serviceItems);
+    const offlineMessages = candidates.length > 0 ? [...result.messages, candidateSummaryMessage(candidates.length, unresolvedCandidates2)] : result.messages;
+    if (serviceItems.length > 0) {
+      return {
+        detection,
+        items: serviceItems,
+        source: "search",
+        offline: false,
+        messages: offlineMessages,
+        unresolvedCandidates: unresolvedCandidates2
+      };
+    }
+    return {
+      detection,
+      items: [],
+      source: "none",
+      offline: true,
+      messages: offlineMessages,
+      unresolvedCandidates: unresolvedCandidates2
+    };
+  }
+  const preResolvedItems = mergeServiceItems(result.items, serviceItems);
+  const confirmedCandidates = candidates.filter(
+    (c) => c.confidence === "confirmed" && !candidateResolvedByItems(c.token, preResolvedItems)
+  );
+  const { tasks: candidateTasks, coveredTokens } = buildCandidateSearchTasks(
+    confirmedCandidates,
+    maxQueries,
+    result.queriesDispatched
+  );
+  const candidateSearch = await dispatchCandidateSearch(candidateTasks, {
+    provider: options.provider,
+    timeoutMs,
+    policy
+  });
+  const baseItems = mergeServiceItems(result.items, serviceItems);
+  const { items: candidateItems, unresolved: unresolvedCandidates } = attachCandidateHits(
+    candidates,
+    new Set(coveredTokens),
+    candidateSearch.hits,
+    baseItems
+  );
+  const stackItems = [...baseItems, ...candidateItems];
+  const libraryItems = await suggestLibraryDocs({
+    ...libraryOptions,
+    allowSearch: !(candidateTasks.length > 0 && candidateSearch.allFailed),
+    remainingQueries: maxQueries - result.queriesDispatched - candidateSearch.queriesDispatched,
+    existingItems: stackItems
+  });
+  const items = [...stackItems, ...libraryItems];
+  const messages = [...result.messages, ...candidateSearch.messages];
+  if (candidates.length > 0) {
+    messages.push(candidateSummaryMessage(candidates.length, unresolvedCandidates));
+  }
+  const candidateSearchDead = candidateTasks.length > 0 && candidateSearch.allFailed;
+  if (candidateSearchDead && result.queriesDispatched === 0) {
+    return {
+      detection,
+      items: mergeServiceItems([], serviceItems),
+      source: serviceItems.length > 0 ? "search" : "none",
+      offline: serviceItems.length === 0,
+      messages,
+      unresolvedCandidates
+    };
+  }
+  const searchDegraded = result.failedTasks > 0 || candidateSearchDead;
+  if (searchDegraded) {
+    messages.push(DEGRADED_SEARCH_NOT_CACHED_MESSAGE);
+  }
+  if (!guidance && !searchDegraded) {
+    const searchableTokens = new Set(
+      candidates.filter((c) => c.confidence === "confirmed" && isCandidateQuerySafe(c)).map((c) => c.token)
+    );
+    const searchableUnresolved = unresolvedCandidates.filter(
+      (u) => searchableTokens.has(u.token)
+    ).length;
+    const fullyCovered = !candidateSearchDead && searchableUnresolved === 0;
+    await writeCachedRecommendations(
+      detection.fingerprint,
+      fullyCovered ? [...result.items, ...candidateItems] : result.items,
+      result.messages,
+      options.cache,
+      fullyCovered ? currentSignature : void 0
+    );
+  }
+  return {
+    detection,
+    items,
+    source: "search",
+    offline: false,
+    messages,
+    unresolvedCandidates
+  };
+}
+var KNOWLEDGE_BLOCK_MARKERS = {
+  begin: KNOWLEDGE_BLOCK_BEGIN,
+  end: KNOWLEDGE_BLOCK_END
+};
+function safeHost(sourceUrl) {
+  try {
+    return new URL(sourceUrl).hostname;
+  } catch {
+    return "(invalid-url)";
+  }
+}
+function renderKnowledgeBlock(items, updatedAt) {
+  const lines = [
+    KNOWLEDGE_BLOCK_BEGIN,
+    "## Knowledge kit (managed by Build)",
+    "",
+    `Current stack resources accepted via \`build init\` (updated ${updatedAt}).`,
+    "Do not edit inside this block \u2014 changes are overwritten on the next apply.",
+    "Full source URLs live in .build-project/context/knowledge/manifest.json.",
+    ""
+  ];
+  for (const item of items) {
+    lines.push(
+      `- [${item.trust}] ${item.kind}: ${safeHost(item.sourceUrl)} (${item.versionOrDate}, ${item.mode})`
+    );
+  }
+  if (items.length === 0) {
+    lines.push("- (no accepted items)");
+  }
+  lines.push(KNOWLEDGE_BLOCK_END);
+  return lines.join("\n");
+}
+var PENDING_INTENT_MARKER = "A stack intent contract is declared for this repository";
+function renderPendingIntentBlock(dimensionCount) {
+  const safeCount = Number.isFinite(dimensionCount) && dimensionCount > 0 ? Math.floor(dimensionCount) : 0;
+  const dimensionsPhrase = safeCount === 1 ? "1 dimension" : `${safeCount} dimensions`;
+  const lines = [
+    KNOWLEDGE_BLOCK_BEGIN,
+    "## Knowledge kit (managed by Build)",
+    "",
+    `${PENDING_INTENT_MARKER} (${dimensionsPhrase}), but no knowledge kit has been accepted yet.`,
+    "Run `build init knowledge status` for details and `build init knowledge offer` to fetch curated resources.",
+    "Do not edit inside this block \u2014 it is replaced automatically when a kit is accepted.",
+    KNOWLEDGE_BLOCK_END
+  ];
+  return lines.join("\n");
+}
+function blockIsPendingIntent(existingContent) {
+  const beginIndex = existingContent.indexOf(KNOWLEDGE_BLOCK_BEGIN);
+  const endIndex = existingContent.indexOf(KNOWLEDGE_BLOCK_END);
+  if (beginIndex === -1 || endIndex === -1 || endIndex < beginIndex) return false;
+  const block = existingContent.slice(beginIndex, endIndex + KNOWLEDGE_BLOCK_END.length);
+  return block.includes(PENDING_INTENT_MARKER);
+}
+function removeKnowledgeBlock(existingContent) {
+  return removeManagedBlock(existingContent, KNOWLEDGE_BLOCK_MARKERS);
+}
+function upsertKnowledgeBlock(existingContent, block) {
+  return upsertManagedBlock(existingContent, block, KNOWLEDGE_BLOCK_MARKERS);
+}
+function provenancePath(root, appliedAt) {
+  const stamp = appliedAt.replace(/[:.]/g, "-");
+  return path2.join(root, ".build-project", "provenance", `knowledge-apply-${stamp}.json`);
+}
+function trustNoteFor(item) {
+  switch (item.trust) {
+    case "official":
+      return "Official vendor source.";
+    case "community":
+      return "Community-maintained source \u2014 review before installing.";
+    default:
+      return "THIRD-PARTY source \u2014 Build will not install this automatically; review the command and source before running it.";
+  }
+}
+async function applyKit(offer, acceptedItemIds, options = {}) {
+  const root = offer.detection.root;
+  const now = options.now?.() ?? /* @__PURE__ */ new Date();
+  const appliedAt = now.toISOString();
+  const acceptedIds = new Set(acceptedItemIds);
+  const unknownIds = acceptedItemIds.filter((id) => !offer.items.some((item) => item.id === id));
+  if (unknownIds.length > 0) {
+    throw new Error(`Accepted item ids not present in the offer: ${unknownIds.join(", ")}`);
+  }
+  const accepted = offer.items.filter((item) => acceptedIds.has(item.id)).map((item) => ({
+    id: item.id,
+    kind: item.kind,
+    sourceUrl: item.sourceUrl,
+    trust: item.trust,
+    description: item.description,
+    installHint: item.installHint,
+    versionOrDate: appliedAt.slice(0, 10),
+    mode: "online-ref"
+  }));
+  const prior = readKnowledgeManifest(root);
+  let kitReplace;
+  if (prior.status === "ok") {
+    const priorIds = new Set(prior.manifest.items.map((item) => item.id));
+    const newIds = new Set(accepted.map((item) => item.id));
+    const isProperSubset = newIds.size < priorIds.size && [...newIds].every((id) => priorIds.has(id));
+    if (isProperSubset) {
+      kitReplace = {
+        previousCount: priorIds.size,
+        acceptedCount: newIds.size,
+        droppedCount: priorIds.size - newIds.size
+      };
+    }
+  }
+  const agentsPath = path2.join(root, "AGENTS.md");
+  let existing = "";
+  try {
+    const st = lstatSync(agentsPath);
+    if (!st.isFile()) {
+      throw new Error(
+        "AGENTS.md is not a regular file (symlink or special); refusing to write through it."
+      );
+    }
+    existing = readFileSync2(agentsPath, "utf8");
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? error.code : void 0;
+    if (code !== "ENOENT") throw error;
+  }
+  const block = renderKnowledgeBlock(accepted, appliedAt.slice(0, 10));
+  const updated = upsertKnowledgeBlock(existing, block);
+  const filesTouched = [];
+  if (updated !== existing) {
+    await atomicWriteText(agentsPath, updated, { ensureDir: false });
+  }
+  filesTouched.push("AGENTS.md");
+  const manifest = createManifest(offer.detection.fingerprint, accepted, now);
+  await writeKnowledgeManifest(root, manifest);
+  filesTouched.push(path2.relative(root, knowledgeManifestPath(root)));
+  const installActions = offer.items.filter((item) => acceptedIds.has(item.id) && item.kind === "mcp" && item.installHint).map((item) => ({
+    id: item.id,
+    command: item.installHint,
+    trustNote: trustNoteFor(item)
+  }));
+  const trustSummary = {};
+  for (const item of accepted) {
+    trustSummary[item.trust] = (trustSummary[item.trust] ?? 0) + 1;
+  }
+  const provenance = {
+    kind: "knowledge-apply",
+    schemaVersion: 1,
+    appliedAt,
+    buildVersion: resolveBuildVersion(),
+    stackFingerprint: offer.detection.fingerprint,
+    items: accepted.map((item) => ({
+      id: item.id,
+      kind: item.kind,
+      sourceUrl: item.sourceUrl,
+      trust: item.trust,
+      versionOrDate: item.versionOrDate,
+      mode: item.mode
+    })),
+    filesTouched: [...filesTouched],
+    trustSummary
+  };
+  const provenanceFile = provenancePath(root, appliedAt);
+  await atomicWriteText(provenanceFile, JSON.stringify(provenance, null, 2), {
+    ensureDir: true,
+    trailingNewline: true
+  });
+  filesTouched.push(path2.relative(root, provenanceFile));
+  return {
+    filesTouched,
+    accepted,
+    installActions,
+    provenance,
+    ...kitReplace ? { kitReplace } : {}
+  };
+}
+
+// src/core/knowledge/pending-notice.ts
+import { existsSync as existsSync2, readFileSync as readFileSync3, unlinkSync } from "fs";
+import path3 from "path";
+import { z as z3 } from "zod";
+var PENDING_OFFER_NOTICE_MESSAGE = "Knowledge kit: offer skipped (non-interactive session). Run build init knowledge offer for a headless offer, or re-run build init in a terminal.";
+var PendingOfferNoticeSchema = z3.object({
+  schemaVersion: z3.literal(1),
+  skippedAt: z3.string().min(1),
+  cause: z3.union([z3.literal("non-interactive"), z3.literal("suppressed")]),
+  message: z3.string().min(1)
+});
+function pendingOfferNoticePath(cwd) {
+  return path3.join(cwd, ".build-project", "state", "knowledge", "pending-offer-notice.json");
+}
+function writePendingOfferNotice(cwd, cause) {
+  const notice = {
+    schemaVersion: 1,
+    skippedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    cause,
+    message: PENDING_OFFER_NOTICE_MESSAGE
+  };
+  try {
+    atomicWriteJsonSync(pendingOfferNoticePath(cwd), notice);
+  } catch {
+  }
+}
+function readPendingOfferNotice(cwd) {
+  const filePath = pendingOfferNoticePath(cwd);
+  if (!existsSync2(filePath)) return void 0;
+  try {
+    const parsed = PendingOfferNoticeSchema.safeParse(JSON.parse(readFileSync3(filePath, "utf8")));
+    if (!parsed.success) return void 0;
+    return { ...parsed.data, message: PENDING_OFFER_NOTICE_MESSAGE };
+  } catch {
+    return void 0;
+  }
+}
+function clearPendingOfferNotice(cwd) {
+  try {
+    unlinkSync(pendingOfferNoticePath(cwd));
+  } catch {
+  }
+}
+
+// src/core/context/usage-block.ts
+import { readFileSync as readFileSync4 } from "fs";
+import path4 from "path";
+var USAGE_BLOCK_MARKERS = {
+  begin: "<!-- build-usage:begin -->",
+  end: "<!-- build-usage:end -->"
+};
+function sliceUsageBlock(template, markers = USAGE_BLOCK_MARKERS) {
+  const begin = template.indexOf(markers.begin);
+  const end = template.indexOf(markers.end);
+  if (begin < 0 || end < begin) return void 0;
+  return template.slice(begin, end + markers.end.length);
+}
+var WORK_TRACKING_MARKERS = {
+  begin: "<!-- build-work-tracking:begin -->",
+  end: "<!-- build-work-tracking:end -->"
+};
+function readPackagedUsageBlock(markers = USAGE_BLOCK_MARKERS) {
+  try {
+    const templatePath = path4.join(getPackageRoot(), "templates", "AGENTS.template.md");
+    return sliceUsageBlock(readFileSync4(templatePath, "utf8"), markers);
+  } catch {
+    return void 0;
+  }
+}
+var LEGACY_USAGE_HEADING = /^#{2,3} (?:Build Commands|Running Work Through Build)[ \t]*$/m;
+var LEGACY_USAGE_REASON = 'AGENTS.md already has an older Build guide without markers ("Build Commands", "Running Work Through Build"); delete those sections, then run build config context apply to install the current guide.';
+function hasLegacyUsageGuide(agentsContent) {
+  return !agentsContent.includes(USAGE_BLOCK_MARKERS.begin) && LEGACY_USAGE_HEADING.test(agentsContent);
+}
+function upsertUsageBlock(agentsContent) {
+  if (hasLegacyUsageGuide(agentsContent)) return agentsContent;
+  const fragment = readPackagedUsageBlock();
+  if (fragment === void 0) {
+    throw new Error("Usage block missing from the packaged AGENTS template.");
+  }
+  return upsertManagedBlock(agentsContent, fragment, USAGE_BLOCK_MARKERS);
+}
+function installUsageBlockIfAbsent(agentsContent) {
+  if (agentsContent.includes(USAGE_BLOCK_MARKERS.begin) || agentsContent.includes(USAGE_BLOCK_MARKERS.end)) {
+    return agentsContent;
+  }
+  return upsertUsageBlock(agentsContent);
+}
+
+// src/core/context/fabric.ts
+import { lstatSync as lstatSync3, readFileSync as readFileSync7 } from "fs";
+import path7 from "path";
+
+// src/core/knowledge/actions.ts
+import { randomBytes } from "crypto";
+import { existsSync as existsSync3, lstatSync as lstatSync2, readdirSync, readFileSync as readFileSync5, unlinkSync as unlinkSync2 } from "fs";
+import path5 from "path";
+import { z as z4 } from "zod";
+var KNOWLEDGE_NEXT_ACTION_HINT = "Next: build init knowledge offer mints a review token; accept <token> all applies the kit.";
+var GRADUATION_ELIGIBLE_NO_MANIFEST_HINT = "Fully satisfied \u2014 run build init knowledge offer, then accept <token> all to apply the kit, then graduate <token> (or build init interactively).";
+var GRADUATION_ELIGIBLE_HINT = "Fully satisfied \u2014 run build init knowledge offer, then accept <token> all, then graduate <token> (or build init interactively).";
+function knowledgeStatus(cwd) {
+  const detection = detectStack(cwd);
+  const stored = readIntentContract(cwd);
+  let contract;
+  let effective = detection;
+  if (stored.status === "absent") {
+    contract = { status: "absent" };
+  } else if (stored.status === "invalid") {
+    contract = { status: "invalid", error: stored.error };
+  } else if (stored.contract.status === "retired") {
+    contract = {
+      status: "ok",
+      spec: stored.contract.spec,
+      declaredAt: stored.contract.declaredAt,
+      ...stored.contract.rationale ? { rationale: stored.contract.rationale } : {},
+      contractStatus: "retired",
+      dimensions: stored.contract.dimensions.map(describeDim),
+      conflicts: [],
+      graduationEligible: false
+    };
+  } else {
+    const resolution = resolveIntent(detection, stored.contract);
+    effective = resolution.effective;
+    contract = {
+      status: "ok",
+      spec: stored.contract.spec,
+      declaredAt: stored.contract.declaredAt,
+      ...stored.contract.rationale ? { rationale: stored.contract.rationale } : {},
+      contractStatus: resolution.contract.status,
+      dimensions: resolution.contract.dimensions.map(describeDim),
+      conflicts: resolution.conflicts.map((c) => ({
+        token: c.dimension.token,
+        detectedToken: c.detectedToken
+      })),
+      graduationEligible: isGraduationEligible(resolution)
+    };
+  }
+  const manifestResult = readKnowledgeManifest(cwd);
+  let manifest;
+  if (manifestResult.status === "absent") {
+    manifest = { status: "absent" };
+  } else if (manifestResult.status === "invalid") {
+    manifest = { status: "invalid", error: manifestResult.error };
+  } else {
+    manifest = {
+      status: "ok",
+      stackFingerprint: manifestResult.manifest.stackFingerprint,
+      itemCount: manifestResult.manifest.items.length,
+      updatedAt: manifestResult.manifest.updatedAt,
+      drifted: manifestResult.manifest.stackFingerprint !== effective.fingerprint
+    };
+  }
+  const liveNoManifest = contract.status === "ok" && contract.contractStatus !== "retired" && manifest.status === "absent";
+  const graduationGuidance = contract.status === "ok" && contract.graduationEligible ? manifest.status === "absent" ? GRADUATION_ELIGIBLE_NO_MANIFEST_HINT : GRADUATION_ELIGIBLE_HINT : void 0;
+  return {
+    detection: {
+      languages: detection.languages.filter((l) => l !== "unknown" && l !== "docs"),
+      frameworks: detection.frameworks,
+      sdkTargets: detection.sdkTargets,
+      tools: detection.tools ?? [],
+      domains: detection.domains ?? [],
+      fingerprint: detection.fingerprint
+    },
+    contract,
+    manifest,
+    ...liveNoManifest ? { nextAction: KNOWLEDGE_NEXT_ACTION_HINT } : {},
+    ...graduationGuidance ? { graduationGuidance } : {}
+  };
+}
+function computeKnowledgeProjection(cwd, existingContent) {
+  const manifestResult = readKnowledgeManifest(cwd);
+  if (manifestResult.status === "ok") {
+    const block = renderKnowledgeBlock(
+      manifestResult.manifest.items,
+      manifestResult.manifest.updatedAt.slice(0, 10)
+    );
+    return { kind: "upsert", block };
+  }
+  if (manifestResult.status === "invalid") {
+    return { kind: "none" };
+  }
+  const stored = readIntentContract(cwd);
+  const liveContract = stored.status === "ok" && stored.contract.status !== "retired" ? stored.contract : void 0;
+  if (liveContract) {
+    const resolved = resolveIntent(detectStack(cwd), liveContract).contract;
+    const liveDimensions = resolved.dimensions.filter((d) => d.status !== "retired").length;
+    return { kind: "upsert", block: renderPendingIntentBlock(liveDimensions) };
+  }
+  if (blockIsPendingIntent(existingContent)) {
+    return { kind: "remove" };
+  }
+  return { kind: "none" };
+}
+function describeDim(dim) {
+  return {
+    token: dim.token,
+    dimension: dim.dimension,
+    status: dim.status,
+    ...dim.conflict ? { conflict: dim.conflict } : {}
+  };
+}
+function isGraduationEligible(resolution) {
+  const hasSatisfiedDim = resolution.contract.dimensions.some((d) => d.status === "satisfied");
+  return resolution.allSatisfied && (hasSatisfiedDim || resolution.allCovered);
+}
+function effectiveDetection(cwd) {
+  migrateLegacyDeclaration(cwd);
+  const detection = detectStack(cwd);
+  const stored = readIntentContract(cwd);
+  if (stored.status !== "ok" || stored.contract.status === "retired") {
+    return detection;
+  }
+  return resolveIntent(detection, stored.contract).effective;
+}
+function syncPendingIntentBlock(cwd) {
+  try {
+    const agentsPath = path5.join(cwd, "AGENTS.md");
+    if (!existsSync3(agentsPath) || !lstatSync2(agentsPath).isFile()) {
+      return;
+    }
+    if (readKnowledgeManifest(cwd).status !== "absent") return;
+    const stored = readIntentContract(cwd);
+    const liveContract = stored.status === "ok" && stored.contract.status !== "retired" ? stored.contract : void 0;
+    const existing = readFileSync5(agentsPath, "utf8");
+    if (liveContract) {
+      const resolved = resolveIntent(detectStack(cwd), liveContract).contract;
+      const liveDimensions = resolved.dimensions.filter((d) => d.status !== "retired").length;
+      const block = renderPendingIntentBlock(liveDimensions);
+      const updated = upsertKnowledgeBlock(existing, block);
+      if (updated !== existing) {
+        atomicWriteTextSync(agentsPath, updated, { ensureDir: false });
+      }
+      return;
+    }
+    if (blockIsPendingIntent(existing)) {
+      const updated = removeKnowledgeBlock(existing);
+      if (updated !== existing) {
+        atomicWriteTextSync(agentsPath, updated, { ensureDir: false });
+      }
+    }
+  } catch {
+  }
+}
+function declareIntent(cwd, spec, reason) {
+  const parsed = parseIntentSpec(spec);
+  if (!parsed.ok) {
+    return { ok: false, error: parsed.error };
+  }
+  try {
+    unlinkSync2(legacyDeclaredStackPath(cwd));
+  } catch {
+  }
+  const candidate = createIntentContract(spec, parsed.tokens, { rationale: reason });
+  const detection = detectStack(cwd);
+  const probe = resolveIntent(detection, candidate);
+  if (probe.allCovered) {
+    removeIntentContract(cwd);
+    syncPendingIntentBlock(cwd);
+    return { ok: true, outcome: "covered", spec, conflicts: [] };
+  }
+  writeIntentContract(cwd, probe.contract);
+  syncPendingIntentBlock(cwd);
+  return {
+    ok: true,
+    outcome: "stored",
+    spec,
+    conflicts: probe.conflicts.map((c) => ({
+      token: c.dimension.token,
+      detectedToken: c.detectedToken
+    }))
+  };
+}
+function clearIntent(cwd) {
+  const stored = readIntentContract(cwd);
+  let cleared = false;
+  if (stored.status !== "absent") {
+    removeIntentContract(cwd);
+    cleared = true;
+  }
+  try {
+    unlinkSync2(legacyDeclaredStackPath(cwd));
+    cleared = true;
+  } catch {
+  }
+  syncPendingIntentBlock(cwd);
+  return { cleared };
+}
+function resolveConflicts(cwd, choice) {
+  const stored = readIntentContract(cwd);
+  if (stored.status === "absent") {
+    return { ok: false, error: "No stack intent contract to resolve conflicts on." };
+  }
+  if (stored.status === "invalid") {
+    return {
+      ok: false,
+      error: `Stack intent contract is invalid (${stored.error}); re-declare or clear it first.`
+    };
+  }
+  const resolution = resolveIntent(detectStack(cwd), stored.contract);
+  const pending = resolution.conflicts.length;
+  if (pending === 0) {
+    return { ok: false, error: "No pending conflicts to resolve." };
+  }
+  const updated = choice === "keep" ? acknowledgeConflicts(resolution.contract) : acceptDetectedReality(resolution.contract);
+  writeIntentContract(cwd, updated);
+  syncPendingIntentBlock(cwd);
+  return { ok: true, resolvedCount: pending, choice };
+}
+function pendingOffersDir(cwd) {
+  return path5.join(cwd, ".build-project", "state", "knowledge", "pending-offers");
+}
+var PENDING_OFFER_TTL_MS = 60 * 60 * 1e3;
+var PendingOfferSchema = z4.object({
+  schemaVersion: z4.literal(1),
+  token: z4.string().min(1),
+  /** Repo root the offer was built for (guards cross-repo token reuse). */
+  root: z4.string().min(1),
+  stackFingerprint: z4.string().min(1),
+  guidance: z4.string().optional(),
+  createdAt: z4.string().min(1),
+  /** True when search was unavailable — an offline offer NEVER counts as a review. */
+  offline: z4.boolean(),
+  items: z4.array(KitItemSchema),
+  messages: z4.array(z4.string()),
+  /** Set by acceptOffer; a consumed offer still gates graduation until TTL. */
+  consumedAt: z4.string().optional()
+});
+var TOKEN_PATTERN = /^[a-f0-9]{32}$/;
+function pendingOfferPath(cwd, token) {
+  return path5.join(pendingOffersDir(cwd), `${token}.json`);
+}
+function readPendingOffer(cwd, token) {
+  if (!TOKEN_PATTERN.test(token)) return void 0;
+  const filePath = pendingOfferPath(cwd, token);
+  if (!existsSync3(filePath)) return void 0;
+  try {
+    const parsed = PendingOfferSchema.safeParse(JSON.parse(readFileSync5(filePath, "utf8")));
+    return parsed.success ? parsed.data : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function offerExpired(offer, now) {
+  const created = Date.parse(offer.createdAt);
+  return !Number.isFinite(created) || now.getTime() - created > PENDING_OFFER_TTL_MS;
+}
+function cleanupExpiredOffers(cwd, now) {
+  const dir = pendingOffersDir(cwd);
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) continue;
+    const token = entry.slice(0, -".json".length);
+    if (!TOKEN_PATTERN.test(token)) continue;
+    const offer = readPendingOffer(cwd, token);
+    if (!offer || offerExpired(offer, now)) {
+      try {
+        unlinkSync2(path5.join(dir, entry));
+      } catch {
+      }
+    }
+  }
+}
+async function createOffer(cwd, options) {
+  const now = options.now?.() ?? /* @__PURE__ */ new Date();
+  cleanupExpiredOffers(cwd, now);
+  const offer = await buildKitOffer(cwd, {
+    provider: options.provider,
+    cache: options.cache,
+    refresh: options.refresh,
+    userGuidance: options.guidance,
+    detection: effectiveDetection(cwd)
+  });
+  if (offer.offline) {
+    return {
+      offline: true,
+      source: offer.source,
+      items: [],
+      messages: offer.messages,
+      detectionFingerprint: offer.detection.fingerprint
+    };
+  }
+  const token = randomBytes(16).toString("hex");
+  const pending = {
+    schemaVersion: 1,
+    token,
+    root: offer.detection.root,
+    stackFingerprint: offer.detection.fingerprint,
+    ...options.guidance ? { guidance: options.guidance } : {},
+    createdAt: now.toISOString(),
+    offline: false,
+    items: offer.items,
+    messages: offer.messages
+  };
+  await atomicWriteJson(pendingOfferPath(cwd, token), pending);
+  clearPendingOfferNotice(cwd);
+  return {
+    token,
+    offline: false,
+    source: offer.source,
+    items: offer.items,
+    messages: offer.messages,
+    detectionFingerprint: offer.detection.fingerprint
+  };
+}
+async function acceptOffer(cwd, token, itemIds, options = {}) {
+  const now = options.now?.() ?? /* @__PURE__ */ new Date();
+  const pending = readPendingOffer(cwd, token);
+  if (!pending) {
+    return { ok: false, error: "Unknown or malformed offer token; run knowledge offer again." };
+  }
+  if (path5.resolve(pending.root) !== path5.resolve(cwd)) {
+    return {
+      ok: false,
+      error: "Offer token was minted for a different repository root; run knowledge offer again."
+    };
+  }
+  if (pending.consumedAt) {
+    return { ok: false, error: "Offer already accepted; run knowledge offer again for a new one." };
+  }
+  if (offerExpired(pending, now)) {
+    return { ok: false, error: "Offer expired; run knowledge offer again." };
+  }
+  const detection = effectiveDetection(cwd);
+  if (detection.fingerprint !== pending.stackFingerprint) {
+    return {
+      ok: false,
+      error: "The effective stack changed since the offer was created; run knowledge offer again."
+    };
+  }
+  const acceptedIds = itemIds === "all" ? pending.items.map((item) => item.id) : itemIds;
+  if (acceptedIds.length === 0) {
+    if (itemIds === "all" && pending.items.length === 0) {
+      await atomicWriteJson(pendingOfferPath(cwd, token), {
+        ...pending,
+        consumedAt: now.toISOString()
+      });
+      return {
+        ok: true,
+        applied: {
+          filesTouched: [],
+          accepted: [],
+          installActions: [],
+          provenance: {
+            kind: "knowledge-apply",
+            schemaVersion: 1,
+            appliedAt: now.toISOString(),
+            buildVersion: resolveBuildVersion(),
+            stackFingerprint: pending.stackFingerprint,
+            items: [],
+            filesTouched: [],
+            trustSummary: {}
+          }
+        }
+      };
+    }
+    return { ok: false, error: "No items selected; pass item ids or all." };
+  }
+  const offer = {
+    detection,
+    items: pending.items,
+    source: "cache",
+    offline: false,
+    messages: pending.messages
+  };
+  let applied;
+  try {
+    applied = await applyKit(offer, acceptedIds, { now: () => now });
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+  await atomicWriteJson(pendingOfferPath(cwd, token), {
+    ...pending,
+    consumedAt: now.toISOString()
+  });
+  return { ok: true, applied };
+}
+async function graduateIntent(cwd, token, options = {}) {
+  const now = options.now?.() ?? /* @__PURE__ */ new Date();
+  const pending = readPendingOffer(cwd, token);
+  if (!pending || pending.offline) {
+    return {
+      ok: false,
+      error: "Graduation requires a token from a successful knowledge offer that has been accepted; run knowledge offer, then accept, then graduate."
+    };
+  }
+  if (path5.resolve(pending.root) !== path5.resolve(cwd)) {
+    return {
+      ok: false,
+      error: "Offer token was minted for a different repository root; run knowledge offer again."
+    };
+  }
+  if (offerExpired(pending, now)) {
+    return { ok: false, error: "Offer token expired; run knowledge offer again." };
+  }
+  migrateLegacyDeclaration(cwd);
+  const stored = readIntentContract(cwd);
+  if (stored.status === "absent") {
+    return { ok: false, error: "No stack intent contract to graduate." };
+  }
+  if (stored.status === "invalid") {
+    return {
+      ok: false,
+      error: `Stack intent contract is invalid (${stored.error}); re-declare or clear it first.`
+    };
+  }
+  if (stored.contract.status === "retired") {
+    return { ok: false, error: "Stack intent contract is already retired." };
+  }
+  const detection = detectStack(cwd);
+  const resolution = resolveIntent(detection, stored.contract, { now: () => now });
+  if (resolution.effective.fingerprint !== pending.stackFingerprint) {
+    return {
+      ok: false,
+      error: "The effective stack changed since the offer was created; run knowledge offer again before graduating."
+    };
+  }
+  if (!isGraduationEligible(resolution)) {
+    const unsatisfied = resolution.contract.dimensions.filter(
+      (d) => d.status !== "satisfied" && d.status !== "retired" && !(d.status === "conflict" && d.conflict?.acknowledged === true)
+    ).map((d) => d.token);
+    return {
+      ok: false,
+      error: `Stack intent "${stored.contract.spec}" is not fully satisfied yet (pending: ${unsatisfied.join(", ") || "evidence of detection catch-up"}).`
+    };
+  }
+  if (!pending.consumedAt) {
+    return {
+      ok: false,
+      error: "Graduation requires the offer to be accepted first; run build init knowledge accept <token> all, then graduate."
+    };
+  }
+  const manifestResult = readKnowledgeManifest(cwd);
+  if (pending.items.length > 0) {
+    if (manifestResult.status === "absent") {
+      return {
+        ok: false,
+        error: "Graduation requires an accepted knowledge kit (manifest missing); run build init knowledge accept <token> all, then graduate."
+      };
+    }
+    if (manifestResult.status === "invalid") {
+      return {
+        ok: false,
+        error: `Knowledge manifest is invalid (${manifestResult.error}); re-run build init knowledge accept before graduating.`
+      };
+    }
+  }
+  let manifestReconfirmed = false;
+  const effectiveFingerprint = resolution.effective.fingerprint;
+  if (manifestResult.status === "ok" && manifestResult.manifest.stackFingerprint !== effectiveFingerprint) {
+    const reconfirmed = {
+      ...manifestResult.manifest,
+      stackFingerprint: effectiveFingerprint,
+      updatedAt: now.toISOString()
+    };
+    await writeKnowledgeManifest(cwd, reconfirmed);
+    manifestReconfirmed = true;
+  }
+  writeIntentContract(cwd, retireContract(resolution.contract, { now: () => now }));
+  try {
+    unlinkSync2(pendingOfferPath(cwd, token));
+  } catch {
+  }
+  syncPendingIntentBlock(cwd);
+  return { ok: true, spec: stored.contract.spec, manifestReconfirmed };
+}
+
+// src/core/context/service/render-service-block.ts
+var SERVICE_BLOCK_MARKERS = {
+  begin: "<!-- build-context-service:begin -->",
+  end: "<!-- build-context-service:end -->"
+};
+var KNOWN_MANAGED_BLOCK_MARKERS = [
+  SERVICE_BLOCK_MARKERS.begin,
+  SERVICE_BLOCK_MARKERS.end,
+  STACK_BLOCK_MARKERS.begin,
+  STACK_BLOCK_MARKERS.end,
+  PURPOSE_BLOCK_MARKERS.begin,
+  PURPOSE_BLOCK_MARKERS.end,
+  KNOWLEDGE_BLOCK_BEGIN,
+  KNOWLEDGE_BLOCK_END,
+  USAGE_BLOCK_MARKERS.begin,
+  USAGE_BLOCK_MARKERS.end
+];
+function fragmentEmbedsManagedMarker(fragment, ownMarkers) {
+  let interior = fragment;
+  if (interior.startsWith(ownMarkers.begin)) {
+    interior = interior.slice(ownMarkers.begin.length);
+  }
+  if (interior.endsWith(ownMarkers.end)) {
+    interior = interior.slice(0, interior.length - ownMarkers.end.length);
+  }
+  return KNOWN_MANAGED_BLOCK_MARKERS.some((marker) => interior.includes(marker));
+}
+function renderServiceContextBlock(entries) {
+  const lines = ["## Service context (managed by Build)", ""];
+  const inlined = entries.filter((entry) => entry.inline);
+  if (inlined.length === 0) {
+    lines.push("No inlined service context entries.");
+  } else {
+    for (const entry of inlined) {
+      lines.push(`### ${entry.title}`);
+      lines.push(`Source: ${entry.source} (captured ${entry.capturedAt})`);
+      lines.push("");
+      lines.push(entry.body.replace(/\s+$/, ""));
+      lines.push("");
+    }
+  }
+  lines.push(
+    "Do not edit inside this block \u2014 it is regenerated by `build config context apply`. Entries live in .build-project/context/service/."
+  );
+  return lines.join("\n");
+}
+function renderServiceBlockFragment(entries) {
+  const content = renderServiceContextBlock(entries);
+  if (KNOWN_MANAGED_BLOCK_MARKERS.some((marker) => content.includes(marker))) {
+    throw new Error(
+      "Service block content contains a managed-block marker string; refusing to render a self-corrupting block."
+    );
+  }
+  return [SERVICE_BLOCK_MARKERS.begin, content, SERVICE_BLOCK_MARKERS.end].join("\n");
+}
+
+// src/core/context/service/store.ts
+import { randomBytes as randomBytes2 } from "crypto";
+import { existsSync as existsSync4, readdirSync as readdirSync2, readFileSync as readFileSync6 } from "fs";
+import { link, mkdir, unlink, writeFile } from "fs/promises";
+import path6 from "path";
+import * as YAML from "yaml";
+
+// src/core/context/service/schema.ts
+import { z as z5 } from "zod";
+var ServiceEntryFrontmatterSchema = z5.object({
+  /**
+   * Slug id; MUST equal the filename stem AND satisfy the finite-grammar
+   * identifier — the same grammar the id is derived under. A hand-edited entry
+   * whose id is prose (e.g. `ignore previous instructions`) fails here and is
+   * skipped, so it can never be surfaced or inlined.
+   */
+  id: z5.string().min(1).refine(isSafeStackIdentifier, {
+    message: "id must be a finite-grammar-safe identifier"
+  }),
+  /** Human title of the entry. */
+  title: z5.string().min(1),
+  /** Free-text reference to the origin (URL, path, or title). */
+  source: z5.string().min(1),
+  /** ISO datetime the entry was captured (auto-set on add). */
+  capturedAt: z5.string().datetime(),
+  /** Optional free-text author note (from `--by`); NOT a git identity. */
+  capturedBy: z5.string().min(1).optional(),
+  /** Builder's destination choice: when true, the body is projected into AGENTS.md. */
+  inline: z5.boolean()
+});
+
+// src/core/context/service/store.ts
+var SERVICE_DIR = path6.join(CONTEXT_DIR, "service");
+function serviceDir(root) {
+  return path6.join(root, SERVICE_DIR);
+}
+function serviceEntryPath(root, id) {
+  return path6.join(serviceDir(root), `${id}.md`);
+}
+function slugifyTitle(title) {
+  return title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64).replace(/-+$/g, "");
+}
+function shortHash(seed) {
+  let h = 0;
+  for (let i = 0; i < seed.length; i++) {
+    h = h * 31 + seed.charCodeAt(i) >>> 0;
+  }
+  return h.toString(36).slice(0, 8);
+}
+function deriveEntryId(title, existingIds) {
+  let base = slugifyTitle(title);
+  if (!isSafeStackIdentifier(base)) {
+    base = `service-${shortHash(title)}`;
+  }
+  if (!existingIds.has(base)) return base;
+  for (let n = 2; ; n++) {
+    const suffix = `-${n}`;
+    const candidate = `${base.slice(0, 64 - suffix.length)}${suffix}`;
+    if (isSafeStackIdentifier(candidate) && !existingIds.has(candidate)) return candidate;
+  }
+}
+function occupiedEntryIds(root) {
+  const dir = serviceDir(root);
+  if (!existsSync4(dir)) return /* @__PURE__ */ new Set();
+  try {
+    return new Set(
+      readdirSync2(dir).filter((f) => f.toLowerCase().endsWith(".md")).map((f) => f.slice(0, -".md".length).toLowerCase())
+    );
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function parseEntryFile(content) {
+  const normalized = content.replace(/\r\n/g, "\n");
+  const lines = normalized.split("\n");
+  if (lines[0]?.trim() !== "---") return void 0;
+  let closingLine = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i]?.trim() === "---") {
+      closingLine = i;
+      break;
+    }
+  }
+  if (closingLine === -1) return void 0;
+  const yamlText = lines.slice(1, closingLine).join("\n");
+  const body = lines.slice(closingLine + 1).join("\n");
+  let frontmatter;
+  try {
+    frontmatter = YAML.parse(yamlText);
+  } catch {
+    return void 0;
+  }
+  return { frontmatter, body };
+}
+function listServiceEntries(root, options = {}) {
+  const dir = serviceDir(root);
+  let files;
+  try {
+    files = readdirSync2(dir).filter((f) => f.endsWith(".md"));
+  } catch (error) {
+    if (options.requireComplete && error.code !== "ENOENT") throw error;
+    return [];
+  }
+  const entries = [];
+  for (const file of files.sort()) {
+    try {
+      const raw = readFileSync6(path6.join(dir, file), "utf8");
+      const parsed = parseEntryFile(raw);
+      if (!parsed) throw new Error(`Invalid service entry: ${file}`);
+      const result = ServiceEntryFrontmatterSchema.safeParse(parsed.frontmatter);
+      if (!result.success) throw new Error(`Invalid service entry: ${file}`);
+      const frontmatter = result.data;
+      if (file.slice(0, -".md".length) !== frontmatter.id)
+        throw new Error(`Service entry ID mismatch: ${file}`);
+      entries.push({ ...frontmatter, body: parsed.body });
+    } catch (error) {
+      if (options.requireComplete) throw error;
+    }
+  }
+  return entries;
+}
+function serializeEntry(entry) {
+  const { body, ...frontmatter } = entry;
+  const ordered = {
+    id: frontmatter.id,
+    title: frontmatter.title,
+    source: frontmatter.source,
+    capturedAt: frontmatter.capturedAt,
+    ...frontmatter.capturedBy !== void 0 ? { capturedBy: frontmatter.capturedBy } : {},
+    inline: frontmatter.inline
+  };
+  const yamlText = YAML.stringify(ordered, { lineWidth: 0 }).trimEnd();
+  return `---
+${yamlText}
+---
+${body}`;
+}
+async function addServiceEntry(root, input) {
+  const now = input.now ?? (() => /* @__PURE__ */ new Date());
+  const id = deriveEntryId(input.title, occupiedEntryIds(root));
+  const frontmatter = ServiceEntryFrontmatterSchema.parse({
+    id,
+    title: input.title,
+    source: input.source,
+    capturedAt: now().toISOString(),
+    ...input.capturedBy !== void 0 ? { capturedBy: input.capturedBy } : {},
+    inline: input.inline
+  });
+  const entry = { ...frontmatter, body: input.body };
+  const targetEntryPath = serviceEntryPath(root, id);
+  const payload = `${serializeEntry(entry)}
+`;
+  const dir = path6.dirname(targetEntryPath);
+  await mkdir(dir, { recursive: true });
+  const tempPath = path6.join(dir, `.tmp.${process.pid}.${randomBytes2(8).toString("hex")}`);
+  try {
+    await writeFile(tempPath, payload, { encoding: "utf8", flag: "wx" });
+    try {
+      await link(tempPath, targetEntryPath);
+    } catch (error) {
+      if (error.code === "EEXIST") {
+        throw new Error(
+          `Refusing to overwrite an existing service entry file at ${path6.basename(targetEntryPath)}.`
+        );
+      }
+      throw error;
+    }
+  } finally {
+    await unlink(tempPath).catch(() => {
+    });
+  }
+  return { entry, entryPath: targetEntryPath };
+}
+
+// src/core/context/fabric.ts
+var STACK_BLOCK_MARKERS2 = {
+  begin: STACK_BLOCK_MARKERS.begin,
+  end: STACK_BLOCK_MARKERS.end
+};
+var KNOWLEDGE_BLOCK_MARKERS2 = {
+  begin: KNOWLEDGE_BLOCK_BEGIN,
+  end: KNOWLEDGE_BLOCK_END
+};
+function classifyAgentsFile(root) {
+  try {
+    return lstatSync3(path7.join(root, "AGENTS.md")).isFile() ? "regular" : "non-regular";
+  } catch {
+    return "missing";
+  }
+}
+var AGENTS_UNAVAILABLE_REASONS = {
+  missing: "AGENTS.md is missing; run `build init` to create it. Build never creates AGENTS.md here.",
+  "non-regular": "AGENTS.md is not a regular file (directory or symlink); Build will not write through it.",
+  unreadable: "AGENTS.md could not be read; check its permissions."
+};
+function readAgents(root) {
+  const kind = classifyAgentsFile(root);
+  if (kind !== "regular") return { kind: "unavailable", cause: kind };
+  try {
+    return { kind: "ok", content: readFileSync7(path7.join(root, "AGENTS.md"), "utf8") };
+  } catch {
+    return { kind: "unavailable", cause: "unreadable" };
+  }
+}
+function expectedFragment(root, block, existingContent) {
+  if (block === "stack") {
+    const detection = resolvedStackDetection(root);
+    const fragment = [
+      STACK_BLOCK_MARKERS2.begin,
+      renderStackAgentsBlock(detection),
+      STACK_BLOCK_MARKERS2.end
+    ].join("\n");
+    return { present: true, fragment };
+  }
+  if (block === "knowledge") {
+    const projection = computeKnowledgeProjection(root, existingContent);
+    if (projection.kind === "upsert") return { present: true, fragment: projection.block };
+    if (projection.kind === "remove") return { present: false };
+    return knowledgeManifestIsInvalid(root) ? { present: "unrenderable" } : { present: false };
+  }
+  if (block === "usage") {
+    const fragment = readPackagedUsageBlock();
+    return fragment === void 0 ? { present: "unrenderable" } : { present: true, fragment };
+  }
+  let entries;
+  try {
+    entries = listServiceEntries(root, { requireComplete: true });
+  } catch {
+    return { present: "unrenderable" };
+  }
+  try {
+    const inlined = entries.filter((e) => e.inline);
+    if (inlined.length === 0) return { present: false };
+    return { present: true, fragment: renderServiceBlockFragment(entries) };
+  } catch {
+    return { present: "error" };
+  }
+}
+function knowledgeManifestIsInvalid(root) {
+  return readKnowledgeManifest(root).status === "invalid";
+}
+function readOnDiskFragment(content, markers) {
+  const beginIndex = content.indexOf(markers.begin);
+  const endIndex = content.indexOf(markers.end);
+  if (beginIndex === -1 && endIndex === -1) return { state: "absent" };
+  if (beginIndex === -1 || endIndex === -1 || endIndex < beginIndex) return { state: "malformed" };
+  return { state: "present", fragment: content.slice(beginIndex, endIndex + markers.end.length) };
+}
+function markersFor(block) {
+  if (block === "stack") return STACK_BLOCK_MARKERS2;
+  if (block === "knowledge") return KNOWLEDGE_BLOCK_MARKERS2;
+  if (block === "usage") return USAGE_BLOCK_MARKERS;
+  return { begin: SERVICE_BLOCK_MARKERS.begin, end: SERVICE_BLOCK_MARKERS.end };
+}
+var BLOCK_ORDER = ["stack", "knowledge", "service", "usage"];
+var MALFORMED_MARKER_REASON = "managed-block markers are unpaired or out of order; left untouched.";
+var MARKER_IN_FRAGMENT_REASON = "rendered content contains a managed-block marker string; left untouched.";
+var KNOWLEDGE_UNREADABLE_REASON = "knowledge manifest is present but unreadable; block left as-is (repair the manifest).";
+var UNRENDERABLE_REASONS = {
+  stack: KNOWLEDGE_UNREADABLE_REASON,
+  knowledge: KNOWLEDGE_UNREADABLE_REASON,
+  service: "Stored service context is unreadable or invalid; existing guidance is preserved.",
+  usage: "The packaged usage guide is unreadable; existing guidance is preserved."
+};
+function computeContextPlan(root, agents) {
+  if (agents.kind === "unavailable") {
+    return BLOCK_ORDER.map((block) => ({
+      block,
+      status: "agents-unavailable",
+      action: "skip",
+      reason: AGENTS_UNAVAILABLE_REASONS[agents.cause]
+    }));
+  }
+  return BLOCK_ORDER.map((block) => {
+    const markers = markersFor(block);
+    const onDisk = readOnDiskFragment(agents.content, markers);
+    if (onDisk.state === "malformed") {
+      return {
+        block,
+        status: "markers-malformed",
+        action: "skip",
+        reason: MALFORMED_MARKER_REASON
+      };
+    }
+    const expected = expectedFragment(root, block, agents.content);
+    if (expected.present === "error") {
+      return {
+        block,
+        status: "markers-malformed",
+        action: "skip",
+        reason: MARKER_IN_FRAGMENT_REASON
+      };
+    }
+    if (expected.present === "unrenderable") {
+      return onDisk.state === "present" ? {
+        block,
+        status: "needs-attention",
+        action: "nothing",
+        reason: UNRENDERABLE_REASONS[block]
+      } : { block, status: "not-applicable", action: "nothing" };
+    }
+    if (expected.present === false) {
+      return onDisk.state === "present" ? { block, status: "stale", action: "remove" } : { block, status: "not-applicable", action: "nothing" };
+    }
+    if (fragmentEmbedsManagedMarker(expected.fragment, markers)) {
+      return {
+        block,
+        status: "markers-malformed",
+        action: "skip",
+        reason: MARKER_IN_FRAGMENT_REASON
+      };
+    }
+    if (onDisk.state === "absent") {
+      if (block === "usage" && hasLegacyUsageGuide(agents.content)) {
+        return { block, status: "needs-attention", action: "skip", reason: LEGACY_USAGE_REASON };
+      }
+      return {
+        block,
+        status: block === "usage" ? "not-installed" : "stale",
+        action: "upsert",
+        fragment: expected.fragment
+      };
+    }
+    return onDisk.fragment === expected.fragment ? { block, status: "in-sync", action: "nothing", fragment: expected.fragment } : { block, status: "stale", action: "upsert", fragment: expected.fragment };
+  });
+}
+var KNOWLEDGE_POINTER = "knowledge: manage with `build init knowledge ...`";
+function buildContextView(root) {
+  const agents = readAgents(root);
+  const status = knowledgeStatus(root);
+  const entries = listServiceEntries(root);
+  const detection = resolvedStackDetection(root);
+  const contractStatus = status.contract.status === "ok" ? status.contract.contractStatus : status.contract.status;
+  return {
+    stack: {
+      // Match init/apply exactly, including detection outcome tokens.
+      languages: detection.languages,
+      frameworks: detection.frameworks,
+      sdkTargets: detection.sdkTargets,
+      tools: detection.tools ?? [],
+      domains: detection.domains ?? []
+    },
+    knowledge: {
+      contractStatus,
+      manifestStatus: status.manifest.status,
+      itemCount: status.manifest.status === "ok" ? status.manifest.itemCount : 0
+    },
+    service: {
+      count: entries.length,
+      inlineCount: entries.filter((e) => e.inline).length,
+      entries: entries.map((e) => ({ id: e.id, title: e.title, inline: e.inline }))
+    },
+    // Render the SAME plan apply executes, so view and apply never disagree.
+    blocks: computeContextPlan(root, agents).map(
+      (plan) => ({
+        block: plan.block,
+        status: plan.status,
+        ...plan.reason ? { reason: plan.reason } : {}
+      })
+    ),
+    agentsAvailable: agents.kind === "ok",
+    knowledgePointer: KNOWLEDGE_POINTER
+  };
+}
+function listStaleManagedBlocks(root) {
+  const agents = readAgents(root);
+  if (agents.kind !== "ok") return [];
+  return computeContextPlan(root, agents).filter(
+    (plan) => plan.status === "stale" && readOnDiskFragment(agents.content, markersFor(plan.block)).state === "present"
+  ).map((plan) => plan.block);
+}
+async function applyContext(root, options = {}) {
+  const agents = readAgents(root);
+  const plan = computeContextPlan(root, agents).filter(
+    (step) => step.block !== "usage" || options.includeUsage !== false
+  );
+  if (agents.kind === "unavailable") {
+    return {
+      agentsUnavailable: true,
+      wrote: false,
+      outcomes: plan.map((p) => ({
+        block: p.block,
+        result: "skipped",
+        reason: p.reason ?? "AGENTS.md is absent or not a regular file."
+      }))
+    };
+  }
+  let working = agents.content;
+  const outcomes = [];
+  for (const step of plan) {
+    const markers = markersFor(step.block);
+    switch (step.action) {
+      case "skip":
+        outcomes.push({
+          block: step.block,
+          result: "skipped",
+          reason: step.reason ?? MALFORMED_MARKER_REASON
+        });
+        break;
+      case "nothing":
+        outcomes.push({
+          block: step.block,
+          result: step.status === "in-sync" ? "already-in-sync" : "nothing-to-project"
+        });
+        break;
+      case "remove": {
+        const next = removeManagedBlock(working, markers);
+        if (next !== working) {
+          working = next;
+          outcomes.push({ block: step.block, result: "updated" });
+        } else {
+          outcomes.push({ block: step.block, result: "nothing-to-project" });
+        }
+        break;
+      }
+      case "upsert": {
+        try {
+          const next = upsertManagedBlock(working, step.fragment, markers);
+          if (next === working) {
+            outcomes.push({ block: step.block, result: "already-in-sync" });
+          } else {
+            working = next;
+            outcomes.push({ block: step.block, result: "updated" });
+          }
+        } catch {
+          outcomes.push({
+            block: step.block,
+            result: "skipped",
+            reason: MALFORMED_MARKER_REASON
+          });
+        }
+        break;
+      }
+    }
+  }
+  const wrote = working !== agents.content;
+  if (wrote) {
+    await atomicWriteText(path7.join(root, "AGENTS.md"), working, { trailingNewline: false });
+  }
+  return { agentsUnavailable: false, wrote, outcomes };
+}
+
+// src/core/init-drift/nudge.ts
+var CONTEXT_BLOCKS_APPLY_COMMAND = "build config context apply";
+function diffSets(before, after) {
+  const beforeSet = new Set(before);
+  const afterSet = new Set(after);
+  return {
+    added: after.filter((item) => !beforeSet.has(item)),
+    removed: before.filter((item) => !afterSet.has(item))
+  };
+}
+function newManifests(stored, current) {
+  return Object.keys(current.manifests).filter((name) => stored.manifests[name] !== true);
+}
+function detectDrift(stored, current) {
+  const detectedAtMs = 0;
+  const records = [];
+  const appearedManifests = newManifests(stored, current);
+  const languages = diffSets(stored.languages, current.languages);
+  for (const language of languages.added) {
+    records.push({
+      key: `language:${language}`,
+      kind: "language-added",
+      subject: language,
+      change: "added",
+      evidence: appearedManifests,
+      detectedAtMs
+    });
+  }
+  for (const language of languages.removed) {
+    records.push({
+      key: `language:${language}`,
+      kind: "language-removed",
+      subject: language,
+      change: "removed",
+      evidence: [],
+      detectedAtMs
+    });
+  }
+  const frameworks = diffSets(stored.frameworks, current.frameworks);
+  for (const framework of frameworks.added) {
+    records.push({
+      key: `framework:${framework}`,
+      kind: "framework-changed",
+      subject: framework,
+      change: "added",
+      evidence: appearedManifests,
+      detectedAtMs
+    });
+  }
+  for (const framework of frameworks.removed) {
+    records.push({
+      key: `framework:${framework}`,
+      kind: "framework-changed",
+      subject: framework,
+      change: "removed",
+      evidence: [],
+      detectedAtMs
+    });
+  }
+  const explained = new Set(records.flatMap((record) => record.evidence));
+  for (const manifest of appearedManifests) {
+    if (explained.has(manifest)) continue;
+    records.push({
+      key: `manifest:${manifest}`,
+      kind: "manifest-appeared",
+      subject: manifest,
+      change: "added",
+      evidence: [manifest],
+      detectedAtMs
+    });
+  }
+  return records;
+}
+function checkDrift(cwd, options = {}) {
+  const now = options.now ?? Date.now;
+  const current = computeStackFingerprint(cwd);
+  const currentDigest = fingerprintDigest(current);
+  const stored = readStoredFingerprint(cwd);
+  if (stored === void 0) {
+    writeStoredFingerprint(cwd, current, options);
+    return {
+      hadBaseline: false,
+      newDrift: [],
+      pending: listPendingDrift(cwd, options),
+      currentDigest
+    };
+  }
+  if (stored.digest === currentDigest) {
+    return {
+      hadBaseline: true,
+      newDrift: [],
+      pending: listPendingDrift(cwd, options),
+      currentDigest
+    };
+  }
+  const nowMs = now();
+  const newDrift = detectDrift(stored.fingerprint, current).map((record) => ({
+    ...record,
+    detectedAtMs: nowMs
+  }));
+  if (newDrift.length > 0) {
+    recordDriftRecords(cwd, newDrift, options);
+  }
+  writeStoredFingerprint(cwd, current, options);
+  return {
+    hadBaseline: true,
+    newDrift,
+    pending: listPendingDrift(cwd, options),
+    currentDigest
+  };
+}
+var LANGUAGE_LABELS = {
+  python: { label: "Python", artifacts: "recommend Python docs/resources for coding agents" },
+  go: { label: "Go", artifacts: "recommend Go docs/resources for coding agents" },
+  rust: { label: "Rust", artifacts: "recommend Rust docs/resources for coding agents" },
+  swift: { label: "Swift", artifacts: "recommend Swift/Apple docs/resources for coding agents" },
+  typescript: {
+    label: "TypeScript",
+    artifacts: "recommend TypeScript docs/resources for coding agents"
+  },
+  javascript: {
+    label: "JavaScript",
+    artifacts: "recommend JavaScript docs/resources for coding agents"
+  },
+  node: { label: "Node.js", artifacts: "recommend Node.js docs/resources for coding agents" },
+  java: { label: "Java", artifacts: "recommend Java docs/resources for coding agents" },
+  kotlin: { label: "Kotlin", artifacts: "recommend Kotlin docs/resources for coding agents" },
+  ruby: { label: "Ruby", artifacts: "recommend Ruby docs/resources for coding agents" },
+  php: { label: "PHP", artifacts: "recommend PHP docs/resources for coding agents" },
+  dart: { label: "Dart", artifacts: "recommend Dart/Flutter docs/resources for coding agents" },
+  dotnet: { label: ".NET", artifacts: "recommend .NET docs/resources for coding agents" },
+  c: { label: "C", artifacts: "recommend C docs/resources for coding agents" },
+  cpp: { label: "C++", artifacts: "recommend C++ docs/resources for coding agents" }
+};
+function languageLabel(subject) {
+  return LANGUAGE_LABELS[subject] ?? {
+    label: subject,
+    artifacts: `recommend ${subject} docs/resources for coding agents`
+  };
+}
+function evidenceSuffix(record) {
+  if (record.evidence.length === 0) return "";
+  return ` (${record.evidence.join(", ")} added)`;
+}
+function composeNudgeMessage(record) {
+  const previewPromise = "Run 'build init' when ready \u2014 it will show you exactly what it proposes before changing anything.";
+  switch (record.kind) {
+    case "ci-setup":
+      return ciAdvisoryMessage(record.subject);
+    case "context-blocks-stale":
+      return `Notice: Managed context blocks in AGENTS.md are out of date (${record.subject}). Run '${CONTEXT_BLOCKS_APPLY_COMMAND}' to refresh them; nothing is written until you do.`;
+    case "language-added": {
+      const { label, artifacts } = languageLabel(record.subject);
+      return `Notice: New since last check: ${label}${evidenceSuffix(record)}. Build can update the agent instructions (AGENTS.md) and ${artifacts}. ` + previewPromise;
+    }
+    case "language-removed": {
+      const { label } = languageLabel(record.subject);
+      return `Notice: Changed since last check: ${label} no longer detected in this repo. Build can update the agent instructions (AGENTS.md) and retire stale ${label} guidance for coding agents. ` + previewPromise;
+    }
+    case "framework-changed": {
+      const direction = record.change === "added" ? "added" : "removed";
+      return `Notice: Changed since last check: ${record.subject} toolchain signal ${direction}${evidenceSuffix(record)}. Build can update the agent instructions (AGENTS.md) and adjust the recommended docs/resources for coding agents. ` + previewPromise;
+    }
+    case "manifest-appeared":
+      return `Notice: New since last check: ${record.subject} appeared. Build can update the agent instructions (AGENTS.md) and recommend docs/resources matching the new stack surface. ` + previewPromise;
+  }
+}
+
+// src/core/init-drift/render.ts
+function shouldSuppressNudges(policy, options = {}) {
+  if (policy.json || policy.quiet) return true;
+  if (isCiEnvironment(options.env ?? process.env)) return true;
+  const stderrIsTty = options.stderrIsTty ?? Boolean(process.stderr.isTTY);
+  return !stderrIsTty;
+}
+function formatAge(ageMs) {
+  const days = Math.floor(ageMs / (24 * 60 * 60 * 1e3));
+  if (days >= 2) return `${days} days`;
+  if (days === 1) return "1 day";
+  const hours = Math.floor(ageMs / (60 * 60 * 1e3));
+  if (hours >= 1) return hours === 1 ? "1 hour" : `${hours} hours`;
+  return "less than an hour";
+}
+function defaultWriteLine(line) {
+  process.stderr.write(`${line}
+`);
+}
+function renderPendingNudges(cwd, streamPolicy, options = {}) {
+  const pending = listPendingDrift(cwd, options).filter(
+    (record) => options.includeRecord?.(record) ?? true
+  );
+  if (shouldSuppressNudges(streamPolicy, options)) {
+    return { rendered: false, deliveredKeys: [], pendingCount: pending.length };
+  }
+  if (pending.length === 0) {
+    return { rendered: false, deliveredKeys: [], pendingCount: 0 };
+  }
+  const writeLine = options.writeLine ?? defaultWriteLine;
+  for (const record of pending) {
+    const message = composeNudgeMessage(record);
+    const suffix = options.includeAge === true ? ` (not yet reviewed, ${formatAge(record.ageMs)})` : "";
+    writeLine(`${message}${suffix}`);
+  }
+  const deliveredKeys = pending.map((record) => record.key);
+  if (!options.readOnly) recordDelivery(cwd, deliveredKeys, options);
+  return {
+    rendered: true,
+    deliveredKeys: options.readOnly ? [] : deliveredKeys,
+    pendingCount: options.readOnly ? pending.length : 0
+  };
+}
+function listPendingNudges(cwd, options = {}) {
+  return listPendingDrift(cwd, options);
+}
+
+// src/core/init-drift/context-blocks.ts
+var CONTEXT_BLOCKS_DRIFT_KEY = "context-blocks";
+function syncContextBlocksDrift(cwd, options = {}) {
+  const stale = listStaleManagedBlocks(cwd);
+  const prior = readDriftRecord(cwd, CONTEXT_BLOCKS_DRIFT_KEY);
+  if (stale.length === 0) {
+    if (prior) forgetDriftRecord(cwd, CONTEXT_BLOCKS_DRIFT_KEY);
+    return;
+  }
+  const subject = stale.join(", ");
+  if (prior?.record.subject === subject) return;
+  const now = options.now ?? Date.now;
+  recordDriftRecords(
+    cwd,
+    [
+      {
+        key: CONTEXT_BLOCKS_DRIFT_KEY,
+        kind: "context-blocks-stale",
+        subject,
+        change: "added",
+        evidence: [],
+        detectedAtMs: Math.max(now(), (prior?.record.detectedAtMs ?? 0) + 1)
+      }
+    ],
+    options
+  );
+}
+
+export {
+  upsertManagedBlock,
+  removeManagedBlock,
+  createAskSearchProvider,
+  buildKitOffer,
+  renderPendingIntentBlock,
+  blockIsPendingIntent,
+  removeKnowledgeBlock,
+  upsertKnowledgeBlock,
+  applyKit,
+  PENDING_OFFER_NOTICE_MESSAGE,
+  writePendingOfferNotice,
+  readPendingOfferNotice,
+  clearPendingOfferNotice,
+  knowledgeStatus,
+  declareIntent,
+  clearIntent,
+  resolveConflicts,
+  createOffer,
+  acceptOffer,
+  graduateIntent,
+  WORK_TRACKING_MARKERS,
+  readPackagedUsageBlock,
+  installUsageBlockIfAbsent,
+  listServiceEntries,
+  addServiceEntry,
+  classifyAgentsFile,
+  buildContextView,
+  listStaleManagedBlocks,
+  applyContext,
+  syncContextBlocksDrift,
+  CONTEXT_BLOCKS_APPLY_COMMAND,
+  checkDrift,
+  shouldSuppressNudges,
+  renderPendingNudges,
+  listPendingNudges
+};
+//# sourceMappingURL=chunk-KZWGBUIO.js.map