@muggleai/works 4.10.0 → 4.11.0

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

@@ -0,0 +1,49 @@
+# Configure (interactive picker)
+
+Use whenever the user wants to change preferences without naming a specific key. Drives selections through `AskUserQuestion` so they toggle with the keyboard instead of typing key names.
+
+## Step 1 — show current state
+
+Print the preference table per `ops/list.md` so the user sees what's set today.
+
+## Step 2 — usage instructions
+
+Print verbatim before calling `AskUserQuestion`:
+
+```
+How to use this picker:
+  ↑/↓        move between options
+  space      toggle a preference (selected = set to `always`)
+  tab        move to the next question
+  enter      confirm
+
+Anything you don't toggle keeps its current value. After this picker
+you can tell me which (if any) should instead be set to `never`.
+```
+
+## Step 3 — call AskUserQuestion
+
+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`
+- `multiSelect: true`, `header: "Test run"` — `showElectronBrowser`, `openTestResultsAfterRun`, `autoPublishLocalResults`
+- `multiSelect: true`, `header: "Suggestions & PR"` — `suggestRelatedUseCases`, `suggestRelatedTestCases`, `postPRVisualWalkthrough`, `autoCreatePR`
+- `multiSelect: true`, `header: "Branch hygiene"` — `autoUseWorktree`, `autoRebase`, `autoCleanup`
+- `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: "Scope"` — final scope question. Options: `Global (all repos)` (~/.muggle-ai/), `This project only` (.muggle-ai/ in repo).
+
+`AskUserQuestion` accepts up to 4 questions per call — split into two calls if needed (categories first, scope second).
+
+## Step 4 — apply selections
+
+For each toggled key (multi-select questions): `muggle-local-preferences-set` with `value: "always"`. For `defaultExecutionMode`: only set if user picked Local/Remote (skip "Ask each time"). Pass `scope` from the scope question; pass `cwd` when scope is `project`.
+
+## Step 5 — `never` follow-up
+
+Ask: `Want any of these set to "never" (auto-skip without asking)? Name them, e.g. "never on autoPublishLocalResults", or say "no".`. For named keys, call `muggle-local-preferences-set` with `value: "never"`, same scope.
+
+## Step 6 — confirm
+
+One-liner summary: `Set autoLogin=always, openTestResultsAfterRun=always (global).`

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

@@ -0,0 +1,9 @@
+# List
+
+1. Read each `preference-gates/<key>.md` (skip `README.md`). First paragraph of each = description.
+2. Render `Preference | Value | Description` table titled `Muggle AI — Preferences`. Values from session context.
+3. Footer:
+   ```
+   Values: always · ask · never (defaultExecutionMode: local/remote/ask)
+   Scope:  global (~/.muggle-ai/) or project (.muggle-ai/ in repo root)
+   ```

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

@@ -0,0 +1,6 @@
+# Reset
+
+- **Specific key**: `muggle-local-preferences-set` with `value: "ask"` for that key.
+- **All preferences**: same call for every `preference-gates/<key>.md`.
+
+Confirm what was reset.

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

@@ -0,0 +1,10 @@
+# Set — direct (key + value)
+
+Trigger: user names both key and value (e.g. "set autoLogin to always", "make showElectronBrowser never for this project").
+
+1. Parse `key` and `value`.
+2. Verify `preference-gates/<key>.md` exists. If not, list `preference-gates/*.md` and ask.
+3. Validate `value` per Shared context.
+4. Resolve scope per Shared context.
+5. `muggle-local-preferences-set`.
+6. Confirm: `Set {key} to {value} ({scope}).`

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

@@ -10,7 +10,7 @@ which uses `local` / `remote` / `ask`).
 
 ## Resolution
 
-`SessionStart` injects a `Muggle Preferences` line (`key=value` pairs) from
+`SessionStart` injects a `Muggle Test Preferences` line (`key=value` pairs) from
 `~/.muggle-ai/preferences.json` (global) overlaid by
 `<repo>/.muggle-ai/preferences.json` (project). Absent → treat as `ask`.
 

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

@@ -0,0 +1,11 @@
+# `autoCleanup`
+
+After a PR is merged, run the full cleanup sequence (worktree, branch, artifacts, `clean_gone`) — or skip. `always` runs all steps with no per-step prompts. Substitute `{branch}`.
+
+**Picker 1** — header `Cleanup after merge`, question `"PR for {branch} is merged — run cleanup now?"`
+- `Run cleanup` — `Remove worktree, delete branch local+remote, clear local artifacts, prune [gone] branches.` → `always`
+- `Skip cleanup` — `Leave everything in place.` → `never`
+
+**Silent action**
+- `always` → `Running post-merge cleanup for {branch}`
+- `never` → `Skipping post-merge cleanup for {branch}`

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

@@ -0,0 +1,13 @@
+# `autoCreatePR`
+
+Controls whether the cycle pushes the working branch to remote and opens a pull request after local commits land, or stops at "commits made locally". Fires when the agent has buildable commits and no PR exists yet for the branch. Substitute `{branch}`.
+
+**Picker 1** — header `Open PR?`, question `"Push '{branch}' and open a pull request?"`
+- `Open the PR` — `Push branch and run gh pr create.` → `always`
+- `Ask me next time` — `Decide per cycle.` → `ask`
+- `Skip — I'll open it myself` — `Stop after the local commits.` → `never`
+
+**Silent action**
+- `always` → `Opening PR for {branch}`
+- `ask` → `Asking about PR creation`
+- `never` → `Skipping PR creation`

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

@@ -2,9 +2,9 @@
 
 Scan local git changes to scope the test run, or skip the scan.
 
-**Picker 1** — header `Local git scan`, question `"Scan git changes to scope what to test?"`
-- `Yes, scan changes` — `Test cases that match recent diffs get prioritized.` → `always`
-- `No, I'll specify` — `Skip the scan — I'll tell you what to test.` → `never`
+**Picker 1** — header `Scan changes?`, question `"Scan git changes to scope what to test?"`
+- `Scan changes` — `Test cases that match recent diffs get prioritized.` → `always`
+- `Skip scan` — `Skip — you'll tell me what to test.` → `never`
 
 **Silent action**
 - `always` → `Scanning git changes to scope the run`

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

@@ -0,0 +1,11 @@
+# `autoE2ETest`
+
+Run Stage 6 (E2E acceptance) at the end of every `/muggle-do` cycle, or fold the decision into pre-flight each time. Default `always` — running E2E every cycle is the point of `muggle-do`, so `never` is not offered.
+
+**Picker 1** — header `Run E2E acceptance?`, question `"Run Stage 6 every cycle, or decide each time?"`
+- `Always run` — `Run Stage 6 every cycle; no further prompts.` → `always`
+- `Decide each cycle` — `Surface the question in pre-flight each run.` → `ask`
+
+**Silent action**
+- `always` → `Running Stage 6`
+- `ask` → `Asking each cycle whether to run Stage 6`

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

@@ -8,4 +8,4 @@ Reuse the saved session, or force a fresh login. Substitute `{email}`.
 
 **Silent action**
 - `always` → `Continuing as {email}`
-- `never` → `Forcing a fresh login`
+- `never` → `Logging in fresh`

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

@@ -1,8 +1,8 @@
 # `autoPublishLocalResults`
 
-Upload local run artifacts to the Muggle cloud, or keep them local.
+Upload local run artifacts to the Muggle Test cloud, or keep them local.
 
-**Picker 1** — header `Share results?`, question `"Upload these results to the Muggle dashboard?"`
+**Picker 1** — header `Share results?`, question `"Upload these results to the Muggle Test dashboard?"`
 - `Upload them` — `Needed for the dashboard view, PR walkthrough, and team visibility.` → `always`
 - `Keep local-only` — `Stay on this machine — no dashboard view or PR walkthrough.` → `never`
 

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

@@ -0,0 +1,11 @@
+# `autoRebase`
+
+Rebase onto `origin/{default}` before dev servers / E2E, or run as-is. Substitute `{behind}` and `{default}`.
+
+**Picker 1** — header `Rebase first`, question `"Branch is {behind} commits behind origin/{default} — rebase first?"`
+- `Rebase first` — `Pull in default-branch changes so the run reflects the merged main line.` → `always`
+- `Run as-is` — `Skip the rebase.` → `never`
+
+**Silent action**
+- `always` → `Rebasing onto origin/{default} ({behind} behind)`
+- `never` → `Running as-is ({behind} behind origin/{default})`

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

@@ -0,0 +1,19 @@
+# `autoSelectLocalHost`
+
+Reuse the saved local dev server URL for this repo, or pick one each run. Substitute `{lastHost}` (the URL used in the previous run for this repo — omit the option entirely when no cache exists) and `{suggestedHost}` (auto-detected from running ports, e.g. `http://localhost:3000`).
+
+Cache lives at `<cwd>/.muggle-ai/last-host.json`. The calling skill **always** updates the cache after the user picks/types a URL — independent of Picker 2 — so `Use {lastHost}` reflects the most recent run.
+
+**Picker 1** — header `Local server`, question `"Which local URL should the test target?"`
+- `Use {lastHost}` — `From your last run in this repo.` → reuse cached URL. *Skip this option when no cache exists.*
+- `Use {suggestedHost}` — `Detected from a port that's running.` → use the suggestion
+- `Type a URL` — `Paste any URL.` → calling skill prompts for free-text input
+
+**Picker 2 — overrides shared template.** Fires after the user picks a URL.
+- Header `Remember this URL?`, question `"Always use {chosenHost} for this repo from now on, without asking?"`
+- `Yes, always` (sub: `You can change this later in muggle preferences.`) → `muggle-local-preferences-set` (`autoSelectLocalHost=always`, global). The cache is already up to date.
+- `Just this once` (sub: `I'll ask again next time.`) → don't save the preference. The cache still updates.
+
+**Silent action**
+- `always` (cache used) → `Using saved local URL {lastHost}`
+- `never` → no footer; the picker is the visible step.

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

@@ -1,7 +1,6 @@
 # `autoSelectProject`
 
-Reuse the cached project for this repo (`<cwd>/.muggle-ai/last-project.json`),
-or pick from the list. Substitute `{projectName}`.
+Reuse the saved project for this repo, or pick from the list. Substitute `{projectName}`.
 
 Picker 1 *is* the project list (rendered by the calling skill — format and
 tail options like "Show full list" / "Create new project" are skill-defined).

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

@@ -0,0 +1,11 @@
+# `autoUseWorktree`
+
+Create a worktree for the change, or work in the current checkout.
+
+**Picker 1** — header `Worktree`, question `"Create a git worktree for this change, or work in the current checkout?"`
+- `Create a worktree` — `Isolate the change so your current checkout stays untouched.` → `always`
+- `Use current checkout` — `Edit in place.` → `never`
+
+**Silent action**
+- `always` → `Creating a worktree for this change`
+- `never` → `Working in the current checkout`

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

@@ -1,10 +1,10 @@
 # `checkForUpdates`
 
-Check npm for a newer Muggle version at session start.
+Check npm for a newer Muggle Test version at session start.
 
-**Picker 1** — header `Update check`, question `"Check npm for a newer Muggle version? Requires a network call."`
-- `Yes, check` — `Quick network call — flags if you're behind.` → `always`
-- `No, skip` — `Skip the check — saves a network call at session start.` → `never`
+**Picker 1** — header `Update check`, question `"Check for a newer Muggle Test version (one quick network call)?"`
+- `Check now` — `Flags if you're behind.` → `always`
+- `Skip check` — `Saves a network call at session start.` → `never`
 
 **Silent action**
 - `always` → `Checked for updates`

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

@@ -4,7 +4,7 @@ Default place to run tests when the user's request is ambiguous.
 
 **Picker 1** — header `Where to run tests?`, question `"On your computer or in the cloud?"`
 - `On my computer` — `Real browser on localhost. Faster feedback while developing.` → `local`
-- `In the cloud` — `Muggle's cloud runs against a preview/staging URL.` → `remote`
+- `In the cloud` — `Muggle Test's cloud runs against a preview/staging URL.` → `remote`
 
 If the user's intent is already clear (e.g. "test on staging"), skip Picker 1
 — confirm with `"Yes, proceed in <mode>"` / `"Switch to <other mode>"` and

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

@@ -8,4 +8,4 @@ Auto-open the dashboard after a run, or just print the URL.
 
 **Silent action**
 - `always` → `Opening results on the dashboard`
-- `never` → `Just printing the link — no auto-open`
+- `never` → `Just printing the link`

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

@@ -1,30 +1,13 @@
 # `postPRVisualWalkthrough`
 
-Post a visual walkthrough of test results to a PR.
+Preference gate. Controls whether the cycle posts the visual walkthrough comment (per-test-case dashboard links + step-by-step screenshots) to the PR after E2E results are available, or stops at "results ready". Fires once per E2E result set when a PR exists for the working branch (if it doesn't, callers fire [`autoCreatePR`](autoCreatePR.md) separately). Substitute `{prNumber}`.
 
-**PR detection (mandatory before any picker).** Run `gh pr view --json number,title,url 2>/dev/null` first. The result picks Case A or B.
-Substitute `{prNumber}`, `{prTitle}` into prompts.
+**Picker 1** — header `Post to PR`, question `"Post the visual walkthrough to PR #{prNumber}?"`
+- `Post to #{prNumber}` — `Comment with screenshots is added to the PR.` → `always`
+- `Ask me each time` — `Decide per run.` → `ask`
+- `Skip` — `Walkthrough is not posted.` → `never`
 
-## Case A — open PR found
-
-**Picker 1** — header `Share with the team`, question `"Post a visual walkthrough to PR #{prNumber} ({prTitle})?"`
-- `Yes, post to #{prNumber}` — `Reviewers see clickable per-test screenshots and dashboard links.` → `always`
-- `Skip` — `Keep it off the PR — you can post later from the dashboard.` → `never`
-
-**Silent action (Case A)**
+**Silent action**
 - `always` → `Posting walkthrough to PR #{prNumber}`
-- `never` → `Skipping PR walkthrough for #{prNumber}`
-
-## Case B — no open PR
-
-Situational fork — saved value is *not* updated from this picker.
-
-**Picker 1** — header `No PR yet`, question `"This branch has no open PR. Create one and post the walkthrough, or skip?"`
-- `Create a PR and post` — `I'll open a PR for this branch, then attach the walkthrough.` → run PR-creation flow (calling skill's responsibility), then post.
-- `Skip` — `Skip the walkthrough this time — you can post later from the dashboard.` → continue.
-
-**Picker 2** — skipped entirely.
-
-**Silent action (Case B)** — when saved gate is `always` or `never` but no PR exists:
-- `always` → fall through to Case B Picker 1 (don't auto-create silently). Print: `(`postPRVisualWalkthrough = always`, but this branch has no PR — asking what to do.)`
-- `never` → `Skipping PR walkthrough — no open PR for this branch`
+- `ask` → `Asking about PR walkthrough`
+- `never` → `Skipping PR walkthrough`

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

@@ -1,6 +1,6 @@
 # `showElectronBrowser`
 
-Show the Electron browser during local tests, or run hidden.
+Show the browser during local tests, or run hidden.
 
 **Picker 1** — header `Browser window`, question `"Show the test browser as it runs?"`
 - `Show it` — `Watch the test live — useful when something's failing.` → `always` (omit `showUi`)

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

@@ -1,10 +1,10 @@
 # `suggestRelatedTestCases`
 
-After creating/running a test case, surface related ones already attached to the use case.
+After creating/running a test case, show related ones already attached to the use case.
 
-**Picker 1** — header `Related test cases`, question `"Surface related test cases already attached to this use case?"`
-- `Yes, suggest related` — `Catch test cases your import or change might have missed.` → `always`
-- `No, skip` — `Don't show suggestions — I'll ask if I want them later.` → `never`
+**Picker 1** — header `Related test cases`, question `"Show related test cases already attached to this use case?"`
+- `Show related` — `Catch test cases your import or change might have missed.` → `always`
+- `Skip` — `You can ask later if you want them.` → `never`
 
 **Silent action**
 - `always` → `Showing related test cases below`

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

@@ -1,10 +1,10 @@
 # `suggestRelatedUseCases`
 
-After creating/running a use case, surface related ones already in the project.
+After creating/running a use case, show related ones already in the project.
 
-**Picker 1** — header `Related use cases`, question `"Surface related use cases already in this project?"`
-- `Yes, suggest related` — `Catch use cases your import or change might have missed.` → `always`
-- `No, skip` — `Don't show suggestions — I'll ask if I want them later.` → `never`
+**Picker 1** — header `Related use cases`, question `"Show related use cases already in this project?"`
+- `Show related` — `Catch use cases your import or change might have missed.` → `always`
+- `Skip` — `You can ask later if you want them.` → `never`
 
 **Silent action**
 - `always` → `Showing related use cases below`

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

@@ -1,9 +1,11 @@
 ---
 name: muggle-repair
-description: Diagnose and fix a broken Muggle AI installation. Use when user types muggle repair or asks to fix Muggle setup.
+description: Diagnose and fix a broken Muggle AI installation. Use when user types muggle repair or asks to fix Muggle Test setup.
 ---
 
-# Muggle Repair
+# Muggle Test Repair
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-repair"`.
 
 Automatically diagnose and fix broken components.
 

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

@@ -1,9 +1,11 @@
 ---
 name: muggle-status
-description: Check health of the Muggle AI installation. Use when user types muggle status, asks for Muggle health, MCP health, or auth validity.
+description: Check health of the Muggle AI installation. Use when user types muggle status, asks for Muggle Test health, MCP health, or auth validity.
 ---
 
-# Muggle Status
+# Muggle Test Status
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-status"`.
 
 Run a full health check and report results.
 
@@ -13,7 +15,7 @@ Gates run per `preference-gates/README.md`.
 
 | Preference | Step | Decision it gates |
 |------------|------|-------------------|
-| `checkForUpdates` | Check 4 | Check for newer Muggle version |
+| `checkForUpdates` | Check 4 | Check for newer Muggle Test version |
 
 ## Checks
 
@@ -24,8 +26,9 @@ Gates run per `preference-gates/README.md`.
 3. **Authentication** — call `muggle-remote-auth-status`. Report whether credentials are valid and when they expire.
 
 4. **CLI version** — gate `checkForUpdates` (per `preference-gates/README.md`):
-   - Pro-action: run the check below.
-   - Skip-action: render the row as `[skip]  check disabled by preference`.
+   - `always` → run the check below.
+   - `never` → render the row as `[skip]  check disabled by preference`.
+   - `ask` → run Picker 1 from `preference-gates/checkForUpdates.md` via `AskUserQuestion`; map the answer back to one of the actions above.
 
    When the check runs: capture installed (`muggle --version`) and latest (`npm view @muggleai/works version`). Compare with `sort -V`; flag as out-of-date only when latest is strictly greater.