added CLAUDE.md

Author: dg

CLAUDE.md

@@ -0,0 +1,174 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the official documentation repository for the Nette PHP framework ecosystem. It contains technical documentation for 31 packages across 16+ languages, written in Texy markup format and published at nette.org, doc.nette.org, latte.nette.org, tester.nette.org, and tracy.nette.org.
+
+## CRITICAL: Language Version Rules
+
+**⚠️ MOST IMPORTANT: All edits and changes MUST ONLY be made to `/cs/` and `/en/` language versions!**
+
+### Strict Synchronization Requirements
+
+1. **Edit only `/cs/` and `/en/` versions** - Never directly edit other language variants (de, fr, es, ru, etc.)
+2. **Perfect line alignment** - `/cs/` and `/en/` must have identical line counts and structure
+   - Same information must be on the same line number in both versions
+   - Example: Line 14 in `application/en/presenters.texy` corresponds to line 14 in `application/cs/presenters.texy`
+   - Both files must have exactly the same number of lines (e.g., both have 510 lines)
+3. **Same file sets** - `/cs/` and `/en/` must contain exactly the same `.texy` files
+4. **Automatic translation** - Other language variants (de, fr, es, etc.) are translated automatically from `/en/` or `/cs/` using DeepL
+5. **Verification** - Use `php verifyLineAlignment.php` to check line synchronization across language versions
+
+### Why This Matters
+
+The translation system relies on line-by-line correspondence between `/cs/` and `/en/`. When these versions are perfectly aligned:
+- Automated translation tools can map content accurately
+- Changes propagate correctly to all 16+ language variants
+- Documentation consistency is maintained across all languages
+
+**Before any edit:**
+- Check that both `/cs/` and `/en/` files exist
+- Ensure line counts match: `wc -l package/en/file.texy package/cs/file.texy`
+- Make parallel changes to maintain synchronization
+
+## Documentation Structure
+
+Documentation is organized by package, language, and article:
+
+```
+<package>/
+├── en/              # English version (primary language)
+├── cs/              # Czech version
+├── de/, fr/, ...    # Other language variants
+├── files/           # Shared images and assets
+└── meta.json        # Package metadata (version, repo, composer name)
+```
+
+### Complete Package Inventory (31 packages, 233 files in /en)
+
+**Core Framework (77 files):**
+- `application/` (14 files) - MVC framework, presenters, routing, components
+- `bootstrap/` (2 files) - Application initialization and configuration
+- `component-model/` (2 files) - Component system and lifecycle
+- `dependency-injection/` (14 files) - DI container, autowiring, services
+- `forms/` (9 files) - Form creation, validation, rendering
+- `http/` (8 files) - HTTP request/response, sessions, URLs
+- `security/` (7 files) - Authentication, authorization, passwords
+- `caching/` (2 files) - Caching mechanisms
+- `mail/` (2 files) - Email sending
+- `nette/` (9 files) - Main documentation hub, glossary, installation
+- `quickstart/` (9 files) - Getting started tutorial
+
+**Templating & Content (44 files):**
+- `latte/` (33 files) - Templating engine v3.0+ with `/cookbook/` subdirectory (only package with nested structure)
+- `texy/` (11 files) - Texy markup language processor
+
+**Database & Data (28 files):**
+- `database/` (13 files) - Database access layer, Explorer, transactions
+- `dibi/` (3 files) - Dibi database abstraction layer
+- `migrations/` (10 files) - Database migrations and version upgrades
+- `schema/` (2 files) - Schema validation and generation
+
+**Utilities & Tools (47 files):**
+- `utils/` (23 files) - Arrays, strings, filesystem, validation, datetime
+- `tracy/` (11 files) - Debugger, dumper, extensions
+- `tester/` (12 files) - Testing framework with assertions and TestCase
+- `tokenizer/` (1 file) - PHP tokenizer
+
+**Code Generation & Processing (5 files):**
+- `php-generator/` (2 files) - PHP code generation
+- `robot-loader/` (1 file) - Automatic class loader
+- `safe-stream/` (1 file) - Safe stream handling
+- `neon/` (3 files) - NEON format parser
+
+**Supporting (20 files):**
+- `assets/` (5 files) - Asset management and Vite integration
+- `code-checker/` (1 file) - Code quality checker tool
+- `contributing/` (6 files) - Contribution guidelines and documentation standards
+- `best-practices/` (16 files) - Development patterns and recipes
+- `www/` (11 files) - Website content, logo, license, packages
+
+**Structure notes:**
+- **30 packages** have flat structure (files directly in `/en/` directory)
+- **1 package** has nested structure: `latte/` with `/cookbook/` subdirectory containing 8 additional files
+- All packages include `@home.texy` (entry point) and `@meta.texy` (metadata)
+- Most packages include `@left-menu.texy` or `@menu.texy` for navigation
+
+**Branch structure:**
+- `master` - Current documentation (latest versions)
+- `doc-3.x` - Version 3.x documentation
+- `doc-2.x` - Legacy 2.x documentation
+
+## File Format
+
+Documentation uses **Texy markup** (`.texy` files), a custom markup language for structured content. Files contain headings, paragraphs, and code blocks parsed by the utilities in the root directory.
+
+## Documentation Guidelines
+
+Follow Nette's documentation standards:
+- Start with simple concepts, progress to advanced topics
+- Test all code examples for accuracy
+- Use clear, concise language
+- Minimal use of highlighting and special formatting
+- Adhere to [Coding Standard] in code examples
+
+English is the primary language. Use DeepL Translator for translations, which will be reviewed by contributors.
+
+## Common Tasks
+
+**Adding a new documentation page:**
+1. **CRITICAL:** Create `.texy` file in BOTH `/en/` AND `/cs/` directories
+2. Ensure both files have the same structure and line count
+3. Follow existing structure (headings, code blocks, paragraphs)
+4. Add code examples with proper syntax highlighting
+5. Verify line alignment: `wc -l package/en/file.texy package/cs/file.texy`
+8. Run code-checker before committing
+
+**Editing existing documentation:**
+1. **CRITICAL:** Edit ONLY `/cs/` and `/en/` versions - never edit de, fr, es, ru, etc.
+2. Make parallel changes to both `/cs/` and `/en/` files
+3. Maintain identical line counts - add/remove lines in both files simultaneously
+4. Keep the same information on the same line numbers
+6. Other language variants will be updated automatically by the translation system
+
+### Example: Correct Way to Edit Documentation
+
+**❌ WRONG - Editing only one language:**
+```bash
+# Don't do this!
+vim application/en/presenters.texy
+# Edit only English version
+# Save and commit
+```
+
+**✅ CORRECT - Editing both synchronized versions:**
+```bash
+# Check current line counts
+wc -l application/en/presenters.texy application/cs/presenters.texy
+# Output: 510 application/en/presenters.texy
+#         510 application/cs/presenters.texy
+
+# Edit both files in parallel
+vim application/en/presenters.texy application/cs/presenters.texy
+
+# After editing, verify line counts still match
+wc -l application/en/presenters.texy application/cs/presenters.texy
+# Output should still be: 510 510
+```
+
+**Example of line-by-line correspondence:**
+```
+application/en/presenters.texy:
+  Line 1: Presenters
+  Line 14: [We already know...
+  Line 510: (last line)
+
+application/cs/presenters.texy:
+  Line 1: Presentery
+  Line 14: [Už víme...
+  Line 510: (last line)
+```
+
+Both files have identical structure, same number of lines, same information on corresponding lines - only the language differs.