# Repository Guidelines
This guide supports new agents contributing to `metal-kompanion`, the MCP backend for Kompanion. Follow these practices to keep the service buildable, testable, and easy to review.


source dev.env for envrionment variables.

## MCP Usage
- This project uses agentic-control-framework Use this for task planning

## Project Structure & Module Organization
- `src/` holds C++ code: `mcp/` for server facade and tool routing, `memory/` for embeddings contracts, `dal/` for persistence, and `policy/` for capability rules.
- `docs/` hosts design notes; `runtime/kom_runner.py` is the Python orchestrator for agent execution against Ollama; `db/` and `sql/` capture Postgres schemas.
- `docs/third_party` is a symlink to reference code and apidocs.
- Place sample payloads or fixtures under `tests/` (currently `tests/schemas/` for JSON samples). Generated artifacts live in `build/`.
- `src/cli` is a command line prompt interface that tests the memory integration and pattern
  substiton.
- `tools`

## Build, Test, and Development Commands
```bash
cmake -S . -B build          # configure with CMake 3.22+, targets C++20
cmake --build build -j       # compile the kom_mcp executable
ctest --test-dir build       # run CTest suites once they are defined
python3 runtime/kom_runner.py # exercise the runtime loop (requires OLLAMA_BASE)
```
Run the Python runtime from a virtualenv seeded with `pip install -r runtime/requirements.txt`.

## Coding Style & Naming Conventions
- C++20, clang/gcc friendly, 4-space indentation, braces on the same line (`class KomMcpServer {`).
- Classes use PascalCase; methods camelCase; private members keep the trailing underscore (`tools_`). Prefer `std::` types and RAII helpers over raw pointers.
- Keep headers lean: forward declare where possible and document non-obvious behavior with concise comments.

## Testing Guidelines
- Add unit or schema validation tests under `tests/`, mirroring the source tree (e.g., `tests/mcp/` for dispatcher tests).
- Register new tests with CTest via `add_test` in `CMakeLists.txt`; verify they pass with `ctest --output-on-failure`.
- Provide realistic JSON samples for new tools alongside schema updates to guard against regressions.

## Commit & Pull Request Guidelines
- Follow the existing `scope: message` pattern from git history (`docker: fix host ollama port`); keep messages imperative and present tense.
- Each PR should state intent, link relevant issues, and include before/after notes or screenshots when UI-adjacent runtime behavior changes.
- Mention how to reproduce test runs (`cmake --build`, `ctest`) and flag configuration or migration steps (e.g., `sql/` changes).

## Security & Configuration Tips
- Do not commit secrets; runtime state lives beneath XDG paths (`~/.local/state/kompanion`). Document any new env vars in `docs/`.
- When integrating new tools, ensure access control aligns with `policy/` capabilities and record expected journal entries in `runtime` docs.