# agent-tools — NexusCRM end-user agent tooling

Single source of truth for the **Claude/Codex agent tooling that talks to NexusCRM as a
signed-in user**. These are for sales / ops / GTM people who want to self-serve CRM data
(and clone SFDC reports) without opening the NexusCRM UI or having BigQuery access.

> **This is NOT pack content.** It does not install onto the NexusCRM platform, does not go
> through `pack.validate` / `stack.lock` / final-pack assembly, and must stay **out of `packs/`**.
> Per this repo's `CLAUDE.md` boundary model, this is a distinct category — *client tooling that
> consumes the deployed CRM* — alongside the dev/ops skills already in `.claude/skills/` and
> `.agents/skills/`. CI for the pack pipeline should path-ignore `agent-tools/**`.

## Why this folder exists
These tools were previously passed around as offline `.skill` zips, so versions drifted across
people's laptops and nobody could tell which copy was current. This folder makes the repo the
**one source**; each component carries a `version` + `updated` stamp (see `MANIFEST.md`), and
`install.sh` lays them into each user's `~/.claude/skills/` reproducibly.

## Components

| Folder | What | Audience | Status |
|---|---|---|---|
| `nexuscrm-connect/` | OAuth+PKCE engine (`scripts/nexus_connect.mjs` + `lib/`), the **MCP server** (`mcp/`), and the **canonical business semantics** (`references/nexuscrm-semantics.md`) | everyone — the shared base | here |
| `nexuscrm-connect-cloner/` | Clone SFDC `.report-meta.xml` / `.dashboard-meta.xml` → live NexusCRM HTML report/dashboard | people porting existing SFDC reports | **to be added by its owner** |

> Each skill is added by its **owner**. Drop a folder here that contains a `SKILL.md` and
> `install.sh` picks it up automatically (no script edit needed). The cloner above is owned by
> someone else and will be contributed separately by them.

`nexuscrm-connect/references/nexuscrm-semantics.md` is the **single source of truth** for business
doctrine (Net New ARR, Launch_Date, fiscal calendar, open/closed) and the verified SOQL dialect
limits. Other skills (e.g. the cloner) should defer to it via a relative path
(`../nexuscrm-connect/references/nexuscrm-semantics.md`) so every surface gives the same numbers —
keep the folders siblings (install.sh does).

## Install (per user)

```bash
# from this folder
./install.sh            # copies the skills into ~/.claude/skills/ and npm-installs the MCP

# then sign in once (caches a ~1h token shared by the skills + MCP)
node ~/.claude/skills/nexuscrm-connect/scripts/nexus_connect.mjs auth
```

To use the MCP server in Claude Code/Desktop, register it (see
`nexuscrm-connect/mcp/mcp.json`). To clone an SFDC report, just give Claude the `.report-meta.xml`.

## Updating
`git pull` this repo, re-run `./install.sh`. Check `MANIFEST.md` (or each `SKILL.md` frontmatter
`version`) to confirm what you have. Don't hand-edit installed copies under `~/.claude/skills/` —
edit here and re-install, so the repo stays the source of truth.

## Security / boundary notes
- The OAuth client is **public** (PKCE, no secret), **read-only** scope; safe to keep in-repo.
- This repo is **private**; the PingCAP business semantics here are fine. Do **not** mirror
  `agent-tools/**` to any OSS/upstream repo (it carries PingCAP-specific field names + doctrine).
- No tokens are stored here — the user token lives at `~/.nexuscrm-connect/token.json` at runtime.