Add AGENTS.md with architecture and development guidelines

AGENTS.md

@@ -0,0 +1,113 @@
+# AGENTS.md - LLM Context Memory Calculator
+
+## Quick Reference
+
+```bash
+# Just open index.html in a browser - no build process needed
+# or serve with any static file server
+```
+
+## Architecture Overview
+
+**Pure client-side application** - Single HTML file with embedded CSS/JS. No build tools, no frameworks.
+
+```
+index.html
+├── css/styles.css          # ~380 lines, retro design
+└── js/
+    ├── app.js              # Main app, event handling, translations
+    └── calculation.js      # Pure calculation functions
+```
+
+## Key Facts
+
+### Calculation Formula
+```
+Memory = context_length × effective_layers × kv_heads × head_dim × (bK + bV) × parallel
+
+where:
+- effective_layers = layers / full_attention_interval (if specified)
+- bK, bV = quantization sizes per element
+- parallel = number of concurrent sequences (default: 1)
+```
+
+### Quantization Sizes (bytes per element)
+```
+f32: 4.0
+f16: 2.0
+bf16: 2.0
+q8_0: 34/32 = 1.0625
+q4_0: 18/32 = 0.5625
+q4_1: 20/32 = 0.625
+iq4_nl: 18/32 = 0.5625
+q5_0: 22/32 = 0.6875
+q5_1: 24/32 = 0.75
+```
+
+### HuggingFace Config Format
+- Expected structure: `config.json` from `https://huggingface.co/{model}/resolve/main/config.json`
+- **Critical**: Must use `/resolve/main/` endpoint, NOT `/blob/main/`
+- Config may be nested under `text_config` (e.g., Qwen3.5 models)
+- Required fields (check both top-level and `text_config`):
+  - `num_hidden_layers`
+  - `num_key_value_heads`
+  - `head_dim` (or calculate as `hidden_size / num_attention_heads`)
+
+## Common Pitfalls
+
+### 1. Config Parsing
+- ConfigParser checks BOTH `config` and `config.text_config`
+- Don't forget to check nested structure for newer models
+
+### 2. Tooltip Re-initialization
+After clearing tooltips with `clearAllTooltips()`, always call:
+```javascript
+updateTooltips();
+```
+Otherwise tooltips will be empty.
+
+### 3. Error Icon Styling
+Error icons must have:
+- Black background: `#000000`
+- White text: `#FFFFFF`
+- Blue hover: `#0000FF`
+- Tooltip popup must be re-created after language change
+
+### 4. Optional Fields Without Errors
+Fields with default values should NOT show error icons:
+- `parallel` (default: 1)
+- `model-size` (default: 0)
+- `full-attention` (optional)
+
+### 5. Model Input Error Icon
+The `hf-model` input's error icon is placed differently in HTML:
+```html
+<input id="hf-model" ...>
+<button>...</button>
+<span class="error-icon">!</span>
+```
+Selector must use `#hf-model + .error-icon`, not `#hf-model ~ .error-icon`
+
+## File Changes
+
+### Adding New Translations
+1. Add to `translations.ru` and `translations.en` objects
+2. Add `data-key="key_name"` attribute to HTML element
+3. Update `updateText()` if needed
+
+### Adding New Input Fields
+1. Add HTML element with proper id
+2. Add error icon: `<span class="error-icon" style="display:none; margin-left: 5px;">!</span>`
+3. Add to `ConfigParser.parse()` if used for config parsing
+4. Add to `showConfigErrors()` selector if needed (use `+` for hf-model)
+
+## Testing Checklist
+
+- [ ] Config upload works with nested structure (e.g., Qwen3.5)
+- [ ] HuggingFace fetch works with `/resolve/main/` URL
+- [ ] 404 errors show "Model not found"
+- [ ] Tooltips persist after config parsing
+- [ ] Error icons appear for missing required fields
+- [ ] Error icons don't appear for optional fields
+- [ ] Language toggle updates all translations including tooltips
+- [ ] Reset button clears all fields including model name