docs: apply AI-generated documentation overhaul from proposals

AGENTS.md

@@ -0,0 +1,165 @@
+# AGENTS.md
+
+> This file describes the AI agent system used to generate documentation proposals in this repository. All agents are configured in `opencode.json`. Generated proposals live in `docs/proposals/` and require human review before adoption.
+
+---
+
+## Overview
+
+Documentation in this repository is generated through a structured multi-agent debate. Rather than having a single AI write documentation in one pass, four specialist agents each contribute their perspective, challenge one another's drafts, and a fifth editorial agent unifies the result into a single coherent voice.
+
+The goal is documentation that is simultaneously **accurate**, **reproducible**, **accessible**, and **readable** — without any single perspective dominating at the expense of the others.
+
+---
+
+## How It Works
+
+Every documentation request runs through four rounds:
+
+**Round 1 — Independent Drafts**
+The four subject-matter agents each write a draft independently, without seeing each other's work. This ensures each perspective is genuinely uninfluenced before the debate begins.
+
+**Round 2 — Cross-Review**
+Each agent reviews the other three drafts and returns specific, cited challenges: factual corrections, compliance gaps, accessibility problems, and concrete rewrite proposals. Vague criticism is not accepted — every challenge must include a suggested fix.
+
+**Round 3 — Consensus Synthesis**
+The `docs` orchestrator reconciles all four drafts and the Round 2 challenges into a single consensus document. Where agents disagree, the orchestrator applies a clear precedence order (see below) and records its reasoning in a `## Debate Summary` section at the top of every proposal.
+
+**Round 4 — Editorial Pass**
+The `technical-editor` agent receives the reconciled draft and performs a final pass focused entirely on voice, flow, and readability — without touching any factual content. This is the step that ensures the output reads as one coherent document rather than a committee report.
+
+The final file is written to `docs/proposals/<document-name>.md` and marked as a proposal pending human review.
+
+---
+
+## Agent Roles
+
+### `docs` — Orchestrator
+**Model**: claude-opus-4-6
+**Role**: Routes requests, manages the four debate rounds, synthesises consensus, and writes the final proposal to `docs/proposals/`.
+
+The orchestrator never writes documentation itself during the debate. Its job is coordination, conflict resolution, and final synthesis. It is the only agent with write access, and that access is restricted exclusively to `docs/proposals/`.
+
+**Conflict precedence order** (applied during Round 3 synthesis):
+1. Compliance and FAIR accuracy → `data-steward` challenges take precedence
+2. Computational and provenance accuracy → `bioinformatician` challenges take precedence
+3. Plain-language accessibility → `lab-personnel` challenges take precedence
+4. Structure and platform navigability → `ls-user-guide` challenges take precedence
+
+---
+
+### `data-steward` — Compliance & Metadata Accuracy
+**Model**: claude-sonnet-4-6
+**Voice in the debate**: *"Is this FAIR-compliant and correctly annotated?"*
+
+The data steward is the compliance firewall. It ensures that data and metadata descriptions conform to domain-specific schemas, controlled vocabularies, and Open Science regulations. It holds the line on accuracy — no compliance gap passes through without a citation and a correction.
+
+**Domain coverage**:
+- Genomics: FASTQ, BAM/CRAM, VCF; EGA, SRA, ENA submission standards
+- Proteomics: mzML/mzXML, mzIdentML; PRIDE/ProteomeXchange requirements
+- Immunopeptidomics: HLA-peptidomics, PSMs, MHC ligandome metadata, IEDB schemas
+- Imaging: OME-TIFF, CZI, DICOM, Visium; BioImage Archive and REMBI standards
+
+**Key standards enforced**: FAIR principles, OBO Foundry, EFO, NCIT, PSI-MS, MIAME, MINSEQE, REMBI, Plan S, Horizon Europe DMP, NIH DMSP
+
+---
+
+### `lab-personnel` — Bench Scientist / PI Perspective
+**Model**: claude-sonnet-4-6
+**Voice in the debate**: *"Can a bench scientist actually follow this?"*
+
+This agent represents the primary documentation consumer: a PI or wet-lab scientist with deep biological expertise but little data management background. It advocates for plain language, short steps, and everyday analogies. If a section would cause a busy scientist to disengage, this agent flags it and proposes a simpler alternative.
+
+**What it protects against**: unexplained acronyms, jargon-heavy compliance language, walls of text, steps that feel disconnected from daily lab workflow, and documentation that respects the data manager more than the scientist reading it.
+
+---
+
+### `bioinformatician` — Computational Provenance & Pipeline Accuracy
+**Model**: claude-sonnet-4-6
+**Voice in the debate**: *"Is the computational provenance chain correctly and reproducibly described?"*
+
+This agent fills the gap between compliance metadata and computational reality. It ensures that documentation correctly describes how derived data traces back to primary data — including software versions, parameter sets, checksums, workflow execution records, and environment specifications. If a described workflow would be non-reproducible as written, this agent catches it.
+
+**Domain coverage**:
+- Genomics pipelines: FastQC, STAR, BWA-MEM2, GATK, Salmon, Nextflow, Snakemake
+- Proteomics pipelines: MaxQuant, MSFragger, Spectronaut, DIA-NN, Perseus, MSstats
+- Immunopeptidomics: OptiType, HLA-HD, PSM-level filtering criteria
+- Imaging analysis: ilastik, CellProfiler, QuPath, Cellpose
+
+**Key standards**: FAIR4RS, Workflow RO-Crate, CWL/WDL metadata
+
+---
+
+### `ls-user-guide` — Platform Structure & Navigation
+**Model**: claude-haiku-4-5-20251001
+**Voice in the debate**: *"Is this well-structured and does it hold together as a platform guide?"*
+
+This agent sits at the intersection of the other three. It ensures documentation is grounded in actual platform UI steps and navigation paths, clearly distinguishes required from optional fields, and proposes bridge language when the other three agents are pulling in different directions. It is also the agent most likely to catch structural seams — places where the document stops flowing naturally.
+
+**What it protects against**: vague platform references, inconsistent field labelling, missing callouts for common mistakes, and logical gaps that would send a user looking elsewhere for help.
+
+---
+
+### `technical-editor` — Voice & Readability
+**Model**: claude-sonnet-4-6
+**Role**: Round 4 post-synthesis editorial pass — not a debate participant.
+
+The technical editor never participates in the debate. It receives only the final reconciled consensus draft and performs one job: making it read like it was written by one thoughtful human, not assembled by a committee.
+
+**Target register**: Conversational but professional — precise and confident without being stiff, friendly without being patronising. Think Notion's help docs or a well-edited Nature Methods protocol.
+
+**What it fixes**:
+- Tonal whiplash between sections written in different registers
+- Passive voice, hedging language, and throat-clearing openers
+- AI-characteristic patterns: overly balanced constructions, unnaturally complete enumerations, hollow transitions
+- Inconsistent formatting of UI elements, field labels, and callout styles
+- Sentence rhythm — deliberately varying length so the text reads as human
+
+**What it never changes**: factual content, compliance requirements, tool names, standard citations, the Debate Summary, or the proposal warning header.
+
+---
+
+## Output Format
+
+Every generated file in `docs/proposals/` follows this structure:
+
+```
+> ⚠️ PROPOSAL — Pending review and approval before adoption.
+
+## Debate Summary
+[Key conflicts between agents and orchestrator tie-break reasoning]
+
+---
+[Document content]
+```
+
+The Debate Summary is intentionally preserved in the final output. It gives human reviewers full visibility into where the agents disagreed and why a particular position was chosen — making the review process faster and more informed.
+
+---
+
+## Permissions & Write Access
+
+| Agent | Write access | Editable paths |
+|---|---|---|
+| `docs` (orchestrator) | ✅ Yes | `docs/proposals/` only |
+| `data-steward` | ❌ No | — |
+| `lab-personnel` | ❌ No | — |
+| `bioinformatician` | ❌ No | — |
+| `ls-user-guide` | ❌ No | — |
+| `technical-editor` | ❌ No | — |
+
+No subagent can write, edit, or overwrite any file in the repository. Only the orchestrator can write, and only to `docs/proposals/`. Existing files are never overwritten — a version suffix (e.g. `-v2`) is appended if a filename already exists.
+
+---
+
+## Extending the System
+
+**Adding a new agent perspective**: Define the new agent in `opencode.json` with `"write": false, "edit": false`. Update the orchestrator's `permission.task` block to include it, add it to Rounds 1 and 2 in the orchestrator prompt, and document it here.
+
+**Adding a new omic modality**: Update the `data-steward` and `bioinformatician` prompts in `opencode.json` with the relevant file formats, metadata standards, and pipeline tools. No structural changes to the debate protocol are needed.
+
+**Changing the editorial register**: Update the `technical-editor` prompt's target register description and reference points. The rest of the pipeline is unaffected.
+
+---
+
+*This file is maintained manually. When the agent configuration in `opencode.json` changes, update this file to reflect the change.*

docs/batch/sample-batch.md

@@ -1,111 +1,80 @@
-# Sample Batch
-[//]: # (What is a sample batch?)
-## Definition
+# Sample batches
 
-A sample batch forms a logical container of samples that are going to be shipped together to the
-measurement facility with the intention of being processed under the same conditions.
+## What is a sample batch?
 
-[//]: # (What is the purpose of grouping samples into batches?)
-## Intention 
+A sample batch is a group of samples shipped together to a measurement facility and processed under the same conditions. Tracking batches is how you identify and correct for **batch effects** — technical variation introduced when samples are processed at different times or under different conditions.
 
-Grouping and processing samples as distinct sample batches is key in properly tracking and avoiding batch effects.
-Click [here](https://pmc.ncbi.nlm.nih.gov/articles/PMC3880143/) for a quick introduction into batch effect and their impact on research data. 
+Undocumented batches are one of the most common causes of irreproducible results. [Learn more about batch effects](https://pmc.ncbi.nlm.nih.gov/articles/PMC3880143/).
 
-[//]: # (How do I add samples to my experiment?)
 ## Creating and registering sample batches
 
-We call the process of adding samples to an experiment "sample registration". 
-When you want to link samples to an experiment you need to register metadata for those samples.
+1. In the experiment summary, click **Register sample batch**.
 
-To **start** with the sample registration process, click on the button `Register sample batch` to open the sample registration dialog.
+2. **Download the template** — an Excel spreadsheet with one row per sample.
 
-Please go ahead and **download the metadata template file** from the dialog.
-In this file you can fill out information for the samples you want to register. 
+    !!! note "Mandatory fields"
+        Columns marked with an asterisk (`*`) are mandatory.
 
-!!! note
-    **Mandatory** information for the sample registration is marked by an asterix `*` after the column name.
+3. Fill in the template. For each sample, record its species, specimen, analyte, experimental group, and any other required details.
 
-**Once you filled out** all the information, you can go back to the dialog. In case you closed the dialog, simply re-open it.
-</br>
-Please go ahead and **upload your filled metadata file** in the dialog.
-Once the Data Manager validated the information in your file,
-go ahead and **choose a name for your batch**.
-</br>
-Once you named your batch and uploaded the file with the necessary information, go ahead and **click the
-`Register`** button. The Data Manager will now go through the process of creating samples within your
-experiment.
+    !!! tip "Sample IDs are assigned automatically"
+        Don't fill in the Sample ID column. The system generates a unique, permanent ID for each sample (e.g. `Q2ABCD001AA`) when you register the batch.
 
-!!! info "Email Notification"
-    Upon successful batch registration,
-    all [project collaborators](../project/project_access.md#add-collaborator) will automatically receive
-    an email with a link to the created batch.
+4. Upload the completed file in the registration dialog. The system validates it and highlights any errors.
 
-After the Data Manager is done registering your samples, you can **close** the dialog **by clicking the
-`Finish`** button.
-Now samples annotated with the provided metadata are registered to your experiment. You can see the
-newly created batch next to the other batches in the samples view.
+5. Enter a **batch name** (e.g. "Pilot cohort — January 2026").
 
-!!! info "SampleId"
-    Upon successful batch registration, each sample will be associated with a unique SampleId 
-    distinguishing it from other samples within the system
-    an email with a link to the created batch.
+6. Click **Register**. The system processes your samples in the background.
 
-[//]: # (How do I edit existing samples in my experiment?)
-## Editing sample batches
+7. Click **Finish** when done.
+
+!!! info "Email notification"
+    All [project collaborators](../project/project_access.md#add-collaborator) receive an email with a link to the new batch.
 
-You might need to edit sample metadata after registering the sample batch to the experiment.
-Editing sample information is restricted to editing the sample metadata. Adding or removing samples from a batch is not possible.
+??? info "Sample ID format"
+    Sample IDs follow the pattern `Q2XXXXNNNCC`: the six-character project code, a three-digit running number, and a two-character random suffix (e.g. `Q2ABCD001AA`). They are permanent and cannot be changed after registration.
+
+## Editing sample batches
 
-To **start** with the sample edit process, click on the edit button next to the batch you want to edit. This will open the batch editing dialog.
+You can update sample metadata after registration. You cannot add or remove individual samples from a batch.
 
-!!! info "Project role"
-    Should you not see the action column,   
-    please make sure that you have been granted the "write" or "admin" role to it by the project owner/admin.
+1. Click the **edit** button next to the batch.
 
-Please go ahead and **download the metadata template file** from the dialog.
-In this file you can fill out information for the samples you want to register. 
+    !!! info "Required role"
+        You need **write** or **admin** role.
 
-!!! note
-    **Mandatory** information for the sample editing is marked by an asterix `*` after the column name.
+2. **Download the current metadata** — the template is pre-filled with existing values.
 
-Note that the information in greyed out columns such as e.g. `Sample Id` is immutable and changes made within will not be registered during the sample editing process.
+3. Make your changes. Grey columns (e.g. `Sample Id`) are locked — changes there are ignored.
 
-!!! note
-    Information shown in greyed out columns are immutable and cannot be changed. 
+    !!! note "Mandatory fields"
+        Columns marked with `*` remain mandatory.
 
-**Once you filled out** all the information, you can go back to the dialog. In case you closed the dialog, simply re-open it.
-</br>
-Please go ahead and **upload your filled metadata file** in the dialog.
-Once the Data Manager validated the information in your file,
-go ahead and **choose a name for your batch** if you want to change it.
-</br>
-Once you named your batch and uploaded the file with the necessary information, go ahead and **click the
-`Edit batch`** button. The Data Manager will now go through the process of updating the sample information within your
-experiment.
+4. Upload the edited file, optionally rename the batch, and click **Edit batch**.
 
-After the Data Manager is done registering your samples, you can **close** the dialog **by clicking the
-`Finish`** button.
+5. Click **Finish**.
 
-[//]: # (How do I delete existing samples in my experiment?)
-## Delete a sample batch
+## Deleting a sample batch
 
-!!! warning "Batch Deletion"
-    Keep in mind, that deleting a batch will also delete all sample metadata of the samples within the batch
+!!! danger "This is irreversible"
+    Deleting a batch permanently removes all sample metadata for every sample in that batch.
 
-To **start** with the sample batch deletion process, click on the **`delete`** button next to the batch in question within the action column.
+!!! warning "Measurements must be removed first"
+    A batch can only be deleted if none of its samples are referenced by a measurement. [Delete the measurements](../measurement/measurement_edit.md#delete-measurements) first.
 
-!!! info "Project role"
-    Should you not see the action column,   
-    please make sure that you have been granted the "write" or "admin" role to it by the project owner/admin.
+1. Click the **delete** button next to the batch.
 
-This will open the batch deletion dialog requiring **confirmation** of the batch deletion process by clicking the **`Confirm`** button.
+    !!! info "Required role"
+        You need **write** or **admin** role.
 
-!!! warning "Attached Measurements"
-    Keep in mind, that batches can only be deleted if none of the samples within the batch have been used in a measurement.)
-    Otherwise, you need to delete the measurements in question before the batch can be deleted.
+2. Click **Confirm** in the dialog.
 
-[//]: # (How do I download sample metadata)
 ## Download sample metadata
 
-To **download** the sample metadata for all registered samples click on the **`Download sample metadata`** button.
-This will export all registered metadata as an `.xlsx` file to your local download directory.
+Click **Download sample metadata** to export all registered sample metadata as an `.xlsx` file. This is useful for copying sample IDs into [measurement registration spreadsheets](../measurement/measurement_registration.md).
+
+---
+
+## What's next
+
+➡ [Register measurements](../measurement/measurement_registration.md)

docs/developers/api.md

@@ -1,14 +1,22 @@
-# Data Manager API
+# API reference
 
-Access to resources in Data Manager via a RESTful API.
+Access Data Manager resources programmatically via a RESTful API.
 
-!!! info "API endpoints"
-    Currently, only one endpoint exists, which allows for a download of raw data. It is planned to extend the API in
-    the future to interact with various resources in Data Manager.
+!!! info "Available endpoints"
+    The API currently provides a single endpoint for raw data download. Additional endpoints are planned.
 
+## Documentation
 
-## Swagger API docs
+Interactive API documentation is available via Swagger UI:
 
-Detailed API documentation is available via Swagger UI and [hosted on the web service](https://download.qbic.uni-tuebingen.de/swagger-ui/index.html). 
+**[Open Swagger UI](https://download.qbic.uni-tuebingen.de/swagger-ui/index.html)**
 
+> Not familiar with the metadata fields? See the [Metadata glossary](../metadata/concepts.md).
 
+Authentication uses the same [personal access token](../rawdata/raw_data_download.md#personal-access-token) as the command-line download.
+
+---
+
+## What's next
+
+➡ [Download raw data](../rawdata/raw_data_download.md)