17: Recipes — the shapes a host writes, and what each policy does

[nikolaystrikhar]

What: adds docs/recipes.md — a settings toggle, a manifest of add-ons, the policy outcomes, the release rollout, version negotiation and per-site multisite activation — with the load gate chain, the policy branches and the rollout as Mermaid diagrams; linked from the README's doc list and from conflict-handling.md's version-negotiation note.

Read it rendered on the branch — the diagrams only draw in the blob view, not in this diff.

Usage:

Absorber::register( [
    'slug'                       => 'give-recurring',
    'bundled_plugin_file'        => GIVE_PLUGIN_DIR . 'sub-plugins/give-recurring/give-recurring.php',
    'plugin_loaded_constant'     => 'GIVE_RECURRING_VERSION',
    'standalone_plugin_basename' => 'give-recurring/give-recurring.php',
    'enabled'                    => static fn() => (bool) get_option( 'give_recurring_enabled', true ),
] );

Why this way:

Task-organized, in its own file. The five existing docs are organized by mechanism — every key, every filter, every gate — and none of them answers "how do I ship a toggle". The README is capped at ~120 lines and is at 84, so this could not go there.

The tagline's own case was undemonstrated. "Togglable or always-on" has been on the README since the first commit, and the only enabled example anywhere was a licence check. The toggle recipe also states the two things that surprise people: switching it off unloads nothing until the next request, and it stands the conflict pass down as well.

Version negotiation gets a worked example, not another disclaimer. It is the decision this library keeps being asked to reopen. Ten lines of conflict_policy filter is a cheaper answer than the paragraph explaining why it is out of scope.

Diagrams are Mermaid, and they parse. Every block was run through Mermaid's own parser, and every PHP snippet through php -l.