# NexusCRM agent-tools — distribution & upgrade design

How we ship the connector / MCP to people, and how we update it afterward, across
**macOS + Windows** and **Claude Code (terminal) / Claude Cowork (desktop) / Codex**.

## Audiences (different constraints → different channels)

| Audience | Have GitHub/Node? | Comfortable in terminal? | Channel |
|---|---|---|---|
| Eng / ops | yes | yes | `npx` (private registry) / `claude mcp add` / Codex config |
| **Sales / GTM** | **no GitHub, no Node** | **no** | **signed single-file binary, pushed via IT/MDM** |

There is **no Cowork central push** available, so even Cowork users self-install — which is why
the sales path must be a **double-click, no-account, no-Node** artifact.

## Install

### Sales (the hard case) — signed single-file binary
- Build the engine+MCP as a **single executable** (Node SEA / pkg) for `mac-arm64`, `mac-x64`,
  `win-x64` → no Node prerequisite, no terminal.
- **Code-sign + notarize** (Apple Developer ID; Windows Authenticode) — without this, Gatekeeper /
  SmartScreen block non-technical users. **This is the gating dependency; owned by IT/security.**
- Ship via the channel sales already use: **MDM (Jamf/Intune) / internal download page / Lark file** —
  no GitHub, no npm.
- An **idempotent installer** drops the binary and **auto-registers** into whichever surfaces are
  present (it detects them), so the user never edits JSON:
  - Cowork/desktop → `claude_desktop_config.json` `mcpServers.nexuscrm`
  - Claude Code → `~/.claude.json` (or `claude mcp add`)
  - Codex → `~/.codex/config.toml` `[mcp_servers.nexuscrm]`
- One-time: `… auth` opens the browser for the user's normal NexusCRM login (no dev account).

### Eng / ops — `npx` (parallel, optional)
Once published to an internal registry: `claude mcp add nexuscrm -- npx -y @pingcap/nexuscrm-mcp`
(same command on every OS/surface). Updates = version bump.

> Don't host this as a **remote** MCP: auth is per-user OAuth via a `127.0.0.1` loopback browser
> login — inherently local. A hosted server would also mean one box holding everyone's tokens.

## Upgrade — two layers, very different cadence

The mistake to avoid is "every change needs a re-signed binary pushed to everyone." Split it:

### Layer 1 — business semantics ("口径"), changes often → NO binary rebuild
Stage sequence, closed/realized stages, stage aliases, fiscal-year start month. These are
**externalized to a JSON file** (`NEXUS_SEMANTICS_FILE`, default `~/.nexuscrm-connect/semantics.json`);
built-in defaults are the fallback. To change 口径 fleet-wide, **IT/MDM pushes that small JSON file** —
it's *data, not code*, so **no re-sign, no rebuild, no reinstall**. `get_semantics` shows the active
口径 + its source so you can confirm what each install is using.

Example `semantics.json` (only override what changed):
```json
{ "currentStages": ["Prospecting","Discovery & Qualification","Technical Validation","Business Validation","Negotiation","Deal Closed","Launched"],
  "fiscalYearStartMonth": 4 }
```
(Future option for unmanaged users: serve this JSON from an internal URL, or from a NexusCRM config
record read via the user's session. Not required while MDM file-push covers managed devices.)

> Field NAMES (`ARR_Amount_USD__c`, `Launch_Date__c`) are intentionally **not** externalized —
> they're stable schema; a rename is a code+test change, not a 口径 toggle.

### Layer 2 — the engine/binary, changes rarely → push a new binary
Transport, protocol, new tools, security fixes. Mechanisms:
- **Sales (MDM):** IT re-pushes the new signed binary; the installer is idempotent (re-run upgrades).
- **Self-update (defer to when the binary actually changes often):** binary checks an internal signed
  feed at startup, **verifies signature/hash**, swaps itself. Real work (cross-OS file-swap + verify) —
  not v1.
- **Eng (`npx`):** version bump in the registry.

### Discipline
- **Pin, don't float** for the broad audience; stage rollouts. Don't silently push "latest" to everyone.
- **Version visibility:** the MCP reports its version on the handshake + startup log + `get_semantics`,
  and the repo `MANIFEST.md` is the build source of truth — so you can see the fleet's version spread
  and catch stragglers (this is what kills the offline-zip drift problem at the root).

## Who to ask (dependencies)
- **Code-signing certs** (Apple Developer ID + notarization; Windows Authenticode) → IT / security.
- **Distribution channel** (MDM / internal download / Lark) → IT / endpoint management.
- **Internal npm registry** (optional, eng path only) → dev-infra / EngProd; or use GitHub Packages
  (eng only — sales have no GitHub account, so it does NOT serve the sales path).

## Status
- ✅ Layer-1 externalization (口径 file + `get_semantics` + version reporting) — implemented here.
- ☐ Signed single-file binary + auto-registering installer — to build (gated on signing certs).
- ☐ Self-update — deferred until the binary changes frequently.