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

[KatalKavya96]

Summary

• Add a first-run welcome guide for the Mentoring family, covering welcome, good-first-issue-sweep, good-first-issue-author, and newcomer-issue-explainer, helping maintainers discover the available workflows and get started through natural-language requests.
• Document required and optional configuration, personal setup versus project adoption, and explicit maintainer confirmation before posting comments, creating issues, or applying labels.
• Link the guide from the Mentoring README, add first-run regression tests and a preflight-floor 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 and first-run evaluation coverage

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:
  • Setup-preflight welcome regression tests passed.
  • Preflight fixture reports regenerated and verified with render-preflight-fixtures.py --check.
  • Rendered Mentoring guide verified against the 70-line limit.
  • git diff --check passed.
  • Repository-wide pytest, Ruff, mypy, documentation synchronization, and validators passed through prek.

RFC-AI-0004 compliance

• HITL — maintainer confirmation is required before posting comments, creating issues, or applying labels.
• Sandbox — no new unrestricted host access or runtime permissions introduced.
• Vendor neutrality — project-specific values are resolved through configuration; existing placeholder conventions remain unchanged.
• Conversational + correctable — natural-language examples and the customization workflow are documented.
• Write-access discipline — mentoring skills draft first and require explicit confirmation before publishing.
• Privacy LLM — not affected by this change.

Linked issues

Closes #1659

Refs #1654

Notes for reviewers (optional)

• Follows the existing 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.
• Reuses the shared welcome rules and generated footer, without introducing new runtime behavior.
• The new preflight-floor fixture uses welcome with its actual surface hash, sha256:a61c6575d69da08a.
• Covers all four mentoring skills in family discovery tests.
• Required setup files are distinguished from optional mentoring customization files.

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

[KatalKavya96]

Hi @potiuk,

I've implemented the Mentoring family welcome guide for #1659, following the established pattern from #1669.

It covers all four mentoring skills, their configuration requirements, example workflows, and maintainer confirmation boundaries. I've also added the README link, first-run evaluation fixture, and regression tests.

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

[Kaap10]

Thanks @KatalKavya96 for adding the mentoring family welcome guide!

Tested locally — the guide rendering looks clean, test_welcome.py passes all 51 tests across all four mentoring skills, render-preflight-fixtures.py --check passes with zero drift, and the case counts in the evals READMEs are updated consistently.

Left one inline suggestion on docs/mentoring/README.md regarding layout consistency with other family READMEs (security, utilities, contributor-growth). Other than that, everything looks solid!

[potiuk]

Adds the mentoring-family first-run welcome guide in the same shape as the utilities and security guides, with matching tests, a preflight-floor eval case and the README pointer; the content checks out against the four mentoring skills and their config files.

I pushed one small fixup commit (aea0177) rather than leave a nit for another round trip: the guide said existing welcomes and handled threads "are skipped as appropriate", which leaves a newcomer guessing what actually gets skipped. It now reads "Contributors who were already welcomed, and threads already handled, are skipped.", and the case-11-mentoring-first-run report that embeds the guide is re-rendered to match. Thanks for the guide!

---

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.