Readme updates

README.md

@@ -130,6 +130,10 @@ The full documentation is at [hapapp.readthedocs.io](https://hapapp.readthedocs.
 | Marker lookup table | `assign` | CSV of the MADC's marker names and your standard marker IDs. `build-db` writes one |
 | Allele database and count table | `assign` | The latest versions from `build-db` or an earlier `assign` run |
 
+The MADC report can come straight from DArT genotyping, or you can generate one from FASTQ files with
+[MADCATS](https://madcats.readthedocs.io). [What is a MADC file?](https://softwarehub.breedinginsight.org/learn/what-is-a-madc-file.html)
+explains the format.
+
 ## Output
 
 `assign` writes these files to the run's folder:
@@ -144,6 +148,10 @@ The full documentation is at [hapapp.readthedocs.io](https://hapapp.readthedocs.
 | `hapSearch/sample_hapStatus/*_hapStatus.csv` | Which samples contain each allele |
 | `run_manifest.json` | Status, counts, warnings, tool versions and input checksums |
 
+To turn the report with fixed allele IDs into a VCF, see
+[Convert MADC data to a genotype-called VCF](https://softwarehub.breedinginsight.org/learn/madc-to-vcf.html), which uses
+[BIGr](https://softwarehub.breedinginsight.org/software/bigr.html).
+
 ## Development
 
 ```bash
@@ -162,9 +170,6 @@ If you use HapApp_utils in your work, please cite:
 > assessing and mining crop genetic diversity. *Theoretical and Applied Genetics* 139(9):244.
 > https://doi.org/10.1007/s00122-026-05340-4
 
-For the MADC format, see Breeding Insight's
-[What is a MADC file?](https://softwarehub.breedinginsight.org/learn/what-is-a-madc-file.html).
-
 **AI assistance:** AI assistance applies to version 2 of HapApp_utils and its documentation, not to version 1. Dongyan
 Zhao wrote version 1, the step scripts and bash workflows. For version 2, Claude Opus 5.5 (Anthropic) helped convert those
 workflows into the Python command-line tool, fix bugs in the step scripts, and write the tests and documentation. The

docs/src/development/contributing.md

@@ -35,11 +35,17 @@ tags on `release` that publish the package.
 
 Merges go one way. Merging `release` into `master` would bring the whole package layout with it.
 
+`release` only accepts pull requests, so make the merge on a new branch and open a pull request from it into `release`:
+
 ```bash
-git switch release
-git merge master
+git fetch upstream
+git switch -c merge-master upstream/release
+git merge upstream/master
 ```
 
+Merge that pull request with **Create a merge commit**. A squash merge would lose the link to `master`, so the next
+merge would report the same conflicts again.
+
 Git follows the moved files, so most edits to existing scripts land in `src/hapapp_utils/steps/` with no conflict.
 These changes need more from you:
 
@@ -138,7 +144,7 @@ come from the Breeding Insight palette.
 Pushing a version tag from `release` publishes the package to PyPI through `.github/workflows/release.yml`.
 
 1. Set `__version__` in `src/hapapp_utils/__init__.py` and add the version to the [Changelog](changelog.md).
-2. Merge that change into `release`.
+2. Merge that change into `release` with a pull request.
 3. Tag the merged commit and push the tag, using the new version number:
 
 ```bash

docs/src/getting-started/input-files.md

@@ -11,6 +11,10 @@ from the header row:
 
 Each marker needs a `Ref` and an `Alt` row. Export the report as CSV, not Excel.
 
+The MADC report can come straight from DArT genotyping, or you can generate one from FASTQ files with
+[MADCATS](https://madcats.readthedocs.io). [What is a MADC file?](https://softwarehub.breedinginsight.org/learn/what-is-a-madc-file.html)
+explains the format.
+
 ```text
 AlleleID,CloneID,AlleleSequence,5236,5237,...
 Chr01_000120735|Ref,Chr01_000120735,GGTGATGAGTGGAGTT...,0,12,...