# Repository Guidelines

## Project Structure & Module Organization
- `app.py`: Streamlit UI (entry point for the app).
- `main.py`: RSS fetching, rewrite, and WordPress upload logic.
- `utils/`: Helpers (image/article extraction, WP uploader, UI helpers).
- `pages/`: Streamlit pages (e.g., `01_feed_manager.py`, `log_viewer.py`).
- `data/`: JSON state (`articles.json`, `feeds.json`).
- `logs/`: Runtime logs (`rss_tool.log`).
- `docs/`: Project notes (e.g., roadmap).
- `__version__.py`: Version string written by `versioning.py`.

## Build, Test, and Development Commands
- Create env: `python -m venv .venv && source .venv/bin/activate`
- Install deps: `pip install -r requirements.txt`
- Run app: `streamlit run app.py`
- Version bump: `python versioning.py --level patch --push` (updates `__version__.py`, prepares `CHANGELOG.md`, creates tag; see `--help`).

## Coding Style & Naming Conventions
- Python 3.10+, PEP 8, 4-space indentation, type hints where practical.
- Modules and functions: `snake_case`; classes: `PascalCase`.
- Streamlit pages: numeric prefix for order, e.g., `pages/01_feature.py`.
- Keep functions small and pure in `utils/`; isolate I/O in app layers.
- Suggested tools (optional): Black (`black .`) and Ruff (`ruff check .`).

## Testing Guidelines
- Framework: pytest (recommended). Place tests under `tests/` with `test_*.py`.
- Unit tests for `utils/*`; light integration checks for `main.py` with temporary files.
- Run: `pytest -q`. Add coverage if needed (e.g., `pytest --cov=utils`).
- Test data: avoid mutating files in `data/`; use temp dirs or fixtures.

## Commit & Pull Request Guidelines
- Commits: imperative mood, concise; examples: `Add feed dedupe`, `Fix WP upload retry`, `Bump version to v1.7.0`.
- PRs: clear description, linked issue, screenshots/GIFs for UI changes, note env variables touched.
- Update `CHANGELOG.md` and bump version via `versioning.py` before release PRs.

## Security & Configuration Tips
- Required env: `OPENAI_API_KEY`, `WP_BASE_URL`, `WP_USERNAME`, `WP_PASSWORD` or `WP_AUTH_BASE64` (see `.env`).
- Never commit secrets; `.env` is git-ignored. Avoid hardcoded credentials; prefer `os.getenv`.
- Logs and data may contain content; do not commit `logs/` or large `data/` snapshots.