Hi Wim,
The two fundamental script libraries that 'run' the workflows are the QAF WF Runtime and QAF WF API. The Runtime library is responsible for performing all the functions to implement the workflow logic in the Notes user interface. This library uses the API to perform lower level functions.
You can use any API functions in any of your code to do things that are not provided 'out of the box' so to speak, such as your need to refresh security outside of the normal QAF Actions.
Yes documentation is limited! So please ask any questions you like here. Is is quite common with open source code to try to make the names of functions and the names of their parameters as intuitive as possible, so a little experimentation should reveal how each function works. It's a good idea to browse through the functions in the API to get an idea of the sort of things you can do to manipulate/ trigger the workflow engine, outside of standard QAF Actions.
In principle, the API can be leveraged to produce a completely different run-time interface, such as a browser based interface.
Mark