[youngrok-XCENA]

Summary

After #107, readers encounter conflicting descriptions of CXL mapping, RDMA transfers, worker staging and cache sharing as they move from the homepage to installation, examples and detailed design. Some API and recovery descriptions also promise behavior the current backends do not provide.

Align those guides with the merged implementation, including the actual allocation/store sequence, distinct buffer lifetimes and backend-specific limits. Existing benchmark measurements remain unchanged and are scoped to the configurations actually measured.

Also restore this PR's test dependency installation: the package mirror advertises newer Ruff/virtualenv versions whose wheels return 404, so CI resolves against a known successful dependency snapshot.

Key Changes

• Show both cxl and remote_cxl payload paths in the primary README, homepage and architecture Mermaid diagrams, including GPU copies, worker CPU staging, RDMA and the memory-node agent. Keep directly mapped CXL diagrams under explicit backend headings.
• Connect backend selection to the appropriate examples. Distinguish worker-private cpu/current mixed storage from shared-pool reuse, and require compatible immutable weights, namespace, layout and pool for sharing.
• Align installation and examples: one Resource Manager per shared pool, an agent on every memory node, explicit service starts, and a constrained NIXL stack for the provided vLLM 0.22.1 example. Kernel importability alone does not prove that a serving request used packed CUDA copies.
• Replace the stale detailed GET_ACCESS illustration with a native Mermaid sequence for remote HOLD, NIC registration, deregistration, UNHOLD and region return. Separate server read leases, local staging leases and RM holds, including keeper retention, revocation of server leases during reclamation, and uncertain cleanup.
• Correct context-manager connection timing, supported Handler operations, DAX plugin callback scope, metadata-only health checks and the caller's responsibility to finish writes before registration. Update the generated API docstrings as well; execution logic and signatures are unchanged.
• Remove unconditional no-data-loss and lock-free claims. Separate RM allocation-ledger recovery from volatile key/session metadata and backend-specific cache availability.
• Preserve all 24 documentation image assets, benchmark numeric rows and numbered figure captions. Limit the performance comparison to the reported single-node cxl / TCP-loopback P2P setup; it does not establish remote_cxl performance or a general RDMA advantage.
• Repair heading cross-references and generated API source links so the complete documentation builds without warnings or broken local targets. Preserve Mermaid aspect ratios instead of shrinking long sequences into a fixed 500 px height.
• Apply the same 27-package CI constraints to the dev and dev/vLLM installs, preserving the existing Nexus route, Python matrix, Resource Manager tests and required aggregate gate. Product dependency declarations and the vLLM requirement are unchanged.

Test Plan

• Unit tests added/updated
• Existing tests pass (pytest -v)
• E2E tests (if applicable)
• Clean strict Sphinx build: sphinx-build -E -W --keep-going -b html docs <output>; all 28 source pages build with zero warnings.
• Local targets and fragments checked across all 33 generated HTML files: zero broken links; Python documentation snippets parse.
• Chromium renders all 28 pages at 390 and 1440 px (56 cases, 80 diagram renders): no Mermaid errors, missing images or page overflow. New mapping/return and region-lifecycle diagrams inspected visually.
• The new sequence's desktop labels render at about 12 px instead of 7.4 px; fullscreen open/close works at both widths. Narrow screens still scale diagrams to fit and can use browser zoom.
• All 24 image assets, historical benchmark numeric rows and numbered figure captions preserved byte-for-byte/as text.
• Product Python ASTs match main after excluding docstrings; Ruff check/format and git diff --check pass.
• The two CI files match the validated dependency fix from ci: constrain test dependencies to a working mirror snapshot #125. Python 3.12/3.13/3.14 installs using separate empty caches and the existing Nexus proxy succeeded; workflow YAML and unchanged test gates were checked.

The diff contains 31 Markdown files, Sphinx configuration, two Python files with docstring-only edits, and two CI files. Physical-device and serving tests were not rerun. The combined head runs its own CI; the earlier green #125 run establishes the dependency patch's validation history, not a test result for this new head. This PR remains Draft pending user approval.

Related Issues

Follow-up to #107. Includes and supersedes the CI repair previously proposed in #125.

📦 Release Note (for auto-generation / write in English)

NEW

• Native Mermaid explanations of remote region registration/return and distinct buffer lifetimes.

CHANGED

• Public backend, setup, API, recovery and performance guides describe the current implementation and validation boundaries consistently.

FIXED

• Correct misleading zero-copy, sharing, startup and recovery claims, and broken generated documentation links.
• Restore CI dependency installation using package versions available through the existing mirror.

IMPORTANT NOTES

• Storage behavior, API signatures and benchmark measurements are unchanged. Documentation is deployed after merge by the existing Pages workflow.