# 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 skills `dif init` installs (dif-author-experiment, dif-conclude-experiment, dif-generate-surfaces), 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.
- [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.
- [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.