Update docs after Markdown migration

Author: adewale

.github/workflows/verify.yml

@@ -31,6 +31,8 @@ jobs:
           cat /tmp/pythonbyexample-ci.log
           exit 1
       - name: Verify
+        env:
+          CHROME_PATH: /usr/bin/google-chrome
         run: |
           make verify
           scripts/check_example_migration_parity.py

CHANGELOG.md

@@ -19,14 +19,18 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0
 - Versioned Worker Cache API keys for rendered HTML.
 - `README.md` architecture, verification, deployment, and cache-busting documentation.
 - `docs/lessons-learned.md`.
+- Markdown-backed example sources with `:::program` and `:::cell` blocks.
+- Example source verifier, formatter, embedded-source build step, and golden parity check.
+- GitHub Actions verification workflow.
 
 ### Changed
 
 - Example walkthroughs now pair prose, source fragments, and output evidence.
 - Read-only code highlighting is handled by Shiki; editable code highlighting is handled by CodeMirror.
 - Prototype routes under `/layout-options/*` bypass the Worker Cache API and return `Cache-Control: no-store`.
 - Static assets use immutable cache headers only on fingerprinted filenames.
-- Deployment flow now regenerates asset fingerprints first.
+- Deployment flow now regenerates embedded example data and asset fingerprints first.
+- `src/examples.py` is now a compatibility shim over Markdown example sources.
 - Output panels reserve space for execution timing to prevent layout shift after runs.
 
 ### Fixed

README.md

@@ -77,13 +77,20 @@ http://localhost:9696
 
 ## Verification
 
-Run the main checks before deploying or pushing:
+Run a local Worker before the full browser-backed verification:
+
+```bash
+uv run --group workers pywrangler dev --port 9696
+```
+
+Then run the main checks before deploying or pushing:
 
 ```bash
 make verify
 scripts/check_example_migration_parity.py
 scripts/format_examples.py --check
 make verify-python-version VERSION=3.13
+git diff --check
 ```
 
 `make seo-cache-lint` verifies that:
@@ -138,19 +145,14 @@ Prototype layout routes under `/layout-options/*` bypass the Worker Cache API an
 Run checks, then deploy:
 
 ```bash
-scripts/fingerprint_assets.py
-make test
-make seo-cache-lint
-make browser-layout-test
-uv run pywrangler deploy
-```
-
-or:
-
-```bash
+make verify
+scripts/check_example_migration_parity.py
+scripts/format_examples.py --check
 make deploy
 ```
 
+`make deploy` runs `make build` first, so embedded example data and cache fingerprints are regenerated before Wrangler deploys.
+
 ## Updating examples or Python version
 
 Edit Markdown files under `src/example_sources/`.
@@ -169,6 +171,7 @@ make build
 make verify-examples
 scripts/format_examples.py --check
 scripts/check_example_migration_parity.py
+make check-generated
 ```
 
 `src/example_sources_data.py` is generated and committed so Cloudflare Workers can load examples in production. Do not edit it by hand.

docs/example-source-format-spec.md

@@ -140,8 +140,8 @@ Investigation and verification tasks come first because they decide the implemen
 - [ ] Smoke-test `https://www.pythonbyexample.dev`.
 - [ ] Smoke-test `https://pythonbyexample.adewale-883.workers.dev`.
 - [ ] Verify production asset caching and HTML cache-busting after an example-only edit.
-- [ ] Remove old hand-authored example catalog only after one successful production deployment.
-- [ ] Remove temporary golden parity scaffolding after cleanup is complete.
+- [ ] Keep the frozen golden fixture through at least one stable production release cycle and rollback window.
+- [ ] Remove temporary golden parity scaffolding only in a dedicated cleanup PR after CI and production confidence are established.
 - [ ] Update README contributor instructions to point contributors at Markdown examples, `make build`, and `make verify-examples`.
 
 ## Implementation milestones
@@ -151,7 +151,7 @@ This migration must not be implemented as one large switch-over.
 1. **Tooling-only milestone** — add Markdown sources, canonical loader, build scripts, verifier, formatter, and golden parity checks while the live app still imports `src/examples.py`.
 2. **Dual-read milestone** — allow tests to load both `src/examples.py` and Markdown examples; keep `src/examples.py` as the public catalog until parity is clean.
 3. **App switch milestone** — switch `src/examples.py` to a thin compatibility layer over the Markdown loader only after local Worker startup, browser layout checks, and 100% golden parity pass.
-4. **Cleanup milestone** — remove the old hand-authored catalog and golden fixture only after one successful deploy and smoke test on both `www.pythonbyexample.dev` and the `workers.dev` hostname.
+4. **Cleanup milestone** — remove the old hand-authored catalog immediately after the app switch, but keep the golden fixture until a stable production release cycle, rollback window, and dedicated cleanup PR.
 
 Each milestone should be independently reviewable and revertible.
 

docs/lessons-learned.md

@@ -34,6 +34,9 @@ This document records project lessons that should guide future changes to Python
 - Avoid decorative labels that do not teach. Labels such as `Cell 1 · <<fragment-1>>` add noise unless the fragment name is meaningful to the learner.
 - If a source fragment only prepares state and has no output, merge it with the next fragment that produces output. Every displayed cell should have evidence.
 - Keep the complete editable program visible because it is the thing that actually runs.
+- When storing examples as Markdown, keep the full editable program in `:::program` and teaching fragments in separate `:::cell` blocks. Do not concatenate cells to recreate the editor source.
+- Fine-grained cells can restate definitions to stay executable. This is better than collapsing class, property, recursion, match, or type-hint examples into one large cell.
+- Preserve a frozen golden catalog while migrating source formats. Full stdout parity is not enough; rendered teaching-cell structure must also match.
 
 ## Layout and mobile
 
@@ -47,16 +50,18 @@ This document records project lessons that should guide future changes to Python
 - Unit tests are good for catalog integrity, rendering contracts, Dynamic Worker code generation, and cache-policy source checks.
 - Browser tests are necessary for Shiki/CodeMirror layout behavior and visual regressions.
 - SEO and cache-busting deserve a dedicated linter because errors are easy to reintroduce when adding pages or assets.
-- Always run the full pre-push set before publishing:
+- Always run the full pre-push set before publishing. Start `pywrangler dev --port 9696`, then run:
 
 ```bash
-make fingerprint
-make test
-make seo-cache-lint
-make browser-layout-test
-make lint
+make verify
+scripts/check_example_migration_parity.py
+scripts/format_examples.py --check
+make verify-python-version VERSION=3.13
+git diff --check
 ```
 
+- `make check-generated` should fail if embedded example data, asset manifests, or cache headers are stale.
+
 ## Documentation and GitHub readiness
 
 - Keep generated runtime directories out of Git: `.wrangler/`, `.venv/`, `.venv-workers/`, and `python_modules/`.

scripts/check_browser_layout.mjs

@@ -4,7 +4,9 @@ import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 
-const chromePath = process.env.CHROME_PATH || '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+const chromePath = process.env.CHROME_PATH || (process.platform === 'darwin'
+  ? '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+  : '/usr/bin/google-chrome');
 const target = process.argv[2] || 'http://127.0.0.1:9696/layout-options/mobile-run-first';
 const url = `${target}${target.includes('?') ? '&' : '?'}browser_layout_check=${Date.now()}`;
 const port = 9333 + Math.floor(Math.random() * 1000);