Release prep: bump to v0.2 + refresh docs (#807) (#838)

* chore: bump version base to 0.2 (#807)

Bump nbgv version base from 0.1 to 0.2 for the v0.2 release line.
The commit-height patch component is still derived by Nerdbank.GitVersioning
from the Git commit and the orchestrator will tag v0.2.<patch> on main
after this PR merges.

Refs #807, #706

* docs: refresh release notes, diagnostics catalogue, tutorials for v0.2 (#807)

Doc sweep for the v0.2 release line:

- Cut the `Unreleased` block in release-notes.md into a dated `0.2`
  section. Add a `Highlights` summary covering the Oats-sweep themes
  (ADR-0070..0104), the legacy-spelling removals with their migration
  diagnostics, native-interop end-to-end, the Go-flavored opt-in import,
  and tooling polish (LSP async-shaped completions, nil quick fixes,
  null->nil did-you-mean).
- Update the version-base paragraph to point at `0.2`.
- Add diagnostics-page sections for previously-undocumented v0.2 IDs:
  GS0285-GS0287 (top-level statements), GS0288 (field var/let),
  GS0289-GS0292 (deinit), GS0293-GS0295 (labeled break/continue), and
  GS0365 (variadic slot in anonymous function-type clause must be a
  slice). Extend the existing GS0363/GS0364 section to cover ADR-0102.
- Tutorials: drop the stale "this is the v0.1 design" comment in
  control-flow.md.

Refs #807, #706

* docs(website): rotate versioned snapshot from 0.1 to 0.2 (#807)

Snapshot the live docs as the new `version-0.2` set (created with
`npm run docusaurus -- docs:version 0.2`) and retire the `version-0.1`
snapshot. Update versions.json so the docusaurus version dropdown lists
only `0.2` and `Next`. The 0.1 URL space is no longer served.

Verified `npm ci && npm run build` succeeds with no broken links and
no warnings.

Refs #807, #706

---------

Co-authored-by: Copilot CLI <noreply@github.com>

Author: DavidObando

version.json

@@ -4,7 +4,7 @@
     // Specifies the Major and Minor product version. The build number is automatically appended
     // to this as the 3rd part of the product version. Increment the Major product version for
     // major product milestones. Optionally increment the Minor product version for minor milestones.
-    "version": "0.1",
+    "version": "0.2",
 
     "publicReleaseRefSpec": [
       "^refs/heads/main$", // we release out of main

website/docs/ref/diagnostics.md

@@ -452,6 +452,61 @@ Cause/fix examples:
 - **GS0296** — `let s = "hi"; if let v = s { ... }`. Fix: either use a plain `let v = s` (no narrowing) or pass a nullable value. The binding only makes sense when the RHS has type `T?`.
 - **GS0297** — `guard let v = s else { var x = 1 }`. Fix: make the else block exit the enclosing scope — `return`, `throw`, `break`, or `continue`. The binding is only in scope after the guard precisely because the else cannot fall through.
 
+## Top-level-statement diagnostics (GS0285–GS0287)
+
+ADR-0066 (top-level statements). The three diagnostics below cover
+the project-shape / placement / return-shape rules that the synthesized
+entry point depends on.
+
+| Code | Severity | Message |
+|------|----------|---------|
+| GS0285 | Error | Top-level statements are not allowed in a library project. Set `<OutputType>Exe</OutputType>` on the project, or move the statements into an explicit `func Main()`. |
+| GS0286 | Warning | Top-level statements should form a single contiguous block within a file — interleaving them with type or function declarations is hard to read. |
+| GS0287 | Error | Top-level statements mix bare `return;` and `return <expr>;`. Choose one return shape so the synthesized entry point has a single return type. |
+
+## Field declaration `var` / `let` requirement (GS0288)
+
+ADR-0067. Field declarations inside a `struct`, `class`, or `shared`
+block must carry a leading `var` (mutable) or `let` (read-only)
+keyword. The keyword distinguishes mutable from read-only storage and
+keeps type bodies visually consistent with property, event, and method
+members.
+
+| Code | Severity | Message |
+|------|----------|---------|
+| GS0288 | Error | Field declarations require a `var` (mutable) or `let` (read-only) keyword. |
+
+Cause/fix — `struct Point { x int32; y int32 }` → `struct Point { var x int32; var y int32 }` (or `let` for read-only). The parser recovers by treating the field as `var`, but the error still fires.
+
+## `deinit` (finalizer) diagnostics (GS0289–GS0292)
+
+ADR-0068 / issue #698 — `deinit { … }` declares a CLR finalizer on a
+class. The diagnostics below cover the placement and shape rules.
+
+| Code | Severity | Message |
+|------|----------|---------|
+| GS0289 | Error | `deinit` is only valid on a class type — `<type>` is a `<kind>`. |
+| GS0290 | Error | Class `<name>` declares more than one `deinit`; only the first declaration emits a finalizer. |
+| GS0291 | Error | `deinit` may not declare parameters — the CLR invokes the destructor with no arguments. |
+| GS0292 | Error | `deinit` may not declare a return type — the CLR finalizer always returns void. |
+
+## Labeled `break` / `continue` diagnostics (GS0293–GS0295)
+
+ADR-0070 / issue #707 — labeled loops and `break label` / `continue
+label` targeting an enclosing loop by name.
+
+| Code | Severity | Message |
+|------|----------|---------|
+| GS0293 | Error | No enclosing loop is labeled `<label>` (in `break <label>` / `continue <label>`). |
+| GS0294 | Error | Label `<label>` can only be applied to a loop statement (`for` / `while` / `do-while`). |
+| GS0295 | Warning | Label `<label>` shadows an enclosing loop label of the same name; the inner label wins for nested `break` / `continue`. |
+
+Cause/fix:
+
+- **GS0293** — typo or stale name; spell the label exactly as it appears on the enclosing loop.
+- **GS0294** — label-prefixes only attach to the three loop forms; remove the prefix on `if`/`switch`/etc.
+- **GS0295** — rename the inner label so the two are distinguishable, or accept the inner-wins semantics.
+
 ## If-expression diagnostics (GS0276–GS0277)
 
 ADR-0064 generalises `if` so that it can sit in value position (`let x = if cond { a } else { b }`). The diagnostics below guard the two binder rejection paths that are unique to the expression form; the branch-type-mismatch case reuses GS0263 (shared with the ADR-0062 ternary).
@@ -1400,26 +1455,35 @@ Cross-references:
 - ADR-0087 — reified generics (`initobj T` for unconstrained `T`).
 - Issues #795 (this feature), #792 (dogfooded `Optional`/`Sequences` port), #706 (parent tracker).
 
-## Variadic-parameter diagnostics (GS0363, GS0364)
+## Variadic-parameter diagnostics (GS0363, GS0364, GS0365)
 
-ADR-0101 / issue #799. The canonical G# spelling for a variadic
-parameter is `name ...T` (Go-style: the ellipsis sits between the
-parameter identifier and the element type); inside the body the
-parameter has type `[]T`. A signature may declare **at most one**
-variadic parameter and it must be the **last** parameter
-(see `GS0145` above). Variadic declarations are accepted only on
-top-level `func` declarations in this ADR; other declaration sites
-report `GS0146` (see above).
+ADR-0101 (`...T` parameters) and ADR-0102 (variadic slot in anonymous
+function-type clauses) / issues #799, #818. The canonical G# spelling
+for a variadic parameter is `name ...T` (Go-style: the ellipsis sits
+between the parameter identifier and the element type); inside the
+body the parameter has type `[]T`. A signature may declare **at most
+one** variadic parameter and it must be the **last** parameter
+(see `GS0145` above). Variadic declarations are accepted on top-level
+`func` declarations and on anonymous function-type clauses of the
+shape `(T1, ...T2) -> R`; other declaration sites report `GS0146`
+(see above).
 
 | Code | Severity | Message |
 |----|----------|-------------|
 | GS0363 | Error | The C# `params` keyword is not supported in G#. Use the canonical variadic spelling `name ...T` (Go-style); inside the function body the parameter has type `[]T`. |
 | GS0364 | Error | A function signature may declare at most one variadic parameter. |
+| GS0365 | Error | A variadic parameter slot in an anonymous function-type clause must use the slice form `[]T`; got `<typeName>`. |
 
 Cause/fix:
 
 - **GS0363 — `params` keyword.** Replace `params values []T` with `values ...T`. The lowering and call-site behaviour are identical; this is purely a spelling decision (ADR-0101 §"Structural rules" explains why the alias was rejected).
 - **GS0364 — multiple variadic parameters.** Pick the one parameter that should accept the parameter pack and drop the `...` from the others. The remaining variadic must be the last parameter (`GS0145`).
+- **GS0365 — variadic slot in `(...)-> R` is not a slice.** In an
+  anonymous function-type clause the `...` marker turns the parameter
+  slot into a pack/passthrough call site, so the slot's element type
+  must be a slice. Spell it `(...[]T) -> R`, not `(...T) -> R`. The
+  body-side spelling on a real declaration (`func f(values ...T)`) is
+  unchanged.
 
 Caller-side semantics — the binder packs trailing positional arguments
 into a fresh `[]T` array; if the caller supplies exactly one trailing
@@ -1431,9 +1495,10 @@ VB consumers see it as `params T[]`.
 Cross-references:
 
 - ADR-0101 — variadic (`...T`) parameter declarations.
+- ADR-0102 — variadic slot in anonymous function-type clauses.
 - ADR-0084 — slice type `[]T` (the body-visible type of a variadic parameter).
 - ADR-0063 — overload resolution & generic inference.
-- Issues #799 (this feature), #792 (dogfooded `Optional`/`Sequences` port), #706 (parent tracker).
+- Issues #799, #818 (these features), #792 (dogfooded `Optional`/`Sequences` port), #706 (parent tracker).
 
 
 ## Map type-clause spelling removal (GS0366)

website/docs/release-notes.md

@@ -5,11 +5,91 @@ draft: false
 
 # Release notes
 
-G# is pre-1.0. The repository's version base is currently `0.1`, and product versions are derived by Nerdbank.GitVersioning from that base and the Git commit. Until the project reaches a stable compatibility promise, release notes should be read as implementation status notes rather than a long-term compatibility contract.
-
-## Unreleased
-
-The G# compiler, language server, and VS Code extension absorbed a large stack of additions this cycle. The summary below groups them by area; each item links to the design decision (ADR) or implementation reference.
+G# is pre-1.0. The repository's version base is currently `0.2`, and product versions are derived by Nerdbank.GitVersioning from that base and the Git commit. Until the project reaches a stable compatibility promise, release notes should be read as implementation status notes rather than a long-term compatibility contract.
+
+## 0.2
+
+The second pre-1.0 line ("Oats" sweep, parent epic #706). v0.2 is a
+syntax-and-ergonomics release: the parser, binder, and emitter all
+absorbed substantial additions, several legacy Go-flavored spellings
+were retired in favour of canonical G# forms, and the native-interop
+and default-interface-method surfaces shipped end-to-end. This release
+also formally introduces docs versioning — the `0.1` snapshot is
+removed and a fresh `0.2` snapshot is cut from the live docs.
+
+### Highlights
+
+- **New language surface.** `while` / `do…while` + labeled
+  `break`/`continue` ([ADR-0070](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0070-while-do-loops-and-labeled-break-continue.md)),
+  `if let` / `guard let` smart-cast bindings ([ADR-0071](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0071-if-let-guard-let-bindings.md)),
+  null-coalescing compound assignment `??=` ([ADR-0072](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0072-null-coalescing-compound-assignment.md)),
+  null-conditional indexing `a?[i]` ([ADR-0073](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0073-null-conditional-indexing.md)),
+  arrow lambdas `x => body` ([ADR-0074](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0074-arrow-lambda-expressions.md)),
+  the canonical `(T1, T2) -> R` function-type clause ([ADR-0075](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0075-function-type-clause-arrow-syntax.md)),
+  lambda binding-type inference ([ADR-0076](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0076-lambda-binding-type-inference.md)),
+  Kotlin/Swift-style type-declaration grammar ([ADR-0078](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0078-kotlin-swift-style-type-declarations.md)),
+  if-as-expression finished ([ADR-0064](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0064-if-expression.md), issue #711),
+  smart-cast extensions (ADR-0069 addendum), discriminated-union
+  enum payloads (issue #725), `default(T)` and target-typed bare
+  `default` ([ADR-0100](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0100-default-expression.md)),
+  variadic `...T` parameters ([ADR-0101](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0101-variadic-parameters.md)) including
+  the variadic slot inside anonymous function-type clauses
+  ([ADR-0102](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0102-variadic-anonymous-function-type-clause.md))
+  and at every declaration site ([ADR-0103](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0103-variadic-all-declaration-sites.md)),
+  `class` / `struct` / `new()` constraint flag spellings
+  ([ADR-0097](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0097-class-struct-new-constraints.md)),
+  default-interface methods ([ADR-0085](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0085-default-interface-methods.md),
+  [ADR-0089](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0089-default-interface-methods-static-virtual.md),
+  [ADR-0090](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0090-default-interface-methods-private-helpers.md),
+  [ADR-0091](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0091-default-interface-methods-explicit-base.md)),
+  reified generics ([ADR-0087](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0087-reified-generics.md) R1–R7),
+  `Gsharp.Extensions.Optional` and `Gsharp.Extensions.Sequences`
+  ([ADR-0084](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0084-extensions-optional-sequences.md)),
+  friendly numeric type aliases ([ADR-0098](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0098-friendly-numeric-type-aliases.md)),
+  and the canonical map type clause `map[K,V]`
+  ([ADR-0104](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0104-map-type-clause-canonical-spelling.md)).
+- **Removals (breaking).** Five legacy spellings were retired this
+  cycle. The lexer / parser still recognise each shape long enough to
+  emit a focused span-accurate diagnostic with the canonical
+  replacement, so IDE quick-fixes can patch in one edit:
+  - `type` keyword for type declarations (`type Foo struct { … }` →
+    `struct Foo { … }`) — [ADR-0078](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0078-kotlin-swift-style-type-declarations.md).
+  - `record` keyword (use `data class` or `data struct`) — ADR-0078.
+  - `:=` short variable declaration (use `let` / `var`) —
+    [ADR-0077](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0077-drop-colon-equals-short-variable-declaration.md), `GS0305`.
+  - `name = value` named-argument separator (use `name: value`)
+    deprecated this release —
+    [ADR-0080](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0080-deprecate-equals-named-arguments.md), `GS0315`.
+  - `func(T) R` legacy function-type clause (use `(T) -> R`)
+    deprecated this release —
+    [ADR-0075](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0075-function-type-clause-arrow-syntax.md), `GS0303`.
+  - Go-flavored `map[K]V` type clause (use `map[K,V]`) — ADR-0104, `GS0366`.
+- **Native interop end-to-end.** P/Invoke via `@DllImport`
+  ([ADR-0086](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0086-pinvoke-dllimport.md)),
+  source-generator-shaped `@LibraryImport`
+  ([ADR-0092](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0092-pinvoke-libraryimport.md)),
+  struct/class marshalling
+  ([ADR-0093](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0093-pinvoke-struct-marshalling.md)),
+  `ref` / `out` / `in` parameter marshalling
+  ([ADR-0094](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0094-pinvoke-ref-out-in.md)),
+  function-pointer marshalling
+  ([ADR-0095](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0095-pinvoke-function-pointers.md)),
+  and `@MarshalAs` parameter overrides
+  ([ADR-0096](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0096-pinvoke-marshalas-parameter-overrides.md)).
+- **Go-flavored concurrency moved behind an opt-in import.** `go`,
+  `chan`, `select`, channel send/receive, `make(chan T)` and the
+  built-ins `len`, `cap`, `append`, `make`, `delete` now require
+  `import Gsharp.Extensions.Go` ([ADR-0082](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0082-go-concurrency-extensions.md),
+  [ADR-0083](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0083-go-builtins-extensions.md)).
+  Diagnostics `GS0316` / `GS0317` point at the missing import.
+- **Tooling polish.** LSP completion polish for async-shaped types
+  (`async (T) -> R`, `async sequence[T]`) (#713); nil-related quick
+  fixes from `textDocument/codeAction` ([ADR-0099](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0099-lsp-nil-quick-fixes.md));
+  `null` → `nil` "did you mean" diagnostic
+  ([ADR-0081](https://github.com/DavidObando/gsharp/blob/main/docs/adr/0081-null-to-nil-did-you-mean.md), `GS0273`).
+- **Diagnostics catalogue extended.** v0.2 introduces GS0273,
+  GS0288–GS0366. The [Diagnostics reference](./ref/diagnostics.md)
+  has the per-ID cause/fix detail.
 
 ### Added
 
@@ -35,6 +115,7 @@ The G# compiler, language server, and VS Code extension absorbed a large stack o
 - The website spec, feature matrix, FAQ, bridges page, guide pages, and design-decisions index were refreshed to match the compiler ground truth — most visibly, "Parameters do not have default-value syntax" and "Named arguments — Partial" are no longer correct and were rewritten.
 - The repo `docs/lexical.md` block-comment paragraph (which incorrectly claimed block comments were not implemented) is corrected, and a documentation-comments subsection was added.
 - The VS Code TextMate grammar adds the missing contextual keywords (`data`, `inline`, `record`, `delegate`, `event`, `prop`, `init`, `shared`, `scoped`, accessor names `get`/`set`/`add`/`remove`/`raise`, ref-kinds `ref`/`out`), operators (`:=`, `?.`, `??`, `?`/`:`, `!!`, `...`, `=>`), an `@Annotation` scope, and a `///` documentation-comment scope with `@tag` highlighting. The VS Code snippet set was rewritten to match current grammar.
+- The Docusaurus site cuts a new `0.2` snapshot from the live docs and retires the `0.1` snapshot. The version dropdown lists `0.2` and `Next`; the `0.1` URL space is no longer served.
 
 ### Fixed
 

website/docs/tutorials/control-flow.md

@@ -22,11 +22,9 @@ header when you need init and post clauses:
 
 ```gsharp title="Loop.gs"
 // file: Loop.gs
-// Demonstrates statements added across Phases 1 and 2: implicit
-// `import System` (Phase 1.5), string interpolation (Phase 1.1),
-// the C-style `for init; cond; post { … }` clause form (Phase 2.4),
-// and the `i--` decrement statement (Phase 2.2). This is the v0.1
-// design — see `design/Gsharp-design-v0.1.md` and ADR-0010.
+// Demonstrates implicit `import System`, string interpolation,
+// the C-style `for init; cond; post { … }` clause form, and
+// the `i--` decrement statement.
 
 package GSharp.Example.Loop