# AGENTS.md

Repository guidance for contributors and coding agents.

## Purpose

This repository ships `pyro-mcp`, an MCP-compatible package for ephemeral VM lifecycle tools used by coding agents.

## Development Workflow

- Use `uv` for all Python environment and command execution.
- Run `make setup` after cloning.
- Run `make check` before opening a PR.
- Use `make runtime-bundle` to regenerate the packaged runtime bundle from `runtime_sources/`.
- Use `make runtime-materialize` to build real runtime inputs into `build/runtime_sources/`.
- Use `make runtime-fetch-binaries`, `make runtime-build-kernel-real`, and `make runtime-build-rootfs-real` if you need to debug the real-source pipeline step by step.
- Use `make runtime-boot-check` to run a direct Firecracker boot validation against the bundled runtime artifacts.
- Use `make runtime-network-check` to validate outbound internet access from inside the guest.
- Use `make demo` to validate deterministic VM lifecycle execution.
- Use `make network-demo` to validate deterministic VM lifecycle execution with guest networking enabled.
- Use `make ollama-demo` to validate model-triggered lifecycle tool usage with guest networking enabled.
- Use `make doctor` to inspect bundled runtime integrity and host prerequisites.
- If you need full log payloads from the Ollama demo, use `make ollama-demo OLLAMA_DEMO_FLAGS=-v`.

## Quality Gates

- Linting: `ruff`
- Type checking: `mypy` (strict mode)
- Tests: `pytest` with coverage threshold

These checks run in pre-commit hooks and should all pass locally.

## Key API Contract

- Public factory: `pyro_mcp.create_server()`
- Runtime diagnostics CLI: `pyro-mcp-doctor`
- Runtime bundle build CLI: `pyro-mcp-runtime-build`
- Current bundled runtime is guest-capable for VM boot, guest exec, and guest networking; check `make doctor` for runtime capabilities.
- Lifecycle tools:
  - `vm_list_profiles`
  - `vm_create`
  - `vm_start`
  - `vm_exec`
  - `vm_stop`
  - `vm_delete`
  - `vm_status`
  - `vm_network_info`
  - `vm_reap_expired`