feat: add custom Go linter with no-double-dash rule (#7)

ben-miru · claude · web-flow · commit ab0cf7a52c28 · 2026-03-23T14:35:22.000-07:00
## Summary - Add `tools/lint`, a Go-based MDX prose linter with a `no-double-dash` rule that flags `--` in prose (suggesting em dash replacement) - Scanner skips frontmatter, fenced code blocks, inline code, HTML comments, JSX tags, thematic breaks, table separators, and import/export lines - Integrate into `scripts/lint.sh` and CI workflow (`setup-go` step) - Fix 32 existing `--` occurrences across 18 MDX files with proper em dashes 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -11,6 +11,11 @@ jobs:
       - name: Check out repository
         uses: actions/checkout@v5
 
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: tools/lint/go.mod
+
       - name: Set up pnpm
         uses: pnpm/action-setup@v4
         with:
diff --git a/.gitignore b/.gitignore
@@ -13,4 +13,7 @@ images/
 videos/
 changelog/
 
-node_modules/
+node_modules/
+
+# lint compiled binary
+tools/lint/lint
diff --git a/docs/admin/users/overview.mdx b/docs/admin/users/overview.mdx
@@ -79,6 +79,6 @@ As such, there are three possible statuses for a user:
 | `suspended` | User's access was revoked by an admin          |
 | `left`      | User has left the workspace                    |
 
-Only `active` users can log in and access workspace resources. `suspended` and `left` users exist solely for auditing purposes--they cannot log in to the workspace or access any resources.
+Only `active` users can log in and access workspace resources. `suspended` and `left` users exist solely for auditing purposes—they cannot log in to the workspace or access any resources.
 
 Users who have been suspended or left can be reinvited to the workspace at any time by an admin via [invites](/docs/admin/users/invites#send-an-invite).
diff --git a/docs/changelogs/agent.mdx b/docs/changelogs/agent.mdx
@@ -18,7 +18,7 @@ description: "Changelog and migration steps for the Miru Agent"
 
 ## Features
 
-- Deployments are guaranteed to be atomic--all config instances for a deployment are written to the filesystem simultaneously or none of them are
+- Deployments are guaranteed to be atomic—all config instances for a deployment are written to the filesystem simultaneously or none of them are
 - The agent now explicitly tracks `deployed_at` and `archived_at` timestamps on device when deployments are applied
 - Config instances deployed to the device's file system are now identical (indents, spacing, etc.) to config instances edited in the config editor
 
diff --git a/docs/developers/agent/architecture.mdx b/docs/developers/agent/architecture.mdx
@@ -33,7 +33,7 @@ The agent maintains a persistent connection to an MQTT broker over TLS. The cont
 
 ## Sync cycle
 
-At its core, the agent is built around a **sync** cycle--the process of reconciling the device's local state with the control plane's state.
+At its core, the agent is built around a **sync** cycle—the process of reconciling the device's local state with the control plane's state.
 
 When the agent performs a sync cycle, it communicates directly with the Miru control plane over HTTPS. MQTT is not used at all in this process.
 
diff --git a/docs/developers/agent/commands.mdx b/docs/developers/agent/commands.mdx
@@ -124,7 +124,7 @@ systemctl restart miru
 
 ### Stop
 
-`stop` stops the agent while leaving its state intact. Stopping the agent does not [disable](/docs/developers/agent/commands#disable) the agent--it will still automatically start on next system boot.
+`stop` stops the agent while leaving its state intact. Stopping the agent does not [disable](/docs/developers/agent/commands#disable) the agent—it will still automatically start on next system boot.
 
 Note that stopping the agent will prevent any new deployments from reaching the device until the agent is started again.
 
@@ -153,7 +153,7 @@ systemctl start miru
 
 Disabling the agent prevents it from starting automatically on boot. 
 
-This does not immediately [stop](/docs/developers/agent/commands#stop) the agent--it will still run if it is currently running. However, it will not be able to start on next system boot.
+This does not immediately [stop](/docs/developers/agent/commands#stop) the agent—it will still run if it is currently running. However, it will not be able to start on next system boot.
 
 ```bash
 systemctl disable miru
@@ -163,7 +163,7 @@ systemctl disable miru
 
 Enabling the agent allows it to start automatically on boot. This is the default behavior after installation and only needs to be done if the agent has been [disabled](/docs/developers/agent/commands#disable).
 
-Enabling the agent will not immediately start it--it will still need to be [started](/docs/developers/agent/commands#start) manually.
+Enabling the agent will not immediately start it—it will still need to be [started](/docs/developers/agent/commands#start) manually.
 
 ```bash
 systemctl enable miru
diff --git a/docs/developers/agent/security.mdx b/docs/developers/agent/security.mdx
@@ -143,7 +143,7 @@ The only local interface is a Unix domain socket at `/run/miru/miru.sock`, used
 
 ## Local API access control
 
-The agent's local REST API is exposed through a Unix domain socket, not a TCP port. It is not possible to access the agent's local API over a network--it is only accessible from processes running on the same device as the agent.
+The agent's local REST API is exposed through a Unix domain socket, not a TCP port. It is not possible to access the agent's local API over a network—it is only accessible from processes running on the same device as the agent.
 
 Access is controlled through filesystem permissions:
 
diff --git a/docs/developers/agent/versions.mdx b/docs/developers/agent/versions.mdx
@@ -8,7 +8,7 @@ import { CardNewTab } from '/snippets/components/card.jsx';
 
 The Miru Agent follows [semantic versioning](https://semver.org/) for its releases. 
 
-Currently, the Miru Agent is still in beta, signified by the `v0` prefix for its releases. There is no established release cadence for the Miru Agent--features are simply released as soon as they are ready.
+Currently, the Miru Agent is still in beta, signified by the `v0` prefix for its releases. There is no established release cadence for the Miru Agent—features are simply released as soon as they are ready.
 
 ## Supported versions
 
diff --git a/docs/developers/device-api/overview.mdx b/docs/developers/device-api/overview.mdx
@@ -6,7 +6,7 @@ import DeviceAPICard from '/snippets/references/device-api/card.mdx';
 
 The Miru Device API is a REST API for programmatically interacting with the Miru Agent from an application running on the same device as the agent.
 
-The Device API is not available over the internet--it is only accessible from the device running the Miru Agent. It is useful for manually refreshing configurations, retrieving current configurations, and checking agent status from applications running on your devices.
+The Device API is not available over the internet—it is only accessible from the device running the Miru Agent. It is useful for manually refreshing configurations, retrieving current configurations, and checking agent status from applications running on your devices.
 
 The Device API is distinct from the Miru [Platform API](/docs/developers/platform-api/overview), which is a REST API for backend services and CI/CD pipelines to manage Miru resources.
 
diff --git a/docs/developers/device-api/versioning.mdx b/docs/developers/device-api/versioning.mdx
@@ -11,7 +11,7 @@ import { CardNewTab } from '/snippets/components/card.jsx';
 
 The Device API adheres to [semantic versioning](https://semver.org/), which was chosen so that on-device applications can easily determine API version compatibility.
 
-The Device API is currently in beta, signified by the `v0` prefix. There is no established release cadence for the Device API--features are simply released as soon as they are ready.
+The Device API is currently in beta, signified by the `v0` prefix. There is no established release cadence for the Device API—features are simply released as soon as they are ready.
 
 ## URL format
 
@@ -48,7 +48,7 @@ As rule of thumb, use the API version of the oldest agent version that is deploy
 
 ## Supported versions
 
-The Device API does not have its own support policy--its support is inherited from the Miru Agent. 
+The Device API does not have its own support policy—its support is inherited from the Miru Agent. 
 
 If a supported Miru Agent uses an API version, that API version is supported. You can find the supported Miru Agent versions on the [Agent Versions](/docs/developers/agent/versions) page.
 
@@ -86,7 +86,7 @@ During **beta** (`v0.x.y`)
 
 After **stable** (`v1.0`+)
 - Major version bumps (e.g. `v1.x` to `v2.0`) may include breaking changes
-- Minor version bumps (e.g. `v1.0` to `v1.1`) are additive only--no breaking changes
+- Minor version bumps (e.g. `v1.0` to `v1.1`) are additive only—no breaking changes
 
 ### Breaking changes
 
diff --git a/docs/getting-started/quick-start/create-release.mdx b/docs/getting-started/quick-start/create-release.mdx
@@ -63,7 +63,7 @@ Click the **New Config Type** button, supply the name `Mobility` and slug `mobil
   ![Miru UI screenshot](https://assets.mirurobotics.com/docs/v03/images/config-types/create-dialog.png)
 </Frame>
 
-The provided slug is a unique identifier for the config type--it's how the CLI determines which config type a schema belongs to. As such, config schemas _must_ be annotated with the slug of the config type to which they belong.
+The provided slug is a unique identifier for the config type—it's how the CLI determines which config type a schema belongs to. As such, config schemas _must_ be annotated with the slug of the config type to which they belong.
 
 <CodeGroup>
 
diff --git a/docs/learn/deployments.mdx b/docs/learn/deployments.mdx
@@ -167,13 +167,13 @@ As you can see, the target status can only move _forward_, never backwards.
 
 Once a deployment's target status has been set to `deployed`, it can never be set to `staged` again.  Similarly, once a deployment's target status has been set to `archived`, it can never be set to `deployed` again.
 
-This is intentional--deployments are one-time use. Once a deployment has been deployed, it cannot be redeployed. You must create a new deployment with identical content to roll back.
+This is intentional—deployments are one-time use. Once a deployment has been deployed, it cannot be redeployed. You must create a new deployment with identical content to roll back.
 
 ## Activity Status
 
 The activity status is the _last known_ state of a deployment.
 
-We use _the last known state_ intentionally -- poor network connectivity can prevent devices from immediately syncing their activity state with the cloud. In practice, this isn't too common. However, it's still a critical point to keep in mind.
+We use _the last known state_ intentionally—poor network connectivity can prevent devices from immediately syncing their activity state with the cloud. In practice, this isn't too common. However, it's still a critical point to keep in mind.
 
 There are five possible activity states for a deployment.
 
@@ -234,7 +234,7 @@ As with the target status, activity states can only progress forward since deplo
 
 ## Error Status
 
-The error status is the _last known_ error state of a deployment. Again, we use _the last known state_ intentionally -- poor network connectivity can prevent devices from immediately syncing their error state to the cloud.
+The error status is the _last known_ error state of a deployment. Again, we use _the last known state_ intentionally—poor network connectivity can prevent devices from immediately syncing their error state to the cloud.
 
 The error status is independent of the activity and target statuses. The error status does not imply any particular activity or target state, and vice versa. The error status is only concerned with errors encountered during deployment.
 
diff --git a/docs/learn/devices/deployment-history.mdx b/docs/learn/devices/deployment-history.mdx
@@ -28,7 +28,7 @@ To view the details of any config instances in the deployment, click into the co
   ![Miru UI screenshot](https://assets.mirurobotics.com/docs/v03/images/deployments/deployed-panel:configurations.png)
 </Frame>
 
-The content tab shows the config instance's parameters , while the metadata tab contains audit information--the author, creation date, description, etc.
+The content tab shows the config instance's parameters , while the metadata tab contains audit information—the author, creation date, description, etc.
 
 <Tabs>
   <Tab title="Content">
diff --git a/docs/learn/devices/manage.mdx b/docs/learn/devices/manage.mdx
@@ -88,7 +88,7 @@ To delete a device, click the ellipses (...) on the device you want to delete an
   ![Miru UI screenshot](https://assets.mirurobotics.com/docs/v03/images/devices/ellipses-dropdown.png)
 </Frame>
 
-A confirmation dialog will appear--click **Delete** to confirm.
+A confirmation dialog will appear—click **Delete** to confirm.
 
 <Frame>
   ![Miru UI screenshot](https://assets.mirurobotics.com/docs/v03/images/devices/delete-dialog.png)
diff --git a/docs/learn/devices/overview.mdx b/docs/learn/devices/overview.mdx
@@ -103,7 +103,7 @@ flowchart LR
 
 Devices begin in the `inactive` state. During the Miru Agent install process, devices briefly enter the `activating` state before transitioning to `online`.
 
-Once the Miru Agent has been activated on a device, the device remains `online` or `offline` for the remainder of its existence--devices don't transition back to `inactive` or `activating`.
+Once the Miru Agent has been activated on a device, the device remains `online` or `offline` for the remainder of its existence—devices don't transition back to `inactive` or `activating`.
 
 The only exception to this is when a device is [reactivated](/docs/learn/devices/manage#reactivate-a-device). During reactivation, devices briefly enter the `activating` state before transitioning back to `online`.
 
diff --git a/docs/learn/releases/deployment-history.mdx b/docs/learn/releases/deployment-history.mdx
@@ -28,7 +28,7 @@ To view the details of any config instances in the deployment, click into the co
   ![Miru UI screenshot](https://assets.mirurobotics.com/docs/v03/images/deployments/deployed-panel:configurations.png)
 </Frame>
 
-The content tab contains the config instance's parameters, while the metadata tab contains audit information--the author, creation date, description, etc.
+The content tab contains the config instance's parameters, while the metadata tab contains audit information—the author, creation date, description, etc.
 
 <Tabs>
   <Tab title="Content">
diff --git a/docs/learn/releases/staging-area.mdx b/docs/learn/releases/staging-area.mdx
@@ -114,7 +114,7 @@ instance in the **Configurations** section of the panel.
 </Frame>
 
 The content tab contains the config instance's parameters, while the metadata tab
-contains audit information--the author, creation date, description, etc.
+contains audit information—the author, creation date, description, etc.
 
 <Tabs>
   <Tab title="Content">
@@ -173,7 +173,7 @@ To archive a single deployment, click the ellipsis (...) on the deployment and s
   ![Miru UI screenshot](https://assets.mirurobotics.com/docs/v03/images/releases/stage/ellipses-dropdown:staged.png)
 </Frame>
 
-A confirmation dialog will appear--hit **Archive** to confirm.
+A confirmation dialog will appear—hit **Archive** to confirm.
 
 <Frame>
   ![Miru UI screenshot](https://assets.mirurobotics.com/docs/v03/images/releases/stage/archive-dialog:single.png)
@@ -194,7 +194,7 @@ At the bottom of the page, click **Archive** from the available bulk actions.
   ![Miru UI screenshot](https://assets.mirurobotics.com/docs/v03/images/releases/stage/bulk-actions.png)
 </Frame>
 
-A confirmation dialog will appear--hit **Archive** to confirm.
+A confirmation dialog will appear—hit **Archive** to confirm.
 
 <Frame>
   ![Miru UI screenshot](https://assets.mirurobotics.com/docs/v03/images/releases/stage/archive-dialog:bulk.png)
@@ -240,7 +240,7 @@ Our device is about to be upgraded to release `v1.6` though, so we've staged dep
 `DPL-Q4CeX` for the upcoming upgrade.
 
 However, before the upgrade occurs, our device receives some configuration updates on
-release `v1.5`--`DPL-Npfzv` is patched with `DPL-BFwc3`. Since it's often the case that
+release `v1.5`—`DPL-Npfzv` is patched with `DPL-BFwc3`. Since it's often the case that
 this patch also needs to be applied to the staged deployment `DPL-Q4CeX`, we say
 `DPL-Q4CeX` has _drifted_.
 
diff --git a/docs/learn/schemas/overview.mdx b/docs/learn/schemas/overview.mdx
@@ -51,7 +51,7 @@ import {Framed} from '/snippets/components/framed.jsx';
 
   A hash of the canonicalized schema content.
 
-  Digests are computed by converting schemas to a canonical format--a format that ignores whitespace, comments, and other non-semantic differences--and then hashing the result. This is useful for comparing schemas and detecting duplicates.
+  Digests are computed by converting schemas to a canonical format—a format that ignores whitespace, comments, and other non-semantic differences—and then hashing the result. This is useful for comparing schemas and detecting duplicates.
 
   Examples: `sha256:45YeoJJ2btBnAKQztAEXEjHsqyyQfC1z1Mw3LLM4xMUy`
 </ParamField>
@@ -76,7 +76,7 @@ import {Framed} from '/snippets/components/framed.jsx';
 
 ## Schema languages
 
-Config schemas are defined using a schema language--a formal language for describing the structure, constraints, and data types of a configuration.
+Config schemas are defined using a schema language—a formal language for describing the structure, constraints, and data types of a configuration.
 
 Miru supports:
 
@@ -146,7 +146,7 @@ The schema defines what constitutes a valid config instance in several different
 - Names the available properties
 - Organizes the configuration structure, placing some properties at the root while nesting other properties into logical groups
 - Gives each property a type, such as `number`, `boolean`, etc.
-- Constrains the values of each property--minimums, maximums, enumerations, etc.
+- Constrains the values of each property—minimums, maximums, enumerations, etc.
 - Supplies default values to properties where appropriate
 
 Most of these constraints are optional, and many features of JSON Schema are omitted here, but this gives you a flavor of what schemas are capable of.
@@ -179,7 +179,7 @@ Although simple in concept, schemas are a powerful tool for preventing typos, mi
 
 While schemas provide significant value in production deployments, defining one from scratch can be a considerable undertaking.
 
-Many teams find it best to begin with an empty schema--one that accepts any configuration--and gradually add constraints. This approach allows you to define the most highly valued constraints first and progressively transition to stricter and stricter schemas as needed.
+Many teams find it best to begin with an empty schema—one that accepts any configuration—and gradually add constraints. This approach allows you to define the most highly valued constraints first and progressively transition to stricter and stricter schemas as needed.
 
 Below are the empty schemas for JSON Schema and CUE, respectively.
 
diff --git a/scripts/lint.sh b/scripts/lint.sh
@@ -12,6 +12,11 @@ if ! command -v pnpm >/dev/null 2>&1; then
   exit 1
 fi
 
+if ! command -v go >/dev/null 2>&1; then
+  echo "go is required for MDX prose linting. Install Go and rerun ./scripts/lint.sh." >&2
+  exit 1
+fi
+
 cd "${repo_root}"
 
 collect_files() {
@@ -56,6 +61,10 @@ if [[ ${#openapi_targets[@]} -eq 0 ]]; then
   exit 1
 fi
 
+echo "== MDX Prose =="
+(cd "${repo_root}/tools/lint" && go build -o lint .)
+"${repo_root}/tools/lint/lint" "${mdx_targets[@]}"
+
 echo "== ESLint (MDX) =="
 pnpm exec eslint --max-warnings=0 "${mdx_targets[@]}"
 
diff --git a/snippets/definitions/release.mdx b/snippets/definitions/release.mdx
@@ -1,6 +1,6 @@
 A **release** is a version of software and its compatible config schemas.
 
-Within a fleet of robots, multiple software versions may be deployed -- each release defines which config schemas are valid for that version.
+Within a fleet of robots, multiple software versions may be deployed—each release defines which config schemas are valid for that version.
 
 For example, software release `v1.7.0` might specify the following schemas:
 
diff --git a/snippets/references/cli/releases/create/cue-packages.mdx b/snippets/references/cli/releases/create/cue-packages.mdx
@@ -15,7 +15,7 @@ Each file defines a portion of the schema, which is then aggregated by the `main
 
 The Miru CLI automatically identifies CUE packages for you when creating a release using the `package` clause at the top of each schema file (as described in the [CUE documentation](https://cuelang.org/docs/tour/packages/packages/)).
 
-You don't need to explicitly specify the package in the CLI command--just provide the path to the package directory or to the individual schema files within the package.
+You don't need to explicitly specify the package in the CLI command—just provide the path to the package directory or to the individual schema files within the package.
 
 **Annotations**
 
diff --git a/tools/lint/go.mod b/tools/lint/go.mod
@@ -0,0 +1,3 @@
+module github.com/mirurobotics/docs/tools/lint
+
+go 1.24
diff --git a/tools/lint/main.go b/tools/lint/main.go
diff --git a/tools/lint/rules.go b/tools/lint/rules.go
diff --git a/tools/lint/rules_test.go b/tools/lint/rules_test.go
diff --git a/tools/lint/scanner.go b/tools/lint/scanner.go
diff --git a/tools/lint/scanner_test.go b/tools/lint/scanner_test.go
