Initial commit: Flask quiz game 'Уроки французского'

AGENTS.md

@@ -0,0 +1,164 @@
+# AGENTS.md - Guidelines for Agentic Coding
+
+## Project Overview
+
+This is a simple Flask web application - a "Jeopardy-style" quiz game about the Russian short story "Уроки французского" by Valentin Rasputin. The project uses:
+- **Backend**: Python 3.13 with Flask
+- **Frontend**: HTML, CSS, JavaScript (vanilla)
+- **Data Storage**: JSON file (`data/questions.json`)
+- **State**: Browser localStorage (client-side)
+
+## Build/Test Commands
+
+### Running the Application
+
+```bash
+# Activate virtual environment
+source venv/bin/activate
+
+# Run Flask app (default port 5000)
+python app.py
+
+# Run on specific port
+python -c "from app import app; app.run(port=5002)"
+```
+
+### No Formal Tests
+
+This project does not have a formal test suite. For manual testing:
+- Use `curl` to test API endpoints
+- Test in browser at http://localhost:5000 (or configured port)
+
+### Linting/Type Checking
+
+No formal linter is configured. The codebase uses basic Python and JavaScript.
+
+## Code Style Guidelines
+
+### Python (app.py)
+
+**Imports**
+- Standard library first, then third-party
+- Use absolute imports
+- Example:
+  ```python
+  import json
+  from flask import Flask, render_template, request, redirect, url_for, make_response
+  ```
+
+**Formatting**
+- Use 4 spaces for indentation
+- Maximum line length: 100 characters
+- Blank lines: 2 between top-level definitions, 1 between function definitions
+
+**Naming Conventions**
+- `snake_case` for variables, functions
+- `PascalCase` for classes
+- `UPPER_SNAKE_CASE` for constants
+
+**Error Handling**
+- Use try/except for file operations (JSON loading/saving)
+- Return proper HTTP error codes (400, 404, 500)
+- Log errors to console
+
+**Flask-Specific**
+- Use `app.secret_key` for sessions
+- Always use `ensure_ascii=False` with JSON for Cyrillic support
+- Use `context_processor` for global template variables
+
+### JavaScript (templates/*.html)
+
+**General**
+- Use vanilla JavaScript (no frameworks)
+- Prefer `var` over `let/const` for compatibility
+- Use `function` keyword instead of arrow functions where possible
+
+**Event Handling**
+- Use `onclick` directly in HTML or `element.onclick = function()` 
+- Avoid `addEventListener` for simplicity
+
+**DOM Manipulation**
+- Use `document.getElementById` and `document.querySelector`
+- Template literals for dynamic content: `` `string ${variable}` ``
+- Use `JSON.parse()` and `JSON.stringify()` for localStorage
+
+**Naming**
+- camelCase for variables and functions
+- Descriptive names (e.g., `currentTeam`, `selectAnswer`)
+
+### HTML/CSS (templates/*.html)
+
+**Template Syntax (Jinja2)**
+- Use `{% for %}` loops with `enumerate()` for indexed iteration
+- Pass data via `{{ variable }}` syntax
+- Use `|tojson` filter for JavaScript data
+
+**CSS**
+- Use CSS custom properties (variables) for colors
+- Follow BEM-like naming for classes
+- Keep responsive design in mind
+
+**Structure**
+- Inline CSS in `<style>` tags (simple project)
+- Inline JS in `<script>` tags at end of body
+
+## File Organization
+
+```
+/home/eof/dev/roma/sigra/
+├── app.py              # Flask application
+├── data/
+│   └── questions.json  # Game questions data
+├── templates/
+│   ├── index.html      # Main game page
+│   ├── admin.html      # Admin panel (edit questions)
+│   ├── edit.html       # Question editor
+│   └── login.html      # Admin login
+├── static/             # Static assets (empty currently)
+├── venv/               # Virtual environment
+├── SPEC.md             # Project specification
+└── AGENTS.md          # This file
+```
+
+## Common Patterns
+
+### Adding a New Question
+1. Edit `data/questions.json` manually or via admin panel at `/admin`
+2. Follow existing structure:
+   ```json
+   {
+       "cost": 600,
+       "question": "Question text?",
+       "options": ["Option 1", "Option 2", "Option 3", "Option 4"],
+       "answer": 0  // 0-3 index of correct answer
+   }
+   ```
+
+### Adding a New Route
+1. Add route in `app.py` using `@app.route()`
+2. Return `render_template()` or `jsonify()`
+3. For API routes, use proper HTTP methods
+
+### Modifying Game Logic
+- Game state stored in browser's localStorage
+- Key: `francuzskiy_game`
+- Structure: `{ score: 0, answered: [], userAnswers: {}, teams: [] }`
+
+## Security Notes
+
+- Admin panel is password-protected (password in `app.py`)
+- No database - data is in JSON file
+- No SQL injection risk (no database)
+- XSS: Be careful with `innerHTML` - user input in questions is trusted
+
+## Dependencies
+
+```
+Flask==3.1.3
+Jinja2==3.1.6
+Werkzeug==3.1.6
+```
+
+## Contact
+
+For questions about this codebase, refer to SPEC.md or the original requirements.