Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 extractsdiff --git a/packages/app/src/lib/onboarding-card-store.test.ts b/packages/app/src/lib/onboarding-card-store.test.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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): Pe2eSmoke: false,singleFile: false,initialDoc: null,+ freshlyCreated: false,},onProjectSwitched: () => () => {},onMenuAction: () => () => {},diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.tsindex 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.tsindex 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.tsindex 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.tsindex 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 asdiff --git a/packages/desktop/tests/main/window-manager.test.ts b/packages/desktop/tests/main/window-manager.test.tsindex 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.tsindex 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 ({