Manual QA, in the browser you already have open.

You are setting up the Qiksy manual-QA Chrome extension so you can drive the
human's REAL, logged-in browser — over Qiksy's MCP bridge, and (optionally) over
Playwright/CDP for direct clicks. Go ONE STEP AT A TIME. After each step, ask the
human to confirm what they see before continuing. Whenever you send them to a panel
or popup, FIRST DRAW AN ASCII DIAGRAM of it with the exact control marked "← click".

USE GOOGLE CHROME. Qiksy is a Chrome extension — not Firefox, Safari or Edge. Do
everything in Google Chrome (a Chromium build works, but tell the human to use
Chrome unless they know otherwise).

TWO FACTS THAT MAKE OR BREAK IT — state them up front:
  1. The Chrome window must stay OPEN and LOGGED IN to the app under test for the
     whole session. The bridge and Playwright both attach to that live window; close
     it and the session is gone.
  2. To load an UNPACKED (dev) build, the human must be LOGGED IN first — a fresh/
     incognito profile has no session. Log in, THEN load, and keep that window.

STEP 1 — extension
Install Qiksy from the Chrome Web Store, or chrome://extensions → Load unpacked →
the dist folder. Confirm the round Q bubble shows bottom-right on any page.

STEP 2 — the token (DRAW THIS)
Open the toolbar popup and find "Agent bridge · MCP":

  +-- Qiksy popup --------------------+
  | Assistant overlay          [ On ] |
  | Agent bridge · MCP         [ On ] |  <- turn ON, accept the consent
  |   Port [ 7333 ]  Token [________] |
  |   [ Generate ]  [ Copy ]          |  <- Generate, then Copy (it saves itself)
  +-----------------------------------+

Have them Generate -> Copy (the popup saves it automatically), and paste the token to you.

STEP 3 — run the bridge (keep it running in a terminal)
  QIKSY_MCP_TOKEN=<paste the token> npx qiksy-mcp --port 7333

STEP 4 — connect you (MCP)
Add the qiksy server to the agent config (Claude Code: claude mcp add --transport
stdio qiksy --env QIKSY_MCP_TOKEN=<token> -- npx qiksy-mcp --port 7333; or the
.mcp.json block from the site). Restart the agent, then call qa_tabs — it should list
the human's tabs. If it says "not connected", the popup bridge is off or the token/
port differ.

STEP 5 — drop the manual into the project
Run "npx qiksy-mcp init" in the project root. It writes the full agent guide to
.claude/qiksy-bridge.md and adds a short block to CLAUDE.md / AGENTS.md, so every
future session starts knowing what the bridge can do.

STEP 6 — Playwright over CDP (optional, and only for two things)
Qiksy drives the browser itself — clicks, whole forms, calendars, uploads, several
logins. The only gaps are SCREENSHOTS and arbitrary JavaScript. If the task needs one
of those, launch Chrome with --remote-debugging-port=9222 (or reuse the open window),
keep it OPEN and LOGGED IN, and point Playwright MCP at http://localhost:9222.

THEN: qa_tabs -> qa_export (forms with MEANING + live findings) -> drive with
qa_fill_json (a whole step per call) and qa_click by name (needs Pro + "Agent control"
on in the panel). A control that refuses is a ladder, not a wall: qa_probe, raw:true,
qa_pick_*, a CSS selector — never a second browser driver, which would open an empty
browser without these logins. You cannot undo — a click on a real Delete deletes for
real. If a tool says pro-required or consent-required, name the switch the human must
flip, and stop.

You have Qiksy over MCP — a manual-QA extension attached to a REAL Chrome window
with the human's logins already in place. It IS the browser for this session: do not
switch to Playwright, Puppeteer, Selenium or CDP because a control looked unfamiliar
or refused once. Another driver opens a DIFFERENT, EMPTY browser — none of these
logins are in it, so the run stops being the test that was asked for. Exactly two
things are absent here: screenshots (no pixels) and arbitrary JavaScript (no eval, a
Web Store rule). Need one? Say which, and let the human decide.

Start with:
  qa_tabs      — which tabs are in the agent session, which are isolated logins
                 (every tool takes tabId)
  qa_snapshot  — the page as an accessibility tree with stable refs; fields_only on a
                 heavy app, geometry:true for every box in CSS pixels
  qa_export    — forms with MEANING (kind: "email" / "card-number" / "first-name"),
                 findings, failed requests WITH the server's error body, repro steps
                 and a NAVIGATION map (labelled routes, current:true on the open page)

Don't scrape the DOM yourself — qa_export already knows what each field is and where
the app can go. Pick a route from navigation[] and go by href instead of probe-clicking.

A FORM IS ONE CALL PER STEP, never one per field (needs Pro + "Agent control"):
  qa_fill_json { fields: { "Full name": "Ada Lovelace", "Country": "Ukraine",
                           "Start date": "06/11/2024", "I agree": true },
                 advance: "Next" }
It resolves the labels itself, drives custom dropdowns, calendars, cascaders, trees,
tags and time pickers, and presses Next ONLY if every entry landed. Keys that matched
nothing come back with the page's real field names, so your next call fixes itself.

WHEN A CONTROL REFUSES — the ladder, in order. Don't change tool, change rung:
  qa_probe { name }        what this widget is and which verb drives it
  raw: true                write the value straight into its own text input
  qa_pick_date / _time / _range / _path (cascader, tree) / _tags
  a CSS selector           every verb takes one; a portalled popup with no roles
                           (Ant) is MEANT to be driven that way
  qa_click { name }        then read the "widget" verdict in the reply and act on it
  qa_focus_tab             custom popovers only render in the FOREGROUND tab

AFTER ANYTHING THAT NAVIGATES call qa_wait_ready, and press the advance control by
NAME, not by a ref you took before filling: any new snapshot renumbers refs, so an old
one succeeds on the WRONG control. This is the most common way a run goes wrong.

Several logins at once:
  qa_open_isolated { url, sessions: ["admin","member"] }  → one cookie jar per tab
  qa_close_tab { tabIds: [...] }                          → clean up
SSO works — Microsoft, Google, Okta: it is their own browser, and a tab the provider
opens joins the session automatically. A captcha or a 2FA prompt is theirs: stop and say so.

Saw a long form? qa_recipe_save { name } — the next run replays it a call per step.

Finish with qa_report { path, spec: { title, story, checks:[{id,text,status,evidence}] } }
— a self-contained HTML file led by YOUR verdicts next to Qiksy's evidence.

You cannot undo. A click on a real Delete button deletes for real. If a tool says
pro-required / consent-required, that is a switch the human must flip — say which
one and stop.