diff --git a/.github/ARCHITECTURE.md b/.github/ARCHITECTURE.md
index 24a6b42..03568c0 100644
--- a/.github/ARCHITECTURE.md
+++ b/.github/ARCHITECTURE.md
@@ -230,7 +230,13 @@ for f in tasks/*/task.json; do
 done
 ```
 
-GitVersion provides `minor` and `patch` as separate outputs. Task `Major` is preserved (only bumped for breaking YAML contract changes). Consumers reference tasks as `TaskName@1`.
+GitVersion provides `minor` and `patch` as separate outputs. Task `Major` is deliberately preserved: it
+is the `@N` consumers reference in YAML (`TaskName@1`), so raising it breaks every pipeline pinned to the
+old major. It is only bumped for breaking YAML contract changes, and then a copy of the previous major
+has to keep shipping alongside it.
+
+As a result the task version in the pipeline log header (`Version: 1.x.y`) is intentionally independent
+of the extension version on the Marketplace (`2.x.y`); only `Minor` and `Patch` track GitVersion.
 
 ### CI Pipeline Flow
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 804f6ed..f304230 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -126,7 +126,7 @@ The [CI workflow](.github/workflows/ci.yml) runs on every PR touching `azure-dev
 Every push to `main` automatically publishes the **dev extension** (`alcops-ado-dev`):
 
 1. GitVersion calculates the next version (e.g., `0.1.3`)
-2. Inline `jq` in the workflow stamps all `task.json` version fields (Minor + Patch)
+2. Inline `jq` in the workflow stamps all `task.json` version fields (Minor + Patch; `Major` is pinned)
 3. `tfx extension publish` pushes to the Marketplace as a private extension
 4. The extension is shared with the configured Azure DevOps org
 
diff --git a/README.md b/README.md
index 0942ae7..c03b87e 100644
--- a/README.md
+++ b/README.md
@@ -51,6 +51,11 @@ steps:
       detectFrom: "marketplace"
 ```
 
+> **Note:** Both VSIX layouts of the AL Language extension are supported from `@alcops/core` 0.2.0:
+> the flat `extension/bin/` layout used by AL 18+ (BC 29) and the legacy `extension/bin/Analyzers/` layout.
+> Compiling with AL 18 additionally requires a .NET 10 runtime on the agent, since its binaries are
+> framework-dependent `net10.0`. Installing that runtime is outside the scope of this task.
+
 ### Auto-detect from Compiler Path
 
 ```yaml
@@ -101,7 +106,7 @@ Download ALCops code analyzers with automatic TFM detection.
 | `detectUsing` | — | Input for TFM detection: BC artifact URL, local compiler path, NuGet DevTools version/channel, or VS Marketplace version. Smart routing determines the source. |
 | `detectFrom` | *(auto)* | Force a detection source: `bc-artifact`, `marketplace`, `nuget-devtools`, `compiler-path` |
 | `tfm` | — | Explicit target framework: `net8.0`, `netstandard2.1`, `net10.0`. Skips detection. |
-| `version` | `latest` | ALCops version: `latest`, `preview`, or specific (e.g., `1.2.3`) |
+| `version` | `latest` | ALCops version: `latest`, `prerelease`, or specific (e.g., `1.2.3`) |
 | `outputPath` | `$(Build.SourcesDirectory)/.alcops` | Where to place extracted analyzer DLLs |
 
 > **Note:** Either `detectUsing` or `tfm` must be provided.
@@ -115,6 +120,15 @@ Download ALCops code analyzers with automatic TFM detection.
 | `outputDir` | Full path to extracted analyzer DLLs directory |
 | `files` | Semicolon-separated list of analyzer DLL paths |
 
+#### Versioning
+
+The `@1` in `ALCopsDownloadAnalyzers@1` is the **task** major version, and the pipeline log header
+shows the task's own version (`Version: 1.x.y`). That is intentionally independent of the extension
+version on the Marketplace (`2.x.y`): every release stamps the task `Minor` and `Patch`, while `Major`
+stays at `1` because it is the number your YAML pins. It only changes on a breaking task contract
+change, which would mean updating your pipelines to `@2`. So a `Version: 1.x.y` header on a 2.x
+extension is expected, not a mismatch.
+
 ## Troubleshooting
 
 ### "A supported task execution handler was not found ... not compatible with your current operating system"
diff --git a/overview.md b/overview.md
index 301bae7..88983a3 100644
--- a/overview.md
+++ b/overview.md
@@ -19,6 +19,9 @@ steps:
       outputPath: "$(Build.SourcesDirectory)/.alcops"
 ```
 
+> **Note:** The `@1` is the task major version and is independent of the extension version shown above;
+> the `Version: 1.x.y` line in the pipeline log is the task's own version, not the extension's.
+
 ## Usage Examples
 
 ### Auto-detect from BC Artifact URL
@@ -44,6 +47,11 @@ steps:
       detectFrom: "nuget-devtools" # Optional: Defaults to BC DevTools from NuGet, set to 'marketplace' for AL Language extension from VS Code Marketplace
 ```
 
+> **Note:** With `detectFrom: marketplace`, both VSIX layouts of the AL Language extension are supported
+> from `@alcops/core` 0.2.0: the flat `extension/bin/` layout used by AL 18+ (BC 29) and the legacy
+> `extension/bin/Analyzers/` layout. Compiling with AL 18 additionally requires a .NET 10 runtime on the
+> agent, since its binaries are framework-dependent `net10.0`.
+
 ## Links
 
 - [Full documentation on GitHub](https://github.com/ALCops/azure-devops-extension)
diff --git a/package-lock.json b/package-lock.json
index f10c8e0..428f4cf 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -9,7 +9,7 @@
       "version": "0.1.0",
       "license": "MIT",
       "dependencies": {
-        "@alcops/core": "^0.1.2",
+        "@alcops/core": "^0.2.0",
         "azure-pipelines-task-lib": "^5.279.0"
       },
       "devDependencies": {
@@ -26,9 +26,9 @@
       }
     },
     "node_modules/@alcops/core": {
-      "version": "0.1.2",
-      "resolved": "https://registry.npmjs.org/@alcops/core/-/core-0.1.2.tgz",
-      "integrity": "sha512-JmkuhW5GYs8aC40bLMPQBfgylC2kYHJggR8m9A0KvlZ2Gwz/bWzCwB0kni2HSBJVf17bobII26TnPv3w8EAKQQ==",
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/@alcops/core/-/core-0.2.0.tgz",
+      "integrity": "sha512-jJtfMLHzFDKPepYElHsdVUUO2mH/j6AjXXFtXRP+TzweQKLIBQ4Mo1UEA0FI6PFfjwBH2ZcmZ61VDD8HyKlTgw==",
       "license": "MIT",
       "dependencies": {
         "fflate": "^0.8.2",
diff --git a/package.json b/package.json
index 359117a..34393a8 100644
--- a/package.json
+++ b/package.json
@@ -35,7 +35,7 @@
     "vitest": "^4.1.11"
   },
   "dependencies": {
-    "@alcops/core": "^0.1.2",
+    "@alcops/core": "^0.2.0",
     "azure-pipelines-task-lib": "^5.279.0"
   },
   "engines": {