Official

settings

Built-in settings UI (JavaScript UI plugin).

The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install convergence/settings@0.2.2

Permissions in 0.2.2

  • Manage plugins plugins.manageOfficial onlyReloads and enables plugins. Only official plugins can have it.List, enable, disable and reload plugins, install updates, and quit to finish an update
  • Change app settings settings.writeHighChanges the app settings.Change the settings and the theme
  • Manage agents agents.manageHighEnables, disables and signs in agents, and changes their settings.Turn agents on and off, sign in to them and update them
  • Control chats chats.controlHighCreates chats, sends prompts and cancels runs.Import an agent's own sessions as chats
  • Read chats chats.readMediumReads your transcripts and chat lists.List the workspaces an agent's sessions can be imported into
  • Read app settings settings.readLowReads the app settings.Show the settings, and the tools and rules of every plugin
  • Show panels ui.slotsAlways grantedShows views in the listed parts of the window.Draw settings and the return-to-onboarding buttonSlots: centertitle

Files

views/onboarding.ts17.9 KB
// A quiet setup page. Agents, folders and plugins operate real settings;
// marketplace installs keep the guide's place and use the normal review flow.
import { html as htm } from "convergence";
import * as kit from "convergence";
import type { Element, IconName } from "convergence";
import type { EffectViewContext } from "convergence/effect";
import { STEPS } from "../onboarding.ts";
import type { Onboarding } from "../onboarding.ts";
import { renderAgentChoices } from "./agents.ts";
import { renderChatImport } from "./chat-import.ts";
import { card, column, fill, full, listRow, row, section, segmented } from "./layout.ts";

const TITLES = ["A workspace you can make your own.", "Bring your favorite agents.", "Make yourself at home.", "Choose what belongs in your workspace."];
const SUBTITLES = [
  "Your agents, your tools, your interface. Here’s what makes Divergence different.",
  "Choose one or several. Each uses its own models and account, with one place to work.",
  "Choose a look and a project folder. You can change both whenever you like.",
  "Enable optional official plugins, or find something new in the Marketplace. You decide what can run.",
];

function lesson(icon: IconName, title: string, text: string) {
  return htm`<div ...${row} alignItems="start" gap="medium" paddingY="medium" flexBasis=${260} flexGrow=${1} minWidth=${0}>
    <div ...${row} width=${28} height=${28} justifyContent="center" background="muted" borderRadius="sm" flexShrink=${0}><icon name=${icon} small tone="muted" /></div>
    <div ...${column} gap=${4} minWidth=${0} flexGrow=${1}>
      <text style="body" weight=${500}>${title}</text><text style="body" size="sm" tone="muted">${text}</text>
    </div>
  </div>`;
}

function discover() {
  return htm`<div ...${column} gap="large">
    <div ...${column} gap="large" padding="large" background="muted" borderRadius="xl">
      <div ...${row} gap="medium"><icon name="puzzle" tone="primary" /><text style="heading">Everything is a plugin. Even this page.</text></div>
      <text style="body" tone="muted">The chat, sidebar, agents, tools and themes are editable pieces of your workspace. Keep what works, add what’s missing, and make the rest yours.</text>
      <div ...${row} gap="large" flexWrap="wrap">
        ${[
          ["panel-left", "Sidebar"], ["messages-square", "Chat"], ["bot", "Agents"], ["wrench", "Tools"], ["palette", "Themes"],
        ].map(([icon, label]) => htm`<div ...${row} gap="small"><icon name=${icon} small tone="muted" /><text style="body" size="sm">${label}</text></div>`)}
      </div>
    </div>
    <div ...${row} gap="large" flexWrap="wrap" alignItems="start">
      ${lesson("sparkles", "Change the app by asking", "Open the Plugins workspace in the sidebar and ask an agent to change or build a plugin. Saved edits reload in the app.")}
      ${lesson("store", "Add something new", "Browse the Marketplace from the right rail. An agent reviews the plugin, then you approve its permissions before enabling it.")}
      ${lesson("wrench", "Give every agent new tools", "Enabled plugins can add tools, commands and instructions to your agents. Manage plugins in Settings → Plugins and tools in Settings → Tools.")}
      ${lesson("rotate-ccw", "Explore with a way back", "Divergence records file checkpoints before prompts. Use a message’s restore action to return the conversation and files to that point.")}
    </div>
    <div ...${column} gap="medium">
      <div ...${column} gap=${4}>
        <text style="body" weight=${500}>Try it in the Plugins workspace</text>
        <text style="body" size="sm" tone="muted">Your agent already has the plugin documentation, so describe what you want in plain language.</text>
      </div>
      <div ...${row} gap="medium" paddingX=${14} paddingY="medium" background="bubble" borderRadius="xl" ...${RAISED}>
        <icon name="message-square" small tone="muted" />
        <text style="body" size="sm">Build a plugin that adds a checklist panel for this project.</text>
      </div>
    </div>
    <div ...${row} gap="large" flexWrap="wrap">
      ${[
        ["at-sign", "Type @ to add files to a prompt"], ["square-slash", "Type / to open commands"], ["panel-right", "Files, Git and Terminal are in the right rail"],
      ].map(([icon, label]) => htm`<div ...${row} gap="small"><icon name=${icon} small tone="muted" /><text style="body" size="sm" tone="muted">${label}</text></div>`)}
    </div>
  </div>`;
}

function workspace(ctx: EffectViewContext<object>, actions: Onboarding["Service"]) {
  const state = actions.state;
  const selected = state.workspaces.find((w) => w.id === state.workspaceId);
  const enabled = state.agents.filter((a) => a.enabled);
  const ready = enabled.filter((a) => a.status?.state === "ready");
  return htm`<div ...${column} gap="large">
    <div ...${column} gap="medium" paddingY="large">
      <div ...${row} gap="medium"><icon name="palette" tone="muted" /><text style="heading">A look that feels right</text></div>
      <text style="body" tone="muted">Follow your system, or keep Divergence light or dark. More themes are in Settings.</text>
      <div ...${row}>${segmented("onboarding-appearance", state.settings?.appearance ?? "system", [
        { value: "system", label: "System" }, { value: "light", label: "Light" }, { value: "dark", label: "Dark" },
      ], (value) => ctx.run(actions.changeAppearance(value)))}</div>
    </div>
    <div ...${column} gap="medium" padding="large" background="muted" borderRadius="xl">
      <div ...${row} gap="medium"><icon name="folder-open" tone="primary" /><text style="heading">Where do you want to work?</text></div>
      <text style="body" tone="muted">A workspace is a folder on your computer. Its chats, files, terminal and Git changes stay together.</text>
      ${state.workspaces.length ? htm`<select id="onboarding-workspace" value=${state.workspaceId ?? ""} placeholder="Choose a workspace"
        options=${state.workspaces.map((w) => ({ value: w.id, label: w.name }))}
        onChange=${(e: { value: string }) => ctx.run(actions.chooseWorkspace(e.value))} />` : null}
      ${selected ? htm`<text style="body" size="xs" tone="muted">${selected.path}</text>` : null}
      <div ...${row}><button id="onboarding-folder" label=${selected ? "Choose another folder…" : "Choose a project folder…"} icon="folder-plus"
        loading=${state.pending === "folder"} disabled=${Boolean(state.pending)} onClick=${() => ctx.run(actions.addWorkspace())} /></div>
      <text style="body" size="xs" tone="faint">You can also choose Plugins to start customizing Divergence, or add a project later.</text>
    </div>
    <div ...${row} gap="medium" paddingY="large" alignItems="start">
      <icon name=${ready.length ? "circle-check" : "info"} tone=${ready.length ? "success" : "muted"} />
      <div ...${column} gap="small" ...${fill}>
        <text style="body" weight=${500}>${ready.length ? `${ready.map((a) => a.name).join(", ")} ${ready.length === 1 ? "is" : "are"} ready.` : "You can finish setting up your agents later."}</text>
        <text style="body" tone="muted">${ready.length && selected
          ? `Your first chat will open in ${selected.name}. Switch agents, models and modes from the controls below your prompt.`
          : !selected ? "Add a folder whenever you’re ready. New chat in the sidebar starts a conversation there."
          : "Enable an agent and finish its setup in Settings → Agents to start chatting."}</text>
        <text style="body" size="xs" tone="faint">Existing conversations? Import them into a workspace from Settings → General.</text>
      </div>
    </div>
  </div>`;
}

function plugins(ctx: EffectViewContext<object>, actions: Onboarding["Service"]) {
  const state = actions.state;
  const choices = state.plugins.filter((p) => actions.pluginChoices.has(p.name));
  const busy = Boolean(state.pending);
  const marketplace = state.plugins.find((p) => p.name === "market");
  return htm`<div ...${column} gap="large">
    ${section("Optional plugins", "Installed official extras and Marketplace plugins. New permissions always need your approval on the app’s card.", card(choices.map((p) => {
      const needsReview = p.pending.length > 0 || p.state === "not_enabled";
      return listRow(htm`<div ...${column} ...${fill} gap="small">
        <div ...${row} gap="small"><text style="body" size="sm" weight=${500}>${p.name}</text>
          ${p.official ? htm`<badge>Official</badge>` : null}
          ${p.enabled ? htm`<badge variant="success">Enabled</badge>` : null}
          ${p.state === "failed" ? htm`<badge variant="danger">Failed</badge>` : null}
        </div>
        <text style="body" size="xs" tone="muted">${p.description}</text>
        ${p.error ? htm`<text style="body" size="xs" tone="danger">${p.error}</text>` : null}
      </div>`, needsReview
        ? htm`<button id=${`onboarding-review-${p.name}`} label=${p.enabled ? "Review permissions…" : "Review and enable…"} small
            disabled=${busy} onClick=${() => ctx.run(actions.reviewPlugin(p.name))} />`
        : htm`<switch id=${`onboarding-plugin-${p.name}`} label="" checked=${p.enabled} disabled=${busy}
            onChange=${(e: { value: boolean }) => ctx.run(actions.setPluginEnabled(p.name, e.value))} />`);
    })))}
    ${!choices.length ? htm`<text style="body" tone="muted">Your installed plugins are already enabled. Find official extras and other plugins in the Marketplace.</text>` : null}
    <div ...${column} gap="medium" padding="large" background="muted" borderRadius="xl">
      <div ...${row} gap="medium"><icon name="store" tone="primary" /><text style="heading">Find something new</text></div>
      <text style="body" tone="muted">Browse official extras and community plugins. Install opens a chat where an agent reviews the plugin, then asks you to approve its permissions.</text>
      <text style="body" size="sm" tone="muted">Use “Back to onboarding” in the title bar to return here after the review. Your place is saved, even across restarts.</text>
      ${marketplace?.enabled
        ? htm`<div ...${row}><button id="onboarding-market" label="Browse plugins" icon="store" disabled=${busy} onClick=${() => ctx.run(actions.browsePlugins())} /></div>`
        : marketplace ? htm`<div ...${row}><button id="onboarding-enable-market" label="Enable Marketplace…" disabled=${busy} onClick=${() => ctx.run(actions.setPluginEnabled(marketplace.name, true))} /></div>`
        : htm`<text style="body" size="sm" tone="warning">The Marketplace plugin is not installed. Add it to browse new plugins.</text>`}
      ${!state.agents.some((a) => a.enabled && a.status?.state === "ready") ? htm`<text style="body" size="sm" tone="muted">Enable and sign in to an agent to review new plugins. You can browse now and install later.</text>` : null}
    </div>
  </div>`;
}

export function renderOnboardingReturn(ctx: EffectViewContext<object>, actions: Onboarding["Service"]): Element | null {
  if (!actions.state.returning || ctx.app.route === "onboarding") return null;
  return htm`<div ...${row} gap="small"><button id="onboarding-return" label="Back to onboarding" icon="arrow-left" small variant="ghost"
    disabled=${Boolean(actions.state.pending)} onClick=${() => ctx.run(actions.resume())} /></div>`;
}

// The guide covers the window (the kernel's `cover` overlay): one pane, a
// step list on the left whose selection glides between steps, and the
// step itself rising in. Every motion runs in the kernel.
const STEP_HINTS = ["What makes it different", "Choose who you work with", "Look and project folder", "Extras and Marketplace"];
const STEP_ROW = 46;
const STEP_GAP = 4;
// The shared surface looks from the runtime; an older runtime without them
// gets the same `elevation`, which its kernel already draws.
const RAISED = kit.RAISED ?? { elevation: "raised" };
const FLAT = kit.FLAT ?? { elevation: "none" };

// A block that rises a little and fades in, `order` steps after the first.
function rise(key: string, order: number, child: Element | null) {
  if (!child) return null;
  return htm`<div key=${key} ...${column} position="relative" top=${10} opacity=${0}
    motion=${{ to: { top: 0, opacity: 1 }, duration: 520, delay: order * 70, easing: "spring" }}>${child}</div>`;
}

function stepList(ctx: EffectViewContext<object>, actions: Onboarding["Service"], busy: boolean) {
  const step = actions.state.step;
  return htm`<div ...${column} position="relative" gap=${STEP_GAP}>
    <div id="onboarding-step-highlight" position="absolute" left=${0} right=${0} top=${step * (STEP_ROW + STEP_GAP)} height=${STEP_ROW}
      background="accent" borderRadius="sm" ...${RAISED}
      motion=${{ to: { top: step * (STEP_ROW + STEP_GAP) }, duration: 460, easing: "spring" }} />
    ${STEPS.map((label, i) => {
      const reachable = !busy && i <= step && i !== step;
      const mark = i < step ? "circle-check" : i === step ? "circle-dot" : "circle";
      return htm`<div id=${`onboarding-step-${i}`} key=${`step-${i}`} ...${row} gap="medium" height=${STEP_ROW} paddingX=${10}
        borderRadius="sm" ...${FLAT} cursor=${reachable ? "pointer" : undefined} opacity=${i > step ? 0.55 : 1}
        hover=${reachable ? { background: "hover" } : undefined} onClick=${reachable ? () => ctx.run(actions.move(i)) : undefined}>
        <icon name=${mark} small tone=${i < step ? "success" : i === step ? "primary" : "faint"} />
        <div ...${column} ...${fill} gap=${1}>
          <text style="body" size="sm" weight=${i === step ? 600 : 500}>${label}</text>
          <text style="body" size="xs" tone="muted" truncate>${STEP_HINTS[i]}</text>
        </div>
      </div>`;
    })}
  </div>`;
}

// Four short pills under the step: done ones full, the current one filling.
function progress(step: number) {
  return htm`<div ...${row} gap=${4}>${STEPS.map((_, i) => htm`<div key=${`pill-${i}`} width=${22} height=${4} borderRadius="full" background="muted" overflow="hidden">
    ${i <= step ? htm`<div key=${i === step ? `fill-${step}` : `done-${i}`} height=${4} width=${i < step ? 22 : 0} background="primary" borderRadius="full"
      motion=${i === step ? { to: { width: 22 }, duration: 640, easing: "easeOut", delay: 120 } : undefined} />` : null}
  </div>`)}</div>`;
}

export function renderOnboarding(ctx: EffectViewContext<object>, actions: Onboarding["Service"]): Element | null {
  const state = actions.state;
  if (ctx.app.route !== "onboarding") { state.active = false; return null; }
  if (!state.active) ctx.run(actions.enter());
  const busy = Boolean(state.pending);
  const canStart = Boolean(state.workspaceId && state.agents.some((a) => a.enabled && a.status?.state === "ready"));
  const step = state.step;
  const body = !state.ready ? htm`<text style="body" tone="muted">Loading your workspace…</text>`
    : step === 0 ? discover()
    : step === 1 ? htm`<div ...${column} gap="large">
        ${state.agents.length ? renderAgentChoices(ctx, actions) : htm`<callout title="No agents available" text="Enable an agent provider in Settings → Plugins, then return here to finish setup." />`}
        ${card([renderChatImport(ctx, actions.imports)])}
        <text style="body" size="sm" tone="muted">Sign-in and installation messages come from each agent. You can continue and finish setup later.</text>
      </div>`
    : step === 2 ? htm`<div ...${column} gap="large">${workspace(ctx, actions)}${actions.imports.state.enabled ? card([renderChatImport(ctx, actions.imports)]) : null}</div>`
    : plugins(ctx, actions);
  const page = htm`<div ...${row} ...${full} alignItems="stretch">
    <div ...${column} width=${264} flexShrink=${0} padding="large" paddingY=${28} gap=${28}>
      <div ...${row} gap="medium" paddingX=${10}>
        <icon name="puzzle" small tone="primary" /><text style="body" weight=${600}>Welcome to Divergence</text>
      </div>
      ${stepList(ctx, actions, busy)}
      <spacer />
      <text style="body" size="xs" tone="faint">You can revisit this guide anytime from Settings → General.</text>
    </div>
    <div ...${column} ...${fill}>
      <div ...${column} ...${fill} width="100%" overflowY="scroll">
        <div key=${`step-${step}`} ...${column} maxWidth=${680} width="100%" marginX="auto" gap=${24} paddingX="large" paddingTop=${56} paddingBottom="large">
          ${rise("head", 0, htm`<div ...${column} gap="medium">
            <text style="body" size="xs" weight=${600} tone="muted">${`Step ${step + 1} of ${STEPS.length}`}</text>
            <div fontFamily="Bricolage Grotesque" fontSize="1.875rem" fontWeight=${500}><text>${TITLES[step]}</text></div>
            <text style="body" tone="muted">${SUBTITLES[step]}</text>
          </div>`)}
          ${rise("error", 1, state.error ? htm`<callout tone="danger" title="Something needs attention" text=${state.error}>
            <button id="onboarding-retry" label=${state.ready ? "Refresh status" : "Try again"} disabled=${busy} onClick=${() => ctx.run(actions.retry())} />
          </callout>` : null)}
          ${rise(state.ready ? "body" : "loading", 2, body)}
        </div>
      </div>
      <div ...${row} maxWidth=${680} width="100%" marginX="auto" gap="medium" paddingX="large" paddingY="large" flexWrap="wrap">
        ${step > 0 ? htm`<button id="onboarding-back" label="Back" icon="arrow-left" variant="ghost" disabled=${busy} onClick=${() => ctx.run(actions.move(step - 1))} />` : null}
        <button id="onboarding-skip" label="Set up later" variant="ghost" disabled=${busy} onClick=${() => ctx.run(actions.finish(false))} />
        <spacer />
        ${progress(step)}
        <button id="onboarding-next" label=${step === 0 ? "Choose agents" : step === 1 ? "Make it yours" : step === 2 ? "Choose plugins" : canStart ? "Start your first chat" : "Open Divergence"}
          icon=${step === 3 ? "arrow-up-right" : "arrow-right"} variant="primary" loading=${state.pending === "finish"}
          disabled=${busy || !state.ready} onClick=${() => ctx.run(step === 3 ? actions.finish(true) : actions.move(step + 1))} />
      </div>
    </div>
  </div>`;
  // `width` and `top` only shape the card an older kernel draws without `cover`.
  return htm`<overlay id="onboarding" open cover width=${880} top=${0.06}>${page}</overlay>`;
}

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.3latestNov 21, 2026>=2 <439.8 KB7 permissionsListed
0.2.2Oct 25, 2026>=2 <439.3 KB7 permissionsListed
0.2.1Oct 23, 2026>=2 <439.2 KB7 permissionsListed
0.2.0Oct 5, 2026>=2 <324.7 KB7 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.