opsmill · yjouffrault · May 27, 2026
diff --git a/.vale/styles/spelling-exceptions.txt b/.vale/styles/spelling-exceptions.txt
@@ -88,6 +88,7 @@ modularization
 namespace
 namespaces
 Nautobot
+Nautobot's
 Netbox
 Newsfragment
 Nornir
@@ -131,6 +132,15 @@ uv
 validator
 validators
 Version Control
+VRFs
+walkthrough
+runbook
+runbooks
+Splunk
+Datadog
+Infoblox
+PeeringDB
+Device42
 Vitest
 VLANs
 vscode

diff --git a/README.md b/README.md
@@ -45,7 +45,7 @@ pip install infrahub-sync
 infrahub-sync --help
 ```
 
-→ For step-by-step setup, see [Installing Infrahub Sync](https://docs.infrahub.app/sync/guides/installation), [Creating a new sync instance](https://docs.infrahub.app/sync/guides/creation), and [Running sync tasks](https://docs.infrahub.app/sync/guides/run).
+→ For step-by-step setup, see [Install Infrahub Sync](https://docs.infrahub.app/sync/installation), [Create a sync project](https://docs.infrahub.app/sync/creating-a-sync-project), and [Run a sync](https://docs.infrahub.app/sync/running-a-sync).
 
 ---
 
@@ -63,7 +63,7 @@ infrahub-sync sync --name from-netbox --directory ./examples
 
 After the sync completes, every NetBox device, interface, VLAN, prefix, and related model appears in Infrahub, mapped per the schema mapping in `config.yml`.
 
-→ For the full walkthrough of what happens under the hood — adapter generation, diff calculation, and sync ordering — see [Running sync tasks](https://docs.infrahub.app/sync/guides/run).
+→ For the full walkthrough of what happens under the hood — adapter generation, diff calculation, and sync ordering — see [Run a sync](https://docs.infrahub.app/sync/running-a-sync).
 
 ---
 
@@ -113,21 +113,21 @@ After the sync completes, every NetBox device, interface, VLAN, prefix, and rela
 
 | | |
 |---|---|
-| **Install and run** | [Installing Infrahub Sync](https://docs.infrahub.app/sync/guides/installation) · [Creating a sync instance](https://docs.infrahub.app/sync/guides/creation) · [Running sync tasks](https://docs.infrahub.app/sync/guides/run) |
+| **Install and run** | [Install Infrahub Sync](https://docs.infrahub.app/sync/installation) · [Create a sync project](https://docs.infrahub.app/sync/creating-a-sync-project) · [Run a sync](https://docs.infrahub.app/sync/running-a-sync) |
 | **Full documentation** | [Infrahub Sync docs](https://docs.infrahub.app/sync) |
 | **All adapters** | [Adapter reference](https://docs.infrahub.app/sync#adapters) |
 | **Configuration reference** | [Sync instance configuration](https://docs.infrahub.app/sync/reference/config) · [CLI reference](https://docs.infrahub.app/sync/reference/cli) |
-| **Custom CA certificates** | [Custom certificates guide](https://docs.infrahub.app/sync/guides/custom-certificates) |
+| **Custom CA certificates** | [Custom certificates guide](https://docs.infrahub.app/sync/custom-certificates) |
 | **Local custom adapters** | [Local adapters guide](https://docs.infrahub.app/sync/adapters/local-adapters) |
-| **Contribute** | [Development guide](https://docs.infrahub.app/sync/development) — development environment, tests, releases |
+| **Contribute** | [Contributing guide](https://docs.infrahub.app/sync/contributing) — development environment, tests, code standards |
 
 ---
 
 ## Questions or Contributing?
 
 - **Report a bug or request a feature** — [GitHub Issues](https://github.com/opsmill/infrahub-sync/issues)
 - **Discuss with the community** — [discord.gg/opsmill](https://discord.gg/opsmill)
-- **Contribute code or docs** — see the [Development guide](https://docs.infrahub.app/sync/development)
+- **Contribute code or docs** — see the [Contributing guide](https://docs.infrahub.app/sync/contributing)
 
 ---
 

diff --git a/docs/docs/development.mdx → RELEASING.md b/docs/docs/development.mdx → RELEASING.md
@@ -1,176 +1,28 @@
----
-title: Development
----
+# Releasing Infrahub Sync
 
-This guide covers how to set up a development environment for `infrahub-sync`, contribute to the project, and publish releases.
+Maintainer-only runbook for publishing new releases of `infrahub-sync` to [PyPI](https://pypi.org/project/infrahub-sync/).
 
-## Prerequisites
-
-- Python 3.10–3.13 (3.12 recommended)
-- [uv](https://docs.astral.sh/uv/) for dependency management
-- Git
-
-## Setting up your development environment
-
-### Clone the repository
-
-```bash
-git clone https://github.com/opsmill/infrahub-sync.git
-cd infrahub-sync
-```
-
-### Install uv
-
-If you don't have uv installed, you can install it with:
-
-```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
-```
-
-Or see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for other options.
-
-### Install dependencies
-
-```bash
-uv sync --group dev
-```
-
-This installs all runtime and development dependencies defined in `pyproject.toml`.
-
-### Verify your setup
-
-```bash
-uv run infrahub-sync --help
-uv run infrahub-sync list --directory examples/
-```
-
-## Development workflow
-
-Before committing any changes, run the following commands in order:
-
-```bash
-uv run invoke format    # Format code with ruff
-uv run invoke lint      # Lint code with ruff and pylint
-uv run mypy infrahub_sync/ --ignore-missing-imports
-```
-
-### Validate the CLI
-
-After making changes, verify the CLI still works:
-
-```bash
-uv run infrahub-sync --help
-uv run infrahub-sync list --directory examples/
-uv run infrahub-sync generate --name from-netbox --directory examples/
-```
-
-### Running tests
-
-```bash
-uv run pytest -q
-```
-
-## Code standards
-
-### Python style
-
-- Python 3.10–3.13 compatible
-- Type hints on new or changed code
-- Ruff-formatted and lint-clean
-- Mypy-checked (do not increase existing error count)
-- Public functions and classes require documentation strings
-- Raise specific exceptions; avoid broad `except Exception:`
-
-### Line length
-
-- Maximum line length: 120 characters (configured in `pyproject.toml`)
-
-## Documentation
-
-If you make user-facing changes (CLI flags, configuration options, new adapters), update the documentation.
-
-### Generate command-line documentation
-
-```bash
-uv run invoke docs.generate
-```
-
-### Build documentation site
-
-First-time setup (requires Node.js):
-
-```bash
-cd docs && npm install
-```
-
-Build the site:
-
-```bash
-uv run invoke docs.docusaurus
-```
-
-### Lint markdown files
-
-```bash
-npx markdownlint-cli "docs/docs/**/*.{md,mdx}"
-npx markdownlint-cli --fix "docs/docs/**/*.{md,mdx}"
-```
-
-## Adding a new adapter
-
-1. Create `infrahub_sync/adapters/<name>.py` following existing adapter patterns
-2. Add connection configuration schema and an example under `examples/`
-3. Provide `list` and `diff` pathways before enabling `sync`
-4. Document required environment variables and expected error cases
-5. Create a documentation page in `docs/docs/adapters/`
-6. Add the adapter to the sidebar in `docs/sidebars.ts`
-
-## Invoke tasks
-
-View all available tasks:
-
-```bash
-uv run invoke --list
-```
-
-Common tasks:
-
-| Task | Description |
-|------|-------------|
-| `linter.format-ruff` | Format Python code with ruff |
-| `linter.lint-ruff` | Lint Python code with ruff |
-| `linter.lint-pylint` | Lint Python code with pylint |
-| `linter.lint-yaml` | Lint YAML files with yamllint |
-| `docs.generate` | Generate CLI documentation |
-| `docs.docusaurus` | Build documentation website |
-| `format` | Alias for ruff format |
-| `lint` | Run all linters |
-
-## Publishing a release
-
-This section documents how to publish new releases of `infrahub-sync` to PyPI.
-
-### Overview
+## Overview
 
 The project uses an automated release system powered by GitHub Actions. There are three ways to publish a release:
 
 1. **Automated release** (recommended for regular releases)
 2. **Manual GitHub release** (for controlled releases)
 3. **Manual workflow dispatch** (for emergency or custom releases)
 
-### Prerequisites
+## Prerequisites
 
 Before publishing, ensure:
 
 - You have write access to the repository
 - The `PYPI_TOKEN` secret is configured in repository settings
 - The `GH_INFRAHUB_BOT_TOKEN` secret is configured (for automated releases)
 
-### Method 1: Automated release (recommended)
+## Method 1: Automated release (recommended)
 
 This is the standard release flow. Releases are triggered automatically when PRs are merged to `main` or `stable` branches.
 
-#### Step 1: Label your pull requests
+### Step 1: Label your pull requests
 
 Apply appropriate labels to PRs before merging. Labels determine the version bump:
 
@@ -189,7 +41,7 @@ Auto-labeling rules are configured in `.github/release-drafter.yml` but require
 | Contains `chore` | `ci/skip-changelog` |
 | Contains `deprecat` | `type/deprecated` |
 
-#### Step 2: Merge to main
+### Step 2: Merge to main
 
 Merge your labeled PR to the `main` branch. The automation will:
 
@@ -198,7 +50,7 @@ Merge your labeled PR to the `main` branch. The automation will:
 3. Commit changes as `chore(release): v{VERSION} [skip ci]`
 4. Create/update a draft GitHub Release with auto-generated release notes
 
-#### Step 3: Publish the GitHub release
+### Step 3: Publish the GitHub release
 
 1. Navigate to the repository's **Releases** page
 2. Find the draft release created by Release Drafter
@@ -208,11 +60,11 @@ Merge your labeled PR to the `main` branch. The automation will:
 
 Publishing the release triggers the PyPI upload automatically.
 
-### Method 2: Manual GitHub release
+## Method 2: Manual GitHub release
 
 Use this method when you want full control over the release timing and notes.
 
-#### Step 1: Update the version
+### Step 1: Update the version
 
 Update the version in `pyproject.toml`:
 
@@ -229,7 +81,7 @@ git commit -m "chore(release): vX.Y.Z"
 git push origin main
 ```
 
-#### Step 2: Create a GitHub release
+### Step 2: Create a GitHub release
 
 1. Go to **Releases** → **Draft a new release**
 2. Click **Choose a tag** and create a new tag matching your version (for example, `1.6.0`)
@@ -240,11 +92,11 @@ git push origin main
 
 This triggers the `trigger-release.yml` workflow, which publishes to PyPI.
 
-### Method 3: Manual workflow dispatch
+## Method 3: Manual workflow dispatch
 
 Use this for emergency releases or when you need to bypass the standard flow.
 
-#### Using the GitHub UI
+### Using the GitHub UI
 
 1. Go to **Actions** → **Publish Infrahub Sync Package**
 2. Click **Run workflow**
@@ -254,7 +106,7 @@ Use this for emergency releases or when you need to bypass the standard flow.
    - `runs-on`: OS for the runner (default: `ubuntu-22.04`)
 4. Click **Run workflow**
 
-#### Using the GitHub CLI
+### Using the GitHub CLI
 
 ```bash
 gh workflow run workflow-publish.yml \
@@ -264,7 +116,7 @@ gh workflow run workflow-publish.yml \
 
 **Important:** When using workflow dispatch, ensure `pyproject.toml` already has the correct version, as this method builds from the current code state.
 
-### Release notes
+## Release notes
 
 Release notes are auto-generated based on merged PRs and their labels:
 
@@ -280,7 +132,7 @@ PRs with these labels are excluded from release notes:
 - `ci/skip-changelog`
 - `type/duplicate`
 
-### Verifying a release
+## Verifying a release
 
 After publishing:
 
@@ -293,17 +145,17 @@ pip install infrahub-sync==<new-version>
 infrahub-sync --version
 ```
 
-### Troubleshooting
+## Troubleshooting
 
-#### Release workflow skipped
+### Release workflow skipped
 
 The automated release is skipped when:
 
 - The commit author is `opsmill-bot` with a `chore` prefix (prevents recursive releases)
 - No version bump is detected (no labeled PRs since last release)
 - Changes are only in the `docs/` directory
 
-#### The PyPI upload failed
+### The PyPI upload failed
 
 Common causes:
 
@@ -313,11 +165,11 @@ Common causes:
 
 To retry, use the manual workflow dispatch method.
 
-#### Version not bumped correctly
+### Version not bumped correctly
 
 Ensure PRs have appropriate labels before merging. If labels are missing, the version drafter may not calculate a new version.
 
-### Workflow files reference
+## Workflow files reference
 
 | Workflow | Type | Purpose |
 |----------|------|---------|