expansion.yaml

version: 59

# Percent-tilde (%~) expansion rules
# Authoritative syntax: audit/cmd-help/call-help.txt (CALL /?)
# Requires Command Extensions (CALL /?); see command_extensions_off.

valid_modifiers:
  n: name
  x: extension
  f: full path
  d: drive
  p: path
  s: short names
  t: timestamp
  z: size
  a: attributes
  $: path search (e.g. %~$PATH:1)

# Letter modifiers for %~dpnx... combinations. Path-search $ is separate; see path_search_modifier.
valid_modifier_chars: "nxfpdstaz"

valid_parameter_patterns:
  - digit_0_9
  - for_var_letter

invalid_combinations:
  - modifiers: "*"
    reason: "%~ modifiers may not be used with %* (CALL /?)"
  # Matches forms like %~q1 or %~dq1 where a letter is outside nxfpdstaz.
  # Does not match %~1, %~dpnx0, %~DPNX0, %~*, or %~$PATH:1. Letter classes
  # include both cases because modifiers are case-insensitive (FOR /?, CALL /?).
  # Note: %~* is still semantically invalid (see modifiers: "*" above); the
  # letter-regex simply does not catch the star form because * is an allowed
  # terminator.
  - pattern: "%~[nxfpdstazNXFPDSTAZ]*[^0-9*$nxfpdstazNXFPDSTAZ]"
    reason: >-
      Percent-tilde letter modifiers must be from nxfpdstaz (case-insensitive;
      CALL /?, FOR /?); the parameter must be 0-9, *, or a path-search $ENV: form

valid_combined_examples:
  - "%~1"
  - "%~dpnx1"
  - "%~f1"
  - "%~nx1"
  - "%~fs1"
  - "%~dp0"
  - "%~z0"
  - "%~ftza1"
  - "%~dp$PATH:1"

path_search_modifier:
  pattern: "%~$ENV:parameter"
  description: "Searches PATH or other env var for file; expands to first match"
  example: "%~$PATH:1"
  empty_on_miss: >-
    When the named environment variable is undefined or no matching file is
    found, %~$ENV:n expands to an empty string (CALL /?).
  cwd_not_implicit: >-
    Path search walks only the semicolon-separated directories listed in the
    named environment variable. A file that exists only in the current
    directory is a miss (empty expansion) unless that CWD path is present in
    the env var. First listed match wins (CALL /?; confirmed on live Windows
    10/11 cmd).
  combine_with_letter_modifiers: >-
    Letter modifiers may precede the $ENV: search (for example %~dp$PATH:1
    expands to the drive+path of the first PATH hit). The $ENV: form still
    terminates the modifier sequence; a miss expands to empty.

percent_tilde_notes:
  requires_command_extensions: >-
    Percent-tilde (%~) modifiers and path-search forms require Command
    Extensions (CALL /?). With extensions disabled, %~1 / %~dp0 / %~$PATH:1
    are not expanded (the leading % is consumed and the remainder such as
    ~1 or ~dp0 remains literal text). Base %0-%9 still expand without
    extensions.
  bare_quote_strip: "%~1 strips surrounding quotes from the parameter with no letter modifiers"
  multi_digit_parameter: >-
    %~10 is %~1 followed by literal 0; a single digit or a path-search $ENV:
    form terminates %~ (CALL /?). %~* is not a valid terminator (CALL /?
    forbids percent-tilde with %*) and is a live / grammar syntax error.
  adjacent_literal_after_digit_param: >-
    After a single-digit %~ parameter (%~dp0, %~1, and peers), immediately
    adjacent alphanumeric text is literal (for example %~dp0log.txt expands as
    %~dp0 followed by log.txt, and %~10 is %~1 plus literal 0). Cross-ref
    batch_parameters.multi_digit_percent and percent_tilde_notes.multi_digit_parameter.
  syntax_rejects: >-
    Live cmd rejects invalid percent-tilde forms with a path-operator message
    and "The syntax of the command is incorrect." (exit 255). Covered rejects
    include unknown letter modifiers (%~q1 / %~q1%), %~*, and %~name% spellings
    that look like env vars. The grammar emits syntax errors for those forms;
    valid %~1 / %~dp0 / %~$PATH:1 remain clean parses. Parallel FOR metavariable
    forms such as %%~qf / %%~* / %%~q$PATH:i are NOT syntax errors: live leaves
    the unresolved %~... text literal and continues (see
    for_loop_variables.tilde_invalid_modifier_not_syntax).
  for_metavar_parallel: >-
    The same letter modifiers (nxfpdstaz) and path-search $ENV: forms apply to
    active FOR metavariables (%%~fI / %%~$PATH:I / %%~zA for file size on
    metavar A). Unlike batch-parameter %~q1,
    an unknown letter before a FOR metavar is absorbed into the %%~ scan and is
    not a path-operator syntax abort.
  modifier_order_independent: >-
    Letter modifiers may be combined in any order (%~dpnx0 and %~nxdp0 are
    equivalent).
  modifier_case_insensitive: >-
    Letter modifiers are not case-sensitive (%~DPNX0 and %~dpnx0 are equivalent;
    FOR /?).
  attribute_mask: >-
    %~a / %%~a expands to a fixed-width attribute mask (commonly 11 characters)
    using letters and dashes in DIR-like slots (for example --a-------- for an
    archive file). Missing files expand the attribute field to empty (CALL /?).
  bare_vs_f_qualification: >-
    Bare %~1 / %%~ strips quotes but keeps the argument spelling (relative or
    as given). The f modifier (%~f1 / %%~f) expands to a fully qualified path
    based on the current directory when the argument has no drive/path; this
    happens even when the target file does not exist. Combining F with other
    letters (for example %~Ff1) is equivalent for qualification (CALL /?).
  f_overrides_component_selectors: >-
    When F is combined with component-selector letters (n/x/d/p), live cmd still
    expands to the fully qualified path: %~fnx1, %~nxf1, %~df1, %~pf1, and peers
    all yield the same full path as %~f1. F dominates; the other letters do not
    narrow the result to name/ext/drive/path alone. Confirmed on live Windows
    10/11 cmd.
  bare_quote_strip_leading_trailing: >-
    %~1 removes at most one leading quote character and one trailing quote
    character by position. Interior quotes remain (call :label "a""b" with an
    embedded doubled pair keeps interior quotes after strip; call :label
    "abc"def"ghi" yields abc"def"ghi for %~1). An unbalanced leading or trailing
    quote is still stripped on that side alone. Confirmed on live Windows 10/11
    cmd.
  directory_zat_modifiers: >-
    %~z / %~a / %~t apply to directory arguments as well as files. For an
    existing directory, %~z returns a filesystem-dependent size value (often 0
    for a newly created empty directory and a non-zero value for some populated
    directories), not the empty miss used for missing paths. %~a / %~t likewise
    report directory attributes and timestamps. Confirmed on live Windows 10/11
    cmd; treat exact %~z digits as host/filesystem-dependent.
  short_name_form: >-
    The s modifier requests short (8.3) name components. %~s1 / %%~s and
    combinations such as %~sf1 expand to a fully qualified path whose path
    segments use short names where available (not a basename-only short name).
    When short names are unavailable, cmd may still return a qualified path
    (CALL /?; filesystem-dependent).
  timestamp_format: >-
    %~t / %%~t expands to the file's last-write date/time using the locale's
    DATE/TIME formatting (separators and AM/PM style vary). Missing files
    expand the timestamp field to empty (CALL /?).
  dp0_trailing_backslash_quote: >-
    %~dp0 (and other %~dp forms) always end with a trailing backslash. Closing
    a quoted path immediately after that backslash then appending more text
    (for example "%~dp0"foo) can treat the \" as an escaped quote and break
    the intended argument boundary. Prefer "%~dp0foo" or "%~dp0%foo%" so the
    closing quote does not follow the trailing backslash. Confirmed on live
    Windows 10/11 cmd that %~dp0 ends with \.

percent_expansion:
  undefined_is_empty: >-
    Inside a .cmd/.bat script, an undefined name expands to an empty string for
    both %name% and (when delayed expansion is enabled) !name!. Incomplete forms
    without a closing % are not treated as successful expansions.
  interactive_undefined_literal: >-
    On the interactive command line, an undefined %name% often remains as the
    literal text %name% rather than expanding to empty (script behavior differs;
    see undefined_is_empty). Confirmed on live Windows 10/11 cmd as a common
    interactive-vs-script mode difference; portable scripts must not assume
    prompt behavior.
  script_vs_interactive_modes: >-
    Several expansion spellings differ between .bat/.cmd scripts and the
    interactive prompt: undefined %name% (empty in scripts; often literal at
    the prompt); FOR metavars (%%i in scripts; %i interactively); SET /A modulo
    (%% in scripts; % interactively). Prefer always testing scripted forms when
    authoring SoT fixtures or consumer tooling. Cross-ref
    interactive_undefined_literal, double_percent, and set_a.modulo_in_batch.
  incomplete_unclosed: >-
    An unclosed %name form (no matching closing %) is not a successful expansion.
    In scripts, cmd typically strips the leading % and leaves the following text
    as literals (for example %NOSUCH becomes NOSUCH; a lone % may yield empty).
    Prefer always-closed %name% / %% forms for portable scripts.
  compound_line_expansion: >-
    Percent expansion runs over the entire physical line before any chained
    command on that line executes. Confirmed on live Windows 10/11 cmd:
    set "x=1" then set "x=2"&echo %x% prints 1 (the pre-line value), while a
    following echo %x% prints 2. The same pre-command binding applies across
    && on a successful left-hand side. Prefer delayed expansion or CALL
    reparse when a later chained command must see an earlier same-line SET.
  injects_command_metacharacters: >-
    After percent expansion, & | < > in the expanded text re-enter command
    parsing. Storing set "a=val&ue" then unquoted echo [%a%] splits on &
    (often "'ue]' is not recognized..."). Quoted forms such as echo ["%a%"]
    and delayed echo [!a!] keep the ampersand intact. Confirmed on live
    Windows 10/11 cmd.
  adjacent_percent_pair_eating: >-
    Percent expansion pairs the nearest closing % after an opening %, so
    intervening text (including spaces and ordinary words) becomes a candidate
    variable name. In a script, an undefined name expands to empty. Confirmed
    on live Windows 10/11 cmd: echo Between 60% and 80% of X prints
    Between 60 of X because % and 80% is treated as an undefined name (the
    candidate includes the leading space after 60; SET strips leading spaces
    from names, so that exact name is not creatable via ordinary SET and the
    pair always collapses to empty). When the intervening name is creatable
    and defined, its value is substituted (echo 60%foo%80 with set foo=DEFINED
    prints 60DEFINED80). Prefer %% for literal percents in scripts
    (echo Between 60%% and 80%% of X) or break the pair. Distinct from
    incomplete_unclosed (no closing %).

delayed_expansion:
  pattern: "!VAR!"
  requires_setlocal: false
  default_off: >-
    Delayed expansion is disabled by default (CMD /?, SET /?). Enable it
    explicitly via cmd /V:ON, SETLOCAL EnableDelayedExpansion, or the Command
    Processor DelayedExpansion registry value.
  literal_when_disabled: >-
    When delayed expansion is disabled, !var! (including substring and replace
    forms) is ordinary literal text and is not expanded.
  orthogonal_to_extensions: >-
    Delayed expansion is independent of Command Extensions. cmd /E:OFF /V:ON
    (or SETLOCAL DisableExtensions EnableDelayedExpansion) still expands plain
    !var! forms. Percent and delayed substring/replace ops (%var:~% / !var:~!
    and :old=new) still require extensions; with extensions off those forms
    expand to empty rather than performing substring/replace or leaving the
    !var:~...! / %var:~...% text literal.
  enable_keywords:
    - "setlocal enabledelayedexpansion"
    - "setlocal enableextensions enabledelayedexpansion"
  disable_keywords:
    - "setlocal disabledelayedexpansion"
    - "setlocal enableextensions disabledelayedexpansion"
  enable_paths:
    - "cmd /V:ON"
    - "SETLOCAL EnableDelayedExpansion"
    - "registry Command Processor DelayedExpansion"
  disable_paths:
    - "cmd /V:OFF"
    - "SETLOCAL DisableDelayedExpansion"
    - "registry Command Processor DelayedExpansion=0"
  midline_enable_immediate: >-
    SETLOCAL EnableDelayedExpansion takes effect for later chained commands on
    the same physical line. Confirmed on live Windows 10/11 cmd: set "x=1" then
    setlocal enabledelayedexpansion & echo !x! prints 1 (not literal !x!).
    Percent expansion remains bound for the whole line before any command runs
    (see percent_expansion.compound_line_expansion).
  substring_pattern: "!var:~start,length!"
  replacement_pattern: "!var:old=new!"
  not_batch_parameters: >-
    Delayed !n! / !name! forms expand ordinary environment variables, not
    batch argument slots. !1! is the env var named 1 (if defined), never %1.
    There is no delayed peer of %1-%9 / %* / %~. Assign parameters to env vars
    first (set "arg=%~1") then use !arg! / %arg:~...% / %arg:old=new% as needed.
    Confirmed on live Windows 10/11 cmd: with %1=hello and set 1=ENV, !1!
    expands to ENV while %1 remains hello.
  digit_leading_names: >-
    Environment names that start with a digit expand with delayed !name! forms;
    percent %1name% is parsed as argument %1 plus literal text (not %1name%).
    Likewise %*name% is always %* plus literal text; a name cannot start with *
    for percent expansion.
  exclamation_escaping: >-
    With delayed expansion enabled, a literal ! commonly needs caret escaping
    such as ^^!. A single ^! is not enough: live cmd typically emits nothing
    useful for that form (confirmed: echo [^!] prints empty brackets). The same
    ^^ before a non-! character yields a single caret (for example ^^2 becomes
    ^2). Extra caret pairs continue to interact with bang phases (for example
    ^^^^! yields a single caret and ^^^^^^! yields ^!), so bang escaping is
    phase-sensitive and not identical to ordinary caret doubling for other
    characters.
  case_insensitive_search: >-
    Delayed !var:old=new! search is case-insensitive, matching percent
    %var:old=new% behavior; replacement text is literal.
  indirect_expansion: >-
    With delayed expansion enabled, percent expansion runs before delayed
    expansion, so !%name%! first substitutes %name% then expands the resulting
    !value! at execution time (for example set Car=Toyota & set Toyota=Prius
    yields !%Car%! -> Prius). Related forms such as !prefix%name%! /
    !%name%suffix! follow the same two-phase substitution. Without delayed
    expansion, !...! is literal text.
  block_indirect_percent_binding: >-
    Inside a parenthesized IF/FOR block, %name% is still the pre-block value, so
    !prefix%name%! builds the bang name from that frozen percent value even when
    set name=... runs earlier in the same block (for example set "city=NYC"
    then echo !food%city%! still uses the pre-block city). To compose a name
    assigned in the block, bind it through a FOR metavar
    (FOR /F %%x in ("!name!") do ...), CALL with %~1, or a CALL reparse such as
    call echo %%food!city!%%, rather than expecting !prefix%name%! to see the
    in-block assignment.
  for_accumulate_pattern: >-
    With delayed expansion enabled, a FOR body can accumulate with forms such
    as set "LIST=!LIST! %%i" so each iteration sees the updated LIST. Plain
    %LIST% expands when the FOR block is parsed and stays fixed for the loop;
    if LIST starts empty, set LIST=%LIST% %%i therefore keeps only the last
    iteration's contribution rather than building a growing list.
  value_with_exclamation: >-
    When delayed expansion is enabled, a value that contains ! (and often ^) can
    be corrupted at SET time if delayed expansion is already on during the
    assignment. Live cmd commonly stores set "A=hi!there" as hithere (the bang
    and following text are mangled) even before a later read. Prefer disabling
    delayed expansion while assigning such data (setlocal DisableDelayedExpansion
    / endlocal around the SET), then re-enable before reading with !var!. Do not
    rely on a single ^! inside the SET value under delayed-on: live probes such
    as set "B=hi^!there" still corrupt the stored text. Separately, once an
    intact bang-bearing value exists (stored with delayed off), reading it with
    %var% re-scans the inserted text for !name! under delayed expansion and can
    mangle it, while direct !var! keeps embedded ! characters (confirmed on live
    Windows 10/11 cmd: store aa!bb!cc with delayed off, then with delayed on %V%
    yields aacc and !V! yields aa!bb!cc). Prefer !var! (or delayed off) when
    values may contain !.
  call_second_pass: >-
    CALL reparses its command tail after percent expansion, so a second
    percent-expansion pass is available. With delayed expansion enabled,
    patterns such as call set "out=%%%name%%%" (after set name=other and
    set other=value) expand %name% on the first pass, then expand %other% on
    the CALL reparse, storing value in out. Related forms call echo %%var%%
    similarly print the current value after reparse. This is distinct from
    single-pass !%name%! indirect expansion.
  writing_batch_files: >-
    With delayed expansion enabled, emitting a later-expanding bang form into
    a child .cmd/.bat requires caret-escaping the ! in the parent so the
    parent does not expand it while writing. A common pattern is
    echo echo ^^!var^^!>>child, which stores echo !var! in the child for the
    child's delayed-expansion pass (confirmed on live Windows 10/11 cmd).
    See also double_percent.writing_batch_files and
    caret_escape.writing_batch_files.

for_loop_variables:
  batch_file_prefix: "%%"
  command_line_prefix: "%"
  letter_charset: "a-zA-Z0-9?#$@_`[]{}+.-\\!*():/~"
  letter_charset_notes: >-
    Live cmd.exe accepts letters, digits, and many punctuation characters as the
    single FOR variable letter, including tilde (for %%~ in (hello) do ...).
    Bare %%~ is a metavar whose letter is ~; %%~~ is quote-strip of that metavar.
    When additional letters follow %%~, longest-match %%~ modifier forms
    (FOR_VAR_TILDE) take precedence (for example %%~fI). Operators that fail as
    FOR letters include % | & = ; < >. Prefer letters to avoid clashing with
    %0-%9.
  tilde_invalid_modifier_not_syntax: >-
    Unlike batch-parameter %~q1 (a live syntax error), FOR forms with unknown
    tilde letters such as %%~qf, %%~*, or %%~q$PATH:i are accepted: live cmd
    leaves the unresolved %~... text as literals and continues the script. The
    grammar likewise does not report those FOR forms as syntax errors.
    Confirmed on live Windows 10/11 cmd.
  case_sensitive: >-
    FOR variable letters are case-sensitive (%i and %I are distinct). Up to 52
    active FOR variables may be in use (a-z and A-Z).
  metavar_adjacent_literal: >-
    After a FOR metavariable expands, immediately adjacent literal text stays
    attached with no separator (for example in a batch file %%n0 is the value of
    %%n followed by literal 0, not a two-digit metavariable). This is distinct
    from %%~n modifiers (tilde forms) and from %~10 / %%~n0 parameter-style
    multi-digit batveats. Prefer letters for metavars when a digit suffix is
    intended as a literal.
  undeclared_metavar_literal: >-
    A %%letter form that is not an active FOR metavariable in the current DO
    body expands as a literal %letter (the %% percent-escape), not as empty.
    Example: FOR /F "tokens=1-2" %%a IN ("one two three") DO echo %%c prints
    %c because only %%a and %%b were implied. Digits are valid FOR letters;
    multi-token implication walks ASCII succession from the declared letter
    (including digit starts such as %%7 -> %%8 -> %%9), not only a-z / A-Z.

for_forms:
  description: >-
    With Command Extensions, FOR supports /D (directories only), /R (recursive
    tree; optional root path, default current directory), /L (numeric
    start,step,end), and /F (parse text from files, strings, or command output).
    Source: FOR /?.
  slash_d: >-
    FOR /D matches directory names only when the set contains wildcards.
  slash_r: >-
    FOR /R walks the directory tree rooted at an optional path (default: current
    directory). A trailing backslash on the root path is accepted and equivalent
    to the same path without it (for /R C:\dir\ and for /R C:\dir). A set that
    is only '.' enumerates each directory visited (including the root of the
    walk). When the set has no wildcards (* or ?), FOR /R synthesizes a
    candidate path of root\setname under each directory visited (even when that
    file does not exist) rather than matching existing files by wildcard
    (FOR /?). On live Windows 10/11 cmd, FOR /R %%D in (.) visits depth-first:
    the walk root, then a subdirectory before that subdirectory's siblings that
    sort later in the filesystem enumeration.
  slash_d_r: >-
    FOR /D /R (directories recursively) with a wildcard set such as (*) lists
    matching subdirectory names under the walk and does not emit the walk root
    itself as a match. Prefer FOR /R %%D in (.) when the root directory must be
    included in the enumeration. Enumeration order differs from FOR /R (.): on
    live Windows 10/11 cmd, FOR /D /R %%D in (*) commonly yields sibling
    directories before descending into a sibling's children (for example A, B,
    then A\child), so scripts must not assume identical walk order across the
    two forms.
  slash_l: >-
    FOR /L iterates a numeric sequence (start,step,end), inclusive of endpoints
    that the step reaches. The end need not be hit exactly; iteration stops once
    the index passes the end in the step direction. When the start is already
    past the end for a positive step (for example for /l %%i in (5,1,3)) or
    before the end for a negative step, the DO body runs zero times (confirmed
    on live Windows 10/11 cmd). A step of 0 never advances the index, so the
    end condition is never met: on live Windows 10/11 cmd the DO body repeats
    forever. Neither GOTO nor EXIT /B from that DO body terminates the loop
    (the process must be interrupted or ended with bare EXIT); avoid step 0
    entirely.
  slash_f: >-
    FOR /F parses text from a file-set, a quoted string, or command output; see
    for_f for option details.
  classic_literal_set: >-
    In the classic FOR %%i IN (set) DO form, set members without wildcards (* or
    ?) are treated as literal strings and are iterated even when no matching
    file exists (for example FOR %%i IN (nosuch.xyz) DO ... runs once with
    %%i=nosuch.xyz). Wildcards match existing filesystem entries (FOR /?).
  wildcard_no_match_zero_iterations: >-
    When a classic FOR set member contains wildcards (* or ?) and no filesystem
    entry matches, the DO body runs zero times for that mask (it does not run
    once with the literal pattern). Prior ERRORLEVEL is left unchanged (not set
    to 5). Confirmed on live Windows 10/11 cmd; secondary docs that claim
    ERRORLEVEL 5 or a single literal iteration for unmatched masks are wrong
    on current hosts.
  empty_set_zero_iterations: >-
    An empty classic FOR set (FOR %%i IN () DO ...) iterates zero times and does
    not run the DO body. Separator-only sets such as (,,) or ( ; ) likewise
    yield zero iterations after consecutive delimiters collapse. A quoted empty
    member ("") is one iteration whose metavar text is two quote characters.
    Confirmed on live Windows 10/11 cmd; the grammar accepts empty and
    separator-only forList forms.
  set_member_delimiters: >-
    Unquoted members in a classic FOR %%i IN (set) are split on the same
    delimiters as batch arguments: space, tab, comma, semicolon, and equals
    (FOR /?; confirmed on live Windows 10/11 cmd). Example: FOR %%i IN (a,b;c=d)
    yields four iterations a, b, c, d. A quoted member stays one iteration,
    including internal = / , / ; (for example "a=b").
  percent_star_as_set: >-
    FOR %%i IN (%*) DO ... expands %* first, then re-tokenizes that text with
    classic FOR set delimiters (see set_member_delimiters). Unquoted a=b or e;f
    become separate iterations; a quoted argument such as "c d" remains one
    member (quotes typically still visible on the metavar). This is distinct
    from walking %%1.. via SHIFT. Cross-ref batch_parameters.percent_star.
  multiple_set_members_or_masks: >-
    A classic FOR set may list multiple literal members and/or masks (space-
    and/or comma-separated). Each mask is expanded independently (for example
    *.txt *.csv or Italy*.jpg,Italy*.bmp). Combine with set_member_delimiters
    when diagnosing unexpected splits on = / ; / ,.
  wildcard_question_trailing: >-
    In FOR file-set masks, a trailing ? (or ? immediately before a dot) can match
    fewer characters than the number of question marks, including matching a
    shorter basename (for example ???.txt may match a.txt as well as ab.txt).
    The same trailing-? behavior appears in other cmd file masks (DIR, COPY,
    DEL, and peers). Short 8.3 names can also satisfy masks that the long name
    alone would not (for example *.tar matching a file whose long extension is
    .targa when a short .tar alias exists); treat mask matching as
    filesystem-dependent and inspect DIR /X when hits look unexpected.
  wildcard_question_mid: >-
    A ? that is not at the end of a name component and not immediately before a
    dot matches exactly one character. Confirmed on live Windows 10/11 cmd:
    sh?t.txt matches shot.txt and shut.txt but not sht.txt or shunt.txt, while
    sh??t.txt matches shunt.txt and sh*t.txt matches all of those basenames.
    Combine with wildcard_question_trailing when diagnosing flexible trailing-?
    matches versus exact mid-mask ?.
  wildcard_asterisk: >-
    In classic FOR / DIR / COPY / DEL masks, * matches any remaining characters
    in that name component, including dots (for example filea*c.txt matches
    fileabc.txt; *.tar matches names whose final extension component is tar,
    not *.tar.gz). Combine with wildcard_question_trailing and short-name notes
    when diagnosing unexpected hits. Confirmed on live Windows 10/11 cmd.
  goto_exits_body: >-
    A GOTO from a FOR DO body exits the loop early and continues at the target
    label for classic FOR, FOR /F, and FOR /L with a non-zero step. BREAK does
    not terminate FOR iteration (see break_command.not_loop_break). Confirmed on
    live Windows 10/11 cmd for both FOR %%i IN (...) DO ... & GOTO :label and
    parenthesized DO bodies. FOR /L with step 0 is excluded: GOTO and EXIT /B
    do not escape that infinite loop (see slash_l).
  in_do_paren_spacing: >-
    Live cmd requires space or tab between IN and '(' and between DO and a
    parenthesized DO body. Glued forms are syntax errors: for %%i in(a) do
    echo x reports "in(a) was unexpected"; for %%i in (a) do(echo x) reports
    "do( was unexpected". A newline between DO and '(' is also a syntax error
    ("The syntax of the command is incorrect"). Spaced forms
    (for %%i in (a) do (echo x) / do echo x) are valid. Confirmed on live
    Windows 10/11 cmd; the grammar rejects the glued IN(/DO( forms.

for_f:
  description: "FOR /F parsing options and input forms (FOR /?)"
  options:
    - eol
    - skip
    - delims
    - tokens
    - usebackq
  option_details:
    eol: >-
      eol=c sets a single end-of-line comment character (default semicolon).
      A line is skipped when its first parsed token begins with that character;
      the same character later on the line is ordinary data (not a C-style
      mid-line comment). Only one character is accepted after eol=; additional
      characters in the same eol= value are not a multi-character comment
      prefix and commonly break option-string parsing on live cmd (for example
      eol=#x yields a message such as x" was unexpected at this time).
    skip: >-
      skip=n skips the first n physical lines of each input file (or each
      string / command-output unit), including blank lines and lines that would
      later be treated as eol= comments. Omitting skip is the legal way to
      process from the first line; it is not equivalent to writing skip=0
      (skip=0 is a syntax error — see skip_requires_integer). In a multi-file
      fileset such as IN (a.txt b.txt), skip applies independently to each file
      in listed order, not once across the whole fileset (FOR /?; confirmed on
      live Windows 10/11 cmd).
    delims: >-
      delims=xxx replaces the default delimiter set (space and tab). An empty
      delims= means no delimiters (whole line is one token); confirmed for forms
      such as FOR /F "delims=" %%a IN ("a b c"). When a space is included among
      delimiters it must be the last character of the delims= value; otherwise
      the options string can misparse. Prefer placing the delims= clause last
      among FOR /F options so a trailing space delimiter sits immediately
      before the closing quote (for example "tokens=1,2 delims=, "). Delimiter
      characters are case-sensitive (delims=D does not treat lowercase d as a
      delimiter). The grammar accepts any delims= character payload without
      validating which characters are safe delimiters; metacharacters in the
      delimiter set (for example | & < > ^) remain catalog/runtime concerns and
      often need caret-escaping in unquoted option forms (see
      unquoted_options_caret).
    tokens: >-
      tokens=x,y,m-n selects token indexes; a trailing * assigns the remainder
      of the line to one variable. Selected indexes are sorted ascending before
      metavar assignment, so tokens=5,7,1-3 and tokens=1-3,5,7 bind the same
      successive letters (confirmed: "A B C D E F G H" yields %%a=A %%b=B
      %%c=C %%d=E %%e=G for both spellings). Sparse lists skip indexes:
      tokens=1,3 with %%a assigns token 1 to %%a and token 3 to %%b (the next
      letter); there is no empty metavariable for the skipped token 2
      (confirmed: "one,two,three" with delims=, yields %%a=one and %%b=three).
      Additional FOR variables are implied by ASCII succession from the
      declared letter (not only a-z / A-Z): for example tokens=1-27 starting at
      %%a assigns the 27th token to %%{ on live Windows 10/11 cmd. FOR /? and
      some references claim a 26-token / past-z ceiling; live cmd continues
      past z/Z, though some successor characters are unusable in DO text
      (notably | as a pipe). Prefer staying within a-z / A-Z for portable
      scripts. Independently of letter succession, a single FOR /F selects at
      most 31 token indexes: tokens=1-31 iterates, while tokens=1-32 or
      tokens=32 silently produce zero iterations (no syntax error). tokens=*
      still applies leading-delimiter stripping first (default space/tab), so
      leading spaces are removed before the remainder is assigned; use empty
      delims= when leading whitespace must be preserved (confirmed: tokens=*
      on "   spaced" yields spaced, while delims= yields the spaced string
      including leading spaces).
    usebackq: >-
      usebackq switches quoting: backtick `command` for command output, single
      quotes for literal strings, and double quotes for filenames. Without
      usebackq, single quotes wrap a command and double quotes wrap a string.
      With usebackq, a single-quoted string that contains unescaped parentheses
      commonly fails to parse (for example ') was unexpected at this time');
      caret-escape them as ^(...^) inside the quotes when those characters are
      data. Prefer the non-usebackq "string" form when the text holds parentheses
      and no embedded double quotes are required.
  useback_synonym: >-
    Live cmd.exe also accepts useback as a synonym for usebackq (trailing q
    optional). Prefer the documented usebackq spelling in new scripts.
  tokens_syntax_rejects: >-
    Live cmd rejects malformed tokens= values as option-string syntax errors
    (messages such as abc" was unexpected at this time). Confirmed rejects
    include non-numeric tokens=abc, empty slots such as tokens=1,,2,
    multi-hyphen forms such as tokens=1-2-3, and any index whose integer value
    is 0 (tokens=0, tokens=00, tokens=1-0, tokens=0*). Leading zeros on a
    non-zero index are accepted (tokens=01 is index 1). Valid forms are a
    single *, a comma-separated list of positive integers, and single hyphen
    ranges m-n (optionally mixed), with an optional trailing * on the last
    item (with or without a comma before the *: tokens=1* and tokens=1,* are
    both accepted). These option-string syntax errors are non-fatal (later
    statements still run), matching skip= / eol= option rejects. The grammar
    applies the same checks to quoted and unquoted (caret-escaped) option text.
  tokens_comma_before_star: >-
    A trailing remainder star may be written as tokens=1* or tokens=1,* (and
    likewise after ranges/lists). Both forms assign the first selected token to
    the declared metavar and the unparsed remainder of the line to the next
    letter. Confirmed on live Windows 10/11 cmd.
  skip_requires_integer: >-
    skip= requires a numeric line count whose integer value is at least 1.
    Non-numeric values such as skip=xyz and zero counts such as skip=0 /
    skip=00 are live syntax errors (for example xyz tokens=1" or " was
    unexpected at this time). Leading zeros on a non-zero count are accepted
    (skip=01 skips one line). Omitting the skip keyword entirely skips nothing
    and is the correct spelling when no lines should be skipped — do not write
    skip=0. These option-string syntax errors are non-fatal: the FOR statement
    fails to iterate, but the batch continues with later statements (process
    exit 0), unlike invalid percent-tilde forms such as %~q1 that abort.
    Confirmed on live Windows 10/11 cmd.
  skip_counts_physical_lines: >-
    The skip=n budget counts physical lines before blank-line and eol= comment
    filtering. Empty lines and lines whose first parsed token begins with the
    eol character still consume skip counts. After the skip budget is exhausted,
    blank lines are ignored as usual and remaining eol-comment lines are
    skipped. Confirmed on live Windows 10/11 cmd: a file of two blank lines then
    DATA with skip=2 tokens=* iterates DATA; two semicolon comment lines then
    KEEP with default eol and skip=2 iterates KEEP.
  option_keyword_last_wins: >-
    If the same FOR /F option keyword appears more than once in the options
    string, live cmd applies the last occurrence (for example
    tokens=1 tokens=2 keeps tokens=2; skip=1 skip=2 skips two lines;
    eol=# eol=; uses semicolon). Prefer listing each keyword once.
  option_keyword_order_independent: >-
    Distinct option keywords may appear in any order; live cmd does not apply a
    fixed cross-keyword precedence such as usebackq > skip > delims > eol >
    tokens. Confirmed on live Windows 10/11 cmd: tokens=1 delims=, and
    delims=, tokens=1 bind the same first token; eol=# delims=, and
    delims=, eol=# agree on which lines are comments. Prefer a readable order
    with delims= last when a trailing space delimiter is required.
  options_from_expansion: >-
    The FOR /F options string may be produced by percent (or delayed) expansion
    (for /f "%opts%" %%a in (...) when opts holds tokens=... delims=...). Mixed
    forms such as "%tok% delims=," also work. Confirmed on live Windows 10/11
    cmd.
  whitespace_only_lines: >-
    Truly empty/blank lines in FOR /F file or command-output input are skipped.
    A whitespace-only line is also skipped with default delimiters; with empty
    delims= it is kept as a spaces-only token; with tokens=* it still iterates
    but often yields empty after leading-delimiter stripping. Confirmed on live
    Windows 10/11 cmd.
  tokens_hard_max: 31
  tokens_star_delimiter_only: >-
    When tokens=* appears alone (no numeric indexes), a non-empty input that
    consists only of delimiter characters still causes one DO iteration with an
    empty metavar (for example tokens=* delims=x on "xxx" sets %%A to empty and
    runs the body). Forms that include any numeric token index such as
    tokens=1,* or tokens=1 skip delimiter-only lines and do not iterate.
    Confirmed on live Windows 10/11 cmd.
  eol_empty: >-
    An empty eol= value (for example "eol=" alone) removes the default
    semicolon comment character on live Windows 10/11 cmd, so lines beginning
    with ; are kept as data. A space after eol= before the next keyword (as in
    "eol= delims=,") installs space as the eol character rather than leaving
    comments fully disabled. Prefer setting eol= to an unused character that
    will not appear as a line prefix when a defined comment character is still
    required; do not treat empty eol= as a portable multi-character "off"
    switch across hosts or documentation.
  unquoted_options_caret: >-
    When an options string cannot use surrounding double quotes (for example
    because delims must include a quote character), the options may be written
    unquoted with caret-escaped equals and spaces, such as
    tokens^=1-2^ delims^=^". Prefer quoted options whenever possible.
  consecutive_delims: >-
    Consecutive delimiter characters collapse to one delimiter; empty fields
    between repeated delimiters are not preserved by default.
  empty_fields_token_shift: >-
    Because consecutive delimiters collapse, a,,b with delims=, and
    tokens=1,2,3 yields token1=a, token2=b, and token3 empty (the middle empty
    field is skipped). A leading delimiter such as ,a,b likewise shifts so
    token1=a and token2=b. Multiple leading delimiters collapse the same way:
    confirmed on live Windows 10 (build 19045) cmd, for /f "tokens=1-3 delims=,"
    %%a in (",b,c") yields %%a=b %%b=c %%c=empty, and ",,,d" with tokens=1-4
    yields %%a=d with the later metavars empty. There is no built-in FOR /F mode
    that preserves empty fields between collapsed delimiters.
  empty_fields_workarounds: >-
    To honor empty fields, transform the line before FOR /F so consecutive
    delimiters become delimiter-plus-placeholder-plus-delimiter, then parse.
    Confirmed on live Windows 10/11 cmd with delayed expansion: for line a,,b,
    set "line=!line:,,=,__EMPTY__,!" then for /f "tokens=1-3 delims=," %%a in
    ("!line!") yields %%a=a, %%b=__EMPTY__, %%c=b. Replace the placeholder with
    an empty string after the loop when a true empty field is required. Leading
    delimiters still need an explicit leading placeholder (for example prepend
    a sentinel before the first character, or rewrite a leading "," into
    "__EMPTY__,") if an empty first field must be preserved.
  default_first_token: >-
    By default, /F passes the first blank-separated token from each line
    (FOR /?).
  variables_are_global: >-
    FOR replaceable parameters are single-letter, case-sensitive, and drawn from
    a shared session namespace of up to 52 active letters (FOR /?). Metavar
    expansion applies in the FOR DO body (including &-chained commands on that
    body), not in later unrelated statements or in a CALL :label body unless the
    value is passed as an ordinary argument. Nested FOR loops may reuse the same
    letter: during the inner loop the letter holds the inner value; after the
    inner FOR completes, the outer value is restored on modern Windows.
  input_forms: >-
    file-set; "string" (or 'string' with usebackq); 'command' (or `command`
    with usebackq). A bare/multi fileset IN (a.txt b.txt) opens files in listed
    order (each file is a separate input for skip= and eol=). Blank lines in
    file and command-output input are skipped (FOR /?): a physical empty line
    does not produce a loop iteration. A quoted multi-string file-set form such
    as ("a" "" "b") is not a blank-line probe; cmd treats that as a single
    string argument rather than three lines.
  fileset_member_delimiters: >-
    Unquoted FOR /F file-set members split on the same delimiters as classic
    FOR sets: space, tab, comma, semicolon, and equals. IN (a.txt,b.txt),
    IN (a.txt;b.txt), and IN (a.txt=b.txt) each open two files in order
    (confirmed on live Windows 10/11 cmd). Quoted members stay one name.
  fileset_no_wildcards: >-
    A FOR /F file-set does not expand * or ? wildcards into multiple files.
    for /f %%a in (x*.txt) reports that the file cannot be found and yields no
    iterations when no literal name x*.txt exists. Enumerate matches via a
    command-output form such as for /f %%a in ('dir /b x*.txt') do ... instead.
    Confirmed on live Windows 10/11 cmd.
  tokens_duplicate_indexes: >-
    Repeating the same tokens= index still allocates successive metavars, but
    later duplicates receive empty values rather than re-binding the token.
    Confirmed on live Windows 10/11 cmd: tokens=1,2,1 delims=, on A,B,C with
    %%a yields %%a=A, %%b=B, %%c empty; tokens=1,1 on A B yields %%a=A and
    %%b empty. Prefer unique indexes.
  does_not_set_errorlevel: >-
    FOR /F itself does not clear or set ERRORLEVEL. A missing fileset file
    prints a cannot-find message and leaves the prior ERRORLEVEL unchanged; a
    command-output child's exit code likewise does not overwrite the parent
    ERRORLEVEL merely because FOR /F iterated. Confirmed on live Windows 10/11
    cmd (prior cmd /c exit 7 remains 7 after a missing fileset and after a
    successful for /f %%a in ('echo OUT') loop).
  input_encoding: >-
    FOR /F file and command-output tokenization expects text in the active
    console/OEM code page (or compatible ANSI). UTF-16LE files with a BOM are
    typically not tokenized usefully by a bare fileset; piping through TYPE
    (for /f %%a in ('type u16.txt') do ...) often recovers readable lines on
    live Windows 10/11 cmd. Prefer ASCII/OEM inputs or an explicit conversion
    step when encoding matters.
  string_embedded_quotes: >-
    Without usebackq, a double-quoted string input may contain an even number of
    embedded " characters as paired quotes (for example
    for /f "tokens=1-3" %%a in ("one ""two"" three") do ...). Confirmed on live
    Windows 10/11 cmd: tokens become one, ""two"", three. A solitary unescaped "
    inside that form commonly breaks parsing; prefer usebackq with '...' when
    the data holds awkward quote mixes.
  command_stdout_only: >-
    The FOR /F command-output form captures only the command's stdout as token
    lines. Stderr still prints to the console (or follows redirects on the
    command) but does not become FOR tokens. Confirmed on live Windows 10/11
    cmd: for /f %%a in ('cmd /c "echo OUT&echo ERR 1>&2"') yields token OUT
    while ERR appears on stderr.
  bare_fileset_no_path_search: >-
    A bare FOR /F file-set name (for example for /f %%a in (data.txt) do ...)
    is resolved relative to the current directory (or an explicit drive/path on
    the name). Unlike command resolution, live Windows 10/11 cmd does not search
    %PATH% for that file: a data.txt that exists only under a PATH directory is
    reported as "The system cannot find the file ..." and yields no iterations.
    Use an absolute or relative path, pushd to the directory, or a command-output
    form such as for /f %%a in ('type "path\data.txt"') do ... when the file is
    not in the CWD.

caret_escape:
  description: >-
    Caret escaping is phase-driven. For ordinary multilevel escaping without
    CALL, each re-parse hop commonly needs 2^n-1 carets before a special
    character. CALL adds an extra re-parse that doubles every caret on its
    command tail (including carets inside double quotes), so nested CALL or
    percent-expanded command execution requires compensating counts per hop
    rather than relying on 2^n-1 alone across CALL boundaries.
  call_doubling: >-
    CALL doubles all carets once on its arguments before the line is parsed
    again; quoted carets are doubled even though quotes suppress escaping.
  line_continuation: >-
    A caret as the last character of a physical line continues onto the next
    line (the CRLF is escaped). CRLF is two bytes escaped by that single
    trailing caret (the unusual case where one ^ spans a two-byte sequence). A
    trailing space after ^ escapes the space instead, so the next line is not a
    continuation. Percent expansion runs on each physical line before
    continuation joins the next line, so a name cannot span the break: echo
    %NA^ / ME% does not form %NAME% (live cmd typically leaves incomplete-%
    stripping such as NAME). Keep %name% on one physical line. Confirmed on
    live Windows 10/11 cmd.
  percent_not_escaped: >-
    Caret does not escape percent. Percent expansion runs before caret-escape
    processing, so ^%name% still expands %name% (use %% in scripts for a
    literal percent). Escaping ! under delayed expansion is a separate
    phase-sensitive rule (see delayed_expansion.exclamation_escaping).
  metachar_inventory: >-
    Characters that commonly require caret escaping outside quotes include
    & | < > ^ and sometimes (). Double quotes suppress those metacharacters
    for command parsing but do not suppress percent expansion or delayed
    ! expansion (see quoting). Literal % uses %% in scripts; literal ! under
    delayed expansion commonly needs caret doubling such as ^^!. Multilevel
    re-parse uses 2^n-1 carets (or CALL doubling) rather than a single ^
    always being enough.
  writing_batch_files: >-
    When a parent ECHO-redirects into a child .cmd/.bat, one caret-escape pass
    applies while writing: ^> stores >, ^^^> stores ^>, and ^^^^^> stores ^^>
    in the child (confirmed on live Windows 10/11 cmd). Parentheses written into
    IF/FOR blocks likewise need caret escaping on the write pass (echo if 1==1
    ^( / echo ^) ) so the parent does not treat them as grouping while emitting
    the child. Pair with double_percent.writing_batch_files (%% hops) and
    delayed_expansion.writing_batch_files (! emit) for multigenerational
    generators.

quoting:
  description: >-
    Double quotes group an argument and suppress command metacharacters, but
    they do not disable percent or delayed-expansion parsing.
  suppress_metacharacters: >-
    Inside double quotes, & | < > ^ and () lose their command-separator /
    redirect / escape meaning for that quoted span (they may appear as literal
    text in the argument). Quotes themselves are stripped from %~1 bare
    quote-strip forms.
  no_suppress_percent_or_delayed: >-
    Percent expansion (%name%, %1, %~...) still runs inside double quotes.
    When delayed expansion is enabled, !name! also expands inside quotes.
    Use %% / phase-aware ! escaping when a literal percent or exclamation
    mark must survive.
  embedded_doubled_quotes: >-
    Inside a quoted argument, "" is an embedded quote pair and is not collapsed
    to a single quotation mark by %~1. Example: call :t "a""b" then %~1 expands
    to a""b (outer quotes stripped; embedded "" retained). %1 keeps the outer
    quotes as ["a""b"].
  ascii_double_quotes_only: >-
    Only ASCII double quote (code point U+0022) opens and closes cmd argument
    quoting. Typographic / curly quotes (U+201C left and U+201D right double
    quotation marks, and similar) are ordinary characters: they do not group
    arguments or suppress metacharacters. Confirmed on live Windows 10/11 cmd:
    a CALL whose first token is curly-quoted hello followed by world yields %1
    containing those curly quote characters around hello and %2=world, whereas
    ASCII-quoted "hello" world yields one quoted argument slot for hello.
    Prefer ASCII quotes in scripts; editors that insert smart quotes break
    argument parsing.

double_percent:
  for_body_rule: "FOR loop variables use %% in batch files"
  echo_literal_rule: "Literal % in ECHO often requires %% escaping"
  batch_vs_cmdline: >-
    Inside a .cmd/.bat file a literal percent is written as %% (for example
    echo Progress: 50%% prints Progress: 50%). On the interactive command line
    a single % is usually enough for a literal percent. FOR variables follow the
    same split: %%i in batch files versus %i interactively. SET /A modulo also
    uses %% in batch files (single % interactively).
  call_percent_reduction: >-
    CALL performs an extra parse of its argument tail that reduces each %% pair
    to a single % (in addition to caret doubling). Example: call echo %%%%
    prints a single %.
  writing_batch_files: >-
    When a parent script writes another .cmd/.bat via ECHO redirection, each %%
    pair in the parent becomes a single % in the child file (so echo %%~nx0>>child
    stores %~nx0 for the child to expand later). A single %name% or %~ in the
    parent expands while writing, baking the current value into the child.
    Multilevel generators need additional %% layers per hop. This is ordinary
    percent reduction when emitting text, distinct from CALL's argument-tail
    reparse (call_percent_reduction) though both halve %% pairs. Caret and
    delayed-! emit hops are documented under caret_escape.writing_batch_files
    and delayed_expansion.writing_batch_files.

string_operations:
  substring_pattern: "%var:~start,length%"
  replacement_pattern: "%var:old=new%"
  description: "Batch substring and search-replace expansion"
  requires_command_extensions: >-
    Substring (%var:~...) and replace (%var:old=new%) forms require Command
    Extensions (SET /?). With extensions disabled, both percent and delayed
    substring/replace forms expand to empty rather than performing the
    operation or leaving the operator text literal.
  negative_offsets: >-
    Negative start counts from the end (%PATH:~-10%). Negative length trims
    from the end (%PATH:~0,-2%). Combined forms like %PATH:~7,-5% are valid.
  omit_length: >-
    If the length is omitted (%PATH:~10%), the substring runs from the start
    offset through the remainder of the value (SET /?).
  missing_or_empty_substring_batveat: >-
    When a name is undefined or expands to empty (including after SET name=),
    substring forms like %var:~-1% or %NOSUCH:~0,1% expand to the literal
    ~-offset[,length] text rather than an empty string. Delayed peers such as
    !empty:~-1! behave the same when delayed expansion is enabled. SET name=
    unsets the name (IF DEFINED is false); it does not leave a defined empty
    value.
  missing_or_empty_replace_batveat: >-
    The same undefined/empty name rule applies to replace forms. When a name is
    undefined or expands to empty (including after SET name=), %var:old=new%
    and delayed !var:old=new! do not yield an empty string. Percent expansion
    removes %var: (or !var:) and continues scanning, so the remainder
    old=new% / old=new! typically becomes the literal old=new text after the
    trailing % / ! is consumed (for example %NOSUCH:a=b% and %EMPTY:a=b% after
    SET EMPTY= both expand to a=b). Star-prefix forms leave the asterisk as
    well (%EMPTY:*a=b% -> *a=b). Prefer IF DEFINED before substring/replace, or
    use delayed expansion only after confirming the name is defined. Distinct
    from empty_replacement_deletes (%var:old=% on a defined non-empty value).
  beyond_length_returns_empty: >-
    When the name is defined and non-empty, a substring that starts past the
    end of the value (for example %var:~10% on a 6-character string) expands to
    an empty string rather than the literal ~offset text. A start within the
    string with a length that runs past the end returns only the remaining
    characters (for example %var:~3,10% on abcdef yields def).
  case_insensitive_search: >-
    In %var:old=new%, the search for old is case-insensitive; the replacement
    text new is inserted literally. The same case rule applies to delayed
    !var:old=new! forms.
  replace_all_occurrences: >-
    %var:old=new% substitutes every occurrence of old in the value (SET /?),
    not only the first match.
  empty_replacement_deletes: >-
    When new is empty (%var:old=%), each matched occurrence of old is deleted
    (SET /?).
  star_prefix_replace: >-
    In %var:*old=new%, a leading asterisk on the search text replaces from the
    beginning of the value through the first match of old.
  not_on_batch_parameters: >-
    Substring and replace forms apply to environment variable names, not to
    batch parameter spellings. %1:~0,2% and %~1:~0,2% do not take a substring of
    the argument: after %1 / %~1 expand, the :~... text remains literal (for
    example with %1=hello, %1:~0,2% yields hello:~0,2). The same applies to
    replace (%1:_=-% yields foo_bar:_=- when %1=foo_bar). Assign first
    (set "s=%~1" then %s:~0,2% / %s:_=-%). Confirmed on live Windows 10/11 cmd.
    Cross-ref batch_parameters.no_substring_or_replace and
    delayed_expansion.not_batch_parameters.

set_a:
  description: "SET /A arithmetic expression operators (SET /?)"
  requires_command_extensions: >-
    SET /A requires Command Extensions (SET /?). With extensions disabled, an
    unquoted form such as set /A N=1+1 is treated as a plain assignment whose
    variable name includes the /A token (for example name "/A N" with value
    "1+1"), not as arithmetic (see command_extensions_off.set_a_and_string_ops).
    Quoted forms such as set /A "N=1+1" are a syntax error when extensions are
    off (same family as quoted SET "name=value" under OFF).
  unary_operators:
    - "!"
    - "~"
    - "-"
  binary_operators:
    - "*"
    - "/"
    - "%"
    - "+"
    - "-"
    - "<<"
    - ">>"
    - "&"
    - "^"
    - "|"
  assignment_operators:
    - "="
    - "*="
    - "/="
    - "%="
    - "+="
    - "-="
    - "&="
    - "^="
    - "|="
    - "<<="
    - ">>="
  grouping: "Parentheses () group subexpressions"
  expression_separator: >-
    Comma separates multiple expressions in one SET /A; the final expression
    value is the overall result (and is printed when SET /A runs outside a script).
  hex_literal: "0x12 style hexadecimal integers"
  octal_literal: >-
    Leading-zero octal (022). Digits 08 and 09 are invalid octal and fail SET /A.
  no_binary_literal: >-
    SET /A does not accept 0b-style binary integer literals. Only decimal,
    0x hexadecimal, and leading-zero octal forms are recognized (SET /?). A
    form such as 0b10 fails the expression (non-zero ERRORLEVEL; the target
    variable is left unset/unchanged for a failed assignment).
  modulo_in_batch: "Modulo uses %% in batch files (single % on the interactive command line)"
  quoting_rule: >-
    Logical operators and modulus that would be misparsed as command syntax
    need the expression quoted (SET /?). Operators that are also cmd shell
    metacharacters — & | ^ << >> — must be quoted or caret-escaped; otherwise
    cmd applies shell parsing before SET /A arithmetic (SET /?; confirmed on
    live Windows 10/11 cmd).
  shell_metachar_quoting: >-
    Unquoted << is a live syntax error (for example set /A x=1<<2 yields a
    message such as 1<< was unexpected at this time). Prefer set /A "x=1<<2".
    Unquoted >> is not a SET /A right-shift: cmd treats >> as append redirection
    (set /A x=8>>1 appends the command's stdout to a file named 1 and does not
    shift). Unquoted & and | split or pipe the command line; use quotes or
    caret escapes (set /A x=5^&3, set /A "x=5&3"). Unquoted ^ escapes the next
    character (set /A x=2^3 stores 23); XOR needs quotes (set /A "x=2^3") or a
    doubled caret (set /A x=5^^1). Confirmed on live Windows 10/11 cmd.
  undefined_as_zero: >-
    An environment name that is not defined is treated as numeric 0. Names may
    appear without % percent signs inside the expression.
  bare_names: "Variable names in SET /A expressions expand without requiring %name% wrappers"
  bare_name_numeric_truncation: >-
    A bare environment name inside SET /A is read with SET /A's integer scanner,
    not full percent expansion. A leading signed integer prefix is taken and any
    following non-integer junk is ignored with ERRORLEVEL 0 (for example
    amt1=1.99 and amt2=2.50 yields set /A sum=amt1+amt2 -> sum=3; v=12abc yields
    set /A r=v -> r=12). A value that does not begin with a digit (for example
    .5) is treated as 0.
  bare_vs_expanded_noninteger: >-
    Bare names and %name% / !name! are not equivalent when the stored value is
    not a pure integer. Bare names truncate silently (bare_name_numeric_truncation).
    Percent or delayed expansion substitutes the literal text first, so an
    expression such as set /A r=%amt% with amt=1.99 sees the token 1.99, fails
    with a non-zero ERRORLEVEL (often 1073750990 on live Windows 10/11 cmd), and
    may still store a truncated leading integer (see decimal_literal_partial_assign).
  octal_in_variable_value: >-
    Leading-zero octal applies to bare-name values as well as literals: v=010
    yields set /A r=v -> r=8. Invalid octal digits in a bare-name value truncate
    rather than fail: v=08 or v=09 yields r=0 with ERRORLEVEL 0. By contrast,
    literal set /A r=08 fails with Invalid number, leaves the prior value
    unchanged, and sets a non-zero ERRORLEVEL (often 1073750991).
  integer_range: "Signed 32-bit integers (-2147483648 through 2147483647)"
  spaces_around_assignment: >-
    Unlike plain SET, SET /A allows spaces around = and other operators inside
    the expression.
  interactive_display: >-
    When SET /A runs from the interactive command line outside a script, it
    prints the final expression value (SET /?). Inside a .cmd/.bat script the
    same expression is evaluated silently (no automatic print).
  expression_without_assignment: >-
    SET /A accepts a bare expression with no assignment (for example
    set /A 1+2). Assignment operators are optional; when present they require
    an environment variable name on the left (SET /?). In scripts the
    expression still runs (and can set ERRORLEVEL on failure) without printing.
  unary_bang_vs_delayed: >-
    SET /A lists unary ! (logical NOT). When delayed expansion is disabled,
    set /A N=!0 yields 1. When delayed expansion is enabled, ! is also the
    delayed-expansion delimiter, so bare ! in a SET /A expression is consumed as
    delayed syntax first: forms such as set /A N=!Z! expand the variable before
    arithmetic, and a lone !0 does not reliably apply unary NOT (live cmd often
    leaves N=0). Prefer testing unary ! with delayed expansion disabled, or
    quote/escape so SET /A still sees a literal bang.
  operator_precedence: >-
    Operators apply in decreasing precedence (SET /?): grouping (); unary
    ! ~ -; * / %; + -; << >>; &; ^; |; assignment operators; comma.
  left_associative_same_tier: >-
    Operators at the same precedence tier associate left-to-right on live cmd
    (for example 8/2*2 yields 8, and 8/2/2 yields 2). Parentheses change
    grouping as usual. Confirmed on live Windows 10/11 cmd.
  overflow_wraps: >-
    Signed 32-bit overflow wraps (for example 2147483647+1 becomes
    -2147483648) rather than failing the expression.
  divide_by_zero_errorlevel: >-
    Division by zero and other failed SET /A expressions leave a non-zero
    ERRORLEVEL (exact codes are implementation-defined / host-specific). On
    live Windows 10 (build 19045) cmd, probes observed 1073750993 for
    divide-by-zero (set /A x=1/0), 1073750991 for invalid numeric literals such
    as 08 or 0b10, and nearby codes such as 1073750990 for decimal-point /
    Missing operator forms such as 1.5. Treat these constants as host-observed
    hints, not a portable API.
  integer_division_truncates: >-
    The / operator performs signed integer division toward zero (for example
    7/2 yields 3 and -7/2 yields -3). There is no floating-point result.
  modulo_sign: >-
    The remainder operator follows toward-zero division: the sign of the
    result matches the dividend. Confirmed on live Windows 10/11 cmd:
    set /A r=-7%%3 yields -1 and set /A r=7%%-3 yields 1 (batch %% escaping).
  no_power_operator: >-
    SET /A has no exponent/power operator. ^ is bitwise XOR, not power; forms
    such as 2**3 are not valid SET /A syntax.
  no_floating_point: >-
    SET /A is signed 32-bit integer arithmetic only. There is no floating-point
    type or decimal fraction result; fractional work requires scaled integers or
    an external tool rather than native float operators (see
    integer_division_truncates and bare_name_numeric_truncation).
  scaled_integer_pattern: >-
    A common portable pattern is to keep a fixed scale in the integer domain:
    strip or avoid a decimal point with string replace, multiply/divide with
    SET /A, then reinsert a decimal for display. Example confirmed on live
    Windows 10/11 cmd: with value 1.25 stored as digits 125 at scale 100,
    set /A out=125*10/100 yields 12 (toward-zero integer math). Do not expect
    SET /A itself to accept 1.25 as a float literal (see
    decimal_literal_partial_assign).
  decimal_literal_partial_assign: >-
    A decimal-point token in the expression text (literal 1.5, or %var% / !var!
    that expands to such text) is a failed SET /A expression (Missing operator;
    non-zero ERRORLEVEL, often 1073750990). Despite the failure, live cmd may
    still write a truncated leading integer into the assignment target (for
    example set x=99 then set /A x=1.5 leaves x=1). Do not assume failure always
    preserves the prior value for decimal forms (contrast failed_leaves_prior
    for Invalid number / divide-by-zero).
  failed_leaves_prior: >-
    When a SET /A assignment fails with Invalid number or divide-by-zero (for
    example literal 08, 0b10, or 1/0), the target variable is left unchanged
    (prior value or still unset). Decimal-point / Missing operator failures can
    still partial-assign a truncated integer (see decimal_literal_partial_assign).
  comma_expression_partial_success: >-
    SET /A comma separates multiple expressions left-to-right. When an earlier
    assignment succeeds and a later expression fails, the earlier targets keep
    their new values and ERRORLEVEL reflects the failure. Confirmed on live
    Windows 10/11 cmd: set /A "x=1, y=1/0" leaves x=1 with divide-by-zero
    ERRORLEVEL (see divide_by_zero_errorlevel) while y is unchanged / unset.
  signed_shift: >-
    The << and >> operators are signed 32-bit arithmetic shifts on live
    Windows 10/11 cmd. Arithmetic right shift preserves the sign bit:
    set /A s=-8^>^>1 yields -4; set /A s=-1^>^>1 yields -1 (not a logical
    shift to a large unsigned value); left shift of -1 by 1 yields -2.
    Captured SET /? labels << >> as "logical shift", which understates the live
    signed/arithmetic behavior; prefer live probes over that help wording.
    Prefer caret-escaping > inside scripts so redirection does not consume
    the operators. Confirmed on live Windows 10/11 cmd.
  quoted_expression_trailer: >-
    After set /A "expr", further non-separator tokens on the same statement are
    folded into the arithmetic parse rather than discarded like plain quoted
    SET trailers. Examples confirmed on live Windows 10/11 cmd:
    set /A "x=1+1"zzz reports Invalid number and leaves x unset/unchanged for
    that failure mode; set /A "x=1+1" zzz may assign x=2 then report Missing
    operator. Use & to start a true second command. The grammar absorbs those
    trailer tokens into the SET /A statement (not a second top-level command).
  assignment_requires_name: >-
    Assignment operators require an environment variable name on the left
    (SET /?).
  parameter_as_lhs: >-
    With extensions, a percent-expanded argument can supply the left-hand
    variable name (for example set /A %~1=%~2+%~3 after CALL :Add out 1 2).
    The name must expand before SET /A evaluates the expression. With delayed
    expansion enabled, !%~1! resolves a parameter that holds a variable name
    so the same slot can be read and written (for example
    set /A %~1=!%~1!*!%~1! after call :sq n with n=3 yields n=9). Confirmed on
    live Windows 10/11 cmd.

set_assignment:
  description: >-
    Without /A or /P, SET takes name=value where the name is everything after
    SET up to the first = and the value is everything after that =. Spaces
    adjacent to = become part of the name and/or value. Quoted forms like
    SET "name=value" keep spaces out of the name when the quotes wrap the
    assignment.
  prefix_query: >-
    With extensions, SET name (no equals) lists every defined variable whose
    name begins with that prefix (SET /?). Example: SET P lists PATH, PATHEXT,
    and other P* names.
  missing_name_errorlevel: >-
    SET with a name/prefix that matches no variable sets ERRORLEVEL to 1 and
    prints that the environment variable is not defined (SET /?).
  unset_with_empty_value: >-
    SET name= or SET "name=" removes the variable (IF DEFINED name is false).
    A value that is only spaces (SET "name= ") remains defined.
  bat_vs_cmd_errorlevel:
    description: >-
      Script file extension changes whether certain successful internal
      commands clear ERRORLEVEL. Prefer EXIT /B or cmd /C exit N when the exit
      code must be set explicitly.
    commands_clear_in_cmd: >-
      With Command Extensions enabled, successful SET, PATH, PROMPT, ASSOC, and
      FTYPE in a .cmd script set ERRORLEVEL to 0. The same successful commands
      in a .bat script leave the prior ERRORLEVEL unchanged. Live Windows 10/11
      cmd also applies this clear-vs-preserve rule to successful SET /A and
      SET /P (redirect/file input). APPEND is not part of this live-verified
      matrix: modern hosts typically lack APPEND as an internal or PATH command
      (see commands.yaml removed_commands.append).
    failure_still_sets: >-
      Failures still set a non-zero ERRORLEVEL in both .bat and .cmd (for
      example SET with a missing prefix name sets ERRORLEVEL 1).
    probe_recipe: >-
      Reset with cmd /C exit N immediately before the command under test, then
      read %ERRORLEVEL% (extensions on) or IF ERRORLEVEL (always). Avoid
      echo|set /P probes: the pipe runs SET /P in a child and does not update
      the parent environment.
    extensions_off: >-
      Without extensions, dynamic %ERRORLEVEL% / !ERRORLEVEL! are unavailable,
      so bat-vs-cmd clearing is best observed with IF ERRORLEVEL. Plain SET
      assignment still runs; SET /A and SET /P are not arithmetic/prompt forms
      when extensions are off (see command_extensions_off).
  bare_set_lists_all: >-
    SET with no arguments lists the entire environment (SET /?). Dynamic
    names such as CD/DATE/TIME are omitted unless the user defined ordinary
    variables with those names.
  ampersand_terminator: >-
    An unquoted & ends the SET statement. Trailing spaces before & remain part
    of the value (for example set name=value   & rem keeps the trailing
    spaces). Use this to terminate a value that would otherwise include the
    rest of a chained line.
  quoted_close_discards_trailer: >-
    After a quoted assignment set "name=value", any non-separator text after the
    closing quote — glued or spaced — is discarded and is not executed as a
    second command (set "g=ok"zzz and set "g=ok" echo HI both store ok and do
    not run the trailer). Trailer absorption stops at & / && / || / | so
    set "g=ok"& echo HI still runs the chained echo. Confirmed on live
    Windows 10/11 cmd.
  quoted_close_allows_redirects: >-
    Redirects may follow a quoted SET assignment (and any discarded trailer):
    set "g=ok">file and set "g=ok"zzz>file attach the redirect to the SET
    statement. SET itself writes no stdout, so the target is often a 0-byte
    file. Confirmed on live Windows 10/11 cmd.

set_p:
  description: >-
    SET /P var=[prompt] reads a line of input into var (SET /?). The prompt
    string is optional and may be empty (SET /P var=). Requires Command
    Extensions (see command_extensions_off.set_p_requires_extensions).
  prompt_vs_stdin: >-
    The text after = is only the console prompt written to stdout for the user
    (confirmed on live Windows 10/11 cmd with 1> / 2> separation); it is never
    taken from a pipe or redirected stdin. Piped or redirected data supply the
    answer line that SET /P assigns to var, not the prompt string (and not %*).
  eof_keeps_prior: >-
    If input ends immediately (EOF) or is redirected from NUL with no data,
    the prior value of var is left unchanged.
  blank_line_keeps_prior: >-
    A blank input line (the user presses Enter with no text, or a redirected
    file whose next line is empty) leaves the prior value of var unchanged --
    the same keep-prior behavior as EOF/NUL. It does not assign an empty
    string and therefore cannot clear a variable via SET /P alone. A line that
    contains only spaces assigns those spaces (the variable remains defined).
  pipe_child_isolation: >-
    The right-hand side of a pipe runs in a child cmd.exe context, so
    echo text| set /p var= updates var only in that child; the parent
    environment is unchanged (same isolation as other pipe-side mutations).
  redirect_from_file: >-
    SET /P var=<file reads the first line of file into var (stdin redirect).
    Later lines are not consumed by that SET /P. Combined with eof_keeps_prior
    and blank_line_keeps_prior when the file is empty or the next line is blank.

environment_variable_names:
  description: >-
    SET /? forbids '=' inside a variable name. Live cmd.exe accepts a wider
    charset than [A-Za-z_][A-Za-z0-9_]* -- including '.', '-', '~', and many
    punctuation characters (for example %a~b%, %var;x%, %var@x%, %var#x%,
    %ab)%, and %var$with.odd[chars]% after a matching SET). Names that start
    with a digit or '*' are not reachable via %name% (those spellings are
    %0-%9 / %* plus trailing text); use delayed !1abc! for digit-leading names.
    Quoted SET "a b=value" can define names that contain spaces; percent
    expansion then uses matching %a b% forms. Prefer underscore-alnum names for
    portability.
  forbidden_in_name: "="
  accepted_examples:
    - "my.var"
    - "a-b"
    - "a~b"
    - "a b"
    - "var;x"
    - ";"
    - "var@x"
    - "var#x"
    - "var$with.odd[chars]"
  lone_semicolon_name: >-
    A variable whose entire name is a single semicolon is accepted on live
    Windows 10/11 cmd (set ";=value" then %;% expands to value). Prefer clearer
    names in portable scripts; semicolon also appears as an argument delimiter
    and as the default FOR /F eol comment character.
  tokenizer_note: >-
    The ANTLR lexer treats %name% as a single PERCENT_VAR for any name
    characters other than '%', '=', or newlines (matching live cmd's wide
    charset, including spaces and punctuation such as @ # $ ; [ ]). Unquoted
    SET targets assemble the same punctuation from adjacent tokens
    (setNamePart: letters/digits plus ~ @ # $ ; , ( ) * + ? . -) so forms
    such as set a~b=1 and set var@x=3 stay one setStmt. Prefer
    underscore-alnum names for portable scripts.
  case_insensitive_names: >-
    Environment variable names are case-insensitive for lookup and assignment
    (%abc% and %AbC% refer to the same variable). Values are stored with the
    casing used in the SET that defined them.
  paren_names: >-
    Names may include parentheses (for example ProgramFiles(x86)). Prefer
    quoted SET "ProgramFiles(x86)=..." forms. Percent expansion of such names
    can interact with parenthesized blocks; keep expansions simple or use
    delayed expansion carefully.
  ordinary_vs_dynamic: >-
    Ordinary process environment variables such as COMPUTERNAME, USERNAME,
    TEMP, TMP, SystemRoot, and ProgramFiles appear in SET listings and are
    present at session start. Dynamic names listed under
    dynamic_environment_variables (CD, DATE, TIME, RANDOM, ERRORLEVEL,
    CMDEXTVERSION, CMDCMDLINE, HIGHESTNUMANODENUMBER) expand only with
    Command Extensions and do not appear in SET unless shadowed by a normal
    SET assignment. IF DEFINED is true for those dynamic names even when
    unshadowed (see dynamic_environment_variables.defined_without_set_listing)
    and also for ordinary or shadowed names.
  array_hash_idioms: >-
    cmd.exe has no array or hash type. Scripts emulate them with ordinary
    environment names that embed indexes or keys, commonly using brackets:
    set "arr[1]=alpha" then %arr[1]% / !arr[1]!. With delayed expansion, an
    index in another variable can be composed as !arr[%i%]! (percent expands
    the index when the line/block is parsed) or set "arr[!i!]=value" (delayed
    index at assignment). Confirmed on live Windows 10/11 cmd. Bracket and
    other punctuation characters are part of the variable name charset (see
    description / accepted_examples); this is naming convention, not new
    syntax. Prefer delayed expansion inside FOR/IF blocks when the index
    changes each iteration.
  percent_sign_not_in_name: >-
    A literal % cannot be part of an environment variable name in practice:
    percent expansion runs while parsing the SET line, so a % inside the name
    side is consumed as an expansion delimiter rather than stored. Confirmed on
    live Windows 10/11 cmd: set "a%=try" defines name a with value try (not a
    name containing %). The lexer likewise excludes % from PERCENT_VAR name
    bodies (see tokenizer_note).
  quoted_metachar_names: >-
    Quoted SET can define names that include shell metacharacters such as &, <,
    and > (for example set "a&=1", set "a<=1", set "a>=1"). Those names appear
    in SET listings and expand via matching %a&% / %a<% / %a>% forms, but they
    are hazardous in unquoted use because & | < > re-enter command parsing.
    Prefer underscore-alnum names. Distinct from forbidden_in_name (= only).

echo_forms:
  description: >-
    ECHO prints its arguments. Blank-line forms glue punctuation directly to
    ECHO with no intervening space (ECHO. ECHO: ECHO/ and similar). A spaced
    form such as ECHO . prints the punctuation instead of a blank line.
  blank_line_examples:
    - "echo."
    - "echo:"
    - "echo/"
    - "echo\\"
    - "echo("
    - "echo+"
    - "echo["
    - "echo]"
  blank_line_tokenizer_note: >-
    Live cmd accepts the listed blank-line spellings. echo[ and echo] tokenize
    as a single WORD (brackets are allowed in WORD). echo( is still WORD echo
    plus LPAREN because '(' is a distinct token; both forms parse as ordinary
    commands.
  echo_on_off: >-
    ECHO ON and ECHO OFF toggle command echoing on stdout. A leading @ suppresses
    echoing for that single statement (@echo off). ECHO OFF / @echo off does not
    suppress stderr; redirect with 2>nul or >nul 2>&1 when stderr must be quiet.
  ghost_trace_unexecuted_blocks: >-
    With ECHO ON, parenthesized IF and FOR bodies are still written to stdout as
    the parser traces the command text even when the predicate is false or the
    body does not execute (a debugging "ghost" of the unrun block). Percent
    expansion has already run for that physical line, so %var% appears resolved
    in the echoed text, while delayed !var! commonly remains literal in the
    echo because delayed expansion happens at execution of statements that
    actually run. Prefer @echo off (or @ on individual lines) when traces must
    stay quiet. Confirmed on live Windows 10/11 cmd.
  bare_or_whitespace_status: >-
    ECHO with no arguments, or with only whitespace arguments, prints the
    current ECHO is on/off status rather than a blank line.
  at_prefix: >-
    A leading @ suppresses echo of that one statement when ECHO is ON (not only
    @echo off). It applies to arbitrary commands, not only ECHO.

cmd_processor_switches:
  description: >-
    CMD.EXE command-line switches that affect language behavior (CMD /?).
  delayed_expansion: "cmd /V:ON enables delayed expansion; /V:OFF disables it"
  extensions: "cmd /E:ON enables Command Extensions; /E:OFF disables them"
  defaults: >-
    Command Extensions are enabled by default; delayed expansion is disabled
    by default (CMD /?, SET /?).
  compatibility_aliases: >-
    For compatibility, /X is the same as /E:ON, /Y is the same as /E:OFF, and
    /R is the same as /C (CMD /?). Other unrecognized switches are ignored.
  c_k_s_quoting: >-
    /C runs string then terminates; /K runs string and remains. /S modifies
    quote handling after /C or /K. When /C or /K is used, quotes are preserved
    only if there is no /S, exactly two quotes, no special &<>()@^| between
    them, whitespace between the quotes, and the interior names an executable;
    otherwise a leading quote is stripped and the last quote on the line is
    removed (CMD /?).
  echo_off_q: "/Q turns echo off for the CMD session (CMD /?)"
  disable_autorun_d: >-
    /D disables execution of AutoRun commands from the registry on startup
    (CMD /?).
  output_ansi_a: >-
    /A causes output of internal commands to a pipe or file to be ANSI
    (CMD /?).
  output_unicode_u: >-
    /U causes output of internal commands to a pipe or file to be Unicode
    (CMD /?).
  file_completion_f: >-
    /F:ON enables file and directory name completion characters; /F:OFF
    disables them. Completion is off by default (CMD /?).
  completion_chars: >-
    With /F:ON, CMD /? documents Ctrl-F / Ctrl-D style completion (and related
    CompletionChar / PathCompletionChar registry values under Command
    Processor). Exact control characters are host/configuration dependent;
    scripts should not rely on interactive completion.
  color_t: >-
    /T:ab sets the session console colors using the same two-hex-digit order as
    COLOR: first digit background, second digit foreground (COLOR /?). CMD /?
    labels the switch /T:fg and says "foreground/background", but the digit
    order still matches COLOR (for example /T:17 is background 1, foreground 7,
    same as COLOR 17). Prefer COLOR /? for attr order; see color_command.attr_hex.
  autorun_registry: >-
    Unless /D is specified, CMD looks for AutoRun REG_SZ/REG_EXPAND_SZ values
    under HKLM and HKCU Software\Microsoft\Command Processor\AutoRun and
    executes them first when present (CMD /?). Command-line switches take
    precedence over registry EnableExtensions / DelayedExpansion /
    CompletionChar settings; SETLOCAL Enable/Disable Extensions or
    DelayedExpansion takes precedence over /E and /V for the local scope.

command_extensions_off:
  description: >-
    Behavior when Command Extensions are disabled via cmd /E:OFF, /Y, registry
    EnableExtensions=0, or SETLOCAL DisableExtensions (CMD /?, IF /?, SET /?,
    FOR /?, CALL /?, GOTO /?, SHIFT /?).
  disable_paths:
    - "cmd /E:OFF"
    - "cmd /Y"
    - "SETLOCAL DisableExtensions"
    - "registry Command Processor EnableExtensions=0"
  base_if_remains: >-
    Base IF forms remain: IF [NOT] ERRORLEVEL n, IF [NOT] string1==string2, and
    IF [NOT] EXIST filename.
  extension_if_unavailable: >-
    Extension IF forms are unavailable: compare-ops (EQU/NEQ/LSS/LEQ/GTR/GEQ),
    /I, IF DEFINED, and IF CMDEXTVERSION. Using them yields a syntax error
    (for example 'EQU was unexpected', '/I' compare forms unexpected, or
    'DEFINED' operand unexpected).
  goto_eof_not_special: >-
    GOTO :EOF is not an end-of-file target without extensions; cmd searches for
    a user label named eof and errors if none exists. A user :eof label works
    as an ordinary label target.
  call_label_and_modifiers: >-
    CALL :label internal routines and percent-tilde / %* argument expansions
    require extensions. With extensions off, %* expands to literal * and %~1
    leaves literal ~1 (leading % consumed). Base %0-%9 still expand.
  call_label_runtime: >-
    With extensions off, CALL :label does not transfer to an internal label; the
    CALL is skipped and execution continues at the next statement (no jump to
    :label). CALL without a colon still searches for an external program/script.
  set_a_and_string_ops: >-
    SET /A arithmetic and %var:~...% / %var:old=new% (and the delayed !var!
    equivalents) require extensions. With extensions off, a line such as
    set /A N=1+1 is treated as a plain assignment whose variable name includes
    the /A token (for example name "/A N" with value "1+1"), not as arithmetic.
    Quoted set /A "N=1+1" is a syntax error under OFF (quoted SET requires
    extensions). Substring/replace expansions (%var:~...%, %var:old=new%, and
    delayed equivalents) expand to empty under OFF rather than leaving the
    operator text literal.
  set_p_requires_extensions: >-
    SET /P requires extensions. With extensions off, set /P var=text is treated
    as a plain assignment whose variable name includes the /P token (for
    example name "/P var"), not as a prompt/read.
  prefix_query_requires_extensions: >-
    Prefix query (SET name with no equals) requires extensions. With extensions
    off it is a syntax error ("The syntax of the command is incorrect").
  quoted_assignment_requires_extensions: >-
    Quoted assignment SET "name=value" requires extensions. With extensions off
    it is a syntax error and the variable is not set. Unquoted set name=value
    remains available.
  for_slash_forms: >-
    FOR /D, /R, /L, and /F (and their options) require extensions; only the
    classic FOR %%i IN (set) DO form remains without them. Slash forms yield
    errors such as '/F was unexpected at this time'.
  shift_n: >-
    SHIFT /n requires extensions; bare SHIFT remains available. With extensions
    off, a form such as shift /1 does not preserve %0 the way SHIFT /1 does when
    extensions are on: live cmd performs an ordinary bare SHIFT (including
    shifting %0) rather than the /n start-at-n behavior (confirmed on live
    Windows 10/11 cmd). Prefer omitting /n when extensions may be disabled.
  dynamic_environment: >-
    Dynamic environment names (CD, DATE, TIME, RANDOM, ERRORLEVEL,
    CMDEXTVERSION, CMDCMDLINE, HIGHESTNUMANODENUMBER) are not provided without
    extensions unless the user defines ordinary variables with those names.
  directory_and_prompt_gated: >-
    CD /D (other-drive change), PUSHD UNC temp-drive mapping / POPD unmap, and
    PROMPT $+ / $M codes require extensions. Plain CD, PUSHD/POPD for ordinary
    paths, and basic PROMPT codes remain. With extensions, CD also normalizes
    case to on-disk names and does not treat spaces as delimiters; without
    extensions, paths with spaces need quotes (see directory_commands). Nested
    MKDIR intermediate-directory creation also requires extensions (see
    mkdir_command).
  assoc_ftype_color_gated: >-
    ASSOC, FTYPE, and COLOR are unavailable when extensions are disabled
    (reported as not recognized internal/external commands).
  delayed_independent: >-
    Delayed expansion can be enabled while extensions are disabled. Plain
    !var! still expands; substring/replace bang forms expand to empty under
    OFF and dynamic env names still need extensions (see
    delayed_expansion.orthogonal_to_extensions).

setlocal_options:
  flags:
    - ENABLEEXTENSIONS
    - DISABLEEXTENSIONS
    - ENABLEDELAYEDEXPANSION
    - DISABLEDELAYEDEXPANSION
  nesting_limit: >-
    Up to 32 active SETLOCAL instantiations are allowed per CALL level.
    Exceeding that limit prints "Maximum setlocal recursion level reached."
    The overflowing SETLOCAL does not change ERRORLEVEL (it remains 0 when
    previously 0) and execution continues; later statements still run.
    Each CALL :label (or CALLed script) receives its own independent allocation
    of up to 32 levels. SETLOCAL /? documents implied ENDLOCAL at script end
    but does not state the numeric limit.
  implied_endlocal: "An unmatched SETLOCAL is ended when the batch script exits"
  argument_errorlevel: >-
    With extensions, SETLOCAL sets ERRORLEVEL to 0 when given a recognized
    Enable/Disable argument (ENABLEEXTENSIONS, DISABLEEXTENSIONS,
    ENABLEDELAYEDEXPANSION, or DISABLEDELAYEDEXPANSION) and to 1 for an
    unrecognized argument. SETLOCAL /? lists all four flags but still says
    "two valid arguments"; live cmd treats all four as valid (ERRORLEVEL 0).
    Classic probe: VERIFY OTHER 2>nul & SETLOCAL ENABLEEXTENSIONS & IF
    ERRORLEVEL 1 (SETLOCAL /?).
  help_text_two_arguments: >-
    Captured SETLOCAL /? wording about "two valid arguments" is incomplete
    relative to the four Enable/Disable flags it documents and that live cmd
    accepts; prefer the flags list and live ERRORLEVEL behavior over that count.
  survive_via_percent_on_same_line: >-
    Percent expansion happens before ENDLOCAL runs on a chained line, so
    endlocal & set "out=%in%" can export in into out after the local scope
    ends.
  precedence_over_cmd_switches: >-
    SETLOCAL Enable/Disable Extensions or DelayedExpansion takes precedence
    over CMD /E and /V for the duration of that local scope (SETLOCAL /?).
  endlocal_restores_state: >-
    ENDLOCAL restores the prior environment and the prior enabled/disabled
    state of Extensions and DelayedExpansion from the matching SETLOCAL
    (ENDLOCAL /?).
  endlocal_restores_directory: >-
    ENDLOCAL also restores the current drive and directory that were in effect
    at the matching SETLOCAL. CD/CHDIR or PUSHD changes made inside the local
    scope are undone by ENDLOCAL even though ENDLOCAL /? omits this detail.
  survive_via_paren_block: >-
    The same parse-time percent capture used by endlocal & set "out=%in%" also
    works in a parenthesized block, because %in% expands when the block is
    parsed, before ENDLOCAL runs. Both the chained form (endlocal & set
    "out=%in%") and a multi-line block with ENDLOCAL on its own line followed by
    set "out=%in%" export successfully (confirmed on live Windows 10/11 cmd).
  endlocal_bang_vs_percent_asymmetry: >-
    After ENDLOCAL inside a parenthesized block (or on a chained line) with
    delayed expansion enabled, %var% still sees the pre-ENDLOCAL local value
    (parse-time capture) while !var! sees the restored outer value. Confirmed
    on live Windows 10/11 cmd: with outer survive=OUTER, setlocal, set
    survive=LOCAL, then (endlocal & echo %survive% & echo !survive!) prints
    LOCAL then OUTER. Prefer percent capture on the ENDLOCAL line when
    exporting locals; bang forms re-read the post-ENDLOCAL environment.
  bare_inherits_flags: >-
    Bare SETLOCAL with no Enable/Disable argument still opens a new local
    scope and inherits the current Extensions and DelayedExpansion enablement
    from the outer scope (for example EnableDelayedExpansion then a nested
    bare SETLOCAL still expands !var!). ENDLOCAL of the nested scope restores
    the immediately prior snapshot as usual. Confirmed on live Windows 10/11
    cmd.
  flag_order_and_duplicates: >-
    The two optional SETLOCAL flag categories (Extensions and DelayedExpansion)
    may appear in either order. If the same category appears twice in one
    SETLOCAL command, the last occurrence wins (for example
    setlocal enableextensions disableextensions leaves extensions off).
    Confirmed on live Windows 10/11 cmd.
  quoted_flag_rejected: >-
    Quoting a SETLOCAL flag (setlocal "enableextensions") is not recognized:
    cmd prints "Invalid parameter to SETLOCAL command" and sets ERRORLEVEL 1.
    When one token is valid and another is garbage in the same command
    (setlocal disableextensions foobar), the valid flag is still applied even
    though the bad token also triggers that message and ERRORLEVEL 1.
    Confirmed on live Windows 10/11 cmd.
  endlocal_call_level_scoped: >-
    ENDLOCAL only closes a SETLOCAL opened at the same CALL level. An ENDLOCAL
    with nothing to close at the current level is a silent no-op (no message;
    ERRORLEVEL unchanged). A SETLOCAL left open inside CALL :label is closed
    when that subroutine returns (EXIT /B or fallthrough). Confirmed on live
    Windows 10/11 cmd.
  endlocal_ignores_extra_arguments: >-
    Unlike SETLOCAL, ENDLOCAL performs no argument validation: trailing garbage
    (endlocal foobar) produces no error message and no ERRORLEVEL change; the
    matching scope still closes. Confirmed on live Windows 10/11 cmd.
  pushd_stack_not_restored: >-
    ENDLOCAL restores the current directory from the matching SETLOCAL but does
    not restore the PUSHD directory stack. A PUSHD performed inside the local
    scope leaves its stack entry after ENDLOCAL, so an extra POPD may be needed
    to unwind fully. Confirmed on live Windows 10/11 cmd.

errorlevel:
  if_form: >-
    IF ERRORLEVEL n is true when the current exit code is greater than or equal
    to n (not equality). Prefer IF %ERRORLEVEL% EQU n for exact tests when the
    dynamic ERRORLEVEL name is not shadowed.
  classic_number_forms: >-
    Classic IF ERRORLEVEL / IF CMDEXTVERSION accept an optional leading minus on
    a numeric literal (IF ERRORLEVEL -1 uses ordinary >= semantics) and accept a
    percent/bang/FOR expansion in the number position after the percent pass
    (IF ERRORLEVEL %n% behaves like IF ERRORLEVEL <expanded digits>). Confirmed
    on live Windows 10/11 cmd; the grammar accepts these forms as ifStmt.
  leading_zeros_decimal: >-
    Leading zeros on classic IF ERRORLEVEL / IF CMDEXTVERSION literals are
    decimal, not octal: IF ERRORLEVEL 010 means >= 10, and IF ERRORLEVEL 08
    means >= 8. That diverges from compare-ops, where 010 EQU 8 is true (octal)
    and 08 falls back to a string compare. Confirmed on live Windows 10/11 cmd
    (exit code 8: IF ERRORLEVEL 08 true, IF ERRORLEVEL 010 false, 010 EQU 8
    true).
  variable_form: "%ERRORLEVEL% / !ERRORLEVEL! hold the numeric exit code as text"
  env_var_shadowing: >-
    A user-defined environment variable named ERRORLEVEL (also CMDCMDLINE,
    CMDEXTVERSION, and other dynamic names) overrides %name% expansion. Defining
    ERRORLEVEL with SET prevents later commands from updating the dynamic
    %ERRORLEVEL% value until that variable is cleared. IF ERRORLEVEL n still
    reads the internal exit code, not the shadowed environment string. Prefer
    cmd /C exit N (or EXIT /B) to set ERRORLEVEL rather than SET ERRORLEVEL=.
  choice_ordinal: >-
    See choice_command for CHOICE ERRORLEVEL ordinals and switches. Summary:
    CHOICE sets ERRORLEVEL to the 1-based index of the selected key; omitted /C
    defaults to YN; errors return 255; CTRL+C/BREAK return 0 (CHOICE /?).
  not_errorlevel_negative: >-
    IF ERRORLEVEL n means >= n. IF NOT ERRORLEVEL n means < n. Because of the
    >= test, IF NOT ERRORLEVEL 0 is true only when ERRORLEVEL is negative, not
    when ERRORLEVEL is any non-zero value. Prefer IF %ERRORLEVEL% NEQ 0 (with
    extensions) for a non-zero test when the dynamic name is not shadowed.
  cmd_c_exit_reset: >-
    Running cmd /C exit N (or cmd /C "exit /B N") from a batch script sets the
    parent session ERRORLEVEL to N. This is the usual way to force ERRORLEVEL
    to 0 after a prior failure without SET ERRORLEVEL= (which shadows the
    dynamic name -- see env_var_shadowing). Confirmed on live Windows 10/11
    cmd.
  call_empty_sets_errorlevel: >-
    A CALL with no target -- written as bare call or (call) with no trailing
    space after the word CALL -- sets ERRORLEVEL to 1 without running a
    subroutine or external. Confirmed on live Windows 10/11 cmd. Prefer this
    (or COLOR 00) when a script must force a failure code without EXIT /B.
  call_space_clears_errorlevel: >-
    A CALL whose only "argument" is a trailing space -- written as call[space]
    or (call ) with a space before the closing parenthesis -- sets ERRORLEVEL
    to 0 without running a subroutine or external. The space after CALL is
    required; (call) and (call ) are different. Confirmed on live Windows
    10/11 cmd. Prefer this over SET ERRORLEVEL=0 (which shadows the dynamic
    name -- see env_var_shadowing). Inside a parenthesized block, %ERRORLEVEL%
    still shows the pre-block value; use !ERRORLEVEL! with delayed expansion
    when reading the cleared code in the same block.
  concatenated_digit_probe: >-
    Scripts sometimes concatenate successive ERRORLEVEL digits into one string
    (set "c=%c%%ERRORLEVEL%") and then test if %c% neq 0 / equ 0. When every
    digit is 0, the joined text such as 0000 still compares equal to 0 under
    numeric compare-ops (0000 EQU 0 is true). Digits 8 and 9 in an intermediate
    concatenation can force a string compare fallback under octal rules for
    compare-ops (see if_forms.compare_ops_notes), so treat multi-digit joins as
    a probe pattern rather than a portable ERRORLEVEL API. Confirmed on live
    Windows 10/11 cmd for the all-zero case.

cmdextversion:
  description: >-
    IF CMDEXTVERSION n is true when the Command Extensions version is >= n.
    Never true when extensions are disabled (the predicate is a syntax error
    under /E:OFF). %CMDEXTVERSION% exposes the version. The first extensions
    version is 1 and increments when significant enhancements are added (IF /?).
  host_value_windows_10_11: >-
    Live Windows 10/11 cmd.exe reports %CMDEXTVERSION%=2, so IF CMDEXTVERSION 1
    and IF CMDEXTVERSION 2 are true while IF CMDEXTVERSION 3 is false. Treat the
    numeric value as host/OS-specific; scripts that require a minimum should
    use IF CMDEXTVERSION n rather than hard-coding equality to 2.
  if_ignores_env_shadow: >-
    Classic IF CMDEXTVERSION n reads the internal extensions version, not a
    user-defined %CMDEXTVERSION% environment string. Shadowing with
    set CMDEXTVERSION=0 changes percent expansion but leaves IF CMDEXTVERSION 2
    true on hosts where the internal version is 2 (same pattern as IF ERRORLEVEL
    vs shadowed %ERRORLEVEL%). Confirmed on live Windows 10/11 cmd.

dynamic_environment_variables:
  description: >-
    When Command Extensions are enabled, these names expand dynamically and do
    not appear in the SET listing unless the user defines a normal variable with
    the same name (which overrides the dynamic value). Source: SET /?.
  names:
    CD: current directory string
    DATE: current date (same format as DATE command)
    TIME: current time (same format as TIME command)
    RANDOM: random decimal integer from 0 to 32767
    ERRORLEVEL: current ERRORLEVEL value
    CMDEXTVERSION: Command Processor Extensions version number
    CMDCMDLINE: original command line that invoked the Command Processor
    HIGHESTNUMANODENUMBER: highest NUMA node number on this machine
    "=ExitCode": >-
      Undocumented; 8-digit zero-padded hexadecimal of the most recent exit code
      from an external program (for example cmd /c exit 65 yields 00000041).
      Hidden from SET listings because the name begins with '='. EXIT /B updates
      ERRORLEVEL for the caller but does not refresh %=ExitCode% on live
      Windows 10/11 cmd (a prior external value remains until another external
      runs).
    "=ExitCodeAscii": >-
      Undocumented peer of =ExitCode; expands to the ASCII character for the
      least-significant byte when that byte is printable (for example 65 -> A).
      Non-printable codes such as 0, 1, or 10 (newline) expand to empty on live
      Windows 10/11 cmd.
  undocumented_equals_exitcode: >-
    %=ExitCode% and %=ExitCodeAscii% are not listed in SET /?. They update after
    an external program returns an exit code (confirmed: cmd /c exit 65 ->
    00000041 / A). EXIT /B sets ERRORLEVEL but does not update these expansions
    (confirmed: after cmd /c exit 11 then CALL :label with EXIT /B 22, the caller
    sees ERRORLEVEL 22 while %=ExitCode% remains 0000000B). Ordinary SET cannot
    define names containing '=', so these values cannot be shadowed via SET.
  time_leading_space: >-
    %TIME% uses the same format as the TIME command. For hours 0-9 the hour
    field is commonly space-padded (a leading space before the digit), so the
    expanded string can begin with whitespace. Prefer replacing spaces or
    zero-padding before parsing time fields.
  time_space_to_zero: >-
    A common portable pad is %TIME: =0%, which replaces every space in the
    dynamic TIME string with 0 so hours 0-9 become zero-padded without
    depending on locale hour width. When the hour is already two digits the
    replace is a no-op.
  random_modulo_bias: >-
    %RANDOM% yields an integer in 0..32767. Forms such as %RANDOM% %% N (SET /A)
    are biased unless N divides 32768 evenly, because 32768 is not a multiple of
    every N. Prefer rejection sampling or accept the bias for non-cryptographic
    uses. The generator is also time-seeded pseudo-random, not a CSPRNG.
  date_locale_format: >-
    %DATE% uses the same region-specific format as the DATE command (order of
    day/month/year, separators, and optional weekday text vary by locale). Do
    not assume a fixed layout such as MM/DD/YYYY.
  time_locale_delimiters: >-
    The TIME format (and therefore %TIME%) can use locale-specific separators.
    In some locales the separator may be a comma, which is also a command
    argument delimiter -- parse %TIME% carefully in portable scripts.
  cmdcmdline_shape: >-
    %CMDCMDLINE% expands to the original command line that started this cmd.exe
    process (SET /?). When a script is launched via cmd /C "script.cmd args",
    the expanded value typically includes the /C switch and the quoted script
    invocation text rather than only the script's own arguments. Explorer-style
    launches commonly look like cmd /c ""C:\full\path\script.cmd" " (script
    path present in %CMDCMDLINE%), while an interactive console that later runs
    a script often shows only the original comspec line without the script
    name. In-process CALL of another .bat/.cmd does not rewrite %CMDCMDLINE%;
    the called script still sees the process-original line while %0 reflects
    the called script's invocation spelling (confirmed on live Windows 10/11
    cmd).
  cd_shadow_vs_cwd: >-
    SET CD=value overrides %CD% expansion with that string but does not change
    the process current directory. Bare CD (and filesystem operations) still
    use the real CWD; clear the CD variable to restore dynamic %CD%.
  set_shadow_freezes: >-
    SET name=value for a dynamic name freezes %name% to that ordinary string
    until the variable is cleared. Confirmed on live Windows 10/11 cmd: after
    set DATE=frozen / set TIME=99:99:99.99 / set RANDOM=42, successive
    expansions stay frozen (TIME does not tick; RANDOM does not advance) even
    across TIMEOUT delays; set DATE= / set TIME= / set RANDOM= restores live
    dynamic expansion. Same pattern as ERRORLEVEL shadowing (see
    errorlevel.env_var_shadowing).
  defined_without_set_listing: >-
    IF DEFINED name is true for the dynamic names (CD, DATE, TIME, RANDOM,
    ERRORLEVEL, CMDEXTVERSION, CMDCMDLINE, HIGHESTNUMANODENUMBER) even when
    they are not shadowed and do not appear in SET listings. Clearing a shadow
    restores dynamic expansion but leaves IF DEFINED true. Ordinary missing
    names remain undefined (IF DEFINED false). Confirmed on live Windows
    10/11 cmd.
  random_seed_correlation: >-
    Near-simultaneous new cmd.exe processes often share the same time-based
    %RANDOM% seed and can emit identical or highly correlated sequences.
    Treat %RANDOM% as a weak per-process PRNG, not an independent entropy
    source across co-started children.
  extensions_required: true

keyword_boundaries:
  description: >-
    Builtin keywords must not be glued to %, !, quote marks, or ')'. Live cmd
    expands percent forms first, so IF%1 and SET%x% are not recognized as
    IF/SET. Gluing ')' (for example rem) or if)) likewise yields a non-keyword
    command name. When the glued expansion is non-empty (for example SET%x% with
    x=1 becomes SET1=...), cmd reports the result as not recognized. When the
    expansion is empty (undefined x), SET%x%=hello becomes SET=hello and yields
    "The syntax of the command is incorrect." Spaced forms (IF %1, SET %x%,
    FOR %%i) are required. Note rem( without space remains REM (see remarks).
  paren_keyword_spacing: >-
    Parenthesized FOR and ELSE bodies also reject glued keywords: live cmd
    requires space or tab between IN and '(', between DO and a parenthesized
    DO body, and between ELSE and a parenthesized ELSE body. Forms such as
    in(a), do(echo x), and else(echo F) are syntax errors ("... was unexpected").
    IF is different: '(' may glue immediately after the IF keyword
    (if(1==1) ...) as a paren-wrapped predicate that is usually silent-false
    (see if_forms.paren_wrapped_predicate). That is not a true then-body; a
    parenthesized then-body after a complete predicate still needs space or
    tab before '(' (if 1==1 (echo T) works; if 1==1(echo T) does not run the
    block — see if_block_parentheses.then_body_paren_spacing). Confirmed on
    live Windows 10/11 cmd; the grammar enforces the IN/DO/ELSE spacing rules.
  rem_open_paren_exception: >-
    Bare rem( remains the REM keyword (trailer '(' is allowed for REM), unlike
    rem) which is a non-keyword. See remarks.rem_punctuation_glue.
  reject_glue_after_keyword:
    - "%"
    - "!"
    - "\""
    - "'"
    - "`"
    - ")"

if_forms:
  description: "IF predicates (IF /?)"
  base_forms:
    - "IF [NOT] ERRORLEVEL number command"
    - "IF [NOT] string1==string2 command"
    - "IF [NOT] EXIST filename command"
  extension_forms:
    - "IF [/I] string1 compare-op string2 command"
    - "IF CMDEXTVERSION number command"
    - "IF DEFINED variable command"
  compare_ops:
    - EQU
    - NEQ
    - LSS
    - LEQ
    - GTR
    - GEQ
  compare_ops_notes: >-
    If both sides are all decimal digits, compare-ops perform a numeric
    comparison; otherwise a string comparison. Quoting a side (for example
    "000" EQU "0") forces string comparison even when the text looks numeric.
    String ordering is not raw ASCII byte order. On live Windows 10/11 cmd the
    collation ranks digits before letters and uses a letter-case chain where
    a LSS A, A LSS b, and b LSS B are all true (so a < A < b < B), while raw
    ASCII would rank uppercase before lowercase differently; quoted "10" LSS
    "9" is true as a lexicographic string compare. Mixed letter/digit unquoted
    compares are string compares: A GTR 9 is true and 9 GTR A is false. /I
    forces case-insensitive string compares and also applies to the
    string1==string2 form and to compare-ops. When both sides look numeric,
    cmd accepts leading-zero octal and 0x hex (010 EQU 8 and 0x10 EQU 16 are
    true). Invalid octal digit strings such as 08 or 09 are not numeric: they
    fall back to string compare, so 09 EQU 9 is false. Out-of-range all-digit
    operands clamp to signed 32-bit extremes for the numeric compare
    (2147483648 EQU 2147483647 and 9999999999 EQU 2147483647 are true; likewise
    -2147483649 EQU -2147483648).
  defined_notes: "DEFINED takes a variable name without % percent signs"
  defined_semantics: >-
    IF DEFINED tests whether the named environment variable exists (IF /?).
    The source text uses a bare name (no % / !), but percent or delayed
    expansion may supply that name first (if defined %nm% / if defined !nm!
    after set nm=VAR). A variable set to spaces (set "S= ") is defined; a
    cleared name (set "E=" / set E=) is undefined for ordinary names. Dynamic
    environment names (CD, DATE, TIME, RANDOM, ERRORLEVEL, CMDEXTVERSION,
    CMDCMDLINE, HIGHESTNUMANODENUMBER) count as defined even when unshadowed
    and absent from SET listings (see
    dynamic_environment_variables.defined_without_set_listing). Composition such
    as if defined %prefix%BAR works when the expanded name exists. Names that
    contain spaces (set "a b=1") expand via %a b% but cannot be tested with
    IF DEFINED: the predicate takes only the first token as the name
    (if defined a b treats a as the name and b as the THEN command), and
    quoting the spaced name (if defined "a b") does not match the variable.
    Prefer underscore-alnum names when IF DEFINED is required. Confirmed on
    live Windows 10/11 cmd.
  else_same_line: >-
    ELSE must appear on the same physical line as the end of the IF command
    (after the THEN command or the closing ')' of a parenthesized block). A
    newline-detached ELSE is not the IF elseClause: live cmd reports
    "'ELSE'/'else' is not recognized as an internal or external command" and
    continues. When the detached line is `else (` … `)`, the parenthesized
    block still runs as an independent command group, so both the IF THEN body
    and the orphan block can execute (confirmed on live Windows 10/11 cmd).
  else_if_chaining: >-
    There is no separate else if keyword. Multi-branch forms are ordinary
    same-line ELSE followed by another IF (for example
    if 1==2 (echo A) else if 1==1 (echo B) else (echo C)). Each ELSE still
    requires same-line attachment per else_same_line. Confirmed on live
    Windows 10/11 cmd.
  exist_files_and_directories: >-
    IF EXIST tests whether a file or directory path exists (trailing backslash
    forms commonly target directories). Wildcard masks in the EXIST operand
    are accepted and succeed when at least one matching filesystem entry
    exists (for example IF EXIST *.txt).
  exist_trailing_backslash: >-
    A trailing backslash on the EXIST operand is true for an existing directory
    and false for a normal file of the same path without the slash (both forms
    without trailing \\ are true when the entry exists). Confirmed on live
    Windows 10/11 cmd.
  empty_unquoted_operands: >-
    Unquoted empty IF operands cause a syntax error (for example IF == text or
    IF %EMPTY%==x when EMPTY is undefined and expands to nothing). Prefer
    quoted compares such as IF "%var%"=="value" or IF DEFINED for presence
    tests. The grammar reports these as syntax errors to match live cmd.
  exist_spelling: >-
    The file/directory test keyword is EXIST (IF /?), not EXISTS. A misspelled
    IF EXISTS ... is a live syntax error (for example 'nul was unexpected at
    this time'). The grammar rejects this form as a syntax error.
  operand_padding: >-
    Classic unquoted padding such as IF .%var%.==.value. can guard against
    empty expansion for simple values, but breaks when the expanded text
    contains spaces or IF metacharacters (the line re-tokenizes). A trailing
    space in the expanded value is a special case of that retokenization:
    after set "v=sad ", unquoted if .%v% equ .sad is true (the trailing space
    collapses into inter-token whitespace before EQU), while quoted
    if "%v%"=="sad" is false and if "%v%"=="sad " is true. Prefer quoted
    compares or IF DEFINED for robust empty/undefined and trailing-space
    handling. Confirmed on live Windows 10/11 cmd.
  trailing_spaces_significant: >-
    Trailing spaces in an expanded operand are significant and are not
    stripped before == or compare-ops. After set "v=sad ", if "%v%"=="sad" and
    if %v% EQU sad are false while if "%v%"=="sad " is true (confirmed on live
    Windows 10/11 cmd). Quote both sides when trailing whitespace must match.
  exist_special_devices: >-
    IF EXIST treats some reserved device names as present: if exist nul is
    true on live Windows 10/11 cmd, while if exist nul\ (trailing backslash) is
    false. Do not probe if exist con in unattended scripts -- opening CON as a
    path can block waiting on console I/O. That EXIST hang risk is distinct from
    redirecting to CON (for example echo text>CON / <CON), which is a normal
    console I/O redirect and does not use the EXIST path probe. Prefer IF EXIST
    for ordinary files and directories; see also redirection.special_devices.
  no_and_or_keywords: >-
    IF has no native boolean AND/OR keywords. Two common parse shapes: (1) after
    a complete predicate with no then-command yet, and / or becomes the THEN
    command (if 1==1 and echo X runs command "and", not a boolean join —
    typically "'and' is not recognized..." with ERRORLEVEL 9009); (2) after a
    completed IF statement, a following and / or line is likewise a separate
    unknown command. When that failed AND/OR token is followed by a
    parenthesized group — including if 1==1 and 2==2 ( ... ) with '(' at the
    end of the IF line, or a newline before '(' — live cmd still executes that
    orphan (block) after reporting the unrecognized token (ERRORLEVEL commonly
    9009). Same-line if 1==1 and 2==2 (echo X) keeps the paren text on the
    failed "and" command and does not run an orphan group. Compose conditions
    with nested IF, chained && / || on ERRORLEVEL, or other documented patterns
    — not IF ... and .... Confirmed on live Windows 10/11 cmd.
  joined_operand_and: >-
    Without AND keywords, multi-value equality can be composed by joining
    operands into one compare string (for example if "%a%-%b%" equ "X-Y").
    Choose a delimiter that cannot appear in either value: if both sides can
    expand to the same delimiter-only text (set "A=-" & set "B=" and
    set "X=" & set "Y=-"), if "%A%-%B%" equ "%X%-%Y%" is a false positive
    (both sides become "--"). Prefer nested IF or a delimiter absent from the
    data. Confirmed on live Windows 10/11 cmd.
  expanded_predicate: >-
    Percent (or delayed) expansion runs before IF parses its predicate, so the
    entire comparison text may come from a variable. Example confirmed on live
    Windows 10/11 cmd: set "b=a==a" then if %b% is a true string equality, and
    set "b=a==b" then if %b% is false. Forms such as set "b=true==true" then
    if %b% likewise succeed; expansion does not inject spaces around == (the
    interpreter sees if true==true, which is valid). IF NOT combines the same
    way: set "b=true==true" then if not %b% is false, and set "b=false==x"
    then if not %b% is true. The expanded text must still form a valid IF
    operand sequence after expansion (spaces and metacharacters already present
    in the value can break tokenization the same way as literal operands).
  errorlevel_variable_needs_compare: >-
    IF %ERRORLEVEL% n without == or a compare-op (EQU/NEQ/...) is a syntax
    error (for example '1 was unexpected at this time'). Use classic
    IF ERRORLEVEL n (>= semantics) or IF %ERRORLEVEL% EQU n for an exact test
    when the dynamic ERRORLEVEL name is not shadowed.
  paren_wrapped_predicate: >-
    Wrapping the IF predicate in parentheses is not C-style grouping. Live cmd
    typically absorbs glued parentheses into the compare operands (if(1==1) /
    if (1==1) / if (1 == 1) compares text such as "(1" to "1)"), so the
    comparison is usually false with no error and execution continues. Spaces
    around the compare-op inside glued wrapping parens still silent-false.
    Prefer unwrapped predicates. The grammar accepts optional outer parentheses
    without interior space so these lines parse as ifStmt rather than hard
    syntax errors. Confirmed on live Windows 10/11 cmd.
  paren_interior_space_fatal: >-
    When both wrapping parentheses are present, space or tab immediately inside
    '(' or ')' is a live syntax error (for example if ( 1==1 ), if( 1==1), and
    if(1==1 ) abort with "was unexpected at this time" / "The syntax of the
    command is incorrect."). Space between IF and '(' is fine. Single-sided
    forms such as if(1==1 without a closing ')' or if 1==1) remain silent-false.
    The grammar rejects the fatal interior-space forms via a source-text
    predicate (lexer skips WS). Confirmed on live Windows 10/11 cmd.
  chained_eq_first_only: >-
    Classic string1==string2 splits on the first == only; further == text stays
    in the right-hand operand (if 1==1==1 compares "1" to "1==1" and is false).
    Confirmed on live Windows 10/11 cmd.
  leading_plus_numeric: >-
    Compare-ops treat a leading + on an otherwise numeric operand as numeric
    (+5 EQU 5 is true), matching leading-minus acceptance for negatives.
    Confirmed on live Windows 10/11 cmd.
  slash_i_before_non_compare: >-
    IF /? documents /I for string compares, but live cmd also accepts /I before
    EXIST / DEFINED / ERRORLEVEL / CMDEXTVERSION with no behavioral change
    (if /i defined FOO matches if defined FOO). Confirmed on live Windows 10/11
    cmd.

if_block_parentheses:
  description: >-
    A parenthesized THEN/ELSE block requires '(' on the same logical line as
    the predicate (or ELSE); intervening spaces before '(' are allowed. An
    unclosed '(' block is a syntax error at runtime. ELSE must attach to the
    closing ')' without an intervening newline (IF /?). Parentheses around the
    ELSE branch are optional when the false-path is a single command on the
    same line (if 1==0 (echo T) else echo F); use ( ) when the ELSE body needs
    multiple statements.
  then_body_paren_spacing: >-
    A parenthesized THEN body after a complete predicate requires space or tab
    before '('. Live cmd runs if 1==1 (echo T) / if exist nul (echo T) but does
    not treat if 1==1(echo T) / if exist nul(echo T) as a true then-body block
    (typically silent-false or otherwise non-executing for the intended body;
    classic == forms absorb the glued paren into the operand text). Prefer an
    explicit space before '('. Confirmed on live Windows 10/11 cmd. Distinct
    from if(1==1) keyword-glued paren-wrapped predicates
    (if_forms.paren_wrapped_predicate).
  else_paren_spacing: >-
    A parenthesized ELSE body requires space or tab between ELSE and '('. Live
    cmd rejects else(echo F) with "else(echo was unexpected at this time" while
    else (echo F) is valid. Unlike IF, ELSE does not accept a keyword-glued
    else( form as a silent-false predicate — glued ELSE( is a hard syntax
    error. Confirmed on live Windows 10/11 cmd; the grammar rejects glued
    ELSE(.

command_chaining:
  description: >-
    Statement separators and conditionals compose commandLine forms in the
    grammar and in cmd.exe.
  operators:
    "&": "Unconditional command separator; run the next statement regardless of prior success"
    "&&": "Run the next statement only if the prior statement succeeded for chaining purposes"
    "||": "Run the next statement only if the prior statement failed for chaining purposes"
    "|": "Pipe stdout of the left statement into stdin of the right (not a conditional)"
  grouping: >-
    Parentheses group a statement list so trailing && / || observe the group's
    chaining success and resulting ERRORLEVEL. Prefer explicit groups for
    portable scripts.
  and_or_precedence: >-
    On live cmd.exe, && binds tighter than ||, so A || B && C behaves as
    A || (B && C), and A && B || C behaves as (A && B) || C. Equal-precedence
    left-to-right is not the observed model; parenthesize when intent is
    ambiguous. After a successful || alternative, later || alternatives are
    skipped (including a trailing && group that belongs to a later alternative,
    for example cmd /c exit 1 || echo B || echo C && echo D prints only B).
    Do not assume a successful early || alternative still runs a later && that
    was grouped into a skipped alternative; parenthesize when the && must always
    observe the whole || chain.
  pipe_binds_tighter_than_amp: >-
    The pipe operator | binds tighter than & / && / ||. Live cmd parses
    echo a & echo b | findstr b as a & (b|findstr), and
    cmd /c exit 1 && echo L| echo R>file as exit1 && (L|R) (so the redirect
    never runs when the left && fails). Parenthesize when a pipe must span a
    whole chain. Confirmed on live Windows 10/11 cmd.
  pipe_child_process: >-
    Each side of a pipe runs in a child cmd.exe context. Environment mutations
    (SET, SET /P, SETLOCAL) on a pipe side do not update the parent environment.
  pipe_concurrent_start: >-
    Both pipe sides are started as child cmd contexts for the pipeline; do not
    assume the left side fully completes before the right side begins.
  pipe_delayed_expansion_default: >-
    Pipe-side child cmd.exe instances start with the processor defaults for
    delayed expansion and extensions (delayed expansion off unless registry or
    an explicit /V:ON on that child enables it; extensions on by default).
    Parent SETLOCAL Enable/Disable DelayedExpansion or Extensions does not
    automatically apply inside the pipe child. With parent delayed expansion
    off (the usual default), !var! in pipeline statement text remains literal
    unless the child enables delayed expansion (for example cmd /v:on /c "...").
    With parent delayed expansion enabled, the parent still expands !var! in
    the pipeline statement text when that line runs, so the child may never
    see the bang forms. A child script invoked via the pipe can still use
    extension IF/FOR/SET forms even when the parent used SETLOCAL
    DisableExtensions.
  pipe_extensions_default: >-
    Same isolation as pipe_delayed_expansion_default for Command Extensions:
    the pipe child does not inherit the parent's SETLOCAL DisableExtensions /
    EnableExtensions state. A separate script CALLed from the pipe right-hand
    side runs under the child's default extensions (on unless that child was
    started with /E:OFF or equivalent).
  pipe_parent_errorlevel: >-
    After a pipeline finishes, the parent ERRORLEVEL is the exit code of the
    rightmost pipe stage. The left stage's exit code is discarded when that
    child cmd exits (for example findstr NOSUCH ^| ver leaves ERRORLEVEL 0,
    while echo hi ^| findstr NOSUCH leaves a non-zero ERRORLEVEL). Capture the
    left code inside that stage (temp file / CALL echo %%^^ERRORLEVEL%%) when
    both sides matter. Confirmed on live Windows 10/11 cmd.
  and_or_chain_trap: >-
    In A && (B) || (C), statement C runs when A fails or when B leaves a
    non-zero ERRORLEVEL. A successful A followed by a failing B still executes
    C -- this is not a boolean if/else. Group carefully or test ERRORLEVEL
    explicitly when only one of B/C should run.
  no_space_adjacency: >-
    Spaces around & / && / || / | are optional. Compact forms such as
    ver>nul&&echo ok||echo fail parse and run the same chaining rules as the
    spaced spellings (confirmed on live Windows 10/11 cmd). Prefer spaces for
    readability; do not assume whitespace is required between a redirect target
    and a following && / ||.
  trailing_ampersand_in_block: >-
    Inside a parenthesized block, a line that ends with a bare & (no following
    command on that physical line) is a syntax error. Terminate with & rem, or
    escape a literal ampersand as ^&, rather than leaving a dangling separator.
  success_is_errorlevel_zero: >-
    && and || follow command success/failure for chaining; they are NOT the
    same as IF %ERRORLEVEL% EQU 0. Many builtins (notably ECHO and REM, and in
    .bat files successful SET / PATH / PROMPT) can succeed for && / || without
    clearing a prior non-zero ERRORLEVEL, so a later IF %ERRORLEVEL% test can
    still see the stale code. Confirmed anti-example on live Windows 10/11 cmd:
    cmd /c exit 5 & echo x && echo AND still runs AND while ERRORLEVEL remains
    5. CALL of another .bat/.cmd likewise does not clear ERRORLEVEL to 0 on
    success (see call_goto.call_script_errorlevel and
    call_script_or_stale_errorlevel). Tools that return non-zero on partial
    success (notably ROBOCOPY bitmasks; see external_tool_notes) can make &&
    skip follow-on commands even when the operation was useful. Prefer explicit
    IF ERRORLEVEL / IF %ERRORLEVEL% tests when wrapping such tools.
  call_script_or_stale_errorlevel: >-
    Because successful CALL of a .bat/.cmd does not set ERRORLEVEL to 0, a form
    such as call other.cmd || handler can false-fire when ERRORLEVEL was already
    non-zero before the CALL. Reset with cmd /C exit 0 (or an equivalent clear)
    before relying on || / && around CALLed scripts.

batch_parameters:
  description: "Batch argument references (CALL /?, SHIFT /?)"
  percent_star: >-
    With Command Extensions, %* expands to all arguments starting at %1
    (%1 %2 ...) and never includes %0. With extensions disabled, %* is not
    expanded (literal * after the leading % is consumed). Base %1-%9 and %0
    still expand without extensions.
  percent_star_and_shift: >-
    SHIFT moves %1/%2/... but does not change the text expanded by %* (still
    the original full argument list).
  shift_n: >-
    With extensions, SHIFT /n starts shifting at argument n where n is 0..8
    (SHIFT /?). SHIFT /9 is invalid. SHIFT /1 leaves %0 unchanged and shifts
    %1<-%2<-%3... (useful when the script path in %0 must survive); bare SHIFT
    and SHIFT /0 both move starting at %0. Confirmed on live Windows 10/11 cmd.
  shift_invalid_parameter: >-
    Invalid SHIFT /n forms (/9, /99, /-1, /abc, and similar) print
    "Invalid parameter to SHIFT command", set ERRORLEVEL 1, and continue the
    script (non-fatal). Confirmed on live Windows 10/11 cmd.
  shift_default: >-
    Bare SHIFT (no /n) shifts starting at %0: the former %1 becomes the new %0,
    former %2 becomes %1, and so on. Inside CALL :label, that means bare SHIFT
    overwrites the label identity in %0 with the former %1 (while %* text is
    still unchanged). Prefer SHIFT /1 when %0 must remain the script path or
    :label identity. Confirmed on live Windows 10/11 cmd.
  shift_vacates_high_slots: >-
    After SHIFT, the highest previously occupied %n slot becomes empty when there
    is no further argument to shift into it (for example with args a b, after one
    SHIFT %1 becomes b and %2 expands empty).
  percent_zero: >-
    %0 is the script path or, inside CALL :label, the :label identity -- not a
    user-supplied argument. With extensions, path modifiers such as %~dp0
    apply; without extensions %~ forms are not expanded. The text of %0 mirrors
    the spelling/casing/quoting used to invoke the script or CALL :label (for
    example CALL :MiXeD yields %0=':MiXeD'). Explorer/file-association launches
    commonly invoke cmd /c ""C:\full\path\script.cmd" " so %0 is a quoted full
    path; typing a relative name from an existing prompt typically yields that
    relative spelling without added quotes (confirmed on live Windows 10/11
    cmd). Prefer %~f0 / %~dp0 when a canonical path is required. Redirecting
    into %0 (for example echo text>%0) expands the target to the running script
    path and can truncate/overwrite that file while it still executes -- avoid
    writing to %0.
  multi_digit_percent: >-
    Only %0 through %9 are parameter slots. %10 is %1 followed by literal 0
    (for example with %1=one, %10 expands to one0). The same single-digit
    termination applies to percent-tilde forms (%~10 is %~1 plus literal 0;
    see percent_tilde_notes.multi_digit_parameter).
  argument_delimiters: >-
    Unquoted argument tokens are split on space, tab, comma, semicolon, and
    equals. Quotes preserve those characters inside a single argument. Example
    confirmed on live Windows 10/11 cmd: call :label a=b c,d e;f yields six
    slots (%1=a %2=b %3=c %4=d %5=e %6=f) while %* retains the original
    delimiter characters (a=b c,d e;f).
  empty_quoted_argument: >-
    An explicitly empty quoted argument ("") still occupies a parameter slot.
    For example call :label "" hop leaves %1 expanded as two quote characters
    ("") and %2=hop. Percent-tilde stripping clears the quotes: %~1 is empty.
    Prefer %~1 or "%~1" when testing for empty content; raw %1=="" compares
    against the two-character quote form.
  shell_launch_arguments: >-
    How arguments arrive depends on the launcher, not only on batch parsing.
    Drag-and-drop or shell "Open with" of one or more files onto a .bat/.cmd
    typically supplies each path as its own quoted argument (%1, %2, ...).
    Explorer association launches also commonly quote %0 as a full path (see
    percent_zero). After delivery, ordinary delimiter and %~ rules apply.
    Parse corpus models the delivered shape with CALL :label "C:\path one.ext"
    "D:\path two.ext" (quoted multi-arg slots); the Explorer/drag-drop host
    itself is outside parse conformance.
  command_line_limit: >-
    The maximum length of a command line that cmd.exe accepts is 8191
    characters (Microsoft documentation for cmd.exe). Longer input is rejected
    or truncated by the console host before normal parsing completes.
  no_substring_or_replace: >-
    Batch parameter forms (%0-%9, %*, %~...) do not accept substring or replace
    suffixes. %1:~0,2% / %~1:~0,2% / %1:old=new% leave the :~ / :old=new text as
    literals after the parameter expands. Assign to an environment variable
    first (set "s=%~1") then apply string_operations. Confirmed on live
    Windows 10/11 cmd. Cross-ref string_operations.not_on_batch_parameters and
    delayed_expansion.not_batch_parameters.

call_goto:
  description: "CALL :label and GOTO :EOF (CALL /?, GOTO /?)"
  call_label: >-
    CALL :label arguments creates a new batch context at the label. Control
    returns to the statement after CALL when the called context reaches physical
    EOF, or when it executes GOTO :EOF / EXIT /B. A later mainline EOF then ends
    the script; fenced routines that return via GOTO :EOF / EXIT /B never need
    a "second EOF" to exit the CALL.
  call_label_fresh_parameters: >-
    CALL :label with no explicit arguments does not inherit the caller's %1..%9
    or %*; those slots are empty in the called context until arguments are
    passed on the CALL line. Confirmed on live Windows 10/11 cmd.
  call_context_runs_to_eof: >-
    After CALL :label, execution continues from the statement following the
    label through subsequent lines and label fallthrough until the called
    context hits physical EOF, GOTO :EOF, or EXIT /B. Labels and commands after
    the routine are still executed in the CALL context unless fenced. Fence
    routines with GOTO :EOF or EXIT /B before later labels when return should
    happen immediately.
  call_requires_colon_for_label: >-
    CALL :label requires the colon for an internal label. CALL name without a
    colon searches PATH/PATHEXT for an external program or script instead of
    jumping to :name (confirmed: with :foo present, call foo reports not
    recognized / misses the label). Prefer call :foo for routines.
  glued_colon_target: >-
    GOTO and CALL accept a glued colon with no space after the keyword
    (goto:eof / call:label). The lexer rejects WORD matches that begin with
    goto: or call: so those forms tokenize as KEYWORD + COLON + target (same
    as the spaced forms). Confirmed on live Windows 10/11 cmd for goto:eof.
  call_missing_label: >-
    CALL :missinglabel sets ERRORLEVEL to 1 and continues with the next
    statement (it does not abort the script).
  call_eof_not_special: >-
    Unlike GOTO :EOF, CALL :EOF is not an end-of-file / return shortcut. Cmd
    searches for a user label named EOF; when none exists it reports that the
    batch label cannot be found, sets ERRORLEVEL 1, and continues (same as any
    missing CALL :label). Prefer EXIT /B or GOTO :EOF to return or end a
    routine. Confirmed on live Windows 10/11 cmd.
  call_preserves_prior_errorlevel: >-
    A successful CALL :label that returns without EXIT /B (falling through to
    EOF of the routine) does not clear ERRORLEVEL to 0; the prior exit code
    remains. EXIT /B n from the called context sets ERRORLEVEL to n on return.
    Prefer an explicit EXIT /B 0 at the end of routines when a clean success
    code is required.
  call_vs_goto_exit_b: >-
    EXIT /B n after CALL :label returns to the caller with ERRORLEVEL n (the
    statement after CALL still runs). The same EXIT /B n reached via GOTO :label
    ends the current script context without returning to a CALL site (there is
    none). Prefer CALL when an abort routine must return; prefer GOTO when it
    must terminate the script.
  call_command_clears_errorlevel: >-
    CALL of a non-label, non-batch-script target that succeeds clears ERRORLEVEL
    to 0 when the called command does not itself set a non-zero code. Examples
    confirmed on live Windows 10/11 cmd: call echo ok, call rem remark, call ver,
    and call set "name=value". This differs from CALL :label and from CALL of
    another .bat/.cmd (see call_preserves_prior_errorlevel and
    call_script_errorlevel). Bare CALL with no target uses the empty /
    space rules under errorlevel.call_empty_sets_errorlevel and
    errorlevel.call_space_clears_errorlevel.
  call_script_returns: >-
    CALL other.cmd (or other.bat) runs the script and returns to the caller.
    Invoking other.cmd as a bare command transfers control permanently and does
    not return to the caller when the child ends. By contrast, a bare external
    program (.exe and other non-batch PATHEXT targets) runs and returns to the
    next line without CALL.
  call_inherits_cwd: >-
    CALL does not change the process current directory: the callee inherits the
    caller's CWD. cmd.exe itself also does not auto-cd to the script directory;
    CWD at script start is whatever the launcher set (Explorer associations
    commonly set CWD to the script's folder before starting cmd; cmd /c from
    another directory leaves that other directory as CWD). Confirmed on live
    Windows 10/11 cmd for CALL and cmd /c inheritance.
  call_script_errorlevel: >-
    A CALLed .bat/.cmd inherits the caller's ERRORLEVEL and returns whatever
    ERRORLEVEL the child leaves when it ends. Commands that do not clear
    ERRORLEVEL on success (notably ECHO and REM) leave the inherited value in
    place, so a child that only echoes can return the pre-CALL code. Commands
    that do clear or set ERRORLEVEL (for example VER, successful SET in a .cmd,
    or EXIT /B n) determine the value seen by the caller. A missing script or
    other failed external CALL sets ERRORLEVEL 1. This is distinct from CALL of
    a non-script command such as call echo ok, which clears ERRORLEVEL to 0
    (call_command_clears_errorlevel).
  call_stack_limit: >-
    Deep recursive CALL :label (or nested CALL of scripts) is limited by the
    interpreter's call stack. When usage approaches the allocation (commonly
    reported near 90 percent), cmd aborts with a message such as "BATCH
    RECURSION exceeds STACK limits" and "BATCH PROCESSING IS ABORTED",
    including a Recursion Count. Exact depth is host- and stack-dependent
    (live Windows 10/11 probes often abort in the low hundreds of nested CALL
    levels). This limit is separate from SETLOCAL's 32-level nesting cap
    (see setlocal_options.nesting_limit).
  goto_eof: >-
    GOTO :EOF transfers control to the end of the current batch script file
    without requiring a user-defined label. A user label named :eof does not
    replace this extension target.
  goto_eof_vs_label: >-
    With the colon (GOTO :EOF), Command Extensions treat EOF as the end-of-file
    target and ignore a user label :EOF. Without the colon (GOTO EOF), cmd
    performs an ordinary label search and jumps to :EOF if present.
  goto_label_matching: >-
    Ordinary GOTO targets are matched case-insensitively. A leading colon on
    the GOTO operand is optional for user labels (goto foo and goto :foo both
    match :Foo). A missing label prints an error and does not continue later
    lines in the current batch context. The prior ERRORLEVEL is preserved
    (not forced to 1), but goto missing || echo OR still runs the || side.
    Inside CALL :label or a CALLed script, a missing GOTO ends that CALLed
    context and returns to the caller with ERRORLEVEL 1 (the caller continues).
    goto lab does not match a distinct longer label such as :label (that
    folklore is false on live Windows 10/11 cmd); see label_call_vs_goto_spaces
    for the real prefix rule on spaced label lines.
  goto_empty_target: >-
    Bare GOTO with no target prints "No batch label specified to GOTO command."
    and ends the current batch context (top-level scripts stop; inside CALL
    :label the routine returns to the caller with ERRORLEVEL 1). This differs
    from a missing named label message ("The system cannot find the batch label
    specified - name"). Confirmed on live Windows 10/11 cmd.
  label_first_match: >-
    When the same label text appears more than once, GOTO and CALL :label
    resolve to the first matching label in file order; later duplicates are
    ignored (confirmed: goto mid hits the first :mid and never the second).
    Prefer unique labels.
  label_line_form: >-
    A label is a line beginning with a colon (GOTO /?). Indented labels are
    accepted by cmd; prefer a colon in column 0 for portable scripts.
  label_charset: >-
    User label names may include letters, digits, dots, spaces, and many
    punctuation characters after the leading colon (for example :ok.label and
    :has space). A label line consumes the rest of the physical line after the
    leading colon (GOTO /?). A second colon immediately after the first (::) is
    the label-style remark form, not a normal jump target. Additional colons
    after the second character are allowed on real jump labels (for example
    :ok:extra matches goto :ok:extra). Prefer simple alphanumeric labels for
    portable scripts; avoid ')' inside labels used within parenthesized blocks
    (see remarks.double_colon). The ANTLR LABEL token matches ':' plus the
    remainder of the line (excluding the newline).
  label_call_vs_goto_spaces: >-
    CALL :label arguments treats the first token after the colon as the label
    name and subsequent tokens as routine arguments (CALL /?). GOTO label uses
    the remainder of the statement as the target text, so goto :has space can
    target a line ":has space". Label lookup is prefix-oriented: goto :has also
    matches a line beginning with ":has " (live cmd).
  label_fallthrough: >-
    A label line is not a control-flow barrier. Execution falls through into
    following statements unless a GOTO/EXIT (or similar) jumps away. After
    CALL :label returns, a later encounter of the same :label as a line label
    runs that body again unless fenced with GOTO :EOF or EXIT /B.
  expanded_label_target: >-
    Percent (and delayed) expansion runs before GOTO/CALL execute, so a target
    may come from a variable: goto %name% jumps to :value when name expands to
    value (with or without a leading colon in the expanded text). CALL :%name%
    likewise resolves the label after expansion. A missing expanded label
    follows the same missing-label rules as a literal target (GOTO aborts;
    CALL :missing continues with ERRORLEVEL 1).

exit_semantics:
  description: "EXIT [/B] [exitCode] (EXIT /?)"
  bare_exit: >-
    Bare EXIT (without /B) terminates the cmd.exe process (closes the console
    session when it is the top-level interpreter). An optional exitCode after
    bare EXIT (EXIT n, still without /B) sets the process exit code and still
    terminates cmd.exe (EXIT /?). Inside CALL :label or a CALLed script, bare
    EXIT still kills the whole interpreter -- lines after the CALL never run.
    Prefer EXIT /B inside batch scripts when only the script/routine should
    end; use EXIT /B n to set ERRORLEVEL on return.
  exit_b: >-
    EXIT /B exits the current batch script context (returns from a CALL :label
    routine, or ends the script) without necessarily closing the parent cmd.exe
    window. Optional exitCode sets ERRORLEVEL when using /B.
  exit_b_preserves_without_code: >-
    EXIT /B with no exitCode leaves the prior ERRORLEVEL unchanged when
    returning from CALL :label (or when ending a CALLed script context that
    returns to a parent batch). Use EXIT /B n when a specific code must be
    returned. At top level under cmd /C, bare EXIT /B may still yield process
    exit code 0 even when ERRORLEVEL was non-zero; fall off EOF or use
    EXIT /B n to propagate a non-zero process exit code.
  exit_b_non_numeric: >-
    EXIT /B parses an optional leading signed decimal integer from exitCode and
    ignores any trailing non-digit junk (EXIT /B 12x returns 12; EXIT /B +3
    returns 3; EXIT /B 0abc returns 0). Unlike SET /A and IF compare-ops, EXIT
    does not accept 0x hex or 0-prefixed octal forms as numeric bases: a token
    such as 0x10 is read as leading decimal 0 with trailing junk x10, so it
    returns 0. When exitCode has no leading integer digits (for example EXIT /B
    abc or EXIT /B x12), live cmd treats the form like EXIT /B with no code: it
    returns from the CALL/script context and preserves the prior ERRORLEVEL
    rather than forcing 1 (confirmed on live Windows 10/11 cmd; matches
    independent EXIT parsing write-ups). Do not assume every non-numeric token
    sets ERRORLEVEL 1.

remarks:
  rem: >-
    REM remarks out the remainder of the physical line when used as the
    command verb -- at line start or after statement separators (&, &&, ||).
    Trailing `& command`, pipes, and redirection on that same REM line do not
    execute (for example echo before&rem note & echo after prints only
    "before"). Glued forms such as REMCASE are not the REM command (longest
    token match treats them as ordinary names). Mid-token letters "rem" inside
    other commands remain ordinary text. Prefer a separate command line for
    real redirects and chained commands after a remark.
  rem_keyword_boundary: >-
    REM is recognized only as a complete command token. Longer spellings such
    as REMCASE or remark are not REM; live cmd may treat them as external
    program names ("not recognized") while later &-chained commands still run.
  rem_punctuation_glue: >-
    Like ECHO blank-line spellings (echo. / echo:), several punctuation-glued
    REM forms still invoke the REM builtin on live Windows 10/11 cmd and remark
    out the remainder of the physical line: rem. rem/ rem: rem[ rem] rem+ rem\
    rem= rem, rem; and rem( (confirmed: rem. note hides note; rem. & echo still
    runs the trailing & command because the delimiter leaves an empty remark
    before &). The grammar tokenizes many of those glued spellings as a single
    WORD (same longest-match path as echo.), so parse fixtures may report
    genericCmd even though runtime is REM. By contrast, rem) rem{ rem} rem@
    rem# rem~ rem! rem? and rem* are not REM: live cmd reports them as
    unrecognized command names while a trailing & command on the same line may
    still run. Prefer spaced REM note over delimiter/glue hacks.
  double_colon: >-
    A line starting with :: is a label whose second character is :, commonly
    used as a remark. Real jump targets must not place : in the second
    character position (that form is the label-style remark). Additional colons
    later in the label text are allowed (for example :ok:extra is a valid jump
    target). Inside parenthesized blocks, prefer REM: a :: line that contains
    ')' has historically been able to close the block early because ')' remains
    significant on label lines on some hosts/versions. On modern Windows 10
    (build 19045) live probes, a :: remark containing ')' inside ( ) did not
    early-close the block (following statements in the group still ran), but
    REM remains the portable choice across hosts/versions.
  rem_vs_label: >-
    Prefer REM for portable remarks. :: is a label form and can break or
    misparse inside parenthesized IF/FOR blocks.
  echo_visibility: >-
    With ECHO ON, a REM remark is echoed to stdout like other commands. A ::
    label-style remark is typically not echoed as a command line. Neither form
    prints the remark text as output by itself when ECHO is OFF.
  percent_expansion_still_runs: >-
    Percent expansion still runs on REM lines. With ECHO ON, rem value is %FOO%
    echoes the expanded value. Delayed !FOO! on a REM line typically remains
    literal even when delayed expansion is enabled (percent phase still
    applies; bang expansion does not rewrite the remark the same way).
  rem_no_redirection: >-
    Because REM remarks out the remainder of the physical line, redirection
    operators and chained commands on that same REM line do not execute (for
    example rem note >file.txt does not create file.txt). Prefer a separate
    command line for real redirects.
  rem_slash_help: >-
    REM /? is an exception: like other builtins, the /? help switch prints REM
    usage (and may be redirected) rather than treating /? as remark text.
    Confirmed on live Windows 10/11 cmd (rem /? >file.txt captures the help
    text). Ordinary rem comment >file.txt still does not create the file.

redirection:
  description: >-
    Cmd.exe I/O redirection attaches to a statement (or parenthesized group).
    Handle numbers default to 1 (stdout) for > / >> and 0 (stdin) for <.
  operators:
    ">": "Overwrite redirect of stdout (or n>) to a file"
    ">>": "Append redirect of stdout (or n>>) to a file"
    "<": "Redirect stdin (or n<) from a file"
    ">&": "Duplicate an output handle onto another handle (e.g. 2>&1, >&2)"
    "<&": "Duplicate an input handle onto another handle"
  examples:
    - "echo ok >out.txt"
    - "echo more >>out.txt"
    - "sort <in.txt"
    - "command 2>err.txt"
    - "command >out.txt 2>&1"
    - "command 1>nul 2>&1"
    - "command >&2"
    - ">out.txt echo hi"
  nul_suppress: >-
    Redirecting to NUL discards that stream (commonly 1>nul, 2>nul, or
    >nul 2>&1).
  group_redirect: >-
    A parenthesized group may take a trailing redirect that applies to the
    whole group.
  leading_redirect: >-
    A redirect may appear before the command name (for example
    >out.txt echo hi); cmd applies it to that statement.
  digit_glued_handle: >-
    A handle digit before > / >> / < must be its own whitespace-separated token.
    echo 2>nul runs bare ECHO (prints on/off status) with stderr redirected to
    NUL; echo hello 1>f.txt writes hello (trailing space) via handle 1. A digit
    glued to preceding non-whitespace text stays part of that argument:
    echo hello1>f.txt writes hello1 (the 1 is data, not a handle). The same
    rule applies after percent expansion: with set "msg=Meet at 2",
    echo %msg%>file.txt becomes echo Meet at 2>file.txt so handle 2 receives
    the redirect and stdout shows Meet at (leading redirect >file.txt echo %msg%
    avoids the trap). Prefer an explicit space-separated handle, a leading
    redirect, or a space before the operator when a trailing digit is data
    (echo 2 >nul). Confirmed on live Windows 10/11 cmd.
  handle_order: >-
    Redirects apply left to right. command >file 2>&1 sends both stdout and
    stderr to file. command 2>&1 >file first duplicates stderr to the current
    stdout (often the console), then redirects stdout alone to file, so stderr
    may remain on the console.
  ampersand_in_handle_dup: >-
    In 2>&1 / 1>&2 / <&0 the ampersand is redirect handle-duplication syntax,
    not the & command separator. The digit after & is the source handle being
    duplicated onto the left-hand handle. Do not insert spaces that would split
    the operator (prefer 2>&1). This is distinct from statement chaining with a
    lone & between commands (see command_chaining and
    per_statement_amp_redirect). Confirmed on live Windows 10/11 cmd.
  create_before_execute: >-
    An output redirect opens/creates (or truncates with >) the target before
    the command runs. A failing or missing command can still leave a zero-byte
    file (confirmed: nosuchcmd >r.txt creates r.txt of size 0). Prefer IF
    EXIST / error checks when an empty redirect artifact would be misleading.
  per_statement_amp_redirect: >-
    On an &-chained line, each statement carries its own redirects.
    echo A>a.txt & echo B>b.txt writes both files; echo ONLY>c.txt & echo ALSO
    redirects only the first statement (the second still hits the console).
    Confirmed on live Windows 10/11 cmd.
  call_redirect_captures_context: >-
    Redirecting a CALL (call :label >file.txt) captures stdout from the entire
    CALLed context, including nested CALL :inner output, until that context
    returns. Statements after the CALL in the caller are not captured by that
    redirect. Confirmed on live Windows 10/11 cmd.
  pipe_with_redirect: >-
    When a pipe and a redirect share a command line, ownership matters. On
    type file.txt | findstr pat >out.txt the redirect belongs to the right-hand
    stage and captures findstr output. On type file.txt >out.txt | findstr pat
    the left-hand redirect consumes the type output into out.txt, so the pipe
    receives an empty stream and the right-hand capture stays empty (confirmed
    on live Windows 10/11 cmd). Prefer redirecting the stage whose output you
    intend to keep.
  bare_redirect_rejected: >-
    A statement that is only a redirect (no command name) is a live syntax
    error ("The syntax of the command is incorrect."), including a lone
    >file.txt and the bash-like &>file spelling (parsed as & then >file with no
    command). Leading redirects remain valid when a command follows
    (>file.txt echo hi / echo a & >file.txt echo b). The grammar rejects
    redirect-only genericCmd statements to match live cmd. Confirmed on live
    Windows 10/11 cmd.
  bash_style_redirects_rejected: >-
    Bash/POSIX spellings such as &>file and >&file (as a single bash operator)
    are not cmd.exe redirects. &>file is AMP plus a bare >file and fails as in
    bare_redirect_rejected. Use >file 2>&1 (or 1>file 2>&1) to merge streams.
  special_devices: >-
    NUL and CON are reliable redirect targets/sources on modern Windows (for
    example >nul, >CON, <CON). CON as a redirect target/source is not the same
    as IF EXIST con, which can block on console I/O (see
    if_forms.exist_special_devices). Other reserved device names such as PRN,
    AUX, COM1, and LPT1 may fail as redirect targets with "The system cannot
    find the file specified" depending on the host (live Windows 10 cmd often
    leaves ERRORLEVEL 0 after that failure message); treat them as OS device
    names, not ordinary files.
  con_for_interactive_prompts: >-
    When stdout is redirected to a file, interactive prompts (SET /P, CHOICE,
    PAUSE, COPY/XCOPY overwrite prompts) may hang or write prompts into the
    redirect target. Leading redirects such as >CON echo ... or >CON choice
    can keep prompts on the console while the rest of the script still redirects
    elsewhere. Confirmed pattern on live Windows 10/11 cmd; pair with
    cls_command.redirected_stdout_noop.

paren_block_expansion:
  description: >-
    Parentheses group statements into a block. Percent (%) expansion for names
    inside the block is performed when the block is parsed, not when each line
    executes. Delayed expansion (!name!) is performed at execution time when
    enabled. Therefore SET name=value followed by echo %name% inside the same
    block typically still shows the pre-block value, while echo !name! shows
    the updated value after SETLOCAL EnableDelayedExpansion.
  percent_at_parse: >-
    %var% inside ( ) expands with the value known when the block is read.
  percent_parameters_frozen: >-
    Batch parameter forms %0-%9 / %* / %~ inside a parenthesized block are also
    expanded when the block is parsed. SHIFT (or CALL argument changes) inside
    that same block does not change those percent expansions on later lines of
    the block; the updated slots are visible only after the closing ')'.
    Confirmed on live Windows 10/11 cmd: with CALL :t one two, a block that
    runs shift then echo %1 still prints one inside the block and two after it.
    Assign to an env var and use delayed expansion when in-block argument
    walking is required.
  delayed_at_execution: >-
    !var! inside ( ) expands when that line runs, seeing SET updates from
    earlier lines in the same block.
  nested_blocks_two_values: >-
    Nested parenthesized blocks still expose only two values for a given name:
    the value captured when the outermost block was parsed (%var%), and the
    current value at execution (!var!). Inner blocks do not create an additional
    percent-expansion snapshot layer.
  dual_value_swap: >-
    Because %var% is captured when the block is parsed and !var! updates at
    execution, a naked parenthesized block can observe both the pre-block and
    in-block values (for example swapping two variables with percent expansion
    inside one block).
  naked_code_block: >-
    A standalone parenthesized group that is not the THEN/ELSE/DO body of IF or
    FOR is a valid command group (a "naked" code block). It runs immediately,
    shares the current environment/scope (assignments persist like any other
    block), and is the usual vehicle for dual-value percent swaps and for
    ENDLOCAL export via parse-time %var% capture (see dual_value_swap and
    setlocal_options.survive_via_paren_block /
    endlocal_bang_vs_percent_asymmetry). Confirmed on live Windows 10/11 cmd:
    (echo hi) prints hi; (set a=%b% & set b=%a%) swaps using pre-block percent
    snapshots.
expansion_phases: >-
  Approximate cmd parsing phases for a physical line: (1) percent (%var%, %n,
  %*, %~) expansion across the whole physical line (including all & / && / ||
  segments) before any chained command runs; (2) special-character / caret
  processing and tokenization (including line-continuation caret that joins the
  next physical line only after this line's percent pass -- %name% cannot span
  a caret-continued break; see caret_escape.line_continuation); (3) command
  recognition and execution of each chain segment; (4) when delayed expansion
  is enabled, !var! expansion at execution time (including inside already-parsed
  parenthesized blocks). CALL re-parses its argument tail (notably doubling
  carets and reducing %% pairs): each CALL halves %% sequences on the tail, so
  call echo %%NAME%% expands NAME after one CALL reparse while a bare echo
  %%NAME%% in a script prints %NAME%. Nested CALL continues reducing. Pipe
  sides run in child cmd.exe contexts with their own defaults. See
  percent_expansion.compound_line_expansion, percent_expansion,
  delayed_expansion, caret_escape, double_percent, paren_block_expansion,
  command_chaining, and echo_forms.ghost_trace_unexecuted_blocks for details.

script_encoding:
  description: >-
    Batch scripts are interpreted as a sequence of bytes that cmd.exe maps to
    command text. Prefer ASCII or the active console code page without a BOM.
  bom_prefixes_first_token: >-
    A UTF-8 BOM (EF BB BF) at the start of a .cmd/.bat file is consumed as part
    of the first token. A leading @echo off then becomes a non-command such as
    '<BOM>@echo', so echo remains on and the line fails as an unrecognized
    command. A UTF-16 BOM (FF FE / FE FF) typically garbles the entire first
    line worse than UTF-8 and breaks recognition even more severely. Save
    scripts without a BOM, or place a blank line before the first command if a
    BOM cannot be avoided.
  crlf_vs_lf: >-
    CRLF and LF line endings both work on modern Windows cmd for ordinary
    scripts; prefer CRLF for maximum tool compatibility. The parse corpus may
    include an LF-only smoke fixture; UTF-16-encoded input.cmd files are not
    stored in the corpus because validators require UTF-8 decode (UTF-16 BOM
    behavior remains catalog-only under bom_prefixes_first_token).

command_resolution:
  description: >-
    How cmd.exe finds an external command name that is not an internal command
    (PATH /?, PATHEXT, and live cmd behavior).
  search_order: >-
    For a name without a directory path, cmd searches the current directory,
    then each directory listed in %PATH%. In each directory it tries the
    extensions listed in %PATHEXT% in order (default commonly includes
    .COM;.EXE;.BAT;.CMD and may include scripting extensions). An explicit
    extension on the name restricts the search to that extension.
  cwd_shadows_externals: >-
    True internal commands (for example ECHO, DIR, SET, IF, FOR, CALL, GOTO,
    REM) are never overridden by a same-named file in the current directory.
    External utilities resolved via PATHEXT -- including System32 tools such as
    label.exe and where.exe -- can be shadowed by a same-named .bat/.cmd/.exe
    in the CWD when that extension is tried before the PATH hit. Confirmed on
    live Windows 10/11 cmd: with label.bat or where.bat in the CWD, bare label
    / where runs the local script instead of System32. Prefer explicit
    paths (.\tool.bat, %SystemRoot%\System32\where.exe) when shadowing must be
    avoided.
  not_found_errorlevel: >-
    When no matching program or script is found, cmd prints that the name is
    not recognized and sets ERRORLEVEL to 9009.
  call_missing_script: >-
    CALL of a missing label sets ERRORLEVEL to 1 and continues (see
    call_goto.call_missing_label). CALL of a missing external script/program
    also sets ERRORLEVEL to 1 (not 9009). A bare missing name without CALL sets
    ERRORLEVEL to 9009 (see not_found_errorlevel).

directory_commands:
  description: >-
    CD/CHDIR and PUSHD/POPD directory language (CD /?, PUSHD /?, POPD /?).
  cd_slash_d: >-
    CD /D (or CHDIR /D) changes the current drive as well as the directory.
    Without /D, CD D:\path sets that drive's current directory but does not
    switch the process to drive D: (CD /?). /D requires Command Extensions
    (see command_extensions_off.directory_and_prompt_gated).
  bare_drive_letter: >-
    A bare drive letter command such as D: (or Z: after SUBST) switches the
    process to that drive while restoring that drive's saved current directory
    (often the drive root if it has not been visited). Confirmed on live
    Windows 10/11 cmd with SUBST Z: mapping: Z: changes %CD% to Z:\ and a later
    C: returns to the prior C: path. This is distinct from CD without /D, which
    updates another drive's directory without switching the process drive.
  cd_drive_query: >-
    CD drive: with no path displays the current directory on that drive.
    CD with no arguments displays the current drive and directory.
  cd_case_normalization: >-
    With Command Extensions enabled, CD/CHDIR converts the current-directory
    string to the same case as the on-disk names (for example CD C:\TEMP may
    become C:\Temp) (CD /?).
  cd_spaces_not_delimiters: >-
    With Command Extensions enabled, CD/CHDIR does not treat spaces as
    delimiters, so an unquoted path with spaces is accepted (for example
    cd \path\start menu). Without extensions, such paths require quotes
    (CD /?).
  cd_missing_errorlevel: >-
    CD/CHDIR to a nonexistent path leaves ERRORLEVEL 1 (confirmed on live
    Windows 10/11 cmd). Prefer IF EXIST before CD when absence must be handled
    without relying on ERRORLEVEL alone.
  pushd_popd_stack: >-
    PUSHD path stores the current directory then changes to path. POPD returns
    to the pushed directory. With extensions, PUSHD accepts UNC paths and maps
    a temporary drive letter from Z: downward for the network resource; POPD
    can unmap that temporary drive (PUSHD /?, POPD /?).
  pushd_bare_lists_stack: >-
    Bare PUSHD with no path argument lists the current PUSHD directory stack
    (one path per line) without changing directory. Confirmed on live Windows
    10/11 cmd (PUSHD /?).
  pushd_local_no_drive_map: >-
    PUSHD of a local path changes directory and pushes the prior CWD onto the
    stack but does not create a SUBST-style virtual drive mapping. Only UNC
    paths trigger the temporary Z:-downward drive letter mapping when
    extensions are enabled. Confirmed on live Windows 10/11 cmd.
  popd_no_arguments: >-
    POPD takes no path arguments (POPD /?). Extra tokens after POPD are ignored
    on live Windows 10/11 cmd; POPD still pops one stack entry. Prefer bare
    POPD for portable scripts.
  pushd_unc_temp_drive: >-
    With extensions, PUSHD of a UNC path maps a temporary drive letter starting
    from Z: downward; POPD can remove that mapping (PUSHD /?, POPD /?). An
    unbalanced PUSHD of a UNC path without a matching POPD can leave that
    temporary drive letter mapped after the script exits until POPD, SUBST /D,
    or logoff/reboot clears it.

mkdir_command:
  description: >-
    MKDIR/MD directory creation (MD /?). Intermediate-directory creation is an
    extensions feature.
  intermediate_directories: >-
    With Command Extensions enabled, MKDIR/MD creates any missing intermediate
    directories in the path (for example mkdir \a\b\c\d creates a, b, c, and d
    as needed) (MD /?). Without extensions, each level must already exist or be
    created separately; a multi-level path fails if parents are missing.
  error_on_existing: >-
    Creating a directory that already exists typically sets a non-zero ERRORLEVEL
    (often 1) on live Windows cmd; scripts that use MD in loops should test
    ERRORLEVEL or IF EXIST before creating.

rmdir_command:
  description: >-
    RMDIR/RD directory removal (RD /?). Tree deletion uses /S; quiet mode uses
    /Q. Unlike MKDIR intermediate creation, /S tree removal remains available
    when Command Extensions are disabled.
  slash_s_tree: >-
    RD /S (or RMDIR /S) removes the specified directory and all files and
    subdirectories under it (RD /?). /Q suppresses the confirmation prompt for
    /S tree removal.
  source: "RD /? (audit/cmd-help/rd-help.txt)"
  empty_required_without_s: >-
    Without /S, RD/RMDIR fails when the directory is not empty. /S removes the
    tree; /Q suppresses the /S confirmation prompt (RD /?).

color_command:
  description: >-
    COLOR sets the console foreground/background attributes (COLOR /?). COLOR
    requires Command Extensions (see command_extensions_off.assoc_ftype_color_gated).
  attr_hex: >-
    COLOR [attr] takes two hex digits: background then foreground (0-9, A-F).
    A single hex digit is also accepted and sets the foreground while leaving
    the current background unchanged (for example COLOR 2 / COLOR A). With no
    argument, COLOR restores the colors from cmd.exe startup (/T, console, or
    DefaultColor registry) (COLOR /?).
  same_color_errorlevel: >-
    COLOR /? documents ERRORLEVEL 1 when foreground and background are the
    same (for example COLOR 00). Microsoft Learn and SS64 describe successful
    COLOR as ERRORLEVEL 0, but live Windows 10/11 cmd.exe leaves ERRORLEVEL 1
    after successful different-color changes (for example COLOR 17), after same-
    color attempts, and after bare COLOR (restore), in both .bat and .cmd
    scripts. COLOR ... && therefore does not run the right-hand side on those
    hosts. Prefer live-host behavior over the success=0 documentation when
    writing portable scripts. Note: some Microsoft Learn pages invert the
    attr digit order in prose; COLOR /? (background then foreground) is
    authoritative and matches attr_hex.
  source: >-
    COLOR /? (audit/cmd-help/color-help.txt); live cmd.exe; contrast
    Microsoft Learn color command and SS64 COLOR
  no_arg_restore: >-
    COLOR with no argument restores the colors active when CMD started
    (/T, console defaults, or DefaultColor registry) (COLOR /?).

del_erase_command:
  description: >-
    DEL/ERASE file deletion (DEL /?; audit/cmd-help/del-help.txt). Attribute
    filters and recursion switches are documented in DEL /?; display semantics
    of /S change with extensions.
  switches: >-
    DEL [/P] [/F] [/S] [/Q] [/A[[:]attributes]] names (aliases ERASE). /P prompts
    per file; /F forces read-only; /S recurses subdirectories; /Q quiet on global
    wildcard; /A filters by attributes R/S/H/A/I/L/O with optional - not-prefix
    (DEL /?).
  slash_s_display_with_extensions: >-
    With Command Extensions enabled, DEL/ERASE /S shows only the files that are
    deleted, not the ones it could not find (DEL /?).
  directory_operand: >-
    If a directory is specified as a name, all files within that directory are
    deleted (not the directory itself) (DEL /?).
  missing_file_errorlevel: >-
    Deleting a nonexistent file commonly writes a "Could Not Find" message to
    stderr yet leaves ERRORLEVEL 0 on live Windows 10/11 cmd (the file is
    already absent). Do not treat a zero ERRORLEVEL after DEL as proof the
    path existed; prefer IF EXIST before deleting when presence matters.
  hidden_skipped_by_default: >-
    Without /A, DEL/ERASE does not delete hidden (or system) matches for a
    wildcard. Confirmed on live Windows 10/11 cmd: with both visible.txt and
    hidden (+H) file1.txt present, del *.txt removes visible.txt and leaves the
    hidden file; del /a:h *.txt (or /a:-h with other filters as needed) is
    required to target hidden files. ERRORLEVEL commonly remains 0 in both
    cases. Prefer /A attribute filters or attrib -H before deleting when hidden
    files must be included.
  source: "DEL /? (audit/cmd-help/del-help.txt); live cmd.exe"

assoc_ftype_command:
  description: >-
    ASSOC and FTYPE manage file-extension associations and open-command strings
    (ASSOC /?, FTYPE /?). Both require Command Extensions (see
    command_extensions_off.assoc_ftype_color_gated).
  assoc_forms: >-
    ASSOC [.ext[=[fileType]]] displays or sets the file type for an extension;
    ASSOC .ext= deletes the association (ASSOC /?).
  ftype_forms: >-
    FTYPE [fileType[=[openCommandString]]] displays or sets the open command
    for a file type; empty open-command deletes it. Open strings may use %0/%1,
    %*, and %~n parameter forms (FTYPE /?).
  extensions_required: >-
    ASSOC and FTYPE are unavailable when Command Extensions are disabled
    (see command_extensions_off.assoc_ftype_color_gated).

path_command:
  description: >-
    The PATH command displays or sets the executable search path (PATH /?).
  display_or_set: >-
    PATH with no arguments displays the current path. PATH value sets the path
    for the session. PATH ; clears the path to empty (PATH /?).
  append_via_percent: >-
    Appending commonly uses PATH %PATH%;C:\more. Clearing with PATH ; removes
    all search directories until PATH is set again.
  session_only: >-
    PATH changes apply to the current cmd.exe session (and child processes that
    inherit the environment). Persistent PATH changes require SETX or other
    system/user environment editors (see setx_command).

start_command:
  description: >-
    START launches a separate process/window (START /?; audit/cmd-help/start-help.txt).
    Grammar treats START as a generic command; these notes capture language-relevant
    switches.
  quoted_title: >-
    The first quoted argument is the window title (START "title" command ...).
    Always include an explicit title when the command path is quoted so START
    does not treat the command string as the title. Example: start
    "C:\Program Files\app.exe" opens a window titled with that path (and may
    start a bare cmd) rather than launching the exe; use
    start "" "C:\Program Files\app.exe" instead. Confirmed on live Windows
    10/11 cmd.
  wait_and_b: >-
    /WAIT waits for the started process to terminate. /B starts without a new
    window. With /B, the started application has default ^C handling ignored;
    unless the application itself enables ^C processing, ^Break is the only way
    to interrupt it (START /?; audit/cmd-help/start-help.txt). Confirmed against
    captured START /? on Windows 10/11.
  async_without_wait: >-
    Without /WAIT, START returns as soon as the child is launched and the parent
    continues immediately while the child runs concurrently. Shared CWD, files,
    and environment mutations can race. Confirmed on live Windows 10/11 cmd
    (parent prints continue before a delayed child side-effect appears).
  errorlevel: >-
    With /WAIT, START sets ERRORLEVEL to the started process's exit code
    (confirmed on live Windows 10/11 cmd: start "" /wait cmd /c exit 7 leaves
    ERRORLEVEL 7). Without /WAIT, a successful START returns promptly while the
    child continues asynchronously and leaves the prior ERRORLEVEL unchanged
    (it does not clear to 0). Do not use bare START ... && to mean "child
    succeeded". Confirmed on live Windows 10/11 cmd.
  launch_failure_errorlevel: >-
    When START cannot launch the target (for example a missing executable
    name), live Windows 10/11 cmd prints a cannot-find / create-process style
    message and sets ERRORLEVEL to 9059. Treat 9059 as a host-observed launch-
    failure code for START, distinct from the bare missing-command 9009 used
    when cmd itself fails to resolve an external name.
  window_and_priority: >-
    /MIN and /MAX control the initial window state. Priority class switches
    include /LOW /NORMAL /HIGH /REALTIME /ABOVENORMAL /BELOWNORMAL. /SEPARATE
    and /SHARED apply only to 16-bit programs and are unsupported on 64-bit
    platforms (START /?).
  node_and_affinity: >-
    /NODE <n> prefers a NUMA node; /AFFINITY <hex> restricts processors. When
    combined, affinity is interpreted relative to the node's processor mask
    (START /?).
  working_directory: >-
    /D path sets the starting directory for the new process (START /?).
  batch_and_internal: >-
    When command is a batch script or internal cmd command, START runs the
    command processor with the /K switch (START /?; audit/cmd-help/start-help.txt).
    That keeps the new console open after the batch/internal finishes, so
    start "" /wait script.cmd can wait indefinitely on a lingering cmd.exe
    window. Prefer an explicit cmd /c "script.cmd ..." (or /c with a carefully
    quoted argument list) when the child must exit, and prefer CALL when the
    callee should run in the current interpreter and return. Confirmed on live
    Windows 10 (build 19045): start "" /wait of a .cmd that only writes a file
    and exits still left /WAIT blocked on the /K window.
  vs_call_return: >-
    START does not return to the caller the way CALL script.cmd does: the
    started process runs separately (optionally waited with /WAIT). A bare
    script invoke without CALL also does not return (see
    call_goto.call_script_returns). Use CALL for subroutine/script return;
    use START when a new window/process is intended.
  env_and_associations: >-
    /I starts with the original environment passed to cmd.exe rather than the
    current environment. With extensions, starting a non-executable file uses
    file associations (ASSOC/FTYPE).
  setlocal_state_not_inherited: >-
    START-launched batch scripts and cmd.exe children inherit ordinary
    environment variables from the parent (unless /I), but they do not inherit
    the parent's SETLOCAL Enable/Disable DelayedExpansion or Extensions state.
    A child begins with the usual defaults (extensions on, delayed expansion
    off unless cmd /V, registry, or the child itself enables them). Confirmed on
    live Windows 10/11 cmd: after setlocal EnableDelayedExpansion and set
    x=PARENTVAL, a started child.cmd prints literal !x! until it enables delayed
    expansion, while %x% still expands to PARENTVAL. Percent and bang forms on
    the START command line itself are still expanded by the parent before launch
    when those phases apply.
  source: "START /? (audit/cmd-help/start-help.txt)"

prompt_codes:
  description: >-
    PROMPT text may include $-codes that expand when the prompt is displayed
    (PROMPT /?). Base codes include $A & $B | $C ( $D date $E ESC $F ) $G >
    $H backspace $L < $N drive $P drive+path $Q = $S space $T time $V version
    $_ CR+LF $$ literal $. With Command Extensions, $+ shows PUSHD stack depth
    and $M shows the remote name for a network drive (or empty).
  prompt_env: >-
    %PROMPT% expands to the current prompt template string when the PROMPT
    environment variable is defined. After a bare PROMPT reset, the PROMPT
    environment variable is cleared, so %PROMPT% expands to empty until a new
    PROMPT command sets it again. Appending via prompt %PROMPT%$S after a bare
    reset therefore yields only $S, not $P$G$S.
  source: "PROMPT /? (audit/cmd-help/prompt-help.txt)"
  reset_default: >-
    PROMPT with no arguments restores the default displayed prompt ($P$G) and
    clears the PROMPT environment variable (PROMPT /?).

break_command:
  description: >-
    BREAK is a DOS-compatibility internal. Under Windows it has no effect on
    CTRL+C checking and does not terminate FOR/IF blocks (BREAK /?). With
    Command Extensions on a debugger-attached process, BREAK may enter a
    hardcoded breakpoint; otherwise treat it as a no-op for script control flow.
  not_loop_break: >-
    BREAK does not exit FOR or IF blocks and is not a structured-loop break
    keyword; use GOTO :EOF, EXIT /B, or restructure control flow.
  source: "BREAK /?"

choice_command:
  description: >-
    CHOICE prompts for a single key and sets ERRORLEVEL to the 1-based index
    (CHOICE /?; audit/cmd-help/choice-help.txt).
  switches: >-
    CHOICE [/C choices] [/N] [/CS] [/T timeout /D choice] [/M text]. /C lists
    keys (default YN); both /C ABC and /C:ABC forms are accepted on live cmd.
    Without /N the prompt appends a trailing choice list of the form
    [choices]? (after /M text when present, or alone when /M is omitted).
    /N hides that entire trailing list including the auto-appended ? (the /M
    message still displays; choices remain enabled). /CS makes choices
    case-sensitive; /T with /D selects a default after timeout seconds
    (0-9999; 0 means immediate default); /M sets message text. Keys outside
    the /C list sound a warning beep and do not complete the prompt until a
    listed key (or cancel/timeout) is used (CHOICE /?; confirmed on live
    Windows 10/11 cmd).
  errorlevel_ordinal: >-
    First choice -> ERRORLEVEL 1, second -> 2, and so on. Tool errors return
    255. CTRL+C or CTRL+BREAK returns 0. Classic IF ERRORLEVEL n is true when
    ERRORLEVEL is greater than or equal to n, so after CHOICE a descending
    cascade is required: if errorlevel 3 ... else if errorlevel 2 ... else if
    errorlevel 1 .... A lone if errorlevel 1 after choice C of ABC is also true
    for keys B and C (ERRORLEVEL 2 and 3). Prefer decreasing-order tests or
    IF %ERRORLEVEL% EQU n for an exact match (CHOICE /?; confirmed on live
    Windows 10/11 cmd with exit-code stand-ins).
  source: "CHOICE /? (audit/cmd-help/choice-help.txt)"

date_command:
  description: >-
    DATE displays or sets the system date (DATE /?; audit/cmd-help/date-help.txt).
  forms: >-
    DATE without parameters displays the current date and prompts for a new
    one (ENTER keeps the current date). DATE date sets the date when permitted.
  slash_t: >-
    With Command Extensions, DATE /T prints the current date without prompting
    (DATE /?). The printed format matches %DATE% and is locale-specific
    (see dynamic_environment_variables.date_locale_format).
  source: "DATE /? (audit/cmd-help/date-help.txt)"

time_command:
  description: >-
    TIME displays or sets the system time (TIME /?; audit/cmd-help/time-help.txt).
  forms: >-
    TIME without parameters displays the current time and prompts for a new
    one (ENTER keeps the current time). TIME time sets the time when permitted.
  slash_t: >-
    With Command Extensions, TIME /T prints the current time without prompting
    (TIME /?). Format matches %TIME% including common leading-space hour padding
    (see dynamic_environment_variables.time_leading_space).
  source: "TIME /? (audit/cmd-help/time-help.txt)"

verify_command:
  description: >-
    VERIFY toggles write-after-write verification for disk writes
    (VERIFY /?; audit/cmd-help/verify-help.txt).
  forms: >-
    VERIFY [ON | OFF] enables or disables verification. VERIFY without a
    parameter displays the current setting. Classic SETLOCAL probes often use
    VERIFY OTHER 2>nul to force a non-zero ERRORLEVEL before testing SETLOCAL
    (see setlocal_options.argument_errorlevel).
  source: "VERIFY /? (audit/cmd-help/verify-help.txt)"

setx_command:
  description: >-
    SETX writes a persistent user or system environment variable
    (SETX /?; audit/cmd-help/setx-help.txt). Unlike SET, changes apply to future
    processes, not the current cmd.exe session.
  space_delimited: >-
    Basic form is SETX var value [/M]. Arguments are space-delimited; there is
    no '=' assignment token as with SET. Quote values that contain spaces.
  machine_flag: >-
    /M writes to the system (machine) environment instead of the user
    environment (elevation may be required).
  not_current_session: >-
    SETX does not update the current process environment. Scripts that need
    the new value immediately must also SET the variable in-session or start a
    new cmd.exe after SETX.
  source: "SETX /? (audit/cmd-help/setx-help.txt)"

subst_command:
  description: >-
    SUBST maps a path to a virtual drive letter
    (SUBST /?; audit/cmd-help/subst-help.txt).
  forms: >-
    SUBST drive1: path associates path with drive1:. SUBST drive1: /D deletes
    the virtual drive. SUBST with no parameters lists current substitutions.
  persistence: >-
    SUBST mappings are process-global for the Windows session: they persist
    after the creating cmd.exe exits and remain visible to later cmd.exe
    processes until SUBST drive: /D, logoff, or reboot. Confirmed on live
    Windows 10/11 cmd; Microsoft Learn documents the forms but not this
    session-persistence detail explicitly.
  failure_errorlevel: >-
    Mapping a drive letter that is already SUBSTed prints "Drive already
    SUBSTed" and leaves ERRORLEVEL 1. Mapping a nonexistent path prints
    "Path not found - ..." and leaves ERRORLEVEL 1. Confirmed on live
    Windows 10 (build 19045) cmd.
  nested_mappings: >-
    A SUBST target may itself be a SUBST drive (for example subst Y: Z:\subdir
    after subst Z: C:\Windows). If the parent mapping is deleted first, the
    nested letter becomes unusable until remapped (directory access fails).
    Confirmed on live Windows 10/11 cmd.
  restricted_commands: >-
    Microsoft Learn lists commands that must not be used on SUBST drives
    (including chkdsk, diskcomp, diskcopy, format, label, recover). Prefer
    operating on the underlying path for those tools.
  source: "SUBST /? (audit/cmd-help/subst-help.txt); Microsoft Learn subst"

copy_command:
  description: >-
    COPY copies one or more files (COPY /?; audit/cmd-help/copy-help.txt).
  switches: >-
    Common switches: /A ASCII, /B binary, /V verify, /Y suppress overwrite
    prompt, /-Y force prompt, /D decrypt destination, /Z restartable network
    copy, /L copy symlink itself, /N short name. Sources may be combined with +
    to append into one destination (COPY /?).
  overwrite_defaults: >-
    Overwrite prompting defaults to prompt unless COPY runs from a batch
    script (then /Y is effectively default). COPYCMD may preset /Y or /-Y;
    command-line /-Y or /Y overrides (COPY /?).
  nul_source: >-
    copy nul filename is a common idiom to create an empty file
    (NUL is a special device; see redirection.special_devices).
  ascii_vs_binary_ctrl_z: >-
    /A (ASCII) stops at the first Ctrl+Z (0x1A) in the source; /B (binary)
    copies through it. Confirmed on live Windows 10/11 cmd for a five-byte
    source AB^ZCD: copy /A yields a three-byte file (through Ctrl+Z) while
    copy /B yields all five bytes. Prefer /B when binary fidelity matters.
  concatenation: >-
    Multiple sources joined with + are concatenated into one destination
    (COPY /?). Confirmed on live Windows 10/11 cmd: copy /y a.txt+b.txt out.txt
    writes the contents of a.txt followed by b.txt into out.txt.
  missing_source_errorlevel: >-
    COPY of a missing named source leaves ERRORLEVEL 1 (confirmed on live
    Windows 10/11 cmd). Successful copy leaves ERRORLEVEL 0.
  source: "COPY /? (audit/cmd-help/copy-help.txt)"

type_command:
  description: >-
    TYPE displays the contents of a text file or files
    (TYPE /?; audit/cmd-help/type-help.txt).
  forms: "TYPE [drive:][path]filename (multiple files may be listed)."
  errorlevel: >-
    Successfully displaying a file leaves ERRORLEVEL 0. A missing named file or
    invalid parameters leave ERRORLEVEL 1 (confirmed on live Windows 10/11 cmd;
    stderr still shows the cannot-find-file message unless redirected). Prefer
    IF EXIST before TYPE when absence must be handled without relying on
    ERRORLEVEL alone.
  append_after_type_crlf: >-
    TYPE copies file bytes as-is. If the source's last line has no trailing
    CRLF, a later >> append (for example echo ...) continues on that same
    physical line in the destination. Insert echo.>>file (or otherwise write a
    CRLF) after TYPE when the next append must start a new line. Confirmed on
    live Windows 10/11 cmd.
  con_stdin_capture: >-
    TYPE CON reads from the console keyboard until the user signals end-of-file
    (Ctrl+Z then Enter). Redirecting that stream (type con >file.txt) captures
    multi-line keyboard input into a file. This is an interactive form, not a
    substitute for SET /P for single-line prompts. Confirmed behavior matches
    TYPE /? device-name usage; prefer SET /P for scripted prompts.
  source: "TYPE /? (audit/cmd-help/type-help.txt)"

title_command:
  description: >-
    TITLE sets the console window title
    (TITLE /?; audit/cmd-help/title-help.txt).
  forms: >-
    TITLE [string] sets the title bar text. Omitting string typically clears
    or sets an empty title depending on host behavior; prefer an explicit string.
  quotes_literal: >-
    Double quotes around or inside the TITLE argument are kept as literal
    characters in the window title (they are not stripped). Prefer unquoted
    text when quotes must not appear in the title bar; escape metacharacters
    with ^ instead of relying on quotes. Confirmed on live Windows 10/11 cmd.
  works_under_redirect: >-
    TITLE updates the console window title even when the script's stdout is
    redirected to a file (unlike CLS/COLOR, which are display/attribute side
    effects that do not rewrite a redirected log). Confirmed on live Windows
    10/11 cmd.
  source: "TITLE /? (audit/cmd-help/title-help.txt)"

pause_command:
  description: >-
    PAUSE suspends batch execution until a key is pressed
    (PAUSE /?; audit/cmd-help/pause-help.txt).
  message: >-
    Displays "Press any key to continue . . ." and waits for a keypress
    (PAUSE /?).
  source: "PAUSE /? (audit/cmd-help/pause-help.txt)"

cls_command:
  description: >-
    CLS clears the console screen (CLS /?; audit/cmd-help/cls-help.txt).
  forms: "CLS takes no operands."
  redirected_stdout_noop: >-
    CLS affects the console display. When stdout is redirected (for example
    cls>nul or a script invoked with >logfile), CLS does not clear a redirected
    log file and often leaves the visible console unchanged depending on how
    the process was launched. Redirected stdout may still receive a form-feed
    byte (0x0C) from CLS even though the log is not "cleared" as a console
    would be. COLOR similarly updates console attributes and is ineffective
    for rewriting a pure redirected log (and still leaves ERRORLEVEL 1 on live
    Windows 10/11; see color_command.same_color_errorlevel). Prefer >CON for
    console-only side effects when the script stdout is a file (see
    redirection.con_for_interactive_prompts). Confirmed on live Windows
    10/11 cmd for cls>nul completing without error.
  source: "CLS /? (audit/cmd-help/cls-help.txt)"

ver_command:
  description: >-
    VER displays the Windows version string
    (VER /?; audit/cmd-help/ver-help.txt).
  forms: "VER takes no operands."
  source: "VER /? (audit/cmd-help/ver-help.txt)"

vol_command:
  description: >-
    VOL displays the disk volume label and serial number if present
    (VOL /?; audit/cmd-help/vol-help.txt).
  forms: "VOL [drive:] shows volume info for the specified or current drive."
  source: "VOL /? (audit/cmd-help/vol-help.txt)"

mklink_command:
  description: >-
    MKLINK creates symbolic links, hard links, or directory junctions
    (MKLINK /?; audit/cmd-help/mklink-help.txt). Creating symlinks typically
    requires appropriate privilege (SeCreateSymbolicLinkPrivilege or Developer
    Mode) on modern Windows.
  forms: >-
    MKLINK [[/D] | [/H] | [/J]] Link Target. Default is a file symbolic link;
    /D directory symlink; /H hard link; /J directory junction (MKLINK /?).
  source: "MKLINK /? (audit/cmd-help/mklink-help.txt)"

dir_command:
  description: >-
    DIR lists files and subdirectories
    (DIR /?; audit/cmd-help/dir-help.txt).
  switches: >-
    Common switches include /A attributes, /B bare, /S recurse, /W wide,
    /O sort order, /T time field, /X short names, /P pause, /Q owner, /R ADS
    streams (lists alternate data streams when present; DIR /?). Full switch
    matrix is in DIR /?.
  dircmd_env: >-
    DIRCMD is an ordinary environment variable (not a SET-list dynamic name
    from SET /?). When set, its value supplies default switches for DIR (for
    example SET DIRCMD=/B). Override a preset by prefixing the switch with -
    (for example DIR /-W) (DIR /?; audit/cmd-help/dir-help.txt).
  no_match_errorlevel: >-
    DIR with a mask that matches nothing leaves ERRORLEVEL 1 (confirmed on live
    Windows 10/11 cmd for dir /b nosuch_zzz*.qqq). A successful listing leaves
    ERRORLEVEL 0.
  source: "DIR /? (audit/cmd-help/dir-help.txt)"

move_command:
  description: >-
    MOVE moves files and renames files/directories
    (MOVE /?; audit/cmd-help/move-help.txt).
  forms: >-
    MOVE [/Y | /-Y] source destination moves files; MOVE can also rename a
    directory. /Y suppresses overwrite prompts; /-Y forces prompts. COPYCMD
    may preset /Y; batch scripts default to suppress prompts similarly to COPY
    (MOVE /?).
  cross_volume: >-
    Moving a file to a different volume is allowed and succeeds as a
    copy-then-delete of the source (the source path is gone after a successful
    move). Confirmed on live Windows 10/11 cmd using SUBST to create a second
    volume letter: move /y %TEMP%\file Z:\file leaves ERRORLEVEL 0, creates the
    destination, and removes the source.
  source: "MOVE /? (audit/cmd-help/move-help.txt)"

ren_command:
  description: >-
    REN/RENAME renames files
    (REN /?; audit/cmd-help/ren-help.txt).
  forms: >-
    REN [drive:][path]filename1 filename2. The destination cannot specify a
    new drive or path -- rename in place only (REN /?).
  wildcard_destination_map: >-
    When both source and destination use wildcards, live Windows 10/11 cmd maps
    the destination wildcard by overwriting a prefix of the characters that the
    source wildcard preserved rather than inserting a longer literal stem.
    Confirmed: ren her*.txt your*.txt renames herfile.txt to yourile.txt (the
    four-character your stem overwrites herf of the preserved herfile stem,
    leaving ile.txt), not yourfile.txt. Prefer explicit destination names when
    the intended mapping is not this overwrite behavior.
  destination_exists_errorlevel: >-
    REN fails with ERRORLEVEL 1 when the destination name already exists
    ("A duplicate file name exists, or the file cannot be found.") Confirmed
    on live Windows 10/11 cmd: ren a.txt b.txt with both files present leaves
    EL 1 and keeps both names.
  source: "REN /? (audit/cmd-help/ren-help.txt); live cmd.exe"

chcp_command:
  description: >-
    CHCP displays or sets the active console code page
    (CHCP /?; audit/cmd-help/chcp-help.txt).
  forms: >-
    CHCP [nnn] sets code page nnn; CHCP with no argument displays the active
    code page (CHCP /?).
  source: "CHCP /? (audit/cmd-help/chcp-help.txt)"

doskey_command:
  description: >-
    DOSKEY edits command lines, recalls history, and defines macros
    (DOSKEY /?; audit/cmd-help/doskey-help.txt).
  forms: >-
    DOSKEY [options] [macroname=[text]]. Macro text may use $T as a command
    separator and $1-$9 / $* as parameter placeholders analogous to batch
    %1-%9 / %* (DOSKEY /?).
  source: "DOSKEY /? (audit/cmd-help/doskey-help.txt)"

help_command:
  description: >-
    HELP displays help text for Windows commands
    (HELP /?; audit/cmd-help/help-help.txt).
  forms: "HELP [command] shows help for the named command (HELP /?)."
  source: "HELP /? (audit/cmd-help/help-help.txt)"

more_command:
  description: >-
    MORE displays output one screen at a time and is commonly used on the
    right-hand side of a pipe (MORE /?; audit/cmd-help/more-help.txt).
  forms: >-
    command | MORE [options], MORE < file, or MORE /E [options] [files].
    Extended /E features include clear, formfeed expand, squeeze blank lines,
    and tab expansion (MORE /?).
  errorlevel: >-
    MORE typically leaves ERRORLEVEL 0 after displaying piped or redirected
    input on live Windows 10/11 cmd; treat it as a filter, not a presence test.
  source: "MORE /? (audit/cmd-help/more-help.txt)"

sort_command:
  description: >-
    SORT sorts input lines and is commonly used in pipes
    (SORT /?; audit/cmd-help/sort-help.txt).
  forms: >-
    SORT [/R] [/+n] [/M kilobytes] [/L locale] [/REC chars] [[drive1:][path1]filename1]
    [/T [drive2:][path2]] [/O [drive3:][path3]filename3]. /R reverses order;
    /+n starts compare at column n (SORT /?).
  unique_switch: >-
    SORT accepts /UNIQUE (and shorter prefixes such as /UNIQ) to suppress
    duplicate lines after sorting. Microsoft Learn documents /unique; local
    SORT /? on some Windows 10/11 hosts still omits it. Unknown switches such
    as /NOTAREAL fail with "Invalid switch" and a non-zero ERRORLEVEL (often
    1). Confirmed on live Windows 10/11 cmd.
  errorlevel: >-
    SORT typically leaves ERRORLEVEL 0 after a successful sort on live
    Windows 10/11 cmd; failure modes are tool-defined and less commonly used
    for && / || chaining than FIND/FINDSTR or ROBOCOPY.
  source: "SORT /? (audit/cmd-help/sort-help.txt)"

dpath_command:
  description: >-
    DPATH is a deprecated undocumented cmd internal that mirrors legacy APPEND
    (DPATH /?; audit/cmd-help/dpath-help.txt). Captured help text still uses
    the APPEND spelling for syntax. Prefer ordinary PATH / full paths in modern
    scripts; do not rely on DPATH for new tooling.
  source: "DPATH /? (audit/cmd-help/dpath-help.txt)"

keys_command:
  description: >-
    KEYS is a DOS-compatibility internal that enables or disables command-line
    editing (KEYS /?; audit/cmd-help/keys-help.txt). Under modern Windows it is
    a no-op because command-line editing is always enabled. Listed under
    deprecated_commands.
  source: "KEYS /? (audit/cmd-help/keys-help.txt)"

mode_command:
  description: >-
    MODE configures devices and console properties (MODE /?;
    audit/cmd-help/mode-help.txt). Common script uses include MODE CON: COLS=n
    LINES=m for console size. Device availability and accepted switches are
    host-dependent; treat MODE failures as tool-defined ERRORLEVEL.
  source: "MODE /? (audit/cmd-help/mode-help.txt)"

label_command:
  description: >-
    LABEL.exe sets or displays a volume label (LABEL /?;
    audit/cmd-help/label-help.txt). It is a stock System32 utility, not a cmd
    internal, and can be shadowed by a same-named file in the CWD (see
    command_resolution.cwd_shadows_externals). Interactive LABEL without args
    prompts; prefer non-interactive forms in scripts.
  source: "LABEL /? (audit/cmd-help/label-help.txt)"

print_command:
  description: >-
    PRINT.exe queues a text file to a print device (PRINT /?;
    audit/cmd-help/print-help.txt). It is a stock System32 utility, not a cmd
    internal, and can be shadowed by a same-named file in the CWD (see
    command_resolution.cwd_shadows_externals).
  forms: >-
    PRINT [/D:device] [[drive:][path]filename[...]]. /D:device selects the
    print device. Multiple filenames may be listed.
  bare_invocation: >-
    Bare PRINT with no filename prints "No file to print" and leaves
    ERRORLEVEL 0 on live Windows 10/11 cmd (confirmed). Prefer an explicit
    path when printing is intentional.
  source: "PRINT /? (audit/cmd-help/print-help.txt)"

external_tool_notes:
  description: >-
    Language-impacting notes for common external PATH tools. These are not
    full switch encyclopedias; they document ERRORLEVEL and parsing facts that
    affect Batch control flow (&& / || / IF ERRORLEVEL).
  hostname_command: >-
    hostname.exe is a stock System32 utility listed under
    stock_windows_utilities / builtin_commands. It
    prints the computer's host name to stdout; for scripts that need the machine
    name as data, prefer the ordinary environment variable %COMPUTERNAME%
    (distinct from the dynamic SET /? names). hostname is not a cmd internal.
  find_and_findstr: >-
    FIND and FINDSTR search text (FIND /?, FINDSTR /?;
    audit/cmd-help/find-help.txt, findstr-help.txt). ERRORLEVEL tables:
    find_errorlevel and findstr_errorlevel. Prefer IF EXIST before searching
    expected paths, or redirect stderr (2>nul) when a missing mask is expected.
    When FINDSTR is given two or more input files, each matching line is
    prefixed with path: (colon-delimited); a single-file search does not add
    that prefix (so multi-file output can collide with drive letters such as
    C:). FINDSTR /S with a bare filename searches that name under the
    directory tree from the current directory (not only a CWD file of that
    name). FINDSTR without /C treats a quoted multi-word argument as OR of
    words; /C:"literal with spaces" searches the literal phrase (FINDSTR /?).
    Default FINDSTR matching is case-sensitive unless /I is used. FINDSTR
    defaults to regular-expression mode (/R): metacharacters such as
    . * ^ $ [ ] \< \> apply unless /L forces literal matching (FINDSTR /?;
    Microsoft Learn findstr). Positional /B /E /X are line-break oriented; a
    final line without a trailing newline can fail /E or /X matches that
    succeed after a CRLF (or blank line) is appended (confirmed on live cmd).
    FINDSTR /G:file reads search strings from a file (/ for console) and
    /F:file reads the filename list from a file (/ for console)
    (FINDSTR /?; audit/cmd-help/findstr-help.txt). Confirmed on live
    Windows 10/11 cmd: findstr /G:needles.txt hay.txt and findstr /F:files.txt
    needle leave ERRORLEVEL 0 on a successful match.
  find_errorlevel: >-
    FIND ERRORLEVEL on live Windows 10 (build 19045) cmd (FIND /?;
    audit/cmd-help/find-help.txt — captured help has no Return Code section):
    0 string found in the searched file(s); 1 string not found or missing
    named file (stderr may still report a cannot-open message); 2 invalid
    switch or wildcard pathname matching zero files. Some secondary references
    document ERRORLEVEL 2 for every open failure; live named missing files
    commonly use 1. Because no-match and missing-file share code 1, prefer
    IF EXIST on the path before chaining on FIND alone.
  findstr_errorlevel: >-
    FINDSTR ERRORLEVEL on live Windows 10 (build 19045) cmd (FINDSTR /?;
    audit/cmd-help/findstr-help.txt — no Return Code section): 0 match found
    or /? help display; 1 no match, missing named file, or wildcard pathname
    with zero matching files (stderr "FINDSTR: Cannot open ..." — same code as
    no-match); 2 invalid switch (confirmed with a nonexistent switch such as
    /NOTREAL). Do not treat ERRORLEVEL 1 alone as proof the input path
    existed. Prefer IF EXIST or stderr inspection when open failures must be
    distinguished from no-match.
  where_command: >-
    WHERE locates files matching a pattern via PATH/PATHEXT-style search
    (WHERE /?; audit/cmd-help/where-help.txt). Useful to resolve which
    executable a bare name would run. A successful match leaves ERRORLEVEL 0;
    no match leaves ERRORLEVEL 1 (confirmed on live Windows 10/11 cmd).
    WHERE /R dir pattern recursively searches from dir (WHERE /?). Confirmed on
    live Windows 10/11 cmd: where /r . wave2.cmd from a directory containing
    that file leaves ERRORLEVEL 0 and prints the match path.
  forfiles_command: >-
    FORFILES iterates files and can run a command per match
    (FORFILES /?; audit/cmd-help/forfiles-help.txt). Variables use @file
    style placeholders documented in FORFILES /?. One or more matches leave
    ERRORLEVEL 0; no matches leave ERRORLEVEL 1 and write an error to stderr
    (confirmed on live Windows 10/11 cmd). Prefer wrapping internal commands
    and redirection in cmd /c inside /C "..." (FORFILES /?).
  fc_command: >-
    FC compares two files or sets of files (FC /?; audit/cmd-help/fc-help.txt).
    Live Windows 10/11 ERRORLEVEL: 0 identical; 1 different; 2 cannot find at
    least one file; -1 invalid syntax such as only one file argument. Because
    successful compare is 0 and different is 1, FC ... && next runs next only
    when the files are identical.
  comp_command: >-
    COMP compares two files or sets of files (COMP /?;
    audit/cmd-help/comp-help.txt). /M suppresses the "Compare more files"
    prompt. Live Windows 10/11 ERRORLEVEL: 0 identical; 1 different (including
    unequal sizes reported as "Files are different sizes"); 2 cannot open a
    file or invalid arguments/switch. Without /N, unequal file sizes stop the
    compare with that size message; /N=n limits the compare to n lines and can
    proceed even when sizes differ (trailing extras beyond n may still be
    missed). Without /M, pipe a reply (for example echo n^| COMP ...) to avoid
    an interactive prompt. Confirmed on live Windows 10/11 cmd.
  attrib_command: >-
    ATTRIB displays or changes file attributes (ATTRIB /?;
    audit/cmd-help/attrib-help.txt). Common letters include R/A/S/H plus
    extended NTFS flags listed in ATTRIB /?. /S recurses; /D processes
    directories; /L targets the symlink itself. A missing named file commonly
    leaves ERRORLEVEL 0 on live Windows 10/11 cmd despite a stderr message -
    do not treat zero ERRORLEVEL as proof the path existed. While the hidden
    (H) or system (S) attribute is set, ATTRIB refuses other attribute changes
    and prints "Not resetting hidden file" / "Not resetting system file";
    ERRORLEVEL often remains 0. Clear -H / -S first (or combine -H/-S with the
    desired +R/+A change in one ATTRIB invocation) before modifying other
    attributes on those files. Confirmed on live Windows 10/11 cmd.
  tree_command: >-
    TREE graphically displays folder structure (TREE /?;
    audit/cmd-help/tree-help.txt). /F includes files; /A forces ASCII line
    drawing. A missing path commonly still leaves ERRORLEVEL 0 on live
    Windows 10/11 cmd while writing an invalid-path message to stderr - prefer
    IF EXIST before relying on TREE for presence checks.
  robocopy_errorlevel: >-
    ROBOCOPY returns a bitmask ERRORLEVEL (ROBOCOPY /?;
    audit/cmd-help/robocopy-help.txt; Microsoft Learn Robocopy return codes):
    bit 0 (value 0) — no copies, no failures, no mismatches; bit 1 (1) —
    files copied and/or extra files/dirs detected (successful copies often
    leave 1, so ROBOCOPY ... && next commonly skips next); bit 2 (2) — extra
    files or directories in destination; bit 4 (4) — mismatched files/dirs;
    bit 8 (8) — copy failures; bit 16 (16) — serious/fatal error (bad or
    inaccessible source path). Values 0–7 are commonly treated as success;
    >=8 indicates failure. Live Win10 19045: missing named file under an
    existing source directory often EL 0; missing source directory often EL
    16; /L list-only over an existing file often EL 1; copying one new file
    often EL 1; repeat copy with no changes often EL 0. Test with set /a or
    IF ERRORLEVEL when masking bits.
  robocopy_mov_vs_move: >-
    /MOV moves files only (delete from source after copy; source directories
    remain). /MOVE moves files and directories (delete from source after copy,
    including source directory structure when emptied) (ROBOCOPY /?; Microsoft
    Learn robocopy). Locked files or missing delete permission can leave source
    items behind after either switch.
  robocopy_missing_named_file: >-
    When the source directory exists and one explicitly named file under it does
    not, ROBOCOPY commonly returns ERRORLEVEL 0 (nothing copied / no failure
    bits) on live Windows cmd. A missing or inaccessible source directory path
    is different and commonly sets serious-error bit 16. The same missing named
    file with XCOPY typically returns a non-zero code such as 4 (see
    xcopy_notes). Prefer IF EXIST or wildcard sets when absence must be treated
    as failure.
  xcopy_errorlevel: >-
    XCOPY return codes (not listed in captured XCOPY /?;
    audit/cmd-help/xcopy-help.txt): 0 files copied without error; 1 no files
    found to copy; 2 user pressed Ctrl+C or, on live Win10 19045, a
    non-interactive F/D file-vs-directory prompt received no valid answer
    (destination path ambiguous without /I); 4 initialization error (invalid
    switch, missing named source, insufficient memory or invalid drive); 5
    disk write error during copy. Live Win10 19045: missing named source EL 4;
    copy into an existing directory (trailing backslash) EL 0; wildcard over
    an empty directory EL 0; invalid switch EL 4. See xcopy_notes for ROBOCOPY
    contrast, /I, and F/D prompt handling with redirects.
  xcopy_notes: >-
    XCOPY is an external recursive copy tool (XCOPY /?). See xcopy_errorlevel
    for the return-code table. /C continues after errors. Return codes are
    tool-defined; do not assume identical semantics to COPY or ROBOCOPY when
    chaining with && / ||. Confirmed on live Windows 10/11 cmd: a successful
    copy to a directory destination leaves ERRORLEVEL 0; a missing named
    source file leaves ERRORLEVEL 4 ("File not found"), unlike ROBOCOPY's
    typical 0 for the same single missing name (see robocopy_missing_named_file).
    An empty source directory with a wildcard (xcopy src\*.* dst\) left
    ERRORLEVEL 0 on this host even when no files were copied -- do not assume
    every "no files" condition is non-zero without probing the host. When the
    destination does not exist, XCOPY may prompt whether the target is a file
    or directory (F/D). With stdout redirected away from the console that
    prompt can hang or land in the redirect file and leave ERRORLEVEL 2;
    answer via a pipe such as echo F| xcopy ... or keep prompts on the
    console with >CON (see redirection.con_for_interactive_prompts).
  timeout_command: >-
    TIMEOUT [/T] seconds [/NOBREAK] waits for a key or a timeout
    (TIMEOUT /?; audit/cmd-help/timeout-help.txt). Valid range includes -1
    (wait indefinitely for a key) through 99999 seconds. /T 0 returns
    immediately (useful in parse/smoke fixtures). /NOBREAK ignores keypresses
    other than CTRL+C until the timeout elapses. When stdin is redirected
    (for example timeout /t 0 <nul or a pipe into TIMEOUT), live Windows 10/11
    cmd commonly fails with a message that input redirection is not supported
    and leaves a non-zero ERRORLEVEL (confirmed EL 1 for /t 0 with <nul and
    with a piped empty line).
  reg_query: >-
    REG QUERY reads registry keys/values (REG /?, REG QUERY /?;
    audit/cmd-help/reg-help.txt, audit/cmd-help/reg-query-help.txt).
    Success leaves ERRORLEVEL 0; failure (including a missing key) leaves
    ERRORLEVEL 1 (REG /? Return Code). Prefer IF ERRORLEVEL / %ERRORLEVEL%
    tests when chaining on registry lookups.
  replace_command: >-
    REPLACE updates matching files in a destination directory from a source
    mask (REPLACE /?; audit/cmd-help/replace-help.txt). Default mode replaces
    only names that already exist in the destination; /A adds new names; /U
    updates only when the source is newer; /S recurses (incompatible with /A);
    /R allows read-only targets. Live Windows 10/11 ERRORLEVEL: 0 when the
    command completes without a hard failure -- including "No files replaced"
    when a named source is missing under an existing path, when the destination
    has no matching name, or when zero files needed updating; 3 when the source
    or destination path is not found; 11 for invalid syntax or switch. Some
    secondary references document ERRORLEVEL 2 for a missing source file, but
    live cmd commonly leaves 0 for a missing named file under an existing
    directory (stderr may still show "No files replaced"). Prefer IF EXIST on
    the source before relying on REPLACE for presence checks.
  whoami_command: >-
    WHOAMI.exe prints the current user / group / privilege context
    (WHOAMI /?; audit/cmd-help/whoami-help.txt). Successful runs typically leave
    ERRORLEVEL 0; invalid switches leave a non-zero code. Prefer %USERNAME% /
    %USERDOMAIN% when only the simple name is needed.
  tasklist_taskkill: >-
    TASKLIST / TASKKILL enumerate and terminate processes
    (audit/cmd-help/tasklist-help.txt, taskkill-help.txt). ERRORLEVEL tables:
    tasklist_errorlevel and taskkill_errorlevel. Requires appropriate
    privileges; access-denied failures may use codes other than those listed.
  tasklist_errorlevel: >-
    TASKLIST ERRORLEVEL on live Windows 10 (build 19045) cmd (TASKLIST /?;
    audit/cmd-help/tasklist-help.txt — no Return Code section): 0 command
    completed successfully, including zero output rows (a /FI filter matching
    no processes still leaves EL 0 — use stdout inspection or a follow-up
    FINDSTR/TASKLIST parse to detect hits); 1 invalid /FI filter syntax or
    invalid switch.
  taskkill_errorlevel: >-
    TASKKILL ERRORLEVEL on live Windows 10 (build 19045) cmd (TASKKILL /?;
    audit/cmd-help/taskkill-help.txt — no Return Code section): 0 one or more
    target processes terminated; 128 process not found (/IM image not running,
    with or without /F); 1 invalid switch. Privilege or access-denied failures
    can yield other non-zero codes — inspect stderr and test on the host. Do
    not assume ERRORLEVEL 0 means a kill succeeded without checking output.
  icacls_command: >-
    ICACLS displays or modifies NTFS ACLs (ICACLS /?;
    audit/cmd-help/icacls-help.txt). Prefer ICACLS over deprecated CACLS. Success
    and failure ERRORLEVEL values are tool-defined; redirect carefully when
    capturing ACL dumps.
  clip_command: >-
    CLIP.exe copies stdin to the Windows clipboard (CLIP /?;
    audit/cmd-help/clip-help.txt). Common idiom: echo text| clip. Not a cmd
    internal; availability matches stock System32 on modern Windows 10/11.
  certutil_command: >-
    CERTUTIL is a multi-purpose crypto/certificate utility (CERTUTIL /?;
    audit/cmd-help/certutil-help.txt). Scripts often use certutil -encode /
    -decode / -hashfile. Switch surface is large; prefer documented
    subcommands from captured help. ERRORLEVEL: certutil_errorlevel.
  certutil_errorlevel: >-
    CERTUTIL ERRORLEVEL on live Windows 10 (build 19045) cmd (CERTUTIL /?;
    audit/cmd-help/certutil-help.txt — no unified Return Code section):
    -hashfile on an existing file EL 0; -hashfile on a missing path EL
    -2147024894 (0x80070002 FILE_NOT_FOUND when interpreted as unsigned);
    -encode / -decode success EL 0; unknown top-level verb EL 1; invalid hash
    algorithm EL -805305819 (host-specific CRYPT HRESULT). %ERRORLEVEL% and
    IF ERRORLEVEL display the signed 32-bit value — use set /a or unsigned
    comparison when matching HRESULT constants. Many PKI/ADCS subcommands return
    other HRESULT-style codes; probe the specific verb on the deployment host.
  waitfor_command: >-
    WAITFOR.exe sends or waits for a named signal across systems
    (WAITFOR /?; audit/cmd-help/waitfor-help.txt). Not a cmd internal. Forms:
    WAITFOR [/T timeout] signal waits (default forever; /T range 1-99999
    seconds), and WAITFOR [/S system [/U user [/P [password]]]] /SI signal
    sends. Signal names are limited to 225 characters of a-z A-Z 0-9 and
    ASCII 128-255. Treat ERRORLEVEL as tool-defined; do not assume success
    clears a prior code without checking. Prefer TIMEOUT for local
    second-based waits that do not need cross-machine signaling.
  msg_command: >-
    MSG.exe sends a message to a user or session
    (MSG /?; audit/cmd-help/msg-help.txt). Not a cmd internal. Targets include
    username, sessionname, sessionid, @filename, or * for all sessions on the
    server (/SERVER). /TIME sets acknowledge wait seconds; /V verbose; /W waits
    for a response. Message text may be an argument, prompted, or read from
    stdin. Availability and rights vary by session/host policy; treat
    ERRORLEVEL as tool-defined.
  ping_command: >-
    PING.exe sends ICMP echo requests (PING /?; audit/cmd-help/ping-help.txt).
    Not a cmd internal. Confirmed on live Windows 10 (build 19045): ping -n 1
    127.0.0.1 leaves ERRORLEVEL 0 on success; an unreachably answered probe such
    as ping -n 1 0.0.0.0 commonly leaves ERRORLEVEL 1. Prefer %ERRORLEVEL% /
    IF ERRORLEVEL tests when chaining on reachability; do not treat stdout text
    alone as the control-flow signal.
  ipconfig_command: >-
    IPCONFIG.exe displays TCP/IP configuration (IPCONFIG /?;
    audit/cmd-help/ipconfig-help.txt). Not a cmd internal. Confirmed on live
    Windows 10/11 cmd: a successful bare ipconfig leaves ERRORLEVEL 0; an
    invalid switch leaves ERRORLEVEL 1. Prefer documented switches from the
    captured help (/all, /release, /renew, ...) rather than inventing flags.
  network_admin_tools: >-
    Stock System32 utilities commonly driven from batch for network and admin
    tasks include net.exe, sc.exe, schtasks.exe, systeminfo.exe, takeown.exe,
    fsutil.exe, compact.exe, cipher.exe, arp.exe, route.exe, and netstat.exe.
    Captured help lives under audit/cmd-help/*-help.txt for those names.
    Language-relevant guidance: treat ERRORLEVEL as tool-defined unless a
    specific code is confirmed on the host; net.exe is a multi-subcommand front
    end (net help / net help <command>); sc.exe and schtasks.exe require
    appropriate privileges; takeown.exe changes file ownership before ICACLS
    work. These notes are control-flow oriented, not full switch encyclopedias.
  host_notes: >-
    Language facts in this catalog were confirmed primarily on live Windows 10
    cmd (build family 19045) plus Microsoft /? text and secondary references.
    Windows 11 / Server hosts generally match for core language rules; optional
    Feature-on-Demand tools (telnet, and some media/legacy utilities) and
    SORT /UNIQUE help-text omissions can differ by image. When a claim is
    host-specific, individual keys note the observation rather than asserting
    universal parity. When Microsoft Learn prose conflicts with live Win10/11
    cmd behavior, this catalog records the live observation and notes the
    documentation variance (see also set_a.signed_shift and COLOR ERRORLEVEL
    notes).