patchright-cli 0.6.0__tar.gz → 0.7.0__tar.gz

{patchright_cli-0.6.0 → patchright_cli-0.7.0}/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Anti-detect browser automation CLI & Skills for AI agents, powered by Patchright",
-    "version": "0.5.0"
+    "version": "0.7.0"
   },
   "plugins": [
     {

{patchright_cli-0.6.0 → patchright_cli-0.7.0}/.gitignore

@@ -8,3 +8,5 @@ build/
 docs/reddit-post.md
 docs/superpowers/
 .worktrees/
+.claude/settings.local.json
+=*

{patchright_cli-0.6.0 → patchright_cli-0.7.0}/CLAUDE.md

@@ -57,10 +57,10 @@ CLI (cli.py) --TCP:9321--> Daemon (daemon.py) --Patchright--> Chrome
 
 - Always uses persistent browser context (`launch_persistent_context`) with real Chrome (`channel="chrome"`), not Chromium
 - Headed by default (headless is more detectable)
-- Default daemon port: 9321, profiles stored at `~/.patchright-cli/profiles/<session-name>`
+- Default daemon port: 9321, profiles stored at `~/.patchright-cli/profiles/<profile-name>`; a session's profile defaults to its session name (`--profile=<name>` overrides, a value with `/` or `\` is a directory). One session per profile at a time
 - CLI-daemon protocol: length-prefixed (4-byte big-endian `!I`) JSON over TCP
 - CLI parses argv manually in `main()` — click is only used for `click.echo()`, not subcommands. New commands must be added to both `COMMANDS_HELP` dict and the `handle_command()` if/elif chain in daemon.py
-- Version must be updated in both `pyproject.toml` and `src/patchright_cli/__init__.py` (then run `uv lock` to sync the lock file)
+- Version must be updated in `pyproject.toml`, `src/patchright_cli/__init__.py` and `.claude-plugin/marketplace.json` (then run `uv lock` to sync the lock file; `tests/test_packaging.py` checks they match)
 - `python -m patchright_cli` works via `__main__.py`
 - Uses hatchling as build backend, ruff for linting (line-length=120, target py310)
 - Ruff rules: E, F, I, W, UP, B, SIM (ignores E501, SIM105, E402)

patchright_cli-0.7.0/GLOSSARY.md

@@ -0,0 +1,58 @@
+# patchright-cli
+
+An anti-detect browser automation CLI: callers drive real Chrome through short commands sent to a long-running daemon.
+
+## Sessions and browsers
+
+**Session**:
+A named handle on one browser context that callers drive with commands; selected with `-s`.
+_Avoid_: Browser, instance, profile
+
+**Default Session**:
+The Session used when no `-s` is given.
+
+**Launched Session**:
+A Session whose Chrome patchright-cli started itself and therefore owns outright.
+
+**Profile**:
+A named, persistent store of browser state — cookies, storage, logins, history — that a Launched Session runs on; at most one Session uses a Profile at a time. Unless told otherwise, a Session's Profile is named after the Session.
+_Avoid_: User data dir, profile directory, persistent context
+
+**Attached Session**:
+A Session connected to a Chrome that something else started, reached over CDP.
+_Avoid_: Connected session, remote session
+
+**Host**:
+Whatever started and owns the Chrome an Attached Session connects to — a person, a script, or a product such as a workspace manager.
+_Avoid_: External browser, owner
+
+**Host Context**:
+The Host's own browser context, carrying its profile's cookies, storage and logins; at most one Session may use a given Host Context.
+_Avoid_: Default context, existing context, persistent context
+
+**Isolated Context**:
+A fresh browser context an Attached Session creates inside the Host's Chrome, sharing none of the Host's state.
+_Avoid_: Incognito context
+
+## Tabs and pages
+
+**Page**:
+One browser tab as Chrome sees it.
+_Avoid_: Tab (except in the playwright-cli-compatible `tab-*` command names, which act on Pages)
+
+**Tab**:
+A named workspace inside a Session — its own Page, element refs and navigation history — selected with `--tab`.
+_Avoid_: Lane, worker
+
+**Default Tab**:
+The Tab used when no `--tab` is given; it follows whichever Page is currently selected rather than owning one.
+
+## Ending a Session
+
+**Close**:
+Ending a Session by destroying what it owns: its Tabs' Pages and, for a context it owns, the context itself.
+_Avoid_: Quit, kill (except `kill-all`)
+
+**Detach**:
+Letting go of an Attached Session while leaving the Host's Chrome, and anything the Host owns, untouched.
+_Avoid_: Disconnect, release

{patchright_cli-0.6.0 → patchright_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: patchright-cli
-Version: 0.6.0
+Version: 0.7.0
 Summary: Anti-detect browser automation CLI using Patchright (undetected Playwright fork)
 Project-URL: Homepage, https://github.com/AhaiMk01/patchright-cli
 Project-URL: Repository, https://github.com/AhaiMk01/patchright-cli
@@ -149,7 +149,7 @@ graph LR
 |-----------|------|
 | **Daemon** (`daemon.py`) | Long-running process managing browser sessions via Patchright. Auto-starts on first `open`. |
 | **CLI** (`cli.py`) | Thin client — connects, sends command, prints result, disconnects. Browser stays open. |
-| **Snapshot** (`snapshot.py`) | `TreeWalker`-based DOM scan assigning `data-patchright-ref` attributes for element targeting. |
+| **Snapshot** (`snapshot.py`) | Playwright `aria_snapshot()` accessibility tree, annotated with sequential `[ref=eN]` handles for element targeting. |
 
 ---
 
@@ -159,9 +159,12 @@ graph LR
 ### Core
 ```bash
 patchright-cli open [url]              # Launch browser
-patchright-cli open --persistent       # With persistent profile
+patchright-cli open --profile=work     # Named profile any session can use (logins persist)
 patchright-cli open --headless         # Run headless
-patchright-cli open --profile=<path>   # Custom profile directory
+patchright-cli open --profile=./dir    # A value with / or \ is a profile directory
+patchright-cli --tab <name> open <url> # Named tab: shared browser, own page/refs
+patchright-cli open --mobile           # Emulate a generic mobile device (Pixel 7)
+patchright-cli open --device="Pixel 5" # Emulate a specific Playwright device
 patchright-cli goto <url>              # Navigate
 patchright-cli click <ref>             # Click element
 patchright-cli click <ref> right       # Right-click
@@ -180,8 +183,13 @@ patchright-cli drag <from> <to>        # Drag and drop
 patchright-cli snapshot                # Accessibility snapshot
 patchright-cli snapshot -i             # Interactive elements only (recommended)
 patchright-cli snapshot --depth=3      # Limit depth
+patchright-cli snapshot --selector=CSS  # Snapshot a CSS-scoped subtree
 patchright-cli snapshot <ref>          # Snapshot element subtree
 patchright-cli snapshot --filename=f   # Save to custom path
+patchright-cli find "text"             # Search snapshot for text
+patchright-cli find --regex "a|b"      # Search by regex
+patchright-cli find "text" --all       # Include text/paragraph nodes
+patchright-cli find "text" --limit=50  # Cap hits (default 20)
 patchright-cli eval <expr>             # Run JavaScript
 patchright-cli eval --file=script.js   # Run JS from file
 patchright-cli run-code <code>         # Run JS with return value
@@ -190,6 +198,7 @@ patchright-cli screenshot              # Page screenshot
 patchright-cli screenshot --full-page  # Full scrollable page
 patchright-cli screenshot <ref>        # Element screenshot
 patchright-cli screenshot --filename=f # Save to custom path
+patchright-cli screenshot --hires      # Capture at device pixel ratio
 patchright-cli close                   # Close session
 ```
 
@@ -198,6 +207,10 @@ patchright-cli close                   # Close session
 patchright-cli go-back
 patchright-cli go-forward
 patchright-cli reload
+patchright-cli wait 500                 # Wait a fixed number of milliseconds
+patchright-cli wait --url="**/dashboard" # Wait for the URL to match (`*` never crosses a `/`)
+patchright-cli wait-for <ref>           # Wait until an element is visible
+patchright-cli wait-for <ref> --state=hidden
 ```
 
 ### Keyboard / Mouse
@@ -285,6 +298,9 @@ patchright-cli tracing-stop            # Saves .zip trace file
 patchright-cli video-start             # Start video recording (CDP screencast)
 patchright-cli video-stop              # Stop and save video (requires ffmpeg for .webm)
 patchright-cli video-stop --filename=recording.webm
+patchright-cli show --annotate          # Ask a human to mark up the page, wait for it
+patchright-cli video-show-actions       # Annotate each action in the recording
+patchright-cli video-hide-actions       # Stop annotating actions
 patchright-cli pdf --filename=page.pdf
 ```
 
@@ -317,13 +333,15 @@ patchright-cli install --skills        # Auto-install skills for detected AI age
 
 ### Sessions
 ```bash
-patchright-cli -s=mysession open https://example.com --persistent
+patchright-cli -s=mysession open https://example.com
 patchright-cli -s=mysession click e6
 patchright-cli -s=mysession close
 patchright-cli list                    # List all sessions
 patchright-cli close-all
 patchright-cli kill-all
-patchright-cli delete-data             # Delete persistent profile
+patchright-cli delete-data             # Delete the profile named after the session
+patchright-cli profile-list           # Profiles, size, and which session uses each
+patchright-cli profile-delete <name>  # Delete an idle named profile
 patchright-cli --port=9322 open        # Custom daemon port
 ```
 

{patchright_cli-0.6.0 → patchright_cli-0.7.0}/README.md

@@ -116,7 +116,7 @@ graph LR
 |-----------|------|
 | **Daemon** (`daemon.py`) | Long-running process managing browser sessions via Patchright. Auto-starts on first `open`. |
 | **CLI** (`cli.py`) | Thin client — connects, sends command, prints result, disconnects. Browser stays open. |
-| **Snapshot** (`snapshot.py`) | `TreeWalker`-based DOM scan assigning `data-patchright-ref` attributes for element targeting. |
+| **Snapshot** (`snapshot.py`) | Playwright `aria_snapshot()` accessibility tree, annotated with sequential `[ref=eN]` handles for element targeting. |
 
 ---
 
@@ -126,9 +126,12 @@ graph LR
 ### Core
 ```bash
 patchright-cli open [url]              # Launch browser
-patchright-cli open --persistent       # With persistent profile
+patchright-cli open --profile=work     # Named profile any session can use (logins persist)
 patchright-cli open --headless         # Run headless
-patchright-cli open --profile=<path>   # Custom profile directory
+patchright-cli open --profile=./dir    # A value with / or \ is a profile directory
+patchright-cli --tab <name> open <url> # Named tab: shared browser, own page/refs
+patchright-cli open --mobile           # Emulate a generic mobile device (Pixel 7)
+patchright-cli open --device="Pixel 5" # Emulate a specific Playwright device
 patchright-cli goto <url>              # Navigate
 patchright-cli click <ref>             # Click element
 patchright-cli click <ref> right       # Right-click
@@ -147,8 +150,13 @@ patchright-cli drag <from> <to>        # Drag and drop
 patchright-cli snapshot                # Accessibility snapshot
 patchright-cli snapshot -i             # Interactive elements only (recommended)
 patchright-cli snapshot --depth=3      # Limit depth
+patchright-cli snapshot --selector=CSS  # Snapshot a CSS-scoped subtree
 patchright-cli snapshot <ref>          # Snapshot element subtree
 patchright-cli snapshot --filename=f   # Save to custom path
+patchright-cli find "text"             # Search snapshot for text
+patchright-cli find --regex "a|b"      # Search by regex
+patchright-cli find "text" --all       # Include text/paragraph nodes
+patchright-cli find "text" --limit=50  # Cap hits (default 20)
 patchright-cli eval <expr>             # Run JavaScript
 patchright-cli eval --file=script.js   # Run JS from file
 patchright-cli run-code <code>         # Run JS with return value
@@ -157,6 +165,7 @@ patchright-cli screenshot              # Page screenshot
 patchright-cli screenshot --full-page  # Full scrollable page
 patchright-cli screenshot <ref>        # Element screenshot
 patchright-cli screenshot --filename=f # Save to custom path
+patchright-cli screenshot --hires      # Capture at device pixel ratio
 patchright-cli close                   # Close session
 ```
 
@@ -165,6 +174,10 @@ patchright-cli close                   # Close session
 patchright-cli go-back
 patchright-cli go-forward
 patchright-cli reload
+patchright-cli wait 500                 # Wait a fixed number of milliseconds
+patchright-cli wait --url="**/dashboard" # Wait for the URL to match (`*` never crosses a `/`)
+patchright-cli wait-for <ref>           # Wait until an element is visible
+patchright-cli wait-for <ref> --state=hidden
 ```
 
 ### Keyboard / Mouse
@@ -252,6 +265,9 @@ patchright-cli tracing-stop            # Saves .zip trace file
 patchright-cli video-start             # Start video recording (CDP screencast)
 patchright-cli video-stop              # Stop and save video (requires ffmpeg for .webm)
 patchright-cli video-stop --filename=recording.webm
+patchright-cli show --annotate          # Ask a human to mark up the page, wait for it
+patchright-cli video-show-actions       # Annotate each action in the recording
+patchright-cli video-hide-actions       # Stop annotating actions
 patchright-cli pdf --filename=page.pdf
 ```
 
@@ -284,13 +300,15 @@ patchright-cli install --skills        # Auto-install skills for detected AI age
 
 ### Sessions
 ```bash
-patchright-cli -s=mysession open https://example.com --persistent
+patchright-cli -s=mysession open https://example.com
 patchright-cli -s=mysession click e6
 patchright-cli -s=mysession close
 patchright-cli list                    # List all sessions
 patchright-cli close-all
 patchright-cli kill-all
-patchright-cli delete-data             # Delete persistent profile
+patchright-cli delete-data             # Delete the profile named after the session
+patchright-cli profile-list           # Profiles, size, and which session uses each
+patchright-cli profile-delete <name>  # Delete an idle named profile
 patchright-cli --port=9322 open        # Custom daemon port
 ```
 

{patchright_cli-0.6.0 → patchright_cli-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "patchright-cli"
-version = "0.6.0"
+version = "0.7.0"
 description = "Anti-detect browser automation CLI using Patchright (undetected Playwright fork)"
 license = "Apache-2.0"
 requires-python = ">=3.10"

{patchright_cli-0.6.0 → patchright_cli-0.7.0}/skills/patchright-cli/SKILL.md

@@ -9,6 +9,14 @@ patchright-cli drives a real Chrome browser that passes bot detection (Cloudflar
 
 ## Quick start
 
+If `patchright-cli` is not on PATH yet, install it first -- one of:
+
+```bash
+uvx patchright-cli --version                 # run without installing
+pip install patchright-cli                   # or install it
+python -m patchright install chromium        # then fetch the browser, once
+```
+
 ```bash
 patchright-cli open https://example.com     # launch browser + navigate
 patchright-cli snapshot                      # get element refs
@@ -35,33 +43,63 @@ patchright-cli snapshot          # read refs from output
 patchright-cli click e5          # use discovered ref
 ```
 
+## Shell quoting
+
+Quote any URL containing `&`. Unquoted, the shell eats it before patchright-cli
+sees it:
+
+```bash
+# WRONG -- PowerShell 7 treats `&` as the background operator: the command is
+# detached and everything after `&` is run as a separate command.
+# cmd.exe treats it as a command separator. Either way the URL is truncated.
+patchright-cli goto https://example.com/search?q=cats&page=2
+
+# RIGHT -- on any shell
+patchright-cli goto "https://example.com/search?q=cats&page=2"
+```
+
+The same applies to `#` (a bash comment), spaces, and `%` (expanded by
+cmd.exe), and to any argument holding shell metacharacters. Quoting always
+works; leave it on.
+
 ## Global options
 
 These go before the command:
 
 ```bash
 --headless              # Run headless (default: headed -- headed is less detectable)
---persistent            # Use persistent profile (keeps cookies/storage across sessions)
---profile=/path         # Custom profile directory
+--profile=<name>        # Named profile any session can use (default: the session name);
+                        # profiles always persist. A value with / or \ is a directory
 --proxy=<url>           # Proxy server (http, https, socks5) -- supports user:pass@host auth
 -s=mysession            # Named session (default: "default", or PATCHRIGHT_CLI_SESSION env var)
 --port=9322             # Custom daemon port (default: 9321)
 --config=<path>         # Load options from JSON config file
 --cdp=<url>             # Attach to Chrome via CDP endpoint (use with `attach` command)
+--context=new|host      # With `attach`: fresh isolated context (default) or the browser's own
 --device="iPhone 15"    # Emulate a device
+--mobile                # Emulate a generic mobile device (Pixel 7); mobile pages
+                        # are lighter, so snapshots are smaller and cheaper
 --viewport-size=1280x720 # Set viewport size
 --locale=en-US          # Browser locale
 --timezone=America/New_York # Timezone ID
 --geolocation=40.7,-74.0   # Geolocation override (lat,lon)
 --user-agent=<ua>       # Custom user agent string
 --grant-permissions=geolocation,camera  # Grant permissions at launch
---timeout-action=10000  # Default action timeout (ms)
---timeout-navigation=30000 # Default navigation timeout (ms)
 --show-port=9322        # Dashboard port (default: 9322)
 --raw                   # Strip page/snapshot decorations from output
 --json                  # Wrap full response as JSON ({success, output, ...})
 ```
 
+These go *after* the command instead:
+
+```bash
+--timeout=1800          # Daemon idle timeout in seconds before it exits and
+                        # takes the browser (and its login) with it. Default 1800.
+                        # Also settable up front via $PATCHRIGHT_CLI_IDLE_TIMEOUT.
+--timeout-action=10000  # Default action timeout (ms)
+--timeout-navigation=30000 # Default navigation timeout (ms)
+```
+
 ---
 
 ## Core commands
@@ -70,10 +108,11 @@ These go before the command:
 
 ```bash
 open [url]                    # Launch browser (optionally navigate)
-open --persistent             # Keep cookies/storage between runs
+open --profile=work           # Run on a named profile (logins persist; one session at a time)
 open --headless               # Headless mode
-attach --cdp=<url>            # Attach to existing Chrome via CDP
-close                         # Close session (closes the browser)
+attach --cdp=<url>            # Attach to existing Chrome via CDP (fresh, isolated context)
+attach --cdp=<url> --context=host  # Use the Host Context: the browser's own logins, cookies, storage
+close                         # Close session (closes the browser); refused on --context=host -- use detach
 detach                        # Detach an attached session (keeps external browser running)
 ```
 
@@ -92,11 +131,47 @@ title                         # Print page title
 ```bash
 snapshot                      # Full page snapshot
 snapshot <ref>                # Subtree of a specific element
+snapshot --selector="#main"   # Subtree of a CSS selector -- must match exactly
+                              # one element. No ref needed, so
+                              # this works before the first snapshot
 snapshot --depth=N            # Limit depth
 snapshot -i                   # Interactive elements only
 snapshot --boxes              # Append [box=x,y,w,h] to each [ref=eN] line
 ```
 
+### Searching instead of snapshotting
+
+On a large page, `find` is the cheaper first move — a full snapshot of a
+Wikipedia article is ~87k tokens; `find` returns a few hundred.
+
+```bash
+patchright-cli find "Sign in"              # substring, case-insensitive
+patchright-cli find --regex "sign (in|up)" # regex, case-insensitive
+patchright-cli find --regex "/Sign In/"    # slash form carries flags (i, m, s)
+patchright-cli find "price" --all          # include text/paragraph nodes
+patchright-cli find "hide" --limit=50      # default limit is 20
+```
+
+`find` searches links, buttons, inputs and headings by default — the things
+you can act on. Use `--all` when you are looking for page *content* rather
+than a control.
+
+Each hit prints a `#` breadcrumb showing where it sits, so identical
+controls stay distinguishable:
+
+```
+  # table > rowgroup > cell "407 points by pluc 4 hours ago | hide | 321 ..."
+- link "hide": [ref=e49]
+  - /url: hide?id=49489982
+```
+
+Refs from `find` are numbered across the whole page and are immediately
+usable with `click`, `fill`, and the rest. They stay valid until the next
+`snapshot` or `find`.
+
+When output says `Found 20 of 340 matches`, narrow the query rather than
+raising `--limit`.
+
 ### Interaction
 
 ```bash
@@ -138,6 +213,9 @@ screenshot --filename=F       # Custom filename
 scroll <dx> <dy>              # Scroll by pixels
 scroll-to <ref>               # Scroll element into view
 wait <ms>                     # Wait N milliseconds
+wait --url="**/dashboard"     # Wait until the URL matches -- the right tool
+                              # after a login or any redirect. `*` does NOT
+                              # cross a `/`, so use `**`; `/regex/i` also works
 wait-for <ref>                # Wait until element visible
 wait-for <ref> --state=hidden # Wait until hidden
 press <key>                   # Keypress (Enter, ArrowDown, etc.)
@@ -157,10 +235,51 @@ mousewheel <dx> <dy>          # Scroll wheel
 ```bash
 tab-list                      # List open tabs
 tab-new <url>                 # Open new tab
-tab-select <index>            # Switch to tab
-tab-close [index]             # Close tab
+tab-select <index>            # Switch to tab (default tab only; a --tab
+                              # caller is pinned to its own page)
+tab-close [index]             # Close tab (with --context=host, only tabs this session opened)
+```
+
+### Parallel agents: --tab
+
+`--tab <name>` gives a caller its own page, its own refs and its own history
+inside one shared browser -- same fingerprint, same cookies, same login. It is
+the cheap way to parallelise: one Chrome total, not one per agent.
+
+```bash
+patchright-cli --tab inbox-scan open https://app.example.com/inbox
+patchright-cli --tab report-pull open https://app.example.com/reports
+patchright-cli --tab inbox-scan snapshot     # refs belong to this tab only
+patchright-cli tab-list                      # every tab, labelled by owner
+patchright-cli --tab inbox-scan close        # frees this tab; browser stays
+```
+
+**Choose the name once, with a shell-generated suffix.** Nothing enforces
+uniqueness -- two agents on the same name share one page and clobber each
+other. Do not invent the random part yourself; LLM-chosen "random" characters
+collide.
+
+```bash
+TAB="price-scan-$(openssl rand -hex 2)" && echo "$TAB"
+patchright-cli --tab "$TAB" open https://example.com
+# reuse that exact printed name in every later command
 ```
 
+`$PATCHRIGHT_CLI_TAB` sets it for a whole shell, the way `$PATCHRIGHT_CLI_SESSION`
+does for sessions.
+
+Cleanup needs no coordination: every agent runs `close` addressed to its own
+tab, and the browser exits when the last tab goes. On an `attach --context=host`
+session the host's browser never exits: closing tabs leaves it attached, and
+whoever attached runs `detach` at the end.
+
+**`--tab` vs `-s`.** `--tab` shares identity, one browser (~50-150MB per extra
+tab), for agents acting as the same logged-in user. `-s` isolates identity --
+its own profile, cookies and fingerprint, a full Chrome each (~300-500MB) --
+for multi-account work. Tabs share one browser process, so commands from
+different tabs queue behind a slow navigation; separate sessions run fully in
+parallel.
+
 ### Dialogs
 
 Dialogs must be pre-armed *before* the action that triggers them:
@@ -191,11 +310,14 @@ highlight <ref> --hide        # Remove overlay; `highlight --hide` clears all
 ```bash
 screenshot / pdf              # Static capture
 video-start / video-stop      # Video recording
+video-show-actions            # Label each action in the recording [--duration=ms] [--position=P]
+video-hide-actions            # Stop labelling actions
 tracing-start / tracing-stop  # Playwright trace
 codegen / codegen-stop        # Record interactions as script
 resize <w> <h>                # Viewport resize
 upload <file> [ref]           # File upload
 show                          # Live dashboard
+show --annotate               # Ask a human to mark up the page and wait for it
 ```
 
 ### Storage
@@ -224,6 +346,8 @@ list                          # List active sessions
 close-all                     # Close all sessions
 kill-all                      # Force-kill all + stop daemon
 delete-data                   # Delete session profile data
+profile-list                  # List profiles, size, and which session uses each
+profile-delete <name>         # Delete an idle named profile
 grant-permissions <perms>     # Grant browser permissions
 ```
 
@@ -234,13 +358,13 @@ grant-permissions <perms>     # Grant browser permissions
 ### Login flow
 
 ```bash
-patchright-cli open https://example.com/login --persistent
+patchright-cli open --profile=myapp https://example.com/login
 patchright-cli snapshot
 patchright-cli fill e3 "user@example.com"
 patchright-cli fill e5 "password123"
 patchright-cli click e8
 patchright-cli snapshot
-# With --persistent, cookies survive across sessions
+# The login persists in profile "myapp" for any later session that opens it
 ```
 
 ### Extracting data
@@ -278,11 +402,35 @@ patchright-cli click e5                   # This click triggers the dialog
 ```bash
 patchright-cli wait-for e12               # Wait for element
 patchright-cli wait 1000                  # Fixed wait
+patchright-cli wait --url="**/dashboard"  # Wait for a redirect to land
 # For custom conditions, use run-code (see references/running-code.md)
 ```
 
 ---
 
+## Asking a human what to change
+
+`show --annotate` is for design and UI review: it opens a page in the user's
+browser showing a live capture of the current page, they draw on it and write
+what they want changed, and the command returns their drawing plus their notes.
+
+```bash
+patchright-cli show --annotate                  # waits up to 5 minutes
+patchright-cli show --annotate --wait=900       # give them longer
+patchright-cli show --annotate --no-open        # headless box: do not launch a browser
+```
+
+The command **blocks** until they submit, so it opens the review link for them
+rather than printing it. The link is also written to
+`.patchright-cli/annotate-url.txt`, which is how you get it when `--no-open`
+suppressed the browser. You get back the annotated screenshot saved under
+`.patchright-cli/`, their notes, and a fresh snapshot of the page -- enough to
+act on the feedback without asking follow-up questions.
+
+Reach for it when the decision is aesthetic or subjective and you would
+otherwise be guessing: which of two layouts, where an element belongs, whether
+spacing reads right. Do not use it for anything you can check yourself.
+
 ## Anti-detect notes
 
 - Uses real Chrome (not Chromium) -- this is what makes it undetectable
@@ -291,7 +439,8 @@ patchright-cli wait 1000                  # Fixed wait
 - No custom user-agent or headers by default -- preserves Chrome's natural fingerprint
 - Persistent profiles maintain realistic browser history and cookies
 - The daemon architecture means Chrome stays running between commands, behaving like a real user's browser
-- `attach --cdp` lets you connect to an existing Chrome instance
+- `attach --cdp` lets you connect to an existing Chrome instance; add `--context=host` to reuse its logins,
+  cookies and storage (see references/session-management.md)
 
 ## Config files
 
@@ -339,6 +488,16 @@ pip install patchright-cli && patchright-cli install --skills
 # "Install patchright-cli skill from https://raw.githubusercontent.com/AhaiMk01/patchright-cli/main/skills/patchright-cli/SKILL.md"
 ```
 
+When an installed copy of this skill drifts from the tool version,
+patchright-cli prints a one-line warning on stderr -- once a day per
+version, so a chained run is not buried in it. Re-run
+`patchright-cli install --skills` to resync, or set
+`PATCHRIGHT_CLI_NO_SKILL_CHECK=1` to silence the check.
+
+`open` also checks PyPI once a day for a newer patchright-cli and prints a
+one-line note when there is one. Set `PATCHRIGHT_CLI_NO_VERSION_CHECK=1` to
+turn that off.
+
 ## Specific tasks
 
 * **Snapshots and element refs** [references/snapshot-refs.md](references/snapshot-refs.md)