Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(open-knowledge): first-run onboarding card (OK Desktop) (#2311)

sarah2a719ca69dc7
diff --git a/.changeset/onboarding-card.md b/.changeset/onboarding-card.md
new file mode 100644
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.json
index 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.po
index 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.ts
msgid "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.ts
msgid "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.tsx
msgid "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.tsx
msgid "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.tsx
msgid "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.tsx
msgid "Git auto-sync"
msgstr "Git auto-sync"
@@ -7040,6 +7055,10 @@ msgstr "You picked the filesystem root (/). Scaffolding here will scan every fil
msgid "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.tsx
msgid "You're subscribed!"
msgstr "You're subscribed!"
diff --git a/packages/app/src/locales/pseudo/messages.json b/packages/app/src/locales/pseudo/messages.json
index 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.po
index 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.ts
msgid "Ask AI"
@@ -1288,6 +1289,10 @@ msgstr ""
msgid "Complete"
msgstr ""
+#: src/components/OnboardingCard.tsx
+msgid "Completed:"
+msgstr ""
+
#: src/lib/keyboard-shortcuts.ts
msgid "Component boundary navigation"
msgstr ""
@@ -1896,9 +1901,14 @@ msgid "Create with {0} CLI"
msgstr ""
#: src/components/FileTree.tsx
+#: src/components/OnboardingCard.tsx
msgid "Create your first file"
msgstr ""
+#: src/components/OnboardingCard.tsx
+msgid "Create your first project"
+msgstr ""
+
#: src/components/FolderTimelineCard.tsx
msgid "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.tsx
msgid "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.tsx
msgid "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.tsx
msgid "You're subscribed!"
msgstr ""
diff --git a/packages/app/src/main.tsx b/packages/app/src/main.tsx
index 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') {