You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by gi...@apache.org on 2026/09/16 10:36:32 UTC
(magpie-site) branch publish updated (32bac73 -> 4c6f5ce)
This is an automated email from the ASF dual-hosted git repository.
github-actions[bot] pushed a change to branch publish
in repository https://gitbox.apache.org/repos/asf/magpie-site.git
discard 32bac73 Publish site (3cbf9a9)
new 4c6f5ce Publish site (bea09c3)
This update added new revisions after undoing existing revisions.
That is to say, some revisions that were in the old version of the
branch are not in the new version. This situation occurs
when a user --force pushes a change and generates a repository
containing something like this:
* -- * -- B -- O -- O -- O (32bac73)
\
N -- N -- N refs/heads/publish (4c6f5ce)
You should already have received notification emails for all of the O
revisions, and so the following emails describe only the N revisions
from the common base, B.
Any revisions marked "omit" are not gone; other references still
refer to them. Any revisions marked "discard" are gone forever.
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
(magpie-site) 01/01: Publish site (bea09c3)
Posted by gi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
github-actions[bot] pushed a commit to branch publish
in repository https://gitbox.apache.org/repos/asf/magpie-site.git
commit 4c6f5ce0e2c752b5862f5a3f71c2ec7f991aa781
Author: github-actions[bot] <gi...@users.noreply.github.com>
AuthorDate: Wed Sep 16 10:36:24 2026 +0000
Publish site (bea09c3)
---
.asf.yaml | 32 +
.htaccess | 39 +
404.html | 1 +
_astro/ImmersiveGradientHero.d5d-wTHX.js | 10 +
_astro/SiteFooter.C2Dgj2WR.css | 2 +
_astro/client.bxcwkfp-.js | 9 +
.../geist-cyrillic-ext-wght-normal.DjL33-gN.woff2 | Bin 0 -> 7420 bytes
_astro/geist-cyrillic-wght-normal.BEAKL7Jp.woff2 | Bin 0 -> 15084 bytes
_astro/geist-latin-ext-wght-normal.DC-KSUi6.woff2 | Bin 0 -> 16512 bytes
_astro/geist-latin-wght-normal.BgDaEnEv.woff2 | Bin 0 -> 29400 bytes
_astro/geist-vietnamese-wght-normal.6IgcOCM7.woff2 | Bin 0 -> 8004 bytes
_astro/inter-cyrillic-400-normal.HOLc17fK.woff | Bin 0 -> 9780 bytes
_astro/inter-cyrillic-400-normal.obahsSVq.woff2 | Bin 0 -> 7712 bytes
_astro/inter-cyrillic-500-normal.BasfLYem.woff2 | Bin 0 -> 7900 bytes
_astro/inter-cyrillic-500-normal.CxZf_p3X.woff | Bin 0 -> 9940 bytes
_astro/inter-cyrillic-600-normal.4D_pXhcN.woff | Bin 0 -> 9936 bytes
_astro/inter-cyrillic-600-normal.CWCymEST.woff2 | Bin 0 -> 7972 bytes
_astro/inter-cyrillic-700-normal.CjBOestx.woff2 | Bin 0 -> 7904 bytes
_astro/inter-cyrillic-700-normal.DrXBdSj3.woff | Bin 0 -> 9912 bytes
.../inter-cyrillic-ext-400-normal.BQZuk6qB.woff2 | Bin 0 -> 10232 bytes
_astro/inter-cyrillic-ext-400-normal.DQukG94-.woff | Bin 0 -> 13336 bytes
.../inter-cyrillic-ext-500-normal.B0yAr1jD.woff2 | Bin 0 -> 10432 bytes
_astro/inter-cyrillic-ext-500-normal.BmqWE9Dz.woff | Bin 0 -> 13452 bytes
_astro/inter-cyrillic-ext-600-normal.Bcila6Z-.woff | Bin 0 -> 13464 bytes
.../inter-cyrillic-ext-600-normal.Dfes3d0z.woff2 | Bin 0 -> 10484 bytes
.../inter-cyrillic-ext-700-normal.BjwYoWNd.woff2 | Bin 0 -> 10496 bytes
_astro/inter-cyrillic-ext-700-normal.LO58E6JB.woff | Bin 0 -> 13408 bytes
_astro/inter-greek-400-normal.B4URO6DV.woff2 | Bin 0 -> 7776 bytes
_astro/inter-greek-400-normal.q2sYcFCs.woff | Bin 0 -> 9924 bytes
_astro/inter-greek-500-normal.BIZE56-Y.woff2 | Bin 0 -> 7920 bytes
_astro/inter-greek-500-normal.Xzm54t5V.woff | Bin 0 -> 9980 bytes
_astro/inter-greek-600-normal.BZpKdvQh.woff | Bin 0 -> 10032 bytes
_astro/inter-greek-600-normal.plRanbMR.woff2 | Bin 0 -> 7944 bytes
_astro/inter-greek-700-normal.BUv2fZ6O.woff | Bin 0 -> 9980 bytes
_astro/inter-greek-700-normal.C3JjAnD8.woff2 | Bin 0 -> 7920 bytes
_astro/inter-greek-ext-400-normal.DGGRlc-M.woff2 | Bin 0 -> 5264 bytes
_astro/inter-greek-ext-400-normal.KugGGMne.woff | Bin 0 -> 7064 bytes
_astro/inter-greek-ext-500-normal.2j5mBUwD.woff | Bin 0 -> 7192 bytes
_astro/inter-greek-ext-500-normal.C4iEst2y.woff2 | Bin 0 -> 5428 bytes
_astro/inter-greek-ext-600-normal.B8X0CLgF.woff | Bin 0 -> 7212 bytes
_astro/inter-greek-ext-600-normal.DRtmH8MT.woff2 | Bin 0 -> 5432 bytes
_astro/inter-greek-ext-700-normal.BoQ6DsYi.woff | Bin 0 -> 7216 bytes
_astro/inter-greek-ext-700-normal.qfdV9bQt.woff2 | Bin 0 -> 5444 bytes
_astro/inter-latin-400-normal.C38fXH4l.woff2 | Bin 0 -> 23664 bytes
_astro/inter-latin-400-normal.CyCys3Eg.woff | Bin 0 -> 30696 bytes
_astro/inter-latin-500-normal.BL9OpVg8.woff | Bin 0 -> 31284 bytes
_astro/inter-latin-500-normal.Cerq10X2.woff2 | Bin 0 -> 24272 bytes
_astro/inter-latin-600-normal.CiBQ2DWP.woff | Bin 0 -> 31260 bytes
_astro/inter-latin-600-normal.LgqL8muc.woff2 | Bin 0 -> 24452 bytes
_astro/inter-latin-700-normal.BLAVimhd.woff | Bin 0 -> 31320 bytes
_astro/inter-latin-700-normal.Yt3aPRUw.woff2 | Bin 0 -> 24356 bytes
_astro/inter-latin-ext-400-normal.77YHD8bZ.woff | Bin 0 -> 47560 bytes
_astro/inter-latin-ext-400-normal.C1nco2VV.woff2 | Bin 0 -> 35000 bytes
_astro/inter-latin-ext-500-normal.BxGbmqWO.woff | Bin 0 -> 48492 bytes
_astro/inter-latin-ext-500-normal.CV4jyFjo.woff2 | Bin 0 -> 36024 bytes
_astro/inter-latin-ext-600-normal.CIVaiw4L.woff | Bin 0 -> 48668 bytes
_astro/inter-latin-ext-600-normal.D2bJ5OIk.woff2 | Bin 0 -> 36260 bytes
_astro/inter-latin-ext-700-normal.Ca8adRJv.woff2 | Bin 0 -> 36244 bytes
_astro/inter-latin-ext-700-normal.TidjK2hL.woff | Bin 0 -> 48632 bytes
_astro/inter-vietnamese-400-normal.Bbgyi5SW.woff | Bin 0 -> 6500 bytes
_astro/inter-vietnamese-400-normal.DMkecbls.woff2 | Bin 0 -> 4972 bytes
_astro/inter-vietnamese-500-normal.DOriooB6.woff2 | Bin 0 -> 5112 bytes
_astro/inter-vietnamese-500-normal.mJboJaSs.woff | Bin 0 -> 6596 bytes
_astro/inter-vietnamese-600-normal.BuLX-rYi.woff | Bin 0 -> 6640 bytes
_astro/inter-vietnamese-600-normal.Cc8MFFhd.woff2 | Bin 0 -> 5100 bytes
_astro/inter-vietnamese-700-normal.BZaoP0fm.woff | Bin 0 -> 6632 bytes
_astro/inter-vietnamese-700-normal.DlLaEgI2.woff2 | Bin 0 -> 5104 bytes
_astro/jost-cyrillic-400-normal.Dk3McGkH.woff | Bin 0 -> 5588 bytes
_astro/jost-cyrillic-400-normal.bVZEi0jL.woff2 | Bin 0 -> 4108 bytes
_astro/jost-cyrillic-500-normal.DlHwnXyv.woff | Bin 0 -> 5872 bytes
_astro/jost-cyrillic-500-normal.DtB2bvF0.woff2 | Bin 0 -> 4412 bytes
_astro/jost-cyrillic-600-normal.BEDXyecp.woff2 | Bin 0 -> 4436 bytes
_astro/jost-cyrillic-600-normal.D0Fzn8un.woff | Bin 0 -> 5868 bytes
_astro/jost-cyrillic-700-normal.BHDNzvjF.woff | Bin 0 -> 5900 bytes
_astro/jost-cyrillic-700-normal._ob5o-r5.woff2 | Bin 0 -> 4384 bytes
_astro/jost-latin-400-normal.C7S-3Ky6.woff | Bin 0 -> 13224 bytes
_astro/jost-latin-400-normal.q-RKOgPK.woff2 | Bin 0 -> 9404 bytes
_astro/jost-latin-500-normal.41lBe9I9.woff2 | Bin 0 -> 10476 bytes
_astro/jost-latin-500-normal.B-AtzreL.woff | Bin 0 -> 14220 bytes
_astro/jost-latin-600-normal.Bv_M0d15.woff | Bin 0 -> 14232 bytes
_astro/jost-latin-600-normal.C497H-z9.woff2 | Bin 0 -> 10480 bytes
_astro/jost-latin-700-normal.k-iBXzmq.woff | Bin 0 -> 14288 bytes
_astro/jost-latin-700-normal.u2Hrqd6k.woff2 | Bin 0 -> 10520 bytes
_astro/jost-latin-ext-400-normal.CpdMQIMr.woff2 | Bin 0 -> 6396 bytes
_astro/jost-latin-ext-400-normal.Dsyb2mtt.woff | Bin 0 -> 9108 bytes
_astro/jost-latin-ext-500-normal.BkvHgcKf.woff2 | Bin 0 -> 6912 bytes
_astro/jost-latin-ext-500-normal.Cpxiadwk.woff | Bin 0 -> 9524 bytes
_astro/jost-latin-ext-600-normal.D8I9kjga.woff2 | Bin 0 -> 6832 bytes
_astro/jost-latin-ext-600-normal.Pm6OqGZB.woff | Bin 0 -> 9604 bytes
_astro/jost-latin-ext-700-normal.AnR_ULdm.woff2 | Bin 0 -> 6884 bytes
_astro/jost-latin-ext-700-normal.DTcCupJy.woff | Bin 0 -> 9572 bytes
_astro/react.CYuo-Lgd.js | 1 +
architecture/index.html | 75 +
brand/avatar-1000.png | Bin 0 -> 34340 bytes
brand/avatar-400.png | Bin 0 -> 17393 bytes
brand/banner-1500x500.png | Bin 0 -> 106721 bytes
brand/banner-bluesky-3000x1000.png | Bin 0 -> 194147 bytes
brand/banner-linkedin-1128x191.png | Bin 0 -> 57326 bytes
brand/index.html | 19 +
community-avatars/CalvinKirs.png | Bin 0 -> 5672 bytes
community-avatars/RussellSpitzer.png | Bin 0 -> 3445 bytes
community-avatars/amoghrajesh.png | Bin 0 -> 8587 bytes
community-avatars/andreahlert.png | Bin 0 -> 36790 bytes
community-avatars/andrewmusselman.png | Bin 0 -> 928 bytes
community-avatars/choo121600.png | Bin 0 -> 5341 bytes
community-avatars/clr-apache.png | Bin 0 -> 4281 bytes
community-avatars/csutherl.png | Bin 0 -> 3790 bytes
community-avatars/eladkal.png | Bin 0 -> 3446 bytes
community-avatars/gopidesupavan.png | Bin 0 -> 7693 bytes
community-avatars/iemejia.png | Bin 0 -> 55669 bytes
community-avatars/jamesfredley.png | Bin 0 -> 4439 bytes
community-avatars/jbonofre.png | Bin 0 -> 1581 bytes
community-avatars/justinmclean.png | Bin 0 -> 4523 bytes
community-avatars/madrob.png | Bin 0 -> 1537 bytes
community-avatars/onlyarnav.png | Bin 0 -> 4233 bytes
community-avatars/paulk-asert.png | Bin 0 -> 53934 bytes
community-avatars/potiuk.png | Bin 0 -> 45314 bytes
community-avatars/ppkarwasz.png | Bin 0 -> 4255 bytes
community-avatars/rbowen.png | Bin 0 -> 5812 bytes
community-avatars/rmaucher.png | Bin 0 -> 7063 bytes
community-avatars/rusackas.png | Bin 0 -> 7158 bytes
community-avatars/rzo1.png | Bin 0 -> 38907 bytes
community-avatars/tisonkun.png | Bin 0 -> 4485 bytes
community-avatars/zeroshade.png | Bin 0 -> 5030 bytes
docs-assets/badge.json | 8 +
docs-assets/bump-dev-version-run.png | Bin 0 -> 228243 bytes
docs-assets/installed-plugins.png | Bin 0 -> 601625 bytes
docs-assets/quickstart/README.md | 167 +
docs-assets/quickstart/demo.svg | 60 +
.../families/contributor-growth/activity-sweep.svg | 48 +
.../families/contributor-growth/activity-sweep.txt | 33 +
.../contributor-growth/committer-onboarding.svg | 49 +
.../contributor-growth/committer-onboarding.txt | 34 +
.../families/contributor-growth/nomination.svg | 48 +
.../families/contributor-growth/nomination.txt | 34 +
.../quickstart/families/issue/deduplicate.svg | 49 +
.../quickstart/families/issue/deduplicate.txt | 35 +
.../quickstart/families/issue/reproducer.svg | 47 +
.../quickstart/families/issue/reproducer.txt | 33 +
docs-assets/quickstart/families/issue/triage.svg | 49 +
docs-assets/quickstart/families/issue/triage.txt | 33 +
.../families/mentoring/good-first-issue-sweep.svg | 49 +
.../families/mentoring/good-first-issue-sweep.txt | 34 +
.../mentoring/newcomer-issue-explainer.svg | 47 +
.../mentoring/newcomer-issue-explainer.txt | 32 +
.../quickstart/families/mentoring/welcome.svg | 48 +
.../quickstart/families/mentoring/welcome.txt | 33 +
.../families/pairing/multi-agent-review.svg | 50 +
.../families/pairing/multi-agent-review.txt | 37 +
.../quickstart/families/pairing/self-review.svg | 47 +
.../quickstart/families/pairing/self-review.txt | 32 +
.../quickstart/families/pr-management/stats.svg | 50 +
.../quickstart/families/pr-management/stats.txt | 37 +
.../quickstart/families/pr-management/triage.svg | 50 +
.../quickstart/families/pr-management/triage.txt | 34 +
.../families/release-management/prepare.svg | 48 +
.../families/release-management/prepare.txt | 33 +
.../families/release-management/verify-rc.svg | 49 +
.../families/release-management/verify-rc.txt | 34 +
.../families/release-management/vote-tally.svg | 49 +
.../families/release-management/vote-tally.txt | 35 +
.../families/repo-health/dependency-audit.svg | 49 +
.../families/repo-health/dependency-audit.txt | 35 +
.../families/repo-health/flaky-test-triage.svg | 49 +
.../families/repo-health/flaky-test-triage.txt | 35 +
.../repo-health/workflow-security-audit.svg | 48 +
.../repo-health/workflow-security-audit.txt | 33 +
.../quickstart/families/security/issue-import.svg | 47 +
.../quickstart/families/security/issue-import.txt | 33 +
.../quickstart/families/security/issue-triage.svg | 49 +
.../quickstart/families/security/issue-triage.txt | 34 +
.../quickstart/families/security/model-verify.svg | 47 +
.../quickstart/families/security/model-verify.txt | 32 +
.../families/setup/isolated-setup-install.svg | 48 +
.../families/setup/isolated-setup-install.txt | 33 +
.../families/setup/isolated-setup-verify.svg | 49 +
.../families/setup/isolated-setup-verify.txt | 34 +
docs-assets/quickstart/families/setup/status.svg | 48 +
docs-assets/quickstart/families/setup/status.txt | 32 +
.../quickstart/families/utilities/list-skills.svg | 49 +
.../quickstart/families/utilities/list-skills.txt | 35 +
.../families/utilities/report-framework-issue.svg | 47 +
.../families/utilities/report-framework-issue.txt | 32 +
.../quickstart/families/utilities/write-skill.svg | 48 +
.../quickstart/families/utilities/write-skill.txt | 34 +
docs-assets/quickstart/install.svg | 53 +
docs-assets/quickstart/magpie-setup.svg | 69 +
docs-assets/quickstart/step-adopt.svg | 50 +
docs-assets/quickstart/step-guard.svg | 54 +
docs-assets/quickstart/step-install.svg | 55 +
docs-assets/quickstart/step-isolation.svg | 51 +
docs-assets/quickstart/step-privacy.svg | 54 +
docs-assets/quickstart/step-use.svg | 51 +
.../quickstart/walkthrough/1-preflight-stops.svg | 47 +
.../quickstart/walkthrough/1-preflight-stops.txt | 32 +
.../quickstart/walkthrough/2-config-wizard.svg | 47 +
.../quickstart/walkthrough/2-config-wizard.txt | 32 +
.../quickstart/walkthrough/3-scaffolded.svg | 50 +
.../quickstart/walkthrough/3-scaffolded.txt | 37 +
docs-assets/quickstart/walkthrough/4-it-runs.svg | 47 +
docs-assets/quickstart/walkthrough/4-it-runs.txt | 32 +
.../quickstart/walkthrough/5-adopt-promotes.svg | 54 +
.../quickstart/walkthrough/5-adopt-promotes.txt | 40 +
.../quickstart/wizard/contributor-growth.svg | 60 +
docs-assets/quickstart/wizard/issue.svg | 60 +
docs-assets/quickstart/wizard/mentoring.svg | 54 +
docs-assets/quickstart/wizard/pr-management.svg | 60 +
.../quickstart/wizard/release-management.svg | 56 +
docs-assets/quickstart/wizard/repo-health.svg | 54 +
docs-assets/quickstart/wizard/security.svg | 66 +
docs-assets/sandbox-blocks-read.png | Bin 0 -> 350556 bytes
docs-assets/sandbox-bypass-banner.png | Bin 0 -> 484008 bytes
docs-assets/sandbox-modes.png | Bin 0 -> 512135 bytes
docs-assets/sandbox-os-level-block.png | Bin 0 -> 528082 bytes
docs-assets/session-no-sandbox.png | Bin 0 -> 462482 bytes
docs-assets/session-sandboxed.png | Bin 0 -> 359031 bytes
docs/adapters/add-a-harness.md | 282 +
docs/adapters/add-a-harness/index.html | 290 +
docs/adapters/authoring.md | 82 +
docs/adapters/authoring/index.html | 156 +
docs/adapters/codex.md | 223 +
docs/adapters/codex/index.html | 246 +
docs/adapters/cursor.md | 125 +
docs/adapters/cursor/index.html | 169 +
docs/adapters/gemini.md | 361 +
docs/adapters/gemini/index.html | 479 +
docs/adapters/kiro.md | 103 +
docs/adapters/kiro/index.html | 135 +
docs/adapters/local-llm.md | 247 +
docs/adapters/local-llm/index.html | 248 +
docs/adapters/opencode.md | 104 +
docs/adapters/opencode/index.html | 138 +
docs/adapters/readme.md | 70 +
docs/adapters/readme/index.html | 146 +
docs/adapters/registry.md | 85 +
docs/adapters/registry/index.html | 193 +
docs/confidentiality.md | 54 +
docs/confidentiality/index.html | 96 +
docs/contributor-growth/readme.md | 214 +
docs/contributor-growth/readme/index.html | 354 +
docs/contributor-sentiment.md | 267 +
docs/contributor-sentiment/index.html | 305 +
docs/designs/2026-09-13-install-adopt-upgrade.md | 624 +
.../2026-09-13-install-adopt-upgrade/index.html | 646 +
docs/designs/readme.md | 31 +
docs/designs/readme/index.html | 82 +
docs/editorial-guidelines.md | 485 +
docs/editorial-guidelines/index.html | 463 +
docs/education/agentic-work.md | 175 +
docs/education/agentic-work/index.html | 197 +
docs/education/choosing-models.md | 151 +
docs/education/choosing-models/index.html | 177 +
docs/education/contributing.md | 161 +
docs/education/contributing/index.html | 192 +
docs/education/debugging-skills.md | 272 +
docs/education/debugging-skills/index.html | 292 +
docs/education/english-as-code.md | 164 +
docs/education/english-as-code/index.html | 212 +
docs/education/eval-driven-development.md | 460 +
docs/education/eval-driven-development/index.html | 417 +
docs/education/pattern-catalogue.md | 485 +
docs/education/pattern-catalogue/index.html | 416 +
docs/education/portable-skills.md | 289 +
docs/education/portable-skills/index.html | 311 +
docs/education/readme.md | 159 +
docs/education/readme/index.html | 251 +
docs/education/training/instructor-guide.md | 653 +
.../education/training/instructor-guide/index.html | 769 +
.../training/lesson-01-what-agents-are.md | 217 +
.../training/lesson-01-what-agents-are/index.html | 202 +
.../training/lesson-02-working-with-agents.md | 244 +
.../lesson-02-working-with-agents/index.html | 234 +
.../training/lesson-03-choosing-models.md | 240 +
.../training/lesson-03-choosing-models/index.html | 234 +
.../training/lesson-04-your-first-skill.md | 270 +
.../training/lesson-04-your-first-skill/index.html | 257 +
.../training/lesson-05-writing-safe-skills.md | 368 +
.../lesson-05-writing-safe-skills/index.html | 363 +
.../training/lesson-06-debugging-a-skill.md | 352 +
.../lesson-06-debugging-a-skill/index.html | 327 +
.../training/lesson-07-writing-portable-skills.md | 337 +
.../lesson-07-writing-portable-skills/index.html | 313 +
.../training/lesson-08-eval-driven-development.md | 550 +
.../lesson-08-eval-driven-development/index.html | 512 +
.../lesson-09-agentic-and-autonomous-work.md | 486 +
.../index.html | 550 +
.../lesson-10-english-as-a-programming-language.md | 402 +
.../index.html | 562 +
.../training/lesson-11-how-to-contribute.md | 422 +
.../lesson-11-how-to-contribute/index.html | 634 +
docs/education/training/lesson-lab-tutorials.md | 396 +
.../training/lesson-lab-tutorials/index.html | 381 +
docs/education/training/readme.md | 107 +
docs/education/training/readme/index.html | 187 +
docs/education/training/upstream-contribution.md | 247 +
.../training/upstream-contribution/index.html | 327 +
docs/education/tutorials.md | 287 +
docs/education/tutorials/index.html | 259 +
docs/education/what-agents-are.md | 180 +
docs/education/what-agents-are/index.html | 217 +
docs/education/working-with-agents.md | 177 +
docs/education/working-with-agents/index.html | 204 +
docs/education/writing-safe-skills.md | 323 +
docs/education/writing-safe-skills/index.html | 316 +
docs/education/your-first-skill.md | 390 +
docs/education/your-first-skill/index.html | 377 +
docs/extending.md | 122 +
docs/extending/index.html | 216 +
docs/index.html | 50 +
docs/index.md | 137 +
docs/index/index.html | 280 +
docs/issue-management/readme.md | 205 +
docs/issue-management/readme/index.html | 305 +
docs/labels-and-capabilities.md | 447 +
docs/labels-and-capabilities/index.html | 1111 +
docs/mentoring/readme.md | 205 +
docs/mentoring/readme/index.html | 275 +
docs/mentoring/spec.md | 211 +
docs/mentoring/spec/index.html | 289 +
docs/mode-economics.md | 459 +
docs/mode-economics/index.html | 1140 +
docs/modes.md | 350 +
docs/modes/index.html | 762 +
docs/pairing/readme.md | 196 +
docs/pairing/readme/index.html | 214 +
docs/pilot-report-template.md | 99 +
docs/pilot-report-template/index.html | 116 +
docs/pr-management/readme.md | 202 +
docs/pr-management/readme/index.html | 297 +
docs/principles.md | 126 +
docs/principles/index.html | 127 +
docs/quick-start.md | 371 +
docs/quick-start/families.md | 46 +
docs/quick-start/families/index.html | 160 +
docs/quick-start/first-run.md | 216 +
docs/quick-start/first-run/index.html | 258 +
docs/quick-start/index.html | 372 +
docs/quick-start/other-install-methods.md | 328 +
docs/quick-start/other-install-methods/index.html | 373 +
docs/quick-start/prerequisites.md | 278 +
docs/quick-start/prerequisites/index.html | 292 +
docs/quick-start/readme.md | 24 +
docs/quick-start/readme/index.html | 89 +
docs/quick-start/two-ways.md | 42 +
docs/quick-start/two-ways/index.html | 110 +
docs/release-management/atr-release-runbook.md | 483 +
.../atr-release-runbook/index.html | 560 +
docs/release-management/manual-release-process.md | 386 +
.../manual-release-process/index.html | 366 +
docs/release-management/process.md | 523 +
docs/release-management/process/index.html | 573 +
docs/release-management/readme.md | 301 +
docs/release-management/readme/index.html | 455 +
docs/release-management/spec.md | 843 +
docs/release-management/spec/index.html | 979 +
docs/release-management/svn-release-runbook.md | 289 +
.../svn-release-runbook/index.html | 320 +
docs/repo-health/readme.md | 378 +
docs/repo-health/readme/index.html | 353 +
docs/rfcs/readme.md | 32 +
docs/rfcs/readme/index.html | 109 +
docs/rfcs/rfc-ai-0002.md | 556 +
docs/rfcs/rfc-ai-0002/index.html | 621 +
docs/rfcs/rfc-ai-0003.md | 442 +
docs/rfcs/rfc-ai-0003/index.html | 662 +
docs/rfcs/rfc-ai-0004.md | 375 +
docs/rfcs/rfc-ai-0004/index.html | 441 +
docs/rfcs/rfc-ai-0005.md | 220 +
docs/rfcs/rfc-ai-0005/index.html | 339 +
docs/rfcs/rfc-ai-0006.md | 241 +
docs/rfcs/rfc-ai-0006/index.html | 284 +
docs/rfcs/rfc-ai-0007.md | 177 +
docs/rfcs/rfc-ai-0007/index.html | 199 +
docs/rfcs/rfc-ai-0008.md | 731 +
docs/rfcs/rfc-ai-0008/index.html | 773 +
docs/security/fixing-security-issues.md | 135 +
docs/security/fixing-security-issues/index.html | 183 +
docs/security/forwarder-routing-policy.md | 258 +
docs/security/forwarder-routing-policy/index.html | 318 +
docs/security/how-the-security-team-works.md | 258 +
.../how-the-security-team-works/index.html | 280 +
docs/security/poc-handling-policy.md | 93 +
docs/security/poc-handling-policy/index.html | 133 +
docs/security/process.md | 554 +
docs/security/process/index.html | 614 +
docs/security/readme.md | 253 +
docs/security/readme/index.html | 379 +
docs/security/roles.md | 444 +
docs/security/roles/index.html | 435 +
docs/security/security-model-preparation.md | 238 +
.../security/security-model-preparation/index.html | 293 +
docs/security/threat-model.md | 695 +
docs/security/threat-model/index.html | 1211 +
docs/setup/agentic-overrides.md | 367 +
docs/setup/agentic-overrides/index.html | 364 +
docs/setup/companion-skills.md | 143 +
docs/setup/companion-skills/index.html | 116 +
docs/setup/individual-use.md | 357 +
docs/setup/individual-use/index.html | 343 +
docs/setup/marketplace-install.md | 159 +
docs/setup/marketplace-install/index.html | 171 +
docs/setup/marketplace.md | 665 +
docs/setup/marketplace/index.html | 865 +
docs/setup/per-role-mcp-access.md | 276 +
docs/setup/per-role-mcp-access/index.html | 269 +
docs/setup/privacy-llm.md | 400 +
docs/setup/privacy-llm/index.html | 388 +
docs/setup/readme.md | 214 +
docs/setup/readme/index.html | 285 +
docs/setup/sandbox-troubleshooting.md | 465 +
docs/setup/sandbox-troubleshooting/index.html | 433 +
docs/setup/secure-agent-internals.md | 302 +
docs/setup/secure-agent-internals/index.html | 369 +
docs/setup/secure-agent-setup.md | 2609 ++
docs/setup/secure-agent-setup/index.html | 2460 ++
docs/setup/team-adoption.md | 204 +
docs/setup/team-adoption/index.html | 228 +
docs/setup/uninstall.md | 242 +
docs/setup/uninstall/index.html | 239 +
docs/skill-sources/authoring-a-source.md | 187 +
docs/skill-sources/authoring-a-source/index.html | 212 +
docs/skill-sources/readme.md | 187 +
docs/skill-sources/readme/index.html | 230 +
docs/skill-sources/registry.md | 65 +
docs/skill-sources/registry/index.html | 135 +
docs/source-release-contents.md | 61 +
docs/source-release-contents/index.html | 131 +
docs/spec-driven-development.md | 248 +
docs/spec-driven-development/index.html | 308 +
docs/tools/agent-guard/readme.md | 383 +
docs/tools/agent-guard/readme/index.html | 389 +
docs/tools/agent-isolation/readme.md | 143 +
docs/tools/agent-isolation/readme/index.html | 211 +
docs/tools/apache-projects/readme.md | 44 +
docs/tools/apache-projects/readme/index.html | 81 +
docs/tools/asf-svn/readme.md | 96 +
docs/tools/asf-svn/readme/index.html | 157 +
docs/tools/bitbucket/readme.md | 296 +
docs/tools/bitbucket/readme/index.html | 453 +
docs/tools/change-request/readme.md | 362 +
docs/tools/change-request/readme/index.html | 522 +
docs/tools/cve-org/readme.md | 32 +
docs/tools/cve-org/readme/index.html | 71 +
docs/tools/cve-tool-vulnogram/readme.md | 40 +
docs/tools/cve-tool-vulnogram/readme/index.html | 76 +
docs/tools/cve-tool/readme.md | 406 +
docs/tools/cve-tool/readme/index.html | 493 +
docs/tools/dashboard-generator/readme.md | 104 +
docs/tools/dashboard-generator/readme/index.html | 149 +
docs/tools/dev/readme.md | 68 +
docs/tools/dev/readme/index.html | 158 +
docs/tools/egress-gateway/readme.md | 107 +
docs/tools/egress-gateway/readme/index.html | 120 +
docs/tools/forwarder-relay/readme.md | 436 +
docs/tools/forwarder-relay/readme/index.html | 504 +
docs/tools/fossil/readme.md | 48 +
docs/tools/fossil/readme/index.html | 84 +
docs/tools/github-body-field/readme.md | 114 +
docs/tools/github-body-field/readme/index.html | 152 +
docs/tools/github-rollup/readme.md | 96 +
docs/tools/github-rollup/readme/index.html | 139 +
docs/tools/github/readme.md | 37 +
docs/tools/github/readme/index.html | 74 +
docs/tools/gmail/readme.md | 41 +
docs/tools/gmail/readme/index.html | 79 +
docs/tools/jira-patch/readme.md | 133 +
docs/tools/jira-patch/readme/index.html | 187 +
docs/tools/jira/readme.md | 299 +
docs/tools/jira/readme/index.html | 251 +
docs/tools/mail-archive/readme.md | 383 +
docs/tools/mail-archive/readme/index.html | 547 +
docs/tools/mail-patch/readme.md | 140 +
docs/tools/mail-patch/readme/index.html | 193 +
docs/tools/mail-source/readme.md | 42 +
docs/tools/mail-source/readme/index.html | 79 +
docs/tools/maildir/readme.md | 150 +
docs/tools/maildir/readme/index.html | 200 +
docs/tools/permission-audit/readme.md | 264 +
docs/tools/permission-audit/readme/index.html | 271 +
docs/tools/pilot-report-validator/readme.md | 73 +
.../tools/pilot-report-validator/readme/index.html | 106 +
docs/tools/ponymail/readme.md | 45 +
docs/tools/ponymail/readme/index.html | 80 +
docs/tools/pr-management-stats/readme.md | 178 +
docs/tools/pr-management-stats/readme/index.html | 198 +
docs/tools/preflight-audit/readme.md | 137 +
docs/tools/preflight-audit/readme/index.html | 147 +
docs/tools/privacy-llm/readme.md | 21 +
docs/tools/privacy-llm/readme/index.html | 63 +
docs/tools/probe-templates/readme.md | 107 +
docs/tools/probe-templates/readme/index.html | 136 +
docs/tools/sandbox-lint/readme.md | 232 +
docs/tools/sandbox-lint/readme/index.html | 246 +
docs/tools/scan-format/readme.md | 121 +
docs/tools/scan-format/readme/index.html | 195 +
.../security-tracker-stats-dashboard/readme.md | 300 +
.../readme/index.html | 405 +
docs/tools/skill-and-tool-validator/readme.md | 92 +
.../skill-and-tool-validator/readme/index.html | 125 +
docs/tools/skill-evals/readme.md | 445 +
docs/tools/skill-evals/readme/index.html | 430 +
docs/tools/skill-reconciler-diff/readme.md | 144 +
docs/tools/skill-reconciler-diff/readme/index.html | 190 +
docs/tools/skill-token-count/readme.md | 169 +
docs/tools/skill-token-count/readme/index.html | 177 +
docs/tools/sourcehut/readme.md | 50 +
docs/tools/sourcehut/readme/index.html | 97 +
docs/tools/spec-inventory/readme.md | 72 +
docs/tools/spec-inventory/readme/index.html | 97 +
docs/tools/spec-loop/readme.md | 167 +
docs/tools/spec-loop/readme/index.html | 214 +
docs/tools/spec-status-index/readme.md | 63 +
docs/tools/spec-status-index/readme/index.html | 113 +
docs/tools/spec-validator/readme.md | 55 +
docs/tools/spec-validator/readme/index.html | 91 +
docs/tools/symlink-lint/readme.md | 112 +
docs/tools/symlink-lint/readme/index.html | 143 +
docs/tools/vcs/readme.md | 124 +
docs/tools/vcs/readme/index.html | 222 +
docs/tools/vendor-neutrality-score/readme.md | 101 +
.../vendor-neutrality-score/readme/index.html | 147 +
docs/tools/vetted-ops/readme.md | 298 +
docs/tools/vetted-ops/readme/index.html | 308 +
docs/updating-magpie.md | 47 +
docs/updating-magpie/index.html | 88 +
docs/utilities/readme.md | 158 +
docs/utilities/readme/index.html | 190 +
docs/vendor-neutrality.md | 667 +
docs/vendor-neutrality/index.html | 998 +
downloads/index.html | 27 +
favicon.ico | Bin 0 -> 15086 bytes
favicon.svg | 1 +
index.html | 155 +
llms-full.txt | 41154 +++++++++++++++++++
llms.txt | 194 +
magpie-mark.png | Bin 0 -> 40625 bytes
magpie-mascot.png | Bin 0 -> 303273 bytes
mark.svg | 1 +
og-image.png | Bin 0 -> 102843 bytes
robots.txt | 4 +
sitemap-0.xml | 1 +
sitemap-index.xml | 1 +
skills/adapters/add-a-harness/index.html | 1 +
skills/adapters/authoring/index.html | 1 +
skills/adapters/codex/index.html | 1 +
skills/adapters/cursor/index.html | 1 +
skills/adapters/gemini/index.html | 1 +
skills/adapters/kiro/index.html | 1 +
skills/adapters/local-llm/index.html | 1 +
skills/adapters/opencode/index.html | 1 +
skills/adapters/readme/index.html | 1 +
skills/adapters/registry/index.html | 1 +
skills/confidentiality/index.html | 1 +
skills/contributor-growth/readme/index.html | 1 +
skills/contributor-sentiment/index.html | 1 +
.../2026-09-13-install-adopt-upgrade/index.html | 1 +
skills/designs/readme/index.html | 1 +
skills/editorial-guidelines/index.html | 1 +
skills/education/agentic-work/index.html | 1 +
skills/education/choosing-models/index.html | 1 +
skills/education/contributing/index.html | 1 +
skills/education/debugging-skills/index.html | 1 +
skills/education/english-as-code/index.html | 1 +
.../education/eval-driven-development/index.html | 1 +
skills/education/pattern-catalogue/index.html | 1 +
skills/education/portable-skills/index.html | 1 +
skills/education/readme/index.html | 1 +
.../education/training/instructor-guide/index.html | 1 +
.../training/lesson-01-what-agents-are/index.html | 1 +
.../lesson-02-working-with-agents/index.html | 1 +
.../training/lesson-03-choosing-models/index.html | 1 +
.../training/lesson-04-your-first-skill/index.html | 1 +
.../lesson-05-writing-safe-skills/index.html | 1 +
.../lesson-06-debugging-a-skill/index.html | 1 +
.../lesson-07-writing-portable-skills/index.html | 1 +
.../lesson-08-eval-driven-development/index.html | 1 +
.../index.html | 1 +
.../index.html | 1 +
.../lesson-11-how-to-contribute/index.html | 1 +
.../training/lesson-lab-tutorials/index.html | 1 +
skills/education/training/readme/index.html | 1 +
.../training/upstream-contribution/index.html | 1 +
skills/education/tutorials/index.html | 1 +
skills/education/what-agents-are/index.html | 1 +
skills/education/working-with-agents/index.html | 1 +
skills/education/writing-safe-skills/index.html | 1 +
skills/education/your-first-skill/index.html | 1 +
skills/extending/index.html | 1 +
skills/index.html | 1 +
skills/index/index.html | 1 +
skills/issue-management/readme/index.html | 1 +
skills/labels-and-capabilities/index.html | 1 +
skills/mentoring/readme/index.html | 1 +
skills/mentoring/spec/index.html | 1 +
skills/mode-economics/index.html | 1 +
skills/modes/index.html | 1 +
skills/pairing/readme/index.html | 1 +
skills/pilot-report-template/index.html | 1 +
skills/pr-management/readme/index.html | 1 +
skills/principles/index.html | 1 +
skills/quick-start/families/index.html | 1 +
skills/quick-start/first-run/index.html | 1 +
skills/quick-start/index.html | 1 +
.../quick-start/other-install-methods/index.html | 1 +
skills/quick-start/prerequisites/index.html | 1 +
skills/quick-start/readme/index.html | 1 +
skills/quick-start/two-ways/index.html | 1 +
.../atr-release-runbook/index.html | 1 +
.../manual-release-process/index.html | 1 +
skills/release-management/process/index.html | 1 +
skills/release-management/readme/index.html | 1 +
skills/release-management/spec/index.html | 1 +
.../svn-release-runbook/index.html | 1 +
skills/repo-health/readme/index.html | 1 +
skills/rfcs/readme/index.html | 1 +
skills/rfcs/rfc-ai-0002/index.html | 1 +
skills/rfcs/rfc-ai-0003/index.html | 1 +
skills/rfcs/rfc-ai-0004/index.html | 1 +
skills/rfcs/rfc-ai-0005/index.html | 1 +
skills/rfcs/rfc-ai-0006/index.html | 1 +
skills/rfcs/rfc-ai-0007/index.html | 1 +
skills/rfcs/rfc-ai-0008/index.html | 1 +
skills/security/fixing-security-issues/index.html | 1 +
.../security/forwarder-routing-policy/index.html | 1 +
.../how-the-security-team-works/index.html | 1 +
skills/security/poc-handling-policy/index.html | 1 +
skills/security/process/index.html | 1 +
skills/security/readme/index.html | 1 +
skills/security/roles/index.html | 1 +
.../security/security-model-preparation/index.html | 1 +
skills/security/threat-model/index.html | 1 +
skills/setup/agentic-overrides/index.html | 1 +
skills/setup/companion-skills/index.html | 1 +
skills/setup/individual-use/index.html | 1 +
skills/setup/marketplace-install/index.html | 1 +
skills/setup/marketplace/index.html | 1 +
skills/setup/per-role-mcp-access/index.html | 1 +
skills/setup/privacy-llm/index.html | 1 +
skills/setup/readme/index.html | 1 +
skills/setup/sandbox-troubleshooting/index.html | 1 +
skills/setup/secure-agent-internals/index.html | 1 +
skills/setup/secure-agent-setup/index.html | 1 +
skills/setup/team-adoption/index.html | 1 +
skills/setup/uninstall/index.html | 1 +
skills/skill-sources/authoring-a-source/index.html | 1 +
skills/skill-sources/readme/index.html | 1 +
skills/skill-sources/registry/index.html | 1 +
skills/source-release-contents/index.html | 1 +
skills/spec-driven-development/index.html | 1 +
skills/tools/agent-guard/readme/index.html | 1 +
skills/tools/agent-isolation/readme/index.html | 1 +
skills/tools/apache-projects/readme/index.html | 1 +
skills/tools/asf-svn/readme/index.html | 1 +
skills/tools/bitbucket/readme/index.html | 1 +
skills/tools/change-request/readme/index.html | 1 +
skills/tools/cve-org/readme/index.html | 1 +
skills/tools/cve-tool-vulnogram/readme/index.html | 1 +
skills/tools/cve-tool/readme/index.html | 1 +
skills/tools/dashboard-generator/readme/index.html | 1 +
skills/tools/dev/readme/index.html | 1 +
skills/tools/egress-gateway/readme/index.html | 1 +
skills/tools/forwarder-relay/readme/index.html | 1 +
skills/tools/fossil/readme/index.html | 1 +
skills/tools/github-body-field/readme/index.html | 1 +
skills/tools/github-rollup/readme/index.html | 1 +
skills/tools/github/readme/index.html | 1 +
skills/tools/gmail/readme/index.html | 1 +
skills/tools/jira-patch/readme/index.html | 1 +
skills/tools/jira/readme/index.html | 1 +
skills/tools/mail-archive/readme/index.html | 1 +
skills/tools/mail-patch/readme/index.html | 1 +
skills/tools/mail-source/readme/index.html | 1 +
skills/tools/maildir/readme/index.html | 1 +
skills/tools/permission-audit/readme/index.html | 1 +
.../tools/pilot-report-validator/readme/index.html | 1 +
skills/tools/ponymail/readme/index.html | 1 +
skills/tools/pr-management-stats/readme/index.html | 1 +
skills/tools/preflight-audit/readme/index.html | 1 +
skills/tools/privacy-llm/readme/index.html | 1 +
skills/tools/probe-templates/readme/index.html | 1 +
skills/tools/sandbox-lint/readme/index.html | 1 +
skills/tools/scan-format/readme/index.html | 1 +
.../readme/index.html | 1 +
.../skill-and-tool-validator/readme/index.html | 1 +
skills/tools/skill-evals/readme/index.html | 1 +
.../tools/skill-reconciler-diff/readme/index.html | 1 +
skills/tools/skill-token-count/readme/index.html | 1 +
skills/tools/sourcehut/readme/index.html | 1 +
skills/tools/spec-inventory/readme/index.html | 1 +
skills/tools/spec-loop/readme/index.html | 1 +
skills/tools/spec-status-index/readme/index.html | 1 +
skills/tools/spec-validator/readme/index.html | 1 +
skills/tools/symlink-lint/readme/index.html | 1 +
skills/tools/vcs/readme/index.html | 1 +
.../vendor-neutrality-score/readme/index.html | 1 +
skills/tools/vetted-ops/readme/index.html | 1 +
skills/updating-magpie/index.html | 1 +
skills/utilities/readme/index.html | 1 +
skills/vendor-neutrality/index.html | 1 +
styled-logo.svg | 259 +
subframe-mark.svg | 1 +
subframe-styled.svg | 11 +
subframe-wordmark.png | Bin 0 -> 304964 bytes
tools/index.html | 128 +
vendor-logos/atlassian.svg | 1 +
vendor-logos/git.svg | 1 +
vendor-logos/github.svg | 1 +
vendor-logos/google.svg | 1 +
vendor-logos/oak.svg | 1 +
vendor-logos/subversion.svg | 1 +
wordmark.svg | 11 +
711 files changed, 136726 insertions(+)
diff --git a/.asf.yaml b/.asf.yaml
new file mode 100644
index 0000000..8aeb480
--- /dev/null
+++ b/.asf.yaml
@@ -0,0 +1,32 @@
+# Apache Software Foundation repository configuration.
+# https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features
+#
+# The `github:` block below is applied from the default branch (main).
+# The `publish:` block is what serves the website: CI builds the site and
+# force-pushes the generated output (this file included) to the `publish`
+# branch. The `.asf.yaml` on that branch carries `whoami: publish`, which
+# matches the branch name (the asfyaml multi-tenancy guard), so ASF infra
+# publishes it. The hostname is INFERRED from the repository name
+# (magpie-site -> magpie.apache.org) and must NOT be set explicitly: asfyaml
+# forbids naming your own $project.apache.org via the `hostname` field
+# ("It has to be inferred to prevent abuse").
+
+github:
+ description: "Website for Apache Magpie — agent-assisted repository maintainership and development."
+ homepage: https://magpie.apache.org/
+ labels:
+ - apache
+ - magpie
+ - website
+ - astro
+ features:
+ issues: true
+
+notifications:
+ commits: commits@magpie.apache.org
+ issues: commits@magpie.apache.org
+ pullrequests: commits@magpie.apache.org
+ discussions: dev@magpie.apache.org
+
+publish:
+ whoami: publish
diff --git a/.htaccess b/.htaccess
new file mode 100644
index 0000000..05c74ff
--- /dev/null
+++ b/.htaccess
@@ -0,0 +1,39 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Astro copies public/ into dist/ verbatim, and CI force-pushes dist/ to the
+# `publish` branch that ASF infrastructure serves at magpie.apache.org, so
+# this file lands at the site root.
+
+# Unknown paths must answer 404, never a 200 with the app shell. Astro writes
+# 404.html at build time; without ErrorDocument the ASF web server answers
+# with its own bare "Not Found" body and the page's recovery links are lost.
+ErrorDocument 404 /404.html
+
+# Root discovery files and the .md twins carry the Markdown media type. The
+# twins are alternates of the HTML page, not pages, so they stay out of
+# search results.
+<Files "llms.txt">
+ Header set Content-Type "text/markdown; charset=utf-8"
+</Files>
+<Files "llms-full.txt">
+ Header set Content-Type "text/markdown; charset=utf-8"
+</Files>
+<FilesMatch "\.md$">
+ Header set Content-Type "text/markdown; charset=utf-8"
+ Header set X-Robots-Tag "noindex"
+</FilesMatch>
diff --git a/404.html b/404.html
new file mode 100644
index 0000000..3a0fad9
--- /dev/null
+++ b/404.html
@@ -0,0 +1 @@
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="robots" content="noindex"><title>Page not found — Apache Magpie</title></head><body><main><h1>Page not found</h1><p>There is no page at this address on Apache Magpie. It may have moved when the documentation was reorganised.</p><ul><li><a href="/docs/">Documentation index</a></li><li><a href="/">Home</a></li><li><a href="https://magpie.apache.org/llms [...]
\ No newline at end of file
diff --git a/_astro/ImmersiveGradientHero.d5d-wTHX.js b/_astro/ImmersiveGradientHero.d5d-wTHX.js
new file mode 100644
index 0000000..1e1879a
--- /dev/null
+++ b/_astro/ImmersiveGradientHero.d5d-wTHX.js
@@ -0,0 +1,10 @@
+"use client";import{n as e,r as t,t as n}from"./react.CYuo-Lgd.js";var r=t(n(),1);function i(e){var t,n,r=``;if(typeof e==`string`||typeof e==`number`)r+=e;else if(typeof e==`object`)if(Array.isArray(e)){var a=e.length;for(t=0;t<a;t++)e[t]&&(n=i(e[t]))&&(r&&(r+=` `),r+=n)}else for(n in e)e[n]&&(r&&(r+=` `),r+=n);return r}function a(){for(var e,t,n=0,r=``,a=arguments.length;n<a;n++)(e=arguments[n])&&(t=i(e))&&(r&&(r+=` `),r+=t);return r}var o=(e,t)=>{let n=Array(e.length+t.length);for(let [...]
+ [data-motion-pop-id="${s}"] {
+ position: absolute !important;
+ width: ${e}px !important;
+ height: ${r}px !important;
+ ${_}px !important;
+ ${v}px !important;
+ }
+ `),()=>{c.current?.removeAttribute(`data-motion-pop-id`),b.contains(y)&&b.removeChild(y)}},[t]),(0,L.jsx)(Fl,{isPresent:t,childRef:c,sizeRef:l,pop:o,children:o===!1?e:r.cloneElement(e,{ref:d})})}var Ll=({children:e,initial:t,isPresent:n,onExitComplete:i,custom:a,presenceAffectsLayout:o,mode:s,anchorX:c,anchorY:l,root:u})=>{let d=ot(Rl),f=(0,r.useId)(),p=(0,r.useRef)(n),m=(0,r.useRef)(i);st(()=>{p.current=n,m.current=i});let h=!0,g=(0,r.useMemo)(()=>(h=!1,{id:f,initial:t,isPresent [...]
+`)})]},e.chapter))})]}),(0,L.jsxs)(`a`,{href:I(`/docs/security/readme`),className:`mt-5 inline-flex items-center gap-1.5 rounded-md border border-solid border-brand-200 bg-default-background px-3 py-1.5 text-caption font-caption text-brand-700 hover:border-brand-300 hover:bg-brand-100`,children:[`How the security family actually works`,(0,L.jsx)(Q,{className:`size-3.5`})]}),(0,L.jsx)(`p`,{className:`mt-3 max-w-[760px] text-center text-caption font-caption text-subtext-color`,children:`Ex [...]
\ No newline at end of file
diff --git a/_astro/SiteFooter.C2Dgj2WR.css b/_astro/SiteFooter.C2Dgj2WR.css
new file mode 100644
index 0000000..56ae2e2
--- /dev/null
+++ b/_astro/SiteFooter.C2Dgj2WR.css
@@ -0,0 +1,2 @@
+/*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
+@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){:root,:host{--shimmer-angle:20deg}*,:before,:after,::backdrop{--tw-translate-x:0;--tw-translate-y:0;--tw-translate-z:0;--tw-scale-x:1;--tw-scale-y:1;--tw-scale-z:1;--tw-rotate-x:initial;--tw-rotate-y:initial;--tw-rotate-z:initial;--tw-skew-x:initial;--tw-skew-y:initial;--tw-border-style:solid;--tw-gradient-position:initial;--tw-gradient-fro [...]
diff --git a/_astro/client.bxcwkfp-.js b/_astro/client.bxcwkfp-.js
new file mode 100644
index 0000000..dd29ac3
--- /dev/null
+++ b/_astro/client.bxcwkfp-.js
@@ -0,0 +1,9 @@
+import{n as e,r as t,t as n}from"./react.CYuo-Lgd.js";var r=e((e=>{function t(e,t){var n=e.length;e.push(t);a:for(;0<n;){var r=n-1>>>1,a=e[r];if(0<i(a,t))e[r]=t,e[n]=a,n=r;else break a}}function n(e){return e.length===0?null:e[0]}function r(e){if(e.length===0)return null;var t=e[0],n=e.pop();if(n!==t){e[0]=n;a:for(var r=0,a=e.length,o=a>>>1;r<o;){var s=2*(r+1)-1,c=e[s],l=s+1,u=e[l];if(0>i(c,n))l<a&&0>i(u,c)?(e[r]=u,e[l]=n,r=l):(e[r]=c,e[s]=n,r=s);else if(l<a&&0>i(u,n))e[r]=u,e[l]=n,r=l;e [...]
+ at`)?` (<anonymous>)`:-1<e.stack.indexOf(`@`)?`@unknown:0:0`:``}return`
+`+Ee+e+De}var ke=!1;function Ae(e,t){if(!e||ke)return``;ke=!0;var n=Error.prepareStackTrace;Error.prepareStackTrace=void 0;try{var r={DetermineComponentFrameRoot:function(){try{if(t){var n=function(){throw Error()};if(Object.defineProperty(n.prototype,"props",{set:function(){throw Error()}}),typeof Reflect==`object`&&Reflect.construct){try{Reflect.construct(n,[])}catch(e){var r=e}Reflect.construct(e,[],n)}else{try{n.call()}catch(e){r=e}e.call(n.prototype)}}else{try{throw Error()}catch(e) [...]
+`),l=s.split(`
+`);for(i=r=0;r<c.length&&!c[r].includes(`DetermineComponentFrameRoot`);)r++;for(;i<l.length&&!l[i].includes(`DetermineComponentFrameRoot`);)i++;if(r===c.length||i===l.length)for(r=c.length-1,i=l.length-1;1<=r&&0<=i&&c[r]!==l[i];)i--;for(;1<=r&&0<=i;r--,i--)if(c[r]!==l[i]){if(r!==1||i!==1)do if(r--,i--,0>i||c[r]!==l[i]){var u=`
+`+c[r].replace(` at new `,` at `);return e.displayName&&u.includes(`<anonymous>`)&&(u=u.replace(`<anonymous>`,e.displayName)),u}while(1<=r&&0<=i);break}}}finally{ke=!1,Error.prepareStackTrace=n}return(n=e?e.displayName||e.name:``)?Oe(n):``}function je(e,t){switch(e.tag){case 26:case 27:case 5:return Oe(e.type);case 16:return Oe(`Lazy`);case 13:return e.child!==t&&t!==null?Oe(`Suspense Fallback`):Oe(`Suspense`);case 19:return Oe(`SuspenseList`);case 0:case 15:return Ae(e.type,!1);case 11: [...]
+Error generating stack: `+e.message+`
+`+e.stack}}var Ne=Object.prototype.hasOwnProperty,Pe=t.unstable_scheduleCallback,Fe=t.unstable_cancelCallback,Ie=t.unstable_shouldYield,Le=t.unstable_requestPaint,Re=t.unstable_now,ze=t.unstable_getCurrentPriorityLevel,Be=t.unstable_ImmediatePriority,Ve=t.unstable_UserBlockingPriority,He=t.unstable_NormalPriority,Ue=t.unstable_LowPriority,We=t.unstable_IdlePriority,Ge=t.log,Ke=t.unstable_setDisableYieldValue,qe=null,Je=null;function Ye(e){if(typeof Ge==`function`&&Ke(e),Je&&typeof Je.set [...]
+`).replace(jd,``)}function Nd(e,t){return t=Md(t),Md(e)===t}function Q(e,t,n,r,i,a){switch(n){case`children`:typeof r==`string`?t===`body`||t===`textarea`&&r===``||rn(e,r):(typeof r==`number`||typeof r==`bigint`)&&t!==`body`&&rn(e,``+r);break;case`className`:Vt(e,`class`,r);break;case`tabIndex`:Vt(e,`tabindex`,r);break;case`dir`:case`role`:case`viewBox`:case`width`:case`height`:Vt(e,n,r);break;case`style`:sn(e,r,a);break;case`data`:if(t!==`object`){Vt(e,`data`,r);break}case`src`:case`hre [...]
\ No newline at end of file
diff --git a/_astro/geist-cyrillic-ext-wght-normal.DjL33-gN.woff2 b/_astro/geist-cyrillic-ext-wght-normal.DjL33-gN.woff2
new file mode 100644
index 0000000..4c46295
Binary files /dev/null and b/_astro/geist-cyrillic-ext-wght-normal.DjL33-gN.woff2 differ
diff --git a/_astro/geist-cyrillic-wght-normal.BEAKL7Jp.woff2 b/_astro/geist-cyrillic-wght-normal.BEAKL7Jp.woff2
new file mode 100644
index 0000000..4b7a2be
Binary files /dev/null and b/_astro/geist-cyrillic-wght-normal.BEAKL7Jp.woff2 differ
diff --git a/_astro/geist-latin-ext-wght-normal.DC-KSUi6.woff2 b/_astro/geist-latin-ext-wght-normal.DC-KSUi6.woff2
new file mode 100644
index 0000000..ba90e20
Binary files /dev/null and b/_astro/geist-latin-ext-wght-normal.DC-KSUi6.woff2 differ
diff --git a/_astro/geist-latin-wght-normal.BgDaEnEv.woff2 b/_astro/geist-latin-wght-normal.BgDaEnEv.woff2
new file mode 100644
index 0000000..991445d
Binary files /dev/null and b/_astro/geist-latin-wght-normal.BgDaEnEv.woff2 differ
diff --git a/_astro/geist-vietnamese-wght-normal.6IgcOCM7.woff2 b/_astro/geist-vietnamese-wght-normal.6IgcOCM7.woff2
new file mode 100644
index 0000000..ee96589
Binary files /dev/null and b/_astro/geist-vietnamese-wght-normal.6IgcOCM7.woff2 differ
diff --git a/_astro/inter-cyrillic-400-normal.HOLc17fK.woff b/_astro/inter-cyrillic-400-normal.HOLc17fK.woff
new file mode 100644
index 0000000..6bd8b02
Binary files /dev/null and b/_astro/inter-cyrillic-400-normal.HOLc17fK.woff differ
diff --git a/_astro/inter-cyrillic-400-normal.obahsSVq.woff2 b/_astro/inter-cyrillic-400-normal.obahsSVq.woff2
new file mode 100644
index 0000000..e7583fc
Binary files /dev/null and b/_astro/inter-cyrillic-400-normal.obahsSVq.woff2 differ
diff --git a/_astro/inter-cyrillic-500-normal.BasfLYem.woff2 b/_astro/inter-cyrillic-500-normal.BasfLYem.woff2
new file mode 100644
index 0000000..dd14bcf
Binary files /dev/null and b/_astro/inter-cyrillic-500-normal.BasfLYem.woff2 differ
diff --git a/_astro/inter-cyrillic-500-normal.CxZf_p3X.woff b/_astro/inter-cyrillic-500-normal.CxZf_p3X.woff
new file mode 100644
index 0000000..c8aa26e
Binary files /dev/null and b/_astro/inter-cyrillic-500-normal.CxZf_p3X.woff differ
diff --git a/_astro/inter-cyrillic-600-normal.4D_pXhcN.woff b/_astro/inter-cyrillic-600-normal.4D_pXhcN.woff
new file mode 100644
index 0000000..10ec579
Binary files /dev/null and b/_astro/inter-cyrillic-600-normal.4D_pXhcN.woff differ
diff --git a/_astro/inter-cyrillic-600-normal.CWCymEST.woff2 b/_astro/inter-cyrillic-600-normal.CWCymEST.woff2
new file mode 100644
index 0000000..e250ef0
Binary files /dev/null and b/_astro/inter-cyrillic-600-normal.CWCymEST.woff2 differ
diff --git a/_astro/inter-cyrillic-700-normal.CjBOestx.woff2 b/_astro/inter-cyrillic-700-normal.CjBOestx.woff2
new file mode 100644
index 0000000..781e4b4
Binary files /dev/null and b/_astro/inter-cyrillic-700-normal.CjBOestx.woff2 differ
diff --git a/_astro/inter-cyrillic-700-normal.DrXBdSj3.woff b/_astro/inter-cyrillic-700-normal.DrXBdSj3.woff
new file mode 100644
index 0000000..46451f1
Binary files /dev/null and b/_astro/inter-cyrillic-700-normal.DrXBdSj3.woff differ
diff --git a/_astro/inter-cyrillic-ext-400-normal.BQZuk6qB.woff2 b/_astro/inter-cyrillic-ext-400-normal.BQZuk6qB.woff2
new file mode 100644
index 0000000..4ee0d27
Binary files /dev/null and b/_astro/inter-cyrillic-ext-400-normal.BQZuk6qB.woff2 differ
diff --git a/_astro/inter-cyrillic-ext-400-normal.DQukG94-.woff b/_astro/inter-cyrillic-ext-400-normal.DQukG94-.woff
new file mode 100644
index 0000000..6b6dc78
Binary files /dev/null and b/_astro/inter-cyrillic-ext-400-normal.DQukG94-.woff differ
diff --git a/_astro/inter-cyrillic-ext-500-normal.B0yAr1jD.woff2 b/_astro/inter-cyrillic-ext-500-normal.B0yAr1jD.woff2
new file mode 100644
index 0000000..c21492c
Binary files /dev/null and b/_astro/inter-cyrillic-ext-500-normal.B0yAr1jD.woff2 differ
diff --git a/_astro/inter-cyrillic-ext-500-normal.BmqWE9Dz.woff b/_astro/inter-cyrillic-ext-500-normal.BmqWE9Dz.woff
new file mode 100644
index 0000000..e5c7962
Binary files /dev/null and b/_astro/inter-cyrillic-ext-500-normal.BmqWE9Dz.woff differ
diff --git a/_astro/inter-cyrillic-ext-600-normal.Bcila6Z-.woff b/_astro/inter-cyrillic-ext-600-normal.Bcila6Z-.woff
new file mode 100644
index 0000000..7b24dd8
Binary files /dev/null and b/_astro/inter-cyrillic-ext-600-normal.Bcila6Z-.woff differ
diff --git a/_astro/inter-cyrillic-ext-600-normal.Dfes3d0z.woff2 b/_astro/inter-cyrillic-ext-600-normal.Dfes3d0z.woff2
new file mode 100644
index 0000000..e00289e
Binary files /dev/null and b/_astro/inter-cyrillic-ext-600-normal.Dfes3d0z.woff2 differ
diff --git a/_astro/inter-cyrillic-ext-700-normal.BjwYoWNd.woff2 b/_astro/inter-cyrillic-ext-700-normal.BjwYoWNd.woff2
new file mode 100644
index 0000000..1a5c3ce
Binary files /dev/null and b/_astro/inter-cyrillic-ext-700-normal.BjwYoWNd.woff2 differ
diff --git a/_astro/inter-cyrillic-ext-700-normal.LO58E6JB.woff b/_astro/inter-cyrillic-ext-700-normal.LO58E6JB.woff
new file mode 100644
index 0000000..6fb2700
Binary files /dev/null and b/_astro/inter-cyrillic-ext-700-normal.LO58E6JB.woff differ
diff --git a/_astro/inter-greek-400-normal.B4URO6DV.woff2 b/_astro/inter-greek-400-normal.B4URO6DV.woff2
new file mode 100644
index 0000000..e7103fb
Binary files /dev/null and b/_astro/inter-greek-400-normal.B4URO6DV.woff2 differ
diff --git a/_astro/inter-greek-400-normal.q2sYcFCs.woff b/_astro/inter-greek-400-normal.q2sYcFCs.woff
new file mode 100644
index 0000000..c0c36e2
Binary files /dev/null and b/_astro/inter-greek-400-normal.q2sYcFCs.woff differ
diff --git a/_astro/inter-greek-500-normal.BIZE56-Y.woff2 b/_astro/inter-greek-500-normal.BIZE56-Y.woff2
new file mode 100644
index 0000000..730be94
Binary files /dev/null and b/_astro/inter-greek-500-normal.BIZE56-Y.woff2 differ
diff --git a/_astro/inter-greek-500-normal.Xzm54t5V.woff b/_astro/inter-greek-500-normal.Xzm54t5V.woff
new file mode 100644
index 0000000..b4ebbd9
Binary files /dev/null and b/_astro/inter-greek-500-normal.Xzm54t5V.woff differ
diff --git a/_astro/inter-greek-600-normal.BZpKdvQh.woff b/_astro/inter-greek-600-normal.BZpKdvQh.woff
new file mode 100644
index 0000000..ae72058
Binary files /dev/null and b/_astro/inter-greek-600-normal.BZpKdvQh.woff differ
diff --git a/_astro/inter-greek-600-normal.plRanbMR.woff2 b/_astro/inter-greek-600-normal.plRanbMR.woff2
new file mode 100644
index 0000000..479b547
Binary files /dev/null and b/_astro/inter-greek-600-normal.plRanbMR.woff2 differ
diff --git a/_astro/inter-greek-700-normal.BUv2fZ6O.woff b/_astro/inter-greek-700-normal.BUv2fZ6O.woff
new file mode 100644
index 0000000..1d428f5
Binary files /dev/null and b/_astro/inter-greek-700-normal.BUv2fZ6O.woff differ
diff --git a/_astro/inter-greek-700-normal.C3JjAnD8.woff2 b/_astro/inter-greek-700-normal.C3JjAnD8.woff2
new file mode 100644
index 0000000..3a9fc0b
Binary files /dev/null and b/_astro/inter-greek-700-normal.C3JjAnD8.woff2 differ
diff --git a/_astro/inter-greek-ext-400-normal.DGGRlc-M.woff2 b/_astro/inter-greek-ext-400-normal.DGGRlc-M.woff2
new file mode 100644
index 0000000..7cb1d6b
Binary files /dev/null and b/_astro/inter-greek-ext-400-normal.DGGRlc-M.woff2 differ
diff --git a/_astro/inter-greek-ext-400-normal.KugGGMne.woff b/_astro/inter-greek-ext-400-normal.KugGGMne.woff
new file mode 100644
index 0000000..96f1f60
Binary files /dev/null and b/_astro/inter-greek-ext-400-normal.KugGGMne.woff differ
diff --git a/_astro/inter-greek-ext-500-normal.2j5mBUwD.woff b/_astro/inter-greek-ext-500-normal.2j5mBUwD.woff
new file mode 100644
index 0000000..713c500
Binary files /dev/null and b/_astro/inter-greek-ext-500-normal.2j5mBUwD.woff differ
diff --git a/_astro/inter-greek-ext-500-normal.C4iEst2y.woff2 b/_astro/inter-greek-ext-500-normal.C4iEst2y.woff2
new file mode 100644
index 0000000..4062b66
Binary files /dev/null and b/_astro/inter-greek-ext-500-normal.C4iEst2y.woff2 differ
diff --git a/_astro/inter-greek-ext-600-normal.B8X0CLgF.woff b/_astro/inter-greek-ext-600-normal.B8X0CLgF.woff
new file mode 100644
index 0000000..b3d15d1
Binary files /dev/null and b/_astro/inter-greek-ext-600-normal.B8X0CLgF.woff differ
diff --git a/_astro/inter-greek-ext-600-normal.DRtmH8MT.woff2 b/_astro/inter-greek-ext-600-normal.DRtmH8MT.woff2
new file mode 100644
index 0000000..83e7de9
Binary files /dev/null and b/_astro/inter-greek-ext-600-normal.DRtmH8MT.woff2 differ
diff --git a/_astro/inter-greek-ext-700-normal.BoQ6DsYi.woff b/_astro/inter-greek-ext-700-normal.BoQ6DsYi.woff
new file mode 100644
index 0000000..e36fd56
Binary files /dev/null and b/_astro/inter-greek-ext-700-normal.BoQ6DsYi.woff differ
diff --git a/_astro/inter-greek-ext-700-normal.qfdV9bQt.woff2 b/_astro/inter-greek-ext-700-normal.qfdV9bQt.woff2
new file mode 100644
index 0000000..af7bcba
Binary files /dev/null and b/_astro/inter-greek-ext-700-normal.qfdV9bQt.woff2 differ
diff --git a/_astro/inter-latin-400-normal.C38fXH4l.woff2 b/_astro/inter-latin-400-normal.C38fXH4l.woff2
new file mode 100644
index 0000000..f15b025
Binary files /dev/null and b/_astro/inter-latin-400-normal.C38fXH4l.woff2 differ
diff --git a/_astro/inter-latin-400-normal.CyCys3Eg.woff b/_astro/inter-latin-400-normal.CyCys3Eg.woff
new file mode 100644
index 0000000..2f21ed4
Binary files /dev/null and b/_astro/inter-latin-400-normal.CyCys3Eg.woff differ
diff --git a/_astro/inter-latin-500-normal.BL9OpVg8.woff b/_astro/inter-latin-500-normal.BL9OpVg8.woff
new file mode 100644
index 0000000..07775a3
Binary files /dev/null and b/_astro/inter-latin-500-normal.BL9OpVg8.woff differ
diff --git a/_astro/inter-latin-500-normal.Cerq10X2.woff2 b/_astro/inter-latin-500-normal.Cerq10X2.woff2
new file mode 100644
index 0000000..54f0a59
Binary files /dev/null and b/_astro/inter-latin-500-normal.Cerq10X2.woff2 differ
diff --git a/_astro/inter-latin-600-normal.CiBQ2DWP.woff b/_astro/inter-latin-600-normal.CiBQ2DWP.woff
new file mode 100644
index 0000000..323fa67
Binary files /dev/null and b/_astro/inter-latin-600-normal.CiBQ2DWP.woff differ
diff --git a/_astro/inter-latin-600-normal.LgqL8muc.woff2 b/_astro/inter-latin-600-normal.LgqL8muc.woff2
new file mode 100644
index 0000000..d189794
Binary files /dev/null and b/_astro/inter-latin-600-normal.LgqL8muc.woff2 differ
diff --git a/_astro/inter-latin-700-normal.BLAVimhd.woff b/_astro/inter-latin-700-normal.BLAVimhd.woff
new file mode 100644
index 0000000..161b01e
Binary files /dev/null and b/_astro/inter-latin-700-normal.BLAVimhd.woff differ
diff --git a/_astro/inter-latin-700-normal.Yt3aPRUw.woff2 b/_astro/inter-latin-700-normal.Yt3aPRUw.woff2
new file mode 100644
index 0000000..a68fb10
Binary files /dev/null and b/_astro/inter-latin-700-normal.Yt3aPRUw.woff2 differ
diff --git a/_astro/inter-latin-ext-400-normal.77YHD8bZ.woff b/_astro/inter-latin-ext-400-normal.77YHD8bZ.woff
new file mode 100644
index 0000000..0238739
Binary files /dev/null and b/_astro/inter-latin-ext-400-normal.77YHD8bZ.woff differ
diff --git a/_astro/inter-latin-ext-400-normal.C1nco2VV.woff2 b/_astro/inter-latin-ext-400-normal.C1nco2VV.woff2
new file mode 100644
index 0000000..5243e4b
Binary files /dev/null and b/_astro/inter-latin-ext-400-normal.C1nco2VV.woff2 differ
diff --git a/_astro/inter-latin-ext-500-normal.BxGbmqWO.woff b/_astro/inter-latin-ext-500-normal.BxGbmqWO.woff
new file mode 100644
index 0000000..e6a577e
Binary files /dev/null and b/_astro/inter-latin-ext-500-normal.BxGbmqWO.woff differ
diff --git a/_astro/inter-latin-ext-500-normal.CV4jyFjo.woff2 b/_astro/inter-latin-ext-500-normal.CV4jyFjo.woff2
new file mode 100644
index 0000000..2ab7ebf
Binary files /dev/null and b/_astro/inter-latin-ext-500-normal.CV4jyFjo.woff2 differ
diff --git a/_astro/inter-latin-ext-600-normal.CIVaiw4L.woff b/_astro/inter-latin-ext-600-normal.CIVaiw4L.woff
new file mode 100644
index 0000000..74b454b
Binary files /dev/null and b/_astro/inter-latin-ext-600-normal.CIVaiw4L.woff differ
diff --git a/_astro/inter-latin-ext-600-normal.D2bJ5OIk.woff2 b/_astro/inter-latin-ext-600-normal.D2bJ5OIk.woff2
new file mode 100644
index 0000000..bad65d4
Binary files /dev/null and b/_astro/inter-latin-ext-600-normal.D2bJ5OIk.woff2 differ
diff --git a/_astro/inter-latin-ext-700-normal.Ca8adRJv.woff2 b/_astro/inter-latin-ext-700-normal.Ca8adRJv.woff2
new file mode 100644
index 0000000..c9507e3
Binary files /dev/null and b/_astro/inter-latin-ext-700-normal.Ca8adRJv.woff2 differ
diff --git a/_astro/inter-latin-ext-700-normal.TidjK2hL.woff b/_astro/inter-latin-ext-700-normal.TidjK2hL.woff
new file mode 100644
index 0000000..b4517fc
Binary files /dev/null and b/_astro/inter-latin-ext-700-normal.TidjK2hL.woff differ
diff --git a/_astro/inter-vietnamese-400-normal.Bbgyi5SW.woff b/_astro/inter-vietnamese-400-normal.Bbgyi5SW.woff
new file mode 100644
index 0000000..ff3f8f1
Binary files /dev/null and b/_astro/inter-vietnamese-400-normal.Bbgyi5SW.woff differ
diff --git a/_astro/inter-vietnamese-400-normal.DMkecbls.woff2 b/_astro/inter-vietnamese-400-normal.DMkecbls.woff2
new file mode 100644
index 0000000..ba7767f
Binary files /dev/null and b/_astro/inter-vietnamese-400-normal.DMkecbls.woff2 differ
diff --git a/_astro/inter-vietnamese-500-normal.DOriooB6.woff2 b/_astro/inter-vietnamese-500-normal.DOriooB6.woff2
new file mode 100644
index 0000000..abe88f5
Binary files /dev/null and b/_astro/inter-vietnamese-500-normal.DOriooB6.woff2 differ
diff --git a/_astro/inter-vietnamese-500-normal.mJboJaSs.woff b/_astro/inter-vietnamese-500-normal.mJboJaSs.woff
new file mode 100644
index 0000000..87a9d4d
Binary files /dev/null and b/_astro/inter-vietnamese-500-normal.mJboJaSs.woff differ
diff --git a/_astro/inter-vietnamese-600-normal.BuLX-rYi.woff b/_astro/inter-vietnamese-600-normal.BuLX-rYi.woff
new file mode 100644
index 0000000..264f0f5
Binary files /dev/null and b/_astro/inter-vietnamese-600-normal.BuLX-rYi.woff differ
diff --git a/_astro/inter-vietnamese-600-normal.Cc8MFFhd.woff2 b/_astro/inter-vietnamese-600-normal.Cc8MFFhd.woff2
new file mode 100644
index 0000000..e7b7814
Binary files /dev/null and b/_astro/inter-vietnamese-600-normal.Cc8MFFhd.woff2 differ
diff --git a/_astro/inter-vietnamese-700-normal.BZaoP0fm.woff b/_astro/inter-vietnamese-700-normal.BZaoP0fm.woff
new file mode 100644
index 0000000..26d92ec
Binary files /dev/null and b/_astro/inter-vietnamese-700-normal.BZaoP0fm.woff differ
diff --git a/_astro/inter-vietnamese-700-normal.DlLaEgI2.woff2 b/_astro/inter-vietnamese-700-normal.DlLaEgI2.woff2
new file mode 100644
index 0000000..38c516e
Binary files /dev/null and b/_astro/inter-vietnamese-700-normal.DlLaEgI2.woff2 differ
diff --git a/_astro/jost-cyrillic-400-normal.Dk3McGkH.woff b/_astro/jost-cyrillic-400-normal.Dk3McGkH.woff
new file mode 100644
index 0000000..2ba4e06
Binary files /dev/null and b/_astro/jost-cyrillic-400-normal.Dk3McGkH.woff differ
diff --git a/_astro/jost-cyrillic-400-normal.bVZEi0jL.woff2 b/_astro/jost-cyrillic-400-normal.bVZEi0jL.woff2
new file mode 100644
index 0000000..c930567
Binary files /dev/null and b/_astro/jost-cyrillic-400-normal.bVZEi0jL.woff2 differ
diff --git a/_astro/jost-cyrillic-500-normal.DlHwnXyv.woff b/_astro/jost-cyrillic-500-normal.DlHwnXyv.woff
new file mode 100644
index 0000000..4a4616a
Binary files /dev/null and b/_astro/jost-cyrillic-500-normal.DlHwnXyv.woff differ
diff --git a/_astro/jost-cyrillic-500-normal.DtB2bvF0.woff2 b/_astro/jost-cyrillic-500-normal.DtB2bvF0.woff2
new file mode 100644
index 0000000..37f6401
Binary files /dev/null and b/_astro/jost-cyrillic-500-normal.DtB2bvF0.woff2 differ
diff --git a/_astro/jost-cyrillic-600-normal.BEDXyecp.woff2 b/_astro/jost-cyrillic-600-normal.BEDXyecp.woff2
new file mode 100644
index 0000000..4ebbae6
Binary files /dev/null and b/_astro/jost-cyrillic-600-normal.BEDXyecp.woff2 differ
diff --git a/_astro/jost-cyrillic-600-normal.D0Fzn8un.woff b/_astro/jost-cyrillic-600-normal.D0Fzn8un.woff
new file mode 100644
index 0000000..27fd386
Binary files /dev/null and b/_astro/jost-cyrillic-600-normal.D0Fzn8un.woff differ
diff --git a/_astro/jost-cyrillic-700-normal.BHDNzvjF.woff b/_astro/jost-cyrillic-700-normal.BHDNzvjF.woff
new file mode 100644
index 0000000..5914f0f
Binary files /dev/null and b/_astro/jost-cyrillic-700-normal.BHDNzvjF.woff differ
diff --git a/_astro/jost-cyrillic-700-normal._ob5o-r5.woff2 b/_astro/jost-cyrillic-700-normal._ob5o-r5.woff2
new file mode 100644
index 0000000..5ae7751
Binary files /dev/null and b/_astro/jost-cyrillic-700-normal._ob5o-r5.woff2 differ
diff --git a/_astro/jost-latin-400-normal.C7S-3Ky6.woff b/_astro/jost-latin-400-normal.C7S-3Ky6.woff
new file mode 100644
index 0000000..515f532
Binary files /dev/null and b/_astro/jost-latin-400-normal.C7S-3Ky6.woff differ
diff --git a/_astro/jost-latin-400-normal.q-RKOgPK.woff2 b/_astro/jost-latin-400-normal.q-RKOgPK.woff2
new file mode 100644
index 0000000..a93b79d
Binary files /dev/null and b/_astro/jost-latin-400-normal.q-RKOgPK.woff2 differ
diff --git a/_astro/jost-latin-500-normal.41lBe9I9.woff2 b/_astro/jost-latin-500-normal.41lBe9I9.woff2
new file mode 100644
index 0000000..80e9c5b
Binary files /dev/null and b/_astro/jost-latin-500-normal.41lBe9I9.woff2 differ
diff --git a/_astro/jost-latin-500-normal.B-AtzreL.woff b/_astro/jost-latin-500-normal.B-AtzreL.woff
new file mode 100644
index 0000000..62837c4
Binary files /dev/null and b/_astro/jost-latin-500-normal.B-AtzreL.woff differ
diff --git a/_astro/jost-latin-600-normal.Bv_M0d15.woff b/_astro/jost-latin-600-normal.Bv_M0d15.woff
new file mode 100644
index 0000000..554e7e7
Binary files /dev/null and b/_astro/jost-latin-600-normal.Bv_M0d15.woff differ
diff --git a/_astro/jost-latin-600-normal.C497H-z9.woff2 b/_astro/jost-latin-600-normal.C497H-z9.woff2
new file mode 100644
index 0000000..d083772
Binary files /dev/null and b/_astro/jost-latin-600-normal.C497H-z9.woff2 differ
diff --git a/_astro/jost-latin-700-normal.k-iBXzmq.woff b/_astro/jost-latin-700-normal.k-iBXzmq.woff
new file mode 100644
index 0000000..99caca0
Binary files /dev/null and b/_astro/jost-latin-700-normal.k-iBXzmq.woff differ
diff --git a/_astro/jost-latin-700-normal.u2Hrqd6k.woff2 b/_astro/jost-latin-700-normal.u2Hrqd6k.woff2
new file mode 100644
index 0000000..3d3e683
Binary files /dev/null and b/_astro/jost-latin-700-normal.u2Hrqd6k.woff2 differ
diff --git a/_astro/jost-latin-ext-400-normal.CpdMQIMr.woff2 b/_astro/jost-latin-ext-400-normal.CpdMQIMr.woff2
new file mode 100644
index 0000000..07e0e47
Binary files /dev/null and b/_astro/jost-latin-ext-400-normal.CpdMQIMr.woff2 differ
diff --git a/_astro/jost-latin-ext-400-normal.Dsyb2mtt.woff b/_astro/jost-latin-ext-400-normal.Dsyb2mtt.woff
new file mode 100644
index 0000000..ab7db75
Binary files /dev/null and b/_astro/jost-latin-ext-400-normal.Dsyb2mtt.woff differ
diff --git a/_astro/jost-latin-ext-500-normal.BkvHgcKf.woff2 b/_astro/jost-latin-ext-500-normal.BkvHgcKf.woff2
new file mode 100644
index 0000000..4d4b532
Binary files /dev/null and b/_astro/jost-latin-ext-500-normal.BkvHgcKf.woff2 differ
diff --git a/_astro/jost-latin-ext-500-normal.Cpxiadwk.woff b/_astro/jost-latin-ext-500-normal.Cpxiadwk.woff
new file mode 100644
index 0000000..8c24c0a
Binary files /dev/null and b/_astro/jost-latin-ext-500-normal.Cpxiadwk.woff differ
diff --git a/_astro/jost-latin-ext-600-normal.D8I9kjga.woff2 b/_astro/jost-latin-ext-600-normal.D8I9kjga.woff2
new file mode 100644
index 0000000..3809c6a
Binary files /dev/null and b/_astro/jost-latin-ext-600-normal.D8I9kjga.woff2 differ
diff --git a/_astro/jost-latin-ext-600-normal.Pm6OqGZB.woff b/_astro/jost-latin-ext-600-normal.Pm6OqGZB.woff
new file mode 100644
index 0000000..dbba5f7
Binary files /dev/null and b/_astro/jost-latin-ext-600-normal.Pm6OqGZB.woff differ
diff --git a/_astro/jost-latin-ext-700-normal.AnR_ULdm.woff2 b/_astro/jost-latin-ext-700-normal.AnR_ULdm.woff2
new file mode 100644
index 0000000..4f7d685
Binary files /dev/null and b/_astro/jost-latin-ext-700-normal.AnR_ULdm.woff2 differ
diff --git a/_astro/jost-latin-ext-700-normal.DTcCupJy.woff b/_astro/jost-latin-ext-700-normal.DTcCupJy.woff
new file mode 100644
index 0000000..3e578b5
Binary files /dev/null and b/_astro/jost-latin-ext-700-normal.DTcCupJy.woff differ
diff --git a/_astro/react.CYuo-Lgd.js b/_astro/react.CYuo-Lgd.js
new file mode 100644
index 0000000..d1dd543
--- /dev/null
+++ b/_astro/react.CYuo-Lgd.js
@@ -0,0 +1 @@
+var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,t)=>()=>(t||(e((t={exports:{}}).exports,t),e=null),t.exports),s=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},c=(n,r,a)=>(a=n==null?{}:e(i(n)),s(r||!n||!n.__e [...]
\ No newline at end of file
diff --git a/architecture/index.html b/architecture/index.html
new file mode 100644
index 0000000..0e9e2d7
--- /dev/null
+++ b/architecture/index.html
@@ -0,0 +1,75 @@
+<!DOCTYPE html><html lang="en" data-astro-cid-z4jru4n3><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="description" content="Apache Magpie's architecture: skills declare capabilities, tools provide contract and substrate interfaces, adapters implement them, and organizations bundle the defaults. Generated from the framework repo."><link rel="icon" type="image/svg+xml" href="/favicon.svg"><link rel="icon" type="image/x-icon" si [...]
+ var _paq = (window._paq = window._paq || []);
+ /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
+ _paq.push(["setDoNotTrack", true]);
+ _paq.push(["disableCookies"]);
+ _paq.push(["trackPageView"]);
+ _paq.push(["enableLinkTracking"]);
+ (function () {
+ var u = "https://analytics.apache.org/";
+ _paq.push(["setTrackerUrl", u + "matomo.php"]);
+ _paq.push(["setSiteId", "89"]);
+ var d = document,
+ g = d.createElement("script"),
+ s = d.getElementsByTagName("script")[0];
+ g.async = true;
+ g.src = u + "matomo.js";
+ s.parentNode.insertBefore(g, s);
+ })();
+ </script><link rel="stylesheet" href="/_astro/SiteFooter.C2Dgj2WR.css"></head><body data-astro-cid-z4jru4n3><nav class="relative z-10 flex w-full items-center justify-between bg-default-background px-8 py-5 mobile:px-4"><a href="/" aria-label="Apache Magpie home" class="flex items-end justify-end gap-2 px-2 py-2"><img class="h-10 w-10 flex-none object-cover" src="/subframe-mark.svg" alt="Apache Magpie"/><img class="h-10 flex-none object-contain" src="/subframe-wordmark.png" alt="Magp [...]
+ │ the capability is the only coupling
+ TOOL ──provides──▶ contract:tracker ─┘ (skills never branch on the backend)
+ │
+ ├─ contract:* one per capability seam → an ADAPTER implements it for a vendor
+ └─ substrate:* framework plumbing (sandbox, privacy, analytics, …)
+
+ ORGANIZATION (ASF, independent, …) ──bundles──▶ which adapter fulfils each capability
+ + governance vocabulary + identity/logo</pre></div></div></section><!-- Skill capabilities --><section id="skill-capabilities" class="w-full px-8 py-16 mobile:px-4 mobile:py-12 bg-default-background scroll-mt-14"><div class="mx-auto flex w-full max-w-[1100px] flex-col gap-5"><div class="flex flex-col gap-1"><h2 class="text-heading-2 font-heading-2 text-default-font">Skill capabilities</h2><p class="text-body font-body text-subtext-color [...]
+ (() => {
+ const links = [...document.querySelectorAll("[data-arch-link]")];
+ if (!links.length) return;
+ let current = null;
+ const setActive = (id) => {
+ if (id === current) return;
+ current = id;
+ for (const a of links) {
+ const on = a.getAttribute("data-arch-link") === id;
+ a.classList.toggle("bg-brand-100", on);
+ a.classList.toggle("text-brand-800", on);
+ a.classList.toggle("text-default-font", !on);
+ if (on) a.setAttribute("aria-current", "true");
+ else a.removeAttribute("aria-current");
+ }
+ };
+ const ids = links.map((a) => a.getAttribute("data-arch-link"));
+ const lastId = ids[ids.length - 1];
+ const sections = ids.map((id) => document.getElementById(id)).filter(Boolean);
+
+ // Near the bottom the last section can never reach the top active-band, so
+ // the observer would otherwise leave a higher section highlighted. Force
+ // the last item active whenever the page can't scroll any further.
+ const atBottom = () =>
+ window.innerHeight + Math.ceil(window.scrollY) >=
+ document.documentElement.scrollHeight - 2;
+
+ const obs = new IntersectionObserver(
+ (entries) => {
+ if (atBottom()) return setActive(lastId);
+ const visible = entries.filter((e) => e.isIntersecting);
+ if (!visible.length) return;
+ visible.sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top);
+ setActive(visible[0].target.id);
+ },
+ { rootMargin: "-10% 0px -80% 0px", threshold: 0 },
+ );
+ for (const s of sections) obs.observe(s);
+ window.addEventListener("scroll", () => { if (atBottom()) setActive(lastId); }, { passive: true });
+
+ // Clicking a nav item highlights it right away and keeps it highlighted —
+ // important for short sections (e.g. the last one) that the scroll-spy's
+ // active-band can't reach.
+ for (const a of links) {
+ a.addEventListener("click", () => setActive(a.getAttribute("data-arch-link")));
+ }
+ })();
+ </script><a href="https://github.com/apache/magpie-site/edit/main/src/pages/architecture.astro" target="_blank" rel="noopener noreferrer" class="suggest-change" aria-label="Suggest a change to this page on GitHub" data-astro-cid-z4jru4n3><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" data-astro-cid-z4jru4n3><path d="M12 20h9" data-astro-cid-z4jru4n3></path><path d="M16. [...]
\ No newline at end of file
diff --git a/brand/avatar-1000.png b/brand/avatar-1000.png
new file mode 100644
index 0000000..9a39fa5
Binary files /dev/null and b/brand/avatar-1000.png differ
diff --git a/brand/avatar-400.png b/brand/avatar-400.png
new file mode 100644
index 0000000..6d6b0f5
Binary files /dev/null and b/brand/avatar-400.png differ
diff --git a/brand/banner-1500x500.png b/brand/banner-1500x500.png
new file mode 100644
index 0000000..30b8985
Binary files /dev/null and b/brand/banner-1500x500.png differ
diff --git a/brand/banner-bluesky-3000x1000.png b/brand/banner-bluesky-3000x1000.png
new file mode 100644
index 0000000..8a5f65f
Binary files /dev/null and b/brand/banner-bluesky-3000x1000.png differ
diff --git a/brand/banner-linkedin-1128x191.png b/brand/banner-linkedin-1128x191.png
new file mode 100644
index 0000000..6e5fbc8
Binary files /dev/null and b/brand/banner-linkedin-1128x191.png differ
diff --git a/brand/index.html b/brand/index.html
new file mode 100644
index 0000000..2ae02ac
--- /dev/null
+++ b/brand/index.html
@@ -0,0 +1,19 @@
+<!DOCTYPE html><html lang="en" data-astro-cid-z4jru4n3><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="description" content="The Apache Magpie brand book: logo and mark, color palette, typography, and ready-to-use social-media avatars and banners for X, LinkedIn, Fosstodon/Mastodon and Bluesky."><link rel="icon" type="image/svg+xml" href="/favicon.svg"><link rel="icon" type="image/x-icon" sizes="any" href="/favicon.ico"><title [...]
+ var _paq = (window._paq = window._paq || []);
+ /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
+ _paq.push(["setDoNotTrack", true]);
+ _paq.push(["disableCookies"]);
+ _paq.push(["trackPageView"]);
+ _paq.push(["enableLinkTracking"]);
+ (function () {
+ var u = "https://analytics.apache.org/";
+ _paq.push(["setTrackerUrl", u + "matomo.php"]);
+ _paq.push(["setSiteId", "89"]);
+ var d = document,
+ g = d.createElement("script"),
+ s = d.getElementsByTagName("script")[0];
+ g.async = true;
+ g.src = u + "matomo.js";
+ s.parentNode.insertBefore(g, s);
+ })();
+ </script><link rel="stylesheet" href="/_astro/SiteFooter.C2Dgj2WR.css"></head><body data-astro-cid-z4jru4n3><nav class="relative z-10 flex w-full items-center justify-between bg-default-background px-8 py-5 mobile:px-4"><a href="/" aria-label="Apache Magpie home" class="flex items-end justify-end gap-2 px-2 py-2"><img class="h-10 w-10 flex-none object-cover" src="/subframe-mark.svg" alt="Apache Magpie"/><img class="h-10 flex-none object-contain" src="/subframe-wordmark.png" alt="Magp [...]
\ No newline at end of file
diff --git a/community-avatars/CalvinKirs.png b/community-avatars/CalvinKirs.png
new file mode 100644
index 0000000..8b8e5d4
Binary files /dev/null and b/community-avatars/CalvinKirs.png differ
diff --git a/community-avatars/RussellSpitzer.png b/community-avatars/RussellSpitzer.png
new file mode 100644
index 0000000..af1abd6
Binary files /dev/null and b/community-avatars/RussellSpitzer.png differ
diff --git a/community-avatars/amoghrajesh.png b/community-avatars/amoghrajesh.png
new file mode 100644
index 0000000..852471f
Binary files /dev/null and b/community-avatars/amoghrajesh.png differ
diff --git a/community-avatars/andreahlert.png b/community-avatars/andreahlert.png
new file mode 100644
index 0000000..a96535f
Binary files /dev/null and b/community-avatars/andreahlert.png differ
diff --git a/community-avatars/andrewmusselman.png b/community-avatars/andrewmusselman.png
new file mode 100644
index 0000000..8e40e77
Binary files /dev/null and b/community-avatars/andrewmusselman.png differ
diff --git a/community-avatars/choo121600.png b/community-avatars/choo121600.png
new file mode 100644
index 0000000..041c0ae
Binary files /dev/null and b/community-avatars/choo121600.png differ
diff --git a/community-avatars/clr-apache.png b/community-avatars/clr-apache.png
new file mode 100644
index 0000000..30e0202
Binary files /dev/null and b/community-avatars/clr-apache.png differ
diff --git a/community-avatars/csutherl.png b/community-avatars/csutherl.png
new file mode 100644
index 0000000..d386755
Binary files /dev/null and b/community-avatars/csutherl.png differ
diff --git a/community-avatars/eladkal.png b/community-avatars/eladkal.png
new file mode 100644
index 0000000..70fbfd4
Binary files /dev/null and b/community-avatars/eladkal.png differ
diff --git a/community-avatars/gopidesupavan.png b/community-avatars/gopidesupavan.png
new file mode 100644
index 0000000..2b3e9c0
Binary files /dev/null and b/community-avatars/gopidesupavan.png differ
diff --git a/community-avatars/iemejia.png b/community-avatars/iemejia.png
new file mode 100644
index 0000000..69fa30c
Binary files /dev/null and b/community-avatars/iemejia.png differ
diff --git a/community-avatars/jamesfredley.png b/community-avatars/jamesfredley.png
new file mode 100644
index 0000000..a3e92ef
Binary files /dev/null and b/community-avatars/jamesfredley.png differ
diff --git a/community-avatars/jbonofre.png b/community-avatars/jbonofre.png
new file mode 100644
index 0000000..6a8c1ce
Binary files /dev/null and b/community-avatars/jbonofre.png differ
diff --git a/community-avatars/justinmclean.png b/community-avatars/justinmclean.png
new file mode 100644
index 0000000..35f8a2a
Binary files /dev/null and b/community-avatars/justinmclean.png differ
diff --git a/community-avatars/madrob.png b/community-avatars/madrob.png
new file mode 100644
index 0000000..4e290bf
Binary files /dev/null and b/community-avatars/madrob.png differ
diff --git a/community-avatars/onlyarnav.png b/community-avatars/onlyarnav.png
new file mode 100644
index 0000000..6d5d22a
Binary files /dev/null and b/community-avatars/onlyarnav.png differ
diff --git a/community-avatars/paulk-asert.png b/community-avatars/paulk-asert.png
new file mode 100644
index 0000000..ec7a550
Binary files /dev/null and b/community-avatars/paulk-asert.png differ
diff --git a/community-avatars/potiuk.png b/community-avatars/potiuk.png
new file mode 100644
index 0000000..32a2e8e
Binary files /dev/null and b/community-avatars/potiuk.png differ
diff --git a/community-avatars/ppkarwasz.png b/community-avatars/ppkarwasz.png
new file mode 100644
index 0000000..871ba0e
Binary files /dev/null and b/community-avatars/ppkarwasz.png differ
diff --git a/community-avatars/rbowen.png b/community-avatars/rbowen.png
new file mode 100644
index 0000000..6741308
Binary files /dev/null and b/community-avatars/rbowen.png differ
diff --git a/community-avatars/rmaucher.png b/community-avatars/rmaucher.png
new file mode 100644
index 0000000..58c5a6d
Binary files /dev/null and b/community-avatars/rmaucher.png differ
diff --git a/community-avatars/rusackas.png b/community-avatars/rusackas.png
new file mode 100644
index 0000000..37eedb1
Binary files /dev/null and b/community-avatars/rusackas.png differ
diff --git a/community-avatars/rzo1.png b/community-avatars/rzo1.png
new file mode 100644
index 0000000..23e350d
Binary files /dev/null and b/community-avatars/rzo1.png differ
diff --git a/community-avatars/tisonkun.png b/community-avatars/tisonkun.png
new file mode 100644
index 0000000..eead4fa
Binary files /dev/null and b/community-avatars/tisonkun.png differ
diff --git a/community-avatars/zeroshade.png b/community-avatars/zeroshade.png
new file mode 100644
index 0000000..9abe36b
Binary files /dev/null and b/community-avatars/zeroshade.png differ
diff --git a/docs-assets/badge.json b/docs-assets/badge.json
new file mode 100644
index 0000000..78a59c2
--- /dev/null
+++ b/docs-assets/badge.json
@@ -0,0 +1,8 @@
+{
+ "label": "",
+ "message": "Magpie",
+ "logoSvg": "<svg xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" width=\"2000\" zoomAndPan=\"magnify\" viewBox=\"0 0 1500 1499.999933\" height=\"2000\" preserveAspectRatio=\"xMidYMid meet\" version=\"1.0\"><defs><clipPath id=\"9639fc2a4f\"><path d=\"M 16.496094 41.253906 L 1483.496094 41.253906 L 1483.496094 1458.753906 L 16.496094 1458.753906 Z M 16.496094 41.253906 \" clip-rule=\"nonzero\"/></clipPath></defs><g clip-path=\"url(#9639fc2a4f)\"><path fi [...]
+ "logoWidth": 10,
+ "labelColor": "#004aae",
+ "color": "#004aae"
+}
diff --git a/docs-assets/bump-dev-version-run.png b/docs-assets/bump-dev-version-run.png
new file mode 100644
index 0000000..d07369a
Binary files /dev/null and b/docs-assets/bump-dev-version-run.png differ
diff --git a/docs-assets/installed-plugins.png b/docs-assets/installed-plugins.png
new file mode 100644
index 0000000..09cee6e
Binary files /dev/null and b/docs-assets/installed-plugins.png differ
diff --git a/docs-assets/quickstart/README.md b/docs-assets/quickstart/README.md
new file mode 100644
index 0000000..5688d7f
--- /dev/null
+++ b/docs-assets/quickstart/README.md
@@ -0,0 +1,167 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [One recording, and a set of authored screenshots](#one-recording-and-a-set-of-authored-screenshots)
+ - [Why one is recorded and the rest are written](#why-one-is-recorded-and-the-rest-are-written)
+ - [What the check can prove, and what it cannot](#what-the-check-can-prove-and-what-it-cannot)
+ - [Adding a screenshot](#adding-a-screenshot)
+ - [Conventions](#conventions)
+ - [The animated runs](#the-animated-runs)
+ - [Why SVG](#why-svg)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# One recording, and a set of authored screenshots
+
+| File | Embedded by | Shows |
+|---|---|---|
+| `magpie-setup.svg` | [`docs/quick-start.md`](../../docs/quick-start.md), and [`docs/setup/README.md`](../../docs/setup/README.md) | `/magpie-setup` detecting the checkout, printing its plan, and waiting for approval. A real recording of a real run. |
+| `wizard/<family>.svg` | that family's README, *Before the first run* | An **animated** `/magpie-setup config` run for that family. Generated from `requires_config:` frontmatter by [`render-wizard.py`](../../tools/dev/render-wizard.py) — there is no transcript to edit. Illustrative of the shape of a run, not a recording of one. |
+| `families/<family>/<skill>.txt` | — | The authored transcript. This is the source file. |
+| `families/<family>/<skill>.svg` | that family's README, *Try these first* | The transcript rendered. Generated; never hand-edited. |
+
+The setup family has no screenshot of `/magpie-setup` itself: its first run
+*is* `magpie-setup.svg`, so `docs/setup/README.md` embeds that rather than a
+copy.
+
+## Why one is recorded and the rest are written
+
+A capture needs a terminal, a scratch project, and a human — and it needs all
+three again the next time any output moves.
+
+That price is worth paying once. `/magpie-setup` is the run a reader has not
+done yet, and seeing it actually happen, at the pace it happens, is worth more
+than a description of it. So that one is a recording.
+
+It was not worth paying ten times, and the proof is what happened when the
+repository tried: nine family recordings sat in the tree as placeholders for
+months, and when they were written they all showed the *same* thing — a
+pre-flight stopping on an unadopted repo, which is setup's arc, not the
+family's. Nine copies of the quick start, filed under ten families.
+
+A screenshot's job on a family page is to show the shape of a run: what comes
+back, and how it is laid out. That does not need a capture. It needs someone
+to write down what a typical run looks like, which is a text file anyone can
+fix in a pull request without booking a recording session.
+
+## What the check can prove, and what it cannot
+
+[`render-screenshot.sh`](../../tools/dev/render-screenshot.sh) is
+deterministic: the same `.txt` produces the same `.svg`, byte for byte, on any
+machine. So
+[`check-quickstart-recording.py`](../../tools/dev/check-quickstart-recording.py)
+can prove that **every committed `.svg` still matches its transcript**. Edit
+one without re-rendering and the build fails.
+
+It **cannot** prove that a transcript still matches what the skill prints
+today. Nothing here can. That is the real cost of authoring rather than
+capturing, and it is accepted deliberately: a screenshot on these pages is
+there to show the shape of a run, not to serve as a test oracle. Write
+transcripts to be robust to cosmetic change and the gap stays small — see the
+conventions below.
+
+## Adding a screenshot
+
+```bash
+$EDITOR assets/quickstart/families/pairing/self-review.txt
+tools/dev/render-screenshot.sh assets/quickstart/families/pairing/self-review.txt
+```
+
+Then embed the `.svg` in that family's README under *Try these first*, with
+alt text describing what the run shows. `--all` re-renders everything and
+`--check` fails on anything stale, which is what runs on commit.
+
+Colour comes from the line itself, so a transcript stays something you read as
+a terminal rather than as markup:
+
+| Line | Rendered |
+|---|---|
+| starts with `> ` | the command, in the prompt colour |
+| starts with `✓` | green |
+| starts with `⚠` | amber |
+| starts with `✗` | red |
+| ALL CAPS on its own | a section label, in amber |
+| anything else | ordinary output |
+
+## Conventions
+
+- **Under ~20 lines.** A screenshot shows a shape. A reader who wants the
+ whole output runs the command.
+- **No version strings, no dates, no counts a minor change would move.** The
+ check cannot tell you a transcript has gone stale, so write ones that do not
+ go stale easily. "reviewed 4 changed files" is fine; "74 skills" is a number
+ that will be wrong.
+- **Nothing secret in frame** — tokens, private repository names, reporter
+ addresses. These files are *text*: anything in them is greppable in the
+ repository forever. For `magpie-security` in particular, invent the tracker
+ numbers and use a scratch tracker name; a real transcript would put an
+ embargoed report in a public repository permanently.
+- **Say what the skill does not do.** Most of these skills are read-only or
+ draft-then-confirm, and that is the single most reassuring thing a first-time
+ reader can see. Several transcripts end on it.
+- **Keep the ASF header.** Every `.txt` opens with the licence header as a
+ block of `#` comments, exactly like any other authored file here, and the
+ renderer strips it before drawing — so it satisfies Apache RAT without being
+ rendered into the picture and without needing a `.rat-excludes` entry. The
+ one constraint it buys: a transcript cannot open with a literal `#` line.
+- **Never hand-edit an `.svg`.** It is generated. Edit the `.txt` and
+ re-render.
+- **Under 1536 KB**, enforced on commit. Nothing generated here comes close;
+ the cap catches a transcript that grew without anyone noticing.
+
+## The animated runs
+
+[`tools/dev/render-wizard.py`](../../tools/dev/render-wizard.py) writes them
+all:
+
+```bash
+python3 tools/dev/render-wizard.py # write
+python3 tools/dev/render-wizard.py --check # fail on drift
+```
+
+`magpie-setup.svg` is one fixed arc — the agent detected, the families picked,
+the install commands, then the secure-agent setup applying the sandbox, the
+clean-environment wrapper, the hooks and the status line. Edit
+`setup_script()` to change it. The per-family runs under `wizard/` have no
+script to edit: they are derived from each family's skills' `requires_config:`
+frontmatter, so a family that gains a required file gains a frame by itself.
+
+Animation is SMIL — one `<animate>` on opacity per line, all sharing one
+duration so the sequence loops as a unit. A viewer that does not animate SVG
+shows the first frame, which is the command about to be typed.
+
+**Nothing in this repository is captured.** `magpie-setup.svg` was the last
+recording, made with `asciinema` and `svg-term-cli`. It was also wrong: it
+opened with the marketplace install, which became a prerequisite with its own
+page, and fixing that needed a terminal, a scratch project and a human — which
+is why it stayed wrong for as long as it did. The recorder is retired and the
+Node dependency with it.
+
+What that costs is the same thing the authored screenshots cost, and it is
+worth restating here: a generated animation cannot prove the program still
+behaves the way the picture says. It shows the *shape* of a run — what is
+asked, in what order, and what is written where — and every embed says so.
+
+## Why SVG
+
+The output is text, which is most of the argument:
+
+- it goes through review as a diff, not as an opaque binary blob;
+- it carries its own Apache licence header, so RAT is satisfied by the file
+ itself;
+- it needs no player and no external host;
+- it stays sharp at any width;
+- it costs a fraction of what a terminal GIF or a PNG set would add to every
+ source release.
+
+The tradeoff for the one animated file: a renderer that does not run SVG
+animation shows the first frame rather than the loop. That is an acceptable
+still, and GitHub — where these pages are actually read — animates it. The
+authored screenshots are static, so they have no such tradeoff.
diff --git a/docs-assets/quickstart/demo.svg b/docs-assets/quickstart/demo.svg
new file mode 100644
index 0000000..b21a444
--- /dev/null
+++ b/docs-assets/quickstart/demo.svg
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 705 760"
+ width="705" height="760" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated walk-through: Magpie installed from the marketplace, the agent sandboxed and guarded, privacy configured, then a security report imported, triaged, fixed and published as a CVE">
+ <title>One security report, start to finish</title>
+ <desc>Illustrative animation of the security lifecycle end to end. Not a recording.</desc>
+ <rect width="705" height="760" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="705" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="705" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /plugin marketplace add apache/magpie<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="104" fill="#7f9f7f" opacity="0"> ✓ apache-magpie added - 12 plugins<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0388;0.0398;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="152" fill="#8abeb7" opacity="0">> /magpie-setup<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0776;0.0786;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#7f9f7f" opacity="0"> ✓ detected example-org/example-app - configuration written<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1163;0.1173;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="224" fill="#8abeb7" opacity="0">> /magpie-setup:isolated-setup-install<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1551;0.1561;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="248" fill="#7f9f7f" opacity="0"> ✓ sandbox, clean env, guard hook - 3 settings changes, 1 sudo<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1939;0.1949;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="296" fill="#8abeb7" opacity="0">> /magpie-setup:privacy-llm<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2327;0.2337;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#7f9f7f" opacity="0"> ✓ gate passed - third-party names redacted: N-a3f9d2, E-7c1b04<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2714;0.2724;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="368" fill="#8abeb7" opacity="0">> /magpie-security:issue-import<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3102;0.3112;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#c5c8c6" opacity="0"> Opened #41 and #42 in example-app-security<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3490;0.3500;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="440" fill="#8abeb7" opacity="0">> /magpie-security:issue-triage<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3878;0.3888;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="464" fill="#c5c8c6" opacity="0"> #41 path traversal in archive extraction high<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4265;0.4275;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="488" fill="#8a8f94" opacity="0"> #42 not a vulnerability - reported behaviour is intended<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4653;0.4663;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="536" fill="#8abeb7" opacity="0">> /magpie-security:issue-fix 41<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5041;0.5051;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="560" fill="#c5c8c6" opacity="0"> Fix drafted, PR opened - title and body carry no CVE,<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5429;0.5439;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="584" fill="#8a8f94" opacity="0"> no security wording, and no link back to the tracker.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5816;0.5826;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="632" fill="#8abeb7" opacity="0">> /magpie-security:cve-allocate 41<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6204;0.6214;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="656" fill="#7f9f7f" opacity="0"> ✓ CVE-2026-XXXXX published, advisory drafted<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6592;0.6602;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="704" fill="#d8a657" opacity="0"> Every message that leaves the project was drafted here<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6980;0.6990;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="728" fill="#d8a657" opacity="0"> and sent by a person. Nothing was posted unattended.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.7367;0.7377;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <rect x="26" y="715" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/contributor-growth/activity-sweep.svg b/docs-assets/quickstart/families/contributor-growth/activity-sweep.svg
new file mode 100644
index 0000000..8faa5bb
--- /dev/null
+++ b/docs-assets/quickstart/families/contributor-growth/activity-sweep.svg
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 845 430"
+ width="845" height="430" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: activity-sweep">
+ <title>activity-sweep</title>
+ <rect width="845" height="430" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="845" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="845" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-contributor-growth:activity-sweep alex-dev 90d</text>
+ <text x="28" y="136" fill="#c5c8c6"> GitHub activity, last 90 days</text>
+ <text x="28" y="188" fill="#c5c8c6"> Authored 7 PRs, 6 merged, 1 open</text>
+ <text x="28" y="214" fill="#c5c8c6"> Reviewed 19 PRs, 14 with substantive comments</text>
+ <text x="28" y="240" fill="#c5c8c6"> Issues 11 triaged, 3 reproduced</text>
+ <text x="28" y="266" fill="#c5c8c6"> Comments 52 across issues and PRs</text>
+ <text x="28" y="318" fill="#c5c8c6"> Busiest area providers/aws</text>
+ <text x="28" y="370" fill="#c5c8c6"> This is what GitHub can see. Mailing lists, release votes and mentoring</text>
+ <text x="28" y="396" fill="#c5c8c6"> are not in here, and for most candidates they are half the picture.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/contributor-growth/activity-sweep.txt b/docs-assets/quickstart/families/contributor-growth/activity-sweep.txt
new file mode 100644
index 0000000..b444c36
--- /dev/null
+++ b/docs-assets/quickstart/families/contributor-growth/activity-sweep.txt
@@ -0,0 +1,33 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-contributor-growth:activity-sweep alex-dev 90d
+
+ GitHub activity, last 90 days
+
+ Authored 7 PRs, 6 merged, 1 open
+ Reviewed 19 PRs, 14 with substantive comments
+ Issues 11 triaged, 3 reproduced
+ Comments 52 across issues and PRs
+
+ Busiest area providers/aws
+
+ This is what GitHub can see. Mailing lists, release votes and mentoring
+ are not in here, and for most candidates they are half the picture.
diff --git a/docs-assets/quickstart/families/contributor-growth/committer-onboarding.svg b/docs-assets/quickstart/families/contributor-growth/committer-onboarding.svg
new file mode 100644
index 0000000..a9f8058
--- /dev/null
+++ b/docs-assets/quickstart/families/contributor-growth/committer-onboarding.svg
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 812 456"
+ width="812" height="456" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: committer-onboarding">
+ <title>committer-onboarding</title>
+ <rect width="812" height="456" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="812" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="812" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-contributor-growth:committer-onboarding</text>
+ <text x="28" y="136" fill="#c5c8c6"> The vote on @kasia-w passed. 8 steps to close it out.</text>
+ <text x="28" y="188" fill="#7f9f7f"> ✓ ICLA on file</text>
+ <text x="28" y="214" fill="#7f9f7f"> ✓ Apache account requested</text>
+ <text x="28" y="240" fill="#d8a657"> ⚠ karma grant needs a PMC chair</text>
+ <text x="28" y="266" fill="#d8a657"> ⚠ private@ notification needs a PMC chair</text>
+ <text x="28" y="292" fill="#c5c8c6"> welcome announcement drafted, not sent</text>
+ <text x="28" y="344" fill="#c5c8c6"> Podling or TLP changes two of these steps; this project is a TLP, so</text>
+ <text x="28" y="370" fill="#c5c8c6"> the secretary request is skipped.</text>
+ <text x="28" y="422" fill="#c5c8c6"> Walk the remaining steps one at a time? [Y/n]</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/contributor-growth/committer-onboarding.txt b/docs-assets/quickstart/families/contributor-growth/committer-onboarding.txt
new file mode 100644
index 0000000..9bca8db
--- /dev/null
+++ b/docs-assets/quickstart/families/contributor-growth/committer-onboarding.txt
@@ -0,0 +1,34 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-contributor-growth:committer-onboarding
+
+ The vote on @kasia-w passed. 8 steps to close it out.
+
+ ✓ ICLA on file
+ ✓ Apache account requested
+ ⚠ karma grant needs a PMC chair
+ ⚠ private@ notification needs a PMC chair
+ welcome announcement drafted, not sent
+
+ Podling or TLP changes two of these steps; this project is a TLP, so
+ the secretary request is skipped.
+
+ Walk the remaining steps one at a time? [Y/n]
diff --git a/docs-assets/quickstart/families/contributor-growth/nomination.svg b/docs-assets/quickstart/families/contributor-growth/nomination.svg
new file mode 100644
index 0000000..9125994
--- /dev/null
+++ b/docs-assets/quickstart/families/contributor-growth/nomination.svg
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 802 456"
+ width="802" height="456" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: nomination">
+ <title>nomination</title>
+ <rect width="802" height="456" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="802" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="802" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-contributor-growth:nomination</text>
+ <text x="28" y="136" fill="#c5c8c6"> Building the nomination brief</text>
+ <text x="28" y="188" fill="#c5c8c6"> On GitHub, last 12 months</text>
+ <text x="28" y="214" fill="#c5c8c6"> 24 merged PRs across 4 areas, 61 reviews given, 38 issues triaged</text>
+ <text x="28" y="240" fill="#c5c8c6"> steady since the spring, not a single burst</text>
+ <text x="28" y="292" fill="#c5c8c6"> Not visible from here - you fill these in</text>
+ <text x="28" y="318" fill="#c5c8c6"> mailing-list participation, release verification, mentoring</text>
+ <text x="28" y="370" fill="#c5c8c6"> Drafted the [DISCUSS] thread and the private nomination summary.</text>
+ <text x="28" y="422" fill="#c5c8c6"> Neither is sent. A nomination is the PMC's decision, not a score.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/contributor-growth/nomination.txt b/docs-assets/quickstart/families/contributor-growth/nomination.txt
new file mode 100644
index 0000000..e1f4fb2
--- /dev/null
+++ b/docs-assets/quickstart/families/contributor-growth/nomination.txt
@@ -0,0 +1,34 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-contributor-growth:nomination
+
+ Building the nomination brief
+
+ On GitHub, last 12 months
+ 24 merged PRs across 4 areas, 61 reviews given, 38 issues triaged
+ steady since the spring, not a single burst
+
+ Not visible from here - you fill these in
+ mailing-list participation, release verification, mentoring
+
+ Drafted the [DISCUSS] thread and the private nomination summary.
+
+ Neither is sent. A nomination is the PMC's decision, not a score.
diff --git a/docs-assets/quickstart/families/issue/deduplicate.svg b/docs-assets/quickstart/families/issue/deduplicate.svg
new file mode 100644
index 0000000..4b7ae32
--- /dev/null
+++ b/docs-assets/quickstart/families/issue/deduplicate.svg
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 834 482"
+ width="834" height="482" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: deduplicate">
+ <title>deduplicate</title>
+ <rect width="834" height="482" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="834" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="834" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-issue:deduplicate</text>
+ <text x="28" y="136" fill="#c5c8c6"> Scanning 140 open issues for duplicate root causes</text>
+ <text x="28" y="188" fill="#d8a657"> STRONG</text>
+ <text x="28" y="214" fill="#c5c8c6"> #3324 and #3298 same traceback, same config key</text>
+ <text x="28" y="266" fill="#d8a657"> WORTH A LOOK</text>
+ <text x="28" y="292" fill="#c5c8c6"> #3201 and #3155 both describe a hang on shutdown, different paths</text>
+ <text x="28" y="344" fill="#c5c8c6"> Proposed for the strong match: keep #3298, close #3324 as a duplicate,</text>
+ <text x="28" y="370" fill="#c5c8c6"> and carry the second reporter's extra detail into the kept issue so no</text>
+ <text x="28" y="396" fill="#c5c8c6"> one loses credit.</text>
+ <text x="28" y="448" fill="#c5c8c6"> Apply? [y/N]</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/issue/deduplicate.txt b/docs-assets/quickstart/families/issue/deduplicate.txt
new file mode 100644
index 0000000..870e840
--- /dev/null
+++ b/docs-assets/quickstart/families/issue/deduplicate.txt
@@ -0,0 +1,35 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-issue:deduplicate
+
+ Scanning 140 open issues for duplicate root causes
+
+ STRONG
+ #3324 and #3298 same traceback, same config key
+
+ WORTH A LOOK
+ #3201 and #3155 both describe a hang on shutdown, different paths
+
+ Proposed for the strong match: keep #3298, close #3324 as a duplicate,
+ and carry the second reporter's extra detail into the kept issue so no
+ one loses credit.
+
+ Apply? [y/N]
diff --git a/docs-assets/quickstart/families/issue/reproducer.svg b/docs-assets/quickstart/families/issue/reproducer.svg
new file mode 100644
index 0000000..e543293
--- /dev/null
+++ b/docs-assets/quickstart/families/issue/reproducer.svg
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 780 430"
+ width="780" height="430" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: reproducer">
+ <title>reproducer</title>
+ <rect width="780" height="430" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="780" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="780" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-issue:reproducer 3312</text>
+ <text x="28" y="136" fill="#c5c8c6"> Extracting a runnable case from the report</text>
+ <text x="28" y="188" fill="#c5c8c6"> Found config snippet, stack trace, version pin</text>
+ <text x="28" y="214" fill="#c5c8c6"> Missing the platform - assuming linux from the traceback paths</text>
+ <text x="28" y="266" fill="#c5c8c6"> Wrote a probe: 11 lines, stdlib only, no network</text>
+ <text x="28" y="318" fill="#7f9f7f"> ✓ reproduced - the same KeyError on line 88</text>
+ <text x="28" y="370" fill="#c5c8c6"> The report is actionable. The probe is attached to the issue as a</text>
+ <text x="28" y="396" fill="#c5c8c6"> comment for you to review before anything is posted.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/issue/reproducer.txt b/docs-assets/quickstart/families/issue/reproducer.txt
new file mode 100644
index 0000000..e7b6a2a
--- /dev/null
+++ b/docs-assets/quickstart/families/issue/reproducer.txt
@@ -0,0 +1,33 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-issue:reproducer 3312
+
+ Extracting a runnable case from the report
+
+ Found config snippet, stack trace, version pin
+ Missing the platform - assuming linux from the traceback paths
+
+ Wrote a probe: 11 lines, stdlib only, no network
+
+ ✓ reproduced - the same KeyError on line 88
+
+ The report is actionable. The probe is attached to the issue as a
+ comment for you to review before anything is posted.
diff --git a/docs-assets/quickstart/families/issue/triage.svg b/docs-assets/quickstart/families/issue/triage.svg
new file mode 100644
index 0000000..b942b5c
--- /dev/null
+++ b/docs-assets/quickstart/families/issue/triage.svg
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 780 430"
+ width="780" height="430" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: triage">
+ <title>triage</title>
+ <rect width="780" height="430" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="780" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="780" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-issue:triage</text>
+ <text x="28" y="136" fill="#c5c8c6"> 23 issues carry needs-triage</text>
+ <text x="28" y="188" fill="#c5c8c6"> #3312 crash on startup with an empty config file</text>
+ <text x="28" y="214" fill="#c5c8c6"> bug - reproducible from the report, has a stack trace</text>
+ <text x="28" y="240" fill="#c5c8c6"> #3319 "add a dark mode"</text>
+ <text x="28" y="266" fill="#c5c8c6"> feature request - no design, routing to discussion</text>
+ <text x="28" y="292" fill="#c5c8c6"> #3321 "it does not work"</text>
+ <text x="28" y="318" fill="#c5c8c6"> needs info - drafted a reply asking for version and steps</text>
+ <text x="28" y="344" fill="#c5c8c6"> #3324 duplicate of #3298, same root cause</text>
+ <text x="28" y="396" fill="#c5c8c6"> Labels, replies and closes are all proposals. Confirm each? [Y/n]</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/issue/triage.txt b/docs-assets/quickstart/families/issue/triage.txt
new file mode 100644
index 0000000..7b48bcd
--- /dev/null
+++ b/docs-assets/quickstart/families/issue/triage.txt
@@ -0,0 +1,33 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-issue:triage
+
+ 23 issues carry needs-triage
+
+ #3312 crash on startup with an empty config file
+ bug - reproducible from the report, has a stack trace
+ #3319 "add a dark mode"
+ feature request - no design, routing to discussion
+ #3321 "it does not work"
+ needs info - drafted a reply asking for version and steps
+ #3324 duplicate of #3298, same root cause
+
+ Labels, replies and closes are all proposals. Confirm each? [Y/n]
diff --git a/docs-assets/quickstart/families/mentoring/good-first-issue-sweep.svg b/docs-assets/quickstart/families/mentoring/good-first-issue-sweep.svg
new file mode 100644
index 0000000..c4df88d
--- /dev/null
+++ b/docs-assets/quickstart/families/mentoring/good-first-issue-sweep.svg
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 823 456"
+ width="823" height="456" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: good-first-issue-sweep">
+ <title>good-first-issue-sweep</title>
+ <rect width="823" height="456" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="823" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="823" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-mentoring:good-first-issue-sweep</text>
+ <text x="28" y="136" fill="#c5c8c6"> Looking for issues a newcomer could actually finish</text>
+ <text x="28" y="188" fill="#d8a657"> READY</text>
+ <text x="28" y="214" fill="#c5c8c6"> #2890 add a unit test for the retry helper</text>
+ <text x="28" y="240" fill="#c5c8c6"> scoped, has a pointer to the file, no design decision left</text>
+ <text x="28" y="266" fill="#c5c8c6"> #2912 fix a broken link in the install docs</text>
+ <text x="28" y="318" fill="#c5c8c6"> NOT READY, BUT CLOSE</text>
+ <text x="28" y="344" fill="#c5c8c6"> #2877 needs one sentence saying where the code lives</text>
+ <text x="28" y="370" fill="#c5c8c6"> #2901 labelled good first issue, but the fix needs a schema change</text>
+ <text x="28" y="422" fill="#c5c8c6"> Drafted the label changes and the missing-context comments. Confirm?</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/mentoring/good-first-issue-sweep.txt b/docs-assets/quickstart/families/mentoring/good-first-issue-sweep.txt
new file mode 100644
index 0000000..210509e
--- /dev/null
+++ b/docs-assets/quickstart/families/mentoring/good-first-issue-sweep.txt
@@ -0,0 +1,34 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-mentoring:good-first-issue-sweep
+
+ Looking for issues a newcomer could actually finish
+
+ READY
+ #2890 add a unit test for the retry helper
+ scoped, has a pointer to the file, no design decision left
+ #2912 fix a broken link in the install docs
+
+ NOT READY, BUT CLOSE
+ #2877 needs one sentence saying where the code lives
+ #2901 labelled good first issue, but the fix needs a schema change
+
+ Drafted the label changes and the missing-context comments. Confirm?
diff --git a/docs-assets/quickstart/families/mentoring/newcomer-issue-explainer.svg b/docs-assets/quickstart/families/mentoring/newcomer-issue-explainer.svg
new file mode 100644
index 0000000..5a5b110
--- /dev/null
+++ b/docs-assets/quickstart/families/mentoring/newcomer-issue-explainer.svg
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 834 404"
+ width="834" height="404" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: newcomer-issue-explainer">
+ <title>newcomer-issue-explainer</title>
+ <rect width="834" height="404" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="834" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="834" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-mentoring:newcomer-issue-explainer 8144</text>
+ <text x="28" y="136" fill="#c5c8c6"> Reading the issue, then the code it points at</text>
+ <text x="28" y="188" fill="#c5c8c6"> What breaks the parser drops the last field on a trailing comma</text>
+ <text x="28" y="214" fill="#c5c8c6"> Where two files - the tokenizer and one test</text>
+ <text x="28" y="240" fill="#c5c8c6"> How to check one test, named in the comment, runs in under a second</text>
+ <text x="28" y="292" fill="#c5c8c6"> Drafted a comment in a teaching register: what to change and why, not</text>
+ <text x="28" y="318" fill="#c5c8c6"> what to type. It asks nothing of the newcomer they cannot answer.</text>
+ <text x="28" y="370" fill="#c5c8c6"> Post it? [y/N]</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/mentoring/newcomer-issue-explainer.txt b/docs-assets/quickstart/families/mentoring/newcomer-issue-explainer.txt
new file mode 100644
index 0000000..e8c7644
--- /dev/null
+++ b/docs-assets/quickstart/families/mentoring/newcomer-issue-explainer.txt
@@ -0,0 +1,32 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-mentoring:newcomer-issue-explainer 8144
+
+ Reading the issue, then the code it points at
+
+ What breaks the parser drops the last field on a trailing comma
+ Where two files - the tokenizer and one test
+ How to check one test, named in the comment, runs in under a second
+
+ Drafted a comment in a teaching register: what to change and why, not
+ what to type. It asks nothing of the newcomer they cannot answer.
+
+ Post it? [y/N]
diff --git a/docs-assets/quickstart/families/mentoring/welcome.svg b/docs-assets/quickstart/families/mentoring/welcome.svg
new file mode 100644
index 0000000..51d9c81
--- /dev/null
+++ b/docs-assets/quickstart/families/mentoring/welcome.svg
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 834 430"
+ width="834" height="430" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: welcome">
+ <title>welcome</title>
+ <rect width="834" height="430" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="834" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="834" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-mentoring:welcome</text>
+ <text x="28" y="136" fill="#c5c8c6"> 3 first-time contributors opened a PR today</text>
+ <text x="28" y="188" fill="#c5c8c6"> #1421 alex-dev first PR to this project</text>
+ <text x="28" y="214" fill="#c5c8c6"> #1425 sam-builds first PR to this project</text>
+ <text x="28" y="240" fill="#c5c8c6"> #1427 jo-writes first PR, docs only</text>
+ <text x="28" y="292" fill="#c5c8c6"> Drafted a welcome for each: what happens next, roughly how long review</text>
+ <text x="28" y="318" fill="#c5c8c6"> takes, and who to ask if it stalls. No template stamping - each one</text>
+ <text x="28" y="344" fill="#c5c8c6"> names what the PR actually changed.</text>
+ <text x="28" y="396" fill="#c5c8c6"> Review the three drafts before anything is posted? [Y/n]</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/mentoring/welcome.txt b/docs-assets/quickstart/families/mentoring/welcome.txt
new file mode 100644
index 0000000..705e068
--- /dev/null
+++ b/docs-assets/quickstart/families/mentoring/welcome.txt
@@ -0,0 +1,33 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-mentoring:welcome
+
+ 3 first-time contributors opened a PR today
+
+ #1421 alex-dev first PR to this project
+ #1425 sam-builds first PR to this project
+ #1427 jo-writes first PR, docs only
+
+ Drafted a welcome for each: what happens next, roughly how long review
+ takes, and who to ask if it stalls. No template stamping - each one
+ names what the PR actually changed.
+
+ Review the three drafts before anything is posted? [Y/n]
diff --git a/docs-assets/quickstart/families/pairing/multi-agent-review.svg b/docs-assets/quickstart/families/pairing/multi-agent-review.svg
new file mode 100644
index 0000000..0f03923
--- /dev/null
+++ b/docs-assets/quickstart/families/pairing/multi-agent-review.svg
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 845 534"
+ width="845" height="534" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: multi-agent-review">
+ <title>multi-agent-review</title>
+ <rect width="845" height="534" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="845" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="845" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-pairing:multi-agent-review</text>
+ <text x="28" y="136" fill="#c5c8c6"> Two independent reads of the same diff</text>
+ <text x="28" y="188" fill="#d8a657"> BOTH FOUND</text>
+ <text x="28" y="214" fill="#c5c8c6"> src/queue.py:142 the retry loop can spin forever on a 5xx</text>
+ <text x="28" y="266" fill="#d8a657"> ONLY THE FIRST READ</text>
+ <text x="28" y="292" fill="#c5c8c6"> src/queue.py:88 the lock is held across a network call</text>
+ <text x="28" y="344" fill="#d8a657"> ONLY THE SECOND READ</text>
+ <text x="28" y="370" fill="#c5c8c6"> tests/test_queue.py:30 the test passes if the function does nothing</text>
+ <text x="28" y="422" fill="#c5c8c6"> Disagreement is the point: a finding one read missed is worth more than</text>
+ <text x="28" y="448" fill="#c5c8c6"> a finding both agreed on.</text>
+ <text x="28" y="500" fill="#c5c8c6"> Nothing was posted.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/pairing/multi-agent-review.txt b/docs-assets/quickstart/families/pairing/multi-agent-review.txt
new file mode 100644
index 0000000..1ae5493
--- /dev/null
+++ b/docs-assets/quickstart/families/pairing/multi-agent-review.txt
@@ -0,0 +1,37 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-pairing:multi-agent-review
+
+ Two independent reads of the same diff
+
+ BOTH FOUND
+ src/queue.py:142 the retry loop can spin forever on a 5xx
+
+ ONLY THE FIRST READ
+ src/queue.py:88 the lock is held across a network call
+
+ ONLY THE SECOND READ
+ tests/test_queue.py:30 the test passes if the function does nothing
+
+ Disagreement is the point: a finding one read missed is worth more than
+ a finding both agreed on.
+
+ Nothing was posted.
diff --git a/docs-assets/quickstart/families/pairing/self-review.svg b/docs-assets/quickstart/families/pairing/self-review.svg
new file mode 100644
index 0000000..c9a4ec4
--- /dev/null
+++ b/docs-assets/quickstart/families/pairing/self-review.svg
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 791 404"
+ width="791" height="404" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: self-review">
+ <title>self-review</title>
+ <rect width="791" height="404" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="791" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="791" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-pairing:self-review</text>
+ <text x="28" y="136" fill="#c5c8c6"> Reviewing 4 changed files against origin/main</text>
+ <text x="28" y="188" fill="#d8a657"> BLOCKING</text>
+ <text x="28" y="214" fill="#c5c8c6"> src/cache.py:88 unchecked dict access on a caller-supplied key</text>
+ <text x="28" y="266" fill="#d8a657"> NON-BLOCKING</text>
+ <text x="28" y="292" fill="#c5c8c6"> src/cache.py:12 module docstring omits the eviction policy</text>
+ <text x="28" y="318" fill="#c5c8c6"> tests/test_cache.py:40 asserts the mock, not the behaviour</text>
+ <text x="28" y="370" fill="#c5c8c6"> Nothing was sent, posted, or merged - the report is the output.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/pairing/self-review.txt b/docs-assets/quickstart/families/pairing/self-review.txt
new file mode 100644
index 0000000..89ec9f4
--- /dev/null
+++ b/docs-assets/quickstart/families/pairing/self-review.txt
@@ -0,0 +1,32 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-pairing:self-review
+
+ Reviewing 4 changed files against origin/main
+
+ BLOCKING
+ src/cache.py:88 unchecked dict access on a caller-supplied key
+
+ NON-BLOCKING
+ src/cache.py:12 module docstring omits the eviction policy
+ tests/test_cache.py:40 asserts the mock, not the behaviour
+
+ Nothing was sent, posted, or merged - the report is the output.
diff --git a/docs-assets/quickstart/families/pr-management/stats.svg b/docs-assets/quickstart/families/pr-management/stats.svg
new file mode 100644
index 0000000..ffbd25c
--- /dev/null
+++ b/docs-assets/quickstart/families/pr-management/stats.svg
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 834 534"
+ width="834" height="534" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: stats">
+ <title>stats</title>
+ <rect width="834" height="534" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="834" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="834" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-pr-management:stats</text>
+ <text x="28" y="136" fill="#c5c8c6"> Open PR backlog</text>
+ <text x="28" y="188" fill="#c5c8c6"> Health FAIR - the queue is growing slowly</text>
+ <text x="28" y="240" fill="#c5c8c6"> This week opened 19 closed 14 net +5</text>
+ <text x="28" y="266" fill="#c5c8c6"> Last week opened 15 closed 21 net -6</text>
+ <text x="28" y="318" fill="#c5c8c6"> Where the pressure is</text>
+ <text x="28" y="344" fill="#c5c8c6"> scheduler 11 open, oldest 62 days</text>
+ <text x="28" y="370" fill="#c5c8c6"> providers 9 open, oldest 21 days</text>
+ <text x="28" y="396" fill="#c5c8c6"> docs 4 open, oldest 6 days</text>
+ <text x="28" y="448" fill="#c5c8c6"> Triage funnel 12 untriaged -> 17 ready for review -> 9 in review</text>
+ <text x="28" y="500" fill="#c5c8c6"> Start with the scheduler queue: it is both the largest and the oldest.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/pr-management/stats.txt b/docs-assets/quickstart/families/pr-management/stats.txt
new file mode 100644
index 0000000..8b35f20
--- /dev/null
+++ b/docs-assets/quickstart/families/pr-management/stats.txt
@@ -0,0 +1,37 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-pr-management:stats
+
+ Open PR backlog
+
+ Health FAIR - the queue is growing slowly
+
+ This week opened 19 closed 14 net +5
+ Last week opened 15 closed 21 net -6
+
+ Where the pressure is
+ scheduler 11 open, oldest 62 days
+ providers 9 open, oldest 21 days
+ docs 4 open, oldest 6 days
+
+ Triage funnel 12 untriaged -> 17 ready for review -> 9 in review
+
+ Start with the scheduler queue: it is both the largest and the oldest.
diff --git a/docs-assets/quickstart/families/pr-management/triage.svg b/docs-assets/quickstart/families/pr-management/triage.svg
new file mode 100644
index 0000000..41a3032
--- /dev/null
+++ b/docs-assets/quickstart/families/pr-management/triage.svg
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 802 456"
+ width="802" height="456" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: triage">
+ <title>triage</title>
+ <rect width="802" height="456" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="802" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="802" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-pr-management:triage</text>
+ <text x="28" y="136" fill="#c5c8c6"> 38 open PRs, 12 untriaged</text>
+ <text x="28" y="188" fill="#c5c8c6"> #1421 first-time contributor, CI green, no reviewer</text>
+ <text x="28" y="214" fill="#c5c8c6"> -> mark ready for maintainer review</text>
+ <text x="28" y="240" fill="#c5c8c6"> #1388 draft for 3 weeks, no commits since</text>
+ <text x="28" y="266" fill="#c5c8c6"> -> comment asking whether it is still active</text>
+ <text x="28" y="292" fill="#c5c8c6"> #1402 branch 200 commits behind, conflicts</text>
+ <text x="28" y="318" fill="#c5c8c6"> -> ask the author to rebase</text>
+ <text x="28" y="344" fill="#c5c8c6"> #1377 bot-authored dependency bump, CI green</text>
+ <text x="28" y="370" fill="#c5c8c6"> -> promote out of draft</text>
+ <text x="28" y="422" fill="#c5c8c6"> Each action needs your confirmation. Walk them one at a time? [Y/n]</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/pr-management/triage.txt b/docs-assets/quickstart/families/pr-management/triage.txt
new file mode 100644
index 0000000..3726d9b
--- /dev/null
+++ b/docs-assets/quickstart/families/pr-management/triage.txt
@@ -0,0 +1,34 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-pr-management:triage
+
+ 38 open PRs, 12 untriaged
+
+ #1421 first-time contributor, CI green, no reviewer
+ -> mark ready for maintainer review
+ #1388 draft for 3 weeks, no commits since
+ -> comment asking whether it is still active
+ #1402 branch 200 commits behind, conflicts
+ -> ask the author to rebase
+ #1377 bot-authored dependency bump, CI green
+ -> promote out of draft
+
+ Each action needs your confirmation. Walk them one at a time? [Y/n]
diff --git a/docs-assets/quickstart/families/release-management/prepare.svg b/docs-assets/quickstart/families/release-management/prepare.svg
new file mode 100644
index 0000000..d442ed2
--- /dev/null
+++ b/docs-assets/quickstart/families/release-management/prepare.svg
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 845 430"
+ width="845" height="430" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: prepare">
+ <title>prepare</title>
+ <rect width="845" height="430" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="845" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="845" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-release-management:prepare 1.4.0</text>
+ <text x="28" y="136" fill="#c5c8c6"> Reading the release train and the release-management config</text>
+ <text x="28" y="188" fill="#c5c8c6"> Drafted, nothing filed:</text>
+ <text x="28" y="240" fill="#c5c8c6"> Planning issue "Release 1.4.0" - the 14-step checklist, the RM named,</text>
+ <text x="28" y="266" fill="#c5c8c6"> the target date from the train</text>
+ <text x="28" y="292" fill="#c5c8c6"> Prep PR version bump across 4 files, changelog assembled from</text>
+ <text x="28" y="318" fill="#c5c8c6"> the merged PRs since 1.3.0</text>
+ <text x="28" y="370" fill="#c5c8c6"> Review both, then say the word. The agent never marks a PR ready and</text>
+ <text x="28" y="396" fill="#c5c8c6"> never merges one.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/release-management/prepare.txt b/docs-assets/quickstart/families/release-management/prepare.txt
new file mode 100644
index 0000000..a5eb926
--- /dev/null
+++ b/docs-assets/quickstart/families/release-management/prepare.txt
@@ -0,0 +1,33 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-release-management:prepare 1.4.0
+
+ Reading the release train and the release-management config
+
+ Drafted, nothing filed:
+
+ Planning issue "Release 1.4.0" - the 14-step checklist, the RM named,
+ the target date from the train
+ Prep PR version bump across 4 files, changelog assembled from
+ the merged PRs since 1.3.0
+
+ Review both, then say the word. The agent never marks a PR ready and
+ never merges one.
diff --git a/docs-assets/quickstart/families/release-management/verify-rc.svg b/docs-assets/quickstart/families/release-management/verify-rc.svg
new file mode 100644
index 0000000..517c10c
--- /dev/null
+++ b/docs-assets/quickstart/families/release-management/verify-rc.svg
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 877 456"
+ width="877" height="456" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: verify-rc">
+ <title>verify-rc</title>
+ <rect width="877" height="456" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="877" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="877" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-release-management:verify-rc 1.4.0-rc2</text>
+ <text x="28" y="136" fill="#c5c8c6"> Pre-flight on the staged candidate</text>
+ <text x="28" y="188" fill="#7f9f7f"> ✓ signatures every artefact verifies against the KEYS file</text>
+ <text x="28" y="214" fill="#7f9f7f"> ✓ checksums sha512 matches for all 6 artefacts</text>
+ <text x="28" y="240" fill="#7f9f7f"> ✓ licence headers Apache RAT reports no unapproved file</text>
+ <text x="28" y="266" fill="#7f9f7f"> ✓ NOTICE/LICENSE present, and NOTICE names every bundled dependency</text>
+ <text x="28" y="292" fill="#7f9f7f"> ✓ no binaries no .pyc, no __pycache__, no jar in the source archive</text>
+ <text x="28" y="318" fill="#d8a657"> ⚠ version strings docs/conf.py still reads 1.3.0</text>
+ <text x="28" y="370" fill="#d8a657"> PASS WITH WARNINGS</text>
+ <text x="28" y="422" fill="#c5c8c6"> Read-only. Nothing was posted to the planning issue.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/release-management/verify-rc.txt b/docs-assets/quickstart/families/release-management/verify-rc.txt
new file mode 100644
index 0000000..061146b
--- /dev/null
+++ b/docs-assets/quickstart/families/release-management/verify-rc.txt
@@ -0,0 +1,34 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-release-management:verify-rc 1.4.0-rc2
+
+ Pre-flight on the staged candidate
+
+ ✓ signatures every artefact verifies against the KEYS file
+ ✓ checksums sha512 matches for all 6 artefacts
+ ✓ licence headers Apache RAT reports no unapproved file
+ ✓ NOTICE/LICENSE present, and NOTICE names every bundled dependency
+ ✓ no binaries no .pyc, no __pycache__, no jar in the source archive
+ ⚠ version strings docs/conf.py still reads 1.3.0
+
+ PASS WITH WARNINGS
+
+ Read-only. Nothing was posted to the planning issue.
diff --git a/docs-assets/quickstart/families/release-management/vote-tally.svg b/docs-assets/quickstart/families/release-management/vote-tally.svg
new file mode 100644
index 0000000..ad40aeb
--- /dev/null
+++ b/docs-assets/quickstart/families/release-management/vote-tally.svg
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 791 482"
+ width="791" height="482" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: vote-tally">
+ <title>vote-tally</title>
+ <rect width="791" height="482" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="791" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="791" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-release-management:vote-tally 1.4.0-rc2</text>
+ <text x="28" y="136" fill="#c5c8c6"> Vote window closed 6 hours ago</text>
+ <text x="28" y="188" fill="#d8a657"> BINDING</text>
+ <text x="28" y="214" fill="#c5c8c6"> +1 three PMC members</text>
+ <text x="28" y="240" fill="#c5c8c6"> 0 one PMC member (did not verify)</text>
+ <text x="28" y="292" fill="#d8a657"> NON-BINDING</text>
+ <text x="28" y="318" fill="#c5c8c6"> +1 two contributors</text>
+ <text x="28" y="370" fill="#c5c8c6"> 3 binding +1, no -1: the vote passes.</text>
+ <text x="28" y="422" fill="#c5c8c6"> Drafted the [RESULT][VOTE] email and the vote-passed label change.</text>
+ <text x="28" y="448" fill="#c5c8c6"> Neither is sent or applied until you confirm.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/release-management/vote-tally.txt b/docs-assets/quickstart/families/release-management/vote-tally.txt
new file mode 100644
index 0000000..98a02e3
--- /dev/null
+++ b/docs-assets/quickstart/families/release-management/vote-tally.txt
@@ -0,0 +1,35 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-release-management:vote-tally 1.4.0-rc2
+
+ Vote window closed 6 hours ago
+
+ BINDING
+ +1 three PMC members
+ 0 one PMC member (did not verify)
+
+ NON-BINDING
+ +1 two contributors
+
+ 3 binding +1, no -1: the vote passes.
+
+ Drafted the [RESULT][VOTE] email and the vote-passed label change.
+ Neither is sent or applied until you confirm.
diff --git a/docs-assets/quickstart/families/repo-health/dependency-audit.svg b/docs-assets/quickstart/families/repo-health/dependency-audit.svg
new file mode 100644
index 0000000..3a73dcc
--- /dev/null
+++ b/docs-assets/quickstart/families/repo-health/dependency-audit.svg
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 834 482"
+ width="834" height="482" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: dependency-audit">
+ <title>dependency-audit</title>
+ <rect width="834" height="482" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="834" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="834" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-repo-health:dependency-audit</text>
+ <text x="28" y="136" fill="#c5c8c6"> Resolving the dependency tree</text>
+ <text x="28" y="188" fill="#d8a657"> OUTDATED WITH A FIX AVAILABLE</text>
+ <text x="28" y="214" fill="#c5c8c6"> requests 2 minor versions behind</text>
+ <text x="28" y="240" fill="#c5c8c6"> cryptography 1 major behind - the upgrade has a breaking API change</text>
+ <text x="28" y="292" fill="#d8a657"> UNMAINTAINED</text>
+ <text x="28" y="318" fill="#c5c8c6"> parsedatetime no release in 4 years, 2 open security reports</text>
+ <text x="28" y="370" fill="#d8a657"> PINNED BUT UNUSED</text>
+ <text x="28" y="396" fill="#c5c8c6"> six no import anywhere in the tree</text>
+ <text x="28" y="448" fill="#c5c8c6"> Read-only. Nothing was upgraded and no PR was opened.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/repo-health/dependency-audit.txt b/docs-assets/quickstart/families/repo-health/dependency-audit.txt
new file mode 100644
index 0000000..71cd78c
--- /dev/null
+++ b/docs-assets/quickstart/families/repo-health/dependency-audit.txt
@@ -0,0 +1,35 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-repo-health:dependency-audit
+
+ Resolving the dependency tree
+
+ OUTDATED WITH A FIX AVAILABLE
+ requests 2 minor versions behind
+ cryptography 1 major behind - the upgrade has a breaking API change
+
+ UNMAINTAINED
+ parsedatetime no release in 4 years, 2 open security reports
+
+ PINNED BUT UNUSED
+ six no import anywhere in the tree
+
+ Read-only. Nothing was upgraded and no PR was opened.
diff --git a/docs-assets/quickstart/families/repo-health/flaky-test-triage.svg b/docs-assets/quickstart/families/repo-health/flaky-test-triage.svg
new file mode 100644
index 0000000..54ffcaa
--- /dev/null
+++ b/docs-assets/quickstart/families/repo-health/flaky-test-triage.svg
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 845 482"
+ width="845" height="482" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: flaky-test-triage">
+ <title>flaky-test-triage</title>
+ <rect width="845" height="482" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="845" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="845" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-repo-health:flaky-test-triage</text>
+ <text x="28" y="136" fill="#c5c8c6"> Reading the last 200 CI runs on main</text>
+ <text x="28" y="188" fill="#d8a657"> FLAKY</text>
+ <text x="28" y="214" fill="#c5c8c6"> test_scheduler_timeout fails 1 run in 9, always on the slow runner</text>
+ <text x="28" y="240" fill="#c5c8c6"> test_upload_retry fails 1 run in 30, no pattern in the runner</text>
+ <text x="28" y="292" fill="#c5c8c6"> FAILING, NOT FLAKY</text>
+ <text x="28" y="318" fill="#c5c8c6"> test_config_defaults fails every run since the config change</text>
+ <text x="28" y="370" fill="#c5c8c6"> The last one is a real regression wearing a flake's clothes - it is in</text>
+ <text x="28" y="396" fill="#c5c8c6"> the same file as two genuine flakes, which is why nobody looked.</text>
+ <text x="28" y="448" fill="#c5c8c6"> Read-only.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/repo-health/flaky-test-triage.txt b/docs-assets/quickstart/families/repo-health/flaky-test-triage.txt
new file mode 100644
index 0000000..92999ad
--- /dev/null
+++ b/docs-assets/quickstart/families/repo-health/flaky-test-triage.txt
@@ -0,0 +1,35 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-repo-health:flaky-test-triage
+
+ Reading the last 200 CI runs on main
+
+ FLAKY
+ test_scheduler_timeout fails 1 run in 9, always on the slow runner
+ test_upload_retry fails 1 run in 30, no pattern in the runner
+
+ FAILING, NOT FLAKY
+ test_config_defaults fails every run since the config change
+
+ The last one is a real regression wearing a flake's clothes - it is in
+ the same file as two genuine flakes, which is why nobody looked.
+
+ Read-only.
diff --git a/docs-assets/quickstart/families/repo-health/workflow-security-audit.svg b/docs-assets/quickstart/families/repo-health/workflow-security-audit.svg
new file mode 100644
index 0000000..58acbb7
--- /dev/null
+++ b/docs-assets/quickstart/families/repo-health/workflow-security-audit.svg
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 834 430"
+ width="834" height="430" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: workflow-security-audit">
+ <title>workflow-security-audit</title>
+ <rect width="834" height="430" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="834" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="834" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-repo-health:workflow-security-audit</text>
+ <text x="28" y="136" fill="#c5c8c6"> 12 workflow files</text>
+ <text x="28" y="188" fill="#cc6666"> ✗ release.yml pull_request_target with a checkout of the PR head</text>
+ <text x="28" y="214" fill="#c5c8c6"> - runs untrusted code with write permissions</text>
+ <text x="28" y="240" fill="#d8a657"> ⚠ ci.yml actions/checkout pinned to a tag, not a SHA</text>
+ <text x="28" y="266" fill="#d8a657"> ⚠ docs.yml no explicit permissions block - inherits write-all</text>
+ <text x="28" y="292" fill="#7f9f7f"> ✓ nine others no finding</text>
+ <text x="28" y="344" fill="#c5c8c6"> The first one is the one to fix today.</text>
+ <text x="28" y="396" fill="#c5c8c6"> Read-only. No workflow was edited.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/repo-health/workflow-security-audit.txt b/docs-assets/quickstart/families/repo-health/workflow-security-audit.txt
new file mode 100644
index 0000000..fc54b25
--- /dev/null
+++ b/docs-assets/quickstart/families/repo-health/workflow-security-audit.txt
@@ -0,0 +1,33 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-repo-health:workflow-security-audit
+
+ 12 workflow files
+
+ ✗ release.yml pull_request_target with a checkout of the PR head
+ - runs untrusted code with write permissions
+ ⚠ ci.yml actions/checkout pinned to a tag, not a SHA
+ ⚠ docs.yml no explicit permissions block - inherits write-all
+ ✓ nine others no finding
+
+ The first one is the one to fix today.
+
+ Read-only. No workflow was edited.
diff --git a/docs-assets/quickstart/families/security/issue-import.svg b/docs-assets/quickstart/families/security/issue-import.svg
new file mode 100644
index 0000000..6efd199
--- /dev/null
+++ b/docs-assets/quickstart/families/security/issue-import.svg
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 834 430"
+ width="834" height="430" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: issue-import">
+ <title>issue-import</title>
+ <rect width="834" height="430" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="834" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="834" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-security:issue-import</text>
+ <text x="28" y="136" fill="#c5c8c6"> Scanning security@ for reports with no tracker (last 14 days)</text>
+ <text x="28" y="188" fill="#c5c8c6"> 2 threads to import, 3 already tracked, 1 already answered and closed</text>
+ <text x="28" y="240" fill="#c5c8c6"> "Extractor writes outside the destination directory"</text>
+ <text x="28" y="266" fill="#c5c8c6"> -> new tracker, status Needs triage, receipt drafted to the reporter</text>
+ <text x="28" y="318" fill="#c5c8c6"> "Stack trace on malformed input"</text>
+ <text x="28" y="344" fill="#c5c8c6"> -> new tracker, status Needs triage, receipt drafted to the reporter</text>
+ <text x="28" y="396" fill="#c5c8c6"> Import both and draft the receipts? [Y/n]</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/security/issue-import.txt b/docs-assets/quickstart/families/security/issue-import.txt
new file mode 100644
index 0000000..820cd70
--- /dev/null
+++ b/docs-assets/quickstart/families/security/issue-import.txt
@@ -0,0 +1,33 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-security:issue-import
+
+ Scanning security@ for reports with no tracker (last 14 days)
+
+ 2 threads to import, 3 already tracked, 1 already answered and closed
+
+ "Extractor writes outside the destination directory"
+ -> new tracker, status Needs triage, receipt drafted to the reporter
+
+ "Stack trace on malformed input"
+ -> new tracker, status Needs triage, receipt drafted to the reporter
+
+ Import both and draft the receipts? [Y/n]
diff --git a/docs-assets/quickstart/families/security/issue-triage.svg b/docs-assets/quickstart/families/security/issue-triage.svg
new file mode 100644
index 0000000..f5c8d4f
--- /dev/null
+++ b/docs-assets/quickstart/families/security/issue-triage.svg
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 866 456"
+ width="866" height="456" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: issue-triage">
+ <title>issue-triage</title>
+ <rect width="866" height="456" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="866" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="866" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-security:issue-triage</text>
+ <text x="28" y="136" fill="#c5c8c6"> 4 trackers carry needs triage</text>
+ <text x="28" y="188" fill="#c5c8c6"> #218 path traversal in the archive extractor VALID</text>
+ <text x="28" y="214" fill="#c5c8c6"> #221 missing rate limit on the public status page DEFENSE-IN-DEPTH</text>
+ <text x="28" y="240" fill="#c5c8c6"> #223 "your TLS certificate expires soon" INFO-ONLY</text>
+ <text x="28" y="266" fill="#c5c8c6"> #224 same extractor bug, reported independently PROBABLE-DUP of #218</text>
+ <text x="28" y="318" fill="#c5c8c6"> Proposed dispositions are comments, not decisions. Posting one invites</text>
+ <text x="28" y="344" fill="#c5c8c6"> the security team to react; no label is flipped, nothing is closed, and</text>
+ <text x="28" y="370" fill="#c5c8c6"> no CVE is allocated here.</text>
+ <text x="28" y="422" fill="#c5c8c6"> Post all four? [y/N]</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/security/issue-triage.txt b/docs-assets/quickstart/families/security/issue-triage.txt
new file mode 100644
index 0000000..f4c0195
--- /dev/null
+++ b/docs-assets/quickstart/families/security/issue-triage.txt
@@ -0,0 +1,34 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-security:issue-triage
+
+ 4 trackers carry needs triage
+
+ #218 path traversal in the archive extractor VALID
+ #221 missing rate limit on the public status page DEFENSE-IN-DEPTH
+ #223 "your TLS certificate expires soon" INFO-ONLY
+ #224 same extractor bug, reported independently PROBABLE-DUP of #218
+
+ Proposed dispositions are comments, not decisions. Posting one invites
+ the security team to react; no label is flipped, nothing is closed, and
+ no CVE is allocated here.
+
+ Post all four? [y/N]
diff --git a/docs-assets/quickstart/families/security/model-verify.svg b/docs-assets/quickstart/families/security/model-verify.svg
new file mode 100644
index 0000000..f03622f
--- /dev/null
+++ b/docs-assets/quickstart/families/security/model-verify.svg
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 856 404"
+ width="856" height="404" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: model-verify">
+ <title>model-verify</title>
+ <rect width="856" height="404" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="856" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="856" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-security:model-verify</text>
+ <text x="28" y="136" fill="#c5c8c6"> Verifying the threat model against the repository</text>
+ <text x="28" y="188" fill="#7f9f7f"> ✓ every trust boundary in the model has a component that implements it</text>
+ <text x="28" y="214" fill="#7f9f7f"> ✓ every entry point in the code appears in the model</text>
+ <text x="28" y="240" fill="#cc6666"> ✗ model names an "admin API" surface that no route serves any more</text>
+ <text x="28" y="292" fill="#c5c8c6"> One stale assertion. The model is a document that rots like any other;</text>
+ <text x="28" y="318" fill="#c5c8c6"> this is the check that notices.</text>
+ <text x="28" y="370" fill="#c5c8c6"> Nothing was edited - use model-update to propose the change.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/security/model-verify.txt b/docs-assets/quickstart/families/security/model-verify.txt
new file mode 100644
index 0000000..0aca541
--- /dev/null
+++ b/docs-assets/quickstart/families/security/model-verify.txt
@@ -0,0 +1,32 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-security:model-verify
+
+ Verifying the threat model against the repository
+
+ ✓ every trust boundary in the model has a component that implements it
+ ✓ every entry point in the code appears in the model
+ ✗ model names an "admin API" surface that no route serves any more
+
+ One stale assertion. The model is a document that rots like any other;
+ this is the check that notices.
+
+ Nothing was edited - use model-update to propose the change.
diff --git a/docs-assets/quickstart/families/setup/isolated-setup-install.svg b/docs-assets/quickstart/families/setup/isolated-setup-install.svg
new file mode 100644
index 0000000..682f8f5
--- /dev/null
+++ b/docs-assets/quickstart/families/setup/isolated-setup-install.svg
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 845 430"
+ width="845" height="430" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: isolated-setup-install">
+ <title>isolated-setup-install</title>
+ <rect width="845" height="430" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="845" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="845" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-setup:isolated-setup-install</text>
+ <text x="28" y="136" fill="#c5c8c6"> Proposed changes - nothing applied yet</text>
+ <text x="28" y="188" fill="#c5c8c6"> 1 .claude/settings.json sandbox on, 14 deny rules</text>
+ <text x="28" y="214" fill="#c5c8c6"> 2 ~/.claude/scripts/ 3 hooks and the status line</text>
+ <text x="28" y="240" fill="#c5c8c6"> 3 ~/.zshrc source agent-iso.sh</text>
+ <text x="28" y="292" fill="#c5c8c6"> Every step is shown before it runs. Nothing is written with sudo, no</text>
+ <text x="28" y="318" fill="#c5c8c6"> shell rc file is edited behind your back, and an existing settings.json</text>
+ <text x="28" y="344" fill="#c5c8c6"> is merged, never replaced.</text>
+ <text x="28" y="396" fill="#c5c8c6"> Apply 1-3? [y/N]</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/setup/isolated-setup-install.txt b/docs-assets/quickstart/families/setup/isolated-setup-install.txt
new file mode 100644
index 0000000..6d0ab8e
--- /dev/null
+++ b/docs-assets/quickstart/families/setup/isolated-setup-install.txt
@@ -0,0 +1,33 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-setup:isolated-setup-install
+
+ Proposed changes - nothing applied yet
+
+ 1 .claude/settings.json sandbox on, 14 deny rules
+ 2 ~/.claude/scripts/ 3 hooks and the status line
+ 3 ~/.zshrc source agent-iso.sh
+
+ Every step is shown before it runs. Nothing is written with sudo, no
+ shell rc file is edited behind your back, and an existing settings.json
+ is merged, never replaced.
+
+ Apply 1-3? [y/N]
diff --git a/docs-assets/quickstart/families/setup/isolated-setup-verify.svg b/docs-assets/quickstart/families/setup/isolated-setup-verify.svg
new file mode 100644
index 0000000..dca3c18
--- /dev/null
+++ b/docs-assets/quickstart/families/setup/isolated-setup-verify.svg
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 877 456"
+ width="877" height="456" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: isolated-setup-verify">
+ <title>isolated-setup-verify</title>
+ <rect width="877" height="456" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="877" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="877" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-setup:isolated-setup-verify</text>
+ <text x="28" y="136" fill="#c5c8c6"> Checking the secure-agent setup</text>
+ <text x="28" y="188" fill="#7f9f7f"> ✓ settings wiring sandbox, permissions and clean-env layers present</text>
+ <text x="28" y="214" fill="#7f9f7f"> ✓ bubblewrap installed, version recorded in the pin file</text>
+ <text x="28" y="240" fill="#7f9f7f"> ✓ socat installed</text>
+ <text x="28" y="266" fill="#7f9f7f"> ✓ agent socket reachable from inside the sandbox</text>
+ <text x="28" y="292" fill="#d8a657"> ⚠ docker socket not exposed - container work will fail in-session</text>
+ <text x="28" y="344" fill="#c5c8c6"> One warning. Entry 4 of the troubleshooting guide has the settings.json</text>
+ <text x="28" y="370" fill="#c5c8c6"> change that exposes the runtime socket, if you need it.</text>
+ <text x="28" y="422" fill="#c5c8c6"> Nothing was modified: this check is read-only.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/setup/isolated-setup-verify.txt b/docs-assets/quickstart/families/setup/isolated-setup-verify.txt
new file mode 100644
index 0000000..be44156
--- /dev/null
+++ b/docs-assets/quickstart/families/setup/isolated-setup-verify.txt
@@ -0,0 +1,34 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-setup:isolated-setup-verify
+
+ Checking the secure-agent setup
+
+ ✓ settings wiring sandbox, permissions and clean-env layers present
+ ✓ bubblewrap installed, version recorded in the pin file
+ ✓ socat installed
+ ✓ agent socket reachable from inside the sandbox
+ ⚠ docker socket not exposed - container work will fail in-session
+
+ One warning. Entry 4 of the troubleshooting guide has the settings.json
+ change that exposes the runtime socket, if you need it.
+
+ Nothing was modified: this check is read-only.
diff --git a/docs-assets/quickstart/families/setup/status.svg b/docs-assets/quickstart/families/setup/status.svg
new file mode 100644
index 0000000..a2393c2
--- /dev/null
+++ b/docs-assets/quickstart/families/setup/status.svg
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 802 404"
+ width="802" height="404" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: status">
+ <title>status</title>
+ <rect width="802" height="404" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="802" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="802" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-setup:status</text>
+ <text x="28" y="136" fill="#c5c8c6"> Install marketplace (apache-magpie), tracking main</text>
+ <text x="28" y="162" fill="#c5c8c6"> Plugins magpie-setup, magpie-utilities, magpie-agent-guard,</text>
+ <text x="28" y="188" fill="#c5c8c6"> magpie-pr-management</text>
+ <text x="28" y="214" fill="#c5c8c6"> Project floor .apache-magpie.lock - method: marketplace</text>
+ <text x="28" y="266" fill="#7f9f7f"> ✓ every floor plugin is installed and at or above the floor</text>
+ <text x="28" y="292" fill="#7f9f7f"> ✓ no drift between the committed floor and this machine</text>
+ <text x="28" y="344" fill="#c5c8c6"> Ahead of the floor is not drift: magpie-pr-management is yours, not</text>
+ <text x="28" y="370" fill="#c5c8c6"> the project's, and nothing will remove it.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/setup/status.txt b/docs-assets/quickstart/families/setup/status.txt
new file mode 100644
index 0000000..51a9e76
--- /dev/null
+++ b/docs-assets/quickstart/families/setup/status.txt
@@ -0,0 +1,32 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-setup:status
+
+ Install marketplace (apache-magpie), tracking main
+ Plugins magpie-setup, magpie-utilities, magpie-agent-guard,
+ magpie-pr-management
+ Project floor .apache-magpie.lock - method: marketplace
+
+ ✓ every floor plugin is installed and at or above the floor
+ ✓ no drift between the committed floor and this machine
+
+ Ahead of the floor is not drift: magpie-pr-management is yours, not
+ the project's, and nothing will remove it.
diff --git a/docs-assets/quickstart/families/utilities/list-skills.svg b/docs-assets/quickstart/families/utilities/list-skills.svg
new file mode 100644
index 0000000..9265c14
--- /dev/null
+++ b/docs-assets/quickstart/families/utilities/list-skills.svg
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 834 482"
+ width="834" height="482" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: list-skills">
+ <title>list-skills</title>
+ <rect width="834" height="482" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="834" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="834" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-utilities:list-skills</text>
+ <text x="28" y="136" fill="#c5c8c6"> Installed here</text>
+ <text x="28" y="188" fill="#c5c8c6"> magpie-setup 9 skills install, upgrade, adopt, sandbox</text>
+ <text x="28" y="214" fill="#c5c8c6"> magpie-pr-management 8 skills triage, review, stats, quick-merge</text>
+ <text x="28" y="240" fill="#c5c8c6"> magpie-utilities 5 skills author and index your own skills</text>
+ <text x="28" y="292" fill="#c5c8c6"> Available in the marketplace, not installed</text>
+ <text x="28" y="344" fill="#c5c8c6"> magpie-security, magpie-release-management, magpie-issue,</text>
+ <text x="28" y="370" fill="#c5c8c6"> magpie-repo-health, magpie-contributor-growth, magpie-mentoring,</text>
+ <text x="28" y="396" fill="#c5c8c6"> magpie-pairing</text>
+ <text x="28" y="448" fill="#c5c8c6"> Ask about any of them by name and I will read that skill and answer.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/utilities/list-skills.txt b/docs-assets/quickstart/families/utilities/list-skills.txt
new file mode 100644
index 0000000..f7b69e5
--- /dev/null
+++ b/docs-assets/quickstart/families/utilities/list-skills.txt
@@ -0,0 +1,35 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-utilities:list-skills
+
+ Installed here
+
+ magpie-setup 9 skills install, upgrade, adopt, sandbox
+ magpie-pr-management 8 skills triage, review, stats, quick-merge
+ magpie-utilities 5 skills author and index your own skills
+
+ Available in the marketplace, not installed
+
+ magpie-security, magpie-release-management, magpie-issue,
+ magpie-repo-health, magpie-contributor-growth, magpie-mentoring,
+ magpie-pairing
+
+ Ask about any of them by name and I will read that skill and answer.
diff --git a/docs-assets/quickstart/families/utilities/report-framework-issue.svg b/docs-assets/quickstart/families/utilities/report-framework-issue.svg
new file mode 100644
index 0000000..f049a05
--- /dev/null
+++ b/docs-assets/quickstart/families/utilities/report-framework-issue.svg
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 856 404"
+ width="856" height="404" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: report-framework-issue">
+ <title>report-framework-issue</title>
+ <rect width="856" height="404" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="856" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="856" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-utilities:report-framework-issue</text>
+ <text x="28" y="136" fill="#c5c8c6"> You hit: setup-status misreports drift on a fork</text>
+ <text x="28" y="188" fill="#c5c8c6"> Searched apache/magpie</text>
+ <text x="28" y="214" fill="#c5c8c6"> no open issue matches</text>
+ <text x="28" y="240" fill="#c5c8c6"> no open PR matches</text>
+ <text x="28" y="292" fill="#c5c8c6"> Drafted an issue: what you were doing, what happened, what you expected,</text>
+ <text x="28" y="318" fill="#c5c8c6"> and the one command that reproduces it.</text>
+ <text x="28" y="370" fill="#c5c8c6"> This goes to the framework, not to your project. Open it? [y/N]</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/utilities/report-framework-issue.txt b/docs-assets/quickstart/families/utilities/report-framework-issue.txt
new file mode 100644
index 0000000..90253bf
--- /dev/null
+++ b/docs-assets/quickstart/families/utilities/report-framework-issue.txt
@@ -0,0 +1,32 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-utilities:report-framework-issue
+
+ You hit: setup-status misreports drift on a fork
+
+ Searched apache/magpie
+ no open issue matches
+ no open PR matches
+
+ Drafted an issue: what you were doing, what happened, what you expected,
+ and the one command that reproduces it.
+
+ This goes to the framework, not to your project. Open it? [y/N]
diff --git a/docs-assets/quickstart/families/utilities/write-skill.svg b/docs-assets/quickstart/families/utilities/write-skill.svg
new file mode 100644
index 0000000..fff4485
--- /dev/null
+++ b/docs-assets/quickstart/families/utilities/write-skill.svg
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 845 456"
+ width="845" height="456" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: write-skill">
+ <title>write-skill</title>
+ <rect width="845" height="456" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="845" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="845" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-utilities:write-skill</text>
+ <text x="28" y="136" fill="#c5c8c6"> What should the skill do? Sweep stale release branches</text>
+ <text x="28" y="188" fill="#c5c8c6"> Drafting against the framework's conventions</text>
+ <text x="28" y="240" fill="#7f9f7f"> ✓ frontmatter name, description, family, mode, status</text>
+ <text x="28" y="266" fill="#7f9f7f"> ✓ pre-flight the shared block every skill runs first</text>
+ <text x="28" y="292" fill="#7f9f7f"> ✓ hard rules read-only by default; every state change confirmed</text>
+ <text x="28" y="318" fill="#d8a657"> ⚠ eval suite none yet - a skill without one is unverifiable</text>
+ <text x="28" y="370" fill="#c5c8c6"> Wrote the draft to skills/release-branch-sweep/SKILL.md.</text>
+ <text x="28" y="422" fill="#c5c8c6"> Next: the eval suite. It is the part that stops a rewrite breaking it.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/families/utilities/write-skill.txt b/docs-assets/quickstart/families/utilities/write-skill.txt
new file mode 100644
index 0000000..2fe9877
--- /dev/null
+++ b/docs-assets/quickstart/families/utilities/write-skill.txt
@@ -0,0 +1,34 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-utilities:write-skill
+
+ What should the skill do? Sweep stale release branches
+
+ Drafting against the framework's conventions
+
+ ✓ frontmatter name, description, family, mode, status
+ ✓ pre-flight the shared block every skill runs first
+ ✓ hard rules read-only by default; every state change confirmed
+ ⚠ eval suite none yet - a skill without one is unverifiable
+
+ Wrote the draft to skills/release-branch-sweep/SKILL.md.
+
+ Next: the eval suite. It is the part that stops a rewrite breaking it.
diff --git a/docs-assets/quickstart/install.svg b/docs-assets/quickstart/install.svg
new file mode 100644
index 0000000..3176255
--- /dev/null
+++ b/docs-assets/quickstart/install.svg
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 675 520"
+ width="675" height="520" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated first look: three install commands, then a triage run returning 38 open PRs with a proposed action for each and a confirmation prompt">
+ <title>Install Magpie, and use it</title>
+ <desc>Illustrative animation of installing Magpie and running one skill. Not a recording.</desc>
+ <rect width="675" height="520" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="675" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="675" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /plugin marketplace add apache/magpie<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="7.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="104" fill="#8abeb7" opacity="0">> /plugin install magpie-setup@apache-magpie<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0532;0.0542;1" dur="7.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="128" fill="#8abeb7" opacity="0">> /plugin install magpie-agent-guard@apache-magpie<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1064;0.1074;1" dur="7.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="152" fill="#8abeb7" opacity="0">> /plugin install magpie-utilities@apache-magpie<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1597;0.1607;1" dur="7.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#8abeb7" opacity="0">> /plugin install magpie-pr-management@apache-magpie<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2129;0.2139;1" dur="7.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="224" fill="#7f9f7f" opacity="0"> ✓ baseline + one family - nothing written to the repository<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2661;0.2671;1" dur="7.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="272" fill="#8abeb7" opacity="0">> /magpie-pr-management:triage<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3193;0.3203;1" dur="7.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#c5c8c6" opacity="0"> 38 open PRs, 12 untriaged<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3725;0.3735;1" dur="7.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="368" fill="#c5c8c6" opacity="0"> #1421 first contribution, CI green, no reviewer<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4258;0.4268;1" dur="7.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#8a8f94" opacity="0"> -> mark ready for maintainer review<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4790;0.4800;1" dur="7.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="416" fill="#c5c8c6" opacity="0"> #1388 draft 3 weeks, no commits since<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5322;0.5332;1" dur="7.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="440" fill="#8a8f94" opacity="0"> -> ask the author if it is still active<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5854;0.5864;1" dur="7.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="488" fill="#8a8f94" opacity="0"> Each action needs your confirmation. [Y/n]<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6387;0.6397;1" dur="7.1s" repeatCount="indefinite"/></text>
+ <rect x="26" y="475" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/magpie-setup.svg b/docs-assets/quickstart/magpie-setup.svg
new file mode 100644
index 0000000..dd7abfa
--- /dev/null
+++ b/docs-assets/quickstart/magpie-setup.svg
@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 726 1024"
+ width="726" height="1024" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated first run of /magpie-setup: the agent detected, the skill families picked, the install commands emitted, then the secure-agent setup applying the sandbox, the clean-environment wrapper, the hooks and the status line">
+ <title>/magpie-setup — the first run</title>
+ <desc>Illustrative animation of a first /magpie-setup run and the secure-agent setup that follows it. Not a recording.</desc>
+ <rect width="726" height="1024" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="726" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="726" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /magpie-setup<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="128" fill="#8a8f94" opacity="0"> Agent Claude Code<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0287;0.0297;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="152" fill="#8a8f94" opacity="0"> Installed nothing yet<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0575;0.0585;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#8a8f94" opacity="0"> Repo github.com/acme/toolkit, not adopted<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0862;0.0872;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="224" fill="#c5c8c6" opacity="0"> Which families? The baseline three are ticked already.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1150;0.1160;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="248" fill="#7f9f7f" opacity="0"> [x] setup install, upgrade, adopt, sandbox<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1437;0.1447;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="272" fill="#7f9f7f" opacity="0"> [x] agent-guard denies dangerous commands before they run<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1725;0.1735;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="296" fill="#7f9f7f" opacity="0"> [x] utilities author and index your own skills<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2012;0.2022;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#7f9f7f" opacity="0"> [x] pr-management you said "triage"<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2300;0.2310;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="344" fill="#8a8f94" opacity="0"> [ ] security [ ] issue [ ] release-management [ ] …<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2587;0.2597;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#c5c8c6" opacity="0"> Installing 4 plugins for you - user scope:<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2874;0.2884;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="416" fill="#7f9f7f" opacity="0"> ✓ apache-magpie marketplace added<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3162;0.3172;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="440" fill="#7f9f7f" opacity="0"> ✓ magpie-setup ✓ magpie-agent-guard<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3449;0.3459;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="464" fill="#7f9f7f" opacity="0"> ✓ magpie-utilities ✓ magpie-pr-management<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3737;0.3747;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="512" fill="#8a8f94" opacity="0"> Live in your next session. Nothing was written to the<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4024;0.4034;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="536" fill="#8a8f94" opacity="0"> repository - that is the finished state.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4312;0.4322;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="584" fill="#d8a657" opacity="0"> One follow-up that is not optional - these skills read<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4599;0.4609;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="608" fill="#d8a657" opacity="0"> pre-disclosure security content, so sandbox the agent:<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4887;0.4897;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="656" fill="#8abeb7" opacity="0">> /magpie-setup:isolated-setup-install<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5174;0.5184;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="704" fill="#c5c8c6" opacity="0"> Proposed - nothing applied yet:<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5461;0.5471;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="728" fill="#c5c8c6" opacity="0"> 1 .claude/settings.json sandbox on, 14 deny rules<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5749;0.5759;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="752" fill="#c5c8c6" opacity="0"> 2 ~/.claude/scripts/ 3 hooks and the status line<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6036;0.6046;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="776" fill="#c5c8c6" opacity="0"> 3 ~/.zshrc source agent-iso.sh<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6324;0.6334;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="824" fill="#c5c8c6" opacity="0"> Apply 1-3? [y/N] y<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6611;0.6621;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="872" fill="#7f9f7f" opacity="0"> ✓ sandbox filesystem and network confined to this repo<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6899;0.6909;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="896" fill="#7f9f7f" opacity="0"> ✓ clean env credentials stripped before the agent starts<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.7186;0.7196;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="920" fill="#7f9f7f" opacity="0"> ✓ status line shows the sandbox state and the Magpie version<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.7474;0.7484;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="968" fill="#8a8f94" opacity="0"> Run a skill when you are ready. The first one that needs project<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.7761;0.7771;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <text x="26" y="992" fill="#8a8f94" opacity="0"> configuration writes it itself, into gitignored files.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.8048;0.8058;1" dur="13.2s" repeatCount="indefinite"/></text>
+ <rect x="26" y="979" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/step-adopt.svg b/docs-assets/quickstart/step-adopt.svg
new file mode 100644
index 0000000..6462870
--- /dev/null
+++ b/docs-assets/quickstart/step-adopt.svg
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 685 424"
+ width="685" height="424" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated adopt run: three paths staged and not committed, what a contributor gets on clone, and what it does not restrict">
+ <title>Step 6 — adopt it for the project</title>
+ <desc>Illustrative animation of adopting Magpie for a project. Not a recording.</desc>
+ <rect width="685" height="424" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="685" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="685" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#d8a657" opacity="0"> Only if you are a maintainer, deciding with the others.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="6.0s" repeatCount="indefinite"/></text>
+ <text x="26" y="128" fill="#8abeb7" opacity="0">> /magpie-setup adopt<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0633;0.0643;1" dur="6.0s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#c5c8c6" opacity="0"> Staged, not committed:<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1267;0.1277;1" dur="6.0s" repeatCount="indefinite"/></text>
+ <text x="26" y="200" fill="#c5c8c6" opacity="0"> .apache-magpie.lock the floor - a minimum, not a pin<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1900;0.1910;1" dur="6.0s" repeatCount="indefinite"/></text>
+ <text x="26" y="224" fill="#c5c8c6" opacity="0"> .claude/settings.json derived from it<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2533;0.2543;1" dur="6.0s" repeatCount="indefinite"/></text>
+ <text x="26" y="248" fill="#c5c8c6" opacity="0"> .apache-magpie-overrides/ the project's configuration<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3167;0.3177;1" dur="6.0s" repeatCount="indefinite"/></text>
+ <text x="26" y="296" fill="#7f9f7f" opacity="0"> ✓ a contributor who clones this arrives with the floor<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3800;0.3810;1" dur="6.0s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#7f9f7f" opacity="0"> ✓ review it and commit it like any other change<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4433;0.4443;1" dur="6.0s" repeatCount="indefinite"/></text>
+ <text x="26" y="368" fill="#8a8f94" opacity="0"> It limits nobody: anyone may install more, run a newer<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5067;0.5077;1" dur="6.0s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#8a8f94" opacity="0"> Magpie, or ignore the recommendation entirely.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5700;0.5710;1" dur="6.0s" repeatCount="indefinite"/></text>
+ <rect x="26" y="379" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/step-guard.svg b/docs-assets/quickstart/step-guard.svg
new file mode 100644
index 0000000..8c65180
--- /dev/null
+++ b/docs-assets/quickstart/step-guard.svg
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 777 592"
+ width="777" height="592" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated agent-guard setup: the dispatcher, the rules and the PreToolUse hook registered, then a real denial of an unwanted review ping before it was posted">
+ <title>Step 3 — isolate & guard: the action guard</title>
+ <desc>Illustrative animation of the deterministic action guard. Not a recording.</desc>
+ <rect width="777" height="592" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="777" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="777" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /magpie-setup:isolated-setup-install<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="128" fill="#c5c8c6" opacity="0"> Registering the deterministic guard:<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0505;0.0515;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="152" fill="#c5c8c6" opacity="0"> ~/.claude/scripts/agent-guard.py the dispatcher<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1011;0.1021;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#c5c8c6" opacity="0"> ~/.claude/scripts/guards.d/ 5 rules, bundled + skill-owned<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1516;0.1526;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="200" fill="#c5c8c6" opacity="0"> .claude/settings.json PreToolUse hook on Bash<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2021;0.2031;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="248" fill="#7f9f7f" opacity="0"> ✓ every shell command is inspected before it runs<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2527;0.2537;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="296" fill="#8a8f94" opacity="0"> Later that session -<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3032;0.3042;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="344" fill="#8abeb7" opacity="0">> gh pr comment 1421 --body "@alice @bob please take a look"<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3537;0.3547;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#d8a657" opacity="0"> ⚠ agent-guard[mention] denied this before it ran<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4043;0.4053;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="440" fill="#c5c8c6" opacity="0"> A review ping to two maintainers who did not ask for it.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4548;0.4558;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="464" fill="#c5c8c6" opacity="0"> The author is @carol - anyone else is noise.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5053;0.5063;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="488" fill="#8a8f94" opacity="0"> Fix: write `alice` in backticks, or MAGPIE_ALLOW_MENTIONS=1.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5559;0.5569;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="536" fill="#8a8f94" opacity="0"> Nothing was posted. The rule is code, not a line in a SKILL.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6064;0.6074;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="560" fill="#8a8f94" opacity="0"> the model has to remember - so it holds on the turn it matters.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6569;0.6579;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <rect x="26" y="547" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/step-install.svg b/docs-assets/quickstart/step-install.svg
new file mode 100644
index 0000000..6123f15
--- /dev/null
+++ b/docs-assets/quickstart/step-install.svg
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 685 592"
+ width="685" height="592" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated marketplace install: adding apache-magpie, then installing magpie-setup and one family, with nothing written to the repository">
+ <title>Step 1 — install from the marketplace</title>
+ <desc>Illustrative animation of the marketplace install step. Not a recording.</desc>
+ <rect width="685" height="592" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="685" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="685" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /plugin marketplace add apache/magpie<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="7.9s" repeatCount="indefinite"/></text>
+ <text x="26" y="128" fill="#7f9f7f" opacity="0"> ✓ apache-magpie added<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0481;0.0491;1" dur="7.9s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#8abeb7" opacity="0">> /plugin install magpie-setup@apache-magpie<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0962;0.0972;1" dur="7.9s" repeatCount="indefinite"/></text>
+ <text x="26" y="200" fill="#7f9f7f" opacity="0"> ✓ magpie-setup install this one first - nothing<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1443;0.1453;1" dur="7.9s" repeatCount="indefinite"/></text>
+ <text x="26" y="224" fill="#8a8f94" opacity="0"> else installs or upgrades without it<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1924;0.1934;1" dur="7.9s" repeatCount="indefinite"/></text>
+ <text x="26" y="272" fill="#8abeb7" opacity="0">> /plugin install magpie-agent-guard@apache-magpie<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2405;0.2415;1" dur="7.9s" repeatCount="indefinite"/></text>
+ <text x="26" y="296" fill="#7f9f7f" opacity="0"> ✓ magpie-agent-guard denies dangerous shell shapes before<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2886;0.2896;1" dur="7.9s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#8a8f94" opacity="0"> they run<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3367;0.3377;1" dur="7.9s" repeatCount="indefinite"/></text>
+ <text x="26" y="368" fill="#8abeb7" opacity="0">> /plugin install magpie-utilities@apache-magpie<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3848;0.3858;1" dur="7.9s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#7f9f7f" opacity="0"> ✓ magpie-utilities list-skills, and the small tools<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4329;0.4339;1" dur="7.9s" repeatCount="indefinite"/></text>
+ <text x="26" y="440" fill="#8abeb7" opacity="0">> /plugin install magpie-pr-management@apache-magpie<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4810;0.4820;1" dur="7.9s" repeatCount="indefinite"/></text>
+ <text x="26" y="464" fill="#7f9f7f" opacity="0"> ✓ magpie-pr-management the family you picked<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5291;0.5301;1" dur="7.9s" repeatCount="indefinite"/></text>
+ <text x="26" y="512" fill="#8a8f94" opacity="0"> The first three are the baseline - the same set a project<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5772;0.5782;1" dur="7.9s" repeatCount="indefinite"/></text>
+ <text x="26" y="536" fill="#8a8f94" opacity="0"> commits when it adopts. Nothing was written to this<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6253;0.6263;1" dur="7.9s" repeatCount="indefinite"/></text>
+ <text x="26" y="560" fill="#8a8f94" opacity="0"> repository, and your teammates are unaffected.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6734;0.6744;1" dur="7.9s" repeatCount="indefinite"/></text>
+ <rect x="26" y="547" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/step-isolation.svg b/docs-assets/quickstart/step-isolation.svg
new file mode 100644
index 0000000..3b96629
--- /dev/null
+++ b/docs-assets/quickstart/step-isolation.svg
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 685 448"
+ width="685" height="448" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated secure-agent setup: three proposed changes, a confirmation, then the sandbox, the clean environment and the status line in place">
+ <title>Step 3 — isolate & guard: the sandbox</title>
+ <desc>Illustrative animation of the secure-agent setup step. Not a recording.</desc>
+ <rect width="685" height="448" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="685" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="685" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /magpie-setup:isolated-setup-install<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="128" fill="#c5c8c6" opacity="0"> Proposed - nothing applied yet:<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0596;0.0606;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="152" fill="#c5c8c6" opacity="0"> 1 .claude/settings.json sandbox on, credential denies<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1191;0.1201;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#c5c8c6" opacity="0"> 2 ~/.claude/scripts/ hooks and the status line<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1787;0.1797;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="200" fill="#c5c8c6" opacity="0"> 3 ~/.zshrc source agent-iso.sh<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2382;0.2392;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="248" fill="#c5c8c6" opacity="0"> Apply 1-3? [y/N] y<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2978;0.2988;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="296" fill="#7f9f7f" opacity="0"> ✓ sandbox bash sees only the paths you allow<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3574;0.3584;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#7f9f7f" opacity="0"> ✓ clean env credentials stripped before the agent starts<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4169;0.4179;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="344" fill="#7f9f7f" opacity="0"> ✓ status line [sandbox] in the footer, green when it is on<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4765;0.4775;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#8a8f94" opacity="0"> Your ~/.ssh, ~/.aws and tokens are out of reach. Every sudo,<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5361;0.5371;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="416" fill="#8a8f94" opacity="0"> shell-rc and settings change was shown before it ran.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5956;0.5966;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <rect x="26" y="403" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/step-privacy.svg b/docs-assets/quickstart/step-privacy.svg
new file mode 100644
index 0000000..14ad194
--- /dev/null
+++ b/docs-assets/quickstart/step-privacy.svg
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 675 544"
+ width="675" height="544" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated privacy-llm run: the stack detected, the variant written locally, the PII redactor proven, and the approved-LLM gate refusing an unregistered local model">
+ <title>Step 4 — set up privacy</title>
+ <desc>Illustrative animation of the privacy-LLM setup. Not a recording.</desc>
+ <rect width="675" height="544" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="675" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="675" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /magpie-setup:privacy-llm<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="128" fill="#c5c8c6" opacity="0"> Detected, not asked:<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0505;0.0515;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="152" fill="#c5c8c6" opacity="0"> agent Claude Code<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1011;0.1021;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#c5c8c6" opacity="0"> local inference ollama, llama3.1:70b on :11434<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1516;0.1526;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="200" fill="#c5c8c6" opacity="0"> private lists private@acme.apache.org<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2021;0.2031;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="248" fill="#c5c8c6" opacity="0"> That is variant 2 - local inference. Written to<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2527;0.2537;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="272" fill="#c5c8c6" opacity="0"> .apache-magpie-local/privacy-llm.md (gitignored, yours)<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3032;0.3042;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#7f9f7f" opacity="0"> ✓ PII redactor Other Researcher -> N-a3f9d2<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3537;0.3547;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="344" fill="#7f9f7f" opacity="0"> other@example.com -> E-7c1b04<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4043;0.4053;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#d8a657" opacity="0"> ⚠ approved-LLM gate: llama3.1:70b is not in the registry<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4548;0.4558;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="440" fill="#c5c8c6" opacity="0"> Until it is, skills will refuse to fetch private@ mail.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5053;0.5063;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="464" fill="#8a8f94" opacity="0"> Drop it from the stack, or take the opt-in recipe for it.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5559;0.5569;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="488" fill="#8a8f94" opacity="0"> Nothing was widened to make this pass - the gate failing<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6064;0.6074;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="512" fill="#8a8f94" opacity="0"> is the answer, not an obstacle.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6569;0.6579;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <rect x="26" y="499" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/step-use.svg b/docs-assets/quickstart/step-use.svg
new file mode 100644
index 0000000..d5f94ad
--- /dev/null
+++ b/docs-assets/quickstart/step-use.svg
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 654 472"
+ width="654" height="472" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated skill run: listing what is installed, then a triage pass returning 38 open PRs with a proposed action each and nothing posted">
+ <title>Step 5 — use it</title>
+ <desc>Illustrative animation of running a skill. Not a recording.</desc>
+ <rect width="654" height="472" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="654" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="654" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /magpie-utilities:list-skills<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="128" fill="#c5c8c6" opacity="0"> magpie-setup install, upgrade, adopt, sandbox<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0596;0.0606;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="152" fill="#c5c8c6" opacity="0"> magpie-utilities author and index your own skills<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1191;0.1201;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#c5c8c6" opacity="0"> magpie-pr-management triage, review, stats, quick-merge<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1787;0.1797;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="224" fill="#8abeb7" opacity="0">> /magpie-pr-management:triage<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2382;0.2392;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="272" fill="#c5c8c6" opacity="0"> 38 open PRs, 12 untriaged<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2978;0.2988;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#c5c8c6" opacity="0"> #1421 first contribution, CI green, no reviewer<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3574;0.3584;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="344" fill="#8a8f94" opacity="0"> -> mark ready for maintainer review<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4169;0.4179;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="368" fill="#c5c8c6" opacity="0"> #1402 branch 200 commits behind, conflicts<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4765;0.4775;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#8a8f94" opacity="0"> -> ask the author to rebase<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5361;0.5371;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <text x="26" y="440" fill="#7f9f7f" opacity="0"> Nothing has been posted. Every action waits for you.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5956;0.5966;1" dur="6.4s" repeatCount="indefinite"/></text>
+ <rect x="26" y="427" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/walkthrough/1-preflight-stops.svg b/docs-assets/quickstart/walkthrough/1-preflight-stops.svg
new file mode 100644
index 0000000..46f0dae
--- /dev/null
+++ b/docs-assets/quickstart/walkthrough/1-preflight-stops.svg
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 791 404"
+ width="791" height="404" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: 1-preflight-stops">
+ <title>1-preflight-stops</title>
+ <rect width="791" height="404" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="791" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="791" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-pr-management:triage</text>
+ <text x="28" y="136" fill="#c5c8c6"> Pre-flight</text>
+ <text x="28" y="188" fill="#7f9f7f"> ✓ plugin installed magpie-pr-management</text>
+ <text x="28" y="214" fill="#cc6666"> ✗ project configuration 3 required files, none found</text>
+ <text x="28" y="266" fill="#c5c8c6"> Triage needs to know this project's committer team, its area-label</text>
+ <text x="28" y="292" fill="#c5c8c6"> prefix, and which labels mean "ready" - none of which I can infer.</text>
+ <text x="28" y="344" fill="#c5c8c6"> Configuring now. This writes gitignored files in your clone only:</text>
+ <text x="28" y="370" fill="#c5c8c6"> nothing staged, nothing committed, nobody else affected.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/walkthrough/1-preflight-stops.txt b/docs-assets/quickstart/walkthrough/1-preflight-stops.txt
new file mode 100644
index 0000000..ddb81e3
--- /dev/null
+++ b/docs-assets/quickstart/walkthrough/1-preflight-stops.txt
@@ -0,0 +1,32 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-pr-management:triage
+
+ Pre-flight
+
+ ✓ plugin installed magpie-pr-management
+ ✗ project configuration 3 required files, none found
+
+ Triage needs to know this project's committer team, its area-label
+ prefix, and which labels mean "ready" - none of which I can infer.
+
+ Configuring now. This writes gitignored files in your clone only:
+ nothing staged, nothing committed, nobody else affected.
diff --git a/docs-assets/quickstart/walkthrough/2-config-wizard.svg b/docs-assets/quickstart/walkthrough/2-config-wizard.svg
new file mode 100644
index 0000000..7ee3660
--- /dev/null
+++ b/docs-assets/quickstart/walkthrough/2-config-wizard.svg
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 877 404"
+ width="877" height="404" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: 2-config-wizard">
+ <title>2-config-wizard</title>
+ <rect width="877" height="404" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="877" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="877" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#c5c8c6"> Derived from the repository:</text>
+ <text x="28" y="136" fill="#c5c8c6"> project.md upstream_repo acme/toolkit (origin remote)</text>
+ <text x="28" y="162" fill="#c5c8c6"> pr-management-config.md area_prefix area: (17 labels use it)</text>
+ <text x="28" y="214" fill="#c5c8c6"> Three values left. One question:</text>
+ <text x="28" y="266" fill="#c5c8c6"> tracker_url ?</text>
+ <text x="28" y="292" fill="#c5c8c6"> committers team ?</text>
+ <text x="28" y="318" fill="#c5c8c6"> comment footer ?</text>
+ <text x="28" y="370" fill="#c5c8c6"> Answer, or skip any of them - a TODO left in place is not an error.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/walkthrough/2-config-wizard.txt b/docs-assets/quickstart/walkthrough/2-config-wizard.txt
new file mode 100644
index 0000000..a0d4078
--- /dev/null
+++ b/docs-assets/quickstart/walkthrough/2-config-wizard.txt
@@ -0,0 +1,32 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+ Derived from the repository:
+
+ project.md upstream_repo acme/toolkit (origin remote)
+ pr-management-config.md area_prefix area: (17 labels use it)
+
+ Three values left. One question:
+
+ tracker_url ?
+ committers team ?
+ comment footer ?
+
+ Answer, or skip any of them - a TODO left in place is not an error.
diff --git a/docs-assets/quickstart/walkthrough/3-scaffolded.svg b/docs-assets/quickstart/walkthrough/3-scaffolded.svg
new file mode 100644
index 0000000..0feb071
--- /dev/null
+++ b/docs-assets/quickstart/walkthrough/3-scaffolded.svg
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 834 534"
+ width="834" height="534" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: 3-scaffolded">
+ <title>3-scaffolded</title>
+ <rect width="834" height="534" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="834" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="834" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-setup config</text>
+ <text x="28" y="136" fill="#c5c8c6"> Written to .apache-magpie-local/ - gitignored, this clone only</text>
+ <text x="28" y="188" fill="#c5c8c6"> project.md 2 values, 1 TODO</text>
+ <text x="28" y="214" fill="#c5c8c6"> pr-management-config.md 2 values, 1 TODO</text>
+ <text x="28" y="240" fill="#c5c8c6"> pr-management-triage-comment-templates.md 0 values, 4 TODO</text>
+ <text x="28" y="292" fill="#c5c8c6"> Added /.apache-magpie-local/ to .git/info/exclude, not to .gitignore -</text>
+ <text x="28" y="318" fill="#c5c8c6"> .gitignore is committed, and nothing here should be.</text>
+ <text x="28" y="370" fill="#c5c8c6"> Nothing staged. Nothing committed. No teammate sees any of this.</text>
+ <text x="28" y="422" fill="#7f9f7f"> ✓ magpie-pr-management:triage can run now</text>
+ <text x="28" y="474" fill="#c5c8c6"> A TODO left in place is not an error: the skill that needs one names</text>
+ <text x="28" y="500" fill="#c5c8c6"> it when it needs it, and the skills that do not never look.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/walkthrough/3-scaffolded.txt b/docs-assets/quickstart/walkthrough/3-scaffolded.txt
new file mode 100644
index 0000000..3e30e29
--- /dev/null
+++ b/docs-assets/quickstart/walkthrough/3-scaffolded.txt
@@ -0,0 +1,37 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-setup config
+
+ Written to .apache-magpie-local/ - gitignored, this clone only
+
+ project.md 2 values, 1 TODO
+ pr-management-config.md 2 values, 1 TODO
+ pr-management-triage-comment-templates.md 0 values, 4 TODO
+
+ Added /.apache-magpie-local/ to .git/info/exclude, not to .gitignore -
+ .gitignore is committed, and nothing here should be.
+
+ Nothing staged. Nothing committed. No teammate sees any of this.
+
+ ✓ magpie-pr-management:triage can run now
+
+ A TODO left in place is not an error: the skill that needs one names
+ it when it needs it, and the skills that do not never look.
diff --git a/docs-assets/quickstart/walkthrough/4-it-runs.svg b/docs-assets/quickstart/walkthrough/4-it-runs.svg
new file mode 100644
index 0000000..1d5b1b5
--- /dev/null
+++ b/docs-assets/quickstart/walkthrough/4-it-runs.svg
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 802 404"
+ width="802" height="404" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: 4-it-runs">
+ <title>4-it-runs</title>
+ <rect width="802" height="404" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="802" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="802" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-pr-management:triage</text>
+ <text x="28" y="136" fill="#c5c8c6"> Pre-flight ✓ plugin installed ✓ project configuration</text>
+ <text x="28" y="188" fill="#c5c8c6"> 38 open PRs, 12 untriaged</text>
+ <text x="28" y="240" fill="#c5c8c6"> #1421 first-time contributor, CI green, no reviewer</text>
+ <text x="28" y="266" fill="#c5c8c6"> -> mark ready for maintainer review</text>
+ <text x="28" y="292" fill="#c5c8c6"> #1388 draft for 3 weeks, no commits since</text>
+ <text x="28" y="318" fill="#c5c8c6"> -> comment asking whether it is still active</text>
+ <text x="28" y="370" fill="#c5c8c6"> Each action needs your confirmation. Walk them one at a time? [Y/n]</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/walkthrough/4-it-runs.txt b/docs-assets/quickstart/walkthrough/4-it-runs.txt
new file mode 100644
index 0000000..164cc48
--- /dev/null
+++ b/docs-assets/quickstart/walkthrough/4-it-runs.txt
@@ -0,0 +1,32 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-pr-management:triage
+
+ Pre-flight ✓ plugin installed ✓ project configuration
+
+ 38 open PRs, 12 untriaged
+
+ #1421 first-time contributor, CI green, no reviewer
+ -> mark ready for maintainer review
+ #1388 draft for 3 weeks, no commits since
+ -> comment asking whether it is still active
+
+ Each action needs your confirmation. Walk them one at a time? [Y/n]
diff --git a/docs-assets/quickstart/walkthrough/5-adopt-promotes.svg b/docs-assets/quickstart/walkthrough/5-adopt-promotes.svg
new file mode 100644
index 0000000..b944592
--- /dev/null
+++ b/docs-assets/quickstart/walkthrough/5-adopt-promotes.svg
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE — do not edit.
+
+ Rendered from the .txt beside it by tools/dev/render-screenshot.sh.
+ Edit the transcript and re-render; check-quickstart-recording.py fails
+ the build when this file no longer matches its source.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 823 612"
+ width="823" height="612" role="img"
+ data-magpie-rendered="render-screenshot"
+ aria-label="Terminal transcript: 5-adopt-promotes">
+ <title>5-adopt-promotes</title>
+ <rect width="823" height="612" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="823" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="823" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="18" xml:space="preserve">
+ <text x="28" y="84" fill="#8abeb7">> /magpie-setup adopt</text>
+ <text x="28" y="136" fill="#c5c8c6"> You configured three files locally. Adopting publishes them.</text>
+ <text x="28" y="188" fill="#d8a657"> PROMOTE TO THE PROJECT</text>
+ <text x="28" y="214" fill="#c5c8c6"> [x] project.md upstream repo, tracker, mail lists</text>
+ <text x="28" y="240" fill="#c5c8c6"> [x] pr-management-config.md committers team, label prefix</text>
+ <text x="28" y="266" fill="#c5c8c6"> [ ] pr-management-triage-comment-templates.md</text>
+ <text x="28" y="292" fill="#c5c8c6"> still has 4 TODOs - promote it once it says something</text>
+ <text x="28" y="344" fill="#c5c8c6"> Staged, not committed:</text>
+ <text x="28" y="370" fill="#c5c8c6"> .apache-magpie.lock method: marketplace, floor 0.2.0</text>
+ <text x="28" y="396" fill="#c5c8c6"> .claude/settings.json marketplace + 3 plugins, merged</text>
+ <text x="28" y="422" fill="#c5c8c6"> .apache-magpie-overrides/ the 2 files above</text>
+ <text x="28" y="448" fill="#c5c8c6"> .gitignore /.apache-magpie-local/</text>
+ <text x="28" y="500" fill="#c5c8c6"> Local copies now identical to the project's: removed, so the project</text>
+ <text x="28" y="526" fill="#c5c8c6"> can correct them later and you will get the correction.</text>
+ <text x="28" y="578" fill="#c5c8c6"> Nothing else in .apache-magpie-local/ changed. It is still yours.</text>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/walkthrough/5-adopt-promotes.txt b/docs-assets/quickstart/walkthrough/5-adopt-promotes.txt
new file mode 100644
index 0000000..d7632bc
--- /dev/null
+++ b/docs-assets/quickstart/walkthrough/5-adopt-promotes.txt
@@ -0,0 +1,40 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# Rendered to the .svg beside it by tools/dev/render-screenshot.sh, which
+# strips this header. Edit here, never there.
+
+> /magpie-setup adopt
+
+ You configured three files locally. Adopting publishes them.
+
+ PROMOTE TO THE PROJECT
+ [x] project.md upstream repo, tracker, mail lists
+ [x] pr-management-config.md committers team, label prefix
+ [ ] pr-management-triage-comment-templates.md
+ still has 4 TODOs - promote it once it says something
+
+ Staged, not committed:
+ .apache-magpie.lock method: marketplace, floor 0.2.0
+ .claude/settings.json marketplace + 3 plugins, merged
+ .apache-magpie-overrides/ the 2 files above
+ .gitignore /.apache-magpie-local/
+
+ Local copies now identical to the project's: removed, so the project
+ can correct them later and you will get the correction.
+
+ Nothing else in .apache-magpie-local/ changed. It is still yours.
diff --git a/docs-assets/quickstart/wizard/contributor-growth.svg b/docs-assets/quickstart/wizard/contributor-growth.svg
new file mode 100644
index 0000000..178033b
--- /dev/null
+++ b/docs-assets/quickstart/wizard/contributor-growth.svg
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 705 712"
+ width="705" height="712" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated /magpie-setup config run for the contributor-growth family: the check failing, values derived from the repository, one question, and gitignored files written">
+ <title>/magpie-setup config — contributor-growth</title>
+ <desc>Illustrative animation of a configuration run for the contributor-growth family. Derived from the skills' declared required configuration.</desc>
+ <rect width="705" height="712" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="705" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="705" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /magpie-contributor-growth:<skill><animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="128" fill="#d8a657" opacity="0"> ✗ project configuration — 6 required, none found<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0388;0.0398;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#8a8f94" opacity="0"> Configuring now. Gitignored files in this clone only.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0776;0.0786;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="224" fill="#7f9f7f" opacity="0"> ✓ project.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1163;0.1173;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="248" fill="#8a8f94" opacity="0"> upstream_repo acme/toolkit from the origin remote<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1551;0.1561;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="296" fill="#c5c8c6" opacity="0"> One question, for what the repository cannot tell me:<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1939;0.1949;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#c5c8c6" opacity="0"> committer-onboarding-config.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2327;0.2337;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="344" fill="#8a8f94" opacity="0"> Capability-flag vocabulary for committer intake and…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2714;0.2724;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="368" fill="#c5c8c6" opacity="0"> committer-readiness.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3102;0.3112;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#8a8f94" opacity="0"> The project's declared committer and PMC thresholds —…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3490;0.3500;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="416" fill="#c5c8c6" opacity="0"> contributor-nomination-config.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3878;0.3888;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="440" fill="#8a8f94" opacity="0"> Nomination-brief thresholds and assessment window<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4265;0.4275;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="464" fill="#c5c8c6" opacity="0"> contributor-sentiment-config.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4653;0.4663;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="488" fill="#8a8f94" opacity="0"> Signal thresholds for the sentiment gate<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5041;0.5051;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="512" fill="#c5c8c6" opacity="0"> onboarding-concierge-config.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5429;0.5439;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="536" fill="#8a8f94" opacity="0"> The path a new contributor is walked through, and who…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5816;0.5826;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="584" fill="#7f9f7f" opacity="0"> Written to .apache-magpie-local/ — nothing staged, nothing<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6204;0.6214;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="608" fill="#7f9f7f" opacity="0"> committed, no teammate affected.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6592;0.6602;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="656" fill="#8a8f94" opacity="0"> The project can also adopt Magpie, so contributors get this<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6980;0.6990;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="680" fill="#8a8f94" opacity="0"> on clone: /magpie-setup adopt<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.7367;0.7377;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <rect x="26" y="667" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/wizard/issue.svg b/docs-assets/quickstart/wizard/issue.svg
new file mode 100644
index 0000000..b900e8e
--- /dev/null
+++ b/docs-assets/quickstart/wizard/issue.svg
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 685 712"
+ width="685" height="712" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated /magpie-setup config run for the issue family: the check failing, values derived from the repository, one question, and gitignored files written">
+ <title>/magpie-setup config — issue</title>
+ <desc>Illustrative animation of a configuration run for the issue family. Derived from the skills' declared required configuration.</desc>
+ <rect width="685" height="712" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="685" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="685" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /magpie-issue:<skill><animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="128" fill="#d8a657" opacity="0"> ✗ project configuration — 6 required, none found<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0388;0.0398;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#8a8f94" opacity="0"> Configuring now. Gitignored files in this clone only.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0776;0.0786;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="224" fill="#7f9f7f" opacity="0"> ✓ project.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1163;0.1173;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="248" fill="#8a8f94" opacity="0"> upstream_repo acme/toolkit from the origin remote<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1551;0.1561;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="296" fill="#c5c8c6" opacity="0"> One question, for what the repository cannot tell me:<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1939;0.1949;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#c5c8c6" opacity="0"> fix-workflow.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2327;0.2337;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="344" fill="#8a8f94" opacity="0"> Fork / clone / toolchain specifics, backport-label…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2714;0.2724;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="368" fill="#c5c8c6" opacity="0"> issue-tracker-config.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3102;0.3112;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#8a8f94" opacity="0"> Tracker URL, project key, auth model, default query…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3490;0.3500;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="416" fill="#c5c8c6" opacity="0"> reassess-pool-defaults.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3878;0.3888;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="440" fill="#8a8f94" opacity="0"> Named pools for reassessment sweeps (`open-eol`,…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4265;0.4275;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="464" fill="#c5c8c6" opacity="0"> reproducer-conventions.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4653;0.4663;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="488" fill="#8a8f94" opacity="0"> Evidence-package directory layout and frozen-copy…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5041;0.5051;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="512" fill="#c5c8c6" opacity="0"> runtime-invocation.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5429;0.5439;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="536" fill="#8a8f94" opacity="0"> Build prerequisite, run-a-single-file recipe,…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5816;0.5826;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="584" fill="#7f9f7f" opacity="0"> Written to .apache-magpie-local/ — nothing staged, nothing<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6204;0.6214;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="608" fill="#7f9f7f" opacity="0"> committed, no teammate affected.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6592;0.6602;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="656" fill="#8a8f94" opacity="0"> The project can also adopt Magpie, so contributors get this<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6980;0.6990;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="680" fill="#8a8f94" opacity="0"> on clone: /magpie-setup adopt<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.7367;0.7377;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <rect x="26" y="667" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/wizard/mentoring.svg b/docs-assets/quickstart/wizard/mentoring.svg
new file mode 100644
index 0000000..e60c785
--- /dev/null
+++ b/docs-assets/quickstart/wizard/mentoring.svg
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 695 568"
+ width="695" height="568" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated /magpie-setup config run for the mentoring family: the check failing, values derived from the repository, one question, and gitignored files written">
+ <title>/magpie-setup config — mentoring</title>
+ <desc>Illustrative animation of a configuration run for the mentoring family. Derived from the skills' declared required configuration.</desc>
+ <rect width="695" height="568" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="695" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="695" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /magpie-mentoring:<skill><animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="128" fill="#d8a657" opacity="0"> ✗ project configuration — 3 required, none found<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0505;0.0515;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#8a8f94" opacity="0"> Configuring now. Gitignored files in this clone only.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1011;0.1021;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="224" fill="#7f9f7f" opacity="0"> ✓ project.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1516;0.1526;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="248" fill="#8a8f94" opacity="0"> upstream_repo acme/toolkit from the origin remote<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2021;0.2031;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="296" fill="#c5c8c6" opacity="0"> One question, for what the repository cannot tell me:<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2527;0.2537;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#c5c8c6" opacity="0"> good-first-issue-config.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3032;0.3042;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="344" fill="#8a8f94" opacity="0"> What counts as a good first issue here: labels, size…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3537;0.3547;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="368" fill="#c5c8c6" opacity="0"> issue-tracker-config.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4043;0.4053;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#8a8f94" opacity="0"> Tracker URL, project key, auth model, default query…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4548;0.4558;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="440" fill="#7f9f7f" opacity="0"> Written to .apache-magpie-local/ — nothing staged, nothing<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5053;0.5063;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="464" fill="#7f9f7f" opacity="0"> committed, no teammate affected.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5559;0.5569;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="512" fill="#8a8f94" opacity="0"> The project can also adopt Magpie, so contributors get this<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6064;0.6074;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="536" fill="#8a8f94" opacity="0"> on clone: /magpie-setup adopt<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6569;0.6579;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <rect x="26" y="523" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/wizard/pr-management.svg b/docs-assets/quickstart/wizard/pr-management.svg
new file mode 100644
index 0000000..8083099
--- /dev/null
+++ b/docs-assets/quickstart/wizard/pr-management.svg
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 715 712"
+ width="715" height="712" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated /magpie-setup config run for the pr-management family: the check failing, values derived from the repository, one question, and gitignored files written">
+ <title>/magpie-setup config — pr-management</title>
+ <desc>Illustrative animation of a configuration run for the pr-management family. Derived from the skills' declared required configuration.</desc>
+ <rect width="715" height="712" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="715" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="715" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /magpie-pr-management:<skill><animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="128" fill="#d8a657" opacity="0"> ✗ project configuration — 6 required, none found<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0388;0.0398;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#8a8f94" opacity="0"> Configuring now. Gitignored files in this clone only.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0776;0.0786;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="224" fill="#7f9f7f" opacity="0"> ✓ project.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1163;0.1173;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="248" fill="#8a8f94" opacity="0"> upstream_repo acme/toolkit from the origin remote<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1551;0.1561;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="296" fill="#c5c8c6" opacity="0"> One question, for what the repository cannot tell me:<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1939;0.1949;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#c5c8c6" opacity="0"> pr-management-code-review-criteria.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2327;0.2337;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="344" fill="#8a8f94" opacity="0"> List of project's review-criteria source files…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2714;0.2724;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="368" fill="#c5c8c6" opacity="0"> pr-management-config.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3102;0.3112;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#8a8f94" opacity="0"> Committers team handle, area-label prefix,…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3490;0.3500;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="416" fill="#c5c8c6" opacity="0"> pr-management-quick-merge-config.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3878;0.3888;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="440" fill="#8a8f94" opacity="0"> Thresholds, path globs, and the merge-command template…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4265;0.4275;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="464" fill="#c5c8c6" opacity="0"> pr-management-triage-comment-templates.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4653;0.4663;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="488" fill="#8a8f94" opacity="0"> Comment-body URLs (PR quality criteria, two-stage…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5041;0.5051;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="512" fill="#c5c8c6" opacity="0"> reviewer-roster.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5429;0.5439;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="536" fill="#8a8f94" opacity="0"> Who reviews what<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5816;0.5826;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="584" fill="#7f9f7f" opacity="0"> Written to .apache-magpie-local/ — nothing staged, nothing<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6204;0.6214;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="608" fill="#7f9f7f" opacity="0"> committed, no teammate affected.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6592;0.6602;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="656" fill="#8a8f94" opacity="0"> The project can also adopt Magpie, so contributors get this<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6980;0.6990;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <text x="26" y="680" fill="#8a8f94" opacity="0"> on clone: /magpie-setup adopt<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.7367;0.7377;1" dur="9.8s" repeatCount="indefinite"/></text>
+ <rect x="26" y="667" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/wizard/release-management.svg b/docs-assets/quickstart/wizard/release-management.svg
new file mode 100644
index 0000000..bc94356
--- /dev/null
+++ b/docs-assets/quickstart/wizard/release-management.svg
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 695 616"
+ width="695" height="616" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated /magpie-setup config run for the release-management family: the check failing, values derived from the repository, one question, and gitignored files written">
+ <title>/magpie-setup config — release-management</title>
+ <desc>Illustrative animation of a configuration run for the release-management family. Derived from the skills' declared required configuration.</desc>
+ <rect width="695" height="616" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="695" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="695" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /magpie-release-management:<skill><animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <text x="26" y="128" fill="#d8a657" opacity="0"> ✗ project configuration — 4 required, none found<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0459;0.0469;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#8a8f94" opacity="0"> Configuring now. Gitignored files in this clone only.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0918;0.0928;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <text x="26" y="248" fill="#c5c8c6" opacity="0"> One question, for what the repository cannot tell me:<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1377;0.1387;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <text x="26" y="272" fill="#c5c8c6" opacity="0"> pmc-roster.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1836;0.1846;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <text x="26" y="296" fill="#8a8f94" opacity="0"> Who is binding<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2295;0.2305;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#c5c8c6" opacity="0"> release-build.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2754;0.2764;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <text x="26" y="344" fill="#8a8f94" opacity="0"> How this project builds and signs artefacts: build…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3213;0.3223;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <text x="26" y="368" fill="#c5c8c6" opacity="0"> release-management-config.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3671;0.3681;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#8a8f94" opacity="0"> Vote window and pass rule, distribution backend and…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4130;0.4140;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <text x="26" y="416" fill="#c5c8c6" opacity="0"> release-trains.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4589;0.4599;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <text x="26" y="440" fill="#8a8f94" opacity="0"> Active release branches, release-manager attribution…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5048;0.5058;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <text x="26" y="488" fill="#7f9f7f" opacity="0"> Written to .apache-magpie-local/ — nothing staged, nothing<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5507;0.5517;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <text x="26" y="512" fill="#7f9f7f" opacity="0"> committed, no teammate affected.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5966;0.5976;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <text x="26" y="560" fill="#8a8f94" opacity="0"> The project can also adopt Magpie, so contributors get this<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6425;0.6435;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <text x="26" y="584" fill="#8a8f94" opacity="0"> on clone: /magpie-setup adopt<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6884;0.6894;1" dur="8.3s" repeatCount="indefinite"/></text>
+ <rect x="26" y="571" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/wizard/repo-health.svg b/docs-assets/quickstart/wizard/repo-health.svg
new file mode 100644
index 0000000..ecb5776
--- /dev/null
+++ b/docs-assets/quickstart/wizard/repo-health.svg
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 695 568"
+ width="695" height="568" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated /magpie-setup config run for the repo-health family: the check failing, values derived from the repository, one question, and gitignored files written">
+ <title>/magpie-setup config — repo-health</title>
+ <desc>Illustrative animation of a configuration run for the repo-health family. Derived from the skills' declared required configuration.</desc>
+ <rect width="695" height="568" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="695" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="695" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /magpie-repo-health:<skill><animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="128" fill="#d8a657" opacity="0"> ✗ project configuration — 3 required, none found<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0505;0.0515;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#8a8f94" opacity="0"> Configuring now. Gitignored files in this clone only.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1011;0.1021;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="248" fill="#c5c8c6" opacity="0"> One question, for what the repository cannot tell me:<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1516;0.1526;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="272" fill="#c5c8c6" opacity="0"> fix-workflow.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2021;0.2031;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="296" fill="#8a8f94" opacity="0"> Fork / clone / toolchain specifics, backport-label…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2527;0.2537;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#c5c8c6" opacity="0"> repo-health-config.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3032;0.3042;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="344" fill="#8a8f94" opacity="0"> Per-skill switches: deprecated runner labels, zizmor…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3537;0.3547;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="368" fill="#c5c8c6" opacity="0"> runtime-invocation.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4043;0.4053;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#8a8f94" opacity="0"> Build prerequisite, run-a-single-file recipe,…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4548;0.4558;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="440" fill="#7f9f7f" opacity="0"> Written to .apache-magpie-local/ — nothing staged, nothing<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5053;0.5063;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="464" fill="#7f9f7f" opacity="0"> committed, no teammate affected.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5559;0.5569;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="512" fill="#8a8f94" opacity="0"> The project can also adopt Magpie, so contributors get this<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6064;0.6074;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <text x="26" y="536" fill="#8a8f94" opacity="0"> on clone: /magpie-setup adopt<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6569;0.6579;1" dur="7.5s" repeatCount="indefinite"/></text>
+ <rect x="26" y="523" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/quickstart/wizard/security.svg b/docs-assets/quickstart/wizard/security.svg
new file mode 100644
index 0000000..b6afbe3
--- /dev/null
+++ b/docs-assets/quickstart/wizard/security.svg
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ GENERATED FILE - do not edit.
+
+ Written by tools/dev/render-wizard.py. Illustrative of the shape of a
+ run, not a recording of one.
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 726 856"
+ width="726" height="856" role="img"
+ data-magpie-generated="render-wizard"
+ aria-label="An animated /magpie-setup config run for the security family: the check failing, values derived from the repository, one question, and gitignored files written">
+ <title>/magpie-setup config — security</title>
+ <desc>Illustrative animation of a configuration run for the security family. Derived from the skills' declared required configuration.</desc>
+ <rect width="726" height="856" rx="10" fill="#1d1f21"/>
+ <rect x="0" y="0" width="726" height="34" rx="10" fill="#2b2e31"/>
+ <rect x="0" y="24" width="726" height="10" fill="#2b2e31"/>
+ <circle cx="22" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="44" cy="17" r="6" fill="#3f4448"/>
+ <circle cx="66" cy="17" r="6" fill="#3f4448"/>
+ <g font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="17" xml:space="preserve">
+ <text x="26" y="80" fill="#8abeb7" opacity="0">> /magpie-security:<skill><animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0000;0.0010;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="128" fill="#d8a657" opacity="0"> ✗ project configuration — 9 required, none found<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0315;0.0325;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="176" fill="#8a8f94" opacity="0"> Configuring now. Gitignored files in this clone only.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0629;0.0639;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="224" fill="#7f9f7f" opacity="0"> ✓ project.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.0944;0.0954;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="248" fill="#8a8f94" opacity="0"> upstream_repo acme/toolkit from the origin remote<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1258;0.1268;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="296" fill="#c5c8c6" opacity="0"> One question, for what the repository cannot tell me:<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1573;0.1583;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="320" fill="#c5c8c6" opacity="0"> fix-workflow.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.1887;0.1897;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="344" fill="#8a8f94" opacity="0"> Fork / clone / toolchain specifics, backport-label…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2202;0.2212;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="368" fill="#c5c8c6" opacity="0"> milestones.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2517;0.2527;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="392" fill="#8a8f94" opacity="0"> Milestone naming conventions + create-and-assign recipe<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.2831;0.2841;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="416" fill="#c5c8c6" opacity="0"> scanner-products.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3146;0.3156;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="440" fill="#8a8f94" opacity="0"> Private scanner product names, and the…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3460;0.3470;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="464" fill="#c5c8c6" opacity="0"> scope-labels.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.3775;0.3785;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="488" fill="#8a8f94" opacity="0"> Scope label → CVE product / `packageName` /…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4089;0.4099;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="512" fill="#c5c8c6" opacity="0"> security-intake-config.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4404;0.4414;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="536" fill="#8a8f94" opacity="0"> Capability-flag vocabulary for the intake path: how…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.4719;0.4729;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="560" fill="#c5c8c6" opacity="0"> security-model.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5033;0.5043;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="584" fill="#8a8f94" opacity="0"> Authoritative URL for the project's Security Model +…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5348;0.5358;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="608" fill="#c5c8c6" opacity="0"> security-tracker-stats.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5662;0.5672;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="632" fill="#8a8f94" opacity="0"> Which tracker fields and windows the stats dashboard…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.5977;0.5987;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="656" fill="#c5c8c6" opacity="0"> title-normalization.md<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6291;0.6301;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="680" fill="#8a8f94" opacity="0"> Regex cascade the `security-cve-allocate` skill applies…<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6606;0.6616;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="728" fill="#7f9f7f" opacity="0"> Written to .apache-magpie-local/ — nothing staged, nothing<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.6921;0.6931;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="752" fill="#7f9f7f" opacity="0"> committed, no teammate affected.<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.7235;0.7245;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="800" fill="#8a8f94" opacity="0"> The project can also adopt Magpie, so contributors get this<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.7550;0.7560;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <text x="26" y="824" fill="#8a8f94" opacity="0"> on clone: /magpie-setup adopt<animate attributeName="opacity" values="0;0;1;1" keyTimes="0;0.7864;0.7874;1" dur="12.1s" repeatCount="indefinite"/></text>
+ <rect x="26" y="811" width="10" height="17" fill="#c5c8c6"><animate attributeName="opacity" values="1;1;0;0;1" dur="1.2s" repeatCount="indefinite"/></rect>
+ </g>
+</svg>
diff --git a/docs-assets/sandbox-blocks-read.png b/docs-assets/sandbox-blocks-read.png
new file mode 100644
index 0000000..f1f0a26
Binary files /dev/null and b/docs-assets/sandbox-blocks-read.png differ
diff --git a/docs-assets/sandbox-bypass-banner.png b/docs-assets/sandbox-bypass-banner.png
new file mode 100644
index 0000000..2af64d3
Binary files /dev/null and b/docs-assets/sandbox-bypass-banner.png differ
diff --git a/docs-assets/sandbox-modes.png b/docs-assets/sandbox-modes.png
new file mode 100644
index 0000000..7b15e17
Binary files /dev/null and b/docs-assets/sandbox-modes.png differ
diff --git a/docs-assets/sandbox-os-level-block.png b/docs-assets/sandbox-os-level-block.png
new file mode 100644
index 0000000..5871fbe
Binary files /dev/null and b/docs-assets/sandbox-os-level-block.png differ
diff --git a/docs-assets/session-no-sandbox.png b/docs-assets/session-no-sandbox.png
new file mode 100644
index 0000000..a201da8
Binary files /dev/null and b/docs-assets/session-no-sandbox.png differ
diff --git a/docs-assets/session-sandboxed.png b/docs-assets/session-sandboxed.png
new file mode 100644
index 0000000..14b1d9d
Binary files /dev/null and b/docs-assets/session-sandboxed.png differ
diff --git a/docs/adapters/add-a-harness.md b/docs/adapters/add-a-harness.md
new file mode 100644
index 0000000..cfca92c
--- /dev/null
+++ b/docs/adapters/add-a-harness.md
@@ -0,0 +1,282 @@
+# Adding a new agent harness
+
+Rendered page: https://magpie.apache.org/docs/adapters/add-a-harness/
+
+Source: https://github.com/apache/magpie/blob/main/docs/adapters/add-a-harness.md
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+This recipe names every step to wire a new agentic harness into
+Magpie so it loads skills, enforces the action guard, and runs
+the spec-loop. It is the counterpart to the
+[tool-adapter authoring guide](/docs/adapters/authoring) — that guide adds a
+new *backend* (forge, VCS, mail system); this guide adds a new
+*agent harness*.
+
+The framework's skills are plain
+[`AGENTS.md`](https://agents.md/)-standard Markdown. No runtime
+gets its own copy or variant of a skill — the content is
+byte-identical. What differs per runtime is:
+
+1. **Where on disk it looks for skills** (the symlink relay).
+2. **Whether it enforces the action guard** (the pre-tool hook).
+3. **How the spec-loop invokes it headlessly** (the `--cli` profile).
+4. **Which substrate tools list it** (the `**Harness:**` declarations).
+
+Steps 1 and 3 are always required. Step 2 is required for runtimes
+that support a pre-tool hook API (and a matter of OS-level fallback for
+those that do not). Step 4 is a metadata update, not executable code.
+
+---
+
+## Step 1 — add a row to the agent-target registry
+
+The single source of truth for *where each runtime reads skills from* is
+[`skills/setup/agents.md`](https://github.com/apache/magpie/blob/main/skills/setup/agents.md). Add one row:
+
+```markdown
+| `<id>` | `.<runtime>/skills/` | native (relay) | <Runtime name> |
+```
+
+- `<id>` — a short, lowercase, hyphen-safe identifier (e.g. `kiro`,
+ `aider`, `openhands`).
+- `<runtime>/skills/` — the path the runtime reads for project-scope
+ skills. Check the runtime's docs; if it reads `.agents/skills/`
+ directly (like Codex, Cursor, Gemini CLI) no new row is needed —
+ the `universal` row already covers it.
+- `native (relay)` — used for runtimes with their own per-agent
+ directory. Leave the *kind* column as `native (relay)` if the
+ directory is distinct from `.agents/skills/`; use `universal` only
+ for runtimes that read `.agents/` natively.
+
+Once the row is present, `/magpie-setup install` and `upgrade` wire the
+relay symlinks automatically. The rules are:
+
+- The *canonical* entry lives at `.agents/skills/magpie-<skill>` and
+ points at the skill source.
+- Every relay entry at `.<runtime>/skills/magpie-<skill>` points at
+ `../../.agents/skills/magpie-<skill>` — **through the canonical, not
+ straight at source**.
+
+`symlink-lint` enforces the working-tree rules and is wired into `prek`; run it to
+verify after any manual link creation:
+
+```bash
+uv run --project tools/symlink-lint symlink-lint
+```
+
+## Step 2 — wire the action guard
+
+The action guard (`tools/agent-guard`) intercepts shell commands *before*
+they run and denies ones that break hard framework rules (unauthorized
+`git push`, wrong commit-trailer format, premature `--ready-for-review`,
+…). The guard *decisions* live in one harness-agnostic `dispatch()` core;
+each harness gets a thin adapter translating its hook format.
+
+**For runtimes with a pre-tool hook API:** add an adapter following the
+existing OpenCode example.
+
+```text
+tools/agent-guard/
+ src/agent_guard/__init__.py ← dispatch() core + thin CLI adapters
+ src/agent_guard/guards.d/ ← individual guard scripts
+ opencode/plugin.js ← OpenCode adapter (JS plugin)
+ tests/ ← test suite including per-harness cases
+```
+
+The core (`__init__.py`) exposes `dispatch()` plus one thin `*_main()`
+function per hook-shaped harness (`opencode_main()`, `kiro_main()`,
+…). The `cli()` router near the end of the file selects those adapters
+from flags such as `--opencode` and `--kiro`. To add another hook-shaped
+harness, follow that pattern:
+
+1. Parse the harness's pre-tool hook payload (stdin JSON, env vars,
+ CLI args, or a native plugin format — check the runtime docs).
+2. Call `dispatch(command_string)` from the core module.
+3. Return the harness's expected "allow" or "block" response.
+4. Add a `--<runtime>` branch in `cli()` that routes to the new
+ `*_main()` function.
+
+Run the guard's test suite to verify the adapter:
+
+```bash
+uv run --project tools/agent-guard --group dev pytest
+```
+
+**For runtimes without a hook API:** document the limitation explicitly
+in the row's notes in `skills/setup/agents.md`. An OS-level wrapper
+(e.g. `bubblewrap` on Linux, `sandbox-exec` on macOS, or a custom
+`PATH`-shadowing script that intercepts `git push` and `gh pr create`)
+can enforce the rules at the process level without a harness hook. The
+credential-strip layer is already available for any runtime:
+
+```bash
+# Source agent-iso.sh and use the generic entry point:
+source /path/to/magpie/tools/agent-isolation/agent-iso.sh
+agent-iso <your-runtime-cli> [cli-args]
+```
+
+See [`tools/agent-isolation/README.md`](https://github.com/apache/magpie/blob/main/tools/agent-isolation/README.md)
+for the full generic-harness usage. The `agent-iso` entry point works
+for any CLI; the Claude-specific `--settings` sandbox grant is skipped
+automatically. For deeper enforcement (action guard, confirmation
+prompts), a harness-specific adapter is still needed.
+
+Whatever the enforcement mechanism, update the affected substrate tool
+READMEs (step 4) to declare the new harness in their `**Harness:**` line
+once support lands.
+
+## Step 3 — add a spec-loop runner profile
+
+The spec-loop (`tools/spec-loop/loop.sh`) runs the build/plan/update/
+consolidate beats headlessly.
+Each runtime has its own non-interactive invocation and approval behavior.
+Add your runtime's convention in two places.
+
+**`tools/spec-loop/loop.sh` — harness detection:**
+
+```bash
+case "${SPEC_LOOP_HARNESS:-$(basename "$AGENT")}" in
+ *codex*) HARNESS=codex ;;
+ *cursor*) HARNESS=cursor ;;
+ *gemini*) HARNESS=gemini ;;
+ *opencode*) HARNESS=opencode ;;
+ *kiro*) HARNESS=kiro ;;
+ *<runtime>*) HARNESS=<runtime> ;; # add your case here
+ *) HARNESS=claude ;;
+esac
+```
+
+**`tools/spec-loop/lib.sh` — headless invocation:**
+
+Add a branch inside `spec_loop_launch_agent()` following the existing
+patterns. Each branch runs the agent in the background (`&`) with:
+
+- the runtime's documented headless flags, consistent with its security profile;
+ document any change to approval or sandbox behavior, including upgrade impact, in the runtime adapter and PR description;
+- `--model "$model"` forwarded when non-empty;
+- `SPEC_LOOP_EFFORT` mapped when the CLI has a reasoning-effort knob
+ (see the effort table in
+ [`tools/spec-loop/specs/spec-loop-runner.md`](https://github.com/apache/magpie/blob/main/tools/spec-loop/specs/spec-loop-runner.md));
+ if the CLI has no such flag, omit silently like Cursor/Gemini — do not
+ warn;
+- the prompt fed via stdin, a file argument, or a flag — whatever the
+ runtime accepts.
+
+Example template:
+
+```bash
+elif [ "$harness" = "<runtime>" ]; then
+ local effort_args=()
+ case "$effort" in
+ low) effort_args=(--<effort-flag> <low-value>) ;;
+ medium) effort_args=(--<effort-flag> <medium-value>) ;;
+ high) effort_args=(--<effort-flag> <high-or-top-value>) ;;
+ esac
+ "$agent" <headless-flag> \
+ ${model_args[@]+"${model_args[@]}"} \
+ ${effort_args[@]+"${effort_args[@]}"} \
+ "$(cat "$prompt_file")" &
+```
+
+Take the flag name and accepted values from the runtime's own `--help`,
+record them in the effort matrix, and map framework `high` to the CLI's
+top sensible value when it offers more levels than `low|medium|high`.
+
+Validate the loop syntax after editing:
+
+```bash
+bash -n tools/spec-loop/loop.sh && bash -n tools/spec-loop/lib.sh
+```
+
+If the runtime supports a structured-output or JSON-stream mode
+equivalent to Claude's `--output-format stream-json`, wire it via an
+`$output_format` check (see the Cursor branch for an example).
+
+## Step 4 — update tool harness declarations
+
+Substrate tools that are harness-coupled declare `**Harness:**` in their
+README. When your new runtime uses one of these tools, update its line:
+
+| Tool | Current harness declaration |
+|---|---|
+| `tools/agent-guard` | `**Harness:** Claude Code, OpenCode, Kiro, Gemini CLI` |
+| `tools/agent-isolation` | `**Harness:** agnostic` |
+| `tools/permission-audit` | `**Harness:** agnostic` |
+| `tools/sandbox-lint` | `**Harness:** Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Kiro` |
+| `tools/spec-loop` | `**Harness:** Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Kiro` |
+
+`tools/agent-isolation` already exposes a harness-agnostic `agent-iso <cli>` entry
+point — no update needed for new runtimes (see
+[`tools/agent-isolation/README.md`](https://github.com/apache/magpie/blob/main/tools/agent-isolation/README.md)).
+Add your runtime to every other tool it integrates with. Tools that declare
+`**Harness:** any` or `agnostic` need no change — they work under any runtime
+unchanged. After updating, refresh the vendor-neutrality score:
+
+```bash
+uv run --project tools/vendor-neutrality-score vendor-neutrality-score --markdown
+```
+
+Copy the generated block into `docs/vendor-neutrality.md` as instructed
+in its comment header.
+
+## Step 5 — validate the full wiring
+
+```bash
+# 1. Symlink topology (no cycles, correct relay direction)
+uv run --project tools/symlink-lint symlink-lint
+
+# 2. Skill + tool metadata (capability, prerequisites, organization lines)
+uv run --project tools/skill-and-tool-validator --group dev skill-and-tool-validate
+
+# 3. Guard tests (if you added a guard adapter in step 2)
+uv run --project tools/agent-guard --group dev pytest
+
+# 4. Loop syntax
+bash -n tools/spec-loop/loop.sh && bash -n tools/spec-loop/lib.sh
+```
+
+All four must pass before opening a PR.
+
+## Scope of a first-class harness integration
+
+A minimal integration lands steps 1 + 3: skills load, the loop runs.
+Steps 2 and 4 are what turn "skills load" into "skills run safely."
+The recommended order for a community contribution:
+
+1. **Open a tracking issue** (or claim the existing one for your
+ runtime — see `docs/vendor-neutrality.md` § Agentic harness for the
+ issue list).
+2. **Land the registry row + relay symlinks** (step 1) — small PR,
+ unblocks users immediately.
+3. **Land the loop profile** (step 3) — small PR, enables spec-loop
+ use.
+4. **Land the guard adapter or OS-level wrapper** (step 2) — the most
+ harness-specific work; can be a follow-up PR.
+5. **Update harness declarations** (step 4) — include in whichever PR
+ lands the first substantive integration point.
+
+This matches how Claude Code and OpenCode integrations were built: the
+skill path landed first, then guard, then loop, then full harness table.
+
+## See also
+
+- [`skills/setup/agents.md`](https://github.com/apache/magpie/blob/main/skills/setup/agents.md) — the
+ agent-target registry (single source of truth for symlink paths).
+- [`tools/symlink-lint/`](https://github.com/apache/magpie/tree/main/tools/symlink-lint/) — enforces relay
+ symlink correctness.
+- [`tools/agent-guard/`](https://github.com/apache/magpie/tree/main/tools/agent-guard/) — the action guard
+ core and per-harness adapters.
+- [`tools/agent-isolation/`](https://github.com/apache/magpie/tree/main/tools/agent-isolation/) — the
+ clean-environment launcher (OS-level complement to the agent hook).
+- [`tools/spec-loop/loop.sh`](https://github.com/apache/magpie/blob/main/tools/spec-loop/loop.sh) and
+ `lib.sh` — the spec-loop runner with per-harness invocation profiles.
+- [`docs/vendor-neutrality.md`](/docs/vendor-neutrality) § Agentic
+ runtime — the open tracking issues per runtime and the neutrality
+ rationale.
+- [`docs/adapters/authoring.md`](/docs/adapters/authoring) — the analogous recipe
+ for adding a new tool backend (forge, VCS, mail archive, CNA).
diff --git a/docs/adapters/add-a-harness/index.html b/docs/adapters/add-a-harness/index.html
new file mode 100644
index 0000000..102ec03
--- /dev/null
+++ b/docs/adapters/add-a-harness/index.html
@@ -0,0 +1,290 @@
+<!DOCTYPE html><html lang="en" data-astro-cid-z4jru4n3><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="description" content="AI-powered assistant for open-source maintainers. Triage, mentor, draft, pair, and auto-merge under Apache Software Foundation governance."><link rel="icon" type="image/svg+xml" href="/favicon.svg"><link rel="icon" type="image/x-icon" sizes="any" href="/favicon.ico"><title>Adding a new agent harness — Ap [...]
+ var _paq = (window._paq = window._paq || []);
+ /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
+ _paq.push(["setDoNotTrack", true]);
+ _paq.push(["disableCookies"]);
+ _paq.push(["trackPageView"]);
+ _paq.push(["enableLinkTracking"]);
+ (function () {
+ var u = "https://analytics.apache.org/";
+ _paq.push(["setTrackerUrl", u + "matomo.php"]);
+ _paq.push(["setSiteId", "89"]);
+ var d = document,
+ g = d.createElement("script"),
+ s = d.getElementsByTagName("script")[0];
+ g.async = true;
+ g.src = u + "matomo.js";
+ s.parentNode.insertBefore(g, s);
+ })();
+ </script><link rel="stylesheet" href="/_astro/SiteFooter.C2Dgj2WR.css"><style>.tree-summary[data-astro-cid-lihgpoae]{list-style:none}.tree-summary[data-astro-cid-lihgpoae]::-webkit-details-marker{display:none}.tree-chevron[data-astro-cid-lihgpoae]{color:var(--color-subtext-color);transition:transform .15s}details[data-astro-cid-lihgpoae][open]>.tree-summary[data-astro-cid-lihgpoae] .tree-chevron[data-astro-cid-lihgpoae]{transform:rotate(90deg)}.prose h1{color:var(--color-default-font [...]
+</style></head><body data-astro-cid-z4jru4n3><nav class="relative z-10 flex w-full items-center justify-between bg-default-background px-8 py-5 mobile:px-4"><a href="/" aria-label="Apache Magpie home" class="flex items-end justify-end gap-2 px-2 py-2"><img class="h-10 w-10 flex-none object-cover" src="/subframe-mark.svg" alt="Apache Magpie"/><img class="h-10 flex-none object-contain" src="/subframe-wordmark.png" alt="Magpie"/><span class="self-center -mt-2 -ml-2 text-[10px] font-[700] le [...]
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<h1 id="adding-a-new-agent-harness">Adding a new agent harness</h1>
+<p>This recipe names every step to wire a new agentic harness into
+Magpie so it loads skills, enforces the action guard, and runs
+the spec-loop. It is the counterpart to the
+<a href="/docs/adapters/authoring">tool-adapter authoring guide</a> — that guide adds a
+new <em>backend</em> (forge, VCS, mail system); this guide adds a new
+<em>agent harness</em>.</p>
+<p>The framework’s skills are plain
+<a href="https://agents.md/"><code>AGENTS.md</code></a>-standard Markdown. No runtime
+gets its own copy or variant of a skill — the content is
+byte-identical. What differs per runtime is:</p>
+<ol>
+<li><strong>Where on disk it looks for skills</strong> (the symlink relay).</li>
+<li><strong>Whether it enforces the action guard</strong> (the pre-tool hook).</li>
+<li><strong>How the spec-loop invokes it headlessly</strong> (the <code>--cli</code> profile).</li>
+<li><strong>Which substrate tools list it</strong> (the <code>**Harness:**</code> declarations).</li>
+</ol>
+<p>Steps 1 and 3 are always required. Step 2 is required for runtimes
+that support a pre-tool hook API (and a matter of OS-level fallback for
+those that do not). Step 4 is a metadata update, not executable code.</p>
+<hr>
+<h2 id="step-1--add-a-row-to-the-agent-target-registry">Step 1 — add a row to the agent-target registry</h2>
+<p>The single source of truth for <em>where each runtime reads skills from</em> is
+<a href="https://github.com/apache/magpie/blob/main/skills/setup/agents.md"><code>skills/setup/agents.md</code></a>. Add one row:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="markdown"><code><span class="line"><span style="color:#E1E4E8">| </span><span style="color:#79B8FF">`<id>`</span><span style="color:#E1E4E8"> | </span><span style="color:#79B8FF">`.<runtime>/skills/`</span><span style="color:#E1E4E8"> | native (relay) | <Runtime name> |</span></span></code></pre>
+<ul>
+<li><code><id></code> — a short, lowercase, hyphen-safe identifier (e.g. <code>kiro</code>,
+<code>aider</code>, <code>openhands</code>).</li>
+<li><code><runtime>/skills/</code> — the path the runtime reads for project-scope
+skills. Check the runtime’s docs; if it reads <code>.agents/skills/</code>
+directly (like Codex, Cursor, Gemini CLI) no new row is needed —
+the <code>universal</code> row already covers it.</li>
+<li><code>native (relay)</code> — used for runtimes with their own per-agent
+directory. Leave the <em>kind</em> column as <code>native (relay)</code> if the
+directory is distinct from <code>.agents/skills/</code>; use <code>universal</code> only
+for runtimes that read <code>.agents/</code> natively.</li>
+</ul>
+<p>Once the row is present, <code>/magpie-setup install</code> and <code>upgrade</code> wire the
+relay symlinks automatically. The rules are:</p>
+<ul>
+<li>The <em>canonical</em> entry lives at <code>.agents/skills/magpie-<skill></code> and
+points at the skill source.</li>
+<li>Every relay entry at <code>.<runtime>/skills/magpie-<skill></code> points at
+<code>../../.agents/skills/magpie-<skill></code> — <strong>through the canonical, not
+straight at source</strong>.</li>
+</ul>
+<p><code>symlink-lint</code> enforces the working-tree rules and is wired into <code>prek</code>; run it to
+verify after any manual link creation:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> tools/symlink-lint</span><span style="color:#9ECBFF"> symlink-lint</span></span></code></pre>
+<h2 id="step-2--wire-the-action-guard">Step 2 — wire the action guard</h2>
+<p>The action guard (<code>tools/agent-guard</code>) intercepts shell commands <em>before</em>
+they run and denies ones that break hard framework rules (unauthorized
+<code>git push</code>, wrong commit-trailer format, premature <code>--ready-for-review</code>,
+…). The guard <em>decisions</em> live in one harness-agnostic <code>dispatch()</code> core;
+each harness gets a thin adapter translating its hook format.</p>
+<p><strong>For runtimes with a pre-tool hook API:</strong> add an adapter following the
+existing OpenCode example.</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="text"><code><span class="line"><span>tools/agent-guard/</span></span>
+<span class="line"><span> src/agent_guard/__init__.py ← dispatch() core + thin CLI adapters</span></span>
+<span class="line"><span> src/agent_guard/guards.d/ ← individual guard scripts</span></span>
+<span class="line"><span> opencode/plugin.js ← OpenCode adapter (JS plugin)</span></span>
+<span class="line"><span> tests/ ← test suite including per-harness cases</span></span></code></pre>
+<p>The core (<code>__init__.py</code>) exposes <code>dispatch()</code> plus one thin <code>*_main()</code>
+function per hook-shaped harness (<code>opencode_main()</code>, <code>kiro_main()</code>,
+…). The <code>cli()</code> router near the end of the file selects those adapters
+from flags such as <code>--opencode</code> and <code>--kiro</code>. To add another hook-shaped
+harness, follow that pattern:</p>
+<ol>
+<li>Parse the harness’s pre-tool hook payload (stdin JSON, env vars,
+CLI args, or a native plugin format — check the runtime docs).</li>
+<li>Call <code>dispatch(command_string)</code> from the core module.</li>
+<li>Return the harness’s expected “allow” or “block” response.</li>
+<li>Add a <code>--<runtime></code> branch in <code>cli()</code> that routes to the new
+<code>*_main()</code> function.</li>
+</ol>
+<p>Run the guard’s test suite to verify the adapter:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> tools/agent-guard</span><span style="color:#79B8FF"> --group</span><span style="color:#9ECBFF"> dev</span><span style="color:#9ECBFF"> pytest</span></span></code></pre>
+<p><strong>For runtimes without a hook API:</strong> document the limitation explicitly
+in the row’s notes in <code>skills/setup/agents.md</code>. An OS-level wrapper
+(e.g. <code>bubblewrap</code> on Linux, <code>sandbox-exec</code> on macOS, or a custom
+<code>PATH</code>-shadowing script that intercepts <code>git push</code> and <code>gh pr create</code>)
+can enforce the rules at the process level without a harness hook. The
+credential-strip layer is already available for any runtime:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#6A737D"># Source agent-iso.sh and use the generic entry point:</span></span>
+<span class="line"><span style="color:#79B8FF">source</span><span style="color:#9ECBFF"> /path/to/magpie/tools/agent-isolation/agent-iso.sh</span></span>
+<span class="line"><span style="color:#B392F0">agent-iso</span><span style="color:#F97583"> <</span><span style="color:#9ECBFF">your-runtime-cl</span><span style="color:#E1E4E8">i</span><span style="color:#F97583">></span><span style="color:#E1E4E8"> [cli-args]</span></span></code></pre>
+<p>See <a href="https://github.com/apache/magpie/blob/main/tools/agent-isolation/README.md"><code>tools/agent-isolation/README.md</code></a>
+for the full generic-harness usage. The <code>agent-iso</code> entry point works
+for any CLI; the Claude-specific <code>--settings</code> sandbox grant is skipped
+automatically. For deeper enforcement (action guard, confirmation
+prompts), a harness-specific adapter is still needed.</p>
+<p>Whatever the enforcement mechanism, update the affected substrate tool
+READMEs (step 4) to declare the new harness in their <code>**Harness:**</code> line
+once support lands.</p>
+<h2 id="step-3--add-a-spec-loop-runner-profile">Step 3 — add a spec-loop runner profile</h2>
+<p>The spec-loop (<code>tools/spec-loop/loop.sh</code>) runs the build/plan/update/
+consolidate beats headlessly.
+Each runtime has its own non-interactive invocation and approval behavior.
+Add your runtime’s convention in two places.</p>
+<p><strong><code>tools/spec-loop/loop.sh</code> — harness detection:</strong></p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#F97583">case</span><span style="color:#9ECBFF"> "${</span><span style="color:#E1E4E8">SPEC_LOOP_HARNESS</span><span style="color:#F97583">:-</span><span style="color:#9ECBFF">$(</span><span style="color:#E1E4E8">basename</span><span style="color:#9ECBFF"> "</span><span style="color:#E1E4E8">$AGENT</span><span [...]
+<span class="line"><span style="color:#F97583"> *</span><span style="color:#DBEDFF">codex</span><span style="color:#F97583">*</span><span style="color:#F97583">)</span><span style="color:#E1E4E8"> HARNESS</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">codex</span><span style="color:#E1E4E8"> ;;</span></span>
+<span class="line"><span style="color:#F97583"> *</span><span style="color:#DBEDFF">cursor</span><span style="color:#F97583">*</span><span style="color:#F97583">)</span><span style="color:#E1E4E8"> HARNESS</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">cursor</span><span style="color:#E1E4E8"> ;;</span></span>
+<span class="line"><span style="color:#F97583"> *</span><span style="color:#DBEDFF">gemini</span><span style="color:#F97583">*</span><span style="color:#F97583">)</span><span style="color:#E1E4E8"> HARNESS</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">gemini</span><span style="color:#E1E4E8"> ;;</span></span>
+<span class="line"><span style="color:#F97583"> *</span><span style="color:#DBEDFF">opencode</span><span style="color:#F97583">*</span><span style="color:#F97583">)</span><span style="color:#E1E4E8"> HARNESS</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">opencode</span><span style="color:#E1E4E8"> ;;</span></span>
+<span class="line"><span style="color:#F97583"> *</span><span style="color:#DBEDFF">kiro</span><span style="color:#F97583">*</span><span style="color:#F97583">)</span><span style="color:#E1E4E8"> HARNESS</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">kiro</span><span style="color:#E1E4E8"> ;;</span></span>
+<span class="line"><span style="color:#F97583"> *</span><span style="color:#DBEDFF"><runtime></span><span style="color:#F97583">*</span><span style="color:#F97583">)</span><span style="color:#E1E4E8"> HARNESS</span><span style="color:#F97583">=<</span><span style="color:#9ECBFF">runtime</span><span style="color:#F97583">></span><span style="color:#E1E4E8"> ;; </span><span style="color:#6A737D"># add your case here</span></span>
+<span class="line"><span style="color:#F97583"> *)</span><span style="color:#E1E4E8"> HARNESS</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">claude</span><span style="color:#E1E4E8"> ;;</span></span>
+<span class="line"><span style="color:#F97583">esac</span></span></code></pre>
+<p><strong><code>tools/spec-loop/lib.sh</code> — headless invocation:</strong></p>
+<p>Add a branch inside <code>spec_loop_launch_agent()</code> following the existing
+patterns. Each branch runs the agent in the background (<code>&</code>) with:</p>
+<ul>
+<li>the runtime’s documented headless flags, consistent with its security profile;
+document any change to approval or sandbox behavior, including upgrade impact, in the runtime adapter and PR description;</li>
+<li><code>--model "$model"</code> forwarded when non-empty;</li>
+<li><code>SPEC_LOOP_EFFORT</code> mapped when the CLI has a reasoning-effort knob
+(see the effort table in
+<a href="https://github.com/apache/magpie/blob/main/tools/spec-loop/specs/spec-loop-runner.md"><code>tools/spec-loop/specs/spec-loop-runner.md</code></a>);
+if the CLI has no such flag, omit silently like Cursor/Gemini — do not
+warn;</li>
+<li>the prompt fed via stdin, a file argument, or a flag — whatever the
+runtime accepts.</li>
+</ul>
+<p>Example template:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#F97583">elif</span><span style="color:#E1E4E8"> [ </span><span style="color:#9ECBFF">"</span><span style="color:#E1E4E8">$harness</span><span style="color:#9ECBFF">"</span><span style="color:#F97583"> =</span><span style="color:#9ECBFF"> "<runtime>"</span><span style="color:#E1E4E8"> ]; </span><span styl [...]
+<span class="line"><span style="color:#F97583"> local</span><span style="color:#E1E4E8"> effort_args</span><span style="color:#F97583">=</span><span style="color:#E1E4E8">()</span></span>
+<span class="line"><span style="color:#F97583"> case</span><span style="color:#9ECBFF"> "</span><span style="color:#E1E4E8">$effort</span><span style="color:#9ECBFF">"</span><span style="color:#F97583"> in</span></span>
+<span class="line"><span style="color:#DBEDFF"> low</span><span style="color:#F97583">)</span><span style="color:#E1E4E8"> effort_args</span><span style="color:#F97583">=</span><span style="color:#E1E4E8">(</span><span style="color:#9ECBFF">--</span><span style="color:#F97583"><</span><span style="color:#9ECBFF">effort-flag</span><span style="color:#F97583">></span><span style="color:#F97583"> <</span><span style="color:#9ECBFF">low-value</span><span style="color:#F975 [...]
+<span class="line"><span style="color:#DBEDFF"> medium</span><span style="color:#F97583">)</span><span style="color:#E1E4E8"> effort_args</span><span style="color:#F97583">=</span><span style="color:#E1E4E8">(</span><span style="color:#9ECBFF">--</span><span style="color:#F97583"><</span><span style="color:#9ECBFF">effort-flag</span><span style="color:#F97583">></span><span style="color:#F97583"> <</span><span style="color:#9ECBFF">medium-value</span><span style="color:#F [...]
+<span class="line"><span style="color:#DBEDFF"> high</span><span style="color:#F97583">)</span><span style="color:#E1E4E8"> effort_args</span><span style="color:#F97583">=</span><span style="color:#E1E4E8">(</span><span style="color:#9ECBFF">--</span><span style="color:#F97583"><</span><span style="color:#9ECBFF">effort-flag</span><span style="color:#F97583">></span><span style="color:#F97583"> <</span><span style="color:#9ECBFF">high-or-top-value</span><span style="col [...]
+<span class="line"><span style="color:#F97583"> esac</span></span>
+<span class="line"><span style="color:#B392F0"> "</span><span style="color:#E1E4E8">$agent</span><span style="color:#B392F0">"</span><span style="color:#F97583"> <</span><span style="color:#9ECBFF">headless-fla</span><span style="color:#E1E4E8">g</span><span style="color:#F97583">></span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#E1E4E8"> ${model_args[</span><span style="color:#F97583">@</span><span style="color:#E1E4E8">]+</span><span style="color:#9ECBFF">"${</span><span style="color:#E1E4E8">model_args</span><span style="color:#9ECBFF">[</span><span style="color:#F97583">@</span><span style="color:#9ECBFF">]}"</span><span style="color:#E1E4E8">} </span><span style="color:#79B8FF">\</span></span>
+<span class="line"><span style="color:#E1E4E8"> ${effort_args[</span><span style="color:#F97583">@</span><span style="color:#E1E4E8">]+</span><span style="color:#9ECBFF">"${</span><span style="color:#E1E4E8">effort_args</span><span style="color:#9ECBFF">[</span><span style="color:#F97583">@</span><span style="color:#9ECBFF">]}"</span><span style="color:#E1E4E8">} </span><span style="color:#79B8FF">\</span></span>
+<span class="line"><span style="color:#9ECBFF"> "$(</span><span style="color:#B392F0">cat</span><span style="color:#9ECBFF"> "</span><span style="color:#E1E4E8">$prompt_file</span><span style="color:#9ECBFF">")"</span><span style="color:#E1E4E8"> &</span></span></code></pre>
+<p>Take the flag name and accepted values from the runtime’s own <code>--help</code>,
+record them in the effort matrix, and map framework <code>high</code> to the CLI’s
+top sensible value when it offers more levels than <code>low|medium|high</code>.</p>
+<p>Validate the loop syntax after editing:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#B392F0">bash</span><span style="color:#79B8FF"> -n</span><span style="color:#9ECBFF"> tools/spec-loop/loop.sh</span><span style="color:#E1E4E8"> && </span><span style="color:#B392F0">bash</span><span style="color:#79B8FF"> -n</span><span style="color:#9ECBFF"> tools/spec-loop/lib.sh</span></span></code></pre>
+<p>If the runtime supports a structured-output or JSON-stream mode
+equivalent to Claude’s <code>--output-format stream-json</code>, wire it via an
+<code>$output_format</code> check (see the Cursor branch for an example).</p>
+<h2 id="step-4--update-tool-harness-declarations">Step 4 — update tool harness declarations</h2>
+<p>Substrate tools that are harness-coupled declare <code>**Harness:**</code> in their
+README. When your new runtime uses one of these tools, update its line:</p>
+<table>
+<thead>
+<tr>
+<th>Tool</th>
+<th>Current harness declaration</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>tools/agent-guard</code></td>
+<td><code>**Harness:** Claude Code, OpenCode, Kiro, Gemini CLI</code></td>
+</tr>
+<tr>
+<td><code>tools/agent-isolation</code></td>
+<td><code>**Harness:** agnostic</code></td>
+</tr>
+<tr>
+<td><code>tools/permission-audit</code></td>
+<td><code>**Harness:** agnostic</code></td>
+</tr>
+<tr>
+<td><code>tools/sandbox-lint</code></td>
+<td><code>**Harness:** Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Kiro</code></td>
+</tr>
+<tr>
+<td><code>tools/spec-loop</code></td>
+<td><code>**Harness:** Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Kiro</code></td>
+</tr>
+</tbody>
+</table>
+<p><code>tools/agent-isolation</code> already exposes a harness-agnostic <code>agent-iso <cli></code> entry
+point — no update needed for new runtimes (see
+<a href="https://github.com/apache/magpie/blob/main/tools/agent-isolation/README.md"><code>tools/agent-isolation/README.md</code></a>).
+Add your runtime to every other tool it integrates with. Tools that declare
+<code>**Harness:** any</code> or <code>agnostic</code> need no change — they work under any runtime
+unchanged. After updating, refresh the vendor-neutrality score:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> tools/vendor-neutrality-score</span><span style="color:#9ECBFF"> vendor-neutrality-score</span><span style="color:#79B8FF"> --markdown</span></span></code></pre>
+<p>Copy the generated block into <code>docs/vendor-neutrality.md</code> as instructed
+in its comment header.</p>
+<h2 id="step-5--validate-the-full-wiring">Step 5 — validate the full wiring</h2>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#6A737D"># 1. Symlink topology (no cycles, correct relay direction)</span></span>
+<span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> tools/symlink-lint</span><span style="color:#9ECBFF"> symlink-lint</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#6A737D"># 2. Skill + tool metadata (capability, prerequisites, organization lines)</span></span>
+<span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> tools/skill-and-tool-validator</span><span style="color:#79B8FF"> --group</span><span style="color:#9ECBFF"> dev</span><span style="color:#9ECBFF"> skill-and-tool-validate</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#6A737D"># 3. Guard tests (if you added a guard adapter in step 2)</span></span>
+<span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> tools/agent-guard</span><span style="color:#79B8FF"> --group</span><span style="color:#9ECBFF"> dev</span><span style="color:#9ECBFF"> pytest</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#6A737D"># 4. Loop syntax</span></span>
+<span class="line"><span style="color:#B392F0">bash</span><span style="color:#79B8FF"> -n</span><span style="color:#9ECBFF"> tools/spec-loop/loop.sh</span><span style="color:#E1E4E8"> && </span><span style="color:#B392F0">bash</span><span style="color:#79B8FF"> -n</span><span style="color:#9ECBFF"> tools/spec-loop/lib.sh</span></span></code></pre>
+<p>All four must pass before opening a PR.</p>
+<h2 id="scope-of-a-first-class-harness-integration">Scope of a first-class harness integration</h2>
+<p>A minimal integration lands steps 1 + 3: skills load, the loop runs.
+Steps 2 and 4 are what turn “skills load” into “skills run safely.”
+The recommended order for a community contribution:</p>
+<ol>
+<li><strong>Open a tracking issue</strong> (or claim the existing one for your
+runtime — see <code>docs/vendor-neutrality.md</code> § Agentic harness for the
+issue list).</li>
+<li><strong>Land the registry row + relay symlinks</strong> (step 1) — small PR,
+unblocks users immediately.</li>
+<li><strong>Land the loop profile</strong> (step 3) — small PR, enables spec-loop
+use.</li>
+<li><strong>Land the guard adapter or OS-level wrapper</strong> (step 2) — the most
+harness-specific work; can be a follow-up PR.</li>
+<li><strong>Update harness declarations</strong> (step 4) — include in whichever PR
+lands the first substantive integration point.</li>
+</ol>
+<p>This matches how Claude Code and OpenCode integrations were built: the
+skill path landed first, then guard, then loop, then full harness table.</p>
+<h2 id="see-also">See also</h2>
+<ul>
+<li><a href="https://github.com/apache/magpie/blob/main/skills/setup/agents.md"><code>skills/setup/agents.md</code></a> — the
+agent-target registry (single source of truth for symlink paths).</li>
+<li><a href="https://github.com/apache/magpie/tree/main/tools/symlink-lint/"><code>tools/symlink-lint/</code></a> — enforces relay
+symlink correctness.</li>
+<li><a href="https://github.com/apache/magpie/tree/main/tools/agent-guard/"><code>tools/agent-guard/</code></a> — the action guard
+core and per-harness adapters.</li>
+<li><a href="https://github.com/apache/magpie/tree/main/tools/agent-isolation/"><code>tools/agent-isolation/</code></a> — the
+clean-environment launcher (OS-level complement to the agent hook).</li>
+<li><a href="https://github.com/apache/magpie/blob/main/tools/spec-loop/loop.sh"><code>tools/spec-loop/loop.sh</code></a> and
+<code>lib.sh</code> — the spec-loop runner with per-harness invocation profiles.</li>
+<li><a href="/docs/vendor-neutrality"><code>docs/vendor-neutrality.md</code></a> § Agentic
+runtime — the open tracking issues per runtime and the neutrality
+rationale.</li>
+<li><a href="/docs/adapters/authoring"><code>docs/adapters/authoring.md</code></a> — the analogous recipe
+for adding a new tool backend (forge, VCS, mail archive, CNA).</li>
+</ul>
+</article></main><aside class="hidden xl:block w-60 flex-none border-l border-solid border-neutral-200 bg-default-background sticky top-0 h-screen overflow-y-auto px-5 py-12"><div class="mb-3 text-caption font-caption uppercase tracking-wider text-subtext-color">On this page</div><nav><ul class="flex flex-col gap-1.5"><li><a href="#step-1--add-a-row-to-the-agent-target-registry" class="block text-caption font-caption text-subtext-color hover:text-brand-700" style="padding-left: 0rem">Ste [...]
+ (() => {
+ const nav = document.getElementById("docs-nav-scroll");
+ if (!nav) return;
+ for (const link of nav.querySelectorAll("summary a[href]")) {
+ link.addEventListener("click", (event) => {
+ const branch = link.closest("details");
+ if (!branch) return;
+ const plainClick =
+ event.button === 0 &&
+ !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
+ if (plainClick) {
+ event.preventDefault();
+ branch.open = true;
+ window.location.href = link.href;
+ } else {
+ setTimeout(() => { branch.open = true; }, 0);
+ }
+ });
+ }
+ })();
+ </script><script>
+ (() => {
+ const scroller = document.getElementById("docs-nav-scroll");
+ const active = scroller?.querySelector('[aria-current="page"]');
+ if (!scroller || !active) return;
+ const target =
+ active.offsetTop - scroller.clientHeight / 2 + active.offsetHeight / 2;
+ scroller.scrollTop = Math.max(0, target);
+ })();
+ </script><a href="https://github.com/apache/magpie/edit/main/docs/adapters/add-a-harness.md" target="_blank" rel="noopener noreferrer" class="suggest-change" aria-label="Suggest a change to this page on GitHub" data-astro-cid-z4jru4n3><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" data-astro-cid-z4jru4n3><path d="M12 20h9" data-astro-cid-z4jru4n3></path><path d="M16.5 3 [...]
\ No newline at end of file
diff --git a/docs/adapters/authoring.md b/docs/adapters/authoring.md
new file mode 100644
index 0000000..a4e5244
--- /dev/null
+++ b/docs/adapters/authoring.md
@@ -0,0 +1,82 @@
+# Authoring an adapter
+
+Rendered page: https://magpie.apache.org/docs/adapters/authoring/
+
+Source: https://github.com/apache/magpie/blob/main/docs/adapters/authoring.md
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+When Magpie ships no [adapter](/docs/vendor-neutrality#tool-adapters) for
+your backend — a forge, a CNA tool, a chat system, a mail archive, a VCS,
+or a whole [organization](https://github.com/apache/magpie/blob/main/organizations/README.md) profile — you
+author one. The skills stay agnostic: they target a *capability*, and
+your adapter supplies the concrete backend. This guide is the how-to; the
+[registry](/docs/adapters/registry) is the index of what already exists.
+
+## Three homes for an adapter
+
+| | In-tree (upstream) | In your adopter repo | External (another repo) |
+|---|---|---|---|
+| **Where it lives** | a PR into `apache/magpie` | `<project-config>/.apache-magpie-overrides/` | a repo you/the community maintain |
+| **License** | Apache-2.0 ([§17](https://github.com/apache/magpie/blob/main/PRINCIPLES.md#17-contributions-land-under-apache-license-20)) | yours | the author's |
+| **Who reuses it** | every adopter on that backend | your project | anyone who wires it in |
+| **Discovery** | shipped in-tree | committed in your repo | optionally listed in the [registry](/docs/adapters/registry) |
+| **Install** | part of the snapshot | committed override | you wire it in deliberately — never auto-fetched ([§13](https://github.com/apache/magpie/blob/main/PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies)) |
+
+All three are first-class. Contribute upstream when the backend is one
+other projects share; keep it in your adopter repo when it is specific to
+your project; keep it external when a third party maintains it or it is
+shared across your repos but not in Magpie. See
+[`docs/extending.md`](/docs/extending) for the same model applied to every
+extension type.
+
+## Authoring a tool adapter
+
+A tool adapter fulfils a capability *contract* for one backend.
+
+1. **Find the contract.** Pick the `tools/<contract>/` whose capability
+ you are implementing (e.g. [`tools/cve-tool/`](https://github.com/apache/magpie/tree/main/tools/cve-tool/)
+ for a CNA tool, [`tools/mail-archive/`](https://github.com/apache/magpie/tree/main/tools/mail-archive/) for
+ an archive). Its README enumerates the methods/verbs your adapter must
+ provide. If no contract exists for the capability, propose one first.
+2. **Create the adapter directory** — `tools/<contract>-<backend>/` (in
+ tree) or a directory in your own repo (external). Implement the
+ contract's operations.
+3. **Declare the metadata** the validator requires (see
+ [`tools/AGENTS.md`](https://github.com/apache/magpie/blob/main/tools/AGENTS.md)):
+ - a `**Capability:** contract:NAME` (or `substrate:NAME`) line in the README;
+ - a `## Prerequisites` section (runtime, CLIs, credentials, network);
+ - optionally an `**Organization:** <org>` line if the adapter belongs
+ to a specific organization.
+4. **Wire it in.** Point your `<project-config>/project.md` *Tools
+ enabled* manifest (or the relevant capability key, e.g.
+ `cve_authority.tool`) at the adapter. Skill bodies never change.
+5. **Add an eval** ([§8](https://github.com/apache/magpie/blob/main/PRINCIPLES.md#8-eval-is-a-release-blocking-discipline))
+ under `tools/skill-evals/evals/` so the adapter's behaviour is graded,
+ not just demoed.
+
+The [`write-skill`](https://github.com/apache/magpie/blob/main/skills/write-skill/SKILL.md) flow and
+[`CONTRIBUTING.md`](https://github.com/apache/magpie/blob/main/CONTRIBUTING.md) walk the conventions in detail;
+`skill-and-tool-validate` enforces the capability + prerequisites lines.
+
+## Authoring an organization
+
+An organization groups governance vocabulary + capability→adapter
+selections + identity for every project under one governing body. To add
+one, copy [`organizations/_template/`](https://github.com/apache/magpie/tree/main/organizations/_template/) to
+`organizations/<org>/`, fill in `organization.md` (identity incl. `logo`,
+governance vocabulary, and the backend bundle), and point projects at it
+with `organization: <org>`. See
+[`organizations/README.md`](https://github.com/apache/magpie/blob/main/organizations/README.md).
+
+## After authoring
+
+- **Contributing upstream?** Open the PR; once it merges and adopters run
+ `/magpie-setup upgrade`, the adapter is available to everyone.
+- **Keeping it external?** Optionally add a row to the
+ [registry](/docs/adapters/registry#community--external-adapters) so others can
+ discover it — discovery only, no install.
diff --git a/docs/adapters/authoring/index.html b/docs/adapters/authoring/index.html
new file mode 100644
index 0000000..45134da
--- /dev/null
+++ b/docs/adapters/authoring/index.html
@@ -0,0 +1,156 @@
+<!DOCTYPE html><html lang="en" data-astro-cid-z4jru4n3><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="description" content="AI-powered assistant for open-source maintainers. Triage, mentor, draft, pair, and auto-merge under Apache Software Foundation governance."><link rel="icon" type="image/svg+xml" href="/favicon.svg"><link rel="icon" type="image/x-icon" sizes="any" href="/favicon.ico"><title>Authoring an adapter — Apache M [...]
+ var _paq = (window._paq = window._paq || []);
+ /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
+ _paq.push(["setDoNotTrack", true]);
+ _paq.push(["disableCookies"]);
+ _paq.push(["trackPageView"]);
+ _paq.push(["enableLinkTracking"]);
+ (function () {
+ var u = "https://analytics.apache.org/";
+ _paq.push(["setTrackerUrl", u + "matomo.php"]);
+ _paq.push(["setSiteId", "89"]);
+ var d = document,
+ g = d.createElement("script"),
+ s = d.getElementsByTagName("script")[0];
+ g.async = true;
+ g.src = u + "matomo.js";
+ s.parentNode.insertBefore(g, s);
+ })();
+ </script><link rel="stylesheet" href="/_astro/SiteFooter.C2Dgj2WR.css"><style>.tree-summary[data-astro-cid-lihgpoae]{list-style:none}.tree-summary[data-astro-cid-lihgpoae]::-webkit-details-marker{display:none}.tree-chevron[data-astro-cid-lihgpoae]{color:var(--color-subtext-color);transition:transform .15s}details[data-astro-cid-lihgpoae][open]>.tree-summary[data-astro-cid-lihgpoae] .tree-chevron[data-astro-cid-lihgpoae]{transform:rotate(90deg)}.prose h1{color:var(--color-default-font [...]
+</style></head><body data-astro-cid-z4jru4n3><nav class="relative z-10 flex w-full items-center justify-between bg-default-background px-8 py-5 mobile:px-4"><a href="/" aria-label="Apache Magpie home" class="flex items-end justify-end gap-2 px-2 py-2"><img class="h-10 w-10 flex-none object-cover" src="/subframe-mark.svg" alt="Apache Magpie"/><img class="h-10 flex-none object-contain" src="/subframe-wordmark.png" alt="Magpie"/><span class="self-center -mt-2 -ml-2 text-[10px] font-[700] le [...]
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<h1 id="authoring-an-adapter">Authoring an adapter</h1>
+<p>When Magpie ships no <a href="/docs/vendor-neutrality#tool-adapters">adapter</a> for
+your backend — a forge, a CNA tool, a chat system, a mail archive, a VCS,
+or a whole <a href="https://github.com/apache/magpie/blob/main/organizations/README.md">organization</a> profile — you
+author one. The skills stay agnostic: they target a <em>capability</em>, and
+your adapter supplies the concrete backend. This guide is the how-to; the
+<a href="/docs/adapters/registry">registry</a> is the index of what already exists.</p>
+<h2 id="three-homes-for-an-adapter">Three homes for an adapter</h2>
+<table>
+<thead>
+<tr>
+<th></th>
+<th>In-tree (upstream)</th>
+<th>In your adopter repo</th>
+<th>External (another repo)</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>Where it lives</strong></td>
+<td>a PR into <code>apache/magpie</code></td>
+<td><code><project-config>/.apache-magpie-overrides/</code></td>
+<td>a repo you/the community maintain</td>
+</tr>
+<tr>
+<td><strong>License</strong></td>
+<td>Apache-2.0 (<a href="https://github.com/apache/magpie/blob/main/PRINCIPLES.md#17-contributions-land-under-apache-license-20">§17</a>)</td>
+<td>yours</td>
+<td>the author’s</td>
+</tr>
+<tr>
+<td><strong>Who reuses it</strong></td>
+<td>every adopter on that backend</td>
+<td>your project</td>
+<td>anyone who wires it in</td>
+</tr>
+<tr>
+<td><strong>Discovery</strong></td>
+<td>shipped in-tree</td>
+<td>committed in your repo</td>
+<td>optionally listed in the <a href="/docs/adapters/registry">registry</a></td>
+</tr>
+<tr>
+<td><strong>Install</strong></td>
+<td>part of the snapshot</td>
+<td>committed override</td>
+<td>you wire it in deliberately — never auto-fetched (<a href="https://github.com/apache/magpie/blob/main/PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies">§13</a>)</td>
+</tr>
+</tbody>
+</table>
+<p>All three are first-class. Contribute upstream when the backend is one
+other projects share; keep it in your adopter repo when it is specific to
+your project; keep it external when a third party maintains it or it is
+shared across your repos but not in Magpie. See
+<a href="/docs/extending"><code>docs/extending.md</code></a> for the same model applied to every
+extension type.</p>
+<h2 id="authoring-a-tool-adapter">Authoring a tool adapter</h2>
+<p>A tool adapter fulfils a capability <em>contract</em> for one backend.</p>
+<ol>
+<li><strong>Find the contract.</strong> Pick the <code>tools/<contract>/</code> whose capability
+you are implementing (e.g. <a href="https://github.com/apache/magpie/tree/main/tools/cve-tool/"><code>tools/cve-tool/</code></a>
+for a CNA tool, <a href="https://github.com/apache/magpie/tree/main/tools/mail-archive/"><code>tools/mail-archive/</code></a> for
+an archive). Its README enumerates the methods/verbs your adapter must
+provide. If no contract exists for the capability, propose one first.</li>
+<li><strong>Create the adapter directory</strong> — <code>tools/<contract>-<backend>/</code> (in
+tree) or a directory in your own repo (external). Implement the
+contract’s operations.</li>
+<li><strong>Declare the metadata</strong> the validator requires (see
+<a href="https://github.com/apache/magpie/blob/main/tools/AGENTS.md"><code>tools/AGENTS.md</code></a>):
+<ul>
+<li>a <code>**Capability:** contract:NAME</code> (or <code>substrate:NAME</code>) line in the README;</li>
+<li>a <code>## Prerequisites</code> section (runtime, CLIs, credentials, network);</li>
+<li>optionally an <code>**Organization:** <org></code> line if the adapter belongs
+to a specific organization.</li>
+</ul>
+</li>
+<li><strong>Wire it in.</strong> Point your <code><project-config>/project.md</code> <em>Tools
+enabled</em> manifest (or the relevant capability key, e.g.
+<code>cve_authority.tool</code>) at the adapter. Skill bodies never change.</li>
+<li><strong>Add an eval</strong> (<a href="https://github.com/apache/magpie/blob/main/PRINCIPLES.md#8-eval-is-a-release-blocking-discipline">§8</a>)
+under <code>tools/skill-evals/evals/</code> so the adapter’s behaviour is graded,
+not just demoed.</li>
+</ol>
+<p>The <a href="https://github.com/apache/magpie/blob/main/skills/write-skill/SKILL.md"><code>write-skill</code></a> flow and
+<a href="https://github.com/apache/magpie/blob/main/CONTRIBUTING.md"><code>CONTRIBUTING.md</code></a> walk the conventions in detail;
+<code>skill-and-tool-validate</code> enforces the capability + prerequisites lines.</p>
+<h2 id="authoring-an-organization">Authoring an organization</h2>
+<p>An organization groups governance vocabulary + capability→adapter
+selections + identity for every project under one governing body. To add
+one, copy <a href="https://github.com/apache/magpie/tree/main/organizations/_template/"><code>organizations/_template/</code></a> to
+<code>organizations/<org>/</code>, fill in <code>organization.md</code> (identity incl. <code>logo</code>,
+governance vocabulary, and the backend bundle), and point projects at it
+with <code>organization: <org></code>. See
+<a href="https://github.com/apache/magpie/blob/main/organizations/README.md"><code>organizations/README.md</code></a>.</p>
+<h2 id="after-authoring">After authoring</h2>
+<ul>
+<li><strong>Contributing upstream?</strong> Open the PR; once it merges and adopters run
+<code>/magpie-setup upgrade</code>, the adapter is available to everyone.</li>
+<li><strong>Keeping it external?</strong> Optionally add a row to the
+<a href="/docs/adapters/registry#community--external-adapters">registry</a> so others can
+discover it — discovery only, no install.</li>
+</ul>
+</article></main><aside class="hidden xl:block w-60 flex-none border-l border-solid border-neutral-200 bg-default-background sticky top-0 h-screen overflow-y-auto px-5 py-12"><div class="mb-3 text-caption font-caption uppercase tracking-wider text-subtext-color">On this page</div><nav><ul class="flex flex-col gap-1.5"><li><a href="#three-homes-for-an-adapter" class="block text-caption font-caption text-subtext-color hover:text-brand-700" style="padding-left: 0rem">Three homes for an adap [...]
+ (() => {
+ const nav = document.getElementById("docs-nav-scroll");
+ if (!nav) return;
+ for (const link of nav.querySelectorAll("summary a[href]")) {
+ link.addEventListener("click", (event) => {
+ const branch = link.closest("details");
+ if (!branch) return;
+ const plainClick =
+ event.button === 0 &&
+ !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
+ if (plainClick) {
+ event.preventDefault();
+ branch.open = true;
+ window.location.href = link.href;
+ } else {
+ setTimeout(() => { branch.open = true; }, 0);
+ }
+ });
+ }
+ })();
+ </script><script>
+ (() => {
+ const scroller = document.getElementById("docs-nav-scroll");
+ const active = scroller?.querySelector('[aria-current="page"]');
+ if (!scroller || !active) return;
+ const target =
+ active.offsetTop - scroller.clientHeight / 2 + active.offsetHeight / 2;
+ scroller.scrollTop = Math.max(0, target);
+ })();
+ </script><a href="https://github.com/apache/magpie/edit/main/docs/adapters/authoring.md" target="_blank" rel="noopener noreferrer" class="suggest-change" aria-label="Suggest a change to this page on GitHub" data-astro-cid-z4jru4n3><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" data-astro-cid-z4jru4n3><path d="M12 20h9" data-astro-cid-z4jru4n3></path><path d="M16.5 3.5a2 [...]
\ No newline at end of file
diff --git a/docs/adapters/codex.md b/docs/adapters/codex.md
new file mode 100644
index 0000000..5bddb3a
--- /dev/null
+++ b/docs/adapters/codex.md
@@ -0,0 +1,223 @@
+# Codex first-class harness
+
+Rendered page: https://magpie.apache.org/docs/adapters/codex/
+
+Source: https://github.com/apache/magpie/blob/main/docs/adapters/codex.md
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+**Capability:** capability:platform
+
+**Harness:** OpenAI Codex CLI, IDE, and desktop local runtime
+
+This adapter makes Codex a native Apache Magpie skill runtime. It is not the
+Claude Code codex delegation plugin: a maintainer with Codex and no Claude Code
+can discover, invoke, and run Magpie skills end to end.
+
+The implementation follows
+[RFC-AI-0004](/docs/rfcs/rfc-ai-0004): shared skill sources, a native sandbox,
+and per-action human confirmation through Codex's own approval and exec-policy
+layers.
+
+## Harness contract
+
+| Magpie requirement | Codex implementation |
+|---|---|
+| Skill discovery | Codex reads the existing canonical `.agents/skills/magpie-*/SKILL.md` symlinks directly. No SKILL.md-to-AGENTS.md translation or duplicate source tree is needed. |
+| Repository instructions | Codex reads the repository `AGENTS.md` hierarchy natively. |
+| Tool bridges | Skills invoke the same language-neutral `tools/` CLI adapters. Network is disabled inside `workspace-write`; approved network actions cross the sandbox through Codex rules and approval policy. |
+| Filesystem sandbox | Project `.codex/config.toml` selects `workspace-write`. |
+| Human in the loop | `approval_policy = "on-request"` and `.codex/rules/magpie.rules` allow scoped reads, prompt mutations, and forbid credential disclosure. |
+| Deterministic guard | The shared `tools/agent-guard` dispatch core is reachable through its harness-neutral `--check` / `--exec` modes (see [Deterministic guard rules](#deterministic-guard-rules)). |
+| Credential isolation | `tools/agent-isolation/agent-iso.sh` launches `agent-iso codex` through the shared clean-environment wrapper. |
+
+The committed profile lives in:
+
+~~~text
+.codex/
+|-- config.toml
+`-- rules/
+ `-- magpie.rules
+~~~
+
+Both files are policy and are reviewed in Git.
+
+## Invoke a Magpie skill
+
+Codex scans `.agents/skills` from the current directory to the repository root,
+follows symlinked skill directories, and reads `SKILL.md` when a skill is
+chosen. After `magpie-setup` has adopted the repository:
+
+1. Start Codex at the adopter repository root, preferably with
+ `agent-iso codex`.
+2. Use `/skills` to confirm that `magpie-*` skills are visible.
+3. Invoke a skill explicitly by mentioning it with `$`, for example
+ `$magpie-security-issue-triage`, or describe a task that matches its
+ frontmatter description.
+4. The selected skill resolves `tools/*` commands and project placeholders in
+ exactly the same way as every other runtime.
+
+An end-to-end triage therefore starts with:
+
+~~~text
+$magpie-security-issue-triage
+~~~
+
+There is no generated AGENTS.md per skill. `AGENTS.md` carries persistent
+repository instructions; `SKILL.md` remains the workflow source.
+
+## Install
+
+Run `$magpie-setup` from Codex and select adopt or upgrade. The setup
+lifecycle:
+
+1. Creates the canonical `.agents/skills` links and harness relay links.
+2. Merges the reviewed Codex posture into `.codex/` without deleting unrelated
+ project settings. Conflicting sandbox or approval values are surfaced to the
+ maintainer; they are never silently weakened.
+3. Runs `sandbox-lint --codex .codex` on the merged result.
+4. Asks the operator to trust the project in Codex. Repository content cannot
+ grant its own trust.
+
+When `.codex/` already exists, setup preserves unrelated keys. `magpie.rules`
+is Magpie-owned; hand edits are shown before replacement.
+
+For the clean-environment layer on Linux or macOS:
+
+~~~bash
+source <framework>/tools/agent-isolation/agent-iso.sh
+agent-iso codex
+~~~
+
+On Windows, run the POSIX isolation layer through WSL when that layer is
+required. Codex's native Windows sandbox and the project policy still apply to
+a native Windows session.
+
+## Security model
+
+### Sandbox and network
+
+The profile requires:
+
+~~~toml
+sandbox_mode = "workspace-write"
+approval_policy = "on-request"
+
+[sandbox_workspace_write]
+network_access = false
+~~~
+
+Networked bridges such as `gh`, `jira`, Gmail, PonyMail, and CVE tooling
+therefore cannot silently use network access from the workspace sandbox. The
+exec-policy file allows narrowly scoped read-only commands, prompts known
+mutations, and forbids `gh auth token` and credential refresh operations.
+Commands not matched by an allow rule still follow the native on-request
+approval path.
+
+### Exec-policy rules and approval policy
+
+Per-action confirmation belongs to Codex's native rules and approval system:
+`.codex/rules/magpie.rules` classifies known commands as `allow`, `prompt`,
+or `forbidden` before they cross the sandbox boundary, and
+`approval_policy = "on-request"` routes everything else to the operator. This
+is the Codex mapping of RFC-AI-0004 Principle 1 (human-in-the-loop).
+
+### Deterministic guard rules
+
+Claude Code and OpenCode additionally wire the deterministic
+[`tools/agent-guard`](https://github.com/apache/magpie/blob/main/tools/agent-guard/README.md) denials (AI
+`Co-Authored-By` trailers, premature `--ready-for-review`, unsafe public
+security wording, empty force-pushes) as in-process pre-tool hooks. Codex has
+no equivalent wired hook adapter in this profile; the same `dispatch()` core
+remains available through the harness-neutral `--check` / `--exec` modes
+documented in the
+[agent-guard README](https://github.com/apache/magpie/blob/main/tools/agent-guard/README.md#harness-neutral-path-any-runtime).
+Until a native Codex adapter exists, those framework invariants rely on the
+exec-policy prompts plus the operator's review of each confirmed action.
+
+### Trust boundary
+
+Project `.codex` configuration and rules load only for a trusted project. The
+operator reviews that trust decision. The framework does not modify user trust
+state.
+
+Policy changes remain normal reviewed repository changes: an approved elevated
+action can still modify `.codex/`, so the profile complements — never
+replaces — code review.
+
+## Verify
+
+Run the static validator from the framework or snapshot:
+
+~~~bash
+uv run --directory tools/sandbox-lint --group dev sandbox-lint --codex .codex
+~~~
+
+Then test native rule classification:
+
+~~~bash
+codex execpolicy check --pretty \
+ --rules .codex/rules/magpie.rules \
+ -- gh pr view 313
+
+codex execpolicy check --pretty \
+ --rules .codex/rules/magpie.rules \
+ -- gh pr create --title test --body test
+
+codex execpolicy check --pretty \
+ --rules .codex/rules/magpie.rules \
+ -- gh auth token
+~~~
+
+The expected strictest decisions are `allow`, `prompt`, and `forbidden`,
+respectively.
+
+Also verify:
+
+- `/skills` lists `magpie-setup` and a representative workflow skill.
+- Each `tools/*` bridge used by the selected skill is present and
+ authenticated; tool-specific preflight remains owned by that skill.
+
+## setup-isolated lifecycle
+
+The four setup-isolated skills route Codex to this adapter:
+
+- `setup-isolated-setup-install` installs or merges the project profile and
+ explains `agent-iso codex`.
+- `setup-isolated-setup-verify` runs the static validator, rule-classification
+ probes, `/skills` checks, and tool preflights.
+- `setup-isolated-setup-update` compares the installed profile with the
+ current framework snapshot. It reports drift and never weakens policy
+ automatically.
+- `setup-isolated-setup-doctor` runs the shared live environment probes inside
+ the active Codex sandbox and reports native approval or network failures
+ separately.
+
+The Claude-specific setup remains available for Claude Code. Runtime routing
+must happen before a setup-isolated skill follows Claude-only settings paths.
+
+## Known limitations
+
+- Codex exec-policy rules are an evolving runtime interface. Pin a minimum
+ tested Codex version before calling the adapter stable, and rerun the
+ classification probes on upgrades.
+- The deterministic agent-guard denials are not wired as a native Codex hook;
+ see [Deterministic guard rules](#deterministic-guard-rules).
+- Native project policy requires explicit project trust.
+- The clean-environment wrapper is POSIX shell. Native Windows sessions rely
+ on the Codex Windows sandbox unless launched through WSL.
+- MCP and account-backed integrations still require user-scoped registration
+ and authentication. Repository policy never copies credentials into the
+ project.
+
+## Upstream references
+
+- [Codex skills](https://developers.openai.com/codex/skills)
+- [Codex configuration](https://developers.openai.com/codex/config-reference)
+- [Codex rules](https://developers.openai.com/codex/rules)
+- [Codex CLI source](https://github.com/openai/codex)
+- [Agent Skills specification](https://agentskills.io/specification)
diff --git a/docs/adapters/codex/index.html b/docs/adapters/codex/index.html
new file mode 100644
index 0000000..2c3d21f
--- /dev/null
+++ b/docs/adapters/codex/index.html
@@ -0,0 +1,246 @@
+<!DOCTYPE html><html lang="en" data-astro-cid-z4jru4n3><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="description" content="AI-powered assistant for open-source maintainers. Triage, mentor, draft, pair, and auto-merge under Apache Software Foundation governance."><link rel="icon" type="image/svg+xml" href="/favicon.svg"><link rel="icon" type="image/x-icon" sizes="any" href="/favicon.ico"><title>Codex first-class harness — Apa [...]
+ var _paq = (window._paq = window._paq || []);
+ /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
+ _paq.push(["setDoNotTrack", true]);
+ _paq.push(["disableCookies"]);
+ _paq.push(["trackPageView"]);
+ _paq.push(["enableLinkTracking"]);
+ (function () {
+ var u = "https://analytics.apache.org/";
+ _paq.push(["setTrackerUrl", u + "matomo.php"]);
+ _paq.push(["setSiteId", "89"]);
+ var d = document,
+ g = d.createElement("script"),
+ s = d.getElementsByTagName("script")[0];
+ g.async = true;
+ g.src = u + "matomo.js";
+ s.parentNode.insertBefore(g, s);
+ })();
+ </script><link rel="stylesheet" href="/_astro/SiteFooter.C2Dgj2WR.css"><style>.tree-summary[data-astro-cid-lihgpoae]{list-style:none}.tree-summary[data-astro-cid-lihgpoae]::-webkit-details-marker{display:none}.tree-chevron[data-astro-cid-lihgpoae]{color:var(--color-subtext-color);transition:transform .15s}details[data-astro-cid-lihgpoae][open]>.tree-summary[data-astro-cid-lihgpoae] .tree-chevron[data-astro-cid-lihgpoae]{transform:rotate(90deg)}.prose h1{color:var(--color-default-font [...]
+</style></head><body data-astro-cid-z4jru4n3><nav class="relative z-10 flex w-full items-center justify-between bg-default-background px-8 py-5 mobile:px-4"><a href="/" aria-label="Apache Magpie home" class="flex items-end justify-end gap-2 px-2 py-2"><img class="h-10 w-10 flex-none object-cover" src="/subframe-mark.svg" alt="Apache Magpie"/><img class="h-10 flex-none object-contain" src="/subframe-wordmark.png" alt="Magpie"/><span class="self-center -mt-2 -ml-2 text-[10px] font-[700] le [...]
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<h1 id="codex-first-class-harness">Codex first-class harness</h1>
+<p><strong>Capability:</strong> capability:platform</p>
+<p><strong>Harness:</strong> OpenAI Codex CLI, IDE, and desktop local runtime</p>
+<p>This adapter makes Codex a native Apache Magpie skill runtime. It is not the
+Claude Code codex delegation plugin: a maintainer with Codex and no Claude Code
+can discover, invoke, and run Magpie skills end to end.</p>
+<p>The implementation follows
+<a href="/docs/rfcs/rfc-ai-0004">RFC-AI-0004</a>: shared skill sources, a native sandbox,
+and per-action human confirmation through Codex’s own approval and exec-policy
+layers.</p>
+<h2 id="harness-contract">Harness contract</h2>
+<table>
+<thead>
+<tr>
+<th>Magpie requirement</th>
+<th>Codex implementation</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Skill discovery</td>
+<td>Codex reads the existing canonical <code>.agents/skills/magpie-*/SKILL.md</code> symlinks directly. No SKILL.md-to-AGENTS.md translation or duplicate source tree is needed.</td>
+</tr>
+<tr>
+<td>Repository instructions</td>
+<td>Codex reads the repository <code>AGENTS.md</code> hierarchy natively.</td>
+</tr>
+<tr>
+<td>Tool bridges</td>
+<td>Skills invoke the same language-neutral <code>tools/</code> CLI adapters. Network is disabled inside <code>workspace-write</code>; approved network actions cross the sandbox through Codex rules and approval policy.</td>
+</tr>
+<tr>
+<td>Filesystem sandbox</td>
+<td>Project <code>.codex/config.toml</code> selects <code>workspace-write</code>.</td>
+</tr>
+<tr>
+<td>Human in the loop</td>
+<td><code>approval_policy = "on-request"</code> and <code>.codex/rules/magpie.rules</code> allow scoped reads, prompt mutations, and forbid credential disclosure.</td>
+</tr>
+<tr>
+<td>Deterministic guard</td>
+<td>The shared <code>tools/agent-guard</code> dispatch core is reachable through its harness-neutral <code>--check</code> / <code>--exec</code> modes (see <a href="#deterministic-guard-rules">Deterministic guard rules</a>).</td>
+</tr>
+<tr>
+<td>Credential isolation</td>
+<td><code>tools/agent-isolation/agent-iso.sh</code> launches <code>agent-iso codex</code> through the shared clean-environment wrapper.</td>
+</tr>
+</tbody>
+</table>
+<p>The committed profile lives in:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="text"><code><span class="line"><span>.codex/</span></span>
+<span class="line"><span>|-- config.toml</span></span>
+<span class="line"><span>`-- rules/</span></span>
+<span class="line"><span> `-- magpie.rules</span></span></code></pre>
+<p>Both files are policy and are reviewed in Git.</p>
+<h2 id="invoke-a-magpie-skill">Invoke a Magpie skill</h2>
+<p>Codex scans <code>.agents/skills</code> from the current directory to the repository root,
+follows symlinked skill directories, and reads <code>SKILL.md</code> when a skill is
+chosen. After <code>magpie-setup</code> has adopted the repository:</p>
+<ol>
+<li>Start Codex at the adopter repository root, preferably with
+<code>agent-iso codex</code>.</li>
+<li>Use <code>/skills</code> to confirm that <code>magpie-*</code> skills are visible.</li>
+<li>Invoke a skill explicitly by mentioning it with <code>$</code>, for example
+<code>$magpie-security-issue-triage</code>, or describe a task that matches its
+frontmatter description.</li>
+<li>The selected skill resolves <code>tools/*</code> commands and project placeholders in
+exactly the same way as every other runtime.</li>
+</ol>
+<p>An end-to-end triage therefore starts with:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="text"><code><span class="line"><span>$magpie-security-issue-triage</span></span></code></pre>
+<p>There is no generated AGENTS.md per skill. <code>AGENTS.md</code> carries persistent
+repository instructions; <code>SKILL.md</code> remains the workflow source.</p>
+<h2 id="install">Install</h2>
+<p>Run <code>$magpie-setup</code> from Codex and select adopt or upgrade. The setup
+lifecycle:</p>
+<ol>
+<li>Creates the canonical <code>.agents/skills</code> links and harness relay links.</li>
+<li>Merges the reviewed Codex posture into <code>.codex/</code> without deleting unrelated
+project settings. Conflicting sandbox or approval values are surfaced to the
+maintainer; they are never silently weakened.</li>
+<li>Runs <code>sandbox-lint --codex .codex</code> on the merged result.</li>
+<li>Asks the operator to trust the project in Codex. Repository content cannot
+grant its own trust.</li>
+</ol>
+<p>When <code>.codex/</code> already exists, setup preserves unrelated keys. <code>magpie.rules</code>
+is Magpie-owned; hand edits are shown before replacement.</p>
+<p>For the clean-environment layer on Linux or macOS:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#79B8FF">source</span><span style="color:#F97583"> <</span><span style="color:#9ECBFF">framewor</span><span style="color:#E1E4E8">k</span><span style="color:#F97583">></span><span style="color:#9ECBFF">/tools/agent-isolation/agent-iso.sh</span></span>
+<span class="line"><span style="color:#B392F0">agent-iso</span><span style="color:#9ECBFF"> codex</span></span></code></pre>
+<p>On Windows, run the POSIX isolation layer through WSL when that layer is
+required. Codex’s native Windows sandbox and the project policy still apply to
+a native Windows session.</p>
+<h2 id="security-model">Security model</h2>
+<h3 id="sandbox-and-network">Sandbox and network</h3>
+<p>The profile requires:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="toml"><code><span class="line"><span style="color:#E1E4E8">sandbox_mode = </span><span style="color:#9ECBFF">"workspace-write"</span></span>
+<span class="line"><span style="color:#E1E4E8">approval_policy = </span><span style="color:#9ECBFF">"on-request"</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#E1E4E8">[</span><span style="color:#B392F0">sandbox_workspace_write</span><span style="color:#E1E4E8">]</span></span>
+<span class="line"><span style="color:#E1E4E8">network_access = </span><span style="color:#79B8FF">false</span></span></code></pre>
+<p>Networked bridges such as <code>gh</code>, <code>jira</code>, Gmail, PonyMail, and CVE tooling
+therefore cannot silently use network access from the workspace sandbox. The
+exec-policy file allows narrowly scoped read-only commands, prompts known
+mutations, and forbids <code>gh auth token</code> and credential refresh operations.
+Commands not matched by an allow rule still follow the native on-request
+approval path.</p>
+<h3 id="exec-policy-rules-and-approval-policy">Exec-policy rules and approval policy</h3>
+<p>Per-action confirmation belongs to Codex’s native rules and approval system:
+<code>.codex/rules/magpie.rules</code> classifies known commands as <code>allow</code>, <code>prompt</code>,
+or <code>forbidden</code> before they cross the sandbox boundary, and
+<code>approval_policy = "on-request"</code> routes everything else to the operator. This
+is the Codex mapping of RFC-AI-0004 Principle 1 (human-in-the-loop).</p>
+<h3 id="deterministic-guard-rules">Deterministic guard rules</h3>
+<p>Claude Code and OpenCode additionally wire the deterministic
+<a href="https://github.com/apache/magpie/blob/main/tools/agent-guard/README.md"><code>tools/agent-guard</code></a> denials (AI
+<code>Co-Authored-By</code> trailers, premature <code>--ready-for-review</code>, unsafe public
+security wording, empty force-pushes) as in-process pre-tool hooks. Codex has
+no equivalent wired hook adapter in this profile; the same <code>dispatch()</code> core
+remains available through the harness-neutral <code>--check</code> / <code>--exec</code> modes
+documented in the
+<a href="https://github.com/apache/magpie/blob/main/tools/agent-guard/README.md#harness-neutral-path-any-runtime">agent-guard README</a>.
+Until a native Codex adapter exists, those framework invariants rely on the
+exec-policy prompts plus the operator’s review of each confirmed action.</p>
+<h3 id="trust-boundary">Trust boundary</h3>
+<p>Project <code>.codex</code> configuration and rules load only for a trusted project. The
+operator reviews that trust decision. The framework does not modify user trust
+state.</p>
+<p>Policy changes remain normal reviewed repository changes: an approved elevated
+action can still modify <code>.codex/</code>, so the profile complements — never
+replaces — code review.</p>
+<h2 id="verify">Verify</h2>
+<p>Run the static validator from the framework or snapshot:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --directory</span><span style="color:#9ECBFF"> tools/sandbox-lint</span><span style="color:#79B8FF"> --group</span><span style="color:#9ECBFF"> dev</span><span style="color:#9ECBFF"> sandbox-lint</span><span style="color:#79B8 [...]
+<p>Then test native rule classification:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#B392F0">codex</span><span style="color:#9ECBFF"> execpolicy</span><span style="color:#9ECBFF"> check</span><span style="color:#79B8FF"> --pretty</span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#79B8FF"> --rules</span><span style="color:#9ECBFF"> .codex/rules/magpie.rules</span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#79B8FF"> --</span><span style="color:#9ECBFF"> gh</span><span style="color:#9ECBFF"> pr</span><span style="color:#9ECBFF"> view</span><span style="color:#79B8FF"> 313</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#B392F0">codex</span><span style="color:#9ECBFF"> execpolicy</span><span style="color:#9ECBFF"> check</span><span style="color:#79B8FF"> --pretty</span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#79B8FF"> --rules</span><span style="color:#9ECBFF"> .codex/rules/magpie.rules</span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#79B8FF"> --</span><span style="color:#9ECBFF"> gh</span><span style="color:#9ECBFF"> pr</span><span style="color:#9ECBFF"> create</span><span style="color:#79B8FF"> --title</span><span style="color:#9ECBFF"> test</span><span style="color:#79B8FF"> --body</span><span style="color:#9ECBFF"> test</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#B392F0">codex</span><span style="color:#9ECBFF"> execpolicy</span><span style="color:#9ECBFF"> check</span><span style="color:#79B8FF"> --pretty</span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#79B8FF"> --rules</span><span style="color:#9ECBFF"> .codex/rules/magpie.rules</span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#79B8FF"> --</span><span style="color:#9ECBFF"> gh</span><span style="color:#9ECBFF"> auth</span><span style="color:#9ECBFF"> token</span></span></code></pre>
+<p>The expected strictest decisions are <code>allow</code>, <code>prompt</code>, and <code>forbidden</code>,
+respectively.</p>
+<p>Also verify:</p>
+<ul>
+<li><code>/skills</code> lists <code>magpie-setup</code> and a representative workflow skill.</li>
+<li>Each <code>tools/*</code> bridge used by the selected skill is present and
+authenticated; tool-specific preflight remains owned by that skill.</li>
+</ul>
+<h2 id="setup-isolated-lifecycle">setup-isolated lifecycle</h2>
+<p>The four setup-isolated skills route Codex to this adapter:</p>
+<ul>
+<li><code>setup-isolated-setup-install</code> installs or merges the project profile and
+explains <code>agent-iso codex</code>.</li>
+<li><code>setup-isolated-setup-verify</code> runs the static validator, rule-classification
+probes, <code>/skills</code> checks, and tool preflights.</li>
+<li><code>setup-isolated-setup-update</code> compares the installed profile with the
+current framework snapshot. It reports drift and never weakens policy
+automatically.</li>
+<li><code>setup-isolated-setup-doctor</code> runs the shared live environment probes inside
+the active Codex sandbox and reports native approval or network failures
+separately.</li>
+</ul>
+<p>The Claude-specific setup remains available for Claude Code. Runtime routing
+must happen before a setup-isolated skill follows Claude-only settings paths.</p>
+<h2 id="known-limitations">Known limitations</h2>
+<ul>
+<li>Codex exec-policy rules are an evolving runtime interface. Pin a minimum
+tested Codex version before calling the adapter stable, and rerun the
+classification probes on upgrades.</li>
+<li>The deterministic agent-guard denials are not wired as a native Codex hook;
+see <a href="#deterministic-guard-rules">Deterministic guard rules</a>.</li>
+<li>Native project policy requires explicit project trust.</li>
+<li>The clean-environment wrapper is POSIX shell. Native Windows sessions rely
+on the Codex Windows sandbox unless launched through WSL.</li>
+<li>MCP and account-backed integrations still require user-scoped registration
+and authentication. Repository policy never copies credentials into the
+project.</li>
+</ul>
+<h2 id="upstream-references">Upstream references</h2>
+<ul>
+<li><a href="https://developers.openai.com/codex/skills">Codex skills</a></li>
+<li><a href="https://developers.openai.com/codex/config-reference">Codex configuration</a></li>
+<li><a href="https://developers.openai.com/codex/rules">Codex rules</a></li>
+<li><a href="https://github.com/openai/codex">Codex CLI source</a></li>
+<li><a href="https://agentskills.io/specification">Agent Skills specification</a></li>
+</ul>
+</article></main><aside class="hidden xl:block w-60 flex-none border-l border-solid border-neutral-200 bg-default-background sticky top-0 h-screen overflow-y-auto px-5 py-12"><div class="mb-3 text-caption font-caption uppercase tracking-wider text-subtext-color">On this page</div><nav><ul class="flex flex-col gap-1.5"><li><a href="#harness-contract" class="block text-caption font-caption text-subtext-color hover:text-brand-700" style="padding-left: 0rem">Harness contract</a></li><li><a h [...]
+ (() => {
+ const nav = document.getElementById("docs-nav-scroll");
+ if (!nav) return;
+ for (const link of nav.querySelectorAll("summary a[href]")) {
+ link.addEventListener("click", (event) => {
+ const branch = link.closest("details");
+ if (!branch) return;
+ const plainClick =
+ event.button === 0 &&
+ !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
+ if (plainClick) {
+ event.preventDefault();
+ branch.open = true;
+ window.location.href = link.href;
+ } else {
+ setTimeout(() => { branch.open = true; }, 0);
+ }
+ });
+ }
+ })();
+ </script><script>
+ (() => {
+ const scroller = document.getElementById("docs-nav-scroll");
+ const active = scroller?.querySelector('[aria-current="page"]');
+ if (!scroller || !active) return;
+ const target =
+ active.offsetTop - scroller.clientHeight / 2 + active.offsetHeight / 2;
+ scroller.scrollTop = Math.max(0, target);
+ })();
+ </script><a href="https://github.com/apache/magpie/edit/main/docs/adapters/codex.md" target="_blank" rel="noopener noreferrer" class="suggest-change" aria-label="Suggest a change to this page on GitHub" data-astro-cid-z4jru4n3><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" data-astro-cid-z4jru4n3><path d="M12 20h9" data-astro-cid-z4jru4n3></path><path d="M16.5 3.5a2.121 [...]
\ No newline at end of file
diff --git a/docs/adapters/cursor.md b/docs/adapters/cursor.md
new file mode 100644
index 0000000..4513ce2
--- /dev/null
+++ b/docs/adapters/cursor.md
@@ -0,0 +1,125 @@
+# Cursor runtime (Composer + Agent CLI)
+
+Rendered page: https://magpie.apache.org/docs/adapters/cursor/
+
+Source: https://github.com/apache/magpie/blob/main/docs/adapters/cursor.md
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+**Capability:** capability:platform
+
+**Harness:** Cursor (Composer + Agent CLI)
+
+Cursor provides interactive and headless agent capabilities via Cursor Composer in the IDE and the `cursor-agent` CLI.
+This guide documents how Cursor operates as a first-class Apache Magpie skill runtime for [#316](https://github.com/apache/magpie/issues/316).
+
+Cursor integrates with Magpie without requiring custom skill copies, translation passes, or proprietary prompt wrappers.
+The integration follows [RFC-AI-0004 Principle 3 (Vendor Neutrality)](/docs/rfcs/rfc-ai-0004) and [Adding a new agent harness](/docs/adapters/add-a-harness).
+
+## Harness contract
+
+| Magpie requirement | Cursor implementation |
+|---|---|
+| Skill discovery | Cursor reads the canonical `.agents/skills/magpie-*/SKILL.md` symlinks directly. The existing `universal` row in `skills/setup/agents.md` covers this path. |
+| Repository instructions | Cursor ingests repository instructions from `AGENTS.md` and project rules from `.cursor/rules/` or `.cursorrules`. |
+| Human-in-the-loop (HITL) | Cursor Composer enforces per-action approval modals for file edits and terminal commands. Auto-Run permissions map directly to Magpie's proposal-then-confirm discipline. |
+| Tool bridges | Skills invoke the standard `tools/*` CLI adapters. Network access for authenticated operations respects the project isolation policy. |
+| Model and MCP bridges | Cursor's MCP support connects to framework MCP servers (PonyMail, Gmail, ASF project metadata). |
+| Spec-loop | The `cursor` profile forwards `--workspace`, `--print`, `--force`, and `--trust` flags for automated non-interactive runs. |
+| Credential isolation | `agent-iso` launches Cursor or `cursor-agent` through the shared clean-environment wrapper, stripping unapproved ambient tokens. |
+
+## Invoke a Magpie skill
+
+After running `/magpie-setup` to adopt the repository, the canonical `.agents/skills/` links are active in your working tree.
+Cursor scans `.agents/skills/` and discovers all available Magpie workflows.
+
+### Inside Cursor Composer (IDE)
+
+1. Open the adopted project folder in Cursor.
+2. Open Cursor Composer (`Ctrl+I` / `Cmd+I` or `Ctrl+Shift+J` / `Cmd+Shift+J`).
+3. Mention or reference a skill, for example:
+ > Use the `magpie-security-issue-triage` skill to triage the latest reports.
+4. Composer resolves the referenced `SKILL.md` workflow, checks prerequisites, and presents a proposed plan before executing state mutations.
+
+### Headless or CLI invocation (`cursor-agent`)
+
+For non-interactive triage sweeps, automated spec-loops, or terminal sessions:
+
+```bash
+# Interactive terminal session with filtered environment
+agent-iso cursor-agent
+
+# Run a specific Magpie workflow headlessly
+cursor-agent --print --workspace /path/to/repo "Run the magpie-list-skills skill and print the summary."
+```
+
+## Human-in-the-loop and Auto-Run controls
+
+Magpie enforces strict [Human-in-the-Loop principles](/docs/rfcs/rfc-ai-0004): no state mutation (closing issues, writing files, dispatching emails, pushing branches) occurs without explicit human approval.
+
+In Cursor:
+- **Default mode**: Every terminal command and write action requires an explicit **Approve** or **Run** click in the Composer UI.
+- **Auto-Run allowlist**: If you configure Auto-Run rules in Cursor settings, restrict allowlists strictly to read-only diagnostic commands (such as `git status`, `uv run pytest`, `gh issue list`).
+- **Never auto-approve destructive commands**: Commands that mutate remote trackers (`gh issue close`, `git push`, `gh pr create`) must always require human confirmation.
+
+## Deterministic guard rules and tool bridges
+
+Cursor runs tool commands through standard subshells in your project environment.
+Deterministic tool scripts under `tools/` (e.g. `tools/cve-tool-vulnogram/`, `tools/github/`, `tools/privacy-llm/`) execute with standard Python / Groovy runtimes.
+
+When running in environments where `agent-guard` is enabled:
+- The command dispatcher checks shell calls before execution.
+- Any attempt to bypass git verification flags (such as `--no-verify`) or push to protected branches is rejected deterministically.
+
+## Spec-loop runner
+
+The `cursor` profile in [`tools/spec-loop/lib.sh`](https://github.com/apache/magpie/blob/main/tools/spec-loop/lib.sh) invokes the CLI headlessly:
+
+```bash
+cursor agent --print --force --trust --workspace "$root" "<prompt>"
+# or via the standalone CLI
+cursor-agent --print --force --trust --workspace "$root" "<prompt>"
+```
+
+Cursor does not provide a per-invocation reasoning-effort flag, so the runner omits reasoning-level parameters.
+See the [spec-loop guide](https://github.com/apache/magpie/blob/main/tools/spec-loop/README.md) for full options.
+
+## Clean-environment wrapper
+
+To isolate sensitive tokens and run Cursor under the standard Magpie credential policy:
+
+```bash
+source <framework>/tools/agent-isolation/agent-iso.sh
+agent-iso cursor .
+```
+
+The `agent-iso` launcher scrubs undeclared environment variables while preserving local developer toolchains (`git`, `uv`, `gh`).
+
+## Verify
+
+Verify that the Cursor runtime wiring conforms to the framework standards:
+
+```bash
+# 1. Verify skill discovery topology
+$env:PYTHONUTF8=1; uv run --project tools/symlink-lint symlink-lint
+
+# 2. Validate skill and tool metadata
+$env:PYTHONUTF8=1; uv run --project tools/skill-and-tool-validator skill-and-tool-validate
+
+# 3. Check vendor neutrality score
+$env:PYTHONUTF8=1; uv run --project tools/vendor-neutrality-score vendor-neutrality-score
+
+# 4. Run pre-commit formatting and link verification
+uv run prek run doctoc --all-files
+```
+
+## See also
+
+- [`docs/adapters/add-a-harness.md`](/docs/adapters/add-a-harness) — recipe for adding runtime harnesses.
+- [`skills/setup/agents.md`](https://github.com/apache/magpie/blob/main/skills/setup/agents.md) — agent-target registry (`universal` canonical path).
+- [`docs/rfcs/RFC-AI-0004.md`](/docs/rfcs/rfc-ai-0004) — normative principles for vendor neutrality and HITL.
+- [`docs/vendor-neutrality.md`](/docs/vendor-neutrality) — framework vendor neutrality index.
diff --git a/docs/adapters/cursor/index.html b/docs/adapters/cursor/index.html
new file mode 100644
index 0000000..353892d
--- /dev/null
+++ b/docs/adapters/cursor/index.html
@@ -0,0 +1,169 @@
+<!DOCTYPE html><html lang="en" data-astro-cid-z4jru4n3><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="description" content="AI-powered assistant for open-source maintainers. Triage, mentor, draft, pair, and auto-merge under Apache Software Foundation governance."><link rel="icon" type="image/svg+xml" href="/favicon.svg"><link rel="icon" type="image/x-icon" sizes="any" href="/favicon.ico"><title>Cursor runtime (Composer + Agen [...]
+ var _paq = (window._paq = window._paq || []);
+ /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
+ _paq.push(["setDoNotTrack", true]);
+ _paq.push(["disableCookies"]);
+ _paq.push(["trackPageView"]);
+ _paq.push(["enableLinkTracking"]);
+ (function () {
+ var u = "https://analytics.apache.org/";
+ _paq.push(["setTrackerUrl", u + "matomo.php"]);
+ _paq.push(["setSiteId", "89"]);
+ var d = document,
+ g = d.createElement("script"),
+ s = d.getElementsByTagName("script")[0];
+ g.async = true;
+ g.src = u + "matomo.js";
+ s.parentNode.insertBefore(g, s);
+ })();
+ </script><link rel="stylesheet" href="/_astro/SiteFooter.C2Dgj2WR.css"><style>.tree-summary[data-astro-cid-lihgpoae]{list-style:none}.tree-summary[data-astro-cid-lihgpoae]::-webkit-details-marker{display:none}.tree-chevron[data-astro-cid-lihgpoae]{color:var(--color-subtext-color);transition:transform .15s}details[data-astro-cid-lihgpoae][open]>.tree-summary[data-astro-cid-lihgpoae] .tree-chevron[data-astro-cid-lihgpoae]{transform:rotate(90deg)}.prose h1{color:var(--color-default-font [...]
+</style></head><body data-astro-cid-z4jru4n3><nav class="relative z-10 flex w-full items-center justify-between bg-default-background px-8 py-5 mobile:px-4"><a href="/" aria-label="Apache Magpie home" class="flex items-end justify-end gap-2 px-2 py-2"><img class="h-10 w-10 flex-none object-cover" src="/subframe-mark.svg" alt="Apache Magpie"/><img class="h-10 flex-none object-contain" src="/subframe-wordmark.png" alt="Magpie"/><span class="self-center -mt-2 -ml-2 text-[10px] font-[700] le [...]
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<h1 id="cursor-runtime-composer--agent-cli">Cursor runtime (Composer + Agent CLI)</h1>
+<p><strong>Capability:</strong> capability:platform</p>
+<p><strong>Harness:</strong> Cursor (Composer + Agent CLI)</p>
+<p>Cursor provides interactive and headless agent capabilities via Cursor Composer in the IDE and the <code>cursor-agent</code> CLI.
+This guide documents how Cursor operates as a first-class Apache Magpie skill runtime for <a href="https://github.com/apache/magpie/issues/316">#316</a>.</p>
+<p>Cursor integrates with Magpie without requiring custom skill copies, translation passes, or proprietary prompt wrappers.
+The integration follows <a href="/docs/rfcs/rfc-ai-0004">RFC-AI-0004 Principle 3 (Vendor Neutrality)</a> and <a href="/docs/adapters/add-a-harness">Adding a new agent harness</a>.</p>
+<h2 id="harness-contract">Harness contract</h2>
+<table>
+<thead>
+<tr>
+<th>Magpie requirement</th>
+<th>Cursor implementation</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Skill discovery</td>
+<td>Cursor reads the canonical <code>.agents/skills/magpie-*/SKILL.md</code> symlinks directly. The existing <code>universal</code> row in <code>skills/setup/agents.md</code> covers this path.</td>
+</tr>
+<tr>
+<td>Repository instructions</td>
+<td>Cursor ingests repository instructions from <code>AGENTS.md</code> and project rules from <code>.cursor/rules/</code> or <code>.cursorrules</code>.</td>
+</tr>
+<tr>
+<td>Human-in-the-loop (HITL)</td>
+<td>Cursor Composer enforces per-action approval modals for file edits and terminal commands. Auto-Run permissions map directly to Magpie’s proposal-then-confirm discipline.</td>
+</tr>
+<tr>
+<td>Tool bridges</td>
+<td>Skills invoke the standard <code>tools/*</code> CLI adapters. Network access for authenticated operations respects the project isolation policy.</td>
+</tr>
+<tr>
+<td>Model and MCP bridges</td>
+<td>Cursor’s MCP support connects to framework MCP servers (PonyMail, Gmail, ASF project metadata).</td>
+</tr>
+<tr>
+<td>Spec-loop</td>
+<td>The <code>cursor</code> profile forwards <code>--workspace</code>, <code>--print</code>, <code>--force</code>, and <code>--trust</code> flags for automated non-interactive runs.</td>
+</tr>
+<tr>
+<td>Credential isolation</td>
+<td><code>agent-iso</code> launches Cursor or <code>cursor-agent</code> through the shared clean-environment wrapper, stripping unapproved ambient tokens.</td>
+</tr>
+</tbody>
+</table>
+<h2 id="invoke-a-magpie-skill">Invoke a Magpie skill</h2>
+<p>After running <code>/magpie-setup</code> to adopt the repository, the canonical <code>.agents/skills/</code> links are active in your working tree.
+Cursor scans <code>.agents/skills/</code> and discovers all available Magpie workflows.</p>
+<h3 id="inside-cursor-composer-ide">Inside Cursor Composer (IDE)</h3>
+<ol>
+<li>Open the adopted project folder in Cursor.</li>
+<li>Open Cursor Composer (<code>Ctrl+I</code> / <code>Cmd+I</code> or <code>Ctrl+Shift+J</code> / <code>Cmd+Shift+J</code>).</li>
+<li>Mention or reference a skill, for example:
+<blockquote>
+<p>Use the <code>magpie-security-issue-triage</code> skill to triage the latest reports.</p>
+</blockquote>
+</li>
+<li>Composer resolves the referenced <code>SKILL.md</code> workflow, checks prerequisites, and presents a proposed plan before executing state mutations.</li>
+</ol>
+<h3 id="headless-or-cli-invocation-cursor-agent">Headless or CLI invocation (<code>cursor-agent</code>)</h3>
+<p>For non-interactive triage sweeps, automated spec-loops, or terminal sessions:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#6A737D"># Interactive terminal session with filtered environment</span></span>
+<span class="line"><span style="color:#B392F0">agent-iso</span><span style="color:#9ECBFF"> cursor-agent</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#6A737D"># Run a specific Magpie workflow headlessly</span></span>
+<span class="line"><span style="color:#B392F0">cursor-agent</span><span style="color:#79B8FF"> --print</span><span style="color:#79B8FF"> --workspace</span><span style="color:#9ECBFF"> /path/to/repo</span><span style="color:#9ECBFF"> "Run the magpie-list-skills skill and print the summary."</span></span></code></pre>
+<h2 id="human-in-the-loop-and-auto-run-controls">Human-in-the-loop and Auto-Run controls</h2>
+<p>Magpie enforces strict <a href="/docs/rfcs/rfc-ai-0004">Human-in-the-Loop principles</a>: no state mutation (closing issues, writing files, dispatching emails, pushing branches) occurs without explicit human approval.</p>
+<p>In Cursor:</p>
+<ul>
+<li><strong>Default mode</strong>: Every terminal command and write action requires an explicit <strong>Approve</strong> or <strong>Run</strong> click in the Composer UI.</li>
+<li><strong>Auto-Run allowlist</strong>: If you configure Auto-Run rules in Cursor settings, restrict allowlists strictly to read-only diagnostic commands (such as <code>git status</code>, <code>uv run pytest</code>, <code>gh issue list</code>).</li>
+<li><strong>Never auto-approve destructive commands</strong>: Commands that mutate remote trackers (<code>gh issue close</code>, <code>git push</code>, <code>gh pr create</code>) must always require human confirmation.</li>
+</ul>
+<h2 id="deterministic-guard-rules-and-tool-bridges">Deterministic guard rules and tool bridges</h2>
+<p>Cursor runs tool commands through standard subshells in your project environment.
+Deterministic tool scripts under <code>tools/</code> (e.g. <code>tools/cve-tool-vulnogram/</code>, <code>tools/github/</code>, <code>tools/privacy-llm/</code>) execute with standard Python / Groovy runtimes.</p>
+<p>When running in environments where <code>agent-guard</code> is enabled:</p>
+<ul>
+<li>The command dispatcher checks shell calls before execution.</li>
+<li>Any attempt to bypass git verification flags (such as <code>--no-verify</code>) or push to protected branches is rejected deterministically.</li>
+</ul>
+<h2 id="spec-loop-runner">Spec-loop runner</h2>
+<p>The <code>cursor</code> profile in <a href="https://github.com/apache/magpie/blob/main/tools/spec-loop/lib.sh"><code>tools/spec-loop/lib.sh</code></a> invokes the CLI headlessly:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#B392F0">cursor</span><span style="color:#9ECBFF"> agent</span><span style="color:#79B8FF"> --print</span><span style="color:#79B8FF"> --force</span><span style="color:#79B8FF"> --trust</span><span style="color:#79B8FF"> --workspace</span><span style="color:#9ECBFF"> "</span><span style="color:#E1E4E8">$root</s [...]
+<span class="line"><span style="color:#6A737D"># or via the standalone CLI</span></span>
+<span class="line"><span style="color:#B392F0">cursor-agent</span><span style="color:#79B8FF"> --print</span><span style="color:#79B8FF"> --force</span><span style="color:#79B8FF"> --trust</span><span style="color:#79B8FF"> --workspace</span><span style="color:#9ECBFF"> "</span><span style="color:#E1E4E8">$root</span><span style="color:#9ECBFF">"</span><span style="color:#9ECBFF"> "<prompt>"</span></span></code></pre>
+<p>Cursor does not provide a per-invocation reasoning-effort flag, so the runner omits reasoning-level parameters.
+See the <a href="https://github.com/apache/magpie/blob/main/tools/spec-loop/README.md">spec-loop guide</a> for full options.</p>
+<h2 id="clean-environment-wrapper">Clean-environment wrapper</h2>
+<p>To isolate sensitive tokens and run Cursor under the standard Magpie credential policy:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#79B8FF">source</span><span style="color:#F97583"> <</span><span style="color:#9ECBFF">framewor</span><span style="color:#E1E4E8">k</span><span style="color:#F97583">></span><span style="color:#9ECBFF">/tools/agent-isolation/agent-iso.sh</span></span>
+<span class="line"><span style="color:#B392F0">agent-iso</span><span style="color:#9ECBFF"> cursor</span><span style="color:#9ECBFF"> .</span></span></code></pre>
+<p>The <code>agent-iso</code> launcher scrubs undeclared environment variables while preserving local developer toolchains (<code>git</code>, <code>uv</code>, <code>gh</code>).</p>
+<h2 id="verify">Verify</h2>
+<p>Verify that the Cursor runtime wiring conforms to the framework standards:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#6A737D"># 1. Verify skill discovery topology</span></span>
+<span class="line"><span style="color:#E1E4E8">$env:PYTHONUTF8</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">1</span><span style="color:#E1E4E8">; </span><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> tools/symlink-lint</span><span style="color:#9ECBFF"> symlink-lint</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#6A737D"># 2. Validate skill and tool metadata</span></span>
+<span class="line"><span style="color:#E1E4E8">$env:PYTHONUTF8</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">1</span><span style="color:#E1E4E8">; </span><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> tools/skill-and-tool-validator</span><span style="color:#9ECBFF"> skill-and-tool-validate</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#6A737D"># 3. Check vendor neutrality score</span></span>
+<span class="line"><span style="color:#E1E4E8">$env:PYTHONUTF8</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">1</span><span style="color:#E1E4E8">; </span><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> tools/vendor-neutrality-score</span><span style="color:#9ECBFF"> vendor-neutrality-score</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#6A737D"># 4. Run pre-commit formatting and link verification</span></span>
+<span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#9ECBFF"> prek</span><span style="color:#9ECBFF"> run</span><span style="color:#9ECBFF"> doctoc</span><span style="color:#79B8FF"> --all-files</span></span></code></pre>
+<h2 id="see-also">See also</h2>
+<ul>
+<li><a href="/docs/adapters/add-a-harness"><code>docs/adapters/add-a-harness.md</code></a> — recipe for adding runtime harnesses.</li>
+<li><a href="https://github.com/apache/magpie/blob/main/skills/setup/agents.md"><code>skills/setup/agents.md</code></a> — agent-target registry (<code>universal</code> canonical path).</li>
+<li><a href="/docs/rfcs/rfc-ai-0004"><code>docs/rfcs/RFC-AI-0004.md</code></a> — normative principles for vendor neutrality and HITL.</li>
+<li><a href="/docs/vendor-neutrality"><code>docs/vendor-neutrality.md</code></a> — framework vendor neutrality index.</li>
+</ul>
+</article></main><aside class="hidden xl:block w-60 flex-none border-l border-solid border-neutral-200 bg-default-background sticky top-0 h-screen overflow-y-auto px-5 py-12"><div class="mb-3 text-caption font-caption uppercase tracking-wider text-subtext-color">On this page</div><nav><ul class="flex flex-col gap-1.5"><li><a href="#harness-contract" class="block text-caption font-caption text-subtext-color hover:text-brand-700" style="padding-left: 0rem">Harness contract</a></li><li><a h [...]
+ (() => {
+ const nav = document.getElementById("docs-nav-scroll");
+ if (!nav) return;
+ for (const link of nav.querySelectorAll("summary a[href]")) {
+ link.addEventListener("click", (event) => {
+ const branch = link.closest("details");
+ if (!branch) return;
+ const plainClick =
+ event.button === 0 &&
+ !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
+ if (plainClick) {
+ event.preventDefault();
+ branch.open = true;
+ window.location.href = link.href;
+ } else {
+ setTimeout(() => { branch.open = true; }, 0);
+ }
+ });
+ }
+ })();
+ </script><script>
+ (() => {
+ const scroller = document.getElementById("docs-nav-scroll");
+ const active = scroller?.querySelector('[aria-current="page"]');
+ if (!scroller || !active) return;
+ const target =
+ active.offsetTop - scroller.clientHeight / 2 + active.offsetHeight / 2;
+ scroller.scrollTop = Math.max(0, target);
+ })();
+ </script><a href="https://github.com/apache/magpie/edit/main/docs/adapters/cursor.md" target="_blank" rel="noopener noreferrer" class="suggest-change" aria-label="Suggest a change to this page on GitHub" data-astro-cid-z4jru4n3><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" data-astro-cid-z4jru4n3><path d="M12 20h9" data-astro-cid-z4jru4n3></path><path d="M16.5 3.5a2.12 [...]
\ No newline at end of file
diff --git a/docs/adapters/gemini.md b/docs/adapters/gemini.md
new file mode 100644
index 0000000..69b292a
--- /dev/null
+++ b/docs/adapters/gemini.md
@@ -0,0 +1,361 @@
+# Gemini CLI harness
+
+Rendered page: https://magpie.apache.org/docs/adapters/gemini/
+
+Source: https://github.com/apache/magpie/blob/main/docs/adapters/gemini.md
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+**Capability:** capability:platform
+
+**Harness:** Gemini CLI
+
+Gemini CLI runs Magpie's shared skills with repository instructions, an action guard, tool sandboxing, and per-action approval policies.
+The adapter is **experimental**: its Linux sandbox does not provide the Claude Code reference setup's home-directory read isolation or domain allowlist.
+The integration follows the harness contract in [add-a-harness](/docs/adapters/add-a-harness)
+and [RFC-AI-0004](/docs/rfcs/rfc-ai-0004).
+
+## Harness contract
+
+| Magpie requirement | Gemini CLI implementation |
+|---|---|
+| Skill discovery | Gemini reads the canonical `.agents/skills/magpie-*/SKILL.md` links. The existing `universal` row in `skills/setup/agents.md` covers this path. |
+| Repository instructions | The framework's `GEMINI.md` imports its `AGENTS.md`. |
+| Deterministic guard | Project `.gemini/settings.json` wires `agent_guard/__init__.py --gemini` to `BeforeTool` shell events, which call the harness-neutral `dispatch()` core. Adopters register the hook through the install lifecycle below. |
+| Spec-loop | The `gemini` profile forwards the prompt, model, and output format. |
+| Credential isolation | `agent-iso gemini` launches the CLI through the generic clean-environment wrapper, which filters inherited environment variables. |
+| Filesystem and network | `security.toolSandboxing: true` enables Gemini's tool sandboxing. The shipped profile adds no extra writable directories or network grant. See [Tool-sandboxing boundaries](#tool-sandboxing-boundaries) for the difference between native file tools and shell access. |
+| Tool approval | Explicit `policyPaths` loads `policies/magpie.toml`: scoped reads are allowed, other shell calls and native edits require confirmation, and selected commands and credential paths are denied. MCP calls require confirmation. |
+| MCP servers | Register the same server commands in Gemini's user settings; see [Reuse framework MCP servers](#reuse-framework-mcp-servers). No servers or credentials are installed by this profile. |
+
+## Invoke a Magpie skill
+
+Install the [Gemini extension](/docs/setup/marketplace-install#google-gemini-cli) through [setup](https://github.com/apache/magpie/blob/main/skills/setup/SKILL.md), or use the canonical `.agents/skills/` links with a pinned snapshot.
+Both methods expose the same skill sources.
+The framework's [`GEMINI.md`](https://github.com/apache/magpie/blob/main/GEMINI.md) imports `AGENTS.md`; adopters retain their own project instructions alongside that context.
+
+From the adopter repository root:
+
+1. Complete [installation](#install) and launch Gemini through the clean-environment wrapper.
+2. Use `/memory show` to inspect repository instructions and `/skills list` to check discovery.
+3. Ask `Use the magpie-list-skills skill.` and review the activation request.
+4. Approve the skill's catalogue script when prompted; interpreter commands require tool approval even for a read-only workflow.
+
+Skill activation consent and tool approval are separate decisions.
+Skills use the existing `tools/*` adapters, whose READMEs declare their prerequisites.
+
+## Install
+
+Use Gemini CLI **0.59.0 or later**.
+The validation baseline is 0.59.0 on Linux; later versions require [verification](#verify) before use.
+The tested Linux backend requires `bwrap` (bubblewrap), usable user namespaces, and ordinary shell utilities.
+Use the framework's [sandbox primitive versions](https://github.com/apache/magpie/blob/main/tools/agent-isolation/pinned-versions.toml) when installing bubblewrap.
+Python 3.11+ is required for profile linting and the existing action guard.
+
+For guided setup, ask Gemini: `Use the magpie-setup-isolated-setup-install skill.`
+The skill follows this procedure and proposes changes before applying them.
+No adopter project manifest is needed to configure the runtime itself.
+
+Resolve the framework directory from the installation already in use:
+
+| Installation | Framework directory and guard path |
+|---|---|
+| Gemini extension (default) | Use the installed Magpie path reported by `gemini extensions list`, or the resolved source of the active Magpie skill. Register the guard with that absolute path on this machine. |
+| Pinned snapshot | Use the adopter's `.apache-magpie/`. Register the guard relative to `${GEMINI_PROJECT_DIR}/.apache-magpie/` so linked worktrees use their own snapshot symlink. |
+| Framework checkout | Use the checkout root. Its committed settings already register the guard relative to `${GEMINI_PROJECT_DIR}/`. |
+
+Confirm that this directory contains `.gemini/settings.json`, `.gemini/policies/magpie.toml`, and `tools/agent-guard/src/agent_guard/__init__.py`.
+Do not add a snapshot alongside an installed extension or modify the installed framework sources.
+An extension provides skills and context; it does not automatically install the workspace profile.
+If native file tools cannot read shared framework resources outside the activated skill directory, use an approved shell read of the required files.
+
+1. **Inspect and propose.** Read the adopter's existing workspace settings, policies, and hook registrations, including any user-level Magpie guard.
+ Show the proposed file changes and any missing prerequisites; resolve conflicts with the operator before writing.
+ Invalid settings or unexpected value types require repair, not replacement with an empty configuration.
+2. **Merge the profile.** Copy the shipped policy into `.gemini/policies/magpie.toml` and merge the shipped `general`, `security`, and `tools` values into workspace `.gemini/settings.json`.
+ Preserve unrelated keys, including nested settings and MCP configuration.
+ Retain existing `policyPaths` and add the shipped paths once, including `~/.gemini/policies`; review additional policies or sandbox grants that can change the effective baseline.
+ Show edits to an existing `magpie.toml` before replacing it.
+3. **Register the guard.** Merge the [BeforeTool hook](https://github.com/apache/magpie/blob/main/tools/agent-guard/README.md#gemini-cli) using the framework path above.
+ Keep exactly one effective `magpie-agent-guard` registration; preserve unrelated matchers and hooks, and propose correcting a stale or duplicate Magpie entry instead of appending another.
+ Quote the path for the shell and encode the resulting command as JSON.
+ For a standard extension installation, use a home-relative shell path such as `"${HOME}/.gemini/extensions/magpie/tools/agent-guard/src/agent_guard/__init__.py"` to avoid committing a username.
+ Custom installation paths need a portability review before committing workspace settings.
+4. **Validate and launch.** Run the commands below from the adopter root, resolve lint failures, then use the [authentication recipe](#authentication-with-the-clean-environment-wrapper) to start a new session.
+ Review Gemini's [workspace trust request](https://geminicli.com/docs/cli/trusted-folders/) yourself; the skill does not edit trust records or credentials.
+ Complete [Verify](#verify) before reporting the setup as verified.
+
+Use the resolved framework directory in these commands:
+
+```bash
+source "<framework>/tools/agent-isolation/agent-iso.sh"
+uv run --project "<framework>/tools/sandbox-lint" sandbox-lint --gemini .gemini
+```
+
+The [committed settings](https://github.com/apache/magpie/blob/main/.gemini/settings.json) are the profile's source of truth; avoid maintaining a second settings template.
+On repeat installation, leave matching values and hooks unchanged.
+The native editing policy protects `.gemini/`, so apply an approved configuration patch through a normal terminal or an approved shell call; do not disable the policy to bootstrap it.
+Start each session from the directory containing `.gemini/`, because the policy path is relative to the launch directory.
+Restart Gemini after changing settings, policies, or the extension.
+
+### Authentication with the clean-environment wrapper
+
+The [clean-environment wrapper](https://github.com/apache/magpie/blob/main/tools/agent-isolation/README.md#explicit-environment-opt-in) strips inherited credentials and non-essential configuration variables.
+Use `AGENT_ISO_ALLOW` to pass only the variables needed by your selected [authentication method](https://geminicli.com/docs/get-started/authentication/):
+
+| Method | Variables to pass through |
+|---|---|
+| Gemini API key from Google AI Studio | `GEMINI_API_KEY` |
+| Vertex AI with Application Default Credentials (ADC) | `GOOGLE_CLOUD_PROJECT GOOGLE_CLOUD_LOCATION`; add `GOOGLE_APPLICATION_CREDENTIALS` for a custom credential-file path. |
+| Vertex AI with a Google Cloud API key | `GOOGLE_API_KEY GOOGLE_CLOUD_PROJECT GOOGLE_CLOUD_LOCATION` |
+| Sign in with Google | Usually none; pass `GOOGLE_CLOUD_PROJECT` if the account requires it. |
+
+Configure authentication in a normal terminal first, then select the matching method in Gemini.
+For an AI Studio key already set in your shell:
+
+```bash
+AGENT_ISO_ALLOW=GEMINI_API_KEY agent-iso gemini --approval-mode default
+```
+
+For Vertex with ADC and project/location already set:
+
+```bash
+AGENT_ISO_ALLOW="GOOGLE_CLOUD_PROJECT GOOGLE_CLOUD_LOCATION" \
+ agent-iso gemini --approval-mode default
+```
+
+For Google sign-in without additional variables, use `agent-iso gemini --approval-mode default`.
+Naming a variable does not obtain credentials; a later wrapped session must pass the required variables again.
+Keep persistent credentials in the runtime's home-directory storage or your secret manager, never in a project `.env` file.
+Explicitly passed credentials are available to the CLI; environment redaction for tools is a separate runtime control.
+
+## Security model
+
+### Tool-sandboxing boundaries
+
+`security.toolSandboxing: true` enables Gemini's tool sandboxing.
+On Linux, bubblewrap permits writes in the workspace and temporary areas; Magpie's profile starts without tool network access or additional allowed paths.
+Gemini's `--sandbox` flag selects a separate full-process sandbox and is not needed for this profile.
+See the upstream [sandbox guide](https://geminicli.com/docs/cli/sandbox/).
+
+**Native file tools and shell commands have different read boundaries.**
+Native file tools check paths against allowed workspace directories.
+The Linux backend mounts host files broadly read-only, so an approved shell command can read files outside the workspace that the backend has not masked.
+Magpie's credential-path policies deny matching native file-tool arguments; they do not prevent an approved shell from reading the same files.
+The upstream [bubblewrap argument builder](https://github.com/google-gemini/gemini-cli/blob/v0.59.0/packages/core/src/sandbox/linux/bwrapArgsBuilder.ts) defines these mounts.
+
+Tool approval authorizes an operation.
+**Sandbox expansion** separately grants network access or additional filesystem access when needed.
+Review the paths and duration of each grant: filesystem expansion can cover entire directories, and network expansion grants general network access rather than a domain allowlist.
+Existing session grants and `~/.gemini/policies/sandbox.toml` can widen the baseline; disabling remembered tool approvals does not remove saved sandbox grants.
+
+### What asks and what denies
+
+The shipped policy applies these decisions to model-requested tool calls in Default Mode:
+
+| Requested action | Result |
+|---|---|
+| Ordinary native workspace read | Allow under Gemini's built-in read policy. |
+| Listed inspection commands, such as `git status --short`, `git diff --stat`, or `gh pr view` | Allow; network access may still require sandbox expansion. |
+| Other shell commands, including tests, interpreters, `git push`, PR creation, and raw `gh api` calls | Ask before execution. |
+| Native file edits and MCP server tools | Ask for each call, including read-only MCP tools. |
+| Google web search (`google_web_search`) | Ask before each query is sent, including in Plan Mode; headless calls are refused. |
+| URL fetching (`web_fetch`) and MCP resource reads (`read_mcp_resource`) | Ask for each call, including in auto-edit and Plan Mode; headless calls are refused. |
+| Listed credential/export commands, such as `gh auth token`, `curl`, or cloud CLIs | Deny. |
+| Matching credential paths or `.env` files through native file/search tools | Deny. |
+| Native edits to `.gemini/`, `.geminiignore`, `GEMINI.md`, or `AGENTS.md` | Deny. |
+
+The [policy file](https://github.com/apache/magpie/blob/main/.gemini/policies/magpie.toml) defines the complete command and path lists.
+Read allowances match complete command arguments; unlisted Git flags, shell operators, substitutions, and complex quoting fall back to approval.
+This follows the shared intent of the Claude Code and Codex profiles: routine inspection proceeds, mutations require confirmation, and credential disclosure is denied.
+Each runtime implements its own rule precedence.
+
+The verified [v0.59.0 tool definitions](https://github.com/google-gemini/gemini-cli/blob/fb0d535af931b27c51e87e5e6ade72905b1e8390/packages/core/src/tools/tool-names.ts) name content search `grep_search`; the policy engine also matches the legacy `search_file_content` alias.
+The native probe checks canonical policy names, alias matching, and search/multi-file argument schemas against the loaded runtime.
+Google web search sends model-selected query text through Gemini's API outside the shell sandbox, so `sandboxNetworkAccess: false` does not prevent that disclosure.
+Review the query for confidential content before approving it; see the upstream [web-search reference](https://geminicli.com/docs/tools/web-search/).
+URL fetching also uses Gemini's API or a direct-fetch fallback outside the shell sandbox.
+The profile overrides Gemini's built-in auto-edit allowance for `web_fetch`; review the requested URLs before approving a fetch.
+The native `read_mcp_resource` tool retrieves content from an already configured MCP server and needs its own approval rule because the MCP server-tool wildcard does not match it.
+`list_mcp_resources` remains allowed: it lists the cached resource registry without making a resource-read request.
+
+Plan Mode retains scoped reads and denies other shell calls, file edits, and MCP server tools.
+Web search, URL fetching, and native MCP resource reads remain available with approval so they can supply context for planning.
+YOLO and remembered tool approvals are disabled, and automatic edit mode does not override the shipped ask/deny rules.
+These settings preserve [per-proposal confirmation](/docs/rfcs/rfc-ai-0004#principle-1--human-in-the-loop-on-every-state-change).
+Commands typed directly through Gemini's shell interface have different confirmation semantics from model-requested calls.
+
+### Policy loading and precedence
+
+Gemini 0.59.0 requires explicit `policyPaths` to load the workspace policy at **User** tier.
+The profile also retains `~/.gemini/policies`, because specifying paths replaces the default user-policy search path.
+See the upstream [policy reference](https://geminicli.com/docs/reference/policy-engine/).
+
+Within Magpie's policy, scoped read allows outrank fallback asks, while credential and configuration denies outrank both.
+Plan Mode rules preserve read-only behavior despite the higher tier of the workspace policy.
+Other user policies, administrative policies, command-line overrides, and sandbox grants can change the effective behavior.
+The static linter checks the project profile; [live verification](#verify) checks that it is active in your installation.
+
+### Deterministic guard rules
+
+The project `BeforeTool` hook passes shell commands to Magpie's shared [action guard](https://github.com/apache/magpie/blob/main/tools/agent-guard/README.md#gemini-cli).
+The guard enforces framework rules independently of model memory and returns Gemini's blocking exit code when a rule denies the command.
+It retains the shared guard's fail-open behavior for malformed events and covers shell calls; native file and MCP calls use the policy engine.
+
+The framework checkout registers the hook in `.gemini/settings.json` using `GEMINI_PROJECT_DIR`.
+Snapshot adopters must register it in their own workspace settings using the linked recipe; `/magpie-setup` does not yet install Gemini hooks.
+
+## Reuse framework MCP servers
+
+Register the servers selected by the adopter's tool configuration in Gemini's user-scoped [`mcpServers` settings](https://geminicli.com/docs/tools/mcp-server/).
+Reuse each adapter's server command, prerequisites, and home-directory credential storage; registrations in another runtime are not imported automatically.
+For example, the [Apache Projects](https://github.com/apache/magpie/blob/main/tools/apache-projects/tool.md#1-install-the-mcp-server) and [PonyMail](https://github.com/apache/magpie/blob/main/tools/ponymail/tool.md#1-install-the-mcp-server) adapters provide compatible server commands.
+Set `trust: false` and register only the servers the workflow needs.
+
+Restart Gemini and use `/mcp` to inspect connections and discovered operations.
+Tool names can differ from the Claude-oriented examples; select the equivalent server operation.
+Magpie's policy asks for every MCP server-tool call and denies those tools in Plan Mode.
+Native `read_mcp_resource` calls require approval in every mode, including Plan Mode; cached resource listing remains allowed.
+Tool sandboxing does not confine MCP server processes or their network connections.
+Live MCP connections and authenticated archive access have not been verified for this profile.
+
+## Spec-loop runner
+
+The existing `gemini` profile in
+[`tools/spec-loop/lib.sh`](https://github.com/apache/magpie/blob/main/tools/spec-loop/lib.sh) invokes the CLI with
+`--approval-mode default`, `--prompt`, and `--output-format`.
+It forwards `--model` when one is supplied.
+Gemini has no per-invocation effort flag in the inspected CLI, so the runner
+omits that option.
+
+**Upgrade behavior:** the earlier Gemini launcher used `--yolo`; it now preserves this profile's approval boundary with `--approval-mode default`.
+In headless mode, an action that needs confirmation is refused because there is no interactive approver.
+Native reads and the scoped shell reads can run, but a build iteration needing edits or other approval-required calls cannot complete unattended under this profile.
+Use an interactive session for those operations; the runner does not silently bypass the policy.
+See the [spec-loop guide](https://github.com/apache/magpie/blob/main/tools/spec-loop/README.md) for its operating
+environment and invocation options.
+
+## Verify
+
+Ask `Use the magpie-setup-isolated-setup-verify skill.`, or run these checks from the adopter root using the framework directory resolved during [Install](#install):
+
+```bash
+gemini --version
+bwrap --version
+uv run --project "<framework>/tools/sandbox-lint" sandbox-lint --gemini .gemini
+```
+
+Confirm that the configured guard path exists and resolves to the intended installation, and that only one Magpie guard is registered across workspace and user settings.
+The linter must report `OK`; it does not certify a running session.
+If `uv` needs writes outside the sandbox to prepare its environment, run the stdlib-only linter with an existing Python 3.11+ interpreter instead:
+
+```bash
+PYTHONPATH="<framework>/tools/sandbox-lint/src" \
+ python3 -B -c 'from sandbox_lint import main; raise SystemExit(main())' --gemini .gemini
+```
+
+Report each static and live check as passed, failed, or not run, with its evidence.
+If invoked from another runtime or a headless session, hand the live checks to an interactive Gemini session and report verification as incomplete.
+
+Launch through the wrapper and check `/settings` with **Workspace Settings** selected: **Tool Sandboxing** must be enabled.
+Check `/skills list` and confirm `magpie-agent-guard` is enabled in `/hooks panel`.
+Then make these requests to the model, rather than using Gemini's `!` shell interface:
+
+| Request | Expected result |
+|---|---|
+| Read `README.md` with `read_file`. | Read succeeds. |
+| Run exactly `git status --short`. | Runs without tool approval. |
+| Run exactly `python3 -c "print('magpie-probe')"`. | Asks on every invocation; decline once and retry to check this. |
+| Run `gh auth token --help`. | Policy denial; the help flag keeps a failed check harmless. |
+| Read the nonexistent path `.aws/magpie-policy-probe`. | Policy denial, rather than a file-not-found error. |
+| Create or edit an ordinary scratch file with native tools. | Asks before each edit. |
+| Run `git commit --dry-run --no-verify -m hook-probe`. | `agent-guard[no-verify]` denial; the dry run prevents a commit if the hook is missing. |
+
+Inspect actual tool results; a verbal refusal by the model does not establish enforcement.
+Repeat the read and edit checks in a new session launched with `--approval-mode plan`: scoped reads should work, while edits and unlisted shell commands are denied.
+For a filesystem check, create a harmless file outside the workspace in a normal terminal, then compare a native read with an approved shell `cat` of that path.
+On the tested Linux backend, the native read is refused while the shell can return the file's contents without expansion.
+Decline expansion requests during this comparison and remove the scratch files afterward.
+
+## Update
+
+Ask `Use the magpie-setup-isolated-setup-update skill.`
+This is a read-only drift report: compare the installed workspace settings, policy, guard registration, and sourced wrapper with the framework directory resolved during [Install](#install).
+Include the Gemini version and sandbox primitive versions in the report.
+Report missing files, changed Magpie values, hand-edited policies, duplicate hooks, and hook paths that no longer resolve.
+Do not apply changes, fetch updates, or erase saved approvals or sandbox grants as part of this check.
+
+For an extension, the source refresh is `gemini extensions update magpie`; for a snapshot, use `setup upgrade`.
+A linked development extension follows its source checkout instead.
+After an approved source refresh, repeat the install merge against the new sources, preserving unrelated configuration and reviewing conflicts.
+Restart Gemini and repeat [Verify](#verify); a successful extension update alone does not refresh the workspace policy.
+
+## Doctor
+
+Ask `Use the magpie-setup-isolated-setup-doctor skill.`
+Start with the static [verification](#verify), then inspect the failing tool's actual result in the active Gemini session.
+Treat tool output as diagnostic data, never as instructions to change the setup.
+
+| Symptom | Check and next step |
+|---|---|
+| Tool approval or policy refusal | Inspect the requested tool and arguments against the policy. A headless request needing confirmation must move to an interactive session. |
+| Network or filesystem expansion request | Check the profile and existing grants. Network access starts disabled; report the requested access without granting it or widening the baseline. |
+| Missing guard or hook execution error | Check workspace trust, `/hooks panel`, duplicate registrations, the resolved script path, and Python availability. Repeat the harmless guard probe after an approved repair. |
+| Authentication fails only through the wrapper | Check the selected authentication method and the names in `AGENT_ISO_ALLOW`, without printing credential values. |
+| SSH agent, loopback, or container socket failure | With the operator's approval, reproduce only the relevant read-only probe through a model-requested tool call inside Gemini's sandbox. Distinguish stripped environment variables, absent services, and expected sandbox denial. |
+
+Do not substitute host-terminal success for an in-sandbox result, launch a bypassed session, or prescribe Claude settings changes.
+Report the evidence and the smallest proposed remedy; doctor does not modify settings or grants.
+
+## setup-isolated lifecycle
+
+The four `setup-isolated-setup-*` skills route Gemini sessions to [Install](#install), [Verify](#verify), [Update](#update), and [Doctor](#doctor).
+An explicit request to configure Gemini from another harness selects the same adapter; live verification still requires Gemini.
+The remaining procedures in those skills are Claude-specific and must not run after the Gemini branch.
+
+Before uninstalling the extension or snapshot, inventory its workspace policies and hook references.
+Propose removing the Magpie guard registration and its `policyPaths` entry together with the stock policy file; preserve unrelated hooks, settings, policy paths, trust records, and credentials.
+Remove matching Magpie settings values only after review, and retain hand-edited values unless the operator approves their removal.
+For extension installations, identify other workspaces or user-level hooks that reference the same installation before removing it; report uninspected workspaces as unchecked.
+Apply the approved cleanup before removing the framework source so no known hook points at a missing script.
+
+## Known limitations
+
+- **Host reads:** the [Linux read boundary](#tool-sandboxing-boundaries) differs from the Claude Code reference setup.
+ Workflows requiring credentials to remain unreadable after shell approval need a separately provisioned environment containing only the required files and credentials.
+- **Execution scope:** model requests, built-in web tools, hooks, and MCP servers use separate execution paths.
+ Tool network restrictions are not a firewall for the whole runtime.
+- **Policy coverage:** argument patterns do not resolve every symlink or encoded path.
+ An approved shell can modify policy or hook files in the writable workspace; native editing-tool denies do not make them immutable.
+- **Platform and version:** runtime validation covers Gemini 0.59.0 on Linux.
+ macOS and Windows backends have not been verified, and the clean-environment wrapper requires a POSIX shell.
+ Repeat verification after upgrades.
+
+## Developer checks
+
+Run the affected package suites from the framework checkout:
+
+```bash
+uv run --directory tools/sandbox-lint --group dev pytest
+uv run --directory tools/agent-isolation --group dev pytest tests/test_generic_iso.py
+uv run --directory tools/agent-guard --group dev pytest
+bash tools/spec-loop/tests/test_runner_fixtures.sh
+```
+
+The sandbox-lint suite checks profile regressions without Gemini or Node.
+The optional [runtime integration tests](https://github.com/apache/magpie/blob/main/tools/sandbox-lint/tests/integration/README.md) additionally exercise Gemini's own policy engine and Linux sandbox using synthetic files, without a model or authentication.
+Use them when changing policy semantics or validating a runtime upgrade; normal CI runs the static checks only.
+Complete the shared [harness validation](/docs/adapters/add-a-harness#step-5--validate-the-full-wiring) before submitting adapter changes.
+
+## Upstream references
+
+- [Gemini skills](https://geminicli.com/docs/cli/using-agent-skills/)
+- [Gemini configuration](https://geminicli.com/docs/reference/configuration/)
+- [Gemini authentication](https://geminicli.com/docs/get-started/authentication/)
+- [Gemini tool sandboxing and sandbox expansion](https://geminicli.com/docs/cli/sandbox/#tool-sandboxing)
+- [Gemini policy engine](https://geminicli.com/docs/reference/policy-engine/)
+- [Gemini CLI source](https://github.com/google-gemini/gemini-cli)
diff --git a/docs/adapters/gemini/index.html b/docs/adapters/gemini/index.html
new file mode 100644
index 0000000..25d1ec9
--- /dev/null
+++ b/docs/adapters/gemini/index.html
@@ -0,0 +1,479 @@
+<!DOCTYPE html><html lang="en" data-astro-cid-z4jru4n3><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="description" content="AI-powered assistant for open-source maintainers. Triage, mentor, draft, pair, and auto-merge under Apache Software Foundation governance."><link rel="icon" type="image/svg+xml" href="/favicon.svg"><link rel="icon" type="image/x-icon" sizes="any" href="/favicon.ico"><title>Gemini CLI harness — Apache Mag [...]
+ var _paq = (window._paq = window._paq || []);
+ /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
+ _paq.push(["setDoNotTrack", true]);
+ _paq.push(["disableCookies"]);
+ _paq.push(["trackPageView"]);
+ _paq.push(["enableLinkTracking"]);
+ (function () {
+ var u = "https://analytics.apache.org/";
+ _paq.push(["setTrackerUrl", u + "matomo.php"]);
+ _paq.push(["setSiteId", "89"]);
+ var d = document,
+ g = d.createElement("script"),
+ s = d.getElementsByTagName("script")[0];
+ g.async = true;
+ g.src = u + "matomo.js";
+ s.parentNode.insertBefore(g, s);
+ })();
+ </script><link rel="stylesheet" href="/_astro/SiteFooter.C2Dgj2WR.css"><style>.tree-summary[data-astro-cid-lihgpoae]{list-style:none}.tree-summary[data-astro-cid-lihgpoae]::-webkit-details-marker{display:none}.tree-chevron[data-astro-cid-lihgpoae]{color:var(--color-subtext-color);transition:transform .15s}details[data-astro-cid-lihgpoae][open]>.tree-summary[data-astro-cid-lihgpoae] .tree-chevron[data-astro-cid-lihgpoae]{transform:rotate(90deg)}.prose h1{color:var(--color-default-font [...]
+</style></head><body data-astro-cid-z4jru4n3><nav class="relative z-10 flex w-full items-center justify-between bg-default-background px-8 py-5 mobile:px-4"><a href="/" aria-label="Apache Magpie home" class="flex items-end justify-end gap-2 px-2 py-2"><img class="h-10 w-10 flex-none object-cover" src="/subframe-mark.svg" alt="Apache Magpie"/><img class="h-10 flex-none object-contain" src="/subframe-wordmark.png" alt="Magpie"/><span class="self-center -mt-2 -ml-2 text-[10px] font-[700] le [...]
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<h1 id="gemini-cli-harness">Gemini CLI harness</h1>
+<p><strong>Capability:</strong> capability:platform</p>
+<p><strong>Harness:</strong> Gemini CLI</p>
+<p>Gemini CLI runs Magpie’s shared skills with repository instructions, an action guard, tool sandboxing, and per-action approval policies.
+The adapter is <strong>experimental</strong>: its Linux sandbox does not provide the Claude Code reference setup’s home-directory read isolation or domain allowlist.
+The integration follows the harness contract in <a href="/docs/adapters/add-a-harness">add-a-harness</a>
+and <a href="/docs/rfcs/rfc-ai-0004">RFC-AI-0004</a>.</p>
+<h2 id="harness-contract">Harness contract</h2>
+<table>
+<thead>
+<tr>
+<th>Magpie requirement</th>
+<th>Gemini CLI implementation</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Skill discovery</td>
+<td>Gemini reads the canonical <code>.agents/skills/magpie-*/SKILL.md</code> links. The existing <code>universal</code> row in <code>skills/setup/agents.md</code> covers this path.</td>
+</tr>
+<tr>
+<td>Repository instructions</td>
+<td>The framework’s <code>GEMINI.md</code> imports its <code>AGENTS.md</code>.</td>
+</tr>
+<tr>
+<td>Deterministic guard</td>
+<td>Project <code>.gemini/settings.json</code> wires <code>agent_guard/__init__.py --gemini</code> to <code>BeforeTool</code> shell events, which call the harness-neutral <code>dispatch()</code> core. Adopters register the hook through the install lifecycle below.</td>
+</tr>
+<tr>
+<td>Spec-loop</td>
+<td>The <code>gemini</code> profile forwards the prompt, model, and output format.</td>
+</tr>
+<tr>
+<td>Credential isolation</td>
+<td><code>agent-iso gemini</code> launches the CLI through the generic clean-environment wrapper, which filters inherited environment variables.</td>
+</tr>
+<tr>
+<td>Filesystem and network</td>
+<td><code>security.toolSandboxing: true</code> enables Gemini’s tool sandboxing. The shipped profile adds no extra writable directories or network grant. See <a href="#tool-sandboxing-boundaries">Tool-sandboxing boundaries</a> for the difference between native file tools and shell access.</td>
+</tr>
+<tr>
+<td>Tool approval</td>
+<td>Explicit <code>policyPaths</code> loads <code>policies/magpie.toml</code>: scoped reads are allowed, other shell calls and native edits require confirmation, and selected commands and credential paths are denied. MCP calls require confirmation.</td>
+</tr>
+<tr>
+<td>MCP servers</td>
+<td>Register the same server commands in Gemini’s user settings; see <a href="#reuse-framework-mcp-servers">Reuse framework MCP servers</a>. No servers or credentials are installed by this profile.</td>
+</tr>
+</tbody>
+</table>
+<h2 id="invoke-a-magpie-skill">Invoke a Magpie skill</h2>
+<p>Install the <a href="/docs/setup/marketplace-install#google-gemini-cli">Gemini extension</a> through <a href="https://github.com/apache/magpie/blob/main/skills/setup/SKILL.md">setup</a>, or use the canonical <code>.agents/skills/</code> links with a pinned snapshot.
+Both methods expose the same skill sources.
+The framework’s <a href="https://github.com/apache/magpie/blob/main/GEMINI.md"><code>GEMINI.md</code></a> imports <code>AGENTS.md</code>; adopters retain their own project instructions alongside that context.</p>
+<p>From the adopter repository root:</p>
+<ol>
+<li>Complete <a href="#install">installation</a> and launch Gemini through the clean-environment wrapper.</li>
+<li>Use <code>/memory show</code> to inspect repository instructions and <code>/skills list</code> to check discovery.</li>
+<li>Ask <code>Use the magpie-list-skills skill.</code> and review the activation request.</li>
+<li>Approve the skill’s catalogue script when prompted; interpreter commands require tool approval even for a read-only workflow.</li>
+</ol>
+<p>Skill activation consent and tool approval are separate decisions.
+Skills use the existing <code>tools/*</code> adapters, whose READMEs declare their prerequisites.</p>
+<h2 id="install">Install</h2>
+<p>Use Gemini CLI <strong>0.59.0 or later</strong>.
+The validation baseline is 0.59.0 on Linux; later versions require <a href="#verify">verification</a> before use.
+The tested Linux backend requires <code>bwrap</code> (bubblewrap), usable user namespaces, and ordinary shell utilities.
+Use the framework’s <a href="https://github.com/apache/magpie/blob/main/tools/agent-isolation/pinned-versions.toml">sandbox primitive versions</a> when installing bubblewrap.
+Python 3.11+ is required for profile linting and the existing action guard.</p>
+<p>For guided setup, ask Gemini: <code>Use the magpie-setup-isolated-setup-install skill.</code>
+The skill follows this procedure and proposes changes before applying them.
+No adopter project manifest is needed to configure the runtime itself.</p>
+<p>Resolve the framework directory from the installation already in use:</p>
+<table>
+<thead>
+<tr>
+<th>Installation</th>
+<th>Framework directory and guard path</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Gemini extension (default)</td>
+<td>Use the installed Magpie path reported by <code>gemini extensions list</code>, or the resolved source of the active Magpie skill. Register the guard with that absolute path on this machine.</td>
+</tr>
+<tr>
+<td>Pinned snapshot</td>
+<td>Use the adopter’s <code>.apache-magpie/</code>. Register the guard relative to <code>${GEMINI_PROJECT_DIR}/.apache-magpie/</code> so linked worktrees use their own snapshot symlink.</td>
+</tr>
+<tr>
+<td>Framework checkout</td>
+<td>Use the checkout root. Its committed settings already register the guard relative to <code>${GEMINI_PROJECT_DIR}/</code>.</td>
+</tr>
+</tbody>
+</table>
+<p>Confirm that this directory contains <code>.gemini/settings.json</code>, <code>.gemini/policies/magpie.toml</code>, and <code>tools/agent-guard/src/agent_guard/__init__.py</code>.
+Do not add a snapshot alongside an installed extension or modify the installed framework sources.
+An extension provides skills and context; it does not automatically install the workspace profile.
+If native file tools cannot read shared framework resources outside the activated skill directory, use an approved shell read of the required files.</p>
+<ol>
+<li><strong>Inspect and propose.</strong> Read the adopter’s existing workspace settings, policies, and hook registrations, including any user-level Magpie guard.
+Show the proposed file changes and any missing prerequisites; resolve conflicts with the operator before writing.
+Invalid settings or unexpected value types require repair, not replacement with an empty configuration.</li>
+<li><strong>Merge the profile.</strong> Copy the shipped policy into <code>.gemini/policies/magpie.toml</code> and merge the shipped <code>general</code>, <code>security</code>, and <code>tools</code> values into workspace <code>.gemini/settings.json</code>.
+Preserve unrelated keys, including nested settings and MCP configuration.
+Retain existing <code>policyPaths</code> and add the shipped paths once, including <code>~/.gemini/policies</code>; review additional policies or sandbox grants that can change the effective baseline.
+Show edits to an existing <code>magpie.toml</code> before replacing it.</li>
+<li><strong>Register the guard.</strong> Merge the <a href="https://github.com/apache/magpie/blob/main/tools/agent-guard/README.md#gemini-cli">BeforeTool hook</a> using the framework path above.
+Keep exactly one effective <code>magpie-agent-guard</code> registration; preserve unrelated matchers and hooks, and propose correcting a stale or duplicate Magpie entry instead of appending another.
+Quote the path for the shell and encode the resulting command as JSON.
+For a standard extension installation, use a home-relative shell path such as <code>"${HOME}/.gemini/extensions/magpie/tools/agent-guard/src/agent_guard/__init__.py"</code> to avoid committing a username.
+Custom installation paths need a portability review before committing workspace settings.</li>
+<li><strong>Validate and launch.</strong> Run the commands below from the adopter root, resolve lint failures, then use the <a href="#authentication-with-the-clean-environment-wrapper">authentication recipe</a> to start a new session.
+Review Gemini’s <a href="https://geminicli.com/docs/cli/trusted-folders/">workspace trust request</a> yourself; the skill does not edit trust records or credentials.
+Complete <a href="#verify">Verify</a> before reporting the setup as verified.</li>
+</ol>
+<p>Use the resolved framework directory in these commands:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#79B8FF">source</span><span style="color:#9ECBFF"> "<framework>/tools/agent-isolation/agent-iso.sh"</span></span>
+<span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> "<framework>/tools/sandbox-lint"</span><span style="color:#9ECBFF"> sandbox-lint</span><span style="color:#79B8FF"> --gemini</span><span style="color:#9ECBFF"> .gemini</span></span></code></pre>
+<p>The <a href="https://github.com/apache/magpie/blob/main/.gemini/settings.json">committed settings</a> are the profile’s source of truth; avoid maintaining a second settings template.
+On repeat installation, leave matching values and hooks unchanged.
+The native editing policy protects <code>.gemini/</code>, so apply an approved configuration patch through a normal terminal or an approved shell call; do not disable the policy to bootstrap it.
+Start each session from the directory containing <code>.gemini/</code>, because the policy path is relative to the launch directory.
+Restart Gemini after changing settings, policies, or the extension.</p>
+<h3 id="authentication-with-the-clean-environment-wrapper">Authentication with the clean-environment wrapper</h3>
+<p>The <a href="https://github.com/apache/magpie/blob/main/tools/agent-isolation/README.md#explicit-environment-opt-in">clean-environment wrapper</a> strips inherited credentials and non-essential configuration variables.
+Use <code>AGENT_ISO_ALLOW</code> to pass only the variables needed by your selected <a href="https://geminicli.com/docs/get-started/authentication/">authentication method</a>:</p>
+<table>
+<thead>
+<tr>
+<th>Method</th>
+<th>Variables to pass through</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Gemini API key from Google AI Studio</td>
+<td><code>GEMINI_API_KEY</code></td>
+</tr>
+<tr>
+<td>Vertex AI with Application Default Credentials (ADC)</td>
+<td><code>GOOGLE_CLOUD_PROJECT GOOGLE_CLOUD_LOCATION</code>; add <code>GOOGLE_APPLICATION_CREDENTIALS</code> for a custom credential-file path.</td>
+</tr>
+<tr>
+<td>Vertex AI with a Google Cloud API key</td>
+<td><code>GOOGLE_API_KEY GOOGLE_CLOUD_PROJECT GOOGLE_CLOUD_LOCATION</code></td>
+</tr>
+<tr>
+<td>Sign in with Google</td>
+<td>Usually none; pass <code>GOOGLE_CLOUD_PROJECT</code> if the account requires it.</td>
+</tr>
+</tbody>
+</table>
+<p>Configure authentication in a normal terminal first, then select the matching method in Gemini.
+For an AI Studio key already set in your shell:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#E1E4E8">AGENT_ISO_ALLOW</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">GEMINI_API_KEY</span><span style="color:#B392F0"> agent-iso</span><span style="color:#9ECBFF"> gemini</span><span style="color:#79B8FF"> --approval-mode</span><span style="color:#9ECBFF"> default</span></span></code></pre>
+<p>For Vertex with ADC and project/location already set:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#E1E4E8">AGENT_ISO_ALLOW</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">"GOOGLE_CLOUD_PROJECT GOOGLE_CLOUD_LOCATION"</span><span style="color:#B392F0"> \</span></span>
+<span class="line"><span style="color:#9ECBFF"> agent-iso</span><span style="color:#9ECBFF"> gemini</span><span style="color:#79B8FF"> --approval-mode</span><span style="color:#9ECBFF"> default</span></span></code></pre>
+<p>For Google sign-in without additional variables, use <code>agent-iso gemini --approval-mode default</code>.
+Naming a variable does not obtain credentials; a later wrapped session must pass the required variables again.
+Keep persistent credentials in the runtime’s home-directory storage or your secret manager, never in a project <code>.env</code> file.
+Explicitly passed credentials are available to the CLI; environment redaction for tools is a separate runtime control.</p>
+<h2 id="security-model">Security model</h2>
+<h3 id="tool-sandboxing-boundaries">Tool-sandboxing boundaries</h3>
+<p><code>security.toolSandboxing: true</code> enables Gemini’s tool sandboxing.
+On Linux, bubblewrap permits writes in the workspace and temporary areas; Magpie’s profile starts without tool network access or additional allowed paths.
+Gemini’s <code>--sandbox</code> flag selects a separate full-process sandbox and is not needed for this profile.
+See the upstream <a href="https://geminicli.com/docs/cli/sandbox/">sandbox guide</a>.</p>
+<p><strong>Native file tools and shell commands have different read boundaries.</strong>
+Native file tools check paths against allowed workspace directories.
+The Linux backend mounts host files broadly read-only, so an approved shell command can read files outside the workspace that the backend has not masked.
+Magpie’s credential-path policies deny matching native file-tool arguments; they do not prevent an approved shell from reading the same files.
+The upstream <a href="https://github.com/google-gemini/gemini-cli/blob/v0.59.0/packages/core/src/sandbox/linux/bwrapArgsBuilder.ts">bubblewrap argument builder</a> defines these mounts.</p>
+<p>Tool approval authorizes an operation.
+<strong>Sandbox expansion</strong> separately grants network access or additional filesystem access when needed.
+Review the paths and duration of each grant: filesystem expansion can cover entire directories, and network expansion grants general network access rather than a domain allowlist.
+Existing session grants and <code>~/.gemini/policies/sandbox.toml</code> can widen the baseline; disabling remembered tool approvals does not remove saved sandbox grants.</p>
+<h3 id="what-asks-and-what-denies">What asks and what denies</h3>
+<p>The shipped policy applies these decisions to model-requested tool calls in Default Mode:</p>
+<table>
+<thead>
+<tr>
+<th>Requested action</th>
+<th>Result</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Ordinary native workspace read</td>
+<td>Allow under Gemini’s built-in read policy.</td>
+</tr>
+<tr>
+<td>Listed inspection commands, such as <code>git status --short</code>, <code>git diff --stat</code>, or <code>gh pr view</code></td>
+<td>Allow; network access may still require sandbox expansion.</td>
+</tr>
+<tr>
+<td>Other shell commands, including tests, interpreters, <code>git push</code>, PR creation, and raw <code>gh api</code> calls</td>
+<td>Ask before execution.</td>
+</tr>
+<tr>
+<td>Native file edits and MCP server tools</td>
+<td>Ask for each call, including read-only MCP tools.</td>
+</tr>
+<tr>
+<td>Google web search (<code>google_web_search</code>)</td>
+<td>Ask before each query is sent, including in Plan Mode; headless calls are refused.</td>
+</tr>
+<tr>
+<td>URL fetching (<code>web_fetch</code>) and MCP resource reads (<code>read_mcp_resource</code>)</td>
+<td>Ask for each call, including in auto-edit and Plan Mode; headless calls are refused.</td>
+</tr>
+<tr>
+<td>Listed credential/export commands, such as <code>gh auth token</code>, <code>curl</code>, or cloud CLIs</td>
+<td>Deny.</td>
+</tr>
+<tr>
+<td>Matching credential paths or <code>.env</code> files through native file/search tools</td>
+<td>Deny.</td>
+</tr>
+<tr>
+<td>Native edits to <code>.gemini/</code>, <code>.geminiignore</code>, <code>GEMINI.md</code>, or <code>AGENTS.md</code></td>
+<td>Deny.</td>
+</tr>
+</tbody>
+</table>
+<p>The <a href="https://github.com/apache/magpie/blob/main/.gemini/policies/magpie.toml">policy file</a> defines the complete command and path lists.
+Read allowances match complete command arguments; unlisted Git flags, shell operators, substitutions, and complex quoting fall back to approval.
+This follows the shared intent of the Claude Code and Codex profiles: routine inspection proceeds, mutations require confirmation, and credential disclosure is denied.
+Each runtime implements its own rule precedence.</p>
+<p>The verified <a href="https://github.com/google-gemini/gemini-cli/blob/fb0d535af931b27c51e87e5e6ade72905b1e8390/packages/core/src/tools/tool-names.ts">v0.59.0 tool definitions</a> name content search <code>grep_search</code>; the policy engine also matches the legacy <code>search_file_content</code> alias.
+The native probe checks canonical policy names, alias matching, and search/multi-file argument schemas against the loaded runtime.
+Google web search sends model-selected query text through Gemini’s API outside the shell sandbox, so <code>sandboxNetworkAccess: false</code> does not prevent that disclosure.
+Review the query for confidential content before approving it; see the upstream <a href="https://geminicli.com/docs/tools/web-search/">web-search reference</a>.
+URL fetching also uses Gemini’s API or a direct-fetch fallback outside the shell sandbox.
+The profile overrides Gemini’s built-in auto-edit allowance for <code>web_fetch</code>; review the requested URLs before approving a fetch.
+The native <code>read_mcp_resource</code> tool retrieves content from an already configured MCP server and needs its own approval rule because the MCP server-tool wildcard does not match it.
+<code>list_mcp_resources</code> remains allowed: it lists the cached resource registry without making a resource-read request.</p>
+<p>Plan Mode retains scoped reads and denies other shell calls, file edits, and MCP server tools.
+Web search, URL fetching, and native MCP resource reads remain available with approval so they can supply context for planning.
+YOLO and remembered tool approvals are disabled, and automatic edit mode does not override the shipped ask/deny rules.
+These settings preserve <a href="/docs/rfcs/rfc-ai-0004#principle-1--human-in-the-loop-on-every-state-change">per-proposal confirmation</a>.
+Commands typed directly through Gemini’s shell interface have different confirmation semantics from model-requested calls.</p>
+<h3 id="policy-loading-and-precedence">Policy loading and precedence</h3>
+<p>Gemini 0.59.0 requires explicit <code>policyPaths</code> to load the workspace policy at <strong>User</strong> tier.
+The profile also retains <code>~/.gemini/policies</code>, because specifying paths replaces the default user-policy search path.
+See the upstream <a href="https://geminicli.com/docs/reference/policy-engine/">policy reference</a>.</p>
+<p>Within Magpie’s policy, scoped read allows outrank fallback asks, while credential and configuration denies outrank both.
+Plan Mode rules preserve read-only behavior despite the higher tier of the workspace policy.
+Other user policies, administrative policies, command-line overrides, and sandbox grants can change the effective behavior.
+The static linter checks the project profile; <a href="#verify">live verification</a> checks that it is active in your installation.</p>
+<h3 id="deterministic-guard-rules">Deterministic guard rules</h3>
+<p>The project <code>BeforeTool</code> hook passes shell commands to Magpie’s shared <a href="https://github.com/apache/magpie/blob/main/tools/agent-guard/README.md#gemini-cli">action guard</a>.
+The guard enforces framework rules independently of model memory and returns Gemini’s blocking exit code when a rule denies the command.
+It retains the shared guard’s fail-open behavior for malformed events and covers shell calls; native file and MCP calls use the policy engine.</p>
+<p>The framework checkout registers the hook in <code>.gemini/settings.json</code> using <code>GEMINI_PROJECT_DIR</code>.
+Snapshot adopters must register it in their own workspace settings using the linked recipe; <code>/magpie-setup</code> does not yet install Gemini hooks.</p>
+<h2 id="reuse-framework-mcp-servers">Reuse framework MCP servers</h2>
+<p>Register the servers selected by the adopter’s tool configuration in Gemini’s user-scoped <a href="https://geminicli.com/docs/tools/mcp-server/"><code>mcpServers</code> settings</a>.
+Reuse each adapter’s server command, prerequisites, and home-directory credential storage; registrations in another runtime are not imported automatically.
+For example, the <a href="https://github.com/apache/magpie/blob/main/tools/apache-projects/tool.md#1-install-the-mcp-server">Apache Projects</a> and <a href="https://github.com/apache/magpie/blob/main/tools/ponymail/tool.md#1-install-the-mcp-server">PonyMail</a> adapters provide compatible server commands.
+Set <code>trust: false</code> and register only the servers the workflow needs.</p>
+<p>Restart Gemini and use <code>/mcp</code> to inspect connections and discovered operations.
+Tool names can differ from the Claude-oriented examples; select the equivalent server operation.
+Magpie’s policy asks for every MCP server-tool call and denies those tools in Plan Mode.
+Native <code>read_mcp_resource</code> calls require approval in every mode, including Plan Mode; cached resource listing remains allowed.
+Tool sandboxing does not confine MCP server processes or their network connections.
+Live MCP connections and authenticated archive access have not been verified for this profile.</p>
+<h2 id="spec-loop-runner">Spec-loop runner</h2>
+<p>The existing <code>gemini</code> profile in
+<a href="https://github.com/apache/magpie/blob/main/tools/spec-loop/lib.sh"><code>tools/spec-loop/lib.sh</code></a> invokes the CLI with
+<code>--approval-mode default</code>, <code>--prompt</code>, and <code>--output-format</code>.
+It forwards <code>--model</code> when one is supplied.
+Gemini has no per-invocation effort flag in the inspected CLI, so the runner
+omits that option.</p>
+<p><strong>Upgrade behavior:</strong> the earlier Gemini launcher used <code>--yolo</code>; it now preserves this profile’s approval boundary with <code>--approval-mode default</code>.
+In headless mode, an action that needs confirmation is refused because there is no interactive approver.
+Native reads and the scoped shell reads can run, but a build iteration needing edits or other approval-required calls cannot complete unattended under this profile.
+Use an interactive session for those operations; the runner does not silently bypass the policy.
+See the <a href="https://github.com/apache/magpie/blob/main/tools/spec-loop/README.md">spec-loop guide</a> for its operating
+environment and invocation options.</p>
+<h2 id="verify">Verify</h2>
+<p>Ask <code>Use the magpie-setup-isolated-setup-verify skill.</code>, or run these checks from the adopter root using the framework directory resolved during <a href="#install">Install</a>:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#B392F0">gemini</span><span style="color:#79B8FF"> --version</span></span>
+<span class="line"><span style="color:#B392F0">bwrap</span><span style="color:#79B8FF"> --version</span></span>
+<span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> "<framework>/tools/sandbox-lint"</span><span style="color:#9ECBFF"> sandbox-lint</span><span style="color:#79B8FF"> --gemini</span><span style="color:#9ECBFF"> .gemini</span></span></code></pre>
+<p>Confirm that the configured guard path exists and resolves to the intended installation, and that only one Magpie guard is registered across workspace and user settings.
+The linter must report <code>OK</code>; it does not certify a running session.
+If <code>uv</code> needs writes outside the sandbox to prepare its environment, run the stdlib-only linter with an existing Python 3.11+ interpreter instead:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#E1E4E8">PYTHONPATH</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">"<framework>/tools/sandbox-lint/src"</span><span style="color:#B392F0"> \</span></span>
+<span class="line"><span style="color:#9ECBFF"> python3</span><span style="color:#79B8FF"> -B</span><span style="color:#79B8FF"> -c</span><span style="color:#9ECBFF"> 'from sandbox_lint import main; raise SystemExit(main())'</span><span style="color:#79B8FF"> --gemini</span><span style="color:#9ECBFF"> .gemini</span></span></code></pre>
+<p>Report each static and live check as passed, failed, or not run, with its evidence.
+If invoked from another runtime or a headless session, hand the live checks to an interactive Gemini session and report verification as incomplete.</p>
+<p>Launch through the wrapper and check <code>/settings</code> with <strong>Workspace Settings</strong> selected: <strong>Tool Sandboxing</strong> must be enabled.
+Check <code>/skills list</code> and confirm <code>magpie-agent-guard</code> is enabled in <code>/hooks panel</code>.
+Then make these requests to the model, rather than using Gemini’s <code>!</code> shell interface:</p>
+<table>
+<thead>
+<tr>
+<th>Request</th>
+<th>Expected result</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Read <code>README.md</code> with <code>read_file</code>.</td>
+<td>Read succeeds.</td>
+</tr>
+<tr>
+<td>Run exactly <code>git status --short</code>.</td>
+<td>Runs without tool approval.</td>
+</tr>
+<tr>
+<td>Run exactly <code>python3 -c "print('magpie-probe')"</code>.</td>
+<td>Asks on every invocation; decline once and retry to check this.</td>
+</tr>
+<tr>
+<td>Run <code>gh auth token --help</code>.</td>
+<td>Policy denial; the help flag keeps a failed check harmless.</td>
+</tr>
+<tr>
+<td>Read the nonexistent path <code>.aws/magpie-policy-probe</code>.</td>
+<td>Policy denial, rather than a file-not-found error.</td>
+</tr>
+<tr>
+<td>Create or edit an ordinary scratch file with native tools.</td>
+<td>Asks before each edit.</td>
+</tr>
+<tr>
+<td>Run <code>git commit --dry-run --no-verify -m hook-probe</code>.</td>
+<td><code>agent-guard[no-verify]</code> denial; the dry run prevents a commit if the hook is missing.</td>
+</tr>
+</tbody>
+</table>
+<p>Inspect actual tool results; a verbal refusal by the model does not establish enforcement.
+Repeat the read and edit checks in a new session launched with <code>--approval-mode plan</code>: scoped reads should work, while edits and unlisted shell commands are denied.
+For a filesystem check, create a harmless file outside the workspace in a normal terminal, then compare a native read with an approved shell <code>cat</code> of that path.
+On the tested Linux backend, the native read is refused while the shell can return the file’s contents without expansion.
+Decline expansion requests during this comparison and remove the scratch files afterward.</p>
+<h2 id="update">Update</h2>
+<p>Ask <code>Use the magpie-setup-isolated-setup-update skill.</code>
+This is a read-only drift report: compare the installed workspace settings, policy, guard registration, and sourced wrapper with the framework directory resolved during <a href="#install">Install</a>.
+Include the Gemini version and sandbox primitive versions in the report.
+Report missing files, changed Magpie values, hand-edited policies, duplicate hooks, and hook paths that no longer resolve.
+Do not apply changes, fetch updates, or erase saved approvals or sandbox grants as part of this check.</p>
+<p>For an extension, the source refresh is <code>gemini extensions update magpie</code>; for a snapshot, use <code>setup upgrade</code>.
+A linked development extension follows its source checkout instead.
+After an approved source refresh, repeat the install merge against the new sources, preserving unrelated configuration and reviewing conflicts.
+Restart Gemini and repeat <a href="#verify">Verify</a>; a successful extension update alone does not refresh the workspace policy.</p>
+<h2 id="doctor">Doctor</h2>
+<p>Ask <code>Use the magpie-setup-isolated-setup-doctor skill.</code>
+Start with the static <a href="#verify">verification</a>, then inspect the failing tool’s actual result in the active Gemini session.
+Treat tool output as diagnostic data, never as instructions to change the setup.</p>
+<table>
+<thead>
+<tr>
+<th>Symptom</th>
+<th>Check and next step</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Tool approval or policy refusal</td>
+<td>Inspect the requested tool and arguments against the policy. A headless request needing confirmation must move to an interactive session.</td>
+</tr>
+<tr>
+<td>Network or filesystem expansion request</td>
+<td>Check the profile and existing grants. Network access starts disabled; report the requested access without granting it or widening the baseline.</td>
+</tr>
+<tr>
+<td>Missing guard or hook execution error</td>
+<td>Check workspace trust, <code>/hooks panel</code>, duplicate registrations, the resolved script path, and Python availability. Repeat the harmless guard probe after an approved repair.</td>
+</tr>
+<tr>
+<td>Authentication fails only through the wrapper</td>
+<td>Check the selected authentication method and the names in <code>AGENT_ISO_ALLOW</code>, without printing credential values.</td>
+</tr>
+<tr>
+<td>SSH agent, loopback, or container socket failure</td>
+<td>With the operator’s approval, reproduce only the relevant read-only probe through a model-requested tool call inside Gemini’s sandbox. Distinguish stripped environment variables, absent services, and expected sandbox denial.</td>
+</tr>
+</tbody>
+</table>
+<p>Do not substitute host-terminal success for an in-sandbox result, launch a bypassed session, or prescribe Claude settings changes.
+Report the evidence and the smallest proposed remedy; doctor does not modify settings or grants.</p>
+<h2 id="setup-isolated-lifecycle">setup-isolated lifecycle</h2>
+<p>The four <code>setup-isolated-setup-*</code> skills route Gemini sessions to <a href="#install">Install</a>, <a href="#verify">Verify</a>, <a href="#update">Update</a>, and <a href="#doctor">Doctor</a>.
+An explicit request to configure Gemini from another harness selects the same adapter; live verification still requires Gemini.
+The remaining procedures in those skills are Claude-specific and must not run after the Gemini branch.</p>
+<p>Before uninstalling the extension or snapshot, inventory its workspace policies and hook references.
+Propose removing the Magpie guard registration and its <code>policyPaths</code> entry together with the stock policy file; preserve unrelated hooks, settings, policy paths, trust records, and credentials.
+Remove matching Magpie settings values only after review, and retain hand-edited values unless the operator approves their removal.
+For extension installations, identify other workspaces or user-level hooks that reference the same installation before removing it; report uninspected workspaces as unchecked.
+Apply the approved cleanup before removing the framework source so no known hook points at a missing script.</p>
+<h2 id="known-limitations">Known limitations</h2>
+<ul>
+<li><strong>Host reads:</strong> the <a href="#tool-sandboxing-boundaries">Linux read boundary</a> differs from the Claude Code reference setup.
+Workflows requiring credentials to remain unreadable after shell approval need a separately provisioned environment containing only the required files and credentials.</li>
+<li><strong>Execution scope:</strong> model requests, built-in web tools, hooks, and MCP servers use separate execution paths.
+Tool network restrictions are not a firewall for the whole runtime.</li>
+<li><strong>Policy coverage:</strong> argument patterns do not resolve every symlink or encoded path.
+An approved shell can modify policy or hook files in the writable workspace; native editing-tool denies do not make them immutable.</li>
+<li><strong>Platform and version:</strong> runtime validation covers Gemini 0.59.0 on Linux.
+macOS and Windows backends have not been verified, and the clean-environment wrapper requires a POSIX shell.
+Repeat verification after upgrades.</li>
+</ul>
+<h2 id="developer-checks">Developer checks</h2>
+<p>Run the affected package suites from the framework checkout:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --directory</span><span style="color:#9ECBFF"> tools/sandbox-lint</span><span style="color:#79B8FF"> --group</span><span style="color:#9ECBFF"> dev</span><span style="color:#9ECBFF"> pytest</span></span>
+<span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --directory</span><span style="color:#9ECBFF"> tools/agent-isolation</span><span style="color:#79B8FF"> --group</span><span style="color:#9ECBFF"> dev</span><span style="color:#9ECBFF"> pytest</span><span style="color:#9ECBFF"> tests/test_generic_iso.py</span></span>
+<span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --directory</span><span style="color:#9ECBFF"> tools/agent-guard</span><span style="color:#79B8FF"> --group</span><span style="color:#9ECBFF"> dev</span><span style="color:#9ECBFF"> pytest</span></span>
+<span class="line"><span style="color:#B392F0">bash</span><span style="color:#9ECBFF"> tools/spec-loop/tests/test_runner_fixtures.sh</span></span></code></pre>
+<p>The sandbox-lint suite checks profile regressions without Gemini or Node.
+The optional <a href="https://github.com/apache/magpie/blob/main/tools/sandbox-lint/tests/integration/README.md">runtime integration tests</a> additionally exercise Gemini’s own policy engine and Linux sandbox using synthetic files, without a model or authentication.
+Use them when changing policy semantics or validating a runtime upgrade; normal CI runs the static checks only.
+Complete the shared <a href="/docs/adapters/add-a-harness#step-5--validate-the-full-wiring">harness validation</a> before submitting adapter changes.</p>
+<h2 id="upstream-references">Upstream references</h2>
+<ul>
+<li><a href="https://geminicli.com/docs/cli/using-agent-skills/">Gemini skills</a></li>
+<li><a href="https://geminicli.com/docs/reference/configuration/">Gemini configuration</a></li>
+<li><a href="https://geminicli.com/docs/get-started/authentication/">Gemini authentication</a></li>
+<li><a href="https://geminicli.com/docs/cli/sandbox/#tool-sandboxing">Gemini tool sandboxing and sandbox expansion</a></li>
+<li><a href="https://geminicli.com/docs/reference/policy-engine/">Gemini policy engine</a></li>
+<li><a href="https://github.com/google-gemini/gemini-cli">Gemini CLI source</a></li>
+</ul>
+</article></main><aside class="hidden xl:block w-60 flex-none border-l border-solid border-neutral-200 bg-default-background sticky top-0 h-screen overflow-y-auto px-5 py-12"><div class="mb-3 text-caption font-caption uppercase tracking-wider text-subtext-color">On this page</div><nav><ul class="flex flex-col gap-1.5"><li><a href="#harness-contract" class="block text-caption font-caption text-subtext-color hover:text-brand-700" style="padding-left: 0rem">Harness contract</a></li><li><a h [...]
+ (() => {
+ const nav = document.getElementById("docs-nav-scroll");
+ if (!nav) return;
+ for (const link of nav.querySelectorAll("summary a[href]")) {
+ link.addEventListener("click", (event) => {
+ const branch = link.closest("details");
+ if (!branch) return;
+ const plainClick =
+ event.button === 0 &&
+ !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
+ if (plainClick) {
+ event.preventDefault();
+ branch.open = true;
+ window.location.href = link.href;
+ } else {
+ setTimeout(() => { branch.open = true; }, 0);
+ }
+ });
+ }
+ })();
+ </script><script>
+ (() => {
+ const scroller = document.getElementById("docs-nav-scroll");
+ const active = scroller?.querySelector('[aria-current="page"]');
+ if (!scroller || !active) return;
+ const target =
+ active.offsetTop - scroller.clientHeight / 2 + active.offsetHeight / 2;
+ scroller.scrollTop = Math.max(0, target);
+ })();
+ </script><a href="https://github.com/apache/magpie/edit/main/docs/adapters/gemini.md" target="_blank" rel="noopener noreferrer" class="suggest-change" aria-label="Suggest a change to this page on GitHub" data-astro-cid-z4jru4n3><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" data-astro-cid-z4jru4n3><path d="M12 20h9" data-astro-cid-z4jru4n3></path><path d="M16.5 3.5a2.12 [...]
\ No newline at end of file
diff --git a/docs/adapters/kiro.md b/docs/adapters/kiro.md
new file mode 100644
index 0000000..6268f71
--- /dev/null
+++ b/docs/adapters/kiro.md
@@ -0,0 +1,103 @@
+# Kiro CLI harness
+
+Rendered page: https://magpie.apache.org/docs/adapters/kiro/
+
+Source: https://github.com/apache/magpie/blob/main/docs/adapters/kiro.md
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+**Capability:** capability:platform
+
+**Harness:** Kiro CLI
+
+Kiro uses Magpie's skill sources, deterministic action guard, spec-loop runner,
+and clean-environment wrapper. As everywhere else, nothing about a Magpie skill
+or a guard rule is Kiro-aware: the same files serve it through a different
+registration mechanism.
+
+Kiro is the one supported harness with **no marketplace**. It installs skills
+per-skill from a GitHub subdirectory rather than consuming a repository root,
+which changes how Magpie arrives and nothing about how it behaves once there.
+
+## Harness contract
+
+| Magpie requirement | Kiro implementation |
+|---|---|
+| Skill discovery | Native, from `.kiro/skills/`, which the `kiro` row in [`agents.md`](https://github.com/apache/magpie/blob/main/skills/setup/agents.md) writes as a relay into the canonical `.agents/skills/` tree. Kiro also installs a skill directly from a GitHub subdirectory on a pinned tag. |
+| Deterministic guard | The `preToolUse` hook. Kiro pipes the event to the hook command and **blocks** the call when it exits `2`, returning stderr to the model — the Kiro equivalent of a Claude Code `PreToolUse` deny. |
+| Spec-loop | The `kiro` profile passes the prompt positionally to `kiro-cli chat`, with `--no-interactive`. |
+| Credential isolation | `kiro-iso` launches the CLI through the clean-environment wrapper. |
+
+## Installing skills
+
+There is no marketplace to add. Point Kiro's *install from GitHub* at the
+subdirectory of the skill you want, on a pinned tag:
+
+```text
+https://github.com/apache/magpie/tree/0.2.0/skills/release-vote-tally
+```
+
+Kiro reads the `skills/<name>/SKILL.md` there. Pin a tag rather than tracking
+`main`: without a marketplace there is no update command to run later, so the
+version you install is the version you keep until you install again.
+
+That per-skill shape is why Kiro is absent from the family-plugin story. A
+family plugin is a bundle, and Kiro does not consume bundles — you take the
+skills you want, one at a time.
+
+## Deterministic guard rules
+
+`agent-guard.py --kiro` matches the shell tool, runs the shared `dispatch()`
+core, and on a deny writes the reason to stderr and exits `2`. Register it in
+the agent configuration's `hooks` field; the full recipe, including the event
+shape Kiro sends, is in the
+[agent-guard Kiro recipe](https://github.com/apache/magpie/blob/main/tools/agent-guard/README.md#kiro-cli).
+
+Because Kiro calls the same core as every other harness, the bundled and
+skill-contributed guards, the `MAGPIE_*` overrides, and the deny reasons are
+byte-for-byte identical to Claude Code's.
+
+## Spec-loop runner
+
+```bash
+SPEC_LOOP_AGENT=kiro tools/spec-loop/loop.sh <spec>
+```
+
+Two Kiro-specific details the runner handles: the model is selected through the
+agent configuration under `.kiro/agents` rather than a `--model` flag, and the
+output is plain text only — there is no structured mode to ask for. Its
+reasoning-effort scale runs to `xhigh` and `max`; the runner maps the neutral
+`low`/`medium`/`high` band onto `--effort`.
+
+## Clean-environment wrapper
+
+```bash
+source /path/to/magpie/tools/agent-isolation/agent-iso.sh
+kiro-iso
+```
+
+The `kiro` name normalises to the `kiro-cli` binary. Like OpenCode and unlike
+Claude Code, it takes no `--settings` filesystem grant: Kiro gets its
+filesystem isolation from the OS-level sandbox.
+
+## Verify
+
+```bash
+uv run --directory tools/agent-guard --project . python -m pytest
+bash tools/spec-loop/tests/test_runner_fixtures.sh
+```
+
+The guard tests cover the Kiro path end-to-end — the `--kiro` event parsing,
+the exit-`2`-plus-stderr deny protocol, and that a decision from the shared
+core survives unchanged. The runner fixtures verify the positional prompt and
+the `--no-interactive` flag.
+
+To verify in a live session, ask Kiro to run `git status --short`; it should
+pass the guard. For a harmless denial probe, ask it to run
+`git commit --dry-run --no-verify -m hook-probe` — the expected result is an
+`agent-guard[no-verify]` denial before Git starts. The `--dry-run` flag
+prevents the probe from creating a commit even if the hook is not registered.
diff --git a/docs/adapters/kiro/index.html b/docs/adapters/kiro/index.html
new file mode 100644
index 0000000..ab9a9f7
--- /dev/null
+++ b/docs/adapters/kiro/index.html
@@ -0,0 +1,135 @@
+<!DOCTYPE html><html lang="en" data-astro-cid-z4jru4n3><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="description" content="AI-powered assistant for open-source maintainers. Triage, mentor, draft, pair, and auto-merge under Apache Software Foundation governance."><link rel="icon" type="image/svg+xml" href="/favicon.svg"><link rel="icon" type="image/x-icon" sizes="any" href="/favicon.ico"><title>Kiro CLI harness — Apache Magpi [...]
+ var _paq = (window._paq = window._paq || []);
+ /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
+ _paq.push(["setDoNotTrack", true]);
+ _paq.push(["disableCookies"]);
+ _paq.push(["trackPageView"]);
+ _paq.push(["enableLinkTracking"]);
+ (function () {
+ var u = "https://analytics.apache.org/";
+ _paq.push(["setTrackerUrl", u + "matomo.php"]);
+ _paq.push(["setSiteId", "89"]);
+ var d = document,
+ g = d.createElement("script"),
+ s = d.getElementsByTagName("script")[0];
+ g.async = true;
+ g.src = u + "matomo.js";
+ s.parentNode.insertBefore(g, s);
+ })();
+ </script><link rel="stylesheet" href="/_astro/SiteFooter.C2Dgj2WR.css"><style>.tree-summary[data-astro-cid-lihgpoae]{list-style:none}.tree-summary[data-astro-cid-lihgpoae]::-webkit-details-marker{display:none}.tree-chevron[data-astro-cid-lihgpoae]{color:var(--color-subtext-color);transition:transform .15s}details[data-astro-cid-lihgpoae][open]>.tree-summary[data-astro-cid-lihgpoae] .tree-chevron[data-astro-cid-lihgpoae]{transform:rotate(90deg)}.prose h1{color:var(--color-default-font [...]
+</style></head><body data-astro-cid-z4jru4n3><nav class="relative z-10 flex w-full items-center justify-between bg-default-background px-8 py-5 mobile:px-4"><a href="/" aria-label="Apache Magpie home" class="flex items-end justify-end gap-2 px-2 py-2"><img class="h-10 w-10 flex-none object-cover" src="/subframe-mark.svg" alt="Apache Magpie"/><img class="h-10 flex-none object-contain" src="/subframe-wordmark.png" alt="Magpie"/><span class="self-center -mt-2 -ml-2 text-[10px] font-[700] le [...]
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<h1 id="kiro-cli-harness">Kiro CLI harness</h1>
+<p><strong>Capability:</strong> capability:platform</p>
+<p><strong>Harness:</strong> Kiro CLI</p>
+<p>Kiro uses Magpie’s skill sources, deterministic action guard, spec-loop runner,
+and clean-environment wrapper. As everywhere else, nothing about a Magpie skill
+or a guard rule is Kiro-aware: the same files serve it through a different
+registration mechanism.</p>
+<p>Kiro is the one supported harness with <strong>no marketplace</strong>. It installs skills
+per-skill from a GitHub subdirectory rather than consuming a repository root,
+which changes how Magpie arrives and nothing about how it behaves once there.</p>
+<h2 id="harness-contract">Harness contract</h2>
+<table>
+<thead>
+<tr>
+<th>Magpie requirement</th>
+<th>Kiro implementation</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Skill discovery</td>
+<td>Native, from <code>.kiro/skills/</code>, which the <code>kiro</code> row in <a href="https://github.com/apache/magpie/blob/main/skills/setup/agents.md"><code>agents.md</code></a> writes as a relay into the canonical <code>.agents/skills/</code> tree. Kiro also installs a skill directly from a GitHub subdirectory on a pinned tag.</td>
+</tr>
+<tr>
+<td>Deterministic guard</td>
+<td>The <code>preToolUse</code> hook. Kiro pipes the event to the hook command and <strong>blocks</strong> the call when it exits <code>2</code>, returning stderr to the model — the Kiro equivalent of a Claude Code <code>PreToolUse</code> deny.</td>
+</tr>
+<tr>
+<td>Spec-loop</td>
+<td>The <code>kiro</code> profile passes the prompt positionally to <code>kiro-cli chat</code>, with <code>--no-interactive</code>.</td>
+</tr>
+<tr>
+<td>Credential isolation</td>
+<td><code>kiro-iso</code> launches the CLI through the clean-environment wrapper.</td>
+</tr>
+</tbody>
+</table>
+<h2 id="installing-skills">Installing skills</h2>
+<p>There is no marketplace to add. Point Kiro’s <em>install from GitHub</em> at the
+subdirectory of the skill you want, on a pinned tag:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="text"><code><span class="line"><span>https://github.com/apache/magpie/tree/0.2.0/skills/release-vote-tally</span></span></code></pre>
+<p>Kiro reads the <code>skills/<name>/SKILL.md</code> there. Pin a tag rather than tracking
+<code>main</code>: without a marketplace there is no update command to run later, so the
+version you install is the version you keep until you install again.</p>
+<p>That per-skill shape is why Kiro is absent from the family-plugin story. A
+family plugin is a bundle, and Kiro does not consume bundles — you take the
+skills you want, one at a time.</p>
+<h2 id="deterministic-guard-rules">Deterministic guard rules</h2>
+<p><code>agent-guard.py --kiro</code> matches the shell tool, runs the shared <code>dispatch()</code>
+core, and on a deny writes the reason to stderr and exits <code>2</code>. Register it in
+the agent configuration’s <code>hooks</code> field; the full recipe, including the event
+shape Kiro sends, is in the
+<a href="https://github.com/apache/magpie/blob/main/tools/agent-guard/README.md#kiro-cli">agent-guard Kiro recipe</a>.</p>
+<p>Because Kiro calls the same core as every other harness, the bundled and
+skill-contributed guards, the <code>MAGPIE_*</code> overrides, and the deny reasons are
+byte-for-byte identical to Claude Code’s.</p>
+<h2 id="spec-loop-runner">Spec-loop runner</h2>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#E1E4E8">SPEC_LOOP_AGENT</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">kiro</span><span style="color:#B392F0"> tools/spec-loop/loop.sh</span><span style="color:#F97583"> <</span><span style="color:#9ECBFF">spe</span><span style="color:#E1E4E8">c</span><span style="color:#F97583">>< [...]
+<p>Two Kiro-specific details the runner handles: the model is selected through the
+agent configuration under <code>.kiro/agents</code> rather than a <code>--model</code> flag, and the
+output is plain text only — there is no structured mode to ask for. Its
+reasoning-effort scale runs to <code>xhigh</code> and <code>max</code>; the runner maps the neutral
+<code>low</code>/<code>medium</code>/<code>high</code> band onto <code>--effort</code>.</p>
+<h2 id="clean-environment-wrapper">Clean-environment wrapper</h2>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#79B8FF">source</span><span style="color:#9ECBFF"> /path/to/magpie/tools/agent-isolation/agent-iso.sh</span></span>
+<span class="line"><span style="color:#B392F0">kiro-iso</span></span></code></pre>
+<p>The <code>kiro</code> name normalises to the <code>kiro-cli</code> binary. Like OpenCode and unlike
+Claude Code, it takes no <code>--settings</code> filesystem grant: Kiro gets its
+filesystem isolation from the OS-level sandbox.</p>
+<h2 id="verify">Verify</h2>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --directory</span><span style="color:#9ECBFF"> tools/agent-guard</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> .</span><span style="color:#9ECBFF"> python</span><span style="color:#79B8FF"> -m [...]
+<span class="line"><span style="color:#B392F0">bash</span><span style="color:#9ECBFF"> tools/spec-loop/tests/test_runner_fixtures.sh</span></span></code></pre>
+<p>The guard tests cover the Kiro path end-to-end — the <code>--kiro</code> event parsing,
+the exit-<code>2</code>-plus-stderr deny protocol, and that a decision from the shared
+core survives unchanged. The runner fixtures verify the positional prompt and
+the <code>--no-interactive</code> flag.</p>
+<p>To verify in a live session, ask Kiro to run <code>git status --short</code>; it should
+pass the guard. For a harmless denial probe, ask it to run
+<code>git commit --dry-run --no-verify -m hook-probe</code> — the expected result is an
+<code>agent-guard[no-verify]</code> denial before Git starts. The <code>--dry-run</code> flag
+prevents the probe from creating a commit even if the hook is not registered.</p>
+</article></main><aside class="hidden xl:block w-60 flex-none border-l border-solid border-neutral-200 bg-default-background sticky top-0 h-screen overflow-y-auto px-5 py-12"><div class="mb-3 text-caption font-caption uppercase tracking-wider text-subtext-color">On this page</div><nav><ul class="flex flex-col gap-1.5"><li><a href="#harness-contract" class="block text-caption font-caption text-subtext-color hover:text-brand-700" style="padding-left: 0rem">Harness contract</a></li><li><a h [...]
+ (() => {
+ const nav = document.getElementById("docs-nav-scroll");
+ if (!nav) return;
+ for (const link of nav.querySelectorAll("summary a[href]")) {
+ link.addEventListener("click", (event) => {
+ const branch = link.closest("details");
+ if (!branch) return;
+ const plainClick =
+ event.button === 0 &&
+ !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
+ if (plainClick) {
+ event.preventDefault();
+ branch.open = true;
+ window.location.href = link.href;
+ } else {
+ setTimeout(() => { branch.open = true; }, 0);
+ }
+ });
+ }
+ })();
+ </script><script>
+ (() => {
+ const scroller = document.getElementById("docs-nav-scroll");
+ const active = scroller?.querySelector('[aria-current="page"]');
+ if (!scroller || !active) return;
+ const target =
+ active.offsetTop - scroller.clientHeight / 2 + active.offsetHeight / 2;
+ scroller.scrollTop = Math.max(0, target);
+ })();
+ </script><a href="https://github.com/apache/magpie/edit/main/docs/adapters/kiro.md" target="_blank" rel="noopener noreferrer" class="suggest-change" aria-label="Suggest a change to this page on GitHub" data-astro-cid-z4jru4n3><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" data-astro-cid-z4jru4n3><path d="M12 20h9" data-astro-cid-z4jru4n3></path><path d="M16.5 3.5a2.121 [...]
\ No newline at end of file
diff --git a/docs/adapters/local-llm.md b/docs/adapters/local-llm.md
new file mode 100644
index 0000000..a5c2be3
--- /dev/null
+++ b/docs/adapters/local-llm.md
@@ -0,0 +1,247 @@
+# Local LLM runtime (Ollama, llama.cpp, vLLM)
+
+Rendered page: https://magpie.apache.org/docs/adapters/local-llm/
+
+Source: https://github.com/apache/magpie/blob/main/docs/adapters/local-llm.md
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+**Capability:** capability:platform
+
+**Harness:** Local LLM (Ollama / llama.cpp / vLLM)
+
+This guide documents how Apache Magpie operates against **local and on-premise open-weight LLMs** for [#315](https://github.com/apache/magpie/issues/315).
+Grounding is established by [RFC-AI-0004 Principle 3 (Vendor Neutrality)](/docs/rfcs/rfc-ai-0004), which explicitly commits the framework to open-weight models, self-hosted endpoints, and zero cloud-only skill requirements.
+
+Local LLM runtimes serve three primary operational requirements:
+1. **Sovereign deployments:** Projects and foundations bound by strict data-residency laws (such as EU GDPR, public sector, or defense-orbit OSS) that cannot transmit vulnerability or tracker content to external cloud APIs.
+2. **Air-gapped triage:** Security teams operating within isolated networks that triage `<security-list>` traffic with zero external internet connectivity.
+3. **Predictable cost ceilings:** Deployments running open-weight foundation models on shared local or cluster hardware without variable per-token cloud billing.
+
+## Harness contract
+
+| Magpie requirement | Local LLM implementation |
+|---|---|
+| Skill discovery | Agent frontends read the canonical `.agents/skills/magpie-*/SKILL.md` symlinks or `.claude/skills/` links directly without modification. |
+| Model inference | Local engines expose standard OpenAI-compatible REST endpoints (`/v1/chat/completions` and `/v1/models`) over localhost or private network sockets. |
+| Agent frontend | Model-agnostic harnesses (such as OpenCode or Aider) drive workflows by connecting to local inference endpoints. |
+| Repository instructions | The agent ingests repository guidance from `AGENTS.md` and adopter instructions from `<project-config>/`. |
+| Human-in-the-loop (HITL) | The agent frontend enforces strict proposal-then-confirm discipline before executing shell commands, file edits, or dispatch actions. |
+| Tool bridges | Deterministic tool scripts under `tools/` execute as language-agnostic local CLI commands without sending tool code to the model. |
+| Credential & network isolation | `agent-iso` strips ambient cloud credentials and network sockets, ensuring zero inadvertent outbound telemetry. |
+
+## Serving engines and endpoints
+
+Magpie works with any local inference server exposing an OpenAI-compatible HTTP API.
+The primary supported serving backends are detailed below.
+
+### Ollama
+
+[Ollama](https://ollama.com) provides local model management and serving with built-in OpenAI API compatibility.
+
+Start the Ollama daemon:
+
+```bash
+ollama serve
+```
+
+Pull the recommended model weights:
+
+```bash
+# Recommended 70B reasoning model for multi-step triage
+ollama pull llama3.3:70b
+
+# Alternative high-capability models
+ollama pull qwen2.5:72b
+ollama pull deepseek-r1:70b
+
+# Lightweight model for mechanical and bounded tasks
+ollama pull qwen2.5:14b
+```
+
+Ollama serves the OpenAI-compatible API at `http://localhost:11434/v1`.
+
+### llama.cpp server
+
+[`llama.cpp`](https://github.com/ggml-org/llama.cpp) provides lightweight, highly optimized C/C++ inference with GGUF quantization.
+
+Launch the server with an extended context window:
+
+```bash
+llama-server \
+ --model /path/to/models/Llama-3.3-70B-Instruct-Q4_K_M.gguf \
+ --ctx-size 32768 \
+ --port 8080 \
+ --host 127.0.0.1
+```
+
+The server endpoint is available at `http://127.0.0.1:8080/v1`.
+
+### vLLM
+
+[vLLM](https://github.com/vllm-project/vllm) delivers high-throughput inference for multi-GPU workstations and dedicated on-premise clusters.
+
+Start the vLLM OpenAI-compatible server:
+
+```bash
+vllm serve meta-llama/Llama-3.3-70B-Instruct \
+ --port 8000 \
+ --max-model-len 32768 \
+ --tensor-parallel-size 2
+```
+
+The server endpoint is available at `http://localhost:8000/v1`.
+
+### Desktop runners (LM Studio, Jan)
+
+GUI-based local runners also provide local OpenAI-compatible endpoints:
+- **LM Studio:** Start the local server under the Developer tab (default: `http://localhost:1234/v1`).
+- **Jan:** Enable the local API server in Settings (default: `http://localhost:1337/v1`).
+
+## Driving skills via agent frontends
+
+Local models operate through model-agnostic agent frontends that handle skill discovery, tool execution, and the human interaction loop.
+
+### OpenCode (reference harness)
+
+[OpenCode](https://opencode.ai/) is the framework reference implementation and natively connects to any OpenAI-compatible local endpoint.
+
+Configure OpenCode to use the local server in your project configuration or environment:
+
+```bash
+export OPENAI_BASE_URL="http://localhost:11434/v1"
+export OPENAI_API_KEY="local-no-key-required"
+
+# Launch OpenCode pointing to the local model
+opencode --model llama3.3:70b
+```
+
+Inside OpenCode, discover and run Magpie skills directly:
+
+```text
+/skills list
+Use the magpie-list-skills skill.
+```
+
+### Aider CLI
+
+[Aider](https://github.com/paul-gauthier/aider) drives git-centric workflows against local endpoints:
+
+```bash
+# Connect Aider to Ollama
+aider --openai-api-base http://localhost:11434/v1 \
+ --model openai/llama3.3:70b \
+ --no-git
+```
+
+### Goose (Block)
+
+[Goose](https://github.com/block/goose) connects to local OpenAI-compatible endpoints:
+
+```bash
+# Configure Goose with the local endpoint
+export OPENAI_BASE_URL="http://localhost:11434/v1"
+export OPENAI_API_KEY="local-key"
+goose run --model llama3.3:70b
+```
+
+### Continue.dev
+
+[Continue](https://continue.dev/) discovers skills and drives local models inside VS Code and JetBrains IDEs via `~/.continue/config.json`:
+
+```json
+{
+ "models": [
+ {
+ "title": "Local Llama 3.3 70B",
+ "provider": "openai",
+ "model": "llama3.3:70b",
+ "apiBase": "http://localhost:11434/v1"
+ }
+ ]
+}
+```
+
+## Model capability floors and calibration
+
+Skills vary in their cognitive demands.
+Based on calibration against the framework evaluation suite under [`tools/skill-evals/`](https://github.com/apache/magpie/tree/main/tools/skill-evals/), local deployments must respect model size floors to ensure reliable execution.
+
+### Floor 1: 70B+ reasoning class
+
+Multi-step security workflows require strong logical reasoning, instruction adherence across long contexts, and nuanced threat modeling.
+
+**Recommended models:**
+- `Llama-3.3-70B-Instruct`
+- `Qwen2.5-72B-Instruct`
+- `DeepSeek-R1-Distill-Llama-70B`
+
+**Target skills requiring Floor 1:**
+- `magpie-security-issue-triage` (inbound mail triage, attack vector identification, CVSS estimation)
+- `magpie-pr-management-code-review` (security regression analysis, diff inspection)
+- `magpie-cve-allocation-draft` (vulnerability narrative formulation, advisory drafting)
+- `magpie-mentor-contributor` (multi-turn developer guidance and contextual code review)
+
+### Floor 2: 8B–14B bounded class
+
+Deterministic, mechanical, or single-turn tasks operate reliably on smaller, quantized models running on resource-constrained hardware.
+
+**Recommended models:**
+- `Qwen2.5-14B-Instruct`
+- `Llama-3.1-8B-Instruct`
+- `Mistral-Small-24B-Instruct`
+
+**Target skills suitable for Floor 2:**
+- `magpie-git-commit` (structured commit message generation with trailers)
+- `magpie-review-doc` (formatting, spelling, and link consistency checks)
+- `magpie-list-skills` (catalog presentation and inventorying)
+- `magpie-scope-validation` (label taxonomy and milestone alignment)
+
+## Sovereign and air-gapped operations
+
+For deployments requiring absolute privacy or air-gapped isolation:
+
+1. **Verify offline operation:** Ensure the inference server runs with telemetry disabled (`OLLAMA_NO_TELEMETRY=1`, `VLLM_NO_USAGE_STATS=1`).
+2. **Model weight integrity:** Verify SHA-256 checksums of model weights prior to deployment in air-gapped enclaves.
+3. **Zero cloud egress:** All parsing, triage analysis, and tool execution remain strictly local to the machine or local enclave.
+
+## Clean-environment wrapper and isolation
+
+To ensure local LLM execution does not inadvertently access ambient environment secrets:
+
+```bash
+source <framework>/tools/agent-isolation/agent-iso.sh
+agent-iso opencode --model llama3.3:70b
+```
+
+The `agent-iso` launcher strips unapproved environment variables and enforces isolated execution baselines.
+
+## Verify
+
+Verify that the local LLM runtime setup satisfies framework constraints:
+
+```bash
+# 1. Verify skill discovery topology
+$env:PYTHONUTF8=1; uv run --project tools/symlink-lint symlink-lint
+
+# 2. Validate skill and tool metadata
+$env:PYTHONUTF8=1; uv run --project tools/skill-and-tool-validator skill-and-tool-validate
+
+# 3. Check vendor neutrality score
+$env:PYTHONUTF8=1; uv run --project tools/vendor-neutrality-score vendor-neutrality-score
+
+# 4. Check documentation table of contents and formatting
+uv run prek run doctoc --all-files
+```
+
+## See also
+
+- [`docs/rfcs/RFC-AI-0004.md`](/docs/rfcs/rfc-ai-0004) — normative principles for vendor neutrality and open-weight models.
+- [`docs/vendor-neutrality.md`](/docs/vendor-neutrality) — framework vendor neutrality index across LLM backends.
+- [`docs/adapters/add-a-harness.md`](/docs/adapters/add-a-harness) — step-by-step guide for integrating runtime harnesses.
+- [`tools/agent-isolation/README.md`](https://github.com/apache/magpie/blob/main/tools/agent-isolation/README.md) — clean-environment launcher.
+- [`tools/skill-evals/`](https://github.com/apache/magpie/tree/main/tools/skill-evals/) — empirical evaluation suite for model capability calibration.
diff --git a/docs/adapters/local-llm/index.html b/docs/adapters/local-llm/index.html
new file mode 100644
index 0000000..1871c3f
--- /dev/null
+++ b/docs/adapters/local-llm/index.html
@@ -0,0 +1,248 @@
+<!DOCTYPE html><html lang="en" data-astro-cid-z4jru4n3><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="description" content="AI-powered assistant for open-source maintainers. Triage, mentor, draft, pair, and auto-merge under Apache Software Foundation governance."><link rel="icon" type="image/svg+xml" href="/favicon.svg"><link rel="icon" type="image/x-icon" sizes="any" href="/favicon.ico"><title>Local LLM runtime (Ollama, llam [...]
+ var _paq = (window._paq = window._paq || []);
+ /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
+ _paq.push(["setDoNotTrack", true]);
+ _paq.push(["disableCookies"]);
+ _paq.push(["trackPageView"]);
+ _paq.push(["enableLinkTracking"]);
+ (function () {
+ var u = "https://analytics.apache.org/";
+ _paq.push(["setTrackerUrl", u + "matomo.php"]);
+ _paq.push(["setSiteId", "89"]);
+ var d = document,
+ g = d.createElement("script"),
+ s = d.getElementsByTagName("script")[0];
+ g.async = true;
+ g.src = u + "matomo.js";
+ s.parentNode.insertBefore(g, s);
+ })();
+ </script><link rel="stylesheet" href="/_astro/SiteFooter.C2Dgj2WR.css"><style>.tree-summary[data-astro-cid-lihgpoae]{list-style:none}.tree-summary[data-astro-cid-lihgpoae]::-webkit-details-marker{display:none}.tree-chevron[data-astro-cid-lihgpoae]{color:var(--color-subtext-color);transition:transform .15s}details[data-astro-cid-lihgpoae][open]>.tree-summary[data-astro-cid-lihgpoae] .tree-chevron[data-astro-cid-lihgpoae]{transform:rotate(90deg)}.prose h1{color:var(--color-default-font [...]
+</style></head><body data-astro-cid-z4jru4n3><nav class="relative z-10 flex w-full items-center justify-between bg-default-background px-8 py-5 mobile:px-4"><a href="/" aria-label="Apache Magpie home" class="flex items-end justify-end gap-2 px-2 py-2"><img class="h-10 w-10 flex-none object-cover" src="/subframe-mark.svg" alt="Apache Magpie"/><img class="h-10 flex-none object-contain" src="/subframe-wordmark.png" alt="Magpie"/><span class="self-center -mt-2 -ml-2 text-[10px] font-[700] le [...]
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<h1 id="local-llm-runtime-ollama-llamacpp-vllm">Local LLM runtime (Ollama, llama.cpp, vLLM)</h1>
+<p><strong>Capability:</strong> capability:platform</p>
+<p><strong>Harness:</strong> Local LLM (Ollama / llama.cpp / vLLM)</p>
+<p>This guide documents how Apache Magpie operates against <strong>local and on-premise open-weight LLMs</strong> for <a href="https://github.com/apache/magpie/issues/315">#315</a>.
+Grounding is established by <a href="/docs/rfcs/rfc-ai-0004">RFC-AI-0004 Principle 3 (Vendor Neutrality)</a>, which explicitly commits the framework to open-weight models, self-hosted endpoints, and zero cloud-only skill requirements.</p>
+<p>Local LLM runtimes serve three primary operational requirements:</p>
+<ol>
+<li><strong>Sovereign deployments:</strong> Projects and foundations bound by strict data-residency laws (such as EU GDPR, public sector, or defense-orbit OSS) that cannot transmit vulnerability or tracker content to external cloud APIs.</li>
+<li><strong>Air-gapped triage:</strong> Security teams operating within isolated networks that triage <code><security-list></code> traffic with zero external internet connectivity.</li>
+<li><strong>Predictable cost ceilings:</strong> Deployments running open-weight foundation models on shared local or cluster hardware without variable per-token cloud billing.</li>
+</ol>
+<h2 id="harness-contract">Harness contract</h2>
+<table>
+<thead>
+<tr>
+<th>Magpie requirement</th>
+<th>Local LLM implementation</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Skill discovery</td>
+<td>Agent frontends read the canonical <code>.agents/skills/magpie-*/SKILL.md</code> symlinks or <code>.claude/skills/</code> links directly without modification.</td>
+</tr>
+<tr>
+<td>Model inference</td>
+<td>Local engines expose standard OpenAI-compatible REST endpoints (<code>/v1/chat/completions</code> and <code>/v1/models</code>) over localhost or private network sockets.</td>
+</tr>
+<tr>
+<td>Agent frontend</td>
+<td>Model-agnostic harnesses (such as OpenCode or Aider) drive workflows by connecting to local inference endpoints.</td>
+</tr>
+<tr>
+<td>Repository instructions</td>
+<td>The agent ingests repository guidance from <code>AGENTS.md</code> and adopter instructions from <code><project-config>/</code>.</td>
+</tr>
+<tr>
+<td>Human-in-the-loop (HITL)</td>
+<td>The agent frontend enforces strict proposal-then-confirm discipline before executing shell commands, file edits, or dispatch actions.</td>
+</tr>
+<tr>
+<td>Tool bridges</td>
+<td>Deterministic tool scripts under <code>tools/</code> execute as language-agnostic local CLI commands without sending tool code to the model.</td>
+</tr>
+<tr>
+<td>Credential & network isolation</td>
+<td><code>agent-iso</code> strips ambient cloud credentials and network sockets, ensuring zero inadvertent outbound telemetry.</td>
+</tr>
+</tbody>
+</table>
+<h2 id="serving-engines-and-endpoints">Serving engines and endpoints</h2>
+<p>Magpie works with any local inference server exposing an OpenAI-compatible HTTP API.
+The primary supported serving backends are detailed below.</p>
+<h3 id="ollama">Ollama</h3>
+<p><a href="https://ollama.com">Ollama</a> provides local model management and serving with built-in OpenAI API compatibility.</p>
+<p>Start the Ollama daemon:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#B392F0">ollama</span><span style="color:#9ECBFF"> serve</span></span></code></pre>
+<p>Pull the recommended model weights:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#6A737D"># Recommended 70B reasoning model for multi-step triage</span></span>
+<span class="line"><span style="color:#B392F0">ollama</span><span style="color:#9ECBFF"> pull</span><span style="color:#9ECBFF"> llama3.3:70b</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#6A737D"># Alternative high-capability models</span></span>
+<span class="line"><span style="color:#B392F0">ollama</span><span style="color:#9ECBFF"> pull</span><span style="color:#9ECBFF"> qwen2.5:72b</span></span>
+<span class="line"><span style="color:#B392F0">ollama</span><span style="color:#9ECBFF"> pull</span><span style="color:#9ECBFF"> deepseek-r1:70b</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#6A737D"># Lightweight model for mechanical and bounded tasks</span></span>
+<span class="line"><span style="color:#B392F0">ollama</span><span style="color:#9ECBFF"> pull</span><span style="color:#9ECBFF"> qwen2.5:14b</span></span></code></pre>
+<p>Ollama serves the OpenAI-compatible API at <code>http://localhost:11434/v1</code>.</p>
+<h3 id="llamacpp-server">llama.cpp server</h3>
+<p><a href="https://github.com/ggml-org/llama.cpp"><code>llama.cpp</code></a> provides lightweight, highly optimized C/C++ inference with GGUF quantization.</p>
+<p>Launch the server with an extended context window:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#B392F0">llama-server</span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#79B8FF"> --model</span><span style="color:#9ECBFF"> /path/to/models/Llama-3.3-70B-Instruct-Q4_K_M.gguf</span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#79B8FF"> --ctx-size</span><span style="color:#79B8FF"> 32768</span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#79B8FF"> --port</span><span style="color:#79B8FF"> 8080</span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#79B8FF"> --host</span><span style="color:#79B8FF"> 127.0.0.1</span></span></code></pre>
+<p>The server endpoint is available at <code>http://127.0.0.1:8080/v1</code>.</p>
+<h3 id="vllm">vLLM</h3>
+<p><a href="https://github.com/vllm-project/vllm">vLLM</a> delivers high-throughput inference for multi-GPU workstations and dedicated on-premise clusters.</p>
+<p>Start the vLLM OpenAI-compatible server:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#B392F0">vllm</span><span style="color:#9ECBFF"> serve</span><span style="color:#9ECBFF"> meta-llama/Llama-3.3-70B-Instruct</span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#79B8FF"> --port</span><span style="color:#79B8FF"> 8000</span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#79B8FF"> --max-model-len</span><span style="color:#79B8FF"> 32768</span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#79B8FF"> --tensor-parallel-size</span><span style="color:#79B8FF"> 2</span></span></code></pre>
+<p>The server endpoint is available at <code>http://localhost:8000/v1</code>.</p>
+<h3 id="desktop-runners-lm-studio-jan">Desktop runners (LM Studio, Jan)</h3>
+<p>GUI-based local runners also provide local OpenAI-compatible endpoints:</p>
+<ul>
+<li><strong>LM Studio:</strong> Start the local server under the Developer tab (default: <code>http://localhost:1234/v1</code>).</li>
+<li><strong>Jan:</strong> Enable the local API server in Settings (default: <code>http://localhost:1337/v1</code>).</li>
+</ul>
+<h2 id="driving-skills-via-agent-frontends">Driving skills via agent frontends</h2>
+<p>Local models operate through model-agnostic agent frontends that handle skill discovery, tool execution, and the human interaction loop.</p>
+<h3 id="opencode-reference-harness">OpenCode (reference harness)</h3>
+<p><a href="https://opencode.ai/">OpenCode</a> is the framework reference implementation and natively connects to any OpenAI-compatible local endpoint.</p>
+<p>Configure OpenCode to use the local server in your project configuration or environment:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#F97583">export</span><span style="color:#E1E4E8"> OPENAI_BASE_URL</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">"http://localhost:11434/v1"</span></span>
+<span class="line"><span style="color:#F97583">export</span><span style="color:#E1E4E8"> OPENAI_API_KEY</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">"local-no-key-required"</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#6A737D"># Launch OpenCode pointing to the local model</span></span>
+<span class="line"><span style="color:#B392F0">opencode</span><span style="color:#79B8FF"> --model</span><span style="color:#9ECBFF"> llama3.3:70b</span></span></code></pre>
+<p>Inside OpenCode, discover and run Magpie skills directly:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="text"><code><span class="line"><span>/skills list</span></span>
+<span class="line"><span>Use the magpie-list-skills skill.</span></span></code></pre>
+<h3 id="aider-cli">Aider CLI</h3>
+<p><a href="https://github.com/paul-gauthier/aider">Aider</a> drives git-centric workflows against local endpoints:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#6A737D"># Connect Aider to Ollama</span></span>
+<span class="line"><span style="color:#B392F0">aider</span><span style="color:#79B8FF"> --openai-api-base</span><span style="color:#9ECBFF"> http://localhost:11434/v1</span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#79B8FF"> --model</span><span style="color:#9ECBFF"> openai/llama3.3:70b</span><span style="color:#79B8FF"> \</span></span>
+<span class="line"><span style="color:#79B8FF"> --no-git</span></span></code></pre>
+<h3 id="goose-block">Goose (Block)</h3>
+<p><a href="https://github.com/block/goose">Goose</a> connects to local OpenAI-compatible endpoints:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#6A737D"># Configure Goose with the local endpoint</span></span>
+<span class="line"><span style="color:#F97583">export</span><span style="color:#E1E4E8"> OPENAI_BASE_URL</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">"http://localhost:11434/v1"</span></span>
+<span class="line"><span style="color:#F97583">export</span><span style="color:#E1E4E8"> OPENAI_API_KEY</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">"local-key"</span></span>
+<span class="line"><span style="color:#B392F0">goose</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --model</span><span style="color:#9ECBFF"> llama3.3:70b</span></span></code></pre>
+<h3 id="continuedev">Continue.dev</h3>
+<p><a href="https://continue.dev/">Continue</a> discovers skills and drives local models inside VS Code and JetBrains IDEs via <code>~/.continue/config.json</code>:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="json"><code><span class="line"><span style="color:#E1E4E8">{</span></span>
+<span class="line"><span style="color:#79B8FF"> "models"</span><span style="color:#E1E4E8">: [</span></span>
+<span class="line"><span style="color:#E1E4E8"> {</span></span>
+<span class="line"><span style="color:#79B8FF"> "title"</span><span style="color:#E1E4E8">: </span><span style="color:#9ECBFF">"Local Llama 3.3 70B"</span><span style="color:#E1E4E8">,</span></span>
+<span class="line"><span style="color:#79B8FF"> "provider"</span><span style="color:#E1E4E8">: </span><span style="color:#9ECBFF">"openai"</span><span style="color:#E1E4E8">,</span></span>
+<span class="line"><span style="color:#79B8FF"> "model"</span><span style="color:#E1E4E8">: </span><span style="color:#9ECBFF">"llama3.3:70b"</span><span style="color:#E1E4E8">,</span></span>
+<span class="line"><span style="color:#79B8FF"> "apiBase"</span><span style="color:#E1E4E8">: </span><span style="color:#9ECBFF">"http://localhost:11434/v1"</span></span>
+<span class="line"><span style="color:#E1E4E8"> }</span></span>
+<span class="line"><span style="color:#E1E4E8"> ]</span></span>
+<span class="line"><span style="color:#E1E4E8">}</span></span></code></pre>
+<h2 id="model-capability-floors-and-calibration">Model capability floors and calibration</h2>
+<p>Skills vary in their cognitive demands.
+Based on calibration against the framework evaluation suite under <a href="https://github.com/apache/magpie/tree/main/tools/skill-evals/"><code>tools/skill-evals/</code></a>, local deployments must respect model size floors to ensure reliable execution.</p>
+<h3 id="floor-1-70b-reasoning-class">Floor 1: 70B+ reasoning class</h3>
+<p>Multi-step security workflows require strong logical reasoning, instruction adherence across long contexts, and nuanced threat modeling.</p>
+<p><strong>Recommended models:</strong></p>
+<ul>
+<li><code>Llama-3.3-70B-Instruct</code></li>
+<li><code>Qwen2.5-72B-Instruct</code></li>
+<li><code>DeepSeek-R1-Distill-Llama-70B</code></li>
+</ul>
+<p><strong>Target skills requiring Floor 1:</strong></p>
+<ul>
+<li><code>magpie-security-issue-triage</code> (inbound mail triage, attack vector identification, CVSS estimation)</li>
+<li><code>magpie-pr-management-code-review</code> (security regression analysis, diff inspection)</li>
+<li><code>magpie-cve-allocation-draft</code> (vulnerability narrative formulation, advisory drafting)</li>
+<li><code>magpie-mentor-contributor</code> (multi-turn developer guidance and contextual code review)</li>
+</ul>
+<h3 id="floor-2-8b14b-bounded-class">Floor 2: 8B–14B bounded class</h3>
+<p>Deterministic, mechanical, or single-turn tasks operate reliably on smaller, quantized models running on resource-constrained hardware.</p>
+<p><strong>Recommended models:</strong></p>
+<ul>
+<li><code>Qwen2.5-14B-Instruct</code></li>
+<li><code>Llama-3.1-8B-Instruct</code></li>
+<li><code>Mistral-Small-24B-Instruct</code></li>
+</ul>
+<p><strong>Target skills suitable for Floor 2:</strong></p>
+<ul>
+<li><code>magpie-git-commit</code> (structured commit message generation with trailers)</li>
+<li><code>magpie-review-doc</code> (formatting, spelling, and link consistency checks)</li>
+<li><code>magpie-list-skills</code> (catalog presentation and inventorying)</li>
+<li><code>magpie-scope-validation</code> (label taxonomy and milestone alignment)</li>
+</ul>
+<h2 id="sovereign-and-air-gapped-operations">Sovereign and air-gapped operations</h2>
+<p>For deployments requiring absolute privacy or air-gapped isolation:</p>
+<ol>
+<li><strong>Verify offline operation:</strong> Ensure the inference server runs with telemetry disabled (<code>OLLAMA_NO_TELEMETRY=1</code>, <code>VLLM_NO_USAGE_STATS=1</code>).</li>
+<li><strong>Model weight integrity:</strong> Verify SHA-256 checksums of model weights prior to deployment in air-gapped enclaves.</li>
+<li><strong>Zero cloud egress:</strong> All parsing, triage analysis, and tool execution remain strictly local to the machine or local enclave.</li>
+</ol>
+<h2 id="clean-environment-wrapper-and-isolation">Clean-environment wrapper and isolation</h2>
+<p>To ensure local LLM execution does not inadvertently access ambient environment secrets:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#79B8FF">source</span><span style="color:#F97583"> <</span><span style="color:#9ECBFF">framewor</span><span style="color:#E1E4E8">k</span><span style="color:#F97583">></span><span style="color:#9ECBFF">/tools/agent-isolation/agent-iso.sh</span></span>
+<span class="line"><span style="color:#B392F0">agent-iso</span><span style="color:#9ECBFF"> opencode</span><span style="color:#79B8FF"> --model</span><span style="color:#9ECBFF"> llama3.3:70b</span></span></code></pre>
+<p>The <code>agent-iso</code> launcher strips unapproved environment variables and enforces isolated execution baselines.</p>
+<h2 id="verify">Verify</h2>
+<p>Verify that the local LLM runtime setup satisfies framework constraints:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#6A737D"># 1. Verify skill discovery topology</span></span>
+<span class="line"><span style="color:#E1E4E8">$env:PYTHONUTF8</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">1</span><span style="color:#E1E4E8">; </span><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> tools/symlink-lint</span><span style="color:#9ECBFF"> symlink-lint</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#6A737D"># 2. Validate skill and tool metadata</span></span>
+<span class="line"><span style="color:#E1E4E8">$env:PYTHONUTF8</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">1</span><span style="color:#E1E4E8">; </span><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> tools/skill-and-tool-validator</span><span style="color:#9ECBFF"> skill-and-tool-validate</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#6A737D"># 3. Check vendor neutrality score</span></span>
+<span class="line"><span style="color:#E1E4E8">$env:PYTHONUTF8</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">1</span><span style="color:#E1E4E8">; </span><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> tools/vendor-neutrality-score</span><span style="color:#9ECBFF"> vendor-neutrality-score</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#6A737D"># 4. Check documentation table of contents and formatting</span></span>
+<span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#9ECBFF"> prek</span><span style="color:#9ECBFF"> run</span><span style="color:#9ECBFF"> doctoc</span><span style="color:#79B8FF"> --all-files</span></span></code></pre>
+<h2 id="see-also">See also</h2>
+<ul>
+<li><a href="/docs/rfcs/rfc-ai-0004"><code>docs/rfcs/RFC-AI-0004.md</code></a> — normative principles for vendor neutrality and open-weight models.</li>
+<li><a href="/docs/vendor-neutrality"><code>docs/vendor-neutrality.md</code></a> — framework vendor neutrality index across LLM backends.</li>
+<li><a href="/docs/adapters/add-a-harness"><code>docs/adapters/add-a-harness.md</code></a> — step-by-step guide for integrating runtime harnesses.</li>
+<li><a href="https://github.com/apache/magpie/blob/main/tools/agent-isolation/README.md"><code>tools/agent-isolation/README.md</code></a> — clean-environment launcher.</li>
+<li><a href="https://github.com/apache/magpie/tree/main/tools/skill-evals/"><code>tools/skill-evals/</code></a> — empirical evaluation suite for model capability calibration.</li>
+</ul>
+</article></main><aside class="hidden xl:block w-60 flex-none border-l border-solid border-neutral-200 bg-default-background sticky top-0 h-screen overflow-y-auto px-5 py-12"><div class="mb-3 text-caption font-caption uppercase tracking-wider text-subtext-color">On this page</div><nav><ul class="flex flex-col gap-1.5"><li><a href="#harness-contract" class="block text-caption font-caption text-subtext-color hover:text-brand-700" style="padding-left: 0rem">Harness contract</a></li><li><a h [...]
+ (() => {
+ const nav = document.getElementById("docs-nav-scroll");
+ if (!nav) return;
+ for (const link of nav.querySelectorAll("summary a[href]")) {
+ link.addEventListener("click", (event) => {
+ const branch = link.closest("details");
+ if (!branch) return;
+ const plainClick =
+ event.button === 0 &&
+ !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
+ if (plainClick) {
+ event.preventDefault();
+ branch.open = true;
+ window.location.href = link.href;
+ } else {
+ setTimeout(() => { branch.open = true; }, 0);
+ }
+ });
+ }
+ })();
+ </script><script>
+ (() => {
+ const scroller = document.getElementById("docs-nav-scroll");
+ const active = scroller?.querySelector('[aria-current="page"]');
+ if (!scroller || !active) return;
+ const target =
+ active.offsetTop - scroller.clientHeight / 2 + active.offsetHeight / 2;
+ scroller.scrollTop = Math.max(0, target);
+ })();
+ </script><a href="https://github.com/apache/magpie/edit/main/docs/adapters/local-llm.md" target="_blank" rel="noopener noreferrer" class="suggest-change" aria-label="Suggest a change to this page on GitHub" data-astro-cid-z4jru4n3><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" data-astro-cid-z4jru4n3><path d="M12 20h9" data-astro-cid-z4jru4n3></path><path d="M16.5 3.5a2 [...]
\ No newline at end of file
diff --git a/docs/adapters/opencode.md b/docs/adapters/opencode.md
new file mode 100644
index 0000000..243667b
--- /dev/null
+++ b/docs/adapters/opencode.md
@@ -0,0 +1,104 @@
+# OpenCode harness
+
+Rendered page: https://magpie.apache.org/docs/adapters/opencode/
+
+Source: https://github.com/apache/magpie/blob/main/docs/adapters/opencode.md
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+**Capability:** capability:platform
+
+**Harness:** OpenCode
+
+OpenCode uses Magpie's skill sources, deterministic action guard, spec-loop
+runner, and clean-environment wrapper. Nothing about a Magpie skill or a guard
+rule is harness-aware: the same files that serve Claude Code serve OpenCode,
+through a different registration mechanism.
+
+## Harness contract
+
+| Magpie requirement | OpenCode implementation |
+|---|---|
+| Skill discovery | OpenCode is part of the cluster that converged on `.agents/skills/`, which is the canonical target the `universal` row in [`agents.md`](https://github.com/apache/magpie/blob/main/skills/setup/agents.md) already writes. It also reads native Agent Skills from `.opencode/skills/` (project) or `~/.opencode/skills/` (personal). |
+| Deterministic guard | A [plugin](https://opencode.ai/docs/plugins/) on `tool.execute.before` forwards each `bash` command to `agent-guard.py --opencode` and throws the deny reason, which aborts the tool call. |
+| Spec-loop | The `opencode` profile passes the prompt positionally to `opencode run`, with `--auto`, `--model`, and `--format json`. |
+| Credential isolation | `opencode-iso` launches the CLI through the clean-environment wrapper. |
+
+## Deterministic guard rules
+
+OpenCode aborts a tool call whose `tool.execute.before` handler throws, which
+is the OpenCode equivalent of a Claude Code `PreToolUse` deny. The plugin in
+[`tools/agent-guard/opencode/plugin.js`](https://github.com/apache/magpie/blob/main/tools/agent-guard/opencode/plugin.js)
+forwards each `bash` command to the shared `dispatch()` core and throws with
+the reason the core returns.
+
+Register it by dropping the plugin into OpenCode's plugin directory:
+
+```bash
+mkdir -p .opencode/plugin
+ln -s "<framework>/tools/agent-guard/opencode/plugin.js" .opencode/plugin/agent-guard.js
+```
+
+The plugin locates the engine at `.claude/hooks/agent-guard.py` under the
+worktree by default, so a repository already wired for Claude Code needs no
+second copy of the script, and honours
+`MAGPIE_AGENT_GUARD=/abs/path/agent-guard.py` to point elsewhere.
+
+Because both harnesses call the same `dispatch()`, the bundled and
+skill-contributed guards, the `MAGPIE_*` overrides, and the deny reasons are
+byte-for-byte identical across the two. Full wiring notes are in the
+[agent-guard OpenCode recipe](https://github.com/apache/magpie/blob/main/tools/agent-guard/README.md#opencode).
+
+## Spec-loop runner
+
+The `opencode` profile in [`tools/spec-loop/lib.sh`](https://github.com/apache/magpie/blob/main/tools/spec-loop/lib.sh)
+runs `opencode run --auto --model … "<prompt>"` from the repository root and
+asks for stream JSON with `--format json`. Setting `SPEC_LOOP_AGENT=opencode`
+is normally the whole configuration:
+
+```bash
+SPEC_LOOP_AGENT=opencode SPEC_LOOP_MODEL=anthropic/claude-sonnet-4-5 \
+ tools/spec-loop/loop.sh <spec>
+```
+
+OpenCode is the one harness whose reasoning-effort band is not an identity
+mapping: the runner translates the neutral `low` / `medium` / `high` to
+`--variant minimal` / `medium` / `max`. See the
+[spec-loop guide](https://github.com/apache/magpie/blob/main/tools/spec-loop/README.md).
+
+## Clean-environment wrapper
+
+```bash
+source /path/to/magpie/tools/agent-isolation/agent-iso.sh
+opencode-iso
+```
+
+`opencode-iso` applies the same `env -i` credential strip as `claude-iso`, and
+adds no settings grant: OpenCode takes its filesystem isolation from the
+OS-level sandbox rather than from a per-launch allowlist. Network restrictions
+and tool approval are separate controls, described in the
+[secure-agent setup](/docs/setup/secure-agent-setup).
+
+## Verify
+
+```bash
+uv run --directory tools/agent-guard --project . python -m pytest
+bash tools/spec-loop/tests/test_runner_fixtures.sh
+```
+
+The guard tests cover the OpenCode path end-to-end — the plugin's command
+routing, the throw-on-deny contract, and that a decision made by the shared
+core is preserved unchanged. The runner fixtures verify the positional prompt,
+the `--auto` flag, and the effort-band translation, including the `low` →
+`minimal` mapping that is unique to this harness.
+
+To verify in a live session, start OpenCode from the checkout root and ask it
+to run `git status --short`; it should pass the guard. For a harmless denial
+probe, ask it to run `git commit --dry-run --no-verify -m hook-probe` — the
+expected result is an `agent-guard[no-verify]` denial before Git starts. The
+`--dry-run` flag prevents the probe from creating a commit even if the plugin
+is not registered.
diff --git a/docs/adapters/opencode/index.html b/docs/adapters/opencode/index.html
new file mode 100644
index 0000000..755df2a
--- /dev/null
+++ b/docs/adapters/opencode/index.html
@@ -0,0 +1,138 @@
+<!DOCTYPE html><html lang="en" data-astro-cid-z4jru4n3><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="description" content="AI-powered assistant for open-source maintainers. Triage, mentor, draft, pair, and auto-merge under Apache Software Foundation governance."><link rel="icon" type="image/svg+xml" href="/favicon.svg"><link rel="icon" type="image/x-icon" sizes="any" href="/favicon.ico"><title>OpenCode harness — Apache Magpi [...]
+ var _paq = (window._paq = window._paq || []);
+ /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
+ _paq.push(["setDoNotTrack", true]);
+ _paq.push(["disableCookies"]);
+ _paq.push(["trackPageView"]);
+ _paq.push(["enableLinkTracking"]);
+ (function () {
+ var u = "https://analytics.apache.org/";
+ _paq.push(["setTrackerUrl", u + "matomo.php"]);
+ _paq.push(["setSiteId", "89"]);
+ var d = document,
+ g = d.createElement("script"),
+ s = d.getElementsByTagName("script")[0];
+ g.async = true;
+ g.src = u + "matomo.js";
+ s.parentNode.insertBefore(g, s);
+ })();
+ </script><link rel="stylesheet" href="/_astro/SiteFooter.C2Dgj2WR.css"><style>.tree-summary[data-astro-cid-lihgpoae]{list-style:none}.tree-summary[data-astro-cid-lihgpoae]::-webkit-details-marker{display:none}.tree-chevron[data-astro-cid-lihgpoae]{color:var(--color-subtext-color);transition:transform .15s}details[data-astro-cid-lihgpoae][open]>.tree-summary[data-astro-cid-lihgpoae] .tree-chevron[data-astro-cid-lihgpoae]{transform:rotate(90deg)}.prose h1{color:var(--color-default-font [...]
+</style></head><body data-astro-cid-z4jru4n3><nav class="relative z-10 flex w-full items-center justify-between bg-default-background px-8 py-5 mobile:px-4"><a href="/" aria-label="Apache Magpie home" class="flex items-end justify-end gap-2 px-2 py-2"><img class="h-10 w-10 flex-none object-cover" src="/subframe-mark.svg" alt="Apache Magpie"/><img class="h-10 flex-none object-contain" src="/subframe-wordmark.png" alt="Magpie"/><span class="self-center -mt-2 -ml-2 text-[10px] font-[700] le [...]
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<h1 id="opencode-harness">OpenCode harness</h1>
+<p><strong>Capability:</strong> capability:platform</p>
+<p><strong>Harness:</strong> OpenCode</p>
+<p>OpenCode uses Magpie’s skill sources, deterministic action guard, spec-loop
+runner, and clean-environment wrapper. Nothing about a Magpie skill or a guard
+rule is harness-aware: the same files that serve Claude Code serve OpenCode,
+through a different registration mechanism.</p>
+<h2 id="harness-contract">Harness contract</h2>
+<table>
+<thead>
+<tr>
+<th>Magpie requirement</th>
+<th>OpenCode implementation</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Skill discovery</td>
+<td>OpenCode is part of the cluster that converged on <code>.agents/skills/</code>, which is the canonical target the <code>universal</code> row in <a href="https://github.com/apache/magpie/blob/main/skills/setup/agents.md"><code>agents.md</code></a> already writes. It also reads native Agent Skills from <code>.opencode/skills/</code> (project) or <code>~/.opencode/skills/</code> (personal).</td>
+</tr>
+<tr>
+<td>Deterministic guard</td>
+<td>A <a href="https://opencode.ai/docs/plugins/">plugin</a> on <code>tool.execute.before</code> forwards each <code>bash</code> command to <code>agent-guard.py --opencode</code> and throws the deny reason, which aborts the tool call.</td>
+</tr>
+<tr>
+<td>Spec-loop</td>
+<td>The <code>opencode</code> profile passes the prompt positionally to <code>opencode run</code>, with <code>--auto</code>, <code>--model</code>, and <code>--format json</code>.</td>
+</tr>
+<tr>
+<td>Credential isolation</td>
+<td><code>opencode-iso</code> launches the CLI through the clean-environment wrapper.</td>
+</tr>
+</tbody>
+</table>
+<h2 id="deterministic-guard-rules">Deterministic guard rules</h2>
+<p>OpenCode aborts a tool call whose <code>tool.execute.before</code> handler throws, which
+is the OpenCode equivalent of a Claude Code <code>PreToolUse</code> deny. The plugin in
+<a href="https://github.com/apache/magpie/blob/main/tools/agent-guard/opencode/plugin.js"><code>tools/agent-guard/opencode/plugin.js</code></a>
+forwards each <code>bash</code> command to the shared <code>dispatch()</code> core and throws with
+the reason the core returns.</p>
+<p>Register it by dropping the plugin into OpenCode’s plugin directory:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#B392F0">mkdir</span><span style="color:#79B8FF"> -p</span><span style="color:#9ECBFF"> .opencode/plugin</span></span>
+<span class="line"><span style="color:#B392F0">ln</span><span style="color:#79B8FF"> -s</span><span style="color:#9ECBFF"> "<framework>/tools/agent-guard/opencode/plugin.js"</span><span style="color:#9ECBFF"> .opencode/plugin/agent-guard.js</span></span></code></pre>
+<p>The plugin locates the engine at <code>.claude/hooks/agent-guard.py</code> under the
+worktree by default, so a repository already wired for Claude Code needs no
+second copy of the script, and honours
+<code>MAGPIE_AGENT_GUARD=/abs/path/agent-guard.py</code> to point elsewhere.</p>
+<p>Because both harnesses call the same <code>dispatch()</code>, the bundled and
+skill-contributed guards, the <code>MAGPIE_*</code> overrides, and the deny reasons are
+byte-for-byte identical across the two. Full wiring notes are in the
+<a href="https://github.com/apache/magpie/blob/main/tools/agent-guard/README.md#opencode">agent-guard OpenCode recipe</a>.</p>
+<h2 id="spec-loop-runner">Spec-loop runner</h2>
+<p>The <code>opencode</code> profile in <a href="https://github.com/apache/magpie/blob/main/tools/spec-loop/lib.sh"><code>tools/spec-loop/lib.sh</code></a>
+runs <code>opencode run --auto --model … "<prompt>"</code> from the repository root and
+asks for stream JSON with <code>--format json</code>. Setting <code>SPEC_LOOP_AGENT=opencode</code>
+is normally the whole configuration:</p>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#E1E4E8">SPEC_LOOP_AGENT</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">opencode</span><span style="color:#E1E4E8"> SPEC_LOOP_MODEL</span><span style="color:#F97583">=</span><span style="color:#9ECBFF">anthropic/claude-sonnet-4-5</span><span style="color:#B392F0"> \</span></span>
+<span class="line"><span style="color:#9ECBFF"> tools/spec-loop/loop.sh</span><span style="color:#F97583"> <</span><span style="color:#9ECBFF">spe</span><span style="color:#E1E4E8">c</span><span style="color:#F97583">></span></span></code></pre>
+<p>OpenCode is the one harness whose reasoning-effort band is not an identity
+mapping: the runner translates the neutral <code>low</code> / <code>medium</code> / <code>high</code> to
+<code>--variant minimal</code> / <code>medium</code> / <code>max</code>. See the
+<a href="https://github.com/apache/magpie/blob/main/tools/spec-loop/README.md">spec-loop guide</a>.</p>
+<h2 id="clean-environment-wrapper">Clean-environment wrapper</h2>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#79B8FF">source</span><span style="color:#9ECBFF"> /path/to/magpie/tools/agent-isolation/agent-iso.sh</span></span>
+<span class="line"><span style="color:#B392F0">opencode-iso</span></span></code></pre>
+<p><code>opencode-iso</code> applies the same <code>env -i</code> credential strip as <code>claude-iso</code>, and
+adds no settings grant: OpenCode takes its filesystem isolation from the
+OS-level sandbox rather than from a per-launch allowlist. Network restrictions
+and tool approval are separate controls, described in the
+<a href="/docs/setup/secure-agent-setup">secure-agent setup</a>.</p>
+<h2 id="verify">Verify</h2>
+<pre class="astro-code github-dark" style="background-color:#24292e;color:#e1e4e8; overflow-x: auto;" tabindex="0" data-language="bash"><code><span class="line"><span style="color:#B392F0">uv</span><span style="color:#9ECBFF"> run</span><span style="color:#79B8FF"> --directory</span><span style="color:#9ECBFF"> tools/agent-guard</span><span style="color:#79B8FF"> --project</span><span style="color:#9ECBFF"> .</span><span style="color:#9ECBFF"> python</span><span style="color:#79B8FF"> -m [...]
+<span class="line"><span style="color:#B392F0">bash</span><span style="color:#9ECBFF"> tools/spec-loop/tests/test_runner_fixtures.sh</span></span></code></pre>
+<p>The guard tests cover the OpenCode path end-to-end — the plugin’s command
+routing, the throw-on-deny contract, and that a decision made by the shared
+core is preserved unchanged. The runner fixtures verify the positional prompt,
+the <code>--auto</code> flag, and the effort-band translation, including the <code>low</code> →
+<code>minimal</code> mapping that is unique to this harness.</p>
+<p>To verify in a live session, start OpenCode from the checkout root and ask it
+to run <code>git status --short</code>; it should pass the guard. For a harmless denial
+probe, ask it to run <code>git commit --dry-run --no-verify -m hook-probe</code> — the
+expected result is an <code>agent-guard[no-verify]</code> denial before Git starts. The
+<code>--dry-run</code> flag prevents the probe from creating a commit even if the plugin
+is not registered.</p>
+</article></main><aside class="hidden xl:block w-60 flex-none border-l border-solid border-neutral-200 bg-default-background sticky top-0 h-screen overflow-y-auto px-5 py-12"><div class="mb-3 text-caption font-caption uppercase tracking-wider text-subtext-color">On this page</div><nav><ul class="flex flex-col gap-1.5"><li><a href="#harness-contract" class="block text-caption font-caption text-subtext-color hover:text-brand-700" style="padding-left: 0rem">Harness contract</a></li><li><a h [...]
+ (() => {
+ const nav = document.getElementById("docs-nav-scroll");
+ if (!nav) return;
+ for (const link of nav.querySelectorAll("summary a[href]")) {
+ link.addEventListener("click", (event) => {
+ const branch = link.closest("details");
+ if (!branch) return;
+ const plainClick =
+ event.button === 0 &&
+ !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
+ if (plainClick) {
+ event.preventDefault();
+ branch.open = true;
+ window.location.href = link.href;
+ } else {
+ setTimeout(() => { branch.open = true; }, 0);
+ }
+ });
+ }
+ })();
+ </script><script>
+ (() => {
+ const scroller = document.getElementById("docs-nav-scroll");
+ const active = scroller?.querySelector('[aria-current="page"]');
+ if (!scroller || !active) return;
+ const target =
+ active.offsetTop - scroller.clientHeight / 2 + active.offsetHeight / 2;
+ scroller.scrollTop = Math.max(0, target);
+ })();
+ </script><a href="https://github.com/apache/magpie/edit/main/docs/adapters/opencode.md" target="_blank" rel="noopener noreferrer" class="suggest-change" aria-label="Suggest a change to this page on GitHub" data-astro-cid-z4jru4n3><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" data-astro-cid-z4jru4n3><path d="M12 20h9" data-astro-cid-z4jru4n3></path><path d="M16.5 3.5a2. [...]
\ No newline at end of file
diff --git a/docs/adapters/readme.md b/docs/adapters/readme.md
new file mode 100644
index 0000000..d315239
--- /dev/null
+++ b/docs/adapters/readme.md
@@ -0,0 +1,70 @@
+# Adapters and runtimes
+
+Rendered page: https://magpie.apache.org/docs/adapters/readme/
+
+Source: https://github.com/apache/magpie/blob/main/docs/adapters/README.md
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+A Magpie skill names no vendor. It says *what* it needs — open a pull
+request, fetch a mail thread, read a committee roster — and an **adapter**
+binds that request to one concrete service. A **runtime** is the other half:
+the agentic harness that executes the skill in the first place.
+
+Both are swappable by configuration rather than by rewriting a skill, which
+is what [vendor neutrality](/docs/vendor-neutrality) means in practice. This
+section is the map of what exists and how to add what does not.
+
+## Harnesses
+
+One page per supported agentic harness, each declaring
+`capability:platform`:
+
+- [**Codex**](/docs/adapters/codex) — first-class harness.
+- [**Cursor**](/docs/adapters/cursor) — Composer and the Agent CLI.
+- [**Gemini CLI**](/docs/adapters/gemini) — extension install, `BeforeTool` guard, tool
+ sandboxing and policies. Experimental.
+- [**Kiro CLI**](/docs/adapters/kiro) — per-skill installs, no marketplace; guard on
+ `preToolUse`.
+- [**Local LLM**](/docs/adapters/local-llm) — Ollama, llama.cpp, vLLM.
+- [**OpenCode**](/docs/adapters/opencode) — guard plugin on `tool.execute.before`.
+
+### What isolation each harness actually gets
+
+Not the same thing, and the differences matter more than the similarities.
+Every harness gets the clean-environment layer; the action guard reaches four
+of six.
+
+| Harness | Clean environment | Filesystem sandbox | Action guard |
+|---|---|---|---|
+| **Claude Code** | `claude-iso` | Seatbelt / bubblewrap, plus a per-repo allowlist | ✅ `PreToolUse` |
+| **Gemini CLI** | `agent-iso gemini` | tool sandboxing + policies | ✅ `BeforeTool` |
+| **OpenCode** | `opencode-iso` | from the OS-level sandbox | ✅ `tool.execute.before` |
+| **Kiro CLI** | `kiro-iso` | from the OS-level sandbox | ✅ `preToolUse` |
+| **OpenAI Codex CLI** | `agent-iso codex` | Codex's own sandbox and exec policy, statically validated by [sandbox-lint](https://github.com/apache/magpie/blob/main/tools/sandbox-lint/README.md) | ❌ **none** |
+| **Cursor** | `agent-iso cursor` | Cursor's own policy | ❌ **none** |
+
+**What the last column costs.** The action guard is what deterministically
+refuses a command that would break a hard framework rule — pinging maintainers,
+a `Co-Authored-By` trailer, `--no-verify`, marking a PR ready prematurely,
+emptying a PR by force-push. On Codex and Cursor those rules are instructions
+the model is asked to follow, not a gate that stops it. Both harnesses have
+their own approval prompts, and neither knows Magpie's rules.
+
+That is a gap in the framework, not in those tools: `agent-guard`'s core is
+harness-neutral and each supported harness needed only a thin adapter. See
+[`tools/agent-guard/README.md`](https://github.com/apache/magpie/blob/main/tools/agent-guard/README.md) for the shape
+one takes, and [adding a harness](/docs/adapters/add-a-harness) for where it plugs in.
+
+Running something else? [**Adding a new agent harness**](/docs/adapters/add-a-harness)
+names every step to wire a new runtime in so it loads skills and enforces
+the action guard like the rest.
+
+## Adapters
+
+- [**Adapter registry**](/docs/adapters/registry) — the discovery index of the tool
+ adapters that ship with the framework, and the organizations they come
+ from.
+- [**Authoring an adapter**](/docs/adapters/authoring) — what to do when Magpie ships no
+ adapter for your backend: a forge, a CNA tool, a chat system.
diff --git a/docs/adapters/readme/index.html b/docs/adapters/readme/index.html
new file mode 100644
index 0000000..d0a24a2
--- /dev/null
+++ b/docs/adapters/readme/index.html
@@ -0,0 +1,146 @@
+<!DOCTYPE html><html lang="en" data-astro-cid-z4jru4n3><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="description" content="AI-powered assistant for open-source maintainers. Triage, mentor, draft, pair, and auto-merge under Apache Software Foundation governance."><link rel="icon" type="image/svg+xml" href="/favicon.svg"><link rel="icon" type="image/x-icon" sizes="any" href="/favicon.ico"><title>Adapters and runtimes — Apache [...]
+ var _paq = (window._paq = window._paq || []);
+ /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
+ _paq.push(["setDoNotTrack", true]);
+ _paq.push(["disableCookies"]);
+ _paq.push(["trackPageView"]);
+ _paq.push(["enableLinkTracking"]);
+ (function () {
+ var u = "https://analytics.apache.org/";
+ _paq.push(["setTrackerUrl", u + "matomo.php"]);
+ _paq.push(["setSiteId", "89"]);
+ var d = document,
+ g = d.createElement("script"),
+ s = d.getElementsByTagName("script")[0];
+ g.async = true;
+ g.src = u + "matomo.js";
+ s.parentNode.insertBefore(g, s);
+ })();
+ </script><link rel="stylesheet" href="/_astro/SiteFooter.C2Dgj2WR.css"><style>.tree-summary[data-astro-cid-lihgpoae]{list-style:none}.tree-summary[data-astro-cid-lihgpoae]::-webkit-details-marker{display:none}.tree-chevron[data-astro-cid-lihgpoae]{color:var(--color-subtext-color);transition:transform .15s}details[data-astro-cid-lihgpoae][open]>.tree-summary[data-astro-cid-lihgpoae] .tree-chevron[data-astro-cid-lihgpoae]{transform:rotate(90deg)}.prose h1{color:var(--color-default-font [...]
+</style></head><body data-astro-cid-z4jru4n3><nav class="relative z-10 flex w-full items-center justify-between bg-default-background px-8 py-5 mobile:px-4"><a href="/" aria-label="Apache Magpie home" class="flex items-end justify-end gap-2 px-2 py-2"><img class="h-10 w-10 flex-none object-cover" src="/subframe-mark.svg" alt="Apache Magpie"/><img class="h-10 flex-none object-contain" src="/subframe-wordmark.png" alt="Magpie"/><span class="self-center -mt-2 -ml-2 text-[10px] font-[700] le [...]
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<h1 id="adapters-and-runtimes">Adapters and runtimes</h1>
+<p>A Magpie skill names no vendor. It says <em>what</em> it needs — open a pull
+request, fetch a mail thread, read a committee roster — and an <strong>adapter</strong>
+binds that request to one concrete service. A <strong>runtime</strong> is the other half:
+the agentic harness that executes the skill in the first place.</p>
+<p>Both are swappable by configuration rather than by rewriting a skill, which
+is what <a href="/docs/vendor-neutrality">vendor neutrality</a> means in practice. This
+section is the map of what exists and how to add what does not.</p>
+<h2 id="harnesses">Harnesses</h2>
+<p>One page per supported agentic harness, each declaring
+<code>capability:platform</code>:</p>
+<ul>
+<li><a href="/docs/adapters/codex"><strong>Codex</strong></a> — first-class harness.</li>
+<li><a href="/docs/adapters/cursor"><strong>Cursor</strong></a> — Composer and the Agent CLI.</li>
+<li><a href="/docs/adapters/gemini"><strong>Gemini CLI</strong></a> — extension install, <code>BeforeTool</code> guard, tool
+sandboxing and policies. Experimental.</li>
+<li><a href="/docs/adapters/kiro"><strong>Kiro CLI</strong></a> — per-skill installs, no marketplace; guard on
+<code>preToolUse</code>.</li>
+<li><a href="/docs/adapters/local-llm"><strong>Local LLM</strong></a> — Ollama, llama.cpp, vLLM.</li>
+<li><a href="/docs/adapters/opencode"><strong>OpenCode</strong></a> — guard plugin on <code>tool.execute.before</code>.</li>
+</ul>
+<h3 id="what-isolation-each-harness-actually-gets">What isolation each harness actually gets</h3>
+<p>Not the same thing, and the differences matter more than the similarities.
+Every harness gets the clean-environment layer; the action guard reaches four
+of six.</p>
+<table>
+<thead>
+<tr>
+<th>Harness</th>
+<th>Clean environment</th>
+<th>Filesystem sandbox</th>
+<th>Action guard</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>Claude Code</strong></td>
+<td><code>claude-iso</code></td>
+<td>Seatbelt / bubblewrap, plus a per-repo allowlist</td>
+<td>✅ <code>PreToolUse</code></td>
+</tr>
+<tr>
+<td><strong>Gemini CLI</strong></td>
+<td><code>agent-iso gemini</code></td>
+<td>tool sandboxing + policies</td>
+<td>✅ <code>BeforeTool</code></td>
+</tr>
+<tr>
+<td><strong>OpenCode</strong></td>
+<td><code>opencode-iso</code></td>
+<td>from the OS-level sandbox</td>
+<td>✅ <code>tool.execute.before</code></td>
+</tr>
+<tr>
+<td><strong>Kiro CLI</strong></td>
+<td><code>kiro-iso</code></td>
+<td>from the OS-level sandbox</td>
+<td>✅ <code>preToolUse</code></td>
+</tr>
+<tr>
+<td><strong>OpenAI Codex CLI</strong></td>
+<td><code>agent-iso codex</code></td>
+<td>Codex’s own sandbox and exec policy, statically validated by <a href="https://github.com/apache/magpie/blob/main/tools/sandbox-lint/README.md">sandbox-lint</a></td>
+<td>❌ <strong>none</strong></td>
+</tr>
+<tr>
+<td><strong>Cursor</strong></td>
+<td><code>agent-iso cursor</code></td>
+<td>Cursor’s own policy</td>
+<td>❌ <strong>none</strong></td>
+</tr>
+</tbody>
+</table>
+<p><strong>What the last column costs.</strong> The action guard is what deterministically
+refuses a command that would break a hard framework rule — pinging maintainers,
+a <code>Co-Authored-By</code> trailer, <code>--no-verify</code>, marking a PR ready prematurely,
+emptying a PR by force-push. On Codex and Cursor those rules are instructions
+the model is asked to follow, not a gate that stops it. Both harnesses have
+their own approval prompts, and neither knows Magpie’s rules.</p>
+<p>That is a gap in the framework, not in those tools: <code>agent-guard</code>’s core is
+harness-neutral and each supported harness needed only a thin adapter. See
+<a href="https://github.com/apache/magpie/blob/main/tools/agent-guard/README.md"><code>tools/agent-guard/README.md</code></a> for the shape
+one takes, and <a href="/docs/adapters/add-a-harness">adding a harness</a> for where it plugs in.</p>
+<p>Running something else? <a href="/docs/adapters/add-a-harness"><strong>Adding a new agent harness</strong></a>
+names every step to wire a new runtime in so it loads skills and enforces
+the action guard like the rest.</p>
+<h2 id="adapters">Adapters</h2>
+<ul>
+<li><a href="/docs/adapters/registry"><strong>Adapter registry</strong></a> — the discovery index of the tool
+adapters that ship with the framework, and the organizations they come
+from.</li>
+<li><a href="/docs/adapters/authoring"><strong>Authoring an adapter</strong></a> — what to do when Magpie ships no
+adapter for your backend: a forge, a CNA tool, a chat system.</li>
+</ul>
+</article></main><aside class="hidden xl:block w-60 flex-none border-l border-solid border-neutral-200 bg-default-background sticky top-0 h-screen overflow-y-auto px-5 py-12"><div class="mb-3 text-caption font-caption uppercase tracking-wider text-subtext-color">On this page</div><nav><ul class="flex flex-col gap-1.5"><li><a href="#harnesses" class="block text-caption font-caption text-subtext-color hover:text-brand-700" style="padding-left: 0rem">Harnesses</a></li><li><a href="#what-iso [...]
+ (() => {
+ const nav = document.getElementById("docs-nav-scroll");
+ if (!nav) return;
+ for (const link of nav.querySelectorAll("summary a[href]")) {
+ link.addEventListener("click", (event) => {
+ const branch = link.closest("details");
+ if (!branch) return;
+ const plainClick =
+ event.button === 0 &&
+ !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
+ if (plainClick) {
+ event.preventDefault();
+ branch.open = true;
+ window.location.href = link.href;
+ } else {
+ setTimeout(() => { branch.open = true; }, 0);
+ }
+ });
+ }
+ })();
+ </script><script>
+ (() => {
+ const scroller = document.getElementById("docs-nav-scroll");
+ const active = scroller?.querySelector('[aria-current="page"]');
+ if (!scroller || !active) return;
+ const target =
+ active.offsetTop - scroller.clientHeight / 2 + active.offsetHeight / 2;
+ scroller.scrollTop = Math.max(0, target);
+ })();
+ </script><a href="https://github.com/apache/magpie/edit/main/docs/adapters/README.md" target="_blank" rel="noopener noreferrer" class="suggest-change" aria-label="Suggest a change to this page on GitHub" data-astro-cid-z4jru4n3><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" data-astro-cid-z4jru4n3><path d="M12 20h9" data-astro-cid-z4jru4n3></path><path d="M16.5 3.5a2.12 [...]
\ No newline at end of file
diff --git a/docs/adapters/registry.md b/docs/adapters/registry.md
new file mode 100644
index 0000000..98e1af3
--- /dev/null
+++ b/docs/adapters/registry.md
@@ -0,0 +1,85 @@
+# Adapter registry
+
+Rendered page: https://magpie.apache.org/docs/adapters/registry/
+
+Source: https://github.com/apache/magpie/blob/main/docs/adapters/registry.md
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+A **discovery** index of the [tool adapters](/docs/vendor-neutrality#tool-adapters)
+and [organizations](https://github.com/apache/magpie/blob/main/organizations/README.md) Magpie knows about —
+the ones that ship in-tree, the open extension points, and links to
+**community-maintained adapters defined elsewhere**.
+
+> **Discovery, never installation.** Per
+> [`PRINCIPLES.md` §13](https://github.com/apache/magpie/blob/main/PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies),
+> this page is an index, not a package manager. Nothing here is
+> auto-fetched. To use an adapter you wire it in deliberately — point
+> your `<project-config>/project.md` (or `organizations/<org>/`) at it,
+> exactly as you would a built-in one. An external link is a pointer for
+> humans to evaluate, not a supply-chain hook.
+>
+> This applies to the *adapter/organization* index on this page. Skills
+> are different: §13 permits **installing** a skill or skill-family from a
+> **trusted** external source — pinned, verified, and adopter-vouched.
+> That mechanism and its own discovery index live under
+> [`docs/skill-sources/`](/docs/skill-sources/readme).
+
+To author a new adapter, see [`authoring.md`](/docs/adapters/authoring).
+
+## In-tree tool adapters
+
+Each capability contract under `tools/<contract>/` enumerates the
+adapters that fulfil it. Shipping = a working adapter in the tree;
+extension point = a documented, labelled slot with a tracking issue.
+
+| Capability contract | Shipping adapter(s) | Extension points (tracked) |
+|---|---|---|
+| [`tools/cve-tool`](https://github.com/apache/magpie/tree/main/tools/cve-tool/) | [`cve-tool-vulnogram`](https://github.com/apache/magpie/tree/main/tools/cve-tool-vulnogram/) (ASF) | MITRE form, CVE.org direct, GHSA |
+| [`tools/mail-archive`](https://github.com/apache/magpie/tree/main/tools/mail-archive/) | [`ponymail`](https://github.com/apache/magpie/tree/main/tools/ponymail/) (ASF), [`gmail`](https://github.com/apache/magpie/tree/main/tools/gmail/), [`sourcehut`](https://github.com/apache/magpie/tree/main/tools/sourcehut/) | Hyperkitty, Discourse, Google Groups, GitHub Discussions |
+| [`tools/mail-source`](https://github.com/apache/magpie/tree/main/tools/mail-source/) | mbox, IMAP, [`gmail`](https://github.com/apache/magpie/tree/main/tools/gmail/), [`maildir`](https://github.com/apache/magpie/tree/main/tools/maildir/), [`ponymail`](https://github.com/apache/magpie/tree/main/tools/ponymail/) (ASF) | Mailman 3 ([#306](https://github.com/apache/magpie/issues/306)) |
+| [`tools/forwarder-relay`](https://github.com/apache/magpie/tree/main/tools/forwarder-relay/) | ASF-security ([`tools/gmail/asf-relay.md`](https://github.com/apache/magpie/blob/main/tools/gmail/asf-relay.md)) | huntr.com, HackerOne, GHSA relay |
+| [`tools/scan-format`](https://github.com/apache/magpie/tree/main/tools/scan-format/) | ASVS | other scanner formats |
+| [`tools/vcs`](https://github.com/apache/magpie/tree/main/tools/vcs/) | Git, Mercurial, Fossil | Subversion [\#602](https://github.com/apache/magpie/issues/602), Jujutsu [\#603](https://github.com/apache/magpie/issues/603), Perforce [\#605](https://github.com/apache/magpie/issues/605) |
+| Forge / tracker | [`github`](https://github.com/apache/magpie/tree/main/tools/github/), [`jira`](https://github.com/apache/magpie/tree/main/tools/jira/), [`bitbucket`](https://github.com/apache/magpie/tree/main/tools/bitbucket/) `partial-read-only` foundation, [`sourcehut`](https://github.com/apache/magpie/tree/main/tools/sourcehut/), [`fossil`](https://github.com/apache/magpie/tree/main/tools/fossil/) | GitLab [\#305](https://github.com/apache/magpie/issues/305), Forgejo/Gitea [\#310] [...]
+| Agentic harness | Claude Code, [Codex](/docs/adapters/codex) `experimental` ([#313](https://github.com/apache/magpie/issues/313)), [Gemini CLI](/docs/adapters/gemini) ([#314](https://github.com/apache/magpie/issues/314)), [Local LLM (Ollama / llama.cpp / vLLM)](/docs/adapters/local-llm) ([#315](https://github.com/apache/magpie/issues/315)), [Cursor](/docs/adapters/cursor) ([#316](https://github.com/apache/magpie/issues/316)) | Aider [#317](https://github.com/apache/magpie/issues/317)–O [...]
+| Security cross-ref | — | OSV.dev [#311](https://github.com/apache/magpie/issues/311) |
+
+## In-tree organizations
+
+| Organization | Directory |
+|---|---|
+| Apache Software Foundation | [`organizations/ASF/`](https://github.com/apache/magpie/tree/main/organizations/ASF/) |
+| Independent (no formal governing body) | [`organizations/independent/`](https://github.com/apache/magpie/tree/main/organizations/independent/) |
+
+## Community / external adapters
+
+Adapters maintained **outside** this repository — kept in their authors'
+own repos and linked here for discovery. An adopter wires one in by
+pointing their config at it (see the discovery-not-installation note
+above); the framework never fetches them.
+
+| Adapter | Capability / org | Maintainer | Link | Notes |
+|---|---|---|---|---|
+| *(none listed yet)* | | | | Open a PR to add a row — see below. |
+
+### Adding an external adapter to this index
+
+Open a PR against `apache/magpie` that adds one row to the table above
+with: the adapter name, the capability contract (or organization) it
+implements, the maintainer, a link to its repository, and a one-line
+note. Listing here is **editorial discovery only** — it makes no
+guarantee about the adapter and triggers no install. Adapters you would
+rather contribute into the tree itself follow [`authoring.md`](/docs/adapters/authoring)
+instead.
+
+## See also
+
+- [`docs/extending.md`](/docs/extending) — the full extension model (what / where / who).
+- [`docs/vendor-neutrality.md`](/docs/vendor-neutrality) — how tool adapters and organizations deliver neutrality.
+- [`authoring.md`](/docs/adapters/authoring) — authoring your own adapter.
+- [`organizations/README.md`](https://github.com/apache/magpie/blob/main/organizations/README.md) — the organization entity.
diff --git a/docs/adapters/registry/index.html b/docs/adapters/registry/index.html
new file mode 100644
index 0000000..5c70f85
--- /dev/null
+++ b/docs/adapters/registry/index.html
@@ -0,0 +1,193 @@
+<!DOCTYPE html><html lang="en" data-astro-cid-z4jru4n3><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="description" content="AI-powered assistant for open-source maintainers. Triage, mentor, draft, pair, and auto-merge under Apache Software Foundation governance."><link rel="icon" type="image/svg+xml" href="/favicon.svg"><link rel="icon" type="image/x-icon" sizes="any" href="/favicon.ico"><title>Adapter registry — Apache Magpi [...]
+ var _paq = (window._paq = window._paq || []);
+ /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
+ _paq.push(["setDoNotTrack", true]);
+ _paq.push(["disableCookies"]);
+ _paq.push(["trackPageView"]);
+ _paq.push(["enableLinkTracking"]);
+ (function () {
+ var u = "https://analytics.apache.org/";
+ _paq.push(["setTrackerUrl", u + "matomo.php"]);
+ _paq.push(["setSiteId", "89"]);
+ var d = document,
+ g = d.createElement("script"),
+ s = d.getElementsByTagName("script")[0];
+ g.async = true;
+ g.src = u + "matomo.js";
+ s.parentNode.insertBefore(g, s);
+ })();
+ </script><link rel="stylesheet" href="/_astro/SiteFooter.C2Dgj2WR.css"><style>.tree-summary[data-astro-cid-lihgpoae]{list-style:none}.tree-summary[data-astro-cid-lihgpoae]::-webkit-details-marker{display:none}.tree-chevron[data-astro-cid-lihgpoae]{color:var(--color-subtext-color);transition:transform .15s}details[data-astro-cid-lihgpoae][open]>.tree-summary[data-astro-cid-lihgpoae] .tree-chevron[data-astro-cid-lihgpoae]{transform:rotate(90deg)}.prose h1{color:var(--color-default-font [...]
+</style></head><body data-astro-cid-z4jru4n3><nav class="relative z-10 flex w-full items-center justify-between bg-default-background px-8 py-5 mobile:px-4"><a href="/" aria-label="Apache Magpie home" class="flex items-end justify-end gap-2 px-2 py-2"><img class="h-10 w-10 flex-none object-cover" src="/subframe-mark.svg" alt="Apache Magpie"/><img class="h-10 flex-none object-contain" src="/subframe-wordmark.png" alt="Magpie"/><span class="self-center -mt-2 -ml-2 text-[10px] font-[700] le [...]
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<h1 id="adapter-registry">Adapter registry</h1>
+<p>A <strong>discovery</strong> index of the <a href="/docs/vendor-neutrality#tool-adapters">tool adapters</a>
+and <a href="https://github.com/apache/magpie/blob/main/organizations/README.md">organizations</a> Magpie knows about —
+the ones that ship in-tree, the open extension points, and links to
+<strong>community-maintained adapters defined elsewhere</strong>.</p>
+<blockquote>
+<p><strong>Discovery, never installation.</strong> Per
+<a href="https://github.com/apache/magpie/blob/main/PRINCIPLES.md#13-snapshot-plus-override-never-vendored-copies"><code>PRINCIPLES.md</code> §13</a>,
+this page is an index, not a package manager. Nothing here is
+auto-fetched. To use an adapter you wire it in deliberately — point
+your <code><project-config>/project.md</code> (or <code>organizations/<org>/</code>) at it,
+exactly as you would a built-in one. An external link is a pointer for
+humans to evaluate, not a supply-chain hook.</p>
+<p>This applies to the <em>adapter/organization</em> index on this page. Skills
+are different: §13 permits <strong>installing</strong> a skill or skill-family from a
+<strong>trusted</strong> external source — pinned, verified, and adopter-vouched.
+That mechanism and its own discovery index live under
+<a href="/docs/skill-sources/readme"><code>docs/skill-sources/</code></a>.</p>
+</blockquote>
+<p>To author a new adapter, see <a href="/docs/adapters/authoring"><code>authoring.md</code></a>.</p>
+<h2 id="in-tree-tool-adapters">In-tree tool adapters</h2>
+<p>Each capability contract under <code>tools/<contract>/</code> enumerates the
+adapters that fulfil it. Shipping = a working adapter in the tree;
+extension point = a documented, labelled slot with a tracking issue.</p>
+<table>
+<thead>
+<tr>
+<th>Capability contract</th>
+<th>Shipping adapter(s)</th>
+<th>Extension points (tracked)</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><a href="https://github.com/apache/magpie/tree/main/tools/cve-tool/"><code>tools/cve-tool</code></a></td>
+<td><a href="https://github.com/apache/magpie/tree/main/tools/cve-tool-vulnogram/"><code>cve-tool-vulnogram</code></a> (ASF)</td>
+<td>MITRE form, CVE.org direct, GHSA</td>
+</tr>
+<tr>
+<td><a href="https://github.com/apache/magpie/tree/main/tools/mail-archive/"><code>tools/mail-archive</code></a></td>
+<td><a href="https://github.com/apache/magpie/tree/main/tools/ponymail/"><code>ponymail</code></a> (ASF), <a href="https://github.com/apache/magpie/tree/main/tools/gmail/"><code>gmail</code></a>, <a href="https://github.com/apache/magpie/tree/main/tools/sourcehut/"><code>sourcehut</code></a></td>
+<td>Hyperkitty, Discourse, Google Groups, GitHub Discussions</td>
+</tr>
+<tr>
+<td><a href="https://github.com/apache/magpie/tree/main/tools/mail-source/"><code>tools/mail-source</code></a></td>
+<td>mbox, IMAP, <a href="https://github.com/apache/magpie/tree/main/tools/gmail/"><code>gmail</code></a>, <a href="https://github.com/apache/magpie/tree/main/tools/maildir/"><code>maildir</code></a>, <a href="https://github.com/apache/magpie/tree/main/tools/ponymail/"><code>ponymail</code></a> (ASF)</td>
+<td>Mailman 3 (<a href="https://github.com/apache/magpie/issues/306">#306</a>)</td>
+</tr>
+<tr>
+<td><a href="https://github.com/apache/magpie/tree/main/tools/forwarder-relay/"><code>tools/forwarder-relay</code></a></td>
+<td>ASF-security (<a href="https://github.com/apache/magpie/blob/main/tools/gmail/asf-relay.md"><code>tools/gmail/asf-relay.md</code></a>)</td>
+<td>huntr.com, HackerOne, GHSA relay</td>
+</tr>
+<tr>
+<td><a href="https://github.com/apache/magpie/tree/main/tools/scan-format/"><code>tools/scan-format</code></a></td>
+<td>ASVS</td>
+<td>other scanner formats</td>
+</tr>
+<tr>
+<td><a href="https://github.com/apache/magpie/tree/main/tools/vcs/"><code>tools/vcs</code></a></td>
+<td>Git, Mercurial, Fossil</td>
+<td>Subversion <a href="https://github.com/apache/magpie/issues/602">#602</a>, Jujutsu <a href="https://github.com/apache/magpie/issues/603">#603</a>, Perforce <a href="https://github.com/apache/magpie/issues/605">#605</a></td>
+</tr>
+<tr>
+<td>Forge / tracker</td>
+<td><a href="https://github.com/apache/magpie/tree/main/tools/github/"><code>github</code></a>, <a href="https://github.com/apache/magpie/tree/main/tools/jira/"><code>jira</code></a>, <a href="https://github.com/apache/magpie/tree/main/tools/bitbucket/"><code>bitbucket</code></a> <code>partial-read-only</code> foundation, <a href="https://github.com/apache/magpie/tree/main/tools/sourcehut/"><code>sourcehut</code></a>, <a href="https://github.com/apache/magpie/tree/main/tools/fossil/"><co [...]
+<td>GitLab <a href="https://github.com/apache/magpie/issues/305">#305</a>, Forgejo/Gitea <a href="https://github.com/apache/magpie/issues/310">#310</a>, Pagure <a href="https://github.com/apache/magpie/issues/312">#312</a>, deeper Bitbucket/Jira coverage <a href="https://github.com/apache/magpie/issues/606">#606</a>, Bugzilla <a href="https://github.com/apache/magpie/issues/302">#302</a></td>
+</tr>
+<tr>
+<td>Agentic harness</td>
+<td>Claude Code, <a href="/docs/adapters/codex">Codex</a> <code>experimental</code> (<a href="https://github.com/apache/magpie/issues/313">#313</a>), <a href="/docs/adapters/gemini">Gemini CLI</a> (<a href="https://github.com/apache/magpie/issues/314">#314</a>), <a href="/docs/adapters/local-llm">Local LLM (Ollama / llama.cpp / vLLM)</a> (<a href="https://github.com/apache/magpie/issues/315">#315</a>), <a href="/docs/adapters/cursor">Cursor</a> (<a href="https://github.com/apache/magpie/ [...]
+<td>Aider <a href="https://github.com/apache/magpie/issues/317">#317</a>–OpenHands <a href="https://github.com/apache/magpie/issues/322">#322</a></td>
+</tr>
+<tr>
+<td>Security cross-ref</td>
+<td>—</td>
+<td>OSV.dev <a href="https://github.com/apache/magpie/issues/311">#311</a></td>
+</tr>
+</tbody>
+</table>
+<h2 id="in-tree-organizations">In-tree organizations</h2>
+<table>
+<thead>
+<tr>
+<th>Organization</th>
+<th>Directory</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Apache Software Foundation</td>
+<td><a href="https://github.com/apache/magpie/tree/main/organizations/ASF/"><code>organizations/ASF/</code></a></td>
+</tr>
+<tr>
+<td>Independent (no formal governing body)</td>
+<td><a href="https://github.com/apache/magpie/tree/main/organizations/independent/"><code>organizations/independent/</code></a></td>
+</tr>
+</tbody>
+</table>
+<h2 id="community--external-adapters">Community / external adapters</h2>
+<p>Adapters maintained <strong>outside</strong> this repository — kept in their authors’
+own repos and linked here for discovery. An adopter wires one in by
+pointing their config at it (see the discovery-not-installation note
+above); the framework never fetches them.</p>
+<table>
+<thead>
+<tr>
+<th>Adapter</th>
+<th>Capability / org</th>
+<th>Maintainer</th>
+<th>Link</th>
+<th>Notes</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><em>(none listed yet)</em></td>
+<td></td>
+<td></td>
+<td></td>
+<td>Open a PR to add a row — see below.</td>
+</tr>
+</tbody>
+</table>
+<h3 id="adding-an-external-adapter-to-this-index">Adding an external adapter to this index</h3>
+<p>Open a PR against <code>apache/magpie</code> that adds one row to the table above
+with: the adapter name, the capability contract (or organization) it
+implements, the maintainer, a link to its repository, and a one-line
+note. Listing here is <strong>editorial discovery only</strong> — it makes no
+guarantee about the adapter and triggers no install. Adapters you would
+rather contribute into the tree itself follow <a href="/docs/adapters/authoring"><code>authoring.md</code></a>
+instead.</p>
+<h2 id="see-also">See also</h2>
+<ul>
+<li><a href="/docs/extending"><code>docs/extending.md</code></a> — the full extension model (what / where / who).</li>
+<li><a href="/docs/vendor-neutrality"><code>docs/vendor-neutrality.md</code></a> — how tool adapters and organizations deliver neutrality.</li>
+<li><a href="/docs/adapters/authoring"><code>authoring.md</code></a> — authoring your own adapter.</li>
+<li><a href="https://github.com/apache/magpie/blob/main/organizations/README.md"><code>organizations/README.md</code></a> — the organization entity.</li>
+</ul>
+</article></main><aside class="hidden xl:block w-60 flex-none border-l border-solid border-neutral-200 bg-default-background sticky top-0 h-screen overflow-y-auto px-5 py-12"><div class="mb-3 text-caption font-caption uppercase tracking-wider text-subtext-color">On this page</div><nav><ul class="flex flex-col gap-1.5"><li><a href="#in-tree-tool-adapters" class="block text-caption font-caption text-subtext-color hover:text-brand-700" style="padding-left: 0rem">In-tree tool adapters</a></l [...]
+ (() => {
+ const nav = document.getElementById("docs-nav-scroll");
+ if (!nav) return;
+ for (const link of nav.querySelectorAll("summary a[href]")) {
+ link.addEventListener("click", (event) => {
+ const branch = link.closest("details");
+ if (!branch) return;
+ const plainClick =
+ event.button === 0 &&
+ !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
+ if (plainClick) {
+ event.preventDefault();
+ branch.open = true;
+ window.location.href = link.href;
+ } else {
+ setTimeout(() => { branch.open = true; }, 0);
+ }
+ });
+ }
+ })();
+ </script><script>
+ (() => {
+ const scroller = document.getElementById("docs-nav-scroll");
+ const active = scroller?.querySelector('[aria-current="page"]');
+ if (!scroller || !active) return;
+ const target =
+ active.offsetTop - scroller.clientHeight / 2 + active.offsetHeight / 2;
+ scroller.scrollTop = Math.max(0, target);
+ })();
+ </script><a href="https://github.com/apache/magpie/edit/main/docs/adapters/registry.md" target="_blank" rel="noopener noreferrer" class="suggest-change" aria-label="Suggest a change to this page on GitHub" data-astro-cid-z4jru4n3><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" data-astro-cid-z4jru4n3><path d="M12 20h9" data-astro-cid-z4jru4n3></path><path d="M16.5 3.5a2. [...]
\ No newline at end of file
diff --git a/docs/confidentiality.md b/docs/confidentiality.md
new file mode 100644
index 0000000..df68a38
--- /dev/null
+++ b/docs/confidentiality.md
@@ -0,0 +1,54 @@
+# Confidentiality — drafting elaboration
+
+Rendered page: https://magpie.apache.org/docs/confidentiality/
+
+Source: https://github.com/apache/magpie/blob/main/docs/confidentiality.md
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+Agentic Drafting-time elaboration of the tracker-confidentiality rules. The
+load-bearing rules — the three-layer model (identifiers public, contents
+private, security-framing embargoed), the "what public surfaces must not
+contain" checklist, the content scrub, and "other ASF projects" — live
+inline in
+[`AGENTS.md`](https://github.com/apache/magpie/blob/main/AGENTS.md#confidentiality-of-the-tracker-repository).
+This file holds the two how-to elaborations that an agent loads when it
+is actually composing reporter-facing or public text.
+
+## Sharing a tracker URL with someone who cannot access it
+
+When the recipient is an external reporter, a public-PR reviewer who is
+not on the security team, or any other audience without read access to
+`<tracker>`, **pair the URL with a one-line note** that the link is an
+identifier only:
+
+> Tracking this internally as
+> `https://github.com/<tracker>/issues/NNN` (private — you will not
+> be able to view the page; included as a stable identifier so we
+> both reference the same issue across messages).
+
+Wording is not load-bearing; the load-bearing element is that the
+recipient knows the link will 404 for them and that this is expected.
+The note can be omitted on surfaces where every viewer is a
+security-team member (the tracker itself, `<security-list>` threads
+restricted to the team, internal docs, rollup entries).
+
+## Where the tracker URLs are routinely OK to use
+
+- **Reporter emails** — *may* include the tracker URL in any status
+ update, paired with the explanatory note above. This makes
+ cross-message threading much cleaner for the reporter and gives
+ them a stable identifier to file the report under.
+- **Public `<upstream>` PR descriptions and commit messages** —
+ *may* include the tracker URL as a cross-reference, **so long as
+ the surrounding text does not characterise the PR as a security
+ fix** (no CVE ID, no *"vulnerability"*, no *"security advisory"*
+ framing). The URL alone is opaque to non-team viewers.
+- **Public CVE records and archived advisories** — the tracker URL
+ may appear in `references[]` once the advisory ships. For
+ records still in DRAFT / REVIEW state it stays internal-only.
+- **`gh issue comment` calls inside the tracker repository** — fine,
+ they land on private issues.
+- **`<security-list>` private mail threads** — fine.
+- **`<private-list>` PMC escalation mails** — fine.
diff --git a/docs/confidentiality/index.html b/docs/confidentiality/index.html
new file mode 100644
index 0000000..8e2570e
--- /dev/null
+++ b/docs/confidentiality/index.html
@@ -0,0 +1,96 @@
+<!DOCTYPE html><html lang="en" data-astro-cid-z4jru4n3><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="description" content="AI-powered assistant for open-source maintainers. Triage, mentor, draft, pair, and auto-merge under Apache Software Foundation governance."><link rel="icon" type="image/svg+xml" href="/favicon.svg"><link rel="icon" type="image/x-icon" sizes="any" href="/favicon.ico"><title>Confidentiality — drafting elab [...]
+ var _paq = (window._paq = window._paq || []);
+ /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
+ _paq.push(["setDoNotTrack", true]);
+ _paq.push(["disableCookies"]);
+ _paq.push(["trackPageView"]);
+ _paq.push(["enableLinkTracking"]);
+ (function () {
+ var u = "https://analytics.apache.org/";
+ _paq.push(["setTrackerUrl", u + "matomo.php"]);
+ _paq.push(["setSiteId", "89"]);
+ var d = document,
+ g = d.createElement("script"),
+ s = d.getElementsByTagName("script")[0];
+ g.async = true;
+ g.src = u + "matomo.js";
+ s.parentNode.insertBefore(g, s);
+ })();
+ </script><link rel="stylesheet" href="/_astro/SiteFooter.C2Dgj2WR.css"><style>.tree-summary[data-astro-cid-lihgpoae]{list-style:none}.tree-summary[data-astro-cid-lihgpoae]::-webkit-details-marker{display:none}.tree-chevron[data-astro-cid-lihgpoae]{color:var(--color-subtext-color);transition:transform .15s}details[data-astro-cid-lihgpoae][open]>.tree-summary[data-astro-cid-lihgpoae] .tree-chevron[data-astro-cid-lihgpoae]{transform:rotate(90deg)}.prose h1{color:var(--color-default-font [...]
+</style></head><body data-astro-cid-z4jru4n3><nav class="relative z-10 flex w-full items-center justify-between bg-default-background px-8 py-5 mobile:px-4"><a href="/" aria-label="Apache Magpie home" class="flex items-end justify-end gap-2 px-2 py-2"><img class="h-10 w-10 flex-none object-cover" src="/subframe-mark.svg" alt="Apache Magpie"/><img class="h-10 flex-none object-contain" src="/subframe-wordmark.png" alt="Magpie"/><span class="self-center -mt-2 -ml-2 text-[10px] font-[700] le [...]
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+<h1 id="confidentiality--drafting-elaboration">Confidentiality — drafting elaboration</h1>
+<p>Agentic Drafting-time elaboration of the tracker-confidentiality rules. The
+load-bearing rules — the three-layer model (identifiers public, contents
+private, security-framing embargoed), the “what public surfaces must not
+contain” checklist, the content scrub, and “other ASF projects” — live
+inline in
+<a href="https://github.com/apache/magpie/blob/main/AGENTS.md#confidentiality-of-the-tracker-repository"><code>AGENTS.md</code></a>.
+This file holds the two how-to elaborations that an agent loads when it
+is actually composing reporter-facing or public text.</p>
+<h2 id="sharing-a-tracker-url-with-someone-who-cannot-access-it">Sharing a tracker URL with someone who cannot access it</h2>
+<p>When the recipient is an external reporter, a public-PR reviewer who is
+not on the security team, or any other audience without read access to
+<code><tracker></code>, <strong>pair the URL with a one-line note</strong> that the link is an
+identifier only:</p>
+<blockquote>
+<p>Tracking this internally as
+<code>https://github.com/<tracker>/issues/NNN</code> (private — you will not
+be able to view the page; included as a stable identifier so we
+both reference the same issue across messages).</p>
+</blockquote>
+<p>Wording is not load-bearing; the load-bearing element is that the
+recipient knows the link will 404 for them and that this is expected.
+The note can be omitted on surfaces where every viewer is a
+security-team member (the tracker itself, <code><security-list></code> threads
+restricted to the team, internal docs, rollup entries).</p>
+<h2 id="where-the-tracker-urls-are-routinely-ok-to-use">Where the tracker URLs are routinely OK to use</h2>
+<ul>
+<li><strong>Reporter emails</strong> — <em>may</em> include the tracker URL in any status
+update, paired with the explanatory note above. This makes
+cross-message threading much cleaner for the reporter and gives
+them a stable identifier to file the report under.</li>
+<li><strong>Public <code><upstream></code> PR descriptions and commit messages</strong> —
+<em>may</em> include the tracker URL as a cross-reference, <strong>so long as
+the surrounding text does not characterise the PR as a security
+fix</strong> (no CVE ID, no <em>“vulnerability”</em>, no <em>“security advisory”</em>
+framing). The URL alone is opaque to non-team viewers.</li>
+<li><strong>Public CVE records and archived advisories</strong> — the tracker URL
+may appear in <code>references[]</code> once the advisory ships. For
+records still in DRAFT / REVIEW state it stays internal-only.</li>
+<li><strong><code>gh issue comment</code> calls inside the tracker repository</strong> — fine,
+they land on private issues.</li>
+<li><strong><code><security-list></code> private mail threads</strong> — fine.</li>
+<li><strong><code><private-list></code> PMC escalation mails</strong> — fine.</li>
+</ul>
+</article></main><aside class="hidden xl:block w-60 flex-none border-l border-solid border-neutral-200 bg-default-background sticky top-0 h-screen overflow-y-auto px-5 py-12"><div class="mb-3 text-caption font-caption uppercase tracking-wider text-subtext-color">On this page</div><nav><ul class="flex flex-col gap-1.5"><li><a href="#sharing-a-tracker-url-with-someone-who-cannot-access-it" class="block text-caption font-caption text-subtext-color hover:text-brand-700" style="padding-left: [...]
+ (() => {
+ const nav = document.getElementById("docs-nav-scroll");
+ if (!nav) return;
+ for (const link of nav.querySelectorAll("summary a[href]")) {
+ link.addEventListener("click", (event) => {
+ const branch = link.closest("details");
+ if (!branch) return;
+ const plainClick =
+ event.button === 0 &&
+ !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;
+ if (plainClick) {
+ event.preventDefault();
+ branch.open = true;
+ window.location.href = link.href;
+ } else {
+ setTimeout(() => { branch.open = true; }, 0);
+ }
+ });
+ }
+ })();
+ </script><script>
+ (() => {
+ const scroller = document.getElementById("docs-nav-scroll");
+ const active = scroller?.querySelector('[aria-current="page"]');
+ if (!scroller || !active) return;
+ const target =
+ active.offsetTop - scroller.clientHeight / 2 + active.offsetHeight / 2;
+ scroller.scrollTop = Math.max(0, target);
+ })();
+ </script><a href="https://github.com/apache/magpie/edit/main/docs/confidentiality.md" target="_blank" rel="noopener noreferrer" class="suggest-change" aria-label="Suggest a change to this page on GitHub" data-astro-cid-z4jru4n3><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" data-astro-cid-z4jru4n3><path d="M12 20h9" data-astro-cid-z4jru4n3></path><path d="M16.5 3.5a2.12 [...]
\ No newline at end of file
diff --git a/docs/contributor-growth/readme.md b/docs/contributor-growth/readme.md
new file mode 100644
index 0000000..016df50
--- /dev/null
+++ b/docs/contributor-growth/readme.md
@@ -0,0 +1,214 @@
+# Contributor-growth skill family
+
+Rendered page: https://magpie.apache.org/docs/contributor-growth/readme/
+
+Source: https://github.com/apache/magpie/blob/main/docs/contributor-growth/README.md
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+> **Scope — `organization: ASF` · 🪶 ASF-specific.** This family encodes Apache Software
+> Foundation processes (the contributor-to-committer path) and assumes an ASF
+> adopter profile by default. Non-ASF projects can still adopt it through the
+> adapter/config layer, but it carries ASF assumptions the generic families do not.
+
+Maintainer-facing skills that span the contributor-to-committer path:
+welcoming first-time contributors, keeping the issue backlog newcomer-
+ready, tracking contribution activity, checking readiness against declared
+thresholds, measuring contributor sentiment, assembling nomination evidence,
+and walking nominators through post-vote onboarding. Nine skills cover the staged path from first contact
+through committer promotion.
+
+Why a framework skill family? The contributor-to-committer path is one
+of the highest-leverage levers an open-source project has for long-term
+health — lowering onboarding friction and shortening the time from first
+PR to committer status keeps the contributor pipeline healthy. These
+skills were designed independently but cover a contiguous path; grouping
+them makes the adopter configuration and the evaluation story coherent.
+
+> [!TIP]
+> **Why this family**
+> - A nomination brief built from a year of evidence rather than a recent impression
+> - The post-vote checklist, from ICLA to welcome mail, with the steps that need a PMC chair marked
+> - It names what GitHub cannot see — mailing lists, release votes, mentoring — instead of quietly scoring without them
+
+## Install & first runs
+
+Install just this family — one plugin, 6 skills. The path-to-committer track.
+
+Once you have [added the marketplace](/docs/setup/marketplace-install):
+
+```text
+/plugin install magpie-contributor-growth@apache-magpie
+```
+
+New to Magpie? The [quick start](/docs/quick-start) walks the whole path in
+one place — install, the first `/magpie-setup` run, and a recording of it
+happening — plus the other agents and the secure-isolation setup to run next.
+
+### Before the first run
+
+<!-- BEGIN generated: skill-config (tools/dev/check-skill-config.py --fix) -->
+
+
... 131780 lines suppressed ...