Ch 14

▗ ▗ ▖ ▖ Claude Code v2.0.36 Sonnet 4.5 · Claude Pro ▘▘ ▝▝ /Users/danmccreary/Documents/ws/claude-skills

run the generate-chapter-content skill for docs/chapters/13-dev-tools-version-control-deployment/index.md Chapter 13 ⎿ Session limit reached ∙ resets 9pm /upgrade to increase your usage limit.

run the generate-chapter-content skill for docs/chapters/13-dev-tools-version-control-deployment/index.md Chapter 13

⏺ I'll run the chapter-content-generator skill for Chapter 13.

The "chapter-content-generator" skill is running

The "chapter-content-generator" skill is running

⏺ I'll generate comprehensive content for Chapter 13 on Development Tools, Version Control & Deployment. Let me start by following the workflow.

⏺ Read(docs/chapters/13-dev-tools-version-control-deployment/index.md) ⎿ Read 38 lines

⏺ Read(docs/course-description.md) ⎿ Read 121 lines

⏺ Read(~/.claude/skills/chapter-content-generator/references/reading-levels.md) ⎿ Read 245 lines

⏺ Read(~/.claude/skills/chapter-content-generator/references/content-element-types.md) ⎿ Read 595 lines

⏺ I have verified the chapter file and resources. I'll now generate comprehensive content for Chapter 13 at the college/professional level, covering all 10 concepts in pedagogical order.

⏺ Update(docs/chapters/13-dev-tools-version-control-deployment/index.md) ⎿ Updated docs/chapters/13-dev-tools-version-control-deployment/index.md with 1612 additions and 1 removal
34
35 --- 36
37 - TODO: Generate Chapter Content 37 + ## Introduction 38 +
39 + Creating intelligent textbooks requires mastery of professional development tools and workflows that streamline + content creation, version control, and deployment. This chapter introduces the essential development environment + used throughout the intelligent textbook creation process, focusing on Visual Studio Code as the primary content + authoring platform and Bash shell scripting for automation. 40 +
41 + Unlike traditional textbook authoring tools like Microsoft Word or Google Docs, intelligent textbook development + leverages software engineering practices including version control with Git, command-line workflows, and + automated deployment pipelines. These practices enable collaborative content development, reproducible builds, + and seamless publication to web platforms like GitHub Pages. 42 +
43 + By the end of this chapter, you'll work through a comprehensive capstone project that integrates all the skills, + tools, and workflows from previous chapters to create a complete intelligent textbook from concept to + deployment. 44 +
45 + ## Visual Studio Code 46 +
47 + Visual Studio Code (VS Code) is a free, open-source code editor developed by Microsoft that has become the de + facto standard for modern software development and technical content creation. While it was initially designed + for programming, its extensibility, integrated terminal, and markdown preview capabilities make it ideal for + intelligent textbook authoring. 48 +
49 + ### Why VS Code for Textbook Development? 50 +
51 + Traditional word processors are optimized for print documents with fixed page layouts, while intelligent + textbooks are dynamic, web-based resources built from markdown source files. VS Code provides several advantages + for this workflow: 52 +
53 + - Markdown editing with live preview: Real-time rendering of formatted content 54 + - Integrated Git support: Version control operations without leaving the editor 55 + - Built-in terminal: Execute MkDocs commands, Python scripts, and shell utilities 56 + - Extension ecosystem: Plugins for spell-checking, markdown linting, and diagram generation 57 + - Multi-file management: Navigate complex textbook structures with hundreds of files 58 + - Search and replace across files: Consistent terminology and formatting at scale 59 +
60 + ### Key Features for Content Creators 61 +
62 + The following features are particularly valuable for intelligent textbook development: 63 +
64 + - Explorer panel: Navigate chapter directories, MicroSim folders, and asset files 65 + - Search panel: Find all references to specific concepts across the entire textbook 66 + - Source control panel: Track changes, create commits, and push updates to GitHub 67 + - Extensions marketplace: Install tools like Markdown All in One, Code Spell Checker, and MkDocs plugins 68 + - Integrated terminal: Run mkdocs serve, execute Python scripts, and manage dependencies 69 + - Command palette (Cmd/Ctrl+Shift+P): Quick access to all VS Code functionality 70 +
71 +

72 +

VS Code Interface Layout for Textbook Development

73 + Type: diagram 74 +
75 + Purpose: Show the VS Code interface configured for intelligent textbook authoring 76 +
77 + Components to show: 78 + - Activity Bar (far left): Explorer, Search, Source Control, Extensions icons highlighted 79 + - Side Bar (left): Explorer panel showing typical textbook directory structure: 80 + /docs 81 + /chapters 82 + /01-intro-ai-intelligent-textbooks 83 + /02-getting-started-claude-skills 84 + (etc.) 85 + /sims 86 + /learning-graph 87 + mkdocs.yml 88 + - Editor Group (center): Split view showing: 89 + - Left pane: index.md file in edit mode with markdown content 90 + - Right pane: Markdown preview pane showing rendered content 91 + - Panel (bottom): Integrated terminal showing "mkdocs serve" command running 92 + - Status Bar (bottom): Git branch indicator, file type, cursor position 93 +
94 + Annotations: 95 + - Arrow pointing to Explorer: "Navigate textbook structure" 96 + - Arrow pointing to Split editor: "Edit and preview simultaneously" 97 + - Arrow pointing to Terminal: "Run MkDocs and Python scripts" 98 + - Arrow pointing to Source Control icon: "Track changes with Git" 99 +
100 + Visual style: Modern interface mockup with realistic VS Code color scheme (dark theme) 101 + Color scheme: VS Code Dark+ theme colors (dark gray background, syntax highlighting) 102 +
103 + Implementation: SVG diagram or annotated screenshot 104 +

105 +
106 + ### Installation and Setup 107 +
108 + VS Code can be downloaded from code.visualstudio.com for macOS, Windows, and + Linux. For intelligent textbook development, install these recommended extensions: 109 +
110 + | Extension | Purpose | Installation Command | 111 + |-----------|---------|---------------------| 112 + | Markdown All in One | Keyboard shortcuts, auto-preview, TOC generation |

code --install-extension 
            + yzhang.markdown-all-in-one

| 113 + | Code Spell Checker | Catch typos in markdown content |

code --install-extension 
            + streetsidesoftware.code-spell-checker

| 114 + | Markdown Preview Enhanced | Advanced preview with diagrams and export |

code --install-extension 
            + shd101wyy.markdown-preview-enhanced

| 115 + | Python | Syntax highlighting for Python scripts | code --install-extension ms-python.python | 116 +
117 + After installation, configure VS Code for optimal markdown editing by adding these settings to your user + settings (Cmd/Ctrl+,): 118 +
119 +

json
        120 +  {
        121 +    "editor.wordWrap": "on",
        122 +    "editor.formatOnSave": true,
        123 +    "markdown.preview.breaks": true,
        124 +    "files.trimTrailingWhitespace": true
        125 +  }
        126 +

127 +
128 + ## VS Code for Content Development 129 +
130 + While VS Code is a powerful general-purpose editor, intelligent textbook content development requires specific + workflows and practices that differ from traditional software development. This section covers techniques for + efficiently authoring markdown content, managing chapter files, and integrating with the MkDocs build system. 131 +
132 + ### Content Authoring Workflow 133 +
134 + A typical content development session follows this pattern: 135 +
136 + 1. Open the project folder: Use File → Open Folder to load the entire textbook repository 137 + 2. Start the development server: Open integrated terminal and run mkdocs serve 138 + 3. Navigate to target chapter: Use Explorer panel to locate the chapter's index.md file 139 + 4. Edit in split view: Open markdown preview (Cmd/Ctrl+K V) to see rendered output 140 + 5. Save frequently: VS Code auto-saves, but Cmd/Ctrl+S forces immediate update 141 + 6. Preview in browser: Navigate to http://localhost:8000 to see the full site 142 +
143 + This workflow enables rapid iteration, where changes to markdown files are immediately reflected in the browser + preview within 1-2 seconds of saving. 144 +
145 + ### Multi-File Editing Techniques 146 +
147 + Intelligent textbooks often require editing multiple files simultaneously—for example, updating a concept + definition in the glossary while editing chapter content. VS Code provides several techniques for efficient + multi-file editing: 148 +
149 + - Split editor groups: Drag tabs to create side-by-side or stacked editor layouts 150 + - Quick Open (Cmd/Ctrl+P): Type partial filename to instantly open any file 151 + - Go to Symbol (Cmd/Ctrl+Shift+O): Navigate to specific headers within long markdown files 152 + - Breadcrumbs: Show file path and document structure at top of editor 153 + - Tab groups: Organize related files (e.g., all Chapter 3 materials) in separate tab groups 154 +
155 + For complex editing tasks like renaming a concept across all chapters, use VS Code's search and replace across + files feature: 156 +
157 + - Open Search panel (Cmd/Ctrl+Shift+F) 158 + - Enter search term: "Configuration Item (CI)" 159 + - Enter replacement: "Configuration Item" 160 + - Review matches in context 161 + - Replace All to update all instances 162 +
163 + ### Markdown Productivity Tips 164 +
165 + The following keyboard shortcuts and features accelerate markdown authoring: 166 +
167 + - Cmd/Ctrl+B: Toggle bold formatting on selected text 168 + - Cmd/Ctrl+I: Toggle italic formatting 169 + - Cmd/Ctrl+Shift+V: Open markdown preview in new tab 170 + - Cmd/Ctrl+K V: Open preview to the side 171 + - Alt+Shift+F: Auto-format current markdown file 172 + - Cmd/Ctrl+/: Toggle comment on selected lines (useful for temporary removal) 173 +
174 + The Markdown All in One extension adds additional shortcuts: 175 +
176 + - Cmd/Ctrl+Shift+]: Insert/update table of contents 177 + - Alt+C: Check/uncheck task list items 178 + - Ctrl+Shift+[: Decrease heading level 179 + - Ctrl+Shift+]: Increase heading level 180 +
181 + ## Terminal in VS Code 182 +
183 + The integrated terminal in VS Code eliminates context switching between the editor and a separate terminal + application, enabling seamless execution of build commands, Python scripts, and Git operations. This integration + is particularly valuable for intelligent textbook workflows where content editing and script execution are + tightly coupled. 184 +
185 + ### Accessing the Integrated Terminal 186 +
187 + The terminal can be opened in several ways: 188 +
189 + - Keyboard shortcut: Ctrl+

(backtick) toggles terminal visibility
        190 +  - **Menu:** View → Terminal
        191 +  - **Command Palette:** Cmd/Ctrl+Shift+P, then type "Terminal: Create New Integrated Terminal"
        192 +  
        193 +  By default, the terminal appears in the Panel area at the bottom of the VS Code window, but it can be moved to 
            + the side or floated as a separate panel.
        194 +  
        195 +  ### Terminal Features for Textbook Development
        196 +  
        197 +  The integrated terminal provides several advantages over standalone terminal applications:
        198 +  
        199 +  - **Automatic working directory:** Terminal opens in the project root directory
        200 +  - **Output linking:** Click file paths in error messages to jump to that file
        201 +  - **Split terminals:** Run multiple commands simultaneously (e.g.,

mkdocs serve

in one, Python scripts in 
            + another)
        202 +  - **Command history:** Use up/down arrows to recall previous commands
        203 +  - **Copy/paste integration:** Cmd/Ctrl+C/V work as expected (no special terminal shortcuts needed)
        204 +  
        205 +  ### Common Terminal Commands for Textbook Projects
        206 +  
        207 +  The following commands are executed frequently during intelligent textbook development:
        208 +  
        209 +  | Command | Purpose | Typical Output |
        210 +  |---------|---------|----------------|
        211 +  |

mkdocs serve| Start local development server |Serving on http://127.0.0.1:8000

|
        212 +  |

mkdocs build --strict| Build site and fail on warnings |INFO - Building documentation...

|
        213 +  |

python docs/learning-graph/analyze-graph.py| Validate learning graph structure |Quality score: 87/100

|
        214 +  |

./scripts/list-skills.sh| List available Claude skills |Available skills: glossary-generator, + quiz-generator...

|
        215 +  |

git status| Check current repository state |On branch main, nothing to commit

|
        216 +  |

git add . && git commit -m "message"| Stage and commit changes |[main abc1234] message

|
        217 +  
        218 +  ### Managing Multiple Terminal Sessions
        219 +  
        220 +  Complex workflows often require multiple simultaneous terminal sessions. VS Code supports this through terminal 
            + splitting and tabs:
        221 +  
        222 +  - **Create new terminal:** Click + icon in terminal toolbar
        223 +  - **Split terminal:** Click split icon to create side-by-side terminals
        224 +  - **Rename terminal:** Right-click terminal tab, select "Rename"
        225 +  - **Kill terminal:** Click trash icon or exit the shell process
        226 +  
        227 +  A typical intelligent textbook development session might maintain three terminal sessions:
        228 +  
        229 +  1. **Development server terminal:** Running

mkdocs serve

continuously
        230 +  2. **Script execution terminal:** For running Python analysis scripts and skill invocations
        231 +  3. **Git operations terminal:** For staging commits and pushing changes
        232 +  
        233 +  <details markdown="1">
        234 +      <summary>Terminal Workflow for Textbook Development</summary>
        235 +      Type: workflow
        236 +  
        237 +      Purpose: Illustrate the typical terminal command sequence for developing and deploying textbook content
        238 +  
        239 +      Visual style: Flowchart with terminal command boxes and decision points
        240 +  
        241 +      Steps:
        242 +      1. Start: "Open project in VS Code"
        243 +         Hover text: "File → Open Folder, select textbook repository"
        244 +  
        245 +      2. Process: "Open integrated terminal (Ctrl+

)" 246 + Hover text: "Terminal opens in project root directory" 247 +
248 + 3. Process: "mkdocs serve" 249 + Hover text: "Starts development server on localhost:8000" 250 +
251 + 4. Decision: "Need to run Python scripts?" 252 + Hover text: "Learning graph analysis, content generation, etc." 253 +
254 + 5a. Process: "Create new terminal (+)" 255 + Hover text: "Keep mkdocs serve running in first terminal" 256 +
257 + 5b. Continue to step 6 258 +
259 + 6. Process: "Edit markdown files" 260 + Hover text: "Changes auto-reload in browser within 1-2 seconds" 261 +
262 + 7. Process: "python docs/learning-graph/analyze-graph.py" 263 + Hover text: "Validate learning graph quality and structure" 264 +
265 + 8. Decision: "Quality check passed?" 266 + Hover text: "Review quality-metrics.md for issues" 267 +
268 + 9a. Process: "Fix identified issues" 269 + Hover text: "Edit learning-graph.csv, re-run analysis" 270 + Returns to step 6 271 +
272 + 9b. Continue to step 10 273 +
274 + 10. Process: "git add . && git commit -m 'message'" 275 + Hover text: "Stage all changes and create commit" 276 +
277 + 11. Process: "git push origin main" 278 + Hover text: "Push commits to GitHub repository" 279 +
280 + 12. Process: "mkdocs gh-deploy" 281 + Hover text: "Build site and deploy to GitHub Pages" 282 +
283 + 13. End: "Textbook published" 284 + Hover text: "Changes live at https://username.github.io/textbook-name" 285 +
286 + Color coding: 287 + - Blue: Terminal commands 288 + - Yellow: Decision points 289 + - Green: Git operations 290 + - Orange: Deployment steps 291 +
292 + Swimlanes: 293 + - Terminal 1 (Development Server) 294 + - Terminal 2 (Script Execution) 295 + - Terminal 3 (Git Operations) 296 +
297 + Implementation: SVG flowchart with interactive hover states (HTML/CSS/JavaScript) 298 + 299 +
300 + ## Bash 301 +
302 + Bash (Bourne Again Shell) is the default command-line shell on macOS and most Linux distributions, providing a + text-based interface for executing commands, running scripts, and automating workflows. While Windows uses + PowerShell by default, Windows Subsystem for Linux (WSL) provides access to Bash on Windows systems. 303 +
304 + Understanding Bash is essential for intelligent textbook development because the MkDocs build system, Python + script execution, Git version control, and deployment automation all rely on command-line operations. 305 +
306 + ### Shell vs. Terminal vs. Bash 307 +
308 + These terms are often used interchangeably but have distinct meanings: 309 +
310 + - Terminal: The application that provides a text interface (e.g., Terminal.app on macOS, Windows Terminal) 311 + - Shell: The program that interprets commands (e.g., Bash, Zsh, Fish, PowerShell) 312 + - Bash: A specific shell implementation, currently the most widely used on Unix-like systems 313 +
314 + When you open the integrated terminal in VS Code, you're opening a terminal application that runs a shell + (typically Bash or Zsh on macOS/Linux, PowerShell on Windows). 315 +
316 + ### Bash Command Structure 317 +
318 + Bash commands follow a consistent structure: 319 +
320 +

bash
        321 +  command [options] [arguments]
        322 +

323 +
324 + For example, the command ls -la /docs/chapters breaks down as: 325 +
326 + - Command: ls (list directory contents) 327 + - Options: -la (long format, show hidden files) 328 + - Arguments: /docs/chapters (directory to list) 329 +
330 + Options typically start with - (single dash) for short options or -- (double dash) for long options. + Multiple short options can be combined: -l -a is equivalent to -la. 331 +
332 + ### Essential Bash Commands for Textbook Development 333 +
334 + The following commands are used frequently in intelligent textbook workflows: 335 +
336 + | Command | Purpose | Example | 337 + |---------|---------|---------| 338 + | pwd | Print working directory | pwd → /Users/username/textbook-project | 339 + | ls | List directory contents | ls -la docs/chapters | 340 + | cd | Change directory | cd docs/chapters/01-intro | 341 + | mkdir | Create directory | mkdir docs/sims/new-microsim | 342 + | touch | Create empty file | touch docs/chapters/05-graphs/index.md | 343 + | cp | Copy files | cp template.md chapter-03.md | 344 + | mv | Move/rename files | mv old-name.md new-name.md | 345 + | rm | Remove files | rm docs/chapters/draft.md | 346 + | cat | Display file contents | cat mkdocs.yml | 347 + | grep | Search text | grep "learning graph" docs/**/*.md | 348 + | chmod | Change file permissions | chmod +x scripts/install-skills.sh | 349 + | ln | Create symbolic link | ln -s ~/.claude/skills/glossary-generator ./ | 350 +
351 + ### Bash Environment and Variables 352 +
353 + Bash maintains environment variables that configure shell behavior and store system information. Common + variables include: 354 +
355 + - $HOME: User's home directory (e.g., /Users/username) 356 + - $PATH: Directories searched for executable commands 357 + - $PWD: Current working directory 358 + - $USER: Current username 359 +
360 + You can display variable values using echo: 361 +
362 +

bash
        363 +  echo $HOME      # /Users/username
        364 +  echo $PATH      # /usr/local/bin:/usr/bin:/bin
        365 +  echo $PWD       # /Users/username/textbook-project
        366 +

367 +
368 + ### Command Chaining and Redirection 369 +
370 + Bash allows combining multiple commands using operators: 371 +
372 + - Sequential execution (;): Run commands one after another regardless of success 373 +

bash
        374 +    cd docs/learning-graph; python analyze-graph.py learning-graph.csv quality-metrics.md
        375 +

376 +
377 + - Conditional execution (&&): Run second command only if first succeeds 378 +

bash
        379 +    mkdocs build --strict && mkdocs gh-deploy
        380 +

381 +
382 + - Output redirection (>): Save command output to file 383 +

bash
        384 +    python analyze-graph.py learning-graph.csv > quality-report.txt
        385 +

386 +
387 + - Append to file (>>): Add command output to end of existing file 388 +

bash
        389 +    echo "Quality check completed" >> build-log.txt
        390 +

391 +
392 + - Pipe (|): Send output of one command as input to another 393 +

bash
        394 +    ls -la | grep ".md"     # List only markdown files
        395 +

396 +
397 + ## Directory Navigation 398 +
399 + Efficient directory navigation is fundamental to command-line workflows, enabling quick access to chapter files, + MicroSim directories, Python scripts, and configuration files. While graphical file browsers are intuitive, + command-line navigation is often faster for developers who have memorized their project structure. 400 +
401 + ### Understanding File Paths 402 +
403 + File paths specify the location of files and directories in the filesystem hierarchy. There are two types of + paths: 404 +
405 + - Absolute paths: Start from the root directory (/ on Unix, C:\ on Windows) 406 +

bash
        407 +    /Users/username/Documents/textbook-project/docs/chapters/01-intro/index.md
        408 +

409 +
410 + - Relative paths: Start from the current working directory 411 +

bash
        412 +    # If current directory is /Users/username/Documents/textbook-project
        413 +    docs/chapters/01-intro/index.md
        414 +

415 +
416 + Special directory references: 417 +
418 + - . (single dot): Current directory 419 + - .. (double dot): Parent directory 420 + - ~ (tilde): User's home directory 421 + - - (dash): Previous working directory 422 +
423 + ### Navigating the Filesystem 424 +
425 + The cd (change directory) command moves between directories: 426 +
427 +

bash
        428 +  # Navigate to home directory
        429 +  cd ~
        430 +  
        431 +  # Navigate to specific project directory
        432 +  cd ~/Documents/textbook-project
        433 +  
        434 +  # Navigate to subdirectory (relative path)
        435 +  cd docs/chapters
        436 +  
        437 +  # Go up one level to parent directory
        438 +  cd ..
        439 +  
        440 +  # Go up two levels
        441 +  cd ../..
        442 +  
        443 +  # Return to previous directory
        444 +  cd -
        445 +  
        446 +  # Navigate to root directory
        447 +  cd /
        448 +

449 +
450 + ### Intelligent Textbook Directory Structure 451 +
452 + A typical intelligent textbook project has this structure: 453 +
454 +

455 +  textbook-project/
        456 +  ├── docs/
        457 +  │   ├── chapters/
        458 +  │   │   ├── 01-intro-ai-intelligent-textbooks/
        459 +  │   │   │   └── index.md
        460 +  │   │   ├── 02-getting-started-claude-skills/
        461 +  │   │   │   └── index.md
        462 +  │   │   └── (more chapters...)
        463 +  │   ├── sims/
        464 +  │   │   ├── graph-traversal/
        465 +  │   │   │   ├── main.html
        466 +  │   │   │   └── index.md
        467 +  │   │   └── (more MicroSims...)
        468 +  │   ├── learning-graph/
        469 +  │   │   ├── learning-graph.csv
        470 +  │   │   ├── learning-graph.json
        471 +  │   │   ├── analyze-graph.py
        472 +  │   │   └── quality-metrics.md
        473 +  │   ├── glossary.md
        474 +  │   ├── faq.md
        475 +  │   └── index.md
        476 +  ├── scripts/
        477 +  │   ├── install-claude-skills.sh
        478 +  │   └── list-skills.sh
        479 +  ├── .claude/
        480 +  │   ├── skills/
        481 +  │   └── commands/
        482 +  ├── mkdocs.yml
        483 +  ├── README.md
        484 +  └── requirements.txt
        485 +

486 +
487 + ### Navigation Best Practices 488 +
489 + Efficient navigation requires understanding project structure and using shortcuts: 490 +
491 + - Use tab completion: Type first few characters and press Tab to autocomplete 492 +

bash
        493 +    cd docs/ch<Tab>     # Autocompletes to docs/chapters/
        494 +

495 +
496 + - Use wildcards for pattern matching: 497 +

bash
        498 +    ls docs/chapters/*/index.md     # List all chapter index files
        499 +

500 +
501 + - Create shell aliases for frequent destinations: 502 +

bash
        503 +    alias chapters="cd ~/Documents/textbook-project/docs/chapters"
        504 +    alias sims="cd ~/Documents/textbook-project/docs/sims"
        505 +

506 +
507 + - Use pushd and popd for temporary directory changes: 508 +

bash
        509 +    pushd docs/learning-graph    # Navigate and save previous location
        510 +    python analyze-graph.py learning-graph.csv quality-metrics.md
        511 +    popd                         # Return to previous location
        512 +

513 +
514 +

515 +

Interactive Directory Navigation Practice MicroSim

516 + Type: microsim 517 +
518 + Learning objective: Practice Bash directory navigation commands in a simulated filesystem without risk of + breaking a real project 519 +
520 + Canvas layout (900x700px): 521 + - Left side (550x700): Simulated terminal interface showing: 522 + - Current working directory display at top 523 + - Command input field 524 + - Command output area 525 + - Command history (last 5 commands) 526 + - Right side (350x700): Visual filesystem tree showing: 527 + - Root directory 528 + - Expandable/collapsible directories 529 + - Current location highlighted in yellow 530 + - Files shown as leaf nodes 531 +
532 + Visual elements: 533 + - Terminal with black background, green text (retro style) 534 + - Filesystem tree with folder icons (📁) and file icons (📄) 535 + - Current directory highlighted with yellow background 536 + - Valid commands show success in green, errors in red 537 + - Breadcrumb trail showing path to current location 538 +
539 + Simulated filesystem structure: 540 +

541 +      /home/student/
        542 +      ├── textbook-project/
        543 +      │   ├── docs/
        544 +      │   │   ├── chapters/
        545 +      │   │   │   ├── 01-intro/
        546 +      │   │   │   │   └── index.md
        547 +      │   │   │   └── 02-graphs/
        548 +      │   │   │       └── index.md
        549 +      │   │   ├── sims/
        550 +      │   │   │   └── graph-viz/
        551 +      │   │   │       └── main.html
        552 +      │   │   └── learning-graph/
        553 +      │   │       ├── learning-graph.csv
        554 +      │   │       └── analyze-graph.py
        555 +      │   ├── scripts/
        556 +      │   │   └── install-skills.sh
        557 +      │   └── mkdocs.yml
        558 +      └── Downloads/
        559 +          └── readme.txt
        560 +

561 +
562 + Interactive controls (right panel): 563 + - Display: Current working directory (e.g., "/home/student") 564 + - Text input: Command entry field 565 + - Button: "Execute Command" 566 + - Button: "Clear Terminal" 567 + - Button: "Reset to Home" 568 + - Checkbox: "Show hidden files" 569 + - Display: Challenge progress (5 challenges) 570 +
571 + Supported commands: 572 + - pwd: Display current directory 573 + - ls: List current directory contents 574 + - ls -la: List with details 575 + - cd <directory>: Change to specified directory 576 + - cd ..: Go to parent directory 577 + - cd ~: Go to home directory 578 + - cd -: Go to previous directory 579 +
580 + Default parameters: 581 + - Starting directory: /home/student 582 + - Challenge mode: Enabled 583 + - Show hints: True 584 +
585 + Challenges (progressively harder): 586 + 1. "Navigate to the textbook-project directory" 587 + Solution: cd textbook-project 588 + 2. "List the contents of the docs directory without changing into it" 589 + Solution: ls docs 590 + 3. "Navigate to the chapters directory using a relative path" 591 + Solution: cd docs/chapters 592 + 4. "Navigate to the scripts directory from chapters" 593 + Solution: cd ../../scripts 594 + 5. "Return to the previous directory using the dash shortcut" 595 + Solution: cd - 596 +
597 + Behavior: 598 + - When user enters command, parse and validate it 599 + - If valid, update current directory and filesystem tree highlight 600 + - Display command output in terminal area 601 + - Show error message for invalid commands 602 + - Track challenge completion (green checkmark when solved) 603 + - Provide hint button that shows first step of current challenge 604 +
605 + Interactive features: 606 + - Click directories in tree view to highlight them (doesn't navigate) 607 + - Hover over directories shows full path 608 + - Right-click file/directory shows properties (size, permissions) 609 + - Double-click directory in tree auto-fills cd command 610 +
611 + Feedback: 612 + - Success messages: "✓ Navigated to /home/student/textbook-project" 613 + - Error messages: "✗ Directory not found: 'doc' (did you mean 'docs'?)" 614 + - Challenge completion: "🎉 Challenge 1 complete! (4 remaining)" 615 + - Hints: "💡 Hint: Try using 'cd' followed by the directory name" 616 +
617 + Implementation notes: 618 + - Use p5.js for rendering 619 + - Store filesystem as nested JavaScript object 620 + - Track current working directory as array of path segments 621 + - Parse commands using string splitting and regex 622 + - Implement basic tab completion (suggest directory names) 623 + - Save progress to localStorage for session persistence 624 +

625 +
626 + ## File Creation and Editing 627 +
628 + Command-line file creation and editing are essential skills for automating textbook workflows, especially when + generating multiple files from templates or making bulk updates. While VS Code is the primary editor for content + development, knowing command-line file operations enables scripting and automation. 629 +
630 + ### Creating Files 631 +
632 + The touch command creates empty files or updates the modification timestamp of existing files: 633 +
634 +

bash
        635 +  # Create a new chapter index file
        636 +  touch docs/chapters/14-future-directions/index.md
        637 +  
        638 +  # Create multiple files at once
        639 +  touch docs/chapters/14-future-directions/{index.md,exercises.md,glossary.md}
        640 +

641 +
642 + The echo command combined with output redirection creates files with initial content: 643 +
644 +

bash
        645 +  # Create file with single line of content
        646 +  echo "# Chapter 14: Future Directions" > docs/chapters/14-future-directions/index.md
        647 +  
        648 +  # Append content to existing file
        649 +  echo "## Summary" >> docs/chapters/14-future-directions/index.md
        650 +

651 +
652 + For multi-line content, use a here-document: 653 +
654 +

bash
        655 +  cat << EOF > docs/chapters/14-future-directions/index.md
        656 +  # Chapter 14: Future Directions
        657 +  
        658 +  ## Summary
        659 +  
        660 +  This chapter explores emerging trends in AI-assisted education.
        661 +  
        662 +  ## Concepts Covered
        663 +  
        664 +  1. Large Language Models
        665 +  2. Adaptive Learning Systems
        666 +  3. Real-time Content Generation
        667 +  EOF
        668 +

669 +
670 + ### Editing Files 671 +
672 + While command-line text editors like vim, nano, and emacs are available, most intelligent textbook + developers prefer editing in VS Code. However, simple text transformations can be performed using command-line + tools: 673 +
674 + sed (stream editor): Perform find-and-replace operations 675 +
676 +

bash
        677 +  # Replace all occurrences of "CMDB" with "Configuration Management Database"
        678 +  sed -i '' 's/CMDB/Configuration Management Database/g' docs/chapters/*/index.md
        679 +  
        680 +  # Add a line after a specific pattern
        681 +  sed -i '' '/## Summary/a\
        682 +  This chapter covers fundamental concepts.' docs/chapters/14-future-directions/index.md
        683 +

684 +
685 + awk (text processing): Extract and transform structured text 686 +
687 +

bash
        688 +  # Extract all level-2 headers from a file
        689 +  awk '/^## / {print $0}' docs/chapters/01-intro/index.md
        690 +  
        691 +  # Print only lines containing "learning graph"
        692 +  awk '/learning graph/ {print}' docs/chapters/*/index.md
        693 +

694 +
695 + grep (pattern matching): Search for text patterns 696 +
697 +

bash
        698 +  # Find all chapters mentioning "MicroSim"
        699 +  grep -r "MicroSim" docs/chapters/
        700 +  
        701 +  # Count occurrences of "learning graph" in all markdown files
        702 +  grep -r "learning graph" docs/ --include="*.md" | wc -l
        703 +

704 +
705 + ### File Manipulation Operations 706 +
707 + Common file operations for textbook projects: 708 +
709 + | Operation | Command | Example | 710 + |-----------|---------|---------| 711 + | Copy file | cp source destination | cp chapter-template.md chapter-05.md | 712 + | Copy directory | cp -r source destination | cp -r templates/chapter docs/chapters/05-new | 713 + | Move/rename | mv source destination | mv old-chapter.md new-chapter.md | 714 + | Delete file | rm filename | rm docs/chapters/draft.md | 715 + | Delete directory | rm -r dirname | rm -r docs/chapters/deprecated | 716 + | Create directory | mkdir dirname | mkdir docs/chapters/15-appendix | 717 + | Create nested directories | mkdir -p path/to/dir | mkdir -p docs/sims/new-sim/assets | 718 +
719 + ### Safe File Operations 720 +
721 + To prevent accidental data loss, use these practices: 722 +
723 + - Use -i flag for interactive confirmation: 724 +

bash
        725 +    rm -i docs/chapters/draft.md    # Prompts "remove docs/chapters/draft.md?"
        726 +

727 +
728 + - Use -n flag for no-clobber (don't overwrite): 729 +

bash
        730 +    cp -n source.md destination.md  # Only copies if destination doesn't exist
        731 +

732 +
733 + - Preview operations before executing: 734 +

bash
        735 +    # Preview files that would be deleted
        736 +    find docs/chapters -name "draft*.md"
        737 +    # Then delete them
        738 +    find docs/chapters -name "draft*.md" -delete
        739 +

740 +
741 + - Use version control as a safety net: 742 +

bash
        743 +    git status                      # Check for uncommitted changes
        744 +    git stash                       # Temporarily save current changes
        745 +    # Perform risky operations
        746 +    git stash pop                   # Restore changes if needed
        747 +

748 +
749 + ## Shell Scripts 750 +
751 + Shell scripts are text files containing sequences of Bash commands that automate repetitive tasks. In + intelligent textbook development, shell scripts are used to install Claude skills, generate content, validate + quality, and deploy to production. 752 +
753 + ### Anatomy of a Shell Script 754 +
755 + A basic shell script has three components: 756 +
757 + 1. Shebang line: Specifies the interpreter (always first line) 758 +

bash
        759 +     #!/bin/bash
        760 +

761 +
762 + 2. Comments: Explain what the script does (start with #) 763 +

bash
        764 +     # Install Claude skills to global skills directory
        765 +

766 +
767 + 3. Commands: The actual operations to perform 768 +

bash
        769 +     ln -s $(pwd)/skills/* ~/.claude/skills/
        770 +

771 +
772 + ### Example: Installing Claude Skills 773 +
774 + The install-claude-skills.sh script creates symbolic links from the project's skills directory to the global + Claude skills directory: 775 +
776 +

bash
        777 +  #!/bin/bash
        778 +  
        779 +  # Install Claude skills to global skills directory
        780 +  # This makes skills available to all Claude projects
        781 +  
        782 +  SKILLS_DIR="$HOME/.claude/skills"
        783 +  PROJECT_SKILLS="$(pwd)/skills"
        784 +  
        785 +  # Create skills directory if it doesn't exist
        786 +  mkdir -p "$SKILLS_DIR"
        787 +  
        788 +  # Link each skill to global directory
        789 +  for skill in "$PROJECT_SKILLS"/*; do
        790 +      skill_name=$(basename "$skill")
        791 +      echo "Installing skill: $skill_name"
        792 +      ln -sf "$skill" "$SKILLS_DIR/$skill_name"
        793 +  done
        794 +  
        795 +  echo "Skills installation complete!"
        796 +

797 +
798 + ### Script Components Explained 799 +
800 + Variables: 801 +

bash
        802 +  SKILLS_DIR="$HOME/.claude/skills"      # Directory where skills are installed
        803 +  PROJECT_SKILLS="$(pwd)/skills"         # Directory containing project skills
        804 +

805 +
806 + Command substitution: 807 +

bash
        808 +  skill_name=$(basename "$skill")        # Extracts filename from full path
        809 +

810 +
811 + For loops: 812 +

bash
        813 +  for skill in "$PROJECT_SKILLS"/*; do   # Iterate over each skill directory
        814 +      # Commands here execute for each skill
        815 +  done
        816 +

817 +
818 + Conditional creation: 819 +

bash
        820 +  mkdir -p "$SKILLS_DIR"                 # Create directory if it doesn't exist
        821 +

822 +
823 + Symbolic links: 824 +

bash
        825 +  ln -sf "$skill" "$SKILLS_DIR/$skill_name"    # -s = symbolic, -f = force (replace if exists)
        826 +

827 +
828 + ### Script Best Practices 829 +
830 + Effective shell scripts follow these conventions: 831 +
832 + - Start with shebang: #!/bin/bash on line 1 833 + - Use meaningful variable names: SKILLS_DIR not dir1 834 + - Quote variables: "$variable" prevents word splitting 835 + - Check for errors: Use set -e to exit on any command failure 836 + - Add help text: Provide usage instructions when run with -h or --help 837 + - Use functions: Break complex scripts into reusable functions 838 + - Validate inputs: Check that required files/directories exist 839 +
840 + ### Example: Advanced Script with Error Handling 841 +
842 +

bash
        843 +  #!/bin/bash
        844 +  set -e  # Exit on any error
        845 +  
        846 +  # Validate learning graph quality before deployment
        847 +  
        848 +  LEARNING_GRAPH_CSV="docs/learning-graph/learning-graph.csv"
        849 +  QUALITY_THRESHOLD=70
        850 +  
        851 +  # Check that learning graph file exists
        852 +  if [ ! -f "$LEARNING_GRAPH_CSV" ]; then
        853 +      echo "Error: Learning graph file not found: $LEARNING_GRAPH_CSV"
        854 +      exit 1
        855 +  fi
        856 +  
        857 +  # Run quality analysis
        858 +  echo "Analyzing learning graph quality..."
        859 +  python docs/learning-graph/analyze-graph.py "$LEARNING_GRAPH_CSV" quality-metrics.md
        860 +  
        861 +  # Extract quality score from quality-metrics.md
        862 +  quality_score=$(grep "Quality Score:" quality-metrics.md | awk '{print $3}' | cut -d'/' -f1)
        863 +  
        864 +  echo "Quality score: $quality_score/100"
        865 +  
        866 +  # Check if quality meets threshold
        867 +  if [ "$quality_score" -lt "$QUALITY_THRESHOLD" ]; then
        868 +      echo "Error: Quality score ($quality_score) is below threshold ($QUALITY_THRESHOLD)"
        869 +      echo "Review quality-metrics.md for issues"
        870 +      exit 1
        871 +  fi
        872 +  
        873 +  echo "✓ Quality check passed! Ready for deployment."
        874 +

875 +
876 + This script demonstrates: 877 + - Error handling with set -e 878 + - File existence checks 879 + - External command execution (Python script) 880 + - Text parsing with grep, awk, and cut 881 + - Conditional logic with if statements 882 + - Meaningful exit codes (0 = success, 1 = failure) 883 +
884 + ## Script Execution Permissions 885 +
886 + Unix-like systems (macOS, Linux) use a permission system to control who can read, write, or execute files. + Before a shell script can be run, it must have execute permissions set. 887 +
888 + ### Understanding File Permissions 889 +
890 + File permissions are displayed by ls -l: 891 +
892 +

bash
        893 +  $ ls -l scripts/install-claude-skills.sh
        894 +  -rwxr-xr-x  1 username  staff  512 Jan 15 10:30 install-claude-skills.sh
        895 +

896 +
897 + The permission string -rwxr-xr-x breaks down as: 898 +
899 + - File type: - (regular file), d (directory), l (symbolic link) 900 + - Owner permissions: rwx (read, write, execute) 901 + - Group permissions: r-x (read, execute, no write) 902 + - Other permissions: r-x (read, execute, no write) 903 +
904 + ### Permission Notation 905 +
906 + Permissions can be represented in two formats: 907 +
908 + Symbolic notation: 909 +

910 +  r = read (4)
        911 +  w = write (2)
        912 +  x = execute (1)
        913 +

914 +
915 + Numeric notation (octal): 916 +

917 +  rwx = 4+2+1 = 7
        918 +  r-x = 4+0+1 = 5
        919 +  r-- = 4+0+0 = 4
        920 +

921 +
922 + Common permission combinations: 923 +
924 + | Octal | Symbolic | Meaning | 925 + |-------|----------|---------| 926 + | 755 | -rwxr-xr-x | Owner can read/write/execute, others can read/execute | 927 + | 644 | -rw-r--r-- | Owner can read/write, others can read only | 928 + | 700 | -rwx------ | Owner can read/write/execute, others have no access | 929 + | 775 | -rwxrwxr-x | Owner and group can read/write/execute, others can read/execute | 930 +
931 + ### Making Scripts Executable 932 +
933 + To make a script executable, use the chmod command: 934 +
935 +

bash
        936 +  # Add execute permission for owner
        937 +  chmod +x scripts/install-claude-skills.sh
        938 +  
        939 +  # Add execute permission for everyone
        940 +  chmod a+x scripts/install-claude-skills.sh
        941 +  
        942 +  # Set specific permissions using numeric notation
        943 +  chmod 755 scripts/install-claude-skills.sh
        944 +

945 +
946 + After setting execute permissions, the script can be run directly: 947 +
948 +

bash
        949 +  # Run with full path
        950 +  ./scripts/install-claude-skills.sh
        951 +  
        952 +  # Run with relative path
        953 +  cd scripts
        954 +  ./install-claude-skills.sh
        955 +  
        956 +  # Run from anywhere if in PATH
        957 +  install-claude-skills.sh
        958 +

959 +
960 +

961 +

Permission Bits Visual Infographic

962 + Type: infographic 963 +
964 + Purpose: Explain Unix file permission system with visual representation of permission bits 965 +
966 + Layout: Grid layout with three main sections 967 +
968 + Section 1 - Permission String Breakdown (top): 969 + - Large text: -rwxr-xr-x 970 + - Each character highlighted separately: 971 + - - → "File type: Regular file" 972 + - rwx → "Owner: Read, Write, Execute" 973 + - r-x → "Group: Read, Execute only" 974 + - r-x → "Others: Read, Execute only" 975 + - Color coding: Owner (blue), Group (green), Others (orange) 976 +
977 + Section 2 - Octal Representation (middle): 978 + - Visual breakdown showing how rwx maps to numbers: 979 +

980 +        r w x
        981 +        4 2 1
        982 +

983 + - Example calculations: 984 + - rwx = 4+2+1 = 7 985 + - r-x = 4+0+1 = 5 986 + - r-- = 4+0+0 = 4 987 + - Final octal: 755 988 +
989 + Section 3 - Common Permissions (bottom): 990 + - Cards showing common permission sets: 991 +
992 + Card 1: "Executable Script" 993 + - Octal: 755 994 + - Symbolic: -rwxr-xr-x 995 + - Use case: Shell scripts that should run 996 + - Icon: 📜 with ⚡ 997 +
998 + Card 2: "Private Script" 999 + - Octal: 700 1000 + - Symbolic: -rwx------ 1001 + - Use case: Scripts with sensitive data 1002 + - Icon: 🔒 1003 +
1004 + Card 3: "Markdown File" 1005 + - Octal: 644 1006 + - Symbolic: -rw-r--r-- 1007 + - Use case: Documentation files 1008 + - Icon: 📝 1009 +
1010 + Card 4: "Directory" 1011 + - Octal: 755 1012 + - Symbolic: drwxr-xr-x 1013 + - Use case: Standard project directories 1014 + - Icon: 📁 1015 +
1016 + Interactive elements: 1017 + - Hover over permission bits to see explanation 1018 + - Click octal number to toggle between symbolic and numeric views 1019 + - Click "Common Permissions" cards to see full explanation and chmod command 1020 + - Slider to build custom permissions: drag to set r/w/x for owner/group/others 1021 + - Displays resulting chmod command in real-time 1022 +
1023 + Visual style: Modern, clean design with monospace font for permission strings 1024 + Color scheme: 1025 + - File type: Gray 1026 + - Owner permissions: Blue (#3498db) 1027 + - Group permissions: Green (#2ecc71) 1028 + - Other permissions: Orange (#e67e22) 1029 + - Background: White with subtle shadows for cards 1030 +
1031 + Implementation: HTML/CSS/JavaScript with interactive permission builder 1032 +

1033 +
1034 + ### Security Considerations 1035 +
1036 + Execute permissions should be granted carefully: 1037 +
1038 + - Only make scripts executable if they need to be run: Don't blindly chmod +x all files 1039 + - Review scripts before making them executable: Malicious scripts can damage systems 1040 + - Be cautious with scripts from untrusted sources: Always inspect before running 1041 + - Use least privilege: Grant minimum permissions necessary (e.g., 700 for personal scripts instead of 777) 1042 +
1043 + ### Troubleshooting Permission Issues 1044 +
1045 + Common permission-related errors: 1046 +
1047 + Error: "Permission denied" 1048 +

bash
       1049 +  $ ./scripts/install-claude-skills.sh
       1050 +  -bash: ./scripts/install-claude-skills.sh: Permission denied
       1051 +

1052 + Solution: Add execute permission 1053 +

bash
       1054 +  chmod +x scripts/install-claude-skills.sh
       1055 +

1056 +
1057 + Error: "No such file or directory" when script exists 1058 +

bash
       1059 +  $ ./scripts/install-claude-skills.sh
       1060 +  -bash: ./scripts/install-claude-skills.sh: No such file or directory
       1061 +

1062 + Cause: Incorrect shebang line (e.g., Windows line endings) 1063 + Solution: Convert line endings to Unix format 1064 +

bash
       1065 +  dos2unix scripts/install-claude-skills.sh
       1066 +

1067 +
1068 + ## Symlink Creation 1069 +
1070 + Symbolic links (symlinks) are special files that act as pointers to other files or directories, enabling + multiple paths to access the same content. In intelligent textbook development, symlinks are used to install + Claude skills globally while maintaining the skills in the project repository. 1071 +
1072 + ### Why Use Symlinks for Skills? 1073 +
1074 + Claude Code looks for skills in ~/.claude/skills/ by default. Without symlinks, you would need to: 1075 +
1076 + - Copy skill files to ~/.claude/skills/ every time they're updated 1077 + - Maintain duplicate copies in each project 1078 + - Manually synchronize changes across projects 1079 +
1080 + Symlinks solve this by creating a reference in ~/.claude/skills/ that points to the original skill files in + the project repository. When the original files are updated, the changes are immediately reflected in all + projects using that symlink. 1081 +
1082 + ### Creating Symlinks 1083 +
1084 + The ln command creates symbolic links: 1085 +
1086 +

bash
       1087 +  # Syntax
       1088 +  ln -s /path/to/original /path/to/link
       1089 +  
       1090 +  # Example: Link a single skill
       1091 +  ln -s ~/Documents/textbook-project/skills/glossary-generator ~/.claude/skills/glossary-generator
       1092 +  
       1093 +  # Example: Link all skills in a directory
       1094 +  ln -s ~/Documents/textbook-project/skills/* ~/.claude/skills/
       1095 +

1096 +
1097 + Flags: 1098 + - -s: Create symbolic link (not a hard link) 1099 + - -f: Force overwrite if link already exists 1100 + - -n: Don't dereference existing symlink (useful when updating) 1101 +
1102 + ### Symlinks vs. Copies 1103 +
1104 + Understanding the difference is crucial: 1105 +
1106 + | Operation | Copy | Symlink | 1107 + |-----------|------|---------| 1108 + | Storage | Duplicates content | Only stores pointer (~1KB) | 1109 + | Updates | Manual re-copy needed | Automatic (follows original) | 1110 + | Deletion | Independent files | Deleting symlink doesn't affect original | 1111 + | Portability | Works if original is deleted | Breaks if original is moved/deleted | 1112 + | Permissions | Uses copy's permissions | Uses original's permissions | 1113 +
1114 + ### Verifying Symlinks 1115 +
1116 + Use ls -l to see symlink targets: 1117 +
1118 +

bash
       1119 +  $ ls -l ~/.claude/skills/glossary-generator
       1120 +  lrwxr-xr-x  1 username  staff  72 Jan 15 10:30 glossary-generator -> 
            + /Users/username/Documents/textbook-project/skills/glossary-generator
       1121 +

1122 +
1123 + The -> arrow indicates this is a symlink pointing to the target path. 1124 +
1125 + ### Managing Symlinks 1126 +
1127 + List all symlinks in a directory: 1128 +

bash
       1129 +  find ~/.claude/skills/ -type l -ls
       1130 +

1131 +
1132 + Check if a symlink target exists: 1133 +

bash
       1134 +  test -e ~/.claude/skills/glossary-generator && echo "Target exists" || echo "Broken symlink"
       1135 +

1136 +
1137 + Remove a symlink: 1138 +

bash
       1139 +  rm ~/.claude/skills/glossary-generator     # Removes link only, original unaffected
       1140 +

1141 +
1142 + Update a symlink to point to a new target: 1143 +

bash
       1144 +  ln -sf /new/path/to/skill ~/.claude/skills/glossary-generator
       1145 +

1146 +
1147 + ### Project-Local vs. Global Skills 1148 +
1149 + Claude Code supports two skill installation strategies: 1150 +
1151 + Global skills (~/.claude/skills/): 1152 + - Available to all projects 1153 + - Ideal for stable, mature skills used across multiple textbooks 1154 + - Installed via scripts/install-claude-skills.sh 1155 +
1156 + Project-local skills (.claude/skills/): 1157 + - Available only to the current project 1158 + - Ideal for experimental or project-specific skills 1159 + - Installed by creating .claude/skills/ directory in project root 1160 +
1161 + The installation script can be modified to install to project-local directory by changing: 1162 +
1163 +

bash
       1164 +  # From:
       1165 +  SKILLS_DIR="$HOME/.claude/skills"
       1166 +  
       1167 +  # To:
       1168 +  SKILLS_DIR="$(pwd)/.claude/skills"
       1169 +

1170 +
1171 + ### Troubleshooting Symlinks 1172 +
1173 + Problem: "Skill not found" error in Claude Code 1174 +
1175 + Possible causes: 1176 + 1. Symlink not created correctly 1177 + 2. Target path is incorrect 1178 + 3. Permissions issue on target directory 1179 +
1180 + Solution: 1181 +

bash
       1182 +  # Verify symlink exists
       1183 +  ls -l ~/.claude/skills/
       1184 +  
       1185 +  # Check target is accessible
       1186 +  ls -l ~/Documents/textbook-project/skills/glossary-generator
       1187 +  
       1188 +  # Re-create symlink with correct path
       1189 +  ln -sf ~/Documents/textbook-project/skills/glossary-generator ~/.claude/skills/glossary-generator
       1190 +

1191 +
1192 + Problem: "Permission denied" when running skill 1193 +
1194 + Solution: 1195 +

bash
       1196 +  # Ensure original skill directory has correct permissions
       1197 +  chmod -R 755 ~/Documents/textbook-project/skills/
       1198 +

1199 +
1200 +

1201 +

Skill Installation Workflow Diagram

1202 + Type: diagram 1203 +
1204 + Purpose: Show the relationship between project skills directory, global skills directory, and Claude Code's + skill discovery 1205 +
1206 + Components to show: 1207 + - Project repository structure (left side): 1208 +

1209 +        ~/Documents/textbook-project/
       1210 +        ├── skills/
       1211 +        │   ├── glossary-generator/
       1212 +        │   │   ├── SKILL.md
       1213 +        │   │   └── templates/
       1214 +        │   ├── quiz-generator/
       1215 +        │   │   └── SKILL.md
       1216 +        │   └── learning-graph-generator/
       1217 +        │       ├── SKILL.md
       1218 +        │       └── scripts/
       1219 +        └── scripts/
       1220 +            └── install-claude-skills.sh
       1221 +

1222 +
1223 + - Global skills directory (center): 1224 +

1225 +        ~/.claude/skills/
       1226 +        ├── glossary-generator -> ~/Documents/textbook-project/skills/glossary-generator
       1227 +        ├── quiz-generator -> ~/Documents/textbook-project/skills/quiz-generator
       1228 +        └── learning-graph-generator -> ~/Documents/textbook-project/skills/learning-graph-generator
       1229 +

1230 +
1231 + - Claude Code (right side): 1232 + - Search icon looking in ~/.claude/skills/ 1233 + - Successfully finding skills via symlinks 1234 + - Loading SKILL.md files 1235 +
1236 + Connections: 1237 + - Dashed arrows from global skills to project skills (labeled "symlink") 1238 + - Solid arrow from install-claude-skills.sh to global skills (labeled "creates") 1239 + - Solid arrow from Claude Code to global skills (labeled "reads from") 1240 +
1241 + Annotations: 1242 + - Label on project skills: "Original files (version controlled)" 1243 + - Label on global skills: "Symlinks (not version controlled)" 1244 + - Label on symlinks: "Points to original, no duplication" 1245 + - Callout: "When original files update, changes immediately available to Claude" 1246 +
1247 + Visual style: System architecture diagram with clear flow 1248 + Color scheme: 1249 + - Project files: Blue 1250 + - Symlinks: Orange (with dotted line style) 1251 + - Claude Code: Purple 1252 +
1253 + Implementation: SVG diagram with labeled components and directional arrows 1254 +

1255 +
1256 + ## Capstone: Complete Textbook Project 1257 +
1258 + The capstone project synthesizes all skills, tools, and workflows from this course by guiding you through the + complete process of creating an intelligent textbook from initial concept to published website. This + comprehensive project mirrors real-world educational content development and demonstrates your ability to apply + course concepts independently. 1259 +
1260 + ### Project Overview 1261 +
1262 + You will create an intelligent textbook on a subject of your choice, following the complete workflow: 1263 +
1264 + 1. Develop a comprehensive course description 1265 + 2. Generate a 200-concept learning graph with dependencies 1266 + 3. Design chapter structure based on concept dependencies 1267 + 4. Create chapter content with interactive elements 1268 + 5. Generate glossary, quiz, and FAQ content 1269 + 6. Build and deploy the textbook to GitHub Pages 1270 +
1271 + The project typically requires 15-25 hours depending on textbook scope and prior experience. You are encouraged + to choose a subject in which you have expertise, as domain knowledge significantly accelerates content creation. 1272 +
1273 + ### Project Requirements 1274 +
1275 + Your completed textbook must include: 1276 +
1277 + Foundation (Required): 1278 + - Course description meeting all quality criteria (score ≥ 85/100) 1279 + - Learning graph with 200 concepts, validated dependencies (DAG structure), and taxonomy categorization 1280 + - 6-12 chapters with clear concept mapping 1281 + - MkDocs configuration with proper navigation 1282 +
1283 + Content (Required): 1284 + - At least 3 complete chapters with rich content (~3,000 words each) 1285 + - Minimum 15 non-text elements across chapters (lists, tables, diagrams, MicroSims, etc.) 1286 + - Glossary with 50+ terms following ISO 11179 standards 1287 + - One complete chapter quiz (10+ questions, multiple Bloom's levels) 1288 +
1289 + Interactive Elements (Choose at least 2): 1290 + - At least one MicroSim demonstrating a key concept 1291 + - At least one interactive infographic or timeline 1292 + - Learning graph visualization using vis-network 1293 + - FAQ page with 20+ questions 1294 +
1295 + Deployment (Required): 1296 + - GitHub repository with complete source files 1297 + - Deployed website on GitHub Pages 1298 + - README with project overview and build instructions 1299 +
1300 + ### Phase 1: Course Design (3-5 hours) 1301 +
1302 + Step 1: Course Description Development 1303 +
1304 + Use the course-description-analyzer skill to create your course description: 1305 +
1306 +

bash
       1307 +  # In Claude Code, invoke the skill
       1308 +  /skill course-description-analyzer
       1309 +

1310 +
1311 + Your course description should specify: 1312 + - Course title and target audience (reading level) 1313 + - Prerequisites and assumed knowledge 1314 + - Main topics covered (15-25 topics) 1315 + - Topics explicitly out of scope (5-10 topics) 1316 + - Learning outcomes across all six Bloom's Taxonomy levels 1317 +
1318 + Quality check: 1319 +

bash
       1320 +  # Skill will generate quality score
       1321 +  # Target: ≥ 85/100
       1322 +

1323 +
1324 + Step 2: Learning Graph Generation 1325 +
1326 + Use the learning-graph-generator skill to create your concept map: 1327 +
1328 +

bash
       1329 +  /skill learning-graph-generator
       1330 +

1331 +
1332 + The skill will: 1333 + - Enumerate 200 concepts from your course description 1334 + - Map concept dependencies (directed acyclic graph) 1335 + - Categorize concepts by taxonomy 1336 + - Validate graph quality 1337 +
1338 + Quality check: 1339 +

bash
       1340 +  cd docs/learning-graph
       1341 +  python analyze-graph.py learning-graph.csv quality-metrics.md
       1342 +  
       1343 +  # Target: Quality score ≥ 70/100
       1344 +  # Ensure zero circular dependencies
       1345 +

1346 +
1347 + Step 3: Chapter Structure Design 1348 +
1349 + Use the book-chapter-generator skill to design chapters: 1350 +
1351 +

bash
       1352 +  /skill book-chapter-generator
       1353 +

1354 +
1355 + The skill creates chapter directories with: 1356 + - Chapter title and summary 1357 + - List of concepts covered in each chapter 1358 + - Prerequisites linking to earlier chapters 1359 +
1360 + Review: 1361 + - Verify concept dependencies are respected (prerequisites taught before dependents) 1362 + - Ensure even distribution (no chapter has >40 concepts) 1363 + - Check that foundational concepts appear in early chapters 1364 +
1365 + ### Phase 2: Content Creation (8-15 hours) 1366 +
1367 + Step 4: Generate Chapter Content 1368 +
1369 + For each chapter, use the chapter-content-generator skill: 1370 +
1371 +

bash
       1372 +  /skill chapter-content-generator
       1373 +  # Provide chapter name or path when prompted
       1374 +

1375 +
1376 + The skill generates: 1377 + - Detailed educational content at appropriate reading level 1378 + - Diverse non-text elements (lists, tables, diagrams) 1379 + - Specifications for complex elements (MicroSims, infographics) in <details> blocks 1380 +
1381 + Minimum requirement: Complete 3 chapters with rich content 1382 +
1383 + Step 5: Create Interactive Elements 1384 +
1385 + Implement at least one MicroSim using the microsim-p5 skill: 1386 +
1387 +

bash
       1388 +  /skill microsim-p5
       1389 +

1390 +
1391 + Choose a concept that benefits from interactive visualization, such as: 1392 + - Algorithm visualization (sorting, graph traversal) 1393 + - System behavior simulation (networking, resource allocation) 1394 + - Parameter exploration (statistical distributions, optimization) 1395 +
1396 + Step 6: Build Supporting Resources 1397 +
1398 + Generate glossary: 1399 +

bash
       1400 +  /skill glossary-generator
       1401 +

1402 +
1403 + Generate chapter quizzes: 1404 +

bash
       1405 +  /skill quiz-generator
       1406 +  # Generate quiz for at least one chapter
       1407 +

1408 +
1409 + Generate FAQ: 1410 +

bash
       1411 +  /skill faq-generator
       1412 +

1413 +
1414 + ### Phase 3: Integration and Quality Assurance (2-4 hours) 1415 +
1416 + Step 7: Configure MkDocs 1417 +
1418 + Update mkdocs.yml navigation to include all content: 1419 +
1420 +

yaml
       1421 +  nav:
       1422 +    - Home: index.md
       1423 +    - Learning Graph:
       1424 +        - Introduction: learning-graph/index.md
       1425 +        - Concept List: learning-graph/list-concepts.md
       1426 +        - Quality Analysis: learning-graph/quality-metrics.md
       1427 +    - Chapters:
       1428 +        - Chapter 1: chapters/01-chapter-name/index.md
       1429 +        - Chapter 2: chapters/02-chapter-name/index.md
       1430 +        # Add all chapters
       1431 +    - Resources:
       1432 +        - Glossary: glossary.md
       1433 +        - FAQ: faq.md
       1434 +    - MicroSims:
       1435 +        - Simulation Name: sims/sim-name/index.md
       1436 +

1437 +
1438 + Step 8: Test Locally 1439 +
1440 + Build and serve the textbook locally: 1441 +
1442 +

bash
       1443 +  # Install dependencies
       1444 +  pip install -r requirements.txt
       1445 +  
       1446 +  # Serve locally
       1447 +  mkdocs serve
       1448 +  
       1449 +  # Open browser to http://localhost:8000
       1450 +

1451 +
1452 + Quality checks: 1453 + - All navigation links work 1454 + - Images and MicroSims load correctly 1455 + - No broken internal links 1456 + - Consistent formatting across chapters 1457 + - Glossary terms properly defined 1458 + - Quiz questions display correctly 1459 +
1460 + Step 9: Build Validation 1461 +
1462 + Test strict build (fail on warnings): 1463 +
1464 +

bash
       1465 +  mkdocs build --strict
       1466 +

1467 +
1468 + Fix any warnings or errors reported by MkDocs. 1469 +
1470 + ### Phase 4: Deployment (1-2 hours) 1471 +
1472 + Step 10: GitHub Repository Setup 1473 +
1474 + Initialize Git repository (if not already done): 1475 +
1476 +

bash
       1477 +  git init
       1478 +  git add .
       1479 +  git commit -m "Initial commit: Complete intelligent textbook project"
       1480 +

1481 +
1482 + Create GitHub repository and push: 1483 +
1484 +

bash
       1485 +  # Create repository on GitHub (github.com/new)
       1486 +  # Then:
       1487 +  git remote add origin https://github.com/username/textbook-name.git
       1488 +  git branch -M main
       1489 +  git push -u origin main
       1490 +

1491 +
1492 + Step 11: Deploy to GitHub Pages 1493 +
1494 + Configure GitHub Pages in repository settings: 1495 + - Settings → Pages → Source: Deploy from branch 1496 + - Branch: gh-pages 1497 + - Folder: / (root) 1498 +
1499 + Deploy using MkDocs: 1500 +
1501 +

bash
       1502 +  mkdocs gh-deploy
       1503 +

1504 +
1505 + This command: 1506 + 1. Builds the static site 1507 + 2. Creates/updates gh-pages branch 1508 + 3. Pushes to GitHub 1509 + 4. Triggers GitHub Pages deployment 1510 +
1511 + Wait 2-5 minutes for deployment to complete, then visit: 1512 +

1513 +  https://username.github.io/textbook-name/
       1514 +

1515 +
1516 + Step 12: Documentation 1517 +
1518 + Update README.md with: 1519 +
1520 +

markdown
       1521 +  # [Textbook Title]
       1522 +  
       1523 +  An intelligent textbook on [subject] created using Claude Skills.
       1524 +  
       1525 +  ## Overview
       1526 +  
       1527 +  [Brief description of textbook content and target audience]
       1528 +  
       1529 +  ## Features
       1530 +  
       1531 +  - 200-concept learning graph with dependency mapping
       1532 +  - [X] chapters with interactive elements
       1533 +  - [Y] MicroSims demonstrating key concepts
       1534 +  - Comprehensive glossary with [Z] terms
       1535 +  - Chapter quizzes aligned to Bloom's Taxonomy
       1536 +  
       1537 +  ## Live Site
       1538 +  
       1539 +  View the textbook: https://username.github.io/textbook-name/
       1540 +  
       1541 +  ## Building Locally
       1542 +  
       1543 +

bash 1544 + # Install dependencies 1545 + pip install -r requirements.txt 1546 +
1547 + # Serve locally 1548 + mkdocs serve 1549 +

1550 +  
       1551 +  ## Project Structure
       1552 +  
       1553 +

1554 + textbook-name/ 1555 + ├── docs/ # Textbook content 1556 + ├── skills/ # Claude skills used 1557 + ├── scripts/ # Utility scripts 1558 + └── mkdocs.yml # Site configuration 1559 +

1560 +  
       1561 +  ## License
       1562 +  
       1563 +  [Your chosen license]
       1564 +

1565 +
1566 + ### Project Evaluation Checklist 1567 +
1568 + Use this checklist to verify project completeness: 1569 +
1570 + Foundation: 1571 + - [ ] Course description with quality score ≥ 85/100 1572 + - [ ] Learning graph with 200 concepts 1573 + - [ ] Zero circular dependencies in learning graph 1574 + - [ ] Learning graph quality score ≥ 70/100 1575 + - [ ] 6-12 chapters created with concept mapping 1576 + - [ ] MkDocs configuration complete 1577 +
1578 + Content: 1579 + - [ ] At least 3 complete chapters (~3,000 words each) 1580 + - [ ] 15+ non-text elements total across chapters 1581 + - [ ] Glossary with 50+ ISO 11179-compliant terms 1582 + - [ ] At least one complete chapter quiz (10+ questions) 1583 +
1584 + Interactive Elements: 1585 + - [ ] At least one MicroSim implemented and functional 1586 + - [ ] At least one interactive infographic or timeline 1587 + - [ ] Learning graph visualization (optional but recommended) 1588 + - [ ] FAQ page with 20+ questions (optional) 1589 +
1590 + Deployment: 1591 + - [ ] GitHub repository created and pushed 1592 + - [ ] Website deployed to GitHub Pages 1593 + - [ ] All links functional in deployed site 1594 + - [ ] README.md with complete documentation 1595 + - [ ] No build warnings or errors 1596 +
1597 + Quality: 1598 + - [ ] Consistent markdown formatting across chapters 1599 + - [ ] All images and MicroSims load correctly 1600 + - [ ] No broken internal links 1601 + - [ ] Mobile-responsive design (MkDocs Material default) 1602 + - [ ] Search functionality works (MkDocs Material default) 1603 +
1604 + ### Next Steps and Extensions 1605 +
1606 + After completing the capstone project, consider these extensions: 1607 +
1608 + Advanced Features: 1609 + - Install learning graph viewer with interactive exploration 1610 + - Add custom CSS styling to match your branding 1611 + - Implement additional MicroSims for complex concepts 1612 + - Create video walkthroughs of key topics 1613 + - Add social media preview images 1614 +
1615 + Collaboration: 1616 + - Invite subject matter experts to review content 1617 + - Set up GitHub Issues for feedback collection 1618 + - Create contribution guidelines for open-source collaboration 1619 + - Establish content review workflows 1620 +
1621 + Analytics and Improvement: 1622 + - Add Google Analytics to track visitor engagement 1623 + - Monitor which pages receive most traffic 1624 + - Identify chapters with high bounce rates for improvement 1625 + - Survey learners for feedback 1626 +
1627 + Publication: 1628 + - Share on social media and educational platforms 1629 + - Submit to open educational resources (OER) repositories 1630 + - Present at conferences or webinars 1631 + - Write blog post about development process 1632 +
1633 + ## Summary 1634 +
1635 + This chapter equipped you with the essential development tools and workflows for creating intelligent textbooks. + You learned to use Visual Studio Code as a comprehensive content authoring platform, leveraging its integrated + terminal, markdown preview, and Git integration. You mastered Bash command-line operations including directory + navigation, file manipulation, and shell scripting for automation. 1636 +
1637 + The capstone project challenged you to synthesize all course concepts by creating a complete intelligent + textbook from concept to deployment. This comprehensive exercise demonstrated the end-to-end workflow: course + description development, learning graph generation, chapter structuring, content creation, interactive element + integration, quality assurance, and deployment to GitHub Pages. 1638 +
1639 + By completing this chapter and capstone project, you have demonstrated proficiency in: 1640 +
1641 + - Configuring professional development environments for technical content creation 1642 + - Executing command-line workflows for build automation and deployment 1643 + - Writing shell scripts to automate repetitive tasks 1644 + - Managing file permissions and symbolic links for skill installation 1645 + - Integrating all course skills into a coherent textbook development workflow 1646 + - Publishing educational content to production web platforms 1647 +
1648 + You are now equipped to independently create intelligent, AI-enhanced textbooks that advance educational + outcomes through structured knowledge graphs, interactive simulations, and adaptive learning resources.

⏺ Perfect! I've successfully generated comprehensive content for Chapter 13. Let me create a summary report:

Chapter Content Generation Complete

Chapter: 13 - Development Tools, Version Control, and DeploymentReading level: College/Professional DevelopmentContent length: ~11,000 words

Non-Text Elements Included

Markdown lists: 25+ lists throughout (feature lists, keyboard shortcuts, navigation best practices, project requirements, etc.)

Markdown tables: 6 tables - VS Code extensions comparison - Common terminal commands - Essential Bash commands - File manipulation operations - Permission combinations - Symlinks vs. Copies comparison

Diagrams (in

blocks): 2 - VS Code Interface Layout for Textbook Development - Skill Installation Workflow Diagram

Workflows (in

blocks): 1 - Terminal Workflow for Textbook Development (with swimlanes and decision points)

MicroSims (in

blocks): 1 - Interactive Directory Navigation Practice MicroSim (simulated terminal with filesystem visualization and 5 progressive challenges)

Infographics (in

blocks): 1 - Permission Bits Visual Infographic (interactive permission builder with octal/symbolic notation)

Total specialized elements: 5 interactive elements requiring implementationTotal non-text elements: 30+ (including all lists and tables)

All Concepts Covered ✓

✓ Visual Studio Code - Introduction, features, installation, setup
✓ VS Code for Content Development - Workflows, multi-file editing, productivity tips
✓ Terminal in VS Code - Accessing, features, managing multiple sessions
✓ Bash - Shell basics, command structure, essential commands, environment variables
✓ Shell Scripts - Anatomy, examples, best practices, error handling
✓ Script Execution Permissions - Understanding permissions, chmod, security considerations
✓ Directory Navigation - File paths, cd commands, project structure, best practices
✓ File Creation and Editing - Touch, echo, sed, awk, grep, safe operations
✓ Symlink Creation - Purpose, creation, management, troubleshooting
✓ Capstone: Complete Textbook Project - 4-phase comprehensive workflow (15-25 hours) with detailed requirements, evaluation checklist, and next steps

Content Highlights

Pedagogical progression: Simple tools (VS Code) → Basic operations (navigation, files) → Advanced concepts (scripts, permissions, symlinks) → Synthesis (capstone)
Practical focus: Real commands, actual workflows, troubleshooting sections
Professional depth: Security considerations, best practices, error handling
Comprehensive capstone: 12-step deployment workflow integrating all course concepts
Interactive learning: MicroSim for safe practice, infographic for visual learning

The chapter successfully synthesizes all prior course material into a complete development workflow, culminating in a capstone project that demonstrates mastery of the entire intelligent textbook creation process.