nexarch 0.14.0 → 0.15.0

package/README.md

@@ -1,63 +1,69 @@
-# nexarch
-
-Your architecture workspace for AI delivery.
-
-## Quick start
-
-```sh
-npx nexarch login
-npx nexarch setup
-```
-
-> `setup`, `mcp-config`, and `init-agent` are registry-driven and fail closed.
-> If the published integration registry is unavailable/invalid, these commands stop until service is restored.
-
-## Commands
-
-| Command | Description |
-|---|---|
-| `nexarch login [--company <id>]` | Authenticate via browser and store company-scoped credentials; prompts for company when multiple memberships exist |
-| `nexarch logout` | Remove local credentials |
-| `nexarch status` | Check connection, registry health/version, and architecture summary for the company selected at login |
-| `nexarch setup` | Auto-configure detected MCP clients |
-| `nexarch mcp-config [client]` | Print config block for manual setup (supported client codes are registry-managed) |
-| `nexarch mcp-proxy` | stdio→HTTP bridge used internally by MCP clients |
-| `nexarch init-agent [--json] [--strict] [--agent-id <id>] [--redact-hostname]` | Run onboarding handshake and mandatory `agent` entity registration in graph |
-| `nexarch init-agent --bind-to-external-key <key> [--bind-relationship-type <code>]` | Optionally bind the agent node to an existing graph external key |
-| `nexarch init-agent` (default behavior) | Also upserts technology component entities (host, OS, Node.js runtime) and links them to the agent |
-| `nexarch agent identify ...` | Submit provider/model/client identity metadata to complete agent profile enrichment |
-
-## Bootstrap flow after `init-agent`
-
-`nexarch init-agent` writes a bootstrap file at:
-
-```sh
-~/.nexarch/agent-bootstrap.md
-```
-
-That file contains a pre-filled `npx nexarch agent identify ...` command template.
-The current workflow is:
-
-1. run `npx nexarch init-agent`
-2. open `~/.nexarch/agent-bootstrap.md`
-3. copy the generated `npx nexarch agent identify ...` template
-4. fill in the real provider/model/client details
-5. run the completed command
-
-Do not assume an `npx nexarch agent prompt` command exists unless/until it is explicitly implemented and documented.
-
-## Company context behavior
-
-- Company is selected during `nexarch login`.
-- If your user has one active company, login auto-selects it.
-- If your user has multiple active companies, login requires explicit selection.
-- To switch company later, run `nexarch login` again and pick another company.
-
-## Requirements
-
-- Node.js 18 or later
-- A Nexarch workspace account
-
-## Documentation
-
-[nexarch.ai/docs/cli-reference](https://nexarch.ai/docs/cli-reference)
+# nexarch
+
+Your architecture workspace for AI delivery.
+
+## Quick start
+
+```sh
+npx nexarch login
+npx nexarch setup
+```
+
+For browserless agent enrollment, use `npx nexarch enroll --code <code> --client <client>`.
+Known clients receive their MCP connection configuration and Nexarch skills as part
+of the same enrollment.
+
+> `setup`, `mcp-config`, and `init-agent` are registry-driven and fail closed.
+> If the published integration registry is unavailable/invalid, these commands stop until service is restored.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `nexarch login [--company <id>]` | Authenticate via browser and store company-scoped credentials; prompts for company when multiple memberships exist |
+| `nexarch logout` | Remove local credentials |
+| `nexarch status` | Check connection, registry health/version, and architecture summary for the company selected at login |
+| `nexarch setup` | Auto-configure detected MCP clients, write instructions, and refresh all managed skills |
+| `nexarch skills update` | Refresh all Nexarch-managed skills for installed agent runtimes |
+| `nexarch enroll --code <code> --client <client>` | Redeem a one-time enrollment, configure the known client, and install its Nexarch skills |
+| `nexarch mcp-config [client]` | Print config block for manual setup (supported client codes are registry-managed) |
+| `nexarch mcp-proxy` | stdio→HTTP bridge used internally by MCP clients |
+| `nexarch init-agent [--json] [--strict] [--agent-id <id>] [--redact-hostname]` | Run onboarding handshake and mandatory `agent` entity registration in graph |
+| `nexarch init-agent --bind-to-external-key <key> [--bind-relationship-type <code>]` | Optionally bind the agent node to an existing graph external key |
+| `nexarch init-agent` (default behavior) | Also upserts technology component entities (host, OS, Node.js runtime) and links them to the agent |
+| `nexarch agent identify ...` | Submit provider/model/client identity metadata to complete agent profile enrichment |
+
+## Bootstrap flow after `init-agent`
+
+`nexarch init-agent` writes a bootstrap file at:
+
+```sh
+~/.nexarch/agent-bootstrap.md
+```
+
+That file contains a pre-filled `npx nexarch agent identify ...` command template.
+The current workflow is:
+
+1. run `npx nexarch init-agent`
+2. open `~/.nexarch/agent-bootstrap.md`
+3. copy the generated `npx nexarch agent identify ...` template
+4. fill in the real provider/model/client details
+5. run the completed command
+
+Do not assume an `npx nexarch agent prompt` command exists unless/until it is explicitly implemented and documented.
+
+## Company context behavior
+
+- Company is selected during `nexarch login`.
+- If your user has one active company, login auto-selects it.
+- If your user has multiple active companies, login requires explicit selection.
+- To switch company later, run `nexarch login` again and pick another company.
+
+## Requirements
+
+- Node.js 18 or later
+- A Nexarch workspace account
+
+## Documentation
+
+[nexarch.ai/docs/cli-reference](https://nexarch.ai/docs/cli-reference)

package/dist/commands/enroll.js

@@ -3,6 +3,8 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { expandHomePath, supportsAutoWrite, writeClientConfig } from "../lib/client-config-writers.js";
+import { fetchAgentRegistryOrThrow } from "../lib/agent-registry.js";
+import { installSkillsForRuntime } from "../lib/skills.js";
 // Matches www.nexarch.ai — the default production host for the web app that
 // owns /api/agent-enrollments/exchange. Not the same service as
 // mcp.nexarch.ai (the MCP gateway); --host exists because staging and
@@ -36,6 +38,18 @@ function parseOptionValue(args, option) {
 function redactedManifest(manifest) {
     return { ...manifest, credential: { ...manifest.credential, token: "(redacted — see saved file, or pass --print-token)" } };
 }
+function skillRuntimeForClient(clientCode) {
+    switch (clientCode) {
+        case "claude-code":
+            return "claude-code";
+        case "codex-cli":
+            return "codex-cli";
+        case "hermes-agent":
+            return "hermes-agent";
+        default:
+            return null;
+    }
+}
 /**
  * Bootstraps a headless (browserless) MCP agent by redeeming a one-time
  * enrollment code for a long-lived credential — the CLI equivalent of the
@@ -95,9 +109,15 @@ export async function enroll(args) {
         });
         wroteClientConfig = true;
     }
+    let skills = [];
+    const skillRuntime = skillRuntimeForClient(clientCode);
+    if (skillRuntime) {
+        const registry = await fetchAgentRegistryOrThrow();
+        skills = installSkillsForRuntime(registry, skillRuntime);
+    }
     if (asJson) {
         const output = printToken ? manifest : redactedManifest(manifest);
-        process.stdout.write(`${JSON.stringify({ ...output, wroteClientConfig }, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify({ ...output, wroteClientConfig, skills }, null, 2)}\n`);
         return;
     }
     console.log(`✓ Enrolled agent ${manifest.agent.ref} in workspace "${manifest.workspace.name}"`);
@@ -114,6 +134,13 @@ export async function enroll(args) {
     else {
         console.log(`\nNo known auto-write target for client "${clientCode}" — connect it manually:`);
     }
+    if (skills.length > 0) {
+        console.log(`\n${clientCode} skills:`);
+        for (const skill of skills) {
+            const verb = skill.status === "installed" ? "installed" : skill.status === "updated" ? "updated" : "already current";
+            console.log(`  ${verb.padEnd(15)} ${skill.dirName}`);
+        }
+    }
     const shownToken = printToken ? manifest.credential.token : `<see ${destination}>`;
     if (manifest.connectInstructionsTemplate) {
         console.log(renderInstructions(manifest.connectInstructionsTemplate, manifest, shownToken, mcpEndpoint));

package/dist/commands/setup.js

@@ -3,7 +3,7 @@ import { requireCredentials } from "../lib/credentials.js";
 import { detectClientsFromRegistry, writeClientConfig, nexarchServerBlockFromRegistry } from "../lib/clients.js";
 import { fetchAgentRegistryOrThrow } from "../lib/agent-registry.js";
 import { initAgent } from "./init-agent.js";
-import { installSkillsForRuntime } from "../lib/skills.js";
+import { installSkillsForRuntime, installedSkillRuntimes } from "../lib/skills.js";
 import { login } from "./login.js";
 function argValue(args, flag) {
     const idx = args.indexOf(flag);
@@ -168,22 +168,19 @@ export async function setup(args) {
         initAgentArgs.push("--instruction-runtime-targets", instructionRuntimeTargets.join(","));
     }
     await initAgent(initAgentArgs);
-    // Claude Code and Codex CLI both support Agent Skills: a trigger
-    // description that sits permanently in the agent's context and loads a
-    // playbook when a matching moment comes up. MCP alone makes the graph
-    // available; skills are what make an agent actually consult it — for
-    // building, diagramming, working its command queue, and governance
-    // review. Both runtimes use the same SKILL.md format, just a different
-    // root directory (see RUNTIME_SKILLS_ROOT in lib/skills.ts), so the same
-    // content installs to both unmodified. Installed under the same consent
-    // as instruction writes — setup already opts into those above.
-    const skillRuntimes = [
-        { clientCode: "claude-code", runtime: "claude-code", label: "Claude Code" },
-        { clientCode: "codex-cli", runtime: "codex-cli", label: "Codex CLI" },
-    ];
-    for (const { clientCode, runtime, label } of skillRuntimes) {
-        if (!clients.some((client) => client.code === clientCode))
-            continue;
+    // Refresh every installed skill-capable runtime, not only MCP clients
+    // detected in this setup pass. This keeps `setup` useful for existing
+    // installations and gives it the same managed-skill behavior as
+    // `nexarch skills update`.
+    const skillRuntimes = new Set(installedSkillRuntimes());
+    for (const client of clients) {
+        if (client.code === "claude-code")
+            skillRuntimes.add("claude-code");
+        if (client.code === "codex-cli")
+            skillRuntimes.add("codex-cli");
+    }
+    for (const runtime of skillRuntimes) {
+        const label = runtime === "claude-code" ? "Claude Code" : runtime === "codex-cli" ? "Codex CLI" : "Hermes Agent";
         try {
             const skills = installSkillsForRuntime(registry, runtime);
             const anyChanged = skills.some((s) => s.status !== "already_current");

package/dist/commands/skills-update.js

@@ -0,0 +1,51 @@
+import { requireCredentials } from "../lib/credentials.js";
+import { fetchAgentRegistryOrThrow } from "../lib/agent-registry.js";
+import { installSkillsForRuntime, installedSkillRuntimes } from "../lib/skills.js";
+const RUNTIME_LABELS = {
+    "claude-code": "Claude Code",
+    "codex-cli": "Codex CLI",
+    "hermes-agent": "Hermes Agent",
+};
+function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+export async function skillsUpdate(args) {
+    if (hasFlag(args, "--help") || hasFlag(args, "-h")) {
+        console.log(`
+Usage:
+  nexarch skills update [--json]
+
+Refresh all Nexarch-managed skills for installed agent runtimes.
+`);
+        return;
+    }
+    const asJson = hasFlag(args, "--json");
+    requireCredentials();
+    const registry = await fetchAgentRegistryOrThrow();
+    const runtimes = installedSkillRuntimes();
+    const results = [];
+    for (const runtime of runtimes) {
+        results.push({
+            runtime,
+            label: RUNTIME_LABELS[runtime],
+            skills: installSkillsForRuntime(registry, runtime),
+        });
+    }
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify({ registryVersion: registry.release.version, runtimes: results }, null, 2)}\n`);
+        return;
+    }
+    console.log(`Using integration registry release v${registry.release.version}.`);
+    if (results.length === 0) {
+        console.log("No installed Nexarch skill runtimes found.");
+        return;
+    }
+    for (const result of results) {
+        console.log(`\n${result.label} skills:`);
+        for (const skill of result.skills) {
+            const verb = skill.status === "installed" ? "installed" : skill.status === "updated" ? "updated" : "already current";
+            console.log(`  ${verb.padEnd(15)} ${skill.dirName}`);
+        }
+    }
+    console.log("\nNexarch-managed skills refreshed.");
+}

package/dist/index.js

@@ -4,6 +4,7 @@ import { enroll } from "./commands/enroll.js";
 import { logout } from "./commands/logout.js";
 import { status } from "./commands/status.js";
 import { setup } from "./commands/setup.js";
+import { skillsUpdate } from "./commands/skills-update.js";
 import { mcpConfig } from "./commands/mcp-config.js";
 import { mcpProxy } from "./commands/mcp-proxy.js";
 import { initAgent } from "./commands/init-agent.js";
@@ -82,6 +83,13 @@ async function main() {
             return;
         }
     }
+    if (command === "skills") {
+        const [subcommand, ...subArgs] = args;
+        if (subcommand === "update") {
+            await skillsUpdate(subArgs);
+            return;
+        }
+    }
     if (command === "proposals") {
         const [subcommand, ...subArgs] = args;
         if (subcommand === "start") {
@@ -119,8 +127,8 @@ Usage:
                         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.
+                        and installs its Nexarch skills; for anything else,
+                        prints instructions instead.
                         Options: --code <code>          (required, starts with nxe_)
                                  --client <code>         (required, e.g. hermes-agent)
                                  --client-version <v>
@@ -141,6 +149,8 @@ Usage:
                         Options: --company <id|code>  target a workspace directly
                                  --yes  accept the stored workspace without asking
                                  --no-browser  log in by pasting a one-time code (see login)
+  nexarch skills update
+                        Refresh all Nexarch-managed skills for installed agent runtimes
   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)

package/dist/lib/skills.js

@@ -408,7 +408,16 @@ export const SKILLS = [
 const RUNTIME_SKILLS_ROOT = {
     "claude-code": [".claude", "skills"],
     "codex-cli": [".agents", "skills"],
+    "hermes-agent": [".hermes", "skills"],
 };
+export function skillRootForRuntime(runtime, homeDir = homedir()) {
+    return runtime === "hermes-agent" && process.env.HERMES_HOME
+        ? join(process.env.HERMES_HOME, "skills")
+        : join(homeDir, ...RUNTIME_SKILLS_ROOT[runtime]);
+}
+export function installedSkillRuntimes(homeDir = homedir()) {
+    return Object.keys(RUNTIME_SKILLS_ROOT).filter((runtime) => existsSync(skillRootForRuntime(runtime, homeDir)));
+}
 function installSkill(spec, registry, skillsRoot) {
     const template = registry.instructionTemplates.find((t) => t.code === spec.templateCode);
     const body = template ? template.body.trim() + "\n" : spec.fallbackBody;
@@ -428,7 +437,6 @@ function installSkill(spec, registry, skillsRoot) {
     return { dirName: spec.dirName, path: skillPath, status: "installed", source };
 }
 export function installSkillsForRuntime(registry, runtime, options = {}) {
-    const homeDir = options.homeDir ?? homedir();
-    const skillsRoot = join(homeDir, ...RUNTIME_SKILLS_ROOT[runtime]);
+    const skillsRoot = skillRootForRuntime(runtime, options.homeDir ?? homedir());
     return SKILLS.map((spec) => installSkill(spec, registry, skillsRoot));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexarch",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "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 && tsx scripts/test-search-icons.ts && tsx scripts/test-paste-login.ts && tsx scripts/test-credentials-resolution.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 && tsx scripts/test-paste-login.ts && tsx scripts/test-credentials-resolution.ts && tsx scripts/test-hermes-skills.ts"
   },
   "devDependencies": {
     "@types/node": "^22",