ai-session-search: Instructions file for Codex

AI Session Search agent guidance

Read by every tool following the AGENTS.md convention. CLAUDE.md imports it, so change it here only.

Rust first: logic, checks, and tooling belong in the crate, and Python carries only the binding surface and the tests that must exercise it.

Setup

Rust 1.88 or newer, CPython 3.12 through 3.14 with the standard GIL (3.12 is the floor; 3.12–3.14 are what CI tests), and uv.

uv sync --locked --all-extras
uv run maturin develop --uv    # abi3 extension into the venv; pytest fails without it

Build

./run_ci_local.sh                                       # host-platform gate, before proposing a commit
cargo test -p ai-session-search <test name>             # focused Rust
uv run pytest tests/<file>.py -k <test name>            # focused Python
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
uv run ruff check . && uv run mypy ai_session_search tests

The gate reproduces the required Rust, Python, license, and workflow-security commands that use the current host and toolchain. The required CI matrix still owns macOS/Windows and CPython 3.12–3.14 coverage, and registry, path, and Git install pathways. That matrix has caught what a green local gate could not: a test building a file:// URL by string interpolation passed where paths start with a separator and failed on Windows, where the drive letter parses as the URL host.

Linux and the MSRV build are reachable locally without waiting for CI, on any host that runs containers:

./scripts/linux_container_gate.sh                        # ./run_ci_local.sh on Linux
./scripts/linux_container_gate.sh --rust 1.88.0 msrv     # the two commands the msrv job runs
./scripts/linux_container_gate.sh bench-tui              # registered TUI cases on Linux
./scripts/linux_container_gate.sh --platform linux/amd64 # emulated; the default is the host arch

It adds no checks — it runs the ones above inside docker/linux-gate.Dockerfile, so a check never exists in two places. Read a green run for what it covers: Linux build, tests, packaging, and install pathways at the host architecture. It omits cargo-deny, actionlint, and zizmor, which inspect the dependency graph and workflow files and do not vary by host, and on Apple Silicon it covers linux/arm64 unless --platform says otherwise. The host checkout is never mounted: a source snapshot is streamed in and Cargo, uv, and the virtual environment write to container volumes, so a Linux target/ cannot collide with the host toolchain's and a Linux .venv cannot replace the host interpreter's.