nexarch 0.9.10 → 0.9.13

package/dist/commands/init-project.js

@@ -549,6 +549,17 @@ function findPackageJsonPaths(rootDir) {
                     const l1Pkg = join(l1Path, "package.json");
                     if (existsSync(l1Pkg)) {
                         pushPath(l1Pkg);
+                        // Resolve workspace sub-packages declared inside this project, so that
+                        // running init-project from a multi-project root still discovers nested
+                        // apps/* / packages/* within each child project.
+                        const l1PkgData = readRootPackage(l1Pkg);
+                        if (l1PkgData.workspaces) {
+                            for (const wsDir of resolveWorkspaceDirs(l1Path, l1PkgData.workspaces)) {
+                                const wsPkg = join(wsDir, "package.json");
+                                if (existsSync(wsPkg))
+                                    pushPath(wsPkg);
+                            }
+                        }
                         continue;
                     }
                     for (const l2 of readdirSync(l1Path)) {
@@ -887,14 +898,17 @@ function scanProject(dir) {
     };
 }
 // ─── Relationship type selection ──────────────────────────────────────────────
-function pickRelationshipType(toEntityTypeCode, _fromEntityTypeCode = "application") {
+function pickRelationshipType(toEntityTypeCode, toEntitySubtypeCode, _fromEntityTypeCode = "application") {
     switch (toEntityTypeCode) {
         case "model":
             return "uses_model";
         case "platform":
-        case "platform_component":
-            // runs_on is the valid ontology relationship from application/tech to platform
             return "runs_on";
+        case "platform_component":
+            // platform_service (Vercel Analytics, Vercel Postgres, Cloudinary, etc.) are opt-in
+            // managed services — integrates_with is the semantically correct relationship.
+            // Other platform_component subtypes (platform_runtime, platform_control_plane) use depends_on.
+            return toEntitySubtypeCode === "platform_service" ? "integrates_with" : "depends_on";
         case "skill":
             return "uses";
         case "technology_component":
@@ -1029,6 +1043,7 @@ export async function initProject(args) {
     const autoMapApplication = parseFlag(args, "--auto-map-application");
     const nonInteractive = parseFlag(args, "--non-interactive");
     const upsertBatchSize = Number(parseOptionValue(args, "--batch-size") ?? "10") || 10;
+    const refreshMode = parseFlag(args, "--refresh");
     const creds = requireCredentials();
     const mcpOpts = { companyId: creds.companyId };
     if (!asJson)
@@ -1222,8 +1237,24 @@ export async function initProject(args) {
         }
     }
     logProgress("application.target", projectExternalKey);
+    // In refresh mode, snapshot the current graph state for this project before writing,
+    // so we can diff what changed and surface stale relationships to the agent.
+    let currentOutgoingRels = [];
+    let currentPartOfRels = [];
+    if (refreshMode) {
+        logProgress("refresh.fetch.start");
+        if (!asJson)
+            console.log("\nFetching current graph state…");
+        const [outgoingRaw, partOfRaw] = await Promise.all([
+            callMcpProfiled("nexarch_list_relationships", { companyId: creds.companyId, fromEntityExternalKey: projectExternalKey, limit: 500 }, { phase: "refresh.outgoing" }),
+            callMcpProfiled("nexarch_list_relationships", { companyId: creds.companyId, toEntityExternalKey: projectExternalKey, relationshipTypeCode: "part_of", limit: 500 }, { phase: "refresh.partOf" }),
+        ]);
+        currentOutgoingRels = parseToolText(outgoingRaw).relationships ?? [];
+        currentPartOfRels = parseToolText(partOfRaw).relationships ?? [];
+        logProgress("refresh.fetch.done", `outgoing=${currentOutgoingRels.length}, partOf=${currentPartOfRels.length}`);
+    }
     const agentContext = {
-        agentId: "nexarch-cli:init-project",
+        agentId: refreshMode ? "nexarch-cli:update-project" : "nexarch-cli:init-project",
         agentRunId: `init-project-${Date.now()}`,
         repoRef,
         repoPath,
@@ -1343,7 +1374,7 @@ export async function initProject(args) {
         if (!rootDepNames.has(r.input) && !rootDepNames.has(r.normalised))
             continue;
         const depSpec = rootDepVersions.get(r.input) ?? rootDepVersions.get(r.normalised);
-        addRel(pickRelationshipType(r.entityTypeCode), projectExternalKey, r.canonicalExternalRef, 0.9, {
+        addRel(pickRelationshipType(r.entityTypeCode, r.entitySubtypeCode), projectExternalKey, r.canonicalExternalRef, 0.9, {
             source: depSpec?.source ?? "manifest_scan",
             detected_at: nowIso,
             ...buildVersionAttributes(depSpec?.versionRaw ?? null, depSpec?.source ?? "manifest_scan"),
@@ -1363,7 +1394,7 @@ export async function initProject(args) {
             const r = resolvedByInput.get(dep.name);
             if (!r?.canonicalExternalRef || !r.entityTypeCode)
                 continue;
-            addRel(pickRelationshipType(r.entityTypeCode, sp.entityType), sp.externalKey, r.canonicalExternalRef, 0.9, {
+            addRel(pickRelationshipType(r.entityTypeCode, r.entitySubtypeCode, sp.entityType), sp.externalKey, r.canonicalExternalRef, 0.9, {
                 source: dep.source,
                 detected_at: nowIso,
                 ...buildVersionAttributes(dep.versionRaw, dep.source),
@@ -1393,6 +1424,22 @@ export async function initProject(args) {
     if (detectedRepo?.canonicalRepoRef) {
         addRel("depends_on", projectExternalKey, detectedRepo.canonicalRepoRef, 0.95);
     }
+    let graphDiff = null;
+    if (refreshMode) {
+        const newRelKeySet = new Set(relationships.map((r) => `${r.relationshipTypeCode}::${r.fromEntityExternalKey}::${r.toEntityExternalKey}`));
+        const currentRelKeySet = new Set(currentOutgoingRels
+            .filter((r) => r.fromEntityExternalKey && r.toEntityExternalKey)
+            .map((r) => `${r.relationshipTypeCode}::${r.fromEntityExternalKey}::${r.toEntityExternalKey}`));
+        const newRelationshipsInDiff = relationships.filter((r) => !currentRelKeySet.has(`${r.relationshipTypeCode}::${r.fromEntityExternalKey}::${r.toEntityExternalKey}`));
+        const staleRelationships = currentOutgoingRels.filter((r) => r.fromEntityExternalKey &&
+            r.toEntityExternalKey &&
+            !newRelKeySet.has(`${r.relationshipTypeCode}::${r.fromEntityExternalKey}::${r.toEntityExternalKey}`));
+        const currentSubPackageKeys = new Set(currentPartOfRels.map((r) => r.fromEntityExternalKey).filter((k) => Boolean(k)));
+        const newSubPackageKeys = new Set(subPackages.map((sp) => sp.externalKey));
+        const removedSubPackageKeys = [...currentSubPackageKeys].filter((k) => !newSubPackageKeys.has(k));
+        graphDiff = { newRelationships: newRelationshipsInDiff, staleRelationships, removedSubPackageKeys };
+        logProgress("refresh.diff", `newRels=${newRelationshipsInDiff.length}, staleRels=${staleRelationships.length}, removedSubPkgs=${removedSubPackageKeys.length}`);
+    }
     if (!asJson)
         console.log(`\nWriting to graph…`);
     // Upsert entities (chunked for progressive feedback)
@@ -1455,276 +1502,174 @@ export async function initProject(args) {
         }
         logProgress("upsert.relationships.done", `succeeded=${relsResult.summary?.succeeded ?? 0}, failed=${relsResult.summary?.failed ?? 0}`);
     }
-    // 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(", ")
-            : "unknown";
-        const manifestHint = detectedEcosystems.includes("nodejs")
-            ? "package.json"
-            : detectedEcosystems.includes("python")
-                ? "pyproject.toml / requirements.txt"
-                : detectedEcosystems.includes("go")
-                    ? "go.mod"
-                    : detectedEcosystems.includes("ruby")
-                        ? "Gemfile"
-                        : detectedEcosystems.includes("rust")
-                            ? "Cargo.toml"
-                            : "dependency manifest";
-        const subPkgSection = subPackages.length === 0 ? "" : `
-STEP 3 — Classify and register each sub-package as its own entity.
-  The scanner found ${subPackages.length} workspace package(s):
-
-${subPackages.map((sp) => `    • ${sp.name}  (${sp.relativePath})`).join("\n")}
-
-  For each one, READ its package.json and any README to understand what it actually is,
-  then choose the correct entity type and subtype before running update-entity:
-
-  CLASSIFICATION GUIDE — pick the best fit:
-    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
-      → --entity-type technology_component --subtype tech_framework
-    Type definitions or utility package with no runtime
-      → --entity-type technology_component --subtype tech_library
-
-  ICON ASSIGNMENT (applications only):
-    • Pick one icon from the full Lucide icon set for each application/sub-app.
-    • If confidence is low, skip --icon rather than guessing.
-    • Use kebab-case icon names (example: server, workflow, shield-check).
-
-  For each sub-package, run update-entity to register it:
-
-  npx nexarch update-entity \\
-    --key "<entity-type>:<slugified-package-name>" \\
-    --entity-type "<chosen entity type>" \\
-    --subtype "<chosen subtype>" \\
-    --name "<human readable name>" \\
-    --description "<what this package does and its role in the project>" \\
-    --icon "<lucide icon>"   # applications only
-
-  Then register it as a resolvable alias so future scans don't re-surface it as a candidate:
-
-  npx nexarch register-alias \\
-    --alias "<original package name e.g. @scope/name>" \\
-    --key "<same entity-type>:<slugified-package-name>" \\
-    --name "<same human readable name>" \\
-    --entity-type "<same entity type>"
-
-  ⚠️  DIRECTION MATTERS — wire relationships as follows:
-
-  Deployable sub-apps (apps/*) are PART OF the parent application — child points to parent:
-    npx nexarch add-relationship \\
-      --from "<sub-app-key>" \\
-      --to "${projectExternalKey}" \\
-      --type "part_of"
-    (FROM = the sub-app, TO = ${projectExternalKey})
-
-  Shared libraries (packages/*) are depended on by the parent — parent points to library:
-    npx nexarch add-relationship \\
-      --from "${projectExternalKey}" \\
-      --to "<library-key>" \\
-      --type "depends_on"
-    (FROM = ${projectExternalKey}, TO = the library)
-
-  ⚠️  WIRE DEPENDENCIES TO THE SUB-APP THAT DECLARES THEM, NOT TO THE PARENT.
-
-  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"
-    technology_component → technology_component : --type "depends_on"
-    any → platform                       : --type "runs_on"
-    any → platform_component             : --type "depends_on" (or "integrates_with" where appropriate)
-    any → model                          : --type "uses_model"
-
-  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))
-                .filter((r) => !!r?.canonicalExternalRef);
-            if (resolved.length === 0)
-                return `    • ${sp.name}: (no pre-resolved deps — check package.json manually)`;
-            const lines = resolved.map((r) => {
-                const relType = pickRelationshipType(r.entityTypeCode, sp.entityType);
-                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}:\n${lines.join("\n")}`;
-        }).join("\n\n")}
-`;
-        const adrStepNumber = subPackages.length > 0 ? "STEP 4" : "STEP 3";
-        const finalStep = subPackages.length > 0 ? "STEP 5" : "STEP 4";
-        const adrSection = `
-${adrStepNumber} — Ask the enrichment agent to extract ADRs and register decision records.
-
-  Do NOT rely on init-project to parse ADR files. The enrichment agent should read ADR markdown and
-  explicitly register decision records with relationships.
-
-  Agent task:
-    • Find ADR files (e.g. docs/adr, adrs, decisions, ADR-*.md)
-    • For each ADR, create/update a decision record entity
-    • Link it using: decision_record --decides--> application/sub-app
-
-  REQUIRED fields to pass per decision (strict):
-    • key:      decision_record:<project>-<adr-slug>
-    • subtype:  decision_architecture
-    • name:     ADR title
-    • decision summary: short business summary (1–3 sentences)
-    • decision detail: full decision detail in markdown (context + decision + consequences)
-
-  Command pattern:
-    npx nexarch update-entity \\
-      --key "decision_record:<project>-<adr-slug>" \\
-      --entity-type "decision_record" \\
-      --subtype "decision_architecture" \\
-      --name "<ADR title>" \\
-      --attributes-json '{"decision":{"summary":"<short summary>","detail":"## Context\\n<context>\\n\\n## Decision\\n<decision>\\n\\n## Consequences\\n<consequences>"}}'
-
-    npx nexarch add-relationship \\
-      --from "decision_record:<project>-<adr-slug>" \\
-      --to "<application-or-sub-app-key>" \\
-      --type "decides"
-`;
-        const gapCheckSection = `
-${finalStep} — Identify architecturally significant components not auto-detected.
-
-  The mechanical scan only finds declared dependencies, env var names, and a few config files.
-  It systematically misses hosting platforms, managed infrastructure, SaaS integrations,
-  and external APIs that are only mentioned in README or deployment config.
-
-  Review what you've read and ask yourself: are there any of the following that are
-  clearly part of this system's architecture but weren't auto-detected?
-
-    • Hosting / deployment platforms  (Vercel, Railway, Fly.io, AWS, GCP, Azure…)
-    • Managed data services           (Neon, PlanetScale, Supabase, Upstash, Atlas…)
-    • Auth / identity providers       (Clerk, Auth0, WorkOS, Okta…)
-    • External SaaS integrations      (Stripe, Resend, SendGrid, Twilio, Sentry…)
-    • CDN / storage / queues          (Cloudflare, S3, CloudFront, SQS, Redis…)
-    • CI/CD platforms                 (GitHub Actions, GitLab CI, CircleCI…)
-
-  ONLY register entries you are highly confident about — i.e. explicitly mentioned in
-  the README, a config file, or a deployment manifest. Do not guess.
-
-  For each one you identify:
-
-  1. Resolve it to a canonical reference:
-     npx nexarch resolve-names --names "<platform name>" --json
-
-  2. If resolved, instantiate the entity in the graph (REQUIRED before add-relationship):
-     npx nexarch update-entity \\
-       --key "<resolved-ref>" \\
-       --entity-type "<entityTypeCode from resolve-names>" \\
-       --name "<canonicalName from resolve-names>"
-
-  3. Wire the relationship:
-     npx nexarch add-relationship \\
-       --from "${projectExternalKey}" \\
-       --to "<resolved-ref>" \\
-       --type "runs_on"    # for platforms (Vercel, Neon, etc.)
-       # use --type "depends_on" for external APIs/SaaS (Stripe, Resend, etc.)
-
-  4. If unresolved (not in the reference library), skip it for now — it will appear
-     as a reference candidate on the next scan once you register an alias for it.
-`;
-        const fallbackTemplate = `
-╔══════════════════════════════════════════════════════════════════╗
-║  ENRICHMENT TASK — action required                               ║
-╚══════════════════════════════════════════════════════════════════╝
-
-The mechanical scan has written a skeleton graph entry for this project (NOT fully enriched).
-You now need to enrich it with meaningful content before considering registration complete.
-
-PROJECT ENTITY  : ${projectExternalKey}
-PROJECT DIR     : ${dir}
-ECOSYSTEM(S)    : ${ecosystemLabel}
-MANIFEST        : ${manifestHint}
-${readmeHints.length > 0 ? `README FILES    : ${readmeHints.join(", ")}` : "README FILES    : (none found — check docs/)"}
-
-IMPORTANT REPORTING RULE:
-  Do NOT report "fully registered" or "fully done" after init-project alone.
-  Correct status after init-project is: "skeleton created; enrichment pending" until Steps 1+ are completed.
-
-STEP 1 — Read the project README / docs and build your understanding of:
-  • What does this project do? (business purpose, key features)
-  • Who are the users?
-  • What is the high-level architecture?
-  • Any notable technical decisions or constraints?
-
-STEP 2 — Enrich the project entity. Run this command with the description you've written:
-
-  ENRICHMENT QUALITY RULE:
-    • Do enrichment as explicit per-entity updates.
-    • Do NOT shortcut with bulk entity updates for semantic enrichment.
-    • The goal is accurate, evidence-based descriptions/subtypes per entity, not just write throughput.
-
-  npx nexarch update-entity \\
-    --key "${projectExternalKey}" \\
-    --entity-type "${entityTypeOverride}"${entityTypeOverride === "application" ? " \\\n    --subtype \"app_custom_built\" \\\n    --icon \"<curated icon>\"" : ""} \\
-    --name "<proper product name from README>" \\
-    --description "<2–4 sentence summary of what it does and why>"
-${subPkgSection}${adrSection}${gapCheckSection}`;
-        return fallbackTemplate;
-    }
-    const enrichmentTask = {
-        template: {
-            code: "builtin:init-project-enrichment",
-            source: "builtin",
-            registryVersion: null,
-        },
-        instructions: buildEnrichmentInstructions(),
-        iconHints: {
-            provider: "lucide",
-            note: "Use any Lucide icon name for agent-selected enrichment icons; omit icon when low confidence.",
-        },
-        projectEntity: {
-            externalKey: projectExternalKey,
-            entityType: entityTypeOverride,
-            readmeFiles: readmeHints,
-        },
-        subPackages: subPackages.map((sp) => {
-            const resolvedDeps = sp.depSpecs
-                .map((d) => resolvedByInput.get(d.name))
-                .filter((r) => !!r?.canonicalExternalRef)
-                .map((r) => {
-                const relationshipTypeCode = pickRelationshipType(r.entityTypeCode, sp.entityType);
-                const relationshipKey = `${relationshipTypeCode}::${sp.externalKey}::${r.canonicalExternalRef}`;
+    // Confidence heuristic for sub-package classification based on path signals.
+    function subPackageConfidence(sp) {
+        if (sp.relativePath.startsWith("packages/"))
+            return 0.75;
+        if (sp.relativePath.startsWith("apps/"))
+            return 0.70;
+        return 0.60;
+    }
+    // Build the structured enrichment payload for JSON output.
+    function buildEnrichmentPayload() {
+        return {
+            status: "enrichment_required",
+            projectEntity: {
+                externalKey: projectExternalKey,
+                entityType: entityTypeOverride,
+            },
+            readFiles: readmeHints,
+            classifyPackages: subPackages.map((sp) => {
+                const resolvedDeps = sp.depSpecs
+                    .map((d) => resolvedByInput.get(d.name))
+                    .filter((r) => !!r?.canonicalExternalRef)
+                    .map((r) => {
+                    const relationshipTypeCode = pickRelationshipType(r.entityTypeCode, r.entitySubtypeCode, 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 {
-                    canonicalExternalRef: r.canonicalExternalRef,
-                    canonicalName: r.canonicalName,
-                    entityTypeCode: r.entityTypeCode,
-                    relationshipTypeCode,
-                    preWired: preWiredRelationshipKeys.has(relationshipKey),
+                    name: sp.name,
+                    relativePath: sp.relativePath,
+                    externalKey: sp.externalKey,
+                    heuristicEntityType: sp.entityType,
+                    heuristicSubtype: sp.subtype,
+                    confidence: subPackageConfidence(sp),
+                    resolvedDeps,
+                    unresolvedDeps: sp.depSpecs.map((d) => d.name).filter((d) => !resolvedByInput.has(d)),
                 };
-            });
-            return {
-                name: sp.name,
-                relativePath: sp.relativePath,
-                externalKey: sp.externalKey,
-                inferredEntityType: sp.entityType,
-                inferredSubtype: sp.subtype,
-                resolvedDeps,
-                unresolvedDeps: sp.depSpecs.map((d) => d.name).filter((d) => !resolvedByInput.has(d)),
-            };
-        }),
-    };
+            }),
+            unresolvedNames: unresolvedItems.map((r) => r.input),
+            iconHints: {
+                provider: "lucide",
+                note: "Use any Lucide icon name (kebab-case); omit when confidence is low.",
+            },
+            ...(graphDiff
+                ? {
+                    diff: {
+                        newRelationships: graphDiff.newRelationships.map((r) => ({
+                            type: r.relationshipTypeCode,
+                            from: r.fromEntityExternalKey,
+                            to: r.toEntityExternalKey,
+                        })),
+                        staleRelationships: graphDiff.staleRelationships.map((r) => ({
+                            type: r.relationshipTypeCode,
+                            from: r.fromEntityExternalKey,
+                            to: r.toEntityExternalKey,
+                            fromName: r.fromEntityName ?? null,
+                            toName: r.toEntityName ?? null,
+                        })),
+                        removedSubPackageKeys: graphDiff.removedSubPackageKeys,
+                    },
+                }
+                : {}),
+        };
+    }
+    // Build an agent-directed directive block for human/terminal output.
+    // This is addressed to the *calling agent* (Claude Code, Codex, etc.) and tells it
+    // to act inline in this same session — not to queue enrichment for later.
+    function buildEnrichmentDirective() {
+        const lines = [];
+        lines.push("─── ENRICHMENT REQUIRED ─────────────────────────────────────────────────");
+        lines.push("init-project wrote a skeleton. Complete enrichment NOW — do not ask the");
+        lines.push("user for permission, do not summarise and pause, just execute the steps.");
+        lines.push("Do NOT report the project as registered until enrichment is done.");
+        lines.push("");
+        lines.push(`PROJECT : ${projectExternalKey}`);
+        lines.push(`DIR     : ${dir}`);
+        if (readmeHints.length > 0) {
+            lines.push("");
+            lines.push("READ_THESE first:");
+            for (const f of readmeHints)
+                lines.push(`  ${join(dir, f)}`);
+        }
+        else {
+            lines.push("");
+            lines.push("READ_THESE first: (no README found — check docs/ for any markdown overview)");
+        }
+        if (subPackages.length > 0) {
+            lines.push("");
+            lines.push(`CLASSIFY_THESE (${subPackages.length} sub-package(s) — read each, confirm type, then update):`);
+            for (const sp of subPackages) {
+                const conf = subPackageConfidence(sp);
+                lines.push(`  ${sp.relativePath}`);
+                lines.push(`    key      : ${sp.externalKey}`);
+                lines.push(`    inferred : ${sp.entityType} / ${sp.subtype}  (confidence ${conf.toFixed(2)})`);
+                const unresolvedDeps = sp.depSpecs.map((d) => d.name).filter((d) => !resolvedByInput.has(d));
+                if (unresolvedDeps.length > 0) {
+                    lines.push(`    unresolved deps (${unresolvedDeps.length}): ${unresolvedDeps.slice(0, 5).join(", ")}${unresolvedDeps.length > 5 ? ` … +${unresolvedDeps.length - 5} more` : ""}`);
+                }
+                lines.push(`    → nexarch update-entity --key "${sp.externalKey}" --entity-type "${sp.entityType}" --subtype "${sp.subtype}" --name "..." --description "..."`);
+            }
+        }
+        if (unresolvedItems.length > 0) {
+            lines.push("");
+            lines.push(`UNRESOLVED (${unresolvedItems.length} names not matched in reference library):`);
+            const sample = unresolvedItems.slice(0, 20).map((r) => r.input);
+            lines.push(`  ${JSON.stringify(sample)}`);
+            if (unresolvedItems.length > 20)
+                lines.push(`  … and ${unresolvedItems.length - 20} more`);
+        }
+        lines.push("");
+        lines.push("THEN_RUN (execute these steps immediately — do not pause or ask for confirmation):");
+        let step = 1;
+        lines.push(`  ${step++}. nexarch update-entity --key "${projectExternalKey}" --entity-type "${entityTypeOverride}"${entityTypeOverride === "application" ? ' --subtype "<subtype>" --icon "<lucide-icon>"' : ""} --name "..." --description "..."`);
+        if (entityTypeOverride === "application") {
+            lines.push(`     Valid subtypes: app_custom_built  app_saas  app_mobile  app_cli  app_integration_service  app_data_pipeline`);
+            lines.push(`     (choose app_custom_built as the default if none of the others clearly apply)`);
+        }
+        if (subPackages.length > 0) {
+            lines.push(`  ${step++}. Update each sub-package listed under CLASSIFY_THESE above.`);
+        }
+        lines.push(`  ${step++}. Scan the READMEs for platforms/SaaS not auto-detected (Vercel, Neon, Stripe, etc.).`);
+        lines.push(`       For each found: nexarch resolve-names --names "..." --json  →  nexarch update-entity  →  nexarch add-relationship`);
+        lines.push(`  ${step++}. Look for ADRs (docs/adr/, decisions/, ADR-*.md) and register decision_record entities.`);
+        lines.push(`       nexarch update-entity --key "decision_record:${projectExternalKey.split(":")[1] ?? "project"}-<adr-slug>" --entity-type decision_record --subtype decision_architecture --name "..." --attributes-json '{"decision":{"summary":"...","detail":"..."}}'`);
+        lines.push(`       nexarch add-relationship --from "decision_record:..." --to "${projectExternalKey}" --type decides`);
+        lines.push("");
+        lines.push("RELATIONSHIP DIRECTION RULES (for sub-packages):");
+        lines.push("  apps/* (deployable components) → part_of → parent application");
+        lines.push("  packages/* (shared libraries)  → parent depends_on → library");
+        lines.push("  Deps wired from manifests are already pre-wired; do not re-add unless key changed.");
+        if (graphDiff) {
+            if (graphDiff.staleRelationships.length > 0) {
+                lines.push("");
+                lines.push(`STALE_RELATIONSHIPS (${graphDiff.staleRelationships.length} — in graph but no longer in manifests; review and retire if confirmed removed):`);
+                for (const r of graphDiff.staleRelationships) {
+                    const from = r.fromEntityExternalKey ?? r.fromEntityName ?? "?";
+                    const to = r.toEntityExternalKey ?? r.toEntityName ?? "?";
+                    lines.push(`  [${r.relationshipTypeCode}]  ${from}  →  ${to}`);
+                }
+            }
+            if (graphDiff.removedSubPackageKeys.length > 0) {
+                lines.push("");
+                lines.push(`REMOVED_SUB_PACKAGES (${graphDiff.removedSubPackageKeys.length} — previously registered but no longer found in filesystem; retire or reassign):`);
+                for (const k of graphDiff.removedSubPackageKeys)
+                    lines.push(`  ${k}`);
+            }
+            if (graphDiff.staleRelationships.length === 0 && graphDiff.removedSubPackageKeys.length === 0) {
+                lines.push("");
+                lines.push("DIFF: No stale relationships or removed sub-packages detected.");
+            }
+        }
+        lines.push("");
+        lines.push("─────────────────────────────────────────────────────────────────────────");
+        return lines.join("\n");
+    }
+    const enrichmentRequired = buildEnrichmentPayload();
     const output = {
         ok: Number(entitiesResult.summary?.failed ?? 0) === 0,
+        status: "enrichment_required",
+        mode: refreshMode ? "refresh" : "init",
         project: { name: displayName, externalKey: projectExternalKey, entityType: entityTypeOverride, detectedEcosystems },
         entities: entitiesResult.summary ?? {},
         relationships: relsResult?.summary ?? { requested: 0, succeeded: 0, failed: 0 },
@@ -1736,10 +1681,9 @@ ${subPkgSection}${adrSection}${gapCheckSection}`;
         },
         resolved: resolvedItems.length,
         unresolved: unresolvedItems.length,
-        unresolvedSample: unresolvedItems.slice(0, 10).map((r) => r.input),
         entityErrors: entitiesResult.errors ?? [],
         relationshipErrors: relsResult?.errors ?? [],
-        enrichmentTask,
+        enrichmentRequired,
         profile: profileEnabled
             ? {
                 startedAt: profile.startedAt,
@@ -1758,6 +1702,7 @@ ${subPkgSection}${adrSection}${gapCheckSection}`;
         return;
     }
     console.log(`\nDone.`);
+    console.log(`  Mode         : ${refreshMode ? "refresh (update-project)" : "init"}`);
     console.log(`  Entities     : ${output.entities.succeeded ?? 0} written, ${output.entities.failed ?? 0} failed`);
     console.log(`  Relationships: ${output.relationships.succeeded ?? 0} written`);
     console.log("  Status       : skeleton created; enrichment pending");
@@ -1767,13 +1712,19 @@ ${subPkgSection}${adrSection}${gapCheckSection}`;
     if (unresolvedItems.length > 0) {
         console.log(`  Candidates   : ${unresolvedItems.length} added to reference candidates`);
     }
+    if (graphDiff && graphDiff.staleRelationships.length > 0) {
+        console.log(`  Stale rels   : ${graphDiff.staleRelationships.length} in graph but absent from manifests (see STALE_RELATIONSHIPS below)`);
+    }
+    if (graphDiff && graphDiff.removedSubPackageKeys.length > 0) {
+        console.log(`  Removed pkgs : ${graphDiff.removedSubPackageKeys.length} sub-packages no longer on filesystem (see REMOVED_SUB_PACKAGES below)`);
+    }
     if (output.entityErrors.length > 0) {
         console.log("\nEntity errors:");
         for (const err of output.entityErrors) {
             console.log(`  ${err.externalKey}: ${err.error} — ${err.message}`);
         }
     }
-    // ─── Enrichment task ────────────────────────────────────────────────────────
-    console.log(enrichmentTask.instructions);
+    // ─── Enrichment directive ───────────────────────────────────────────────────
+    console.log(buildEnrichmentDirective());
     logProgress("complete", `ok=${output.ok}`);
 }

package/dist/commands/update-entity.js

@@ -52,7 +52,7 @@ export async function updateEntity(args) {
         console.error("error: batch entity updates were removed. Use explicit per-entity update-entity commands for enrichment quality.");
         process.exit(1);
     }
-    const externalKey = parseOptionValue(args, "--key");
+    const externalKey = parseOptionValue(args, "--key") ?? parseOptionValue(args, "--external-key");
     const name = parseOptionValue(args, "--name");
     const description = parseOptionValue(args, "--description");
     const entityTypeCode = parseOptionValue(args, "--entity-type") ?? "application";

package/dist/index.js

@@ -32,6 +32,7 @@ const commands = {
     "init-agent": initAgent,
     "agent-identify": agentIdentify,
     "init-project": initProject,
+    "update-project": (args) => initProject(["--refresh", ...args]),
     "update-entity": updateEntity,
     "add-relationship": addRelationship,
     "register-alias": registerAlias,
@@ -98,6 +99,19 @@ Usage:
                                --profile  include timing/profile data in JSON output
                                --dry-run  preview without writing
                                --json
+  nexarch update-project
+                      Re-scan a previously registered project directory, refresh
+                      entities and relationships in the graph, and diff the new scan
+                      against the current graph state to surface stale relationships
+                      and removed sub-packages for the calling agent to review.
+                      Accepts all the same options as init-project plus:
+                               --application-ref <entityRef>  target project key (recommended)
+                               --auto-map-application  auto-select best-match application
+                      Output includes enrichmentRequired.diff with:
+                        newRelationships    — detected but not yet in graph
+                        staleRelationships  — in graph but absent from manifests
+                        removedSubPackages  — previously registered, no longer on disk
+                               --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

package/package.json

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