nexarch 0.13.3 → 0.13.4

package/dist/commands/init-project.js

@@ -2343,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."] }
@@ -2384,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.",
                 },
@@ -2405,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`,
@@ -2519,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.",
             },
         };
     }
@@ -2643,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("");

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.3",
+  "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",