feat(setup): add setup family first-run welcome guide

docs/setup/README.md

@@ -63,6 +63,12 @@ New to Magpie? The [quick start](../quick-start.md) walks the whole path in
 one place — install, the first `/magpie-setup:setup` run, and a recording of it
 happening — plus the other agents and the secure-isolation setup to run next.
 
+The first setup skill you run opens with a one-minute
+[welcome guide](../../plugins/magpie-setup/skills/setup/setup_preflight/guides/setup.md):
+the typical flow, what needs configuring, what to ask it, and how to make it yours.
+Dismiss it, or hide it for good, from its last line;
+*"show the setup welcome again"* or `/magpie-setup:welcome-guide setup` brings it back.
+
 ### The first run
 
 This family is what the other nine defer to. `/magpie-setup:setup` (`/magpie-setup`

plugins/magpie-setup/skills/setup/setup_preflight/guides/general.md

@@ -24,8 +24,7 @@ On a pinned-snapshot install the commands are shorter: `/magpie-setup config`, `
 - 🧩 Gemini CLI takes `--auto-update` at install time; Codex has no auto-update, so run `codex plugin marketplace upgrade apache-magpie`
 
 After an update, the next skill you run checks your configuration against it and proposes any fixes;
-`/magpie-setup:setup reconcile` checks everything at once
-(on a pinned snapshot, `/magpie-setup upgrade` does the update).
+`/magpie-setup:setup reconcile` checks everything at once (on a pinned snapshot, `/magpie-setup upgrade` does the update).
 
 ## 💬 Just ask
 
@@ -41,8 +40,7 @@ Describe what you want a skill to do for you:
 - *"when you triage PRs, leave the bot-authored ones alone"*
 
 Magpie records it as an override for that skill (`/magpie-setup:setup override <skill>`).
-Worth sharing? Say *"upstream this change to Magpie"* —
-it makes the change generic and opens a PR to `apache/magpie` for you to review (`/magpie-setup:override-upstream`).
+Worth sharing? Say *"upstream this change to Magpie"* — it makes the change generic and opens a PR to `apache/magpie` for you to review (`/magpie-setup:override-upstream`).
 
 ## 📚 More guides
 

plugins/magpie-setup/skills/setup/setup_preflight/guides/setup.md

@@ -0,0 +1,57 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+     https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# 🐦 Magpie here — your setup sidekick
+
+A one-minute tour, then straight back to what you asked for.
+
+## 🔄 The typical flow
+
+1. 🧭 **Check status** — *"show how Magpie is installed and adopted here"*
+2. 🛠️ **Install and configure** — *"set up Magpie for me"*
+3. 🔐 **Isolate the agent** — *"install the secure agent sandbox"*
+4. ✅ **Verify and diagnose** — *"verify isolation"* or *"diagnose my sandbox"*
+5. 🆙 **Check for drift and upgrade** — *"check my sandbox for drift"* or *"upgrade Magpie"*
+6. 🏗️ **Adopt for the team** — *"adopt Magpie for this repository"*
+
+Other skills help configure LLM privacy, synchronize shared config, upstream useful overrides, propose framework bug fixes, and replay welcome guides.
+
+Read-only checks report findings.
+Installation, adoption, upgrades, configuration writes, and repository changes follow their own approval steps.
+Never edit Magpie's gitignored, read-only framework snapshot directly.
+
+## ⚙️ Configure it
+
+Nothing is required before using the Setup family:
+
+- 📋 **Setup defaults** — optional `magpie-setup.md`
+- 🔏 **Privacy policy** — optional `privacy-llm.md`
+- 🧩 **Project identity** — optional `project.md`
+- 🔗 **Trusted skill sources** — optional `skill-sources.md`
+
+`/magpie-setup:setup config` writes personal configuration.
+`/magpie-setup:setup adopt` proposes committed project-wide settings.
+Review the plan and confirm before any project-wide mutation.
+
+## 💬 Just ask
+
+Talk to Magpie in plain language:
+
+- *"show Magpie status in this checkout"*
+- *"install Magpie and configure it just for me"*
+- *"secure the agent with a sandbox and verify it"*
+- *"set up privacy rules for model access"*
+- *"check for configuration drift after an upgrade"*
+- *"prepare a framework fix for this broken setup helper"*
+
+## 🎨 Make it yours
+
+Describe how your setup should behave:
+
+- *"use our approved skill sources"*
+- *"keep my personal privacy rules separate from project policy"*
+
+Magpie records each request as an override of the setup skill it touches.
+If other projects would want it too, say *"upstream this change to Magpie"* and review the generic `apache/magpie` PR it prepares.
+
+<!-- welcome footer: generated from guides/_footer.md -->

tools/setup-preflight/tests/test_welcome.py

@@ -184,6 +184,29 @@ def test_the_repo_health_family_guide_comes_on_the_next_run(project: Path, versi
     assert due(project, "ci-runner-audit") == [("general", "again")]
 
 
+def test_the_setup_family_guide_comes_on_the_next_run(project: Path, version) -> None:
+    for skill in (
+        "isolated-setup-doctor",
+        "isolated-setup-install",
+        "isolated-setup-update",
+        "isolated-setup-verify",
+        "override-upstream",
+        "privacy-llm",
+        "setup",
+        "shared-config-sync",
+        "status",
+        "upstream-fix",
+        "welcome-guide",
+    ):
+        assert welcome.family_of(skill) == "setup"
+
+    assert due(project, "status") == [("general", "first-run")]
+    welcome.record(project, "general", "seen")
+    assert due(project, "status") == [("setup", "first-run")]
+    welcome.record(project, "setup", "seen")
+    assert due(project, "status") == [("general", "again")]
+
+
 def test_at_most_one_guide_per_run(project: Path, version) -> None:
     for _ in range(8):
         found = welcome_findings(project, SECURITY_SKILL)
@@ -491,6 +514,7 @@ def test_the_rules_section_and_all_guides_ship() -> None:
         "pr-management",
         "contributor-growth",
         "repo-health",
+        "setup",
     } <= set(welcome.guides())
     assert welcome.family_guides() == [g for g in welcome.guides() if g != "general"]
 
@@ -507,6 +531,7 @@ def test_the_rules_section_and_all_guides_ship() -> None:
         "pr-management",
         "contributor-growth",
         "repo-health",
+        "setup",
     ],
 )
 def test_each_guide_is_short_and_ends_with_the_way_back(name: str) -> None:
@@ -536,6 +561,7 @@ def test_the_footer_is_shared_and_filled_in_per_guide() -> None:
     pr_management = welcome.guide("pr-management") or ""
     contributor_growth = welcome.guide("contributor-growth") or ""
     repo_health = welcome.guide("repo-health") or ""
+    setup = welcome.guide("setup") or ""
     for text in (
         security,
         general,
@@ -546,6 +572,7 @@ def test_the_footer_is_shared_and_filled_in_per_guide() -> None:
         pr_management,
         contributor_growth,
         repo_health,
+        setup,
     ):
         assert "{{" not in text
         assert "welcome footer: generated" not in text
@@ -567,6 +594,8 @@ def test_the_footer_is_shared_and_filled_in_per_guide() -> None:
     assert "--family contributor-growth --color=always" in contributor_growth
     assert "`/magpie-setup:welcome-guide repo-health`" in repo_health
     assert "--family repo-health --color=always" in repo_health
+    assert "`/magpie-setup:welcome-guide setup`" in setup
+    assert "--family setup --color=always" in setup
 
 
 def test_list_prints_every_guide(capsys) -> None:

tools/skill-evals/README.md

@@ -11,7 +11,7 @@ Behavioral eval harness for Apache Magpie skills. Each eval suite tests a skill
 
 Suites are currently implemented for:
 
-- **setup** — 139 cases across 30 steps (step-verify-drift, step-overrides-surface, step-override-bypass, step-m3-baseline-pick, step-m4-install-gates, step-m5-no-repo-offer, step-m5-companion-offer, step-upgrade-companion-offer, step-adopt-settings-merge, verify-default-set, uninstall-default-set, lock-marketplace-parse, adopt-write-floor, setup-prefill-from-floor, preflight-floor, upgrade-adoption-split, verify-floor, adopt-review-process, adopt-security-list, step-reconcile, step-verify, step-config-stamp, step-config-adversarial, step-config-mail, step-adopt-stamp, step-upgrade-stamp, step-delegate-propose, config-vcs-backend, config-local-custom-parser)
+- **setup** — 140 cases across 30 steps (step-verify-drift, step-overrides-surface, step-override-bypass, step-m3-baseline-pick, step-m4-install-gates, step-m5-no-repo-offer, step-m5-companion-offer, step-upgrade-companion-offer, step-adopt-settings-merge, verify-default-set, uninstall-default-set, lock-marketplace-parse, adopt-write-floor, setup-prefill-from-floor, preflight-floor, upgrade-adoption-split, verify-floor, adopt-review-process, adopt-security-list, step-reconcile, step-verify, step-config-stamp, step-config-adversarial, step-config-mail, step-adopt-stamp, step-upgrade-stamp, step-delegate-propose, config-vcs-backend, config-local-custom-parser)
 - **setup-isolated-setup-install** — 19 cases across 5 steps (runtime-routing, step-snapshot-drift, step-scope-confirm, step-hardware-key, step-roborev-exclusion)
 - **setup-privacy-llm** — 6 cases across 2 steps (step-1-resolve, step-4-gate)
 - **setup-shared-config-sync** — 12 cases across 2 steps (step-3-decide-action, step-5-draft-commit)

tools/skill-evals/evals/setup/README.md

@@ -5,7 +5,7 @@
 
 Behavioral evals for the `setup` skill.
 
-## Suites (139 cases total)
+## Suites (140 cases total)
 
 | Suite | Step | Cases | What it covers |
 |---|---|---|---|
@@ -25,7 +25,7 @@ Behavioral evals for the `setup` skill.
 | adopt-review-process | adopt.md § Step 4c | 5 | a fresh adopt finding two deviations in the confirmed documents where one is accepted and one rejected, and a release policy left alone because that family is not in the floor; a re-adoption reviewing only the one family the floor diff added; a re-adoption that adds no family, where edited process documents are still not re-read; a sentence that would weaken a merge confirmation gate, dropped and named while a label deviation beside it is written; and a repo whose only candidate document the maintainer un-ticks, skipping the step |
 | adopt-security-list | adopt.md § Step 4b | 4 | an ASF project whose dedicated security list is in its docs and on the ASF page (recommend `security@`); an ASF project with no dedicated list (no recommendation, `private@` only as a flagged fallback); a non-ASF project, which is not asked; and conflicting evidence between `SECURITY.md` and the ASF page (no recommendation, flagged fallback) |
 | setup-prefill-from-floor | install.md § Step M0b | 4 | adopted (propose the floor), unadopted (framework defaults), a foreign marketplace called out, and a snapshot lock falling through |
-| preflight-floor | preflight-block.md § Pre-flight | 19 | at floor (silent), below floor (update), plugin missing (install), foreign marketplace (ask first, run nothing), no `claude` CLI (print), unadopted (propose setup), `apache/magpie` in an alarming context (update anyway, unasked), unreadable `claude plugin list --json` (silent, treated as unknown not absent), first Magpie run (show the general welcome guide, record it, carry on), first utilities run (show the utilities welcome guide, record it, carry on), first mentoring run (show the mentoring welcome guide, record it, carry on), first pairing run (show the pairing welcome guide, record it, carry on), first issue run (show the issue welcome guide, record it, carry on), first pr-management run (show the pr-management welcome guide, record it, carry on), first contributor-growth run (show the contributor-growth welcome guide, record it, carry on), below floor on Codex (marketplace upgrade), below floor on Gemini (update the extension once), at floor on Gemini (silent), first repo-health run (show the repo-health welcome guide, record it, carry on) |
+| preflight-floor | preflight-block.md § Pre-flight | 20 | at floor (silent), below floor (update), plugin missing (install), foreign marketplace (ask first, run nothing), no `claude` CLI (print), unadopted (propose setup), `apache/magpie` in an alarming context (update anyway, unasked), unreadable `claude plugin list --json` (silent, treated as unknown not absent), first Magpie run (show the general welcome guide, record it, carry on), first utilities run (show the utilities welcome guide, record it, carry on), first mentoring run (show the mentoring welcome guide, record it, carry on), first pairing run (show the pairing welcome guide, record it, carry on), first issue run (show the issue welcome guide, record it, carry on), first pr-management run (show the pr-management welcome guide, record it, carry on), first contributor-growth run (show the contributor-growth welcome guide, record it, carry on), below floor on Codex (marketplace upgrade), below floor on Gemini (update the extension once), at floor on Gemini (silent), first repo-health run (show the repo-health welcome guide, record it, carry on), first setup run (show the setup welcome guide, record it, carry on) |
 | upgrade-adoption-split | upgrade.md § Step 0b | 4 | not adopted (nothing staged), adopted (floor raised and staged), already ahead (floor unchanged), snapshot method (falls through) |
 | verify-floor | verify.md § Adoption floor | 4 | no lock (not a fault), ahead of floor with extra plugins (not a fault), a shortfall (a fault), a floor plugin the marketplace no longer ships (a fault, not installed around) |
 | step-reconcile | reconcile.md § The sweep | 3 | a clean sweep on a pinned-snapshot install (anchor present, config resolved — stamp written, nothing proposed), a renamed step heading stranding an override's anchor (one re-anchor proposal named), a marketplace install whose plugin cache is sandbox-denied (anchor resolution left `unchecked`, config resolution still completes) |

tools/skill-evals/evals/setup/preflight-floor/fixtures/case-20-setup-first-run/case-meta.json

@@ -0,0 +1 @@
+{"tags":["local-smoke"]}

tools/skill-evals/evals/setup/preflight-floor/fixtures/case-20-setup-first-run/expected.json

@@ -0,0 +1 @@
+{"action": "welcome", "commands": [], "blocks": false}

tools/skill-evals/evals/setup/preflight-floor/fixtures/case-20-setup-first-run/report.md

@@ -0,0 +1,37 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+     https://www.apache.org/licenses/LICENSE-2.0 -->
+
+There is no `.apache-magpie.lock`, no `.apache-magpie-overrides/` and no
+`.apache-magpie-local/` at the repo root. The running agent is Claude Code
+with magpie-setup 0.4.0 installed.
+
+The user has already seen the initial general welcome guide on an earlier run.
+The invoked skill's own frontmatter reads `name: status` and
+`surface_hash: sha256:85dfb8b48739fc11`; it belongs to the setup family.
+This is the first time a setup skill has run here.
+The user asked it to "show Magpie status".
+
+The pre-flight command printed:
+
+```json
+{
+  "findings": [
+    {
+      "code": "welcome",
+      "facts": {
+        "family": "setup",
+        "guide": "# \ud83d\udc26 Magpie here \u2014 your setup sidekick\n\nA one-minute tour, then straight back to what you asked for.\n\n## \ud83d\udd04 The typical flow\n\n1. \ud83e\udded **Check status** \u2014 *\"show how Magpie is installed and adopted here\"*\n2. \ud83d\udee0\ufe0f **Install and configure** \u2014 *\"set up Magpie for me\"*\n3. \ud83d\udd10 **Isolate the agent** \u2014 *\"install the secure agent sandbox\"*\n4. \u2705 **Verify and diagnose** \u2014 *\"verify isolation\"* or *\"diagnose my sandbox\"*\n5. \ud83c\udd99 **Check for drift and upgrade** \u2014 *\"check my sandbox for drift\"* or *\"upgrade Magpie\"*\n6. \ud83c\udfd7\ufe0f **Adopt for the team** \u2014 *\"adopt Magpie for this repository\"*\n\nOther skills help configure LLM privacy, synchronize shared config, upstream useful overrides, propose framework bug fixes, and replay welcome guides.\n\nRead-only checks report findings.\nInstallation, adoption, upgrades, configuration writes, and repository changes follow their own approval steps.\nNever edit Magpie's gitignored, read-only framework snapshot directly.\n\n## \u2699\ufe0f Configure it\n\nNothing is required before using the Setup family:\n\n- \ud83d\udccb **Setup defaults** \u2014 optional `magpie-setup.md`\n- \ud83d\udd0f **Privacy policy** \u2014 optional `privacy-llm.md`\n- \ud83e\udde9 **Project identity** \u2014 optional `project.md`\n- \ud83d\udd17 **Trusted skill sources** \u2014 optional `skill-sources.md`\n\n`/magpie-setup:setup config` writes personal configuration.\n`/magpie-setup:setup adopt` proposes committed project-wide settings.\nReview the plan and confirm before any project-wide mutation.\n\n## \ud83d\udcac Just ask\n\nTalk to Magpie in plain language:\n\n- *\"show Magpie status in this checkout\"*\n- *\"install Magpie and configure it just for me\"*\n- *\"secure the agent with a sandbox and verify it\"*\n- *\"set up privacy rules for model access\"*\n- *\"check for configuration drift after an upgrade\"*\n- *\"prepare a framework fix for this broken setup helper\"*\n\n## \ud83c\udfa8 Make it yours\n\nDescribe how your setup should behave:\n\n- *\"use our approved skill sources\"*\n- *\"keep my personal privacy rules separate from project policy\"*\n\nMagpie records each request as an override of the setup skill it touches.\nIf other projects would want it too, say *\"upstream this change to Magpie\"* and review the generic `apache/magpie` PR it prepares.\n\n## \ud83d\udc4b About this guide\n\n- **Continue** \u2014 show it again next time (three times at most)\n- **Dismiss** \u2014 hide it until the next Magpie upgrade\n- **Don't show again** \u2014 hide it for good; say *\"show the setup welcome again\"* to bring it back\n\nShow this again any time: `/magpie-setup:welcome-guide setup`\n(`/magpie-setup-welcome-guide setup` on a pinned snapshot).\n\n\ud83c\udf08 Prefer it in colour? Run this yourself \u2014 the `!` prefix runs it as a shell command:\n\n```text\n! PYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" python3 -m setup_preflight.welcome show --family setup --color=always\n```\n",
+        "max_shown": 3,
+        "reason": "first-run",
+        "shown": 0
+      },
+      "scope": "family",
+      "section": "welcome"
+    }
+  ],
+  "rules": {
+    "welcome": "## welcome \u2014 a first-run welcome guide is due\n\nA welcome guide is due on this run: `facts.family` names it\n(`general`, for the first Magpie skill this user runs here, or the skill's own family),\nand `facts.reason` says why (`first-run`, `again`, or `upgraded` after a dismissal).\n`facts.guide` is the guide. The checker shows at most one guide per run and has already picked it.\n\n1. **Show `facts.guide` to the user verbatim**, as Markdown, before the work they asked for.\n   Do not summarise, reword, trim, or add to it, and substitute nothing in it:\n   its placeholders (`<security-list>`, `<tracker>`, `<family>`, \u2026) are meant to be read as written.\n2. **Offer the three choices in one line**:\n   **Continue** (show again next time) \u00b7 **Dismiss** (hide until the next Magpie upgrade) \u00b7 **Don't show again**.\n3. **Record `seen` at once**, which is what no answer means, then carry on with the user's request in the same turn.\n   Never block the requested work on the guide, and never wait for an answer before starting it.\n4. **When the user picks Dismiss or Don't show again** \u2014 now or later in the session \u2014 record that choice;\n   it replaces `seen`. Continue needs nothing further.\n\n```bash\nPYTHONPATH=\".apache-magpie-local:$(git rev-parse --git-common-dir)/../.apache-magpie-local:$(git rev-parse --git-common-dir)/apache-magpie\" \\\n  python3 -m setup_preflight.welcome record --family <facts.family> --choice <seen|dismiss|never>\n```\n\n`seen` brings the guide back on a later run, `facts.max_shown` recorded showings in all (`facts.shown` so far);\n`dismiss` hides it until the framework version changes; `never` hides it until re-enabled.\nEvery write merges into the personal layer's `reconciled.json` under `welcome.<facts.family>`, keeping every other key;\nnever write it by hand.\nIf the command exits non-zero, say nothing more about it and carry on.\n\nAny guide can be shown again on request with `/magpie-setup:welcome-guide [<family>]`,\nwhich also turns a hidden one back on."
+  },
+  "verdict": "action"
+}
+```

tools/skill-evals/evals/setup/preflight-floor/fixtures/case-20-setup-first-run/state.json

@@ -0,0 +1,20 @@
+{
+  "lock": null,
+  "plugins": [
+    [
+      "magpie-setup",
+      "0.4.0"
+    ]
+  ],
+  "reconciled": {
+    "welcome": {
+      "general": {
+        "choice": "seen",
+        "shown": 1
+      }
+    }
+  },
+  "skill": "status",
+  "welcome": true,
+  "hash": "sha256:85dfb8b48739fc11"
+}