Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(web-studio): render L0/L1 sidecar metadata (#4519)

Zayn Jarvis30ef75ce0299
diff --git a/web-studio/package-lock.json b/web-studio/package-lock.json
index b673e85e4..d74dbc25e 100644
--- a/web-studio/package-lock.json
+++ b/web-studio/package-lock.json
@@ -66,7 +66,8 @@
"tailwind-merge": "^3.5.0",
"tailwindcss": "^4.1.18",
"three": "^0.183.2",
- "tw-animate-css": "^1.4.0"
+ "tw-animate-css": "^1.4.0",
+ "yaml": "^2.8.1"
},
"devDependencies": {
"@hey-api/openapi-ts": "^0.95.0",
@@ -15080,6 +15081,21 @@
"integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==",
"license": "ISC"
},
+ "node_modules/yaml": {
+ "version": "2.9.0",
+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
+ "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
+ "license": "ISC",
+ "bin": {
+ "yaml": "bin.mjs"
+ },
+ "engines": {
+ "node": ">= 14.6"
+ },
+ "funding": {
+ "url": "https://github.com/sponsors/eemeli"
+ }
+ },
"node_modules/yargs": {
"version": "17.7.2",
"resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz",
diff --git a/web-studio/package.json b/web-studio/package.json
index 7aa6c95bd..13ef1d129 100644
--- a/web-studio/package.json
+++ b/web-studio/package.json
@@ -76,7 +76,8 @@
"tailwind-merge": "^3.5.0",
"tailwindcss": "^4.1.18",
"three": "^0.183.2",
- "tw-animate-css": "^1.4.0"
+ "tw-animate-css": "^1.4.0",
+ "yaml": "^2.8.1"
},
"devDependencies": {
"@hey-api/openapi-ts": "^0.95.0",
diff --git a/web-studio/src/i18n/locales/en/resources.ts b/web-studio/src/i18n/locales/en/resources.ts
index 7516aa2e9..bba621f42 100644
--- a/web-studio/src/i18n/locales/en/resources.ts
+++ b/web-studio/src/i18n/locales/en/resources.ts
@@ -433,6 +433,18 @@ const resources = {
save: 'Save',
selectDirectoryContext: 'Select a chip to show folder context.',
unsupportedBinary: 'Binary files do not support text preview.',
+ yamlMetadata: {
+ ariaLabel: 'Directory metadata',
+ directory: 'Directory',
+ generatedBy: 'Generated by',
+ trigger: 'Trigger',
+ source: 'Source',
+ freshness: 'Freshness',
+ coverage: '{{sampled}} / {{total}} sampled',
+ unsampled: '{{count}} unsampled',
+ pendingChanges: 'Pending changes: {{count}}',
+ rawYaml: 'YAML metadata',
+ },
jsonl: {
collapse: 'Collapse',
dialogMode: 'Dialog mode',
diff --git a/web-studio/src/i18n/locales/zh-CN/resources.ts b/web-studio/src/i18n/locales/zh-CN/resources.ts
index a1785c323..93b18c62c 100644
--- a/web-studio/src/i18n/locales/zh-CN/resources.ts
+++ b/web-studio/src/i18n/locales/zh-CN/resources.ts
@@ -413,6 +413,18 @@ const resources = {
save: '保存',
selectDirectoryContext: '选择一个标签查看目录上下文。',
unsupportedBinary: '二进制文件不支持文本预览。',
+ yamlMetadata: {
+ ariaLabel: '目录元数据',
+ directory: '所属目录',
+ generatedBy: '生成组件',
+ trigger: '触发方式',
+ source: '来源',
+ freshness: '新鲜度',
+ coverage: '已采样 {{sampled}} / {{total}}',
+ unsampled: '{{count}} 条未采样',
+ pendingChanges: '待处理变更:{{count}}',
+ rawYaml: 'YAML 元数据',
+ },
jsonl: {
collapse: '收起',
dialogMode: '对话模式',
diff --git a/web-studio/src/lib/okf-markdown.test.ts b/web-studio/src/lib/okf-markdown.test.ts
new file mode 100644
index 000000000..c3100570e
--- /dev/null
+++ b/web-studio/src/lib/okf-markdown.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest'
+
+import { parseOkfSidecarMarkdown } from './okf-markdown'
+
+const sample = `---
+directory: viking://resources/openviking-contribute/
+generated_by:
+ component: SemanticProcessor
+ trigger: parent_refresh
+freshness:
+ total_entries: 4
+ sampled_entries: 4
+ unsampled_entries: 0
+ pending_child_changes: 0
+extensions:
+ ranking:
+ strategy: semantic
+---
+
+这是 OpenViking 相关项目的 PR 贡献规范集合。`
+
+describe('parseOkfSidecarMarkdown', () => {
+ it.each(['.abstract.md', '.overview.md'])(
+ 'separates valid OKF metadata from the Markdown body for %s',
+ (filename) => {
+ expect(
+ parseOkfSidecarMarkdown(
+ `viking://resources/openviking-contribute/${filename}`,
+ sample,
+ ),
+ ).toEqual({
+ body: '这是 OpenViking 相关项目的 PR 贡献规范集合。',
+ metadata: {
+ directory: 'viking://resources/openviking-contribute/',
+ freshness: {
+ pending_child_changes: 0,
+ sampled_entries: 4,
+ total_entries: 4,
+ unsampled_entries: 0,
+ },
+ generated_by: {
+ component: 'SemanticProcessor',
+ trigger: 'parent_refresh',
+ },
+ },
+ rawFrontmatter: [
+ '---',
+ 'directory: viking://resources/openviking-contribute/',
+ 'generated_by:',
+ ' component: SemanticProcessor',
+ ' trigger: parent_refresh',
+ 'freshness:',
+ ' total_entries: 4',
+ ' sampled_entries: 4',
+ ' unsampled_entries: 0',
+ ' pending_child_changes: 0',
+ 'extensions:',
+ ' ranking:',
+ ' strategy: semantic',
+ '---',
+ ].join('\n'),
+ })
+ },
+ )
+
+ it('does not reinterpret frontmatter in an ordinary Markdown file', () => {
+ expect(
+ parseOkfSidecarMarkdown(
+ 'viking://resources/openviking-contribute/README.md',
+ sample,
+ ),
+ ).toBeNull()
+ })
+
+ it('falls back to the original Markdown path for malformed metadata', () => {
+ expect(
+ parseOkfSidecarMarkdown(
+ 'viking://resources/openviking-contribute/.abstract.md',
+ sample.replace('sampled_entries: 4', 'sampled_entries: nope'),
+ ),
+ ).toBeNull()
+ })
+})
diff --git a/web-studio/src/lib/okf-markdown.ts b/web-studio/src/lib/okf-markdown.ts
new file mode 100644
index 000000000..13d4e398a
--- /dev/null
+++ b/web-studio/src/lib/okf-markdown.ts
@@ -0,0 +1,148 @@
+import { parse as parseYaml } from 'yaml'
+
+import { isDirectorySemanticSidecarUri } from './viking-uri'
+
+export interface OkfSourceMetadata {
+ kind: string
+ uri: string
+}
+
+export interface OkfGeneratedByMetadata {
+ component: string
+ trigger: string
+}
+
+export interface OkfFreshnessMetadata {
+ pending_child_changes: number
+ sampled_entries: number
+ total_entries: number
+ unsampled_entries: number
+}
+
+export interface OkfSidecarMetadata {
+ directory: string
+ freshness?: OkfFreshnessMetadata
+ generated_by?: OkfGeneratedByMetadata
+ source?: OkfSourceMetadata
+}
+
+export interface OkfSidecarDocument {
+ body: string
+ metadata: OkfSidecarMetadata
+ rawFrontmatter: string
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function nonEmptyString(value: unknown): string | null {
+ return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
+function nonNegativeInteger(value: unknown): number | null {
+ return typeof value === 'number' && Number.isInteger(value) && value >= 0
+ ? value
+ : null
+}
+
+function parseSource(value: unknown): OkfSourceMetadata | undefined | null {
+ if (value === undefined) return undefined
+ if (!isRecord(value)) return null
+ const kind = nonEmptyString(value.kind)
+ const uri = nonEmptyString(value.uri)
+ return kind && uri ? { kind, uri } : null
+}
+
+function parseGeneratedBy(
+ value: unknown,
+): OkfGeneratedByMetadata | undefined | null {
+ if (value === undefined) return undefined
+ if (!isRecord(value)) return null
+ const component = nonEmptyString(value.component)
+ const trigger = nonEmptyString(value.trigger)
+ return component && trigger ? { component, trigger } : null
+}
+
+function parseFreshness(
+ value: unknown,
+): OkfFreshnessMetadata | undefined | null {
+ if (value === undefined) return undefined
+ if (!isRecord(value)) return null
+
+ const totalEntries = nonNegativeInteger(value.total_entries)
+ const sampledEntries = nonNegativeInteger(value.sampled_entries)
+ const unsampledEntries = nonNegativeInteger(value.unsampled_entries)
+ const pendingChildChanges = nonNegativeInteger(value.pending_child_changes)
+ if (
+ totalEntries === null ||
+ sampledEntries === null ||
+ unsampledEntries === null ||
+ pendingChildChanges === null ||
+ sampledEntries + unsampledEntries !== totalEntries
+ ) {
+ return null
+ }
+
+ return {
+ pending_child_changes: pendingChildChanges,
+ sampled_entries: sampledEntries,
+ total_entries: totalEntries,
+ unsampled_entries: unsampledEntries,
+ }
+}
+
+function normalizeMetadata(value: unknown): OkfSidecarMetadata | null {
+ if (!isRecord(value)) return null
+ const directory = nonEmptyString(value.directory)
+ if (!directory?.startsWith('viking://')) return null
+
+ const source = parseSource(value.source)
+ const generatedBy = parseGeneratedBy(value.generated_by)
+ const freshness = parseFreshness(value.freshness)
+ if (source === null || generatedBy === null || freshness === null) return null
+
+ return {
+ directory,
+ ...(source ? { source } : {}),
+ ...(generatedBy ? { generated_by: generatedBy } : {}),
+ ...(freshness ? { freshness } : {}),
+ }
+}
+
+/**
+ * Parse the strict YAML frontmatter used by generated L0/L1 sidecars.
+ * Ordinary Markdown and malformed/legacy sidecars return null so callers can
+ * render their original content without accidentally hiding user text.
+ */
+export function parseOkfSidecarMarkdown(
+ uri: string,
+ content: string,
+): OkfSidecarDocument | null {
+ if (!isDirectorySemanticSidecarUri(uri)) return null
+
+ const normalized = content.replace(/\r\n?/g, '\n')
+ const lines = normalized.split('\n')
+ if (lines[0] !== '---') return null
+
+ const closingIndex = lines.indexOf('---', 1)
+ if (closingIndex < 0) return null
+
+ let parsed: unknown
+ try {
+ parsed = parseYaml(lines.slice(1, closingIndex).join('\n'))
+ } catch {
+ return null
+ }
+
+ const metadata = normalizeMetadata(parsed)
+ if (!metadata) return null
+
+ const bodyLines = lines.slice(closingIndex + 1)
+ if (bodyLines[0] === '') bodyLines.shift()
+ return {
+ body: bodyLines.join('\n'),
+ metadata,
+ rawFrontmatter: lines.slice(0, closingIndex + 1).join('\n'),
+ }
+}
diff --git a/web-studio/src/lib/viking-uri.test.ts b/web-studio/src/lib/viking-uri.test.ts
index 46ec96c83..0623f6bc0 100644
--- a/web-studio/src/lib/viking-uri.test.ts
+++ b/web-studio/src/lib/viking-uri.test.ts
@@ -1,6 +1,10 @@
import { describe, expect, it } from 'vitest'
-import { cleanVikingUri } from './viking-uri'
+import {
+ cleanVikingUri,
+ isDirectorySemanticSidecarUri,
+ retrievalResultNameFromUri,
+} from './viking-uri'
describe('cleanVikingUri', () => {
it('keeps spaces in direct viking uri values', () => {
@@ -19,3 +23,25 @@ describe('cleanVikingUri', () => {
)
})
})
+
+describe('retrievalResultNameFromUri', () => {
+ it.each(['.abstract.md', '.overview.md'])(
+ 'adds the summarized directory to %s results',
+ (sidecar) => {
+ const uri = `viking://resources/openviking-release/${sidecar}`
+
+ expect(isDirectorySemanticSidecarUri(uri)).toBe(true)
+ expect(retrievalResultNameFromUri(uri)).toBe(
+ `openviking-release/${sidecar}`,
+ )
+ },
+ )
+
+ it('keeps ordinary result names unchanged', () => {
+ expect(
+ retrievalResultNameFromUri(
+ 'viking://resources/openviking-release/README.md',
+ ),
+ ).toBe('README.md')
+ })
+})
diff --git a/web-studio/src/lib/viking-uri.ts b/web-studio/src/lib/viking-uri.ts
index 144f71184..c043653d9 100644
--- a/web-studio/src/lib/viking-uri.ts
+++ b/web-studio/src/lib/viking-uri.ts
@@ -5,6 +5,25 @@ export function fileNameFromUri(uri: string): string {
return trimmed.slice(index + 1) || trimmed
}
+const DIRECTORY_SEMANTIC_SIDECARS = new Set(['.abstract.md', '.overview.md'])
+
+export function isDirectorySemanticSidecarUri(uri: string): boolean {
+ return DIRECTORY_SEMANTIC_SIDECARS.has(fileNameFromUri(uri))
+}
+
+/**
+ * L0/L1 hits all share one of two hidden filenames, so a bare basename loses
+ * the identity of the directory they summarize. Keep ordinary result names
+ * compact while adding exactly one parent segment for semantic sidecars.
+ */
+export function retrievalResultNameFromUri(uri: string): string {
+ const name = fileNameFromUri(uri)
+ if (!DIRECTORY_SEMANTIC_SIDECARS.has(name)) return name
+
+ const parentName = fileNameFromUri(parentUri(uri))
+ return parentName ? `${parentName}/${name}` : name
+}
+
export function normalizeDirUri(uri: string): string {
const value = uri.trim()
if (!value) {
diff --git a/web-studio/src/routes/resources/-components/file-preview.test.tsx b/web-studio/src/routes/resources/-components/file-preview.test.tsx
index f56188afe..34a2b7a76 100644
--- a/web-studio/src/routes/resources/-components/file-preview.test.tsx
+++ b/web-studio/src/routes/resources/-components/file-preview.test.tsx
@@ -82,17 +82,18 @@ function renderPreview(
entry: VikingFsEntry,
onNavigate: (uri: string) => void,
directoryOverview?: string,
+ directoryAbstract?: string,
) {
const queryClient = new QueryClient({
defaultOptions: { queries: { retry: false } },
})
if (entry.isDir) {
queryClient.setQueryData(
- ['viking-directory-level', entry.uri, 'abstract'],
- '',
+ ['viking-directory-sidecar', entry.uri, 'abstract'],
+ directoryAbstract ?? '',
)
queryClient.setQueryData(
- ['viking-directory-level', entry.uri, 'overview'],
+ ['viking-directory-sidecar', entry.uri, 'overview'],
directoryOverview,
)
}
@@ -204,6 +205,229 @@ describe('FilePreview Markdown links', () => {
expect(screen.queryByRole('link', { name: 'Blob' })).toBeNull()
expect(onNavigate).not.toHaveBeenCalled()
})
+
+ it('renders directory L0 and L1 frontmatter as independent metadata panels', () => {
+ const sidecar = (
+ filename: '.abstract.md' | '.overview.md',
+ trigger: string,
+ body: string,
+ ) =>
+ [
+ '---',
+ `directory: viking://resources/wiki/`,
+ 'generated_by:',
+ ' component: SemanticProcessor',
+ ` trigger: ${trigger}`,
+ 'freshness:',
+ ' total_entries: 2',
+ ' sampled_entries: 2',
+ ' unsampled_entries: 0',
+ ' pending_child_changes: 0',
+ 'extensions:',
+ ` sidecar: ${filename}`,
+ '---',
+ '',
+ body,
+ ].join('\n')
+
+ const { container } = renderPreview(
+ directory,
+ vi.fn(),
+ sidecar('.overview.md', 'overview_refresh', 'L1 body'),
+ sidecar('.abstract.md', 'abstract_refresh', 'L0 body'),
+ )
+
+ expect(
+ screen.getAllByRole('region', {
+ name: 'filePreview.yamlMetadata.ariaLabel',
+ }),
+ ).toHaveLength(2)
+ expect(screen.getByText('abstract_refresh')).toBeDefined()
+ expect(screen.getByText('overview_refresh')).toBeDefined()
+ expect(screen.getByText('L0 body')).toBeDefined()
+ expect(screen.getByText('L1 body')).toBeDefined()
+
+ const articles = [
+ screen.getByText('L0 body').closest('article'),
+ screen.getByText('L1 body').closest('article'),
+ ]
+ expect(articles.every(Boolean)).toBe(true)
+ for (const article of articles) {
+ expect(article?.textContent).not.toContain('generated_by:')
+ expect(article?.textContent).not.toContain('extensions:')
+ }
+
+ const details = [...container.querySelectorAll('details')]
+ expect(details).toHaveLength(2)
+ expect(details.every((item) => !item.open)).toBe(true)
+ fireEvent.click(details[0].querySelector('summary')!)
+ expect(details[0].textContent).toContain('sidecar: .abstract.md')
+ expect(details[1].textContent).toContain('sidecar: .overview.md')
+ })
+})
+
+describe('FilePreview OKF semantic sidecars', () => {
+ beforeEach(() => {
+ cleanup()
+ })
+
+ afterEach(() => {
+ previewState.override = null
+ })
+
+ it.each(['.abstract.md', '.overview.md'])(
+ 'renders %s frontmatter as metadata and keeps the body as Markdown',
+ (name) => {
+ previewState.override = {
+ content: [
+ '---',
+ 'directory: viking://resources/openviking-contribute/',
+ 'generated_by:',
+ ' component: SemanticProcessor',
+ ' trigger: parent_refresh',
+ 'freshness:',
+ ' total_entries: 4',
+ ' sampled_entries: 4',
+ ' unsampled_entries: 0',
+ ' pending_child_changes: 0',
+ 'extensions:',
+ ' ranking:',
+ ' strategy: semantic',
+ '---',
+ '',
+ '**这是 OpenViking 相关项目的 PR 贡献规范集合。**',
+ ].join('\n'),
+ fileType: 'markdown',
+ }
+
+ const { container } = renderPreview(
+ {
+ ...file,
+ name,
+ uri: `viking://resources/openviking-contribute/${name}`,
+ },
+ vi.fn(),
+ )
+
+ expect(
+ screen.getByRole('region', {
+ name: 'filePreview.yamlMetadata.ariaLabel',
+ }),
+ ).toBeDefined()
+ expect(screen.getByText('SemanticProcessor')).toBeDefined()
+ expect(screen.getByText('parent_refresh')).toBeDefined()
+ expect(
+ screen.getByText('这是 OpenViking 相关项目的 PR 贡献规范集合。'),
+ ).toBeDefined()
+ const article = container.querySelector('article')
+ expect(article?.textContent).not.toContain('generated_by:')
+ expect(article?.textContent).not.toContain('total_entries:')
+
+ const region = screen.getByRole('region', {
+ name: 'filePreview.yamlMetadata.ariaLabel',
+ })
+ const details = region.querySelector('details')
+ expect(details?.open).toBe(false)
+ expect(region.getAttribute('aria-label')).not.toMatch(/okf/i)
+
+ const summary = screen.getByText('filePreview.yamlMetadata.rawYaml')
+ expect(summary.textContent).not.toMatch(/okf/i)
+ fireEvent.click(summary)
+
+ expect(details?.open).toBe(true)
+ expect(details?.textContent).toContain('extensions:')
+ expect(details?.textContent).toContain(' ranking:')
+ expect(details?.textContent).toContain(' strategy: semantic')
+
+ fireEvent.click(
+ screen.getByRole('button', {
+ name: 'filePreview.markdownSource',
+ }),
+ )
+ expect(container.textContent).toContain('extensions:')
+ expect(container.textContent).toContain('strategy: semantic')
+ },
+ )
+
+ it('leaves ordinary Markdown frontmatter in the document', () => {
+ previewState.override = {
+ content: ['---', 'title: User document', '---', '', 'Body'].join('\n'),
+ fileType: 'markdown',
+ }
+
+ renderPreview(file, vi.fn())
+
+ expect(
+ screen.queryByRole('region', {
+ name: 'filePreview.yamlMetadata.ariaLabel',
+ }),
+ ).toBeNull()
+ expect(screen.getByText(/title: User document/)).toBeDefined()
+ })
+
+ it('warns when the sidecar reports pending child changes', () => {
+ previewState.override = {
+ content: [
+ '---',
+ 'directory: viking://resources/openviking-contribute/',
+ 'freshness:',
+ ' total_entries: 4',
+ ' sampled_entries: 4',
+ ' unsampled_entries: 0',
+ ' pending_child_changes: 2',
+ '---',
+ '',
+ 'Body',
+ ].join('\n'),
+ fileType: 'markdown',
+ }
+
+ const { container } = renderPreview(
+ {
+ ...file,
+ name: '.overview.md',
+ uri: 'viking://resources/openviking-contribute/.overview.md',
+ },
+ vi.fn(),
+ )
+
+ const pending = container.querySelector('[data-pending="true"]')
+ expect(pending).not.toBeNull()
+ expect(pending?.classList.contains('text-amber-700')).toBe(true)
+ })
+
+ it('shows the empty state instead of leaking frontmatter for an empty body', () => {
+ previewState.override = {
+ content: [
+ '---',
+ 'directory: viking://resources/openviking-contribute/',
+ '---',
+ '',
+ ].join('\n'),
+ fileType: 'markdown',
+ }
+
+ const { container } = renderPreview(
+ {
+ ...file,
+ name: '.abstract.md',
+ uri: 'viking://resources/openviking-contribute/.abstract.md',
+ },
+ vi.fn(),
+ )
+
+ expect(screen.getByText('filePreview.emptyFile')).toBeDefined()
+ expect(container.querySelector('article')?.textContent).not.toContain(
+ 'directory:',
+ )
+ expect(
+ screen
+ .getByRole('region', {
+ name: 'filePreview.yamlMetadata.ariaLabel',
+ })
+ .querySelector('details')?.open,
+ ).toBe(false)
+ })
})
describe('normalizeJsonlDisplayText', () => {
diff --git a/web-studio/src/routes/resources/-components/file-preview.tsx b/web-studio/src/routes/resources/-components/file-preview.tsx
index b625c2183..2e5276b49 100644
--- a/web-studio/src/routes/resources/-components/file-preview.tsx
+++ b/web-studio/src/routes/resources/-components/file-preview.tsx
@@ -14,12 +14,17 @@ import { Button } from '#/components/ui/button'
import { ScrollArea } from '#/components/ui/scroll-area'
import { client } from '#/gen/ov-client/client.gen'
import { getContentDownload, ovClient } from '#/lib/ov-client'
+import { parseOkfSidecarMarkdown } from '#/lib/okf-markdown'
import { fileNameFromUri } from '#/lib/viking-uri'
import type { GetContentDownloadData } from '#/gen/ov-client/types.gen'
import type { ContentDownloadQuery } from '@ov-server/api/v1/content'
-import { formatSize, normalizeReadContent } from '../-lib/normalize'
-import { fetchDirectoryLevelContent, saveFileContent } from '../-lib/api'
+import {
+ formatSize,
+ normalizeDirUri,
+ normalizeReadContent,
+} from '../-lib/normalize'
+import { fetchDirectorySidecarContent, saveFileContent } from '../-lib/api'
import {
useVikingFilePreview,
useVikingFsStat,
@@ -28,6 +33,7 @@ import {
import { useJsonFormat } from '../-hooks/use-json-format'
import type { VikingFsEntry } from '../-types/viking-fm'
import type { CodeEditorHandle } from './code-editor'
+import { OkfMetadataPanel } from './okf-metadata-panel'
const LazyCodeEditor = lazy(() =>
import('./code-editor').then((m) => ({ default: m.CodeEditor })),
@@ -201,52 +207,78 @@ function cleanSummaryContent(value: unknown): string {
return text
}
+function directoryLevelPreview(
+ directoryUri: string,
+ level: DirectoryLevelId,
+ ...values: unknown[]
+) {
+ const rawContent =
+ values.map(cleanSummaryContent).find((content) => content.length > 0) ?? ''
+ const document = rawContent
+ ? parseOkfSidecarMarkdown(
+ `${normalizeDirUri(directoryUri)}.${level}.md`,
+ rawContent,
+ )
+ : null
+
+ return {
+ content: document?.body ?? rawContent,
+ document,
+ }
+}
+
function useDirectoryPreview(file: VikingFsEntry | null) {
const enabled = Boolean(file?.isDir)
const abstractQuery = useQuery({
enabled,
- queryKey: ['viking-directory-level', file?.uri, 'abstract'],
- queryFn: () => fetchDirectoryLevelContent(file!.uri, 'abstract'),
+ queryKey: ['viking-directory-sidecar', file?.uri, 'abstract'],
+ queryFn: () => fetchDirectorySidecarContent(file!.uri, 'abstract'),
staleTime: 30_000,
})
const overviewQuery = useQuery({
enabled,
- queryKey: ['viking-directory-level', file?.uri, 'overview'],
- queryFn: () => fetchDirectoryLevelContent(file!.uri, 'overview'),
+ queryKey: ['viking-directory-sidecar', file?.uri, 'overview'],
+ queryFn: () => fetchDirectorySidecarContent(file!.uri, 'overview'),
staleTime: 30_000,
})
- return useMemo(
- () => ({
+ return useMemo(() => {
+ const directoryUri = file?.uri ?? ''
+ return {
isLoading: abstractQuery.isLoading || overviewQuery.isLoading,
levels: [
{
...DIRECTORY_LEVEL_META[0],
- content:
- cleanSummaryContent(abstractQuery.data) ||
- cleanSummaryContent(file?.abstract),
+ ...directoryLevelPreview(
+ directoryUri,
+ 'abstract',
+ abstractQuery.data,
+ file?.abstract,
+ ),
error: abstractQuery.error,
},
{
...DIRECTORY_LEVEL_META[1],
- content:
- cleanSummaryContent(overviewQuery.data) ||
- cleanSummaryContent(file?.overview),
+ ...directoryLevelPreview(
+ directoryUri,
+ 'overview',
+ overviewQuery.data,
+ file?.overview,
+ ),
error: overviewQuery.error,
},
],
- }),
- [
- abstractQuery.data,
- abstractQuery.error,
- abstractQuery.isLoading,
- file?.abstract,
- file?.overview,
- overviewQuery.data,
- overviewQuery.error,
- overviewQuery.isLoading,
- ],
- )
+ }
+ }, [
+ abstractQuery.data,
+ abstractQuery.error,
+ abstractQuery.isLoading,
+ file?.abstract,
+ file?.overview,
+ overviewQuery.data,
+ overviewQuery.error,
+ overviewQuery.isLoading,
+ ])
}
function dirnameVikingUri(fileUri: string): string {
@@ -1331,6 +1363,13 @@ export function FilePreview({
() => memoryFieldsDisplayContent(preview?.content || ''),
[preview?.content],
)
+ const okfDocument = useMemo(
+ () =>
+ file && preview?.fileType === 'markdown'
+ ? parseOkfSidecarMarkdown(file.uri, displayContent)
+ : null,
+ [displayContent, file, preview?.fileType],
+ )
const jsonFormat = useJsonFormat(
displayContent,
isJsonFile && hasPreviewContent,
@@ -1499,8 +1538,8 @@ export function FilePreview({
const isMarkdown = preview?.fileType === 'markdown'
const isDark = document.documentElement.classList.contains('dark')
const emptyFileText = t('filePreview.emptyFile')
- const availableDirectoryLevels = directoryPreview.levels.filter((level) =>
- level.content.trim(),
+ const availableDirectoryLevels = directoryPreview.levels.filter(
+ (level) => level.document !== null || level.content.trim(),
)
const visibleDirectoryLevels = availableDirectoryLevels.filter((level) =>
activeDirectoryLevels.has(level.id),
@@ -1758,26 +1797,35 @@ export function FilePreview({
{level.title}
</span>
</header>
- <article className="prose prose-sm max-w-none break-words rounded-md border bg-muted/20 p-3 dark:prose-invert dark:prose-pre:bg-muted-foreground/20">
- <ReactMarkdown
- remarkPlugins={[remarkGfm]}
- urlTransform={transformDirectoryMarkdownUrl}
- components={{
- ...markdownComponents,
- a: ({ href, children }) => (
- <DirectoryMarkdownLink
- href={href}
- fileUri={file.uri}
- onNavigate={onNavigate}
- >
- {children}
- </DirectoryMarkdownLink>
- ),
- }}
- >
- {level.content}
- </ReactMarkdown>
- </article>
+ {level.document ? (
+ <OkfMetadataPanel
+ metadata={level.document.metadata}
+ onNavigate={onNavigate}
+ rawFrontmatter={level.document.rawFrontmatter}
+ />
+ ) : null}
+ {level.content.trim() ? (
+ <article className="prose prose-sm max-w-none break-words rounded-md border bg-muted/20 p-3 dark:prose-invert dark:prose-pre:bg-muted-foreground/20">
+ <ReactMarkdown
+ remarkPlugins={[remarkGfm]}
+ urlTransform={transformDirectoryMarkdownUrl}
+ components={{
+ ...markdownComponents,
+ a: ({ href, children }) => (
+ <DirectoryMarkdownLink
+ href={href}
+ fileUri={file.uri}
+ onNavigate={onNavigate}
+ >
+ {children}
+ </DirectoryMarkdownLink>
+ ),
+ }}
+ >
+ {level.content}
+ </ReactMarkdown>
+ </article>
+ ) : null}
</section>
))}
</div>
@@ -1857,34 +1905,45 @@ export function FilePreview({
preview?.fileType === 'markdown' &&
hasPreviewContent &&
markdownMode === 'preview' ? (
- <article className="prose prose-sm max-w-none break-words dark:prose-invert dark:prose-pre:bg-muted-foreground/20">
- <ReactMarkdown
- remarkPlugins={[remarkGfm]}
- rehypePlugins={[rehypeRaw, rehypeSanitize]}
- urlTransform={(url) => url}
- components={{
- ...markdownComponents,
- img: ({ src, alt }) => (
- <MarkdownImage
- src={src ? String(src) : undefined}
- alt={alt}
- fileUri={file.uri}
- />
- ),
- a: ({ href, children }) => (
- <MarkdownLink
- href={href}
- fileUri={file.uri}
- onNavigate={onNavigate}
- >
- {children}
- </MarkdownLink>
- ),
- }}
- >
- {displayContent || emptyFileText}
- </ReactMarkdown>
- </article>
+ <div className="space-y-5">
+ {okfDocument ? (
+ <OkfMetadataPanel
+ metadata={okfDocument.metadata}
+ onNavigate={onNavigate}
+ rawFrontmatter={okfDocument.rawFrontmatter}
+ />
+ ) : null}
+ <article className="prose prose-sm max-w-none break-words dark:prose-invert dark:prose-pre:bg-muted-foreground/20">
+ <ReactMarkdown
+ remarkPlugins={[remarkGfm]}
+ rehypePlugins={[rehypeRaw, rehypeSanitize]}
+ urlTransform={(url) => url}
+ components={{
+ ...markdownComponents,
+ img: ({ src, alt }) => (
+ <MarkdownImage
+ src={src ? String(src) : undefined}
+ alt={alt}
+ fileUri={file.uri}
+ />
+ ),
+ a: ({ href, children }) => (
+ <MarkdownLink
+ href={href}
+ fileUri={file.uri}
+ onNavigate={onNavigate}
+ >
+ {children}
+ </MarkdownLink>
+ ),
+ }}
+ >
+ {okfDocument
+ ? okfDocument.body || emptyFileText
+ : displayContent || emptyFileText}
+ </ReactMarkdown>
+ </article>
+ </div>
) : null}
{!previewLoading &&
diff --git a/web-studio/src/routes/resources/-components/find-palette.tsx b/web-studio/src/routes/resources/-components/find-palette.tsx
index 8c6db9332..16fa0ef8a 100644
--- a/web-studio/src/routes/resources/-components/find-palette.tsx
+++ b/web-studio/src/routes/resources/-components/find-palette.tsx
@@ -10,19 +10,17 @@ import {
import { useTranslation } from 'react-i18next'
import { cn } from '#/lib/utils'
+import { retrievalResultNameFromUri } from '#/lib/viking-uri'
import { useTransientScrollbar } from '#/hooks/use-transient-scrollbar'
import { useRetrievalQuery } from '#/routes/retrieval/-hooks/use-retrieval-query'
import type { RetrievalMode } from '#/routes/retrieval/-types/retrieval'
-import {
- fileNameFromUri,
- normalizeDirUri,
- parentUri as getParentUri,
-} from '../-lib/normalize'
+import { normalizeDirUri, parentUri as getParentUri } from '../-lib/normalize'
import {
filterResourceSearchEntries,
getResourceSearchSpec,
normalizeGlobPattern,
+ resourceEntryAbstractForDisplay,
retrievalItemsToEntries,
} from '../-lib/find-search'
import {
@@ -56,7 +54,7 @@ const KEY_ESCAPE_LABEL = 'esc'
const KEY_TAB_LABEL = 'Tab'
function displayName(uri: string): { name: string; parent: string } {
- const name = fileNameFromUri(uri)
+ const name = retrievalResultNameFromUri(uri)
const dir = getParentUri(uri)
const segments = dir.replace(/\/$/, '').split('/').filter(Boolean)
const parent = segments.length > 1 ? segments.slice(-1)[0] : dir
@@ -735,6 +733,7 @@ function DirResultList({
>
{items.map((entry, i) => {
const { name, parent } = displayName(entry.uri)
+ const abstract = resourceEntryAbstractForDisplay(entry)
const isActive = i === activeIndex
const EntryIcon = entry.isDir ? FolderIcon : FileIcon
@@ -769,7 +768,7 @@ function DirResultList({
<div className="min-w-0 flex-1">
<div className="truncate text-sm font-medium">{name}</div>
<div className="mt-0.5 truncate text-xs text-muted-foreground/80">
- {entry.abstract.trim() ? entry.abstract : parent}
+ {abstract || parent}
</div>
</div>
</button>
diff --git a/web-studio/src/routes/resources/-components/okf-metadata-panel.tsx b/web-studio/src/routes/resources/-components/okf-metadata-panel.tsx
new file mode 100644
index 000000000..fce7f8443
--- /dev/null
+++ b/web-studio/src/routes/resources/-components/okf-metadata-panel.tsx
@@ -0,0 +1,152 @@
+import {
+ Bot,
+ ChevronRight,
+ CircleAlert,
+ FolderOpen,
+ RefreshCw,
+ Waypoints,
+} from 'lucide-react'
+import { useTranslation } from 'react-i18next'
+
+import type { OkfSidecarMetadata } from '#/lib/okf-markdown'
+
+export function OkfMetadataPanel({
+ metadata,
+ onNavigate,
+ rawFrontmatter,
+}: {
+ metadata: OkfSidecarMetadata
+ onNavigate?: (uri: string) => void
+ rawFrontmatter: string
+}) {
+ const { t } = useTranslation('resources')
+ const generatedBy = metadata.generated_by
+ const freshness = metadata.freshness
+ const source = metadata.source
+
+ return (
+ <section
+ aria-label={t('filePreview.yamlMetadata.ariaLabel')}
+ className="not-prose overflow-hidden rounded-md border bg-muted/10"
+ >
+ <dl className="grid gap-2.5 p-3 text-xs">
+ <div className="grid min-w-0 grid-cols-[7rem_minmax(0,1fr)] items-start gap-3">
+ <dt className="flex items-center gap-1.5 pt-0.5 text-muted-foreground">
+ <FolderOpen className="size-3.5 shrink-0" />
+ {t('filePreview.yamlMetadata.directory')}
+ </dt>
+ <dd className="min-w-0">
+ {onNavigate ? (
+ <button
+ type="button"
+ className="block max-w-full truncate font-mono text-primary underline-offset-4 hover:underline"
+ title={metadata.directory}
+ onClick={() => onNavigate(metadata.directory)}
+ >
+ {metadata.directory}
+ </button>
+ ) : (
+ <code
+ className="block truncate font-mono text-foreground"
+ title={metadata.directory}
+ >
+ {metadata.directory}
+ </code>
+ )}
+ </dd>
+ </div>
+
+ {generatedBy ? (
+ <div className="grid min-w-0 grid-cols-[7rem_minmax(0,1fr)] items-start gap-3">
+ <dt className="flex items-center gap-1.5 pt-0.5 text-muted-foreground">
+ <Bot className="size-3.5 shrink-0" />
+ {t('filePreview.yamlMetadata.generatedBy')}
+ </dt>
+ <dd className="flex min-w-0 flex-wrap items-center gap-1.5">
+ <code className="rounded bg-muted px-1.5 py-0.5 font-mono text-[11px] text-foreground">
+ {generatedBy.component}
+ </code>
+ <span className="text-muted-foreground">
+ {t('filePreview.yamlMetadata.trigger')}
+ </span>
+ <code className="font-mono text-[11px] text-foreground/80">
+ {generatedBy.trigger}
+ </code>
+ </dd>
+ </div>
+ ) : null}
+
+ {source ? (
+ <div className="grid min-w-0 grid-cols-[7rem_minmax(0,1fr)] items-start gap-3">
+ <dt className="flex items-center gap-1.5 pt-0.5 text-muted-foreground">
+ <Waypoints className="size-3.5 shrink-0" />
+ {t('filePreview.yamlMetadata.source')}
+ </dt>
+ <dd className="flex min-w-0 items-center gap-1.5">
+ <span className="rounded bg-muted px-1.5 py-0.5 font-mono text-[10px] font-medium uppercase text-muted-foreground">
+ {source.kind}
+ </span>
+ <code
+ className="min-w-0 truncate font-mono text-[11px] text-foreground/80"
+ title={source.uri}
+ >
+ {source.uri}
+ </code>
+ </dd>
+ </div>
+ ) : null}
+ </dl>
+
+ {freshness ? (
+ <div className="flex flex-wrap items-center gap-x-4 gap-y-1.5 border-t bg-muted/10 px-3 py-2 text-[11px]">
+ <div className="flex items-center gap-1.5 font-medium text-muted-foreground">
+ <RefreshCw className="size-3" />
+ {t('filePreview.yamlMetadata.freshness')}
+ </div>
+ <span className="font-mono tabular-nums text-foreground/80">
+ {t('filePreview.yamlMetadata.coverage', {
+ sampled: freshness.sampled_entries,
+ total: freshness.total_entries,
+ })}
+ <span className="text-muted-foreground">
+ {' '}
+ ·{' '}
+ {t('filePreview.yamlMetadata.unsampled', {
+ count: freshness.unsampled_entries,
+ })}
+ </span>
+ </span>
+ <span
+ data-pending={
+ freshness.pending_child_changes > 0 ? 'true' : undefined
+ }
+ className={
+ freshness.pending_child_changes > 0
+ ? 'inline-flex items-center gap-1 rounded border border-amber-500/35 bg-amber-500/10 px-1.5 py-0.5 font-mono font-medium tabular-nums text-amber-700 dark:text-amber-300'
+ : 'font-mono tabular-nums text-muted-foreground'
+ }
+ >
+ {freshness.pending_child_changes > 0 ? (
+ <CircleAlert className="size-3" />
+ ) : null}
+ {t('filePreview.yamlMetadata.pendingChanges', {
+ count: freshness.pending_child_changes,
+ })}
+ </span>
+ </div>
+ ) : null}
+
+ <details className="group border-t bg-background/40">
+ <summary className="flex cursor-pointer list-none items-center gap-1.5 px-3 py-2 text-[11px] font-medium text-muted-foreground transition-colors marker:hidden hover:bg-muted/40 hover:text-foreground">
+ <ChevronRight className="size-3.5 shrink-0 transition-transform group-open:rotate-90" />
+ {t('filePreview.yamlMetadata.rawYaml')}
+ </summary>
+ <div className="border-t bg-background/70 p-3">
+ <pre className="max-h-[32rem] min-h-32 overflow-auto whitespace-pre rounded-md border bg-muted/20 p-3 font-mono text-xs leading-5 text-foreground">
+ <code>{rawFrontmatter}</code>
+ </pre>
+ </div>
+ </details>
+ </section>
+ )
+}
diff --git a/web-studio/src/routes/resources/-lib/api.test.ts b/web-studio/src/routes/resources/-lib/api.test.ts
index d581e8bac..fb525c5c5 100644
--- a/web-studio/src/routes/resources/-lib/api.test.ts
+++ b/web-studio/src/routes/resources/-lib/api.test.ts
@@ -1,8 +1,9 @@
import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { fetchFsList } from './api'
+import { fetchDirectorySidecarContent, fetchFsList } from './api'
-const { getFsLsMock } = vi.hoisted(() => ({
+const { getContentReadMock, getFsLsMock } = vi.hoisted(() => ({
+ getContentReadMock: vi.fn(),
getFsLsMock: vi.fn(),
}))
@@ -10,20 +11,47 @@ vi.mock('#/lib/ov-client', async (importOriginal) => {
const original = await importOriginal()
return {
...original,
+ getContentRead: getContentReadMock,
getFsLs: getFsLsMock,
}
})
-describe('fetchFsList', () => {
- beforeEach(() => {
- getFsLsMock.mockReset()
- getFsLsMock.mockResolvedValue({
- data: { status: 'ok', result: [] },
+beforeEach(() => {
+ getContentReadMock.mockReset()
+ getFsLsMock.mockReset()
+ getFsLsMock.mockResolvedValue({
+ data: { status: 'ok', result: [] },
+ headers: {},
+ status: 200,
+ })
+})
+
+describe('fetchDirectorySidecarContent', () => {
+ it('reads raw L0/L1 sidecars instead of the body-only semantic accessors', async () => {
+ getContentReadMock.mockResolvedValue({
+ data: {
+ status: 'ok',
+ result: '---\ndirectory: viking://resources/demo/\n---',
+ },
headers: {},
status: 200,
})
+
+ await expect(
+ fetchDirectorySidecarContent('viking://resources/demo/', 'abstract'),
+ ).resolves.toContain('directory: viking://resources/demo/')
+ expect(getContentReadMock).toHaveBeenCalledWith({
+ query: {
+ uri: 'viking://resources/demo/.abstract.md',
+ offset: 0,
+ limit: -1,
+ raw: true,
+ },
+ })
})
+})
+describe('fetchFsList', () => {
it('requests newest entries before the server applies node_limit', async () => {
await fetchFsList('viking://session', { nodeLimit: 200 })
diff --git a/web-studio/src/routes/resources/-lib/api.ts b/web-studio/src/routes/resources/-lib/api.ts
index 11f00d1d1..52b1b6101 100644
--- a/web-studio/src/routes/resources/-lib/api.ts
+++ b/web-studio/src/routes/resources/-lib/api.ts
@@ -160,6 +160,18 @@ export async function fetchDirectoryLevelContent(
}
}
+export async function fetchDirectorySidecarContent(
+ uri: string,
+ level: 'abstract' | 'overview',
+): Promise<string> {
+ const sidecarUri = `${normalizeDirUri(uri)}.${level}.md`
+ const result = await fetchFileContent(sidecarUri, {
+ limit: -1,
+ raw: true,
+ })
+ return result.content
+}
+
export async function fetchFsStat(
uri: string,
options: { throwOnError?: boolean } = {},
diff --git a/web-studio/src/routes/resources/-lib/find-search.test.ts b/web-studio/src/routes/resources/-lib/find-search.test.ts
index 64623351e..4c8821e03 100644
--- a/web-studio/src/routes/resources/-lib/find-search.test.ts
+++ b/web-studio/src/routes/resources/-lib/find-search.test.ts
@@ -4,6 +4,7 @@ import {
filterResourceSearchEntries,
getResourceSearchSpec,
normalizeGlobPattern,
+ resourceEntryAbstractForDisplay,
retrievalItemsToEntries,
} from './find-search'
import type { FindResultItem } from '#/lib/retrieval'
@@ -126,7 +127,99 @@ describe('retrievalItemsToEntries', () => {
expect(entries[1].size).toBe('')
})
+ it('adds parent context to L0/L1 semantic sidecar names only', () => {
+ const entries = retrievalItemsToEntries({
+ memories: [],
+ resources: [
+ item({
+ level: 0,
+ uri: 'viking://resources/openviking-release/.abstract.md',
+ }),
+ item({
+ level: 1,
+ uri: 'viking://resources/openviking-release/.overview.md',
+ }),
+ item({
+ level: 2,
+ uri: 'viking://resources/openviking-release/README.md',
+ }),
+ ],
+ skills: [],
+ total: 3,
+ })
+
+ expect(entries.map((resultEntry) => resultEntry.name)).toEqual([
+ 'openviking-release/.abstract.md',
+ 'openviking-release/.overview.md',
+ 'README.md',
+ ])
+ })
+
it('returns nothing without a result', () => {
expect(retrievalItemsToEntries(undefined)).toEqual([])
})
})
+
+describe('resourceEntryAbstractForDisplay', () => {
+ it('shows only the body for a directory with sidecar frontmatter', () => {
+ expect(
+ resourceEntryAbstractForDisplay({
+ ...entry(
+ 'viking://resources/openviking-contribute/pr-review-axiom/',
+ true,
+ ),
+ abstract: [
+ '---',
+ 'directory: viking://resources/openviking-contribute/pr-review-axiom/',
+ 'generated_by:',
+ ' component: SemanticProcessor',
+ ' trigger: parent_refresh',
+ '---',
+ '',
+ 'PR review guidance',
+ ].join('\n'),
+ }),
+ ).toBe('PR review guidance')
+ })
+
+ it('hides clipped directory frontmatter when the list payload has no body', () => {
+ expect(
+ resourceEntryAbstractForDisplay({
+ ...entry(
+ 'viking://resources/openviking-contribute/pr-review-axiom/',
+ true,
+ ),
+ abstract:
+ '---\ndirectory: viking://resources/openviking-contribute/pr-review-axiom/\ngenerated_by: ...',
+ }),
+ ).toBe('')
+ })
+
+ it('keeps legacy directory summaries and file abstracts unchanged', () => {
+ expect(
+ resourceEntryAbstractForDisplay({
+ ...entry('viking://resources/legacy/', true),
+ abstract: 'Legacy summary',
+ }),
+ ).toBe('Legacy summary')
+ expect(
+ resourceEntryAbstractForDisplay({
+ ...entry('viking://resources/user.md'),
+ abstract: '---\ntitle: user content\n---',
+ }),
+ ).toBe('---\ntitle: user content\n---')
+ expect(
+ resourceEntryAbstractForDisplay({
+ ...entry('viking://resources/legacy/', true),
+ abstract: '---\n\nLegacy summary',
+ }),
+ ).toBe('---\n\nLegacy summary')
+ expect(
+ resourceEntryAbstractForDisplay({
+ ...entry('viking://resources/manual/', true),
+ abstract:
+ '---\ndirectory: viking://resources/manual/\n---\nManual summary',
+ }),
+ ).toBe('---\ndirectory: viking://resources/manual/\n---\nManual summary')
+ })
+})
diff --git a/web-studio/src/routes/resources/-lib/find-search.ts b/web-studio/src/routes/resources/-lib/find-search.ts
index d7be9ff35..2228db1be 100644
--- a/web-studio/src/routes/resources/-lib/find-search.ts
+++ b/web-studio/src/routes/resources/-lib/find-search.ts
@@ -1,12 +1,9 @@
import type { GroupedFindResult } from '#/lib/retrieval'
+import { parseOkfSidecarMarkdown } from '#/lib/okf-markdown'
+import { retrievalResultNameFromUri } from '#/lib/viking-uri'
import type { VikingFsEntry } from '../-types/viking-fm'
-import {
- fileNameFromUri,
- normalizeDirUri,
- normalizeFileUri,
- parentUri,
-} from './normalize'
+import { normalizeDirUri, normalizeFileUri, parentUri } from './normalize'
const VIKING_URI_PREFIX = 'viking://'
@@ -125,7 +122,7 @@ export function retrievalItemsToEntries(
return items.map((item) => ({
uri: item.uri,
name:
- fileNameFromUri(item.uri) +
+ retrievalResultNameFromUri(item.uri) +
(item.line === undefined ? '' : `:${item.line}`),
isDir: item.uri.endsWith('/'),
abstract: item.abstract,
@@ -139,3 +136,25 @@ export function retrievalItemsToEntries(
modTimestamp: null,
}))
}
+
+export function resourceEntryAbstractForDisplay(
+ entry: Pick<VikingFsEntry, 'abstract' | 'isDir' | 'uri'>,
+): string {
+ const content = entry.abstract.trim()
+ if (!content || !entry.isDir) return content
+
+ const looksLikeGeneratedSidecar =
+ /^---\r?\ndirectory:\s*viking:\/\//.test(content) &&
+ /\r?\ngenerated_by:/.test(content)
+ if (!looksLikeGeneratedSidecar) return content
+
+ const document = parseOkfSidecarMarkdown(
+ `${normalizeDirUri(entry.uri)}.abstract.md`,
+ content,
+ )
+ if (document) return document.body.trim()
+
+ // Directory abstracts returned in list/search payloads may be clipped before
+ // the closing `---`. Do not surface that partial YAML as a human summary.
+ return ''
+}
diff --git a/web-studio/src/routes/retrieval/-components/retrieval-results.test.tsx b/web-studio/src/routes/retrieval/-components/retrieval-results.test.tsx
index 57da9190e..fa1f0c943 100644
--- a/web-studio/src/routes/retrieval/-components/retrieval-results.test.tsx
+++ b/web-studio/src/routes/retrieval/-components/retrieval-results.test.tsx
@@ -112,6 +112,49 @@ describe('RetrievalResults', () => {
expect(screen.getByText(/expanded query/)).toBeDefined()
})
+ it.each([
+ ['.abstract.md', 0],
+ ['.overview.md', 1],
+ ] as const)(
+ 'shows parent context in the title of %s results',
+ (sidecar, level) => {
+ render(
+ <RetrievalResults
+ data={{
+ memories: [],
+ resources: [
+ {
+ abstract: 'Directory summary',
+ category: '',
+ context_type: 'resource',
+ level,
+ match_reason: '',
+ score: 0.8,
+ uri: `viking://resources/openviking-release/${sidecar}`,
+ },
+ ],
+ skills: [],
+ total: 1,
+ }}
+ hasRetrievableContext
+ hasSubmitted
+ isCheckingContext={false}
+ isError={false}
+ isLoading={false}
+ onUploadClick={vi.fn()}
+ resultCount={10}
+ t={t}
+ />,
+ )
+
+ expect(
+ screen.getByRole('heading', {
+ name: `openviking-release/${sidecar}`,
+ }),
+ ).toBeDefined()
+ },
+ )
+
it('shows the API error message and diagnostic metadata', () => {
render(
<RetrievalResults
diff --git a/web-studio/src/routes/retrieval/-components/retrieval-results.tsx b/web-studio/src/routes/retrieval/-components/retrieval-results.tsx
index b18b906a4..4a1cb32c0 100644
--- a/web-studio/src/routes/retrieval/-components/retrieval-results.tsx
+++ b/web-studio/src/routes/retrieval/-components/retrieval-results.tsx
@@ -14,6 +14,7 @@ import type { TFunction } from 'i18next'
import { Button } from '#/components/ui/button'
import { cn } from '#/lib/utils'
+import { retrievalResultNameFromUri } from '#/lib/viking-uri'
import type {
FindContextType,
FindQueryPlanItem,
@@ -23,7 +24,7 @@ import type {
import { LoadingHint } from './loading-hint'
import { RetrievalDetailSheet } from './retrieval-detail-sheet'
import type { RetrievalDetail } from './retrieval-detail-sheet'
-import { displayName, flattenResults, memoryTypeFromUri } from '../-lib/results'
+import { flattenResults, memoryTypeFromUri } from '../-lib/results'
import type { FlatRetrievalItem } from '../-types/retrieval'
const TYPE_META: Record<
@@ -360,7 +361,7 @@ function ResultRowContent({
item: FlatRetrievalItem
t: TFunction<'retrieval'>
}) {
- const { name } = displayName(item.item.uri)
+ const name = retrievalResultNameFromUri(item.item.uri)
const meta = TYPE_META[item.type]
const Icon = meta.icon
const memoryType =