book-installer

name	book-installer
description	Installs and configures project infrastructure including MkDocs Material intelligent textbook templates, learning graph viewers, and skill tracking systems. Routes to the appropriate installation guide based on what the user needs to set up.

Book Installer

Overview

This meta-skill handles installation and setup tasks for intelligent textbook projects. It consolidates three installation skills into a single entry point with on-demand loading of specific installation guides.

When to Use This Skill

Use this skill when users request:

• Setting up a new MkDocs Material project
• Creating a new intelligent textbook from scratch
• Installing a learning graph viewer
• Setting up skill usage tracking with hooks
• Bootstrapping project infrastructure

Step 1: Handle Help Requests

If the user asks for "help", "what can you do", or "list features", display this numbered list directly (do not load a reference file):

Book Installer Features (most → least common):

 1. Simple mkdocs.yml template - Minimal starter config for new projects
 2. Site logo - Add custom logo to header
 3. Favicon - Browser tab/bookmark icon
 3b. Generate favicon from mascot - Auto-generate favicon.ico from neutral.png mascot image
 4. Cover image & social preview - Home page image + og:image metadata
 4b. Generate cover image - Auto-generate cover using AI (API or ChatGPT)
 4c. Social media preview hook - Inject og:* / twitter:* meta tags via MkDocs hook (no Cairo required)
 5. Math equations - KaTeX (recommended) or MathJax
 6. Code syntax highlighting - Language-aware code blocks
 7. Code copy button - One-click copy for code blocks
 8. Mermaid diagrams - Flowcharts, sequence diagrams from text
 9. Content tabs - Tabbed sections for alternatives
10. Image zoom (GLightbox) - Click to enlarge images
11. Custom admonitions - Prompt boxes with copy button
12. Interactive quizzes - Self-assessment questions
13. Abbreviations & tooltips - Glossary hover definitions
14. Task lists - Checkbox lists
15. Simple feedback - Thumbs up/down per page
16. Detailed comments (Giscus) - GitHub Discussions integration
17. Tags & categorization - Page tagging system
18. Search enhancements - Suggestions and highlighting
19. Table of contents config - TOC sidebar options
20. Blog support - Add blog section
21. Announcement bar - Dismissible top banner
22. Privacy & cookie consent - GDPR compliance
23. Learning graph viewer - Interactive concept visualization
24. Skill usage tracker - Claude Code analytics hooks
25. Google Analytics - requires a Google Analytics property ID G-*
26. .gitignore installer - make sure that `site` and `.cache` are not in the main branch
27. extra CSS installer for iframe and customer prompt admonition
28. extra JavaScript installer - for prompt admonition copy button
29. Feature checklist - auto-detect and document which features are implemented
30. Learning mascot - add a pedagogical agent character to guide students
31. Instructor's guide - comprehensive teacher's guide with classroom tips
32. Custom 404 page - friendly error page with mascot image
33. Document status indicators - colored dots in nav showing page lifecycle state
34. Kanban board - GitHub Projects board for tracking textbook development
35. Mascot chapter updater - retrofit existing chapters with mascot admonitions
36. About page - professional about.md with motivation, author bio, and citations
37. Slide generator - install slide-viewer MicroSim and generate slides.md decks for chapters
38. Reading level analysis - Flesch-Kincaid grade level report for all chapters

Type a number or feature name to install.

Note: If you see `navigation.tabs` in mkdocs.yml, remove it. These books
use side navigation optimized for wide landscape screens.

After displaying the list, wait for user to specify which feature they want.

---

Step 1b: Check for Navigation Tabs (Existing Projects)

When working with an existing mkdocs.yml, always check for and remove navigation tabs:

# REMOVE these lines if present in mkdocs.yml:
theme:
  features:
    - navigation.tabs        # DELETE
    - navigation.tabs.sticky # DELETE

These books use side navigation optimized for wide landscape screens. Top navigation tabs waste vertical space and are not appropriate for this format.

---

Step 2: Identify Installation Type

Match the user's request to the appropriate installation guide:

Routing Table

Trigger Keywords	Action	Purpose
help, what can you do, features, capabilities, list features	Display numbered list (Step 1)	Show quick feature overview
init textbook, scaffold textbook, brand new book, empty directory, fresh start	init-textbook skill (separate skill)	Bootstrap a brand-new textbook from scratch (mkdocs.yml + docs/ + license + contact) — run this before using book-installer features
1, simple mkdocs, minimal template, starter config	references/mkdocs-template.md (minimal section)	Create simple mkdocs.yml starter
enrich, add feature, number 2-24, specific feature name	references/mkdocs-features.md	Install specific feature
new project, mkdocs, textbook, bootstrap, setup, template, new book	references/mkdocs-template.md	Create new MkDocs Material project
graph viewer, learning graph, visualization, interactive graph, concept viewer	references/learning-graph-viewer.md	Add learning graph viewer to existing project
track skills, skill usage, activity tracking, hooks, usage analytics	references/skill-tracker.md	Set up skill tracking with hooks
generate cover, generate cover image, auto cover, create cover image, run cover script	references/cover-image-generator.md	Auto-generate cover image using AI (guides through API/ChatGPT options)
cover image, home page, montage, book cover, index page	references/home-page-template.md	Create home page with cover image and social metadata
social media preview, social card, social meta, og:image, og:title, og:description, open graph, twitter card, twitter image, linkedin preview, slack unfurl, bk-check-social-cover, social hook, social override	references/social-media-preview.md	Install the Cairo-free hook that injects og:* and twitter:* meta tags on every page
logo, site logo, branding, upper left, header icon	references/mkdocs-features.md	Add custom logo with AI prompt examples
favicon, browser tab, bookmark icon, .ico	references/mkdocs-features.md	Add favicon with AI prompt examples
generate favicon, favicon from mascot, mascot favicon, favicon.ico from png, create favicon	references/favicon-generator.md	Generate favicon.ico from neutral.png mascot using Python
math, equations, latex, mathjax, katex	references/mkdocs-features.md	Add math equation support
feature checklist, generate feature checklist, feature status, what features	references/feature-checklist-generator.md	Auto-detect and document implemented features
quiz, quizzes, assessment, multiple choice	references/mkdocs-features.md	Add interactive quizzes
feedback, thumbs up, thumbs down, was this helpful	references/mkdocs-features.md	Add page feedback widget
comments, giscus, discussions	references/mkdocs-features.md	Add comment system
image zoom, lightbox, glightbox, click to enlarge	references/mkdocs-features.md	Add image zoom on click
code highlighting, syntax, copy button	references/mkdocs-features.md	Add code syntax highlighting
mermaid, diagrams, flowchart	references/mkdocs-features.md	Add Mermaid diagram support
admonition, callout, prompt box, copy prompt	references/mkdocs-features.md	Add custom admonitions with copy
mascot, learning mascot, pedagogical agent, character, guide character, persona	references/learning-mascot.md	Add a learning mascot to guide students
instructor guide, teacher guide, teachers guide, instructor's guide, classroom guide	references/instructors-guide.md	Generate comprehensive instructor's guide
404, error page, not found, custom 404, page not found	references/custom-404-page.md	Add custom 404 page with mascot
document status, page status, status indicators, status dots, nav status, page lifecycle, review workflow	references/document-status.md	Add colored status dots to nav sidebar
kanban, project board, kanban board, project management, github project, task board, milestones, 34	references/kanban-board.md	Create GitHub Projects Kanban board for textbook development
mascot chapter, update chapter, retrofit mascot, place mascot, add mascot to chapter, mascot placement, 35	references/mascot-chapter-updater.md	Retrofit an existing chapter with mascot admonitions using placement rules
about page, about, about.md, about this book, author bio, cite this book, citation, 36	references/about-page.md	Generate professional about page with motivation, bio, and citations
slide generator, slides, slide deck, slide viewer, presentation, generate slides, install slide viewer, 37	references/slide-generator.md	Install the slide-viewer MicroSim and generate slides.md decks for chapters
reading level, readability, flesch kincaid, grade level, reading analysis, 38	references/reading-level-analysis.md	Analyze chapter reading level consistency

Decision Tree

Asking for help or what book-installer can do?
  → YES: Display numbered list directly (Step 1)

Creating a new project/textbook from scratch?
  → YES: mkdocs-template.md

Adding a learning graph viewer to existing project?
  → YES: learning-graph-viewer.md

Setting up skill usage tracking?
  → YES: skill-tracker.md

Want to GENERATE a cover image automatically using AI?
  → YES: cover-image-generator.md (guides through API vs ChatGPT options)

Creating a cover image MANUALLY or setting up home page with social metadata?
  → YES: home-page-template.md

Installing the social media preview hook (og:* / twitter:* meta tags) or
fixing a failing bk-check-social-cover run?
  → YES: social-media-preview.md (Cairo-free; this is the default approach)

Want to generate a feature checklist showing what's implemented?
  → YES: feature-checklist-generator.md

Want to GENERATE a favicon.ico automatically from the mascot's neutral.png?
  → YES: favicon-generator.md (runs scripts/generate-favicon.py via Python/Pillow)

Want to add branding (logo, favicon, cover image)?
  → YES: mkdocs-features.md (Branding Features section)

Want to add a learning mascot (pedagogical agent) to guide students?
  → YES: learning-mascot.md

Want to generate an instructor's/teacher's guide?
  → YES: instructors-guide.md

Want a custom 404 error page with the mascot?
  → YES: custom-404-page.md

Want to add colored status dots to the nav sidebar for page lifecycle tracking?
  → YES: document-status.md

Want a GitHub Projects Kanban board to track textbook development?
  → YES: kanban-board.md

Want to retrofit an existing chapter with mascot admonitions?
  → YES: mascot-chapter-updater.md

Want to generate a professional about page with author bio and citations?
  → YES: about-page.md

Want to install a slide viewer and generate slide decks for chapters?
  → YES: slide-generator.md

Want to analyze reading level consistency across chapters?
  → YES: reading-level-analysis.md

Want to add a specific feature (equations, quizzes, feedback, etc.)?
  → YES: mkdocs-features.md (then follow specific feature instructions)

Step 2: Load the Matched Guide

Read the corresponding guide file from references/ and follow its installation workflow.

Step 3: Execute Installation

Each guide contains:

1. Prerequisites and requirements
2. Step-by-step installation commands
3. Configuration options
4. Verification steps
5. Troubleshooting tips

Available Installation Guides

mkdocs-features.md

Purpose: Detailed configuration for all MkDocs feature enhancements

Contains: Full configuration snippets for features 2-24 listed in the help output, including:

• YAML for mkdocs.yml
• JavaScript files to create
• CSS files to create
• Usage examples

Use when:

• User selects a feature by number or name
• User wants detailed configuration for a specific feature
• User has a minimal mkdocs.yml and wants to enrich it

mkdocs-template.md

Purpose: Bootstrap a complete MkDocs Material intelligent textbook project

Creates:

• Conda virtual environment named 'mkdocs'
• Full MkDocs Material project structure
• Custom CSS for branding
• Social media card plugins
• GitHub Pages deployment configuration
• URI scheme in extra section for global discoverability

URI Scheme: New projects automatically include the textbook schema in mkdocs.yml:

extra:
  schema: https://dmccreary.github.io/intelligent-textbooks/ns/textbook/v1

See the URI Scheme documentation for details.

Prerequisites:

• Conda installed
• Git installed
• GitHub repository created

learning-graph-viewer.md

Purpose: Add interactive learning graph exploration to existing textbook

Creates:

• Interactive vis-network graph viewer
• Search, filtering, and statistics features
• Integration with existing learning-graph.json

Prerequisites:

• Existing MkDocs project
• learning-graph.json file present

skill-tracker.md

Purpose: Set up Claude Code skill usage tracking

Creates:

• Hook scripts for tracking skill invocations
• Activity log directory structure
• Reporting scripts for usage analysis

Prerequisites:

• Claude Code installed
• ~/.claude directory exists

social-media-preview.md

Purpose: Install a Cairo-free MkDocs hook that emits Open Graph and Twitter Card meta tags on every page

Creates:

• plugins/social_override.py — on_post_page hook that injects/replaces og:title, og:description, og:image, og:type, og:url, and twitter:* tags
• hooks: block in mkdocs.yml referencing the new file

Features:

• Reads image:, title:, description: from each page's frontmatter; falls back to img/cover.png and the site-wide values
• Emits absolute og:image URLs by joining site_url with the image path (so crawlers and bk-check-social-cover can HEAD-request them)
• Works without mkdocs-material[imaging] / Cairo — the common-case default
• Compatible with the full social plugin when Cairo is present: replaces its auto-generated /assets/images/social/... URLs with the declared cover.png
• Verified via ~/.local/bin/bk-check-social-cover (which enforces og:image basename = cover.png and image reachability)

Prerequisites:

• Existing MkDocs Material project with site_url: set
• docs/img/cover.png (use cover-image-generator.md or home-page-template.md first if missing)
• Home page frontmatter with title: and description: (typically from home-page-template.md)

home-page-template.md

Purpose: Create professional home page with cover image and social media optimization

Creates:

• docs/index.md with proper frontmatter metadata
• AI image generation prompts for cover with montage background
• Open Graph and Twitter Card configuration

Features:

• Cover image design guidance (1.91:1 aspect ratio)
• Montage element suggestions by topic
• Social media preview optimization
• Example prompts for various book themes

Prerequisites:

• Existing MkDocs project
• Access to AI image generator (DALL-E, Midjourney, etc.)

learning-mascot.md

Purpose: Design and implement a pedagogical agent (learning mascot) that guides students through the textbook

Creates:

• Character design (name, species, appearance, personality, catchphrase)
• AI image generation prompts for consistent mascot poses
• Implementation via inline images, custom CSS admonitions, or JavaScript auto-detection
• CLAUDE.md character guidelines for consistent AI-generated content

Features:

• Subject-specific mascot suggestions with reasoning
• Six standard pose variants (welcome, thinking, tip, warning, celebration, encouraging)
• Three implementation methods at different complexity levels
• Restraint guidelines to prevent overuse

Prerequisites:

• Existing MkDocs Material project
• Access to AI image generator (DALL-E, Midjourney, etc.)

instructors-guide.md

Purpose: Generate a comprehensive instructor's/teacher's guide for the textbook

Creates:

• docs/teachers-guide/index.md (or docs/instructors-guide/index.md for college-level)
• Navigation entry in mkdocs.yml

Features:

• Five levels of intelligent textbooks explained
• Detailed usage instructions for chapters, MicroSims, glossary, FAQ, quizzes, and references
• Classroom tips (before/during/after class suggestions, pacing)
• MicroSim iframe embedding guide for external LMS pages
• Creative Commons license explained in plain English (what you can/cannot do)
• Step-by-step customization guide (fork, clone, change colors/title/logo, deploy)
• Google Analytics setup instructions
• xAPI/LRS overview with FERPA/COPPA/GDPR regulatory warnings
• Learning graph usage tips for teachers
• Pedagogical agent (mascot) documentation (if mascot exists)
• All technical terms defined before use — no assumed prior knowledge

Prerequisites:

• Existing MkDocs Material project
• At least some chapter content written

custom-404-page.md

Purpose: Add a custom 404 error page featuring the project's learning mascot

Creates:

• overrides/404.html — Jinja2 template extending Material base theme with mascot image, friendly message, and home link
• mkdocs.yml updates for custom_dir and static_templates

Features:

• Uses the mascot's warning pose (or other pose) centered on the page
• Inherits full site navigation (header, sidebar, footer) from the Material theme
• Customizable message matched to the mascot's personality and voice
• Absolute image paths so the 404 works from any URL depth

Prerequisites:

• Existing MkDocs Material project
• Learning mascot images in docs/img/mascot/ (use learning-mascot.md first if needed)

document-status.md

Purpose: Add per-page colored status dots to the navigation sidebar for tracking page lifecycle state

Creates:

• extra.status configuration in mkdocs.yml
• CSS rules for colored status dots in extra.css
• status: frontmatter on individual pages

Features:

• Three-state workflow (spec-complete → prototype → ready-for-testing)
• Colored dots (red, orange, green) visible in the nav sidebar
• Tooltip text on hover
• Customizable status codes for any workflow

Prerequisites:

• Existing MkDocs Material project
• Custom CSS file referenced in extra_css

reading-level-analysis.md

Purpose: Analyze Flesch-Kincaid grade level consistency across all chapters

Creates:

• docs/learning-graph/chapter-reading-levels.md — per-chapter reading level report

Uses script: scripts/analyze-reading-levels.py

Features:

• Strips markdown/HTML formatting to analyze pure prose
• Per-chapter table with FK grade and explanatory notes
• Summary statistics (mean, median, range, standard deviation)
• Interpretation section explaining whether variation is meaningful
• Identifies vocabulary-driven score inflation vs. genuine difficulty differences

Prerequisites:

• Existing MkDocs project with chapters in docs/chapters/
• Python textstat library (pip install textstat)

favicon-generator.md

Purpose: Generate a web-compliant multi-resolution favicon.ico from the mascot's neutral.png

Creates:

• docs/img/favicon.ico — multi-resolution icon (16, 32, 48, 64, 128, 256 px) embedded in a single .ico file

Uses script: scripts/generate-favicon.py

How it works:

• Detects the bounding box of non-transparent pixels (trims invisible padding)
• Centers the visible content on a square canvas with configurable padding
• Downscales to each favicon size using Lanczos resampling
• Supports transparent or white background canvas

Prerequisites:

• Mascot image at docs/img/mascot/neutral.png (image need not be square)
• Python Pillow library (pip install Pillow)

cover-image-generator.md

Purpose: Auto-generate cover images using the generate-cover.sh script

Provides:

• Interactive questionnaire to determine best workflow
• Commands for API, ChatGPT Pro, or manual generation
• Troubleshooting for common issues

Workflows:

• Full Auto: OpenAI API with active billing (fastest)
• Browser Auto: ChatGPT Pro + macOS (opens browser, pastes prompt)
• Local Prompt: ChatGPT Pro, any OS (displays prompt for manual copy)
• Fallback: Free tier options with manual generation

Prerequisites:

• Existing MkDocs project with mkdocs.yml
• docs/course-description.md with book content description
• One of: OpenAI API billing, ChatGPT Pro subscription, or free AI image generator

kanban-board.md

Purpose: Create a GitHub Projects (v2) Kanban board for tracking textbook development progress

Creates:

• GitHub Projects board with Board (Kanban) layout
• Priority field (High / Medium / Low)
• 13 standard textbook milestone draft items
• docs/project-management.md with column documentation and workflow guide
• README section about the Kanban board

Features:

• Automated setup via gh project CLI commands
• Links project to the repository automatically
• Pre-populated milestones matching the 12-step textbook workflow
• Fallback instructions for manual setup if gh commands fail

Prerequisites:

• gh CLI installed and authenticated
• project scope on the GitHub token (gh auth refresh -s project)
• Existing MkDocs project with mkdocs.yml

slide-generator.md

Purpose: Install the slide-viewer MicroSim into an intelligent textbook project and generate presentation-style slides.md decks for specified chapters

Creates:

• docs/sims/slide-viewer/ — viewer shell (main.html, script.js, local.css, index.md) that fetches any rendered MkDocs page URL, splits its content on <hr> elements, and renders one slide at a time with keyboard + button navigation
• docs/chapters/<slug>/slides.md — per chapter: title slide, content slides separated by ---, retrieval check, bridge, celebration close
• Three-button nav bar (Content, Slides, Slides in Viewer) at the top of each chapter's index.md and its slides.md
• mkdocs.yml nav restructured so each chapter with slides has Content / Slides sub-entries

Features:

• Viewer reads MkDocs' rendered HTML (never raw .md — MkDocs doesn't serve .md directly)
• Mascot integration: neutral pose on every slide, celebration pose on the last slide (uses docs/img/mascot/neutral.png and celebration.png if present; silently absent otherwise)
• First/last-slide jump buttons, Home/End keys, fullscreen, table-of-contents overlay
• Distills chapter index.md into 15–28 slides following project voice/style rules

Prerequisites:

• Existing MkDocs Material project with docs/chapters/ populated
• Chapter index.md files with real content (not just scaffold) — guide checks line counts before generating
• Optional: mascot installed via learning-mascot.md

mascot-chapter-updater.md

Purpose: Retrofit an existing chapter markdown file with mascot admonitions in the right places, following the placement rules from learning-mascot.md

Creates:

• In-place edits to the specified chapter file only (no new files)
• A placement plan shown to the user for confirmation before editing

Features:

• LLM-driven workflow for semantic placement (no regex auto-insertion)
• Enforces hard limits: ≤6 admonitions per chapter, one welcome and one celebration maximum, no back-to-back placements
• Image-path guidance for directory-URL rendering (counts ../ from rendered page)
• Voice and body-text rules: 1-3 sentences, in-character, specific to chapter content
• Validation via scripts/validate-chapter-mascots.py that flags count limits, back-to-backs, missing <img> tags, and body-text length

Prerequisites:

• Mascot images present in docs/img/mascot/ or docs/img/mascots/
• docs/css/mascot.css loaded and the mascot-test page renders correctly
• Specific chapter file identified by absolute path

Examples

Example 1: Ask for Help

User: "book-installer help" Routing: Keyword "help" → Display numbered list Action: Show the numbered feature list (Step 1), then wait for user to select a feature

Example 2: Add a Specific Feature

User: "Add math equation support to my book" Routing: Keyword "math" → references/mkdocs-features.md Action: Load mkdocs-features.md, find the Math Equations section, and apply the configuration

Example 2b: Select by Number

User: "5" Routing: Number selection after help list → references/mkdocs-features.md Action: Load mkdocs-features.md, find Math Equations (item 5), and apply the configuration

Example 2c: Simple Template

User: "1" Routing: Number 1 → references/mkdocs-template.md (minimal section) Action: Load mkdocs-template.md and create a simple mkdocs.yml starter config

Example 3: New Textbook Project

User: "I want to create a new intelligent textbook about machine learning" Routing: Keywords "create", "new", "textbook" → references/mkdocs-template.md Action: Read mkdocs-template.md and follow its workflow

Example 4: Add Graph Viewer

User: "Add an interactive viewer for the learning graph" Routing: Keywords "viewer", "learning graph", "interactive" → references/learning-graph-viewer.md Action: Read learning-graph-viewer.md and follow its workflow

Example 5: Track Skill Usage

User: "I want to track which skills I use most often" Routing: Keywords "track", "skills", "usage" → references/skill-tracker.md Action: Read skill-tracker.md and follow its workflow

Example 6: Create Cover Image

User: "Help me create a cover image for my textbook" Routing: Keywords "cover image", "textbook" → references/home-page-template.md Action: Read home-page-template.md and follow its workflow

Example 7: Set Up Home Page with Social Sharing

User: "I need to add og:image metadata to my home page" Routing: Keywords "og:image", "home page" → references/home-page-template.md Action: Read home-page-template.md and follow its workflow

Example 8: Generate Cover Image Automatically

User: "generate cover image" or "book-installer generate cover image" Routing: Keywords "generate cover image" → references/cover-image-generator.md Action: Read cover-image-generator.md, ask user about their resources (API key, ChatGPT Pro, macOS), then run the appropriate generate-cover.sh command

Example 9: Add a Learning Mascot

User: "I want to add a mascot character to my math textbook" Routing: Keywords "mascot", "character" → references/learning-mascot.md Action: Read learning-mascot.md, guide user through character design, generate AI image prompts, and implement chosen method (inline, CSS admonitions, or JS detection)

Example 10: Generate Feature Checklist

User: "generate a feature checklist" or "what features do I have" Routing: Keywords "feature checklist" → references/feature-checklist-generator.md Action: Read feature-checklist-generator.md, run the detection script, generate docs/feature-checklist.md with detected statuses

Example 11: Generate Instructor's Guide

User: "add a teacher's guide" or "create instructor guide" Routing: Keywords "teacher guide", "instructor guide" → references/instructors-guide.md Action: Read instructors-guide.md, gather project variables from mkdocs.yml/course-description.md/CLAUDE.md, generate the guide with all variables substituted, add to navigation

Example 12: Create Kanban Board

User: "set up a kanban board for my textbook" or "create a project board" Routing: Keywords "kanban", "project board" → references/kanban-board.md Action: Read kanban-board.md, verify gh auth with project scope, create the GitHub Project, link to repo, populate milestones, create docs/project-management.md, update nav and README

Example 13: Generate About Page

User: "create an about page" or "add about.md with author bio and citations" Routing: Keywords "about page", "about", "author bio", "citation" → references/about-page.md Action: Read about-page.md, gather project variables from mkdocs.yml/course-description.md, generate docs/about.md with all sections (motivation, author bio, citation formats), add to navigation

Example 14: Add Mascots to an Existing Chapter

User: "add Sparky admonitions to chapter 2" or "place the mascot in docs/chapters/02-ohms-law/index.md" Routing: Keywords "mascot chapter", "place mascot", "add mascot to chapter" → references/mascot-chapter-updater.md Action: Read mascot-chapter-updater.md, survey the chapter, propose a placement plan with line numbers, wait for user confirmation, apply edits, run validate-chapter-mascots.py, and address any flags

Example 15: Generate Favicon from Mascot

User: "generate favicon from mascot" or "create favicon.ico from neutral.png" Routing: Keywords "generate favicon", "mascot favicon", "favicon from mascot" → references/favicon-generator.md Action: Read favicon-generator.md, verify docs/img/mascot/neutral.png exists and Pillow is installed, run scripts/generate-favicon.py from the project root, then update theme.favicon in mkdocs.yml to img/favicon.ico

Example 15b: Install Social Media Preview Hook

User: "add the social media preview mkdocs hook" or "my bk-check-social-cover is failing" or "install og:image meta tags" Routing: Keywords "social media preview", "og:image", "bk-check-social-cover", "social hook" → references/social-media-preview.md Action: Read social-media-preview.md, create plugins/social_override.py at the project root with the exact code in the reference, add a top-level hooks: - plugins/social_override.py block to mkdocs.yml, run mkdocs build, verify the nine og:* / twitter:* meta tags appear in site/index.html, then run bk-check-social-cover against either the deployed URL or a local server staging the build under /<project>/

Example 16: Install Slide Viewer and Generate Chapter Slides

User: "install the slide viewer and make slides for chapters 1 and 2" or "generate slides for chapter 3" Routing: Keywords "slide", "slides", "slide viewer", "generate slides", "slide deck" → references/slide-generator.md Action: Read slide-generator.md, copy the slide-viewer assets into docs/sims/slide-viewer/, ask which chapters to generate decks for, create slides.md for each (title + content slides separated by --- + retrieval check + bridge + celebration), add the three-button nav bar to each chapter's index.md, restructure the chapter's mkdocs.yml entry into Content/Slides sub-entries, and append deck links to the viewer's index.md

Common Workflows

Full Project Setup

For a complete new project, users typically run these installations in order:

1. mkdocs-template.md - Create the project structure
2. cover-image-generator.md - Auto-generate cover image using AI
3. home-page-template.md - Configure home page with cover image metadata
4. social-media-preview.md - Install the og:* / twitter:* meta-tag hook (verify with bk-check-social-cover)
5. learning-graph-viewer.md - Add graph visualization (after learning graph exists)
6. skill-tracker.md - Enable usage analytics (optional)

Verification Commands

After any installation, verify with:

# For MkDocs projects
mkdocs serve
# Visit http://127.0.0.1:8000/[project-name]/

# For skill tracker
cat ~/.claude/activity-logs/skill-usage.jsonl | tail -5