CLAUDE.md

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

Repository Overview

Crumbforest is a pedagogical educational platform combining terminal-based learning, Docker containerization, markdown documentation, and AI-powered teaching assistants. The project is written primarily in German and uses metaphors from nature ("Wald" = forest, "Krümel" = crumb) to make technology accessible to children.

This repository contains approximately 470+ markdown documentation files that describe:
- Educational concepts and philosophy
- Terminal interactions and user journeys
- System architecture and component specifications
- Character/role definitions (Eule, Fuchs, Snake, Dumbo, etc.)
- Build manifests and deployment logs

Core System Architecture

Multi-Container Docker Setup

The system runs as a Docker Compose application with:
- App Container: CakePHP 5 (PHP 8.3+) with Authentication & Markdown viewer
- Database: MariaDB with kuchenwald database
- Adminer: Database management interface (port 8081)
- TTYD Terminal: Web-based terminal interface (port 7681)

Key Routes & Endpoints

/markdowns/index              - Auto-index of all markdown files
/markdowns/view/:slug         - Individual markdown file viewer
/users/login                  - Authentication login page
/bin/cake tagcloud            - Generate TagCloud HTML
/bin/cake generate_token      - Create API tokens
/bin/cake kruemellog_builder  - Export logs as markdown

Access points:
- http://localhost:8080 - CakePHP application
- http://localhost:8081 - Adminer
- http://localhost:7681 - Terminal interface
- http://localhost:8080/tagcloud.html - Dynamic TagCloud

Core Components & File Locations

Markdown Content

  • Location: webroot/markdown/*.md
  • Auto-indexed and linkable via /markdowns/index
  • TagCloud generation from markdown metadata

Terminal System

  • Login script: /scripts/terminal_login.sh
  • Session wrapper: /scripts/session_wrapper.sh
  • Supported users: root, kruemel, jupiter, heimkind, robot
  • Terminal commands: nano, ls, mc, cat, mission, login

Vector Search & Indexing

  • Python venv: /opt/venvs/crumbforest/bin/python3
  • Qdrant collection: md_files
  • Tools:
  • vector → /opt/vector/cli.py
  • vector-index → /opt/gitea-md/index_md_qdrant.py
  • eule → /opt/eule/eule_rag.py
  • Logs: /var/log/crumb/vector.jsonl, /var/log/crumb/eule.jsonl
  • Cache directories: HF_HOME=/opt/cache/hf, SENTENCE_TRANSFORMERS_HOME=/opt/cache/st, TORCH_HOME=/opt/cache/torch

Snapshot Collector (CF Tools)

  • Base directory: /var/cf
  • Snapshots: /var/cf/snapshots/<Layer>/<Device>/
  • Index files: /var/cf/index/LAYER-DEVICE.txt

Logs

  • KrümelLogs: /var/www/html/tmp/kruemel_logs/gpt_log.json
  • Format: JSONL with timestamp, user, role, question, answer, model, tokens

AI Teaching Roles ("Specialist Roles")

The system uses metaphorical characters to make different technical domains approachable:

  • Dumbo (#dumbo #sql) - SQL interpreter, translates questions to SQL
  • Snake (#snake #python) - Python starter and idea generator
  • ASCII-Monster (#ascii #monster) - Visual terminal art creator
  • Bytebird (#bytebird #api) - REST/JSON/API explainer
  • Crabby (#crabby #rust) - Rust advisor focused on safety
  • Bugsy (#bugsy #debug) - Error message translator
  • Shellfinch (#shellfinch #bash) - Bash/terminal teacher
  • DockerDuke (#duke #docker) - Container/deployment guide
  • Eule (Owl) - Observer, wisdom keeper
  • Fuchs (Fox) - Path discoverer
  • Kreumeleule - Terminal guide

Common Development Workflows

Building and Running

# Build and start containers
docker-compose build
docker-compose up -d

# Access app container shell
docker exec -it <app-container> bash --login -i

# Reset environment and rebuild
./reset_to_null_and_rebuild.sh

The reset script performs:
- Container reset
- Volume cleanup
- SQL import
- TagCloud generation
- Log entries

Markdown Indexing Workflow

# Add or modify markdown files
# (no git pull required for local indexing)

# Re-index into Qdrant
vector-index

# Test vector search
vector info
vector search "search term" --k 5

# Test with Eule (context-only, no LLM)
eule --no-llm "question about content"

# Create snapshot backup
vector snapshot create --collection md_files
vector snapshot list --collection md_files

CF Tools (Snapshot Management)

# Check recent activity (last 60 minutes, Layer L1)
cf-tools recent L1 60

# Top 5 most active devices
cf-tools top L1 60 5

# Device statistics (text format)
cf-tools device L1 SVGA_ESP04

# Device statistics (JSON for monitoring)
cf-tools device-json L1 SVGA_ESP04 | jq

# Get latest file path
cf-tools last-file L1 SVGA_ESP10

# Find duplicate Layer/Device combinations
cf-tools dupe-ids

# Maintenance
cf-tools prune-empty       # Remove empty directories
cf-tools rebuild-index     # Rebuild index files
cf-tools fix-perms         # Fix permissions (sysop:sysop, 2775)

# Live monitoring (requires inotify-tools)
cf-tools follow L1 SVGA_ESP04

# Careful: purge old files
cf-tools purge L1 SVGA_ESP04 60  # older than 60 minutes

Terminal User Management

Users authenticate through the terminal login menu. The system supports:
- Internal user switching without external auth
- Session wrapper for privilege escalation
- Sudo configuration for specific scripts

# Start mission with session wrapper
/scripts/session_wrapper.sh /usr/local/bin/mission

# Or with sudo
sudo mission

Key Philosophical Concepts

The "Nullfeld" (Zero Field)

Represents the origin state, unlimited children's questions, and the starting point before access. Central to the pedagogical philosophy.

Transparency & Child-Friendliness

  • All interactions are logged in child-appropriate language
  • Metaphors from nature make technology accessible
  • Focus on exploration and learning through play

Roles as Resonance

Characters/roles emerge from resonance rather than pure function - each represents a domain, symbol, and attitude that provides child-appropriate access to technology.

Technical Notes

Authentication

  • Uses CakePHP AuthenticationPlugin
  • Login via email and password
  • Successful login grants access to all markdown views
  • Session validation via middleware

Markdown Processing

  • Frontmatter with slug, tags, lang, summary
  • Auto-generation of TagCloud visualization
  • Vector embedding for semantic search

Permissions

  • Cache directories: vectorbot:crumblog with 775
  • CF snapshots: sysop:sysop with 2775
  • Sudoers configuration in /etc/sudoers.d/crumbforest-tools

Environment Variables for Indexing

HF_HOME=/opt/cache/hf
SENTENCE_TRANSFORMERS_HOME=/opt/cache/st
TORCH_HOME=/opt/cache/torch
GIT_PULL=0  # Disable git pull during indexing

Troubleshooting Common Issues

Vector/Embedding Permission Errors

sudo install -d -m 775 -o vectorbot -g crumblog /opt/cache/hf /opt/cache/st /opt/cache/torch
sudo chown -R vectorbot:crumblog /opt/cache

Sudo Password Required

Check that wrapper scripts exactly match /etc/sudoers.d/crumbforest-tools entries.

Nano Not Found in Terminal

Always start shell as login + interactive: exec bash --login -i

Mission Script Fails

Use session wrapper or sudo: /scripts/session_wrapper.sh /usr/local/bin/mission

Git Credentials Prompt During Indexing

Set GIT_PULL=0 in wrapper or remove git pull from indexer script.

Project Culture

This project values:
- Poetic and metaphorical language in documentation
- Child-centered design thinking
- Transparency in all technical operations
- Forest/nature metaphors ("Wald", "Krümel", "Eule")
- Balance between technical precision and accessibility
- Community ("Crew") collaboration

Documentation often includes emotive language, philosophical reflections, and celebratory markers like "WUUUUHUUUUU!" which are integral to the project's identity.