@captain_z/zsk 1.8.3 → 1.8.5

package/dist/core/prepare-sync.js

@@ -1,39 +1,47 @@
-import { createHash } from "node:crypto";
+import { Buffer } from "node:buffer";
+import { execFile } from "node:child_process";
 import { createRequire } from "node:module";
-import { copyFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
-import { DESIGN_LOCAL_FILE_ORIGIN_KEYS, JIRA_LOCAL_FILE_ORIGIN_KEYS, flattenProjectSources, resolveSourceSnapshot, } from "./config.js";
+import { copyFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, extname, join, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import { DESIGN_LOCAL_FILE_ORIGIN_KEYS, JIRA_LOCAL_FILE_ORIGIN_KEYS, flattenPrepareEntries, resolveSourceSnapshot, } from "./config.js";
 import { inferSourceOrigin } from "./origin-detection.js";
+import { discoverMcpRegistries } from "./mcp-registry-discovery.js";
+import { loadProviderPolicy } from "./provider-policy.js";
+import { buildProviderReadinessEvidence } from "./provider-readiness.js";
 import { describeResource, updateRawIndexes, updateRawManifest } from "./raw-manifest.js";
+import { createSyncRunId, resolvePrepareSyncArtifacts, } from "./prepare-artifacts.js";
+import { hashIfExists, sha256, writePreparedSnapshot } from "./prepare-materialization.js";
+import { renderDownstreamImpact, renderPreparationReport } from "./prepare-reporting.js";
+import { routePreparedResources } from "./prepare-routing.js";
+import { escapeTable, exists, isRecord, safeFileName } from "./prepare-utils.js";
+import { interpretSourceAdapter } from "./source-adapter-normalization.js";
+import { acquireSourceSnapshot, chooseSourceSnapshotStrategy, createSourceSnapshotContext, } from "./source-snapshot-adapters.js";
+import { isPathInside, resolvePlaywrightAuthProfilePath, resolvePlaywrightAuthStatePath, } from "./workspace-conformance.js";
 import { getWorkspacePath } from "./workspace-layout.js";
-export function resolvePrepareSyncArtifacts(target, config, runId) {
-    const dir = resolve(target, getWorkspacePath(config, "evidenceRoot"), "prepare", runId);
-    const authDir = resolve(target, getWorkspacePath(config, "playwrightRoot"), ".auth");
-    return {
-        runId,
-        dir,
-        adapterResultsDir: join(dir, "adapter-results"),
-        authCheckPath: join(dir, "auth-check.json"),
-        downstreamImpactPath: join(dir, "downstream-impact.md"),
-        authScriptPath: join(authDir, "login.mjs"),
-        authStatePath: join(authDir, "user_data.json"),
-        migrationPlanPath: join(dir, "raws-migration-plan.md"),
-    };
-}
+export { createSyncRunId, resolvePrepareSyncArtifacts } from "./prepare-artifacts.js";
+export { writeAuthLoginHelper } from "./prepare-auth-helper.js";
+export { buildRawMigrationPlan } from "./prepare-migration.js";
+const execFileAsync = promisify(execFile);
+const DEFAULT_ADAPTER_COMMAND_TIMEOUT_MS = 60_000;
+const DEFAULT_ADAPTER_COMMAND_MAX_BUFFER = 10 * 1024 * 1024;
 export async function syncPrepareSources(target, config, opts = {}) {
     const runId = opts.runId ?? createSyncRunId();
     const artifacts = resolvePrepareSyncArtifacts(target, config, runId);
-    const entries = flattenProjectSources(config.sources);
+    const entries = flattenPrepareEntries(config);
     const selected = new Set(selectSourceEntries(entries, opts));
     const results = [];
     await mkdir(artifacts.adapterResultsDir, { recursive: true });
+    await mkdir(artifacts.providerReadinessDir, { recursive: true });
+    const providerReadiness = await resolveProviderReadiness(target, artifacts, [...selected]);
     for (const entry of entries) {
         if (!selected.has(entry))
             continue;
-        const result = await syncEntry(target, config, entry, opts);
+        const result = annotateProviderReadiness(target, entry, await syncEntry(target, config, entry, opts, entries), providerReadiness.byProvider);
         results.push(result);
         await writeFile(join(artifacts.adapterResultsDir, `${safeFileName(entry.id)}.json`), `${JSON.stringify(result, null, 2)}\n`, "utf8");
     }
+    const routes = opts.dryRun ? [] : await routePreparedResources(target, config, results);
     if (!opts.dryRun) {
         const records = [];
         for (const entry of entries) {
@@ -45,43 +53,22 @@ export async function syncPrepareSources(target, config, opts = {}) {
     const downstreamImpact = renderDownstreamImpact(results);
     await mkdir(dirname(artifacts.downstreamImpactPath), { recursive: true });
     await writeFile(artifacts.downstreamImpactPath, downstreamImpact, "utf8");
+    const syncReport = renderPreparationReport(entries, results, routes);
+    await mkdir(dirname(artifacts.syncReportPath), { recursive: true });
+    await writeFile(artifacts.syncReportPath, syncReport, "utf8");
     return {
         artifacts,
         results,
+        routes,
+        providerReadiness: [...providerReadiness.byProvider.values()].map((item) => item.evidence),
         downstreamImpact,
+        syncReport,
     };
 }
-export async function writeAuthLoginHelper(target, config, opts = {}) {
-    const artifacts = resolvePrepareSyncArtifacts(target, config, opts.runId ?? createSyncRunId());
-    const statePath = opts.out ? resolve(target, opts.out) : resolveAuthProfilePath(target, config, opts.profile);
-    const authRoot = dirname(artifacts.authScriptPath);
-    if (!isInside(authRoot, statePath)) {
-        throw new Error(`Playwright storageState output must stay under ${authRoot}`);
-    }
-    const script = [
-        `import { chromium } from "playwright";`,
-        ``,
-        `const targetUrl = process.env.ZSK_PREPARE_AUTH_URL ?? ${JSON.stringify(opts.url ?? "about:blank")};`,
-        `const storageStatePath = process.env.ZSK_PLAYWRIGHT_STORAGE_STATE ?? ${JSON.stringify(statePath)};`,
-        `const browser = await chromium.launch({ headless: false });`,
-        `const context = await browser.newContext();`,
-        `const page = await context.newPage();`,
-        `await page.goto(targetUrl, { waitUntil: "domcontentloaded" });`,
-        `console.log("Complete login in the opened browser, then press Enter here to save storageState.");`,
-        `await new Promise((resolve) => process.stdin.once("data", resolve));`,
-        `await context.storageState({ path: storageStatePath });`,
-        `console.log(\`Saved Playwright storageState to ${"${storageStatePath}"}\`);`,
-        `await browser.close();`,
-        ``,
-    ].join("\n");
-    await mkdir(dirname(artifacts.authScriptPath), { recursive: true });
-    await writeFile(artifacts.authScriptPath, script, "utf8");
-    return { ...artifacts, authStatePath: statePath };
-}
 export async function checkPrepareAuth(target, config, opts = {}) {
     const runId = opts.runId ?? createSyncRunId();
     const artifacts = resolvePrepareSyncArtifacts(target, config, runId);
-    const entries = selectSourceEntries(flattenProjectSources(config.sources), opts);
+    const entries = selectSourceEntries(flattenPrepareEntries(config), opts);
     const authStatePath = resolveSelectedAuthStatePath(target, config, opts);
     const results = [];
     for (const entry of entries) {
@@ -91,45 +78,6 @@ export async function checkPrepareAuth(target, config, opts = {}) {
     await writeFile(artifacts.authCheckPath, `${JSON.stringify({ runId, results }, null, 2)}\n`, "utf8");
     return { artifacts, results };
 }
-export async function buildRawMigrationPlan(target, config, runId = createSyncRunId()) {
-    const artifacts = resolvePrepareSyncArtifacts(target, config, runId);
-    const prepareRoot = resolve(target, getWorkspacePath(config, "resourcesRoot"), "prepare");
-    const staleNames = new Set([
-        "qa-engineer",
-        "test-engineer",
-        "backend-engineer",
-        "frontend-engineer",
-        "product-manager",
-        "designer",
-        "jira",
-        "confluence",
-        "figma",
-        "modao",
-        "manual",
-        "provider",
-        "version",
-    ]);
-    const entries = await safeReadDir(prepareRoot);
-    const findings = entries
-        .filter((entry) => entry.isDirectory() && isMigrationLaneCandidate(entry.name, staleNames))
-        .map((entry) => ({
-        path: join(".zsk/raws/prepare", entry.name),
-        action: "dry-run only; keep readable, require explicit migration before rewriting references",
-    }));
-    const content = [
-        "# Raw Migration Plan",
-        "",
-        "Dry-run report only. No files were moved, deleted, or rewritten.",
-        "",
-        findings.length === 0
-            ? "No stale provider/method/version prepare lanes were found."
-            : findings.map((item) => `- \`${item.path}\`: ${item.action}`).join("\n"),
-        "",
-    ].join("\n");
-    await mkdir(dirname(artifacts.migrationPlanPath), { recursive: true });
-    await writeFile(artifacts.migrationPlanPath, content, "utf8");
-    return { artifacts, content };
-}
 function selectSourceEntries(entries, opts) {
     if (opts.all || !opts.source)
         return entries;
@@ -144,6 +92,52 @@ function selectSourceEntries(entries, opts) {
     }
     return alias;
 }
+async function resolveProviderReadiness(target, artifacts, entries) {
+    const names = new Map();
+    for (const entry of entries) {
+        const normalized = interpretSourceAdapter(entry.source);
+        if (!normalized.mcpProviderName)
+            continue;
+        names.set(normalized.mcpProviderName, normalized);
+    }
+    if (names.size === 0)
+        return { byProvider: new Map() };
+    const policy = await loadProviderPolicy(target);
+    const registry = await discoverMcpRegistries(target);
+    const byProvider = new Map();
+    for (const [providerName, normalized] of names) {
+        const evidence = buildProviderReadinessEvidence(target, providerName, normalized.adapterId, policy, registry.registrations);
+        evidence.warnings.push(...registry.warnings);
+        const path = join(artifacts.providerReadinessDir, `${safeFileName(providerName)}.json`);
+        await writeFile(path, `${JSON.stringify(evidence, null, 2)}\n`, "utf8");
+        byProvider.set(providerName, { path, evidence });
+    }
+    return { byProvider };
+}
+function annotateProviderReadiness(target, entry, result, readiness) {
+    const normalized = interpretSourceAdapter(entry.source);
+    const providerName = normalized.mcpProviderName;
+    if (!providerName)
+        return result;
+    const item = readiness.get(providerName);
+    if (!item)
+        return result;
+    return {
+        ...result,
+        metadata: cleanMetadata({
+            ...(result.metadata ?? {}),
+            adapterId: normalized.adapterId,
+            mcpProvider: providerName,
+            providerReadiness: relative(target, item.path),
+            providerReadinessStatus: item.evidence.summary,
+            providerPolicyStatus: item.evidence.policy.status,
+            providerRegistryStatus: item.evidence.registry.status,
+            providerConnectionStatus: item.evidence.connection.status,
+            capabilitiesMatched: item.evidence.capabilities.matched.join(", ") || undefined,
+            capabilitiesEvaluation: item.evidence.capabilities.evaluation,
+        }),
+    };
+}
 async function checkAuthEntry(entry, authStatePath, opts) {
     const origin = inferSourceOrigin(entry.source);
     const base = {
@@ -154,20 +148,20 @@ async function checkAuthEntry(entry, authStatePath, opts) {
         origin: origin.ref,
         method: origin.method,
     };
-    const url = origin.ref;
-    if (!url || origin.method !== "url") {
+    const url = authCheckUrlForSource(entry.source, origin);
+    if (!url) {
         return {
             ...base,
             status: "source-gap",
             authSources: [],
             directAuthAvailable: false,
             networkAttempted: false,
-            reason: "auth-check only validates URL origins; configure origin.url before checking runtime credentials",
+            reason: "auth-check needs origin.url or provider fields that derive a REST URL before checking runtime credentials",
             validation: { urlOrigin: "fail", secretValuesHidden: "pass" },
         };
     }
     const { headers, authSources } = await headersForSource(entry.source, url, authStatePath);
-    const directAuthAvailable = Boolean(headers.authorization || headers.cookie);
+    const directAuthAvailable = hasRuntimeAuthHeaders(headers);
     if (!opts.allowNetwork) {
         return {
             ...base,
@@ -253,161 +247,193 @@ async function checkAuthEntry(entry, authStatePath, opts) {
         };
     }
 }
-async function syncEntry(target, config, entry, opts) {
-    const source = entry.source;
-    const origin = inferSourceOrigin(source);
-    const snapshot = resolveSourceSnapshot(config, entry);
-    const snapshotPath = resolve(target, snapshot);
-    const previousSnapshotHash = await hashIfExists(snapshotPath);
-    const base = {
-        envelopeVersion: 1,
-        sourceKey: entry.id,
-        sourcePath: entry.path,
-        rawLane: entry.rawLane,
-        provider: origin.provider,
-        origin: origin.ref,
-        snapshot,
-        previousSnapshotHash,
+function authCheckUrlForSource(source, origin) {
+    if (origin.ref && origin.method === "url")
+        return origin.ref;
+    const provider = sourceProviderToken(source);
+    if (provider?.includes("confluence")) {
+        return firstOriginString(source, "apiUrl", "restUrl") ?? deriveConfluenceRestUrl(source);
+    }
+    if (provider?.includes("jira")) {
+        return firstOriginString(source, "apiUrl", "searchUrl") ?? deriveJiraRestUrl(source);
+    }
+    return undefined;
+}
+async function syncEntry(target, config, entry, opts, entries = [entry]) {
+    const context = await createSourceSnapshotContext(target, config, entry, optsWithSourceFallback(entry.source, opts), hashIfExists);
+    const sharedSnapshot = sharedSnapshotProvenance(target, config, entry, entries);
+    return acquireSourceSnapshot(context, {
+        dryRun: skippedDryRunSnapshot,
+        local: syncLocalSnapshot,
+        provider: (snapshotContext, providerAdapter) => syncProviderSnapshot(snapshotContext, providerAdapter, sharedSnapshot),
+        repository: syncRepositorySnapshot,
+        url: syncUrlSnapshot,
+        providerManaged: blockedProviderManagedSnapshot,
+    });
+}
+function optsWithSourceFallback(source, opts) {
+    const interpretation = interpretSourceAdapter(source);
+    if (interpretation.hasBrowserFallback) {
+        return { ...opts, browser: true };
+    }
+    return opts;
+}
+function skippedDryRunSnapshot(context) {
+    return {
+        ...context.base,
+        strategy: chooseSourceSnapshotStrategy(context.origin.method),
+        status: "skipped",
+        changed: false,
+        reason: "dry-run requested; no snapshot was written",
+        validation: { dryRun: "pass" },
     };
-    if (opts.dryRun) {
-        return {
-            ...base,
-            strategy: chooseStrategy(origin.method),
-            status: "skipped",
-            changed: false,
-            reason: "dry-run requested; no snapshot was written",
-            validation: { dryRun: "pass" },
-        };
+}
+async function syncLocalSnapshot(context) {
+    const { base, entry, source, snapshotPath, previousSnapshotHash, target, opts } = context;
+    const sourcePath = source.origin?.path ?? source.path;
+    if (!sourcePath) {
+        return sourceGap(base, "configured local origin has no path");
     }
-    if (origin.method === "local") {
-        const sourcePath = source.origin?.path ?? source.path;
-        if (!sourcePath) {
-            return sourceGap(base, "configured local origin has no path");
-        }
-        const originPath = resolve(target, sourcePath);
-        if (!(await exists(originPath))) {
-            return sourceGap(base, "configured local origin path does not exist");
-        }
+    const originPath = resolve(target, sourcePath);
+    if (!(await exists(originPath)) && opts.allowNetwork && isGitSubmoduleResource(source)) {
+        const update = await updateGitSubmodule(target, sourcePath);
+        if (!update.ok)
+            return failed(base, update.reason);
+    }
+    const info = await safeStat(originPath);
+    if (!info) {
+        return sourceGap(base, "configured local origin path does not exist");
+    }
+    let written;
+    if (info.isDirectory) {
+        written = await writePreparedSnapshot(target, snapshotPath, await renderStructuredLocalDirectoryMarkdown(target, entry, originPath), previousSnapshotHash);
+    }
+    else if (shouldPreserveMachineReadable(source, originPath, snapshotPath)) {
         await mkdir(dirname(snapshotPath), { recursive: true });
-        if (shouldPreserveMachineReadable(source, originPath, snapshotPath)) {
-            await copyFile(originPath, snapshotPath);
-        }
-        else {
-            await writeFile(snapshotPath, await renderStructuredLocalMarkdown(target, entry, originPath), "utf8");
-        }
+        await copyFile(originPath, snapshotPath);
         const snapshotHash = await sha256(snapshotPath);
-        return {
-            ...base,
-            strategy: "local-copy-structured-markdown",
-            status: "materialized",
+        written = {
             snapshotHash,
             changed: previousSnapshotHash !== snapshotHash,
-            reason: "local origin copied or materialized into configured snapshot",
-            validation: { sourceExists: "pass", bodyContent: "pass", snapshotWritten: "pass" },
         };
     }
-    const providerAdapter = selectProviderAdapter(source, origin);
-    if (providerAdapter) {
-        const authStatePath = resolveSelectedAuthStatePath(target, config, opts);
-        const adapterResult = await runProviderAdapter(providerAdapter, target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts);
-        if (adapterResult) {
-            if (adapterResult.status === "blocked-auth" && opts.browser && origin.method === "url") {
-                const browserResult = await fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
-                return {
-                    ...browserResult,
-                    adapter: `${providerAdapter}-browser-fallback`,
-                    metadata: cleanMetadata({ providerAdapter, fallbackFrom: adapterResult.strategy }),
-                };
-            }
+    else {
+        written = await writePreparedSnapshot(target, snapshotPath, await renderStructuredLocalMarkdown(target, entry, originPath), previousSnapshotHash);
+    }
+    return {
+        ...base,
+        strategy: "local-copy-structured-markdown",
+        status: "materialized",
+        snapshotHash: written.snapshotHash,
+        changed: written.changed,
+        reason: info.isDirectory
+            ? "local directory origin summarized into configured snapshot"
+            : "local origin copied or materialized into configured snapshot",
+        validation: { sourceExists: "pass", bodyContent: "pass", snapshotWritten: "pass" },
+    };
+}
+async function syncProviderSnapshot(context, providerAdapter, sharedSnapshot) {
+    const { target, config, entry, snapshotPath, previousSnapshotHash, opts, origin } = context;
+    const authStatePath = resolveSelectedAuthStatePath(target, config, opts);
+    const adapterResult = await runProviderAdapter(providerAdapter, target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts, sharedSnapshot);
+    if (!adapterResult)
+        return null;
+    if (adapterResult.status === "source-gap" && origin.method === "url") {
+        if (adapterResult.metadata?.providerGap === "adapter-ambiguous") {
             return adapterResult;
         }
+        const fallback = await syncUrlSnapshot(context);
+        return annotateFallbackResult(fallback, providerAdapter, adapterResult);
     }
-    if (origin.method === "repository") {
-        await mkdir(dirname(snapshotPath), { recursive: true });
-        const content = renderRepositoryMetadata(entry, origin.ref ?? "");
-        await writeFile(snapshotPath, content, "utf8");
-        const snapshotHash = await sha256(snapshotPath);
+    if (adapterResult.status === "blocked-auth" && opts.browser && origin.method === "url") {
+        const browserResult = await fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+        return annotateFallbackResult(browserResult, providerAdapter, adapterResult, `${providerAdapter}-browser-fallback`);
+    }
+    return adapterResult;
+}
+function annotateFallbackResult(fallback, providerAdapter, adapterResult, adapter = `${providerAdapter}-generic-fallback`) {
+    return {
+        ...fallback,
+        adapter,
+        metadata: cleanMetadata({
+            ...(fallback.metadata ?? {}),
+            providerAdapter,
+            fallbackFrom: adapterResult.strategy,
+            fallbackReason: adapterResult.reason,
+            fallbackStatus: adapterResult.status,
+        }),
+    };
+}
+async function syncRepositorySnapshot(context) {
+    const { base, entry, origin, snapshotPath, previousSnapshotHash } = context;
+    const content = renderRepositoryMetadata(entry, origin.ref ?? "");
+    const written = await writePreparedSnapshot(context.target, snapshotPath, content, previousSnapshotHash);
+    return {
+        ...base,
+        strategy: "repository-metadata-only",
+        status: "metadata-only",
+        snapshotHash: written.snapshotHash,
+        changed: written.changed,
+        reason: "repository origin recorded as metadata; configure contract paths or checkout policy before broad acquisition",
+        validation: { repositoryNotCrawled: "pass", snapshotWritten: "pass" },
+    };
+}
+async function syncUrlSnapshot(context) {
+    const { base, entry, source, origin, target, config, opts, snapshotPath, previousSnapshotHash } = context;
+    if (!opts.allowNetwork) {
         return {
             ...base,
-            strategy: "repository-metadata-only",
-            status: "metadata-only",
-            snapshotHash,
-            changed: previousSnapshotHash !== snapshotHash,
-            reason: "repository origin recorded as metadata; configure contract paths or checkout policy before broad acquisition",
-            validation: { repositoryNotCrawled: "pass", snapshotWritten: "pass" },
+            strategy: "playwright-auth-or-direct-fetch",
+            status: "blocked-auth",
+            changed: false,
+            reason: "remote URL requires --allow-network or a materialized snapshot; Playwright auth helper can create reusable storageState first",
+            validation: { networkAllowed: "fail", previousSnapshotPreserved: previousSnapshotHash ? "pass" : "skipped" },
         };
     }
-    if (origin.method === "url") {
-        if (!opts.allowNetwork) {
-            return {
-                ...base,
-                strategy: "playwright-auth-or-direct-fetch",
-                status: "blocked-auth",
-                changed: false,
-                reason: "remote URL requires --allow-network or a materialized snapshot; Playwright auth helper can create reusable storageState first",
-                validation: { networkAllowed: "fail", previousSnapshotPreserved: previousSnapshotHash ? "pass" : "skipped" },
-            };
-        }
-        const authStatePath = resolveSelectedAuthStatePath(target, config, opts);
-        if (opts.browser) {
-            if (origin.ref && await hasDirectRuntimeAuthForSource(source, origin.ref, authStatePath)) {
-                const direct = await fetchUrlSnapshot(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
-                if (direct.status === "materialized")
-                    return direct;
-            }
-            return fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+    const authStatePath = resolveSelectedAuthStatePath(target, config, opts);
+    if (opts.browser) {
+        if (origin.ref && await hasDirectRuntimeAuthForSource(source, origin.ref, authStatePath)) {
+            const direct = await fetchUrlSnapshot(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+            if (direct.status === "materialized")
+                return direct;
         }
-        return fetchUrlSnapshot(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+        return fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
     }
+    return fetchUrlSnapshot(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
+}
+function blockedProviderManagedSnapshot(context) {
     return {
-        ...base,
+        ...context.base,
         strategy: "confirm-acquisition-method",
         status: "blocked-auth",
         changed: false,
         reason: "provider-managed origin needs an explicit acquisition method or exported snapshot",
-        validation: { acquisitionMethodConfirmed: "fail", previousSnapshotPreserved: previousSnapshotHash ? "pass" : "skipped" },
+        validation: { acquisitionMethodConfirmed: "fail", previousSnapshotPreserved: context.previousSnapshotHash ? "pass" : "skipped" },
     };
 }
-function selectProviderAdapter(source, origin) {
-    const keys = [
-        origin.provider,
-        origin.kind,
-        source.origin?.provider,
-        source.origin?.kind,
-        source.kind,
-        source.type,
-    ].map((value) => normalizeAdapterKey(typeof value === "string" ? value : undefined));
-    if (keys.some((value) => value.includes("confluence")))
-        return "confluence";
-    if (keys.some((value) => value.includes("jira")))
-        return "jira";
-    if (keys.some((value) => value.includes("gitlab")))
-        return "gitlab";
-    if (keys.some((value) => ["figma", "modao", "mastergo", "design", "design-asset", "design-source"].includes(value))) {
-        return "design-source";
-    }
-    return undefined;
-}
-async function runProviderAdapter(adapter, target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts) {
+async function runProviderAdapter(adapter, target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts, sharedSnapshot) {
     if (adapter === "confluence") {
-        return runConfluenceAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts);
+        return runConfluenceAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts, sharedSnapshot);
     }
     if (adapter === "jira") {
-        return runJiraAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts);
+        return runJiraAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts, sharedSnapshot);
     }
     if (adapter === "gitlab") {
-        return runGitLabAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts);
+        return runGitLabAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts, sharedSnapshot);
     }
-    return runDesignAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts);
+    return runDesignAdapter(adapter, target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts, sharedSnapshot);
 }
-async function runConfluenceAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts) {
+async function runConfluenceAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts, sharedSnapshot) {
     const base = adapterBase(target, entry, snapshotPath, previousSnapshotHash, "confluence");
-    const url = firstOriginString(entry.source, "apiUrl", "restUrl", "url") ?? base.origin;
-    const strategy = "confluence-storage-rest";
+    const exportWordUrl = firstOriginString(entry.source, "exportWordUrl", "wordExportUrl", "exportUrl");
+    const restUrl = firstOriginString(entry.source, "apiUrl", "restUrl") ?? deriveConfluenceRestUrl(entry.source);
+    const pageUrl = firstOriginString(entry.source, "url") ?? base.origin;
+    const url = exportWordUrl ?? restUrl ?? pageUrl;
+    const strategy = exportWordUrl ? "confluence-word-export" : "confluence-storage-rest";
     if (!url)
-        return sourceGap(base, "confluence adapter needs origin.url, origin.apiUrl, or origin.restUrl");
+        return sourceGap(base, "confluence adapter needs origin.url, origin.apiUrl, origin.restUrl, or origin.exportWordUrl");
     if (!opts.allowNetwork) {
-        return blockedAdapter(base, strategy, "confluence source requires --allow-network and optional Playwright storageState before acquisition");
+        return blockedAdapter(base, strategy, "confluence source requires --allow-network and optional env auth or Playwright storageState before acquisition", cleanMetadata({ derivedUrl: restUrl }));
     }
     const fetched = await fetchAdapterBody(entry.source, url, authStatePath);
     if (!fetched.ok)
@@ -416,15 +442,18 @@ async function runConfluenceAdapter(target, entry, snapshotPath, previousSnapsho
         return blockedAdapter(base, strategy, "confluence adapter resolved to login/chrome content; previous snapshot was preserved");
     }
     const parsed = parseJsonObject(fetched.body);
+    const wordExport = parseConfluenceWordExport(fetched.body, fetched.contentType);
     const title = parsed ? stringValue(parsed, "title") : undefined;
     const pageId = parsed ? firstStringValue(parsed, "id", "pageId", "contentId") : undefined;
     const version = parsed ? versionValue(parsed) : undefined;
     const storageHtml = parsed ? confluenceBodyValue(parsed) : undefined;
-    const content = storageHtml
-        ? htmlToStructuredMarkdown(storageHtml)
-        : fetched.contentType.includes("html")
-            ? htmlToStructuredMarkdown(fetched.body)
-            : fencedBody(fetched.body, fetched.contentType);
+    const content = wordExport?.html
+        ? htmlToStructuredMarkdown(wordExport.html)
+        : storageHtml
+            ? htmlToStructuredMarkdown(storageHtml)
+            : fetched.contentType.includes("html")
+                ? htmlToStructuredMarkdown(fetched.body)
+                : fencedBody(fetched.body, fetched.contentType);
     if (!hasMaterialContent(content)) {
         return blockedAdapter(base, strategy, "confluence adapter produced no material body content; previous snapshot was preserved");
     }
@@ -435,11 +464,11 @@ async function runConfluenceAdapter(target, entry, snapshotPath, previousSnapsho
         contentType: fetched.contentType,
         content,
         reason: "confluence source fetched and normalized into structured Markdown",
-        metadata: cleanMetadata({ title, pageId, version, runtimeAuth: fetched.authSources.join(", ") || undefined }),
+        metadata: cleanMetadata({ title: wordExport?.title ?? title, pageId, version, runtimeAuth: fetched.authSources.join(", ") || undefined }),
         validation: { httpOk: "pass", loginPageRejected: "pass", bodyContent: "pass", snapshotWritten: "pass" },
-    });
+    }, sharedSnapshot);
 }
-async function runJiraAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts) {
+async function runJiraAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts, sharedSnapshot) {
     const base = adapterBase(target, entry, snapshotPath, previousSnapshotHash, "jira");
     const csvPath = firstOriginString(entry.source, ...JIRA_LOCAL_FILE_ORIGIN_KEYS);
     if (csvPath) {
@@ -463,14 +492,15 @@ async function runJiraAdapter(target, entry, snapshotPath, previousSnapshotHash,
             reason: "jira CSV export imported and normalized into structured Markdown",
             metadata: cleanMetadata({ issueCount: rows.length, fallback: "csv" }),
             validation: { sourceExists: "pass", bodyContent: "pass", snapshotWritten: "pass" },
-        });
+        }, sharedSnapshot);
     }
-    const url = firstOriginString(entry.source, "apiUrl", "searchUrl", "url") ?? (base.origin?.startsWith("http") || base.origin?.startsWith("data:") ? base.origin : undefined);
+    const derivedUrl = deriveJiraRestUrl(entry.source);
+    const url = firstOriginString(entry.source, "apiUrl", "searchUrl") ?? derivedUrl ?? firstOriginString(entry.source, "url") ?? (base.origin?.startsWith("http") || base.origin?.startsWith("data:") ? base.origin : undefined);
     if (!url)
         return null;
     const strategy = "jira-rest-search";
     if (!opts.allowNetwork) {
-        return blockedAdapter(base, strategy, "jira REST source requires --allow-network and optional Playwright storageState before acquisition");
+        return blockedAdapter(base, strategy, "jira REST source requires --allow-network and optional env auth or Playwright storageState before acquisition", cleanMetadata({ derivedUrl }));
     }
     const fetched = await fetchAdapterBody(entry.source, url, authStatePath);
     if (!fetched.ok)
@@ -492,9 +522,9 @@ async function runJiraAdapter(target, entry, snapshotPath, previousSnapshotHash,
         reason: "jira REST source fetched and normalized into structured Markdown",
         metadata: cleanMetadata({ issueCount: jiraIssueCount(parsed), runtimeAuth: fetched.authSources.join(", ") || undefined }),
         validation: { httpOk: "pass", loginPageRejected: "pass", bodyContent: "pass", snapshotWritten: "pass" },
-    });
+    }, sharedSnapshot);
 }
-async function runGitLabAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts) {
+async function runGitLabAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts, sharedSnapshot) {
     const base = adapterBase(target, entry, snapshotPath, previousSnapshotHash, "gitlab");
     const url = firstOriginString(entry.source, "rawUrl", "apiUrl", "url");
     if (!url)
@@ -532,10 +562,11 @@ async function runGitLabAdapter(target, entry, snapshotPath, previousSnapshotHas
             runtimeAuth: fetched.authSources.join(", ") || undefined,
         }),
         validation: { httpOk: "pass", loginPageRejected: "pass", bodyContent: "pass", snapshotWritten: "pass" },
-    });
+    }, sharedSnapshot);
 }
-async function runDesignAdapter(target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts) {
-    const base = adapterBase(target, entry, snapshotPath, previousSnapshotHash, "design-source");
+async function runDesignAdapter(adapter, target, entry, snapshotPath, previousSnapshotHash, authStatePath, opts, sharedSnapshot) {
+    const normalized = interpretSourceAdapter(entry.source);
+    const base = adapterBase(target, entry, snapshotPath, previousSnapshotHash, adapter);
     const exportPath = firstOriginString(entry.source, ...DESIGN_LOCAL_FILE_ORIGIN_KEYS);
     if (exportPath) {
         const path = resolveAdapterLocalFilePath(target, exportPath);
@@ -549,7 +580,7 @@ async function runDesignAdapter(target, entry, snapshotPath, previousSnapshotHas
             return blockedAdapter(base, "design-export-import", "design export produced no material content; previous snapshot was preserved");
         }
         return writeAdapterSnapshot(target, entry, snapshotPath, previousSnapshotHash, {
-            adapter: "design-source",
+            adapter,
             strategy: "design-export-import",
             resolvedOrigin: exportPath,
             contentType: contentTypeForPath(exportPath),
@@ -557,21 +588,56 @@ async function runDesignAdapter(target, entry, snapshotPath, previousSnapshotHas
             reason: "design export imported and normalized into structured Markdown",
             metadata: cleanMetadata({ provider: base.provider, fallback: "export" }),
             validation: { sourceExists: "pass", bodyContent: "pass", snapshotWritten: "pass" },
-        });
+        }, sharedSnapshot);
+    }
+    if (adapter === "design-source" && normalized.ambiguous && !exportPath) {
+        return sourceGap(base, "design source needs explicit adapter before provider-backed acquisition; configure source adapter, for example adapter: figma", designProviderGapMetadata("adapter-ambiguous", entry.source, undefined));
     }
-    const url = firstOriginString(entry.source, "apiUrl", "exportUrl", "url") ?? base.origin;
+    const figmaLocator = figmaLocatorForSource(entry.source);
+    const command = figmaCommandForSource(entry.source, target, relative(target, snapshotPath), figmaLocator);
+    if (command) {
+        if (!opts.allowNetwork) {
+            return blockedAdapter(base, "figma-mcp-command", "figma MCP command acquisition requires --allow-network because it may contact the local MCP bridge or Figma desktop plugin", designProviderGapMetadata("network-not-allowed", entry.source, figmaLocator));
+        }
+        const commandResult = await runDesignCommand(target, command);
+        if (!commandResult.ok) {
+            return blockedAdapter(base, "figma-mcp-command", commandResult.reason, designProviderGapMetadata("mcp-command-failed", entry.source, figmaLocator));
+        }
+        const content = renderDesignMarkdown(commandResult.body, commandResult.origin, commandResult.contentType);
+        if (!hasMaterialContent(content)) {
+            return blockedAdapter(base, "figma-mcp-command", "figma MCP command produced no material design content; previous snapshot was preserved", designProviderGapMetadata("mcp-command-empty", entry.source, figmaLocator));
+        }
+        return writeAdapterSnapshot(target, entry, snapshotPath, previousSnapshotHash, {
+            adapter,
+            strategy: "figma-mcp-command",
+            resolvedOrigin: commandResult.origin,
+            contentType: commandResult.contentType,
+            content,
+            reason: "design source captured through configured Figma MCP command and normalized into structured Markdown",
+            metadata: cleanMetadata({
+                provider: base.provider,
+                mcpProvider: command.provider,
+                command: command.safeLabel,
+                fileKey: figmaLocator?.fileKey,
+                nodeId: figmaLocator?.nodeId,
+            }),
+            validation: { commandExited: "pass", bodyContent: "pass", snapshotWritten: "pass", secretValuesHidden: "pass" },
+        }, sharedSnapshot);
+    }
+    const derivedApiUrl = figmaLocator?.apiUrl;
+    const url = firstOriginString(entry.source, "apiUrl", "exportUrl") ?? derivedApiUrl ?? firstOriginString(entry.source, "url") ?? base.origin;
     if (!url) {
-        return sourceGap(base, "design source needs origin.url, origin.apiUrl, origin.exportUrl, or a local exportPath/assetPath/filePath before acquisition", designProviderGapMetadata("missing-provider-locator"));
+        return sourceGap(base, "design source needs origin.url, origin.apiUrl, origin.exportUrl, or a local exportPath/assetPath/filePath before acquisition", designProviderGapMetadata("missing-provider-locator", entry.source, figmaLocator));
     }
     if (!opts.allowNetwork) {
-        return blockedAdapter(base, opts.browser ? "design-browser-render" : "design-api-or-browser", "design source requires --allow-network with token/export URL or --browser storageState acquisition", designProviderGapMetadata("network-not-allowed"));
+        return blockedAdapter(base, opts.browser ? "design-browser-render" : "design-api-or-browser", "design source requires --allow-network with token/export URL or --browser storageState acquisition", designProviderGapMetadata("network-not-allowed", entry.source, figmaLocator));
     }
     const directRuntimeAuth = await hasDirectRuntimeAuthForSource(entry.source, url, authStatePath);
     if (opts.browser && !directRuntimeAuth) {
         const rendered = await fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
         return {
             ...rendered,
-            adapter: "design-source",
+            adapter,
             metadata: cleanMetadata({ provider: base.provider, acquisition: "browser" }),
         };
     }
@@ -579,29 +645,35 @@ async function runDesignAdapter(target, entry, snapshotPath, previousSnapshotHas
     if (!fetched.ok) {
         if (opts.browser)
             return fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
-        return blockedAdapter(base, "design-api-or-export", fetched.reason, designProviderGapMetadata("provider-fetch-failed"));
+        return blockedAdapter(base, "design-api-or-export", fetched.reason, designProviderGapMetadata("provider-fetch-failed", entry.source, figmaLocator));
     }
     if (looksLikeLoginPage(fetched.body, fetched.resolvedOrigin)) {
         if (opts.browser)
             return fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
-        return blockedAdapter(base, "design-api-or-export", "design adapter resolved to login/chrome content; previous snapshot was preserved", designProviderGapMetadata("provider-auth-blocked"));
+        return blockedAdapter(base, "design-api-or-export", "design adapter resolved to login/chrome content; previous snapshot was preserved", designProviderGapMetadata("provider-auth-blocked", entry.source, figmaLocator));
     }
     const content = renderDesignMarkdown(fetched.body, fetched.resolvedOrigin, fetched.contentType);
     if (!hasMaterialContent(content)) {
         if (opts.browser)
             return fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previousSnapshotHash, authStatePath);
-        return blockedAdapter(base, "design-api-or-export", "design adapter produced no material design content; previous snapshot was preserved", designProviderGapMetadata("provider-content-incomplete"));
+        return blockedAdapter(base, "design-api-or-export", "design adapter produced no material design content; previous snapshot was preserved", designProviderGapMetadata("provider-content-incomplete", entry.source, figmaLocator));
     }
     return writeAdapterSnapshot(target, entry, snapshotPath, previousSnapshotHash, {
-        adapter: "design-source",
+        adapter,
         strategy: "design-api-or-export",
         resolvedOrigin: fetched.resolvedOrigin,
         contentType: fetched.contentType,
         content,
         reason: "design source fetched and normalized into structured Markdown",
-        metadata: cleanMetadata({ provider: base.provider, runtimeAuth: fetched.authSources.join(", ") || undefined }),
+        metadata: cleanMetadata({
+            provider: base.provider,
+            runtimeAuth: fetched.authSources.join(", ") || undefined,
+            derivedApiUrl,
+            fileKey: figmaLocator?.fileKey,
+            nodeId: figmaLocator?.nodeId,
+        }),
         validation: { httpOk: "pass", loginPageRejected: "pass", bodyContent: "pass", snapshotWritten: "pass" },
-    });
+    }, sharedSnapshot);
 }
 function adapterBase(target, entry, snapshotPath, previousSnapshotHash, adapter) {
     const origin = inferSourceOrigin(entry.source);
@@ -617,12 +689,10 @@ function adapterBase(target, entry, snapshotPath, previousSnapshotHash, adapter)
         previousSnapshotHash,
     };
 }
-async function writeAdapterSnapshot(target, entry, snapshotPath, previousSnapshotHash, result) {
+async function writeAdapterSnapshot(target, entry, snapshotPath, previousSnapshotHash, result, sharedSnapshot) {
     const origin = inferSourceOrigin(entry.source);
-    const markdown = renderAdapterMarkdown(entry, result.resolvedOrigin, result.contentType, result.content, result.strategy, result.adapter, result.metadata);
-    await mkdir(dirname(snapshotPath), { recursive: true });
-    await writeFile(snapshotPath, markdown, "utf8");
-    const snapshotHash = await sha256(snapshotPath);
+    const markdown = renderAdapterMarkdown(entry, result.resolvedOrigin, result.contentType, result.content, result.strategy, result.adapter, result.metadata, sharedSnapshot);
+    const written = await writePreparedSnapshot(target, snapshotPath, markdown, previousSnapshotHash);
     return {
         envelopeVersion: 1,
         sourceKey: entry.id,
@@ -635,11 +705,11 @@ async function writeAdapterSnapshot(target, entry, snapshotPath, previousSnapsho
         origin: origin.ref,
         resolvedOrigin: result.resolvedOrigin,
         contentType: result.contentType,
-        snapshot: relative(target, snapshotPath),
-        snapshotHash,
+        snapshot: written.snapshot,
+        snapshotHash: written.snapshotHash,
         previousSnapshotHash,
         metadata: result.metadata,
-        changed: previousSnapshotHash !== snapshotHash,
+        changed: written.changed,
         reason: result.reason,
         validation: result.validation,
     };
@@ -663,13 +733,18 @@ async function headersForSource(source, url, authStatePath) {
     const authSources = [];
     const token = envValue(authStringList(source, "tokenEnv", "accessTokenEnv", "apiTokenEnv"));
     if (token.value) {
-        const headerName = firstAuthString(source, "tokenHeader", "headerName") ?? "authorization";
-        const tokenScheme = firstAuthString(source, "tokenScheme", "scheme") ?? "Bearer";
+        const headerName = firstAuthString(source, "tokenHeader", "headerName") ?? defaultTokenHeader(source);
+        const tokenScheme = firstAuthString(source, "tokenScheme", "scheme") ?? defaultTokenScheme(source, headerName);
         headers[headerName] = headerName.toLowerCase() === "authorization" && tokenScheme
             ? `${tokenScheme} ${token.value}`
             : token.value;
         authSources.push(`env:${token.name}`);
     }
+    const basic = basicAuthHeaderFromEnvironment(source);
+    if (!headers.authorization && basic.value) {
+        headers.authorization = basic.value;
+        authSources.push(...basic.sources.map((name) => `env:${name}`));
+    }
     const envCookie = cookieHeaderFromEnvironment(source);
     if (envCookie.source)
         authSources.push(`env:${envCookie.source}`);
@@ -683,7 +758,10 @@ async function headersForSource(source, url, authStatePath) {
 }
 async function hasDirectRuntimeAuthForSource(source, url, authStatePath) {
     const { headers } = await headersForSource(source, url, authStatePath);
-    return Boolean(headers.authorization || headers.cookie);
+    return hasRuntimeAuthHeaders(headers);
+}
+function hasRuntimeAuthHeaders(headers) {
+    return Object.keys(headers).length > 0;
 }
 async function fetchUrlSnapshot(target, entry, snapshotPath, previousSnapshotHash, authStatePath) {
     const origin = inferSourceOrigin(entry.source);
@@ -718,17 +796,15 @@ async function fetchUrlSnapshot(target, entry, snapshotPath, previousSnapshotHas
             return blocked(base, "remote fetch produced no material body content; previous snapshot was preserved");
         }
         const markdown = renderRemoteMarkdown(entry, response.url, contentType, content);
-        await mkdir(dirname(snapshotPath), { recursive: true });
-        await writeFile(snapshotPath, markdown, "utf8");
-        const snapshotHash = await sha256(snapshotPath);
+        const written = await writePreparedSnapshot(target, snapshotPath, markdown, previousSnapshotHash);
         return {
             ...base,
             strategy: authSources.length > 0 ? "runtime-auth-direct-fetch" : "direct-fetch-structured-markdown",
             status: "materialized",
             resolvedOrigin: response.url,
             contentType,
-            snapshotHash,
-            changed: previousSnapshotHash !== snapshotHash,
+            snapshotHash: written.snapshotHash,
+            changed: written.changed,
             reason: "remote URL fetched and normalized into structured Markdown",
             metadata: cleanMetadata({ runtimeAuth: authSources.join(", ") || undefined }),
             validation: { httpOk: "pass", loginPageRejected: "pass", bodyContent: "pass", snapshotWritten: "pass" },
@@ -773,17 +849,15 @@ async function fetchUrlSnapshotWithBrowser(target, entry, snapshotPath, previous
                 return blocked(base, "browser acquisition produced no material body content; previous snapshot was preserved");
             }
             const markdown = renderRemoteMarkdown(entry, resolvedUrl, "text/html; rendered=playwright", content, "playwright-headless-browser");
-            await mkdir(dirname(snapshotPath), { recursive: true });
-            await writeFile(snapshotPath, markdown, "utf8");
-            const snapshotHash = await sha256(snapshotPath);
+            const written = await writePreparedSnapshot(target, snapshotPath, markdown, previousSnapshotHash);
             return {
                 ...base,
                 strategy: "playwright-headless-browser",
                 status: "materialized",
                 resolvedOrigin: resolvedUrl,
                 contentType: "text/html; rendered=playwright",
-                snapshotHash,
-                changed: previousSnapshotHash !== snapshotHash,
+                snapshotHash: written.snapshotHash,
+                changed: written.changed,
                 reason: "remote URL rendered through Playwright and normalized into structured Markdown",
                 validation: { browserRendered: "pass", loginPageRejected: "pass", bodyContent: "pass", snapshotWritten: "pass" },
             };
@@ -827,6 +901,63 @@ async function renderStructuredLocalMarkdown(target, entry, originPath) {
         "",
     ].filter((line) => typeof line === "string").join("\n");
 }
+async function renderStructuredLocalDirectoryMarkdown(target, entry, originPath) {
+    const entries = await readdir(originPath, { withFileTypes: true }).catch(() => []);
+    const git = await readGitDirectoryMetadata(originPath);
+    return [
+        "---",
+        `sourceKey: ${JSON.stringify(entry.id)}`,
+        `sourcePath: ${JSON.stringify(entry.path)}`,
+        entry.provider !== entry.id ? `sourceAlias: ${JSON.stringify(entry.provider)}` : undefined,
+        `origin: ${JSON.stringify(relative(target, originPath))}`,
+        `extractionMethod: "local-directory-summary"`,
+        `extractedAt: ${JSON.stringify(new Date().toISOString())}`,
+        `snapshotStatus: "metadata-only"`,
+        git.head ? `gitHead: ${JSON.stringify(git.head)}` : undefined,
+        git.status ? `gitStatus: ${JSON.stringify(git.status)}` : undefined,
+        "---",
+        "",
+        "# Directory Resource Snapshot",
+        "",
+        "## Provenance",
+        "",
+        `- Source key: \`${entry.id}\``,
+        entry.provider !== entry.id ? `- Source alias: \`${entry.provider}\`` : undefined,
+        `- Origin: \`${relative(target, originPath)}\``,
+        "- Method: local-directory-summary",
+        git.head ? `- Git HEAD: \`${git.head}\`` : undefined,
+        git.status ? `- Git status: ${git.status}` : undefined,
+        "",
+        "## Top-Level Entries",
+        "",
+        entries.length === 0
+            ? "- Empty directory."
+            : entries
+                .slice(0, 200)
+                .map((entry) => `- ${entry.isDirectory() ? "dir" : "file"}: \`${entry.name}\``)
+                .join("\n"),
+        entries.length > 200 ? `- ... ${entries.length - 200} more entries omitted.` : undefined,
+        "",
+    ].filter((line) => typeof line === "string").join("\n");
+}
+async function readGitDirectoryMetadata(originPath) {
+    const head = await gitOutput(originPath, ["rev-parse", "HEAD"]);
+    const status = await gitOutput(originPath, ["status", "--short"]);
+    return {
+        head,
+        status: status ? "dirty" : head ? "clean" : undefined,
+    };
+}
+async function gitOutput(cwd, args) {
+    try {
+        const { stdout } = await execFileAsync("git", args, { cwd, timeout: 10_000, maxBuffer: 1024 * 1024 });
+        const value = stdout.trim();
+        return value || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function renderRemoteMarkdown(entry, resolvedUrl, contentType, content, extractionMethod = "direct-fetch") {
     return [
         "---",
@@ -855,7 +986,33 @@ function renderRemoteMarkdown(entry, resolvedUrl, contentType, content, extracti
         "",
     ].filter((line) => typeof line === "string").join("\n");
 }
-function renderAdapterMarkdown(entry, resolvedOrigin, contentType, content, extractionMethod, adapter, metadata) {
+function sharedSnapshotProvenance(target, config, entry, entries) {
+    const snapshotPath = resolve(target, resolveSourceSnapshot(config, entry));
+    const shared = entries.filter((candidate) => resolve(target, resolveSourceSnapshot(config, candidate)) === snapshotPath);
+    if (shared.length <= 1)
+        return undefined;
+    return {
+        sourceKeys: shared.map((candidate) => candidate.id),
+        sourcePaths: shared.map((candidate) => candidate.path),
+        sourceAliases: uniqueStrings(shared.map((candidate) => candidate.provider).filter(Boolean)),
+        sourceTypes: uniqueStrings(shared.map(sourceType).filter((value) => Boolean(value))),
+    };
+}
+function sourceType(entry) {
+    return typeof entry.source.type === "string" && entry.source.type.trim() ? entry.source.type : undefined;
+}
+function uniqueStrings(values) {
+    return Array.from(new Set(values));
+}
+function yamlStringList(key, values) {
+    if (values.length === 0)
+        return [];
+    return [
+        `${key}:`,
+        ...values.map((value) => `  - ${JSON.stringify(value)}`),
+    ];
+}
+function renderAdapterMarkdown(entry, resolvedOrigin, contentType, content, extractionMethod, adapter, metadata, sharedSnapshot) {
     const metadataLines = metadata && Object.keys(metadata).length > 0
         ? [
             "## Adapter Metadata",
@@ -864,11 +1021,28 @@ function renderAdapterMarkdown(entry, resolvedOrigin, contentType, content, extr
             "",
         ]
         : [];
+    const sharedFrontmatter = sharedSnapshot
+        ? [
+            `snapshotProvenance: "shared-config-snapshot"`,
+            ...yamlStringList("sourceKeys", sharedSnapshot.sourceKeys),
+            ...yamlStringList("sourcePaths", sharedSnapshot.sourcePaths),
+            ...yamlStringList("sourceAliases", sharedSnapshot.sourceAliases),
+            ...yamlStringList("sourceTypes", sharedSnapshot.sourceTypes),
+        ]
+        : [];
+    const sharedProvenance = sharedSnapshot
+        ? [
+            `- Shared snapshot: ${sharedSnapshot.sourceKeys.length} configured sources`,
+            `- Source keys: ${sharedSnapshot.sourceKeys.map((key) => `\`${key}\``).join(", ")}`,
+            `- Source aliases: ${sharedSnapshot.sourceAliases.map((alias) => `\`${alias}\``).join(", ")}`,
+        ]
+        : [];
     return [
         "---",
         `sourceKey: ${JSON.stringify(entry.id)}`,
         `sourcePath: ${JSON.stringify(entry.path)}`,
         entry.provider !== entry.id ? `sourceAlias: ${JSON.stringify(entry.provider)}` : undefined,
+        ...sharedFrontmatter,
         `origin: ${JSON.stringify(resolvedOrigin)}`,
         `contentType: ${JSON.stringify(contentType)}`,
         `adapter: ${JSON.stringify(adapter)}`,
@@ -883,6 +1057,7 @@ function renderAdapterMarkdown(entry, resolvedOrigin, contentType, content, extr
         "",
         `- Source key: \`${entry.id}\``,
         entry.provider !== entry.id ? `- Source alias: \`${entry.provider}\`` : undefined,
+        ...sharedProvenance,
         `- Resolved origin: \`${resolvedOrigin}\``,
         `- Adapter: ${adapter}`,
         `- Method: ${extractionMethod}`,
@@ -903,6 +1078,75 @@ function confluenceBodyValue(value) {
     const view = recordValue(body, "view");
     return stringValue(storage, "value") ?? stringValue(view, "value") ?? stringValue(value, "content") ?? stringValue(value, "value");
 }
+function parseConfluenceWordExport(body, contentType) {
+    if (!/multipart\/related|application\/vnd\.ms-word|MIME-Version:/i.test(`${contentType}\n${body.slice(0, 512)}`)) {
+        return undefined;
+    }
+    const rootHeadersEnd = body.search(/\r?\n\r?\n/);
+    if (rootHeadersEnd === -1)
+        return undefined;
+    const rootHeaders = parseMimeHeaders(body.slice(0, rootHeadersEnd));
+    const boundary = /boundary="?([^";\r\n]+)"?/i.exec(rootHeaders["content-type"] ?? "")?.[1];
+    if (!boundary)
+        return undefined;
+    const chunks = body.split(`--${boundary}`).slice(1);
+    for (const chunk of chunks) {
+        if (chunk.startsWith("--"))
+            continue;
+        const trimmed = chunk.replace(/^\r?\n/, "");
+        const headerEnd = trimmed.search(/\r?\n\r?\n/);
+        if (headerEnd === -1)
+            continue;
+        const headers = parseMimeHeaders(trimmed.slice(0, headerEnd));
+        if (!/text\/html/i.test(headers["content-type"] ?? ""))
+            continue;
+        const html = decodeMimePartBody(trimmed.slice(headerEnd).replace(/^\r?\n\r?\n?/, ""), headers);
+        return {
+            html,
+            title: decodeHtmlEntities(stripHtml(html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1] ?? "")) || undefined,
+        };
+    }
+    return undefined;
+}
+function parseMimeHeaders(text) {
+    const headers = {};
+    let current;
+    for (const line of text.split(/\r?\n/)) {
+        if (/^\s/.test(line) && current) {
+            headers[current] += ` ${line.trim()}`;
+            continue;
+        }
+        const index = line.indexOf(":");
+        if (index === -1)
+            continue;
+        current = line.slice(0, index).toLowerCase();
+        headers[current] = line.slice(index + 1).trim();
+    }
+    return headers;
+}
+function decodeMimePartBody(body, headers) {
+    const encoding = (headers["content-transfer-encoding"] ?? "").toLowerCase();
+    if (encoding.includes("quoted-printable"))
+        return decodeQuotedPrintable(body);
+    if (encoding.includes("base64"))
+        return Buffer.from(body.replace(/\s+/g, ""), "base64").toString("utf8");
+    return body;
+}
+function decodeQuotedPrintable(input) {
+    const normalized = input.replace(/=\r?\n/g, "");
+    const bytes = [];
+    for (let i = 0; i < normalized.length; i += 1) {
+        if (normalized[i] === "=" && /^[0-9a-fA-F]{2}$/.test(normalized.slice(i + 1, i + 3))) {
+            bytes.push(parseInt(normalized.slice(i + 1, i + 3), 16));
+            i += 2;
+            continue;
+        }
+        const char = normalized[i];
+        if (char)
+            bytes.push(...Buffer.from(char, "utf8"));
+    }
+    return Buffer.from(bytes).toString("utf8");
+}
 function versionValue(value) {
     const version = recordValue(value, "version");
     const number = version?.number;
@@ -1041,13 +1285,230 @@ function designNodeNames(value) {
     const nested = Array.isArray(children) ? children.flatMap(designNodeNames) : [];
     return current ? [current, ...nested] : nested;
 }
-function designProviderGapMetadata(reason) {
+function designProviderGapMetadata(reason, source, figma) {
+    const mcpProvider = source ? interpretSourceAdapter(source).mcpProviderName : undefined;
     return {
         providerGap: reason,
         fallbackEvidenceRequired: true,
+        mcpProvider,
+        derivedApiUrl: figma?.apiUrl,
+        fileKey: figma?.fileKey,
+        nodeId: figma?.nodeId,
+        nextActions: [
+            "configure a local exportPath/assetPath/filePath",
+            "configure origin.mcpCommand + origin.mcpArgs for a Figma MCP capture command",
+            "use Playwright/browser acquisition with --browser when HTML rendering is sufficient",
+            "capture Computer Use or human visual evidence outside the CLI and attach it as a raw source",
+        ].join("; "),
         reconstructionRisk: "semantic UE reconstruction needs provider raw payload, assets/raw files, reconstruction.json, and known gaps before downstream design use",
     };
 }
+function deriveConfluenceRestUrl(source) {
+    const pageId = firstOriginString(source, "pageId", "contentId", "id") ?? confluencePageIdFromUrl(firstOriginString(source, "url"));
+    if (!pageId)
+        return undefined;
+    const base = confluenceBaseUrl(source);
+    if (!base)
+        return undefined;
+    return `${base}/rest/api/content/${encodeURIComponent(pageId)}?expand=body.storage,version`;
+}
+function confluencePageIdFromUrl(value) {
+    if (!value)
+        return undefined;
+    try {
+        const url = new URL(value);
+        return /\/pages\/(\d+)/.exec(url.pathname)?.[1] ?? undefined;
+    }
+    catch {
+        return /\/pages\/(\d+)/.exec(value)?.[1] ?? undefined;
+    }
+}
+function confluenceBaseUrl(source) {
+    const explicit = firstOriginString(source, "baseUrl", "siteUrl", "host");
+    if (explicit)
+        return trimTrailingSlash(explicit);
+    const pageUrl = firstOriginString(source, "url");
+    if (!pageUrl)
+        return undefined;
+    try {
+        const url = new URL(pageUrl);
+        const wikiPrefix = url.pathname.startsWith("/wiki/") ? "/wiki" : "";
+        return `${url.protocol}//${url.host}${wikiPrefix}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+function deriveJiraRestUrl(source) {
+    const explicitIssue = firstOriginString(source, "issueKey", "key", "id") ?? jiraIssueKeyFromUrl(firstOriginString(source, "url"));
+    const query = firstOriginString(source, "jql", "query");
+    const base = jiraBaseUrl(source);
+    if (!base)
+        return undefined;
+    if (explicitIssue)
+        return `${base}/rest/api/3/issue/${encodeURIComponent(explicitIssue)}`;
+    if (query)
+        return `${base}/rest/api/3/search?jql=${encodeURIComponent(query)}`;
+    return undefined;
+}
+function jiraIssueKeyFromUrl(value) {
+    if (!value)
+        return undefined;
+    try {
+        const url = new URL(value);
+        return /\/browse\/([A-Z][A-Z0-9_]+-\d+)/i.exec(url.pathname)?.[1] ?? undefined;
+    }
+    catch {
+        return /\/browse\/([A-Z][A-Z0-9_]+-\d+)/i.exec(value)?.[1] ?? undefined;
+    }
+}
+function jiraBaseUrl(source) {
+    const explicit = firstOriginString(source, "baseUrl", "siteUrl", "host");
+    if (explicit)
+        return trimTrailingSlash(explicit);
+    const urlValue = firstOriginString(source, "url");
+    if (!urlValue)
+        return undefined;
+    try {
+        const url = new URL(urlValue);
+        return `${url.protocol}//${url.host}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+function figmaLocatorForSource(source) {
+    if (!isFigmaSource(source))
+        return undefined;
+    const sourceUrl = firstOriginString(source, "url");
+    const fileKey = firstOriginString(source, "fileKey", "file_key", "fileId", "file_id", "id") ?? figmaFileKeyFromUrl(sourceUrl);
+    const nodeId = normalizeFigmaNodeId(firstOriginString(source, "nodeId", "node_id") ?? figmaNodeIdFromUrl(sourceUrl));
+    const explicitApiUrl = firstOriginString(source, "apiUrl", "exportUrl");
+    const apiUrl = explicitApiUrl ?? (fileKey ? figmaApiUrl(fileKey, nodeId) : undefined);
+    return cleanMetadata({ sourceUrl, fileKey, nodeId, apiUrl });
+}
+function isFigmaSource(source) {
+    return [
+        source.origin?.kind,
+        source.origin?.provider,
+        source.kind,
+        source.type,
+        firstOriginString(source, "mcpProvider", "mcpServer"),
+        firstOriginString(source, "url"),
+    ]
+        .filter((value) => typeof value === "string")
+        .some((value) => value.toLowerCase().includes("figma"));
+}
+function figmaFileKeyFromUrl(value) {
+    if (!value)
+        return undefined;
+    try {
+        const url = new URL(value);
+        return /\/(?:file|design)\/([^/?#]+)/i.exec(url.pathname)?.[1] ?? undefined;
+    }
+    catch {
+        return /\/(?:file|design)\/([^/?#]+)/i.exec(value)?.[1] ?? undefined;
+    }
+}
+function figmaNodeIdFromUrl(value) {
+    if (!value)
+        return undefined;
+    try {
+        return new URL(value).searchParams.get("node-id") ?? undefined;
+    }
+    catch {
+        return /[?&]node-id=([^&#]+)/i.exec(value)?.[1] ?? undefined;
+    }
+}
+function normalizeFigmaNodeId(value) {
+    if (!value)
+        return undefined;
+    const decoded = decodeURIComponent(value.trim());
+    return decoded.includes(":") ? decoded : decoded.replace("-", ":");
+}
+function figmaApiUrl(fileKey, nodeId) {
+    const encodedFileKey = encodeURIComponent(fileKey);
+    if (nodeId)
+        return `https://api.figma.com/v1/files/${encodedFileKey}/nodes?ids=${encodeURIComponent(nodeId)}`;
+    return `https://api.figma.com/v1/files/${encodedFileKey}`;
+}
+function figmaCommandForSource(source, target, snapshot, figma) {
+    const command = firstOriginString(source, "mcpCommand", "command", "exportCommand");
+    if (!command)
+        return undefined;
+    const args = originStringList(source, "mcpArgs", "args", "commandArgs")
+        .map((arg) => renderCommandTemplate(arg, source, snapshot, figma));
+    const provider = interpretSourceAdapter(source).mcpProviderName;
+    const contentType = firstOriginString(source, "commandContentType", "contentType") ?? "application/json";
+    const timeoutMs = numberOriginValue(source, "timeoutMs") ?? DEFAULT_ADAPTER_COMMAND_TIMEOUT_MS;
+    const resolvedCommand = resolveCommandForTarget(target, command);
+    return {
+        command: resolvedCommand,
+        args,
+        provider,
+        safeLabel: `${command} (${args.length} args)`,
+        contentType,
+        timeoutMs,
+    };
+}
+async function runDesignCommand(target, command) {
+    try {
+        const { stdout } = await execFileAsync(command.command, command.args, {
+            cwd: target,
+            env: process.env,
+            timeout: command.timeoutMs,
+            maxBuffer: DEFAULT_ADAPTER_COMMAND_MAX_BUFFER,
+        });
+        const body = stdout.trim();
+        if (!body)
+            return { ok: false, reason: "configured design command exited without stdout content" };
+        return {
+            ok: true,
+            body,
+            contentType: command.contentType,
+            origin: `command:${command.safeLabel}`,
+        };
+    }
+    catch (error) {
+        const code = isRecord(error) && (typeof error.code === "number" || typeof error.code === "string") ? String(error.code) : "unknown";
+        return {
+            ok: false,
+            reason: `configured design command failed without exposing stdout/stderr content (code: ${code})`,
+        };
+    }
+}
+function originStringList(source, ...keys) {
+    const origin = source.origin;
+    const values = [];
+    for (const key of keys) {
+        values.push(...stringListValue(origin?.[key]));
+    }
+    return values;
+}
+function numberOriginValue(source, key) {
+    const value = source.origin?.[key];
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+function renderCommandTemplate(value, source, snapshot, figma) {
+    const replacements = {
+        url: firstOriginString(source, "url") ?? "",
+        fileKey: figma?.fileKey ?? "",
+        file_key: figma?.fileKey ?? "",
+        nodeId: figma?.nodeId ?? "",
+        node_id: figma?.nodeId ?? "",
+        apiUrl: figma?.apiUrl ?? "",
+        snapshot,
+    };
+    return value.replace(/\{\{\s*([A-Za-z0-9_]+)\s*\}\}/g, (_, key) => replacements[key] ?? "");
+}
+function resolveCommandForTarget(target, command) {
+    if (command.includes("/") || command.includes("\\"))
+        return resolve(target, command);
+    return command;
+}
+function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
 function parseCsvRows(value) {
     const rows = parseCsv(value).filter((row) => row.some((cell) => cell.trim().length > 0));
     const headers = rows.shift() ?? [];
@@ -1138,10 +1599,11 @@ function firstCsvValue(row, ...keys) {
 }
 function firstOriginString(source, ...keys) {
     const origin = source.origin;
-    if (!origin)
-        return undefined;
     for (const key of keys) {
-        const value = origin[key];
+        const sourceValue = source[key];
+        if (typeof sourceValue === "string" && sourceValue.trim().length > 0)
+            return sourceValue.trim();
+        const value = origin?.[key];
         if (typeof value === "string" && value.trim().length > 0)
             return value.trim();
     }
@@ -1162,9 +1624,13 @@ function authStringList(source, ...keys) {
     for (const key of keys) {
         values.push(...stringListValue(auth?.[key]));
     }
+    if (keys.some((key) => ["tokenEnv", "accessTokenEnv", "apiTokenEnv"].includes(key))) {
+        values.push(...stringListValue(auth?.env));
+    }
     for (const key of keys) {
         values.push(...stringListValue(source.origin?.[key]));
     }
+    values.push(...defaultAuthEnvNames(source, keys));
     return Array.from(new Set(values));
 }
 function authCookieMap(source) {
@@ -1199,6 +1665,77 @@ function envValue(names) {
     }
     return {};
 }
+function basicAuthHeaderFromEnvironment(source) {
+    const username = envValue(authStringList(source, "usernameEnv", "userEnv", "basicUsernameEnv", "basicUserEnv"));
+    const password = envValue(authStringList(source, "passwordEnv", "passEnv", "basicPasswordEnv", "basicPassEnv"));
+    if (!username.value || !password.value)
+        return { sources: [] };
+    return {
+        sources: [username.name, password.name].filter((name) => Boolean(name)),
+        value: `Basic ${Buffer.from(`${username.value}:${password.value}`).toString("base64")}`,
+    };
+}
+function defaultAuthEnvNames(source, keys) {
+    const provider = sourceProviderToken(source);
+    if (!provider)
+        return [];
+    if (keys.some((key) => ["tokenEnv", "accessTokenEnv", "apiTokenEnv"].includes(key))) {
+        if (provider.includes("figma"))
+            return ["FIGMA_ACCESS_TOKEN", "FIGMA_TOKEN", "FIGMA_API_TOKEN"];
+        if (provider.includes("gitlab"))
+            return ["GITLAB_TOKEN", "GITLAB_ACCESS_TOKEN", "GITLAB_PRIVATE_TOKEN"];
+        if (provider.includes("jira"))
+            return ["ACCESS_TOKEN", "JIRA_ACCESS_TOKEN", "JIRA_TOKEN"];
+        if (provider.includes("confluence"))
+            return ["CONFLUENCE_ACCESS_TOKEN", "CONFLUENCE_TOKEN"];
+    }
+    if (keys.some((key) => ["usernameEnv", "userEnv", "basicUsernameEnv", "basicUserEnv"].includes(key))) {
+        if (provider.includes("jira"))
+            return ["JIRA_USER", "JIRA_USERNAME", "ATLASSIAN_EMAIL", "ATLASSIAN_USER"];
+        if (provider.includes("confluence"))
+            return ["CONFLUENCE_USER", "CONFLUENCE_USERNAME", "ATLASSIAN_EMAIL", "ATLASSIAN_USER"];
+    }
+    if (keys.some((key) => ["passwordEnv", "passEnv", "basicPasswordEnv", "basicPassEnv"].includes(key))) {
+        if (provider.includes("jira"))
+            return ["JIRA_API_TOKEN", "JIRA_PASSWORD", "ATLASSIAN_API_TOKEN", "ATLASSIAN_TOKEN"];
+        if (provider.includes("confluence"))
+            return ["CONFLUENCE_API_TOKEN", "CONFLUENCE_PASSWORD", "ATLASSIAN_API_TOKEN", "ATLASSIAN_TOKEN"];
+    }
+    return [];
+}
+function defaultTokenHeader(source) {
+    const provider = sourceProviderToken(source);
+    if (provider?.includes("figma"))
+        return "X-Figma-Token";
+    if (provider?.includes("gitlab"))
+        return "PRIVATE-TOKEN";
+    return "authorization";
+}
+function defaultTokenScheme(source, headerName) {
+    const provider = sourceProviderToken(source);
+    if (headerName.toLowerCase() !== "authorization")
+        return "";
+    if (provider?.includes("figma") || provider?.includes("gitlab"))
+        return "";
+    return "Bearer";
+}
+function sourceProviderToken(source) {
+    const origin = inferSourceOrigin(source);
+    return [
+        origin.provider,
+        origin.kind,
+        source.origin?.provider,
+        source.origin?.kind,
+        source.kind,
+        source.type,
+    ]
+        .filter((value) => typeof value === "string" && value.trim().length > 0)
+        .map((value) => value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""))
+        .find((value) => value.includes("figma") ||
+        value.includes("jira") ||
+        value.includes("confluence") ||
+        value.includes("gitlab"));
+}
 function cookieHeaderFromEnvironment(source) {
     const parts = [];
     const sources = [];
@@ -1253,15 +1790,6 @@ function contentTypeForPath(path) {
         return "text/html";
     return "text/plain";
 }
-function escapeTable(value) {
-    return value.replace(/\|/g, "\\|").replace(/\n/g, " ");
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function normalizeAdapterKey(value) {
-    return value?.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") ?? "";
-}
 function renderRepositoryMetadata(entry, repository) {
     return [
         "---",
@@ -1295,6 +1823,7 @@ function htmlToStructuredMarkdown(value) {
         .replace(/<style[\s\S]*?<\/style>/gi, "")
         .replace(/<(nav|header|footer|aside)[^>]*>[\s\S]*?<\/\1>/gi, "");
     return body
+        .replace(/<table\b[^>]*>[\s\S]*?<\/table>/gi, (table) => `\n${htmlTableToMarkdown(table)}\n`)
         .replace(/<h1[^>]*>([\s\S]*?)<\/h1>/gi, "\n# $1\n")
         .replace(/<h2[^>]*>([\s\S]*?)<\/h2>/gi, "\n## $1\n")
         .replace(/<h3[^>]*>([\s\S]*?)<\/h3>/gi, "\n### $1\n")
@@ -1305,14 +1834,60 @@ function htmlToStructuredMarkdown(value) {
         .replace(/<a\b[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi, "[$2]($1)")
         .replace(/<[^>]+>/g, "")
         .replace(/&nbsp;/g, " ")
+        .split("\n")
+        .map((line) => decodeHtmlEntities(line).trim())
+        .filter((line, index, lines) => line.length > 0 || lines[index - 1]?.length)
+        .join("\n");
+}
+function htmlTableToMarkdown(table) {
+    const rows = Array.from(table.matchAll(/<tr\b[^>]*>([\s\S]*?)<\/tr>/gi))
+        .map((row) => Array.from((row[1] ?? "").matchAll(/<(td|th)\b[^>]*>([\s\S]*?)<\/\1>/gi))
+        .map((cell) => tableCellText(cell[2] ?? "")))
+        .filter((row) => row.some((cell) => cell.length > 0));
+    if (!rows.length)
+        return "";
+    const width = Math.max(...rows.map((row) => row.length));
+    const normalized = rows.map((row) => {
+        const copy = row.slice();
+        while (copy.length < width)
+            copy.push("");
+        return copy;
+    });
+    const header = normalized[0] ?? [];
+    if (!header.length)
+        return "";
+    const body = normalized.slice(1);
+    return [
+        `| ${header.join(" | ")} |`,
+        `| ${header.map(() => "---").join(" | ")} |`,
+        ...body.map((row) => `| ${row.join(" | ")} |`),
+    ].join("\n");
+}
+function tableCellText(value) {
+    return decodeHtmlEntities(stripHtml(value
+        .replace(/<br\s*\/?>/gi, " ZSK_BR ")
+        .replace(/<\/(p|div|section|li)>/gi, " ZSK_BR ")
+        .replace(/<li\b[^>]*>/gi, "- ")))
+        .replace(/\s*ZSK_BR\s*/g, "; ")
+        .replace(/[ \t\r\n]+/g, " ")
+        .replace(/(?:\s*;\s*){2,}/g, "; ")
+        .replace(/^\s*;\s*|\s*;\s*$/g, "")
+        .replace(/\|/g, "\\|")
+        .trim();
+}
+function stripHtml(value) {
+    return value.replace(/<[^>]+>/g, "");
+}
+function decodeHtmlEntities(value) {
+    return value
+        .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+        .replace(/&#x([0-9a-fA-F]+);/g, (_, code) => String.fromCodePoint(parseInt(code, 16)))
+        .replace(/&nbsp;/g, " ")
         .replace(/&amp;/g, "&")
         .replace(/&lt;/g, "<")
         .replace(/&gt;/g, ">")
         .replace(/&quot;/g, "\"")
-        .split("\n")
-        .map((line) => line.trim())
-        .filter((line, index, lines) => line.length > 0 || lines[index - 1]?.length)
-        .join("\n");
+        .replace(/&apos;/g, "'");
 }
 function fencedBody(body, contentType) {
     const info = contentType.includes("json")
@@ -1330,34 +1905,6 @@ function shouldPreserveMachineReadable(source, originPath, snapshotPath) {
         [".json", ".yaml", ".yml"].includes(ext) ||
         [".json", ".yaml", ".yml"].includes(snapshotExt));
 }
-function chooseStrategy(method) {
-    if (method === "local")
-        return "local-copy-structured-markdown";
-    if (method === "repository")
-        return "repository-metadata-only";
-    if (method === "url")
-        return "playwright-auth-or-direct-fetch";
-    return "confirm-acquisition-method";
-}
-function renderDownstreamImpact(results) {
-    const changed = results.filter((result) => result.changed);
-    const blocked = results.filter((result) => ["blocked-auth", "source-gap", "failed"].includes(result.status));
-    return [
-        "# Downstream Impact",
-        "",
-        `Changed sources: ${changed.length}`,
-        `Blocked sources: ${blocked.length}`,
-        "",
-        changed.length === 0
-            ? "No downstream refresh is recommended from this sync run."
-            : changed.map((result) => `- \`${result.sourcePath}\`: snapshot changed; review dependent proposal/spec/design/tasks/tests before claiming freshness.`).join("\n"),
-        "",
-        blocked.length === 0
-            ? "No blocked sources."
-            : blocked.map((result) => `- \`${result.sourcePath}\` [${result.status}]: ${result.reason}`).join("\n"),
-        "",
-    ].join("\n");
-}
 async function cookieHeaderFromStorageState(storageStatePath, url) {
     try {
         const parsed = JSON.parse(await readFile(storageStatePath, "utf8"));
@@ -1441,74 +1988,46 @@ async function loadProjectPlaywright(target) {
     }
     return await import(resolved);
 }
-async function hashIfExists(path) {
+async function safeStat(path) {
     try {
-        return await sha256(path);
+        const info = await stat(path);
+        return { isDirectory: info.isDirectory(), isFile: info.isFile() };
     }
     catch {
-        return undefined;
+        return null;
     }
 }
-async function sha256(path) {
-    const content = await readFile(path);
-    return `sha256:${createHash("sha256").update(content).digest("hex")}`;
-}
-async function exists(path) {
-    try {
-        await stat(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
+function isGitSubmoduleResource(source) {
+    const values = [
+        source.kind,
+        source.type,
+        source.origin?.kind,
+        source.metadata?.resourceType,
+    ].map((value) => typeof value === "string" ? value.toLowerCase() : "");
+    return values.some((value) => value === "git-submodule" || value === "submodule");
 }
-async function safeReadDir(path) {
+async function updateGitSubmodule(target, sourcePath) {
     try {
-        return await import("node:fs/promises").then((fs) => fs.readdir(path, { withFileTypes: true }));
+        await execFileAsync("git", ["-C", target, "submodule", "update", "--init", "--remote", "--", sourcePath], {
+            timeout: 120_000,
+            maxBuffer: DEFAULT_ADAPTER_COMMAND_MAX_BUFFER,
+        });
+        return { ok: true };
     }
-    catch {
-        return [];
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return { ok: false, reason: `git submodule update failed for ${sourcePath}: ${reason}` };
     }
 }
-function safeFileName(value) {
-    return value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "source";
-}
-function isMigrationLaneCandidate(value, staleNames) {
-    return (staleNames.has(value) ||
-        /^v?\d+(?:[._-]\d+)*$/i.test(value) ||
-        /^(sprint|iteration|release)[-_]?\d*/i.test(value));
-}
-function resolveAuthStatePath(target, config, authState) {
-    const statePath = resolve(target, authState);
-    const sharedAuthRoot = resolve(target, getWorkspacePath(config, "playwrightRoot"), ".auth");
-    const modulesRoot = resolve(target, getWorkspacePath(config, "modulesRoot"));
-    const pathParts = statePath.split(/[\\/]/);
-    const modulePrivate = isInside(modulesRoot, statePath) && pathParts.includes("_playwright") && pathParts.includes(".auth");
-    if (isInside(sharedAuthRoot, statePath) || modulePrivate)
-        return statePath;
-    throw new Error(`Playwright storageState input must stay under ${sharedAuthRoot} or a module _playwright/.auth directory`);
-}
 function resolveSelectedAuthStatePath(target, config, opts) {
     if (opts.authState)
-        return resolveAuthStatePath(target, config, opts.authState);
+        return resolvePlaywrightAuthStatePath(target, config, opts.authState);
     if (opts.authProfile)
-        return resolveAuthProfilePath(target, config, opts.authProfile);
+        return resolvePlaywrightAuthProfilePath(target, config, opts.authProfile);
     return undefined;
 }
-function resolveAuthProfilePath(target, config, profile) {
-    const authRoot = resolve(target, getWorkspacePath(config, "playwrightRoot"), ".auth");
-    const fileName = profile ? `${safeFileName(profile)}.json` : "user_data.json";
-    return join(authRoot, fileName);
-}
 function resolveAdapterLocalFilePath(target, value) {
     const path = resolve(target, value);
-    return isInside(resolve(target), path) ? path : undefined;
-}
-function isInside(root, target) {
-    const rel = relative(root, target);
-    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
-}
-export function createSyncRunId(now = new Date()) {
-    return now.toISOString().replace(/[:.]/g, "-");
+    return isPathInside(resolve(target), path) ? path : undefined;
 }
 //# sourceMappingURL=prepare-sync.js.map