# Repository Guidelines

## Project Structure & Module Organization
This repo is a Rust TUI editor prototype built around `ratatui` 0.30, `crossterm`, and `tokio`. The application entry point is [src/main.rs](/home/stdpi/repo/ration/src/main.rs). Local workspace crates live under `crates/`: `ratatui-code-editor` provides the editor widget and `tui-tree-widget` provides the explorer tree. Treat `src/main.rs` as app orchestration only; push reusable editing, workspace, and UI logic into focused modules or local crates instead of growing one monolithic file.

## Build, Test, and Development Commands
Use:
- `cargo run` to launch the TUI
- `cargo check` for fast compile validation
- `cargo fmt` to format changes
- `cargo clippy --all-targets --all-features` before finishing non-trivial work
- `cargo test` when editing crate logic that already has tests or clearly needs them

There is no CI config in the tree yet, so local verification is the gate.

## Ratatui-TUI Conventions
Bake in the `ratatui-tui` skill by default for this repo. Prefer The Elm Architecture shape: model/state, typed actions/messages, update, and view. Keep event ingestion async with `EventStream` + `tokio::select!`. Use `StatefulWidget` state types for explorer, lists, tables, and scrollbars instead of ad hoc cursor bookkeeping where possible.

Styling should use `Stylize` helpers like `.bold()`, `.cyan()`, `.dim()`, not verbose `Style` construction unless necessary. Avoid hardcoded pure white/black defaults. Ensure panic hooks always restore the terminal and mouse capture state.

## Coding Style & Safety
Avoid `unwrap()` outside tests. Propagate errors with `anyhow::Result` or `color_eyre`-style context. Keep terminal-facing behavior exact: cursor math, scrolling, tab width, and selection rendering are correctness issues, not polish. Skip `.git`, `target`, and symlink loops when scanning the workspace.

## Testing Guidelines
Prefer focused unit tests in the local crates for editor actions, history, cursor math, and tree behavior. For TUI changes, verify both compile correctness and interactive behavior with `cargo run`.

## Commit & PR Guidelines
Git history is unavailable because this branch has no commits yet. Use conventional subjects such as `feat: add workspace save flow`, `fix: correct cursor rendering`, or `docs: refresh repo guidelines`.

@RTK.md