# Make Rover Production discoverable + transactable by AI agents (Rover frontdoor) AI agents and chatbots discover → read → act on your site by fetching a small set of files on your own domain, then transacting through Rover's Agent-to-Web (A2W) endpoint. Add the surfaces below at the exact paths shown. You can host them by hand, or hand this whole file to Claude Code / Cursor / Codex and ask it to add them to your codebase. - **Base URL:** https://rtrvr.ai - **A2W endpoint:** https://agent.rtrvr.ai/v2/a2w/runs - **Presentation:** Rover for visitors - **First-party A2W:** Rover cloud execution is available to URL-fetch agents and chatbots; browser-capable agents may use an explicit receipt or handoff. - **Third-party cloud tools:** Off. First-party cloud A2W does not grant Rover access to other sites. ## 1. Embed the Rover script Add this just before the closing `` tag on every page: ```html ``` ## 2. Discovery link tags Add these inside `` so agents can find the surfaces below: ```html ``` ## 3. `/.well-known/agent-card.json` Agent card — identifies the site + its A2W run endpoint to agents. Serve at `https://rtrvr.ai/.well-known/agent-card.json` with `Content-Type: application/json`: ```json { "name": "Rover Production", "description": "Structured Rover entrypoints for Rover Production. Prefer the published shortcuts and explicit tools over raw DOM automation whenever they match the user's goal.", "url": "https://agent.rtrvr.ai/v2/a2w/runs", "version": "1.0.0", "defaultInputModes": [ "text/plain", "application/json" ], "defaultOutputModes": [ "text/plain", "application/json" ], "provider": { "organization": "Rover Production", "url": "https://rtrvr.ai/" }, "securitySchemes": { "webBotAuth": { "type": "http", "scheme": "signature", "description": "RFC 9421 HTTP Message Signatures (Web Bot Auth). Sign requests with Signature + Signature-Input and present Signature-Agent; publish your key set at /.well-known/http-message-signatures-directory. A verified signature earns a higher trust tier, which unlocks more capabilities." }, "roverDelegation": { "type": "http", "scheme": "bearer", "bearerFormat": "rds", "description": "Rover human-delegation token (rds_…): a key-bound, scoped, spend-capped authorization a verified human grants for actions on their behalf via the Rover identity plane. Never a raw site credential." } }, "security": [ { "webBotAuth": [] }, { "roverDelegation": [] } ], "capabilities": { "streaming": true, "a2wRuns": true, "stateTransitions": true, "delegatedHandoffs": false, "webmcp": false }, "skills": [ { "id": "setup_rover", "name": "Set up Rover", "description": "Set up Rover. Rover is live on my domain, the first visitor journey works, and I know the best next customization. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation.", "tags": [ "shortcut", "rover" ], "examples": [ "Help me set up Rover on my website and verify my first useful visitor journey." ], "inputSchema": { "type": "object", "additionalProperties": false, "description": "This shortcut is parameterless. Invoke it directly by id." }, "outputSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "A2W run status returned by Rover." }, "summary": { "type": "string", "description": "High-level summary of what Rover completed or observed." }, "run": { "type": "string", "description": "Canonical A2W run URL." }, "workflow": { "type": "string", "description": "Canonical A2W workflow URL when delegation occurs." } } }, "sideEffect": "transactional", "requiresConfirmation": true, "preferredInterface": "shortcut", "category": "primary", "rover": { "shortcutId": "setup_rover", "playbookId": "setup_rover", "engagementKind": "onboarding", "prompt": "Help me set up Rover on my website and verify my first useful visitor journey.", "routing": "act", "run": { "endpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "payload": { "url": "https://rtrvr.ai/", "shortcutId": "setup_rover", "engagementKind": "onboarding" } }, "source": "shortcut" } }, { "id": "analytics_only_onboarding", "name": "Set up Rover Analytics", "description": "Set up Rover Analytics. Add a production site and open its Analytics only install snippet. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation.", "tags": [ "shortcut", "rover" ], "examples": [ "Set up Rover Analytics only in this workspace. Follow this exact flow: 1. If the visitor is signed out or a sign-in page is visible, call ask_user once with exactly one required question: key \"signin_complete\", query \"Si" ], "inputSchema": { "type": "object", "additionalProperties": false, "description": "This shortcut is parameterless. Invoke it directly by id." }, "outputSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "A2W run status returned by Rover." }, "summary": { "type": "string", "description": "High-level summary of what Rover completed or observed." }, "run": { "type": "string", "description": "Canonical A2W run URL." }, "workflow": { "type": "string", "description": "Canonical A2W workflow URL when delegation occurs." } } }, "sideEffect": "transactional", "requiresConfirmation": true, "preferredInterface": "shortcut", "category": "primary", "rover": { "shortcutId": "analytics_only_onboarding", "engagementKind": "onboarding", "prompt": "Set up Rover Analytics only in this workspace. Follow this exact flow: 1. If the visitor is signed out or a sign-in page is visible, call ask_user once with exactly one required question: key \"signin_complete\", query \"Sign in, then choose Continue.\", choices [\"Continue\"]. Do not continue until they choose Continue. After Continue, inspect the signed-in workspace again. 2. Reuse a matching existing site without asking for confirmation. If the production URL and display name are still missing, call ask_user once with exactly two required questions: key \"production_url\", query \"What is the exact production app URL?\", and key \"display_name\", query \"What should this site be called in Rover?\". Use both answers directly. Never ask the visitor to confirm, double-check, or approve either value. 3. In Workspace, reuse an existing site whose configured production domain matches the supplied URL. Otherwise choose Add a site and create it immediately with the supplied display name and production URL. Normal domain and subdomain handling is expected. 4. Select Analytics only, save, and open the installation screen. 5. Stop as soon as the exact generated installation script tag is visible. Do not ask whether it was deployed. Do not wait for deployment. Do not verify the live install. Do not switch to Rover for visitors. Your final response must be only the exact generated tag copied from the installation screen, with no heading, explanation, confirmation request, markdown fence, or text after the closing .", "routing": "act", "run": { "endpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "payload": { "url": "https://rtrvr.ai/", "shortcutId": "analytics_only_onboarding", "engagementKind": "onboarding" } }, "source": "shortcut" } }, { "id": "find_plan", "name": "Find the right plan", "description": "Find the right plan. Compare the relevant plans and recommend the best fit. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation.", "tags": [ "shortcut", "rover" ], "examples": [ "Help me choose the right rtrvr and Rover plan for the work I want to accomplish." ], "inputSchema": { "type": "object", "additionalProperties": false, "description": "This shortcut is parameterless. Invoke it directly by id." }, "outputSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "A2W run status returned by Rover." }, "summary": { "type": "string", "description": "High-level summary of what Rover completed or observed." }, "run": { "type": "string", "description": "Canonical A2W run URL." }, "workflow": { "type": "string", "description": "Canonical A2W workflow URL when delegation occurs." } } }, "sideEffect": "transactional", "requiresConfirmation": true, "preferredInterface": "shortcut", "category": "primary", "rover": { "shortcutId": "find_plan", "playbookId": "find_plan", "engagementKind": "demo", "prompt": "Help me choose the right rtrvr and Rover plan for the work I want to accomplish.", "routing": "act", "run": { "endpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "payload": { "url": "https://rtrvr.ai/", "shortcutId": "find_plan", "engagementKind": "demo" } }, "source": "shortcut" } }, { "id": "fix_rover_install", "name": "Fix my Rover install", "description": "Fix my Rover install. Diagnose, resolve, and verify a Rover installation problem. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation.", "tags": [ "shortcut", "rover" ], "examples": [ "Diagnose why Rover is not appearing or running on my site, resolve what can be fixed safely, and verify the result." ], "inputSchema": { "type": "object", "additionalProperties": false, "description": "This shortcut is parameterless. Invoke it directly by id." }, "outputSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "A2W run status returned by Rover." }, "summary": { "type": "string", "description": "High-level summary of what Rover completed or observed." }, "run": { "type": "string", "description": "Canonical A2W run URL." }, "workflow": { "type": "string", "description": "Canonical A2W workflow URL when delegation occurs." } } }, "sideEffect": "transactional", "requiresConfirmation": true, "preferredInterface": "shortcut", "category": "primary", "rover": { "shortcutId": "fix_rover_install", "playbookId": "fix_rover_install", "engagementKind": "support", "prompt": "Diagnose why Rover is not appearing or running on my site, resolve what can be fixed safely, and verify the result.", "routing": "planner", "run": { "endpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "payload": { "url": "https://rtrvr.ai/", "shortcutId": "fix_rover_install", "engagementKind": "support" } }, "source": "shortcut" } } ], "interfaces": [ { "type": "run", "url": "https://agent.rtrvr.ai/v2/a2w/runs", "description": "Canonical Agent-to-Web Protocol (A2W) run creation endpoint.", "available": true }, { "type": "run_get", "url": "https://agent.rtrvr.ai/v2/a2w/runs", "description": "A2W v2 GET run creation for URL-fetch chatbots. Supply url and exactly one canonical selector; cloud, 25 seconds, and Markdown are the defaults.", "available": true }, { "type": "workflow", "url": "https://agent.rtrvr.ai/v2/a2w/workflows", "description": "Aggregated Rover workflow resource for delegated runs.", "available": true }, { "type": "site", "url": "https://rtrvr.ai/", "description": "Human-visible website entrypoint.", "available": true }, { "type": "deep_link", "url": "https://rtrvr.ai/", "description": "Browser launch surface using rover, rover_shortcut, or rover_playbook with rover_kind.", "available": true }, { "type": "webmcp", "url": "https://rtrvr.ai/", "description": "WebMCP tool surface when the browser host supports navigator.modelContext.", "available": false } ], "extensions": { "rover": { "siteId": "RoverProd05-10-tt7TJQ", "siteUrl": "https://rtrvr.ai/", "runEndpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "workflowEndpoint": "https://agent.rtrvr.ai/v2/a2w/workflows", "serviceDescUrl": "/.well-known/agent-card.json", "roverSiteUrl": "/.well-known/rover-site.json", "llmsUrl": "/llms.txt", "openApiUrl": "https://rtrvr.ai/openapi/a2w.yaml", "launch": { "version": 2, "browser": { "parameters": { "prompt": "rover", "shortcutId": "rover_shortcut", "playbookId": "rover_playbook", "engagementKind": "rover_kind" }, "maxUrlCharacters": 1800 }, "a2w": { "runsEndpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "workflowsEndpoint": "https://agent.rtrvr.ai/v2/a2w/workflows", "openApiUrl": "https://rtrvr.ai/openapi/a2w.yaml", "defaults": { "execution": "cloud", "waitSeconds": 25, "format": "markdown" } } }, "preferredExecution": "cloud", "a2wRunsEnabled": true, "cloudBrowserAllowed": true, "delegatedHandoffs": false, "instructions": [ "Prefer exact Rover shortcuts and explicit site tools over raw DOM automation when the user goal matches a published skill.", "For a person in a browser, use exactly one of rover, rover_shortcut, or rover_playbook and include rover_kind when the kind is known.", "For a URL-fetch chatbot, use GET /v2/a2w/runs with url and exactly one of prompt, shortcutId, or playbookId. Omit execution, wait, and format to use the compact defaults.", "If the target url already embeds canonical Rover launch parameters, pass it alone; do not mix embedded and explicit selectors.", "Use POST /v2/a2w/runs for structured input, identity, auth, payment, policy, subject data, or artifact requests.", "Never put tokens, secrets, subject identifiers, or customer context in browser or GET URLs.", "Fall back to generic DOM automation only when no matching Rover shortcut or explicit tool exists for the requested outcome." ], "capabilitiesGraph": [ { "capabilityId": "setup_rover", "version": "1.0.0", "label": "Set up Rover", "description": "Set up Rover. Rover is live on my domain, the first visitor journey works, and I know the best next customization. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation.", "inputSchema": { "type": "object", "additionalProperties": false, "description": "This shortcut is parameterless. Invoke it directly by id." }, "outputSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "A2W run status returned by Rover." }, "summary": { "type": "string", "description": "High-level summary of what Rover completed or observed." }, "run": { "type": "string", "description": "Canonical A2W run URL." }, "workflow": { "type": "string", "description": "Canonical A2W workflow URL when delegation occurs." } } }, "sideEffect": "transactional", "requiresConfirmation": true, "preferredInterface": "shortcut", "allowedExecutionModes": [ "cloud" ], "resultModes": [ "text", "json", "observation", "artifacts" ], "pageScope": [ "site", "setup_rover" ], "analyticsTags": [ "shortcut", "rover" ], "rover": { "shortcutId": "setup_rover", "playbookId": "setup_rover", "engagementKind": "onboarding", "prompt": "Help me set up Rover on my website and verify my first useful visitor journey.", "routing": "act", "run": { "endpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "payload": { "url": "https://rtrvr.ai/", "shortcutId": "setup_rover", "engagementKind": "onboarding" } }, "source": "shortcut" } }, { "capabilityId": "analytics_only_onboarding", "version": "1.0.0", "label": "Set up Rover Analytics", "description": "Set up Rover Analytics. Add a production site and open its Analytics only install snippet. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation.", "inputSchema": { "type": "object", "additionalProperties": false, "description": "This shortcut is parameterless. Invoke it directly by id." }, "outputSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "A2W run status returned by Rover." }, "summary": { "type": "string", "description": "High-level summary of what Rover completed or observed." }, "run": { "type": "string", "description": "Canonical A2W run URL." }, "workflow": { "type": "string", "description": "Canonical A2W workflow URL when delegation occurs." } } }, "sideEffect": "transactional", "requiresConfirmation": true, "preferredInterface": "shortcut", "allowedExecutionModes": [ "cloud" ], "resultModes": [ "text", "json", "observation", "artifacts" ], "pageScope": [ "site", "analytics_only_onboarding" ], "analyticsTags": [ "shortcut", "rover" ], "rover": { "shortcutId": "analytics_only_onboarding", "engagementKind": "onboarding", "prompt": "Set up Rover Analytics only in this workspace. Follow this exact flow: 1. If the visitor is signed out or a sign-in page is visible, call ask_user once with exactly one required question: key \"signin_complete\", query \"Sign in, then choose Continue.\", choices [\"Continue\"]. Do not continue until they choose Continue. After Continue, inspect the signed-in workspace again. 2. Reuse a matching existing site without asking for confirmation. If the production URL and display name are still missing, call ask_user once with exactly two required questions: key \"production_url\", query \"What is the exact production app URL?\", and key \"display_name\", query \"What should this site be called in Rover?\". Use both answers directly. Never ask the visitor to confirm, double-check, or approve either value. 3. In Workspace, reuse an existing site whose configured production domain matches the supplied URL. Otherwise choose Add a site and create it immediately with the supplied display name and production URL. Normal domain and subdomain handling is expected. 4. Select Analytics only, save, and open the installation screen. 5. Stop as soon as the exact generated installation script tag is visible. Do not ask whether it was deployed. Do not wait for deployment. Do not verify the live install. Do not switch to Rover for visitors. Your final response must be only the exact generated tag copied from the installation screen, with no heading, explanation, confirmation request, markdown fence, or text after the closing .", "routing": "act", "run": { "endpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "payload": { "url": "https://rtrvr.ai/", "shortcutId": "analytics_only_onboarding", "engagementKind": "onboarding" } }, "source": "shortcut" } }, { "capabilityId": "find_plan", "version": "1.0.0", "label": "Find the right plan", "description": "Find the right plan. Compare the relevant plans and recommend the best fit. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation.", "inputSchema": { "type": "object", "additionalProperties": false, "description": "This shortcut is parameterless. Invoke it directly by id." }, "outputSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "A2W run status returned by Rover." }, "summary": { "type": "string", "description": "High-level summary of what Rover completed or observed." }, "run": { "type": "string", "description": "Canonical A2W run URL." }, "workflow": { "type": "string", "description": "Canonical A2W workflow URL when delegation occurs." } } }, "sideEffect": "transactional", "requiresConfirmation": true, "preferredInterface": "shortcut", "allowedExecutionModes": [ "cloud" ], "resultModes": [ "text", "json", "observation", "artifacts" ], "pageScope": [ "site", "find_plan" ], "analyticsTags": [ "shortcut", "rover" ], "rover": { "shortcutId": "find_plan", "playbookId": "find_plan", "engagementKind": "demo", "prompt": "Help me choose the right rtrvr and Rover plan for the work I want to accomplish.", "routing": "act", "run": { "endpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "payload": { "url": "https://rtrvr.ai/", "shortcutId": "find_plan", "engagementKind": "demo" } }, "source": "shortcut" } }, { "capabilityId": "fix_rover_install", "version": "1.0.0", "label": "Fix my Rover install", "description": "Fix my Rover install. Diagnose, resolve, and verify a Rover installation problem. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation.", "inputSchema": { "type": "object", "additionalProperties": false, "description": "This shortcut is parameterless. Invoke it directly by id." }, "outputSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "A2W run status returned by Rover." }, "summary": { "type": "string", "description": "High-level summary of what Rover completed or observed." }, "run": { "type": "string", "description": "Canonical A2W run URL." }, "workflow": { "type": "string", "description": "Canonical A2W workflow URL when delegation occurs." } } }, "sideEffect": "transactional", "requiresConfirmation": true, "preferredInterface": "shortcut", "allowedExecutionModes": [ "cloud" ], "resultModes": [ "text", "json", "observation", "artifacts" ], "pageScope": [ "site", "fix_rover_install" ], "analyticsTags": [ "shortcut", "rover" ], "rover": { "shortcutId": "fix_rover_install", "playbookId": "fix_rover_install", "engagementKind": "support", "prompt": "Diagnose why Rover is not appearing or running on my site, resolve what can be fixed safely, and verify the result.", "routing": "planner", "run": { "endpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "payload": { "url": "https://rtrvr.ai/", "shortcutId": "fix_rover_install", "engagementKind": "support" } }, "source": "shortcut" } } ], "pages": [ { "pageId": "home", "route": "/", "capabilityIds": [ "setup_rover", "analytics_only_onboarding", "find_plan", "fix_rover_install" ], "entityHints": [], "formHints": [], "discoveryMode": "beacon", "hostSurface": "auto", "actionReveal": "click", "agentModeEntryHints": [ "Use the page beacon or A2W run endpoint before attempting generic DOM automation.", "When Rover is already active, prefer the current-page actions over screenshot loops." ], "capabilitySummary": [ "Set up Rover", "Set up Rover Analytics", "Find the right plan", "Fix my Rover install" ] } ], "currentPage": { "pageId": "home", "route": "/", "capabilityIds": [ "setup_rover", "analytics_only_onboarding", "find_plan", "fix_rover_install" ], "entityHints": [], "formHints": [], "discoveryMode": "beacon", "hostSurface": "auto", "actionReveal": "click", "agentModeEntryHints": [ "Use the page beacon or A2W run endpoint before attempting generic DOM automation.", "When Rover is already active, prefer the current-page actions over screenshot loops." ], "capabilitySummary": [ "Set up Rover", "Set up Rover Analytics", "Find the right plan", "Fix my Rover install" ] }, "discoverySurface": { "mode": "beacon", "branding": "site", "hostSurface": "floating-corner", "actionReveal": "click", "agentModeEntryHints": [ "Use the page beacon or A2W run endpoint before attempting generic DOM automation.", "When Rover is already active, prefer the current-page actions over screenshot loops." ], "compactActionMaxActions": 3, "beaconLabel": "Ask Rover" }, "shortcuts": [ { "id": "setup_rover", "label": "Set up Rover", "prompt": "Help me set up Rover on my website and verify my first useful visitor journey.", "description": "Rover is live on my domain, the first visitor journey works, and I know the best next customization.", "routing": "act", "engagementKind": "onboarding", "playbookId": "setup_rover" }, { "id": "analytics_only_onboarding", "label": "Set up Rover Analytics", "prompt": "Set up Rover Analytics only in this workspace. Follow this exact flow: 1. If the visitor is signed out or a sign-in page is visible, call ask_user once with exactly one required question: key \"signin_complete\", query \"Sign in, then choose Continue.\", choices [\"Continue\"]. Do not continue until they choose Continue. After Continue, inspect the signed-in workspace again. 2. Reuse a matching existing site without asking for confirmation. If the production URL and display name are still missing, call ask_user once with exactly two required questions: key \"production_url\", query \"What is the exact production app URL?\", and key \"display_name\", query \"What should this site be called in Rover?\". Use both answers directly. Never ask the visitor to confirm, double-check, or approve either value. 3. In Workspace, reuse an existing site whose configured production domain matches the supplied URL. Otherwise choose Add a site and create it immediately with the supplied display name and production URL. Normal domain and subdomain handling is expected. 4. Select Analytics only, save, and open the installation screen. 5. Stop as soon as the exact generated installation script tag is visible. Do not ask whether it was deployed. Do not wait for deployment. Do not verify the live install. Do not switch to Rover for visitors. Your final response must be only the exact generated tag copied from the installation screen, with no heading, explanation, confirmation request, markdown fence, or text after the closing .", "description": "Add a production site and open its Analytics only install snippet.", "routing": "act", "engagementKind": "onboarding" }, { "id": "find_plan", "label": "Find the right plan", "prompt": "Help me choose the right rtrvr and Rover plan for the work I want to accomplish.", "description": "Compare the relevant plans and recommend the best fit", "routing": "act", "engagementKind": "demo", "playbookId": "find_plan" }, { "id": "fix_rover_install", "label": "Fix my Rover install", "prompt": "Diagnose why Rover is not appearing or running on my site, resolve what can be fixed safely, and verify the result.", "description": "Diagnose, resolve, and verify a Rover installation problem", "routing": "planner", "engagementKind": "support", "playbookId": "fix_rover_install" } ], "webmcp": { "available": false, "tools": [] }, "presence": { "assistantName": "Rover", "ctaText": "Ask Rover", "draggable": true }, "experience": { "audio": { "narration": { "enabled": true, "rate": 1, "language": "en-US" } }, "motion": { "actionSpotlight": true, "actionSpotlightColor": "#FF4C00" }, "momentCards": { "enabled": true, "autoRecedeMs": 6500, "assets": [ { "id": "rtrvr_generic_open", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_generic_open.webp", "alt": "Minimal rtrvr.ai card reading 'Watch it work.' in dark type with an orange period.", "role": "opening", "focal": "center" }, { "id": "rtrvr_generic_checkpoint", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_generic_checkpoint.webp", "alt": "Minimal rtrvr.ai card reading 'On it.' with a thin orange progress line.", "role": "checkpoint", "focal": "center" }, { "id": "rtrvr_generic_close", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_generic_close.webp", "alt": "Minimal rtrvr.ai card reading 'Task complete.' with a small orange check.", "role": "closing", "focal": "center" }, { "id": "rtrvr_first_win_open", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_first_win_open.webp", "alt": "Minimal rtrvr.ai card reading 'Your first task.' in dark type with an orange period.", "role": "opening", "playbookId": "first_win_extension", "focal": "center" }, { "id": "rtrvr_first_win_checkpoint", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_first_win_checkpoint.webp", "alt": "Minimal rtrvr.ai card reading 'Running in your tab.' with a thin orange progress line.", "role": "checkpoint", "playbookId": "first_win_extension", "focal": "center" }, { "id": "rtrvr_first_win_close", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_first_win_close.webp", "alt": "Minimal rtrvr.ai card reading 'First win, done.' with a small orange check.", "role": "closing", "playbookId": "first_win_extension", "focal": "center" }, { "id": "rtrvr_cloud_open", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_cloud_open.webp", "alt": "Minimal rtrvr.ai card reading 'No tab required.' in dark type with an orange period.", "role": "opening", "playbookId": "cloud_workflow_live", "focal": "center" }, { "id": "rtrvr_cloud_checkpoint", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_cloud_checkpoint.webp", "alt": "Minimal rtrvr.ai card reading 'Running hosted.' with a thin orange progress line.", "role": "checkpoint", "playbookId": "cloud_workflow_live", "focal": "center" }, { "id": "rtrvr_cloud_close", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_cloud_close.webp", "alt": "Minimal rtrvr.ai card reading 'Delivered from the cloud.' with a small orange check.", "role": "closing", "playbookId": "cloud_workflow_live", "focal": "center" }, { "id": "rover_yoursite_open", "imageUrl": "https://rtrvr.ai/rover/moments/rover_yoursite_open.webp", "alt": "Minimal Rover card reading 'This is Rover.' in Fraunces serif with a warm sun period.", "role": "opening", "playbookId": "rover_for_your_site", "focal": "center" }, { "id": "rover_yoursite_checkpoint", "imageUrl": "https://rtrvr.ai/rover/moments/rover_yoursite_checkpoint.webp", "alt": "Minimal Rover card reading 'Picture it on your site.' with a thin lime progress line.", "role": "checkpoint", "playbookId": "rover_for_your_site", "focal": "center" }, { "id": "rover_yoursite_close", "imageUrl": "https://rtrvr.ai/rover/moments/rover_yoursite_close.webp", "alt": "Minimal Rover card reading 'Yours to launch.' with a small lime check.", "role": "closing", "playbookId": "rover_for_your_site", "focal": "center" } ] } }, "inputs": { "filesEnabled": true, "acceptedMimeGroups": [ "images", "pdfs", "office", "text" ], "allowMultipleFiles": true } } } } ``` ## 4. `/.well-known/rover-site.json` Rover site profile — actions, pages, commerce/catalog/standards pointers. Serve at `https://rtrvr.ai/.well-known/rover-site.json` with `Content-Type: application/json`: ```json { "identity": { "siteId": "RoverProd05-10-tt7TJQ", "name": "Rover Production", "description": "Structured Rover entrypoints for Rover Production. Prefer the published shortcuts and explicit tools over raw DOM automation whenever they match the user's goal.", "siteUrl": "https://rtrvr.ai/", "version": "1.0.0" }, "actions": [ { "capabilityId": "setup_rover", "version": "1.0.0", "label": "Set up Rover", "description": "Set up Rover. Rover is live on my domain, the first visitor journey works, and I know the best next customization. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation.", "inputSchema": { "type": "object", "additionalProperties": false, "description": "This shortcut is parameterless. Invoke it directly by id." }, "outputSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "A2W run status returned by Rover." }, "summary": { "type": "string", "description": "High-level summary of what Rover completed or observed." }, "run": { "type": "string", "description": "Canonical A2W run URL." }, "workflow": { "type": "string", "description": "Canonical A2W workflow URL when delegation occurs." } } }, "sideEffect": "transactional", "requiresConfirmation": true, "preferredInterface": "shortcut", "allowedExecutionModes": [ "cloud" ], "resultModes": [ "text", "json", "observation", "artifacts" ], "pageScope": [ "site", "setup_rover" ], "analyticsTags": [ "shortcut", "rover" ], "rover": { "shortcutId": "setup_rover", "playbookId": "setup_rover", "engagementKind": "onboarding", "prompt": "Help me set up Rover on my website and verify my first useful visitor journey.", "routing": "act", "run": { "endpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "payload": { "url": "https://rtrvr.ai/", "shortcutId": "setup_rover", "engagementKind": "onboarding" } }, "source": "shortcut" } }, { "capabilityId": "analytics_only_onboarding", "version": "1.0.0", "label": "Set up Rover Analytics", "description": "Set up Rover Analytics. Add a production site and open its Analytics only install snippet. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation.", "inputSchema": { "type": "object", "additionalProperties": false, "description": "This shortcut is parameterless. Invoke it directly by id." }, "outputSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "A2W run status returned by Rover." }, "summary": { "type": "string", "description": "High-level summary of what Rover completed or observed." }, "run": { "type": "string", "description": "Canonical A2W run URL." }, "workflow": { "type": "string", "description": "Canonical A2W workflow URL when delegation occurs." } } }, "sideEffect": "transactional", "requiresConfirmation": true, "preferredInterface": "shortcut", "allowedExecutionModes": [ "cloud" ], "resultModes": [ "text", "json", "observation", "artifacts" ], "pageScope": [ "site", "analytics_only_onboarding" ], "analyticsTags": [ "shortcut", "rover" ], "rover": { "shortcutId": "analytics_only_onboarding", "engagementKind": "onboarding", "prompt": "Set up Rover Analytics only in this workspace. Follow this exact flow: 1. If the visitor is signed out or a sign-in page is visible, call ask_user once with exactly one required question: key \"signin_complete\", query \"Sign in, then choose Continue.\", choices [\"Continue\"]. Do not continue until they choose Continue. After Continue, inspect the signed-in workspace again. 2. Reuse a matching existing site without asking for confirmation. If the production URL and display name are still missing, call ask_user once with exactly two required questions: key \"production_url\", query \"What is the exact production app URL?\", and key \"display_name\", query \"What should this site be called in Rover?\". Use both answers directly. Never ask the visitor to confirm, double-check, or approve either value. 3. In Workspace, reuse an existing site whose configured production domain matches the supplied URL. Otherwise choose Add a site and create it immediately with the supplied display name and production URL. Normal domain and subdomain handling is expected. 4. Select Analytics only, save, and open the installation screen. 5. Stop as soon as the exact generated installation script tag is visible. Do not ask whether it was deployed. Do not wait for deployment. Do not verify the live install. Do not switch to Rover for visitors. Your final response must be only the exact generated tag copied from the installation screen, with no heading, explanation, confirmation request, markdown fence, or text after the closing .", "routing": "act", "run": { "endpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "payload": { "url": "https://rtrvr.ai/", "shortcutId": "analytics_only_onboarding", "engagementKind": "onboarding" } }, "source": "shortcut" } }, { "capabilityId": "find_plan", "version": "1.0.0", "label": "Find the right plan", "description": "Find the right plan. Compare the relevant plans and recommend the best fit. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation.", "inputSchema": { "type": "object", "additionalProperties": false, "description": "This shortcut is parameterless. Invoke it directly by id." }, "outputSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "A2W run status returned by Rover." }, "summary": { "type": "string", "description": "High-level summary of what Rover completed or observed." }, "run": { "type": "string", "description": "Canonical A2W run URL." }, "workflow": { "type": "string", "description": "Canonical A2W workflow URL when delegation occurs." } } }, "sideEffect": "transactional", "requiresConfirmation": true, "preferredInterface": "shortcut", "allowedExecutionModes": [ "cloud" ], "resultModes": [ "text", "json", "observation", "artifacts" ], "pageScope": [ "site", "find_plan" ], "analyticsTags": [ "shortcut", "rover" ], "rover": { "shortcutId": "find_plan", "playbookId": "find_plan", "engagementKind": "demo", "prompt": "Help me choose the right rtrvr and Rover plan for the work I want to accomplish.", "routing": "act", "run": { "endpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "payload": { "url": "https://rtrvr.ai/", "shortcutId": "find_plan", "engagementKind": "demo" } }, "source": "shortcut" } }, { "capabilityId": "fix_rover_install", "version": "1.0.0", "label": "Fix my Rover install", "description": "Fix my Rover install. Diagnose, resolve, and verify a Rover installation problem. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation.", "inputSchema": { "type": "object", "additionalProperties": false, "description": "This shortcut is parameterless. Invoke it directly by id." }, "outputSchema": { "type": "object", "properties": { "status": { "type": "string", "description": "A2W run status returned by Rover." }, "summary": { "type": "string", "description": "High-level summary of what Rover completed or observed." }, "run": { "type": "string", "description": "Canonical A2W run URL." }, "workflow": { "type": "string", "description": "Canonical A2W workflow URL when delegation occurs." } } }, "sideEffect": "transactional", "requiresConfirmation": true, "preferredInterface": "shortcut", "allowedExecutionModes": [ "cloud" ], "resultModes": [ "text", "json", "observation", "artifacts" ], "pageScope": [ "site", "fix_rover_install" ], "analyticsTags": [ "shortcut", "rover" ], "rover": { "shortcutId": "fix_rover_install", "playbookId": "fix_rover_install", "engagementKind": "support", "prompt": "Diagnose why Rover is not appearing or running on my site, resolve what can be fixed safely, and verify the result.", "routing": "planner", "run": { "endpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "payload": { "url": "https://rtrvr.ai/", "shortcutId": "fix_rover_install", "engagementKind": "support" } }, "source": "shortcut" } } ], "pages": [ { "pageId": "home", "route": "/", "capabilityIds": [ "setup_rover", "analytics_only_onboarding", "find_plan", "fix_rover_install" ], "entityHints": [], "formHints": [], "discoveryMode": "beacon", "hostSurface": "auto", "actionReveal": "click", "agentModeEntryHints": [ "Use the page beacon or A2W run endpoint before attempting generic DOM automation.", "When Rover is already active, prefer the current-page actions over screenshot loops." ], "capabilitySummary": [ "Set up Rover", "Set up Rover Analytics", "Find the right plan", "Fix my Rover install" ] } ], "policies": { "preferredExecution": "cloud", "a2wRunsEnabled": true, "cloudBrowserAllowed": true, "delegatedHandoffs": false }, "auth": { "runEndpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "workflowEndpoint": "https://agent.rtrvr.ai/v2/a2w/workflows", "launch": { "version": 2, "browser": { "parameters": { "prompt": "rover", "shortcutId": "rover_shortcut", "playbookId": "rover_playbook", "engagementKind": "rover_kind" }, "maxUrlCharacters": 1800 }, "a2w": { "runsEndpoint": "https://agent.rtrvr.ai/v2/a2w/runs", "workflowsEndpoint": "https://agent.rtrvr.ai/v2/a2w/workflows", "openApiUrl": "https://rtrvr.ai/openapi/a2w.yaml", "defaults": { "execution": "cloud", "waitSeconds": 25, "format": "markdown" } } }, "acceptsHttpMessageSignatures": true, "supportsUnsignedSelfReportedIdentity": true }, "analytics": { "layer": "roverbook", "runIdField": "runId", "workflowIdField": "workflowId", "capabilityIdField": "capabilityId", "pageIdField": "pageId" }, "currentPage": { "pageId": "home", "route": "/", "capabilityIds": [ "setup_rover", "analytics_only_onboarding", "find_plan", "fix_rover_install" ], "entityHints": [], "formHints": [], "discoveryMode": "beacon", "hostSurface": "auto", "actionReveal": "click", "agentModeEntryHints": [ "Use the page beacon or A2W run endpoint before attempting generic DOM automation.", "When Rover is already active, prefer the current-page actions over screenshot loops." ], "capabilitySummary": [ "Set up Rover", "Set up Rover Analytics", "Find the right plan", "Fix my Rover install" ] }, "display": { "mode": "beacon", "branding": "site", "hostSurface": "floating-corner", "actionReveal": "click", "agentModeEntryHints": [ "Use the page beacon or A2W run endpoint before attempting generic DOM automation.", "When Rover is already active, prefer the current-page actions over screenshot loops." ], "compactActionMaxActions": 3, "beaconLabel": "Ask Rover", "presence": "draggable_pill", "openMode": "center_stage", "mobileMode": "fullscreen_sheet", "streamMode": "single_column", "focusView": "focus_stream" }, "artifacts": { "agentCardUrl": "/.well-known/agent-card.json", "roverSiteUrl": "/.well-known/rover-site.json", "llmsUrl": "/llms.txt", "openApiUrl": "https://rtrvr.ai/openapi/a2w.yaml", "siteUrl": "https://rtrvr.ai/" }, "interfaces": [ { "type": "run", "url": "https://agent.rtrvr.ai/v2/a2w/runs", "description": "Canonical Agent-to-Web Protocol (A2W) run creation endpoint.", "available": true }, { "type": "run_get", "url": "https://agent.rtrvr.ai/v2/a2w/runs", "description": "A2W v2 GET run creation for URL-fetch chatbots. Supply url and exactly one canonical selector; cloud, 25 seconds, and Markdown are the defaults.", "available": true }, { "type": "workflow", "url": "https://agent.rtrvr.ai/v2/a2w/workflows", "description": "Aggregated Rover workflow resource for delegated runs.", "available": true }, { "type": "site", "url": "https://rtrvr.ai/", "description": "Human-visible website entrypoint.", "available": true }, { "type": "deep_link", "url": "https://rtrvr.ai/", "description": "Browser launch surface using rover, rover_shortcut, or rover_playbook with rover_kind.", "available": true }, { "type": "webmcp", "url": "https://rtrvr.ai/", "description": "WebMCP tool surface when the browser host supports navigator.modelContext.", "available": false } ], "experience": { "audio": { "narration": { "enabled": true, "rate": 1, "language": "en-US" } }, "motion": { "actionSpotlight": true, "actionSpotlightColor": "#FF4C00" }, "momentCards": { "enabled": true, "autoRecedeMs": 6500, "assets": [ { "id": "rtrvr_generic_open", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_generic_open.webp", "alt": "Minimal rtrvr.ai card reading 'Watch it work.' in dark type with an orange period.", "role": "opening", "focal": "center" }, { "id": "rtrvr_generic_checkpoint", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_generic_checkpoint.webp", "alt": "Minimal rtrvr.ai card reading 'On it.' with a thin orange progress line.", "role": "checkpoint", "focal": "center" }, { "id": "rtrvr_generic_close", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_generic_close.webp", "alt": "Minimal rtrvr.ai card reading 'Task complete.' with a small orange check.", "role": "closing", "focal": "center" }, { "id": "rtrvr_first_win_open", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_first_win_open.webp", "alt": "Minimal rtrvr.ai card reading 'Your first task.' in dark type with an orange period.", "role": "opening", "playbookId": "first_win_extension", "focal": "center" }, { "id": "rtrvr_first_win_checkpoint", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_first_win_checkpoint.webp", "alt": "Minimal rtrvr.ai card reading 'Running in your tab.' with a thin orange progress line.", "role": "checkpoint", "playbookId": "first_win_extension", "focal": "center" }, { "id": "rtrvr_first_win_close", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_first_win_close.webp", "alt": "Minimal rtrvr.ai card reading 'First win, done.' with a small orange check.", "role": "closing", "playbookId": "first_win_extension", "focal": "center" }, { "id": "rtrvr_cloud_open", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_cloud_open.webp", "alt": "Minimal rtrvr.ai card reading 'No tab required.' in dark type with an orange period.", "role": "opening", "playbookId": "cloud_workflow_live", "focal": "center" }, { "id": "rtrvr_cloud_checkpoint", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_cloud_checkpoint.webp", "alt": "Minimal rtrvr.ai card reading 'Running hosted.' with a thin orange progress line.", "role": "checkpoint", "playbookId": "cloud_workflow_live", "focal": "center" }, { "id": "rtrvr_cloud_close", "imageUrl": "https://rtrvr.ai/rover/moments/rtrvr_cloud_close.webp", "alt": "Minimal rtrvr.ai card reading 'Delivered from the cloud.' with a small orange check.", "role": "closing", "playbookId": "cloud_workflow_live", "focal": "center" }, { "id": "rover_yoursite_open", "imageUrl": "https://rtrvr.ai/rover/moments/rover_yoursite_open.webp", "alt": "Minimal Rover card reading 'This is Rover.' in Fraunces serif with a warm sun period.", "role": "opening", "playbookId": "rover_for_your_site", "focal": "center" }, { "id": "rover_yoursite_checkpoint", "imageUrl": "https://rtrvr.ai/rover/moments/rover_yoursite_checkpoint.webp", "alt": "Minimal Rover card reading 'Picture it on your site.' with a thin lime progress line.", "role": "checkpoint", "playbookId": "rover_for_your_site", "focal": "center" }, { "id": "rover_yoursite_close", "imageUrl": "https://rtrvr.ai/rover/moments/rover_yoursite_close.webp", "alt": "Minimal Rover card reading 'Yours to launch.' with a small lime check.", "role": "closing", "playbookId": "rover_for_your_site", "focal": "center" } ] } }, "inputs": { "filesEnabled": true, "acceptedMimeGroups": [ "images", "pdfs", "office", "text" ], "allowMultipleFiles": true } } ``` ## 5. `/llms.txt` Plain-language guide agents read first. Serve at `https://rtrvr.ai/llms.txt` with `Content-Type: text/markdown`: ```markdown # Rover Production > Structured Rover entrypoints for Rover Production. Prefer the published shortcuts and explicit tools over raw DOM automation whenever they match the user's goal. Prefer Rover shortcuts, explicit site tools, and A2W runs over raw DOM automation when they match the requested outcome. ## Act on this site (A2W) - [Primary A2W run endpoint](https://agent.rtrvr.ai/v2/a2w/runs): POST for structured arguments, identity, auth, policy, payment, subject data, or artifacts - [A2W GET for URL-fetch chatbots](https://agent.rtrvr.ai/v2/a2w/runs?url=&prompt=): compact one-request form - [A2W workflow endpoint](https://agent.rtrvr.ai/v2/a2w/workflows): multi-step runs - [A2W OpenAPI spec](https://rtrvr.ai/openapi/a2w.yaml): full REST contract Use exactly one selector: prompt, shortcutId, or playbookId. A linked selector may also supply engagementKind. GET defaults to cloud execution, a 25-second wait, and Markdown. wait accepts 0-55 seconds (higher values are clamped to 55); runs that outlive the window return status: running plus a poll URL. Use POST whenever identity, auth, policy, payment, subject data, or artifacts are needed. Never place secrets, customer context, or subject identifiers in browser or GET URLs. ## Published skills - [setup_rover: Set up Rover](https://agent.rtrvr.ai/v2/a2w/runs?url=https%3A%2F%2Frtrvr.ai%2F&shortcutId=setup_rover) [shortcut] - Set up Rover. Rover is live on my domain, the first visitor journey works, and I know the best next customization. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation. - [analytics_only_onboarding: Set up Rover Analytics](https://agent.rtrvr.ai/v2/a2w/runs?url=https%3A%2F%2Frtrvr.ai%2F&shortcutId=analytics_only_onboarding) [shortcut] - Set up Rover Analytics. Add a production site and open its Analytics only install snippet. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation. - [find_plan: Find the right plan](https://agent.rtrvr.ai/v2/a2w/runs?url=https%3A%2F%2Frtrvr.ai%2F&shortcutId=find_plan) [shortcut] - Find the right plan. Compare the relevant plans and recommend the best fit. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation. - [fix_rover_install: Fix my Rover install](https://agent.rtrvr.ai/v2/a2w/runs?url=https%3A%2F%2Frtrvr.ai%2F&shortcutId=fix_rover_install) [shortcut] - Fix my Rover install. Diagnose, resolve, and verify a Rover installation problem. When to use: Use this when the user wants this exact site outcome and you want a stable path that avoids brittle DOM guessing. Why use this path: Rover shortcuts are explicit site-owned entrypoints with structured A2W run progress and cleaner recovery than generic DOM automation. ## Pages - [home](https://rtrvr.ai/): Set up Rover, Set up Rover Analytics, Find the right plan, Fix my Rover install ## Discovery - [Agent capability card](https://rtrvr.ai/.well-known/agent-card.json): A2A card with skills and interfaces - [Rover site profile](https://rtrvr.ai/.well-known/rover-site.json): full site profile with actions, pages, and policies - [OpenAPI](https://rtrvr.ai/openapi/a2w.yaml): A2W REST contract ``` ## 6. `/.well-known/ai-catalog.json` ARD catalog (Agentic Resource Discovery, draft) — protocol-agnostic index of your agent surfaces. Serve at `https://rtrvr.ai/.well-known/ai-catalog.json` with `Content-Type: application/json`: ```json { "rover_bridge": { "standardPath": "ai-catalog", "status": "preview_ard_v0_9_draft", "canonicalProtocol": "a2w" }, "specVersion": "0.9", "host": "rtrvr.ai", "entries": [ { "name": "rtrvr.ai agent card", "mediaType": "application/a2a-agent-card+json", "url": "https://rtrvr.ai/.well-known/agent-card.json", "description": "A2A agent card: capabilities, skills, security schemes, and the A2W run endpoint." }, { "name": "rtrvr.ai MCP server", "mediaType": "application/mcp-server-card+json", "url": "https://agent.rtrvr.ai/v1/mcp?url=https%3A%2F%2Frtrvr.ai%2F", "description": "Live per-site Rover MCP server (Streamable HTTP): catalog resources plus site capabilities as tools, executing via A2W." } ] } ``` ## 7. `/openapi/a2w.yaml` Exact A2W v2 OpenAPI contract shipped with this Rover backend revision. Serve at `https://rtrvr.ai/openapi/a2w.yaml` with `Content-Type: application/yaml`: ```yaml openapi: 3.1.0 info: title: Rover Agent-to-Web API version: 2.0.0 summary: Strict v2 browser-agent execution for Rover-enabled websites. servers: - url: https://agent.rtrvr.ai security: - {} - webBotAuth: [] - roverDelegation: [] - accessToken: [] paths: /v2/a2w/runs: get: summary: Run Rover from a URL-fetch chatbot parameters: - { name: url, in: query, required: true, schema: { type: string, format: uri } } - { name: prompt, in: query, schema: { type: string } } - { name: shortcutId, in: query, schema: { type: string } } - { name: playbookId, in: query, schema: { type: string } } - { name: engagementKind, in: query, schema: { $ref: '#/components/schemas/EngagementKind' } } - { name: capabilityId, in: query, schema: { type: string } } - { name: execution, in: query, schema: { $ref: '#/components/schemas/Execution' } } - { name: wait, in: query, description: 'Seconds to hold the request open before returning status: running with a poll URL. Values above 55 are clamped to 55; default 25.', schema: { type: integer, minimum: 0, maximum: 55, default: 25 } } - { name: format, in: query, schema: { type: string, enum: [markdown, json], default: markdown } } - { name: commerceType, in: query, schema: { type: string } } - { name: plan, in: query, schema: { type: string } } - { name: actionId, in: query, schema: { type: string } } - { name: maxAmount, in: query, schema: { type: number, minimum: 0 } } - { name: currency, in: query, schema: { type: string } } - { name: cadence, in: query, schema: { type: string } } - { name: confirmationPolicy, in: query, schema: { type: string } } responses: '200': description: Final or in-progress run result content: application/json: schema: { $ref: '#/components/schemas/A2WRun' } '400': { $ref: '#/components/responses/ContractError' } post: summary: Create a structured Rover run parameters: - { name: Idempotency-Key, in: header, schema: { type: string } } - { name: Prefer, in: header, schema: { type: string, example: wait=25 } } requestBody: required: true content: application/json: schema: { $ref: '#/components/schemas/CreateRun' } responses: '200': description: Final result within the requested wait content: application/json: schema: { $ref: '#/components/schemas/A2WRun' } '202': description: Accepted run resource content: application/json: schema: { $ref: '#/components/schemas/A2WRun' } '400': { $ref: '#/components/responses/ContractError' } /v2/a2w/runs/{runId}: parameters: - { $ref: '#/components/parameters/RunId' } - { $ref: '#/components/parameters/Access' } get: summary: Read or stream a run responses: '200': description: Current run state or event stream content: application/json: schema: { $ref: '#/components/schemas/A2WRun' } text/event-stream: { schema: { type: string } } application/x-ndjson: { schema: { type: string } } post: summary: Continue a run requiring ordinary input requestBody: required: true content: application/json: schema: oneOf: - { type: object, additionalProperties: false, required: [input], properties: { input: { type: string } } } - { type: object, additionalProperties: false, required: [answers], properties: { answers: { type: object, additionalProperties: { type: string } } } } responses: '200': description: Resumed run content: application/json: schema: { $ref: '#/components/schemas/A2WRun' } '400': { $ref: '#/components/responses/ContractError' } delete: summary: Cancel a run responses: { '200': { description: Cancelled } } /v2/a2w/runs/{runId}/auth-input: parameters: - { $ref: '#/components/parameters/RunId' } - { $ref: '#/components/parameters/Access' } post: summary: Provide one-shot sign-in continuation data requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: [kind, value] properties: kind: { type: string, enum: [magic_link, otp, unknown] } value: { type: string } responses: '200': description: Resumed run content: application/json: schema: { $ref: '#/components/schemas/A2WRun' } '400': { $ref: '#/components/responses/ContractError' } /v2/a2w/runs/{runId}/artifacts: parameters: - { $ref: '#/components/parameters/RunId' } - { $ref: '#/components/parameters/Access' } get: summary: Open run artifacts responses: { '200': { description: Artifact manifest } } /v2/a2w/runs/{runId}/handoffs: parameters: - { $ref: '#/components/parameters/RunId' } - { $ref: '#/components/parameters/Access' } post: summary: Delegate to another Rover-enabled site requestBody: required: true content: application/json: schema: { $ref: '#/components/schemas/CreateHandoff' } responses: '202': description: Child run created content: application/json: schema: { $ref: '#/components/schemas/A2WRun' } /v2/a2w/workflows/{workflowId}: parameters: - { name: workflowId, in: path, required: true, schema: { type: string } } - { $ref: '#/components/parameters/Access' } get: summary: Read a multi-run workflow responses: { '200': { description: Workflow state } } /v2/a2w/capabilities: get: summary: Discover capabilities for a Rover-enabled URL parameters: - { name: url, in: query, schema: { type: string, format: uri } } - { name: host, in: query, schema: { type: string } } - { name: siteId, in: query, schema: { type: string } } responses: { '200': { description: Capability summary } } /v2/a2w/discovery-events: post: summary: Record redacted discovery telemetry responses: { '202': { description: Accepted } } components: securitySchemes: webBotAuth: type: apiKey in: header name: Signature description: RFC 9421 HTTP Message Signature verified with Rover Web Bot Auth. roverDelegation: type: http scheme: bearer bearerFormat: Rover delegation token accessToken: type: apiKey in: query name: access description: Opaque run- or workflow-scoped access token returned at creation. parameters: RunId: { name: runId, in: path, required: true, schema: { type: string } } Access: { name: access, in: query, schema: { type: string }, description: Opaque run access token. } schemas: EngagementKind: { type: string, enum: [demo, onboarding, support, task] } A2WRunStatus: { type: string, enum: [pending, waiting_browser, running, input_required, completed, failed, cancelled, expired] } A2WInputReason: type: string enum: - auth_required - sign_in_link_required - account_link_required - payment_method_required - payment_confirmation_required - action_confirmation_required - human_verification_required - browser_takeover_required - merchant_policy_blocked - risk_review_required - terms_acknowledgement_required - offer_claim_required Execution: { type: string, enum: [cloud, browser], default: cloud } ExecutionSpec: type: object additionalProperties: false properties: preference: { type: string, enum: [cloud, browser, auto] } mode: { type: string, enum: [cloud, browser] } allowedModes: type: array uniqueItems: true items: { type: string, enum: [cloud, browser] } userPresent: { type: boolean } AgentAttribution: type: object additionalProperties: false properties: key: { type: string } displayName: { type: string } vendor: { type: string } model: { type: string } version: { type: string } homepage: { type: string, format: uri } memoryKey: { type: string } clientId: { type: string } Identity: type: object additionalProperties: false properties: userPresent: { type: boolean } sessionId: { type: string } agentKey: { type: string } memoryKey: { type: string } Accept: type: object additionalProperties: false properties: modes: type: array uniqueItems: true items: { type: string, enum: [text, markdown, json, observation, artifacts] } primary: { type: string, enum: [text, markdown, json, observation, artifacts] } Policy: type: object additionalProperties: false properties: confirmation: { type: string, enum: [required, site_policy, auto] } crossHost: { type: string, enum: [same_host, site_policy, allow] } maxHops: { type: integer, minimum: 0 } Subject: type: object additionalProperties: false properties: emailHint: { type: string } subjectId: { type: string } externalUserIdHash: { type: string } merchantUserId: { type: string } Auth: type: object additionalProperties: false properties: mode: { type: string } token: { type: string, writeOnly: true } scopes: { type: array, items: { type: string } } Payment: type: object additionalProperties: false properties: maxAmount: { type: number, minimum: 0 } currency: { type: string } cadence: { type: string } Commerce: type: object additionalProperties: false properties: type: { type: string } plan: { type: string } actionId: { type: string } CreateRun: type: object additionalProperties: false required: [url] oneOf: - { required: [prompt] } - { required: [shortcutId] } - { required: [playbookId] } properties: url: { type: string, format: uri } prompt: { type: string } shortcutId: { type: string } playbookId: { type: string } engagementKind: { $ref: '#/components/schemas/EngagementKind' } capabilityId: { type: string } args: { type: object, additionalProperties: true } agent: { $ref: '#/components/schemas/AgentAttribution' } identity: { $ref: '#/components/schemas/Identity' } execution: { $ref: '#/components/schemas/ExecutionSpec' } accept: { $ref: '#/components/schemas/Accept' } policy: { $ref: '#/components/schemas/Policy' } subject: { $ref: '#/components/schemas/Subject' } auth: { $ref: '#/components/schemas/Auth' } payment: { $ref: '#/components/schemas/Payment' } commerce: { $ref: '#/components/schemas/Commerce' } confirmationPolicy: { type: string, enum: [require_before_charge, auto, site_policy] } artifacts: type: array maxItems: 16 items: { type: string, maxLength: 64 } CreateHandoff: type: object additionalProperties: false required: [url] oneOf: - { required: [prompt] } - { required: [shortcutId] } - { required: [playbookId] } properties: url: { type: string, format: uri } prompt: { type: string } shortcutId: { type: string } playbookId: { type: string } engagementKind: { $ref: '#/components/schemas/EngagementKind' } capabilityId: { type: string } args: { type: object, additionalProperties: true } agent: { $ref: '#/components/schemas/AgentAttribution' } identity: { $ref: '#/components/schemas/Identity' } execution: { $ref: '#/components/schemas/ExecutionSpec' } accept: { $ref: '#/components/schemas/Accept' } policy: { $ref: '#/components/schemas/Policy' } contextSummary: { type: string } expectedOutput: { type: string } lastObservation: { type: object, additionalProperties: true } A2WInputRequest: type: object additionalProperties: false properties: questions: { type: array, items: {} } askUser: { type: object, additionalProperties: true } message: { type: string } reason: { $ref: '#/components/schemas/A2WInputReason' } links: type: object additionalProperties: false properties: confirm: { type: string, format: uri } open: { type: string, format: uri } verify: { type: string, format: uri } expiresAt: { type: string, format: date-time } commerceStandards: { type: object, additionalProperties: true } A2WRun: type: object additionalProperties: false required: [id, protocol, runId, run, status, terminalStatuses, interactiveStatuses, links, next, execution, diagnostics, identity, request] properties: id: { type: string } protocol: { type: string, const: a2w } runId: { type: string } workflowId: { type: string } run: { type: string, format: uri } workflow: { type: string, format: uri } status: { $ref: '#/components/schemas/A2WRunStatus' } terminalStatuses: type: array items: { $ref: '#/components/schemas/A2WRunStatus' } interactiveStatuses: type: array items: { $ref: '#/components/schemas/A2WRunStatus' } retryAfterMs: { type: integer, minimum: 0 } links: { type: object, additionalProperties: true } next: { type: object, additionalProperties: true } execution: { type: object, additionalProperties: true } diagnostics: { type: object, additionalProperties: true } identity: { type: object, additionalProperties: false, required: [trust], properties: { trust: { type: string, enum: [verified, anonymous] }, upgrade: { type: string } } } request: { type: object, additionalProperties: true } open: { type: string, format: uri } browserLink: { type: string, format: uri } error: {} result: { type: object, additionalProperties: true } openedTabs: { type: array, items: { type: object, additionalProperties: true } } handoff: { type: object, additionalProperties: true } input: { $ref: '#/components/schemas/A2WInputRequest' } authInput: type: object additionalProperties: false properties: status: { type: string, enum: [awaiting, provided, consumed] } kind: { type: string, enum: [magic_link, otp, unknown] } prompt: { type: string } emailMasked: { type: string } responses: ContractError: description: Strict v2 contract error content: application/json: schema: type: object additionalProperties: false required: [error] properties: error: type: object additionalProperties: false required: [code, message] properties: code: { type: string, enum: [unsupported_parameter, selector_conflict, kind_conflict, invalid_parameter] } message: { type: string } ``` ## 8. How agents transact (A2W) Agents send a plain-language goal to `https://agent.rtrvr.ai/v2/a2w/runs` (POST JSON, or GET with `?url=&prompt=`). They never need an internal action id. The authoritative contract is `extensions.rover.instructions` in `agent-card.json` plus the OpenAPI file above; the current instructions are: Chatbots and other URL-fetch agents should use Rover's first-party cloud A2W endpoint. Coding agents that can open a browser may instead use the explicit browser receipt/handoff path. These are two execution paths for this Rover-enabled site; neither enables third-party cloud tools. - Prefer exact Rover shortcuts and explicit site tools over raw DOM automation when the user goal matches a published skill. - For a person in a browser, use exactly one of rover, rover_shortcut, or rover_playbook and include rover_kind when the kind is known. - For a URL-fetch chatbot, use GET /v2/a2w/runs with url and exactly one of prompt, shortcutId, or playbookId. Omit execution, wait, and format to use the compact defaults. - If the target url already embeds canonical Rover launch parameters, pass it alone; do not mix embedded and explicit selectors. - Use POST /v2/a2w/runs for structured input, identity, auth, payment, policy, subject data, or artifact requests. - Never put tokens, secrets, subject identifiers, or customer context in browser or GET URLs. - Fall back to generic DOM automation only when no matching Rover shortcut or explicit tool exists for the requested outcome. - To purchase, subscribe, or check out, send a plain-language prompt to A2W (e.g. "subscribe me to the pro plan"). You never need to know an internal action id. Discovery commerce teasers may include a priceHint (display-only, e.g. "$9.99/month"). - Payment ALWAYS returns status=input_required with reason=payment_confirmation_required and an input.links.confirm URL (confirm/verify links live under the run's input object, never top-level links). Relay that link to the human and poll the run — never collect or send card details. - If a run returns reason=auth_required, relay input.links.verify to the human; after they verify, the run completes with a delegation token. Retry your request with auth: { mode: "delegated_session", token }. - If a run returns status=input_required with NO payment/auth reason (an ordinary question), POST { input: "answer" } to the run; you may also pass auth: { mode: "delegated_session", token } to act as a verified subject. Reasons payment_confirmation_required and auth_required complete out-of-band — relay the link and poll; never POST input to those. - Two execution modes: execution=cloud runs in Rover's hosted browser (default); execution=browser returns links.open to drive the human's OWN browser in their session. If a continuation returns error=browser_session_gone, relay the fresh data.open link from the error, or re-POST with execution="cloud" to resume in the cloud. - You may pass subject.emailHint (the user's email) and payment.maxAmount to scope a purchase. Card data must never pass through you. - The merchant stays merchant of record; checkout completes on your own rails. ## 9. Rover's agent traffic is cryptographically signed Rover signs its outbound agent requests with RFC 9421 HTTP Message Signatures (IETF Web Bot Auth): `Signature` + `Signature-Input` headers with `Signature-Agent` pointing at Rover's public key directory, `https://agent.rtrvr.ai/.well-known/http-message-signatures-directory`. If your CDN or WAF verifies signed agents (e.g. Cloudflare Verified Bots / Signed Agents), you can allow-list Rover by that directory instead of by IP or User-Agent string. ## 10. Tell Rover who's signed in (one line) Rover greets identified visitors like your product already knows them, and remembers where each one left off. Wire it wherever your app learns who signed in: ```js // After sign-in (any auth provider — Firebase, Clerk, Auth0, Supabase, NextAuth…): window.rover?.identify({ userId: user.id, email: user.email, name: user.name }); // Optional org/account grouping and safe context hints: window.rover?.group({ accountId: account.id }); window.rover?.update({ visitor: { name: user.name } }); // On sign-out: window.rover?.update({ visitor: null }); window.rover?.resetIdentity(); // On business events you want attributed: window.rover?.trackGoal({ goalId: 'configured_goal_id', value: 49, currency: 'USD' }); window.rover?.trackEvent({ eventId: 'configured_event_id', properties: {} }); // trackConversion remains supported as a legacy alias. // Wire this to your consent manager before collecting analytics: window.rover?.setConsent({ analytics: consent.analytics }); ``` Only salted hashes of ids leave the page. Never put customer identifiers, context tokens, or resolver payloads in URLs or logs. For server-verified identity (cross-device memory), wire the signed context resolver from the workspace's Audience section. No goal IDs are configured yet. Add bounded goals in Analytics > Data settings before wiring `trackGoal`. No semantic product events are configured yet. Add registered events in Analytics > Data settings before wiring `trackEvent`. ## 11. SPA, CSP, and verification Rover observes history.pushState, history.replaceState, and popstate for route measurement; do not add a second route tracker. Allow the generated embed and API origins in script-src/connect-src, keep the tag single-instance, then verify hard navigation, SPA navigation, consent revoke/grant, identify/sign-out, and one configured goal. For non-JavaScript crawlers, optionally install `@rtrvr-ai/rover/analytics/server` with a separate server-only credential. Never expose that credential to browser code and never forward raw IP addresses, cookies, request bodies, or arbitrary query values. ```js import { createRoverServerAnalytics } from '@rtrvr-ai/rover/analytics/server'; const roverAnalytics = createRoverServerAnalytics({ siteId: process.env.ROVER_SITE_ID, credential: process.env.ROVER_SERVER_ANALYTICS_KEY, }); app.use(roverAnalytics.middleware); // GET/HEAD path + bounded user-agent family only ``` ## 12. Choose who sees Rover By default Rover appears for every visitor. The workspace's Install section can restrict it to signed-in visitors only, or to chosen pages (`experience.presence.visibility`). On a gated site the widget stays hidden until `identify()` runs — so verify the install from a signed-in page load, or with the workspace's Live Test. ## 13. Configure Rover with your AI — and talk to it from your pages The workspace's Install section mints a site-scoped key your own AI tools can use over MCP or REST to read this site's Rover setup and propose changes. Proposals land in the owner's review inbox — nothing an outside AI writes applies without the owner keeping it. Any page can also open Rover with a visitor's words — a search box, a help button, a "Talk to Rover" control: ```js // Opens Rover and starts a new chat with the visitor's words: window.rover?.ask(input.value); // Empty text just opens the panel (type or talk there): window.rover?.ask(''); ``` Use the API call, never a client-built `?rover=` URL, for same-page launches — the SDK's recursive-launch guard treats constructed launch URLs as agent-driven and suppresses them. ### Page-scoped shortcuts Any configured shortcut can carry `pages`, a list of path prefixes (max 20, each starting with `/`) where that shortcut is visible — `pages: ["/pricing"]` shows it on `/pricing` and `/pricing/enterprise`, nowhere else. Absent `pages` keeps the shortcut on every page, and the visible set re-evaluates automatically on SPA route changes. Use it to give each page its own starter chips, with `rover?.ask(...)` covering fully bespoke page controls. ## 14. For your coding agent (save this file as AGENTS.md) This file follows the AGENTS.md convention that coding agents (Codex, Cursor, GitHub Copilot, Windsurf, Jules) read automatically from your repo root: 1. Save this file as `AGENTS.md` at your repo root. If you already have an `AGENTS.md`, **append this content as a `## Rover` section — never overwrite** what's there. 2. Claude Code reads `CLAUDE.md`, not `AGENTS.md`: add a `CLAUDE.md` whose first line is `@AGENTS.md` (or append that line to your existing `CLAUDE.md`). 3. Ask the agent to: add the embed `