nexarch 0.12.28 → 0.12.31

package/dist/commands/init-project.js

@@ -1877,8 +1877,8 @@ export async function initProject(args) {
             pendingSteps.push({
                 step: stepNum++,
                 action: "describe_project",
-                instruction: `Give the project (repository) entity a short description of what lives in this repo.`,
-                command: `nexarch update-entity --key "${projectEntityKey}" --entity-type "project" --name "${projectDirName}" --description "..."`,
+                instruction: `Give the project (repository) entity a meaningful display name (not the raw directory name "${projectDirName}") and a short description of what lives in this repo.`,
+                command: `nexarch update-entity --key "${projectEntityKey}" --entity-type "project" --name "..." --description "..."`,
             });
         }
         if (!projectConstruct || !isMonorepo) {
@@ -2149,8 +2149,8 @@ export async function initProject(args) {
         lines.push("REMAINING STEPS:");
         let step = 1;
         if (projectConstruct) {
-            lines.push(`  ${step++}. nexarch update-entity --key "${projectEntityKey}" --entity-type "project" --name "${projectDirName}" --description "..."`);
-            lines.push(`     (short description of what lives in this repository)`);
+            lines.push(`  ${step++}. nexarch update-entity --key "${projectEntityKey}" --entity-type "project" --name "..." --description "..."`);
+            lines.push(`     (meaningful display name — not the raw directory name "${projectDirName}" — and a short description of what lives in this repository)`);
         }
         if (!projectConstruct || !isMonorepo) {
             lines.push(`  ${step++}. nexarch update-entity --key "${projectExternalKey}" --entity-type "${entityTypeOverride}"${entityTypeOverride === "application" ? ' --subtype "<subtype>" --icon "<lucide-icon>"' : ""} --name "..." --description "..."`);

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 { installClaudeCodeSkill } from "../lib/skills.js";
+import { installSkillsForRuntime } from "../lib/skills.js";
 import { login } from "./login.js";
 function argValue(args, flag) {
     const idx = args.indexOf(flag);
@@ -168,25 +168,38 @@ export async function setup(args) {
         initAgentArgs.push("--instruction-runtime-targets", instructionRuntimeTargets.join(","));
     }
     await initAgent(initAgentArgs);
-    // Claude Code supports Agent Skills: a trigger description that sits
-    // permanently in the agent's context and loads a playbook when a build-shaped
-    // moment matches. MCP alone makes the graph available; the skill is what
-    // makes an agent check it before building something new. Installed under the
-    // same consent as instruction writes — setup already opts into those above.
-    const hasClaudeCode = clients.some((client) => client.code === "claude-code");
-    if (hasClaudeCode) {
+    // 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;
         try {
-            const skill = installClaudeCodeSkill(registry);
-            const verb = skill.status === "installed" ? "installed" : skill.status === "updated" ? "updated" : "already current";
-            console.log(`\nClaude Code skill ${verb}: ${skill.path}`);
-            if (skill.status !== "already_current") {
-                console.log("  New Claude Code sessions will check the architecture graph before building something new.");
+            const skills = installSkillsForRuntime(registry, runtime);
+            const anyChanged = skills.some((s) => s.status !== "already_current");
+            console.log(`\n${label} 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}`);
+            }
+            if (anyChanged) {
+                console.log(`  New ${label} sessions will use these to decide when to consult Nexarch.`);
             }
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            console.log(`\nClaude Code skill install failed — ${message}`);
-            console.log("  Setup is otherwise complete; re-run setup to retry the skill.");
+            console.log(`\n${label} skill install failed — ${message}`);
+            console.log("  Setup is otherwise complete; re-run setup to retry the skills.");
         }
     }
     if (clients.length > 0) {

package/dist/lib/skills.js

@@ -1,24 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
-/**
- * Claude Code skill installation.
- *
- * MCP makes the architecture graph *available* to an agent; nothing makes the
- * agent *consult* it. Tool descriptions are skimmed once and forgotten, and the
- * injected AGENTS.md block is repo-scoped. A skill closes that gap: its
- * description sits permanently in the agent's context as a trigger, and when a
- * build-shaped moment matches, the full playbook loads.
- *
- * The body is registry-managed (template nexarch_claude_code_skill_v1) so it
- * can be updated by migration like the instruction templates; the baked-in
- * fallback below keeps installs working when the registry predates the
- * template. Installed to the user-level skills directory because agent setup is
- * a per-machine action, like MCP client configuration.
- */
-export const CLAUDE_SKILL_TEMPLATE_CODE = "nexarch_claude_code_skill_v1";
-export const CLAUDE_SKILL_DIR_NAME = "nexarch-architecture-graph";
-export const FALLBACK_SKILL_BODY = `---
+const ARCHITECTURE_GRAPH_SKILL_BODY = `---
 name: nexarch-architecture-graph
 description: Consult the organisation's Nexarch architecture graph before building anything new, and register what gets built. Use when creating a new service, application, module, integration, API endpoint, or scheduled job; when adding a significant dependency or choosing between libraries; when asked whether a capability, integration, or dataset already exists; or when asked what applications or systems the organisation has. Requires the Nexarch MCP tools (nexarch_*).
 ---
@@ -61,21 +44,185 @@ repository; the graph knows all of them.
 - End architectural work with a one-line summary of what was recorded and what
   remains unresolved.
 `;
-export function installClaudeCodeSkill(registry, options = {}) {
-    const template = registry.instructionTemplates.find((t) => t.code === CLAUDE_SKILL_TEMPLATE_CODE);
-    const body = template ? template.body.trim() + "\n" : FALLBACK_SKILL_BODY;
+const DIAGRAM_VIEWS_SKILL_BODY = `---
+name: nexarch-diagram-views
+description: Create, update, or find an architecture diagram in Nexarch. Use when asked to visualize, diagram, or map the architecture; show a system topology or environment overview; draw how something connects to the rest of the estate; or update an existing diagram's layout or filters. Requires the Nexarch MCP tools (nexarch_*).
+---
+
+# Nexarch Diagram Views
+
+Diagrams in Nexarch are saved views over the live graph, not static images —
+each one has filters, a layout, and a revision history, and every view is
+shared workspace state, not scratch output.
+
+## Before creating one
+
+1. \`nexarch_list_diagram_views\` — check whether a view covering this already
+   exists (they're grouped by folder). Reuse an existing view over creating a
+   near-duplicate; the same reuse-before-build principle applies to diagrams
+   as it does to applications.
+2. If one exists but looks stale or wrong, \`nexarch_get_diagram_view\` to see
+   its current filters/layout before deciding whether to update it or start
+   fresh.
+
+## Creating or refreshing a view
+
+- Prefer \`nexarch_generate_diagram_view\` over hand-building one: it derives
+  nodes and edges straight from graph semantics (\`application_topology\`,
+  \`environment_overview\`, or \`edge_to_runtime\`), so it's correct by
+  construction and stays correct as the graph changes.
+- Reach for \`nexarch_create_diagram_view\` only when you need a specific,
+  hand-picked set of filters that generation doesn't produce.
+- To modify an existing view's filters or layout, \`nexarch_update_diagram_view\`
+  is optimistic-locked — always \`nexarch_get_diagram_view\` first to read the
+  current \`lockVersion\` and pass it back, or the update will be rejected
+  rather than silently overwriting a concurrent edit.
+
+## Ground rules
+
+- Never write a diagram view no one asked for; a rendered summary in chat is
+  enough unless the human wants it saved to the workspace.
+- \`nexarch_list_diagram_revisions\` before assuming a view's current state is
+  its only state — check history before concluding something was never
+  captured.
+- Confirm which view you updated (name, folder) so the human can find it in
+  the workspace, not just in this conversation.
+`;
+const AGENT_WORKQUEUE_SKILL_BODY = `---
+name: nexarch-agent-workqueue
+description: Check for and work through pending Nexarch commands assigned to this agent. Use when the human asks you to check in, look for pending work, process the command queue, or asks whether there's anything waiting for this agent. Requires the Nexarch MCP tools (nexarch_*).
+---
+
+# Nexarch Agent Work Queue
+
+Nexarch can queue commands for a specific registered agent — review requests,
+scans, follow-ups raised by other agents or humans in the workspace. This
+skill is the check-in → claim → complete loop for working that queue.
+
+## Checking in
+
+- \`nexarch_check_in\` previews pending commands and draft/proposed
+  applications for this agent. It does **not** claim or change anything —
+  safe to call any time, including proactively at the start of a session.
+- Report exactly what check-in found. Don't reinterpret "check in" as
+  registration (\`init-agent\`) or as a general health check
+  (\`nexarch_get_governance_summary\`) — they're different actions.
+- If check-in fails because this agent isn't registered yet, that's a signal
+  to register first, not to fall back to a different tool.
+
+## Working a command
+
+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.
+2. Do the work the command describes.
+3. Close it out: \`nexarch_complete_command\` on success, or
+   \`nexarch_fail_command\` with a reason if it couldn't be done. Never leave a
+   claimed command unresolved at the end of a session.
+
+## Ground rules
+
+- \`nexarch_claim_command\` is a legacy alias for \`nexarch_check_in\` — use
+  \`nexarch_check_in\` directly, not the alias.
+- One command at a time is fine; don't claim ahead of what you can actually
+  finish in this session.
+- Summarize what was claimed, completed, or failed — the human wasn't
+  watching the queue directly.
+`;
+const GOVERNANCE_REVIEW_SKILL_BODY = `---
+name: nexarch-governance-review
+description: Check or record compliance, policy audit results, decision conformance, or review a proposed application before activation. Use when asked about compliance or policy status for an app, to run or record a policy audit, whether an architectural decision was actually implemented, or to review/activate an application waiting in the proposed queue. Requires the Nexarch MCP tools (nexarch_*).
+---
+
+# Nexarch Governance Review
+
+Governance in Nexarch is evidence-backed: controls are assigned to entities,
+audits are recorded (not inferred), and proposed applications wait for
+explicit human activation. This skill covers reading and recording that
+evidence — never invent a compliance status that isn't stored.
+
+## Compliance and policy status
+
+- Asked about compliance or policy status for an app → \`nexarch_get_policy_audit_results\`
+  first. **No stored results means say so** — "no audit has been run" — rather
+  than guessing from the code.
+- \`nexarch_get_entity_policy_controls\` to see which controls actually apply
+  to a given entity before assessing it against the wrong set.
+- To record a real audit: read the applicable rules from
+  \`nexarch_get_applied_policies\`, evaluate the evidence yourself, then
+  persist the findings with \`nexarch_submit_policy_audit\`. The tool stores
+  results — it does not evaluate anything for you.
+- \`nexarch_submit_decision_conformance\` records whether a repository actually
+  implements a \`decision_record\` at a given commit, with evidence. Use this
+  when checking whether an architectural decision was followed, not just
+  whether it was written down.
+
+## Proposed applications
+
+- \`nexarch_list_proposed_applications\` — the review queue: apps an agent
+  drafted that are waiting on a human.
+- \`nexarch_get_proposed_application\` — full context before recommending
+  anything: recommendation provenance, capability gaps, linked policy
+  controls, pre-scaffold review requirements.
+- \`nexarch_activate_proposed_application\` moves one to active state. Only
+  call this once the human has actually asked for it and the scaffolding is
+  real — being listed as proposed is not itself permission to activate.
+
+## Ground rules
+
+- Findings are evidence, not opinion: cite what \`nexarch_get_policy_audit_results\`
+  or \`nexarch_submit_policy_audit\` actually returned rather than paraphrasing
+  from memory.
+- Never activate a proposed application on your own judgement alone — surface
+  what you found and let the human decide, same as the reuse-before-build
+  principle elsewhere in Nexarch.
+`;
+export const SKILLS = [
+    {
+        templateCode: "nexarch_claude_code_skill_v1",
+        dirName: "nexarch-architecture-graph",
+        fallbackBody: ARCHITECTURE_GRAPH_SKILL_BODY,
+    },
+    {
+        templateCode: "nexarch_diagram_views_skill_v1",
+        dirName: "nexarch-diagram-views",
+        fallbackBody: DIAGRAM_VIEWS_SKILL_BODY,
+    },
+    {
+        templateCode: "nexarch_agent_workqueue_skill_v1",
+        dirName: "nexarch-agent-workqueue",
+        fallbackBody: AGENT_WORKQUEUE_SKILL_BODY,
+    },
+    {
+        templateCode: "nexarch_governance_review_skill_v1",
+        dirName: "nexarch-governance-review",
+        fallbackBody: GOVERNANCE_REVIEW_SKILL_BODY,
+    },
+];
+const RUNTIME_SKILLS_ROOT = {
+    "claude-code": [".claude", "skills"],
+    "codex-cli": [".agents", "skills"],
+};
+function installSkill(spec, registry, skillsRoot) {
+    const template = registry.instructionTemplates.find((t) => t.code === spec.templateCode);
+    const body = template ? template.body.trim() + "\n" : spec.fallbackBody;
     const source = template ? "registry" : "fallback";
-    const skillDir = join(options.homeDir ?? homedir(), ".claude", "skills", CLAUDE_SKILL_DIR_NAME);
+    const skillDir = join(skillsRoot, spec.dirName);
     const skillPath = join(skillDir, "SKILL.md");
     if (existsSync(skillPath)) {
         const existing = readFileSync(skillPath, "utf8");
         if (existing === body) {
-            return { path: skillPath, status: "already_current", source };
+            return { dirName: spec.dirName, path: skillPath, status: "already_current", source };
         }
         writeFileSync(skillPath, body, "utf8");
-        return { path: skillPath, status: "updated", source };
+        return { dirName: spec.dirName, path: skillPath, status: "updated", source };
     }
     mkdirSync(skillDir, { recursive: true });
     writeFileSync(skillPath, body, "utf8");
-    return { path: skillPath, status: "installed", source };
+    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]);
+    return SKILLS.map((spec) => installSkill(spec, registry, skillsRoot));
 }

package/package.json

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