# GTM Engine Product Guide GTM Engine is an AI-powered revenue intelligence platform that connects to your CRM and communication tools and gives sales teams actionable insights, automates data hygiene, forecasts revenue, and coaches reps to close more deals. This guide answers two kinds of questions: 1. **Marketing / prospect questions** from visitors on www.gtmengine.ai — "what is GTM Engine?", "what CRMs do you support?", "how do I try it?" (See Section 0: About GTM Engine.) 2. **Internal / in-app questions** from users of a GTM Engine org — "how do I configure X?", "where is Y?", "who has access to Z?" (Sections 1 onward.) Each feature section covers: what it does, why it matters, where to find it, who can access it, how it works, and key actions. Roles: **Admin**, **RevOps**, **Member**, **Guest**. Job levels: **Executive**, **Manager**, **AE** (Account Executive), and others. --- ## 0. About GTM Engine (Marketing-Facing) This section is designed for anonymous website visitors asking broad product questions. If you don't have a specific answer about pricing, security, or contracts, offer to open a demo request form rather than guessing. ### What is GTM Engine? GTM Engine is an AI-powered revenue intelligence and automation platform for B2B sales teams. It sits on top of your CRM (HubSpot or Salesforce) and your communication tools (email, calendar, call recorders) and uses AI to: - **Keep CRM data clean** automatically — no more unlinked activities, orphaned records, duplicate accounts, or stale deals. - **Auto-fill deal, account, and contact fields** by reading every meeting, email, and call so reps stop doing data entry. - **Forecast revenue** more accurately by combining rep judgment with AI-generated deal health signals. - **Run agents and workflows** on your pipeline — enrichment, prospecting, follow-up automation, scoring, and custom processes — all configurable without code. - **Let anyone build reports and dashboards** by asking questions in natural language ("show me healthcare accounts with more than $100K in pipeline, grouped by owner"). - **Answer any question in context** via Genie, an AI assistant embedded in every page. ### Who is it for? - **Sales leaders** (VP Sales, CRO) who want an accurate forecast and a clear picture of team performance. - **Revenue Operations (RevOps)** teams who need to automate CRM hygiene, enrichment, prospecting, and reporting without building a stack of point tools. - **Account Executives (AEs)** who want AI to do data entry for them, surface which deals need attention, and prep them for every meeting. - **Managers** who want to coach reps off real conversation data. ### How do I try GTM Engine? Any new user can sign up from the public `/get-started` page with a work email. Self-service sign-up has no credit card requirement and starts free accounts with 1000 credits for finding, enriching, and researching accounts and contacts, finding contact information, and running propensity scoring. Personal or temporary email domains are blocked before an account is created. For a guided walkthrough of your specific use case, ask the assistant to open a demo request form and our **success team** will reach out. ### What does GTM Engine integrate with? - **CRMs** (one at a time): HubSpot, Salesforce, or the built-in GTM Engine CRM. - **Call recorders**: Gong, Sybill, Fathom, Grain, Read, Circleback, Fireflies, plus a built-in GTM Engine call recorder for teams that don't already use a third-party recorder. - **Email & calendar**: Google Workspace, Microsoft 365. - **Messaging**: Slack and Microsoft Teams (for Genie agents embedded in chat). - **Sales engagement**: Instantly (send contacts to campaigns from workflows). - **Content**: Sanity CMS (publish documents from workflows). ### Pricing, security, and contracts Pricing, security posture (SOC2, data residency), and contracting questions are best handled by the GTM Engine **success team** — a helpful, non-pushy group focused on getting people set up, not on closing quota. If a visitor asks about any of these, open a demo request form so the success team can follow up. In-app billing for Admins routes self-serve paid plan purchases through Stripe and applies upgraded plan access only after Stripe confirms payment. Team Members lets paid-plan admins add seats by entering the number of seats, reviewing the Stripe total, and continuing to Stripe for payment. RevOps users can view credit balance and usage in Billing & Usage, but plan changes, credit purchases, invoices, billing portal access, and billing history remain admin-only. Custom-plan customers should contact support to change seats, update plans, or cancel. If a subscription has a scheduled cancellation date, Billing & Usage shows the date; within two months of cancellation, admins also see a warning that access continues until then. ### How is GTM Engine different? GTM Engine combines things that are usually separate tools: CRM hygiene + AI field auto-fill + forecasting + reporting/dashboards + workflow automation + a conversational AI assistant. Rather than stitching together Clari, Gong, Outreach, and a data-quality tool, teams run all of it in one place on top of their existing CRM. --- ## 1. Getting Started — Sign-Up and Onboarding ### Self-Service Sign-Up - **Page**: `/get-started` for public sign-up, `/` for sign-in, then `/signup` after authentication for company setup - **Access**: Anonymous new users with a work email - **Why it matters**: New teams can create a GTM Engine organization without waiting for a sales-led provisioning process. - **How it works**: The app sign-in page links new users to `/get-started`, a public marketing sign-up page with the work-email capture form. The sign-up path blocks personal/disposable domains and sends approved users an org-scoped WorkOS invitation before any WorkOS user is created. `/get-started` also embeds the public marketing Genie for product questions and demo/contact requests; this Genie only has product-help and demo-request/contact-form tools. After authentication, `/signup` presents company setup as step 1 of account setup, previews the company name/logo from the verified domain when available, collects company name and domain, provisions the signer as an **Admin**, assigns the catalog-backed Free plan, grants the free-account credits, and routes them into onboarding. Duplicate sign-up attempts prompt the user to sign in or ask an admin for an invite. ### Role- and Plan-Aware Onboarding Onboarding now adapts to both the organization's plan and the user's role. - **Free Plan onboarding**: Focuses on finding value quickly without a CRM setup requirement. Users are guided to define products and ICPs, configure propensity signals, find at least 5 target accounts, find contacts, understand what unlocks on paid plans, and then set up their profile. The Home page keeps this setup guide front and center until products/ICP, propensity signals, at least 5 accounts, at least one contact, and the user's profile are complete. - **Paid Plan Admin onboarding**: Preserves the full organization setup path: connect CRM, connect call recorder, configure sales process/products/organization settings, map fields, connect email/calendar, invite teammates, and backfill CRM data. - **Paid Plan non-Admin onboarding**: Focuses on the user's own profile rather than organization configuration. Non-admins are guided to add LinkedIn, timezone, email voice and signature, email/calendar, and quota context. - **Persistent profile setup nudge**: Admins and non-admins can see a dismissible nudge until their profile context is complete. This improves Genie, day planning, writing instructions, and personalized recommendations. ### Setup Checklist and Progress - **Location**: Sidebar bottom area and contextual setup cards. - **Access**: All users see profile setup. Admin and RevOps users see organization setup when their plan allows it. - **Live sync progress**: CRM and transcript sync progress appears in the sidebar above the onboarding card. A toast fires when sync completes. - **Backfill CRM**: After CRM and transcript sync complete, a Backfill CRM action remains available until triggered. - **Completion**: Paid admin setup disappears when complete. Profile setup nudges disappear at 100% completion or after dismissal. - **Onboarding-aware Genie**: Settings and setup surfaces can register writable fields so Genie can help complete forms. --- ## 2. Navigation, Home, and Search ### Home Page - **Page**: `/home` - **Access**: All roles and plans - **Why it matters**: Home is now the user's daily command center rather than a redirect to role-specific legacy dashboards. - **First-session setup**: Free-plan users who have not completed the core setup see a branded accordion-style onboarding guide instead of the Genie Day Planner and Today's Meetings. The guide explains why each step matters, then routes them to products/ICP, propensity scoring, the Records → Accounts find-accounts modal, contacts, plan upgrades, and profile setup. The target accounts step requires at least 5 accounts and tells users that research and propensity scoring run on each account but can take a few minutes. Once products/ICP, propensity signals, at least 5 accounts, at least one contact, and the user's profile are complete, Home returns to the Day Planner and meetings workspace. - **Genie Day Planner**: The primary Home experience is an AI-generated, strictly prioritized plan for the day. It uses user profile context, LinkedIn-derived preferences, calendar/meetings, records, reports, and recent product activity, then condenses the output into "Do these today no matter what" and "Explore these things" so opportunity and forecast context is not repeated across sections. - **Refine Plan**: Feedback opens inside the Genie Day Planner and regenerates the plan while also informing `daily_plan_preferences`. - **Meetings**: Today's Meetings are embedded in the planner area using the calendar Day view with time labels and a current-time marker. Users can expand the calendar in place to the full calendar widget with day/week/month controls, which pushes the Genie Day Planner below it. The compact meetings card includes a settings gear for participant filtering, while the expanded calendar exposes the full calendar settings menu. - **Admin / RevOps tab**: Admin and RevOps users also see recommended process improvements, including automations they have not configured yet and onboarding or upgrade suggestions when relevant. ### Sidebar Navigation - **Location**: Left side of every authenticated page. Collapsible; mobile uses a slide-out sheet. - **Primary sections**: - **Home**: Genie Day Planner and process recommendations. - **Generate Pipeline**: Target Accounts, Propensity Scoring Config, Outreach Campaigns. - **Close Pipeline**: Forecast, Pipeline, Team Performance, Sales Process. - **Grow Customers**: Customer Health, Renewal Forecast, Customer Success Config. - **Records**: Accounts, Contacts, Opportunities, Transcripts, Activities. - **Reports / Dashboards**: Saved reports, natural-language report building, dashboards. - **CRM Hygiene**: Assessment, cleanup, activity hygiene, rules. - **Automation**: Workflows, triggers, agents, automation map. - **Settings**: Profile, products, organization, fields, integrations, team, API keys. - **Plan gating**: Free Plan users can access Home, Profile, basic Records, Products, and Generate Pipeline. Paid-only sections show locked nav items and route-specific blurred previews behind the upgrade card. Grow Customers is not generally available yet; users who open a Grow page see a Support contact prompt instead of the customer workspace. - **Personalized guidance tip**: The sidebar footer can show one lightweight Genie suggestion based on a user's UI guidance profile. Users can dismiss individual tips. ### CMD+K Global Search - **Shortcut**: Cmd+K (Mac) or Ctrl+K (Windows) - **Access**: All roles - **Why it matters**: Instantly find and navigate to accounts, contacts, opportunities, and pages without clicking through menus. ### Profile Menu - **Location**: Bottom of sidebar - **Actions**: View profile, access settings, sign out. --- ## 3. Generate Pipeline Generate Pipeline helps SDRs, AEs, and founder-led sellers work through the full pipeline-generation flow: find non-customer accounts, score them, find the right contacts, enrich contact information, and generate outbound content. ### Target Accounts - **Page**: `/generate/accounts` - **Access**: Free and paid plans - **Why it matters**: Starts pipeline generation from accounts that are not already customers and ranks them by propensity. - **Key actions**: Search/filter target accounts, sort by propensity or creation date, identify newly added accounts with the New badge, inspect propensity reasoning and signal-level scores, open existing account plans, use the row-level Contacts action to find buyer-persona contacts for a specific account, and enroll contacts into outreach campaigns. The Prioritize accounts info drawer explains that propensity scoring is unique to each GTM Engine customer: it uses that customer's products, CRM context, ICPs, configured signals, and GTM Engine matching algorithms to create differentiated targeting angles and a wedge into each account. Users can enroll from a single account row or select multiple accounts and bulk-enroll their contacts. The enrollment planner supports selecting multiple contacts and multiple outreach campaigns, assigning contacts into campaign buckets, separating contacts that already have an `outreach_campaign` value into an Already Enrolled bucket, enriching contacts that lack email or have stale `last_enriched` data, reviewing an estimated credit-consumption modal, then accepting before GTM Engine starts enrichment or campaign workflows in batches. Bulk select skips already-enrolled contacts by default, but users can still manually select one to override or re-enroll. - **Bulk scoring**: Use Records → Accounts and Run Workflow to bulk-run propensity scoring against selected or filtered accounts. - **Genie**: `generate_accounts_page` helps prioritize target accounts, explain propensity/scoring gaps, and identify accounts that need buyer-persona contacts. ### Propensity Scoring Config - **Page**: `/generate/scoring` - **Access**: Admin, RevOps; available on the Free Plan - **Why it matters**: Propensity scoring researches account-level signals to prioritize outreach and prepare teams for meetings. The same signal data can later help customer teams spot churn or upsell signals. - **How it works**: Admins define scoring signals manually or from AI recommendations. When automatic scoring is enabled, GTM Engine researches and propensity scores every new account added directly or synced from the CRM, then writes research, reasoning, and score fields. When disabled, admins must run scoring manually. Signals can be backfilled against existing accounts. - **UX**: Configured/running signals are visually separated from recommendations. Help documentation lives in a drawer opened from the page, and the enable/disable toggle is inside the Configured Signals box with explicit automatic-vs-manual scoring copy. New AI-generated signals appear immediately as pending cards with progress while GTM Engine generates prompts in the background; users review each generated signal before creating fields and saving it to the workflow. Saved signal edits can create an unpublished workflow draft; the page flags unpublished changes and provides a Publish changes button so tests and automation use the latest signal set. ### Buyer-Persona Contacts - **Primary path**: Open a high-propensity account from `/records/accounts` or `/generate/accounts`, then use the account page's Find Contacts action. - **Access**: Free and paid plans - **Why it matters**: Once target accounts are identified, sellers need relevant people at those accounts with enough contact data to start outbound. - **Key actions**: Add contacts from the account page so each contact is tied to a prioritized account showing buying signals, enrich missing email/phone/LinkedIn, and move ready contacts into outreach. Users can also add or manage contacts from `/records/contacts`, but the recommended setup path starts from high-propensity accounts rather than a generic contact list. - **Genie**: `account_page` helps evaluate account-specific contacts, missing info, and outbound readiness. ### Outreach Campaigns and Outbound Fields - **Page**: `/generate/outreach` - **Access**: Free and paid plans can build campaign content; delivery through Manual CRM Mapping or Instantly requires paid-plan integrations access. Settings → Integrations is managed by Admin or RevOps users. - **Why it matters**: Outbound content should be generated once, stored on Contacts, and mapped to the CRM so sequencing tools can use it. - **How it works**: Outreach campaigns compile into workflows with fixed `account_id` and `contact_id` inputs. The builder walks users through basics, delivery, structure/prompts, then test/save. Each campaign name must be unique because it prefixes generated field keys. Each run fetches the account/contact, uses one object-generating AI Prompt task to create the full sequence content, writes that content to Contact fields, and optionally adds the contact to an Instantly campaign. - **Preview and prompts**: The preview picker prioritizes high-propensity accounts that already have associated contacts and only searches accounts with contacts. Preview runs are dry runs, so they generate drafts without writing Contact fields or enrolling contacts in Instantly. The advanced campaign prompt is a single prompt for the whole sequence and uses the same variable insertion and validation experience as the workflow builder, with account/contact variables such as `{{steps.1.account.account_name}}` and `{{steps.1.contact.email}}`. Users must add tone, length, direction, and CTA guidance to every step before generating campaign-level content instructions. Testing is a dedicated final step where users select an account/contact, generate drafts, refine the prompt from feedback, or directly edit the prompt and test again. - **Delivery**: If Instantly is connected and selected, the workflow adds the contact to the chosen Instantly campaign after content generation. Selecting an Instantly campaign imports the campaign's email-step count into the builder as blank steps; users still provide their own step guidance before generating prompts. After a preview run, users can send the selected test contact to the Instantly campaign with generated custom variables so those variables are available for mapping in Instantly; this test send does not update GTM Engine Contact fields. Otherwise, paid users map generated Contact fields to CRM fields directly from the Structure step when HubSpot or Salesforce is connected, then use those CRM fields as variables in their engagement platform. Members who need Instantly connected should ask an Admin or RevOps user; Free-plan users are prompted to upgrade before using either delivery path. - **Contact fields**: Outbound content is stored on Contact fields such as `outreach_campaign`, `campaign_name_email_subject_1`, `campaign_name_email_body_1`, `campaign_name_email_subject_2`, `campaign_name_email_body_2`, `campaign_name_linkedin_dm_1`, etc. - **Field category**: Outbound fields are a dedicated contact analysis type/section, separate from generic research or AI analysis, so admins can map them cleanly to CRM fields. - **Sequencer variables**: Users must make sure variables in their sequencer match the generated field keys or mapped CRM fields exactly; mismatched variable names can send blank content. - **Genie**: `outreach_page` can configure campaign names, descriptions, delivery settings, steps, channels, generate content instructions, and refine the single campaign prompt through `set_form_field`, and can answer CRM field-mapping questions. Before generating content instructions, Genie should gather tone, structure, length, direction, and CTA guidance for every step. --- ## 4. Close Pipeline Close Pipeline is the paid-plan workspace for forecasting, deal inspection, pipeline management, and team performance. ### Forecast - **Page**: `/close/forecast` - **Access**: Manager and Executive job levels with paid forecast access - **Why it matters**: Sales leaders predict whether the team will hit its number by combining human judgment with AI-generated deal health and historical movement data. **Overview tab**: Progress Bar, Pipeline Summary, Forecast Map (Sankey-style flow visualization), Opportunities Table with inline editing, date controls, team hierarchy tabs, category filters, search, and column customization. **Team setup**: Forecast can show all opportunities before Team Structure is configured, but it shows a persistent setup warning and a dismissible setup prompt. Configuring Settings → Team → Structure enables accurate team hierarchy tabs, manager/member filtering, rollups, and target attainment. **History tab**: Answers "what changed in my forecast and why?" by comparing the current forecast against a snapshot from a chosen point in the past. The server reconstructs historical values of `forecast_category`, `amount`, `health_score`, and stage using field history. **Forecast Map (Sankey chart)**: Toggle between category flow and risk flow. Hover previews the movement, clicking a node filters the chart, and clicking a flow band surfaces the underlying deals. **Forecast table**: Users can change visible fields, reorder columns, save preferences, reset defaults, and inline-edit editable opportunity fields. Forecast category mapping controls how raw CRM category values display and roll up. **Genie**: `forecast_page` can answer questions about forecast data, risk, category movement, pipeline trends, and underlying deal lists. ### Pipeline - **Page**: `/close/pipeline` - **Access**: Paid pipeline access - **Why it matters**: Visual and table-based deal management for active opportunities. - **Features**: Pipeline selector, stage filters, search, team selection, create opportunity, chart/table views, and links to opportunity detail. - **Team setup**: Pipeline can load without Team Structure configured and will show all opportunities instead of filtering by owner team membership. The page keeps a setup warning visible until Settings → Team → Structure is configured; users can dismiss the setup prompt to continue viewing data. ### Team Performance - **Page**: `/close/performance` - **Access**: Manager and Executive job levels on paid plans - **Why it matters**: Compare rep performance, quota attainment, activity levels, and pipeline health across the team. - **Free Plan behavior**: Locked in the sidebar and route guard for Free Plan users. ### Sales Process - **Page**: `/close/sales-process` - **Access**: Admin, RevOps on paid plans - **Why it matters**: Configure the pipelines, stages, health scoring, and methodology that power Close Pipeline. Legacy `/sales/*` paths may remain as redirects for compatibility, but the product should link users to `/close/*`. --- ## 5. Grow Customers Grow Customers helps post-sale teams understand customer health, churn risk, expansion readiness, renewals, and sales-to-CS handoffs. **Current access model**: Grow Customers is visible in navigation but not generally available yet. Users who open a Grow page see a Contact Support prompt that files a support ticket through the standard feedback/support path. ### Customer Health - **Page**: `/grow/health` - **Access**: Not generally available yet; users see the Contact Support gate - **Why it matters**: Gives customer teams one shared workspace for customer health, churn risk, expansion readiness, renewal indicators, CSM churn rates, and sales-to-CS handoffs. - **Account queues**: Shows filtered customer accounts with health, churn, expansion, and renewal fields. `/grow/churn-risk` and `/grow/expansion` redirect here so teams work from a single customer-health surface. - **Handoff plans**: Users can generate handoff plans for recently or upcoming Closed Won opportunities. The plan is saved to account AI fields for CS review. - **Genie**: `customer_health_page` helps prioritize customers, explain churn/expansion signals, and guide next actions. ### Renewal Forecast - **Page**: `/grow/renewal-forecast` - **Access**: Not generally available yet; users see the Contact Support gate - **Why it matters**: Shows renewal confidence, renewal forecast category, and upcoming customer handoffs. - **Genie**: Reuses `forecast_page` with `pipeline_purpose = "renewal"` so the assistant answers with renewal/customer-risk framing instead of new-business pipeline framing. ### Customer Success Config - **Page**: `/grow/customer-success-config` - **Access**: Not generally available yet; the page is behind the Grow Customers gate - **Customer account definition**: Admins can choose a customer account template. This creates a saved account report and stores the filter configuration in organization customer-success settings. - **Account health guidelines**: Admins can edit the account-health rubric used by health, churn, renewal, and expansion workflows. - **CS workflow coverage**: Shows default workflows needed to generate the fields that power Grow Customers. - **Genie**: Uses `settings_page` because this is a configuration surface. --- ## 6. Records Records are the core data objects in GTM Engine: **Accounts, Contacts, Opportunities, Activities, Transcripts**. Each has a list page (search, filter, report) and a detail page (deep-dive into a single record). The Records landing page at `/records` uses `records_home_page` Genie context to help users choose the right record type and navigate to specific accounts, contacts, opportunities, transcripts, or activities. ### Accounts - **List**: `/records/accounts` (all roles). Report builder, table, create, export, bulk workflow runs, **bulk update** (select rows or "Select all matching" + wizard for field/value or tag add/remove), Views. - **Detail**: `/records/accounts/{id}` (all roles). Tabs: Overview / Detailed Information / Research (AI-enriched data: industry, funding, tech stack, web traffic) / Products/Services / Competitors / Plan / Custom Fields. Sidebar panels for contacts, opportunities, activities, transcripts. Propensity score with reasoning. Parent-account hierarchy UI. Genie: `account_page`. ### Contacts - **List**: `/records/contacts`. Same report-builder features as accounts, including bulk update (field value or tag add/remove). - **Detail**: `/records/contacts/{id}`. Tabs: Contact Details / Research Information / Opportunity Information / Custom Fields. Genie: `contact_page`. ### Opportunities - **List**: `/records/opportunities`. Same report-builder features, plus custom aggregate columns and bulk update (e.g. reassign owner, change stage, edit tags) on selected or filter-matched records. - **Detail**: `/close/pipeline/{id}` or linked opportunity detail routes from records/forecast tables. Genie page context: `opportunity_page`. #### Opportunity detail tabs - **Overview** — GTM + Standard Fields side-by-side, including AI fields (health score, AI forecast close date, deal gaps, summaries), editable CRM fields, and the Contacts panel. Header shows owner, stage, amount, and the Methodology circles (see below). Owner-change prompt fires if the logged-in user isn't the opportunity owner to prevent accidental writes under the wrong identity. - **Path to Close** — a structured view of how the deal progresses through the methodology. See the dedicated section below. - **Activity** — chronological activity timeline (meetings, emails, calls, CRM updates) for the opportunity and its associated contacts. Clicking a meeting opens Meeting Prep (see below). - **Notes** — a dedicated notes surface with folder-style organization. Each note has a title, rich body, and independent edit/view mode. Designed for running deal journals, call prep, and handoff documents that live on the opportunity itself rather than being buried in activity comments. Collapsible sidebar lists all notes; resize handle between sidebar and editor; delete confirmation modal. #### Path to Close & Methodology Path to Close is the opportunity-level "what needs to happen for this deal to close" surface. It replaces ad-hoc close plans in spreadsheets and keeps the methodology visible without forcing reps into a rigid checklist. **Methodology progress (the circles in the opportunity header)** - Shows a ring of scored dimensions — typically a MEDDIC-style framework (Metrics, Economic Buyer, Decision Criteria, Decision Process, Identify Pain, Champion, Competition), but the exact dimensions are org-configurable. - Each circle is scored 0-10 based on AI analysis of activities + fields; color-coded (red/yellow/green). - Click a circle to open the **Qualification Modal**, which shows: the current score, the AI's rationale (what evidence in activities/fields drove the score), what's missing, and suggested questions/actions to raise the score. - The average score across dimensions is surfaced as an overall methodology health indicator. **Stage timeline & entry/exit criteria** - Visualizes each pipeline stage with expected duration (set in Settings → Configuration → Sales Process) and current time-in-stage. - For each stage, the Entry Criteria (what must be true to enter) and Exit Criteria (what must be true to leave) configured at the org level are rendered as a checklist. AI evaluates whether each criterion is met based on activities, fields, and qualification signals. Unmet criteria on the current stage are the concrete blockers. - Highlights stage skips, stuck deals (exceeded expected duration), and regression (moved backwards). **Action planner (AI-generated, rep-editable)** Four grouped action lists, all editable inline: - **Completed Actions** — what's already happened (auto-surfaced from activities + fields + methodology evidence). - **Pending Actions** — committed next steps with reasoning. - **Blockers** — explicit obstacles, each with reasoning (e.g. "Waiting on security review — contact John in IT"). - **Suggested Next Steps** — AI-proposed actions, prioritized (Priority 1 / 2 / 3), each with a "why this matters" rationale. Reps can add, edit, reorder, or delete any item manually; AI will never silently overwrite rep edits. The Genie lamp next to the section regenerates suggestions from the latest activity. **Why it matters**: Deal inspection meetings can be run directly off the opportunity page — the circles, stage timeline, and blockers together answer "is this deal real, what's stuck, and what's next?" without switching to a separate close-plan spreadsheet. #### Meeting Prep When the opportunity has scheduled meetings in its activity timeline, clicking a meeting opens the **Meeting Prep** dialog — an AI-generated briefing document designed to be read in the 5 minutes before the call. - **What it contains**: opportunity summary, current stage + methodology scores, contact list with roles/promoter scores, recent activity digest, open blockers from Path to Close, talking points, and suggested questions tailored to the stage. If the meeting has associated contacts, each contact card shows their title, LinkedIn, recent engagement, and last-touch summary. - **Association editing**: Reps can add/remove the meeting's associated opportunity or contacts inline — useful when the CRM only attached the meeting to a generic account. - **Contact search & add**: Built-in contact search lets reps add attendees who weren't originally on the invite but are relevant. - **Email composer**: One-click "send a follow-up / pre-call email" inline, with recipients and context pre-filled from the meeting. - **Why it matters**: No more "I have a call in 3 minutes, what do I need to know?" panic — the full deal + relationship + risk snapshot is one click from the activity timeline. ### Activities - **List**: `/records/activities`. Filter by type, date, associated records. Bulk update for editable activity fields and tags (associations are managed per-record). The page exposes transcript-derived columns (`has_transcript`, `call_score`, `call_type`, `topics`, `transcript_title`, `call_url`, `call_score_reasoning`) for filtering, sorting, and reporting via a `LEFT JOIN` to the `transcripts` table. A **"Recorded Meetings"** preset button next to the search bar one-click filters to `interaction_type IN [meeting, live_meeting, phone_call, conference_meeting]` AND `has_transcript = true` and adds the transcript columns when not already present. Genie understands these fields, so prompts like "best discovery calls last quarter" or "calls about pricing where score < 5" produce correct filter configurations. - **Detail**: `/records/activities/{id}`. Layouts vary by type — Meeting / Email / Other. Tasks card. Related Records sidebar. Genie: `activity_page`. ### Transcripts - **List**: `/records/transcripts` (requires `transcripts-view` feature flag). Searchable library with AI summaries. Manual "Sync Transcripts" button. - **Detail**: `/records/transcripts/{id}`. Full transcript text, participants, AI summary, linked activity. - **Genie**: `transcripts_page` works on both list and detail routes. It can summarize loaded transcript context, extract follow-ups, explain participants and related records, and navigate to linked accounts/contacts/opportunities when available. --- ## 7. Analytics — Reports & Dashboards Reports and Dashboards are first-class analytics surfaces in GTM Engine. Earlier versions used the name "Saved Views"; those are now **Reports**, accessible at `/reports`. Dashboards live at `/dashboards`. ### Reports - **Page**: `/reports` (all roles). List of all reports with folder sidebar, tag filter chips, search, per-row tag editor, and "Move to Folder". - **Available on**: All record list pages (`/records/accounts`, `/records/contacts`, `/records/opportunities`, `/records/activities`) as inline report builders. #### Ask Genie (AI Report Building) Type a natural-language question like "Show me all accounts in healthcare with more than $100K in pipeline" and Genie translates it into filters, columns, grouping, and charts. Follow-ups refine: "Now group by owner", "Add a bar chart." Genie also knows about `dateGroupBy` (time bucketing) and `groupSortBy` (sort by aggregate). #### Manual Report Building - **Field filters**: Filter any field by operators (equals, contains, greater than, between, is empty, etc.). - **Join filters**: Filter by related-entity fields (e.g., accounts whose opportunities have stage = "Negotiation"). - **History filters**: Filter by field changes over time. - **Grouping & Aggregates**: Group by any field; configure count/sum/average/min/max aggregates on numeric fields. - **Date-based grouping (`dateGroupBy`)**: Bucket by **Day / Week / Month / Quarter** using `date_trunc` — closes the chart/table parity gap so tables and charts share the same time granularity. - **Column Customization**: Reorder, resize, save per view. - **Period Comparison**: Current vs. previous period for trend analysis. #### Charts & Visualizations Up to 4 charts per view. Types: Bar, Horizontal Bar, Line, Pie/Donut, Funnel, Gauge, Metric Card, Scatter. Each chart configured with group-by dimension + metric. #### Report UX details - Filter popovers use a local draft state — operator/value changes are staged and only committed on "Done" or dismiss. Prevents refetching on every keystroke. #### Saved Reports - **Save** filters, columns, sort order, grouping, charts, and period comparison as a named report. - **Visibility**: Private (only you) / Team / Organization. - **Tags & Folders**: Tags (and virtual folder tags) stored on `reports.tags`. Same tagging/folder experience as Workflows. - **Pin to sidebar** for one-click access. - **URL-shareable** via `?view={id}`. #### Export & Run Workflow - **Export**: Export filtered results to CSV. - **Run Workflow** (Admin/RevOps): Run a workflow against the filtered record set for bulk enrichment, updates, or custom automations. #### Report Builder Guide A built-in documentation page at `/records/docs/report-builder` covers getting started, example prompts, filter/measure explanations, chart types, and saved-report instructions. ### Dashboards - **Page**: `/dashboards` (list) and `/dashboards/{id}` (detail) — all roles. - **Why it matters**: Combine multiple reports and metrics into one page for exec-level and team-level views. - **Elements**: Dashboards are composed of **dashboard elements** (was `dashboard_widgets`). Each element can reference a report visualization or a metric card. - **Tags & Folders**: Same folder/tag system as Reports (stored on `dashboards.tags`). - **Organization & sharing**: Create, share at Organization level, pin. - **List Genie**: `dashboards_list_page` helps users find dashboards, organize folders/tags/favorites, understand sharing/edit access, and create/search reports that can become dashboard content. **Genie-driven dashboard composition**: From a dashboard detail page, Genie can compose and rearrange dashboards in natural language. Three dedicated tools — `add_dashboard_widget`, `remove_dashboard_widget`, `reposition_dashboard_widget` — let a user say things like: - "Add a bar chart of deals by stage to this dashboard" → Genie calls `build_report` (new report), then `add_dashboard_widget` with the resulting visualization ID. - "Do we have a report for pipeline by rep? Add it to the bottom of this dashboard." → Genie calls `search_reports` first, then `add_dashboard_widget` with the existing `report_visualization_id` (no duplicate report). - "Move the forecast chart to the top-left and make it wider." → `reposition_dashboard_widget` with absolute pixel coordinates. - "Remove the activity volume chart." → `remove_dashboard_widget`. Widget positions are absolute pixel coordinates on the dashboard canvas; Genie receives the current widget list (including IDs) as part of page context, so it can reason about "the chart in the top-right" without asking for a widget ID. > Underlying data model note: in mid-2026 the `views` table was renamed to `reports`, `dashboard_widgets` to `dashboard_elements`, and `visualizations` was extracted into a `report_visualizations` table. The `/api/views` endpoints proxy to `/api/reports` for backward compatibility, but new integrations should use the canonical names. --- ## 8. CRM Hygiene ### CRM Assessment - **Page**: `/hygiene/assessment` - **Access**: Admin, RevOps (requires `crm-assessment` feature flag) - **Why it matters**: An objective health score for CRM data quality and sales execution. Identifies systemic issues (missing contacts on deals, stale pipeline, poor activity logging) before they compound. - **Features**: Overall health score, Storyboards (Close Business, Build Pipeline, Customer Health, Marketing, Trends), per-entity tabs (Opportunities/Contacts/Accounts/Leads), Assessment History for comparisons. - **Record Cleanup links**: Throughout the assessment — e.g., "Fix Orphans" from the orphaned contacts banner, "Fix Stale Records" from the Data Freshness metric, clickable stale-accounts badges, and a "Fix" button on the Duplicates summary card route users straight into the Record Cleanup page. - **Genie**: `hygiene_assessment_page` explains assessment findings, compares history/trends, and helps prioritize cleanup work. ### Record Cleanup - **Page**: `/hygiene/cleanup` - **Access**: All roles (Admin/RevOps/Member; requires CRM integration) - **Why it matters**: Unified hygiene console — a single page with tabbed navigation for every class of CRM data problem. - **Tabs**: **Duplicates**, **Stale**, **Empty**, **Strays**, **Orphans**. - **Shared UX**: A single `HygieneTable` component with sorting, column configuration, per-tab counts (from a hygiene summary endpoint), association counts (contacts/opportunities on accounts, and similar), and a row-click preview sheet that opens a side panel showing all populated fields dynamically (empty fields collapsible). - **Dismiss / undismiss**: Stale, Empty, Strays, and Orphans all support dismiss/undismiss via `PATCH /api/organizations/hygiene-dismissal`. Dismissed records are hidden by default with a toggle to show them. - **Genie**: `hygiene_cleanup_page` explains duplicates, stale, empty, stray, and orphan cleanup categories and helps users decide where to start. #### Duplicates (`/hygiene/duplicates` or Cleanup → Duplicates) - Groups accounts by normalized domain (`www.domain.com`, `domain.com`, `https://domain.com` all collapse to the same canonical domain via `tldts`'s `getDomain`) and contacts by email. - **Merge Preview** dialog shows a field-by-field comparison with color-coded provenance indicators, a "Merged Result" tab (populated fields by default, empty fields togglable), and an explanation of the merge logic. - **Unmapped CRM fields are preserved**: before deleting non-canonical records from the CRM, the system fetches full CRM records, identifies fields not in the GTM field mappings, merges them onto the canonical CRM record, and patches them back. Unmapped fields are shown with an orange "CRM" badge in the merge preview. - **Single and bulk merge**. Bulk merge uses a two-step verification flow with a CRM deletion warning when a CRM integration is connected. - Merges run CRM updates inside the DB transaction so failures roll back both systems. CRM deletes tolerate 404s for records already removed from the CRM. #### Stale (`/hygiene/stale` or Cleanup → Stale) - Configurable threshold (30 / 60 / 90 / 180 / 365 days). - Dismiss, delete, and inline actions. Row-click opens the preview sheet with last-updated context. #### Empty (`/hygiene/empty` or Cleanup → Empty) - Filter presets: no domain, no contacts, no email, no name. - Client-side fill-rate column. Dismiss/delete actions. Preview sheet. #### Strays (`/hygiene/strays` or Cleanup → Strays) - Opportunities and Contacts with no linked account. - AI-suggested accounts with confidence scores. Accept, search manually, or bulk assign. Per-row and bulk delete with confirmation. "Delete and block" for contacts (adds the domain to the blacklist so it won't be reimported). #### Orphans (`/hygiene/orphans` or Cleanup → Orphans) - Records with no owner. - Tabs: Opportunities, Accounts, Contacts. AI-suggested owners. Accept, search manually, or bulk assign. Per-row delete on opportunities; bulk delete on all three entity types (opportunities, accounts, contacts). "Delete and block" for accounts/contacts. ### Activity Hygiene - **Page**: `/hygiene/activities` - **Access**: Admin, RevOps, Member - **Why it matters**: After meetings and calls, activities need to be linked to the right opportunity. Unlinked activities mean AI insights miss context, forecasts are less accurate, and manager visibility suffers. - **How it works**: Shows meetings/calls not linked to an opportunity. For each: activity card with date/time, recording link, contacts, accounts; up to **5 AI-recommended opportunities** with confidence; actions to accept, search (modal supports up to 10 results), create a new opportunity, or dismiss; contact-association choice when linking. ### Rules (Blacklists) - **Page**: `/hygiene/rules` - **Access**: Admin, RevOps - **Why it matters**: Prevent unwanted records from being created during CRM sync — personal-email domains, competitors, internal domains. - **Redesigned page**: Collapsible "How Records Are Created" explainer at the top, two-column layout (Account Rules / Contact Rules), responsive testing sidebar, and **AI-powered rule creation via Genie as the primary method**. Brand color scheme. - **Features**: - **Rule Tester**: Test a domain or email against current blacklists. - **Blocked Domains**: Domains blocked from account creation during sync. - **Blocked Emails**: Emails blocked from contact creation during sync. --- ## 9. Automation The Automation section is accessible to **Admin** and **RevOps** roles. ### Automation Map - **Page**: `/automation` (Process Map tab); `/automation/map` remains available as a direct map route. - **Access**: Admin, RevOps - **Why it matters**: One interactive canvas for the entire automation graph — triggers on the left, connected workflows in the middle, nested workflows/agents as branches on the right. - **How it works**: - Clicking a trigger or workflow focuses its downstream subgraph (unrelated nodes dim). - Health indicators surface on workflow nodes — **broken variables**, **deprecated models**. - Toolbar: quick create for triggers, workflows, agents. - Auto layout via React Flow + dagre (left-to-right). ### Model Migration - **Page**: `/automation/model-migration` - **Access**: Admin and RevOps can migrate their org's stored model references. - **Why it matters**: Deprecated AI models stay runnable until admins explicitly migrate stored workflow, field task, and agent configurations to supported replacements. - **How it works**: The model catalog marks deprecated models and optional replacement targets. The migration page scans stored configs by provider and model name, defaults the target to the configured replacement when available, previews affected workflows/field tasks/agents, and rewrites only selected references. Runtime execution does not silently remap deprecated models. ### Batch History - **Page**: `/automation/batches` - **Access**: Admin, RevOps. - **Why it matters**: Workflow batches (e.g., "run propensity scoring on these 200 accounts") are the most common bulk-automation primitive in the product. Batch History gives users a single place to see what's currently running, what just finished, and what failed — without losing the previous "just-enqueued" pill in the sidebar. - **How it works**: - Filter bar (URL-synced): workflow, record type, status (Running / Pending / Success / Partial failure / Failure), triggered-by user, and date range. - Each row shows the batch's date, workflow/batch name, who triggered it, total records, a status pill, a progress bar, and **View** / **Rerun failed** actions. View opens the existing batch detail modal (per-record drill-in); Rerun failed re-enqueues only the failed rows of the original batch. - A **Queue health** card at the top summarizes pending/running counts, the age of the oldest pending row, and failures in the last hour. The "oldest pending" value turns red once the row has been pending for more than 30 minutes — a hint that the queue may be stuck or the reaper is about to mark it failed. - Active batches (in flight from the current session) are highlighted in the table. - **Sidebar pill**: While any batch is running, a compact card sits above the user profile in the left sidebar showing aggregate progress (e.g., `2 batches · 47/200 · 3 failed`) with a thin progress bar and an expandable list of individual batches. The pill replaces the older bottom-right floating widget. "View history" inside the pill links to `/automation/batches`. ### Triggers - **List**: `/automation/triggers` - **Detail**: `/automation/triggers/{id}` - **New**: `/automation/triggers/new` - **Access**: Admin, RevOps - **Why it matters**: Triggers are now standalone, reusable entities — not attached 1:1 to workflows. One trigger can fan out to many workflows; one workflow can be invoked by many triggers (many-to-many via `trigger_workflows`). #### Trigger Types - **Timer** — Cron-based. Includes an AI natural-language generator ("every weekday at 9am PT" → cron). - **Record Created** — Fires when an Account, Contact, Opportunity, etc. is created. - **Record Updated** — Fires on record changes; authoritative list of changed fields is carried on the event. - **Activity Created** — Fires when an activity (meeting/email/call) is created. #### Filter Conditions - 11 operators, with AND/OR grouping. - On Record Updated filters, `value` and `newValue` both get set so overrides take effect across all code paths. #### Inputs: Explicit Trigger-to-Workflow Variable Mapping - The old implicit `{{trigger.*}}` namespace is **replaced** by explicit mapping from trigger output → workflow input variable. - When a workflow is installed from the Explore tab and has linked trigger templates, the install modal detects the triggers, shows a review step, and flags env-specific `RecordUpdated` filter values (stage names, enum values, etc.) as **amber-highlighted editable fields** before copying them in the same transaction as the workflow. #### Descriptions - Triggers have an optional **description** field, shown as a text area on detail and new-trigger pages. Descriptions are surfaced prominently on Recommended cards. - Triggers also support tags and folder tags in the unified Automation Library, matching workflow organization. #### My Triggers vs Recommended Tabs - **My Triggers**: your org's triggers. - **Recommended**: system trigger templates (`organization_id` = NULL). One-click "Add Trigger" copies the template into your org and switches you to My Triggers. The empty state of My Triggers links to "Browse recommended". #### Activation - Timer triggers start as `is_active: false` when installed and do not sync to the scheduler until activated — prevents phantom scheduler registrations. ### Workflows - **List**: `/automation/workflows` - **Detail**: `/automation/workflows/{id}` - **Fields workflows**: `/automation/workflows/fields` - **Access**: Admin, RevOps - **Why it matters**: Workflows are the automation backbone — AI field auto-fill, record enrichment, data transformations, and custom integrations, all without writing code. #### Workflow Types - **Custom**: User-created. - **System**: Built-in workflows that power core features (enrichment, propensity scoring, etc.). Admin and RevOps users discover suggested system workflows through Explore, can customize them into org-owned workflows, and can still open read-only system workflow details from the Automation Map. - **Customized System**: System workflows that have been customized in your org. - **Tools**: Workflows exposed as tools to AI agents. - The Workflows Library **Tools** tab lists custom tools users have built for Admin/RevOps users. The tab includes a short explanation plus a help drawer covering tools, agents, workflow tools, core tools, and agentic tool use. #### Workflow Library — Explore Tab - The sidebar's **Automation → Recommended Automations** page reuses the old workflow-library Explore experience: all recommended system workflows are shown as installable cards grouped by category tags. - One-click **"Add Automation"** copies a system workflow into your org and opens the editor. If the workflow has linked default trigger templates, the install modal detects them, surfaces a review step (flagging env-specific filter values), and copies the triggers as org-owned rows in the same transaction. - Users see custom workflows, customized system workflows, and recommended automation cards. #### Publish / Draft and Version History - Workflows have an explicit **Publish** action. Only the **published version** runs in production (with a fallback to latest for backward compat). - Saving after a publish creates a new **draft** row (version + 1) so edits never affect the running workflow until explicitly published. - A **Version History** tab shows every version with Live / Draft / Historical status and a **View** button per row. - A clickable **version badge** in the editor header opens a dropdown to switch between versions. Older versions open in read-only mode with a banner and a **"Publish this version"** rollback option. - The header also shows a draft vs published **status badge**. - `GET /api/workflows/[id]` returns the latest version by default; `?version=N` loads a specific version. Publishing carries over the previous `is_active` value. Retest and direct-execute paths use version-aware helpers so they always hit the published version. - Publishing is bulletproof: the bulk `SET is_published = false` no longer touches the target version row, avoiding a PostgreSQL 27000 tuple-conflict from the `enforce_single_active_version` BEFORE trigger. #### Workflow Folders - Organize workflows into folders using tags. The same `folder:` tag pattern is also available for triggers and agents in the unified Automation Library. Workflow list has folder sidebar, tag filter chips, and search. Tab state syncs to the URL (`?tab=`) so selections are bookmarkable and shareable. #### Workflow Builder Genie - Workflow detail pages include a code-defined **Workflow Builder Genie Workspace** with tabs for Workflow, Diagnostics, Runs, and Version History, plus linked-resource tabs for nested workflows, agents, focused prompts, and schemas. Trigger editing and the Process Map live in the top-level Automation Library workspace. Unlike most page Genies, this agent definition lives in the codebase rather than in the `agents` table. - Genie can read the current workflow, linked triggers, nested agents, AI models, and task capabilities; validate schema, Liquid, variable references, and AI output schemas; and propose narrow patch operations instead of rewriting the whole workflow JSON. - Genie can create workflows, triggers, and agents from scratch. Creation tools return Automation IDE workspace operations so the new resource opens in a tab, becomes focused, and is highlighted as new in the Automation Explorer. - Genie reads organization record schema with base GTM fields, pipeline stages, Slack IDs on users, and table-backed team hierarchy (`teams` / `team_members`). For stage-change workflows it can use the same stage ids shown in the trigger builder dropdown; for Slack invite workflows it should use `users.slack_id`; for manager rollups it should use team hierarchy rather than deprecated `users.manager_id`. - For new workflows and major rebuilds, Genie uses a scaffold-first build flow: create sparse metadata/input/output/step patches first, then run task-specialist builders that fill task-specific configuration and StepTask conditions. Specialist outputs become deterministic workflow patch operations rather than whole workflow rewrites. - Genie can search existing triggers, create new triggers, install recommended trigger templates, assign triggers to workflows, and update trigger-to-workflow variable mappings. Timer triggers created by Genie use the same scheduler sync path as UI-created triggers. - Genie can search reusable subworkflows for Nested Workflow and For Each tasks, including candidate inputs, outputs, tags, tool/template status, and suitability notes so builders can reuse existing automations before inventing new child workflows. - Patch operations are applied through a version-checked workflow patch API. If the current row is already published, edits create a new draft version so the live workflow is protected until publish. - Prompt and schema work should reuse the existing prompt/schema utility workflows (`generate_ai_prompt`, `rewrite_prompt`, `generate_ai_schema`, `generate_agent_prompt`). Nested agent creation/editing should delegate to the existing Agent Builder Genie, then link the resulting agent id into the workflow task. - Workflow Builder Genie uses a workflow-aware conversation summary profile with a larger recent-context budget so long design sessions preserve task ids, variable mappings, Liquid expressions, user decisions, diagnostics, and open workspace resources. #### Workflow Task Types (steps you can add) - **Prompt** — send data to an AI model. - **Agent** — invoke an AI agent as a step. - **Enrich** — company/person enrichment; supports `sourceContactId`/`sourceAccountId` (auto-populate fields), `updateSourceRecord` (write enrichment results back to those source records), and `overwriteExistingValues` (overwrite existing values instead of only filling blanks). Legacy `updateContactId` is still respected for ContactEmailPhone but is deprecated; prefer `updateSourceRecord` with `sourceContactId`. - **Update Record** / **Create Record** / **Get Record** — CRUD on accounts/contacts/opportunities. "Get Multiple Records" for Contacts supports fetching by Account ID or Opportunity ID; Opportunities by Account ID. **Get Record** also returns an `associations: { accounts, contacts, opportunities }` object with related record IDs (e.g. fetching a Contact returns the IDs of its accounts and opportunities), which downstream tasks can use without a follow-up lookup. - **Search** — search records matching criteria. - **Scrape** / **LinkedIn Scrape** — extract data from web pages / LinkedIn profiles. - **Send Email** — automated email. - **Slack** — post to Slack channels. - **Sanity Publish Document** — publish a document to Sanity CMS via `createOrReplace` mutations. Full Liquid variable substitution for `documentId` and document fields. Uses a per-org Sanity Robot Token stored encrypted via Settings → Integrations. - **Instantly Sequence** — add contacts to an Instantly campaign. API key resolved per-organization from the Instantly integration settings, with an environment fallback for local/system workflows. Campaign dropdown uses server-side search (supports >100 campaigns), defaults to active-only with a status badge for inactive. - **Research** — run deep research on a topic. - **Research Signal** — evaluate a specific research signal (used in propensity scoring). - **Find Prospects** — search for potential contacts. Accepts `accountId` (scopes to a specific account; domain filter injected). Accepts `productIcpId` (loads pre-configured ICP filters; `companyFilters` deep-merged with task criteria). When `createContacts` is enabled, new contacts inherit the account owner and are CRM-synced. Dedup is scoped to the target account's contacts when an account is provided. - **Conditional** — if/else branching. - **Nested Workflow** — run another workflow as a sub-step. - **ForEach** — iterate over an array (e.g., `contact_ids` from Find Prospects), run a nested workflow per item, return aggregate results (`results[]`, `outputs[]`, `total`, `succeeded`, `failed`). Supports sequential or parallel (batched) execution via `concurrency`, with a `maxItems` safety cap (default 500). Null/undefined items are skipped with a warning. - **Inputs / Outputs** — define workflow input parameters and output values. Output schemas are now JSON Schema; a visual SchemaBuilder supports nested `object` properties and arrays of objects with a Raw JSON toggle. Output schema validation accepts any valid JSON Schema (nested objects, arrays of objects, anyOf/oneOf, const). #### Workflow Management - Create, edit, duplicate, delete. Test with sample data. Execution history and logs. Deletion uses accessible confirm dialogs (no browser `confirm()`). - The sidebar groups automation surfaces under **Automation**: **Your Automations** (`/automation`), **Recommended Automations** (`/automation/recommended`), and **API** (`/automation/api`). Your Automations combines the automation explorer and Process Map into one workspace for workflows, workflow tools, triggers, and agents. The Automation Explorer pane can collapse and be resized by dragging its right edge; workflow filters open in a popover with workflow type, status, creator, tag, and sort controls plus visible filter chips. Users only see workflow types they can access. From the explorer, users can create folders and subfolders for workflows, triggers, and agents, cancel folder creation by clicking out or pressing Escape, drag resources between folders, create a new workflow directly inside a folder, and delete workflows inline. Opening a workflow, trigger, or agent from the explorer or map loads its editor in the same workspace tab and collapses the main app sidebar for more editing space. The previous `/automation/workflows`, `/automation/triggers`, and `/automation/agents` library URLs remain available as compatibility routes. - Workflow, trigger, and agent builder tabs expose direct editor links plus threaded comments for team discussion and @mentions. Workflow detail pages use real editor tabs for the parent workflow, diagnostics, runs, and version history, plus linked-resource tabs for nested workflows, agents, focused prompts, and output schemas. Triggers and the Process Map are handled by the top-level Automation Library workspace. Workflow Builder Genie uses the active tab/resource context when inspecting or patching automation assets. #### Fields Workflows - **Page**: `/automation/workflows/fields` - **Access**: Admin, RevOps - **Why it matters**: Configure which workflows power AI auto-fill for accounts, contacts, and opportunities. - **Tabs**: Accounts, Contacts, Opportunities. ### Agents - **List**: `/automation/agents` - **Detail**: `/automation/agents/{id}` - **Access**: Admin, RevOps - **Why it matters**: Agents are AI assistants that can use workflows as tools. Workflows are deterministic; agents are dynamic — they decide which tools to use based on the conversation. This powers Genie and custom assistants. - **Agent Types**: Custom / Suggested / Customized System for admins and RevOps. - **Configuration**: System prompt, model (OpenAI / Anthropic / Google), temperature, max steps, input variables, tools. - **Organization**: Agents support tags and folder tags in the unified Automation Library, matching workflow organization. - **Tools tab**: Shows assigned tools and available tools. A built-in help drawer explains what tools are, how agents use them, examples of core and workflow tools, and how to choose the smallest useful tool set for an agent. - **Chat platforms**: Agents can be wired into **Slack or Microsoft Teams** chat via per-agent chat config — see Settings → Integrations. - **Testing**: Test agents directly in a chat interface from the configuration page. ### AI Auto-Fill Fields - **Configure**: `/settings/fields`, `/settings/fields/ai_field`, `/settings/fields/ai_analysis_field` - **Execution**: `/automation/workflows/fields` - **Access**: Admin, RevOps to configure; all roles see the generated values. - **Why it matters**: AI auto-fill eliminates hours of manual data entry. Instead of reps typing in deal summaries, health assessments, or research, AI reads activity data and fills fields automatically. - **Field Categories**: Standard CRM / AI Data / AI Analysis / Research. - **Configuration flow**: Create a field → specify AI prompt → choose content handling (Re-Evaluate / Replace / Prepend) → map to CRM field → test against a real record → iterate on the prompt → save and activate. - **Common fields**: Accounts (industry analysis, account plan, recent news, funding data, tech stack, ICP fit). Contacts (previous companies, skills, career progression, communication style). Opportunities (health score, AI forecast close date, deal gaps, suggested next steps, risk factors, meeting summaries). #### Supported field types (AI can write to all of them) AI auto-fill is **not** limited to text. The same engine writes structured values into any of these data types, so fields are reportable, filterable, and chartable exactly like native CRM fields — not freeform strings that you have to post-process. - **Text** (`text`) — short-form strings, URLs, IDs, names. - **Long text** (`long_text`) — multi-paragraph outputs: account plans, health-score reasoning, meeting summaries, research briefs. Rendered with line breaks in the record drawer and truncated in list views. - **Number** (`number` / numeric / bigint) — integers and decimals. Usable as chart metrics, filter ranges, sort keys. Example: `overall_interest_score`, `employee_int`, AI-proposed deal amount. - **Date** (`date`, `timestamp with time zone`, `timestamp without time zone`) — AI returns ISO-8601 and it's stored as a real date column, so it groups by day/week/month/quarter in reports and evaluates against `RecordUpdated` triggers. Example: `ai_forecast_close_date`. - **Boolean** (`boolean`) — true/false. Usable in filters and as grouping dimensions. Example: "ICP fit?", "champion identified?". - **Single-select / enum** (`single_select` / `enum`) — picklist with a defined set of values. AI is constrained to pick one option from the list (it cannot invent values). Example: `forecast_category` (Commit / Best Case / Pipeline / Omitted), `relationship_type`, `sales_status`. Picklists are reportable as grouping dimensions and chart categories. - **Multi-select** (`multi_select`) — checklist-style multi-value picklist. AI can pick any subset of the defined options. Example: `competitors` on an opportunity, `tech_stack` on an account. - **User reference** (`user`) — points at a CRM user (e.g. owner, secondary owner). AI can resolve from activity data (e.g. "assign to the AE on the last recorded call"). **How AI maps outputs to structured types:** The field's `ai_prompt` tells the model what to extract, and the field's declared type constrains the output shape. For `single_select` / `multi_select`, the model is shown the allowed picklist values and is required to return one (or a subset). For `number`, the output is parsed and rejected if non-numeric. For `date`, the model is prompted for ISO-8601 and the value is coerced. The field config also supports an optional `output_schema` (JSON schema) and `output_path` for fields that need to extract a specific value out of a richer structured response. **Why this matters for reports:** Because enum / multi-select / number / date / boolean fields are first-class typed columns, reports built against AI-populated fields behave identically to reports built against rep-entered fields — grouping, filtering, charting (including `dateGroupBy` by day/week/month/quarter and `groupSortBy`), and funnel analysis all work natively. This is the distinction from first-generation AI-logging tools that dump everything into freeform text blobs and force you to do string matching downstream. **Per-field sync direction** (also configurable): AI-populated fields can sync **to** the CRM, **from** the CRM, **bidirectionally**, or **not at all** (GTM Engine-only fields). Useful when you want AI values to stay in GTM Engine without polluting the CRM, or vice versa. ### Enrichment - **Account enrichment**: industry, employee count, revenue, funding, headquarters, tech stack, web traffic, social profiles. Triggered automatically on new records and manually via "Research Account". - **Contact enrichment**: verified email, direct phone, LinkedIn, skills, education, work history. - **Email/Phone Lookup**: Waterfall across multiple data providers. ### Propensity Scoring - **Configure**: `/generate/scoring` - **Visible on**: Generate Pipeline target accounts, Account detail, record list pages, and any workflow/report using propensity fields. - **How it works**: Configure research signals (recent funding, ICP fit, tech adoption, hiring trends, churn/upsell indicators, etc.) with prompts. Publish saved signal changes, then enable scoring. A workflow (`research_propensity_scoring`) runs Research Signal tasks per account and produces signal-level research/reasoning/score fields plus `propensity_score` and `propensity_score_reasoning`. - **Cross-team value**: The same external signal data helps sellers prioritize outbound, AEs prepare for meetings, and customer teams recognize churn or expansion signals. - **Setup Genie**: `propensity_setup` — helps admins configure and tune the scoring model. --- ## 10. Genie AI Assistant - **Available**: Every page (floating button bottom-right, opens as a resizable sidebar) - **Access**: All roles - **Why it matters**: Genie is the AI layer that makes GTM Engine accessible — ask in plain English instead of hunting through menus. Genie understands context (what page you're on, what record you're viewing) and takes action. ### How Genie Works - **Floating button** bottom-right on every page. - **Sidebar**: Resizable 360-800px wide, persists across page navigation. - **Page context**: Genie automatically knows which page you're on and adapts (on an account, it knows about that account; on forecast, it knows pipeline data). - **Chat history**: Previous conversations are saved; start a new chat at any time. Page context and saved history are isolated so `set_form_field` values from prior sessions do not re-apply when the sidebar mounts. - **Home Day Planner**: The Home page uses a tool-capable Genie Day Planner agent. It returns structured plan output, streams draft plan sections while the final plan is generated, and can search records, search/preview reports, search/inspect dashboards, inspect forecast signals, build reports, navigate to records, and run web research. Explore cards are evidence-backed links to forecast, reports, or dashboards instead of generic navigation suggestions. - **Personalized UI guidance**: GTM Engine tracks compact, privacy-conscious local activity (`gtm:userActivity:v1`) and periodically stores a model-generated `ui_guidance_profile` on `user_preferences`. The sidebar can show one non-intrusive suggestion based on what the user has and has not used. ### System Tools Genie Can Use Genie has a catalog of tools it picks from based on the page context and the user's ask. Every Genie tool is available to every Genie-style agent unless the agent config restricts it. **Knowledge & search:** 1. **Product Help** (`product_help`) — answers questions about GTM Engine features using this product guide. Tailors responses to the user's role. 2. **Search Records** (`search_records`) — searches accounts, contacts, opportunities by name/text. 3. **Search Reports** (`search_reports`) — finds existing saved reports by name or entity type before Genie builds a new one. Use when the user asks "do we already have a report for X?" — Genie checks the saved-reports library first instead of duplicating. 4. **Preview Report** (`preview_report`) — reads an accessible saved report's configuration, visualizations, approximate row count, and sample rows so agents can ground recommendations in actual report context. 5. **Navigate to Record** (`navigate_to_record`) — finds a record and returns a preview card with a link. 6. **Research Web** (`research_web`) — researches current external information using web research providers and returns cited findings. **Reports & dashboards:** 7. **Build Report** (`build_report`) — translates natural language into filters, columns, grouping, charts (including `dateGroupBy` and `groupSortBy`). Works on accounts, contacts, opportunities, and activities. 8. **Search Dashboards** (`search_dashboards`) — finds accessible dashboards and returns widget/report summaries plus dashboard links. 9. **Inspect Dashboard** (`inspect_dashboard`) — reads an accessible dashboard's widgets and linked report visualizations before recommending it. 10. **Get Forecast Insights** (`get_forecast_insights`) — returns concrete forecast signals such as in-quarter risk, no-next-activity deals, and deals that moved out of the quarter. 11. **Add Dashboard Widget** (`add_dashboard_widget`) — adds a report visualization to the current dashboard as a widget. Accepts either a freshly-built `build_report` result or a `report_visualization_id` from `search_reports`. 12. **Reposition Dashboard Widget** (`reposition_dashboard_widget`) — moves or resizes one or more widgets on the current dashboard. 13. **Remove Dashboard Widget** (`remove_dashboard_widget`) — deletes a widget from the current dashboard. **Configuration / setup assistance:** 10. **Create AI Field** (`create_ai_field`) — proposes a new AI auto-fill field with name, prompt, and typed schema. User reviews and saves. 11. **Create Product ICP** (`create_product_icp`) — creates an account- or contact-level ICP under a product. Starts broad (2-3 core filters) and lets the user refine. See Settings → Products. 12. **Update Product ICP** (`update_product_icp`) — edits an existing ICP's filters. 13. **Fetch Organization Users** (`fetch_organization_users`) — lists org users with role, job function, job level, email, and Slack ID. 14. **Create Team Structure** (`create_team_structure`) — builds a team hierarchy from natural language or JSON. 15. **Delete Team** (`delete_team`) — removes a team by name. 16. **Update Team Targets** (`update_team_targets`) — sets quarterly revenue targets for a team. **Per-page assistance:** 17. **Set Form Field** (`set_form_field`) — fills in form fields on the current page (when fields are registered). 18. **Display Card** (`display_card`) — renders a rich interactive card inline in chat with structured fields, text, and links. 19. **File Support Ticket** (`file_support_ticket`) — opens a pre-filled support ticket form; user reviews and submits. **Memory (runs silently):** 20. **Update Working Memory** (`update_working_memory`) — persists durable facts about the user across conversations. See "Working Memory" below. > The public marketing Genie (www.gtmengine.ai) is intentionally locked down to `product_help` and `submit_demo_request` only — none of the tools above are exposed to anonymous website traffic. ### Generative UI Components Tool results render as interactive UI inline in chat: Report Builder, Record Preview Card, Support Ticket Form, Field Recommendation, Form Fill (apply/dismiss), Dashboard Widget Preview, ICP Filter Preview, Team Structure Preview, Display Card (rich structured card with fields/links). ### Page-Specific Genie Contexts Genie adapts to each page with a tailored agent: - `dashboard_page` — stats, open deals, tasks, meetings, target accounts. - `account_page` — full account context: contacts, opportunities, activities, enrichment. - `contact_page` — contact profile, relationships, engagement. - `opportunity_page` — deal metrics, methodology, contacts, activity history. - `activity_page` — activity content, related records. - `forecast_page` — pipeline data, forecast categories, team hierarchy; also powers Renewal Forecast with renewal-specific page context. - `generate_accounts_page` — target-account prioritization, filters, selected accounts, propensity scores, and scoring actions. - `outreach_page` — outreach sequence list and builder context, including step goals, prompts, saved status, and generated draft previews. - `customer_health_page` — customer account health, churn risk, expansion readiness, handoffs, and CSM churn trends. - `records_home_page` — Records landing-page navigation across accounts, contacts, opportunities, transcripts, and activities. - `records_page` — record list report-builder context for Accounts, Contacts, Opportunities, and Activities. - `transcripts_page` — transcript list/detail context, participants, summaries, related records, and transcript excerpts. - `reports_list_page` — saved reports list and natural-language report building. - `reports_dashboard_page` — dashboard canvas context and dashboard widget management. - `dashboards_list_page` — dashboards list context, folders, tags, favorites, filters, sorting, and sharing/edit access. - `hygiene_assessment_page` — CRM assessment scorecards, storyboards, record-type metrics, history, trends, and integration status. - `hygiene_cleanup_page` — CRM cleanup tabs, summary counts, tab metadata, and cleanup prioritization. - `fields_page` — field definitions, AI field setup help. - `propensity_setup` — help configuring propensity signals and scoring. - `settings_page` — organization, team, product, sales process, and customer success configuration. ### Working Memory (persistent cross-session context) Genie remembers durable facts about each user across conversations — so you don't have to re-explain your role, team, or preferences every chat. - **What's stored**: Role & context (job title, team, function, reporting structure, tenure); goals & priorities (recurring asks, current focus areas, OKRs); preferences (response length, preferred metrics, table vs. prose); org & product context (team size, key stakeholders, ICP, competitive landscape, product areas owned). - **What's NOT stored**: Specific deal names, amounts, close dates, one-off questions, or any transient data. Genie only writes to memory when it learns something reusable. - **How it updates**: Genie silently calls the `update_working_memory` tool whenever it learns something worth remembering. There is no user-facing message — memory updates happen in the background with no chat output. The full memory is always rewritten (merge + add), never appended destructively. - **Where it's stored**: On the user record (`users.agent_working_memory`), scoped to the individual user, not the organization. Two users at the same company have separate memories. - **How it's used**: At the start of every Genie turn, the user's current memory is injected into the system prompt as `[What you remember about this user from past conversations]`, so subsequent turns are pre-contextualized. This is why Genie can answer "show me my pipeline the way I usually want it" without the user re-stating formatting preferences. - **How to clear / edit**: Memory is text and lives on the user row. Admins can clear a user's memory via direct DB update; a per-user "clear memory" UI is on the roadmap. Asking Genie "forget what you know about me" does not currently reset memory — this is a known gap. ### Prompt Library - **Access**: All roles (organization-level prompts managed by Admin/RevOps) - **Location**: Book icon in the Genie chat input area. - **Visibility**: Personal / Organization / Suggested (curated). - **Page context**: Prompts can be scoped to specific pages (opportunity-only, dashboard-only, all-pages). Only relevant prompts appear. ### Dynamic Suggestions Contextual prompt suggestions above the input area are dynamically generated based on the current page and data, plus static examples configured for the agent. ### Personalized UI Guidance The app records broad usage signals rather than raw clickstreams. Examples include page categories visited, whether the user saw important components, and high-signal actions such as using the forecast Sankey, saving report columns, building a report, adding a dashboard widget, generating target accounts/contacts/outreach, using Grow pages, saving profile context, or configuring automation. A small model periodically reasons over these signals, the user's role/job level, plan, onboarding state, and preferences to produce a `ui_guidance_profile`. - **Storage**: Local activity snapshot in browser storage; generated profile in `user_preferences.ui_guidance_profile`. - **Throttling**: Generation is throttled by activity count and time to avoid excessive model calls. - **Fallback**: If the model fails, a deterministic fallback suggestion is stored. - **Display**: The sidebar guidance tip hides if dismissed, expired, low-confidence, or already on the suggested target page. ### Multi-Platform Agent Chat — Slack & Teams - Beyond the in-app sidebar, Genie-style agents can be exposed inside **Slack** and **Microsoft Teams** channels from a single code path (Chat SDK). - Per-agent chat config lives at `/api/agents/[id]/chat-config` and is set up from the agent detail page's **Chat Config** tab (platform selector: Slack / Teams, per-platform credential forms, webhook URL display, setup instructions). - After connecting Slack on the Integrations page, a prompt appears to add the GTM Engine bot to the workspace. Since the app is pending marketplace approval, a "Contact Support" modal sends the team a Slack notification with the user's details. ### Public Marketing Genie (Website) A separate, anonymous Genie runs on **www.gtmengine.ai** for prospects. It is a system-level agent (`execution_id: 'marketing_genie'`, `organization_id = NULL`) with a strictly limited toolset: - **Product Help** (`product_help`) — answer questions about GTM Engine features. - **Submit Demo Request** (`submit_demo_request`) — open a demo request form that pre-fills any info the visitor has mentioned (name, work email, company, team size, CRM, use case). The visitor reviews/edits before submitting, and the request is routed to the GTM Engine **success team**. **Framing for prospects**: When offering the demo request form, the assistant should describe the follow-up as coming from the **success team** — a helpful team whose job is to answer questions, help prospects get set up, and make sure the product fits — rather than "sales". Prospects should never feel like filling out the form will trigger a high-pressure sales cycle. This public Genie has **no access** to any customer's CRM, data, or tools. It runs behind a `marketing`-permission API key on `packages/api` at `POST /v1/genie/chat` (and `POST /v1/genie/demo-request` for form submissions, which post to Slack via `SLACK_DEMO_WEBHOOK_URL`). --- ## 11. Settings Settings pages are accessible from the sidebar navigation. Most require Admin or RevOps. ### Sales Process Configuration - **Page**: `/close/sales-process` (legacy `/settings/configuration` redirects where applicable) - **Access**: Admin, RevOps - **Why it matters**: Org-wide settings that affect how data is displayed, how forecasting works, and how AI scoring behaves. #### Sales Process Tab (`?tab=sales-process`) - **Pipelines**: Create and manage sales pipelines. - When **HubSpot or Salesforce is connected**, pipeline names and structure are owned by the CRM. Edit / Rename / Delete pipeline actions and the "Create Pipeline" button are hidden; only **"Set as default"** remains. - **Stages**: Add, edit, delete, reorder (drag-and-drop). Set expected duration per stage. - **Entry/Exit Criteria**: What must be true to enter or leave a stage. Powers methodology tracking on opportunity detail pages. #### Salesforce Pipeline Routing - Available on Salesforce orgs via the Pipeline Routing UI in Configuration. - Opportunities are assigned to pipelines based on a configurable Salesforce field (e.g., "Type"). Each pipeline gets its own copy of all Salesforce stages so Closed Won/Closed Lost are scoped per-pipeline (a Renewal Closed Won won't count toward New Business). - Stage ordering always comes from Salesforce's `SortOrder`. - Salesforce stage sync queries the `OpportunityStage` SObject for authoritative `IsClosed` / `IsWon` flags — correctly handles custom closed stages like "Disqualified" or "No Decision". ### Products - **Page**: `/settings/products` - **Access**: Free and paid plans for product configuration where allowed by plan; Admin/RevOps manage shared products. - **Product Catalog**: Name, description, value proposition, features, pricing, ROI. Used by enrichment, propensity scoring, AI Data/Analysis fields, and deal qualification prompts so the model writes context-aware output instead of generic summaries. #### Product ICPs (per-product Ideal Customer Profiles) ICPs are first-class objects nested under a product. Each product can have many ICPs, and each ICP is either **account-level** or **contact-level**: - **Name + description** — human-readable, shown in ICP pickers across the app. - **Record type** — `account` or `contact`. Account ICPs filter companies; contact ICPs filter people, and contact ICPs can layer on top of their parent account's filters (e.g. "VP of Sales at a mid-market SaaS company"). - **Filters** — structured search criteria: industries, employee count ranges, revenue ranges, geography, tech stack, job titles, seniority, departments, keywords, exclusions. Legacy single-value filters (e.g. `jobTitleKeywords`) are normalized on load. - **Live preview** — before saving an ICP, you can preview the total matching record count and a sample of matches from the data universe. This is the fastest way to sanity-check whether the filters are too broad or too narrow. **Where ICPs are used:** - **Find Prospects** workflow task — accepts a `productIcpId` as input and runs enrichment/prospecting against the ICP's filters. The primary batch entry point for "go find me 500 accounts matching this ICP." - **Product Fit field** — auto-populated AI fields can cite specific ICPs when writing fit summaries. - **Scoring & propensity** — ICP match is a signal in propensity scoring. - **Generate Pipeline** — target account and contact generation use product and ICP context to focus recommendations. - **Genie** — `create_product_icp` and `update_product_icp` let a user say "create a mid-market SaaS ICP under Enterprise Plan, 200-1000 employees, North America, decision-maker titles" and Genie drafts the filters for review. **Why per-product ICPs matter**: A multi-product company doesn't have one ICP — the right customer for the SMB self-serve product is different from the right customer for the enterprise platform. Per-product ICPs mean enrichment, scoring, and prospecting all speak the same product language. ### Organization - **Page**: `/settings/organization` - Organization name. - **Fiscal year start** (affects all period-based reporting and forecasting). - **Timezone**. - Billing and usage visibility, with plan-management actions for admins. ### Propensity Scoring Config - **Page**: `/generate/scoring` - Configure propensity scoring signals, enable/disable scoring, test on sample accounts, and read the drawer documentation explaining how account signal research works. > **Note for Members/Guests**: Organization configuration is managed by admins. Contact your admin to request changes. ### Fields - **Page**: `/settings/fields` - **Access**: Admin, RevOps - **Why it matters**: Fields are the data schema for your records. Proper field configuration ensures CRM data syncs correctly and AI fields generate useful values. #### Tabs - **Opportunities**, **Accounts**, **Contacts**, **Forecast Categories** (when CRM is connected). #### Field Categories - **Standard CRM** — fields mapped from your CRM. - **AI Data** — AI-generated fields that extract data points from activities. - **AI Analysis** — AI-generated fields providing analytical summaries. - **Research** — fields populated by enrichment workflows. - **Outbound** — contact-level outbound campaign fields such as email subjects/bodies and `outbound_campaign_id`. #### Key Actions - Add/edit/delete fields, configure AI auto-fill, CRM mapping, sync direction (to/from/bidirectional/no sync), editability, required level. - Filter by type, auto-fill status, CRM mapping status. - **Suggested mappings**: after a CRM is connected, standard GTM fields can show default HubSpot/Salesforce mapping suggestions that admins can review and apply. - **Suggested fields**: view unmapped CRM fields that could be added. Search and field filters also apply to this unmapped CRM field list. - **GTM-owned account enums**: `relationship_type` and `sales_status` use GTM Engine's canonical enum values and only sync from GTM Engine to the CRM. Their sync direction is locked and explained with a tooltip. - `/settings/fields/ai_field` and `/settings/fields/ai_analysis_field` for detailed AI field configuration. #### Forecast Category Mapping - `forecast_category` stores raw CRM API values (e.g., `"MostLikely"`) — no conversion during sync. All display mapping (CRM label + internal bucketing) happens on the frontend via `forecast_category_mappings`. > **Note for Members/Guests**: Field configuration is managed by admins. Contact your admin to request new fields or changes. ### Integrations - **Page**: `/settings/integrations` - **Access**: Admin, RevOps - **Why it matters**: Integrations are how GTM Engine gets data. Without a CRM there are no records; without call recorders there are no transcripts for AI to analyze. #### CRM (one at a time) - **HubSpot** — OAuth. After connecting, proceed to field mapping. - **Salesforce** — OAuth. Supports Record Type pipeline routing (see Sales Process Configuration). - **GTM Engine CRM** — built-in CRM for orgs that don't use HubSpot or Salesforce. #### Call Recording - **Gong** (OAuth), **Sybill**, **Fathom**, **Grain**, **Read**, **Circleback** (webhook URL into their settings), **Fireflies** (API key, `fireflies-integration` flag), **GTM Engine Call Recorder** (the built-in bot; feature-flagged, configured per-user on the Profile page), **GTM Engine Contact Activity** (custom activity webhook). #### Communication - **Email / Calendar** appears on `/settings/integrations` as a shortcut section for Gmail and Microsoft Outlook. Selecting either option opens `/settings/profile#email-calendar-integrations`, where each user connects their own provider. - **Google Workspace** — each user connects their own Gmail and Google Calendar from Profile. - **Microsoft 365** — each user can connect Microsoft Outlook from Profile; admins can also manage the org-wide Microsoft option. #### Sales Engagement - **Instantly** — connect by entering your API key (found at Instantly → Settings → Integrations → API). Stored securely in GTM Engine integration settings. Used by the Instantly Sequence workflow task. #### Content / CMS - **Sanity** — enter a per-org Sanity Robot Token (stored encrypted). Used by the Sanity Publish Document workflow task to publish documents via `createOrReplace` mutations. #### Chat Platforms - **Slack** — for Genie-style agents embedded in Slack channels (webhook: `/slack/events/:configId`, backward-compatible path preserved). - **Microsoft Teams** — for Genie-style agents in Teams (webhook: `/teams/events/:configId`). Configured per agent via the Chat Config tab on an agent's detail page. #### CRM Field Mapping - After connecting a CRM, mapping is done on the unified Fields page. Tabs: Accounts, Opportunities, Contacts, Forecast Categories. Map GTM Engine fields to CRM properties (HubSpot or Salesforce). Field groups: Standard CRM, AI Data, AI Analysis, Summary. > **Note for Members/Guests**: Integration setup is managed by admins. You can connect your own email/calendar from your profile. ### API Keys - **Page**: `/automation/api` (legacy `/settings/organization/api-keys` and `/settings/api_keys` redirect) - **Access**: Admin, RevOps - **Why it matters**: For customers building integrations against GTM Engine's public REST API (`packages/api`). - **Permissions**: - `read` — Read-only access to CRM records (accounts, contacts, opportunities, etc.). - `read_write` — Full CRUD on CRM records. - `marketing` — Access only to `/v1/genie/*` routes for the marketing site chatbot. **Cannot read or write CRM data.** Issue keys with this permission for the public marketing Genie. - **Status**: `active` / `disabled`. Optional expiration. Keys are hashed at rest; only the preview is retained after creation. - **Docs**: OpenAPI docs at the API's `/docs` endpoint; `X-Api-Key` header. ### Team Members (Account Settings) - **Page**: `/settings/team/members` - **Access**: Admin, RevOps - **User table**: Name, email, role, job level, status, quota, email sync, transcript processing. - **Actions**: Add, edit, invite / resend / revoke, activate/deactivate, delete (optionally reassign records). Search by name/email. - **Onboarding hook**: Changes here (activate/deactivate/invite) update onboarding status. - **Roles**: Admin (full), Member (standard), Guest (read-only). - **Job levels**: Executive, Manager, AE, others. Controls forecast/performance access. - **Quota**: Q1–Q4 targets for current and next fiscal year. - **Transcript processing**: Enable/disable AI transcript processing per user. - **Seat Usage**: Occupied vs. purchased seats. Admins see a self-serve **Manage seats** flow instead of a dead-end dialog. The flow shows current usage, seat price, amount due now for increases, future recurring cost, and scheduled reductions. Paid-plan admins can add prorated seats to the existing subscription, or jump to Billing & Usage to compare all plans when a higher off-the-shelf plan covers the requested total seat count; admins already on the top self-serve tier are routed to support for a custom plan. Free-plan organizations open an upgrade plan selector before adding seats. Seat increases become available after Stripe confirms payment; reductions are scheduled for the next billing cycle with no refund or credit and must still cover the current occupied team size. Non-admins are told to ask an organization admin, and custom/manual subscriptions are directed to support. ### Team Structure - **Page**: `/settings/team/structure` - **Access**: Admin, RevOps (save: Admin only) - **Why it matters**: Defines who reports to whom — drives data visibility in forecasting, performance tracking, and team hierarchy tabs. - **Features**: Org chart, add/edit/delete teams (with managers and members), quarterly targets per team for current and next fiscal year, rollup settings. Delete uses a proper modal dialog (no browser `confirm`). Deleting unsaved team nodes does not make API calls. Save/delete updates onboarding status. ### Profile - **Page**: `/settings/profile` - **Access**: All roles - **Sections**: Profile Header (name, photo), Profile Details (including LinkedIn URL), Email Instructions and signature, Quota, Integrations (personal Google/Microsoft for email & calendar), and GTM Engine Call Recorder settings (feature-flagged). - **Personalization**: LinkedIn URL can be scraped into `linkedin_profile`, profile photo can be uploaded to Cloudinary, and `job_description_summary` / `daily_plan_preferences` are generated automatically rather than manually edited. - **Timezone**: Defaults from the user's browser when available and is used by the Genie Day Planner. ### Billing, Plans, and Credits - **Page**: `/settings/organization` - **Access**: All users can review billing health. RevOps users can view credit balance and usage. Admins can change plans, open the Stripe Billing Portal, buy credit packs, subscribe to monthly credit packs, cancel credit subscriptions, and view invoice links. - **Self-service plans**: Admins choose a plan on `/settings/organization`. Paid plans use Stripe Checkout for new subscriptions and Stripe prorations for active plan changes. Downgrading to Free cancels the paid Stripe subscription before GTM Engine switches the org's local plan. - **Self-service additional seats**: Admins can manage seats from `/settings/team/members` when they hit the seat limit, or proactively from the Seats card on `/settings/organization`. Additional seats are priced from the plan's overage seat price (`overage_seat_price_cents`). Paid plans add a separate recurring subscription item to the existing Stripe subscription; when a higher non-custom plan includes enough seats for the requested total, the modal links to Billing & Usage's full plan selector for comparison instead of starting a direct upgrade. Top self-serve tiers are routed to support for custom plans. Free plans route admins to upgrade before adding seats. Increases only update GTM Engine entitlements after Stripe confirms payment through the webhook. Reductions update the Stripe add-on quantity with no proration/refund, remain pending locally, and only lower GTM Engine entitlements after the next paid billing cycle syncs. - **Payment methods and invoices**: Admins use the Stripe Billing Portal from `/settings/organization` to update payment methods. Invoice URLs/PDFs and card brand/last4 are only shown to billing admins. - **Billing history**: The History tab records plan and seat changes, including confirmed seat additions, scheduled reductions, cancellations, resumes, and downgrades to Free. Workflow credit consumption appears in usage detail instead of billing history. - **Credit packs**: One-time credit packs are available to Free and paid organizations. They charge the saved Stripe payment method when available or open an embedded Stripe Payment Element when a card is needed; credits are granted from `payment_intent.succeeded` metadata and do not require a paid base subscription. Recurring credit-pack subscriptions are tracked as Stripe subscription items and can be cancelled from the same page. - **Monthly credits**: Monthly credit subscriptions grant credits on successful Stripe `invoice.paid`. A scheduled fallback grants missed/custom/manual plan credits idempotently, but Stripe-backed subscriptions are skipped unless the latest paid subscription period is healthy and covers the due period. Enterprise annual contracts skip monthly plan-credit grants because their credits are granted upfront for the contract year. - **Payment failures**: Failed payments do not grant credits. Stripe-backed subscriptions in `past_due`, `unpaid`, `incomplete`, `incomplete_expired`, or `paused` are skipped by the fallback. If a Free-plan seat-only subscription payment fails, GTM Engine removes paid-seat entitlement and marks every user except one billing admin inactive so the preserved admin can update payment or reduce seats. - **Workflow credit gate**: Billable custom workflows check organization credits before billable tasks start. Organizations can have a negative credit floor (default around -1000) before new billable work is blocked. Field tasks (the AI Prompt / Research tasks attached to record fields under `/records/.../fields`) are billed per-task: system-default field tasks GTM Engine ships are seat-billed (free, recorded for analytics only), but custom field tasks an organization configures themselves consume credits the same way an ad-hoc custom workflow's billable tasks do. - **AI task costing**: AI Prompt and Agent workflow tasks can charge a configurable flat execution fee plus pass-through token cost. Token costs convert to credits at real cost where 1 credit equals $0.01 by default, and non-zero AI spend rounds up with `Math.ceil`. - **Free Plan gating**: Free Plan users see locked paid pages with route-specific blurred previews that tease relevant reports, insights, and automation value behind the upgrade card. ### Slack - **Page**: `/settings/slack` - **Why it matters**: Receive notifications about deals, AI insights, and activity updates in Slack. See Integrations and the Chat SDK section above for multi-platform agent chat. --- ## 12. Support & Feedback - **Available**: Feedback button in the sidebar, or ask Genie to file a support ticket. - **Access**: All roles. ### Filing Support Tickets - **Via Genie**: Ask Genie "I need help with..." or "file a support ticket." Genie opens a pre-filled form (subject, description, priority). Review and submit. - **Via Feedback Button**: Click the feedback button in the sidebar to submit general feedback. - **Ticket details**: Subject, description, priority (low/medium/high/urgent). Tickets are tracked in the system and sent to the support team via Slack. ### Marketing-Site Questions Visitors on www.gtmengine.ai who want a demo or follow-up don't file a support ticket — the public Marketing Genie opens a demo request form that posts to Slack for the GTM Engine **success team** to pick up. The success team handles prospect questions, demos, and help getting set up — not high-pressure sales. --- ## 13. Roles & Access Reference ### Roles | Role | Description | Access Level | |------|-------------|--------------| | **Admin** | Organization administrator | All settings, all records, user management, integrations, **workflows & agents**, triggers, API keys | | **RevOps** | Revenue Operations | All settings, all records, workflows, triggers, agents, automation | | **Member** | Standard sales team member | Home, profile, records, available Generate Pipeline surfaces, and plan-allowed hygiene/close/grow surfaces | | **Guest** | Read-only access | View records, reports, and dashboards only | ### Job Levels and Plan Access | Job Level | Forecast | Performance | Home | |-----------|----------|-------------|------| | **Executive** | Yes, when plan allows | Yes, when plan allows | `/home` | | **Manager** | Yes, when plan allows | Yes, when plan allows | `/home` | | **AE** | No | No | `/home` | | **Other** | No | No | `/home` | Free Plan capabilities include Home, Profile, basic Records, Products, and Generate Pipeline. Paid plans unlock the full Close Pipeline, advanced reports/dashboards, CRM Hygiene, Automation, Integrations, Fields, and organization-level configuration. Grow Customers is currently visible but not generally available; users are prompted to contact Support. ### Feature Flags Some features require feature flags to be enabled for the organization: | Flag | Feature | |------|---------| | `transcripts-view` | Transcripts page in Records | | `crm-assessment` | CRM Assessment page | | `propensity` | Propensity Scoring Config | | `fireflies-integration` | Fireflies integration | | `calendar` | Calendar widget and meeting context | ### Common Role-Based Guidance - **"I can't see the Forecast page"** — Forecast requires Manager or Executive job level and paid forecast access. Contact your admin. - **"I see an upgrade card instead of the page"** — The route is available as a paid-plan teaser, but the organization's current plan does not include that capability. - **"I can't see the Automation section"** — Automation requires Admin or RevOps and paid automation access. - **"I can't see Settings"** — Most settings require Admin or RevOps. You can still access your profile at `/settings/profile`. - **"I can't access Transcripts"** — The `transcripts-view` feature flag must be enabled for your organization. - **"I want to connect my email"** — Go to `/settings/profile` and connect Google or Microsoft in the Integrations section. - **"I want to change the CRM integration"** — Contact your Admin — CRM connections are managed at `/settings/integrations`. - **"I want to try GTM Engine"** (prospect) — Go to `/get-started` and use a work email. Free accounts do not require a credit card and include 1000 credits. You can also ask the assistant on www.gtmengine.ai to open a demo request form. --- ## 14. Quick Reference — Page Paths | Page | Path | Access | |------|------|--------| | Home | `/home` | All | | Auth Entry | `/` | Anonymous and authenticated | | Public Sign-Up | `/get-started` | Anonymous | | Sign-In | `/sign-in` | Anonymous | | Company Setup | `/signup` | Authenticated self-serve users | | Generate Target Accounts | `/generate/accounts` | All plans | | Propensity Scoring Config | `/generate/scoring` | Admin, RevOps; Free Plan available | | Outreach Campaigns | `/generate/outreach` | All plans | | Forecast | `/close/forecast` | Manager, Executive, paid | | Pipeline | `/close/pipeline` | Paid | | Team Performance | `/close/performance` | Manager, Executive, paid | | Sales Process | `/close/sales-process` | Admin, RevOps, paid | | Customer Health | `/grow/health` | Not generally available; users see Contact Support | | Renewal Forecast | `/grow/renewal-forecast` | Not generally available; users see Contact Support | | Customer Success Config | `/grow/customer-success-config` | Not generally available; users see Contact Support | | CRM Assessment | `/hygiene/assessment` | Admin, RevOps (flag) | | Record Cleanup | `/hygiene/cleanup` | Admin, RevOps, Member, paid | | Duplicates | `/hygiene/duplicates` | Admin, RevOps, Member, paid | | Stale | `/hygiene/stale` | Admin, RevOps, Member, paid | | Empty | `/hygiene/empty` | Admin, RevOps, Member, paid | | Strays | `/hygiene/strays` | Admin, RevOps, Member, paid | | Orphaned | `/hygiene/orphans` | Admin, RevOps, paid | | Activity Hygiene | `/hygiene/activities` | Admin, RevOps, Member, paid | | Hygiene Rules | `/hygiene/rules` | Admin, RevOps, paid | | Accounts List | `/records/accounts` | All | | Account Detail | `/records/accounts/{id}` | All | | Contacts List | `/records/contacts` | All | | Contact Detail | `/records/contacts/{id}` | All | | Opportunities List | `/records/opportunities` | All | | Activities List | `/records/activities` | All | | Activity Detail | `/records/activities/{id}` | All | | Transcripts List | `/records/transcripts` | All (flag) | | Transcript Detail | `/records/transcripts/{id}` | All (flag) | | Report Builder Guide | `/records/docs/report-builder` | All | | Reports | `/reports` | All | | Dashboards | `/dashboards` | All | | Dashboard Detail | `/dashboards/{id}` | All | | Workflows | `/automation/workflows` | Admin, RevOps | | Workflow Detail | `/automation/workflows/{id}` | Admin, RevOps | | Workflow Fields | `/automation/workflows/fields` | Admin, RevOps | | Triggers | `/automation/triggers` | Admin, RevOps | | Trigger Detail | `/automation/triggers/{id}` | Admin, RevOps | | New Trigger | `/automation/triggers/new` | Admin, RevOps | | Agents | `/automation/agents` | Admin, RevOps | | Agent Detail | `/automation/agents/{id}` | Admin, RevOps | | Automation Map | `/automation/map` | Admin, RevOps | | Sales Process Configuration | `/close/sales-process` | Admin, RevOps | | Products | `/settings/products` | Admin, RevOps; Free plan allowed | | Organization | `/settings/organization` | Admin, RevOps | | Fields | `/settings/fields` | Admin, RevOps | | AI Field Config | `/settings/fields/ai_field` | Admin, RevOps | | AI Analysis Field | `/settings/fields/ai_analysis_field` | Admin, RevOps | | Integrations | `/settings/integrations` | Admin, RevOps | | API Keys | `/automation/api` | Admin, RevOps | | Team Members | `/settings/team/members` | Admin, RevOps | | Team Structure | `/settings/team/structure` | Admin, RevOps | | Profile | `/settings/profile` | All | | Slack | `/settings/slack` | All |