nexarch 0.12.39 → 0.12.44

package/dist/commands/add-relationship.js

@@ -50,11 +50,19 @@ function parseRelationships(args) {
             if (!from || !to || !type) {
                 throw new Error(`Relationship #${index + 1} is missing required fields (from/to/type)`);
             }
+            const subtype = typeof v.relationshipSubtypeCode === "string" ? v.relationshipSubtypeCode
+                : typeof v.subtype === "string" ? v.subtype
+                    : undefined;
+            const attributes = v.attributes && typeof v.attributes === "object" && !Array.isArray(v.attributes)
+                ? v.attributes
+                : undefined;
             return {
                 fromEntityExternalKey: from,
                 toEntityExternalKey: to,
                 relationshipTypeCode: type,
                 confidence: Number.isFinite(confidence) ? confidence : 1,
+                ...(subtype ? { relationshipSubtypeCode: subtype } : {}),
+                ...(attributes ? { attributes } : {}),
             };
         });
     }
@@ -113,8 +121,14 @@ export async function addRelationship(args) {
         model: "n/a",
         provider: "n/a",
     };
+    // score is an unverified agent assertion of policy conformance, not a fact
+    // the CLI can establish itself -- it never reads the applied policy
+    // documents or evaluates the write against them, so asserting 1 ("fully
+    // conformant") here was a fabricated default the caller had no way to
+    // override. null ("not evaluated") is the honest value, matching the
+    // guidance direct-MCP playbooks already give agents for the same field.
     const policyContext = policyBundleHash
-        ? { policyBundleHash, alignmentSummary: { score: 1, violations: [], waivers: [] } }
+        ? { policyBundleHash, alignmentSummary: { score: null, violations: [], waivers: [] } }
         : undefined;
     let raw = await callMcpTool("nexarch_upsert_relationships", { relationships, agentContext, policyContext }, mcpOpts);
     let result = parseToolText(raw);

package/dist/commands/init-agent.js

@@ -266,43 +266,43 @@ function writeAgentBootstrap(params) {
         `--capabilities "<comma,separated,capabilities>"`,
         `--json`,
     ].join(" \\\n  ");
-    const content = `# Nexarch Agent Bootstrap
-
-This file was written by \`nexarch init-agent\` on ${new Date().toISOString()}.
-It contains instructions for an AI agent to complete its Nexarch registration.
-
-## What has already been registered
-
-The following entities are now in the architecture graph:
-
-| Entity | Name | Type |
-|--------|------|------|
-| Agent | \`${params.agentId}\` | agent |
-| Host | \`Host ${params.hostname}\` | tech_compute |
-| OS | \`${params.osPlatform} ${params.osRelease}\` | tech_operating_system |
-| Runtime | \`Node.js ${params.nodeVersion}\` | tech_runtime |
-
-## Your task
-
-Run the command below, substituting your own values for the placeholders.
-Return ONLY the completed command (no markdown, no explanation) — it will be executed directly.
-
-\`\`\`
-${identifyCmd}
-\`\`\`
-
-Fill in:
-- **provider** — your AI provider (e.g. \`anthropic\`, \`openai\`, \`google\`)
-- **model** — the exact model ID you are running as (e.g. \`gpt-4o\`, \`claude-sonnet-4-6\`, \`gemini-2-flash\`)
-- **client** — the MCP client tool you are running inside (e.g. \`claude-code\`, \`cursor\`, \`continue\`, \`codex-cli\`)
-- **framework** — the agent framework in use (e.g. \`openclaw\`)
-- **session-id** — your current session ID if available
-- **tool-version** — the version of the client tool (run the tool's version command and use the version number only, e.g. \`1.2.3\`)
-- **capabilities** — comma-separated list of your capabilities (e.g. \`code,files,bash,web\`)
-
-Omit any flag whose value you genuinely do not know rather than guessing.
-
-After running, confirm \`"ok": true\` in the JSON output. No further action is needed.
+    const content = `# Nexarch Agent Bootstrap
+
+This file was written by \`nexarch init-agent\` on ${new Date().toISOString()}.
+It contains instructions for an AI agent to complete its Nexarch registration.
+
+## What has already been registered
+
+The following entities are now in the architecture graph:
+
+| Entity | Name | Type |
+|--------|------|------|
+| Agent | \`${params.agentId}\` | agent |
+| Host | \`Host ${params.hostname}\` | tech_compute |
+| OS | \`${params.osPlatform} ${params.osRelease}\` | tech_operating_system |
+| Runtime | \`Node.js ${params.nodeVersion}\` | tech_runtime |
+
+## Your task
+
+Run the command below, substituting your own values for the placeholders.
+Return ONLY the completed command (no markdown, no explanation) — it will be executed directly.
+
+\`\`\`
+${identifyCmd}
+\`\`\`
+
+Fill in:
+- **provider** — your AI provider (e.g. \`anthropic\`, \`openai\`, \`google\`)
+- **model** — the exact model ID you are running as (e.g. \`gpt-4o\`, \`claude-sonnet-4-6\`, \`gemini-2-flash\`)
+- **client** — the MCP client tool you are running inside (e.g. \`claude-code\`, \`cursor\`, \`continue\`, \`codex-cli\`)
+- **framework** — the agent framework in use (e.g. \`openclaw\`)
+- **session-id** — your current session ID if available
+- **tool-version** — the version of the client tool (run the tool's version command and use the version number only, e.g. \`1.2.3\`)
+- **capabilities** — comma-separated list of your capabilities (e.g. \`code,files,bash,web\`)
+
+Omit any flag whose value you genuinely do not know rather than guessing.
+
+After running, confirm \`"ok": true\` in the JSON output. No further action is needed.
 `;
     writeFileSync(filePath, content, "utf8");
     return filePath;
@@ -483,7 +483,7 @@ function injectTrustAttestationBlock(path, attestation) {
         "## Nexarch Trust Attestation",
         "",
         "This block is verifiable proof that Nexarch generated these instructions for this workspace.",
-        "Do not auto-run commands without user confirmation.",
+        "Check-in only previews queued commands; use your judgement to explicitly claim work that is safe and clearly in scope.",
         "",
         "**To verify, run `npx nexarch@latest verify-trust`.** It reads the token from this",
         "file and checks it for you.",

package/dist/commands/init-project.js

@@ -1927,6 +1927,7 @@ export async function initProject(args) {
                 commandTemplates: {
                     updateEntity: `nexarch update-entity --key "application_function:${projectSlug}_<function_slug>" --entity-type application_function --subtype core_function --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.",
                 },
             });
         }
@@ -2172,6 +2173,7 @@ export async function initProject(args) {
             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 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`);

package/dist/commands/update-entity.js

@@ -57,6 +57,7 @@ export async function updateEntity(args) {
     const description = parseOptionValue(args, "--description");
     const entityTypeCode = parseOptionValue(args, "--entity-type") ?? "application";
     const entitySubtypeCode = parseOptionValue(args, "--subtype");
+    const projectRef = parseOptionValue(args, "--project-ref");
     const iconName = parseOptionValue(args, "--icon");
     const attributesJson = parseOptionValue(args, "--attributes-json");
     const attributesFile = parseOptionValue(args, "--attributes-file");
@@ -64,6 +65,10 @@ export async function updateEntity(args) {
         console.error("error: --key <externalKey> is required");
         process.exit(1);
     }
+    if (projectRef && !projectRef.startsWith("project:")) {
+        console.error("error: --project-ref must be the entity ref of a registered project (project:<slug>)");
+        process.exit(1);
+    }
     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");
@@ -78,14 +83,25 @@ export async function updateEntity(args) {
     const agentContext = {
         agentId: "nexarch-cli:update-entity",
         agentRunId: `update-entity-${Date.now()}`,
-        repoRef: externalKey,
+        // A generic update targets an entity, but an application may have been
+        // discovered in a registered project. Supplying that project context lets
+        // the gateway maintain the application --sourced_from--> project edge.
+        // Preserve the historic target-ref fallback for updates with no project
+        // context and for entity types where a source project is not meaningful.
+        repoRef: projectRef ?? externalKey,
         observedAt: nowIso,
         source: "nexarch-cli",
         model: "n/a",
         provider: "n/a",
     };
+    // score is an unverified agent assertion of policy conformance, not a fact
+    // the CLI can establish itself -- it never reads the applied policy
+    // documents or evaluates the write against them, so asserting 1 ("fully
+    // conformant") here was a fabricated default the caller had no way to
+    // override. null ("not evaluated") is the honest value, matching the
+    // guidance direct-MCP playbooks already give agents for the same field.
     const policyContext = policyBundleHash
-        ? { policyBundleHash, alignmentSummary: { score: 1, violations: [], waivers: [] } }
+        ? { policyBundleHash, alignmentSummary: { score: null, violations: [], waivers: [] } }
         : undefined;
     const entity = {
         externalKey,

package/dist/index.js

@@ -90,7 +90,7 @@ async function main() {
     if (command === "--version" || command === "-v" || command === "version") {
         const build = cliBuild();
         if (args.includes("--json"))
-            process.stdout.write(`${JSON.stringify(build, null, 2)}
+            process.stdout.write(`${JSON.stringify(build, null, 2)}
 `);
         else
             console.log(formatBuild(build));
@@ -98,226 +98,227 @@ async function main() {
     }
     const handler = commands[command ?? ""];
     if (!handler) {
-        console.log(`
-nexarch — Your architecture workspace for AI delivery.
-
-Usage:
-  nexarch login         Authenticate in browser and store company-scoped credentials
-                        Option: --company <id>
-  nexarch --version     Print the version and the path this copy runs from
-  nexarch enroll        Bootstrap a headless (browserless) agent with a one-time
-                        enrollment code — no login required. Writes the resulting
-                        credential to ~/.nexarch/agent-credential.json (mode 600)
-                        rather than printing it. For a client with a known config
-                        format (e.g. hermes-agent), also writes the connection
-                        directly into that client's own env/config files; for
-                        anything else, prints instructions instead.
-                        Options: --code <code>          (required, starts with nxe_)
-                                 --client <code>         (required, e.g. hermes-agent)
-                                 --client-version <v>
-                                 --host <baseUrl>        (default: https://www.nexarch.ai)
-                                 --out <path>            write credential here instead
-                                 --skip-client-config    don't touch the client's own files
-                                 --print-token           also print the token to stdout
-                                 --json
-  nexarch logout        Remove stored credentials
-  nexarch status        Check connection and show architecture summary
-  nexarch verify-trust  Verify this repo's Nexarch trust attestation. Reads the token
-                        from the instruction file, so nothing has to be copied.
-                        Options: --dir <path>  (default: cwd)
-                                 --json
-  nexarch setup         One-step onboarding: login (if needed) + MCP config + register agent
-                        Names the workspace it will write to and confirms it before
-                        registering anything; answer 'n' to pick a different one.
-                        Options: --company <id|code>  target a workspace directly
-                                 --yes  accept the stored workspace without asking
-  nexarch mcp-config    Print MCP server config block for manual setup
-                        Client list is registry-managed (see 'nexarch mcp-config --client <code>')
-  nexarch mcp-proxy     Run as stdio MCP proxy (used by MCP clients)
-  nexarch init-agent    Run handshake + mandatory agent registration in graph (advanced/manual)
-                        Options: --agent-id <id> --bind-to-external-key <key>
-                                 --bind-relationship-type <code> --redact-hostname
-                                 --json --strict
-  nexarch agent identify
-                      Capture richer coding-agent identity metadata
-                      Options: --agent-id <id> --provider <provider> --model <model>
-                               --client <name> [--framework <name>] [--session-id <id>]
-                               [--tool-version <v>] [--capabilities <csv>]
-                               [--notes <text>] [--json]
-  nexarch agent-identify
-                      Alias of 'nexarch agent identify'
-  nexarch init-project
-                      Scan a project directory, resolve detected packages/env vars/
-                      config files against the reference library, write entities and
-                      relationships to the architecture graph, and log unresolved
-                      names as reference candidates.
-                      Monorepos register a project entity plus one proposed
-                      application per deployable package (sourced_from the project).
-                      Single-package repos register the repo's one application; when
-                      similar applications exist they are listed, and the new
-                      application is created as proposed for review at activation.
-                      Terraform repositories take a different path: no dependency
-                      scan and no applications. They register a project plus the
-                      environments their root modules define, and hand over the
-                      per-root ingest-infra commands that read the actual estate.
-                      Options: --dir <path>  (default: cwd)
-                               --name <name>  override project name
-                               --entity-type <code>  (default: application)
-                               --application-ref <entityRef>  force mapping target
-                               --create-application  force new application entity
-                               --auto-map-application  auto-map only when high confidence
-                               --non-interactive  deprecated (mapping no longer prompts)
-                               --batch-size <n>  upsert batch size (default: 10)
-                               --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
-                      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
-  nexarch add-relationship
-                      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.
-                      Use after enriching internal monorepo packages.
-                      Options: --alias <value>       (required, e.g. @scope/name)
-                               --key <externalKey>   (required)
-                               --name <name>         (required)
-                               --entity-type <code>  (required)
-                               --subtype <code>
-                               --description <text>
-                               --json
-  nexarch resolve-names
-                      Look up one or more raw names (package names, platform
-                      names) against the global reference library and return
-                      their canonical external keys. Useful for gap-check
-                      results before calling add-relationship.
-                      Options: --names <csv>  (required, e.g. "vercel,neon")
-                               --json
-  nexarch list-entities
-                      List entities from the workspace graph.
-                      Options: --type <entityTypeCode>
-                               --status <status>
-                               --query <text>
-                               --limit <1-500>
-                               --json
-  nexarch list-relationships
-                      List relationships from the workspace graph.
-                      Options: --type <relationshipTypeCode>
-                               --status <status>
-                               --from <fromExternalKey>
-                               --to <toExternalKey>
-                               --limit <1-500>
-                               --json
-  nexarch register-runtime
-                      Register or refresh runtime + optional application context
-                      without performing check-in.
-                      Options: --application-ref <entityRef>
-                               --client <name>
-                               --version <semver>
-                               --json
-  nexarch check-in    Preview pending application-target commands (no auto-claim)
-                      and report draft/proposed applications needing review so the
-                      agent can prompt the user to explore and instantiate them.
-                      Use command-claim to explicitly claim a specific command.
-                      Scope is resolved server-side from active company context.
-                      Options: --agent-key <key>   override stored agent key
-                               --application-ref <entityRef>  narrow preview scope
-                               --json              JSON output includes draftApplications[] and proposedApplications[]
-  nexarch proposals start
-                      Start a new application workspace from a proposed NexArch app.
-                      Lists proposed apps, shows policy review gates, writes a starter
-                      project scaffold, and activates the proposal to active once
-                      required policy controls are acknowledged.
-                      Options: --id <applicationId>
-                               --dir <path>
-                               --reason <text>
-                               --repo <url>
-                               --skip-activate
-                               --activate
-                               --force
-                               --non-interactive
-                               --json
-  nexarch command-claim
-                      Explicitly claim a pending command by ID.
-                      Options: --id <commandId>    (required)
-                               --agent-key <key>   override stored agent key
-                               --application-ref <entityRef>  required for application-target commands
-                               --json
-  nexarch command-done
-                      Mark a claimed command as completed.
-                      Options: --id <commandId>    (required)
-                               --summary <text>    short summary of what was done
-                               --summary-file <path.md|txt>
-                               --json
-  nexarch command-fail
-                      Mark a claimed command as failed.
-                      Options: --id <commandId>    (required)
-                               --error <message>   (required)
-                               --json
-  nexarch policy-controls
-                      Fetch policy controls/rules assigned to an entity (for policy audits).
-                      Options: --entity <externalKey>  (required, e.g. application:bad-driving)
-                               --json
-  nexarch policy-audit-template
-                      Generate a findings JSON template from policy controls/rules for an entity.
-                      Options: --entity <externalKey>   (required)
-                               --control-id <uuid>      (repeatable; optional filter)
-                               --default-result <pass|partial|fail> (default: fail)
-                               --output <path.json>
-                               --json
-  nexarch policy-audit-submit
-                      Submit structured policy findings (writes policy_audit_finding rows).
-                      Options: --command-id <id>        (required)
-                               --application-key <key>  (required)
-                               --agent-key <key>        (optional; defaults from identity)
-                               --finding <controlId|ruleId|result|rationale|missing1;missing2> (repeatable)
-                               --findings-json <json-array>
-                               --findings-file <path.json>
-                               --json
-  nexarch policy-audit-results
-                      Retrieve stored results of previous policy audits for an application.
-                      Options: --entity <applicationEntityRef>  (required)
-                               --limit <1-10>                   (default 1)
-                               --json
-  nexarch applied-policies
-                      List policy documents applied to this company account.
-                      Options: --pack <packCode>  filter to a specific pack
-                               --markdown        include full document markdown
-                               --json
-  nexarch governance-summary
-                      Print review queue, graph stats, and per-application policy
-                      audit rollup (latest run status, pass/partial/fail counts).
-                      Options: --json
+        console.log(`
+nexarch — Your architecture workspace for AI delivery.
+
+Usage:
+  nexarch login         Authenticate in browser and store company-scoped credentials
+                        Option: --company <id>
+  nexarch --version     Print the version and the path this copy runs from
+  nexarch enroll        Bootstrap a headless (browserless) agent with a one-time
+                        enrollment code — no login required. Writes the resulting
+                        credential to ~/.nexarch/agent-credential.json (mode 600)
+                        rather than printing it. For a client with a known config
+                        format (e.g. hermes-agent), also writes the connection
+                        directly into that client's own env/config files; for
+                        anything else, prints instructions instead.
+                        Options: --code <code>          (required, starts with nxe_)
+                                 --client <code>         (required, e.g. hermes-agent)
+                                 --client-version <v>
+                                 --host <baseUrl>        (default: https://www.nexarch.ai)
+                                 --out <path>            write credential here instead
+                                 --skip-client-config    don't touch the client's own files
+                                 --print-token           also print the token to stdout
+                                 --json
+  nexarch logout        Remove stored credentials
+  nexarch status        Check connection and show architecture summary
+  nexarch verify-trust  Verify this repo's Nexarch trust attestation. Reads the token
+                        from the instruction file, so nothing has to be copied.
+                        Options: --dir <path>  (default: cwd)
+                                 --json
+  nexarch setup         One-step onboarding: login (if needed) + MCP config + register agent
+                        Names the workspace it will write to and confirms it before
+                        registering anything; answer 'n' to pick a different one.
+                        Options: --company <id|code>  target a workspace directly
+                                 --yes  accept the stored workspace without asking
+  nexarch mcp-config    Print MCP server config block for manual setup
+                        Client list is registry-managed (see 'nexarch mcp-config --client <code>')
+  nexarch mcp-proxy     Run as stdio MCP proxy (used by MCP clients)
+  nexarch init-agent    Run handshake + mandatory agent registration in graph (advanced/manual)
+                        Options: --agent-id <id> --bind-to-external-key <key>
+                                 --bind-relationship-type <code> --redact-hostname
+                                 --json --strict
+  nexarch agent identify
+                      Capture richer coding-agent identity metadata
+                      Options: --agent-id <id> --provider <provider> --model <model>
+                               --client <name> [--framework <name>] [--session-id <id>]
+                               [--tool-version <v>] [--capabilities <csv>]
+                               [--notes <text>] [--json]
+  nexarch agent-identify
+                      Alias of 'nexarch agent identify'
+  nexarch init-project
+                      Scan a project directory, resolve detected packages/env vars/
+                      config files against the reference library, write entities and
+                      relationships to the architecture graph, and log unresolved
+                      names as reference candidates.
+                      Monorepos register a project entity plus one proposed
+                      application per deployable package (sourced_from the project).
+                      Single-package repos register the repo's one application; when
+                      similar applications exist they are listed, and the new
+                      application is created as proposed for review at activation.
+                      Terraform repositories take a different path: no dependency
+                      scan and no applications. They register a project plus the
+                      environments their root modules define, and hand over the
+                      per-root ingest-infra commands that read the actual estate.
+                      Options: --dir <path>  (default: cwd)
+                               --name <name>  override project name
+                               --entity-type <code>  (default: application)
+                               --application-ref <entityRef>  force mapping target
+                               --create-application  force new application entity
+                               --auto-map-application  auto-map only when high confidence
+                               --non-interactive  deprecated (mapping no longer prompts)
+                               --batch-size <n>  upsert batch size (default: 10)
+                               --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
+                      content from the project README or docs.
+                      Options: --key <externalKey>  (required)
+                               --name <name>
+                               --description <text>
+                               --entity-type <code>  (default: application)
+                               --subtype <code>
+                               --project-ref <project:ref>  link an application to its registered source project
+                               --icon <lucide-name>  (convenience; sets attributes.application_icon)
+                               --attributes-json '<json object>'
+                               --attributes-file <path.json>
+                               --json
+  nexarch add-relationship
+                      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.
+                      Use after enriching internal monorepo packages.
+                      Options: --alias <value>       (required, e.g. @scope/name)
+                               --key <externalKey>   (required)
+                               --name <name>         (required)
+                               --entity-type <code>  (required)
+                               --subtype <code>
+                               --description <text>
+                               --json
+  nexarch resolve-names
+                      Look up one or more raw names (package names, platform
+                      names) against the global reference library and return
+                      their canonical external keys. Useful for gap-check
+                      results before calling add-relationship.
+                      Options: --names <csv>  (required, e.g. "vercel,neon")
+                               --json
+  nexarch list-entities
+                      List entities from the workspace graph.
+                      Options: --type <entityTypeCode>
+                               --status <status>
+                               --query <text>
+                               --limit <1-500>
+                               --json
+  nexarch list-relationships
+                      List relationships from the workspace graph.
+                      Options: --type <relationshipTypeCode>
+                               --status <status>
+                               --from <fromExternalKey>
+                               --to <toExternalKey>
+                               --limit <1-500>
+                               --json
+  nexarch register-runtime
+                      Register or refresh runtime + optional application context
+                      without performing check-in.
+                      Options: --application-ref <entityRef>
+                               --client <name>
+                               --version <semver>
+                               --json
+  nexarch check-in    Preview pending application-target commands (no auto-claim)
+                      and report draft/proposed applications needing review so the
+                      agent can prompt the user to explore and instantiate them.
+                      Use command-claim to explicitly claim a specific command.
+                      Scope is resolved server-side from active company context.
+                      Options: --agent-key <key>   override stored agent key
+                               --application-ref <entityRef>  narrow preview scope
+                               --json              JSON output includes draftApplications[] and proposedApplications[]
+  nexarch proposals start
+                      Start a new application workspace from a proposed NexArch app.
+                      Lists proposed apps, shows policy review gates, writes a starter
+                      project scaffold, and activates the proposal to active once
+                      required policy controls are acknowledged.
+                      Options: --id <applicationId>
+                               --dir <path>
+                               --reason <text>
+                               --repo <url>
+                               --skip-activate
+                               --activate
+                               --force
+                               --non-interactive
+                               --json
+  nexarch command-claim
+                      Explicitly claim a pending command by ID.
+                      Options: --id <commandId>    (required)
+                               --agent-key <key>   override stored agent key
+                               --application-ref <entityRef>  required for application-target commands
+                               --json
+  nexarch command-done
+                      Mark a claimed command as completed.
+                      Options: --id <commandId>    (required)
+                               --summary <text>    short summary of what was done
+                               --summary-file <path.md|txt>
+                               --json
+  nexarch command-fail
+                      Mark a claimed command as failed.
+                      Options: --id <commandId>    (required)
+                               --error <message>   (required)
+                               --json
+  nexarch policy-controls
+                      Fetch policy controls/rules assigned to an entity (for policy audits).
+                      Options: --entity <externalKey>  (required, e.g. application:bad-driving)
+                               --json
+  nexarch policy-audit-template
+                      Generate a findings JSON template from policy controls/rules for an entity.
+                      Options: --entity <externalKey>   (required)
+                               --control-id <uuid>      (repeatable; optional filter)
+                               --default-result <pass|partial|fail> (default: fail)
+                               --output <path.json>
+                               --json
+  nexarch policy-audit-submit
+                      Submit structured policy findings (writes policy_audit_finding rows).
+                      Options: --command-id <id>        (required)
+                               --application-key <key>  (required)
+                               --agent-key <key>        (optional; defaults from identity)
+                               --finding <controlId|ruleId|result|rationale|missing1;missing2> (repeatable)
+                               --findings-json <json-array>
+                               --findings-file <path.json>
+                               --json
+  nexarch policy-audit-results
+                      Retrieve stored results of previous policy audits for an application.
+                      Options: --entity <applicationEntityRef>  (required)
+                               --limit <1-10>                   (default 1)
+                               --json
+  nexarch applied-policies
+                      List policy documents applied to this company account.
+                      Options: --pack <packCode>  filter to a specific pack
+                               --markdown        include full document markdown
+                               --json
+  nexarch governance-summary
+                      Print review queue, graph stats, and per-application policy
+                      audit rollup (latest run status, pass/partial/fail counts).
+                      Options: --json
     `);
         if (updateCheck)
             await printUpdateNoticeIfReady(updateCheck);

package/dist/lib/skills.js

@@ -30,8 +30,18 @@ repository; the graph knows all of them.
 
 - \`nexarch_upsert_entities\` for what you created; \`nexarch_upsert_relationships\`
   to wire dependencies (\`part_of\`, \`depends_on\`, \`runs_on\`).
+- An \`application_function\` describes what its owning application does: link it
+  **only** with \`application_function -> part_of -> application\`. Do not model
+  service or runtime dependencies from a function. Use an \`application\` or
+  \`application_component\` boundary, then link that boundary with
+  \`depends_on\` or \`integrates_with\` as the evidence supports.
 - New applications arrive as **proposed** and wait for a human to activate them
   in the workspace — say so in your summary rather than calling them registered.
+- Every new \`application\` needs an icon in the same upsert. Call
+  \`nexarch_search_icons\` with a concrete description, then set
+  \`attributes.application_icon\` to \`{ provider: "lucide", name: "<returned-name>" }\`.
+  If no specific icon fits, use \`app-window\`; do not leave an application
+  without an icon.
 - Unsure whether something belongs in the graph? \`nexarch_emit_observations\`
   is non-blocking and carries no schema commitment.
 
@@ -141,10 +151,13 @@ you're about to do the three steps below in the same turn — a claimed
 command that's never executed or closed out sits there looking done while
 blocking that queue slot, which is worse than never having claimed it.
 
-1. Only claim a specific command with \`nexarch_claim_command_by_id\` when the
-   human explicitly wants it worked — check-in surfacing a command is not
-   itself permission to claim it, and neither is check-in itself: claiming
-   is a separate, deliberate call you make because you're about to act.
+1. Assess each command using your judgement: scope, evidence, permissions,
+   reversibility, and risk. Check-in is only a preview and must never claim
+   work automatically. Explicitly claim a specific command with
+   \`nexarch_claim_command_by_id\` when it is safe, clearly in scope, and you
+   can execute and close it in this session. Ask the human when the requested
+   work is ambiguous, consequential, destructive, external, or beyond your
+   authority.
 2. **Execute \`command.resolved_playbook_text\` from the claim response** —
    that field is the actual task. \`command.instructions\` is a different
    field and is almost always \`null\`; don't mistake its emptiness for "no

package/package.json

@@ -1,39 +1,39 @@
-{
-  "name": "nexarch",
-  "version": "0.12.39",
-  "description": "Your architecture workspace for AI delivery.",
-  "keywords": [
-    "nexarch",
-    "mcp",
-    "architecture",
-    "ai"
-  ],
-  "license": "MIT",
-  "author": "Nexarch <hello@nexarch.ai>",
-  "homepage": "https://nexarch.ai",
-  "engines": {
-    "node": ">=18"
-  },
-  "type": "module",
-  "bin": {
-    "nexarch": "dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "tsc",
-    "dev": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "tsx scripts/test-mcp-proxy-response.ts"
-  },
-  "devDependencies": {
-    "@types/node": "^22",
-    "tsx": "^4",
-    "typescript": "^5"
-  },
-  "dependencies": {
-    "yaml": "^2.9.0"
-  }
-}
+{
+  "name": "nexarch",
+  "version": "0.12.44",
+  "description": "Your architecture workspace for AI delivery.",
+  "keywords": [
+    "nexarch",
+    "mcp",
+    "architecture",
+    "ai"
+  ],
+  "license": "MIT",
+  "author": "Nexarch <hello@nexarch.ai>",
+  "homepage": "https://nexarch.ai",
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "bin": {
+    "nexarch": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx scripts/test-mcp-proxy-response.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsx": "^4",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  }
+}