@cat-factory/app 0.16.0 → 0.16.1

package/app/components/layout/AiProvidersBanner.vue

@@ -0,0 +1,113 @@
+<script setup lang="ts">
+// Persistent prompt that AI isn't ready, mirroring GitHubPatBanner. Two states, in priority
+// order: (1) no usable model source at all → "Configure AI" reopens the onboarding dialog;
+// (2) usable models exist but the default model preset points at unavailable ones → a milder
+// warning reopening the preset-mismatch dialog. Dismissible per session (the dismissed flags
+// live on the ui store, so the auto-open watcher and this banner share one source of truth).
+import { computed } from 'vue'
+
+const ui = useUiStore()
+const { ready, hasUsableModel, defaultPresetBroken } = useAiReadiness()
+
+const showSetup = computed(() => ready.value && !hasUsableModel.value && !ui.aiSetupDismissed)
+const showPreset = computed(() => ready.value && defaultPresetBroken.value && !ui.aiPresetDismissed)
+// The no-AI prompt owns the screen when nothing works; the preset prompt is secondary.
+const show = computed(() => showSetup.value || showPreset.value)
+</script>
+
+<template>
+  <Transition name="fade">
+    <div v-if="show" class="absolute inset-x-0 top-0 z-40 flex justify-center px-4 pt-4">
+      <!-- (1) No usable AI source -->
+      <div
+        v-if="showSetup"
+        class="w-full max-w-3xl rounded-2xl border-2 border-amber-500/70 bg-amber-950/95 p-5 shadow-2xl backdrop-blur"
+        role="alert"
+      >
+        <div class="flex items-start gap-4">
+          <UIcon name="i-lucide-cpu" class="mt-0.5 h-9 w-9 shrink-0 text-amber-400" />
+          <div class="min-w-0 flex-1">
+            <div class="flex items-start justify-between gap-3">
+              <h2 class="text-lg font-semibold text-amber-100">No AI model configured</h2>
+              <UButton
+                color="neutral"
+                variant="ghost"
+                size="xs"
+                icon="i-lucide-x"
+                aria-label="Dismiss"
+                @click="ui.dismissAiSetup()"
+              />
+            </div>
+            <p class="mt-1 text-sm text-amber-200/90">
+              Agents need a model to run. AI works out of the box only on a Cloudflare deployment
+              with Workers AI enabled — otherwise connect a provider key, subscription, proxy, or
+              local runner to continue.
+            </p>
+            <div class="mt-4">
+              <UButton
+                color="warning"
+                variant="solid"
+                icon="i-lucide-settings"
+                @click="ui.openAiProviderSetup()"
+              >
+                Configure AI
+              </UButton>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <!-- (2) Default preset references unavailable models -->
+      <div
+        v-else
+        class="w-full max-w-3xl rounded-2xl border border-amber-500/50 bg-amber-950/90 p-4 shadow-xl backdrop-blur"
+        role="alert"
+      >
+        <div class="flex items-start gap-3">
+          <UIcon name="i-lucide-triangle-alert" class="mt-0.5 h-7 w-7 shrink-0 text-amber-400" />
+          <div class="min-w-0 flex-1">
+            <div class="flex items-start justify-between gap-3">
+              <h2 class="text-sm font-semibold text-amber-100">
+                Default model preset uses unavailable models
+              </h2>
+              <UButton
+                color="neutral"
+                variant="ghost"
+                size="xs"
+                icon="i-lucide-x"
+                aria-label="Dismiss"
+                @click="ui.dismissAiPresetMismatch()"
+              />
+            </div>
+            <p class="mt-1 text-[13px] text-amber-200/90">
+              Tasks using the default preset would fail. Edit the preset or configure the missing
+              provider.
+            </p>
+            <div class="mt-3">
+              <UButton
+                size="sm"
+                color="warning"
+                variant="solid"
+                icon="i-lucide-cpu"
+                @click="ui.openAiPresetMismatch()"
+              >
+                Review preset
+              </UButton>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </Transition>
+</template>
+
+<style scoped>
+.fade-enter-active,
+.fade-leave-active {
+  transition: opacity 0.2s ease;
+}
+.fade-enter-from,
+.fade-leave-to {
+  opacity: 0;
+}
+</style>

package/app/components/panels/inspector/TaskRunSettings.vue

@@ -8,9 +8,12 @@ const props = defineProps<{ block: Block }>()
 const board = useBoardStore()
 const mergePresets = useMergePresetsStore()
 const modelPresets = useModelPresetsStore()
+const models = useModelsStore()
 const pipelines = usePipelinesStore()
 const accounts = useAccountsStore()
 const tracker = useTrackerStore()
+const ui = useUiStore()
+const { ready, unavailableInPreset } = useAiReadiness()
 
 // ---- responsible product person --------------------------------------------
 // The account member (a `product` role-holder) accountable for this task; they are
@@ -73,6 +76,17 @@ function setPreset(id: string) {
 // (a running step keeps the model it was dispatched with). A model pinned directly on
 // the task still overrides the preset.
 const selectedModelPreset = computed(() => modelPresets.resolve(props.block.modelPresetId))
+
+// Model ids in the chosen preset that aren't usable under the current configuration — the
+// task would fail when a step dispatches onto one. Labelled for the inline warning below.
+// Gated on `ready`: until the per-workspace catalog has loaded, `isUsableId` reports every
+// model unusable, which would surface a spurious "this task would fail" warning (e.g. while
+// the catalog fetch is in flight, or if it failed) — so only flag once the catalog is known.
+const unavailablePresetModels = computed(() =>
+  ready.value
+    ? unavailableInPreset(selectedModelPreset.value).map((id) => models.labelForId(id))
+    : [],
+)
 const modelPresetMenu = computed(() => [
   [
     {
@@ -243,6 +257,38 @@ const resolveOnMergeLabel = computed(() =>
       <div v-else class="text-[11px] text-slate-500">
         No preset configured — agents run on the deployment's default routing.
       </div>
+      <div
+        v-if="unavailablePresetModels.length"
+        class="mt-2 rounded-md border border-amber-500/40 bg-amber-950/40 p-2 text-[11px] text-amber-200/90"
+      >
+        <div class="flex items-start gap-1.5">
+          <UIcon
+            name="i-lucide-triangle-alert"
+            class="mt-0.5 h-3.5 w-3.5 shrink-0 text-amber-400"
+          />
+          <div class="min-w-0">
+            <p>
+              Not available under the current configuration:
+              <span class="text-amber-100">{{ unavailablePresetModels.join(', ') }}</span
+              >. This task would fail on those steps.
+            </p>
+            <div class="mt-1.5 flex flex-wrap gap-2">
+              <button
+                class="font-medium text-amber-100 underline-offset-2 hover:underline"
+                @click="ui.openModelConfig()"
+              >
+                Edit presets
+              </button>
+              <button
+                class="font-medium text-amber-100 underline-offset-2 hover:underline"
+                @click="ui.openVendorCredentials()"
+              >
+                Configure vendors
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
       <p class="mt-1 text-[11px] text-slate-500">
         Changing this affects only steps that haven't started yet.
       </p>

package/app/components/providers/AiPresetMismatchDialog.vue

@@ -0,0 +1,84 @@
+<script setup lang="ts">
+// Shown when the workspace HAS usable AI models but its DEFAULT model preset still points
+// at one or more that aren't usable under the current configuration (e.g. the built-in
+// "Kimi K2.7" default with no Kimi source connected). Tasks fall back to the default
+// preset, so they would dispatch onto an unavailable model and fail. This dialog names the
+// offending models and offers to edit/switch the preset or configure more vendors. It
+// auto-opens once per session (driven from pages/index.vue) and clears once the preset is
+// fixed (or all its models become available).
+import { computed } from 'vue'
+
+const ui = useUiStore()
+const models = useModelsStore()
+const modelPresets = useModelPresetsStore()
+const { defaultPresetUnavailable } = useAiReadiness()
+
+const open = computed({
+  get: () => ui.aiPresetMismatchOpen,
+  set: (v: boolean) => (v ? ui.openAiPresetMismatch() : ui.closeAiPresetMismatch()),
+})
+
+const presetName = computed(() => modelPresets.defaultPreset?.name ?? 'default preset')
+
+/** Readable labels for the unavailable model ids (catalog label, else the raw id). */
+const unavailableLabels = computed(() =>
+  defaultPresetUnavailable.value.map((id) => models.labelForId(id)),
+)
+
+function go(action: () => void) {
+  ui.closeAiPresetMismatch()
+  action()
+}
+</script>
+
+<template>
+  <UModal v-model:open="open" title="Preset uses unavailable models" :ui="{ content: 'max-w-xl' }">
+    <template #body>
+      <div class="space-y-5">
+        <p class="text-sm text-slate-300">
+          The workspace default model preset
+          <span class="font-medium text-slate-100">“{{ presetName }}”</span>
+          assigns models that aren't available under the current configuration. Tasks that use this
+          preset would fail when they reach those steps.
+        </p>
+
+        <div class="rounded-lg border border-slate-700 bg-slate-900/50 p-3">
+          <p class="mb-1.5 text-[11px] font-semibold uppercase tracking-wide text-slate-500">
+            Unavailable
+          </p>
+          <div class="flex flex-wrap gap-1.5">
+            <UBadge
+              v-for="label in unavailableLabels"
+              :key="label"
+              color="warning"
+              variant="subtle"
+              size="sm"
+            >
+              {{ label }}
+            </UBadge>
+          </div>
+        </div>
+
+        <p class="text-[13px] text-slate-400">
+          Either repoint the preset at models you have configured, or add the missing provider.
+        </p>
+
+        <div class="flex flex-wrap justify-end gap-2">
+          <UButton color="neutral" variant="ghost" size="sm" @click="open = false"> Later </UButton>
+          <UButton
+            color="neutral"
+            variant="subtle"
+            size="sm"
+            icon="i-lucide-key-round"
+            @click="go(ui.openVendorCredentials)"
+          >
+            Configure vendors
+          </UButton>
+          <UButton color="primary" size="sm" icon="i-lucide-cpu" @click="go(ui.openModelConfig)">
+            Edit presets
+          </UButton>
+        </div>
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/components/providers/AiProviderOnboardingModal.vue

@@ -0,0 +1,106 @@
+<script setup lang="ts">
+// Shown when the workspace has NO usable AI model source. cat-factory only ships a working
+// model out of the box on a Cloudflare deployment with Workers AI enabled; every other
+// deployment needs the user to onboard at least one source. This dialog explains that and
+// routes to each configuration surface (reusing the existing credential panels rather than
+// duplicating them). It auto-opens once per session (driven from pages/index.vue) and, like
+// the banner, disappears automatically the moment a usable source exists.
+import { computed } from 'vue'
+
+const ui = useUiStore()
+
+const open = computed({
+  get: () => ui.aiProviderSetupOpen,
+  set: (v: boolean) => (v ? ui.openAiProviderSetup() : ui.closeAiProviderSetup()),
+})
+
+// Each route closes this dialog first so we never stack two modals, then opens the target
+// panel. All of these panels are mounted in pages/index.vue alongside this one.
+function go(action: () => void) {
+  ui.closeAiProviderSetup()
+  action()
+}
+
+interface Route {
+  icon: string
+  title: string
+  body: string
+  cta: string
+  onSelect: () => void
+}
+
+const routes = computed<Route[]>(() => [
+  {
+    icon: 'i-lucide-key-round',
+    title: 'Provider keys & subscriptions',
+    body: 'Add a direct provider API key (OpenAI, Anthropic, Qwen, …) or connect a commercial coding-plan subscription (Kimi, DeepSeek) or a personal one (Claude, GLM, Codex).',
+    cta: 'Open LLM vendors',
+    onSelect: () => go(ui.openVendorCredentials),
+  },
+  {
+    icon: 'i-lucide-route',
+    title: 'OpenRouter gateway',
+    body: 'Enable models through the OpenRouter gateway with a single key — browse and turn on the models you want.',
+    cta: 'Browse OpenRouter models',
+    onSelect: () => go(ui.openOpenRouter),
+  },
+  {
+    icon: 'i-lucide-server',
+    title: 'My local runners',
+    body: 'Point cat-factory at a model you run yourself (Ollama, LM Studio, llama.cpp, vLLM, …). No API key, no spend.',
+    cta: 'Configure local runners',
+    onSelect: () => go(ui.openLocalModels),
+  },
+])
+</script>
+
+<template>
+  <UModal v-model:open="open" title="Set up an AI model provider" :ui="{ content: 'max-w-2xl' }">
+    <template #body>
+      <div class="space-y-5">
+        <div
+          class="flex items-start gap-3 rounded-lg border border-amber-500/40 bg-amber-950/40 p-4"
+        >
+          <UIcon name="i-lucide-cpu" class="mt-0.5 h-6 w-6 shrink-0 text-amber-400" />
+          <div class="min-w-0 text-sm text-amber-100/90">
+            <p class="font-medium text-amber-100">
+              No AI model is available on this workspace yet.
+            </p>
+            <p class="mt-1">
+              Agents need a model to run. AI works out of the box only on a Cloudflare deployment
+              with Workers AI enabled — otherwise connect at least one source below.
+            </p>
+          </div>
+        </div>
+
+        <div class="space-y-3">
+          <div
+            v-for="r in routes"
+            :key="r.title"
+            class="flex items-start gap-3 rounded-xl border border-slate-700 bg-slate-900/50 p-4"
+          >
+            <UIcon :name="r.icon" class="mt-0.5 h-5 w-5 shrink-0 text-indigo-300" />
+            <div class="min-w-0 flex-1">
+              <p class="text-sm font-semibold text-slate-100">{{ r.title }}</p>
+              <p class="mt-0.5 text-[13px] leading-relaxed text-slate-400">{{ r.body }}</p>
+            </div>
+            <UButton
+              size="sm"
+              color="primary"
+              variant="subtle"
+              class="shrink-0"
+              @click="r.onSelect()"
+            >
+              {{ r.cta }}
+            </UButton>
+          </div>
+        </div>
+
+        <p class="text-[11px] leading-relaxed text-slate-500">
+          AWS Bedrock and Cloudflare Workers AI are enabled by the deployment operator via
+          environment configuration, not from this screen.
+        </p>
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/composables/useAiReadiness.ts

@@ -0,0 +1,62 @@
+import type { ModelPreset } from '~/types/model-presets'
+
+/**
+ * AI-configuration readiness for the active workspace. cat-factory only ships a usable
+ * AI model out of the box on a Cloudflare deployment with Workers AI enabled; every other
+ * deployment needs the user to onboard at least one source (a provider key, a pooled /
+ * personal subscription, a proxy, Bedrock, or a local runner). This composable turns the
+ * per-workspace model catalog (whose `available` flag already reflects all of those) plus
+ * the workspace's model presets into the two signals the onboarding surfaces consume:
+ *
+ *  - `hasUsableModel` — is ANY AI source configured at all? (false ⇒ the no-AI prompt)
+ *  - `defaultPresetBroken` — the workspace has usable models, but its DEFAULT model preset
+ *    still points at one or more that aren't usable (⇒ the preset-mismatch prompt). Gated on
+ *    `hasUsableModel` so the no-AI prompt owns the "nothing works" case on its own.
+ *
+ * Read-only over the existing stores; the catalog is loaded elsewhere (on workspace-ready
+ * and after credential edits), so `ready` simply reports whether that load has landed for
+ * the active workspace.
+ */
+export function useAiReadiness() {
+  const models = useModelsStore()
+  const modelPresets = useModelPresetsStore()
+  const workspace = useWorkspaceStore()
+
+  /** The per-workspace catalog has loaded for the workspace currently open. */
+  const ready = computed(
+    () =>
+      models.loaded &&
+      workspace.workspaceId != null &&
+      models.loadedWorkspaceId === workspace.workspaceId,
+  )
+
+  const hasUsableModel = computed(() => models.hasUsableModel)
+
+  /** Every distinct catalog model id a preset assigns (base + overrides). */
+  function presetModelIds(preset: ModelPreset | null): string[] {
+    if (!preset) return []
+    return [...new Set([preset.baseModelId, ...Object.values(preset.overrides)])]
+  }
+
+  /** The preset's assigned model ids that aren't usable under the current configuration. */
+  function unavailableInPreset(preset: ModelPreset | null): string[] {
+    return presetModelIds(preset).filter((id) => !models.isUsableId(id))
+  }
+
+  /** Unusable model ids in the workspace DEFAULT preset (what tasks fall back to). */
+  const defaultPresetUnavailable = computed(() => unavailableInPreset(modelPresets.defaultPreset))
+
+  /** Usable models exist, but the default preset still references unusable ones. */
+  const defaultPresetBroken = computed(
+    () => hasUsableModel.value && defaultPresetUnavailable.value.length > 0,
+  )
+
+  return {
+    ready,
+    hasUsableModel,
+    presetModelIds,
+    unavailableInPreset,
+    defaultPresetUnavailable,
+    defaultPresetBroken,
+  }
+}

package/app/pages/index.vue

@@ -4,6 +4,7 @@ import SideBar from '~/components/layout/SideBar.vue'
 import BoardToolbar from '~/components/layout/BoardToolbar.vue'
 import SpendWarningBanner from '~/components/layout/SpendWarningBanner.vue'
 import GitHubPatBanner from '~/components/layout/GitHubPatBanner.vue'
+import AiProvidersBanner from '~/components/layout/AiProvidersBanner.vue'
 import PipelineBuilder from '~/components/pipeline/PipelineBuilder.vue'
 import InspectorPanel from '~/components/panels/InspectorPanel.vue'
 import DecisionModal from '~/components/panels/DecisionModal.vue'
@@ -33,13 +34,72 @@ import LocalModelEndpointsPanel from '~/components/settings/LocalModelEndpointsP
 import OpenRouterCatalogPanel from '~/components/settings/OpenRouterCatalogPanel.vue'
 import VendorCredentialsModal from '~/components/providers/VendorCredentialsModal.vue'
 import PersonalCredentialModal from '~/components/providers/PersonalCredentialModal.vue'
+import AiProviderOnboardingModal from '~/components/providers/AiProviderOnboardingModal.vue'
+import AiPresetMismatchDialog from '~/components/providers/AiPresetMismatchDialog.vue'
 
 const workspace = useWorkspaceStore()
 const github = useGitHubStore()
+const models = useModelsStore()
+const ui = useUiStore()
+const aiReadiness = useAiReadiness()
 
 // Load the board from the backend before rendering it.
 onMounted(() => workspace.init())
 
+// Per-session guards so each AI-onboarding dialog auto-opens at most once (later opens are
+// user-driven from the banner). Reset on workspace switch by the catalog watcher below.
+const autoOpenedSetup = ref(false)
+const autoOpenedPreset = ref(false)
+
+// Load the per-workspace model catalog as soon as a board is active (re-loaded per board —
+// availability reflects that workspace's keys/subscriptions). This populates the AI-readiness
+// signals regardless of which lazy picker happens to mount, so the onboarding prompts below
+// can fire. Credential edits re-fetch via `models.refresh()` in the provider panels.
+watch(
+  () => workspace.workspaceId,
+  (id, prev) => {
+    if (id) void models.ensureLoaded(id)
+    // Switching workspaces resets the per-session AI-onboarding state: dismissals and the
+    // auto-open guards are scoped to one workspace, so a prompt dismissed in workspace A must
+    // not suppress the (independent) prompt for workspace B that also lacks a usable source.
+    if (prev !== undefined && id !== prev) {
+      autoOpenedSetup.value = false
+      autoOpenedPreset.value = false
+      ui.resetAiOnboarding()
+    }
+  },
+  { immediate: true },
+)
+
+// Auto-open the right AI-onboarding dialog once per session: the no-source prompt takes
+// precedence over the preset-mismatch prompt. Honour the per-session dismissed flags so a
+// user who closed the banner isn't re-interrupted, and only auto-open once each (later opens
+// are user-driven from the banner). The prompts clear themselves once the gap is closed.
+watch(
+  () => [
+    aiReadiness.ready.value,
+    aiReadiness.hasUsableModel.value,
+    aiReadiness.defaultPresetBroken.value,
+  ],
+  () => {
+    if (!aiReadiness.ready.value) return
+    if (!aiReadiness.hasUsableModel.value) {
+      if (!autoOpenedSetup.value && !ui.aiSetupDismissed) {
+        autoOpenedSetup.value = true
+        ui.openAiProviderSetup()
+      }
+      return
+    }
+    if (aiReadiness.defaultPresetBroken.value) {
+      if (!autoOpenedPreset.value && !ui.aiPresetDismissed) {
+        autoOpenedPreset.value = true
+        ui.openAiPresetMismatch()
+      }
+    }
+  },
+  { immediate: true },
+)
+
 // 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. SideBar
@@ -75,6 +135,8 @@ watch(
   <div class="flex h-screen w-screen overflow-hidden bg-slate-950 text-slate-100">
     <!-- Local-mode setup prompt (missing GitHub PAT); floats over whatever is shown below. -->
     <GitHubPatBanner />
+    <!-- AI-readiness prompt (no usable model source, or default preset uses unavailable models). -->
+    <AiProvidersBanner v-if="workspace.ready && !needsGitHubInstall && !githubProbePending" />
 
     <!-- Resolving whether the GitHub App is installed, before we decide what to show. -->
     <div
@@ -124,6 +186,8 @@ watch(
       <OpenRouterCatalogPanel />
       <VendorCredentialsModal />
       <PersonalCredentialModal />
+      <AiProviderOnboardingModal />
+      <AiPresetMismatchDialog />
     </template>
 
     <!-- Backend unreachable / bootstrap failed -->

package/app/stores/models.ts

@@ -116,6 +116,28 @@ export const useModelsStore = defineStore('models', () => {
     return id ? byId.value.get(id) : undefined
   }
 
+  /** Readable label for a catalog model id: the catalog label, else the raw id. */
+  function labelForId(id: string): string {
+    return byId.value.get(id)?.label ?? id
+  }
+
+  /**
+   * Whether the workspace has at least one usable AI model source right now. The
+   * per-workspace catalog already resolves `available` from the configured keys /
+   * subscriptions / Cloudflare opt-in / local runners, so this is the single signal for
+   * "is any AI configured at all". Only meaningful once the per-workspace catalog has
+   * loaded (`loadedWorkspaceId` set); the deployment catalog leaves `available` undefined.
+   */
+  const hasUsableModel = computed(() => models.value.some((m) => m.available === true))
+
+  /**
+   * Whether a specific catalog model id is usable under the current configuration. An id
+   * absent from the catalog (e.g. a model that was removed) counts as not usable.
+   */
+  function isUsableId(id: string): boolean {
+    return byId.value.get(id)?.available === true
+  }
+
   /**
    * Friendly label for a recorded `provider:model` identifier (as carried on a
    * pipeline step). Matches it against the catalog's effective refs; falls back
@@ -130,5 +152,17 @@ export const useModelsStore = defineStore('models', () => {
     return hit ? `${hit.label} · ${hit.providerLabel}` : model || ref
   }
 
-  return { models, loaded, ensureLoaded, refresh, byId, getModel, labelForRef }
+  return {
+    models,
+    loaded,
+    loadedWorkspaceId,
+    ensureLoaded,
+    refresh,
+    byId,
+    getModel,
+    labelForId,
+    hasUsableModel,
+    isUsableId,
+    labelForRef,
+  }
 })

package/app/stores/ui.ts

@@ -88,6 +88,16 @@ export const useUiStore = defineStore('ui', () => {
   // Per-workspace settings panel: the OpenRouter dynamic catalog (browse/enable gateway models).
   const openRouterOpen = ref(false)
 
+  // AI-onboarding surfaces (driven by `useAiReadiness`). `aiProviderSetupOpen` is the
+  // "no usable AI source" dialog; `aiPresetMismatchOpen` is the "default preset points at
+  // unavailable models" dialog. The `*Dismissed` flags are per-session: they suppress the
+  // auto-open (and let the banner be dismissed) without permanently hiding the prompt — it
+  // re-evaluates on the next load. Both clear themselves once the underlying gap is closed.
+  const aiProviderSetupOpen = ref(false)
+  const aiPresetMismatchOpen = ref(false)
+  const aiSetupDismissed = ref(false)
+  const aiPresetDismissed = ref(false)
+
   // Dedicated result-view overlay: a step whose agent kind declares a bespoke
   // visualization (via the archetype's `resultView`) opens here instead of the generic
   // prose step-detail panel. `view` is the registry id (e.g. 'requirements-review');
@@ -330,6 +340,39 @@ export const useUiStore = defineStore('ui', () => {
   function closeOpenRouter() {
     openRouterOpen.value = false
   }
+  function openAiProviderSetup() {
+    aiProviderSetupOpen.value = true
+  }
+  function closeAiProviderSetup() {
+    aiProviderSetupOpen.value = false
+  }
+  function openAiPresetMismatch() {
+    aiPresetMismatchOpen.value = true
+  }
+  function closeAiPresetMismatch() {
+    aiPresetMismatchOpen.value = false
+  }
+  // Banner dismissal is distinct from closing the dialog: closing the dialog leaves the
+  // banner so the user can reopen it; dismissing the banner hides the whole prompt for
+  // the session (it re-evaluates on the next load).
+  function dismissAiSetup() {
+    aiProviderSetupOpen.value = false
+    aiSetupDismissed.value = true
+  }
+  function dismissAiPresetMismatch() {
+    aiPresetMismatchOpen.value = false
+    aiPresetDismissed.value = true
+  }
+  // Clear the per-session AI-onboarding state (open dialogs + dismissed flags). Called on
+  // workspace switch: dismissals are per-session-per-workspace, so a prompt dismissed in one
+  // workspace must not suppress the (independent) prompt for another workspace that also
+  // lacks a usable AI source / has a broken default preset.
+  function resetAiOnboarding() {
+    aiProviderSetupOpen.value = false
+    aiPresetMismatchOpen.value = false
+    aiSetupDismissed.value = false
+    aiPresetDismissed.value = false
+  }
   function openRequirementReview(blockId: string) {
     resultView.value = { view: 'requirements-review', blockId, instanceId: null, stepIndex: null }
   }
@@ -384,6 +427,10 @@ export const useUiStore = defineStore('ui', () => {
     vendorCredentialsOpen,
     localModelsOpen,
     openRouterOpen,
+    aiProviderSetupOpen,
+    aiPresetMismatchOpen,
+    aiSetupDismissed,
+    aiPresetDismissed,
     resultView,
     closeResultView,
     stepDetail,
@@ -442,6 +489,13 @@ export const useUiStore = defineStore('ui', () => {
     closeLocalModels,
     openOpenRouter,
     closeOpenRouter,
+    openAiProviderSetup,
+    closeAiProviderSetup,
+    openAiPresetMismatch,
+    closeAiPresetMismatch,
+    dismissAiSetup,
+    dismissAiPresetMismatch,
+    resetAiOnboarding,
     openRequirementReview,
     openClarityReview,
     openServiceSpec,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",