Set up governance

Your contract

The contract is the list of canonical components (the ones people and agents should reuse instead of rebuilding) and the stylesheet files that define your tokens. The scan proposes both; you confirm. There is deliberately no free-text way to add vocabulary in the dashboard — Fragments never invents vocabulary on your behalf.

Approving the contract arms exactly four Tier A rules: components/shadow-component (FUI1007), components/prefer-library (FUI1004), tokens/css-vars-must-be-defined (FUI2015), and tokens/upstream-drift (FUI2017). Until a contract exists, the customer default produces zero findings.

Path A or Path B

Path A — you have a component library. The library's compiled manifest is the source of truth. Build it once locally to see what will be published, then declare the library as a canonical source in fragments.config.ts (paths are repository-root-relative):

npx @usefragments/cli build

import type { FragmentsConfig } from "@usefragments/core";

const config = {
  framework: "react",
  govern: {
    presets: ["universal@2"],
    canonicalSources: [
      {
        kind: "directory",
        path: "src/components",
        include: ["Button", "Input", "Dialog"],
      },
    ],
  },
} satisfies FragmentsConfig;

export default config;

Your governance CI does the rest: the same scan that reports findings publishes the manifest's vocabulary — every root component, including compound roots and their members — to Fragments Cloud. Open the Contract page and click Adopt vocabulary: that one click writes the contract with full provenance, and nothing changes until you approve.

Every published contract gets a content-addressed identity (an FCID) and a version. Agent hooks, CI checks, and the hosted MCP tools all read the same contract, so a component is either canonical everywhere or nowhere.

Path B — no library yet. The scan detects component definitions and the Contract page lists them as candidates. Confirm the ones that are canonical, pick your token source files, save the manifest as one revision, and run a scan to publish it — same approval surface, same versioned, enforceable contract.

When your library changes, the next CI scan republishes the manifest. The Contract page flips to Behind manifest and shows exactly which roots were added or removed; click Update contract to adopt the new vocabulary — the enforced contract never moves without that click.

What every pull request gets

The workflow runs the same command you can run locally:

npx @usefragments/cli check --ci

When the repository has no local configuration, the CLI fetches your cloud-managed policy automatically, so the rules CI enforces are exactly the ones you approved. On pull requests the check scans only what changed, keeping runs fast on large codebases.

Results land in three places: a GitHub Check Run with annotations on the exact lines that drifted, inline review comments on the pull request itself, and the Fragments dashboard, where the same findings get triage, bulk actions, and history. To tune rule severity, scope rules off legacy paths, or add auditable suppressions, see the configuration reference.

The dashboard's "Caught before merge" number counts unique blocking violations observed on open PRs, deduplicated by finding fingerprint per PR — repeated pushes to the same failing PR never re-count the same violation. A second line reports how many of those PRs later merged clean. Both figures count observed events only; Fragments does not report counterfactual "violations prevented" numbers.

Using GitLab

GitLab repositories get the generated Fragments job instead of a GitHub Actions workflow; if both providers are present, setup requires an explicit choice and writes neither CI file. Fragments owns .gitlab-ci.fragments.yml and never edits your .gitlab-ci.yml — if your root file already has an include block, the job is still written and setup prints the one line to add:

include:
  - local: '.gitlab-ci.fragments.yml'

The job runs on merge requests and on your default branch, and publishes its findings as a Code Quality report. GitLab reads that report natively, so findings show up in the merge request itself — no bot, no token, no Fragments Cloud in the loop. Every finding carries a stable fingerprint, so GitLab follows the same one across pushes instead of listing it again.

fragments_governance:
  image: node:22
  stage: test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  script:
    - corepack enable
    - pnpm install --frozen-lockfile
    - pnpm exec fragments check --ci --format json --codequality gl-code-quality-report.json
  artifacts:
    when: always
    reports:
      codequality: gl-code-quality-report.json

When governance is inert

Governance is inert when a run resolves no enforceable rule family at all — no canonical components, no token sources, and no hygiene rules. An inert run finds nothing, which looks exactly like a clean run.

So check --ci refuses to report it as a pass. When a repository declares governance but resolves inert, the CI check fails and names the missing families:

✖ Governance gate: Governance inert — no enforceable rule family is armed
governance is inert but --ci claims a gate; author a contract
(see remediations) or pass --allow-inert to bypass

The fix is to approve a contract, not to silence the gate. A repository still mid-migration can pass --allow-inert to bypass it — a deliberate, temporary escape hatch that prints a warning on every run, so a bypassed gate is never mistaken for an enforced one.

A run with hygiene rules armed but no contract vocabulary declared is reported as degraded rather than inert: it enforces what it has, and says what it is missing.

The agent-side surfaces are honest about the same state. When the hosted policy cannot be reached, the vocabulary card reports that component-reuse enforcement is off rather than rendering a clean card — a hook that cannot prove your contract never implies compliance.

Troubleshooting

Fragments watches its own footprint. A push that edits or deletes the workflow file flips governance from active to broken, and the Governance page names what changed and how to repair it — usually restoring the file or re-running the one-click installation, which supersedes the old one safely. Nothing silently stops enforcing.

When enforcement looks wrong, run the doctor — it walks the whole chain and names the one action for the first broken link:

npx @usefragments/cli doctor

No canonical components registered — nothing has been adopted or configured yet. Follow Path A or Path B above.

Manifest error on the Contract page — your declared package published a missing, empty, or invalid manifest. Fix the manifest and push; Fragments never silently falls back to detection for a declared package.

Contract stale in the hook card — your local session is pinned to an older contract version. Re-run npx @usefragments/cli init to refresh the local bundle.