# Desktop

Desktop is the recommended first entry point for DotCraft. It works as an AppServer client and provides a visual UI for workspaces, sessions, diffs, plans, model configuration, automation review, and runtime status.

For first-time setup, follow [Getting Started](../../getting-started.md) for download, workspace selection, and model configuration. This page focuses on Desktop-specific panels and settings.

## Installation

### Use a Release

1. Download an installer from [GitHub Releases](https://github.com/DotHarness/dotcraft/releases).
2. Start DotCraft.
3. Choose a project folder as the workspace.

### Run from Source

```bash
cd desktop
npm install
npm run dev
```

When running from source, Desktop looks for `dotcraft` on `PATH`. If it cannot find it, set the AppServer / `dotcraft` binary path in settings. Build installer artifacts with `npm run dist`; outputs land in `desktop/dist/`.

## Startup Arguments

```bash
DotCraft --app-server /path/to/dotcraft
DotCraft --workspace /path/to/project
```

## Desktop-Specific Settings

| Section | Purpose |
|---|---|
| **Settings → General** | Current workspace path, AppServer binary path, language |
| **Settings → Personalization** | Long-term memory / Dreams switches, run-now, auto-update, reset memory |
| **Settings → Model Providers** | Personal providers, credentials, endpoints, workspace provider and model |
| **Settings → Sub Agents** | Reuse external CLI sessions (see [SubAgents](../subagents.md)) |
| **Settings → Connection** | Switch between local Hub and remote AppServer |

### Personalization → Dreams

- **Run now** — trigger a Dreams consolidation immediately.
- **Auto-update Dreams** — off: new Dreams stay pending; on: future successful runs auto-apply as active.
- **Manage Dreams** — list of recent runs; each opens Dashboard for diff, trace, apply, discard, cancel, archive.
- **Reset memory** — clear `MEMORY.md`, `HISTORY.md`, `.craft/dreams/`, and derived caches in one click. It does not delete sessions, config, skills, or automations.

See [Memory & Dreams](../memory.md) for the full picture.

### Model Providers

- Provider credentials and endpoints are written to personal `~/.craft/config.json`, **not** the workspace.
- The workspace only stores `ProviderId` and `Model`, so shared workspace config never holds secrets.
- Desktop currently supports OpenAI and Anthropic providers.
- Use **Test** to check credential and model-list reachability. If a provider cannot list models, save it and type the model name manually.

### Connection (Local vs Remote)

- **Local (default)**: Desktop launches or discovers a workspace AppServer through Hub; multiple entries share the same process.
- **Remote**: connect to an existing WebSocket AppServer. Desktop does not restart the remote process, only tests and switches.
- Remote URL/token changes are first probed against a draft connection. Failures are not saved, so a bad URL never traps you on the next start.
- When Desktop is launched with `--remote`, the persistent connection switch in Settings is disabled.

## What's New

After Desktop is upgraded, **What's New** appears once when you enter a ready workspace UI and highlights the current version's new capabilities. Animated previews are downloaded from the DotHarness resources repo, verified, and cached locally; the automatic prompt waits for previews, while manual reopen shows text and placeholders immediately. Reopen any time via **Help → What's New** or the version label at the bottom of the sidebar.

## Updates

On startup, DotCraft checks [GitHub Releases](https://github.com/DotHarness/dotcraft/releases) for a newer release tag. When a platform installer is available, a highlighted download button appears in the title bar. Select it to review the release, download the installer with progress, then DotCraft quits and opens the downloaded installer.

## Usage Examples

| Scenario | Desktop path |
|---|---|
| First-time setup | Choose workspace → configure model → create session |
| Inspect agent work | Open session detail, diff, trace, or Dashboard |
| Review automation tasks | Open Automations and inspect pending review items |
| Switch projects | Choose another workspace so config and tasks stay project-scoped |
| Take back SubAgent control | Settings → Sub Agents → disable reuse external CLI sessions |

## Advanced

- Desktop consumes the AppServer Wire Protocol, so it shares the same session core with TUI, ACP, and external channels.
- Image attachments live under `.craft/attachments/images/` and survive restart.

## Troubleshooting

### No session is available after startup

Confirm a workspace is selected and the AppServer / `dotcraft` binary can run.

### Settings changes do not apply

Provider and model selections take effect for new sessions. Existing provider-aware threads keep their captured provider and model unless you explicitly change the active thread's model. AppServer, port, and entry-point settings require restarting Desktop or the background host. See [Settings Lifecycle](../../developing/settings-lifecycle.md).

### The Automations panel is empty

Use Gateway or a host that loads Automations, and enable the relevant task source. See [Automations](../automations.md).

## Related

- [Getting Started](../../getting-started.md)
- [TUI](./tui.md)
- [Observability](../observability.md)
- [Settings Lifecycle](../../developing/settings-lifecycle.md)
