steppy-dev 0.3.0__py3-none-any.whl

steppy/templates/angular/component.ts.j2

@@ -0,0 +1,229 @@
+// GENERATED BY STEPPY — DO NOT EDIT. Regenerate with: steppy build
+import { Component, computed, effect, ElementRef, inject, signal, ViewEncapsulation } from '@angular/core';
+import { DomSanitizer } from '@angular/platform-browser';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { map, startWith } from 'rxjs/operators';
+import { TranslateService, TranslatePipe } from '@ngx-translate/core';
+{% if has_multiple_modes or has_multiple_layouts %}
+import { FormsModule } from '@angular/forms';
+import { SelectButtonModule } from 'primeng/selectbutton';
+{% endif %}
+{% if onboarding_strip %}
+import { RouterLink } from '@angular/router';
+{% endif %}
+{% if has_interactive %}
+import { {{ class_name }}InteractiveComponent } from './{{ slug }}-interactive.component';
+{% endif %}
+{% if has_video %}
+import { {{ class_name }}VideoComponent } from './{{ slug }}-video.component';
+{% endif %}
+import { CONTENT, STEPS, TIMINGS } from './{{ slug }}.content';
+
+// Stepbystep cursor animation. The guide HTML is injected via [innerHTML], and
+// the browser never runs <script> tags inserted that way — so the cursor
+// driver is loaded here (once per page, like the interactive player bundle)
+// and (re)invoked after every render. The vendored IIFE exposes
+// window.__STEPPY_CURSOR__.mount(root, steps, timings), which returns a
+// disposer that disconnects the observer and aborts any in-flight animation.
+const CURSOR_BUNDLE_URL = '/assets/{{ role }}/steppy-cursor.js';
+
+interface SteppyCursorApi {
+  mount(root: ParentNode, steps: unknown, timings?: unknown): () => void;
+}
+
+let cursorScriptLoading: Promise<void> | null = null;
+
+function ensureCursorLoaded(): Promise<void> {
+  // Idempotent: inserts the <script> once per page no matter how many guides
+  // mount. Resolves immediately once window.__STEPPY_CURSOR__ is available.
+  if (cursorScriptLoading) return cursorScriptLoading;
+  if (typeof window === 'undefined' || typeof document === 'undefined') {
+    return Promise.resolve();
+  }
+  if ((window as unknown as { __STEPPY_CURSOR__?: SteppyCursorApi }).__STEPPY_CURSOR__) {
+    cursorScriptLoading = Promise.resolve();
+    return cursorScriptLoading;
+  }
+  cursorScriptLoading = new Promise<void>((resolve, reject) => {
+    const script = document.createElement('script');
+    script.src = CURSOR_BUNDLE_URL;
+    script.async = true;
+    script.onload = () => resolve();
+    script.onerror = (err) => reject(err);
+    document.head.appendChild(script);
+  });
+  return cursorScriptLoading;
+}
+
+function scheduleAfterRender(cb: () => void): void {
+  // Defer past Angular's [innerHTML] DOM flush so the freshly-injected
+  // .steppy-step sections exist before the driver observes them.
+  if (typeof requestAnimationFrame === 'function') {
+    requestAnimationFrame(() => cb());
+  } else {
+    setTimeout(cb, 0);
+  }
+}
+
+@Component({
+  selector: 'app-guide-{{ slug }}',
+  standalone: true,
+  imports: [
+    TranslatePipe,
+{% if has_multiple_modes or has_multiple_layouts %}
+    FormsModule,
+    SelectButtonModule,
+{% endif %}
+{% if onboarding_strip %}
+    RouterLink,
+{% endif %}
+{% if has_interactive %}
+    {{ class_name }}InteractiveComponent,
+{% endif %}
+{% if has_video %}
+    {{ class_name }}VideoComponent,
+{% endif %}
+  ],
+  template: `
+{% if onboarding_strip %}
+    <nav class="steppy-onboarding-strip" aria-label="Onboarding progress">
+      <span class="steppy-onboarding-strip-progress">
+        <a [routerLink]="['../', '{{ onboarding_strip.path_slug }}']">{{ '{{' }} '{{ role_namespace }}.onboarding.title' | translate {{ '}}' }}</a>
+        — {{ '{{' }} '{{ role_namespace }}.onboarding.stepLabel' | translate: { position: {{ onboarding_strip.position }}, total: {{ onboarding_strip.total }} } {{ '}}' }}
+      </span>
+      <span class="steppy-onboarding-strip-nav">
+{% if onboarding_strip.prev %}
+        <a class="steppy-onboarding-prev"
+           [routerLink]="['../', '{{ onboarding_strip.prev.slug }}']"
+           [queryParams]="{ onboarding: 1 }">‹ {{ '{{' }} '{{ role_namespace }}.guides.{{ onboarding_strip.prev.slug }}.title' | translate {{ '}}' }}</a>
+{% else %}
+        <span class="steppy-onboarding-prev steppy-onboarding-disabled" aria-disabled="true">‹ {{ '{{' }} '{{ role_namespace }}.onboarding.previousLabel' | translate {{ '}}' }}</span>
+{% endif %}
+{% if onboarding_strip.next %}
+        <a class="steppy-onboarding-next"
+           [routerLink]="['../', '{{ onboarding_strip.next.slug }}']"
+           [queryParams]="{ onboarding: 1 }">{{ '{{' }} '{{ role_namespace }}.guides.{{ onboarding_strip.next.slug }}.title' | translate {{ '}}' }} ›</a>
+{% else %}
+        <span class="steppy-onboarding-next steppy-onboarding-disabled" aria-disabled="true">{{ '{{' }} '{{ role_namespace }}.onboarding.doneLabel' | translate {{ '}}' }}</span>
+{% endif %}
+      </span>
+    </nav>
+{% endif %}
+{% if has_multiple_modes or has_multiple_layouts %}
+    <div class="guide-toolbar">
+{% if has_multiple_layouts %}
+      <p-selectButton
+        [options]="layoutOptions"
+        [ngModel]="selectedLayout()"
+        (ngModelChange)="selectedLayout.set($event)"
+        optionLabel="label"
+        optionValue="value" />
+{% endif %}
+{% if has_multiple_modes %}
+      <p-selectButton
+        [options]="modeOptions"
+        [(ngModel)]="selectedMode"
+        optionLabel="label"
+        optionValue="value" />
+{% endif %}
+    </div>
+{% endif %}
+{% if has_interactive or has_video %}
+    @if (selectedMode() === 'stepbystep') {
+      <div [innerHTML]="trustedHtml()"></div>
+    }
+{% if has_interactive %}
+    @if (selectedMode() === 'interactive') {
+      <app-guide-{{ slug }}-interactive{% if has_multiple_layouts %} [variant]="selectedLayout()"{% endif %} />
+    }
+{% endif %}
+{% if has_video %}
+    @if (selectedMode() === 'video') {
+      <app-guide-{{ slug }}-video{% if has_multiple_layouts %} [variant]="selectedLayout()"{% endif %} />
+    }
+{% endif %}
+{% else %}
+    <div [innerHTML]="trustedHtml()"></div>
+{% endif %}
+  `,
+  encapsulation: ViewEncapsulation.None,
+})
+export class {{ class_name }}Component {
+  private readonly translate = inject(TranslateService);
+  private readonly sanitizer = inject(DomSanitizer);
+  private readonly host = inject<ElementRef<HTMLElement>>(ElementRef);
+
+{% if has_multiple_layouts %}
+  readonly layoutOptions = [
+{% for layout in layouts %}
+    { label: '{{ layout | capitalize }}', value: '{{ layout }}' },
+{% endfor %}
+  ];
+{% endif %}
+
+{% if has_multiple_modes %}
+  readonly modeOptions = [
+{% for mode in modes %}
+    { label: '{{ mode_labels[mode] }}', value: '{{ mode }}' },
+{% endfor %}
+  ];
+{% endif %}
+
+  readonly selectedLocale = toSignal(
+    this.translate.onLangChange.pipe(
+      map((event) => event.lang),
+      startWith(this.translate.currentLang || this.translate.getDefaultLang() || '{{ default_locale }}'),
+    ),
+    { initialValue: this.translate.currentLang || this.translate.getDefaultLang() || '{{ default_locale }}' },
+  );
+
+  readonly selectedLayout = signal<string>('{{ default_layout }}');
+{% if has_multiple_modes %}
+  selectedMode = signal('{{ default_mode }}');
+{% else %}
+  selectedMode = signal('stepbystep');
+{% endif %}
+
+  readonly trustedHtml = computed(() => {
+    const byLayout = CONTENT[this.selectedLocale()] ?? {};
+    const layoutKey = this.selectedLayout();
+    // Fall back to "default" (the back-compat single-layout key) if the
+    // requested layout isn't present — handles cases where the consumer
+    // toggles to a layout that this guide didn't capture.
+    const raw = byLayout[layoutKey] ?? byLayout['default'] ?? '';
+    return this.sanitizer.bypassSecurityTrustHtml(raw);
+  });
+
+  // Stepbystep cursor lifecycle. Re-drives the animator whenever the rendered
+  // DOM changes — locale, layout, and the mode toggle each swap the
+  // [innerHTML] content under our feet. The effect's cleanup disposes the
+  // previous mount before the next one (and on destroy).
+  private cursorDispose: (() => void) | null = null;
+
+  constructor() {
+    effect((onCleanup) => {
+      // Track the signals that change the injected DOM so this re-runs on each.
+      const locale = this.selectedLocale();
+      const layout = this.selectedLayout();
+      const mode = this.selectedMode();
+      if (mode !== 'stepbystep' || typeof window === 'undefined') return;
+      let cancelled = false;
+      onCleanup(() => {
+        cancelled = true;
+        this.cursorDispose?.();
+        this.cursorDispose = null;
+      });
+      scheduleAfterRender(() => {
+        if (cancelled) return;
+        const byLayout = STEPS[locale] ?? {};
+        const steps = byLayout[layout] ?? byLayout['default'] ?? [];
+        void ensureCursorLoaded().then(() => {
+          if (cancelled) return;
+          const api = (window as unknown as { __STEPPY_CURSOR__?: SteppyCursorApi }).__STEPPY_CURSOR__;
+          if (!api) return;
+          this.cursorDispose = api.mount(this.host.nativeElement, steps, TIMINGS);
+        });
+      });
+    });
+  }
+}

steppy/templates/angular/content.ts.j2

@@ -0,0 +1,31 @@
+// GENERATED BY STEPPY — DO NOT EDIT. Regenerate with: steppy build
+export const CONTENT: Record<string, Record<string, string>> = {
+{% for locale, by_layout in content_by_locale.items() %}
+  '{{ locale }}': {
+{% for layout_key, html in by_layout.items() %}
+    '{{ layout_key }}': {{ html | tojson }},
+{% endfor %}
+  },
+{% endfor %}
+};
+
+// Per-step cursor frame data, keyed by locale then layout (mirroring CONTENT;
+// single-layout configs collapse to a single "default" key). The stepbystep
+// cursor driver (window.__STEPPY_CURSOR__.mount) reads this to animate the
+// arrow over the [innerHTML]-injected guide: each frame carries the
+// capture-space viewport + cursor behavior the animator projects onto the
+// displayed screenshot. `index` matches the `data-step-index` on each
+// `.steppy-step` section.
+export interface SteppyCursorStepFrame {
+  viewport: { width: number; height: number } | null;
+  cursor: unknown;
+}
+export interface SteppyCursorStep {
+  index: number;
+  frames: SteppyCursorStepFrame[];
+}
+export const STEPS: Record<string, Record<string, SteppyCursorStep[]>> = {{ steps_by_locale | tojson }};
+
+// Cursor timing overrides for this guide (scenario.guide.cursor); passed
+// straight to the animator, which fills any gaps with its defaults.
+export const TIMINGS: Record<string, number> = {{ cursor_timings | tojson }};

steppy/templates/angular/gitignore.j2

@@ -0,0 +1,3 @@
+# GENERATED BY STEPPY — DO NOT EDIT. Regenerate with: steppy build
+# Everything in this directory is generated and should not be manually edited.
+*

steppy/templates/angular/group.component.ts.j2

@@ -0,0 +1,39 @@
+// GENERATED BY STEPPY — DO NOT EDIT. Regenerate with: steppy build
+import { Component, ViewEncapsulation } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { TranslatePipe } from '@ngx-translate/core';
+
+interface GroupChild {
+  slug: string;
+}
+
+@Component({
+  selector: 'app-guide-group-{{ group.slug }}',
+  standalone: true,
+  imports: [RouterLink, TranslatePipe],
+  template: `
+    <section class="steppy-index">
+      <h1>{{ '{{' }} '{{ role_namespace }}.groups.{{ group.slug }}.title' | translate {{ '}}' }}</h1>
+{% if has_description %}
+      <p class="steppy-group-description">{{ '{{' }} '{{ role_namespace }}.groups.{{ group.slug }}.description' | translate {{ '}}' }}</p>
+{% endif %}
+      @if (children.length === 0) {
+        <p class="steppy-index-empty">{{ '{{' }} '{{ role_namespace }}.ui.groupEmpty' | translate {{ '}}' }}</p>
+      } @else {
+        <ul class="steppy-index-list">
+          @for (child of children; track child.slug) {
+            <li>
+              <a [routerLink]="['../', child.slug]">
+                <span class="steppy-index-title">{{ '{{' }} '{{ role_namespace }}.guides.' + child.slug + '.title' | translate {{ '}}' }}</span>
+              </a>
+            </li>
+          }
+        </ul>
+      }
+    </section>
+  `,
+  encapsulation: ViewEncapsulation.None,
+})
+export class {{ class_name }}GroupComponent {
+  readonly children: GroupChild[] = {{ children | tojson(indent=2) }};
+}

steppy/templates/angular/onboarding.component.ts.j2

@@ -0,0 +1,43 @@
+// GENERATED BY STEPPY — DO NOT EDIT. Regenerate with: steppy build
+import { Component, ViewEncapsulation } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { TranslatePipe } from '@ngx-translate/core';
+
+interface OnboardingStep {
+  slug: string;
+}
+
+@Component({
+  selector: 'app-guide-onboarding',
+  standalone: true,
+  imports: [RouterLink, TranslatePipe],
+  template: `
+    <section class="steppy-onboarding">
+      <h1>{{ '{{' }} '{{ role_namespace }}.onboarding.title' | translate {{ '}}' }}</h1>
+{% if has_description %}
+      <p class="steppy-onboarding-description">{{ '{{' }} '{{ role_namespace }}.onboarding.description' | translate {{ '}}' }}</p>
+{% endif %}
+      <ol class="steppy-onboarding-steps">
+        @for (step of steps; track step.slug; let i = $index) {
+          <li>
+            <a [routerLink]="['../', step.slug]" [queryParams]="{ onboarding: 1 }">
+              <span class="steppy-onboarding-step-number">{{ '{{' }} i + 1 {{ '}}' }}</span>
+              <span class="steppy-onboarding-step-title">{{ '{{' }} '{{ role_namespace }}.guides.' + step.slug + '.title' | translate {{ '}}' }}</span>
+            </a>
+          </li>
+        }
+      </ol>
+      @if (steps.length > 0) {
+        <p class="steppy-onboarding-cta">
+          <a class="steppy-onboarding-start"
+             [routerLink]="['../', steps[0].slug]"
+             [queryParams]="{ onboarding: 1 }">{{ '{{' }} '{{ role_namespace }}.onboarding.start' | translate {{ '}}' }}</a>
+        </p>
+      }
+    </section>
+  `,
+  encapsulation: ViewEncapsulation.None,
+})
+export class OnboardingComponent {
+  readonly steps: OnboardingStep[] = {{ steps | tojson(indent=2) }};
+}

steppy/templates/angular/routes.ts.j2

@@ -0,0 +1,34 @@
+// GENERATED BY STEPPY — DO NOT EDIT. Regenerate with: steppy build
+// Role: {{ role }}
+import { Routes } from '@angular/router';
+
+export const {{ routes_const }}: Routes = [
+{% for guide in guides %}
+  {
+    path: '{{ guide.slug }}',
+    loadComponent: () =>
+      import('./{{ guide.slug }}/{{ guide.slug }}.component').then(
+        (m) => m.{{ guide.class_name }}Component,
+      ),
+  },
+{% endfor %}
+{% for group in groups %}
+  {
+    path: '{{ group.slug }}',
+    loadComponent: () =>
+      import('./_groups/{{ group.slug }}.group.component').then(
+        (m) => m.{{ group.class_name }}GroupComponent,
+      ),
+  },
+{% endfor %}
+{% if has_onboarding %}
+  {
+    path: '{{ onboarding_slug }}',
+    loadComponent: () =>
+      import('./_onboarding/onboarding.component').then(
+        (m) => m.OnboardingComponent,
+      ),
+  },
+{% endif %}
+  { path: '', redirectTo: '{{ default_slug }}', pathMatch: 'full' },
+];

steppy/templates/ci/github-actions.yml

@@ -0,0 +1,284 @@
+# Steppy CI workflow — copy this to .github/workflows/steppy.yml in your project.
+#
+# Brings your application stack up with Docker Compose, runs your Steppy
+# scenarios against it, and publishes a browsable run report as a build artifact.
+#
+# Prerequisites in your repo:
+#   - config.yaml + scenarios/ committed
+#   - a docker-compose.yml that boots your app (see the two notes on the compose
+#     step below — healthchecks and published ports are both load-bearing)
+#   - credentials provided via repository secrets (referenced as ${VAR} in
+#     config.yaml — e.g. STEPPY_ADMIN_USERNAME / STEPPY_ADMIN_PASSWORD)
+#
+# If your app already runs somewhere the runner can reach, drop the compose steps
+# and point apps.<role>.url at that deployment instead.
+#
+# This file is the OWNED copy: every trap is documented beside the step it applies
+# to, and it is yours to edit. If you would rather not own it, Steppy also ships
+# the same recipe as a reusable workflow — pin a tag, never a branch:
+#
+#   jobs:
+#     e2e:
+#       uses: Steppy-dev/steppy/.github/workflows/steppy-e2e.yml@v0.3.0
+#       with:
+#         compose-file: docker-compose.yml
+#       secrets:
+#         steppy-env: ${{ secrets.STEPPY_ENV }}
+#
+# That form exposes verdict / exit-code / badge-percent as job outputs, but it IS
+# the job — you cannot interleave your own steps into it. Keep this file if you
+# need to (building an image before the run, for instance).
+name: Steppy E2E
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Steppy
+        # Steppy is not on PyPI yet, so CI installs from git. Pin a tag rather
+        # than a branch: an e2e suite that silently changes its own tooling
+        # mid-week turns every unexplained failure into a two-hour bisect.
+        #
+        # The extras are what make `report.html` and `report.retries` /
+        # `steppy run --retries N` actually do something — without them Steppy
+        # warns and skips those features rather than failing the run.
+        run: pip install 'steppy-dev[retry,report] @ git+https://github.com/Steppy-dev/steppy.git@v0.3.0'
+
+      - name: Install Playwright browsers
+        run: playwright install chromium --with-deps
+
+      # In-app tours (only with `tours.enabled: true` in config.yaml): fail fast
+      # when the tour files committed to the app no longer match the scenarios.
+      # No browser, no app. It compares content for the build id each committed
+      # copy records, so a new commit alone never fails it. The app must then be
+      # BUILT with those files (`docker compose up --build` below) before the
+      # tour replays run against it.
+      # - name: Check the in-app tour files are current
+      #   run: steppy tours --check
+
+      # Two things decide whether this step actually leaves you with a running
+      # app, and both are properties of YOUR compose file, not of this workflow:
+      #
+      #   1. `--wait` only waits on services that declare a `healthcheck:`. With
+      #      no healthchecks it returns as soon as the containers are created,
+      #      the scenarios start against a port that is not serving yet, and the
+      #      run dies wholesale. This is the most common first-run failure.
+      #   2. The scenarios and your seed scripts run HERE, on the runner — not
+      #      inside a container. So the app (and the database, if seeds touch it)
+      #      must publish its ports, and apps.<role>.url points at localhost.
+      - name: Start the application stack
+        run: docker compose up -d --wait --wait-timeout 180
+
+      - name: Generate tests
+        run: steppy generate
+
+      - name: Run scenarios
+        env:
+          # Map your repository secrets onto the ${VAR} refs in config.yaml.
+          STEPPY_ADMIN_USERNAME: ${{ secrets.STEPPY_ADMIN_USERNAME }}
+          STEPPY_ADMIN_PASSWORD: ${{ secrets.STEPPY_ADMIN_PASSWORD }}
+        # --bundle records per-test and per-step events plus JUnit XML, which is
+        # what lets the report below name the step a failure died in instead of
+        # only the test. It changes the pytest invocation, so it is opt-in.
+        run: steppy run --trace --bundle
+
+      # When the suite goes red, the question is almost always "was it the tests
+      # or the stack?" — and the stack's own logs are the fastest way to know.
+      - name: Application logs
+        if: failure()
+        run: docker compose logs --no-color --tail 200
+
+      # A browsable report of this run: outcomes, failure causes grouped so one
+      # broken selector across forty scenarios reads as one row, the failing step
+      # named, and its screenshot. Self-contained and relative — open index.html
+      # straight out of the downloaded artifact.
+      #
+      # `if: always()` because a failing run is exactly when you want it, and
+      # `steppy report` exits 0 either way: it describes rendering, not the run.
+      - name: Build the run report
+        if: always()
+        run: steppy report
+
+      - name: Upload the report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: steppy-report
+          path: output/report/
+
+      - name: Upload results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: steppy-output
+          path: output/
+
+      # `-v` so the next run starts from a clean database rather than inheriting
+      # whatever the last one's seeds left behind.
+      - name: Stop the application stack
+        if: always()
+        run: docker compose down -v
+
+# ── Publishing the report to GitHub Pages ─────────────────────────────────────
+#
+# ⚠ READ THIS FIRST. GitHub Pages is PUBLIC — on a public repo there is no access
+# control, and a published screenshot is permanent and indexable. Your captures
+# show your app with real-looking data in it. `screenshot.mask` (config.yaml) can
+# redact fields at capture time, but a leak cannot be taken back.
+#
+#   * This is for SHOWCASE and open-source repos, where the stack under test is
+#     seeded with throwaway data. For client work, keep the artifact upload above
+#     and read the report from there.
+#   * The report marks every page `noindex` and ships a `robots.txt` that
+#     disallows everything, so it will not be indexed by a well-behaved crawler.
+#     That is a courtesy, not a control.
+#   * `--screenshots failed` (the default) copies only the captures of variants
+#     that did not pass. Use `--screenshots all` deliberately, knowing it puts
+#     every step of every locale and layout on the public internet — and that on
+#     a large suite it is also what pushes the site towards Pages' size limit.
+#
+# One-time setup: repository Settings → Pages → Source: "GitHub Actions".
+#
+# Publish as an ARTIFACT, never by committing to a gh-pages branch: screenshots
+# pushed on every run grow the repository's history forever and cannot be pruned
+# without a rewrite.
+#
+#   permissions:
+#     contents: read
+#     pages: write
+#     id-token: write
+#
+#   jobs:
+#     # ... the e2e job above ...
+#
+#     publish-report:
+#       # Default branch only. A report from every PR would publish work in
+#       # progress, and PR runs from forks cannot get an id-token anyway.
+#       if: always() && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+#       needs: e2e
+#       runs-on: ubuntu-latest
+#       environment:
+#         name: github-pages
+#         url: ${{ steps.deploy.outputs.page_url }}
+#       steps:
+#         - uses: actions/download-artifact@v4
+#           with:
+#             name: steppy-report
+#             path: site
+#         - uses: actions/configure-pages@v5
+#         - uses: actions/upload-pages-artifact@v3
+#           with:
+#             path: site
+#         - id: deploy
+#           uses: actions/deploy-pages@v4
+#
+# A repository has exactly ONE Pages site. If you also publish generated guides
+# (`steppy build`), decide the tree before anything links to it — e.g. the report
+# under site/report/ and the guides under site/guides/ — because moving the
+# report later also moves badge.json, and that URL is a contract with every
+# README that points at it.
+#
+# ── The e2e-surface coverage badge ────────────────────────────────────────────
+#
+# `steppy report` writes a shields endpoint at badge.json in the site root, so
+# once the Pages job above is live the badge is served at <page_url>/badge.json:
+#
+#   ![e2e surface](https://img.shields.io/endpoint?url=https://<owner>.github.io/<repo>/badge.json)
+#
+# Three prerequisites, in order — miss any one and there is no number:
+#
+#   1. badge.json is written ONLY when the run recorded coverage. Without
+#      `steppy run --coverage` the report has no coverage section and no badge
+#      file at all, and the shields URL 404s.
+#   2. A percentage needs a DECLARED surface to score against, which means a
+#      `coverage:` block in config.yaml naming `coverage.apis[].openapi` (a URL
+#      the runner can reach — your compose stack serving /openapi.json qualifies)
+#      and optionally `coverage.sitemap`. With coverage recorded but nothing
+#      declared, the badge honestly reads `n/a` in grey rather than 0%.
+#   3. `steppy coverage refresh` EXITS 1 when no `coverage:` block is configured,
+#      which is why these steps are not armed by default. Add them once you have
+#      declared a surface.
+#
+# Two things worth knowing before you turn it on:
+#
+#   * Recording drives CDP precise coverage, which costs runtime. On free
+#     runners, recording it on default-branch pushes only — and not on every PR
+#     — is usually the right trade.
+#   * Declare `coverage.non_ui` in config.yaml (health checks, webhook receivers,
+#     OAuth callbacks, internal cron). Triage flags set with `steppy coverage
+#     triage` live in the gitignored .steppy/coverage.db, so a fresh CI checkout
+#     has none and every one of those endpoints counts against you.
+#
+#   - name: Run scenarios
+#     run: steppy run --trace --bundle --coverage
+#
+#   - name: Refresh the declared surface
+#     if: always()
+#     run: steppy coverage refresh && steppy coverage report --json output/coverage/gaps.json
+#
+# ── Results bundles ───────────────────────────────────────────────────────────
+#
+# Instead of uploading a loose output/ tree, package the run into one portable,
+# self-describing archive. The run step already passes --bundle, so the event
+# records and JUnit XML a bundle needs are captured; add the packaging step:
+#
+#   - name: Package results
+#     if: always()
+#     run: steppy bundle create
+#
+#   - name: Upload results
+#     if: always()
+#     uses: actions/upload-artifact@v4
+#     with:
+#       name: steppy-bundle
+#       path: output/bundles/
+#
+# The archive holds output/ exactly as steppy wrote it, so `tar -xf` then
+# `steppy report` / `steppy guide` / `steppy build` works unchanged on a
+# downloaded artifact. Adding the `bundle` extra to the install line above gets
+# zstd compression; without it bundles are .tar.gz.
+
+# ── Running in parallel ───────────────────────────────────────────────────────
+#
+# For a large suite, swap the run step for `steppy run --workers 4 --trace`. Note
+# what that changes about the compose steps above: the coordinator brings up ONE
+# FULL STACK PER WORKER and tears them down itself, so you drop the explicit
+# `docker compose up` and give it `parallel.compose_file` instead. Four copies of
+# your app on one hosted runner is a lot — this earns its keep on a large suite
+# or a beefy self-hosted runner, not on a thirty-scenario suite.
+#
+# It needs a `parallel:` block + per-app `internal_url` in config.yaml,
+# healthchecks on your compose services, and Docker Compose 2.20+ on the runner
+# (ubuntu-latest has it). Two things worth knowing about the CI output:
+#
+#   * Failed scenarios are automatically re-run once at reduced concurrency. One
+#     that then passes is reported as FLAKY and does NOT fail the build — it lost
+#     a race, it is not broken. Pass --strict-flaky if you would rather CI go red
+#     on flakes, or --retry-pass 0 to turn the retry off entirely.
+#   * If the app or auth is down, the run aborts after ~10 scenarios instead of
+#     burning the full wall clock on 300 identical failures.
+#
+# `steppy flaky` ranks repeat offenders across runs, which is only useful if the
+# history survives between builds. Cache it around the run step:
+#
+#   - uses: actions/cache@v4
+#     with:
+#       path: .steppy/history.jsonl
+#       key: steppy-history-${{ github.run_id }}
+#       restore-keys: steppy-history-
+#
+# ...then add a reporting step after the run:
+#
+#   - name: Flakiest scenarios
+#     if: always()
+#     run: steppy flaky --last 20 --min-rate 0.1