Add the public documentation and VS Code 1.0.1 (#29)

The landing page links a guide, a shortcuts reference, and the
`.wimport` contract. Release-management now starts with what to run,
then how the pipelines work.

The VS Code extension is 1.0.1: it treats `.wimport` as Markdown and
recommends itself from the repository and from `docs/samples`.
Whiteboard VersionPrefix is unchanged.

Author: marcosqlbi

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+  "recommendations": [
+    "sqlbi.sqlbi-whiteboard"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "files.associations": {
+    "*.wimport": "markdown"
+  }
+}

README.md

@@ -107,11 +107,14 @@ running when the artwork changes.
 
 `.azure/pipelines/build-whiteboard.yaml` performs the same build in Azure Pipelines and
 signs the binaries and both MSI packages with the SQLBI certificate held in Azure Key Vault.
+What to run for a pre-release, a full release, the VS Code extension, or the site is the
+opening section of [docs/release-management.md](docs/release-management.md).
 
 ## Landing page
 
-`site/` is the landing page for <https://whiteboard.sqlbi.com>, and is self-contained: one
-HTML file plus the generated favicons and social card.
+`site/` is <https://whiteboard.sqlbi.com>: the download landing page plus the public
+guide, shortcuts, and `.wimport` contract. Styles live in `site/styles.css`. Pages are
+hand-authored HTML, not generated from this README.
 
 `.github/workflows/publish-site.yml` deploys it to GitHub Pages whenever `site/` changes on
 `main`. `site/CNAME` carries the custom domain so it survives each deployment. Asset paths
@@ -213,9 +216,9 @@ The full contract for authors and agents is [docs/wimport.md](docs/wimport.md).
 
 Plain `.md` files are not imported.
 
-A `.wboard` in the same tree opens as the embedded preview if the extension in
-`vscode/sqlbi-whiteboard` is installed. Marketplace listing is still outstanding; that
-folder's README has the local VSIX steps.
+A `.wboard` in the same tree opens as the embedded preview if
+[SQLBI Whiteboard for VS Code](https://marketplace.visualstudio.com/items?itemName=sqlbi.sqlbi-whiteboard)
+is installed. The source is `vscode/sqlbi-whiteboard`.
 
 ## Architecture
 

TODO.md

@@ -59,11 +59,12 @@ The released installer registers a Native AOT in-process thumbnail handler that
 The pre-release channel does not register `.wboard`, so it does not register the handler
 either.
 
-### 6. Preview of `.wboard` files in VS Code
+### 6. Preview of `.wboard` files in VS Code — done
 
-The extension lives in `vscode/sqlbi-whiteboard/`. It opens a `.wboard` file as the embedded
-`preview.png` rather than as an archive. Marketplace listing is still outstanding — until then
-install from a local VSIX as described in that folder's README.
+`sqlbi.sqlbi-whiteboard` on the Marketplace opens a `.wboard` file as the embedded
+`preview.png`. The source is `vscode/sqlbi-whiteboard/`. Boards without a preview show a
+short message. Bump that folder's `package.json` version to ship an update; GitHub Actions
+publishes it. The desktop installer does not carry the extension.
 
 ### 7. Video teaser
 
@@ -75,19 +76,12 @@ all need, so it sits on the critical path for all three.
 Here rather than earlier because it should show the 1.0 UI, including the configuration dialog
 and drag and drop.
 
-### 8. Documentation on whiteboard.sqlbi.com
+### 8. Documentation on whiteboard.sqlbi.com — done
 
-The site is a download page today. It needs real documentation: the tool set, containers,
-LiveView, the DAX and SQL Server text containers, the import format, and the keyboard and pen
-shortcuts. The README already carries most of this content, so the open question is whether the
-site renders from those files or keeps its own copy — decide that before writing the pages
-twice. The `.wimport` contract for authors and agents is already written in
-[docs/wimport.md](docs/wimport.md); publish that file rather than rewriting it.
-
-The pages should also spell out user stories, not only what each control does. Features that
-look small in a reference list are the ones people miss in a live session. One to write up:
-copying a LiveView and pasting it produces a bitmap of the last frame, which is how you freeze
-a screenshot onto the board during an interactive explanation without leaving the whiteboard.
+The landing page stays the download. Guide, shortcuts, and the `.wimport` contract are
+separate pages under `site/`, linked from the nav. The site is hand-authored HTML, not
+generated from the README. `docs/wimport.md` remains the in-repo contract; `site/wimport.html`
+is the same grammar for the public site.
 
 ### 9. Microsoft Store
 

docs/release-management.md

@@ -6,6 +6,33 @@ How the project is built, packaged, and shipped. The reasoning behind these choi
 Sections marked **Not yet built** describe an agreed design that does not exist in the
 repository yet.
 
+## What to run
+
+Day-to-day shipping is a merge, plus one of the GitHub Actions below when the merge is not
+enough (a retry, or a deploy that has no new commit). Pull request validation runs by
+itself. Do not run it to “release” anything.
+
+| You want to | Do this |
+| --- | --- |
+| Land a change | Open a pull request against `main`. The **Pull request** Action builds and tests; merge when it is green. |
+| Ship a Whiteboard pre-release | Merge to `main` (anything except `docs/`, `site/`, `vscode/`, and top-level markdown). Azure Pipelines **SQLBI Whiteboard** signs and publishes the GitHub prerelease. To rebuild an existing commit: Azure DevOps → that pipeline → **Run pipeline**. Do not use **Re-run**. |
+| Promote that build to a full release | Approve the **Release** stage of the same Azure run. Nothing is rebuilt. |
+| Ship a VS Code extension update | Bump `version` in `vscode/sqlbi-whiteboard/package.json` in a pull request and merge. The **Publish VS Code extension** Action publishes `sqlbi.sqlbi-whiteboard` if that version is not already on the Marketplace. To retry: Actions → **Publish VS Code extension** → **Run workflow**. |
+| Update whiteboard.sqlbi.com | Merge a change under `site/`. The **Publish site** Action deploys. To retry: Actions → **Publish site** → **Run workflow**. |
+| Rebuild brand assets | Run `scripts/build-assets.ps1` locally. Only when the artwork changes. |
+
+The three GitHub Actions live under **Actions** in this repository. Their names are
+**Pull request**, **Publish VS Code extension**, and **Publish site**. The signed
+Whiteboard pipeline is not a GitHub Action; it stays in Azure DevOps because of the
+certificate (decision 3).
+
+Version numbers are reviewed in pull requests, not typed into a pipeline UI.
+Whiteboard's version is `VersionPrefix` in `Directory.Build.props`. The VS Code
+extension's version is `version` in `vscode/sqlbi-whiteboard/package.json`. They move
+independently.
+
+---
+
 ## Day to day
 
 `main` is protected. Work on short-lived branches and merge through a pull request — the
@@ -68,42 +95,50 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build-assets.ps1
 Colours live in two places that must be changed together: the SVG, and
 `tools/AssetGenerator/Program.cs`.
 
-## Pull request validation
+---
+
+## How it works
 
-`.github/workflows/pull-request.yml` runs on every pull request against `main`:
+### GitHub Actions
+
+Three workflows in `.github/workflows/`. None of them see the EV certificate. Logs are
+public, so they must not print tokens.
+
+**Pull request** (`.github/workflows/pull-request.yml`) runs on every pull request against
+`main`, and can be started by hand if a check needs repeating:
 
 - **Build and test** — restores, builds the solution in Release, and runs the Core smoke
-  tests. `TreatWarningsAsErrors` means a warning fails it.
+  tests. A warning fails it.
 - **Build installers** — runs `scripts/build-installer.ps1` unsigned, so WiX authoring
-  errors surface here rather than at release time. The output is discarded.
+  errors surface here rather than at release time. The output is discarded. It builds a
+  diagonal pair of variants, framework-dependent, which is enough to walk every `<?if?>` in
+  the WiX source.
 - **VS Code extension** — compiles and tests `vscode/sqlbi-whiteboard` when that tree
   changed.
 
-It signs nothing and publishes nothing. Everything that touches the certificate stays in
-Azure Pipelines, because this repository is public and so are these logs (decision 3).
-
-Running on GitHub also means it works for pull requests from forks, which have no access to
-secrets and need none.
+Fork pull requests get the same jobs and no secrets.
 
-## VS Code extension publishing
+**Publish VS Code extension** (`.github/workflows/publish-vscode-extension.yml`) publishes
+`vscode/sqlbi-whiteboard` as `sqlbi.sqlbi-whiteboard`. It runs when that extension's
+`package.json` lands on `main`, and on **Run workflow**. It packages, then publishes only
+when `version` is not already on the Marketplace, so a description-only edit does not
+republish. It does not rewrite the version.
 
-`.github/workflows/publish-vscode-extension.yml` publishes `vscode/sqlbi-whiteboard` to
-the Visual Studio Marketplace as `sqlbi.sqlbi-whiteboard`. It does not touch the EV
-certificate.
+The repository secret `VSCE_PAT` is a Marketplace **Manage** personal access token with
+organization **All accessible organizations**. Create it in the Azure DevOps organization
+tied to the `sqlbi` publisher, then add it under the GitHub repo **Settings → Secrets and
+variables → Actions**. Forks never receive it.
 
-It runs on a push to `main` that changes that extension's `package.json`, and on
-**Run workflow**. It packages, then publishes only when `package.json` `version` is not
-already on the Marketplace. Bump that version in a pull request to ship; do not let CI
-rewrite it.
+**Publish site** (`.github/workflows/publish-site.yml`) deploys `site/` to GitHub Pages
+when that tree changes on `main`, and on **Run workflow**. It needs **Settings → Pages →
+Source: GitHub Actions**. `site/CNAME` carries the custom domain.
 
-The repository secret `VSCE_PAT` must be a Marketplace **Manage** personal access token
-with organization **All accessible organizations**. Create it in the Azure DevOps
-organization tied to the `sqlbi` publisher, then add it under the GitHub repo
-**Settings → Secrets and variables → Actions**.
+### Azure Pipelines
 
-## The pipeline
-
-`.azure/pipelines/build-whiteboard.yaml`, in the `SQLBI Whiteboard` Azure DevOps project.
+`.azure/pipelines/build-whiteboard.yaml`, in the `SQLBI Whiteboard` Azure DevOps project,
+is the only place that signs. A merge to `main` starts it unless the change is only
+`docs/`, `site/`, `vscode/`, `.github/`, or top-level markdown. It can also be started with
+**Run pipeline**.
 
 Parameters:
 
@@ -112,53 +147,53 @@ Parameters:
 | `verbosity` | `normal` | MSBuild verbosity |
 | `sign` | on | Code sign binaries and MSIs |
 
-Two variable groups supply its settings; both must be authorised for the pipeline before it
-can run. The signing group's contents are described in decision 1 and held by the
-maintainers.
+Two variable groups must be authorised for the pipeline. Their contents stay in Azure
+DevOps, not in this repository:
 
-The version is **not** among them: it comes from `VersionPrefix` in `Directory.Build.props`
-(decision 8). `AppVersionMajor`, `AppVersionMinor` and `AppVersionPatch` are obsolete and
-can be removed from the `SQLBI.Whiteboard` group.
+- **SQLBI-CodeSigning** — vault URL, tenant, client, secret, certificate name (decision 1).
+- **SQLBI.Whiteboard** — product settings. The version is not among them.
 
 Signing uses `AzureSignTool` against the certificate in Azure Key Vault.
 
-> **When adding a new first-party project, add its assembly to the signing step.** The
-> installer harvests new files automatically, so an unsigned assembly ships silently
-> beside a signed executable. This has already happened once.
+> **When adding a new first-party assembly, add it to the signing step.** The installer
+> harvests new files automatically, so an unsigned assembly ships silently beside a signed
+> executable. This has already happened once. The VS Code extension is not an assembly and
+> is not signed here.
+
+Stages: **Build** produces every installer variant, **PreRelease** publishes the
+pre-release channel to GitHub, **Release** is gated by approvals on the
+`whiteboard-release` environment and uploads the released-channel installers **that the
+same run already produced** (decision 9).
 
-To run it: **Run pipeline**, set parameters, **Run**. Do not use **Re-run** to pick up a
-fix — that replays the original commit.
+Creating a GitHub Release uses the `sql-bi write assets` service connection
+(`contents: write`).
 
-## Versioning
+### Versioning
 
-`VersionPrefix` in `Directory.Build.props` is the only place the product version is written.
-Everything else derives from it:
+`VersionPrefix` in `Directory.Build.props` is the only place the **desktop** product
+version is written. Everything in the installer derives from it:
 
 - assemblies are stamped `major.minor.<days since 2000-01-01>.<seconds since midnight / 2>`,
   the algorithm MSBuild and the Bravo pipeline use, so every matrix job in a run stamps the
   same number;
 - the informational version is the plain `major.minor.patch`;
 - artifact and installer file names use it directly.
 
-Releasing therefore starts with a pull request that changes one line.
+The VS Code extension does not read `VersionPrefix`.
 
-## Releasing
+### Releasing
 
-**Not yet built.** The agreed shape:
+The agreed shape, now in use for the pre-release path:
 
-1. Every push to `main` builds, signs, and publishes the pre-release channel to a GitHub
-   prerelease automatically. Pull requests build unsigned and publish nothing.
-2. A maintainer bumps the version in a pull request. Once merged, that build carries the
-   release version.
-3. Promotion is an approval on a Release stage of that run. It publishes the **already-built
-   released-channel artifacts from the same run** — nothing is rebuilt (decision 9).
+1. A maintainer bumps `VersionPrefix` in a pull request when the number should change.
+2. The merge to `main` builds, signs, and publishes the pre-release channel to a GitHub
+   prerelease.
+3. Promotion is an approval on the Release stage of **that** run. It publishes the
+   already-built released-channel artifacts — nothing is rebuilt.
 4. winget submission and the Store submission follow from the published release, in
-   parallel; neither gates the download being available.
-
-Until it exists, releasing means running the pipeline manually and uploading artifacts by
-hand.
+   parallel, once those pieces exist. Neither gates the download being available.
 
-## Still to build
+### Still to build
 
 Roughly in dependency order:
 
@@ -167,7 +202,7 @@ Roughly in dependency order:
 2. Add winget submission triggered by a published release.
 3. MSIX packaging and Store submission (decision 13).
 
-## Verification before a public release
+### Verification before a public release
 
 The build, signing, and publishing chain is proven (see above). What has **not** been done
 for a real release is everything that involves installing the result.

docs/samples/.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+  "recommendations": [
+    "sqlbi.sqlbi-whiteboard"
+  ]
+}

docs/samples/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "files.associations": {
+    "*.wimport": "markdown"
+  }
+}

docs/wimport.md

@@ -1,7 +1,7 @@
 # `.wimport` format for authors and agents
 
 Read this file before writing a `.wimport`. It is the contract SQLBI Whiteboard implements.
-The site documentation (TODO item 8) should publish this same file rather than a second copy.
+The public edition is [whiteboard.sqlbi.com/wimport.html](https://whiteboard.sqlbi.com/wimport.html). Keep the two in step.
 
 A `.wimport` file is a Markdown **recipe**. Whiteboard imports it as image and text
 containers. It is not a board file. There is no export back to `.wimport`. After import the
@@ -14,6 +14,10 @@ renderer. Associate the extension if the editor does not treat it as Markdown:
 "files.associations": { "*.wimport": "markdown" }
 ```
 
+A folder of recipes can ship that association in `.vscode/settings.json`, and recommend
+`sqlbi.sqlbi-whiteboard` in `.vscode/extensions.json` so `.wboard` files open as the
+embedded preview. This repository and `docs/samples` both do that.
+
 ## Produce this
 
 - Extension: `.wimport` (not `.md`, not `.imp`).