Add: docs/ index and runtime capability survey

[ChaoWao]

Summary

docs/ had 35 files flat at its root with no index. The top-level README listed 10 of them, so the other 25 were discoverable only by grep, and four had no inbound link from anywhere in the repo (install.md, simt-launch.md, profiling-config-naming.md, sim_multi_device_isolation.md). Only investigations/ carried a README — dfx/ (12 files, 5,227 lines), troubleshooting/ (7) and hardware/ (4) had none. Root also keeps growing: #1453 adds a 36th file.

Three changes:

1. docs/README.md — indexes every root document and subdirectory, grouped by reader intent (Start here / Architecture / Kernels / Launch & linking / Multi-chip & comm / Profiling & DFX / Build & test / When something is broken). It also states the rule that a new doc registers there in the same commit, so the index does not silently fall behind. All four orphans are now reachable.
2. docs/capability-survey.md — a status snapshot of what is shipped, gated, or design-only across the level model (L2 chip → L4 host-to-host), the CANN launch surface for AICore/AICPU, and the communication engines. Every claim carries a file:line, and the page records its snapshot commit up front because status claims rot faster than architecture prose.
3. docs/dfx/ consolidation — moved profiling-framework.md, profiling-name-map.md and profiling-config-naming.md into docs/dfx/, plus a new docs/dfx/README.md index.

Why the profiling docs belong in dfx/

docs/dfx/ already held 12 profiling documents and already linked upward to these three nine times via ../profiling-framework.md / ../profiling-name-map.md. Their main consumer was the directory they were not in. Each had 0–1 external references, so the move is cheap.

logging.md deliberately stays at the docs/ root. PR #1475 modifies that file, and renaming it here would hand its author a rename-vs-modify conflict. It can follow once #1475 lands.

A full topical regrouping of the remaining root docs (architecture/, mechanisms/, guides/) is not in this PR: it would touch ~28 reference sites in .cpp/.h/.py/.yml plus .claude/rules/ and skills, and it collides with #1467 (6 core architecture docs), #1475 (9 docs) and #1453. The index captures the orientation benefit at none of that cost.

Drive-by fix, disclosed

docs/dfx/pmu-profiling.md — a file this PR already edits — had 7 broken links: 6 with the wrong relative depth (../src → ../../src), and profiling_copy.h, which moved to src/common/platform/include/host/ when #944 unified the collector framework. Same file, same defect class, individually verified.

Testing

Documentation only (.md); no code, build, or config files changed, so the sim/hardware suites do not apply per the git-commit skill's test matrix.

• markdownlint-cli2 clean across all 19 touched markdown files, using v0.20.0 — the version .pre-commit-config.yaml:83 pins, i.e. what CI runs
• Repo-wide relative-link validation: 13 broken links before → 5 after, and all 5 remaining are pre-existing, in files this PR does not touch (tests/st/**, tools/cann-examples/**, one false positive in troubleshooting/macos-build.md). This change introduces zero broken links
• Index completeness checked programmatically: every root doc appears in docs/README.md
• git detected all three moves as renames, so history is preserved
• Simulation tests — not applicable (no code changed)
• Hardware tests — not applicable (no code changed)

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3dcc3a9a-6f5a-4c35-8f2c-49888016e4ae

📥 Commits

Reviewing files that changed from the base of the PR and between cbbeb8c and 1b48318.

📒 Files selected for processing (10)

• README.md
• docs/README.md
• docs/capability-survey.md
• docs/dfx/README.md
• docs/dfx/args-dump.md
• docs/dfx/l2-swimlane-profiling.md
• docs/dfx/pmu-profiling.md
• docs/dfx/profiling-config-naming.md
• docs/dfx/profiling-framework.md
• docs/dfx/profiling-name-map.md

---

📝 Walkthrough

Walkthrough

The PR expands documentation navigation, adds a runtime capability survey covering topology, launch, and communication engines, creates a DFX documentation index, and corrects relative links across profiling documents.

Changes

Documentation navigation and status

Layer / File(s)	Summary
Documentation indexes README.md, docs/README.md, docs/dfx/README.md	Adds categorized documentation indexes and links the new capability survey from the root README.
Runtime capability survey docs/capability-survey.md	Documents runtime topology, CANN launch mechanics, communication engines, open questions, and documentation drift findings.
DFX documentation references docs/dfx/*.md	Corrects relative links to profiling documents, source headers, tracing documentation, and related references.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• hw-native-sys/simpler#1262: Updates related L2 swimlane and profiling-framework documentation links.

Poem

A bunny hops through docs so neat,
With surveyed paths and links complete.
DFX trails now point just right,
Capability stars shine bright.
“No broken hops!” the rabbit sings.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main documentation index and capability survey additions.
Description check	✅ Passed	The description is detailed and directly matches the documentation indexing, survey, and profiling-doc moves.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

---

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.}