Revise Python Notebook learning experience prototype

.gitignore

@@ -25,8 +25,8 @@ __pycache__/
 .idea/
 *.so
 samples/scratch/
-samples/qdk-learning/
-samples/qdk-learning.json
+qdk-learning/
+qdk-learning.json
 *.pyd
 /python_doc/
 /logs/

.vscode/launch.shared.json

@@ -10,7 +10,7 @@
       "args": [
         "--profile=dev",
         "--extensionDevelopmentPath=${workspaceFolder}/source/vscode",
-        "${workspaceFolder}/samples/"
+        "${workspaceFolder}/source/vscode/test/suites/learning/test-workspace"
       ],
       "outFiles": [
         "${workspaceFolder}/source/vscode/out/**/*.js",
@@ -68,7 +68,7 @@
         "--profile=dev",
         "--remote=codespaces+${env:CODESPACE_NAME}",
         "--extensionDevelopmentPath=${workspaceFolder}/source/vscode",
-        "${workspaceFolder}/samples/"
+        "${workspaceFolder}/source/vscode/test/suites/learning/test-workspace"
       ],
       "outFiles": [
         "${workspaceFolder}/source/vscode/out/**/*.js",

package.json

@@ -31,6 +31,7 @@
     "@vscode/debugprotocol": "^1.68.0",
     "@vscode/extension-telemetry": "0.8.5",
     "@vscode/markdown-it-katex": "^1.0.0",
+    "@vscode/python-environments": "^1.0.0",
     "@vscode/test-electron": "^3.1.0",
     "@vscode/test-web": "^0.0.81",
     "3dmol": "^2.5.4",

source/vscode/.gitignore

@@ -2,3 +2,4 @@ out/
 test/out/
 wasm/
 *.vsix
+.vscode/

source/vscode/ai/qdk-learning.agent.md

@@ -1,22 +1,24 @@
 ---
 name: QDK Learning
-description: "Learn quantum computing interactively with the Quantum Katas — guided lessons, hands-on exercises, and Q# code you can run, check, and explore right in VS Code."
+description: "Learn quantum computing interactively in VS Code — guided lessons, hands-on exercises, and code you can run, check, and explore. Includes the Quantum Katas and other learning courses."
 model: ["Claude Haiku 4.5 (copilot)", "Auto (copilot)"]
 ---
 
 # Quantum Development Kit Learning
 
-You are an agent that helps users navigate and interact with the Quantum Katas panel in VS Code. Your role is to respond to chat prompts related to the katas, provide hints, explanations, and guidance.
+You are an agent that helps users navigate and interact with the QDK Learning feature in VS Code. Your role is to respond to chat prompts related to the active course, provide hints, explanations, and guidance.
 
-The `qdk-learning-*` tools drive a **Quantum Katas panel** in VS Code. The panel renders the current activity, action bar, and progress bar. Its buttons handle navigation, run, check, etc. directly — they bypass the LLM. Your job: set up the workspace, show the current activity, then step aside. You only handle chat prompts and concept questions.
+The `qdk-learning-*` tools drive the QDK Learning UI in VS Code. The Lesson panel renders the current activity, action bar, and progress bar. Its buttons handle navigation, run, check, etc. directly — they bypass the LLM. Your job: set up the workspace, show the current activity, then step aside. You only handle chat prompts and concept questions.
+
+A user can work through more than one **course**. The **Quantum Katas** is the default course. Additional courses may also be available in the workspace. Each course has its own units, activities, and progress.
 
 ## Definitions
 
-Following is a user-ready description of the Quantum Katas. You may refer to it if the user asks what the katas are or how they work.
+The **Quantum Katas** is the flagship course. Following is a user-ready description. You may refer to it if the user asks what the katas are or how they work.
 
 > Quantum Katas (_kaˑta_ | kah-tuh — Japanese for "form", a pattern of learning and practicing new skills) are self-paced, AI-assisted tutorials for quantum computing and Q# programming. Each tutorial includes relevant theory and interactive hands-on exercises designed to test knowledge.
 
-The tools refer to each kata as a "unit." Each unit contains ordered activities (lessons, examples, exercises).
+The tools refer to each kata as a "unit". In other courses, there are no katas, simply units. Each unit contains ordered activities (lessons, examples, exercises).
 
 **Tool naming:** All learning tools share the `qdk-learning-` prefix. This document uses short names (e.g. `show` for `qdk-learning-show`).
 
@@ -28,13 +30,30 @@ The tools refer to each kata as a "unit." Each unit contains ordered activities
 
 ## Startup
 
-Call `get-state` first. It never requires confirmation and tells you whether the workspace is initialized.
+Call `get-state` first. It never requires confirmation and tells you whether the workspace is initialized and which course is active.
 
-- **If `initialized: true`** — you have the current position and progress. Greet the user briefly, then call `show` to open the activity panel. Direct the user's attention to the Quantum Katas panel so they can continue where they left off.
+- **If `initialized: true`** — you have the current position, active course, and progress. Greet the user briefly, then call `show` to open the activity panel. Direct the user's attention to the Learning panel so they can continue where they left off.
 - **If `initialized: false`** — the workspace hasn't been set up yet. Greet the user warmly and explain what the Quantum Katas are (use the description from **Definitions** above). Then call `show` to initialize the workspace — let the user know they'll be asked to confirm workspace creation. Once initialized, direct them to the panel to get started.
 
 Mention that they can chat with you at any time for hints, explanations, or guidance. Don't explain how the agent works, list tools, or show menus.
 
+## Courses
+
+Multiple courses may be available. The active course is reported by `get-state` (the `course` field) and is the context for all activity, run, and check operations. The **Quantum Katas** is the default course.
+
+| Intent                                | Tool                | Notes                                                                     |
+| ------------------------------------- | ------------------- | ------------------------------------------------------------------------- |
+| "What courses are available?"         | `list-courses`      | Returns the available courses and the active course id.                   |
+| "Switch to …" / "Open the … course"   | `switch-course`     | Pass the `courseId`. Switching changes the active course and position.    |
+| "Tell me about this course"           | `course-info`       | Returns the course descriptor and README (defaults to the active course). |
+| "Diagnose" / "Set up the environment" | `check-environment` | Runs environment diagnostics for the active course (Python courses).      |
+
+**Handling guidance:**
+
+- When the user asks to change courses, call `list-courses` first if you're unsure of the exact `courseId`, match the user's request to a course, then call `switch-course`. After switching, call `show` to surface the new course's current activity and briefly tell the user where they landed.
+- Python notebook courses use a per-course environment. If running or checking a task reports environment or kernel problems, call `check-environment` to diagnose; it reports which checks fail and whether a one-click setup can fix them. The katas need no environment and always pass `check-environment`.
+- Don't switch courses unless the user clearly asks. Panel and tree actions can also switch courses without involving you, so always call `get-state` to learn the current course before answering.
+
 ## Tone
 
 Warm, friendly tutor. Celebrate passes, encourage on failures, use natural language.
@@ -68,13 +87,16 @@ Call `show`. Use the returned state for your greeting. Don't call on every turn
 
 To start a specific unit: `list-units` → find `unitId` → `goto`.
 
+To change courses: `list-courses` → find `courseId` → `switch-course` → `show`.
+
 ### 2. Route Chat Input
 
 Call `get-state` first. If the user is asking to navigate, run, check, reset, etc., call the matching tool directly. Notable cases:
 
 - **hint** → use the **Hint Strategy** below instead of just calling the tool
 - **solution** → warn about spoilers before calling
 - **reset** → confirm the user wants to lose their code before calling
+- **switch course / list courses / course info** → use the **Courses** tools (`switch-course`, `list-courses`, `course-info`); call `show` after a switch
 - **"help with my code" / "debug"** → call `read-code`, then give personalized feedback
 - **Q# or QDK question** → if the answer isn't obvious from the current lesson context, **always** read the `/qdk-programming` skill before responding.
 - **free-form question** → answer using knowledge + current state; no tool needed

source/vscode/ai/qdk-learning.prompt.md

@@ -5,4 +5,4 @@ agent: QDK Learning
 argument-hint: Chat with the QDK Learning agent. e.g. "give me a hint", "check my solution", "run my code"
 ---
 
-Let's do the Quantum Katas.
+Let's learn quantum computing with the QDK. Start with the Quantum Katas, or switch to another available course.

source/vscode/package.json

@@ -326,6 +326,10 @@
           "command": "qsharp-vscode.learningResetExercise",
           "when": "false"
         },
+        {
+          "command": "qsharp-vscode.learningResetUnit",
+          "when": "false"
+        },
         {
           "command": "qsharp-vscode.learningShowActivity",
           "when": "false"
@@ -341,6 +345,26 @@
         {
           "command": "qsharp-vscode.learningAskInChat",
           "when": "false"
+        },
+        {
+          "command": "qsharp-vscode.learningSwitchCourse",
+          "when": "false"
+        },
+        {
+          "command": "qsharp-vscode.learningCourseInfo",
+          "when": "false"
+        },
+        {
+          "command": "qsharp-vscode.learningCheckEnvironment",
+          "when": "qsharp-vscode.learningWorkspaceDetected"
+        },
+        {
+          "command": "qsharp-vscode.learningNotebookHint",
+          "when": "false"
+        },
+        {
+          "command": "qsharp-vscode.learningNotebookExplain",
+          "when": "false"
         }
       ],
       "view/title": [
@@ -371,6 +395,32 @@
         }
       ],
       "view/item/context": [
+        {
+          "command": "qsharp-vscode.learningSwitchCourse",
+          "group": "inline",
+          "when": "view == qsharp-vscode.learningTree && (viewItem == course || viewItem == coursePython)"
+        },
+        {
+          "command": "qsharp-vscode.learningCourseInfo",
+          "group": "inline",
+          "when": "view == qsharp-vscode.learningTree && (viewItem == course || viewItem == coursePython)"
+        },
+        {
+          "command": "qsharp-vscode.learningSwitchCourse",
+          "when": "view == qsharp-vscode.learningTree && (viewItem == course || viewItem == coursePython)"
+        },
+        {
+          "command": "qsharp-vscode.learningCourseInfo",
+          "when": "view == qsharp-vscode.learningTree && (viewItem == course || viewItem == coursePython)"
+        },
+        {
+          "command": "qsharp-vscode.learningCheckEnvironment",
+          "when": "view == qsharp-vscode.learningTree && viewItem == coursePython"
+        },
+        {
+          "command": "qsharp-vscode.learningResetUnit",
+          "when": "view == qsharp-vscode.learningTree && viewItem == unitPython"
+        },
         {
           "command": "qsharp-vscode.workspaceOpenPortal",
           "group": "inline",
@@ -417,7 +467,26 @@
         {
           "command": "qsharp-vscode.learningAskInChat",
           "group": "inline",
-          "when": "view == qsharp-vscode.learningTree && (viewItem == continue || viewItem == unit || viewItem == lesson || viewItem == exercise || viewItem == example)"
+          "when": "view == qsharp-vscode.learningTree && (viewItem == continue || viewItem == unit || viewItem == unitPython || viewItem == lesson || viewItem == exercise || viewItem == example)"
+        }
+      ],
+      "notebook/toolbar": [
+        {
+          "command": "qsharp-vscode.learningCheckEnvironment",
+          "when": "qsharp-vscode.learningNotebookActive",
+          "group": "navigation@100"
+        },
+        {
+          "command": "qsharp-vscode.learningResetUnit",
+          "when": "qsharp-vscode.learningNotebookActive",
+          "group": "navigation@110"
+        }
+      ],
+      "notebook/cell/title": [
+        {
+          "command": "qsharp-vscode.learningNotebookExplain",
+          "when": "notebookType == 'jupyter-notebook' && qsharp-vscode.learningWorkspaceDetected",
+          "group": "inline/cell@50"
         }
       ],
       "explorer/context": [
@@ -694,11 +763,47 @@
         "category": "QDK Learning",
         "icon": "$(discard)"
       },
+      {
+        "command": "qsharp-vscode.learningResetUnit",
+        "title": "Reset Unit",
+        "category": "QDK Learning",
+        "icon": "$(discard)"
+      },
       {
         "command": "qsharp-vscode.learningShowActivity",
         "title": "Show Current Activity",
         "category": "QDK Learning",
         "icon": "$(mortar-board)"
+      },
+      {
+        "command": "qsharp-vscode.learningSwitchCourse",
+        "title": "Switch Course",
+        "category": "QDK Learning",
+        "icon": "$(arrow-swap)"
+      },
+      {
+        "command": "qsharp-vscode.learningCourseInfo",
+        "title": "Course Info",
+        "category": "QDK Learning",
+        "icon": "$(info)"
+      },
+      {
+        "command": "qsharp-vscode.learningCheckEnvironment",
+        "title": "Run Course Diagnostics",
+        "category": "QDK Learning",
+        "icon": "$(pulse)"
+      },
+      {
+        "command": "qsharp-vscode.learningNotebookHint",
+        "title": "Ask for a Hint",
+        "category": "QDK Learning",
+        "icon": "$(comment-discussion-sparkle)"
+      },
+      {
+        "command": "qsharp-vscode.learningNotebookExplain",
+        "title": "Explain",
+        "category": "QDK Learning",
+        "icon": "$(comment-discussion-sparkle)"
       }
     ],
     "breakpoints": [
@@ -1331,6 +1436,94 @@
           "additionalProperties": false
         }
       },
+      {
+        "name": "qdk-learning-list-courses",
+        "tags": [
+          "qdk",
+          "qdk-learning",
+          "quantum-katas"
+        ],
+        "toolReferenceName": "qdkLearningListCourses",
+        "displayName": "QDK Learning: List Courses",
+        "modelDescription": "List all available learning courses (loaded or not) with their ids, titles, kinds, and the id of the currently-active course. Use the course ids with switch-course or goto.",
+        "canBeReferencedInPrompt": true,
+        "icon": "./resources/file-icon-light.svg",
+        "inputSchema": {
+          "type": "object",
+          "properties": {},
+          "required": [],
+          "additionalProperties": false
+        }
+      },
+      {
+        "name": "qdk-learning-switch-course",
+        "tags": [
+          "qdk",
+          "qdk-learning",
+          "quantum-katas"
+        ],
+        "toolReferenceName": "qdkLearningSwitchCourse",
+        "displayName": "QDK Learning: Switch Course",
+        "modelDescription": "Switch the active learning course. Moves to the first incomplete activity in that course and updates the panel. Use a courseId from list-courses.",
+        "canBeReferencedInPrompt": true,
+        "icon": "./resources/file-icon-light.svg",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "courseId": {
+              "type": "string",
+              "description": "ID of the course to switch to (from list-courses)."
+            }
+          },
+          "required": [
+            "courseId"
+          ],
+          "additionalProperties": false
+        }
+      },
+      {
+        "name": "qdk-learning-course-info",
+        "tags": [
+          "qdk",
+          "qdk-learning",
+          "quantum-katas"
+        ],
+        "toolReferenceName": "qdkLearningCourseInfo",
+        "displayName": "QDK Learning: Course Info",
+        "modelDescription": "Return the descriptor and README content (if any) for a course. Defaults to the active course when no courseId is provided.",
+        "canBeReferencedInPrompt": true,
+        "icon": "./resources/file-icon-light.svg",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "courseId": {
+              "type": "string",
+              "description": "ID of the course. Omit for the active course."
+            }
+          },
+          "required": [],
+          "additionalProperties": false
+        }
+      },
+      {
+        "name": "qdk-learning-check-environment",
+        "tags": [
+          "qdk",
+          "qdk-learning",
+          "quantum-katas"
+        ],
+        "toolReferenceName": "qdkLearningCheckEnvironment",
+        "displayName": "QDK Learning: Check Environment",
+        "modelDescription": "Run environment diagnostics for the active learning course. Returns structured checks (Python interpreter, virtual environment, fingerprint, required packages) and whether a one-click environment setup can fix any failures. Q# courses need no environment and pass trivially.",
+        "canBeReferencedInPrompt": true,
+        "icon": "./resources/file-icon-light.svg",
+        "inputSchema": {
+          "type": "object",
+          "properties": {},
+          "required": [],
+          "additionalProperties": false
+        }
+      },
       {
         "name": "qdk-learning-next",
         "tags": [