Add about_Error_Handling and fix error terminology across docs (#12890)

* Add about_Error_Handling and fix error terminology across docs

Create a comprehensive about_Error_Handling reference topic that documents
PowerShell's three error categories: non-terminating, statement-terminating,
and script-terminating errors. Correct false claims in about_CommonParameters
and about_Preference_Variables that state -ErrorAction and
$ErrorActionPreference have "no effect on terminating errors." Update
about_Try_Catch_Finally, about_Throw, about_Trap, and
everything-about-exceptions to use precise terminology consistent with
existing usage in about_Calculated_Properties, about_Pipeline_Chain_Operators,
and about_Pwsh.

Fixes #1583

* Address mklement0 review: fix error terminology precision

- -ErrorAction Stop promotes to script-terminating, not statement-terminating
- $ErrorActionPreference applies to both non-terminating and
  statement-terminating errors (unlike -ErrorAction parameter)
- $ErrorActionPreference = 'Ignore' is now accepted (remove outdated caveat)
- Native command non-zero exit emits non-terminating NativeCommandExitException

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Comprehensive accuracy overhaul: escalation semantics, asymmetry, parse errors

Major corrections verified against PowerShell engine source code:

- Fix: -ErrorAction Stop produces script-terminating errors, not
  statement-terminating. ActionPreferenceStopException sets
  SuppressPromptInInterpreter=true, causing call-stack unwinding.
  Fixed across all 4 affected files.

- Add: New "$ErrorActionPreference asymmetry" section in
  about_Error_Handling documenting that $ErrorActionPreference applies
  to BOTH non-terminating and statement-terminating errors, while
  -ErrorAction only affects non-terminating errors. Includes runnable
  demo and IMPORTANT callout for exceptions (SuppressPromptInInterpreter,
  PS classes, PipelineStoppedException).

- Add: Parse errors to script-terminating generators list (per
  mklement0 review comment).

- Fix: about_Preference_Variables Ignore bullet incorrectly stated
  "Ignore isn't a valid value for $ErrorActionPreference" — it is
  accepted (only Suspend is rejected per ExecutionContext.cs).

- Fix: NOTE block on ThrowTerminatingError now correctly explains
  that $ErrorActionPreference can suppress it via the engine's
  statement-level handler in MiscOps.CheckActionPreference.

- Fix: Summary table updated — -ErrorAction Stop moved from
  statement-terminating to script-terminating column, new row added
  for $ErrorActionPreference behavior per error type.

- Fix: everything-about-exceptions.md — three remaining instances of
  vague "terminating error" updated to "script-terminating error" for
  throw and -ErrorAction Stop contexts.

All claims verified with live PowerShell 7.x tests:
  1. -ErrorAction Stop: next statement in scriptblock does NOT run (script-terminating)
  2. Parse errors: caught as MethodInvocationException
  3. $ErrorActionPreference='Ignore': accepted without error
  4. $ErrorActionPreference='SilentlyContinue': suppresses ThrowTerminatingError
  5. -ErrorAction SilentlyContinue: does NOT suppress ThrowTerminatingError

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Address mklement0 feedback: throw suppression, Ignore/$Error, advanced escalation

Three corrections based on mklement0's review:

1. throw CAN be suppressed by $ErrorActionPreference when set to
   SilentlyContinue or Ignore. Removed the incorrect claim that throw
   is "always" script-terminating "regardless of $ErrorActionPreference".
   Also documented that -ErrorAction on advanced functions translates
   to a scope-local $ErrorActionPreference, so it suppresses throw too.

2. Added NOTE that $ErrorActionPreference = 'Ignore' still records
   terminating errors in $Error. Ignore only prevents $Error recording
   for non-terminating errors.

3. Escalation section now documents the advanced vs. non-advanced
   distinction: $ErrorActionPreference = 'Stop' produces
   script-terminating errors in non-advanced contexts, but
   statement-terminating errors in advanced contexts ([CmdletBinding()]).
   Summary table updated to reflect both contexts.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Refine escalation terminology: terminating (context-dependent) not script-terminating

Per mklement0 feedback, -ErrorAction Stop escalation scope depends on
whether the context is advanced ([CmdletBinding()]) or non-advanced.
Changed about_CommonParameters.md and ErrorAction table to say
"terminating error" generically, with escalation section providing
the full advanced vs. non-advanced explanation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Extend error handling accuracy to about_Throw, about_Try_Catch_Finally

- about_Throw: Add $ErrorActionPreference suppression caveat (throw CAN
  be suppressed by SilentlyContinue/Ignore), add NOTE block with Ignore
  still recording in $Error, update description to "by default"
- about_Try_Catch_Finally: Add NOTE about throw suppression with cross-ref
  to about_Error_Handling, fix $tempPath -> $tempFile code bug (line 264)
- about_Preference_Variables: Fix Ignore bullet - clarify that Ignore only
  prevents $Error recording for non-terminating errors, not terminating
- everything-about-exceptions: Change -ErrorAction Stop from
  "script-terminating" to "terminating" (context-dependent behavior)

All claims verified against live PowerShell 7.6 behavior.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Final polish: qualify Ignore/$Error claims and About.md index

- About.md: Update throw index to "script-terminating error by default"
- about_Automatic_Variables: Qualify $Error/Ignore as non-terminating only
- about_CommonParameters: Qualify Ignore bullet as non-terminating only

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add about_Error_Handling to index; fix stale descriptions and dates

- About.md: Add missing about_Error_Handling entry to topic index
- About.md: Update about_Trap and about_Try_Catch_Finally descriptions
  to say "statement-terminating and script-terminating errors"
- about_Try_Catch_Finally.md: Fix [07] link text to match target heading
- Update ms.date on about_Trap, about_CommonParameters,
  about_Preference_Variables, everything-about-exceptions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Editorial changes - mostly formatting

* Copy changes to all versions

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Sean Wheeler <sean.wheeler@microsoft.com>

Author: 3 people

reference/5.1/Microsoft.PowerShell.Core/About/about_Automatic_Variables.md

@@ -1,7 +1,7 @@
 ---
 description: Describes variables that store state information for PowerShell. These variables are created and maintained by PowerShell.
 Locale: en-US
-ms.date: 02/10/2026
+ms.date: 04/02/2026
 no-loc: [Reset, Current, Background, Blink, Bold, Foreground, Formatting, Hidden, Italic, Reset, Reverse, Underline, PSEventArgs, PSEventSubscriber, PSEdition]
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
@@ -160,8 +160,8 @@ use this automatic variable to determine the file to update.
 Contains an array of error objects that represent the most recent errors. The
 most recent error is the first error object in the array `$Error[0]`.
 
-To prevent an error from being added to the `$Error` array, use the
-**ErrorAction** common parameter with a value of **Ignore**. For more
+To prevent a non-terminating error from being added to the `$Error` array, use
+the **ErrorAction** common parameter with a value of **Ignore**. For more
 information, see [about_CommonParameters][53].
 
 ### `$Event`

reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md

@@ -1,7 +1,7 @@
 ---
 description: Describes the parameters that can be used with any cmdlet.
 Locale: en-US
-ms.date: 01/18/2026
+ms.date: 04/02/2026
 no-loc: [Confirm, Debug, ErrorAction, ErrorVariable, InformationAction, InformationVariable, OutBuffer, OutVariable, PipelineVariable, ProgressAction, Verbose, WarningAction, WarningVariable, WhatIf]
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_commonparameters?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
@@ -109,14 +109,13 @@ the display of debugging messages when `$DebugPreference` isn't
 ### -ErrorAction
 
 Determines how the cmdlet responds to a non-terminating error from the command.
-This parameter works only when the command generates a non-terminating error,
-such as those from the `Write-Error` cmdlet.
+This parameter overrides the value of the `$ErrorActionPreference` variable for
+non-terminating errors generated by the command or the `Write-Error` cmdlet.
 
 ```yaml
 Type: ActionPreference
 Aliases: ea
-Accepted values: Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
-
+Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
 Required: False
 Position: Named
 Default value: Depends on preference variable
@@ -129,9 +128,12 @@ variable for the current command. Because the default value of the
 `$ErrorActionPreference` variable is `Continue`, error messages are displayed
 and execution continues unless you use the `ErrorAction` parameter.
 
-The `ErrorAction` parameter has no effect on terminating errors (such as
-missing data, parameters that aren't valid, or insufficient permissions) that
-prevent a command from completing successfully.
+The `-ErrorAction` parameter doesn't prevent statement-terminating errors
+(such as missing data, parameters that aren't valid, or insufficient
+permissions) from stopping the current statement. However, when set to `Stop`,
+it escalates non-terminating errors to script-terminating errors, making them
+catchable by `try/catch`. For more information about error categories, see
+[about_Error_Handling][15].
 
 - `-ErrorAction:Break` Enters the debugger when an error occurs or an exception
   is raised.
@@ -829,6 +831,7 @@ Mode                LastWriteTime     Length Name
 
 <!-- Using backtick on cmdlet names to avoid localization -->
 - [about_Preference_Variables][03]
+- [about_Error_Handling][15]
 - [`Write-Debug`][11]
 - [`Write-Error`][12]
 - [`Write-Verbose`][13]
@@ -844,4 +847,5 @@ Mode                LastWriteTime     Length Name
 [12]: xref:Microsoft.PowerShell.Utility.Write-Error
 [13]: xref:Microsoft.PowerShell.Utility.Write-Verbose
 [14]: xref:Microsoft.PowerShell.Utility.Write-Warning
+[15]: about_Error_Handling.md