OZM-Keks-Handbuch-v1/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Crumbpages v2 is a documentation and learning system for system administration, combining educational content with operational tooling. The project uses the "Crumbforest" metaphor - representing knowledge as a forest where "Krümels" (crumbs) guide learners through admin paths.

This is a bash-centric repository focused on documentation and shell scripting for system operations, SSH security automation, and API tooling for the broader Crumbforest infrastructure.

Core Philosophy

The "Waldwächter" (Forest Guardian) approach emphasizes:

• Transparency over magic - Clear, readable code that can be explained to learners
• Simplicity over complexity - Minimal dependencies, straightforward patterns
• Education-first - All tools should be teachable and understandable
• Security by default - Automated security practices, especially around SSH

See crumbforest-manifesto-guardian.md for the full philosophy.

Repository Structure

Documentation (Crumbpages)

Educational documentation organized as numbered "paths" (crumbpage-XX-*.md):

• 20 crumbpages covering Linux fundamentals through advanced topics
• Template-based structure for consistency (crumbpage-template.md)
• Each page includes: concepts, hands-on exercises, troubleshooting, skill checks
• Progressive learning path from basic user management to kernel operations

Operational Scripts

Three main shell scripts provide system tooling:

1. crumbpages-doktor.sh (496 lines) - Main diagnostic and operational tool
2. ssh-agent-guard.sh (68 lines) - Production SSH security daemon
3. ssh-agent-screenlock_v4.sh (67 lines) - MATE desktop SSH integration

Meta Documentation

• CRUMBFOREST_PROJECT_INDEX.md - Complete project history and milestone tracking
• HANDBUCH.md - crumbpages-doktor.sh manual
• QUICKSTART.md - Quick reference for common operations
• Various tagebuch (diary) files tracking problem-solving journeys

Common Commands

Running the Main Tool

# Make executable (first time)
chmod +x crumbpages-doktor.sh

# Launch interactive menu
./crumbpages-doktor.sh

The doktor script provides 6 modules:

1. Git Workstation - Interactive git shell with health checks
2. DNS Doktor - DNS diagnostics and reporting
3. System Doktor - Host vitals (disk, RAM, OS info)
4. Web Tools - API testing (api_search, api_get, api_ask)
5. Remote Tools - SSH helpers and SCP uploads
6. Werkzeugkasten - Tool availability checks

SSH Security Scripts

# Start SSH agent guard (systemd/autostart)
./ssh-agent-guard.sh

# For MATE desktop integration
./ssh-agent-screenlock_v4.sh

Both scripts automatically:

• Kill and restart ssh-agent on screen lock
• Write to ~/.ssh-agent-screenlock.log
• Store agent environment in ~/.ssh/agent-environment
• Use fixed socket path ~/.ssh/agent.sock

Configuration

Environment Variables (.env)

The doktor script uses .env for configuration (auto-created on first run):

# API endpoints (for Crumbforest backend integration)
CRUMB_API_URL="http://localhost:8000"
CRUMB_API_TOKEN="changeme"

# SSH/Remote settings
CRUMB_SSH_USER="admin"
CRUMB_SCP_TARGET="backup.crumbforest.de:/var/backups"

# Qdrant vector DB
CRUMB_QDRANT_URL="http://localhost:6333"
CRUMB_QDRANT_KEY=""

Architecture Notes

Modular Shell Design

The crumbpages-doktor.sh follows a modular pattern:

• Each module is a bash function (e.g., git_doktor(), web_doktor())
• Interactive subshells use bash --rcfile with custom .rc files in /tmp
• Environment isolation via export and temp RC files
• Color-coded output using ANSI escape sequences

SSH Security Pattern

Both ssh-agent scripts implement "zero-trust on lock":

• Single purpose: Kill agent when screen locks
• Singleton enforcement: PID file prevents duplicate daemons
• Deep Work Mode: ssh-agent-guard.sh supports pause file for uninterrupted work
• Fixed socket path: Enables multiple terminals to share agent state
• MATE integration: Uses dbus-monitor for screensaver events

API Integration

Web Tools module provides curl wrappers for the Crumbforest backend:

• FastAPI backend at CRUMB_API_URL
• Bearer token auth when CRUMB_API_TOKEN is set
• Functions: api_search, api_get, api_ask, open_url
• Qdrant-specific helpers: q_health, q_list, q_info

Development Patterns

Shell Script Style

• Bash-native (no external frameworks)
• Functions over scripts-within-scripts
• Descriptive color variables (GREEN, BLUE, RED, YELLOW, CYAN)
• Heredocs for multi-line templates
• Error handling via explicit checks, not set -e

Documentation Style

• Markdown with emoji for visual anchoring
• Collapsible sections using <details> tags
• Code examples with inline comments
• "DO/DON'T" sections for best practices
• Skill check checklists at end of each page

Git Workflow

Standard git practices:

• Main branch: main
• Commit history shows iterative refinement ("Logs active", "magic!", "CleanUp Magic")
• Modified files tracked: doktor script and tagebuch entries

Context: The Broader Crumbforest

This repository is part of a larger ecosystem:

• CrumbCore v1: FastAPI + Qdrant RAG chat system (production)
• PHP CRM: Legacy system integration for child management
• RouterOS: Network integration for 500+ user deployment
• TTYD: Terminal containers for educational use

The bash scripts here serve as the "field tools" for administrators working across the full stack.

Working with This Codebase

When editing shell scripts:

• Test interactively before committing (scripts are meant to be run by humans)
• Preserve color scheme consistency
• Maintain module boundaries in doktor script
• Update HANDBUCH.md if adding/changing doktor modules

When editing crumbpages:

• Follow crumbpage-template.md structure exactly
• Maintain numbering scheme (crumbpage-##-topic.md)
• Include skill checks and hands-on exercises
• Cross-link to related pages in navigation footer

When debugging:

• Check .env configuration first
• Review logs: ~/.ssh-agent-screenlock.log for SSH issues
• Use doktor's System Doktor module for host diagnostics
• Git Workstation module has check_health for repo state

Security Considerations

• SSH agent scripts actively kill credentials on screen lock
• API tokens stored in .env (gitignored)
• No hardcoded credentials anywhere
• MATE screensaver hardening (lock-enabled true, lock-delay 0)
• Singleton daemon pattern prevents privilege escalation via duplicate processes

References

• Project history: CRUMBFOREST_PROJECT_INDEX.md
• Philosophy: crumbforest-manifesto-guardian.md
• Tool manual: HANDBUCH.md
• Quick commands: QUICKSTART.md