[rwgk]

Description

While researching the shared agent-skills proposal in #3192, we found stale contributor guidance in the bindings and core documentation. Correct it immediately so contributors and agents can follow the current paths, commands, and runtime contracts while the broader skills proposal is discussed.

• Correct the bindings legacy-test, Cython-test, and sample paths; use the existing Pixi sample task and link to the maintained Python/C++ benchmark instructions.
• Distinguish Python host callbacks and GIL-taking owner cleanup from CUDA user-object destructor callbacks, which enqueue deferred cleanup without acquiring the GIL. Align the core agent guidance and runtime design document.
• Correct typing.TYPE_CHECK to typing.TYPE_CHECKING.

Related to #3192; the shared skills infrastructure remains tracked there. This PR changes documentation only.

Validation

• pre-commit run --files cuda_bindings_13/AGENTS.md cuda_bindings_13/README.md cuda_core/AGENTS.md cuda_core/cuda/core/_cpp/rt/DESIGN.md: passed, including link checks.
• git diff --check: passed.
• Verified the guidance against the current test directories, Pixi tasks, host callback trampoline, and deferred-cleanup implementation. No runtime tests or benchmarks were needed for these documentation-only changes.

Review And CI

Ready for human review. Kept in draft to retain manual control over triggering full CI.

Checklist

• Validation appropriate to these documentation-only changes is complete.
• The documentation is up to date with these changes.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Source mode: Auto
• Repository: NVIDIA/cuda-python
• Branch: main
• File: .coderabbit.yaml
• Commit: afa6249
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Enterprise
• Run ID: 87cfa985-e6aa-46ba-bb1f-e79d66c59d68

📥 Commits

Reviewing files that changed from the base of the PR and between afa6249 and ba1451c.

📒 Files selected for processing: 4

• cuda_bindings_13/AGENTS.md
• cuda_bindings_13/README.md
• cuda_core/AGENTS.md
• cuda_core/cuda/core/_cpp/rt/DESIGN.md

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 10 remain after this review.

📝 Summary

Summary by CodeRabbit

• Documentation
  • Updated testing guidance to point to the current sample coverage and Cython test locations, with instructions for running sample tests.
  • Revised sample and benchmark documentation with links to examples, benchmark environments, commands, and result comparisons.
  • Clarified guidance on CUDA callback behavior, including restrictions on driver calls, GIL acquisition, and Python-object access in user-object destructor callbacks.

The pull request updates bindings test, sample, and benchmark documentation. It also clarifies core guidance on GIL use and deferred cleanup for CUDA user-object destructor callbacks, and corrects a type-checking import reference.

Changes: Bindings test and benchmark guidance

Layer / File(s)	Summary
Test and sample instructions cuda_bindings_13/AGENTS.md, cuda_bindings_13/README.md	The guidance points to updated Cython and legacy-test paths, sample documentation, and the pixi run test-samples command.
Benchmark instructions cuda_bindings_13/AGENTS.md, cuda_bindings_13/README.md	The benchmark guidance links to Python and C++ benchmark resources and Pixi task instructions.

Core callback and GIL guidance

Layer / File(s)	Summary
Callback and type-checking guidance cuda_core/AGENTS.md, cuda_core/cuda/core/_cpp/rt/DESIGN.md	The documentation identifies paths that may acquire the GIL and states that CUDA user-object destructor callbacks defer cleanup without acquiring the GIL, accessing Python objects, or calling the driver. It also corrects typing.TYPE_CHECKING.

Possibly related issues

• NVIDIA/cuda-python#3192: Both changes update bindings and core agent guidance. This pull request does not add the shared skills layout.

Suggested reviewers: mdboom

Priority: ⬇️ Low

Change: Other

Merge Risk: ⚪ Minimal · up to ba145

The documentation updates are mergeable with no identified implementation risk.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

[rwgk]

Thanks @Andy-Jost!