docs(academy): public Hydra leerlijn — 6 chained Dutch tutorials

[WilcoLouwerse]

Summary

Publieke Nederlandstalige leerlijn over Hydra (Conductions agentic CI/CD-platform). Zes opeenvolgende tutorials die samen van "wat is Hydra" tot "spec → PR via de pipeline" lopen.

Audience-update (2026-05-19): oorspronkelijk opgezet als interne leerlijn (unlisted: true + warning-callouts). Per beslissing van @WilcoLouwerse nu volledig publiek gemaakt — zie comment hieronder voor details.

Closes ConductionNL/.github#50.

Test plan

• Lokale Docusaurus build (npm start) — sidebar toont de zes tutorials in volgorde
• Interne links tussen de zes pagina's werken
• Code-blocks en screenshots laden correct
• Compileert zonder warnings na merge van development + npm install

[MWest2020]

Code review — internal Hydra leerlijn

Overview

Adds an internal Dutch Hydra leerlijn (6 chained tutorials, unlisted: true) onto development. The diff is larger than the PR description suggests — it also contains 4 public Claude Skills tutorials, a data/app-downloads.json data refresh, package-lock.json deletions, and src/css/site.css additions for blockquote + .tutorial-quiz styling.

---

Blocking concerns

1. Audience framing is wrong — "ZZP-developers en partners onder NDA"

academy/2026-05-12-hydra-tutorial-1-wat-is-hydra/index.mdx:26:

"Deze leerlijn beschrijft IP van Conduction (skills, gates, prompts, pipelines) en is bedoeld voor medewerkers, vertrouwde ZZP-developers en partners onder NDA."

ZZP'ers horen er niet in als aparte categorie — Hydra is voor iedereen die het kan/wil gebruiken. De huidige framing is zowel te smal (singles out ZZP) als te restrictief (NDA-gated). Reword the warning callout in tutorial 1 (the other 5 tutorials use a shorter version on lines 282, 546, 797, 1164, 1535 which is fine — they don't mention ZZP). Re-evaluate whether the leerlijn should still be unlisted: true at all if Hydra is meant voor "een ieder die het kan/wil gebruiken" — the unlisted flag and the audience claim now contradict each other.

2. Scope creep — the PR claims 6 tutorials, contains 10 + data + lockfile + CSS

The PR title says "6 chained Dutch tutorials" but the diff includes:

• 6 Hydra tutorials (matches description) ✓
• 4 Claude Skills tutorials (2026-05-15-claude-skills-tutorial-1..4) — not mentioned in the PR body
• data/app-downloads.json — 314+/232- — appears to be an auto-generated stats refresh (new deskdesk entry, updated download counts, new release v0.1.3)
• package-lock.json — 86+/196- — pure deletions removing duplicated postcss-selector-parser@7.1.1 nodes (likely an npm dedupe)
• src/css/site.css — blockquote + .tutorial-quiz block styling

The Claude Skills tutorials look like the same set already merged to main (commits 11ab918, 7f91181, e1e4012) but not yet to development. This PR will resurrect them on development — fine if intentional, but the PR body should say so. Bigger concern: mixing content (tutorials), data (app-downloads.json), tooling (lockfile dedupe), and styling (CSS) in one PR makes rollback hard and the diff hard to audit. Suggested split:

• This PR: Hydra tutorials + CSS for quiz blocks (the CSS is genuinely used by the tutorials)
• Separate PR: forward-port of Claude Skills tutorials from main → development (or sync development from main)
• Separate chore PR: lockfile dedupe with npm audit signatures output attached
• Separate (probably automated) PR: app-downloads.json refresh

3. package-lock.json dedupe without verification log

Any lockfile change should land with npm audit signatures output recorded. The diff is benign-looking (only removes duplicate nested postcss-selector-parser v7.1.1 entries — no version bumps, no new resolved URLs), but the PR body says nothing about how this was produced. Confirm it came from a clean npm dedupe on top of a min-release-age=7-respecting registry session and post npm audit signatures output in the PR body before merge.

---

Smaller content notes

• Test-plan command vs. lockfile: PR body lists pnpm start, but the repo uses npm (package-lock.json, no pnpm-lock.yaml). Either the author ran pnpm against an npm tree (works but odd), or the test plan should say npm start.
• (private) repo link in prerequisites (tutorial 1, line 49): https://github.com/ConductionNL/hydra is listed as a prerequisite. Fine for an unlisted internal page, but worth aligning with the audience reframe from blocker Bump symfony/framework-bundle from 4.2.4 to 4.2.7 #1 — if Hydra is voor iedereen, a private-repo prereq excludes most of that audience. Either point at the public docs first, or list private-repo access as "if you're going to run it" not "to read this".
• Public .github link (tutorial 1, line 52): Links to ConductionNL/.github/blob/main/docs/hydra/README.md as "publieke 1-pagina-versie". Verify that page actually exists and is current before merging — the leerlijn leans on it as a warm-up.
• Date collisions: All 6 Hydra tutorials share date: 2026-05-12 and all 4 Claude Skills tutorials share date: 2026-05-15. Docusaurus should sort by partNumber within a series regardless, but worth a spot-check in the sidebar after build.
• Inconsistent unlisted flag: Hydra tutorials all set unlisted: true; Claude Skills tutorials don't. That matches intent (Skills = public, Hydra = internal), just calling it out so reviewers don't flag it as inconsistency.
• CSS scope: src/css/site.css adds a global blockquote brand restyle, which affects every blockquote on the site, not just academy tutorials. That's a site-wide visual change shipped in a tutorial PR — worth a separate design call-out, especially if marketing pages rely on the current neutral blockquote look.

---

Recommendation

Fix the ZZP framing in tutorial 1, decide whether unlisted: true is still correct after broadening the audience, and either split the unrelated changes (Claude Skills tutorials, app-downloads.json, lockfile dedupe, global blockquote CSS) into separate PRs or update the PR body to declare them explicitly. Content-wise the Hydra leerlijn itself reads well — the issues are framing, scope, and supply-chain hygiene around the bundled lockfile change.

[MWest2020]

Specter weg.

[WilcoLouwerse]

Review-response op @MWest2020 (review 2026-05-18)

Hieronder per punt wat er is aangepakt en wat (bewust) niet.

Blocking concerns

1. Audience framing — ZZP-developers/NDA
Beslist: leerlijn gaat volledig publiek. Concrete wijzigingen in commit ff20e9d3:

• unlisted: true verwijderd uit frontmatter van alle 6 tutorials
• :::warning Intern document callout verwijderd op alle 6 pagina's
• Intern-tag verwijderd uit alle frontmatter
• ZZP-specifieke framing in Deel 1 callout was al weg vóór de publiek-flip
• Private repo (ConductionNL/hydra) prereq in Deel 1 verplaatst onderaan met expliciete framing "alleen nodig als je Hydra zelf wilt draaien"

2. Scope creep — bundled changes
Per beslissing: niet splitsen. Toelichting:

• Claude Skills tutorials (4 bestanden) zaten op deze branch omdat ze tegelijk zijn ontwikkeld. PR academy: public Claude Skills leerlijn (4 chained Dutch tutorials) #46 (Claude Skills) is op 2026-05-18 gemerged in tutorial/hydra-leerlijn-intern (deze branch), niet in development of main — ze staan dus nog gewoon in de diff van deze PR en landen via docs(academy): public Hydra leerlijn — 6 chained Dutch tutorials #37 op development. Correctie t.o.v. eerdere versie van deze response: er was geen aparte main→dev-route.
• data/app-downloads.json — automatisch ververst door prebuild hook; niet menselijk bewerkt.
• src/css/site.css — bevat zowel .tutorial-quiz styling (hoort logisch bij quiz-blocks in tutorials) als de blockquote-restyle. Die laatste is nu gescoped aan .markdown (commit ff20e9d3) zodat marketing-pages ongewijzigd blijven.

3. Lockfile dedupe + npm audit signatures
Tussen je review (18 mei) en nu was er een serieuzere divergentie ontstaan: deze branch zat op @conduction/docusaurus-preset@2.1.0, terwijl development doorgebumped is via #55 t/m #79 naar ^3.6.0/3.10.0. Merge-as-is zou dat hebben gedowngrade.

Opgelost door git merge origin/development (commit d865f17f) + npm install (commit 034c6927). Lockfile is nu de schone uitkomst van een npm install op de gemergde package.json, niet langer een dedupe.

npm audit signatures zelf werkt niet op deze tree door een bekende npm-aliasing-bug (react-loadable@npm:@docusaurus/react-loadable@6.0.0 faalt registry-lookup met ETARGET). Speelt ook op development, niet door deze PR veroorzaakt. Output ter info:

npm error code ETARGET
npm error notarget No matching version found for react-loadable@6.0.0.

Reguliere npm audit rapporteert 21 vulnerabilities (2 moderate, 19 high) — allemaal pre-existing op development, niet beïnvloed door deze PR.

Smaller content notes

• Test plan pnpm → npm: PR body bijgewerkt.
• Public .github-link in Deel 1 prereqs: gecheckt — .github/docs/hydra/README.md bestaat (5402 bytes).
• Date collisions: bewust ongewijzigd gelaten — Docusaurus sorteert binnen een series op partNumber, niet op datum.
• Inconsistent unlisted flag: nu consistent — geen enkel bestand heeft unlisted: true.
• Global blockquote CSS: gescoped naar .markdown blockquote zodat marketing-pages niet meer worden aangeraakt.

Status

• Build groen (lokaal npm start, geen warnings na merge)
• Klaar voor herziene review

[WilcoLouwerse]

Goed om misschien eerst deze te mergen:
#73

[MWest2020]

Specter weg ✅ — geverifieerd op PR-head (88d8b978): 0 matches voor specter/spectre in de volledige diff en per-file in alle zes Hydra-tutorials. Eerdere blocking concerns (ZZP/NDA-framing, lockfile dedupe, scope) zijn afgehandeld in de review-response.