# Setup Assistant — How It Works

_Setup Assistant_

Available on every plan, the Setup Assistant lives at Settings > Setup Assistant. It runs a 4-7 question conversational interview to learn your business, then generates a curated configuration package: pipelines, custom fields, workflows (drawn from CRMown's 100+ pre-built templates), role templates, suite-activation suggestions, dashboard nav hints, integration suggestions, and optional sample data. Every recommendation is reviewable; you toggle items on/off, edit configs, then click Apply. Recently-onboarded orgs (under 14 days old) also see a dismissible discovery banner on the dashboard.

## Steps
1. Open Settings > Setup Assistant or click the dashboard banner if it's shown.
2. Click "Start setup". CRMown AI greets you and asks what your business does.
3. Answer in 1-3 sentences. The AI asks 1-6 follow-up questions, capped at 7 total.
4. When the interview completes, the AI puts together a recommendation package (15-25 items) — usually within 15 seconds.
5. Review each recommendation: toggle off anything that doesn't fit. Click "Apply selected".
6. If any selected item activates a paid suite that adds to your bill, a confirmation modal lists the dollar impact before anything is charged. You must explicitly confirm.
7. Watch the apply progress page — pipelines, workflows, custom fields, etc. are created in dependency order. Failed items are highlighted with the exact error.
8. On completion, you'll see "Pages worth knowing about" links to the dashboards we recommend bookmarking, and a "Connect these next" list for any integrations the assistant suggested.

## Tips
- The assistant is also available to existing customers as a "rebalance my setup" tool. Re-run it whenever your team grows or your business evolves — recommendations adapt to your current org state.
- Recommendations are plan-aware. Starter orgs never see paid-suite activations recommended. Pro orgs see them with a "+$50/month" price label and the toggle defaults to OFF until you opt in. Max orgs see suite activations default to ON because all 9 are included at no extra cost.
- Workflow recommendations wrap CRMown's built-in template library — they reference real templateIds from workflow-templates.ts. The assistant picks templates that fit your context; the template definitions themselves come from the same library you can browse manually under Workflows > New > From Template.
- Industry detection is advisory: the assistant maps your free-text description to one of ~10 industry hints (real_estate, agency, saas, etc.) for scoring purposes. Org.industry stays free-text — your original phrasing is preserved.
- Sandbox-aware: running the Setup Assistant inside a sandbox lands every applied config in the sandbox org. Promote selected configs back to parent via the regular sandbox diff/promote workflow.

## Example
Devon signs up for CRMown for his 8-agent residential real estate brokerage. He clicks the dashboard banner and starts the assistant. After answering "DFW residential brokerage, 8 agents, mostly buyer-side referral business" plus three follow-ups, the AI proposes 18 items: Buyer + Listing pipelines, commission-split fields on PipelineItem, the "New Lead Welcome" + "Quote Follow-Up" + "24h Appointment Reminder" workflows, a "Brokerage Office Admin" role template, the Operations suite activation (defaulted ON because they're on Max), 4 dashboard nav hints, Stripe + Google Workspace integration suggestions, and 5 sample buyer/seller contacts. Devon toggles off the sample data, edits one stage name on the Buyer pipeline, and clicks Apply. Eight minutes after creating his account, the office is functional.

## Troubleshooting
- **The AI asked one question and immediately stopped — recommendations look generic.** — Your first answer was vague enough that the AI couldn't extract enough context, but it gave up rather than re-asking. Or you hit the 7-question cap. Fix: In the recommendation review, click "This isn't quite right — clarify". That abandons the current session and starts fresh — give a more detailed business description.
- **I selected a paid suite recommendation and got a 402 / "billing confirmation required" response.** — Working as designed (delta decision D). On Pro plans, activating a suite beyond the 4 included adds $50/month to your subscription. The Setup Assistant never activates paid suites silently — it always pops a confirmation modal showing the exact dollar impact. Fix: The frontend handles this automatically — review the modal, confirm, and the apply continues with `confirmedBilling: true`.
- **A custom field recommendation for a pipeline failed to apply.** — The custom field references a pipeline (via `targetPipelineCatalogId`) that you toggled OFF in the same session. Without the parent pipeline, the field has nowhere to live. Fix: Re-run the assistant and either keep the parent pipeline selected, or skip this field. The recommendation engine pairs them as `requires:` in the catalog.
- **The "Setup Assistant" tab is missing from Settings.** — Your role doesn't have setup-assistant:read or :write permission. Fix: OWNER, ADMIN, EXECUTIVE, and DIRECTOR roles can run the assistant. Other roles see Settings without this tab. Ask your admin to elevate or run the assistant on your behalf.
- **I never see the dashboard discovery banner.** — The banner only shows for orgs under 14 days old that have no applied SetupSession. If your org is older or you've already run a session, the banner self-hides. Fix: Use the Settings > Setup Assistant tab directly any time — the banner is just a discovery aid, not the only entry point.

## Error messages
- `The "setup_assistant_interview" AI feature is disabled for this organization.` — An admin turned this AI feature off in Settings > AI Usage > AI Features. Re-enable it or use the static checklist alternative under Settings > Customize.
- `Recommendation generation failed — AI output unparseable` — The AI returned malformed JSON. Rare — usually a transient model issue. Re-run the interview or click "This isn't quite right" to start fresh.
- `Unknown workflow template "..."` — A catalog entry references a template that no longer exists in workflow-templates.ts. This is an authoring bug — report it; it does not indicate something wrong with your org.
- `Target pipeline ... not found in this session` — You toggled off a pipeline that a custom field depended on. Either re-include the pipeline or skip the dependent field.

## Plans
Available on every plan including Starter and pre-billing free orgs. The catalog filter respects plan tier — free / Starter orgs only see basics-only recommendations (no paid-suite activations, no Pro-only workflows). Suite activations (and their billing-confirmation modal) appear only for Pro / Max / custom plans.