# Repository Guidelines

## Project structure

| Path                           | Purpose                                                                                                                 |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `src/`                         | Rust CLI (`main.rs`) and library (`lib.rs`). Modules: `auth/`, `http/`, `template/`, `security/`, `search/`, `secrets/` |
| `tests/`                       | Integration tests. Helpers in `tests/common/mod.rs`, fixtures in `tests/fixtures/`                                      |
| `examples/`                    | Example configs and templates                                                                                           |
| `site/`                        | Docs site (Next.js + MDX)                                                                                               |
| `scripts/`, `scripts/release/` | Build and release utilities                                                                                             |

## Commands

**Rust:**

```bash
cargo check                                              # fast compile check
cargo run -- --help                                      # run CLI locally
cargo test --all-targets --all-features                  # full test suite (matches CI)
cargo fmt --all                                          # format
cargo clippy --all-targets --all-features -- -D warnings # lint
cargo publish --dry-run --locked                         # verify packaging
```

**Docs site:**

```bash
pnpm install --frozen-lockfile
pnpm dev:site      # local docs dev server (Next.js)
pnpm dev:web       # local web playground dev server (Vite)
pnpm build:site    # static docs build + rustdoc via Turbo
pnpm build:web     # web playground build via Turbo
pnpm types:check   # site MDX/type checks via Turbo
```

## Coding style

- Rust: `rustfmt` defaults, idiomatic Rust 2024 edition
- Naming: `snake_case` (modules/functions), `UpperCamelCase` (types/traits), `SCREAMING_SNAKE_CASE` (constants)
- Security-sensitive logic (allowlists, SSRF protections, redaction) must be explicit — no hidden side effects
- Site code: Biome config at `site/biome.json` (2-space indent, organized imports)

## Testing

- Add or update integration tests in `tests/` for any behavior change
- Name test files by feature: `http_executor.rs`, `security_allowlist_ssrf.rs`
- Scope fixtures by domain: `tests/fixtures/oauth/`, `tests/fixtures/templates/`
- Bug fixes require a regression test that fails before and passes after the fix

## Commits and PRs

- Use Conventional Commits: `feat:`, `fix:`, `chore:`, etc. (drives release-please automation)
- Keep commits focused and logically grouped
- PRs must include: summary and motivation, linked issue(s), commands run as test evidence, screenshots for `site/` changes
- Release PRs (`chore: release <version>`) are auto-generated — do not hand-edit release artifacts unless necessary
