Projects/AGENTS.md

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.