@inkobytes/nexus 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 1.0.2 - 2026-06-03
+
+- Collapsed large `nexus doctor` Git Privacy floods into grouped per-root summaries with sample paths.
+- Prioritized `CONTINUITY.md` and `memories/` samples first so agent-local issues stay visible.
+
+## 1.0.1 - 2026-06-02
+
+- Added colorized `nexus help` output for a more readable CLI experience.
+- Added `nexus completion zsh` so users can load shell completions without extra scripts.

package/README.md

@@ -67,6 +67,23 @@ npx @inkobytes/nexus help
 
 Requires Node.js 18 or newer.
 
+## What's New In 1.0.1
+
+- Colorized `nexus help` output for easier scanning in the terminal
+- Built-in `nexus completion zsh` support for shell completions
+
+See [CHANGELOG.md](./CHANGELOG.md) for the release summary.
+
+## Shell Experience
+
+For better typed-command ergonomics in `zsh`, load Nexus completions:
+
+```bash
+source <(nexus completion zsh)
+```
+
+If you want typed commands themselves to colorize while you type in iTerm, pair that with `zsh-syntax-highlighting`. Nexus provides the completions and colorized CLI output; the live input-line highlighting is handled by your shell.
+
 ## Quick Start
 
 In a Git repo:
@@ -149,6 +166,7 @@ Doctor reports grouped issues:
 - missing Nexus files
 - package script exfiltration and install-hook risks
 - package privacy risks for local/private files
+- grouped Git Privacy summaries for tracked private/local trees so large agent folders stay readable
 - stale nexus locks
 - missing agent instructions specifically for nexus
 - missing continuity and memory scaffolds
@@ -198,6 +216,17 @@ nexus dashboard --serve --port 13787
 
 The dashboard prints both `127.0.0.1` and local-network URLs when available, then shows repo health, active locks, queue items, recent standup lines, recent release notes, and dirty git files. It uses local files as the source of truth and updates the page through server-sent events. The default port is `13787`; if that port is already in use, Nexus tries `13788`, `13789`, and so on. Passing `--port` uses that exact port.
 
+### `nexus completion zsh`
+
+Print a zsh completion script for Nexus.
+
+```bash
+nexus completion zsh
+source <(nexus completion zsh)
+```
+
+This gives `zsh` tab-completion for commands like `claim`, `release`, `doctor`, `drill`, and common agent handles such as `@codex` and `@claude`.
+
 ### `nexus ledger [--json]`
 
 Show completed task entries from `_NEXUS_LEDGER.md`.

package/bin/nexus.js

@@ -5,6 +5,7 @@ import { argv, exit } from 'process';
 const COMMANDS = {
   init: () => import('../src/commands/init.js'),
   doctor: () => import('../src/commands/doctor.js'),
+  completion: () => import('../src/commands/completion.js'),
   checkin: () => import('../src/commands/checkin.js'),
   checkout: () => import('../src/commands/checkout.js'),
   claim: () => import('../src/commands/claim.js'),
@@ -24,7 +25,8 @@ const COMMANDS = {
   help: () => import('../src/commands/help.js'),
 };
 
-const VERSION = '1.0.0';
+const VERSION = '1.0.1';
+const COLORS = createColors();
 
 const args = argv.slice(2);
 const command = args[0];
@@ -40,8 +42,8 @@ if (command === '--version' || command === '-v') {
 }
 
 if (!COMMANDS[command]) {
-  console.error(`Unknown command: ${command}`);
-  console.error(`Run "nexus help" for available commands.`);
+  console.error(COLORS.red(`Unknown command: ${command}`));
+  console.error(`Run ${COLORS.cyan('nexus help')} for available commands.`);
   exit(1);
 }
 
@@ -54,55 +56,98 @@ try {
 }
 
 function printHelp() {
-  console.log(`
-@inkobytes/nexus v${VERSION}
-Multi-agent coordination for shared repositories.
+  const commands = [
+    ['init', 'Scaffold Nexus files into current repo'],
+    ['doctor [--fix] [--json]', 'Check or repair agent protocol files'],
+    ['completion zsh', 'Print zsh completion script for nexus'],
+    ['checkin <agent>', 'Signal agent presence (heartbeat)'],
+    ['checkout [--all] <agent>', 'Signal session end or cleanup'],
+    ['claim <path> <agent> "<intent>"', 'Lock a file or directory'],
+    ['release <path> "<commit msg>"', 'Unlock, auto-commit, and log'],
+    ['standup "<dated message>"', 'Append a validated standup line'],
+    ['status', 'Show current blackboard state'],
+    ['clean [--stale | <path>]', 'Prune locks (surgical, stale, or nuke)'],
+    ['next <agent>', 'Suggest next safe task from queue'],
+    ['start [--agent @handle]', 'Orient an agent entering this repo'],
+    ['dashboard --serve [--port <port>]', 'Serve live local Nexus dashboard'],
+    ['metrics [--json]', 'Summarize commits, releases, and queue cost'],
+    ['ledger [--json|backfill]', 'Show or backfill completed task ledger'],
+    ['chmod [--list] [--init]', 'Show or set promptCHMOD permissions'],
+    ['db <backup|list|restore|schedule>', 'Database backup and recovery'],
+    ['drill <list|show|run|report>', 'Inspect or run protocol drills'],
+    ['soul [--file <path>] [--status | --remove]', 'Manage local soul overlay in agent files'],
+    ['help', 'Show this help'],
+  ];
 
-Usage: nexus <command> [options]
+  const examples = [
+    'nexus init',
+    'nexus doctor --fix',
+    'nexus doctor --json',
+    'nexus completion zsh',
+    'nexus start',
+    'nexus dashboard --serve',
+    'nexus metrics --json',
+    'nexus ledger backfill',
+    'nexus drill show wrong-repo-push',
+    'nexus claim src/lib/components/login/ @claude "Building login UI"',
+    'nexus release src/lib/components/login/ "feat: login form component"',
+    'nexus standup "2026-06-01 08:38 AM @codex [DONE]: Updated tests"',
+    'nexus clean --stale',
+    'nexus next @claude',
+  ];
 
-Commands:
-  init                              Scaffold Nexus files into current repo
-  doctor [--fix] [--json]           Check or repair agent protocol files
-  checkin <agent>                   Signal agent presence (heartbeat)
-  checkout [--all] <agent>          Signal session end or cleanup
-  claim <path> <agent> "<intent>"   Lock a file or directory
-                                    Also accepts --agent and --intent
-  release <path> "<commit msg>"     Unlock, auto-commit, and log
-  standup "<dated message>"          Append a validated standup line
-  status                            Show current blackboard state
-  clean [--stale | <path>]          Prune locks (surgical, stale, or nuke)
-  next <agent>                      Suggest next safe task from queue
-  start [--agent @handle]           Orient an agent entering this repo
-  dashboard --serve [--port <port>]  Serve live local Nexus dashboard
-  metrics [--json]                   Summarize commits, releases, and queue cost
-  ledger [--json|backfill]           Show or backfill completed task ledger
-  chmod [--list] [--init]            Show or set promptCHMOD permissions
-  db <backup|list|restore|schedule>  Database backup and recovery
-  drill <list|show|run|report>       Inspect or run protocol drills
-  soul [--file <path>] [--status | --remove]
-                                    Manage local soul overlay in agent files
-  help                              Show this help
+  const width = Math.max(...commands.map(([left]) => left.length)) + 2;
+  const lines = [
+    '',
+    COLORS.bold(COLORS.cyan(`@inkobytes/nexus v${VERSION}`)),
+    COLORS.dim('Multi-agent coordination for shared repositories.'),
+    '',
+    COLORS.bold('Usage'),
+    `  ${COLORS.cyan('nexus')} ${COLORS.yellow('<command>')} ${COLORS.dim('[options]')}`,
+    '',
+    COLORS.bold('Commands'),
+    ...commands.map(([left, right]) => `  ${COLORS.cyan(left.padEnd(width))}${COLORS.dim(right)}`),
+    '',
+    COLORS.bold('Examples'),
+    ...examples.map((example) => `  ${colorizeInline(example)}`),
+    '',
+    COLORS.dim('Tip: load zsh completions with `source <(nexus completion zsh)` and pair it with zsh-syntax-highlighting for typed command color.'),
+    '',
+  ];
 
-Examples:
-  nexus init
-  nexus doctor --fix
-  nexus doctor --json
-  nexus start
-  nexus dashboard --serve
-  nexus metrics
-  nexus metrics --json
-  nexus ledger
-  nexus ledger --json
-  nexus ledger backfill
-  nexus drill list
-  nexus drill show wrong-repo-push
-  nexus drill run wrong-repo-push
-  nexus drill report
-  nexus soul
-  nexus claim src/lib/components/login/ @claude "Building login UI"
-  nexus release src/lib/components/login/ "feat: login form component"
-  nexus standup "2026-06-01 08:38 AM @codex [DONE]: Updated tests"
-  nexus clean --stale
-  nexus next @claude
-`);
+  console.log(lines.join('\n'));
+}
+
+function colorizeInline(value) {
+  return String(value)
+    .split(/(\s+)/)
+    .map((part, index) => {
+      if (/^\s+$/.test(part)) return part;
+      if (index === 0 && part === 'nexus') return COLORS.cyan(part);
+      if (part.startsWith('--')) return COLORS.blue(part);
+      if (part.startsWith('@')) return COLORS.green(part);
+      if (part.startsWith('"') || part.endsWith('"')) return COLORS.yellow(part);
+      return part;
+    })
+    .join('');
+}
+
+function createColors() {
+  const enabled = supportsColor();
+  const wrap = (open, close) => (value) => enabled ? `\u001b[${open}m${value}\u001b[${close}m` : String(value);
+  return {
+    bold: wrap(1, 22),
+    dim: wrap(2, 22),
+    red: wrap(31, 39),
+    green: wrap(32, 39),
+    yellow: wrap(33, 39),
+    blue: wrap(34, 39),
+    cyan: wrap(36, 39),
+  };
+}
+
+function supportsColor() {
+  if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== '0') return true;
+  if ('NO_COLOR' in process.env) return false;
+  return Boolean(process.stdout && process.stdout.isTTY);
 }

package/nexus-dashboard/docs/index.html

@@ -50,115 +50,97 @@
         <div class="docs-layout">
           <section class="docs-main">
             <h2><span data-icon="file-text"></span>Commands</h2>
-            <div class="command-list">
-              <article class="command-card" id="checkin">
-                <h3><code>nexus checkin &lt;agent&gt;</code></h3>
-                <p>Writes an agent heartbeat so the dashboard can show online, idle, or offline presence.</p>
-              </article>
-              <article class="command-card" id="checkout">
-                <h3><code>nexus checkout [--all] &lt;agent&gt;</code></h3>
-                <p>Marks an agent session as ended, or clears all presence records during emergency cleanup.</p>
-              </article>
-              <article class="command-card" id="chmod">
-                <h3><code>nexus chmod [--list] [--init]</code></h3>
-                <p>Shows or initializes promptCHMOD permissions for agent-safe file access conventions.</p>
-              </article>
-              <article class="command-card" id="claim">
-                <h3><code>nexus claim &lt;path&gt; &lt;agent&gt; "&lt;intent&gt;"</code></h3>
-                <p>Locks a file or directory before edits so other agents can see ownership and intent. Also accepts <code>--agent &lt;agent&gt;</code> and <code>--intent "&lt;intent&gt;"</code>. Warns when agent, intent, or model metadata is missing.</p>
-              </article>
-              <article class="command-card" id="clean">
-                <h3><code>nexus clean [--stale | &lt;path&gt;]</code></h3>
-                <p>Prunes locks surgically, by stale age, or by explicit target when cleanup is needed.</p>
-              </article>
-              <article class="command-card" id="dashboard">
-                <h3><code>nexus dashboard --serve [--port &lt;port&gt;]</code></h3>
-                <p>Serves the local dashboard with claims, queue state, metrics, ledger history, and report views.</p>
-              </article>
-              <article class="command-card" id="db">
-                <h3><code>nexus db &lt;backup|list|restore|schedule&gt;</code></h3>
-                <p>Runs database backup and recovery helpers for repo-local protection workflows.</p>
-              </article>
-              <article class="command-card" id="doctor">
-                <h3><code>nexus doctor [--fix] [--json]</code></h3>
-                <p>Checks protocol files, private-path safety, and repo health; can repair known protocol drift.</p>
-              </article>
-              <article class="command-card" id="drill">
-                <h3><code>nexus drill &lt;list|show|run|report&gt;</code></h3>
-                <p>Inspects or runs protocol drills and summarizes the latest drill results.</p>
-              </article>
-              <article class="command-card" id="help">
-                <h3><code>nexus help</code></h3>
-                <p>Prints the CLI command list, examples, and usage syntax.</p>
-              </article>
-              <article class="command-card" id="init">
-                <h3><code>nexus init</code></h3>
-                <p>Scaffolds Nexus coordination files into the current repository.</p>
-              </article>
-              <article class="command-card" id="ledger">
-                <h3><code>nexus ledger [--json|backfill]</code></h3>
-                <p>Shows or backfills the completed-task ledger that powers dashboard history and charts.</p>
-              </article>
-              <article class="command-card" id="metrics">
-                <h3><code>nexus metrics [--json]</code></h3>
-                <p>Summarizes commits, release activity, queue cost, and agent attribution.</p>
-              </article>
-              <article class="command-card" id="next">
-                <h3><code>nexus next &lt;agent&gt;</code></h3>
-                <p>Suggests the next safe ready task for an agent from the queue.</p>
-              </article>
-              <article class="command-card" id="release">
-                <h3><code>nexus release &lt;path&gt; "&lt;commit msg&gt;"</code></h3>
-                <p>Releases a claim, stages and commits the target, and appends a Nexus report receipt.</p>
-              </article>
-              <article class="command-card" id="soul">
-                <h3><code>nexus soul [--file &lt;path&gt;] [--status | --remove]</code></h3>
-                <p>Manages local soul overlays in agent files without making them part of public docs.</p>
-              </article>
-              <article class="command-card" id="standup">
-                <h3><code>nexus standup "YYYY-MM-DD HH:MM AM/PM @agent [STATUS]: message"</code></h3>
-                <p>Appends a standup line only after validating the agent handle, date/time, status, and message.</p>
-              </article>
-              <article class="command-card" id="start">
-                <h3><code>nexus start [--agent @handle]</code></h3>
-                <p>Orients an entering agent with repo facts, scoped memory paths, locks, and current status.</p>
-              </article>
-              <article class="command-card" id="status">
-                <h3><code>nexus status</code></h3>
-                <p>Shows the current Nexus blackboard state, active locks, and coordination context.</p>
-              </article>
-            </div>
+            <div id="command-list" class="command-list"></div>
           </section>
 
           <aside class="docs-toc" aria-label="Command table of contents">
             <h2><span data-icon="list-checks"></span>Commands</h2>
-            <nav>
-              <a href="#checkin">checkin</a>
-              <a href="#checkout">checkout</a>
-              <a href="#chmod">chmod</a>
-              <a href="#claim">claim</a>
-              <a href="#clean">clean</a>
-              <a href="#dashboard">dashboard</a>
-              <a href="#db">db</a>
-              <a href="#doctor">doctor</a>
-              <a href="#drill">drill</a>
-              <a href="#help">help</a>
-              <a href="#init">init</a>
-              <a href="#ledger">ledger</a>
-              <a href="#metrics">metrics</a>
-              <a href="#next">next</a>
-              <a href="#release">release</a>
-              <a href="#soul">soul</a>
-              <a href="#standup">standup</a>
-              <a href="#start">start</a>
-              <a href="#status">status</a>
-            </nav>
+            <nav id="docs-toc-nav"></nav>
           </aside>
         </div>
       </main>
     </div>
 
     <script>
+      const COMMANDS = [
+        { id: 'checkin', name: 'checkin', syntax: 'nexus checkin <agent>', summary: 'Writes an agent heartbeat so the dashboard can show online, idle, or offline presence.', example: 'nexus checkin @codex', tags: ['presence', 'heartbeat'] },
+        { id: 'checkout', name: 'checkout', syntax: 'nexus checkout [--all] <agent>', summary: 'Marks an agent session as ended, or clears all presence records during emergency cleanup.', example: 'nexus checkout @codex', tags: ['presence', 'cleanup'] },
+        { id: 'chmod', name: 'chmod', syntax: 'nexus chmod [--list] [--init]', summary: 'Shows or initializes promptCHMOD permissions for agent-safe file access conventions.', example: 'nexus chmod --list', tags: ['permissions', 'setup'] },
+        { id: 'completion', name: 'completion', syntax: 'nexus completion zsh', summary: 'Prints a zsh completion script so Nexus commands and agent handles tab-complete in your shell.', example: 'source <(nexus completion zsh)', tags: ['shell', 'completion'] },
+        { id: 'claim', name: 'claim', syntax: 'nexus claim <path> <agent> "<intent>"', summary: 'Locks a file or directory before edits so other agents can see ownership and intent. Also accepts --agent and --intent.', example: 'nexus claim src/commands/dashboard.js @codex "Polish report chart UI"', tags: ['lock', 'ownership', 'before editing'] },
+        { id: 'clean', name: 'clean', syntax: 'nexus clean [--stale | <path>]', summary: 'Prunes locks surgically, by stale age, or by explicit target when cleanup is needed.', example: 'nexus clean --stale', tags: ['locks', 'cleanup'] },
+        { id: 'dashboard', name: 'dashboard', syntax: 'nexus dashboard --serve [--port <port>]', summary: 'Serves the local dashboard with claims, queue state, metrics, ledger history, and report views.', example: 'nexus dashboard --serve --port 13787', tags: ['dashboard', 'local UI'] },
+        { id: 'db', name: 'db', syntax: 'nexus db <backup|list|restore|schedule>', summary: 'Runs database backup and recovery helpers for repo-local protection workflows.', example: 'nexus db backup', tags: ['database', 'safety'] },
+        { id: 'doctor', name: 'doctor', syntax: 'nexus doctor [--fix] [--json]', summary: 'Checks protocol files, private-path safety, and repo health; can repair known protocol drift.', example: 'nexus doctor --fix', tags: ['health', 'repair'] },
+        { id: 'drill', name: 'drill', syntax: 'nexus drill <list|show|run|report>', summary: 'Inspects or runs protocol drills and summarizes the latest drill results.', example: 'nexus drill show wrong-repo-push', tags: ['guidance', 'playbooks'] },
+        { id: 'help', name: 'help', syntax: 'nexus help', summary: 'Prints the CLI command list, examples, and usage syntax.', example: 'nexus help', tags: ['reference'] },
+        { id: 'init', name: 'init', syntax: 'nexus init', summary: 'Scaffolds Nexus coordination files into the current repository.', example: 'nexus init', tags: ['setup'] },
+        { id: 'ledger', name: 'ledger', syntax: 'nexus ledger [--json|backfill]', summary: 'Shows or backfills the completed-task ledger that powers dashboard history and charts.', example: 'nexus ledger backfill', tags: ['history', 'analytics'] },
+        { id: 'metrics', name: 'metrics', syntax: 'nexus metrics [--json]', summary: 'Summarizes commits, release activity, queue cost, and agent attribution.', example: 'nexus metrics --json', tags: ['metrics', 'reporting'] },
+        { id: 'next', name: 'next', syntax: 'nexus next <agent>', summary: 'Suggests the next safe ready task for an agent from the queue.', example: 'nexus next @codex', tags: ['queue', 'routing'] },
+        { id: 'release', name: 'release', syntax: 'nexus release <path> "<commit msg>"', summary: 'Releases a claim, stages and commits the target, and appends a Nexus report receipt.', example: 'nexus release src/commands/dashboard.js "feat: improve docs command cards"', tags: ['release', 'commit'] },
+        { id: 'soul', name: 'soul', syntax: 'nexus soul [--file <path>] [--status | --remove]', summary: 'Manages local soul overlays in agent files without making them part of public docs.', example: 'nexus soul --status', tags: ['local-only', 'agent files'] },
+        { id: 'standup', name: 'standup', syntax: 'nexus standup "YYYY-MM-DD HH:MM AM/PM @agent [STATUS]: message"', summary: 'Appends a standup line only after validating the agent handle, date/time, status, and message.', example: 'nexus standup "2026-06-01 08:38 AM @codex [DONE]: Updated tests"', tags: ['comms', 'validated format'] },
+        { id: 'start', name: 'start', syntax: 'nexus start [--agent @handle]', summary: 'Orients an entering agent with repo facts, scoped memory paths, locks, and current status.', example: 'nexus start --agent @codex', tags: ['onboarding', 'context'] },
+        { id: 'status', name: 'status', syntax: 'nexus status', summary: 'Shows the current Nexus blackboard state, active locks, and coordination context.', example: 'nexus status', tags: ['snapshot'] },
+      ];
+
+      function renderDocs() {
+        document.getElementById('command-list').innerHTML = COMMANDS.map(renderCommandCard).join('');
+        document.getElementById('docs-toc-nav').innerHTML = COMMANDS.map((command) =>
+          '<a href="#' + command.id + '">' + command.name + '</a>'
+        ).join('');
+      }
+
+      function renderCommandCard(command) {
+        return '<article class="command-card" id="' + command.id + '">'
+          + '<div class="command-card-top">'
+          + '<div class="command-name">' + escapeHtml(command.name) + '</div>'
+          + '<div class="command-tags">' + command.tags.map(renderTag).join('') + '</div>'
+          + '</div>'
+          + '<h3>' + renderCommandSyntax(command.syntax) + '</h3>'
+          + '<p>' + escapeHtml(command.summary) + '</p>'
+          + '<div class="command-example-label">Example</div>'
+          + '<pre class="command-example"><code>' + renderCommandSyntax(command.example) + '</code></pre>'
+          + '</article>';
+      }
+
+      function renderTag(tag) {
+        return '<span class="command-tag">' + escapeHtml(tag) + '</span>';
+      }
+
+      function renderCommandSyntax(value) {
+        const pattern = /(".*?"|--[a-z-]+|@[a-z0-9_-]+|<[^>]+>|\[[^\]]+\]|\bnexus\b)/gi;
+        let html = '';
+        let cursor = 0;
+        const source = String(value || '');
+
+        for (const match of source.matchAll(pattern)) {
+          const token = match[0];
+          const index = match.index || 0;
+          if (index > cursor) html += escapeHtml(source.slice(cursor, index));
+          html += wrapCommandToken(token);
+          cursor = index + token.length;
+        }
+
+        if (cursor < source.length) html += escapeHtml(source.slice(cursor));
+        return html;
+      }
+
+      function wrapCommandToken(token) {
+        const escaped = escapeHtml(token);
+        if (token === 'nexus') return '<span class="token-cli">' + escaped + '</span>';
+        if (token.startsWith('--')) return '<span class="token-flag">' + escaped + '</span>';
+        if (token.startsWith('@')) return '<span class="token-agent">' + escaped + '</span>';
+        if (token.startsWith('"')) return '<span class="token-string">' + escaped + '</span>';
+        if (token.startsWith('<') || token.startsWith('[')) return '<span class="token-arg">' + escaped + '</span>';
+        return escaped;
+      }
+
+      function escapeHtml(value) {
+        return String(value).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+      }
+
       function renderIcons() {
         const icons = {
           activity: '<polyline points="22 12 18 12 15 21 9 3 6 12 2 12"></polyline>',
@@ -177,6 +159,7 @@
           node.innerHTML = '<svg class="icon" viewBox="0 0 24 24" aria-hidden="true">' + (icons[name] || '') + '</svg>';
         });
       }
+      renderDocs();
       renderIcons();
     </script>
   </body>