> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livepeer.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Automations
> Map of GitHub Actions, CI gates, scheduled jobs, dispatchers, remediators, and automation governance in the Livepeer Docs repo.
# Automations
The automation layer is the repo's operating system. The repo is ownerless and self-governed – there is no single human responsible for keeping content fresh, links unbroken, navigation in sync, or generated artefacts aligned with their sources. The automation layer fills that role. **It validates new contributions before they land, regenerates derived artefacts the moment a source changes, ingests live data from external services, repairs deterministic drift, and surfaces what it cannot fix as backlog.**
This page documents what's live as of 2026-05-23. The canonical published framework is at [`docs-guide/frameworks/github-actions.mdx`](../frameworks/github-actions.mdx) (with the internal working spec at `.github/workspace/framework-canonical.md`).
## The 4-tier composable architecture (D-GOV-08, 2026-05-22)
A major refactor on 2026-05-22 consolidated **53 standalone workflows → 11 active workflows** under a 4-tier composable model. Workflow YAML files are dispatchers only; the typed work lives in scripts. The type classification comes from what the script does, not the workflow filename. Smoke test passing 66/66 dispatchers per `framework-canonical.md` Status line.
| Tier | Layer | What lives here | Count (2026-05-23) |
| ---- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| 1 | `.github/workflows/*.yml` | Pure dispatchers (trigger + permissions + orchestration only) | **11 active** (6 `dispatch-{concern}` + 5 `interface-governance-*`) |
| 2 | `operations/scripts/dispatch/{concern}/` | Meta-dispatchers (per-mode entry: check / generate / scan / update / repair / sync) | 102 dispatcher scripts |
| 3 | `operations/scripts/{type}/{concern}/{niche}/` | Atomic scripts (validator / generator / integrator / remediator / audit / interface) | 219 atomic scripts |
| 4 | `tools/lib/` | Shared libraries imported by atomics (governance, copy-governance, docs, docs-usefulness, ai, bootstrap) | 6 lib subtrees |
The refactor locked **18 decisions** (D-ACT-01..10 + D-GOV-01..08) in [`.github/workspace/decisions-log.mdx`](https://github.com/livepeer/docs/blob/docs-v2-dev/.github/workspace/decisions-log.mdx).
## The 11 active workflows
### 6 concern dispatchers (`dispatch-{concern}.yml`)
Each follows an identical 4-mode shape per D-ACT-08 + D-GOV-08:
1. **PR check** (`pull_request`) – `dispatch-{concern}-check.js --staged`
2. **Post-merge** (`push` to `docs-v2`) – `dispatch-{concern}-generate.js --write` (or `-sync.js`)
3. **Scheduled** (cron) – `dispatch-{concern}-update.js` or `-scan.js` with FLAGS pattern (⚠️ see §[The cron-is-dry-run bug](#known-gaps))
4. **Manual repair** (`workflow_dispatch` with `mode=manual`) – `dispatch-{concern}-repair.js` with FLAGS pattern
| File | Concern | Cron | Path filters (PR/push) |
| ------------------------------ | --------------- | --------------- | ---------------------------------------------------------------------------------------- |
| `dispatch-brand.yml` | brand | Mon 06:30 UTC | `v2/**/*.mdx`, `snippets/**/*.mdx`, `snippets/components/**` |
| `dispatch-copy.yml` | copy | daily 03:00 UTC | `v2/**/*.mdx`, `snippets/data/**` |
| `dispatch-discoverability.yml` | discoverability | daily 04:00 UTC | `v2/**`, `snippets/**`, `docs.json` |
| `dispatch-governance.yml` | governance | daily 07:00 UTC | `.github/**`, `operations/scripts/**`, `docs-guide/**`, `tools/config/**`, `snippets/**` |
| `dispatch-health.yml` | health | daily 06:00 UTC | `v2/**`, `snippets/**`, content/scripts paths |
| `dispatch-maintenance.yml` | maintenance | daily 05:00 UTC | `snippets/components/**`, `snippets/data/**`, `docs.json` |
`dispatch-governance.yml` has an additional fifth job: `pipeline-tests` runs `operations/tests/integration/pipeline-smoke-test.js` (66/66 dispatcher smoke test) + `pipeline-functional-tests.js` (synthetic violation cycles per D-GOV-03). `dispatch-health.yml` and `dispatch-brand.yml` open a PR on manual repair via `peter-evans/create-pull-request@v7`.
### 5 governance interfaces (`interface-governance-*.yml`)
| File | Trigger | What it does |
| --------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `assign-reviewers.yml` | `pull_request` (opened/reopened/ready/edited/labeled) | Codex PR eligibility gate; request Copilot reviewer; fallback assign via `gh` CLI |
| `close-linked-issues.yml` | `push` to docs-v2 | Close issues linked to merged PRs |
| `index-issues.yml` | `issues` events + cron every 6h | Rolling docs-v2 issue index (marker-based discovery, single canonical index issue) |
| `intake-discord-issues.yml` | `repository_dispatch` (type: `discord-issue-intake`) | Discord webhook → GitHub issue conversion |
| `label-issues.yml` | `issues` events | Auto-label new issues by parsed body headings (`area:*` + `priority:*`) |
All 5 interfaces are tagged `# pipeline: P7` in their header comment – distinct from the P2-P6 dispatcher taxonomy.
## Pipeline patterns (A–G)
Every pipeline follows one of these shapes. Source: `.github/workspace/framework-canonical.md`.
| Pattern | Trigger | Flow | Example |
| ------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **A – Integrate** | cron / dispatch / manual | Fetch external API → transform → diff → commit + push → on failure create issue | contracts addresses; exchanges data; social feeds |
| **B – Generate** | push to deploy branch / manual | Read repo data → generate output → diff → commit + push | catalogs; component registry; docs-index; llms files; AI sitemap |
| **C – Check** | pull\_request / push | Run validator(s) → report pass/fail → P2 block or P3 advise | docs-quality; OpenAPI reference audit; link health |
| **D – Scan, Report, Act** | cron / manual | Scan → report → route findings (auto-remediate / create issue / re-dispatch). "No headless scans – every finding gets a response." | content-quality scheduled scan + manual repair pair |
| **E – Repair** | cron / manual | Scan for drift → fix → commit or PR | brand sweep; styles sweep |
| **F, G** | – | reserved; see framework canonical for full spec | – |
The gold standard implementation is the contracts pipeline (Pattern A with shadow verification) – daily cron + verification-only shadow + bytecode auth against Arbitrum + Ethereum + health-check artefacts + incident issue creation + publish gate requiring `--check` rerun.
## Operations scripts taxonomy
321 active scripts under `operations/scripts/`, 38 in archive. Every script declares `@type` / `@concern` / `@niche` via an 11-tag JSDoc header.
| Type | Live count | Purpose |
| ----------------------- | ---------: | ------------------------------------------------------------------------------------------------------------------- |
| `dispatch` | **102** | Meta-dispatchers + per-concern entries (`-check`, `-update`, `-scan`, `-generate`, `-repair`, `-sync`) per D-ACT-08 |
| `integrators` | **58** | Pull/transform external + internal data into repo |
| `validators` | **55** | Exit-code checks for hooks, CI, manual validation |
| `remediators` | **37** | Deterministic repairs to existing files |
| `generators` | **31** | Produce derived files from canonical sources |
| `audits` | **25** | Read-only scans and reports |
| `interfaces` | **8** | Issue/PR/Discord event handlers |
| `archive` + `x-archive` | 38 | Deprecated or legacy scripts retained for review/compatibility |
**JSDoc compliance (sampled 2026-05-23):**
* 327 of 321 active scripts have `@purpose` (canonical) – basically 100%
* 81% have `@type`, 81% have `@concern` (sampled 100)
* 45 scripts repo-wide still use retired `@category`
* 4 scripts use retired `@domain`
* The retired tags (`@category`, `@domain`, `@needs`, `@purpose-statement`, `@owner`) are explicitly banned per `docs-guide/policies/script-governance.mdx` lines 195-205
**The previously documented "218 non-compliant scripts" figure (from gap-analysis.mdx as of 2026-05-14) is stale.** Actual non-compliance as of 2026-05-23 is \~45-50 scripts with retired tags – a 4× improvement from the documented baseline.
## Hook pipeline (`.githooks/`)
5 active hooks + 4 docs + 4 utility files in `.githooks/`. Hard gates run on every commit, scoped to a 60-second runtime budget.
| Hook | What it enforces |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pre-commit` | MDX syntax; `docs.json` redirect integrity; no-deletion guard; `.allowlist` + `v1/` protection; Codex branch isolation. **22.8 KB; the entry-point.** |
| `pre-push` | Codex `codex/*` branch contract; lock overlap; AI-stash policy; non-fast-forward push guard |
| `pre-commit-no-deletions` | Deletion guard (alternative variant – wiring status unclear; flagged in SLICE-03 as dead code) |
| `install.sh` | Wires `.git/hooks/pre-commit` → `.githooks/pre-commit` |
| `verify.sh` | One-shot verification runner (7 internal checks: MDX, JSON, JS, shell, mintlify, snippets-import, browser); **orphan in pre-commit** per SLICE-03 – defined but not invoked |
Bypass policy in `.githooks/BYPASS.md`. Pre-commit has an undocumented carve-out: allows deletion without `--trailer "allow-deletions=true"` if the blob hash matches a `v2/x-archived/` follow-up.
## Gate layers
| Layer | Belongs here | Does not belong here |
| --------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Pre-commit | Fast staged checks; generated artefact drift checks; root structure guardrails; v1 frozen-file guard | Browser sweeps; network calls; long full-site audits |
| Pre-push | Codex branch contract; lock checks; issue readiness; branch safety | Style checks already handled by pre-commit or PR CI |
| PR CI | Changed-file quality; docs-index; OpenAPI references; component + governance checks | Local-only setup checks |
| Scheduled CI | Broad freshness; links; page integrity; data refresh; advisory scans | Mutating source files without deterministic PR or repair path |
| Manual dispatch | One-off migrations; approvals; repair waves; large data updates | Routine drift that should be covered by a gate |
## Ownerless automation contract
Each production automation must declare (per `docs-guide/policies/ownerless-governance.mdx`):
| Requirement | Implementation target |
| ---------------- | ------------------------------------------------------------------------------ |
| Canonical source | Policy, config, source data, docs tree, or workflow definition that owns truth |
| Validator | Local or CI command that fails deterministically when drift exists |
| Repair command | Exact command or workflow that restores derived state |
| Primary gate | One layer only (pre-commit / PR / scheduled / manual) |
| Output contract | Where reports, generated files, or PR comments are written |
| Retention policy | Whether outputs are committed, archived, summarised, or purged |
**Post-D-ACT-10 (2026-04-05):** the canonical registry is `operations/governance/config/repo-governance-surfaces.json` with **5 unified surfaces, 4 ownerless-ready, 1 advisory** (`github-workspace-governance`). The file's `bridge_mode` is `"retired"` and `legacy_bridge_inventory` is empty – migration complete. The legacy 8-entry `ownerless-governance-surfaces.json` remains on disk for reference but is superseded.
## Locked decisions (18)
10 D-ACT decisions + 8 D-GOV decisions, split across two logs by date:
* **D-ACT-01..10 + D-GOV-07..08** in [`.github/workspace/decisions-log.mdx`](https://github.com/livepeer/docs/blob/docs-v2-dev/.github/workspace/decisions-log.mdx) (workflow architecture, taxonomy, dispatcher model; locked 2026-03-31 through 2026-05-22)
* **D-GOV-01..06** in [`.github/workspace/design/governance/design-overview.md`](https://github.com/livepeer/docs/blob/docs-v2-dev/.github/workspace/design/governance/design-overview.md) (governance principles; locked 2026-04-04)
| ID | What it locks |
| -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| D-ACT-01 | `interface` is a 7th type (issue/PR event handlers – not a subtype of `automation`) |
| D-ACT-02 | `P5-auto` is a distinct pipeline tag from `P5` (scheduled writes vs scheduled read-only) |
| D-ACT-03 | 7 social-data workflows consolidate into 1 matrix `update-social-feeds.yml` |
| D-ACT-04 | Workflow naming `type-concern-function-name.yml` with closed-enum 11 function verbs |
| D-ACT-05 | Concern taxonomy expanded from 4 to 7 (`integrations`, `copy`, `maintenance`, `health`, `discoverability`, `governance`, `brand`) |
| D-ACT-06 | Migrate `.github/scripts/` into `operations/scripts/` governance – `.github/scripts/` is **intentionally empty** as a result |
| D-ACT-07 | Rename `automation` type to `integrator` (script + workflow side) |
| D-ACT-08 | Workflows are dispatchers; type reflects the script. No inline logic in YAML |
| D-ACT-09 | Pipeline output locations (per type/concern) |
| D-ACT-10 | Unified governance registry replaces `ownerless-governance-surfaces.json` (single source of truth) |
| D-GOV-01 | Governance is enforcement infrastructure, not content rules |
| D-GOV-02 | Categories are enforcement layers, not surfaces (pre-commit, PR, post-merge, scheduled, self-heal, hooks, lifecycle) |
| D-GOV-03 | Every detection must self-repair or escalate (auto-fix > PR > issue > block) |
| D-GOV-04 | Tooling makes correct the default (templates, scaffolding, IDE snippets) |
| D-GOV-05 | Advisory before hard gate (P3 first, promote to P2 after baseline clean) |
| D-GOV-06 | Align script framework to actions framework (7 types, 7 concerns) |
| D-GOV-07 | Every workflow dispatcher must have a local CLI equivalent |
| D-GOV-08 | Every folder is governed. No commit of files that do not belong |
**Pipeline tag taxonomy (8 tags):** P2 (PR required), P3 (PR advisory), P4 (post-merge), P5 (scheduled read-only), P5-auto (scheduled writes), P6 (self-heal), manual, event-driven.
**Concern taxonomy (7):** `integrations`, `copy`, `maintenance`, `health`, `discoverability`, `governance`, `brand`.
**Type taxonomy (7):** `integrator`, `generator`, `validator`, `audit`, `remediator`, `dispatch`, `interface`.
## Recently shipped (May 2026)
### Veracity dispatcher tranche
Three new dispatchers under `operations/scripts/dispatch/content/veracity/` (type `dispatch`, concern `health`, niche `veracity`) close the long-standing "veracity-pass DRAFT blocks Phase 6" gap noted in the Checks Framework:
| Script | Pipeline | Purpose |
| ---------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `docs-research-packet.js` | manual packet generator | Generic engine: derives nav/manifest/path scope, runs the research stack tranche-by-tranche, writes reusable packet reports + master rollup |
| `orchestrator-guides-research-review.js` | manual wrapper | Delegates to `docs-research-packet.js` with live Orchestrators Guides nav scope and legacy output root |
| `docs-page-research-pr-report.js` | manual, experimental advisory PR integration, non-blocking | Runs fact-check research runner on changed docs pages; emits PR artefact summarising claim families, contradictions, unresolved factual risk, propagation follow-up |
These are manual-pipeline (not yet on cron); inputs/outputs registered under `workspace/research/claims/` + `workspace/reports/`. Unit-tested under `operations/tests/unit/`.
### Local social-feed dispatcher
`operations/scripts/dispatch/content/data/run-solutions-social-fetch.js` (type `dispatch`, concern `integrations`, niche `social-feeds`) mirrors `dispatch-social-feeds.yml` for local workstation use: loads `.env`, supports `--mode forum,youtube`, `--dry-run`, `--skip discord`. Iterates the 7 fetchers under `operations/scripts/integrators/copy/social-feeds/`. **Local-only, not in any GitHub Actions workflow** (a deliberate contributor tool, not a duplicate CI surface). Closes the gap where contributors couldn't fetch live forum/discord/blog/YouTube/GitHub data on their workstation before pushing snippets that depended on freshly-generated outputs.
## Known gaps
### Cron-is-dry-run-by-default bug – FIXED 2026-05-25
**Status:** Fixed in commit `e42946cdf` on `docs-v2-dev-draft`. Pending merge to `docs-v2`.
Every `dispatch-{concern}.yml` scheduled job previously had this pattern:
```yaml icon="terminal" theme={"theme":{"light":"github-light","dark":"dark-plus"}}
- name: {concern} scheduled meta
run: |
FLAGS=""
if [[ "${{ inputs.dry_run }}" == "false" ]]; then FLAGS="--write --verify"; fi
node operations/scripts/dispatch/.../dispatch-{concern}-update.js $FLAGS
```
The `schedule` event did not pass `inputs.dry_run` – it was empty, never the literal string `"false"`. So `FLAGS` stayed empty and the script ran with no `--write --verify`. Cron physically could not trigger the write mode. Only `workflow_dispatch` with explicit `dry_run: false` actually wrote.
**Net effect (pre-fix):** the entire daily cron schedule was check-only theatre. Root cause of:
* Contract addresses last written 2026-05-04 (19 days stale on 2026-05-23) despite `_health-checks.json` confirming the pipeline ran daily
* `llms.txt` + `sitemap-ai.xml` 47 days stale (no manual dispatch with `dry_run: false`)
* `generate-og-images.js` + `generate-seo.js` classified "manual-only" in 2026-03-30 P0 flag – they're CI-wired but cron defaulted to dry-run
**Fix shipped:** inverted FLAGS default in all 6 `dispatch-{concern}.yml` (`FLAGS="--write --verify"; if ... == "true" then FLAGS=""`). Manual-repair jobs deliberately unchanged (safe-by-default for human-triggered repairs). Post-merge jobs unaffected (already hardcode `--write`).
### Archive sprawl
Three archive lanes in `.github/`:
1. `.github/workflows/deprecated/` (1 file: `update-blog-data.yml`)
2. `.github/workflows/x-archive/` (61 files: 56 `.archived` + 5 non-`.archived`)
3. `.github/x-archive/` (separate at `.github` root, contents not enumerated)
The script-framework declares one lane (`x-archive/`). Plus `operations/scripts/archive/` and `operations/scripts/x-archive/` – two more for scripts.
### Path drift from pre-refactor docs
`.github/scripts/` is **intentionally empty** per D-ACT-06 (migration locked 2026-04-04). Stale references in older docs need updating:
* Contracts pipeline doc references `.github/scripts/fetch-contract-addresses.js`. Current path: `operations/scripts/integrators/maintenance/contracts/fetch-contract-addresses.js`.
* `agent-governance-framework.mdx` lines 137 + 228 reference `validators/governance/check-agent-docs-freshness.js`; actual path is `validators/governance/compliance/check-agent-docs-freshness.js` (missing `/compliance/` subfolder). `AGENTS.md` line 98 has the right path.
### Published framework lags the 2026-05-22 refactor
`.github/workspace/framework-canonical.md` says: *"Canonical published framework: `docs-guide/frameworks/github-actions.mdx` – read that first."* But the published framework likely predates the 2026-05-22 refactor. Sync state undocumented.
### Stale governance map
`node operations/scripts/generators/governance/reports/generate-repo-governance-status.js --check` reports `docs-guide/repo-ops/config/repo-governance-map.mdx is stale.` Self-detection works; auto-repair doesn't run.
### `.githooks` orphan + dead code
* `verify.sh` is defined with 7 internal checks but **not invoked by active `pre-commit`** – dead enforcement (per SLICE-03)
* `pre-commit-no-deletions` is unwired dead code per its own JSDoc (`@pipeline manual – not yet in pipeline`)
* `.githooks/post-commit.disabled` has NO JSDoc header at all
* `.githooks/script-index.md` only catalogues 3 of 7 hook scripts (generator filter broken)
### `actions-library/` per-action MDX catalogue not enumerated
`.github/workspace/actions-library/{type}/{concern}/{niche}/*.mdx` – one MDX file per atomic action. Mostly auto-generated from script JSDoc headers. Full enumeration not done; freshness vs source not verified.
### Phase 4 workflow consolidation pending
`framework-canonical.md` Status line says "Phase 4 consolidation shipped" but **Phase 6 (renames, inline-script extraction, consolidation) is explicitly noted as pending** per the 2026-04-08 component-governance row in CLAUDE.md.
## Related
* **[GitHub Actions Framework](../frameworks/github-actions.mdx)** – canonical published framework (v2.2, synced 2026-05-25 with the 2026-05-22 refactor + D-ACT-09/10 + D-GOV-07/08)
* **[Script Framework](../frameworks/script-framework.mdx)** – 11-tag JSDoc spec + type/concern/niche taxonomy
* **[Script Governance Policy](../policies/script-governance.mdx)** – what retired tags look like + repair commands (lines 195-205)
* **[Ownerless Governance Policy](../policies/ownerless-governance.mdx)** – the 4-part contract every governed surface must declare
* **[Infrastructure Principles](../policies/infrastructure-principles.mdx)** – gate-layer rule ownership
* **[Generated-Artifact & Hook Governance](../policies/generated-artifact-and-hook-governance.mdx)** – 3 classes + commit/hook/CI policies + delta strategies for every generated output
* **[Quality Gates Policy](../policies/quality-gates.mdx)** – full gate-layer map with named tools per tier
* **[Workflows Catalog](../catalog/workflows-catalog.mdx)** – generated catalogue of all workflows (auto-regenerated by `dispatch-maintenance`)
* **[Scripts Catalog](../catalog/scripts-catalog.mdx)** – generated catalogue of all scripts
* **`.github/workspace/framework-canonical.md`** – internal working spec (the 2026-05-22 Status line is the most current document)
* **`.github/workspace/decisions-log.mdx`** – 18 locked decisions (D-ACT-01..10 + D-GOV-01..08)