Enforce structured install step authoring

- reject mixing formula install hooks in every tap
- autocorrect legacy step methods and keywords
- retain stable serialised API values for compatibility
- document canonical Formula and Cask step authoring
- remove the resolved Cask sandbox deprecation reminder

docs/Cask-Cookbook.md

@@ -646,7 +646,7 @@ Relative paths default to `staged_path` for `base:`, `source_base:` and `target_
 * `remove`: remove one or more paths; example: `remove ["Shared/old", "Shared/*.bak"], recursive: true`.
 * `inreplace`: replace a string or regular expression in a file; example: `inreplace "Shared/foo.conf", "@PREFIX@", "{{HOMEBREW_PREFIX}}"`.
 * `symlink`: create a symlink; example: `symlink "Shared/payload", "Payload", source_base: :relative`.
-* `write_file`: atomically write exact literal content, replacing an existing file; example: `write_file "Shared/foo.conf", "key = value\n"`.
+* `write_file`: atomically write literal content, replacing an existing file by default; pass `append_newline: true` to ensure a trailing newline or `overwrite: false` to preserve it; example: `write_file "Shared/foo.conf", "key = value\n"`.
 * `delete_keychain_certificates`: delete macOS keychain certificates whose common name matches the argument; example: `delete_keychain_certificates "Charles"`. Pass `fingerprint_of:` with a local certificate path to delete only the matching SHA-256 fingerprint; example:
   `delete_keychain_certificates "NodeMITMProxyCA", fingerprint_of: "~/Library/Application Support/betwixt/ssl/certs/ca.pem"`.
 * `set_permissions`: recursively change existing path permissions with `chmod`; example: `set_permissions "Shared/payload", "0755"`.

docs/Formula-Cookbook.md

@@ -1067,7 +1067,7 @@ end
 
 Formulae in official Homebrew taps must represent post-install work with [`post_install_steps`](/rubydoc/Formula.html#post_install_steps-class_method); new `post_install` methods are rejected. These steps can be re-run separately with `brew postinstall <formula>`, are stored in the JSON API and do not require downloading source formula Ruby. A `post_install_steps` block may only contain the supported step calls with literal arguments. It cannot call the wider formula DSL or arbitrary Ruby code. Homebrew executes the steps with the same post-install sandbox policy.
 
-The legacy `post_install` method remains available temporarily for third-party tap compatibility, but is not an authoring interface for official formulae.
+The legacy `post_install` method remains available temporarily for third-party tap compatibility, but is not an authoring interface for official formulae. A formula cannot define both `post_install` and `post_install_steps`.
 
 ```ruby
 class Foo < Formula
@@ -1114,7 +1114,7 @@ end
 
 #### Default config and template steps
 
-`write_file` atomically writes its exact literal content, replacing an existing file. Specify its `base:`, such as `base: :etc`. Use `unless_path_exists` when a default file should preserve user edits across upgrades:
+`write_file` atomically writes its literal content, replacing an existing file by default. Specify its `base:`, such as `base: :etc`. Pass `append_newline: true` to ensure the content ends in a newline, `overwrite: false` to preserve an existing file or use `unless_path_exists` to guard a group of default-file steps:
 
 ```ruby
 unless_path_exists "foo.conf", base: :etc do
@@ -1195,6 +1195,7 @@ symlink_children "bin", suffix: "-{{version.major}}"
 These steps rebuild shared desktop and cache state using Homebrew-owned tools.
 
 * `compile_gsettings_schemas`: compile GSettings schemas in `share/glib-2.0/schemas`.
+* `update_gio_modules_cache`: update the GIO module cache in `lib/gio/modules`.
 * `update_gdk_pixbuf_loaders_cache`: update the GDK Pixbuf loader cache.
 * `update_gtk_icon_cache`: refresh the `hicolor` GTK icon cache.
 * `update_mime_database`: rebuild the shared MIME database in `share/mime`.