# 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
```bash
# 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
```bash
# 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):

```ini
# 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`