@lovrozagar/grunt 0.10.0 → 0.11.0

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

@@ -5,18 +5,18 @@
 | path | title | tags | summary |
 | --- | --- | --- | --- |
 | .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/cascade.md | Protocol | cascade | The session agent has tools. Fat Read/Grep/Bash dumps are rewritten to `.rulesync/scripts/grunt-job.mjs` (squeez + stas… |
 | .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 carries only the folder map: Claude / Codex run `../../scripts/session-map.mjs`, which injects the code-on… |
+| .rulesync/reference/hooks.md | Hooks | hooks | SessionStart carries only the folder map: Claude / Codex run `../../.rulesync/scripts/session-map.mjs`, which injects t… |
 | .rulesync/reference/implementation-format.md | Implementation format (SSOT) |  | Local session journal for `/implement-plan`. Not a plan, handoff, or git commit. |
 | .rulesync/reference/jev.md | Jev | jev | Closed external decision. The source text is already saved. The question is a yes/no or a named choice. One call. Not o… |
 | .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. Concise complete sentences with natural grammar. Skip filler and fluff. |
+| .rulesync/reference/output.md | Output | output | en-US unless asked. Concise complete sentences with natural grammar. Skip filler and fluff. Examples are a class. |
 | .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/scope.md | Scope | scope | Plan by default. A straight shot is the exception. The plan caps the result, so its depth scales with the work. This fi… |
 | .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/rtk.md

@@ -24,4 +24,4 @@ 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).
+**lightpanda:** browser-rail CDP via `.rulesync/scripts/browser.mjs` (not MCP, not env).

package/.rulesync/reference/scope.md

@@ -4,34 +4,32 @@ tags: [scope]
 
 # Scope
 
-Default: do the work. Escalate only when it is not a straight shot. This file is the size-gate SSOT.
+Plan by default. A straight shot is the exception. The plan caps the result, so its depth scales with the work. This file is the size-gate SSOT.
 
 ## Gate
 
-Straight shot: one obvious path, the user named the edit, or a follow-up on work already agreed. Do it. Do not run this file as a ritual.
+Straight shot: one file, one obvious edit, nothing to decide. Do it. Also skip planning for questions, lookups, commits, a follow-up inside an approved plan, and an explicit "just do it".
 
-Not a straight shot: ambiguous goal, two or more valid approaches, cross-cutting, or hard to undo — or the user asked to plan.
+Plan: two or more files, two or more items in the message, two or more valid approaches, cross-cutting or hard-to-undo work, or the user asked to plan. A named goal is not a named edit.
 
-Skip the loop: questions, lookups, one-file named edits, "just do it", commits.
-
-`/ask` is not this loop. `/ask` pauses after each execution step. This loop pauses until the approach is agreed. `/auto` already treats a real choice as a blocker; "which approach?" is that blocker.
+`/ask` is not this loop. `/ask` pauses after each execution step. This loop pauses on questions and on the plan. `/auto` continues after approval; it does not skip approval.
 
 ## Research
 
-Read and search until you can pick an approach. Enough to choose, not a literature review. Fat notes go under `.tmp/grunt/` (`/tmp` if they must persist). Do not add `## Research` to a plan.
+Read and search until every leaf is defensible and needs no re-planning. Depth scales with stakes and ambiguity: a clear task needs enough to write the leaves; an unclear, cross-cutting, or hard-to-undo one needs the alternatives checked against the code, docs, and data. Fat notes go under `.tmp/grunt/`.
 
-## Suggest
+## Questions
 
-5–10 lines: approach, why, rejected alternative, one open question. Not a fake plan. Do not `/write-plan` in the same turn.
+Ask only what research cannot settle and what changes the plan's shape: intent, scope, a trade-off the user owns. Batch them into one round, each with your recommendation. Research again on each answer, and ask again only if a new plan-shaping gap appears. When research settles everything, skip this step and write the plan in one shot.
 
-## Wait
+## Plan
 
-Stop. One real question. Feedback → research if needed → suggest again. Repeat until the approach is agreed.
+`/write-plan`. Format: `.rulesync/reference/plan-format.md`. The plan is the proposal: the chosen approach and its rejected alternative sit in Context or Constraints. A minor open choice is written as the default plus "confirm"; a plan-shaping one goes back to Questions. Report the goal, phases, top risks, open assumptions, and path, then stop for approval.
 
-## Plan
+## Approval
 
-After agreement only: `/write-plan`. Format: `.rulesync/reference/plan-format.md`. Distill facts into Context, Constraints, Watch-outs. Leaves are the work. Report serial. Stop unless the user said plan and do it.
+Feedback revises the same plan file; research again if needed. Stop again until the user approves. Approval is the user saying go, or an explicit "plan and do it" in the request.
 
 ## Implement
 
-`/implement-plan` in a separate turn, or the same turn only if the user said plan and do it. Skip `[x]`. Write-allowlist = paths listed in the plan. Do not skip test leaves. Journal: `.rulesync/reference/implementation-format.md` under `.tmp/grunt/implementations/` (create on start; not for straight shots). Straight-shot behavior change: run the nearest existing test if the repo has one. Bugfix: repro first. Do not scaffold a test file on a straight shot unless it is a bug.
+`/implement-plan` after approval, in the same turn only on an explicit "plan and do it". Skip `[x]`. Write-allowlist = paths listed in the plan. Do not skip test leaves. Journal: `.rulesync/reference/implementation-format.md` under `.tmp/grunt/implementations/` (create on start; not for straight shots). Straight-shot behavior change: run the nearest existing test if the repo has one. Bugfix: repro first. Do not scaffold a test file on a straight shot unless it is a bug.

package/.rulesync/reference/setup.md

@@ -8,15 +8,15 @@ Handheld machine setup for optional integrations. Any OS. Secrets stay in `~/.gr
 
 ```
 npm exec grunt setup
-node scripts/setup.mjs
-node scripts/setup.mjs speak
-node scripts/setup.mjs listen
-node scripts/setup.mjs google-workspace
-node scripts/setup.mjs browser
-node scripts/setup.mjs jev
+node .rulesync/scripts/setup.mjs
+node .rulesync/scripts/setup.mjs speak
+node .rulesync/scripts/setup.mjs listen
+node .rulesync/scripts/setup.mjs google-workspace
+node .rulesync/scripts/setup.mjs browser
+node .rulesync/scripts/setup.mjs jev
 ```
 
-TTY: menu with ok/missing. The menu lists enabled packs and always lists browser and jev. A pack is enabled when `.rulesync/grunt.features.jsonc` names it. `node scripts/setup.mjs <pack>` when that pack is off prints how to enable it (`grunt init` or `grunt upgrade`) and exits 1. Already ok asks redo (`--redo` skips the ask). Missing bins: print the OS command (never run it), then re-check PATH. Ends with one status line per listed target. Non-TTY needs flags (keys / `--creds`). Doctor never installs bins; setup never installs bins either.
+TTY: menu with ok/missing. The menu lists enabled packs and always lists browser and jev. A pack is enabled when `.rulesync/grunt.features.jsonc` names it. `node .rulesync/scripts/setup.mjs <pack>` when that pack is off prints how to enable it (`grunt init` or `grunt upgrade`) and exits 1. Already ok asks redo (`--redo` skips the ask). Missing bins: print the OS command (never run it), then re-check PATH. Ends with one status line per listed target. Non-TTY needs flags (keys / `--creds`). Doctor never installs bins; setup never installs bins either.
 
 | target | what it writes | flags |
 | --- | --- | --- |

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

@@ -6,7 +6,7 @@
 | --- | --- | --- | --- | --- | --- |
 | 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. |  |  |  |
+| browser | local | Browse via node .rulesync/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.… |  |  |  |
@@ -14,13 +14,13 @@
 | 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 | Longer human recap this reply only. |  |  |  |
-| google-workspace | local | Google Sheets, Docs, Slides, Calendar, Gmail via node scripts/google-workspace.mjs. |  |  |  |
+| google-workspace | local | Google Sheets, Docs, Slides, Calendar, Gmail via node .rulesync/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]. |  |  |  |
-| jev | local | Yes/no or named-option decision on text already saved. Run node scripts/jev.mjs --available first. On yes, one decision… |  |  |  |
-| listen | local | Speech-to-text via node scripts/listen.mjs (ffmpeg mic + local whisper.cpp, OpenAI fallback). Input only. |  |  |  |
+| jev | local | Yes/no or named-option decision on text already saved. Run node .rulesync/scripts/jev.mjs --available first. On yes, on… |  |  |  |
+| listen | local | Speech-to-text via node .rulesync/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. |  |  |  |
+| speak | local | Text-to-speech via node .rulesync/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/reference/speak.md

@@ -4,21 +4,21 @@ tags: [speak]
 
 # Speak
 
-Text-to-speech from the session. Output only. Not STT. Not a mic. Not MCP. Speech-to-text is `/listen`: `.rulesync/reference/listen.md` and `node scripts/listen.mjs`.
+Text-to-speech from the session. Output only. Not STT. Not a mic. Not MCP. Speech-to-text is `/listen`: `.rulesync/reference/listen.md` and `node .rulesync/scripts/listen.mjs`.
 
 ```
-node scripts/speak.mjs whoami
-node scripts/speak.mjs voices [--provider elevenlabs|openai]
-node scripts/speak.mjs say --text "hello" [--provider elevenlabs|openai] [--voice ID] [--out path] [--play]
+node .rulesync/scripts/speak.mjs whoami
+node .rulesync/scripts/speak.mjs voices [--provider elevenlabs|openai]
+node .rulesync/scripts/speak.mjs say --text "hello" [--provider elevenlabs|openai] [--voice ID] [--out path] [--play]
 ```
 
 `say` writes an mp3 under `.tmp/grunt/speak/` (or `--out`) and prints the path. `--play` is local `afplay` (mac) or `ffplay`.
 
 ## Auth
 
-Handheld (any OS): `node scripts/setup.mjs speak` or `npm exec grunt setup` → speak. Opens the key page, hides the paste, writes `~/.grunt/speak.json`, verifies. Non-TTY: `--elevenlabs-key` / `--openai-key`.
+Handheld (any OS): `node .rulesync/scripts/setup.mjs speak` or `npm exec grunt setup` → speak. Opens the key page, hides the paste, writes `~/.grunt/speak.json`, verifies. Non-TTY: `--elevenlabs-key` / `--openai-key`.
 
-If a key is missing or rejected, the CLI prints `setup: node scripts/setup.mjs speak` and exits 1. Agents should show that line, not a stack or JSON. Do not invent a key.
+If a key is missing or rejected, the CLI prints `setup: node .rulesync/scripts/setup.mjs speak` and exits 1. Agents should show that line, not a stack or JSON. Do not invent a key.
 
 One key is enough. Never commit it.
 

package/.rulesync/rules/overview.md

@@ -8,16 +8,20 @@ targets:
 globs:
   - "**/*"
 ---
-You are the session agent. Do the work. Use en-US unless asked. Write concise complete sentences with natural grammar. Skip filler and fluff. Ship optimal solutions only; rewrite if not. Flag blockers. Do not monkey-patch. When advising, recommend the optimal choice based on research, data, and reasoning, not the user's preference. Change it only for new evidence or a flaw found in it. Pushback or a leading question is not a reason to switch; keep the recommendation and explain why. Do and verify the work yourself with every tool and credential you have. Don't guess, say "likely" or similar, trust older memory, stop short, leave placeholders, or hand the user anything you could do. Ask only when you truly lack the means, and say what you tried. Keep all work free of AI attribution, Co-Authored-By, trailers, and generated markers.
+You are the session agent. Do the work. Use en-US unless asked. Write concise complete sentences with natural grammar. Skip filler and fluff. Ship optimal solutions only; rewrite if not. Flag blockers. Do not monkey-patch. When advising, recommend the optimal choice based on research, data, and reasoning, not the user's preference. Change it only for new evidence or a flaw found in it. Pushback or a leading question is not a reason to switch; keep the recommendation and explain why. Do and verify the work yourself with every tool and credential you have. Don't guess, say "likely" or similar, trust older memory, stop short, leave placeholders, or hand the user anything you could do. Stopping for approval of a written plan is not stopping short. Ask only when you truly lack the means (the user's intent and preferences count), and say what you tried. Keep all work free of AI attribution, Co-Authored-By, trailers, and generated markers.
 
-Size first. Straight shot: do it. Else read `.rulesync/reference/scope.md`.
+Examples are a class. `...`, `etc` / etcetera, and a `;` between specimens are that same class. An example, an open list, or a negative example means infer the class and do what reasonably fits this case, including what they did not name. Do not copy the example's words, stop at the named items, or add work outside the class. In a plan or a spawn prompt, pass the class. A `;` in code or an ordinary clause is not that cue. Closed instructions stay literal. Detail: `.rulesync/reference/output.md`.
+
+A question or a work result opens with the verdict, the counts, or the outcome, failures included. The middle is the concise explanation. The last line lands those same facts as the decision or the one real next step. Do not invent a question or change the numbers. Skip this shape for a one-line answer, a raw artifact, or a reply a skill already shapes.
+
+Plan first. A straight shot is one file, one obvious edit, and nothing to decide: do it. Anything else: the plan caps the result, so research until every leaf is defensible, ask what only the user can answer, and research again on each answer. A clear task gets one plan; an unclear one gets rounds. Then `/write-plan`, stop for approval, revise on feedback, and `/implement-plan`. Detail: `.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.
-To learn the repo layout, use the folder map if it is in your context. If it is missing, or you need more depth, run `node scripts/folder-map.mjs [dir]` instead of exploring with `ls` or `find`.
+To learn the repo layout, use the folder map if it is in your context. If it is missing, or you need more depth, run `node .rulesync/scripts/folder-map.mjs [dir]` instead of exploring with `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.
+Fat dumps: `node .rulesync/scripts/grunt-job.mjs --job search|exec|slice|fetch|test` first; spawn grunt only when the dump needs judgment.
 
-Browse with `node scripts/browser.mjs`. Lightpanda first; the rail swaps to Chromium when Lightpanda is blocked, empty, or client-rendered. Do not stop and say you cannot. App e2e is `playwright test`.
+Browse with `node .rulesync/scripts/browser.mjs`. Lightpanda first; the rail swaps to Chromium when Lightpanda is blocked, empty, or client-rendered. Do not stop and say you cannot. App e2e is `playwright test`.

package/{scripts → .rulesync/scripts}/doctor.mjs

@@ -469,9 +469,9 @@ export function runDoctor({
   return { code: missingRequired.length || missingMaps.length ? 1 : 0, stdout, stderr: "" };
 }
 
-/** Load dest `scripts/lib/env.mjs` `loadEnv` when that file exists next to this script. */
+/** Load the consumer's root `scripts/lib/env.mjs` `loadEnv` when it exists (this script is `.rulesync/scripts/doctor.mjs`). */
 export async function loadOptionalConsumerEnv(baseHref = import.meta.url) {
-  const file = fileURLToPath(new URL("./lib/env.mjs", baseHref));
+  const file = fileURLToPath(new URL("../../scripts/lib/env.mjs", baseHref));
   if (!fs.existsSync(file)) return false;
   const { loadEnv } = await import(pathToFileURL(file).href);
   if (typeof loadEnv === "function") loadEnv();

package/{scripts → .rulesync/scripts}/feature-packs.mjs

@@ -107,7 +107,7 @@ export function unselectedPackRels(selected) {
     if (on.has(pack.name)) continue;
     for (const dir of SKILL_DIRS) rels.push(`${dir}/${pack.skill}`);
     if (pack.ref) rels.push(`.rulesync/reference/${pack.ref}`);
-    if (pack.script) rels.push(`scripts/${pack.script}`);
+    if (pack.script) rels.push(`.rulesync/scripts/${pack.script}`);
   }
   return rels;
 }

package/{scripts → .rulesync/scripts}/folder-map.mjs

@@ -9,7 +9,7 @@
  * Depth is uniform per package: the deepest level that fits the size limit;
  * deeper folders end in `…`.
  *
- *   node scripts/folder-map.mjs [dir]
+ *   node .rulesync/scripts/folder-map.mjs [dir]
  */
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
@@ -32,6 +32,8 @@ export const DEFAULTS = Object.freeze({
 });
 
 export const CONFIG_REL = ".rulesync/grunt.map.jsonc";
+/** Grunt's product scripts run in every repo; map them despite the dot segment. */
+const DOT_CODE_DIRS = [".rulesync/scripts"];
 const MANIFESTS = ["package.json", "go.mod", "Cargo.toml", "pyproject.toml"];
 
 /** DEFAULTS merged with known keys from CONFIG_REL; bad file → defaults + warn. */
@@ -133,7 +135,9 @@ export function buildTree(root, files, opts = {}) {
     const segs = dir.split("/");
     if (!forced) {
       if (!code.test(f)) continue;
-      if (segs.some((s) => s.startsWith(".") || skip.has(s))) continue;
+      const under = DOT_CODE_DIRS.find((d) => dir === d || dir.startsWith(`${d}/`));
+      const checked = under ? segs.slice(under.split("/").length) : segs;
+      if (checked.some((s) => s.startsWith(".") || skip.has(s))) continue;
     }
     let node = top;
     for (const s of segs) {
@@ -254,7 +258,7 @@ export function folderMap({ root, dir = "", ...opts } = {}) {
   return { text, rows: lines.length, tokens: tokens(text), depth };
 }
 
-/** Text for `grunt map [dir]` / `node scripts/folder-map.mjs [dir]` run from `cwd`. */
+/** Text for `grunt map [dir]` / `node .rulesync/scripts/folder-map.mjs [dir]` run from `cwd`. */
 export function mapCommand(cwd, dir = "") {
   const out = folderMap({ root: cwd, dir });
   if (!out) return "grunt map: not a git repository\n";

package/{scripts → .rulesync/scripts}/gate-fat-tools.mjs

@@ -348,7 +348,7 @@ export function quoteQuery(q) {
 }
 
 export function gruntJobCommand(workspaceRoot, args) {
-  const script = path.join(workspaceRoot, "scripts", "grunt-job.mjs");
+  const script = path.join(workspaceRoot, ".rulesync", "scripts", "grunt-job.mjs");
   return `node ${script} ${args}`;
 }
 
@@ -498,12 +498,12 @@ function gruntJobRest(command, workspaceRoot) {
   const abs = path.isAbsolute(scriptArg)
     ? path.resolve(scriptArg)
     : path.resolve(workspaceRoot, scriptArg);
-  const expected = path.resolve(workspaceRoot, "scripts", "grunt-job.mjs");
+  const expected = path.resolve(workspaceRoot, ".rulesync", "scripts", "grunt-job.mjs");
   if (abs !== expected) return null;
   return parts.slice(i + 1);
 }
 
-/** True when argv targets workspace scripts/grunt-job.mjs (flags may be messy). */
+/** True when argv targets workspace .rulesync/scripts/grunt-job.mjs (flags may be messy). */
 export function isWorkspaceGruntJobScript(command, workspaceRoot) {
   return gruntJobRest(command, workspaceRoot) != null;
 }

package/{scripts → .rulesync/scripts}/google-workspace.mjs

@@ -146,7 +146,7 @@ function persistToken(t, access, expiry) {
 
 async function accessToken() {
   const t = loadToken();
-  if (!t) throw new Error("not logged in; run node scripts/google-workspace.mjs login");
+  if (!t) throw new Error("not logged in; run node .rulesync/scripts/google-workspace.mjs login");
   if (t.access_token && Number(t.expiry_date) > Date.now() + 60_000) {
     return t.access_token;
   }
@@ -288,7 +288,7 @@ async function runLogin(flags) {
     return ok("logged in via gcloud ADC");
   }
   return fail(
-    `missing Desktop OAuth JSON (${creds}). setup: node scripts/setup.mjs google-workspace`,
+    `missing Desktop OAuth JSON (${creds}). setup: node .rulesync/scripts/setup.mjs google-workspace`,
   );
 }
 

package/{scripts → .rulesync/scripts}/grunt-job.mjs

@@ -485,8 +485,10 @@ export function runSearch(query, { cwd, path: searchPath, glob } = {}) {
   }
   const globs = Array.isArray(glob) ? glob.filter(Boolean) : glob ? [String(glob)] : [];
   const relStart = path.relative(root, start) || ".";
+  // --hidden: grunt code (.rulesync/scripts) and rulesync SSOT live in dot dirs; .gitignore still applies.
   const rgArgs = [
     "-n",
+    "--hidden",
     "--max-count",
     String(MAX_HITS),
     "--max-filesize",

package/{scripts → .rulesync/scripts}/guarded-md.mjs

@@ -26,6 +26,10 @@ function trimTrailingNewlines(text) {
   return String(text).replace(/(?:\r?\n)+$/, "");
 }
 
+function trimLeadingBlankLines(text) {
+  return String(text).replace(/^(?:[ \t]*\r?\n)+/, "");
+}
+
 function normEq(a, b) {
   return (
     trimTrailingNewlines(String(a).replace(/\r\n/g, "\n")) ===
@@ -55,7 +59,7 @@ function unwrapStackedMarkers(text) {
   const lines = String(text).split(/\r?\n/);
   let start = 0;
   let end = lines.length;
-  while (start < end && BEGIN_LINE_RE.test(lines[start])) start++;
+  while (start < end && (BEGIN_LINE_RE.test(lines[start]) || !lines[start].trim())) start++;
   while (end > start && lines[end - 1] === "") end--;
   while (end > start && END_LINE_RE.test(lines[end - 1])) {
     end--;
@@ -87,13 +91,15 @@ function userRemainderIsBlank(user) {
   return String(user).replace(/\r\n/g, "\n").replace(/\n/g, "") === "";
 }
 
+/** Blank lines around each sentinel: the markdown formatter fixed point (prettier, remark, mdformat). */
 export function composeGuardedMarkdown(gruntBody, userRemainder, nl = "\n") {
   const raw = extractGruntBody(gruntBody) ?? gruntBody;
-  const body = toNewline(trimTrailingNewlines(raw), nl);
-  const block = `${SENTINEL_BEGIN}${nl}${body}${nl}${SENTINEL_END}${nl}`;
+  const body = toNewline(trimTrailingNewlines(trimLeadingBlankLines(raw)), nl);
+  const inner = body ? `${nl}${body}${nl}${nl}` : nl;
+  const block = `${SENTINEL_BEGIN}${nl}${inner}${SENTINEL_END}${nl}`;
   const user = extractUserMarkdown(userRemainder == null ? "" : String(userRemainder));
   if (!user || userRemainderIsBlank(user)) return block;
-  return block + toNewline(user, nl);
+  return `${block}${nl}${toNewline(trimLeadingBlankLines(user), nl)}`;
 }
 
 export function mergeGuardedContent(existingText, gruntBody) {

package/{scripts → .rulesync/scripts}/hooks-union.mjs

@@ -13,14 +13,14 @@
  * validate+sim. Path deny from consumer `.rulesync/permissions.json`.
  * Gemini: SessionStart + AfterTool only; check-behind / path deny stay caveats.
  *
- *   node scripts/hooks-union.mjs           apply then check
- *   node scripts/hooks-union.mjs --check   keep-list only
+ *   node .rulesync/scripts/hooks-union.mjs           apply then check
+ *   node .rulesync/scripts/hooks-union.mjs --check   keep-list only
  */
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 
 export const PULL = "node scripts/daily-pull-check.mjs";
 export const RTK = "node scripts/rtk-check.mjs";
@@ -29,11 +29,11 @@ export const BEHIND = "node scripts/check-behind.mjs --hook";
 export const VALIDATE = "node scripts/validate.mjs --hook";
 export const SIM = "node scripts/sim.mjs --hook";
 export const SCRUB =
-  'node "${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/scrub-spawn-prompt.mjs"';
+  'node "${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.rulesync/scripts/scrub-spawn-prompt.mjs"';
 export const GATE_FAT =
-  'node "${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/gate-fat-tools.mjs"';
+  'node "${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.rulesync/scripts/gate-fat-tools.mjs"';
 export const MAP =
-  'node "${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/session-map.mjs"';
+  'node "${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.rulesync/scripts/session-map.mjs"';
 const MAP_NEEDLE = "session-map.mjs";
 
 export const AUTORUN_NEEDLES = [
@@ -83,10 +83,15 @@ function resolveRoot(opts) {
   return process.cwd();
 }
 
+/** Consumer-owned extras live in the consumer's root `scripts/`. */
 function hasScript(root, name) {
   return fs.existsSync(path.join(root, "scripts", name));
 }
 
+function hasGruntScript(root, name) {
+  return fs.existsSync(path.join(root, ".rulesync", "scripts", name));
+}
+
 function withoutWritePath(arr) {
   return arr.filter((x) => typeof x === "string" && !x.startsWith("Write("));
 }
@@ -179,13 +184,13 @@ function desiredPre(root) {
 }
 
 function mapNeedles(root) {
-  return hasScript(root, MAP_NEEDLE) ? [MAP_NEEDLE] : [];
+  return hasGruntScript(root, MAP_NEEDLE) ? [MAP_NEEDLE] : [];
 }
 
 /** `map: false` for hosts rulesync emits no sessionStart for (Antigravity). */
 function desiredSession(root, { map = true } = {}) {
   const hooks = [];
-  if (map && hasScript(root, MAP_NEEDLE)) hooks.push(hookCmd(MAP, 5));
+  if (map && hasGruntScript(root, MAP_NEEDLE)) hooks.push(hookCmd(MAP, 5));
   if (hasScript(root, "daily-pull-check.mjs")) hooks.push(hookCmd(PULL));
   if (hasScript(root, "rtk-check.mjs")) hooks.push(hookCmd(RTK));
   if (hasScript(root, "daily-fleet-check.mjs")) hooks.push(hookCmd(FLEET));

package/{scripts → .rulesync/scripts}/jev.mjs

@@ -15,9 +15,9 @@ export const TIMEOUT_MS = 10_000;
 export const MAX_RETRY_WAIT_MS = 2_000;
 export const LOCK_STALE_MS = 10_000;
 
-const USAGE = "usage: node scripts/jev.mjs --available | --state FILE --questions FILE\n";
+const USAGE = "usage: node .rulesync/scripts/jev.mjs --available | --state FILE --questions FILE\n";
 const MISSING_KEY =
-  "missing TYPESAFE_API_KEY or ~/.grunt/jev.json. setup: node scripts/setup.mjs jev\n";
+  "missing TYPESAFE_API_KEY or ~/.grunt/jev.json. setup: node .rulesync/scripts/setup.mjs jev\n";
 
 export function jevJsonPath(home) {
   return path.join(home, ".grunt", "jev.json");

package/{scripts → .rulesync/scripts}/listen.mjs

@@ -14,15 +14,15 @@ export const DEFAULT_SECONDS = 8;
 export const MAX_SECONDS = 120;
 export const USAGE =
   "usage: listen whoami | devices | rec [--seconds N] [--device D] [--clip] | start [--device D] | stop [--clip] | toggle [--clip] | status | file --path P [--clip] | latest";
-export const SETUP = "node scripts/setup.mjs listen";
+export const SETUP = "node .rulesync/scripts/setup.mjs listen";
 export const NEED_STT =
-  "missing whisper-cli (mac: brew install whisper-cpp) or OPENAI_API_KEY / ~/.grunt/speak.json openai.apiKey. setup: node scripts/setup.mjs listen";
+  "missing whisper-cli (mac: brew install whisper-cpp) or OPENAI_API_KEY / ~/.grunt/speak.json openai.apiKey. setup: node .rulesync/scripts/setup.mjs listen";
 export const NEED_FFMPEG =
-  "missing ffmpeg. mac: brew install ffmpeg · linux: sudo apt install ffmpeg · win: winget install Gyan.FFmpeg. setup: node scripts/setup.mjs listen";
+  "missing ffmpeg. mac: brew install ffmpeg · linux: sudo apt install ffmpeg · win: winget install Gyan.FFmpeg. setup: node .rulesync/scripts/setup.mjs listen";
 export const NEED_OPENAI =
-  "missing OPENAI_API_KEY (or ~/.grunt/speak.json openai.apiKey). setup: node scripts/setup.mjs listen";
+  "missing OPENAI_API_KEY (or ~/.grunt/speak.json openai.apiKey). setup: node .rulesync/scripts/setup.mjs listen";
 export const NEED_GGML =
-  "whisper-cli found but no ggml model (auto-download failed). set WHISPER_MODEL or retry. setup: node scripts/setup.mjs listen";
+  "whisper-cli found but no ggml model (auto-download failed). set WHISPER_MODEL or retry. setup: node .rulesync/scripts/setup.mjs listen";
 
 export function formatHttpError(status, body, provider = "openai") {
   const n = Number(status);
@@ -254,7 +254,7 @@ export function ffmpegInputArgs(platform, device, ffmpegFormat = "") {
   if (platform === "win32") {
     if (!d) {
       throw new Error(
-        "missing --device or LISTEN_DEVICE. run: node scripts/listen.mjs devices. setup: node scripts/setup.mjs listen",
+        "missing --device or LISTEN_DEVICE. run: node .rulesync/scripts/listen.mjs devices. setup: node .rulesync/scripts/setup.mjs listen",
       );
     }
     const spec = d.startsWith("audio=") ? d : `audio=${d}`;

package/{scripts → .rulesync/scripts}/pipeline.mjs

@@ -12,27 +12,27 @@ export const COMMANDS = {
   generate: [
     "rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,subagents,skills",
     "rulesync generate -t claudecode,codexcli,antigravity-cli -f hooks",
-    "node scripts/emit-mcp-policy.mjs",
-    "node scripts/emit-gemini.mjs",
-    "node scripts/emit-agent-shell-tools.mjs",
-    "node scripts/emit-maps.mjs",
-    "node scripts/hooks-union.mjs",
+    "node .rulesync/scripts/emit-mcp-policy.mjs",
+    "node .rulesync/scripts/emit-gemini.mjs",
+    "node .rulesync/scripts/emit-agent-shell-tools.mjs",
+    "node .rulesync/scripts/emit-maps.mjs",
+    "node .rulesync/scripts/hooks-union.mjs",
   ],
   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/emit-maps.mjs --check",
-    "node scripts/check-globals.mjs",
-    "node scripts/hooks-union.mjs --check",
+    "node .rulesync/scripts/emit-mcp-policy.mjs --check",
+    "node .rulesync/scripts/emit-gemini.mjs --check",
+    "node .rulesync/scripts/emit-agent-shell-tools.mjs --check",
+    "node .rulesync/scripts/emit-maps.mjs --check",
+    "node .rulesync/scripts/check-globals.mjs",
+    "node .rulesync/scripts/hooks-union.mjs --check",
   ],
   watch: [
-    "node scripts/emit-mcp-policy.mjs",
-    "node scripts/emit-gemini.mjs",
-    "node scripts/emit-agent-shell-tools.mjs",
+    "node .rulesync/scripts/emit-mcp-policy.mjs",
+    "node .rulesync/scripts/emit-gemini.mjs",
+    "node .rulesync/scripts/emit-agent-shell-tools.mjs",
     "rulesync generate -t claudecode,codexcli,antigravity-cli,grokcli -f rules,subagents,skills --watch",
   ],
 };

package/{scripts → .rulesync/scripts}/session-map.mjs

@@ -13,7 +13,7 @@ import { folderMap } from "./folder-map.mjs";
 /** First line of the injected map; `depth` = levels per package, null when nothing was cut. */
 export function header(depth) {
   const scope = depth == null ? "complete" : `${depth} levels per package`;
-  return `Folder map (code folders, ${scope}; \`…\` = deeper, run \`node scripts/folder-map.mjs <dir>\`):`;
+  return `Folder map (code folders, ${scope}; \`…\` = deeper, run \`node .rulesync/scripts/folder-map.mjs <dir>\`):`;
 }
 /** Claude Code caps each hook's additionalContext at 10,000 chars; above it, only a 2KB preview stays inline. */
 export const HOOK_CONTEXT_CHARS = 10000;

package/{scripts → .rulesync/scripts}/setup.mjs

@@ -427,7 +427,7 @@ export async function setupSpeak({
     throw new Error(
       interactive
         ? "need an ElevenLabs or OpenAI key"
-        : "need --elevenlabs-key or --openai-key (or TTY: node scripts/setup.mjs speak)",
+        : "need --elevenlabs-key or --openai-key (or TTY: node .rulesync/scripts/setup.mjs speak)",
     );
   }
 
@@ -502,7 +502,7 @@ export async function setupListen({
       openaiKey = str(await io.password({ message: "OpenAI API key (fallback STT)" }));
     } else {
       throw new Error(
-        "need whisper-cli or --openai-key (or TTY: node scripts/setup.mjs listen)",
+        "need whisper-cli or --openai-key (or TTY: node .rulesync/scripts/setup.mjs listen)",
       );
     }
   }
@@ -611,7 +611,7 @@ export async function setupGoogleWorkspace({
       installOAuthJson({ src: credsFlag, dest });
     } else if (!fs.existsSync(dest)) {
       throw new Error(
-        `need --creds PATH (or TTY: node scripts/setup.mjs google-workspace)`,
+        `need --creds PATH (or TTY: node .rulesync/scripts/setup.mjs google-workspace)`,
       );
     }
 
@@ -678,7 +678,7 @@ export async function setupJev({
     throw new Error(
       interactive
         ? "need a TypeSafe API key"
-        : "need --api-key (or TTY: node scripts/setup.mjs jev)",
+        : "need --api-key (or TTY: node .rulesync/scripts/setup.mjs jev)",
     );
   }
   const dest = writeSecretJson(path.join(home, ".grunt", "jev.json"), { apiKey });

package/{scripts → .rulesync/scripts}/speak.mjs

@@ -27,13 +27,13 @@ export const USAGE =
   "usage: speak whoami | voices | say --text T [--provider elevenlabs|openai] [--voice ID] [--out path] [--play]";
 const ELEVEN_API = "https://api.elevenlabs.io/v1";
 const OPENAI_API = "https://api.openai.com/v1";
-export const SETUP = "node scripts/setup.mjs speak";
+export const SETUP = "node .rulesync/scripts/setup.mjs speak";
 export const NEED_KEY =
-  "missing ELEVENLABS_API_KEY or OPENAI_API_KEY (or ~/.grunt/speak.json). setup: node scripts/setup.mjs speak";
+  "missing ELEVENLABS_API_KEY or OPENAI_API_KEY (or ~/.grunt/speak.json). setup: node .rulesync/scripts/setup.mjs speak";
 export const NEED_ELEVEN =
-  "missing ELEVENLABS_API_KEY (or ~/.grunt/speak.json elevenlabs.apiKey). setup: node scripts/setup.mjs speak";
+  "missing ELEVENLABS_API_KEY (or ~/.grunt/speak.json elevenlabs.apiKey). setup: node .rulesync/scripts/setup.mjs speak";
 export const NEED_OPENAI =
-  "missing OPENAI_API_KEY (or ~/.grunt/speak.json openai.apiKey). setup: node scripts/setup.mjs speak";
+  "missing OPENAI_API_KEY (or ~/.grunt/speak.json openai.apiKey). setup: node .rulesync/scripts/setup.mjs speak";
 
 export function formatHttpError(status, body, provider) {
   const n = Number(status);

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

@@ -1,9 +1,9 @@
 ---
 name: browser
-description: "Browse via node scripts/browser.mjs (Lightpanda). App e2e uses Playwright."
+description: "Browse via node .rulesync/scripts/browser.mjs (Lightpanda). App e2e uses Playwright."
 ---
 
-Zero-config. `node scripts/browser.mjs <verb>`.
+Zero-config. `node .rulesync/scripts/browser.mjs <verb>`.
 
 Verbs: `nav <url>` · `snap` · `click <ref>` · `fill <ref> <text>` · `scroll [ref|down|up|N]` · `wait [ms]` · `hover <ref>` · `select <ref> <value>` · `shot` · `pdf` · `stop` · `doctor` · `ensure`.
 
@@ -11,5 +11,5 @@ Verbs: `nav <url>` · `snap` · `click <ref>` · `fill <ref> <text>` · `scroll
 - Lightpanda default. The rail swaps to Chromium when `shot`/`pdf`/`trace`, win32, missing Lightpanda, probe-fail once, Chromium-first hosts (figma docs/sheets/slides mail.google earth amazon), or a blocked/empty/client-rendered snap. One swap. Do not stop and say you cannot.
 - 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`. Engine hints: `node scripts/setup.mjs browser`. Do not read a README unless doctor/setup is missing; then https://github.com/lovrozagar/grunt#prerequisites (not the consumer README).
+- `doctor`/`ensure` → `node .rulesync/scripts/doctor.mjs` or `grunt doctor`. Engine hints: `node .rulesync/scripts/setup.mjs browser`. Do not read a README unless doctor/setup is missing; then https://github.com/lovrozagar/grunt#prerequisites (not the consumer README).
 - No env. No MCP. No raw Playwright. Spec: `.rulesync/reference/browser.md`.

package/.rulesync/skills/clasp/SKILL.md

@@ -6,4 +6,4 @@ description: "Low-level Apps Script CLI. Prefer /google-workspace for sheet, doc
 
 Custom Apps Script in-repo only. Spec: `.rulesync/reference/clasp.md`.
 
-Sheets, Docs, Slides, Calendar, Gmail: `node scripts/google-workspace.mjs` and `.rulesync/reference/google-workspace.md`.
+Sheets, Docs, Slides, Calendar, Gmail: `node .rulesync/scripts/google-workspace.mjs` and `.rulesync/reference/google-workspace.md`.