@muggleai/works 5.16.0 → 5.17.0-staging.113

package/dist/plugin/scripts/ensure-electron-app.sh

@@ -114,14 +114,22 @@ version_check || true
 # <cwd>/.muggle-ai/preferences.json is left on disk but no longer read, so the
 # keys it can no longer apply are named once — the stamp file suppresses the
 # repeat until that key set changes.
-prefs_global_file="${HOME}/.muggle-ai/preferences.json"
 prefs_line=""
 prefs_file_note=""
 
-if [ -f "$prefs_global_file" ]; then
-  # Extract preferences object keys and values into a compact one-liner.
-  # Uses node for reliable JSON parsing (already required for muggle).
-  prefs_line=$(node -e "
+# Defaults ship as data next to this hook so the context line and the MCP tools
+# resolve a preference the same way. Hardcoding them here drifted once already.
+prefs_hook_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+prefs_defaults_file="${prefs_hook_dir}/../config/preference-defaults.json"
+prefs_limits_file="${prefs_hook_dir}/../config/onboarding-limits.json"
+
+onboarding_directive='Muggle Test first-run setup has not been run on this machine. Before acting on the user request, acknowledge what they asked for, then offer them the one-time setup walkthrough (the `onboard` operation of the muggle-preferences skill) which explains how Muggle Test works and saves their preferences. Accepting the recommended defaults takes one keystroke. If they decline, record the skip and carry on with their request using defaults.'
+
+# A missing preferences file is not a special case: the resolver below falls back to
+# the shipped defaults, which is exactly what the code will use until setup seeds them.
+# Extract preferences object keys and values into a compact one-liner.
+# Uses node for reliable JSON parsing (already required for muggle).
+prefs_line=$(MUGGLE_PREFERENCE_DEFAULTS_FILE="$prefs_defaults_file" MUGGLE_ONBOARDING_LIMITS_FILE="$prefs_limits_file" MUGGLE_ONBOARDING_DIRECTIVE="$onboarding_directive" node -e "
     const fs = require('fs');
     const os = require('os');
     const path = require('path');
@@ -129,21 +137,31 @@ if [ -f "$prefs_global_file" ]; then
       // Resolved through node, not the shell's \$HOME: under Git Bash the shell
       // reports a POSIX path that Windows node cannot open.
       const globalFile = path.join(os.homedir(), '.muggle-ai', 'preferences.json');
-      const g = JSON.parse(fs.readFileSync(globalFile, 'utf-8')).preferences || {};
-      const defaults = {
-        autoLogin:'ask', autoSelectProject:'ask', autoSelectLocalHost:'ask',
-        showElectronBrowser:'ask', openTestResultsAfterRun:'ask',
-        defaultExecutionMode:'ask',
-        suggestRelatedUseCases:'ask', suggestRelatedTestCases:'ask', autoDetectChanges:'ask',
-        postPRVisualWalkthrough:'ask', autoCreatePR:'ask',
-        checkForUpdates:'ask', verboseOutput:'ask',
-        autoUseWorktree:'ask', autoRebase:'ask', autoCleanup:'ask',
-        autoE2ETest:'always', autoRouteBuildToMuggleDo:'ask'
-      };
+      let file = {};
+      try { file = JSON.parse(fs.readFileSync(globalFile, 'utf-8')); } catch {}
+      const g = file.preferences || {};
+      let defaults = {};
+      try { defaults = JSON.parse(fs.readFileSync(process.env.MUGGLE_PREFERENCE_DEFAULTS_FILE, 'utf-8')); } catch {}
       const resolved = { ...defaults, ...g };
       const line = Object.entries(resolved).map(([k,v]) => k+'='+v).join(' ');
       const blocks = ['Muggle Test Preferences (~/.muggle-ai/preferences.json):\\\\n' + line];
 
+      const onboardedAt = file.onboardingCompletedAt;
+      if (typeof onboardedAt !== 'string' || onboardedAt.length === 0) {
+        // The offer is capped here rather than only in the skip path: a user who never
+        // engages would otherwise be re-asked every session forever.
+        let maxOffers = 0;
+        try { maxOffers = JSON.parse(fs.readFileSync(process.env.MUGGLE_ONBOARDING_LIMITS_FILE, 'utf-8')).maxOffers; } catch {}
+        const offersDir = path.join(os.homedir(), '.cache', 'muggle');
+        const offersFile = path.join(offersDir, 'onboarding-offers');
+        let offers = 0;
+        try { offers = parseInt(fs.readFileSync(offersFile, 'utf-8'), 10) || 0; } catch {}
+        if (maxOffers > 0 && offers < maxOffers) {
+          try { fs.mkdirSync(offersDir, { recursive: true }); fs.writeFileSync(offersFile, String(offers + 1)); } catch {}
+          blocks.push(process.env.MUGGLE_ONBOARDING_DIRECTIVE);
+        }
+      }
+
       const cwd = process.env.CLAUDE_CWD || process.env.CURSOR_CWD || process.cwd();
       const pPath = path.join(cwd, '.muggle-ai', 'preferences.json');
       let p = {};
@@ -166,11 +184,8 @@ if [ -f "$prefs_global_file" ]; then
       console.log(blocks.join('\\\\n\\\\n'));
     } catch { console.log(''); }
   " 2>/dev/null || true)
-  if [ -n "$prefs_line" ]; then
-    prefs_file_note="\\n\\n${prefs_line}"
-  fi
-else
-  prefs_file_note="\\n\\nMuggle Test Preferences: not configured. Run \\\`muggle setup\\\` or tell the agent to set preferences."
+if [ -n "$prefs_line" ]; then
+  prefs_file_note="\\n\\n${prefs_line}"
 fi
 
 # --- Last-used cache injection ---

package/dist/plugin/skills/muggle/SKILL.md

@@ -12,7 +12,7 @@ Use this as the top-level Muggle Test command router.
 
 ## Preferences
 
-User preferences are injected by the SessionStart hook into a `Muggle Test Preferences` line in session context (key=value pairs). Resolution: defaults → `~/.muggle-ai/preferences.json`. Preferences are user-level and apply to every repo. Treat absent prefs as `ask`.
+User preferences are injected by the SessionStart hook into a `Muggle Test Preferences` line in session context (key=value pairs). Resolution: shipped defaults → `~/.muggle-ai/preferences.json`. Preferences are user-level and apply to every repo. The line carries every key already resolved, so a key is never absent.
 
 This router skill itself does not gate any decision on a preference — it just routes user intent to a downstream skill. Each downstream skill consults its own preferences. For example, `checkForUpdates` is consulted by `muggle-status` (Check 4), not here.
 

package/dist/plugin/skills/muggle-preferences/SKILL.md

@@ -23,10 +23,11 @@ Pick the operation, then read its op file for the procedure.
 | "show preferences" / no args | `ops/list.md` |
 | "configure muggle" / "muggle setup" / change without naming a key | `ops/configure.md` |
 | "reset preferences" | `ops/reset.md` |
+| Session context says first-run setup has not been run | `ops/onboard.md` |
 
 ## Shared context (all ops)
 
-- **Current values**: session-context line `Muggle Test Preferences key=value …`. Default `ask`.
+- **Current values**: session-context line `Muggle Test Preferences key=value …`, already resolved against the shipped defaults in `${CLAUDE_PLUGIN_ROOT}/config/preference-defaults.json`.
 - **Per-key files**: `preference-gates/<key>.md`. Key list = `ls preference-gates/*.md` minus `README.md`.
-- **Allowed values**: `always`/`never`/`ask` (or `local`/`remote`/`ask` for `defaultExecutionMode`).
+- **Allowed values**: `always`/`never`/`ask`, except `defaultExecutionMode` (`local`/`remote`/`ask`), `autoE2ETest` (`always`/`ask`), and `watcherLifetime` (`1d`/`7d`/`never`).
 - **Scope**: preferences are user-level. Every write lands in `~/.muggle-ai/preferences.json` and applies to every repo. If the user asks for a per-project setting, say it isn't supported and confirm before setting it everywhere.

package/dist/plugin/skills/muggle-preferences/ops/configure.md

@@ -26,13 +26,14 @@ you can tell me which (if any) should instead be set to `never`.
 For each option: label = key name, description = first paragraph of `preference-gates/<key>.md`. Multi-select question text = `Which of these should auto-proceed (set to "always")?`; selected = `always`.
 
 - `multiSelect: true`, `header: "Auth & session"` — `autoLogin`, `autoSelectProject`, `checkForUpdates`, `verboseOutput`
-- `multiSelect: true`, `header: "Test setup"` — `autoSelectLocalHost`, `autoDetectChanges`, `autoReuseValidationContext`
+- `multiSelect: true`, `header: "Test setup"` — `autoSelectLocalHost`, `autoDetectChanges`, `autoReuseValidationContext`, `reusePreparePlan`
 - `multiSelect: true`, `header: "Test run"` — `showElectronBrowser`, `openTestResultsAfterRun`
 - `multiSelect: true`, `header: "Suggestions"` — `suggestRelatedUseCases`, `suggestRelatedTestCases`
-- `multiSelect: true`, `header: "PR"` — `postPRVisualWalkthrough`, `autoCreatePR`, `autoWatchPR`
-- `multiSelect: true`, `header: "Branch hygiene"` — `autoUseWorktree`, `autoRebase`, `autoCleanup`
+- `multiSelect: true`, `header: "PR"` — `postPRVisualWalkthrough`, `autoCreatePR`, `autoWatchPR`, `autoRouteBuildToMuggleDo`
+- `multiSelect: true`, `header: "Branch hygiene"` — `autoUseWorktree`, `autoRebase`, `autoCleanup`, `autoResolveConflicts`
 - `multiSelect: false`, `header: "E2E acceptance"` — `autoE2ETest`. Options: `Always run Stage 6 at the end` (`always` — default), `Ask each cycle` (`ask`). No `never` option.
 - `multiSelect: false`, `header: "Default mode"` — `defaultExecutionMode`. Options: `Local — run on my computer` (`local`), `Remote — run in the Muggle Test cloud` (`remote`), `Ask each time` (don't change).
+- `multiSelect: false`, `header: "PR watcher"` — `watcherLifetime`. Options: `Retire after 1 day` (`1d`), `Retire after 7 days` (`7d` — default), `Never retire` (`never`).
 
 `AskUserQuestion` accepts up to 4 questions per call — split across calls.
 

package/dist/plugin/skills/muggle-preferences/ops/list.md

@@ -4,6 +4,7 @@
 2. Render `Preference | Value | Description` table titled `Muggle AI — Preferences`. Values from session context.
 3. Footer:
    ```
-   Values: always · ask · never (defaultExecutionMode: local/remote/ask)
+   Values: always · ask · never — except defaultExecutionMode (local/remote/ask),
+   autoE2ETest (always/ask), watcherLifetime (1d/7d/never)
    Stored: ~/.muggle-ai/preferences.json — applies to every repo
    ```

package/dist/plugin/skills/muggle-preferences/ops/onboard.md

@@ -0,0 +1,54 @@
+# Onboard (first-run walkthrough)
+
+Runs once per machine, when session context says Muggle Test first-run setup has not been run. Explains what Muggle Test is, then saves the user's preferences.
+
+The CLI owns the questions and every mapping from an answer onto a preference value. Render what `muggle init --json` returns — never hardcode keys, labels, or defaults here, and never write `preferences.json` directly.
+
+## Step 1 — answer the user first
+
+If the user asked for something, acknowledge it before offering setup. Setup is an offer, not a gate. Never make them wait for it.
+
+## Step 2 — load the walkthrough
+
+Run `muggle init --json`. It returns:
+
+- `primerHeadline`, `primerBullets` — what to show before asking anything
+- `blanketOptions` — the dispositions, each with `choice`, `label`, `description`
+- `groups` — per-group questions; `kind` is `toggle` or `choice`
+
+## Step 3 — show the primer, then the blanket choice
+
+Print `primerHeadline` and `primerBullets` verbatim. Then one `AskUserQuestion` whose options are `blanketOptions` in order, using each `label` and `description`. The first option is pre-selected.
+
+Record the picked `choice` value.
+
+## Step 4 — per-group questions
+
+Only when the user picked `customize`. Otherwise skip to step 5.
+
+For each entry in `groups`, in order:
+
+- `kind: "toggle"` — one `multiSelect: true` question. `header` = the group's `header`, question text = its `prompt`, one option per entry using `key` as the label and `description` as the description. Pre-select every entry whose `isSelectedByDefault` is true. Collect the selected `key`s.
+- `kind: "choice"` — one `multiSelect: false` question. `header` = the group's `header`, question text = its `prompt`, one option per entry in `options` using `label`. Pre-select the option whose `isDefault` is true. Record `key` → the picked option's `value`.
+
+`AskUserQuestion` takes at most 4 questions per call, so split the groups across calls.
+
+## Step 5 — apply
+
+Write the answers to `~/.muggle-ai/temp/onboarding-answers.json`:
+
+```json
+{
+  "blanket": "customize",
+  "selectedToggleKeys": ["autoLogin", "autoSelectProject"],
+  "choices": { "autoE2ETest": "always", "defaultExecutionMode": "local", "watcherLifetime": "7d" }
+}
+```
+
+`blanket` is the value from step 3. Include `selectedToggleKeys` and `choices` only when it is `customize`.
+
+Run `muggle init --apply ~/.muggle-ai/temp/onboarding-answers.json`, then delete the file.
+
+## Step 6 — confirm
+
+Print what the CLI reported. On `skip`, say it will be offered again next session and move on — a declined offer retires itself after the third time.

package/dist/plugin/skills/muggle-preferences/preference-gates/README.md

@@ -4,21 +4,23 @@ One file per key in this directory — `ls preference-gates/*.md` is the
 authoritative key list. Skills load this contract + only the gates they
 actually fire.
 
-Default allowed values: `always` / `never` / `ask`. Per-key overrides
-are noted in their own file (currently only `defaultExecutionMode`,
-which uses `local` / `remote` / `ask`).
+Default allowed values: `always` / `never` / `ask`. Per-key overrides are noted
+in their own file: `defaultExecutionMode` (`local` / `remote` / `ask`),
+`autoE2ETest` (`always` / `ask`), and `watcherLifetime` (`1d` / `7d` / `never`).
 
 ## Resolution
 
 `SessionStart` injects a `Muggle Test Preferences` line (`key=value` pairs) from
 `~/.muggle-ai/preferences.json`. Preferences are user-level — there is no
-per-project layer. Absent → treat as `ask`.
+per-project layer. The line carries every key, already resolved against the
+shipped defaults in `${CLAUDE_PLUGIN_ROOT}/config/preference-defaults.json`, so a
+key is never absent.
 
 ## Gate behavior
 
 - `always` → take the pro-action, then **always** print the silent footer.
 - `never` → take the skip-action, then **always** print the silent footer.
-- `ask` (or absent) → run Picker 1 (per-key file) → Picker 2 (below).
+- `ask` → run Picker 1 (per-key file) → Picker 2 (below).
 
 `defaultExecutionMode` uses `local`/`remote` instead of `always`/`never`.
 

package/dist/plugin/skills/muggle-preferences/preference-gates/autoResolveConflicts.md

@@ -1,6 +1,6 @@
 # `autoResolveConflicts`
 
-When a rebase onto `origin/{default}` hits conflicts, `always` resolves them autonomously behind a verify-or-rollback gate and `never` aborts the rebase and escalates. Take the effective value from the configured preference per [`../README.md`](../README.md#resolution) (the injected `Muggle Test Preferences` line) — don't assume a default; an unset key resolves to `ask`.
+When a rebase onto `origin/{default}` hits conflicts, `always` resolves them autonomously behind a verify-or-rollback gate and `never` aborts the rebase and escalates. Take the effective value from the configured preference per [`../README.md`](../README.md#resolution) (the injected `Muggle Test Preferences` line) — don't assume a default; the line carries every key already resolved.
 
 **Picker 1** — header `Resolve rebase conflicts?`, question `"Rebase onto origin/{default} hit conflicts in {conflicted} file(s) — resolve them autonomously?"`
 - `Resolve autonomously` — `Resolve the conflicts, then re-verify (build + unit + E2E) before any push; roll back and escalate if verification fails.` → `always`

package/dist/plugin/skills/muggle-test-prepare/steps/check-running.md

@@ -5,7 +5,7 @@
 The dev-server URL the tests will hit is a **recorded value, not a guess** — resolve it before probing anything.
 
 1. Read the cached host with `muggle-local-last-host-get`. It reads the entry keyed on `<cwd>` in `~/.muggle-ai/last-host.json`; a worktree usually has **no cache of its own**, so when the worktree returns nothing, pass the **main** working-tree root as `cwd` — `git rev-parse --git-common-dir`, then its parent directory.
-2. Apply the [`autoSelectLocalHost`](../../muggle-preferences/preference-gates/autoSelectLocalHost.md) gate (read its value from the `Muggle Test Preferences` session-context line; absent → `ask`):
+2. Apply the [`autoSelectLocalHost`](../../muggle-preferences/preference-gates/autoSelectLocalHost.md) gate (read its value from the `Muggle Test Preferences` session-context line, which carries every key already resolved):
    - `always` **and** a cache exists → use it silently: `Using saved local URL {lastHost}`.
    - otherwise (`ask` / `never`, or no cache) → **confirm before using any host.** Run the gate's Picker 1 with `{lastHost}` (cached URL, omitted when absent) and `{suggestedHost}` (a port you actually detect listening). Never auto-pick, and never fall back to a framework default like `:3000`; if nothing is cached or detected, ask the user to type the URL.
 

package/dist/plugin/skills/muggle-test-prepare/steps/reuse-plan.md

@@ -17,7 +17,7 @@ Load the prose companion per [e2e-instructions](./e2e-instructions.md) — `~/.m
 
 ## Gate `reusePreparePlan`
 
-Per [`muggle-preferences/preference-gates/README.md`](../../muggle-preferences/preference-gates/README.md). Read the current value from the `Muggle Test Preferences` session-context line; absent → `ask`.
+Per [`muggle-preferences/preference-gates/README.md`](../../muggle-preferences/preference-gates/README.md). Read the current value from the `Muggle Test Preferences` session-context line, which carries every key already resolved.
 
 - `always` → silently take the **reuse path** (below). Print the silent footer (substitute `{services}` with the comma-separated names from the loaded plan).
 - `never` → take the **rediscover path**: exit this step; continue at [rebase-check](./rebase-check.md).

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
   "release": "5.13.1",
-  "buildId": "run-112-1",
-  "commitSha": "988e61e57e14c6a98490167183cfa0a33421bf51",
-  "buildTime": "2026-09-09T20:15:58Z",
+  "buildId": "run-113-1",
+  "commitSha": "7ee3a19d04e8507a86d41d123b9daa7d2bf1a572",
+  "buildTime": "2026-09-15T05:23:37Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/dist/src-52J7RTUV.js

@@ -0,0 +1 @@
+export { DEFAULT_PREFERENCES, ElectronAppReleaseStream, ONBOARDING_BLANKET_OPTIONS, ONBOARDING_CHOICE_GROUPS, ONBOARDING_MAX_OFFERS, ONBOARDING_PRIMER_BULLETS, ONBOARDING_PRIMER_HEADLINE, ONBOARDING_TOGGLE_GROUPS, ONBOARDING_TOGGLE_PROMPT, ONBOARDING_UNSELECTED_TOGGLE_VALUE, OnboardingBlanketChoice, OnboardingGroupKind, PREFERENCES_FILE_NAME, PREFERENCES_PROJECT_DIR_NAME, PREFERENCES_SCHEMA, PREFERENCES_VERSION, PREFERENCE_ALLOWED_VALUES, PreferenceKey, PreferenceValue, ProjectPreferencesReconcileOutcome, RuntimeTarget, WATCHER_LIFETIME_SECONDS, WATCHER_LIFETIME_UNBOUNDED_SECONDS, applyOnboardingAnswers, assertDeviceCodeClientProvisioned, buildElectronAppChecksumsUrl, buildElectronAppReleaseAssetUrl, buildElectronAppReleaseTag, buildOnboardingPlan, calculateFileChecksum, completeOnboarding, createApiKeyWithToken, createChildLogger, deleteApiKeyData, deleteCredentials, e2e_exports as e2e, formatPreferencesOneLiner, getActiveElectronAppReleaseStream, getActiveRuntimeTarget, getApiKey, getApiKeyFilePath, getAuthService, getBundledElectronAppVersion, getCallerCredentials, getCallerCredentialsAsync, getChecksumForPlatform, getConfig, getCredentialsFilePath, getDataDir, getDownloadBaseUrl, getElectronAppChecksums, getElectronAppDir, getElectronAppReleaseTagPrefix, getElectronAppSignedFromVersion, getElectronAppVersion, getElectronAppVersionSource, getLocalQaTools, getLogger, getOnboardingToggleKeys, getPlatformKey, getQaTools, getReleaseSignerIdentityUri, getValidApiKeyData, getValidCredentials, hasApiKey, isElectronAppInstalled, isFirstRun, loadApiKeyData, loadCredentials, local_exports as localQa, markOnboardingCompleted, mcp_exports as mcp, needsOnboarding, openBrowserUrl, performLogin, performLogout, pollDeviceCode, e2e_exports as qa, readPreferencesMetadata, reconcileProjectPreferences, recordOnboardingSkip, resetConfig, resetLogger, resetPreference, resolveActiveProfile, resolveActiveReleaseStream, resolveActiveReleaseTagPrefix, resolveBlanketPreferences, resolveElectronAppPathOrNull, resolveOnboardingAnswers, resolvePreferences, resolveRuntimeTarget, resolveTogglePreferences, saveApiKey, saveApiKeyData, saveCredentials, startDeviceCodeFlow, toolRequiresAuth, validatePreference, verifyFileChecksum, writePreferences, writePreferencesWithMetadata } from './chunk-EKSYEVM2.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "5.16.0",
+  "version": "5.17.0-staging.113",
   "description": "Ship quality products with AI-powered E2E acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
   "type": "module",
   "main": "dist/index.js",
@@ -13,6 +13,7 @@
     "plugin",
     "bin/muggle.js",
     "scripts/postinstall.mjs",
+    "scripts/onboarding-backfill.mjs",
     "scripts/release-integrity",
     "config/runtime-targets.json"
   ],
@@ -53,7 +54,7 @@
   "muggleConfig": {
     "electronAppVersion": "1.10.3",
     "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
-    "runtimeTargetDefault": "production",
+    "runtimeTargetDefault": "staging",
     "checksumsByStream": {
       "production": {
         "win32-x64": "58e2238b1609ceff65b836b4b724b1c4c341d737a15debaa8a71af21b70bc436",

package/plugin/config/onboarding-limits.json

@@ -0,0 +1,3 @@
+{
+  "maxOffers": 3
+}

package/plugin/config/preference-defaults.json

@@ -0,0 +1,25 @@
+{
+  "autoLogin": "always",
+  "autoSelectProject": "always",
+  "autoSelectLocalHost": "always",
+  "showElectronBrowser": "always",
+  "openTestResultsAfterRun": "always",
+  "defaultExecutionMode": "local",
+  "suggestRelatedUseCases": "always",
+  "suggestRelatedTestCases": "always",
+  "autoDetectChanges": "always",
+  "postPRVisualWalkthrough": "always",
+  "autoCreatePR": "always",
+  "checkForUpdates": "always",
+  "verboseOutput": "never",
+  "autoUseWorktree": "always",
+  "autoRebase": "always",
+  "autoCleanup": "always",
+  "autoE2ETest": "always",
+  "autoResolveConflicts": "always",
+  "autoReuseValidationContext": "always",
+  "autoRouteBuildToMuggleDo": "always",
+  "autoWatchPR": "always",
+  "reusePreparePlan": "always",
+  "watcherLifetime": "7d"
+}

package/plugin/scripts/ensure-electron-app.sh

@@ -114,14 +114,22 @@ version_check || true
 # <cwd>/.muggle-ai/preferences.json is left on disk but no longer read, so the
 # keys it can no longer apply are named once — the stamp file suppresses the
 # repeat until that key set changes.
-prefs_global_file="${HOME}/.muggle-ai/preferences.json"
 prefs_line=""
 prefs_file_note=""
 
-if [ -f "$prefs_global_file" ]; then
-  # Extract preferences object keys and values into a compact one-liner.
-  # Uses node for reliable JSON parsing (already required for muggle).
-  prefs_line=$(node -e "
+# Defaults ship as data next to this hook so the context line and the MCP tools
+# resolve a preference the same way. Hardcoding them here drifted once already.
+prefs_hook_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+prefs_defaults_file="${prefs_hook_dir}/../config/preference-defaults.json"
+prefs_limits_file="${prefs_hook_dir}/../config/onboarding-limits.json"
+
+onboarding_directive='Muggle Test first-run setup has not been run on this machine. Before acting on the user request, acknowledge what they asked for, then offer them the one-time setup walkthrough (the `onboard` operation of the muggle-preferences skill) which explains how Muggle Test works and saves their preferences. Accepting the recommended defaults takes one keystroke. If they decline, record the skip and carry on with their request using defaults.'
+
+# A missing preferences file is not a special case: the resolver below falls back to
+# the shipped defaults, which is exactly what the code will use until setup seeds them.
+# Extract preferences object keys and values into a compact one-liner.
+# Uses node for reliable JSON parsing (already required for muggle).
+prefs_line=$(MUGGLE_PREFERENCE_DEFAULTS_FILE="$prefs_defaults_file" MUGGLE_ONBOARDING_LIMITS_FILE="$prefs_limits_file" MUGGLE_ONBOARDING_DIRECTIVE="$onboarding_directive" node -e "
     const fs = require('fs');
     const os = require('os');
     const path = require('path');
@@ -129,21 +137,31 @@ if [ -f "$prefs_global_file" ]; then
       // Resolved through node, not the shell's \$HOME: under Git Bash the shell
       // reports a POSIX path that Windows node cannot open.
       const globalFile = path.join(os.homedir(), '.muggle-ai', 'preferences.json');
-      const g = JSON.parse(fs.readFileSync(globalFile, 'utf-8')).preferences || {};
-      const defaults = {
-        autoLogin:'ask', autoSelectProject:'ask', autoSelectLocalHost:'ask',
-        showElectronBrowser:'ask', openTestResultsAfterRun:'ask',
-        defaultExecutionMode:'ask',
-        suggestRelatedUseCases:'ask', suggestRelatedTestCases:'ask', autoDetectChanges:'ask',
-        postPRVisualWalkthrough:'ask', autoCreatePR:'ask',
-        checkForUpdates:'ask', verboseOutput:'ask',
-        autoUseWorktree:'ask', autoRebase:'ask', autoCleanup:'ask',
-        autoE2ETest:'always', autoRouteBuildToMuggleDo:'ask'
-      };
+      let file = {};
+      try { file = JSON.parse(fs.readFileSync(globalFile, 'utf-8')); } catch {}
+      const g = file.preferences || {};
+      let defaults = {};
+      try { defaults = JSON.parse(fs.readFileSync(process.env.MUGGLE_PREFERENCE_DEFAULTS_FILE, 'utf-8')); } catch {}
       const resolved = { ...defaults, ...g };
       const line = Object.entries(resolved).map(([k,v]) => k+'='+v).join(' ');
       const blocks = ['Muggle Test Preferences (~/.muggle-ai/preferences.json):\\\\n' + line];
 
+      const onboardedAt = file.onboardingCompletedAt;
+      if (typeof onboardedAt !== 'string' || onboardedAt.length === 0) {
+        // The offer is capped here rather than only in the skip path: a user who never
+        // engages would otherwise be re-asked every session forever.
+        let maxOffers = 0;
+        try { maxOffers = JSON.parse(fs.readFileSync(process.env.MUGGLE_ONBOARDING_LIMITS_FILE, 'utf-8')).maxOffers; } catch {}
+        const offersDir = path.join(os.homedir(), '.cache', 'muggle');
+        const offersFile = path.join(offersDir, 'onboarding-offers');
+        let offers = 0;
+        try { offers = parseInt(fs.readFileSync(offersFile, 'utf-8'), 10) || 0; } catch {}
+        if (maxOffers > 0 && offers < maxOffers) {
+          try { fs.mkdirSync(offersDir, { recursive: true }); fs.writeFileSync(offersFile, String(offers + 1)); } catch {}
+          blocks.push(process.env.MUGGLE_ONBOARDING_DIRECTIVE);
+        }
+      }
+
       const cwd = process.env.CLAUDE_CWD || process.env.CURSOR_CWD || process.cwd();
       const pPath = path.join(cwd, '.muggle-ai', 'preferences.json');
       let p = {};
@@ -166,11 +184,8 @@ if [ -f "$prefs_global_file" ]; then
       console.log(blocks.join('\\\\n\\\\n'));
     } catch { console.log(''); }
   " 2>/dev/null || true)
-  if [ -n "$prefs_line" ]; then
-    prefs_file_note="\\n\\n${prefs_line}"
-  fi
-else
-  prefs_file_note="\\n\\nMuggle Test Preferences: not configured. Run \\\`muggle setup\\\` or tell the agent to set preferences."
+if [ -n "$prefs_line" ]; then
+  prefs_file_note="\\n\\n${prefs_line}"
 fi
 
 # --- Last-used cache injection ---

package/plugin/skills/muggle/SKILL.md

@@ -12,7 +12,7 @@ Use this as the top-level Muggle Test command router.
 
 ## Preferences
 
-User preferences are injected by the SessionStart hook into a `Muggle Test Preferences` line in session context (key=value pairs). Resolution: defaults → `~/.muggle-ai/preferences.json`. Preferences are user-level and apply to every repo. Treat absent prefs as `ask`.
+User preferences are injected by the SessionStart hook into a `Muggle Test Preferences` line in session context (key=value pairs). Resolution: shipped defaults → `~/.muggle-ai/preferences.json`. Preferences are user-level and apply to every repo. The line carries every key already resolved, so a key is never absent.
 
 This router skill itself does not gate any decision on a preference — it just routes user intent to a downstream skill. Each downstream skill consults its own preferences. For example, `checkForUpdates` is consulted by `muggle-status` (Check 4), not here.
 

package/plugin/skills/muggle-preferences/SKILL.md

@@ -23,10 +23,11 @@ Pick the operation, then read its op file for the procedure.
 | "show preferences" / no args | `ops/list.md` |
 | "configure muggle" / "muggle setup" / change without naming a key | `ops/configure.md` |
 | "reset preferences" | `ops/reset.md` |
+| Session context says first-run setup has not been run | `ops/onboard.md` |
 
 ## Shared context (all ops)
 
-- **Current values**: session-context line `Muggle Test Preferences key=value …`. Default `ask`.
+- **Current values**: session-context line `Muggle Test Preferences key=value …`, already resolved against the shipped defaults in `${CLAUDE_PLUGIN_ROOT}/config/preference-defaults.json`.
 - **Per-key files**: `preference-gates/<key>.md`. Key list = `ls preference-gates/*.md` minus `README.md`.
-- **Allowed values**: `always`/`never`/`ask` (or `local`/`remote`/`ask` for `defaultExecutionMode`).
+- **Allowed values**: `always`/`never`/`ask`, except `defaultExecutionMode` (`local`/`remote`/`ask`), `autoE2ETest` (`always`/`ask`), and `watcherLifetime` (`1d`/`7d`/`never`).
 - **Scope**: preferences are user-level. Every write lands in `~/.muggle-ai/preferences.json` and applies to every repo. If the user asks for a per-project setting, say it isn't supported and confirm before setting it everywhere.

package/plugin/skills/muggle-preferences/ops/configure.md

@@ -26,13 +26,14 @@ you can tell me which (if any) should instead be set to `never`.
 For each option: label = key name, description = first paragraph of `preference-gates/<key>.md`. Multi-select question text = `Which of these should auto-proceed (set to "always")?`; selected = `always`.
 
 - `multiSelect: true`, `header: "Auth & session"` — `autoLogin`, `autoSelectProject`, `checkForUpdates`, `verboseOutput`
-- `multiSelect: true`, `header: "Test setup"` — `autoSelectLocalHost`, `autoDetectChanges`, `autoReuseValidationContext`
+- `multiSelect: true`, `header: "Test setup"` — `autoSelectLocalHost`, `autoDetectChanges`, `autoReuseValidationContext`, `reusePreparePlan`
 - `multiSelect: true`, `header: "Test run"` — `showElectronBrowser`, `openTestResultsAfterRun`
 - `multiSelect: true`, `header: "Suggestions"` — `suggestRelatedUseCases`, `suggestRelatedTestCases`
-- `multiSelect: true`, `header: "PR"` — `postPRVisualWalkthrough`, `autoCreatePR`, `autoWatchPR`
-- `multiSelect: true`, `header: "Branch hygiene"` — `autoUseWorktree`, `autoRebase`, `autoCleanup`
+- `multiSelect: true`, `header: "PR"` — `postPRVisualWalkthrough`, `autoCreatePR`, `autoWatchPR`, `autoRouteBuildToMuggleDo`
+- `multiSelect: true`, `header: "Branch hygiene"` — `autoUseWorktree`, `autoRebase`, `autoCleanup`, `autoResolveConflicts`
 - `multiSelect: false`, `header: "E2E acceptance"` — `autoE2ETest`. Options: `Always run Stage 6 at the end` (`always` — default), `Ask each cycle` (`ask`). No `never` option.
 - `multiSelect: false`, `header: "Default mode"` — `defaultExecutionMode`. Options: `Local — run on my computer` (`local`), `Remote — run in the Muggle Test cloud` (`remote`), `Ask each time` (don't change).
+- `multiSelect: false`, `header: "PR watcher"` — `watcherLifetime`. Options: `Retire after 1 day` (`1d`), `Retire after 7 days` (`7d` — default), `Never retire` (`never`).
 
 `AskUserQuestion` accepts up to 4 questions per call — split across calls.
 

package/plugin/skills/muggle-preferences/ops/list.md

@@ -4,6 +4,7 @@
 2. Render `Preference | Value | Description` table titled `Muggle AI — Preferences`. Values from session context.
 3. Footer:
    ```
-   Values: always · ask · never (defaultExecutionMode: local/remote/ask)
+   Values: always · ask · never — except defaultExecutionMode (local/remote/ask),
+   autoE2ETest (always/ask), watcherLifetime (1d/7d/never)
    Stored: ~/.muggle-ai/preferences.json — applies to every repo
    ```

package/plugin/skills/muggle-preferences/ops/onboard.md

@@ -0,0 +1,54 @@
+# Onboard (first-run walkthrough)
+
+Runs once per machine, when session context says Muggle Test first-run setup has not been run. Explains what Muggle Test is, then saves the user's preferences.
+
+The CLI owns the questions and every mapping from an answer onto a preference value. Render what `muggle init --json` returns — never hardcode keys, labels, or defaults here, and never write `preferences.json` directly.
+
+## Step 1 — answer the user first
+
+If the user asked for something, acknowledge it before offering setup. Setup is an offer, not a gate. Never make them wait for it.
+
+## Step 2 — load the walkthrough
+
+Run `muggle init --json`. It returns:
+
+- `primerHeadline`, `primerBullets` — what to show before asking anything
+- `blanketOptions` — the dispositions, each with `choice`, `label`, `description`
+- `groups` — per-group questions; `kind` is `toggle` or `choice`
+
+## Step 3 — show the primer, then the blanket choice
+
+Print `primerHeadline` and `primerBullets` verbatim. Then one `AskUserQuestion` whose options are `blanketOptions` in order, using each `label` and `description`. The first option is pre-selected.
+
+Record the picked `choice` value.
+
+## Step 4 — per-group questions
+
+Only when the user picked `customize`. Otherwise skip to step 5.
+
+For each entry in `groups`, in order:
+
+- `kind: "toggle"` — one `multiSelect: true` question. `header` = the group's `header`, question text = its `prompt`, one option per entry using `key` as the label and `description` as the description. Pre-select every entry whose `isSelectedByDefault` is true. Collect the selected `key`s.
+- `kind: "choice"` — one `multiSelect: false` question. `header` = the group's `header`, question text = its `prompt`, one option per entry in `options` using `label`. Pre-select the option whose `isDefault` is true. Record `key` → the picked option's `value`.
+
+`AskUserQuestion` takes at most 4 questions per call, so split the groups across calls.
+
+## Step 5 — apply
+
+Write the answers to `~/.muggle-ai/temp/onboarding-answers.json`:
+
+```json
+{
+  "blanket": "customize",
+  "selectedToggleKeys": ["autoLogin", "autoSelectProject"],
+  "choices": { "autoE2ETest": "always", "defaultExecutionMode": "local", "watcherLifetime": "7d" }
+}
+```
+
+`blanket` is the value from step 3. Include `selectedToggleKeys` and `choices` only when it is `customize`.
+
+Run `muggle init --apply ~/.muggle-ai/temp/onboarding-answers.json`, then delete the file.
+
+## Step 6 — confirm
+
+Print what the CLI reported. On `skip`, say it will be offered again next session and move on — a declined offer retires itself after the third time.

package/plugin/skills/muggle-preferences/preference-gates/README.md

@@ -4,21 +4,23 @@ One file per key in this directory — `ls preference-gates/*.md` is the
 authoritative key list. Skills load this contract + only the gates they
 actually fire.
 
-Default allowed values: `always` / `never` / `ask`. Per-key overrides
-are noted in their own file (currently only `defaultExecutionMode`,
-which uses `local` / `remote` / `ask`).
+Default allowed values: `always` / `never` / `ask`. Per-key overrides are noted
+in their own file: `defaultExecutionMode` (`local` / `remote` / `ask`),
+`autoE2ETest` (`always` / `ask`), and `watcherLifetime` (`1d` / `7d` / `never`).
 
 ## Resolution
 
 `SessionStart` injects a `Muggle Test Preferences` line (`key=value` pairs) from
 `~/.muggle-ai/preferences.json`. Preferences are user-level — there is no
-per-project layer. Absent → treat as `ask`.
+per-project layer. The line carries every key, already resolved against the
+shipped defaults in `${CLAUDE_PLUGIN_ROOT}/config/preference-defaults.json`, so a
+key is never absent.
 
 ## Gate behavior
 
 - `always` → take the pro-action, then **always** print the silent footer.
 - `never` → take the skip-action, then **always** print the silent footer.
-- `ask` (or absent) → run Picker 1 (per-key file) → Picker 2 (below).
+- `ask` → run Picker 1 (per-key file) → Picker 2 (below).
 
 `defaultExecutionMode` uses `local`/`remote` instead of `always`/`never`.
 

package/plugin/skills/muggle-preferences/preference-gates/autoResolveConflicts.md

@@ -1,6 +1,6 @@
 # `autoResolveConflicts`
 
-When a rebase onto `origin/{default}` hits conflicts, `always` resolves them autonomously behind a verify-or-rollback gate and `never` aborts the rebase and escalates. Take the effective value from the configured preference per [`../README.md`](../README.md#resolution) (the injected `Muggle Test Preferences` line) — don't assume a default; an unset key resolves to `ask`.
+When a rebase onto `origin/{default}` hits conflicts, `always` resolves them autonomously behind a verify-or-rollback gate and `never` aborts the rebase and escalates. Take the effective value from the configured preference per [`../README.md`](../README.md#resolution) (the injected `Muggle Test Preferences` line) — don't assume a default; the line carries every key already resolved.
 
 **Picker 1** — header `Resolve rebase conflicts?`, question `"Rebase onto origin/{default} hit conflicts in {conflicted} file(s) — resolve them autonomously?"`
 - `Resolve autonomously` — `Resolve the conflicts, then re-verify (build + unit + E2E) before any push; roll back and escalate if verification fails.` → `always`

package/plugin/skills/muggle-test-prepare/steps/check-running.md

@@ -5,7 +5,7 @@
 The dev-server URL the tests will hit is a **recorded value, not a guess** — resolve it before probing anything.
 
 1. Read the cached host with `muggle-local-last-host-get`. It reads the entry keyed on `<cwd>` in `~/.muggle-ai/last-host.json`; a worktree usually has **no cache of its own**, so when the worktree returns nothing, pass the **main** working-tree root as `cwd` — `git rev-parse --git-common-dir`, then its parent directory.
-2. Apply the [`autoSelectLocalHost`](../../muggle-preferences/preference-gates/autoSelectLocalHost.md) gate (read its value from the `Muggle Test Preferences` session-context line; absent → `ask`):
+2. Apply the [`autoSelectLocalHost`](../../muggle-preferences/preference-gates/autoSelectLocalHost.md) gate (read its value from the `Muggle Test Preferences` session-context line, which carries every key already resolved):
    - `always` **and** a cache exists → use it silently: `Using saved local URL {lastHost}`.
    - otherwise (`ask` / `never`, or no cache) → **confirm before using any host.** Run the gate's Picker 1 with `{lastHost}` (cached URL, omitted when absent) and `{suggestedHost}` (a port you actually detect listening). Never auto-pick, and never fall back to a framework default like `:3000`; if nothing is cached or detected, ask the user to type the URL.
 

package/plugin/skills/muggle-test-prepare/steps/reuse-plan.md

@@ -17,7 +17,7 @@ Load the prose companion per [e2e-instructions](./e2e-instructions.md) — `~/.m
 
 ## Gate `reusePreparePlan`
 
-Per [`muggle-preferences/preference-gates/README.md`](../../muggle-preferences/preference-gates/README.md). Read the current value from the `Muggle Test Preferences` session-context line; absent → `ask`.
+Per [`muggle-preferences/preference-gates/README.md`](../../muggle-preferences/preference-gates/README.md). Read the current value from the `Muggle Test Preferences` session-context line, which carries every key already resolved.
 
 - `always` → silently take the **reuse path** (below). Print the silent footer (substitute `{services}` with the comma-separated names from the loaded plan).
 - `never` → take the **rediscover path**: exit this step; continue at [rebase-check](./rebase-check.md).