AI at the Workbench

A. Terminal and operating-system notes

A terminal displays commands and their output. A shell interprets those commands. Windows examples in this edition use PowerShell; a .cmd file launched from it runs a Windows command wrapper. The working directory determines what a relative path identifies. Confirm that directory before diagnosing a missing file or running a project operation.

The small PowerShell vocabulary

From a normal PowerShell terminal, use Get-Location to print the current folder and Get-ChildItem to list it. Use Set-Location 'C:\BookLab\sensor-monitor' to enter your actual extraction root. Quotes keep a path with spaces together. A leading dot in .\scripts\replay.cmd means the current folder; .. means its parent. Do not copy a prompt decoration such as PS C:\...> as part of a command.

Use Get-Command git to see whether the shell can resolve Git. Replace the tool name for another executable. A tool may be installed in a documented portable directory without being on the current PATH, the list of locations searched for commands. Follow the project's setup instructions or use its explicit environment override instead of scattering executable copies into unrelated folders.

After a native command, inspect $LASTEXITCODE promptly. The value belongs to the most recently executed native program and can be replaced by a later command. A result of zero ordinarily indicates successful completion for these project wrappers; the application's documented meaning is authoritative. An intentional FAULT state in synthetic replay can still be a successful program execution. A failed assertion and a fixture parse error are different outcomes.

# Context: PowerShell in the applicable project checkpoint root.
.\scripts\replay.cmd
$LASTEXITCODE

Keep the exact command, source checkpoint, and output together. If you redirect output to a file, use a deliberate path inside your evidence folder and do not overwrite the only copy of an earlier result. Read error output as well as ordinary output. A command that never started is not a failed policy assertion.

Windows ARM setup boundary

The recorded native compiler is the ARM64 LLVM-MinGW package identified in dependencies.json. Keep the package's directory structure. The .cmd wrappers manage the selected compiler's runtime directory for their own process, avoiding a permanent user/system PATH change. The primary path does not require a PowerShell execution-policy change. Optional .ps1 wrappers apply only where the existing policy permits them.

If automatic discovery does not match your installation, set the documented overrides in the current PowerShell session using your actual executable paths:

# Context: PowerShell; examples must be replaced with actual installed paths.
$env:CXX = 'C:\Tools\llvm-mingw\bin\clang++.exe'
$env:ARDUINO_CLI = 'C:\Tools\arduino\arduino-cli.exe'
.\scripts\replay.cmd
.\scripts\build-firmware.cmd

A native host compiler and ESP32 cross-compiler are distinct. The first builds the program running on Windows; the second builds firmware for the selected board. Read the actual setup and dependency manifest for pinned archives, hashes, installation locations, and full target options.

macOS host appendix path

The reference project provides a Python wrapper for a host C++17 compiler. The authoring host path was exercised with Apple Clang 21.0.0 and Python 3.13.12 as recorded in project evidence. It is separate from the Windows learner demonstration and does not certify a different firmware or physical path. From the final project root:

# Context: macOS shell in CP09/final sensor-monitor, with documented tools installed.
python3 scripts/native.py test
python3 scripts/native.py replay
python3 scripts/native.py commands

Earlier checkpoints may not contain these later helpers; use their README. Do not translate a Windows path by changing slashes and assume every compiler option or dependency remains available. Record the actual version and result on your platform.

Linux guidance, not a tested certification

The host code is designed for a C++17 compiler, and the Python wrapper supports an explicit compiler selection. Linux users can inspect the wrapper and run it with their installed compiler, such as the documented --cxx option for g++. This edition's Windows and macOS results do not constitute a Linux execution receipt. Complete a new setup record and relevant checks before describing that combination as tested.

For any platform, keep the source unchanged while investigating a loader or path failure. Once the executable reaches a reproducible program error, move to the software diagnosis workflow. This order prevents environment problems from causing unnecessary firmware edits.