@cat-factory/app 0.24.0 → 0.26.0

package/app/components/fragments/FragmentLibraryPanel.vue

@@ -4,10 +4,11 @@
 // + resync), and review the merged catalog (built-in ∪ account ∪ workspace) an
 // agent is selected from per run. Workspace-tier focused; the resolved view shows
 // every tier so the inheritance is visible.
-import type { ResolvedFragment } from '~/types/domain'
+import type { DocumentSourceKind, ResolvedFragment } from '~/types/domain'
 
 const ui = useUiStore()
 const library = useFragmentLibraryStore()
+const documents = useDocumentsStore()
 const toast = useToast()
 
 const open = computed({
@@ -18,10 +19,13 @@ const open = computed({
 })
 
 watch(open, (isOpen) => {
-  if (isOpen) void library.probe()
+  if (isOpen) {
+    void library.probe()
+    void documents.probe()
+  }
 })
 
-type Tab = 'catalog' | 'authored' | 'sources'
+type Tab = 'catalog' | 'authored' | 'documents' | 'sources'
 const tab = ref<Tab>('catalog')
 
 const tierLabel: Record<ResolvedFragment['tier'], string> = {
@@ -80,6 +84,42 @@ async function removeFragment(id: string) {
   }
 }
 
+// ---- document-backed (living) fragments -----------------------------------
+// Link a Confluence/Notion page or GitHub file as a fragment that is re-resolved
+// from the source at run time (a living source of truth, not a frozen snapshot).
+const docDraft = ref({ source: '' as DocumentSourceKind | '', ref: '', tags: '' })
+const docDraftValid = computed(() => docDraft.value.source && docDraft.value.ref.trim())
+
+/** The board's existing document-backed fragments (workspace tier). */
+const documentFragments = computed(() => library.fragments.filter((f) => f.documentRef))
+
+async function linkDocumentFragment() {
+  if (!docDraftValid.value) return
+  try {
+    await library.createDocumentFragment({
+      source: docDraft.value.source as DocumentSourceKind,
+      ref: docDraft.value.ref.trim(),
+      tags: docDraft.value.tags
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean),
+    })
+    docDraft.value = { source: '', ref: '', tags: '' }
+    toast.add({ title: 'Document linked as a living fragment', icon: 'i-lucide-link' })
+  } catch (e) {
+    notifyError('Could not link document', e)
+  }
+}
+
+async function refreshFragment(id: string) {
+  try {
+    await library.refreshDocumentFragment(id)
+    toast.add({ title: 'Fragment re-resolved from source', icon: 'i-lucide-refresh-cw' })
+  } catch (e) {
+    notifyError('Could not refresh fragment', e)
+  }
+}
+
 // ---- repo sources ----------------------------------------------------------
 const sourceDraft = ref({ repoOwner: '', repoName: '', dirPath: '', gitRef: '' })
 const sourceValid = computed(
@@ -150,7 +190,7 @@ async function unlinkSource(id: string) {
 
         <div class="flex gap-2">
           <UButton
-            v-for="t in ['catalog', 'authored', 'sources'] as Tab[]"
+            v-for="t in ['catalog', 'authored', 'documents', 'sources'] as Tab[]"
             :key="t"
             :color="tab === t ? 'primary' : 'neutral'"
             :variant="tab === t ? 'solid' : 'ghost'"
@@ -162,7 +202,9 @@ async function unlinkSource(id: string) {
                 ? 'Resolved catalog'
                 : t === 'authored'
                   ? 'This board'
-                  : 'Repo sources'
+                  : t === 'documents'
+                    ? 'Documents'
+                    : 'Repo sources'
             }}
           </UButton>
         </div>
@@ -183,6 +225,15 @@ async function unlinkSource(id: string) {
               <UBadge size="xs" :color="tierColor[f.tier]" variant="subtle">
                 {{ tierLabel[f.tier] }}
               </UBadge>
+              <UBadge
+                v-if="f.documentRef"
+                size="xs"
+                color="success"
+                variant="subtle"
+                icon="i-lucide-radio"
+              >
+                Live · {{ f.documentRef.source }}
+              </UBadge>
               <span class="ml-auto font-mono text-[11px] text-slate-500">{{ f.id }}</span>
             </div>
             <p class="mt-1 text-sm text-slate-400">{{ f.summary }}</p>
@@ -249,6 +300,91 @@ async function unlinkSource(id: string) {
           </div>
         </div>
 
+        <!-- Document-backed (living) fragments -->
+        <div v-else-if="tab === 'documents'" class="flex flex-col gap-3">
+          <p class="text-xs text-slate-500">
+            Link a Confluence/Notion page or a GitHub file as a best-practice fragment. Its guidance
+            is re-resolved from the source at run time — edit the doc and the next agent run follows
+            the new version (no re-import).
+          </p>
+
+          <div
+            v-for="f in documentFragments"
+            :key="f.id"
+            class="flex items-start gap-2 rounded-md border border-slate-800 bg-slate-900/60 p-3"
+          >
+            <UIcon name="i-lucide-radio" class="mt-0.5 h-4 w-4 text-emerald-400" />
+            <div class="min-w-0">
+              <div class="flex items-center gap-2">
+                <span class="font-medium text-slate-100">{{ f.title }}</span>
+                <UBadge size="xs" color="success" variant="subtle">
+                  {{ f.documentRef?.source }}
+                </UBadge>
+              </div>
+              <p class="text-sm text-slate-400">{{ f.summary }}</p>
+              <p v-if="f.resolvedAt" class="text-[11px] text-slate-500">
+                last resolved {{ new Date(f.resolvedAt).toLocaleString() }}
+              </p>
+            </div>
+            <div class="ml-auto flex gap-1">
+              <UButton
+                icon="i-lucide-refresh-cw"
+                size="xs"
+                variant="ghost"
+                :loading="library.loading"
+                title="Re-resolve from source now"
+                @click="refreshFragment(f.id)"
+              />
+              <UButton
+                icon="i-lucide-trash-2"
+                size="xs"
+                color="error"
+                variant="ghost"
+                @click="removeFragment(f.id)"
+              />
+            </div>
+          </div>
+          <p v-if="!documentFragments.length" class="text-sm text-slate-500">
+            No document-backed fragments yet. Link one below.
+          </p>
+
+          <div class="rounded-md border border-slate-800 p-3">
+            <p class="mb-2 text-sm font-medium">Link a document</p>
+            <div v-if="!documents.connectedSources.length" class="text-sm text-slate-500">
+              Connect a document source (Confluence, Notion or GitHub) under Integrations first.
+            </div>
+            <div v-else class="flex flex-col gap-2">
+              <div class="flex flex-wrap gap-2">
+                <UButton
+                  v-for="s in documents.connectedSources"
+                  :key="s.source"
+                  size="xs"
+                  :color="docDraft.source === s.source ? 'primary' : 'neutral'"
+                  :variant="docDraft.source === s.source ? 'solid' : 'outline'"
+                  @click="docDraft.source = s.source"
+                >
+                  {{ s.label }}
+                </UButton>
+              </div>
+              <UInput
+                v-model="docDraft.ref"
+                placeholder="Page id or URL (e.g. a Confluence/Notion page or GitHub file URL)"
+              />
+              <UInput v-model="docDraft.tags" placeholder="Tags, comma-separated (optional)" />
+              <UButton
+                icon="i-lucide-link"
+                size="sm"
+                :disabled="!docDraftValid"
+                :loading="library.loading"
+                class="self-start"
+                @click="linkDocumentFragment"
+              >
+                Link as living fragment
+              </UButton>
+            </div>
+          </div>
+        </div>
+
         <!-- Repo sources -->
         <div v-else class="flex flex-col gap-3">
           <div

package/app/components/layout/IntegrationsHub.vue

@@ -14,6 +14,7 @@ const documents = useDocumentsStore()
 const tasks = useTasksStore()
 const tracker = useTrackerStore()
 const releaseHealth = useReleaseHealthStore()
+const providerConnections = useProviderConnectionsStore()
 const userSecrets = useUserSecretsStore()
 const apiKeys = useApiKeysStore()
 const workspace = useWorkspaceStore()
@@ -32,6 +33,7 @@ watch(
   (isOpen) => {
     if (isOpen) {
       void releaseHealth.ensureLoaded().catch(() => {})
+      void providerConnections.ensureLoaded().catch(() => {})
       void userSecrets.load().catch(() => {})
       // Drives the OpenRouter row's "Key connected" badge.
       if (workspace.workspaceId) void apiKeys.load(workspace.workspaceId).catch(() => {})
@@ -224,6 +226,37 @@ const groups = computed<IntegrationGroup[]>(() => {
     })
   }
 
+  // --- Infrastructure (ephemeral environments + self-hosted runner pool) -----
+  // Each gates on its own availability probe, so a backend with the integration off
+  // shows no dead row. The connected badge reflects a saved connection; the
+  // ProviderConfigBanner handles the louder "missing mandatory fields" warning.
+  const infra: IntegrationItem[] = []
+  if (providerConnections.isAvailable('environment')) {
+    const conn = providerConnections.connectionFor('environment')
+    infra.push({
+      key: 'environment',
+      icon: 'i-lucide-cloud',
+      label: 'Ephemeral environments',
+      description: 'Where the Tester agent runs against a live preview environment.',
+      status: conn ? 'Connected' : undefined,
+      connected: !!conn,
+      onClick: () => go(() => ui.openProviderConnection('environment')),
+    })
+  }
+  if (providerConnections.isAvailable('runner-pool')) {
+    const conn = providerConnections.connectionFor('runner-pool')
+    infra.push({
+      key: 'runner-pool',
+      icon: 'i-lucide-server-cog',
+      label: 'Self-hosted runner pool',
+      description: 'Where the coding agents run when not using Cloudflare Containers.',
+      status: conn ? 'Connected' : undefined,
+      connected: !!conn,
+      onClick: () => go(() => ui.openProviderConnection('runner-pool')),
+    })
+  }
+  if (infra.length) out.push({ title: 'Infrastructure', items: infra })
+
   return out
 })
 </script>

package/app/components/layout/ProviderConfigBanner.vue

@@ -0,0 +1,88 @@
+<script setup lang="ts">
+// Loud prompt that an infrastructure provider is wired for this instance but the workspace
+// hasn't supplied its mandatory config yet — mirroring AiProvidersBanner. A custom
+// environment provider / runner pool can declare required-without-default fields (e.g. an
+// API token); until they're set, the provider can't run, so we surface it with a direct
+// link into its connect panel. Dismissible per session.
+import { computed, ref, watch } from 'vue'
+import type { ProviderConnectionKind } from '~/types/providerConnections'
+
+const ui = useUiStore()
+const workspace = useWorkspaceStore()
+const store = useProviderConnectionsStore()
+
+const LABEL: Record<ProviderConnectionKind, string> = {
+  environment: 'Environment provider',
+  'runner-pool': 'Runner pool',
+}
+
+// Probe both providers once the workspace is ready (the descriptor view is secret-less).
+watch(
+  () => workspace.ready,
+  (ready) => {
+    if (ready) void store.ensureLoaded().catch(() => {})
+  },
+  { immediate: true },
+)
+
+const dismissed = ref(false)
+const pending = computed(() => store.needingConfig as ProviderConnectionKind[])
+const show = computed(() => pending.value.length > 0 && !dismissed.value)
+</script>
+
+<template>
+  <Transition name="fade">
+    <div v-if="show" class="absolute inset-x-0 top-0 z-40 flex justify-center px-4 pt-4">
+      <div
+        class="w-full max-w-3xl rounded-2xl border-2 border-amber-500/70 bg-amber-950/95 p-5 shadow-2xl backdrop-blur"
+        role="alert"
+      >
+        <div class="flex items-start gap-4">
+          <UIcon name="i-lucide-plug" class="mt-0.5 h-9 w-9 shrink-0 text-amber-400" />
+          <div class="min-w-0 flex-1">
+            <div class="flex items-start justify-between gap-3">
+              <h2 class="text-lg font-semibold text-amber-100">
+                {{ pending.length > 1 ? 'Providers need configuration' : `${LABEL[pending[0]!]} needs configuration` }}
+              </h2>
+              <UButton
+                color="neutral"
+                variant="ghost"
+                size="xs"
+                icon="i-lucide-x"
+                aria-label="Dismiss"
+                @click="dismissed = true"
+              />
+            </div>
+            <p class="mt-1 text-sm text-amber-200/90">
+              A provider is wired for this instance but is missing required settings, so it can't
+              run yet. Add the mandatory fields to finish connecting it.
+            </p>
+            <div class="mt-4 flex flex-wrap gap-2">
+              <UButton
+                v-for="k in pending"
+                :key="k"
+                color="warning"
+                variant="solid"
+                icon="i-lucide-settings"
+                @click="ui.openProviderConnection(k)"
+              >
+                Configure {{ LABEL[k].toLowerCase() }}
+              </UButton>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </Transition>
+</template>
+
+<style scoped>
+.fade-enter-active,
+.fade-leave-active {
+  transition: opacity 0.2s ease;
+}
+.fade-enter-from,
+.fade-leave-to {
+  opacity: 0;
+}
+</style>

package/app/components/settings/ProviderConnectionPanel.vue

@@ -0,0 +1,315 @@
+<script setup lang="ts">
+// The generic connect form for the two infrastructure providers — the ephemeral-environment
+// provider and the self-hosted runner pool. Both self-describe via a ProviderDescriptor
+// (fields + defaults + the missingRequired keys still owed); this renders them without
+// hard-coding either. A NATIVE provider also ships a `manifestTemplate`, so the flat fields
+// are overlaid back onto a full manifest before saving (the single manifest storage path —
+// see backend/docs/native-environment-adapter.md): a `secret` field → the write-only secret
+// bundle, a non-secret field → providerConfig[key], a `baseUrl` field → baseUrl. A field
+// with a `default` is optional — left blank it falls back to that default.
+import { computed, ref, watch } from 'vue'
+import type { ProviderConnectionKind } from '~/types/providerConnections'
+
+const ui = useUiStore()
+const store = useProviderConnectionsStore()
+const toast = useToast()
+
+const META: Record<ProviderConnectionKind, { title: string; icon: string; blurb: string }> = {
+  environment: {
+    title: 'Ephemeral environment provider',
+    icon: 'i-lucide-cloud',
+    blurb:
+      'Where the Tester agent runs against a live preview environment. Configure the per-workspace settings and credentials your provider needs.',
+  },
+  'runner-pool': {
+    title: 'Self-hosted runner pool',
+    icon: 'i-lucide-server-cog',
+    blurb:
+      'Where the coding agents run when not using Cloudflare Containers. Configure the pool scheduler endpoint and credentials.',
+  },
+}
+
+const kind = computed<ProviderConnectionKind | null>(() => ui.providerConnectionKind)
+const open = computed({
+  get: () => kind.value !== null,
+  set: (v: boolean) => {
+    if (!v) ui.closeProviderConnection()
+  },
+})
+
+const meta = computed(() => (kind.value ? META[kind.value] : null))
+const descriptor = computed(() => (kind.value ? store.descriptorFor(kind.value) : null))
+const connection = computed(() => (kind.value ? store.connectionFor(kind.value) : null))
+
+// Per-field draft values, keyed by field key (blank ⇒ fall back to default/stored value).
+const values = ref<Record<string, string>>({})
+const testResult = ref<{ ok: boolean; message?: string } | null>(null)
+const testing = ref(false)
+const busy = ref(false)
+
+// Seed the draft from the saved manifest so an edit starts from the CURRENT non-secret config
+// (baseUrl + providerConfig) rather than blanks — re-saving then re-sends it instead of
+// dropping it. Secret fields are never prefilled (write-only); they must be re-entered to save.
+function resetDraft() {
+  testResult.value = null
+  const saved = descriptor.value?.savedManifest
+  const cfg = (saved?.providerConfig as Record<string, unknown> | undefined) ?? {}
+  const next: Record<string, string> = {}
+  for (const f of descriptor.value?.configFields ?? []) {
+    if (f.secret) continue
+    if (f.key === 'baseUrl') {
+      const b = saved?.baseUrl ?? connection.value?.baseUrl
+      if (typeof b === 'string') next[f.key] = b
+    } else if (typeof cfg[f.key] === 'string') {
+      next[f.key] = cfg[f.key] as string
+    }
+  }
+  values.value = next
+}
+
+watch(
+  kind,
+  (k) => {
+    if (k) void store.loadKind(k).then(resetDraft)
+  },
+  { immediate: true },
+)
+
+/** A native provider ships a manifest scaffold ⇒ we can author/register the full manifest. */
+const canAuthor = computed(() => !!descriptor.value?.manifestTemplate)
+const secretFieldCount = computed(
+  () => (descriptor.value?.configFields ?? []).filter((f) => f.secret).length,
+)
+const hasSecretFields = computed(() => secretFieldCount.value > 0)
+/** Already-configured manifest provider: we can still rotate its secrets. */
+const canRotateSecrets = computed(() => !canAuthor.value && !!connection.value)
+
+/** A field is satisfied when filled now, or already stored, or it has a default. */
+function satisfied(key: string): boolean {
+  const f = descriptor.value?.configFields.find((cf) => cf.key === key)
+  if (!f) return true
+  if ((values.value[key] ?? '').trim()) return true
+  if (f.default !== undefined) return true
+  return !(descriptor.value?.missingRequired ?? []).includes(key)
+}
+
+/** Save is allowed once every required-without-default key is supplied. */
+const canSave = computed(() => {
+  if (!descriptor.value) return false
+  if (!canAuthor.value && !canRotateSecrets.value) return false
+  return (descriptor.value.missingRequired ?? []).every(satisfied)
+})
+
+/**
+ * Overlay the flat field values onto the provider's manifest. We base the overlay on the
+ * CURRENT saved manifest when one exists (so previously-stored providerConfig — including
+ * nested values the flat form doesn't render — survives a re-save), falling back to the bare
+ * `manifestTemplate` scaffold on a first connect. Native providers only (a manifest provider
+ * has no template ⇒ null, and rotates secrets via the dedicated path instead).
+ */
+function buildManifestPayload(): { manifest: Record<string, unknown>; secrets: Record<string, string> } | null {
+  const template = descriptor.value?.manifestTemplate
+  if (!template) return null
+  const base = descriptor.value?.savedManifest ?? template
+  const manifest: Record<string, unknown> = structuredClone(base)
+  const providerConfig: Record<string, unknown> = {
+    ...((manifest.providerConfig as Record<string, unknown> | undefined) ?? {}),
+  }
+  const secrets: Record<string, string> = {}
+  for (const f of descriptor.value?.configFields ?? []) {
+    const val = (values.value[f.key] ?? '').trim()
+    if (!val) continue // omit ⇒ falls back to the scaffold default
+    if (f.secret) secrets[f.key] = val
+    else if (f.key === 'baseUrl') manifest.baseUrl = val
+    else providerConfig[f.key] = val
+  }
+  if (Object.keys(providerConfig).length) manifest.providerConfig = providerConfig
+  return { manifest, secrets }
+}
+
+/** Just the secret-field values (for rotating an authored manifest provider's secrets). */
+function buildSecretsOnly(): Record<string, string> {
+  const secrets: Record<string, string> = {}
+  for (const f of descriptor.value?.configFields ?? []) {
+    if (!f.secret) continue
+    const val = (values.value[f.key] ?? '').trim()
+    if (val) secrets[f.key] = val
+  }
+  return secrets
+}
+
+function notifyError(title: string, e: unknown) {
+  toast.add({
+    title,
+    description: e instanceof Error ? e.message : String(e),
+    icon: 'i-lucide-triangle-alert',
+    color: 'error',
+  })
+}
+
+async function test() {
+  if (!kind.value) return
+  const payload = buildManifestPayload()
+  testing.value = true
+  testResult.value = null
+  try {
+    testResult.value = await store.test(kind.value, payload ?? { secrets: buildSecretsOnly() })
+  } catch (e) {
+    testResult.value = { ok: false, message: e instanceof Error ? e.message : String(e) }
+  } finally {
+    testing.value = false
+  }
+}
+
+async function save() {
+  if (!kind.value) return
+  busy.value = true
+  try {
+    if (canAuthor.value) {
+      const payload = buildManifestPayload()
+      if (payload) await store.register(kind.value, payload)
+    } else {
+      await store.updateSecrets(kind.value, buildSecretsOnly())
+    }
+    resetDraft()
+    toast.add({ title: `${meta.value?.title} saved`, icon: 'i-lucide-check', color: 'success' })
+  } catch (e) {
+    notifyError('Could not save the connection', e)
+  } finally {
+    busy.value = false
+  }
+}
+
+async function remove() {
+  if (!kind.value) return
+  busy.value = true
+  try {
+    await store.remove(kind.value)
+    resetDraft()
+    toast.add({ title: 'Connection removed', icon: 'i-lucide-check' })
+  } catch (e) {
+    notifyError('Could not remove the connection', e)
+  } finally {
+    busy.value = false
+  }
+}
+
+/** The helper line under a field — its own help, plus the "defaulted to …" hint. */
+function fieldHelp(key: string): string | undefined {
+  const f = descriptor.value?.configFields.find((cf) => cf.key === key)
+  if (!f) return undefined
+  const filled = (values.value[key] ?? '').trim()
+  if (f.default !== undefined && !filled) {
+    return f.help ? `${f.help} · Defaults to ${f.default}` : `Defaults to ${f.default}`
+  }
+  return f.help
+}
+</script>
+
+<template>
+  <UModal v-model:open="open" :title="meta?.title ?? 'Provider'" :ui="{ content: 'max-w-xl' }">
+    <template #body>
+      <div v-if="descriptor" class="space-y-4">
+        <p class="text-xs text-slate-400">{{ meta?.blurb }}</p>
+
+        <!-- Saved connection summary -->
+        <div
+          v-if="connection"
+          class="flex items-center justify-between rounded-md border border-slate-700 bg-slate-900/50 px-3 py-2 text-sm"
+        >
+          <div>
+            <span class="font-medium text-slate-200">{{ connection.label }}</span>
+            <div class="text-[11px] text-emerald-400">Connected · {{ connection.baseUrl }}</div>
+          </div>
+          <UButton
+            icon="i-lucide-trash-2"
+            color="error"
+            variant="ghost"
+            size="xs"
+            :disabled="busy"
+            @click="remove()"
+          />
+        </div>
+
+        <!-- Mandatory-fields warning (mirrors the banner) -->
+        <div
+          v-if="descriptor.missingRequired.length"
+          class="rounded-md border border-amber-500/40 bg-amber-950/40 px-3 py-2 text-xs text-amber-200"
+        >
+          Missing required config: {{ descriptor.missingRequired.join(', ') }}
+        </div>
+
+        <!-- Generic, descriptor-driven field form -->
+        <div
+          v-if="canAuthor || canRotateSecrets"
+          class="rounded-lg border border-dashed border-slate-700 p-3 space-y-3"
+        >
+          <p class="text-[11px] font-semibold uppercase tracking-wide text-slate-400">
+            {{ connection ? 'Update configuration' : 'Connect' }}
+          </p>
+          <!-- A native re-register replaces the whole manifest; secrets are write-only so they
+               must be re-supplied. Non-secret config is prefilled, so it survives a save. -->
+          <p v-if="connection && canAuthor && hasSecretFields" class="text-[11px] text-amber-300/80">
+            Re-enter the secret field{{ secretFieldCount > 1 ? 's' : '' }} to save changes — stored
+            secrets are write-only and aren't shown.
+          </p>
+
+          <UFormField
+            v-for="field in descriptor.configFields"
+            :key="field.key"
+            :label="field.label + (field.required && field.default === undefined ? '' : ' (optional)')"
+            :help="fieldHelp(field.key)"
+          >
+            <USelect
+              v-if="field.type === 'select'"
+              v-model="values[field.key]"
+              :items="(field.options ?? []).map((o) => ({ label: o.label, value: o.value }))"
+              :placeholder="field.default ?? field.placeholder"
+            />
+            <UInput
+              v-else
+              v-model="values[field.key]"
+              :type="field.secret ? 'password' : 'text'"
+              class="font-mono"
+              :placeholder="field.default ?? field.placeholder"
+            />
+          </UFormField>
+
+          <div v-if="descriptor.supportsTest" class="flex items-center gap-2">
+            <UButton
+              color="neutral"
+              variant="soft"
+              size="sm"
+              icon="i-lucide-plug-zap"
+              :loading="testing"
+              @click="test()"
+            >
+              Test connection
+            </UButton>
+            <span v-if="testResult && testResult.ok" class="text-xs text-emerald-400">
+              {{ testResult.message ?? 'Connection OK' }}
+            </span>
+            <span v-else-if="testResult" class="text-xs text-rose-400">
+              {{ testResult.message ?? 'Connection failed' }}
+            </span>
+          </div>
+
+          <div class="flex justify-end">
+            <UButton color="primary" size="sm" :loading="busy" :disabled="!canSave" @click="save()">
+              {{ connection ? 'Save' : 'Connect' }}
+            </UButton>
+          </div>
+        </div>
+
+        <!-- Manifest provider with nothing to overlay onto: needs the manifest editor -->
+        <div
+          v-else
+          class="rounded-md border border-slate-700 bg-slate-900/40 px-3 py-3 text-xs text-slate-400"
+        >
+          This provider is configured by authoring a manifest. The in-app manifest editor isn't
+          available yet — register it via the API for now.
+        </div>
+      </div>
+    </template>
+  </UModal>
+</template>

package/app/composables/api/fragments.ts

@@ -1,4 +1,5 @@
 import type {
+  CreateDocumentFragmentInput,
   CreatePromptFragmentInput,
   FragmentOwnerKind,
   FragmentSource,
@@ -45,6 +46,20 @@ export function fragmentsApi({ http, ws, scope }: ApiContext) {
         method: 'DELETE',
       }),
 
+    // Link an external document (Confluence/Notion/GitHub) as a living fragment.
+    createDocumentFragment: (
+      kind: FragmentOwnerKind,
+      id: string,
+      body: CreateDocumentFragmentInput,
+    ) => http<PromptFragment>(`${scope(kind, id)}/document-fragments`, { method: 'POST', body }),
+
+    // Force an immediate live re-resolve of a document-backed fragment.
+    refreshFragment: (kind: FragmentOwnerKind, id: string, fragmentId: string) =>
+      http<PromptFragment>(
+        `${scope(kind, id)}/prompt-fragments/${encodeURIComponent(fragmentId)}/refresh`,
+        { method: 'POST' },
+      ),
+
     // Repo sources of guideline Markdown.
     listFragmentSources: (kind: FragmentOwnerKind, id: string) =>
       http<FragmentSource[]>(`${scope(kind, id)}/fragment-sources`),

package/app/composables/api/providerConnections.ts

@@ -0,0 +1,61 @@
+import type {
+  ConnectionTestResult,
+  ProviderConnection,
+  ProviderConnectionKind,
+  ProviderDescriptor,
+  RegisterProviderInput,
+  TestProviderInput,
+} from '~/types/providerConnections'
+import type { ApiContext } from './context'
+
+// The two infrastructure providers share an identical REST surface, differing only in the
+// path segment (`environments` vs `runner-pool`). One factory serves both so a single
+// generic store + connect form drives either.
+const SEGMENT: Record<ProviderConnectionKind, string> = {
+  environment: 'environments',
+  'runner-pool': 'runner-pool',
+}
+
+/** Environment-provider + runner-pool connection endpoints (self-describe + register/test). */
+export function providerConnectionsApi({ http, ws }: ApiContext) {
+  const base = (workspaceId: string, kind: ProviderConnectionKind) =>
+    `${ws(workspaceId)}/${SEGMENT[kind]}`
+
+  return {
+    describeProvider: (workspaceId: string, kind: ProviderConnectionKind) =>
+      http<ProviderDescriptor>(`${base(workspaceId, kind)}/provider`),
+
+    getProviderConnection: (workspaceId: string, kind: ProviderConnectionKind) =>
+      http<{ connection: ProviderConnection | null }>(`${base(workspaceId, kind)}/connection`),
+
+    registerProviderConnection: (
+      workspaceId: string,
+      kind: ProviderConnectionKind,
+      body: RegisterProviderInput,
+    ) =>
+      http<ProviderConnection>(`${base(workspaceId, kind)}/connection`, { method: 'POST', body }),
+
+    updateProviderSecrets: (
+      workspaceId: string,
+      kind: ProviderConnectionKind,
+      secrets: Record<string, string>,
+    ) =>
+      http<ProviderConnection>(`${base(workspaceId, kind)}/connection/secrets`, {
+        method: 'PUT',
+        body: { secrets },
+      }),
+
+    testProviderConnection: (
+      workspaceId: string,
+      kind: ProviderConnectionKind,
+      body: TestProviderInput,
+    ) =>
+      http<ConnectionTestResult>(`${base(workspaceId, kind)}/connection/test`, {
+        method: 'POST',
+        body,
+      }),
+
+    deleteProviderConnection: (workspaceId: string, kind: ProviderConnectionKind) =>
+      http(`${base(workspaceId, kind)}/connection`, { method: 'DELETE' }),
+  }
+}

package/app/composables/useApi.ts

@@ -12,6 +12,7 @@ import { humanTestApi } from './api/humanTest'
 import { modelsApi } from './api/models'
 import { notificationsApi } from './api/notifications'
 import { presetsApi } from './api/presets'
+import { providerConnectionsApi } from './api/providerConnections'
 import { recurringApi } from './api/recurring'
 import { releaseHealthApi } from './api/releaseHealth'
 import { reviewsApi } from './api/reviews'
@@ -85,6 +86,7 @@ export function useApi() {
     ...specApi(ctx),
     ...notificationsApi(ctx),
     ...presetsApi(ctx),
+    ...providerConnectionsApi(ctx),
     ...releaseHealthApi(ctx),
     ...recurringApi(ctx),
     ...githubApi(ctx),

package/app/pages/index.vue

@@ -29,6 +29,8 @@ import CommandBar from '~/components/layout/CommandBar.vue'
 import IntegrationsHub from '~/components/layout/IntegrationsHub.vue'
 import WorkspaceSettingsPanel from '~/components/settings/WorkspaceSettingsPanel.vue'
 import ObservabilityConnectionPanel from '~/components/settings/ObservabilityConnectionPanel.vue'
+import ProviderConnectionPanel from '~/components/settings/ProviderConnectionPanel.vue'
+import ProviderConfigBanner from '~/components/layout/ProviderConfigBanner.vue'
 import ModelConfigurationPanel from '~/components/settings/ModelConfigurationPanel.vue'
 import LocalModelEndpointsPanel from '~/components/settings/LocalModelEndpointsPanel.vue'
 import UserSecretsSection from '~/components/settings/UserSecretsSection.vue'
@@ -138,6 +140,8 @@ watch(
     <GitHubPatBanner />
     <!-- AI-readiness prompt (no usable model source, or default preset uses unavailable models). -->
     <AiProvidersBanner v-if="workspace.ready && !needsGitHubInstall && !githubProbePending" />
+    <!-- Infrastructure provider prompt (env/runner-pool wired but missing mandatory config). -->
+    <ProviderConfigBanner v-if="workspace.ready && !needsGitHubInstall && !githubProbePending" />
 
     <!-- Resolving whether the GitHub App is installed, before we decide what to show. -->
     <div
@@ -182,6 +186,7 @@ watch(
       <IntegrationsHub />
       <WorkspaceSettingsPanel />
       <ObservabilityConnectionPanel />
+      <ProviderConnectionPanel />
       <ModelConfigurationPanel />
       <LocalModelEndpointsPanel />
       <UserSecretsSection />

package/app/stores/fragmentLibrary.ts

@@ -1,6 +1,7 @@
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
 import type {
+  CreateDocumentFragmentInput,
   CreatePromptFragmentInput,
   FragmentSource,
   LinkFragmentSourceInput,
@@ -77,6 +78,28 @@ export const useFragmentLibraryStore = defineStore('fragmentLibrary', () => {
     await Promise.all([reloadTier(), refreshResolved()])
   }
 
+  /** Link an external document as a living (dynamically-resolved) fragment. */
+  async function createDocumentFragment(input: CreateDocumentFragmentInput) {
+    loading.value = true
+    try {
+      await api.createDocumentFragment('workspace', workspace.requireId(), input)
+      await Promise.all([reloadTier(), refreshResolved()])
+    } finally {
+      loading.value = false
+    }
+  }
+
+  /** Force an immediate live re-resolve of a document-backed fragment. */
+  async function refreshDocumentFragment(fragmentId: string) {
+    loading.value = true
+    try {
+      await api.refreshFragment('workspace', workspace.requireId(), fragmentId)
+      await Promise.all([reloadTier(), refreshResolved()])
+    } finally {
+      loading.value = false
+    }
+  }
+
   /** Tombstone a fragment at the workspace tier (suppresses an inherited one). */
   async function remove(fragmentId: string) {
     await api.deleteFragment('workspace', workspace.requireId(), fragmentId)
@@ -137,6 +160,8 @@ export const useFragmentLibraryStore = defineStore('fragmentLibrary', () => {
     probe,
     refreshResolved,
     create,
+    createDocumentFragment,
+    refreshDocumentFragment,
     update,
     remove,
     linkSource,

package/app/stores/providerConnections.ts

@@ -0,0 +1,136 @@
+import { defineStore } from 'pinia'
+import { computed, reactive, ref } from 'vue'
+import type {
+  ProviderConnection,
+  ProviderConnectionKind,
+  ProviderDescriptor,
+  RegisterProviderInput,
+  TestProviderInput,
+} from '~/types/providerConnections'
+import { useWorkspaceStore } from '~/stores/workspace'
+
+const KINDS: ProviderConnectionKind[] = ['environment', 'runner-pool']
+
+interface ProviderState {
+  /** null until first probed; false ⇒ integration disabled on the backend (hide it). */
+  available: boolean | null
+  descriptor: ProviderDescriptor | null
+  connection: ProviderConnection | null
+}
+
+function emptyState(): ProviderState {
+  return { available: null, descriptor: null, connection: null }
+}
+
+/**
+ * The two infrastructure providers configured through the generic connect form — the
+ * ephemeral-environment provider and the self-hosted runner pool. Each exposes a
+ * self-describing `ProviderDescriptor` (fields + defaults + the `missingRequired` keys the
+ * org still has to supply) plus the saved connection metadata (never secret values). Loaded
+ * on demand: the banner probes both eagerly so it can warn when a provider is wired for the
+ * instance but mandatory fields are missing; the panel re-loads its own kind on open.
+ */
+export const useProviderConnectionsStore = defineStore('providerConnections', () => {
+  const api = useApi()
+  const state = reactive<Record<ProviderConnectionKind, ProviderState>>({
+    environment: emptyState(),
+    'runner-pool': emptyState(),
+  })
+  const loaded = ref(false)
+  let inFlight: Promise<void> | null = null
+
+  async function loadKind(kind: ProviderConnectionKind) {
+    const ws = useWorkspaceStore()
+    const s = state[kind]
+    try {
+      const [descriptor, { connection }] = await Promise.all([
+        api.describeProvider(ws.requireId(), kind),
+        api.getProviderConnection(ws.requireId(), kind),
+      ])
+      s.descriptor = descriptor
+      s.connection = connection
+      s.available = true
+    } catch {
+      // 503 (integration disabled) or any error → hide this provider's UI entry points.
+      s.available = false
+      s.descriptor = null
+      s.connection = null
+    }
+  }
+
+  /** Refresh both providers (used by the banner + after a save/remove). */
+  async function load() {
+    await Promise.all(KINDS.map(loadKind))
+    loaded.value = true
+  }
+
+  /** Load once and share the result (coalescing concurrent callers). */
+  async function ensureLoaded() {
+    if (loaded.value) return
+    if (!inFlight) inFlight = load().finally(() => (inFlight = null))
+    return inFlight
+  }
+
+  function descriptorFor(kind: ProviderConnectionKind): ProviderDescriptor | null {
+    return state[kind].descriptor
+  }
+  function connectionFor(kind: ProviderConnectionKind): ProviderConnection | null {
+    return state[kind].connection
+  }
+  function isAvailable(kind: ProviderConnectionKind): boolean {
+    return state[kind].available === true
+  }
+
+  /**
+   * Providers that are wired for this instance but still missing mandatory config —
+   * exactly what the loud banner surfaces. A provider with no config fields at all (a
+   * stock manifest provider with nothing authored yet) is NOT flagged: there is nothing
+   * to nag about until someone introduces a provider that declares required fields.
+   */
+  const needingConfig = computed<ProviderConnectionKind[]>(() =>
+    KINDS.filter((kind) => {
+      const d = state[kind].descriptor
+      return state[kind].available === true && !!d && d.missingRequired.length > 0
+    }),
+  )
+
+  async function register(kind: ProviderConnectionKind, input: RegisterProviderInput) {
+    const ws = useWorkspaceStore()
+    state[kind].connection = await api.registerProviderConnection(ws.requireId(), kind, input)
+    await loadKind(kind) // refresh missingRequired/descriptor after the change
+  }
+
+  async function updateSecrets(kind: ProviderConnectionKind, secrets: Record<string, string>) {
+    const ws = useWorkspaceStore()
+    state[kind].connection = await api.updateProviderSecrets(ws.requireId(), kind, secrets)
+    await loadKind(kind)
+  }
+
+  async function test(kind: ProviderConnectionKind, input: TestProviderInput) {
+    const ws = useWorkspaceStore()
+    return api.testProviderConnection(ws.requireId(), kind, input)
+  }
+
+  async function remove(kind: ProviderConnectionKind) {
+    const ws = useWorkspaceStore()
+    await api.deleteProviderConnection(ws.requireId(), kind)
+    state[kind].connection = null
+    await loadKind(kind)
+  }
+
+  return {
+    state,
+    loaded,
+    load,
+    loadKind,
+    ensureLoaded,
+    descriptorFor,
+    connectionFor,
+    isAvailable,
+    needingConfig,
+    register,
+    updateSecrets,
+    test,
+    remove,
+  }
+})

package/app/stores/ui.ts

@@ -96,6 +96,9 @@ export const useUiStore = defineStore('ui', () => {
   // today, pluggable). NB: distinct from `observabilityInstanceId` below, which is the
   // LLM per-call observability panel.
   const observabilityConnectionOpen = ref(false)
+  // Infrastructure provider connect panels (ephemeral-environment provider + self-hosted
+  // runner pool). One panel renders whichever kind is open; null ⇒ closed.
+  const providerConnectionKind = ref<'environment' | 'runner-pool' | null>(null)
   const modelConfigOpen = ref(false)
   // LLM-vendor subscription credentials (the token pool powering the Claude Code
   // / Codex harnesses).
@@ -341,6 +344,12 @@ export const useUiStore = defineStore('ui', () => {
   function closeObservabilityConnection() {
     observabilityConnectionOpen.value = false
   }
+  function openProviderConnection(kind: 'environment' | 'runner-pool') {
+    providerConnectionKind.value = kind
+  }
+  function closeProviderConnection() {
+    providerConnectionKind.value = null
+  }
   function openModelConfig() {
     modelConfigOpen.value = true
   }
@@ -455,6 +464,7 @@ export const useUiStore = defineStore('ui', () => {
     workspaceSettingsOpen,
     workspaceSettingsTab,
     observabilityConnectionOpen,
+    providerConnectionKind,
     modelConfigOpen,
     vendorCredentialsOpen,
     localModelsOpen,
@@ -514,6 +524,8 @@ export const useUiStore = defineStore('ui', () => {
     setWorkspaceSettingsTab,
     openObservabilityConnection,
     closeObservabilityConnection,
+    openProviderConnection,
+    closeProviderConnection,
     openModelConfig,
     closeModelConfig,
     openVendorCredentials,

package/app/types/fragments.ts

@@ -5,6 +5,7 @@
 // ---------------------------------------------------------------------------
 
 import type { AgentKind, BlockType } from './domain'
+import type { DocumentSourceKind } from './documents'
 import type { PromptFragment } from './models'
 
 /** Which scope owns a managed fragment / source. */
@@ -28,6 +29,21 @@ export interface CreatePromptFragmentInput {
 /** Partial patch for editing a fragment at a tier. */
 export type UpdatePromptFragmentInput = Partial<CreatePromptFragmentInput>
 
+/**
+ * Inputs for linking an external document (Confluence/Notion page or GitHub file)
+ * as a LIVING fragment at a tier. Title/summary/body are derived from the fetched
+ * document, not supplied here. `viaWorkspaceId` is only needed at the account tier.
+ */
+export interface CreateDocumentFragmentInput {
+  source: DocumentSourceKind
+  ref: string
+  id?: string
+  category?: string
+  tags?: string[]
+  appliesTo?: { blockTypes?: BlockType[]; agentKinds?: AgentKind[] }
+  viaWorkspaceId?: string
+}
+
 /** A fragment after the three tiers are merged for a workspace. */
 export interface ResolvedFragment extends PromptFragment {
   tier: FragmentTier

package/app/types/models.ts

@@ -4,6 +4,7 @@
 // ---------------------------------------------------------------------------
 
 import type { AgentKind, BlockType } from './domain'
+import type { DocumentSourceKind } from './documents'
 
 /** Subscription vendors whose pooled tokens drive the Claude Code / Codex harnesses. */
 export type SubscriptionVendor = 'claude' | 'codex' | 'glm' | 'kimi' | 'deepseek'
@@ -154,4 +155,14 @@ export interface PromptFragment {
     path: string
     sha: string
   }
+  /**
+   * Provenance when the body is a LIVING external document (Confluence/Notion/
+   * GitHub). The body is re-resolved from the source at run time, not frozen.
+   */
+  documentRef?: {
+    source: DocumentSourceKind
+    externalId: string
+  }
+  /** When the document-backed body was last resolved from the source (epoch ms). */
+  resolvedAt?: number
 }

package/app/types/providerConnections.ts

@@ -0,0 +1,67 @@
+// Frontend mirrors of the shared provider self-description + connection wire contracts
+// (`@cat-factory/contracts` provider-config.ts + environments.ts + runners.ts), used by
+// the generic connect form for the two infrastructure providers: the ephemeral-environment
+// provider and the self-hosted runner pool. Both speak the same ProviderDescriptor.
+
+/** The two infrastructure providers configured through the generic connect form. */
+export type ProviderConnectionKind = 'environment' | 'runner-pool'
+
+/** One config value a provider needs, rendered as a single form field. */
+export interface ProviderConfigField {
+  key: string
+  label: string
+  help?: string
+  placeholder?: string
+  secret?: boolean
+  required?: boolean
+  type?: 'text' | 'password' | 'select'
+  options?: { value: string; label: string }[]
+  /** The provider/manifest default; a field with one is optional (UI shows a hint). */
+  default?: string
+}
+
+/** What the SPA needs to render a provider's connect form. */
+export interface ProviderDescriptor {
+  providerId: string
+  label: string
+  kind: 'native' | 'manifest'
+  configFields: ProviderConfigField[]
+  supportsTest: boolean
+  /** Required-without-default keys not yet supplied (drives the banner). */
+  missingRequired: string[]
+  /** Base manifest a native provider's flat fields are overlaid onto before save. */
+  manifestTemplate?: Record<string, unknown>
+  /**
+   * The CURRENT saved manifest (non-secret — only secret-ref key names), present once a
+   * connection exists. Edits are overlaid onto this (not the bare `manifestTemplate`) so
+   * re-saving preserves previously-stored providerConfig instead of dropping it.
+   */
+  savedManifest?: Record<string, unknown>
+}
+
+/** A workspace's provider binding, as exposed to clients (never secret values). */
+export interface ProviderConnection {
+  providerId: string
+  label: string
+  baseUrl: string
+  connectedAt: number
+  /** Which secret/config keys are stored (names only), so the UI shows completeness. */
+  secretKeys: string[]
+}
+
+export interface ConnectionTestResult {
+  ok: boolean
+  message?: string
+}
+
+/** The assembled register payload (a full manifest + the write-only secret bundle). */
+export interface RegisterProviderInput {
+  manifest: Record<string, unknown>
+  secrets: Record<string, string>
+}
+
+export interface TestProviderInput {
+  manifest?: Record<string, unknown>
+  config?: Record<string, string>
+  secrets?: Record<string, string>
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",