update-mascots

This skill keeps the book-mascots gallery in sync with sibling book/course projects under $HOME/Documents/ws/. It is project-local and assumes it is being run from inside $HOME/Documents/ws/book-mascots.

What it does

1. Lists existing mascots already in docs/mascots/.
2. Walks every sibling project in /Users/dan/Documents/ws/ looking for a mascot directory (commonly docs/img/mascot/, docs/mascots/, or docs/img/mascots/) that has at least 3 standard pose PNGs and a neutral.png (or *neutral.png).
3. For each sibling not already in the gallery:
   • Creates docs/mascots/<slug>/
   • Copies every *.png from the source mascot dir
   • Copies the source prompt file to docs/mascots/<slug>/image-prompts.md (looking in priority order: image-prompts.md, mascot-prompts.md, mascot-descriptions.md, README.md in the mascot dir; docs/prompts/*mascot*.md; docs/learning-graph/*mascot*guide*.md)
   • Generates docs/mascots/<slug>/index.md (a Material grid cards block, one card per pose PNG, emitted in canonical pose order — see Pose ordering below) — the page initially has only the title, the boilerplate "All poses for the X mascot." line, and the gallery; the descriptive intro paragraph is added in step 4 below.
4. Author a detailed intro paragraph for each newly-imported mascot. This step is a manual follow-up the agent (Claude) performs after the script finishes — the script cannot produce it because it requires subject-domain judgment (species symbolism, name etymology, biology metaphors, pedagogical fit). For every slug returned by the import step, edit docs/mascots/<slug>/index.md and insert a 4–6 sentence paragraph immediately after the # Title heading and before the All poses for the **X** mascot. line. See the Intro paragraph pattern section below for the required structure.
5. Regenerates docs/list-mascots.md from scratch by scanning docs/mascots/. Each card has the linked book title, the neutral image, and the mascot's character name (e.g. "Olli the Octopus") extracted from its prompt file.
6. Rewrites the Mascots: section of mkdocs.yml so the nav lists every mascot alphabetically by display title. The rest of the file is left alone.
7. Prints a summary: how many new mascots were imported (with slugs), the new total count, and any sibling projects that had a mascot dir but were skipped (e.g. missing neutral.png, fewer than 3 poses).

How to run it