clickmax-funnels

As tools abaixo aparecem com os nomes que o MCP da Clickmax registra. Se o seu cliente de IA prefixar nomes de tool (mcp<servidor>, mcp<servidor>, ou outro), use o nome já prefixado que aparecer na sua lista de tools.

When this applies

Use this skill when the user wants to operate a Clickmax funnel: inventory it, create/edit graph nodes, connect triggers/pages, validate, publish, deactivate, delete, or inspect analytics.

Not this skill:

• Funnel step backed by an EXTERNAL page (URL hosted outside Clickmax, e.g. the user's own site/domain) -> STAY here: compose the granular tools (see the external-page common flow below). Never use pages_create for an external URL — that makes an empty INTERNAL page.
• Script-install help for an EXISTING external page (no graph change) -> clickmax-external-pages
• Lead/payment cohort analysis inside a funnel -> solve that with the relevant sales/CRM skill first
• Full AI-authored funnel with responsive page copy/design -> stay here and follow [AI funnel creation](references/ai-funnel-creation.md); load clickmax-pages alongside it, because that skill owns everything that happens inside a single page.
• ONE page, with no funnel graph involved (create, restyle, rebuild, configure, publish a single page) -> clickmax-pages
• Fine-grained visual edits after creation (moving one block or changing one mounted element) -> page editor UI.

Build completion rule (mandatory)

• ONE build = ONE funnel. Call funnelscreate exactly once. If a later step fails, validation is dirty, or the graph looks wrong, FIX the existing funnelId in place — re-run only the specific failing funnelsnodecreate/connect/funnelsabtestvariantsupdate — NEVER call funnelscreate again to "start over". Retrying by re-creating leaves duplicate funnels (and if you also publish each attempt, several live funnels with the same name). If a prior attempt already left a half-built funnel, delete it with funnelsdelete (or reuse it) instead of stacking another.
• Do NOT publish until the build is complete and funnels_validate is clean and the user asked to go live — never publish an attempt you might abandon.
• Creating nodes is only half the job. A funnel build is incomplete until its nodes are routed.
• After creating page nodes you must connect them with funnelstriggersconnect and, for non-page node families, with the type-specific tool (funnelsabtestvariantsupdate, funnelsconditionalbranchesupdate, funnelstrafficsource_update).
• Never end the turn with page nodes whose triggers still have no target: unrouted triggers show up as loose, disconnected nodes with no edges in the editor.
• Multi-node builds should do create + connect as one continuous workflow, not in stop-and-go calls that might stop before the connect step.
• Before reporting done: call funnelsstructureget, confirm every intended route has an edge, then call funnels_validate; if there are leftover disconnectedTriggers or orphanNodeIds, surface them instead of silently finishing.

Key assumptions

• Scope = one workspace + one project; never ask for workspace id
• Funnel lifecycle = draft -> published -> unpublished_changes after graph edits -> republish, or disabled after deactivate
• Graph = nodes + embedded triggers/variants/branches/outputs depending on node type
• Trigger, branch, and variant ids are server-generated; always read them from create/structure output
• Manual node creation is not a stopping point by itself; after funnelsnodecreate, always finish the wiring step
• Funnel workflow nodes own the entry (page trigger feeding the flow) and exit (flow-membership end) of their linked flow — this is flow membership, not page routing; a workflow never forwards the visitor to a page. Do not also configure standalone flow triggers for that embedded automation
• funnels_validate.valid is not enough by itself; still inspect disconnected triggers, orphan nodes, and missing page links
• Delete tools are destructive and should be confirmed unless deletion was already explicit
• Connections define the visual flow: the builder arranges the funnel left-to-right by following routed edges. Disconnected nodes have no graph flow, so they tend to stack in the first column.

• Read [lifecycle and safety](references/lifecycle-and-safety.md) when deciding between draft edits, publish, deactivate, or destructive delete.
• Read [node types and edges](references/node-types-and-edges.md) when choosing node types and the correct connection tool for each edge family.
• Read [templates and starters](references/templates-and-starters.md) when the user wants a standard funnel shape that maps to a sequence template.
• Read [AI funnel creation](references/ai-funnel-creation.md) when the user wants discovery, automatic decisions, or a full assembled funnel.
• Load the clickmax-pages skill whenever a build has to produce page content. It owns the page authoring pipeline, the visual system, the section spine and copy, and the form/checkout/CTA/motion contracts; nothing here restates them.

Thought process

1. Classify the request: read/list/analytics vs create/build/connect vs AI-authored funnel vs publish/deactivate/delete.
2. Resolve projectId and funnelId first.
3. Prefer template scaffolds for common funnel families; prefer manual graph creation only when the user describes a custom route.
4. Use funnelsstructureget as the canonical graph view before connecting, publishing, deleting, or diagnosing.
5. Keep graph wiring separate from page authoring: page nodes can exist before page ids are connected.
6. Always finish the wiring after node creation. A build that created nodes but skipped connecting them is not done.
7. Publish only after validation is clean enough and the user explicitly wants the funnel live.

Execute guide

Use the tools in dependency order when later ids come from earlier results.

• Resolve the target project with projectsfilters or list funnels with funnelslist when the project or funnel is not yet known.
• Read one funnel with funnels_get, passing the funnelId.
• Use funnelsstructureget, passing the funnelId, as the canonical graph view before wiring, publishing, deleting, or diagnosing.
• For a standard starter, create the funnel with funnelscreate, then scaffold the graph with funnelssequence_create. Set objective on create to the funnel's obvious goal (capture | sales | scheduling | diagnosis); it pre-configures the Analytics metrics. When you scaffold from a template, the objective + metrics are auto-derived — don't re-set them.
• For a custom graph, create nodes with funnelsnodecreate, then read back the generated trigger, branch, variant, or output ids before routing them.
• For page nodes or other trigger-based draft nodes, connect outgoing edges with funnelstriggersconnect.
• For A/B test nodes, route each variant with funnelsabtestvariantsupdate, giving every variant its OWN distinct page node in connectedTo (clone the base page once per variant with pagesclone first); two variants sharing one page is not a test.
• For traffic source nodes, route the output with funnelstrafficsource_update.
• For conditional nodes, route each branch with funnelsconditionalbranches_update.
• When real page ids already exist, attach them to the correct page nodes with funnelsnodeconnect_page before publishing.
• Validate with funnels_validate, passing the funnelId, then re-read structure if you need to confirm every intended edge is present.
• Publish only when the user wants the funnel live: use funnels_publish with the funnelId and the node ids that should go live.
• Page-level operations on a linked editor3 page: publish a single page on its own with pagespublish, adjust its checkout/settings with pagesupdateconfig, or duplicate it with pagesclone (e.g. to seed A/B variations from one built page).

Common flows:

• AI-authored funnel = follow [AI funnel creation](references/ai-funnel-creation.md) for the funnel half and clickmax-pages for the page half: guided or automatic discovery -> one brief -> one design for the whole funnel -> one draft funnel -> authored draft pages with pagesimporthtml_draft -> graph connections -> structure check -> validation. Never publish as part of automatic creation.
• Template funnel = use funnelscreate, then funnelssequencecreate, then funnelsvalidate, then publish only if the user asked for it.
• Custom funnel = use funnelsnodecreate, then the correct connection tool for that node family, then funnelsstructureget, then funnels_validate.
• Go live with existing pages = use funnelsnodeconnectpage, then funnelsvalidate, then funnels_publish.
• Page WITH a checkout = pagestemplateslist (type: ["checkout"], pick canUse: true), then pagescreate (type: "checkout" + templateId + offerId + funnelId) so the offer is auto-bound to the checkout, then funnelsnodeconnectpage to link it. See [pages and checkout](references/pages-and-checkout.md).
• Funnel step is an EXTERNAL page (the user gives a URL hosted OUTSIDE Clickmax — their own site/domain/landing) = compose these granular tools in order (NEVER pages_create — that makes an empty INTERNAL page):

1. pagescreateexternal (projectId + externalUrl + name + type) -> returns the pageId. projectId = the FUNNEL's project; a page from another project is refused at connect time. 2. funnelsnodecreate (funnelId, type: "page", a slug, pageType, and triggers = one contactcaptured + one undefined) -> returns the page node id. 3. funnelsnodeconnectpage (funnelId + nodeId + pageId) — linking an EXTERNAL page auto-wires node.config.externalUrl, so the funnel 302-redirects visitors to the URL and tracks them (no manual config needed). ONE page per node: repeat 2+3 per page (each page needs its OWN node). 4. funnelstriggersconnect to route the contactcaptured trigger to the next node (e.g. the thank-you page). 5. pagesgetexternalscript (pageId) -> returns headScript (paste in <head>); for lead-capture + redirect snippets use the clickmax-external-pages skill references. The external page does NOT track or advance until headScript is installed.

• Checkout page WITH order bumps = set them after the checkout page exists and is linked to its node, with checkoutssetorderbump. Bumps ARE offers, so create them first with offerscreate/products_create. Full parameter semantics are in clickmax-pages.
• A/B test across pages = the split only tests something if each variant resolves to a DIFFERENT page. Build the base page once (pagescreate from a template), then pagesclone it once PER additional variant (each clone is a separate editable page); connect each page to its own page node (funnelsnodeconnectpage), create the abtest node (funnelsnodecreate), and call funnelsabtestvariants_update with EACH variant's connectedTo set to a DIFFERENT page node id and the percentage split across them. The variant pages may reconverge downstream (e.g. all route on to one checkout), but their connectedTo targets must be distinct — never point two variants at the same page.
• Funnel WITH an embedded automation (e.g. "on lead capture, run an email automation") = build the capture page AND its page route (e.g. to the thank-you page) first, then call funnelsworkflowautomationcreate with funnelId + projectId + the capture page node id (capturePageNodeId, from funnelsstructureget) + a title (those four ONLY — there is NO next-page/connect parameter). That ONE atomic call adds the workflow node, wires the capture lead trigger into it as a PARALLEL side-effect (the trigger KEEPS routing the visitor to its existing page — nothing is disconnected), creates the flow, and links them (funnel-managed, shown in the canvas as a workflowinput edge). The workflow is TERMINAL: it does NOT forward the visitor onward, so never try to give it an outgoing edge or exit to "reach" the thank-you page — the visitor path continues from the page trigger's own route, in parallel. Idempotent per capture trigger: do NOT re-call it to "start over" (that stacks duplicate automations) — fix the existing one in place, or funnelsnodedelete a bad attempt. It returns flowId + entryStepId; then add the message with flowssendwhatsapp/flowssendemail and connect it to entryStepId (pass it as target, or use flowsstepconnect), then flowsvalidate. Only fall back to building it by hand (funnelsnodecreate type=workflow → funnelsworkflowflowset → funnelstriggersconnect, in that order so the flow is linked before the trigger is wired) for a non-standard shape; never hand-set the flow's funnelId or its start triggers for an embedded automation.

• Full "capture + thank-you (+ email on capture)" build: resolve the project with projectsfilters, create one funnel with funnelscreate, and scaffold its capture and thank-you nodes with funnelssequencecreate using the lead-magnet template. For authored content, create each page with pagesimporthtmldraft; for a ready-made template, use pagescreate. Connect each returned page id to its matching node with funnelsnodeconnectpage. For email, follow the embedded-automation recipe above using the capture node id from funnelsstructureget, then validate with funnelsvalidate. Publish only if asked.
• Read [templates and starters](references/templates-and-starters.md) to choose between sales, lead-magnet, webinar, tripwire, vsl-auto, and upsell-downsell.
• Read [node types and edges](references/node-types-and-edges.md) when deciding which connection tool owns each edge.
• Read [lifecycle and safety](references/lifecycle-and-safety.md#publish-checklist) before publishing, deactivating, or deleting.

Report

• For reads: name | id | projectId | status | publishedAt | node count | key problems
• For create/build: return funnel id, discovery mode, assumptions, visual direction, created page/node labels, validation summary, factual gaps, and next action
• For publish: report whether the funnel went live, how many nodes were published, and any remaining manual element wiring
• For deactivate: explain that the funnel is offline, not deleted
• For analytics: summarize the main period metrics instead of dumping raw payloads
• Cap long node/trigger lists and prefer graph summaries

Warnings

• Resolve real projectId, funnelId, nodeId, triggerId, and pageId; never invent them
• Publish from fresh structure data, not stale ids captured before later edits
• valid=true can still hide non-blocking but important issues like missing pages or disconnected triggers
• API-created graphs may need visual rearrangement in the builder; do not promise tidy coordinates
• Use the correct edge tool for the node family (funnelstriggersconnect, funnelsabtestvariantsupdate, funnelstrafficsourceupdate, funnelsconditionalbranches_update)
• funnelsnodeconnectpage rules, all refused server-side: target = page/draft node ONLY (never abtest/conditional/workflow/traffic_source/quiz — connect THOSE to a page node instead) | page and funnel in the SAME project | one page per node, so a second call REPLACES the first and returns the swapped-out page in replacedPageId — read it before reporting two pages as linked
• funnels_validate.nodesWithUnusedPage = node carrying a page its type never serves (legacy link); the visitor never reaches that page
• For a workflow node, link its flow (funnelsworkflowflowset, resolving flowId via flowslist/flowscreate) and set its exit event (funnelsworkflowexittriggerset); a workflow without a linked flow does not fire automation and is flagged by funnelsvalidate.workflowsMissingFlow
• For a workflow node, configure entry/exit from the funnel side; flow-level start events are for standalone automations, not funnel-embedded flows
• Creating nodes without connecting them leaves a broken-looking graph: no routed edges and stacked nodes
• When the target project, product, or offer is ambiguous, ask the user to choose an existing entity or explicitly request a new one before mutation.
• Never fabricate testimonials, customers, metrics, certifications, dates, scarcity, guarantees, or outcomes while filling skipped discovery answers.

Anti-patterns

• Asking for workspace id
• Using raw funnelsget as the only planning source when funnelsstructure_get gives the compact graph view
• Connecting nodes by slug/label instead of real ids
• Creating page nodes and stopping before funnelstriggersconnect, leaving loose unrouted nodes in the editor
• Splitting create and connect across separate incomplete steps so the build stops before routing is finished
• Deleting a funnel when the user only wants it offline or paused
• Creating a BLANK page when the user wanted a checkout/sales page — start from a template (pagestemplateslist) and pass offerId so the checkout is bound, instead of leaving an empty page
• Building an abtest and pointing every variant's connectedTo at the SAME page (all the percentages bound to one page) — that splits traffic to one destination and tests nothing; clone the base page (pagesclone) once per variant and give each variant a distinct page node
• Connecting two pages to the SAME node and reporting both as added — the second silently replaced the first (replacedPageId says which); one node per page
• Retrying a failed/imperfect build by calling funnelscreate again — it leaves duplicate funnels (all published/live if you also publish each try). One build = one funnel: fix the existing funnelId in place, or funnelsdelete the broken attempt before restarting; never stack a fresh funnel on top of a failed one
• Creating page nodes BOTH ways in one build — funnelsnodecreate by hand AND funnelssequencecreate — leaves the manually-created nodes orphaned and forces a messy delete/reconnect cleanup. Decide the skeleton ONCE up front: for a standard family (capture→thank-you, sales, webinar, …) use funnelssequencecreate alone and connect pages to ITS nodes; use funnelsnodecreate only for a custom graph the templates don't cover — never both
• Treating a workflow as a step BETWEEN pages — it is a parallel side-effect with no visitor output, so giving it a flowcompleted/pageviewed exit to "reach" the next page does nothing. On lead capture the SAME trigger routes the visitor to the page AND feeds the automation in parallel (funnelsworkflowautomation_create keeps the page route); never re-point the capture trigger onto the workflow to add an automation — that used to disconnect the page