{
  "schema_version": "1.0",
  "name": "TrendsAGI browser-agent surface",
  "updated": "2026-10-30",
  "description": "Stable DOM hooks, readiness markers and task recipes for Browser Harness, browser-use, Playwright and other CDP agents.",
  "site": "https://trendsagi.com",
  "app": "https://app.trendsagi.com",
  "documentation": {
    "guide": "https://trendsagi.com/browser-agents",
    "markdown": "https://trendsagi.com/browser-agents.md",
    "llms_txt": "https://trendsagi.com/llms.txt",
    "webmcp": "https://trendsagi.com/webmcp",
    "mcp": "https://trendsagi.com/mcp",
    "api_docs": "https://trendsagi.com/api-docs"
  },
  "modes": {
    "agent_query_parameter": "agent=1",
    "agent_mode_example": "https://trendsagi.com/?agent=1",
    "effect": "Disables decorative motion and exposes deterministic readiness markers. Does not bypass authentication, permissions, paywalls or rate limits.",
    "prefers_reduced_motion": true
  },
  "readiness": {
    "selector_attribute": "data-agent",
    "wait_for": "body[data-agent-ready=\"true\"]",
    "attributes": [
      {
        "name": "data-agent-mode",
        "placement": "html",
        "values": [
          "true"
        ],
        "purpose": "Agent mode is active."
      },
      {
        "name": "data-agent-site",
        "placement": "body",
        "values": [
          "trendsagi-public",
          "trendsagi-app"
        ],
        "purpose": "Which host is rendered."
      },
      {
        "name": "data-agent-route",
        "placement": "body",
        "values": [
          "pathname"
        ],
        "purpose": "Current route, updated after client-side navigation."
      },
      {
        "name": "data-agent-ready",
        "placement": "body",
        "values": [
          "true",
          "false"
        ],
        "purpose": "Shell is hydrated and interactive; lazy route content may still show its own loading status."
      },
      {
        "name": "data-agent-shell",
        "placement": "app root",
        "values": [
          "app",
          "workspace",
          "billing",
          "auth",
          "checkout",
          "public",
          "preview"
        ],
        "purpose": "Active application shell."
      }
    ]
  },
  "selectors": {
    "attribute": "data-agent",
    "stability": "Names are stable across releases and are listed here before they are used. Responsive variants of the same control share one name; prefer the visible match. Unknown names should be treated as absent, not guessed.",
    "public": [
      {
        "group": "global",
        "name": "site-header",
        "element": "nav",
        "purpose": "Primary site navigation."
      },
      {
        "group": "global",
        "name": "home-link",
        "element": "a",
        "purpose": "Returns to the home page."
      },
      {
        "group": "global",
        "name": "header-login",
        "element": "a",
        "purpose": "Opens the sign-in form."
      },
      {
        "group": "global",
        "name": "header-signup",
        "element": "a",
        "purpose": "Opens account registration."
      },
      {
        "group": "global",
        "name": "header-dashboard",
        "element": "a",
        "purpose": "Opens the app when the browser already has a session."
      },
      {
        "group": "global",
        "name": "mobile-menu-toggle",
        "element": "button",
        "purpose": "Opens the navigation drawer below 1200px."
      },
      {
        "group": "global",
        "name": "mobile-menu",
        "element": "div",
        "purpose": "The open navigation drawer."
      },
      {
        "group": "global",
        "name": "site-footer",
        "element": "footer",
        "purpose": "Footer navigation, including Browser agents."
      },
      {
        "group": "global",
        "name": "footer-browser-agents",
        "element": "a",
        "purpose": "Opens this guide."
      },
      {
        "group": "global",
        "name": "nav-research",
        "element": "a",
        "purpose": "Primary navigation: Research."
      },
      {
        "group": "global",
        "name": "nav-use-cases",
        "element": "a",
        "purpose": "Primary navigation: Use Cases."
      },
      {
        "group": "global",
        "name": "nav-tools",
        "element": "a",
        "purpose": "Primary navigation: Tools."
      },
      {
        "group": "global",
        "name": "nav-subscription",
        "element": "a",
        "purpose": "Primary navigation: Pricing."
      },
      {
        "group": "global",
        "name": "nav-api-docs",
        "element": "a",
        "purpose": "Primary navigation: API Docs."
      },
      {
        "group": "global",
        "name": "nav-security",
        "element": "a",
        "purpose": "Primary navigation: Security."
      },
      {
        "group": "global",
        "name": "cookie-banner",
        "element": "aside",
        "purpose": "Analytics consent banner, when consent is unset."
      },
      {
        "group": "global",
        "name": "cookie-deny",
        "element": "button",
        "purpose": "Keeps optional analytics off."
      },
      {
        "group": "global",
        "name": "cookie-accept",
        "element": "button",
        "purpose": "Turns optional analytics on."
      },
      {
        "group": "home",
        "name": "hero-start-free",
        "element": "a",
        "purpose": "Primary signup call to action in the hero."
      },
      {
        "group": "home",
        "name": "hero-strategy-call",
        "element": "a",
        "purpose": "Books a strategy call, in a new tab."
      },
      {
        "group": "home",
        "name": "hero-api-docs",
        "element": "a",
        "purpose": "Opens the API documentation."
      },
      {
        "group": "home",
        "name": "plans",
        "element": "section",
        "purpose": "The pricing section on the home or subscription page."
      },
      {
        "group": "home",
        "name": "billing-monthly",
        "element": "button",
        "purpose": "Shows monthly prices."
      },
      {
        "group": "home",
        "name": "billing-yearly",
        "element": "button",
        "purpose": "Shows yearly prices."
      },
      {
        "group": "home",
        "name": "plan-developer-cta",
        "element": "button",
        "purpose": "Starts the free Developer plan."
      },
      {
        "group": "home",
        "name": "plan-advantage-cta",
        "element": "button",
        "purpose": "Starts the Advantage plan."
      },
      {
        "group": "home",
        "name": "plan-scale-cta",
        "element": "button",
        "purpose": "Starts the Scale plan."
      },
      {
        "group": "home",
        "name": "agent-api-cta",
        "element": "a",
        "purpose": "Opens the agent API documentation."
      },
      {
        "group": "home",
        "name": "agent-harness-cta",
        "element": "a",
        "purpose": "Opens this browser-agent guide from the home page."
      },
      {
        "group": "account",
        "name": "login-form",
        "element": "form",
        "purpose": "Email and password sign-in."
      },
      {
        "group": "account",
        "name": "login-email",
        "element": "input",
        "purpose": "Account email address."
      },
      {
        "group": "account",
        "name": "login-password",
        "element": "input",
        "purpose": "Account password."
      },
      {
        "group": "account",
        "name": "login-remember",
        "element": "input",
        "purpose": "Remember-me checkbox."
      },
      {
        "group": "account",
        "name": "login-submit",
        "element": "button",
        "purpose": "Submits the sign-in form."
      },
      {
        "group": "account",
        "name": "login-error",
        "element": "div",
        "purpose": "Form-level sign-in error, role=alert."
      },
      {
        "group": "account",
        "name": "login-google",
        "element": "div",
        "purpose": "Google Identity button container, when configured."
      },
      {
        "group": "account",
        "name": "login-microsoft",
        "element": "button",
        "purpose": "Starts Microsoft single sign-on."
      },
      {
        "group": "account",
        "name": "login-forgot",
        "element": "a",
        "purpose": "Opens password recovery."
      },
      {
        "group": "account",
        "name": "login-register",
        "element": "a",
        "purpose": "Switches to registration."
      },
      {
        "group": "account",
        "name": "register-form",
        "element": "form",
        "purpose": "Account registration."
      },
      {
        "group": "account",
        "name": "register-first-name",
        "element": "input",
        "purpose": "First name."
      },
      {
        "group": "account",
        "name": "register-last-name",
        "element": "input",
        "purpose": "Last name."
      },
      {
        "group": "account",
        "name": "register-email",
        "element": "input",
        "purpose": "Account email address."
      },
      {
        "group": "account",
        "name": "register-password",
        "element": "input",
        "purpose": "New password, at least 8 characters."
      },
      {
        "group": "account",
        "name": "register-confirm-password",
        "element": "input",
        "purpose": "Password confirmation."
      },
      {
        "group": "account",
        "name": "register-terms",
        "element": "input",
        "purpose": "Terms and privacy agreement checkbox."
      },
      {
        "group": "account",
        "name": "register-submit",
        "element": "button",
        "purpose": "Creates the account."
      },
      {
        "group": "account",
        "name": "register-error",
        "element": "div",
        "purpose": "Form-level registration error, role=alert."
      },
      {
        "group": "account",
        "name": "register-login",
        "element": "a",
        "purpose": "Switches to sign-in."
      },
      {
        "group": "contact",
        "name": "contact-form",
        "element": "form",
        "purpose": "Contact form."
      },
      {
        "group": "contact",
        "name": "contact-name",
        "element": "input",
        "purpose": "Sender's name."
      },
      {
        "group": "contact",
        "name": "contact-email",
        "element": "input",
        "purpose": "Sender's email address."
      },
      {
        "group": "contact",
        "name": "contact-message",
        "element": "textarea",
        "purpose": "Message body."
      },
      {
        "group": "contact",
        "name": "contact-submit",
        "element": "button",
        "purpose": "Sends the message."
      },
      {
        "group": "guide",
        "name": "browser-agent-guide",
        "element": "div",
        "purpose": "This page."
      },
      {
        "group": "guide",
        "name": "agent-mode-link",
        "element": "a",
        "purpose": "Opens the current page with agent mode on."
      },
      {
        "group": "guide",
        "name": "manifest-link",
        "element": "a",
        "purpose": "Opens the machine-readable manifest."
      }
    ],
    "app": [
      {
        "group": "shell",
        "name": "app-root",
        "element": "div",
        "purpose": "Top-level app container, with the active shell as data-agent-shell."
      },
      {
        "group": "shell",
        "name": "app-nav",
        "element": "nav",
        "purpose": "Signed-in navigation."
      },
      {
        "group": "shell",
        "name": "app-home",
        "element": "a",
        "purpose": "Returns to the dashboard when signed in."
      },
      {
        "group": "shell",
        "name": "app-search",
        "element": "button",
        "purpose": "Opens the command palette."
      },
      {
        "group": "shell",
        "name": "app-notifications",
        "element": "button",
        "purpose": "Opens recent notifications."
      },
      {
        "group": "shell",
        "name": "app-notifications-panel",
        "element": "section",
        "purpose": "The open notifications panel."
      },
      {
        "group": "shell",
        "name": "app-account",
        "element": "button",
        "purpose": "Opens the account menu."
      },
      {
        "group": "shell",
        "name": "app-logout",
        "element": "button",
        "purpose": "Signs out."
      },
      {
        "group": "shell",
        "name": "app-mobile-menu-toggle",
        "element": "button",
        "purpose": "Opens the navigation drawer below 1280px."
      },
      {
        "group": "shell",
        "name": "app-mobile-menu",
        "element": "aside",
        "purpose": "The open navigation drawer."
      },
      {
        "group": "shell",
        "name": "app-login",
        "element": "a",
        "purpose": "Opens the public sign-in page."
      },
      {
        "group": "shell",
        "name": "app-signup",
        "element": "a",
        "purpose": "Opens public registration."
      },
      {
        "group": "navigation",
        "name": "app-nav-dashboard",
        "element": "a",
        "purpose": "Dashboard."
      },
      {
        "group": "navigation",
        "name": "app-nav-trends",
        "element": "a",
        "purpose": "Live trends."
      },
      {
        "group": "navigation",
        "name": "app-nav-watchlists",
        "element": "a",
        "purpose": "Watchlists."
      },
      {
        "group": "navigation",
        "name": "app-nav-insights",
        "element": "a",
        "purpose": "AI insights."
      },
      {
        "group": "navigation",
        "name": "app-nav-integrations",
        "element": "a",
        "purpose": "Connected ad platforms."
      },
      {
        "group": "navigation",
        "name": "app-nav-more",
        "element": "button",
        "purpose": "Opens the workspace menu."
      },
      {
        "group": "navigation",
        "name": "app-more-menu",
        "element": "div",
        "purpose": "The open workspace menu."
      },
      {
        "group": "command",
        "name": "app-command-palette",
        "element": "section",
        "purpose": "Keyboard-driven navigation dialog."
      },
      {
        "group": "command",
        "name": "app-command-input",
        "element": "input",
        "purpose": "Command search field."
      },
      {
        "group": "command",
        "name": "app-command-close",
        "element": "button",
        "purpose": "Closes the palette."
      },
      {
        "group": "workspace",
        "name": "app-dashboard",
        "element": "div",
        "purpose": "Signal desk overview."
      },
      {
        "group": "workspace",
        "name": "app-trends",
        "element": "div",
        "purpose": "Trend discovery page."
      },
      {
        "group": "workspace",
        "name": "app-trends-search",
        "element": "input",
        "purpose": "Filters trends by phrase."
      },
      {
        "group": "workspace",
        "name": "app-trends-category",
        "element": "select",
        "purpose": "Filters trends by category."
      },
      {
        "group": "workspace",
        "name": "app-trends-timeframe",
        "element": "select",
        "purpose": "Filters trends by time window."
      },
      {
        "group": "workspace",
        "name": "app-watchlists",
        "element": "div",
        "purpose": "Watchlist coverage page."
      },
      {
        "group": "workspace",
        "name": "app-watchlist-add",
        "element": "button",
        "purpose": "Opens the add-watchlist form."
      },
      {
        "group": "workspace",
        "name": "app-watchlist-modal",
        "element": "div",
        "purpose": "The add-watchlist dialog."
      },
      {
        "group": "workspace",
        "name": "app-watchlist-form",
        "element": "form",
        "purpose": "The add-watchlist form."
      },
      {
        "group": "workspace",
        "name": "app-watchlist-keyword",
        "element": "input",
        "purpose": "Keyword or phrase to track."
      },
      {
        "group": "workspace",
        "name": "app-watchlist-threshold",
        "element": "input",
        "purpose": "Volume threshold for the alert."
      },
      {
        "group": "workspace",
        "name": "app-watchlist-submit",
        "element": "button",
        "purpose": "Adds the watchlist stream."
      },
      {
        "group": "workspace",
        "name": "app-watchlist-close",
        "element": "button",
        "purpose": "Closes the dialog without adding."
      },
      {
        "group": "workspace",
        "name": "app-export",
        "element": "div",
        "purpose": "Data export page."
      },
      {
        "group": "workspace",
        "name": "app-export-run",
        "element": "button",
        "purpose": "Starts the selected export."
      },
      {
        "group": "consent",
        "name": "app-cookie-banner",
        "element": "section",
        "purpose": "Analytics consent panel, when consent is unset."
      },
      {
        "group": "consent",
        "name": "app-cookie-deny",
        "element": "button",
        "purpose": "Keeps optional analytics off."
      },
      {
        "group": "consent",
        "name": "app-cookie-accept",
        "element": "button",
        "purpose": "Turns optional analytics on."
      }
    ]
  },
  "flows": [
    {
      "id": "read-public",
      "title": "Read public trend intelligence",
      "entry": "https://trendsagi.com/trending",
      "steps": [
        "Open the trending page, or /blog for editorial reports.",
        "Read the page h1 and the article links; no account or consent choice is required to read them.",
        "Follow a report to /blog/trends/<slug> for its measured velocity and evidence."
      ],
      "success": "A report page with a dated headline and its measurement notes is visible."
    },
    {
      "id": "compare-plans",
      "title": "Compare plans and prices",
      "entry": "https://trendsagi.com/subscription",
      "steps": [
        "Open /subscription. Prices follow the visitor's detected currency.",
        "Use data-agent=\"billing-monthly\" or data-agent=\"billing-yearly\" to switch the cycle.",
        "Read each plan card, or call the public get_trendsagi_plans WebMCP tool when the browser supports it."
      ],
      "success": "Plan names, prices and included capacity are visible without signing in."
    },
    {
      "id": "create-account",
      "title": "Create an account",
      "entry": "https://trendsagi.com/register",
      "steps": [
        "Wait for data-agent-ready=\"true\" on the body.",
        "Fill register-first-name, register-last-name, register-email, register-password and register-confirm-password.",
        "Tick register-terms, then press register-submit.",
        "Registration ends on /confirm-email; the account is usable after the email is confirmed."
      ],
      "success": "The confirm-email page names the address that was registered."
    },
    {
      "id": "sign-in",
      "title": "Sign in to the app",
      "entry": "https://trendsagi.com/login",
      "steps": [
        "Use email and password with login-email, login-password and login-submit. This is the deterministic path.",
        "Wait for the redirect to app.trendsagi.com and for body[data-agent-ready=\"true\"].",
        "Read body[data-agent-route] to confirm the landing route, usually /dashboard or /onboarding."
      ],
      "success": "The signed-in app shell is visible and app-nav is present."
    },
    {
      "id": "find-trend",
      "title": "Find a rising trend",
      "entry": "https://app.trendsagi.com/trends",
      "steps": [
        "Open /trends and wait for the app to be ready.",
        "Type a phrase into app-trends-search, or choose a category with app-trends-category.",
        "Read the result rows and follow a row's link for the trend's insight page."
      ],
      "success": "The trend table shows filtered rows with measured volume and velocity."
    },
    {
      "id": "add-watchlist",
      "title": "Add a watchlist stream",
      "entry": "https://app.trendsagi.com/watchlists",
      "steps": [
        "Open /watchlists and press app-watchlist-add.",
        "Enter a phrase in app-watchlist-keyword, or switch the dialog to Category and choose one.",
        "Set the alert threshold with app-watchlist-threshold, then press app-watchlist-submit.",
        "Wait for the dialog to close and the new stream to appear in the coverage list."
      ],
      "success": "The new stream appears in the watchlist coverage list with its alert condition."
    },
    {
      "id": "export",
      "title": "Read or download an export",
      "entry": "https://app.trendsagi.com/export",
      "steps": [
        "Open /export and choose a report type.",
        "Press app-export-run, or open a saved configuration and run it.",
        "Wait for the export run to reach a completed state before downloading it."
      ],
      "success": "A completed export run exposes a download link or the configured destination."
    },
    {
      "id": "webmcp",
      "title": "Use the browser's own tool interface",
      "entry": "https://trendsagi.com/webmcp",
      "steps": [
        "In Chrome 149+ or another WebMCP browser, sign in at app.trendsagi.com.",
        "The page registers read-only TrendsAGI tools with document.modelContext.",
        "Call the tool directly instead of driving the DOM; see /webmcp for the list."
      ],
      "success": "The browser lists TrendsAGI tools and returns structured trend data."
    }
  ],
  "auth": {
    "deterministic_path": "Email and password at https://trendsagi.com/login",
    "fields": [
      "login-email",
      "login-password"
    ],
    "submit": "login-submit",
    "success_signal": "body[data-agent-site=\"trendsagi-app\"][data-agent-ready=\"true\"]",
    "sso_note": "Google and Microsoft sign-in hand control to the identity provider and may add their own challenge.",
    "registration": "https://trendsagi.com/register",
    "carries_agent_mode": "Email/password and Google sign-in append ?agent=1 to the app redirect when agent mode is active. Microsoft sign-in returns through the identity provider and does not carry it."
  },
  "constraints": [
    "Agent mode (?agent=1) disables decorative motion. It does not bypass authentication, permissions, paywalls or rate limits.",
    "Public pages are readable without an account. Dashboard, watchlist, insight and export routes require a signed-in session.",
    "Email and password is the deterministic sign-in path. Google and Microsoft sign-in hand control to the identity provider, which may add its own challenge.",
    "One account per operator. Do not create accounts, start trials or run exports in bulk.",
    "Read the Terms of Service and the API limits that apply to the account you use.",
    "The stable selectors are for navigation and reading. They are not a licence to automate actions a person could not take in the same session."
  ]
}