docs: document Marketplace installation and updates

README.md

@@ -6,7 +6,7 @@
 
 An open-source visual Markdown editor for VS Code. Write in a rendered view, switch to source when needed, and work with tables, code, equations, and diagrams in the same document.
 
-[Download a release](https://github.com/BinaryOutlook/binary-markdown/releases) · [Documentation](docs/README.md) · [Changelog](CHANGELOG.md) · [Report an issue](https://github.com/BinaryOutlook/binary-markdown/issues)
+[Install from Marketplace](https://marketplace.visualstudio.com/items?itemName=BinaryOutlook.binary-markdown) · [Download a VSIX](https://github.com/BinaryOutlook/binary-markdown/releases) · [Documentation](docs/README.md) · [Changelog](CHANGELOG.md) · [Report an issue](https://github.com/BinaryOutlook/binary-markdown/issues)
 
 Built on [Any Markdown by raggbal and contributors](https://github.com/raggbal/any-markdown), which provides the visual editor and much of its existing functionality under MIT. BinaryOutlook independently maintains Binary Markdown's changes, releases, and support. See [Acknowledgments](ACKNOWLEDGMENTS.md) for provenance.
 
@@ -16,10 +16,14 @@ Built on [Any Markdown by raggbal and contributors](https://github.com/raggbal/a
 
 Use local desktop VS Code **1.85.0 or later**. Validation targets Windows x86-64, macOS ARM64, and Ubuntu x86-64; each release identifies the environments actually tested. Standalone Electron installers and other editors require separate validation.
 
-1. Download the `.vsix` and its SHA-256 checksum from [GitHub Releases](https://github.com/BinaryOutlook/binary-markdown/releases), or [build from source](docs/building.md). Follow the [checksum instructions](docs/building.md#inspect-and-install-the-output) before installing.
-2. In VS Code, open **Extensions**, choose **… → Install from VSIX…**, select the package, and reload if prompted.
+1. Open **Extensions** in VS Code and search for `@id:BinaryOutlook.binary-markdown`, or open the [Visual Studio Marketplace listing](https://marketplace.visualstudio.com/items?itemName=BinaryOutlook.binary-markdown).
+2. Select **Binary Markdown Editor** by **BinaryOutlook**, choose **Install**, and reload if prompted.
 3. Open a Markdown file and choose **Reopen Editor With… → Binary Markdown**.
 
+VS Code installs Marketplace updates when automatic extension updates are enabled. If you manage updates manually, use **Extensions: Check for Extension Updates** in the Command Palette, then select **Update** for Binary Markdown. Marketplace and GitHub Releases are published separately; check the version available in your chosen channel.
+
+For offline installation or a specific GitHub release, download its `.vsix` and SHA-256 checksum from [GitHub Releases](https://github.com/BinaryOutlook/binary-markdown/releases), verify it using the [checksum instructions](docs/building.md#inspect-and-install-the-output), then use **Extensions → … → Install from VSIX…**. You can also [build from source](docs/building.md).
+
 For unreleased branch or PR work, [download an automated development VSIX](docs/building.md#download-an-automated-development-build). Check the run's validation status and retain the checksum and build-information sidecars. These temporary testing packages do not publish a Marketplace update.
 
 The extension ID is `BinaryOutlook.binary-markdown`. Installation leaves your default Markdown editor unchanged; use **Configure Default Editor…** if you want Binary Markdown to open every Markdown file. Updating this extension retains its identity and settings. For older Any Markdown or test-build IDs, follow the [migration guide](docs/migration.md).
@@ -35,7 +39,7 @@ The extension ID is `BinaryOutlook.binary-markdown`. Installation leaves your de
 - **Protection from external changes:** unsaved edits stay when another program writes the open file, with **Compare** and **Load Disk Version** choices. See [external file changes](docs/editor-guide.md#external-file-changes).
 - **Experimental export:** local HTML, PDF, Word, and EPUB conversion, with PDF/DOCX code labels, optional line counts, and optional numbering.
 
-These features describe the current source. The [changelog](CHANGELOG.md) groups changes by version; GitHub Releases establishes publication. Unset toolbar preferences use Full mode and unset export-label positions use top-left; explicit saved choices remain honored. Width starts at a centered 860 px cap, code-block action labels are shown, and export line counts and numbering are off by default.
+These features describe the current source. The [changelog](CHANGELOG.md) groups changes by version; check the Marketplace listing or GitHub Releases for availability in each channel. Unset toolbar preferences use Full mode and unset export-label positions use top-left; explicit saved choices remain honored. Width starts at a centered 860 px cap, code-block action labels are shown, and export line counts and numbering are off by default.
 
 ## Configure the editor
 

docs/README.md

@@ -1,6 +1,6 @@
 # Documentation
 
-Start here for maintained Binary Markdown guidance. These pages describe the source in this checkout; features in development are identified explicitly. For available packages and their tested scope, use [GitHub Releases](https://github.com/BinaryOutlook/binary-markdown/releases).
+Start here for maintained Binary Markdown guidance. These pages describe the source in this checkout; features in development are identified explicitly. Install through the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=BinaryOutlook.binary-markdown), or use [GitHub Releases](https://github.com/BinaryOutlook/binary-markdown/releases) for downloadable VSIX packages, source revisions, checksums and tested scope. Versions can differ between channels.
 
 | You want to… | Start with | Then read |
 | --- | --- | --- |

docs/building.md

@@ -61,7 +61,7 @@ cd ..
 
 On Linux, `sha256sum --check` is an equivalent command. A digest checks bytes, not publisher identity; obtain release artifacts and checksums from the same official release. The source stamp records commit, tree, local modifications and build runtime. Actions-built packages also record their workflow build number, run ID, attempt, ref and run URL; local or older packages explicitly report absent CI identity. **Binary Markdown: Copy Build Information** adds the running VS Code version and host architecture. An unidentified source archive reports unknown fields rather than inventing a Git revision. An archive builder may supply `BINARY_MARKDOWN_SOURCE_COMMIT` with the full source SHA, which is labelled as provided, not a verified clean checkout.
 
-Install through **Extensions → … → Install from VSIX…**, reload if prompted, then choose **Reopen Editor With… → Binary Markdown**. Local builds use `BinaryOutlook.binary-markdown`, so installing one replaces that ID's current version. Preserve the ID for routine builds. To return to an official version, install its published VSIX. Version 0.2 keeps 0.1's settings, commands and outline storage keys; migration from older Any Markdown IDs is covered [separately](migration.md).
+Install through **Extensions → … → Install from VSIX…**, reload if prompted, then choose **Reopen Editor With… → Binary Markdown**. Local builds use `BinaryOutlook.binary-markdown`, so installing one replaces that ID's current version. Preserve the ID for routine builds. To return to an official version, choose **Install Another Version…** from the extension's gear menu and select a Marketplace version, or install a published GitHub release VSIX. See [installation and updates](../README.md#install) for the two channels. Version 0.2 keeps 0.1's settings, commands and outline storage keys; migration from older Any Markdown IDs is covered [separately](migration.md).
 
 For isolated native checks, use the [guarded test harness](../test/native/export-smoke.md). It creates a fresh profile and workspace and installs the actual VSIX. It does not modify your normal VS Code settings. Source edits do not refresh an already installed package: rebuild and reinstall when testing new code.
 

docs/index.html

@@ -29,12 +29,14 @@ <h1>Binary Markdown Editor</h1>
     <p><a href="https://github.com/BinaryOutlook/binary-markdown/blob/main/docs/README.md">Documentation</a> · <a href="https://github.com/BinaryOutlook/binary-markdown">Source</a> · <a href="https://github.com/BinaryOutlook/binary-markdown/issues">Report an issue</a></p>
 
     <h2>Install a release</h2>
-    <p>Choose a package from <a href="https://github.com/BinaryOutlook/binary-markdown/releases">GitHub Releases</a>. Read that release's notes for its source revision, tested platforms and limitations, and verify its checksum before installation.</p>
+    <p>Install <a href="https://marketplace.visualstudio.com/items?itemName=BinaryOutlook.binary-markdown">Binary Markdown Editor from the Visual Studio Marketplace</a> in local desktop VS Code 1.85.0 or later.</p>
     <ol>
-      <li>Open VS Code's Extensions panel and choose <strong>Install from VSIX…</strong>.</li>
-      <li>Select the package, then open a Markdown document.</li>
-      <li>Choose <strong>Reopen Editor With… → Binary Markdown</strong>.</li>
+      <li>Open VS Code's Extensions panel and search for <code>@id:BinaryOutlook.binary-markdown</code>.</li>
+      <li>Select <strong>Binary Markdown Editor</strong> by <strong>BinaryOutlook</strong>, choose <strong>Install</strong>, and reload if prompted.</li>
+      <li>Open a Markdown document and choose <strong>Reopen Editor With… → Binary Markdown</strong>.</li>
     </ol>
+    <p>VS Code installs Marketplace updates when automatic extension updates are enabled. For manual updates, run <strong>Extensions: Check for Extension Updates</strong>, then select <strong>Update</strong> for Binary Markdown.</p>
+    <p>For offline installation or a specific version, download a VSIX and checksum from <a href="https://github.com/BinaryOutlook/binary-markdown/releases">GitHub Releases</a>, verify the checksum, and use <strong>Extensions → … → Install from VSIX…</strong>. Read the <a href="https://github.com/BinaryOutlook/binary-markdown/blob/main/README.md#install">installation guide</a> for details. Marketplace and GitHub versions can differ because publication is separate.</p>
     <p>Installation leaves your default Markdown editor unchanged. Binary Markdown uses its own extension ID, commands, settings, and editor registration.</p>
 
     <h2>Built on a capable editor</h2>

docs/migration.md

@@ -24,7 +24,7 @@ Binary Markdown 0.1.0 introduced a new installation identity. It does not overwr
 
 ## Install and select the editor
 
-Install the new VSIX using **Extensions → … → Install from VSIX…**. Open a document and choose **Reopen Editor With… → Binary Markdown**. Existing editor tabs may need to be closed and reopened.
+Install Binary Markdown from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=BinaryOutlook.binary-markdown), or install a GitHub release VSIX using **Extensions → … → Install from VSIX…**. Follow the [installation and update instructions](../README.md#install), then open a document and choose **Reopen Editor With… → Binary Markdown**. Existing editor tabs may need to be closed and reopened.
 
 The new package registers `binary-markdown.editor`, separate commands, and separate settings. It can be installed alongside Any Markdown without sharing those registrations. Its editor remains optional and does not change `workbench.editorAssociations` on installation.
 

docs/releases-and-support.md

@@ -18,11 +18,14 @@ The [repository transition](repository-transition.md) preserves the original for
 
 **Free (freedom):** Users retain the rights to run, study, modify, and redistribute the software under the applicable licenses. Other distributors may charge for copies or support while complying with those licenses. The [licensing guide](licensing.md#cost-and-software-freedom) explains the four freedoms, their GNU/FSF heritage, and AGPL obligations. Future licensing arrangements depend on the rights the project holds and do not remove these commitments.
 
-[GitHub Releases](https://github.com/BinaryOutlook/binary-markdown/releases) is the initial official download channel. Marketplace uploads are a separate manual maintainer action; these workflows do not publish there. Open VSX publication remains separate work. Source builds and VSIX installation do not require Marketplace credentials. [Build instructions](building.md) cover `main`, release tags and historical commits.
+Binary Markdown is available on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=BinaryOutlook.binary-markdown) for installation and updates through VS Code. [GitHub Releases](https://github.com/BinaryOutlook/binary-markdown/releases) provides downloadable VSIX packages with source revisions, checksums and validation records. Follow the [installation and update instructions](../README.md#install).
+
+Marketplace uploads are a separate manual maintainer action; the GitHub release workflows do not publish there. Versions can differ between the two channels, and a GitHub release does not establish Marketplace availability of that version. Open VSX publication remains separate work. Source builds and VSIX installation do not require Marketplace credentials. [Build instructions](building.md) cover `main`, release tags and historical commits.
 
 | Channel | What it means |
 | --- | --- |
-| Published release | Maintainer-published version with identified source, checksums and release validation. A prerelease is explicitly labelled. |
+| Visual Studio Marketplace | Official extension listing under `BinaryOutlook.binary-markdown`. VS Code offers published updates according to your extension update settings. |
+| GitHub release | Maintainer-published VSIX with identified source, checksums and release validation. A prerelease is explicitly labelled. |
 | CI candidate | An automatically packaged development snapshot with a source stamp and test results. Passing CI does not itself publish or approve a release. |
 | Local/community build | A build from a selected commit, possibly modified. Identify its origin and changes; do not imply maintainer validation. |
 

docs/roadmap.md

@@ -8,7 +8,7 @@ Binary Markdown aims to be a useful, free, open-source Markdown editor that user
 | Editor workspace | Visual/Source/Split views, command and insertion search, source-based Find and Replace, Outline/Document navigation, compact table tools, block diagnostics, session-only code wrapping and categorized settings | Remaining keyboard and visual acceptance, physical input and screen-reader checks |
 | Export | Saved-revision HTML/PDF/DOCX/EPUB, portable supported resources, explicit warnings, cancellation and meaningful stage progress | Unsaved export, destination/template customization, compression, richer pagination and additional Markdown syntax |
 | Identity and documentation | AGPL-3.0-or-later with retained notices, supplied 01 / MD artwork, clear build/support policy and source identification | Broader guides and community contributions as features mature |
-| Release automation | Identified branch/PR development packages, one shared candidate, four installed-VSIX lanes, nine browser shards, checksums, validation evidence and release promotion | Marketplace/Open VSX distribution and further validated environments |
+| Distribution and release automation | [Visual Studio Marketplace listing](https://marketplace.visualstudio.com/items?itemName=BinaryOutlook.binary-markdown), GitHub Releases, identified branch/PR development packages, one shared candidate, four installed-VSIX lanes, nine browser shards, checksums, validation evidence and release promotion | Open VSX publication and further validated environments |
 
 The release workload is a frozen complex report, calibrated to approximately 30 pages under reference typography. Actual PDF page counts vary with rendering and machine fonts. This is a practical content-coverage target; the product promises useful stage updates rather than a fixed completion time. Do not remove hard fixture cases or hide warnings to achieve a smaller page count.