Merge PR #713: docs(vscode): lead the VS Code page with the install decision

merge-queue-bot · merge-queue-bot · commit 830a7ca8083f · 2026-06-29T20:20:57.000Z
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -147,6 +147,7 @@ row: "- [{summary}](../{filename})"
 - [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](../docs/reference/schema-types.md)
 - [Section-schema reference for inline `kinds.<name>.schema:` blocks. Covers the `heading:` discriminator, the `regex:` matcher (a Go RE2 body with `\#(digits)` and `\#(fmvar(...))` helpers), the `repeat: {min, max}` cardinality field, and the matching algorithm. `proto.md` files are parsed into the same shape by the schema package, but MDS020's file-schema check still uses its legacy parser; see the proto.md section below for what is and is not migrated.](../docs/reference/section-schema.md)
 - [mdsmith collects no telemetry, no usage analytics, no error reports, and no identifiers. The CLI and the LSP server make no outbound network calls at runtime.](../docs/reference/telemetry.md)
+- [Settings and troubleshooting for the mdsmith VS Code extension: the five `mdsmith.*` settings, fix-on-save wiring, and fixes for its known failure modes.](../docs/reference/vscode-extension.md)
 <?/catalog?>
 
 ### Development Workflow
diff --git a/AGENTS.md b/AGENTS.md
@@ -153,6 +153,7 @@ row: "- [{summary}]({filename})"
 - [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](docs/reference/schema-types.md)
 - [Section-schema reference for inline `kinds.<name>.schema:` blocks. Covers the `heading:` discriminator, the `regex:` matcher (a Go RE2 body with `\#(digits)` and `\#(fmvar(...))` helpers), the `repeat: {min, max}` cardinality field, and the matching algorithm. `proto.md` files are parsed into the same shape by the schema package, but MDS020's file-schema check still uses its legacy parser; see the proto.md section below for what is and is not migrated.](docs/reference/section-schema.md)
 - [mdsmith collects no telemetry, no usage analytics, no error reports, and no identifiers. The CLI and the LSP server make no outbound network calls at runtime.](docs/reference/telemetry.md)
+- [Settings and troubleshooting for the mdsmith VS Code extension: the five `mdsmith.*` settings, fix-on-save wiring, and fixes for its known failure modes.](docs/reference/vscode-extension.md)
 <?/catalog?>
 
 ## Development Workflow
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -139,6 +139,7 @@ row: "- [{summary}]({filename})"
 - [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](docs/reference/schema-types.md)
 - [Section-schema reference for inline `kinds.<name>.schema:` blocks. Covers the `heading:` discriminator, the `regex:` matcher (a Go RE2 body with `\#(digits)` and `\#(fmvar(...))` helpers), the `repeat: {min, max}` cardinality field, and the matching algorithm. `proto.md` files are parsed into the same shape by the schema package, but MDS020's file-schema check still uses its legacy parser; see the proto.md section below for what is and is not migrated.](docs/reference/section-schema.md)
 - [mdsmith collects no telemetry, no usage analytics, no error reports, and no identifiers. The CLI and the LSP server make no outbound network calls at runtime.](docs/reference/telemetry.md)
+- [Settings and troubleshooting for the mdsmith VS Code extension: the five `mdsmith.*` settings, fix-on-save wiring, and fixes for its known failure modes.](docs/reference/vscode-extension.md)
 <?/catalog?>
 
 ## Development Workflow
diff --git a/docs/guides/editors/vscode.md b/docs/guides/editors/vscode.md
@@ -7,19 +7,24 @@ summary: >-
 ---
 # mdsmith for VS Code
 
-The mdsmith extension puts the linter, the formatter, and
-cross-file navigation in your editor. It runs the same rule
-engine as `mdsmith check` on the command line and in CI, so a
-file that is clean as you edit is clean in the pipeline.
-Diagnostics, quick fixes, and navigation all come from one
-bundled binary, with nothing else to install.
+mdsmith is a Markdown linter and formatter that runs inside
+VS Code. It flags style, readability, structure, and broken
+cross-file links as you type, and fixes what fixes cleanly on
+save. The editor runs the same rule engine as `mdsmith check`
+on the command line and in CI, so a file that is clean as you
+edit is clean in the pipeline.
 
 If you use markdownlint today, mdsmith covers the same style
-rules and adds cross-file checks. `mdsmith init
+rules and adds checks markdownlint has no model for: links
+and anchors across files, generated sections, heading and
+front-matter schemas, and readability budgets. `mdsmith init
 --from-markdownlint` converts your config in one command; the
 [migration guide](../migrate-from-markdownlint.md) covers the
 rest of the move.
 
+Diagnostics, quick fixes, and navigation all come from one
+bundled binary, with nothing else to install.
+
 ## What you get
 
 Each feature links to a page with its rules and examples.
@@ -51,15 +56,8 @@ clicked.
 
 Each save then fixes trailing whitespace, heading style, code
 fences, bare URLs, list indentation, and table alignment.
-
-**Preview fix-on-save.** Enable `mdsmith.previewFix` and
-fix-on-save routes through VS Code's Refactor Preview pane, so
-you see the diff and confirm it before `source.fixAll.mdsmith`
-writes it on save. Interactive lightbulb quick fixes always
-apply immediately — they are the one fix you just chose, so
-there is nothing to confirm. To preview a single quick fix,
-use VS Code's built-in lightbulb Preview (the chevron, or
-Ctrl+Enter).
+Enable `mdsmith.previewFix` to see the diff in VS Code's
+Refactor Preview before each save writes.
 
 **Hover for help.** Hover a diagnostic for the rule's one-line
 summary plus a link that opens its full documentation offline:
@@ -124,75 +122,29 @@ codium --install-extension jeduden.mdsmith
 code --install-extension mdsmith-<version>.vsix
 ```
 
-You need VS Code 1.85 or later. A config file is optional:
-mdsmith lints with built-in defaults, so the extension works
-as soon as you install it. To tune the rules, run the
-**mdsmith: Initialize Config** command, which writes a starter
-`.mdsmith.yml`. The server then finds that file by walking up
-from the workspace root to the nearest `.mdsmith.yml` or
-`.git`, the same as `mdsmith check`. See
+You need VS Code 1.85 or later. See
 [Installation: VS Code extension](../install.md#vs-code-extension)
 for the channel-by-channel breakdown.
 
-## Settings
-
-Project overrides go in `.vscode/settings.json`; global
-preferences go in your user settings. Changing any setting
-takes effect on the next document event, with no window
-reload.
-
-| Setting                | Default   | Purpose                                                                                   |
-| ---------------------- | --------- | ----------------------------------------------------------------------------------------- |
-| `mdsmith.run`          | `onType`  | When to lint: `onType` (default), `onSave`, or `off` (off stops automatic linting)        |
-| `mdsmith.previewFix`   | `false`   | Show the diff (Refactor Preview) before fix-on-save writes; quick fixes apply immediately |
-| `mdsmith.config`       | `""`      | Override the `.mdsmith.yml` path (absolute or workspace)                                  |
-| `mdsmith.path`         | `mdsmith` | Pin a binary; the default runs the bundled per-platform one                               |
-| `mdsmith.trace.server` | `off`     | LSP trace verbosity: `off`, `messages`, or `verbose`                                      |
-
-`mdsmith.run` defaults to `onType`, so diagnostics update live
-as you type; `onSave` defers them to save, and `off` stops
-them entirely (quick fixes still work on demand).
-
-Fix-on-save is configured through VS Code's native
-`editor.codeActionsOnSave`, shown above under **Fix on save** —
-not through an mdsmith setting. The former `mdsmith.fixOnSave`
-toggle is now a deprecated no-op. Fix-on-save runs independently
-of `mdsmith.run`, and `mdsmith.previewFix` decides whether each
-save shows the diff before writing. `mdsmith.previewFix` governs
-fix-on-save only; interactive lightbulb quick fixes always apply
-immediately (use the lightbulb's own Preview to inspect one).
-
-## Troubleshooting
-
-**No diagnostics appear.** Confirm the binary resolves: open
-the integrated terminal and run `mdsmith version`. If it is
-not found, set `mdsmith.path` to an absolute path. Set
-`mdsmith.trace.server` to `messages` and read the "mdsmith"
-Output channel.
-
-**`spawn mdsmith ENOENT`.** Reachable only when you set
-`mdsmith.path` to a bare name and your platform was not
-bundled. The extension host does not source `~/.bashrc`, so a
-`go install` location such as `~/go/bin` is invisible to it.
-Clear `mdsmith.path` to use the bundled binary, or set it to
-an absolute path.
-
-**Server crashed too many times.** The restart limiter
-tripped because the binary crashes on every request. Open the
-"mdsmith" Output channel for the stack trace, fix the cause,
-then run `mdsmith: Restart Language Server`.
-
-**Two mdsmith servers running; I want one.** A reload or
-update can leave the old extension host alive next to the new
-one, each running its own server. The newest server wins: it
-claims the workspace and the older one exits, sending an
-`mdsmith/superseded` notice first so the client does not
-restart it. If an older build left an orphan, kill its
-extension host once — not the `mdsmith` process, which the
-host respawns.
+## Settings and troubleshooting
+
+A config file is optional: mdsmith lints with built-in
+defaults, so the extension works as soon as you install it. To
+tune the rules, run the **mdsmith: Initialize Config** command,
+which writes a starter `.mdsmith.yml`. The server then finds
+that file by walking up from the workspace root to the nearest
+`.mdsmith.yml` or `.git`, the same as `mdsmith check`.
+
+For the full settings table — `mdsmith.run`, `mdsmith.path`,
+`mdsmith.config`, `mdsmith.previewFix`, and
+`mdsmith.trace.server` — and fixes for common failure modes,
+see the
+[VS Code extension reference](../../reference/vscode-extension.md).
 
 ## See also
 
+- [VS Code extension reference](../../reference/vscode-extension.md)
+  — the settings table and troubleshooting
 - [`mdsmith lsp`](../../reference/cli/lsp.md) — the protocol
   reference: capabilities, diagnostic mapping, symbol
   navigation, and the latency budget
diff --git a/docs/reference/cli/lsp.md b/docs/reference/cli/lsp.md
@@ -296,5 +296,7 @@ the p95 latency benchmarks (150 ms on 1 000-line, 500 ms on
 
 - [`mdsmith check`](check.md) — the CLI surface that the server reuses
 - [`mdsmith fix`](fix.md) — the fix pipeline behind both code actions
-- [VS Code guide](../../guides/editors/vscode.md) — install,
-  settings, troubleshooting
+- [VS Code guide](../../guides/editors/vscode.md) — what the
+  extension does and how to install it
+- [VS Code extension reference](../vscode-extension.md) — the
+  settings table and troubleshooting
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -44,4 +44,5 @@ row: "- [{summary}]({filename})"
 - [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](schema-types.md)
 - [Section-schema reference for inline `kinds.<name>.schema:` blocks. Covers the `heading:` discriminator, the `regex:` matcher (a Go RE2 body with `\#(digits)` and `\#(fmvar(...))` helpers), the `repeat: {min, max}` cardinality field, and the matching algorithm. `proto.md` files are parsed into the same shape by the schema package, but MDS020's file-schema check still uses its legacy parser; see the proto.md section below for what is and is not migrated.](section-schema.md)
 - [mdsmith collects no telemetry, no usage analytics, no error reports, and no identifiers. The CLI and the LSP server make no outbound network calls at runtime.](telemetry.md)
+- [Settings and troubleshooting for the mdsmith VS Code extension: the five `mdsmith.*` settings, fix-on-save wiring, and fixes for its known failure modes.](vscode-extension.md)
 <?/catalog?>
diff --git a/docs/reference/vscode-extension.md b/docs/reference/vscode-extension.md
@@ -0,0 +1,90 @@
+---
+weight: 45
+summary: >-
+  Settings and troubleshooting for the mdsmith VS Code
+  extension: the five `mdsmith.*` settings, fix-on-save
+  wiring, and fixes for its known failure modes.
+---
+# mdsmith VS Code extension
+
+The mdsmith VS Code extension is a thin LSP client over the
+bundled `mdsmith` binary, which it runs with the `lsp`
+subcommand. This page lists the extension's settings and the
+fixes for its known failure modes. For what the extension
+does and how to install it, see the
+[VS Code guide](../guides/editors/vscode.md).
+
+## Settings
+
+Project overrides go in `.vscode/settings.json`; global
+preferences go in user settings. A changed setting takes
+effect on the next document event, with no window reload.
+
+| Setting                | Default   | Purpose                                                                                   |
+| ---------------------- | --------- | ----------------------------------------------------------------------------------------- |
+| `mdsmith.run`          | `onType`  | When to lint: `onType` (default), `onSave`, or `off` (off stops automatic linting)        |
+| `mdsmith.previewFix`   | `false`   | Show the diff (Refactor Preview) before fix-on-save writes; quick fixes apply immediately |
+| `mdsmith.config`       | `""`      | Override the `.mdsmith.yml` path (absolute or workspace)                                  |
+| `mdsmith.path`         | `mdsmith` | Pin a binary; the default runs the bundled per-platform one                               |
+| `mdsmith.trace.server` | `off`     | LSP trace verbosity: `off`, `messages`, or `verbose`                                      |
+
+`mdsmith.run` controls automatic linting. `onType` updates
+diagnostics live as text changes. `onSave` defers them to
+save. `off` stops automatic linting; quick fixes still run
+on demand.
+
+`mdsmith.config` overrides config discovery. Without it, the
+server walks up from the workspace root to the nearest
+`.mdsmith.yml` or `.git`, the same as `mdsmith check`.
+
+## Fix on save
+
+Fix-on-save is configured through VS Code's native
+`editor.codeActionsOnSave`, not an mdsmith setting. The
+[VS Code guide](../guides/editors/vscode.md) shows the
+`source.fixAll.mdsmith` entry. The former `mdsmith.fixOnSave`
+toggle is now a deprecated no-op.
+
+Fix-on-save runs independently of `mdsmith.run`.
+`mdsmith.previewFix` governs fix-on-save only. When it is
+`true`, each save routes through VS Code's Refactor Preview
+pane and shows the diff before the edit writes. Interactive
+lightbulb quick fixes always apply immediately, since each is
+the one fix just chosen.
+
+## Troubleshooting
+
+**No diagnostics appear.** The binary did not resolve. Run
+`mdsmith version` in the integrated terminal. If the command
+is not found, set `mdsmith.path` to an absolute path. Set
+`mdsmith.trace.server` to `messages` and read the "mdsmith"
+Output channel.
+
+**`spawn mdsmith ENOENT`.** This is reachable only when
+`mdsmith.path` is a bare name and the running platform was
+not bundled. The extension host does not source `~/.bashrc`,
+so a `go install` location such as `~/go/bin` is invisible to
+it. Clear `mdsmith.path` to use the bundled binary, or set it
+to an absolute path.
+
+**Server crashed too many times.** The restart limiter
+tripped because the binary crashes on every request. Open the
+"mdsmith" Output channel for the stack trace, fix the cause,
+then run **mdsmith: Restart Language Server**.
+
+**Two mdsmith servers running.** A reload or update can leave
+the old extension host alive next to the new one, each with
+its own server. The newest server wins: it claims the
+workspace, and the older one exits after sending an
+`mdsmith/superseded` notice so the client does not restart
+it. If an older build left an orphan, kill its extension host
+once — not the `mdsmith` process, which the host respawns.
+
+## See also
+
+- [VS Code guide](../guides/editors/vscode.md) — what the
+  extension does and how to install it
+- [`mdsmith lsp`](cli/lsp.md) — the protocol reference:
+  capabilities, diagnostic mapping, and symbol navigation
+- [`mdsmith check`](cli/check.md) and [`mdsmith fix`](cli/fix.md)
+  — the CLI surfaces the extension reuses
