ruff-sync 0.1.7.dev2__tar.gz → 0.1.8__tar.gz

{ruff_sync-0.1.7.dev2/.agents/skills/ruff-sync-usage → ruff_sync-0.1.8/.agents/skills/ruff-sync}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ruff-sync-usage
+name: ruff-sync
 description: >-
   Configure and operate ruff-sync to synchronize Ruff linter settings across Python projects.
   Use when the user wants to set up ruff-sync, sync Ruff config from an upstream source,

{ruff_sync-0.1.7.dev2 → ruff_sync-0.1.8}/AGENTS.md

@@ -38,13 +38,14 @@ Specific workflows, libraries, and tools are documented in `.agents/skills/`. Be
   decisions/           # Internal Architectural Decision Records (ADRs)
     README.md          # Index of all architectural decisions
   skills/
-    ruff-sync-usage/   # Agent Skill for users adopting ruff-sync (keep current!)
+    ruff-sync/         # Symlink to src/ruff_sync/.agents/skills/ruff-sync (for local workspace agent loading)
       SKILL.md
       references/
         configuration.md
         troubleshooting.md
         ci-integration.md
 src/ruff_sync/         # The application source
+  .agents/skills/ruff-sync/ # [NEW] Canonical physical skill source directory (packaged into wheels)
   __init__.py          # Public API
   __main__.py          # CLI entry point (`python -m ruff_sync`)
   cli.py               # CLI argparse definition and orchestration
@@ -218,7 +219,7 @@ CI is defined in `.github/workflows/ci.yaml`:
 1. **tomlkit proxy objects**: When adding new keys to a proxy table (from dotted keys), the proxy must be converted to a real table first. The `_recursive_update` function handles this. Don't bypass it.
 2. **`cast(Any, ...)` in tests**: Use `cast(Any, tomlkit.parse(...))["tool"]["ruff"]` pattern in tests to avoid mypy complaints about `tomlkit`'s `Item | Container` return types.
 3. **Pre-commit ruff version**: The ruff version in `.pre-commit-config.yaml` must stay in sync with the version in `pyproject.toml`. The test `test_pre_commit_versions_are_in_sync` enforces this.
-4. **Keep `ruff-sync-usage` current**: Update `.agents/skills/ruff-sync-usage/` after any CLI behavior changes (flags, config keys, exits) to ensure the documentation stays accurate. Keep details inside the skill directory.
+4. **Keep `ruff-sync` current**: Update `.agents/skills/ruff-sync/` (which is a symlink pointing to the physical files at `src/ruff_sync/.agents/skills/ruff-sync/`) after any CLI behavior changes (flags, config keys, exits) to ensure the documentation stays accurate. Keep details inside the skill directory.
 5. **No `autouse=True` fixtures**: NEVER use `autouse=True` for pytest fixtures. All fixtures must be explicitly requested by the test functions that require them. This ensures dependencies are explicit and avoids hidden side effects.
 
 ## Browser Tool Usage

{ruff_sync-0.1.7.dev2 → ruff_sync-0.1.8}/CONTRIBUTING.md

@@ -131,7 +131,7 @@ This creates three files in `tests/lifecycle_tomls/`: `<case>_initial.toml`, `<c
 1. Push your branch and open a PR against `main`.
 2. Fill in the PR description: what changed, why, and how to test it.
 3. Ensure all CI checks pass.
-4. If your change affects CLI behaviour (new flags, changed exit codes, new config keys, URL handling), **update the agent skill** at [`.agents/skills/ruff-sync-usage/`](.agents/skills/ruff-sync-usage/):
+4. If your change affects CLI behaviour (new flags, changed exit codes, new config keys, URL handling), **update the agent skill** at [`.agents/skills/ruff-sync/`](.agents/skills/ruff-sync/) (which is a symlink pointing to the physical files at `src/ruff_sync/.agents/skills/ruff-sync/`):
    - `SKILL.md` — quick start, workflows, exit codes, gotchas
    - `references/configuration.md` — config key reference
    - `references/troubleshooting.md` — error scenarios

{ruff_sync-0.1.7.dev2 → ruff_sync-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruff-sync
-Version: 0.1.7.dev2
+Version: 0.1.8
 Summary: Synchronize Ruff linter configuration across projects
 Project-URL: Homepage, https://github.com/Kilo59/ruff-sync
 Project-URL: Documentation, https://kilo59.github.io/ruff-sync/
@@ -353,7 +353,15 @@ $ ruff-sync check --semantic
 
 ## Agent Skill
 
-`ruff-sync` ships a bundled [Agent Skill](https://agentskills.io/home) at [`.agents/skills/ruff-sync-usage/`](.agents/skills/ruff-sync-usage/). AI coding agents that support the [Agent Skills format](https://agentskills.io/what-are-skills) (GitHub Copilot, Claude Code, Cursor, etc.) will automatically use it to guide you through setup, configuration, CI integration, and troubleshooting — without you needing to explain the tool each time.
+`ruff-sync` supports the [Library Skills](https://library-skills.io/) specification. AI coding agents that support the [Agent Skills format](https://agentskills.io/what-are-skills) (GitHub Copilot, Claude Code, Cursor, etc.) can automatically load this skill to guide you through setup, configuration, CI integration, and troubleshooting.
+
+You can install it automatically using `uvx` (or `npx` in a Node.js project):
+
+```console
+$ uvx library-skills
+```
+
+This will link the `ruff-sync` skill (bundled inside the installed package) into your project's `.agents/skills/ruff-sync` folder.
 
 See the **[Agent Skill guide](https://kilo59.github.io/ruff-sync/stable/agent-skill/)** for details.
 

{ruff_sync-0.1.7.dev2 → ruff_sync-0.1.8}/README.md

@@ -320,7 +320,15 @@ $ ruff-sync check --semantic
 
 ## Agent Skill
 
-`ruff-sync` ships a bundled [Agent Skill](https://agentskills.io/home) at [`.agents/skills/ruff-sync-usage/`](.agents/skills/ruff-sync-usage/). AI coding agents that support the [Agent Skills format](https://agentskills.io/what-are-skills) (GitHub Copilot, Claude Code, Cursor, etc.) will automatically use it to guide you through setup, configuration, CI integration, and troubleshooting — without you needing to explain the tool each time.
+`ruff-sync` supports the [Library Skills](https://library-skills.io/) specification. AI coding agents that support the [Agent Skills format](https://agentskills.io/what-are-skills) (GitHub Copilot, Claude Code, Cursor, etc.) can automatically load this skill to guide you through setup, configuration, CI integration, and troubleshooting.
+
+You can install it automatically using `uvx` (or `npx` in a Node.js project):
+
+```console
+$ uvx library-skills
+```
+
+This will link the `ruff-sync` skill (bundled inside the installed package) into your project's `.agents/skills/ruff-sync` folder.
 
 See the **[Agent Skill guide](https://kilo59.github.io/ruff-sync/stable/agent-skill/)** for details.
 

{ruff_sync-0.1.7.dev2 → ruff_sync-0.1.8}/docs/agent-skill.md

@@ -8,7 +8,7 @@ The [Agent Skills specification](https://agentskills.io/specification) is an ope
 
 ## What the ruff-sync Skill Covers
 
-The skill lives at [`.agents/skills/ruff-sync-usage/`](https://github.com/Kilo59/ruff-sync/tree/main/.agents/skills/ruff-sync-usage/) and teaches agents:
+The skill lives at [`.agents/skills/ruff-sync/`](https://github.com/Kilo59/ruff-sync/tree/main/src/ruff_sync/.agents/skills/ruff-sync/) and teaches agents:
 
 | File | Contents |
 |---|---|
@@ -21,15 +21,19 @@ The skill uses [progressive disclosure](https://agentskills.io/specification#pro
 
 ## Using the Skill in Your Project
 
-The skill is bundled in the `ruff-sync` repository itself. If you install `ruff-sync` from source or clone the repo, the skill is already present.
-
-For agents that scan a configurable skill directory (e.g. `.agents/skills/`), copy the skill folder into your own project:
+`ruff-sync` supports the [Library Skills](https://library-skills.io/) specification. You can automatically install the agent skill using `uvx` (or `npx` if in a Node.js project):
 
 ```bash
-cp -r path/to/ruff-sync/.agents/skills/ruff-sync-usage .agents/skills/
+uvx library-skills
 ```
 
-Or reference the upstream directly if your agent supports remote skills.
+This scans your environment, detects `ruff-sync` from your project's dependencies, and sets up a symlink at `.agents/skills/ruff-sync` pointing to the skill files bundled inside the installed package.
+
+For Claude Code (which uses `.claude/skills` instead of `.agents/skills`), you can specify the targets or run:
+
+```bash
+uvx library-skills --claude
+```
 
 ## Activation
 

{ruff_sync-0.1.7.dev2 → ruff_sync-0.1.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ruff-sync"
-version = "0.1.7.dev2"
+version = "0.1.8"
 description = "Synchronize Ruff linter configuration across projects"
 keywords = ["ruff", "linter", "config", "synchronize", "python", "linting", "automation", "tomlkit", "pre-commit"]
 authors = [
@@ -79,6 +79,9 @@ default-groups = ["dev"]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.build.targets.sdist.force-include]
+"src/ruff_sync/.agents" = "src/ruff_sync/.agents"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/ruff_sync"]
 

ruff_sync-0.1.8/src/ruff_sync/.agents/skills/ruff-sync/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: ruff-sync
+description: >-
+  Configure and operate ruff-sync to synchronize Ruff linter settings across Python projects.
+  Use when the user wants to set up ruff-sync, sync Ruff config from an upstream source,
+  check for configuration drift, integrate ruff-sync into CI, troubleshoot sync issues,
+  or keep Ruff rules consistent across multiple repositories.
+---
+
+# ruff-sync Usage
+
+`ruff-sync` pulls a canonical Ruff configuration from an upstream URL and merges it into your local project, preserving comments, whitespace, and per-project overrides.
+
+## Quick Start
+
+```bash
+# 1. Install
+uv tool install ruff-sync
+
+# 2. Sync from an upstream repo (extracts [tool.ruff] / ruff.toml automatically)
+ruff-sync https://github.com/my-org/standards
+
+# 3. Review the changes before committing
+git diff pyproject.toml
+```
+
+## Persist Configuration
+
+Add to `pyproject.toml` so you don't need to pass CLI args every time:
+
+```toml
+[tool.ruff-sync]
+upstream = "https://github.com/my-org/standards"
+exclude = [
+    "target-version",            # each project uses its own Python version
+    "lint.per-file-ignores",     # project-specific suppressions
+    "lint.ignore",
+    "lint.isort.known-first-party",
+]
+```
+
+Then just run `ruff-sync` (no arguments needed).
+
+See [references/configuration.md](references/configuration.md) for all config keys and defaults.
+
+## Common Workflows
+
+### Initial Project Setup
+
+```
+Setup Progress:
+- [ ] 1. Install ruff-sync (uv tool install ruff-sync)
+- [ ] 2. Check for `.pre-commit-config.yaml` — if present, ensure the `ruff` hook is used
+- [ ] 3. Add `[tool.ruff-sync]` to `pyproject.toml` with upstream URL and exclusions
+- [ ] 4. If `.pre-commit-config.yaml` exists, set `pre-commit-version-sync = true` in `[tool.ruff-sync]`
+- [ ] 5. Run `ruff-sync` to pull the upstream config
+- [ ] 6. Review `git diff`
+- [ ] 7. Fix any new lint errors: `uv run ruff check . --fix`
+- [ ] 8. Commit
+```
+
+### Upstream Layers (multi-source)
+
+Stack multiple upstream sources — later entries win on conflict:
+
+```toml
+[tool.ruff-sync]
+upstream = [
+    "https://github.com/my-org/python-standards",   # base company rules
+    "https://github.com/my-org/ml-team-tweaks",     # team-specific overrides
+]
+```
+
+### CI Drift Check
+
+```
+CI Setup Progress:
+- [ ] 1. Add ruff-sync check step to CI workflow (see references/ci-integration.md)
+- [ ] 2. Decide: --semantic for value-only checks, or full string comparison
+- [ ] 3. Set output format: --output-format github for PR annotations
+- [ ] 4. Set exit-code expectations (0 = in sync, 1 = config drift, 2 = pre-commit only)
+- [ ] 5. Verify locally: `ruff-sync check --semantic`
+```
+
+Keep the `ruff-pre-commit` hook version in `.pre-commit-config.yaml` aligned with the project's Ruff version.
+
+**Recommendation:** Always prefer the persistent TOML configuration over the ephemeral `--pre-commit` CLI flag.
+
+```toml
+[tool.ruff-sync]
+pre-commit-version-sync = true
+```
+
+Then run `ruff-sync` — it updates the hook rev automatically. Exit code 2 means only the hook version is out of sync (Ruff config itself is fine).
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | In sync — no action needed |
+| `1` | Ruff config is out of sync with upstream |
+| `2` | Config is in sync, but pre-commit hook version is stale (only when `--pre-commit` is active) |
+
+## URL Formats Supported
+
+All of these work as the `upstream` value:
+
+```bash
+ruff-sync https://github.com/my-org/standards              # repo root
+ruff-sync https://github.com/my-org/standards/tree/main/cfg  # subdirectory
+ruff-sync https://github.com/my-org/standards/blob/main/ruff.toml  # specific file
+ruff-sync https://raw.githubusercontent.com/my-org/standards/main/pyproject.toml
+ruff-sync git@github.com:my-org/standards.git             # SSH (shallow clone)
+```
+
+## CLI Reference (Short)
+
+| Flag | Meaning |
+|------|---------|
+| `--validate`      | Validate merged config with Ruff before writing; aborts if Ruff rejects it |
+| `--strict`        | Like `--validate` but also treats warnings (version mismatch, deprecated rules) as failures. Implies `--validate` |
+| `--output-format` | `text` (default), `json`, `github`, `gitlab`, `sarif` (auto-detected in CI) |
+| `--semantic`      | Ignore whitespace/comments in `check` |
+| `--pre-commit`    | Sync `.pre-commit-config.yaml` hook version |
+| `--save`          | Persist CLI args to `pyproject.toml` |
+
+## Gotchas
+
+- **`exclude` uses dotted paths, not TOML paths.** `lint.per-file-ignores` refers to the `per-file-ignores` key inside `[tool.ruff.lint]`. Do NOT write `tool.ruff.lint.per-file-ignores`.
+- **`--validate` is opt-in.** Validation is off by default. Pass `--validate` (or `--strict`) to run the merged config through Ruff before writing. The sync is aborted if Ruff rejects the config, leaving the local file untouched. This includes a **Python version consistency check** that compares upstream `target-version` against local `requires-python`.
+- **Excluding `target-version` skips consistency validation.** If `target-version` (or `tool.ruff.target-version`) is in the `exclude` list, `ruff-sync` will skip the version consistency check and log a warning. This is useful for projects that intentionally deviate from upstream Python versions.
+- **`--strict` implies `--validate`.** If you want warnings (like version mismatches or deprecated rules) treated as failures, only `--strict` is needed — don't pass both.
+- **Validation soft-fails if `ruff` is not on PATH.** If the `ruff` binary can't be found, a warning is logged and the sync continues normally.
+- **Use `--init` only for new projects.** `ruff-sync` requires an existing `pyproject.toml` or `ruff.toml`. Pass `--init` to scaffold one if the directory is empty. This will automatically generate a `[tool.ruff-sync]` configuration block for future syncs.
+- **Use `--save` to persist CLI arguments.** If you want to update an existing `pyproject.toml` with a new upstream URL or exclusion, pass `--save` to write the new configuration to the file.
+- **`--semantic` ignores comments and whitespace.** Use it in CI to avoid false positives from cosmetic local edits. Omit it for strict byte-for-byte checks.
+- **SSH URLs trigger a shallow clone.** `git@github.com:...` URLs use `git clone --filter=blob:none --depth=1` — no `git` credential issues as long as SSH auth is configured.
+- **Later upstreams win in `upstream` lists.** In a multi-source list, keys set by entry 2 overwrite keys from entry 1.
+- **Config discovery order matters.** When targeting a directory, `ruff-sync` looks for `ruff.toml` -> `.ruff.toml` -> `pyproject.toml` in that order.
+- **Pre-commit exit code 2 is intentional.** A `2` exit from `ruff-sync check` means the Ruff _config_ is fine, only the pre-commit hook tag is stale. You may want to treat this differently from a full config drift (exit 1) in CI.
+- **Prefer TOML for pre-commit sync.** While `--pre-commit` works on the CLI, setting `pre-commit-version-sync = true` in `pyproject.toml` is the recommended way to ensure hook versioning stays consistent for all contributors.
+
+## References
+
+- **[Configuration reference](references/configuration.md)** — All `[tool.ruff-sync]` keys, types, and defaults
+- **[Troubleshooting](references/troubleshooting.md)** — Common errors and how to resolve them
+- **[CI integration recipes](references/ci-integration.md)** — GitHub Actions, GitLab CI, pre-commit hook

ruff_sync-0.1.8/src/ruff_sync/.agents/skills/ruff-sync/references/ci-integration.md

@@ -0,0 +1,233 @@
+# CI Integration Recipes
+
+## GitHub Actions
+
+### Basic Drift Check
+
+Add this step to any existing workflow (e.g., `.github/workflows/ci.yaml`):
+
+```yaml
+- name: Check Ruff config is in sync
+  run: ruff-sync check --semantic --output-format github
+```
+
+`--semantic` ignores cosmetic differences (comments, whitespace) — only real value or rule changes cause failure.
+`--output-format github` creates inline PR annotations and a structured Job Summary report.
+
+### With Strict Validation
+
+To also catch deprecated rules and Python version mismatches in CI:
+
+```yaml
+- name: Check Ruff config (with validation)
+  run: ruff-sync check --semantic --strict --output-format github
+```
+
+`--strict` implies `--validate`. Deprecated rules and version mismatches are upgraded to failures.
+
+> [!TIP]
+> `ruff-sync` automatically groups multiple drifts in the same file into a single annotation to reduce PR noise.
+
+### Full Workflow Example
+
+Uses [`astral-sh/setup-uv`](https://github.com/astral-sh/setup-uv) — the official action that installs uv, adds it to PATH, and handles caching. No separate `setup-python` step needed.
+
+```yaml
+name: Ruff sync check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ruff-sync-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.10.x"   # pin to a minor range; Dependabot can keep this current
+
+      - name: Install ruff-sync
+        run: uv tool install ruff-sync
+
+      - name: Check Ruff config is in sync with upstream
+        run: ruff-sync check --semantic --output-format github
+```
+
+### With Pre-commit Sync Check
+
+To also verify the pre-commit hook version, add the `--pre-commit` flag:
+
+```yaml
+- name: Check Ruff config and pre-commit hook
+  run: ruff-sync check --semantic --pre-commit --output-format github
+```
+
+(Note: For better consistency, you can instead set `pre-commit-version-sync = true` in your `pyproject.toml` — then `ruff-sync check --semantic` will automatically include this check.)
+
+### SARIF Upload (GitHub Advanced Security)
+
+For repositories with GitHub Advanced Security enabled, upload SARIF results to track drift findings in the **Security tab** and get per-key inline PR annotations that persist across runs:
+
+```yaml
+- name: Check Ruff config (SARIF)
+  run: ruff-sync check --output-format sarif > ruff-sync.sarif || true
+
+- name: Upload SARIF results
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: ruff-sync.sarif
+    category: ruff-sync
+```
+
+The `|| true` ensures the upload step always runs even when `ruff-sync` exits 1 (drift detected). Without it, GitHub Actions would skip the upload step on failure.
+
+> **Why SARIF over `--output-format github`?**
+>
+> | Feature | `github` | `sarif` |
+> |---------|----------|---------|
+> | **PR Feedback** | Inline annotations (grouped) | Inline annotations (per-key) |
+> | **Job Summary** | ✅ Markdown table | ❌ (requires separate parsing) |
+> | **Persistence** | Ephemeral (until re-run) | Persistent (Security tab) |
+> | **Tracking** | Manual | Automated "introduced/resolved" |
+
+---
+
+## GitLab CI
+
+Use the official [`ghcr.io/astral-sh/uv`](https://docs.astral.sh/uv/guides/integration/gitlab/) image — uv is already on the `PATH`, no install step needed.
+
+```yaml
+variables:
+  UV_VERSION: "0.10"
+  PYTHON_VERSION: "3.12"
+  BASE_LAYER: alpine
+  UV_LINK_MODE: copy   # required: GitLab mounts build dir separately
+
+ruff-sync-check:
+  stage: lint
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
+  script:
+    - uvx ruff-sync check --semantic --output-format gitlab > gl-code-quality-report.json
+  artifacts:
+    when: always
+    reports:
+      codequality: gl-code-quality-report.json
+    paths:
+      - gl-code-quality-report.json
+    expire_in: 1 week
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+```
+
+### GitLab SAST Report / SARIF (Ultimate tier)
+
+Use `--output-format sarif` to feed the GitLab [Security & Compliance dashboard](https://docs.gitlab.com/user/application_security/) via the `sast` artifact report type:
+
+```yaml
+variables:
+  UV_VERSION: "0.10"
+  PYTHON_VERSION: "3.12"
+  BASE_LAYER: alpine
+  UV_LINK_MODE: copy   # required: GitLab mounts build dir separately
+
+ruff-sync-sarif:
+  stage: lint
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python$PYTHON_VERSION-$BASE_LAYER
+  script:
+    - uvx ruff-sync check --output-format sarif > ruff-sync.sarif
+  artifacts:
+    when: always          # Upload even when ruff-sync exits 1 (drift detected)
+    reports:
+      sast: ruff-sync.sarif
+    paths:
+      - ruff-sync.sarif
+    expire_in: 1 week
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+```
+
+> **Why SARIF over `--output-format gitlab` (codequality)?**
+>
+> | Concern | `codequality` | `sarif` |
+> |---------|--------------|--------|
+> | GitLab tier | Free (MR widget), Ultimate (inline diff) | Ultimate (Security dashboard) |
+> | GitHub support | ❌ | ✅ via `upload-sarif` |
+> | Per-key findings | ❌ one issue per file | ✅ one finding per drifted TOML key |
+> | Finding persistence | MR widget only | Security tab, tracked across branches |
+> | Portability | GitLab only | GitHub, GitLab, SonarQube, IDE extensions |
+>
+> **Rule of thumb**: use `codequality` for lightweight GitLab-native linting feedback; use `sarif` when you need cross-platform compatibility or want findings tracked in a security/code-scanning dashboard.
+
+---
+
+## Pre-commit Hook
+
+Run `ruff-sync check` as a pre-commit hook to catch drift before every commit:
+
+```yaml
+# .pre-commit-config.yaml
+- repo: https://github.com/Kilo59/ruff-sync
+  rev: v0.1.6   # pin to a release tag
+  hooks:
+    - id: ruff-sync-check
+```
+
+The hook runs `ruff-sync check --semantic` automatically. Update `rev` to the latest ruff-sync version.
+
+---
+
+## Makefile
+
+```makefile
+.PHONY: sync-check sync
+
+sync-check:
+	ruff-sync check --semantic
+
+sync:
+	ruff-sync
+	git diff pyproject.toml
+```
+
+---
+
+## Deciding: `--semantic` vs. Full String Check
+
+| Mode | Fails on | Use when |
+|------|---------|---------|
+| `ruff-sync check --semantic` | Value/rule differences only | CI — avoids false positives from local comment edits |
+| `ruff-sync check` | Any string difference (comments, whitespace, values) | Enforcing exact config file consistency |
+
+Recommendation: **use `--semantic` in CI** and save the full-string check for auditing purposes.
+
+---
+
+## Dogfooding (Self-Check)
+
+If `ruff-sync` is configured in the project's own `pyproject.toml` (the standard case), just run:
+
+```bash
+ruff-sync check
+```
+
+No URL argument needed — it reads `upstream` from `[tool.ruff-sync]`.
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|----------|
+| **0** | In sync — no drift detected |
+| **1** | Config drift (`check`), validation failure (`pull --validate`), or sync error |
+| **2** | CLI usage error — invalid arguments (reserved by argparse) |
+| **3** | Pre-commit hook drift — use `--pre-commit` flag to enable this check |
+| **4** | Upstream unreachable — HTTP error or network failure |
+
+All non-zero codes cause a CI step to fail, which is the desired behaviour. To diagnose which failure occurred, check the exit code with `echo $?` after the `ruff-sync check` call.