@elitedcs/ghl-mcp 3.53.2 → 3.55.0

package/skills/blueprint/references/intake-question-set.md

@@ -0,0 +1,141 @@
+# Intake Question Set — v1.1 (hand-off to ghl-command-mcp)
+
+STATUS: FINAL for v1.1, 2026-06-15. Owner: atlas (wording/labels) → ghl-command-mcp (builds the form-template installer from this). Jerry approves the final set. **v1.1 adds 3 keys** (`team_size`, `monthly_lead_volume`, `business_hours`) per Jerry's 2026-06-15 ruling — see "Ratified additions" at the bottom.
+
+This is the canonical list of questions the installed intake form asks. It is the **built-in fallback brief source** (schema §2A path B) — the path taken when no partner OS (Agency OS) is detected or the subscriber declines it. It is the FLOOR: the form is installed regardless, because it is the only path when no partner OS is present.
+
+**Contract rule honored:** the 25 original `key`s below are unchanged from schema §3 (changing a key is a contract change). Only wording/labels/options/help text are finalized here. **3 keys were ADDED** (`team_size`, `monthly_lead_volume`, `business_hours`) per Jerry's 2026-06-15 ruling — a coordinated contract change: command-center folds them into schema §3 + §6, ghl-command-mcp adds them to the installer. They are integrated into the sections below (Section A: A6–A8) and the Key → Brief map; the atlas-owned dataType + brief-path decisions are documented under "Ratified additions" at the bottom.
+
+Each question maps 1:1 to a Brief field (schema §4) via its `key`. The mapping column is authoritative for the normalizer.
+
+---
+
+## How the installer should read this
+
+- The form is **account-agnostic**: installed into whatever `get_current_location` returns, zero hardcoded IDs.
+- The form needs the **standard GHL contact fields** too (first name, last name, email, phone) — these carry the submitter/contact identity and are not business-profile `key`s. They are not in the table below; add them as the form's standard contact block. The business-profile answers below populate the Brief.
+- `required: true` questions are the minimum to generate a usable plan. Everything else is optional; the skill omits unknowns (never emits `null`) and notes safe defaults.
+- Field types use GHL form field types. Where a question offers fixed choices, the options are listed verbatim; the installer should use these exact option labels (the normalizer matches on them).
+- Sections A–F are display groupings (use as form sections/page breaks); they are not part of the contract.
+
+---
+
+## Section A — Business basics
+
+| # | Label (client sees) | `key` | Type | Required | Options / help |
+|---|---|---|---|---|---|
+| A1 | Business name | `business_name` | text | yes | Your business or brand name, as you want it to appear. |
+| A2 | What kind of business is this? | `business_type` | dropdown | yes | Options: `Med spa`, `Clinic / practice`, `Coach / consultant`, `Ecommerce`, `Local service`, `Agency`, `Other`. *(Drives preset selection.)* |
+| A3 | Website | `website` | url | no | If you have one. Leave blank if not. |
+| A4 | Primary location | `primary_location` | text | no | City, State/Country. Used for tone + scheduling. |
+| A5 | Time zone | `timezone` | dropdown | yes | Standard IANA time-zone list (e.g. `America/Phoenix`). Drives appointment hours and send windows. |
+| A6 | How many people work your leads? | `team_size` | dropdown | no | Options: `Just me`, `2-5`, `6+`. Sizes how much human follow-up vs automation we build (and opportunity assignment / round-robin). |
+| A7 | Roughly how many new leads per month? | `monthly_lead_volume` | dropdown | no | Options: `Under 100`, `100-500`, `500-1000`, `1000+`. Sizes SMS phone numbers (~1 per 500/mo) and send volume. Leave blank if unsure. |
+| A8 | Your business hours | `business_hours` | textarea | no | e.g. "Mon-Fri 9-6, Sat 10-2". Sets your calendar's default booking hours. Leave blank for Mon-Fri 9-5. |
+
+## Section B — Offer and pricing
+
+| # | Label | `key` | Type | Required | Options / help |
+|---|---|---|---|---|---|
+| B1 | What do you sell? | `core_offer` | textarea | yes | One or two sentences. The main thing a customer buys from you. |
+| B2 | Your main offers and prices | `price_points` | textarea | no | List your key offers with prices, one per line (e.g. "New client consult — $19"). |
+| B3 | Free offer / lead magnet | `lead_magnet` | text | no | A free thing you give to capture a lead (assessment, guide, trial). Leave blank if none. |
+| B4 | Average sale value | `avg_deal_value` | text | no | Roughly what a new customer is worth on the first purchase. |
+
+## Section C — Audience
+
+| # | Label | `key` | Type | Required | Options / help |
+|---|---|---|---|---|---|
+| C1 | Who is your ideal customer? | `ideal_customer` | textarea | yes | Who you serve best. Be specific (age, situation, what they want). |
+| C2 | What problems do they come to you with? | `top_pain_points` | textarea | no | The top pains/frustrations that bring them in. One per line is fine. |
+| C3 | Why do prospects hesitate? | `objections` | textarea | no | The objections you hear most (price, trust, timing, fear). |
+
+## Section D — Goal and sales process
+
+| # | Label | `key` | Type | Required | Options / help |
+|---|---|---|---|---|---|
+| D1 | What should this account do first and best? | `primary_goal` | dropdown | yes | Options: `Book appointments`, `Capture + nurture leads`, `Direct sales`, `Re-engage past clients`, `Other`. *(Drives the workflow + pipeline spine.)* |
+| D2 | The steps a lead moves through, from new to won | `sales_stages` | textarea | no | Name the stages in order (e.g. "new lead → contacted → consult booked → showed → sold → repeat"). If blank, we use a sensible default for your business type. *(Drives pipeline stages.)* |
+| D3 | Do customers book appointments with you? | `booking_needed` | radio (yes/no) | yes | Yes if you take consults/appointments. *(Drives whether a calendar is built.)* |
+| D4 | Follow-up style | `follow_up_style` | dropdown | no | Options: `High-touch / multi-step`, `Light`, `Single confirmation`. How aggressively to follow up. |
+
+## Section E — Channels and tech
+
+| # | Label | `key` | Type | Required | Options / help |
+|---|---|---|---|---|---|
+| E1 | Is your business email sending set up? | `email_ready` | radio (yes/no) | no | Yes if you have a sending domain / mailbox connected in GHL. |
+| E2 | Do you want to send text messages (SMS)? | `sms_desired` | radio (yes/no) | no | Yes flags the A2P registration step you'll need to complete. |
+| E3 | A2P / SMS registration status | `a2p_status` | dropdown | no | Options: `Not started`, `In progress`, `Approved`, `Not needed`. |
+| E4 | Payment processing | `payment_processor` | dropdown | no | Options: `Stripe connected`, `Stripe not connected`, `Other`, `None`. *(Flags the Stripe handoff if you sell on a page.)* |
+| E5 | Is your calendar connected? | `calendar_connected` | radio (yes/no) | no | Yes if your Google/Outlook calendar is already authorized in GHL. *(Flags the OAuth handoff if booking is needed and this is no.)* |
+| E6 | Which channels do you post on? | `social_channels` | multiselect | no | Options: `Instagram`, `Facebook`, `TikTok`, `YouTube`, `LinkedIn`, `Google Business`, `None`. |
+
+## Section F — Assets on hand
+
+| # | Label | `key` | Type | Required | Options / help |
+|---|---|---|---|---|---|
+| F1 | Do you already have a pipeline built? | `existing_pipeline` | radio (yes/no) + textarea | no | If yes, describe it briefly so we don't duplicate it. |
+| F2 | Anything already built we should not touch? | `existing_workflows` | textarea | no | List workflows/automations already live that we must leave alone. *(Becomes the do-not-clobber guardrail for the executor.)* |
+| F3 | Brand assets | `brand_assets` | text | no | Logo, colors, domain available — whatever you have. |
+| F4 | Anything else we should know? | `anything_else` | textarea | no | Constraints, compliance limits, preferences, context. |
+
+---
+
+## Key → Brief field map (authoritative for the normalizer)
+
+| `key` | Brief field (§4) |
+|---|---|
+| `business_name` | `business.name` |
+| `business_type` | `business.type` + `preset` (selection) |
+| `website` | `business.website` |
+| `primary_location` | `business.location` |
+| `timezone` | `business.timezone` |
+| `team_size` | `business.teamSize` (enum) |
+| `monthly_lead_volume` | `business.monthlyLeadVolume` (enum) |
+| `business_hours` | `business.hours` |
+| `core_offer` | `offer.summary` |
+| `price_points` | `offer.pricePoints` (parse `[{name, price}]` per line) |
+| `lead_magnet` | `offer.leadMagnet` |
+| `avg_deal_value` | `offer.avgDealValue` |
+| `ideal_customer` | `audience.ideal` |
+| `top_pain_points` | `audience.painPoints` (split lines → array) |
+| `objections` | `audience.objections` (split lines → array) |
+| `primary_goal` | `goal.primary` |
+| `sales_stages` | `goal.salesStages` (split → array of stage names) |
+| `booking_needed` | `goal.bookingNeeded` (bool) |
+| `follow_up_style` | `goal.followUpStyle` |
+| `email_ready` | `channels.email` (bool) |
+| `sms_desired` | `channels.sms` (bool) |
+| `a2p_status` | `channels.a2pStatus` |
+| `payment_processor` | `channels.payment` |
+| `calendar_connected` | `channels.calendarConnected` (bool) |
+| `social_channels` | `channels.social` (array) |
+| `existing_pipeline` | `assets.existingPipeline` |
+| `existing_workflows` | `assets.existingWorkflows` |
+| `brand_assets` | `assets.brand` |
+| `anything_else` | `assets.notes` |
+
+### Derived `flags` (normalizer computes, not asked)
+- `needs_a2p` ← `sms_desired == yes` AND `a2p_status != approved`
+- `stripe_not_connected` ← `payment_processor == "Stripe not connected"`
+- `calendar_oauth_needed` ← `booking_needed == yes` AND `calendar_connected == no`
+- `email_domain_needed` ← `email_ready == no`
+
+---
+
+## Ratified additions — folded in 2026-06-15 (Jerry)
+
+These three keys came up while reconciling against the CLL 49-field form and Module 0 prereqs. **Jerry ratified adding all three on 2026-06-15** (`outbox/2026-06-15-to-atlas-intake-decisions.md`, decision #1, overriding the earlier "ship without"). They are now in the installed set above (Section A: A6–A8) and the Key → Brief map. Adding them is a coordinated contract change: **command-center** folds the keys into schema §3 + §6; **ghl-command-mcp** adds them to the form-template installer. All three are **optional** (the required floor is unchanged), so the skill still degrades gracefully when a subscriber leaves them blank.
+
+atlas-owned wording decisions — the dataType + brief path proposed for cc (§3/§6 fold-in) and mcp (installer):
+
+| `key` | Form type | GHL `dataType` | Brief path (§4) | Brief type | Option labels | Drives in plan |
+|---|---|---|---|---|---|---|
+| `team_size` | dropdown | `SINGLE_OPTIONS` | `business.teamSize` | enum | `Just me`, `2-5`, `6+` | speed-to-lead human-follow-up sizing + opportunity assignment / round-robin; calendar staff hint |
+| `monthly_lead_volume` | dropdown | `SINGLE_OPTIONS` | `business.monthlyLeadVolume` | enum | `Under 100`, `100-500`, `500-1000`, `1000+` | SMS phone-number count for the clinic_launch_a2p preset (~1 per 500/mo) + send-volume sizing |
+| `business_hours` | textarea | `LARGE_TEXT` | `business.hours` | string | — (free text) | calendar `openHours` defaults (replaces the generic Mon-Fri 9-5); parsed + operator-editable |
+
+Fold-in notes:
+- **`monthly_lead_volume` refined from the original "(text)" proposal → dropdown buckets (`SINGLE_OPTIONS`).** Free text ("a few hundred?") is unparseable for the 1-number-per-500 math; fixed buckets map cleanly to a phone-number count. Flagging the type change explicitly so the installer builds a dropdown, not a text field.
+- All three land under the Brief's `business.*` namespace (new sub-keys `teamSize`, `monthlyLeadVolume`, `hours`) — purely additive, no existing field changes, so `schemaVersion` stays `0.1`.
+- No new derived `flags`. `monthly_lead_volume` is read directly by the clinic_launch_a2p preset at phone-provisioning time; absent → the preset keeps its current ask-at-handoff default. `business_hours` absent → skill keeps the Mon-Fri 9-5 default + operator-edit flag. `team_size` absent → skill keeps "automate first touch, human follow-up light."

package/skills/blueprint/references/preset-format.md

@@ -0,0 +1,130 @@
+# Preset Format & Versioning
+
+STATUS: v1, 2026-06-15. Owner: atlas. Defines how Intake-to-Build presets are authored, versioned, and consumed by the plan-gen skill. Ratifies schema §7 item 4 (preset → plan determinism).
+
+## What a preset is
+
+A preset is a **build-plan template**: it is authored in the exact vocabulary of the §5 build-plan (refs, logical actions, handoffs), with two additions — **template tokens** that the skill fills from the brief, and **`conditionalOn`** flags that the skill evaluates to add or drop items. The preset sets the *skeleton*; the brief fills the *specifics*.
+
+This keeps preset → plan **deterministic** and keeps the preset in the same shape the operator reviews and the phase-2 executor consumes. There is no separate "preset language" to learn beyond §5 + the two additions below.
+
+> Ratification of §7 #4: **the preset fixes the skeleton** (pipeline stage *set*, the workflow *set*, the asset *list*, the handoff *set*, default copy direction). **The brief fills** names, copy, toggles, and any list the brief overrides (e.g. stages from `goal.salesStages`). **Brief `flags` add or drop conditional items.** The skill does not invent structure the preset does not declare; it only fills, drops, and expands. Same brief + same preset version → same plan skeleton, every time.
+
+## File layout
+
+Each preset is two files in `intake-to-build/presets/`:
+
+- `<preset-id>.preset.json` — the machine-readable template the skill loads.
+- `<preset-id>.md` — a human companion: what this preset builds, when it is selected, and the source it was harvested from. (Reviewers read this; the skill reads the JSON.)
+
+## Preset JSON envelope
+
+```jsonc
+{
+  "presetId": "med_spa",
+  "presetVersion": "1.0.0",      // semver; bump on any skeleton change
+  "schemaVersion": "0.1",         // the build-plan schema this targets
+  "title": "Med Spa",
+  "description": "One-line summary.",
+  "default": true,                // exactly one preset across the library is the default
+  "selectors": {                  // how the skill picks this preset
+    "businessTypes": ["Med spa","Medical spa","Medical aesthetics","Aesthetics"],
+    "aliases": ["med_spa","medspa","medical_spa","aesthetics","injectables"]
+  },
+  "source": "ghl-command showcase Modules 0-7 + proven Bliss / Lux Bio med-spa builds",
+  "skeleton": { /* §5 build-plan shape with tokens + conditionalOn, see below */ }
+}
+```
+
+`selectors.businessTypes` are the `business_type` answers that route to this preset. `selectors.aliases` are the `brief.preset` enum values that resolve to this preset (e.g. `preset: "med_spa"` resolves to the med-spa preset, which claims that alias). Exactly one preset across the library has `"default": true` — currently **`med_spa`** (the reference preset). `generic` is `default:false`, the neutral fallback reached via its `businessTypes`.
+
+## The `skeleton` object
+
+`skeleton` mirrors the §5 build-plan top level — `pipelines`, `customFields`, `tags`, `customValues`, `calendars`, `forms`, `funnels`, `emails`, `sms`, `workflows`, `handoffs`. Every item is a §5 object, optionally annotated with:
+
+### 1. Template tokens — `{{ ... }}`
+A `{{path}}` inside any string field is replaced with the brief value at that path. Dotted paths read the brief (`{{business.name}}`, `{{offer.summary}}`). Supports a fallback with `||`:
+
+```jsonc
+{ "ref": "pipeline.main", "name": "{{business.name}} Pipeline || Patient Journey" }
+```
+
+If `business.name` is present, it fills; otherwise the literal after `||` is used. A token that resolves to empty with no fallback → the skill omits the field (never emits an empty string) and notes the default it used.
+
+### 2. `conditionalOn` — include/drop the whole item
+A string boolean expression over the brief. If it evaluates false, the skill **drops the item entirely** (and anything that referenced it — the skill prunes dangling refs and records the prune in the plan summary). Grammar is intentionally tiny:
+
+- `goal.bookingNeeded == true`
+- `channels.sms == true`
+- `flags includes needs_a2p`
+- `channels.payment != "Stripe connected"`
+- combine with `&&` / `||`
+
+```jsonc
+{ "ref": "calendar.consult", "conditionalOn": "goal.bookingNeeded == true", "name": "Consultation", ... }
+{ "ref": "handoff.a2p",      "conditionalOn": "flags includes needs_a2p", ... }
+```
+
+### 3. `fillFrom` — populate a list from the brief, else the preset default
+For list-valued structure the brief can override (the clearest case is pipeline stages):
+
+```jsonc
+{
+  "ref": "pipeline.main",
+  "name": "{{business.name}} Pipeline || Sales Pipeline",
+  "stages": {
+    "fillFrom": "goal.salesStages",
+    "transform": "stageList",     // skill turns ["new lead","contacted",...] into [{ref,name,position}]
+    "default": [
+      { "ref": "stage.new_lead",  "name": "New Lead",  "position": 0 },
+      { "ref": "stage.contacted", "name": "Contacted", "position": 1 }
+      /* ... preset's own default stage set ... */
+    ]
+  }
+}
+```
+
+If `goal.salesStages` is non-empty, the skill builds the stage list from it (slugging each name into a `stage.<slug>` ref, assigning positions in order). If empty, it uses `default`. Workflows that point at `stage.*` refs resolve against whichever set won; if a referenced stage is not in the chosen set, the skill maps it to the nearest equivalent or notes the gap (it never ships a dead ref).
+
+### 4. `copyDirection` — outline guidance for copy assets
+On `emails`/`sms`/`funnels[].pages`, `copyDirection` is the instruction the skill turns into a `bodyOutline` (default) or full copy (on expansion — see RATIFICATION §3). Tokens and brief context (offer, audience, and `extended` ICA/offer/voice when partner-OS-sourced) ground the copy.
+
+```jsonc
+{ "ref": "email.welcome_1", "name": "Welcome 1",
+  "subject": "Welcome to {{business.name}}",
+  "copyDirection": "Thank them for reaching out; restate the core offer in their language; set expectation for next step; CTA to book. Warm, concrete, no hype.",
+  "mergeTags": ["contact.first_name"] }
+```
+
+## The skill's deterministic fill algorithm (consumes a preset)
+
+1. Resolve preset (brief.preset alias → preset, else business_type → preset, else default).
+2. Deep-copy `skeleton`.
+3. Evaluate every `conditionalOn`; drop false items; prune now-dangling refs (record prunes).
+4. Resolve every `fillFrom` (brief override or default), slug refs, assign positions.
+5. Substitute every `{{token}}` (with `||` fallback); omit-and-note where empty.
+6. Derive flag-driven handoffs not already present (a2p, stripe, calendar_oauth, add_staff, email_domain).
+7. Turn each `copyDirection` into a `bodyOutline` (or full copy on expansion).
+8. Set `buildOrder`, compute `summary`, leave `idMap` empty.
+9. Run the quality gate (SKILL.md), fix, then render the §5A approval view.
+
+Steps 2–6 are pure and order-independent of the model's discretion — that is what makes the skeleton deterministic. Step 7 (copy) is the only generative step, and it is grounded in the brief, gated, and editable at review.
+
+## Enum discipline (must pass the mcp validators)
+
+Presets must use GHL-correct enum values so the emitted plan passes ghl-command-mcp's Zod / JSON-Schema validators (their §7 #1 ratification):
+
+- `customFields[].dataType` ∈ `TEXT`, `LARGE_TEXT`, `NUMERICAL`, `PHONE`, **`MONETORY`** (GHL's own spelling — NOT "MONETARY"), `CHECKBOX`, `SINGLE_OPTIONS`, `MULTIPLE_OPTIONS`, `FLOAT`, `DATE`, `TEXTBOX_LIST`, `FILE_UPLOAD`, `SIGNATURE`. Choice types (`SINGLE_OPTIONS`/`MULTIPLE_OPTIONS`/`CHECKBOX`) MUST carry an `options` array.
+- `calendars[].calendarType` ∈ `round_robin`, `event`, `class_booking`, `collective`, `service_booking`.
+- `customFields[].model` ∈ `contact`, `opportunity`.
+- **Trigger `type`** ∈ the executor's native set so triggers auto-build: `contact_tag`, `form_submission`, `appointment` (+ `appointmentStatus`), `customer_reply`, `pipeline_stage_updated`, `inbound_webhook`, `payment_received`. `form_submitted`/`contact_replied` are accepted aliases; `tag_added`/`appointment_status`/`appointment_booked` are NOT recognized (they surface as a manual step) — never use them in a preset.
+- handoff `owner` ∈ **`OPERATOR-UI`**, **`OPERATOR-EXT`**, **`TEAM`** (customer-facing, generic). The MCP still accepts + normalizes the legacy `JERRY-UI`/`JERRY-EXT`/`SASHA`, but presets EMIT the canonical labels.
+- `internal_notification.to` carries the `{{operator.userId}}` token (the skill resolves a real GHL user id from `get_users` at fill time — a non-user value is an unpublishable notify-all).
+
+> The schema §5 contract (v0.3) and the live Zod schema (`src/intake-to-build/plan.ts`) are the sources of truth; the `MONETARY`/`MONETORY` spelling note is RESOLVED (the contract example was corrected in §7 #1). If the doc and the Zod schema ever disagree, the Zod schema wins.
+
+## Versioning & distribution
+
+- **Version:** semver in `presetVersion`. Patch = copy/wording; minor = additive items; major = removed/renamed refs or changed skeleton shape. The generated plan records which preset+version produced it in its `summary` line so a build is reproducible.
+- **Distribution:** presets ship **alongside the skill** (the `intake-to-build/presets/` directory travels with `SKILL.md` in whatever package distributes the skill — the same mechanism, TBD, that distributes the Founder Operating Pack). They are not in the MCP package; the MCP consumes the *plan*, not the preset. Adding a preset = drop two files in `presets/` and give it a `selector`; no skill code change.
+- **Authoring a new preset:** copy `generic-client.preset.json`, change `presetId`/`title`/`selectors`/`default:false`, edit the skeleton, write the `.md` companion. The skill picks it up by selector.