adding agents.md file

AGENTS.md

@@ -0,0 +1,98 @@
+# AGENTS.md
+
+## Purpose
+
+This document outlines general practices and expectations for AI agents assisting with the development of `ngxstat`, a hybrid log analytics tool for Nginx. The agent’s role includes writing code, testing functionality, and generating documentation, with particular attention to the following technologies and design choices.
+
+## Project Overview
+
+**Project Name**: `ngxstat`
+**Goal**: Per-domain log analysis for Nginx with a hybrid of statically generated reports and lightweight live JSON API endpoints.
+
+---
+
+## Stack & Tooling
+
+### Python
+- Version: 3.10+ recommended
+- Project isolation: Use `venv`
+  ```bash
+  python -m venv .venv
+  source .venv/bin/activate
+````
+
+* Dependency management: Use `requirements.txt` or `pip-tools`
+* Use standard libraries where feasible (e.g., `sqlite3`, `argparse`, `datetime`)
+* Adopt `typer` for CLI command interface (if CLI ergonomics matter)
+
+### SQLite
+
+* Used for log ingestion and aggregation
+* Prefer raw SQL or use lightweight ORM (e.g., `dataset`, `sqlite-utils`) only if necessary
+* Index columns used in groupings (e.g., timestamp, domain, status, cache result)
+
+### Charting: Chart.js
+
+* Use latest CDN version for embedded dashboards
+* Charts should be rendered from pre-generated JSON blobs in `/json/`
+
+### Styling: Bulma CSS
+
+* Use via CDN or vendored minified copy (to keep reports fully static)
+* Stick to default components (columns, cards, buttons, etc.)
+* No JS dependencies from Bulma
+
+### Icon Set: [Feather Icons (CC0)](https://feathericons.com/)
+
+* License: MIT / CC0-like
+* Use SVG versions
+* Download as:
+
+  * Individual SVGs in `/static/icons/`, or
+  * Pre-bundled sprite/minified set if needed
+
+---
+
+## 📄 File Structure Guidelines
+
+```plaintext
+ngxstat/
+├── scripts/            # Log importers, SQLite tools
+├── templates/          # Jinja2 templates for static page generation
+├── static/             # CSS, JS, icons (Chart.js, Bulma, icons)
+├── output/             # Generated reports
+├── database/           # SQLite DBs and schema migrations
+├── api/                # Lightweight live API server (Flask/FastAPI)
+├── AGENTS.md           # This file
+├── README.md
+```
+
+---
+
+## Agentic Behavior Expectations
+
+* **Code must be modular and documented.**
+* **Use consistent naming and formatting.**
+* **Err on the side of clarity over cleverness.**
+* **Avoid introducing unnecessary dependencies.**
+* **Validate SQL statements when modifying schema.**
+* **Verify that logs parse cleanly and reject malformed lines.**
+
+If uncertain, the agent should prompt the human for clarification before making architectural assumptions.
+
+---
+
+## Future Capabilities
+
+As the project matures, agents may also:
+
+* Suggest aggregation logic (e.g., bot detection, per-path stats)
+* Help build a Dockerized deployable version
+* Expand dashboard with new view types or filters
+* Integrate log format autodetection heuristics
+
+---
+
+## Changelog
+
+* **2025-07-17**: Initial version by Jordan + ChatGPT