Install course illustrations and show learner transformation on family landings

[alexeygrigorev]

User intent

The user approved the new course illustration set, then clarified: “no need for zip archive - put them in the pages.” They still see old illustrations at http://127.0.0.1:8091/courses and http://localhost:8000/courses/ml-zoomcamp, and ask to update all course images. Deliver an installed, locally rendered result, not an archive or a browser-only preview swap. After seeing the oversized ML family hero, the user requested a proper landing page that shows the learner transformation, explicitly invoked the adversarial-design-review skill, and asked to continue. The family landing must explain the value of the course, not merely display a smaller illustration.

Normative references

• _docs/specs/04-courses-and-cohorts.md: reusable Course family ownership and public catalogue behavior.
• _docs/specs/02-url-link-seo-compatibility.md: preserve established /courses and /courses/<family> routes.
• _docs/design/design-system.md: decorative image semantics, shared shell, reserved slots, responsive and theme behavior.
• _docs/design/illustration-assets.md and website illustration workflow: genuine transparency, lossless encoding, source-specific quality and real-page checks.
• _docs/architecture/database-only-content.md: static design assets are permitted; course records and visible captions remain database-owned.
• _docs/ci/change-selective-ci.md and _docs/PROCESS.md: verification and independent tester/PM gates.

Scope

Install the six approved light-theme illustrations from .tmp/course-illustrations-20260915/png/ as native-size 1254 × 1254, transparent, lossless WebP static assets. Families are ai-dev-tools-zoomcamp, de-zoomcamp, ml-zoomcamp, mlops-zoomcamp, llm-zoomcamp, and sma-zoomcamp. The ML source is the corrected approved exported PNG, not the rejected earlier edge-removal result.

The user's later LLM quality objection authorizes a targeted imagegen correction of that scene. Its newly reviewed native PNG replaces the earlier LLM source after acceptance; preserve the learner/documents/grounded-answer story while correcting ambiguous limb connections and the coarse cloud boundary. Each robot must have exactly two clearly connected shoulder→arm→hand paths, and the cloud must have a clean irregular coverage fade without key spill, sawtooth noise, abrupt opacity, halo, or fabricated pixel texture. Inspect foreground and the complete cloud at native and enlarged sizes on actual cream/white consuming surfaces. Preserve the other five accepted scene compositions and all unrelated/dark assets; an edge repair elsewhere is limited to a demonstrated in-scope edge defect.

Use one shared decorative-asset association keyed by the actual Course family slug. Apply it to every matching family hero and the existing catalogue hero collage. The collage must retain family identity when pairing its database title with artwork; its existing bounded number/order of cards need not change. Unrecognized families retain a generic illustration fallback. A slug-to-static-asset association is presentation configuration, not a new public-content source.

Replace all three existing course-card “mascot needed” placeholder branches with that family's shared illustration, while retaining any explicitly authored campaign image. The user expressly wants the original course catalogue cards preserved: keep the open-registration, running and self-paced sections, course cards, captions, ordering, actions and membership. A placeholder-art update does not authorize dropping or replacing those components.

The user also objected to the blurb against the collage's white framed background, then explicitly clarified that the original cards must be preserved. Retain all four hero cards, their design-system borders/shadows and database captions; use a cream rather than white card ground, an aligned regular two-by-two group, compact artwork scale and no rotations. This is the independently accepted interpretation of the user's final card-preservation constraint and supersedes the earlier proposed removal of all frames/shadows. Do not delete hero or listing cards, replace them with a different component, or turn this into a full catalogue redesign. Only the bounded card art/surface treatment changes.

Keep the existing independently generated dark artwork and its theme behavior. No dark generation was approved in this set; do not synthesize dark variants with filters or mechanically recolor light images. Preserve unaffected assets, catalogue layout, actual destinations, registration behavior, public visibility, and the mobile art visibility policy. The shared family landing layout and hierarchy may change as described below.

Update the owning asset record/workflow to distinguish concepts from installed assets and explicitly require installing and verifying the actual pages when the user requests installation. Retain the earlier feedback: relevant learner action/course outcome, builtin imagegen without a key detour, documented latest versus actual backend honesty, and actual pixel checks rather than assuming PNG means clean.

The user has repeated a standing tool instruction: use the imagegen skill and built-in imagegen tool, and never ask them to configure OPENAI_API_KEY for image generation or inspect credentials for model selection. If the built-in tool exposes neither model selection nor reliable version metadata, continue using it and record the backend as unverified. Save this preference in the applicable agent/workflow instructions; a documented latest model is not proof of the backend actually used.

The user also asked to save useful temporary scripts. Promote only reusable chroma-finishing and decoded-pixel/alpha verification helpers under .agents/skills/website-illustrations/scripts/, and the configurable actual-host browser screenshot/check helper under scripts/dev/, with usage guidance and focused tests. Use uv, keep image dependencies outside the website runtime where practical, accept explicit input/output/host options, and save outputs below .tmp/. One-off course-copy payloads, DB snapshots, generation intermediates, screenshots and throwaway scripts remain scratch data, not checked-in public-content sources.

User refinement: transformation-led family landing

The latest request supersedes the earlier size-only refinement. The individual family landing should answer, in order: where the learner starts, which practical skills/process they work through, and what they can build by the end, with real curriculum/project evidence and a clear next action. Use Machine Learning as the representative page and implement the shared narrative consistently for all six families. Lead with a course-specific built outcome beneath the course title; show an explicit starting point → at least three evidenced skill concepts → built artifact before registration logistics dominate the page. Bring genuine project briefs, submission-gallery destinations, and published testimonials into the evidence story where those records exist. Administrative project-attempt titles/states are not examples of learner-built products.

The illustration must support this narrative without dominating the opening viewport. Keep its native source pixels and square containment; approximately 280–360px on ordinary desktop is a review direction, not a user-mandated 352px cap. The hero should reveal its outcome, principal action, and the start of the first value section at 1440×900; the initial transformation should remain understandable within the first two mobile screens. Heading hierarchy and section ordering may change within the existing design system. Preserve mobile hidden-art behavior and the catalogue collage layout.

Minimal database-owned content path

Repository inspection found Course.description and Course.outcome, but no learner starting-state field. Five families have existing descriptions/outcomes; ML has neither, although its public cohort description and curriculum establish its subject matter. Add one optional, blank-default Course.starting_point text field for the explicit before-state, reuse the existing Course.outcome for the after-state, and compose the process/proof from the existing published curriculum, homework, project and testimonial records. No generic landing-content JSON schema, extra one-to-one model, hardcoded per-slug copy, or runtime file fallback is needed for this scope.

Author the required six families' local DB content deliberately from existing public course records and verified course-owner material, with a recorded source/rationale and a reversible before/after content record. Fill ML's missing course outcome rather than inventing a runtime fallback. A starting-state statement is a learner framing, not an unverified prerequisite claim. The new DB-managed field must survive curriculum re-import; existing description/outcome import ownership remains unchanged and any later import overwrite must be documented, not hidden. Do not seed authored public copy in migrations or tests-as-production content. Keep optional fields safely absent for unknown or uncurated families.

The user's explicit adversarial-design-review request adds an independent design acceptance gate before final acceptance. The assigned reviewer owns the concrete rendered contract and must explicitly return ACCEPT after checking the full family set, corrected artwork, affected catalogue surfaces and representative states. Concurrent certificate work in the shared template remains another owner's change surface: preserve those edits and coordinate any truthful conditional messaging adjustment required by the redesigned narrative. Do not imply that a self-paced cohort automatically earns a certificate. Restoring known pre-existing certificate markup lost to an unrelated concurrent Git operation is preservation, not permission to claim its full implementation as issue #401 work.

Non-goals and boundaries

• No deployment, push, archive deliverable, or changes to unrelated worktree edits. Targeted LLM correction, the single narrative field/migration and sourced local course-copy updates above are in scope. The user has now explicitly requested focused local commits after the independent gates pass; this supersedes the initial no-commit boundary but does not authorize pushing.
• No replacement of homepage artwork or generic fallback assets used by other pages.
• No full catalogue redesign, removal of original catalogue components, or changes to authentication/authorization/API behavior. Existing placeholder art slots and the bounded collage surface refinement above are in scope.
• No new dark companions and no claim that the approved light set covers dark-theme regeneration.
• No new authoring product, curriculum-format redesign, automatic copy generation, invented numerical/career/financial outcomes, unverified prerequisites, or fabricated project/testimonial evidence.

Dependencies

Approved local source assets and course records already exist. The independent design reviewer has inspected the current family pages and supplied a narrative/render contract; implement against that contract and obtain an explicit final ACCEPT. Both user-supplied local hosts must be checked; any serving-process/static-cache issue that prevents the working-tree installation from appearing must be identified and resolved only within local task scope. No production deployment authority is implied.

Acceptance criteria

• All six approved PNGs have installed transparent, lossless WebP equivalents at native dimensions, with provenance sufficient to identify the approved source and verify decoded pixel equivalence; unrelated illustration bytes remain unchanged.
• The corrected LLM image has unambiguous two-arm anatomy and a clean, intentionally irregular watercolor fade on actual cream/white surfaces at native and enlarged scale. Its reviewed source/provenance supersedes the rejected earlier LLM artwork; no CSS masking, blur, denoising or lossy encoding conceals the defect.
• Each of the six /courses/<family> light-theme heroes requests its matching newly installed static asset through ordinary server rendering, including /courses/ml-zoomcamp; no browser intercept is needed.
• The /courses light-theme collage uses each displayed family's own new illustration rather than an index-based cycle of unrelated homepage/reading artwork. Captions, ordering, membership, and other public course data remain database-owned and preserve existing behavior.
• All three existing catalogue placeholder branches show matching course art while retaining authored campaign images. Original open-registration/running/self-paced cards, sections and functional destinations remain present; no “mascot needed” placeholder remains in those branches.
• All four original hero cards remain, with cream (not white) ground, existing design-system borders/shadows, matching artwork at compact scale, database captions, and an aligned regular two-by-two arrangement without rotations. The blurb is reviewed on its real card surface; all original open-registration/running/self-paced listing cards also remain. The user's final preserve-cards instruction supersedes the earlier remove-frames/shadows proposal.
• Unknown family slugs safely retain the existing generic artwork, and existing dark assets/theme switching remain functional without fake recolored variants or missing image requests.
• Decorative alt="", asynchronous decoding, loading behavior and reserved image geometry remain appropriate; actual registration/navigation destinations and existing mobile hiding behavior are preserved, with no new overflow, clipping, image plate, halo, or visibly noisy edge caused by this change.
• The actual user hosts http://127.0.0.1:8091/courses and http://localhost:8000/courses/ml-zoomcamp display the installed light artwork after normal loading, and all six family routes are verified. Report the checked hosts and distinguish local installation from production deployment.
• Focused Django tests cover shared family mapping, unknown fallback, collage family identity and existing behaviors; browser tests are updated for the current collage contract rather than retaining stale assertions that the catalogue has no illustrations.
• Independent tester verification includes inspected real-page desktop/mobile evidence and the required verification plan dispositions; PM accepts only after technical verification passes.
• The illustration workflow and provenance record capture the installation handoff and user's feedback, and completion presents the working pages rather than a ZIP archive.
• Agent/workflow instructions explicitly preserve built-in imagegen and the never-request-an-API-key preference, with honest unverified-backend handling; reusable finishing/pixel/browser helpers are saved in the agreed maintained locations, documented and tested without promoting scratch data into runtime public content.
• All six family landings prominently communicate a course-specific starting state, at least three evidenced skill concepts, and a concrete built outcome before registration logistics dominate the page. ML is no longer a title/CTA/illustration hero with no value explanation.
• The responsive family hero makes the outcome and primary action dominant, keeps artwork subordinate and square without editing its native pixels, and reveals the beginning of the first value section at 1440×900; the transformation remains clear within the first two 390px mobile screens. The earlier rigid 352px size target is not an acceptance requirement.
• Public transformation copy is read from database-owned fields/records. The optional starting-point field has a migration and import-preservation coverage; all six local records have sourced, reversible authored content, while missing/unknown families omit unsupported claims without runtime editorial fallbacks.
• Process/proof refers to real published curriculum and genuine project briefs/submission-gallery destinations or published testimonials; attempt numbers and CLOSED states are not mislabeled as learner-built examples. No fabricated counts, careers, profitability, prerequisite or certificate guarantees appear. Self-paced/certificate messaging is truthful and coordinated with the concurrent certificate owner.
• The independent adversarial design reviewer explicitly ACCEPTS the rendered six-family design and representative desktop/mobile/theme/state contract. Tester PASS and PM product acceptance are separate required gates.
• After independent design/tester/PM acceptance, create focused local commits containing only issue-owned changes and issue references. Preserve unrelated auth/homework/certificate edits and concurrent Git work; do not push or deploy.

Verification scenarios

Django/integration

Exercise all six known family slugs, an unknown family, and an empty catalogue. Verify that runtime rendering resolves static files without reading .tmp/ or a checked-in content projection. Check collage records retain both slug and database-derived title, including reordered and unknown families, without exceeding the existing bound. Confirm registration links, visibility and unrelated title ordering remain unchanged.

Exercise each open-registration/running/self-paced art branch with and without an authored campaign image and verify the existing card content/actions remain present. Test maintained helpers' argument validation, safe output containment and representative valid/invalid image checks with synthetic data; the browser helper must inspect ordinary decoded static requests on explicit hosts, not replace images in the browser.

For the narrative, test optional/blank and full starting-point/outcome data, escaping, real course-owned process/proof associations, absent curriculum/projects/testimonials, and preservation of DB-managed starting-point copy through curriculum re-import. Test live-registration, self-paced and materials-only actions without changes to permission behavior. Run migration-drift checks for the single schema extension. Review the authored local DB diff and source record separately from synthetic test fixtures.

Browser

On the actual supplied hosts, check anonymous light-mode /courses and each of the six family URLs, wait for every image to decode, and assert the expected static path and natural dimensions. Capture and inspect affected desktop 1440×900 and mobile 390×844 / 320×844 layouts as required by the illustration workflow. Verify collage caption/art association and inspect foreground/transparent boundaries on real page backgrounds. Verify dark mode still shows existing dark companions; at narrow widths respect the existing hidden-art design. Exercise a visible catalogue-to-family navigation and family registration action without submitting data. Compare against baseline to avoid attributing an existing overflow to this patch.

For the transformation redesign, capture and inspect all six family pages in light/dark desktop/mobile states, with ML also at the intermediate 768px and narrow 320px widths. Check the reviewer-owned hierarchy/spacing/typography/palette contract, text extremes, visible focused actions and 44px targets, reduced motion, and readable contrast. The family redesign must not introduce catalogue changes beyond its separately authorized art/placeholder surface scope. Record ML's revised hero/value-section bounds to show the actual reserved space changed, not just the bitmap. Complete normal catalogue-to-family and course action navigation without submitting data.

For the catalogue amendment, inspect 1440px, 768px, 390px and 320px layouts in both themes: the real course cards remain available, placeholders are gone, collage figures/captions align, images decode from normal static requests, and controls/navigation stay usable without new overflow. Inspect the final LLM asset independently at native and enlarged size before assessing its real-page rendering.

Repository/operations

Record source/final paths and hashes, lossless decoded equality, alpha/border checks, unchanged unrelated assets, exact validation commands and report paths. Produce the process-required verification plan and preserve independent tester screenshot ownership. Leave changes uncommitted during the gates, then create the explicitly requested focused local commits after acceptance. Stage exact owned paths/hunks, inspect the staged diff, and preserve unrelated or concurrently restored work. Do not push or deploy.

[alexeygrigorev]

Grooming Complete

Ready for implementation. Install the six approved light-theme assets on the actual course family heroes and the existing catalogue collage, keyed by Course slug while retaining database-owned captions. Preserve existing dark artwork, unknown-family fallback, current layout/actions, and unrelated worktree changes. Verify both user-supplied local hosts; no archive, image regeneration, commit, push, or deployment is in scope. Acceptance criteria and desktop/mobile/browser scenarios are now in the issue. No blocking dependencies.

Repository finding: the catalogue currently cycles generic artwork by index, and its older Playwright assertion still describes a text-only hero; update the association and affected test contract together. Independent tester and PM acceptance remain required.

[alexeygrigorev]

Grooming Amendment — Compact Family Hero

The user’s ML screenshot and “this is too large” refinement apply to the individual course landing hero, not the catalogue. Added scope and a testable acceptance criterion: cap the shared family artwork at 22rem/352px on desktop, preserve its square ratio and heading/actions, and reduce art-driven hero height so Get started moves higher. Apply consistently to all six family pages; retain existing mobile hiding and catalogue geometry. Approved image pixels and concurrent certificate edits remain out of the change surface. Compare ML before/after geometry and inspect desktop/mobile plus intermediate breakpoint behavior. This is ready for implementation; no new dependency or artwork generation.

[alexeygrigorev]

Grooming Amendment — Transformation-led Family Landing

Latest user request supersedes size-only work: a proper course landing must show starting point → practical skills/process → concrete built outcome, supported by real curriculum/projects. Apply the shared narrative to all six families, with ML representative, and obtain explicit ACCEPT from the independently assigned adversarial design reviewer. A 352px illustration cap was our proposal, not a user requirement; narrative hierarchy now controls layout.

Minimal content path: add one optional DB-managed Course.starting_point text field, reuse Course.outcome, and compose real curriculum/project evidence. Five families already have outcome/description; ML has neither and needs sourced local DB copy. Do not invent runtime per-slug marketing, fabricate prerequisites/results, treat attempt labels as learner-built examples, or imply self-paced certificate eligibility. Preserve unrelated certificate work and coordinate any necessary truthful wording. No new CMS/JSON model, catalogue redesign, image generation, commit, push, or deployment.

The issue now records updated scope, data ownership, optional/empty-state and re-import-preservation tests, reviewer desktop/mobile/theme contract, and separate independent design/tester/PM gates.

[alexeygrigorev]

Grooming Amendment — Artwork Quality, Catalogue Preservation, Reusable Tools

Queued user additions are now part of the groomed scope: targeted LLM anatomy/cloud correction through built-in imagegen; matching illustrations in all three catalogue placeholder branches while preserving authored campaign images and every original open/running/self-paced course card; and a restrained aligned four-figure collage without individual white plates, rotation or heavy framing. This is not permission to remove catalogue components or redesign unrelated surfaces.

Save reusable chroma/pixel helpers under the illustration skill and actual-host screenshot checks under scripts/dev, with docs and focused tests; keep one-off content payloads and generated evidence in .tmp. Persist the repeated standing instruction to use imagegen skill/built-in tool and NEVER request OPENAI_API_KEY for image generation; unknown backend remains explicitly unverified.

The user now authorizes focused LOCAL commits after design ACCEPT, independent tester PASS and PM acceptance. No push/deployment is authorized. Use exact owned staging and preserve concurrent auth/homework/certificate work, including restoration of known pre-existing edits lost to another Git operation. Scope additions are groomed; final product acceptance remains pending independent tester evidence.

[alexeygrigorev]

Grooming Clarification — Preserve the Four Hero Cards

The user’s final preserve-cards instruction applies to the four catalogue hero cards as well as the original listing cards. Corrected the stale earlier criterion: keep all four hero cards, existing design-system borders/shadows, database captions and regular aligned 2×2 arrangement; use cream rather than white ground, compact artwork scale and no rotations. The independent design reviewer has accepted this constraint. Removing every frame/shadow is no longer required or permitted as a substitute for preserving the requested cards. Open-registration/running/self-paced listing cards also remain unchanged in membership and function.

This resolves the tester-intake scope conflict; technical verification and final PM acceptance remain pending.

[alexeygrigorev]

Product Acceptance — Bounded Implementation Accepted; Final Gate Blocked

Final-gate verdict: REJECT / blocked pending scope decisions and complete technical verification. This is not a rejection of the implemented design. The requested local product behavior matches the groomed scope, and the independent adversarial design verdict remains ACCEPT. No overall technical or final PM PASS, issue closure, or gate-dependent commit is authorized by this report.

Bounded product findings

I reviewed the final issue scope, frozen handoff, authored local-copy source/backup records, changed narrative/data contracts and tests, and rendered evidence across the six family pages, catalogue, narrow layouts, corrected LLM anatomy, course notes, and certificate/self-paced messaging.

• All six new light illustrations are installed on the real local pages; the catalogue retains its four cream-ground hero cards and original listing cards, replacing placeholder art while preserving authored campaign images.
• Family landings explain the learner starting point, real curriculum skills and concrete build outcome before route logistics. Proof uses real project/gallery destinations, not closed assignment-attempt cards. Important course notes and actual navigation remain accessible.
• The LLM correction and subordinate hero scale satisfy the independent visual contract. Existing dark artwork remains deliberately unchanged.
• Public narrative is database-owned, with sourced local authoring and reversible records. The saved workflow/tools preserve the built-in imagegen and never-request-an-API-key requirement.
• The issue-owned starting_point raw-SQL import regression is fixed and independently verified. No unrelated production/content write is implied.

Evidence and technical limit

The independent iteration-3 report records 138 tests passed and 202 subtests passed, including all 29 review-import cases. The tester independently recomputed the frozen verification plan; every field matches the engineer plan except created_at. Only the two importer files changed after the accepted rendered inputs.

All seven full-verification components still select rerun. There are no recorded reuse, skip or not-applicable waivers, and no complete accepted full evidence envelope for this source fingerprint. The tester's overall verdict remains REVISE, not PASS.

A separate clean-HEAD bounded reproduction confirms the remaining non-importer failure categories predate this work: 22 failures in a 65-case selection including subtests, plus the same browser resource-failure teardown category. These are attribution evidence, not permission to ignore required checks. The broader failures and incomplete components remain blockers; this issue does not silently absorb unrelated repairs.

The clean starting commit also references two missing certificate templates and five missing SVG assets. Those files exist locally as pre-existing user-owned work. Excluding this issue's certificate hunks alone would not produce a self-contained committed family page.

Evidence retained locally:

• .tmp/course-illustrations-20260915/design-review-acceptance.md
• .tmp/course-illustrations-20260915/verification-tester-iteration3/qa-review.md
• .tmp/course-illustrations-20260915/verification-tester-iteration2/baseline-reproduction.md
• .tmp/course-illustrations-20260915/engineer-handoff-3.md

Frozen HEAD: c528f2f34bd2dcd451a1c2b97a30b76aa73b3ff2; source manifest: 9e0159b0dbeeb9fa84dc0693676d77231917c749dab04d00bae2a4d8e910c9cb.

Direction required

The user must choose whether to authorize separately tracked baseline repairs and inclusion of the pre-existing certificate dependency in its own focused commit, or retain the current working local result with changes uncommitted. If repairs are authorized, the repaired/frozen candidate must complete the required independent technical gate before final PM acceptance and focused commits. No push or deployment is authorized.

Acceptance checkboxes remain unchanged: bounded successes must not be presented as full completion.