AGENTS.md

# Repository Guidelines

## Project Structure & Module Organization
- `core/`, `memory/`, `learning/`, `reasoning/`, `safety/`, `training/` hold the primary Python packages referenced in `pyproject.toml`.
- Top-level orchestrators and demos live at the repo root (for example `main_orchestrator.py`, `run_onboarding.py`, `demo_*`).
- Web UI assets are under `dashboard/` and `dashboard-v3/` (frontend tooling and static assets).
- Tests are in `tests/` plus root-level `test_*.py` integration checks.
- Supporting material lives in `docs/`, `datasets/`, `research/`, and `scripts/`.

## Build, Test, and Development Commands
- `python -m venv venv && source venv/bin/activate` creates an isolated Python env.
- `pip install -r requirements.txt` installs runtime dependencies.
- `pip install -e ".[dev]"` installs dev tools (pytest/black/flake8/mypy).
- `python main_orchestrator.py` runs the primary orchestration flow.
- `python run_onboarding.py` launches the onboarding flow for profiles.
- `cd dashboard && npm install && npm run dev` starts the dashboard (adjust path if using `dashboard-v3`).

## Coding Style & Naming Conventions
- Indentation: 4 spaces for Python; keep line length at 100 (Black default).
- Naming: `snake_case` for functions/variables/files, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants.
- Format/lint locally with `black .` and `flake8` before major changes.

## Testing Guidelines
- Pytest is the standard runner; use `pytest` to execute the full suite.
- Test discovery follows `tests/` plus `test_*.py` at repo root; name new tests `test_<feature>.py`.
- Prefer focused tests (`pytest tests/test_feature.py -k case_name`) when iterating.

## Commit & Pull Request Guidelines
- Commit history favors short, imperative summaries, sometimes with a type prefix like `feat:` or `fix:`.
- Keep commits scoped to one logical change; mention benchmarks or demos impacted.
- PRs should include a clear summary, list of tests run, and screenshots for UI changes.

## Configuration & Secrets
- Runtime config is sourced from `.env`; use `.env.example` as the template.
- Never commit API keys or personal tokens; document required env vars in PRs when adding new ones.

## Skills Catalog
- Full merged skills from QuLabInfinite, `echo_prime`, and `achlys` are tracked in `docs/merged_skills_catalog.md`.
- Machine-readable merged skills are tracked in `docs/merged_skills_catalog.json`.
- Rebuild the catalog with: `python scripts/build_skill_catalog.py`