@sanity/workflow-studio-plugin 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,165 @@
 # @sanity/workflow-studio-plugin
 
+## 0.5.0
+
+### Minor Changes
+
+- 767497c: Document reference previews render as hoverable card links: the preview card IS the edit-intent link, with hover/focus affordances instead of a static-text face. Compact row lockups (the tool's group bands) compose the chip from schema icon + live title on the row's own text metric — Studio's portable-text inline preview misaligns outside a text run — so chips center exactly with the badges and buttons beside them. The tool's document group bands step up one radius, give the collapse toggle a larger hit area, and vertically center every band item.
+- 0143226: The document form strip now shows every workflow run instead of hiding finished ones and collapsing concurrent actives. Each active instance renders its own line (definition title, current stage, its own assigned-task count — the "N active workflows" aggregate line is gone), and each workflow type whose runs have all settled keeps one line showing its latest run's terminal state (an Aborted chip for a run that never completed), with the settle time on hover; a type running again is represented by its active line instead. Clicking any line opens the Workflows view focused on that run — only its section unfurled, via a sticky pane param that survives reloads.
+- 767497c: Tool instance bands render the form strip's instance lockup — title, then the stage face with its glyph in the primary tone — and the lockup is a real link to the instance's detail view: plain clicks navigate in place (carrying the selected tab), modified clicks open the resolved route in a new tab.
+- 24b11dd: Surface the `progress` field kind: a progress field's pill wears its value as a tweened background fill with a whole-number percent caption in a reserved-width slot (at-a-glance progress that never resizes as it ticks), the tweened `ProgressBar` (from `@sanity/workflow-components`) renders on every field-value display surface — pill popovers, field rows, the activity dialog — and edits go through native 0–100 number inputs honoring declared validation bounds; the MCP authoring guide documents the kind.
+- 767497c: The Workflows tool drops its All workflows tab: the tool is Overview and For me. The instance-level filter arms that only backed that listing are gone with it.
+- 2005ab7: Terminal-action placement keys on what firing concludes: an action whose fire would exit the stage right now (the engine's `firing` consequence) joins the own-status settling actions in the dialog footer and the row's terminal cluster — no longer a quiet top-strip button. The activity detail dialog's footer also drops its Cancel button (field edits commit on their own gestures, so there was nothing to cancel — dismissal is the header X, Esc, or the overlay) and renders only when terminal actions exist.
+- 47fd2b5: Terminal actions fold into menus instead of the primary-plus-chevron split button. An activity list row with two or more actions offers one "Select action" menu listing them all; a lone action stays a plain ghost button. The activity dialog footer lays actions out inline — capped at three, and only as many as the measured footer width fits without wrapping, refitting as the dialog resizes — with the surplus behind a "More actions" menu.
+- 767497c: Workflows tool layout: the title, tabs, and the active tab's filter row are a fixed header — only the task list scrolls, with a stable scrollbar gutter so the scrollbar appearing doesn't reflow rows. Task rows indent under their instance band (the document view's stage inset) and share the bands' border radius. Header padding is uniform, with the tool title optically aligned to the tab labels; the tabs' loading rows share the same optical indent. The plugin now declares `react-dom` as a peer dependency (the header slot renders through a portal).
+- 767497c: Workflows tool: one tab strip — Overview (all tasks, default) and For me (the user's assignments) — replacing the Tasks/All workflows tabs and the nested My tasks/All tasks toggle. The selected tab now rides the tool's URL search params with the same contract as the document view's tab (default elided, unknown values read as the default), so reloads, bookmarks, and detail-view round-trips keep the tab. The "New workflow" button drops its primary tone and tightens its icon-to-label gap.
+- 767497c: Workflows tool: task rows are now the document view's shared activity row — same geometry and the same inline controls: the assignee picker and a new date chip. The Overview groups one dimension per level — a band per document, lighter collapsible bands per workflow instance under it (the title + current-stage lockup, a link to the instance's detail view; every band's affordance acts on exactly the entity it names), and the instance's activity rows below. Instances without a Studio document band bare in a trailing section. The For me segment reads the same hierarchy cut to the user's assignments, its rows carrying the inline terminal-action cluster (everything listed is yours to act on — Overview rows stay action-free); the document pane's For me tab keeps its flat list. Rendered rows pull their instances into the provider's live evaluation to drive the controls; rows hold the committed facts in the same shell until it lands.
+
+  The inline assign and date controls are state-driven so identical-looking triggers never behave differently across rows: a declared-editable field with anything to show always renders its trigger — the popover shows a loading state until the live evaluation lands, and the picker while the field is editable for the actor; once editing is closed (a settled activity, a denying predicate) the trigger swallows the click and explains itself in the hover hint instead of falling through to the row's dialog. Values whose field is never declared editable render as plain content, without button chrome. The activity row gains an optional date-control slot for surfaces that show dates on rows.
+
+- 767497c: An unreadable workflow document no longer blanks the Workflows tool: the task list renders every readable row and flags the refused ones in a compact caution note with a Copy details button producing a paste-ready report (id, reason, and the validation detail naming the offending fields). Document surfaces keep the conservative wholesale notice: an unreadable row can't be attributed to a document, so discovery still fails loud there.
+
+### Patch Changes
+
+- 767497c: Tool bands drop their overflow menus — the document chip and the instance lockup are the inline affordances now, each carrying a tooltip ("Open document" / "View workflow") — and instance bands trail a centered hairline rule filling the rest of the band.
+- 767497c: The document view's workflow instance accordion wears the tool's band shell: a discrete chevron toggle, the title lockup, and the trailing hairline, with the instance menu kept at the band's end. One shared CollapsibleBand component now backs both surfaces, so their geometry can't drift.
+- 767497c: Overflow menus render the standard surface wherever they open — the popover no longer inherits a toned host card's background (a group band's transparent tone painted the menu grey). Menus anchor to the trigger's end edge, flipping above only when there's no room below.
+- 767497c: The inline "Document unavailable" face aligns with linked document chips: same padded box, the warning icon in its own text cell, and the chip's gap before the label.
+- 0143226: The Workflows view's instance section header spinner renders at the header lockup's own text scale (size 1) instead of the default size.
+- 767497c: The tool's task rows stay mounted across the committed-facts → live-evaluation transition: one row component renders either source, so a loading popover opened before the instance's evaluation lands resolves in place into the picker instead of closing. The shared activity row now takes a normalized face (title, status, tags) rather than a raw activity evaluation, so any surface can render it from committed facts.
+- 2005ab7: A terminal-action cluster (a row's lone button or "Select action" menu, the dialog footer's inline buttons plus "More actions" menu) shares one in-flight fire lock: while any member fires, the firing button shows loading, the menu trigger and every item disable, and sibling fires drop before reaching the session. Firing from a menu no longer leaves the cluster looking idle (a menu item unmounts when its menu closes, so its own pending state — and its double-fire guard — died with it).
+- 767497c: Per-instance session updates no longer re-render every workflow surface: the provider's live entries move out of the context value into a subscribable store, consumers subscribe per key with identity-stable snapshots, and report bursts coalesce into one trailing flush per fixed window (never extended, so a steady stream of reports still flushes on cadence). Opening the Workflows tool over dozens of instances now settles in seconds instead of tens of seconds of main-thread churn.
+- Updated dependencies [24b11dd]
+- Updated dependencies [2005ab7]
+- Updated dependencies [767497c]
+- Updated dependencies [24b11dd]
+- Updated dependencies [24b11dd]
+- Updated dependencies [59b40fd]
+  - @sanity/workflow-engine@0.19.0
+  - @sanity/workflow-react@0.14.0
+  - @sanity/workflow-studio@0.10.0
+  - @sanity/workflow-components@0.2.0
+  - @sanity/workflow-diagram@0.4.1
+
+## 0.4.0
+
+### Minor Changes
+
+- 0f50aed: Activity rows carry their tags beside the title instead of pinned to the row's end, as tight default-chrome badges that keep the row height and explain themselves on hover: "Automated" (default tone) on truly hands-off activities, and "Blocked" (caution tone) when every rendered action is disallowed. The "Awaiting decision" and "Failed" chips are gone — a multi-way decision reads as open work, and a failed activity's status glyph carries the outcome. The row's end cluster keeps only controls: terminal actions and the assignees.
+- 0f50aed: Activity status glyphs get a clearer vocabulary. Active rows wear the dashed dial (EmptyIcon) instead of an outline circle that read as an unchecked checkbox. Done rows wear a new filled checkmark-circle — a filled counterpart @sanity/icons doesn't ship, drawn to the set's filled-variant conventions with the outline icon's exact checkmark knocked out — rendered neutral rather than green, since completion is a fact, not a success banner. Failed rows wear ErrorFilledIcon in the critical tone, the one toned glyph in the set.
+- c8fa0b1: **BREAKING:** Remove the per-mapping `mandatory` option and the
+  `MandatoryWorkflowGate` it drove. A content type "requiring" a workflow is
+  extrinsic to the workflow definition and unenforceable from the client — any
+  raw write bypasses the Studio — so form-gating is dropped in favour of
+  `autoStart`.
+
+  Add `autoStart`: a plugin option mapping document `_type` to the deployed
+  workflow definition name(s) to start when an editor opens a fresh document of
+  that type, so the document is born with its workflow. The gate materializes the
+  document (like `performStart`, in the Studio's active perspective — the selected
+  release's version or the draft) and seeds it as each workflow's subject; when
+  several workflows share an input beyond the subject, one mandatory dialog
+  collects that union once and feeds each (started silently when nothing is
+  needed), and the form is revealed once the instance is live. Several workflows
+  for one type start in parallel, best-effort — a failure of one is surfaced
+  without rolling back the others. Studio-only — a floor, not enforcement.
+  Accepts a function form to vary the map by workspace name or schema.
+
+- 7276702: Editor-facing copy no longer leaks implementation vocabulary. Failure toasts show the human reason without the error class name (`describeError` maps typed engine rejections to their reason sentences); the document-action lock title names only the owning workflow, never guard machine names; activity chip hints drop the "settle"/"fired" jargon; the automation row's hover lead reads "Runs automatically"; the pending-work badge counts "automations" instead of "effects" and lists each queued effect on hover — declared title, or the registry name in code face when untitled; the superseded-definition badge reads "Older version"; the first-evaluation row reads "Loading…"; the unreadable-definition notice drops "definition"/"raw names"; field consequence hints say "set off automatic work" and "Saving will advance"; and the start-success toast shows the stage's declared title instead of its name.
+
+  An expanded Workflows-view section also gets breathing room below its body before the next section's header; collapsed sections keep their tight spacing. The Overview tab's empty state and the no-workflow pane state (previously a bare line with one start button per mapping) render in the same bordered card as the For-me tab's ("No active workflows" with a timeline icon), carrying the same "Start workflow" control as the header's "+" — button or menu, with its full gating and hints; when no mapping is startable the card carries no action row. Failed action fires log the raw error to the console — the toast keeps only the editor-facing reason. Empty-state and empty-list copy drops trailing full stops (interface copy, not prose); reason sentences keep theirs.
+
+  When a workflow completes, the spine's current-stage chip wears a checkmark instead of the stage glyph, and its hover card shows "Completed at …" (the instant the terminal stage was entered). Aborted instances keep the plain chip — abort is not a finish.
+
+  Icon-only buttons that had only an aria-label now hover-hint it: the header "+" menu face ("Start a workflow" / its label override), the instance overflow menu ("More views"), the tool's filter toggle ("Filter"), task-group menu ("Group actions"), and the instance-detail back arrow ("Back to workflows").
+
+  Every toast the plugin pushes is closable — an editor can dismiss one instead of waiting out its timeout.
+
+- 0f50aed: The "N automations pending" badge (and its hover list of queued effects) is removed from every surface that showed it: the Workflows-view instance accordion header, the tool dashboard rows, and the instance detail header.
+
+  The instance status chip now flags only the aborted outcome: completed instances wear no chip (done is not an alert), and the tool dashboard's in-flight rows drop the current-stage chip the status badge used to carry. `InstanceStatusBadge` is renamed `AbortedBadge` accordingly.
+
+- 0f50aed: The For me tab renders one flat list of assigned tasks — activity rows and to-do items across every instance — instead of nesting them in per-instance accordion groups. With no group header naming the workflow, each row carries a muted "workflow › stage" breadcrumb (chevron-separated) beside its label, which truncates to an ellipsis when space runs short. Activity and to-do labels now always truncate instead of wrapping the row taller.
+- 0f50aed: Settled activities stay in the For me list as dimmed receipts, the same way checked-off to-do items stay struck through — finishing an activity reads as an acknowledgment instead of the row vanishing. Receipts never count toward the "For me" badge or the "N assigned tasks" metric, and they clear when the stage advances.
+- cd03973: **BREAKING:** Reject initial workflow field values that cannot be consumed and expose structured preflight issues.
+
+  Calls that supplied unknown, wrong-kind, non-input, non-workflow-scope, or duplicate initial field rows previously succeeded while discarding those rows. They now fail before creating an instance with structured remediation details.
+
+  Deploy also rejects `spawn.with` keys that the resolved child definition cannot consume because the workflow field is missing or is not input-sourced. `SpawnContractsInvalidError` exposes every rejected parent/child row for machine-readable remediation.
+
+- 0f50aed: The Workflows view's "Active Workflows" and "Finished Workflows" headings carry a muted count of their instances, in the exact treatment the "For me" tab count uses — and like it, a zero shows no count.
+- b1d6801: **BREAKING:** `WorkflowMapping.subjectGdrType` and `WorkflowMapping.subjectKind` are removed. The subject reference's document type is derived from the row's `docType` — the subject is always the document the flow was opened from, whose schema type is `docType` by construction, so `subjectGdrType` could only ever restate that or misdescribe the subject; `subjectKind` was a required field nothing consumed. Delete both fields from each mapping row — rows that stamped `subjectGdrType` with their `docType` (the only correct value) behave identically.
+
+  Mapping validation now checks the document types a row's start would seed: a local `doc.ref`/`doc.refs` value whose GDR `type` the Studio schema doesn't declare as a content document type is rejected. The seeded type is what subject previews resolve against, so a type the schema can't preview — including the intrinsic `document` base, which resolves in the schema registry but carries no preview config — silently rendered every subject pill as "Untitled". Foreign-resource refs are exempt (their types live in another resource's schema). The verdict surfaces like other mapping issues: a console error plus a blocked start row.
+
+- 0f50aed: Field pills sit transparent at rest — outlined only — and light their regular background on hover and press, so the pill rows read quieter until pointed at. One chrome drives every field pill, workflow- and stage-scope alike.
+- 0f50aed: The Overview section's stage card leads with the spine alone. The spine band sits on a muted face so it reads as chrome rather than content; non-current stage pills render transparent on it with a hairline ring, and no pill changes background on hover — the hover card is a pill's one response. The current-stage pill is a primary-toned card with a deeper inset, carrying the round as a muted note after its label ("Round N", second visit on), and its hover card shows when the stage was entered ("Entered …"), the same way past stages show their exit. The stage header under the band ("<title> · Current stage · Round N") is gone — the spine now carries everything it said. The form strip renders the current stage as the chip's bare face — glyph and title without the pill — so the strip keeps its slim line height.
+- 0f50aed: The Workflows-view spine band renders on a neutral-toned card instead of the default-toned one.
+- 0f50aed: The spine pill's hover card is split in two by a full-bleed hairline: the stage title and its authored description above, live run state below (advance hint, history stamp). Hover hints gain a `flush` content mode for this — the content owns all padding so a divider can reach the tooltip's edges.
+
+  The advance hint renders on a primary-toned inset card, and on a conditionally-gated single-transition stage it now phrases the actual conditions as a live condition checklist read from the evaluation's transition insight, adding an undecidable-hold note when the `when` evaluated to GROQ null (a value it depends on is missing). Without a live evaluation it keeps the generic "when its conditions are met" phrasing.
+
+  History stamps drop the seconds and read relative-first, the absolute instant on its own line ("Entered about 3 hours ago" over "16 Jul 2026, 13:43"). The terminal stage a workflow finished in stamps "Completed"; a previously-visited stage that lies ahead again after a send-back shows no stamp at all — a past date there would read as schedule, not history. The activity count is gone.
+
+- 0f50aed: A branching stage's hover card now shows an advance hint for its forward route — the transition targeting the next stage in authored order, the node the spine draws beside it — phrased with the same live condition list as a single-transition stage. Sibling routes (send-backs, detours) stay undrawn, matching the band's linear reading. No hint renders when no route targets the authored-adjacent stage or the stage is authored last. The phrased conditions are what the forward route requires; the engine still fires the first truthy transition in declaration order.
+
+  The advance card also drops its leading arrow, renders the target stage name in medium weight, and lists conditions as neutral bullets — no ✗/✓ marks, and an all-of root's "All of:" label is hoisted since the card's "when:" lead already carries the conjunction. The stage's authored description renders in italics, so it reads as description rather than a statement about the run.
+
+- 5cd8ffd: **BREAKING:** Effect handlers now receive each host's concrete Sanity client unchanged, preserving its complete runtime and type surface. Handler traffic is no longer automatically tagged as `workflow.effect` or pinned to the engine API version; handlers own that configuration.
+- 0f50aed: Hovering a document-strip line now previews the user's open assigned tasks under an "Assigned tasks" heading — bare task names behind their status faces (glyph or read-only checkbox), with no action buttons, assignee controls, or breadcrumbs: the glance names the work, and the view the line opens carries the full context. Settled receipts don't earn a preview — they stay in the For me tab. The glance caps at three rows with an "and N more" tail and rides a wider tooltip cap so long names keep room. With nothing open, the tooltip keeps its "Open the Workflows view" affordance copy plus a "Nothing here is assigned to you" note once the user's identity has resolved to back that claim.
+- 0f50aed: The form strip's assigned-task slot shows an inline spinner while identity and evaluations are still landing, instead of the "Loading…" text. The spinner sits outside the line's clickable card, so a cursor parked on it doesn't light the hover face; the count and the stale-window "Updating…" text stay inside as before.
+- 5244335: **BREAKING:** Require Sanity Studio v6. The Studio validation harness now installs the workflow CLI alongside the plugin and builds that combined package set, guarding the shared Vite 8 toolchain.
+- 55a54b3: Surfaces understand the new `subject` field kind. Studio plugin: the start dialog's default subject seed lands on a definition's `subject`-kind entry whatever it is named (the doc.ref-named-`subject` convention stays the fallback), subject entries get the document picker / read-only face / state-panel preview / document pill, and mapping validation checks the subject entry's `types` facet. MCP: the subject lookup behind title enrichment prefers the `subject`-kind entry and keeps the name convention as fallback; the authoring guide teaches the kind. Test bench — **BREAKING:** `subjectField` now builds a `subject`-KIND entry value (matching its name and the engine's subject rule); a definition declaring the doc.ref convention needs the new `docRefField(documentId, {name})` instead. `instancesForSubject` matches both single-ref kinds.
+- b82bda4: Add the opt-in `$subjectHasInFlightInstance` start variable for composing subject-exclusive visibility and permission rules.
+- 0f50aed: An activity-scope to-do item's breadcrumb now ends with its activity's title ("workflow › stage › activity"), naming the parent that a flat list can't show. When a row runs out of room, the breadcrumb yields before the title — task names keep their space and the context truncates first.
+- 4490442: Add inclusive validation.min/max bounds for workflow string, text, and number declarations, with Studio input constraints and MCP authoring guidance.
+- 1540dce: **BREAKING:** Definitions and instances written by this release require a model-2 engine reader; upgrade every reader before deploying its writers.
+
+  Workflow fields, nested field shapes, effect outputs, and action parameters can declare typed scalar choices with `options.list`. The engine validates authored lists and rejects runtime values outside them, Studio renders one shared select control and displays each selected choice by its title, and the MCP authoring guide explains the syntax.
+
+### Patch Changes
+
+- 0f50aed: Breadcrumb chevrons now center on the text's cap band instead of the x-height band (which sat them visibly low beside mixed-case segments) and render slightly dimmed everywhere, so they read as punctuation rather than content. To-do item labels render in medium weight, matching the activity rows they sit between.
+- 6351232: Add reusable member, assignee, and date controls for Studio and App SDK integrations.
+- 0f50aed: The assign control no longer renders on a field the actor can't edit — previously a settled activity's row (and its dialog) showed a picker trigger that took the click, flashed its pressed face, and did nothing, since the engine closes an activity-scope field's edit window once the activity settles. A non-editable assignees field now shows its assignees as plain display: the row keeps the avatar stack when anyone was assigned and shows nothing otherwise.
+- d26cc1a: Add the engine-owned Actor resolution contract with client-backed resolution for server, CLI, and MCP runtimes; add native Studio and App SDK project-user integrations; and migrate the Studio plugin member picker to the shared directory.
+- 9126299: **BREAKING:** Delete persisted stage guard documents when their stage exits, and remove the lifted-record `GUARD_LIFTED_PREDICATE` and `isGuardLifted` exports.
+
+  Guard deletion now uses the observed document revision so stale exit reconciliation cannot delete a guard reactivated by a newer stage visit. Reactive guard streams contain only active persisted guards.
+
+- d526887: The start dialog no longer flashes the "A previous start of this workflow didn't finish" resume card during a normal start. A start lands as separate create/prime commits, and the live list echoes the attempt's own instance mid-flight; the dialog now holds the presentation the attempt began with (the input form for a fresh start, the resume card for a continue) until the attempt settles, instead of re-deriving it from that echo. A start that fails after its create commit still surfaces the resume card once the attempt is over.
+- b06a45c: Document links (previews and the task list's "Open document" item) now gate on the target's actual `_type`: a probe resolves the real type from the lake, and only a target whose type is a concrete document type in the workspace schema gets an edit link. A target whose type can't back a document form here renders a no-link notice instead of navigating into a Studio error, the linked preview uses the actual type rather than the stored reference type, and the "Open document" menu item applies the same locality and existence gates as preview links.
+- b06a45c: Document links in workflow surfaces navigate by document id only and let the Studio resolve the target's real `_type`. Previously the stored GDR `type` was passed as the edit intent's `type` param, and the Studio trusts that value verbatim — when it wasn't the target's concrete schema type (e.g. the generic `document`), the document pane built a form for a fieldless type and crashed the Studio.
+- 0f50aed: A to-do checkbox that can't be toggled now explains why on hover — the tooltip rides the checkbox itself, not the whole row. The row derivation carries the owning field's edit-disabled reason, and the row surfaces it with the same lines the field pills use — in the For me list, the Overview, and the activity dialog's checklist alike. Those reason lines are retuned as single-line interface copy: no trailing full stops, no "field" vocabulary (the same line shows on checkboxes outside any field context), and the closed-window case names the actual cause: "Can only be edited while its activity is active".
+- Updated dependencies [239d9f6]
+- Updated dependencies [775fb3c]
+- Updated dependencies [3af2ca0]
+- Updated dependencies [7276702]
+- Updated dependencies [7276702]
+- Updated dependencies [6351232]
+- Updated dependencies [58f8211]
+- Updated dependencies [00c089d]
+- Updated dependencies [f1fbedd]
+- Updated dependencies [71cd58e]
+- Updated dependencies [cd03973]
+- Updated dependencies [d26cc1a]
+- Updated dependencies [9126299]
+- Updated dependencies [f02d026]
+- Updated dependencies [72018af]
+- Updated dependencies [5cd8ffd]
+- Updated dependencies [b82bda4]
+- Updated dependencies [5244335]
+- Updated dependencies [55a54b3]
+- Updated dependencies [b82bda4]
+- Updated dependencies [4490442]
+- Updated dependencies [1540dce]
+- Updated dependencies [b341a7d]
+  - @sanity/workflow-engine@0.18.0
+  - @sanity/workflow-components@0.1.0
+  - @sanity/workflow-diagram@0.4.0
+  - @sanity/workflow-studio@0.9.0
+  - @sanity/workflow-react@0.13.0
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -11,8 +11,8 @@ UI: a **workflow strip** above the editor form of mapped documents (the
 current stage, your task count, and a **Start workflow** button), and a
 **Workflows tab** next to the editor with the stage's activities and to-dos,
 where they fire actions and read the history, and a **Workflows tool** in the
-Studio navbar — a tasks view, a dashboard of the newest workflow instances,
-and a deep-linkable per-workflow detail view.
+Studio navbar — the open tasks across the newest workflow instances (capped),
+the user's own cut of them, and a deep-linkable per-workflow detail view.
 
 Four ideas cover everything in this guide:
 
@@ -36,7 +36,7 @@ treat plugin-side checks as a security boundary.
 npm install @sanity/workflow-studio-plugin @sanity/workflow-engine @sanity/workflow-cli
 ```
 
-Requires a Studio v5 project (`sanity ^5.30`, `react ^19`,
+Requires a Studio v6 project (`sanity ^6`, `react ^19`,
 `styled-components ^6`, `@sanity/sdk ^2.12` — the usual studio peers).
 
 ## 2. Define a workflow
@@ -56,7 +56,7 @@ export const articleReview = defineWorkflow({
   fields: [
     // The document this workflow is about. The plugin fills it in when an
     // editor starts the workflow from a document.
-    {type: 'doc.ref', name: 'subject', title: 'Article', initialValue: {type: 'input'}},
+    {type: 'subject', name: 'subject', title: 'Article', initialValue: {type: 'input'}},
   ],
   stages: [
     {
@@ -103,6 +103,7 @@ import {articleReview} from './workflows/article-review'
 export default defineWorkflowConfig({
   deployments: [
     {
+      expectedMinReaderModel: 2,
       name: 'production',
       // The tag namespaces all workflow data — the plugin only sees
       // definitions and instances deployed under the tag it's configured with.
@@ -140,8 +141,6 @@ const workflowMappings: readonly WorkflowMapping[] = [
   {
     docType: 'article', // your schema type
     definition: 'article-review', // the deployed definition's `name`
-    subjectKind: 'document',
-    subjectGdrType: 'article',
     label: 'Article review',
   },
 ]
@@ -193,11 +192,68 @@ export const article = defineType({
 })
 ```
 
+### Auto-start a workflow on new documents
+
+`autoStart` starts a workflow the moment an editor opens a **fresh** document
+of a given type — the document is born with its workflow instead of relying on
+someone to press "Start". It's a map of document `_type` to the deployed
+definition name(s) to start:
+
+```ts
+workflowStudioPlugin({
+  tag: 'production',
+  mappings: [
+    /* ... */
+  ],
+  autoStart: {
+    article: 'article-review', // one workflow
+    campaign: ['legal-review', 'brand-review'], // several, started together
+  },
+})
+```
+
+Pass a function instead of a map to vary it by workspace (its name, or the
+schema):
+
+```ts
+autoStart: ({workspaceName}) => (workspaceName === 'editorial' ? {article: 'article-review'} : {})
+```
+
+How it behaves:
+
+- **Fresh only.** Studio doesn't persist a new document until its first edit,
+  so "fresh" means never-persisted (no `_createdAt`). The gate takes over that
+  first form render and never touches a document that already exists.
+- **The document is the subject.** The gate materializes the document (like
+  pressing "Start workflow" does) in the Studio's **active perspective** — the
+  selected release's version, or the draft when none is selected — and seeds it
+  as each workflow's subject. When
+  several workflows share an input beyond the subject, one dialog collects that
+  union once and feeds every workflow; when nothing is needed, they start
+  silently. The dialog is **mandatory** — auto-start means the workflow will
+  start, so there's no skip; the required inputs must be filled. The form is
+  revealed once the workflow instance is live.
+- **Best-effort with several workflows.** When a type maps to more than one
+  workflow they start in parallel, and the form stays held until they've all
+  started. A failure is never a dead end: the takeover shows the error with a
+  **Try again** (re-attempts only the workflows that didn't start — never
+  double-starting one) and a **Continue editing without it**. There's no
+  automatic rollback — the document is left created, its workflows as they
+  landed.
+- **A floor, not a guarantee.** A raw client or any non-Studio write bypasses it
+  entirely; enforcing "this type must have a workflow" needs a service in front
+  of the Content Lake, which is out of scope. A misconfigured entry (unknown
+  type, undeployed or spawn-only workflow, a subject that doesn't accept the
+  type) is dropped with a `console.warn`, never a crash.
+
+Naming a workflow here doesn't require a `mappings` entry — the inputs come
+from the deployed definition itself — but pairing the two is common, so the
+same document also carries the workflow strip and views.
+
 Plugin options, for later: `workflowDataset` (keep workflow state in a
 separate dataset), `effectHandlers` (run effect side-effects in the browser
-— the runtime below is usually the better home), and per-mapping `mandatory`
-(gate the editor form until a workflow is attached), `initialStateBuilder`,
-and `perspectiveField` (bind a release to the workflow).
+— the runtime below is usually the better home), and per-mapping
+`initialStateBuilder` and `perspectiveField` (bind a release to the workflow).
 
 ## 5. Add the runtime (two Sanity Functions)