docs: distinguish dependency setup recommendations from lookup policy

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

2 files changed, 42 insertions, 19 deletions

diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md
index e5801a3..f5738d1 100644
--- a/AGENTS/ARCH.md
+++ b/AGENTS/ARCH.md
@@ -26,7 +26,7 @@ The compiler emits textual IR. Initial configuration must explicitly select
 development libraries to build; NONE still generates IR. Native binaries remain manual:
 
 ```bash
-# First download dependencies as documented in doc/build.md.
+# Prepare dependencies using the recommendations in doc/build.md.
 cmake -S . -B build -DCPSC_RUN_MODE=EMBEDDED \
   -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++
 cmake --build build
@@ -36,11 +36,17 @@ build/cpsc prog.cps -r -o prog.ir # save IR, then run it
 clang-18 prog.ll -o prog && ./prog
 ```
 
-CMake, make and Clang are system tools. Other build dependencies are downloaded
-to the configured build directory's `deps/packages/`. The modular
-`cmake/LocalDependencies.cmake` entry point extracts Debian, MSYS2 and Homebrew
-binary packages into `deps/root/`, then searches each dependency locally before
-falling back to system libraries. Local LLVM overrides a cached system `LLVM_DIR`.
+`doc/build.md` recommends which packages to install and which to download;
+CMake does not enforce that split. The modular `cmake/LocalDependencies.cmake`
+entry point extracts Debian, MSYS2 and Homebrew binary packages from the build
+directory's `deps/packages/` into `deps/root/`. Standard bin/lib/include layouts
+under the build directory are also searched. The shared
+`cmake/FindDependency.cmake` helper searches locally first, then the system, and
+reports missing required dependencies. Compilers, make, LLVM, support libraries,
+Pandoc, Git and installer/relocation tools use the same lookup policy. System-only
+and mixed installations are supported. Local dependencies override cached system
+paths. Build tools are resolved before `project()` enables compiler checks;
+compiler information is refreshed when the selected executable changes.
 Platform modules relocate package paths only inside the extraction directory;
 Homebrew bottles also receive local Cellar/opt links and Mach-O relocation/signing.
 Package hashes skip unchanged extractions; a changed package set rebuilds the
@@ -134,7 +140,9 @@ untested.)
 | `lib/CodeGen/*Handler.cc`, `FunctionGen.cc`, `RuntimeCheck.cc`, `TypeSystem.cc` | Helpers owned by CodeGen |
 | `CMakeLists.txt` | 3 static libs (CPSLexer, CPSParser, CPSCodeGen) + `cpsc`. **New .cc files must be added to the source lists here** |
 | `tools/driver/EmbeddedRunner.cc`, `cmake/EmbeddedLLVM.cmake` | EMBEDDED-only MCJIT runner and static support-library selection |
-| `cmake/LocalDependencies.cmake`, `cmake/*Packages.cmake` | Local package extraction, platform relocation and dependency discovery |
+| `cmake/LocalDependencies.cmake`, `cmake/*Packages.cmake` | Local package extraction and platform relocation |
+| `cmake/DependencyPaths.cmake`, `cmake/FindDependency.cmake` | Shared local paths and local-first/system-fallback lookup |
+| `cmake/BuildTools.cmake`, `cmake/LLVMDependencies.cmake` | Compiler/build tool selection and LLVM dependency discovery |
 | `cmake/Manual.cmake`, `cmake/GenerateManual.cmake.in` | Optional manual generation with local-first Pandoc discovery |
 | `install.sh`, `install.ps1`, `cmake/Install.cmake.in`, `cmake/Release.cmake` | Artifact installation and versioned binary release packaging |
 
diff --git a/doc/build.md b/doc/build.md
index 18165b7..ca1c30a 100644
--- a/doc/build.md
+++ b/doc/build.md
@@ -5,10 +5,21 @@ see [install.md](install.md).
 
 ## Dependencies
 
-Install CMake, make and Clang as system tools. Download the other dependencies to
-`build/deps/packages/`; CMake extracts them into `build/deps/root/` during
-configuration. Each dependency is searched locally first, then in the system.
-Local LLVM takes precedence over a previously cached system `LLVM_DIR`.
+The commands below recommend installing CMake, make and Clang as system tools
+and downloading LLVM and other dependencies to `build/deps/packages/`. CMake
+extracts downloaded packages into `build/deps/root/` during configuration.
+
+These are setup recommendations, not requirements on where dependencies must
+be installed. Once CMake itself can run, compilers, build tools, libraries and
+optional tools all follow the same lookup rule: local build directories first,
+then the system. A required dependency missing from both locations is an error.
+System-only and mixed installations are supported, including system-installed
+LLVM without any local LLVM download. Local dependencies take precedence over
+previously cached system paths.
+
+CMake searches standard `bin/`, `lib/` and `include/` directories under the build
+directory as well as the extracted package layouts. Compiler and make selection
+follow the same rule as LLVM and Pandoc selection.
 
 Unchanged packages are not extracted again. Keep one version of each package in
 the download directory; remove old archives before downloading a different
@@ -22,14 +33,14 @@ LLVM 18 is the tested version; newer versions remain untested.
 
 ### Linux (Debian/Ubuntu)
 
-Use a distribution repository that provides LLVM 18. Install the build tools:
+Use a distribution repository that provides LLVM 18. Recommended build tools:
 
 ```bash
 sudo apt-get update
 sudo apt-get install -y --no-install-recommends build-essential cmake clang-18
 ```
 
-Download LLVM and its support packages without installing them:
+Recommended LLVM and support-package downloads:
 
 ```bash
 mkdir -p build/deps/packages
@@ -60,7 +71,7 @@ pacman -S --needed \
   mingw-w64-x86_64-clang
 ```
 
-Download the dependencies to the project build directory:
+Recommended dependency downloads to the project build directory:
 
 ```bash
 mkdir -p build/deps/packages
@@ -90,7 +101,7 @@ Use Clang and make from the Xcode Command Line Tools. If they are missing, run
 brew install cmake
 ```
 
-Download the binary bottles to the build directory:
+Recommended binary-bottle downloads to the build directory:
 
 ```bash
 mkdir -p build/deps/packages
@@ -139,9 +150,12 @@ cmake -S . -B build -DCPSC_RUN_MODE=EMBEDDED -DCMAKE_BUILD_TYPE=Release \
 cmake --build build -j4
 ```
 
-Local packages do not need `-DLLVM_DIR`. When no local LLVM is present, CMake uses
-the system search; you can specify `-DLLVM_DIR=/path/to/lib/cmake/llvm` for a
-system installation outside its usual search paths.
+If LLVM and its required support libraries are already installed in the system,
+skip the download steps and use the same build commands. Local and system
+dependencies can also be mixed; the lookup rule applies to each dependency.
+Local packages do not need `-DLLVM_DIR`. You can specify
+`-DLLVM_DIR=/path/to/lib/cmake/llvm` for a system installation outside the usual
+search paths or to select a system LLVM version when several are installed.
 
 Distribute `build/cpsc` (Windows: `build/cpsc.exe`) for `EMBEDDED`. LLVM and its
 required compression/terminal support libraries are linked statically; a missing
@@ -172,7 +186,8 @@ export PATH="$PWD/build/deps/root/opt/llvm@18/bin:$PATH"
 ## Manual
 
 The quick reference is in [cpsc.md](cpsc.md). Pandoc is required only for the
-`doc`, installation and release targets. Download it for your platform:
+`doc`, installation and release targets. Recommended local downloads follow;
+an existing system Pandoc works with the same manual-generation command.
 
 Linux: