---
name: client
description: "Client portfolio management -- list, resolve, inspect, and maintain client records and their lineage to companies, contacts, and source deals -- via the elevasis-sdk client:* CLI."
argument-hint: "[list | status | get | resolve | create | update | delete] [args]"
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
---

# Client Management

`/client` is the entrypoint for all client-portfolio work in the template. It covers:

- **Portfolio status** -- bare `/client` or `/client status` gives a portfolio-level overview of all clients.
- **Lookup and resolution** -- `/client <query>` or `/client resolve <query>` resolves a name or search term to a canonical client ID.
- **Detail and lineage** -- `/client get <id>` returns full client detail including linked companies, contacts, and source deals.
- **CRUD surface** -- create, update, and delete client records via `elevasis-sdk client:*`.

**Usage:**

- `/client` / `/client status` -- Portfolio overview (see "Status Mode" below). Wraps `client:status`.
- `/client list [--search q] [--status s] [--limit n] [--offset n]` -- Paginated client list. Wraps `client:list`.
- `/client <query>` / `/client resolve <query>` -- Fuzzy-resolve a client by name, UUID, or search string. Wraps `client:resolve`.
- `/client get <id>` -- Full client detail: name, status, source, linked company, contact, deals. Wraps `client:get`.
- `/client create --name "..." [options]` -- Create a new client (confirm ceremony). Wraps `client:create`.
- `/client update <id> [options]` -- Update client fields (confirm ceremony). Wraps `client:update`.
- `/client delete <id>` -- Delete a client (destructive -- explicit confirmation required). Wraps `client:delete`.

---

## Ambient Vibe Integration

`/client` is the landing point for client-scoped vibe intents. Agents arriving from the ambient layer behave identically to a direct invocation.

| Vibe intent    | What vibe detected                                          | What to do here                                                                                       |
| -------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Describe**   | "tell me about Acme", "what's the status of this client"    | Resolve the client name via `client:resolve`, then run `client:get <id>` and narrate detail + lineage |
| **Query**      | "which clients are active", "list clients", "client status" | Run `client:list [--status s] [--search q]` or `client:status` and present the results                |
| **Navigate**   | "focus on Acme", "switch to Acme", "back to Acme"           | Resolve via `client:resolve <query>`, update scope to that client, narrate the new context            |
| **Capture**    | "add a new client", "create a client for Beta LLC"          | Draft fields from the user's message, confirm with user (Capture ceremony), then `client:create`      |
| **Transition** | "update Acme's status", "mark Acme as active"               | Confirm the change with user (Transition ceremony), then `client:update <id> --status <new>`          |

`client:create`, `client:update`, and `client:delete` MUST route through the standard Capture/Transition confirm step before executing. The destructive `client:delete` requires explicit user confirmation (show what will be deleted and ask "Are you sure?" before proceeding).

---

## Prerequisites

**Run from the project root** (the directory containing `.elevasis`). Before issuing any other commands, run:

```bash
pnpm elevasis-sdk doctor
```

If `doctor` fails, stop immediately and surface the error -- do not retry other commands. Fix the reported issue first (missing `.env`, bad API key, wrong directory), then re-run `doctor` before proceeding.

---

## Invocation Contract

All `elevasis-sdk` commands in this skill use the wrapper script form:

```bash
pnpm elevasis-sdk <subcommand> [flags]
```

Available from the **project root** -- the directory that contains the `.elevasis` marker file. The long form `pnpm -C operations exec elevasis-sdk <subcommand>` is equivalent.

---

## Status Mode (bare `/client` or `/client status`)

When invoked without a subcommand or with `status`, enter **client portfolio mode**: present a high-level overview and offer next actions.

```bash
pnpm elevasis-sdk client:status --pretty
```

Present the result as a compact summary: total clients, breakdown by status, and a suggestion of what to do next (e.g. "3 active clients. Inspect one with `/client get <id>` or list all with `/client list`").

---

## Operations

### `list [options]` -- Client List

```bash
pnpm elevasis-sdk client:list --pretty

# Filter by status
pnpm elevasis-sdk client:list --status active --pretty

# Search by name
pnpm elevasis-sdk client:list --search "Acme" --pretty

# Paginate
pnpm elevasis-sdk client:list --limit 20 --offset 0 --pretty
```

**Options:** `--status <status>`, `--search <query>`, `--limit <n>`, `--offset <n>`, `--api-url <url>`, `--pretty`

Present as a compact table: name, status, source.

### `resolve <query>` -- Name-to-ID Resolution

Resolves a name, UUID, or search string to a canonical client record. This is the primary tool for name-to-ID translation before any `get`, `update`, or `delete` call.

```bash
pnpm elevasis-sdk client:resolve "Acme" --pretty
```

If multiple candidates match, the CLI returns candidates -- pick the right one and confirm with the user before proceeding. If zero match, surface the error and suggest `client:list --search "<query>"` to browse.

### `get <id>` -- Client Detail and Lineage

```bash
pnpm elevasis-sdk client:get <id> --pretty
```

Returns full client detail: name, status, source, source deal, linked primary company, primary contact, and metadata. Narrate the lineage in plain language (e.g. "Acme Corp -- active client, sourced from deal john@acme.com, linked to Acme Corp (acq_companies)").

### `create` -- Create Client (Confirm Ceremony)

**Always confirm before creating.** Collect required and optional fields, draft a summary, and ask the user to confirm before executing.

**Required:** `--name <name>`

**Optional:** `--status <status>`, `--source <source>`, `--source-deal-id <uuid>`, `--primary-company-id <uuid>`, `--primary-contact-id <uuid>`, `--metadata <json>`

```bash
pnpm elevasis-sdk client:create \
  --name "Acme Corp" \
  --status active \
  --source deal \
  --source-deal-id <deal-uuid> \
  --pretty
```

After creation, show the new client ID and suggest `/client get <id>` to verify.

### `update <id>` -- Update Client (Confirm Ceremony)

**Always confirm before updating.** Show the current state via `client:get <id>`, draft the proposed changes, and ask the user to confirm before executing.

**Options:** `--name <name>`, `--status <status>`, `--source <source>`, `--source-deal-id <uuid>`, `--clear-source-deal`, `--primary-company-id <uuid>`, `--clear-primary-company`, `--primary-contact-id <uuid>`, `--clear-primary-contact`, `--metadata <json>`

```bash
pnpm elevasis-sdk client:update <id> --status active --pretty
```

To clear a linked field, use the corresponding `--clear-*` flag (e.g. `--clear-source-deal`, `--clear-primary-company`, `--clear-primary-contact`). Do NOT pass an empty string -- it is rejected. Use the clear flag instead.

### `delete <id>` -- Delete Client (Destructive -- Explicit Confirmation Required)

**ALWAYS confirm before deleting.** Show the client record first (via `client:get <id>`), then ask the user explicitly: "Delete client `<name>` (`<id>`)? This cannot be undone." Only proceed after an affirmative confirmation.

```bash
pnpm elevasis-sdk client:delete <id> --pretty
```

---

## Client Inference

When the user refers to a client by name rather than ID, resolve using these steps (in priority order):

1. **Exact UUID** -- if the argument looks like a UUID, use it directly with `client:get`
2. **`client:resolve`** -- run `client:resolve "<name>"` to fuzzy-match by name; use the returned ID
3. **`client:list --search`** -- if `resolve` returns no match, search with `client:list --search "<name>"` and present candidates
4. **Context from conversation** -- if a specific client was resolved earlier in this session, prefer it
5. **Ambiguous** -- if multiple match or none match, show candidates and ask

---

## Natural Language Mode

When args do not match any command pattern, infer intent from natural language:

| User says                                         | Inferred operation                                          |
| ------------------------------------------------- | ----------------------------------------------------------- |
| "show me Acme"                                    | `resolve "Acme"` then `get <id>`                            |
| "who are our active clients"                      | `list --status active --pretty`                             |
| "client overview" / "how many clients do we have" | `status --pretty`                                           |
| "add a new client: Beta LLC"                      | `create --name "Beta LLC"` (confirm ceremony)               |
| "update Acme to active"                           | `resolve "Acme"` then `update <id> --status active`         |
| "delete the Gamma client"                         | `resolve "Gamma"` then `delete <id>` (explicit confirm)     |
| "link Acme to deal <uuid>"                        | `resolve "Acme"` then `update <id> --source-deal-id <uuid>` |
| "remove Acme's source deal"                       | `resolve "Acme"` then `update <id> --clear-source-deal`     |

---

## Safety Rules

1. **Always confirm create/update/delete** -- show proposed changes and ask the user before executing any write operation
2. **Explicit confirmation for delete** -- `client:delete` is irreversible; require an affirmative "yes" before running
3. **Organization scoping** -- all API calls are automatically org-scoped via `ELEVASIS_PLATFORM_KEY`; no `--org` flag is required
4. **Read before write** -- when updating, show current state via `client:get` before applying changes
5. **Use `--clear-*` flags to unlink** -- never pass empty strings to clear linked fields; use `--clear-source-deal`, `--clear-primary-company`, or `--clear-primary-contact`
6. **Template project assumption** -- the template is a single-organization project; all `/client` operations are scoped by `ELEVASIS_PLATFORM_KEY`; there is no cross-org capability

---

**Last Updated:** 2026-06-03
