From 27d930a7288771a51c5e2877ead63dc7db6b875f Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Fri, 26 Jun 2026 06:35:51 +0000
Subject: [PATCH] feat(hub): exclude projects via right-click menu on project
 cards

Add the ability to hide projects from the hub without disabling them.
Excluded projects stay enabled and keep syncing in the background, but
are filtered out of the hub home, summary aggregates, project switcher,
prev/next navigation, sync-all, and the recent/todo/queue feeds.

Right-clicking a project card opens a context menu with "Sync this
project now" and "Exclude this project". Exclusions persist to hub.json
and broadcast to every open client. Hidden projects can be restored from
the Manage projects settings panel.
---
 src/devframe/hub-mode.ts                 | 15 +++++
 src/devframe/rpc/capabilities.ts         |  7 ++-
 src/devframe/rpc/helpers.ts              |  8 ++-
 src/devframe/rpc/hub-context.ts          |  4 ++
 src/devframe/rpc/hub-disable.ts          |  3 +
 src/devframe/rpc/hub-set-excluded.ts     | 35 +++++++++++
 src/devframe/rpc/index.ts                |  2 +
 src/devframe/rpc/list-projects.ts        |  7 ++-
 src/devframe/rpc/types.ts                |  8 +++
 src/devframe/rpc/utils.ts                |  5 ++
 src/hub/config.test.ts                   | 69 +++++++++++++++++++++
 src/hub/config.ts                        | 35 +++++++++++
 ui/components/hub/Home.vue               | 48 +++++++++++----
 ui/components/hub/ProjectContextMenu.vue | 76 ++++++++++++++++++++++++
 ui/components/hub/ProjectSwitcher.vue    |  6 +-
 ui/components/panel/SettingsProjects.vue | 54 +++++++++++++++++
 ui/composables/useAppCommands.ts         | 33 +++++++++-
 ui/composables/useHubQueue.ts            | 13 ++--
 ui/composables/useHubRecent.ts           | 11 +++-
 ui/composables/useHubState.ts            | 24 +++++++-
 ui/composables/useHubTodos.ts            | 12 +++-
 ui/composables/useHubUiState.ts          | 37 +++++++++++-
 ui/composables/useWhenContext.ts         |  6 +-
 23 files changed, 487 insertions(+), 31 deletions(-)
 create mode 100644 src/devframe/rpc/hub-set-excluded.ts
 create mode 100644 ui/components/hub/ProjectContextMenu.vue

diff --git a/src/devframe/hub-mode.ts b/src/devframe/hub-mode.ts
index 878c6a3..288aa25 100644
--- a/src/devframe/hub-mode.ts
+++ b/src/devframe/hub-mode.ts
@@ -9,6 +9,7 @@ import {
   addHubRoot,
   loadHubConfig,
   setEnabledProjects,
+  setExcludedProjects,
 } from '../hub/config'
 import { slugifyRepoName } from '../server/portless'
 import { buildProjectContext, closeProjectContext } from './project-factory'
@@ -41,6 +42,9 @@ export async function setupHubMode(
   const homeDir = options.homeDir
   const roots = new Set<string>()
   const projects = new Map<string, ProjectContext>()
+  // Absolute paths of enabled projects hidden from the hub. Kept loaded; the
+  // client filters them out of hub surfaces.
+  const excluded = new Set<string>()
 
   // Single in-flight promise serializes config-mutating operations so two
   // concurrent RPCs don't race on the shared hub.json file.
@@ -127,6 +131,8 @@ export async function setupHubMode(
     config = await addHubRoot({ homeDir, path: launchCwd })
   for (const root of config.roots)
     roots.add(root)
+  for (const entry of config.excludedProjects ?? [])
+    excluded.add(entry.path)
   await loadEnabledProjects(config.enabledProjects.map(p => p.path))
 
   const registry: ProjectRegistry = {
@@ -148,6 +154,13 @@ export async function setupHubMode(
     })
   }
 
+  async function persistExcluded(): Promise<void> {
+    await setExcludedProjects({
+      homeDir,
+      paths: Array.from(excluded),
+    })
+  }
+
   setProjectRegistry(devframeCtx, registry)
   setHubContext(devframeCtx, {
     devframeCtx,
@@ -155,12 +168,14 @@ export async function setupHubMode(
     launchCwd,
     roots,
     projects,
+    excluded,
     withLock,
     buildHubInfo,
     broadcastProjectsChange,
     broadcastHubInfoChange,
     loadProjectByPath,
     persistEnabled,
+    persistExcluded,
     autoSync,
   })
   registerGhfsRpc(devframeCtx)
diff --git a/src/devframe/rpc/capabilities.ts b/src/devframe/rpc/capabilities.ts
index cf1176c..8c33dae 100644
--- a/src/devframe/rpc/capabilities.ts
+++ b/src/devframe/rpc/capabilities.ts
@@ -1,18 +1,21 @@
 import { defineRpcFunction } from 'devframe'
 import { GHFS_VERSION } from '../../meta'
 import { summarizeProject } from './helpers'
-import { getProjectRegistry } from './utils'
+import { getProjectRegistry, tryGetHubContext } from './utils'
 
 export const capabilities = defineRpcFunction({
   name: 'ghfs:capabilities',
   type: 'static',
   setup: (context) => {
     const registry = getProjectRegistry(context)
+    const hub = tryGetHubContext(context)
     return {
       handler: async () => ({
         mode: registry.mode,
         ghfsVersion: GHFS_VERSION,
-        projects: await Promise.all(registry.listProjects().map(summarizeProject)),
+        projects: await Promise.all(
+          registry.listProjects().map(ctx => summarizeProject(ctx, { excluded: hub?.excluded.has(ctx.path) ?? false })),
+        ),
       }),
     }
   },
diff --git a/src/devframe/rpc/helpers.ts b/src/devframe/rpc/helpers.ts
index 726febf..554554f 100644
--- a/src/devframe/rpc/helpers.ts
+++ b/src/devframe/rpc/helpers.ts
@@ -59,7 +59,12 @@ export async function buildRepoMeta(ctx: ProjectContext): Promise<RepoMeta> {
   }
 }
 
-export async function summarizeProject(ctx: ProjectContext): Promise<ProjectSummary> {
+export interface SummarizeProjectOptions {
+  /** Whether the user has hidden this project from the hub. */
+  excluded?: boolean
+}
+
+export async function summarizeProject(ctx: ProjectContext, options: SummarizeProjectOptions = {}): Promise<ProjectSummary> {
   const [repo, syncState, snapshot] = await Promise.all([
     buildRepoMeta(ctx),
     loadSyncState(ctx.storageDirAbsolute),
@@ -107,6 +112,7 @@ export async function summarizeProject(ctx: ProjectContext): Promise<ProjectSumm
     lastSyncedAt: syncState.lastSyncedAt,
     lastActivityAt,
     labels,
+    excluded: options.excluded ?? false,
   }
 }
 
diff --git a/src/devframe/rpc/hub-context.ts b/src/devframe/rpc/hub-context.ts
index e034d4c..8065cd5 100644
--- a/src/devframe/rpc/hub-context.ts
+++ b/src/devframe/rpc/hub-context.ts
@@ -13,11 +13,15 @@ export interface HubRpcContext {
   launchCwd: string
   roots: Set<string>
   projects: Map<string, ProjectContext>
+  /** Absolute paths of enabled projects the user has hidden from the hub. */
+  excluded: Set<string>
   withLock: <T>(fn: () => Promise<T>) => Promise<T>
   buildHubInfo: () => HubInfo
   broadcastProjectsChange: () => void
   broadcastHubInfoChange: () => void
   loadProjectByPath: (path: string) => Promise<ProjectContext>
   persistEnabled: () => Promise<void>
+  /** Persist the current `excluded` set to hub.json. */
+  persistExcluded: () => Promise<void>
   autoSync: { setInterval: (ms: number | undefined) => void, close: () => void }
 }
diff --git a/src/devframe/rpc/hub-disable.ts b/src/devframe/rpc/hub-disable.ts
index 253bf6b..0f82156 100644
--- a/src/devframe/rpc/hub-disable.ts
+++ b/src/devframe/rpc/hub-disable.ts
@@ -16,6 +16,9 @@ export const hubDisable = defineRpcFunction({
           hub.projects.delete(id)
           await closeProjectContext(ctx)
           await hub.persistEnabled()
+          // A disabled project should not linger in the excluded set.
+          if (hub.excluded.delete(ctx.path))
+            await hub.persistExcluded()
           hub.broadcastProjectsChange()
           return { removed: true }
         })
diff --git a/src/devframe/rpc/hub-set-excluded.ts b/src/devframe/rpc/hub-set-excluded.ts
new file mode 100644
index 0000000..2763ec4
--- /dev/null
+++ b/src/devframe/rpc/hub-set-excluded.ts
@@ -0,0 +1,35 @@
+import { defineRpcFunction } from 'devframe'
+import { getHubContext } from './utils'
+
+/**
+ * Hide (or restore) an enabled project from the hub. Excluded projects stay
+ * loaded and keep syncing — the exclusion only filters them out of the hub
+ * home, aggregates, and recent/todo/queue views. Persisted to hub.json and
+ * broadcast so every open client refreshes its project list.
+ */
+export const hubSetExcluded = defineRpcFunction({
+  name: 'ghfs:hub-set-excluded',
+  type: 'action',
+  setup: (context) => {
+    const hub = getHubContext(context)
+    return {
+      handler: async (id: string, excluded: boolean): Promise<{ excluded: boolean }> => {
+        return hub.withLock(async () => {
+          const ctx = hub.projects.get(id)
+          if (!ctx)
+            return { excluded: false }
+          const had = hub.excluded.has(ctx.path)
+          if (excluded)
+            hub.excluded.add(ctx.path)
+          else
+            hub.excluded.delete(ctx.path)
+          if (had !== excluded) {
+            await hub.persistExcluded()
+            hub.broadcastProjectsChange()
+          }
+          return { excluded }
+        })
+      },
+    }
+  },
+})
diff --git a/src/devframe/rpc/index.ts b/src/devframe/rpc/index.ts
index 245e1ce..a2db796 100644
--- a/src/devframe/rpc/index.ts
+++ b/src/devframe/rpc/index.ts
@@ -20,6 +20,7 @@ import { hubRecentItems } from './hub-recent-items'
 import { hubRemoveRoot } from './hub-remove-root'
 import { hubScan } from './hub-scan'
 import { hubSeenHistory } from './hub-seen-history'
+import { hubSetExcluded } from './hub-set-excluded'
 import { hubSetSettings } from './hub-set-settings'
 import { hubSettings } from './hub-settings'
 import { hubTodos } from './hub-todos'
@@ -71,6 +72,7 @@ export const rpcFunctions = [
   hubScan,
   hubEnable,
   hubDisable,
+  hubSetExcluded,
   hubAddRoot,
   hubRemoveRoot,
   hubSettings,
diff --git a/src/devframe/rpc/list-projects.ts b/src/devframe/rpc/list-projects.ts
index 2b7f020..a4116d3 100644
--- a/src/devframe/rpc/list-projects.ts
+++ b/src/devframe/rpc/list-projects.ts
@@ -1,14 +1,17 @@
 import { defineRpcFunction } from 'devframe'
 import { summarizeProject } from './helpers'
-import { getProjectRegistry } from './utils'
+import { getProjectRegistry, tryGetHubContext } from './utils'
 
 export const listProjects = defineRpcFunction({
   name: 'ghfs:list-projects',
   type: 'query',
   setup: (context) => {
     const registry = getProjectRegistry(context)
+    const hub = tryGetHubContext(context)
     return {
-      handler: async () => Promise.all(registry.listProjects().map(summarizeProject)),
+      handler: async () => Promise.all(
+        registry.listProjects().map(ctx => summarizeProject(ctx, { excluded: hub?.excluded.has(ctx.path) ?? false })),
+      ),
     }
   },
 })
diff --git a/src/devframe/rpc/types.ts b/src/devframe/rpc/types.ts
index 1293aae..07ad616 100644
--- a/src/devframe/rpc/types.ts
+++ b/src/devframe/rpc/types.ts
@@ -27,6 +27,13 @@ export interface ProjectSummary {
   lastSyncedAt?: string
   /** Most recent `item.updatedAt` across the project's tracked items. */
   lastActivityAt?: string
+  /**
+   * True when the user has hidden this project from the hub. Excluded projects
+   * stay enabled and keep syncing; the client filters them out of the hub home,
+   * aggregates, and recent/todo/queue views. Always `false` in single-project
+   * (ui) mode.
+   */
+  excluded?: boolean
   /**
    * Repository label registry (names, colors, descriptions) from the most
    * recent repo snapshot. Consumed by hub-level views (recent, todos) to
@@ -219,6 +226,7 @@ export interface GhfsServerFunctions {
   'ghfs:hub-scan': () => Promise<HubScannedProject[]>
   'ghfs:hub-enable': (path: string) => Promise<{ id: string }>
   'ghfs:hub-disable': (id: string) => Promise<{ removed: boolean }>
+  'ghfs:hub-set-excluded': (id: string, excluded: boolean) => Promise<{ excluded: boolean }>
   'ghfs:hub-add-root': (path: string) => Promise<HubInfo>
   'ghfs:hub-remove-root': (path: string) => Promise<HubInfo>
   'ghfs:hub-recent-items': (limit?: number) => Promise<HubRecentItem[]>
diff --git a/src/devframe/rpc/utils.ts b/src/devframe/rpc/utils.ts
index ee6d17c..ad1f47e 100644
--- a/src/devframe/rpc/utils.ts
+++ b/src/devframe/rpc/utils.ts
@@ -26,6 +26,11 @@ export function getHubContext(ctx: DevframeNodeContext): HubRpcContext {
   return hub
 }
 
+/** Like {@link getHubContext} but returns null in single-project (ui) mode. */
+export function tryGetHubContext(ctx: DevframeNodeContext): HubRpcContext | null {
+  return hubMap.get(ctx) ?? null
+}
+
 export function setHubContext(ctx: DevframeNodeContext, hub: HubRpcContext): void {
   hubMap.set(ctx, hub)
 }
diff --git a/src/hub/config.test.ts b/src/hub/config.test.ts
index 5e6f0ed..617e901 100644
--- a/src/hub/config.test.ts
+++ b/src/hub/config.test.ts
@@ -9,6 +9,7 @@ import {
   resolveHubConfigPath,
   saveHubConfig,
   setEnabledProjects,
+  setExcludedProjects,
   setHubAutoSyncInterval,
   setHubCommentTemplates,
   setHubSwrSettings,
@@ -141,6 +142,74 @@ describe('hub config', () => {
     expect(config.roots).toEqual(['/a'])
   })
 
+  it('round-trips excludedProjects', async () => {
+    const homeDir = await makeHome()
+    const config = await setExcludedProjects({
+      homeDir,
+      paths: ['/a/hidden-1', '/a/hidden-2', '/a/hidden-1'],
+    })
+    expect(config.excludedProjects).toEqual([
+      { path: '/a/hidden-1' },
+      { path: '/a/hidden-2' },
+    ])
+    const reloaded = await loadHubConfig({ homeDir })
+    expect(reloaded.excludedProjects).toEqual([
+      { path: '/a/hidden-1' },
+      { path: '/a/hidden-2' },
+    ])
+  })
+
+  it('setExcludedProjects preserves enabledProjects and roots', async () => {
+    const homeDir = await makeHome()
+    await saveHubConfig({
+      homeDir,
+      config: { roots: ['/a'], enabledProjects: [{ path: '/a/keep' }, { path: '/a/hide' }] },
+    })
+    const config = await setExcludedProjects({ homeDir, paths: ['/a/hide'] })
+    expect(config.roots).toEqual(['/a'])
+    expect(config.enabledProjects).toEqual([{ path: '/a/keep' }, { path: '/a/hide' }])
+    expect(config.excludedProjects).toEqual([{ path: '/a/hide' }])
+  })
+
+  it('omits excludedProjects from disk when never set', async () => {
+    const homeDir = await makeHome()
+    await saveHubConfig({ homeDir, config: { roots: ['/a'], enabledProjects: [] } })
+    const raw = JSON.parse(await readFile(resolveHubConfigPath({ homeDir }), 'utf8'))
+    expect('excludedProjects' in raw).toBe(false)
+  })
+
+  it('distinguishes never-set from explicitly-empty excludedProjects', async () => {
+    const homeDir = await makeHome()
+    await saveHubConfig({ homeDir, config: { roots: ['/a'], enabledProjects: [] } })
+    expect((await loadHubConfig({ homeDir })).excludedProjects).toBeUndefined()
+    await setExcludedProjects({ homeDir, paths: [] })
+    expect((await loadHubConfig({ homeDir })).excludedProjects).toEqual([])
+  })
+
+  it('removeHubRoot prunes excludedProjects under the removed root', async () => {
+    const homeDir = await makeHome()
+    await saveHubConfig({
+      homeDir,
+      config: {
+        roots: ['/a', '/b'],
+        enabledProjects: [{ path: '/a/repo-1' }, { path: '/b/repo-2' }],
+        excludedProjects: [{ path: '/a/repo-1' }, { path: '/b/repo-2' }],
+      },
+    })
+    const config = await removeHubRoot({ homeDir, path: '/a' })
+    expect(config.enabledProjects).toEqual([{ path: '/b/repo-2' }])
+    expect(config.excludedProjects).toEqual([{ path: '/b/repo-2' }])
+  })
+
+  it('preserves excludedProjects when other fields are mutated', async () => {
+    const homeDir = await makeHome()
+    await setExcludedProjects({ homeDir, paths: ['/a/hide'] })
+    await setHubAutoSyncInterval({ homeDir, intervalMs: 120_000 })
+    const reloaded = await loadHubConfig({ homeDir })
+    expect(reloaded.excludedProjects).toEqual([{ path: '/a/hide' }])
+    expect(reloaded.autoSyncIntervalMs).toBe(120_000)
+  })
+
   it('setHubAutoSyncInterval updates the global field', async () => {
     const homeDir = await makeHome()
     await addHubRoot({ homeDir, path: '/a' })
diff --git a/src/hub/config.ts b/src/hub/config.ts
index 93e3ada..28ef5dd 100644
--- a/src/hub/config.ts
+++ b/src/hub/config.ts
@@ -15,6 +15,7 @@ const CommentTemplateSchema = v.object({
 const ConfigSchema = v.object({
   roots: v.optional(v.array(v.string())),
   enabledProjects: v.optional(v.array(ProjectEntrySchema)),
+  excludedProjects: v.optional(v.array(ProjectEntrySchema)),
   autoSyncIntervalMs: v.optional(v.pipe(v.number(), v.minValue(60_000), v.maxValue(3_600_000))),
   commentTemplates: v.optional(v.array(CommentTemplateSchema)),
   swrSyncEnabled: v.optional(v.boolean()),
@@ -46,6 +47,13 @@ export interface HubConfig {
   roots: string[]
   /** Absolute paths of projects the user has enabled. Independent of `roots`. */
   enabledProjects: HubProjectEntry[]
+  /**
+   * Absolute paths of enabled projects the user has hidden from the hub. These
+   * stay loaded and keep syncing — they are merely filtered out of the hub
+   * home, aggregates, and recent/todo/queue views until restored. A subset of
+   * `enabledProjects`.
+   */
+  excludedProjects?: HubProjectEntry[]
   /** Global auto-sync interval applied to every project. */
   autoSyncIntervalMs?: number
   /** Global comment templates surfaced in the composer's template picker. */
@@ -124,6 +132,8 @@ function parseConfig(raw: unknown): HubConfig {
       swrSyncEnabled: flat.output.swrSyncEnabled,
       swrCacheTimeoutMs: flat.output.swrCacheTimeoutMs,
     }
+    if (flat.output.excludedProjects !== undefined)
+      config.excludedProjects = dedupeProjects(flat.output.excludedProjects.map(e => ({ path: normalizePath(e.path) })))
     if (flat.output.commentTemplates !== undefined)
       config.commentTemplates = flat.output.commentTemplates.map(t => ({ title: t.title, body: t.body }))
     return config
@@ -167,6 +177,9 @@ export async function saveHubConfig(options: SaveHubConfigOptions): Promise<void
   const next: HubConfig = {
     roots: dedupePaths(options.config.roots.map(normalizePath)),
     enabledProjects: dedupeProjects(options.config.enabledProjects.map(e => ({ path: normalizePath(e.path) }))),
+    excludedProjects: options.config.excludedProjects === undefined
+      ? undefined
+      : dedupeProjects(options.config.excludedProjects.map(e => ({ path: normalizePath(e.path) }))),
     autoSyncIntervalMs: options.config.autoSyncIntervalMs,
     commentTemplates: options.config.commentTemplates,
     swrSyncEnabled: options.config.swrSyncEnabled,
@@ -178,6 +191,8 @@ export async function saveHubConfig(options: SaveHubConfigOptions): Promise<void
     roots: next.roots,
     enabledProjects: next.enabledProjects,
   }
+  if (next.excludedProjects !== undefined)
+    json.excludedProjects = next.excludedProjects
   if (next.autoSyncIntervalMs !== undefined)
     json.autoSyncIntervalMs = next.autoSyncIntervalMs
   if (next.commentTemplates !== undefined)
@@ -215,6 +230,7 @@ export async function removeHubRoot(options: MutateHubConfigOptions): Promise<Hu
     ...current,
     roots: nextRoots,
     enabledProjects: nextProjects,
+    excludedProjects: current.excludedProjects?.filter(p => !isUnder(p.path, target)),
   }
   await saveHubConfig({ homeDir: options.homeDir, config: next })
   return next
@@ -234,6 +250,25 @@ export async function setEnabledProjects(options: SetEnabledProjectsOptions): Pr
   return next
 }
 
+export interface SetExcludedProjectsOptions extends ResolveHubConfigPathOptions {
+  paths: string[]
+}
+
+/**
+ * Overwrite the set of projects hidden from the hub. Pass the full list of
+ * excluded paths (deduped + normalized here). An empty array clears the
+ * exclusion (the field is then written as `[]`).
+ */
+export async function setExcludedProjects(options: SetExcludedProjectsOptions): Promise<HubConfig> {
+  const current = await loadHubConfig(options)
+  const next: HubConfig = {
+    ...current,
+    excludedProjects: dedupeProjects(options.paths.map(p => ({ path: normalizePath(p) }))),
+  }
+  await saveHubConfig({ homeDir: options.homeDir, config: next })
+  return next
+}
+
 export interface SetHubAutoSyncIntervalOptions extends ResolveHubConfigPathOptions {
   intervalMs: number | undefined
 }
diff --git a/ui/components/hub/Home.vue b/ui/components/hub/Home.vue
index c3c541d..9a37f2f 100644
--- a/ui/components/hub/Home.vue
+++ b/ui/components/hub/Home.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { ProjectSummary } from '#ghfs/rpc-types'
-import { computed, onMounted, ref } from 'vue'
+import { computed, onBeforeUnmount, onMounted, ref } from 'vue'
 import { navigateTo } from '#imports'
 import { useHubActivity } from '../../composables/useHubActivity'
 import { useHubState } from '../../composables/useHubState'
@@ -12,11 +12,12 @@ import UiEmptyState from '../ui/EmptyState.vue'
 import UiModal from '../ui/Modal.vue'
 import UiWithCommand from '../ui/WithCommand.vue'
 import HubProjectCard from './ProjectCard.vue'
+import HubProjectContextMenu from './ProjectContextMenu.vue'
 
 const rpc = useRpc()
 const hub = useHubState()
 
-const projects = computed<ProjectSummary[]>(() => hub.projects.value)
+const projects = computed<ProjectSummary[]>(() => hub.visibleProjects.value)
 const focusedIndex = ref(0)
 
 const onboardingOpen = ref(false)
@@ -155,6 +156,22 @@ function onCardKeydown(event: KeyboardEvent, index: number) {
   }
   focusedIndex.value = index
 }
+
+function onCardFocus(index: number, projectId: string) {
+  focusedIndex.value = index
+  hub.setFocusedProjectId(projectId)
+}
+
+function onCardBlur(projectId: string) {
+  // Only clear if this card still owns the focus marker — a card→card move
+  // fires blur(prev) before focus(next), so guarding avoids clobbering.
+  if (hub.focusedProjectId.value === projectId)
+    hub.setFocusedProjectId(null)
+}
+
+onBeforeUnmount(() => {
+  hub.setFocusedProjectId(null)
+})
 </script>
 
 <template>
@@ -219,7 +236,9 @@ function onCardKeydown(event: KeyboardEvent, index: number) {
         <section class="flex flex-col gap-3">
           <div class="flex items-baseline gap-2">
             <h2 class="text-sm font-semibold">Projects</h2>
-            <span class="color-muted text-xs">{{ projects.length }} enabled · sorted by recent activity</span>
+            <span class="color-muted text-xs">
+              {{ projects.length }} shown<template v-if="hub.excludedProjects.value.length > 0"> · {{ hub.excludedProjects.value.length }} hidden</template> · sorted by recent activity
+            </span>
             <div class="flex-1" />
             <UiWithCommand v-if="projects.length > 0" v-slot="{ execute, disabled }" command="hub.manage">
               <button
@@ -259,18 +278,23 @@ function onCardKeydown(event: KeyboardEvent, index: number) {
             class="grid gap-3"
             style="grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));"
           >
-            <HubProjectCard
+            <HubProjectContextMenu
               v-for="(project, index) in projects"
               :key="project.id"
-              :ref="el => setCardRef(el, index)"
               :project="project"
-              data-testid="hub-project-card"
-              :data-project-id="project.id"
-              :data-project-repo="project.repo"
-              @click="openProject(project.repo)"
-              @keydown="onCardKeydown($event, index)"
-              @focus="focusedIndex = index"
-            />
+            >
+              <HubProjectCard
+                :ref="el => setCardRef(el, index)"
+                :project="project"
+                data-testid="hub-project-card"
+                :data-project-id="project.id"
+                :data-project-repo="project.repo"
+                @click="openProject(project.repo)"
+                @keydown="onCardKeydown($event, index)"
+                @focus="onCardFocus(index, project.id)"
+                @blur="onCardBlur(project.id)"
+              />
+            </HubProjectContextMenu>
           </div>
         </section>
       </div>
diff --git a/ui/components/hub/ProjectContextMenu.vue b/ui/components/hub/ProjectContextMenu.vue
new file mode 100644
index 0000000..5a56d99
--- /dev/null
+++ b/ui/components/hub/ProjectContextMenu.vue
@@ -0,0 +1,76 @@
+<script setup lang="ts">
+import type { ProjectSummary } from '#ghfs/rpc-types'
+import { computed } from 'vue'
+import {
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuPortal,
+  ContextMenuRoot,
+  ContextMenuSeparator,
+  ContextMenuTrigger,
+} from 'reka-ui'
+import { useAppState } from '../../composables/useAppState'
+import { setProjectExcluded, syncProject } from '../../composables/useHubUiState'
+import { useOnlineState } from '../../composables/useOnlineState'
+import UiKbd from '../ui/Kbd.vue'
+
+const props = defineProps<{
+  project: ProjectSummary
+}>()
+
+const state = useAppState(props.project.id)
+const { offline } = useOnlineState()
+
+const syncing = computed(() => state.syncing.value)
+const canSync = computed(() => props.project.hasToken && !syncing.value && !offline.value)
+
+const itemClass = 'flex items-center gap-2 px-2.5 py-1.5 text-sm rounded-md cursor-default select-none outline-none data-[highlighted]:bg-active data-[disabled]:op-50 data-[disabled]:pointer-events-none'
+
+function onSync() {
+  if (!canSync.value)
+    return
+  void syncProject(props.project.id)
+}
+
+function onExclude() {
+  void setProjectExcluded(props.project.id, true)
+}
+</script>
+
+<template>
+  <ContextMenuRoot>
+    <ContextMenuTrigger as-child>
+      <slot />
+    </ContextMenuTrigger>
+    <ContextMenuPortal>
+      <ContextMenuContent
+        class="panel-floating z-dropdown min-w-56 rounded-lg p-1 shadow-lg outline-none"
+        :collision-padding="8"
+        data-testid="hub-project-menu"
+      >
+        <div class="px-2.5 py-1 text-[11px] color-muted font-mono truncate" :title="project.repo">
+          {{ project.repo }}
+        </div>
+        <ContextMenuSeparator class="my-1 h-px bg-base" />
+        <ContextMenuItem
+          :class="itemClass"
+          :disabled="!canSync"
+          data-testid="hub-project-menu-sync"
+          @select="onSync"
+        >
+          <span class="i-octicon-sync-16 text-sm shrink-0" :class="syncing ? 'animate-spin' : ''" />
+          <span class="flex-1">Sync this project now</span>
+        </ContextMenuItem>
+        <ContextMenuItem
+          :class="itemClass"
+          data-testid="hub-project-menu-exclude"
+          @select="onExclude"
+        >
+          <span class="i-ph-eye-slash-duotone text-sm shrink-0" />
+          <span class="flex-1">Exclude this project</span>
+          <UiKbd command="hub.exclude-project" />
+        </ContextMenuItem>
+      </ContextMenuContent>
+    </ContextMenuPortal>
+  </ContextMenuRoot>
+</template>
diff --git a/ui/components/hub/ProjectSwitcher.vue b/ui/components/hub/ProjectSwitcher.vue
index 8b934a9..c5b9b15 100644
--- a/ui/components/hub/ProjectSwitcher.vue
+++ b/ui/components/hub/ProjectSwitcher.vue
@@ -20,8 +20,10 @@ const triggerRef = ref<HTMLButtonElement | null>(null)
 const menuRef = ref<HTMLElement | null>(null)
 const search = ref('')
 
-const projects = computed<ProjectSummary[]>(() => hub.projects.value)
-const current = computed(() => projects.value.find(p => p.id === props.projectId))
+const projects = computed<ProjectSummary[]>(() => hub.visibleProjects.value)
+// Resolve the active project from the full list so the navbar still labels an
+// excluded-but-open project correctly even though it's hidden from the list.
+const current = computed(() => hub.projects.value.find(p => p.id === props.projectId))
 const filtered = computed<ProjectSummary[]>(() => {
   const q = search.value.trim().toLowerCase()
   if (!q)
diff --git a/ui/components/panel/SettingsProjects.vue b/ui/components/panel/SettingsProjects.vue
index 4b2ea10..d579cb2 100644
--- a/ui/components/panel/SettingsProjects.vue
+++ b/ui/components/panel/SettingsProjects.vue
@@ -2,6 +2,7 @@
 import { computed, ref, watch } from 'vue'
 import type { HubScannedProject } from '#ghfs/rpc-types'
 import { useHubState } from '../../composables/useHubState'
+import { setProjectExcluded } from '../../composables/useHubUiState'
 import { useRpc } from '../../composables/useRpc'
 import DisplayProjectIcon from '../display/ProjectIcon.vue'
 import UiEmptyState from '../ui/EmptyState.vue'
@@ -16,6 +17,22 @@ const props = defineProps<{
 const rpc = useRpc()
 const hub = useHubState()
 
+// ── Excluded projects (hidden from the hub) ───────────────────────────
+const excludedProjects = computed(() => hub.excludedProjects.value)
+const restoringId = ref<string | null>(null)
+
+async function restore(id: string) {
+  if (restoringId.value)
+    return
+  restoringId.value = id
+  try {
+    await setProjectExcluded(id, false)
+  }
+  finally {
+    restoringId.value = null
+  }
+}
+
 // ── Hub roots (top section) ───────────────────────────────────────────
 const rootDraft = ref('')
 const rootError = ref<string | null>(null)
@@ -151,6 +168,43 @@ watch(() => hub.hubRoots.value.join('|'), () => {
 
 <template>
   <div class="flex flex-col gap-6">
+    <!-- Excluded projects -->
+    <section v-if="excludedProjects.length > 0" class="flex flex-col gap-2" data-testid="settings-excluded-projects">
+      <header class="flex items-center gap-1.5">
+        <span class="i-ph-eye-slash-duotone color-active text-sm" />
+        <h3 class="text-sm font-medium">Excluded from hub</h3>
+        <span class="text-xs color-muted">{{ excludedProjects.length }} hidden</span>
+      </header>
+      <p class="text-xs color-muted">These projects stay enabled and keep syncing, but are hidden from the hub home and aggregate views. Restore one to show it again.</p>
+
+      <ul class="flex flex-col border border-base rounded bg-base/40 overflow-hidden">
+        <li
+          v-for="project in excludedProjects"
+          :key="project.id"
+          class="flex items-center gap-3 px-3 py-2 border-b border-base last:border-b-0 hover:bg-active transition"
+          data-testid="settings-excluded-row"
+          :data-project-id="project.id"
+        >
+          <DisplayProjectIcon :project="project" :size="28" fallback-class="color-muted" />
+          <div class="flex-1 min-w-0">
+            <div class="text-sm font-medium font-mono truncate color-muted">{{ project.repo }}</div>
+            <div class="text-[11px] color-faint font-mono truncate" :title="project.path">{{ project.path }}</div>
+          </div>
+          <button
+            type="button"
+            class="btn-action-sm shrink-0"
+            data-testid="settings-excluded-restore"
+            :disabled="restoringId === project.id"
+            :aria-label="`Restore ${project.repo}`"
+            @click="restore(project.id)"
+          >
+            <span :class="restoringId === project.id ? 'i-octicon-sync-16 animate-spin' : 'i-ph-eye-duotone'" />
+            <span>Restore</span>
+          </button>
+        </li>
+      </ul>
+    </section>
+
     <!-- Hub roots -->
     <section class="flex flex-col gap-2">
       <header class="flex items-center gap-1.5">
diff --git a/ui/composables/useAppCommands.ts b/ui/composables/useAppCommands.ts
index 4fb9612..7e4fd39 100644
--- a/ui/composables/useAppCommands.ts
+++ b/ui/composables/useAppCommands.ts
@@ -10,7 +10,7 @@ import { useHubRecent } from './useHubRecent'
 import { useHubState } from './useHubState'
 import { useHubTodos } from './useHubTodos'
 import { useHubQueue } from './useHubQueue'
-import { useHubUiState, syncAllProjects } from './useHubUiState'
+import { useHubUiState, setProjectExcluded, syncAllProjects, syncProject } from './useHubUiState'
 import { useOnlineState } from './useOnlineState'
 import { useQueue } from './useQueue'
 import { useRecentFiltered } from './useRecentFiltered'
@@ -259,7 +259,7 @@ export function createAppCommands(): Command[] {
   }
 
   function navigateProject(delta: number): void {
-    const projects = hub.projects.value
+    const projects = hub.visibleProjects.value
     if (projects.length === 0)
       return
     const currentIdx = projects.findIndex(p => p.id === activeId.value)
@@ -723,6 +723,35 @@ export function createAppCommands(): Command[] {
       help: 'hubMode',
       run: () => { syncAllProjects() },
     },
+    {
+      id: 'hub.sync-project',
+      title: 'Hub: Sync focused project',
+      category: 'Hub',
+      icon: 'i-octicon-sync-16',
+      when: 'hubHome && hubHasFocusedProject && online',
+      help: 'hubMode',
+      run: () => {
+        const id = hub.focusedProjectId.value
+        if (id)
+          void syncProject(id)
+      },
+    },
+    {
+      id: 'hub.exclude-project',
+      title: 'Hub: Exclude focused project',
+      category: 'Hub',
+      icon: 'i-ph-eye-slash-duotone',
+      keybindings: ['e'],
+      when: 'hubHome && hubHasFocusedProject',
+      help: 'hubMode',
+      run: () => {
+        const id = hub.focusedProjectId.value
+        if (!id)
+          return
+        hub.setFocusedProjectId(null)
+        void setProjectExcluded(id, true)
+      },
+    },
     {
       id: 'hub.manage',
       title: 'Hub: Manage projects',
diff --git a/ui/composables/useHubQueue.ts b/ui/composables/useHubQueue.ts
index 5a02ef7..550649a 100644
--- a/ui/composables/useHubQueue.ts
+++ b/ui/composables/useHubQueue.ts
@@ -1,5 +1,6 @@
 import { computed, ref } from 'vue'
 import type { HubQueueGroup } from '#ghfs/rpc-types'
+import { useHubState } from './useHubState'
 import { useOnlineState } from './useOnlineState'
 import { useRpc } from './useRpc'
 
@@ -56,10 +57,14 @@ export function useHubQueue() {
     }
   }
 
-  const groupedEntries = computed(() => groups.value
-    .map(g => ({ ...g, total: totalFor(g) }))
-    .filter(g => g.total > 0),
-  )
+  const hub = useHubState()
+  const groupedEntries = computed(() => {
+    const hidden = hub.excludedIds.value
+    return groups.value
+      .filter(g => !hidden.has(g.projectId))
+      .map(g => ({ ...g, total: totalFor(g) }))
+      .filter(g => g.total > 0)
+  })
 
   const totalCount = computed(() => groupedEntries.value.reduce((sum, g) => sum + g.total, 0))
 
diff --git a/ui/composables/useHubRecent.ts b/ui/composables/useHubRecent.ts
index 650506f..ae09ffa 100644
--- a/ui/composables/useHubRecent.ts
+++ b/ui/composables/useHubRecent.ts
@@ -1,6 +1,7 @@
 import { computed, ref } from 'vue'
 import type { HubRecentItem } from '#ghfs/rpc-types'
 import { useActiveProjectId, useAppState } from './useAppState'
+import { useHubState } from './useHubState'
 import { useProjectPayload } from './useProjectPayload'
 import { useRpc } from './useRpc'
 
@@ -15,6 +16,14 @@ export function recentItemKey(item: Pick<HubRecentItem, 'projectId' | 'kind' | '
 
 export function useHubRecent() {
   const payload = useProjectPayload()
+  const hub = useHubState()
+  // Hide items belonging to projects the user has excluded from the hub.
+  const visibleItems = computed<HubRecentItem[]>(() => {
+    const hidden = hub.excludedIds.value
+    if (hidden.size === 0)
+      return items.value
+    return items.value.filter(it => !hidden.has(it.projectId))
+  })
 
   async function load(limit = 100) {
     loading.value = true
@@ -39,7 +48,7 @@ export function useHubRecent() {
   }
 
   return {
-    items: computed(() => items.value),
+    items: visibleItems,
     loading: computed(() => loading.value),
     error: computed(() => error.value),
     selectedKey,
diff --git a/ui/composables/useHubState.ts b/ui/composables/useHubState.ts
index 8d12a29..11a4195 100644
--- a/ui/composables/useHubState.ts
+++ b/ui/composables/useHubState.ts
@@ -1,13 +1,28 @@
-import { ref, shallowRef } from 'vue'
+import { computed, ref, shallowRef } from 'vue'
 import type { GhfsCapabilities, ProjectSummary } from '#ghfs/rpc-types'
 
 const capabilities = shallowRef<GhfsCapabilities | null>(null)
+// The complete project list (including projects the user has excluded). Most
+// hub surfaces should use `visibleProjects`; `projects` is retained for lookups
+// and routing where an excluded-but-still-enabled project must still resolve.
 const projects = shallowRef<ProjectSummary[]>([])
 const hubRoots = ref<string[]>([])
 const launchCwd = ref<string | null>(null)
 const launchCwdInRoots = ref<boolean>(true)
 const loading = ref(false)
 
+// Projects shown on hub surfaces (home grid, aggregates, switcher, nav).
+const visibleProjects = computed<ProjectSummary[]>(() => projects.value.filter(p => !p.excluded))
+// Projects the user has hidden from the hub — surfaced in settings to restore.
+const excludedProjects = computed<ProjectSummary[]>(() => projects.value.filter(p => p.excluded))
+// Ids of excluded projects, for filtering aggregate feeds (recent/todo/queue).
+const excludedIds = computed<Set<string>>(() => new Set(excludedProjects.value.map(p => p.id)))
+
+// Id of the hub-home project card that currently has keyboard focus, used by
+// the `hub.exclude-project` / `hub.sync-project` commands. Null when no card
+// is focused (e.g. focus moved to the palette or elsewhere).
+const focusedProjectId = ref<string | null>(null)
+
 /**
  * Order projects by recency: most-recently-active first (by item
  * `updatedAt`), then by last sync time, then by repo name. Projects with
@@ -40,10 +55,17 @@ export function useHubState() {
   return {
     capabilities,
     projects,
+    visibleProjects,
+    excludedProjects,
+    excludedIds,
+    focusedProjectId,
     hubRoots,
     launchCwd,
     launchCwdInRoots,
     loading,
+    setFocusedProjectId(id: string | null) {
+      focusedProjectId.value = id
+    },
     setCapabilities(next: GhfsCapabilities) {
       capabilities.value = next
       projects.value = sortProjectsByActivity(next.projects)
diff --git a/ui/composables/useHubTodos.ts b/ui/composables/useHubTodos.ts
index d187692..49a2765 100644
--- a/ui/composables/useHubTodos.ts
+++ b/ui/composables/useHubTodos.ts
@@ -3,6 +3,7 @@ import type { HubTodoItem } from '#ghfs/rpc-types'
 import type { IssueKind } from '../../src/types/issue'
 import type { ListItem } from '../types/list-item'
 import { listItemKey } from '../types/list-item'
+import { useHubState } from './useHubState'
 import { useRpc } from './useRpc'
 
 const items = ref<HubTodoItem[]>([])
@@ -27,6 +28,8 @@ function toListItem(it: HubTodoItem): ListItem {
 }
 
 export function useHubTodos() {
+  const hub = useHubState()
+
   async function load() {
     loading.value = true
     error.value = null
@@ -42,7 +45,14 @@ export function useHubTodos() {
     }
   }
 
-  const listItems = computed<ListItem[]>(() => items.value.map(toListItem))
+  // Hide todos belonging to projects the user has excluded from the hub.
+  const visibleItems = computed<HubTodoItem[]>(() => {
+    const hidden = hub.excludedIds.value
+    if (hidden.size === 0)
+      return items.value
+    return items.value.filter(it => !hidden.has(it.projectId))
+  })
+  const listItems = computed<ListItem[]>(() => visibleItems.value.map(toListItem))
   const filteredListItems = computed<ListItem[]>(() => listItems.value.filter(it => it.kind === kind.value))
 
   const counts = computed(() => {
diff --git a/ui/composables/useHubUiState.ts b/ui/composables/useHubUiState.ts
index c091081..b718977 100644
--- a/ui/composables/useHubUiState.ts
+++ b/ui/composables/useHubUiState.ts
@@ -1,4 +1,5 @@
 import { ref } from 'vue'
+import { useAppState } from './useAppState'
 import { useHubState } from './useHubState'
 import { useOnlineState } from './useOnlineState'
 import { useRpc } from './useRpc'
@@ -57,7 +58,7 @@ export async function syncAllProjects(): Promise<void> {
     return
   if (offline.value)
     return
-  const targets = hub.projects.value.filter(p => p.hasToken)
+  const targets = hub.visibleProjects.value.filter(p => p.hasToken)
   if (targets.length === 0)
     return
   ui.setSyncingAll(true)
@@ -73,3 +74,37 @@ export async function syncAllProjects(): Promise<void> {
     ui.setSyncingAll(false)
   }
 }
+
+/**
+ * Trigger a sync for a single project from the hub (e.g. the project card's
+ * context menu). Sets the project's syncing flag eagerly so the card shows a
+ * spinner immediately; live progress events take over from there, and
+ * `onSyncComplete` clears the flag + refreshes the project list.
+ */
+export async function syncProject(projectId: string): Promise<void> {
+  const rpc = useRpc()
+  const { offline } = useOnlineState()
+  const state = useAppState(projectId)
+  if (offline.value)
+    return
+  if (state.syncing.value)
+    return
+  state.setSyncing(true)
+  state.setError(null)
+  try {
+    await rpc.$call('ghfs:trigger-sync', projectId, {})
+  }
+  catch (error) {
+    state.setError(`Sync failed: ${(error as Error).message}`)
+    state.setSyncing(false)
+  }
+}
+
+/**
+ * Hide or restore a project on the hub. The server persists the change and
+ * broadcasts `onProjectsChange`, so every client refetches the project list
+ * (which carries the updated `excluded` flag) and the card appears/disappears.
+ */
+export async function setProjectExcluded(projectId: string, excluded: boolean): Promise<void> {
+  await useRpc().$call('ghfs:hub-set-excluded', projectId, excluded)
+}
diff --git a/ui/composables/useWhenContext.ts b/ui/composables/useWhenContext.ts
index 2af7970..456b88a 100644
--- a/ui/composables/useWhenContext.ts
+++ b/ui/composables/useWhenContext.ts
@@ -42,6 +42,7 @@ export interface WhenContext extends Record<string, unknown> {
   hubQueueTotal: number
   hubProjectsCount: number
   hasActiveProjectId: boolean
+  hubHasFocusedProject: boolean
   anyOverlayOpen: boolean
   onCardsPage: boolean
   cardsHasPile: boolean
@@ -111,7 +112,7 @@ export function useWhenContext(): ComputedRef<WhenContext> {
         ? recentSearch.value.trim().length > 0
         : state.value.filters.search.trim().length > 0,
       hasToken: state.value.payload.value?.repo.hasToken ?? false,
-      hasSyncableProjects: hub.projects.value.some(p => p.hasToken),
+      hasSyncableProjects: hub.visibleProjects.value.some(p => p.hasToken),
       syncing: state.value.syncing.value,
       syncingAll: hubUi.syncingAll.value,
       executing: state.value.executing.value,
@@ -127,8 +128,9 @@ export function useWhenContext(): ComputedRef<WhenContext> {
       hubQueueDrawerOpen,
       hubExecuteAllConfirmOpen,
       hubQueueTotal: hubQueueTotal.value,
-      hubProjectsCount: hub.projects.value.length,
+      hubProjectsCount: hub.visibleProjects.value.length,
       hasActiveProjectId: Boolean(activeId.value),
+      hubHasFocusedProject: Boolean(hub.focusedProjectId.value),
       // NB: cardsCommentDialogOpen is deliberately *not* in anyOverlayOpen.
       // The cards comment dialog is a Reka UiModal that handles its own
       // Escape via closeOnEscape, so propagating Escape to panel.close (which