[pull] master from flypythoncom:master - #23

… and modernized tooling

- Add 3 new runnable examples: pydantic-validation, mcp-server, and async-fetcher
- Add 3 new task playbooks: write-llm-evals, setup-structured-logging, manage-database-migrations
- Add 3 new depth guides: modern-typing, async-patterns, and context-budget
- Add 8 new reviewed catalog resources (Ruff, Mypy, SQLAlchemy, Alembic, Polars, DuckDB, Instructor, MCP)
- Initialize Project Radar evaluated projects list in catalog/projects/
- Add reusable templates for agent IDE rules, eval records, and API specifications
- Modernize pyproject.toml and add Makefile for unified development tasks
- Generalize example verification and test discovery across all examples
- Re-export catalog.json, content-manifest.json, and rendered bilingual READMEs

… uv modernization

- Rewrite the mcp-server example for the stateless 2026-07-28 spec: no
  initialize handshake, per-request _meta.protocolVersion validation, and
  the input_required round-trip via params.inputResponses (8 tests).
- Add bilingual migration guide guides/mcp/migrate-2026-07-28 covering the
  removals, deprecations, authorization hardening, and a migration checklist.
- Add the four official MCP/AAIF announcement sources to the reviewed catalog;
  regenerate catalog.json, README catalogs, and the content manifest (19 docs).

- Add bilingual docs/repo-plan-0.0.3 (courses/ spec, radar data model,
  radar_scan tool, contract updates, referral overhaul, FP-325~344)
- Add dual LICENSE: MIT for code/examples/tools/templates, CC BY 4.0 for
  written content — prerequisite for distributing course folders
- CURATION_POLICY: extend scope to courses + radar, add radar lifecycle
  statuses and ai_familiarity grading, update licensing section
- AGENTS.md: content ships EN+ZH in the same change; governance docs are
  English-canonical

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

…ontracts

- courses/ content type with the flagship Claude Code hands-on course
  (EN+ZH lessons, three scenario skins, task contract, starter/solution,
  verify.py objective evidence, REVIEW.md record)
- tools/verify_courses.py course-contract verifier wired into Makefile and CI
- catalog/projects/ per-project YAML (7 seeds) with ai_familiarity,
  bilingual generated Radar tables, radar.json export + radar-v1 schema,
  and --target both support in export_catalog.py
- tools/radar_scan.py read-only candidate discovery (GitHub/PyPI/HN) with
  the no-verdict guarantee enforced by tests
- content-manifest schema + builder gain the course type
- course-feedback issue template; llms.txt courses and radar sections
- README course banner plus contextual flypython.com footers on every
  guide, playbook, and example per REPO_TO_WEBSITE.md

C2 'Hands-on with OpenAI Codex CLI' ships EN+ZH lessons, the same three
scenario skins and the same verified starter/solution/tests contract as C1
per the 0.0.3 plan reuse rule; REVIEW.md records the mechanical verification
with the live Codex run-through logged as pending launch evidence.

GitHub moved jxnl/instructor to 567-labs/instructor; the radar entry and the
generated radar.json/README tables now use the canonical URL so the site's
external-link gate stays green.

- C3 'One source of truth for agent rules': new stdlib rules_check.py core
  (source/pointer/copy/drift classification + CLI exit codes, 11 tests)
- C4 'From it runs to it ships': new stdlib ship_check.py core (parsed test
  counts, no-tests verdict, unverified list, atomic SHIP-RECORD.json,
  10 tests) with green/red/no-tests scenario projects
- C5 'Give your agent tools with MCP': assembled from the reviewed
  examples/mcp-server contract plus wire-format request samples
- All five courses EN+ZH with COURSE teaching contracts, scenario skins,
  TASK contracts, REVIEW records, and verify.py both-directions evidence

Planning draft for the local-first challenge/badge layer in course folders:
verify.py progress writing PROGRESS.json, badge contract and challenge
narrative (EN+ZH), gated BADGE.md artifact, SKILL.md packaging evaluation,
and verify_courses.py coverage. Carries the open 0.0.3 release mechanics
forward.

Rev 2 superseding the local-first draft: the website records progress from
deterministic checkpoint claim codes printed by verify.py (FP-411), the
challenge/badge narrative points at the site recording flow (FP-412), badge
metadata becomes structured course data (FP-413), and verify_courses.py
gains claim-code determinism coverage (FP-415). Local-only artifacts are
dropped.

M0 intro module (agent tool ecosystem overview), the dual-agent route
challenge, and paths/foundation/ contract reusing the live C1-C4 courses
as modules 1-4; full path system defined in the site's LEARNING-PATHS.md.

- Claim code = flag contract; serves local challenge loop first,
  website server recording later
- FP-412 reframed: learner solves challenges; COURSE.md becomes
  optional guided-mode entry
- Agent-solvability is a launch gate for every challenge
- No repo work pairs with website phase B until catalog depth met

- Course folder retrofit: TASK.md as challenge entry, COURSE.md as
  optional guided mode, badge frontmatter contract, claim-code
  derivation (salt + course_id + checkpoint_id + evidence_hash)
- paths/ layer: PATH.md structured contract, capstone challenge,
  points table (10/50/200)
- Contract follow-ups: manifest type 'path', curation scope, README
  narrative, solvability records in REVIEW.md
- Landing order: C1 pilot -> C2-C5 rollout -> foundation path ->
  DA courses

Merges feat/0.0.3-courses-and-radar: the five-course batch (C1-C5,
EN+ZH), per-project Radar YAML with radar.json + schema, claim-code
 groundwork plan (0.0.4 docs), README referral, and the instructor
canonicalization.

ubuntu-latest images now ship an externally-managed system Python
(PEP 668), so 'uv pip install --system' refuses to install and the
Validate workflow dies at the dependency step. Create the project venv
from the matrix interpreter and run every gate through 'uv run'.

'uv run' re-syncs the project environment and rebuilds it on the system
interpreter, dropping uv-pip-installed tools like ruff. Invoke the venv
binaries directly so the matrix interpreter and installed tools are
exactly what runs.

…(FP-411/412/415)

- verify.py gains a progress subcommand per course: per-checkpoint status
  derived from the objective suite (l03 starter-suite, l04 both-suites)
  plus learner-attested checkpoints (l01/l02/l05), each printing a
  deterministic 8-char base32 claim code derived from documented
  per-course constants (FP-411)
- COURSE.md/COURSE_cn.md gain the badge contract section (badge id, name,
  points, honest self-reported-evidence framing), content_version 2,
  manifest regenerated (FP-412)
- verify_courses.py validates the progress contract: double-run
  determinism, document shape, five checkpoints, claim-code format
  (FP-415)

…13/416/417/418)

- Three new challenge courses: da-eda (pandas EDA, 12 tests),
  da-visualization (matplotlib charts, 5 tests), da-report (structured
  report, 6 tests) — first non-stdlib courses, deps pinned via
  requirements.txt and dev lock (pandas 2.3.3, matplotlib 3.10.9)
- paths/foundation + paths/data-analysis path contracts (path.json)
  with M0 orientation, dual-agent route challenge, and a 303-row
  capstone challenge with ground-truth verify.py + claim code
- Structured badge metadata (badge + course_id frontmatter) on all
  eight courses for website rendering (FP-413)
- tools/verify_paths.py: path contract checks (bilingual fields,
  badge block, sequential orders, course/module ref resolution)
  wired into make check and validate.yml
- manifest type 'path' + schema enum; paths/**/*.md in CONTENT_GLOBS;
  CURATION_POLICY scope + bilingual README narrative updated for the
  challenge model; output artifacts gitignored

- Inject progressive per-checkpoint hints into all 40 checkpoint pairs
  (80 EN/ZH lesson files); DA lessons gain full frontmatter so they
  enter the content manifest like the other courses.
- paths/foundation/path.json declares the first-agent branch group so
  the site can treat Claude Code / Codex modules as alternatives.
- Record real-agent solvability runs (Devin, SWE-2 Max) in all 8 course
  REVIEW.md files — challenge-mode runs with observed deviations noted;
  starters restored and --expect-failure re-verified.
- Regenerate content-manifest.json; update repo-plan status lines.
- Verified: verify_courses (8/8), verify_examples (5/5), manifest,
  catalog export, and readme rendering checks all green.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

# Conflicts:
#	docs/repo-plan-0.0.4.md

Licensing and entry points:
- CONTRIBUTING permissions now match the dual MIT/CC-BY LICENSE
- README_cn hero rewritten for the challenge-platform narrative (TASK.md
  contracts, verify.py claim codes, paths badge routes)
- llms.txt: fix four template paths, add the three DA courses, refresh
  tagline and Radar description

Indexes and governance docs:
- README/CONTRIBUTING/AGENTS: complete the CI check list
  (verify_courses, verify_paths, --target both), add courses/, paths/,
  radar.json to the structure diagram, dependency-aware course contract
- CHANGELOG: record post-0.1.0 0.0.4 phase A under [Unreleased]
- CONSUMING: document radar.json as the third pinned export
- repo-plan-0.0.4: mark FP-334 done (v0.1.0)

Courses and examples:
- mcp-server-in-python: fix stale examples/mcp-server verify path in
  TASK pair; expect-failure now requires all named failures; REVIEW
  wording matches the actual scenario layout
- da-report: remove the unused pandas gate (verify.py, requirements,
  COURSE pair) — the course is stdlib-only
- agent-rules L01 pair: add the missing verifier command
- product-slug: fix punctuation-before-collapse ordering so removed
  punctuation cannot create duplicate separators; regression test added
- async-fetcher: solution uses asyncio.TaskGroup; TASK pair states the
  total-attempts retry semantics
- structured-pipeline: solution actually iterates in batch_size batches
- pydantic-validation: honest stdlib-by-design note (EN+ZH) and accurate
  verify message
- align DA badge ids to the course- prefix convention

Bilingual parity and paths:
- templates: add CODE_REVIEW/IMPLEMENTATION_PLAN CN pairs and link them
  from both indexes; fix EVAL_RECORD/AGENT_RULES CN drift
- guides: fix async-patterns_cn example, modern-typing_cn dropped
  clause, migrate guide EN em-dash sentence
- playbooks: CN footers deep-link the same resources anchors as EN
- paths: add README pair, resolve undefined C1-C4 labels to course
  slugs, link the index from the main READMEs

Hygiene:
- drop committed course .venv/__pycache__ artifacts, ignore
  .pytest_cache, exempt starter scaffolding imports from ruff F401

Validation: pytest 136 passed; ruff clean; catalog/radar/README/manifest
checks current; 5 examples, 8 courses, 2 paths verified.

- Rename hands-on-with-openai-codex-cli → hands-on-with-openai-codex and
  rewrite all content for the Codex desktop app (threads, approvals,
  AGENTS.md, diff review); course_id course-codex-cli and salt preserved.
- Add four new report-tool core courses authored from official docs:
  hands-on-with-cursor, hands-on-with-deepseek-harness,
  hands-on-with-kimi-code, hands-on-with-zcode. Each ships EN+ZH
  COURSE/lessons, honest REVIEW.md (docs-authored, live run-through
  pending), and a verify.py with its own course_id + salt.
- Enforce shared-core byte equality via core-group marker checked by
  tools/verify_courses.py.
- Foundation path: first-agent branch now offers all six tools; m0
  orientation and route-challenge rewritten accordingly (any two tools).
- tools/claim_receipt.py + verify.py receipt support and
  build_solution_hashes.py → course-solutions.json (claim receipts A-side).

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

…urse lesson 1 rework

FP-820: python verify.py (no args) is the learner's command on all 12
free courses, 3 pro courses, and the data-analysis capstone - suite
status, per-checkpoint claim codes, English-first output, non-zero exit
while gated checkpoints are open. Published progress --json and
--receipt-out formats unchanged; the four explicit usages stay for
maintainers.

FP-821: verify_courses.py copies each course plus tools/claim_receipt.py
into an isolated tree and enforces the default command + receipts there.

FP-822: six agent-tool courses' lesson 1 (EN+ZH) rewritten to the fixed
order tool -> FlyPython Skill (network on) -> agent fetches the course
files; download wording removed from COURSE.md and lessons; solution no
longer the completion standard.

FP-823: prose checkpoints in three 0.0.3 courses became question lists
for the human-in-the-loop gate.

FP-824: README/README_cn start section leads with the Skill entry
sentence and the six tool courses.

…0.1.0)

First draft from the parallel planning session: permanently-free community
courses, review states, and open questions. Referenced by the website's
0.0.9 plan revision 4.

- paths/foundation: m0 orientation is now an optional extra-credit module
  (never first step, never badge-required); verify_paths understands
  "optional" and badge math excludes it. Route-challenge copy: the module
  pages live on flypython.com now, repo keeps the canonical markdown.
- six tool-course L01s (en+zh): step 2 pre-installs the Skill as optional
  (the entry sentence reads it from the URL); starter failure count
  corrected to "five classes + two end-to-end consequences = seven named
  failures".
- READMEs: new positioning line, same change both languages.

make check green (12 courses, 2 paths).

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

FP-1012: docs/repo-plan-0.1.0.md -> docs/repo-plan-0.1.x.md (community
courses are a post-launch 0.1.x track, not the launch version); CHANGELOG
gains the 0.0.9 and 0.1.0 sections recording FP-983/FP-984 and the rename.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

FP-1012: pyproject 0.1.1 (the v0.1.0 tag stays immutable on e420fca);
CONTRIBUTING gains the release/tag rules — tags immutable, independent
repo/website versions linked by CHANGELOG + Release mapping, website
consumes only a pinned full SHA. CHANGELOG records the v0.1.0-website /
v0.1.1-repo compatibility.

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>