@cat-factory/app 0.312.0 → 0.314.0

package/app/components/setup/SetupChecklistPanel.vue

@@ -0,0 +1,340 @@
+<script setup lang="ts">
+import type { SetupRow, SetupRowCause, SetupRowId, SetupRowStatus } from '~/utils/setupChecklist'
+import type { SetupRemedy } from '~/utils/setupAudience'
+import SectionLabel from '~/components/common/SectionLabel.vue'
+import Spinner from '~/components/common/Spinner.vue'
+
+/**
+ * The setup checklist: every prerequisite for "a task can run and merge", its state, and one
+ * action per row (issue #2258).
+ *
+ * The probes and the surfaces each row opens are the ones the setup banners, the AI-provider
+ * dialogs and the startup health advisories already use (`useSetupChecklist`), and so is the rule
+ * for who may act: a row the caller cannot fix shows who can instead of a button. What it adds is
+ * the whole list in one place, with a finish line, instead of one interruption per missing piece.
+ * Opening a row's surface closes the checklist, so the two never stack.
+ */
+const { t } = useI18n()
+const ui = useUiStore()
+const { checklist, actionFor, refresh, patSource, patMissing } = useSetupChecklist()
+
+const open = computed({
+  get: () => ui.setupChecklistOpen,
+  set: (v: boolean) => (v ? ui.openSetupChecklist() : ui.closeSetupChecklist()),
+})
+watch(
+  () => ui.setupChecklistOpen,
+  (isOpen) => {
+    if (isOpen) refresh()
+  },
+  { immediate: true },
+)
+
+/** Open a surface from the checklist: close the checklist first, so the two never stack. */
+function go(fn: () => void) {
+  ui.closeSetupChecklist()
+  fn()
+}
+function act(row: SetupRow) {
+  const action = actionFor(row)
+  if (!action) return
+  // Asking a probe again keeps the checklist open: its answer lands here.
+  if (row.cause === 'probeFailed') action()
+  else go(action)
+}
+
+/** The rows this caller can act on, with the action to show. */
+function canAct(row: SetupRow): boolean {
+  return row.remedy === null && actionFor(row) !== null
+}
+
+/**
+ * The ONE solid button in the view: the first required row that is not done and that this caller
+ * can act on. Every other open row takes a lighter variant, so the list reads in order.
+ */
+const primaryRowId = computed<SetupRowId | null>(
+  () =>
+    checklist.value.rows.find(
+      (r) => r.required && (r.status === 'missing' || r.status === 'attention') && canAct(r),
+    )?.id ?? null,
+)
+
+const pipelineHealth = usePipelineHealth()
+const riskPolicyHealth = useRiskPolicyHealth()
+const modelPresetHealth = useModelPresetHealth()
+
+const STATUS_META: Record<SetupRowStatus, { icon: string; class: string }> = {
+  done: { icon: 'i-lucide-circle-check', class: 'text-success' },
+  missing: { icon: 'i-lucide-circle', class: 'text-dimmed' },
+  attention: { icon: 'i-lucide-circle-alert', class: 'text-warning' },
+  checking: { icon: 'i-lucide-loader-circle', class: 'text-dimmed' },
+  not_needed: { icon: 'i-lucide-circle-minus', class: 'text-dimmed' },
+}
+
+/**
+ * The action's word per state. Null for the two states that never carry an action
+ * (`useSetupChecklist.actionFor`), so no copy ships for a button that cannot render.
+ */
+const ACTION_KEYS: Record<SetupRowStatus, string | null> = {
+  done: 'setup.action.change',
+  missing: 'setup.action.connect',
+  attention: 'setup.action.fix',
+  checking: null,
+  not_needed: null,
+}
+
+function actionLabel(row: SetupRow): string {
+  if (row.cause === 'probeFailed') return t('setup.action.retry')
+  const key = ACTION_KEYS[row.status]
+  return key ? t(key) : ''
+}
+
+/** Whose token a token row is about: the remedy differs, so the row says it, as the banner does. */
+const patSourceKey = computed(() =>
+  patSource.value === 'deployment'
+    ? 'layout.githubPatPermissionsBanner.sourceDeployment'
+    : 'layout.githubPatPermissionsBanner.sourceInitiator',
+)
+
+/**
+ * Each row's title and its line for the states that are about the row. An `attention` row's line
+ * is its CAUSE (`CAUSE_KEYS`): the title already names the area, and each cause needs its own fix.
+ */
+const ROW_COPY: Record<
+  SetupRowId,
+  { title: string } & Record<Exclude<SetupRowStatus, 'attention'>, string>
+> = {
+  model: {
+    title: 'setup.rows.model.title',
+    done: 'setup.rows.model.done',
+    missing: 'setup.rows.model.missing',
+    checking: 'setup.rows.checking',
+    not_needed: 'setup.rows.notNeeded',
+  },
+  sourceControl: {
+    title: 'setup.rows.sourceControl.title',
+    done: 'setup.rows.sourceControl.done',
+    missing: 'setup.rows.sourceControl.missing',
+    checking: 'setup.rows.checking',
+    not_needed: 'setup.rows.notNeeded',
+  },
+  agentExecutor: {
+    title: 'setup.rows.agentExecutor.title',
+    done: 'setup.rows.agentExecutor.done',
+    missing: 'setup.rows.agentExecutor.missing',
+    checking: 'setup.rows.checking',
+    not_needed: 'setup.rows.agentExecutor.notNeeded',
+  },
+  ephemeralEnvironments: {
+    title: 'setup.rows.ephemeralEnvironments.title',
+    done: 'setup.rows.ephemeralEnvironments.done',
+    missing: 'setup.rows.ephemeralEnvironments.missing',
+    checking: 'setup.rows.checking',
+    not_needed: 'setup.rows.notNeeded',
+  },
+  binaryStorage: {
+    title: 'setup.rows.binaryStorage.title',
+    done: 'setup.rows.binaryStorage.done',
+    missing: 'setup.rows.binaryStorage.missing',
+    checking: 'setup.rows.checking',
+    not_needed: 'setup.rows.notNeeded',
+  },
+}
+const CAUSE_KEYS: Record<SetupRowCause, string> = {
+  unreachable: 'setup.causes.unreachable',
+  incomplete: 'setup.causes.incomplete',
+  rejected: 'setup.causes.rejected',
+  underscoped: 'setup.causes.underscoped',
+  presetBroken: 'setup.causes.presetBroken',
+  probeFailed: 'setup.causes.probeFailed',
+  notReported: 'setup.causes.notReported',
+}
+function rowLine(row: SetupRow): string {
+  return row.status === 'attention' ? t(CAUSE_KEYS[row.cause]) : t(ROW_COPY[row.id][row.status])
+}
+
+// The same "who can fix this" lines the infrastructure notice shows a caller who cannot act.
+const REMEDY_KEYS: Record<SetupRemedy, string> = {
+  workspace_admin: 'layout.infraSetupNotice.owner.workspace_admin',
+  account_admin: 'layout.infraSetupNotice.owner.account_admin',
+  operator: 'layout.infraSetupNotice.owner.operator',
+  full_surface: 'layout.infraSetupNotice.fullSurface',
+}
+
+/**
+ * The secondary list: advisories that used to open as startup dialogs, each count on its own so
+ * no sentence has to agree with a number. Only rows with work.
+ */
+const also = computed(() =>
+  [
+    {
+      id: 'pipelines',
+      labelKey: 'setup.also.pipelines',
+      counts: [
+        {
+          key: 'setup.also.counts.repair',
+          n:
+            pipelineHealth.health.value.filter((h) => h.invalid).length +
+            pipelineHealth.retired.value.length,
+        },
+        {
+          key: 'setup.also.counts.outdated',
+          n: pipelineHealth.health.value.filter((h) => !h.invalid && h.outdated).length,
+        },
+        { key: 'setup.also.counts.new', n: pipelineHealth.newPipelines.value.length },
+      ],
+      open: () => go(() => ui.openPipelineHealth()),
+    },
+    {
+      id: 'riskPolicies',
+      labelKey: 'setup.also.riskPolicies',
+      counts: [
+        { key: 'setup.also.counts.outdated', n: riskPolicyHealth.outdated.value.length },
+        { key: 'setup.also.counts.new', n: riskPolicyHealth.newPresets.value.length },
+      ],
+      open: () => go(() => ui.openRiskPolicyHealth()),
+    },
+    {
+      id: 'modelPresets',
+      labelKey: 'setup.also.modelPresets',
+      counts: [
+        { key: 'setup.also.counts.outdated', n: modelPresetHealth.outdated.value.length },
+        { key: 'setup.also.counts.new', n: modelPresetHealth.newPresets.value.length },
+      ],
+      open: () => go(() => ui.openModelPresetHealth()),
+    },
+  ]
+    .map((row) => ({ ...row, counts: row.counts.filter((c) => c.n > 0) }))
+    .filter((row) => row.counts.length > 0),
+)
+</script>
+
+<template>
+  <UModal v-model:open="open" :title="t('setup.title')" :ui="{ content: 'sm:max-w-3xl' }">
+    <template #title>
+      <span class="flex items-baseline gap-3">
+        {{ t('setup.title') }}
+        <!-- While a probe has not answered, the count is not one yet, so the badge says so. -->
+        <UBadge color="neutral" variant="subtle" data-testid="setup-progress">
+          {{
+            checklist.checking
+              ? t('setup.rows.checking')
+              : t('setup.progress', { done: checklist.done, total: checklist.total })
+          }}
+        </UBadge>
+      </span>
+    </template>
+    <template #body>
+      <div data-testid="setup-checklist">
+        <p class="text-sm text-muted">{{ t('setup.intro') }}</p>
+
+        <ul class="mt-6 space-y-3">
+          <li
+            v-for="row in checklist.rows"
+            :key="row.id"
+            class="flex items-center gap-3 rounded-lg border border-muted bg-default p-4"
+            data-testid="setup-row"
+            :data-row="row.id"
+            :data-status="row.status"
+            :data-cause="row.cause ?? undefined"
+            :data-remedy="row.remedy ?? undefined"
+          >
+            <Spinner
+              :name="STATUS_META[row.status].icon"
+              :spinning="row.status === 'checking'"
+              class="h-5 w-5 shrink-0"
+              :class="STATUS_META[row.status].class"
+            />
+            <div class="min-w-0 flex-1">
+              <div class="flex flex-wrap items-center gap-2">
+                <span class="font-medium text-highlighted">{{ t(ROW_COPY[row.id].title) }}</span>
+                <UBadge v-if="row.status !== 'done'" size="sm" color="neutral" variant="outline">
+                  {{ row.required ? t('setup.required') : t('setup.optional') }}
+                </UBadge>
+              </div>
+              <p class="mt-0.5 text-xs text-muted">{{ rowLine(row) }}</p>
+              <!-- The token rows carry the banners' second half: whose token it is, and, for a
+                   missing local token, where the new one goes. -->
+              <p
+                v-if="row.cause === 'rejected' || row.cause === 'underscoped'"
+                class="mt-0.5 text-xs text-dimmed"
+              >
+                {{ t(patSourceKey) }}
+              </p>
+              <p
+                v-else-if="row.id === 'sourceControl' && row.status === 'missing' && patMissing"
+                class="mt-0.5 text-xs text-dimmed"
+              >
+                <i18n-t keypath="layout.githubPatBanner.thenSet" tag="span" scope="global">
+                  <template #envVar>
+                    <code class="font-mono">GITHUB_PAT</code>
+                  </template>
+                </i18n-t>
+              </p>
+              <!-- A gap this caller cannot close: who can, in place of a button their save would
+                   be refused on. A done row needs neither. -->
+              <p
+                v-if="row.remedy && row.status !== 'done' && row.status !== 'not_needed'"
+                class="mt-0.5 text-xs text-dimmed"
+                data-testid="setup-row-remedy"
+              >
+                {{ t(REMEDY_KEYS[row.remedy]) }}
+              </p>
+            </div>
+            <UButton
+              v-if="canAct(row)"
+              size="sm"
+              :color="row.status === 'done' ? 'neutral' : 'primary'"
+              :variant="
+                row.id === primaryRowId ? 'solid' : row.status === 'done' ? 'outline' : 'soft'
+              "
+              data-testid="setup-row-action"
+              @click="act(row)"
+            >
+              {{ actionLabel(row) }}
+            </UButton>
+          </li>
+        </ul>
+
+        <USeparator class="my-6" />
+        <SectionLabel as="h2" class="mb-3">{{ t('setup.also.title') }}</SectionLabel>
+        <ul class="space-y-2 text-sm">
+          <li v-for="row in also" :key="row.id" class="flex flex-wrap items-center gap-2">
+            <span class="text-muted">{{ t(row.labelKey) }}</span>
+            <UBadge v-for="c in row.counts" :key="c.key" size="sm" color="neutral" variant="subtle">
+              {{ t(c.key, { count: c.n }) }}
+            </UBadge>
+            <UButton
+              class="ms-auto"
+              size="xs"
+              color="neutral"
+              variant="outline"
+              @click="row.open()"
+            >
+              {{ t('setup.action.review') }}
+            </UButton>
+          </li>
+          <li class="flex flex-wrap items-center gap-2 text-muted">
+            <span class="flex-1">{{ t('setup.also.settings') }}</span>
+            <UButton
+              size="xs"
+              color="neutral"
+              variant="ghost"
+              @click="go(() => ui.openWorkspaceSettings())"
+            >
+              {{ t('setup.also.workspaceSettings') }}
+            </UButton>
+            <UButton
+              size="xs"
+              color="neutral"
+              variant="ghost"
+              @click="go(() => ui.openIntegrations())"
+            >
+              {{ t('setup.also.integrations') }}
+            </UButton>
+          </li>
+        </ul>
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/composables/useNavContributions.ts

@@ -55,6 +55,7 @@ export function useNavContributions() {
     foundationalServices: () => ui.openFoundationalServices(),
     mergeThresholds: () => ui.openWorkspaceSettings('merge'),
     workspaceSettings: () => ui.openWorkspaceSettings(),
+    setupChecklist: () => ui.openSetupChecklist(),
     modelConfiguration: () => ui.openModelConfig(),
     serviceFragmentDefaults: () => ui.openWorkspaceSettings('fragments'),
     localModels: () => ui.openLocalModels(),
@@ -72,6 +73,7 @@ export function useNavContributions() {
     // The QUESTION, not a toggle: with three roles there is no unambiguous "next one", and the
     // prompt is the one surface that states what each role gives you before you pick it.
     chooseRole: () => useUiRoleStore().openPrompt(),
+    describeWork: () => ui.openDescribeWork(),
     queueView: () => useWorkViewStore().show('queue'),
     boardView: () => useWorkViewStore().show('board'),
   }

package/app/composables/useSetupChecklist.ts

@@ -0,0 +1,122 @@
+import { computed, ref } from 'vue'
+import { githubPatCheckNeedsAttention } from '@cat-factory/contracts'
+import { deriveSetupChecklist, type SetupRow } from '~/utils/setupChecklist'
+
+/**
+ * The store-facing half of `utils/setupChecklist.ts`: resolve every probe the checklist reads,
+ * and the existing surface each row's action opens.
+ *
+ * Every action goes to the surface the matching banner or dialog opens for the same state, so
+ * the checklist is a new index over the setup the product has, never a second copy of it.
+ */
+export function useSetupChecklist() {
+  const ui = useUiStore()
+  const github = useGitHubStore()
+  const models = useModelsStore()
+  const workspace = useWorkspaceStore()
+  const providerConnections = useProviderConnectionsStore()
+  const ai = useAiReadiness()
+  const { actor } = useSetupActor()
+  // Where each gap is fixed: the map the setup banners open through too.
+  const remedies = useSetupRemedies()
+  /** Local mode with no token: the row says where the new one goes, as the banner does. */
+  const patMissing = computed(() => !!remedies.patSetupUrl.value)
+
+  // The catalog is loaded on board open, and a failed load is dropped there on purpose (it stays
+  // retryable, see `models.prefetchForBoard`). The checklist is where that failure is stated, so
+  // it asks for the catalog itself and keeps the outcome.
+  const modelLoadFailed = ref(false)
+  async function loadModels() {
+    const id = workspace.workspaceId
+    if (!id) return
+    modelLoadFailed.value = false
+    try {
+      await models.ensureLoaded(id)
+    } catch {
+      modelLoadFailed.value = true
+    }
+  }
+
+  /**
+   * Ask every probe the checklist reads, so a row does not wait on a banner that happens to be
+   * mounted. Each is single-flighted or load-once in its store, so this costs nothing when the
+   * board already asked.
+   */
+  function refresh() {
+    void loadModels()
+    void providerConnections.ensureLoaded()
+    void github.ensureProbed()
+  }
+
+  const patCheck = computed(() => github.patCheck)
+  const patProblem = computed<'rejected' | 'underscoped' | null>(() => {
+    const check = patCheck.value
+    if (!check || !githubPatCheckNeedsAttention(check)) return null
+    return check.state === 'token_rejected' ? 'rejected' : 'underscoped'
+  })
+
+  const checklist = computed(() =>
+    deriveSetupChecklist({
+      model: {
+        loaded: ai.ready.value,
+        loadFailed: modelLoadFailed.value,
+        usable: ai.hasUsableModel.value,
+        presetBroken: ai.defaultPresetBroken.value,
+      },
+      sourceControl: {
+        available: github.available,
+        unavailableCause: github.unavailableCause,
+        connected: github.connected,
+        patMissing: patMissing.value,
+        patProblem: patProblem.value,
+      },
+      infra: workspace.infraSetup ?? null,
+      workspaceLoaded: workspace.ready,
+      infraOwners: workspace.infraSetupOwners ?? null,
+      providers: {
+        loaded: providerConnections.loaded,
+        needingConfig: providerConnections.needingConfig,
+      },
+      actor: actor.value,
+    }),
+  )
+
+  /**
+   * Where a row's action goes, by row AND state, through the remedies the matching banner uses.
+   * Null where there is nothing to open: the deployment does not use the area, or does not report
+   * it.
+   */
+  function actionFor(row: SetupRow): (() => void) | null {
+    if (row.status === 'not_needed' || row.status === 'checking') return null
+    if (row.cause === 'notReported') return null
+    switch (row.id) {
+      case 'model':
+        if (row.cause === 'probeFailed') return () => void loadModels()
+        if (row.status === 'missing') return remedies.openModelSetup
+        if (row.cause === 'presetBroken') return remedies.openPresetMismatch
+        return () => ui.openModelProviders()
+      case 'sourceControl': {
+        const setupUrl = remedies.patSetupUrl.value
+        if (setupUrl) return () => window.open(setupUrl, '_blank', 'noopener')
+        if (row.cause === 'rejected' || row.cause === 'underscoped') {
+          const remint = remedies.patRemintUrl.value
+          return () => window.open(remint, '_blank', 'noopener')
+        }
+        if (row.cause === 'probeFailed') return () => void github.probe()
+        return () => ui.openGitHub()
+      }
+      case 'agentExecutor':
+      case 'ephemeralEnvironments':
+      case 'binaryStorage': {
+        const area = row.id
+        return () => remedies.openInfraArea(area)
+      }
+      default: {
+        const unreachable: never = row.id
+        return unreachable
+      }
+    }
+  }
+
+  return { checklist, actionFor, refresh, patSource: remedies.patSource, patMissing }
+}

package/app/composables/useSetupRemedies.ts

@@ -0,0 +1,72 @@
+import { computed } from 'vue'
+import { githubPatCheckSource } from '@cat-factory/contracts'
+import type { GitHubPatKind, InfraSetupArea } from '~/types/domain'
+import { githubPatRemintUrl } from '~/utils/vcs'
+
+/**
+ * Where each setup gap is fixed: the ONE map the setup banners and the setup checklist both open
+ * through, so "the row opens what its banner opens" holds because there is one place that says
+ * it, never two copies kept in step by hand.
+ *
+ * Keyed by `InfraSetupArea` for the infrastructure, the vocabulary the server reports in, plus the
+ * model and source-control remedies, which have no area of their own.
+ */
+export function useSetupRemedies() {
+  const ui = useUiStore()
+  const auth = useAuthStore()
+  const github = useGitHubStore()
+
+  const INFRA: Record<InfraSetupArea, () => void> = {
+    agentExecutor: () => ui.openProviderConnection('runner-pool'),
+    ephemeralEnvironments: () => ui.openProviderConnection('environment'),
+    binaryStorage: () => ui.openContentStorageSettings(),
+  }
+
+  /** Open the screen that configures an infrastructure area. */
+  function openInfraArea(area: InfraSetupArea) {
+    INFRA[area]()
+  }
+
+  /** No usable model: the AI onboarding dialog. */
+  function openModelSetup() {
+    ui.openAiProviderSetup()
+  }
+
+  /** Usable models, but the default preset names one that is not: the preset-mismatch dialog. */
+  function openPresetMismatch() {
+    ui.openAiPresetMismatch()
+  }
+
+  /** Local mode with no token: GitHub's token page, scopes preselected. Null outside that case. */
+  const patSetupUrl = computed(() => auth.localMode?.githubPatSetupUrl ?? null)
+
+  /**
+   * The token page for a token GitHub rejected or under-scoped. A rejected token was never
+   * classified, so it falls back to `unknown`, which lands on the classic form, the only one
+   * GitHub lets us pre-fill.
+   */
+  const patReport = computed(() =>
+    github.patCheck?.state === 'checked' ? github.patCheck.report : undefined,
+  )
+  /** The token's kind, which picks the form. `unknown` for a token GitHub rejected outright. */
+  const patKind = computed<GitHubPatKind>(() => patReport.value?.kind ?? 'unknown')
+  const patRemintUrl = computed(() =>
+    githubPatRemintUrl(patKind.value, patReport.value?.webUrl ?? github.connection?.webUrl),
+  )
+
+  /**
+   * Whose token that is: the deployment's (replaced by whoever runs it) or the person's own
+   * (replaced in their settings). Read off the check, which carries it in every state it reports.
+   */
+  const patSource = computed(() => (github.patCheck ? githubPatCheckSource(github.patCheck) : null))
+
+  return {
+    openInfraArea,
+    openModelSetup,
+    openPresetMismatch,
+    patSetupUrl,
+    patKind,
+    patRemintUrl,
+    patSource,
+  }
+}

package/app/composables/useTaskActions.ts

@@ -43,6 +43,7 @@ export function useTaskActions(taskId: () => string) {
 
   const pipelineFor = useStartPipelineResolver()
   const defaultPipeline = computed(() => pipelineFor(task.value))
+  const { startTask } = useStartWithFeedback()
 
   /**
    * Whether the outcome summary has something to show, asked of the SAME reduction the window
@@ -77,35 +78,12 @@ export function useTaskActions(taskId: () => string) {
       })
       return
     }
-    const pipeline = defaultPipeline.value
-    if (!pipeline) {
-      toast.error('board.task.noPipelineTitle', { description: t('board.task.noPipelineBody') })
-      return
-    }
+    const block = task.value
+    if (!block) return
     starting.value = true
-    // false ⇒ the run never started (the user cancelled the personal-password prompt, or the
-    // start was refused: the store surfaces the actionable toast itself). Revert the optimistic
-    // state; on success the button unmounts once the stream pushes in_progress.
-    const started = await execution.start(taskId(), pipeline)
-    if (started) {
-      // Confirm the (optimistic) start landed: the button unmounts once the stream pushes
-      // in_progress, so without this the successful action gives no feedback. A sandboxed start
-      // says so here rather than borrowing the live wording: this is the moment the reader learns
-      // what they just started, and the two runs differ in what they will end up doing.
-      // A sandboxed run is `warning`: it ran, and its outcome differs in a way the reader should
-      // know (it opens a pull request and merges nothing), so it stays until closed.
-      if (sandboxed.value) {
-        toast.warning('board.dryRunToast.title', {
-          description: t('board.dryRunToast.body', { name: pipeline.name }),
-        })
-      } else {
-        toast.success('board.task.startedToast.title', {
-          description: t('board.task.startedToast.body', { name: pipeline.name }),
-        })
-      }
-    } else {
-      starting.value = false
-    }
+    // On success the button unmounts once the stream pushes in_progress; otherwise revert the
+    // optimistic state (`startTask` has said why).
+    if (!(await startTask(block))) starting.value = false
   }
 
   async function merge() {
@@ -199,6 +177,51 @@ export function useTaskActions(taskId: () => string) {
   }
 }
 
+/**
+ * Start a task on the pipeline a plain "Start" uses, and tell the person what happened: the
+ * card's Start and the intake's "Add and start" both go through it, so the two say the same thing.
+ * Resolves false when nothing started (no pipeline to run, a cancelled credential prompt, or a
+ * refused start, which `execution.start` reports itself).
+ */
+export function useStartWithFeedback() {
+  const execution = useExecutionStore()
+  const toast = useActionToast()
+  const { t } = useI18n()
+  const { forcedFor } = useDryRunPolicy()
+  const pipelineFor = useStartPipelineResolver()
+
+  async function startTask(block: Pick<Block, 'id' | 'pipelineId'>): Promise<boolean> {
+    const pipeline = pipelineFor(block)
+    if (!pipeline) {
+      // A refusal decided in the browser, in translated copy: the `error` tone.
+      toast.error('board.task.noPipelineTitle', { description: t('board.task.noPipelineBody') })
+      return false
+    }
+    // Read before the start: the sandbox policy is a fact about this task and role now.
+    const sandboxed = forcedFor(block.id)
+    const started = await execution.start(block.id, pipeline)
+    if (started) {
+      // Confirm the start landed: without this the action gives no feedback until the stream
+      // moves the card. A sandboxed start says so rather than borrowing the live wording: this is
+      // the moment the reader learns what they just started, and the two runs end differently.
+      // A sandboxed run is `warning`: it ran, and it ends differently (it opens a pull request and
+      // merges nothing), so the toast stays until closed.
+      if (sandboxed) {
+        toast.warning('board.dryRunToast.title', {
+          description: t('board.dryRunToast.body', { name: pipeline.name }),
+        })
+      } else {
+        toast.success('board.task.startedToast.title', {
+          description: t('board.task.startedToast.body', { name: pipeline.name }),
+        })
+      }
+    }
+    return started
+  }
+
+  return { startTask }
+}
+
 /** The pipeline a plain "Start" runs, as the descriptor `execution.start` takes. */
 export interface StartPipeline {
   id: string

package/app/modular/nav-contributions.spec.ts

@@ -224,6 +224,7 @@ describe('navSlotFilter', () => {
       tutorial: 'the walkthroughs - the surface with the fewest destinations needs them most',
       'keyboard-shortcuts': 'the cheatsheet covers the board and the palette, which every role has',
       'ui-role': 'the way BACK out of the narrowed role',
+      'describe-work': 'filing a task from one sentence is the job the intake role exists for',
       'queue-view': 'which view of the board a person works in is their own choice, in every role',
       'board-view': 'the way back to the canvas from the queue view, in every role',
     }
@@ -491,6 +492,7 @@ describe('nav grouping helpers', () => {
     expect(integrations?.items.map((i) => i.id)).toEqual(['integrations-hub'])
     const configuration = groups.find((g) => g.group === 'configuration')
     expect(configuration?.items.map((i) => i.id)).toEqual([
+      'setup-checklist',
       'workspace-settings',
       'account-settings',
       'operator-dashboard',
@@ -524,6 +526,7 @@ describe('nav grouping helpers', () => {
       'ui-role',
       'tutorial',
       'foundational-services',
+      'setup-checklist',
       'queue-view',
       'board-view',
     ])