# Support Overview

> Curated runbook for the support team's MCP-driven Claude assistant. **Read this once at the start of a new dealer support topic** - it gives you the system vocabulary, points you at the right deeper docs, and captures tribal knowledge that doesn't fit anywhere else.

## How to use this doc

You're answering dealer support questions through Claude Code with access to live dealer/Stripe data plus this docs MCP. The general flow:

1. **Read the dealer's question.** What category does it fit? (Custom domain, billing, login, etc. - see scenarios below.)
2. **Check live data first** with `search_dealers` / `get_dealer` / `search_users` / `get_user` / `get_stripe_info`. Many "site is broken" reports turn out to be data lookups (subdomain typo, status mismatch).
3. **Consult the right doc** via `search_docs` and `get_doc` for behavior/policy questions.
4. **Trust live data over docs** when they disagree. Docs describe how things SHOULD work; the database describes what IS true. Flag the discrepancy if you see one.

## System vocabulary

**Dealer status values** (`dealer.status`):

- `pending` - registration started, not complete
- `registration_pending` - payment not yet captured
- `registration_complete` - paid, awaiting deal completion
- `active` - live, fully working
- `cancelled_pending` - cancellation requested, period not yet ended (still active until renewal)
- `cancelled` - terminated
- `suspended` - admin-suspended
- `payment_failed` - billing problem; site may be inactive

**Subscription tiers** (`dealer.subscriptionTier`):

- `starter` - basic site (annual-only, $48/yr)
- `growth` - adds SEO and feature improvements ($25/mo, $300/yr)
- `enhanced` - slider editing, social integration ($50/mo, $600/yr)
- `professional` - full CMS ($200/mo, $2400/yr)

**Custom domain addon** - separate $36/yr add-on available to any tier (most commonly purchased by Starter dealers who want a custom URL without upgrading the whole plan). Tracked on its own fields, **not** as a tier value:

- `dealer.hasCustomDomainAddon` (boolean) - does the dealer have an active addon
- `dealer.customDomainAddonStatus` (`none | active | cancelled`) - current addon status
- `dealer.customDomainAddonSubscriptionId` - the Stripe subscription ID for the addon

A Starter dealer with the addon still has `subscriptionTier === 'starter'`; the addon is an additive flag, not a different tier.

**Grandfathered custom domain access** - a separate path that predates the addon. Some legacy/migrated dealers retain free custom-domain access regardless of tier:

- `dealer.hasGrandfatheredCustomDomain` (boolean) - if `true`, the dealer keeps custom-domain access without paying for the addon and without upgrading to Growth+

When triaging "why does this Starter dealer have a custom domain?", check both `hasCustomDomainAddon` (paid addon) and `hasGrandfatheredCustomDomain` (legacy free access). Admins can toggle the grandfathered flag at `/admin/dealers/[id]` → custom-domain row.

See [PLAN_FEATURES_MATRIX.md](./PLAN_FEATURES_MATRIX.md) for the per-tier feature matrix and [billing/README.md](./billing/README.md) for the charge-identification cheatsheet.

**Custom domain status** (`dealer.customDomainStatus`):

- `none | pending | verified | active | failed` - see [DEALER_DASHBOARD.md](./DEALER_DASHBOARD.md) "Support Triage" section for the decoder.

**Domain suffixes** - exactly four valid values: `myamsoil.com`, `shopamsoil.com`, `myamsoil.ca`, `shopamsoil.ca`. See [subdomains/README.md](./subdomains/README.md) "Valid dealer site URL formats" for full table.

## Common scenarios

### 1. Custom domain not connecting / "no record found"

**What dealers say:** "I added the DNS records but the site doesn't work." / "It says 'no record found' when I click Check My DNS."

**Check:** `get_dealer` → `customDomain`, `customDomainStatus`.

**Tell them:** Send them to `/dashboard/settings/domains` - that page shows their personal CNAME target value and the "Check My DNS" button. Decode their `customDomainStatus` from [DEALER_DASHBOARD.md](./DEALER_DASHBOARD.md) Support Triage section. For legacy A-record dealers, the value is `69.169.111.27`. DNS propagation is usually <1h, up to 24h.

**Deeper:** [DEALER_DASHBOARD.md](./DEALER_DASHBOARD.md) (Custom Domain Configuration + Support Triage), [subdomains/README.md](./subdomains/README.md).

### 2. Cancel subscription / update payment method

**What dealers say:** "How do I cancel?" / "Where do I update my card?"

**Tell them:** `/dashboard/subscription` → click **Manage Billing & Invoices**. The Stripe customer portal handles cancellation, card updates, and invoice history. Cancellations are at-period-end - they remain active until the next renewal and aren't billed again.

**Deeper:** [billing/README.md](./billing/README.md) Common Support Scenarios, [STRIPE_CUSTOMER_PORTAL.md](./STRIPE_CUSTOMER_PORTAL.md).

### 3. "I was billed after I cancelled"

**Check:** `get_dealer` → `status`. If `cancelled_pending`, the last invoice covers the remainder of the period and is correct. If `cancelled` and a new charge appears, look for duplicate accounts under different emails (use `search_users` with name/phone).

**Deeper:** [TIER_TRANSITIONS.md](./TIER_TRANSITIONS.md), [billing/README.md](./billing/README.md).

### 4. Tier upgrade/downgrade - "weird charge" / "what is this $X?"

**Check:** `get_stripe_info { dealer_id }` for recent invoices. Mid-cycle tier changes prorate - you'll see a small partial-period charge alongside the regular renewal.

**Tell them:** Plain-English proration explanation in [billing/README.md](./billing/README.md). Identify the charge using the cheatsheet there.

**Deeper:** [PLAN_FEATURES_MATRIX.md](./PLAN_FEATURES_MATRIX.md), [TIER_TRANSITIONS.md](./TIER_TRANSITIONS.md), [billing/README.md](./billing/README.md).

### 5. Can't log in

**Check:** `get_user { id }` → `accounts` array. The `provider` field tells you the original signup method (`google`, `apple`, or `credentials`).

**Tell them:** If they used Google/Apple originally, they need to use that same button - not email/password. There is no password to reset for OAuth users.

**Deeper:** [auth/README.md](./auth/README.md) Common Login Failures, [AUTH_EMAIL_NORMALIZATION.md](./AUTH_EMAIL_NORMALIZATION.md).

### 6. Site not on Google

**Check:** `get_dealer` → `subdomain`, `lastPublishedAt`. The clock starts when the subdomain is first set, not at account creation.

**Tell them:** Indexing typically takes ~7 days from going live. <7 days: sit tight. 7–14 days: should be soon. >14 days: escalate.

**Deeper:** [SEO_INDEXING.md](./SEO_INDEXING.md).

### 7. Dealer can't find their site / "site is down" but you find them

**Common causes:**

- Domain-suffix confusion: dealer thinks they're at `name.shopamsoil.com` but actually at `name.myamsoil.com` (or `.ca` variants).
- Status is `suspended` or `payment_failed` (active in DB but not serving).
- Custom domain is `pending` and they expect it to be live.

**Tell them:** Their actual URL is `<subdomain>.<their-actual-suffix>`. Confirm with `get_dealer`.

**Deeper:** [subdomains/README.md](./subdomains/README.md) Valid dealer site URL formats.

### 8. Dealer wants us to change logo / address / header text / etc.

**Tell them:** Most fields are self-serve - see [DEALER_EDITORS.md](./DEALER_EDITORS.md) Self-Serve Quick Reference table. Logo, business name/address/phone, header text, and tracking scripts all live on `/dashboard/editor`. Media library uploads are at `/dashboard/media`. Slider images are at `/dashboard/slider-editor` (Enhanced+ tier only). Custom domain setup is at `/dashboard/settings/domains` (the settings page is currently domains-only).

Truly admin-only: subdomain change after creation, dealer number change. Escalate those.

**Deeper:** [DEALER_EDITORS.md](./DEALER_EDITORS.md), [DEALER_DASHBOARD.md](./DEALER_DASHBOARD.md).

### 9. "I paid for a year but my site is down" - and you can't find their account

**Common causes:**

- They signed up with a different email than they're contacting from. Search by phone, name, business name.
- Account is `cancelled` (still in DB, just not active).
- They're confused about which product (their AMSOIL dealer membership is separate from the website subscription).

**Action:** Try multiple `search_users` and `search_dealers` queries. If `cancelled`, direct them to re-subscribe at `amsoil.aimclear.com`.

### 10. Pre-signup / brand new dealer questions

"How long does setup take?" - about 5 minutes; site live within minutes after.
"Do you build the site for me?" - yes, automatically.
"How does it work?" - see [overview.md](./overview.md) Pre-signup FAQ.

**Deeper:** [overview.md](./overview.md) Pre-signup FAQ.

## What we DON'T do

- Email hosting / forwarding - website only.
- File hosting (PDFs, etc.) - dealers can link to externally hosted files from the menu but we don't host.
- Custom code or custom design - only what the editor exposes.

## When to escalate

Escalate to engineering (Tim, Jack) when:

- Site is genuinely down (returns 5xx, not just confused dealer).
- Custom domain DNS check passes but domain still doesn't work.
- Indexing >14 days after subdomain set.
- Stripe data and DB data disagree on subscription state.
- Anything you suspect is a bug, not a how-to question.
- Admin-only changes (subdomain, dealer number, refund disputes).

## Out-of-scope tools we don't have yet (so support knows)

- Activity timeline lookup (when was subdomain first set?) - currently only via admin UI; future MCP enhancement.
- Self-service field updates from the MCP (admin write tools) - currently must escalate to engineering.