# AGENTS.md

## Scope

This file applies to the Rust workspace at `digitemp-rrdgraph/`.

## Project Summary

- The binary provides three operational subcommands: `update`, `check-alert`, and `send-info`.
- The repository is a Cargo workspace with a CLI crate at the repository root and an internal library crate at `crates/core/` named `digitemp_rrdgraph_core`.
- The system depends on external commands and resources: `digitemp`, `rrdtool`, SMTP, JSON config files under `etc/`, Tera templates under `templates/`, generated graphs under `html/images/`, and RRD files under `db/`.

## Source Of Truth

- Treat this Rust repository as the sole implementation and documentation target.
- Preserve the CLI contract exposed by `src/main.rs`, the command modules under `src/commands/`, and the public interfaces exposed by `crates/core/src/lib.rs` unless the user explicitly requests a behavior change.
- Preserve the configuration schema in `etc/config.sample.json` unless the user explicitly asks for a breaking change.
- Preserve template variable names expected by `templates/*.tera` unless the templates are updated in the same change.

## Documentation And Language

- Write repository documentation such as `AGENTS.md`, `README.md`, and other project documents in English by default.
- When adding comments to source code, configuration files, templates, or scripts, write those comments in English.
- Keep user-facing configuration keys, template names, and command names stable unless the task explicitly requires a change.

## Change Priorities

- Prefer fixes at the behavior or interface boundary, not cosmetic refactors.
- Keep CLI behavior and config keys stable.
- Keep changes small and local to the affected command or library module.
- Avoid introducing new crates unless the standard library or existing dependencies are clearly insufficient.
- Prefer explicit error propagation with `Result` over `unwrap` or `expect` in runtime paths.

## Safe Editing Rules

- Do not edit generated or runtime data under `target/`, `db/`, or `html/images/` unless the task explicitly requires it.
- Do not overwrite `etc/digitemp-rrdgraph.conf` for convenience; use `etc/config.sample.json` as the editable reference.
- Be careful with commands that can talk to real hardware, modify RRD files, or send email.
- When validation would invoke external systems, prefer build-only or isolated checks unless the user explicitly wants end-to-end execution.

## Validation Expectations

- After Rust code changes, run `cargo build` in this repository at minimum. Prefer `cargo build --workspace` when changes affect `crates/core/` or workspace wiring.
- If you add or refactor logic that can be unit tested without hardware or SMTP, add focused tests and run them.
- Prefer tests around pure logic such as config parsing, digitemp config parsing, template rendering, and any command-argument construction helpers.
- If a change depends on hardware access or local services, state clearly what could not be verified.

## Implementation Guidance

- Keep path handling relative to the repository root unless a config field explicitly stores an absolute path.
- Encapsulate shell command construction so it can be inspected or tested without executing the command.
- Match existing naming and module boundaries under `src/commands/` and `crates/core/src/`.
- Keep CLI-only orchestration in the root crate and reusable logic in `digitemp_rrdgraph_core`.
- Prefer direct, maintainable implementations over compatibility layers or unnecessary abstraction.

## Useful References

- Rust entrypoint: `src/main.rs`
- Rust commands: `src/commands/`
- Internal library crate manifest: `crates/core/Cargo.toml`
- Rust support modules: `crates/core/src/`
- Sample config: `etc/config.sample.json`
- Email templates: `templates/`
- RRD files: `db/`
- Graph images: `html/images/`
- External dependencies: `digitemp`, `rrdtool`, SMTP server