@cat-factory/app 0.274.0 → 0.276.0

package/app/modular/tutorial-tours.ts

@@ -130,6 +130,17 @@ export const TUTORIAL_REQUIREMENTS = {
     labelKey: 'tutorial.requirements.advancedTier',
     met: (gates) => gates.advancedMode,
   },
+  // The other SPA-narrowing axis, and it is a requirement for exactly the same reason the tier is:
+  // a narrowed ROLE (`utils/uiRole.ts`) keeps only the `intake` nav entries, so every tour whose
+  // step CLICKS one of the others would be offered to a designer and then hunt for a sidebar entry
+  // their screen does not render. Which tours those are is not a judgement call: it is the pairing
+  // `tutorial-tours.spec.ts` derives from `navItemVisible`, so a tour that gains a nav-anchored
+  // step fails there until this is declared.
+  fullSurface: {
+    id: 'full-surface',
+    labelKey: 'tutorial.requirements.fullSurface',
+    met: (gates) => gates.fullSurface,
+  },
   // The platform half's requirements. Each mirrors, exactly, the `gate` of the sidebar entry the
   // tour clicks (`nav-model-providers` / `nav-integrations`, `nav-fragments`). A requirement
   // WEAKER than the gate of the control a step points at offers the tour to a user who has no
@@ -204,15 +215,33 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
         titleKey: 'tutorial.tours.boardBasics.steps.toolbar.title',
         bodyKey: 'tutorial.tours.boardBasics.steps.toolbar.body',
       },
+      {
+        // The role decides which surfaces exist at all, so the orientation tour names it before
+        // the tier it caps. No `when`: the switcher is rendered in EVERY role (it is the way back
+        // out of the narrowed one), which is exactly why the tour can always point at it.
+        id: 'role',
+        target: 'ui-role-switcher',
+        altTargets: ['ui-role-toggle'],
+        placement: 'right',
+        titleKey: 'tutorial.tours.boardBasics.steps.role.title',
+        bodyKey: 'tutorial.tours.boardBasics.steps.role.body',
+      },
       {
         // Basic mode is the shipped default, and it HIDES a whole half of the product
         // (sandbox, Kaizen, bootstrap, the operator surfaces). A user who never finds the
         // switcher never learns that half exists, so the orientation tour is the one place
         // that has to name it — the switcher is deliberately visible in both tiers for the
         // same reason (see `nav-contributions.ts`).
+        //
+        // `when` rather than a tour-level requirement, and rather than nothing: a narrowed role's
+        // tier is CAPPED at basic, so the sidebar drops this switcher, and a step that merely
+        // missed its anchor would be reported as an abridged tour, which is the wrong thing to say
+        // about a control that is absent because of a choice the user made. Gating the whole tour
+        // would be worse still: orientation is the one walkthrough every role should get.
         id: 'interfaceTier',
         target: 'ui-mode-switcher',
         altTargets: ['ui-mode-toggle'],
+        when: (gates) => gates.fullSurface,
         placement: 'right',
         titleKey: 'tutorial.tours.boardBasics.steps.interfaceTier.title',
         bodyKey: 'tutorial.tours.boardBasics.steps.interfaceTier.body',
@@ -236,7 +265,11 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // repo is a board write against a connected source, and in basic interface mode
     // add-from-repo is the ONLY route (bootstrap is advanced), which is what makes this
     // worth a tour rather than a hint.
-    requires: [TUTORIAL_REQUIREMENTS.boardWrite, TUTORIAL_REQUIREMENTS.sourceControl],
+    requires: [
+      TUTORIAL_REQUIREMENTS.boardWrite,
+      TUTORIAL_REQUIREMENTS.sourceControl,
+      TUTORIAL_REQUIREMENTS.fullSurface,
+    ],
     steps: [
       {
         id: 'intro',
@@ -668,7 +701,7 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // onboarding advisory, which the launch prompt stands down for) — this is for the person who
     // meets the question later, or who wants to know where the answer lives.
     offeredAtLaunch: false,
-    requires: [TUTORIAL_REQUIREMENTS.integrationsManage],
+    requires: [TUTORIAL_REQUIREMENTS.integrationsManage, TUTORIAL_REQUIREMENTS.fullSurface],
     steps: [
       {
         id: 'intro',
@@ -712,7 +745,7 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // change. A user who never finds the builder treats the built-in catalog as the product's
     // fixed shape and works around it in task descriptions instead.
     offeredAtLaunch: false,
-    requires: [TUTORIAL_REQUIREMENTS.boardWrite],
+    requires: [TUTORIAL_REQUIREMENTS.boardWrite, TUTORIAL_REQUIREMENTS.fullSurface],
     steps: [
       {
         id: 'intro',
@@ -774,7 +807,11 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // How you steer output without restating your conventions in every task description, which
     // is what people do instead when they never find this.
     offeredAtLaunch: false,
-    requires: [TUTORIAL_REQUIREMENTS.library, TUTORIAL_REQUIREMENTS.settingsManage],
+    requires: [
+      TUTORIAL_REQUIREMENTS.library,
+      TUTORIAL_REQUIREMENTS.settingsManage,
+      TUTORIAL_REQUIREMENTS.fullSurface,
+    ],
     steps: [
       {
         id: 'intro',
@@ -813,7 +850,7 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // Each integration changes what a run can SEE or SAY, and none of them announces itself:
     // a board with no tracker linked simply never mentions that issues could arrive on their own.
     offeredAtLaunch: false,
-    requires: [TUTORIAL_REQUIREMENTS.integrationsManage],
+    requires: [TUTORIAL_REQUIREMENTS.integrationsManage, TUTORIAL_REQUIREMENTS.fullSurface],
     steps: [
       {
         id: 'intro',
@@ -854,7 +891,7 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // itself, and the cost of not finding it is a run that fails on provisioning with a banner
     // pointing at a window the user has never opened.
     offeredAtLaunch: false,
-    requires: [TUTORIAL_REQUIREMENTS.infrastructure],
+    requires: [TUTORIAL_REQUIREMENTS.infrastructure, TUTORIAL_REQUIREMENTS.fullSurface],
     steps: [
       {
         id: 'intro',
@@ -906,7 +943,11 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // workspace that has never made a group renders nothing for the anchored step to find. The
     // guard only pairs a tour against the visibility of a NAV entry, so a section hiding itself
     // one level in is exactly the case that has to be declared by hand.
-    requires: [TUTORIAL_REQUIREMENTS.settingsManage, TUTORIAL_REQUIREMENTS.advancedTier],
+    requires: [
+      TUTORIAL_REQUIREMENTS.settingsManage,
+      TUTORIAL_REQUIREMENTS.advancedTier,
+      TUTORIAL_REQUIREMENTS.fullSurface,
+    ],
     steps: [
       {
         id: 'intro',
@@ -950,7 +991,11 @@ export const TUTORIAL_TOURS: readonly TutorialTour[] = [
     // renders the entry this tour clicks. Declared rather than assumed: `navRequirementDrift`
     // enumerates the whole gate matrix against that entry's own visibility rule and fails
     // without it.
-    requires: [TUTORIAL_REQUIREMENTS.settingsManage, TUTORIAL_REQUIREMENTS.advancedTier],
+    requires: [
+      TUTORIAL_REQUIREMENTS.settingsManage,
+      TUTORIAL_REQUIREMENTS.advancedTier,
+      TUTORIAL_REQUIREMENTS.fullSurface,
+    ],
     steps: [
       {
         id: 'intro',

package/app/pages/index.vue

@@ -155,6 +155,9 @@ const TutorialOverlay = defineAsyncComponent(
   () => import('~/components/tutorial/TutorialOverlay.vue'),
 )
 const TutorialNudge = defineAsyncComponent(() => import('~/components/tutorial/TutorialNudge.vue'))
+// The first-run role question (Engineer / Product manager / Designer). Same shape as the tutorial
+// launch prompt: mounted only while its store flag is set, so an answered question costs nothing.
+const RolePrompt = defineAsyncComponent(() => import('~/components/layout/RolePrompt.vue'))
 
 const workspace = useWorkspaceStore()
 const github = useGitHubStore()
@@ -312,11 +315,11 @@ const needsGitHubInstall = computed(() => github.available === true && !github.c
 const githubProbePending = computed(() => github.available === null)
 
 // Offer the tutorial on launch, once the board is up. Yields to every other startup
-// surface — the GitHub onboarding gate and the advisory/onboarding modals above — so a
-// first launch never stacks the tour prompt on top of a dialog that needs answering
-// first; when one of those is open, the flip of its flag re-fires this watcher and the
-// prompt appears then. The store guards the rest: only a user who never answered is
-// asked, at most once per session.
+// surface — the GitHub onboarding gate, the advisory/onboarding modals above, and the role
+// question below — so a first launch never stacks the tour prompt on top of a dialog that
+// needs answering first; when one of those is open, the flip of its flag re-fires this
+// watcher and the prompt appears then. The store guards the rest: only a user who never
+// answered is asked, at most once per session.
 //
 // Yielding runs in BOTH directions: an advisory that opens LATER (a health probe that
 // resolves a beat after the board) would otherwise land on top of an open tour prompt,
@@ -330,6 +333,7 @@ const githubProbePending = computed(() => github.available === null)
 // state pays nothing for the launch offer: no watcher, no mounted component (the v-ifs
 // below), no store reads.
 const tutorial = useTutorialStore()
+const uiRole = useUiRoleStore()
 const startupAdvisoryOpen = computed(
   () =>
     needsGitHubInstall.value ||
@@ -340,6 +344,30 @@ const startupAdvisoryOpen = computed(
     ui.aiProviderSetupOpen ||
     ui.aiPresetMismatchOpen,
 )
+
+// The ROLE question comes before the tour offer, and the ordering is the point: the role decides
+// which surfaces exist, so a tour picked ahead of it could be about half a product the next answer
+// removes. It runs the same launch machine as the tutorial offer (yield to anything the user must
+// actually answer, re-arm when that surface goes, at most one offer per session) and stops itself
+// once it can no longer do anything.
+const roleOfferSettled = () => uiRole.chosen || (uiRole.promptAutoOpened && !uiRole.promptOpen)
+if (!roleOfferSettled()) {
+  let stopRoleOffer: (() => void) | undefined
+  stopRoleOffer = watch(
+    () => [workspace.ready, startupAdvisoryOpen.value, uiRole.promptOpen],
+    () => {
+      if (startupAdvisoryOpen.value) uiRole.deferPrompt()
+      else if (workspace.ready) uiRole.maybeOfferOnLaunch()
+      if (roleOfferSettled()) stopRoleOffer?.()
+    },
+    { immediate: true },
+  )
+  if (roleOfferSettled()) stopRoleOffer()
+}
+// What the TOUR offer yields to: every startup advisory, plus the role question above it. The
+// role prompt is not in `startupAdvisoryOpen` itself, or the role offer would defer to its own
+// standing offer and withdraw it a tick after making it.
+const tutorialYieldsTo = computed(() => startupAdvisoryOpen.value || uiRole.promptOpen)
 // Settled = the offer can never need to act again: a decision exists, or the prompt was
 // auto-opened and is still standing (a deferral clears `promptAutoOpened`, which is
 // exactly what keeps the watcher alive to re-offer).
@@ -350,9 +378,9 @@ if (!tutorialOfferSettled()) {
   // inside `watch(...)`, before the handle is assigned — the trailing check covers it.
   let stopTutorialOffer: (() => void) | undefined
   stopTutorialOffer = watch(
-    () => [workspace.ready, startupAdvisoryOpen.value, tutorial.promptOpen],
+    () => [workspace.ready, tutorialYieldsTo.value, tutorial.promptOpen],
     () => {
-      if (startupAdvisoryOpen.value) tutorial.deferPrompt()
+      if (tutorialYieldsTo.value) tutorial.deferPrompt()
       else if (workspace.ready) tutorial.maybeOfferOnLaunch()
       if (tutorialOfferSettled()) stopTutorialOffer?.()
     },
@@ -506,6 +534,7 @@ watch(
         <VendorCredentialsModal v-if="ui.vendorCredentialsOpen" />
         <AiProviderOnboardingModal v-if="ui.aiProviderSetupOpen" />
         <AiPresetMismatchDialog v-if="ui.aiPresetMismatchOpen" />
+        <RolePrompt v-if="uiRole.promptOpen" />
         <TutorialPrompt v-if="tutorial.promptOpen" />
         <TutorialCatalogue v-if="tutorial.catalogueOpen" />
         <TutorialOverlay v-if="tutorial.touring" />

package/app/stores/board/placement.ts

@@ -1,4 +1,5 @@
 import type { UpdateBlockInput } from '@cat-factory/contracts'
+import { moduleNameInContainer } from '@cat-factory/contracts'
 import { useServicesStore } from '~/stores/services'
 import { useWorkspaceStore } from '~/stores/workspace'
 import { createBoardDependencies } from './dependencies'
@@ -59,9 +60,14 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
     // block in the wrong container (a structural lie that survives until re-hydrate).
     const prevParentId = b.parentId
     const prevPosition = b.position
+    const prevModuleName = b.moduleName
     const name = b.title
     b.parentId = newParentId
     b.position = position
+    // The server re-stamps a moved task's declared module from its new container, so predict the
+    // same answer here: without it the card lands in the lane group it was dragged OUT of and
+    // jumps to the right one when the response arrives.
+    if (b.level === 'task') b.moduleName = moduleNameInContainer(parent)
     try {
       upsert(
         await api.reparentBlock(useWorkspaceStore().requireId(), id, {
@@ -90,6 +96,7 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
     } catch (e) {
       b.parentId = prevParentId
       b.position = prevPosition
+      b.moduleName = prevModuleName
       // A cross-home drag can be refused on merge-preset grounds, which is a condition the mover
       // can act on rather than a fault. The backend sends the machine-readable reason and no
       // translated prose, so map it here; anything else keeps the raw message as the last resort.

package/app/stores/board.spec.ts

@@ -3,6 +3,8 @@ import { setActivePinia, createPinia } from 'pinia'
 import type { Block, BlockStatus } from '~/types/domain'
 import { useBoardStore } from '~/stores/board'
 import { useWorkspaceStore } from '~/stores/workspace'
+import { EMPTY_FRAME_SIZE } from '~/utils/framePlacement'
+import { frameContentSize, laneBodyHeightIn, LANE_GEOMETRY } from '~/utils/laneGeometry'
 
 /** Minimal Block factory — only the fields the read getters care about. */
 function block(id: string, over: Partial<Block> = {}): Block {
@@ -27,6 +29,8 @@ const moduleBlock = (id: string, parentId: string, over: Partial<Block> = {}) =>
   block(id, { level: 'module', parentId, ...over })
 const task = (id: string, parentId: string, over: Partial<Block> = {}) =>
   block(id, { level: 'task', parentId, ...over })
+const initiativeBlock = (id: string, parentId: string, over: Partial<Block> = {}) =>
+  block(id, { level: 'initiative', parentId, ...over })
 
 describe('board store read getters', () => {
   let store: ReturnType<typeof useBoardStore>
@@ -212,29 +216,77 @@ describe('board store read getters', () => {
   })
 
   describe('containerSize', () => {
-    it('returns base dimensions for an empty service', () => {
+    // A frame's size is now a function of the LANE GEOMETRY, not of its contents. That is the
+    // point of the swimlanes: each lane scrolls, so a service accumulating work no longer grows
+    // a taller and taller frame until it dwarfs its neighbours. These tests pin the INVARIANT
+    // (size independent of task count and task position) rather than the pixel arithmetic, which
+    // belongs to `LANE_GEOMETRY` and would otherwise be restated here to no purpose.
+    it('sizes a service with nothing in it to the panel it actually renders', () => {
+      // An empty service shows one "add the first task" panel, not lanes, so it reserves the
+      // panel's footprint. Reserving the lanes' would leave the frame more than twice as tall as
+      // its own contents — and, since a placement clears frames by their reserved size, would
+      // push its neighbours that much further away for a frame holding nothing.
       store.hydrate([frame('f1')])
-      expect(store.containerSize('f1')).toEqual({ w: 360, h: 220 })
+      expect(store.containerSize('f1')).toEqual(
+        frameContentSize({ hasChildren: false, initiatives: 0 }),
+      )
     })
 
-    it('grows to fit a task and adds the module header height for modules', () => {
+    it('reserves the same footprint for a new frame that a new frame will render at', () => {
+      // The drift this caught: `EMPTY_FRAME_SIZE` is what a placement decision reserves BEFORE the
+      // block exists, so it cannot measure the frame and has to predict it. A hand-copied pair
+      // went stale when the floor changed underneath it, and every new service was then dropped
+      // on top of a neighbour it had been placed to clear.
+      store.hydrate([frame('f1')])
+      expect(store.containerSize('f1')).toEqual(EMPTY_FRAME_SIZE)
+    })
+
+    it('does not grow with task count, however many tasks and wherever they sat', () => {
+      store.hydrate([frame('f1'), task('t1', 'f1')])
+      const oneTask = store.containerSize('f1')
+
       store.hydrate([
         frame('f1'),
-        moduleBlock('m1', 'f1', { position: { x: 0, y: 0 } }),
+        moduleBlock('m1', 'f1', { position: { x: 400, y: 300 } }),
         task('t1', 'm1', { position: { x: 300, y: 200 } }),
+        // A position far outside the old content extent: it used to stretch the frame to reach
+        // it, and now means nothing at all, because a task no longer renders at coordinates.
+        task('t2', 'f1', { position: { x: 4000, y: 9000 } }),
       ])
-      // module inner width/height fit the task, plus the 30px module header.
-      const size = store.containerSize('m1')
-      expect(size.w).toBe(300 + 210 + 12)
-      expect(size.h).toBe(200 + 160 + 12 + 30)
+      expect(store.containerSize('f1')).toEqual(oneTask)
+    })
+
+    it('makes room for the initiative band above the lanes', () => {
+      // Initiatives are the one child still laid out by the frame itself (in a wrapping band),
+      // so they are the one thing the frame's height still has to account for.
+      store.hydrate([frame('f1'), task('t1', 'f1')])
+      const withoutBand = store.containerSize('f1').h
+      store.hydrate([frame('f1'), task('t1', 'f1'), initiativeBlock('i1', 'f1')])
+      expect(store.containerSize('f1').h).toBe(withoutBand + LANE_GEOMETRY.initiativeHeight)
+    })
+
+    it('sizes a frame holding only an initiative for lanes, since that is what it renders', () => {
+      // `BlockNode` gates the lanes on having ANY child — tasks, modules or initiatives — so a
+      // frame with an initiative and no tasks renders three (empty) lanes. A size that disagreed
+      // with what rendered is the clipping this geometry exists to prevent.
+      store.hydrate([frame('f1'), initiativeBlock('i1', 'f1')])
+      expect(store.containerSize('f1')).toEqual(
+        frameContentSize({ hasChildren: true, initiatives: 1 }),
+      )
     })
 
-    it('expands a service to enclose its nested modules', () => {
-      store.hydrate([frame('f1'), moduleBlock('m1', 'f1', { position: { x: 400, y: 300 } })])
-      const mod = store.containerSize('m1')
-      const svc = store.containerSize('f1')
-      expect(svc.w).toBe(400 + mod.w + 12)
-      expect(svc.h).toBe(300 + mod.h + 12)
+    it('a module reports no canvas of its own, since it is no longer drawn as a box', () => {
+      store.hydrate([frame('f1'), moduleBlock('m1', 'f1'), task('t1', 'm1')])
+      expect(store.containerSize('m1').h).toBe(0)
+    })
+
+    it('keeps an explicitly resized frame at the size the user dragged it to', () => {
+      // The geometry is a FLOOR, not a fixed size: dragging the border still gives a reader more
+      // room, and a lane grows its scroll viewport into it rather than leaving dead canvas below.
+      store.hydrate([frame('f1', { size: { w: 2000, h: 1500 } }), task('t1', 'f1')])
+      const size = store.containerSize('f1')
+      expect(size).toEqual({ w: 2000, h: 1500 })
+      expect(laneBodyHeightIn(size, 0)).toBeGreaterThan(LANE_GEOMETRY.laneBodyHeight)
     })
   })
 
@@ -422,6 +474,59 @@ describe('board store optimistic rollback', () => {
     // the undo move is itself non-undoable, so no second toast is queued
     expect(actions).toHaveLength(1)
   })
+
+  it('reparentBlock predicts the declared module the server will re-stamp', async () => {
+    // The board reads a task's PARENT for its module and falls back to the name it DECLARES (a
+    // task can name a module before the engine materialises the block on merge). So a card
+    // dragged out of a module and left still declaring it re-groups under the module it was just
+    // dragged out of. The server re-stamps the name on every reparent; the optimistic write here
+    // has to predict the same answer or the card visibly jumps when the response lands.
+    //
+    // The request never settles, so what is asserted is strictly what this store put on screen
+    // BEFORE hearing back — the window the card would otherwise spend in the wrong group.
+    vi.stubGlobal('useApi', () => ({ reparentBlock: () => new Promise(() => {}) }))
+    vi.stubGlobal('useToast', () => ({ add: () => {} }))
+    setActivePinia(createPinia())
+    useWorkspaceStore().workspaceId = 'ws1'
+    const store = useBoardStore()
+    store.hydrate([
+      frame('f1'),
+      moduleBlock('m1', 'f1', { title: 'Sessions' }),
+      task('t1', 'm1', { moduleName: 'Sessions' }),
+      task('t2', 'f1'),
+    ])
+
+    // Out to the service frame: the declared name goes with it, as the empty string the store
+    // maps to NULL. Left behind, it is what files the card straight back into "Sessions".
+    void store.reparentBlock('t1', 'f1', { x: 0, y: 0 })
+    expect(store.getBlock('t1')?.moduleName).toBe('')
+
+    // And in: the destination module's title, whatever the task declared before.
+    void store.reparentBlock('t2', 'm1', { x: 0, y: 0 })
+    expect(store.getBlock('t2')?.moduleName).toBe('Sessions')
+  })
+
+  it('reparentBlock restores the declared module when the move is rejected', async () => {
+    // The same rollback contract the parent and position already had: a refused move must not
+    // leave the card grouped somewhere the server never put it.
+    vi.stubGlobal('useApi', () => ({
+      reparentBlock: async () => {
+        throw new Error('nope')
+      },
+    }))
+    vi.stubGlobal('useToast', () => ({ add: () => {} }))
+    setActivePinia(createPinia())
+    useWorkspaceStore().workspaceId = 'ws1'
+    const store = useBoardStore()
+    store.hydrate([
+      frame('f1'),
+      moduleBlock('m1', 'f1', { title: 'Sessions' }),
+      task('t1', 'm1', { moduleName: 'Sessions' }),
+    ])
+
+    await store.reparentBlock('t1', 'f1', { x: 0, y: 0 })
+    expect(store.getBlock('t1')).toMatchObject({ parentId: 'm1', moduleName: 'Sessions' })
+  })
 })
 
 describe('board store deferred delete + undo', () => {

package/app/stores/laneView.spec.ts

@@ -0,0 +1,61 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import { createPinia, setActivePinia } from 'pinia'
+import { useLaneViewStore } from '~/stores/laneView'
+
+// The preference is PERSISTED in the reader's browser, which makes the restored value
+// untrusted input: a blob written by an older build can name a sort key this build has
+// retired, and feeding that to the comparator lookup would throw mid-sort and take the whole
+// board down over a stale preference. That narrowing is the thing worth pinning here.
+
+describe('laneView store', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
+
+  it('defaults to the per-lane smart order with no grouping', () => {
+    const store = useLaneViewStore()
+    expect(store.sortKey).toBe('smart')
+    expect(store.groupKey).toBe('none')
+    expect(store.hasOverride).toBe(false)
+  })
+
+  it('opens with the Done lane collapsed', () => {
+    // A service with a long history would otherwise open as a wall of merged cards.
+    expect(useLaneViewStore().doneLaneCollapsed).toBe(true)
+  })
+
+  it('falls back to the default when a restored key is not in this build vocabulary', () => {
+    const store = useLaneViewStore()
+    // Exactly what a persisted blob from an older build looks like.
+    store.storedSortKey = 'sort_by_vibes'
+    store.storedGroupKey = 'group_by_astrology'
+    expect(store.sortKey).toBe('smart')
+    expect(store.groupKey).toBe('none')
+    // …and a stale value must not read as an override, or the board would claim a preference
+    // it is not actually applying.
+    expect(store.hasOverride).toBe(false)
+  })
+
+  it('reports an override so the control survives a switch to basic mode', () => {
+    const store = useLaneViewStore()
+    store.setSortKey('severity_desc')
+    expect(store.hasOverride).toBe(true)
+    store.reset()
+    expect(store.hasOverride).toBe(false)
+    expect(store.sortKey).toBe('smart')
+  })
+
+  it('treats grouping alone as an override', () => {
+    const store = useLaneViewStore()
+    store.setGroupKey('module')
+    expect(store.hasOverride).toBe(true)
+  })
+
+  it('toggles the Done lane', () => {
+    const store = useLaneViewStore()
+    store.toggleDoneLane()
+    expect(store.doneLaneCollapsed).toBe(false)
+    store.toggleDoneLane()
+    expect(store.doneLaneCollapsed).toBe(true)
+  })
+})

package/app/stores/laneView.ts

@@ -0,0 +1,85 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import {
+  isLaneGroupKey,
+  isLaneSortKey,
+  type LaneGroupKey,
+  type LaneSortKey,
+} from '~/utils/laneSort'
+
+/**
+ * How this reader wants a frame's swimlanes ordered and grouped, plus whether the Done lane
+ * is open.
+ *
+ * Per USER and per BROWSER, persisted like the interface tier and the agent tier. That is a
+ * deliberate split from the Done lane's two CAPS, which are per-workspace settings: what the
+ * board may show is a shared decision about a service's history, while the order a reader
+ * scans it in is personal and changes several times an hour. Making the order shared would
+ * mean one person's triage sweep re-arranging everyone else's board.
+ *
+ * `sortKey` defaults to `smart`, which is per-lane (see `SMART_ORDER_BY_LANE`) rather than one
+ * global order — the actionable order genuinely differs by column. The explicit keys are an
+ * OVERRIDE of that, which is why the control offering them is an advanced-tier affordance:
+ * hiding it in basic mode leaves exactly the default it would have shown.
+ */
+export const useLaneViewStore = defineStore(
+  'laneView',
+  () => {
+    // Stored raw and narrowed on read, the same split `uiMode` uses for `storedMode`. A setup
+    // store can only persist what it returns, so these are reachable directly; the narrowing
+    // below is what makes that safe rather than a trust assumption.
+    const storedSortKey = ref<string>('smart')
+    const storedGroupKey = ref<string>('none')
+    /**
+     * Collapsed by default. The lane's job is to prove finished work exists and give a route
+     * to it, and a service with a long history would otherwise open as a wall of merged
+     * cards nobody asked to read.
+     */
+    const doneLaneCollapsed = ref(true)
+
+    const sortKey = computed<LaneSortKey>(() =>
+      isLaneSortKey(storedSortKey.value) ? storedSortKey.value : 'smart',
+    )
+    const groupKey = computed<LaneGroupKey>(() =>
+      isLaneGroupKey(storedGroupKey.value) ? storedGroupKey.value : 'none',
+    )
+
+    /**
+     * Whether the reader has overridden the defaults. Drives `showOverrideField`, so a
+     * preference set in advanced mode stays visible (and clearable) after a switch to basic
+     * — the one case where hiding an override would conceal a setting the board is using.
+     */
+    const hasOverride = computed(() => sortKey.value !== 'smart' || groupKey.value !== 'none')
+
+    function setSortKey(next: LaneSortKey) {
+      storedSortKey.value = next
+    }
+
+    function setGroupKey(next: LaneGroupKey) {
+      storedGroupKey.value = next
+    }
+
+    function reset() {
+      storedSortKey.value = 'smart'
+      storedGroupKey.value = 'none'
+    }
+
+    function toggleDoneLane() {
+      doneLaneCollapsed.value = !doneLaneCollapsed.value
+    }
+
+    return {
+      storedSortKey,
+      storedGroupKey,
+      doneLaneCollapsed,
+      sortKey,
+      groupKey,
+      hasOverride,
+      setSortKey,
+      setGroupKey,
+      reset,
+      toggleDoneLane,
+    }
+  },
+  { persist: { pick: ['storedSortKey', 'storedGroupKey', 'doneLaneCollapsed'] } },
+)

package/app/stores/launchPrompt.ts

@@ -0,0 +1,63 @@
+import { ref } from 'vue'
+
+/**
+ * The state machine behind a ONCE-PER-SESSION launch offer: the tutorial's "take a tour?"
+ * (`stores/tutorial.ts`) and the role question (`stores/uiRole.ts`) are the same shape, so
+ * they share this rather than each re-deriving it.
+ *
+ * It is a small machine with four distinguishable exits and no other job, which is what makes
+ * it a seam worth having rather than four refs among twenty: closing without answering, an
+ * explicit decline (the caller's own, since only it knows what a decision IS), a DEFERRAL
+ * (something the user must actually answer opened on top), and the once-per-session auto-open
+ * are four different things, and only some of them write anything down. The subtlety they share
+ * is the ONE-OFFER-PER-SESSION guard, which is why they belong together: `promptAutoOpened`
+ * must be spent by an offer the user saw and NOT by one that was withdrawn.
+ *
+ * `hasDecision` is a bound getter over the caller's persisted record rather than the record
+ * itself, so this module never learns what a decision IS — only whether one exists, which is
+ * the whole of what the offer needs.
+ */
+export function createLaunchPrompt(deps: { hasDecision: () => boolean }) {
+  const promptOpen = ref(false)
+  /** Once-per-session guard for the launch auto-open; later opens are user-driven. */
+  const promptAutoOpened = ref(false)
+
+  /**
+   * Auto-open the launch prompt, at most once per session and only while the user has never
+   * answered it. Callers gate on the rest of the launch context (board ready, no other startup
+   * advisory open) — see `pages/index.vue`.
+   */
+  function maybeOfferOnLaunch() {
+    if (deps.hasDecision() || promptAutoOpened.value) return
+    promptAutoOpened.value = true
+    promptOpen.value = true
+  }
+
+  /** User-driven open (command palette), regardless of any saved decision. */
+  function openPrompt() {
+    promptOpen.value = true
+  }
+
+  /**
+   * Withdraw an offer this store made, because something the user actually has to answer (a
+   * startup advisory, the GitHub onboarding gate) opened on top of it — and re-arm, so the offer
+   * returns once that surface is gone. Distinct from {@link closePrompt}: no decision is written
+   * EITHER way, but a deferral was not the user's doing, so it must not consume this session's
+   * one offer.
+   *
+   * Only ever withdraws the AUTO-opened prompt; a prompt the user opened themselves from the
+   * palette is theirs to close.
+   */
+  function deferPrompt() {
+    if (!promptAutoOpened.value) return
+    promptOpen.value = false
+    promptAutoOpened.value = false
+  }
+
+  /** Close without answering: no decision is written, so the next launch asks again. */
+  function closePrompt() {
+    promptOpen.value = false
+  }
+
+  return { promptOpen, promptAutoOpened, maybeOfferOnLaunch, openPrompt, deferPrompt, closePrompt }
+}

package/app/stores/taskExpansion.spec.ts

@@ -4,7 +4,7 @@ import { useUiStore } from '~/stores/ui'
 
 /**
  * The expansion gate combines two independent grants (hover at any zoom, the deep zoom
- * bands otherwise). Both `TaskPipelineMini` (what renders) and `DraggableTask` (what
+ * bands otherwise). Both `TaskPipelineMini` (what renders) and `LaneTask` (what
  * stacks on top) read `isExpanded`, so these cases pin the rule they share.
  *
  * Zoom is set through the ui store's raw `zoom`, the same value the board canvas writes;

package/app/stores/taskExpansion.ts

@@ -8,7 +8,7 @@ import { useUiStore } from '~/stores/ui'
  *
  * Two independent grants, both written every frame by the board driver
  * (`useTaskExpansion`) and combined HERE so the render (`TaskPipelineMini`) and the
- * stacking (`DraggableTask`) can never disagree about which cards are expanded:
+ * stacking (`LaneTask`) can never disagree about which cards are expanded:
  *
  *  - HOVER — the card under the pointer expands at ANY zoom level. Pointing at a task
  *    is asking what it is doing right now, and that answer used to be reachable only