@cat-factory/app 0.247.0 → 0.249.0

package/app/components/documents/StartFromDesignModal.vue

@@ -0,0 +1,237 @@
+<script setup lang="ts">
+// Start a task from a design link: paste a Figma/Zeplin URL on a service frame, and the resolved
+// reference is staged onto the add-task form as context. One affordance, three steps that used to
+// be four separate surfaces (Integrations hub → import modal → board → add task → attach).
+//
+// Three rules this surface exists to hold, each of which the obvious version gets wrong.
+//
+//  - It resolves the reference BEFORE anything is created, through the same
+//    `POST /document-sources/:source/resolve-ref` the attach picker uses, so a share link's title
+//    segment and tracking params are trimmed where the person who pasted them can still see it,
+//    and a link the source cannot read is a correction rather than a toast over a task that
+//    already exists without its design.
+//  - It only asks the CONNECTED DESIGN sources, and it asks them in claim-confidence order
+//    (host-pinned first), because a host-blind prose parser will happily claim a Figma URL whose
+//    file key carries a UUID-shaped run. `connectedDesignSources` is already in registry order
+//    and every design source is host-pinned, so the order is the store's.
+//  - A WIDENED reference is stated separately from a trimmed one. Figma's own Copy link emits a
+//    complex instance id for any component instance, which the parser cannot read, so it falls
+//    back to the whole file: "I attached this frame" and "I attached the entire design" otherwise
+//    render identically. For a designer that widening IS the defect, not a detail.
+import { refRowFor, classifyRefFailure, type RefState } from './ContextDocumentPicker.logic'
+import type { DocumentSourceKind, ResolvedDocumentRef } from '~/types/domain'
+
+const { t } = useI18n()
+const ui = useUiStore()
+const documents = useDocumentsStore()
+
+const open = computed({
+  get: () => ui.startFromDesign !== null,
+  set: (v: boolean) => {
+    if (!v) ui.closeStartFromDesign()
+  },
+})
+
+const pasted = ref('')
+const state = ref<RefState>({ status: 'none' })
+/** The source that claimed the paste, held beside the verdict so the staged item names it. */
+const claimant = ref<DocumentSourceKind | null>(null)
+/**
+ * The exact text {@link state} is the verdict FOR, so the same text is never re-resolved.
+ *
+ * This is what keeps Continue clickable. The input resolves on blur, and clicking Continue blurs
+ * it, so a person who resolved with Enter and then reached for the button re-entered `resolve()`
+ * on mousedown: the state fell back to `checking`, `row` went null, and Vue disabled the button
+ * before mouseup, so the click was never dispatched. The button came back enabled a moment later
+ * having done nothing, which reads as a dead button rather than as a race. (The `start-from-design`
+ * tour hit the same edge, its `advanceOn: 'target-click'` step waiting on a click that never fired.)
+ *
+ * Guarding on the TEXT rather than suppressing the blur is what makes it a fix instead of a
+ * workaround: re-resolving input that already has a verdict spends one HTTP call per connected
+ * design source to arrive back where it started, whoever caused it.
+ */
+const resolvedFor = ref<string | null>(null)
+
+watch(open, (isOpen) => {
+  if (!isOpen) return
+  pasted.value = ''
+  state.value = { status: 'none' }
+  claimant.value = null
+  resolvedFor.value = null
+})
+
+const row = computed(() => refRowFor(state.value, pasted.value))
+const sources = computed(() => documents.connectedDesignSources)
+
+/**
+ * The source the staged reference will be attached to.
+ *
+ * An UNCHECKED paste (the pre-flight itself failed: offline, a 502, a proxy's error page) is not
+ * a refusal, so it stays stageable with the import as the backstop it always was — but only when
+ * ONE design source is connected, because that is the only case where nothing has to be guessed.
+ * With two, the source is exactly what the resolve was going to tell us, and picking the
+ * first-registered one would attach a Zeplin screen to Figma's key space. Then the honest answer
+ * is to say the check could not be made and let the person retry.
+ */
+const target = computed<DocumentSourceKind | null>(() => {
+  if (claimant.value) return claimant.value
+  if (state.value.status !== 'unchecked') return null
+  return sources.value.length === 1 ? (sources.value[0] ?? null) : null
+})
+
+/**
+ * Ask each connected design source in turn and keep the FIRST that claims the paste.
+ *
+ * Sequential rather than parallel: the sources are ordered by how much a claim over a URL is
+ * worth, and running them together would make the winner whichever answered first. A refusal from
+ * one source is not a refusal of the paste, so only the LAST one is surfaced when nobody claims
+ * it — that is the state where the person genuinely has to change something.
+ */
+async function resolve() {
+  const text = pasted.value.trim()
+  // Already judged, so there is nothing to learn and a verdict to lose (see `resolvedFor`).
+  if (text === resolvedFor.value) return
+  claimant.value = null
+  if (!text) {
+    state.value = { status: 'none' }
+    resolvedFor.value = null
+    return
+  }
+  state.value = { status: 'checking' }
+  let last: RefState = { status: 'rejected', reason: 'document_ref_unrecognized' }
+  for (const source of sources.value) {
+    try {
+      const ref: ResolvedDocumentRef = await documents.resolveRef(source, text)
+      claimant.value = source
+      state.value = { status: 'ok', ref }
+      resolvedFor.value = text
+      return
+    } catch (e) {
+      last = classifyRefFailure(e)
+      // An outage leaves the paste UNJUDGED rather than refused, and asking the next source
+      // would turn one source being down into a different source's verdict.
+      if (last.status === 'unchecked') break
+    }
+  }
+  state.value = last
+  // A refusal and an outage are verdicts too: re-running on the same text would reach the same
+  // one, and an `unchecked` paste is stageable, so it must survive the blur Continue causes.
+  resolvedFor.value = text
+}
+
+/**
+ * Hand the resolved reference to the add-task form as a staged attachment.
+ *
+ * `needsImport` is true because nothing has been fetched yet: the form's own pre-create resolve
+ * (`useContextLinking().resolvePending`) performs the import, which is where an unreachable page
+ * becomes a correction the author can still make. Importing here as well would spend the fetch
+ * twice and move the failure back before the form exists.
+ */
+function stage() {
+  const frame = ui.startFromDesign
+  const resolved = row.value
+  const source = target.value
+  if (!frame || !resolved || !source) return
+  const descriptor = documents.descriptorFor(source)
+  ui.closeStartFromDesign()
+  ui.openAddTask(frame.frameId, {
+    context: [
+      {
+        kind: 'document',
+        source,
+        externalId: resolved.externalId,
+        title: resolved.label,
+        subtitle: descriptor?.label,
+        icon: descriptor?.icon,
+        needsImport: true,
+      },
+    ],
+  })
+}
+</script>
+
+<template>
+  <UModal v-model:open="open" :title="t('documents.startFromDesign.title')">
+    <template #body>
+      <div class="space-y-4">
+        <p class="text-sm text-slate-400">{{ t('documents.startFromDesign.intro') }}</p>
+
+        <!-- No connected design source: the flow cannot run, and saying which step is missing
+             beats an input that refuses every paste. The connect route is withheld from a member
+             for the same reason the picker's add tier is: connecting stores a credential. -->
+        <p v-if="sources.length === 0" class="text-sm text-amber-300">
+          {{ t('documents.startFromDesign.noSource') }}
+        </p>
+
+        <template v-else>
+          <UFormField :label="t('documents.startFromDesign.linkLabel')">
+            <UInput
+              v-model="pasted"
+              :placeholder="t('documents.startFromDesign.linkPlaceholder')"
+              class="w-full"
+              data-testid="start-from-design-link"
+              @blur="resolve"
+              @keyup.enter="resolve"
+            />
+          </UFormField>
+
+          <div
+            v-if="state.status === 'checking'"
+            class="flex items-center gap-2 text-sm text-slate-400"
+          >
+            <UIcon name="i-lucide-loader" class="h-4 w-4 animate-spin" />
+            {{ t('documents.startFromDesign.checking') }}
+          </div>
+
+          <div
+            v-else-if="row"
+            class="space-y-1 rounded-lg border border-slate-800 bg-slate-900/60 p-3"
+            data-testid="start-from-design-resolved"
+          >
+            <div class="flex items-center gap-2 text-sm text-white">
+              <UIcon name="i-lucide-frame" class="h-4 w-4 text-indigo-400" />
+              <span class="truncate">{{ row.label }}</span>
+            </div>
+            <p v-if="row.trimmed" class="text-[11px] text-slate-400">
+              {{ t('documents.startFromDesign.trimmed') }}
+            </p>
+            <!-- Its own line, in amber: a trim resolves the same page, a drop widens ONE frame to
+                 the whole design file, and the second is what a designer needs to see. -->
+            <p v-if="row.droppedScope" class="text-[11px] text-amber-300">
+              {{ t('documents.startFromDesign.widened', { scope: row.droppedScope }) }}
+            </p>
+            <p v-if="row.unchecked && target" class="text-[11px] text-slate-400">
+              {{ t('documents.startFromDesign.unchecked') }}
+            </p>
+            <p v-else-if="row.unchecked" class="text-[11px] text-amber-300">
+              {{ t('documents.startFromDesign.uncheckedAmbiguous') }}
+            </p>
+          </div>
+
+          <p
+            v-else-if="state.status === 'rejected'"
+            class="text-sm text-amber-300"
+            data-testid="start-from-design-rejected"
+          >
+            {{ t('documents.startFromDesign.rejected') }}
+          </p>
+        </template>
+
+        <div class="flex justify-end gap-2 pt-1">
+          <UButton color="neutral" variant="ghost" @click="ui.closeStartFromDesign()">
+            {{ t('common.cancel') }}
+          </UButton>
+          <UButton
+            color="primary"
+            icon="i-lucide-arrow-right"
+            :disabled="!row || !target"
+            data-testid="start-from-design-continue"
+            @click="stage"
+          >
+            {{ t('documents.startFromDesign.continue') }}
+          </UButton>
+        </div>
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/components/environments/EnvironmentSetupWizard.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 // The environment setup wizard shell (shared-stacks slice 7; converted to a
 // modular-vue journey in slice 3 of the modular-vue adoption —
-// docs/initiatives/modular-vue-adoption.md).
+// backend/docs/adr/0049-modular-vue-adoption.md).
 //
 // This component is now purely the MODAL + STEPPER CHROME. The step sequence,
 // forward/back navigation, and resume are owned by the `environment-setup`

package/app/components/environments/steps/JourneyStepNav.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 // Shared footer chrome for a modular-vue journey step (slice 3 of the modular-vue
-// adoption — docs/initiatives/modular-vue-adoption.md). Renders the Back control
+// adoption — backend/docs/adr/0049-modular-vue-adoption.md). Renders the Back control
 // (wired to the host-provided `goBack`, present only when the current entry
 // declared `allowBack` and there's a prior step) plus a `primary` slot for the
 // step's own advance affordance, so gating stays local to each step.

package/app/components/layout/AccountDeploymentSettings.vue

@@ -39,9 +39,14 @@ watch(
 
 const slack = reactive({ clientId: '', clientSecret: '', redirectUrl: '' })
 const linear = reactive({ clientId: '', clientSecret: '', redirectUrl: '' })
+// The deployment's registered Figma app, which is what turns "Connect with Figma" on for every
+// board in the account. Without it the Figma document source still connects, by personal access
+// token — which is the step this exists to spare a designer.
+const figma = reactive({ clientId: '', clientSecret: '', redirectUrl: '' })
 const web = reactive({ braveApiKey: '', searxngUrl: '', searxngApiKey: '' })
 const savingSlack = ref(false)
 const savingLinear = ref(false)
+const savingFigma = ref(false)
 const savingWeb = ref(false)
 
 const summary = computed(() => store.view?.summary ?? null)
@@ -289,6 +294,62 @@ async function clearLinear() {
   }
 }
 
+async function saveFigma() {
+  if (!figma.clientId.trim() || !figma.clientSecret.trim() || !figma.redirectUrl.trim()) {
+    toast.add({ title: t('layout.accountDeployment.figma.validation'), color: 'error' })
+    return
+  }
+  savingFigma.value = true
+  try {
+    await store.save(props.accountId, {
+      secrets: {
+        figmaOAuth: {
+          clientId: figma.clientId.trim(),
+          clientSecret: figma.clientSecret.trim(),
+          redirectUrl: figma.redirectUrl.trim(),
+        },
+      },
+    })
+    figma.clientId = ''
+    figma.clientSecret = ''
+    figma.redirectUrl = ''
+    toast.add({
+      title: t('layout.accountDeployment.figma.saved'),
+      icon: 'i-lucide-check',
+      color: 'success',
+    })
+  } catch (e) {
+    toast.add({
+      title: t('layout.accountDeployment.figma.saveFailed'),
+      description: e instanceof Error ? e.message : String(e),
+      color: 'error',
+    })
+  } finally {
+    savingFigma.value = false
+  }
+}
+
+async function clearFigma() {
+  if (!(await confirmAction('clear', 'Figma'))) return
+  savingFigma.value = true
+  try {
+    await store.save(props.accountId, { secrets: { figmaOAuth: null } })
+    toast.add({
+      title: t('layout.accountDeployment.figma.cleared'),
+      icon: 'i-lucide-check',
+      color: 'success',
+    })
+  } catch (e) {
+    toast.add({
+      title: t('layout.accountDeployment.figma.clearFailed'),
+      description: e instanceof Error ? e.message : String(e),
+      color: 'error',
+    })
+  } finally {
+    savingFigma.value = false
+  }
+}
+
 async function saveWeb() {
   const brave = web.braveApiKey.trim()
   const searxng = web.searxngUrl.trim()
@@ -479,6 +540,67 @@ async function clearWeb() {
       </div>
     </section>
 
+    <!-- Figma app OAuth (the document source's designer-doable connect) -->
+    <section class="space-y-2 border-t border-slate-800 pt-6">
+      <div class="flex items-center gap-2">
+        <h4 class="text-sm font-semibold text-slate-200">
+          {{ t('layout.accountDeployment.figma.title') }}
+        </h4>
+        <UBadge
+          :color="summary?.figmaOAuthConfigured ? 'success' : 'neutral'"
+          variant="subtle"
+          size="xs"
+        >
+          {{
+            summary?.figmaOAuthConfigured
+              ? t('layout.accountDeployment.configured')
+              : t('layout.accountDeployment.notSet')
+          }}
+        </UBadge>
+      </div>
+      <p class="text-[11px] text-slate-400">
+        {{ t('layout.accountDeployment.figma.description') }}
+      </p>
+      <div class="grid grid-cols-1 gap-2 sm:grid-cols-3">
+        <UInput
+          v-model="figma.clientId"
+          :placeholder="t('layout.accountDeployment.figma.clientId')"
+          size="sm"
+        />
+        <SecretInput
+          v-model="figma.clientSecret"
+          :placeholder="t('layout.accountDeployment.figma.clientSecret')"
+          size="sm"
+        />
+        <UInput
+          v-model="figma.redirectUrl"
+          :placeholder="t('layout.accountDeployment.figma.redirectUrl')"
+          size="sm"
+        />
+      </div>
+      <div class="flex gap-2">
+        <UButton
+          color="primary"
+          size="xs"
+          icon="i-lucide-save"
+          :loading="savingFigma"
+          @click="saveFigma"
+        >
+          {{ t('common.save') }}
+        </UButton>
+        <UButton
+          v-if="summary?.figmaOAuthConfigured"
+          color="neutral"
+          variant="ghost"
+          size="xs"
+          :loading="savingFigma"
+          @click="clearFigma"
+        >
+          {{ t('layout.accountDeployment.clear') }}
+        </UButton>
+      </div>
+    </section>
+
     <!-- Web search keys -->
     <section class="space-y-2 border-t border-slate-800 pt-6">
       <div class="flex items-center gap-2">

package/app/components/layout/BoardToolbar.vue

@@ -5,7 +5,7 @@ import IconButton from '~/components/common/IconButton.vue'
 
 const ui = useUiStore()
 const board = useBoardStore()
-// Toolbar contributions from the shared nav manifest (docs/initiatives/modular-vue-adoption.md,
+// Toolbar contributions from the shared nav manifest (backend/docs/adr/0049-modular-vue-adoption.md,
 // slice 1). First-party contributes none — this is the reactive extension point a consumer
 // deployment uses to add a board-toolbar action via `registerAppModule`, gated + rendered like
 // the sidebar/command entries with zero edits here.

package/app/components/layout/CommandBar.vue

@@ -26,7 +26,7 @@ const library = useFragmentLibraryStore()
 const access = useWorkspaceAccess()
 
 // The static destination catalog + its RBAC/availability gating now comes from
-// the shared nav manifest (docs/initiatives/modular-vue-adoption.md, slice 1),
+// the shared nav manifest (backend/docs/adr/0049-modular-vue-adoption.md, slice 1),
 // rendered here as command entries. The DYNAMIC per-connection commands below
 // (github/slack/doc/task connect + import) stay local to the palette — they vary
 // per live connection, so they are not part of the static manifest this slice.

package/app/components/layout/SideBar.vue

@@ -31,7 +31,7 @@ const providerConnections = useProviderConnectionsStore()
 const ui = useUiStore()
 
 // The nav catalog + its reactive RBAC/availability gating now lives in the shared
-// modular-vue manifest (docs/initiatives/modular-vue-adoption.md, slice 1): every
+// modular-vue manifest (backend/docs/adr/0049-modular-vue-adoption.md, slice 1): every
 // destination is declared once in `nav-contributions.ts`, gated by `navSlotFilter`
 // over a reactive `gates` service, and rendered here (and in CommandBar / BoardToolbar)
 // from `useReactiveSlots`. Sections + items appear/disappear reactively as a permission
@@ -230,7 +230,7 @@ watch(
       </button>
 
       <!-- Sections + items come from the shared nav manifest, already gated by the
-         reactive slotFilter (docs/initiatives/modular-vue-adoption.md, slice 1) — which
+         reactive slotFilter (backend/docs/adr/0049-modular-vue-adoption.md, slice 1) — which
          also drops the `advanced` items in basic interface mode. An empty section is
          dropped upstream, so there is no per-section `v-if` here.
          In the rail the section HEADERS go (they'd wrap to nothing at 3.5rem) but the

package/app/components/merge/MergeEffortChips.vue

@@ -6,7 +6,7 @@
 // Tagging is never mandatory: the parent can always act without a selection, and an untagged
 // merge records a null tag. This component only chooses; the parent performs the action.
 //
-// See docs/initiatives/merge-track-record.md.
+// See backend/docs/adr/0046-merge-track-record.md.
 import { computed } from 'vue'
 import { REVIEW_EFFORTS } from '@cat-factory/contracts'
 import type { ChangeClass, MergeClassRollup, ReviewEffort } from '~/types/merge'

package/app/components/panels/InspectorPanel.vue

@@ -524,7 +524,7 @@ const showOriginalDescription = ref(false)
            `Block | null` is rejected at compile time. `unknown` is the real
            runtime contract; `as any` is the minimal unblock until the binding
            types the prop explicitly (filed upstream — see the slice-4 residuals
-           in docs/initiatives/modular-vue-slice4-upstream-zones.md). -->
+           in backend/docs/adr/0049-modular-vue-adoption.md). -->
       <PanelsOutlet
         :group="inspectorPanels"
         :subject="(block ?? null) as any"

package/app/components/panels/ResultWindowShell.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 // Shared modal shell for the agent-run result windows (slice 5 of the modular-vue
-// adoption — docs/initiatives/modular-vue-adoption.md; progress in
-// docs/initiatives/modular-vue-slice5-progress.md).
+// adoption — backend/docs/adr/0049-modular-vue-adoption.md; progress in
+// backend/docs/adr/0049-modular-vue-adoption.md).
 //
 // Every result window (the merger verdict, the tester report, the requirements-review
 // loop, the gates, …) used to hand-roll the SAME modal chrome — `<Teleport>`, a

package/app/components/panels/StepResultViewHost.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 // Universal dedicated-result-view host (slice 2 of the modular-vue adoption —
-// docs/initiatives/modular-vue-adoption.md). An agent archetype can declare a
+// backend/docs/adr/0049-modular-vue-adoption.md). An agent archetype can declare a
 // `resultView` id (see `~/utils/catalog`); when a step of that kind is opened,
 // `ui.resultView` is set and this host mounts the matching registered window
 // instead of the generic `AgentStepDetail` prose panel.

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

@@ -195,7 +195,7 @@ function setResolveOnMerge(value: WritebackOverride | null) {
   board.updateBlock(props.block.id, { trackerResolveOnMerge: value })
 }
 // Only consulted for runs started through the public API — a task started here keeps its in-app
-// clarification window regardless (docs/initiatives/headless-clarification-loop.md).
+// clarification window regardless (backend/docs/adr/0047-headless-clarification-loop.md).
 function setQuestionsOnPark(value: WritebackOverride | null) {
   board.updateBlock(props.block.id, { trackerQuestionsOnPark: value })
 }

package/app/components/settings/MergeClassRulesEditor.vue

@@ -6,7 +6,7 @@
 //
 // `unknown` is deliberately not listed: no rule may ever match it (an unclassifiable diff must
 // fall back to the score ceilings), so offering one would be a lie. See
-// docs/initiatives/merge-track-record.md.
+// backend/docs/adr/0046-merge-track-record.md.
 import { computed } from 'vue'
 import { autoMergeShare, frictionlessShare, RULEABLE_CHANGE_CLASSES } from '@cat-factory/contracts'
 import type { MergeClassRule, MergeClassRules } from '~/types/merge'

package/app/composables/api/documents.ts

@@ -1,6 +1,7 @@
 import {
   connectDocumentSourceContract,
   disconnectDocumentSourceContract,
+  documentSourceOAuthUrlContract,
   importDocumentContract,
   linkDocumentContract,
   linkDocumentForKindContract,
@@ -41,6 +42,14 @@ export function documentsApi({ send, ws }: ApiContext) {
         body: { credentials },
       }),
 
+    // The vendor authorization URL for a source's OAuth connect. Admin-tier: what it hands back
+    // is the first half of a credential write, completed by the public callback.
+    documentSourceOAuthUrl: (workspaceId: string, source: DocumentSourceKind) =>
+      send(documentSourceOAuthUrlContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { source },
+      }),
+
     disconnectDocumentSource: (workspaceId: string, source: DocumentSourceKind) =>
       send(disconnectDocumentSourceContract, {
         pathPrefix: ws(workspaceId),
@@ -77,12 +86,14 @@ export function documentsApi({ send, ws }: ApiContext) {
         body: { query },
       }),
 
-    planDocument: (workspaceId: string, source: DocumentSourceKind, externalId: string) =>
-      send(planDocumentContract, {
-        pathPrefix: ws(workspaceId),
-        pathParams: { source },
-        body: { externalId },
-      }),
+    // `frameId` makes the plan TARGET-AWARE: modules and tasks for a service that already exists
+    // rather than an architecture. The same frame is sent to the spawn, so the preview and the
+    // write agree about the target.
+    planDocument: (
+      workspaceId: string,
+      source: DocumentSourceKind,
+      body: { externalId: string; frameId?: string },
+    ) => send(planDocumentContract, { pathPrefix: ws(workspaceId), pathParams: { source }, body }),
 
     spawnDocument: (
       workspaceId: string,

package/app/composables/useDocumentSourceConnect.ts

@@ -0,0 +1,88 @@
+import { computed, type ComputedRef, type Ref } from 'vue'
+import { isDesignSource } from '@cat-factory/contracts'
+import type {
+  DocumentConnection,
+  DocumentSourceDescriptor,
+  DocumentSourceKind,
+} from '~/types/domain'
+
+/**
+ * How this workspace CONNECTS to a document source, and what it may connect with.
+ *
+ * Split out of `stores/documents.ts` when the OAuth half landed, because "which credential can
+ * this board offer for this source" turned into a question with several parts: a source declares
+ * an OAuth half in code, the deployment may or may not have registered an app for it, and the
+ * typed-credential form is the fallback either way. The store's other concerns (the imported
+ * documents, their freshness, the doc-kind role links) never read any of it.
+ *
+ * It takes bound accessors rather than the store, so it stays testable on its own and cannot
+ * reach for state it has no business in.
+ */
+export interface DocumentSourceConnectDeps {
+  workspaceId: () => string
+  /**
+   * The sources this DEPLOYMENT can OAuth, as the backend reports them beside the descriptors.
+   *
+   * Owned by the caller (the probe writes it) rather than fetched here, because it arrives on the
+   * same response as the descriptors and a second read would be a second round trip that could
+   * disagree with the first.
+   */
+  oauthSources: Ref<DocumentSourceKind[]>
+  /** The connected subset of the descriptors, in registry order. */
+  connectedSources: ComputedRef<DocumentSourceDescriptor[]>
+  /** Fold a new/updated connection into the caller's list. */
+  onConnected: (connection: DocumentConnection) => void
+  /** Drop a source's connection from the caller's list. */
+  onDisconnected: (source: DocumentSourceKind) => void
+}
+
+export function useDocumentSourceConnect(deps: DocumentSourceConnectDeps) {
+  const api = useApi()
+
+  /**
+   * Whether this deployment can run the OAuth connect for a source RIGHT NOW.
+   *
+   * Deliberately not `descriptor.oauth !== undefined`: that says the source supports the flow,
+   * which is true of Figma on every deployment, including the ones that have registered no app.
+   * A button rendered off the descriptor alone could only 503.
+   */
+  function canConnectWithOAuth(source: DocumentSourceKind): boolean {
+    return deps.oauthSources.value.includes(source)
+  }
+
+  /**
+   * Every CONNECTED design source, in the order the backend registered them.
+   *
+   * `isDesignSource` comes from contracts rather than a local list, for the reason the backend
+   * reads it there: whether a source describes a design is a fact both sides have to agree about,
+   * and a second copy here would drift the moment a source is added.
+   */
+  const connectedDesignSources = computed(() =>
+    deps.connectedSources.value.map((s) => s.source).filter(isDesignSource),
+  )
+
+  /** Connect the workspace to a source with its credential bag. */
+  async function connect(source: DocumentSourceKind, credentials: Record<string, string>) {
+    deps.onConnected(await api.connectDocumentSource(deps.workspaceId(), source, credentials))
+  }
+
+  /** Disconnect the workspace from a source. */
+  async function disconnect(source: DocumentSourceKind) {
+    await api.disconnectDocumentSource(deps.workspaceId(), source)
+    deps.onDisconnected(source)
+  }
+
+  /**
+   * Send the browser to a source's vendor consent screen.
+   *
+   * A full navigation rather than a popup: the vendor lands back on the app's own OAuth callback,
+   * which stores the grant and redirects here, so the returning page re-probes and sees the
+   * connection. A popup would leave the opener holding stale state with nothing to tell it.
+   */
+  async function beginOAuthConnect(source: DocumentSourceKind) {
+    const { url } = await api.documentSourceOAuthUrl(deps.workspaceId(), source)
+    window.location.assign(url)
+  }
+
+  return { canConnectWithOAuth, connectedDesignSources, connect, disconnect, beginOAuthConnect }
+}

package/app/modular/agent-kinds.ts

@@ -2,7 +2,7 @@ import type { AgentArchetype, CustomAgentKind } from '~/types/domain'
 
 /**
  * Custom agent-kind projection (slice 2 of the modular-vue adoption —
- * docs/initiatives/modular-vue-adoption.md).
+ * backend/docs/adr/0049-modular-vue-adoption.md).
  *
  * A deployment's BACKEND-registered agent kinds arrive in the workspace snapshot as
  * `customAgentKinds` (wire data), folded into the shared per-workspace capability manifest

package/app/modular/external-tools.spec.ts

@@ -33,6 +33,7 @@ const GATES: NavGates = {
   canManageSettings: true,
   githubAvailable: true,
   libraryAvailable: true,
+  designSourceConnected: true,
   infrastructureAvailable: true,
   accountsEnabled: true,
   isAccountAdmin: true,

package/app/modular/journeys/environmentSetup.logic.ts

@@ -1,6 +1,6 @@
 /**
  * Pure navigation logic for the environment-setup journey (slice 3 of the
- * modular-vue adoption — docs/initiatives/modular-vue-adoption.md).
+ * modular-vue adoption — backend/docs/adr/0049-modular-vue-adoption.md).
  *
  * The journey owns only the WIZARD NAVIGATION — the ordered steps
  * (pick → review → preflight → save), the forward transitions, and the