From 3c239e68f3fd2e755b0ceb61500e98b621d5f7ab Mon Sep 17 00:00:00 2001
From: phg <mail@philip-henning.com>
Date: Thu, 14 Aug 2025 08:04:04 +0200
Subject: [PATCH] feat: Add CLAUDE.md for project documentation and guidance

---
 CLAUDE.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..904d2aa
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Go TUI application for managing `/etc/hosts` files using the Bubble Tea framework. The app provides a two-pane interface (list view + detail view) for viewing, editing, and managing host entries with features like activation/deactivation, sorting, and DNS resolution.
+
+## Architecture
+
+The codebase follows a clean architecture pattern with separation of concerns:
+
+- `cmd/hosts/main.go` - Entry point that parses `/etc/hosts` and launches the TUI
+- `internal/core/` - Core business logic and data models
+  - `models.go` - Data structures for HostEntry and HostsFile with validation
+  - `parser.go` - Hosts file parsing, formatting, and writing with intelligent formatting detection
+- `internal/tui/` - Bubble Tea TUI components
+  - `model.go` - Main Bubble Tea model with pane navigation and mode management
+  - `view.go` - Rendering logic for the two-pane interface
+  - `update.go` - Message handling and state updates
+- `tests/` - Test files following TDD approach
+
+## Key Technical Patterns
+
+### Data Models
+- `HostEntry` represents individual host entries with IP, hostname, aliases, comments, and active status
+- `HostsFile` contains collections of entries with methods for searching, adding, and removing
+- All models include validation methods and proper error handling
+
+### TUI Architecture
+- Uses Bubble Tea's Model-View-Update pattern
+- Two-pane layout with list and detail views
+- Mode switching between ViewMode and EditMode
+- Pane focus management (listPane/detailPane)
+
+### File Operations
+- Intelligent formatting detection preserves original hosts file style
+- Atomic file operations with backup creation
+- Proper validation before writing changes
+
+## Development Commands
+
+### Build and Run
+```bash
+go run cmd/hosts/main.go
+go build -o hosts cmd/hosts/main.go
+```
+
+### Testing
+```bash
+go test ./...                    # Run all tests
+go test ./tests/                 # Run tests in tests directory
+go test -v ./internal/core/      # Run core package tests with verbose output
+go test -cover ./...             # Run tests with coverage
+```
+
+### Dependencies
+Key dependencies are managed via `go.mod`:
+- Bubble Tea framework for TUI
+- Bubbles for common components
+- Lip Gloss for styling
+- testify for test assertions
+
+## Important Implementation Details
+
+### Hosts File Parsing
+The parser in `internal/core/parser.go` handles:
+- Active and inactive (commented) entries
+- Inline comments preservation
+- Intelligent formatting detection (tabs vs spaces)
+- IPv4/IPv6 address validation
+- RFC-compliant hostname validation
+
+### TUI Navigation
+- Tab/Shift+Tab for pane switching
+- Arrow keys for list navigation
+- Space for toggling entry activation
+- 'q' to quit application
+
+### Error Handling
+- Comprehensive validation at model level
+- Parse warnings collection during file parsing
+- Graceful error recovery in TUI operations
+
+## Memory Bank Integration
+
+This project uses Cline's Memory Bank system located in `memory-bank/` directory. The project brief and context files provide additional architectural context and development history. Always consult these files when making significant changes to understand the project's evolution and design decisions.
\ No newline at end of file