Reorganize physical backend documentation

[AntoineRichard]

Description

Reorganizes the physical backend documentation by content type:

• Concepts now owns backend selection, architecture, backend identities, and solver differences.
• How-to guides own Newton asset preparation, MJWarp and Kamino tuning, policy transfer, and native physics API lifecycles.
• The developer guide owns adding a physics backend.
• Canonical installation and generated API pages remain the sources of truth for setup and configuration details.
• Legacy landing, installation, configuration, and supported-feature pages are removed after migrating their durable content and repository links.
• Backend-related user skills are synchronized with the new authoritative pages.

No runtime behavior, public API, dependency, or installation behavior changes are included.

Type of change

• Documentation update

Screenshots

Not applicable; this is an information-architecture and prose update.

Release backport

• Backport this pull request to the active release branch after it merges into develop

Validation

• Warnings-as-errors Sphinx dummy build passed with zero warnings.
• Skill validation passed for all 21 skills.
• Repository-wide pre-commit checks passed.
• Branch diff checks passed.
• Required labels are unique and stale backend-document paths are absent.

Checklist

• I have run the pre-commit checks with ./isaaclab.sh -f.
• I have made corresponding changes to the documentation.
• My changes generate no new warnings.
• Code tests are not applicable because this change is documentation-only.
• A package changelog fragment is not applicable because no package is touched.
• I have read and understood the contribution guidelines.
• I have added my name to CONTRIBUTORS.md or my name already exists there.

[greptile-apps]

Greptile Summary

The PR reorganizes physical-backend documentation into concepts, task-oriented how-to guides, and developer guidance, while synchronizing backend-related user skills.

• Adds consolidated backend architecture, identity, solver-comparison, asset-preparation, tuning, policy-transfer, and native-API documentation.
• Removes legacy backend landing and setup pages and updates internal navigation and references.
• Excludes local design specifications from Sphinx source discovery.
• Leaves legacy published page URLs without redirects to their replacement content.

Confidence Score: 4/5

The documentation reorganization should not merge until legacy backend-page URLs redirect to their replacement content.

Internal references resolve, but moving and deleting published Sphinx pages without aliases causes existing bookmarks, search results, and external links to return 404 responses.

Files Needing Attention: docs/source/how-to/native_physics_api/index.rst and the documentation redirect configuration

Important Files Changed

Filename	Overview
docs/conf.py	Excludes local superpowers design documents from Sphinx, but adds no redirect facility for removed public pages.
docs/index.rst	Adds the consolidated backend concept pages to top-level documentation navigation.
docs/source/concepts/physics_backends.rst	Introduces the canonical overview of backend identities, requirements, maturity, and solver families.
docs/source/concepts/backend_architecture.rst	Consolidates factory dispatch, lifecycle, portable interfaces, and native-access boundaries.
docs/source/how-to/index.rst	Adds a physics-backend how-to section whose files and cross-reference labels resolve.
docs/source/how-to/native_physics_api/index.rst	Moves native API guidance to its new canonical location without preserving the former published URL.
skills/user/select-backends/SKILL.md	Synchronizes backend-selection skill guidance with the new concepts documentation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Legacy[Legacy backend pages] --> Concepts[Concepts: selection, architecture, identities, solvers]
    Legacy --> HowTo[How-to: preparation, tuning, transfer, native APIs]
    Legacy --> Developer[Developer guide: adding a backend]
    Concepts --> Skills[Backend user skills]
    HowTo --> Skills

Loading

_{Reviews (1): Last reviewed commit: "Clarify physical backend concepts" | Re-trigger Greptile}

[greptile-apps]

Legacy page redirects are missing

When users follow previously published physical-backend or direct-API URLs, the moved and deleted pages have no aliases or per-page redirects, causing bookmarks, search results, and external links to return 404 responses instead of reaching the reorganized content.

[isaaclab-review-bot]

Isaac Lab Review Bot

The documentation reorganization is coherent, but the PR also commits a hidden design-plan artifact under docs/superpowers/, contrary to the repository rule against committing generated plans or agent artifacts.

• Design and architecture: The content is sensibly divided among Concepts, How-to, and Developer Guide pages, with legacy backend material routed through updated toctrees and references. Before merge, remove the committed docs/superpowers/specs/2026-08-13-physical-backend-docs-reorganization-design.md plan and its dedicated Sphinx exclusion.
• API: No public runtime API changes are introduced. The documentation compatibility surface includes preserved labels for the moved MJWarp and Kamino pages and updated references to the new backend architecture, physics backend, solver differences, and native API locations.
• Implementation: The moved and deleted documentation paths are generally integrated consistently, including skill references and the renamed native-physics API tree. The remaining issue is the 208-line implementation plan committed beneath docs/superpowers/ and hidden via exclude_patterns; it pins transient implementation context and should not remain as an unbuilt repository artifact.

Minor fixes needed. Posted 1 actionable finding inline.

Automated review; human maintainers own approval decisions.

[isaaclab-review-bot]

🟡 Warning · Design Architecture — Committed plan artifact excluded from docs build

This 208-line design/plan document is an agent artifact, and docs/conf.py adds superpowers/** to exclude_patterns solely so Sphinx ignores it. Repository guidelines state not to commit generated plans, scratch files, or agent artifacts. It pins a base commit SHA and a page inventory, so it will silently drift from the pages it describes while living permanently under docs/. Remove the file and the accompanying exclusion.

[mmichelis]

Why is this folder name with underscore while others are with dash?

[kellyguo11]

were these intended to be added?