AMDResearch · KerwinTsaiii · Jun 5, 2026 · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026
diff --git a/source/_static/images/user-guide/code-server-main-interface.png b/source/_static/images/user-guide/code-server-main-interface.png
diff --git a/source/_static/images/user-guide/code-server-selection.png b/source/_static/images/user-guide/code-server-selection.png
diff --git a/source/_static/images/user-guide/extensions-panel.png b/source/_static/images/user-guide/extensions-panel.png
diff --git a/source/_static/images/user-guide/github-login.png b/source/_static/images/user-guide/github-login.png
diff --git a/source/_static/images/user-guide/jupyterlab-launcher.png b/source/_static/images/user-guide/jupyterlab-launcher.png
diff --git a/source/_static/images/user-guide/jupyterlab-selection.png b/source/_static/images/user-guide/jupyterlab-selection.png
diff --git a/source/_static/images/user-guide/launch-server.png b/source/_static/images/user-guide/launch-server.png
diff --git a/source/_static/images/user-guide/platform-login-page.png b/source/_static/images/user-guide/platform-login-page.png
diff --git a/source/_static/images/user-guide/ports-panel.png b/source/_static/images/user-guide/ports-panel.png
diff --git a/source/_static/images/user-guide/resource-selection-page.png b/source/_static/images/user-guide/resource-selection-page.png
diff --git a/source/_static/images/user-guide/stop-my-server.png b/source/_static/images/user-guide/stop-my-server.png
diff --git a/source/user-guide/admin-manual.md → source/jupyterhub/admin-manual.md b/source/user-guide/admin-manual.md → source/jupyterhub/admin-manual.md
@@ -2,7 +2,7 @@
 
 This page summarizes the current administrator-facing workflows.
 
-For value-by-value configuration, use the [Configuration Reference](../jupyterhub/configuration-reference.md).
+For value-by-value configuration, use the [Configuration Reference](configuration-reference.md).
 
 ## Admin Surfaces
 
@@ -73,7 +73,7 @@ If quota is enabled, administrators can:
 - grant unlimited quota
 - inspect usage detail from the admin UI
 
-See [User Quota System](../jupyterhub/quota-system.md) for details.
+See [User Quota System](quota-system.md) for details.
 
 ### Update Login / Home Announcement
 

diff --git a/source/jupyterhub/index.md b/source/jupyterhub/index.md
@@ -9,6 +9,7 @@ configuration-reference
 README
 authentication-guide
 user-management
+admin-manual
 quota-system
 github-oauth-setup
 ```
@@ -19,5 +20,6 @@ github-oauth-setup
 - {doc}`README` - Quick setup notes for runtime/values.yaml
 - {doc}`authentication-guide` - Setup authentication
 - {doc}`user-management` - Manage users
+- {doc}`admin-manual` - Run common administrator workflows
 - {doc}`quota-system` - Configure quotas
 - {doc}`github-oauth-setup` - GitHub OAuth setup
diff --git a/source/user-guide/code-server-guide.md b/source/user-guide/code-server-guide.md
@@ -0,0 +1,177 @@
+# Code Server Guide
+
+This guide explains how to use Code Server in AUP Learning Cloud. Code Server provides a browser-based VS Code experience for coding, terminals, extensions, debugging, and web application previews.
+
+For login, environment selection, storage, and stopping servers, start with [Platform Basics](platform-basics.md).
+
+## When To Use Code Server
+
+Use Code Server when you want to:
+
+- Work in a VS Code-style editor from the browser
+- Use integrated terminals
+- Run scripts, training jobs, or development servers
+- Install editor extensions
+- Preview web applications through forwarded ports
+- Work with multi-file projects or Git repositories
+
+If your task is mainly notebook-based, use [JupyterLab Guide](jupyterlab-guide.md).
+
+## Start A Code Server Environment
+
+1. Sign in to AUP Learning Cloud.
+2. Select **Code Server CPU Environment** or **Code Server GPU Environment**.
+3. Choose the required hardware resources.
+4. Choose the runtime duration.
+5. Click **Launch Server**.
+6. Wait for the browser to open the VS Code interface.
+
+![Code Server selection](../_static/images/user-guide/code-server-selection.png)
+
+## Interface Overview
+
+The Code Server interface is similar to local VS Code:
+
+- Left side: Explorer, Search, Source Control, Run and Debug, Extensions
+- Center: code editor
+- Bottom panel: Terminal, Ports, Output, Problems
+
+![Code Server main interface](../_static/images/user-guide/code-server-main-interface.png)
+
+## Use The Terminal
+
+Open the integrated terminal with `Ctrl + \`` or from the top menu.
+
+Common commands:
+
+```bash
+# Check GPU status in GPU environments
+rocm-smi
+
+# Install Python packages
+pip install torch torchvision
+
+# Run a script
+python train.py
+
+# Start a simple web server
+python -m http.server 8080
+```
+
+You can open multiple terminal sessions by clicking the `+` button in the terminal panel.
+
+## Save Files
+
+Use the same storage rules as other AUP Learning Cloud environments:
+
+- Save important work under `/home/jovyan`.
+- Do not rely on temporary or image-provided directories for long-term storage.
+- Copy work to `/home/jovyan` before stopping the server.
+
+Example:
+
+```bash
+cp <file-or-directory-to-save> /home/jovyan/
+```
+
+## Port Forwarding
+
+When you run a web service inside Code Server, the platform can expose it through the browser.
+
+Example:
+
+```bash
+python -m http.server 8080
+```
+
+After the service starts:
+
+1. Open the **PORTS** panel.
+2. Select the forwarded port and open the forwarded address.
+3. If a notification appears, you can also click **Open in Browser**.
+4. If the port does not appear automatically, add it manually in the **PORTS** panel.
+
+![Ports panel](../_static/images/user-guide/ports-panel.png)
+
+Forwarded URLs usually follow this pattern:
+
+```text
+https://www.openhw.io/user/<your-username>/proxy/<port>/
+```
+
+Example:
+
+```text
+https://www.openhw.io/user/github%3Ausername/proxy/3000/
+```
+
+:::{note}
+Port forwarding works for HTTP and WebSocket services that listen on a port inside your remote environment. Make sure your application is actually running and listening on the expected port.
+:::
+
+## Extensions
+
+Code Server supports many VS Code extensions. Common preinstalled extensions may include:
+
+| Extension | Purpose |
+|---|---|
+| Python | Python language support, IntelliSense, and debugging |
+| Jupyter | Notebook support inside VS Code |
+| GitLens | Git history, blame, and comparison tools |
+| Python Debugger | Python breakpoint debugging |
+| Ruff | Python formatting and linting |
+| YAML | YAML syntax support |
+
+To install an extension:
+
+1. Open the Extensions panel on the left.
+2. Search for the extension name.
+3. Click **Install**.
+
+![Extensions panel](../_static/images/user-guide/extensions-panel.png)
+
+Recommended extensions for some workflows:
+
+- C/C++: C/C++ development support
+- ROCm HIP: AMD GPU programming support
+- Remote - Containers: container development support
+- Thunder Client: lightweight API testing
+- Markdown Preview: live Markdown preview
+
+:::{note}
+Extensions are installed in the remote environment. After a server restart or image change, you may need to install some extensions again. Keep a short list of your commonly used extensions.
+:::
+
+## Stop Code Server
+
+Before leaving:
+
+1. Save your files.
+2. Stop long-running terminal processes that you no longer need.
+3. Copy important work to `/home/jovyan`.
+4. Return to the Hub control page.
+5. Click **Stop my server**.
+
+## Troubleshooting
+
+### Port forwarding does not work
+
+- Confirm the service is running.
+- Confirm the service is listening on the expected port.
+- Check the **PORTS** panel.
+- Add the port manually if needed.
+- Refresh the browser page and try again.
+
+### Extension installation fails
+
+- Check the network connection.
+- Refresh the page and try again.
+- Search for an alternative extension.
+- Some desktop-only extensions may not fully support browser-based VS Code.
+
+### The terminal command cannot find a file
+
+- Check the current directory with `pwd`.
+- List files with `ls`.
+- Use absolute paths when needed.
+- Confirm important files are stored under `/home/jovyan`.
diff --git a/source/user-guide/index.md b/source/user-guide/index.md
@@ -1,20 +1,18 @@
 # User Guide
 
-This section provides guides for users and administrators of AUP Learning Cloud.
+This section provides end-user guides for AUP Learning Cloud.
 
 ```{toctree}
 :maxdepth: 2
 
-admin-manual
+platform-basics
+jupyterlab-guide
+code-server-guide
 ```
 
-## For Administrators
-
-- {doc}`admin-manual` - Comprehensive guide for system administrators
-
 ## For Users
 
-End-user topics are summarized in **Quick Links** below. For login and authentication, see the [Authentication Guide](../jupyterhub/authentication-guide.md). Your administrator can provide the JupyterHub URL; once logged in you can:
+Start with [Platform Basics](platform-basics.md) for login, environment selection, storage, and server lifecycle. Then use [JupyterLab Guide](jupyterlab-guide.md) or [Code Server Guide](code-server-guide.md) depending on the environment you launch. For authentication details, see the [Authentication Guide](../jupyterhub/authentication-guide.md). Your administrator can provide the JupyterHub URL; once logged in you can:
 
 - Launch notebook environments (Base CPU, GPU Base, CV/DL/LLM/PhySim courses)
 - Use hardware acceleration options (CPU, GPU) as allowed for your account

diff --git a/source/user-guide/jupyterlab-guide.md b/source/user-guide/jupyterlab-guide.md
@@ -0,0 +1,126 @@
+# JupyterLab Guide
+
+This guide explains how to use the JupyterLab environment in AUP Learning Cloud for notebooks, Python experiments, course materials, and terminal access.
+
+For login, environment selection, storage, and stopping servers, start with [Platform Basics](platform-basics.md).
+
+## When To Use JupyterLab
+
+Use JupyterLab when you want to:
+
+- Run Jupyter notebooks for course labs
+- Execute Python code interactively
+- Read and modify course-provided notebooks
+- Use a terminal for simple commands
+- Save experiment results in your user directory
+
+If you need a full VS Code-style IDE, use [Code Server Guide](code-server-guide.md) instead.
+
+## Start A JupyterLab Environment
+
+1. Sign in to AUP Learning Cloud.
+2. Select a course, tutorial, test, or notebook environment.
+3. Choose CPU or GPU resources if options are available.
+4. Choose the runtime duration.
+5. Click **Launch Server**.
+6. Wait for the browser to open JupyterLab.
+
+![JupyterLab environment selection](../_static/images/user-guide/jupyterlab-selection.png)
+
+## Create A Notebook
+
+1. In the Launcher page, choose **Python 3**.
+2. A new notebook opens in the main work area.
+3. Type code in a cell.
+4. Press `Shift + Enter` to run the cell.
+
+Example:
+
+```python
+print("Hello, JupyterHub!")
+```
+
+![JupyterLab Launcher](../_static/images/user-guide/jupyterlab-launcher.png)
+
+## Run Notebook Cells
+
+Common actions:
+
+| Action | Shortcut |
+|---|---|
+| Run current cell | `Shift + Enter` |
+| Save notebook | `Ctrl + S` on Windows/Linux, `Cmd + S` on macOS |
+| Add a new cell | Use the notebook toolbar `+` button |
+| Change cell type | Use the cell type dropdown in the toolbar |
+
+Run notebook cells in order when the notebook depends on previous variables, imports, or setup steps.
+
+## Use The File Browser
+
+The file browser on the left side lets you open, rename, move, upload, and download files.
+
+Recommended workflow:
+
+1. Keep active course work in a clear folder.
+2. Save assignments and personal results under `/home/jovyan`.
+3. Download a backup if the work is important.
+
+:::{warning}
+Some course images use `/ryzers/notebooks` as the default working directory. Move important files to `/home/jovyan` before the environment stops.
+:::
+
+## Use The Terminal
+
+JupyterLab includes a terminal for shell commands.
+
+1. Open the Launcher page.
+2. Click **Terminal**.
+3. Run commands as needed.
+
+Useful examples:
+
+```bash
+# Check the current directory
+pwd
+
+# List files
+ls
+
+# Copy important work to persistent storage
+cp <file-or-directory-to-save> /home/jovyan/
+
+# Check GPU status in GPU environments
+rocm-smi
+```
+
+## Save And Exit
+
+Before leaving JupyterLab:
+
+1. Save all notebooks.
+2. Copy important files to `/home/jovyan`.
+3. Shut down long-running notebooks or terminal commands that you no longer need.
+4. Return to the Hub control page and click **Stop my server**.
+
+## Troubleshooting
+
+### A notebook cell fails
+
+Check for common issues first:
+
+- Missing imports
+- Typing mistakes
+- Cells run out of order
+- Missing files or wrong file paths
+- Dependencies that were not installed
+
+### The notebook appears stuck
+
+- Check whether a cell is still running.
+- Interrupt the kernel if needed.
+- Restart the kernel if the session is in a bad state.
+- Save important files before stopping the server.
+
+### A file is missing after restart
+
+Check `/home/jovyan` first. Files that were only kept in temporary directories or default image directories may not persist.