nexus-agents 2.80.3 → 2.81.0

package/dist/{chunk-Q2PSRDW6.js → chunk-KL23OVEU.js}

@@ -8,7 +8,7 @@ import {
   checkSqlite,
   defaultConfig,
   initDataDirectories
-} from "./chunk-6GDF6FLC.js";
+} from "./chunk-VOFTCWSI.js";
 import {
   probeAllClis
 } from "./chunk-BMNWUPJO.js";
@@ -1974,4 +1974,4 @@ export {
   setupCommand,
   setupCommandAsync
 };
-//# sourceMappingURL=chunk-Q2PSRDW6.js.map
+//# sourceMappingURL=chunk-KL23OVEU.js.map

package/dist/{chunk-6GDF6FLC.js → chunk-VOFTCWSI.js}

@@ -40,7 +40,7 @@ import {
 } from "./chunk-I2HMWH4R.js";
 
 // src/version.ts
-var VERSION = true ? "2.80.3" : "dev";
+var VERSION = true ? "2.81.0" : "dev";
 
 // src/config/schemas-core.ts
 import { z } from "zod";
@@ -2107,7 +2107,7 @@ async function runDoctorFix(result) {
   writeLine2("\u2500".repeat(40));
   let fixCount = 0;
   if (!result.dataDirectory.rootExists || result.dataDirectory.subdirectories.some((d) => !d.exists || !d.writable)) {
-    const { runSetup } = await import("./setup-command-IJ6WIK7O.js");
+    const { runSetup } = await import("./setup-command-RC4ZBQ2V.js");
     const setupResult = runSetup({
       skipMcp: true,
       skipRules: true,
@@ -2219,4 +2219,4 @@ export {
   startStdioServer,
   closeServer
 };
-//# sourceMappingURL=chunk-6GDF6FLC.js.map
+//# sourceMappingURL=chunk-VOFTCWSI.js.map

package/dist/cli.d.ts

@@ -41,7 +41,7 @@ declare const EXIT_CODES: {
 /**
  * CLI command types that can be executed.
  */
-type CliCommand = 'server' | 'help' | 'version' | 'hello' | 'config' | 'expert' | 'workflow' | 'doctor' | 'verify' | 'review' | 'routing-audit' | 'orchestrate' | 'system-review' | 'vote' | 'index' | 'research' | 'validation' | 'learning-metrics' | 'swe-bench' | 'atbench' | 'setup' | 'hooks' | 'demo' | 'sprint' | 'session' | 'evaluate' | 'issue' | 'fitness-audit' | 'release-notes' | 'release-validate' | 'release-announce' | 'scaffold' | 'visualize' | 'capabilities' | 'status' | 'memory-benchmark' | 'auth' | 'scenario' | 'warm-up' | 'e2e-eval' | 'routing-ab' | 'memory-eval' | 'health' | 'init' | 'validate' | 'registry' | 'login' | 'usage' | 'migrate' | 'improvement-review';
+type CliCommand = 'server' | 'help' | 'version' | 'hello' | 'config' | 'expert' | 'workflow' | 'doctor' | 'verify' | 'review' | 'routing-audit' | 'orchestrate' | 'system-review' | 'vote' | 'index' | 'research' | 'validation' | 'learning-metrics' | 'swe-bench' | 'atbench' | 'setup' | 'hooks' | 'demo' | 'sprint' | 'session' | 'evaluate' | 'issue' | 'fitness-audit' | 'release-notes' | 'release-validate' | 'release-announce' | 'scaffold' | 'visualize' | 'capabilities' | 'status' | 'memory-benchmark' | 'auth' | 'scenario' | 'warm-up' | 'e2e-eval' | 'routing-ab' | 'memory-eval' | 'health' | 'init' | 'validate' | 'registry' | 'login' | 'usage' | 'migrate' | 'tour' | 'improvement-review';
 /**
  * Parsed CLI arguments and command.
  */

package/dist/cli.js

@@ -22,7 +22,7 @@ import {
 import {
   setupCommandAsync,
   verifyCommand
-} from "./chunk-Q2PSRDW6.js";
+} from "./chunk-KL23OVEU.js";
 import "./chunk-6YQCLEHL.js";
 import {
   AuthHandler,
@@ -153,7 +153,7 @@ import {
   validateCommand,
   validateWorkflow,
   wrapInMarkdownFence
-} from "./chunk-HYOIDNBX.js";
+} from "./chunk-DQW2PQU3.js";
 import "./chunk-AP2FD37C.js";
 import "./chunk-ED6VQWNG.js";
 import {
@@ -226,7 +226,7 @@ import {
   loadConfig,
   runDoctor,
   validateNexusEnv
-} from "./chunk-6GDF6FLC.js";
+} from "./chunk-VOFTCWSI.js";
 import "./chunk-WZGCVCRQ.js";
 import "./chunk-73K7575Z.js";
 import {
@@ -9511,6 +9511,11 @@ var COMMAND_CATALOG = [
     audience: "essential"
   },
   // ── Advanced ─────────────────────────────────────────────────────────────
+  {
+    command: "tour",
+    description: "Guided walkthrough of the four headline tools \u2014 no API keys, no quota (#2851). --non-interactive runs straight through.",
+    audience: "advanced"
+  },
   {
     command: "session",
     description: "Manage session persistence (list, show, export, delete)",
@@ -13520,6 +13525,180 @@ async function demoCommand(subcommand, args, options) {
   }
 }
 
+// src/cli/tour-command.ts
+import { createInterface as createInterface2 } from "readline";
+var STEP_WELCOME = {
+  title: "Welcome",
+  intro: [
+    "nexus-agents is a governance substrate for AI coding agents \u2014 Claude,",
+    "Codex, Gemini, OpenCode. The agents do the engineering; this project",
+    "routes tasks, runs adversarial review, takes consensus votes, and keeps",
+    "an immutable audit trail of everything those agents touch.",
+    "",
+    "This tour walks four headline tools using cached fixtures, so it costs",
+    "nothing to run and needs no API keys configured."
+  ].join("\n"),
+  demo: "",
+  takeaway: "No live API calls in this tour \u2014 everything you see is a representative fixture.",
+  paths: ["~/.nexus-agents/                (data root \u2014 overridable via NEXUS_DATA_DIR)"]
+};
+var STEP_ORCHESTRATE = {
+  title: "orchestrate \u2014 route a task to the right model",
+  intro: [
+    "The `orchestrate` MCP tool takes a task description, classifies it,",
+    "picks the best-fit CLI and pattern (sequential / graph / consensus),",
+    "and dispatches. Routing uses real outcome history \u2014 earlier successes",
+    "and failures bias the next pick."
+  ].join("\n"),
+  demo: [
+    'Task: "implement a /healthz endpoint with structured logging"',
+    "  Classifier:    task_type=implementation  complexity=4/10",
+    "  Router picked: claude-sonnet           (capability=code_generation, score=0.91)",
+    "  Pattern:       graph                    (2 sequential subtasks detected)",
+    "  Pre-flight:    rate-limit budget OK   |  outcome history: 14 runs, 92% success",
+    "  -> dispatched"
+  ].join("\n"),
+  takeaway: "The router learns from outcomes \u2014 bad runs lower a CLI/category score next time."
+};
+var STEP_VOTE = {
+  title: "vote --quick \u2014 3-agent consensus on a proposal",
+  intro: [
+    "`nexus-agents vote --quick` runs a 3-voter panel (architect / security /",
+    "scope_steward) on a proposal and aggregates their decisions. Each voter is",
+    "a real LLM call, runs in parallel, and returns a structured rationale.",
+    "`--quick` is for fast tie-breaks; the full 7-voter panel uses higher-order",
+    "Bayesian aggregation."
+  ].join("\n"),
+  demo: [
+    'Proposal: "Adopt Bun as the dev-time test runner alongside Vitest"',
+    "  Software Architect   APPROVE  (conf 0.82)  Keeps deps slim; vitest API parity",
+    "  Security Engineer    REJECT   (conf 0.74)  New supply-chain surface, unproven",
+    "  Scope Steward        REJECT   (conf 0.71)  Two runners = sprawl; pick one",
+    "  Result: 1/3 approve (33%)  ->  REJECTED  (simple_majority, threshold 50%)"
+  ].join("\n"),
+  takeaway: "Decisions get recorded \u2014 same proposal voted twice gets the same panel rationale."
+};
+var STEP_RESEARCH = {
+  title: "research_synthesize \u2014 cluster + align literature",
+  intro: [
+    "`research_synthesize` walks the registered research catalog, clusters",
+    "sources by topic, and maps techniques back to where they live in this",
+    "codebase. Useful for asking 'what do we know about X, and what have",
+    "we already implemented?'"
+  ].join("\n"),
+  demo: [
+    "Synthesis: 12 sources, 4 clusters",
+    "",
+    "  agent prompting        7 sources   evidence-tier: strong",
+    "    Top techniques:      ToT (5/7), self-critique (4/7)",
+    "    Implementations:     SimpleAgent.buildPrompt, agents/agentic-adapter",
+    "",
+    "  memory architectures   3 sources   evidence-tier: emerging",
+    "    Gap:                 cross-process episodic store",
+    "    Tracked at:          open issue #2921"
+  ].join("\n"),
+  takeaway: 'Maps "what the literature says" onto "what we built" \u2014 drift surfaces as gaps.'
+};
+var STEP_AUDIT = {
+  title: "verify_audit_chain \u2014 tamper-evident history",
+  intro: [
+    "Every governance-relevant action \u2014 routing decisions, votes, expert",
+    "invocations, policy denials \u2014 is appended to a Merkle-linked audit log.",
+    "`verify_audit_chain` re-walks the chain and confirms every entry hashes",
+    "back to its predecessor. If any entry was tampered with, the verification",
+    "fails at the first broken link."
+  ].join("\n"),
+  demo: [
+    "Audit chain: ~/.nexus-agents/audit/chain.jsonl",
+    "  Entries:    4,217",
+    "  Span:       2026-04-18T09:14Z  ->  2026-05-22T03:51Z",
+    "  Merkle:     OK   (every entry hashes back to its predecessor)",
+    "  Result:     VERIFIED  - chain is intact"
+  ].join("\n"),
+  takeaway: "The chain is append-only and hash-linked \u2014 any historical edit breaks verification.",
+  paths: [
+    "~/.nexus-agents/audit/chain.jsonl     (immutable audit log)",
+    "~/.nexus-agents/learning/outcomes.db  (routing outcome history)"
+  ]
+};
+var TOUR_STEPS = [
+  STEP_WELCOME,
+  STEP_ORCHESTRATE,
+  STEP_VOTE,
+  STEP_RESEARCH,
+  STEP_AUDIT
+];
+async function runTour(opts, io) {
+  io.write("\u2550\u2550\u2550 nexus-agents tour \u2550\u2550\u2550\n");
+  io.write(
+    `A no-API-keys walkthrough of the four headline tools. ${opts.nonInteractive ? "Non-interactive mode." : "Press Enter to advance."}
+`
+  );
+  for (let i = 0; i < TOUR_STEPS.length; i++) {
+    const step = TOUR_STEPS[i];
+    if (step === void 0) continue;
+    renderStep(io, step, i + 1, TOUR_STEPS.length);
+    if (!opts.nonInteractive && i < TOUR_STEPS.length - 1) {
+      await io.prompt("\nPress Enter to continue (Ctrl-C to exit) ... ");
+    }
+  }
+  io.write("\n\u2550\u2550\u2550 Tour complete \u2550\u2550\u2550\n");
+  io.write("Next steps:\n");
+  io.write("  nexus-agents doctor              -- check your install\n");
+  io.write("  nexus-agents setup               -- configure MCP + .rules + data dirs\n");
+  io.write("  nexus-agents --help --all        -- see every command\n");
+  io.close();
+  return 0;
+}
+function renderStep(io, step, n, total) {
+  io.write(`
+\u2500\u2500\u2500 Step ${String(n)}/${String(total)}: ${step.title} \u2500\u2500\u2500
+
+`);
+  io.write(`${step.intro}
+`);
+  if (step.demo !== "") {
+    io.write("\n--- representative output ---\n");
+    io.write(`${step.demo}
+`);
+    io.write("--- end output ---\n");
+  }
+  io.write(`
+Takeaway: ${step.takeaway}
+`);
+  if (step.paths !== void 0 && step.paths.length > 0) {
+    io.write("\nFiles on your machine:\n");
+    for (const p of step.paths) io.write(`  - ${p}
+`);
+  }
+}
+function interactiveIO() {
+  const rl = createInterface2({ input: process.stdin, output: process.stdout });
+  return {
+    write: (text) => {
+      process.stdout.write(text);
+    },
+    prompt: (question) => new Promise((resolve14) => {
+      rl.question(question, (answer) => {
+        resolve14(answer.trim());
+      });
+    }),
+    close: () => {
+      rl.close();
+    }
+  };
+}
+function scriptedIO() {
+  return {
+    write: (text) => {
+      process.stdout.write(text);
+    },
+    prompt: () => Promise.resolve(""),
+    close: () => {
+    }
+  };
+}
+
 // src/cli/fitness-audit.ts
 var COLORS = colors;
 function formatScore(score, max) {
@@ -16262,7 +16441,8 @@ var VALID_COMMANDS = [
   "login",
   "usage",
   "improvement-review",
-  "migrate"
+  "migrate",
+  "tour"
 ];
 function isValidCommand(value) {
   return VALID_COMMANDS.includes(value);
@@ -20025,6 +20205,11 @@ async function handleDemoCommand(args) {
   const exitCode = await demoCommand(subcommand, additionalArgs, options);
   process.exit(exitCode === 0 ? EXIT_CODES.SUCCESS : EXIT_CODES.SERVER_START_FAILED);
 }
+async function handleTourCommand(args) {
+  const io = args.options.nonInteractive ? scriptedIO() : interactiveIO();
+  const exitCode = await runTour({ nonInteractive: args.options.nonInteractive }, io);
+  process.exit(exitCode === 0 ? EXIT_CODES.SUCCESS : EXIT_CODES.SERVER_START_FAILED);
+}
 async function handleHooksCommand(args) {
   if (args.options.help || args.positionals.length < 2) {
     printHookHelp();
@@ -22520,6 +22705,8 @@ var ASYNC_COMMAND_HANDLERS = {
   init: handleInitCommand,
   demo: handleDemoCommand,
   // Made async for live CLI execution
+  // Issue #2851: nexus-agents tour — interactive zero-API walkthrough
+  tour: handleTourCommand,
   // Issue #526: Newly wired async commands
   sprint: handleSprintCommand,
   session: handleSessionCommand,