@cat-factory/app 0.215.1 → 0.216.0

package/README.md

@@ -18,6 +18,9 @@ The SPA source lives under `app/` (the Nuxt srcDir).
 - [Interface modes (basic / advanced)](#interface-modes-basic--advanced)
 - [Agent tiers (basic / intermediate / advanced)](#agent-tiers-basic--intermediate--advanced)
 - [In-app tutorial tours](#in-app-tutorial-tours)
+- [Real-time store coherence](#real-time-store-coherence-avoid-the-full-refresh-clobber)
+- [Internationalization (i18n) authoring](#internationalization-i18n-authoring)
+- [Extending the layer (consumer modules)](#extending-the-layer-consumer-modules)
 - [Key UI surfaces](#key-ui-surfaces)
 - [Develop & test](#develop--test)
 
@@ -329,7 +332,7 @@ is SUPPRESSED rather than unmounted, because it holds the running tour's resolve
 remount would re-resolve it against gates that may have flipped since the tour started.
 
 The decisions behind this surface, and why each alternative was rejected, are recorded in
-[ADR 0033](../../backend/docs/adr/0033-in-app-tutorials.md). This section is the authority on how
+[ADR 0036](../../backend/docs/adr/0036-in-app-tutorials.md). This section is the authority on how
 the thing WORKS.
 
 A tour is **data, not components**: an ordered list of steps, each pointing at an on-screen
@@ -511,6 +514,111 @@ guard scans the layer for both ways an id is named: written onto an element, or
 `testId` field on a data contribution (the whole `nav-*` family reaches the DOM that way). It
 is scoped to the built-in catalog, since a consumer's tours anchor on its own layer.
 
+## Real-time store coherence: avoid the full-refresh CLOBBER
+
+The recurring product bug behind most e2e flakes: a stale full-snapshot refresh clobbering newer
+live state. The SPA has two delivery shapes and mixing them wrong drops live-added state with NO
+event left to restore it.
+
+- **Know how your entity is delivered.** A `board` event is COARSE: no payload, only a debounced
+  full `workspace.refresh()`, and `hydrate` REPLACES whole lists. A spawned task/module block
+  reaches the browser ONLY this way. Targeted events (`execution`/`bootstrap`/`initiative`) carry
+  the entity and `upsert` it, so they don't clobber. Prefer a targeted upsert for anything that
+  must appear reliably.
+- **Full refreshes MUST be monotonic.** Two `refresh()` calls can be in flight; a staler one
+  resolving later overwrites the newer. `workspace.refresh()` guards this with a sequence. Do not
+  reintroduce an unguarded `hydrate(await fetch())`, and apply the guard to any new coalesced
+  refresh path.
+- **Never gate readiness on a snapshot a later resync can undo.** The on-connect resync flips
+  `connected` only after it settles (which is why e2e gates on `data-connected`).
+- **A REPLACE-style `hydrate` must never silently drop live-only state.** Either fold that state
+  into the snapshot or reconcile rather than replace.
+- **An action's OPTIMISTIC ECHO is a clobber too, and it bypasses both guards above.** A store
+  that awaits a mutation and then assigns the returned sub-state onto the cached run
+  (`step.forkDecision`, `step.prReview`, `step.judge`, `step.followUps`) is writing straight past
+  `upsert`'s `rev` check. Where the mutation WAKES THE DRIVER, the driver's next emit routinely
+  beats the HTTP response, so the echo puts the run back; if the run then parks, nothing emits
+  again and the newer state is gone for good (the fork-chat reply that vanished, leaving a
+  "thinking…" bubble spinning). Every echo therefore goes through
+  `execution.echoAfter(executionId, send, apply)`, which captures the run's `rev` before the
+  request and drops the echo if anything advanced it. Never hand-roll the await-then-assign.
+- **Pin it with a store-level unit test** (`stores/workspace.spec.ts` for refreshes,
+  `stores/execution.spec.ts` for echoes): drive the two orderings and assert the fresher one
+  wins.
+
+## Internationalization (i18n) authoring
+
+All user-facing SPA copy goes through `@nuxtjs/i18n`; never hard-code a display string. This
+layer ships the base `en` locale, and a downstream deployment overrides by dropping its own files
+(the per-layer deep-merge is the override seam, consumer wins key by key). Migration status:
+[`docs/localization.md`](../../docs/localization.md).
+
+- `i18n/locales/<locale>.json`: the catalogs (the v9+ `i18n/` convention, NOT `app/locales/`).
+- `i18n/i18n.config.ts`: runtime vue-i18n behaviour only (fallback locale, the named
+  `numberFormats`/`datetimeFormats`). Messages are deliberately NOT here so the module can
+  deep-merge across the `extends` chain. Referenced as the BARE filename
+  `vueI18n: 'i18n.config.ts'`, never `layerDir`-anchored.
+- `package.json` `files` MUST include `"i18n"`. Release-blocking.
+
+**Adding a string**: add the key to `en.json` under the feature namespace, resolve with
+`t('feature.area.key')`, and format numbers/dates through `$n`/`$d` (the named formats), never
+raw `Intl`.
+
+**Key conventions**: one namespace per feature; **leaf keys mirror the enum/code value verbatim**
+so a dynamic lookup is total; **no cross-key concatenation** (a full sentence is ONE key with
+`{named}` placeholders, plurals use the pipe form).
+
+**Component mechanics that bite:**
+
+- `useI18n` is auto-imported; destructure in `<script setup>` and use those fns in the template
+  so the typed-key check sees literal keys. Never `import` it.
+- Plural + interpolation: `t(key, { vendor, count }, count)`, where the THIRD arg is the choice.
+- **Code/format-example placeholders stay INLINE**, not in the catalog; required when they
+  contain `{`/`}` (vue-i18n metacharacters). Only prose placeholders get a key. Same for brand
+  names.
+- **No HTML in message bodies**: drop mid-sentence `<strong>`, or use `<i18n-t>` with slots.
+- For a vendor/enum-keyed set, build an array of STATIC literal `t()` keys, one per member.
+  Reserve the runtime-assembled key + exhaustive `Record` guard for lookups genuinely unknown
+  until runtime.
+- Straight quotes, no em-dashes in new entries.
+
+**Translator descriptions (`@<key>` siblings): default to NONE.** They live only in `en.json` and
+are notes to a translator, never runtime data. Add one ONLY when a competent translator seeing
+the English and the key path could plausibly get it wrong: homograph / part-of-speech ambiguity
+(`@close`), proper nouns that must NOT be translated (`@kaizen`), umbrella strings hiding cases
+the text doesn't show, placeholder/format constraints, or plural-form requirements beyond
+English's two.
+
+**Presenting a backend failure**: raw backend prose is DETAIL, never the description. Even with
+no `reason` to key off, a failure is described from its STATUS CLASS through an exhaustive
+`Record<ApiErrorCode, …>` of translated copy, and the untranslated `message` (plus a validation
+400's `issues` and the envelope's `requestId`) is reached through a "Show details" disclosure
+that reveals it in place. So a non-English user is never handed English as the primary
+explanation, and the elaborate operator remedies the backend does write stay one click away
+rather than being dropped. A new failure-presenting surface copies that split (the
+`usePipelineErrorToast.ts` pattern; the wire vocabulary comes from `@cat-factory/contracts`).
+
+**Drift guards** (oxlint has no `no-raw-text` rule, so these replace it):
+
+1. **Typed message keys** make a statically written unknown `t('literal.key')` a typecheck
+   failure. This does NOT cover a runtime-assembled key.
+2. For enum→key lookups, guard with an **exhaustive `Record<TheEnum, string>`** keyed off the
+   contracts union, plus a runtime `te()` fallback. Never rely on tier 1 alone for a
+   reason/status-keyed lookup.
+3. `pnpm --filter @cat-factory/app run i18n:check` hard-fails on MISSING keys and reports unused
+   ones as non-blocking warnings (the catalog legitimately seeds keys ahead of use).
+4. **Locale parity**: `i18n-locale-parity.mjs --since origin/<base>` requires a PR that adds,
+   changes, or removes an `en.json` key to make the SAME change in every other locale. It is
+   change-coupling against the merge-base, NOT full key parity.
+
+**Translate for real: NEVER ship an English string as a non-`en` value.** The parity gate checks
+only that the key exists, so it will pass a verbatim English copy, and that copy is a bug. The
+only values that may legitimately match `en` are proper nouns identical across languages
+(`DeepSeek`, `AWS Bedrock`). If you genuinely cannot produce a translation, say so in the PR
+rather than committing a placeholder that reads as done.
+
+Migration is incremental: when you touch a component, lift its visible copy into the catalog.
+
 ## Extending the layer (consumer modules)
 
 A deployment can contribute its own components (result windows, nav entries, inspector

package/app/components/bootstrap/BootstrapModal.vue

@@ -5,9 +5,8 @@
 // architecture, or from scratch following a freeform prompt. The modal pairs the
 // launch form with the managed base list.
 import type { BootstrapStatus, FrameRepoType, ReferenceArchitecture } from '~/types/domain'
-// Explicit import (see GitHubPanel): the auto-import name for github/GitHubConnect
-// doesn't match the `<GitHubConnect>` tag, so bind it directly.
-import GitHubConnect from '~/components/github/GitHubConnect.vue'
+import VcsConnectSurfaces from '~/components/vcs/VcsConnectSurfaces.vue'
+import { appInstallationManageUrl, newRepoUrl, VCS_PROVIDER_LABELS } from '~/utils/vcs'
 
 const ui = useUiStore()
 const bootstrap = useBootstrapStore()
@@ -137,35 +136,42 @@ watch(
   { immediate: true },
 )
 
-// A bootstrap run pushes into a GitHub repo, so the workspace must be connected
-// first (the backend pre-flights the same and 409s otherwise). When the
-// integration is on but unconnected, surface the discover-and-link prompt inline
-// and block launch until it's bound.
-const needsGitHub = computed(() => github.available === true && !github.connected)
-
-// The account the repo must live under — the connected installation's account. The
-// run pushes into an existing repo here (cat-factory doesn't create it: a GitHub App
-// can't create repos under a personal account, and we'd rather not hold the broad
-// Administration permission). The repo must be empty or hold only a prepopulated
-// README/.gitignore/license — the push force-overwrites that boilerplate. The
-// convenience link opens GitHub's new-repo page prefilled so the user can create it
-// in one click.
+// A bootstrap run pushes into a repo on the connected host, so the workspace must be
+// connected first (the backend pre-flights the same and 409s otherwise). When the
+// integration is on but unconnected, surface the connect prompt inline and block launch
+// until it's bound.
+const needsConnection = computed(() => github.available === true && !github.connected)
+
+// The host this modal is about: the connected one, or the only one the deployment could
+// connect while nothing is bound. Null where it offers several and none is connected, so
+// `provider`'s own "what is connected" default can never send a GitLab deployment to github.com.
+const hostProvider = computed(() => github.surfaceProvider)
+const providerLabel = computed(() =>
+  hostProvider.value ? VCS_PROVIDER_LABELS[hostProvider.value] : '',
+)
+
+// The account the repo must live under — the connected account. The run pushes into an
+// existing repo here (cat-factory doesn't create it: a GitHub App can't create repos under a
+// personal account, and we'd rather not hold the broad Administration permission). The repo
+// must be empty or hold only a prepopulated README/.gitignore/license — the push
+// force-overwrites that boilerplate. The convenience link opens the host's own new-repo page,
+// prefilled, and is ABSENT for any host `~/utils/vcs` can't name (an unresolved provider, or a
+// GitLab whose instance nothing on the wire states); the copy and the button both key off it,
+// so what the intro promises and what renders cannot disagree.
 const repoOwner = computed(() => github.connection?.accountLogin ?? '')
-const createRepoUrl = computed(() => {
-  const params = new URLSearchParams()
-  if (repoOwner.value) params.set('owner', repoOwner.value)
-  const name = repoName.value.trim()
-  if (name) params.set('name', name)
-  const desc = description.value.trim()
-  if (desc) params.set('description', desc)
-  params.set('visibility', isPrivate.value ? 'private' : 'public')
-  return `https://github.com/new?${params.toString()}`
-})
+const createRepoUrl = computed(() =>
+  newRepoUrl(hostProvider.value, {
+    owner: repoOwner.value,
+    name: repoName.value.trim(),
+    description: description.value.trim(),
+    private: isPrivate.value,
+  }),
+)
 
 const creatingRepo = ref(false)
 
 // The "create repository" button behaves differently per tier. Restricted orgs
-// (the default) open GitHub's new-repo page prefilled — cat-factory needs no
+// (the default) open the host's new-repo page — cat-factory needs no
 // repo-creation permission. Privileged orgs (the connection reports
 // `canCreateRepos`) create it programmatically via the backend, with no page.
 async function openCreateRepo() {
@@ -173,7 +179,9 @@ async function openCreateRepo() {
   if (!name || repoNameError.value) return
 
   if (!github.canCreateRepos) {
-    window.open(createRepoUrl.value, '_blank', 'noopener')
+    // The button is hidden without a resolved host, so there is always a URL here; the guard
+    // keeps that a local fact rather than an assumption about the template.
+    if (createRepoUrl.value) window.open(createRepoUrl.value, '_blank', 'noopener')
     return
   }
 
@@ -207,20 +215,15 @@ async function openCreateRepo() {
 // "not accessible to the GitHub App". Link straight to the connected
 // installation's settings page, where the user adds the repo to its access list
 // in one click — no install/connect round-trip (the workspace is already bound).
-const manageInstallUrl = computed(() => {
-  const conn = github.connection
-  if (!conn) return undefined
-  return conn.targetType === 'Organization'
-    ? `https://github.com/organizations/${conn.accountLogin}/settings/installations/${conn.installationId}`
-    : `https://github.com/settings/installations/${conn.installationId}`
-})
+// Absent on a PAT connection, which grants no per-installation access (see `~/utils/vcs`).
+const manageInstallUrl = computed(() => appInstallationManageUrl(github.connection))
 
 function openManageInstall() {
   if (manageInstallUrl.value) window.open(manageInstallUrl.value, '_blank', 'noopener')
 }
 
 const canLaunch = computed(() => {
-  if (needsGitHub.value) return false
+  if (needsConnection.value) return false
   if (!repoName.value.trim() || repoNameError.value) return false
   return usingReference.value ? !!selectedArchId.value : instructions.value.trim().length > 0
 })
@@ -420,22 +423,34 @@ const statusLabel = computed<Record<BootstrapStatus, string>>(() => ({
   <UModal v-model:open="open" :title="t('bootstrap.title')" :ui="{ content: 'max-w-2xl' }">
     <template #body>
       <div class="space-y-6">
+        <!-- Three states, because each promises the user something different about the repo.
+             cat-factory creates it (privileged App tier, so a provider is always resolved);
+             the user creates it in one click on a host we can name; or the user creates it
+             themselves somewhere we cannot name, where promising a click below would be a lie
+             (the button is absent for exactly the same reason). -->
         <p class="text-sm text-slate-400">
-          {{ github.canCreateRepos ? t('bootstrap.intro.canCreate') : t('bootstrap.intro.manual') }}
+          {{
+            github.canCreateRepos
+              ? t('vcs.bootstrap.introCanCreate', { provider: providerLabel })
+              : createRepoUrl
+                ? t('vcs.bootstrap.introManual', { provider: providerLabel })
+                : t('vcs.bootstrap.introManualAny')
+          }}
         </p>
 
-        <!-- not connected: a run needs GitHub, so discover & link before launching -->
+        <!-- not connected: a run pushes to the host, so connect before launching. Offer
+             whichever methods the deployment serves, never just the GitHub App. -->
         <div
-          v-if="needsGitHub"
+          v-if="needsConnection"
           class="space-y-3 rounded-md border border-amber-500/30 bg-amber-500/5 p-3"
         >
           <div class="flex items-start gap-2">
             <UIcon name="i-lucide-plug-zap" class="mt-0.5 h-4 w-4 shrink-0 text-amber-400" />
             <p class="text-sm text-amber-200/90">
-              {{ t('bootstrap.github.prompt') }}
+              {{ t('vcs.bootstrap.connectPrompt') }}
             </p>
           </div>
-          <GitHubConnect />
+          <VcsConnectSurfaces />
         </div>
 
         <!-- launch -->
@@ -484,7 +499,11 @@ const statusLabel = computed<Record<BootstrapStatus, string>>(() => ({
                   :placeholder="t('bootstrap.targetRepo.namePlaceholder')"
                   class="w-full"
                 />
+                <!-- Creating the repo for the user needs no host name; sending them to the
+                     host's own form needs one, so that variant waits until a host is
+                     resolved rather than guessing which page to open. -->
                 <UButton
+                  v-if="github.canCreateRepos || createRepoUrl"
                   color="neutral"
                   variant="subtle"
                   :icon="github.canCreateRepos ? 'i-lucide-plus' : 'i-lucide-external-link'"
@@ -493,14 +512,14 @@ const statusLabel = computed<Record<BootstrapStatus, string>>(() => ({
                   :title="
                     github.canCreateRepos
                       ? t('bootstrap.createRepo.titleNow')
-                      : t('bootstrap.createRepo.titleGitHub')
+                      : t('vcs.bootstrap.createRepoTitle', { provider: providerLabel })
                   "
                   @click="openCreateRepo"
                 >
                   {{
                     github.canCreateRepos
                       ? t('bootstrap.createRepo.now')
-                      : t('bootstrap.createRepo.onGitHub')
+                      : t('vcs.bootstrap.createRepoOn', { provider: providerLabel })
                   }}
                 </UButton>
               </div>
@@ -671,9 +690,11 @@ const statusLabel = computed<Record<BootstrapStatus, string>>(() => ({
             v-if="showArchForm"
             class="space-y-3 rounded-md border border-slate-700 bg-slate-900/80 p-3"
           >
+            <!-- The options come from the connected projection, so a repo to pick means a
+                 connection exists and `providerLabel` names it rather than guessing. -->
             <UFormField
               v-if="hasRepoOptions"
-              :label="t('bootstrap.arch.pickRepo.label')"
+              :label="t('vcs.bootstrap.archPickRepo', { provider: providerLabel })"
               :description="t('bootstrap.arch.pickRepo.description')"
             >
               <USelect

package/app/components/github/AddServiceFromRepoModal.vue

@@ -1,10 +1,11 @@
 <script setup lang="ts">
-// Add a board service backed by an EXISTING GitHub repository — no bootstrap
-// run. Unlike the bootstrap modal (which creates a repo and has an agent adapt
-// it in a container), this just links a repo the App can access to a fresh,
-// `ready` service frame. The workspace need not track the repo yet: the backend
-// links + syncs it on import. If the App can't see the wanted repo, the user
-// grants it access from here, then searches for it again.
+// Add a board service backed by an EXISTING repository — no bootstrap run. Unlike the
+// bootstrap modal (which creates a repo and has an agent adapt it in a container), this
+// just links a repo the workspace's connection can reach to a fresh, `ready` service
+// frame. The workspace need not track the repo yet: the backend links + syncs it on
+// import. On a GitHub App connection, a repo the App can't see yet is granted from here
+// and searched for again; a PAT connection has no such page (see `~/utils/vcs`), so what
+// is listed follows the token's own access.
 //
 // MONOREPO support: a repo flagged a monorepo can back SEVERAL services, each
 // pinned to a subdirectory. When the selected repo is a monorepo, the user
@@ -12,11 +13,12 @@
 // parent folder, in one pass — then adds them all at once. Directories that
 // already back a service on this board are shown but not selectable.
 import type { FrameRepoType, GitHubAvailableRepo } from '~/types/domain'
-import GitHubConnect from '~/components/github/GitHubConnect.vue'
 import RepoSearchEmpty from '~/components/github/RepoSearchEmpty.vue'
 import RepoTreeBrowser from '~/components/github/RepoTreeBrowser.vue'
+import VcsConnectSurfaces from '~/components/vcs/VcsConnectSurfaces.vue'
 import ServiceTestConfig from '~/components/panels/inspector/ServiceTestConfig.vue'
 import ServiceFragments from '~/components/panels/inspector/ServiceFragments.vue'
+import { appInstallationManageUrl, VCS_PROVIDER_LABELS } from '~/utils/vcs'
 
 const { t } = useI18n()
 
@@ -64,7 +66,22 @@ watch(
 )
 
 // The integration is on but this workspace isn't bound yet — connect first.
-const needsGitHub = computed(() => github.available === true && !github.connected)
+const needsConnection = computed(() => github.available === true && !github.connected)
+
+// Brand name of whatever the workspace connected, for the hint that names it. Only read where
+// a connection exists (the hints below the picker), so `provider` is the right question there.
+const providerLabel = computed(() => VCS_PROVIDER_LABELS[github.provider])
+
+// Which remedy the picker's hint offers: an App installation sends the user to its repo-access
+// list, a pasted token to the token's own scope. Asked of the CONNECTION rather than of the
+// manage URL below, so a host whose settings page we could not build (an Enterprise install,
+// say) never tells an App-connected user to go check their token's scope.
+const isAppConnection = computed(() => github.connection?.method === 'app')
+
+// The intro renders BEFORE a connection may exist, so it asks `surfaceProvider` instead and
+// stays neutral where the deployment offers several and none is bound: naming one would be a
+// guess, and `provider`'s own default would name GitHub on a GitLab-only deployment.
+const introProvider = computed(() => github.surfaceProvider)
 
 // Repos whose service is ALREADY mounted on THIS board can't be added again — adding here would
 // be a no-op. A repo whose service lives on ANOTHER board in the org stays addable: adding it
@@ -201,15 +218,10 @@ function clearSelection() {
   resetSelection()
 }
 
-// The App's installation settings page — where the user grants it access to a
-// repo it can't see yet (mirrors the bootstrap modal's "grant access" link).
-const manageInstallUrl = computed(() => {
-  const conn = github.connection
-  if (!conn) return undefined
-  return conn.targetType === 'Organization'
-    ? `https://github.com/organizations/${conn.accountLogin}/settings/installations/${conn.installationId}`
-    : `https://github.com/settings/installations/${conn.installationId}`
-})
+// The App's installation settings page — where the user grants it access to a repo it can't
+// see yet (mirrors the bootstrap modal's "grant access" link). Absent on a PAT connection,
+// which has no installation to manage, so the affordance and its hint both drop out.
+const manageInstallUrl = computed(() => appInstallationManageUrl(github.connection))
 
 function openManageInstall() {
   if (manageInstallUrl.value) window.open(manageInstallUrl.value, '_blank', 'noopener')
@@ -242,14 +254,14 @@ watch(
 // multi-selects directories and adds them together via `addServices`.
 const canAdd = computed(
   () =>
-    !needsGitHub.value &&
+    !needsConnection.value &&
     selectedRepoId.value !== undefined &&
     !isMonorepo.value &&
     !configuredBlockId.value,
 )
 const canAddServices = computed(
   () =>
-    !needsGitHub.value &&
+    !needsConnection.value &&
     selectedRepoId.value !== undefined &&
     isMonorepo.value &&
     selectedDirectories.value.length > 0,
@@ -357,27 +369,36 @@ function done() {
     <template #body>
       <div class="space-y-6">
         <p class="text-sm text-slate-400">
-          {{ t('github.addService.intro') }}
+          {{
+            introProvider
+              ? t('vcs.addService.intro', { provider: VCS_PROVIDER_LABELS[introProvider] })
+              : t('vcs.addService.introAny')
+          }}
         </p>
 
-        <!-- not connected: linking a repo needs the App bound to this workspace -->
+        <!-- not connected: linking a repo needs a connection bound to this workspace, so
+             offer whichever connect methods the deployment serves (never just the App) -->
         <div
-          v-if="needsGitHub"
+          v-if="needsConnection"
           class="space-y-3 rounded-md border border-amber-500/30 bg-amber-500/5 p-3"
         >
           <div class="flex items-start gap-2">
             <UIcon name="i-lucide-plug-zap" class="mt-0.5 h-4 w-4 shrink-0 text-amber-400" />
             <p class="text-sm text-amber-200/90">
-              {{ t('github.addService.connectFirst') }}
+              {{ t('vcs.addService.connectFirst') }}
             </p>
           </div>
-          <GitHubConnect />
+          <VcsConnectSurfaces />
         </div>
 
         <template v-else>
           <UFormField
             :label="t('github.addService.repository')"
-            :description="t('github.addService.repositoryHint')"
+            :description="
+              isAppConnection
+                ? t('vcs.addService.repositoryHintApp')
+                : t('vcs.addService.repositoryHintToken', { provider: providerLabel })
+            "
             required
           >
             <!-- The wrapper, not the UInputMenu itself, carries the anchor: a tutorial tour
@@ -521,9 +542,10 @@ function done() {
             <ServiceFragments :block="configuredBlock" default-open />
           </div>
 
-          <div class="flex flex-wrap items-center gap-2">
+          <!-- App connections only: a pasted token has no installation whose repo access
+               could be edited, so there is no page to send the user to. -->
+          <div v-if="manageInstallUrl" class="flex flex-wrap items-center gap-2">
             <UButton
-              v-if="manageInstallUrl"
               color="neutral"
               variant="subtle"
               size="sm"

package/app/components/github/GitHubOnboarding.vue

@@ -2,13 +2,9 @@
 // Hard onboarding gate shown after login when the VCS integration is enabled but the workspace
 // has no connection yet. cat-factory's whole flow runs on a connected repository host (agents
 // open pull/merge requests on the user's repos), so the board is withheld until the workspace
-// connects one. Renders the connect surfaces the deployment can actually serve: <GitHubConnect>
-// drives the account-level App install (https://github.com/apps/<slug>/installations/new — the
-// user picks the account/org and grants all or a subset of repos) plus the
-// pick-an-existing-installation path, and <GitLabConnect> takes a pasted GitLab PAT. A "Sign
-// out" escape hatch avoids trapping a user who needs to switch accounts.
-import GitHubConnect from '~/components/github/GitHubConnect.vue'
-import GitLabConnect from '~/components/vcs/GitLabConnect.vue'
+// connects one. <VcsConnectSurfaces> renders whichever connect methods the deployment serves; a
+// "Sign out" escape hatch avoids trapping a user who needs to switch accounts.
+import VcsConnectSurfaces from '~/components/vcs/VcsConnectSurfaces.vue'
 import { VCS_PROVIDER_ICONS, VCS_PROVIDER_LABELS } from '~/utils/vcs'
 
 const { t } = useI18n()
@@ -41,22 +37,7 @@ const title = computed(() =>
         </p>
       </div>
 
-      <template v-if="github.canConnectGitHubApp">
-        <p class="mb-3 text-sm text-slate-400">{{ t('github.onboarding.appIntro') }}</p>
-        <GitHubConnect />
-      </template>
-      <USeparator
-        v-if="github.canConnectGitHubApp && github.canConnectGitLabPat"
-        class="my-4"
-        :label="t('vcs.connect.or')"
-      />
-      <GitLabConnect v-if="github.canConnectGitLabPat" />
-      <p
-        v-if="!github.canConnectGitHubApp && !github.canConnectGitLabPat"
-        class="rounded-md border border-dashed border-slate-800 px-3 py-3 text-sm text-slate-400"
-      >
-        {{ t('vcs.connect.noneConfigured') }}
-      </p>
+      <VcsConnectSurfaces :app-intro="t('github.onboarding.appIntro')" />
 
       <p
         v-if="auth.required && auth.user"

package/app/components/github/GitHubPanel.vue

@@ -1,17 +1,14 @@
 <script setup lang="ts">
-// GitHub integration panel: connect the workspace's App installation, manage the
-// connection (disconnect / resync), and browse the projected repos, branches,
-// pull requests and issues the backend caches in D1. Mirrors the document-source
-// connect/import surface, but for GitHub. Writes (new branch, open/merge PR,
-// comment) go straight to the repo via the backend's installation token.
+// Source-control panel: connect the workspace, manage the connection (disconnect / resync),
+// and browse the projected repos, branches, pull requests and issues the backend caches.
+// Mirrors the document-source connect/import surface. Writes (new branch, open/merge PR,
+// comment) go straight to the repo via the backend's connection credential.
 import type { GitHubPullRequest, GitHubRepo, VcsProvider } from '~/types/domain'
-// Explicit import: the auto-import name for a component nested under a
-// like-named directory (github/GitHubConnect) doesn't match the `<GitHubConnect>`
-// tag, so it silently renders as an empty element. Importing it directly binds
-// the tag unambiguously.
-import GitHubConnect from './GitHubConnect.vue'
+// Explicit imports: the auto-import name for a component nested under a like-named directory
+// (github/BranchProtectionPreflight) doesn't match the tag used below, so it would silently
+// render as an empty element. Importing by path binds each tag unambiguously.
 import BranchProtectionPreflight from './BranchProtectionPreflight.vue'
-import GitLabConnect from '~/components/vcs/GitLabConnect.vue'
+import VcsConnectSurfaces from '~/components/vcs/VcsConnectSurfaces.vue'
 import IntegrationBackTitle from '~/components/layout/IntegrationBackTitle.vue'
 import { VCS_PROVIDER_ICONS, VCS_PROVIDER_LABELS } from '~/utils/vcs'
 
@@ -33,9 +30,7 @@ const back = useIntegrationBack(open)
 // Provider-aware chrome: once connected, the panel is titled for the provider the workspace
 // actually connected; before that it names the sole connectable provider, or stays neutral when
 // the deployment serves several. Brand names are verbatim in every locale (see `~/utils/vcs`).
-const chromeProvider = computed(() =>
-  github.connected ? github.provider : github.soleConnectProvider,
-)
+const chromeProvider = computed(() => github.surfaceProvider)
 const panelTitle = computed(() =>
   chromeProvider.value ? VCS_PROVIDER_LABELS[chromeProvider.value] : t('vcs.panel.title'),
 )
@@ -283,26 +278,7 @@ async function merge(pr: GitHubPullRequest) {
     <template #body>
       <div class="space-y-5">
         <!-- not connected: connect -->
-        <template v-if="!github.connected">
-          <!-- One connect surface per method the deployment actually serves: the App
-               installation picker only where a GitHub App is configured, the PAT box only
-               where the per-workspace GitLab connect is wired. -->
-          <template v-if="github.canConnectGitHubApp">
-            <p class="text-sm text-slate-400">{{ t('github.panel.connectIntro') }}</p>
-            <GitHubConnect />
-          </template>
-          <USeparator
-            v-if="github.canConnectGitHubApp && github.canConnectGitLabPat"
-            :label="t('vcs.connect.or')"
-          />
-          <GitLabConnect v-if="github.canConnectGitLabPat" />
-          <p
-            v-if="!github.canConnectGitHubApp && !github.canConnectGitLabPat"
-            class="rounded-md border border-dashed border-slate-800 px-3 py-3 text-sm text-slate-400"
-          >
-            {{ t('vcs.connect.noneConfigured') }}
-          </p>
-        </template>
+        <VcsConnectSurfaces v-if="!github.connected" :app-intro="t('github.panel.connectIntro')" />
 
         <!-- connected: manage + browse -->
         <template v-else>