Agent-Ready Setup

Quick start

Run from your repo root. No flags needed for local-first setup:

npx @fragments-sdk/cli init

That detects your framework, classifies your components, writes the agent context files, wires a hosted MCP entry, generates a CI workflow, and captures a governance baseline. Verify the result with:

npx @fragments-sdk/cli status

Four green ticks means your agents now have working context, a hosted validator, a CI mirror, and (if connected) a Cloud sync. Anything else exits non-zero with a stable code so it's hookable into pre-commit and CI.

The Guardrails Contract

A repo has active guardrails when four things are true. The CLI produces all of them; fragments status verifies them.

• Agent context current. AGENTS.md references .fragments/agent-context.md, which exists and was generated against your current preset.
• Validation available. .mcp.json has a hosted fragments entry so agents can call lint/file and findings/for_file mid-edit.
• CI mirrors local. A workflow exists and runs the same engine you run locally, against the same preset.
• In sync with team (when Cloud-connected) — your local rules version matches what your team published in Fragments Cloud.

What init writes

Every file is idempotent. Re-running init refreshes what fragments owns without clobbering your content.

• fragments.config.ts — project shape, framework, pinned preset version (e.g. universal@2).
• AGENTS.md — the cross-tool convention file (read by Claude, Codex, Cursor). On first run we create it; on subsequent runs we add only one line pointing at the generated context. The rest of the file is yours.
• .fragments/agent-context.md — canonical primitives, available tokens, active rules, and the definition-of-done agents should follow. Generated on every init run.
• .mcp.json — merged conservatively. We only own the fragments entry; any other MCP servers you have configured are preserved. When a Cloud key is available, the entry points at the hosted Fragments MCP endpoint with an Authorization header.
• .github/workflows/fragments.yml — a PR + push workflow that runs fragments check with your preset, emits SARIF for code-scanning, and uploads a report artifact.
• .fragments/baseline.json — governance snapshot at init time. Future scans can compute deltas against this baseline.
• .fragments/classification.json — per-component canonical mapping if AI classification ran (requires ANTHROPIC_API_KEY or OPENAI_API_KEY; otherwise written empty and you can re-run classify later).

Coming from Cloud

If you signed up at app.usefragments.comand created an org or project before running the CLI, the wizard's last screen hands you a paste token scoped to your org, project, and (for monorepos) path. Run:

npx @fragments-sdk/cli init --token=fc_eyJ...

The CLI uses the token to pull your governance policy, classification, and baseline from Cloud, then writes the same local files as the local-first path. Re-run anytime to refresh after your team edits rules in the dashboard.

Verifying with fragments status

status reads the four contract items and reports a pass/fail per item. Useful both interactively and as a hook.

$ npx @fragments-sdk/cli status

Fragments status

  ✓ Agent context current
    .fragments/agent-context.md is referenced and current.
  ✓ Validation available
    hosted Fragments MCP endpoint is present.
  ✓ CI mirrors local
    .github/workflows/fragments.yml runs fragments check with universal.
  - In sync with team
    No Cloud sync file found; local-only project.

Guardrails active.

Exit codes

status exits non-zero when any required item fails. Each item has a stable exit code so scripts can react specifically.

• 0 — all contract items pass.
• 11 — Agent context current failed (missing or stale).
• 12 — Validation available failed (MCP entry missing or invalid).
• 13 — CI mirrors local failed (no workflow matching the active preset).
• 14 — In sync with team failed (Cloud sync stale or rules version mismatch).

Pre-commit hook

Drop into Husky / lefthook / git hooks directly:

#!/usr/bin/env sh
npx @fragments-sdk/cli status || {
  echo "Run 'fragments init' to refresh guardrails."
  exit 1
}

For JSON output suitable for CI dashboards, pass --json.

CI workflow

init writes a GitHub Actions workflow at .github/workflows/fragments.yml that runs fragments check on PRs and pushes, uploads a SARIF report to GitHub code-scanning, and writes a JSON report artifact.

To ingest findings into Fragments Cloud (Check Runs + inline PR review comments), add these repo secrets in your GitHub repo settings:

• FRAGMENTS_API_KEY — your project-scoped Fragments Cloud key.
• FRAGMENTS_CLOUD_URL — optional; defaults to https://app.usefragments.com.

Monorepos

GitHub Actions only reads workflows from the repository root, so a project at a subpath like apps/cloud can't ship a workflow at apps/cloud/.github/workflows. status understands this: when the canonical path is missing it walks up to the git repo root and scans .github/workflows/ for any workflow that runs fragments check with the right preset, and (when present) the right --dir.

For a project under apps/cloud with multiple packages, run init from each project root. Each gets its own scoped token (when Cloud-connected) and its own context files.

# from a monorepo subpackage
cd apps/cloud
npx @fragments-sdk/cli init --path apps/cloud
npx @fragments-sdk/cli status

AI component classifier

On first run, init scans your components and asks an LLM to map them to canonical primitives (Button, Input, Dialog, etc.). This step uses yourAnthropic or OpenAI API key — there's no Fragments proxy and no cost on our side.

export ANTHROPIC_API_KEY=sk-ant-...
npx @fragments-sdk/cli init

If no key is set, classification is skipped cleanly — everything else still runs. Add a key and run npx @fragments-sdk/cli classify later when ready.

Updating

init is idempotent. Run it again to:

• Refresh .fragments/agent-context.md with the latest preset rules.
• Re-pull team rules from Cloud (when a token is configured).
• Re-baseline governance findings.
• Pick up a new preset version (e.g. moving from universal@2 to universal@3).

Your AGENTS.md body is never touched after the initial pointer is added. Add --force to reinitialize an already-set-up project from scratch.

Troubleshooting

Exit code 11 — agent context. Most often: AGENTS.md doesn't reference .fragments/agent-context.md. Re-run init to add the pointer line, or add See: .fragments/agent-context.md by hand.

Exit code 12 — MCP entry. Your .mcp.json exists but the fragments server entry is missing, lacks an HTTPS URL, or has an invalid auth header. Re-run init to repair just the fragments entry — other servers stay untouched.

Exit code 13 — CI mirror. No workflow runs fragments check with the same preset as your local config. In a monorepo, ensure your root workflow passes --dir <your-project-path> or scans the whole repo.

Exit code 14 — Cloud sync. Cloud has a newer rules version, or your sync is older than the tolerance window (default 168h). Re-run init with your token to pull the latest team rules.

For machine-readable output, pass --json to status — the same checks come back as a structured object with the failing item identified by id.