feat(setup): first-run welcome guides, general and for the security skills

.agents/skills/magpie-setup-welcome-guide

@@ -0,0 +1 @@
+../../plugins/magpie-setup/skills/welcome-guide

.claude-plugin/marketplace.json

@@ -76,7 +76,7 @@
       "name": "magpie-setup",
       "source": "./plugins/magpie-setup",
       "version": "0.9.0.dev202610140816",
-      "description": "Apache Magpie setup family (10 skills)."
+      "description": "Apache Magpie setup family (11 skills)."
     },
     {
       "name": "magpie-utilities",

.claude/skills/magpie-setup-welcome-guide

@@ -0,0 +1 @@
+../../.agents/skills/magpie-setup-welcome-guide

.github/labeler.yml

@@ -77,6 +77,7 @@ capability:platform:
           - 'plugins/magpie-setup/skills/shared-config-sync/**'
           - 'plugins/magpie-setup/skills/status/**'
           - 'plugins/magpie-setup/skills/upstream-fix/**'
+          - 'plugins/magpie-setup/skills/welcome-guide/**'
           - 'plugins/magpie-utilities/skills/report-framework-issue/**'
           - 'tools/skill-evals/evals/report-framework-issue/**'
           - 'tools/skill-evals/evals/setup-isolated-setup-doctor/**'
@@ -88,6 +89,7 @@ capability:platform:
           - 'tools/skill-evals/evals/setup-shared-config-sync/**'
           - 'tools/skill-evals/evals/setup-status/**'
           - 'tools/skill-evals/evals/setup-upstream-fix/**'
+          - 'tools/skill-evals/evals/setup-welcome-guide/**'
           - 'tools/skill-evals/evals/setup/**'
 
 capability:reassess:
@@ -389,6 +391,7 @@ family:setup:
           - 'tools/skill-evals/evals/setup-shared-config-sync/**'
           - 'tools/skill-evals/evals/setup-status/**'
           - 'tools/skill-evals/evals/setup-upstream-fix/**'
+          - 'tools/skill-evals/evals/setup-welcome-guide/**'
           - 'tools/skill-evals/evals/setup/**'
 
 family:tools:

.github/skills/magpie-setup-welcome-guide

@@ -0,0 +1 @@
+../../.agents/skills/magpie-setup-welcome-guide

.grok/skills/magpie-setup-welcome-guide

@@ -0,0 +1 @@
+../../.agents/skills/magpie-setup-welcome-guide

.kiro/skills/magpie-setup-welcome-guide

@@ -0,0 +1 @@
+../../.agents/skills/magpie-setup-welcome-guide

README.md

@@ -175,7 +175,7 @@ means and which modes are still proposed vs. shipping today.
 
 | Family | Type | Modes | Purpose | Detail |
 |---|---|---|---|---|
-| [**setup**](docs/setup/README.md) | always-on | (infra) | Isolated agent setup, framework install + maintenance, shared-config sync. The prerequisite — at minimum the `setup` skill itself runs out of this family. | 10 skills, [`docs/setup/`](docs/setup/) |
+| [**setup**](docs/setup/README.md) | always-on | (infra) | Isolated agent setup, framework install + maintenance, shared-config sync. The prerequisite — at minimum the `setup` skill itself runs out of this family. | 11 skills, [`docs/setup/`](docs/setup/) |
 | **utilities** | always-on | (meta) | Framework meta-skills: author skills (`write-skill`), restructure them (`optimize-skill`), reconcile skill state (`skill-reconciler`), report framework issues (`report-framework-issue`), and print a live index (`list-skills`). | 5 skills |
 | [**security**](docs/security/README.md) | opt-in | Triage, Drafting | 16-step security-issue handling lifecycle — from `security@` import through CVE publication, including state sync — plus producing, verifying, and maintaining the project's own security model. Maintainer-only. | 15 skills, [`docs/security/`](docs/security/) |
 | [**pr-management**](docs/pr-management/README.md) | opt-in | Triage | Maintainer-facing PR-queue management — triage, stats, deep code review, stack review, express-lane merge, stale-sweep, reviewer routing, and pre-first-PR checks. | 9 skills, [`docs/pr-management/`](docs/pr-management/README.md) |

docs/labels-and-capabilities.md

@@ -298,6 +298,7 @@ Capabilities for every skill currently in
 | `setup-isolated-setup-update` | `capability:platform` |
 | `setup-isolated-setup-doctor` | `capability:platform` + `capability:reassess` *(re-checks an installed sandbox against current spec — the phase is reassess on subject setup)* |
 | `setup-override-upstream` | `capability:platform` |
+| `setup-welcome-guide` | `capability:platform` *(shows the framework's own welcome guides and turns a dismissed one back on)* |
 | `setup-upstream-fix` | `capability:platform` |
 | `report-framework-issue` | `capability:platform` *(files a redacted bug / change-proposal issue against the framework repo when a skill or tool misbehaves; the mandatory public-disclosure scrub keeps private tracker / CVE / cross-project content out of the public issue; never files without confirmation)* |
 | `security-model-prepare` | `capability:authoring` *(produces the project's first security model in draft-first mode and lands it, plus its discoverability chain, as one reviewable PR per repository)* |

docs/mode-economics.md

@@ -105,6 +105,13 @@ The rules are 2,057 tokens across eight sections, held once in the tool. A
 run that needs one pays for one — typically 120 to 580 tokens — and the
 ordinary `{"verdict": "ok"}` pays for none.
 
+The first-run welcome guides ride the same verdict:
+a `welcome` finding carrying one guide and the `welcome` rules, roughly 1,300 tokens.
+At most one guide per run, each paid on at most three runs per user (fewer once dismissed) —
+the general guide on any skill, a family's on that family's skills —
+and again only on the first run after an upgrade lifts a dismissal.
+`--no-welcome` leaves it out.
+
 What is left in the block is the part a model is for: run the command,
 stay silent on `ok`, follow the rules a finding carries, and never run
 `/magpie-setup:setup adopt` unattended. What is left in neither is the

docs/modes.md

@@ -63,7 +63,7 @@ Autonomous* (the renamed former *Auto-merge*).
 | **Mentoring** | *(Agentic Mentoring)* Joins issue and PR threads in a teaching register: clarifying questions, pointers to project conventions, paired examples from prior PRs, hand-off to a human when scope exceeds the agent. Also authors net-new good first issues, curates the existing backlog, and explains filed issues to newcomers to lower onboarding latency. | experimental | 7 |
 | **Drafting** | *(Agentic Drafting)* Agent drafts a fix for a well-scoped problem and opens a PR; every PR is reviewed and merged by a human committer. | stable (security-only); experimental (issue-management, audit-findings, release-management family) | 11 |
 | **Pairing** | *(Agentic Pairing)* Developer-side dev-cycle skills with mentorship intrinsic — multi-agent review pipelines, self-review and pre-flight patterns, scoped fix drafting under the developer's driver's seat. | experimental | 3 |
-| **Meta** | *(framework infrastructure & authoring)* Adoption, isolation, upgrade, status, and skill-authoring flows plus read-only stats dashboards' framework plumbing. These skills are framework machinery rather than a maintainership mode; they do not act on issues, PRs, or contributor threads on their own. | stable | 19 |
+| **Meta** | *(framework infrastructure & authoring)* Adoption, isolation, upgrade, status, and skill-authoring flows plus read-only stats dashboards' framework plumbing. These skills are framework machinery rather than a maintainership mode; they do not act on issues, PRs, or contributor threads on their own. | stable | 20 |
 | **Agentic Autonomous** | Auto-merge restricted to objectively boring change classes only (lint, dependency bumps inside an allow-list, license-header insertion, formatting, broken-link repair). | off | 0 |
 
 Framework-infrastructure and authoring skills carry the **Meta**
@@ -308,6 +308,7 @@ contributor threads on their own. The always-on `setup` and
 | [`setup-shared-config-sync`](../skills/setup-shared-config-sync/SKILL.md) | Sync shared configuration across worktrees. |
 | [`setup-isolated-setup-doctor`](../skills/setup-isolated-setup-doctor/SKILL.md) | In-session functional health check of the secure-agent sandbox: probes SSH agent / Yubikey reachability, localhost port access, and filesystem restrictions. |
 | [`setup-status`](../skills/setup-status/SKILL.md) | Render a Markdown adoption dashboard: install method and pin, drift, and which skills are wired in the current repo. |
+| [`setup-welcome-guide`](../skills/setup-welcome-guide/SKILL.md) | Show a Magpie welcome guide on demand — the general one or a family's — and turn a dismissed one back on. |
 | [`committer-onboarding`](../skills/committer-onboarding/SKILL.md) | Post-vote committer and PMC onboarding for Apache projects: walks the nominator through every step from ICLA check to welcome announcement for both podlings and TLPs. |
 | [`security-tracker-stats-dashboard`](../skills/security-tracker-stats-dashboard/SKILL.md) | Generate a self-contained HTML dashboard of `<tracker>` statistics (lifecycle-band breakdowns, time-to-triage trends, velocity) without modifying any tracker state. |
 | [`optimize-skill`](../skills/optimize-skill/SKILL.md) | Optimize an existing framework skill by applying restructuring patterns: split oversized SKILL.md into linked sibling docs, trim frontmatter, improve eval alignment. |

docs/quick-start.md

@@ -36,7 +36,7 @@ project and no opt-in from your teammates. Committing anything for other
 people is a separate act called **adoption** —
 [Installation or Adoption?](quick-start/two-ways.md) draws the line.
 
-**What you get.** 79 skills your agent can run, grouped into 10 **families** —
+**What you get.** 80 skills your agent can run, grouped into 10 **families** —
 PR triage and review, issue triage, security-report handling, release
 management, contributor mentoring. Install only the families you need; each one
 you add costs context in every session —
@@ -178,7 +178,7 @@ draws the line.
 
 **Every skill configures itself on first use.** You do not have to remember
 which projects are set up, or run anything to prepare a family before you use
-it: 69 of the 79 skills open with a silent pre-flight — the ten exceptions are
+it: 69 of the 80 skills open with a silent pre-flight — the eleven exceptions are
 the setup skills themselves, which are what you run to fix whatever it finds.
 
 The first time you call a skill in a project, that pre-flight works out how

docs/quick-start/families.md

@@ -39,7 +39,7 @@ today — you are not meant to take all of them.
 
 | Plugin | Skills | The problem it solves | What it offers |
 |---|---|---|---|
-| `magpie-setup` | 10 | Your agent can read every credential on your machine, and you have no way to tell whether it is sandboxed right now. | A filesystem sandbox, a clean-env wrapper, a status line that shows sandbox state, and a red banner before any bypass. Plus install, upgrade, and drift checks. **You must install this one first** — it is what installs everything else. |
+| `magpie-setup` | 11 | Your agent can read every credential on your machine, and you have no way to tell whether it is sandboxed right now. | A filesystem sandbox, a clean-env wrapper, a status line that shows sandbox state, and a red banner before any bypass. Plus install, upgrade, and drift checks. **You must install this one first** — it is what installs everything else. |
 | `magpie-security` | 15 | Security reports arrive by mail and must be triaged, fixed, and disclosed on a clock — with nothing leaking early. | A 16-step lifecycle: intake from the mailbox, validity triage, canned responses, fix drafting, CVE allocation, advisory and publication. Drafts land in Gmail; nothing is ever sent for you. |
 | `magpie-release-management` | 10 | An ASF release is a long checklist where one missed step invalidates the vote. | RC cut, RC verification (signatures, hashes, LICENSE/NOTICE, no stray binaries), the `[VOTE]` thread, the tally, promotion, `[ANNOUNCE]`, archive sweep, audit log. The agent never holds your signing key and never publishes. |
 | `magpie-pr-management` | 9 | The PR queue grows faster than you can read it, and the oldest ones quietly rot. | Queue triage into ready / needs-review / waiting-on-author, deep code review with blocking vs non-blocking findings, whole-stack review of stacked PRs, reviewer routing, express-lane merge, stale sweep, and queue statistics. |

docs/quick-start/first-run.md

@@ -58,6 +58,13 @@ changes nothing any teammate can see.
 What it will **not** do is proceed on a guess. It did not label anything, post
 anything, or fall back to a default committer team.
 
+Your first Magpie skill also opens with a one-minute
+[welcome guide](../../plugins/magpie-setup/skills/setup/setup_preflight/guides/general.md),
+and a family can bring its own for the next run in that family — the security family does.
+A guide shows before the work starts, never instead of it,
+and ends with a choice to see it again, dismiss it until the next upgrade, or hide it for good.
+`/magpie-setup:welcome-guide [<family>]` shows any of them again.
+
 ## 2. It configures, deriving what it can
 
 ![What config derived from the repository itself, and the single prompt covering the values it could not](../../assets/quickstart/walkthrough/2-config-wizard.svg)

docs/security/README.md

@@ -65,6 +65,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 security skill you run opens with a one-minute
+[welcome guide](../../plugins/magpie-setup/skills/setup/setup_preflight/guides/security.md):
+the typical flow, configuring Magpie, what to ask it, and how to make it yours.
+Dismiss it, or hide it for good, from its last line;
+*"show the security welcome again"* or `/magpie-setup:welcome-guide security` brings it back.
+
 ### Before the first run
 
 <!-- BEGIN generated: skill-config (tools/dev/check-skill-config.py --fix) -->

docs/setup/README.md

@@ -51,7 +51,7 @@ framework safe to use.
 
 ## Install & first runs
 
-Install just this family — one plugin, 10 skills. Sandbox, clean environment, and the framework's own install/upgrade.
+Install just this family — one plugin, 11 skills. Sandbox, clean environment, and the framework's own install/upgrade.
 
 Once you have [added the marketplace](../setup/marketplace-install.md):
 
@@ -156,6 +156,7 @@ for the complete rule.
 | [`setup-status`](../../skills/setup-status/SKILL.md) | Render a Markdown adoption dashboard (install pin, drift, wired agent targets, installed skill families, symlink health) and adjust the wiring in place. |
 | [`setup-shared-config-sync`](../../skills/setup-shared-config-sync/SKILL.md) | Commit + push the user's shared Claude config to its sync repo. |
 | [`setup-override-upstream`](../../skills/setup-override-upstream/SKILL.md) | Promote a local `.apache-magpie-overrides/<skill>.md` file into a PR against `apache/magpie`; prompts to remove the override once merged and upgraded. |
+| [`setup-welcome-guide`](../../skills/setup-welcome-guide/SKILL.md) | Show a Magpie welcome guide on demand — the general one, or a family's such as `security` — and turn a dismissed one back on. |
 | [`setup-upstream-fix`](../../skills/setup-upstream-fix/SKILL.md) | Turn a framework bug or quirk hit mid-session into a fix PR against `apache/magpie`, after checking for an existing issue or PR that already covers it. |
 
 ## Deep documentation

docs/setup/marketplace.md

@@ -53,7 +53,7 @@ Magpie**. The [pinned snapshot install](../quick-start/other-install-methods.md)
 for the cases it does not cover.
 
 > [!IMPORTANT]
-> A marketplace install drops the 79 skills into your agent and is complete
+> A marketplace install drops the 80 skills into your agent and is complete
 > for day-to-day use. What it does **not** set up on its own is the
 > repo-side machinery — the committed pin, the gitignored snapshot, drift
 > detection, agentic overrides — or the secure-agent setup, which you run
@@ -158,7 +158,7 @@ can say so, because it is the floor everything else is managed from.
 | Family plugin | Skills | ~Always-on tokens |
 |---|---|---|
 | `magpie-security` | 15 | ~1.1k |
-| `magpie-setup` | 10 | ~0.7k |
+| `magpie-setup` | 11 | ~0.8k |
 | `magpie-release-management` | 10 | ~0.8k |
 | `magpie-pr-management` | 9 | ~1.0k |
 | `magpie-issue` | 8 | ~0.7k |
@@ -657,6 +657,22 @@ The same suggestion also comes back weekly by default, and the interval can be c
 Run the skill directly at any time to check now.
 Details: [Automatic reminders from the pre-flight](secure-agent-setup.md#automatic-reminders-from-the-pre-flight).
 
+**The first skills you run show a welcome guide.**
+The same pre-flight carries short first-run guides:
+a [general one](../../plugins/magpie-setup/skills/setup/setup_preflight/guides/general.md) on the first Magpie skill you run —
+getting started, staying current, asking in plain language, making Magpie yours —
+and a family's own on the next run of a skill in that family
+(today the [security family's](../../plugins/magpie-setup/skills/setup/setup_preflight/guides/security.md)).
+At most one guide shows per run, and each ends with three choices.
+**Continue** shows it again next time (three times at most),
+**Dismiss** hides it until the next Magpie upgrade,
+and **Don't show again** hides it until you ask for it back —
+say *"show the security welcome again"*.
+Any guide is one command away: `/magpie-setup:welcome-guide [<family>]`
+(`/magpie-setup-welcome-guide` on a pinned snapshot).
+The choice is kept in `reconciled.json` in your personal layer.
+Mechanics: [`welcome-guide`](../../plugins/magpie-setup/skills/welcome-guide/SKILL.md).
+
 ## Versioning
 
 The plugin version tracks the framework version in `pyproject.toml`, which is

docs/vendor-neutrality.md

@@ -603,15 +603,15 @@ generated block below.
 | `contract:people` | ✅ | vendor-backed | Atlassian, GitHub | 2 backend vendors: Atlassian, GitHub |
 | `contract:security-tracker` | ✅ | vendor-backed | Atlassian, agnostic | 2 backend vendors: Atlassian, agnostic |
 
-**Per-skill assessment: 79/79 skills carry no vendor lock-in.** A skill is *capability-pure* when it names no backend at all, *portable* when every backend it names has an alternative (its contract is green), and *vendor-coupled* only when it reaches for a backend that is the sole implementation of a capability.
+**Per-skill assessment: 80/80 skills carry no vendor lock-in.** A skill is *capability-pure* when it names no backend at all, *portable* when every backend it names has an alternative (its contract is green), and *vendor-coupled* only when it reaches for a backend that is the sole implementation of a capability.
 
 | Skill neutrality | Count |
 |---|---|
-| capability-pure (names no backend) | 25 |
+| capability-pure (names no backend) | 26 |
 | portable (named backends are swappable) | 54 |
 | vendor-coupled (sole-backend dependency) | 0 |
 
-Organization scope (declared, orthogonal to vendor): ASF = 16, agnostic = 63.
+Organization scope (declared, orthogonal to vendor): ASF = 16, agnostic = 64.
 
 **LLM / agent-integration neutrality**