1 files changed, 59 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4c44b8d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,59 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## What this is
+
+`coomer_dl`: single-file Python script that downloads Coomer creators, single
+posts and single files. Runtime dependency: `requests` only. Keep it a single
+file and do not add dependencies. Sibling project: `../bunkr_dl`, same
+structure and `download_file`.
+
+## Download chain
+
+The site sits behind DDoS-Guard. When the script finds nothing, re-inspect the
+API with `curl --compressed -H 'Accept: text/css'` before changing code.
+
+1. `GET /api/v1/<service>/user/<id>/posts?o=N` returns a JSON list of up to 50
+   posts. Pagination stops on a short or empty page.
+2. `GET /api/v1/<service>/user/<id>/post/<post id>` returns
+   `{"post": {...}, ...}`.
+3. `GET /api/v1/<service>/user/<id>/profile` gives the creator `name`, used as
+   the folder name.
+4. Each post has `file` (may be `{}`) and `attachments`, each `{name, path}`.
+   The main file often repeats as an attachment, `post_files` dedupes by path.
+5. `GET /data<path>` 302-redirects to `nN.<domain>/data<path>`.
+
+All API calls need `Accept: text/css`, otherwise 403.
+
+## Conventions
+
+- New options go in the `argparse` setup in `main()` and in the README usage
+  table.
+- `download_file` resumes with a per-request `Range` header. Never mutate the
+  global `headers` dict. 206 appends, 200 overwrites, 416 means already complete.
+- Creator folders are reused across runs (not suffixed like bunkr_dl) so a
+  re-run resumes and only fetches new posts.
+- Use placeholder URLs (`https://coomer.st/onlyfans/user/NAME`) in docs,
+  comments and commit messages, never real creator names or post ids.
+
+## Testing
+
+No test suite. Verify the API side without downloading by stubbing
+`download_file`:
+
+    python - <<'PY'
+    import importlib.util, importlib.machinery
+    l = importlib.machinery.SourceFileLoader('c', 'coomer_dl')
+    c = importlib.util.module_from_spec(importlib.util.spec_from_loader('c', l)); l.exec_module(c)
+    got = []; c.download_file = lambda *a: got.append(a)
+    c.process_creator('https://coomer.st', 'onlyfans', 'NAME', '/tmp/x')
+    print(len(got), got[0])
+    PY
+
+The "Found N posts" total should match `post_count` from the profile endpoint.
+For a full run use `-o` pointing at a temp dir.
+
+## Repo facts
+
+- License: GPLv2 only (`LICENSE`, header in `coomer_dl`).