CrumbCodex-v.0.0/CLAUDE.md

# 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

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

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

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

```bash
# 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
```bash
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
```bash
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.