Iblai Vibe Crm Overview

---
name: iblai-vibe-crm-overview
description: Reference and family index for the ibl.ai Platform-scoped CRM REST API at /api/crm/ — auth, seeded defaults (default Pipeline + 6 stages + 4 Lead Sources), the four CRM RBAC roles (Viewer/User/Manager/Inviter), and the workflow sub-skill map. Use when the user mentions CRM, leads, pipelines, deals, contacts, or asks where a CRM workflow lives. The CRM workflow skills live in the DM skill set (iblai-dm-pro) as `crm-*`: see `crm-foundation` for auth/RBAC/notifications, `crm-contacts` + `crm-person-onboarding` for people, `crm-pipeline` for pipelines + deals, `crm-activities` for the timeline, `crm-tags` for tags; /iblai-vibe-auth for token wiring, /iblai-vibe-rbac for role assignment.
globs:
alwaysApply: false
metadata:
  kind: guide
---

# /iblai-vibe-crm-overview

Reference skill for the ibl.ai CRM. Covers authentication, seeded
defaults, the four CRM RBAC roles, and indexes the CRM workflow skills
— the `crm-*` skills in the DM skill set (`iblai-dm-pro/.claude/skills/`).
This skill builds no UI — open it first when you need orientation, then
jump to the workflow skill that matches the surface you are building.

> **Common setup (brand, conventions, env files, verification):** see [docs/skill-setup.md](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/docs/skill-setup.md).

## Authentication

Every CRM endpoint lives under `/api/crm/` and requires a
Platform-scoped token:

```
Authorization: Token <your-access-token>
```

Tokens bind to exactly one Platform at the moment of issue. The
Platform is inferred from the token on every request — there is no
`?platform_key=` query parameter on the consumer surface, and supplying
one will not change the Platform a request resolves to.

Records belonging to a different Platform return **`404 Not Found`,
never `403 Forbidden`**. This is intentional: returning `403` would
leak the existence of cross-Platform records. Treat a `404` on a
record you just created as a sign you are pointing at the wrong
Platform; a `403` always means "authenticated but the role does not
grant this action."

The full REST contract (base URL, pagination envelope, ID types per
resource, side effects) is in
[`references/api-overview.md`](./references/api-overview.md). For
token wiring inside a Next.js app see `/iblai-vibe-auth`.

## Seeded defaults

The first time a Platform is provisioned, the CRM seeds a working
configuration. You do not need to create any of these yourself — they
exist on every Platform and back-fill into existing Platforms via a
data migration.

- **One default Pipeline** with `code="default"`, `is_default=true`,
  `rotten_days=30`.
- **Six default Stages** on that Pipeline, referenced by stable `code`:
  `new` → `qualified` → `proposal` → `negotiation` → `won` (terminal,
  `is_won=true`) and `lost` (terminal, `is_lost=true`).
- **Four default Lead Sources**: `web`, `referral`, `cold_call`,
  `advertisement`.

The stage and lead-source `code` fields are stable across environments
(dev / staging / prod) and across renames. Numeric `id` values are not
— always reference seeds by `code` in client code, save the pipeline
`id` only for the immediate deal payload.

Full seeded tables (every stage's `probability` / `sort_order` /
terminal flags, every lead source `name`) are in
[`references/seeded-defaults.md`](./references/seeded-defaults.md).

## RBAC

The CRM ships four roles per Platform. Roles are seeded automatically
on Platform provisioning and assigned through the standard
role-management surface — the CRM does not expose its own
role-assignment endpoints. A user may hold more than one role;
effective permissions are the union.

| Role | One-line mandate |
|---|---|
| **CRM Viewer** | Read everything across the CRM. Write nothing. |
| **CRM User** | Day-to-day operator — full CRUD on people, organizations, deals, activities, tags. Pipelines are read-only. No invitations. |
| **CRM Manager** | Wildcard CRM access — pipeline / stage / lead-source administration plus invitations. |
| **CRM Inviter** | Narrow role — read people and send invitations only. Cannot edit or create people. |

Two non-obvious rules worth a second look:
- **Invitation is its own bucket.** `Ibl.CRM/Persons/write` does not
  imply `Ibl.CRM/Invite/action`. Gate the "Invite" affordance
  independently.
- **Tag attach/detach requires `Ibl.CRM/Tags/write`.** A role with
  `Ibl.CRM/Persons/write` cannot tag a person without it.

Full HTTP-verb → action-code mapping and the action-by-action matrix
are in [`references/rbac-matrix.md`](./references/rbac-matrix.md). For
the management UI that lists and binds roles, see `/iblai-vibe-rbac`.

## The CRM skill family

The CRM workflow skills live in the **DM skill set**
(`iblai-dm-pro/.claude/skills/`), named `crm-*` — this
`iblai-vibe-crm-overview` skill is the index. Read `crm-foundation`
first, then pick the skill that matches the surface you are building.

| Skill | Covers |
|---|---|
| `crm-foundation` | **Read first** — auth, Platform scoping, pagination envelope, error model, the four RBAC roles + `Ibl.CRM/*` verbs, the three CRM notification types (`CRM_PERSON_CREATED`, `CRM_DEAL_STAGE_CHANGED`, `CRM_PERSON_LINKED_TO_USER`), the metadata escape hatch, and the cross-cutting tagging pattern |
| `crm-contacts` | Person + Organization CRUD, list filters (lifecycle stage / owner / organization / date / tags), tag attach / detach |
| `crm-person-onboarding` | Person lifecycle — `/link-user/`, `/invite/`, `/merge/`, the dedup triage (link vs invite vs merge), and the separate `Ibl.CRM/Invite/action` bucket |
| `crm-pipeline` | Pipelines, Stages, Lead Sources, Deals CRUD + the deal state machine (`/move-stage/`, `/won/`, `/lost/`), kanban fetch, Deal tag attach / detach |
| `crm-activities` | Activity CRUD, the `/done/` action, schedule + reminder fields, and the timeline (incl. auto-Activities from Deal stage transitions) |
| `crm-tags` | Tag CRUD, hex-color contract, name uniqueness per Platform, cascade delete, attach / detach convention |

When in doubt, start with `crm-contacts` (a deal needs a person), then
`crm-pipeline`, then layer `crm-activities` and `crm-tags` on the detail
pages. CRM notifications are covered in `crm-foundation`.

## Related skills

- `crm-foundation` — auth, pagination, RBAC, notifications, tagging (read first)
- `crm-contacts` — People + Organizations + list filters
- `crm-person-onboarding` — link / invite / merge + dedup triage
- `crm-pipeline` — Pipelines + Stages + Lead Sources + Deals
- `crm-activities` — Activity timeline for persons and deals
- `crm-tags` — Tag CRUD + attach / detach
- `/iblai-vibe-auth` — Token wiring; every CRM call uses the same
  `Authorization: Token <token>` header.
- `/iblai-vibe-rbac` — Role-management UI (`<Admin>` → Roles + Policies
  tabs) and the action-definitions endpoint. The four CRM roles are
  assigned here.
- **Brand guidelines**: [BRAND.md](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/BRAND.md)