# ChatStack — browser agent notes

> Short guide for browser automation agents (Playwright, Computer Use, and similar) that drive the human chat UI at `https://www.chatstack.app/`. Unofficial UI automation — not a product SKU.

This document covers the **chat interview** path only. Do **not** call marketing-site REST submit endpoints from Playwright / Computer Use — those are a different door (see Paths).

## Paths

Pick **one** door. Browser automation stays on the first row.

| Path | When to use | Notes |
|------|-------------|--------|
| **Chat interview** at `/` (**this doc**) | You still need the on-site 4-agent workflow in the widget | Drive UI → gates → PRD form. Submit goes through the chat (`prd.submit` → site actions API), not Agent REST. |
| **Skip-interview submit** | You **already** have structured PRD artifacts and a server-side `AGENT_API_KEY` | `POST /api/agent/submit`. **Not** for browser agents. |
| **Portal MCP / CRM REST** | A PRD already exists; you need packs, writes, Improve/Build, or lock | Portal → Settings → API access. Stdio or hosted portal MCP + PAT. Never put `AGENT_API_KEY` in MCP config. See https://www.chatstack.app/cursor-ai-prd-integration-guide.md |
| **Public interview MCP** | Run the 4-agent flow from an MCP client without a portal account | `https://interview-mcp.chatstack.app/mcp` (no PAT); staging: `https://interview-mcp-staging.chatstack.app/mcp`. Not this Playwright guide. See `/cursor-ai-prd-integration-guide.md`. |
| **Interview API** | Run the 4-agent flow without the iframe (REST) | Portal PAT or guest `interview_token` → `/api/agent/interview/*`. Not this Playwright guide. |

**Discovery (not a workflow step):** `GET https://www.chatstack.app/api/agent` (submit / Interview catalog) and `GET https://www.portal.chatstack.app/api/agent` (CRM REST/MCP catalog). Neither runs the chat UI. Do not open them as part of a Playwright run of this guide.

If you already have (or only need) structured artifacts, prefer skip-interview submit or portal MCP instead of browser UI automation.

## Viewport: first message

Breakpoint matches Tailwind `md` (`max-width: 767px` = mobile).

| | Desktop (≥768px) | Mobile (<768px) |
|--|------------------|-------------------|
| First composer | Same-origin landing overlay | ChatKit start screen inside `iframe[name="chatkit"]` |
| Hooks | `data-testid="chatstack-landing-input"` (`aria-label="Describe your app idea"`), `data-testid="chatstack-landing-send"` | None on the iframe composer — find by greeting / placeholder text |
| After first send | Landing unmounts; later turns use the ChatKit iframe | Stay in the iframe |

Do **not** type the first desktop message into the ChatKit iframe.

## Same-origin hooks (parent page)

ChatKit gates live in a **cross-origin** iframe. Parent-page scripts cannot patch iframe buttons. Wait on the parent live region instead of long fixed sleeps:

- `[data-testid="chatstack-workflow-step"]`
- `data-workflow-step` — machine step id (e.g. `summary-confirm`, `estimate-prd`)
- `data-next-control` — visible label of the usual next enabled control when a gate is pending (empty when none). **Attribute only** — not duplicated into the screen-reader announcement.

Other same-origin hooks:

| Hook | Role |
|------|------|
| `chatstack-cookie-accept` | Cookie banner accept |
| `chatstack-idle-dismiss` | Idle “Can we help?” dismiss (“Not now”) if shown |
| `chatstack-prd-success` / `chatstack-prd-error` | PRD result dialogs |
| `chatstack-estimate-totals` | Optional estimate totals (`data-hours` / `data-usd`) |

Do **not** invent `data-testid`s on iframe gate buttons. ChatKit `Button` has no `data-testid` / `ariaLabel` API.

## Gate labels (visible text in the iframe)

Find enabled controls by **visible label**. Do not use `.nth()` on generic “Accept” / “Approve” text.

| `data-workflow-step` | Typical next control (`data-next-control`) |
|----------------------|--------------------------------------------|
| `interview-mcq` | `Submit answers` |
| `summary-confirm` | `Confirm summary` |
| `mode-select` | `Choose A — Normal` (A/B/C are all valid; attribute names the common default) |
| `stories-draft` | `Confirm user stories draft` |
| `stories-approval` | `Confirm user stories` |
| `requirements-approval` | `Accept requirements` |
| `techspec-approval` | `Accept technical specifications` |
| `estimate-prd` | `Request PRD` |

Reject / request-changes siblings exist (e.g. `Request user story changes`). Only click **enabled** buttons.

## Useful `data-workflow-step` values

| Step | Meaning |
|------|---------|
| `landing` | Desktop landing overlay open |
| `interview-mcq` | MCQ / choice widget |
| `summary-confirm` | Confirm summary gate |
| `mode-select` | Choose A/B/C |
| `stories-draft` | Confirm user stories draft |
| `stories-approval` | Confirm user stories lock |
| `requirements-approval` | Accept requirements |
| `techspec-approval` | Accept technical specifications |
| `estimate` | Estimate generating |
| `estimate-prd` | Request PRD form (after estimate + hosting TCO card) |
| `prd-submitted` | Submit succeeded this session |
| `processing` | Agent working; composer blocked |

## Approximate timings (not SLAs)

A full Lean Startup path to PRD submit is often **~10–15 minutes** wall clock (varies with scope, MCQ depth, and model load). Prefer polling `data-workflow-step` / `data-next-control` over blind multi-minute sleeps.

| Phase | Typical wait | Still healthy if… |
|-------|--------------|-------------------|
| After first send → first MCQ / gate | ~15–45s (fallback poll if live region empty ~15–20s) | Step leaves `landing` / enters `interview-mcq` or `processing` |
| Each `processing` stretch (agent drafting) | ~30s–3 min per stretch | Step stays `processing` and composer is blocked — **do not abort** |
| MCQ rounds (`interview-mcq`) | Seconds per round; 0–4+ chained rounds | Loop while `Submit answers` / step is `interview-mcq` |
| Human gates (confirm / accept) | Instant once the button is enabled | `data-next-control` matches the gate table |
| Stories / requirements / techspec generation | Often 1–3+ min each under `processing` | Step eventually becomes the matching `*-approval` / `*-draft` |
| `estimate` → `estimate-prd` | Often ~30s–2+ min | Step becomes `estimate-prd` and **Request PRD** appears |
| After **Request PRD** | Usually seconds | `chatstack-prd-success` or step `prd-submitted` (or `chatstack-prd-error`) |

These ranges are **approximate**. A long quiet spell with step `processing` or `estimate` is normal — wait for the next step change, not a fixed timeout.

## PRD contact form (`estimate-prd`)

When the step is `estimate-prd`, fill the form in the iframe, then click **Request PRD**.

Labels already say `(required)` / `(optional)`; agents should still treat the lists below as authoritative.

**Required (fill all five):**

| Visible label | Notes |
|---------------|--------|
| First name (required) | |
| Surname (required) | |
| Project name (required) | Use a stable project title for the session |
| Email address (required) | Valid email format |
| Home country (required) | |

**Optional (safe to leave blank):**

| Visible label |
|---------------|
| Where did you hear about us? (optional) |
| Feedback or notes (optional) |

If submit is blocked, read the same-origin dialog `chatstack-prd-error` (iframe HTML5 validation is often invisible in the a11y tree). On success, expect `chatstack-prd-success` and/or `data-workflow-step="prd-submitted"`.

## Practices

- Prefer waiting on `data-workflow-step` / `data-next-control` over multi-minute blind sleeps.
- Do not rely on hidden multi-step instruction scripts in the page; unique visible labels and the live-region attributes are the durable hooks.
- Chat content is in `iframe[name="chatkit"]`. Use your tool’s iframe-aware click/type APIs; do not assume top-level `evaluate` can read chat DOM.
- Do not call `GET /api/agent` or `POST /api/agent/submit` as part of this browser flow.

## Related

- Skip-interview Agent API discovery: https://www.chatstack.app/api/agent
- Portal agent API / MCP setup: https://www.portal.chatstack.app/api/agent · https://www.chatstack.app/cursor-ai-prd-integration-guide.md
- Product summary for agents: https://www.chatstack.app/llms.txt
- Full reference: https://www.chatstack.app/llms-full.txt