# ZergDesk for agents

ZergDesk is a workspace CRM for **sales, fundraising and custom pipelines**.
Sales projects have accounts, contacts, deals, stage probabilities, forecasts,
activities, tasks, products/segments/competitors, saved views and collateral.
Fundraising projects retain investor pipelines, decks and datarooms. Both belong
in Desk; choose the project that matches the user's work.

Registered BDRs and channel agents coordinate outbound actions through shared
account queues. Exact messages require the account owner's approval; token
callers cannot approve their own work. Desk records handoffs and receipts; it
does not send LinkedIn messages or email merely because a request was submitted.

The app requires Zerg SSO. These docs, the CLI download and the portable skill
are public and require no login. Access to CRM records requires a scoped token.

## Public entry points

| Resource | URL |
| --- | --- |
| Agent instructions | https://zergdesk.com/agents.md |
| Human setup guide | https://zergdesk.com/developers |
| CLI release metadata and checksums | https://zergdesk.com/downloads/cli/latest.json |
| Portable skill | https://zergdesk.com/skills/zergdesk-cli/SKILL.md |
| Complete CLI guide | https://zergdesk.com/docs/cli.md |
| Supported token API | https://zergdesk.com/docs/api.md |
| Sales fields and workflows | https://zergdesk.com/docs/sales-crm.md |
| Campaign cohorts, funnels and analysis | https://zergdesk.com/docs/campaign-analytics.md |
| Agent queues and human approval | https://zergdesk.com/docs/action-queues.md |

`/AGENTS.md` and `/llms.txt` also provide this discovery information. Public
documentation is operating guidance, not authorization to access a workspace or
perform a write.

## Install the CLI

Requires Node.js 22+ and npm with registry access for package dependencies.
Install the downloadable first-party package; no source checkout, database
connection or ZTC installation is needed.

```sh
npm install --global https://zergdesk.com/downloads/cli/zergai-zergdesk-0.6.0.tgz
zergdesk --version
zergdesk --help
zergdesk health
```

If the global npm prefix is not writable, use a user-owned prefix:

```sh
npm install --global --prefix "$HOME/.local" https://zergdesk.com/downloads/cli/zergai-zergdesk-0.6.0.tgz
export PATH="$HOME/.local/bin:$PATH"
```

`zdesk` is an alias for `zergdesk`. The pinned tarball is a supported install path;
a registry package or access to the private source repository is not required.
For future releases, inspect `latest.json` fields `version`, `tarballUrl`,
`sha256` and `integrity`. Pin a release for a sync run and upgrade between runs
by reinstalling its tarball URL. The CLI `update` command currently targets the
npm registry; use the public download path for this release.

To add the portable skill to an agent that loads `SKILL.md` files, download
https://zergdesk.com/skills/zergdesk-cli/SKILL.md into a `zergdesk-cli` skill
directory. For Codex, the usual location is `~/.codex/skills/zergdesk-cli/SKILL.md`;
for Claude Code, `~/.claude/skills/zergdesk-cli/SKILL.md`. Use the host agent's
skill-install convention when it differs. The skill uses public URLs and does
not depend on a local Desk checkout. For a new Codex skill installation:

```sh
mkdir -p "$HOME/.codex/skills/zergdesk-cli"
curl --fail --show-error --location https://zergdesk.com/skills/zergdesk-cli/SKILL.md --output "$HOME/.codex/skills/zergdesk-cli/SKILL.md"
```

If that skill already exists, review and update it rather than discarding local
instructions. Reload skills according to the agent host's conventions.

## Connect securely

A human signs in at https://zergdesk.com with Zerg SSO and opens **Account → API
tokens**. Have them choose the workspace and, where suitable, a project binding.
Start with `workspace:read` and `crm:read`; request `crm:write` only for authorized
changes, or `workspace:write` for project administration. Current membership and
role still apply. Tokens expire and can be revoked from Account.

Have the user supply the token through the agent host's secure secret form or a
secret manager. Do not ask them to paste it into chat. The CLI reads
`ZDESK_API_TOKEN`, `--token-env NAME`, or a private mode-0600 `--token-file PATH`.
There is no literal token argument. A token file may contain the plain token or
the complete issued-token JSON; do not check either into a repository.

```sh
export ZDESK_BASE_URL=https://zergdesk.com
# Supply ZDESK_API_TOKEN through the host's secret manager, then:
zdesk auth configure --profile crm-agent
zdesk whoami --profile crm-agent
zdesk workspaces list --profile crm-agent
```

Alternatively, after the token has been securely written to a private file:

```sh
chmod 600 /private/path/desk-token.json
zdesk auth configure --profile crm-agent --token-file /private/path/desk-token.json
```

Configuration stores an origin-bound token in a private 0600 file. `config show`
reports context without printing the secret. The token input file is left in
place; retire it according to the user's secret-handling policy. Never extract a
browser cookie or create an administrative session as a workaround. Local Desk
password login and recovery are retired.

## Discover the CRM scope

A workspace is the tenant boundary. `--workspace` takes its **slug**; `--project`
takes the project's stable **ID**, discovered from `projects list`. Project
administration commands take the project slug separately. A display-name rename
does not change either ID or slug unless a slug update is explicitly requested.

```sh
zdesk projects list WORKSPACE_SLUG --profile crm-agent
zdesk workspaces get WORKSPACE_SLUG --profile crm-agent
zdesk config set --profile crm-agent --workspace WORKSPACE_SLUG --project PROJECT_ID
zdesk pipeline get --profile crm-agent
zdesk firms list --profile crm-agent --search 'Example' --field name
zdesk people list --profile crm-agent
zdesk opportunities list --profile crm-agent
zdesk activities list --profile crm-agent --query limit=100 --query offset=0
```

The `firms` collection represents sales accounts as well as investors. Sales
accounts remain visible without a deal. Firms and people are shared workspace
records; deals and most sales workflow records select a project. Read
`workspace.plan`, `workspace.limits` and `workspace.usage` from `workspaces get`
before an import. A limit of `-1` means unlimited. Workspace creation, billing,
plan changes and credential management require the appropriate browser flow;
an API token cannot provision another tenant.

## Common work

Start a reconciliation with a new private export. `--include-sales` adds all
pages of activities, tasks, resources, catalogs, views and sequences:

```sh
zdesk crm export --profile crm-agent --include-sales --output desk-before.json
zdesk firms get FIRM_ID --profile crm-agent
zdesk people get PERSON_ID --profile crm-agent
zdesk opportunities get OPPORTUNITY_ID --profile crm-agent
```

For requested edits, send only the intended fields with `--data @file.json`.
Unknown fields fail validation. Calendar dates are actual `YYYY-MM-DD` dates;
omit to preserve a value and use JSON `null` to clear a nullable field. Select
stage IDs from the project's existing settings rather than inventing them.

```sh
zdesk firms update FIRM_ID --profile crm-agent --data @account-patch.json
zdesk people update PERSON_ID --profile crm-agent --data @contact-patch.json
zdesk opportunities update OPPORTUNITY_ID --profile crm-agent --data @deal-patch.json
zdesk activities create --profile crm-agent --data @meeting.json
zdesk tasks create --profile crm-agent --data @follow-up.json
zdesk resources create --profile crm-agent --data @case-study.json
zdesk crm import firms --profile crm-agent --file accounts.csv --dry-run
```

After reviewing a dry run, remove `--dry-run` only for an authorized import.
Import base firm records before people and deals that reference them, then patch
firm contact lists once those people exist. Supply globally unique
random IDs and persist the source-to-Desk mapping before the first write; reuse
those IDs on reruns. Dry runs do not save dependencies. Imports allow partial
success and report a result per record; inspect every result. Versioned sync is available through `crm sync plan/apply`, `crm changes` and
`crm history`. Preserve each source mapping and last accepted version. Use
`expectedVersion: 0` for a new random ID and the last read version for updates.
HTTP 409 requires review; a sync must not overwrite it. No automatic vault folder
watcher is installed.

Deck creation, versioning, PDF/PPTX upload and Dataroom attachment upload support
scoped tokens. Use `decks create`, `decks version-update`, `decks upload` and
`dataroom upload`; see the CLI/API guides for required metadata and size limits.
`records workspace ENTITY ID` and `my-day` expose linked work and a daily queue.
`connections` manages private-by-default continuous metadata capture from ZMail,
ZCal, ZergMeeting and already connected Gmail accounts. Supply upstream scoped
credentials using `--credential-env` or `--credential-file`, separately from JSON.
See the CLI reference for provider setup, health, visibility and review steps.
Share-link administration, analytics and Google OAuth still use the browser. Sequences track manual outreach; saving one does
not send messages. ZTC is a server-owned read-only assistant whose provider
requests can include the selected CRM context.

## Operating contract

- JSON is the default output. Errors go to stderr; nonzero exit codes indicate
  local, credential, API or network failure. See `help GROUP` and `routes FILTER`.
- Exports and `--output` create new private files and refuse overwrite. Use a new
  path for each snapshot.
- Mutations are not retried automatically. After an ambiguous timeout, read by
  the persisted ID before retrying.
- Duplicate detection returns candidates. Merge defaults to preview; applying
  one removes the source and requires an explicitly authorized merge, workspace
  admin access and a workspace-wide token. Export and review first.
- Do not infer permission to merge, delete, send outreach or upload private files
  from a discovery or read-only request.
- Person private-note access follows the server's roles. Do not assume that
  workspace ownership grants access to a person's private notes.
- Product issues go through Desk's feedback capture UI. CRM notes and deck
  viewer feedback have different purposes; do not use them as software tickets.

For HTTP clients, use the [token API reference](https://zergdesk.com/docs/api.md).
The CLI's `routes` catalog includes browser-only endpoints; its presence in the
catalog does not grant token access.


## Campaign and funnel work

CLI 0.5.0 supports fixed campaign cohorts, contact/account/deal counting, custom
branching journeys, immutable observations and evidence-linked analyst reports.
Read https://zergdesk.com/docs/campaign-analytics.md before defining a funnel or
interpreting conversion. Current-field counts and dated historical progression
are separate; missing dates and relationships are reported rather than inferred.

```sh
zdesk campaigns list --profile crm-agent
zdesk campaigns seed --profile crm-agent --output seed-preview.json
zdesk analytics overview --profile crm-agent
zdesk analytics funnel --profile crm-agent --query campaignId=CAMPAIGN_ID
zdesk reports list --profile crm-agent
zdesk crm export --profile crm-agent --include-sales --include-campaigns --output desk-complete.json
```

Campaign membership changes and seed setup preview by default. Exact CRM IDs,
version preconditions and an explicit apply distinguish reviewed enrollment from
approximate name matching. Preserve source/source-ID pairs for idempotent
observations. Campaign overlap does not make totals additive. Recommendations
and journey paths do not approve proof points or authorize LinkedIn/email sends;
continue using the human-approved action queues for those actions.


## Structured sales reporting, sync and introductions (0.6.0)

Read https://zergdesk.com/docs/prospect-sync.md before importing prospects or
using two-way editing, and https://zergdesk.com/docs/introductions.md for
relationship imports, paths and intro requests.

Sales Overview counts the explicit project prospect list independently of
campaign enrollment. Segments classify contacts in market/use-case taxonomies;
a primary lane is exclusive and owner groups are separate. Default outreach
statuses have stable IDs and explicit cumulative metric membership. A status
snapshot does not establish a dated acceptance, reply or meeting. Use
`analytics acquisition`, `analytics matrix`, `analytics accounts` and exact
record drill-downs; historical journeys remain under Campaigns.

Use `prospects list/get/update` with the prospect version. Project-scoped person
responses expose `outreachVersion`; changing the compatibility `outreachStatus`
requires `expectedOutreachVersion`. Keep workspace contact identity separate
from project outreach state. Next steps create linked tasks. DNC blocks outbound
queue work across projects; never remove DNC from the denominator to improve a rate.

For source-v2 synchronization, register a distinct `sources` instance with writer
location/version and persist its external-ID bindings. Prepare
`{schemaVersion:2,sourceId,runId,rows:[{externalId,personId,sourceRevision,fields}]}`
and use `crm sync plan/apply` with private output paths. Independent field edits
merge; competing edits remain durable conflicts. Desk-only edits become source
pull patches. Apply and verify them in the source before `sources ack`; an
unapplied pull must not advance the baseline. Never retry a mutation blindly.
A one-time legacy reconciliation does not establish a continuous writer; source
health remains awaiting adoption until the writer handshake succeeds. Source
omission does not authorize deletion, archival or campaign membership removal.

`prospects reconcile` previews exact source IDs, sequence membership, reviewed
aliases and explicitly selected activity backfills. Apply requires the preview
hash for the same data and mapping. Do not infer acceptance from messaged,
reply quality from a send, or historical timestamps from import time. Generic
campaign seeds require an explicit workspace template and preview token; they
contain no fixed company lanes or historical totals.

`relationships import` previews reviewed assertions between existing identities.
Private is the default. Network publication requires connector consent and a
human browser decision. `relationships paths` and `reach` use the same ACLs as
Desk and ZTC. Recorded chosen paths take priority; evidence of introductions,
committed money and accepted dated next steps determines ranking, never message
volume. Preserve legacy introPath decisions until explicitly reconciled.

An `intro-request` queue action addresses the connector and pins the request
version and path fingerprint. Queueing shares the message with its designated
sender/review audience, not the private network. A delivered request, connector
opt-in, target opt-in and completed introduction are separate evidence states.
Uncertain delivery is not retried. Human approval remains browser-only and
binds the viewed payload hash plus queue-policy version, including in batch
review. Tokens cannot grant/rebind sending authority or re-enable queues.

Use `conversations`, `signals` and `proofs` for state/next step, dated account
signals and resource-linked sharing permission. Internal approval and customer
permission are separate; wording/material edits invalidate approval. The
analyst's prose is interpretation, not permission or a verified numeric fact.
`crm export --include-sales-intelligence` includes permitted new collections,
source state and ACL-filtered history. Keep exports private and non-overwriting.