feat: editorial illustrations, mobile overflow/contrast fixes, AGENTS.md

[crypticpy]

What this is

The pre-demo hardening wave, in five commits:

1. fix: mobile overflow and contrast on module pages — past event rows recede via grayscale instead of opacity-70 (desaturation preserves luminance, so text stays at WCAG AA); cohort hero breadcrumbs get on-dark colors (separators were 2.22:1); min-w-0 on three grid-item groups whose nowrap/truncate content set the track wider than narrow viewports (resources group cards, the cohort aside, materials list items). Verified clean across a 7-width × 11-page matrix (320–1920px).
2. test: extend a11y gate to compare, A–Z and 404 pages — these were never audited by CI. compare is gated on the catalog module like governance.
3. feat: ship the editorial illustration set — fills every image slot wired in feat: visual polish pass — illustration slots, steppers, micro-motion #34: hero, og-card, submit open/closed, about, events, resources, governance, cohort journey, four empty states, 404, wizard-complete, plus two alpha-extracted pattern tiles. Palette-recompressed PNGs + AVIF/WebP derivatives at 400/800/1280.
4. docs: add AGENTS.md — the setup runbook for AI agents handed a copy of this template: the .phct/ownership.yml contract, the pre-setup interview checklist, the setup → generate → validate loop, and the four GitHub settings only a human can click. Routing pointers in CLAUDE.md, README, docs/index.md.
5. fix: only audit the A–Z page when entries exist — facet_pages.rb skips it for an empty catalog, so the gate would have audited a 404 on a fresh setup.

Verification

• pa11y-ci WCAG2AA (axe + htmlcs): 21/21 gate URLs, plus a one-off 10/10 run over the module pages (events/cohorts/resources enabled locally) that found the two contrast bugs fixed here.
• Responsive matrix: 77/77 page/width combos with no horizontal overflow.
• 657/657 Node tests, 211/211 Ruby runs, npm run validate PASS, ownership contract valid, derivatives --check in sync.

🤖 Generated with Claude Code

Summary by Sourcery

Harden mobile accessibility and page coverage while shipping the editorial illustration system and agent-focused setup guidance.

New Features:

• Add the editorial illustration set across site pages, empty states, submission flows, social previews, and decorative backgrounds.
• Provide an AI-agent setup runbook that explains repository ownership, configuration, validation, and required GitHub settings.

Bug Fixes:

• Preserve accessibility contrast for past events and cohort breadcrumbs.
• Prevent narrow mobile layouts from overflowing due to long or truncated content.
• Avoid auditing the generated A–Z URL when an empty catalog does not produce that page.

Enhancements:

• Expand the accessibility gate to cover compare, A–Z, and 404 pages when they are available.
• Document configurable illustration fallbacks and update setup guidance for the shipped visual defaults.

CI:

• Extend pull-request accessibility checks with conditional compare and A–Z coverage plus the 404 page.

Documentation:

• Add AGENTS.md and link it from the repository guidance and documentation index.

Tests:

• Validate the expanded accessibility coverage and responsive behavior across module pages.

[sourcery-ai]

Reviewer's Guide

This PR hardens responsive and accessibility behavior, wires a complete editorial illustration set into site defaults and generated configuration, expands accessibility coverage to compare/A–Z/404 routes with build-aware gating, and adds an AI-agent setup runbook with ownership and launch guidance.

Sequence diagram for build-aware accessibility auditing

sequenceDiagram
  participant Gate as pa11y-ci gate
  participant URLs as qualityUrls
  participant Modules as Module configuration
  participant Catalog as Catalog content
  participant Site as Built site

  Gate->>URLs: qualityUrls(base)
  URLs->>Modules: moduleOn(catalog)
  URLs->>Catalog: sampleEntryPaths()
  alt catalog enabled
    URLs-->>Gate: compare route
  end
  alt catalog enabled and entries exist
    URLs-->>Gate: A-Z route
  end
  URLs-->>Gate: 404 route
  Gate->>Site: Audit selected routes with WCAG2AA

Loading

Flow diagram for AI-agent template setup

flowchart TD
  Start[Agent receives a template copy] --> Read[Read AGENTS.md]
  Read --> Interview[Collect organization, schema, modules, branding, repository, and submission answers]
  Interview --> Ownership[Edit deployment-owned configuration and content files]
  Ownership --> Setup[npm run setup]
  Setup --> Generate[npm run generate]
  Generate --> Validate[npm run validate]
  Validate -->|Pass| Human[Ask a human to configure required GitHub settings]
  Validate -->|Fail| Fix[Correct configuration or generated files]
  Fix --> Generate
  Human --> Launch[Run tests and deploy]

Loading

File-Level Changes

Change	Details	Files
Added an agent-focused setup and ownership runbook, with documentation routing from existing contributor and user-facing entry points.	Documented deployment versus template-owned files and generated-file rules. Added a pre-configuration interview checklist and setup, generation, validation, sample-ejection, and verification workflow. Documented GitHub settings requiring human or administrative action. Linked the runbook from the repository documentation and clarified copy-versus-template guidance.	AGENTS.md CLAUDE.md README.md docs/index.md
Enabled the shipped editorial illustration set throughout the default site configuration and regenerated configurator defaults.	Configured hero, social card, submission, about, events, resources, governance, cohort, empty-state, 404, and texture assets. Added the cohort journey image and synchronized generated derivative metadata and configurator defaults. Added the illustration asset set and responsive image derivatives in the assets tree.	_data/cohorts/2026.yml _data/derivatives.json _data/governance.yml _data/site.yml _data/theme.yml assets/js/configurator/defaults.generated.js assets/images/illustrations/*
Fixed narrow-viewport layout overflow and preserved accessibility contrast on module pages.	Changed past-event styling from opacity reduction to grayscale desaturation. Added on-dark breadcrumb styling for cohort headers, including breadcrumb-list separators. Applied min-w-0 to resource cards, cohort sidebars, material list items, and related grid content to allow truncation within narrow tracks.	_includes/event-list.html _includes/materials.html _layouts/cohort.html resources/index.md
Expanded the pa11y accessibility gate to cover previously unaudited routes while avoiding invalid audits for pages omitted by the build.	Added compare, A–Z, and 404 URLs to the gate. Conditioned compare on the catalog module and A–Z on both the catalog module and non-empty sample entries. Reused sampled entry paths when constructing gated URLs.	quality/pa11yci.js quality/urls.js

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

Sourcery assessment

Approved.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fe1e1eb788

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[sourcery-ai]

Sourcery assessment

Approved.