# Agent Instructions for Anson's Projects

This repository contains a multi-language technical blog with Rust automation tools, Julia data analysis notebooks, and Quarto documentation.

## Build/Lint/Test Commands

### Rust (ghost-upload/)
- **Build**: `cd ghost-upload && cargo build`
- **Run**: `cd ghost-upload && cargo run`
- **Test**: `cd ghost-upload && cargo test`
- **Lint**: `cd ghost-upload && cargo clippy`
- **Format**: `cd ghost-upload && cargo fmt`
- **Single test**: `cd ghost-upload && cargo test <test_name>`

### Julia (posts/*/ and root)
- **Run notebook**: `julia <filename>.jl`
- **Package management**: `julia -e "using Pkg; Pkg.instantiate()"`
- **Precompile**: `julia -e "using Pkg; Pkg.precompile()"`

### Quarto (Documentation)
- **Build site**: `quarto render --to html --output-dir public`
- **Preview**: `quarto preview`
- **Check**: `quarto check`

### Docker
- **Build**: `docker build -t projects .`
- **Run**: `docker run projects`

## Code Style Guidelines

### Rust
- **Formatting**: Use `cargo fmt` (4-space indentation, standard Rust style)
- **Linting**: Use `cargo clippy` and fix all warnings
- **Imports**: Group by standard library, external crates, then local modules
- **Error Handling**: Prefer `?` operator over `unwrap()`, use custom error types for complex cases
- **Naming**: snake_case for functions/variables, PascalCase for structs/enums
- **Documentation**: Use `///` for public APIs, `//` for implementation details
- **Async**: Use `async fn` for async functions, avoid blocking operations in async contexts

### Julia
- **Formatting**: 4-space indentation, spaces around operators
- **Imports**: Use `using` for packages, group at top of file
- **Naming**: snake_case for functions and variables
- **Types**: Use descriptive names, consider performance implications
- **Plotting**: Use Plots.jl with consistent themes (e.g., `theme(:ggplot2)`)
- **DataFrames**: Use pipe operators `|>` for data transformations
- **Error Handling**: Use try-catch blocks for expected errors

### Quarto (.qmd files)
- **YAML frontmatter**: Include title, date, and relevant metadata
- **Code chunks**: Use appropriate language engines (`{rust}`, `{julia}`, `{python}`)
- **Output**: Set `echo: false` for clean output, `warning: false` to suppress warnings
- **Figures**: Use descriptive captions and alt text
- **Citations**: Use `@citekey` format with bibliography files

### General
- **Git**: Write clear commit messages, use conventional commits when possible
- **Documentation**: Update README.md for significant changes
- **Dependencies**: Keep dependencies minimal and up-to-date
- **Security**: Never commit API keys or sensitive credentials
- **Performance**: Profile code before optimizing, focus on readability first

## Project Structure
- `ghost-upload/`: Rust automation for blog post publishing
- `posts/`: Individual blog posts (Quarto markdown + Julia/Python code)
- Root: Quarto website configuration and shared assets

## Environment Variables
- `kagi_api_key`: For Kagi API summarization (Rust)
- `admin_api_key`: For Ghost CMS API (Rust)

## Testing Strategy
- **Rust**: Unit tests for core functionality, integration tests for API interactions
- **Julia**: Visual validation of plots and data transformations
- **Quarto**: Manual review of rendered output and links

## Deployment
- Uses GitLab CI/CD with Docker
- Deploys to static hosting after Quarto build
- Rust component runs separately for content synchronization