docs: Explain extensible builtin subs concept in builtin.vcl

Author: SashankBhamidi

bin/varnishd/builtin.vcl

@@ -28,7 +28,25 @@
 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 # SUCH DAMAGE.
 #
-# This is the builtin VCL code
+# This file contains the builtin VCL code.
+#
+# All subroutines in this file can be overridden by user-provided VCL.
+#
+# There are two main patterns for overridable subroutines:
+#
+# 1. `vcl_builtin_*` subroutines: These wrap core Varnish logic. When you
+#    override these in user VCL, your code runs first, followed by the
+#    builtin VCL code (unless you `return()`). Note that calling
+#    `vcl_builtin_*` from your own `vcl_builtin_*` does not work (triggers
+#    recursion check).
+#
+# 2. `vcl_req_*`, `vcl_beresp_*`, etc. subroutines: These act as specific
+#    "hooks" within the default Varnish behavior. Overriding these allows
+#    you to modify a narrow aspect of behavior without reimplementing the
+#    entire parent `vcl_builtin_*` logic.
+#
+# Consult the Varnish documentation for details on each subroutine and
+# its intended use.
 
 vcl 4.0;