[RFC/NFM] docs: distributed programming guides — collectives, benchmarking, and API reference

[georgebisbas]

⚠️ Superseded — split into four smaller PRs

This PR grew too large to review comfortably (36 files, ~3000 lines) and has
been split into four small, independently-reviewable PRs carrying the exact
same content:

1. docs: fix distributed-op docstrings and the ReduceOp type-stub #2218 — Distributed op docstring & type-stub fixes (pure Python, ~184 lines)
2. docs(user): add the Distributed Programming chapter #2219 — Distributed Programming chapter (docs/en/user/distributed/ + zh mirror)
3. docs(user): add the Performance & Benchmarking chapter #2220 — Performance & Benchmarking chapter (docs/en/user/performance/ + zh mirror)
4. docs(user): wire the Distributed Programming chapter into the manual #2221 — Wire both chapters into the landing pages and operation reference
   (draft — depends on docs(user): add the Distributed Programming chapter #2219 and docs(user): add the Performance & Benchmarking chapter #2220 merging first)

All four were cut from this branch's final commit and independently verified
(markdownlint, EN/ZH parity, nav coverage, pre-commit run --all-files,
mkdocs build --strict); a full end-to-end integration of all four together
was also verified to build cleanly with zero broken links and no lost or
duplicated content versus this branch.

Closing this PR without merging — please review and merge #2218–#2221 instead.

---

Original description (superseded, kept for reference)

Summary

Adds the Distributed Programming and Performance & Benchmarking
chapters to the PyPTO user manual, covering PyPTO's L3 distributed execution
model and its benchmarking/tuning workflow end to end. Structure and scope
follow the site's documentation plan and slot directly into the existing
mkdocs.yml nav (EN + ZH).

What's in this PR

Distributed Programming (docs/en/user/distributed/)

• index.md — PyPTO's distributed model in one page: symmetric memory
  • signals, comm domains, and how PyPTO's simplified L2 (single-chip) /
    L3 (cross-rank) vocabulary relates to the simpler runtime's own finer
    L0–L6 hierarchy.
• 00-model.md — A minimal end-to-end HelloAllReduce walkthrough:
  host orchestrator, per-chip orchestration function, InCore kernel, window
  buffers, and how to launch it (a distributed program launches as a plain
  python script.py — PyPTO forks the per-chip workers internally, there's
  no external multi-process launcher).
• 01-collectives.md — Every collective (allreduce, barrier,
  broadcast, allgather, reduce_scatter, all_to_all), the three
  execution paths (InCore hand-rolled, InCore composite, HOST builtin) and
  when to reach for each, supported ReduceOp/dtype per operation, and
  worked examples for each collective.
• 02-primitives.md — The lower-level building blocks for anyone
  writing a custom protocol: notify/wait signal handshakes, window
  buffer allocation, tile-level RMA (remote_load/remote_store),
  one-sided put/get with their chunking/pipelining constraints, and how
  to compose primitives into a hand-rolled collective.
• 03-execution.md — DistributedWorker lifecycle, DistributedConfig,
  and how a compiled distributed program is dispatched.
• 04-debugging.md — Common failure modes (hangs, dispatch-time type
  errors, misconfigured device_ids) with symptoms and fixes.

Performance & Benchmarking (docs/en/user/performance/)

• index.md / 00-methodology.md — A decision tree for where to look
  first (compiler hints, span tree, op-simulator, memory map, dependency
  graph) and the programmatic benchmark() API: signature, BenchmarkStats
  fields, aggregates, and span-tree rendering.
• 01-single-node.md — Single-node tuning: partitioning/parallelism
  (pl.split, pl.spmd, pl.cluster), pipelining/unrolling, the matmul
  path, memory placement (target_memory, MemorySpace), and scheduling
  controls (predicate=, no_dep, manual_scope).
• 02-distributed.md — L3-specific performance: ring sizing and
  RunConfig prewarming, and a bus-bandwidth estimation formula.
• 03-cases.md — End-to-end worked cases (status: additional cases
  planned).

Every page is mirrored in full under docs/zh/user/....

Operation Reference

docs/en/user/02-operation_reference.md gains a Distributed / Collective
Operations section: a capability matrix covering every pld.* op (API,
modes, ReduceOp, atomic support, supported dtypes per execution path, and
notes), cross-linked to the new chapters above.

Site wiring

mkdocs.yml: Distributed: and Performance: nav sections under
User Manual:, with nav_translations entries for the ZH sidebar.

Supporting docstring updates

A handful of docstrings in tensor_ops.py, system_ops.py, tile_ops.py,
dsl_api.py, distributed_compiled_program.py, bench.py, and the
ir.pyi type stub were tightened to match the semantics described in the
new guides (per-operation ReduceOp support, per-operation signal-shape
rank acceptance, and similar precision fixes) so the in-editor docs and the
manual agree.

Verification

• npx markdownlint-cli2 (project config)
• python3 tests/lint/check_docs_en_zh_parity.py
• python3 tests/lint/check_docs_nav.py
• pre-commit run --all-files
• mkdocs build --strict
• Every embedded Python code example checked for valid syntax
• Full CI (unit/system/dist-system tests, codegen tests, clang-tidy)

What this does NOT cover

• Any runtime or compiler code changes — docs, docstrings, and one type
  stub only
• Full EN/ZH structural parity for every subsection of
  performance/01-single-node.md (the ZH mirror is intentionally more
  condensed in a few places; tracked as a follow-up)
• Automated CI verification of embedded doc code blocks (checked manually
  for this PR; a good candidate for a follow-up lint rule)

[coderabbitai]

📝 Walkthrough

Walkthrough

This documentation-focused change adds English and Chinese distributed-programming, API-reference, and benchmarking guides, updates operation references and getting-started pages, and expands Python API docstrings. No executable logic or public signatures change.

Changes

Distributed documentation

Layer / File(s)	Summary
Distributed programming guides docs/{en,zh-cn}/user/00-getting_started.md, docs/{en,zh-cn}/user/05-distributed-guide.md	Adds mesh and ring allreduce examples, notify/wait protocols, collective patterns, cluster execution instructions, debugging guidance, and cross-references.
Distributed API reference docs/{en,zh-cn}/user/02-operation_reference.md, docs/{en,zh-cn}/user/04-distributed-api-reference.md	Documents distributed namespaces, types, collectives, RMA, DSL constructs, data movement, runtime configuration, and worker APIs.
Benchmarking documentation docs/{en,zh-cn}/user/06-benchmarking-guide.md, docs/{en,zh-cn}/user/00-getting_started.md	Documents benchmark harnesses, BenchmarkStats, L2/L3 timing, bus bandwidth, span trees, caveats, and ring preparation.
Python API documentation python/pypto/ir/..., python/pypto/language/..., python/pypto/runtime/bench.py	Expands docstrings with usage forms, constraints, signal shapes, collective notes, remote-operation examples, reduction limitations, and benchmark accessors.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• hw-native-sys/pypto#2084: Updates overlapping pld.tensor.allreduce documentation and protocol details.
• hw-native-sys/pypto#2093: Relates to the documented ring allreduce mode and lowering behavior.
• hw-native-sys/pypto#2094: Adds the ring allreduce implementation reflected by these distributed documentation updates.

Poem

A rabbit hops through docs so bright,
Mesh and ring now share the light.
Signals wait, benchmarks sing,
APIs explain each helpful thing.
“No code changed!” the bunny cheers—
Clearer paths for future years!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main documentation additions: distributed guides, benchmarking, and API reference updates.
Description check	✅ Passed	The description is related to the changeset and accurately outlines the same documentation work, even though it is marked superseded.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3e2172dbf6

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 11

🧹 Nitpick comments (1)

docs/en/user/06-benchmarking-guide.md (1)

28-28: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Fix the mirrored Markdownlint warnings.

Add appropriate language identifiers to fenced blocks and remove or prefix blank lines inside blockquotes in both language versions.

• docs/en/user/06-benchmarking-guide.md#L28-L28: tag the output fence.
• docs/en/user/06-benchmarking-guide.md#L58-L58: tag the API-signature fence.
• docs/en/user/06-benchmarking-guide.md#L114-L114: tag the span-tree fence.
• docs/en/user/06-benchmarking-guide.md#L193-L193: tag the variance-output fence.
• docs/en/user/06-benchmarking-guide.md#L264-L264: tag the formula fence.
• docs/en/user/06-benchmarking-guide.md#L285-L285: tag the worked-example fence.
• docs/en/user/06-benchmarking-guide.md#L324-L324: fix the blank blockquote line.
• docs/en/user/06-benchmarking-guide.md#L329-L329: fix the blank blockquote line.
• docs/en/user/06-benchmarking-guide.md#L334-L334: fix the blank blockquote line.
• docs/en/user/06-benchmarking-guide.md#L363-L363: tag the span-tree fence.
• docs/zh-cn/user/06-benchmarking-guide.md#L27-L27: tag the output fence.
• docs/zh-cn/user/06-benchmarking-guide.md#L57-L57: tag the API-signature fence.
• docs/zh-cn/user/06-benchmarking-guide.md#L113-L113: tag the span-tree fence.
• docs/zh-cn/user/06-benchmarking-guide.md#L188-L188: tag the variance-output fence.
• docs/zh-cn/user/06-benchmarking-guide.md#L257-L257: tag the formula fence.
• docs/zh-cn/user/06-benchmarking-guide.md#L278-L278: tag the worked-example fence.
• docs/zh-cn/user/06-benchmarking-guide.md#L312-L312: fix the blank blockquote line.
• docs/zh-cn/user/06-benchmarking-guide.md#L316-L316: fix the blank blockquote line.
• docs/zh-cn/user/06-benchmarking-guide.md#L320-L320: fix the blank blockquote line.
• docs/zh-cn/user/06-benchmarking-guide.md#L346-L346: tag the span-tree fence.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/en/user/06-benchmarking-guide.md` at line 28, Fix the mirrored
Markdownlint issues in docs/en/user/06-benchmarking-guide.md at lines 28, 58,
114, 193, 264, 285, and 363 by adding appropriate language identifiers to the
output, API-signature, span-tree, variance-output, formula, worked-example, and
span-tree fences; prefix the blank blockquote lines at 324, 329, and 334. Apply
the same corresponding fixes in docs/zh-cn/user/06-benchmarking-guide.md at
lines 27, 57, 113, 188, 257, 278, and 346 for fences, and 312, 316, and 320 for
blank blockquote lines, preserving the existing bilingual content.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/en/user/02-operation_reference.md`:
- Around line 289-298: The capability matrices in
docs/en/user/02-operation_reference.md lines 289-298 and
docs/zh-cn/user/02-operation_reference.md lines 289-298 incorrectly place Put’s
AtomicType.None_ / Add values in the ReduceOps column. Update both matrices to
represent Put’s atomic types in a separate, appropriate capability column while
leaving ReduceOps distinct and preserving the equivalent English and Chinese
content.

In `@docs/en/user/04-distributed-api-reference.md`:
- Around line 243-244: Update the descriptions of
rt.release_inherited_host_tensor_refs() in both
docs/en/user/04-distributed-api-reference.md (lines 243-244) and
docs/zh-cn/user/04-distributed-api-reference.md (lines 240-241) to state that
runtime-held host references are dropped after fork, without promising
unconditional destruction of the host tensor.
- Around line 157-160: Update the benchmark() documentation in
docs/en/user/04-distributed-api-reference.md lines 157-160 to replace the
incorrect RuntimeError claim with the documented zero-sample fallback when
SIMPLER_HOST_STRACE is disabled. Apply the same corrected benchmark contract in
docs/zh-cn/user/04-distributed-api-reference.md lines 155-158, keeping both API
references consistent.
- Around line 220-227: The DeviceTensor examples are not executable or
worker-safe because they omit torch, allocate outside the prepared runtime, and
invoke compiled directly. In docs/en/user/04-distributed-api-reference.md lines
220-227 and docs/zh-cn/user/04-distributed-api-reference.md lines 217-224,
import torch, move rt.alloc_tensor into the compiled.prepare() lifecycle, and
dispatch the compiled call through rt(...), preserving the documented
DeviceTensor usage in both language versions.
- Around line 231-236: Correct the documented compiled.prepare() signature to
remove inherited_host_tensors and list the actual supported parameters in
docs/en/user/04-distributed-api-reference.md lines 231-236 and
docs/zh-cn/user/04-distributed-api-reference.md lines 226-233, keeping both
bilingual API references consistent.

In `@docs/en/user/05-distributed-guide.md`:
- Around line 35-45: Define SIZE before the type annotations in both mirrored
HelloAllReduce examples, using the same documented extent such as 256:
docs/en/user/05-distributed-guide.md lines 35-45 and
docs/zh-cn/user/05-distributed-guide.md lines 31-42 each require this direct
change.
- Around line 155-164: Update both handshake examples in
docs/en/user/05-distributed-guide.md (lines 155-164) and
docs/zh-cn/user/05-distributed-guide.md (lines 149-159) to document and enforce
the precondition tag >= 1 before the notify/wait sequence; keep the existing
signal cell and wait behavior unchanged.

In `@docs/en/user/06-benchmarking-guide.md`:
- Line 87: The benchmarking documentation inconsistently describes non-STRACE
behavior. Update docs/en/user/06-benchmarking-guide.md lines 87 and 320-328 and
docs/zh-cn/user/06-benchmarking-guide.md lines 85 and 308-315 so both languages
consistently state that non-STRACE benchmarking raises before returning
statistics, removing the implication that zero-valued statistics are returned.

In `@docs/zh-cn/user/00-getting_started.md`:
- Around line 407-459: 将 HelloAllReduce 示例引导语中的“可直接复制运行”改为明确表明这是 InCore
kernel/sample 的措辞，避免暗示无需额外配置即可执行；保留现有内核代码及分布式指南链接不变，除非补充完整的 host、COMPILER 和
distributed 运行设置。

In `@python/pypto/language/distributed/op/tensor_ops.py`:
- Around line 541-544: Update the affected Python docstrings near the
signal-shape documentation to replace the Unicode multiplication and minus
symbols with ASCII `x` and `-`, including the additional occurrences around the
referenced lines. Do not add inline Ruff suppressions; preserve the documented
shape expressions and wording otherwise.

In `@python/pypto/language/dsl_api.py`:
- Around line 715-724: Update the “Three usage forms at a glance” table to show
the capture form as `with pl.spmd(n) as tid:` and indicate that optional
`deps=[...]` may be added, rather than presenting deps as required. Keep the
existing descriptions of dispatch/inline behavior and captured producer TaskId.

---

Nitpick comments:
In `@docs/en/user/06-benchmarking-guide.md`:
- Line 28: Fix the mirrored Markdownlint issues in
docs/en/user/06-benchmarking-guide.md at lines 28, 58, 114, 193, 264, 285, and
363 by adding appropriate language identifiers to the output, API-signature,
span-tree, variance-output, formula, worked-example, and span-tree fences;
prefix the blank blockquote lines at 324, 329, and 334. Apply the same
corresponding fixes in docs/zh-cn/user/06-benchmarking-guide.md at lines 27, 57,
113, 188, 257, 278, and 346 for fences, and 312, 316, and 320 for blank
blockquote lines, preserving the existing bilingual content.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6354b3a2-bc3b-4fe9-ac31-591dc7526bdf

📥 Commits

Reviewing files that changed from the base of the PR and between 768c6f9 and 3e2172d.

📒 Files selected for processing (17)

• docs/en/user/00-getting_started.md
• docs/en/user/02-operation_reference.md
• docs/en/user/04-distributed-api-reference.md
• docs/en/user/05-distributed-guide.md
• docs/en/user/06-benchmarking-guide.md
• docs/zh-cn/user/00-getting_started.md
• docs/zh-cn/user/02-operation_reference.md
• docs/zh-cn/user/04-distributed-api-reference.md
• docs/zh-cn/user/05-distributed-guide.md
• docs/zh-cn/user/06-benchmarking-guide.md
• python/pypto/ir/distributed_compiled_program.py
• python/pypto/language/distributed/op/system_ops.py
• python/pypto/language/distributed/op/tensor_ops.py
• python/pypto/language/distributed/op/tile_ops.py
• python/pypto/language/dsl_api.py
• python/pypto/pypto_core/ir.pyi
• python/pypto/runtime/bench.py

[georgebisbas]

AI Review Comment Fixes — All Addressed

All 17 review comments from CodeRabbit and chatgpt-codex-connector have been addressed in the latest commit. Here's a summary:

chatgpt-codex-connector (6 comments — already fixed in previous commits, verified clean):

1. Import import pypto.language.pld → Changed to import pypto.language.distributed as pld in both EN and zh-cn.
2. Dtype matrix overstates HOST-mode support → Now distinguishes FP32 (HOST builtin) from FP16/BF16 (InCore hand-rolled).
3. prepare() incorrectly lists inherited_host_tensors= → Removed; it only exists on DistributedWorker().
4. L3 benchmark claims silent corruption on non-shared tensors → Now correctly documents that DistributedWorker.__call__ raises TypeError.
5. DFX flags documented as "not plumbed through L3" → Now correctly documents that enable_l2_swimlane IS plumbed.
6. ring_heap=128 is not a valid power-of-two → Changed to ring_heap=1024.

CodeRabbit (11 comments — all fixed in this commit):

1. Put's AtomicType.None_/Add in ReduceOps column → Added a dedicated "Atomic" column to the capability matrix.
2. all_zero_device mentions "non-STRACE builds" → Removed; non-STRACE raises RuntimeError, zero-valued stats occur only on *sim platforms.
3. DeviceTensor example not executable → Added import torch, wrapped in compiled.prepare() context, dispatch via rt(...).
4. prepare() API contract → Already fixed (verified clean).
5. release_inherited_host_tensor_refs() over-promises destruction → Now says "drop runtime-held references", not "free the host copy".
6. SIZE undefined in HelloAllReduce → Added SIZE = 256 in both EN and zh-cn.
7. Handshake example missing tag >= 1 precondition → Added callout in both languages.
8. STRACE behavior inconsistency → all_zero_device description aligned with the caveat (non-STRACE raises, *sim returns zero).
9. zh-cn "可直接复制运行" misleading → Clarified this is an InCore kernel sample requiring additional setup.
10. Unicode math symbols (×, −) → Replaced with ASCII x and - in tensor_ops.py.
11. spmd table shows deps as required → Updated to show with pl.spmd(n) as tid: with optional deps=[...].

Nit:

• Markdownlint bare code blocks → Added text/python language tags to bare fences in EN benchmarking guide.

[YunjiQin]

Thanks for putting these together — the distributed and benchmarking surface has needed user-facing documentation for a while, and the structure here is good. I checked the prose against the implementation rather than reading for style; most of it holds up.

Verified correct (spot-checking the claims that are easiest to get wrong):

• C1 pl.Level.HOST + pl.Role.Orchestrator — matches decorator.py:776 and ir.pyi:837/896.
• C2 SIMPLER_HOST_STRACE / SIMPLER_DFX as compile-time macros defaulting to 1 — profiling_config.h:15-24; SIMPLER_DEVICE_STRACE_ENABLE really is a getenv (c_api_shared.cpp:474). Good catch, this one was genuinely misdocumented before.
• benchmark() signature — byte-for-byte with bench.py:840-849; every BenchmarkStats field and property in the guide exists.
• Ring signal [2(NR-1), NR] + the factory-function pattern — matches test_l3_allreduce_ring.py:71-84,205.
• allreduce-inside-a-loop rejection — synthesize_allreduce_signals_pass.cpp:190.
• pld.* short-form / no-short-form table — exactly matches distributed/__init__.py's __all__.
• RunConfig(ring_task_window=256, ring_heap=1024) — both satisfy the power-of-2 constraints in runner.py:307-312.

Blocking, in rough priority order (details inline):

1. 05 — the "InCore Hand-Rolled vs Host-Level Builtin" section is built on a dichotomy that does not exist; InCore composites are a first-class path with their own ST suite.
2. 05 — the Hello World HOST orchestrator will not compile (missing chip-orch layer, rank mismatch, tensor-into-pl.store, pl.dynamic used as a runtime shape).
3. 05 vs 06 — contradictory claims about a missing .share_memory_(); the runtime raises TypeError.
4. tensor_ops.py x6 + 04/05 — the "1-D host / 2-D InCore" signal-shape rule; the host rail accepts both.
5. 04 — window / alloc_window_buffer filed under pld.system.*; they are pld.tensor.*.
6. 06 — prepare(ring_task_window=...) and the "prewarm" paragraph describe an API that does not exist.
7. 04 / 05 — cmake -DSIMPLER_HOST_STRACE=1 is a no-op; nothing in the build reads it.

Scope / hygiene:

8. 04 — the pl.* DSL-constructs and pl.system.* cross-core sections are L2 / intra-chip material and do not belong in a distributed API reference.
9. 04 (and to a lesser degree 06) — the PYPTO_BENCH* table documents pypto-lib-owned variables that have no effect in this repo.
10. 04 — ScopeMode is pl.ScopeMode; bench.py — the new RST table does not parse; 05 is 581 lines against the 500-line cap in .claude/rules/documentation-length.md.

All of the above apply equally to docs/zh-cn/user/, which mirrors the English text faithfully — including the errors. Worth fixing both sides in the same pass.

[georgebisbas]

Update: Rebased onto main, wired into the site, and addressed all review comments

This PR is now rebased onto current main and all outstanding review feedback has been resolved (commit 60c1b490).

Rebase onto main

The branch had drifted ~2 days behind main, which in the meantime gained the MkDocs site scaffold (#2193), including the docs/zh-cn → docs/zh locale rename. Rebased and moved this PR's zh content to the new docs/zh/ path accordingly.

Wired into the live site

The distributed/ and performance/ chapters didn't exist in mkdocs.yml's nav or the top-level user-manual index.md when this branch forked. Added:

• Both chapters to mkdocs.yml's User Manual nav (with zh nav translations).
• Links to both chapters from docs/en/user/index.md / docs/zh/user/index.md, replacing the old "not here yet" placeholder rows.
• Retargeted 5 dangling cross-references (in 00-getting_started.md / 02-operation_reference.md, en + zh) that still pointed at the deleted flat 04-/05-/06-*.md files.
• Fixed a handful of broken relative links (wrong path depth, links to not-yet-existing language//tutorials//execution/ chapters) that mkdocs build --strict caught.

CI fixes

The restructure commit introduced 66 markdownlint errors (MD060 table-pipe spacing, MD028 blank lines inside blockquotes, MD040 missing fence languages) that were never fixed. All resolved — pre-commit run --all-files and mkdocs build --strict are both clean.

Review comments — all 18 addressed

13 needed real fixes, all applied and replied to inline; 5 turned out to already be resolved by the restructure commit:

• distributed/00-model.md — the Quickstart HelloAllReduce example had 4 real bugs (missing Orchestration dispatch layer, a rank mismatch from pl.slice, a redundant post-dispatch pl.store, wrong window-buffer shape). Rewritten to match the working tests/st/distributed/collectives/test_l3_allreduce.py::AllReduceMesh reference.
• distributed/02-primitives.md — window/alloc_window_buffer moved out of the pld.system.* table into their actual pld.tensor.* namespace.
• distributed/01-collectives.md + tensor_ops.py (6 docstrings) — corrected the host-builtin signal shape (rank-1 or rank-2, not only 1-D) and replaced the InCore-hand-rolled-vs-HOST-builtin dichotomy with the real three-way split (hand-rolled / InCore composite / HOST builtin), since ring mode is InCore-composite-only.
• distributed/03-execution.md, performance/00-methodology.md — dropped fabricated PYPTO_BENCH* defaults that belong to pypto-lib, not this repo.
• distributed/04-debugging.md — removed a non-functional cmake -D... example for compile-time macros that no CMakeLists.txt in the repo reads.
• performance/02-distributed.md — corrected Ring Sizing to show RunConfig passed to every dispatch (not just prepare()), with the real power-of-2 size constraints.
• 02-operation_reference.md — dropped a stale branch reference and an unverified dtype restriction from the AllReduce capability matrix.
• bench.py — fixed a malformed RST table (column marker narrower than its widest cell).

All fixes mirrored in docs/zh/user/. CI is green (13/13 checks).

[georgebisbas]

converting to draft, no need for review yet, needs some work and polishing

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5bfb602d42

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[georgebisbas]

This PR will be broken down to smaller parts as discussed offline with @lyfne123. Making it draft, and will step by step break it down and to smaller ones.

[georgebisbas]

Closing in favor of the split: #2218, #2219, #2220, #2221. See the updated description above for the mapping.