ai-session-search AGENTS.md

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 the MSRV build, macOS/Windows/Linux 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.

Keep this command map accurate when a required job changes. A missing local command makes a green run mean less than it reads as: cargo doc was absent once, and a public item linking a private one passed locally before failing the hosted rust job. Tools the gate does not install — actionlint, cargo-deny — report named skips and exact pinned install commands; when installed, their versions must match the workflow pins before their results count as hosted-command evidence.

Run the gate with no environment prefix. Never prefix AI_SESSION_SEARCH_RUSTC_WRAPPER=: it exports an empty RUSTC_WRAPPER and disables sccache. Use it only when an inherited wrapper is broken. Before step one the gate prints the wrapper it resolved and whether incremental compilation is on; read that line before concluding a build is slow for another reason.