diff --git a/apps/desktop/src/components/CommandPalette.tsx b/apps/desktop/src/components/CommandPalette.tsx index 055e925..8d1a23f 100644 --- a/apps/desktop/src/components/CommandPalette.tsx +++ b/apps/desktop/src/components/CommandPalette.tsx @@ -10,6 +10,7 @@ import { ChevronIcon, FolderIcon, GlobeIcon, + HelpIcon, KeyboardIcon, LinkIcon, PlayIcon, @@ -183,6 +184,8 @@ function ItemIcon({ icon }: { icon: PaletteIcon }) { return ; case "agents": return ; + case "help": + return ; case "play": case "restart": return ; diff --git a/apps/desktop/src/components/GetStarted.tsx b/apps/desktop/src/components/GetStarted.tsx index 9aebef7..8d2e7af 100644 --- a/apps/desktop/src/components/GetStarted.tsx +++ b/apps/desktop/src/components/GetStarted.tsx @@ -6,9 +6,11 @@ import { type ChecklistItem, checklistItems, hasRunningService, + hideChecklist, isAnyAgentConnected, isChecklistShown, updateOnboarding, + useIsChecklistReplayed, useOnboarding, } from "../onboarding"; import { showSheet, useUi } from "../ui"; @@ -25,10 +27,12 @@ type Props = { /** * The Get started checklist, at the foot of the sidebar once there is a * Project: each row ticks from what is true, an open row takes the user - * there. It goes away for good when every row is ticked or it is closed. + * there. It goes away for good when every row is ticked or it is closed; + * shown again from Help, it stays until closed. */ export function GetStarted({ view, selectedProjectId, onSelectProject }: Props) { const onboarding = useOnboarding(); + const isReplayed = useIsChecklistReplayed(); const isShown = onboarding !== null && isChecklistShown(onboarding, view); const hasConnectedAgent = useHasConnectedAgent(isShown); const isRunning = hasRunningService(view); @@ -39,10 +43,10 @@ export function GetStarted({ view, selectedProjectId, onSelectProject }: Props) if (isShown && isRunning && !onboarding?.hasStartedService) updateOnboarding({ hasStartedService: true }); }, [isShown, isRunning, onboarding]); useEffect(() => { - if (isShown && isComplete) updateOnboarding({ isChecklistDone: true }); - }, [isShown, isComplete]); + if (isShown && isComplete && !isReplayed) updateOnboarding({ isChecklistDone: true }); + }, [isShown, isComplete, isReplayed]); - if (!isShown || isComplete) return null; + if (!isShown || (isComplete && !isReplayed)) return null; const doneCount = items.filter((item) => item.isDone).length; const act = (item: ChecklistItem) => { if (item.step === "agents") { @@ -70,7 +74,7 @@ export function GetStarted({ view, selectedProjectId, onSelectProject }: Props) className={styles.close} aria-label="Hide Get Started" title="Hide Get Started" - onClick={() => updateOnboarding({ isChecklistDone: true })} + onClick={hideChecklist} > diff --git a/apps/desktop/src/components/Icons.tsx b/apps/desktop/src/components/Icons.tsx index 42ba3cb..bf6b616 100644 --- a/apps/desktop/src/components/Icons.tsx +++ b/apps/desktop/src/components/Icons.tsx @@ -255,6 +255,14 @@ export const CheckIcon = (props: Props) => ( ); +/** `questionmark.circle`: Help. */ +export const HelpIcon = (props: Props) => ( + + + + +); + /** `keyboard`: Keyboard Shortcuts. */ export const KeyboardIcon = (props: Props) => ( diff --git a/apps/desktop/src/components/Menu.module.css b/apps/desktop/src/components/Menu.module.css index 9ccb3ce..27960a8 100644 --- a/apps/desktop/src/components/Menu.module.css +++ b/apps/desktop/src/components/Menu.module.css @@ -47,6 +47,12 @@ right: 0; } +.above { + position: absolute; + bottom: calc(100% + 4px); + right: 0; +} + .alignLeft { right: auto; left: 0; diff --git a/apps/desktop/src/components/Menu.tsx b/apps/desktop/src/components/Menu.tsx index 0fedb91..a1f9cfb 100644 --- a/apps/desktop/src/components/Menu.tsx +++ b/apps/desktop/src/components/Menu.tsx @@ -15,10 +15,12 @@ type Props = { button?: { content: ReactNode; className: string }; /** Which side of the button the menu lines up with. */ align?: "left" | "right"; + /** Opens upward, for a button at the foot of the window. */ + isAbove?: boolean; }; /** A button opening a menu: by default a borderless `⋯`, for rare actions. */ -export function Menu({ label, items, button: custom, align = "right" }: Props) { +export function Menu({ label, items, button: custom, align = "right", isAbove = false }: Props) { const [isOpen, setIsOpen] = useState(false); const button = useRef(null); const menuId = useId(); @@ -44,7 +46,7 @@ export function Menu({ label, items, button: custom, align = "right" }: Props) { id={menuId} label={label} items={items} - className={`${styles.below} ${align === "left" ? styles.alignLeft : ""}`} + className={`${isAbove ? styles.above : styles.below} ${align === "left" ? styles.alignLeft : ""}`} onClose={(returnFocus) => { setIsOpen(false); if (returnFocus) button.current?.focus(); diff --git a/apps/desktop/src/components/Onboarding.test.tsx b/apps/desktop/src/components/Onboarding.test.tsx index d6f54a7..3891567 100644 --- a/apps/desktop/src/components/Onboarding.test.tsx +++ b/apps/desktop/src/components/Onboarding.test.tsx @@ -1,10 +1,11 @@ import { act, fireEvent, render, screen, waitFor } from "@testing-library/react"; import { afterEach, describe, expect, it, vi } from "vitest"; import { viewFromSnapshot } from "../core"; -import { resetOnboarding, startOnboarding } from "../onboarding"; +import { resetOnboarding, showChecklistAgain, startOnboarding } from "../onboarding"; import { project, service, status } from "../test/fixtures"; import { currentUi, resetUi } from "../ui"; import { GetStarted } from "./GetStarted"; +import { helpMenuItems } from "./Sidebar"; import { Welcome } from "./Welcome"; const commands = vi.hoisted(() => ({ @@ -94,3 +95,54 @@ describe("GetStarted", () => { expect(container.innerHTML).toBe(""); }); }); + +describe("Help", () => { + const shop = project("Shop", 0, [service("Web")]); + const used = { hasSeenWelcome: true, isChecklistDone: true, hasStartedService: true }; + const help = (label: string) => { + const item = helpMenuItems().find((item) => item !== "separator" && item.label === label); + if (!item || item === "separator") throw new Error(`no ${label}`); + return item; + }; + + it("shows the welcome again with Projects present, and leaves the saved state as it was", async () => { + commands.onboarding.mockResolvedValue({ onboarding: used, hasOpenedBefore: true }); + await act(() => startOnboarding(1)); + act(() => help("Show Welcome…").onSelect()); + expect(currentUi().sheet).toEqual({ kind: "welcome" }); + + render(); + fireEvent.click(screen.getByRole("button", { name: "Skip" })); + expect(currentUi().sheet).toBeNull(); + expect(commands.saveOnboarding).not.toHaveBeenCalled(); + }); + + it("brings back the checklist, ticked from what is true, until closed again", async () => { + commands.onboarding.mockResolvedValue({ onboarding: used, hasOpenedBefore: true }); + commands.agentStatuses.mockResolvedValue([{ connection: "connected" }]); + await act(() => startOnboarding(1)); + const view = viewFromSnapshot({ projects: [shop], statuses: [status(shop.services[0].id, "running")], projectStates: [] }); + const { container } = render(); + expect(container.innerHTML).toBe(""); + + act(() => help("Show Get Started Checklist").onSelect()); + expect(commands.saveOnboarding).toHaveBeenLastCalledWith({ ...used, isChecklistDone: false }); + // Every row is ticked, yet it stays: it was asked for. + await waitFor(() => expect(screen.getByText("4 of 4")).toBeTruthy()); + await act(() => new Promise((resolve) => setTimeout(resolve, 0))); + expect(screen.getByText("4 of 4")).toBeTruthy(); + + fireEvent.click(screen.getByRole("button", { name: "Hide Get Started" })); + expect(container.innerHTML).toBe(""); + expect(commands.saveOnboarding).toHaveBeenLastCalledWith(used); + }); + + it("shows a closed checklist again even before it was complete", async () => { + commands.onboarding.mockResolvedValue({ onboarding: { ...used, hasStartedService: false }, hasOpenedBefore: true }); + await act(() => startOnboarding(1)); + const view = viewFromSnapshot({ projects: [shop], statuses: [], projectStates: [] }); + render(); + act(() => showChecklistAgain()); + expect(screen.getByText("2 of 4")).toBeTruthy(); + }); +}); diff --git a/apps/desktop/src/components/Sidebar.tsx b/apps/desktop/src/components/Sidebar.tsx index a5a55fa..126f23f 100644 --- a/apps/desktop/src/components/Sidebar.tsx +++ b/apps/desktop/src/components/Sidebar.tsx @@ -7,10 +7,11 @@ import { importProject } from "../editors"; import { SHORTCUTS, shortcutLabel } from "../keyboard"; import type { ShownMachine } from "../machines"; import { isActive, projectServicesSummary } from "../status"; +import { showChecklistAgain } from "../onboarding"; import { showAlert, showSheet } from "../ui"; import { useUpdate } from "../updates"; import { GetStarted } from "./GetStarted"; -import { ClearIcon, GearIcon, GlobeIcon, KeyboardIcon, PlusIcon, SearchIcon } from "./Icons"; +import { ClearIcon, GearIcon, GlobeIcon, HelpIcon, PlusIcon, SearchIcon } from "./Icons"; import { Menu, type MenuItem, useContextMenu } from "./Menu"; import { projectMenuItems } from "./ServicesColumn"; import { ShortcutBadge } from "./ShortcutBadge"; @@ -29,8 +30,8 @@ type Props = { /** * The wordmark and project search, Ports and the Projects, then each other - * Machine's, a newer version when there is one, and a footer with Settings - * and how many Services run. + * Machine's, a newer version when there is one, and a footer with Settings, + * Help and how many Services run. */ export function Sidebar({ view, machines = [], selection, onSelect }: Props) { const [search, setSearch] = useState(""); @@ -167,14 +168,13 @@ export function Sidebar({ view, machines = [], selection, onSelect }: Props) { > - + , className: "iconButton" }} + align="left" + isAbove + /> {running > 0 && {running} running} @@ -182,6 +182,19 @@ export function Sidebar({ view, machines = [], selection, onSelect }: Props) { ); } +/** + * The macOS app's Help menu, as this window has no menu bar: Keyboard + * Shortcuts, and the first run's welcome and checklist on request. + */ +export function helpMenuItems(): MenuItem[] { + return [ + { label: "Keyboard Shortcuts", onSelect: () => showAlert({ kind: "keyboardShortcuts" }) }, + "separator", + { label: "Show Welcome…", onSelect: () => showSheet({ kind: "welcome" }) }, + { label: "Show Get Started Checklist", onSelect: showChecklistAgain }, + ]; +} + type ProjectRowProps = { project: Project; view: CoreView; diff --git a/apps/desktop/src/components/Welcome.tsx b/apps/desktop/src/components/Welcome.tsx index 379f0fc..62ab914 100644 --- a/apps/desktop/src/components/Welcome.tsx +++ b/apps/desktop/src/components/Welcome.tsx @@ -11,7 +11,7 @@ import styles from "./Welcome.module.css"; /** * The first launch's welcome: what a Project, a Service and a Port are, one * step each, ending in Add Project…. Skipping, Escape or finishing all - * mean it never opens again. + * mean it never opens by itself again; Help › Show Welcome… opens it anyway. */ export function Welcome() { const [index, setIndex] = useState(0); diff --git a/apps/desktop/src/onboarding.ts b/apps/desktop/src/onboarding.ts index 56dcdb3..2f54a35 100644 --- a/apps/desktop/src/onboarding.ts +++ b/apps/desktop/src/onboarding.ts @@ -92,11 +92,18 @@ export function isAnyAgentConnected(agents: readonly AgentStatus[]): boolean { // so nothing shows before then. let current: Onboarding | null = null; +// The checklist was asked for again from Help: it stays until closed, even +// with every row ticked. Not saved, so the next launch is as before. +let isChecklistReplayed = false; const listeners = new Set<() => void>(); +function notify() { + listeners.forEach((listener) => listener()); +} + function publish(next: Onboarding) { current = next; - listeners.forEach((listener) => listener()); + notify(); } /** At launch, once the Projects are known: whether to open the welcome. */ @@ -118,17 +125,40 @@ export function updateOnboarding(change: Partial) { void commands.saveOnboarding(next); } +/** + * Help › Show Get Started Checklist: brings the checklist back after it was + * closed or completed. Its rows still tick from what is true. + */ +export function showChecklistAgain() { + if (!current) return; + isChecklistReplayed = true; + if (current.isChecklistDone) updateOnboarding({ isChecklistDone: false }); + else notify(); +} + +/** The checklist's close button: gone until asked for again. */ +export function hideChecklist() { + isChecklistReplayed = false; + updateOnboarding({ isChecklistDone: true }); + notify(); +} + +function subscribe(listener: () => void) { + listeners.add(listener); + return () => void listeners.delete(listener); +} + export function useOnboarding(): Onboarding | null { - return useSyncExternalStore( - (listener) => { - listeners.add(listener); - return () => listeners.delete(listener); - }, - () => current, - ); + return useSyncExternalStore(subscribe, () => current); +} + +/** Whether the checklist was asked for again, so a complete one stays until closed. */ +export function useIsChecklistReplayed(): boolean { + return useSyncExternalStore(subscribe, () => isChecklistReplayed); } /** For tests. */ export function resetOnboarding() { current = null; + isChecklistReplayed = false; } diff --git a/apps/desktop/src/palette.test.ts b/apps/desktop/src/palette.test.ts index db201d1..647e6c4 100644 --- a/apps/desktop/src/palette.test.ts +++ b/apps/desktop/src/palette.test.ts @@ -61,4 +61,15 @@ describe("palette", () => { item.run(); expect(currentUi().sheet).toEqual({ kind: "connectAgents" }); }); + + it("offers Show Welcome… and Show Get Started Checklist when typed for", () => { + resetUi(); + const items = paletteItems(view, shop, { kind: "all" }, navigator); + const welcome = items.find((item) => item.title === "Show Welcome…")!; + const checklist = items.find((item) => item.title === "Show Get Started Checklist")!; + expect(welcome.id.startsWith("other:")).toBe(true); + expect(checklist.id.startsWith("other:")).toBe(true); + welcome.run(); + expect(currentUi().sheet).toEqual({ kind: "welcome" }); + }); }); diff --git a/apps/desktop/src/palette.ts b/apps/desktop/src/palette.ts index 5fe73da..f8dc1b6 100644 --- a/apps/desktop/src/palette.ts +++ b/apps/desktop/src/palette.ts @@ -5,6 +5,7 @@ import { projectShortcut, SHORTCUTS, type Shortcut, serviceShortcut, shortcutLab import { tildePath } from "./paths"; import type { ServiceSelection } from "./selection"; import { isActive } from "./status"; +import { showChecklistAgain } from "./onboarding"; import { showAlert, showSheet } from "./ui"; import { checkForUpdates } from "./updates"; @@ -19,7 +20,7 @@ export type Navigator = { }; export type PaletteIcon = - | { kind: "symbol"; name: "folder" | "service" | "play" | "stop" | "restart" | "browser" | "terminal" | "editor" | "ports" | "new" | "keyboard" | "agents" } + | { kind: "symbol"; name: "folder" | "service" | "play" | "stop" | "restart" | "browser" | "terminal" | "editor" | "ports" | "new" | "keyboard" | "agents" | "help" } /** A Service: its colour (by position) and state glyph. */ | { kind: "service"; index: number; state: ServiceState }; @@ -98,6 +99,20 @@ export function paletteItems( keywords: "mcp claude cursor codex agent skill path terminal cli", run: () => showSheet({ kind: "connectAgents" }), }); + items.push({ + id: "other:show-welcome", + title: "Show Welcome…", + icon: { kind: "symbol", name: "help" }, + keywords: "help onboarding introduction tour first run", + run: () => showSheet({ kind: "welcome" }), + }); + items.push({ + id: "other:show-checklist", + title: "Show Get Started Checklist", + icon: { kind: "symbol", name: "help" }, + keywords: "help onboarding get started first run", + run: showChecklistAgain, + }); items.push({ id: "other:check-for-updates", title: "Check for Updates…", diff --git a/apps/desktop/src/ui.ts b/apps/desktop/src/ui.ts index d19f606..430dbdc 100644 --- a/apps/desktop/src/ui.ts +++ b/apps/desktop/src/ui.ts @@ -40,7 +40,7 @@ export type Sheet = | { kind: "importProject"; file: string; preview: ImportPreview } /** Connect your agents: Claude Code, Cursor and Codex, and the command in terminals. */ | { kind: "connectAgents" } - /** The first launch's welcome, ending in Add Project…. */ + /** The first launch's welcome, ending in Add Project…; also Help › Show Welcome…. */ | { kind: "welcome" }; /** The UI's own state, outside the core. */ diff --git a/apps/macos/App/AppModel.swift b/apps/macos/App/AppModel.swift index 71de27c..4755e86 100644 --- a/apps/macos/App/AppModel.swift +++ b/apps/macos/App/AppModel.swift @@ -179,6 +179,9 @@ final class AppModel { private(set) var isTelemetryNoticePending = false /// The first run's welcome and checklist; `nil` when the core couldn't open. private(set) var onboarding: Onboarding? + /// The checklist was asked for again from Help: it stays until closed, + /// even with every row ticked. Not saved, so the next launch is as before. + private(set) var isChecklistReplayed = false /// What the app sends when it opens, worded once for the notice and Settings. static let telemetrySummary = "When localhost opens it sends a random id, its version, your OS and architecture, and how it was installed. Never your projects, commands, paths or logs." @@ -813,12 +816,33 @@ final class AppModel { next.save() } - /// The welcome was finished or skipped: it never opens again. + /// The welcome was finished or skipped: it never opens by itself again. func finishWelcome(addingProject: Bool) { updateOnboarding { $0.hasSeenWelcome = true } presentedSheet = addingProject ? .addProject : nil } + /// Help › Show Welcome…: the first run's welcome on request, Projects or not. + func showWelcome() { + guard onboarding != nil, presentedSheet == nil else { return } + isShowingPalette = false + presentedSheet = .welcome + } + + /// Help › Show Get Started Checklist: brings the checklist back after it + /// was closed or completed. Its rows still tick from what is true. + func showChecklistAgain() { + guard onboarding != nil else { return } + isChecklistReplayed = true + updateOnboarding { $0.isChecklistDone = false } + } + + /// The checklist's close button: gone until asked for again. + func hideChecklist() { + isChecklistReplayed = false + updateOnboarding { $0.isChecklistDone = true } + } + /// Whether a Service on this Mac is Running now. var hasRunningService: Bool { core?.statuses.statuses.values.contains { $0.state == .running } ?? false diff --git a/apps/macos/App/CommandPalette.swift b/apps/macos/App/CommandPalette.swift index 55238e3..e6d5a3e 100644 --- a/apps/macos/App/CommandPalette.swift +++ b/apps/macos/App/CommandPalette.swift @@ -61,6 +61,16 @@ extension AppModel { keywords: "mcp claude cursor codex agent skill path terminal cli") { [weak self] in self?.showConnectAgents() }) + if onboarding != nil { + items.append(PaletteItem(id: "other:show-welcome", title: "Show Welcome…", icon: .symbol("questionmark.circle"), + keywords: "help onboarding introduction tour first run") { [weak self] in + self?.showWelcome() + }) + items.append(PaletteItem(id: "other:show-checklist", title: "Show Get Started Checklist", + icon: .symbol("questionmark.circle"), keywords: "help onboarding get started first run") { [weak self] in + self?.showChecklistAgain() + }) + } items.append(PaletteItem(id: "other:check-for-updates", title: "Check for Updates…", icon: .symbol("arrow.down.circle"), keywords: "update upgrade version release") { [weak self] in self?.updates.checkForUpdates() diff --git a/apps/macos/App/LocalhostApp.swift b/apps/macos/App/LocalhostApp.swift index b20cd3f..0977348 100644 --- a/apps/macos/App/LocalhostApp.swift +++ b/apps/macos/App/LocalhostApp.swift @@ -99,6 +99,15 @@ struct AppCommands: Commands { model.toggleKeyboardShortcuts() } .keyboardShortcut("/") + Divider() + Button("Show Welcome…") { + openWindow(id: "main") + model.showWelcome() + } + Button("Show Get Started Checklist") { + openWindow(id: "main") + model.showChecklistAgain() + } } CommandGroup(before: .windowList) { Button("Main Window") { openWindow(id: "main") } diff --git a/apps/macos/App/Views/GetStartedView.swift b/apps/macos/App/Views/GetStartedView.swift index af2a967..a8d8626 100644 --- a/apps/macos/App/Views/GetStartedView.swift +++ b/apps/macos/App/Views/GetStartedView.swift @@ -3,7 +3,8 @@ import SwiftUI /// The Get started checklist, at the foot of the sidebar once there is a /// Project: each row ticks from what is true, an open row takes the user -/// there. It goes away for good when every row is ticked or it is closed. +/// there. It goes away for good when every row is ticked or it is closed; +/// shown again from Help, it stays until closed. /// Ticks use the accent: green belongs to Service State. struct GetStartedView: View { @Environment(AppModel.self) private var model @@ -16,7 +17,7 @@ struct GetStartedView: View { ) let isComplete = items.allSatisfy(\.isDone) Group { - if !isComplete { + if !isComplete || model.isChecklistReplayed { checklist(items) } } @@ -28,7 +29,7 @@ struct GetStartedView: View { if isRunning { model.updateOnboarding { $0.hasStartedService = true } } } .onChange(of: isComplete, initial: true) { - if isComplete { model.updateOnboarding { $0.isChecklistDone = true } } + if isComplete, !model.isChecklistReplayed { model.updateOnboarding { $0.isChecklistDone = true } } } } } @@ -43,9 +44,7 @@ struct GetStartedView: View { Text("\(items.filter(\.isDone).count) of \(items.count)") .font(.system(size: 11, weight: .medium, design: .monospaced)) .foregroundStyle(.secondary) - Button("Hide Get Started", systemImage: "xmark") { - model.updateOnboarding { $0.isChecklistDone = true } - } + Button("Hide Get Started", systemImage: "xmark") { model.hideChecklist() } .labelStyle(.iconOnly) .buttonStyle(.plain) .font(.system(size: 10, weight: .semibold)) diff --git a/apps/macos/App/Views/WelcomeView.swift b/apps/macos/App/Views/WelcomeView.swift index 2e3d9d1..78ce0b8 100644 --- a/apps/macos/App/Views/WelcomeView.swift +++ b/apps/macos/App/Views/WelcomeView.swift @@ -3,7 +3,7 @@ import SwiftUI /// The first launch's welcome: what a Project, a Service and a Port are, one /// step each, ending in Add Project…. Skipping, Escape or finishing all mean -/// it never opens again. +/// it never opens by itself again; Help › Show Welcome… opens it anyway. struct WelcomeView: View { @Environment(AppModel.self) private var model @State private var index = 0 diff --git a/site/src/content/docs/quick-start.md b/site/src/content/docs/quick-start.md index 657b989..b3a9197 100644 --- a/site/src/content/docs/quick-start.md +++ b/site/src/content/docs/quick-start.md @@ -1,9 +1,11 @@ Shortcuts are written for macOS; on Linux and Windows use Ctrl for ⌘ and Alt for ⌥ (see [Keyboard shortcuts](/docs/keyboard)). -The first time you open localhost, a short welcome explains the three words that matter: a **Project** is a folder, a **Service** is a long-running command in it (`pnpm dev`, `docker compose up`), and its **Port** is how localhost knows it is Running. It ends in **Add Project…**, which is step 1 below; **Skip** or **Not Now** closes it, and it doesn't come back. If you used localhost before, you won't see it. +The first time you open localhost, a short welcome explains the three words that matter: a **Project** is a folder, a **Service** is a long-running command in it (`pnpm dev`, `docker compose up`), and its **Port** is how localhost knows it is Running. It ends in **Add Project…**, which is step 1 below; **Skip** or **Not Now** closes it, and it doesn't come back by itself. If you used localhost before, you won't see it. Once you have a Project, a **Get started** checklist at the foot of the sidebar ticks off adding a Project, adding a Service and starting your first one, plus connecting your coding agents if you want to. Click an open item to go there. It disappears once everything is ticked, or close it with **×**. +To see either again, choose **Show Welcome…** or **Show Get Started Checklist** from the **Help** menu (the **?** at the foot of the sidebar on Linux and Windows) or the command palette. + ## 1. Add a Project Click **Add Project…** (or press **⌘N**, or choose **New Project…** from the **+** in the sidebar) and choose your project's folder. localhost fills in a name and a **Key** (a short handle such as `my-saas`, used in logs and by the command line), then scans the folder and lists what it found: