Install course dependencies from manifest pins (#95)

* Use course manifest pins for installation and updates

* Verify older project pins remain isolated from public latest

Author: Sunrisepeak

.github/workflows/fresh-install.yml

@@ -218,14 +218,14 @@ jobs:
           include-hidden-files: true
 
   released-course:
-    name: Published d2x install route (main only)
-    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main' && inputs.candidate_run == ''
+    name: d2x download and pinned install
+    if: ${{ !inputs.diagnose && inputs.candidate_run == '' }}
     runs-on: ubuntu-24.04
     timeout-minutes: 60
     steps:
       - uses: actions/checkout@v4
-      - name: Follow the README using the public course download
-        run: python3 scripts/ci/readme.py --published
+      - name: Verify the documented existing-d2x download route
+        run: python3 scripts/ci/readme.py --d2x-download ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/main' && '--published' || '' }}
       - uses: actions/upload-artifact@v4
         if: always()
         with:
@@ -265,7 +265,7 @@ jobs:
           include-hidden-files: true
 
   latest-stable:
-    if: github.ref == 'refs/heads/main' && inputs.candidate_run == ''
+    if: ${{ !inputs.diagnose && inputs.candidate_run == '' }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -280,7 +280,7 @@ jobs:
         if: runner.os == 'Windows'
         shell: powershell
         run: ./scripts/install-xlings.ps1
-      - name: Check stable release, public latest and course pin
+      - name: Check public latest and independently restore course pins
         shell: bash
         env:
           GH_TOKEN: ${{ github.token }}

.github/workflows/online-ebook.yml

@@ -45,9 +45,6 @@ jobs:
       run:
         working-directory: book
 
-    env:
-      MDBOOK_VERSION: 0.4.43
-
     steps:
       - uses: actions/checkout@v4
 
@@ -57,8 +54,8 @@ jobs:
       - name: Install the shared xlings baseline
         run: bash ../scripts/install-xlings.sh
 
-      - name: Install mdBook
-        run: xlings install mdbook@${MDBOOK_VERSION} -y
+      - name: Install the course dependencies from .xlings.json
+        run: xlings install -y
 
       - name: Setup Pages
         if: github.event_name != 'pull_request'

README.md

@@ -43,22 +43,24 @@ Wait for the environment to be ready, then run `d2x checker` in the terminal.
 
 ### Practice locally
 
-**1. Install the tools**
+**1. Get the course**
 
-Install [xlings](docs/environment.md#install-xlings), reopen your terminal, then run:
+Install [xlings](docs/environment.md#install-xlings) and Git, then reopen your terminal.
 
 ```bash
-xlings update
-xlings install --use d2x@latest mcpp@latest -y
+git clone https://github.com/mcpp-community/d2mcpp.git
+cd d2mcpp
 ```
 
-**2. Get the course**
+**2. Install the course versions**
 
 ```bash
-d2x install d2mcpp
-cd d2mcpp
+xlings update
+xlings install -y
 ```
 
+Run these commands from the course directory. `xlings install` installs the versions declared in `.xlings.json`; after updating the course with Git, run the same two commands again.
+
 **3. Verify and practice**
 
 ```bash

README.zh.hant.md

@@ -43,22 +43,24 @@
 
 ### 建立本地練習環境
 
-**第一步：安裝工具**
+**第一步：取得課程**
 
-安裝 [xlings](docs/environment.zh.md#install-xlings)，重新開啟終端後執行：
+安裝 [xlings](docs/environment.zh.md#install-xlings) 和 Git，然後重新開啟終端。
 
 ```bash
-xlings update
-xlings install --use d2x@latest mcpp@latest -y
+git clone https://github.com/mcpp-community/d2mcpp.git
+cd d2mcpp
 ```
 
-**第二步：取得課程**
+**第二步：安裝課程版本**
 
 ```bash
-d2x install d2mcpp
-cd d2mcpp
+xlings update
+xlings install -y
 ```
 
+在課程目錄執行上述命令。`xlings install` 安裝 `.xlings.json` 宣告的版本；透過 Git 更新課程後，再次執行這兩條命令。
+
 **第三步：驗證並開始練習**
 
 ```bash

README.zh.md

@@ -43,22 +43,24 @@
 
 ### 搭建本地练习环境
 
-**第一步：安装工具**
+**第一步：获取课程**
 
-安装 [xlings](docs/environment.zh.md#install-xlings)，重新打开终端后执行：
+安装 [xlings](docs/environment.zh.md#install-xlings) 和 Git，然后重新打开终端。
 
 ```bash
-xlings update
-xlings install --use d2x@latest mcpp@latest -y
+git clone https://github.com/mcpp-community/d2mcpp.git
+cd d2mcpp
 ```
 
-**第二步：获取课程**
+**第二步：安装课程版本**
 
 ```bash
-d2x install d2mcpp
-cd d2mcpp
+xlings update
+xlings install -y
 ```
 
+在课程目录执行上述命令。`xlings install` 安装 `.xlings.json` 声明的版本；通过 Git 更新课程后，再次执行这两条命令。
+
 **第三步：验证并开始练习**
 
 ```bash

book/en/src/base/chapter_1.md

@@ -40,32 +40,18 @@ $env:Path = "$env:USERPROFILE\.xlings\subos\current\bin;$env:Path"
 The PATH command makes the installed tools available in this terminal. For future sessions, reopen your terminal after installation. Preparation can be repeated and preserves your exercise files and progress.
 
 <details>
-<summary>Alternative: download with d2x install</summary>
+<summary>Alternative: download with an existing d2x</summary>
 
-Install [xlings](https://github.com/openxlings/xlings) first:
+If d2x is already installed, use the commands below. After downloading, run `xlings install -y` from the course directory to install the `.xlings.json` dependencies. There is no need to preinstall mcpp or select latest.
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/v2026.10.18.1/tools/other/quick_install.sh | bash -s v2026.10.18.1
-export PATH="$HOME/.xlings/subos/current/bin:$PATH"
-```
-
-Or on Windows PowerShell:
-
-```powershell
-irm https://raw.githubusercontent.com/mcpp-community/d2mcpp/main/scripts/install-xlings.ps1 | iex
-$env:Path = "$env:USERPROFILE\.xlings\subos\current\bin;$env:Path"
-```
-
-Then, on either system:
-
-```text
-xlings update
-xlings install --use d2x@latest mcpp@latest -y
 d2x install d2mcpp
 cd d2mcpp
+xlings update
+xlings install -y
 ```
 
-Continue with the preparation script for your system in step 2; both download routes use the same verification below.
+Then continue with the preparation script in step 2. Apply project pins again after updating the course.
 
 </details>
 

book/en/src/changelog.md

@@ -10,6 +10,13 @@
 
 ## 2026/10
 
+**Install dependencies from the course manifest**
+
+Get the course before running `xlings install -y` to install the versions pinned in `.xlings.json`. Align update instructions and verify both Git and d2x downloads in CI. Check upstream latest independently of course dependency upgrades.
+
+- `Book`: [zh](https://mcpp-community.github.io/d2mcpp/base/chapter_1.html) / [en](https://mcpp-community.github.io/d2mcpp/en/base/chapter_1.html) - 2026/10/21
+- `Code`: [first-use CI](https://github.com/mcpp-community/d2mcpp/blob/main/.github/workflows/fresh-install.yml) - 2026/10/21
+
 **d2x upgrade and cold-start diagnostics**
 
 Upgrade d2x to 2026.10.21.1 and verify the selected executable; bound first Provider startup separately, show preparation and retain raw logs.

book/src/base/chapter_1.md

@@ -40,32 +40,18 @@ $env:Path = "$env:USERPROFILE\.xlings\subos\current\bin;$env:Path"
 PATH 命令让当前终端立即找到工具；安装后重新打开终端即可供后续会话使用。准备脚本可重复执行，不会改动练习文件或学习进度。
 
 <details>
-<summary>可选：通过 d2x install 下载课程</summary>
+<summary>可选：通过已有 d2x 下载课程</summary>
 
-先安装 [xlings](https://github.com/openxlings/xlings)：
+如果已经安装 d2x，可以使用以下方式。下载后在课程目录执行 `xlings install -y`，按 `.xlings.json` 安装依赖，无需提前安装 mcpp 或选择 latest。
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/v2026.10.18.1/tools/other/quick_install.sh | bash -s v2026.10.18.1
-export PATH="$HOME/.xlings/subos/current/bin:$PATH"
-```
-
-Windows PowerShell 使用：
-
-```powershell
-irm https://raw.githubusercontent.com/mcpp-community/d2mcpp/main/scripts/install-xlings.ps1 | iex
-$env:Path = "$env:USERPROFILE\.xlings\subos\current\bin;$env:Path"
-```
-
-然后在任一系统执行：
-
-```text
-xlings update
-xlings install --use d2x@latest mcpp@latest -y
 d2x install d2mcpp
 cd d2mcpp
+xlings update
+xlings install -y
 ```
 
-继续执行第二步中对应系统的准备脚本；两种下载方式共用下面的验证步骤。
+之后继续第二步的准备脚本。更新课程后同样按项目配置安装依赖。
 
 </details>
 

book/src/changelog.md

@@ -10,6 +10,13 @@
 
 ## 2026/10
 
+**按课程配置安装依赖**
+
+默认先获取课程，再由 `xlings install -y` 安装 `.xlings.json` 固定的版本；统一更新说明，并在 CI 验证 Git 与 d2x 下载路径。上游 latest 检查独立于课程版本升级。
+
+- `Book`: [zh](https://mcpp-community.github.io/d2mcpp/base/chapter_1.html) / [en](https://mcpp-community.github.io/d2mcpp/en/base/chapter_1.html) - 2026/10/21
+- `Code`: [first-use CI](https://github.com/mcpp-community/d2mcpp/blob/main/.github/workflows/fresh-install.yml) - 2026/10/21
+
 **d2x 最新版联动与冷启动诊断**
 
 升级 d2x 至 2026.10.21.1，核对实际执行版本；首次 Provider 构建单独限时，显示准备进度并保留原始日志。

docs/environment.md

@@ -26,7 +26,7 @@ Continue with the README. If a command is not found, reopen your terminal or app
 
 ## Git installation and updates
 
-After installing xlings, you can also clone the course. Replace the URL with your fork if needed:
+After installing xlings, clone the course as shown in the README. Replace the URL with your fork if needed:
 
 ```bash
 git clone https://github.com/mcpp-community/d2mcpp.git
@@ -104,6 +104,22 @@ limit. Preparation messages do not extend the startup deadline. On failure, keep
 `.d2x/provider.stdout.log`, `.d2x/provider.stderr.log` and the command output.
 Startup/transport errors exit nonzero; an unfinished exercise verdict is expected.
 
-For an existing tool installation, use `xlings install --use d2x@latest mcpp@latest -y` after `xlings update`. `@latest` selects the newest stable index entry; `--use` activates it even when already installed. Bare install commands can retain the previously selected version.
+From an existing course directory, install or restore the versions declared in `.xlings.json` with the commands below. `xlings update` refreshes the package index; `xlings install -y` installs the project dependencies. Use the course pins rather than `@latest`. Dependency upgrades belong in `.xlings.json` and must pass CI before publication.
+
+```bash
+xlings update
+xlings install -y
+```
 
 User cancellation returns 130 and a `cancelled` event without a Provider-failure warning or a failed exercise verdict.
+
+## Download with an existing d2x
+
+If d2x is already available, you can use this download route. The installer applies the downloaded course dependencies; running `xlings install -y` from the course directory explicitly reapplies its pins. There is no need to preinstall mcpp or select latest.
+
+```bash
+d2x install d2mcpp
+cd d2mcpp
+xlings update
+xlings install -y
+```