Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(open-knowledge): first-run onboarding card (OK Desktop) (#2311)
sarah2a719ca69dc7
diff --git a/.changeset/onboarding-card.md b/.changeset/onboarding-card.mdnew file mode 100644index 000000000..08b718d6c--- /dev/null+++ b/.changeset/onboarding-card.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": minor+---++Add a first-run onboarding card to OK Desktop. A dismissable checklist in the sidebar footer guides genuinely new users through three momentum steps — create a project (pre-checked), create the first file (⌘N), and ask AI (⌘L) — each showing its keyboard shortcut. Steps check off as the user actually performs them; on finishing all three the card celebrates in place with the OK blob mascot before animating away for good. It shows only for a fresh single-project desktop session and never returns once dismissed or completed (device-local). Web and CLI render nothing.diff --git a/packages/app/src/components/BottomComposer.dom.test.tsx b/packages/app/src/components/BottomComposer.dom.test.tsxindex b78295772..7240c04fc 100644--- a/packages/app/src/components/BottomComposer.dom.test.tsx+++ b/packages/app/src/components/BottomComposer.dom.test.tsx@@ -120,6 +120,9 @@ mock.module('@/hooks/use-selection-context', () => ({usePublishFrontmatterSelection: () => {},}));+const recordAskedAiSpy = mock(() => {});+mock.module('@/lib/onboarding-signals', () => ({ recordOnboardingAskedAi: recordAskedAiSpy }));+const dispatchCalls: Array<{ target: string; input: unknown }> = [];const buildArgs: Array<{docName: string | null;@@ -204,6 +207,22 @@ async function renderComposerWithTerminal(docName = 'notes') {);}+async function renderComposerWithThrowingTerminal(docName = 'notes') {+ const { BottomComposer } = await import('./BottomComposer');+ const { TerminalLaunchProvider } = await import('./handoff/TerminalLaunchContext');+ return render(+ <TerminalLaunchProvider+ value={{+ launchInTerminal: () => {+ throw new Error('no terminal session');+ },+ }}+ >+ <BottomComposer docName={docName} surface="wysiwyg" />+ </TerminalLaunchProvider>,+ );+}+async function renderFolderComposer(folderPath = 'specs/foo') {const { BottomComposer } = await import('./BottomComposer');return render(<BottomComposer folderPath={folderPath} />);@@ -260,6 +279,7 @@ beforeEach(() => {mockInlineMentions = [];emitMentions = null;dispatchCalls.length = 0;+ recordAskedAiSpy.mockClear();buildArgs.length = 0;terminalLaunchCalls.length = 0;toastErrors.length = 0;@@ -417,6 +437,26 @@ describe('BottomComposer (dispatch + picker + sticky default)', () => {expect(dispatchCalls[0]?.target).toBe('claude-code');});+ test('a successful dispatch records the Ask-AI onboarding step', async () => {+ await renderComposer('specs/foo/SPEC');+ fireEvent.change(getInput(), { target: { value: 'condense this doc' } });+ fireEvent.keyDown(getInput(), { key: 'Enter' });++ await waitFor(() => expect(dispatchCalls).toHaveLength(1));+ await waitFor(() => expect(recordAskedAiSpy).toHaveBeenCalledTimes(1));+ });++ test('an aborted submit (null compose input) does not record the Ask-AI step', async () => {+ builderReturnsNull = true;+ await renderComposer('specs/foo/SPEC');+ fireEvent.change(getInput(), { target: { value: 'this submit aborts' } });+ fireEvent.keyDown(getInput(), { key: 'Enter' });++ await waitFor(() => expect(toastErrors.length).toBeGreaterThan(0));+ expect(dispatchCalls).toHaveLength(0);+ expect(recordAskedAiSpy).not.toHaveBeenCalled();+ });+test('picking a non-default agent dispatches to it and persists the choice', async () => {const user = userEvent.setup();await renderComposer();@@ -451,6 +491,24 @@ describe('BottomComposer (dispatch + picker + sticky default)', () => {compose: { instruction: 'summarize this doc' },});expect(dispatchCalls).toHaveLength(0);+ expect(recordAskedAiSpy).toHaveBeenCalledTimes(1);+ });++ test('a terminal launch that throws keeps the draft, toasts, and records no Ask-AI step', async () => {+ const user = userEvent.setup();+ await renderComposerWithThrowingTerminal();++ await user.click(screen.getByTestId('ask-ai-agent-trigger'));+ await user.click(await screen.findByTestId('ask-ai-agent-option-terminal'));++ fireEvent.change(getInput(), { target: { value: 'summarize this doc' } });+ fireEvent.keyDown(getInput(), { key: 'Enter' });++ await waitFor(() => expect(toastErrors.length).toBeGreaterThan(0));+ expect(toastErrors.some((m) => m.includes('open the terminal'))).toBe(true);+ expect(getInput().value).toBe('summarize this doc');+ expect(recordAskedAiSpy).not.toHaveBeenCalled();+ expect(dispatchCalls).toHaveLength(0);});test('the Codex CLI option launches the docked terminal with cli=codex', async () => {@@ -892,6 +950,18 @@ describe('BottomComposer (failure + defensive guards)', () => {expect(toastErrors).toHaveLength(0);});+ test('an unsuccessful ({ok:false}) dispatch does not record the Ask-AI onboarding step', async () => {+ dispatchImpl = () => Promise.resolve({ ok: false });++ await renderComposer();+ fireEvent.change(getInput(), { target: { value: 'condense this doc' } });+ fireEvent.click(screen.getByTestId('ask-ai-send'));++ await waitFor(() => expect(dispatchCalls).toHaveLength(1));+ await waitFor(() => expect(getInput().value).toBe(''));+ expect(recordAskedAiSpy).not.toHaveBeenCalled();+ });+test('a null build result surfaces a toast instead of a silent no-op', async () => {builderReturnsNull = true;diff --git a/packages/app/src/components/BottomComposer.tsx b/packages/app/src/components/BottomComposer.tsxindex 330b4d6ce..e49f28c85 100644--- a/packages/app/src/components/BottomComposer.tsx+++ b/packages/app/src/components/BottomComposer.tsx@@ -35,6 +35,7 @@ import type { EditorSurface } from '@/editor/selection-stats';import { useSelectionContext } from '@/hooks/use-selection-context';import { VISIBLE_TARGETS } from '@/lib/handoff/targets';import { matchesKeyboardShortcut } from '@/lib/keyboard-shortcuts';+import { recordOnboardingAskedAi } from '@/lib/onboarding-signals';import {loadStickyAgent,parseStickyCliId,@@ -344,15 +345,20 @@ export function BottomComposer({toast.error(t`Couldn't open the terminal — please try again.`);return;}+ recordOnboardingAskedAi();clearComposer();return;}if (resolvedTarget === null) return;setPending(true);- void dispatch(resolvedTarget.id, input).finally(() => {- setPending(false);- clearComposer();- });+ void dispatch(resolvedTarget.id, input)+ .then((outcome) => {+ if (outcome.ok) recordOnboardingAskedAi();+ })+ .finally(() => {+ setPending(false);+ clearComposer();+ });};const submit = () => {diff --git a/packages/app/src/components/FileSidebar.tsx b/packages/app/src/components/FileSidebar.tsxindex 9c054f846..ee08acda2 100644--- a/packages/app/src/components/FileSidebar.tsx+++ b/packages/app/src/components/FileSidebar.tsx@@ -24,6 +24,7 @@ import {useHandoffDispatch,} from '@/components/handoff/useHandoffDispatch';import { useInstalledAgents } from '@/components/handoff/useInstalledAgents';+import { OnboardingCardMount } from '@/components/OnboardingCard';import { ProjectSwitcher } from '@/components/ProjectSwitcher';import { onPillRenderError, SidebarSearchBar } from '@/components/SidebarSearchBar';import { SkillsSidebarSection } from '@/components/SkillsSidebarSection';@@ -666,6 +667,7 @@ function FileSidebarInner({ onOpenSearch }: FileSidebarProps) {/></SidebarContent><SidebarFooter className="px-0">+ <OnboardingCardMount /><UpdateNotices />{typeof window !== 'undefined' && window.okDesktop ? (<SidebarMenu>diff --git a/packages/app/src/components/OnboardingCard.dom.test.tsx b/packages/app/src/components/OnboardingCard.dom.test.tsxnew file mode 100644index 000000000..a0b87856c--- /dev/null+++ b/packages/app/src/components/OnboardingCard.dom.test.tsx@@ -0,0 +1,91 @@+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';++mock.module('@/components/OkBlob', () => ({+ OkBlob: () => <span data-testid="ok-blob" />,+}));++import { formatShortcut } from '@/lib/keyboard-shortcuts';+import {+ createOnboardingCardStore,+ type OnboardingCardStorage,+ type OnboardingCardStore,+} from '@/lib/onboarding-card-store';+import { OnboardingCard } from './OnboardingCard';++function freshStore(): OnboardingCardStore {+ const map = new Map<string, string>();+ const storage: OnboardingCardStorage = {+ getItem: (k) => map.get(k) ?? null,+ setItem: (k, v) => {+ map.set(k, v);+ },+ };+ return createOnboardingCardStore(storage);+}++let originalFetch: typeof globalThis.fetch;+beforeEach(() => {+ originalFetch = globalThis.fetch;+ globalThis.fetch = mock(() =>+ Promise.resolve(new Response(JSON.stringify({ documents: [] }), { status: 200 })),+ ) as never;+});+afterEach(() => {+ cleanup();+ globalThis.fetch = originalFetch;+});++describe('OnboardingCard', () => {+ test('renders the three steps with step 1 pre-checked and 1/3 progress', () => {+ render(<OnboardingCard store={freshStore()} />);+ expect(screen.getByText('Get set up')).toBeTruthy();+ expect(screen.getByText('1 / 3')).toBeTruthy();+ expect(screen.getByText('Create your first project')).toBeTruthy();+ expect(screen.getByText('Create your first file')).toBeTruthy();+ expect(screen.getByText('Ask AI')).toBeTruthy();+ expect(screen.getByRole('status').textContent?.trim()).toBe('');+ });++ test('step rows are informational, not interactive buttons', () => {+ render(<OnboardingCard store={freshStore()} />);+ expect(screen.queryByRole('button', { name: /Create your first file/ })).toBeNull();+ expect(screen.queryByRole('button', { name: /Ask AI/ })).toBeNull();+ expect(screen.queryByRole('button', { name: /Create your first project/ })).toBeNull();+ });++ test('shows the registry shortcut glyphs for the active platform', () => {+ render(<OnboardingCard store={freshStore()} />);+ expect(screen.getByText(formatShortcut('new-item'))).toBeTruthy();+ expect(screen.getByText(formatShortcut('open-ask-ai'))).toBeTruthy();+ });++ test('Dismiss permanently dismisses via the store', () => {+ const store = freshStore();+ render(<OnboardingCard store={store} />);+ fireEvent.click(screen.getByRole('button', { name: 'Dismiss' }));+ expect(store.getSnapshot().dismissed).toBe(true);+ });++ test('a completed step advances progress and stays non-interactive', async () => {+ const store = freshStore();+ render(<OnboardingCard store={store} />);+ expect(screen.getByText('1 / 3')).toBeTruthy();+ act(() => {+ store.markStepComplete('file');+ });+ await waitFor(() => expect(screen.getByText('2 / 3')).toBeTruthy());+ expect(screen.queryByRole('button', { name: /Create your first file/ })).toBeNull();+ });++ test('completing all steps celebrates in-card (blob) then auto-closes', async () => {+ const store = freshStore();+ store.markStepComplete('file');+ store.markStepComplete('askedAi');+ render(<OnboardingCard store={store} lingerMs={20} />);+ expect(screen.getByTestId('ok-blob')).toBeTruthy();+ expect(screen.getAllByText(/all set up/).length).toBeGreaterThanOrEqual(1);+ expect(screen.queryByText('Create your first file')).toBeNull();+ await waitFor(() => expect(store.getSnapshot().completed).toBe(true));+ });+});diff --git a/packages/app/src/components/OnboardingCard.tsx b/packages/app/src/components/OnboardingCard.tsxnew file mode 100644index 000000000..5a04bb2d5--- /dev/null+++ b/packages/app/src/components/OnboardingCard.tsx@@ -0,0 +1,170 @@++import { Trans, useLingui } from '@lingui/react/macro';+import { useEffect, useState } from 'react';+import { OkBlob } from '@/components/OkBlob';+import { Button } from '@/components/ui/button';+import { Checkbox } from '@/components/ui/checkbox';+import { Kbd } from '@/components/ui/kbd';+import { useOnboardingCardVisible } from '@/hooks/use-onboarding-card-visible';+import { useOnboardingFileCompletion } from '@/hooks/use-onboarding-file-completion';+import { formatShortcut, type KeyboardShortcutId } from '@/lib/keyboard-shortcuts';+import {+ type OnboardingCardStore,+ onboardingCardStore,+ useOnboardingCardState,+} from '@/lib/onboarding-card-store';+import { cn } from '@/lib/utils';++const TOTAL_STEPS = 3;+const SUCCESS_LINGER_MS = 5200;+const CELEBRATE_BURST_MS = 1500;+/** Exit-animation length — the card stays mounted this long so the fade-out can+ play before `markCompleted` unmounts it. Matches the `duration-200` class. */+const EXIT_MS = 220;++function StepRow({+ complete,+ label,+ shortcutId,+}: {+ complete: boolean;+ label: React.ReactNode;+ shortcutId?: KeyboardShortcutId;+}) {+ return (+ <li className="flex items-center gap-2 py-0.5 text-sm">+ <Checkbox+ checked={complete}+ disabled+ aria-hidden+ tabIndex={-1}+ className="pointer-events-none opacity-100 disabled:opacity-100"+ />+ <span className={complete ? 'flex-1 text-muted-foreground/60' : 'flex-1'}>+ {complete ? (+ <span className="sr-only">+ <Trans>Completed:</Trans>{' '}+ </span>+ ) : null}+ {label}+ </span>+ {shortcutId ? <Kbd>{formatShortcut(shortcutId)}</Kbd> : null}+ </li>+ );+}++export function OnboardingCard({+ store = onboardingCardStore,+ lingerMs = SUCCESS_LINGER_MS,+}: {+ store?: OnboardingCardStore;+ lingerMs?: number;+}) {+ const { t } = useLingui();+ const { steps } = useOnboardingCardState(store);+ useOnboardingFileCompletion(store);+ const [celebrateSignal, setCelebrateSignal] = useState(0);+ const [exiting, setExiting] = useState(false);++ const completedCount = 1 + (steps.file ? 1 : 0) + (steps.askedAi ? 1 : 0);+ const allComplete = completedCount === TOTAL_STEPS;++ useEffect(() => {+ if (!allComplete) return;+ setCelebrateSignal((n) => n + 1);+ const burst = setInterval(() => setCelebrateSignal((n) => n + 1), CELEBRATE_BURST_MS);+ const startExit = setTimeout(() => {+ clearInterval(burst);+ setExiting(true);+ }, lingerMs);+ return () => {+ clearInterval(burst);+ clearTimeout(startExit);+ };+ }, [allComplete, lingerMs]);++ useEffect(() => {+ if (!exiting) return;+ const done = setTimeout(() => store.markCompleted(), EXIT_MS);+ return () => clearTimeout(done);+ }, [exiting, store]);++ return (+ <>+ {/* Live region mounted unconditionally (pre-registered empty) so the+ completion announcement is reliable on VoiceOver/Safari — a region+ added and populated in the same render cycle is missed. Reduced-motion+ users who can't see the blob celebration rely on this. WCAG 4.1.3. */}+ <div className="sr-only" role="status" aria-live="polite">+ {allComplete ? t`You're all set up!` : ''}+ </div>++ {allComplete ? (+ <section+ aria-hidden+ className={cn(+ 'mx-2 mb-1 flex items-center gap-3 rounded-lg border bg-card px-4 py-3 text-card-foreground',+ 'motion-reduce:animate-none motion-reduce:duration-0',+ exiting+ ? // fill-mode-forwards holds the faded-out end state until unmount;+ 'animate-out fade-out-0 zoom-out-95 fill-mode-forwards duration-200'+ : 'animate-in fade-in-0 zoom-in-95 duration-300',+ )}+ >+ {/* celebrateSignal fires Blobby's happy-eyes + firework burst; bumped+ on an interval so the celebration keeps popping over its dwell. */}+ <OkBlob size={36} celebrateSignal={celebrateSignal} />+ <span className="font-medium text-sm">+ <Trans>You're all set up!</Trans>+ </span>+ </section>+ ) : (+ <section+ aria-labelledby="onboarding-card-heading"+ className="mx-2 mb-1 rounded-lg border bg-card px-4 py-3 text-card-foreground"+ >+ <header className="mb-3 flex items-center justify-between">+ <h2 id="onboarding-card-heading" className="font-medium text-sm">+ <Trans>Get set up</Trans>+ </h2>+ <span className="text-muted-foreground/60 text-xs tabular-nums">+ {`${completedCount} / ${TOTAL_STEPS}`}+ </span>+ </header>++ <ul className="flex flex-col gap-2">+ <StepRow complete label={<Trans>Create your first project</Trans>} />+ <StepRow+ complete={steps.file}+ label={<Trans>Create your first file</Trans>}+ shortcutId="new-item"+ />+ <StepRow+ complete={steps.askedAi}+ label={<Trans>Ask AI</Trans>}+ shortcutId="open-ask-ai"+ />+ </ul>++ <footer className="-mb-1 mt-2 flex justify-end">+ <Button+ type="button"+ variant="ghost"+ size="sm"+ className="h-auto px-2 py-1 text-muted-foreground text-xs"+ onClick={() => store.dismiss()}+ >+ <Trans>Dismiss</Trans>+ </Button>+ </footer>+ </section>+ )}+ </>+ );+}++export function OnboardingCardMount() {+ const visible = useOnboardingCardVisible();+ if (!visible) return null;+ return <OnboardingCard />;+}diff --git a/packages/app/src/components/OnboardingCardMount.dom.test.tsx b/packages/app/src/components/OnboardingCardMount.dom.test.tsxnew file mode 100644index 000000000..e3feec27c--- /dev/null+++ b/packages/app/src/components/OnboardingCardMount.dom.test.tsx@@ -0,0 +1,35 @@+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';+import { cleanup, render, screen } from '@testing-library/react';++let mockVisible = false;+mock.module('@/hooks/use-onboarding-card-visible', () => ({+ useOnboardingCardVisible: () => mockVisible,+}));++import { OnboardingCardMount } from './OnboardingCard';++let originalFetch: typeof globalThis.fetch;+beforeEach(() => {+ originalFetch = globalThis.fetch;+ globalThis.fetch = mock(() =>+ Promise.resolve(new Response(JSON.stringify({ documents: [] }), { status: 200 })),+ ) as never;+});+afterEach(() => {+ cleanup();+ globalThis.fetch = originalFetch;+});++describe('OnboardingCardMount', () => {+ test('renders nothing when the visibility predicate is false', () => {+ mockVisible = false;+ const { container } = render(<OnboardingCardMount />);+ expect(container.firstChild).toBeNull();+ });++ test('renders the onboarding card when visible', () => {+ mockVisible = true;+ render(<OnboardingCardMount />);+ expect(screen.getByText('Get set up')).toBeTruthy();+ });+});diff --git a/packages/app/src/hooks/use-onboarding-card-visible.dom.test.tsx b/packages/app/src/hooks/use-onboarding-card-visible.dom.test.tsxnew file mode 100644index 000000000..3ab7104c7--- /dev/null+++ b/packages/app/src/hooks/use-onboarding-card-visible.dom.test.tsx@@ -0,0 +1,155 @@+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';+import { act, cleanup, render, screen, waitFor } from '@testing-library/react';+import {+ createOnboardingCardStore,+ type OnboardingCardStorage,+ type OnboardingCardStore,+} from '@/lib/onboarding-card-store';+import { useOnboardingCardVisible } from './use-onboarding-card-visible';++const CURRENT_PATH = '/Users/me/project';++function memoryStorage(): OnboardingCardStorage {+ const map = new Map<string, string>();+ return {+ getItem: (k) => map.get(k) ?? null,+ setItem: (k, v) => {+ map.set(k, v);+ },+ };+}++function setDesktopHost(recents: Array<{ path: string }>): void {+ (window as unknown as { okDesktop: unknown }).okDesktop = {+ project: { listRecent: () => Promise.resolve(recents) },+ config: { projectPath: CURRENT_PATH },+ };+}++function clearDesktopHost(): void {+ (window as unknown as { okDesktop?: unknown }).okDesktop = undefined;+}++function mockDocuments(documents: unknown[]): void {+ globalThis.fetch = mock(() =>+ Promise.resolve(new Response(JSON.stringify({ documents }), { status: 200 })),+ ) as never;+}++function Probe({ store }: { store: OnboardingCardStore }) {+ const visible = useOnboardingCardVisible(store);+ return <div data-testid="visible">{String(visible)}</div>;+}++let originalFetch: typeof globalThis.fetch;+beforeEach(() => {+ originalFetch = globalThis.fetch;+});+afterEach(() => {+ cleanup();+ globalThis.fetch = originalFetch;+ clearDesktopHost();+});++describe('useOnboardingCardVisible', () => {+ test('no desktop host → never visible, never activates', async () => {+ clearDesktopHost();+ const fetchMock = mock(() =>+ Promise.resolve(new Response(JSON.stringify({ documents: [] }), { status: 200 })),+ );+ globalThis.fetch = fetchMock as never;+ const store = createOnboardingCardStore(memoryStorage());+ render(<Probe store={store} />);+ await act(async () => {});+ expect(fetchMock).not.toHaveBeenCalled();+ expect(screen.getByTestId('visible').textContent).toBe('false');+ expect(store.getSnapshot().initialized).toBe(false);+ });++ test('fresh single-project desktop session → activates and becomes visible', async () => {+ setDesktopHost([{ path: CURRENT_PATH }]);+ mockDocuments([]);+ const store = createOnboardingCardStore(memoryStorage());+ render(<Probe store={store} />);+ await waitFor(() => expect(screen.getByTestId('visible').textContent).toBe('true'));+ expect(store.getSnapshot().initialized).toBe(true);+ });++ test('established session (other project present) → stays hidden', async () => {+ const listRecent = mock(() => Promise.resolve([{ path: CURRENT_PATH }, { path: '/other' }]));+ (window as unknown as { okDesktop: unknown }).okDesktop = {+ project: { listRecent },+ config: { projectPath: CURRENT_PATH },+ };+ mockDocuments([]);+ const store = createOnboardingCardStore(memoryStorage());+ render(<Probe store={store} />);+ await waitFor(() => expect(listRecent).toHaveBeenCalled());+ await act(async () => {});+ expect(screen.getByTestId('visible').textContent).toBe('false');+ expect(store.getSnapshot().initialized).toBe(false);+ });++ test('dismissed store → hidden and skips evaluation', async () => {+ const fetchMock = mock(() =>+ Promise.resolve(new Response(JSON.stringify({ documents: [] }), { status: 200 })),+ );+ globalThis.fetch = fetchMock as never;+ setDesktopHost([{ path: CURRENT_PATH }]);+ const store = createOnboardingCardStore(memoryStorage());+ store.dismiss();+ render(<Probe store={store} />);+ await act(async () => {});+ expect(fetchMock).not.toHaveBeenCalled();+ expect(screen.getByTestId('visible').textContent).toBe('false');+ });++ test('latch: stays visible after a step completes (entry count no longer 0)', async () => {+ setDesktopHost([{ path: CURRENT_PATH }]);+ mockDocuments([]);+ const store = createOnboardingCardStore(memoryStorage());+ render(<Probe store={store} />);+ await waitFor(() => expect(screen.getByTestId('visible').textContent).toBe('true'));+ act(() => {+ store.markStepComplete('file');+ });+ expect(screen.getByTestId('visible').textContent).toBe('true');+ });++ test('completed store → hidden forever', async () => {+ const fetchMock = mock(() =>+ Promise.resolve(new Response(JSON.stringify({ documents: [] }), { status: 200 })),+ );+ globalThis.fetch = fetchMock as never;+ setDesktopHost([{ path: CURRENT_PATH }]);+ const store = createOnboardingCardStore(memoryStorage());+ store.markCompleted();+ render(<Probe store={store} />);+ await act(async () => {});+ expect(fetchMock).not.toHaveBeenCalled();+ expect(screen.getByTestId('visible').textContent).toBe('false');+ });++ test('cancels a pending activation when the probe unmounts mid-flight', async () => {+ let resolveRecents!: (r: Array<{ path: string }>) => void;+ const listRecent = mock(+ () =>+ new Promise<Array<{ path: string }>>((res) => {+ resolveRecents = res;+ }),+ );+ (window as unknown as { okDesktop: unknown }).okDesktop = {+ project: { listRecent },+ config: { projectPath: CURRENT_PATH },+ };+ mockDocuments([]);+ const store = createOnboardingCardStore(memoryStorage());+ const view = render(<Probe store={store} />);+ await waitFor(() => expect(listRecent).toHaveBeenCalled());+ view.unmount();+ await act(async () => {+ resolveRecents([{ path: CURRENT_PATH }]);+ });+ expect(store.getSnapshot().initialized).toBe(false);+ });+});diff --git a/packages/app/src/hooks/use-onboarding-card-visible.test.ts b/packages/app/src/hooks/use-onboarding-card-visible.test.tsnew file mode 100644index 000000000..15287f4ed--- /dev/null+++ b/packages/app/src/hooks/use-onboarding-card-visible.test.ts@@ -0,0 +1,76 @@+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';+import type { OkDesktopBridge } from '@/lib/desktop-bridge-types';+import { evaluateFreshProject } from './use-onboarding-card-visible';++const CURRENT_PATH = '/Users/me/project';++function bridgeWith(recents: Array<{ path: string }>): OkDesktopBridge {+ return {+ project: { listRecent: () => Promise.resolve(recents) },+ config: { projectPath: CURRENT_PATH },+ } as unknown as OkDesktopBridge;+}++function rejectingBridge(): OkDesktopBridge {+ return {+ project: { listRecent: () => Promise.reject(new Error('IPC down')) },+ config: { projectPath: CURRENT_PATH },+ } as unknown as OkDesktopBridge;+}++function mockDocumentsResponse(body: unknown, status = 200): void {+ globalThis.fetch = mock(() =>+ Promise.resolve(new Response(JSON.stringify(body), { status })),+ ) as never;+}++const aDocument = { kind: 'document', docName: 'welcome', size: 0, modified: '2026-06-30' };++let originalFetch: typeof globalThis.fetch;+beforeEach(() => {+ originalFetch = globalThis.fetch;+});+afterEach(() => {+ globalThis.fetch = originalFetch;+});++describe('evaluateFreshProject', () => {+ test('fresh single project with zero entries → true', async () => {+ mockDocumentsResponse({ documents: [] });+ expect(await evaluateFreshProject(bridgeWith([{ path: CURRENT_PATH }]))).toBe(true);+ });++ test('an empty recents list still counts as no-other-project → true when empty', async () => {+ mockDocumentsResponse({ documents: [] });+ expect(await evaluateFreshProject(bridgeWith([]))).toBe(true);+ });++ test('a second switchable project → false (does not fetch documents)', async () => {+ const fetchSpy = mock(() => Promise.resolve(new Response('{}', { status: 200 })));+ globalThis.fetch = fetchSpy as never;+ expect(+ await evaluateFreshProject(bridgeWith([{ path: CURRENT_PATH }, { path: '/other/project' }])),+ ).toBe(false);+ expect(fetchSpy).not.toHaveBeenCalled();+ });++ test('project already has content → false', async () => {+ mockDocumentsResponse({ documents: [aDocument] });+ expect(await evaluateFreshProject(bridgeWith([{ path: CURRENT_PATH }]))).toBe(false);+ });++ test('listRecent rejection is suppressed → false (fail-safe)', async () => {+ mockDocumentsResponse({ documents: [] });+ expect(await evaluateFreshProject(rejectingBridge())).toBe(false);+ });++ test('non-ok /api/documents response → false (fail-safe)', async () => {+ mockDocumentsResponse({ error: 'boom' }, 500);+ expect(await evaluateFreshProject(bridgeWith([{ path: CURRENT_PATH }]))).toBe(false);+ });++ test('schema-violating /api/documents body → false (fail-safe)', async () => {+ mockDocumentsResponse({ unexpected: 'shape' });+ expect(await evaluateFreshProject(bridgeWith([{ path: CURRENT_PATH }]))).toBe(false);+ });+});diff --git a/packages/app/src/hooks/use-onboarding-card-visible.ts b/packages/app/src/hooks/use-onboarding-card-visible.tsnew file mode 100644index 000000000..c4389c987--- /dev/null+++ b/packages/app/src/hooks/use-onboarding-card-visible.ts@@ -0,0 +1,45 @@++import { useEffect, useSyncExternalStore } from 'react';+import type { OkDesktopBridge } from '@/lib/desktop-bridge-types';+import { type OnboardingCardStore, onboardingCardStore } from '@/lib/onboarding-card-store';+import { fetchDocumentEntryCount } from '@/lib/onboarding-document-count';++export async function evaluateFreshProject(bridge: OkDesktopBridge): Promise<boolean> {+ try {+ const recents = await bridge.project.listRecent();+ const currentPath = bridge.config.projectPath;+ const hasOtherProject = recents.some((entry) => entry.path !== currentPath);+ if (hasOtherProject) return false;+ return (await fetchDocumentEntryCount()) === 0;+ } catch (err) {+ console.warn('[onboarding-card-visible] fresh-project probe failed; suppressing card', err);+ return false;+ }+}++export function useOnboardingCardVisible(+ store: OnboardingCardStore = onboardingCardStore,+): boolean {+ const { initialized, dismissed, completed } = useSyncExternalStore(+ store.subscribe,+ store.getSnapshot,+ store.getSnapshot,+ );+ const suppressed = dismissed || completed;+ const shouldEvaluate = !initialized && !suppressed;++ useEffect(() => {+ if (!shouldEvaluate) return;+ const bridge = window.okDesktop;+ if (bridge == null) return;+ let cancelled = false;+ void evaluateFreshProject(bridge).then((isFresh) => {+ if (!cancelled && isFresh) store.activate();+ });+ return () => {+ cancelled = true;+ };+ }, [shouldEvaluate, store]);++ return initialized && !suppressed;+}diff --git a/packages/app/src/hooks/use-onboarding-file-completion.dom.test.tsx b/packages/app/src/hooks/use-onboarding-file-completion.dom.test.tsxnew file mode 100644index 000000000..aedcf8a88--- /dev/null+++ b/packages/app/src/hooks/use-onboarding-file-completion.dom.test.tsx@@ -0,0 +1,108 @@+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';+import { act, cleanup, render, waitFor } from '@testing-library/react';+import { emitDocumentsChanged } from '@/lib/documents-events';+import {+ createOnboardingCardStore,+ type OnboardingCardStorage,+ type OnboardingCardStore,+} from '@/lib/onboarding-card-store';+import { useOnboardingFileCompletion } from './use-onboarding-file-completion';++function freshStore(): OnboardingCardStore {+ const map = new Map<string, string>();+ const storage: OnboardingCardStorage = {+ getItem: (k) => map.get(k) ?? null,+ setItem: (k, v) => {+ map.set(k, v);+ },+ };+ return createOnboardingCardStore(storage);+}++function mockDocuments(documents: unknown[]): void {+ globalThis.fetch = mock(() =>+ Promise.resolve(new Response(JSON.stringify({ documents }), { status: 200 })),+ ) as never;+}++const aDocument = { kind: 'document', docName: 'welcome', size: 0, modified: '2026-06-30' };++function Probe({ store }: { store: OnboardingCardStore }) {+ useOnboardingFileCompletion(store);+ return null;+}++let originalFetch: typeof globalThis.fetch;+beforeEach(() => {+ originalFetch = globalThis.fetch;+});+afterEach(() => {+ cleanup();+ globalThis.fetch = originalFetch;+});++describe('useOnboardingFileCompletion', () => {+ test('marks the file step when a files change reveals content', async () => {+ mockDocuments([]);+ const store = freshStore();+ store.activate();+ render(<Probe store={store} />);+ mockDocuments([aDocument]);+ emitDocumentsChanged(['files']);+ await waitFor(() => expect(store.getSnapshot().steps.file).toBe(true));+ });++ test('ignores non-files channels — no extra fetch on graph/backlinks updates', async () => {+ const fetchMock = mock(() =>+ Promise.resolve(new Response(JSON.stringify({ documents: [] }), { status: 200 })),+ );+ globalThis.fetch = fetchMock as never;+ const store = freshStore();+ store.activate();+ render(<Probe store={store} />);+ await waitFor(() => expect(fetchMock.mock.calls.length).toBeGreaterThanOrEqual(1));+ const afterMount = fetchMock.mock.calls.length;+ emitDocumentsChanged(['graph']);+ emitDocumentsChanged(['backlinks']);+ await act(async () => {});+ expect(fetchMock.mock.calls.length).toBe(afterMount);+ });++ test('marks the file step at mount when content already exists', async () => {+ mockDocuments([aDocument]);+ const store = freshStore();+ store.activate();+ render(<Probe store={store} />);+ await waitFor(() => expect(store.getSnapshot().steps.file).toBe(true));+ });++ test('does not mark the step while the project stays empty', async () => {+ const fetchMock = mock(() =>+ Promise.resolve(new Response(JSON.stringify({ documents: [] }), { status: 200 })),+ );+ globalThis.fetch = fetchMock as never;+ const store = freshStore();+ store.activate();+ render(<Probe store={store} />);+ emitDocumentsChanged(['files']);+ await waitFor(() => expect(fetchMock.mock.calls.length).toBeGreaterThanOrEqual(2));+ await act(async () => {});+ expect(store.getSnapshot().steps.file).toBe(false);+ });++ test('skips subscribing and fetching when the file step is already complete', async () => {+ const fetchMock = mock(() =>+ Promise.resolve(new Response(JSON.stringify({ documents: [] }), { status: 200 })),+ );+ globalThis.fetch = fetchMock as never;+ const store = freshStore();+ store.activate();+ store.markStepComplete('file'); // already complete before mount+ render(<Probe store={store} />);+ await act(async () => {});+ expect(fetchMock).not.toHaveBeenCalled();+ emitDocumentsChanged(['files']);+ await act(async () => {});+ expect(fetchMock).not.toHaveBeenCalled();+ });+});diff --git a/packages/app/src/hooks/use-onboarding-file-completion.ts b/packages/app/src/hooks/use-onboarding-file-completion.tsnew file mode 100644index 000000000..50449b200--- /dev/null+++ b/packages/app/src/hooks/use-onboarding-file-completion.ts@@ -0,0 +1,18 @@++import { useEffect } from 'react';+import { subscribeToDocumentsChanged } from '@/lib/documents-events';+import { type OnboardingCardStore, onboardingCardStore } from '@/lib/onboarding-card-store';+import { recordOnboardingFileStep } from '@/lib/onboarding-signals';++export function useOnboardingFileCompletion(+ store: OnboardingCardStore = onboardingCardStore,+): void {+ useEffect(() => {+ if (store.getSnapshot().steps.file) return;+ const unsubscribe = subscribeToDocumentsChanged((channels) => {+ if (channels.includes('files')) void recordOnboardingFileStep(store);+ });+ void recordOnboardingFileStep(store);+ return unsubscribe;+ }, [store]);+}diff --git a/packages/app/src/lib/onboarding-card-store.test.ts b/packages/app/src/lib/onboarding-card-store.test.tsnew file mode 100644index 000000000..7fea65529--- /dev/null+++ b/packages/app/src/lib/onboarding-card-store.test.ts@@ -0,0 +1,281 @@+import { describe, expect, test } from 'bun:test';+import {+ createOnboardingCardStore,+ DEFAULT_ONBOARDING_CARD_STATE,+ ONBOARDING_CARD_STORAGE_KEY,+ type OnboardingCardStorage,+ readPersistedState,+ writePersistedState,+} from './onboarding-card-store.ts';++function memoryStorage(initial: Record<string, string> = {}): OnboardingCardStorage {+ const data = new Map(Object.entries(initial));+ return {+ getItem(key) {+ return data.get(key) ?? null;+ },+ setItem(key, value) {+ data.set(key, value);+ },+ };+}++describe('readPersistedState', () => {+ test('absent key returns default', () => {+ expect(readPersistedState(memoryStorage())).toEqual(DEFAULT_ONBOARDING_CARD_STATE);+ });++ test('round-trips a fully populated state', () => {+ const stored = {+ initialized: true,+ steps: { file: true, askedAi: true },+ dismissed: false,+ completed: true,+ };+ const s = memoryStorage({ [ONBOARDING_CARD_STORAGE_KEY]: JSON.stringify(stored) });+ expect(readPersistedState(s)).toEqual(stored);+ });++ test('missing fields default to false', () => {+ const s = memoryStorage({+ [ONBOARDING_CARD_STORAGE_KEY]: JSON.stringify({ steps: { file: true } }),+ });+ expect(readPersistedState(s)).toEqual({+ initialized: false,+ steps: { file: true, askedAi: false },+ dismissed: false,+ completed: false,+ });+ });++ test('non-boolean field values are coerced to false', () => {+ const s = memoryStorage({+ [ONBOARDING_CARD_STORAGE_KEY]: JSON.stringify({+ dismissed: 'yes',+ completed: 1,+ steps: { file: 'true', askedAi: null },+ }),+ });+ const read = readPersistedState(s);+ expect(read.dismissed).toBe(false);+ expect(read.completed).toBe(false);+ expect(read.steps).toEqual({ file: false, askedAi: false });+ });++ test('corrupt JSON falls back to default', () => {+ const s = memoryStorage({ [ONBOARDING_CARD_STORAGE_KEY]: '{not valid json' });+ expect(readPersistedState(s)).toEqual(DEFAULT_ONBOARDING_CARD_STATE);+ });++ test('non-object JSON falls back to default', () => {+ const s = memoryStorage({ [ONBOARDING_CARD_STORAGE_KEY]: '"a string"' });+ expect(readPersistedState(s)).toEqual(DEFAULT_ONBOARDING_CARD_STATE);+ });++ test('returns default when getItem throws (SecurityError / private browsing)', () => {+ const throwingStorage: OnboardingCardStorage = {+ getItem: () => {+ throw new DOMException('SecurityError');+ },+ setItem: () => {},+ };+ expect(readPersistedState(throwingStorage)).toEqual(DEFAULT_ONBOARDING_CARD_STATE);+ });+});++describe('writePersistedState', () => {+ test('a written state reads back identically (reload round-trip)', () => {+ const s = memoryStorage();+ const next = { ...DEFAULT_ONBOARDING_CARD_STATE, dismissed: true, completed: true };+ writePersistedState(next, s);+ expect(readPersistedState(s)).toEqual(next);+ });++ test('does not throw when setItem throws (quota exceeded)', () => {+ const throwingStorage: OnboardingCardStorage = {+ getItem: () => null,+ setItem: () => {+ throw new DOMException('QuotaExceededError');+ },+ };+ expect(() => writePersistedState(DEFAULT_ONBOARDING_CARD_STATE, throwingStorage)).not.toThrow();+ });+});++describe('createOnboardingCardStore — mutations', () => {+ test('markStepComplete checks the named step', () => {+ const store = createOnboardingCardStore(memoryStorage());+ store.markStepComplete('file');+ expect(store.getSnapshot().steps).toEqual({ file: true, askedAi: false });+ });++ test('steps are independent', () => {+ const store = createOnboardingCardStore(memoryStorage());+ store.markStepComplete('askedAi');+ expect(store.getSnapshot().steps).toEqual({ file: false, askedAi: true });+ });++ test('activate latches initialized', () => {+ const store = createOnboardingCardStore(memoryStorage());+ expect(store.getSnapshot().initialized).toBe(false);+ store.activate();+ expect(store.getSnapshot().initialized).toBe(true);+ });++ test('dismiss sets the dismissed flag', () => {+ const store = createOnboardingCardStore(memoryStorage());+ store.dismiss();+ expect(store.getSnapshot().dismissed).toBe(true);+ });++ test('markCompleted sets the completed flag', () => {+ const store = createOnboardingCardStore(memoryStorage());+ store.markCompleted();+ expect(store.getSnapshot().completed).toBe(true);+ });+});++describe('createOnboardingCardStore — persistence across remount', () => {+ test('dismiss persists so a fresh store reads it back true', () => {+ const shared = memoryStorage();+ createOnboardingCardStore(shared).dismiss();+ expect(createOnboardingCardStore(shared).getSnapshot().dismissed).toBe(true);+ });++ test('markCompleted persists so a fresh store reads it back true', () => {+ const shared = memoryStorage();+ createOnboardingCardStore(shared).markCompleted();+ expect(createOnboardingCardStore(shared).getSnapshot().completed).toBe(true);+ });++ test('step completion persists across remount', () => {+ const shared = memoryStorage();+ createOnboardingCardStore(shared).markStepComplete('file');+ expect(createOnboardingCardStore(shared).getSnapshot().steps.file).toBe(true);+ });++ test('completion state persists across remount', () => {+ const shared = memoryStorage();+ createOnboardingCardStore(shared).markCompleted();+ expect(createOnboardingCardStore(shared).getSnapshot().completed).toBe(true);+ });+});++describe('createOnboardingCardStore — idempotence', () => {+ test('markStepComplete twice does not notify the second time', () => {+ const store = createOnboardingCardStore(memoryStorage());+ let notifications = 0;+ store.subscribe(() => {+ notifications += 1;+ });+ store.markStepComplete('file');+ store.markStepComplete('file');+ expect(notifications).toBe(1);+ expect(store.getSnapshot().steps.file).toBe(true);+ });++ test('dismiss twice does not notify the second time', () => {+ const store = createOnboardingCardStore(memoryStorage());+ let notifications = 0;+ store.subscribe(() => {+ notifications += 1;+ });+ store.dismiss();+ store.dismiss();+ expect(notifications).toBe(1);+ });++ test('activate twice does not notify the second time', () => {+ const store = createOnboardingCardStore(memoryStorage());+ let notifications = 0;+ store.subscribe(() => {+ notifications += 1;+ });+ store.activate();+ store.activate();+ expect(notifications).toBe(1);+ });++ test('markStepComplete for an already-complete step is a no-op', () => {+ const store = createOnboardingCardStore(memoryStorage());+ store.markStepComplete('file');+ let notifications = 0;+ store.subscribe(() => {+ notifications += 1;+ });+ store.markStepComplete('file');+ expect(notifications).toBe(0);+ });+});++describe('createOnboardingCardStore — subscription', () => {+ test('a subscribed listener is notified on mutation', () => {+ const store = createOnboardingCardStore(memoryStorage());+ let notified = false;+ store.subscribe(() => {+ notified = true;+ });+ store.markStepComplete('askedAi');+ expect(notified).toBe(true);+ });++ test('an unsubscribed listener is not notified', () => {+ const store = createOnboardingCardStore(memoryStorage());+ let notifications = 0;+ const unsubscribe = store.subscribe(() => {+ notifications += 1;+ });+ unsubscribe();+ store.dismiss();+ expect(notifications).toBe(0);+ });++ test('getSnapshot returns a stable reference until a mutation occurs', () => {+ const store = createOnboardingCardStore(memoryStorage());+ const first = store.getSnapshot();+ expect(store.getSnapshot()).toBe(first);+ store.markStepComplete('file');+ expect(store.getSnapshot()).not.toBe(first);+ });+});++describe('createOnboardingCardStore — install', () => {+ test('install re-syncs from storage seeded after construction', () => {+ const shared = memoryStorage();+ const store = createOnboardingCardStore(shared);+ expect(store.getSnapshot().dismissed).toBe(false);+ shared.setItem(+ ONBOARDING_CARD_STORAGE_KEY,+ JSON.stringify({ ...DEFAULT_ONBOARDING_CARD_STATE, dismissed: true }),+ );+ store.install();+ expect(store.getSnapshot().dismissed).toBe(true);+ });++ test('install is idempotent — a second call does not re-sync', () => {+ const shared = memoryStorage();+ const store = createOnboardingCardStore(shared);+ store.install();+ shared.setItem(+ ONBOARDING_CARD_STORAGE_KEY,+ JSON.stringify({ ...DEFAULT_ONBOARDING_CARD_STATE, completed: true }),+ );+ store.install();+ expect(store.getSnapshot().completed).toBe(false);+ });++ test('install notifies subscribers when it re-syncs', () => {+ const shared = memoryStorage();+ const store = createOnboardingCardStore(shared);+ let notified = false;+ store.subscribe(() => {+ notified = true;+ });+ store.install();+ expect(notified).toBe(true);+ });++ test('construct + install over the default storage path does not throw', () => {+ expect(() => createOnboardingCardStore().install()).not.toThrow();+ });+});diff --git a/packages/app/src/lib/onboarding-card-store.ts b/packages/app/src/lib/onboarding-card-store.tsnew file mode 100644index 000000000..aee384c45--- /dev/null+++ b/packages/app/src/lib/onboarding-card-store.ts@@ -0,0 +1,149 @@++import { useSyncExternalStore } from 'react';++export const ONBOARDING_CARD_STORAGE_KEY = 'ok-onboarding-card-v1';++type OnboardingStep = 'file' | 'askedAi';++export interface OnboardingCardState {+ readonly initialized: boolean;+ readonly steps: {+ readonly file: boolean;+ readonly askedAi: boolean;+ };+ readonly dismissed: boolean;+ readonly completed: boolean;+}++export const DEFAULT_ONBOARDING_CARD_STATE: OnboardingCardState = {+ initialized: false,+ steps: { file: false, askedAi: false },+ dismissed: false,+ completed: false,+};++export interface OnboardingCardStorage {+ getItem(key: string): string | null;+ setItem(key: string, value: string): void;+}++export interface OnboardingCardStore {+ getSnapshot(): OnboardingCardState;+ subscribe(listener: () => void): () => void;+ activate(): void;+ markStepComplete(step: OnboardingStep): void;+ dismiss(): void;+ markCompleted(): void;+ install(): void;+}++function asFlag(value: unknown): boolean {+ return value === true;+}++function coerceState(parsed: unknown): OnboardingCardState {+ if (typeof parsed !== 'object' || parsed === null) return DEFAULT_ONBOARDING_CARD_STATE;+ const obj = parsed as Record<string, unknown>;+ const steps =+ typeof obj.steps === 'object' && obj.steps !== null+ ? (obj.steps as Record<string, unknown>)+ : {};+ return {+ initialized: asFlag(obj.initialized),+ steps: { file: asFlag(steps.file), askedAi: asFlag(steps.askedAi) },+ dismissed: asFlag(obj.dismissed),+ completed: asFlag(obj.completed),+ };+}++export function readPersistedState(storage?: OnboardingCardStorage): OnboardingCardState {+ try {+ const s = storage ?? localStorage;+ const raw = s.getItem(ONBOARDING_CARD_STORAGE_KEY);+ if (raw == null) return DEFAULT_ONBOARDING_CARD_STATE;+ return coerceState(JSON.parse(raw));+ } catch (err) {+ console.warn('[onboarding-card-store] readPersistedState failed (corrupt/privacy/SSR)', err);+ return DEFAULT_ONBOARDING_CARD_STATE;+ }+}++export function writePersistedState(+ state: OnboardingCardState,+ storage?: OnboardingCardStorage,+): void {+ try {+ const s = storage ?? localStorage;+ s.setItem(ONBOARDING_CARD_STORAGE_KEY, JSON.stringify(state));+ } catch (err) {+ console.warn('[onboarding-card-store] writePersistedState failed (quota/privacy/SSR)', err);+ }+}++export function createOnboardingCardStore(storage?: OnboardingCardStorage): OnboardingCardStore {+ let state = readPersistedState(storage);+ const listeners = new Set<() => void>();+ let installed = false;++ function notify(): void {+ for (const listener of listeners) listener();+ }++ function commit(next: OnboardingCardState): void {+ state = next;+ writePersistedState(state, storage);+ notify();+ }++ return {+ getSnapshot(): OnboardingCardState {+ return state;+ },++ subscribe(listener): () => void {+ listeners.add(listener);+ return () => {+ listeners.delete(listener);+ };+ },++ activate(): void {+ if (state.initialized) return;+ commit({ ...state, initialized: true });+ },++ markStepComplete(step): void {+ if (state.steps[step]) return;+ commit({ ...state, steps: { ...state.steps, [step]: true } });+ },++ dismiss(): void {+ if (state.dismissed) return;+ commit({ ...state, dismissed: true });+ },++ markCompleted(): void {+ if (state.completed) return;+ commit({ ...state, completed: true });+ },++ install(): void {+ if (installed) return;+ installed = true;+ state = readPersistedState(storage);+ notify();+ },+ };+}++export const onboardingCardStore: OnboardingCardStore = createOnboardingCardStore();++export function useOnboardingCardState(+ store: OnboardingCardStore = onboardingCardStore,+): OnboardingCardState {+ return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);+}++export function installOnboardingCardStore(): void {+ onboardingCardStore.install();+}diff --git a/packages/app/src/lib/onboarding-document-count.test.ts b/packages/app/src/lib/onboarding-document-count.test.tsnew file mode 100644index 000000000..a2507c499--- /dev/null+++ b/packages/app/src/lib/onboarding-document-count.test.ts@@ -0,0 +1,50 @@+import { describe, expect, test } from 'bun:test';+import type { DocumentListSuccess } from '@inkeep/open-knowledge-core';+import { countVisibleEntries } from './onboarding-document-count';++type Entry = DocumentListSuccess['documents'][number];++const base = {+ docExt: '.md',+ size: 0,+ modified: '2026-06-30',+ isSymlink: false,+ canonicalDocName: null,+ targetPath: null,+} as const;++const doc = (docName: string): Entry => ({ ...base, kind: 'document', docName }) as Entry;+const folder = (path: string): Entry => ({ ...base, kind: 'folder', path }) as Entry;+const asset = (path: string): Entry =>+ ({ ...base, kind: 'asset', path, assetExt: '.png', referencedBy: [] }) as Entry;+const file = (path: string): Entry => ({ ...base, kind: 'file', path }) as Entry;++describe('countVisibleEntries', () => {+ test('an empty project counts zero', () => {+ expect(countVisibleEntries([])).toBe(0);+ });++ test('counts documents', () => {+ expect(countVisibleEntries([doc('welcome'), doc('notes')])).toBe(2);+ });++ test('counts folders — starter packs often scaffold only folders', () => {+ expect(countVisibleEntries([folder('guides'), folder('references')])).toBe(2);+ });++ test('counts documents and folders together', () => {+ expect(countVisibleEntries([doc('welcome'), folder('guides'), doc('notes')])).toBe(3);+ });++ test('excludes assets and bare non-markdown files', () => {+ expect(countVisibleEntries([doc('welcome'), asset('logo.png'), file('data.csv')])).toBe(1);+ });++ test('excludes hidden entries (dotfiles, .ok config, .git)', () => {+ expect(countVisibleEntries([doc('welcome'), doc('.ok/config'), folder('.git')])).toBe(1);+ });++ test('excludes entries that ship without a docName or path', () => {+ expect(countVisibleEntries([doc(''), folder('')])).toBe(0);+ });+});diff --git a/packages/app/src/lib/onboarding-document-count.ts b/packages/app/src/lib/onboarding-document-count.tsnew file mode 100644index 000000000..0ec5f2e67--- /dev/null+++ b/packages/app/src/lib/onboarding-document-count.ts@@ -0,0 +1,19 @@++import { type DocumentListSuccess, DocumentListSuccessSchema } from '@inkeep/open-knowledge-core';+import { filterVisibleEntries } from '@/components/file-tree-utils';++export function countVisibleEntries(documents: DocumentListSuccess['documents']): number {+ return filterVisibleEntries(documents).filter(+ (entry) => entry.kind === 'document' || entry.kind === 'folder',+ ).length;+}++export async function fetchDocumentEntryCount(): Promise<number> {+ const response = await fetch('/api/documents');+ if (!response.ok) throw new Error(`documents request failed: ${response.status}`);+ const body = (await response.json()) as unknown;+ const parsed = DocumentListSuccessSchema.safeParse(body);+ if (!parsed.success)+ throw new Error('documents response did not match schema', { cause: parsed.error });+ return countVisibleEntries(parsed.data.documents);+}diff --git a/packages/app/src/lib/onboarding-signals.test.ts b/packages/app/src/lib/onboarding-signals.test.tsnew file mode 100644index 000000000..c83c9ea79--- /dev/null+++ b/packages/app/src/lib/onboarding-signals.test.ts@@ -0,0 +1,95 @@+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';+import {+ createOnboardingCardStore,+ type OnboardingCardStorage,+ type OnboardingCardStore,+} from './onboarding-card-store';+import { recordOnboardingAskedAi, recordOnboardingFileStep } from './onboarding-signals';++function freshStore(): OnboardingCardStore {+ const map = new Map<string, string>();+ const storage: OnboardingCardStorage = {+ getItem: (k) => map.get(k) ?? null,+ setItem: (k, v) => {+ map.set(k, v);+ },+ };+ return createOnboardingCardStore(storage);+}++function mockDocuments(documents: unknown[], status = 200): void {+ globalThis.fetch = mock(() =>+ Promise.resolve(new Response(JSON.stringify({ documents }), { status })),+ ) as never;+}++const aDocument = { kind: 'document', docName: 'welcome', size: 0, modified: '2026-06-30' };++let originalFetch: typeof globalThis.fetch;+beforeEach(() => {+ originalFetch = globalThis.fetch;+});+afterEach(() => {+ globalThis.fetch = originalFetch;+});++describe('recordOnboardingAskedAi', () => {+ test('marks the step when onboarding is active', () => {+ const store = freshStore();+ store.activate();+ recordOnboardingAskedAi(store);+ expect(store.getSnapshot().steps.askedAi).toBe(true);+ });++ test('no-op when onboarding was never activated (established user)', () => {+ const store = freshStore();+ recordOnboardingAskedAi(store);+ expect(store.getSnapshot().steps.askedAi).toBe(false);+ expect(store.getSnapshot().initialized).toBe(false);+ });+});++describe('recordOnboardingFileStep', () => {+ test('marks the file step when the project has at least one entry', async () => {+ mockDocuments([aDocument]);+ const store = freshStore();+ store.activate();+ await recordOnboardingFileStep(store);+ expect(store.getSnapshot().steps.file).toBe(true);+ });++ test('does not mark the file step when the project is still empty', async () => {+ mockDocuments([]);+ const store = freshStore();+ store.activate();+ await recordOnboardingFileStep(store);+ expect(store.getSnapshot().steps.file).toBe(false);+ });++ test('no-op when onboarding is not active (file created by an established user)', async () => {+ const fetchSpy = mock(() => Promise.resolve(new Response('{}', { status: 200 })));+ globalThis.fetch = fetchSpy as never;+ const store = freshStore();+ await recordOnboardingFileStep(store);+ expect(fetchSpy).not.toHaveBeenCalled();+ expect(store.getSnapshot().steps.file).toBe(false);+ });++ test('is a no-op (no fetch) when the step is already complete', async () => {+ const fetchSpy = mock(() => Promise.resolve(new Response('{}', { status: 200 })));+ globalThis.fetch = fetchSpy as never;+ const store = freshStore();+ store.activate();+ store.markStepComplete('file');+ await recordOnboardingFileStep(store);+ expect(fetchSpy).not.toHaveBeenCalled();+ });++ test('swallows a failed count read and leaves the step incomplete', async () => {+ mockDocuments({ error: 'boom' } as never, 500);+ const store = freshStore();+ store.activate();+ await recordOnboardingFileStep(store);+ expect(store.getSnapshot().steps.file).toBe(false);+ });+});diff --git a/packages/app/src/lib/onboarding-signals.ts b/packages/app/src/lib/onboarding-signals.tsnew file mode 100644index 000000000..62d8a1ab5--- /dev/null+++ b/packages/app/src/lib/onboarding-signals.ts@@ -0,0 +1,19 @@++import { type OnboardingCardStore, onboardingCardStore } from '@/lib/onboarding-card-store';+import { fetchDocumentEntryCount } from '@/lib/onboarding-document-count';++export async function recordOnboardingFileStep(+ store: OnboardingCardStore = onboardingCardStore,+): Promise<void> {+ const snapshot = store.getSnapshot();+ if (snapshot.steps.file || !snapshot.initialized) return;+ try {+ if ((await fetchDocumentEntryCount()) >= 1) store.markStepComplete('file');+ } catch (err) {+ console.warn('[onboarding-signals] file-step count read failed; leaving step incomplete', err);+ }+}++export function recordOnboardingAskedAi(store: OnboardingCardStore = onboardingCardStore): void {+ if (store.getSnapshot().initialized) store.markStepComplete('askedAi');+}diff --git a/packages/app/src/locales/en/messages.json b/packages/app/src/locales/en/messages.jsonindex 510089b03..ea818f9fc 100644--- a/packages/app/src/locales/en/messages.json+++ b/packages/app/src/locales/en/messages.json@@ -176,6 +176,7 @@"4A3Yzu": ["Code block"],"4BITzH": ["Error:"],"4CfgPM": ["Project folder created, but git init failed. Try again."],+ "4E9jPa": ["Create your first project"],"4Gz2wC": ["Failed to upload file"],"4KmEoC": ["Hotkeys"],"4NC2Ym": ["Move to the next or previous table cell."],@@ -320,6 +321,7 @@],"7d1a0d": ["Public"],"7hctf2": ["Describe the project you want to create"],+ "7jIIFX": ["You're all set up!"],"7qRHf0": ["Install for Claude Chat & Cowork"],"80c4-P": ["Code copied to clipboard"],"81H_23": ["Add properties"],@@ -973,6 +975,7 @@"QYfQdv": [["displayName"], " CLI"],"QcpeeE": ["Navigate to ", ["docName"]],"QfFBdJ": ["The template's filename (without `.md`)."],+ "Qj4RL5": ["Completed:"],"QlxHAH": ["Showing results for \"", ["semanticResultsLabel"], "\""],"QqBQu1": ["Label <0>(visible link text)</0>"],"Qvls7J": ["Eng specs"],@@ -1198,6 +1201,7 @@"XyOUTJ": ["Exit merge"],"Xzy0s0": ["Remove ", ["fullLabel"], " from context"],"Y-Urt2": ["Block math equation rendered with KaTeX from a LaTeX source string."],+ "Y1QMlM": ["Get set up"],"Y1kX2z": ["OpenKnowledge initializes at <0>",["projectDir"],diff --git a/packages/app/src/locales/en/messages.po b/packages/app/src/locales/en/messages.poindex 128ff9475..b16d428aa 100644--- a/packages/app/src/locales/en/messages.po+++ b/packages/app/src/locales/en/messages.po@@ -737,6 +737,7 @@ msgstr "Ask {0} CLI"#: src/components/BottomComposer.tsx#: src/components/EditorFooter.tsx+#: src/components/OnboardingCard.tsx#: src/editor/bubble-menu/EditWithAiBubbleButton.tsx#: src/lib/keyboard-shortcuts.tsmsgid "Ask AI"@@ -1293,6 +1294,10 @@ msgstr "Competitor research"msgid "Complete"msgstr "Complete"+#: src/components/OnboardingCard.tsx+msgid "Completed:"+msgstr "Completed:"+#: src/lib/keyboard-shortcuts.tsmsgid "Component boundary navigation"msgstr "Component boundary navigation"@@ -1901,9 +1906,14 @@ msgid "Create with {0} CLI"msgstr "Create with {0} CLI"#: src/components/FileTree.tsx+#: src/components/OnboardingCard.tsxmsgid "Create your first file"msgstr "Create your first file"+#: src/components/OnboardingCard.tsx+msgid "Create your first project"+msgstr "Create your first project"+#: src/components/FolderTimelineCard.tsxmsgid "created folder"msgstr "created folder"@@ -2116,6 +2126,7 @@ msgstr "Disconnecting"#: src/components/ClaudeReadinessBanner.tsx#: src/components/NavigatorApp.tsx+#: src/components/OnboardingCard.tsx#: src/components/settings/SharingSection.tsx#: src/components/TerminalCliMissingBanner.tsxmsgid "Dismiss"@@ -2932,6 +2943,10 @@ msgstr "Get Claude Code"msgid "Get product updates in your inbox."msgstr "Get product updates in your inbox."+#: src/components/OnboardingCard.tsx+msgid "Get set up"+msgstr "Get set up"+#: src/components/settings/SettingsDialogBody.tsxmsgid "Git auto-sync"msgstr "Git auto-sync"@@ -7040,6 +7055,10 @@ msgstr "You picked the filesystem root (/). Scaffolding here will scan every filmsgid "You picked your home directory. OpenKnowledge will index everything in your home tree — large and may surface personal files."msgstr "You picked your home directory. OpenKnowledge will index everything in your home tree — large and may surface personal files."+#: src/components/OnboardingCard.tsx+msgid "You're all set up!"+msgstr "You're all set up!"+#: src/components/SubscribeForm.tsxmsgid "You're subscribed!"msgstr "You're subscribed!"diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.jsonindex bf4924d40..cd1ce2931 100644--- a/packages/app/src/locales/pseudo/messages.json+++ b/packages/app/src/locales/pseudo/messages.json@@ -176,6 +176,7 @@"4A3Yzu": ["Ćōďē ƀĺōćķ"],"4BITzH": ["Ēŕŕōŕ:"],"4CfgPM": ["ƤŕōĴēćţ ƒōĺďēŕ ćŕēàţēď, ƀũţ ĝĩţ ĩńĩţ ƒàĩĺēď. Ţŕŷ àĝàĩń."],+ "4E9jPa": ["Ćŕēàţē ŷōũŕ ƒĩŕśţ ƥŕōĴēćţ"],"4Gz2wC": ["Ƒàĩĺēď ţō ũƥĺōàď ƒĩĺē"],"4KmEoC": ["Ĥōţķēŷś"],"4NC2Ym": ["Ḿōvē ţō ţĥē ńēxţ ōŕ ƥŕēvĩōũś ţàƀĺē ćēĺĺ."],@@ -320,6 +321,7 @@],"7d1a0d": ["Ƥũƀĺĩć"],"7hctf2": ["Ďēśćŕĩƀē ţĥē ƥŕōĴēćţ ŷōũ ŵàńţ ţō ćŕēàţē"],+ "7jIIFX": ["Ŷōũ'ŕē àĺĺ śēţ ũƥ!"],"7qRHf0": ["Ĩńśţàĺĺ ƒōŕ Ćĺàũďē Ćĥàţ & Ćōŵōŕķ"],"80c4-P": ["Ćōďē ćōƥĩēď ţō ćĺĩƥƀōàŕď"],"81H_23": ["Àďď ƥŕōƥēŕţĩēś"],@@ -973,6 +975,7 @@"QYfQdv": [["displayName"], " ĆĹĨ"],"QcpeeE": ["Ńàvĩĝàţē ţō ", ["docName"]],"QfFBdJ": ["Ţĥē ţēḿƥĺàţē'ś ƒĩĺēńàḿē (ŵĩţĥōũţ `.ḿď`)."],+ "Qj4RL5": ["Ćōḿƥĺēţēď:"],"QlxHAH": ["Śĥōŵĩńĝ ŕēśũĺţś ƒōŕ \"", ["semanticResultsLabel"], "\""],"QqBQu1": ["Ĺàƀēĺ <0>(vĩśĩƀĺē ĺĩńķ ţēxţ)</0>"],"Qvls7J": ["Ēńĝ śƥēćś"],@@ -1198,6 +1201,7 @@"XyOUTJ": ["Ēxĩţ ḿēŕĝē"],"Xzy0s0": ["Ŕēḿōvē ", ["fullLabel"], " ƒŕōḿ ćōńţēxţ"],"Y-Urt2": ["ßĺōćķ ḿàţĥ ēǫũàţĩōń ŕēńďēŕēď ŵĩţĥ ĶàŢēX ƒŕōḿ à ĹàŢēX śōũŕćē śţŕĩńĝ."],+ "Y1QMlM": ["Ĝēţ śēţ ũƥ"],"Y1kX2z": ["ŌƥēńĶńōŵĺēďĝē ĩńĩţĩàĺĩźēś àţ <0>",["projectDir"],diff --git a/packages/app/src/locales/pseudo/messages.po b/packages/app/src/locales/pseudo/messages.poindex 9f8f2dac2..b45765b0c 100644--- a/packages/app/src/locales/pseudo/messages.po+++ b/packages/app/src/locales/pseudo/messages.po@@ -732,6 +732,7 @@ msgstr ""#: src/components/BottomComposer.tsx#: src/components/EditorFooter.tsx+#: src/components/OnboardingCard.tsx#: src/editor/bubble-menu/EditWithAiBubbleButton.tsx#: src/lib/keyboard-shortcuts.tsmsgid "Ask AI"@@ -1288,6 +1289,10 @@ msgstr ""msgid "Complete"msgstr ""+#: src/components/OnboardingCard.tsx+msgid "Completed:"+msgstr ""+#: src/lib/keyboard-shortcuts.tsmsgid "Component boundary navigation"msgstr ""@@ -1896,9 +1901,14 @@ msgid "Create with {0} CLI"msgstr ""#: src/components/FileTree.tsx+#: src/components/OnboardingCard.tsxmsgid "Create your first file"msgstr ""+#: src/components/OnboardingCard.tsx+msgid "Create your first project"+msgstr ""+#: src/components/FolderTimelineCard.tsxmsgid "created folder"msgstr ""@@ -2111,6 +2121,7 @@ msgstr ""#: src/components/ClaudeReadinessBanner.tsx#: src/components/NavigatorApp.tsx+#: src/components/OnboardingCard.tsx#: src/components/settings/SharingSection.tsx#: src/components/TerminalCliMissingBanner.tsxmsgid "Dismiss"@@ -2927,6 +2938,10 @@ msgstr ""msgid "Get product updates in your inbox."msgstr ""+#: src/components/OnboardingCard.tsx+msgid "Get set up"+msgstr ""+#: src/components/settings/SettingsDialogBody.tsxmsgid "Git auto-sync"msgstr ""@@ -7035,6 +7050,10 @@ msgstr ""msgid "You picked your home directory. OpenKnowledge will index everything in your home tree — large and may surface personal files."msgstr ""+#: src/components/OnboardingCard.tsx+msgid "You're all set up!"+msgstr ""+#: src/components/SubscribeForm.tsxmsgid "You're subscribed!"msgstr ""diff --git a/packages/app/src/main.tsx b/packages/app/src/main.tsxindex bc0553d98..ac459d6bb 100644--- a/packages/app/src/main.tsx+++ b/packages/app/src/main.tsx@@ -21,6 +21,7 @@ import { installDeepLinkListener } from '@/lib/install-deep-link-listener';import { installOnboardingToastListener } from '@/lib/install-onboarding-toast';import { installServerDriftListener } from '@/lib/install-server-drift-listener';import { installMcpConsentListener } from '@/lib/mcp-consent-store';+import { installOnboardingCardStore } from '@/lib/onboarding-card-store';import { initWebVitals } from '@/lib/perf';import {installColdMountInstrumentation,@@ -52,6 +53,8 @@ if (import.meta.env.DEV || import.meta.env.MODE === 'test') {installUpdateNoticesBridge();+installOnboardingCardStore();+installRelaunchStateBridge();if (typeof window !== 'undefined') {