Chart builder: discoverable entry points — Build Chart door, dataset picker, no-datasets state

docs/spec/01-application-shell.md

@@ -82,13 +82,16 @@ The app reflects its current location in the URL hash so that reloading restores
 
 States and their hash forms:
 
-| State                       | Hash                           |
-| --------------------------- | ------------------------------ |
-| A selected snippet          | `#snippet-<id>`                |
-| Datasets manager (list)     | `#datasets`                    |
-| A specific dataset          | `#datasets/dataset-<id>`       |
-| New-dataset form            | `#datasets/new`                |
-| Chart Builder for a dataset | `#datasets/dataset-<id>/build` |
+| State                          | Hash                           |
+| ------------------------------ | ------------------------------ |
+| A selected snippet             | `#snippet-<id>`                |
+| Datasets manager (list)        | `#datasets`                    |
+| A specific dataset             | `#datasets/dataset-<id>`       |
+| New-dataset form               | `#datasets/new`                |
+| Chart Builder for a dataset    | `#datasets/dataset-<id>/build` |
+| Chart Builder, no dataset open | `#build`                       |
+
+`#build` is the Chart Builder opened with an empty dataset library (its no-datasets state). When datasets exist, an un-targeted builder open immediately lands on one (see _Chart Builder → Opening_), so the URL shows the dataset form instead.
 
 Behavior:
 

docs/spec/02-snippet-library.md

@@ -4,10 +4,14 @@ The Snippet Library is the left pane and the primary entry point to the app. A *
 
 ## The List
 
-The list shows every saved snippet and is always visible. A persistent "Create New Snippet" affordance sits at the top of the list, above all snippets, so the user can always start a new snippet regardless of scroll position.
+The list shows every saved snippet and is always visible. A persistent **creation surface** sits at the top of the list, above all snippets, so the user can always start a new chart regardless of scroll position. It offers the two ways in with a clear hierarchy:
+
+- **Build Chart** — the primary action; opens the **Chart Builder** (see _Chart Builder_), the guided no-JSON path. The builder opens on the most recently modified dataset (or its no-datasets state when the library has none) — it is not gated on first selecting a dataset.
+- **New JSON snippet** — a ghost/tertiary action beside it; creates and selects a new snippet directly in the editor (see _Snippet Operations_ → Create New), the expert path — always visible, one click, never hidden behind the guided one.
+
+When the library pane is dragged narrow, the buttons shed their labels (the long ghost label first) and keep their icons and accessible names.
 
 - The list shows all snippets, ordered newest-modified first by default (see _Sort_).
-- A "Create New Snippet" item is pinned at the top of the list; activating it creates and selects a new snippet (see _Snippet Operations_).
 - Selecting a snippet makes it the **active snippet**: it loads into the editor and preview, becomes highlighted in the list, and the URL updates to reflect the selected snippet so the state is shareable and survives a page reload (see _Application Shell & Navigation_).
 - Exactly one snippet is active at a time.
 - When no snippets match the current search, the list shows an empty-state message ("No snippets match your search", with a hint to try a different term). This is the list's only empty state: a genuinely empty library never shows the list at all (see next).
@@ -17,8 +21,9 @@ The list shows every saved snippet and is always visible. A persistent "Create N
 
 When the library is empty — on first run, or after the user deletes their last snippet — the app does **not** seed placeholder content. Instead the **onboarding canvas takes the full workspace**, replacing the pane chrome (the pane toggle strip, the library list, the editor, and the preview): with no snippets, the library's create/search/sort/storage controls and the pane toggles have nothing to act on, so the welcome gets the whole width. The user starts from a deliberate choice rather than dropped into the middle of an unfamiliar spec.
 
-- The canvas briefly identifies what Astrolabe is, then offers two ways to begin.
+- The canvas briefly identifies what Astrolabe is, then offers the ways to begin.
 - **Create your first snippet** — the primary action; starts a new snippet from the sample bar-chart template and opens it in the editor (identical to _Create New_ under _Snippet Operations_).
+- **Build a chart from your data** — the data-first door beside the primary; opens the **Chart Builder** over the canvas. With no datasets yet, the builder's no-datasets state explains itself and leads to "Add a dataset" (see _Chart Builder → Opening_) — the path never dead-ends. Opening the builder also lays the workspace out at the default split below, since creating from the builder leaves the canvas directly.
 - An **example gallery** of a few simple snippets showcasing distinct Vega-Lite capabilities (e.g. a bar chart, a time-series line, a scatter plot, a stacked area, a donut, a binned histogram). Each example shows a **live preview** of the chart and a one-line description.
   - **Add** on an example creates it as an ordinary snippet and makes it active (opening it in the editor).
   - **Add all** creates the whole set at once and makes one of them active.

docs/spec/06-chart-builder.md

@@ -6,15 +6,30 @@ The Chart Builder is a visual, no-JSON way to compose a Vega-Lite chart from a s
 
 ## Opening
 
-- Launched from a selected dataset in the _Datasets_ manager via that dataset's "build chart" action.
-- Opens as a modal dialog over the application; the URL reflects the dataset's "build" action so the open builder is shareable/restorable (see _Application Shell & Navigation_).
-- On open, the builder loads the selected dataset, displays its name, and pre-populates sensible defaults (see below). If no dataset is available, it shows a "No dataset loaded" message and offers no controls.
+The builder has several doors; the guided creation path must be visible where the intent to make a chart forms, not buried behind the data model.
+
+- **The library's creation surface** — the primary **Build Chart** action (see _Snippet Library → The List_). Opens the builder with no preselected dataset; the builder picks the **most recently modified dataset** itself.
+- **The onboarding canvas** — the data-first "Build a chart from your data" door (see _Snippet Library → First-Run & Empty Workspace_).
+- **A dataset's "Build Chart" action** in the _Datasets_ manager — the contextual shortcut; opens the builder on that dataset.
+- Opens as a modal dialog over the application; the URL reflects the loaded dataset's "build" form (or `#build` while no dataset is loaded) so the open builder is shareable/restorable (see _Application Shell & Navigation_).
+- On open, the builder loads its dataset and pre-populates sensible defaults (see below).
+
+### Dataset picker
+
+Which data the chart builds from is itself a builder choice. A **Dataset** picker sits at the top of the configuration pane, showing the loaded dataset and letting the user switch to any other without leaving the builder.
+
+- Switching while the configuration is still the untouched opening default **re-derives fresh smart defaults** for the new dataset.
+- Switching after the user has built on the configuration **rebases** it instead: chart-level intent survives (mark, title/subtitle, explicit size, sort/stack, calculated fields, expression filters), while bindings to columns the new dataset lacks are shed (encodings cleared, predicate filters dropped). A same-schema dataset — the common switch — keeps everything.
+
+### No datasets
+
+With an empty dataset library the builder shows a **no-datasets state** instead of controls: it says what the builder does and offers one primary next step — **Add a dataset**, which opens the _Datasets_ manager on its create form. The guided path never dead-ends.
 
 ## Layout
 
 A two-pane modal:
 
-- **Left — configuration:** dataset name, a **Data** section (row filters, calculated fields, and a collapsible row preview — see _Data_ below), mark type selector, a **field shelf** (the dataset's columns, field-first), a **Marks** card (the Colour and Size encodings), and a "Create Snippet" action. Chart-level properties (title/subtitle, width/height) sit on the **preview side**, under the chart (see _Chart properties_).
+- **Left — configuration:** the dataset picker, a **Data** section (row filters, calculated fields, and a collapsible row preview — see _Data_ below), mark type selector, a **field shelf** (the dataset's columns, field-first), a **Marks** card (the Colour and Size encodings), and a "Create Snippet" action. Chart-level properties (title/subtitle, width/height) sit on the **preview side**, under the chart (see _Chart properties_).
 - **Right — live preview:** the **Columns** (X) and **Rows** (Y) shelves stacked above a rendered chart that updates as the configuration changes, with a placeholder/error area. Position is a property of the chart, so its controls sit on the chart (Tableau's Columns/Rows metaphor).
 
 ## Data (preview, filters, calculated fields)