Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(onboarding): show first-run card for starter-pack projects + baseline the file step (#2527)

sarahe5f66d29fdec
diff --git a/.changeset/onboarding-card-starter-pack.md b/.changeset/onboarding-card-starter-pack.md
new file mode 100644
index 000000000..edced88f2
--- /dev/null
+++ b/.changeset/onboarding-card-starter-pack.md
@@ -0,0 +1,7 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Fix: the first-run onboarding card now appears when you start a project from a starter pack, not just from a blank project. A starter pack seeds content at create time, which previously made the card's "fresh project" check treat the project as already-established and stay hidden. The card now keys off the first-run create-new flow, so both blank and starter-pack projects get onboarding — while opening a pre-existing populated folder still correctly stays quiet.
+
+Also fixed: on a starter-pack project the "Create your first file" step no longer auto-completes from the pack's seeded templates. The step now baselines the entry count at activation and completes only when you author a document beyond the seed, so the checkmark reflects an action you actually took.
diff --git a/packages/app/src/hooks/use-onboarding-card-visible.test.ts b/packages/app/src/hooks/use-onboarding-card-visible.test.ts
index 15287f4ed..fc0cde1bd 100644
--- a/packages/app/src/hooks/use-onboarding-card-visible.test.ts
+++ b/packages/app/src/hooks/use-onboarding-card-visible.test.ts
@@ -4,10 +4,13 @@ import { evaluateFreshProject } from './use-onboarding-card-visible';
const CURRENT_PATH = '/Users/me/project';
-function bridgeWith(recents: Array<{ path: string }>): OkDesktopBridge {
+function bridgeWith(
+ recents: Array<{ path: string }>,
+ config: { freshlyCreated?: boolean } = {},
+): OkDesktopBridge {
return {
project: { listRecent: () => Promise.resolve(recents) },
- config: { projectPath: CURRENT_PATH },
+ config: { projectPath: CURRENT_PATH, freshlyCreated: config.freshlyCreated ?? false },
} as unknown as OkDesktopBridge;
}
@@ -35,42 +38,75 @@ afterEach(() => {
});
describe('evaluateFreshProject', () => {
- test('fresh single project with zero entries → true', async () => {
+ test('fresh single project with zero entries → activates with baseline 0', async () => {
mockDocumentsResponse({ documents: [] });
- expect(await evaluateFreshProject(bridgeWith([{ path: CURRENT_PATH }]))).toBe(true);
+ expect(await evaluateFreshProject(bridgeWith([{ path: CURRENT_PATH }]))).toBe(0);
});
- test('an empty recents list still counts as no-other-project → true when empty', async () => {
+ test('an empty recents list still counts as no-other-project → baseline 0 when empty', async () => {
mockDocumentsResponse({ documents: [] });
- expect(await evaluateFreshProject(bridgeWith([]))).toBe(true);
+ expect(await evaluateFreshProject(bridgeWith([]))).toBe(0);
});
- test('a second switchable project → false (does not fetch documents)', async () => {
+ test('a second switchable project → null (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);
+ ).toBeNull();
expect(fetchSpy).not.toHaveBeenCalled();
});
- test('project already has content → false', async () => {
+ test('project already has content (not freshly created) → null', async () => {
mockDocumentsResponse({ documents: [aDocument] });
- expect(await evaluateFreshProject(bridgeWith([{ path: CURRENT_PATH }]))).toBe(false);
+ expect(await evaluateFreshProject(bridgeWith([{ path: CURRENT_PATH }]))).toBeNull();
+ });
+
+ test('freshly created (starter-pack seed) → activates, returning the seed count as baseline', async () => {
+ // A starter pack scaffolds content at create time; the `create-new` entry
+ // point sets `freshlyCreated`, so the card activates despite the entries —
+ // and the entry count becomes the file-step baseline so the seed's own
+ // templates don't auto-complete "create your first file".
+ mockDocumentsResponse({ documents: [aDocument, { ...aDocument, docName: 'guide' }] });
+ expect(
+ await evaluateFreshProject(bridgeWith([{ path: CURRENT_PATH }], { freshlyCreated: true })),
+ ).toBe(2);
+ });
+
+ test('freshly created blank project (zero entries) → activates with baseline 0', async () => {
+ // The primary happy path for a blank `create-new` open: freshlyCreated with
+ // no content activates with baseline 0 (any first file then completes the
+ // file step). Guards against a future narrowing like `freshlyCreated &&
+ // entryCount > 0` silently suppressing the card for blank-project users.
+ mockDocumentsResponse({ documents: [] });
+ expect(
+ await evaluateFreshProject(bridgeWith([{ path: CURRENT_PATH }], { freshlyCreated: true })),
+ ).toBe(0);
+ });
+
+ test('freshly created but a second project exists → null (hasOtherProject wins)', 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' }], { freshlyCreated: true }),
+ ),
+ ).toBeNull();
+ expect(fetchSpy).not.toHaveBeenCalled();
});
- test('listRecent rejection is suppressed → false (fail-safe)', async () => {
+ test('listRecent rejection is suppressed → null (fail-safe)', async () => {
mockDocumentsResponse({ documents: [] });
- expect(await evaluateFreshProject(rejectingBridge())).toBe(false);
+ expect(await evaluateFreshProject(rejectingBridge())).toBeNull();
});
- test('non-ok /api/documents response → false (fail-safe)', async () => {
+ test('non-ok /api/documents response → null (fail-safe)', async () => {
mockDocumentsResponse({ error: 'boom' }, 500);
- expect(await evaluateFreshProject(bridgeWith([{ path: CURRENT_PATH }]))).toBe(false);
+ expect(await evaluateFreshProject(bridgeWith([{ path: CURRENT_PATH }]))).toBeNull();
});
- test('schema-violating /api/documents body → false (fail-safe)', async () => {
+ test('schema-violating /api/documents body → null (fail-safe)', async () => {
mockDocumentsResponse({ unexpected: 'shape' });
- expect(await evaluateFreshProject(bridgeWith([{ path: CURRENT_PATH }]))).toBe(false);
+ expect(await evaluateFreshProject(bridgeWith([{ path: CURRENT_PATH }]))).toBeNull();
});
});
diff --git a/packages/app/src/hooks/use-onboarding-card-visible.ts b/packages/app/src/hooks/use-onboarding-card-visible.ts
index dfc657bd3..182750a2e 100644
--- a/packages/app/src/hooks/use-onboarding-card-visible.ts
+++ b/packages/app/src/hooks/use-onboarding-card-visible.ts
@@ -6,8 +6,14 @@
* 1. Host gate — only the Electron host exposes `window.okDesktop`; web / CLI
* builds render nothing because the predicate is never evaluated there.
* 2. Fresh-project gate — the user has no other projects (`listRecent`
- * filtered to other switchable projects is empty) AND this project is
- * empty (entry count 0 at first sight).
+ * filtered to other switchable projects is empty) AND either this window
+ * was opened by a first-run create-new flow (`config.freshlyCreated`, true
+ * for both blank and starter-pack-seeded projects) OR the project is empty
+ * (entry count 0 at first sight). The create-new short-circuit exists
+ * because a starter pack scaffolds content at create time, which would
+ * otherwise fail the entry-count check; opening a pre-existing populated
+ * folder is not create-new, so it stays suppressed — the deliberate
+ * protection for an established single-project user opening their vault.
* 3. Store-flag gate — a card that was dismissed or completed on this device
* never returns.
*
@@ -31,22 +37,38 @@ import { type OnboardingCardStore, onboardingCardStore } from '@/lib/onboarding-
import { fetchDocumentEntryCount } from '@/lib/onboarding-document-count';
/**
- * Resolve whether this is a fresh, single-project desktop session: no other
- * switchable projects and zero content entries. Resolves `false` on any failure
- * to confirm that status — the card stays hidden rather than showing blind.
+ * Resolve whether this is a fresh, single-project desktop session and, if so,
+ * the file-step baseline to latch with. Returns the entry count at activation
+ * (the "create your first file" baseline) when the card should activate, or
+ * `null` when it should not — no other switchable projects, and either a
+ * first-run create-new open or a genuinely empty project. Returns `null` on any
+ * failure to confirm that status — the card stays hidden rather than showing
+ * blind.
*/
-export async function evaluateFreshProject(bridge: OkDesktopBridge): Promise<boolean> {
+export async function evaluateFreshProject(bridge: OkDesktopBridge): Promise<number | null> {
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;
+ if (hasOtherProject) return null;
+ const entryCount = await fetchDocumentEntryCount();
+ // A first-run create-new open (blank OR starter-pack seed) is a genuinely
+ // new user regardless of content: a starter pack scaffolds files/folders at
+ // create time, so the `entryCount === 0` gate below would misclassify a
+ // seeded project as established and hide the card. `freshlyCreated` only
+ // rides the `create-new` entry point, so opening a pre-existing populated
+ // folder (pick-existing / recents) still falls through to the entry-count
+ // gate and stays suppressed — the deliberate protection for an established
+ // single-project user opening their existing vault. The count doubles as the
+ // file-step baseline so the seed's own templates don't auto-complete "create
+ // your first file".
+ if (bridge.config.freshlyCreated) return entryCount;
+ return entryCount === 0 ? 0 : null;
} catch (err) {
// listRecent (IPC) or /api/documents (network) failed — we cannot confirm
// a new user, so suppress rather than ambush an established one.
console.warn('[onboarding-card-visible] fresh-project probe failed; suppressing card', err);
- return false;
+ return null;
}
}
@@ -74,8 +96,8 @@ export function useOnboardingCardVisible(
const bridge = window.okDesktop;
if (bridge == null) return;
let cancelled = false;
- void evaluateFreshProject(bridge).then((isFresh) => {
- if (!cancelled && isFresh) store.activate();
+ void evaluateFreshProject(bridge).then((baseline) => {
+ if (!cancelled && baseline !== null) store.activate(baseline);
});
return () => {
cancelled = true;
diff --git a/packages/app/src/lib/desktop-bridge-types.ts b/packages/app/src/lib/desktop-bridge-types.ts
index c68e19a95..3448f63b2 100644
--- a/packages/app/src/lib/desktop-bridge-types.ts
+++ b/packages/app/src/lib/desktop-bridge-types.ts
@@ -168,6 +168,14 @@ export interface OkDesktopConfig {
* `OkDesktopConfig` (`packages/desktop/src/shared/bridge-contract.ts`).
*/
readonly initialDoc: string | null;
+ /**
+ * `true` when this window was opened by a first-run create-new flow (blank
+ * OR starter-pack seed) — the `create-new` entry point. The onboarding-card
+ * visibility predicate (`evaluateFreshProject`) reads it — see there for why a
+ * seeded project needs this signal. `false` on every other entry point and on
+ * a re-queried live window. Lockstep with the desktop-side `OkDesktopConfig`.
+ */
+ readonly freshlyCreated: boolean;
/**
* W3C `traceparent` of the Electron main process's `ok.app-startup` root
* span, or `undefined` when OTel is disabled in main. The renderer extracts
diff --git a/packages/app/src/lib/onboarding-card-store.test.ts b/packages/app/src/lib/onboarding-card-store.test.ts
index 576582e1b..7e06fddc7 100644
--- a/packages/app/src/lib/onboarding-card-store.test.ts
+++ b/packages/app/src/lib/onboarding-card-store.test.ts
@@ -29,6 +29,7 @@ describe('readPersistedState', () => {
const stored = {
initialized: true,
steps: { file: true, askedAi: true },
+ fileBaseline: 3,
dismissed: false,
completed: true,
};
@@ -36,18 +37,28 @@ describe('readPersistedState', () => {
expect(readPersistedState(s)).toEqual(stored);
});
- test('missing fields default to false', () => {
+ test('missing fields default to false / baseline 0', () => {
const s = memoryStorage({
[ONBOARDING_CARD_STORAGE_KEY]: JSON.stringify({ steps: { file: true } }),
});
expect(readPersistedState(s)).toEqual({
initialized: false,
steps: { file: true, askedAi: false },
+ fileBaseline: 0,
dismissed: false,
completed: false,
});
});
+ test('a non-numeric / negative fileBaseline coerces to 0', () => {
+ for (const bad of ['5', -2, Number.NaN, null, {}]) {
+ const s = memoryStorage({
+ [ONBOARDING_CARD_STORAGE_KEY]: JSON.stringify({ initialized: true, fileBaseline: bad }),
+ });
+ expect(readPersistedState(s).fileBaseline).toBe(0);
+ }
+ });
+
test('non-boolean field values are coerced to false', () => {
const s = memoryStorage({
[ONBOARDING_CARD_STORAGE_KEY]: JSON.stringify({
@@ -129,6 +140,23 @@ describe('createOnboardingCardStore — mutations', () => {
expect(store.getSnapshot().initialized).toBe(true);
});
+ test('activate records the file baseline (defaults to 0)', () => {
+ const store = createOnboardingCardStore(memoryStorage());
+ store.activate(4);
+ expect(store.getSnapshot().fileBaseline).toBe(4);
+
+ const blank = createOnboardingCardStore(memoryStorage());
+ blank.activate();
+ expect(blank.getSnapshot().fileBaseline).toBe(0);
+ });
+
+ test('activate is idempotent — the first baseline wins', () => {
+ const store = createOnboardingCardStore(memoryStorage());
+ store.activate(4);
+ store.activate(9);
+ expect(store.getSnapshot().fileBaseline).toBe(4);
+ });
+
test('dismiss sets the dismissed flag', () => {
const store = createOnboardingCardStore(memoryStorage());
store.dismiss();
diff --git a/packages/app/src/lib/onboarding-card-store.ts b/packages/app/src/lib/onboarding-card-store.ts
index fde907b50..495a70d89 100644
--- a/packages/app/src/lib/onboarding-card-store.ts
+++ b/packages/app/src/lib/onboarding-card-store.ts
@@ -33,6 +33,14 @@ export interface OnboardingCardState {
readonly file: boolean;
readonly askedAi: boolean;
};
+ /**
+ * Entry count observed when the card latched on (`activate`). The "create your
+ * first file" step completes only once the count rises ABOVE this baseline, so
+ * a starter-pack project's seeded templates (present at activation) don't
+ * auto-complete a step the user hasn't performed. Blank projects activate with
+ * baseline 0, so any first file still completes it (`> 0` ≡ the old `>= 1`).
+ */
+ readonly fileBaseline: number;
readonly dismissed: boolean;
readonly completed: boolean;
}
@@ -40,6 +48,7 @@ export interface OnboardingCardState {
export const DEFAULT_ONBOARDING_CARD_STATE: OnboardingCardState = {
initialized: false,
steps: { file: false, askedAi: false },
+ fileBaseline: 0,
dismissed: false,
completed: false,
};
@@ -52,8 +61,13 @@ export interface OnboardingCardStorage {
export interface OnboardingCardStore {
getSnapshot(): OnboardingCardState;
subscribe(listener: () => void): () => void;
- /** Latch the card on for a fresh project. Idempotent — never regresses an already-initialized store. */
- activate(): void;
+ /**
+ * Latch the card on for a fresh project, recording `fileBaseline` (the entry
+ * count at activation; the "create your first file" step completes only above
+ * it). Idempotent — never regresses an already-initialized store, so the first
+ * activation's baseline wins. Defaults to 0 (blank-project semantics).
+ */
+ activate(fileBaseline?: number): void;
markStepComplete(step: OnboardingStep): void;
dismiss(): void;
markCompleted(): void;
@@ -80,6 +94,16 @@ function coerceState(parsed: unknown): OnboardingCardState {
return {
initialized: asFlag(obj.initialized),
steps: { file: asFlag(steps.file), askedAi: asFlag(steps.askedAi) },
+ // Accept any non-negative finite number (0 is the canonical blank-project
+ // baseline); a negative / non-finite / non-number payload (corrupt or
+ // forward-incompat) degrades to 0 — the safe default (never blocks a
+ // legitimate first file).
+ fileBaseline:
+ typeof obj.fileBaseline === 'number' &&
+ Number.isFinite(obj.fileBaseline) &&
+ obj.fileBaseline >= 0
+ ? obj.fileBaseline
+ : 0,
dismissed: asFlag(obj.dismissed),
completed: asFlag(obj.completed),
};
@@ -141,9 +165,9 @@ export function createOnboardingCardStore(storage?: OnboardingCardStorage): Onbo
};
},
- activate(): void {
+ activate(fileBaseline = 0): void {
if (state.initialized) return;
- commit({ ...state, initialized: true });
+ commit({ ...state, initialized: true, fileBaseline });
},
markStepComplete(step): void {
diff --git a/packages/app/src/lib/onboarding-document-count.ts b/packages/app/src/lib/onboarding-document-count.ts
index e37ff8adb..b2a6159ef 100644
--- a/packages/app/src/lib/onboarding-document-count.ts
+++ b/packages/app/src/lib/onboarding-document-count.ts
@@ -1,8 +1,9 @@
/**
* Shared content-entry count for the onboarding card. Both the visibility
- * predicate (is the project fresh — count 0?) and the file-completion signal
- * (did the first file land — count >= 1?) key off the same `/api/documents`
- * read, so the fetch + counting rule lives in one place.
+ * predicate (is this a fresh, single-project session?) and the file-completion
+ * signal (did the user author a file beyond the activation baseline — count
+ * greater than `fileBaseline`?) key off the same `/api/documents` read, so the
+ * fetch + counting rule lives in one place.
*/
import { type DocumentListSuccess, DocumentListSuccessSchema } from '@inkeep/open-knowledge-core';
diff --git a/packages/app/src/lib/onboarding-signals.test.ts b/packages/app/src/lib/onboarding-signals.test.ts
index c190756ee..96e2367a0 100644
--- a/packages/app/src/lib/onboarding-signals.test.ts
+++ b/packages/app/src/lib/onboarding-signals.test.ts
@@ -66,6 +66,30 @@ describe('recordOnboardingFileStep', () => {
expect(store.getSnapshot().steps.file).toBe(false);
});
+ test('a starter-pack seed (count === baseline) does not complete the file step', async () => {
+ // Activated with a baseline of 2 (two seeded templates). A read that still
+ // shows exactly 2 entries is the seed itself — the user has not authored a
+ // file yet, so the step must stay incomplete.
+ mockDocuments([aDocument, { ...aDocument, docName: 'guide' }]);
+ const store = freshStore();
+ store.activate(2);
+ await recordOnboardingFileStep(store);
+ expect(store.getSnapshot().steps.file).toBe(false);
+ });
+
+ test('a user-authored file beyond the seed baseline completes the file step', async () => {
+ // Count rises to 3, above the baseline of 2 → the user created a doc.
+ mockDocuments([
+ aDocument,
+ { ...aDocument, docName: 'guide' },
+ { ...aDocument, docName: 'mine' },
+ ]);
+ const store = freshStore();
+ store.activate(2);
+ await recordOnboardingFileStep(store);
+ expect(store.getSnapshot().steps.file).toBe(true);
+ });
+
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;
diff --git a/packages/app/src/lib/onboarding-signals.ts b/packages/app/src/lib/onboarding-signals.ts
index fa9d6c1de..4a1d6bd67 100644
--- a/packages/app/src/lib/onboarding-signals.ts
+++ b/packages/app/src/lib/onboarding-signals.ts
@@ -14,12 +14,16 @@ import { type OnboardingCardStore, onboardingCardStore } from '@/lib/onboarding-
import { fetchDocumentEntryCount } from '@/lib/onboarding-document-count';
/**
- * Mark the "create your first file" step complete once the project has at least
- * one content entry. No-op if onboarding isn't active, the step is already done,
- * or the count read fails (the next document-change event retries). The
- * `initialized` gate mirrors the Ask-AI recorder so a file created by an
- * established user never writes onboarding state, regardless of call site. The
- * `store` parameter is a test seam.
+ * Mark the "create your first file" step complete once the project's entry count
+ * rises ABOVE the baseline captured at activation (`snapshot.fileBaseline`). For
+ * a blank project the baseline is 0, so any first file completes it (`> 0` ≡ the
+ * old `>= 1`); for a starter-pack project the baseline is the seeded template
+ * count, so the step completes only when the user authors a doc beyond the seed —
+ * a pack's templates never auto-complete a step the user hasn't performed. No-op
+ * if onboarding isn't active, the step is already done, or the count read fails
+ * (the next document-change event retries). The `initialized` gate mirrors the
+ * Ask-AI recorder so a file created by an established user never writes onboarding
+ * state, regardless of call site. The `store` parameter is a test seam.
*/
export async function recordOnboardingFileStep(
store: OnboardingCardStore = onboardingCardStore,
@@ -27,7 +31,7 @@ export async function recordOnboardingFileStep(
const snapshot = store.getSnapshot();
if (snapshot.steps.file || !snapshot.initialized) return;
try {
- if ((await fetchDocumentEntryCount()) >= 1) store.markStepComplete('file');
+ if ((await fetchDocumentEntryCount()) > snapshot.fileBaseline) store.markStepComplete('file');
} catch (err) {
// Transient/failed count read — leave the step incomplete; a later
// documents-changed event re-runs this.
diff --git a/packages/app/tests/stress/fixtures/handoff-mocks.ts b/packages/app/tests/stress/fixtures/handoff-mocks.ts
index 7b88e558f..937cdf27f 100644
--- a/packages/app/tests/stress/fixtures/handoff-mocks.ts
+++ b/packages/app/tests/stress/fixtures/handoff-mocks.ts
@@ -357,6 +357,7 @@ export async function installHandoffMocks(page: Page, cfg: HandoffMockConfig): P
e2eSmoke: false,
singleFile: false,
initialDoc: null,
+ freshlyCreated: false,
},
onProjectSwitched: () => () => {},
onMenuAction: () => () => {},
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index 4f8001383..df72ce221 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -1738,6 +1738,9 @@ async function openProject(
didEnsureGit,
consentVersion: 1,
localOpCliArgs: resolveLocalOpCliArgs(),
+ // Nested-redirect implies an enclosing existing project (an established
+ // user), so it is deliberately excluded from the fresh-create signal.
+ freshlyCreated: entryPoint === 'create-new',
});
getLogger('project').info(
{
@@ -3627,6 +3630,10 @@ function registerIpcHandlers() {
// boot from the preload-injected bridge config). A live window queried via
// get-info has already navigated, so there is nothing to re-seed → null.
initialDoc: null,
+ // `freshlyCreated` is a cold-start-only onboarding signal (the card
+ // evaluates it once at first paint). A re-queried live window is past
+ // that point — parity with `initialDoc: null` above.
+ freshlyCreated: false,
};
});
diff --git a/packages/desktop/src/main/window-manager.ts b/packages/desktop/src/main/window-manager.ts
index 4fe18a1af..61d4b53f0 100644
--- a/packages/desktop/src/main/window-manager.ts
+++ b/packages/desktop/src/main/window-manager.ts
@@ -380,6 +380,14 @@ interface CreateProjectWindowOpts {
* renderer confirms the server now matches the app.
*/
pendingServerRestartedToast?: boolean;
+ /**
+ * `true` when this open is a first-run create-new flow (blank or starter-pack
+ * seed), derived by the caller from the `create-new` entry point. Forwarded to
+ * the renderer as `--ok-fresh-create=1`; the onboarding card keys off it (see
+ * `evaluateFreshProject` for why). Default false — a plain boolean keeps the
+ * manager decoupled from `EntryPoint` semantics.
+ */
+ freshlyCreated?: boolean;
}
/** Test-injectable side-effect surface (Electron + node:fs primitives). */
@@ -1380,6 +1388,7 @@ export class WindowManager {
pendingTargetMissing: opts.pendingTargetMissing,
pendingShareBranchSwitch: opts.pendingShareBranchSwitch,
pendingServerRestartedToast: opts.pendingServerRestartedToast,
+ freshlyCreated: opts.freshlyCreated,
});
}
// Reclaimed: the terminated server's (possibly stale) lock is cleared by
@@ -1490,6 +1499,7 @@ export class WindowManager {
pendingTargetMissing: opts.pendingTargetMissing,
pendingShareBranchSwitch: opts.pendingShareBranchSwitch,
pendingServerRestartedToast: opts.pendingServerRestartedToast,
+ freshlyCreated: opts.freshlyCreated,
});
}
@@ -1649,6 +1659,9 @@ export class WindowManager {
...(this.deps.startup?.traceparent !== undefined
? [`--ok-startup-traceparent=${this.deps.startup.traceparent}`]
: []),
+ // Appended only when set, so every other entry point omits it (preload
+ // coerces absent → false).
+ ...(opts.freshlyCreated ? ['--ok-fresh-create=1'] : []),
];
const window = this.deps.createWindow({
additionalArguments,
@@ -2237,6 +2250,13 @@ export class WindowManager {
pendingTargetMissing?: boolean;
pendingShareBranchSwitch?: ShareDeepLinkBranchSwitchPayload;
pendingServerRestartedToast?: boolean;
+ /**
+ * First-run create-new signal, forwarded from `createProjectWindow`'s opts.
+ * Attach mode is the PRODUCTION path (detached-spawn + direct-attach both
+ * land here), so the onboarding card's `--ok-fresh-create=1` MUST be
+ * injected here too — the utility-fork branch is dev/test only.
+ */
+ freshlyCreated?: boolean;
}): Promise<ProjectContext> {
const {
projectPath,
@@ -2249,6 +2269,7 @@ export class WindowManager {
pendingTargetMissing,
pendingShareBranchSwitch,
pendingServerRestartedToast,
+ freshlyCreated,
} = args;
const port = lock.port;
const apiOrigin = `http://localhost:${port}`;
@@ -2274,6 +2295,11 @@ export class WindowManager {
...(this.deps.startup?.traceparent !== undefined
? [`--ok-startup-traceparent=${this.deps.startup.traceparent}`]
: []),
+ // Mirror the utility-fork branch's injection: attach mode is the
+ // production path, so a first-run create-new (blank or starter-pack
+ // seed) must surface `freshlyCreated` here too or the onboarding card
+ // never activates in packaged builds.
+ ...(freshlyCreated ? ['--ok-fresh-create=1'] : []),
],
title: formatEditorTitle(projectName),
});
diff --git a/packages/desktop/src/preload/index.ts b/packages/desktop/src/preload/index.ts
index 1ff370673..5d8681583 100644
--- a/packages/desktop/src/preload/index.ts
+++ b/packages/desktop/src/preload/index.ts
@@ -216,6 +216,10 @@ function readConfigFromArgv(): OkDesktopConfig {
// Ephemeral single-file windows carry the doc to seed into the hash before
// first paint; normal project windows omit it (`null` → seed is a no-op).
const initialDoc = parseArg('initial-doc') ?? null;
+ // Present only on a first-run create-new open (blank or starter-pack seed);
+ // every other entry point omits the flag and coerces to `false`. The
+ // onboarding card reads it to stay visible for a seeded project.
+ const freshlyCreated = parseArg('fresh-create') === '1';
// Set only under the Electron smoke suite (main injects `--ok-e2e-smoke=1`):
// tells the renderer to use xterm's DOM renderer instead of the WebGL canvas
// so the DOM-based terminal smoke assertions can read output + deliver input.
@@ -233,6 +237,7 @@ function readConfigFromArgv(): OkDesktopConfig {
e2eSmoke,
singleFile,
initialDoc,
+ freshlyCreated,
...(startupTraceparent !== undefined ? { startupTraceparent } : {}),
});
}
diff --git a/packages/desktop/src/shared/bridge-contract.ts b/packages/desktop/src/shared/bridge-contract.ts
index 1a74427e0..06b24d42a 100644
--- a/packages/desktop/src/shared/bridge-contract.ts
+++ b/packages/desktop/src/shared/bridge-contract.ts
@@ -148,6 +148,15 @@ export interface OkDesktopConfig {
* Lockstep with the app-side `OkDesktopConfig`.
*/
readonly initialDoc: string | null;
+ /**
+ * `true` when this window was opened by a first-run create-new flow (blank
+ * OR starter-pack seed) — the `create-new` entry point. The onboarding card's
+ * visibility predicate reads it (see `evaluateFreshProject` for why a seeded
+ * project needs this signal). `false` on every other entry point and on a
+ * re-queried live window (get-info). Lockstep with the app-side
+ * `OkDesktopConfig`.
+ */
+ readonly freshlyCreated: boolean;
/**
* W3C `traceparent` of the Electron main process's `ok.app-startup` root
* span, or `undefined` when OTel is disabled in main. Injected as
diff --git a/packages/desktop/tests/main/window-manager.test.ts b/packages/desktop/tests/main/window-manager.test.ts
index 1702a3720..1bb4ebaf8 100644
--- a/packages/desktop/tests/main/window-manager.test.ts
+++ b/packages/desktop/tests/main/window-manager.test.ts
@@ -205,6 +205,27 @@ describe('WindowManager', () => {
expect(env.createWindowOpts[0]?.title).toBe('dragon-wiki — OpenKnowledge');
});
+ test('createProjectWindow injects --ok-fresh-create=1 only when freshlyCreated is set', async () => {
+ // The renderer's onboarding card reads this flag (via preload → bridge
+ // config) to stay visible for a first-run create-new project even when a
+ // starter pack seeded it with content. Absent → omitted (coerces false).
+ const wmFresh = new WindowManager(env.deps);
+ const freshPromise = wmFresh.createProjectWindow({
+ projectPath: '/tmp/seeded',
+ freshlyCreated: true,
+ });
+ env.utilities[0]?.fire({ type: 'ready', port: 52010, apiOrigin: 'http://localhost:52010' });
+ await freshPromise;
+ expect(env.createWindowOpts[0]?.additionalArguments).toContain('--ok-fresh-create=1');
+
+ const env2 = buildEnv();
+ const wmPlain = new WindowManager(env2.deps);
+ const plainPromise = wmPlain.createProjectWindow({ projectPath: '/tmp/opened' });
+ env2.utilities[0]?.fire({ type: 'ready', port: 52011, apiOrigin: 'http://localhost:52011' });
+ await plainPromise;
+ expect(env2.createWindowOpts[0]?.additionalArguments).not.toContain('--ok-fresh-create=1');
+ });
+
test('createProjectWindow forks utility, sends init, waits for ready, creates window', async () => {
const wm = new WindowManager(env.deps);
const promise = wm.createProjectWindow({ projectPath: '/tmp/test-project' });
@@ -693,6 +714,31 @@ describe('WindowManager', () => {
expect(env.createWindowOpts[0]?.title).toBe('dragon — OpenKnowledge');
});
+ test('attach path injects --ok-fresh-create=1 when freshlyCreated is set (production path)', async () => {
+ // Attach mode — both the direct-attach and detached-spawn callers delegate
+ // here — is the PRODUCTION window path (packaged builds wire
+ // spawnDetachedServer). The onboarding-card flag MUST be injected here too,
+ // not only in the dev/test utility-fork branch, or the starter-pack fix
+ // silently fails for every packaged user.
+ enableAttachProbe();
+ const wm = new WindowManager(env.deps);
+ const ctx = await wm.createProjectWindow({
+ projectPath: '/tmp/dragon',
+ freshlyCreated: true,
+ });
+ // No utility forked → we genuinely took the attach path, not utility-fork.
+ expect(env.utilities.length).toBe(0);
+ expect(ctx.ownsServer).toBe(false);
+ expect(env.createWindowOpts[0]?.additionalArguments).toContain('--ok-fresh-create=1');
+ });
+
+ test('attach path omits --ok-fresh-create=1 when freshlyCreated is not set', async () => {
+ enableAttachProbe();
+ const wm = new WindowManager(env.deps);
+ await wm.createProjectWindow({ projectPath: '/tmp/dragon' });
+ expect(env.createWindowOpts[0]?.additionalArguments).not.toContain('--ok-fresh-create=1');
+ });
+
function driftSends(w: ReturnType<typeof makeWindow>): unknown[] {
return (w.webContents.send as ReturnType<typeof mock>).mock.calls.filter(
(c: unknown[]) => c[0] === 'ok:server-version-drift',
diff --git a/packages/desktop/tests/smoke/create-new-project.e2e.ts b/packages/desktop/tests/smoke/create-new-project.e2e.ts
index 852aeb71f..ddf969e9d 100644
--- a/packages/desktop/tests/smoke/create-new-project.e2e.ts
+++ b/packages/desktop/tests/smoke/create-new-project.e2e.ts
@@ -1,7 +1,13 @@
/**
* Create-new-project smoke harness — drives an Electron launch through the
- * Navigator → "Create new project" card → in-app CreateProjectDialog flow and
- * asserts the three end-to-end cascade UX states:
+ * Navigator → blank-create affordance → in-app CreateProjectDialog flow and
+ * asserts the three end-to-end cascade UX states.
+ *
+ * Every test seeds zero recents (`seedTmpHome`), so the Navigator opens on the
+ * first-run packs-forward view — the blank-create affordance there is
+ * `nav-first-run-blank`, NOT the returning-user `nav-create-new` card (which
+ * renders only once recents exist). Both fire the same `onCreate` → the same
+ * dialog. The cascade states asserted:
*
* 1. Free path (happy submit): no banner, Create enabled. After submit,
* .ok/config.yml lands at parent/<name> and the editor window opens
@@ -227,6 +233,29 @@ test.describe('Create-new-project smoke', () => {
await expect
.poll(() => existsSync(join(expectedTarget, '.ok', 'config.yml')), { timeout: 15_000 })
.toBe(true);
+
+ // The create-new open must surface `freshlyCreated: true` on the editor
+ // window's bridge config (main → `--ok-fresh-create=1` → preload → config).
+ // This is what lets the renderer's onboarding card stay visible for a
+ // first-run project — including a starter-pack seed, which opens through
+ // this same `create-new` entry point. Blank and seeded creates are
+ // indistinguishable at this seam, so asserting it here covers both.
+ //
+ // The editor window already exists (the countWindowsByMode poll above waited
+ // for it), so read it inline rather than re-polling via the 20s-default
+ // `findWindowByMode` helper — that second helper budget would push this
+ // test's cumulative inner-timeout over the calibration ceiling.
+ let editor: Page | undefined;
+ for (const page of app.windows()) {
+ const m = await page.evaluate(() => window.okDesktop?.config?.mode).catch(() => undefined);
+ if (m === 'editor') {
+ editor = page;
+ break;
+ }
+ }
+ if (!editor) throw new Error('editor window not found after create-new submit');
+ const freshlyCreated = await editor.evaluate(() => window.okDesktop?.config?.freshlyCreated);
+ expect(freshlyCreated).toBe(true);
});
test('blocks creation when chosen Location is inside an existing OK project', async ({