@cat-factory/app 0.274.0 → 0.276.0

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

@@ -7,8 +7,69 @@ const props = defineProps<{ block: Block }>()
 
 const board = useBoardStore()
 const fragments = useFragmentsStore()
+const toast = useToast()
 const { t } = useI18n()
 
+// ---- module assignment -----------------------------------------------------
+// This is the module-assignment route that does NOT depend on how the board is currently
+// grouped. Dragging a card onto a module's group header works only while the reader has
+// grouping set to `module`, and module sub-frames no longer render as boxes to drop onto, so
+// without this the only way to move a task into a module would be to first change a view
+// preference. It writes the same two things a drag does: the declared `moduleName` and, when the
+// module block already exists, the structural parent.
+//
+// The field used to be a free-text `UInput` bound with `v-model="block.moduleName"`, which
+// mutated the cached store object and never called `updateBlock` — so a module typed here was
+// silently discarded on the next board refresh. Now that module grouping is a first-class board
+// affordance, a field that looks like it assigns a module and does not would read as the grouping
+// being broken.
+const service = computed(() => board.serviceOf(props.block))
+
+/** The modules the enclosing service has materialised, as picker options. */
+const moduleOptions = computed(() => {
+  const frame = service.value
+  const existing = frame ? board.modulesOf(frame.id).map((m) => m.title) : []
+  // A task can DECLARE a module the engine has not created a block for yet (it materialises one
+  // on merge), so the task's own value has to be offerable even when no block carries that name,
+  // or opening the picker would silently drop it.
+  const own = props.block.moduleName?.trim()
+  const names = own && !existing.includes(own) ? [...existing, own] : existing
+  return [
+    { label: t('inspector.structure.moduleNone'), value: '' },
+    ...names.map((n) => ({ label: n, value: n })),
+  ]
+})
+
+const selectedModule = computed(() => props.block.moduleName?.trim() ?? '')
+
+async function setModule(name: string) {
+  const previous = selectedModule.value
+  if (name === previous) return
+  try {
+    // The declared module is what the engine reads when it materialises the module block on
+    // merge, so it is written first and is authoritative. "No module" sends the EMPTY STRING,
+    // which is how `updateBlock` spells a clear: `undefined` is dropped by `JSON.stringify`, so
+    // it reached the server as an empty patch and the response then restored the old value.
+    await board.updateBlock(props.block.id, { moduleName: name })
+
+    // When a block for that module already exists, move the task under it now rather than waiting
+    // for a merge, so the board's grouping matches what was just chosen.
+    const frame = service.value
+    const target = frame
+      ? name
+        ? board.modulesOf(frame.id).find((m) => m.title === name)
+        : frame
+      : undefined
+    if (target && target.id !== props.block.parentId) {
+      await board.reparentBlock(props.block.id, target.id, { x: 0, y: 0 })
+    }
+  } catch {
+    // `updateBlock`/`reparentBlock` already roll back and toast their own failures; this catch
+    // exists so a rejected reparent cannot leave the await chain unhandled.
+    // silent-catch-ok: both mutations report their own failure to the user.
+  }
+}
+
 // ---- best-practice prompt fragments ----------------------------------------
 // The task's OWN selection (seeded from its service at creation, then editable per task). The
 // shared <FragmentSelector> renders the picker; a change persists via updateBlock.
@@ -25,12 +86,18 @@ function setFragments(ids: string[]) {
       <div class="mb-1 text-[11px] font-semibold uppercase tracking-wide text-slate-400">
         {{ t('inspector.structure.module') }}
       </div>
-      <UInput
-        v-model="block.moduleName"
+      <USelectMenu
+        :model-value="selectedModule"
+        :items="moduleOptions"
+        value-key="value"
         size="sm"
         class="w-full"
-        :placeholder="t('inspector.structure.modulePlaceholder')"
         icon="i-lucide-package"
+        :create-item="true"
+        :placeholder="t('inspector.structure.modulePlaceholder')"
+        data-testid="task-module-select"
+        @update:model-value="setModule"
+        @create="setModule"
       />
       <p class="mt-1 text-[11px] leading-snug text-slate-500">
         {{ t('inspector.structure.moduleHint') }}

package/app/components/settings/WorkspaceSettingsPanel.vue

@@ -197,6 +197,9 @@ const draft = reactive({
   storeAgentContext: true,
   publishPrVerificationReport: true,
   artifactRetentionDays: 14,
+  doneLaneMaxItems: 20,
+  doneLaneRetentionEnabled: true,
+  doneLaneRetentionDays: 14 as number,
   kaizenEnabled: true,
   allowInitiatorPat: true,
   inputGateMode: 'standard' as InputGateMode,
@@ -218,6 +221,12 @@ function hydrate() {
   draft.storeAgentContext = s.storeAgentContext
   draft.publishPrVerificationReport = s.publishPrVerificationReport
   draft.artifactRetentionDays = s.artifactRetentionDays
+  draft.doneLaneMaxItems = s.doneLaneMaxItems
+  // Nullable (null ⇒ no age cap), so a checkbox is derived from whether a value is stored
+  // and the number input keeps a sensible starting value to switch back on with — the same
+  // shape the nullable review-friction triggers below use.
+  draft.doneLaneRetentionEnabled = s.doneLaneRetentionDays != null
+  draft.doneLaneRetentionDays = s.doneLaneRetentionDays ?? 14
   draft.kaizenEnabled = s.kaizenEnabled
   draft.allowInitiatorPat = s.allowInitiatorPat
   draft.inputGateMode = s.inputGateMode
@@ -276,6 +285,8 @@ async function save() {
       storeAgentContext: draft.storeAgentContext,
       publishPrVerificationReport: draft.publishPrVerificationReport,
       artifactRetentionDays: draft.artifactRetentionDays,
+      doneLaneMaxItems: draft.doneLaneMaxItems,
+      doneLaneRetentionDays: draft.doneLaneRetentionEnabled ? draft.doneLaneRetentionDays : null,
       kaizenEnabled: draft.kaizenEnabled,
       allowInitiatorPat: draft.allowInitiatorPat,
       inputGateMode: draft.inputGateMode,
@@ -540,6 +551,54 @@ async function save() {
               </label>
             </section>
 
+            <!-- What the board's Done swimlane keeps in view -->
+            <section class="space-y-2">
+              <h3 class="text-sm font-semibold text-slate-200">
+                {{ t('settings.workspaceSettings.doneLane.heading') }}
+              </h3>
+              <p class="text-[11px] text-slate-400">
+                {{ t('settings.workspaceSettings.doneLane.body') }}
+              </p>
+              <label class="block w-48">
+                <span class="mb-1 block text-[10px] uppercase tracking-wide text-slate-500">
+                  {{ t('settings.workspaceSettings.doneLane.maxItems') }}
+                </span>
+                <UInput
+                  v-model.number="draft.doneLaneMaxItems"
+                  type="number"
+                  :min="0"
+                  :max="500"
+                  size="sm"
+                  data-testid="done-lane-max-items"
+                />
+              </label>
+              <p v-if="draft.doneLaneMaxItems === 0" class="text-[11px] text-slate-500">
+                {{ t('settings.workspaceSettings.doneLane.zeroHint') }}
+              </p>
+              <label class="flex items-center gap-2">
+                <UCheckbox v-model="draft.doneLaneRetentionEnabled" size="sm" />
+                <span class="text-[11px] text-slate-300">{{
+                  t('settings.workspaceSettings.doneLane.ageToggle')
+                }}</span>
+              </label>
+              <label v-if="draft.doneLaneRetentionEnabled" class="block w-48">
+                <span class="mb-1 block text-[10px] uppercase tracking-wide text-slate-500">
+                  {{ t('settings.workspaceSettings.doneLane.days') }}
+                </span>
+                <UInput
+                  v-model.number="draft.doneLaneRetentionDays"
+                  type="number"
+                  :min="1"
+                  :max="3650"
+                  size="sm"
+                  data-testid="done-lane-retention-days"
+                />
+              </label>
+              <p class="text-[11px] text-slate-500">
+                {{ t('settings.workspaceSettings.doneLane.hidesOnlyHint') }}
+              </p>
+            </section>
+
             <!-- Run credential: the App installation vs. the initiator's own token -->
             <section class="space-y-2">
               <h3 class="text-sm font-semibold text-slate-200">

package/app/composables/useBlockDrag.ts

@@ -9,11 +9,18 @@ const draggingId = ref<string | null>(null)
 
 /**
  * Pointer-driven dragging for blocks positioned inside a container's 2D canvas
- * (tasks inside services/modules, modules inside services) and for free-floating
- * service frames (via their header handle). Movement is divided by the board zoom
- * so the block tracks the cursor. When `reparent` is set, the drop point is
- * hit-tested against `[data-drop-zone]` ancestors so a task can be dragged from a
- * service into a module (or back out).
+ * (initiative cards inside services) and for free-floating service frames (via
+ * their header handle). Movement is divided by the board zoom so the block tracks
+ * the cursor. When `reparent` is set, the drop point is hit-tested against
+ * `[data-drop-zone]` ancestors so a block can be dragged from a service into a
+ * module (or back out).
+ *
+ * A TASK is a `positioned: false` drag, because tasks are laid out in swimlanes and
+ * carry no coordinates a reader can see. Such a drag previews nothing and commits
+ * nothing on a same-container drop: its ONLY effect is a reparent, which is what a
+ * task drag is still for (moving work between services, and into or out of a module).
+ * A position write there would persist coordinates nothing renders and emit a board
+ * event for a change with no visible result.
  */
 export function useBlockDrag() {
   const board = useBoardStore()
@@ -23,7 +30,7 @@ export function useBlockDrag() {
   function startDrag(
     block: Block,
     e: PointerEvent,
-    opts: { reparent?: boolean; clamp?: boolean } = {},
+    opts: { reparent?: boolean; clamp?: boolean; positioned?: boolean } = {},
   ) {
     if (e.button !== 0) return
     // Read-only viewers can pan/inspect but never move or reparent a block — the drag
@@ -35,9 +42,11 @@ export function useBlockDrag() {
     const startX = e.clientX
     const startY = e.clientY
     const orig = { ...block.position }
-    // Container-local blocks (tasks/modules) are clamped to their parent's origin;
-    // frames live in free-floating flow space, so they opt out via `clamp: false`.
+    // Container-local blocks (initiative cards) are clamped to their parent's origin;
+    // frames live in free-floating flow space, so they opt out via `clamp: false`. Inert for
+    // a `positioned: false` drag, which never writes a position at all.
     const clamp = opts.clamp ?? true
+    const positioned = opts.positioned ?? true
     draggingId.value = block.id
     // Position is only previewed locally while dragging and persisted once on
     // release. Writing every move raced — a late, out-of-order response could land
@@ -51,7 +60,10 @@ export function useBlockDrag() {
       const ny = orig.y + (ev.clientY - startY) / z
       moved = true
       last = { x: clamp ? Math.max(0, nx) : nx, y: clamp ? Math.max(0, ny) : ny }
-      board.previewMove(block.id, last)
+      // A lane task has nowhere to preview TO: its place in the column is derived from its
+      // status and the reader's sort, so following the cursor would be a lie the drop then
+      // undoes. The `draggingId` state the card dims itself with is the whole feedback.
+      if (positioned) board.previewMove(block.id, last)
     }
     const onUp = (ev: PointerEvent) => {
       window.removeEventListener('pointermove', onMove)
@@ -60,9 +72,9 @@ export function useBlockDrag() {
         // A successful reparent persists the move itself; otherwise commit the final
         // position in place. Either way it's a single write, not one per frame. Run
         // the hit-test BEFORE clearing draggingId so the dragged element is still
-        // marked non-interactive (see DraggableTask) and the zone beneath resolves.
-        const reparented = opts.reparent && reparentAt(block, ev.clientX, ev.clientY)
-        if (!reparented) void board.moveBlock(block.id, last)
+        // marked non-interactive (see LaneTask) and the zone beneath resolves.
+        const reparented = opts.reparent && reparentAt(block, ev.clientX, ev.clientY, positioned)
+        if (!reparented && positioned) void board.moveBlock(block.id, last)
       }
       draggingId.value = null
     }
@@ -71,10 +83,15 @@ export function useBlockDrag() {
   }
 
   /** Returns true when the block was dropped into a *different* container. */
-  function reparentAt(block: Block, clientX: number, clientY: number): boolean {
+  function reparentAt(
+    block: Block,
+    clientX: number,
+    clientY: number,
+    positioned: boolean,
+  ): boolean {
     const el = document.querySelector(`[data-block-id="${block.id}"]`) as HTMLElement | null
     if (!el) return false
-    // The dragged block is already non-interactive while dragging (DraggableTask
+    // The dragged block is already non-interactive while dragging (LaneTask
     // drops pointer-events on the whole wrapper, handle included); belt-and-braces,
     // also neutralise this node so elementFromPoint resolves the zone beneath it.
     const prev = el.style.pointerEvents
@@ -87,14 +104,27 @@ export function useBlockDrag() {
     const newParent = zoneEl.getAttribute('data-drop-zone')!
     if (newParent === block.parentId) return false // same container — caller commits position
 
+    void board.reparentBlock(block.id, newParent, positionIn(zoneEl, el, positioned))
+    return true
+  }
+
+  /**
+   * Where the dropped block lands in its new container.
+   *
+   * A lane task gets the origin, not the coordinates it happened to be released over.
+   * Its place in the new container is derived from its status and the reader's sort, so a
+   * captured offset would be a coordinate nothing reads and every later reader would have
+   * to wonder whether it meant something.
+   */
+  function positionIn(zoneEl: HTMLElement, el: HTMLElement, positioned: boolean) {
+    if (!positioned) return { x: 0, y: 0 }
     const z = ui.zoom || 1
     const zr = zoneEl.getBoundingClientRect()
     const er = el.getBoundingClientRect()
-    void board.reparentBlock(block.id, newParent, {
+    return {
       x: Math.max(0, (er.left - zr.left) / z),
       y: Math.max(0, (er.top - zr.top) / z),
-    })
-    return true
+    }
   }
 
   return { draggingId, startDrag }

package/app/composables/useBlockQueries.ts

@@ -1,5 +1,6 @@
 import { computed, type Ref } from 'vue'
 import type { Block, BlockStatus } from '~/types/domain'
+import { frameContentSize, LANE_GEOMETRY } from '~/utils/laneGeometry'
 
 /**
  * Pure, read-only queries over a board's blocks. Extracted from the board store
@@ -162,33 +163,35 @@ export function useBlockQueries(blocks: Ref<Block[]>) {
   }
 
   /**
-   * The natural extent of a container's inner 2D canvas — the smallest size that
-   * still fits all its children. This is the floor a resizable frame can never be
-   * dragged below (so tasks/modules are never clipped).
+   * The natural extent of a frame's inner canvas — the smallest size that fits its swimlanes
+   * and its initiative band. This is the floor a resizable frame can never be dragged below.
+   *
+   * Task positions are deliberately NOT consulted any more. Tasks are laid out in status
+   * lanes, so the frame's size is a function of the LANE GEOMETRY, not of where cards happen
+   * to sit, and each lane SCROLLS rather than growing without bound. That decoupling is what
+   * fixes the old behaviour where a service accumulating work grew a taller and taller frame
+   * until it dwarfed its neighbours, and it is also what keeps this function pure over blocks:
+   * a lane's population depends on run state, which this layer cannot see and must not need to.
+   *
+   * The arithmetic itself lives in `frameContentSize` so the placement helper, which sizes a
+   * frame that does not exist yet, reserves the same footprint this one will render at.
    */
   function contentSize(id: string): { w: number; h: number } {
     const b = getBlock(id)
-    const isModule = b?.level === 'module'
-    const TASK_W = 210
-    const TASK_H = 160
-    const headerH = isModule ? 30 : 0
-    let w = isModule ? 200 : 360
-    let inner = isModule ? 60 : 220
-    for (const t of tasksOf(id)) {
-      w = Math.max(w, t.position.x + TASK_W + 12)
-      inner = Math.max(inner, t.position.y + TASK_H + 12)
-    }
-    for (const m of modulesOf(id)) {
-      const s = containerSize(m.id)
-      w = Math.max(w, m.position.x + s.w + 12)
-      inner = Math.max(inner, m.position.y + s.h + 12)
-    }
-    // Initiative cards render inside the frame's drop zone like tasks (230×~170).
-    for (const i of initiativesOf(id)) {
-      w = Math.max(w, i.position.x + 230 + 12)
-      inner = Math.max(inner, i.position.y + 170 + 12)
-    }
-    return { w, h: inner + headerH }
+    // A module is no longer drawn as a box (its tasks appear in the frame's lanes, grouped by
+    // module name), so it has no canvas of its own. A minimal size keeps any incidental caller
+    // honest rather than returning zero, which would read as "measured, and empty".
+    if (b?.level === 'module') return { w: LANE_GEOMETRY.laneWidth, h: 0 }
+
+    const initiatives = initiativesOf(id)
+    return frameContentSize({
+      // The predicate `BlockNode` renders the lanes on: an empty service shows one "add the first
+      // task" panel instead, and reserving lane-sized space for it would leave the frame two and
+      // a half times taller than its own contents.
+      hasChildren:
+        allTasksUnder(id).length > 0 || modulesOf(id).length > 0 || initiatives.length > 0,
+      initiatives: initiatives.length,
+    })
   }
 
   /**

package/app/composables/useFrameLanes.ts

@@ -0,0 +1,177 @@
+import { computed, type Ref } from 'vue'
+import { collectReviewDebt } from '@cat-factory/contracts'
+import type { Block } from '~/types/domain'
+import {
+  groupLaneTasks,
+  runActivityAt,
+  runWaitingSince,
+  sortLaneTasks,
+  type LaneGroup,
+  type LaneTaskEntry,
+} from '~/utils/laneSort'
+import {
+  classifyTask,
+  selectDoneLaneTasks,
+  TASK_LANES,
+  type DoneLaneSelection,
+  type TaskLane,
+} from '~/utils/swimlanes'
+
+/** One rendered lane: its identity, its groups, and the count its header states. */
+export interface RenderedLane {
+  readonly lane: TaskLane
+  readonly groups: LaneGroup[]
+  /** Every task classified into this lane, BEFORE the Done lane's caps. */
+  readonly total: number
+}
+
+/** A lane entry plus the lane it was classified into. */
+interface ClassifiedEntry {
+  readonly entry: LaneTaskEntry
+  readonly lane: TaskLane
+}
+
+/**
+ * Assemble a service frame's tasks into swimlanes.
+ *
+ * This is the store-facing half of the lane model: it resolves every input the pure
+ * `classifyTask` / `sortLaneTasks` / `groupLaneTasks` functions need and nothing more, so the
+ * classification and ordering rules stay testable without a Pinia instance. It also keeps the
+ * per-frame cost linear in the frame's tasks: every cross-block lookup below is a Map read off
+ * an index the stores already maintain, never a scan per task.
+ */
+export function useFrameLanes(frameId: Ref<string>) {
+  const board = useBoardStore()
+  const execution = useExecutionStore()
+  const agentRuns = useAgentRunsStore()
+  const notifications = useNotificationsStore()
+  const settings = useWorkspaceSettingsStore()
+  const laneView = useLaneViewStore()
+  const reviews = useReviewStage()
+
+  /** Tasks directly in the frame plus those inside its modules: a module renders no box now. */
+  const tasks = computed(() => board.allTasksUnder(frameId.value))
+
+  /** Module name → the module BLOCK that materialises it, so a group header can be a drop zone. */
+  const moduleBlockIdByName = computed(
+    () => new Map(board.modulesOf(frameId.value).map((m) => [m.title, m.id])),
+  )
+
+  /**
+   * Per-block "waiting since", derived once from the workspace's open review-wait cards by the
+   * same `collectReviewDebt` the backend's friction check uses. It is the fallback source for
+   * the park surfaces that stamp no `step.pausedAt`; deriving it once rather than per task is
+   * what keeps this assembly linear.
+   */
+  const waitingSinceByBlock = computed(
+    () => new Map(collectReviewDebt(notifications.open).map((d) => [d.blockId, d.waitingSince])),
+  )
+
+  /**
+   * The module a task belongs to: the module BLOCK's title when it already lives in one, else
+   * the module it DECLARES. The engine only materialises the block on merge
+   * (`applyModuleAssignment`), so keying on the parent alone would leave every unmerged task in
+   * "no module" while its own card names one.
+   */
+  function moduleNameOf(task: Block): string | null {
+    const parent = task.parentId ? board.getBlock(task.parentId) : undefined
+    if (parent?.level === 'module') return parent.title
+    return task.moduleName?.trim() || null
+  }
+
+  function classify(task: Block, order: number): ClassifiedEntry {
+    const run = execution.getByBlock(task.id) ?? null
+    const decisions = execution.decisionsByBlock.get(task.id) ?? []
+    const allApprovals = execution.approvalsByBlock.get(task.id) ?? []
+    // The same suppression the card and the frame badge apply: an iterative reviewer mid-cycle
+    // holds a pending approval while the driver folds answers in, and nobody is waiting on it.
+    const humanApprovals = allApprovals.filter((a) => !reviews.isBackground(a.agentKind, a.blockId))
+
+    const { lane, reason } = classifyTask({
+      status: task.status,
+      // Read from the coarse per-block summary, which also covers a bootstrap run.
+      runFailed: agentRuns.byBlock[task.id]?.status === 'failed',
+      run,
+      // A park is background exactly when everything asking was suppressed AND nothing else
+      // asks. With no approvals at all it is NOT background: it is a park on a surface this
+      // layer cannot name, which `classifyTask` reports as `parked` rather than as work.
+      parkIsBackground:
+        decisions.length === 0 &&
+        humanApprovals.length === 0 &&
+        allApprovals.length > humanApprovals.length,
+      pendingDecision: decisions.length > 0,
+      pendingApproval: humanApprovals.length > 0,
+      hasUnmetDeps: board.unmetDeps(task.id).length > 0,
+    })
+
+    return {
+      lane,
+      entry: {
+        task,
+        reason,
+        order,
+        activityAt: runActivityAt(run),
+        waitingSince: runWaitingSince(run, waitingSinceByBlock.value.get(task.id) ?? null),
+        moduleName: moduleNameOf(task),
+        initiativeName: task.initiativeId
+          ? (board.getBlock(task.initiativeId)?.title ?? null)
+          : null,
+        epicName: board.epicOf(task)?.title ?? null,
+      },
+    }
+  }
+
+  /** Every task bucketed by lane, in board order, before sorting. */
+  const byLane = computed(() => {
+    const buckets = new Map<TaskLane, LaneTaskEntry[]>(TASK_LANES.map((lane) => [lane, []]))
+    tasks.value.forEach((task, order) => {
+      const { lane, entry } = classify(task, order)
+      buckets.get(lane)!.push(entry)
+    })
+    return buckets
+  })
+
+  /**
+   * What the Done lane renders, and a full account of what it withheld.
+   *
+   * Computed even while the lane is collapsed, because the collapsed header states the TOTAL:
+   * "this service has finished 312 tasks" is the fact the lane exists to carry, and a header
+   * counting only what it happens to render would understate it by two orders of magnitude.
+   *
+   * `Date.now()` is read non-reactively, as `useReviewDebt` does. The cutoff is re-evaluated
+   * whenever the board, the runs or the settings change, which on a live board is constantly; a
+   * ticking clock purely so a card could vanish mid-session would be motion nobody asked for.
+   */
+  const doneSelection = computed<DoneLaneSelection>(() =>
+    selectDoneLaneTasks(
+      (byLane.value.get('done') ?? []).map((e) => e.task),
+      {
+        maxItems: settings.settings.doneLaneMaxItems,
+        retentionDays: settings.settings.doneLaneRetentionDays,
+      },
+      Date.now(),
+    ),
+  )
+
+  const lanes = computed<RenderedLane[]>(() =>
+    TASK_LANES.map((lane) => {
+      const bucket = byLane.value.get(lane) ?? []
+      // Only the Done lane is capped; every other lane renders everything in it.
+      const visible = lane === 'done' ? admittedByCaps(bucket, doneSelection.value) : bucket
+      const ordered = sortLaneTasks(visible, laneView.sortKey, lane)
+      return {
+        lane,
+        groups: groupLaneTasks(ordered, laneView.groupKey, moduleBlockIdByName.value),
+        total: bucket.length,
+      }
+    }),
+  )
+
+  return { lanes, doneSelection }
+}
+
+/** The entries whose task survived the Done lane's caps. */
+function admittedByCaps(entries: LaneTaskEntry[], selection: DoneLaneSelection): LaneTaskEntry[] {
+  const admitted = new Set(selection.shown.map((task) => task.id))
+  return entries.filter((e) => admitted.has(e.task.id))
+}

package/app/composables/useNavContributions.ts

@@ -66,6 +66,9 @@ export function useNavContributions() {
     // No-op under an env pin (`setMode` refuses), so the palette entry matches the sidebar
     // switcher's read-only state rather than pretending to flip a tier the resolver fixes.
     toggleUiMode: () => useUiModeStore().toggleMode(),
+    // The QUESTION, not a toggle: with three roles there is no unambiguous "next one", and the
+    // prompt is the one surface that states what each role gives you before you pick it.
+    chooseRole: () => useUiRoleStore().openPrompt(),
   }
 
   /** Run a contribution's action (consumer `run` closure wins over the id map). */

package/app/composables/useTaskExpansion.ts

@@ -75,7 +75,7 @@ export function useTaskExpansion(container: Ref<HTMLElement | null>, activity: B
   //
   // Blocks with no pipeline to show are filtered out here rather than left to the card:
   // a frame, a module, or a task with no run expands to nothing, and granting it would
-  // still lift an empty card over its neighbours (see DraggableTask's z-index).
+  // still lift an empty card over its neighbours (see LaneTask's z-index).
   function hoveredTaskId(): string | null {
     if (!pointer) return null
     const hit = document.elementFromPoint(pointer.x, pointer.y)

package/app/docs/consumer-extensions.md

@@ -61,18 +61,29 @@ export default defineNuxtPlugin(() => {
 | Run-detail windows                  | `resultViews`             | `{ id: '<ns>:<name>', component }`                                                                        | `StepResultViewHost` via `dispatchStepView`                               |
 | Agent kinds (palette data)          | `agentKinds`              | `{ kind, container, presentation: { label, icon, color, description, category?, resultView? } }`          | agents store merge → `agentKindMeta`                                      |
 | Custom task types                   | `taskTypes`               | `{ taskType: '<ns>:<name>', presentation, fields?, defaultPipelineId?, defaultFragmentIds?, formPanel? }` | `AddTaskModal` picker/fields + `TaskCard` badge (via `taskTypeMeta`)      |
-| Sidebar / command-palette / toolbar | `nav`                     | `{ id, labelKey, icon, surfaces, gate?, advanced?, run, sidebar?, command?, toolbar? }`                   | the three shells via `useNavContributions`                                |
+| Sidebar / command-palette / toolbar | `nav`                     | `{ id, labelKey, icon, surfaces, gate?, advanced?, intake?, run, sidebar?, command?, toolbar? }`          | the three shells via `useNavContributions`                                |
 | Inspector body panels               | `inspectorPanels`         | `{ id, component, when(block), order }` (`PanelEntry<Block>`)                                             | `<PanelsOutlet>` in `InspectorPanel`                                      |
 | Top-level overlays                  | `appOverlays`             | `{ id: '<ns>:<name>', component }`                                                                        | `<AppOverlayHost>` via `useAppOverlays().open(id)`                        |
-| External tools                      | `externalTools`           | `{ id, title, icon, url, description?, requiredMetadata?, gate?, advanced?, order? }`                     | the "External tools" sidebar section + palette, via `useNavContributions` |
+| External tools                      | `externalTools`           | `{ id, title, icon, url, description?, requiredMetadata?, gate?, advanced?, intake?, order? }`            | the "External tools" sidebar section + palette, via `useNavContributions` |
 | Custom workspace metadata fields    | `workspaceMetadataFields` | `{ key, label, description?, placeholder?, type?, options?, order? }`                                     | the Metadata tab of Workspace settings                                    |
 | Multi-step wizards                  | (journeys)                | `registerJourney` + step modules                                                                          | `<JourneyHost>` / `<JourneyOutlet>`                                       |
 | Locale strings                      | (i18n)                    | `i18n/locales/*.json` in the deployment                                                                   | `@nuxtjs/i18n` layer deep-merge                                           |
 
-A `nav` entry may also declare `advanced: true`, which hides it in **basic** interface mode
-(the shipped default) exactly as it does for the first-party destinations: see
+Beyond `gate`, a destination answers to two narrowing axes, both applied to your entries exactly
+as they are to the first-party ones. All three are independent, and all three must pass.
+
+`advanced: true` hides an entry in **basic** interface mode, the shipped default: see
 [the layer README](../../README.md#interface-modes-basic--advanced). Use it for a power-user
-destination; the flag is independent of `gate`, so both must pass for the item to render.
+destination.
+
+`intake: true` keeps an entry for a role narrowed to the intake surface, today `designer`: see
+[Roles](../../README.md#roles-engineer--product-manager--designer). This one is opt-IN, so an
+entry that says nothing is offered to the full-surface roles only. Declare it where your
+destination is somewhere work comes IN from rather than somewhere the platform is configured; a
+design-handoff console qualifies, an admin panel does not.
+
+Both flags live on `NavGatedContribution`, which an external tool extends too, so a tool answers
+the same axes as a `nav` entry and there is one predicate (`navItemVisible`) deciding both.
 
 ### Run-detail windows (`resultViews` + `agentKinds`)
 
@@ -153,7 +164,10 @@ workspaceMetadataFields: [{ key: 'gameId', label: 'Game id', placeholder: 'zork'
   reason (`resolver-failed`) with the cause logged to the console: the sidebar, the palette and
   the toolbar all render from one catalog, so an uncaught throw would otherwise blank all three.
   Do not rely on it: `requiredMetadata` is how you say a field must be there.
-- **`gate` and `advanced`** work exactly as on a `nav` entry; both must pass.
+- **`gate`, `advanced` and `intake`** work exactly as on a `nav` entry, and for the same reason:
+  a tool is projected onto a nav contribution and filtered by the same predicate. All must pass,
+  and `intake` defaults the same way, so a registered application is dropped for a narrowed role
+  until you say it belongs there.
 
 **The metadata half** is a deployment-declared FIELD list (here) whose VALUES are per workspace,
 typed in under _Workspace settings → Metadata_ and persisted on the workspace settings row. The