nexarch 0.12.29 → 0.12.33

package/dist/commands/login.js

@@ -6,8 +6,22 @@ import { saveCredentials } from "../lib/credentials.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
+import { selectFromList } from "../lib/prompt-select.js";
 const NEXARCH_URL = "https://nexarch.ai";
 const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+// Mirrors AGENT_CAPABILITY_PROFILES in web/src/lib/mcp-agents.ts — the
+// server is the actual authority on what each profile grants; this is just
+// the same labels/descriptions shown in the enrollment UI, reused here so
+// the CLI prompt and the web form agree about what "Worker" means.
+const PROFILE_CHOICES = [
+    { value: "observer", label: "Observer", description: "Read graph, policies, and governance context. Cannot write or claim work." },
+    { value: "contributor", label: "Contributor", description: "Observer, plus proposing entities/relationships and new applications." },
+    { value: "worker", label: "Worker", description: "Contributor, plus checking in, claiming, and completing commands." },
+    { value: "delivery", label: "Delivery", description: "Worker, plus activating proposed applications." },
+];
+async function promptCapabilityProfile() {
+    return selectFromList("Select a capability profile for this credential:", PROFILE_CHOICES, "worker");
+}
 function printLoginBanner() {
     const logo = String.raw `
         ######        ######
@@ -136,10 +150,14 @@ export async function login(args) {
     const state = generateState();
     const port = await findFreePort();
     const requestedCompany = getArgValue(args, "--company");
-    const qp = new URLSearchParams({ port: String(port), state });
+    const requestedProfile = getArgValue(args, "--profile");
+    const isCapabilityProfile = (value) => PROFILE_CHOICES.some((c) => c.value === value);
+    const profile = isCapabilityProfile(requestedProfile) ? requestedProfile : await promptCapabilityProfile();
+    const qp = new URLSearchParams({ port: String(port), state, profile });
     if (requestedCompany)
         qp.set("company", requestedCompany);
     const authUrl = `${NEXARCH_URL}/auth/cli?${qp.toString()}`;
+    console.log(`\nCapability profile: ${profile}`);
     console.log("Opening Nexarch in your browser…");
     console.log(`\n  ${authUrl}\n`);
     console.log("If the browser did not open, copy the URL above and paste it in manually.\n");

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/prompt-select.js

@@ -0,0 +1,72 @@
+import readline from "readline";
+/**
+ * Arrow-key single-select prompt. No dependency — this package has none for
+ * a reason (see package.json), and Node's own readline keypress events cover
+ * the whole interaction: up/down to move, enter to confirm, ctrl+c to abort.
+ *
+ * Falls back to `defaultValue` without prompting when stdin/stdout isn't a
+ * TTY (piped input, --non-interactive runs, CI) — the same guard setup.ts
+ * already uses for its yes/no prompt.
+ */
+export async function selectFromList(title, choices, defaultValue) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        return defaultValue;
+    }
+    const defaultIndex = choices.findIndex((c) => c.value === defaultValue);
+    let index = defaultIndex >= 0 ? defaultIndex : 0;
+    let linesDrawn = 0;
+    const render = () => {
+        if (linesDrawn > 0) {
+            readline.moveCursor(process.stdout, 0, -linesDrawn);
+            readline.cursorTo(process.stdout, 0);
+            readline.clearScreenDown(process.stdout);
+        }
+        const lines = [
+            `${title} (↑/↓ to move, enter to select)`,
+            ...choices.flatMap((choice, i) => {
+                const selected = i === index;
+                const pointer = selected ? "❯ " : "  ";
+                const label = selected ? `\x1b[1m${choice.label}\x1b[0m` : choice.label;
+                return [`${pointer}${label}`, `    ${choice.description}`];
+            }),
+        ];
+        process.stdout.write(lines.join("\n") + "\n");
+        linesDrawn = lines.length;
+    };
+    return new Promise((resolve) => {
+        readline.emitKeypressEvents(process.stdin);
+        const wasRaw = process.stdin.isRaw;
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        const cleanup = () => {
+            process.stdin.removeListener("keypress", onKeypress);
+            process.stdin.setRawMode(Boolean(wasRaw));
+            process.stdin.pause();
+        };
+        const onKeypress = (_str, key) => {
+            if (!key)
+                return;
+            if (key.ctrl && key.name === "c") {
+                cleanup();
+                console.log();
+                process.exit(130);
+            }
+            if (key.name === "up") {
+                index = (index - 1 + choices.length) % choices.length;
+                render();
+                return;
+            }
+            if (key.name === "down") {
+                index = (index + 1) % choices.length;
+                render();
+                return;
+            }
+            if (key.name === "return") {
+                cleanup();
+                resolve(choices[index].value);
+            }
+        };
+        render();
+        process.stdin.on("keypress", onKeypress);
+    });
+}

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,282 @@ 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.
+
+## If check-in shows a command you can't claim
+
+Claiming/completing/failing a command needs the \`mcp:work:commands\` scope —
+a separate, higher capability profile ("worker" or above) than what does the
+graph writing (\`mcp:write:discovery\`, granted from "contributor" up). A
+credential can see pending commands and still lack the scope to claim one;
+check-in's response says so explicitly when that's the case
+(\`claimReason: "credential_missing_work_scope"\`). If you hit this: still do
+the work if it's clearly what's needed, but say in your summary that you
+couldn't formally claim/complete the command, and that a human needs to
+either handle it in the workspace or reissue your credential with the
+"worker" profile. Don't call \`nexarch_claim_command_by_id\` speculatively —
+if your tools/list doesn't include it, your credential doesn't have the
+scope, and the call will fail.
+
+## 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.
+`;
+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_*).
+---
+
+# Nexarch Decision Records
+
+Decisions are first-class in Nexarch: \`decision_record\` entities linked to
+whatever they concern via \`decides\`, reviewed in the workspace's Decisions
+page, and optionally promoted into workspace-wide policy by a human. This
+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.
+
+## Before recording
+
+\`nexarch_resolve_reference\` / \`nexarch_list_entities\` for an existing
+\`decision_record\` covering the same choice — match by name/summary first.
+Reuse and refresh it rather than creating a duplicate for the same decision.
+
+## Recording a decision
+
+\`entityTypeCode: "decision_record"\`. Two attributes are strictly required —
+MCP rejects the write with \`INVALID_DECISION_RECORD_PAYLOAD\` if either is
+missing or empty, with no fallback to \`description\` (ADR-0101):
+
+- \`attributes.decision.summary\` — one sentence naming what was chosen.
+- \`attributes.decision.detail\` — the fuller rationale, cited to its evidence.
+
+Never invent a decision from a technology's mere presence — it must trace to
+an actual stated reason someone chose it over an alternative.
+
+### Optional fields — add them when the evidence actually supports them
+
+All additive; a decision recorded with only summary/detail is still
+completely valid. Leave a field unset rather than guessing it:
+
+- \`attributes.source.repositoryUrl\` / \`.commit\` / \`.path\` / \`.lines\` — where
+  the decision was found, so the workspace can show exact evidence and
+  detect when it drifts from what's now in the repo.
+- \`attributes.decision.status\` — one of \`unknown\` / \`proposed\` / \`accepted\`
+  / \`deprecated\` / \`superseded\` / \`rejected\`, only when the source states it
+  explicitly.
+- \`attributes.decision.rationale\` — the "why", as its own field, when it's
+  distinguishable from the alternatives/consequences discussion.
+- \`attributes.decision.alternatives\` — array of \`{"option": "...",
+  "whyRejected": "..."}\` for alternatives the source explicitly names and
+  explains rejecting. Don't invent alternatives the source never mentions.
+- \`attributes.decision.consequences\` — array of plain-string trade-offs the
+  source explicitly states.
+- \`attributes.decision.supersededByRef\` — the \`entityRef\` of the
+  \`decision_record\` that replaces this one, only when the source explicitly
+  says so. Setting this on an upsert automatically flags the old decision as
+  superseded in the workspace — you don't need to touch the old record
+  yourself.
+
+### Linking
+
+\`decision_record -> decides -> <application | technology_component |
+platform | api | other ontology-valid target>\` — the most specific existing
+entity the decision actually concerns. Only link to entities that already
+exist; this skill records decisions, it doesn't discover architecture. If
+nothing ontology-valid exists yet to link to, still record the decision and
+say so rather than skipping it or inventing a target.
+
+## Ground rules
+
+- A decision being implemented is not the same as a decision being followed
+  correctly — recording one here says nothing about whether the code
+  actually conforms. That's \`nexarch_submit_decision_conformance\` (see the
+  \`nexarch-governance-review\` skill), a separate, evidence-based check.
+- Conflicts, duplicates, and workspace-wide promotion of a decision are
+  reviewed by a human in the workspace UI, not something to resolve or
+  decide yourself — your job is accurate recording and evidenced linking.
+- End with a one-line summary: what was recorded or reused, and what (if
+  anything) couldn't be linked.
+`;
+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,
+    },
+    {
+        templateCode: "nexarch_decision_records_skill_v1",
+        dirName: "nexarch-decision-records",
+        fallbackBody: DECISION_RECORDS_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.29",
+  "version": "0.12.33",
   "description": "Your architecture workspace for AI delivery.",
   "keywords": [
     "nexarch",