lecode-official · lecode-official · Aug 1, 2026 · Aug 1, 2026
diff --git a/.github/workflows/linters.yml b/.github/workflows/linters.yml
@@ -21,8 +21,8 @@ jobs:
       - name: Checkout Repository
         uses: actions/checkout@v7
 
-      # Installs Node.js, which is required to run the npm-based linters CSpell and MarkdownLint, as well as the dprint code formatter, which is
-      # distributed as an npm package; pins the Node.js version to the current long-term support release, so that the linters run in a stable and
+      # Installs Node.js, which is required to run the NPM-based linters CSpell and MarkdownLint, as well as the dprint code formatter, which is
+      # distributed as an NPM package; pins the Node.js version to the current long-term support release, so that the linters run in a stable and
       # reproducible environment
       - name: Set Up Node.js
         uses: actions/setup-node@v6

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -12,7 +12,7 @@ Start from [docs/developer-manual/architecture/overview.md](docs/developer-manua
 
 - **Match the surrounding code and the documented conventions** ([docs/developer-manual/conventions/](docs/developer-manual/conventions/csharp-style.md)). This code is heavily and consistently documented — follow it.
 - **Formatting is owned by dprint** ([docs/developer-manual/tooling/formatting-dprint.md](docs/developer-manual/tooling/formatting-dprint.md)) for Markdown, JSON, XML (including `.csproj`/`.slnx`), YAML, and TOML — never add a lint rule that reformats one of these. Run `dprint fmt` before finishing. **C# is not covered by dprint** (there is no C# plugin configured); its whitespace comes from [`.editorconfig`](.editorconfig) and its style from [C# Style](docs/developer-manual/conventions/csharp-style.md) alone, so review it by eye.
-- **Run the linters before finishing** — there is no npm-script wrapper, so invoke them directly with the versions [Continuous Integration](docs/developer-manual/tooling/continuous-integration.md) pins:
+- **Run the linters before finishing** — there is no NPM-script wrapper, so invoke them directly with the versions [Continuous Integration](docs/developer-manual/tooling/continuous-integration.md) pins:
 
   ```shell
   dprint check "**/*"
@@ -41,6 +41,7 @@ Start from [docs/developer-manual/architecture/overview.md](docs/developer-manua
 
 - **Repository layout, the solution, the projects** → [docs/developer-manual/architecture/](docs/developer-manual/architecture/overview.md).
 - **C# source code** → [docs/developer-manual/conventions/csharp-style.md](docs/developer-manual/conventions/csharp-style.md).
+- **Installing the SDK, Node.js, or the editor before working on the project** → [docs/developer-manual/tooling/developer-setup.md](docs/developer-manual/tooling/developer-setup.md).
 - **Linting, formatting, spell checking, CI, editor setup** → [docs/developer-manual/tooling/](docs/developer-manual/tooling/README.md).
 - **Markdown and documentation style** → [docs/developer-manual/conventions/markdown-style.md](docs/developer-manual/conventions/markdown-style.md).
 - **Writing commit messages** → [docs/developer-manual/conventions/commit-messages.md](docs/developer-manual/conventions/commit-messages.md).

diff --git a/README.md b/README.md
@@ -19,6 +19,10 @@ The repository is organized into a few top-level directories:
 
 ## Development
 
+### Developer Setup
+
+Building and working on CLI.NET Core requires the .NET SDK (the exact version pinned in [`global.json`](global.json)) and Node.js with NPM (used to run the linters and code formatter). Visual Studio Code is recommended, with the extensions recommended in [`.vscode/extensions.json`](.vscode/extensions.json) installed. See [Developer Setup](docs/developer-manual/tooling/developer-setup.md) for how to install and configure all of it.
+
 ### Code Formatting & Linting
 
 The project uses a set of linters and a code formatter to (1) find and correct problems in the code and (2) to consistently format all files. If you use Visual Studio Code to work on the project, all linters and the code formatter are configured to directly work in the code editor. A set of recommended extensions is included for the linters and the code formatter. The following tools are being used:
@@ -37,10 +41,6 @@ dotnet test "source/CLI.NET Core.slnx"
 
 See [the developer manual](docs/developer-manual/tooling/testing-and-code-coverage.md) for how code coverage is collected and reported.
 
-### Visual Studio Code
-
-The project maintainer uses Visual Studio Code for the development of CLI.NET Core and the configuration is committed to the repository. To allow other developers to change the local configuration when using Visual Studio Code, the [Workspace Config+](https://marketplace.visualstudio.com/items?itemName=swellaby.workspace-config-plus) extension is used to manage the workspace configuration. Instead of having a single set of configuration files (`settings.json`, `tasks.json`, and `launch.json`), the project has shared configuration files (`settings.shared.json`, `tasks.shared.json`, and `launch.shared.json`) that are checked into source control, while allowing individual developers to override specific settings in their local configuration files (`settings.local.json`, `tasks.local.json`, and `launch.local.json`). The extension automatically merges the shared and local configuration files into a single configuration file that is used by Visual Studio Code, giving the local configuration files preference when there are conflicts. The extension is included in the list of recommended extensions (`.vscode/extensions.json`) and will be recommended by Visual Studio Code when opening the repository for the first time.
-
 ## Use of AI
 
 This project is developed with the help of AI and I want to be fully transparent about that. The heart of the project — its architecture, its public API, and the implementation of its core — was and will continue to be written by hand, by me. AI is a tool that I use for the work around that core, never a substitute for it, and everything an AI produces is reviewed and, where necessary, rewritten by me before it is committed. Concretely, I use AI for the following kinds of tasks:

diff --git a/docs/developer-manual/README.md b/docs/developer-manual/README.md
@@ -5,12 +5,13 @@ This manual is for people working on the CLI.NET Core codebase itself: where thi
 1. [Architecture](architecture/README.md)
    1. [Overview](architecture/overview.md)
 2. [Tooling](tooling/README.md)
-   1. [Visual Studio Code Integration](tooling/vscode-integration.md)
-   2. [Spell Checking (CSpell)](tooling/spell-checking-cspell.md)
-   3. [MarkdownLint](tooling/linting-markdownlint.md)
-   4. [dprint](tooling/formatting-dprint.md)
-   5. [Continuous Integration](tooling/continuous-integration.md)
-   6. [Testing and Code Coverage](tooling/testing-and-code-coverage.md)
+   1. [Developer Setup](tooling/developer-setup.md)
+   2. [Visual Studio Code Integration](tooling/vscode-integration.md)
+   3. [Spell Checking (CSpell)](tooling/spell-checking-cspell.md)
+   4. [MarkdownLint](tooling/linting-markdownlint.md)
+   5. [dprint](tooling/formatting-dprint.md)
+   6. [Continuous Integration](tooling/continuous-integration.md)
+   7. [Testing and Code Coverage](tooling/testing-and-code-coverage.md)
 3. [Conventions](conventions/README.md)
    1. [C# Style](conventions/csharp-style.md)
    2. [Markdown Style](conventions/markdown-style.md)

diff --git a/docs/developer-manual/tooling/README.md b/docs/developer-manual/tooling/README.md
@@ -2,11 +2,12 @@
 
 This section gives an overview of the tools used for development, including code editors and IDEs, linters, and code formatters:
 
-1. [Visual Studio Code Integration](vscode-integration.md)
-2. [Spell Checking (CSpell)](spell-checking-cspell.md)
-3. [MarkdownLint](linting-markdownlint.md)
-4. [dprint](formatting-dprint.md)
-5. [Continuous Integration](continuous-integration.md)
-6. [Testing and Code Coverage](testing-and-code-coverage.md)
+1. [Developer Setup](developer-setup.md)
+2. [Visual Studio Code Integration](vscode-integration.md)
+3. [Spell Checking (CSpell)](spell-checking-cspell.md)
+4. [MarkdownLint](linting-markdownlint.md)
+5. [dprint](formatting-dprint.md)
+6. [Continuous Integration](continuous-integration.md)
+7. [Testing and Code Coverage](testing-and-code-coverage.md)
 
 The linters and the code formatter are not installed as project dependencies (there is no Node.js package manifest in this repository) — they are run directly from the command line, either installed globally or invoked on demand through `npx`. [Continuous Integration](continuous-integration.md) installs pinned versions of all three explicitly; running them locally with the same versions keeps results consistent with what CI reports. The test project and its tools are the exception: they are restored the normal .NET way, as `PackageReference`s and a local tool manifest (see [Testing and Code Coverage](testing-and-code-coverage.md)).
diff --git a/docs/developer-manual/tooling/developer-setup.md b/docs/developer-manual/tooling/developer-setup.md
@@ -0,0 +1,48 @@
+# Developer Setup
+
+This article covers what to install before building, testing, linting, or formatting CLI.NET Core locally.
+
+## .NET SDK
+
+Install the exact .NET SDK version pinned in [`global.json`](../../../global.json) (currently `10.0.300`) from the [.NET downloads page](https://dotnet.microsoft.com/download). `global.json` sets `rollForward` to `disable`, so a mismatched version fails outright rather than silently substituting a different one — see [Dependency Management](../conventions/dependency-management.md).
+
+Once the SDK is installed, restore the pinned local `dotnet` tools declared in [`.config/dotnet-tools.json`](../../../.config/dotnet-tools.json):
+
+```shell
+dotnet tool restore
+```
+
+This currently installs [ReportGenerator](https://github.com/danielpalme/ReportGenerator), used to turn raw code coverage output into an HTML report (see [Testing and Code Coverage](testing-and-code-coverage.md)).
+
+## Node.js and NPM
+
+[dprint](formatting-dprint.md), [CSpell](spell-checking-cspell.md), and [MarkdownLint](linting-markdownlint.md) are not installed as project dependencies (there is no Node.js package manifest in this repository) — install [Node.js](https://nodejs.org) (which bundles NPM), then:
+
+- Install dprint globally, pinned to the version [Continuous Integration](continuous-integration.md) uses:
+
+  ```shell
+  npm install --global dprint@0.55.1
+  ```
+
+  A persistent install is required here, not just for the `dprint check "**/*"` and `dprint fmt` commands, but because the Visual Studio Code dprint extension has no formatting engine of its own — it calls the `dprint` executable on the machine directly (see [Visual Studio Code Integration](vscode-integration.md)).
+- CSpell and MarkdownLint-cli2 do not need a persistent install — run them on demand through `npx`, pinned to the versions CI uses:
+
+  ```shell
+  npx --yes cspell@10.0.1 lint --config tests/linters/.cspell.json --no-progress "**/*"
+  npx --yes markdownlint-cli2@0.23.0 --config tests/linters/.markdownlint.yml "**/*.md" "#**/bin/**" "#**/obj/**"
+  ```
+
+  `npx` downloads and caches the pinned version the first time it runs, so a local pass reliably predicts a green CI run. Their Visual Studio Code extensions bundle their own engines, so no global install is needed for editor integration either.
+
+## Visual Studio Code
+
+Visual Studio Code is recommended, though not required, to work on CLI.NET Core. When first opening the repository, Visual Studio Code offers to install the extensions recommended in [`.vscode/extensions.json`](../../../.vscode/extensions.json) — install all of them.
+
+One of those, [Workspace Config Plus](https://marketplace.visualstudio.com/items?itemName=swellaby.workspace-config-plus), is not optional in practice: this project splits editor configuration into a checked-in `settings.shared.json` and a per-developer, git-ignored `settings.local.json`, and Workspace Config Plus is what merges the two into the `settings.json` Visual Studio Code actually reads. Without it installed, no `settings.json` is generated at all, so none of the shared configuration takes effect — format-on-save with dprint, the C# solution path, and the CSpell and MarkdownLint integrations all silently do nothing. See [Visual Studio Code Integration](vscode-integration.md) for the full shared/local mechanism and what each setting does.
+
+## Related
+
+- [Visual Studio Code Integration](vscode-integration.md) — the shared/local settings mechanism Workspace Config Plus enables.
+- [Continuous Integration](continuous-integration.md) — the pinned tool versions to match locally.
+- [Dependency Management](../conventions/dependency-management.md) — how the SDK, local tool, and NuGet package versions are kept exact.
+- [Testing and Code Coverage](testing-and-code-coverage.md) — running the tests and collecting coverage once the SDK is installed.