fix: pandas course setup and tooling/doc consistency

.github/dependabot.yml

@@ -8,6 +8,12 @@ updates:
       time: "09:00"
       timezone: Asia/Shanghai
     open-pull-requests-limit: 5
+    ignore:
+      # Course folders pin these in their own requirements.txt, which this
+      # root-level config does not scan. Upgrade them together with the
+      # course pins during a course re-review, not in the weekly group PR.
+      - dependency-name: "pandas"
+      - dependency-name: "matplotlib"
     groups:
       python-dependencies:
         patterns:

.github/workflows/notify-site.yml

@@ -4,7 +4,6 @@ on:
   push:
     branches:
       - master
-      - main
     tags:
       - "v*"
 

.github/workflows/validate.yml

@@ -5,7 +5,6 @@ on:
   push:
     branches:
       - master
-      - main
 
 permissions:
   contents: read

AGENTS.md

@@ -40,8 +40,11 @@ reviewed catalog data, and stable public JSON contracts.
   pairs (objective, exercise, checkpoint, expected evidence), `scenario/`
   data files for each skin, `TASK.md`/`TASK_cn.md` (task contract),
   `starter/` and `solution/` runnable pairs, a self-contained `verify.py`
-  that fails on `starter` and passes on `solution`, exposes deterministic
-  claim codes through `verify.py progress` (five checkpoints), and runs on
+  that fails on `starter` and passes on `solution`, reports five checkpoints
+  through `python verify.py` and the versioned `check --json` interface
+  (deterministic claim codes; self-reported checkpoints emit a code only after
+  explicit `--attest ID`; `progress --json` stays only for legacy signed
+  receipts), and runs on
   the standard library unless the course ships its own `requirements.txt`
   (as the pandas/matplotlib data-analysis courses do), and `REVIEW.md`
   recording the maintainer run-through (date, tool, version, observed agent

CHANGELOG.md

@@ -4,6 +4,29 @@ This file records notable catalog-contract and maintenance changes.
 
 ## [Unreleased]
 
+### Fixed — 2026-10-04 CI and course setup
+
+- CI: `ruff` is pinned in `requirements-dev.lock.txt`. CI had installed the
+  latest unpinned ruff, whose new rules failed every Validate run from
+  2026-09-16; the three findings were fixed without behavior change.
+- CI: the dev lock installs on Python 3.11 again (`numpy` and `contourpy`
+  use `python_version` markers); the 3.11 job had failed at install since
+  the lock was added.
+- Tests: guide heading extraction requires whitespace after the step number
+  (#90), and guide URL extraction ignores Markdown link titles (adapted from
+  #91).
+- Actions: `actions/checkout` v7, `astral-sh/setup-uv` v7,
+  `peter-evans/repository-dispatch` v4 (#89).
+- Courses: `da-eda` and `da-visualization` setup (EN+ZH) and the `verify.py`
+  missing-dependency hint no longer say `uv sync`, which fails in a
+  standalone course folder (no `pyproject.toml`) and does not install pandas
+  in a clone (it lives in the `dev` extra). They now create a virtual
+  environment and run `pip install -r requirements.txt`.
+- Tooling: removed the stale, unused `uv.lock` (`requirements*.lock.txt` are
+  the only lock files); `make check` now also runs ruff and pytest, as CI
+  does; Dependabot ignores pandas and matplotlib, which course folders pin;
+  workflows no longer trigger on the deleted `main` branch.
+
 ### Changed — 2026-09-16 learner verifier v2
 
 - All 12 public course verifiers now expose `check --json` and require
@@ -15,8 +38,9 @@ This file records notable catalog-contract and maintenance changes.
 - `progress --json` remains available only for the v1 signed-receipt contract;
   its legacy self-reported rows must not be submitted as learner claims.
 - `tools/verify_courses.py`, both READMEs, paired course guidance, and
-  `content-manifest.json` were updated together. Production consumer pin:
-  `39a3e79be939f491ac3c779494bf5c655c5588a0`.
+  `content-manifest.json` were updated together. The website consumer pin was
+  `39a3e79be939f491ac3c779494bf5c655c5588a0` at the time; the current pin is
+  recorded in the website's `src/data/content-pin.json`.
 
 0.1.0 — companion-repository half of the public launch (website
 `docs/product-and-growth-plan-0.1.0.md`; see the website `CHANGELOG.md`
@@ -25,8 +49,8 @@ for the platform half).
 Release mapping (FP-1012): this repository ships **v0.1.1** on this
 release train — the earlier `v0.1.0` tag stays immutably on `e420fca`.
 Compatibility: website `v0.1.0` ↔ repository `v0.1.1`. The immutable tag is
-`db85cdd…`; current `master` and the production website pin have advanced to
-post-tag verifier commit `39a3e79…`.
+`db85cdd…`; `master` and the website pin have since moved past the tag (see
+`[Unreleased]`).
 
 ### Changed
 

CONTRIBUTING.md

@@ -84,9 +84,10 @@ python tools/render_readmes.py
 python tools/build_content_manifest.py
 ```
 
-Run the same deterministic checks as CI:
+Run the same deterministic checks as CI (or `make check`):
 
 ```bash
+python -m ruff check .
 python -m pytest
 python tools/validate_catalog.py
 python tools/export_catalog.py --check --target both

Makefile

@@ -1,20 +1,21 @@
-.PHONY: help check export render manifest test verify courses paths lint typecheck all
+.PHONY: help check export render manifest test verify courses paths lint all
 
 PYTHON ?= python3
 
 help:
 	@echo "FlyPython Development Workflow:"
-	@echo "  make check      - Run all catalog, radar, export, readme, manifest, example, and course checks"
+	@echo "  make check      - Run the same checks as CI: lint, tests, catalog, radar, export, readme, manifest, example, course, and path checks"
 	@echo "  make export     - Regenerate catalog.json and radar.json"
 	@echo "  make render     - Regenerate README and README_cn catalog indexes plus the Radar table"
 	@echo "  make manifest   - Regenerate content-manifest.json"
+	@echo "  make lint       - Run ruff"
 	@echo "  make test       - Run pytest test suite"
 	@echo "  make verify     - Verify all runnable examples"
 	@echo "  make courses    - Verify all course folders"
 	@echo "  make paths      - Verify all learning-path contracts"
 	@echo "  make all        - Regenerate all exports and run all checks and tests"
 
-check:
+check: lint test
 	$(PYTHON) tools/validate_catalog.py
 	$(PYTHON) tools/export_catalog.py --check --target both
 	$(PYTHON) tools/render_readmes.py --check
@@ -32,6 +33,9 @@ render:
 manifest:
 	$(PYTHON) tools/build_content_manifest.py
 
+lint:
+	$(PYTHON) -m ruff check .
+
 test:
 	$(PYTHON) -m pytest
 
@@ -44,4 +48,4 @@ courses:
 paths:
 	$(PYTHON) tools/verify_paths.py
 
-all: export render manifest test check
+all: export render manifest check

README.md

@@ -27,13 +27,14 @@ versions into a browsable learning experience.
 
 ## Current status
 
-As of 2026-09-19, `master` is `39a3e79be939f491ac3c779494bf5c655c5588a0`
-and the package version is `0.1.1`. This commit follows the immutable `v0.1.1`
-tag and adds learner verifier v2: tests must pass and reflection checkpoints
-must be explicitly confirmed with `--attest`. FlyPython.com pins this exact
-commit and serves it in production. That proves release delivery, not learner
-outcomes or paid demand; the website's payment and email operations still have
-separate acceptance gates.
+The package version is `0.1.1`; the immutable `v0.1.1` tag points to `db85cdd`.
+Since that tag, `master` has added learner verifier v2 (tests must pass and
+reflection checkpoints must be explicitly confirmed with `--attest`) plus CI
+and course-setup fixes; see [CHANGELOG.md](CHANGELOG.md). FlyPython.com builds
+from an exact commit pinned on the website side, so `master` can be ahead of
+what the site serves. A pinned, served commit proves release delivery, not
+learner outcomes or paid demand; the website's payment and email operations
+still have separate acceptance gates.
 
 ## Start in three minutes
 

README_cn.md

@@ -24,11 +24,11 @@ FlyPython 是一个面向实践的双语仓库，帮助你写好 Python，并把
 
 ## 当前状态
 
-截至 2026-09-19，`master` 为 `39a3e79be939f491ac3c779494bf5c655c5588a0`，
-包版本为 `0.1.1`。该提交位于不可变标签 `v0.1.1` 之后，加入 learner verifier v2：
-测试关卡必须通过，自报关卡必须用 `--attest` 显式确认。FlyPython.com 固定并在生产环境
-交付此提交。这只能证明发布与交付，不证明学习效果或付费需求；网站的真实付款和邮件运营
-仍有独立验收关卡。
+包版本为 `0.1.1`；不可变标签 `v0.1.1` 指向 `db85cdd`。该标签之后，`master` 加入了
+learner verifier v2（测试关卡必须通过，自报关卡必须用 `--attest` 显式确认），以及 CI
+与课程环境说明的修复，详见 [CHANGELOG.md](CHANGELOG.md)。FlyPython.com 按网站侧固定的
+精确提交构建，所以 `master` 可能领先于网站当前交付的版本。固定并交付某个提交只能证明
+发布与交付，不证明学习效果或付费需求；网站的真实付款和邮件运营仍有独立验收关卡。
 
 ## 3 分钟开始
 

content-manifest.json

@@ -610,15 +610,15 @@
           "lang": "en-US",
           "path": "courses/da-eda/COURSE.md",
           "title": "Exploratory Data Analysis with an Agent",
-          "summary": "A challenge course — point your agent at a messy shop export and produce a verified EDA summary (results.json) whose numbers are checked against ground truth. First non-stdlib course in the catalog; pandas is managed with uv.",
-          "sha256": "e50b0ca1ec8d3dcccfeb8a9597a31bf3a9b351a869be95c72495a9861ee0b224"
+          "summary": "A challenge course — point your agent at a messy shop export and produce a verified EDA summary (results.json) whose numbers are checked against ground truth. First non-stdlib course in the catalog; pandas is pinned in requirements.txt.",
+          "sha256": "412cd414e1ecafa7827772f1c4355c1d2be4e7f5da7cd52700bb88c5c782fa56"
         },
         {
           "lang": "zh-CN",
           "path": "courses/da-eda/COURSE_cn.md",
           "title": "用 Agent 做探索性数据分析",
-          "summary": "挑战式课程——让你的 Agent 处理一份脏的商店导出数据，产出一份经过真值校验的 EDA 摘要（results.json）。目录中第一门非标准库课程；pandas 由 uv 管理。",
-          "sha256": "83b2a03bbb124d95b81e3d537b8a6a89b0b7be4600e43e3585dbbc5b07af18c1"
+          "summary": "挑战式课程——让你的 Agent 处理一份脏的商店导出数据，产出一份经过真值校验的 EDA 摘要（results.json）。目录中第一门非标准库课程；pandas 版本固定在 requirements.txt。",
+          "sha256": "509913a62ecc46d0972b7572578f3f716c5cc98155734b19d4cb077c218780ac"
         }
       ]
     },
@@ -887,14 +887,14 @@
           "path": "courses/da-visualization/COURSE.md",
           "title": "Data Visualization with an Agent",
           "summary": "Challenge course — turn a clean sales dataset into three spec'd charts plus a summary.json whose numbers are verified against the data. Charts must be generated from data, never hardcoded.",
-          "sha256": "fe7a7d00197b676cff35f62b1f098b39501c529b8dff93f034f716e623cd467b"
+          "sha256": "fd71dfd018467977e3430e61d290dfaf23ca888177af62bf4d81ac80a51da909"
         },
         {
           "lang": "zh-CN",
           "path": "courses/da-visualization/COURSE_cn.md",
           "title": "用 Agent 做数据可视化",
           "summary": "挑战课程——把干净的销售数据变成三张有规格的图和一份 summary.json，其中数字会与数据集校验。图必须由数据生成，不许硬编码。",
-          "sha256": "d4e4447b9f31c9c31936b94cc0985e9f37e36090da3c562dd6450dbf1147c7f8"
+          "sha256": "c67db40a964dbca98e46d61d6dbe5fb9bd4aa557bb49d9bb4af24e509e1281f5"
         }
       ]
     },

courses/da-eda/COURSE.md

@@ -2,7 +2,7 @@
 id: course-da-eda
 type: course
 title: Exploratory Data Analysis with an Agent
-summary: A challenge course — point your agent at a messy shop export and produce a verified EDA summary (results.json) whose numbers are checked against ground truth. First non-stdlib course in the catalog; pandas is managed with uv.
+summary: A challenge course — point your agent at a messy shop export and produce a verified EDA summary (results.json) whose numbers are checked against ground truth. First non-stdlib course in the catalog; pandas is pinned in requirements.txt.
 lang: en-US
 content_version: 1
 status: reviewed
@@ -37,7 +37,9 @@ This is the first course in the catalog that leaves the standard library:
 
 ```bash
 cd courses/da-eda
-uv sync            # or: pip install -r requirements.txt
+python -m venv .venv               # or: uv venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -r requirements.txt    # or: uv pip install -r requirements.txt
 ```
 
 `verify.py` checks for pandas and prints this hint if it is missing.

courses/da-eda/COURSE_cn.md

@@ -2,7 +2,7 @@
 id: course-da-eda
 type: course
 title: 用 Agent 做探索性数据分析
-summary: 挑战式课程——让你的 Agent 处理一份脏的商店导出数据，产出一份经过真值校验的 EDA 摘要（results.json）。目录中第一门非标准库课程；pandas 由 uv 管理。
+summary: 挑战式课程——让你的 Agent 处理一份脏的商店导出数据，产出一份经过真值校验的 EDA 摘要（results.json）。目录中第一门非标准库课程；pandas 版本固定在 requirements.txt。
 lang: zh-CN
 content_version: 1
 status: reviewed
@@ -35,7 +35,9 @@ course_id: course-da-eda
 
 ```bash
 cd courses/da-eda
-uv sync            # 或：pip install -r requirements.txt
+python -m venv .venv               # 或：uv venv
+source .venv/bin/activate          # Windows：.venv\Scripts\activate
+pip install -r requirements.txt    # 或：uv pip install -r requirements.txt
 ```
 
 `verify.py` 会检查 pandas，缺失时打印这条提示。

courses/da-eda/verify.py

@@ -7,8 +7,9 @@
 that the failing tests are the intended ones. ``progress`` prints the
 checkpoint claim codes for recording on flypython.com.
 
-Dependencies (pandas) are managed with uv — run ``uv sync`` (or
-``pip install -r requirements.txt``) inside this folder first.
+Dependencies (pandas) are pinned in requirements.txt — install them into a
+virtual environment inside this folder first (``python -m venv .venv``,
+activate it, then ``pip install -r requirements.txt``).
 """
 
 from __future__ import annotations
@@ -71,8 +72,9 @@ def _deps_available():
 
 def _deps_hint():
     print(
-        "pandas is not installed. Run `uv sync` (or "
-        "`pip install -r requirements.txt`) inside this course folder first.",
+        "pandas is not installed. In this course folder, create and activate "
+        "a virtual environment, then run `pip install -r requirements.txt` "
+        "(or `uv pip install -r requirements.txt`).",
         file=sys.stderr,
     )
 

courses/da-visualization/COURSE.md

@@ -33,7 +33,9 @@ A matplotlib script that produces `out/revenue_by_region.png`,
 
 ```bash
 cd courses/da-visualization
-uv sync            # pandas + matplotlib (or: pip install -r requirements.txt)
+python -m venv .venv               # or: uv venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -r requirements.txt    # pandas + matplotlib (or: uv pip install -r requirements.txt)
 ```
 
 ## Challenges (checkpoints)

courses/da-visualization/COURSE_cn.md

@@ -32,7 +32,9 @@ course_id: course-da-visualization
 
 ```bash
 cd courses/da-visualization
-uv sync            # pandas + matplotlib（或 pip install -r requirements.txt）
+python -m venv .venv               # 或：uv venv
+source .venv/bin/activate          # Windows：.venv\Scripts\activate
+pip install -r requirements.txt    # pandas + matplotlib（或 uv pip install -r requirements.txt）
 ```
 
 ## 挑战（检查点）

courses/da-visualization/verify.py

@@ -3,8 +3,8 @@
 
 Objective completion evidence for "Data visualization" (da-visualization).
 ``progress`` prints checkpoint claim codes for recording on flypython.com.
-Dependencies (pandas, matplotlib) managed with uv — run ``uv sync`` inside
-this folder first.
+Dependencies (pandas, matplotlib) are pinned in requirements.txt — install
+them into a virtual environment inside this folder first.
 """
 
 from __future__ import annotations
@@ -60,8 +60,9 @@ def _deps_available():
 
 def _deps_hint():
     print(
-        "pandas/matplotlib not installed. Run `uv sync` (or "
-        "`pip install -r requirements.txt`) inside this course folder first.",
+        "pandas/matplotlib not installed. In this course folder, create and "
+        "activate a virtual environment, then run `pip install -r "
+        "requirements.txt` (or `uv pip install -r requirements.txt`).",
         file=sys.stderr,
     )
 

docs/repo-plan-0.1.x.md

@@ -1,11 +1,12 @@
 # FlyPython 仓库 0.1.x 规划：社区贡献课程
 
 版本：0.1.x（规划，第 3 稿；2026-09-14 从 `repo-plan-0.1.0.md` 改名，避免与已发布标签混淆）
-更新日期：2026-09-19
+更新日期：2026-10-04
 状态：**规划，尚未立项。网站 0.1.0 已发布，前置条件已满足；但仍没有所有者批准的
 范围、负责人或实施提交，不能把本文件当成已开放社区课程贡献。后续是否立项由真实激活、
 维护容量和收费验收数据决定。**
-关联：网站仓库 `docs/product-and-growth-plan-0.0.9.md`（附录 B 记录了移出决定）·
+关联：网站仓库 0.0.9 计划附录 B 记录了移出决定（该文件已于 2026-10-02 删除，用
+`git show e16cb3c:docs/product-and-growth-plan-0.0.9.md` 查看）·
 网站仓库 `docs/courses/README.md`（课程标准）· 本仓库 `CONTRIBUTING.md`、
 `docs/CURATION_POLICY.md`、`LICENSE`
 
@@ -17,7 +18,7 @@
 - 官方示范（视频、终端回放、文字稿）是 Pro 专属；社区课是否配官方示范、如何开放，
   届时按网站当时的 Pro 规则另行决定。本规划不承诺社区课有示范。
 
-## 现状（2026-09-19 核对）
+## 现状（2026-10-04 核对）
 
 - `LICENSE` 已是双许可：代码（starter、solution、`verify.py`、工具）MIT；课文等书面
   内容 CC BY 4.0，署名「FlyPython (flypython.com)」。
@@ -28,8 +29,8 @@
   0.0.8 起课程文件夹单独取出也能运行 `python verify.py`。
 - 网站的课程数据与认领契约目前是手工镜像本仓库，每加一门课都要改网站代码——
   社区课一多就成为瓶颈（见第 6 项）。
-- 当前 `master` 为 `39a3e79…`，12 门公开课程已使用 learner verifier v2；社区课程
-  proposal、脚手架、CODEOWNERS、安全审查和自动接入仍全部未实现。
+- 12 门公开课程自 2026-09-16 起使用 learner verifier v2；社区课程 proposal、脚手架、
+  CODEOWNERS、安全审查和自动接入仍全部未实现。
 
 ## 待办（0.1.x 立项时细化）