# 01 — Getting Started

## AI grep hints

- Keys: `app.connections`, `app.settings`, `app.aiAssistant`, `app.dontSleep`, `app.dontSleepEnabledTooltip`, `app.dontSleepDisabledTooltip`, `app.trayExit`, `settings.dontSleepForegroundOnly`
- Topics: first launch, what KKTerm is, system tray, "Don't Sleep" mode, primary navigation, restoring the last Module
- Synonyms users may type: "open the app", "left bar icons", "tray icon", "keep awake", "prevent sleep", "why did it open dashboard", "last page", "remember module"

## What KKTerm is

KKTerm is a local-first Windows desktop workspace for terminal, SSH, SFTP, embedded URL Connections, RDP, and VNC work, with a built-in Dashboard and AI Assistant. Durable data lives in SQLite on the user's machine; secrets live in the Windows Credential Manager. There is no cloud account.

See `CONTEXT.md` for the canonical domain terms — **Connection**, **Quick Connect**, **Session**, **Tab**, **Pane**, **Dashboard View**, **Widget Instance**.

## First launch

On first launch KKTerm seeds:

- An empty Connection Tree (see [03-connections.md](03-connections.md)); when enabled, this same tree also hosts Child Connection Tabs under parent Connections.
- A single Dashboard View named `dashboard.defaultView` ("Default") with one App Launcher Widget Instance.
- Default Settings, persisted to SQLite.
- Locale defaulting to the user's OS language if a matching JSON exists under `src/i18n/locales/`, falling back to English.

No Sessions are open. The Workspace Canvas shows the **Default Launch State** — recent Connections and a brief overview. It is not a Module; it appears inside the Workspace Module whenever all Tabs are closed.

## App shell

The window is divided into four regions:

1. **Activity Rail** (48 px, left edge) — primary navigation. See [02-app-layout.md](02-app-layout.md).
2. **Connections Panel** (resizable, left) — visible inside the Workspace Module only. See [03-connections.md](03-connections.md).
3. **Workspace Canvas** (centre) — Tab Strip plus active Tab content for the current Module, or Child Connection Tabs in the Connection Tree when the top Tab Strip is hidden.
4. **AI Assistant Panel** (resizable, right) — `app.aiAssistant`. Collapsible. See [13-ai-assistant.md](13-ai-assistant.md).
5. **Status Bar** (bottom, full width) — host usage metrics and transient notifications that appear as popups just above the bar.

Resize handles use the labels `app.resizeConnections` and `app.resizeAiAssistant`.

## Primary navigation (Activity Rail)

Top to bottom:

- Workspace (label `workspace.workspace`)
- Dashboard (label `dashboard.moduleLabel`)
- Connection Rail shortcuts (label `app.connectionRail`, group `app.connectedConnectionsRail`) — pinned and currently-connected Connections appear here as direct shortcuts.
- Settings (label `app.settings`, anchored to the bottom)

Hover tooltips on rail icons are rendered by the shared `RailTooltip` (`src/app/RailTooltip.tsx`), never the browser's native `title` tooltip. On Windows desktop builds, `RailTooltip` mirrors labels through a native topmost tooltip so they can show above RDP ActiveX surfaces.

## System tray

KKTerm registers a Windows tray icon with recent Connections plus app controls:

- Recent Connections — selecting a Connection restores the window, switches to the Workspace Module, and opens or focuses that Connection's Tab.
- `app.trayDontSleep` — toggles the same state as the in-app "Don't Sleep" mode (see below).
- `app.trayExit` — exits the app unconditionally. This path bypasses the close-to-tray diversion.

## Closing the window

The title-bar close button is the standard close path. KKTerm always uses its custom title bar. When "minimize to tray" is enabled in Settings, the close button hides the window to the tray instead of exiting; when disabled, it exits normally. There are no in-app close-confirmation dialogs.

## "Don't Sleep" mode

`app.dontSleep` keeps the OS awake while KKTerm is running. Toggled either from the Activity Rail menu or the tray (`app.trayDontSleep`). Rail hover text uses `app.dontSleepEnabledTooltip` or `app.dontSleepDisabledTooltip` depending on state. Status popups use `app.dontSleepEnabled` and `app.dontSleepDisabled`. Errors surface as `app.dontSleepError`.

Settings - Don't Sleep (`settings.sectionDontSleep`) controls whether the keep-awake effect applies only while KKTerm is foregrounded. When `settings.dontSleepForegroundOnly` is on, enabling `app.dontSleep` stores the mode as enabled but the OS power assertion is active only while the main KKTerm window is focused and not minimized. When it is off, Don't Sleep keeps the OS awake globally while KKTerm is running.

## Where to go next

- To open a saved Connection: [03-connections.md](03-connections.md).
- To start a session fast: Quick Connect saves the Connection (reusing an identical existing SSH Connection when present) and opens it — see [03-connections.md](03-connections.md) §Quick Connect.
- To set up the AI Assistant: [13-ai-assistant.md](13-ai-assistant.md) plus [15-settings.md](15-settings.md) §AI.
