Update AGENTS.md files with build instructions and formatting guidance

- water/AGENTS.md: restructure Building section to clarify that Water
  must be built with CMake first, then pip install with WAVE_WATER_DIR;
  add full cmake configure/build commands and useful flags; note that
  ninja alone is sufficient for iterating after initial pip install;
  add git clang-format guidance; add lit location note; add Pipelines.cpp
  reference in Pass Pipeline section
- waveasm/AGENTS.md: add git clang-format guidance
- AGENTS.md: update pre-commit invocation; add AGENTS.local.md to .gitignore

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: Tim Gymnich <tim@gymni.ch>

Author: tgymnich

.gitignore

@@ -60,5 +60,6 @@ water/build_tools/wheel/water_mlir/water_mlir
 # rocm version detection
 requirements-pytorch-rocm-generated.txt
 
-# Claude
+# AI Agents
 CLAUDE.local.md
+AGENTS.local.md

AGENTS.md

@@ -21,13 +21,12 @@ pytest -s tests/ --run-e2e                             # GPU tests (requires har
 
 ### Linting
 ```bash
-mypy                        # type check wave_lang
-pre-commit run --all-files  # Black, Ruff, clang-format
+mypy               # type check wave_lang
+pre-commit run     # run Black, Ruff, clang-format against currently staged files
 ```
 
 ### Gotchas
 - **Always set `WAVE_CACHE_ON=0`** when testing code changes — stale cache entries hide the effect of edits: `WAVE_CACHE_ON=0 pytest ...`
-- DCO sign-off required on commits: `git commit -s`
 - Dump MLIR for debugging: `pytest --dump-mlir-files-path=/tmp/mlir tests/`
 
 ## Architecture

water/AGENTS.md

@@ -2,26 +2,57 @@ Water is an optional MLIR layer in the Wave compiler stack that replaces IREE's
 
 ## Building
 
+Water must be built with CMake first. `pip install` alone does not build Water — `WAVE_WATER_DIR` is required to point Wave at an existing Water build.
+
+LLVM is pinned at `water/llvm-sha.txt`. CLI tool: `water-opt` (analogous to `mlir-opt`).
+
+### Step 1: Build Water with CMake
+
+Requires a pre-built LLVM/MLIR. Set `$BUILD_DIR` to your LLVM build or install tree.
+
 ```bash
-# First build — builds LLVM from source, takes a while
-WAVE_WATER_DIR=water/build pip install -e ".[dev]"
+# Configure
+cmake -G Ninja \
+      -B water/build \
+      water/ \
+      -DMLIR_DIR=$BUILD_DIR/lib/cmake/mlir \
+      -DBUILD_SHARED_LIBS=ON \
+      -DPython3_EXECUTABLE="$(which python)" \
+      -DWATER_ENABLE_PYTHON=ON
+
+# Optional: faster builds with clang + ccache + lld
+cmake -B water/build \
+      -DCMAKE_C_COMPILER=clang \
+      -DCMAKE_CXX_COMPILER=clang++ \
+      -DCMAKE_C_COMPILER_LAUNCHER=ccache \
+      -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
+      -DLLVM_USE_LINKER=lld
+
+# Build
+cmake --build water/build
+```
+
+### Step 2: Install Wave with Water bindings
 
-# Iterating on C++ changes
-ninja -C water/build          # rebuild changed targets only
-pip install -e ".[dev]"       # re-links Python extension (fast, skips CMake)
+```bash
+WAVE_WATER_DIR=water/build pip install -e ".[dev]"
 ```
 
-`WAVE_WATER_DIR` tells the Wave build system to use an existing build directory instead of rebuilding from scratch. Without it, the full LLVM + Water CMake build runs on every `pip install`.
+`WAVE_WATER_DIR` tells Wave where to find the Water build. Without it, Water is not included.
 
-LLVM is pinned at `water/llvm-sha.txt`. CLI tool: `water-opt` (analogous to `mlir-opt`).
+### Iterating on C++ changes
 
-## Formatting
+```bash
+ninja -C water/build          # rebuild changed C++ targets and Python bindings
+```
 
-C++ code is formatted with `clang-format`. Run via pre-commit or directly:
+## Formatting
 
+C++ code is formatted with `git clang-format` which formats only the lines changed relative to a commit (default: `HEAD`)
 ```bash
-clang-format -i <file>          # format a single file in-place
-pre-commit run clang-format     # format all staged files
+git clang-format                # format staged changes
+git clang-format HEAD~1         # also include most recent commit
+git clang-format main           # format everything touched on your branch
 ```
 
 ## Testing

waveasm/AGENTS.md

@@ -15,11 +15,12 @@ Set `WAVE_WAVEASM_DIR=waveasm/build` after first build to avoid full rebuilds on
 
 ## Formatting
 
-C++ code is formatted with `clang-format`. Run via pre-commit or directly:
+C++ code is formatted with `git clang-format` which formats only the lines changed relative to a commit (default: `HEAD`)
 
 ```bash
-clang-format -i <file>          # format a single file in-place
-pre-commit run clang-format     # format all staged files
+git clang-format                # format staged changes
+git clang-format HEAD~1         # also include most recent commit
+git clang-format main           # format everything touched on your branch
 ```
 
 ## Testing