From e2fe8140c168dba0489446f652aa163b763a8ad7 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sun, 7 Jun 2026 03:13:34 +0000
Subject: [PATCH] Add AGENTS.md with Cursor Cloud development instructions

Co-authored-by: Travis Dart <TravisDart@users.noreply.github.com>
---
 AGENTS.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3ad06a0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,54 @@
+# AGENTS.md
+
+## Project overview
+
+**pull-index** is a Python CLI for reading Elasticsearch snapshot repository metadata from S3 and optionally exporting documents via ephemeral Docker Elasticsearch. See `README.md` for command usage.
+
+## Cursor Cloud specific instructions
+
+### Running the CLI
+
+All commands run from the repo root with `uv`:
+
+```bash
+uv run main.py list s3://<bucket>/<prefix>/
+uv run main.py download s3://<bucket>/<prefix>/ '<index-name>'
+uv run main.py export-documents s3://<bucket>/<prefix>/ '<index-name>'
+```
+
+There is no long-running dev server. The CLI is the application.
+
+### Dependencies
+
+| Tool | Purpose |
+|------|---------|
+| **uv** + **Python 3.13** | Runtime (managed via `pyproject.toml` / `.python-version`) |
+| **AWS CLI v2** | S3 access for all commands |
+| **Docker** | Required only for `export-documents` |
+
+### AWS credentials
+
+S3 commands need valid AWS credentials (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`, or `~/.aws/credentials`). Without them, `list` and `download` fail when reading from S3 (even if `.pull-index/generation-files.json` cache exists).
+
+### Docker in Cloud Agent VMs
+
+The Docker daemon uses the `fuse-overlayfs` storage driver in this environment. If `docker info` reports permission errors, ensure `dockerd` is running and `/var/run/docker.sock` is accessible (e.g. `sudo chmod 666 /var/run/docker.sock` or membership in the `docker` group).
+
+`export-documents` pulls `docker.elastic.co/elasticsearch/elasticsearch:<version>` on first use.
+
+### Repository listing cache
+
+After the first successful `list` or `download` for a repository URI, index generation file paths are cached in `.pull-index/generation-files.json`. Subsequent commands skip the slow S3 listing. Delete `.pull-index/` to force a refresh.
+
+### Lint / tests
+
+There is no configured linter or automated test suite in this repo. For a quick sanity check:
+
+```bash
+uv run python -m py_compile main.py snapshot_export.py repo_es_version.py
+uv run main.py --help
+```
+
+### Example repository
+
+The README documents `s3://cold-qa01/2022-Q1/` as an example snapshot path.