@lovrozagar/grunt 0.6.2 → 0.8.0

package/.agents/skills/su/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: su
+description: 'Short status update: done, next, and blockers or on-track ETA.'
+---
+This reply only: a status update in two to four short lines. No process narration.
+
+- Done: what is finished. Flag anything unverified.
+- Next: the immediate next step.
+- Health: if stuck, blocked, broken, or slipping, say so plainly. Otherwise "On track" with a rough ETA (minutes, ~1h, end of session).
+
+Never soften bad news or claim progress not made.

package/.claude/settings.json

@@ -73,6 +73,17 @@
           }
         ]
       }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/session-map.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   },
   "enableAllProjectMcpServers": false,

package/.claude/skills/su/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: su
+description: 'Short status update: done, next, and blockers or on-track ETA.'
+---
+This reply only: a status update in two to four short lines. No process narration.
+
+- Done: what is finished. Flag anything unverified.
+- Next: the immediate next step.
+- Health: if stuck, blocked, broken, or slipping, say so plainly. Otherwise "On track" with a rough ETA (minutes, ~1h, end of session).
+
+Never soften bad news or claim progress not made.

package/.codex/hooks.json

@@ -64,6 +64,17 @@
           }
         ]
       }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/session-map.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   }
 }

package/.grok/hooks/orchestrate-parent.js

@@ -87,7 +87,6 @@ function preToolUse(data) {
       });
       return 0;
     }
-    emit({ decision: "allow" });
     return 0;
   }
   if (WRITE_TOOLS.has(toolKey)) {
@@ -96,7 +95,6 @@ function preToolUse(data) {
   }
   const fatCode = emitFat(data);
   if (fatCode !== null) return fatCode;
-  emit({ decision: "allow" });
   return 0;
 }
 
@@ -162,7 +160,7 @@ export function isUnderTmp(filePath, workspaceRoot) {
 
 function parentWrite(data, toolInput) {
   if (!toolInput || typeof toolInput !== "object" || Array.isArray(toolInput)) {
-    emit({ decision: "deny", reason: DENY_REASON });
+    emit(denyResponse(DENY_REASON));
     return 0;
   }
   const ws = workspaceRootOf(data);
@@ -200,7 +198,7 @@ function parentWrite(data, toolInput) {
       if (!isFullImplementationBody(content)) return null;
       const errors = validateImplementation(path.basename(abs), content);
       if (errors.length) {
-        emit({ decision: "deny", reason: errors.join("; ") || invalid });
+        emit(denyResponse(errors.join("; ") || invalid));
         return 0;
       }
       const next = Object.assign({}, toolInput, {
@@ -224,10 +222,7 @@ function parentWrite(data, toolInput) {
   const content = typeof toolInput.content === "string" ? toolInput.content : "";
   const result = persist({ workspaceRoot: ws, content });
   if (!result.ok) {
-    emit({
-      decision: "deny",
-      reason: result.error || invalid,
-    });
+    emit(denyResponse(result.error || invalid));
     return 0;
   }
   const next = Object.assign({}, toolInput, {

package/.grok/skills/su/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: su
+description: 'Short status update: done, next, and blockers or on-track ETA.'
+---
+This reply only: a status update in two to four short lines. No process narration.
+
+- Done: what is finished. Flag anything unverified.
+- Next: the immediate next step.
+- Health: if stuck, blocked, broken, or slipping, say so plainly. Otherwise "On track" with a rough ETA (minutes, ~1h, end of session).
+
+Never soften bad news or claim progress not made.

package/.rulesync/hooks.jsonc

@@ -25,6 +25,14 @@
         "timeout": 5
       }
     ],
+    "sessionStart": [
+      {
+        // Code-only folder map as additionalContext (hooks-union keeps it first).
+        "type": "command",
+        "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/session-map.mjs\"",
+        "timeout": 5
+      }
+    ],
     "beforeSubmitPrompt": [
       {
         "type": "command",

package/.rulesync/reference/INDEX.md

@@ -6,7 +6,7 @@ Protocol stays overview; domain fills this.
 
 ## Skills naming
 
-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`.
+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` `su` `tmp` `write-plan`.
 
 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.
 
@@ -32,6 +32,7 @@ Upgrade copies the current package trees and product scripts, then deletes cumul
 | 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. |  |  |  |
+| su | local | Short status update: done, next, and blockers or on-track ETA. |  |  |  |
 | 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}. |  |  |  |
 
@@ -43,7 +44,7 @@ Upgrade copies the current package trees and product scripts, then deletes cumul
 | .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/hooks.md | Hooks | hooks | SessionStart carries only the folder map: Claude / Codex run `../../scripts/session-map.mjs`, which injects the code-on… |
 | .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. |

package/.rulesync/reference/hooks.md

@@ -4,7 +4,7 @@ tags: [hooks]
 
 # Hooks
 
-SessionStart: keep empty (token baseline). Do not inject context. Do not register a SessionStart hook on `../../.grok/hooks/orchestrate-parent.json`.
+SessionStart carries only the folder map: Claude / Codex run `../../scripts/session-map.mjs`, which injects the code-only map from `../../scripts/folder-map.mjs` as `additionalContext` (budget 5k tokens, cache-stable, fail-open) and logs `{rows, tokens}` to `.tmp/grunt/sessions/<sid>/map.json`. Inject nothing else at SessionStart. Antigravity has no rulesync sessionStart. Do not register a SessionStart hook on `../../.grok/hooks/orchestrate-parent.json`.
 
 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`.
 

package/.rulesync/reference/law.md

@@ -4,7 +4,7 @@ Protocol stays overview; domain fills this.
 
 ## Skills naming
 
-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`.
+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` `su` `tmp` `write-plan`.
 
 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.
 

package/.rulesync/reference/refs-map.md

@@ -8,7 +8,7 @@
 | .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/hooks.md | Hooks | hooks | SessionStart carries only the folder map: Claude / Codex run `../../scripts/session-map.mjs`, which injects the code-on… |
 | .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. |

package/.rulesync/reference/skills-map.md

@@ -20,5 +20,6 @@
 | 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. |  |  |  |
+| su | local | Short status update: done, next, and blockers or on-track ETA. |  |  |  |
 | 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}. |  |  |  |

package/.rulesync/rules/overview.md

@@ -12,8 +12,10 @@ You are the session agent. Do the work. Use en-US unless asked. Write concise co
 
 Size first. Straight shot: do it. Else read `.rulesync/reference/scope.md`.
 Default `/auto`: keep going; ask on blockers. `/ask`: one step, then ask.
+Ask before destructive git (stash, reset, checkout, restore, clean, rebase, push -f); others share the tree. In a loop, skip it and edit code instead.
 
 Read `.rulesync/reference/INDEX.md` once. When a row matches the work, read that reference in full.
+Use the folder map in session context to find code. Run `node scripts/folder-map.mjs <dir>` for depth before `ls` or `find`.
 
 Large dumps are compressed (search, test logs, snaps). Scratch and dumps live in `.tmp/grunt/` (gitignored). After a write, recap the path; edit with an offset slice when you need lines.
 Fat dumps: `node scripts/grunt-job.mjs --job search|exec|slice|fetch|test` first; spawn grunt only when the dump needs judgment.

package/.rulesync/skills/su/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: su
+description: "Short status update: done, next, and blockers or on-track ETA."
+---
+This reply only: a status update in two to four short lines. No process narration.
+
+- Done: what is finished. Flag anything unverified.
+- Next: the immediate next step.
+- Health: if stuck, blocked, broken, or slipping, say so plainly. Otherwise "On track" with a rough ETA (minutes, ~1h, end of session).
+
+Never soften bad news or claim progress not made.

package/AGENTS.md

@@ -3,8 +3,10 @@ You are the session agent. Do the work. Use en-US unless asked. Write concise co
 
 Size first. Straight shot: do it. Else read `.rulesync/reference/scope.md`.
 Default `/auto`: keep going; ask on blockers. `/ask`: one step, then ask.
+Ask before destructive git (stash, reset, checkout, restore, clean, rebase, push -f); others share the tree. In a loop, skip it and edit code instead.
 
 Read `.rulesync/reference/INDEX.md` once. When a row matches the work, read that reference in full.
+Use the folder map in session context to find code. Run `node scripts/folder-map.mjs <dir>` for depth before `ls` or `find`.
 
 Large dumps are compressed (search, test logs, snaps). Scratch and dumps live in `.tmp/grunt/` (gitignored). After a write, recap the path; edit with an offset slice when you need lines.
 Fat dumps: `node scripts/grunt-job.mjs --job search|exec|slice|fetch|test` first; spawn grunt only when the dump needs judgment.

package/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-03
+
+### Added
+
+- `grunt map [dir]` / `node scripts/folder-map.mjs [dir]`: code-only folder map (folders only, git-tracked, gitignore applied). Package rows show name and full path; pass-through chains collapse; 12+ leaf dirs fold; 5k-token breadth-first budget with fair share; depth cap counts from package roots. Optional `.rulesync/grunt.map.jsonc`
+- Claude / Codex SessionStart hook `scripts/session-map.mjs` injects the folder map and logs `{rows, tokens}` per session
+- `/su` skill: short status update (done, next, blockers or on-track ETA)
+- Root rule: ask before destructive git; in a loop, skip it and edit code instead
+
+### Fixed
+
+- PreToolUse hooks no longer print top-level `decision: "allow"` / `"deny"`, which Claude rejected on every tool call; allow is empty stdout and deny is `block` plus `permissionDecision: "deny"`, so denies are enforced
+- Fat-tool gate no longer rewrites compound shell (`|`, `;`, `&&`, heredocs) into grunt-job, which never ran them; rewritten queries are single-quoted so backticks and `$` stay literal
+- Re-init replaces a grunt-owned SessionStart group instead of duplicating it
+
+## [0.7.0] - 2026-09-30
+
+### Added
+
+- Package manager detection for init/generate/check/doctor/setup: lockfile or `package.json` `"packageManager"`, then how grunt was launched, then TTY ask. `--pm npm|yarn|pnpm|bun` overrides. Non-interactive with no signal fails instead of assuming npm.
+
+### Fixed
+
+- Init no longer forces `npm install` / `npm run`
+- Init keeps `@lovrozagar/grunt` in `devDependencies` (moves it out of `dependencies` when present; adds it when missing)
+- Init INDEX/skills-map/refs-map are generated from the dest tree (grunt refs plus consumer extras) instead of copying the package maps
+- Init writes root `.mcp.json` when dest is missing it
+
 ## [0.6.2] - 2026-09-17
 
 ### Changed

package/README.md

@@ -23,23 +23,26 @@ OSS drop-in; merges existing configs; switches default provider flow to Grunt.
 ## Install
 
 - Node.js 22+
-- Consumer:
+- Consumer (devDependency; init moves it there if it landed in `dependencies`):
 
 ```
-npm i -D @lovrozagar/grunt
-npm exec grunt
+npm i -D @lovrozagar/grunt && npm exec grunt
+pnpm add -D @lovrozagar/grunt && pnpm exec grunt
+yarn add -D @lovrozagar/grunt && yarn grunt
+bun add -D @lovrozagar/grunt && bunx grunt
 ```
 
-- Same as `npm exec grunt init` when no command
-- Do not `npm test` as a consumer
-- Package: `@lovrozagar/grunt` `0.6.0` MIT · https://github.com/lovrozagar/grunt
+- Same as `grunt init` when no command
+- Do not run this package's test script as a consumer
+- Package: `@lovrozagar/grunt` MIT · https://github.com/lovrozagar/grunt
+- Package manager: lockfile or `package.json` `"packageManager"`, then how grunt was launched, then TTY ask. `--pm npm|yarn|pnpm|bun` overrides. Non-interactive with no signal fails (does not assume npm).
 
 ## Prerequisites
 
 All OS. Print-only. Never auto-install.
 
 ```
-npm exec grunt doctor
+grunt doctor
 node scripts/doctor.mjs
 ```
 
@@ -47,7 +50,8 @@ Exit 1 if any required missing; 0 if all required ok. Optional tools are reporte
 
 | tool | required | install |
 | --- | --- | --- |
-| node ≥22 + npm | yes | https://nodejs.org (≥22) · nvm / OS pkg · win `winget install OpenJS.NodeJS.LTS` |
+| node ≥22 | yes | https://nodejs.org (≥22) · nvm / OS pkg · win `winget install OpenJS.NodeJS.LTS` |
+| package manager | yes | npm (ships with Node ≥22) · yarn/pnpm `corepack enable` · bun https://bun.sh · detected from the repo, else how grunt was launched |
 | 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) |
@@ -61,7 +65,7 @@ Exit 1 if any required missing; 0 if all required ok. Optional tools are reporte
 | whisper-cli | no | local STT for `/listen` · mac `brew install whisper-cpp` · first listen downloads `ggml-base.en.bin` · setup in `.rulesync/reference/listen.md` |
 | listen | no | `node scripts/listen.mjs` · STT input · `grunt setup` / `node scripts/setup.mjs listen` · local whisper.cpp then OpenAI Whisper |
 
-Rulesync schema doctor is separate: `npm run grunt:rulesync:doctor`.
+Rulesync schema doctor is separate: `grunt:rulesync:doctor` (or SoT `rulesync:doctor`).
 
 ## Usage
 
@@ -73,14 +77,15 @@ Rulesync schema doctor is separate: `npm run grunt:rulesync:doctor`.
 
 ### Commands
 
-- `init` → `init()` — merge SoT, `npm install`, `grunt:rulesync:generate`, `grunt:sync:globals:apply`, `grunt:rulesync:check`
-- `generate` → `npm run grunt:rulesync:generate`
-- `check` → `npm run grunt:rulesync:check`
-- `sync-globals` → `npm run grunt:sync:globals` (dry-run); `--apply` → `grunt:sync:globals:apply`
-- `purge-mcps` → `npm run grunt:purge:global-mcps` (dry-run); `--apply` → `grunt:purge:global-mcps:apply`
-- `doctor` → `npm run grunt:doctor` (`npm exec grunt doctor` / `node scripts/doctor.mjs` stay). Rulesync schema: `npm run grunt:rulesync:doctor`
-- `setup` → `npm run grunt:setup` (`node scripts/setup.mjs`) — handheld speak / listen / google-workspace / browser. TTY walks each; flags for non-TTY keys/`--creds`
+- `init` → `init()` — merge SoT, install, `grunt:rulesync:generate`, `grunt:sync:globals:apply`, `grunt:rulesync:check`
+- `generate` → run `grunt:rulesync:generate`
+- `check` → run `grunt:rulesync:check`
+- `sync-globals` → run `grunt:sync:globals` (dry-run); `--apply` → `grunt:sync:globals:apply`
+- `purge-mcps` → run `grunt:purge:global-mcps` (dry-run); `--apply` → `grunt:purge:global-mcps:apply`
+- `doctor` → run `grunt:doctor` (`grunt doctor` / `node scripts/doctor.mjs` stay). Rulesync schema: `grunt:rulesync:doctor`
+- `setup` → run `grunt:setup` (`node scripts/setup.mjs`) — handheld speak / listen / google-workspace / browser. TTY walks each; flags for non-TTY keys/`--creds`
 - `upgrade` → same merge as init for an already-inited repo: copy owned trees/scripts, prune retired grunt-owned names, print reserved skill names
+- `map [dir]` → code-only folder map (`scripts/folder-map.mjs`); no package manager needed. See [Folder map](#folder-map)
 - `help`
 - `version`
 
@@ -90,25 +95,31 @@ Rulesync schema doctor is separate: `npm run grunt:rulesync:doctor`.
 - `--yes` / `-y` / `--non-interactive` — no TTY menu; default command still `init`. Not `--apply`
 - `--apply` — write for `sync-globals` / `purge-mcps`
 - `--host <id>` — `sync-globals --host <id>`
+- `--pm <name>` — `npm` | `yarn` | `pnpm` | `bun`
 
 ## Init
 
-- Merge SoT `npm install` `grunt:rulesync:generate` `grunt:sync:globals:apply` `grunt:rulesync:check`
+- Merge SoT, install with the detected package manager, `grunt:rulesync:generate` `grunt:sync:globals:apply` `grunt:rulesync:check`
+- `@lovrozagar/grunt` is a consumer devDependency. Init moves it out of `dependencies` when it is there, and adds it when missing.
+- INDEX / skills-map / refs-map are generated from the dest `.rulesync` tree (grunt files plus consumer extras). Package copies of those maps are not stamped over dest.
+- Root `.mcp.json` is created when missing; generate still merges from `.rulesync/mcp-policy.jsonc`.
 - `--skip-globals` skips apply
 - TTY init asks `Apply global prompt optimizations? (recommended)` (default Yes; `--skip-globals` defaults No)
 - Non-interactive re-init auto-skips globals when `<!-- grunt:begin -->` in `AGENTS.md`/`CLAUDE.md`
 - First init (no sentinel) applies globals unless flagged
 - Owned trees/scripts refresh; extra `.rulesync` files kept; patches to grunt-owned files lost
 - `cp` cannot delete dest extras. Init/upgrade then prune: retired skills `parent` `solo` `cascade`, agents `implementer` `thinker` (plus `.grok/roles/{implementer,thinker}.toml` and `.gemini/agents/{name}/`), scripts `telemetry.mjs` `grunt-config.mjs`, paths `.grok/parent.md` `.grok/skills/shared` `.rulesync/grunt.config.jsonc` plus local overlay and example, and reserved skill dirs this package no longer ships. Consumer extras stay.
-- Breaking: consumer npm scripts are `grunt:<SoT-key>` (`grunt:rulesync:generate`, `grunt:doctor`). Re-init migrates `package.json` (owned unprefixed keys + suffixes; `npm run` refs in other dest scripts). CI/husky/`npm run rulesync:*` / `npm run doctor` must switch. No aliases. SoT repo scripts stay unprefixed (`npm run rulesync:generate`).
+- Breaking: consumer scripts are `grunt:<SoT-key>` (`grunt:rulesync:generate`, `grunt:doctor`). Re-init migrates `package.json` (owned unprefixed keys + suffixes; `npm|yarn|pnpm|bun run` refs in other dest scripts). CI/husky/`run rulesync:*` / `run doctor` must switch. No aliases. SoT repo scripts stay unprefixed (`rulesync:generate`).
 
 ## Version bump
 
 Already-inited consumer (0.5.x → 0.6, and later):
 
 ```
-npm i -D @lovrozagar/grunt@latest
-npm exec grunt upgrade
+npm i -D @lovrozagar/grunt@latest && npm exec grunt upgrade
+pnpm add -D @lovrozagar/grunt@latest && pnpm exec grunt upgrade
+yarn add -D @lovrozagar/grunt@latest && yarn grunt upgrade
+bun add -D @lovrozagar/grunt@latest && bunx grunt upgrade
 ```
 
 `upgrade` is init plus a reserved-names print. Same merge, prune, and globals-skip rules as Init. New skills/scripts appear because they are in the package copy list. Dropped grunt-owned files disappear only if they are on the retired lists (or a reserved skill this package no longer ships). Do not expect a blind dest-dir mirror-delete; that would wipe consumer extras.
@@ -134,7 +145,7 @@ Lightpanda-first session CLI: `node scripts/browser.mjs`. Zero MCP. Zero env kno
 
 Present under `.claude` / `.rulesync` / `.agents` / `.grok` (`rulesync -f skills` mirrors SSOT):
 
-- `ask` `auto` `browser` `clasp` `commit` `commit-and-push` (1-release alias → `commit-push`) `commit-push` `commit-push-deploy` `commit-push-release` `explain` `google-workspace` `handoff` `implement-plan` `listen` `pickup` `speak` `tmp` `write-plan`
+- `ask` `auto` `browser` `clasp` `commit` `commit-and-push` (1-release alias → `commit-push`) `commit-push` `commit-push-deploy` `commit-push-release` `explain` `google-workspace` `handoff` `implement-plan` `listen` `pickup` `speak` `su` `tmp` `write-plan`
 
 `/auto` (default) keeps going and asks on blockers. `/ask` finishes one step, recaps, then asks. `/auto` returns the session to auto.
 
@@ -155,7 +166,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` = rulesync check. `doctor` = unified prereqs. Schema: `npm run rulesync:doctor`.
+`check` = rulesync check. `doctor` = unified prereqs. Schema: `rulesync:doctor`.
 
 Emit writes other-CLI trees from `.rulesync` for the **next** process of that CLI. Not a live hop into another host.
 
@@ -166,11 +177,34 @@ Emit writes other-CLI trees from `.rulesync` for the **next** process of that CL
 - `sync-globals` / `purge-mcps`: dry-run default; `--apply` writes
 - Hosts: grok claude codex gemini antigravity
 
+### Folder map
+
+Claude and Codex get a folder map at SessionStart (`scripts/session-map.mjs`), so agents skip `ls`/`find` loops. Agents run `node scripts/folder-map.mjs <dir>` (same as `grunt map <dir>`) for depth. Grok and Antigravity get the `AGENTS.md` line only.
+
+- Folders only, never files. Source: `git ls-files --cached --others --exclude-standard`, so gitignored paths never show
+- A folder shows when it or a descendant holds a code file (`codeExt`) and no path segment is a dot dir or in `skip`
+- Package roots (`package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`) show `# name  repo/relative/path`
+- Pass-through single-child chains collapse (`a/b/c/`). 12+ plain leaf dirs under one parent fold into one row
+- Budget (chars ÷ 4): breadth-first per top-level subtree; on overflow, cheapest subtrees first with an equal share; cut dirs end in `…` (the header names the command). Depth cap counts from the nearest package root
+- Size per session: `.tmp/grunt/sessions/<sid>/map.json`
+
+Optional `.rulesync/grunt.map.jsonc` (missing or invalid → defaults):
+
+| key | default | |
+|---|---|---|
+| `budget` | `5000` | tokens |
+| `depthCap` | `6` | levels below a package root |
+| `foldAt` | `12` | leaf dirs before folding |
+| `codeExt` | `ts tsx js jsx mjs cjs py go rs sql vue svelte astro` | |
+| `skip` | `_gen gen generated dist build assets static public fixtures __fixtures__ __snapshots__ __mocks__ testdata vendor migrations locales i18n` | segment names |
+| `include` | `[]` | globs always shown (`*` one segment, `**` any) |
+| `exclude` | `[]` | globs never shown |
+
 ### Secrets (machine)
 
 Not git. Not `sync-globals`.
 
-First-hand: `npm exec grunt setup` (TTY). Per target: `node scripts/setup.mjs speak|listen|google-workspace|browser`. Spec: `.rulesync/reference/setup.md`.
+First-hand: `grunt setup` (TTY). Per target: `node scripts/setup.mjs speak|listen|google-workspace|browser`. Spec: `.rulesync/reference/setup.md`.
 
 | | where |
 | --- | --- |