1 files changed, 73 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..78eb42f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,73 @@
+# abusectl
+
+Abuse reporting for phishing mail. Parses a flagged message, extracts its
+indicators, resolves who to report each one to, and files the result to a
+MISP instance and to public abuse channels.
+
+**Status: early.** The design is settled and the first part is being built.
+Nothing here submits anything yet.
+
+## What it does
+
+```
+abusectl parse msg.eml        # -> case directory, IOCs      offline
+abusectl contacts <case>      # + abuse contacts via RDAP    network, read-only
+abusectl report <case>        # + report bodies              offline
+      # review the bodies, by hand or in a mail client
+abusectl submit <case>        # MISP, then the vendors       network, writes
+```
+
+Each subcommand runs on its own and is useful on its own. `parse` triages a
+message with no configuration at all; `parse`, `contacts` and `report`
+together produce a document you can send by hand with no API key anywhere.
+
+State lives in a **case directory** rather than in memory, so a review can
+take a week and survive a reboot.
+
+## Two properties that are not negotiable
+
+**Recipient identifiers are never captured.** Not the `To`, `Cc`,
+`Delivered-To` or `X-Original-To` headers, not your Message-IDs, not maildir
+paths or account names. They are dropped at extraction rather than stripped at
+submission, so the tool cannot disclose an identifier it was never given.
+Tracking tokens inside URLs count: parameter values are redacted, parameter
+names and paths are kept, because the names fingerprint the kit and the values
+identify you.
+
+**Nothing remote is ever fetched while parsing.** Not the URLs, not the
+redirect chains, not remote images. Following a link confirms your address is
+live to the sender and fires exactly the tracker the message wanted. Redirect
+chains are read from headers and link text, never by following them.
+
+## Reversible and irreversible
+
+`submit` writes to MISP first and stops if that fails. MISP is your own
+instance and is correctable; a report to AbuseIPDB, URLhaus or VirusTotal
+cannot be recalled. The reversible step gates the irreversible ones, and it is
+also what answers "have I reported this infrastructure before".
+
+Every destination carries its own status, so a retry sends only what failed. A
+rate-limited vendor does not mean re-reporting to the three that accepted.
+
+## Design
+
+`docs/specs/2026-09-08-abusectl-design.md` is the umbrella design. Each part
+gets its own spec before it is built.
+
+## Requirements
+
+Python 3.11 or newer. `parse` and `report` need nothing else; `contacts` needs
+an HTTP client and `submit` needs PyMISP. Development runs from a venv in the
+checkout.
+
+## License
+
+GPLv2. See `LICENSE`.
+
+## 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.