AGENTS.md

# Codex Instructions (Prompt_Squirrel_RAG)

## Environment (Windows / PowerShell)
- Always run from the repo root.
- Never run `python` or `pip` directly.
- Always use the venv interpreter:
  - `.venv\Scripts\python.exe`
- Install deps with:
  - `.venv\Scripts\python.exe -m pip install -r requirements.txt`

## Change discipline
- Keep diffs small: fix one issue or implement one focused step per patch.
- Do not rewrite large files.
- Do not move logic across modules unless the contract requires it.
- Preserve stage boundaries: rewriting (LLM) vs retrieval (candidate generation) vs selection (index-only).

## Project contracts
- Follow the retrieval grounding / candidate generation contract:
  - `docs/retrieval_contract.md`
- If behavior conflicts with existing code, update code to match the contract (not the other way around).

## Git setup notes for this repository/user
- Remote mapping currently used by user:
  - `github` => `https://github.com/FoodDesert/Prompt_Squirrel_RAG.git`
  - `origin` => `https://huggingface.co/spaces/FoodDesert/Prompt_Squirrel_RAG`
- For code collaboration, prefer explicit GitHub remote commands to avoid pushing code to Hugging Face remote.

## Mandatory agent bootstrap for any new workspace
- Always run these first, in order:
  1. `git status --short --branch`
  2. `git remote -v`
  3. `git branch -vv`
  4. `rg --files | rg 'AGENTS.md|PROJECT_SUMMARY.md|SESSION_QUICKSTART.md'`
- If `github` remote is missing, add it immediately:
  - `git remote add github https://github.com/FoodDesert/Prompt_Squirrel_RAG.git`
- Sync before any work:
  - `git pull --rebase github HEAD`

### Git guidance style for this user
- Keep Git instructions short and step-by-step.
- Ask for / interpret `git status --short --branch` output first.
- Prefer explicit commands with remote names, e.g.:
  - `git pull --rebase github HEAD`
  - `git push github HEAD`
- If branch divergence appears, prefer a low-risk resync path over complex conflict resolution.