@cat-factory/app 0.15.0 → 0.16.1

package/app/components/board/AddTaskModal.vue

@@ -5,13 +5,14 @@
 // pipeline on it explicitly (and can keep editing it until they do).
 //
 // The form also shows ungated "Context documents" / "Context issues" sections
-// (mirroring the task inspector): pick already-imported docs/issues — or open the
-// import flow — to attach as agent context. When the relevant integration isn't
-// connected the Attach button is disabled with a hint. Linking needs the block id,
+// (mirroring the task inspector): an inline search picker (ContextDocumentPicker /
+// ContextIssuePicker) finds already-imported items, search hits, or a pasted ref to
+// attach as agent context. When the relevant integration isn't connected the Attach
+// button is disabled with a hint. Linking needs the block id,
 // so chosen items are staged locally and import-and-linked once the task is created
 // (see useContextLinking) — the same context the agents see for every step of the run.
-import type { DropdownMenuItem } from '@nuxt/ui'
 import type { CreateTaskType, TaskTypeFields } from '~/types/domain'
+import ContextDocumentPicker from '~/components/documents/ContextDocumentPicker.vue'
 import ContextIssuePicker from '~/components/tasks/ContextIssuePicker.vue'
 
 const ui = useUiStore()
@@ -200,41 +201,13 @@ function removePending(item: PendingContext) {
   pendingContext.value = pendingContext.value.filter((c) => contextKey(c) !== contextKey(item))
 }
 
-// Attach menus: already-imported items not yet chosen, plus the import entry — the
-// same affordances the inspector offers. Picking one stages it locally (it links
-// after the task is created).
-const docAttachMenu = computed<DropdownMenuItem[][]>(() => {
-  const chosen = new Set(pendingContext.value.map(contextKey))
-  const items: DropdownMenuItem[] = documents.documents
-    .filter(
-      (d) =>
-        !chosen.has(contextKey({ kind: 'document', source: d.source, externalId: d.externalId })),
-    )
-    .map((d) => ({
-      label: d.title,
-      icon: documents.descriptorFor(d.source)?.icon ?? 'i-lucide-file-text',
-      onSelect: () =>
-        addPending({
-          kind: 'document',
-          source: d.source,
-          externalId: d.externalId,
-          title: d.title,
-          icon: documents.descriptorFor(d.source)?.icon ?? 'i-lucide-file-text',
-          needsImport: false,
-        }),
-    }))
-  items.push({
-    label: 'Import a page…',
-    icon: 'i-lucide-file-down',
-    onSelect: () => ui.openDocumentImport(null),
-  })
-  return [items]
-})
-
-// Context issues are picked through an inline search picker (ContextIssuePicker)
-// rather than a dropdown that opens a second modal — stacked page-level modals
-// don't interact here, which is why the old "Import an issue…" path appeared to
-// do nothing. The "Attach" button toggles the picker open.
+// Context documents and issues are both picked through an inline search picker
+// (ContextDocumentPicker / ContextIssuePicker) rather than a dropdown that opens a
+// second modal — stacked page-level modals don't interact here, which is why the
+// old "Import a page…" / "Import an issue…" entries appeared to open something but
+// nothing was clickable. The "Attach" button toggles the relevant picker open.
+const showDocPicker = ref(false)
+const chosenDocKeys = computed(() => pendingDocs.value.map(contextKey))
 const showIssuePicker = ref(false)
 const chosenIssueKeys = computed(() => pendingIssues.value.map(contextKey))
 
@@ -255,6 +228,7 @@ watch(open, (isOpen) => {
   pipelineId.value = ''
   agentConfigValues.value = {}
   pendingContext.value = []
+  showDocPicker.value = false
   showIssuePicker.value = false
   documents.loadDocuments().catch(() => {})
   tasks.loadTasks().catch(() => {})
@@ -508,15 +482,16 @@ async function add() {
               <span class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
                 Context documents
               </span>
-              <UDropdownMenu
+              <UButton
                 v-if="docsConnected"
-                :items="docAttachMenu"
-                :content="{ side: 'bottom', align: 'end' }"
+                color="neutral"
+                variant="soft"
+                size="xs"
+                :icon="showDocPicker ? 'i-lucide-x' : 'i-lucide-plus'"
+                @click="showDocPicker = !showDocPicker"
               >
-                <UButton color="neutral" variant="soft" size="xs" icon="i-lucide-plus">
-                  Attach
-                </UButton>
-              </UDropdownMenu>
+                {{ showDocPicker ? 'Done' : 'Attach' }}
+              </UButton>
               <UButton
                 v-else
                 color="neutral"
@@ -533,6 +508,11 @@ async function add() {
                 Attach
               </UButton>
             </div>
+            <ContextDocumentPicker
+              v-if="showDocPicker && docsConnected"
+              :chosen-keys="chosenDocKeys"
+              @pick="addPending"
+            />
             <div v-if="pendingDocs.length" class="space-y-1">
               <div
                 v-for="item in pendingDocs"

package/app/components/documents/ContextDocumentPicker.vue

@@ -0,0 +1,245 @@
+<script setup lang="ts">
+// Inline picker for attaching a document (Confluence / Notion / GitHub page) as
+// task context. It searches the connected source by free text, lists
+// already-imported documents for quick re-use, and accepts a pasted URL/ID as a
+// reference — all inline, with NO second modal (stacked page-level modals don't
+// interact here, which is why the old "Import a page…" path appeared to open
+// something but nothing was clickable). It only *stages* a choice: the caller
+// collects PendingContext items and links them once the block exists (see
+// useContextLinking). A search hit / pasted ref carries `needsImport: true` so
+// it's fetched + persisted before linking. Mirrors ContextIssuePicker.
+import type { DocumentSearchResult, DocumentSourceKind } from '~/types/domain'
+
+const props = defineProps<{
+  /** contextKeys already staged by the caller, so they're filtered out / not re-offered. */
+  chosenKeys?: string[]
+}>()
+const emit = defineEmits<{ pick: [item: PendingContext] }>()
+
+const documents = useDocumentsStore()
+
+const chosen = computed(() => new Set(props.chosenKeys ?? []))
+
+// Source: default to the first connected source; a selector appears only when
+// more than one is connected (the common case is a single source).
+const source = ref<DocumentSourceKind | undefined>(documents.connectedSources[0]?.source)
+const sourceItems = computed(() =>
+  documents.connectedSources.map((s) => ({ label: s.label, value: s.source })),
+)
+const descriptor = computed(() =>
+  source.value ? documents.descriptorFor(source.value) : undefined,
+)
+const searchable = computed(() => descriptor.value?.searchable ?? false)
+
+const query = ref('')
+const results = ref<DocumentSearchResult[]>([])
+const searching = ref(false)
+const searchError = ref<string | null>(null)
+
+// Debounced search: free text hits the source; a query that's clearly a URL/ID
+// is left to the explicit "by reference" row below (search won't surface it).
+let timer: ReturnType<typeof setTimeout> | undefined
+watch([query, source], () => {
+  if (timer) clearTimeout(timer)
+  results.value = []
+  searchError.value = null
+  const q = query.value.trim()
+  if (!q || !searchable.value) return
+  timer = setTimeout(runSearch, 300)
+})
+
+async function runSearch() {
+  const q = query.value.trim()
+  if (!q || !source.value) return
+  searching.value = true
+  searchError.value = null
+  try {
+    results.value = await documents.search(source.value, q)
+  } catch (e) {
+    results.value = []
+    searchError.value = e instanceof Error ? e.message : String(e)
+  } finally {
+    searching.value = false
+  }
+}
+
+const icon = computed(() => descriptor.value?.icon ?? 'i-lucide-file-text')
+
+function keyFor(externalId: string): string {
+  return source.value
+    ? contextKey({ kind: 'document', source: source.value, externalId })
+    : `document::${externalId}`
+}
+
+// Already-imported documents for this source, filtered by the query and never
+// re-offering one the caller already staged.
+const importedRows = computed(() => {
+  if (!source.value) return []
+  const q = query.value.trim().toLowerCase()
+  return documents.documents
+    .filter((d) => d.source === source.value)
+    .filter((d) => !chosen.value.has(keyFor(d.externalId)))
+    .filter((d) => !q || d.title.toLowerCase().includes(q) || d.excerpt.toLowerCase().includes(q))
+})
+
+// Search hits not already imported (those show in importedRows) and not staged.
+const searchRows = computed(() => {
+  if (!source.value) return []
+  const importedIds = new Set(
+    documents.documents.filter((d) => d.source === source.value).map((d) => d.externalId),
+  )
+  return results.value
+    .filter((r) => !importedIds.has(r.externalId))
+    .filter((r) => !chosen.value.has(keyFor(r.externalId)))
+})
+
+// A pasted URL / ID the search won't match: offer it as an explicit reference.
+// When the source isn't searchable, any non-empty query is treated as a ref (the
+// only way to attach a page there, mirroring the import modal's single input).
+const refRow = computed(() => {
+  const q = query.value.trim()
+  if (!q || !source.value) return null
+  const known =
+    importedRows.value.some((d) => d.externalId === q) ||
+    searchRows.value.some((r) => r.externalId === q) ||
+    chosen.value.has(keyFor(q))
+  if (known) return null
+  if (!searchable.value) return q
+  // Only worth offering when it looks like a reference, not a search phrase.
+  const looksLikeRef = q.includes('#') || q.includes('/') || /^https?:\/\//i.test(q)
+  return looksLikeRef ? q : null
+})
+
+const empty = computed(
+  () =>
+    !searching.value &&
+    !searchError.value &&
+    importedRows.value.length === 0 &&
+    searchRows.value.length === 0 &&
+    refRow.value === null,
+)
+
+function pickImported(externalId: string, title: string, excerpt: string) {
+  if (!source.value) return
+  emit('pick', {
+    kind: 'document',
+    source: source.value,
+    externalId,
+    title,
+    subtitle: excerpt || undefined,
+    icon: icon.value,
+    needsImport: false,
+  })
+}
+
+function pickSearch(r: DocumentSearchResult) {
+  emit('pick', {
+    kind: 'document',
+    source: r.source,
+    externalId: r.externalId,
+    title: r.title,
+    subtitle: r.excerpt || undefined,
+    icon: icon.value,
+    needsImport: true,
+  })
+}
+
+function pickRef(q: string) {
+  if (!source.value) return
+  emit('pick', {
+    kind: 'document',
+    source: source.value,
+    externalId: q,
+    title: q,
+    subtitle: descriptor.value?.label,
+    icon: icon.value,
+    needsImport: true,
+  })
+  query.value = ''
+}
+
+onMounted(() => {
+  // Keep the quick-pick list current (cheap; the store dedupes).
+  documents.loadDocuments().catch(() => {})
+})
+</script>
+
+<template>
+  <div class="space-y-2 rounded-lg border border-slate-800 bg-slate-900/40 p-2">
+    <USelect
+      v-if="sourceItems.length > 1"
+      v-model="source"
+      :items="sourceItems"
+      size="xs"
+      class="w-full"
+    />
+
+    <UInput
+      v-model="query"
+      :icon="searching ? 'i-lucide-loader-circle' : 'i-lucide-search'"
+      :ui="{ leadingIcon: searching ? 'animate-spin' : '' }"
+      size="sm"
+      class="w-full"
+      :placeholder="
+        searchable
+          ? 'Search pages or paste a URL/ID…'
+          : (descriptor?.refPlaceholder ?? 'Paste a page URL or ID…')
+      "
+      @keydown.enter="refRow && pickRef(refRow)"
+    />
+
+    <p v-if="searchError" class="px-1 text-[11px] text-amber-400">
+      Search failed: {{ searchError }}
+    </p>
+
+    <div class="max-h-56 space-y-0.5 overflow-y-auto">
+      <!-- Already-imported documents (linked directly, no re-fetch). -->
+      <button
+        v-for="d in importedRows"
+        :key="`imp:${d.externalId}`"
+        type="button"
+        class="flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-xs text-slate-300 hover:bg-slate-800/70"
+        @click="pickImported(d.externalId, d.title, d.excerpt)"
+      >
+        <UIcon :name="icon" class="h-3.5 w-3.5 shrink-0 text-indigo-400" />
+        <span class="truncate">{{ d.title }}</span>
+        <UBadge color="neutral" variant="soft" size="xs" class="ml-auto shrink-0">imported</UBadge>
+      </button>
+
+      <!-- Source search hits (imported on add). -->
+      <button
+        v-for="r in searchRows"
+        :key="`hit:${r.externalId}`"
+        type="button"
+        class="flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-xs text-slate-300 hover:bg-slate-800/70"
+        @click="pickSearch(r)"
+      >
+        <UIcon :name="icon" class="h-3.5 w-3.5 shrink-0 text-slate-400" />
+        <span class="truncate">{{ r.title }}</span>
+      </button>
+
+      <!-- Explicit URL/ID reference (imported on add). -->
+      <button
+        v-if="refRow"
+        type="button"
+        class="flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-xs text-slate-300 hover:bg-slate-800/70"
+        @click="pickRef(refRow)"
+      >
+        <UIcon name="i-lucide-link" class="h-3.5 w-3.5 shrink-0 text-slate-400" />
+        <span class="truncate"
+          >Attach <span class="text-slate-200">{{ refRow }}</span> by reference</span
+        >
+      </button>
+
+      <p v-if="empty" class="px-2 py-1.5 text-[11px] text-slate-500">
+        {{
+          query.trim()
+            ? 'No matching pages.'
+            : searchable
+              ? 'Search by title, or pick an imported document.'
+              : 'Paste a page URL or ID to attach it.'
+        }}
+      </p>
+    </div>
+  </div>
+</template>

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.15.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",