chore: release v0.1.1 + add release runbook (bd-yomgkxoc) (#284)

* chore: release v0.1.1 + add release runbook (bd-yomgkxoc)

Bump [workspace.package] version 0.1.0 → 0.1.1 (cargo update --workspace
regenerates only the workspace crates' lock entries; --locked build of
q2 confirms the lockfile is release-ready and --version prints
'q2 (quarto 2) 0.1.1'). v0.1.1 ships everything on origin/main through
the clippy-gate merge, plus #282 (version string) and #283
(wait_for_change MCP tool).

Also adds the release runbook we lacked:
claude-notes/instructions/release-runbook.md (+ a pointer from
CLAUDE.md). It captures the full version-bump → tag → monitor → verify
procedure and the gotchas learned in the v0.1.0 dry-run (bd-c6l13j79):
tag must equal Cargo.toml version, --locked everywhere, linux is gnu
not musl (rusty_v8 has no musl prebuilts), signing happens in the
release job (jammy lacks minisign), darwin_amd64 cross-build keyring
staging, pinned-nightly target add, version-string last-token contract.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: correct stale rusty_v8/musl notes — dependency is gone (bd-yomgkxoc)

rusty_v8 (via deno_core → quarto-system-runtime) was removed from q2
(bd-3e3sam51) before this branch, so the 'static musl is impossible
because rusty_v8 has no musl prebuilts' explanation in the release.yml
header and the new runbook is no longer true. Reword both: linux still
ships gnu today (unchanged for v0.1.1), but the musl blocker is gone
and switching is now viable future work (filed bd-dofxhzaj). The
historical dry-run log in the plan doc is left as-is — it was accurate
when written.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* test: make phase5 byte-identity baseline robust to version bumps (bd-yomgkxoc)

The single-doc byte-identity guard hashed doc.html raw, which embeds
the generator version (<meta content="quarto-rust-X.Y.Z">). The 0.1.0
→ 0.1.1 bump changed that one tag and broke the test, even though
nothing about the rendering changed — and it would break on every
future bump (we bump on a cadence now).

Normalize the embedded crate version to a placeholder before hashing
HTML artifacts (CARGO_PKG_VERSION → "VERSION"); non-HTML artifacts
(styles.css) carry no version and are hashed raw. The byte-identity
guarantee is preserved for every other byte; the baseline now absorbs
version churn and never needs re-capturing for a bump. doc.html
baseline re-captured against the normalized bytes; styles.css unchanged.

Runbook gains a note: a version bump should break no test; if one
breaks, harden it rather than re-snapshotting.

Confirmed sole failure under the bump (full --no-fail-fast workspace
run: 10039 pass, 1 fail → now 10040). clippy clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: cscheid

.github/workflows/release.yml

@@ -37,11 +37,13 @@
 #   release builds only; see crates/quarto-mcp-launcher/src/defaults.rs
 #   for why the Desktop-app client secret is safe to embed.
 # - Linux targets are gnu on the oldest available runners (glibc 2.35
-#   floor). Static musl is impossible for q2: rusty_v8 (deno_core →
-#   quarto-system-runtime) publishes no musl prebuilt archives — both
-#   musl legs 404'd in the v0.1.0 dry-run (run 27449454203). The linux
-#   legs build with `--features vendored-openssl` so the binary has no
-#   runtime libssl dependency (plan D4).
+#   floor). Static musl was originally blocked because rusty_v8
+#   (deno_core → quarto-system-runtime) shipped no musl prebuilts —
+#   both musl legs 404'd in the v0.1.0 dry-run (run 27449454203). That
+#   dependency has since been removed (bd-3e3sam51), so musl is now
+#   viable; we simply haven't switched yet (tracked separately). The
+#   linux legs build with `--features vendored-openssl` so the binary
+#   has no runtime libssl dependency (plan D4).
 #
 # Signing key: MINISIGN_SECRET_KEY repo secret; the public half is pinned
 # in install.sh (MINISIGN_PUBKEY) and README. The sign step verifies its

CLAUDE.md

@@ -470,6 +470,16 @@ xtask. Design: `claude-notes/plans/2026-06-11-q2-mcp-hub-auth.md`
 - Always verify WASM changes with the correct build command
 - Fresh clone builds require dist/ directories to exist; run full build before testing
 
+## Cutting a release
+
+To ship a signed, multi-platform `q2` binary release (the `Release`
+GitHub Actions workflow), follow the runbook:
+**`claude-notes/instructions/release-runbook.md`**. It covers the
+version-bump → tag → monitor → verify procedure and the non-obvious
+gotchas (tag must equal `Cargo.toml` version; linux is gnu not musl;
+signing happens in the release job; etc.). Do not improvise a release —
+the preflight job and `--locked` builds are unforgiving.
+
 ## Full Project Verification
 
 **IMPORTANT**: Before committing changes that affect `quarto-core`, `quarto-pandoc-types`, or other crates used by `wasm-quarto-hub-client`, run full verification:

Cargo.lock

@@ -23,7 +23,7 @@ exclude = [
 resolver = "2"
 
 [workspace.package]
-version = "0.1.0"
+version = "0.1.1"
 authors = ["Posit Software, PBC"]
 homepage = "https://github.com/posit-dev/quarto-markdown-syntax"
 keywords = ["parser"]