@lovrozagar/grunt 0.5.0 → 0.6.0

package/.rulesync/reference/INDEX.md

@@ -2,42 +2,55 @@
 
 # Law
 
-Protocol stays cascade/overview; domain fills this.
+Protocol stays overview; domain fills this.
 
 ## Skills naming
 
-Reserved (do not reuse in consumer custom skills): `browser` `cascade` `commit` `commit-and-push` `commit-push` `commit-push-deploy` `commit-push-release` `explain` `handoff` `implement-plan` `parent` `pickup` `solo` `write-plan`.
+Reserved (do not reuse in consumer custom skills): `ask` `auto` `browser` `clasp` `commit` `commit-and-push` `commit-push` `commit-push-deploy` `commit-push-release` `explain` `google-workspace` `handoff` `implement-plan` `listen` `pickup` `speak` `tmp` `write-plan`.
 
-Override: same name → one SSOT path (`.rulesync/skills/<name>/`). Re-init force-refresh overwrites grunt-owned names; consumer extras kept. Maps `origin` badge ≠ content picker.
+Override: same name → one SSOT path (`.rulesync/skills/<name>/`). Re-init / `grunt upgrade` force-refresh overwrites grunt-owned names; consumer extras kept. Maps `origin` badge ≠ content picker.
+
+Upgrade copies the current package trees and product scripts, then deletes cumulative retired grunt-owned names (skills `parent` `solo` `cascade`; agents `implementer` `thinker`; scripts `telemetry.mjs` `grunt-config.mjs`; paths `.grok/parent.md` `.grok/skills/shared` `.rulesync/grunt.config.jsonc` `.rulesync/grunt.config.local.jsonc` `.rulesync/grunt.config.local.jsonc.example`) and any reserved skill dir this package no longer ships. `fs.cpSync` does not remove dest extras; prune is what drops them. Consumer skills/refs/scripts not on those lists stay.
 
 # Skills
 
 | name | origin | description | task | commandPath | refs |
 | --- | --- | --- | --- | --- | --- |
-| browser | local | Session browser rail. /browser or browse a URL. Call node scripts/browser.mjs nav\|snap\|click\|fill\|shot\|pdf\|stop. Lightp… |  |  |  |
-| cascade | local | Session mode. /cascade exits solo and restores the grunt cascade for this session — spawn, orchestrator, recap, need\|ve… |  |  |  |
+| ask | local | Session flag. Finish one step, recap, then ask before the next. |  |  |  |
+| auto | local | Session flag. Default. Work the task through. Ask on blockers instead of monkey-patching. |  |  |  |
+| browser | local | Browse via node scripts/browser.mjs (Lightpanda). App e2e uses Playwright. |  |  |  |
+| clasp | local | Low-level Apps Script CLI. Prefer /google-workspace for sheet, doc, meeting, mail. |  |  |  |
 | commit | local | Inspect the diff and commit with a Conventional Commits subject line. Use for /commit, "commit this", "commit these cha… |  |  |  |
 | commit-and-push | local | Alias of commit-push (1-release stub). Use for /commit-and-push, "commit and push", "commit this and push". Must push.… |  |  |  |
 | commit-push | local | Commit with a Conventional Commits subject, then push. Use for /commit-push, "commit and push", "commit this and push".… |  |  |  |
 | commit-push-deploy | local | Commit, push, then deploy only if allowlisted infra already exists. Use for /commit-push-deploy, "commit push deploy",… |  |  |  |
 | commit-push-release | local | Commit, push, bump package.json, tag vX.Y.Z, push the tag. CI publishes. Use for /commit-push-release, "commit push rel… |  |  |  |
-| explain | local | One-off human recap. /explain. First action = spawn grunt\|implementer\|thinker if facts/work; else recap already-visible… |  |  |  |
-| handoff | local | Parent writes a session handoff under .tmp/grunt/handoffs/ and tells the user to continue in a fresh session. Use for /… |  |  |  |
-| implement-plan | local | Implementer executes a local .tmp/plans checklist: continue, resume, or pick among plans. Empty /implement-plan resumes… |  |  |  |
-| parent | local | One-turn parent-orchestrator escape. Use for /parent. Not a session mode. |  |  |  |
-| pickup | local | Pick up/continue a session handoff under .tmp/grunt/handoffs/. Use for /pickup, pick up, continue handoff, serial, drag… |  |  |  |
-| solo | local | Session mode. /solo disables the grunt cascade for this session — one normal agent, no spawn, no orchestrator. /cascade… |  |  |  |
-| write-plan | local | Thinker drafts a local implementer-ready checklist plan; parent Write persists .tmp/plans/{serial}-{slug}-{YYYYMMDDTHHM… |  |  |  |
+| explain | local | Longer human recap this reply only. |  |  |  |
+| google-workspace | local | Google Sheets, Docs, Slides, Calendar, Gmail via node scripts/google-workspace.mjs. |  |  |  |
+| handoff | local | Write a session handoff under .tmp/grunt/handoffs/. Continue with /pickup. |  |  |  |
+| implement-plan | local | Execute remaining leaves in a .tmp/grunt/plans checklist. Skip [x]. |  |  |  |
+| listen | local | Speech-to-text via node scripts/listen.mjs (ffmpeg mic + local whisper.cpp, OpenAI fallback). Input only. |  |  |  |
+| pickup | local | Continue a handoff under .tmp/grunt/handoffs/. |  |  |  |
+| speak | local | Text-to-speech via node scripts/speak.mjs (ElevenLabs or OpenAI). Output only. |  |  |  |
+| tmp | local | Dump a one-off convo artifact under .tmp/grunt/. |  |  |  |
+| write-plan | local | Write a local checklist under .tmp/grunt/plans/. Then /implement-plan {n}. |  |  |  |
 
 # Refs
 
 | path | title | tags | summary |
 | --- | --- | --- | --- |
-| .rulesync/reference/browser.md | Browser | browser | Zero-config in-tree session rail. Not MCP. Not env. Not raw Playwright. |
-| .rulesync/reference/cascade.md | Cascade | cascade | Shipped protocol: **parent-only spawn**. Only the parent **orchestrator** session calls `spawn_subagent`. Implementer a… |
+| .rulesync/reference/browser.md | Browser | browser | Zero-config in-tree session rail. Not MCP. Not env. Not raw Playwright. Lightpanda first; swap to Chromium when blocked. |
+| .rulesync/reference/cascade.md | Protocol | cascade | The session agent has tools. Fat Read/Grep/Bash dumps are rewritten to `scripts/grunt-job.mjs` (squeez + stash). Isolat… |
+| .rulesync/reference/clasp.md | Clasp | clasp | Low-level Apps Script CLI. Optional. Doctor reports it. |
+| .rulesync/reference/google-workspace.md | google-workspace | google-workspace | Create and edit Google Sheets, Docs, Slides, Calendar events, and Gmail from the session. |
 | .rulesync/reference/hooks.md | Hooks | hooks | SessionStart: keep empty (token baseline). Do not inject context. Do not register a SessionStart hook on `../../.grok/h… |
-| .rulesync/reference/law.md | Law |  | Protocol stays cascade/overview; domain fills this. |
+| .rulesync/reference/implementation-format.md | Implementation format (SSOT) |  | Local session journal for `/implement-plan`. Not a plan, handoff, or git commit. |
+| .rulesync/reference/law.md | Law |  | Protocol stays overview; domain fills this. |
+| .rulesync/reference/listen.md | Listen | listen | Speech-to-text from the session. Input only. Not TTS. Not a live voice agent. Not MCP. |
 | .rulesync/reference/map.md | Map | map | Cheap outline. Not a file dump. |
-| .rulesync/reference/output.md | Output | output | en-US unless asked. every output maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. Parent and child. E… |
-| .rulesync/reference/plan-format.md | Plan format (SSOT) |  | Local implementer checklist. Not a design doc, PR stack, or DAG. |
+| .rulesync/reference/output.md | Output | output | en-US unless asked. Concise complete sentences with natural grammar. Skip filler and fluff. |
+| .rulesync/reference/plan-format.md | Plan format (SSOT) |  | Local session checklist. Not a design doc, PR stack, or DAG. |
 | .rulesync/reference/rtk.md | RTK | rtk | Shell stdout compression. PreToolUse: Bash → `rtk <cmd>`. Not Read/Grep/Glob/prompts/images. |
+| .rulesync/reference/scope.md | Scope | scope | Default: do the work. Escalate only when it is not a straight shot. This file is the size-gate SSOT. |
+| .rulesync/reference/setup.md | Setup | setup | Handheld machine setup for optional integrations. Any OS. Secrets stay in `~/.grunt/` (Windows `%USERPROFILE%\.grunt`).… |
+| .rulesync/reference/speak.md | Speak | speak | Text-to-speech from the session. Output only. Not STT. Not a mic. Not MCP. Speech-to-text is `/listen`: `.rulesync/refe… |

package/.rulesync/reference/browser.md

@@ -4,13 +4,13 @@ tags: [browser]
 
 # Browser
 
-Zero-config in-tree session rail. Not MCP. Not env. Not raw Playwright.
+Zero-config in-tree session rail. Not MCP. Not env. Not raw Playwright. Lightpanda first; swap to Chromium when blocked.
 
 ```
-node scripts/browser.mjs nav|snap|click|fill|shot|pdf|stop|doctor|ensure
+node scripts/browser.mjs nav|snap|click|fill|scroll|wait|hover|select|shot|pdf|stop|doctor|ensure
 ```
 
-Default engine: **Lightpanda** (`lightpanda` on PATH). Chromium only when a rule below requires it.
+Default engine: **Lightpanda** (`lightpanda` on PATH). Chromium when a rule below requires it. Never report "can't browse" while Chromium is available.
 
 ## Verbs
 
@@ -20,6 +20,10 @@ Default engine: **Lightpanda** (`lightpanda` on PATH). Chromium only when a rule
 | `snap` | markdown + numbered AX refs (default read) |
 | `click <ref>` | click a ref from last `snap` |
 | `fill <ref> <text>` | fill a ref from last `snap` |
+| `scroll [ref|down|up|N]` | scroll a snap ref into view, or the window |
+| `wait [ms]` | pause (default 1000, cap 15000) |
+| `hover <ref>` | hover a snap ref |
+| `select <ref> <value>` | set a select/option value |
 | `shot` | screenshot (Chromium paint) |
 | `pdf` | PDF (Chromium paint) |
 | `stop` | reap engine pid; clear session; idempotent |
@@ -30,7 +34,7 @@ Session + profile + artifacts: `.tmp/grunt/browser/` only.
 
 ## Install
 
-Run `grunt doctor` / `node scripts/doctor.mjs`. See README Prerequisites.
+Run `grunt doctor` / `node scripts/doctor.mjs`. Handheld engine hints (no keys): `node scripts/setup.mjs browser`. Doctor/setup is enough. Do not read a README unless those are missing; then https://github.com/lovrozagar/grunt#prerequisites (not the consumer README).
 
 ## Engine
 
@@ -40,9 +44,12 @@ Chromium immediately when any of:
 
 - verb is `shot` | `pdf` | `trace`
 - `process.platform === "win32"`
-- paint-host URL (tiny set): figma, Google docs / sheets / slides, mail.google, earth
+- Chromium-first host: figma, Google docs / sheets / slides, mail.google, earth, amazon
 - `lightpanda` missing from PATH and a Chromium binary is present
 - Lightpanda probe fails **once** → one Chromium replay of last URL; no loop
+- `snap` on Lightpanda is empty, a bot/JS wall, or client-rendered junk → one Chromium replay, then snap again
+
+The session agent does not invent a "can't" for Amazon or other client-rendered sites. The rail swaps. One swap cap. App e2e stays Playwright (`playwright test`), not this CLI.
 
 No user env. Never `GRUNT_BROWSER*`. Never `LIGHTPANDA_CDP_URL`.
 
@@ -50,7 +57,7 @@ No user env. Never `GRUNT_BROWSER*`. Never `LIGHTPANDA_CDP_URL`.
 
 - MCP browser servers
 - user env knobs
-- raw Playwright as the agent tool
+- raw Playwright as the browse tool (Playwright is the app e2e runner)
 - grunt `job:browse`
 - teaching thinker / orchestrator to browse
 

package/.rulesync/reference/cascade.md

@@ -2,92 +2,14 @@
 tags: [cascade]
 ---
 
-# Cascade
+# Protocol
 
-Shipped protocol: **parent-only spawn**. Only the parent **orchestrator** session calls `spawn_subagent`. Implementer and thinker never spawn. Isolation is a **grunt sibling**. See [map](map.md).
+The session agent has tools. Fat Read/Grep/Bash dumps are rewritten to `scripts/grunt-job.mjs` (squeez + stash). Isolation facts stay ≤8 lines.
 
-## Parent orchestrator
+Run `node scripts/grunt-job.mjs --job search|exec|slice|fetch|test` first. Spawn a grunt model only when the dump needs judgment (browse snap, messy test log). Isolation work may run as grunt.
 
-Always-do lives in orchestrator/overview (do not open this file first). Peek/kill/`need:` stay here as reference.
-⚠ / validate / sim → spawn implementer; not stop.
-Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.
+`need:` JSON (search|exec|slice|fetch) may be intercepted in-hook (cap 4). Peek/kill if a child is running: Grok `get_command_or_subagent_output` `timeout_ms=60000`. Other hosts: block on spawn return.
 
-Always spawn + prompt. First token = spawn. Parent Read/Bash deny expected if forgotten. Only `/solo` (session stamp) escapes spawn workflow. `/parent` is last-ditch hook stamp not skill-instructed Read/Bash. No try-then-spawn. No parent probe. No tiny-read/grep/list_dir/bash/grunt-job for the user. No skip-spawn.
-Create/change product files → grunt facts first; then thinker advise/plan/stop unless small/simple or prompt-is-spec → implementer. Default without detailed spec = grunt check → thinker advise/plan → stop. Advise-first stop wins until unlock. Unlock implementer only on: numbered/label pick1 or pick2 or `/implement-plan {n}` or explicit implement (=pick1). `ok`/`yes`/`y`/`continue` ≠ either implement path (`continue` = write-plan file gate only). Thinker recap alone ≠ spec-ready; do not auto-implement. Conversational advise recap = stop.
-Advise leftover: numbered pick each on own line after tagged recap (not same-line):
-1. Implementer with verbal plan
-2. Implementer with file plan
-3. Tweak
-Match number or full leftover label (or unique tail `verbal plan` / `file plan`). Always-do leftover match; not Skill-name (`2` ≠ write-plan). 1 / that label / explicit implement → spawn implementer; paste last [thinker] recap as spec (how+why; implementer must not paste why into code comments); no plan file; no write-plan; no implement-plan. Bare `implement`/`implementer` → pick1 only (shared prefix; do not substring-match both picks). 2 / that label → persist `.tmp/plans/{n}` then spawn implementer with `plan=/abs/...` path only (write-plan then implement-plan one-shot; skip inspect pause; no user slash). Parent still no Write — existing write-plan path/skill sequencing. 3 / Tweak → stay advise; no implementer. Extra user text = revision notes → thinker; bare 3/Tweak = stop wait notes. `/write-plan` persist-only inspect-pause; remainder ask `/implement-plan {n}`. Not a leftover number. `/implement-plan {n}` stays disk/file run; ≠ conversational verbal pick. Disk leftover may invoke without user slash; verbal ≠ implement-plan.
-Never parent Write/Edit/Bash/Skill-that-writes. Child returned is not terminal if writes remain after that gate or spawn count is 0 on a pick1/pick2/`/implement-plan {n}`/spec/small file-change turn. plan/spec ready + writes remain → spawn implementer only on that gate; else recap-stop. plan-only `/write-plan` → recap + remainder `/implement-plan` (ask).
+Session flags: `/auto` (default) keeps going and asks on blockers instead of monkey-patching. `/ask` finishes one step, recaps, then asks. Slash `/ask` stamps `.tmp/grunt/orchestrator-logs/session-gate-{sid}`; `/auto` unlinks.
 
-Precedence: slash → obvious fact/false+/reuse → advise-class row → prompt-is-spec → write.
-1. Tools (facts / search / exec / git / web / test / low-reason mechanical write) → grunt. Facts/search → grunt, never thinker.
-2. Write defined solution (prompt-is-spec or small/simple) → implementer. **Blocked if advise-class stems present** unless prompt-is-spec / obvious comment-spec false+. Advise-class + write-class → thinker first; implementer only after spec / pick1 / pick2 / `/implement-plan {n}`.
-3. Think / plan / advise / recommend / how / why / explain (ask-us; not slash `/explain`; not one-cmd/last-log/source-token) → thinker. Facts=grunt/`need:`. **No implementer this turn**. Unsure → thinker. Cheap false+: I think / terraform plan / `/implement-plan` / `/solo` / source tokens / one-cmd / how- last-log / why. Why = judgment not patch not dump; parent cannot invent why; **parent cannot drop why**. Thinker recap without why = incomplete (leftover 3 / re-spawn; not silent; not invent). One re-spawn max then recap-as-is + flag.
-   Reuse iff ALL: (1) same parent transcript already has finished `[thinker]:` (or the fact recap they’re poking); (2) user turn is advise-class again with no new path/error/snippet/name/“what about/also/now/but/instead”; (3) no implementer or grunt after that answer; no unresolved `need:`; (4) not “more/deeper/details/walk through/wrong”. Any tick fail / new session / `/pickup` / `/handoff` / compaction ate the body → spawn. Echo last `[thinker]:` recap one-line (don’t paraphrase; no-strip why; no compress-to-verdict). Advise leftover still adds numbered pick on own lines. Prose → `/explain` on visible child. Always-why recap ≠ `/explain`. Not grunt for parrot. Tag `[orchestrator]:` on no-spawn — don’t fake `[thinker]:`. Pitfalls: deeper→thinker; code moved invalidates; `need:` open; compaction.
-4. Fresh/world facts → grunt `job: web`. Never answer from memory.
-
-Spawn only `grunt` | `implementer` | `thinker`. Omit `model`. Isolation `none` unless asked.
-
-Implementer may tiny-Read/Grep/list_dir. Thinker named-file Read of prompt SSOT only; investigate/search/trees → `need:` grunt. Fat dumps via `need:` JSON.
-
-Long parent sessions rely on two-pass compaction; prefer a new parent session per task rather than unbounded resume chains. `[features] two_pass_compaction = true` must live in `~/.grok/config.toml` (from `.grok/global-settings.toml` via `npm run sync:globals` dry-run / `npm run sync:globals:apply`). Project `.grok/config.toml` cannot set `[features]`. Do not add a SessionStart hook.
-
-## Wait / peek
-
-Parent-only. Non-blocking spawn so each child has a host id immediately. Per-child, not one global timer.
-Every 60s peek is real host status (no `sleep` then guess). `timeout_ms=60000` every peek.
-Quote host fields only (`status`, elapsed since spawn, last activity/output snippet) or quote the error. Never invent.
-Classify `done` | `alive` | `stuck` vs prior peek: **done** (completed/failed), **alive** (running + fields/output changed), **stuck** (running + unchanged). Unchanged snippet = stuck, not “still working”.
-Loop until done. No auto-kill. Kill only if the user asks and the host has a kill tool.
-Final recap uses [output.md](output.md) natural buckets (completed / in-flight / remainder / blocker; omit empty). Do not redo the child's work. Exceptions: in-flight wait = `[orchestrator]: wait grunt` only; `need:` stop = JSON only; max 3 `resume_from` → blocker recap + gathered verdicts (ask).
-
-Parent Stop (`MAX_STOP=3`): do not waive fenced/impl finals for `tools-used` stamp. Parent `end_turn` is tagged recap (advise leftover numbered pick on own lines after) or `[orchestrator]: wait grunt`. First non-empty line must match legal `[orchestrator|grunt|implementer|thinker|handoff]:`. Advise leftover numbered pick may follow the tagged recap (format only; hook does not map `1`/`2`/`3` → skills). Siblings still run → role tag + one-line echo. In-flight wait recap is `[orchestrator]: wait grunt` only. Mid-turn stays exactly `[orchestrator]: wait grunt`. Or consume `parent-escape-{sid}` once. Else block. No `isCheap` / trivia / long definitions.
-`/handoff` is the other in-parent turn: context large + work unfinished → parent writes one `.tmp/grunt/handoffs/` file from its own transcript (no child sees the session), recaps `[handoff]: serial=… path=…`, tells the user to continue in a new session. No spawn, one write, not a mode.
-`/pickup` is spawn-first pickup, not in-parent write; parent never Read. Inverse of `/handoff`.
-`/solo` is the session mode (not one-turn): `beforeSubmitPrompt` writes `.tmp/orchestrator-logs/grunt-off-{sid}`, every gate short-circuits while it exists, `/cascade` unlinks it. Everything above resumes next turn. Antigravity: skill-only, no stamp create (see hooks.md). `/parent` is last-ditch hook stamp (not a mode, not skill-instructed Read/Bash): UserPromptSubmit writes `.tmp/orchestrator-logs/parent-escape-{sid}`; Stop consumes+unlinks once. Next Stop resumes spawn/recap rules. `/explain` is human recap after children; never parent Read; not a mode; not spawn-escape. Skills point here; do not paste this file. Never parent-Read protocol files.
-
-Host mapping (in-tree only; do not invent peek/kill APIs). GAP rows: no fake peeks, no auto-kill.
-
-| Host | Spawn | Peek | Kill |
-| --- | --- | --- | --- |
-| Grok | `spawn_subagent` `background:true` → `task_id` | `get_command_or_subagent_output` + `timeout_ms=60000` | `kill_command_or_subagent` (user-ask only) |
-| Claude Code | `Agent` if the parent session exposes it | GAP unless an in-tree schema names a status/output tool on that id (do not invent `TaskOutput`); else block on Agent return and classify `done`. Agent launch ≠ child done; in-flight host Stop → only `[orchestrator]: wait grunt`; no SendMessage | GAP unless in-tree; no auto-kill |
-| Codex | host agent/call | GAP; block on host agent/call return; classify `done` | GAP; no auto-kill |
-| Antigravity | main-session parent | GAP peek/kill; main-session parent | GAP; no auto-kill |
-| Gemini | not emitted; tracked gap | GAP; no fake peeks | GAP; no auto-kill |
-
-## Late dump (`need:` + `resume_from`)
-
-If implementer/thinker still needs a fat dump: it **stops**. The stop message for dumps is this JSON line only (no prose):
-
-```
-need: [{"job":"search","query":"..."}]
-```
-
-`job` ∈ search|exec|web|test. 1–N jobs. Cap one batch at 4 jobs; overflow stays for the next loop. Do not emit N sequential single-job stops for known-parallel dumps.
-
-If a child still emits `need:` and every job is `search|exec`, SubagentStop (and child `Stop` with `subagentType`) runs grunt-job in-hook and continues the child with concatenated `verdict:` blobs (`decision: "block"` + `additionalContext`). Mixed / web / test batches are not intercepted: parent `scripts/parse-need.mjs` + LLM grunt. Thinker has no bash; intercept still applies.
-
-Parent: parse with `scripts/parse-need.mjs` (same grammar). If parse succeeds, fan out those jobs as parallel grunt spawns; do not interpret surrounding prose. Wait; one `resume_from: <child id>` with **new** `verdict:` blobs only. Do not fresh-spawn. Max 3 `resume_from` for one child id; then parent blocker recap + the verdicts already gathered (ask).
-
-Resume prompt = `You are {agent} subagent.` plus the new verdicts. Do not re-send the original task, cascade, or prior verdicts (`resume_from` already has the transcript).
-
-Voice: [output](output.md). Does not change need:/verdict:/plan grammar.
-
-## Isolation grunt `verdict:`
-
-```
-verdict: ok|fail|empty
-n: <count>
-- path:line — fact
-```
-
-Fail: first 3 error lines. ≤8 lines. No dumps, recap, HTML, JSON, full logs.
-
-Implementer/thinker: fat dumps via `need:` JSON. Implementer shell via rtk; cat/rg/curl/tests without rtk → fat `need:`.
-
-Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.
-
-Grok PostToolUse is observe-only. SessionStart stays empty (token baseline). See [hooks](hooks.md).
+Scratch: `.tmp/grunt/`. Stash: `.tmp/grunt/stash/`. Sessions: `.tmp/grunt/sessions/{sid}/`. Browser: `.tmp/grunt/browser/`.

package/.rulesync/reference/clasp.md

@@ -0,0 +1,21 @@
+---
+tags: [clasp]
+---
+
+# Clasp
+
+Low-level Apps Script CLI. Optional. Doctor reports it.
+
+For create/edit sheet, doc, slide, meeting, or mail, use **google-workspace**: `.rulesync/reference/google-workspace.md` and `node scripts/google-workspace.mjs`. Do not start from clasp.
+
+```
+npm i -g @google/clasp
+clasp login
+clasp create --type standalone --title <name>
+clasp pull
+clasp push
+clasp run <function>
+clasp status
+```
+
+Script files live next to `appsscript.json`. Git tracks them. `clasp run` needs the Apps Script API and an API-executable deployment. That path is for custom `.gs`, not day-to-day Workspace.

package/.rulesync/reference/google-workspace.md

@@ -0,0 +1,79 @@
+---
+tags: [google-workspace]
+---
+
+# google-workspace
+
+Create and edit Google Sheets, Docs, Slides, Calendar events, and Gmail from the session.
+
+```
+node scripts/google-workspace.mjs whoami
+node scripts/google-workspace.mjs scopes
+node scripts/google-workspace.mjs login
+node scripts/google-workspace.mjs sheet create --title "Q3" --csv "item,qty\nA,2"
+node scripts/google-workspace.mjs sheet set --id ID --cell A1 --value x
+node scripts/google-workspace.mjs sheet get --id ID --range A1:B10
+node scripts/google-workspace.mjs sheet append --id ID --csv "c,3"
+node scripts/google-workspace.mjs sheet clear --id ID --range A1:Z
+node scripts/google-workspace.mjs doc create --title "Notes" --body "hello"
+node scripts/google-workspace.mjs doc append --id ID --body "more"
+node scripts/google-workspace.mjs drive list --query "mimeType='application/vnd.google-apps.spreadsheet'"
+node scripts/google-workspace.mjs slide create --title "Deck"
+node scripts/google-workspace.mjs meeting create --title "Standup" --start 2026-09-15T09:00:00Z --end 2026-09-15T09:15:00Z --attendees a@x.com,b@y.com
+node scripts/google-workspace.mjs mail send --to you@example.com --subject hi --body hello
+node scripts/google-workspace.mjs mail list
+```
+
+Each person has their own Google Cloud app. Creds stay in `~/.grunt/` on that machine. Do not share OAuth JSON or tokens. Do not commit them. Inviting others to a meeting is attendee emails, not shared creds.
+
+Handheld (any OS): `node scripts/setup.mjs google-workspace` or `npm exec grunt setup` → google-workspace. Opens each Cloud Console page, waits, copies the Desktop JSON into `~/.grunt/google-oauth.json`, then browser Allow. Non-TTY: `--creds PATH` to a Desktop download. `--account NAME` for a second Google user.
+
+Doctor reports google-workspace as optional: `ok` when Desktop OAuth JSON, tokens, gcloud ADC, or `~/.clasprc.json` exists, else `missing (optional)`. It prints source names (`oauth` `tokens` `adc` `clasprc`), not secrets. `clasprc` is Drive-only.
+
+Two Google accounts on one machine: `--account NAME` (or `WORKSPACE_ACCOUNT`). Default is `default` (legacy files `~/.grunt/google-oauth.json` + `workspace-tokens.json` still work). Other accounts use `~/.grunt/workspace/NAME/`.
+
+```
+node scripts/google-workspace.mjs --account work login
+node scripts/google-workspace.mjs --account work whoami
+node scripts/google-workspace.mjs accounts
+```
+
+Each account needs its own Desktop JSON in that folder (`google-oauth.json`) and its own `login`.
+
+Clasp’s public OAuth client is Drive-only. Calendar and Gmail are restricted; Google blocks extra scopes on that app. Use **your** Desktop OAuth client.
+
+## Agent: setup e2e
+
+If `whoami` works but `meeting` / `mail` / `sheet set` fail with missing scope or “app is blocked”, run **this user** through `node scripts/setup.mjs google-workspace` (TTY). Do not reuse another person’s JSON. Do not invent a client JSON.
+
+Local dir is created by setup (`~/.grunt/`, mode 700 on Unix). Manual equivalent: `mkdir -p "$HOME/.grunt" && chmod 700 "$HOME/.grunt"` then:
+
+1. Open `https://console.cloud.google.com/projectcreate` — **Create**. Org can be their Workspace org. Note **Project ID** from the dashboard URL (`?project=`).
+2. Open `https://console.cloud.google.com/auth/overview/create?project=PROJECT_ID` (or **Google Auth Platform → Branding**).
+   - App name: anything (`autorun` is fine). That string is only the Allow screen.
+   - User support email: their address.
+   - Audience: **Internal** if the Google account is a paid Workspace org (e.g. `@rearm.co`). **Testing** + add their own address as a test user if it is a personal `@gmail.com` (Internal is not offered). APIs work on both; only this consent type changes.
+   - Next / Create through the wizard.
+3. Open `https://console.cloud.google.com/flows/enableapi?apiid=calendar-json.googleapis.com,gmail.googleapis.com,sheets.googleapis.com,docs.googleapis.com,drive.googleapis.com&project=PROJECT_ID` — **Enable**.
+4. Open `https://console.cloud.google.com/auth/clients/create?project=PROJECT_ID`.
+   - Application type: **Desktop app**.
+   - Create → **Download JSON**.
+5. Copy the download to `$HOME/.grunt/google-oauth.json` (Windows: `%USERPROFILE%\.grunt\google-oauth.json`). chmod 600 on Unix. Confirm it has `"installed"` and `client_id`. For `--account NAME`, use `$HOME/.grunt/workspace/NAME/google-oauth.json`.
+6. From the repo: `node scripts/google-workspace.mjs login` (or `--account NAME`) — browser Allow. Tokens write beside the JSON (`workspace-tokens.json` or `workspace/NAME/tokens.json`).
+7. Smoke:
+
+```
+node scripts/google-workspace.mjs whoami
+node scripts/google-workspace.mjs scopes
+node scripts/google-workspace.mjs sheet create --title smoke-sheet --csv "k,v\nok,1"
+node scripts/google-workspace.mjs doc create --title smoke-doc --body ok
+node scripts/google-workspace.mjs slide create --title smoke-slide
+node scripts/google-workspace.mjs meeting create --title smoke-meeting --start 2026-09-16T09:00:00Z --end 2026-09-16T09:15:00Z
+node scripts/google-workspace.mjs mail send --to THEIR_EMAIL --subject smoke --body ok
+```
+
+`scopes` must include `calendar`, `gmail.modify` or `gmail.send`, `spreadsheets`, `documents`, `drive`. If login times out, they did not finish Allow; re-run `login`.
+
+If `google-oauth.json` is missing, `login` prints `setup: node scripts/setup.mjs google-workspace`. Prefer the handheld setup (it opens the Project ID URLs). Manual steps above still work.
+
+`gcloud` on PATH is an alternate login (`gcloud auth application-default login` with the extra scopes). Still per person, still local.

package/.rulesync/reference/hooks.md

@@ -6,20 +6,18 @@ tags: [hooks]
 
 SessionStart: keep empty (token baseline). Do not inject context. Do not register a SessionStart hook on `../../.grok/hooks/orchestrate-parent.json`.
 
-Grok PostToolUse / UserPromptSubmit / SessionStart are observe-only — do not attempt output scrub; compress via RTK / spawn / isolation verdict only. Do not add PostToolUse scrub hooks.
+Grok PostToolUse / SessionStart are observe-only — do not attempt output scrub; compress via RTK / spawn / isolation facts only. Do not add PostToolUse scrub hooks. Grok UserPromptSubmit may emit a one-line `sessionGate=auto|ask` plus session receipt (`hookSpecificOutput.additionalContext`). Skip host Stop banners. `/ask` exact-match slash stamps `session-gate-{sid}` to `ask`. `/auto` unlinks. Sid-less: no stamp. Default: `auto`.
 
-Claude / Codex / Antigravity PreToolUse still run `../../scripts/scrub-spawn-prompt.mjs` and `../../scripts/gate-fat-tools.mjs`. Grok does not — spawn/fat rewrite is `../../.grok/hooks/orchestrate-parent.js` only. RTK stays `../../.grok/hooks/rtk.json`.
+In `sessionGate=ask`, parent Stop on `end_turn` blocks unless the recap asks (`?`) or is exactly `[orchestrator]: wait grunt`. Reason: `ask after this step`. Cap 3. `sessionGate=auto` does not Stop-block.
 
-Parent Read|Write|Edit|Bash|Skill deny unless `/solo` (session) or `/parent` last-ditch stamp. Grok PreToolUse has no matcher (Read included). Skills spawn-first; do not instruct parent Read/Bash. `.tmp/plans/` and `.tmp/grunt/handoffs/` Write still persist. Parent Bash still allowed for workspace `../../scripts/grunt-job.mjs` `--job search|exec`. Children with a type skip parent-deny (fat-only). Skill allowlist without escape: `parent|explain|solo|cascade|handoff|pickup|write-plan|implement-plan`. Deny reason: `First action=spawn implementer|grunt|thinker. Deny expected. Only /solo this session escapes.`. Parent `end_turn` is tagged recap (advise leftover numbered pick on own lines after) or `[orchestrator]: wait grunt`. Mid-turn stays exactly `[orchestrator]: wait grunt`.
+Claude / Codex / Antigravity PreToolUse still run `../../scripts/scrub-spawn-prompt.mjs` and `../../scripts/gate-fat-tools.mjs`. Grok spawn/fat rewrite is `../../.grok/hooks/orchestrate-parent.js`. RTK stays `../../.grok/hooks/rtk.json`.
 
-Parent `run_terminal_command` is deny-by-default except `node` (optional leading `rtk`) invoking `{workspace}/scripts/grunt-job.mjs` with `--job search|exec` and `--query`. Optional `--path` `--glob` (repeatable) `--cwd`. Not `web|test`, not other scripts. META strips `--query` value first so `|` inside query is allowed; pipes/`&&` outside query still deny. Never `cd &&`. Exec shell-meta in query is grunt-job FALLBACK (exit 2), not a parent-bash allow. Unknown flags → FALLBACK.
+Session agent tools are on. Fat Read/Grep/Glob/Bash still gate. Writes under `.tmp/grunt/plans/`, `.tmp/grunt/handoffs/`, `.tmp/grunt/implementations/`, and `.tmp/grunt/` root files persist via `../../scripts/persist-plan.mjs` / `persist-handoff.mjs` / `persist-implementation.mjs` / `persist-tmp.mjs`. Invalid body denies.
 
-SubagentStop (and child Stop with `subagentType`) intercepts a parseable `need:` whose jobs are all `search|exec` (cap 4): runs grunt-job in-hook and continues the child with concatenated `verdict:` blobs. Mixed/web/test, parse fail, FALLBACK, `stopHookActive`, or more than 3 intercepts per child session → empty stdout (allow stop; parent LLM path). Parent `write` is deny-by-default except `.tmp/plans/` (`../../scripts/persist-plan.mjs`) and `.tmp/grunt/handoffs/` (`../../scripts/persist-handoff.mjs`); both validate + rewrite path/content, invalid body denies. Parent Stop (`MAX_STOP=3`): do not waive impl finals for `tools-used`. Parent `end_turn` is tagged recap (advise leftover numbered pick on own lines after) or `[orchestrator]: wait grunt`. Mid-turn stays exactly `[orchestrator]: wait grunt`. First non-empty line must match legal `[orchestrator|grunt|implementer|thinker|handoff]:`. Claude Agent launch ≠ done; in-flight host Stop → wait recap `[orchestrator]: wait grunt` only; no SendMessage. Or consume `parent-escape-{sid}` once (`/parent` last-ditch, not “use parent tools”). No `isCheap` / trivia. Stamps: `tools-used` / `stop-block` / `need-intercept` / `parent-escape`. Skills point to cascade; do not paste protocol here.
+SubagentStop (and child Stop with `subagentType`) intercepts a parseable `need:` whose jobs are all `search|exec|slice|fetch` (cap 4): runs grunt-job in-hook and continues the child with concatenated facts. Mixed/web/test, parse fail, FALLBACK, `stopHookActive`, or more than 3 intercepts per child session → empty stdout (allow stop).
 
-`/solo` writes `grunt-off-{sid}`; `/cascade` unlinks it (`beforeSubmitPrompt`, exact-match only). While set: PreToolUse allows parent tools (fat gate still runs) and skips the `defaultGrunt` spawn rewrite; Stop returns 0 **before** the `parent-escape` consume, so solo never burns the one-turn stamp. Session-scoped, fail-closed.
+Stop and SubagentStop timeout is 30s (grunt-job cap is 20s). PreToolUse / UserPromptSubmit stay at 5s.
 
-rulesync canonical event is `beforeSubmitPrompt` (→ Claude/Codex `UserPromptSubmit`), not `userPromptSubmit` — an unknown key makes Zod reject the whole `.rulesync/hooks.jsonc`, emitting nothing while `--check` still reports up to date. Antigravity supports neither `beforeSubmitPrompt` nor `subagentStop`; `/solo` degrades there to the skill body alone.
-
-Stop and SubagentStop timeout is 30s (grunt-job cap is 20s). PreToolUse / PostToolUse / UserPromptSubmit stay at 5s. If the intercept times out, the hook fail-opens and the child stops without verdicts.
+rulesync canonical event is `beforeSubmitPrompt` (→ Claude/Codex `UserPromptSubmit`), not `userPromptSubmit`.
 
 `[features] two_pass_compaction` must live in `~/.grok/config.toml` (from `.grok/global-settings.toml` via `npm run sync:globals` / `npm run sync:globals:apply`). Project `.grok/config.toml` cannot set `[features]`.

package/.rulesync/reference/implementation-format.md

@@ -0,0 +1,113 @@
+# Implementation format (SSOT)
+
+Local session journal for `/implement-plan`. Not a plan, handoff, or git commit.
+
+Created when `/implement-plan` starts. Straight shots skip this file. Do not merge into the plan (plan = flip the box only).
+
+## Path
+
+`.tmp/grunt/implementations/{serial}-{slug}-{YYYYMMDDTHHMMSSZ}.md`
+
+- **serial:** own counter (not plan serials). Unpadded decimal int ≥ 1. Never `0001`.
+- **filename:** unpadded serial, slug, UTC datetime stamp. Same regex as new plans: `^[0-9]+-[a-z0-9]+(-[a-z0-9]+)*-\d{8}T\d{6}Z\.md$`
+- **lookup:** integer equality on leading digits.
+- Frontmatter `serial:` line must match `^serial: [1-9][0-9]*$`.
+- New writes always stamped. Collision: increment serial, same stamp.
+
+## Link
+
+Frontmatter `plan:` is the plan serial (`6`) or `none`. Own serial stays independent.
+
+## Slugify / allocate
+
+Same as plans (`slugify`, `nextSerial` on this dir). Body line 1: `IMPL_NAME: <3-6 word name>`. Optional `IMPL_PLAN: <n|none>` (default `none`).
+
+## Frontmatter (required)
+
+```yaml
+---
+serial: 1
+plan: 6                 # unpadded int or none
+name: add-auth
+status: in-progress     # in-progress | done | blocked
+created: 2026-08-26T14:30:00Z
+source: "<≤120 chars of user task>"
+---
+```
+
+### Status machine
+
+`in-progress` → `done` | `blocked`
+
+- Fresh write: `in-progress`
+- Plan Verify done and journal caught up: `done`
+- Cannot finish: `blocked` (`## Blockers` must not be `(none)`)
+
+## Body headings (this order only)
+
+`# {slug}`, `## Done`, `## Issue`, `## Files`, `## Log`, `## Blockers`, `## Notes`
+
+No other `##` headings.
+
+| Section | Amount |
+|---|---|
+| Done | bullets. What landed and why. Past tense. Fresh: `(none)` |
+| Issue | bug root cause bullets, or `(none)` |
+| Files | repo-relative product paths as `- path` bullets. Default `/commit` stage set. No abs paths. No `.tmp/`. Fresh: `(none)` |
+| Log | append-only. Fresh: `(none)`. After each plan leaf: `N.M [x] one line` (notes, fail, skip). `[x]` allowed |
+| Blockers | open problems. `(none)` unless `status: blocked` |
+| Notes | short leftovers, or `(none)` |
+
+## Write
+
+Write under `.tmp/grunt/implementations/` (any filename in that dir). Grok `orchestrate-parent.js` runs `scripts/persist-implementation.mjs` on create (`IMPL_NAME:`): serial/slug from the name, injects frontmatter, rewrites path + content. Updates to an existing file keep the path; full-body writes are validated in place. Invalid create/update denies — fix the body, do not retry elsewhere.
+
+Host without that hook: name the file per **Path**, or pipe the body to `node scripts/persist-implementation.mjs --workspace {repo}` and use its `path`.
+
+Never allocate a new serial to log a leaf. Append Log, update Files/Done, flip the plan box.
+
+## Validation checklist
+
+- filename stamped unpadded; serial int equals leading digits; `name` equals slug
+- frontmatter keys: `serial`, `plan`, `name`, `status`, `created`, `source`
+- `plan` is `none` or unpadded int ≥ 1; `status` ∈ `in-progress` | `done` | `blocked`
+- headings in order only; no extra `##`
+- Done / Issue / Files / Log / Blockers / Notes: bullets and/or `(none)`; none of those sections empty
+- Files: repo-relative; reject abs and `.tmp/`
+- `status: blocked` ⇒ Blockers is not only `(none)`
+
+## Worked example
+
+File: `.tmp/grunt/implementations/1-add-tmp-ignore-20260826T143000Z.md`
+
+```markdown
+---
+serial: 1
+plan: 6
+name: add-tmp-ignore
+status: in-progress
+created: 2026-08-26T14:30:00Z
+source: "gitignore .tmp so local plans stay untracked"
+---
+
+# add-tmp-ignore
+
+## Done
+- Repo `.gitignore` ignores `.tmp/` so plans stay untracked
+
+## Issue
+(none)
+
+## Files
+- .gitignore
+
+## Log
+1.1 [x] read existing gitignore
+1.2 [x] appended .tmp/
+
+## Blockers
+(none)
+
+## Notes
+(none)
+```

package/.rulesync/reference/law.md

@@ -1,9 +1,11 @@
 # Law
 
-Protocol stays cascade/overview; domain fills this.
+Protocol stays overview; domain fills this.
 
 ## Skills naming
 
-Reserved (do not reuse in consumer custom skills): `browser` `cascade` `commit` `commit-and-push` `commit-push` `commit-push-deploy` `commit-push-release` `explain` `handoff` `implement-plan` `parent` `pickup` `solo` `write-plan`.
+Reserved (do not reuse in consumer custom skills): `ask` `auto` `browser` `clasp` `commit` `commit-and-push` `commit-push` `commit-push-deploy` `commit-push-release` `explain` `google-workspace` `handoff` `implement-plan` `listen` `pickup` `speak` `tmp` `write-plan`.
 
-Override: same name → one SSOT path (`.rulesync/skills/<name>/`). Re-init force-refresh overwrites grunt-owned names; consumer extras kept. Maps `origin` badge ≠ content picker.
+Override: same name → one SSOT path (`.rulesync/skills/<name>/`). Re-init / `grunt upgrade` force-refresh overwrites grunt-owned names; consumer extras kept. Maps `origin` badge ≠ content picker.
+
+Upgrade copies the current package trees and product scripts, then deletes cumulative retired grunt-owned names (skills `parent` `solo` `cascade`; agents `implementer` `thinker`; scripts `telemetry.mjs` `grunt-config.mjs`; paths `.grok/parent.md` `.grok/skills/shared` `.rulesync/grunt.config.jsonc` `.rulesync/grunt.config.local.jsonc` `.rulesync/grunt.config.local.jsonc.example`) and any reserved skill dir this package no longer ships. `fs.cpSync` does not remove dest extras; prune is what drops them. Consumer skills/refs/scripts not on those lists stay.

package/.rulesync/reference/listen.md

@@ -0,0 +1,80 @@
+---
+tags: [listen]
+---
+
+# Listen
+
+Speech-to-text from the session. Input only. Not TTS. Not a live voice agent. Not MCP.
+
+```
+node scripts/listen.mjs whoami
+node scripts/listen.mjs devices
+node scripts/listen.mjs rec [--seconds 8] [--device D] [--clip]
+node scripts/listen.mjs start [--device D]
+node scripts/listen.mjs stop [--clip]
+node scripts/listen.mjs toggle [--clip]
+node scripts/listen.mjs status
+node scripts/listen.mjs file --path clip.wav [--clip]
+node scripts/listen.mjs latest
+```
+
+`rec` records then transcribes (default 8s, cap 120s). `toggle` is the hotkey verb: first run starts, second run stops and prints the transcript. Audio and `latest.txt` live under `.tmp/grunt/listen/`. `--cwd /path/to/repo` when the hotkey does not already run in the repo.
+
+## Auth and capture
+
+Handheld (any OS): `node scripts/setup.mjs listen` or `npm exec grunt setup` → listen. Prints OS install commands for ffmpeg / whisper-cli (does not run them), optional ggml download into `~/.grunt/whisper/`, OpenAI fallback key if local STT is missing.
+
+If ffmpeg, whisper-cli, a ggml model, or `OPENAI_API_KEY` is missing, the CLI prints `setup: node scripts/setup.mjs listen` and exits 1. Agents should show that line, not a stack or JSON. Do not invent a key.
+
+STT prefers **local whisper.cpp**. Install the binary; the first `listen` downloads `ggml-base.en.bin` (~142MB) into `~/.grunt/whisper/`. No API cost after that. If the binary or download is missing, it falls back to OpenAI `whisper-1` (`OPENAI_API_KEY` or `~/.grunt/speak.json`). Force with `LISTEN_STT=local` or `LISTEN_STT=openai`. Never commit keys.
+
+| | env | `~/.grunt/speak.json` |
+| --- | --- | --- |
+| Local model | `WHISPER_MODEL` | `listen.whisperModel` |
+| Force engine | `LISTEN_STT` | `listen.stt` (`auto` / `local` / `openai`) |
+| OpenAI key | `OPENAI_API_KEY` | `openai.apiKey` |
+| OpenAI model | `LISTEN_MODEL` | `listen.model` (default `whisper-1`) |
+| Device | `LISTEN_DEVICE` | `listen.device` |
+| Seconds | `LISTEN_SECONDS` | `listen.seconds` |
+
+### Local Whisper (preferred)
+
+One install:
+
+- mac: `brew install whisper-cpp` (provides `whisper-cli`)
+- linux: build https://github.com/ggml-org/whisper.cpp (`whisper-cli` on PATH)
+- win: whisper.cpp release `whisper-cli.exe` on PATH
+
+Then `node scripts/listen.mjs whoami` or `rec`. The first run fetches `ggml-base.en.bin` to `~/.grunt/whisper/`. Do not pip-install OpenAI Whisper. Do not curl the model yourself unless the auto-download fails.
+
+Larger models: put another `ggml-*.bin` in that folder or set `WHISPER_MODEL`. Doctor reports `whisper-cli` as optional. `whoami` prints `stt=local` or `stt=openai`.
+
+### ffmpeg (mic only)
+
+- mac: `brew install ffmpeg`
+- linux: `sudo apt install ffmpeg`
+- win: `winget install Gyan.FFmpeg`
+
+`file` and `latest` work without a mic. Doctor reports ffmpeg as optional.
+
+`rec` detaches ffmpeg and does not attach it to the IDE TTY. AVFoundation can stall forever on a VS Code / Electron PTY even when Visual Studio Code already has Microphone access.
+
+Default devices: mac `:0` (AVFoundation audio 0), linux Pulse `default` (ALSA if the id is `hw:…`), Windows requires `--device` or `LISTEN_DEVICE` from `listen devices`.
+
+## Hotkeys
+
+Bind one key to toggle. Include `--clip` so the transcript is on the clipboard as well as `latest.txt`.
+
+```
+node /ABS/grunt/scripts/listen.mjs toggle --clip --cwd /ABS/grunt
+```
+
+Replace `/ABS/grunt` with the repo root.
+
+- **mac:** Shortcuts (Run Shell Script) or skhd: `hyper - r : node /ABS/grunt/scripts/listen.mjs toggle --clip --cwd /ABS/grunt`
+- **win:** PowerToys Keyboard Manager or AutoHotkey: `^!r:: Run, node C:\ABS\grunt\scripts\listen.mjs toggle --clip --cwd C:\ABS\grunt, C:\ABS\grunt, Hide`
+- **linux:** desktop custom shortcut or sxhkd to the same command.
+
+No daemon. Each keypress is one CLI. First press records; second press transcribes.
+
+`--clip` uses `pbcopy` (mac), `clip` (win), or `wl-copy` / `xclip` / `xsel` (linux).