docs(releases): add Releases section with curated v9.0.0 release notes (#1702)

Adds a per-version release-notes section to the docs site for third-party
developers. One page per release train version (all @objectstack/* packages
are changesets-fixed), covering both the framework packages and the Console
UI delta (derived from the .objectui-sha pin range).

- content/docs/releases/v9.mdx — v9.0.0 notes: breaking changes with
  migration tables (ADR-0021 single-form cutover, ChartTypeSchema trim,
  OS_* settings env vars, @object-ui/plugin-workflow removal), framework
  and Console features, fixes, upgrade checklist.
- content/docs/releases/index.mdx — section overview, versioning policy,
  pointers to per-package changelogs and ADRs.
- scripts/collect-release-notes.sh — collects the raw material for the next
  release page: changesets consumed in a tag range plus the objectui commit
  range between the .objectui-sha pins.

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

Author: os-zhuang

content/docs/meta.json

@@ -7,6 +7,8 @@
     "---",
     "protocol",
     "---",
-    "references"
+    "references",
+    "---",
+    "releases"
   ]
 }

content/docs/releases/index.mdx

@@ -0,0 +1,39 @@
+---
+title: Overview
+description: Release notes for the ObjectStack platform — framework packages and the Console UI, summarized per version for app and plugin developers.
+---
+
+ObjectStack ships as a single release train: all `@objectstack/*` packages are
+version-locked, so one version number describes the whole platform. The
+Console UI (built from the [objectui](https://github.com/objectstack-ai/objectui)
+repository) is frozen into `@objectstack/console` at release time, so each
+release note here also covers what changed in Studio/Console.
+
+Each release page is written for **third-party developers** building apps,
+plugins, or clients on ObjectStack. It leads with breaking changes and
+migration steps, then covers new capabilities and notable fixes.
+
+## Versions
+
+- [v9.0.0](/docs/releases/v9) — Analytics single-form cutover (ADR-0021), honest chart taxonomy, canonical `OS_*` settings env vars, Google sign-in, AI build experience.
+
+## Where the fine-grained changelogs live
+
+These pages are curated summaries. For exhaustive, per-package detail:
+
+- **Framework packages** — every package ships a `CHANGELOG.md` generated from
+  [changesets](https://github.com/changesets/changesets), visible on npm and in
+  the [framework repository](https://github.com/objectstack-ai/framework).
+- **Console UI** — the [objectui CHANGELOG](https://github.com/objectstack-ai/objectui/blob/main/CHANGELOG.md)
+  follows Keep a Changelog.
+- **Design decisions** — breaking changes reference their
+  [ADRs](https://github.com/objectstack-ai/framework/tree/main/docs/adr), which
+  record the rationale.
+
+## Versioning policy
+
+ObjectStack follows [Semantic Versioning](https://semver.org). A **major**
+release may remove or change schemas in `@objectstack/spec`, public APIs, CLI
+flags, or environment variables — always with a migration path documented in
+the release notes. **Minor** releases add capabilities without breaking
+existing metadata or code. **Patch** releases fix bugs.

content/docs/releases/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Releases",
+  "pages": ["index", "v9"]
+}

content/docs/releases/v9.mdx

@@ -0,0 +1,168 @@
+---
+title: v9.0.0
+description: Analytics single-form cutover (ADR-0021), honest chart taxonomy, canonical OS_* settings env vars, Google sign-in, and a smarter AI build experience in Console.
+---
+
+**Released June 10, 2026.** All `@objectstack/*` packages are published at 9.0.0. This is a major
+release: the analytics authoring surface completes its cutover to the dataset
+semantic layer, the chart taxonomy is trimmed to what actually renders, and
+settings environment variables move to their canonical `OS_*` form.
+
+**TL;DR for upgraders:** if your app defines dashboards, reports, or list
+charts with inline queries (`object` + `aggregate` + field names), you must
+migrate them to named datasets. If you configure settings via environment
+variables, rename them to `OS_<NAMESPACE>_<KEY>`. Everything else is additive.
+
+## Breaking changes
+
+### 1. Analytics single-form cutover — datasets are now required (ADR-0021)
+
+The inline analytics author surface is removed from `@objectstack/spec`. Every
+dashboard widget, report, and list chart must now bind a semantic **dataset**
+and select dimensions/measures **by name**. Define a metric once, reference it
+everywhere.
+
+Removed from the spec:
+
+| Schema | Removed properties | Now required |
+|:---|:---|:---|
+| `DashboardWidget` | `object`, `categoryField`, `categoryGranularity`, `valueField`, `aggregate`, `measures` (and the `WidgetMeasure` type) | `dataset` + `values` |
+| `Report` | top-level and joined-block `objectName`, `columns`, `groupingsDown`, `groupingsAcross`, `filter` | `dataset` + `values` (`rows` are the dimensions) |
+| `ListChart` | `xAxisField`, `yAxisFields`, `aggregation`, `groupByField` | `dataset` + `values` |
+
+**Migration:**
+
+1. For each inline query, create a dataset with `defineDataset(...)` declaring
+   its dimensions and measures. See the
+   [Analytics Datasets guide](/docs/guides/analytics-datasets).
+2. Point the widget/report/chart at it: `dataset: "<name>"`, pick `values`
+   (measure names) and `dimensions`/`rows` (dimension names).
+3. Presentation-scope filtering goes through the widget's `filter`, which is
+   applied as the dataset's `runtimeFilter`.
+4. A flat record listing (the former `tabular` report or inline list) is not an
+   analytics dataset — model it as an object-bound **ListView** (ADR-0017).
+
+> Rationale: [ADR-0021 — Analytics: one semantic dataset layer](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0021-analytics-dataset-semantic-layer.md)
+
+### 2. `ChartTypeSchema` trimmed to distinctly-renderable families
+
+Eight chart types that only ever rendered as their base chart are removed, so
+the taxonomy no longer advertises variants the renderer doesn't draw. Update
+any widget or series using a removed type to its base:
+
+| Removed type | Use instead |
+|:---|:---|
+| `grouped-bar`, `stacked-bar`, `bi-polar-bar` | `bar` |
+| `stacked-area` | `area` |
+| `step-line`, `spline` | `line` |
+| `pyramid` | `funnel` |
+| `bubble` | `scatter` |
+
+Kept: `bar` / `horizontal-bar` / `column`, `line` / `area`, `pie` / `donut` /
+`funnel`, `scatter`, `treemap` / `sankey`, `radar`, `table` / `pivot`, and the
+single-value performance family (`metric` / `kpi` / `gauge` / `solid-gauge` /
+`bullet`). Removed variants can return behind an opt-in renderer once a real
+renderer and data model back them.
+
+### 3. Settings env overrides: canonical `OS_<NAMESPACE>_<KEY>` only
+
+`@objectstack/service-settings` no longer accepts unprefixed aliases for
+settings-namespace environment overrides. Rename your deployment variables:
+
+| Before | After |
+|:---|:---|
+| `AI_OPENAI_BASE_URL` (or `ai.openai_base_url`) | `OS_AI_OPENAI_BASE_URL` |
+| `FEATURE_FLAGS_AI_ENABLED` | `OS_FEATURE_FLAGS_AI_ENABLED` |
+
+The general rule: `OS_` + namespace + key, upper-snake-cased. See the
+[Environment Variables guide](/docs/guides/environment-variables).
+
+### 4. `@object-ui/plugin-workflow` removed
+
+The package authored BPMN-style workflow shapes the ObjectStack automation
+engine does not execute (ADR-0020, ADR-0031). If you imported it in a custom
+UI, the replacements ship already: flow authoring is the metadata-admin
+`FlowCanvas` (engine-registry-driven palette) in `@object-ui/app-shell`, run
+history is `FlowRunsPanel`, and approval UI comes from the framework's
+`@objectstack/plugin-approvals`.
+
+## New in the framework
+
+### Analytics results are now presentation-ready
+
+Three `@objectstack/service-analytics` improvements make charts and reports
+human-readable with no frontend work:
+
+- **Dimension display labels.** A `select` dimension shows its option label
+  (`Backlog`, not `backlog`); a `lookup`/`master_detail` dimension shows the
+  related record's display name instead of its foreign-key id. Resolution
+  happens server-side in `queryDataset`.
+- **Date dimensions bucket and format by granularity.** A monthly trend chart
+  now yields one point per month with sort-stable labels (`2026`, `2026-Q2`,
+  `2026-04`) — no more raw epoch milliseconds on the axis.
+- **Measure label and format travel with the result.** `AnalyticsResult.fields[]`
+  gains optional `label` and `format`, so a chart can display "Tasks" and
+  "$616,000" while keeping raw numbers for plotting.
+
+### Auth: Google sign-in and an extension hook
+
+`@objectstack/plugin-auth` binds the `auth` settings namespace to better-auth
+runtime configuration and exposes an extension hook for provider packages.
+Google sign-in works out of the box — configure it in **Setup →
+Authentication** or via deployment-level `GOOGLE_CLIENT_ID` /
+`GOOGLE_CLIENT_SECRET`. See [Auth & SSO](/docs/guides/auth-sso).
+
+### CLI: AI provider SDKs bundled
+
+The CLI now ships `@ai-sdk/openai`, `@ai-sdk/anthropic`, and `@ai-sdk/google`
+as direct dependencies. A globally-installed CLI can configure any
+OpenAI-compatible provider (DeepSeek, DashScope, SiliconFlow, OpenRouter,
+Cloudflare) without the previous "Could not build adapter for provider=…"
+failure.
+
+## New in Console (Studio)
+
+The Console build frozen into `@objectstack/console` 9.0.0 picks up the
+dataset cutover end-to-end, plus a round of AI-builder and designer
+improvements:
+
+- **Dataset widgets render as their true chart type** — pie, donut, funnel,
+  line, area, scatter, radar, treemap, sankey, table, and pivot all route to
+  their real renderer, and metric cards display the measure's label and format.
+- **Reports render the dataset form** (ADR-0021), including matrix and joined
+  variants; widget filters apply as dataset runtime filters.
+- **Flow designer aligned with the engine vocabulary**, with a runs panel for
+  inspecting executions; toolbar flow/script actions now resolve the selected
+  record correctly.
+- **Build-with-AI**: a live build tree streams progress while the agent
+  scaffolds an app, finished apps can auto-publish in chat, seed-data results
+  are surfaced, and the consumer panel no longer dumps raw tool JSON.
+- **Marketplace**: when cloud-bound, the Installed view reads the
+  control-plane's install list (ADR-0007).
+- **Forms**: conditional rules in inline grids can now reference parent-record
+  fields (`parent.<field>` scope).
+- **Pages**: `PageView` gains a console action runtime, so page-embedded
+  actions behave like their grid/detail counterparts.
+- **Charts**: crowded bar-chart x-axis labels angle and truncate instead of
+  overlapping.
+
+## Notable fixes
+
+- Publishing pending drafts by ref so package-less drafts can't get stuck in
+  the metadata-admin publish queue.
+- `FlowRunner` closes cleanly when a terminal resume fails instead of leaving
+  a dead dialog.
+- The AI service treats a stored or env-locked `provider=memory` as an explicit
+  override, while manifest defaults keep boot-time provider auto-detection
+  intact.
+
+## Upgrade checklist
+
+1. Update all `@objectstack/*` dependencies to `^9.0.0` (they are
+   version-locked — upgrade them together).
+2. Migrate inline dashboard widgets, reports, and list charts to named
+   datasets ([guide](/docs/guides/analytics-datasets)).
+3. Replace removed chart types with their base family (table above).
+4. Rename settings env vars to the `OS_<NAMESPACE>_<KEY>` form.
+5. Re-run your app's spec validation (`os validate`) — it will flag any
+   metadata still using removed properties.

scripts/collect-release-notes.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Collect the raw material for a release-notes page in content/docs/releases/.
+#
+# Aggregates, for the release between two framework refs:
+#   1. The changesets consumed by the release (full text, grouped as the
+#      per-package CHANGELOGs were generated from them).
+#   2. The objectui (Console UI) commit range, derived from the .objectui-sha
+#      pin at each ref, with feat/fix commits listed first.
+#
+# Usage:
+#   scripts/collect-release-notes.sh <prev-ref> [<new-ref>]
+#   scripts/collect-release-notes.sh "@objectstack/spec@8.0.1" "@objectstack/spec@9.0.0"
+#   scripts/collect-release-notes.sh "@objectstack/spec@9.0.0"        # new-ref defaults to HEAD
+#
+# Output is markdown on stdout — pipe it to a file and write the curated
+# release page from it:
+#   scripts/collect-release-notes.sh "@objectstack/spec@9.0.0" > /tmp/v10-material.md
+
+set -euo pipefail
+
+FRAMEWORK_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OBJECTUI_ROOT="${OBJECTUI_ROOT:-$(cd "${FRAMEWORK_ROOT}/../objectui" 2>/dev/null && pwd || true)}"
+
+PREV_REF="${1:?usage: collect-release-notes.sh <prev-ref> [<new-ref>]}"
+NEW_REF="${2:-HEAD}"
+
+cd "$FRAMEWORK_ROOT"
+
+echo "# Release material: ${PREV_REF} → ${NEW_REF}"
+echo
+
+echo "## Framework changesets consumed in this release"
+echo
+
+# Changesets deleted anywhere in the range were consumed by `changeset
+# version` for this release. (An endpoint diff would miss files added and
+# consumed within the same dev cycle, so walk the log instead.)
+consumed=$(git log --diff-filter=D --name-only --pretty=format: "${PREV_REF}".."${NEW_REF}" -- '.changeset/*.md' \
+  | grep -v 'README' | grep . | sort -u || true)
+
+if [[ -z "$consumed" ]]; then
+  echo "_None found — is ${NEW_REF} past the 'chore: version packages' commit?_"
+else
+  while IFS= read -r f; do
+    echo "### ${f}"
+    echo
+    echo '```md'
+    # The file may have been added after PREV_REF; show its last pre-deletion state.
+    git show "$(git log --diff-filter=D --pretty=%H -1 "${NEW_REF}" -- "$f")~1:$f" 2>/dev/null \
+      || git show "${PREV_REF}:${f}"
+    echo '```'
+    echo
+  done <<< "$consumed"
+fi
+
+echo "## Console UI (objectui) commit range"
+echo
+
+prev_sha=$(git show "${PREV_REF}:.objectui-sha" 2>/dev/null || true)
+new_sha=$(git show "${NEW_REF}:.objectui-sha" 2>/dev/null || cat .objectui-sha)
+
+echo "- previous pin: \`${prev_sha:-<none>}\`"
+echo "- this release: \`${new_sha}\`"
+echo
+
+if [[ -z "$prev_sha" ]]; then
+  echo "_No .objectui-sha at ${PREV_REF}; cannot compute the range._"
+elif [[ "$prev_sha" == "$new_sha" ]]; then
+  echo "_Console pin unchanged — no objectui delta in this release._"
+elif [[ -z "$OBJECTUI_ROOT" || ! -d "$OBJECTUI_ROOT/.git" ]]; then
+  echo "_objectui checkout not found (set OBJECTUI_ROOT); range is ${prev_sha}..${new_sha}_"
+else
+  echo "### feat / fix"
+  echo
+  git -C "$OBJECTUI_ROOT" log --no-merges --pretty='- %h %s' "${prev_sha}..${new_sha}" \
+    | grep -E '^- [0-9a-f]+ (feat|fix)' || echo "_none_"
+  echo
+  echo "### everything else"
+  echo
+  git -C "$OBJECTUI_ROOT" log --no-merges --pretty='- %h %s' "${prev_sha}..${new_sha}" \
+    | grep -Ev '^- [0-9a-f]+ (feat|fix)' || echo "_none_"
+fi
+
+echo
+echo "---"
+echo "_Write the curated page at content/docs/releases/, register it in"
+echo "content/docs/releases/meta.json, and link it from index.mdx._"