docs: add CompilerSutraPerf project docs

clang_flag_explorer.md

@@ -25,8 +25,8 @@ Requirements:
    - Do not use identical or illustrative before/after assembly as a placeholder. If the flag acts in preprocessing, diagnostics, language selection, or debug metadata, show the appropriate observable artifact (`-E`, diagnostics, `-###`, IR, or object sections) and explain why machine instructions are unchanged.
    - Keep `SourceCode` examples genuinely multiline and readable in the rendered page; do not pass a long one-line JSX string when formatted source is required.
    - **Why use it / when not to use it**: include ABI, portability, correctness, and build-consistency warnings where relevant.
-   - **Performance impact**: explain qualitative tradeoffs. Use `PerfReport` only with real measurements obtained by actually running the [CompilerSutra Perf tool](https://github.com/CompilerSutra/CompilerSutraPerfTool) or its documented CLI. Include the without/with arrays, workload, machine, compiler, trial setup, limitations, and exact reproduction commands. Run the commands in the workspace before reporting any numbers; never invent, estimate, or copy placeholder measurements. If the tool or workload cannot be run, say so and omit `PerfReport` data.
-   - Link the `CompilerSutra Perf` name to https://pypi.org/project/compilersutra-perf/ whenever measurements are reported.
+   - **Performance impact**: explain qualitative tradeoffs. Use `PerfReport` only with real measurements obtained by actually running [CompilerSutraPerf](https://www.compilersutra.com/docs/project/compilersutra-perf/) (`csperf`, [PyPI](https://pypi.org/project/compilersutra-perf/)) or its documented CLI. Include the without/with arrays, workload, machine, compiler, trial setup, limitations, and exact reproduction commands. Run the commands in the workspace before reporting any numbers; never invent, estimate, or copy placeholder measurements. If the tool or workload cannot be run, say so and omit `PerfReport` data.
+   - Link the `CompilerSutraPerf` name to the in-site docs and https://pypi.org/project/compilersutra-perf/ whenever measurements are reported.
    - Format reproduction commands for mobile and desktop: wrap commands line-by-line, avoid repeating long absolute paths, and use tabs or separate compact blocks for comparison variants.
    - **Compatibility**: table covering Clang, GCC, MSVC where relevant, language modes, and target restrictions.
    - **Usage example**: exact, copy-pasteable Clang command lines; include `-###` or IR inspection when useful.
@@ -61,7 +61,7 @@ Requirements:
 12. After writing, sanity-check:
    - the exact generated page path and slug;
    - responsive rendering of long commands and comparison blocks on mobile and desktop;
-   - performance claims link to the CompilerSutra Perf package when measurements are used;
+   - performance claims link to CompilerSutraPerf docs and PyPI when measurements are used;
    - `{/* HAND_AUTHORED */}` is still present;
    - all links and source paths are correct;
    - Mermaid/MDX syntax is valid;

docs/articles/machineblockplacement-329-benchmark-prevalence-and-fix.md

@@ -314,7 +314,7 @@ If **`-O2` is slower than `-O1`** on branchy text/parse code:
 4. **Do not ship** with placement globally disabled — other loops benefit from fall-through layout.
 5. **PGO** may supply missing `branch_weights` on char switches ([part 2](/docs/articles/machineblockplacement-wrong-bet-static-probabilities-pgo)).
 
-Structured harness alternative: [CompilerSutra Perf](https://pypi.org/project/compilersutra-perf/) (`pip install compilersutra-perf`) with manifests like `configs/testcase_O{1,2,2np}.json` in the part 1 bundle.
+Structured harness alternative: [CompilerSutraPerf](/docs/project/compilersutra-perf/) ([PyPI](https://pypi.org/project/compilersutra-perf/)) (`pip install compilersutra-perf`) with manifests like `configs/testcase_O{1,2,2np}.json` in the part 1 bundle.
 
 ## 9. What we do not claim
 
@@ -337,7 +337,7 @@ Structured harness alternative: [CompilerSutra Perf](https://pypi.org/project/co
 - [Part 2: Static Probabilities, Fall-Through, and PGO](/docs/articles/machineblockplacement-wrong-bet-static-probabilities-pgo)
 - [LLVM PR #219126](https://github.com/llvm/llvm-project/pull/219126) · [Issue #218248](https://github.com/llvm/llvm-project/issues/218248)
 - [MachineBlockPlacement](https://llvm.org/doxygen/MachineBlockPlacement_8cpp.html) · [`opt-bisect-limit`](https://llvm.org/docs/CommandGuide/opt.html)
-- [CompilerSutra Perf](https://pypi.org/project/compilersutra-perf/)
+- [CompilerSutraPerf](/docs/project/compilersutra-perf/) · [PyPI](https://pypi.org/project/compilersutra-perf/)
 
 :::note Lab note
 Prevalence CSVs: research kit `results/testsuite_singlesource_mbp_sweep.csv`, `testsuite_multisource_mbp_sweep.csv`, `hpc_external_mbp_sweep.csv`, `text_scan_mbp_sweep.csv`, `parser_mbp_sweep.csv`, `sci_calc_mbp_sweep.csv`, `parallel_mbp_sweep.csv`, `oss_apps_mbp_sweep.csv` (Aug–Sep 2026 sweeps). Unfixed Clang: `/home/aitr/osc/llvm_project_without_change/llvm-project/build/bin/clang` (24.0.0git). Lab repro numbers: part 1/2 artifact bundles. CPU: AMD Ryzen 7 9700X.

docs/articles/when-o2-layout-hurts-machineblockplacement.md

@@ -189,7 +189,7 @@ We run **three separate experiments** with distinct roles. Absolute counter valu
 | Role | Tool | Why it is here |
 |------|------|----------------|
 | **Primary evidence** | Linux `perf` | Direct `perf stat` on the binary; headline table for this article |
-| **Independent benchmark harness** | [CompilerSutra Perf](https://pypi.org/project/compilersutra-perf/) (`csperf`) | Same builds, different runner — confirms the regression is not a `perf` artifact |
+| **Independent benchmark harness** | [CompilerSutraPerf](/docs/project/compilersutra-perf/) ([PyPI](https://pypi.org/project/compilersutra-perf/)) (`csperf`) | Same builds, different runner — confirms the regression is not a `perf` artifact |
 | **Microarchitectural corroboration** | AMD uProf 5.2 | Branch-hotspot view on Zen 5; checks the story at frame level |
 
 ### Experiment A — Primary evidence: Linux `perf`
@@ -206,7 +206,7 @@ Paired: O1 faster in **97/100** runs. Every O2 run has more branch misses than e
 
 `-O0` / `-O3` are not the investigation. For completeness: `-O3` ≈ `-O2` here; `-O0` is slower than `-O1` and is not needed to name the pass.
 
-### Experiment B — Independent benchmark harness: CompilerSutra Perf (`csperf`)
+### Experiment B — Independent benchmark harness: CompilerSutraPerf (`csperf`)
 
 Same source, same `N`, same stage1 Clang. Manifests live under `configs/csperf/testcase_*.json` (warmup 3, repeat 100). Install: `pip install compilersutra-perf`.
 
@@ -540,7 +540,7 @@ Expected sum for `1048576` / seed `29`: `15723844160` (asserted in the full kit
 - LLVM [MachineBlockPlacement](https://llvm.org/doxygen/MachineBlockPlacement_8cpp.html) (“Branch Probability Basic Block Placement”)
 - Upstream report: [llvm/llvm-project#218248](https://github.com/llvm/llvm-project/issues/218248)
 - [`opt-bisect-limit`](https://llvm.org/docs/CommandGuide/opt.html) (same knob via `clang -mllvm`)
-- [CompilerSutra Perf](https://pypi.org/project/compilersutra-perf/) (`pip install compilersutra-perf`)
+- [CompilerSutraPerf](/docs/project/compilersutra-perf/) · [PyPI](https://pypi.org/project/compilersutra-perf/) (`pip install compilersutra-perf`)
 - Related: [Part 2 — static probabilities, PGO, and layout](/docs/articles/machineblockplacement-wrong-bet-static-probabilities-pgo), [Part 3 — 329-benchmark prevalence and LLVM fix](/docs/articles/machineblockplacement-329-benchmark-prevalence-and-fix), [GCC vs Clang real benchmarks](/docs/articles/gcc_vs_clang_real_benchmarks_2026_reporter), [stencil pass trace](/docs/articles/where_gcc_and_clang_diverge_stencil_pass_trace)
 
 :::note Lab note

docs/project/compilersutra-perf/architecture.md

@@ -0,0 +1,260 @@
+---
+title: "Architecture"
+sidebar_label: "Architecture"
+description: "Project architecture for compilersutra-perf — orchestration, adapters, measurement, and result artifacts."
+displayed_sidebar: csperfSidebar
+keywords:
+  - csperf architecture
+  - native runner
+  - pipeline phases
+---
+
+# Architecture
+
+**CompilerSutraPerf** (`csperf`, [PyPI: `compilersutra-perf`](https://pypi.org/project/compilersutra-perf/)) is a **host-side orchestration layer** around existing compilers and profilers. It does not replace Clang, GCC, HIP, OpenCL, Vulkan, or Linux `perf` — it sequences them and normalizes what they produce.
+
+Research framing: [Observatory](/docs/project/compilersutra-perf/observatory/).  
+Day-one usage: [Getting started](/docs/project/compilersutra-perf/getting-started/) · [Tutorial](/docs/project/compilersutra-perf/tutorial/).
+
+:::tip How to read this page
+1. Skim the **project architecture** diagram (layers).  
+2. Follow the **pipeline phases** left → right (one `csperf run`).  
+3. Use the tables when you need field names or “what works today.”
+:::
+
+## Project architecture
+
+Like IREE’s overview, think in **layers**: a stable core, pluggable adapters, optional measurement, and a common artifact.
+
+```mermaid
+graph TB
+  accTitle: csperf project architecture
+  accDescr: Host Python core orchestrates toolchain adapters and native runners, optional profilers and energy plugins, then writes a common result artifact.
+
+  subgraph Core["Core · Python"]
+    CLI["CLI / config<br/>csperf run · doctor · diff"]
+    Detect["Source detect"]
+    Plan["Pipeline plan"]
+    Schema["Result schema<br/>JSON / CSV / XLSX"]
+    Report["Reports<br/>HTML / PDF / dashboard"]
+  end
+
+  subgraph Adapters["Toolchain & backend adapters"]
+    CPU["CPU<br/>clang / g++"]
+    HIP["HIP<br/>hipcc / ROCm"]
+    OCL["OpenCL"]
+    VK["Vulkan<br/>glslang / SPIR-V"]
+  end
+
+  subgraph Native["Native execution · C++"]
+    NR["csperf_native_runner"]
+    OR["OpenCL runner"]
+    VR["Vulkan runner"]
+  end
+
+  subgraph Measure["Measurement plugins"]
+    Perf["CPU profiler<br/>perf / PAPI"]
+    Energy["Energy<br/>RAPL / rocm-smi / …"]
+  end
+
+  Out["Common result artifact<br/>results/*.json"]
+
+  CLI --> Detect --> Plan
+  Plan --> CPU & HIP & OCL & VK
+  CPU --> NR
+  HIP --> NR
+  OCL --> OR
+  VK --> VR
+  NR & OR & VR --> Schema
+  Perf -.-> Schema
+  Energy -.-> Schema
+  Schema --> Report
+  Schema --> Out
+  NR -.-> Perf
+  NR -.-> Energy
+```
+
+| Layer | Responsibility |
+| --- | --- |
+| **Core** | Flags, manifests, detection, planning, schema, compare, reports |
+| **Adapters** | Map a file type to a vendor/open toolchain |
+| **Native** | Low-overhead launch, timers, device interaction |
+| **Measurement** | Optional counters and energy — never invent values |
+| **Artifact** | One reusable JSON (plus CSV / reports) |
+
+**Design rule:** integrate existing tools; do not invent another general-purpose IR just to unify backends. Preserve native outputs; normalize only what must be compared.
+
+## Pipeline phases
+
+A single `csperf run` advances through discrete phases (same idea as IREE’s Input → … → VM overview):
+
+```mermaid
+graph LR
+  accTitle: csperf run phases
+  accDescr: Input to Detect to Plan to Compile to Execute to Measure to Artifact
+
+  A([Input]) --> B([Detect])
+  B --> C([Plan])
+  C --> D([Compile])
+  D --> E([Execute])
+  E --> F([Measure])
+  F --> G([Artifact])
+```
+
+| Phase | What happens | Stop early with |
+| --- | --- | --- |
+| **Input** | Read CLI / manifest / policy | — |
+| **Detect** | Map extension → backend (`cpu`, `hip`, `opencl`, `vulkan`) | — |
+| **Plan** | Build compile + run + profiler command list | `--plan-only` |
+| **Compile** | Invoke toolchain (clang, hipcc, glslang, …) | — |
+| **Execute** | Native runner: warmup + measured trials | `--execution-timeout` |
+| **Measure** | Optional `perf` / PAPI / energy | `--no-perf`, `--no-energy` |
+| **Artifact** | Write JSON (+ CSV; optional XLSX / HTML) | — |
+
+Concrete CPU example (perfwiki-style: command first, then what it means):
+
+```python
+csperf run --input examples/cpp/matrix_traversal.cpp --backend cpu \
+  --warmup-runs 1 --repeat-runs 3 --output results/cpu.json
+csperf profile results/cpu.json
+```
+
+That path is: **Input → Detect(cpu) → Plan → Compile → Execute → Measure → Artifact**.
+
+## Workflow overview
+
+Using `csperf` in practice:
+
+1. **Prepare a workload** — C/C++, HIP, OpenCL `.cl`, or Vulkan shader  
+2. **Pick a backend** — explicit `--backend`, or `gpu` to auto-route by extension  
+3. **Run** — `csperf run` (or `quickstart` for the smoke path)  
+4. **Inspect** — `profile`, `diff`, `visualize`  
+
+```mermaid
+graph LR
+  accTitle: csperf user workflow
+  accDescr: Workload to backend to run to inspect
+
+  W([Workload]) --> B([Backend])
+  B --> R([csperf run])
+  R --> I([Inspect])
+```
+
+| Step | Typical command |
+| --- | --- |
+| Smoke test | `csperf quickstart --output-dir results/quickstart` |
+| Time only | `csperf run … --no-perf --no-energy` |
+| Opt sweep | `csperf run … --diff-optimize --report-format both` |
+| Compare two JSON files | `csperf diff a.json b.json --csv out.csv` |
+
+## CPU path (stable on Linux)
+
+```mermaid
+graph LR
+  accTitle: CPU backend path
+  accDescr: Source to compiler to binary to native runner to optional perf to JSON
+
+  S([Source .c/.cpp]) --> C([Compiler])
+  C --> Bin([Binary])
+  C -.-> IR(["IR *.ll · best-effort"])
+  Bin --> N([Native runner])
+  N --> J([JSON])
+  N -.-> P([perf / PAPI])
+  P --> J
+```
+
+- Compiler resolution: `CXX_COMPILER` → `CXX` → default `clang++`  
+- `CXXFLAGS` is **not** read — pass `--compiler-flag`  
+- Prefer same-execution `perf` for branch/cache studies ([Methodology](/docs/project/compilersutra-perf/methodology/))
+
+## GPU paths (experimental)
+
+```mermaid
+graph TB
+  accTitle: GPU backend routing
+  accDescr: gpu alias routes by extension to HIP OpenCL or Vulkan
+
+  IN([Input]) --> EXT{Extension}
+  EXT -->|.hip| HIP([HIP · hipcc + ROCm])
+  EXT -->|.cl| OCL([OpenCL · build + launch])
+  EXT -->|.comp / .glsl| VK([Vulkan · validate only])
+  HIP & OCL & VK --> OUT([JSON artifact])
+```
+
+| Backend | Execute today? | Notes |
+| --- | --- | --- |
+| HIP | Yes | `kernel_time_ms` (events) ≠ `hip_profiler_*` (rocprof) |
+| OpenCL | Yes | State `--opencl-measure` when publishing times |
+| Vulkan | Partial | Shader-module validation; **no** full dispatch yet |
+
+## Measurement model
+
+Counters and energy are **plugins beside** the timed trials — not the timer itself.
+
+```mermaid
+graph TB
+  accTitle: Measurement plugins
+  accDescr: Timed trials always write JSON; optional profiler and energy feed the same artifact
+
+  T([Timed trials]) --> J([JSON artifact])
+  T -.-> Perf([CPU profiler])
+  T -.-> E([Energy backend])
+  Perf --> J
+  E --> J
+```
+
+| Flag | Effect |
+| --- | --- |
+| `--no-perf` | Skip hardware counters |
+| `--no-energy` | Skip `power` block |
+| `--cpu-profiler auto\|perf\|papi\|papi-native` | Choose counter path |
+
+On Linux, the CPU profiler path is built on the same ideas as the [perfwiki tutorial](https://perfwiki.github.io/main/tutorial/): **events** (software vs PMU), **`perf stat`-style counting**, and **multiplexing/scaling** when you ask for more events than hardware counters. `csperf` records whether counts came from the **same execution** as wall time — that provenance is what makes a claim honest.
+
+Before publishing numbers, read [Methodology](/docs/project/compilersutra-perf/methodology/) (events, same-execution, scaling).
+
+## Result artifact
+
+Every successful or partial run aims to be **self-describing** (commands, host, tool version, provenance).
+
+| If you want… | Look at |
+| --- | --- |
+| Runtime | `metrics.execution_time_ms` |
+| Per-trial times | `execution.trial_results` |
+| Exact commands | `commands` |
+| Same-exec counters? | `execution.measurement.same_execution` |
+| Why counters missing | `execution.perf_error` / `metrics_availability` |
+
+Top-level sections: `pipeline`, `commands`, `hardware`, `metrics`, `execution`, `artifacts`, optional `power`.
+
+## Module map (0.2.0)
+
+| Tree area | Role |
+| --- | --- |
+| `cli` | Unified entry (`run`, `doctor`, `diff`, …) |
+| `execution/` | Compile/run adapters |
+| `profiler/` | `perf`, PAPI, macOS paths |
+| `energy/` | RAPL / AMD GPU / macOS backends |
+| `report/` | HTML/PDF exporters |
+| `experiments/` | row / column / tiled macros |
+| `native/runtime/` | C++ runners |
+| `examples/` | Seed workloads |
+
+## Status matrix
+
+| Path | Ready? |
+| --- | --- |
+| Linux CPU | Stable |
+| OpenCL / HIP | Experimental |
+| Vulkan | Partial (validate) |
+| CUDA / Metal | Not implemented |
+
+Roadmap milestones: [Observatory](/docs/project/compilersutra-perf/observatory/).
+
+## See also
+
+- [Observatory](/docs/project/compilersutra-perf/observatory/) — research goal and evidence labels  
+- [Usage](/docs/project/compilersutra-perf/usage/) — flags and recipes  
+- [Methodology](/docs/project/compilersutra-perf/methodology/) — what you can trust  
+- [Energy & reports](/docs/project/compilersutra-perf/energy-and-reports/) — RAPL and HTML/PDF  
+- [Troubleshooting](/docs/project/compilersutra-perf/troubleshooting/) — when a phase fails