/iblai-vibe-crm-overview

Mirrored from iblai/vibe · skills/organizations/iblai-vibe-crm-overview/SKILL.md. This page is generated — edit it in the repository, not here.

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.

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

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

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

/iblai-vibe-crm-overview

Authentication

Seeded defaults

RBAC

The CRM skill family

Related skills