Merge PR #541: markdownlint migration: auto-conversion via mdsmith init --from-markdownlint + guide rewrite

Author: merge-queue-bot

.github/copilot-instructions.md

@@ -110,7 +110,7 @@ row: "- [{summary}](../{filename})"
 - [User guides for mdsmith directives, structure enforcement, and migration.](../docs/guides/index.md)
 - [Every channel that ships the mdsmith binary, the VS Code extension, or the Claude Code plugin — npm, PyPI, Homebrew, asdf, mise, a Flatpak bundle, the GitHub release, the Visual Studio Marketplace plus Open VSX, and the in-repository Claude Code marketplace — and which channel to pick for which workflow.](../docs/guides/install.md)
 - [Trade-offs and threshold guidance for readability, structure, length, and token budgets.](../docs/guides/metrics-tradeoffs.md)
-- [Move a project from markdownlint-cli or markdownlint-cli2 to mdsmith — the rule mapping, the config rewrite, and the markdownlint-to-mdsmith rule correspondence.](../docs/guides/migrate-from-markdownlint.md)
+- [Convert a markdownlint config to `.mdsmith.yml` with `mdsmith init --from-markdownlint`, review the conversion notes, move inline disables into overrides, and run both linters in parallel until cutover.](../docs/guides/migrate-from-markdownlint.md)
 - [Use `<?catalog?>` with a per-file `summary` front matter field to emit a one-line index of a directory, so AI coding agents read a few thousand tokens of metadata up front and only `Read` the files a task actually touches.](../docs/guides/progressive-disclosure.md)
 - [Declare a document-structure schema inline on a kind or in a proto.md file, validate headings and front matter, and tighten rule config per section.](../docs/guides/schemas.md)
 - [CLI commands, flags, exit codes, and output format.](../docs/reference/cli.md)
@@ -121,7 +121,7 @@ row: "- [{summary}](../{filename})"
 - [Emit a schema-conformant Markdown file as a JSON/YAML/msgpack data tree.](../docs/reference/cli/extract.md)
 - [Auto-fix lint issues in Markdown files in place.](../docs/reference/cli/fix.md)
 - [Show built-in documentation for rules, metrics, and concept pages.](../docs/reference/cli/help.md)
-- [Generate a default `.mdsmith.yml` config in the current directory.](../docs/reference/cli/init.md)
+- [Generate a default `.mdsmith.yml` config in the current directory, or convert an existing markdownlint config with `--from-markdownlint`.](../docs/reference/cli/init.md)
 - [Inspect declared file kinds and resolve effective rule config per file.](../docs/reference/cli/kinds.md)
 - [Selection-style commands that walk the workspace and emit matches.](../docs/reference/cli/list.md)
 - [Run a Language Server Protocol server on stdio for editor integrations.](../docs/reference/cli/lsp.md)
@@ -136,6 +136,7 @@ row: "- [{summary}](../{filename})"
 - [Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.](../docs/reference/globs.md)
 - [Look up exact CLI commands, config glob and schema syntax, the built-in conventions, and the section-schema grammar.](../docs/reference/index.md)
 - [Each file under `.mdsmith/kinds/` declares one kind. The basename is the kind name; the file body carries the full `KindBody` — schema, rules, `path-pattern:`, `extends:`. Sits alongside inline `kinds.<name>:` in `.mdsmith.yml`.](../docs/reference/kind-files.md)
+- [Every markdownlint rule and the mdsmith rule that covers it, generated from the rule README front matter — the same data `mdsmith init --from-markdownlint` reads.](../docs/reference/markdownlint-mapping.md)
 - [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)

AGENTS.md

@@ -116,7 +116,7 @@ row: "- [{summary}]({filename})"
 - [User guides for mdsmith directives, structure enforcement, and migration.](docs/guides/index.md)
 - [Every channel that ships the mdsmith binary, the VS Code extension, or the Claude Code plugin — npm, PyPI, Homebrew, asdf, mise, a Flatpak bundle, the GitHub release, the Visual Studio Marketplace plus Open VSX, and the in-repository Claude Code marketplace — and which channel to pick for which workflow.](docs/guides/install.md)
 - [Trade-offs and threshold guidance for readability, structure, length, and token budgets.](docs/guides/metrics-tradeoffs.md)
-- [Move a project from markdownlint-cli or markdownlint-cli2 to mdsmith — the rule mapping, the config rewrite, and the markdownlint-to-mdsmith rule correspondence.](docs/guides/migrate-from-markdownlint.md)
+- [Convert a markdownlint config to `.mdsmith.yml` with `mdsmith init --from-markdownlint`, review the conversion notes, move inline disables into overrides, and run both linters in parallel until cutover.](docs/guides/migrate-from-markdownlint.md)
 - [Use `<?catalog?>` with a per-file `summary` front matter field to emit a one-line index of a directory, so AI coding agents read a few thousand tokens of metadata up front and only `Read` the files a task actually touches.](docs/guides/progressive-disclosure.md)
 - [Declare a document-structure schema inline on a kind or in a proto.md file, validate headings and front matter, and tighten rule config per section.](docs/guides/schemas.md)
 - [CLI commands, flags, exit codes, and output format.](docs/reference/cli.md)
@@ -127,7 +127,7 @@ row: "- [{summary}]({filename})"
 - [Emit a schema-conformant Markdown file as a JSON/YAML/msgpack data tree.](docs/reference/cli/extract.md)
 - [Auto-fix lint issues in Markdown files in place.](docs/reference/cli/fix.md)
 - [Show built-in documentation for rules, metrics, and concept pages.](docs/reference/cli/help.md)
-- [Generate a default `.mdsmith.yml` config in the current directory.](docs/reference/cli/init.md)
+- [Generate a default `.mdsmith.yml` config in the current directory, or convert an existing markdownlint config with `--from-markdownlint`.](docs/reference/cli/init.md)
 - [Inspect declared file kinds and resolve effective rule config per file.](docs/reference/cli/kinds.md)
 - [Selection-style commands that walk the workspace and emit matches.](docs/reference/cli/list.md)
 - [Run a Language Server Protocol server on stdio for editor integrations.](docs/reference/cli/lsp.md)
@@ -142,6 +142,7 @@ row: "- [{summary}]({filename})"
 - [Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.](docs/reference/globs.md)
 - [Look up exact CLI commands, config glob and schema syntax, the built-in conventions, and the section-schema grammar.](docs/reference/index.md)
 - [Each file under `.mdsmith/kinds/` declares one kind. The basename is the kind name; the file body carries the full `KindBody` — schema, rules, `path-pattern:`, `extends:`. Sits alongside inline `kinds.<name>:` in `.mdsmith.yml`.](docs/reference/kind-files.md)
+- [Every markdownlint rule and the mdsmith rule that covers it, generated from the rule README front matter — the same data `mdsmith init --from-markdownlint` reads.](docs/reference/markdownlint-mapping.md)
 - [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)

CLAUDE.md

@@ -102,7 +102,7 @@ row: "- [{summary}]({filename})"
 - [User guides for mdsmith directives, structure enforcement, and migration.](docs/guides/index.md)
 - [Every channel that ships the mdsmith binary, the VS Code extension, or the Claude Code plugin — npm, PyPI, Homebrew, asdf, mise, a Flatpak bundle, the GitHub release, the Visual Studio Marketplace plus Open VSX, and the in-repository Claude Code marketplace — and which channel to pick for which workflow.](docs/guides/install.md)
 - [Trade-offs and threshold guidance for readability, structure, length, and token budgets.](docs/guides/metrics-tradeoffs.md)
-- [Move a project from markdownlint-cli or markdownlint-cli2 to mdsmith — the rule mapping, the config rewrite, and the markdownlint-to-mdsmith rule correspondence.](docs/guides/migrate-from-markdownlint.md)
+- [Convert a markdownlint config to `.mdsmith.yml` with `mdsmith init --from-markdownlint`, review the conversion notes, move inline disables into overrides, and run both linters in parallel until cutover.](docs/guides/migrate-from-markdownlint.md)
 - [Use `<?catalog?>` with a per-file `summary` front matter field to emit a one-line index of a directory, so AI coding agents read a few thousand tokens of metadata up front and only `Read` the files a task actually touches.](docs/guides/progressive-disclosure.md)
 - [Declare a document-structure schema inline on a kind or in a proto.md file, validate headings and front matter, and tighten rule config per section.](docs/guides/schemas.md)
 - [CLI commands, flags, exit codes, and output format.](docs/reference/cli.md)
@@ -113,7 +113,7 @@ row: "- [{summary}]({filename})"
 - [Emit a schema-conformant Markdown file as a JSON/YAML/msgpack data tree.](docs/reference/cli/extract.md)
 - [Auto-fix lint issues in Markdown files in place.](docs/reference/cli/fix.md)
 - [Show built-in documentation for rules, metrics, and concept pages.](docs/reference/cli/help.md)
-- [Generate a default `.mdsmith.yml` config in the current directory.](docs/reference/cli/init.md)
+- [Generate a default `.mdsmith.yml` config in the current directory, or convert an existing markdownlint config with `--from-markdownlint`.](docs/reference/cli/init.md)
 - [Inspect declared file kinds and resolve effective rule config per file.](docs/reference/cli/kinds.md)
 - [Selection-style commands that walk the workspace and emit matches.](docs/reference/cli/list.md)
 - [Run a Language Server Protocol server on stdio for editor integrations.](docs/reference/cli/lsp.md)
@@ -128,6 +128,7 @@ row: "- [{summary}]({filename})"
 - [Glob pattern syntax across mdsmith config, directives, and CLI argument expansion, with the supported exclusion semantics for each surface.](docs/reference/globs.md)
 - [Look up exact CLI commands, config glob and schema syntax, the built-in conventions, and the section-schema grammar.](docs/reference/index.md)
 - [Each file under `.mdsmith/kinds/` declares one kind. The basename is the kind name; the file body carries the full `KindBody` — schema, rules, `path-pattern:`, `extends:`. Sits alongside inline `kinds.<name>:` in `.mdsmith.yml`.](docs/reference/kind-files.md)
+- [Every markdownlint rule and the mdsmith rule that covers it, generated from the rule README front matter — the same data `mdsmith init --from-markdownlint` reads.](docs/reference/markdownlint-mapping.md)
 - [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)

README.md

@@ -54,6 +54,9 @@ Together they keep a whole docs tree consistent as it grows, so
 the same Markdown can drive your README, your docs site, and
 downstream pipelines.
 
+Already on markdownlint? `mdsmith init --from-markdownlint`
+converts your config and notes whatever needs review.
+
 One rule engine runs everywhere you work: in CI, in your editor
 through `mdsmith lsp`, and in your coding agent through a Claude
 Code plugin. The check that blocks a merge is the same one you see
@@ -256,25 +259,25 @@ header: |
   |---------|-------------|
 row: "| [`{command}`]({filename}) | {summary} |"
 ?>
-| Command                                                      | Description                                                                          |
-| ------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
-| [`check`](docs/reference/cli/check.md)                       | Lint Markdown files for style issues.                                                |
-| [`deps`](docs/reference/cli/deps.md)                         | List a file's dependency-graph edges (includes, links, catalogs, builds).            |
-| [`export`](docs/reference/cli/export.md)                     | Write a portable, directive-free copy of a Markdown file.                            |
-| [`extract`](docs/reference/cli/extract.md)                   | Emit a schema-conformant Markdown file as a JSON/YAML/msgpack data tree.             |
-| [`fix`](docs/reference/cli/fix.md)                           | Auto-fix lint issues in Markdown files in place.                                     |
-| [`help`](docs/reference/cli/help.md)                         | Show built-in documentation for rules, metrics, and concept pages.                   |
-| [`init`](docs/reference/cli/init.md)                         | Generate a default `.mdsmith.yml` config in the current directory.                   |
-| [`kinds`](docs/reference/cli/kinds.md)                       | Inspect declared file kinds and resolve effective rule config per file.              |
-| [`list`](docs/reference/cli/list.md)                         | Selection-style commands that walk the workspace and emit matches.                   |
-| [`list backlinks`](docs/reference/cli/backlinks.md)          | List workspace links that point at a file.                                           |
-| [`list query`](docs/reference/cli/query.md)                  | Select Markdown files by a CUE expression on front matter.                           |
-| [`lsp`](docs/reference/cli/lsp.md)                           | Run a Language Server Protocol server on stdio for editor integrations.              |
-| [`merge-driver`](docs/reference/cli/merge-driver.md)         | Git merge driver that resolves conflicts inside generated sections.                  |
-| [`metrics`](docs/reference/cli/metrics.md)                   | List and rank shared Markdown metrics (file length, token estimate, readability, …). |
-| [`pre-merge-commit`](docs/reference/cli/pre-merge-commit.md) | Install / manage a pre-merge-commit hook that runs `mdsmith fix` after a merge.      |
-| [`rename`](docs/reference/cli/rename.md)                     | Rename a heading or link-reference label and rewrite every dependent edit.           |
-| [`version`](docs/reference/cli/version.md)                   | Print the mdsmith build version and exit.                                            |
+| Command                                                      | Description                                                                                                                               |
+| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| [`check`](docs/reference/cli/check.md)                       | Lint Markdown files for style issues.                                                                                                     |
+| [`deps`](docs/reference/cli/deps.md)                         | List a file's dependency-graph edges (includes, links, catalogs, builds).                                                                 |
+| [`export`](docs/reference/cli/export.md)                     | Write a portable, directive-free copy of a Markdown file.                                                                                 |
+| [`extract`](docs/reference/cli/extract.md)                   | Emit a schema-conformant Markdown file as a JSON/YAML/msgpack data tree.                                                                  |
+| [`fix`](docs/reference/cli/fix.md)                           | Auto-fix lint issues in Markdown files in place.                                                                                          |
+| [`help`](docs/reference/cli/help.md)                         | Show built-in documentation for rules, metrics, and concept pages.                                                                        |
+| [`init`](docs/reference/cli/init.md)                         | Generate a default `.mdsmith.yml` config in the current directory, or convert an existing markdownlint config with `--from-markdownlint`. |
+| [`kinds`](docs/reference/cli/kinds.md)                       | Inspect declared file kinds and resolve effective rule config per file.                                                                   |
+| [`list`](docs/reference/cli/list.md)                         | Selection-style commands that walk the workspace and emit matches.                                                                        |
+| [`list backlinks`](docs/reference/cli/backlinks.md)          | List workspace links that point at a file.                                                                                                |
+| [`list query`](docs/reference/cli/query.md)                  | Select Markdown files by a CUE expression on front matter.                                                                                |
+| [`lsp`](docs/reference/cli/lsp.md)                           | Run a Language Server Protocol server on stdio for editor integrations.                                                                   |
+| [`merge-driver`](docs/reference/cli/merge-driver.md)         | Git merge driver that resolves conflicts inside generated sections.                                                                       |
+| [`metrics`](docs/reference/cli/metrics.md)                   | List and rank shared Markdown metrics (file length, token estimate, readability, …).                                                      |
+| [`pre-merge-commit`](docs/reference/cli/pre-merge-commit.md) | Install / manage a pre-merge-commit hook that runs `mdsmith fix` after a merge.                                                           |
+| [`rename`](docs/reference/cli/rename.md)                     | Rename a heading or link-reference label and rewrite every dependent edit.                                                                |
+| [`version`](docs/reference/cli/version.md)                   | Print the mdsmith build version and exit.                                                                                                 |
 <?/catalog?>
 
 That command table and the feature list above are generated by mdsmith's own directives.