RollCalcPython/AGENTS.md

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 previous admin UI/API has been removed from RollCalc.
• Do not reintroduce admin screens or admin APIs 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 article-data administration as out of scope for RollCalc.

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:

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:

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 previous admin template and backend admin route have been removed; do not rebuild them by default.
• 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.