[docs] Self-healing documentation fixes from issue analysis - 2026-05-28

docs/src/content/docs/reference/frontmatter-full.md

@@ -7690,7 +7690,7 @@ private: true
 # gh-aw repository and verifies the compiled version is not blocked and meets the
 # minimum supported version. Set to false to disable the check (not allowed in
 # strict mode). See:
-# https://github.github.com/gh-aw/reference/frontmatter/#check-for-updates
+# https://github.github.com/gh-aw/reference/frontmatter/#update-check-check-for-updates
 # (optional)
 check-for-updates: true
 
@@ -7701,7 +7701,7 @@ check-for-updates: true
 # supply chain security warning is emitted at compile time; in strict mode this is
 # an error. Per-runtime control is also available via
 # runtimes.<runtime>.run-install-scripts. See:
-# https://github.github.com/gh-aw/reference/frontmatter/#run-install-scripts
+# https://github.github.com/gh-aw/reference/frontmatter/#install-scripts-run-install-scripts
 # (optional)
 run-install-scripts: true
 

docs/src/content/docs/reference/frontmatter.md

@@ -508,6 +508,38 @@ The `private:` field only blocks installation via `gh aw add`. It does not affec
 
 Enable experimental or optional compiler and runtime behaviors as key-value pairs. See [Feature Flags](/gh-aw/reference/feature-flags/) for complete documentation.
 
+### Update Check (`check-for-updates:`)
+
+Controls whether the activation job verifies the workflow was compiled with a supported version of gh-aw.
+
+```yaml wrap
+check-for-updates: true   # default
+```
+
+When `check-for-updates: true` (the default), the activation job downloads `config.json` from the gh-aw repository and verifies the compiled version is not blocked and meets the minimum supported version. Set `check-for-updates: false` to skip this step — for example in air-gapped environments — but the workflow will no longer detect that it was compiled with an outdated or blocked version of gh-aw.
+
+`check-for-updates: false` is not allowed in [strict mode](#strict-mode-strict). In non-strict mode it emits a compile-time warning.
+
+### Install Scripts (`run-install-scripts:`)
+
+Allows npm `pre`/`post` install scripts to execute during package installation.
+
+```yaml wrap
+run-install-scripts: true
+```
+
+By default, the compiler appends `--ignore-scripts` to every generated npm install command to block install-time hooks, which are a common supply-chain attack vector. Setting `run-install-scripts: true` disables this protection globally for every runtime that generates npm install commands (currently `node`). The compiler emits a supply-chain security warning; in [strict mode](#strict-mode-strict) this is a compilation error.
+
+For finer-grained control, set the flag per runtime under [`runtimes:`](#runtimes-runtimes) instead:
+
+```yaml wrap
+runtimes:
+  node:
+    run-install-scripts: true
+```
+
+Only enable this flag when you trust every installed package and its transitive dependencies.
+
 ### Strict Mode (`strict:`)
 
 Disables enhanced security validation for production workflows.

pkg/parser/schemas/main_workflow_schema.json

@@ -9840,13 +9840,13 @@
     "check-for-updates": {
       "type": "boolean",
       "default": true,
-      "description": "Control whether the compile-agentic version update check runs in the activation job. When true (default), the activation job downloads config.json from the gh-aw repository and verifies the compiled version is not blocked and meets the minimum supported version. Set to false to disable the check (not allowed in strict mode). See: https://github.github.com/gh-aw/reference/frontmatter/#check-for-updates",
+      "description": "Control whether the compile-agentic version update check runs in the activation job. When true (default), the activation job downloads config.json from the gh-aw repository and verifies the compiled version is not blocked and meets the minimum supported version. Set to false to disable the check (not allowed in strict mode). See: https://github.github.com/gh-aw/reference/frontmatter/#update-check-check-for-updates",
       "examples": [true, false]
     },
     "run-install-scripts": {
       "type": "boolean",
       "default": false,
-      "description": "Allow npm pre/post install scripts to execute during package installation. By default, --ignore-scripts is added to all generated npm install commands to prevent supply chain attacks via malicious install hooks. Setting run-install-scripts: true disables this protection globally (all runtimes). A supply chain security warning is emitted at compile time; in strict mode this is an error. Per-runtime control is also available via runtimes.<runtime>.run-install-scripts. See: https://github.github.com/gh-aw/reference/frontmatter/#run-install-scripts",
+      "description": "Allow npm pre/post install scripts to execute during package installation. By default, --ignore-scripts is added to all generated npm install commands to prevent supply chain attacks via malicious install hooks. Setting run-install-scripts: true disables this protection globally (all runtimes). A supply chain security warning is emitted at compile time; in strict mode this is an error. Per-runtime control is also available via runtimes.<runtime>.run-install-scripts. See: https://github.github.com/gh-aw/reference/frontmatter/#install-scripts-run-install-scripts",
       "examples": [false, true]
     },
     "mcp-scripts": {