# Repository Guidelines

## Project Structure & Module Organization
- `main.py` runs the CLI agent; `web_server.py` serves the Flask/SocketIO UI from `static/`.
- `core/` contains terminal orchestration (`main_terminal.py`, `web_terminal.py`) and should stay I/O-light.
- `modules/` collects reusable capabilities (file/search/memory/terminal); extend here before touching entrypoints.
- `utils/` provides API clients, context helpers, and logging; import from here instead of adding globals.
- `prompts/`, `data/`, and `project/` bundle prompt templates, fixtures, and demos used primarily for reference.
- `test/` stores integration helpers (`api_interceptor_server.py`, `test_deepseek_output.py`); add new suites alongside them.

## Build, Test, and Development Commands
- `pip install -r requirements.txt` installs Python dependencies.
- `python main.py` launches the CLI agent loop.
- `python web_server.py` serves the web UI at `http://localhost:8091`.
- `python test/api_interceptor_server.py` starts the mock proxy that logs traffic to `api_logs/`.
- `python test_deepseek_output.py` exercises streaming tool-calls; populate `config.py` with valid API credentials first.

## Coding Style & Naming Conventions
- Target Python 3.8+, 4-space indentation, `snake_case` functions, and `PascalCase` classes.
- Add type hints and concise docstrings that follow the existing bilingual tone.
- Use `utils.logger.setup_logger` for diagnostics; reserve `print` for intentional terminal output.
- Keep modules focused: add new features in dedicated `modules/` files with descriptive names.

## Testing Guidelines
- Prefer `pytest` for automation and name files `test/test_<feature>.py`, reusing assets in `data/` when relevant.
- For network flows, run `python test/api_interceptor_server.py` and point the app to the proxy to avoid external calls.
- Capture manual verification steps in PRs and add replay scripts under `test/` for repeated workflows.

## Commit & Pull Request Guidelines
- With no history yet, adopt Conventional Commits (`feat:`, `fix:`, `refactor:`) and keep summaries under 72 characters.
- Squash iterative commits; PRs should outline changes, touched modules, and validation.
- Link issues and attach UI captures or log snippets when behavior shifts.

## Security & Configuration Tips
- Keep real API keys out of git; override defaults via environment variables.
- Clean sensitive data from `api_logs/`, `logs/`, and `experiment_outputs/` before sharing.
- Extend `.gitignore` when new tooling produces temporary artifacts.
