1 files changed, 39 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..061abd4
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,39 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+`app.py` is the Streamlit entrypoint and wires the sidebar, top-of-page sections, and main tabs together. UI sections live in `components/` (`overview.py`, `valuation.py`, `top_movers.py`, etc.). Data access and finance logic live in `services/`, with `data_service.py` handling most `yfinance` work and `valuation_service.py` containing DCF and EV/EBITDA calculations. Shared formatting helpers are in `utils/`. Static assets such as the logo live in `assets/`.
+
+There is currently no dedicated `tests/` directory. If you add tests, place them under `tests/` and mirror the source layout where practical.
+
+## Build, Test, and Development Commands
+Use the local virtual environment before running anything:
+
+```bash
+source .venv/bin/activate
+pip install -r requirements.txt
+streamlit run app.py
+```
+
+- `pip install -r requirements.txt`: installs Streamlit, Plotly, `yfinance`, and supporting libraries.
+- `streamlit run app.py`: starts the dashboard locally at `http://localhost:8501`.
+- `python -m py_compile app.py components/*.py services/*.py utils/*.py`: quick syntax check across the codebase.
+
+## Coding Style & Naming Conventions
+Follow existing Python style: 4-space indentation, descriptive snake_case for functions and variables, and short module-level docstrings. Keep render functions named `render_<section>()` inside `components/`. Prefer small helper functions for repeated UI patterns. Match the repo’s current approach: light comments, defensive fallbacks around API data, and `@st.cache_data` for expensive fetches.
+
+No formatter or linter is configured in the repo today, so keep changes stylistically consistent with neighboring files.
+
+## Testing Guidelines
+There is no automated test suite yet. For UI or data-flow changes, run the app locally and verify the affected tab or section with a few tickers. At minimum, run targeted syntax checks with `python -m py_compile <file>`. If you add nontrivial finance logic, include unit tests in `tests/` and cover both normal and missing-data cases.
+
+## Commit & Pull Request Guidelines
+Use short, imperative commit messages like `Add top movers section` or `Fix EBITDA consistency bug`. Keep each commit focused on one user-visible change or bug fix.
+
+For pull requests, include:
+- a clear summary of what changed and why
+- any data-source or API-key impact
+- screenshots or short screen recordings for UI changes
+- manual verification notes (example tickers tested, tabs checked)
+
+## Security & Configuration Tips
+Store API keys in `.env`; do not commit secrets. Prism can run partially without `FMP_API_KEY` and `FINNHUB_API_KEY`, so document any new required configuration in `README.md`.