docs(hip-kernel-provider): refresh rocKE architecture foundations

[tenpercent]

JIRA ID : AICK-1593

Summary

Stage 1 of the five-stage documentation pilot. Refresh the top-level
documentation map and retain core architecture guidance that remains useful and
grounded in the current implementation.

This stage:

• clarifies the ownership boundary: platform/python/rocke/instances contains
  platform-owned kernel instances, including MoE, while attention builders are
  library-owned under library/kernels; reusable authoring mechanics belong in
  helpers, and foundational IR, analysis, and lowering belong in core;
• defines <project_root>, <platform_root>, and <library_root> so source
  locations, Python imports, and platform/library ownership are not conflated;
• separates exact-target wavefront requirements from matrix-instruction
  selection: gfx942/gfx950 admit wave64 only, gfx1250 admits wave32 only, and
  the current gfx1151/gfx11-generic/gfx1201 catalog rows admit wave32 even
  though those targets can select wave64 at compile time; MFMA/WMMA availability
  and atom identity come from the exact gfx target and its MmaCatalog;
• corrects target-specific attention guidance: gfx942 uses narrow MFMA atoms
  and strided LDS reads for the V operand, gfx950 variants may use target-specific
  transpose LDS reads and wider catalog atoms, and gfx1250 selects its own WMMA
  operations and requires wave32 geometry;
• updates the primitive taxonomy to match the checked-in builders, including
  pooling, top-k reduction, MoE sorting, attention, and reduction paths;
• removes unsupported universal percentage and performance claims; and
• documents buffer-resource encodings as exact-gfx backend choices rather than
  conclusions inferred from a broad accelerator-family label.

Pilot stage map

• Stage 1: docs(hip-kernel-provider): refresh rocKE architecture foundations #9764 — architecture foundations
• Stage 2: docs(hip-kernel-provider): preserve address-planning design #9963 — address-planning future design
• Stage 3: docs(hip-kernel-provider): relocate gfx950 attention case study #9964 — gfx950 attention case study
• Stage 4: docs(hip-kernel-provider): relocate gfx942 attention case study #9965 — gfx942 attention case study
• Stage 5: docs(hip-kernel-provider): correct backend and runtime guidance #9966 — backend, lowering, and runtime guidance

This is a five-stage review-workflow pilot. We will stop after Stage 5 and ask
maintainers whether these boundaries are reviewable before splitting any
remaining audit work.

Test plan

• Focused pre-commit hooks passed for the changed documentation and the committed PR range.
• git diff --check passed.
• Changed-document relative-link and referenced-path checks found no broken local targets.
• Targeted AGPR documentation checks confirmed LLVM attribute emission and the (0, 0) COMGR option sequence against the current Python engine.
• Source grounding confirmed the current known_arches() SRD mapping, exact-target MFMA/WMMA catalogs, compile-time wave constraints, platform/library ownership, non-matmul primitive bodies, the implemented multi-ABD subset, and the C++ AGPR parser scope.
• Focused current-source validation passed: 39 multi-architecture tests with one expected capability skip, plus 3 attention documentation lowering tests.
• Before the split, the full documentation audit ran on gfx950 in a Kreb ROCm image: verify_dsl_docs reported 49 passed and 0 failed; the README implicit-GEMM manifest verification reported bad=0.
• The latest review-response commit is documentation-only and changes no emitted kernel or runtime behavior; no additional GPU kernel rerun was required.
• PR automation completed successfully; component lanes not selected for this documentation-only change were skipped as expected.

[therock-pr-bot]

✅ All Checks Passed — Ready for Review

Check	Status	Details
🌿 Branch Name	✅ Pass	—
📝 PR Title/Description	✅ Pass	—
⛔ Forbidden Files	✅ Pass	—
🧪 Unit Test	✅ Pass	PR does not contain code files — Unit Test auto-passed
🔎 pre-commit	✅ Pass	—
🚫 Draft PR	🔜 To Be Enabled	—
🚩 Feature Flag	🔜 To Be Enabled	—
📊 Code Coverage	🔜 To Be Enabled	—
🤖 therock-pr-bot	✅ Pass	—

🎉 All checks passed! This PR is ready for review.

📖 Need help? See the Policy FAQ for details on every check and how to fix failures.

[therock-pr-bot]

🎉 All checks passed! This PR is ready for review.

[Copilot]

Pull request overview

This PR refreshes the rocKE platform documentation set under rocke/platform/dsl_docs/ and reconciles assorted in-code docstrings/comments to match the current platform/library ownership split, architecture catalog, and supported workflows, while adding a point-in-time audit record for the documentation pass.

Changes:

• Edited and reconciled many dsl_docs/ pages to remove stale claims, update anchors/paths, and align with current code/tests/workflows.
• Updated docstrings/comments across several platform instance builders and helpers to reflect the current implemented behavior and boundaries.
• Added dsl_docs/AICK-1593_DOC_AUDIT.md as an audit inventory for the reviewed documentation set.

Reviewed changes

Copilot reviewed 91 out of 92 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
dnn-providers/hip-kernel-provider/rocke/platform/tests/instances/test_rocke_multiarch.py	Updates an in-test comment pointing to the schedule-hints case study.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/instances/common/transpose.py	Refreshes transpose instance docstring to reflect current transposed-LDS support and chosen generic path.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/instances/common/streamk_gemm.py	Updates StreamK GEMM documentation to reflect current MFMA/Atomic implementation notes.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/instances/common/mx_gemm.py	Rewrites MX GEMM docstring to match current MFMA + explicit scale application behavior and validator constraints.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/instances/common/matmul_nbits.py	Updates MatMulNBits module docstring to describe current dispatcher/bodies.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/instances/common/grouped_gemm.py	Updates grouped GEMM docs to reflect the shipped uniform-shape single-launch path and current boundaries.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/instances/common/gemm_universal.py	Updates schedule-hints comment to reference the current case-study numbering.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/instances/common/conv_direct_grouped.py	Adjusts comment references for refactor-opportunity tracking location.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/instances/common/block_scale_gemm.py	Rewrites block-scale GEMM docstring to match current supported subset/validator behavior.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/instances/common/batched_transpose.py	Updates batched transpose docstring to match current transposed-read support narrative.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/instances/common/batched_gemm.py	Updates docstring to reflect current SGPR scalarization behavior in universal GEMM.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/instances/common/_matmul_nbits_large_n.py	Updates large-N body docstring to reflect current unsupported features/boundaries.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/instances/common/_matmul_nbits_decode_gemv.py	Updates decode-GEMV body docstring to remove milestone phrasing.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/instances/common/_matmul_nbits_common.py	Updates common docstring/comments to reflect current supported families and host-side helpers.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/instances/init.py	Updates re-export documentation for grouped GEMM single-launch availability/boundaries.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/helpers/streamk.py	Updates StreamK helper module docstring to describe current consumer support accurately.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/helpers/reduction.py	Rewords welford_block_reduce docstring to reflect its actual two-moment implementation and guidance.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/helpers/README.md	Updates helper documentation for current module locations/ownership and removes stale roadmap prose.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/helpers/persistent.py	Updates persistent helper docstring wording and references.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/core/ir.py	Updates pin_sgpr docstring example to a current, representative usage pattern.
dnn-providers/hip-kernel-provider/rocke/platform/python/rocke/benchmark/gemm/fp16_rcr_sweep.py	Updates sweep harness docstring to point at the current optimization runbook.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/runtime/manifest_schema.md	Reconciles manifest schema docs with current rocKE naming, paths, and attention ownership.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/runtime/limitations.md	Updates runtime limitations with current multi-target catalog and multi-GPU stance/anchors.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/runtime/compile_launch_and_manifest.md	Updates compile/launch documentation with current paths and workflow anchors.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/runtime/comgr_and_hipmodule.md	Updates COMGR/HIP module docs to reflect the shared runtime coexistence resolver and platform-specific behaviors.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/reference/mfma_atom_catalog.md	Updates atom catalog docs to align with current ArchTarget/MMA catalogs and availability notes.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/reference/glossary.md	Updates glossary entries for target catalog, buffer descriptor facts, and wave-size notes.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/reference/env_flags.md	Updates environment flag documentation with corrected paths and ownership locations.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/reference/api_index.md	Updates curated API index to match current exports and the platform/library ownership split.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/README.md	Updates top-level docs README for rocKE platform scope, reading order, and current anchors.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/primitives/wave_and_cross_lane.md	Updates wave/cross-lane documentation to reflect current target catalog and examples.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/primitives/quantization.md	Updates quantization doc references for current module locations/ownership.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/primitives/intrinsics_and_primitives.md	Updates primitives inventory and references to current module layout and implemented boundaries.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/optimization/utilities/tools/dsl_probes/README.md	Updates probe documentation and paths to reflect current repo layout and invocation context.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/optimization/utilities/skills/kernel-launch-guide.md	Replaces stale “skill” stub with a maintained launch checklist and correct references.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/optimization/utilities/skills/isa-inspection-rocke.md	Updates ISA inspection guidance terminology, paths, and probe references.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/optimization/utilities/README.md	Updates optimization utilities overview to match current ownership and tool locations.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/optimization/runbook_mapping.md	Replaces large stale mapping content with a pointer to the maintained compliance map.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/optimization/arch/README.md	Updates arch-reference guidance to be grounded in current ArchTarget/backend/catalog sources.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/ir_lowering/lowering_pipeline.md	Removes stale compile-time estimates and updates target/wave-size descriptions.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/ir_lowering/backend_details.md	Updates backend details to match current target catalog, runtime resolver, and LLVM-flavor detection.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/instances/index.md	Rewrites instances index around platform/library ownership split and current support references.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/instances/gemm.md	Updates GEMM family documentation to reflect current grouped GEMM and StreamK implementation boundaries.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/instances/convolution.md	Updates convolution docs to remove unscoped perf claims and align with current code-visible levers and paths.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/fusion/overview.md	Minor wording update clarifying current attention fusion boundary.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/examples/index.md	Rewrites examples index around current platform example registry and library workflows.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/development/troubleshooting.md	Fixes links/paths and removes stale build-wrapper reference.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/development/setup_guide.md	Updates setup guide to include gfx1250 catalog entry and current constraints.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/development/refactor_opportunities.md	Replaces stale backlog-style prose with a grounded, current refactor-opportunities list.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/development/onboarding.md	Updates onboarding guide to remove stale perf numbers/paths and reflect current library ownership and workflows.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/development/extending.md	Updates extension guidance to the current examples registry and test structure (vs removed prototype wrappers).
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/development/engine_contributing.md	Removes obsolete guidance that permitted local Python/C++ drift; clarifies reference-tree mode as diagnostic only.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/autotune/overview.md	Updates autotune overview to avoid stale timing claims and reflect bounded retuning rationale.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/architecture/transform_dag.md	Corrects implementation anchor path for TensorDescriptor.offset.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/architecture/mental_model.md	Removes stale compile-time point estimates and updates target catalog description.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/architecture/kernel_taxonomy.md	Updates taxonomy to reflect current MFMA/WMMA/warp-body selection and ownership boundaries.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/architecture/index.md	Converts architecture index into a navigational page (no longer duplicating instance catalog content).
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/architecture/backend_support_agpr_res.md	Replaces proposal text with implemented AGPR allocation control interface, behavior, and tests.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/architecture/authoring_model.md	Updates authoring model to reflect platform vs library ownership and same-change parity requirements.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/architecture/attention_2d_gfx942_experiment_summary.md	Updates gfx942 experiment summary anchors/ownership paths and removes transient WIP-path dependencies.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/architecture/attention_2d_experiment_summary.md	Updates gfx950 experiment summary anchors to current library-owned kernel/benchmark paths.
dnn-providers/hip-kernel-provider/rocke/platform/dsl_docs/AICK-1593_DOC_AUDIT.md	Adds the point-in-time audit inventory and rationale summary for the docs refresh.
dnn-providers/hip-kernel-provider/rocke/library/kernels/common/sparse_attention.py	Updates sparse-attention docs to accurately describe current mask behavior (predicate after load).
dnn-providers/hip-kernel-provider/rocke/library/kernels/common/fmha_splitkv_decode.py	Marks use_mfma_body as a reserved compatibility field (no branching in current builder).
dnn-providers/hip-kernel-provider/rocke/library/kernels/common/fmha_mfma.py	Updates MFMA/WMMA portability description and explicitly documents gfx1250 rejection rationale.
dnn-providers/hip-kernel-provider/rocke/library/kernels/common/fmha_fwd_fp8.py	Updates FP8 FMHA doc/comments to reflect current dequant + narrow MFMA body and re-scoped tuning notes.
dnn-providers/hip-kernel-provider/rocke/library/kernels/common/fmha_bwd.py	Marks use_mfma_body as a reserved compatibility field (no branching in current builder).
dnn-providers/hip-kernel-provider/rocke/library/kernels/common/_fmha_warp_body.py	Updates boundary description to reflect current MFMA/WMMA callers and ownership split.
dnn-providers/hip-kernel-provider/rocke/library/kernels/common/_fmha_common.py	Updates internal-body references to match current organization and shared MFMA helper usage.

[tenpercent]

Addressed the Copilot path feedback in 50f008e6ffe7 and fixed the third occurrence of the same missing-dsl_docs/ prefix class in conv_direct_grouped.py.

Validation:

• Whole-source rocKE detector now reports zero references that resolve only after adding dsl_docs/.
• Black passed for all three changed Python files.
• git diff --check passed.
• GPU documentation verification was completed on parent commit 18808eb64f42 by Slurm job 67578417: a fresh sparse clone ran on an MI355X with a Kreb ROCm image and verify_dsl_docs.py reported 49 passed, 0 failed. Commit 50f008e6ffe7 changes comments only and does not alter runtime behavior.

[tenpercent]

GPU-programming expert follow-up landed in a260acafe91d.

The pass found and corrected a common class of issue: documentation/spec comments describing intended controls or architectural correlations as implemented behavior.

• Wave size is fixed by each ArchTarget; rocKE does not expose a wave32/wave64 switch. MFMA versus WMMA and atom legality come from ArchTarget.matrix_path / ArchTarget.mma. The current wave-size pairing is catalog correlation, not causation.
• The current LLVM wave_all lowering compares an i64 ballot with -1, so it is full-EXEC wave64-only; wave32 support is now recorded as implementation work.
• FP8 FMHA fallback is documented as an f16 activation/output contract. Accepting common.dtype="bf16" does not currently provide BF16+FP8 numeric behavior.
• Sparse attention no longer claims masking is mathematically identical to skipping. K/QK execute before score masking, and all-masked Jenga/VSA rows remain a numeric limitation.
• MX/block-scale per_input_row and the FMHA/sparse fields output_grad_dtype, prune_sliding_window, and use_wave_ballot_scatter are marked reserved/no-op with their actual current behavior.
• f16_4x4x4 and fp8_16x16x128 are identified as direct-emitter/global-helper exceptions absent from the per-target MmaCatalog; the bad ArchTarget.known_arches() reference was also corrected.

No runtime semantics changed. AST comparison after removing docstrings reports 0 semantic changes across all 29 Python files in the PR.

Current-head validation:

• committed-range pre-commit: passed;
• 256 tests passed, 15 skipped, 6 subtests passed;
• 3 focused attention documentation tests passed;
• 134 Markdown links, 244 documented imports, curated API index, and stale-prefix detector: all clean;
• git diff --check and Black on the newly touched Python files: passed.

GPU validation already completed for this PR remains applicable to the documented workflows: Slurm job 67578417 ran verify_dsl_docs.py on MI355X/Kreb (49 passed, 0 failed), and job 67579122 verified the README implicit-GEMM manifest (bad=0/1605632). Those runs did not validate wave32 wave_all, BF16+FP8 FMHA, all-masked sparse attention, or nonuniform row-scale GEMM; those gaps are now explicitly recorded rather than claimed as supported.

[tenpercent]

Factual-accuracy review of the current PR head (a92e1fdf6749bf6752725ba3dcf552605e944829):

Confirmed findings

1. Buffer-resource DW3 is described too broadly. dsl_docs/README.md says descriptors universally use 0x00027000. The value is selected by the exact gfx ISA backend: gfx9/gfx950 use 0x00027000, while gfx1151/gfx1201 use 0x31014000. gfx1250 is CDNA5/CDNA-family hardware on the GFX12 programming model; its current backend inherits 0x31014000, but the backend explicitly marks that SRD behavior as a bring-up placeholder pending the verified gfx1250 57-bit SRD model. The documentation should therefore key this property to the gfx backend, not infer it from CDNA/RDNA family labels, and should preserve the gfx1250 verification caveat.

2. Universal GEMM is not MFMA-only. architecture/kernel_taxonomy.md labels gemm_universal as MFMA even though its builder selects the target-supported MFMA or WMMA family and resolves the legal atom through the target catalog. The universal row and wrappers that truly inherit its path should say target-selected MFMA/WMMA.

3. The architecture index presents a proposal as current lowering. coordinate_address_planning.md explicitly proposes future APIs and rollout milestones, so the index should label it as a design proposal rather than "current" lowering documentation.

4. The AGPR capability is implemented, but its linked page is still written as future work. The index should distinguish the implemented capability from the historical implementation note until that page is refreshed.

5. The newly linked dual-backend RFC contains a stale gfx1250 classification. It calls gfx1250 RDNA4; the checked-in target catalog classifies it as family: cdna, target_family: gfx12_cdna.

Verified nuance

The statement that legal matrix atoms are target/catalog properties rather than consequences of wave width is architecturally correct. Some current builders use wave size as a family-selection shortcut because the checked-in targets correlate, but the target catalog remains the authority for legal atoms.

I am addressing these documentation findings in a follow-up commit on this PR.

[tenpercent]

Addressed the factual-review findings in 28c6295db939:

• document buffer-resource DW3 by exact gfx backend and retain the provisional gfx1250 57-bit-SRD caveat;
• identify gfx1250 as CDNA5 on the GFX12 programming model;
• describe universal GEMM and its wrappers as target-selected MFMA/WMMA paths;
• label address planning and other architecture pages by their actual implemented/proposed status;
• replace the stale AGPR task list with current engine-level implementation anchors, scope, tradeoffs, and remaining validation;
• correct the linked dual-backend RFC's gfx1250 classification.

Validation: pre-commit passed on all eight changed files, git diff --check passed, all local Markdown targets in the changed files resolve, and a targeted engine check confirmed AGPR attribute emission plus the (0, 0) COMGR option sequence. The PR description records the 534-line/eight-file bounded overflow justification and the earlier gfx950 Kreb validation. Current required summaries are passing; the hipDNN superbuild jobs are still pending.

[tenpercent]

Second factual-accuracy review of head 28c6295db93932fb43279741478bf23519ad0031 found four remaining issues:

Confirmed findings

1. gemm_multi_abd overstates implemented coverage. architecture/kernel_taxonomy.md describes multi-A/B with status ✓, but build_gemm_multi_abd() explicitly restricts v1 to one A and one B and raises NotImplementedError otherwise. The row should describe the implemented single-A/single-B subset and identify true multi-A/B as planned.

2. Additional target-polymorphic rows remain MFMA-only. batched_contraction delegates to batched/universal GEMM, conv_implicit_gemm explicitly resolves a restricted WMMA path on wave32 targets, and fused MoE selects universal-GEMM WMMA for gfx1250. Their taxonomy rows should reflect target-selected MFMA/WMMA, with narrower restrictions noted where relevant.

3. The AGPR page overstates validation parity. The Python formatter accepts a two-element pair or "min,max" and validates numeric conversion. The C++ formatter additionally accepts scalar integers and parses string components with strtol(..., NULL, ...), so it does not implement the same input validation. The page should describe corresponding formatting/emission and record the broader C++ parser.

Qualification needed

4. The README's OOB guarantee is broader than the gfx1250 evidence. The bullet correctly marks gfx1250's inherited SRD word as provisional, but its final sentence can still read as guaranteeing bounds-checked zero/drop behavior on gfx1250. The exact checked-in mappings should enumerate current targets (gfx90a/gfx942/gfx950, gfx11-generic/gfx1151/gfx1201) and scope the OOB guarantee to validated mappings; gfx1250 tail safety remains pending SRD validation.

I am addressing these documentation findings in a follow-up commit on this PR.

[tenpercent]

Addressed the second factual-review findings in 501ffd6390de:

• scope gemm_multi_abd to the implemented one-A/one-B v1 subset and mark true multi-A/B as planned;
• identify batched contraction, implicit-GEMM convolution, and per-expert fused MoE as target-selected MFMA/WMMA paths, preserving the restricted WMMA qualifier for convolution;
• document the broader C++ AGPR attribute parser instead of claiming Python/C++ input-validation parity;
• enumerate the exact checked-in SRD mappings and explicitly exclude gfx1250 from the established OOB tail-safety guarantee pending its 57-bit SRD validation.

Validation: pre-commit passed on all eight files, git diff --check passed, all local Markdown targets resolve, known_arches() produces the documented SRD mapping, and each taxonomy correction was traced to the owning validator/builder. The PR remains bounded at 546 changed lines across eight files; its description has been updated accordingly. GPU validation was not rerun because this commit changes documentation only.

[tenpercent]

A further factual-accuracy pass at head 501ffd6390de0bd41d881b85c6a5004c9b70e377 found several remaining source/document mismatches:

• kernel_taxonomy.md still labels attention_tiled_2d and attention_tiled_3d as MFMA-only, but the checked-in gfx1250 implementations are explicitly WMMA and resolve WMMA atoms. The rows should be target-specific.
• The non-matmul taxonomy still contains stale primitive descriptions despite now claiming that every row reflects the checked-in body. In particular, permute_nd uses no LDS; the norm/quant/reduce families use LDS or mixed warp/LDS reduction paths rather than the listed warp-only descriptions; and fmha_appendkv uses ordinary global loads/stores with optional rotary VALU work rather than pure DMA.
• authoring_model.md says every shipped kernel instance lives under platform/python/rocke/instances, while UnifiedAttentionProblem is library-owned under rocke/library/kernels/common/attention_unified.py. The ownership statement and example need to distinguish platform and library kernels.
• The GEMM/conv validation summary still says MFMA atom where the validators also accept WMMA atoms; this should say MMA or matrix atom.

These are source-confirmed documentation issues. I am addressing them in a follow-up commit and will rerun the documentation/static checks.

[tenpercent]

Addressed the latest factual-review findings in 2f9a37997d71:

• distinguish platform-owned instances from library-owned attention kernels and point UnifiedAttentionProblem to its actual library location;
• use MMA/matrix terminology for validators that accept either MFMA or WMMA atoms;
• describe tiled 2D/3D attention as architecture-specific MFMA or WMMA paths, including the checked-in gfx1250 WMMA implementations;
• replace the stale non-matmul taxonomy as a class: record the actual Welford/LDS, warp-plus-LDS, direct global gather/store, indexed load/store, atomic, and optional-rotary bodies;
• remove the incorrect quantitative MFMA reduction example and retain the code-grounded shape explanation.

Validation on the pushed commit:

• committed-range pre-commit passed;
• git diff --check passed;
• 39 CPU tests passed, 1 toolchain capability test skipped, and 6 subtests passed;
• 3 focused attention documentation tests passed;
• all local Markdown targets in the eight changed files resolve;
• the targeted stale-claim scan is clean, with the remaining MFMA-only attention rows corresponding to families whose validators reject WMMA targets.

The PR is now 598 changed lines across the same eight files, still within the documented eight-file overflow ceiling. GPU validation was not rerun because this commit changes documentation only; the earlier gfx950 Kreb verify_dsl_docs and README manifest validation remain applicable and are recorded in the PR test plan.

[tenpercent]

Follow-up factual-accuracy pass in 45d28b2a0a88:

• Separated two independent concepts throughout the authoring guidance: wave32/wave64 is compile-time execution geometry, while MFMA/WMMA availability and atom identity are capabilities of the exact gfx target and must be selected from its MmaCatalog. A wave-size choice must not be used to infer the matrix-instruction family, or vice versa.
• Scoped the matrix examples accordingly. The current builders validate their configured wave geometry against the target and selected MmaOp, while the matrix operation itself comes from the exact-gfx catalog.
• Corrected tiled-attention guidance: gfx942 uses narrow 16x16x16 MFMA atoms and ordinary strided LDS reads for the V operand; gfx950 variants may use target-specific transpose LDS reads and wider catalog atoms; gfx1250 selects its target-specific WMMA operations and separately compiles its current lane geometry for wave32.
• Corrected the non-matmul taxonomy to match the checked-in builders: pooling uses descriptor-driven buffer loads, top-k selects wave-XOR or LDS reduction by configured wave scope, and MoE sorting selects wave Kogge-Stone or LDS Hillis-Steele scan. Unsupported universal percentage/performance claims were removed.
• Clarified <project_root>, <platform_root>, and <library_root> so source paths, Python imports, and platform/library ownership are not conflated.

Validation: focused pre-commit hooks and git diff --check passed; the attention documentation lowering tests passed 3/3; the multi-architecture static/lowering suite passed 39 tests with one expected skip; exact-target catalog, referenced-path, and primitive-selection checks passed. The change is documentation-only and does not alter emitted kernels or runtime behavior.