docs: simplify workshop authoring and verification guidance

[GeekTrainer]

Summary

Layer 1/4 of the replacement stack for source #167, based on main: centralizes authoring guidance and adds small Bash and PowerShell wrappers that call existing verification commands. Following the YAGNI/reuse review, the custom verification engine, fixture framework, site capture hooks, and direct HTML-parser dependency declaration have been removed; source-page, semantic, translation, and visual inspection remain AI responsibilities.

Type of change

• Workshop content (lesson Markdown, images)
• Site shell (website/ Astro + Starlight wrapper)
• Copilot configuration (.github/copilot-instructions.md, instructions, agents, skills)
• Repo housekeeping (CI, dependabot, README, license)
• Other:

Verification

• Type checks and a clean site build pass. Ran the actual Bash wrapper by absolute path from /tmp: npm run check:all, clean website/dist, and npm run build. Zero type-check errors; four existing Astro deprecation hints remain. Bash syntax validation passed. Disposable probes exercised paths with spaces, another working directory, native failure exits 7/9/23, temporary-root cleanup, missing configuration, and refusal to remove a linked output directory.
• Affected pages and translations match their source and intended routes. Not applicable to this tooling-only update: curriculum sources are untouched, and the site configuration, content loader, and package manifests match pre-engine revision 5d881de byte-for-byte. The wrappers do not automate source-to-HTML or translation comparisons; the skill explicitly requires AI inspection of affected pages for content changes.
• Offline internal link checks pass. The Bash wrapper ran existing Lychee offline against the actual build: 17,798 total links, 2,617 unique, zero errors. Each invocation owns and cleans its temporary link root. No fixed page-count gate.
• Changed external links have been checked separately. Not applicable: no external URL changes.

Notes for reviewers

The current implementation is only scripts/verify.sh (32 lines) and scripts/verify.ps1 (53 lines), plus concise skill guidance. Both wrappers locate the repository from their script location, reuse package scripts, clean only website/dist with a link/file guard, and call offline Lychee. PowerShell uses npm.cmd on Windows and explicitly preserves native command exit codes. PowerShell was unavailable, so its wrapper is unexecuted and not parser-validated; no installation or execution-policy bypass was performed.

The latest simplification changes 12 paths, adding 112 lines and removing 686. All four custom engine/test .mjs files are deleted. The Astro configuration, content loader, package.json, and package-lock.json are restored exactly to their pre-engine contents; the original transitive parser dependency is preserved. There is no new dependency, capture integration, content-comparison engine, or committed fixture framework. Validation reused already-installed packages with local caches; temporary links and probes were removed.

Like the unchanged Pages workflow, the wrappers map the current /copilot-workshops/ base path to built output; the skill documents updating that mapping alongside the workflow if the site base changes. CI behavior remains unchanged: existing type checks, build, and pinned offline-link validation. The earlier Pages workflow change is comment-only.

Source-page inspection, semantic accuracy, teaching flow, translation quality, intentional harness differences, and visual/browser behavior remain AI responsibilities. Successful command execution does not prove exact rendered prose or correct translations. Existing plain-div admonition styling is unchanged. There is no current claim of a bundled 17-test verification framework; that framework was removed with the engine.

Curriculum files under docs/, deferred lesson-name examples in .github/instructions/markdown.instructions.md, and existing curriculum descriptions in shared authoring files remain untouched by this tooling follow-up. The draft stack order remains #169 → #174 (App) → #170 (VS Code/Cloud) → #171 (CLI). Source #167 is preserved unchanged; this update does not change stack membership, PR bases, draft state, or auto-merge settings.

[Copilot]

Copilot review overview

🟡 Changes recommended

The unresolved workflow inconsistency and duplicated verification procedures should be addressed before approval.

Get a fresh assessment by requesting another Copilot review.

Review tier: Lite
Findings: 1

Open (1)

• Keep browser validation on the canonical build path · New

What changed in this PR

This PR centralizes workshop authoring and verification guidance and adds Bash/PowerShell wrappers around existing site checks.

Changes:

• Replaces fixed page-count guidance with source/configuration-based inspection.
• Adds cross-platform verification wrappers.
• Updates contributor documentation, skills, CI guidance, templates, and Copilot instructions.

File	Summary
README.md	Points contributors to centralized verification guidance.
CONTRIBUTING.md	Documents CI checks and verification workflow.
AUTHORING.md	Adds lesson guidance and streamlined verification instructions. Nit (1 vote): Link the existing-lesson recipe to the canonical skill instead of repeating npm run dev.
.github/​workflows/​pages.yml	Updates CI description.
.github/​skills/​validate-site-playwright/​SKILL.md	Aligns browser validation with static verification. Nit (2 votes): Clarify or replace the separate build-only prerequisite.
.github/​skills/​README.md	Updates the skill index.
.github/​skills/​make-repo-contribution/​SKILL.md	References centralized verification guidance.
.github/​skills/​check-content-alignment/​SKILL.md	Simplifies content-alignment review. Moderate (1 vote): Align the related workflow’s exclusion rules and historical passage list with this procedure.
.github/​skills/​build-and-verify-docs/​SKILL.md	Defines wrapper-based verification and manual review responsibilities.
.github/​skills/​build-and-verify-docs/​scripts/​verify.sh	Adds the Bash verification wrapper.
.github/​skills/​build-and-verify-docs/​scripts/​verify.ps1	Adds the PowerShell verification wrapper.
.github/​pull_request_template.md	Updates the verification checklist.
.github/​instructions/​astro.instructions.md	Removes fixed page-count guidance.
.github/​copilot-instructions.md	Updates repository verification guidance.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.