+There have to be no mutating C<GET> requests in your application (but
+you shouldn't have any of those anyway); if there are, they won't
+work. (CGI::Auth::Flexible will spot them and cause them to fail,
+rather than allow them to be insecure.)
+
+=head2 GENERATING URLS, FORMS AND AJAX QUERIES
+
+When you generate a URL, C<POST> form or AJAX request you may need to
+include a secret hidden form parameter for the benefit of
+CGI::Auth::Generic. This form parameter will be checked by
+C<check_ok>/C<check_divert> and should be ignored by your application.
+
+By default the hidden parameter is called C<caf_assochash>.
+
+After calling C<check_ok> or C<check_divert> the value to put in your
+form can be obtained from C<secret_hidden_val>; C<secret_hidden_html>
+will generate the whole HTML C<< <input...> >> element.
+
+=head3 Mutation-ignorant applications
+
+For mutation-ignorant applications (see above), all forms etc. should
+include the hidden parameter (and as discussed, they must all use
+POST rather than GET).
+
+=head3 Mutation-aware applications
+
+For mutation-aware applications, whether to include the secret
+parameter depends on the kind of request. CGI::Auth::Flexible knows
+when it is necessary. You should find out by calling
+C<need_add_hidden>.
+
+If it is inconvenient to call C<need_add_hidden> at runtime, you can
+rely instead on the following promises: All POST requests (which
+includes all mutating requests) need the parameter. The return value
+of need_add_hidden depends only on the $method and $reqtype
+parameters, so you can query it once and remember the answer.
+HTML page load GETs do not need the parameter. It is better to
+err on the side of including the parameter.
+
+If you really must, you can call C<need_add_hidden> "on the bench"
+during development and bake the answer into your application code
+structure. However, if you do that and a new vulnerability was
+discovered which is fixed by changing the answer, updating
+CGI::Auth::Flexible wouldn't be sufficient to fix it.
+
+=head3 Mutation-aware applications - non-page requests
+
+If your mutation-aware application supports non-page resources (AJAX
+and JSON requests, stylesheets, favicons, etc.) it must inform
+CGI::Auth::Flexible when it is handling such a request, by calling
+C<check_nonpage>.
+
+Normally C<check_nonpage> will simply return (and you can ignore the
+return value). However, if there is an attack (or, perhaps, a bug) it
+will die, stopping the attack.
+
+(You do not need to call C<check_nonpage> for POST requests, but it is
+harmless to do so.)