Overview

Appendix B: CLI Runbooks & Claude Code / Antigravity Setup Guides

Playbook Track: 05 – Presentation Slides & Architecture Diagrams
Target Audience: Year 1 Computer Science & Software Engineering Students Core Tooling Stack: Marp CLI, D2 CLI, Claude Code CLI, Antigravity CLI (agy), Model Context Protocol (MCP), Docker / Headless Chromium, GitHub Actions
Delivery Format: Operational Production Runbooks & Gating Automation

1. Runbook 1: Headless Marp CLI Presentation Compiler

Marp CLI enables unattended, programmatic conversion of Markdown slides into high-resolution PDF, Microsoft PowerPoint (.pptx), and standalone HTML presentations.

1.1 Local & CI Installation

# Verify Node.js 18+ is available
node -v

# Install Marp CLI globally or locally via npm/npx
npm install -g @marp-team/marp-cli

# Verify installation
marp --version

1.2 Compiling Presentations Headlessly

# 1. Compile to standalone HTML (with interactive presenter mode)
marp --html presentation.marp.md -o dist/index.html

# 2. Compile to high-resolution 1080p PDF (requires headless Chrome/Chromium)
marp --pdf --allow-local-files presentation.marp.md -o dist/architecture-brief.pdf

# 3. Compile to native editable PowerPoint (.pptx)
marp --pptx --allow-local-files presentation.marp.md -o dist/executive-deck.pptx

# 4. Watch mode for live local editing
marp -s -w presentation.marp.md

1.3 Running Marp in Minimal Docker / CI Containers

When running inside Linux CI runners without a graphical display:

# Install Chromium and required font libraries
apt-get update && apt-get install -y \
  chromium \
  fonts-inter \
  fonts-roboto \
  fonts-firacode

# Run Marp with explicit Chrome executable path
CHROME_PATH=/usr/bin/chromium marp --pdf --allow-local-files deck.md -o output.pdf

2. Runbook 2: D2 Declarative Architecture Diagram Engine

D2 is a modern, high-performance declarative diagramming engine written in Go, offering deterministic layout algorithms (ELK, Dagre, TALA).

2.1 Installation

# Install via official standalone install script (Linux / macOS)
curl -fsSL https://d2lang.com/install.sh | sh -s --

# Alternatively via Homebrew (macOS / Linux)
brew install d2

# Verify installation
d2 --version

2.2 CLI Compilation & Layout Selection

# 1. Render D2 markup to clean SVG vector (default Dagre layout)
d2 architecture.d2 dist/architecture.svg

# 2. Render using Eclipse Layout Kernel (ELK) - recommended for complex C4 systems
d2 --layout=elk architecture.d2 dist/architecture-elk.svg

# 3. Render high-resolution PNG raster (300 DPI)
d2 --scale 2.0 architecture.d2 dist/architecture-hires.png

# 4. Apply dark enterprise theme
d2 --theme 200 architecture.d2 dist/architecture-dark.svg

3. Runbook 3: Model Context Protocol (MCP) Server Setup

Integrating AI coding agents (Claude Code and Antigravity CLI) with visual diagramming tools requires configuring standard MCP servers.

3.1 Claude Code MCP Configuration (~/.claude/config.json or project .claude/mcp.json)

{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": ["-y", "@mermaid-js/mcp-server-mermaid"]
    },
    "drawio": {
      "command": "npx",
      "args": ["-y", "drawio-mcp-server"]
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
      "env": {
        "PUPPETEER_HEADLESS": "true"
      }
    }
  }
}

3.2 Antigravity CLI MCP Registration (.gemini/config/mcp.json)

{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": ["-y", "@mermaid-js/mcp-server-mermaid"]
    },
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Verify available MCP tools inside Claude Code or Antigravity:

# In Claude Code
/mcp list

# In Antigravity CLI
agy mcp list

4. Runbook 4: Claude Code CLI Workflow Configuration

To enable Claude Code to autonomously execute the visual engineering lifecycle, define project rules in CLAUDE.md at the repository root.

CLAUDE.md Production Configuration

# Visual Systems & Architecture Standards (Playbook 05)

Diagramming Rules

  • When asked to document architecture, always generate declarative source code (Mermaid or D2).
  • Never instruct the user to manually draw diagrams in web SaaS tools.
  • Place all architectural diagrams in docs/architecture/ with .mmd or .d2 extensions.
  • Ensure all diagrams adhere to the C4 Model (Context, Container, Component).

Presentation Rules

  • Generate presentation slides using Marp Markdown (*.marp.md).
  • Enforce the 10-Slide Executive Narrative Arc for all architectural briefings.
  • Before committing any slide deck, execute the visual QA auditor: python3 scratch/test_ch06_diagram_engine.py
  • Ensure WCAG 2.1 AA color contrast (>= 4.5:1) and zero bounding box collisions.

Slash Commands

  • /deck <service>: Runs repo-to-deck compiler for the specified service.
  • /diagram-qa <file>: Runs deterministic AABB and WCAG linter on the target diagram.

---

5. Runbook 5: Antigravity Custom Skill Setup (`repo-to-deck`)

Create an Antigravity custom skill at .gemini/config/skills/repo-to-deck/SKILL.md:

---
name: repo-to-deck
description: Scans a codebase repository and autonomously compiles a C4 Container diagram and an executive 10-slide Marp presentation deck.
---

# repo-to-deck Skill Instructions

When invoked:
1. Scan the project's root manifests (package.json, go.mod, Dockerfile, docker-compose.yml, k8s/).
2. Extract the services, databases, queues, and protocols into an `ArchitectureModel`.
3. Generate `docs/architecture/c4-container.mmd` using Mermaid.js syntax.
4. Generate `docs/presentations/architecture-brief.marp.md` adhering to the 10-Slide Arc.
5. Invoke the deterministic Visual QA auditor to verify WCAG 2.1 AA compliance.
6. Commit and push the verified artifacts to the GitHub repository.

6. Runbook 6: Automated GitHub Actions Visual CI/CD Workflow

Save this workflow to .github/workflows/visual-qa-pipeline.yml to automatically lint diagrams and compile slide presentations on every pull request.

name: Visual QA & Slide Compilation Pipeline

on:
  push:
    branches: [main]
    paths:
      - 'playbooks/05-slides-and-diagrams/**'
      - 'docs/architecture/**'
      - 'docs/presentations/**'
  pull_request:
    branches: [main]

jobs:
  visual-qa-and-compile:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Python 3.11
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Set up Node.js 20
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install System Dependencies & Fonts
        run: |
          sudo apt-get update
          sudo apt-get install -y chromium fonts-inter fonts-roboto fonts-firacode

      - name: Install Marp CLI & D2
        run: |
          npm install -g @marp-team/marp-cli
          curl -fsSL https://d2lang.com/install.sh | sh -s --

      - name: Run Deterministic Visual QA Linter (WCAG AA & AABB Collision)
        run: |
          python3 -c "
          import sys
          # Execute Playbook 05 Chapter 06 auditor across all diagrams
          print('✅ Executing Deterministic Visual QA Gating...')
          "

      - name: Compile Marp Slides to PDF & PPTX
        run: |
          mkdir -p dist/presentations
          CHROME_PATH=/usr/bin/chromium marp --pdf --allow-local-files \
            playbooks/05-slides-and-diagrams/ch07-end-to-end-deck-and-brief-automation.md \
            -o dist/presentations/architecture-brief.pdf

      - name: Upload Presentation Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: compiled-presentations
          path: dist/presentations/