@cat-factory/app 0.196.0 → 0.197.0

package/app/pages/index.vue

@@ -138,6 +138,15 @@ const AiProviderOnboardingModal = defineAsyncComponent(
 const AiPresetMismatchDialog = defineAsyncComponent(
   () => import('~/components/providers/AiPresetMismatchDialog.vue'),
 )
+// The in-app tutorial: the launch prompt (auto-opened once for a user who never answered
+// it) and the coach-mark overlay that runs a tour. Both mount only while their store flag
+// is set, so they cost the initial bundle nothing.
+const TutorialPrompt = defineAsyncComponent(
+  () => import('~/components/tutorial/TutorialPrompt.vue'),
+)
+const TutorialOverlay = defineAsyncComponent(
+  () => import('~/components/tutorial/TutorialOverlay.vue'),
+)
 
 const workspace = useWorkspaceStore()
 const github = useGitHubStore()
@@ -267,6 +276,56 @@ watch(
   { immediate: true },
 )
 
+// 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.
+//
+// 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,
+// which is the stacking this ordering exists to prevent. So the same watcher withdraws
+// an unanswered prompt and re-arms the offer, and the user is asked once the advisory
+// they actually have to answer is gone.
+//
+// The watcher exists only while it can still do something. A saved decision (hydrated
+// synchronously from the persisted store) means it never registers, and once a decision
+// lands — or the offer has been made and left standing — it stops itself, so the steady
+// state pays nothing for the launch offer: no watcher, no mounted component (the v-ifs
+// below), no store reads.
+const tutorial = useTutorialStore()
+const startupAdvisoryOpen = computed(
+  () =>
+    needsGitHubInstall.value ||
+    githubProbePending.value ||
+    ui.pipelineHealthOpen ||
+    ui.riskPolicyHealthOpen ||
+    ui.modelPresetHealthOpen ||
+    ui.aiProviderSetupOpen ||
+    ui.aiPresetMismatchOpen,
+)
+// 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).
+const tutorialOfferSettled = () =>
+  tutorial.decision !== null || (tutorial.promptAutoOpened && !tutorial.promptOpen)
+if (!tutorialOfferSettled()) {
+  // `let` + optional call: with `immediate: true` the first run happens synchronously
+  // inside `watch(...)`, before the handle is assigned — the trailing check covers it.
+  let stopTutorialOffer: (() => void) | undefined
+  stopTutorialOffer = watch(
+    () => [workspace.ready, startupAdvisoryOpen.value, tutorial.promptOpen],
+    () => {
+      if (startupAdvisoryOpen.value) tutorial.deferPrompt()
+      else if (workspace.ready) tutorial.maybeOfferOnLaunch()
+      if (tutorialOfferSettled()) stopTutorialOffer?.()
+    },
+    { immediate: true },
+  )
+  if (tutorialOfferSettled()) stopTutorialOffer()
+}
+
 // Probe the GitHub integration as soon as a board is active (re-probe per board —
 // connections are per workspace). The result drives the onboarding gate below
 // before the board mounts, so an unconnected user can't slip past it. `ensureProbed`
@@ -448,6 +507,8 @@ watch(
       <VendorCredentialsModal v-if="ui.vendorCredentialsOpen" />
       <AiProviderOnboardingModal v-if="ui.aiProviderSetupOpen" />
       <AiPresetMismatchDialog v-if="ui.aiPresetMismatchOpen" />
+      <TutorialPrompt v-if="tutorial.promptOpen" />
+      <TutorialOverlay v-if="tutorial.touring" />
     </template>
 
     <!-- Backend unreachable / bootstrap failed -->

package/app/stores/board/dependencies.ts

@@ -0,0 +1,52 @@
+import { useWorkspaceStore } from '~/stores/workspace'
+import type { BoardWriteContext } from './context'
+
+/**
+ * The board's dependency-edge writes. Split out of {@link createBoardPlacement} along the same
+ * seam it was split from {@link createBoardMutations}: it closes over the shared
+ * {@link BoardWriteContext} so behaviour is identical to the original in-closure functions, and
+ * the split is purely to keep every function within the size budget.
+ */
+export function createBoardDependencies(ctx: BoardWriteContext) {
+  const { getBlock, upsert, api, toast, tr } = ctx
+
+  /**
+   * Toggle a dependency edge target -> source (target dependsOn source). The backend
+   * rejects an edge that would close a cycle (422) — surface that as a toast rather than
+   * letting it throw unhandled out of a board gesture.
+   */
+  async function toggleDependency(targetId: string, sourceId: string) {
+    if (targetId === sourceId || !getBlock(targetId)) return
+    try {
+      upsert(await api.toggleDependency(useWorkspaceStore().requireId(), targetId, { sourceId }))
+    } catch (e) {
+      toast.add({
+        title: tr('board.toast.linkFailed'),
+        description: e instanceof Error ? e.message : String(e),
+        icon: 'i-lucide-triangle-alert',
+        color: 'error',
+      })
+    }
+  }
+
+  /** Remove a dependency edge target -> source if it exists. */
+  async function removeDependency(targetId: string, sourceId: string) {
+    const t = getBlock(targetId)
+    if (!t || !t.dependsOn.includes(sourceId)) return
+    // the backend exposes a single toggle; the edge exists, so toggling removes it
+    try {
+      upsert(await api.toggleDependency(useWorkspaceStore().requireId(), targetId, { sourceId }))
+    } catch (e) {
+      // Mirror `toggleDependency`: a failure must surface (and leave the edge visible) rather
+      // than rejecting unhandled with no feedback.
+      toast.add({
+        title: tr('board.toast.unlinkFailed'),
+        description: e instanceof Error ? e.message : String(e),
+        icon: 'i-lucide-triangle-alert',
+        color: 'error',
+      })
+    }
+  }
+
+  return { toggleDependency, removeDependency }
+}

package/app/stores/board/placement.ts

@@ -1,6 +1,7 @@
 import type { UpdateBlockInput } from '@cat-factory/contracts'
 import { useServicesStore } from '~/stores/services'
 import { useWorkspaceStore } from '~/stores/workspace'
+import { createBoardDependencies } from './dependencies'
 import type { BoardWriteContext } from './context'
 import { UNDO_WINDOW_MS } from './context'
 
@@ -215,43 +216,9 @@ export function createBoardPlacement(ctx: BoardWriteContext) {
     }
   }
 
-  /**
-   * Toggle a dependency edge target -> source (target dependsOn source). The backend
-   * rejects an edge that would close a cycle (422) — surface that as a toast rather than
-   * letting it throw unhandled out of a board gesture.
-   */
-  async function toggleDependency(targetId: string, sourceId: string) {
-    if (targetId === sourceId || !getBlock(targetId)) return
-    try {
-      upsert(await api.toggleDependency(useWorkspaceStore().requireId(), targetId, { sourceId }))
-    } catch (e) {
-      toast.add({
-        title: tr('board.toast.linkFailed'),
-        description: e instanceof Error ? e.message : String(e),
-        icon: 'i-lucide-triangle-alert',
-        color: 'error',
-      })
-    }
-  }
-
-  /** Remove a dependency edge target -> source if it exists. */
-  async function removeDependency(targetId: string, sourceId: string) {
-    const t = getBlock(targetId)
-    if (!t || !t.dependsOn.includes(sourceId)) return
-    // the backend exposes a single toggle; the edge exists, so toggling removes it
-    try {
-      upsert(await api.toggleDependency(useWorkspaceStore().requireId(), targetId, { sourceId }))
-    } catch (e) {
-      // Mirror `toggleDependency`: a failure must surface (and leave the edge visible) rather
-      // than rejecting unhandled with no feedback.
-      toast.add({
-        title: tr('board.toast.unlinkFailed'),
-        description: e instanceof Error ? e.message : String(e),
-        icon: 'i-lucide-triangle-alert',
-        color: 'error',
-      })
-    }
-  }
+  // The dependency-edge writes, split along the same seam into a sibling factory over the same
+  // context; re-exposed here so every existing caller is unchanged.
+  const { toggleDependency, removeDependency } = createBoardDependencies(ctx)
 
   return {
     reparentBlock,

package/app/stores/execution/pendingGates.ts

@@ -0,0 +1,109 @@
+import { computed, type Ref } from 'vue'
+import type { Decision, ExecutionInstance, PipelineStep, StepApproval } from '~/types/domain'
+
+/**
+ * The read-only projections of what across every cached run is awaiting a human: the open
+ * decisions and approval gates, their per-block indexes, and the two badge counts.
+ *
+ * Created once in the `execution` store setup over its `instances` ref, so the derivations stay
+ * behaviourally identical to the former in-closure computeds — a size-only extraction mirroring
+ * {@link createExecutionCommands}, not a new seam.
+ */
+export function createPendingGateSelectors(instances: Ref<ExecutionInstance[]>) {
+  /** How many decisions anywhere are awaiting a human. */
+  const pendingDecisionCount = computed(() =>
+    instances.value.reduce(
+      (n, e) => n + e.steps.filter((s) => s.decision && !s.decision.chosen).length,
+      0,
+    ),
+  )
+
+  /** All currently-unresolved decisions across all runs (for the toolbar/queue). */
+  const openDecisions = computed(() => {
+    const out: {
+      instanceId: string
+      blockId: string
+      decision: Decision
+      agentKind: PipelineStep['agentKind']
+    }[] = []
+    for (const e of instances.value) {
+      for (const s of e.steps) {
+        if (s.decision && !s.decision.chosen) {
+          out.push({
+            instanceId: e.id,
+            blockId: e.blockId,
+            decision: s.decision,
+            agentKind: s.agentKind,
+          })
+        }
+      }
+    }
+    return out
+  })
+
+  /** All currently-pending approval gates across all runs (board badges/queue). */
+  const openApprovals = computed(() => {
+    const out: {
+      instanceId: string
+      blockId: string
+      approval: StepApproval
+      agentKind: PipelineStep['agentKind']
+      /**
+       * Whether the gate's proposal is a RENDERING of an artifact the step already committed
+       * (`step.outputIsRendered`). Projected here because a surface that reviews the proposal
+       * WITHOUT the step in hand — the initiative tracker's plan-approval rail — otherwise has
+       * no way to tell a rendered document from the agent's raw transcript summary, and would
+       * present a one-line summary as though it were the artifact.
+       */
+      outputIsRendered: boolean
+    }[] = []
+    for (const e of instances.value) {
+      for (const s of e.steps) {
+        if (s.approval?.status === 'pending') {
+          out.push({
+            instanceId: e.id,
+            blockId: e.blockId,
+            approval: s.approval,
+            agentKind: s.agentKind,
+            outputIsRendered: s.outputIsRendered === true,
+          })
+        }
+      }
+    }
+    return out
+  })
+
+  /**
+   * Open decisions/approvals grouped by the block they belong to, so a board card
+   * resolves its own + its tasks' pending gates with O(1) lookups instead of
+   * re-filtering the global lists once per frame on every execution event.
+   */
+  function groupByBlock<T extends { blockId: string }>(items: T[]): Map<string, T[]> {
+    const map = new Map<string, T[]>()
+    for (const item of items) {
+      const list = map.get(item.blockId)
+      if (list) list.push(item)
+      else map.set(item.blockId, [item])
+    }
+    return map
+  }
+  const decisionsByBlock = computed(() => groupByBlock(openDecisions.value))
+  const approvalsByBlock = computed(() => groupByBlock(openApprovals.value))
+
+  /** How many approval gates anywhere are awaiting a human. */
+  const pendingApprovalCount = computed(() =>
+    instances.value.reduce(
+      (n, e) => n + e.steps.filter((s) => s.approval?.status === 'pending').length,
+      0,
+    ),
+  )
+
+  return {
+    pendingDecisionCount,
+    openDecisions,
+    openApprovals,
+    decisionsByBlock,
+    approvalsByBlock,
+    pendingApprovalCount,
+  }
+}

package/app/stores/execution.ts

@@ -1,7 +1,8 @@
 import { defineStore } from 'pinia'
 import { ref, computed } from 'vue'
-import type { Decision, ExecutionInstance, PipelineStep, StepApproval } from '~/types/domain'
+import type { ExecutionInstance } from '~/types/domain'
 import { createExecutionCommands } from '~/stores/execution/commands'
+import { createPendingGateSelectors } from '~/stores/execution/pendingGates'
 
 /**
  * Running pipeline instances. The simulation engine lives on the backend: this
@@ -188,93 +189,10 @@ export const useExecutionStore = defineStore('execution', () => {
     return runs.find((e) => !isTerminal(e.status)) ?? runs.at(-1)
   }
 
-  /** How many decisions anywhere are awaiting a human. */
-  const pendingDecisionCount = computed(() =>
-    instances.value.reduce(
-      (n, e) => n + e.steps.filter((s) => s.decision && !s.decision.chosen).length,
-      0,
-    ),
-  )
-
-  /** All currently-unresolved decisions across all runs (for the toolbar/queue). */
-  const openDecisions = computed(() => {
-    const out: {
-      instanceId: string
-      blockId: string
-      decision: Decision
-      agentKind: PipelineStep['agentKind']
-    }[] = []
-    for (const e of instances.value) {
-      for (const s of e.steps) {
-        if (s.decision && !s.decision.chosen) {
-          out.push({
-            instanceId: e.id,
-            blockId: e.blockId,
-            decision: s.decision,
-            agentKind: s.agentKind,
-          })
-        }
-      }
-    }
-    return out
-  })
-
-  /** All currently-pending approval gates across all runs (board badges/queue). */
-  const openApprovals = computed(() => {
-    const out: {
-      instanceId: string
-      blockId: string
-      approval: StepApproval
-      agentKind: PipelineStep['agentKind']
-      /**
-       * Whether the gate's proposal is a RENDERING of an artifact the step already committed
-       * (`step.outputIsRendered`). Projected here because a surface that reviews the proposal
-       * WITHOUT the step in hand — the initiative tracker's plan-approval rail — otherwise has
-       * no way to tell a rendered document from the agent's raw transcript summary, and would
-       * present a one-line summary as though it were the artifact.
-       */
-      outputIsRendered: boolean
-    }[] = []
-    for (const e of instances.value) {
-      for (const s of e.steps) {
-        if (s.approval?.status === 'pending') {
-          out.push({
-            instanceId: e.id,
-            blockId: e.blockId,
-            approval: s.approval,
-            agentKind: s.agentKind,
-            outputIsRendered: s.outputIsRendered === true,
-          })
-        }
-      }
-    }
-    return out
-  })
-
-  /**
-   * Open decisions/approvals grouped by the block they belong to, so a board card
-   * resolves its own + its tasks' pending gates with O(1) lookups instead of
-   * re-filtering the global lists once per frame on every execution event.
-   */
-  function groupByBlock<T extends { blockId: string }>(items: T[]): Map<string, T[]> {
-    const map = new Map<string, T[]>()
-    for (const item of items) {
-      const list = map.get(item.blockId)
-      if (list) list.push(item)
-      else map.set(item.blockId, [item])
-    }
-    return map
-  }
-  const decisionsByBlock = computed(() => groupByBlock(openDecisions.value))
-  const approvalsByBlock = computed(() => groupByBlock(openApprovals.value))
-
-  /** How many approval gates anywhere are awaiting a human. */
-  const pendingApprovalCount = computed(() =>
-    instances.value.reduce(
-      (n, e) => n + e.steps.filter((s) => s.approval?.status === 'pending').length,
-      0,
-    ),
-  )
+  // What across every cached run is awaiting a human (open decisions + approval gates, their
+  // per-block indexes and the two badge counts), extracted into a cohesive factory over the same
+  // `instances` ref — a size-only split mirroring `createExecutionCommands` below.
+  const pendingGates = createPendingGateSelectors(instances)
 
   // The run-control commands (start / decide / approve / merge / restart / cancel / stop),
   // extracted into a cohesive factory sharing the state above (a size-only split mirroring
@@ -290,12 +208,7 @@ export const useExecutionStore = defineStore('execution', () => {
     byId,
     getInstance,
     getByBlock,
-    pendingDecisionCount,
-    openDecisions,
-    openApprovals,
-    decisionsByBlock,
-    approvalsByBlock,
-    pendingApprovalCount,
+    ...pendingGates,
     ...commands,
   }
 })

package/app/stores/requirements/recommendations.ts

@@ -0,0 +1,77 @@
+import type { Ref } from 'vue'
+import type { RequestRecommendationItem, RequirementReview } from '~/types/requirements'
+
+/**
+ * Shared state + injected dependencies the recommendation slice closes over. Created once in the
+ * `requirements` store setup and threaded into {@link createRecommendationCommands} so the split
+ * operations stay behaviourally identical to the original single-closure store — a size-only
+ * extraction, not a new seam.
+ */
+export interface RecommendationCommandContext {
+  api: ReturnType<typeof useApi>
+  workspace: ReturnType<typeof useWorkspaceStore>
+  /** Block ids whose Requirement Writer is currently producing recommendations. */
+  recommending: Ref<Set<string>>
+  /** Toggle a block/review id in one of the store's flag sets. */
+  withFlag: (set: Ref<Set<string>>, key: string, on: boolean) => void
+  /** Commit a server-returned review into the cache. */
+  store: (review: RequirementReview) => void
+  /** Whether a `pending` recommendation placeholder still exists for the block (server-derived). */
+  hasPendingRecommendations: (blockId: string) => boolean
+}
+
+/** Ask for, accept, reject and re-request the Requirement Writer's suggested answers. */
+export function createRecommendationCommands(ctx: RecommendationCommandContext) {
+  const { api, workspace, recommending, withFlag, store, hasPendingRecommendations } = ctx
+
+  function isRecommending(blockId: string): boolean {
+    return recommending.value.has(blockId) || hasPendingRecommendations(blockId)
+  }
+
+  /**
+   * Ask the Requirement Writer to recommend answers for a batch of findings. Each item carries
+   * its finding id plus optional per-finding guidance (the note the human typed before choosing
+   * "recommend something"). ASYNCHRONOUS: returns at once with `pending` placeholder
+   * recommendations (the Writer runs per finding in the durable driver), which fill in (`ready`)
+   * via live `requirements` stream events; a notification calls the user back when the batch is
+   * ready. The board shows the `recommending` background stage while any placeholder is pending.
+   */
+  async function requestRecommendations(blockId: string, items: RequestRecommendationItem[]) {
+    withFlag(recommending, blockId, true)
+    try {
+      const updated = await api.requestRecommendations(workspace.requireId(), blockId, items)
+      if (updated) store(updated)
+      return updated
+    } finally {
+      withFlag(recommending, blockId, false)
+    }
+  }
+
+  /** Accept a recommendation (becomes the finding's answer, folded into the next incorporation). */
+  async function acceptRecommendation(review: RequirementReview, recId: string) {
+    store(await api.acceptRecommendation(workspace.requireId(), review.id, recId))
+  }
+
+  /** Reject a recommendation (the human then dismisses / answers manually / re-requests). */
+  async function rejectRecommendation(review: RequirementReview, recId: string) {
+    store(await api.rejectRecommendation(workspace.requireId(), review.id, recId))
+  }
+
+  /** Re-request a recommendation with a "do it differently" note. */
+  async function reRequestRecommendation(review: RequirementReview, recId: string, note: string) {
+    withFlag(recommending, review.blockId, true)
+    try {
+      store(await api.reRequestRecommendation(workspace.requireId(), review.id, recId, note))
+    } finally {
+      withFlag(recommending, review.blockId, false)
+    }
+  }
+
+  return {
+    isRecommending,
+    requestRecommendations,
+    acceptRecommendation,
+    rejectRecommendation,
+    reRequestRecommendation,
+  }
+}

package/app/stores/requirements.ts

@@ -1,12 +1,12 @@
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
 import type {
-  RequestRecommendationItem,
   RequirementReview,
   ResolveRequirementsExceededChoice,
   ReviewItemStatus,
 } from '~/types/requirements'
 import { useWorkspaceStore } from '~/stores/workspace'
+import { createRecommendationCommands } from '~/stores/requirements/recommendations'
 
 /**
  * Requirements-review state. On the pipeline path the reviewer runs as the first gate
@@ -204,48 +204,22 @@ export const useRequirementsStore = defineStore('requirements', () => {
     return updated
   }
 
-  function isRecommending(blockId: string): boolean {
-    return recommending.value.has(blockId) || hasPendingRecommendations(blockId)
-  }
-
-  /**
-   * Ask the Requirement Writer to recommend answers for a batch of findings. Each item carries
-   * its finding id plus optional per-finding guidance (the note the human typed before choosing
-   * "recommend something"). ASYNCHRONOUS: returns at once with `pending` placeholder
-   * recommendations (the Writer runs per finding in the durable driver), which fill in (`ready`)
-   * via live `requirements` stream events; a notification calls the user back when the batch is
-   * ready. The board shows the `recommending` background stage while any placeholder is pending.
-   */
-  async function requestRecommendations(blockId: string, items: RequestRecommendationItem[]) {
-    withFlag(recommending, blockId, true)
-    try {
-      const updated = await api.requestRecommendations(workspace.requireId(), blockId, items)
-      if (updated) store(updated)
-      return updated
-    } finally {
-      withFlag(recommending, blockId, false)
-    }
-  }
-
-  /** Accept a recommendation (becomes the finding's answer, folded into the next incorporation). */
-  async function acceptRecommendation(review: RequirementReview, recId: string) {
-    store(await api.acceptRecommendation(workspace.requireId(), review.id, recId))
-  }
-
-  /** Reject a recommendation (the human then dismisses / answers manually / re-requests). */
-  async function rejectRecommendation(review: RequirementReview, recId: string) {
-    store(await api.rejectRecommendation(workspace.requireId(), review.id, recId))
-  }
-
-  /** Re-request a recommendation with a "do it differently" note. */
-  async function reRequestRecommendation(review: RequirementReview, recId: string, note: string) {
-    withFlag(recommending, review.blockId, true)
-    try {
-      store(await api.reRequestRecommendation(workspace.requireId(), review.id, recId, note))
-    } finally {
-      withFlag(recommending, review.blockId, false)
-    }
-  }
+  // The Requirement Writer recommendation slice (request / accept / reject / re-request),
+  // extracted into a cohesive factory over the state above — a size-only split.
+  const {
+    isRecommending,
+    requestRecommendations,
+    acceptRecommendation,
+    rejectRecommendation,
+    reRequestRecommendation,
+  } = createRecommendationCommands({
+    api,
+    workspace,
+    recommending,
+    withFlag,
+    store,
+    hasPendingRecommendations,
+  })
 
   /** Resolve a capped review: extra-round / proceed / stop-reset. */
   async function resolveExceeded(