agent-browser-relaticle

# agent-browser × Relaticle cookbook (cached hints, verified dates, self-healing)

**Prime rule: facts below are cached hints, not truth.** The app's URLs, routes,
selectors, and seeders change. When a documented pattern fails **twice**, stop retrying:
re-derive it from the running app (procedures below), make it work, then **update this
file** with the new pattern and today's `verified:` date.

## 1. URL derivation (NEVER hardcode; panels are conditionally domain-routed)

```bash
php artisan tinker --execute 'echo json_encode([
  "base"            => config("app.url"),
  "app_domain"      => config("app.app_panel_domain"),
  "app_path"        => config("app.app_panel_path", "app"),
  "sysadmin_domain" => config("app.sysadmin_domain"),
  "sysadmin_path"   => config("app.sysadmin_path", "sysadmin"),
]);'
```

- app panel = `https://{app_domain}` if set, else `{base}/{app_path}`
- sysadmin  = `https://{sysadmin_domain}` if set, else `{base}/{sysadmin_path}`
- **Routing mode is per-checkout. Derive it, and never carry it over from another
  workspace.** Both modes are live in the wild:
  - Conductor workspace `bamako`, `APP_PANEL_DOMAIN`/`SYSADMIN_DOMAIN` empty →
    path-routed: `https://bamako.test/app`, `https://bamako.test/sysadmin`
    (verified: 2026-08-12).
  - A checkout with the `*_DOMAIN` envs set → domain-routed, e.g.
    `https://app.relaticle.test`, `https://sysadmin.relaticle.test`
    (verified: 2026-06-12).

  Each Conductor workspace is served by Herd under its own `https://<workspace>.test`,
  so the host changes too. Run the `tinker` block above every run and use what it
  returns.
- Login entry points are Filament-registered routes; ground truth:
  `php artisan route:list --json` filtered for `login` (names like
  `filament.app.auth.login`). If a URL 404s, check the route table before anything else.
- Host unreachable? `herd sites` / `herd links` shows what Herd actually serves this
  checkout as (catches renamed dirs / Polyscope clones). `.env` vs `config()` mismatch →
  `php artisan config:clear`.

## 2. Session setup (every time)

```bash
export AB_SESSION="<purpose>-<run-id>"     # ALWAYS unique per agent; sessions are machine-global
agent-browser --session "$AB_SESSION" set viewport 1920 1080
agent-browser --session "$AB_SESSION" open "$APP_PANEL_URL"
```

Pass `--session "$AB_SESSION"` on EVERY call (or export `AGENT_BROWSER_SESSION`).
Default 1280x720 clips Filament modals (verified: 2026-05).

## 3. Credentials (seeded; re-derive when login fails)

| Surface | Login | Password | Source |
|---|---|---|---|
| app panel | `manuk.minasyan1@gmail.com` | `password` | `database/seeders/LocalSeeder.php` (verified: 2026-06-12) |
| sysadmin | `sysadmin@relaticle.com` | `password` | `SystemAdministratorSeeder` (verified: 2026-06-12) |
| per-run test users | `br-rel-<run>-…@example.test` | `password` | factory |

Login failing? In order: `php artisan db:seed --class=LocalSeeder` (local-gated; also
tops AI credits) → `--class=SystemAdministratorSeeder` → factory-create a namespaced
user (`User::factory()->withPersonalTeam()->create([...])`). If the seeder emails
changed, fix this table (self-heal).

Dev-login affordance: the app registers `laravel-login-link` (route `loginLinkLogin`,
POST `laravel-login-link-login`; verified 2026-06-12 via `route:list`). Local login
pages may render one-click "Login as …" links; prefer them over typing credentials when
present.

## 4. Login flow (both panels, Filament stock login)

**CORRECTION (verified: 2026-06-12, review PR 336):** the `input[name="email"]` selector
is WRONG. It matches a **hidden** input belonging to the `laravel-login-link` dev package
(the page has hidden `_token`/`email`/`key`/`guard`/`user_model` inputs from that form).
`agent-browser fill` against that hidden field **hung the daemon** (`os error 35`,
"daemon may be busy or unresponsive") and never submitted. The REAL Filament inputs have
NO `name` attribute. They are `id="form.email"` / `id="form.password"` with
`wire:model="data.email"` / `data.password`, inside the `<form wire:submit="authenticate">`.

The recipe that works when `fill`/`type` hang (eval-driven, daemon-safe):

```bash
export AGENT_BROWSER_SESSION="<unique>"
agent-browser open "$PANEL_URL/login"
agent-browser eval '(() => {
  const e=document.getElementById("form.email"), p=document.getElementById("form.password");
  e.value="'"$LOGIN"'"; e.dispatchEvent(new Event("input",{bubbles:true}));
  p.value="password";  p.dispatchEvent(new Event("input",{bubbles:true}));
  const f=[...document.querySelectorAll("form")].find(x=>x.getAttribute("wire:submit")==="authenticate");
  f.requestSubmit(); return "submitted";
})()'
sleep 4
agent-browser eval 'location.pathname'   # confirm you left /login (lands on /<team-slug>)
```

- **Daemon hangs on `fill`/`type`** in this environment (verified: 2026-06-12). When a
  command returns `os error 35` / no output, `pkill -9 -f agent-browser; sleep 3` and
  re-open. `open`/`eval`/`snapshot`/`screenshot` are reliable; `click` is flaky, so prefer
  `eval` with `el.click()` for `<a wire:navigate>` links.
- Many stale `--session` entries overload the daemon; keep ONE session per run and chain
  commands with `&&` in a single shell call (the daemon persists the browser).

<details><summary>Older recipe (fill+click), left here for reference; did NOT work on 2026-06-12</summary>

```bash
agent-browser --session "$AB" open "$PANEL_URL/login"
agent-browser --session "$AB" fill 'input[name="email"]' "$LOGIN"
agent-browser --session "$AB" fill 'input[name="password"]' "password"
sleep 1
agent-browser --session "$AB" click "Sign in"
agent-browser --session "$AB" wait --load networkidle
agent-browser --session "$AB" eval 'location.pathname'   # confirm you left /login
```
</details>

- **`click` / `fill` take the element's VISIBLE TEXT or a CSS selector, NOT
  `find role button "<name>"`**. That subcommand syntax errors on this binary
  (verified: 2026-06-12). Use `agent-browser cli