We are well aware that some parts of the documentation are lacking examples, or do not explain things clearly enough. However, as you said, it’s a free open source framework that is developed and maintained by a group of dedicated volunteers. As volunteers we don’t have the time needed to fix every shortcoming of the docs, and so we rely on users such as yourself to edit the documentation when shortcomings are discovered.
Now that you’ve figured out the modulus option, please add a good example into the docs! GitHub - cakephp/docs: CakePHP CookBook
Except that it does 
Where it talks about the url option.
You can also append additional URL content into all URLs generated in the helper
It even has an example of it, and to expand on it from your original post and requirements:
$this->Paginator->options([
'url' => [
'?' => $pagelinks
]
]);