orb: Instructions file for Codex

Agent Guide for Orb

This file provides guidance specifically for AI agents (and humans) working on this codebase. Read AGENTS.md first for full architecture, project structure, and design principles. This file supplements it with practical details, gotchas, and quick references.

Quick Start

make build    # Debug build (fast, use for iterating)
make test     # Run all tests
make lint     # Check formatting + clippy (CI runs this)
make fix      # Auto-fix formatting + clippy issues

Always run make lint before submitting changes. CI will reject PRs that fail lint.

Rust Edition & Toolchain

• Edition: Rust 2024 (edition = "2024" in all Cargo.toml files)
• MSRV: 1.91 (set in all three package Cargo.toml files)
• No rust-toolchain.toml - uses whatever stable/beta toolchain the developer has installed
• Note: CONTRIBUTING.md says "Rust 1.90 (nightly)" — this is outdated. The actual MSRV is 1.91 from Cargo.toml.

Workspace Structure

Cargo.toml              # Workspace root (resolver = "2")
packages/
  orb-cli/              # Binary: `orb` (publish = false)
  orb-client/           # Library (publish = false, designed as standalone)
  orb-mockhttp/         # Mock server library (publish = true)

Critical Rules

1. Client/CLI Separation

orb-client must NEVER import from or depend on orb-cli. This is the most important architectural constraint.

• Adding verbose output? Add a new ClientEvent variant in packages/orb-client/src/events.rs, then handle it in packages/orb-cli/src/verbose_events.rs.
• Adding error handling? Use OrbError variants in orb-client, map to user-friendly messages via fatal! in orb-cli.
• Never use fatal! in orb-client — it's a CLI macro. Use OrbError and propagate with ?.

2. Crypto Provider

Both orb-client and orb-mockhttp use aws-lc-rs as the TLS crypto provider:

let _ = rustls::crypto::aws_lc_rs::default_provider().install_default();