docs(isaac): backend reference + Phase 1 status banner (5/5 of #31 split)

[yinsong1986]

Summary

Part 5 / 5 of the split of #31 — tracked by #42.

Adds the user-facing reference doc for the Isaac backend plus the companion test file that pins R2's "Phase 1 status" disclosure banner. Branched off PR-1 (#44); rebases cleanly onto main once PR-1 merges. Parallel-mergeable with PR-4 (#47) — no code dependency on simulation.py.

What's in this slice

File	Status	LOC	Purpose
docs/backends/isaac.md	new	208	Install + Quick Start + API reference + R2's Phase 1 status banner
strands_robots_sim/isaac/tests/test_phase1_doc_banner.py	new (~75 LOC, 3 tests)	75	Carved from cagataycali's test_phase1_doc_honesty.py::TestIsaacDocsPhase1Banner; pins the banner content + ordering

R2 review-fix carry-over

R2 (commit 85e180f on #31) added a "Phase 1 status" banner to docs/backends/isaac.md between Overview and Installation. The banner discloses that the Phase 1 skeleton silently no-ops the data plane:

• add_robot (procedural branch)
• _load_usd_robot / _load_urdf_robot
• add_object
• add_camera
• replicate

…all return status: "success" without instantiating the underlying USD prim or articulation handle. The observable downstream effect: get_observation() returns {} and render() returns blank frames.

Reviewer asked for this explicitly so a user following the Quick Start sees the disclaimer before following the documented call sequence — the banner sits before the ## Installation heading.

Why split test_phase1_doc_honesty.py

The original test file mixed two concerns:

Source class	New file	Lands in
TestG1DOFCount (3 tests)	tests/test_procedural_g1_dof.py	PR-3 (#46)
TestIsaacDocsPhase1Banner (3 tests)	tests/test_phase1_doc_banner.py	This PR (5/5)

Splitting keeps each parallel-mergeable slice CI-green standalone. Shipping the original combined file in either PR would couple them (PR-3 would CI-red until PR-5 lands, or vice versa). Combined coverage equals the original file.

CI signal

• hatch run lint (black --check / isort --check-only / flake8 over strands_robots_sim/ + examples/) — clean.
• pytest strands_robots_sim/isaac/tests/test_phase1_doc_banner.py -v → 3 passed.
• The 3 tests verify (a) the doc file exists at the expected path, (b) the "Phase 1 status" banner precedes the ## Installation heading, (c) the banner enumerates add_robot, replicate, get_observation by name.

Dependency chain

PR-1 (#44, foundation) → PR-5 (this), parallel with PR-4 (#47, simulation). This is the closing slice — when PR-5 lands and #31 is closed, the umbrella tracker #42 closes too.

Diff: 2 files, +288 / 0 LOC.

Original authorship

Original work by @cagataycali in #31 (413ff15..85e180f). This slice cherry-picks docs/backends/isaac.md plus the carved-out banner test file. R2's banner addition (commit 85e180f) is already baked into this doc.

[cagataycali]

Local review on Thor — 3/3 pin tests pass ✅, docs are accurate

Verified locally:

• pytest strands_robots_sim/isaac/tests/test_phase1_doc_banner.py -v → 3 passed
• Banner sits between Overview and Installation ✅ (line 17, before ## Installation at line 21)
• Banner enumerates the silent-success methods correctly: add_robot (procedural branch), _load_usd_robot, _load_urdf_robot, add_object, add_camera, replicate ✅
• Banner names downstream effects: get_observation() returns {}, render() returns blank frames ✅
• render_mode enum in docs matches config.py: headless / rtx_realtime / rtx_pathtracing ✅

What's good ✅

• 3-test pin file is well-scoped (file existence, banner-precedes-installation ordering, method enumeration)
• Quick Start sequence matches the actual IsaacSimulation API surface in #47
• Phase 1 status disclosure is upfront and honest — exactly what R2's review feedback asked for
• Install paths cover all three real install vectors (Launcher / Isaac Lab / Docker)

Minor nit

Line 73: render_mode="rtx_realtime" in the Quick Start. Combined with headless=True, this is valid but a bit confusing because "headless" is also a render_mode value. A headless=True, render_mode="rtx_realtime" combo means "run with no GUI but still rasterize for camera renders". Worth a one-liner clarifying that headless controls the viewer, render_mode controls camera-render quality. Not blocking.

Mergeability

✅ Mergeable as-is once #44 lands. No code dependency on #47, so this can land in parallel with PR-4 (as the PR description correctly states).

[yinsong1986]

Rebased onto pr1/isaac-foundation at c7e2e5e (PR #44's R1 fix that ports the 10 surface tests + adds pytest>=7.0 to [isaac] extra + flips hatch run test to pytest). Pushed as a force-update with --force-with-lease.

SHA shift on this branch:

	Before	After
docs(isaac): backend reference + Phase 1 status banner …	9c18e83	e811fec

Same content; rebased commit object only. No parallel-session activity on this branch.

Local verification post-rebase:

$ pytest strands_robots_sim/isaac/tests/ -v
… 13 passed in 0.15s   # 10 surface tests from PR-1 + 3 doc-banner tests
$ black --check strands_robots_sim   # clean
$ isort --check-only --profile black --line-length 120 strands_robots_sim   # clean
$ flake8 --max-line-length=120 strands_robots_sim   # clean

PR is approved by @cagataycali and mergeable_state: clean against the new base. After PR-1 (#44) merges to main, this trivially fast-forwards. Awaiting #44's merge before this can land per the dependency chain in #42.

[yinsong1986]

Two-part update: conflict resolved + doc content aligned with what's now in main.

1. Conflict resolved

Rebased onto current main (06fce4d, now includes the squash-merges of #44 / #45 / #46 / #47 / #51) — pushed as --force-with-lease.

	Before	After
Branch HEAD	e811fec	76c3b1f

The interactive rebase dropped 2 commits already in main via PR #44's squash:

• 3a0a854 (foundation __init__ + pyproject.toml) → in PR feat(isaac): [isaac] extras + entry-point + PEP 562 lazy import (1/5 of #31 split) #44's squash
• c7e2e5e (R1 surface tests for PR feat(isaac): [isaac] extras + entry-point + PEP 562 lazy import (1/5 of #31 split) #44) → in PR feat(isaac): [isaac] extras + entry-point + PEP 562 lazy import (1/5 of #31 split) #44's squash

The remaining 2 commits replayed cleanly with zero conflicts:

#	SHA (new)	Title
1	a94150b	docs(isaac): backend reference + Phase 1 status banner (5/5 of #31 split)
2	76c3b1f	docs(isaac): align with PR #47 + PR #51 merged to main

mergeable_state flipped from dirty → blocked (just reviews now).

2. Doc content updated for the post-#47 / #51 state

The Phase 1 status banner in the original e811fec was accurate for the day it was written — but IsaacSimulation (PR #47) and the loaders module (PR #51) merged in the meantime, so several "silent no-op" claims drifted. Commit 76c3b1f brings three sections in line with what actually shipped:

Phase 1 status banner — split into "Working today" (config, is_available, lifecycle, procedural builders, loaders module) vs "Still no-op" (add_object, add_camera, replicate, the per-IsaacSimulation _load_usd_robot / _load_urdf_robot stubs, articulation-touching paths under get_observation / send_action / render). The test_phase1_doc_banner.py pin still passes against the rewrite — the same enumerated method names anchor the contract test.

New "Loading External Description Files (URDF / MJCF / USD)" section — documents isaac.loaders.load_urdf / load_mjcf / load_usd (PR #51): three load_*() functions producing ProceduralRobot dataclass instances, shared failure semantics (FileNotFoundError / ValueError, never silent phantom robot), and the parity-test pin against the seven robosuite-bundled MJCFs the strands-robots LIBERO adapter consumes.

Procedural Robots + Architecture file-list — added the G1 intermediate-link-bodies explanation, the fail-first kinematic-tree guard contract (PR #51's 3eeab25 commit), _install.py (PR #47's centralised install hints), and the actual test files now in main (instead of the placeholder list).

Diff on this commit alone: docs/backends/isaac.md, +51 / -7 LOC.

3. Companion PR for top-level docs

The same drift exists on README.md and examples/MIGRATION.md (Stage 3 framed as "future", rtx_mode='path_traced' kwarg that would TypeError against IsaacConfig's actual render_mode field, R5/R6/R7 checkboxes still unchecked). Filed PR #54 as the top-level sibling — same kind of post-merge alignment as PR #36 did for examples/README.md after #26 merged.

This PR (#48, the canonical home for docs/backends/isaac.md) and PR #54 (top-level README + MIGRATION) together bring all three doc surfaces in sync. They can land independently in either order — no code dependency.

Verification post-rebase + doc update

$ pytest strands_robots_sim/isaac/tests/test_phase1_doc_banner.py -v
3 passed in 0.11s
$ black --check strands_robots_sim       # clean
$ isort --check-only --profile black --line-length 120 strands_robots_sim   # clean
$ flake8 --max-line-length=120 strands_robots_sim   # clean

[cagataycali]

Approve — rebased cleanly + content rewrite verified against main

My earlier R1 approve (2026-05-26T01:40:34Z, dismissed by force-push) covered the original a94150b content. Re-reviewing the rebased branch (76c3b1f) which adds the post-#47 / #51 alignment commit.

Rebase is clean

Dropped 3a0a854 and c7e2e5e (foundation + R1 surface tests, both now in main via PR #44's squash). Two commits replayed with zero conflicts. Branch is now MERGEABLE.

76c3b1f content rewrite — verified accurate against main @ 06fce4d

Phase 1 status banner restructure (Working today vs Still no-op):

• "Working today" enumeration matches code: IsaacConfig (config.py), is_available() (simulation.py), lifecycle methods (PR #47), procedural builders for so100 / panda / unitree_g1 (procedural.py), and the isaac.loaders module with load_urdf / load_mjcf / load_usd (loaders.py lines 157 / 367 / 576).
• "Still no-op" enumeration matches simulation.py stubs: add_object, add_camera, replicate, the per-IsaacSimulation _load_usd_robot / _load_urdf_robot private methods, and articulation-touching paths under get_observation / send_action / render.
• Identical to PR #54's framing — three doc surfaces stay in sync.

New "Loading External Description Files" section:

• Documents the three loader functions accurately (ProceduralRobot return type, shared failure semantics: FileNotFoundError for missing files, ValueError for malformed input — never silent phantom robot).
• Parity-test pin against the seven robosuite-bundled MJCFs is consistent with the LIBERO adapter's actual asset list.

Procedural Robots + Architecture file-list:

• G1 intermediate-link-bodies explanation matches the actual G1 builder's body construction.
• _install.py reference is accurate (PR #47 centralised the install hints there).
• Test file list matches what's actually under strands_robots_sim/isaac/tests/ on main (no longer the placeholder list).

Banner contract test still passes against the rewrite

$ python -m pytest strands_robots_sim/isaac/tests/test_phase1_doc_banner.py -v
strands_robots_sim/isaac/tests/test_phase1_doc_banner.py::TestIsaacDocsPhase1Banner::test_isaac_docs_file_exists PASSED
strands_robots_sim/isaac/tests/test_phase1_doc_banner.py::TestIsaacDocsPhase1Banner::test_phase1_banner_present_before_installation PASSED
strands_robots_sim/isaac/tests/test_phase1_doc_banner.py::TestIsaacDocsPhase1Banner::test_phase1_banner_names_the_silent_methods PASSED
3 passed in 0.02s

The pin survives the rewrite because the same enumerated method names (add_robot, replicate, get_observation) anchor the contract test — the test asks for method-name presence, not exact wording. Good test design choice on the original split.

Render-mode field name now consistent

The rewritten Quick Start uses render_mode="rtx_pathtracing", matching IsaacConfig.render_mode (config.py:67) and the same fix landing in PR #54 for the top-level docs. No more rtx_mode drift anywhere.

headless vs render_mode clarification

The minor nit from my R1 review (overlap between headless=True and render_mode="rtx_realtime") didn't block then and doesn't block now — Phase 2 work is the right place to clean up the headless / render_mode interaction docs once the camera-render path is actually wired. Filing as a follow-up not blocking this docs PR.

Mergeability

MERGEABLE against current main. No code dependency on PR #54 — the two PRs land independently. Re-approving.