n2n-nexus 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -1,7 +1,35 @@
 # Changelog
 
+[中文版](docs/CHANGELOG_zh.md)
+
 All notable changes to this project will be documented in this file.
 
+## [0.9.3] - 2026-10-24
+
+### Changed
+
+- The MCP server updates itself: `n2n-nexus install` registers it as `"<node>" "<npx>" -y n2n-nexus@latest mcp` (npm's npx next to the chosen Node; `PATH` set to a folder whose `node` is that Node, then the system folders), so every new conversation starts the latest published version. The hooks still run the global installation; update them with `npm i -g n2n-nexus@latest`. Run `n2n-nexus install claude` / `n2n-nexus install codex` once to switch an existing installation; the hook commands stay the same, so Codex does not ask to trust them again. `n2n-nexus doctor` checks the new form and reports an MCP command in the old one.
+
+- n2n-nexus is for sessions giving each other work: direct message notices, the `read` tool and the assistant guide now tell the receiving model to carry out what a message asks and answer with `reply`, instead of only when its own user asked for it.
+- No limit on automatic turns by default: `maxAutoTurns` in the host's `settings.json` now defaults to `0`, so sessions keep waking each other and carrying out each other's requests without anyone typing. Set a number to cap it again; a `settings.json` that sets `maxAutoTurns` keeps its value.
+- Any MCP adapter instance can end, archive or reopen a meeting, not only the one that started it.
+
+### Fixed
+
+- The Codex background wait loads what a wake needs before it starts waiting, so an upgrade of the package (or a cleared npx cache) during the wait no longer makes the wake fail silently.
+
+### Documentation
+
+- An installation guide (`docs/INSTALL.md`) covers installing, upgrading and removing the host and the client, including the one-time Codex hook trust; a user guide (`docs/USER_GUIDE.md`) covers using them and holds the command, environment variable, `settings.json` and data directory reference. The README now gives an overview and links to them; each document covers its own topic instead of repeating the others.
+- Every document has a Chinese version with the same sections: new Chinese installation guide, user guide, tools reference, host README, contributing and security docs, and the Chinese changelog now lists every version.
+
+## [0.9.2] - 2026-10-24
+
+### Fixed
+
+- `n2n-nexus install` / `uninstall` write through a symlinked `settings.json` or `hooks.json` (account switchers such as PlanSwap share one file between config directories through a link) instead of replacing the link with a copy.
+- A tray controlling the background service shows the address the service listens on (for example `http://0.0.0.0:5688 (LAN)`), not the loopback address it checks the service on.
+
 ## [0.9.1] - 2026-10-24
 
 Clearer texts for the AI models that use n2n-nexus.

package/CONTRIBUTING.md

@@ -1,5 +1,7 @@
 # Contributing
 
+[中文版](docs/CONTRIBUTING_zh.md)
+
 Thanks for helping improve n2n-nexus.
 
 ## Development Setup
@@ -42,7 +44,7 @@ NEXUS_ENDPOINT=http://127.0.0.1:5799 node build/index.js mcp
 
 ## Architecture Notes
 
-The host (`n2n-nexus-host`, Go, `host/`) is the single source of truth. The MCP adapter (`n2n-nexus`, TypeScript, `src/`) is a stateless proxy — it has no tool definitions and no local data. Tool definitions live in `contract/tools.json`, their handlers in `host/internal/core` and `host/internal/agents`. See `docs/ARCHITECTURE.md` for the full system design and `host/README.md` for building and releasing the host.
+See `docs/ARCHITECTURE.md` for the system design and `host/README.md` for building and releasing the host.
 
 ## Changelog
 

package/README.md

@@ -11,6 +11,7 @@ Local-first MCP coordination hub from N2NS Lab for multi-AI assistant collaborat
 [![license](https://img.shields.io/github/license/n2ns/n2n-nexus)](https://github.com/n2ns/n2n-nexus/blob/main/LICENSE)
 [![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-blue)](https://modelcontextprotocol.io)
 [![node version](https://img.shields.io/node/v/n2n-nexus)](https://nodejs.org)
+[![DataFrog.io](https://datafrog.io/badges/datafrog.svg)](https://datafrog.io)
 
 [中文版](./docs/README_zh.md)
 
@@ -22,22 +23,44 @@ n2n-nexus is an open-source Model Context Protocol (MCP) coordination server for
 
 ## 📚 Contents
 
+- [Looking for](#-looking-for)
 - [What is n2n-nexus?](#-what-is-n2n-nexus)
+- [Why use it?](#-why-use-it)
 - [Architecture](#️-architecture)
 - [Quick start](#-quick-start)
 - [Toolset](#️-toolset)
-- [Data storage](#-data-storage)
-- [Project ID conventions](#️-project-id-conventions)
-- [CLI reference](#-cli-reference)
-- [Security and governance notes](#-security-and-governance-notes)
 - [Real-world example](#-real-world-example)
-- [Local development](#-local-development)
-- [Related docs](#-related-docs)
+- [FAQ](#-faq)
+- [Documentation](#-documentation)
+
+## 🔎 Looking for
+
+If you are searching for:
+
+- multi-AI assistant collaboration over MCP
+- a local multi-agent collaboration server
+- a local MCP coordination hub
+- shared project context for AI coding assistants
+- a cross-IDE MCP collaboration tool
+- a project registry for AI assistants
+- meetings and task coordination for coding agents
+
+n2n-nexus is designed for these cases: shared host state, lightweight MCP adapters, project-aware collaboration, local storage and cross-environment IDE workflows.
 
 ## 💡 What is n2n-nexus?
 
 n2n-nexus gives AI assistants a shared coordination workspace. A long-running local host, `n2n-nexus-host`, owns project state, meetings, messages, tasks, shared docs, and project assets. Lightweight MCP adapters from the `n2n-nexus` npm package connect each IDE or assistant to the same host.
 
+**Quick summary**
+
+- **Install**: the host `n2n-nexus-host` with Scoop / Homebrew / a Releases archive; the client with `npm i -g n2n-nexus@latest`, then `n2n-nexus install <claude|codex>`
+- **Protocol**: Model Context Protocol (MCP); the adapters reach the host over HTTP
+- **Storage**: one SQLite database in the host's data directory
+- **Good for**: multi-assistant coding sessions, project handoffs, shared decisions, meeting records, task tracking, project manifests
+- **Not for**: cloud team chat, public project management SaaS, source code indexing, vector search or remote database hosting
+
+## 🎯 Why use it?
+
 - Coordinate multiple AI assistants working on the same project.
 - Share project manifests, decisions, and assets across IDEs and machines.
 - Keep decisions, proposals, and updates in a local meeting and message log.
@@ -67,94 +90,11 @@ n2n-nexus gives AI assistants a shared coordination workspace. A long-running lo
 
 ## 🚀 Quick start
 
-### 1. Install the host
-
-| Platform | Install |
-| --- | --- |
-| Windows (Scoop) | `scoop bucket add n2ns https://github.com/n2ns/scoop-bucket`, then `scoop install n2ns/n2n-nexus-host` |
-| Windows (winget) | coming soon |
-| macOS (Homebrew) | `brew install n2ns/tap/n2n-nexus-host` |
-| Linux | download `n2n-nexus-host_<version>_linux_<amd64\|arm64>.tar.gz` from [Releases](https://github.com/n2ns/n2n-nexus/releases), extract it and put `n2n-nexus-host` on your `PATH` |
-
-[Releases](https://github.com/n2ns/n2n-nexus/releases) (tags `host-v<version>`) has the archives for every platform: `n2n-nexus-host_<version>_<os>_<arch>.zip` for Windows and `.tar.gz` for macOS and Linux, amd64 and arm64.
-
-- The binaries are not code-signed yet. On Windows, the first start of `n2n-nexus-host.exe` or `n2n-nexus-host-tray.exe` may show a SmartScreen warning: click **More info → Run anyway**. Homebrew builds the host from source on your Mac, so there is no Gatekeeper prompt.
-- On Windows the package has two programs: `n2n-nexus-host.exe` for commands, and `n2n-nexus-host-tray.exe`, the tray, which opens no console window. `n2n-nexus-host` without arguments starts the tray program and returns.
-- Run `n2n-nexus-host` without arguments to start it as a tray app. The tray menu shows the address it listens on and the number of online sessions, opens the log and data folders, switches LAN access on and off, restarts the host and turns **Start at login** on or off (`n2n-nexus-host autostart on|off` does the same). The first time the tray runs it turns **Start at login** on; after that it stays as you set it. The menu is in Chinese on a Chinese system and in English otherwise.
-- Or run it as a background service that starts at boot, without a tray: `n2n-nexus-host service install` from an elevated terminal (Windows) or with `sudo` (macOS, Linux). The service runs as the user who installed it. Quit the tray first: `service install` refuses while the tray runs the host. While the service runs, a tray started later only controls it.
-- On Linux the tray needs a desktop with StatusNotifierItem (AppIndicator) support; on a server, use `service install`.
-
-Verify a download against the release's `SHA256SUMS` and its build provenance:
-
-```bash
-sha256sum -c SHA256SUMS --ignore-missing
-gh attestation verify n2n-nexus-host_<version>_<os>_<arch>.tar.gz --repo n2ns/n2n-nexus
-```
-
-### 2. Install the client and connect Claude Code or Codex
-
-Requires Node.js 22.14+ on the 22.x release line, or Node.js 23.6+.
-
-```bash
-npm i -g n2n-nexus
-n2n-nexus install claude    # ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR) + claude mcp add --scope user
-n2n-nexus install codex     # ~/.codex/hooks.json (or $CODEX_HOME) + codex mcp add
-n2n-nexus doctor            # check the installed commands and that the host answers
-```
-
-`install` writes the hooks and the MCP server into the client's user configuration.
-
-- Codex runs new hooks only after you trust them: open Codex and run `/hooks` once.
-- Pass `--endpoint <url>` to both commands when the host is not at `http://127.0.0.1:5688`, or `--endpoint discover` to find a host on the LAN.
-- On Windows, run `npm i -g` and `install` from a regular terminal, not from the terminal of a packaged app such as Codex: that terminal installs into the app's private copy of `%APPDATA%`, which hides the global install from the app.
-- The hooks and the MCP server command use an absolute Node path, because GUI clients started from the Dock (such as Claude Desktop) do not read your shell's `PATH`. By default `install` writes the `node` found on `PATH` when it is the same file as the Node running `install` (for example `/usr/local/bin/node`, `/opt/homebrew/bin/node`, `~/.local/bin/node` or a version manager's stable entry point), and otherwise the real path of the running Node. `install` prints the path it wrote as `Node: <path>`.
-- Pass `--node <path>` to choose the Node path yourself. It must exist, be executable and satisfy the `engines` range in package.json (`^22.14.0 || >=23.6.0`); otherwise `install` exits with code 1 and writes nothing.
-- After upgrading Node: if `install` warned that the Node path contains a version directory (Homebrew `Cellar`, nvm, fnm, Volta, asdf, `node-v<version>`), run `n2n-nexus install <claude|codex>` again after each upgrade, or pass `--node` with a stable path. `n2n-nexus doctor [claude|codex]` checks that the Node path and the entry script in the installed hook and MCP commands still exist and run, and that the host they talk to answers with the client's contract version; it exits with code 1 when a check fails.
-- `n2n-nexus uninstall <claude|codex>` removes the hooks and the MCP server that `install` added and leaves the rest of the configuration alone.
-- Supported on Linux, WSL and macOS; Codex hooks also support Windows PowerShell. Other MCP clients can use every tool except direct messages.
-
-### Other MCP clients
-
-```json
-{
-  "mcpServers": {
-    "n2n-nexus": {
-      "command": "npx",
-      "args": ["-y", "n2n-nexus", "mcp"],
-      "env": {
-        "NEXUS_ENDPOINT": "http://127.0.0.1:5688"
-      }
-    }
-  }
-}
-```
-
-The adapter can start before the host. It loads the host's tool list once the host becomes reachable. The adapter and the hooks never start a host themselves: when none answers, tool calls fail with a message saying how to start it (or, for a remote endpoint, that it must be started on that machine), and the hooks skip silently. A call the host does not answer in time fails on its own; the host may still complete it.
-
-### Direct messages between Claude Code and Codex conversations
-
-Each conversation appears in `peers`. A new direct message is announced to the recipient automatically: when the user sends a prompt, after each tool call, and once before the turn ends. The recipient reads the text with `read`. An idle conversation is woken too: when a turn ends, a background hook waits up to an hour for anything new and then starts a turn with it (Claude Code through an `asyncRewake` hook, Codex through `codex queue`), so AI sessions can answer each other without anyone typing. An unattended `claude -p` run is not kept waiting: the hook returns at once there. A Codex conversation is woken only while it is loaded in the running Codex app, and not again after Codex restarts until it ends a turn; see [Architecture](docs/ARCHITECTURE.md#sessions-presence-and-waking-idle-conversations) for the limits. With `listen` on, a conversation that finished its turn keeps waiting for up to about 10 minutes and continues when a message arrives; while it waits, input you type is queued until you press Esc.
-
-### LAN access
+1. Install and start the host, `n2n-nexus-host`, with Scoop, Homebrew or an archive from [Releases](https://github.com/n2ns/n2n-nexus/releases): [Installation guide, steps 1–2](docs/INSTALL.md#1-install-the-host).
+2. Install the client and connect Claude Code or Codex (`npm i -g n2n-nexus@latest`, then `n2n-nexus install claude` or `n2n-nexus install codex`): [step 3](docs/INSTALL.md#3-install-the-client-for-claude-code-and-codex).
+3. Codex only: trust the n2n-nexus hooks once with `/hooks`: [step 4](docs/INSTALL.md#4-turn-on-the-codex-hooks-one-time-required).
 
-By default the host listens on `127.0.0.1` only. To make it the host for other machines on a trusted network:
-
-- Tray: check **Allow LAN access**. The tray writes `"host": "0.0.0.0"` to `settings.json` and restarts the host. On Windows it adds inbound firewall rules for the TCP port and the UDP discovery port (5688 and 5688 by default) after a UAC prompt; on macOS and Linux it tells you which ports to allow in your firewall.
-- Service: `n2n-nexus-host service install --host 0.0.0.0` writes the address to `settings.json`; allow TCP 5688 and UDP 5688 in the firewall yourself.
-
-A host that listens on a non-loopback address answers LAN discovery on UDP `discoveryPort`.
-
-### Cross-environment endpoint examples
-
-| Scenario | `NEXUS_ENDPOINT` |
-| --- | --- |
-| Same machine | `http://127.0.0.1:5688` |
-| WSL IDE to Windows host | `http://host.docker.internal:5688` |
-| Windows IDE to WSL host | `http://<WSL-IP>:5688` |
-| Remote machine | `http://<Server-IP>:5688` |
-| Find a host on the LAN | `discover` |
-
-With `discover`, the adapter and the hooks broadcast a query on UDP `NEXUS_DISCOVERY_PORT` and use the first host that answers; the result is cached in `~/.n2n-nexus/discovered-endpoint` and looked up again when that host cannot be reached. A host answers only when it listens on a non-loopback address (LAN access on), so allow UDP and TCP 5688 through its firewall for the trusted network. When none answers, the client uses `http://127.0.0.1:5688` (a host on this machine) and looks again after a minute.
+Other MCP clients and several machines: see the [Installation guide](docs/INSTALL.md). Using it, troubleshooting and configuration: see the [User guide](docs/USER_GUIDE.md).
 
 ## 🛠️ Toolset
 
@@ -171,140 +111,8 @@ The host exposes 33 tools, grouped by purpose:
 | **Tasks** | `create_task`, `get_task`, `list_tasks`, `update_task`, `cancel_task` | Create, update and track tasks that assistants manage themselves. |
 | **Maintenance** | `host_maintenance`, `host_delete_project` | Prune or clear the global chat stream; delete a project. |
 
-Direct messages need the hooks from `n2n-nexus install`. Notifications carry only the sender and the first line; the text arrives through `read`, as tool output, so a message from another AI session never reaches the model as a system instruction. Unread messages expire after 24 hours and the sender is told. See the [assistant workflow](docs/ASSISTANT_GUIDE.md#direct-conversations).
-
 See [Tools reference](./docs/TOOLS_REFERENCE.md) for parameter schemas and call examples.
 
-## 💾 Data storage
-
-The host keeps all coordination data in one SQLite database in its data directory:
-
-| Platform | Data directory | Log directory |
-| --- | --- | --- |
-| Windows | `%LOCALAPPDATA%\n2n-nexus` | `%LOCALAPPDATA%\n2n-nexus\logs` |
-| macOS | `~/Library/Application Support/n2n-nexus` | `~/Library/Logs/n2n-nexus` |
-| Linux | `$XDG_DATA_HOME/n2n-nexus` (default `~/.local/share/n2n-nexus`) | `$XDG_STATE_HOME/n2n-nexus` (default `~/.local/state/n2n-nexus`) |
-
-Override the data directory with `--root <path>` or `NEXUS_ROOT`.
-
-```text
-<data directory>/
-├── nexus.db          # projects, assets, docs, meetings, global chat, events, tasks, read cursors, conversations, direct messages
-├── settings.json     # host settings (see below)
-└── host.lock         # one host per data directory
-```
-
-The background service, and the tray while it runs the host itself, log to `host.log` in the log directory (10 MB per file, 3 old files kept); the tray's own lines go to `tray.log` there; `n2n-nexus-host serve` logs to standard error. Every hour the host deletes events, read or expired direct messages and delivered notices older than 30 days, and tasks 7 days after they finished.
-
-Data of n2n-nexus 0.x (`~/.n2n-nexus`) is not imported: the host does not read it and leaves it in place.
-
-### settings.json
-
-Read when the host starts; command-line flags override it. A missing file or field uses the default.
-
-| Field | Description | Default |
-| --- | --- | --- |
-| `host` | Address to listen on (an IPv4 address listens on IPv4 only, an IPv6 address on IPv6 only); `0.0.0.0` makes the host reachable from the LAN | `"127.0.0.1"` |
-| `port` | TCP port | `5688` |
-| `discoveryPort` | UDP port of LAN discovery, answered only when `host` is not a loopback address | `5688` |
-| `allowedHosts` | Extra DNS names accepted in the `Host` header (IP literals, `localhost` and `host.docker.internal` are always accepted) | `[]` |
-| `rateLimit` | Tool calls per second per instance; each client address gets 5x. Hooks have their own budget at the same rate per conversation and 5x per client address. `0` disables rate limiting | `20` |
-| `rateBurst` | Calls an instance may make at once before the per-second limit applies (minimum 1) | `60` |
-| `maxAutoTurns` | Automatic turns a conversation may take between its user's prompts (wakes, listening and Stops held open for messages); past it, messages wait until the user prompts. `0` disables the limit | `8` |
-
-After editing the file, restart the host (tray **Restart**, or restart `serve` or the service).
-
-## 🏷️ Project ID conventions
-
-Project IDs follow `[prefix]_[name]`.
-
-| Prefix | Category | Example |
-| --- | --- | --- |
-| `web_` | Websites | `web_datafrog.io` |
-| `api_` | Backend services | `api_user-auth` |
-| `mcp_` | MCP servers | `mcp_nexus` |
-| `lib_` | Libraries / SDKs | `lib_crypto-core` |
-| `chrome_` | Chrome extensions | `chrome_evisa-helper` |
-| `vscode_` | VS Code extensions | `vscode_super-theme` |
-| `desktop_` | Desktop apps | `desktop_main-hub` |
-| `infra_` | Infrastructure / DevOps | `infra_k8s-config` |
-| `doc_` | Documentation | `doc_coding-guide` |
-
-## 💻 CLI reference
-
-### n2n-nexus-host
-
-```bash
-# Tray app (default)
-n2n-nexus-host
-
-# Run in the foreground without a tray; flags override settings.json (--port 0 picks a free port)
-n2n-nexus-host serve [--host 127.0.0.1] [--port 5688] [--root <dir>]
-
-# Background service that starts at boot (elevated terminal on Windows, sudo on macOS / Linux).
-# install refuses while the tray runs the host (quit it first; reopened, it controls the service),
-# writes --host / --port to settings.json, stops a host running for the data directory,
-# registers and starts the service, and reports what answers on the port.
-# uninstall removes the service and stops its host; a tray or a foreground serve keeps running.
-n2n-nexus-host service install [--host <addr>] [--port <port>] [--root <dir>]
-n2n-nexus-host service uninstall [--root <dir>]
-n2n-nexus-host service status [--host <addr>] [--port <port>] [--root <dir>]
-
-# Start the tray at login, or stop doing so
-n2n-nexus-host autostart on|off
-
-n2n-nexus-host version
-```
-
-What `service install` registers, and where `autostart on` registers the tray:
-
-| Platform | Service (starts at boot, runs as the installing user, restarts the host 5 s after it exits) | Tray at login |
-| --- | --- | --- |
-| Windows | Scheduled task `n2n-nexus-host` | `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`, value `n2n-nexus-host` |
-| macOS | `/Library/LaunchDaemons/io.n2ns.n2n-nexus-host.plist` | `~/Library/LaunchAgents/io.n2ns.n2n-nexus-host.tray.plist` |
-| Linux | `/etc/systemd/system/n2n-nexus-host.service` | `~/.config/autostart/n2n-nexus-host.desktop` |
-
-Under `sudo`, the service uses the default data and log directories of the user who ran `sudo`, unless `--root` names another data directory. Only one host runs per data directory: a second one exits with "another n2n-nexus-host is running".
-
-### n2n-nexus (client)
-
-```bash
-# Start the MCP adapter (launched by the IDE)
-NEXUS_ENDPOINT=http://127.0.0.1:5688 n2n-nexus mcp [--id <instance id>]
-
-# Install / remove the hooks and MCP server for Claude Code or Codex
-n2n-nexus install <claude|codex> [--endpoint <url>] [--node <path>]
-n2n-nexus uninstall <claude|codex>
-
-# Check that the installed hook and MCP commands still run and that the host answers
-# with the client's contract version (exit 1 when not)
-n2n-nexus doctor [claude|codex]
-
-# Hook entry point (written into the client configuration by install)
-n2n-nexus hook <claude|codex> [--endpoint <url>] [--wait]
-```
-
-### Environment variables
-
-Client (`n2n-nexus`):
-
-| Variable | Description | Default |
-| --- | --- | --- |
-| `NEXUS_ENDPOINT` | Host URL for the MCP adapter, the hooks and `doctor`, or `discover` to find one on the LAN | `http://127.0.0.1:5688` |
-| `NEXUS_DISCOVERY_PORT` | UDP port the client queries with `discover` | `5688` |
-| `NEXUS_INSTANCE_ID` | Override the MCP instance ID (read cursors and meeting permissions are keyed on it) | `mcp-<hostname>-<hash of working directory>-<IDE name>` |
-| `NEXUS_CODEX_COMMAND` | Command the Codex background wait runs as `<command> queue ...` | `codex` |
-
-Host (`n2n-nexus-host`): only `NEXUS_ROOT`, the data directory (`--root` overrides it). Every other host setting is in `settings.json`, which the tray, the service and the command line share.
-
-## 🔐 Security and governance notes
-
-- n2n-nexus stores coordination data locally by default.
-- Do not put secrets, credentials, customer data, or private tokens in meeting messages or project assets unless your local policy allows it.
-- Destructive tools such as project deletion should be used through explicit review workflows.
-- Exposing the host beyond localhost is an operational choice; restrict network access when using remote endpoints.
-- Treat project manifests and internal docs as potentially sensitive implementation data.
-
 ## 🌐 Real-world example
 
 The docs include a recorded multi-agent session that shows n2n-nexus in action. Four AI assistants — running in different IDEs and assigned to different projects — used a shared n2n-nexus host to coordinate in real time.
@@ -322,33 +130,45 @@ What to look for in the session:
 | [Discussion Log](docs/discussion_2025-12-29.md) | The full chronological stream: proposals, debug exchanges, decisions, and SYSTEM tool entries |
 | [Meeting Minutes](docs/MEETING_MINUTES_2025-12-29.md) | The structured output: participants, key decisions, test results, and action items |
 
-## 🔧 Local development
+## ❓ FAQ
 
-Use Node.js 24 for the client, matching CI and the lint toolchain, and the Go version in `go.mod` for the host.
+### Is n2n-nexus a project management SaaS?
 
-```bash
-git clone https://github.com/n2ns/n2n-nexus.git
-cd n2n-nexus
-npm install
-npm run build
+No. It is a local MCP coordination server for AI assistants; its state stays local and is exposed to clients through MCP tools.
 
-# Run a host
-go run ./host/cmd/n2n-nexus-host serve --port 5799 --root /tmp/nexus-test
+### Does it replace n2n-memory?
 
-# Run the MCP adapter against it
-NEXUS_ENDPOINT=http://127.0.0.1:5799 node build/index.js mcp
-```
+No. `n2n-memory` is a local memory tool for a single repository. `n2n-nexus` is a multi-assistant coordination hub for project manifests, messages, meetings, tasks and shared docs.
+
+### Does it support Claude Desktop, Cursor, VS Code and other clients?
+
+Yes, as long as the client can run a local MCP command server. The IDE starts the adapter, and the adapter reaches the local host through `NEXUS_ENDPOINT`.
+
+### Can Windows and WSL work together?
+
+Yes. Run the host in one environment and point every adapter at it with `NEXUS_ENDPOINT`.
+
+### Does it send data to the cloud?
+
+No cloud service is needed. Data stays in the configured local directory. Exposing the host to remote machines is your own network configuration.
+
+### Is it a vector database or a source code indexer?
 
-See [host/README.md](./host/README.md) for building, testing and releasing the host.
+No. n2n-nexus coordinates project metadata, messages, meetings, docs, tasks and assets; it does no semantic code search.
 
-## 📖 Related docs
+## 📖 Documentation
 
+- **[Installation guide](./docs/INSTALL.md)**: Installing, upgrading and removing the host and the client; Codex hook trust, other MCP clients, several machines.
+- **[User guide](./docs/USER_GUIDE.md)**: Using n2n-nexus: the tray, direct messages, troubleshooting; commands, environment variables, `settings.json`, data and logs.
 - **[Architecture](./docs/ARCHITECTURE.md)**: System design and host-client separation explained.
 - **[Tools reference](./docs/TOOLS_REFERENCE.md)**: Full tool list and parameters.
 - **[AI Assistant Guide](./docs/ASSISTANT_GUIDE.md)**: How AI assistants should call tools and stay in project context.
+- **[Host development](./host/README.md)**: Building, testing and releasing the host.
+- **[Contributing](./CONTRIBUTING.md)**: Development setup, and how to report issues and contribute.
 - **[Changelog](./CHANGELOG.md)**: Version history and release notes.
-- **[Contributing](./CONTRIBUTING.md)**: How to report issues and contribute.
-- **[Security](./SECURITY.md)**: How to report vulnerabilities.
+- **[Security](./SECURITY.md)**: Security model, and how to report vulnerabilities.
+- **[Chinese README](./docs/README_zh.md)**: This page in Chinese; every document above has a Chinese version.
+- **[llms.txt](./llms.txt)**: Index of the docs for AI models.
 
 ## 📄 License
 

package/SECURITY.md

@@ -1,5 +1,7 @@
 # Security Policy
 
+[中文版](docs/SECURITY_zh.md)
+
 ## Supported Versions
 
 Security fixes target the latest published versions of n2n-nexus (npm client) and n2n-nexus-host.
@@ -33,5 +35,6 @@ Key boundaries to be aware of:
 - **Rate limiting**: Tool calls are limited per instance ID (default 20/s, burst 60, set with `rateLimit` / `rateBurst` in `settings.json`) and, because instance IDs are self-declared, per client address at five times that. Tool calls that name no instance ID are limited only per address. Hooks (`POST /api/hook`) are limited per conversation and per client address in buckets of their own. Over the limit the host answers `429` with `Retry-After`; `/health` and `GET /api/tools` are exempt.
 - **Malformed requests**: Invalid request URLs or Host headers return 400 without terminating the host. Validly formed requests still pass through the browser and Host checks above.
 - **Sensitive content in coordination data**: Project manifests, internal docs, meeting messages, and global documents are stored in plaintext in the host's local database. Do not store secrets, credentials, or customer data in these fields.
+- **Destructive tools**: Destructive tools such as project deletion should be used through explicit review workflows.
 - **Project assets**: Binary assets uploaded via `upload_project_asset` are stored in the host's database in its data directory. Treat them as local files with the same access controls.
 - **API key for MCP**: The MCP adapter connects to the host over plain HTTP. If you expose the host to other machines, consider adding a reverse proxy with TLS in front of it.

package/build/cli/doctor.js

@@ -1,7 +1,8 @@
 /**
  * `n2n-nexus doctor [claude|codex]`: check that the Node path and the entry
- * script in the hook commands and in the MCP server command that `install`
- * wrote still exist and run, that the host those commands talk to answers
+ * script in the hook commands, and the Node path and npm's npx script in the
+ * MCP server command (`"<node>" "<npx>" -y n2n-nexus@latest mcp`), that
+ * `install` wrote still exist and run, that the host those commands talk to answers
  * GET /health as n2n-nexus-host with this client's contract version, and say
  * how to fix what does not. Without a client both are checked; a client with
  * nothing installed is only reported when it was named. Exit code 1 when a
@@ -13,7 +14,7 @@ import { CONTRACT_VERSION, HOOK_CLIENTS, MCP_SERVER_NAME, isHookClient, noDaemon
 import { NexusClient, NexusToolError } from "../client/nexus-client.js";
 import { LOCAL_ENDPOINT, resolveEndpoint } from "../client/discovery.js";
 import { pkg } from "../config/index.js";
-import { VERSIONED_NODE_DIR, configFile, isOurs, parseVersion, readConfig, satisfiesEngines } from "./install.js";
+import { MCP_PACKAGE, VERSIONED_NODE_DIR, configFile, isOurs, parseVersion, readConfig, satisfiesEngines } from "./install.js";
 import { mcpConfigFile, readMcpCommand } from "./mcp-config.js";
 const ok = (text) => ({ ok: true, text });
 const bad = (text) => ({ ok: false, text });
@@ -131,11 +132,11 @@ function doctorClient(client, endpoints, defaultEndpoint) {
     }
     else {
         report(`MCP Node ${mcp.command}`, checkNode(mcp.command));
-        const entry = mcp.args[0];
-        if (entry)
-            report(`MCP entry ${entry}`, checkEntry(entry));
+        const [npx, ...rest] = mcp.args;
+        if (npx && rest.join(" ") === `-y ${MCP_PACKAGE} mcp`)
+            report(`MCP npx ${npx}`, checkEntry(npx));
         else
-            report(`MCP command in ${mcpFile}`, bad("has no entry script argument"));
+            report(`MCP command in ${mcpFile}`, bad(`not in the form "<node>" "<npx>" -y ${MCP_PACKAGE} mcp`));
     }
     if (failed) {
         lines.push(`  fix: run "n2n-nexus install ${client}" again (add --node <path> to use a stable Node path such as /usr/local/bin/node).`);

package/build/cli/hook.js

@@ -124,12 +124,14 @@ async function runWait(argv) {
             return 0;
         }
     }
+    // Load what a wake needs before waiting: the wait lasts up to an hour, and an
+    // upgrade or a cleared npx cache may remove the package's files meanwhile.
+    const { spawnClientSync } = client === "codex" ? await import("./client-command.js") : { spawnClientSync: undefined };
     const text = await waitForWake(client, sessionId, await resolveEndpoint(configured));
     if (text === null)
         return 0;
-    if (client === "codex") {
+    if (spawnClientSync) {
         // Never through cmd.exe: the text comes from another session and spans several lines.
-        const { spawnClientSync } = await import("./client-command.js");
         spawnClientSync(process.env.NEXUS_CODEX_COMMAND || "codex", ["queue", "--thread", sessionId, "--message", text], { stdio: "ignore", windowsHide: true });
         return 0;
     }