From 7be56b074d4cc063b4806c5d5c0bce28085dd442 Mon Sep 17 00:00:00 2001
From: Matteo Prandi <matteo.prandi94@gmail.com>
Date: Thu, 9 Apr 2026 17:03:00 +0200
Subject: [PATCH] docs(citation): add software citation metadata

---
 .zenodo.json | 21 +++++++++++++++++++++
 CITATION.cff | 21 +++++++++++++++++++++
 README.md    | 40 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+)
 create mode 100644 .zenodo.json
 create mode 100644 CITATION.cff

diff --git a/.zenodo.json b/.zenodo.json
new file mode 100644
index 0000000..b636581
--- /dev/null
+++ b/.zenodo.json
@@ -0,0 +1,21 @@
+{
+  "title": "MASE: Multi-Agent Simulation Environment",
+  "upload_type": "software",
+  "access_right": "open",
+  "license": "Apache-2.0",
+  "creators": [
+    {
+      "name": "Prandi, Matteo",
+      "affiliation": "Icaro Lab",
+      "orcid": "0009-0002-9258-5589"
+    }
+  ],
+  "description": "MASE is experimentation infrastructure for studying AI agent interaction at scale.",
+  "keywords": [
+    "multi-agent systems",
+    "simulation",
+    "AI agents",
+    "research infrastructure"
+  ],
+  "language": "eng"
+}
diff --git a/CITATION.cff b/CITATION.cff
new file mode 100644
index 0000000..1cebe70
--- /dev/null
+++ b/CITATION.cff
@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: >-
+  If you use MASE in academic work, please cite the specific software release
+  you used. If you used unreleased code, cite the repository together with the
+  commit hash.
+title: "MASE: Multi-Agent Simulation Environment"
+type: software
+authors:
+  - family-names: "Prandi"
+    given-names: "Matteo"
+    affiliation: "Icaro Lab"
+    orcid: "https://orcid.org/0009-0002-9258-5589"
+repository-code: "https://github.com/icaro-lab/MASE"
+url: "https://github.com/icaro-lab/MASE"
+license: "Apache-2.0"
+abstract: "Experimentation infrastructure for studying AI agent interaction at scale."
+keywords:
+  - "multi-agent systems"
+  - "simulation"
+  - "AI agents"
+  - "research infrastructure"
diff --git a/README.md b/README.md
index b505413..586a5ba 100644
--- a/README.md
+++ b/README.md
@@ -154,6 +154,46 @@ Public-facing docs for the extractable OSS surface now live under `docs/`:
 - [`docs/run-and-inspect.md`](docs/run-and-inspect.md)
 - [`docs/troubleshooting.md`](docs/troubleshooting.md)
 
+## Citation
+
+MASE now includes both [`CITATION.cff`](CITATION.cff) for GitHub's built-in
+repository citation support and [`.zenodo.json`](.zenodo.json) for release
+archiving metadata on Zenodo.
+
+If you use MASE in research:
+
+- cite the specific software release you used
+- if you used unreleased code, cite the repository together with the commit hash
+
+Until the first DOI-backed release is published, the repo itself can be cited as
+software:
+
+```bibtex
+@software{prandi_mase,
+  author = {Prandi, Matteo},
+  title = {MASE: Multi-Agent Simulation Environment},
+  year = {2026},
+  institution = {Icaro Lab},
+  url = {https://github.com/icaro-lab/MASE},
+  note = {GitHub repository}
+}
+```
+
+After the first Zenodo-backed release, prefer citing the archived release DOI
+instead of the repository URL.
+
+### Maintainer Release Setup
+
+The repository is prepared for DOI-backed releases, but the GitHub-to-Zenodo
+link must be enabled once in the Zenodo UI:
+
+1. Log into Zenodo with GitHub or ORCID and enable the `icaro-lab/MASE`
+   repository under GitHub integration settings.
+2. Create a GitHub release with a version tag such as `v0.1.0`.
+3. Zenodo will archive that release and mint a DOI for it.
+4. Add the minted DOI badge and DOI citation example to this README after the
+   first archived release exists.
+
 ## Project Status
 
 MASE is currently in alpha.