# Repository Guidelines

## Project Structure & Module Organization
- Root contains `docker-compose.yml`, `.env` (local only), and helper scripts like `git_push.py` and `summarize_codebase.sh`.
- All Homepage configuration lives under `config/` (e.g., `bookmarks.*`, `services.*`, `settings.*`, `widgets.*`, `docker.*`).
- Example files (`*.example`) are the templates you should edit and then copy to `*.yaml` for local use; YAML files and `.env` are intentionally git-ignored.

## Build, Test, and Development Commands
- `docker compose up -d` — start or update the Dashboard stack in detached mode.
- `docker compose down` — stop and remove the stack (containers only).
- `docker compose logs homepage` — inspect the Homepage container logs for troubleshooting.
- `docker compose config` — validate the compose configuration before pushing.
- `./summarize_codebase.sh .` — optional helper to generate a local `codebase_summary.txt` (not committed).

## Coding Style & Configuration Conventions
- Prefer small, focused changes in `config/*.example` and keep `*.yaml` environment-specific.
- YAML: two-space indentation, lowercase keys with hyphen-separated words where possible.
- Python helpers use 4-space indentation and `snake_case` for functions; shell scripts follow existing style and use descriptive variable names.

## Testing Guidelines
- There is no automated test suite; rely on Docker commands for validation.
- Before opening a PR, run `docker compose config` and bring the stack up locally with `docker compose up -d` to ensure it boots cleanly.
- Manually verify the Dashboard UI loads and configured services/widgets appear as expected.

## Commit & Pull Request Guidelines
- Use short, descriptive, sentence-style commit messages (e.g., `Update services example for NPM`, `Add new bank icon`).
- Group related configuration and asset changes in a single commit; avoid mixing unrelated updates.
- PRs should include: a concise summary, a brief description of config or icon changes, any relevant screenshots of the Dashboard, and notes on how you validated the stack.

## Security & Secrets
- Never commit real secrets or host-specific details; `.env` and `config/*.yaml` are local-only and must not be added to Git.
- When sharing examples, sanitize domains, IPs, and tokens, and prefer updates to `*.example` files instead of real YAMLs.