qf math tests and docs

Author: deftio

.github/workflows/pages.yml

@@ -1,4 +1,4 @@
-# Deploy static docs/ to GitHub Pages (see repo Settings → Pages → GitHub Actions).
+# Deploy static pages/ to GitHub Pages (see repo Settings → Pages → GitHub Actions).
 
 name: Pages
 
@@ -33,7 +33,7 @@ jobs:
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: docs
+          path: pages
 
       - name: Deploy to GitHub Pages
         id: deployment

.gitignore

@@ -1,8 +1,52 @@
+# --- Local build trees (Makefile, CMake, IDEs)
 /build/
-examples/esp32s3_benchmark/build/
-examples/esp32s3_benchmark/sdkconfig
-examples/esp32s3_benchmark/sdkconfig.old
-examples/lilygo_t_display_s3_bench/.pio/
+**/build/
+cmake-build-*/
+CMakeFiles/
+CMakeCache.txt
+CMakeScripts/
+CTestTestfile.cmake
+_deps/
+DartConfiguration.tcl
+Makefile.cmake
+cmake_install.cmake
+install_manifest*.txt
+
+# Compiled objects / libraries / binaries
+*.o
+*.obj
+*.a
+*.lib
+*.so
+*.so.*
+*.dylib
+*.dll
+*.exe
+*.out
+*.app
+compile_commands.json
+*.d           # GCC -MD dependency files
+
+# PlatformIO / embedded toolchains
+.pio/
+
+# ESP-IDF / Arduino sketch exports (often regenerated)
+**/sdkconfig
+**/sdkconfig.old
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Coverage / sanitizers (keep patterns if tooling adds more)
 *.gcda
 *.gcno
 *.gcov
+
+# OS / editors
+.DS_Store

CMakeLists.txt

@@ -13,3 +13,11 @@ idf_component_register(
     SRCS "src/qf_math.c"
     INCLUDE_DIRS "src"
 )
+
+target_compile_options(${COMPONENT_LIB} PRIVATE
+    -Wall
+    -Wextra
+    -Wshadow
+    -Wconversion
+    -Werror
+)

Makefile

@@ -2,8 +2,12 @@
 # @author M A Chatterjee <deftio [at] deftio [dot] com>
 
 CC      ?= gcc
-CFLAGS   = -Wall -Wextra -Wpedantic -Wshadow -Wconversion -Werror -Os -std=c99
-CFLAGS_RELAX = -Wall -Wextra -Os -std=c99 -Wno-unused-parameter -Wno-conversion
+CXX     ?= g++
+CFLAGS_WARN = -Wall -Wextra -Wpedantic -Wshadow -Wconversion
+CFLAGS   = $(CFLAGS_WARN) -Werror -Os -std=c99
+CFLAGS_RELAX = -Wall -Wextra -Wshadow -Os -std=c99 -Wno-unused-parameter -Wno-conversion
+CXXFLAGS_WARN = -Wall -Wextra -Wpedantic -Wshadow -Wconversion
+CXXFLAGS = $(CXXFLAGS_WARN) -Werror -Os -std=c++11
 LDFLAGS  = -lm
 
 # Defined only for test binaries so internal helpers can be exercised (coverage).
@@ -17,6 +21,7 @@ BUILD    = build
 SRC      = $(SRCDIR)/qf_math.c
 HDR      = $(SRCDIR)/qf_math.h
 TEST_SRC = $(TESTDIR)/qf_math_test.c
+CPP_TEST_SRC = $(TESTDIR)/qf_math_cpp_test.cpp
 
 # --- compare/ harness (deps under build/compare/third_party/) ---
 COMP_DIR    = $(BUILD)/compare
@@ -30,6 +35,10 @@ COMPARE_STAMP   = $(COMP_DIR)/.deps-ready
 LIBFIXMATH_SRCS = fix16.c fract32.c uint32.c fix16_trig.c fix16_sqrt.c fix16_exp.c
 LIBFIXMATH_OBJS = $(addprefix $(COMP_OBJ)/lf_,$(LIBFIXMATH_SRCS:.c=.o))
 FR_MATH_OBJ      = $(COMP_OBJ)/fr_math.o
+FR_MATH_FULL_OBJ = $(COMP_OBJ)/fr_math_full.o
+FR_MATH_LEAN_OBJ = $(COMP_OBJ)/fr_math_lean.o
+FASTTRIG_ESP32_OBJ = examples/lilygo_t_display_s3_bench/.pio/build/lilygo-t-display-s3/libd57/FastTrig/FastTrig.cpp.o
+XTENSA_ESP32S3_SIZE = $(HOME)/.platformio/packages/toolchain-xtensa-esp32s3/bin/xtensa-esp32s3-elf-size
 
 .PHONY: help
 help:
@@ -42,7 +51,7 @@ help:
 	@echo "  lib-lean       Build qf_math_lean.o (-DQF_MATH_LEAN, peer-comparable size)"
 	@echo "  test           Build and run unit tests"
 	@echo "  bench          Build and run qf_math vs libm benchmark"
-	@echo "  docs-pages     Inject fresh bench sweep into docs/pages/index.html"
+	@echo "  docs-pages     Inject fresh bench sweep into pages/index.html"
 	@echo ""
 	@echo "Comparison (see compare/README.md):"
 	@echo "  compare-deps   Fetch libfixmath + fr_math into $(COMP_THIRD)/"
@@ -52,8 +61,9 @@ help:
 	@echo "  compare-matrix Alias for compare"
 	@echo "  compare-tests  Run libfixmath upstream tests_ro64 (CMake)"
 	@echo "  compare-fr-tests Run fr_math upstream makefile test suite"
-	@echo "  mcu-benchmark-snapshot  Flash LilyGO bench → compare/MCU_BENCHMARK_SNAPSHOT.md (USB)"
+	@echo "  mcu-benchmark-snapshot  Flash MCU bench → compare/MCU_BENCHMARK_SNAPSHOT*.md (USB)"
 	@echo "  benchmark-crossplatform Merge host + MCU snapshots → compare/BENCHMARK_CROSSPLATFORM.md"
+	@echo "  benchmark-arch-speed    Build qf_math architecture speed matrix"
 	@echo ""
 	@echo "Analysis:"
 	@echo "  size           Show compiled object size"
@@ -84,16 +94,21 @@ $(BUILD)/qf_math_lean.o: $(SRC) $(HDR)
 	$(CC) $(CFLAGS) -DQF_MATH_LEAN -c $(SRC) -o $@
 
 .PHONY: test
-test: dirs $(BUILD)/qf_math_test
+test: dirs $(BUILD)/qf_math_test $(BUILD)/qf_math_cpp_test
 	@echo "Running qf_math tests..."
 	@echo ""
 	@$(BUILD)/qf_math_test
+	@$(BUILD)/qf_math_cpp_test
 
 $(BUILD)/qf_math_test: $(TEST_SRC) $(SRC) $(HDR)
-	$(CC) -Wall -Wextra -Os -std=c99 -I$(SRCDIR) $(CFLAGS_TEST) $(TEST_SRC) $(SRC) $(LDFLAGS) -o $@
+	$(CC) $(CFLAGS_WARN) -Os -std=c99 -I$(SRCDIR) $(CFLAGS_TEST) $(TEST_SRC) $(SRC) $(LDFLAGS) -o $@
+
+$(BUILD)/qf_math_cpp_test: $(CPP_TEST_SRC) $(SRC) $(HDR) $(SRCDIR)/qf_math.hpp
+	$(CC) $(CFLAGS) -c $(SRC) -o $(BUILD)/qf_math_cpp_test_qf_math.o
+	$(CXX) $(CXXFLAGS) -I$(SRCDIR) $(CPP_TEST_SRC) $(BUILD)/qf_math_cpp_test_qf_math.o $(LDFLAGS) -o $@
 
 $(BUILD)/qf_math_bench: $(TOOLSDIR)/qf_math_bench.c $(SRC) $(HDR)
-	$(CC) -Wall -Wextra -Os -std=c99 -I$(SRCDIR) $(TOOLSDIR)/qf_math_bench.c $(SRC) $(LDFLAGS) -o $@
+	$(CC) $(CFLAGS_WARN) -Os -std=c99 -I$(SRCDIR) $(TOOLSDIR)/qf_math_bench.c $(SRC) $(LDFLAGS) -o $@
 
 .PHONY: bench
 bench: dirs $(BUILD)/qf_math_bench
@@ -120,6 +135,14 @@ $(FR_MATH_OBJ): $(FR_MATH_ROOT)/FR_math.c | $(COMPARE_STAMP)
 	@mkdir -p $(COMP_OBJ)
 	$(CC) $(CFLAGS_RELAX) -c $< -o $@ -I$(FR_MATH_ROOT) -DFR_NO_PRINT
 
+$(FR_MATH_FULL_OBJ): $(FR_MATH_ROOT)/FR_math.c | $(COMPARE_STAMP)
+	@mkdir -p $(COMP_OBJ)
+	$(CC) $(CFLAGS_RELAX) -c $< -o $@ -I$(FR_MATH_ROOT)
+
+$(FR_MATH_LEAN_OBJ): $(FR_MATH_ROOT)/FR_math.c | $(COMPARE_STAMP)
+	@mkdir -p $(COMP_OBJ)
+	$(CC) $(CFLAGS_RELAX) -c $< -o $@ -I$(FR_MATH_ROOT) -DFR_LEAN -DFR_NO_PRINT
+
 COMPARE_BIN = $(COMP_DIR)/benchmark_suite
 
 $(COMPARE_BIN): compare/benchmark_suite.c compare/benchmark_core.c $(SRC) $(HDR) $(LIBFIXMATH_OBJS) $(FR_MATH_OBJ)
@@ -132,11 +155,11 @@ compare compare-matrix: dirs compare-deps $(COMPARE_BIN)
 	@$(COMPARE_BIN)
 
 .PHONY: compare-report
-compare-report: lib lib-lean compare-deps $(LIBFIXMATH_OBJS) $(FR_MATH_OBJ)
-	@bash compare/report_sizes.sh "$(BUILD)/qf_math.o" "$(BUILD)/qf_math_lean.o" "$(FR_MATH_OBJ)" $(LIBFIXMATH_OBJS)
+compare-report: lib lib-lean compare-deps $(LIBFIXMATH_OBJS) $(FR_MATH_OBJ) $(FR_MATH_FULL_OBJ) $(FR_MATH_LEAN_OBJ)
+	@FASTTRIG_O="$(FASTTRIG_ESP32_OBJ)" XTENSA_SIZE="$(XTENSA_ESP32S3_SIZE)" bash compare/report_sizes.sh "$(BUILD)/qf_math.o" "$(BUILD)/qf_math_lean.o" "$(FR_MATH_OBJ)" "$(FR_MATH_FULL_OBJ)" "$(FR_MATH_LEAN_OBJ)" $(LIBFIXMATH_OBJS)
 
 .PHONY: compare-github-report
-compare-github-report: lib lib-lean compare-deps $(COMPARE_BIN) $(LIBFIXMATH_OBJS) $(FR_MATH_OBJ)
+compare-github-report: lib lib-lean compare-deps $(COMPARE_BIN) $(LIBFIXMATH_OBJS) $(FR_MATH_OBJ) $(FR_MATH_FULL_OBJ) $(FR_MATH_LEAN_OBJ)
 	@bash compare/gen_github_report.sh
 
 .PHONY: compare-fr-tests
@@ -151,6 +174,10 @@ mcu-benchmark-snapshot: compare-deps
 benchmark-crossplatform:
 	python3 $(TOOLSDIR)/gen_benchmark_crossplatform.py
 
+.PHONY: benchmark-arch-speed
+benchmark-arch-speed:
+	python3 $(TOOLSDIR)/gen_qf_arch_speed.py
+
 .PHONY: compare-tests
 compare-tests:
 	@bash $(TOOLSDIR)/run_libfixmath_tests.sh

README.md

@@ -4,7 +4,7 @@
 [![Docs](https://img.shields.io/badge/docs-compare%20%26%20bench-blue.svg)](compare/README.md)
 [![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](src/qf_math.h)
 [![GitHub](https://img.shields.io/badge/GitHub-repo-181717.svg?logo=github)](https://github.com/deftio/qf_math)
-
+   
 [![PlatformIO](https://img.shields.io/badge/PlatformIO-library-teal.svg)](https://registry.platformio.org/libraries/deftio/qf_math)
 [![Arduino](https://img.shields.io/badge/Arduino-from%20source-teal.svg)](https://github.com/deftio/qf_math)
 [![ESP-IDF](https://img.shields.io/badge/ESP--IDF-component-teal.svg)](https://components.espressif.com/components/deftio/qf_math)
@@ -13,9 +13,11 @@
 
 **qf_math** is a compact, dependency-free C99 library for **fast approximate math on IEEE-754 `float`**. It targets embedded firmware where you want predictable cost and small flash footprint: table-driven trig, logarithms, exponentials, `sqrt`, `hypot`, waveform helpers, and a floating-point ADSR envelope—without pulling in full libm semantics on platforms where that matters.
 
+[github.com/deftio/fr_math](github.com/deftio/fr_math) is the fixed point (pure integer) cousin of this library with identical apis.
+
 | | |
 |---|---|
-| **Language** | C99 (`float` API, `qf` typedef) |
+| **Language** | C99 (`float` API, `qf` typedef), plus optional C++ header wrapper |
 | **Dependencies** | None at compile time for the library itself |
 | **License** | BSD-2-Clause — see `LICENSE.txt` |
 | **Layout** | `src/` library · `test/` unit tests · `build/` all binaries & fetched third-party sources |
@@ -42,9 +44,11 @@ For targets **without a hardware FPU** (or when you want to avoid soft-float cos
 ## Repository layout
 
 ```
-src/           qf_math.c, qf_math.h   — drop-in library
+src/           qf_math.c, qf_math.h/.hpp — drop-in C library + C++ wrapper
 test/          qf_math_test.c         — correctness vs libm on host
-examples/      optional demos — ESP-IDF (`examples/esp32s3_benchmark`) + LilyGO T-Display-S3 PlatformIO (`examples/lilygo_t_display_s3_bench`)
+docs/          Markdown documentation (algorithms, API, fr_math, integration)
+pages/         GitHub Pages site (compact HTML + CSS; deploy via Actions)
+examples/      optional demos — ESP-IDF (`esp32s3_benchmark`), LilyGO T-Display-S3 PlatformIO (`lilygo_t_display_s3_bench`), Raspberry Pi Pico 2 Arduino (`pico2_benchmark`)
 docker/        multi-arch toolchain image + cross size report (fr_math-style)
 compare/       matrices vs other math libs + benchmark harness (see below)
 tools/         extra shell helpers & qf_math vs libm micro-benchmark
@@ -101,22 +105,22 @@ Documentation tables live under **`compare/`** (`LIBRARIES.md` for platforms/rep
 | `make compare-github-report` | Regenerates **[`compare/BENCHMARK_REPORT.md`](compare/BENCHMARK_REPORT.md)** for GitHub (embedded bench tables + sizes). |
 | `make compare-tests` | CMake-builds libfixmath `tests_ro64` under `build/compare/third_party/libfixmath-build` and runs it. |
 | `make compare-fr-tests` | Runs **fr_math**’s upstream `make test` against the shallow clone (`compare/run_fr_math_tests.sh`). |
-| `make mcu-benchmark-snapshot` | Flash **LilyGO T-Display-S3** bench and rewrite **`compare/MCU_BENCHMARK_SNAPSHOT.md`** via UART (**pio**, **pyserial**). |
-| `make benchmark-crossplatform` | Rewrite **`compare/BENCHMARK_CROSSPLATFORM.md`** — Host \| MCU **Speed vs libm** ratios from the two committed snapshots (no hardware). |
+| `make mcu-benchmark-snapshot` | Flash MCU bench and rewrite **`compare/MCU_BENCHMARK_SNAPSHOT*.md`** via UART (**pio** / Arduino, **pyserial**). Supports LilyGO T-Display-S3, ESP32-S3, and Raspberry Pi Pico 2. |
+| `make benchmark-crossplatform` | Rewrite **`compare/BENCHMARK_CROSSPLATFORM.md`** — Host \| MCU **Speed vs libm** ratios from the committed snapshots (no hardware). |
 
 **Interpretation:** Desktop timings are *not* MCU timings. Bridged benchmarks include float↔fixed overhead that disappears when you stay natively in `fix16_t` / fixed-radix `s32`. The automated `s32` peer row is **fr_math**; other fast libraries are surveyed in [`compare/PEERS.md`](compare/PEERS.md) but are not wired into the reproducible host/ESP32-S3 harness yet. Use these numbers for intuition and regression tracking, not as a substitute for profiling on your silicon.
 
-**On silicon:** **[examples/lilygo_t_display_s3_bench](examples/lilygo_t_display_s3_bench/README.md)** (PlatformIO, **LilyGO T-Display-S3**) or **[examples/esp32s3_benchmark](examples/esp32s3_benchmark/README.md)** (ESP-IDF) runs the **same** [`benchmark_core.c`](compare/benchmark_core.c) loops so UART / USB serial captures wall-clock under Xtensa / newlib `libm`.
+**On silicon:** **[examples/lilygo_t_display_s3_bench](examples/lilygo_t_display_s3_bench/README.md)** (PlatformIO, **LilyGO T-Display-S3**), **[examples/esp32s3_benchmark](examples/esp32s3_benchmark/README.md)** (ESP-IDF), or **[examples/pico2_benchmark](examples/pico2_benchmark/)** (Arduino, **Raspberry Pi Pico 2** ARM / RISC-V) run the **same** [`benchmark_core.c`](compare/benchmark_core.c) loops so UART / USB serial captures wall-clock on real hardware.
 
-**Host vs MCU (relative only):** **[compare/BENCHMARK_CROSSPLATFORM.md](compare/BENCHMARK_CROSSPLATFORM.md)** merges **Speed vs libm** tables from [`compare/BENCHMARK_REPORT.md`](compare/BENCHMARK_REPORT.md) (POSIX snapshot) and [`compare/MCU_BENCHMARK_SNAPSHOT.md`](compare/MCU_BENCHMARK_SNAPSHOT.md); regenerate with **`make benchmark-crossplatform`** after refreshing those files.
+**Host vs MCU (relative only):** **[compare/BENCHMARK_CROSSPLATFORM.md](compare/BENCHMARK_CROSSPLATFORM.md)** merges **Speed vs libm** tables from [`compare/BENCHMARK_REPORT.md`](compare/BENCHMARK_REPORT.md) (POSIX snapshot) and the MCU snapshots (`MCU_BENCHMARK_SNAPSHOT*.md` — ESP32-S3, Pico 2 ARM, Pico 2 RISC-V); regenerate with **`make benchmark-crossplatform`** after refreshing those files.
 
 ---
 
 ## Packaging & integration
 
 ### PlatformIO
 
-Use `library.json` at the repo root: add this folder as a local library or publish following [PlatformIO library format](https://docs.platformio.org/en/latest/manifests/library-json/index.html). Headers resolve from `src/` (`#include "qf_math.h"`).
+Use `library.json` at the repo root: add this folder as a local library or publish following [PlatformIO library format](https://docs.platformio.org/en/latest/manifests/library-json/index.html). Headers resolve from `src/` (`#include "qf_math.h"` for C, `#include "qf_math.hpp"` for C++).
 
 ### Espressif ESP-IDF
 
@@ -132,8 +136,8 @@ Public surface is declared in `src/qf_math.h`:
 
 - **Macros**: clamps, interpolation, deg/rad/BAM, radix bridges (`QF_TO_FR`, …).
 - **Trig**: `qf_sin`, `qf_cos`, `qf_tan`, BAM-native variants, inverse trig.
-- **Log/exp**: `qf_log2`, `qf_ln`, `qf_log10`, `qf_pow2`, `qf_exp`, `qf_pow10`.
-- **Length**: `qf_sqrt`, `qf_hypot`, `qf_hypot_fast8` (piecewise-linear magnitude).
+- **Log/exp/pow**: `qf_log2`, `qf_ln`, `qf_log10`, `qf_pow2`, `qf_exp`, `qf_pow10`, `qf_pow`.
+- **Length**: `qf_sqrt`, `qf_hypot`, `qf_hypot_fast2`, `qf_hypot_fast8` (piecewise-linear magnitude).
 - **Audio-ish**: LFSR noise, PWM/square/saw/triangle waves, `qf_adsr_*` envelope.
 
 Domain violations (`sqrt` of negative, `log` of non-positive) return `QF_DOMAIN_ERROR`.
@@ -144,7 +148,8 @@ Domain violations (`sqrt` of negative, `log` of non-positive) return `QF_DOMAIN_
 
 | File | Purpose |
 |------|---------|
-| [`docs/`](docs/) | **GitHub Pages** site root (enable *Settings → Pages → GitHub Actions*; live at `https://deftio.github.io/qf_math/` after first deploy). |
+| [`docs/`](docs/) | **Markdown documentation** — algorithms, API reference, fr_math relationship, integration guide |
+| [`pages/`](pages/) | **GitHub Pages** site (enable *Settings → Pages → GitHub Actions*; live at `https://deftio.github.io/qf_math/` after first deploy) |
 | [`compare/README.md`](compare/README.md) | Compare harness docs (`make compare`, sizes, upstream suites, GitHub report) |
 | [`compare/BENCHMARK_REPORT.md`](compare/BENCHMARK_REPORT.md) | Last checked-in **host benchmark + size snapshot** (run `make compare-github-report` to refresh) |
 | [`compare/BENCHMARK_CROSSPLATFORM.md`](compare/BENCHMARK_CROSSPLATFORM.md) | Host vs MCU **relative** ratios (`make benchmark-crossplatform`; refresh snapshots first) |

agents.md

@@ -7,7 +7,9 @@ Guidance for automated coding agents editing this repository.
 - **`src/`** — Library only (`qf_math.c`, `qf_math.h`). Keep this TU self-contained and allocation-free unless explicitly requested.
 - **`test/`** — Host-side regression (`qf_math_test.c`). Extend here when changing numerical behavior.
 - **`compare/`** — Peer-library matrices (`*.md`), benchmark harness (`benchmark_suite.c`, **`benchmark_core.c`** — shared with ESP **`examples/`** trees), fetch/report scripts. All clones/build artifacts stay under `build/compare/`.
-- **`examples/`** — Optional on-device benches: **`examples/lilygo_t_display_s3_bench/`** (PlatformIO, LilyGO T-Display-S3) and **`examples/esp32s3_benchmark/`** (ESP-IDF).
+- **`examples/`** — Optional on-device benches: **`examples/lilygo_t_display_s3_bench/`** (PlatformIO, LilyGO T-Display-S3), **`examples/esp32s3_benchmark/`** (ESP-IDF), and **`examples/pico2_benchmark/`** (Arduino, Raspberry Pi Pico 2).
+- **`docs/`** — Markdown documentation (algorithms, API reference, fr_math relationship, integration guide).
+- **`pages/`** — GitHub Pages HTML site (compact single-page bench + overview); deploy via GitHub Actions.
 - **`tools/`** — Host helpers (`qf_math_bench.c`, `run_libfixmath_tests.sh`); keep MCU-light.
 - **`build/`** — All binaries, CMake trees, cloned deps. Never commit; never author primary sources only here.
 
@@ -21,8 +23,8 @@ Guidance for automated coding agents editing this repository.
 - Upstream libfixmath tests: `make compare-tests`
 - Upstream fr_math tests: `make compare-fr-tests`
 - Cross-target ROM/code-size table (Docker, fr_math-style): `make docker-sizes` → `build/docker_size_table.md` (see `docker/README.md`)
-- MCU compare benchmark (needs **`make compare-deps`**): **`examples/lilygo_t_display_s3_bench/`** (`pio run -t upload -t monitor`) or **`examples/esp32s3_benchmark/`** (`idf.py`).
-- Silicon snapshot: **`make mcu-benchmark-snapshot`** → **`compare/MCU_BENCHMARK_SNAPSHOT.md`** (**pio**, **pyserial**, USB).
+- MCU compare benchmark (needs **`make compare-deps`**): **`examples/lilygo_t_display_s3_bench/`** (`pio run -t upload -t monitor`), **`examples/esp32s3_benchmark/`** (`idf.py`), or **`examples/pico2_benchmark/`** (Arduino IDE / `arduino-cli`).
+- Silicon snapshot: **`make mcu-benchmark-snapshot`** → **`compare/MCU_BENCHMARK_SNAPSHOT*.md`** (**pio** / Arduino, **pyserial**, USB).
 
 ## Editing rules
 
@@ -38,4 +40,4 @@ Guidance for automated coding agents editing this repository.
 
 ## Markdown policy
 
-Root `README.md` is canonical user-facing. **`compare/*.md`** holds methodology matrices; **`compare/BENCHMARK_REPORT.md`** is the tooling-generated snapshot (`make compare-github-report`)—refresh it after materially changing numerical behavior if you want GitHub viewers to see fresh tables.
+Root `README.md` is canonical user-facing. **`docs/`** holds Markdown documentation (algorithms, API, fr_math, integration). **`pages/`** holds the GitHub Pages HTML site. **`compare/*.md`** holds methodology matrices; **`compare/BENCHMARK_REPORT.md`** is the tooling-generated snapshot (`make compare-github-report`)—refresh it after materially changing numerical behavior if you want GitHub viewers to see fresh tables.