---
name: waitlist
description: "Waitlist lifecycle — workflow-based extraction from public conversations, admin review, and scheduled automation."
tools:
  - waitlist-scan
  - waitlist-persist
  - waitlist-list
  - waitlist-review
  - waitlist-setup
  - waitlist-heal
always: false
embed: false
lifecycle: {"activate": "waitlist-setup", "heal": "waitlist-heal"}
metadata: {"platform":{"optional":true}}
---

# Waitlist

Manages the waitlist lifecycle: extracting sign-ups from public conversations, reviewing entries, and scheduling automatic extraction.

## How it works

The **only** intake path is public agent conversations. The public agent captures name and email in conversation (via the sales plugin). This plugin uses a **workflow** (3-step pipeline) to scan those conversation transcripts, extract structured contact details and customer discovery intelligence via LLM, and create Person nodes in the graph. There are no other sources: no email inboxes, no web forms, no external imports. Do not suggest or speculate about alternative sign-up sources.

### Extraction workflow

The extraction runs as a standard workflow (managed by the workflows plugin):

1. **Scan** (`waitlist-scan`) — queries all public conversations and returns structured transcripts
2. **LLM extraction** — sends transcripts to the model, which extracts identity (email, given name, family name) and discovery notes (business type, role, needs, challenges, interests, engagement quality, other signals). The extraction prompt is stored in the workflow and is visible via `workflow-get` and editable via `workflow-update`.
3. **Persist** (`waitlist-persist`) — creates/updates Person nodes idempotently via MERGE. Validates that extracted emails actually appear in source conversations (hallucination guard). Merges discovery notes with existing data (new signal enriches, never overwrites).

- Entries where both name and email are found get `status: 'waitlist'`.
- Entries where only an email is found (no name match) get `status: 'review'` — the admin resolves these manually.
- Discovery notes are stored as a JSON string on the Person node's `discoveryNotes` property.

### Modifying the extraction

The extraction prompt is stored in the workflow's LLM step. The user can:
- **View it:** `workflow-get "Waitlist lead extraction"` shows all steps including the prompt
- **Edit it:** `workflow-update` to change what fields are extracted, adjust instructions, or modify behaviour
- **Change the model:** update the LLM step's model field (defaults to the account's adminModel)

No code changes needed to modify extraction behaviour.

## When to use each tool

- `waitlist-scan` — Gather public conversation transcripts. Normally called by the extraction workflow, not directly. Returns structured JSON.
- `waitlist-persist` — Persist LLM extraction results as Person nodes. Normally called by the extraction workflow, not directly. Validates input and applies hallucination guard.
- `waitlist-list` — Show the admin their waitlist entries with discovery notes. Highlight the review count — entries needing name resolution.
- `waitlist-review` — Resolve flagged entries and view discovery context: add a name and change status from `review` to `waitlist` or `approved`. Also use to reject spam entries. Returns discovery notes alongside the status update.
- `waitlist-setup` — Create the extraction workflow and a recurring scheduled event that triggers it. Default: every 4 hours. Idempotent — if the workflow already exists, returns its details. Cleans up old-style extraction events automatically. To change the schedule, cancel the existing event (via `schedule-cancel`) and run `waitlist-setup` with the new recurrence.

## First-time setup

When the admin first asks about waitlist management or wants to see sign-ups, run `waitlist-setup` to create the extraction workflow and schedule. Then run `workflow-execute` on the created workflow to populate entries from existing conversations, followed by `waitlist-list` to show results.

## Relationship to other plugins

- **Sales plugin** — handles the public-facing conversation that captures name and email. The sales plugin collects; the waitlist plugin extracts and manages.
- **Contacts plugin** — waitlist entries are Person nodes (same schema). `contact-list` with `source: 'waitlist'` shows the same data. The waitlist tools add extraction and review workflows on top.
- **Workflows plugin** — the extraction runs as a standard workflow. The user manages the extraction prompt and execution through workflow tools.
- **Scheduling plugin** — `waitlist-setup` creates an Event node that triggers `workflow-execute` via the platform heartbeat. The admin can view and manage this event via scheduling tools.
