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
---

# /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.

Do NOT add custom styles, colors, or CSS overrides to ibl.ai SDK components.
They ship with their own styling. Keep the components as-is.
Do NOT implement dark mode unless the user explicitly asks for it.

When building custom UI around SDK components, use the ibl.ai brand:
- **Primary**: `#0058cc`, **Gradient**: `linear-gradient(135deg, #00b0ef, #0058cc)`
- **Button**: `bg-gradient-to-r from-[#2563EB] to-[#93C5FD] text-white`
- **Font**: System sans-serif stack, **Style**: shadcn/ui new-york variant
- Follow the component hierarchy: use ibl.ai SDK components
  (`@iblai/iblai-js`) first, then shadcn/ui for everything else
  (`npx shadcn@latest add <component>`). Do NOT write custom components
  when an ibl.ai or shadcn equivalent exists. Both share the same
  Tailwind theme and render in ibl.ai brand colors automatically.
- Follow [BRAND.md](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/BRAND.md) for
  colors, typography, spacing, and component styles.

> **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)