@cat-factory/app 0.317.2 → 0.319.0

package/app/components/settings/ApiTokensPanel.vue

@@ -43,23 +43,66 @@ const store = usePublicApiKeysStore()
 const accounts = useAccountsStore()
 const workspace = useWorkspaceStore()
 
-// A key's reach. The default is this board alone. The wider choices are an account admin's to
-// make, so the field is shown to everyone in both UI modes and disabled for anyone else, with the
-// reason, because a directory webhook needs a key that reaches every workspace.
-type TokenReach = 'this' | 'all' | 'selected'
+// WHO the next key runs as. Two named options rather than an unchecked box, because they are two
+// different credentials with two different blast radii and neither is a mere setting on the other:
+//
+//  - `system` (the default): the token belongs to the workspace. Its runs are attributed to nobody
+//    and it can reach no personal subscription, so a leaked shared credential can never spend one
+//    person's Claude quota. This is what a CI job or a shared integration should hold.
+//  - `self`: the token belongs to the person minting it. Its runs are theirs and may unlock their
+//    personal Claude / Codex / GLM subscription, with the password sent on each such call.
+//
+// NOT gated on the interface mode, unlike an override field. This whole panel is the Integrations
+// hub's Development surface, reached only by someone already minting an API key, and `scope` next
+// to it is ungated for the same reason. Hiding it in basic mode would leave that person a key that
+// silently cannot run their own models, with nothing on screen to say why.
+type TokenIdentity = 'system' | 'self'
+const identity = ref<TokenIdentity>('system')
+// Nobody to bind on a board with no signed-in user (a dev-open deployment): the server refuses
+// such a mint outright, so the choice is withheld and every key is a system key, which is what
+// that deployment can honestly offer.
+const canBindSelf = computed(() => auth.user !== null && auth.user !== undefined)
+const identityItems = computed(() => [
+  { value: 'system' as const, label: t('settings.apiTokens.add.identitySystem') },
+  { value: 'self' as const, label: t('settings.apiTokens.add.identitySelf') },
+])
+
+// A key's reach. The default is this board alone. 'all' and 'selected' are an account admin's to
+// make, because a directory webhook needs a key that reaches every workspace. 'memberships' is
+// anyone's for a key that runs as them: it reaches whatever they can act in, call by call, and
+// never more than their role allows in each, so it is the default for such a key.
+type TokenReach = 'this' | 'all' | 'selected' | 'memberships'
 const reach = ref<TokenReach>('this')
 const selectedWorkspaceIds = ref<string[]>([])
 const canWidenReach = computed(() => accounts.activeAccount?.roles?.includes('admin') === true)
 const reachItems = computed(() => [
   { value: 'this' as const, label: t('settings.apiTokens.add.reachThis') },
-  { value: 'all' as const, label: t('settings.apiTokens.add.reachAll') },
-  { value: 'selected' as const, label: t('settings.apiTokens.add.reachSelected') },
+  ...(identity.value === 'self'
+    ? [{ value: 'memberships' as const, label: t('settings.apiTokens.add.reachMemberships') }]
+    : []),
+  {
+    value: 'all' as const,
+    label: t('settings.apiTokens.add.reachAll'),
+    disabled: !canWidenReach.value,
+  },
+  {
+    value: 'selected' as const,
+    label: t('settings.apiTokens.add.reachSelected'),
+    disabled: !canWidenReach.value,
+  },
 ])
+const reachHelp = computed(() => {
+  if (reach.value === 'memberships') return t('settings.apiTokens.add.reachMembershipsHelp')
+  return canWidenReach.value
+    ? t('settings.apiTokens.add.reachHelp')
+    : t('settings.apiTokens.add.reachAdminOnly')
+})
 const workspaceItems = computed(() =>
   workspace.accountWorkspaces.map((w) => ({ value: w.id, label: w.name })),
 )
-/** The `workspaceIds` to mint with: omitted for this board, `null` for all, or the picked list. */
-function requestedReach(): string[] | null | undefined {
+/** The reach to mint with: omitted for this board, `null` for all, the picked list, or memberships. */
+function requestedReach(): string[] | null | 'memberships' | undefined {
+  if (reach.value === 'memberships') return identity.value === 'self' ? 'memberships' : undefined
   if (!canWidenReach.value || reach.value === 'this') return undefined
   if (reach.value === 'all') return null
   return selectedWorkspaceIds.value
@@ -73,6 +116,7 @@ const reachIncomplete = computed(
 
 /** The reach badge for a listed key; none for a key reaching this one board. */
 function reachLabel(key: PublicApiKey): string | null {
+  if (key.followsMemberships) return t('settings.apiTokens.list.reachMemberships')
   if (key.workspaceIds === null) return t('settings.apiTokens.list.reachAll')
   if (key.workspaceIds.length > 1) {
     return t('settings.apiTokens.list.reachCount', { count: key.workspaceIds.length })
@@ -130,29 +174,13 @@ const back = useIntegrationBack(open)
 const label = ref('')
 // The scope the next minted key will carry; defaults to the safe middle of the ladder.
 const scope = ref<PublicApiScope>('write')
-// WHO the next key runs as. Two named options rather than an unchecked box, because they are two
-// different credentials with two different blast radii and neither is a mere setting on the other:
-//
-//  - `system` (the default): the token belongs to the workspace. Its runs are attributed to nobody
-//    and it can reach no personal subscription, so a leaked shared credential can never spend one
-//    person's Claude quota. This is what a CI job or a shared integration should hold.
-//  - `self`: the token belongs to the person minting it. Its runs are theirs and may unlock their
-//    personal Claude / Codex / GLM subscription, with the password sent on each such call.
-//
-// NOT gated on the interface mode, unlike an override field. This whole panel is the Integrations
-// hub's Development surface, reached only by someone already minting an API key, and `scope` next
-// to it is ungated for the same reason. Hiding it in basic mode would leave that person a key that
-// silently cannot run their own models, with nothing on screen to say why.
-type TokenIdentity = 'system' | 'self'
-const identity = ref<TokenIdentity>('system')
-// Nobody to bind on a board with no signed-in user (a dev-open deployment): the server refuses
-// such a mint outright, so the choice is withheld and every key is a system key, which is what
-// that deployment can honestly offer.
-const canBindSelf = computed(() => auth.user !== null && auth.user !== undefined)
-const identityItems = computed(() => [
-  { value: 'system' as const, label: t('settings.apiTokens.add.identitySystem') },
-  { value: 'self' as const, label: t('settings.apiTokens.add.identitySelf') },
-])
+// A key that runs as its person follows their workspaces unless they pick otherwise, and one that
+// runs as nobody has no memberships to follow.
+watch(identity, (next) => {
+  if (next === 'self' && reach.value === 'this') reach.value = 'memberships'
+  if (next === 'system' && reach.value === 'memberships') reach.value = 'this'
+})
+
 /** The help text under the picker, so each option explains ITSELF rather than only its opposite. */
 const identityHelp = computed(() =>
   identity.value === 'self'
@@ -172,6 +200,7 @@ watch(
       newSecret.value = null
       return
     }
+    applyPrefill()
     try {
       await store.ensureLoaded()
     } catch (e) {
@@ -181,6 +210,17 @@ watch(
   { immediate: true },
 )
 
+/** Fill the create form from a new-API-key deep link (`useNewApiKeyDeepLink`), once. */
+function applyPrefill() {
+  const prefill = ui.apiTokensPrefill
+  if (!prefill) return
+  if (prefill.label) label.value = prefill.label
+  if (prefill.scope) scope.value = prefill.scope
+  if (prefill.runsAsSelf && canBindSelf.value) identity.value = 'self'
+  if (prefill.reach === 'memberships' && identity.value === 'self') reach.value = 'memberships'
+  ui.apiTokensPrefill = null
+}
+
 async function createToken() {
   const trimmed = label.value.trim()
   if (!trimmed) return
@@ -381,18 +421,11 @@ async function revokeToken(key: PublicApiKey) {
               data-testid="api-token-identity"
             />
           </UFormField>
-          <UFormField
-            :label="t('settings.apiTokens.add.reach')"
-            :help="
-              canWidenReach
-                ? t('settings.apiTokens.add.reachHelp')
-                : t('settings.apiTokens.add.reachAdminOnly')
-            "
-          >
+          <UFormField :label="t('settings.apiTokens.add.reach')" :help="reachHelp">
             <USelect
               v-model="reach"
               :items="reachItems"
-              :disabled="!canWidenReach"
+              :disabled="!canWidenReach && identity !== 'self'"
               class="w-full"
               data-testid="api-token-reach"
             />

package/app/composables/useNewApiKeyDeepLink.spec.ts

@@ -0,0 +1,62 @@
+import { createPinia, setActivePinia } from 'pinia'
+import { beforeEach, describe, expect, it } from 'vitest'
+import { captureNewApiKeyDeepLink } from './useNewApiKeyDeepLink'
+
+function setUrl(search: string): void {
+  history.replaceState(null, '', `/${search}`)
+}
+
+describe('captureNewApiKeyDeepLink', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    setUrl('')
+  })
+
+  it('parses the link an integration builds, and strips only its own params', () => {
+    setUrl(
+      '?newApiKey=1&label=sainte-beuve&scope=decide&runsAsSelf=1&reach=memberships&ws=ws_1&keep=yes',
+    )
+    expect(captureNewApiKeyDeepLink()).toEqual({
+      label: 'sainte-beuve',
+      scope: 'decide',
+      runsAsSelf: true,
+      reach: 'memberships',
+      workspaceId: 'ws_1',
+    })
+    expect(window.location.search).toBe('?keep=yes')
+    expect(captureNewApiKeyDeepLink()).toBeNull()
+  })
+
+  it('opens the form at its defaults when the link names nothing else', () => {
+    setUrl('?newApiKey=1')
+    expect(captureNewApiKeyDeepLink()).toEqual({
+      label: null,
+      scope: null,
+      runsAsSelf: false,
+      reach: null,
+      workspaceId: null,
+    })
+    expect(window.location.search).toBe('')
+  })
+
+  it('drops a reach this build does not know rather than guessing one', () => {
+    setUrl('?newApiKey=1&runsAsSelf=1&reach=everything')
+    expect(captureNewApiKeyDeepLink()).toMatchObject({ reach: null })
+  })
+
+  it('drops a scope this build does not know rather than guessing one', () => {
+    setUrl('?newApiKey=1&scope=superuser')
+    expect(captureNewApiKeyDeepLink()).toMatchObject({ scope: null })
+  })
+
+  it('cuts a label to what the form accepts', () => {
+    setUrl(`?newApiKey=1&label=${'x'.repeat(200)}`)
+    expect(captureNewApiKeyDeepLink()?.label).toHaveLength(120)
+  })
+
+  it('ignores a URL without the link, and leaves its query alone', () => {
+    setUrl('?label=other&scope=admin')
+    expect(captureNewApiKeyDeepLink()).toBeNull()
+    expect(window.location.search).toBe('?label=other&scope=admin')
+  })
+})

package/app/composables/useNewApiKeyDeepLink.ts

@@ -0,0 +1,102 @@
+/**
+ * Boot-time replay of a NEW API KEY deep link:
+ * `?newApiKey=1&label=<label>&scope=<scope>&runsAsSelf=1&reach=memberships&ws=<id>`.
+ *
+ * An integration that needs a person's OWN key (one bound to them, which is what lets a run use
+ * their personal model subscription) cannot mint it for them: a bound key can only be minted by
+ * its owner, signed in. It sends the person here instead, and the API tokens window opens with the
+ * create form filled in. Nothing is minted until the person clicks create.
+ *
+ * Every parameter but `newApiKey` is optional. A scope this build does not know is dropped rather
+ * than guessed at, and `runsAsSelf` only takes effect where there is a signed-in person to bind
+ * (`ApiTokensPanel` withholds the choice otherwise). Signing in first keeps the query
+ * (`postSignInUrl`). The format is published next to `?addRepo=` in the public API docs.
+ */
+import { PUBLIC_API_SCOPES } from '@cat-factory/contracts'
+import { watch } from 'vue'
+import type { PublicApiScope } from '~/types/publicApiKeys'
+import { useUiStore } from '../stores/ui'
+import { useWorkspaceStore } from '../stores/workspace'
+
+/** What the API tokens window's create form is opened with. Absent fields keep their defaults. */
+export interface NewApiKeyPrefill {
+  label: string | null
+  scope: PublicApiScope | null
+  runsAsSelf: boolean
+  /** `memberships`: reach whatever the person can act in. Only with `runsAsSelf`. */
+  reach: 'memberships' | null
+}
+
+interface PendingNewApiKeyLink extends NewApiKeyPrefill {
+  workspaceId: string | null
+}
+
+const NEW_API_KEY_LINK_PARAMS = [
+  'newApiKey',
+  'label',
+  'scope',
+  'runsAsSelf',
+  'reach',
+  'ws',
+] as const
+
+/** The form's own label limit, so a prefill never starts out invalid. */
+const LABEL_MAX_LENGTH = 120
+
+function scopeOf(value: string | null): PublicApiScope | null {
+  return (PUBLIC_API_SCOPES as readonly string[]).includes(value ?? '')
+    ? (value as PublicApiScope)
+    : null
+}
+
+/**
+ * Read (and strip) a new-API-key link from the current URL, or null when there is none. Called
+ * before `workspace.init()` so `ws` can pin the board.
+ */
+export function captureNewApiKeyDeepLink(): PendingNewApiKeyLink | null {
+  if (typeof window === 'undefined') return null
+  const params = new URLSearchParams(window.location.search)
+  if (params.get('newApiKey') !== '1') return null
+  const label = params.get('label')?.trim().slice(0, LABEL_MAX_LENGTH) || null
+  const link: PendingNewApiKeyLink = {
+    label,
+    scope: scopeOf(params.get('scope')),
+    runsAsSelf: params.get('runsAsSelf') === '1',
+    reach: params.get('reach') === 'memberships' ? 'memberships' : null,
+    workspaceId: params.get('ws'),
+  }
+  for (const key of NEW_API_KEY_LINK_PARAMS) params.delete(key)
+  const qs = params.toString()
+  history.replaceState(null, '', window.location.pathname + (qs ? `?${qs}` : ''))
+  return link
+}
+
+/** Capture a new-API-key link and, once the board has hydrated, open the window with it. */
+export function useNewApiKeyDeepLink(): void {
+  const link = captureNewApiKeyDeepLink()
+  if (!link) return
+
+  const workspace = useWorkspaceStore()
+  const ui = useUiStore()
+  if (link.workspaceId) workspace.workspaceId = link.workspaceId
+
+  // One-shot, as `useAddRepoDeepLink` is: a later refresh must not reopen a window the person
+  // closed, and `immediate` runs the callback before `stop` is bound.
+  let applied = false
+  let stop: (() => void) | undefined
+  stop = watch(
+    () => workspace.ready,
+    (ready) => {
+      if (!ready || applied) return
+      applied = true
+      ui.openApiTokens({
+        label: link.label,
+        scope: link.scope,
+        runsAsSelf: link.runsAsSelf,
+        reach: link.reach,
+      })
+      stop?.()
+    },
+    { immediate: true },
+  )
+}

package/app/modular/tutorial-tours.spec.ts

@@ -134,27 +134,6 @@ function navAnchoredSteps(): {
   )
 }
 
-/**
- * Every combination of the {@link NavGates} booleans, yielded lazily so the 2^N gate sets are
- * never all live at once.
- *
- * Enumerating rather than reasoning is deliberate. The pairing below is an IMPLICATION over
- * gate sets — anything that satisfies a tour must also render its entry — between two
- * predicates written independently in two files, and nothing about their shape is guaranteed
- * (either may be a conjunction, a disjunction, or read a field the other doesn't). The matrix
- * doubles with every field {@link NavGates} gains, so the cost is worth re-measuring rather than
- * quoting from here: at the field count this spec runs against today it is a fraction of a
- * second, a fair price for a guard that needs no assumption about how either side is spelled.
- */
-function* everyGateSet(): Generator<NavGates> {
-  const keys = Object.keys(ALL_GATES) as (keyof NavGates)[]
-  for (let mask = 0; mask < 2 ** keys.length; mask++) {
-    const gates = {} as Record<keyof NavGates, boolean>
-    for (const [bit, key] of keys.entries()) gates[key] = (mask & (1 << bit)) !== 0
-    yield gates as NavGates
-  }
-}
-
 /** The gate fields a witness has turned OFF — the interesting half of a failure message. */
 function absentGates(gates: NavGates): readonly string[] {
   return Object.entries(gates)
@@ -162,39 +141,91 @@ function absentGates(gates: NavGates): readonly string[] {
     .map(([key]) => key)
 }
 
+/** One pair's verdict over `gates`: does it offer the tour while the entry is NOT rendered? */
+function drifts(pair: ReturnType<typeof navAnchoredSteps>[number], gates: NavGates): boolean {
+  if (!(pair.tour.requires ?? []).every((requirement) => requirement.met(gates))) return false
+  if (pair.step.when && !pair.step.when(gates)) return false
+  return !navItemVisible(pair.item, gates)
+}
+
+/** Thrown by the gate proxy on the first read of a field the current branch has not assigned. */
+class UnassignedGate {
+  constructor(readonly key: keyof NavGates) {}
+}
+
 /**
- * For each pair, a gate set that OFFERS its tour while the entry its step clicks is NOT
+ * For one pair, a gate set that OFFERS its tour while the entry its step clicks is NOT
  * rendered, or `undefined` when no such set exists (what the guard wants). A step the gate set
- * DROPS (`when`) needs no anchor, so it cannot be a counterexample.
+ * DROPS (`when`) needs no anchor, so it cannot be a counterexample. Also returns the gate
+ * fields the search branched on, so the test can see that it varied something.
  *
  * Of the many counterexamples one break produces, the one reported is the SMALLEST: the gate
  * set closest to fully-permitted, so its absent fields are exactly the ones that matter. The
- * first witness the matrix happens to reach names most of `NavGates` and reads as noise, which
+ * first witness a search happens to reach names most of `NavGates` and reads as noise, which
  * is the difference between a failure that says "declare `advancedMode`" and one that says
  * "something about fourteen gates".
  *
- * The matrix is walked ONCE for every pair together: building each gate set per pair made the
- * test several times slower, enough to cross vitest's timeout on a loaded CI runner.
+ * The search branches lazily on the fields the pair's predicates read. It evaluates the pair
+ * through a proxy; the first read of a field this branch has not assigned stops the
+ * evaluation, and the search tries that field `false` and then `true`. A branch whose
+ * evaluation completes has a verdict for every gate set that agrees with its assignments, and
+ * its witness holds every unassigned field `true`, which keeps it as small as one can be. So
+ * the cost follows what one tour and one entry read, not the size of `NavGates`.
+ *
+ * This is sound only if the predicates (the tour's `requires`, the step's `when` and
+ * `navItemVisible`) are PURE and read each gate as a plain property (`g.field`). A read the
+ * proxy cannot see would let a field the verdict depends on stay held `true`, so the proxy
+ * refuses `in`, the key list and property descriptors loudly.
  */
-function navRequirementDrifts(
-  pairs: readonly ReturnType<typeof navAnchoredSteps>[number][],
-): (NavGates | undefined)[] {
-  const smallest: (NavGates | undefined)[] = pairs.map(() => undefined)
-  const fewestAbsent = pairs.map(() => Number.POSITIVE_INFINITY)
-  for (const gates of everyGateSet()) {
-    let absent: number | undefined
-    for (const [index, pair] of pairs.entries()) {
-      if (!(pair.tour.requires ?? []).every((requirement) => requirement.met(gates))) continue
-      if (pair.step.when && !pair.step.when(gates)) continue
-      if (navItemVisible(pair.item, gates)) continue
-      absent ??= absentGates(gates).length
-      if (absent < fewestAbsent[index]!) {
-        fewestAbsent[index] = absent
-        smallest[index] = gates
+function navRequirementDrift(pair: ReturnType<typeof navAnchoredSteps>[number]): {
+  witness: NavGates | undefined
+  branched: ReadonlySet<keyof NavGates>
+} {
+  const assigned: Partial<Record<keyof NavGates, boolean>> = {}
+  const branched = new Set<keyof NavGates>()
+  const refuse = (how: string) => () => {
+    throw new Error(`a nav predicate read the gates through ${how}; read each field directly`)
+  }
+  const gates = new Proxy(
+    { ...ALL_GATES },
+    {
+      get(target, key) {
+        if (typeof key !== 'string' || !Object.hasOwn(target, key)) return Reflect.get(target, key)
+        const value = assigned[key as keyof NavGates]
+        if (value === undefined) throw new UnassignedGate(key as keyof NavGates)
+        return value
+      },
+      has: refuse('`in`'),
+      ownKeys: refuse('the key list'),
+      getOwnPropertyDescriptor: refuse('a property descriptor'),
+    },
+  ) as NavGates
+
+  let witness: NavGates | undefined
+  let fewestAbsent = Number.POSITIVE_INFINITY
+  const explore = (): void => {
+    let verdict: boolean
+    try {
+      verdict = drifts(pair, gates)
+    } catch (error) {
+      if (!(error instanceof UnassignedGate)) throw error
+      branched.add(error.key)
+      for (const value of [false, true]) {
+        assigned[error.key] = value
+        explore()
       }
+      delete assigned[error.key]
+      return
+    }
+    if (!verdict) return
+    const absent = Object.values(assigned).filter((value) => value === false).length
+    if (absent < fewestAbsent) {
+      fewestAbsent = absent
+      witness = { ...ALL_GATES, ...assigned }
     }
   }
-  return smallest
+  explore()
+  return { witness, branched }
 }
 
 /** Every static test id this layer actually renders. */
@@ -307,14 +338,14 @@ describe('the built-in tutorial tour catalog', () => {
     const pairs = navAnchoredSteps()
     // Guard the guard, twice over. A pairing that matched nothing would pass vacuously, and
     // there is one per tour that opens a sidebar surface: `add-service` plus every platform
-    // tour. And a gate field that is not a boolean would silently never vary across the
-    // matrix, leaving whatever it gates unexercised.
+    // tour. And a search that branched on no field would pass without varying anything:
+    // `navItemVisible` always reads `advancedMode` or `fullSurface`, so every pair must branch.
     expect(pairs.length).toBeGreaterThanOrEqual(8)
-    expect(Object.values(ALL_GATES).every((value) => typeof value === 'boolean')).toBe(true)
+    const results = pairs.map(navRequirementDrift)
+    expect(results.filter((result) => result.branched.size === 0)).toEqual([])
 
-    const witnesses = navRequirementDrifts(pairs)
     const drifted = pairs.flatMap((pair, index) => {
-      const witness = witnesses[index]
+      const witness = results[index]!.witness
       if (witness === undefined) return []
       return [`${pair.label} is offered without ${absentGates(witness).join(' / ')}`]
     })
@@ -481,7 +512,7 @@ describe('tour availability across the catalog', () => {
 
   it('holds the interface tier as a requirement of the tours whose surface hides in basic', () => {
     // Two different reasons, one requirement. `share-services` clicks a nav entry marked
-    // `advanced: true` (which `navRequirementDrifts` also enforces); `panel-reviews` clicks a
+    // `advanced: true` (which `navRequirementDrift` also enforces); `panel-reviews` clicks a
     // BASIC entry whose consensus section renders only in advanced mode or once a group exists,
     // one level below anything the nav guard can see. Basic is the shipped default, so without
     // this both would be offered to nearly every user and find nothing.

package/app/pages/index.vue

@@ -185,6 +185,8 @@ onMounted(() => {
   useRunDeepLink()
   // `?addRepo=<owner>/<name>`: an integration sending a person to add a service for a repository.
   useAddRepoDeepLink()
+  // `?newApiKey=1`: an integration sending a person to mint a key bound to them.
+  useNewApiKeyDeepLink()
   // `?view=queue` / `?view=board`: a link that opens one of the board's two views.
   views.consumeDeepLink()
   void workspace.init()

package/app/stores/publicApiKeys.spec.ts

@@ -10,6 +10,7 @@ function key(over: Partial<PublicApiKey> = {}): PublicApiKey {
     accountId: 'acc1',
     workspaceId: 'ws1',
     workspaceIds: ['ws1'],
+    followsMemberships: false,
     label: 'CI',
     scope: 'write',
     createdByUserId: null,
@@ -105,10 +106,20 @@ describe('publicApiKeys store', () => {
 
     const store = usePublicApiKeysStore()
     await store.create('ci', 'write')
-    expect(body).toHaveBeenCalledWith({ label: 'ci', scope: 'write', actsAsSelf: false })
+    expect(body).toHaveBeenCalledWith({
+      label: 'ci',
+      scope: 'write',
+      actsAsSelf: false,
+      followsMemberships: false,
+    })
 
     await store.create('mine', 'write', true)
-    expect(body).toHaveBeenCalledWith({ label: 'mine', scope: 'write', actsAsSelf: true })
+    expect(body).toHaveBeenCalledWith({
+      label: 'mine',
+      scope: 'write',
+      actsAsSelf: true,
+      followsMemberships: false,
+    })
   })
 
   it('sends a reach only when one was chosen, so the default stays this workspace alone', async () => {
@@ -119,13 +130,19 @@ describe('publicApiKeys store', () => {
 
     const store = usePublicApiKeysStore()
     await store.create('ci', 'read')
-    expect(body).toHaveBeenLastCalledWith({ label: 'ci', scope: 'read', actsAsSelf: false })
+    expect(body).toHaveBeenLastCalledWith({
+      label: 'ci',
+      scope: 'read',
+      actsAsSelf: false,
+      followsMemberships: false,
+    })
 
     await store.create('all', 'read', false, null)
     expect(body).toHaveBeenLastCalledWith({
       label: 'all',
       scope: 'read',
       actsAsSelf: false,
+      followsMemberships: false,
       workspaceIds: null,
     })
 
@@ -134,8 +151,23 @@ describe('publicApiKeys store', () => {
       label: 'two',
       scope: 'read',
       actsAsSelf: false,
+      followsMemberships: false,
       workspaceIds: ['ws1', 'ws2'],
     })
+
+    // A key that follows its person's memberships names no workspaces, and lists here at once.
+    body.mockResolvedValueOnce({
+      key: key({ id: 'pak_follow', workspaceIds: [], followsMemberships: true }),
+      secret: 's',
+    })
+    await store.create('mine', 'decide', true, 'memberships')
+    expect(body).toHaveBeenLastCalledWith({
+      label: 'mine',
+      scope: 'decide',
+      actsAsSelf: true,
+      followsMemberships: true,
+    })
+    expect(store.keys.map((k) => k.id)).toContain('pak_follow')
   })
 
   it('revoke drops the key from the list', async () => {

package/app/stores/publicApiKeys.ts

@@ -59,14 +59,15 @@ export const usePublicApiKeysStore = defineStore('publicApiKeys', () => {
    * it starts can unlock them with the password sent on that call. Passed through rather than
    * defaulted here: the server writes the id off the session, so this is only ever a yes/no.
    *
-   * `workspaceIds` is the key's reach: omitted for this workspace alone, `null` for every workspace
-   * in the account, or a list. Anything past this workspace needs an account admin.
+   * `reach` is omitted for this workspace alone, `null` for every workspace in the account, a list,
+   * or `'memberships'` for whatever the person can act in on each call (a bound key only). A list
+   * or `null` needs an account admin; following memberships does not.
    */
   async function create(
     label: string,
     scope: PublicApiScope,
     actsAsSelf = false,
-    workspaceIds?: string[] | null,
+    reach?: string[] | null | 'memberships',
   ): Promise<CreatedPublicApiKey> {
     const ws = useWorkspaceStore()
     const workspaceId = ws.requireId()
@@ -74,14 +75,17 @@ export const usePublicApiKeysStore = defineStore('publicApiKeys', () => {
       label,
       scope,
       actsAsSelf,
-      ...(workspaceIds === undefined ? {} : { workspaceIds }),
+      followsMemberships: reach === 'memberships',
+      ...(reach === undefined || reach === 'memberships' ? {} : { workspaceIds: reach }),
     })
     // Prepend: the backend lists newest-first, so the freshly minted key belongs at the
     // top — matching the order a subsequent `load()` would produce. A key picked to reach only
     // other workspaces is not in this board's list, and revoking it from here would be refused as
     // a no-op, so it is not shown.
     const reaches =
-      created.key.workspaceIds === null || created.key.workspaceIds.includes(workspaceId)
+      created.key.followsMemberships ||
+      created.key.workspaceIds === null ||
+      created.key.workspaceIds.includes(workspaceId)
     if (reaches) keys.value = [created.key, ...keys.value]
     available.value = true
     return created

package/app/stores/ui/modals.ts

@@ -11,6 +11,7 @@ import type {
   ProviderConnectionKind,
 } from '~/types/providerConnections'
 import type { AddServicePrefill } from '~/composables/useAddRepoDeepLink'
+import type { NewApiKeyPrefill } from '~/composables/useNewApiKeyDeepLink'
 import type { PendingContext } from '~/composables/useContextLinking'
 import {
   infraSetupDismissalKey,
@@ -667,6 +668,8 @@ function createIntegrationPanelModals(resetHubReturn: ResetHubReturn) {
   // API access tokens: the workspace's inbound public-API keys external systems present to
   // the `/api/v1` surface. Opened from the Integrations hub.
   const apiTokensOpen = ref(false)
+  // The create form a new-API-key deep link opened the window with, consumed on open.
+  const apiTokensPrefill = ref<NewApiKeyPrefill | null>(null)
   // Opened and closed by `createBuilderModelConfigHandoff`, which hands the pipeline builder over.
   const modelConfigOpen = ref(false)
   // LLM-vendor subscription credentials (the token pool powering the Claude Code
@@ -722,12 +725,14 @@ function createIntegrationPanelModals(resetHubReturn: ResetHubReturn) {
   function closeReports() {
     reportsOpen.value = false
   }
-  function openApiTokens() {
+  function openApiTokens(prefill: NewApiKeyPrefill | null = null) {
     resetHubReturn()
+    apiTokensPrefill.value = prefill
     apiTokensOpen.value = true
   }
   function closeApiTokens() {
     apiTokensOpen.value = false
+    apiTokensPrefill.value = null
   }
   function openVendorCredentials(tab = 'pool') {
     resetHubReturn()
@@ -770,6 +775,7 @@ function createIntegrationPanelModals(resetHubReturn: ResetHubReturn) {
     operatorDashboardOpen,
     reportsOpen,
     apiTokensOpen,
+    apiTokensPrefill,
     modelConfigOpen,
     vendorCredentialsOpen,
     vendorCredentialsTab,

package/i18n/locales/de.json

@@ -848,6 +848,7 @@
         "boundToYou": "Ihr Abonnement",
         "boundToOther": "Abonnement von {user}",
         "reachAll": "Alle Arbeitsbereiche",
+        "reachMemberships": "Folgt den Arbeitsbereichen seiner Person",
         "reachCount": "{count} Arbeitsbereiche"
       },
       "add": {
@@ -869,6 +870,8 @@
         "reachThis": "Nur dieser Arbeitsbereich",
         "reachAll": "Alle Arbeitsbereiche des Kontos",
         "reachSelected": "Ausgewählte Arbeitsbereiche",
+        "reachMemberships": "Meine Arbeitsbereiche (folgt meinen Mitgliedschaften)",
+        "reachMembershipsHelp": "Erreicht bei jedem Aufruf jeden Arbeitsbereich, in dem du handeln kannst: Beitritt oder Austritt ändert das, ohne neues Token. In jedem Arbeitsbereich kann es nicht mehr, als deine Rolle dort erlaubt.",
         "reachPick": "Arbeitsbereiche auswählen"
       },
       "scopes": {

package/i18n/locales/en.json

@@ -3916,6 +3916,7 @@
         "boundToYou": "Your subscription",
         "boundToOther": "{user}'s subscription",
         "reachAll": "All workspaces",
+        "reachMemberships": "Follows its owner's workspaces",
         "reachCount": "{count} workspaces"
       },
       "add": {
@@ -3937,6 +3938,8 @@
         "reachThis": "This workspace only",
         "reachAll": "Every workspace in the account",
         "reachSelected": "Selected workspaces",
+        "reachMemberships": "My workspaces (follows my memberships)",
+        "reachMembershipsHelp": "Reaches every workspace you can act in, on each call: joining or leaving one changes it, with nothing to re-create. In each workspace it can do no more than your role there allows.",
         "reachPick": "Choose workspaces"
       },
       "scopes": {

package/i18n/locales/es.json

@@ -3608,6 +3608,7 @@
         "boundToYou": "Tu suscripción",
         "boundToOther": "Suscripción de {user}",
         "reachAll": "Todos los espacios de trabajo",
+        "reachMemberships": "Sigue los espacios de trabajo de su persona",
         "reachCount": "{count} espacios de trabajo"
       },
       "add": {
@@ -3629,6 +3630,8 @@
         "reachThis": "Solo este espacio de trabajo",
         "reachAll": "Todos los espacios de trabajo de la cuenta",
         "reachSelected": "Espacios de trabajo seleccionados",
+        "reachMemberships": "Mis espacios de trabajo (sigue mis membresías)",
+        "reachMembershipsHelp": "Llega a todos los espacios de trabajo en los que puedes actuar, en cada llamada: unirte o salir de uno lo cambia, sin crear nada de nuevo. En cada uno no puede hacer más de lo que permite tu rol allí.",
         "reachPick": "Elige espacios de trabajo"
       },
       "scopes": {

package/i18n/locales/fr.json

@@ -3608,6 +3608,7 @@
         "boundToYou": "Votre abonnement",
         "boundToOther": "Abonnement de {user}",
         "reachAll": "Tous les espaces de travail",
+        "reachMemberships": "Suit les espaces de travail de sa personne",
         "reachCount": "{count} espaces de travail"
       },
       "add": {
@@ -3629,6 +3630,8 @@
         "reachThis": "Cet espace de travail uniquement",
         "reachAll": "Tous les espaces de travail du compte",
         "reachSelected": "Espaces de travail sélectionnés",
+        "reachMemberships": "Mes espaces de travail (suit mes adhésions)",
+        "reachMembershipsHelp": "Atteint à chaque appel chaque espace de travail où vous pouvez agir : en rejoindre ou en quitter un le change, sans rien recréer. Dans chacun, il ne peut pas faire plus que votre rôle ne le permet.",
         "reachPick": "Choisir des espaces de travail"
       },
       "scopes": {

package/i18n/locales/he.json

@@ -3749,6 +3749,7 @@
         "boundToYou": "המנוי שלך",
         "boundToOther": "המנוי של {user}",
         "reachAll": "כל סביבות העבודה",
+        "reachMemberships": "עוקב אחרי סביבות העבודה של בעליו",
         "reachCount": "{count} סביבות עבודה"
       },
       "add": {
@@ -3770,6 +3771,8 @@
         "reachThis": "סביבת העבודה הזו בלבד",
         "reachAll": "כל סביבות העבודה בחשבון",
         "reachSelected": "סביבות עבודה נבחרות",
+        "reachMemberships": "סביבות העבודה שלי (עוקב אחרי החברויות שלי)",
+        "reachMembershipsHelp": "מגיע בכל קריאה לכל סביבת עבודה שבה אתה יכול לפעול: הצטרפות או עזיבה משנות זאת, בלי ליצור מחדש. בכל סביבה הוא לא יכול יותר ממה שהתפקיד שלך שם מאפשר.",
         "reachPick": "בחירת סביבות עבודה"
       },
       "scopes": {

package/i18n/locales/it.json

@@ -848,6 +848,7 @@
         "boundToYou": "Il tuo abbonamento",
         "boundToOther": "Abbonamento di {user}",
         "reachAll": "Tutti gli spazi di lavoro",
+        "reachMemberships": "Segue gli spazi di lavoro della sua persona",
         "reachCount": "{count} spazi di lavoro"
       },
       "add": {
@@ -869,6 +870,8 @@
         "reachThis": "Solo questo spazio di lavoro",
         "reachAll": "Tutti gli spazi di lavoro dell’account",
         "reachSelected": "Spazi di lavoro selezionati",
+        "reachMemberships": "I miei spazi di lavoro (segue le mie appartenenze)",
+        "reachMembershipsHelp": "Raggiunge a ogni chiamata ogni spazio di lavoro in cui puoi agire: entrarne o uscirne lo cambia, senza ricreare nulla. In ciascuno non può fare più di quanto consente il tuo ruolo lì.",
         "reachPick": "Scegli gli spazi di lavoro"
       },
       "scopes": {

package/i18n/locales/ja.json

@@ -3749,6 +3749,7 @@
         "boundToYou": "あなたのサブスクリプション",
         "boundToOther": "{user} のサブスクリプション",
         "reachAll": "すべてのワークスペース",
+        "reachMemberships": "所有者のワークスペースに追従",
         "reachCount": "{count} 個のワークスペース"
       },
       "add": {
@@ -3770,6 +3771,8 @@
         "reachThis": "このワークスペースのみ",
         "reachAll": "アカウント内のすべてのワークスペース",
         "reachSelected": "選択したワークスペース",
+        "reachMemberships": "自分のワークスペース（メンバーシップに追従）",
+        "reachMembershipsHelp": "呼び出しのたびに、あなたが操作できるすべてのワークスペースに届きます。参加や脱退で変わり、作り直しは不要です。各ワークスペースでは、そこでのあなたのロールが許す以上のことはできません。",
         "reachPick": "ワークスペースを選択"
       },
       "scopes": {

package/i18n/locales/pl.json

@@ -3608,6 +3608,7 @@
         "boundToYou": "Twoja subskrypcja",
         "boundToOther": "Subskrypcja użytkownika {user}",
         "reachAll": "Wszystkie obszary robocze",
+        "reachMemberships": "Śledzi obszary robocze swojej osoby",
         "reachCount": "Obszary robocze: {count}"
       },
       "add": {
@@ -3629,6 +3630,8 @@
         "reachThis": "Tylko ten obszar roboczy",
         "reachAll": "Wszystkie obszary robocze konta",
         "reachSelected": "Wybrane obszary robocze",
+        "reachMemberships": "Moje obszary robocze (śledzi moje członkostwa)",
+        "reachMembershipsHelp": "Przy każdym wywołaniu sięga do każdego obszaru roboczego, w którym możesz działać: dołączenie lub odejście to zmienia, bez tworzenia od nowa. W każdym może tyle, ile pozwala tam Twoja rola.",
         "reachPick": "Wybierz obszary robocze"
       },
       "scopes": {

package/i18n/locales/tr.json

@@ -3749,6 +3749,7 @@
         "boundToYou": "Aboneliğiniz",
         "boundToOther": "{user} kullanıcısının aboneliği",
         "reachAll": "Tüm çalışma alanları",
+        "reachMemberships": "Sahibinin çalışma alanlarını izler",
         "reachCount": "{count} çalışma alanı"
       },
       "add": {
@@ -3770,6 +3771,8 @@
         "reachThis": "Yalnızca bu çalışma alanı",
         "reachAll": "Hesaptaki tüm çalışma alanları",
         "reachSelected": "Seçili çalışma alanları",
+        "reachMemberships": "Çalışma alanlarım (üyeliklerimi izler)",
+        "reachMembershipsHelp": "Her çağrıda işlem yapabildiğiniz her çalışma alanına ulaşır: birine katılmak ya da ayrılmak bunu değiştirir, yeniden oluşturmak gerekmez. Her birinde oradaki rolünüzün izin verdiğinden fazlasını yapamaz.",
         "reachPick": "Çalışma alanlarını seçin"
       },
       "scopes": {

package/i18n/locales/uk.json

@@ -3608,6 +3608,7 @@
         "boundToYou": "Ваша підписка",
         "boundToOther": "Підписка {user}",
         "reachAll": "Усі робочі простори",
+        "reachMemberships": "Стежить за робочими просторами свого власника",
         "reachCount": "Робочих просторів: {count}"
       },
       "add": {
@@ -3629,6 +3630,8 @@
         "reachThis": "Лише цей робочий простір",
         "reachAll": "Усі робочі простори облікового запису",
         "reachSelected": "Вибрані робочі простори",
+        "reachMemberships": "Мої робочі простори (стежить за моїми членствами)",
+        "reachMembershipsHelp": "Під час кожного виклику сягає кожного робочого простору, де ви можете діяти: приєднання чи вихід змінюють це без повторного створення. У кожному він може не більше, ніж дозволяє ваша роль там.",
         "reachPick": "Виберіть робочі простори"
       },
       "scopes": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.317.2",
+  "version": "0.319.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",
@@ -18,7 +18,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@cat-factory/contracts": "0.372.0",
+    "@cat-factory/contracts": "0.373.0",
     "@modular-frontend/core": "0.6.0",
     "@modular-vue/core": "^1.5.0",
     "@modular-vue/journeys": "^1.4.0",