# Agents Guidelines

## Project Overview

This project is a Rust command-line client for MDRS-based repositories.

- The binary entry point is `src/main.rs`
- CLI argument parsing is defined in `src/cli.rs`
- Command implementations live under `src/commands/`
- API access code lives under `src/api/`
- Shared domain types live under `src/models/`
- Login cache and runtime settings live under `src/cache/` and `src/settings.rs`

## Development Workflow

### Cargo-first workflow

Prefer standard Cargo commands and existing project tooling over custom scripts
or ad hoc edits.

Common commands:

- `cargo fmt`
- `cargo test`
- `cargo build`
- `cargo run -- <args>`

### Formatting requirement

When you modify Rust code or any code that is formatted by the Rust toolchain,
you must run `cargo fmt` before finishing the task.

### Validation

Use the narrowest relevant validation for the change:

- documentation-only changes do not require Cargo validation
- for behavior changes, run the relevant Rust tests if they already exist
- if no targeted test exists, use the smallest existing Cargo command that
  meaningfully validates the modified area

## Code Guidelines

### Reuse project patterns

Before adding new code, inspect the existing command, API, and model modules
and follow their established patterns.

In particular:

- keep CLI behavior consistent with the existing `clap` command structure
- prefer existing error handling patterns based on `anyhow`
- keep async behavior aligned with the current `tokio`-based implementation
- avoid duplicating logic that already exists in sibling command modules

### Comments and documentation

All comments written inside source code must be in English.

This includes:

- line comments
- block comments
- doc comments

Documentation file language may follow the needs of the project, but source
code comments must stay in English.

## Planning and Review

### Plan mode

When working in plan mode:

1. analyze the current codebase state first
2. write or update the implementation plan in the session plan file
3. require user review of the plan before starting implementation

Do not begin editing project files until the user has reviewed and approved the
plan.

### Git commits

Never run `git commit` without explicit user confirmation.

This requirement still applies after a plan has been reviewed or approved. Plan
approval is not commit approval.

## Git Commit Messages

Commit messages must always be written in English.

Follow the Conventional Commits format:

```text
<type>(<scope>): <short description>
```

Use clear, imperative subjects without a trailing period.

Examples:

- `feat(upload): add recursive directory support`
- `fix(login): handle expired cache gracefully`
- `docs(agents): add Rust project guidance`

## Practical Expectations for Agents

- make precise, minimal changes that fully solve the task
- read nearby modules before changing structure or introducing helpers
- prefer updating existing code paths over adding parallel implementations
- preserve current CLI semantics unless the task explicitly changes them
- surface uncertainties to the user instead of guessing on destructive actions