CI & GitHub Actions

18 workflows run the repository's continuous integration. Only CI Gate is a required status: the per-package workflows are path-filtered, so each runs only when its files change and the gate waits for exactly the set a pull request should trigger. Scheduled and manual workflows cover the slow or operator-driven checks that do not belong on every pull request. Purpose and use case come from scripts/data/workflow-catalog.json; triggers and jobs are read from the workflow files, and this page says nothing about whether a run is currently passing.

Workflows

Workflow	Purpose	Runs on	Required
Admin	Builds and tests the steward cockpit when admin code, the shared code it imports, or the shared test support changes.	pull requests that touch its paths (29 path filters); pushes to main and develop that touch its paths; manual dispatch	No
Agent	Typechecks and tests the messaging agent and its public HTTP API when agent or shared code changes.	pull requests that touch its paths (16 path filters); pushes to main and develop that touch its paths	No
CI Gate	The one required status. It derives the workflows a pull request's changed files should trigger, waits for each to register and report, and fails as soon as one fails or never shows up, so path-filtered workflows cannot silently weaken branch protection.	every pull request	Yes
Client	Builds, tests, and runs the client Playwright project for the public site and the installed PWA.	pull requests that touch its paths (36 path filters); pushes to main and develop that touch its paths; manual dispatch	No
CodeQL Cache Prune	Deletes stale CodeQL overlay databases from the Actions cache so they cannot evict the Foundry caches the contracts jobs rely on.	pushes to develop; a schedule (37 * * * * UTC); manual dispatch	No
Contracts Manual	Runs a chosen contracts operation (fork readiness, the CI lane, or both) on demand by calling the Contracts workflow.	manual dispatch	No
Contracts Nightly	The deep fuzz and invariant lane: pull-request CI runs the capped test profile for speed, and this run restores full depth through the ci profile.	a schedule (17 3 * * * UTC); manual dispatch	No
Contracts	Compiles, lints, and tests the Solidity packages and the contract script suite.	pull requests that touch its paths (9 path filters); pushes to main and develop that touch its paths; a call from another workflow	No
Coverage Nightly	Enforces the measured coverage floors across the packages. Pull requests run plain package tests for fast feedback; this lane measures.	pushes to main; a schedule (43 8 * * * UTC); manual dispatch	No
Dependabot Sync Publish	Publishes repair data from a successful Dependabot Sync run. It validates the origin run, associated PR and current head, executes only trusted default-branch code, and writes a fast-forward repair commit.	completion of another workflow	No
Dependabot Sync	Prepares aligned root and matching workspace dependency pins, the root Bun lockfile, and generated docs on Dependabot package PRs; refreshes generated docs for pinned GitHub Actions updates. Preparation has read-only permissions and lifecycle scripts disabled.	every pull request	No
Design	Checks the design system: Storybook, story coverage, and DesignMD token parity, with optional Chromatic publishing.	pull requests that touch its paths (43 path filters); pushes to main and develop that touch its paths; manual dispatch	No
Docs	Tests the docs generators, audits documentation authority, checks that generated projections and ontology pages are current, and builds the docs site.	pull requests that touch its paths (100 path filters); pushes to main and develop that touch its paths; manual dispatch	No
Indexer	Builds and tests the Envio indexer handlers against the contract ABIs and deployment artifacts.	pull requests that touch its paths (10 path filters); pushes to main and develop that touch its paths	No
Ontology	Validates the ontology sidecar against the code it anchors and keeps its generated reference pages current.	pull requests that touch its paths (96 path filters); pushes to main and develop that touch its paths	No
Release	Builds and publishes a tagged release.	pushed tags matching v*.*.*	No
Shared	Typechecks and tests the shared package: hooks, providers, protocol modules, and UI foundations.	pull requests that touch its paths (12 path filters); pushes to main and develop that touch its paths; a schedule (19 7 * * 1 UTC)	No
Supply Chain Guardrails	Four lanes over the repository's own safety surfaces: formatting on every run; the supply-chain audit of manifests, lockfiles, and the release-age rule; guidance integrity (agent guidance, skill contracts, immutable plan reports, the QA test ID ledger, test quality, and plan hub validation); and workflow performance parity, which pins the validation selector, the git hooks, and the package test configurations.	pull requests that touch its paths (39 path filters); pushes to main and develop that touch its paths; manual dispatch	No

Admin

Builds and tests the steward cockpit when admin code, the shared code it imports, or the shared test support changes.

• Use it when: A change under packages/admin or the shared UI and hooks it depends on.
• Runs on: pull requests that touch its paths (29 path filters); pushes to main and develop that touch its paths; manual dispatch.
• Jobs: e2e, lighthouse, lint-build, sourcemaps, test.
• Required status: no, but the CI Gate waits for it on a pull request that touches its paths.
• File: .github/workflows/admin.yml

Agent

Typechecks and tests the messaging agent and its public HTTP API when agent or shared code changes.

• Use it when: Bot, webhook, or public API changes.
• Runs on: pull requests that touch its paths (16 path filters); pushes to main and develop that touch its paths.
• Jobs: lint-typecheck-build, test.
• Required status: no, but the CI Gate waits for it on a pull request that touches its paths.
• File: .github/workflows/agent.yml

CI Gate

The one required status. It derives the workflows a pull request's changed files should trigger, waits for each to register and report, and fails as soon as one fails or never shows up, so path-filtered workflows cannot silently weaken branch protection.

• Use it when: Every pull request on any base branch. Branch protection points here instead of at the per-package workflows.
• Runs on: every pull request.
• Jobs: gate.
• Required status: yes, branch protection waits for it.
• File: .github/workflows/ci-gate.yml

Client

Builds, tests, and runs the client Playwright project for the public site and the installed PWA.

• Use it when: Client views, routes, service worker, PWA packaging, or the shared UI they render.
• Runs on: pull requests that touch its paths (36 path filters); pushes to main and develop that touch its paths; manual dispatch.
• Jobs: e2e, lighthouse, lint-build, sourcemaps, test.
• Required status: no, but the CI Gate waits for it on a pull request that touches its paths.
• File: .github/workflows/client.yml

CodeQL Cache Prune

Deletes stale CodeQL overlay databases from the Actions cache so they cannot evict the Foundry caches the contracts jobs rely on.

• Use it when: Housekeeping only: it runs after every push to develop and hourly as a backstop. Nothing to trigger by hand unless the cache fills up.
• Runs on: pushes to develop; a schedule (37 * * * * UTC); manual dispatch.
• Jobs: prune.
• Required status: no, and the CI Gate never waits for it: it has no pull request path rule.
• File: .github/workflows/codeql-cache-prune.yml

Contracts Manual

Runs a chosen contracts operation (fork readiness, the CI lane, or both) on demand by calling the Contracts workflow.

• Use it when: An operator wants a contracts check outside a pull request, for example before a release.
• Runs on: manual dispatch.
• Jobs: contracts.
• Required status: no, and the CI Gate never waits for it: it has no pull request path rule.
• File: .github/workflows/contracts-manual.yml

Contracts Nightly

The deep fuzz and invariant lane: pull-request CI runs the capped test profile for speed, and this run restores full depth through the ci profile.

• Use it when: Nightly at 03:17 UTC, or on demand after a change to invariants or fuzz targets.
• Runs on: a schedule (17 3 * * * UTC); manual dispatch.
• Jobs: deep-fuzz.
• Required status: no, and the CI Gate never waits for it: it has no pull request path rule.
• File: .github/workflows/contracts-nightly.yml

Contracts

Compiles, lints, and tests the Solidity packages and the contract script suite.

• Use it when: Any change under packages/contracts or the contract scripts; the manual workflow calls it with an operation name.
• Runs on: pull requests that touch its paths (9 path filters); pushes to main and develop that touch its paths; a call from another workflow.
• Jobs: fork-readiness-arbitrum, fork-readiness-core, lint-build, realism-audit, unit.
• Required status: no, but the CI Gate waits for it on a pull request that touches its paths.
• File: .github/workflows/contracts.yml

Coverage Nightly

Enforces the measured coverage floors across the packages. Pull requests run plain package tests for fast feedback; this lane measures.

• Use it when: Nightly at 08:43 UTC and after every push to main.
• Runs on: pushes to main; a schedule (43 8 * * * UTC); manual dispatch.
• Jobs: coverage.
• Required status: no, and the CI Gate never waits for it: it has no pull request path rule.
• File: .github/workflows/coverage-nightly.yml

Dependabot Sync Publish

Publishes repair data from a successful Dependabot Sync run. It validates the origin run, associated PR and current head, executes only trusted default-branch code, and writes a fast-forward repair commit.

• Use it when: Completion of Dependabot Sync with a repair artifact for a same-repository package or GitHub Actions PR. The built-in token requires approval for follow-up PR CI; see scripts/README.md for credential options.
• Runs on: completion of another workflow.
• Jobs: publish.
• Required status: no, and the CI Gate never waits for it: it has no pull request path rule.
• File: .github/workflows/dependabot-sync-publish.yml

Dependabot Sync

Prepares aligned root and matching workspace dependency pins, the root Bun lockfile, and generated docs on Dependabot package PRs; refreshes generated docs for pinned GitHub Actions updates. Preparation has read-only permissions and lifecycle scripts disabled.

• Use it when: An opened, reopened, or updated same-repository Dependabot Bun, npm or GitHub Actions PR. CI Gate requires the no-repair verification job to succeed; a skipped job blocks the head even after its repair artifact is deleted. Dependabot Sync Publish writes any repair on a new head.
• Runs on: every pull request.
• Jobs: prepare, synchronized.
• Required status: no, but the CI Gate waits for same-repository pull requests authored by dependabot[bot].
• File: .github/workflows/dependabot-sync.yml

Design

Checks the design system: Storybook, story coverage, and DesignMD token parity, with optional Chromatic publishing.

• Use it when: Shared components, styles, tokens, any DESIGN.md, or the docs stylesheet. Dispatch it with publish_chromatic to publish Storybook.
• Runs on: pull requests that touch its paths (43 path filters); pushes to main and develop that touch its paths; manual dispatch.
• Jobs: design-guardrails, storybook.
• Required status: no, but the CI Gate waits for it on a pull request that touches its paths.
• File: .github/workflows/design.yml

Docs

Tests the docs generators, audits documentation authority, checks that generated projections and ontology pages are current, and builds the docs site.

• Use it when: Anything under docs/, the generator scripts, the skills catalog, or a source a projection reads.
• Runs on: pull requests that touch its paths (100 path filters); pushes to main and develop that touch its paths; manual dispatch.
• Jobs: build.
• Required status: no, but the CI Gate waits for it on a pull request that touches its paths.
• File: .github/workflows/docs.yml

Indexer

Builds and tests the Envio indexer handlers against the contract ABIs and deployment artifacts.

• Use it when: Indexer handlers, schema, or config, or the ABIs and deployments they read.
• Runs on: pull requests that touch its paths (10 path filters); pushes to main and develop that touch its paths.
• Jobs: lint-build, test.
• Required status: no, but the CI Gate waits for it on a pull request that touches its paths.
• File: .github/workflows/indexer.yml

Ontology

Validates the ontology sidecar against the code it anchors and keeps its generated reference pages current.

• Use it when: Ontology edits, the data model and entity matrix projections, or a source the sidecar points at.
• Runs on: pull requests that touch its paths (96 path filters); pushes to main and develop that touch its paths.
• Jobs: ontology-drift.
• Required status: no, but the CI Gate waits for it on a pull request that touches its paths.
• File: .github/workflows/ontology.yml

Release

Builds and publishes a tagged release.

• Use it when: A pushed version tag. Maintainers cut releases from main; nothing to run by hand.
• Runs on: pushed tags matching v*.*.*.
• Jobs: release.
• Required status: no, and the CI Gate never waits for it: it has no pull request path rule.
• File: .github/workflows/release.yml

Shared

Typechecks and tests the shared package: hooks, providers, protocol modules, and UI foundations.

• Use it when: Any shared source change. It also runs weekly to catch drift that no pull request touched.
• Runs on: pull requests that touch its paths (12 path filters); pushes to main and develop that touch its paths; a schedule (19 7 * * 1 UTC).
• Jobs: changes, lint-typecheck, test.
• Required status: no, but the CI Gate waits for it on a pull request that touches its paths.
• File: .github/workflows/shared.yml

Supply Chain Guardrails

Four lanes over the repository's own safety surfaces: formatting on every run; the supply-chain audit of manifests, lockfiles, and the release-age rule; guidance integrity (agent guidance, skill contracts, immutable plan reports, the QA test ID ledger, test quality, and plan hub validation); and workflow performance parity, which pins the validation selector, the git hooks, and the package test configurations.

• Use it when: Dependency, lockfile, toolchain, or workflow changes; agent guidance, skills, plan hubs, and the QA catalog; the validation policy, selector, and git hooks. Each lane after formatting runs only when its own paths change.
• Runs on: pull requests that touch its paths (39 path filters); pushes to main and develop that touch its paths; manual dispatch.
• Jobs: audit, changes, format, guidance, parity.
• Required status: no, but the CI Gate waits for it on a pull request that touches its paths.
• File: .github/workflows/supply-chain-guardrails.yml

Root quality and build scripts

The workflows call these root scripts, so running one locally reproduces that step.

Run it	What it runs
bun run build	bun run --cwd packages/contracts build && bun run --cwd packages/shared build && bun run --cwd packages/indexer build && bun run --cwd packages/client build && bun run --cwd packages/admin build
bun run check	node scripts/dev/ci-local.js
bun run format	node scripts/dev/package-commands.mjs root format
bun run lint	node scripts/quality/check-react-patterns.js && bun --bun run oxlint packages/client/src packages/admin/src packages/shared/src packages/indexer/src packages/agent/src packages/contracts/script --deny-warnings && bun run --cwd packages/contracts lint --check
bun run test	node scripts/dev/test.js