# zidane-ui/settings/headless

Import: `import { … } from 'zidane-ui/settings/headless'`. Source: [ui/src/settings/headless/index.ts](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/index.ts).

## Functions

### `accountsFocusId`

Function.

A provider's row on Settings › Accounts, as a deep link's focus names it
(`SettingsShell`'s `initialFocus`).

```ts
function accountsFocusId(provider: string): string
```

**Parameters**

- `provider` (`string`): The provider's key.

**Returns** `string`

Source: [ui/src/settings/headless/providers.ts:119](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/providers.ts#L119)

### `accountsKeyFocusId`

Function.

A provider's API key field on Settings › Accounts, as a deep link's focus
names it: the row opens on its key form.

```ts
function accountsKeyFocusId(provider: string): string
```

**Parameters**

- `provider` (`string`): The provider's key.

**Returns** `string`

Source: [ui/src/settings/headless/providers.ts:129](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/providers.ts#L129)

### `createPerfMonitor`

Function.

Creates a monitor over a host.

```ts
function createPerfMonitor(
  host: SettingsPerformanceHost,
  capacity?: number,
): PerfMonitor
```

**Parameters**

- `host` (`SettingsPerformanceHost`): The host's performance member.
- `capacity?` (`number`, default `PERF_HISTORY`): Samples kept.

**Returns** `PerfMonitor`

Source: [ui/src/settings/headless/performance.ts:281](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L281)

### `createSettingsResource`

Function.

Creates a resource over `read`.

```ts
function createSettingsResource<T>(
  read: () => Promise<T>,
  options?: SettingsResourceOptions<T>,
): SettingsResource<T>
```

**Type parameters**

- `T`

**Parameters**

- `read` (`() => Promise<T>`): Reads the value; a rejection lands in `error`.
- `options?` (`SettingsResourceOptions<T>`, default `{}`): An initial value.

**Returns** `SettingsResource<T>`

Source: [ui/src/settings/headless/resource.ts:22](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/resource.ts#L22)

### `describedOn`

Function.

What a page or row says under its title: on a server's settings (`host`, its name) its server wording when
it has one, else its description.

```ts
function describedOn(
  part: { description: string; serverDescription?: string },
  host?: string,
): string
```

**Parameters**

- `part` (`{ description: string; serverDescription?: string }`): The page or row.
- `host?` (`string`): The server whose settings are shown. Absent: this computer's.

**Returns** `string`: The description.

Source: [ui/src/settings/headless/layout.ts:661](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L661)

### `enabledMcpsAfterAdd`

Function.

After adding a server: the allowlist with it turned on, or `undefined` to
leave the settings alone. Only a server that wasn't listed before is
turned on (an edit keeps its toggle), and only when the list is known.
Same rule as the TUI and a server's `mcp.upsert`.

```ts
function enabledMcpsAfterAdd(
  enabled: readonly string[] | undefined,
  listed: readonly { name: string }[] | null | undefined,
  name: string,
): string[] | undefined
```

**Parameters**

- `enabled` (`readonly string[] | undefined`): The stored `enabledMcps`.
- `listed` (`readonly { name: string }[] | null | undefined`): The servers listed before the add (`null`: not read yet).
- `name` (`string`): The server added.

**Returns** `string[] | undefined`

Source: [ui/src/settings/headless/mcp.ts:283](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L283)

### `enabledMcpTools`

Function.

The tools of a server that are on (`disabledMcpTools` is a deny list).

```ts
function enabledMcpTools(
  server: string,
  tools: readonly SettingsMcpTool[],
  disabled: Record<string, readonly string[]> | undefined,
): ReadonlySet<string>
```

**Parameters**

- `server` (`string`): The server's name.
- `tools` (`readonly SettingsMcpTool[]`): Its tools.
- `disabled` (`Record<string, readonly string[]> | undefined`): The stored `disabledMcpTools`.

**Returns** `ReadonlySet<string>`

Source: [ui/src/settings/headless/mcp.ts:234](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L234)

### `enabledNames`

Function.

The names that are on.

```ts
function enabledNames(
  list: readonly string[] | undefined,
  catalog: readonly string[],
): ReadonlySet<string>
```

**Parameters**

- `list` (`readonly string[] | undefined`): The stored allowlist (`undefined`: every entry).
- `catalog` (`readonly string[]`): The names in the catalog.

**Returns** `ReadonlySet<string>`

Source: [ui/src/settings/headless/enabled.ts:24](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/enabled.ts#L24)

### `formatDuration`

Function.

`0.4 ms`, `38 ms`, `2.1 s`.

```ts
function formatDuration(ms: number): string
```

**Parameters**

- `ms` (`number`): A duration.

**Returns** `string`

Source: [ui/src/settings/headless/performance.ts:519](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L519)

### `formatMemory`

Function.

`512 KB`, `84 MB`, `1.4 GB`.

```ts
function formatMemory(bytes: number): string
```

**Parameters**

- `bytes` (`number`): A size.

**Returns** `string`

Source: [ui/src/settings/headless/performance.ts:507](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L507)

### `formatPercent`

Function.

`12.3%` under 100, `140%` above (several cores).

```ts
function formatPercent(value: number): string
```

**Parameters**

- `value` (`number`): A percentage.

**Returns** `string`

Source: [ui/src/settings/headless/performance.ts:497](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L497)

### `hasCredentialChoice`

Function.

Whether a provider holds more than one stored credential, so there is a
choice of which one is in use (the TUI's expandable auth rows).

```ts
function hasCredentialChoice(provider: Pick<SettingsProvider, 'methods'>): boolean
```

**Parameters**

- `provider` (`Pick<SettingsProvider, 'methods'>`): The provider.

**Returns** `boolean`

Source: [ui/src/settings/headless/providers.ts:139](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/providers.ts#L139)

### `hasLaunched`

Function.

Whether a sample holds anything sessions or terminals launched.

```ts
function hasLaunched(sample: PerfSample): boolean
```

**Parameters**

- `sample` (`PerfSample`): The sample.

**Returns** `boolean`

Source: [ui/src/settings/headless/performance.ts:478](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L478)

### `isPanelPage`

Function.

Whether a page is drawn by one panel (rather than rows).

```ts
function isPanelPage(page: SettingsPage): page is SettingsPanelPage
```

**Parameters**

- `page` (`SettingsPage`): The page.

**Returns** `page is SettingsPanelPage`: `true` for a panel page.

Source: [ui/src/settings/headless/layout.ts:673](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L673)

### `isSettingsError`

Function.

Whether a value is a [`SettingsError`](https://zidane.si/docs/reference/ui-settings-headless.md#SettingsError).

```ts
function isSettingsError(value: unknown): value is SettingsError
```

**Parameters**

- `value` (`unknown`): Anything (a rejection's reason).

**Returns** `value is SettingsError`: `true` for a [`SettingsError`](https://zidane.si/docs/reference/ui-settings-headless.md#SettingsError).

Source: [ui/src/settings/headless/host.ts:118](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/host.ts#L118)

### `keyedSettingsResources`

Function.

Keeps one resource per key (a folder, a skill), so every reader of the same
key shares one read.

```ts
function keyedSettingsResources<K, T>(
  make: (key: K) => SettingsResource<T>,
): (key: K) => SettingsResource<T>
```

**Type parameters**

- `K`
- `T`

**Parameters**

- `make` (`(key: K) => SettingsResource<T>`): Builds the resource for a key.

**Returns** `(key: K) => SettingsResource<T>`

Source: [ui/src/settings/headless/resource.ts:64](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/resource.ts#L64)

### `layoutSearchEntries`

Function.

One entry per row a layout page shows: a catalog row with its keywords
and a choice's option labels, a custom row's or a panel's own entries, an
app action.

```ts
function layoutSearchEntries(
  page: SettingsPage,
  ctx: LayoutSearchContext,
): SettingsSearchEntry[]
```

**Parameters**

- `page` (`SettingsPage`): The layout page.
- `ctx` (`LayoutSearchContext`): Editing a server, and the actions wired in.

**Returns** `SettingsSearchEntry[]`: The page's entries.

Source: [ui/src/settings/headless/search.ts:47](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/search.ts#L47)

### `layoutSections`

Function.

The shell's sections for layout pages, in order.

```ts
function layoutSections(
  pages: readonly SettingsPage[],
  options: LayoutSectionsOptions,
): SettingsSection[]
```

**Parameters**

- `pages` (`readonly SettingsPage[]`): The pages to list.
- `options` (`LayoutSectionsOptions`): The search context and the bodies.

**Returns** `SettingsSection[]`

Source: [ui/src/settings/headless/layout-sections.ts:28](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout-sections.ts#L28)

### `listLength`

Function.

A list's length; `undefined` for an answer that isn't a list (a server too old, a failed read).

```ts
function listLength(list: unknown): number | undefined
```

**Parameters**

- `list` (`unknown`): What a read answered.

**Returns** `number | undefined`

Source: [ui/src/settings/headless/page-counts.ts:16](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/page-counts.ts#L16)

### `mcpBadge`

Function.

The badge of a server. A refused key or a failed connection comes from the
last test; a sign-in in progress (`live`) or a sign-in problem wins.

```ts
function mcpBadge(
  auth: SettingsMcpAuthState,
  test: SettingsMcpTest | undefined,
  live: boolean,
): SettingsMcpBadge
```

**Parameters**

- `auth` (`SettingsMcpAuthState`): Its sign-in state.
- `test` (`SettingsMcpTest | undefined`): Its last test.
- `live` (`boolean`): A sign-in of this server runs here.

**Returns** `SettingsMcpBadge`

Source: [ui/src/settings/headless/mcp.ts:216](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L216)

### `mcpRunning`

Function.

How a server runs now, from the host's instances: `null` when none runs.
Retired processes count only while no fresh one runs (they close soon).

```ts
function mcpRunning(
  name: string,
  instances: readonly SettingsMcpInstance[],
): SettingsMcpRunning | null
```

**Parameters**

- `name` (`string`): The server.
- `instances` (`readonly SettingsMcpInstance[]`): The host's instances.

**Returns** `SettingsMcpRunning | null`

Source: [ui/src/settings/headless/mcp.ts:195](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L195)

### `mcpSettingsAfterRemove`

Function.

What a removal writes: the server out of `enabledMcps`,
`disabledMcpTools` and `mcpSharing`, so a later server of the same name
starts from the defaults. Empty when none names it.

```ts
function mcpSettingsAfterRemove(
  values: Pick<Settings, 'enabledMcps' | 'disabledMcpTools' | 'mcpSharing'>,
  name: string,
): Partial<Settings>
```

**Parameters**

- `values` (`Pick<Settings, 'enabledMcps' | 'disabledMcpTools' | 'mcpSharing'>`): The settings.
- `name` (`string`): The server removed.

**Returns** `Partial<Settings>`

Source: [ui/src/settings/headless/mcp.ts:300](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L300)

### `mcpShareable`

Function.

A server whose process the host may share between sessions: a `stdio`
server the host says runs on it (`scope: 'host'`). Remote and `context`
servers run per session.

```ts
function mcpShareable(server: Pick<SettingsMcpServer, 'transport' | 'scope'>): boolean
```

**Parameters**

- `server` (`Pick<SettingsMcpServer, 'transport' | 'scope'>`): The server.

**Returns** `boolean`

Source: [ui/src/settings/headless/mcp.ts:148](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L148)

### `mcpSharedNow`

Function.

Whether a server shares one process: the `mcpSharing` setting, else its config, else yes.

```ts
function mcpSharedNow(
  server: Pick<SettingsMcpServer, 'name' | 'shared'>,
  sharing: Record<string, boolean> | undefined,
): boolean
```

**Parameters**

- `server` (`Pick<SettingsMcpServer, 'name' | 'shared'>`): The server.
- `sharing` (`Record<string, boolean> | undefined`): The stored `mcpSharing`.

**Returns** `boolean`

Source: [ui/src/settings/headless/mcp.ts:158](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L158)

### `mcpSharingWith`

Function.

`mcpSharing` with one server's choice set.

```ts
function mcpSharingWith(
  sharing: Record<string, boolean> | undefined,
  name: string,
  shared: boolean,
): Record<string, boolean>
```

**Parameters**

- `sharing` (`Record<string, boolean> | undefined`): The stored `mcpSharing`.
- `name` (`string`): The server.
- `shared` (`boolean`): Share one process.

**Returns** `Record<string, boolean>`

Source: [ui/src/settings/headless/mcp.ts:172](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L172)

### `nestProcesses`

Function.

Nests [`processTree`](https://zidane.si/docs/reference/ui-settings-headless.md#processTree)'s rows (each parent before its children).

```ts
function nestProcesses(rows: readonly PerfProcessRow[]): PerfProcessNode[]
```

**Parameters**

- `rows` (`readonly PerfProcessRow[]`): One origin's rows, in tree order.

**Returns** `PerfProcessNode[]`: The roots.

Source: [ui/src/settings/headless/performance.ts:412](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L412)

### `nextOption`

Function.

The option after `current` in a choice's cycle (the first one after the last, or for an unknown value).

```ts
function nextOption(
  row: SettingsChoice,
  current: unknown,
): string | number | boolean | readonly string[] | Record<string, readonly string[]> | Record<string, unknown> | Record<string, boolean> | Space[] | EnvironmentSettings | Record<string, Record<string, unknown>> | undefined
```

**Parameters**

- `row` (`SettingsChoice`): The choice.
- `current` (`unknown`): The setting's value now.

**Returns** `string | number | boolean | readonly string[] | Record<string, readonly string[]> | Record<string, unknown> | Record<string, boolean> | Space[] | EnvironmentSettings | Record<string, Record<string, unknown>> | undefined`: The next value.

Source: [ui/src/settings/headless/catalog.ts:395](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/catalog.ts#L395)

### `perfSeries`

Function.

One value per sample, for a sparkline.

```ts
function perfSeries(
  samples: readonly PerfSample[],
  pick: (sample: PerfSample) => number | undefined,
): number[]
```

**Parameters**

- `samples` (`readonly PerfSample[]`): Oldest first.
- `pick` (`(sample: PerfSample) => number | undefined`): The value of a sample (`undefined`: a gap, drawn as 0).

**Returns** `number[]`

Source: [ui/src/settings/headless/performance.ts:488](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L488)

### `processGroups`

Function.

The processes as two trees, the app's own and what was launched: a
launched tree's roots are what a session or a terminal started.

```ts
function processGroups(
  processes: readonly PerfProcess[],
): Record<PerfOrigin, PerfProcessRow[]>
```

**Parameters**

- `processes` (`readonly PerfProcess[]`): One sample's.

**Returns** `Record<PerfOrigin, PerfProcessRow[]>`

Source: [ui/src/settings/headless/performance.ts:387](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L387)

### `processTree`

Function.

The processes as a tree, each parent before its children, siblings busiest first.

```ts
function processTree(processes: readonly PerfProcess[]): PerfProcessRow[]
```

**Parameters**

- `processes` (`readonly PerfProcess[]`): One sample's.

**Returns** `PerfProcessRow[]`

Source: [ui/src/settings/headless/performance.ts:356](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L356)

### `searchSettings`

Function.

The entries every term of `query` matches, in index order; none for a blank query.

```ts
function searchSettings<H extends SettingsSearchEntry>(
  hits: readonly H[],
  query: string,
): H[]
```

**Type parameters**

- `H` (`extends SettingsSearchEntry`)

**Parameters**

- `hits` (`readonly H[]`): The index.
- `query` (`string`): What the user typed.

**Returns** `H[]`: The matching entries.

Source: [ui/src/settings/headless/search.ts:135](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/search.ts#L135)

### `sectionSearchHits`

Function.

The search index of the shell's sections: each section's `search`
entries, or the section itself (title, description, keywords) when it
has none, then `extra` (entries an app adds, e.g. extension options).

```ts
function sectionSearchHits(
  sections: readonly SettingsSection[],
  extra?: readonly SettingsSearchHit[],
): SettingsSearchHit[]
```

**Parameters**

- `sections` (`readonly SettingsSection[]`): The shell's sections.
- `extra?` (`readonly SettingsSearchHit[]`, default `[]`): More entries, after the sections'.

**Returns** `SettingsSearchHit[]`: The index.

Source: [ui/src/settings/headless/search.ts:107](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/search.ts#L107)

### `sessionGroups`

Function.

The processes per session, busiest first: each session's own tree.

```ts
function sessionGroups(processes: readonly PerfProcess[]): PerfSessionGroup[]
```

**Parameters**

- `processes` (`readonly PerfProcess[]`): One sample's.

**Returns** `PerfSessionGroup[]`

Source: [ui/src/settings/headless/performance.ts:451](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L451)

### `settingsCount`

Function.

How many settings a page holds, as this table describes it (the rail's
count): a page of rows, each table row and each part of a custom row,
actions aside; a panel, the table settings it draws and the rows its search
entries name (those with a `key`). Pages that list things (skills,
servers…) count those from their data instead.

```ts
function settingsCount(page: SettingsPage, server: boolean): number
```

**Parameters**

- `page` (`SettingsPage`): The page.
- `server` (`boolean`): Editing a server: `localOnly` rows are left out.

**Returns** `number`: How many settings it holds.

Source: [ui/src/settings/headless/layout.ts:691](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L691)

### `settingsMcpServerOf`

Function.

A server of a host's catalog (a zidane-server's `catalog.mcps`) as MCP servers lists it: its sign-in
state, tools and last test from `status` (an older host sends none: idle, untested). Removable when it
is the host user's (`mcp.remove` edits that file only).

```ts
function settingsMcpServerOf(entry: HostCatalogMcp): SettingsMcpServer
```

**Parameters**

- `entry` (`HostCatalogMcp`): The catalog entry.

**Returns** `SettingsMcpServer`

Source: [ui/src/settings/headless/mcp.ts:84](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L84)

### `settingsPageCounts`

Function.

Each page's count: a list page's length from `lists`, a page of rows its settings. Zero and unknown
counts are left out.

```ts
function settingsPageCounts(
  pages: readonly SettingsPage[],
  lists: Partial<Record<SettingsTabId, number | undefined>>,
  server: boolean,
): Partial<Record<SettingsTabId, number>>
```

**Parameters**

- `pages` (`readonly SettingsPage[]`): The pages the nav shows.
- `lists` (`Partial<Record<SettingsTabId, number | undefined>>`): The list pages' lengths (`undefined`: unknown).
- `server` (`boolean`): The settings are a server's (its local-only rows are not counted).

**Returns** `Partial<Record<SettingsTabId, number>>`

Source: [ui/src/settings/headless/page-counts.ts:28](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/page-counts.ts#L28)

### `settingsSearchHits`

Function.

[`layoutSearchEntries`](https://zidane.si/docs/reference/ui-settings-headless.md#layoutSearchEntries) for every page, each hit on its page.

```ts
function settingsSearchHits(
  pages: readonly SettingsPage[],
  ctx: LayoutSearchContext,
): SettingsSearchHit[]
```

**Parameters**

- `pages` (`readonly SettingsPage[]`): The pages offered.
- `ctx` (`LayoutSearchContext`): Editing a server, and the actions wired in.

**Returns** `SettingsSearchHit[]`: Every page's entries, in page order.

Source: [ui/src/settings/headless/search.ts:94](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/search.ts#L94)

### `shown`

Function.

Whether a page, section or row is offered: everything but `localOnly` parts while editing a server, Spaces
included when the app's spaces are the server's.

```ts
function shown(
  part: SettingsPage | SettingsPageSection | SettingsRow,
  server: boolean,
  spacesOnServer?: boolean,
): boolean
```

**Parameters**

- `part` (`SettingsPage | SettingsPageSection | SettingsRow`): The page, section or row.
- `server` (`boolean`): Editing a server.
- `spacesOnServer?` (`boolean`, default `false`): The app's spaces live in the server's settings (the web app's do).

**Returns** `boolean`: Whether it is offered.

Source: [ui/src/settings/headless/layout.ts:730](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L730)

### `toggleEnabled`

Function.

The allowlist after turning `name` on or off.

```ts
function toggleEnabled(
  list: readonly string[] | undefined,
  catalog: readonly string[],
  name: string,
): string[]
```

**Parameters**

- `list` (`readonly string[] | undefined`): The stored allowlist (`undefined`: every entry).
- `catalog` (`readonly string[]`): The names in the catalog (the ones the list governs here).
- `name` (`string`): The entry toggled.

**Returns** `string[]`: The new list, sorted: this catalog's enabled names plus every stored name off it.

Source: [ui/src/settings/headless/enabled.ts:36](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/enabled.ts#L36)

### `toggleMcpTool`

Function.

`disabledMcpTools` after turning one tool on or off. Names the server no
longer lists drop out; an empty list drops the server, an empty map is
`undefined`.

```ts
function toggleMcpTool(
  server: string,
  tools: readonly SettingsMcpTool[],
  disabled: Record<string, readonly string[]> | undefined,
  tool: string,
): Record<string, readonly string[]> | undefined
```

**Parameters**

- `server` (`string`): The server's name.
- `tools` (`readonly SettingsMcpTool[]`): Its tools.
- `disabled` (`Record<string, readonly string[]> | undefined`): The stored `disabledMcpTools`.
- `tool` (`string`): The tool toggled.

**Returns** `Record<string, readonly string[]> | undefined`

Source: [ui/src/settings/headless/mcp.ts:256](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L256)

### `toSettingsError`

Function.

Wraps whatever a host call threw as a [`SettingsError`](https://zidane.si/docs/reference/ui-settings-headless.md#SettingsError).

```ts
function toSettingsError(error: unknown, kind?: SettingsErrorKind): SettingsError
```

**Parameters**

- `error` (`unknown`): What was thrown.
- `kind?` (`SettingsErrorKind`, default `'failed'`): The kind when `error` isn't a [`SettingsError`](https://zidane.si/docs/reference/ui-settings-headless.md#SettingsError) already.

**Returns** `SettingsError`: The typed error.

Source: [ui/src/settings/headless/host.ts:106](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/host.ts#L106)

### `visiblePages`

Function.

The pages this modal offers: Hosts needs remote hosts on, and while it edits
a server the pages (and sections and rows, see `shown`) composing this
computer's files drop out.

```ts
function visiblePages(opts: { hostsEnabled: boolean; server: boolean }): SettingsPage[]
```

**Parameters**

- `opts` (`{ hostsEnabled: boolean; server: boolean }`): Editing a server, and whether remote hosts are on.

**Returns** `SettingsPage[]`: The pages offered, in order.

Source: [ui/src/settings/headless/layout.ts:717](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L717)

## Constants

### `DEFAULT_SETTINGS`

Constant.

Default value of every setting.

```ts
const DEFAULT_SETTINGS: Settings
```

Source: [dist/media-type-BzRZ4FqT.d.ts:616](https://github.com/Tahul/zidane/blob/main/dist/media-type-BzRZ4FqT.d.ts#L616)

### `DEFAULT_SETTINGS_LABELS`

Constant.

The default English strings of the settings components.

```ts
const DEFAULT_SETTINGS_LABELS: { settingsAdminOnly: string; settingsBlockedTitle: (requirement: string) => string; settingsClose: string; settingsCopyCommand: string; settingsDurabilityUnavailable: string; settingsError: (error: SettingsError) => string; settingsHostSwitcher: string; settingsHostSwitcherTrigger: (host: string) => string; settingsKilled: (env: string) => string; settingsKilledTitle: (env: string) => string; settingsLoading: string; settingsNavLabel: string; settingsNoResults: (query: string) => string; settingsRestrictedEmpty: string; settingsRetry: string; settingsSearchLabel: string; settingsSearchPlaceholder: string; settingsServerStart: string; settingsTitle: string; settingsUnavailable: string }
```

Source: [ui/src/settings/headless/labels.ts:11](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/labels.ts#L11)

### `HIDDEN_TABLE_KEYS`

Constant.

Table choices no page places: TUI-only (`targetFps`) or drawn by Appearance (`theme`).

```ts
const HIDDEN_TABLE_KEYS: readonly ['theme', 'targetFps']
```

Source: [ui/src/settings/headless/layout.ts:116](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L116)

### `PERF_HISTORY`

Constant.

Samples kept: 5 minutes at the desktop app's 2 s.

```ts
const PERF_HISTORY = 150
```

Source: [ui/src/settings/headless/performance.ts:273](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L273)

### `SETTINGS_CHOICE_BY_KEY`

Constant.

The catalog's choices by key.

```ts
const SETTINGS_CHOICE_BY_KEY: Map<string, SettingsChoice<keyof Settings>>
```

Source: [ui/src/settings/headless/search.ts:26](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/search.ts#L26)

### `SETTINGS_CHOICES`

Constant.

The catalog's choices, in display order.

```ts
const SETTINGS_CHOICES: readonly SettingsChoice[]
```

Source: [ui/src/settings/headless/catalog.ts:401](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/catalog.ts#L401)

### `SETTINGS_PAGES`

Constant.

Every page: the rail's entries in order, then the sub-pages (each listed
under its `parent`). Extensions is an entry of its own, after Agent: the
extensions' settings entries list under it (`useExtensionSettingsSections`).
One flat literal: the website's evaluator skips spreads.

```ts
const SETTINGS_PAGES: readonly SettingsPage[]
```

Source: [ui/src/settings/headless/layout.ts:387](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L387)

### `SETTINGS_TOGGLE_BY_KEY`

Constant.

The catalog's toggles by key.

```ts
const SETTINGS_TOGGLE_BY_KEY: Map<string, SettingsToggle>
```

Source: [ui/src/settings/headless/search.ts:24](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/search.ts#L24)

### `SETTINGS_TOGGLES`

Constant.

The catalog's toggles, in display order.

```ts
const SETTINGS_TOGGLES: readonly SettingsToggle[]
```

Source: [ui/src/settings/headless/catalog.ts:61](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/catalog.ts#L61)

## Interfaces

### `LayoutSearchContext`

Interface.

What a layout page's entries depend on.

```ts
interface LayoutSearchContext
```

**Properties**

- `actions` (`readonly { description: string; id: SettingsActionId; label: string }[]`): The app actions wired in; a row for a missing one is skipped.
- `server` (`boolean`): Editing a server: its `localOnly` parts are left out.
- `spacesOnServer?` (`boolean`): The app's spaces live in the server's settings (the web app's do): Spaces stays while `server`.

Source: [ui/src/settings/headless/search.ts:29](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/search.ts#L29)

### `LayoutSectionsOptions`

Interface.

Options for [`layoutSections`](https://zidane.si/docs/reference/ui-settings-headless.md#layoutSections).

```ts
interface LayoutSectionsOptions extends LayoutSearchContext
```

**Properties**

- `actions` (`readonly { description: string; id: SettingsActionId; label: string }[]`, from `LayoutSearchContext`): The app actions wired in; a row for a missing one is skipped.
- `host?` (`string`): The server whose settings these are, by name: its pages say `serverDescription`. Absent: this computer's.
- `server` (`boolean`, from `LayoutSearchContext`): Editing a server: its `localOnly` parts are left out.
- `spacesOnServer?` (`boolean`, from `LayoutSearchContext`): The app's spaces live in the server's settings (the web app's do): Spaces stays while `server`.
- `renderPanel` (`(page: SettingsPanelPage) => unknown`): The body of a panel page (the app's panel).
- `renderRows` (`(page: SettingsSectionsPage) => unknown`): The body of a page of rows (`SettingsRowsPage` with the app's custom rows).

Source: [ui/src/settings/headless/layout-sections.ts:13](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout-sections.ts#L13)

### `PerfChannel`

Interface.

One message channel's counters.

```ts
interface PerfChannel
```

**Properties**

- `channel` (`string`): The channel's name.
- `count` (`number`): Messages since the counters were last reset.
- `direction` (`PerfChannelDirection`): Which way its messages go.
- `maxMs` (`number`): The slowest one.
- `p95Ms` (`number`): 95th percentile.
- `totalMs` (`number`): Time they took, summed (invokes: until answered).

Source: [ui/src/settings/headless/performance.ts:93](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L93)

### `PerfGpu`

Interface.

Whole-GPU use: every app's.

```ts
interface PerfGpu
```

**Properties**

- `device` (`number`): Percent.
- `memory?` (`number`): In use, bytes.
- `renderer?` (`number`): Renderer utilisation, percent, where the GPU reports it.
- `tiler?` (`number`): Tiler utilisation, percent, where the GPU reports it.

Source: [ui/src/settings/headless/performance.ts:135](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L135)

### `PerfHotFunction`

Interface.

A function a profile spent time in.

```ts
interface PerfHotFunction
```

**Properties**

- `fn` (`string`): The function's name.
- `line` (`number`): Its line there.
- `selfMs` (`number`): Time in the function itself, not in what it called.
- `share` (`number`): Of the profile's busy time (0–1).
- `url` (`string`): The script it is in.

Source: [ui/src/settings/headless/performance.ts:190](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L190)

### `PerfLag`

Interface.

The host's event-loop delay over the last interval, ms.

```ts
interface PerfLag
```

**Properties**

- `max` (`number`): The worst.
- `p50` (`number`): Median.
- `p99` (`number`): 99th percentile.

Source: [ui/src/settings/headless/performance.ts:125](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L125)

### `PerfMonitor`

Interface.

A view's window on the host's samples.

```ts
interface PerfMonitor extends Readable<PerfMonitorState>
```

**Properties**

- `get` (`() => PerfMonitorState`, from `Readable`): Returns the current value.
- `start` (`() => () => void`): Reads the history, then follows new samples; returns the stop. Counted: each start needs its stop.
- `subscribe` (`(onChange: () => void) => () => void`, from `Readable`): Registers a listener called after the value changes. Returns a function that removes the listener.

Source: [ui/src/settings/headless/performance.ts:267](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L267)

### `PerfMonitorState`

Interface.

What a monitor holds.

```ts
interface PerfMonitorState
```

**Properties**

- `error` (`PerfWatchError | null`): Why the host can't be watched; `null` while it can (a sample clears it).
- `samples` (`readonly PerfSample[]`): Oldest first, at most the monitor's capacity.

Source: [ui/src/settings/headless/performance.ts:259](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L259)

### `PerfOsThread`

Interface.

One OS thread of a process (no name on macOS).

```ts
interface PerfOsThread
```

**Properties**

- `cpu` (`number`): CPU over the last interval, percent of one core.
- `id` (`string`): The OS thread id.
- `label` (`string`): Its name, where the OS gives one.

Source: [ui/src/settings/headless/performance.ts:177](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L177)

### `PerfProcess`

Interface.

One process of the app, its daemon, or a program either started.

```ts
interface PerfProcess
```

**Properties**

- `cpu` (`number`): CPU over the last interval, percent of one core.
- `detail?` (`string`): More: the command line, the service, the page's URL.
- `kind` (`PerfProcessKind`): What it is to the app.
- `label` (`string`): A short name.
- `mcp?` (`PerfProcessMcp`): An MCP server's process: its server, and whether sessions share it.
- `memory` (`number`): Resident memory, bytes.
- `origin` (`PerfOrigin`): Whose cost it is.
- `parent` (`number | null`): The process it runs under in the tree shown (`null`: a root).
- `pid` (`number`): The OS process id.
- `session?` (`PerfProcessSession`): The session it runs for: a process a session started (a command, a terminal, its own MCP server), or one under it.

Source: [ui/src/settings/headless/performance.ts:32](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L32)

### `PerfProcessMcp`

Interface.

The MCP server a process runs.

```ts
interface PerfProcessMcp
```

**Properties**

- `name` (`string`): The server's name.
- `sessions` (`number`): Sessions holding it now.
- `shared` (`boolean`): One process for every session, or one session's.

Source: [ui/src/settings/headless/performance.ts:64](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L64)

### `PerfProcessNode`

Interface.

A process with the processes it started, for a tree that opens one level at a time.

```ts
interface PerfProcessNode
```

**Properties**

- `children` (`PerfProcessNode[]`): What it started, in [`processTree`](https://zidane.si/docs/reference/ui-settings-headless.md#processTree)'s order.
- `descendants` (`number`): Every process under it, at any depth.
- `inside` (`PerfTotals`): What every process under it uses, summed (its own figures left out).
- `process` (`PerfProcess`): The process.

Source: [ui/src/settings/headless/performance.ts:395](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L395)

### `PerfProcessRow`

Interface.

A process with its depth in the tree, for an indented list.

```ts
interface PerfProcessRow
```

**Properties**

- `depth` (`number`): Its depth in the tree (0: a root).
- `process` (`PerfProcess`): The process.

Source: [ui/src/settings/headless/performance.ts:344](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L344)

### `PerfProcessSession`

Interface.

The session a process runs for.

```ts
interface PerfProcessSession
```

**Properties**

- `id` (`string`): The session's key, as the app names sessions.
- `title?` (`string`): Its title; absent while it has none.

Source: [ui/src/settings/headless/performance.ts:56](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L56)

### `PerfProfile`

Interface.

A recorded profile, saved where `path` says.

```ts
interface PerfProfile
```

**Properties**

- `durationMs` (`number`): How long it recorded.
- `path` (`string`): The saved `.cpuprofile` file.
- `target` (`PerfProfileTarget`): What was profiled.
- `top` (`PerfHotFunction[]`): The functions it spent most time in, most first.

Source: [ui/src/settings/headless/performance.ts:204](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L204)

### `PerfProfileError`

Interface.

Why a profile wasn't recorded: `busy` (another profile or a debugger holds the target) or `failed`.

```ts
interface PerfProfileError
```

**Properties**

- `detail?` (`string`): The error's message, when there is one.
- `kind` (`'failed' | 'busy'`): Which of the two.

Source: [ui/src/settings/headless/performance.ts:216](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L216)

### `PerfSample`

Interface.

One sample.

```ts
interface PerfSample
```

**Properties**

- `at` (`number`): Epoch ms.
- `channels` (`PerfChannel[]`): Message channels, counted since `countersSince`.
- `cores` (`number`): Logical cores (100% CPU is one of them).
- `countersSince` (`number`): Since when the channel and frame counters count (epoch ms).
- `frames` (`PerfSlowFrame[]`): Where long frames spent their time, since `countersSince`.
- `gpu` (`PerfGpu | null`): `null`: not measured on this platform.
- `intervalMs` (`number`): Time since the previous sample, ms.
- `lag` (`PerfLag | null`): The host's event-loop delay; `null`: not measured.
- `launched` (`PerfTotals`): What sessions and terminals launched, together (origin `launched`).
- `processes` (`PerfProcess[]`): The app's processes, its daemon's and their children.
- `self` (`{ commandMs: number; cpu: number }`): The monitor's own cost: percent of one core, and the wall time of the commands it ran.
- `threads` (`PerfThread[]`): The threads the app can name.
- `totals` (`PerfTotals`): The app's own processes together (origin `app`).

Source: [ui/src/settings/headless/performance.ts:147](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L147)

### `PerfSessionGroup`

Interface.

What one session's processes use.

```ts
interface PerfSessionGroup
```

**Properties**

- `count` (`number`): How many processes it has.
- `id` (`string`): The session's key.
- `roots` (`PerfProcessNode[]`): Its processes as a tree: what the session started, each with what runs under it.
- `title?` (`string`): Its title; absent while it has none.
- `totals` (`PerfTotals`): What they use together.

Source: [ui/src/settings/headless/performance.ts:433](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L433)

### `PerfSlowFrame`

Interface.

Where long frames (over 50 ms) spent their time: one script and function, summed.

```ts
interface PerfSlowFrame
```

**Properties**

- `count` (`number`): Long frames it was part of.
- `fn` (`string`): The function.
- `maxMs` (`number`): Its longest stretch in one frame.
- `source` (`string`): The script (URL) the time was spent in.
- `totalMs` (`number`): Time it took in them, summed.
- `window` (`string`): The window it ran in.

Source: [ui/src/settings/headless/performance.ts:109](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L109)

### `PerfThread`

Interface.

A thread the app can name.

```ts
interface PerfThread
```

**Properties**

- `busy` (`number`): Share of the interval it was busy (0–1).
- `heap?` (`number`): JavaScript heap in use, bytes.
- `id` (`string`): Unique among the sample's threads.
- `kind` (`'main' | 'renderer' | 'worker' | 'renderer-worker'`): A process's main thread, a worker, a window's renderer, or a renderer's worker.
- `label` (`string`): A short name.
- `pid` (`number`): The process it runs in.

Source: [ui/src/settings/headless/performance.ts:74](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L74)

### `PerfTotals`

Interface.

CPU and memory, summed.

```ts
interface PerfTotals
```

**Properties**

- `cpu` (`number`): Percent of one core.
- `memory` (`number`): Resident, bytes.

Source: [ui/src/settings/headless/performance.ts:24](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L24)

### `PerfWatchError`

Interface.

Why a host's figures can't be watched: `unavailable` (the host can't say:
a server too old for it), `refused` (the connection's token may not:
performance needs an admin token), `failed` (anything else, `detail` says).

```ts
interface PerfWatchError
```

**Properties**

- `detail?` (`string`): The error's message, when there is one.
- `kind` (`'failed' | 'unavailable' | 'refused'`): Which of the three.

Source: [ui/src/settings/headless/performance.ts:231](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L231)

### `SettingsAction`

Interface.

A host action's row: the host owns the flow (a full modal), the layout places it.

```ts
interface SettingsAction
```

**Properties**

- `description` (`string`): The row's description.
- `icon` (`string`): The row's icon class.
- `id` (`SettingsActionId`): Which action row it fills.
- `label` (`string`): The row's label.
- `onSelect` (`() => void`): Opens the app's flow.

Source: [ui/src/settings/headless/layout.ts:47](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L47)

### `SettingsCatalogEntries`

Interface.

One catalog's entries.

```ts
interface SettingsCatalogEntries
```

**Properties**

- `extensions` (`HostCatalogExtension`): An extension, with why it failed to load.
- `mcps` (`HostCatalogMcp`): An MCP server, its secrets redacted.
- `plugins` (`HostCatalogPlugin`): A plugin, with what it contributes.
- `skills` (`HostCatalogSkill`): A skill, with where it comes from.

Source: [ui/src/settings/headless/sections-host.ts:289](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L289)

### `SettingsChoice`

Interface.

A choice row of the catalog: a setting with a few values, cycled.

```ts
interface SettingsChoice<K extends keyof Settings = keyof Settings>
```

**Type parameters**

- `K` (`extends keyof Settings`, default `keyof Settings`)

**Properties**

- `description` (`string`): The row's description.
- `key` (`K`): The setting it sets.
- `label` (`string`): The row's label.
- `options` (`readonly { label: string; value: Settings[K] }[]`): The values in cycle order, each with its label.

Source: [ui/src/settings/headless/catalog.ts:377](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/catalog.ts#L377)

### `SettingsClaudeImportCopy`

Interface.

What a copy did: by name.

```ts
interface SettingsClaudeImportCopy
```

**Properties**

- `copied` (`string[]`): Copied.
- `failed` (`{ error: string; name: string }[]`): Failed, with why.
- `skipped` (`string[]`): Skipped: zidane already has one with the same name.

Source: [ui/src/settings/headless/claude-import.ts:30](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/claude-import.ts#L30)

### `SettingsClaudeImportDetect`

Interface.

What the host found in `~/.claude`.

```ts
interface SettingsClaudeImportDetect
```

**Properties**

- `available` (`boolean`): There is a Claude Code setup to import.
- `counts` (`{ all: number; project: number }`): The transcripts found: for the folder, and in every project.

Source: [ui/src/settings/headless/claude-import.ts:8](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/claude-import.ts#L8)

### `SettingsClaudeImportHost`

Interface.

Importing a Claude Code setup on the host.

```ts
interface SettingsClaudeImportHost
```

**Properties**

- `detect` (`(cwd: string) => Promise<SettingsClaudeImportDetect>`): What `~/.claude` holds, counted for `cwd` (`''`: no folder).
- `run` (`(cwd: string, selection: SettingsClaudeImportSelection) => Promise<SettingsClaudeImportSummary>`): Imports the selection. Idempotent: what a previous run brought over is skipped.

Source: [ui/src/settings/headless/claude-import.ts:56](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/claude-import.ts#L56)

### `SettingsClaudeImportSelection`

Interface.

What to import.

```ts
interface SettingsClaudeImportSelection
```

**Properties**

- `allProjects` (`boolean`): Conversations of every project, not just the folder's.
- `commands` (`boolean`): Commands and subagents.
- `mcps` (`boolean`): MCP servers.
- `sessions` (`boolean`): Conversations.
- `skills` (`boolean`): Skills.

Source: [ui/src/settings/headless/claude-import.ts:16](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/claude-import.ts#L16)

### `SettingsClaudeImportSummary`

Interface.

What an import did.

```ts
interface SettingsClaudeImportSummary
```

**Properties**

- `agents?` (`SettingsClaudeImportCopy`): The subagents.
- `commands?` (`SettingsClaudeImportCopy`): The commands.
- `mcps?` (`SettingsClaudeImportCopy`): The MCP servers.
- `notes` (`string[]`): What is deliberately not imported, and why.
- `sessions?` (`{ empty: number; failed: { error: string; path: string }[]; imported: number; skipped: number }`): The conversations.
- `skills?` (`SettingsClaudeImportCopy`): The skills.

Source: [ui/src/settings/headless/claude-import.ts:40](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/claude-import.ts#L40)

### `SettingsCredential`

Interface.

One credential source of a provider. Never a secret.

```ts
interface SettingsCredential
```

**Properties**

- `active?` (`boolean`): The stored credential every reader resolves (`env` never is).
- `detail` (`string`): What to show: the credentials file, an OAuth account's expiry, an env var name.
- `email?` (`string`): An OAuth account's email, when the host knows it: what tells two accounts apart.
- `id?` (`string`): Its stable id (it stays put when another account is promoted): what a failed sign-in names. Absent: not stored, or stored before ids.
- `key?` (`string`): Its key in the credentials store: what `remove`, `rename` and `setPreferred` name. Absent: not stored.
- `label?` (`string`): An OAuth account's name.
- `source` (`'apikey' | 'oauth' | 'env'`): Where it comes from: a stored API key, an OAuth account, or an environment variable (observed, never stored).

Source: [ui/src/settings/headless/providers.ts:16](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/providers.ts#L16)

### `SettingsDecisionModel`

Interface.

A model a provider's decisions endpoint serves, with whether the host's credentials can use it.

```ts
interface SettingsDecisionModel
```

**Properties**

- `available` (`boolean`): The credentials can send it decisions.
- `modelId` (`string`): The model's id.
- `providerKey` (`string`): The provider's key.
- `providerLabel` (`string`): The provider's name.
- `reason?` (`string`): Why not, when not.

Source: [ui/src/settings/headless/models.ts:28](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/models.ts#L28)

### `SettingsEnvironmentsHost`

Interface.

Where new sessions run: the environment kinds and their settings.

```ts
interface SettingsEnvironmentsHost
```

**Properties**

- `list` (`(cwd: string) => Promise<readonly EnvironmentDescriptor[]>`): Every kind, described for a new session in `cwd` (`''`: none).
- `update?` (`(change: EnvironmentSettingsChange) => Promise<void>`): Applies one edit (on, default, an option, a secret). Absent: read-only.
- `verify?` (`(kind: string) => Promise<EnvironmentVerifyResult>`): Tests a kind's connection. Absent: no test button.

Source: [ui/src/settings/headless/sections-host.ts:268](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L268)

### `SettingsError`

Interface.

A settings read or write that did not happen, worded by the labels (`settingsError`).

```ts
interface SettingsError
```

**Properties**

- `detail?` (`string`): What the host said, when it said something.
- `found?` (`readonly string[]`): The extensions a source holds, when an install found none of the name it needed (`name-mismatch`).
- `kind` (`SettingsErrorKind`): Why.

Source: [ui/src/settings/headless/host.ts:40](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/host.ts#L40)

### `SettingsExtension`

Interface.

An extension the host discovered.

```ts
interface SettingsExtension
```

**Properties**

- `capabilities?` (`readonly string[]`): What it contributes: `tools`, `skills`, …
- `description?` (`string`): What it does.
- `dir?` (`string`): Its folder (disk extensions only).
- `displayName?` (`string`): Its display name. Absent: `name`.
- `enabled` (`boolean`): It contributes now.
- `error?` (`string`): Why it did not load.
- `icon?` (`{ gui?: string; tui?: string }`): Its own icon, the first thing `extensionMark` reads.
- `name` (`string`): Its name (the allowlist key).
- `origin?` (`ExtensionInstallOrigin`): The source it was installed from, which Update follows. Absent: not installed from a source.
- `source` (`'inline' | 'user' | 'project' | 'builtin'`): Where it was found.
- `version?` (`string`): Its manifest version.

Source: [ui/src/settings/headless/sections-host.ts:98](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L98)

### `SettingsExtensionAction`

Interface.

An action an extension declares (`registerConfigItem` type `'action'`); it runs on the host.

```ts
interface SettingsExtensionAction
```

**Properties**

- `category` (`string`): The category it sits in.
- `categoryLabel` (`string`): The category's name.
- `description?` (`string`): What it does.
- `extension` (`string`): The extension.
- `hasStatus` (`boolean`): It declares a passive `status()` probe.
- `key` (`string`): The action's key.
- `label` (`string`): Its name.

Source: [ui/src/settings/headless/sections-host.ts:176](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L176)

### `SettingsExtensionActionResult`

Interface.

What a run did: its message, and the config patch it set (already validated by the host).

```ts
interface SettingsExtensionActionResult
```

**Properties**

- `config?` (`Record<string, string | number | boolean>`): The accepted config patch, to store under `Settings.extensionConfig[extension]`.
- `message` (`string`): What to show.

Source: [ui/src/settings/headless/sections-host.ts:202](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L202)

### `SettingsExtensionActionStatus`

Interface.

An action's passive probe.

```ts
interface SettingsExtensionActionStatus
```

**Properties**

- `message` (`string`): What it says.
- `state` (`'error' | 'off' | 'ok'`): How it is.

Source: [ui/src/settings/headless/sections-host.ts:194](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L194)

### `SettingsExtensionCreate`

Interface.

An extension to scaffold.

```ts
interface SettingsExtensionCreate
```

**Properties**

- `cwd?` (`string`): The project folder, for the project scope.
- `name` (`string`): Its name.
- `scope` (`SettingsInstallScope`): Where it goes.

Source: [ui/src/settings/headless/sections-host.ts:210](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L210)

### `SettingsExtensionCreated`

Interface.

A scaffolded extension.

```ts
interface SettingsExtensionCreated
```

**Properties**

- `dir` (`string`): Its folder.
- `name` (`string`): Its name.
- `needsTrust?` (`boolean`): A project extension stays unloaded until the project is trusted.

Source: [ui/src/settings/headless/sections-host.ts:220](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L220)

### `SettingsExtensionInstall`

Interface.

An extension to install.

```ts
interface SettingsExtensionInstall
```

**Properties**

- `extension?` (`string`): Which extension, for a source with several.
- `scope` (`SettingsInstallScope`): Where it goes.
- `source` (`string`): A GitHub / npm spec or a local path.

Source: [ui/src/settings/headless/sections-host.ts:124](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L124)

### `SettingsExtensionsHost`

Interface.

Extensions on the host's disk, for one folder.

```ts
interface SettingsExtensionsHost
```

**Properties**

- `actions?` (`(cwd: string) => SettingsResource<readonly SettingsExtensionAction[]>`): The action rows the enabled extensions declare for `cwd`. Absent: none listed.
- `actionStatuses?` (`(cwd: string) => Promise<Record<string, SettingsExtensionActionStatus>>`): The actions' passive status probes, keyed `extension:key`. Absent: rows without a status line.
- `browse?` (`(input: string) => Promise<ExtensionSourceListing>`): Lists what a source holds (a GitHub repo, an npm package), read from the manifests: nothing runs.
  Never rejects for an unreadable source: the listing carries `error`. Absent: no source browser.
- `changeOrigin?` (`(cwd: string, extension: SettingsExtension, source: string, onProgress?: (line: string) => void) => Promise<string>`): Installs `extension` again from `source`, which must hold an extension of the same name; later
  updates follow it. Its folder changes only on success. Resolves with what the installer said.
  Absent: no Change origin.
- `configSchema?` (`(cwd: string) => SettingsResource<WireExtensionConfigSchema>`): The options the enabled extensions declare for `cwd` (values live on `Settings.extensionConfig`). Absent: none listed.
- `create?` (`(request: SettingsExtensionCreate) => Promise<SettingsExtensionCreated>`): Scaffolds a new extension. Absent: no create flow.
- `install?` (`(cwd: string, request: SettingsExtensionInstall, onProgress?: (line: string) => void) => Promise<{ name: string }>`): Installs one; `onProgress` gets the installer's lines. Resolves with its name. Absent: no install.
- `list` (`(cwd: string) => Promise<readonly SettingsExtension[]>`): The extensions for `cwd`. Read again after each toggle (their state follows the allowlist).
- `remove?` (`(cwd: string, extension: SettingsExtension) => Promise<void>`): Deletes its folder. Absent: no remove.
- `runAction?` (`(cwd: string, extension: string, key: string) => Promise<SettingsExtensionActionResult>`): Runs an action. Absent: no Run buttons.
- `update?` (`(cwd: string, extension: SettingsExtension) => Promise<string>`): Runs its installer again. Resolves with what it said. Absent: no update.

Source: [ui/src/settings/headless/sections-host.ts:134](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L134)

### `SettingsFile`

Interface.

A file the host reads and writes with a guard on its modification time.

```ts
interface SettingsFile
```

**Properties**

- `contents` (`string`): Its text.
- `mtimeMs` (`number`): Its modification time when read.
- `path` (`string`): Its path on the host.

Source: [ui/src/settings/headless/sections-host.ts:49](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L49)

### `SettingsHost`

Interface.

The settings host.

```ts
interface SettingsHost
```

**Properties**

- `claudeImport?` (`SettingsClaudeImportHost`): Importing the Claude Code setup of the host's machine. Absent: no import.
- `document` (`Readable<SettingsDocument>`): The settings document: `loading` until first read.
- `environments?` (`SettingsEnvironmentsHost`): Where new sessions run (Settings › Environments).
- `extensions?` (`SettingsExtensionsHost`): Extensions on disk for a folder (Settings › Extensions).
- `hostCatalog?` (`SettingsHostCatalog`): The host's own catalogs with its enabled state (a server's Skills, MCP servers, Extensions, Plugins).
- `instructions?` (`SettingsInstructionsHost`): What a session's agent is loaded with (Settings › Instructions).
- `logs?` (`SettingsLogsHost`): The host's log funnel (Settings › Logs).
- `mcp?` (`SettingsMcpHost`): A folder's MCP servers, their sign-ins and tests (Settings › MCP servers). Absent: no servers to show.
- `models?` (`SettingsModelsHost`): The model rows' decision catalog, tests and last used model (Settings › Agent). Absent: rows without them.
- `paths?` (`SettingsPaths`): Opening the host's paths in other apps (reveal, open in the editor).
- `performance?` (`SettingsPerformanceHost`): What the app's processes and threads use, live (Settings › Performance). Absent: an empty page.
- `plugins?` (`SettingsPluginsHost`): Agent Plugins for a folder (Settings › Plugins).
- `providers?` (`SettingsProvidersHost`): The providers the host's agents sign in to (Settings › Accounts). Absent: no providers to show.
- `skills?` (`SettingsSkillsHost`): Skills on disk for a folder (Settings › Skills). Absent: no skills section content.
- `writable?` (`Readable<boolean>`): Whether `update` may run now (a server token without the admin scope may not). Absent: whenever `update` is there.
- `refresh` (`() => Promise<void>`): Reads the settings again and tells subscribers. Never rejects: a failure lands in `document` (when nothing was read yet).
- `update?` (`(patch: Partial<Settings>) => Promise<void>`): Applies a patch: `document` shows it at once, then what the host holds
  after the write. Rejects with a [`SettingsError`](https://zidane.si/docs/reference/ui-settings-headless.md#SettingsError) when the write is
  refused, and `document` goes back to what the host holds. Absent: read-only.

Source: [ui/src/settings/headless/host.ts:58](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/host.ts#L58)

### `SettingsHostCatalog`

Interface.

A host's catalogs as the host itself reports them (a zidane-server's
`catalog.*`), each entry with the host's enabled state; the enabled lists
are its settings (`update`). Its MCP servers are the `mcp` group's.

```ts
interface SettingsHostCatalog
```

**Properties**

- `browse?` (`(input: string) => Promise<ExtensionSourceListing>`): Lists the extensions a source holds, read by the host from their manifests (as
  `SettingsExtensionsHost.browse`). Absent: the Install form instead of the source browser.
- `changeOrigin?` (`(name: string, source: string) => Promise<string>`): Installs a user-scope extension again from `source`, which must hold one of the same name (else a
  `SettingsError` with the names it holds in `found`); its updates follow it. Resolves with what the
  host said. Absent: no Change origin.
- `install?` (`(kind: SettingsCatalogInstallKind, spec: string, options?: { extension?: string }) => Promise<void>`): Installs a skill or an extension from a GitHub / npm spec into the host user's scope; `extension` picks one of a source's.
- `installs?` (`() => Promise<boolean>`): Whether the host takes installs and removals from this connection. Absent: never.
- `list` (`<K extends SettingsCatalogKind>(kind: K, cwd?: string) => Promise<SettingsCatalogEntries[K][] | null>`): One catalog, with `cwd`'s project scope (none: the host user's). `null`: the host can't list it.
- `onChanged?` (`(listener: (kind: SettingsCatalogKind) => void) => () => void`): Called when a catalog changed there (an install from any client); returns its unsubscribe.
- `remove?` (`(kind: SettingsCatalogInstallKind, name: string) => Promise<void>`): Removes a user-scope skill or extension.
- `update?` (`(kind: SettingsCatalogInstallKind, name: string) => Promise<void>`): Updates a user-scope extension installed from a source.

Source: [ui/src/settings/headless/sections-host.ts:308](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L308)

### `SettingsInstructionsHost`

Interface.

What a session's agent is loaded with.

```ts
interface SettingsInstructionsHost
```

**Properties**

- `createSystemOverride?` (`(sessionId: string) => Promise<void>`): Seeds a user `SYSTEM.md` from the session's prompt. Absent: no "Create SYSTEM.md".
- `openFile?` (`(sessionId: string, path: string) => Promise<void>`): Opens an instruction file of the session in an editor. Absent: no open button.
- `segments` (`(sessionId: string) => Promise<ContextSegmentsReport | null>`): Every chunk of the session's system prompt with provenance (`null`: no live agent).

Source: [ui/src/settings/headless/sections-host.ts:258](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L258)

### `SettingsLoad`

Interface.

What a [`SettingsResource`](https://zidane.si/docs/reference/ui-settings-headless.md#SettingsResource) holds now.

```ts
interface SettingsLoad<T>
```

**Type parameters**

- `T`

**Properties**

- `data` (`T | undefined`): The last value read; `undefined` until the first read lands.
- `error` (`SettingsError | null`): The last read failed (the last good `data` stays).
- `loading` (`boolean`): Nothing read yet and a read runs.

Source: [ui/src/settings/headless/sections-host.ts:26](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L26)

### `SettingsLogsHost`

Interface.

The host's log funnel.

```ts
interface SettingsLogsHost
```

**Properties**

- `follow` (`(onRecord: (record: LogRecord) => void) => () => void`): Gets each new record; returns its unsubscribe.
- `list` (`() => Promise<readonly LogRecord[]>`): The records held now (a ring buffer).

Source: [ui/src/settings/headless/sections-host.ts:278](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L278)

### `SettingsMcpHost`

Interface.

The MCP servers of a folder (Settings › MCP servers). `cwd` is the folder
(`''`: the user's servers only). Turning a server or one of its tools on
and off is the settings document's (`enabledMcps`, `disabledMcpTools`).

```ts
interface SettingsMcpHost
```

**Properties**

- `projectScope?` (`boolean`): `add` can write a project's config when a folder is set. Absent: the user's config only.
- `add?` (`(cwd: string, server: McpFormResult) => Promise<void>`): Adds or replaces a server (`validateMcpForm`'s result). Read `servers` again to see it. Absent: no Add server.
- `instances?` (`(cwd: string) => SettingsResource<readonly SettingsMcpInstance[]>`): The running processes of the folder's servers (`''`: every folder's). Absent: no process badge, no Restart.
- `remove?` (`(cwd: string, name: string) => Promise<void>`): Removes a server from the file that declares it. Read `servers` again to see it. Absent: no Remove.
- `restart?` (`(cwd: string, name: string) => Promise<void>`): Ends a server's processes now; its next call starts a fresh one. Read `instances` again to see it. Absent: no Restart.
- `servers` (`(cwd: string) => SettingsResource<readonly SettingsMcpServer[]>`): The servers.
- `signIn?` (`(cwd: string, name: string) => SignInFlow`): Starts an `http` server's browser sign-in. Absent: no Sign in.
- `signOut?` (`(cwd: string, name: string) => Promise<void>`): Forgets a server's sign-in. Absent: no Sign out.
- `test?` (`(cwd: string, name: string) => Promise<void>`): Connects, lists the tools and records how it went in `servers`. Absent: no Test.

Source: [ui/src/settings/headless/mcp.ts:120](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L120)

### `SettingsMcpInstance`

Interface.

A running process of a `stdio` server, as the host's pool holds it.

```ts
interface SettingsMcpInstance
```

**Properties**

- `cwd` (`string`): Its folder (`''`: the host's own).
- `name` (`string`): The server's name.
- `pid?` (`number`): Its process id, while it runs.
- `retired` (`boolean`): Its config, switch or sign-in changed: it closes once its last session lets go.
- `sessions` (`number`): How many sessions hold it now (0 while it idles before closing).
- `shared` (`boolean`): One process for every session (`true`), or one session's.

Source: [ui/src/settings/headless/mcp.ts:100](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L100)

### `SettingsMcpRunning`

Interface.

What a server's process badge says: one shared process and how many sessions hold it, or one per session.

```ts
interface SettingsMcpRunning
```

**Properties**

- `sessions` (`number`): Sessions holding the shared process.
- `shared` (`boolean`): One process for every session.

Source: [ui/src/settings/headless/mcp.ts:181](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L181)

### `SettingsMcpServer`

Interface.

An MCP server a folder's agents can use. Secret values never come back.

```ts
interface SettingsMcpServer
```

**Properties**

- `authState` (`SettingsMcpAuthState`): Its sign-in state.
- `command?` (`string`): The command line of a `stdio` server.
- `lastError?` (`string`): Why its last sign-in or connection failed.
- `name` (`string`): Its name (the `enabledMcps` key).
- `path?` (`string`): The config file that declares it.
- `removable?` (`boolean`): `remove` may edit that file.
- `scope?` (`'host' | 'context'`): Where a `stdio` server runs: `host` (shareable), or `context`, started in each session's execution
  context and never shared. Absent: the host doesn't say, so no Shared switch.
- `shared?` (`boolean`): Its config's `shared` (absent: `true`). The `mcpSharing` setting wins over it.
- `test?` (`SettingsMcpTest`): The last test, when one ran.
- `toolError?` (`string`): Why listing its tools failed.
- `tools?` (`readonly SettingsMcpTool[]`): The tools it listed.
- `toolsUpdatedAt?` (`number`): When the tools were listed, epoch ms.
- `transport` (`'stdio' | 'http'`): How it is reached.
- `url?` (`string`): The address of an `http` server.

Source: [ui/src/settings/headless/mcp.ts:43](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L43)

### `SettingsMcpTest`

Interface.

How a server answered its last test: `ok` connected and listed its tools;
`needs-auth` refused with no key of its own (a sign-in fixes it);
`token-rejected` refused the key it sends; `error` anything else.

```ts
interface SettingsMcpTest
```

**Properties**

- `at` (`number`): When, epoch ms.
- `kind` (`'error' | 'needs-auth' | 'ok' | 'token-rejected'`): How it answered.
- `message?` (`string`): What to tell the user (not `ok`).
- `tools?` (`number`): How many tools it listed (`ok`).

Source: [ui/src/settings/headless/mcp.ts:28](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L28)

### `SettingsMcpTool`

Interface.

A tool an MCP server lists.

```ts
interface SettingsMcpTool
```

**Properties**

- `description?` (`string`): What it does.
- `name` (`string`): Its name.

Source: [ui/src/settings/headless/mcp.ts:16](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L16)

### `SettingsModelsHost`

Interface.

The model rows' host calls. Each one left out hides what needs it.

```ts
interface SettingsModelsHost
```

**Properties**

- `decisionModels?` (`(cwd: string) => SettingsResource<readonly SettingsDecisionModel[]>`): The decision models for a folder (`''`: none). Absent: no decision model row, Model decision stays offered.
- `lastUsed?` (`() => Promise<ModelPickRef | null>`): The model new sessions start on with no default set (the last one picked), `null` when none.
- `test?` (`(cwd: string, model: string) => Promise<SettingsModelTest>`): Sends a chat model (`"providerKey[@account]/modelId"`) one tiny prompt. Absent: no Test buttons.
- `testDecision?` (`(cwd: string, model?: string) => Promise<SettingsModelTest>`): Sends one tiny decision (`model` absent: the one agents would get). Absent: the decision row has no Test.

Source: [ui/src/settings/headless/models.ts:42](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/models.ts#L42)

### `SettingsModelTest`

Interface.

How a model test went: one tiny request with the host's credentials.

```ts
interface SettingsModelTest
```

**Properties**

- `durationMs` (`number`): How long it took.
- `message?` (`string`): What the provider said.
- `model?` (`string`): The model that answered (its id).
- `ok` (`boolean`): The model answered.
- `provider?` (`string`): The provider that answered (its key).
- `reason?` (`string`): Why it failed (`unavailable`, `auth`, `timeout`, …).

Source: [ui/src/settings/headless/models.ts:12](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/models.ts#L12)

### `SettingsPanelPage`

Interface.

A page one panel component draws; `search` stands in for its rows, which it loads lazily.

```ts
interface SettingsPanelPage extends PageBase
```

**Properties**

- `description` (`string`, from `PageBase`): Under the title in the header.
- `icon` (`string`, from `PageBase`)
- `id` (`SettingsPanelId`): The page's id.
- `keys?` (`readonly keyof Settings[]`): Table settings the panel draws among its own rows: searched like any table row.
- `label` (`string`, from `PageBase`)
- `localOnly?` (`true`, from `PageBase`): Composes this computer's files: not offered while editing a server.
- `parent?` (`SettingsTopId`, from `PageBase`): A sub-page: listed under this entry.
- `search` (`readonly SettingsSearchEntry[]`): What search finds on it: the page itself first, then its rows.
- `serverDescription?` (`string`, from `PageBase`): Under the title on a server's settings, where `description` would name this computer. `{host}`: the server's name.

Source: [ui/src/settings/headless/layout.ts:103](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L103)

### `SettingsPaths`

Interface.

Opening a path of the host in another app.

```ts
interface SettingsPaths
```

**Properties**

- `open?` (`(path: string) => Promise<void>`): Opens the file in the user's editor. Absent: no open buttons.
- `reveal?` (`(path: string) => Promise<void>`): Shows the file or folder in the system file manager. Absent: no reveal buttons.

Source: [ui/src/settings/headless/sections-host.ts:335](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L335)

### `SettingsPerformanceHost`

Interface.

The host's performance figures (Settings › Performance, the overlay).

```ts
interface SettingsPerformanceHost
```

**Properties**

- `exportReport?` (`() => Promise<string>`): Writes a report and resolves where. Absent: no export button.
- `history` (`() => Promise<readonly PerfSample[]>`): The samples held, oldest first.
- `profile?` (`(target: PerfProfileTarget, seconds: number) => Promise<PerfProfileOutcome>`): Records a CPU profile. Absent: no profile controls.
- `resetCounters?` (`() => Promise<void>`): Zeroes the channel and frame counters. Absent: the host keeps no such counters (a server): no reset button, no Slow frames or IPC section.
- `threads?` (`(pid: number) => Promise<readonly PerfOsThread[]>`): A process's OS threads, busiest first. Absent: rows don't expand.
- `watch` (`(onSample: (sample: PerfSample) => void, onError?: (error: PerfWatchError) => void) => () => void`): Starts sampling (the host samples only while watched) and gets each
  sample; `onError` hears why the host can't be watched (at most once per
  watch, a sample after it means it recovered). Returns the unsubscribe.

Source: [ui/src/settings/headless/performance.ts:239](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L239)

### `SettingsPlugin`

Interface.

An Agent Plugin the host discovered.

```ts
interface SettingsPlugin
```

**Properties**

- `description` (`string | null`): What it does.
- `loadedBy?` (`string`): The extension that loads it (its switch governs the plugin). Absent: found on disk.
- `mcpCount` (`number`): The MCP servers it adds.
- `name` (`string`): Its name (the allowlist key).
- `ok` (`boolean`): `false`: its manifest was rejected, it adds nothing.
- `path` (`string`): Its folder.
- `skillCount` (`number`): The skills it adds.
- `source` (`'user' | 'project'`): Whose config it comes from.
- `version` (`string | null`): Its manifest version.

Source: [ui/src/settings/headless/sections-host.ts:230](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L230)

### `SettingsPluginsHost`

Interface.

Agent Plugins on the host's disk, for one folder.

```ts
interface SettingsPluginsHost
```

**Properties**

- `catalog` (`(cwd: string) => SettingsResource<readonly SettingsPlugin[]>`): The plugins for `cwd`, unfiltered by the allowlist.

Source: [ui/src/settings/headless/sections-host.ts:252](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L252)

### `SettingsProvider`

Interface.

A provider and its sign-in state, as the host reports it. Never a secret.

```ts
interface SettingsProvider
```

**Properties**

- `apiKeyPlaceholder?` (`string`): Placeholder of its API key field.
- `available` (`boolean`): Some credential source is present.
- `configuredFields?` (`Readonly<Record<string, string>>`): The non-secret field values stored now.
- `customFields?` (`readonly SettingsProviderField[]`): Configuration fields it takes instead of an API key.
- `description?` (`string`): One line on what it serves and how it signs in.
- `extension?` (`boolean`): Added by an extension of the folder, not built in.
- `hasApiKey` (`boolean`): An API key is stored.
- `hasOAuth` (`boolean`): An OAuth account is stored.
- `key` (`string`): Provider key.
- `label` (`string`): Display name.
- `methods` (`readonly SettingsCredential[]`): Its credential sources, stored ones first.
- `oauth` (`boolean`): It can sign in with a browser now (with `SettingsProvidersHost.signIn`).
- `signInLabel?` (`string`): The account its browser sign-in uses, for "Sign in with …". Default: `label`.

Source: [ui/src/settings/headless/providers.ts:50](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/providers.ts#L50)

### `SettingsProviderField`

Interface.

A configuration field a provider asks for instead of an API key (an endpoint, a project id).

```ts
interface SettingsProviderField
```

**Properties**

- `hint?` (`string`): One line under it.
- `key` (`string`): The field's key in `configure`.
- `label` (`string`): Its caption.
- `placeholder?` (`string`): Its placeholder.
- `required?` (`boolean`): Saving needs it.
- `secret?` (`boolean`): Typed masked; a blank value keeps the stored one.

Source: [ui/src/settings/headless/providers.ts:34](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/providers.ts#L34)

### `SettingsProvidersHost`

Interface.

The providers a host's agents use (Settings › Accounts). `cwd` is the
folder whose extension providers count (`''`: built-ins only).

```ts
interface SettingsProvidersHost
```

**Properties**

- `clear?` (`(cwd: string, provider: string) => Promise<void>`): Removes every stored credential of a provider. Absent: no Clear.
- `configure?` (`(cwd: string, provider: string, fields: Readonly<Record<string, string>>) => Promise<void>`): Stores a provider's configuration fields. Absent: no configuration form.
- `list` (`(cwd: string) => SettingsResource<readonly SettingsProvider[]>`): The providers and their sign-in state.
- `remove?` (`(cwd: string, provider: string, credential: string) => Promise<void>`): Removes one stored credential (`SettingsCredential.key`). Absent: no Remove.
- `rename?` (`(cwd: string, provider: string, credential: string, label: string) => Promise<void>`): Renames a stored OAuth account. Absent: no Rename.
- `setApiKey?` (`(cwd: string, provider: string, key: string) => Promise<void>`): Stores an API key. Absent: no key form.
- `setPreferred?` (`(cwd: string, provider: string, target: SettingsPreferredCredential) => Promise<void>`): Makes a stored credential the one every reader resolves. Absent: no Use.
- `signIn?` (`(provider: string, options?: SettingsSignInOptions) => SignInFlow`): Starts a browser sign-in; once it is done, `list` shows the account. Absent: keys only.

Source: [ui/src/settings/headless/providers.ts:94](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/providers.ts#L94)

### `SettingsResource`

Interface.

A value the host reads and keeps current: `get` returns the same object until it changes.

```ts
interface SettingsResource<T>
```

**Type parameters**

- `T`

**Properties**

- `get` (`() => SettingsLoad<T>`): What is held now.
- `refresh` (`() => Promise<void>`): Reads again. Never rejects: a failure lands in `error`.
- `subscribe` (`(listener: () => void) => () => void`): Called after each change; returns its unsubscribe.

Source: [ui/src/settings/headless/sections-host.ts:36](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L36)

### `SettingsResourceOptions`

Interface.

Options for [`createSettingsResource`](https://zidane.si/docs/reference/ui-settings-headless.md#createSettingsResource).

```ts
interface SettingsResourceOptions<T>
```

**Type parameters**

- `T`

**Properties**

- `initial?` (`T`): A value to show before the first read lands (no loading state).

Source: [ui/src/settings/headless/resource.ts:11](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/resource.ts#L11)

### `SettingsSearchEntry`

Interface.

One search entry inside a section.

```ts
interface SettingsSearchEntry
```

**Properties**

- `description` (`string`): The result's description.
- `key?` (`string`): The row's `data-setting-focus` id the result lands on (and searchable).
- `keywords?` (`readonly string[]`): More words it matches.
- `label` (`string`): The result's label.

Source: [ui/src/settings/headless/registry.ts:55](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/registry.ts#L55)

### `SettingsSearchHit`

Interface.

One search result: an entry and the section it lands on.

```ts
interface SettingsSearchHit extends SettingsSearchEntry
```

**Properties**

- `description` (`string`, from `SettingsSearchEntry`): The result's description.
- `key?` (`string`, from `SettingsSearchEntry`): The row's `data-setting-focus` id the result lands on (and searchable).
- `keywords?` (`readonly string[]`, from `SettingsSearchEntry`): More words it matches.
- `label` (`string`, from `SettingsSearchEntry`): The result's label.
- `section` (`string`): The section's id.

Source: [ui/src/settings/headless/search.ts:18](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/search.ts#L18)

### `SettingsSection`

Interface.

The settings section registry: the shell (`SettingsShell`) renders the
sections an app hands it (the kit's own, the per-device preference
sections, an app's desktop-only ones), in order. React-free: `render`
returns what the styled shell renders (a ReactNode there), typed
`unknown` here.

A section's body reads its context through hooks, never through
`render` arguments: `useSettingsSection()` (zidane-ui/settings) gives
whether it is the open one, the row a deep link or search landed on, and
the header slot its actions portal into.

```ts
interface SettingsSection
```

**Properties**

- `description?` (`string`): Under the title in the header.
- `group?` (`string`): The id of the top-level section this one is listed under (indented
  beneath it in the nav, e.g. `'interface'` for Appearance). Absent: a
  top-level entry.
- `icon?` (`string`): An icon class (UnoCSS icon, e.g. `i-ph-paint-brush`) the nav draws.
- `id` (`string`): Stable id: deep links (`initialSection`, `select(id, focus)`) and search results name it.
- `keepMounted?` (`boolean`): Keep the body mounted (hidden) after its first visit, so its async state survives switching away.
- `keywords?` (`string[]`): Extra words the settings search matches on the section itself.
- `lead?` (`unknown`): Drawn before the title and description in the header (an extension's mark). A ReactNode in the styled shell.
- `mark?` (`{ brand: string }`): A logo the nav draws in the icon's box, before `icon` and `monogram` (an extension's native
  brand, a Simple Icons slug). `monogram` names it and stands in when the kit has no such logo.
- `monogram?` (`string`): Without an `icon`: the word whose first letter the nav draws as a letter
  badge in the icon's place (an extension's display name). Absent too: no glyph.
- `render` (`() => unknown`): The section body.
- `search?` (`readonly SettingsSearchEntry[]`): Search entries for the rows inside the section: each lands on the
  section and, with a `key`, on the row carrying `data-setting-focus={key}`.
  Absent: the section is found by its title, description and keywords.
- `title` (`string`): The nav entry and the header title, already worded by the registrant.

Source: [ui/src/settings/headless/registry.ts:13](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/registry.ts#L13)

### `SettingsSectionsPage`

Interface.

A page of sections of rows.

```ts
interface SettingsSectionsPage extends PageBase
```

**Properties**

- `description` (`string`, from `PageBase`): Under the title in the header.
- `icon` (`string`, from `PageBase`)
- `id` (`SettingsSectionsPageId`): The page's id.
- `label` (`string`, from `PageBase`)
- `localOnly?` (`true`, from `PageBase`): Composes this computer's files: not offered while editing a server.
- `parent?` (`SettingsTopId`, from `PageBase`): A sub-page: listed under this entry.
- `sections` (`readonly SettingsPageSection[]`): Its sections, in order.
- `serverDescription?` (`string`, from `PageBase`): Under the title on a server's settings, where `description` would name this computer. `{host}`: the server's name.

Source: [ui/src/settings/headless/layout.ts:95](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L95)

### `SettingsSignInOptions`

Interface.

What a browser sign-in is for.

```ts
interface SettingsSignInOptions
```

**Properties**

- `label?` (`string`): The new account's name (a second account of the provider).
- `replaceKey?` (`string`): The stored account it signs in again.

Source: [ui/src/settings/headless/providers.ts:80](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/providers.ts#L80)

### `SettingsSkillInstall`

Interface.

Skills to install from one source.

```ts
interface SettingsSkillInstall
```

**Properties**

- `scope` (`SettingsInstallScope`): Where they go.
- `skills` (`readonly string[]`): The picked skills' paths in the source.
- `source` (`string`): The source spec (`owner/repo`, a URL, a path) the browser listed them from.

Source: [ui/src/settings/headless/sections-host.ts:65](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L65)

### `SettingsSkillsHost`

Interface.

Skills on the host's disk, for one folder (its project scope plus the user's).

```ts
interface SettingsSkillsHost
```

**Properties**

- `browse?` (`(input: string) => Promise<SkillSourceListing>`): Lists what a source holds (a GitHub repo, a skills.sh URL). Absent: no source browser.
- `catalog` (`(cwd: string) => SettingsResource<readonly SkillConfig[]>`): The skills found for `cwd`, unfiltered by the allowlist.
- `file?` (`(cwd: string, name: string) => SettingsResource<SettingsFile | null>`): A skill's `SKILL.md` (`null`: it has no file). Absent: the skill shows its instructions, read-only.
- `install?` (`(cwd: string, request: SettingsSkillInstall, onProgress?: (line: string) => void) => Promise<'installed' | 'unmatched'>`): Installs picked skills; `onProgress` gets the installer's lines. Resolves `unmatched` when the
  installer could not find the picked skills in the source. Absent: no install.
- `remove?` (`(cwd: string, skill: SkillConfig) => Promise<void>`): Deletes a skill's folder from disk. Absent: no delete.
- `write?` (`(cwd: string, name: string, contents: string, expectedMtimeMs: number) => Promise<SettingsFileWrite>`): Writes a skill's `SKILL.md` if it is still at `expectedMtimeMs`. Absent: read-only.

Source: [ui/src/settings/headless/sections-host.ts:75](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L75)

### `SettingsToggle`

Interface.

A toggle row of the catalog.

```ts
interface SettingsToggle
```

**Properties**

- `description` (`string`): The row's description.
- `key` (`BooleanSettingKey`): The setting it flips.
- `killSwitchEnv?` (`string`): The feature gate's kill-switch env var; the row is inert while it is engaged. From canonical.
- `label` (`string`): The row's label.
- `requires?` (`BooleanSettingKey`): Another boolean setting this one needs; the row is greyed while it is off. From canonical, plus `GUI_GREYED_BY`.
- `serverDescription?` (`string`): The description on a server's settings, where `description` would name this computer. `{host}`: the server's name.

Source: [ui/src/settings/headless/catalog.ts:24](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/catalog.ts#L24)

## Types

### `BooleanSettingKey`

Type.

The settings whose value is a boolean: what a toggle row may name.

```ts
type BooleanSettingKey = { [K in keyof Settings]-?: Settings[K] extends boolean ? K : never }[keyof Settings]
```

Source: [ui/src/settings/headless/catalog.ts:19](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/catalog.ts#L19)

### `PerfChannelDirection`

Type.

`invoke`: a request timed to its answer; `send`: a message to the host; `push`: a message from it.

```ts
type PerfChannelDirection = 'invoke' | 'send' | 'push'
```

Source: [ui/src/settings/headless/performance.ts:90](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L90)

### `PerfOrigin`

Type.

Whose cost a process is. `app`: the app's own (its processes, its daemon,
the servers and helpers they run). `launched`: what a session's commands, a
background task or a terminal started, and everything under it.

```ts
type PerfOrigin = 'app' | 'launched'
```

Source: [ui/src/settings/headless/performance.ts:21](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L21)

### `PerfProcessKind`

Type.

What a process is to the app.

```ts
type PerfProcessKind =
  | 'main'
  | 'window'
  | 'page'
  | 'gpu'
  | 'utility'
  | 'daemon'
  | 'child'
  | 'other'
```

Source: [ui/src/settings/headless/performance.ts:14](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L14)

### `PerfProfileOutcome`

Type.

A profile, or why there is none.

```ts
type PerfProfileOutcome =
  | { ok: true; profile: PerfProfile }
  | { error: PerfProfileError; ok: false }
```

Source: [ui/src/settings/headless/performance.ts:224](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L224)

### `PerfProfileTarget`

Type.

What a CPU profile records: the host's main process, or this window.

```ts
type PerfProfileTarget = 'main' | 'window'
```

Source: [ui/src/settings/headless/performance.ts:187](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/performance.ts#L187)

### `SettingsActionId`

Type.

Host actions (`SettingsAction.id`, wired by the app): a row that opens a flow of its own.

```ts
type SettingsActionId = 'claude-import' | 'safelist'
```

Source: [ui/src/settings/headless/layout.ts:44](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L44)

### `SettingsCatalogInstallKind`

Type.

What can be installed from a spec on a host.

```ts
type SettingsCatalogInstallKind = 'skill' | 'extension'
```

Source: [ui/src/settings/headless/sections-host.ts:301](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L301)

### `SettingsCatalogKind`

Type.

Which of a host's catalogs.

```ts
type SettingsCatalogKind = 'skills' | 'mcps' | 'extensions' | 'plugins'
```

Source: [ui/src/settings/headless/sections-host.ts:286](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L286)

### `SettingsCustomRowId`

Type.

Rows that aren't a table toggle or choice: a model picker, or the agent defaults.

```ts
type SettingsCustomRowId =
  | 'agentDefaults'
  | 'textModel'
  | 'decisionModel'
  | 'compactionModel'
  | 'clearSiteData'
  | 'conversationPresets'
```

Source: [ui/src/settings/headless/layout.ts:40](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L40)

### `SettingsDocument`

Type.

The settings document as the host holds it.

```ts
type SettingsDocument =
  | { status: 'loading' }
  | { status: 'ready'; values: Settings }
  | { error: SettingsError; status: 'error' }
```

Source: [ui/src/settings/headless/host.ts:50](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/host.ts#L50)

### `SettingsEnabledListKey`

Type.

The settings keys that hold an enabled allowlist.

```ts
type SettingsEnabledListKey =
  | 'enabledSkills'
  | 'enabledMcps'
  | 'enabledExtensions'
  | 'enabledPlugins'
```

Source: [ui/src/settings/headless/enabled.ts:16](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/enabled.ts#L16)

### `SettingsErrorKind`

Type.

Why the settings could not be read or written.

```ts
type SettingsErrorKind = 'unreachable' | 'refused' | 'failed'
```

Source: [ui/src/settings/headless/host.ts:31](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/host.ts#L31)

### `SettingsFileWrite`

Type.

What a guarded write did.

```ts
type SettingsFileWrite =
  | { mtimeMs: number; ok: true }
  | { ok: false; reason: 'changed' | 'missing' | 'denied' }
```

Source: [ui/src/settings/headless/sections-host.ts:59](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L59)

### `SettingsInstallScope`

Type.

Where an install goes: the project's folder or the user's.

```ts
type SettingsInstallScope = 'user' | 'project'
```

Source: [ui/src/settings/headless/sections-host.ts:46](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/sections-host.ts#L46)

### `SettingsLabels`

Type.

The shape of the settings label dictionary.

```ts
type SettingsLabels = typeof DEFAULT_SETTINGS_LABELS
```

Source: [ui/src/settings/headless/labels.ts:63](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/labels.ts#L63)

### `SettingsMcpAuthState`

Type.

Where an MCP server's sign-in is.

```ts
type SettingsMcpAuthState = 'idle' | 'needs-auth' | 'authorizing' | 'authed' | 'error'
```

Source: [ui/src/settings/headless/mcp.ts:40](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L40)

### `SettingsMcpBadge`

Type.

What a server's badge says: its sign-in state, or how its last test failed. `idle`: no badge.

```ts
type SettingsMcpBadge = SettingsMcpAuthState | 'key-refused' | 'bootstrap-error'
```

Source: [ui/src/settings/headless/mcp.ts:206](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/mcp.ts#L206)

### `SettingsPage`

Type.

A page of the layout.

```ts
type SettingsPage = SettingsSectionsPage | SettingsPanelPage
```

Source: [ui/src/settings/headless/layout.ts:113](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L113)

### `SettingsPageSection`

Type.

One titled section of a page of rows.

```ts
type SettingsPageSection =
  | { note?: SettingsSectionNoteId; rows: readonly SettingsRow[]; title: string }
  | { localOnly?: true; panel: 'spaces'; search: readonly SettingsSearchEntry[]; title: string }
```

Source: [ui/src/settings/headless/layout.ts:71](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L71)

### `SettingsPanelId`

Type.

Pages drawn by one panel component, mounted on first visit and then kept alive (their async state survives).

```ts
type SettingsPanelId =
  | 'instructions'
  | 'skills'
  | 'mcp'
  | 'plugins'
  | 'extensions'
  | 'environments'
  | 'appearance'
  | 'editor'
  | 'keybindings'
  | 'accounts'
  | 'hosts'
  | 'logs'
  | 'performance'
```

Source: [ui/src/settings/headless/layout.ts:21](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L21)

### `SettingsPreferredCredential`

Type.

What `setPreferred` promotes: a stored credential by key, or the first stored one of a kind.

```ts
type SettingsPreferredCredential = 'apikey' | 'oauth' | { key: string }
```

Source: [ui/src/settings/headless/providers.ts:88](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/providers.ts#L88)

### `SettingsRow`

Type.

One row of a section: a catalog key, a custom row the app draws, or an app action.

```ts
type SettingsRow =
  | { key: keyof Settings }
  | { custom: SettingsCustomRowId; localOnly?: true; search?: readonly SettingsSearchEntry[] }
  | { action: SettingsActionId }
```

Source: [ui/src/settings/headless/layout.ts:61](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L61)

### `SettingsSectionNoteId`

Type.

Status lines an app draws under a section (`SettingsRowsPage`'s `notes`): the terminals' daemon, how the app updates.

```ts
type SettingsSectionNoteId = 'terminalDaemon' | 'updates'
```

Source: [ui/src/settings/headless/layout.ts:68](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L68)

### `SettingsSectionsPageId`

Type.

Pages of rows.

```ts
type SettingsSectionsPageId = 'general' | 'agent' | 'interface' | 'advanced'
```

Source: [ui/src/settings/headless/layout.ts:15](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L15)

### `SettingsTabId`

Type.

Every page's id.

```ts
type SettingsTabId = SettingsSectionsPageId | SettingsPanelId
```

Source: [ui/src/settings/headless/layout.ts:37](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L37)

### `SettingsTopId`

Type.

The rail's entries.

```ts
type SettingsTopId = SettingsSectionsPageId | 'accounts' | 'extensions'
```

Source: [ui/src/settings/headless/layout.ts:18](https://github.com/Tahul/zidane/blob/main/ui/src/settings/headless/layout.ts#L18)