@cat-factory/app 0.248.0 → 0.250.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/github/GitHubPanel.vue

@@ -51,6 +51,39 @@ const CONNECTION_META: Record<VcsProvider, () => string> = {
 }
 const connectionMeta = computed(() => CONNECTION_META[github.provider]())
 
+// GitHub opens PULL requests, GitLab opens MERGE requests, and the panel renders both providers'
+// rows through one component. The vocabulary is therefore a per-provider set of STATIC catalog
+// keys (an exhaustive Record, so a new provider fails the typecheck rather than shipping GitHub's
+// nouns), resolved off the connected provider — the panel only ever lists one connection's repos.
+const PULL_TERMS = {
+  github: {
+    tab: 'vcs.panel.pulls.github.tab',
+    open: 'vcs.panel.pulls.github.open',
+    openSubmit: 'vcs.panel.pulls.github.openSubmit',
+    merge: 'vcs.panel.pulls.github.merge',
+    none: 'vcs.panel.pulls.github.none',
+    opened: 'vcs.panel.pulls.github.opened',
+    mergedToast: 'vcs.panel.pulls.github.mergedToast',
+    openFailed: 'vcs.panel.pulls.github.openFailed',
+  },
+  gitlab: {
+    tab: 'vcs.panel.pulls.gitlab.tab',
+    open: 'vcs.panel.pulls.gitlab.open',
+    openSubmit: 'vcs.panel.pulls.gitlab.openSubmit',
+    merge: 'vcs.panel.pulls.gitlab.merge',
+    none: 'vcs.panel.pulls.gitlab.none',
+    opened: 'vcs.panel.pulls.gitlab.opened',
+    mergedToast: 'vcs.panel.pulls.gitlab.mergedToast',
+    openFailed: 'vcs.panel.pulls.gitlab.openFailed',
+  },
+} as const satisfies Record<VcsProvider, Record<string, string>>
+const pullTerms = computed(() => PULL_TERMS[github.provider])
+
+// What the repo picker can offer, and why a repo might be missing from it, differ by how the
+// workspace authenticates rather than by provider: an App installation is shared across the
+// account and has its own access list, a pasted token reaches exactly what its owner does.
+const isAppConnection = computed(() => github.connection?.method === 'app')
+
 // On open: refresh projections when connected. The not-connected state renders
 // <GitHubConnect>, which discovers and links installations on its own.
 watch(
@@ -111,7 +144,7 @@ type Tab = 'repos' | 'pulls' | 'issues'
 const tab = ref<Tab>('repos')
 const tabs = computed<{ id: Tab; label: string; icon: string }[]>(() => [
   { id: 'repos', label: t('github.panel.tabs.repos'), icon: 'i-lucide-folder-git-2' },
-  { id: 'pulls', label: t('github.panel.tabs.pulls'), icon: 'i-lucide-git-pull-request' },
+  { id: 'pulls', label: t(pullTerms.value.tab), icon: 'i-lucide-git-pull-request' },
   { id: 'issues', label: t('github.panel.tabs.issues'), icon: 'i-lucide-circle-dot' },
 ])
 
@@ -233,9 +266,9 @@ async function openPr() {
     })
     showPrForm.value = false
     prForm.value = { repoGithubId: null, title: '', head: '', base: '' }
-    toast.add({ title: t('github.panel.toast.prOpened'), icon: 'i-lucide-check', color: 'success' })
+    toast.add({ title: t(pullTerms.value.opened), icon: 'i-lucide-check', color: 'success' })
   } catch (e) {
-    notifyError(t('github.panel.errors.openPr'), e)
+    notifyError(t(pullTerms.value.openFailed), e)
   } finally {
     openingPr.value = false
   }
@@ -258,7 +291,7 @@ async function merge(pr: GitHubPullRequest) {
   try {
     await github.mergePullRequest(pr.repoGithubId, pr.number, { method: 'squash' })
     toast.add({
-      title: t('github.panel.toast.prMerged', { number: pr.number }),
+      title: t(pullTerms.value.mergedToast, { number: pr.number }),
       icon: 'i-lucide-git-merge',
       color: 'success',
     })
@@ -378,7 +411,9 @@ async function merge(pr: GitHubPullRequest) {
               class="space-y-2 rounded-md border border-slate-700 bg-slate-900/80 p-3"
             >
               <p class="text-[12px] text-slate-400">
-                {{ t('github.panel.manageHint') }}
+                {{
+                  isAppConnection ? t('vcs.panel.manageHintApp') : t('vcs.panel.manageHintToken')
+                }}
               </p>
               <div
                 v-if="github.loadingAvailable"
@@ -388,7 +423,11 @@ async function merge(pr: GitHubPullRequest) {
                 {{ t('github.panel.loadingRepos') }}
               </div>
               <p v-else-if="!github.availableRepos.length" class="py-2 text-sm text-slate-400">
-                {{ t('github.panel.noAvailableRepos') }}
+                {{
+                  isAppConnection
+                    ? t('vcs.panel.noAvailableReposApp')
+                    : t('vcs.panel.noAvailableReposToken')
+                }}
               </p>
               <div v-else class="max-h-64 space-y-1 overflow-y-auto">
                 <button
@@ -554,7 +593,7 @@ async function merge(pr: GitHubPullRequest) {
                   }
                 "
               >
-                {{ t('github.panel.openPr') }}
+                {{ t(pullTerms.open) }}
               </UButton>
             </div>
 
@@ -599,13 +638,13 @@ async function merge(pr: GitHubPullRequest) {
                   :disabled="!canOpenPr"
                   @click="openPr"
                 >
-                  {{ t('github.panel.openPullRequest') }}
+                  {{ t(pullTerms.openSubmit) }}
                 </UButton>
               </div>
             </div>
 
             <p v-if="!github.pulls.length" class="py-4 text-sm text-slate-400">
-              {{ t('github.panel.noPulls') }}
+              {{ t(pullTerms.none) }}
             </p>
             <div
               v-for="pr in github.pulls"
@@ -634,7 +673,7 @@ async function merge(pr: GitHubPullRequest) {
                   color="neutral"
                   variant="ghost"
                   icon="i-lucide-git-merge"
-                  :aria-label="t('github.panel.mergePr')"
+                  :aria-label="t(pullTerms.merge)"
                   :loading="merging === pr.number"
                   @click="merge(pr)"
                 />

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/panels/InspectorPanel.vue

@@ -7,6 +7,7 @@ import { inspectorPanels } from '~/modular/panels/inspector.logic'
 import IconButton from '~/components/common/IconButton.vue'
 import AgentFailureCard from '~/components/board/AgentFailureCard.vue'
 import AgentStopButton from '~/components/board/AgentStopButton.vue'
+import { VCS_PROVIDER_ICONS } from '~/utils/vcs'
 
 const board = useBoardStore()
 const pipelines = usePipelinesStore()
@@ -163,19 +164,23 @@ const serviceRepo = computed(() =>
 const serviceRepoUrl = computed(() =>
   serviceRepo.value ? github.repoUrl(serviceRepo.value.githubId) : null,
 )
-
-// A task's work branch on GitHub, once the agent has pushed one (a PR branch is
-// recorded on the block). Repo linkage lives on the owning service frame, not the
-// task, so resolve the repo by walking up to the frame; fall back to deriving the
-// repo base from the PR url when the projection hasn't loaded. Null until a branch
-// exists, so the link only appears after one is created.
+// The repo link wears its own provider's mark, off the projection row rather than the
+// workspace connection, so a row is never labelled with a brand it does not belong to.
+const serviceRepoIcon = computed(() => VCS_PROVIDER_ICONS[serviceRepo.value?.provider ?? 'github'])
+
+// A task's work branch on the connected host, once the agent has pushed one (a PR branch is
+// recorded on the block). Repo linkage lives on the owning service frame, not the task, so
+// resolve the repo by walking up to the frame, and let the store build the branch path for the
+// repo's own provider (GitLab addresses a tree under `/-/`). Null until a branch exists, so the
+// link only appears after one is created, and null while the projection has not loaded: the
+// former fallback sliced `/pull/<n>` off the PR url, which silently yields nothing on a GitLab
+// merge-request url and would need a second provider guess to fix.
 const taskBranchUrl = computed(() => {
   const pr = isTask.value ? block.value?.pullRequest : undefined
   if (!pr?.branch || !block.value) return null
   const frame = board.serviceOf(block.value)
   const repo = frame ? github.repoForBlock(frame.id) : undefined
-  const base = repo ? github.repoUrl(repo.githubId) : pr.url.replace(/\/pull\/\d+$/, '')
-  return base ? `${base}/tree/${pr.branch}` : null
+  return repo ? github.branchUrl(repo.githubId, pr.branch) : null
 })
 
 // The run MODE, shared with the focus view's Run picker so the two surfaces offer (and force)
@@ -470,7 +475,7 @@ const showOriginalDescription = ref(false)
           color="neutral"
           variant="soft"
           size="xs"
-          icon="i-lucide-github"
+          :icon="serviceRepoIcon"
           trailing-icon="i-lucide-external-link"
         >
           {{ serviceRepo!.owner }}/{{ serviceRepo!.name }}

package/app/components/vcs/GitLabConnect.vue

@@ -11,7 +11,7 @@
 // flattened into a generic toast.
 import SecretInput from '~/components/common/SecretInput.vue'
 import { apiErrorEnvelope } from '~/composables/api/errors'
-import { VCS_PROVIDER_TOKEN_URLS } from '~/utils/vcs'
+import { vcsTokenCreateUrl } from '~/utils/vcs'
 
 const { t } = useI18n()
 const github = useGitHubStore()
@@ -21,7 +21,13 @@ const pat = ref('')
 const connecting = ref(false)
 const error = ref<string | null>(null)
 
-const tokenUrl = VCS_PROVIDER_TOKEN_URLS.gitlab
+// The token page on the instance this deployment would connect, not on gitlab.com: a
+// self-managed GitLab's tokens are minted on its own host. The advertised host is null when the
+// deployment's API base does not name one, and only THIS link falls back to the public instance
+// (a wrong settings page costs a click; see `~/utils/vcs`).
+const tokenUrl = computed(() =>
+  vcsTokenCreateUrl('gitlab', github.connectOptions.find((o) => o.provider === 'gitlab')?.webUrl),
+)
 
 async function connect() {
   const token = pat.value.trim()

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,