@lovrozagar/grunt 0.3.11 → 0.4.0

package/.rulesync/reference/rtk.md

@@ -10,7 +10,7 @@ Grok PostToolUse is observe-only — do not attempt output scrub; compress via R
 
 ## Commands
 
-ls · tree · read · smart · git · gh · glab · aws · psql · pnpm · err · test · json · deps · env · find · diff · log · dotnet · docker · kubectl · oc · summary · grep · rg · init · wget · wc · gain · cc-economics · config · jest · vitest · prisma · tsc · next · lint · prettier · format · playwright · cargo · npm · npx · curl · discover · session · telemetry · learn · run · proxy · pipe · trust · untrust · verify · ruff · pytest · mypy · rake · rubocop · rspec · pip · go · gt · golangci-lint · gradlew · mvn · hook-audit · rewrite · hook · help
+ls · tree · read · smart · git · gh · glab · aws · psql · pnpm · err · test · json · deps · env · find · diff · log · dotnet · docker · kubectl · oc · summary · grep · rg · init · wget · wc · gain · cc-economics · config · jest · vitest · prisma · tsc · next · lint · prettier · format · playwright · lightpanda · cargo · npm · npx · curl · discover · session · telemetry · learn · run · proxy · pipe · trust · untrust · verify · ruff · pytest · mypy · rake · rubocop · rspec · pip · go · gt · golangci-lint · gradlew · mvn · hook-audit · rewrite · hook · help
 
 **git:** diff · log · status · show · add · commit · push · pull · branch · fetch · stash (list show pop apply drop push) · worktree
 **cargo:** build · test · clippy · check · install · nextest
@@ -21,3 +21,6 @@ ls · tree · read · smart · git · gh · glab · aws · psql · pnpm · err
 Flags: `-v`/`-vv`/`-vvv` · `--ultra-compact` · `--skip-env` · `-h` · `-V`
 
 Unknown cmds passthrough. `rtk run` unfiltered.
+
+**playwright:** test-runner family only — not the browser rail.
+**lightpanda:** browser-rail CDP via `scripts/browser.mjs` (not MCP, not env).

package/.rulesync/rules/CLAUDE.md

@@ -24,6 +24,7 @@ Always-do:
 | children done + no findings | recap; stop allowed only if no writes remain and spawn count > 0 when the user asked for a file change |
 | `/parent` | spawn-first; hook last-ditch `parent-escape`; never Read/Bash |
 | `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
+| `/pickup` | spawn-first; grunt resolve if needed; never parent Read; not a mode |
 | `/write-plan` plan-only | recap + `next: /implement-plan` |
 | `/explain` | spawn if facts/work; then human recap of child output; screenshot/visible=context no Read |
 | `/solo` | session escape only; stamp grunt-off-{sid}; else spawn-first |
@@ -31,7 +32,7 @@ Always-do:
 
 Parent = this file not `.claude/agents/orchestrator.md`. You do not talk. Spawn wait echo.
 Spawn only grunt|implementer|thinker. Never spawn orchestrator. Children never spawn.
-You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`.
+You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`. `/pickup` spawn-first; grunt resolve if needed; never parent Read; not a mode.
 `/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow.
 grunt ← tools (facts/search/exec/git/web/test/low-reason mechanical write; world fact: `job: web` never memory). implementer ← write defined solution. thinker ← plan/deep reason.
 Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.

package/.rulesync/rules/overview.md

@@ -29,6 +29,7 @@ Always-do:
 | children done + no findings | recap; stop allowed only if no writes remain and spawn count > 0 when the user asked for a file change |
 | `/parent` | spawn-first; hook last-ditch `parent-escape`; never Read/Bash |
 | `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
+| `/pickup` | spawn-first; grunt resolve if needed; never parent Read; not a mode |
 | `/write-plan` plan-only | recap + `next: /implement-plan` |
 | `/explain` | spawn if facts/work; then human recap of child output; screenshot/visible=context no Read |
 | `/solo` | session escape only; stamp grunt-off-{sid}; else spawn-first |
@@ -36,7 +37,7 @@ Always-do:
 
 Parent = orchestrator. You do not talk. Spawn wait echo.
 Spawn only grunt|implementer|thinker. Never spawn orchestrator. Children never spawn.
-You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`.
+You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`. `/pickup` spawn-first; grunt resolve if needed; never parent Read; not a mode.
 `/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow.
 grunt ← tools (facts/search/exec/git/web/test/low-reason mechanical write; world fact: `job: web` never memory). implementer ← write defined solution. thinker ← plan/deep reason.
 Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.

package/.rulesync/skills/browser/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: browser
+description: >
+  Session browser rail. /browser or browse a URL. Call
+  node scripts/browser.mjs nav|snap|click|fill|shot|pdf|stop.
+  Lightpanda default; snap is the default read. Windows → Chromium.
+  Never MCP. Never env knobs. Never raw Playwright.
+---
+
+Zero-config. `node scripts/browser.mjs <verb>`.
+
+Verbs: `nav <url>` · `snap` · `click <ref>` · `fill <ref> <text>` · `shot` · `pdf` · `stop` · `doctor` · `ensure`.
+
+- **snap** = default read (markdown + numbered refs). `click`/`fill` need a prior snap.
+- Lightpanda default. Chromium when `shot`/`pdf`/`trace`, win32, missing Lightpanda, probe-fail once, or paint hosts (figma docs/sheets/slides mail.google earth).
+- Session/profile: `.tmp/grunt/browser/`. `stop` reaps; second `stop` ok.
+- Windows: Chromium even if Lightpanda exists.
+- `doctor`/`ensure` → `node scripts/doctor.mjs` or `grunt doctor`. See README Prerequisites.
+- No env. No MCP. No raw Playwright. Spec: `.rulesync/reference/browser.md`.

package/.rulesync/skills/handoff/SKILL.md

@@ -67,14 +67,14 @@ Host without that hook: name the file per **Path** yourself, or pipe the body to
 
 ```
 [handoff]: serial={int} path=.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md
-next: start a new session; first action = spawn grunt|implementer with abs path={that file}
+next: start a new session; `/pickup {serial}` (equiv: spawn grunt|implementer with abs path={that file})
 ```
 
 Do not dump the handoff body.
 
 ## Picking one up
 
-New session, `/handoff` not needed: spawn grunt|implementer with abs path of the newest `.tmp/grunt/handoffs/*.md` (or the given serial). Parent never Read. Child sets `status: resumed`, work `Next` leaves in order, flip only the box. All `[x]` → `status: done`. Do not re-plan; a stale leaf → `/write-plan` a follow-up.
+`/pickup {serial}` owns pickup (equiv: spawn grunt|implementer with abs path). Parent never Read. Child sets `status: resumed`, work `Next` leaves in order, flip only the box. All `[x]` → `status: done`. Do not re-plan; a stale leaf → `/write-plan` a follow-up.
 
 ## Rules
 

package/.rulesync/skills/pickup/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: pickup
+description: >
+  Pick up/continue a session handoff under .tmp/grunt/handoffs/. Use for
+  /pickup, pick up, continue handoff, serial, drag-drop path,
+  newest/last/latest, title substring. Inverse of /handoff. Not a plan. Not
+  /handoff.
+---
+# pickup
+
+Voice: `.rulesync/reference/output.md`.
+
+Spawn-first pickup. Parent never Read/Bash/list the handoff. First token = spawn. No ask_user_question. Ask = recap list + stop; wait next user turn. Not a mode. Not `/handoff`. Inverse of `/handoff`. Pickup owns pickup.
+
+## Invocation
+
+- `/pickup`
+- `/pickup latest` (also `newest`/`last`)
+- `/pickup {serial}`
+- `/pickup {abs|rel|drag-drop path}`
+- `/pickup {title substring}`
+
+## Resolve
+
+Via grunt (`job:exec|search` on `.tmp/grunt/handoffs/`). Skip grunt only if user arg is already abs path under that dir.
+
+Order:
+
+1. path-like → file if exists + FILENAME_RE `^[0-9]+-[a-z0-9]+(-[a-z0-9]+)*-\d{8}T\d{6}Z\.md$`
+2. integer → FM serial or filename prefix
+3. latest|newest|last → newest by FM `created`
+4. else case-insensitive substring on name/source/H1
+5. empty arg: 0→none; 1→auto; N→list+ask (**not** auto-newest)
+
+List lines: serial status name created path. Prefer open|resumed first; still include done.
+
+Matches: 0→recap missing; 1→proceed; N→list+ask never guess.
+
+Empty/missing dir: recap no handoffs; stop.
+
+Drag outside handoffs dir or non-FILENAME_RE: reject; list valid.
+
+Corrupt FM: grunt reports; no implementer on garbage.
+
+status done + explicit serial/path: warn; still load if user named it.
+
+## After unique path
+
+Spawn implementer with abs path (default). Child: load file; `status: resumed`; Next leaves in order; flip only that box; all `[x]` → `status: done`; do not re-plan; stale → `/write-plan`. Child Edit in place. Never persist-handoff.mjs on pickup. No parent Write on resume.
+
+## Recap
+
+```
+serial={int} path={abs}
+```
+
+Do not invent a new role tag.
+
+## Rules
+
+- Parent never Read/Bash/list. First token = spawn.
+- No ask_user_question. Ask = recap list + stop.
+- `/handoff` stays one-turn write. This skill owns pickup.
+- Protocol: `.rulesync/reference/cascade.md`. Do not paste.

package/.rulesync/skills/solo/SKILL.md

@@ -18,6 +18,6 @@ Fat-tool caps stay on — token guards, not cascade.
 
 Claude/Codex/Grok: `/solo` via submit hook writes `.tmp/orchestrator-logs/grunt-off-{sid}`; `/cascade` unlinks it and the next turn is orchestrated again. Agents/Antigravity: instruction-only (this skill body); cannot create stamp via `/solo`; Stop still honors a pre-existing stamp if present. Session-scoped, never global.
 
-This is the only session-wide spawn-workflow escape. /explain /parent /handoff /write-plan /implement-plan still spawn-first unless this session’s grunt-off-{sid} exists.
+This is the only session-wide spawn-workflow escape. /explain /parent /handoff /pickup /write-plan /implement-plan still spawn-first unless this session’s grunt-off-{sid} exists.
 
 For advisory/design turns, debugging the cascade itself, or back-and-forth where spawning costs more than it saves.

package/.rulesync/subagents/grunt.md

@@ -43,6 +43,7 @@ Scratch/tmp → `{workspaceRoot}/.tmp/grunt/` only (mkdir as needed). Never `.tm
 `job: search|exec` → first action `node scripts/grunt-job.mjs --job search|exec --query …`; whole reply = stdout.
 `job: test` → grunt-job; `FALLBACK` (exit 2) → LLM tools.
 `job: web` and messy test → LLM grunt (web_search/web_fetch).
+Browser → `node scripts/browser.mjs <verb>` (`nav|snap|click|fill|shot|pdf|stop`). Lightpanda default. Never MCP. Never raw Playwright. Never env knobs.
 Isolation/write reply ≤8 lines. Verdict grammar only — no dumps/recap/HTML/JSON/full logs:
 
 ```

package/.rulesync/subagents/implementer.md

@@ -33,6 +33,7 @@ Voice: `.rulesync/reference/output.md` — must follow.
 
 Implement specified solution. User prompt may be the spec; `.tmp/plans` not required for small/defined writes. Never spawn. Never run for simple tool usage (grunt agent). Never plan (thinker agent).
 After write: validate+sim (mandatory). Fix hard failures. Return findings. Never skip validation
+DOM ⚠ → `node scripts/browser.mjs snap`. Visual ⚠ → `node scripts/browser.mjs shot`.
 Read/Grep/list_dir only if needed for edit. Prefer: implement the spec; dump via `need:`.
 Write-allowlist = paths listed in the spec/plan/prompt only. No unsolicited README/docs/examples. Missing path → blocker/`need:`; do not invent. Checkbox-flip the plan file.
 TDD when the spec/plan says tests: you write intelligent test, confirm test fails, implement solution, confirm test pass and iterate until completion (red/green/refactor).

package/.rulesync/subagents/orchestrator.md

@@ -53,6 +53,7 @@ Always-do:
 | children done + no findings | recap; stop allowed only if no writes remain and spawn count > 0 when the user asked for a file change |
 | `/parent` | spawn-first; hook last-ditch `parent-escape`; never Read/Bash |
 | `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
+| `/pickup` | spawn-first; grunt resolve if needed; never parent Read; not a mode |
 | `/write-plan` plan-only | recap + `next: /implement-plan` |
 | `/explain` | spawn if facts/work; then human recap of child output; screenshot/visible=context no Read |
 | `/solo` | session escape only; stamp grunt-off-{sid}; else spawn-first |
@@ -64,4 +65,4 @@ grunt ← tools. World fact → grunt `job: web`. Never memory. implementer ←
 Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.
 Peek every 60s/child; quote real host fields; `done|alive|stuck`; no invent; no auto-kill. Grok: `get_command_or_subagent_output` `timeout_ms=60000` every peek. Else GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.
 Child `need:` JSON → parse-need + parallel grunt; one `resume_from` + **new** verdicts only; max 3; no re-send task; no fresh-spawn.
-`/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow.
+`/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow. `/pickup` spawn-first; grunt resolve if needed; never parent Read; not a mode.

package/AGENTS.md

@@ -19,6 +19,7 @@ Always-do:
 | children done + no findings | recap; stop allowed only if no writes remain and spawn count > 0 when the user asked for a file change |
 | `/parent` | spawn-first; hook last-ditch `parent-escape`; never Read/Bash |
 | `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
+| `/pickup` | spawn-first; grunt resolve if needed; never parent Read; not a mode |
 | `/write-plan` plan-only | recap + `next: /implement-plan` |
 | `/explain` | spawn if facts/work; then human recap of child output; screenshot/visible=context no Read |
 | `/solo` | session escape only; stamp grunt-off-{sid}; else spawn-first |
@@ -26,7 +27,7 @@ Always-do:
 
 Parent = orchestrator. You do not talk. Spawn wait echo.
 Spawn only grunt|implementer|thinker. Never spawn orchestrator. Children never spawn.
-You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`.
+You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`. `/pickup` spawn-first; grunt resolve if needed; never parent Read; not a mode.
 `/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow.
 grunt ← tools (facts/search/exec/git/web/test/low-reason mechanical write; world fact: `job: web` never memory). implementer ← write defined solution. thinker ← plan/deep reason.
 Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.

package/CLAUDE.md

@@ -19,6 +19,7 @@ Always-do:
 | children done + no findings | recap; stop allowed only if no writes remain and spawn count > 0 when the user asked for a file change |
 | `/parent` | spawn-first; hook last-ditch `parent-escape`; never Read/Bash |
 | `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
+| `/pickup` | spawn-first; grunt resolve if needed; never parent Read; not a mode |
 | `/write-plan` plan-only | recap + `next: /implement-plan` |
 | `/explain` | spawn if facts/work; then human recap of child output; screenshot/visible=context no Read |
 | `/solo` | session escape only; stamp grunt-off-{sid}; else spawn-first |
@@ -26,7 +27,7 @@ Always-do:
 
 Parent = this file not `.claude/agents/orchestrator.md`. You do not talk. Spawn wait echo.
 Spawn only grunt|implementer|thinker. Never spawn orchestrator. Children never spawn.
-You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`.
+You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. After child: legal tag + one-line echo only. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`. `/pickup` spawn-first; grunt resolve if needed; never parent Read; not a mode.
 `/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow.
 grunt ← tools (facts/search/exec/git/web/test/low-reason mechanical write; world fact: `job: web` never memory). implementer ← write defined solution. thinker ← plan/deep reason.
 Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.

package/README.md

@@ -5,6 +5,7 @@ Multi-agent orchestrator SoT — deep-merge rulesync trees product scripts and g
 OSS drop-in; merges existing configs; switches default provider flow to Grunt.
 
 - [Install](#install)
+- [Prerequisites](#prerequisites)
 - [Usage](#usage)
 - [CLI](#cli)
 - [Init](#init)
@@ -33,6 +34,29 @@ npx @lovrozagar/grunt
 - Do not `npm test` as a consumer
 - Package: `@lovrozagar/grunt` `0.3.9` MIT · https://github.com/lovrozagar/grunt
 
+## Prerequisites
+
+All OS. Print-only. Never auto-install.
+
+```
+npx grunt doctor
+node scripts/doctor.mjs
+```
+
+Exit 1 if any required missing; 0 if all required ok. Optional `gh` reported only.
+
+| tool | required | install |
+| --- | --- | --- |
+| node ≥22 + npm | yes | https://nodejs.org (≥22) · nvm / OS pkg · win `winget install OpenJS.NodeJS.LTS` |
+| git | yes | linux `sudo apt install git` · mac `brew install git` · win `winget install Git.Git` |
+| rtk | yes | linux/mac `curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh \| sh` or `brew install rtk` · win release zip `rtk.exe` on PATH or WSL curl ([docs](https://www.rtk-ai.app/docs/getting-started/installation/)) |
+| rulesync | yes | `npm i -D rulesync` / npx (PATH or npx-able) |
+| lightpanda | yes | `curl -fsSL https://pkg.lightpanda.io/install.sh \| bash` · mac `brew tap lightpanda-io/browser` · win WSL only |
+| chromium-family | yes | linux `sudo apt install chromium` · mac `brew install --cask chromium` or `google-chrome` · win `winget install Google.Chrome` / `Microsoft.Edge` + PATH |
+| gh | no | report only |
+
+Rulesync schema doctor is separate: `npm run rulesync:doctor`.
+
 ## Usage
 
 - TTY no command → menu (init default; generate check sync-globals purge-mcps doctor help quit)
@@ -48,7 +72,7 @@ npx @lovrozagar/grunt
 - `check` → `npm run rulesync:check`
 - `sync-globals` → `npm run sync:globals` (dry-run); `--apply` → `sync:globals:apply`
 - `purge-mcps` → `npm run purge:global-mcps` (dry-run); `--apply` → `purge:global-mcps:apply`
-- `doctor` → `npm run rulesync:doctor`
+- `doctor` → `npm run doctor` (`node scripts/doctor.mjs`). Rulesync schema: `npm run rulesync:doctor`
 - `help`
 - `version`
 
@@ -81,18 +105,24 @@ SoT: `.rulesync/subagents/{orchestrator grunt implementer thinker}.md`
 
 Emit: `.claude/` `.grok/` `.agents/` `.gemini/`
 
-- **orchestrator** (parent) — always spawn+prompt; user-facing only `[orchestrator]:` (or child role tag) one-line echo. `/parent` one-turn; `/handoff` writes `.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md`. Small/low router. First token spawn. No parent Read/Bash/Grep. Does not implement, plan, or fetch world facts
+- **orchestrator** (parent) — always spawn+prompt; user-facing only `[orchestrator]:` (or child role tag) one-line echo. `/parent` one-turn; `/handoff` writes `.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md`; `/pickup` spawn-first pickup (inverse of `/handoff`; not a mode). `/solo` session escape; `/cascade` restores it. Small/low router. First token spawn. No parent Read/Bash/Grep. Does not implement, plan, or fetch world facts
 - **grunt** — tools: facts/search/exec/git/web/test/low-reason mechanical write. Isolation `verdict:`. Never feature solution. Never spawn. World fact: `job: web`
 - **implementer** — write already-defined solution on allowlisted paths. TDD when spec/plan says tests. Validate + sim after write. Fat dumps via `need:`. Never spawn. Never plan. Id is **implementer** (not Implementor)
 - **thinker** — plan/deep reason; edge cases. Read-only named-file Read of prompt SSOT; trees/search/exec/web/test → `need:`. Never spawn. No bash. Never implement
 
 Children never spawn. Spawn only grunt|implementer|thinker. Omit model on spawn; frontmatter on agent files picks haiku/sonnet/opus vs grok-4.5 / grok-4.6 / other hosts. Voice: `.rulesync/reference/output.md`. Protocol: `.rulesync/reference/cascade.md`. `AGENTS.md`/`CLAUDE.md` spawn-first. `GEMINI.md` → `@AGENTS.md`. Goals: synced configs across grok build claude code codex gemini cli antigravity; max situational speed; superterse token savings; max/min reasoning by role.
 
+## Browser
+
+Lightpanda-first session CLI: `node scripts/browser.mjs nav|snap|click|fill|shot|pdf|stop|doctor|ensure`. Zero MCP. Zero env knobs. Chromium only for `shot`/`pdf`/`trace`, Windows, missing Lightpanda, one probe-fail replay, or paint hosts. Session: `.tmp/grunt/browser/`. Spec: [`.rulesync/reference/browser.md`](.rulesync/reference/browser.md).
+
+`node scripts/browser.mjs doctor` (alias `ensure`) runs the unified doctor (`scripts/doctor.mjs`). Install engines: [Prerequisites](#prerequisites).
+
 ## Skills
 
 Present under `.claude` / `.rulesync` / `.agents`:
 
-- `cascade` `commit` `commit-and-push` `commit-push` `commit-push-deploy` `commit-push-release` `explain` `handoff` `parent` `solo`
+- `browser` `cascade` `commit` `commit-and-push` `commit-push` `commit-push-deploy` `commit-push-release` `explain` `handoff` `pickup` `parent` `solo`
 - Grok-only: `write-plan` `implement-plan` (`/write-plan` plan-only → `next: /implement-plan`)
 
 ## Generate
@@ -104,7 +134,7 @@ Pipeline (no `-t geminicli`):
 3. `emit-gemini.mjs` — `GEMINI.md` `.gemini/agents/{id}/agent.md` MCP `.gemini/settings.json`
 4. `emit-agent-shell-tools` — Claude grunt body `Bash`; other hosts `run_terminal_command` (hooks-union)
 
-`check` / `doctor` = rulesync check / doctor.
+`check` = rulesync check. `doctor` = unified prereqs. Schema: `npm run rulesync:doctor`.
 
 Emit writes other-CLI trees from `.rulesync` for the **next** process of that CLI. Not a live hop into another host.
 
@@ -288,7 +318,7 @@ Repo-relative (repository root):
 
 ## Layout
 
-Published (`package.json` `files`): `bin/grunt.js` `cli` `scripts/check-globals.mjs` `scripts/emit-agent-shell-tools.mjs` `scripts/emit-gemini.mjs` `scripts/emit-mcp-policy.mjs` `scripts/gate-fat-tools.mjs` `scripts/hooks-union.mjs` `scripts/grunt-job.mjs` `scripts/parse-need.mjs` `scripts/persist-handoff.mjs` `scripts/persist-plan.mjs` `scripts/purge-global-mcps.mjs` `scripts/scrub-spawn-prompt.mjs` `scripts/scrub-text-lib.mjs` `scripts/sync-global-settings.mjs` `scripts/telemetry.mjs` `scripts/scrub-text` `.rulesync` `.grok` `.codex` `.claude` `.agents` `AGENTS.md` `CLAUDE.md` `.mcp.json` `README.md` `LICENSE`
+Published (`package.json` `files`): `bin/grunt.js` `cli` `scripts/check-globals.mjs` `scripts/emit-agent-shell-tools.mjs` `scripts/emit-gemini.mjs` `scripts/emit-mcp-policy.mjs` `scripts/gate-fat-tools.mjs` `scripts/hooks-union.mjs` `scripts/grunt-job.mjs` `scripts/parse-need.mjs` `scripts/persist-handoff.mjs` `scripts/persist-plan.mjs` `scripts/purge-global-mcps.mjs` `scripts/scrub-spawn-prompt.mjs` `scripts/scrub-text-lib.mjs` `scripts/sync-global-settings.mjs` `scripts/telemetry.mjs` `scripts/browser.mjs` `scripts/doctor.mjs` `scripts/scrub-text` `.rulesync` `.grok` `.codex` `.claude` `.agents` `AGENTS.md` `CLAUDE.md` `.mcp.json` `README.md` `LICENSE`
 
 No `scripts/*.test.ts` `scripts/fixtures/` `docs/` `coverage/` `vitest.config.ts` in `files`.
 

package/cli/grunt.mjs

@@ -17,7 +17,7 @@ Commands:
   check         npm run rulesync:check
   sync-globals  npm run sync:globals (dry-run; --apply to write)
   purge-mcps    npm run purge:global-mcps (dry-run; --apply to write)
-  doctor        npm run rulesync:doctor
+  doctor        npm run doctor
   help          Show this help
   version       Print package version
 
@@ -163,7 +163,7 @@ async function dispatch(cmd, flags, interactive) {
     return
   }
   if (cmd === "doctor") {
-    npmRun("rulesync:doctor")
+    npmRun("doctor")
     return
   }
   process.stdout.write(USAGE)

package/cli/grunt.test.ts

@@ -37,7 +37,7 @@ Commands:
   check         npm run rulesync:check
   sync-globals  npm run sync:globals (dry-run; --apply to write)
   purge-mcps    npm run purge:global-mcps (dry-run; --apply to write)
-  doctor        npm run rulesync:doctor
+  doctor        npm run doctor
   help          Show this help
   version       Print package version
 
@@ -236,10 +236,10 @@ describe("start", () => {
     );
   });
 
-  it("doctor npm-runs rulesync:doctor", async () => {
+  it("doctor npm-runs doctor", async () => {
     process.argv = ["node", "grunt", "doctor"];
     await start();
-    expect(execFileSync).toHaveBeenCalledWith("npm", ["run", "rulesync:doctor"], {
+    expect(execFileSync).toHaveBeenCalledWith("npm", ["run", "doctor"], {
       cwd: process.cwd(),
       stdio: "inherit",
     });

package/cli/init.mjs

@@ -21,6 +21,8 @@ const PRODUCT_SCRIPTS = [
   "scrub-text-lib.mjs",
   "sync-global-settings.mjs",
   "telemetry.mjs",
+  "browser.mjs",
+  "doctor.mjs",
   "scrub-text",
 ]
 

package/cli/init.test.ts

@@ -44,6 +44,8 @@ const PRODUCT_FILES = [
   "scrub-text-lib.mjs",
   "sync-global-settings.mjs",
   "telemetry.mjs",
+  "browser.mjs",
+  "doctor.mjs",
 ];
 
 const SRC_CLAUDE_SETTINGS = {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lovrozagar/grunt",
-  "version": "0.3.11",
-  "description": "Multi-agent orchestrator SoT — deep-merge rulesync trees, product scripts, and generate pipeline into a consumer repo",
+  "version": "0.4.0",
+  "description": "Multi-agent orchestrator SoT \u2014 deep-merge rulesync trees, product scripts, and generate pipeline into a consumer repo",
   "keywords": [
     "agents",
     "grunt",
@@ -39,6 +39,8 @@
     "scripts/scrub-text-lib.mjs",
     "scripts/sync-global-settings.mjs",
     "scripts/telemetry.mjs",
+    "scripts/browser.mjs",
+    "scripts/doctor.mjs",
     "scripts/scrub-text",
     ".rulesync",
     ".grok",
@@ -64,6 +66,7 @@
     "rulesync:check": "rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,skills --check && rulesync generate -t codexcli,antigravity-cli,grokcli -f subagents --check && rulesync generate -t claudecode,codexcli,antigravity-cli -f hooks --check && node scripts/emit-mcp-policy.mjs --check && node scripts/emit-gemini.mjs --check && node scripts/emit-agent-shell-tools.mjs --check && node scripts/check-globals.mjs && node scripts/hooks-union.mjs --check",
     "hooks:union": "node scripts/hooks-union.mjs",
     "hooks:check": "node scripts/hooks-union.mjs --check",
+    "doctor": "node ./scripts/doctor.mjs",
     "rulesync:doctor": "rulesync doctor",
     "sync:globals": "node scripts/sync-global-settings.mjs",
     "sync:globals:check": "node scripts/check-globals.mjs",