manigent-server 0.1.0__py3-none-any.whl

manigent/_catalog/skills/photo-story/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: photo-story
+description: >
+  Build animated, single-file HTML "year story" / "trip story" / "milestone story"
+  artifacts from a photo library — Spotify-Wrapped / Apple-Memories style
+  scrollytelling, code-driven motion, plays straight from file://. Also covers
+  the curator-side funnel for getting from 1k–10k photos down to ~50 keepers
+  without melting context. Use when an agent needs to produce a multi-photo
+  narrative artifact OR when triaging a large photo library.
+---
+
+# Photo Story
+
+Two modes in one skill — pick the half you need:
+
+- **Curator mode** (volume → keepers): turn a year's worth of photos into a
+  small, intentional shortlist. Runs locally; never hands the full library to
+  the model.
+- **Bookmaker mode** (keepers → artifact): turn that shortlist into a
+  single-file animated HTML story you can text to family or open in a
+  browser without any build step.
+
+---
+
+## Curator mode: from a thousand photos to fifty
+
+A "best of 2025" album is typically 1k–10k photos. You cannot read them all
+into vision context — token cost is prohibitive and the model can't reason
+over that many at once anyway. **List metadata first, look at images last.**
+
+### Step 1 — Discover the source
+
+Two photo sources are supported. Pick whichever the user has:
+
+**Filesystem folder** (e.g. an iCloud Drive folder mounted at
+`~/Library/Mobile Documents/com~apple~CloudDocs/Photos/2025`): the agent's
+`knowledge_dir` already points at it. Walk the directory and read EXIF.
+
+```python
+# Run this as a Bash one-liner; faster than reading per-file from Python.
+exiftool -j -r -DateTimeOriginal -GPSLatitude -GPSLongitude -ImageWidth \
+  -ImageHeight -FileName "/path/to/folder" > /tmp/exif.json
+```
+
+If `exiftool` isn't installed, fall back to `Pillow`:
+
+```python
+from PIL import Image, ExifTags
+from pathlib import Path
+import json
+
+rows = []
+for p in Path("/path/to/folder").rglob("*"):
+    if p.suffix.lower() not in (".jpg", ".jpeg", ".heic", ".png"):
+        continue
+    try:
+        img = Image.open(p)
+        exif = {ExifTags.TAGS.get(k, k): v for k, v in (img._getexif() or {}).items()}
+    except Exception:
+        exif = {}
+    rows.append({
+        "path": str(p),
+        "date": exif.get("DateTimeOriginal"),
+        "gps": exif.get("GPSInfo"),
+        "size": f"{img.width}x{img.height}" if hasattr(img, "width") else None,
+    })
+```
+
+**Apple Photos album** (e.g. an album called "2025" inside Photos.app,
+synced via iCloud Photo Library): use the `photos` MCP. Photos.app's
+`Photos Library.photoslibrary` is an opaque package; the MCP wraps
+`osxphotos` to query it.
+
+```
+photos.list_albums()                              → pick the right album
+photos.list_photos(album="2025", year=2025)        → metadata + paths, no bytes
+```
+
+### Step 2 — Cluster into events
+
+Don't bucket by calendar week — bucket by what actually happened. Two
+photos within ~2 hours and ~500 m of each other are part of the same event
+(brunch, hike, dinner). A photo with no GPS plus a 6-hour gap from the next
+shot likely starts a new event.
+
+```python
+def cluster_events(rows):
+    rows = sorted(rows, key=lambda r: r["date"])
+    events, current = [], []
+    for r in rows:
+        if not current:
+            current = [r]; continue
+        gap_hours = (r["dt"] - current[-1]["dt"]).total_seconds() / 3600
+        moved = (r.get("gps") and current[-1].get("gps")
+                 and haversine(r["gps"], current[-1]["gps"]) > 0.5)
+        if gap_hours > 2 or moved:
+            events.append(current); current = []
+        current.append(r)
+    if current: events.append(current)
+    return events
+```
+
+Aim for 30–80 events for a typical year. Fewer means under-clustered (a
+trip will swallow surrounding moments); more means over-fragmented.
+
+### Step 3 — Sample-vision per event
+
+For each event, take **at most 3 candidate photos** (e.g. first, middle,
+favorite by user-tag) and read those via the Read tool. Score them on:
+
+- People in frame (faces beat scenery for memory recall)
+- Sharpness (drop the obvious blurs)
+- Specificity (a labeled shopfront beats yet another sunset)
+
+Pick the strongest 1–2 per event. Skip events that are visually thin
+(receipts, screenshots, repeated room shots).
+
+### Step 4 — Funnel to ~50
+
+Total budget: ~50 photos for a year-in-review. If clustering gave 60
+events and you picked ~1 per event, you're done. If it gave 30 events
+because the year was quiet, take 1–2 from each strong event and stop.
+
+**Cull mercilessly.** "Best 50 of 2025" is a feature, not a constraint.
+
+### Step 5 — Write captions
+
+One sentence per photo. Anchor it to the small, forgettable detail (the
+restaurant name, the trail, the inside joke). Match the owner's voice
+from prior writing — terse, warm, dry, sentimental, whatever fits. Read
+each aloud; if it sounds like a greeting card, rewrite it.
+
+---
+
+## Bookmaker mode: animated single-file HTML
+
+Output a `.html` file that opens straight from `file://`. No build step,
+no server. Photos embedded as base64 by default for shareability.
+
+### Architecture
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>2025 — Year Story</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/ScrollTrigger.min.js"></script>
+  <style>
+    html { scroll-behavior: smooth; scroll-snap-type: y mandatory; }
+    section { scroll-snap-align: start; min-height: 100vh; }
+    .photo { transition: transform 0.6s ease, opacity 0.6s ease; }
+    .photo.in-view { transform: scale(1) translateY(0); opacity: 1; }
+    .photo.out-of-view { transform: scale(0.95) translateY(20px); opacity: 0; }
+  </style>
+</head>
+<body class="bg-black text-white font-sans antialiased">
+  <!-- One <section> per chapter (intro, season, milestone, outro) -->
+  <section class="flex flex-col items-center justify-center text-center p-8">
+    <h1 class="text-7xl font-bold tracking-tight">2025</h1>
+    <p class="text-xl text-gray-400 mt-4">A year, in pictures.</p>
+  </section>
+
+  <section class="grid grid-cols-1 md:grid-cols-2 gap-4 p-8 items-center">
+    <img src="data:image/jpeg;base64,..." class="photo rounded-lg shadow-2xl">
+    <div>
+      <h2 class="text-4xl font-semibold">Spring</h2>
+      <p class="text-gray-300 mt-4">Caption here.</p>
+    </div>
+  </section>
+
+  <!-- ... -->
+
+  <script>
+    gsap.registerPlugin(ScrollTrigger);
+    gsap.utils.toArray("section img.photo, section h2").forEach((el) => {
+      gsap.from(el, {
+        opacity: 0,
+        y: 40,
+        duration: 0.8,
+        scrollTrigger: { trigger: el, start: "top 80%" },
+      });
+    });
+  </script>
+</body>
+</html>
+```
+
+### CDN libraries (no install needed)
+
+| Library | CDN | Use |
+|---|---|---|
+| Tailwind CSS | `cdn.tailwindcss.com` | Layout + typography |
+| GSAP + ScrollTrigger | `cdn.jsdelivr.net/npm/gsap@3.12.5` | Scroll-triggered motion |
+| Lottie | `cdn.jsdelivr.net/npm/lottie-web` | After Effects-style accents (optional) |
+| Three.js | `cdn.jsdelivr.net/npm/three@0.160` | 3D / spatial moments (optional) |
+
+You don't need React for this — it's a one-shot, scroll-driven page.
+Keep the JS tiny.
+
+### Image embedding: base64 by default
+
+Inline photos as base64 data URIs. The HTML is bigger (~33% overhead) but
+it's a single file the user can text, AirDrop, or email.
+
+```python
+import base64, mimetypes, json
+from pathlib import Path
+
+def encode(p: Path) -> str:
+    mime, _ = mimetypes.guess_type(p.name)
+    b64 = base64.b64encode(p.read_bytes()).decode("ascii")
+    return f"data:{mime or 'image/jpeg'};base64,{b64}"
+```
+
+For 50 photos at ~500 KB each → roughly 25 MB inline. That's fine for
+single-file sharing. Above 100 photos, switch to **linked mode**: keep
+photos in a sibling `assets/` folder and use relative `<img src="assets/...">`.
+Document the mode used with an HTML comment at the top of the file:
+
+```html
+<!-- mode: linked  (photos in ./assets/, must be sent alongside this file) -->
+```
+
+### Resize before embedding
+
+Don't embed 4032×3024 originals — the page will be enormous and most photos
+look better at ~1600 px wide on the longer axis. Use Pillow:
+
+```python
+from PIL import Image
+img = Image.open(src_path)
+img.thumbnail((1600, 1600))
+img.save(out_path, "JPEG", quality=85, optimize=True)
+```
+
+Test on phone-screen-width — most year stories will be opened on a phone.
+
+### Pacing
+
+| Spread | Use for |
+|---|---|
+| Full-bleed hero | Opener, season titles, biggest moments |
+| Two-up | Pairs (before/after, two-angles, person + place) |
+| Three-up grid | Event recap (a wedding, a trip leg) |
+| Text-only | Section breaks, the closing reflection |
+
+Vary aggressively — three full-bleeds in a row is monotonous. Open and
+close strong; the first and last sections are what people remember.
+
+### Music? Sound? Skip by default.
+
+Auto-playing audio in HTML is jail. If the user explicitly asks, use
+`<audio>` with `controls` (no `autoplay`) and let them hit play.
+
+---
+
+## Verification
+
+Before emitting the file, sanity-check:
+
+1. Open the HTML directly with `file://` in Chrome / Safari. Photos render,
+   transitions don't jank.
+2. Total page size under 50 MB. If over, switch to linked mode or shrink
+   photos.
+3. Captions don't sound like greeting cards.
+4. Mobile viewport works (375 × 667 in DevTools): no horizontal scroll,
+   photos resize, text stays readable.
+
+If any of those fail, fix and re-emit before handing off.
+
+---
+
+## What this skill is NOT
+
+- Not a print-PDF generator. If the user asks for "hardcover book ready for
+  Shutterfly," reach for the `pdf` skill instead.
+- Not a video editor. Output is HTML + CSS animations, not MP4. If they
+  want video, suggest a screen-recording of the HTML scroll-through.
+- Not a face-recognition tool. Person-tagging upstream of this skill is
+  the relationship_mapper's job (via the `photos` MCP's `persons` field
+  or manual user labels).

manigent/_catalog/skills/playwright-browser/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: playwright-browser
+description: >
+  Drive a real Chrome browser via Python playwright when WebFetch can't do the
+  job — login required, JavaScript-rendered UI, or multi-step interaction. Each
+  subcommand cold-starts Chrome (no daemon) against a persistent profile,
+  performs one action, and lets the profile carry state forward. Runs HEADED by
+  default and applies a stealth fingerprint, so it survives Cloudflare's
+  managed-challenge tier. Vocabulary: `manigent browser {start, stop, auth,
+  navigate, snapshot, click, fill, press-key, screenshot, wait-for}`. Optional
+  fast path: `manigent browser start` runs one long-lived browser per agent
+  (tab per project) to drop the cold start and keep login fully live. Two-tier state:
+  agent-level `--storage <name>` (long-lived identity, written by `auth`) +
+  project-level `--session <dir>` (a persistent Chrome profile per project
+  sandbox; defaults to `$PWD/.playwright-session`). Setup: `manigent bootstrap
+  browser` once per runner, then `manigent browser auth --storage <name>` per
+  agent identity. Pairs with `playwright-save-skill` to crystallize a successful
+  explore.
+---
+
+# /manigent:playwright-browser
+
+Browser automation via the `manigent browser` CLI (Python playwright).
+
+## When to NOT use this skill
+
+WebFetch is faster for static public HTML. Only reach for the browser when
+**at least one** is true:
+- The site requires login (password, MFA, passkey, SSO).
+- The content is rendered by JavaScript after page load.
+- The task needs interaction (click / fill / multi-step nav).
+- The user explicitly wants this saved as a replayable skill.
+
+## Preflight
+
+1. **Chromium installed?** `manigent bootstrap browser` writes
+   `{data_dir}/.playwright_bootstrapped`. If missing, reply:
+   > Browser automation needs Chromium. Run `manigent bootstrap browser` once on this runner, then ask me again.
+
+2. **A login exists for this identity?** For login-walled sites you need a
+   signed-in identity (`personal` by default; another `--storage <name>` for a
+   separate one). A login counts if **either** is true: a daemon is running for
+   this agent (see *Fast path*), or the identity has a populated profile /
+   `$MANIGENT_AGENT_DIR/skill-hub/state/playwright-browser/storage/personal.json`.
+   If there's no login yet, hand off:
+   > I need a signed-in browser identity for this agent. On the runner, run:
+   > ```
+   > manigent browser start --url https://google.com
+   > ```
+   > A real Chrome window opens and stays live. Sign in to whatever sites you want me to access (Google, the target app, and any SSO providers) — solve any Cloudflare/Turnstile check yourself. Leave the window running; the session stays live (nothing to export). Reply 'done' and I'll continue.
+   >
+   > (No display on the runner? Use the one-shot login instead: `manigent browser auth --url https://google.com`, sign in, then press Enter in the terminal.)
+
+## Explore loop
+
+Each subcommand runs ONE action and prints `{url, snapshot}` or similar JSON.
+Cold-start cost is ~1.5–2 s per call — unless a daemon is running (see *Fast
+path* below), where calls are sub-second and routing is automatic. Non-navigate
+subcommands re-load `session.meta.json.last_url` automatically — you don't need
+to pass `--url` again after the first navigate.
+
+For a multi-step browser task you MAY enable the fast path first with
+`manigent browser start` (see *Fast path*); it reuses an existing login, and
+every action command below routes to it automatically. For **multi-step form or
+reward/booking flows, or any flow where a click may open a new tab/window**, you
+SHOULD `start` first — only the daemon holds page state and multiple tabs across
+commands (see *Tabs* below); one-shot cannot.
+
+`navigate` / `snapshot` / `screenshot` auto-wait for the page to settle (the
+`load` event + network-idle) so JS/SPA content has painted before you read it —
+no blank/splash captures. If you need a *specific* element, `wait-for 'selector'`
+before screenshotting rather than re-navigating and hoping. Tune with
+`--settle-ms <n>` (0 disables) for unusually slow or static pages.
+
+Actions run **headed** by default (a Chrome window appears) because that is the
+most Cloudflare-resistant. Force the mode per call with `--headless` / `--headed`
+if you need to; the default also follows the skill config's `headless` value
+(see *Cloudflare & bot detection* below).
+
+```bash
+# Step 1 — land
+manigent browser navigate https://app.provi.com --storage personal
+
+# Step 2 — read the accessibility tree, decide what to do
+# (snapshot is in the JSON output; use playwright selector syntax for actions)
+
+# Step 3 — interact
+manigent browser fill 'input[name="q"]' "Sandhi Chardonnay 2022" --storage personal
+manigent browser press-key Enter --storage personal
+
+# Step 4 — wait if needed
+manigent browser wait-for 'text=Search results' --storage personal --timeout-ms 8000
+
+# Step 5 — snapshot for next decision OR screenshot for the user
+manigent browser screenshot --out results.png --storage personal
+```
+
+Inside the runner, `--storage` resolves against the injected `$MANIGENT_AGENT_DIR`
+automatically. To run an action command **manually** outside the runner (e.g. to
+debug), pass `--agent <name>` so `--storage` can resolve — same as `auth`.
+
+Selector syntax is Playwright's: CSS selectors, `text=`, `role=`, plus
+`get_by_*` patterns wrapped as `internal:role=button[name="Sign in"]` etc.
+Refs from a snapshot in a previous CLI invocation are stale (cold-start);
+re-derive from the current snapshot each time, or use stable selectors.
+
+## Tabs (daemon only)
+
+A click can open a **new tab/window** (a `target=_blank` link, a `window.open`
+popup, many reward/booking flows). When it does, the click result does NOT
+switch to it — it stays on the current tab and adds:
+
+```
+"opened_tabs": [{"index": 1, "url": "https://…/reward", "active": false}],
+"note": "new tab(s) opened; active tab unchanged. Use `switch-tab <index>` …"
+```
+
+You decide what to do with it:
+
+```bash
+manigent browser tabs             # list this project's tabs (index, url, active)
+manigent browser switch-tab 1     # make tab 1 active; emits its snapshot
+manigent browser close-tab 1      # close a tab you don't need
+```
+
+If a snapshot looks unchanged after a click that should have advanced the flow,
+run `tabs` — the new page is probably a tab you haven't switched to. These
+commands need the daemon; one-shot can't carry a tab to the next command.
+
+## Fast path (optional): long-lived browser
+
+`manigent browser start` launches one persistent Chrome for the agent (a tab
+per project, keyed by sandbox CWD) and serves every subsequent subcommand from
+it over a local socket. While it runs:
+
+- **No cold start** — each action returns in well under a second.
+- **Login stays fully live** — cookies (including ephemeral session cookies that
+  Chrome never persists to disk), localStorage, and IndexedDB live in memory, so
+  there's no export/copy/seed and no re-auth between commands.
+- **Auth is just sign-in** — `start` (or `auth`) opens the live window; sign in
+  to whatever you need and leave it running. No separate export step.
+
+```bash
+manigent browser start --storage personal        # one live browser (sign in here if first time)
+manigent browser navigate https://app.example.com  # routed to the daemon, fast
+manigent browser snapshot                          # same live tab, sub-second
+```
+
+The action subcommands auto-route: if a daemon is running they use it, otherwise
+they fall back to the one-shot path below — same commands either way. The browser
+is launched once via patchright and **never** reconnected over CDP, so stealth is
+identical to one-shot.
+
+**You may `start`; do not `stop`.** Running `start` at the top of a browser-heavy
+task is fine — it reuses an existing login (only a first-time login needs the
+human to sign in in the live window) and is a no-op if one is already up. But
+`stop` is **user-managed**: stopping drops the in-memory session and the user's
+live window, so never stop a daemon yourself — leave it running for the next task.
+
+## Auth flow (first-time login OR refresh on expiry)
+
+Storage is per-agent + per-identity (`--storage personal`, `--storage work`,
+etc.). One headed `manigent browser auth` session captures cookies +
+localStorage for every domain visited inside that window — apps + SSO
+providers. On the first action of a new `--session`, the storage's cookies
+seed the session's persistent Chrome profile; from then on the profile itself
+carries the logged-in state (and any `cf_clearance`) forward.
+
+The `auth` window is the SAME hardened browser as the actions — real Chrome,
+stealth fingerprint, persistent profile (and patchright when the stealth extra
+is installed). That's what lets you pass Cloudflare/Turnstile during login; the
+human solves any interactive challenge in the window.
+
+Never type credentials yourself. Hand off to the user with the CLI:
+
+> Run `manigent browser auth --url https://google.com` on the runner.
+> A real Chrome window opens at google.com. Sign in to Google, then visit
+> each app site I'll need (e.g. https://app.provi.com); complete the
+> OAuth bounce all the way back to the app and solve any Cloudflare/Turnstile
+> check. Then return to the terminal and **press Enter** (do NOT close the
+> window yourself). The storage lands at
+> `skill-hub/state/playwright-browser/storage/personal.json`.
+
+`auth` defaults to `--storage personal`. Use `--storage <name>` for a
+separate sign-in (e.g. `work`). On subsequent action subcommands
+(`navigate`, `click`, …), `--storage` defaults to empty — pass
+`--storage personal` explicitly, or the browser runs anonymously.
+
+## Things to NOT do
+
+- Do not type credentials yourself — always hand off (`manigent browser start`,
+  or `auth` for the one-shot fallback).
+- Do not log out at the end of a task — that invalidates the storage identity
+  for every future explore.
+- Do not `stop` the browser daemon — it's user-managed and holds the live
+  session (same spirit as "don't log out"). You may `start` it; never stop it.
+- Do not invoke this skill when WebFetch can do the job.
+- Do not pass refs/selectors across CLI invocations in one-shot mode — cold-start
+  invalidates a snapshot's refs; re-derive from the current snapshot.
+- Do not save the explore as a personal skill yourself — that's `playwright-save-skill`'s job.
+
+## Cloudflare & bot detection
+
+The CLI hardens every action against bot detection automatically — you don't
+configure anything for the common case:
+
+- **Headed by default + a stealth fingerprint.** Real Chrome (not bundled
+  Chromium), automation flags stripped, a realistic UA / viewport / locale /
+  timezone, and a `navigator.webdriver` / WebGL mask. Headless is the single
+  biggest bot tell, so prefer the default; only pass `--headless` when you
+  accept a higher block rate.
+- **Persistent per-session profile.** The session is a real Chrome profile at
+  `<session_dir>/profile/` (not a `state.json` dump). Cloudflare's
+  `cf_clearance` cookie and a stable fingerprint persist across the
+  cold-started invocations, so once a session clears a challenge it keeps
+  passing — re-running is also faster.
+- **Challenge-aware waiting.** On a Cloudflare interstitial ("Just a moment…")
+  the command waits up to ~30 s for the challenge to clear before snapshotting.
+  If it never clears, the command exits non-zero with a `ChallengeUnresolvedError`.
+  When that happens: retry, make sure you passed a valid `--storage` identity,
+  and prefer headed mode. A managed challenge may need an interactive `auth`
+  pass first (sign in via `manigent browser auth` so cookies seed the profile).
+
+**Real Chrome recommended.** The CLI prefers the installed Google Chrome and
+falls back to bundled Chromium only if Chrome is absent — but bundled Chromium
+is easier to fingerprint and less likely to pass tough challenges. Install
+Google Chrome on the runner for best results.
+
+**Stubborn sites (airlines, Turnstile, "access denied").** A plain stealthed
+Playwright browser still leaks that it's automated via the CDP `Runtime.enable`
+call — enough for Cloudflare Turnstile to fail the checkbox or for a site to
+deny access after login. The **patchright** stealth runtime closes that leak and
+**ships by default** with manigent (it's a core dependency) — just run:
+
+```
+manigent bootstrap browser     # fetches real Chrome + reports the active runtime
+```
+
+> **Python 3.14 caveat.** patchright has no Python 3.14 build, so on 3.14 it's
+> not installed and the skill falls back to stock Playwright (which Cloudflare
+> Turnstile / airline sites will likely block). Run manigent under Python ≤3.13
+> (e.g. `pyenv install 3.13 && pyenv local 3.13.x`, then reinstall) for the
+> stealth runtime.
+
+`manigent bootstrap browser` prints the active runtime and warns loudly if the
+stealth runtime is inactive (e.g. running on Python 3.14). When active, the skill
+uses **patchright** (closes the CDP leak; real Chrome with a clean, override-free
+config) for both `auth`/`start` and the action commands. Every result JSON
+— and the `auth` opening message — reports `"runtime": "patchright"` when active
+(`"playwright"` otherwise). This is the first thing to try for China-Airlines
+Turnstile or post-login "access denied".
+
+Note: the fingerprint config keys (`user_agent`, `viewport`, `webgl_*`) apply
+**only** to the stock-Playwright fallback. Under patchright they're intentionally
+ignored — patchright presents a coherent real-Chrome fingerprint, and overriding
+it would re-introduce detectable inconsistencies. `headless` and `proxy_*` apply
+to both.
+
+**Proxy (hard IP blocks).** If a site returns an immediate "access denied" /
+error 1020 with no solvable challenge, it's likely blocking the runner's IP
+(datacenter/VPN). Set `proxy_server` (+ optional `proxy_username`/`proxy_password`)
+in the skill config to route through a residential proxy. See `starter_config.jsonc`.
+
+**Headless Linux servers (no display).** Headed mode needs a display. Either
+set `"headless": true` in the config, or wrap the command in a virtual display
+(no extra Python dependency):
+
+```bash
+xvfb-run -a manigent browser navigate https://app.example.com --storage personal
+```
+
+**Optional config.** Fingerprint defaults live in the CLI; override any of
+them per agent via `starter_config.jsonc` (Agent Settings → Skills →
+playwright-browser → Configure): `headless`, `user_agent`, `locale`,
+`timezone_id`, `viewport_width/height`, `webgl_vendor/renderer`. Every key is
+optional. Keep UA / locale / timezone mutually consistent.
+
+## Concurrency
+
+**One-shot mode:** each invocation spawns one Chrome process (against the session
+profile) and tears it down. Parallel explores on the same agent are safe as long
+as they use different `--session` dirs (default `$PWD/.playwright-session` already
+partitions by sandbox CWD). Do **not** run two commands against the *same*
+`--session` concurrently — they share one persistent profile dir and Chrome will
+refuse the second with a "profile in use" error.
+
+**Daemon (fast path) mode:** one Chrome with a tab per project. Different
+projects (different `--session`) run on independent tabs and interleave freely;
+commands on the *same* project serialize on a per-tab lock instead of failing —
+so the same-session restriction above does not apply. Different agents always run
+fully separate daemons/Chromes.

manigent/_catalog/skills/playwright-browser/starter_config.jsonc

@@ -0,0 +1,44 @@
+{
+  // playwright-browser fingerprint overrides. ENTIRELY OPTIONAL — every key
+  // below already has a Cloudflare-resistant default baked into the CLI.
+  // Delete any key to accept its default; delete the whole file to accept all
+  // defaults. The `manigent browser ... --headed/--headless` flag overrides
+  // the `headless` value here.
+  //
+  // NOTE: the fingerprint keys (user_agent, locale, timezone_id, viewport_*,
+  // webgl_*) apply ONLY when running on stock Playwright. When the patchright
+  // stealth runtime is active they are intentionally ignored — patchright
+  // presents a coherent real-Chrome fingerprint and overriding it hurts. The
+  // `headless` and `proxy_*` keys apply to both runtimes.
+
+  // Run with a visible window (false) or headless (true). Headed is by far the
+  // most resistant to Cloudflare / bot detection and is the default. On a
+  // Linux server with no display, either set this to true OR run the CLI under
+  // `xvfb-run` (see SKILL.md) — no extra Python dependency is needed.
+  "headless": false,
+
+  // Browser identity. Keep these mutually consistent — a macOS user-agent, a
+  // US timezone, and an en-US locale all agree with each other. A mismatched
+  // trio (e.g. a macOS UA with a Tokyo timezone) is itself a bot signal.
+  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
+  "locale": "en-US",
+  "timezone_id": "America/New_York",
+
+  // Window size. 1440x900 is a common real-laptop viewport.
+  "viewport_width": 1440,
+  "viewport_height": 900,
+
+  // WebGL spoof — makes the GPU fingerprint look like real hardware instead of
+  // the headless ANGLE/SwiftShader renderer. The defaults below mimic an
+  // Apple-Silicon Mac; change them to match the machine you want to look like.
+  "webgl_vendor": "Google Inc. (Apple)",
+  "webgl_renderer": "ANGLE (Apple, ANGLE Metal Renderer: Apple M1, Unspecified Version)"
+
+  // Optional proxy — only needed when a site blocks the runner's IP outright
+  // (a hard "access denied" / error 1020 with no solvable challenge), which
+  // usually means a datacenter/VPN IP. Point at a residential proxy. Leave the
+  // keys absent (as below) for a direct connection.
+  // "proxy_server": "http://host:port",      // or "socks5://host:port"
+  // "proxy_username": "user",
+  // "proxy_password": "pass"
+}