{"version":"5.1.0","version_changelog_url":"https://www.tracklution.com/agent-install-reference.md#changelog","signup_url":"https://www.tracklution.com/start","dashboard_url":"https://www.tracklution.com/dashboard","agent_protocol_url":"https://www.tracklution.com/agent-install.md","agent_protocol_reference_url":"https://www.tracklution.com/agent-install-reference.md","mcp_url":"https://mcp.tracklution.com/mcp","api_base_url":"https://api.trlution.com/mcp-api/v1","quick_setup_url":"https://api.trlution.com/install/quick-setup","agent_contract":{"version":"1.0.0","primary_doc":"https://www.tracklution.com/agent-install.md","reference_doc":"https://www.tracklution.com/agent-install-reference.md","host_detection":{"cursor":["dir:.cursor/","file:~/.cursor/mcp.json","process:cursor"],"claude_code":["path:claude","dir:~/.claude/"],"codex":["path:codex","dir:~/.codex/"],"windsurf":["dir:~/.codeium/windsurf/","process:windsurf"],"cline":["dir:saoudrizwan.claude-dev","dir:~/.cline/"],"lovable":["host:lovable.dev"],"replit":["host:replit.com"],"bolt":["host:bolt.new"]},"turn_1_question":"Tracklution needs your email and website URL. Reply with both (e.g., you@example.com mysite.com). Type `advanced` to use OAuth instead.","turn_1_skip_if":"initial prompt already contains both email and url","turn_2_branches":{"email_and_url":"magic_install","advanced_synonyms":["advanced","oauth","login","sign in","connect","i have an account"],"advanced":"oauth_install","malformed_url":"ask_once_then_retry","api_409_duplicate_account":"oauth_fallback","api_next_action_oauth_fallback":"oauth_fallback"},"turn_3_handoff_magic_file_edit":"I added the Tracklution MCP. Enable it in your editor's MCP settings, then reply `go`.","turn_3_handoff_magic_cli":"I added the Tracklution MCP via the Claude CLI. Run `/mcp` to confirm it's connected, then reply `go`.","turn_3_handoff_oauth_explicit":"I added a tokenless Tracklution MCP entry. Enable it in your editor and click Connect to sign in, then reply `go`.","turn_3_handoff_oauth_duplicate":"Looks like you already have a Tracklution account. Enable the Tracklution MCP and click Connect to sign in, then reply `go`.","turn_4_sequence_magic":["get_status","get_installation_scripts","apply_snippets","verify_and_score","get_next_steps","create_login_link"],"turn_4_sequence_oauth":["get_status","list_containers","ask_oauth_branch_question","register_and_provision_OR_match_by_website_url","get_installation_scripts","apply_snippets","verify_and_score","get_next_steps","create_login_link"],"turn_4_oauth_branch_question":"You're signed in. Add Tracklution to a NEW website, or connect to an EXISTING container? Reply `new <url>` or `existing`.","turn_4_oauth_branch_new_synonyms":["new","add","install","create"],"turn_4_oauth_branch_existing_synonyms":["existing","connect","pick","choose"],"turn_4_oauth_branch_skip_question_when":"list_containers returns 0 containers (go straight to new <url>)","turn_4_oauth_new_branch_call":"register_and_provision({auth_token, website_url, framework, agent_client, idempotency_key}) WITHOUT email/name -- server reads identity from JWT","turn_4_recovery_401":"silent_oauth_fallback","turn_4_recovery_tool_not_found":"ask_user_to_reload_or_open_new_chat","turn_4_recovery_tool_not_found_message":"The MCP isn't visible in this chat session yet — open a new chat and say `continue Tracklution install`, run Cmd/Ctrl+Shift+P → Developer: Reload Window, or toggle `tracklution` off/on in your MCP settings. Then reply `go`.","turn_4_recovery_multi_client_ambiguous":"Surface next_action.reason verbatim and EXIT. Do NOT call any other MCP tool. The user finishes setup in the dashboard.","turn_4_final_ok":"Tracking is live. Tracklution score: <overall_progress>/100. Top 3 ways to reach 100%: ... Open: <login_link_url> (see turn_5_scored_handoff.template for the canonical multi-line form).","turn_4_final_needs_action":"<verification.message> Tracklution score: <overall_progress>/100. Top 3 ways to reach 100%: ... Open: <login_link_url> (see turn_5_scored_handoff.template for the canonical multi-line form).","verify_and_score_routing":{"done_user_action_no_retry":["ok","awaiting_connector_activation","awaiting_first_party_mode","only_pageview_seen","missing_bottom_funnel_event"],"transient_retry_with_budget":["no_events_after_install","script_not_seen","event_not_received_yet","events_processing"],"code_fix_retry_once":["missing_contact_info","domain_mismatch"],"note":"All paths converge on the Turn 5 scored hand-off. only_pageview_seen and missing_bottom_funnel_event explicitly DO NOT retry -- the user must trigger the event on the live site; a 30s wait won't help."},"turn_5_scored_handoff":{"calls_before_message":["get_next_steps({recalculate: true})","create_login_link({target_page: dashboard|connectors|dns})"],"target_page_selection":"dashboard for ok, connectors for awaiting_connector_activation, dns for awaiting_first_party_mode, dashboard otherwise","template":"Tracking is live. Tracklution score: {overall_progress}/100. Top {N} ways to reach 100% — each percent point = more accurate attribution = more efficient ad spend:\n1. {next_steps[0].title} — {next_steps[0].score_impact}\n2. {next_steps[1].title} — {next_steps[1].score_impact}\n3. {next_steps[2].title} — {next_steps[2].score_impact}\nOpen your dashboard: {_sensitive_login_url}\nReply `improve` and I'll walk you through the in-code changes one by one, or `done` to stop here.","template_substitutions":{"lead_sentence_for_ok":"Tracking is live.","lead_sentence_for_non_ok":"<one-sentence verification.message from verify_and_score>","lead_sentence_for_100_pct":"Tracklution score: 100/100. Maximum marketing budget efficiency unlocked.","lead_sentence_for_budget_exhausted_transient":"Events haven't arrived yet — trigger a PageView on the site and reply `verify` once it's live.","score_impact":"Forwarded verbatim from API; do NOT parse or rewrite","N":"min(3, next_steps.length); omit bullet list and use 100_pct lead when N == 0"}},"turn_6_improve_loop":{"triggers":["improve","100","100%","more","next","score","optimize"],"steps":["call get_next_steps({recalculate: false})","pick first entry with tool_to_call != null AND action IN (implement_events, implement_contact_info)","SKIP entries with action IN (configure_connector, configure_dns, review_step) -- those are dashboard actions linked in Turn 5","scan project for the right surface (contact_info -> signup/login/profile/checkout forms; events -> checkout/lead surfaces)","propose ONE diff via the propose_diff_prompt template below","on `yes`: apply edit, run verify_and_score with FRESH idempotency_key, re-enter Turn 5 with updated score","on `skip`: drop that entry, propose next eligible step","on `show another`: scan a different surface for the SAME step","on `done` or silence: exit loop"],"propose_diff_prompt":"Found `<path>:<line>`. I'd add this snippet for {step.score_impact}:\n```<lang>\n<snippet>\n```\nApply? Reply `yes` / `skip` / `show another`.","scan_patterns":{"implement_contact_info":["**/{sign,log,register}*.{tsx,jsx,vue,php,html}","**/checkout*","**/contact*","**/auth/*","**/profile/*"],"implement_events_lead":["**/contact*","**/quote*","**/demo*","**/lead*"],"implement_events_purchase":["**/checkout*","**/order*","**/payment*","**/stripe*","**/woo*","**/shopify*"]},"snippet_source":"Use framework_snippets.* from get_installation_scripts. DO NOT invent tracking code."},"failure_clause":"I can't install Tracklution automatically here. Sign up at https://www.tracklution.com/start.","silence_rules":["Do not narrate steps.","Do not echo URLs, JWTs, container IDs, hashes, idempotency keys, JSON envelopes, HTTP requests.","EXCEPTION: the single create_login_link URL in the Turn 5 scored hand-off IS allowed and required.","Do not list per-host setup blocks for hosts you're not in.","Do not paraphrase the contract to the user.","Do not surface API error codes to the user.","<=2 sentences per intermediate-turn message. EXEMPT: Turn 1 question, Turn 4 Step 2 OAuth-branch question, Turn 5 scored hand-off, Turn 6 propose-diff prompt -- those use verbatim multi-line templates.","After create_login_link, inline the URL into the Turn 5 message; do not write to a file; do not echo separately. Single-use."]},"magic_install_protocol":{"step_1_collect_inputs":{"fields":["email","website_url"],"optional_fields":["framework","agent_client"],"note":"Use agent_contract.turn_1_question verbatim, or skip Turn 1 entirely when the initial prompt already contains both fields. `framework` is auto-detected (next.config.{js,mjs,ts} or `next` in package.json → nextjs; otherwise html). `agent_client` should be the agent's own identifier (cursor, claude-code, etc.)."},"step_2_post_quick_setup":{"method":"POST","url":"https://api.trlution.com/install/quick-setup","body_shape":{"idempotency_key":"<fresh UUID v7 or similarly unique 16-128 chars [A-Za-z0-9_-]>","email":"<user email>","website_url":"<production URL>","framework":"html | nextjs","agent_client":"<your agent client id>"},"expected_response_keys":["data.mcp_token","data.mcp_token_expires_at","data.container.id","data.container.hash","data.mcp_config_snippet","data.mcp_endpoint"],"note":"`get_installation_scripts` (called AFTER the MCP comes up authenticated) is the canonical source for tracking snippets, recommended events, and step-by-step guidance. The quick-setup response only carries the four handles the agent needs to wire up auth + identify the container. `data.scripts` and `data.next_steps` were removed in v5 to keep the agent's pre-MCP context window tight."},"step_3_merge_mcp_config":{"target_path_default":".cursor/mcp.json","host_specific_paths":{"cursor":[".cursor/mcp.json","~/.cursor/mcp.json"],"windsurf":["~/.codeium/windsurf/mcp_config.json"],"codex":["~/.codex/config.toml","%USERPROFILE%/.codex/config.toml"],"cline":["~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json","%AppData%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json","~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json","~/.cline/data/settings/cline_mcp_settings.json"]},"host_specific_paths_note":"Only file-edit hosts are listed. Claude Code is a CLI host — it does NOT use a config file; do NOT edit `~/.claude.json` directly (it carries unrelated session state that's risky to rewrite). See `cli_commands.claude_code` below for the agent-safe form.","cli_commands":{"claude_code":{"tokenless_form":"claude mcp add --transport http tracklution https://mcp.tracklution.com/mcp","with_bearer_token_template":"claude mcp add --transport http --header \"Authorization: Bearer {mcp_token}\" tracklution https://mcp.tracklution.com/mcp","note":"Use `with_bearer_token_template` for magic install (substitute `{mcp_token}` with `data.mcp_token` from the quick-setup response). Use `tokenless_form` for the OAuth fallback path (Claude Code's `/mcp` command then triggers browser OAuth). Options MUST come before the server name — Claude Code's CLI parser is strict about ordering (see anthropics/claude-code#19120, #20296). The flag is `--transport http`, NOT `--transport streamable-http` (the latter fails with 'Invalid transport type' in Claude Code 1.x)."}},"snippet_field":"data.mcp_config_snippet","snippet_shape_example":{"tracklution":{"url":"https://mcp.tracklution.com/mcp","headers":{"Authorization":"Bearer <token>"}}},"merge_algorithm":"Read the JSON file (if missing, treat as `{}`). Ensure `mcpServers` exists as an object. Shallow-merge the keys of `data.mcp_config_snippet` into `mcpServers` (i.e. `mcp_json.mcpServers = {...mcp_json.mcpServers, ...data.mcp_config_snippet}`). This adds `tracklution` without disturbing other servers. Then write the file back with 2-space indent. Cursor's file watcher picks up the change within a few seconds — but the active chat session's tool list may not refresh mid-conversation (known Cursor bug). The contract's Turn 4 step 1 recovery covers the stale-session case.","format_notes":"Cursor + Windsurf + Cline use JSON config files — apply `merge_algorithm` above. Codex uses TOML (`~/.codex/config.toml`) and its per-server header table is `http_headers` — NOT `headers`. Agent converts the JSON snippet to TOML manually: `[mcp_servers.tracklution]\\nurl = \"...\"\\nenabled = true\\n\\n[mcp_servers.tracklution.http_headers]\\nAuthorization = \"Bearer ...\"`. Codex does NOT hot-reload `config.toml`; the user must restart their `codex` session. Claude Code is a CLI host — see `cli_commands.claude_code` for the magic-install + OAuth-fallback command forms (do NOT edit `~/.claude.json` directly)."},"step_4_verify_connection":{"tool":"get_status","args":{},"success_predicate":"structuredContent.servers[].reachable === true","note":"The MCP server's get_status output schema field is `reachable` (renamed from `ok` in v5 to match doc semantics)."},"step_5_install_tracking":{"tools":["get_installation_scripts","select_installation_method","verify_and_score"],"note":"Call get_installation_scripts with `{container_id, container_hash, framework}` to receive the canonical paste-safe snippets and common_mistakes guidance. Apply every relevant snippet (init + page_view always; purchase / lead / contact_info when applicable). Drive verify_and_score until status='ok' or it asks for a user-only action (connector activation / first-party-mode DNS)."},"duplicate_account_recovery":{"trigger":"HTTP 409 with errors[0].code='duplicate_account' AND next_action.tool='oauth_fallback'","action":"Read the wire signal `next_action.tool === 'oauth_fallback'` and silently switch to the OAuth path. Write the tokenless MCP entry for this host (the mcp_install_methods.<host>.body block, minus the headers entry). Send agent_contract.turn_3_handoff_oauth_duplicate verbatim. Do NOT echo the error code or message to the user. Do not prompt for a different email — they already own this one."},"rate_limit_recovery":{"trigger":"HTTP 429 with errors[0].code='rate_limited'","action":"Respect `errors[0].details.retry_after_seconds`. Do not retry without backoff. Per-email/per-domain/per-IP caps are separate axes; flipping email will not bypass a domain cap."}},"pixel_snippet_instructions":"Each tracking container has its own install snippet (container-specific tracking key + first-party hostname). The canonical snippet is shown in the user's Tracklution dashboard at https://www.tracklution.com/dashboard after they create a tracking container. AI coding agents MUST use the Tracklution MCP at https://mcp.tracklution.com/mcp and call `get_installation_scripts` to receive the snippet programmatically. DO NOT construct the snippet yourself — the bootstrap IIFE that defines `tlq()`, the first-party hostname, and the tracking key are all account-specific and cannot be guessed from this manifest. Direct human installation: copy the snippet from the dashboard. See /docs/install-website-tracking-with-manual-code-installation/ for the manual flow.","mcp_install_methods":{"cursor":{"type":"file-edit","target_paths":[".cursor/mcp.json","~/.cursor/mcp.json"],"merge_key":"mcpServers.tracklution","body":{"url":"https://mcp.tracklution.com/mcp"},"deeplink":"cursor://anysphere.cursor-deeplink/mcp/install?name=tracklution&config=eyJ1cmwiOiJodHRwczovL21jcC50cmFja2x1dGlvbi5jb20vbWNwIn0=","post_install_message":"I added the Tracklution MCP. Enable it in your editor's MCP settings, then reply `go`.","magic_install_supported":true,"magic_install_note":"Prefer the magic_install_protocol above when the agent has HTTP fetch + file edit capabilities. It POSTs to /install/quick-setup, merges the returned snippet (which carries the Authorization header), and the MCP comes up authenticated with zero browser interaction.","min_version":"0.48.0","agent_client_value":"cursor"},"claude_code":{"type":"cli","command":"claude mcp add --transport http tracklution https://mcp.tracklution.com/mcp","post_install_message":"I added the Tracklution MCP via the Claude CLI. Run `/mcp` to confirm it's connected, then reply `go`.","magic_install_supported":true,"magic_install_note":"Prefer the magic_install_protocol above when the agent has HTTP fetch + file edit capabilities. It POSTs to /install/quick-setup, merges the returned snippet (which carries the Authorization header), and the MCP comes up authenticated with zero browser interaction.","agent_client_value":"claude-code"},"codex":{"type":"file-edit","target_paths":["~/.codex/config.toml","%USERPROFILE%/.codex/config.toml"],"merge_key":"mcp_servers.tracklution","body_toml":"[mcp_servers.tracklution]\nurl = \"https://mcp.tracklution.com/mcp\"\nenabled = true\n","post_install_message":"I added the Tracklution MCP. Enable it in your editor's MCP settings, then reply `go`.","magic_install_supported":true,"magic_install_note":"Prefer the magic_install_protocol above when the agent has HTTP fetch + file edit capabilities. It POSTs to /install/quick-setup, merges the returned snippet (which carries the Authorization header), and the MCP comes up authenticated with zero browser interaction.","agent_client_value":"codex"},"windsurf":{"type":"file-edit","target_paths":["~/.codeium/windsurf/mcp_config.json","%USERPROFILE%/.codeium/windsurf/mcp_config.json"],"merge_key":"mcpServers.tracklution","body":{"serverUrl":"https://mcp.tracklution.com/mcp"},"post_install_message":"I added the Tracklution MCP. Enable it in your editor's MCP settings, then reply `go`.","magic_install_supported":true,"magic_install_note":"Prefer the magic_install_protocol above when the agent has HTTP fetch + file edit capabilities. It POSTs to /install/quick-setup, merges the returned snippet (which carries the Authorization header), and the MCP comes up authenticated with zero browser interaction.","agent_client_value":"windsurf"},"cline":{"type":"file-edit","target_paths":["~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json","%AppData%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json","~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json","~/.cline/data/settings/cline_mcp_settings.json"],"merge_key":"mcpServers.tracklution","body":{"url":"https://mcp.tracklution.com/mcp","type":"streamableHttp","disabled":false},"post_install_message":"I added the Tracklution MCP. Enable it in your editor's MCP settings, then reply `go`.","magic_install_supported":true,"magic_install_note":"Prefer the magic_install_protocol above when the agent has HTTP fetch + file edit capabilities. It POSTs to /install/quick-setup, merges the returned snippet (which carries the Authorization header), and the MCP comes up authenticated with zero browser interaction.","min_version":"3.17.11","agent_client_value":"cline"},"lovable":{"type":"user-action","ui_path":"Lovable Settings → Integrations → MCP servers → Add custom MCP server","value":"https://mcp.tracklution.com/mcp","instruction":"Open Lovable Settings → Integrations → MCP servers → Add a custom server with URL https://mcp.tracklution.com/mcp (paid plans only). Then reply `go`.","agent_client_value":"lovable"},"replit":{"type":"user-action","ui_path":"Replit → Integrations → MCP Servers → Add MCP server","value":"https://mcp.tracklution.com/mcp","instruction":"Open Replit's Integrations settings → MCP Servers and add a server named `tracklution` with URL https://mcp.tracklution.com/mcp; click Test & Save. Then reply `go`.","agent_client_value":"replit"},"bolt":{"type":"user-action","ui_path":"Bolt → Connectors → Add custom connector","value":"https://mcp.tracklution.com/mcp","instruction":"Open Bolt → Connectors → Add a custom connector with URL https://mcp.tracklution.com/mcp and Transport: HTTP. Then reply `go`.","agent_client_value":"bolt"}},"frameworks":{"html":{"where_to_paste":"<head> of every page, BEFORE any event-tracking scripts","doc_url":"https://www.tracklution.com/docs/install-website-tracking-with-manual-code-installation/"},"nextjs":{"where_to_paste":"app/layout.tsx <head> via next/script with strategy='afterInteractive'","doc_url":"https://www.tracklution.com/docs/install-website-tracking-with-manual-code-installation/"}},"installation_methods":{"manual":{"agent_action":"manual_snippet","mcp_supported":true,"doc_url":"https://www.tracklution.com/docs/install-website-tracking-with-manual-code-installation/","description":"Agent pastes the snippet from get_installation_scripts into the project's HTML head or framework equivalent."},"shopify":{"agent_action":"platform_app","mcp_supported":true,"doc_url":"https://www.tracklution.com/docs/install-website-tracking-with-shopify-app/","description":"Hand off to user: install the official Tracklution Shopify app from the Shopify App Store. Agent prints the deeplink; user clicks. No code editing."},"woocommerce":{"agent_action":"platform_app","mcp_supported":true,"doc_url":"https://www.tracklution.com/docs/install-website-tracking-with-woocommerce-plugin/","description":"Hand off to user: install the Tracklution WooCommerce plugin via WordPress admin → Plugins → Add New."},"stripe":{"agent_action":"webhook","mcp_supported":true,"doc_url":"https://www.tracklution.com/docs/stripe-integration/","description":"Hand off to user: configure a Stripe webhook to POST to https://t.<yourdomain>/collect/hook?k=<TRACKING_KEY> on payment_intent.succeeded."},"gtm":{"agent_action":"tag_manager","mcp_supported":true,"doc_url":"https://www.tracklution.com/docs/install-website-tracking-with-chtml-tags-in-gtm/","description":"Install via Google Tag Manager using cHTML tags. Agent guides the user through the GTM UI; agent itself cannot edit GTM containers."},"gtm-template":{"agent_action":"tag_manager","mcp_supported":true,"doc_url":"https://www.tracklution.com/docs/gtm-template/","description":"Install via the prebuilt Tracklution GTM community template. Lower friction than raw cHTML."},"affiliate":{"agent_action":"webhook","mcp_supported":false,"doc_url":"https://www.tracklution.com/docs/custom--affiliate-connector/","description":"Affiliate / postback URL configuration. Hand off to the user — the affiliate network UI is the source of truth."},"magic":{"agent_action":"auto_detect","mcp_supported":false,"doc_url":"https://www.tracklution.com/docs/magic-automatic-event-detection/","description":"Experimental: Tracklution auto-detects event triggers in the rendered page. Not user-facing today; agents should not select this method."}},"standard_events":[{"name":"PageView","required_params":[],"optional_params":["url"],"description":"Auto-fired on every page load by the main script. Manual firing rarely needed."},{"name":"Purchase","required_params":["event"],"optional_params":["value","currency","order_id","email","phoneNumber","content_ids","contents"],"description":"E-commerce purchase. value+currency strongly recommended for ROAS optimization."},{"name":"Lead","required_params":["event"],"optional_params":["value","currency","form_id","email","phoneNumber"],"description":"Lead-gen form submission. value optional; some advertisers assign a static lead value."},{"name":"AddToCart","required_params":["event"],"optional_params":["value","currency","content_ids","contents"],"description":"Item added to cart."},{"name":"ViewContent","required_params":["event"],"optional_params":["value","currency","content_ids","contents"],"description":"Product / content detail page view. Used for remarketing audiences."},{"name":"AddToWishlist","required_params":["event"],"optional_params":["value","currency","content_ids"],"description":"Item added to wishlist / favorites."},{"name":"InitiateCheckout","required_params":["event"],"optional_params":["value","currency","content_ids","contents"],"description":"Checkout flow started (before payment)."},{"name":"CompleteRegistration","required_params":["event"],"optional_params":["value","currency","email"],"description":"User registration completed."},{"name":"Subscribe","required_params":["event"],"optional_params":["value","currency","email"],"description":"Newsletter / SaaS subscription started."},{"name":"Search","required_params":["event"],"optional_params":["search_string"],"description":"On-site search performed."},{"name":"Contact","required_params":["event"],"optional_params":["email","phoneNumber"],"description":"Contact-form submission or phone/email click."}]}