nexarch 0.13.2 → 0.13.4

package/dist/commands/init-agent.js

@@ -613,8 +613,9 @@ function injectInitProjectReportingContract(path) {
         "**One exception: a possible duplicate.** If init-project returns `status: \"review_required\"`",
         "or prints `STOP — POSSIBLE DUPLICATE`, an application already in the workspace looks like",
         "one it would register, and it wrote nothing. Tell the human which one you think matches and",
-        "why, wait for their answer, then re-run init-project with the command for their choice",
-        "(`decision.commands` in the output). Only then continue with enrichment.",
+        "why, wait for their answer, then run the command for their choice yourself",
+        "(`decision.commands` in the output) and continue. If it is the same system, enrich the",
+        "existing application — nothing needs merging.",
         "",
         "Stop early only when a step genuinely cannot run — missing cloud credentials, a root",
         "module that has not been initialised, or an environment you should not touch without",

package/dist/commands/init-project.js

@@ -1315,7 +1315,8 @@ export function enrichmentStatusFor(params) {
 }
 export const REVIEW_REQUIRED_NOTE = "STOP. Nothing was written. Existing applications in this workspace resemble what this scan would register"
     + " (see similarApplications). Tell the human, say which one you think is the same system and why, and wait for"
-    + " their answer. Then re-run init-project with the command in `decision.commands` that matches their choice.";
+    + " their answer. Then run the command in `decision.commands` for their choice yourself and carry on. If it is the"
+    + " same system, enrich the existing application: nothing needs merging.";
 /**
  * The possible-duplicate warning for the text directive, first thing in it.
  *
@@ -1338,6 +1339,7 @@ export function possibleDuplicateDirective(matches, isMonorepo) {
             ? "  same system      npx nexarch@latest init-project --dir . --map-deployable <deployable>=<entityRef>"
             : "  same application npx nexarch@latest init-project --dir . --application-ref <entityRef>",
         "  all different    npx nexarch@latest init-project --dir . --create-application",
+        "Run the command for their answer yourself. If it is the same system, enrich the existing application — nothing needs merging.",
     ];
 }
 /**
@@ -1684,6 +1686,11 @@ export async function initProject(args) {
     let stopForReview = null;
     // Names of applications already in the workspace, by ref, for mapped deployables.
     const existingApplicationNames = new Map();
+    // Refs of those that are still proposals: a mapped deployable's leftover
+    // duplicate from an earlier scan is folded away only if nobody reviewed it.
+    const proposedApplicationRefs = new Set();
+    // What happened to each leftover duplicate, for the output.
+    const foldedDuplicates = [];
     if (projectConstruct && isMonorepo && (applicationRefOverride || forceCreateApplication) && !asJson) {
         console.log("\nNote: monorepo detected — no root application is created (ADR 8a); --application-ref/--create-application apply only to single-package repositories.");
     }
@@ -1780,8 +1787,11 @@ export async function initProject(args) {
         const listed = parseToolText(appsRaw).entities ?? [];
         for (const entity of listed) {
             const ref = entity.entityRef ?? entity.externalKey;
-            if (ref)
-                existingApplicationNames.set(ref, entity.name);
+            if (!ref)
+                continue;
+            existingApplicationNames.set(ref, entity.name);
+            if (String(entity.attributes?.workflow_state ?? "").toLowerCase() === "proposed")
+                proposedApplicationRefs.add(ref);
         }
         // A mapped deployable writes no stub of its own, so a mapping to an
         // application that is not there would leave its relationships pointing at
@@ -2172,6 +2182,42 @@ export async function initProject(args) {
             // ability to resolve via tier 2; the scan itself already succeeded.
         }
     }
+    // "There should be nothing to merge" (Paul, 16 September). When the human has
+    // confirmed a deployable is an existing application, an earlier scan may
+    // already have registered that deployable as a proposal of its own -- the
+    // 0.13.1 behaviour, or any run before the duplicate check stopped the scan.
+    // Fold it into the existing application here, so the agent carries on
+    // enriching the real one and nobody has to press Merge. Only unreviewed
+    // proposals: the gateway refuses anything a human has activated.
+    for (const sp of subPackages) {
+        if (sp.mappedBy !== "flag" || !sp.mappedFrom || !proposedApplicationRefs.has(sp.mappedFrom))
+            continue;
+        try {
+            const raw = await callMcpTool("nexarch_merge_proposed_application", {
+                proposedApplicationRef: sp.mappedFrom,
+                intoApplicationRef: sp.externalKey,
+                reason: `The human confirmed the ${sp.relativePath} deployable is ${existingApplicationNames.get(sp.externalKey) ?? sp.externalKey}.`,
+                companyId: creds.companyId,
+            }, { companyId: creds.companyId });
+            const result = parseToolText(raw);
+            foldedDuplicates.push({
+                proposedApplicationRef: sp.mappedFrom,
+                intoApplicationRef: sp.externalKey,
+                folded: true,
+                detail: `folded in; ${result.relationshipsRepointed ?? 0} relationship(s) moved to ${sp.externalKey}`,
+            });
+        }
+        catch (error) {
+            // An older gateway without the tool, or a credential without the scope.
+            // Say so plainly: the duplicate is still there and the human should know.
+            foldedDuplicates.push({
+                proposedApplicationRef: sp.mappedFrom,
+                intoApplicationRef: sp.externalKey,
+                folded: false,
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
     // Remember an explicit --map-deployable, so the next scan does not ask again.
     // A merge registers the same alias; this is the same decision made up front.
     for (const sp of subPackages) {
@@ -2249,8 +2295,7 @@ export async function initProject(args) {
         if (similarApplications.length > 0 && isMonorepo) {
             // --application-ref does not apply to a monorepo (the CLI says so above),
             // so the single-repo remedy would hand the agent a command that does
-            // nothing. The resolution here is a merge, which a human does on the
-            // application page.
+            // nothing. The resolution is --map-deployable, which the agent runs.
             pendingSteps.push({
                 step: stepNum++,
                 action: "review_similar_applications",
@@ -2258,8 +2303,9 @@ export async function initProject(args) {
                     + ` workspace resemble${similarApplications.length === 1 ? "s" : ""} this repository: ${matchList}.`
                     + " One of the deployables just registered may be the same system — for example a web app registered"
                     + " earlier from its public website. Tell the human which deployable you think matches and why, before"
-                    + " enriching anything. The new deployables are PROPOSED, so nothing is broken yet; if one is a"
-                    + " duplicate, the human merges the two with \"Merge with…\" on the application's page.",
+                    + " enriching anything. If the human confirms one is the same system, re-run with"
+                    + " --map-deployable <deployable>=<entityRef> yourself and enrich the existing application: the scan"
+                    + " folds this proposal into it, so there is nothing for anyone to merge.",
                 notes: [
                     "Do not report the registration as complete without mentioning these.",
                     "The match is on the repository, not a specific deployable: say which one you believe it is, and why.",
@@ -2297,7 +2343,7 @@ export async function initProject(args) {
             pendingSteps.push({
                 step: stepNum++,
                 action: "enrich_entity",
-                instruction: `Enrich the application entity with a meaningful name, description, subtype, and icon.`,
+                instruction: `Enrich the application entity with a meaningful name, description, subtype, and icon. Find a real icon name with \`nexarch search-icons "<what the application is>"\`; a guessed name that doesn't exist is dropped without an error.`,
                 command: `nexarch update-entity --key "${projectExternalKey}" --entity-type "${entityTypeOverride}"${entityTypeOverride === "application" ? ' --subtype "<subtype>" --icon "<lucide-icon>"' : ""} --name "..." --description "..."`,
                 ...(entityTypeOverride === "application"
                     ? { notes: [APPLICATION_SUBTYPE_HINT, "Choose app_custom_built as the default if none of the others clearly apply."] }
@@ -2338,9 +2384,11 @@ export async function initProject(args) {
                 instruction: `Review the codebase to identify discrete application functions (what the application does). ` +
                     `Examine named modules, route layout, service boundaries, and any architecture documentation. ` +
                     `Register functions as application_function entities with subtype core_function (primary business function), supporting_function (auxiliary/enablement), integration_function (external connectivity), or data_function (data processing). ` +
-                    `Only register functions clearly evidenced by the codebase — do not invent them. ${DESCRIPTION_GUIDANCE}`,
+                    `Only register functions clearly evidenced by the codebase — do not invent them. ${DESCRIPTION_GUIDANCE} ` +
+                    `Give each function an icon for what it does: find a real name with \`nexarch search-icons "<what it does>"\` (or nexarch_search_icons) and pass it as --icon. Don't guess a name; one that doesn't exist is dropped without an error. If two searches find nothing fitting, leave the icon off.`,
                 commandTemplates: {
-                    updateEntity: `nexarch update-entity --key "application_function:${projectSlug}_<function_slug>" --entity-type application_function --subtype core_function --name "..." --description "..."`,
+                    searchIcons: `nexarch search-icons "<what the function does>"`,
+                    updateEntity: `nexarch update-entity --key "application_function:${projectSlug}_<function_slug>" --entity-type application_function --subtype core_function --icon "<name from search-icons>" --name "..." --description "..."`,
                     addRelationship: `nexarch add-relationship --from "application_function:${projectSlug}_<function_slug>" --to ${projectConstruct && isMonorepo ? '"<owning application key from classifyPackages>"' : `"${projectExternalKey}"`} --type part_of`,
                     note: "Functions are structural decomposition only: do not add runtime dependencies from an application_function. Model independently deployable services as applications or application components, then relate those boundaries with depends_on or integrates_with.",
                 },
@@ -2359,7 +2407,7 @@ export async function initProject(args) {
         pendingSteps.push({
             step: stepNum++,
             action: "register_decision_records",
-            instruction: `Look for ADRs (docs/adr/, decisions/, ADR-*.md) and register each as a decision_record entity.`,
+            instruction: `Look for ADRs (docs/adr/, decisions/, ADR-*.md) and register the architectural ones as decision_record entities: a decision that crosses a boundary between applications, services or teams; changes an integration, data ownership, security or deployment; adopts, replaces or retires a technology others depend on; or is expensive to reverse. Skip design decisions inside one application, even when they are written up as ADRs.`,
             commandTemplates: {
                 updateEntity: `nexarch update-entity --key "decision_record:${projectSlug}_<adr_slug>" --entity-type decision_record --subtype decision_architecture --name "..." --attributes-json '{"decision":{"summary":"...","detail":"..."}}'`,
                 addRelationship: `nexarch add-relationship --from "decision_record:${projectSlug}_<adr_slug>" --to ${projectConstruct && isMonorepo ? '"<the relevant application key>"' : `"${projectExternalKey}"`} --type decides`,
@@ -2473,7 +2521,7 @@ export async function initProject(args) {
             unresolvedNames: unresolvedItems.map((r) => r.input),
             iconHints: {
                 provider: "lucide",
-                note: "Use any Lucide icon name (kebab-case); omit when confidence is low.",
+                note: "Use a name returned by `nexarch search-icons` (or nexarch_search_icons); a guessed name that doesn't exist is dropped without an error. Omit when nothing fits.",
             },
         };
     }
@@ -2532,7 +2580,8 @@ export async function initProject(args) {
                     // "Confirm type, then update" is right for a new skeleton and wrong
                     // here: this is an application a human already registered and named.
                     lines.push(`    MAPPED   : this deployable is the existing application ${sp.externalKey}${sp.mappedBy === "alias" ? " (from an earlier merge)" : ""}.`);
-                    lines.push("               Add what the code shows; do not rename it or replace its description.");
+                    lines.push("               It is this deployable's application: enrich it — name, description, type and");
+                    lines.push("               functions — from the code, as you would a new one.");
                 }
                 lines.push(`    inferred : ${sp.entityType} / ${sp.subtype}  (confidence ${conf.toFixed(2)})`);
                 const unresolvedDeps = sp.depSpecs.map((d) => d.name).filter((d) => !resolvedByInput.has(d));
@@ -2596,15 +2645,19 @@ export async function initProject(args) {
             lines.push(`     Use subtype core_function (primary business function), supporting_function (auxiliary/enablement),`);
             lines.push(`     integration_function (external connectivity), or data_function (data processing).`);
             lines.push(`     Only register functions clearly evidenced by the codebase — do not invent them. ${DESCRIPTION_GUIDANCE}`);
+            lines.push(`     Give each function an icon for what it does. Find a real name first; a guessed one is dropped without an error:`);
+            lines.push(`       nexarch search-icons "<what the function does>"`);
             lines.push(`     For each one found:`);
             const fnOwnerTarget = projectConstruct && isMonorepo ? '"<owning application key from CLASSIFY_THESE>"' : `"${projectExternalKey}"`;
-            lines.push(`       nexarch update-entity --key "application_function:${projectExternalKey.split(":")[1] ?? "project"}_<function_slug>" --entity-type application_function --subtype core_function --name "..." --description "..."`);
+            lines.push(`       nexarch update-entity --key "application_function:${projectExternalKey.split(":")[1] ?? "project"}_<function_slug>" --entity-type application_function --subtype core_function --icon "<name from search-icons>" --name "..." --description "..."`);
             lines.push(`       nexarch add-relationship --from "application_function:${projectExternalKey.split(":")[1] ?? "project"}_<function_slug>" --to ${fnOwnerTarget} --type part_of`);
             lines.push("       Functions are structural only: model runtime/service dependencies between application or application_component boundaries, never from an application_function.");
         }
         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(`  ${step++}. Look for ADRs (docs/adr/, decisions/, ADR-*.md) and register the architectural ones as decision_record entities.`);
+        lines.push(`     Architectural means it crosses a boundary between applications, services or teams; changes an integration, data ownership, security or deployment;`);
+        lines.push(`     adopts or retires a technology others depend on; or is expensive to reverse. Skip design decisions inside one application.`);
         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 ${projectConstruct && isMonorepo ? '"<the relevant application key>"' : `"${projectExternalKey}"`} --type decides`);
         lines.push("");
@@ -2666,6 +2719,7 @@ export async function initProject(args) {
         resolved: resolvedItems.length,
         unresolved: unresolvedItems.length,
         similarApplications,
+        ...(foldedDuplicates.length > 0 ? { foldedDuplicates } : {}),
         entityErrors: entitiesResult.errors ?? [],
         relationshipErrors: relsResult?.errors ?? [],
         enrichmentRequired,

package/dist/commands/search-icons.js

@@ -0,0 +1,64 @@
+import process from "process";
+import { requireCredentials } from "../lib/credentials.js";
+import { callMcpTool } from "../lib/mcp.js";
+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;
+}
+/**
+ * The words to search for: everything that isn't an option or an option's
+ * value, so both `search-icons database` and `search-icons "event stream"` work.
+ */
+export function searchIconsQuery(args) {
+    const valued = new Set(["--limit"]);
+    const words = [];
+    for (let i = 0; i < args.length; i++) {
+        if (valued.has(args[i])) {
+            i++;
+            continue;
+        }
+        if (args[i].startsWith("--"))
+            continue;
+        words.push(args[i]);
+    }
+    return words.join(" ").trim();
+}
+/**
+ * Finds real icon names for `update-entity --icon`. The gateway silently drops
+ * an icon name that doesn't exist, so an agent guessing from memory ends up
+ * with no icon and no error; this searches the same validated set it checks.
+ */
+export async function searchIcons(args) {
+    const asJson = args.includes("--json");
+    const query = searchIconsQuery(args);
+    if (!query) {
+        console.error('error: say what the icon should show, e.g. nexarch search-icons "credit card"');
+        process.exit(1);
+    }
+    const limitRaw = parseOptionValue(args, "--limit");
+    const limit = limitRaw ? Number(limitRaw) : undefined;
+    if (limitRaw && (!Number.isInteger(limit) || limit < 1)) {
+        console.error("error: --limit must be a whole number of 1 or more");
+        process.exit(1);
+    }
+    const creds = requireCredentials();
+    const raw = await callMcpTool("nexarch_search_icons", { query, ...(limit ? { limit } : {}) }, { companyId: creds.companyId });
+    const result = JSON.parse(raw.content?.[0]?.text ?? "{}");
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    if (!result.matches?.length) {
+        console.log(`No icons match "${query}".`);
+        console.log("Icon names are literal objects and actions (database, file, box). Try one more concrete word; if that also finds nothing, leave the icon unset.");
+        return;
+    }
+    for (const name of result.matches)
+        console.log(name);
+    console.log(`\n${result.matches.length} of ${result.totalMatches} match${result.totalMatches === 1 ? "" : "es"}. Use one with: nexarch update-entity --key "<key>" --icon "${result.matches[0]}"`);
+}

package/dist/index.js

@@ -13,6 +13,7 @@ import { updateEntity } from "./commands/update-entity.js";
 import { addRelationship } from "./commands/add-relationship.js";
 import { registerAlias } from "./commands/register-alias.js";
 import { resolveNames } from "./commands/resolve-names.js";
+import { searchIcons } from "./commands/search-icons.js";
 import { feedback } from "./commands/feedback.js";
 import { listEntities } from "./commands/list-entities.js";
 import { listRelationships } from "./commands/list-relationships.js";
@@ -57,6 +58,7 @@ const commands = {
     "add-relationship": addRelationship,
     "register-alias": registerAlias,
     "resolve-names": resolveNames,
+    "search-icons": searchIcons,
     feedback,
     "list-entities": listEntities,
     "list-relationships": listRelationships,
@@ -232,6 +234,12 @@ Usage:
                       results before calling add-relationship.
                       Options: --names <csv>  (required, e.g. "vercel,neon")
                                --json
+  nexarch search-icons <words>
+                      Find real icon names for update-entity --icon. An icon
+                      name that doesn't exist is dropped without an error, so
+                      look one up rather than guessing.
+                      Options: --limit <n>  (default 20, max 50)
+                               --json
   nexarch feedback
                       Report a Nexarch usability problem or tool error.
                       Options: --kind <usability|error>  (required)

package/dist/lib/skills.js

@@ -240,7 +240,7 @@ evidence — never invent a compliance status that isn't stored.
 `;
 const DECISION_RECORDS_SKILL_BODY = `---
 name: nexarch-decision-records
-description: Record an architectural decision in Nexarch, or check what's already been decided about something. Use when a decision is being made (a technology, pattern, or approach chosen over alternatives), when ADR/RFC documents are found in a repository, when asked what's already been decided about a topic, or when a new decision replaces an older one. Requires the Nexarch MCP tools (nexarch_*).
+description: Record an architectural decision in Nexarch, or check what's already been decided about something. Use when a decision crosses a boundary between applications, services or teams, changes an integration, data ownership, security or deployment, adopts a technology others depend on, or is expensive to reverse; when ADR/RFC documents are found in a repository; when asked what's already been decided about a topic; or when a new decision replaces an older one. Not for design decisions inside one application. Requires the Nexarch MCP tools (nexarch_*).
 ---
 
 # Nexarch Decision Records
@@ -252,6 +252,23 @@ skill is for recording one as it happens — mining a whole repository's ADR
 history systematically is a separate, human-triggered Decision Review
 command from the application's page in the workspace.
 
+## Architectural, not design
+
+Record only architectural decisions. A decision is architectural when it does
+at least one of these:
+
+- crosses a boundary between applications, services or teams
+- changes an integration, data ownership, security or authentication, or how
+  the system is deployed
+- adopts, replaces or retires a technology that other systems or teams depend on
+- is expensive to reverse once other work builds on it
+
+Anything else is a design decision — screen layouts, interaction patterns,
+component library choices, internal module structure, naming. It belongs in
+the repository's design documentation, not in the graph. When unsure, ask:
+if this decision changed, would another team or system have to change too? If
+not, do not record it, even when it is written up as an ADR.
+
 ## Before recording
 
 \`nexarch_resolve_reference\` / \`nexarch_list_entities\` for an existing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.13.2",
+  "version": "0.13.4",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",
@@ -26,7 +26,7 @@
     "prepublishOnly": "tsc",
     "dev": "tsx src/index.ts",
     "typecheck": "tsc --noEmit",
-    "test": "tsx scripts/test-mcp-proxy-response.ts && tsx scripts/test-trust-reattest.ts && tsx scripts/test-similar-applications.ts && tsx scripts/test-iac-tool.ts && tsx scripts/test-ansible.ts && tsx scripts/test-reference-sightings.ts"
+    "test": "tsx scripts/test-mcp-proxy-response.ts && tsx scripts/test-trust-reattest.ts && tsx scripts/test-similar-applications.ts && tsx scripts/test-iac-tool.ts && tsx scripts/test-ansible.ts && tsx scripts/test-reference-sightings.ts && tsx scripts/test-search-icons.ts"
   },
   "devDependencies": {
     "@types/node": "^22",