docs: add a Research section with participant instructions

src/index.rst

@@ -45,6 +45,13 @@ Table of contents
    development
    forking
 
+.. _research-docs:
+.. toctree::
+   :maxdepth: 2
+   :caption: Research
+
+   research/index
+
 .. _meta-docs:
 .. toctree::
    :maxdepth: 3

src/research/index.rst

@@ -0,0 +1,88 @@
+.. _research:
+
+ActivityWatch in research
+=========================
+
+ActivityWatch is used as a data-collection instrument in academic studies. This section
+documents the **Research Edition**, a purpose-built variant for that use, and maintains the
+participant-facing instructions so that studies can link to a canonical, versioned page
+rather than circulating copies over email.
+
+Why researchers use it
+----------------------
+
+- **Local-first.** Data stays on the participant's device. Nothing is transmitted
+  automatically. The participant creates an export file and uploads it deliberately, which
+  makes the data flow easy to describe in an ethics application.
+- **Open source.** The collection logic can be read, audited and cited by reviewers.
+- **Cross-platform.** Windows, macOS and Linux, plus Android.
+- **Category-only collection.** The Research Edition can be configured to store predefined
+  categories rather than window titles or URLs.
+
+Self-reported computer use is a poor measure of actual computer use. The canonical validity
+study found that self-report agreed with software registration for only 18% of participants,
+and misclassified exposure for more than 80%:
+
+  IJmker S, Leijssen JNM, Blatter BM, van der Beek AJ, van Mechelen W, Bongers PM.
+  *Test-retest reliability and validity of self-reported duration of computer use at work.*
+  Scand J Work Environ Health. 2008;34(2):113-119. `doi:10.5271/sjweh.1220
+  <https://doi.org/10.5271/sjweh.1220>`_
+
+How to cite
+-----------
+
+If you use ActivityWatch in published work, please cite the software:
+
+  Bjäreholt E, Bjäreholt J. *ActivityWatch.* `doi:10.5281/zenodo.4957165
+  <https://doi.org/10.5281/zenodo.4957165>`_
+
+The repository also contains a ``CITATION.cff``, which GitHub renders as a
+"Cite this repository" button.
+
+Studies and publications
+------------------------
+
+An incomplete list, maintained so that researchers choosing an instrument can see prior use.
+ActivityWatch typically appears in methods sections rather than titles or abstracts, so it is
+largely invisible to citation indexes — if you have used it and are not listed, please
+tell us.
+
+Used as a data-collection instrument
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- **Psychological Wellbeing, Sleep, and Video Gaming: Analyses of Comprehensive Digital
+  Traces** — Oxford Internet Institute (Ballou, Földes, Hakman, Vuorre, Magnusson,
+  Przybylski), Stage 1 Registered Report, 2025. ActivityWatch is the Android data-collection
+  channel for 2,000+ participants over three months, alongside console and storefront
+  telemetry.
+- **On/Off** — imec-mict-UGent (Vanden Abeele, Perneel, Van Gaeveren), the DISCONNECT ERC
+  citizen-science panel. Used for opt-in laptop and PC collection, documented in the study's
+  participant information and privacy materials.
+- **Sabermetrics for Cyber** — Rivera, Booz & Hammerstein (CMU SEI), ECCWS 2025.
+
+Discussed, compared or built upon
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These cite ActivityWatch without using it to collect their data.
+
+- **Traces as Data** — Parry & Klingelhoefer, handbook chapter, 2025. Names ActivityWatch as
+  an exemplar desktop-logging tool.
+- **Activity Frames** — Iyamu, 2026 (`arXiv:2608.05784 <https://arxiv.org/abs/2608.05784>`_).
+  Cites ActivityWatch once as related work, and runs its own capture pipeline.
+- Student theses building on or integrating ActivityWatch: Kroček (University of South
+  Bohemia, 2020), Kraus (Czech Technical University in Prague, 2021), Panchuk (NURE Kharkiv,
+  2026).
+
+Unpublished or unlisted deployments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Known deployments that have not produced a listed publication, including the University of
+Maryland iSchool, MIT Media Lab, Clemson University, and Lund University's IIIEE.
+
+If you are running or planning a study, please get in touch. We are glad to help scope the
+instrument, and we keep a list of studies that have used ActivityWatch.
+
+.. toctree::
+   :maxdepth: 2
+
+   participant-instructions

src/research/participant-instructions.rst

@@ -0,0 +1,133 @@
+.. _research-participant-instructions:
+
+Participant instructions (Research Edition)
+===========================================
+
+.. note::
+   **For researchers.** This page is maintained by the ActivityWatch project so that studies
+   can link to it instead of maintaining their own copy of the technical steps. It is kept in
+   sync with the current Research Edition build.
+
+   Adapt freely: add your study name, your contact details, and your upload location.
+   Translate as needed. The parts worth linking rather than copying are the mechanics below,
+   because those are what change between releases.
+
+   *Last reviewed: 2026-09-16, against v0.14.0b5-research.*
+
+The Research Edition is a separate build. It installs alongside a normal ActivityWatch
+installation without interfering with it: the Research Edition runs on port **5667**, a
+standard installation runs on port 5600. The dashboard shows a **Research Edition** badge at
+the top. If you see that badge, you are in the right place.
+
+Installing
+----------
+
+Download the build for your system from the link your researcher gave you, then open the
+downloaded file and follow the installation steps.
+
+**Windows.** The installer is not code-signed, so Windows may show a blue
+"Windows protected your PC" dialog. Click **More info**, then **Run anyway**.
+
+During installation, leave **Start ActivityWatch when Windows starts** ticked. It is ticked
+by default.
+
+**macOS.** The app asks for two separate permissions, and it needs both:
+
+1. **Accessibility.** On first launch you may see "Missing accessibility permissions".
+   Enable *ActivityWatch Research* under System Settings > Privacy & Security >
+   Accessibility, and restart the app if prompted. Without this permission the app cannot
+   record anything.
+2. **Browser control.** If you use Chrome or Safari, macOS asks whether
+   *ActivityWatch Research* may control it. Click **OK**. This is only used to sort the page
+   into a category. The address is not stored.
+
+If macOS shows a notification that a background item was added, leave it allowed.
+
+Starting automatically
+----------------------
+
+The Research Edition enables start-at-login by itself the first time it runs. You do not need
+to configure anything.
+
+It is still worth checking once or twice during the study that the icon is present: in the
+system tray on Windows (bottom right, possibly hidden under the **^** arrow), or in the menu
+bar on macOS (top right). If it is missing, start *ActivityWatch Research* from the Start menu
+or Applications folder.
+
+What is recorded
+----------------
+
+The Research Edition records **which applications you use** (for example Word, Teams or
+Chrome) and for how long. It does **not** record which websites you visit or what your window
+titles say. Browser activity is converted into predefined categories on your own computer
+before anything is stored, and your computer's hostname is removed from the export.
+
+No information about your activity is sent anywhere automatically. At the end of the study you
+create a file and upload it yourself.
+
+(For completeness: if you open the dashboard, the web interface asks GitHub for the latest
+version number. That request contains nothing about your activity.)
+
+Exporting your data at the end of the study
+-------------------------------------------
+
+Do this once, at the end of the study period, and keep the Research Edition running while you
+do it. It takes a couple of minutes.
+
+1. Click the **ActivityWatch Research** icon (macOS: menu bar, top of the screen. Windows:
+   bottom right near the clock, possibly under the **^** arrow) and choose **Open Dashboard**.
+   The dashboard opens in your browser. Check that it says **Research Edition** at the top.
+   If the dashboard does not open, go to http://localhost:5667
+2. Click **Raw Data** at the top right of the page. If your dashboard is not in English,
+   this is the same button under a translated name (Swedish: **Rådata**).
+3. You will see two rows, ``aw-watcher-window_…`` and ``aw-watcher-afk_…``. That is normal.
+   **Do not export them one by one.** Scroll down to **Import and export buckets**, and under
+   **Export buckets** click **Export all buckets as JSON** (Swedish: **Importera och
+   exportera buckets** > **Exportera alla buckets som JSON**).
+4. A file named ``aw-bucket-export.json`` appears in your Downloads folder. You do not need to
+   open or edit it.
+5. Upload that file where your researcher has asked you to.
+
+If something looks wrong, contact your researcher rather than searching online. The study
+version behaves differently from the public ActivityWatch.
+
+Notes for researchers
+---------------------
+
+A few things that reliably cause support questions:
+
+- **Filtering happens at capture, not at export.** The watcher classifies browser titles
+  into study categories and strips URLs *before* the event is recorded, so live Raw Data
+  already shows categories rather than real titles. What live Raw Data still shows is the
+  **real hostname**: that is rewritten to ``research-participant`` on export only. A
+  researcher comparing the dashboard to an export will see the hostname change, and nothing
+  else.
+- **The export fails closed, and that is the alarming one.** If the Research Edition was
+  installed over an existing ActivityWatch database, the old unfiltered events are still
+  there, and the export refuses rather than shipping them. The message says to reinstall on
+  a clean profile. Tell participants to install the Research Edition on a machine that has
+  no prior ActivityWatch database, or expect this at the end of the study, when there is no
+  time left to re-collect.
+- **Two buckets is the default**, not a double installation: one window watcher and one AFK
+  watcher. Do not use the row count to tell the Research Edition from a standard install --
+  a standard installation also shows two buckets, and the two run as separate servers, so
+  opening port 5600 does not add rows to the 5667 view. Diagnose by the **Research Edition**
+  badge and port **5667**. Buckets are created per watcher and per host
+  (see :doc:`the data model </buckets-and-events>`), so extra watchers or a hostname
+  change can add rows on either server.
+- **Use "Export all buckets as JSON", not the per-row menu.** The three-dot menu on a row
+  exports a single bucket. Participants following that route upload two files, or silently
+  omit AFK data.
+- **JSON, not CSV.** CSV covers one bucket, contains events only, carries no metadata, and
+  does not go through the export API.
+- **The interface may not be in English.** The web UI ships ``en``, ``uk``, ``de``, ``ru``,
+  ``zh-CN`` and ``sv`` locales, and it **selects one automatically from the browser
+  language** unless the participant has already chosen one. Translation coverage is
+  incomplete across all locales, so participants will see a mix. The tray menu is hardcoded
+  English regardless.
+
+  Write button names in both languages in your participant instructions, for example
+  "Rådata (Raw Data)". Assuming English will send some participants looking for a label
+  their screen does not show.
+- **The exported filename is fixed.** It cannot carry a participant number, so your upload
+  form needs a field or a per-participant link.