nexarch 0.12.23 → 0.12.26

package/dist/commands/enroll.js

@@ -0,0 +1,128 @@
+import { hostname, platform, arch } from "node:os";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { expandHomePath, supportsAutoWrite, writeClientConfig } from "../lib/client-config-writers.js";
+// Matches www.nexarch.ai — the default production host for the web app that
+// owns /api/agent-enrollments/exchange. Not the same service as
+// mcp.nexarch.ai (the MCP gateway); --host exists because staging and
+// self-hosted deployments serve the exchange route from a different origin.
+const DEFAULT_EXCHANGE_HOST = "https://www.nexarch.ai";
+function renderInstructions(template, manifest, token, mcpEndpoint) {
+    return template
+        .replaceAll("{{envVarBraced}}", `\${${manifest.mcp.auth.environmentVariable}}`)
+        .replaceAll("{{envVar}}", manifest.mcp.auth.environmentVariable)
+        .replaceAll("{{mcpUrl}}", mcpEndpoint)
+        .replaceAll("{{serverKey}}", manifest.mcp.serverName)
+        .replaceAll("{{token}}", token);
+}
+const ERROR_MESSAGES = {
+    enrollment_invalid: "The enrollment code is invalid, expired, or already used. Ask whoever created it to issue a new one.",
+    enrollment_client_mismatch: "This code was issued for a different client type than the one passed to --client. Check the client code against the one configured when the enrollment was created.",
+    server_not_configured: "The Nexarch server is missing its gateway URL configuration (MCP_GATEWAY_PUBLIC_URL). This is a server-side issue — ask whoever operates that deployment to set it, then retry with the same code.",
+};
+function parseFlag(args, flag) {
+    return args.includes(flag);
+}
+function parseOptionValue(args, option) {
+    const idx = args.indexOf(option);
+    if (idx === -1)
+        return null;
+    const value = args[idx + 1];
+    if (!value || value.startsWith("--"))
+        return null;
+    return value;
+}
+function redactedManifest(manifest) {
+    return { ...manifest, credential: { ...manifest.credential, token: "(redacted — see saved file, or pass --print-token)" } };
+}
+/**
+ * Bootstraps a headless (browserless) MCP agent by redeeming a one-time
+ * enrollment code for a long-lived credential — the CLI equivalent of the
+ * curl snippet the workspace UI shows (headless-enrollment-form.tsx). Reuses
+ * the exact same unauthenticated exchange endpoint; the only thing this adds
+ * is host/platform auto-detection, an error message per failure mode instead
+ * of a raw JSON blob, and keeping the credential out of stdout/shell history
+ * by default.
+ */
+export async function enroll(args) {
+    const asJson = parseFlag(args, "--json");
+    const printToken = parseFlag(args, "--print-token");
+    const skipClientConfig = parseFlag(args, "--skip-client-config");
+    const code = parseOptionValue(args, "--code");
+    const clientCode = parseOptionValue(args, "--client");
+    const clientVersion = parseOptionValue(args, "--client-version");
+    const host = parseOptionValue(args, "--host") ?? DEFAULT_EXCHANGE_HOST;
+    const outPath = parseOptionValue(args, "--out");
+    if (!code || !code.startsWith("nxe_")) {
+        throw new Error("Missing or invalid --code (expected a one-time code starting with 'nxe_' from the workspace UI).");
+    }
+    if (!clientCode) {
+        throw new Error("Missing --client (the client code configured for this enrollment, e.g. hermes-agent).");
+    }
+    const res = await fetch(`${host}/api/agent-enrollments/exchange`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            code,
+            client: { code: clientCode, version: clientVersion ?? undefined },
+            host: { hostname: hostname(), platform: platform(), arch: arch() },
+        }),
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+        const errorCode = typeof body.error === "string" ? body.error : null;
+        const message = (errorCode && ERROR_MESSAGES[errorCode]) ?? `Enrollment exchange failed (${errorCode ?? res.status}).`;
+        throw new Error(message);
+    }
+    const manifest = body;
+    const destination = outPath ?? join(homedir(), ".nexarch", "agent-credential.json");
+    mkdirSync(dirname(destination), { recursive: true });
+    writeFileSync(destination, JSON.stringify(manifest, null, 2), { mode: 0o600 });
+    // The gateway's JSON-RPC endpoint is always {mcp.url}/mcp — mcp.url on the
+    // manifest is the bare origin (e.g. https://mcp.nexarch.ai), matching the
+    // convention nexarch mcp-config already uses for the same gateway.
+    const mcpEndpoint = `${manifest.mcp.url.replace(/\/$/, "")}/mcp`;
+    let wroteClientConfig = false;
+    if (!skipClientConfig && manifest.envFilePath && manifest.mcpConfigPath && supportsAutoWrite(manifest.mcpConfigMergeStrategy)) {
+        writeClientConfig(manifest.mcpConfigMergeStrategy, {
+            envFilePath: expandHomePath(manifest.envFilePath),
+            mcpConfigPath: expandHomePath(manifest.mcpConfigPath),
+            serverKey: manifest.mcp.serverName,
+            envVar: manifest.mcp.auth.environmentVariable,
+            mcpUrl: mcpEndpoint,
+            token: manifest.credential.token,
+        });
+        wroteClientConfig = true;
+    }
+    if (asJson) {
+        const output = printToken ? manifest : redactedManifest(manifest);
+        process.stdout.write(`${JSON.stringify({ ...output, wroteClientConfig }, null, 2)}\n`);
+        return;
+    }
+    console.log(`✓ Enrolled agent ${manifest.agent.ref} in workspace "${manifest.workspace.name}"`);
+    console.log(`  Scopes     : ${manifest.credential.scopes.join(", ")}`);
+    console.log(`  Expires    : ${manifest.credential.expiresAt ?? "never"}`);
+    console.log(`  MCP server : ${mcpEndpoint}`);
+    console.log(`  Credential : saved to ${destination} (mode 600)`);
+    if (wroteClientConfig) {
+        console.log(`\n✓ Wired the connection into ${manifest.envFilePath} and ${manifest.mcpConfigPath}`);
+    }
+    else if (skipClientConfig) {
+        console.log(`\nSkipped client config (--skip-client-config passed).`);
+    }
+    else {
+        console.log(`\nNo known auto-write target for client "${clientCode}" — connect it manually:`);
+    }
+    const shownToken = printToken ? manifest.credential.token : `<see ${destination}>`;
+    if (manifest.connectInstructionsTemplate) {
+        console.log(renderInstructions(manifest.connectInstructionsTemplate, manifest, shownToken, mcpEndpoint));
+    }
+    else if (!wroteClientConfig) {
+        console.log(`Export ${manifest.mcp.auth.environmentVariable}=${shownToken} in the agent runtime's own environment, then`);
+        console.log(`point its MCP client at ${mcpEndpoint} (streamable-http, Authorization: Bearer \${${manifest.mcp.auth.environmentVariable}}).`);
+    }
+    if (printToken) {
+        console.log(`\nToken: ${manifest.credential.token}`);
+    }
+}

package/dist/commands/init-agent.js

@@ -8,7 +8,7 @@ import { requireCredentials } from "../lib/credentials.js";
 import { fetchAgentRegistryOrThrow } from "../lib/agent-registry.js";
 import { callMcpTool, mcpInitialize, mcpListTools } from "../lib/mcp.js";
 import { buildVersionAttributes } from "../lib/version-normalization.js";
-import { requestTrustAttestation } from "../lib/trust.js";
+import { requestTrustAttestation, TRUST_ATTESTATION_SCOPE } from "../lib/trust.js";
 const CLI_VERSION = (() => {
     try {
         const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
@@ -443,6 +443,30 @@ function injectAgentConfigs(registry, runtimeCodes, dryRun) {
     }
     return [];
 }
+/**
+ * Whether the trust attestation already sitting in `path` still holds up: present, unexpired,
+ * and minted under the scope this build of the CLI currently mints under. A registration
+ * section can be byte-identical to the current template (so `injectAgentConfigs` reports
+ * `already_present` and writes nothing) while its neighbouring attestation was minted under an
+ * old scope value or has since expired — that staleness is independent of whether the
+ * registration prose changed, so it needs its own check rather than riding on
+ * `already_present` vs `updated`. See ADR-0112.
+ */
+function isTrustAttestationStale(path) {
+    if (!existsSync(path))
+        return true;
+    const content = readFileSync(path, "utf8");
+    const match = content.match(/<!-- nexarch:trust-attestation:start -->\n([\s\S]*?)\n<!-- nexarch:trust-attestation:end -->/);
+    const body = match ? match[1] : content;
+    const scope = body.match(/^scope:\s*(\S+)\s*$/m)?.[1];
+    const expiresAt = body.match(/^expires_at:\s*(\S+)\s*$/m)?.[1];
+    if (!scope || !expiresAt)
+        return true;
+    if (scope !== TRUST_ATTESTATION_SCOPE)
+        return true;
+    const expiry = Date.parse(expiresAt);
+    return Number.isNaN(expiry) || expiry <= Date.now();
+}
 function injectTrustAttestationBlock(path, attestation) {
     // The fallbacks read this very file, so they have to name it: the block is
     // injected into AGENTS.md and .cursorrules too, where a hardcoded CLAUDE.md
@@ -1258,14 +1282,17 @@ export async function initAgent(args) {
             // the dry-run result is accurate and no second pass is needed.
             agentConfigResults = existingInstructionTargets;
         }
-        // Attest only files actually written (injected/updated) just now. When
-        // consent wasn't granted, nothing was written above — `existingInstructionTargets`
-        // is dry-run data with no corresponding file change — so there is
-        // nothing new to attest. An "already_present" target needs no fresh
-        // attestation either: its content, and whatever attestation it already
-        // carries from a prior run, hasn't changed.
+        // Attest files actually written (injected/updated) just now, plus any
+        // "already_present" target whose existing attestation is itself stale
+        // (missing, expired, or minted under an old scope) — the registration
+        // prose matching the template says nothing about whether the neighbouring
+        // attestation is still current, so that's checked independently rather
+        // than assumed from the write status. See ADR-0112 / isTrustAttestationStale.
+        // When consent wasn't granted, nothing was written above —
+        // `existingInstructionTargets` is dry-run data with no corresponding file
+        // change — so there is nothing to attest.
         const attestationTargets = instructionsWriteAllowed
-            ? agentConfigResults.filter((r) => r.status === "injected" || r.status === "updated")
+            ? agentConfigResults.filter((r) => r.status === "injected" || r.status === "updated" || isTrustAttestationStale(r.path))
             : [];
         if (attestationTargets.length > 0) {
             trustAttestationAttempted = true;
@@ -1338,7 +1365,9 @@ export async function initAgent(args) {
                 : !instructionsWriteAllowed
                     ? "skipped (consent not granted)"
                     : !trustAttestationAttempted
-                        ? "skipped (no instruction target written)"
+                        ? agentConfigResults.length > 0
+                            ? "already current (no refresh needed)"
+                            : "skipped (no instruction target written)"
                         : trustAttestation?.ok
                             ? "minted and injected into instruction file(s)"
                             : `unavailable (${trustAttestation?.reason ?? "unknown"})`,

package/dist/commands/init-project-data.js

@@ -0,0 +1,181 @@
+import { basename } from "path";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+import { detectSourceRepository, resolveProjectIdentity } from "./init-project.js";
+/**
+ * Onboarding for a data-pipeline repository: dbt, Airflow, Dagster, Dataform,
+ * ksqlDB, or Spark (data-architecture-plan.md 1.3, H-06).
+ *
+ * Mirrors init-project-infra.ts's shape deliberately: register first, report
+ * what is still outstanding, never claim completion the write did not earn.
+ * Unlike the infrastructure path there is no state to read afterwards — every
+ * component this scan finds is written in the one pass, so a successful,
+ * non-dry-run write is enrichmentCompleted: true outright.
+ *
+ * The pipeline registers as a `project` (ADR 8a: evidence, not architecture,
+ * same identity resolution as a regular repo — H-05) sourcing an
+ * `application` (subtype app_custom_built — no application subtype names
+ * "data pipeline" specifically, and this is a detection fix, not an ontology
+ * change). Its models/DAGs/assets become `application_component` children
+ * using subtypes that already exist and are already legal
+ * (app_comp_data_pipeline, orchestrator_component) — verified live,
+ * 2026-08-24.
+ */
+const RUNTIME_LABEL = {
+    dbt: "dbt model",
+    airflow: "Airflow DAG",
+    dagster: "Dagster asset",
+    dataform: "Dataform definition",
+    ksqldb: "ksqlDB script",
+    spark: "Spark job",
+};
+function readResult(raw) {
+    return JSON.parse(raw.content?.[0]?.text ?? "{}");
+}
+function slugify(value) {
+    return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 80);
+}
+function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+export async function runDataProjectOnboarding(options, detection) {
+    const { dir, nameOverride, asJson, dryRun } = options;
+    const creds = requireCredentials();
+    const runtime = detection.runtime;
+    const displayName = nameOverride ?? basename(dir);
+    const projectDirSlug = slugify(displayName);
+    const detectedRepo = detectSourceRepository(dir);
+    const projectIdentity = dryRun
+        ? { key: `project:${projectDirSlug}`, source: "directory_slug" }
+        : await resolveProjectIdentity(creds.companyId, detectedRepo, displayName, projectDirSlug);
+    const projectRef = projectIdentity.key;
+    // The application and its components derive their slug from the RESOLVED
+    // project identity, not the current checkout's directory name — otherwise
+    // tier 1/2 dedupe the project entity but every application_component
+    // still mints fresh under application:01_jaffle_shop beside
+    // application:jaffle_shop, which is the same H-05 bug one level down.
+    const resolvedSlug = projectIdentity.key.split(":").slice(1).join(":") || projectDirSlug;
+    const applicationRef = `application:${resolvedSlug}`;
+    if (!asJson) {
+        console.log(`\nDetected a ${runtime} data pipeline — ${detection.signals.join(", ")}.`);
+        if (projectIdentity.source !== "directory_slug") {
+            console.log(`  Identity: matched existing project via ${projectIdentity.source.replace(/_/g, " ")} (${projectRef})`);
+        }
+        console.log(dryRun
+            ? `Dry run — nothing below is written. ${displayName} would be registered as ${projectRef} sourcing ${applicationRef}.`
+            : `Registering ${displayName} as ${projectRef} sourcing ${applicationRef}.`);
+    }
+    const scanProvenance = {
+        source: "nexarch_cli_init_project",
+        source_dir: dir,
+        scanned_at: new Date().toISOString(),
+        data_runtime: runtime,
+        ...(detectedRepo?.url ? { repository_url: detectedRepo.url, source_repository_url: detectedRepo.url } : {}),
+    };
+    const projectEntity = {
+        entityRef: projectRef,
+        entityTypeCode: "project",
+        entitySubtypeCode: "project_repository",
+        name: displayName,
+        confidence: 1,
+        attributes: scanProvenance,
+    };
+    const applicationEntity = {
+        entityRef: applicationRef,
+        entityTypeCode: "application",
+        entitySubtypeCode: "app_custom_built",
+        name: displayName,
+        description: `${runtime} data pipeline (${detection.signals.join(", ")}).`,
+        confidence: 1,
+        attributes: scanProvenance,
+    };
+    const componentEntities = detection.components.map((c) => ({
+        entityRef: `application_component:${resolvedSlug}_${c.slug}`,
+        entityTypeCode: "application_component",
+        entitySubtypeCode: c.subtypeCode,
+        name: c.name,
+        description: `${RUNTIME_LABEL[runtime]} at ${c.relativePath}`,
+        confidence: 0.9,
+        attributes: { source: "nexarch_cli_init_project", data_runtime: runtime, source_path: c.relativePath },
+    }));
+    const entities = [projectEntity, applicationEntity, ...componentEntities];
+    const relationships = [
+        { fromEntityRef: applicationRef, toEntityRef: projectRef, relationshipTypeCode: "sourced_from", confidence: 1 },
+        ...componentEntities.map((c) => ({
+            fromEntityRef: c.entityRef,
+            toEntityRef: applicationRef,
+            relationshipTypeCode: "part_of",
+            confidence: 0.9,
+        })),
+    ];
+    if (dryRun) {
+        if (asJson) {
+            process.stdout.write(`${JSON.stringify({ ok: true, dryRun: true, wrote: false, projectRef, applicationRef, dataRuntime: runtime, registrationStatus: "skeleton_only", enrichmentCompleted: false, detection, plan: { entities, relationships } }, null, 2)}\n`);
+            return;
+        }
+        console.log(`\nWould write ${entities.length} entit${entities.length === 1 ? "y" : "ies"} (${componentEntities.length} pipeline component(s)):`);
+        for (const e of entities.slice(0, 20))
+            console.log(`    ${e.entityRef}  (${e.entityTypeCode} / ${e.entitySubtypeCode})`);
+        if (entities.length > 20)
+            console.log(`    … and ${entities.length - 20} more`);
+        console.log(`\nWould write ${relationships.length} relationship(s).`);
+        console.log(`\nNothing was written. Re-run without --dry-run to register.`);
+        return;
+    }
+    const policiesRaw = await callMcpTool("nexarch_get_applied_policies", {});
+    const policyBundleHash = readResult(policiesRaw).policyBundleHash ?? null;
+    if (!policyBundleHash) {
+        throw new Error("Policy bootstrap is missing for this workspace. Complete workspace setup before registering a project.");
+    }
+    const agentContext = {
+        agentId: "nexarch-cli:init-project",
+        agentRunId: `init-project-data-${Date.now()}`,
+        repoRef: dir,
+        repoPath: dir,
+        observedAt: new Date().toISOString(),
+        source: "nexarch-cli",
+        model: "n/a",
+        provider: "n/a",
+    };
+    const policyContext = { policyBundleHash, alignmentSummary: { score: 1, violations: [], waivers: [] } };
+    let succeeded = 0;
+    let failed = 0;
+    for (const batch of chunk(entities, 400)) {
+        const raw = await callMcpTool("nexarch_upsert_entities", { entities: batch, agentContext, policyContext, companyId: creds.companyId }, { companyId: creds.companyId });
+        const result = readResult(raw);
+        succeeded += Number(result.summary?.succeeded ?? 0);
+        failed += Number(result.summary?.failed ?? 0);
+    }
+    for (const batch of chunk(relationships, 400)) {
+        await callMcpTool("nexarch_upsert_relationships", { relationships: batch, agentContext, policyContext, companyId: creds.companyId }, { companyId: creds.companyId });
+    }
+    if (projectIdentity.source === "directory_slug") {
+        try {
+            await callMcpTool("nexarch_register_alias", { alias: displayName, canonicalExternalKey: projectRef, canonicalName: displayName, entityTypeCode: "project", companyId: creds.companyId }, { companyId: creds.companyId });
+        }
+        catch {
+            // Non-fatal — see resolveProjectIdentity's tier 2.
+        }
+    }
+    if (!asJson) {
+        console.log(`  ✓ Registered ${projectRef} sourcing ${applicationRef}`);
+        console.log(`  ✓ Registered ${componentEntities.length} ${RUNTIME_LABEL[runtime]}(s) as application_component, part_of ${applicationRef}`);
+        if (failed > 0)
+            console.log(`  ! ${failed} entit${failed === 1 ? "y" : "ies"} failed to write — see JSON output (--json) for details.`);
+    }
+    else {
+        process.stdout.write(`${JSON.stringify({
+            ok: failed === 0,
+            projectRef,
+            applicationRef,
+            dataRuntime: runtime,
+            registrationStatus: "enriched",
+            enrichmentCompleted: true,
+            detection,
+            summary: { entitiesRequested: entities.length, entitiesSucceeded: succeeded, entitiesFailed: failed, relationshipsWritten: relationships.length },
+        }, null, 2)}\n`);
+    }
+}

package/dist/commands/init-project.js

@@ -7,6 +7,8 @@ import { callMcpTool } from "../lib/mcp.js";
 import { buildVersionAttributes } from "../lib/version-normalization.js";
 import { detectInfrastructureProject } from "../lib/terraform-detect.js";
 import { runInfrastructureOnboarding } from "./init-project-infra.js";
+import { detectDataProject } from "../lib/data-project-detect.js";
+import { runDataProjectOnboarding } from "./init-project-data.js";
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 function parseFlag(args, flag) {
     return args.includes(flag);
@@ -261,6 +263,55 @@ export function detectSourceRepository(dir) {
         canonicalRepoRef: providerCanonicalRepoRef(provider),
     };
 }
+/**
+ * Project identity must survive re-ingestion from a differently-named
+ * checkout (H-05, docs/plans/data-architecture-plan.md 1.2): ten repositories
+ * became twenty projects because the only identity signal was the local
+ * folder name — `project:01_jaffle_shop` beside `project:jaffle_shop` for the
+ * same remote. Three tiers, tried in order, each a stronger signal than the
+ * one it falls back to:
+ *
+ *  1. git remote URL — survives a clone under any directory name. Matches
+ *     against attributes.source_repository_url already recorded on this
+ *     company's existing `project` entities.
+ *  2. registered entity_ref — a company-scoped alias from a prior run's
+ *     resolveProjectIdentity call (registered by the caller after this
+ *     returns), for repositories tier 1 cannot see: no hosted git remote
+ *     (vendored archives, local-only git, a VCS with no stable URL).
+ *  3. directory slug — today's only mechanism. First contact with this
+ *     repository under either signal.
+ */
+export async function resolveProjectIdentity(companyId, detectedRepo, projectDirName, projectDirSlug) {
+    const fallbackKey = `project:${projectDirSlug}`;
+    if (detectedRepo?.url) {
+        try {
+            const raw = await callMcpTool("nexarch_list_entities", { entityTypeCode: "project", limit: 500, companyId }, { companyId });
+            const parsed = parseToolText(raw);
+            const match = (parsed.entities ?? []).find((e) => {
+                const attrs = e.attributes ?? {};
+                return attrs.source_repository_url === detectedRepo.url || attrs.repository_url === detectedRepo.url;
+            });
+            const matchedRef = match?.entityRef ?? match?.externalKey;
+            if (matchedRef)
+                return { key: matchedRef, source: "git_remote_url" };
+        }
+        catch {
+            // Best effort — an ontology or network hiccup here should not block
+            // the scan; fall through to the next tier.
+        }
+    }
+    try {
+        const raw = await callMcpTool("nexarch_resolve_reference", { names: [projectDirName], companyId }, { companyId });
+        const parsed = parseToolText(raw);
+        const hit = (parsed.results ?? []).find((r) => r.resolved && r.entityTypeCode === "project" && r.canonicalExternalRef);
+        if (hit?.canonicalExternalRef)
+            return { key: hit.canonicalExternalRef, source: "registered_entity_ref" };
+    }
+    catch {
+        // Best effort.
+    }
+    return { key: fallbackKey, source: "directory_slug" };
+}
 // ─── Project scanning ─────────────────────────────────────────────────────────
 // Noise patterns for env var keys that are internal config, not external service references
 const ENV_KEY_NOISE = /^(NODE_ENV|PORT|HOST|DEBUG|LOG_LEVEL|TZ|LANG|PATH|HOME|USER|SHELL|TERM)$|(_LOG_LEVEL|_MAX_|_MIN_|_DEFAULT_|_TIMEOUT|_DELAY|_JOBS|_INTERVAL|_LIMIT|_RETRIES|_CONCURREN|_WORKERS)$|(_URL|_SECRET|_TOKEN|_KEY|_PASSWORD|_CREDENTIAL|_DSN|_URI)$/;
@@ -1023,8 +1074,15 @@ export async function loadAllowedLinks(companyId) {
         allowedLinks = new Set(links.map((l) => linkKey(l.fromEntityTypeCode, l.relationshipTypeCode, l.toEntityTypeCode)));
         return allowedLinks.size;
     }
-    catch {
+    catch (error) {
         allowedLinks = new Set();
+        // Still non-fatal — a scan that records slightly wrong relationships is
+        // worth more than a scan that refuses to run because this one read
+        // failed. But silent degradation is what let a scoped-token companyId
+        // bug (M-05) go unnoticed: the relationship conformer just quietly
+        // stopped narrowing anything, in exactly the CI context it exists for.
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Warning: could not load the ingest contract — relationship conformance is disabled for this run (edges may be sent that the ontology refuses). Reason: ${message}`);
         return 0;
     }
 }
@@ -1042,7 +1100,15 @@ export async function loadAllowedLinks(companyId) {
  * invalidate a shipped CLI: the contract is read at run time, so the constraint
  * the gateway will apply is the constraint used to choose.
  */
+// project has zero legal outbound relationship types (verified live,
+// 2026-08-24 — ADR 8a models it as evidence, not architecture: nothing a
+// project scan discovers depends_on/runs_on/etc. from the project itself).
+// That is a permanent ontology fact, not a transient contract gap, so
+// there is nothing for a refusal to usefully explain (data-architecture-plan.md 1.2).
+const KNOWN_SOURCELESS_ENTITY_TYPES = new Set(["project"]);
 function conformRelationshipType(preferred, fromEntityTypeCode, toEntityTypeCode) {
+    if (KNOWN_SOURCELESS_ENTITY_TYPES.has(fromEntityTypeCode))
+        return null;
     if (allowedLinks.size === 0)
         return preferred;
     if (allowedLinks.has(linkKey(fromEntityTypeCode, preferred, toEntityTypeCode)))
@@ -1173,6 +1239,33 @@ export async function initProject(args) {
     const refreshMode = parseFlag(args, "--refresh");
     const creds = requireCredentials();
     const mcpOpts = { companyId: creds.companyId };
+    // A data-pipeline repository (dbt, Airflow, Dagster, Dataform, ksqlDB,
+    // Spark) is onboarded differently too: the npm/manifest dependency scan
+    // below finds nothing meaningful in it (H-06, data-architecture-plan.md
+    // 1.3). Checked ahead of infrastructure, not instead of it — a repo that
+    // both runs a pipeline and provisions its own Terraform gets both facets
+    // registered, because the first signal found deciding the whole
+    // repository was exactly the module-library bug this mirrors.
+    if (!parseFlag(args, "--as-application")) {
+        const dataProject = detectDataProject(dir);
+        if (dataProject.isDataProject) {
+            await runDataProjectOnboarding({ dir, nameOverride, asJson, dryRun }, dataProject);
+            const infrastructure = detectInfrastructureProject(dir);
+            if (infrastructure.isInfrastructure) {
+                if (!asJson)
+                    console.log(`\nAlso detected infrastructure in the same repository — ${infrastructure.signals.join(", ")}.`);
+                await runInfrastructureOnboarding({
+                    dir,
+                    nameOverride,
+                    asJson,
+                    nonInteractive: parseFlag(args, "--non-interactive"),
+                    skipIngest: parseFlag(args, "--no-ingest"),
+                    dryRun,
+                }, infrastructure);
+            }
+            return;
+        }
+    }
     // An infrastructure repository is onboarded differently: its content lives in
     // Terraform state, not in a manifest, so the dependency scan below would
     // describe the wrong thing entirely (ADR: infrastructure-as-code ingestion).
@@ -1213,7 +1306,18 @@ export async function initProject(args) {
     const isMonorepo = subPackages.length > 0;
     const projectDirName = nameOverride ?? basename(dir);
     const projectDirSlug = slugify(projectDirName);
-    const projectEntityKey = `project:${projectDirSlug}`;
+    // H-05 (data-architecture-plan.md 1.2): resolve identity before minting a
+    // key from the directory name, so re-ingestion from a differently-named
+    // checkout reuses the project this company already has.
+    const projectIdentity = projectConstruct
+        ? await resolveProjectIdentity(creds.companyId, detectedRepo, projectDirName, projectDirSlug)
+        : { key: `project:${projectDirSlug}`, source: "directory_slug" };
+    const projectEntityKey = projectIdentity.key;
+    if (projectConstruct && projectIdentity.source !== "directory_slug") {
+        logProgress("project.identity", `${projectIdentity.source} -> ${projectEntityKey}`);
+        if (!asJson)
+            console.log(`  Identity: matched existing project via ${projectIdentity.source.replace(/_/g, " ")} (${projectEntityKey})`);
+    }
     // Compute sub-package external keys now that projectSlug is known.
     // Unscoped names (no "/") get prefixed with the project slug to avoid ambiguous keys
     // like "application:crawler" — they become "application:whatsontap-crawler" instead,
@@ -1571,8 +1675,11 @@ export async function initProject(args) {
             continue;
         if (!rootDepNames.has(r.input) && !rootDepNames.has(r.normalised))
             continue;
+        const relType = conformRelationshipType(pickRelationshipType(r.entityTypeCode, r.entitySubtypeCode), entityTypeOverride, r.entityTypeCode);
+        if (!relType)
+            continue;
         const depSpec = rootDepVersions.get(r.input) ?? rootDepVersions.get(r.normalised);
-        addRel(conformRelationshipType(pickRelationshipType(r.entityTypeCode, r.entitySubtypeCode), entityTypeOverride, r.entityTypeCode), projectExternalKey, r.canonicalExternalRef, 0.9, {
+        addRel(relType, projectExternalKey, r.canonicalExternalRef, 0.9, {
             source: depSpec?.source ?? "manifest_scan",
             detected_at: nowIso,
             ...buildVersionAttributes(depSpec?.versionRaw ?? null, depSpec?.source ?? "manifest_scan"),
@@ -1602,7 +1709,10 @@ export async function initProject(args) {
         for (const dep of sp.depSpecs) {
             const r = resolvedByInput.get(dep.name);
             if (r?.canonicalExternalRef && r.entityTypeCode) {
-                addRel(conformRelationshipType(pickRelationshipType(r.entityTypeCode, r.entitySubtypeCode, sp.entityType), sp.entityType, r.entityTypeCode), sp.externalKey, r.canonicalExternalRef, 0.9, {
+                const relType = conformRelationshipType(pickRelationshipType(r.entityTypeCode, r.entitySubtypeCode, sp.entityType), sp.entityType, r.entityTypeCode);
+                if (!relType)
+                    continue;
+                addRel(relType, sp.externalKey, r.canonicalExternalRef, 0.9, {
                     source: dep.source,
                     detected_at: nowIso,
                     ...buildVersionAttributes(dep.versionRaw, dep.source),
@@ -1691,6 +1801,25 @@ export async function initProject(args) {
         logProgress("upsert.entities.batch.done", `${i + 1}/${entityChunks.length} succeeded=${chunkResult.summary?.succeeded ?? 0}, failed=${chunkResult.summary?.failed ?? 0}`);
     }
     logProgress("upsert.entities.done", `succeeded=${entitiesResult.summary?.succeeded ?? 0}, failed=${entitiesResult.summary?.failed ?? 0}`);
+    // Register this directory name as an alias for the resolved project key,
+    // so a future run from a renamed checkout with no hosted git remote can
+    // still find this project via resolveProjectIdentity's tier 2 (H-05).
+    // Best effort: a failure here should not fail an otherwise-successful scan.
+    if (projectConstruct && (entitiesResult.summary?.succeeded ?? 0) > 0) {
+        try {
+            await callMcpTool("nexarch_register_alias", {
+                alias: projectDirName,
+                canonicalExternalKey: projectEntityKey,
+                canonicalName: projectDirName,
+                entityTypeCode: "project",
+                companyId: creds.companyId,
+            }, { companyId: creds.companyId });
+        }
+        catch {
+            // Non-fatal — this only affects a future differently-named checkout's
+            // ability to resolve via tier 2; the scan itself already succeeded.
+        }
+    }
     // Upsert relationships (chunked)
     let relsResult = null;
     if (relationships.length > 0) {

package/dist/commands/mcp-proxy.js

@@ -9,6 +9,86 @@ import { forwardToGateway } from "../lib/mcp.js";
  * Each line from stdin is a complete JSON-RPC message.
  * Responses are written to stdout as single-line JSON.
  */
+const MAX_ERROR_DATA_JSON_LENGTH = 8000;
+const FORBIDDEN_KEY_PATTERN = /token|cookie|password|secret|authorization|bearer|stack/i;
+function containsForbiddenKey(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    if (Array.isArray(value))
+        return value.some(containsForbiddenKey);
+    return Object.entries(value).some(([key, val]) => FORBIDDEN_KEY_PATTERN.test(key) || containsForbiddenKey(val));
+}
+function sanitizeErrorData(data) {
+    if (data === undefined)
+        return undefined;
+    if (containsForbiddenKey(data))
+        return { redacted: true, reason: "error detail withheld" };
+    const serialized = JSON.stringify(data);
+    if (serialized !== undefined && serialized.length > MAX_ERROR_DATA_JSON_LENGTH) {
+        return { truncated: true, reason: "error detail exceeded size limit" };
+    }
+    return data;
+}
+function isSafeJsonRpcErrorBody(parsed) {
+    if (!parsed || typeof parsed !== "object")
+        return false;
+    const err = parsed.error;
+    if (!err || typeof err !== "object")
+        return false;
+    const errObj = err;
+    return typeof errObj.code === "number" && typeof errObj.message === "string";
+}
+/**
+ * Builds the JSON-RPC error response written to stdout for a non-200
+ * gateway response. The gateway already returns detailed JSON-RPC error
+ * bodies (field paths, error codes, domain-specific detail) on every
+ * non-200 status — this forwards that body verbatim (sanitized and
+ * size-bounded) instead of collapsing it into "Gateway error (HTTP N)".
+ * A generic fallback is used only when the body is absent, unparseable,
+ * or doesn't look like a safe JSON-RPC error shape.
+ */
+export function buildProxyErrorResponse(requestId, status, rawBody) {
+    let parsed = null;
+    if (rawBody && rawBody.trim()) {
+        try {
+            parsed = JSON.parse(rawBody);
+        }
+        catch {
+            parsed = null;
+        }
+    }
+    if (isSafeJsonRpcErrorBody(parsed)) {
+        const data = sanitizeErrorData(parsed.error.data);
+        if (status === 401) {
+            return JSON.stringify({
+                jsonrpc: "2.0",
+                id: requestId ?? null,
+                error: {
+                    code: -32001,
+                    message: `Unauthorized — run \`nexarch login\` to re-authenticate. (${parsed.error.message})`,
+                    ...(data !== undefined ? { data } : {}),
+                },
+            });
+        }
+        return JSON.stringify({
+            jsonrpc: "2.0",
+            id: requestId ?? null,
+            error: { code: parsed.error.code, message: parsed.error.message, ...(data !== undefined ? { data } : {}) },
+        });
+    }
+    if (status === 401) {
+        return JSON.stringify({
+            jsonrpc: "2.0",
+            id: requestId ?? null,
+            error: { code: -32001, message: "Unauthorized — run `nexarch login` to re-authenticate." },
+        });
+    }
+    return JSON.stringify({
+        jsonrpc: "2.0",
+        id: requestId ?? null,
+        error: { code: -32000, message: `Gateway error (HTTP ${status})` },
+    });
+}
 export async function mcpProxy(_args) {
     const creds = requireCredentials();
     const rl = readline.createInterface({
@@ -45,21 +125,8 @@ export async function mcpProxy(_args) {
                 // Write response as a single line.
                 process.stdout.write(body.replace(/\n/g, " ") + "\n");
             }
-            else if (status === 401) {
-                const errorResponse = JSON.stringify({
-                    jsonrpc: "2.0",
-                    id: message.id ?? null,
-                    error: { code: -32001, message: "Unauthorized — run `nexarch login` to re-authenticate." },
-                });
-                process.stdout.write(errorResponse + "\n");
-            }
             else {
-                const errorResponse = JSON.stringify({
-                    jsonrpc: "2.0",
-                    id: message.id ?? null,
-                    error: { code: -32000, message: `Gateway error (HTTP ${status})` },
-                });
-                process.stdout.write(errorResponse + "\n");
+                process.stdout.write(buildProxyErrorResponse(message.id, status, body) + "\n");
             }
         }
         catch (err) {

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { login } from "./commands/login.js";
+import { enroll } from "./commands/enroll.js";
 import { logout } from "./commands/logout.js";
 import { status } from "./commands/status.js";
 import { setup } from "./commands/setup.js";
@@ -29,9 +30,17 @@ import { registerRuntime } from "./commands/register-runtime.js";
 import { ingestInfra } from "./commands/ingest-infra.js";
 import { verifyTrust } from "./commands/verify-trust.js";
 import { cliBuild, formatBuild } from "./lib/version.js";
+import { checkForUpdate, printUpdateNoticeIfReady } from "./lib/update-check.js";
 const [, , command, ...args] = process.argv;
+// Kicked off before anything else so it rides alongside whatever network
+// calls the command itself makes, rather than adding its own delay — see
+// update-check.ts. Skipped for mcp-proxy: that command's stdout/stderr is a
+// live JSON-RPC stream to an MCP client, and even a stray stderr line has no
+// safe place to land there.
+const updateCheck = command === "mcp-proxy" ? null : checkForUpdate();
 const commands = {
     login,
+    enroll,
     logout,
     status,
     setup,
@@ -96,6 +105,21 @@ Usage:
   nexarch login         Authenticate in browser and store company-scoped credentials
                         Option: --company <id>
   nexarch --version     Print the version and the path this copy runs from
+  nexarch enroll        Bootstrap a headless (browserless) agent with a one-time
+                        enrollment code — no login required. Writes the resulting
+                        credential to ~/.nexarch/agent-credential.json (mode 600)
+                        rather than printing it. For a client with a known config
+                        format (e.g. hermes-agent), also writes the connection
+                        directly into that client's own env/config files; for
+                        anything else, prints instructions instead.
+                        Options: --code <code>          (required, starts with nxe_)
+                                 --client <code>         (required, e.g. hermes-agent)
+                                 --client-version <v>
+                                 --host <baseUrl>        (default: https://www.nexarch.ai)
+                                 --out <path>            write credential here instead
+                                 --skip-client-config    don't touch the client's own files
+                                 --print-token           also print the token to stdout
+                                 --json
   nexarch logout        Remove stored credentials
   nexarch status        Check connection and show architecture summary
   nexarch verify-trust  Verify this repo's Nexarch trust attestation. Reads the token
@@ -295,14 +319,20 @@ Usage:
                       audit rollup (latest run status, pass/partial/fail counts).
                       Options: --json
     `);
+        if (updateCheck)
+            await printUpdateNoticeIfReady(updateCheck);
         process.exit(command ? 1 : 0);
     }
     try {
         await handler(args);
+        if (updateCheck)
+            await printUpdateNoticeIfReady(updateCheck);
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         console.error(`error: ${message}`);
+        if (updateCheck)
+            await printUpdateNoticeIfReady(updateCheck);
         process.exit(1);
     }
 }

package/dist/lib/client-config-writers.js

@@ -0,0 +1,61 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { parseDocument } from "yaml";
+export function expandHomePath(path) {
+    if (path.startsWith("~/") || path === "~") {
+        return join(homedir(), path.slice(1));
+    }
+    return path;
+}
+/**
+ * Replaces the line for `key=` if present, otherwise appends it — never
+ * touches any other line, so unrelated vars in an existing .env survive.
+ */
+function upsertEnvVar(filePath, key, value) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    const existing = existsSync(filePath) ? readFileSync(filePath, "utf8") : "";
+    const lines = existing.length > 0 ? existing.split(/\r?\n/) : [];
+    const lineIndex = lines.findIndex((line) => line.startsWith(`${key}=`));
+    const newLine = `${key}=${value}`;
+    if (lineIndex >= 0) {
+        lines[lineIndex] = newLine;
+    }
+    else {
+        if (lines.length > 0 && lines[lines.length - 1].trim() !== "")
+            lines.push("");
+        lines.push(newLine);
+    }
+    const out = lines.join("\n").replace(/\n*$/, "\n");
+    writeFileSync(filePath, out, { mode: 0o600 });
+}
+/**
+ * Merges one `mcp_servers.<serverKey>` entry into a YAML document, preserving
+ * every other key, comment, and formatting choice already in the file — this
+ * is someone else's live config, not a file this CLI owns. `${VAR}` in the
+ * Authorization header is left as a literal template string; the client
+ * itself (Hermes) resolves it from its own env at connect time, so the raw
+ * token is never written into this file.
+ */
+function yamlUrlBearerStyle(configPath, serverKey, envVar, mcpUrl) {
+    mkdirSync(dirname(configPath), { recursive: true });
+    const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+    const doc = parseDocument(existing);
+    doc.setIn(["mcp_servers", serverKey, "url"], mcpUrl);
+    doc.setIn(["mcp_servers", serverKey, "headers", "Authorization"], `Bearer \${${envVar}}`);
+    writeFileSync(configPath, doc.toString(), { mode: 0o600 });
+}
+const STRATEGIES = {
+    yaml_url_bearer_style: (t) => yamlUrlBearerStyle(t.mcpConfigPath, t.serverKey, t.envVar, t.mcpUrl),
+};
+export function supportsAutoWrite(mergeStrategy) {
+    return Boolean(mergeStrategy && STRATEGIES[mergeStrategy]);
+}
+/** Throws if mergeStrategy isn't recognized — check supportsAutoWrite first. */
+export function writeClientConfig(mergeStrategy, targets) {
+    const strategy = STRATEGIES[mergeStrategy];
+    if (!strategy)
+        throw new Error(`Unknown mcp_config_merge_strategy: ${mergeStrategy}`);
+    upsertEnvVar(targets.envFilePath, targets.envVar, targets.token);
+    strategy(targets);
+}

package/dist/lib/data-project-detect.js

@@ -0,0 +1,204 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+const IGNORED_DIRS = new Set(["node_modules", ".git", ".venv", "venv", "__pycache__", "dist", "build", ".next", "target"]);
+const SCAN_DEPTH = 4;
+function slugify(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function safeReadFile(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Manifest text worth grep-checking for a runtime dependency: requirements.txt, pyproject.toml, setup.py, build.sbt, pom.xml. */
+function readPythonManifests(dir) {
+    return ["requirements.txt", "requirements-dev.txt", "pyproject.toml", "setup.py", "Pipfile"]
+        .map((f) => safeReadFile(join(dir, f)))
+        .join("\n");
+}
+/** Finds a directory by name, searched breadth-first up to SCAN_DEPTH so a nested layout (e.g. `orchestration/dags/`) is still found. */
+function findDirectory(root, name, depth = 0) {
+    if (depth > SCAN_DEPTH)
+        return null;
+    const entries = safeReaddir(root);
+    if (entries.includes(name) && isDir(join(root, name)))
+        return join(root, name);
+    for (const entry of entries) {
+        if (IGNORED_DIRS.has(entry))
+            continue;
+        const full = join(root, entry);
+        if (isDir(full)) {
+            const found = findDirectory(full, name, depth + 1);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+/** Finds a file by exact name, searched breadth-first up to SCAN_DEPTH. */
+function findFile(root, name, depth = 0) {
+    if (depth > SCAN_DEPTH)
+        return null;
+    const entries = safeReaddir(root);
+    if (entries.includes(name) && !isDir(join(root, name)))
+        return join(root, name);
+    for (const entry of entries) {
+        if (IGNORED_DIRS.has(entry))
+            continue;
+        const full = join(root, entry);
+        if (isDir(full)) {
+            const found = findFile(full, name, depth + 1);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+function collectFilesByExtension(dir, extensions, repoRoot, depth = 0, out = [], subtypeCode = "app_comp_data_pipeline") {
+    if (depth > SCAN_DEPTH)
+        return out;
+    for (const entry of safeReaddir(dir)) {
+        if (IGNORED_DIRS.has(entry))
+            continue;
+        const full = join(dir, entry);
+        if (isDir(full)) {
+            collectFilesByExtension(full, extensions, repoRoot, depth + 1, out, subtypeCode);
+            continue;
+        }
+        if (!extensions.some((ext) => entry.endsWith(ext)))
+            continue;
+        if (entry === "schema.yml" || entry === "sources.yml" || entry === "__init__.py")
+            continue;
+        const relativePath = full.slice(repoRoot.length + 1).split("\\").join("/");
+        const baseName = entry.replace(/\.[^.]+$/, "");
+        out.push({ slug: slugify(baseName), name: baseName, relativePath, subtypeCode });
+    }
+    return out;
+}
+function detectDbt(dir) {
+    const manifest = findFile(dir, "dbt_project.yml");
+    if (!manifest)
+        return null;
+    const root = join(manifest, "..");
+    const modelsDir = findDirectory(root, "models") ?? join(root, "models");
+    const signals = [`dbt_project.yml at ${manifest.slice(dir.length + 1)}`];
+    const components = existsSync(modelsDir) ? collectFilesByExtension(modelsDir, [".sql"], dir) : [];
+    if (existsSync(modelsDir))
+        signals.push(`${components.length} model(s) under ${modelsDir.slice(dir.length + 1)}`);
+    return { isDataProject: true, runtime: "dbt", signals, components };
+}
+function detectAirflow(dir) {
+    const dagsDir = findDirectory(dir, "dags");
+    const hasAirflowCfg = Boolean(findFile(dir, "airflow.cfg"));
+    const hasAirflowDep = /apache-airflow/i.test(readPythonManifests(dir));
+    if (!dagsDir && !hasAirflowCfg)
+        return null;
+    if (dagsDir && !hasAirflowDep && !hasAirflowCfg)
+        return null; // a bare "dags" dir with no corroboration is too weak to claim
+    const signals = [];
+    if (dagsDir)
+        signals.push(`dags/ at ${dagsDir.slice(dir.length + 1)}`);
+    if (hasAirflowCfg)
+        signals.push("airflow.cfg present");
+    if (hasAirflowDep)
+        signals.push("apache-airflow in manifest");
+    const components = dagsDir ? collectFilesByExtension(dagsDir, [".py"], dir, 0, [], "orchestrator_component") : [];
+    if (dagsDir)
+        signals.push(`${components.length} DAG file(s)`);
+    return { isDataProject: true, runtime: "airflow", signals, components };
+}
+function detectDagster(dir) {
+    const workspaceYaml = findFile(dir, "workspace.yaml");
+    const hasDagsterDep = /\bdagster\b/i.test(readPythonManifests(dir));
+    const definitionsFile = findFile(dir, "definitions.py") ?? findFile(dir, "repository.py");
+    if (!workspaceYaml && !(hasDagsterDep && definitionsFile))
+        return null;
+    const signals = [];
+    if (workspaceYaml)
+        signals.push(`workspace.yaml at ${workspaceYaml.slice(dir.length + 1)}`);
+    if (hasDagsterDep)
+        signals.push("dagster in manifest");
+    if (definitionsFile)
+        signals.push(`definitions at ${definitionsFile.slice(dir.length + 1)}`);
+    const assetsDir = findDirectory(dir, "assets");
+    const components = assetsDir ? collectFilesByExtension(assetsDir, [".py"], dir) : [];
+    if (assetsDir)
+        signals.push(`${components.length} asset file(s) under ${assetsDir.slice(dir.length + 1)}`);
+    return { isDataProject: true, runtime: "dagster", signals, components };
+}
+function detectDataform(dir) {
+    const configFile = findFile(dir, "workflow_settings.yaml") ?? findFile(dir, "dataform.json");
+    if (!configFile)
+        return null;
+    const definitionsDir = findDirectory(dir, "definitions");
+    const signals = [`${configFile.slice(dir.length + 1)} present`];
+    const components = definitionsDir ? collectFilesByExtension(definitionsDir, [".sqlx", ".sql", ".js"], dir) : [];
+    if (definitionsDir)
+        signals.push(`${components.length} definition(s) under ${definitionsDir.slice(dir.length + 1)}`);
+    return { isDataProject: true, runtime: "dataform", signals, components };
+}
+function detectKsqlDb(dir) {
+    const propsFile = findFile(dir, "ksql-server.properties") ?? findFile(dir, "ksqldb-server.properties");
+    const ksqlFiles = collectFilesByExtension(dir, [".ksql"], dir);
+    if (!propsFile && ksqlFiles.length === 0)
+        return null;
+    const signals = [];
+    if (propsFile)
+        signals.push(`${propsFile.slice(dir.length + 1)} present`);
+    if (ksqlFiles.length > 0)
+        signals.push(`${ksqlFiles.length} .ksql file(s)`);
+    return { isDataProject: true, runtime: "ksqldb", signals, components: ksqlFiles };
+}
+function detectSpark(dir) {
+    const buildSbt = safeReadFile(join(dir, "build.sbt"));
+    const pom = safeReadFile(join(dir, "pom.xml"));
+    const pyManifest = readPythonManifests(dir);
+    const hasSparkDep = /org\.apache\.spark/i.test(buildSbt) || /org\.apache\.spark/i.test(pom) || /\bpyspark\b/i.test(pyManifest);
+    if (!hasSparkDep)
+        return null;
+    // Spark is a general-purpose engine used inside plenty of non-pipeline
+    // applications; requiring a conventional jobs directory too keeps a
+    // service that merely calls into Spark from being reclassified.
+    const jobsDir = findDirectory(dir, "jobs") ?? findDirectory(dir, "spark_jobs");
+    if (!jobsDir)
+        return null;
+    const signals = ["Spark dependency declared", `jobs directory at ${jobsDir.slice(dir.length + 1)}`];
+    const components = collectFilesByExtension(jobsDir, [".py", ".scala"], dir);
+    signals.push(`${components.length} job file(s)`);
+    return { isDataProject: true, runtime: "spark", signals, components };
+}
+const DETECTORS = [detectDbt, detectAirflow, detectDagster, detectDataform, detectKsqlDb, detectSpark];
+/**
+ * Detects the first matching data runtime. Order matters only for the rare
+ * repository combining two markers (e.g. a Dagster project orchestrating dbt
+ * models) — dbt is checked first because `dbt_project.yml` is the least
+ * ambiguous marker of the six, and the dbt models are what actually holds
+ * the domain content worth graphing.
+ */
+export function detectDataProject(dir) {
+    for (const detector of DETECTORS) {
+        const result = detector(dir);
+        if (result)
+            return result;
+    }
+    return { isDataProject: false, runtime: null, signals: [], components: [] };
+}

package/dist/lib/mcp.js

@@ -33,7 +33,13 @@ async function requestOnce(method, params, options) {
             headers: {
                 "Content-Type": "application/json",
                 Authorization: `Bearer ${creds.token}`,
-                "x-company-id": companyId,
+                // Scoped tokens carry their company_id server-side (see
+                // auth.ts's resolveCompanyId) and never populate creds.companyId
+                // locally, so an empty header here is the expected normal case —
+                // sending it as a literal empty string, rather than omitting it,
+                // used to matter for legacy static tokens where the header is the
+                // only source of truth. Omit rather than send "".
+                ...(companyId ? { "x-company-id": companyId } : {}),
                 "Content-Length": Buffer.byteLength(body),
             },
             timeout: REQUEST_TIMEOUT_MS,
@@ -93,7 +99,16 @@ async function callMcpRpc(method, params = {}, options = {}) {
     throw lastError instanceof Error ? lastError : new Error(String(lastError ?? "MCP call failed"));
 }
 export async function callMcpTool(toolName, toolArgs = {}, options = {}) {
-    return callMcpRpc("tools/call", { name: toolName, arguments: toolArgs }, options);
+    // Every gateway tool schema declares companyId as z.string().uuid().optional() —
+    // "optional" means absent, not empty. Call sites pass creds.companyId
+    // unconditionally, which is "" for a scoped token (see credentials.ts);
+    // sent as a literal "", that fails .uuid() and the tool call is refused
+    // outright instead of falling back to the header/token-derived company.
+    // Single choke point: every call site funnels through here.
+    const toolArguments = { ...toolArgs };
+    if (toolArguments.companyId === "")
+        delete toolArguments.companyId;
+    return callMcpRpc("tools/call", { name: toolName, arguments: toolArguments }, options);
 }
 export async function mcpInitialize(options = {}) {
     return callMcpRpc("initialize", {

package/dist/lib/trust.js

@@ -1,6 +1,9 @@
 import https from "https";
 import { requireCredentials } from "./credentials.js";
 const MCP_GATEWAY_URL = "https://mcp.nexarch.ai";
+/** The scope every attestation is minted under — see ADR-0112. Exported so callers can tell a
+ * stored attestation's scope apart from what would be minted today, without duplicating the literal. */
+export const TRUST_ATTESTATION_SCOPE = "agent_config_write";
 /**
  * `contentHash` (sha256 hex of the exact managed-section text being written)
  * binds the signature to the instructions themselves, not just to the claim
@@ -11,7 +14,7 @@ export async function requestTrustAttestation(agentId, contentHash) {
     const creds = requireCredentials();
     const body = JSON.stringify({
         agentId,
-        scope: "agent_config_write",
+        scope: TRUST_ATTESTATION_SCOPE,
         ...(contentHash ? { contentHash } : {}),
     });
     return new Promise((resolve) => {

package/dist/lib/update-check.js

@@ -0,0 +1,109 @@
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { cliVersion } from "./version.js";
+/**
+ * Best-effort "a newer version exists" advisory (feature request #1).
+ *
+ * Checked once per day per machine, not on every invocation — a network call
+ * on every single command would make the CLI feel like it always has a
+ * network dependency, when almost nothing else about a status check does.
+ * The result is cached in the same ~/.nexarch directory as credentials.json,
+ * so most invocations skip the network entirely and this costs nothing.
+ *
+ * Kicked off at the very start of the process and only awaited (with a short
+ * cap) right before the CLI would otherwise exit, so it rides alongside
+ * whatever network calls the command itself is already making rather than
+ * adding its own visible delay.
+ */
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 1500;
+/** How long we're willing to wait for an in-flight check before giving up on printing it this run. */
+const PRINT_GRACE_MS = 200;
+function cacheDir() {
+    return join(homedir(), ".nexarch");
+}
+function cachePath() {
+    return join(cacheDir(), "update-check.json");
+}
+function readCache() {
+    try {
+        if (!existsSync(cachePath()))
+            return null;
+        const parsed = JSON.parse(readFileSync(cachePath(), "utf8"));
+        if (typeof parsed.lastCheckedAt !== "string" || typeof parsed.latestVersion !== "string")
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(cache) {
+    try {
+        mkdirSync(cacheDir(), { recursive: true });
+        writeFileSync(cachePath(), JSON.stringify(cache), "utf8");
+    }
+    catch {
+        // Best effort — a cache write failure should never surface to the user.
+    }
+}
+async function fetchLatestVersion() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch("https://registry.npmjs.org/nexarch/latest", { signal: controller.signal });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.version === "string" ? body.version : null;
+    }
+    catch {
+        // Offline, registry down, DNS failure, timeout — all the same outcome: say nothing.
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Plain numeric semver compare — good enough for release versions, no pre-release handling needed. */
+function isNewer(latest, current) {
+    const a = latest.split(".").map((n) => Number.parseInt(n, 10) || 0);
+    const b = current.split(".").map((n) => Number.parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x !== y)
+            return x > y;
+    }
+    return false;
+}
+/**
+ * Starts the check immediately; resolves to update info only when the
+ * installed copy is actually behind. Never rejects.
+ */
+export async function checkForUpdate() {
+    const current = cliVersion();
+    const cache = readCache();
+    const cacheIsFresh = cache && Date.now() - new Date(cache.lastCheckedAt).getTime() < CHECK_INTERVAL_MS;
+    const latest = cacheIsFresh ? cache.latestVersion : await fetchLatestVersion();
+    if (!cacheIsFresh && latest) {
+        writeCache({ lastCheckedAt: new Date().toISOString(), latestVersion: latest });
+    }
+    if (!latest || !isNewer(latest, current))
+        return null;
+    return { current, latest };
+}
+/**
+ * Awaits an in-flight check with a short grace period and prints the
+ * advisory to stderr if it's ready and outdated — stderr so it never
+ * contaminates a command's --json stdout for an agent caller parsing it.
+ */
+export async function printUpdateNoticeIfReady(pending) {
+    const timeout = new Promise((resolve) => setTimeout(() => resolve(null), PRINT_GRACE_MS));
+    const info = await Promise.race([pending, timeout]);
+    if (!info)
+        return;
+    process.stderr.write(`\nA newer version of nexarch is available: ${info.current} -> ${info.latest}\n` +
+        `Run with npx nexarch@latest to use it — npx always fetches latest, nothing to install.\n`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.12.23",
+  "version": "0.12.26",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",
@@ -25,11 +25,15 @@
     "build": "tsc",
     "prepublishOnly": "tsc",
     "dev": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "tsx scripts/test-mcp-proxy-response.ts"
   },
   "devDependencies": {
     "@types/node": "^22",
     "tsx": "^4",
     "typescript": "^5"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
   }
 }