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