nexarch 0.9.5 → 0.9.6

package/dist/commands/add-relationship.js

@@ -1,4 +1,5 @@
 import process from "process";
+import { existsSync, readFileSync } from "node:fs";
 import { requireCredentials } from "../lib/credentials.js";
 import { callMcpTool } from "../lib/mcp.js";
 function parseFlag(args, flag) {
@@ -17,11 +18,65 @@ function parseToolText(result) {
     const text = result.content?.[0]?.text ?? "{}";
     return JSON.parse(text);
 }
+function parseRelationships(args) {
+    const relationshipsFile = parseOptionValue(args, "--relationships-file");
+    const relationshipsJson = parseOptionValue(args, "--relationships-json");
+    if (relationshipsFile && relationshipsJson) {
+        throw new Error("Use only one of --relationships-file or --relationships-json");
+    }
+    if (relationshipsFile || relationshipsJson) {
+        let raw = relationshipsJson;
+        if (relationshipsFile) {
+            if (!existsSync(relationshipsFile))
+                throw new Error(`--relationships-file not found: ${relationshipsFile}`);
+            raw = readFileSync(relationshipsFile, "utf8");
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw ?? "[]");
+        }
+        catch {
+            throw new Error(relationshipsFile ? "--relationships-file must contain valid JSON array" : "--relationships-json must be valid JSON array");
+        }
+        if (!Array.isArray(parsed) || parsed.length === 0) {
+            throw new Error("Relationships input must be a non-empty JSON array");
+        }
+        return parsed.map((item, index) => {
+            const v = (item ?? {});
+            const from = String(v.fromEntityExternalKey ?? v.fromEntityRef ?? v.from ?? "").trim();
+            const to = String(v.toEntityExternalKey ?? v.toEntityRef ?? v.to ?? "").trim();
+            const type = String(v.relationshipTypeCode ?? v.type ?? "").trim();
+            const confidence = Number(v.confidence ?? 1);
+            if (!from || !to || !type) {
+                throw new Error(`Relationship #${index + 1} is missing required fields (from/to/type)`);
+            }
+            return {
+                fromEntityExternalKey: from,
+                toEntityExternalKey: to,
+                relationshipTypeCode: type,
+                confidence: Number.isFinite(confidence) ? confidence : 1,
+            };
+        });
+    }
+    const fromKey = parseOptionValue(args, "--from");
+    const toKey = parseOptionValue(args, "--to");
+    const relType = parseOptionValue(args, "--type");
+    if (!fromKey)
+        throw new Error("--from <externalKey> is required");
+    if (!toKey)
+        throw new Error("--to <externalKey> is required");
+    if (!relType)
+        throw new Error("--type <relationshipTypeCode> is required");
+    return [{
+            fromEntityExternalKey: fromKey,
+            toEntityExternalKey: toKey,
+            relationshipTypeCode: relType,
+            confidence: 1,
+        }];
+}
 async function tryCreateStubEntity(externalKey, mcpOpts, agentContext, policyContext) {
-    // Only auto-create global reference entities — company entities must be created explicitly
     if (!externalKey.startsWith("global:"))
         return false;
-    // Derive a normalised alias from the external key (e.g. "global:platform:vercel" → "vercel")
     const parts = externalKey.split(":");
     const alias = parts[parts.length - 1];
     const resolveRaw = await callMcpTool("nexarch_resolve_reference", { names: [alias], companyId: mcpOpts.companyId }, mcpOpts);
@@ -42,21 +97,7 @@ async function tryCreateStubEntity(externalKey, mcpOpts, agentContext, policyCon
 }
 export async function addRelationship(args) {
     const asJson = parseFlag(args, "--json");
-    const fromKey = parseOptionValue(args, "--from");
-    const toKey = parseOptionValue(args, "--to");
-    const relType = parseOptionValue(args, "--type");
-    if (!fromKey) {
-        console.error("error: --from <externalKey> is required");
-        process.exit(1);
-    }
-    if (!toKey) {
-        console.error("error: --to <externalKey> is required");
-        process.exit(1);
-    }
-    if (!relType) {
-        console.error("error: --type <relationshipTypeCode> is required");
-        process.exit(1);
-    }
+    const relationships = parseRelationships(args);
     const creds = requireCredentials();
     const mcpOpts = { companyId: creds.companyId };
     const policiesRaw = await callMcpTool("nexarch_get_applied_policies", {}, mcpOpts);
@@ -66,7 +107,7 @@ export async function addRelationship(args) {
     const agentContext = {
         agentId: "nexarch-cli:add-relationship",
         agentRunId: `add-relationship-${Date.now()}`,
-        repoRef: fromKey,
+        repoRef: relationships[0]?.fromEntityExternalKey ?? "batch",
         observedAt: nowIso,
         source: "nexarch-cli",
         model: "n/a",
@@ -75,27 +116,18 @@ export async function addRelationship(args) {
     const policyContext = policyBundleHash
         ? { policyBundleHash, alignmentSummary: { score: 1, violations: [], waivers: [] } }
         : undefined;
-    const relationship = {
-        relationshipTypeCode: relType,
-        fromEntityExternalKey: fromKey,
-        toEntityExternalKey: toKey,
-        confidence: 1,
-    };
-    let raw = await callMcpTool("nexarch_upsert_relationships", { relationships: [relationship], agentContext, policyContext }, mcpOpts);
+    let raw = await callMcpTool("nexarch_upsert_relationships", { relationships, agentContext, policyContext }, mcpOpts);
     let result = parseToolText(raw);
-    // Auto-create global reference stubs if endpoints are missing, then retry once
     const missingEndpoint = result.errors?.some((e) => e.error === "RELATIONSHIP_ENDPOINT_NOT_FOUND");
     if (missingEndpoint) {
-        const failedFromKeys = result.errors
-            ?.filter((e) => e.error === "RELATIONSHIP_ENDPOINT_NOT_FOUND" && e.fromEntityExternalKey)
-            .map((e) => e.fromEntityExternalKey);
-        const failedToKeys = result.errors
-            ?.filter((e) => e.error === "RELATIONSHIP_ENDPOINT_NOT_FOUND" && e.toEntityExternalKey)
-            .map((e) => e.toEntityExternalKey);
-        const keysToCreate = [...new Set([...(failedFromKeys ?? []), ...(failedToKeys ?? [])])];
-        // If no specific endpoint keys returned, fall back to trying both
-        if (keysToCreate.length === 0) {
-            keysToCreate.push(fromKey, toKey);
+        const keysToCreate = new Set();
+        for (const err of result.errors ?? []) {
+            if (err.error !== "RELATIONSHIP_ENDPOINT_NOT_FOUND")
+                continue;
+            if (err.fromEntityExternalKey)
+                keysToCreate.add(err.fromEntityExternalKey);
+            if (err.toEntityExternalKey)
+                keysToCreate.add(err.toEntityExternalKey);
         }
         let createdAny = false;
         for (const key of keysToCreate) {
@@ -104,7 +136,7 @@ export async function addRelationship(args) {
                 createdAny = true;
         }
         if (createdAny) {
-            raw = await callMcpTool("nexarch_upsert_relationships", { relationships: [relationship], agentContext, policyContext }, mcpOpts);
+            raw = await callMcpTool("nexarch_upsert_relationships", { relationships, agentContext, policyContext }, mcpOpts);
             result = parseToolText(raw);
         }
     }
@@ -117,12 +149,12 @@ export async function addRelationship(args) {
     const succeeded = result.summary?.succeeded ?? 0;
     const failed = result.summary?.failed ?? 0;
     if (failed > 0) {
-        console.error(`Failed to add relationship: ${fromKey} -[${relType}]-> ${toKey}`);
+        console.error(`Failed to add relationships (${failed}/${relationships.length}).`);
         const missingFrom = new Set();
         const missingTo = new Set();
         for (const err of result.errors ?? []) {
-            const fromEndpoint = err.fromEntityExternalKey ?? fromKey;
-            const toEndpoint = err.toEntityExternalKey ?? toKey;
+            const fromEndpoint = err.fromEntityExternalKey ?? "(unknown-from)";
+            const toEndpoint = err.toEntityExternalKey ?? "(unknown-to)";
             const message = err.message ?? "(no details returned)";
             if (err.error === "RELATIONSHIP_ENDPOINT_NOT_FOUND") {
                 if (err.fromEntityExternalKey)
@@ -146,5 +178,11 @@ export async function addRelationship(args) {
         process.exitCode = 1;
         return;
     }
-    console.log(`Added ${succeeded} relationship: ${fromKey} -[${relType}]-> ${toKey}`);
+    if (relationships.length === 1) {
+        const r = relationships[0];
+        console.log(`Added ${succeeded} relationship: ${r.fromEntityExternalKey} -[${r.relationshipTypeCode}]-> ${r.toEntityExternalKey}`);
+    }
+    else {
+        console.log(`Added ${succeeded}/${relationships.length} relationships.`);
+    }
 }

package/dist/commands/init-project.js

@@ -453,7 +453,29 @@ function classifySubPackage(pkgPath, relativePath) {
             return { entityType: "technology_component", subtype: "tech_library" };
         return { entityType: "technology_component", subtype: "tech_library" };
     }
-    // apps/* or src/* → deployable application; check scripts
+    // apps/* → deployable application component under the root application.
+    if (topDir === "apps") {
+        const name = relativePath.toLowerCase();
+        if (name.includes("worker"))
+            return { entityType: "application_component", subtype: "app_comp_worker" };
+        if (name.includes("job"))
+            return { entityType: "application_component", subtype: "app_comp_job" };
+        if (name.includes("etl"))
+            return { entityType: "application_component", subtype: "app_comp_etl" };
+        if (name.includes("adapter"))
+            return { entityType: "application_component", subtype: "app_comp_adapter" };
+        if (name.includes("batch"))
+            return { entityType: "application_component", subtype: "app_comp_batch" };
+        if (name.includes("pipeline"))
+            return { entityType: "application_component", subtype: "app_comp_data_pipeline" };
+        if (name.includes("ui") || name.includes("web") || name.includes("front") || name.includes("site") || name.includes("portal") || name.includes("admin")) {
+            return { entityType: "application_component", subtype: "app_comp_ui" };
+        }
+        if (name.includes("api"))
+            return { entityType: "application_component", subtype: "app_comp_api" };
+        return { entityType: "application_component", subtype: "app_comp_api" };
+    }
+    // src/* → deployable application; check scripts
     try {
         const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
         const scripts = Object.keys(pkg.scripts ?? {});
@@ -758,6 +780,9 @@ function scanEcosystems(dir) {
     }
     return { names, ecosystems };
 }
+function isApplicationLikeEntityType(entityType) {
+    return entityType === "application" || entityType === "application_component";
+}
 function scanProject(dir) {
     const names = new Set();
     let projectName = basename(dir);
@@ -1299,10 +1324,15 @@ export async function initProject(args) {
     // - Sub-packages that are apps → part_of the top-level project
     const relationships = [];
     const seenRelPairs = new Set();
+    let relationshipAddAttempts = 0;
+    let relationshipSkippedAsDuplicate = 0;
     function addRel(type, from, to, confidence = 0.9, attributes) {
+        relationshipAddAttempts += 1;
         const key = `${type}::${from}::${to}`;
-        if (seenRelPairs.has(key))
+        if (seenRelPairs.has(key)) {
+            relationshipSkippedAsDuplicate += 1;
             return;
+        }
         seenRelPairs.add(key);
         relationships.push({ relationshipTypeCode: type, fromEntityExternalKey: from, toEntityExternalKey: to, confidence, attributes });
     }
@@ -1325,7 +1355,7 @@ export async function initProject(args) {
             continue;
         seenSubKeys.add(`rel:${sp.externalKey}`);
         // Apps are part_of the top-level project
-        if (sp.entityType === "application") {
+        if (sp.entityType === "application_component") {
             addRel("part_of", sp.externalKey, projectExternalKey);
         }
         // Wire each sub-package's resolved deps to itself
@@ -1355,7 +1385,7 @@ export async function initProject(args) {
     addRel("accountable_for", orgExternalKey, projectExternalKey, 1);
     // Also accountable_for any sub-package applications
     for (const sp of subPackages) {
-        if (sp.externalKey && sp.entityType === "application") {
+        if (sp.externalKey && isApplicationLikeEntityType(sp.entityType)) {
             addRel("accountable_for", orgExternalKey, sp.externalKey, 1);
         }
     }
@@ -1428,6 +1458,7 @@ export async function initProject(args) {
     // Build structured enrichment task (included in JSON output and printed in human mode)
     const readmeHints = ["README.md", "README.mdx", "docs/README.md", "docs/index.md"]
         .filter((f) => existsSync(join(dir, f)));
+    const preWiredRelationshipKeys = new Set(relationships.map((rel) => `${rel.relationshipTypeCode}::${rel.fromEntityExternalKey}::${rel.toEntityExternalKey}`));
     function buildEnrichmentInstructions() {
         const ecosystemLabel = detectedEcosystems.length > 0
             ? detectedEcosystems.join(", ")
@@ -1453,10 +1484,14 @@ ${subPackages.map((sp) => `    • ${sp.name}  (${sp.relativePath})`).join("\n")
   then choose the correct entity type and subtype before running update-entity:
 
   CLASSIFICATION GUIDE — pick the best fit:
-    Deployable web app (has a dev/start/build script, runs in a browser or as a server)
-      → --entity-type application --subtype app_web
-    Deployable background service, worker, or data pipeline (runs as a process, no UI)
-      → --entity-type application --subtype app_custom_built  (or app_integration_service for crawlers/ETL)
+    Root project / top-level product application
+      → --entity-type application --subtype app_custom_built
+    Deployable sub-app under apps/* with UI
+      → --entity-type application_component --subtype app_comp_ui
+    Deployable sub-app under apps/* exposing API/backend service
+      → --entity-type application_component --subtype app_comp_api
+    Deployable background service, worker, job, ETL, or data pipeline under apps/*
+      → --entity-type application_component --subtype app_comp_worker / app_comp_job / app_comp_etl / app_comp_data_pipeline
     Shared internal library or package (imported by other packages, not deployed on its own)
       → --entity-type technology_component --subtype tech_library
     Shared UI component library
@@ -1489,7 +1524,7 @@ ${subPackages.map((sp) => `    • ${sp.name}  (${sp.relativePath})`).join("\n")
 
   ⚠️  DIRECTION MATTERS — wire relationships as follows:
 
-  Deployable sub-apps (apps/*) are PART OF the parent — child points to parent:
+  Deployable sub-apps (apps/*) are PART OF the parent application — child points to parent:
     npx nexarch add-relationship \\
       --from "<sub-app-key>" \\
       --to "${projectExternalKey}" \\
@@ -1504,7 +1539,11 @@ ${subPackages.map((sp) => `    • ${sp.name}  (${sp.relativePath})`).join("\n")
     (FROM = ${projectExternalKey}, TO = the library)
 
   ⚠️  WIRE DEPENDENCIES TO THE SUB-APP THAT DECLARES THEM, NOT TO THE PARENT.
-  After registering each sub-app/library entity, wire its npm dependencies to IT.
+
+  IMPORTANT: init-project has already written baseline dependency relationships from manifests.
+  Do NOT re-run add-relationship for entries listed as pre-wired below unless one of these is true:
+    • you changed the target entity key (e.g. you replaced a temporary key), or
+    • you are intentionally adding/changing relationship attributes beyond the scanned defaults.
 
   RELATIONSHIP TYPE RULES:
     application  → technology_component  : --type "depends_on"
@@ -1512,7 +1551,7 @@ ${subPackages.map((sp) => `    • ${sp.name}  (${sp.relativePath})`).join("\n")
     any → platform / platform_component  : --type "runs_on"   (NOT uses or depends_on)
     any → model                          : --type "uses_model"
 
-  Pre-resolved dependencies per sub-package (wire these after registering each entity):
+  Pre-resolved dependencies per sub-package (already wired by init-project; review only):
 ${subPackages.map((sp) => {
             const resolved = sp.depSpecs
                 .map((d) => resolvedByInput.get(d.name))
@@ -1521,9 +1560,11 @@ ${subPackages.map((sp) => {
                 return `    • ${sp.name}: (no pre-resolved deps — check package.json manually)`;
             const lines = resolved.map((r) => {
                 const relType = pickRelationshipType(r.entityTypeCode, sp.entityType);
-                return `        --to "${r.canonicalExternalRef}"  --type "${relType}"  # ${r.canonicalName}`;
+                const key = `${relType}::${sp.externalKey}::${r.canonicalExternalRef}`;
+                const status = preWiredRelationshipKeys.has(key) ? "[pre-wired]" : "[not pre-wired]";
+                return `        ${status} --from "${sp.externalKey}" --to "${r.canonicalExternalRef}"  --type "${relType}"  # ${r.canonicalName}`;
             });
-            return `    • ${sp.name} (--from "${sp.externalKey}"):\n${lines.join("\n")}`;
+            return `    • ${sp.name}:\n${lines.join("\n")}`;
         }).join("\n\n")}
 `;
         const adrStepNumber = subPackages.length > 0 ? "STEP 4" : "STEP 3";
@@ -1650,7 +1691,17 @@ ${subPkgSection}${adrSection}${gapCheckSection}`;
             const resolvedDeps = sp.depSpecs
                 .map((d) => resolvedByInput.get(d.name))
                 .filter((r) => !!r?.canonicalExternalRef)
-                .map((r) => ({ canonicalExternalRef: r.canonicalExternalRef, canonicalName: r.canonicalName, entityTypeCode: r.entityTypeCode }));
+                .map((r) => {
+                const relationshipTypeCode = pickRelationshipType(r.entityTypeCode, sp.entityType);
+                const relationshipKey = `${relationshipTypeCode}::${sp.externalKey}::${r.canonicalExternalRef}`;
+                return {
+                    canonicalExternalRef: r.canonicalExternalRef,
+                    canonicalName: r.canonicalName,
+                    entityTypeCode: r.entityTypeCode,
+                    relationshipTypeCode,
+                    preWired: preWiredRelationshipKeys.has(relationshipKey),
+                };
+            });
             return {
                 name: sp.name,
                 relativePath: sp.relativePath,
@@ -1667,6 +1718,12 @@ ${subPkgSection}${adrSection}${gapCheckSection}`;
         project: { name: displayName, externalKey: projectExternalKey, entityType: entityTypeOverride, detectedEcosystems },
         entities: entitiesResult.summary ?? {},
         relationships: relsResult?.summary ?? { requested: 0, succeeded: 0, failed: 0 },
+        metrics: {
+            entitiesSubmitted: entities.length,
+            relationshipsSubmitted: relationships.length,
+            relationshipAddAttempts,
+            relationshipsSkippedAsDuplicate: relationshipSkippedAsDuplicate,
+        },
         resolved: resolvedItems.length,
         unresolved: unresolvedItems.length,
         unresolvedSample: unresolvedItems.slice(0, 10).map((r) => r.input),
@@ -1693,6 +1750,9 @@ ${subPkgSection}${adrSection}${gapCheckSection}`;
     console.log(`\nDone.`);
     console.log(`  Entities     : ${output.entities.succeeded ?? 0} written, ${output.entities.failed ?? 0} failed`);
     console.log(`  Relationships: ${output.relationships.succeeded ?? 0} written`);
+    if (output.metrics.relationshipsSkippedAsDuplicate > 0) {
+        console.log(`  Deduped rels : ${output.metrics.relationshipsSkippedAsDuplicate} skipped as duplicates before upsert`);
+    }
     if (unresolvedItems.length > 0) {
         console.log(`  Candidates   : ${unresolvedItems.length} added to reference candidates`);
     }

package/dist/commands/policy-audit-submit.js

@@ -81,26 +81,31 @@ function parseFindings(args) {
         if (!Array.isArray(parsed) || parsed.length === 0) {
             throw new Error(findingsFile ? "--findings-file must contain a non-empty JSON array" : "--findings-json must be a non-empty JSON array");
         }
-        return parsed.map((item) => {
+        return parsed.map((item, index) => {
             const value = item;
-            const policyControlId = String(value.policyControlId ?? value.controlId ?? "").trim();
-            const policyRuleId = String(value.policyRuleId ?? value.ruleId ?? "").trim();
-            const result = String(value.result ?? "").toLowerCase();
+            const policyControlId = String(value.policyControlId ?? value.controlId ?? value.policy_control_id ?? "").trim();
+            const policyRuleId = String(value.policyRuleId ?? value.ruleId ?? value.policy_rule_id ?? "").trim();
+            const result = String(value.result ?? value.status ?? "").toLowerCase();
             if (!policyControlId || !policyRuleId || !result) {
-                throw new Error("Each finding must include policyControlId, policyRuleId, result. Tip: run 'nexarch policy-controls --entity <application:key> --json' and use the rule IDs from controls[].rules[].id");
+                throw new Error(`Finding #${index + 1} is missing required fields. Expected keys: policyControlId (or controlId/policy_control_id), policyRuleId (or ruleId/policy_rule_id), and result (or status). Example: [{\"policyControlId\":\"<uuid>\",\"policyRuleId\":\"<uuid>\",\"result\":\"pass\",\"rationale\":\"...\"}]`);
             }
             if (result !== "pass" && result !== "partial" && result !== "fail") {
-                throw new Error(`Invalid finding result '${String(value.result)}'. Use pass|partial|fail.`);
+                throw new Error(`Invalid finding result '${String(value.result ?? value.status)}' at finding #${index + 1}. Use pass|partial|fail.`);
             }
             const rationale = value.rationale
                 ? String(value.rationale)
                 : [value.summary, value.evidence].filter(Boolean).map(String).join("\n\n");
+            const missingRequirements = Array.isArray(value.missingRequirements)
+                ? value.missingRequirements.map(String)
+                : Array.isArray(value.missing_requirements)
+                    ? value.missing_requirements.map(String)
+                    : undefined;
             return {
                 policyControlId,
                 policyRuleId,
                 result,
                 ...(rationale ? { rationale } : {}),
-                ...(Array.isArray(value.missingRequirements) ? { missingRequirements: value.missingRequirements.map(String) } : {}),
+                ...(missingRequirements ? { missingRequirements } : {}),
             };
         });
     }

package/dist/commands/update-entity.js

@@ -22,48 +22,124 @@ function parseAttributesInput(jsonText, filePath) {
     if (!jsonText && !filePath)
         return null;
     if (jsonText && filePath) {
-        console.error("error: use only one of --attributes-json or --attributes-file");
-        process.exit(1);
+        throw new Error("Use only one of --attributes-json or --attributes-file");
     }
     let raw = jsonText;
     if (filePath) {
         if (!existsSync(filePath)) {
-            console.error(`error: --attributes-file not found: ${filePath}`);
-            process.exit(1);
+            throw new Error(`--attributes-file not found: ${filePath}`);
         }
         raw = readFileSync(filePath, "utf8");
     }
     try {
         const parsed = JSON.parse(raw ?? "{}");
         if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-            console.error("error: attributes input must be a JSON object");
-            process.exit(1);
+            throw new Error("Attributes input must be a JSON object");
         }
         return parsed;
     }
     catch (error) {
-        console.error(`error: invalid attributes JSON (${error instanceof Error ? error.message : "parse failed"})`);
-        process.exit(1);
+        throw new Error(`Invalid attributes JSON (${error instanceof Error ? error.message : "parse failed"})`);
     }
 }
+function parseEntityBatch(args) {
+    const entitiesFile = parseOptionValue(args, "--entities-file");
+    const entitiesJson = parseOptionValue(args, "--entities-json");
+    if (!entitiesFile && !entitiesJson)
+        return null;
+    if (entitiesFile && entitiesJson)
+        throw new Error("Use only one of --entities-file or --entities-json");
+    let raw = entitiesJson;
+    if (entitiesFile) {
+        if (!existsSync(entitiesFile))
+            throw new Error(`--entities-file not found: ${entitiesFile}`);
+        raw = readFileSync(entitiesFile, "utf8");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw ?? "[]");
+    }
+    catch {
+        throw new Error(entitiesFile ? "--entities-file must contain valid JSON array" : "--entities-json must be valid JSON array");
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0) {
+        throw new Error("Entities input must be a non-empty JSON array");
+    }
+    return parsed.map((item, index) => {
+        const v = (item ?? {});
+        const externalKey = String(v.externalKey ?? v.key ?? "").trim();
+        if (!externalKey)
+            throw new Error(`Entity #${index + 1} is missing externalKey/key`);
+        const entityTypeCode = String(v.entityTypeCode ?? v.entity_type_code ?? "application").trim() || "application";
+        const entitySubtypeCode = String(v.entitySubtypeCode ?? v.entity_subtype_code ?? "").trim();
+        const out = {
+            externalKey,
+            entityTypeCode,
+            confidence: 1,
+        };
+        if (typeof v.name === "string" && v.name.trim())
+            out.name = v.name.trim();
+        if (typeof v.description === "string" && v.description.trim())
+            out.description = v.description.trim();
+        if (entitySubtypeCode)
+            out.entitySubtypeCode = entitySubtypeCode;
+        const attrs = {
+            ...(v.attributes && typeof v.attributes === "object" && !Array.isArray(v.attributes) ? v.attributes : {}),
+        };
+        if (typeof v.icon === "string" && v.icon.trim()) {
+            attrs.application_icon = { provider: "lucide", name: v.icon.trim() };
+        }
+        if (Object.keys(attrs).length > 0)
+            out.attributes = attrs;
+        if (!out.name && !out.description && !out.attributes) {
+            throw new Error(`Entity #${index + 1} must include at least one of name, description, icon, or attributes`);
+        }
+        return out;
+    });
+}
 export async function updateEntity(args) {
     const asJson = parseFlag(args, "--json");
-    const externalKey = parseOptionValue(args, "--key");
-    const name = parseOptionValue(args, "--name");
-    const description = parseOptionValue(args, "--description");
-    const entityTypeCode = parseOptionValue(args, "--entity-type") ?? "application";
-    const entitySubtypeCode = parseOptionValue(args, "--subtype");
-    const iconName = parseOptionValue(args, "--icon");
-    const attributesJson = parseOptionValue(args, "--attributes-json");
-    const attributesFile = parseOptionValue(args, "--attributes-file");
-    if (!externalKey) {
-        console.error("error: --key <externalKey> is required");
-        process.exit(1);
+    const batchEntities = parseEntityBatch(args);
+    let entities;
+    if (batchEntities) {
+        entities = batchEntities;
     }
-    const explicitAttributes = parseAttributesInput(attributesJson, attributesFile);
-    if (!name && !description && !iconName && !explicitAttributes) {
-        console.error("error: provide at least one of --name, --description, --icon, --attributes-json, or --attributes-file");
-        process.exit(1);
+    else {
+        const externalKey = parseOptionValue(args, "--key");
+        const name = parseOptionValue(args, "--name");
+        const description = parseOptionValue(args, "--description");
+        const entityTypeCode = parseOptionValue(args, "--entity-type") ?? "application";
+        const entitySubtypeCode = parseOptionValue(args, "--subtype");
+        const iconName = parseOptionValue(args, "--icon");
+        const attributesJson = parseOptionValue(args, "--attributes-json");
+        const attributesFile = parseOptionValue(args, "--attributes-file");
+        if (!externalKey)
+            throw new Error("--key <externalKey> is required (or use --entities-file/--entities-json)");
+        const explicitAttributes = parseAttributesInput(attributesJson, attributesFile);
+        if (!name && !description && !iconName && !explicitAttributes) {
+            throw new Error("Provide at least one of --name, --description, --icon, --attributes-json, or --attributes-file");
+        }
+        const entity = {
+            externalKey,
+            entityTypeCode,
+            confidence: 1,
+        };
+        if (name)
+            entity.name = name;
+        if (description)
+            entity.description = description;
+        if (entitySubtypeCode)
+            entity.entitySubtypeCode = entitySubtypeCode;
+        const attributes = {
+            ...(explicitAttributes ?? {}),
+        };
+        if (iconName) {
+            attributes.application_icon = { provider: "lucide", name: iconName };
+        }
+        if (Object.keys(attributes).length > 0) {
+            entity.attributes = attributes;
+        }
+        entities = [entity];
     }
     const creds = requireCredentials();
     const mcpOpts = { companyId: creds.companyId };
@@ -74,7 +150,7 @@ export async function updateEntity(args) {
     const agentContext = {
         agentId: "nexarch-cli:update-entity",
         agentRunId: `update-entity-${Date.now()}`,
-        repoRef: externalKey,
+        repoRef: String(entities[0]?.externalKey ?? "batch"),
         observedAt: nowIso,
         source: "nexarch-cli",
         model: "n/a",
@@ -83,31 +159,7 @@ export async function updateEntity(args) {
     const policyContext = policyBundleHash
         ? { policyBundleHash, alignmentSummary: { score: 1, violations: [], waivers: [] } }
         : undefined;
-    const entity = {
-        externalKey,
-        entityTypeCode,
-        confidence: 1,
-    };
-    if (name)
-        entity.name = name;
-    if (description)
-        entity.description = description;
-    if (entitySubtypeCode)
-        entity.entitySubtypeCode = entitySubtypeCode;
-    const attributes = {
-        ...(explicitAttributes ?? {}),
-    };
-    // Convenience sugar; still generic because user can fully control payload via --attributes-json/file.
-    if (iconName) {
-        attributes.application_icon = {
-            provider: "lucide",
-            name: iconName,
-        };
-    }
-    if (Object.keys(attributes).length > 0) {
-        entity.attributes = attributes;
-    }
-    const raw = await callMcpTool("nexarch_upsert_entities", { entities: [entity], agentContext, policyContext }, mcpOpts);
+    const raw = await callMcpTool("nexarch_upsert_entities", { entities, agentContext, policyContext }, mcpOpts);
     const result = parseToolText(raw);
     if (asJson) {
         process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
@@ -118,14 +170,17 @@ export async function updateEntity(args) {
     const succeeded = result.summary?.succeeded ?? 0;
     const failed = result.summary?.failed ?? 0;
     if (failed > 0) {
-        console.error(`Failed to update entity: ${externalKey}`);
+        console.error(`Failed to update entities (${failed}/${entities.length}).`);
         for (const err of result.errors ?? []) {
             console.error(`  ${err.externalKey}: ${err.error} — ${err.message}`);
         }
         process.exitCode = 1;
         return;
     }
-    if (!asJson) {
-        console.log(`Updated ${succeeded} entity: ${externalKey}`);
+    if (entities.length === 1) {
+        console.log(`Updated ${succeeded} entity: ${String(entities[0].externalKey)}`);
+    }
+    else {
+        console.log(`Updated ${succeeded}/${entities.length} entities.`);
     }
 }

package/dist/index.js

@@ -99,24 +99,26 @@ Usage:
                                --dry-run  preview without writing
                                --json
   nexarch update-entity
-                      Update the name and/or description of an existing graph entity.
-                      Use this after init-project to enrich the entity with meaningful
-                      content from the project README or docs.
-                      Options: --key <externalKey>  (required)
-                               --name <name>
-                               --description <text>
-                               --entity-type <code>  (default: application)
-                               --subtype <code>
-                               --icon <lucide-name>  (convenience; sets attributes.application_icon)
-                               --attributes-json '<json object>'
-                               --attributes-file <path.json>
-                               --json
+                      Update existing graph entities (single or batch).
+                      Single options: --key <externalKey>
+                                      --name <name>
+                                      --description <text>
+                                      --entity-type <code>  (default: application)
+                                      --subtype <code>
+                                      --icon <lucide-name>  (sets attributes.application_icon)
+                                      --attributes-json '<json object>'
+                                      --attributes-file <path.json>
+                      Batch options:  --entities-json '<json array>'
+                                      --entities-file <path.json>
+                      --json
   nexarch add-relationship
-                      Add a relationship between two existing graph entities.
-                      Options: --from <externalKey>  (required)
-                               --to <externalKey>    (required)
-                               --type <code>         (required, e.g. part_of, depends_on)
-                               --json
+                      Add relationships between existing graph entities (single or batch).
+                      Single options: --from <externalKey>
+                                      --to <externalKey>
+                                      --type <code> (e.g. part_of, depends_on)
+                      Batch options:  --relationships-json '<json array>'
+                                      --relationships-file <path.json>
+                      --json
   nexarch register-alias
                       Register a company-scoped alias for an entity so future
                       scans resolve it instead of logging it as a candidate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",