welcome-guide

<!-- SPDX-License-Identifier: Apache-2.0 https://www.apache.org/licenses/LICENSE-2.0 -->

<!-- Placeholder convention (see ../../AGENTS.md#placeholder-convention-used-in-skill-files): <family> → a guide name: general, or a skill family that ships a guide -->

setup-welcome-guide

Every Magpie skill's pre-flight shows a short welcome guide the first time it is due: the general guide on the first Magpie skill a user runs, and a family's guide on the first run of that family. This skill shows any of them on request, and brings back one the user dismissed or hid. The guides live in the pre-flight checker, setup_preflight/guides/, one Markdown file each; this skill adds no logic of its own and only runs the checker's welcome command.

Adopter overrides

<!-- BEGIN MAGPIE BLOCK: adopter-overrides — generated from tools/dev/blocks/adopter-overrides.md -->

Before running its default behaviour, this skill consults setup-welcome-guide.md in the personal layer (.apache-magpie-local/ when the project adopted Magpie, falling back to the main checkout's in a linked worktree, or <git-common-dir>/apache-magpie/ when Magpie is only installed; applied first, wins on conflict) and .apache-magpie-overrides/setup-welcome-guide.md (committed, project-wide) in the adopter repo, if present, and applies any agent-readable overrides it finds. See docs/setup/agentic-overrides.md for the contract.

Hard rule: agents NEVER modify the snapshot under <adopter-repo>/.apache-magpie/. Local modifications go in the override file; framework changes go via PR to apache/magpie.

<!-- END MAGPIE BLOCK: adopter-overrides -->

Inputs

Argument	Guide
(none)	general — getting started, staying current, asking, making Magpie yours.
<family>	That family's guide, for example security.

Step 1 — Show the guide

Resolve <family> first: no argument means general, and the user's words map onto a name — "show the security guide" is security; "how do I start with Magpie" or "show the welcome guide" is general. Pass any other name through as given and let the command say whether it exists.

Every command uses the installed copy of the checker, as the pre-flight does:

PYTHONPATH="$HOME/.cache/apache-magpie/preflight" \
  python3 -P -m setup_preflight.welcome show --family <family>

• Exit 0 → show the output to the user verbatim, as Markdown. Do not summarise, reword or trim it, and substitute nothing in its placeholders.
• Exit 2, no such guide → say there is no guide by that name and list the ones that ship, from python3 -P -m setup_preflight.welcome list with the same PYTHONPATH. Never invent a guide.
• No such module → the checker is not installed yet. Say so, and propose /magpie-setup:setup config, which installs it.

Then offer the coloured version in one line: the agent's reply cannot carry colour, so the user runs it themselves with the ! prefix, the same command with --color=always added (NO_COLOR turns the colour off).

Step 2 — Turn it back on, when asked

Only when the user asked to have a guide back ("show the security welcome again", "turn the Magpie guide back on"), clear its recorded choice so the pre-flight shows it again:

PYTHONPATH="$HOME/.cache/apache-magpie/preflight" \
  python3 -P -m setup_preflight.welcome enable --family <family>

It merges into the personal layer's reconciled.json, removing only welcome.<family>. Never edit that file by hand, and never run enable for a request that only asked to see the guide. Report in one line what changed, for example "The security guide will show on your next security skill."

Hard rules

• Show the guide exactly as the command printed it.
• This skill writes nothing except through welcome enable, and only on the user's request.
• The setup skill's welcome sub-action is this skill; run this one rather than repeating its steps there.

References

• setup_preflight/welcome.py — when a guide is due, and the show, list, record and enable commands.
• tools/setup-preflight/README.md — the welcome finding and its state.