llms.txt
# dif.sh
> Flags and experiments as one `.md` file per feature flag or A/B test, checked into the repo with the code. `dif validate`/`dif build` compile them to a typed client; the JS SDK reads it at runtime.
## Docs
- [introduction, install, quickstart, workspace layout](https://dif.sh/docs.md): Getting started with dif.sh — install, first project, workspace layout.
- [the .md format](https://dif.sh/docs/format.md): The dif.sh experiment file format. Frontmatter schema, surfaces, audience predicates, exclusion groups.
- [CLI](https://dif.sh/docs/cli.md): The dif.sh CLI commands: init, connect, new, validate, build, qa, conclude, scaffold-audiences. Flags, exit codes, examples.
- [agent skills](https://dif.sh/docs/skills.md): The four skills `dif init` installs (dif-author-experiment, dif-conclude-experiment, dif-generate-surfaces, dif-triage-experiments), plus the guidance it writes to CLAUDE.md, AGENTS.md, .cursor/rules/dif.mdc, and .github/copilot-instructions.md. Install the skills into any agent with `npx skills add dif-sh/dif`.
- [@dif.sh/sdk](https://dif.sh/docs/sdk.md): The dif.sh JavaScript SDK. dif.init(), the dif() call, sinks, exposure events, server assignment, the React and Svelte adapters, and the Cloud-side dif.track() + publishable keys.
- [@dif.sh/flags-sdk](https://dif.sh/docs/flags-sdk.md): The Vercel Flags SDK adapter for dif. difAdapter.variant() and isEnabled(), identify and the dif_uid cookie, preview overrides, exposures, and the Flags Explorer endpoint.
- [events](https://dif.sh/docs/events.md): The two events delivery modes, cloud and custom, and how dif/config.yaml's events: block picks one.
- [MCP and API](https://dif.sh/docs/mcp.md): Read-only dif.sh Cloud experiment verdicts for agents and scripts. Create a dif_pat_ read token, connect an MCP client to https://cloud.dif.sh/mcp (tools: list_projects, get_overview, get_experiment_results, get_learnings), or call the REST API under https://cloud.dif.sh/v1/. Includes the verdict rules.
- [dif/config.yaml](https://dif.sh/docs/config.md): The dif/config.yaml schema: project, default surface, audience attribute schema, bucketing, exposure, and build.
- [troubleshooting](https://dif.sh/docs/troubleshooting.md): Diagnostic codes from dif validate and an FAQ.
## Content negotiation
Send `Accept: text/markdown` to any `/docs/…` URL to receive the markdown version at the same URL. Or fetch the `.md` twin directly at the URL above.
## Catalog
- [ARD manifest](https://dif.sh/.well-known/ai-catalog.json): agent-facing resources index for the origin (ARD spec).
- [API catalog](https://dif.sh/.well-known/api-catalog): RFC 9727 linkset of service documentation and describedby resources.
- [Agent skills](https://dif.sh/.well-known/agent-skills/index.json): agentskills.io v0.2 discovery document.
