1 files changed, 70 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ed788e9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,70 @@
+# coomer_dl
+
+Download every file of a Coomer creator, of a single post, or a single file,
+from the command line.
+
+- Follows the creator's post pagination (50 posts per API page).
+- Saves files as `<post id>_<original name>`, so a post's files stay together.
+- Resumes partial files and skips finished ones when run again against the
+  same folder, so re-running a creator only fetches what is new.
+- Works with any Coomer mirror domain, since API and file URLs are built from
+  the URL you pass.
+
+## Requirements
+
+Python 3.12+ with `requests`.
+
+## Usage
+
+```
+coomer_dl [-h] [-o DIR] url
+```
+
+| Option             | Meaning                                              |
+|--------------------|------------------------------------------------------|
+| `url`              | Creator URL (`https://<domain>/<service>/user/<id>`), post URL (`.../post/<id>`) or file URL (`https://<domain>/data/...`) |
+| `-o, --output DIR` | Base download folder (default: `/data/coomer`)       |
+| `-h, --help`       | Show help and exit                                   |
+
+The default folder is set by `DEFAULT_OUTPUT` near the top of the script.
+
+Examples:
+
+```
+coomer_dl https://coomer.st/onlyfans/user/NAME
+coomer_dl https://coomer.st/onlyfans/user/NAME/post/123456
+coomer_dl -o ~/Downloads 'https://coomer.st/data/ab/cd/HASH.mp4?f=name.mp4'
+```
+
+Quote file URLs so the shell leaves `?` and `&` alone.
+
+### Where files go
+
+- Creator or post: `OUTPUT/<creator name>/<post id>_<file name>`.
+- File URL: `OUTPUT/<file name>`, taken from the `?f=` parameter when present.
+
+## How it works
+
+1. `GET /api/v1/<service>/user/<id>/posts?o=N` pages through the posts, or
+   `GET /api/v1/<service>/user/<id>/post/<post id>` fetches one.
+2. Each post has a `file` and `attachments`, each with a storage `path`.
+3. `GET /data<path>` redirects to a file node (`nN.<domain>`) serving the file.
+
+API calls send `Accept: text/css`, without it DDoS-Guard answers 403. When the
+script reports nothing found, check these steps against the live site first.
+
+## License
+
+Copyright (C) 2026 Danilo M. <danix@danix.xyz>
+
+This program is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License version 2 as published by the Free
+Software Foundation. See [LICENSE](LICENSE) for the full text.
+
+## Development Approach
+
+This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.
+
+All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.
+
+The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.