# Repository Guidelines

## Project Structure & Module Organization
- `ghost-upload/`: Rust automation for Ghost CMS publishing.
- `posts/`: Quarto posts with Julia/Python code per post directory.
- `public/`: Quarto build output (generated by `quarto render`).
- Root: Quarto config (`_quarto.yml`), shared assets, CI/CD, docs.

## Build, Test, and Development Commands
- Rust (`ghost-upload/`):
  - Build: `cd ghost-upload && cargo build`
  - Run: `cd ghost-upload && cargo run`
  - Test: `cd ghost-upload && cargo test` (single: `cargo test <test_name>`)
  - Lint: `cd ghost-upload && cargo clippy`
  - Format: `cd ghost-upload && cargo fmt`
- Julia (root or `posts/*/`):
  - Packages: `julia -e "using Pkg; Pkg.instantiate()"`
  - Precompile: `julia -e "using Pkg; Pkg.precompile()"`
  - Run notebook/script: `julia <filename>.jl`
- Quarto (docs/site):
  - Build site: `quarto render --to html --output-dir public`
  - Preview: `quarto preview`
  - Check: `quarto check`
- Docker: `docker build -t projects .` then `docker run projects`

## Coding Style & Naming Conventions
- Rust: `cargo fmt`; fix all `cargo clippy` warnings. Use `?` over `unwrap()`. Imports: std → external → local. Naming: snake_case (fn/vars), PascalCase (types). Public docs with `///`.
- Julia: 4-space indent; spaces around operators; group `using` at top; snake_case; prefer pipelines `|>` for DataFrames; handle expected errors with try-catch.
- Quarto: Include title/date in YAML; set `echo: false`, `warning: false` for clean outputs; descriptive figure captions and alt text.

## Testing Guidelines
- Rust: Unit tests for core logic; add integration tests for API calls. Run with `cargo test`. Organize tests near code or in `tests/`.
- Julia: Validate transformations and plots visually; keep scripts deterministic.
- Quarto: Manually review rendered HTML for links, figures, and warnings.

## Commit & Pull Request Guidelines
- Commits: Use clear, conventional messages (e.g., `feat:`, `fix:`, `docs:`). Scope small and focused.
- PRs: Provide description, linked issues, steps to validate (commands), and screenshots of rendered docs when relevant.

## Security & Configuration
- Environment variables: `kagi_api_key`, `admin_api_key`. Export locally (e.g., `export admin_api_key=...`); never commit secrets.
- Dependencies: Keep minimal and up-to-date. Prefer configuration via env vars over hardcoded values.

## CI/CD & Deployment
- GitLab CI builds Docker, renders Quarto to static hosting; Rust runs separately for content sync. Avoid pipeline changes unless necessary; include rationale in PRs if modified.

