docs: enhance README based on community feedback (#32)

- Add system requirements (Python 3.12, ≥24GB GPU VRAM)
- Add HuggingFace CLI setup instructions
- Add FAQ section addressing common questions
- Clarify relationship with paper (what's included vs. not)
- Add citation section

Addresses feedback from GitHub issues #12, #19, #30.

Author: super-anova

README.md

@@ -12,6 +12,21 @@
 
 _Note: Following the release of [NVIDIA Alpamayo](https://nvidianews.nvidia.com/news/alpamayo-autonomous-vehicle-development) at CES 2026, Alpamayo-R1 has been renamed to Alpamayo 1._
 
+> **📖 Please read the [HuggingFace Model Card](https://huggingface.co/nvidia/Alpamayo-R1-10B) first!**
+> The model card contains comprehensive details on model architecture, inputs/outputs, licensing, and tested hardware configurations. This GitHub README focuses on setup, usage, and frequently asked questions.
+
+## Requirements
+
+| Requirement | Specification |
+|-------------|---------------|
+| **Python** | 3.12.x (see `pyproject.toml`) |
+| **GPU** | NVIDIA GPU with ≥24 GB VRAM (e.g., RTX 3090, RTX 4090, A5000, H100) |
+| **OS** | Linux (tested); other platforms unverified |
+
+> ⚠️ **Note**: GPUs with less than 24 GB VRAM will likely encounter CUDA out-of-memory errors.
+
+## Installation
+
 ### 1. Install uv (if not already installed)
 
 ```bash
@@ -33,13 +48,19 @@ The model requires access to gated resources. Request access here:
 - 🤗 [Physical AI AV Dataset](https://huggingface.co/datasets/nvidia/PhysicalAI-Autonomous-Vehicles)
 - 🤗 [Alpamayo Model Weights](https://huggingface.co/nvidia/Alpamayo-R1-10B)
 
-Then authenticate:
+Then authenticate using the HuggingFace CLI:
 
 ```bash
-hf auth login
+# Install huggingface-cli if not already installed (included in transformers)
+pip install huggingface_hub
+
+# Login with your token
+huggingface-cli login
 ```
 
-Get your token at: https://huggingface.co/settings/tokens
+Get your access token at: https://huggingface.co/settings/tokens
+
+> 💡 **Tip**: For more details on HuggingFace authentication, see the [official documentation](https://huggingface.co/docs/huggingface_hub/guides/cli).
 
 ## Running Inference
 
@@ -60,6 +81,59 @@ the `num_traj_samples=1` argument to a higher number (Line 60).
 
 We provide a notebook with similar inference code at `notebook/inference.ipynb`.
 
+## Relationship with the Paper
+
+Alpamayo 1 implements the architecture described in our paper [*"Alpamayo-R1: Bridging Reasoning and Action Prediction for Generalizable Autonomous Driving in the Long Tail
+"*](https://arxiv.org/abs/2511.00088), including:
+
+| Feature | Paper Description | This Release (v1.0) |
+|---------|-------------------|---------------------|
+| **Chain-of-Causation (CoC) reasoning** | Hybrid auto-labeling with human in the loop for reasoning traces | ✅ Included |
+| **Vision-Language-Action architecture** | Cosmos-Reason backbone + action expert | ✅ Included |
+| **Trajectory prediction** | 6.4s horizon, 64 waypoints at 10 Hz | ✅ Included |
+| **RL post-training** | Reinforcement learning for reasoning/action consistency | ❌ Not in this release |
+| **Route/navigation conditioning** | Explicit navigation or route inputs | ❌ Not in this release |
+| **Meta-actions/General VQA** | High-level behavior and visual question answering | ❌ Not in this release |
+
+The current release focuses on the core supervised learning components. RL post-training and route conditioning are potential candidates for future releases. Stay tuned!
+
+## Frequently Asked Questions (FAQ)
+
+<details>
+<summary><strong>Does the 10B model accept navigation/route inputs?</strong></summary>
+
+While we have experimented with route conditioning capabilities, the released model does **not** include this feature. The current release takes multi-camera video and egomotion history as inputs, without explicit navigation or route inputs (e.g., waypoints, turn-by-turn navigation instructions).
+
+</details>
+
+<details>
+<summary><strong>Does the model produce meta-actions or support general VQA?</strong></summary>
+
+While we have experimented with meta-action and general VQA capabilities, the released model does **not** include these features. Alpamayo 1 is designed specifically for trajectory prediction with Chain-of-Causation reasoning, producing trajectory + reasoning trace outputs.
+
+</details>
+
+<details>
+<summary><strong>Was the 10B model post-trained with Reinforcement Learning (RL)?</strong></summary>
+
+No. The current 10B model release has **not** undergone RL post-training. While the paper describes RL stages for improving reasoning quality and action consistency, this release focuses on the supervised learning components. As mentioned above, we may release RL post-trained models in future releases.
+
+</details>
+
+<details>
+<summary><strong>What are the minimum GPU requirements?</strong></summary>
+
+You need an NVIDIA GPU with at least **24 GB VRAM** for inference. Tested configurations include RTX 3090, A100, and H100. Running on GPUs with less memory (e.g., 16 GB) will likely result in CUDA out-of-memory errors.
+
+</details>
+
+<details>
+<summary><strong>Can I use this model in production / commercial applications?</strong></summary>
+
+No. The model weights are released under a **non-commercial license**. This release is intended for research, experimentation, and evaluation purposes only. See the [License](#license) section and the [HuggingFace Model Card](https://huggingface.co/nvidia/Alpamayo-R1-10B) for details.
+
+</details>
+
 ## Project Structure
 
 ```
@@ -96,9 +170,17 @@ The model uses Flash Attention 2 by default. If you encounter compatibility issu
 config.attn_implementation = "sdpa"
 ```
 
+### CUDA out-of-memory errors
+
+If you encounter OOM errors:
+1. Ensure you have a GPU with at least 24 GB VRAM
+2. Reduce `num_traj_samples` if generating multiple trajectories
+3. Close other GPU-intensive applications
+
 ## License
 
-Apache License 2.0 - see [LICENSE](./LICENSE) for details.
+- **Inference code**: Apache License 2.0 - see [LICENSE](./LICENSE) for details.
+- **Model weights**: Non-commercial license - see [HuggingFace Model Card](https://huggingface.co/nvidia/Alpamayo-R1-10B) for details.
 
 ## Disclaimer
 
@@ -110,3 +192,16 @@ Important notes:
 - Alpamayo 1 is not a fully fledged driving stack. Among other limitations, it lacks access to critical real-world sensor inputs, does not incorporate required diverse and redundant safety mechanisms, and has not undergone automotive-grade validation for deployment.
 
 By using this model, you acknowledge that it is a research tool intended to support scientific inquiry, benchmarking, and exploration—not a substitute for a certified AV stack. The developers and contributors disclaim any responsibility or liability for the use of the model or its outputs.
+
+## Citation
+
+If you use Alpamayo 1 in your research, please cite:
+
+```bibtex
+@article{nvidia2025alpamayo,
+      title={{Alpamayo-R1}: Bridging Reasoning and Action Prediction for Generalizable Autonomous Driving in the Long Tail},
+      author={NVIDIA and Yan Wang and Wenjie Luo and Junjie Bai and Yulong Cao and Tong Che and Ke Chen and Yuxiao Chen and Jenna Diamond and Yifan Ding and Wenhao Ding and Liang Feng and Greg Heinrich and Jack Huang and Peter Karkus and Boyi Li and Pinyi Li and Tsung-Yi Lin and Dongran Liu and Ming-Yu Liu and Langechuan Liu and Zhijian Liu and Jason Lu and Yunxiang Mao and Pavlo Molchanov and Lindsey Pavao and Zhenghao Peng and Mike Ranzinger and Ed Schmerling and Shida Shen and Yunfei Shi and Sarah Tariq and Ran Tian and Tilman Wekel and Xinshuo Weng and Tianjun Xiao and Eric Yang and Xiaodong Yang and Yurong You and Xiaohui Zeng and Wenyuan Zhang and Boris Ivanovic and Marco Pavone},
+      year={2025},
+      journal={arXiv preprint arXiv:2511.00088},
+}
+```