[KatalKavya96]

Summary

• Add a first-run welcome guide for the Setup family, covering all 11 skills and helping newcomers understand installation, personal configuration, project adoption, sandbox isolation, verification, upgrades, privacy controls, and framework maintenance through natural-language requests.
• Explain optional configuration, personal versus project-wide setup, and the distinction between read-only checks and operations that modify local files or repository state. Preserve existing confirmation requirements and the read-only framework snapshot boundary.
• Integrate the guide into docs/setup/README.md using the standardized family README layout, add welcome regression tests and a first-run evaluation fixture, regenerate affected welcome reports, and update evaluation case counts.

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Groovy reference impl
• Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• Project template (projects/_template/)
• CI / dev loop (prek, workflows, validators)
• Other: Setup-preflight welcome guide, regression tests, and evaluation fixture

Test plan

• prek run --all-files passes
• For Python packages touched: uv run pytest / ruff check / mypy passes
• For Groovy bridges touched: command-line invocation tested end-to-end
• For skill changes: eval suite passes for the affected skill
  (PYTHONPATH=tools/skill-evals/src python3 -m skill_evals.runner tools/skill-evals/evals/<skill>/)
• For skill behaviour changes: a new or updated eval fixture is included in this PR
  (a regression test for the bug fixed / the behaviour added — see CONTRIBUTING.md)
• Other:
  • Added a first-run regression test covering all 11 Setup family skills and welcome-guide ordering.
  • Added case-16-setup-first-run using the status skill and its actual surface hash.
  • Regenerated affected preflight reports and validated them through the render-preflight-fixtures hook.
  • Added Setup to the guide-discovery, length-limit, and shared-footer regression checks.
  • Repository-wide pytest, Ruff check and format, mypy, documentation synchronization, and skill validation passed through prek.
  • git diff --check passed during implementation.

RFC-AI-0004 compliance

• HITL — documents the existing approval boundaries for installation, adoption, upgrades, configuration changes, and repository mutations.
• Sandbox — explains secure-agent isolation and verification without introducing new host permissions or changing sandbox behavior.
• Vendor neutrality — preserves the existing project configuration conventions and supports the framework's documented installation methods.
• Conversational + correctable — includes natural-language requests and examples of project-specific configuration and override customization.
• Write-access discipline — distinguishes read-only diagnostics from approved modifications, while preserving the read-only framework snapshot boundary.
• Privacy LLM — the guide introduces the existing privacy-llm workflow but does not modify privacy enforcement or model-routing behavior.

Linked issues

Closes #1662

Refs #1654

Notes for reviewers (optional)

• Follows the first-run welcome-guide pattern established in feat(setup): first-run welcome guides, general and for the security skills #1653 and feat(setup): first-run welcome guide for the utilities family (#1663) #1669, including the standardized README introduction used across the recently merged families.
• Covers all 11 Setup family skills:
  • setup
  • status
  • welcome-guide
  • isolated-setup-install
  • isolated-setup-verify
  • isolated-setup-doctor
  • isolated-setup-update
  • privacy-llm
  • shared-config-sync
  • override-upstream
  • upstream-fix
• Reuses the existing shared welcome footer and setup-preflight machinery. No production skill behavior, permission model, or security control is changed.
• The first-run fixture uses status with surface_hash: sha256:85dfb8b48739fc11.
• Increases the setup evaluation count from 135 to 136 and the preflight-floor fixture count from 15 to 16, based on the upstream branch used for this PR.
• The Setup README retains its existing The first run and Before the first run sections, with the welcome-guide introduction added immediately before them.
• All repository-wide checks passed locally.

AI assistance disclosure: AI assistance was used for repository inspection, implementation drafting, and review. Changes were applied and validated locally by the contributor.

[KatalKavya96]

Hi @potiuk,

I've completed the Setup family first-run welcome guide for #1662, following the established pattern from our previously merged welcome-guide contributions.

It covers all 11 Setup skills, including installation, configuration, adoption, sandbox isolation, verification, upgrades, privacy controls, and upstream fixes.

I've also added the standardized README integration, first-run evaluation fixture, and regression tests, while preserving the existing confirmation and safety boundaries.

All repository-wide checks passed locally with prek run --all-files.
Thanks!

[potiuk]

Thanks for the setup-family guide. It follows the established pattern closely: the 11 skills, the four optional config files and the /magpie-setup:… invocation forms all match the family as it ships, and test_welcome.py exercises the new guide on discovery, ordering, length and footer.

#1673 and #1724 merged after this was opened and edit the same eval counts, the case-9 report and the test_welcome.py lists, so rather than send it back I rebased the branch onto main and pushed two commits:

• your commit, rebased:
  • the counts taken from main (140 cases total, 20 for preflight-floor, your setup description appended to main's row);
  • test_welcome.py keeps both the repo-health and the setup entries in each list;
  • case-9 re-rendered with tools/dev/render-preflight-fixtures.py;
  • with one more family listed, the general guide went to 71 lines against the 70-line limit, so guides/general.md joins two sentences that were split across lines to stay under it;
• a fixup (b3f9fb79):
  • the eval case is renumbered to case-20-setup-first-run, after main's floor cases and the repo-health case;
  • step 5 of the flow now presents isolated-setup-update as the read-only drift check it is ("check my sandbox for drift"), with its own emoji;
  • "make it yours" now names what a request becomes and how to upstream it;
  • one sentence per line where the guide wrapped mid-sentence.

Thanks!

---

This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The maintainer
approving this PR has read the findings and signed off. If
something feels off, please reply on the PR and a maintainer
will follow up.

More on how Apache Magpie handles maintainer review:
Contributing guide.