# AGENTS.md

Guidance for coding agents working in this repository.

## Scope

This project is a small Flask application with a mostly client-side calculator UI. Treat it as an internal tool with sensitive access and product data assumptions.

Primary files:

- `app.py`: Flask app, HTTP Basic Auth, routes, access logging.
- `templates/roll_calculator.html`: active calculator UI, inline CSS, inline JavaScript, disclaimer gate, roll calculations, forklift check, load optimizer.
- `static/article-data.json`: active product/article data loaded by the UI.
- `static/config.json`: richer forklift/heavy-roll configuration, although the active template also contains inline config.
- `README.md`: developer-facing project overview.
- `PROJECT_KNOWLEDGE.md`: project-specific domain and implementation knowledge.

## Working Rules

- Before larger changes, present a concise plan.
- Do not change functional logic unless explicitly requested.
- Keep edits narrowly scoped to the requested task.
- Do not remove existing features or routes without explicit approval.
- Do not add Python packages without approval.
- Do not change existing APIs, route paths, data formats, or authentication behavior without approval.
- Do not manually edit generated product data unless the user explicitly asks for data maintenance.
- Do not add new article-data administration features to RollCalc; propose a separate app or integration boundary instead.
- Preserve login/access logging unless the user explicitly asks to change or remove it.
- Preserve the current Flask/vanilla JavaScript architecture unless the task is specifically a refactor.
- Prefer documenting observed behavior over assuming intended behavior.

## Planned Direction

- The existing admin UI/API in RollCalc is planned for removal.
- Do not expand or repair the admin area unless explicitly requested as a temporary measure.
- Keep login/access logging in RollCalc.
- Administration and maintenance of `article-data.json` should move to a separate application.
- Treat `templates/admin.html` and `/api/admin/*` expectations as legacy/transitional, not as target architecture.

## Code Style

- Python should follow PEP 8.
- JavaScript should use modern ES6 style where it fits the existing code.
- Keep comments sparse and useful.
- Use clear names over explanatory comments where possible.
- Avoid broad refactors in `templates/roll_calculator.html`; it is large and risk-prone.

## Validation Expectations

For backend or template changes:

- Start the app locally when practical.
- If port `5000` is occupied, use:

```bash
flask --app app run --host 127.0.0.1 --port 5001
```

- Check authenticated endpoints with Basic Auth when practical.
- For pure documentation changes, no runtime validation is required.

Known local credential currently present in `app.py`:

```text
mtazl / rollcalc
```

These credentials are hardcoded and are a known risk; do not introduce more secrets.

## Important Technical Constraints

- `app.py` currently hardcodes users and passwords.
- Access logging writes to `access_log.json` by reading and rewriting the whole file.
- The active UI logic is largely inline in `templates/roll_calculator.html`.
- Several `static/*.js` files appear to be older, alternative, or integration modules. Confirm script inclusion before modifying them.
- The admin template and backend admin routes are inconsistent and scheduled for removal rather than expansion.
- The disclaimer confirmation is client-side only.

## Safety Notes

- Treat `static/article-data.json` as generated ERP-derived data.
- The project contains product/material assumptions. Do not adjust formulas, thresholds, or category rules without a specific request.
- The calculator output is advisory and requires plausibility checks before use.