@nextclaw/ui 0.15.18 → 0.15.20

package/src/features/chat/features/input/hooks/__tests__/use-chat-input-surface-state.test.tsx

@@ -9,6 +9,14 @@ const usePanelAppsMock = vi.hoisted(() =>
     isLoading: false,
   })),
 );
+const useProjectsMock = vi.hoisted(() =>
+  vi.fn(() => ({
+    data: { projects: [] },
+    error: null,
+    isFetching: false,
+    isLoading: false,
+  })),
+);
 const useServerPathSearchMock = vi.hoisted(() =>
   vi.fn(() => ({
     data: { entries: [] },
@@ -38,6 +46,9 @@ const useServerPathBrowseMock = vi.hoisted(() =>
 vi.mock('@/features/panel-apps', () => ({
   usePanelApps: usePanelAppsMock,
 }));
+vi.mock('@/shared/hooks/use-projects', () => ({
+  useProjects: useProjectsMock,
+}));
 vi.mock('@/shared/hooks/use-server-path-search', () => ({
   useServerPathSearch: useServerPathSearchMock,
 }));
@@ -68,6 +79,7 @@ function createHookParams() {
 
 beforeEach(() => {
   usePanelAppsMock.mockClear();
+  useProjectsMock.mockClear();
   useServerPathBrowseMock.mockClear();
   useServerPathSearchMock.mockClear();
 });
@@ -84,6 +96,7 @@ it('browses nested folders while reserving search for project-wide queries', ()
       start: 0,
     }),
   );
+  expect(useProjectsMock).toHaveBeenLastCalledWith({ enabled: true });
   const filesItem = result.current.inputSurfaceState.panel?.items.find(
     (item) => item.selectionBehavior === 'navigate',
   );

package/src/features/chat/features/input/hooks/use-chat-input-surface-state.ts

@@ -10,11 +10,13 @@ import {
   CONTEXT_REFERENCE_TRIGGER_SPEC,
   createContextReferenceInputSurfacePlugin,
 } from '@/features/chat/features/input/input-surface-plugins/context-reference-plugin.utils';
+import type { ContextReferenceLocation } from '@/features/chat/features/input/input-surface-plugins/chat-input-product-plugin-adapters.types';
 import {
   createSlashCommandInputSurfacePlugin,
   type ChatSlashCommandDescriptor,
 } from '@/features/chat/features/input/input-surface-plugins/slash-command-plugin.utils';
 import type { ChatInputBarAdapterTexts, ChatSkillRecord } from '@/features/chat/types/chat-input-bar.types';
+import { useProjects } from '@/shared/hooks/use-projects';
 import { useServerPathBrowse } from '@/shared/hooks/use-server-path-browse';
 import { useServerPathSearch } from '@/shared/hooks/use-server-path-search';
 import type { ServerPathEntryView, ServerPathSearchEntryView } from '@/shared/lib/api';
@@ -39,7 +41,7 @@ type UseChatInputSurfaceStateParams = {
 function buildChatInputSurfacePlugins(params: {
   commands: readonly ChatSlashCommandDescriptor[];
   language: I18nLanguage;
-  onNavigate: (path: string | null) => void;
+  onNavigate: (location: ContextReferenceLocation) => void;
   onSelectPanelApp: (appId: string) => void;
   onSelectSkill: (skillRef: string) => void;
   slashTexts: ChatInputSurfaceSlashTexts;
@@ -105,6 +107,15 @@ function buildChatInputSurfacePlugins(params: {
           parentLabel: t('chatContextReferenceParent', language),
           parentDescription: t('chatContextReferenceParentDescription', language),
           parentHintLabel: t('chatContextReferenceParentHint', language),
+          projectDescription: t('chatContextReferenceProjectDescription', language),
+          projectPathLabel: t('chatContextReferenceProjectPath', language),
+          projectSectionLabel: t('chatContextReferenceProjectSection', language),
+          projectSubtitle: t('chatContextReferenceProjectType', language),
+          projectsDescription: t('chatContextReferenceProjectsDescription', language),
+          projectsHintLabel: t('chatContextReferenceProjectsHint', language),
+          projectsLabel: t('chatContextReferenceProjectsLabel', language),
+          projectsLoadFailedLabel: t('chatContextReferenceProjectsLoadFailed', language),
+          projectsSubtitle: t('chatContextReferenceProjectsType', language),
           projectRootLabel: t('chatContextReferenceProjectRoot', language),
           searchFailedLabel: t('chatContextReferenceSearchFailed', language),
           workspaceSectionLabel: t('chatContextReferenceWorkspaceSection', language),
@@ -150,7 +161,9 @@ export function useChatInputSurfaceState(params: UseChatInputSurfaceStateParams)
     skillRecords,
     commands,
   } = params;
-  const [referencePath, setReferencePath] = useState<string | null>(null);
+  const [referenceLocation, setReferenceLocation] = useState<ContextReferenceLocation>({
+    view: 'root',
+  });
   const [inputSurfaceTrigger, setInputSurfaceTriggerState] = useState<ChatInputSurfaceTrigger | null>(null);
   const inputSurfaceTriggerSignatureRef = useRef('null');
   const setInputSurfaceTrigger = useCallback((nextTrigger: ChatInputSurfaceTrigger | null): void => {
@@ -158,23 +171,25 @@ export function useChatInputSurfaceState(params: UseChatInputSurfaceStateParams)
     if (inputSurfaceTriggerSignatureRef.current === nextSignature) return;
     inputSurfaceTriggerSignatureRef.current = nextSignature;
     if (!nextTrigger) {
-      setReferencePath(null);
+      setReferenceLocation({ view: 'root' });
     }
     setInputSurfaceTriggerState(nextTrigger);
   }, []);
   const isContextReferenceTrigger = inputSurfaceTrigger?.key === CONTEXT_REFERENCE_TRIGGER_SPEC.key;
+  const referencePath = referenceLocation.view === 'files' ? referenceLocation.path : '';
   const deferredReferenceQuery = useDeferredValue(
     isContextReferenceTrigger ? inputSurfaceTrigger.query : '',
   );
   const isBrowsingServerPaths = Boolean(
     isContextReferenceTrigger &&
     projectRoot &&
-    referencePath !== null &&
+    referenceLocation.view === 'files' &&
     !deferredReferenceQuery.trim(),
   );
   const shouldSearchServerPaths = Boolean(
     isContextReferenceTrigger &&
     projectRoot &&
+    referenceLocation.view !== 'projects' &&
     deferredReferenceQuery.trim(),
   );
   const serverPathBrowse = useServerPathBrowse({
@@ -193,7 +208,7 @@ export function useChatInputSurfaceState(params: UseChatInputSurfaceStateParams)
     () => isBrowsingServerPaths
       ? buildBrowsedReferenceEntries({
           entries: serverPathBrowse.data?.entries ?? [],
-          parentRelativePath: referencePath ?? '',
+          parentRelativePath: referencePath,
         })
       : serverPathSearch.data?.entries ?? [],
     [
@@ -207,12 +222,13 @@ export function useChatInputSurfaceState(params: UseChatInputSurfaceStateParams)
     isContextReferenceTrigger ||
     inputSurfaceTrigger?.key === CHAT_INPUT_SURFACE_SLASH_TRIGGER_SPEC.key;
   const panelApps = usePanelApps({ enabled: shouldLoadPanelApps });
+  const projects = useProjects({ enabled: isContextReferenceTrigger });
 
   const inputSurfacePlugins = useMemo(
     () => buildChatInputSurfacePlugins({
       commands,
       language,
-      onNavigate: setReferencePath,
+      onNavigate: setReferenceLocation,
       onSelectPanelApp,
       onSelectSkill,
       slashTexts: itemTexts.slashTexts,
@@ -229,12 +245,15 @@ export function useChatInputSurfaceState(params: UseChatInputSurfaceStateParams)
     () => resolveChatInputSurfaceState({
       data: {
         isPanelAppsLoading: panelApps.isLoading || panelApps.isFetching,
+        isProjectsLoading: projects.isLoading || projects.isFetching,
         isServerPathSearchLoading: activeServerPathQuery.isLoading || activeServerPathQuery.isFetching,
         isSkillsLoading,
         panelApps: panelApps.data?.entries ?? [],
         projectRoot,
+        projects: projects.data?.projects ?? [],
+        projectsError: projects.error instanceof Error ? projects.error.message : null,
         recentSkillValues,
-        referencePath,
+        referenceLocation,
         serverPathEntries,
         serverPathSearchError: activeServerPathQuery.error instanceof Error
           ? activeServerPathQuery.error.message
@@ -251,10 +270,14 @@ export function useChatInputSurfaceState(params: UseChatInputSurfaceStateParams)
       panelApps.isFetching,
       panelApps.isLoading,
       projectRoot,
+      projects.data?.projects,
+      projects.error,
+      projects.isFetching,
+      projects.isLoading,
       activeServerPathQuery.error,
       activeServerPathQuery.isFetching,
       activeServerPathQuery.isLoading,
-      referencePath,
+      referenceLocation,
       serverPathEntries,
       isSkillsLoading,
       recentSkillValues,

package/src/features/chat/features/input/input-surface-plugins/__tests__/context-reference-plugin.test.ts

@@ -4,7 +4,8 @@ import {
   CONTEXT_REFERENCE_TRIGGER_SPEC,
   createContextReferenceInputSurfacePlugin,
 } from '@/features/chat/features/input/input-surface-plugins/context-reference-plugin.utils';
-import type { PanelAppEntryView } from '@/shared/lib/api';
+import type { ContextReferenceLocation } from '@/features/chat/features/input/input-surface-plugins/chat-input-product-plugin-adapters.types';
+import type { PanelAppEntryView, ProjectView } from '@/shared/lib/api';
 
 function createPanelApp(): PanelAppEntryView {
   return {
@@ -25,6 +26,15 @@ function createPanelApp(): PanelAppEntryView {
   };
 }
 
+function createProject(): ProjectView {
+  return {
+    name: 'NextClaw',
+    rootPath: '/tmp/nextclaw',
+    createdAt: '2026-07-28T00:00:00.000Z',
+    updatedAt: '2026-07-28T00:00:00.000Z',
+  };
+}
+
 function createPlugin(onNavigate = vi.fn()) {
   return createContextReferenceInputSurfacePlugin({
     itemTexts: {
@@ -43,6 +53,15 @@ function createPlugin(onNavigate = vi.fn()) {
         parentLabel: 'Up one folder',
         parentDescription: 'Browse parent',
         parentHintLabel: 'Enter to browse parent',
+        projectDescription: 'Project context',
+        projectPathLabel: 'Project path',
+        projectSectionLabel: 'Projects',
+        projectSubtitle: 'Project',
+        projectsDescription: 'Browse registered projects',
+        projectsHintLabel: 'Enter to browse projects',
+        projectsLabel: 'Projects',
+        projectsLoadFailedLabel: 'Projects failed',
+        projectsSubtitle: 'Project Context',
         projectRootLabel: 'Project directory',
         searchFailedLabel: 'Search failed',
         workspaceSectionLabel: 'Files & Folders',
@@ -65,15 +84,18 @@ function createPlugin(onNavigate = vi.fn()) {
   });
 }
 
-function createData(referencePath: string | null = null) {
+function createData(referenceLocation: ContextReferenceLocation = { view: 'root' }) {
   return {
     isPanelAppsLoading: false,
+    isProjectsLoading: false,
     isServerPathSearchLoading: false,
     isSkillsLoading: false,
     panelApps: [createPanelApp()],
     projectRoot: '/tmp/project',
+    projects: [createProject()],
+    projectsError: null,
     recentSkillValues: [],
-    referencePath,
+    referenceLocation,
     serverPathEntries: [
       {
         name: 'server-path.ts',
@@ -98,7 +120,7 @@ function createData(referencePath: string | null = null) {
 }
 
 describe('context reference input surface plugin', () => {
-  it('shows Files & Folders and panel apps in the root @ menu', () => {
+  it('shows Files & Folders, Projects, and panel apps in the root @ menu', () => {
     const state = resolveChatInputSurfaceState({
       plugins: [createPlugin()],
       trigger: {
@@ -116,6 +138,11 @@ describe('context reference input surface plugin', () => {
         icon: 'files',
         selectionBehavior: 'navigate',
       }),
+      expect.objectContaining({
+        title: 'Projects',
+        icon: 'project',
+        selectionBehavior: 'navigate',
+      }),
       expect.objectContaining({
         key: 'panel-app:task-board',
         tokenKind: 'panel_app',
@@ -133,7 +160,7 @@ describe('context reference input surface plugin', () => {
         start: 0,
         end: 7,
       },
-      data: createData(''),
+      data: createData({ view: 'files', path: '' }),
     });
 
     expect(state.panel?.items.slice(1)).toEqual([
@@ -173,7 +200,7 @@ describe('context reference input surface plugin', () => {
 
     state.panel?.onSelectItem?.(item!);
 
-    expect(onNavigate).toHaveBeenCalledWith('');
+    expect(onNavigate).toHaveBeenCalledWith({ view: 'files', path: '' });
     expect(item).not.toHaveProperty('tokenKind');
   });
 
@@ -187,7 +214,7 @@ describe('context reference input surface plugin', () => {
         start: 0,
         end: 1,
       },
-      data: createData(''),
+      data: createData({ view: 'files', path: '' }),
     });
     const directoryItem = rootState.panel?.items.find((item) => item.title === 'docs');
 
@@ -197,7 +224,7 @@ describe('context reference input surface plugin', () => {
     });
     expect(directoryItem?.tokenKind).toBeUndefined();
     rootState.panel?.onSelectItem?.(directoryItem!);
-    expect(onNavigate).toHaveBeenCalledWith('docs');
+    expect(onNavigate).toHaveBeenCalledWith({ view: 'files', path: 'docs' });
 
     const nestedState = resolveChatInputSurfaceState({
       plugins: [createPlugin(onNavigate)],
@@ -207,7 +234,7 @@ describe('context reference input surface plugin', () => {
         start: 0,
         end: 1,
       },
-      data: createData('docs'),
+      data: createData({ view: 'files', path: 'docs' }),
     });
     expect(nestedState.panel?.items).toEqual(expect.arrayContaining([
       expect.objectContaining({
@@ -222,4 +249,47 @@ describe('context reference input surface plugin', () => {
       }),
     ]));
   });
+
+  it('opens the project view and builds semantic project tokens', () => {
+    const onNavigate = vi.fn();
+    const rootState = resolveChatInputSurfaceState({
+      plugins: [createPlugin(onNavigate)],
+      trigger: {
+        ...CONTEXT_REFERENCE_TRIGGER_SPEC,
+        query: '',
+        start: 0,
+        end: 1,
+      },
+      data: createData(),
+    });
+    const projectsItem = rootState.panel?.items.find((item) => item.title === 'Projects');
+
+    rootState.panel?.onSelectItem?.(projectsItem!);
+    expect(onNavigate).toHaveBeenCalledWith({ view: 'projects' });
+
+    const projectsState = resolveChatInputSurfaceState({
+      plugins: [createPlugin(onNavigate)],
+      trigger: {
+        ...CONTEXT_REFERENCE_TRIGGER_SPEC,
+        query: 'next',
+        start: 0,
+        end: 5,
+      },
+      data: createData({ view: 'projects' }),
+    });
+
+    expect(projectsState.panel?.items).toEqual([
+      expect.objectContaining({
+        title: 'Back',
+        selectionBehavior: 'navigate',
+      }),
+      expect.objectContaining({
+        title: 'NextClaw',
+        icon: 'project',
+        tokenKind: 'project',
+        tokenKey: '/tmp/nextclaw',
+        detailLines: ['Project path: /tmp/nextclaw'],
+      }),
+    ]);
+  });
 });

package/src/features/chat/features/input/input-surface-plugins/__tests__/slash-command-plugin.test.ts

@@ -86,6 +86,7 @@ describe('createSlashCommandInputSurfacePlugin', () => {
     const state = resolveChatInputSurfaceState({
       data: {
         isPanelAppsLoading: false,
+        isProjectsLoading: false,
         isServerPathSearchLoading: false,
         isSkillsLoading: false,
         panelApps: [
@@ -96,8 +97,10 @@ describe('createSlashCommandInputSurfacePlugin', () => {
           }),
         ],
         projectRoot: '/tmp/project',
+        projects: [],
+        projectsError: null,
         recentSkillValues: [],
-        referencePath: null,
+        referenceLocation: { view: 'root' },
         serverPathEntries: [],
         serverPathSearchError: null,
         skillRecords: [
@@ -153,12 +156,15 @@ describe('createSlashCommandInputSurfacePlugin', () => {
     const state = resolveChatInputSurfaceState({
       data: {
         isPanelAppsLoading: false,
+        isProjectsLoading: false,
         isServerPathSearchLoading: false,
         isSkillsLoading: false,
         panelApps: [],
         projectRoot: '/tmp/project',
+        projects: [],
+        projectsError: null,
         recentSkillValues: [],
-        referencePath: null,
+        referenceLocation: { view: 'root' },
         serverPathEntries: [],
         serverPathSearchError: null,
         skillRecords: [
@@ -202,12 +208,15 @@ describe('createSlashCommandInputSurfacePlugin', () => {
     const state = resolveChatInputSurfaceState({
       data: {
         isPanelAppsLoading: false,
+        isProjectsLoading: false,
         isServerPathSearchLoading: false,
         isSkillsLoading: false,
         panelApps: [],
         projectRoot: '/tmp/project',
+        projects: [],
+        projectsError: null,
         recentSkillValues: [],
-        referencePath: null,
+        referenceLocation: { view: 'root' },
         serverPathEntries: [],
         serverPathSearchError: null,
         skillRecords: [],
@@ -233,6 +242,7 @@ describe('createSlashCommandInputSurfacePlugin', () => {
     const state = resolveChatInputSurfaceState({
       data: {
         isPanelAppsLoading: false,
+        isProjectsLoading: false,
         isServerPathSearchLoading: false,
         isSkillsLoading: false,
         panelApps: [
@@ -243,8 +253,10 @@ describe('createSlashCommandInputSurfacePlugin', () => {
           }),
         ],
         projectRoot: '/tmp/project',
+        projects: [],
+        projectsError: null,
         recentSkillValues: [],
-        referencePath: null,
+        referenceLocation: { view: 'root' },
         serverPathEntries: [],
         serverPathSearchError: null,
         skillRecords: [],

package/src/features/chat/features/input/input-surface-plugins/chat-input-product-plugin-adapters.types.ts

@@ -1,14 +1,22 @@
 import type { ChatSkillRecord } from '@/features/chat/types/chat-input-bar.types';
-import type { PanelAppEntryView, ServerPathSearchEntryView } from '@/shared/lib/api';
+import type { PanelAppEntryView, ProjectView, ServerPathSearchEntryView } from '@/shared/lib/api';
+
+export type ContextReferenceLocation =
+  | { view: 'root' }
+  | { view: 'files'; path: string }
+  | { view: 'projects' };
 
 export type ChatInputProductPluginData = {
   isPanelAppsLoading: boolean;
+  isProjectsLoading: boolean;
   isServerPathSearchLoading: boolean;
   isSkillsLoading: boolean;
   panelApps: readonly PanelAppEntryView[];
   projectRoot: string;
+  projects: readonly ProjectView[];
+  projectsError: string | null;
   recentSkillValues: readonly string[];
-  referencePath: string | null;
+  referenceLocation: ContextReferenceLocation;
   serverPathEntries: readonly ServerPathSearchEntryView[];
   serverPathSearchError: string | null;
   skillRecords: readonly ChatSkillRecord[];

package/src/features/chat/features/input/input-surface-plugins/context-reference-items.utils.ts

@@ -0,0 +1,240 @@
+import type { ChatInputSurfaceItem } from '@nextclaw/agent-chat-ui';
+import {
+  CHAT_PROJECT_TOKEN_KIND,
+  CHAT_WORKSPACE_DIRECTORY_TOKEN_KIND,
+  CHAT_WORKSPACE_FILE_TOKEN_KIND,
+} from '@nextclaw/shared';
+import type { ProjectView, ServerPathSearchEntryView } from '@/shared/lib/api';
+import type { ContextReferenceLocation } from './chat-input-product-plugin-adapters.types';
+import {
+  resolveInputSurfaceMatchTier,
+  scoreInputSurfaceSearchCandidate,
+} from './input-surface-search.utils';
+
+export const FILES_NAVIGATION_ITEM_KEY = 'context-reference:navigate:files';
+export const PROJECTS_NAVIGATION_ITEM_KEY = 'context-reference:navigate:projects';
+export const ROOT_NAVIGATION_ITEM_KEY = 'context-reference:navigate:root';
+
+const WORKSPACE_SECTION_KEY = 'workspace';
+const PROJECT_SECTION_KEY = 'projects';
+
+export type ContextReferenceInputSurfaceTexts = {
+  backLabel: string;
+  backDescription: string;
+  backHintLabel: string;
+  currentDirectoryLabel: string;
+  directoryDescription: string;
+  fileDescription: string;
+  filesDescription: string;
+  filesHintLabel: string;
+  filesLabel: string;
+  filesSubtitle: string;
+  panelAppSectionLabel: string;
+  parentLabel: string;
+  parentDescription: string;
+  parentHintLabel: string;
+  projectDescription: string;
+  projectPathLabel: string;
+  projectSectionLabel: string;
+  projectSubtitle: string;
+  projectsDescription: string;
+  projectsHintLabel: string;
+  projectsLabel: string;
+  projectsLoadFailedLabel: string;
+  projectsSubtitle: string;
+  projectRootLabel: string;
+  searchFailedLabel: string;
+  workspaceSectionLabel: string;
+};
+
+function resolveProjectLabel(projectRoot: string): string {
+  return projectRoot.split(/[\\/]+/).filter(Boolean).at(-1) ?? projectRoot;
+}
+
+function buildPathPreview(params: {
+  kind: 'directory' | 'file';
+  projectRoot: string;
+  relativePath: string;
+}) {
+  const { kind, projectRoot, relativePath } = params;
+  const pathSegments = relativePath.split('/').filter(Boolean);
+  return {
+    rootLabel: resolveProjectLabel(projectRoot),
+    segments: pathSegments.map((label, index) => ({
+      label,
+      kind: index === pathSegments.length - 1 ? kind : 'directory' as const,
+    })),
+  };
+}
+
+export function buildProjectReferenceItems(params: {
+  projects: readonly ProjectView[];
+  query: string;
+  texts: ContextReferenceInputSurfaceTexts;
+}): ChatInputSurfaceItem[] {
+  const collator = new Intl.Collator(undefined, { sensitivity: 'base', numeric: true });
+  return params.projects
+    .map((project, order) => ({
+      order,
+      project,
+      score: scoreInputSurfaceSearchCandidate(
+        {
+          id: project.rootPath,
+          label: project.name,
+          description: project.rootPath,
+          aliases: project.template ? [project.template] : [],
+        },
+        params.query,
+      ),
+    }))
+    .filter(({ score }) => score > 0)
+    .sort((left, right) => {
+      const leftTier = resolveInputSurfaceMatchTier(left.score);
+      const rightTier = resolveInputSurfaceMatchTier(right.score);
+      if (rightTier !== leftTier) {
+        return rightTier - leftTier;
+      }
+      if (right.score !== left.score) {
+        return right.score - left.score;
+      }
+      return collator.compare(left.project.name, right.project.name) || left.order - right.order;
+    })
+    .map(({ project }) => ({
+      key: `context-reference:project:${project.rootPath}`,
+      icon: 'project',
+      title: project.name,
+      subtitle: params.texts.projectSubtitle,
+      description: params.texts.projectDescription,
+      detailLines: [`${params.texts.projectPathLabel}: ${project.rootPath}`],
+      sectionKey: PROJECT_SECTION_KEY,
+      sectionLabel: params.texts.projectSectionLabel,
+      value: project.rootPath,
+      tokenKind: CHAT_PROJECT_TOKEN_KIND,
+      tokenKey: project.rootPath,
+    }));
+}
+
+export function buildWorkspaceReferenceItems(params: {
+  entries: readonly ServerPathSearchEntryView[];
+  navigateDirectories: boolean;
+  projectRoot: string;
+  texts: ContextReferenceInputSurfaceTexts;
+}): ChatInputSurfaceItem[] {
+  const projectLabel = resolveProjectLabel(params.projectRoot);
+  return params.entries.map((entry) => {
+    const navigates = params.navigateDirectories && entry.kind === 'directory';
+    return {
+      key: `workspace:${entry.kind}:${entry.relativePath}`,
+      icon: entry.kind === 'directory' ? 'folder' : 'file',
+      title: entry.name,
+      subtitle: entry.parentRelativePath || projectLabel,
+      description: entry.kind === 'directory'
+        ? params.texts.directoryDescription
+        : params.texts.fileDescription,
+      detailLines: [
+        `${params.texts.projectRootLabel}: ${params.projectRoot}`,
+        entry.relativePath,
+      ],
+      sectionKey: WORKSPACE_SECTION_KEY,
+      sectionLabel: params.texts.workspaceSectionLabel,
+      value: entry.relativePath,
+      tokenKind: navigates
+        ? undefined
+        : entry.kind === 'directory'
+          ? CHAT_WORKSPACE_DIRECTORY_TOKEN_KIND
+          : CHAT_WORKSPACE_FILE_TOKEN_KIND,
+      tokenKey: navigates ? undefined : entry.relativePath,
+      selectionBehavior: navigates ? 'navigate' : undefined,
+      pathPreview: buildPathPreview({
+        kind: entry.kind,
+        projectRoot: params.projectRoot,
+        relativePath: entry.relativePath,
+      }),
+    } satisfies ChatInputSurfaceItem;
+  });
+}
+
+export function buildCurrentDirectoryReferenceItem(params: {
+  projectRoot: string;
+  referencePath: string;
+  texts: ContextReferenceInputSurfaceTexts;
+}): ChatInputSurfaceItem {
+  const { projectRoot, referencePath, texts } = params;
+  const title = referencePath.split('/').filter(Boolean).at(-1) ?? referencePath;
+  return {
+    key: `context-reference:current-directory:${referencePath}`,
+    icon: 'folder',
+    title: texts.currentDirectoryLabel,
+    subtitle: title,
+    description: texts.directoryDescription,
+    detailLines: [
+      `${texts.projectRootLabel}: ${projectRoot}`,
+      referencePath,
+    ],
+    sectionKey: WORKSPACE_SECTION_KEY,
+    sectionLabel: texts.workspaceSectionLabel,
+    value: referencePath,
+    tokenKind: CHAT_WORKSPACE_DIRECTORY_TOKEN_KIND,
+    tokenKey: referencePath,
+    pathPreview: buildPathPreview({
+      kind: 'directory',
+      projectRoot,
+      relativePath: referencePath,
+    }),
+  };
+}
+
+export function buildFilesNavigationItem(
+  texts: ContextReferenceInputSurfaceTexts,
+): ChatInputSurfaceItem {
+  return {
+    key: FILES_NAVIGATION_ITEM_KEY,
+    icon: 'files',
+    title: texts.filesLabel,
+    subtitle: texts.filesSubtitle,
+    description: texts.filesDescription,
+    detailLines: [],
+    hintLabel: texts.filesHintLabel,
+    selectionBehavior: 'navigate',
+  };
+}
+
+export function buildProjectsNavigationItem(
+  texts: ContextReferenceInputSurfaceTexts,
+): ChatInputSurfaceItem {
+  return {
+    key: PROJECTS_NAVIGATION_ITEM_KEY,
+    icon: 'project',
+    title: texts.projectsLabel,
+    subtitle: texts.projectsSubtitle,
+    description: texts.projectsDescription,
+    detailLines: [],
+    hintLabel: texts.projectsHintLabel,
+    selectionBehavior: 'navigate',
+  };
+}
+
+function resolveParentReferencePath(referencePath: string): string | null {
+  const segments = referencePath.split('/').filter(Boolean);
+  return segments.length === 0 ? null : segments.slice(0, -1).join('/');
+}
+
+export function buildBackNavigationItem(params: {
+  location: ContextReferenceLocation;
+  texts: ContextReferenceInputSurfaceTexts;
+}): ChatInputSurfaceItem {
+  const { location, texts } = params;
+  const referencePath = location.view === 'files' ? location.path : '';
+  const isRootView = location.view !== 'files' || !referencePath;
+  return {
+    key: ROOT_NAVIGATION_ITEM_KEY,
+    icon: 'back',
+    title: isRootView ? texts.backLabel : texts.parentLabel,
+    subtitle: '',
+    description: isRootView ? texts.backDescription : texts.parentDescription,
+    detailLines: [],
+    hintLabel: isRootView ? texts.backHintLabel : texts.parentHintLabel,
+    value: resolveParentReferencePath(referencePath) ?? '',
+    selectionBehavior: 'navigate',
+  };
+}