@nex-ai/nex 0.1.65 → 0.2.1

package/README.md

@@ -1,360 +1,287 @@
-# Nex: Compounding Intelligence for AI agents
+# Nex: Compounding Intelligence for AI Agents
 
 [![npm version](https://img.shields.io/npm/v/@nex-ai/nex)](https://www.npmjs.com/package/@nex-ai/nex)
-[![GitHub](https://img.shields.io/badge/github-nex--crm%2Fnex--as--a--skill-blue)](https://github.com/nex-crm/nex-as-a-skill)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?logo=discord&logoColor=white)](https://discord.gg/gjSySC3PzV)
 
-Turn all your AI agent conversations into a unified knowledge graph with proactive context surfacing. Supports Claude Code, Codex, OpenClaw, Cursor, OpenCode, etc. Adds additional context from Email, Meetings, Slack, HubSpot, Salesforce.
+Nex turns AI agent conversations into a unified knowledge graph. Tell something to one agent, recall it from any other. Context follows you across tools — no copy-pasting, no re-explaining.
+
+Supports Claude Code, OpenClaw, Cursor, Windsurf, Codex, Aider, Continue, Zed, and more. Adds context from Email, Meetings, Slack, HubSpot, Salesforce.
 
 <a href="https://discord.gg/gjSySC3PzV"><img src="https://img.shields.io/badge/Join%20our%20Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join our Discord" /></a>
 
 Talk to the team, share feedback, and connect with other developers building AI agents with Nex.
 
-**GitHub**: [github.com/nex-crm/nex-as-a-skill](https://github.com/nex-crm/nex-as-a-skill)
-
-## Install
-
-```bash
-# Install globally
-npm install -g @nex-ai/nex
-
-# Or run directly (no install)
-npx @nex-ai/nex ask "who is Maria?"
-```
-
-## Quick Start (Recommended)
+## Quick Start
 
-```bash
-# One command to get started — registers, detects platforms, installs hooks, scans files
-nex setup
-```
-
-`nex setup` handles the base install flow: API key registration or re-keying, platform detection, platform installation, optional first integration connection, file scanning, and config creation.
+### Install
 
 ```bash
-# Now query your knowledge
-nex ask "what's the latest on the Acme deal?"
-```
-
-## Copy-Paste Prompt For Any AI Agent
+# Option A: standalone binary (no Node.js required, auto-installs nex-cli)
+curl -fsSL https://raw.githubusercontent.com/nex-crm/nex-as-a-skill/main/install.sh | sh
 
-Use this when you want Claude, Codex, Cursor, OpenCode, or another terminal-capable AI agent to do the full Nex bootstrap for you.
-
-```text
-Install and fully bootstrap Nex in this project from start to finish.
-
-1. If the `nex` CLI is missing, install it globally with `npm install -g @nex-ai/nex`.
-2. If Nex is not authenticated yet, ask me for the email address I want to use for registration, then continue. If Nex is already authenticated, reuse the existing account and key.
-3. Run `nex setup` and complete the full install flow for every detected AI coding platform in this environment.
-4. After setup, inspect integrations and connect the first available unconnected integration. Prefer this order when multiple choices are available: gmail, google-calendar, slack, salesforce, hubspot, attio, outlook, outlook-calendar. If OAuth is required, open the browser flow and wait for it to complete.
-5. Run a fresh file scan for the current directory so the workspace is up to date.
-6. After the scan finishes, trigger Nex compounding jobs by calling the authenticated `POST https://app.nex.ai/api/developers/v1/compounding/trigger` endpoint for these job types: `consolidation`, `pattern_detection`, and `playbook_synthesis`. Use the active Nex API key from the current environment or the config written by Nex setup.
-7. Fetch the last 24 hours of insights with the insights endpoint or `nex insight list --last 24h`, then give me a clean digest with sections for Highlights, Risks, Opportunities, Open Loops, and Recommended Next Actions.
-8. Finish by showing me:
-   - what Nex installed
-   - which integration was connected
-   - how many files were scanned and ingested
-   - whether the compounding/playbooks trigger succeeded
-   - the formatted 24-hour insight digest
+# Option B: install the nex-cli binary directly
+curl -fsSL https://raw.githubusercontent.com/nex-crm/nex-cli/main/install.sh | sh
 
-Do not stop after partial setup. Only pause if you need my email for registration or if an OAuth flow requires my interaction.
+# Option C: install via npm (or bun/pnpm)
+npm install -g @nex-ai/nex
 ```
 
-This works best in agents that can run shell commands and open OAuth URLs.
-
-<details>
-<summary>Manual setup (if you prefer step-by-step)</summary>
+### Sign up and configure
 
 ```bash
-# 1. Register for an API key
+# Create an account (or log in if you already have one)
 nex register --email you@company.com
 
-# 2. Set up your platforms (auto-detects installed tools)
+# Auto-detect your AI platforms and install hooks, MCP, slash commands
 nex setup
-
-# 3. Query your knowledge
-nex ask "what's the latest on the Acme deal?"
-```
-
-</details>
-
-## Supported Platforms
-
-`nex setup` auto-detects and configures these platforms with full-depth integration:
-
-| Platform | Hooks | Plugins | Agents | Workflows | Rules | MCP |
-|----------|-------|---------|--------|-----------|-------|-----|
-| **Claude Code** | SessionStart, UserPromptSubmit, Stop | — | — | 26 slash commands | — | — |
-| **Cursor** | sessionStart, userPromptSubmit, stop | — | — | — | `.cursor/rules/nex.md` | `~/.cursor/mcp.json` |
-| **Windsurf** | pre_user_prompt, post_cascade_response | — | — | /nex-ask, /nex-remember, /nex-search | `.windsurf/rules/nex.md` | `mcp_config.json` |
-| **Cline** | UserPromptSubmit, TaskStart, TaskComplete | — | — | — | `.clinerules/nex.md` | `cline_mcp_settings.json` |
-| **OpenClaw** | auto-recall, auto-capture (plugin) | `openclaw plugins install` (49 tools) | — | — | — | — |
-| **OpenCode** | — | `.opencode/plugins/nex.ts` | — | — | `AGENTS.md` | `opencode.json` |
-| **VS Code** | — | — | `.github/agents/nex.agent.md` | — | `.github/instructions/` | `.vscode/mcp.json` |
-| **Kilo Code** | — | — | `.kilocodemodes` | — | `.kilocode/rules/nex.md` | `.kilocode/mcp.json` |
-| **Continue.dev** | — | — | — | — | `.continue/rules/nex.md` | `mcp.json` |
-| **Zed** | — | — | — | — | `.rules` | `settings.json` |
-| **Claude Desktop** | — | — | — | — | — | `claude_desktop_config.json` |
-| **Aider** | — | — | — | — | `CONVENTIONS.md` | — |
-
-All MCP-based platforms use the same server entry (bundled in this package):
-
-```json
-{
-  "nex": {
-    "command": "nex-mcp",
-    "env": { "NEX_API_KEY": "sk-..." }
-  }
-}
 ```
 
-Or without a global install: `"command": "npx", "args": ["-y", "@nex-ai/nex", "mcp"]`
-
-## Setup Command
+`nex setup` detects your platforms (Claude Code, Cursor, Windsurf, etc.), installs hooks, scans project files, and writes config. After setup:
 
 ```bash
-nex setup                          # Auto-detect platforms, install full stack, scan files, create .nex.toml
-nex setup --platform cursor        # Install for a specific platform only
-nex setup --no-hooks               # Skip hook installation for all platforms
-nex setup --no-plugin              # Skip hooks/commands (alias for --no-hooks)
-nex setup --no-rules               # Skip rules/instruction file installation
-nex setup --no-scan                # Skip file scanning during setup
-nex setup status                   # Show all platforms, install status, and connections
-nex graph                          # Open the workspace graph in your browser
+nex ask "who is Maria Rodriguez?"
+nex remember "Met with Maria, CTO of TechFlow. European expansion Q3, $2M budget."
 ```
 
-**Default behavior** (no flags):
-- If no API key exists: prompts to register
-- If API key exists: offers to regenerate (picks up latest scopes) or change email
-- Installs the full 6-layer hierarchy for each detected platform: hooks → plugins → agents → workflows → rules → MCP
-- Scans current directory and ingests new/changed files into Nex
-- Creates `.nex.toml` project config with commented defaults
-- Stores config in `~/.nex/config.json`
-
-**Single install**: `npm install -g @nex-ai/nex` bundles everything — hooks, adapters, platform plugins, slash commands, rules, MCP server, and notification channel. No separate packages needed.
+## Skills & Platform Rules
 
-**Integration hierarchy** (per platform): Hooks > Custom plugins > Custom agents/modes > Workflows > Rules > MCP. Each platform gets every layer it supports.
+The core of this repo is a set of skills, slash commands, and agent instructions that teach any AI platform how to use Nex.
 
-## Project Config: `.nex.toml`
+### Slash Commands (`plugin-commands/`)
 
-Per-project settings file created by `nex setup`. All fields are optional.
+Drop these `.md` files into your agent's commands directory to get Nex slash commands:
 
-```toml
-[auth]
-# api_key = "sk-..."          # Prefer NEX_API_KEY env var or ~/.nex/config.json
+| Command | What it does |
+|---------|-------------|
+| `/nex:recall <query>` | Search your knowledge base |
+| `/nex:remember <text>` | Store information for later recall |
+| `/nex:entities <query>` | Find people, companies, topics |
+| `/nex:scan <dir>` | Scan project files into Nex |
+| `/nex:integrate <provider>` | Connect an OAuth integration |
+| `/nex:register <email>` | One-time account registration |
+| `/nex:notify` | Check recent notifications |
 
-[hooks]
-# enabled = true              # Master kill switch for all hooks
+For Claude Code: `cp plugin-commands/*.md ~/.claude/commands/`
 
-[hooks.recall]
-# enabled = true              # Proactive context on every prompt
-# debounce_ms = 10000
+### Platform Rules (`platform-rules/`)
 
-[hooks.capture]
-# enabled = true              # Auto-capture on conversation stop
-# min_length = 20
-# max_length = 50000
+Pre-written agent instructions that teach each platform how to use Nex tools. Copy the relevant file into your editor's config:
 
-[hooks.session_start]
-# enabled = true              # Load context on session start
+| Platform | File | Destination |
+|----------|------|-------------|
+| Cursor | `cursor-rules.md` | `.cursor/rules/` |
+| Windsurf | `windsurf-rules.md` | `.windsurf/rules/` |
+| GitHub Copilot | `vscode-instructions.md` | `.github/instructions/` |
+| Zed | `zed-rules.md` | `.zed/rules/` |
+| Aider | `aider-conventions.md` | `.aider/conventions/` |
+| Cline | `cline-rules.md` | `.cline/rules/` |
+| Continue | `continue-rules.md` | `.continue/rules/` |
+| KiloCode | `kilocode-rules.md` | `.kilocode/rules/` |
+| Codex | `codex-agents.md` | `.codex/agents/` |
+| OpenCode | `opencode-agents.md` | `.opencode/agents/` |
 
-[scan]
-# enabled = true
-# extensions = [".md", ".txt", ".csv", ".json", ".yaml", ".yml"]
-# ignore_dirs = ["node_modules", ".git", "dist", "build", "__pycache__"]
-# max_files = 1000
-# max_file_size = 100000
-# depth = 2
+### Platform Plugins (`platform-plugins/`)
 
-[mcp]
-# enabled = false             # Set to true when `nex setup` installs MCP for this project/platform
+Deeper integrations for editors that support plugin APIs:
 
-[output]
-# format = "text"             # "text" | "json"
-# timeout = 120000
-```
+- **Continue** (`continue-provider.ts`) — Nex as a context provider for autocomplete
+- **OpenCode** (`opencode-plugin.ts`) — Session lifecycle hooks for context preservation
+- **KiloCode** (`kilocode-modes.yaml`) — Nex memory mode definitions
+- **Windsurf** (`windsurf-workflows/`) — Native workflow definitions for ask, remember, search, notify
 
-**Resolution order:** CLI flags > `.nex.toml` > env vars > `~/.nex/config.json` > defaults
+## Plugins
 
-## Commands
+### Claude Code Plugin
 
-### Knowledge Graph
+Full auto-recall and auto-capture via Claude Code hooks. Queries Nex before each prompt and captures conversation facts after each response.
 
 ```bash
-nex ask <query>              # Query with natural language
-nex remember <content>       # Ingest text (meeting notes, emails, docs)
-nex recall <query>           # Query → XML-wrapped for agent injection
-nex capture [content]        # Rate-limited ingestion for agent hooks
-nex artifact <id>            # Check processing status
-nex search <query>           # Search CRM records by name
-nex insight list [--last 24h]  # Recent insights
-nex graph                    # Visualize your workspace graph in the browser
+cd claude-code-plugin && bun install && bun run build
 ```
 
-### Integrations
+Then add hooks to `~/.claude/settings.json` (see [`settings.json`](claude-code-plugin/settings.json) for the template) and register the MCP server:
 
 ```bash
-nex integrate list                  # Show all integrations with connection status
-nex integrate connect gmail         # Connect Gmail via OAuth
-nex integrate connect slack         # Connect Slack
-nex integrate disconnect <id>      # Disconnect by connection ID
+cp claude-code-plugin/commands/*.md ~/.claude/commands/
+claude mcp add nex -- nex-mcp
 ```
 
-Available integrations: `gmail`, `google-calendar`, `outlook`, `outlook-calendar`, `slack`, `salesforce`, `hubspot`, `attio`.
+The fastest path is just `nex setup` — it does all of this automatically.
 
-### CRM Records
+See [`claude-code-plugin/README.md`](claude-code-plugin/README.md) for details.
 
-```bash
-nex object list              # List object types (person, company, deal)
-nex record list person --limit 10
-nex record create person --data '{"name":"Jane Doe"}'
-nex record upsert person --match email --data '{"name":"Jane","email":"jane@co.com"}'
-nex record update <id> --data '{"phone":"+1234"}'
-nex record delete <id>
-nex record timeline <id>
-```
+### OpenClaw Plugin
 
-### Tasks & Notes
+15+ tools, auto-recall, and auto-capture for OpenClaw agents.
 
 ```bash
-nex task create --title "Follow up" --priority high --due 2026-04-01
-nex task list --assignee me --search "follow up"
-nex task update <id> --completed
-nex note create --title "Call notes" --content "..." --entity <record-id>
+cp -r openclaw-plugin /path/to/openclaw/plugins/nex
+cd /path/to/openclaw/plugins/nex && bun install && bun run build
 ```
 
-### Relationships & Lists
+Add to `openclaw.json`:
 
-```bash
-nex rel list-defs
-nex rel create <record-id> --def <def-id> --entity1 <id1> --entity2 <id2>
-nex list list person
-nex list add-member <list-id> --parent <record-id>
-nex list-job create "enterprise contacts in EMEA"
+```json
+{
+  "plugins": {
+    "load": { "paths": ["/path/to/plugins/nex"] },
+    "slots": { "memory": "nex" },
+    "entries": {
+      "nex": {
+        "enabled": true,
+        "config": { "apiKey": "sk-your_key_here" }
+      }
+    }
+  }
+}
 ```
 
-### File Scanning
+See [`openclaw-plugin/README.md`](openclaw-plugin/README.md) for details.
 
-On session start, Nex automatically scans project files and ingests changed content using concurrent workers (5 parallel requests). After ingestion, compounding intelligence jobs are triggered automatically to generate patterns and playbook rules.
+### MCP Server (Claude Desktop, Cursor, Windsurf)
 
-```bash
-nex scan                    # Scan current directory (up to 1000 files)
-nex scan --max-files 500    # Limit files per scan
-nex scan --force            # Re-scan all files (ignore manifest)
-nex scan --dry-run          # Preview what would be scanned
+```json
+{
+  "mcpServers": {
+    "nex": {
+      "command": "nex-mcp",
+      "env": { "NEX_API_KEY": "sk-your_key_here" }
+    }
+  }
+}
 ```
 
-**Default text-based extensions:** `.md`, `.txt`, `.csv`, `.json`, `.yaml`, `.yml`
+Or without a global install:
 
-**Document formats** (handled separately): `.docx`, `.doc`, `.odt`, `.xlsx`, `.xls`, `.pptx`, `.ppt`, `.pdf`
+```json
+{
+  "mcpServers": {
+    "nex": {
+      "command": "npx",
+      "args": ["-y", "@nex-ai/nex", "mcp"],
+      "env": { "NEX_API_KEY": "sk-your_key_here" }
+    }
+  }
+}
+```
 
-Configure via `.nex.toml` `[scan]` section or environment variables (`NEX_SCAN_ENABLED`, `NEX_SCAN_EXTENSIONS`, etc.).
+### Shell-only Agents (no Node.js)
 
-### Proactive Context
+Bash scripts for agents that can only run shell commands. Requires `curl` and `jq`.
 
-Nex surfaces relevant knowledge graph context on every prompt — not just questions. When you say "fix the migration script" or "deploy to staging", the system automatically injects entity insights, knowledge insights, and playbook patterns from your knowledge graph.
+```bash
+bash scripts/nex-openclaw-register.sh your@email.com "Your Name"
+printf '{"query":"who is Maria?"}' | bash scripts/nex-api.sh POST /v1/context/ask
+bash scripts/nex-scan-files.sh --dir . --max-files 10
+```
 
-Context is injected as `<nex-context>` blocks that AI agents use naturally without explicitly referencing the source. Only trivial inputs (yes/ok/lgtm) are skipped.
+## Copy-Paste Bootstrap Prompt
 
-### Transcript Capture
+Drop this into any terminal-capable AI agent to bootstrap Nex end-to-end:
 
-At session end, the full conversation transcript is automatically ingested into the knowledge graph. This captures complete decision trails, code discussions, and debugging sessions — not just the last message.
+```text
+Install and fully bootstrap Nex in this project from start to finish.
 
-### MCP Server & Notifications
+1. If the `nex` CLI is missing, install it globally with `npm install -g @nex-ai/nex`.
+2. If Nex is not authenticated yet, ask me for the email address I want to use for registration, then continue. If Nex is already authenticated, reuse the existing account and key.
+3. Run `nex setup` and complete the full install flow for every detected AI coding platform in this environment.
+4. After setup, inspect integrations and connect the first available unconnected integration. Prefer this order when multiple choices are available: gmail, google-calendar, slack, salesforce, hubspot, attio, outlook, outlook-calendar. If OAuth is required, open the browser flow and wait for it to complete.
+5. Run a fresh file scan for the current directory so the workspace is up to date.
+6. After the scan finishes, trigger Nex compounding jobs by calling the authenticated `POST https://app.nex.ai/api/developers/v1/compounding/trigger` endpoint for these job types: `consolidation`, `pattern_detection`, and `playbook_synthesis`. Use the active Nex API key from the current environment or the config written by Nex setup.
+7. Fetch the last 24 hours of insights with the insights endpoint or `nex insight list --last 24h`, then give me a clean digest with sections for Highlights, Risks, Opportunities, Open Loops, and Recommended Next Actions.
+8. Finish by showing me:
+   - what Nex installed
+   - which integration was connected
+   - how many files were scanned and ingested
+   - whether the compounding/playbooks trigger succeeded
+   - the formatted 24-hour insight digest
 
-```bash
-nex mcp                         # Start the embedded MCP server (stdio)
-MCP_TRANSPORT=http nex mcp      # Start with HTTP transport
+Do not stop after partial setup. Only pause if you need my email for registration or if an OAuth flow requires my interaction.
 ```
 
-#### Proactive Notifications (Claude Code Channels)
-
-The MCP server pushes context updates directly into your Claude Code session using the [Channels API](https://code.claude.com/docs/en/channels-reference). No polling commands needed — insights arrive automatically while you work.
+## Development
 
-**Two notification types:**
+### Repo structure
 
-- **Daily digest** — Comprehensive summary of all context collected in the last 24 hours (deal changes, new relationships, upcoming events, actionable items). Fires once per day on session start.
-- **Proactive alerts** — New insights pushed every 15 minutes: relationship changes, deal updates, risks, opportunities. Configurable via `NEX_NOTIFY_INTERVAL_MINUTES`.
+```text
+src/                    # Bootstrapper binary source (compiled via Bun)
+bin/                    # Thin Node.js shims that delegate to nex-cli (npm fallback)
+install.sh              # curl-pipe installer for the standalone binary
+claude-code-plugin/     # Claude Code hooks (auto-recall, auto-capture)
+openclaw-plugin/        # OpenClaw plugin (15+ tools, auto-recall, auto-capture)
+plugin-commands/        # Slash command definitions (.md files)
+platform-rules/         # Agent instructions for 10 platforms
+platform-plugins/       # Editor integrations (Continue, OpenCode, KiloCode, Windsurf)
+scripts/                # Bash API wrappers for shell-only agents
+server.json             # MCP Registry manifest
+```
 
-**Quick setup:**
+### Build and test
 
 ```bash
-# 1. Add MCP server to your project
-cat > .mcp.json << 'EOF'
-{
-  "mcpServers": {
-    "nex": { "command": "nex-mcp", "env": {} }
-  }
-}
-EOF
-
-# 2. Start Claude Code with channels
-claude --dangerously-load-development-channels server:nex
-```
+# Standalone binary (compiles via Bun)
+bun run build:binary            # native platform
+bun run build:all               # all 4 targets (darwin/linux × arm64/x64)
 
-Notifications appear as `<channel source="nex">` events in your session. Claude reads them automatically and incorporates the context.
+# Shims (syntax check only)
+npm test
 
-**Customize frequency:**
+# Claude Code plugin
+cd claude-code-plugin && bun install && bun run build && bun test
 
-```json
-{
-  "mcpServers": {
-    "nex": {
-      "command": "nex-mcp",
-      "env": { "NEX_NOTIFY_INTERVAL_MINUTES": "5" }
-    }
-  }
-}
+# OpenClaw plugin
+cd openclaw-plugin && bun install && bun run build && bun test
 ```
 
-**Force a fresh digest:** `rm ~/.nex/channel-state.json`
+### How it works
 
-**Requirements:** Claude Code v2.1.80+, claude.ai login, `--dangerously-load-development-channels` during research preview.
+**Standalone binary** (`src/nex.ts`): Compiled via `bun build --compile`. Finds `nex-cli` on PATH or common locations and delegates all commands. If `nex-cli` isn't installed, auto-downloads it on first run. Detects `nex-mcp` symlink invocation to transparently prepend `mcp` to args.
 
-### Config & Sessions
+**npm package** (`bin/nex.js`): Thin Node.js shim with the same delegation logic, for `npx @nex-ai/nex` and MCP Registry compatibility.
 
-```bash
-nex config show              # Resolved config (key masked)
-nex config set default_format text
-nex config path              # ~/.nex/config.json
-nex session list             # Stored session mappings
-nex session clear
-```
+### CI/CD
 
-## Global Flags
+- **CI** (`ci.yml`): Validates shims, builds + tests both plugins, builds + smoke tests the binary on every PR
+- **Release** (`release.yml`): Cross-compiles 4 binary targets on `v*` tags, creates GitHub Release with checksums
+- **Publish** (`publish-cli.yml`): Auto-publishes to npm on push to main
+- **MCP Registry** (`publish-mcp.yml`): Publishes `server.json` to the MCP Registry on version tags
 
-```
---api-key <key>     Override API key (env: NEX_API_KEY)
---format <fmt>      json | text (default for integrate list) | quiet
---timeout <ms>      Request timeout (default: 120000)
---session <id>      Session ID for multi-turn context
---debug             Debug output on stderr
-```
+## Environment Variables
 
-## Stdin Support
+| Variable | Required | Default |
+|----------|----------|---------|
+| `NEX_API_KEY` | Yes (or register) | — |
+| `NEX_DEV_URL` | No (dev only) | `https://app.nex.ai` |
+| `NEX_SCAN_ENABLED` | No | `true` |
+| `NEX_SCAN_MAX_FILES` | No | `5` |
+| `NEX_SCAN_DEPTH` | No | `20` |
+| `NEX_NOTIFY_INTERVAL_MINUTES` | No | `15` |
 
-`ask`, `remember`, and `capture` read from stdin when no argument is provided:
+## Architecture
 
-```bash
-cat meeting-notes.txt | nex remember
-echo "what happened today?" | nex ask
-git diff | nex capture
-```
+```mermaid
+graph TD
+    API["Nex Context Graph<br/><i>app.nex.ai API</i>"]
+    CLI["nex-cli binary"]
 
-## Exit Codes
+    API --- CLI
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | General error (server error, rate limit, invalid input) |
-| 2 | Auth error (no API key, invalid key, 401/403) |
+    NEX["nex binary / npm shim"]
+    MCP["MCP Server<br/><i>nex-mcp</i>"]
+    OC["OpenClaw Plugin"]
+    CC["Claude Code Plugin"]
 
-## Development
+    CLI --- NEX
+    CLI --- MCP
+    CLI --- OC
+    CLI --- CC
 
-```bash
-bun install
-bun run build     # TypeScript → dist/
-bun run dev       # Run TS directly (no build)
-bun test          # Unit + integration tests
-NEX_DEV_URL=http://localhost:30000 nex ask "test"  # Local API
+    NEX -.- T1["Any terminal"]
+    MCP -.- T2["Claude Desktop · Cursor<br/>Windsurf · ChatGPT"]
+    OC -.- T3["OpenClaw agents"]
+    CC -.- T4["Claude Code"]
 ```
+
+## License
+
+MIT

package/bin/nex-mcp.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * Thin shim for nex-mcp — delegates to nex-cli mcp.
+ *
+ * This entry point exists for MCP registry compatibility.
+ * Platforms like Claude Desktop install MCP servers via: npx @nex-ai/nex
+ * which resolves to this shim, which delegates to the nex-cli binary.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+const args = ["mcp", ...process.argv.slice(2)];
+
+function tryExec(command, commandArgs) {
+  try {
+    execFileSync(command, commandArgs, { stdio: "inherit" });
+    return true;
+  } catch (err) {
+    if (err.status !== null && err.status !== undefined) {
+      process.exit(err.status);
+    }
+    return false;
+  }
+}
+
+if (tryExec("nex-cli", args)) {
+  process.exit(0);
+}
+
+const commonPaths = ["/usr/local/bin/nex-cli"];
+if (process.env.HOME) {
+  commonPaths.push(`${process.env.HOME}/.local/bin/nex-cli`);
+}
+for (const p of commonPaths) {
+  if (existsSync(p) && tryExec(p, args)) {
+    process.exit(0);
+  }
+}
+
+console.error(`
+  nex-cli binary not found.
+
+  Install it with:
+    curl -fsSL https://raw.githubusercontent.com/nex-crm/nex-cli/main/install.sh | sh
+
+  Then run your command again.
+`);
+process.exit(1);

package/bin/nex.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+
+/**
+ * Thin shim for @nex-ai/nex — delegates all commands to the nex-cli binary.
+ *
+ * Install the binary: curl -fsSL https://raw.githubusercontent.com/nex-crm/nex-cli/main/install.sh | sh
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+const args = process.argv.slice(2);
+
+// Try nex-cli on PATH first
+function tryExec(command, commandArgs) {
+  try {
+    execFileSync(command, commandArgs, { stdio: "inherit" });
+    return true;
+  } catch (err) {
+    // If the command was found but returned non-zero, propagate the exit code
+    if (err.status !== null && err.status !== undefined) {
+      process.exit(err.status);
+    }
+    return false;
+  }
+}
+
+// 1. Try nex-cli directly (installed via curl | sh)
+if (tryExec("nex-cli", args)) {
+  process.exit(0);
+}
+
+// 2. Try common install locations
+const commonPaths = ["/usr/local/bin/nex-cli"];
+if (process.env.HOME) {
+  commonPaths.push(`${process.env.HOME}/.local/bin/nex-cli`);
+}
+for (const p of commonPaths) {
+  if (existsSync(p) && tryExec(p, args)) {
+    process.exit(0);
+  }
+}
+
+// 3. Not found — show install instructions
+console.error(`
+  nex-cli binary not found.
+
+  Install it with:
+    curl -fsSL https://raw.githubusercontent.com/nex-crm/nex-cli/main/install.sh | sh
+
+  Then run your command again.
+`);
+process.exit(1);