Tools & Utilities Reference¶

Complete reference for the Python tools, shell scripts, and Makefile targets available in this repo.

Training Tools¶

Study & Practice¶

Tool	Description	Run with
`run_training_session.py`	Mixed-mode session runner (flashcards, quiz, scenarios). Supports drill manifests, SM-2 spaced repetition, and retry for weak items.	`make run-training-session`
`run_case_study.py`	Case study review runner — 60 case studies across 4 domains.	`python3 tools/run_case_study.py list`
`run_scenario.py`	Incident response drill runner with step-by-step mode and filtering.	`make scenario`
`run_trivia.py`	Interactive "Did you know?" trivia sessions for DevOps topics.	`python3 tools/run_trivia.py`
`quiz.py`	Interactive quiz runner from the quiz bank.	`python3 tools/quiz.py`
`build_study_plan.py`	Generate time-budgeted study plans with 10 named presets. Auto-selects based on SM-2 state.	`make build-study-plan`
`recommend_training_session.py`	Recommend what to study next based on SM-2 due items, weak areas, and coverage gaps.	`make recommend-training-session`
`report_training_progress.py`	Progress and weakness reporting with recommendations.	`make report-training-progress`

Validation¶

Tool	Description	Run with
`validate_registry.py`	Validate the canonical asset registry (`assets.yaml`).	`make validate-registry`
`validate_flashcards.py`	Validate flashcard TSV decks (schema, IDs, duplicates). Supports `--strict`.	Part of `make validate-training-assets`
`validate_quiz_bank.py`	Validate quiz bank YAML (schema, topic cross-ref). Supports `--strict`.	Part of `make validate-training-assets`
`validate_scenarios.py`	Validate scenario YAML files (schema, IDs, fields). Supports `--strict`.	Part of `make validate-training-assets`
`validate_drills.py`	Validate drill manifest YAML files (schema, sources, filters).	`make validate-drills`
`validate_trivia.py`	Validate trivia TSV decks (header schema, field counts, IDs).	`python3 tools/validate_trivia.py`
`validate_structure.py`	Validate repo structure and detect stale references across files, dirs, Makefile, CI.	`make validate-structure`
`check_portal_drift.py`	Check if generated portal files are out of date with the registry.	`make check-portal-drift`

Reporting & Audit¶

Tool	Description	Run with
`audit_training_assets.py`	Audit training assets for quality, coverage, and duplicates.	`make audit-training-assets`
`report_training_coverage.py`	Coverage gap analysis across flashcards, quizzes, scenarios, and docs.	`make report-training-coverage`
`report_topic_coverage_grid.py`	Topic-by-type coverage matrix showing which topics have primers, cards, quiz, etc.	`make report-topic-coverage-grid`
`report_case_study_graph.py`	Map case studies to derived flashcards, related quiz items, and scenarios.	`make report-case-study-graph`
`manage_profiles.py`	List, summarize, reset, or archive learner profiles.	`make manage-profiles`

Content Generation & Pipeline¶

Tool	Description	Run with
`gen_portal.py`	Regenerate portal files (levels, topics, exercise map, progress, catalog) from registry.	`make gen-portal`
`gen_wiki_nav.py`	Generate MkDocs nav, topic landing pages, breadcrumbs, and related sections.	`make gen-wiki-nav`
`gen_mkdocs_nav.py`	Generate the `nav:` section of `mkdocs.yml` from the registry.	`make gen-mkdocs-nav`
`gen_interactive_pages.py`	Generate wiki-browsable pages for flashcards, quiz, scenarios, and drills.	`make gen-interactive-pages`
`generate_training_candidates.py`	Derive candidate flashcards and quiz items from library markdown files.	`python3 tools/generate_training_candidates.py <dir>`
`derive_case_study_assets.py`	Derive flashcards from case study markdown (symptoms, questions, solutions).	`make derive-case-study-assets`
`promote_training_candidates.py`	Review and promote staged candidates to canonical assets with quality scoring.	`make promote-training-candidates`
`export_anki_starters.py`	Regenerate Anki-importable starter decks from canonical flashcards. Supports 5 export modes.	`make export-anki-starters`

Maintenance Utilities¶

Tool	Description	Run with
`normalize_cards.py`	Normalize flashcard outliers (expand one-word answers, strip leading `<br>` tags).	`python3 tools/normalize_cards.py`
`rejoin_split_cards.py`	Rejoin malformed/split flashcard rows (collects orphan lines back into parent).	`python3 tools/rejoin_split_cards.py`
`trim_outliers.py`	Trim bloated answers (>800 chars) and fix bloated questions (>200 chars).	`python3 tools/trim_outliers.py`
`strict_allowlist.py`	Shared helper for loading strict validation allowlists (used by validators).	Library — not called directly

Infrastructure Scripts¶

Scripts in devops/scripts/ for local cluster management and deployment.

Script	Description	Makefile Targets
`deploy-local.sh`	Deploy the grokdevops app to a local k3s/k3d cluster.	`make deploy-all`, `make undeploy-all`
`deploy-wiki.sh`	Build and deploy the wiki to GitHub Pages (`grokdevops-wiki` repo).	`make deploy-wiki`, `make deploy-wiki-dry`
`k3d-cluster.sh`	Manage a k3d (k3s-in-Docker) cluster for local development.	`make k3d-up`, `make k3d-down`, `make k3d-deploy`
`install-observability.sh`	Install Prometheus, Loki, Tempo, and Grafana on the cluster.	Referenced in observability guides
`install-argocd.sh`	Install ArgoCD with CLI configuration and app registration.	`make argocd-install`, `make argocd-uninstall`
`install-kyverno.sh`	Install Kyverno policy engine via Helm for admission control.	`make kyverno-install`, `make kyverno-uninstall`
`install-linkerd.sh`	Install Linkerd service mesh with auto-mTLS and viz extension.	`make linkerd-install`, `make linkerd-uninstall`
`install-postgres.sh`	Install PostgreSQL via Bitnami Helm chart (dev defaults).	`make postgres-install`, `make postgres-uninstall`
`install-vault.sh`	Install HashiCorp Vault in dev mode with Agent Injector.	`make vault-install`, `make vault-uninstall`
`workflow.sh`	Shared helper for infrastructure workflow scripts.	Library — sourced by other scripts

Key Makefile Targets¶

Run make help for the full list. Most commonly used:

# Testing
make test                           # Smoke + pytest (app only, fast)
make test-all                       # Full: lint + all tests + training lint + repo health

# Training validation
make validate-training-assets       # Run all 4 validators (normal mode)
make validate-training-assets-strict # Warnings as errors (CI gate)
make validate-registry              # Registry validation only

# Content generation
make gen-portal                     # Regenerate portal pages from registry
make gen-wiki-nav                   # Regenerate wiki nav and topic pages
make gen-mkdocs-nav                 # Regenerate mkdocs.yml nav section

# Wiki
make deploy-wiki                    # Build + deploy wiki to GitHub Pages
make deploy-wiki-dry                # Build only (no push)
make wiki-serve                     # Local preview server

# Study
make run-training-session           # Run a study session
make recommend-training-session     # What to study next
make build-study-plan               # Generate a study plan
make report-training-progress       # Progress report