@kal-elsam/kairo-runtime 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ Historical entries below may reference the legacy `@kal-elsam/harness` package n
 
 ## Unreleased
 
+## 0.14.0 — 2026-08-07 (Kairo Runtime)
+
+Minor release. Simpler Cockpit, one-command CLI self-update, pnpm for
+contributors, and a minimal IDE status panel. Publish tag:
+`kairo-runtime-v0.14.0`.
+
+### Added
+
+- Cockpit Home with three tabs (Home · Settings · History) and two clear
+  actions (prepare/repair + Configure). Secondary destinations stay in `/`.
+- `kairo update`: update the Kairo CLI from npm (`--yes` applies). Workspace
+  template refresh stays at `kairo update --scope=workspace`.
+- VS Code / Cursor extension scaffold in `packages/kairo-vscode`: status bar +
+  explorer tree from `kairo status --json`; sync/doctor/cockpit open a terminal
+  (no silent writes). Local VSIX via `npm run package`.
+
+### Changed
+
+- Local development and CI use **pnpm 10.x** (`packageManager` pinned). End-user
+  installs and `npm publish` (OIDC Trusted Publishing) stay on npm.
+- Install scripts blocked by default (`pnpm.onlyBuiltDependencies: []`);
+  `.npmrc` sets `strict-dep-builds` and `minimum-release-age=1440`.
+
 ## 0.13.1 — 2026-08-07 (Kairo Runtime)
 
 Patch release. Docs/UX/license polish for npm adoption. Publish tag:

package/README.md

@@ -24,25 +24,23 @@ KAIRO
 Needs attention · 4/4 agents · drift pending
 Kairo coordinates installed AI agents for this project.
 
-→ Fix drift
-  Run "kairo sync" to repair managed content.
-  Enter → preview in Governance
-
-  Last activity · codex · failed
-  Obsidian not connected · open Settings to choose your vault
-  Update available · run kairo updates check
-  9 more in Details · Space
+→ Repair 3 changes
+  You will see the exact plan before anything is written.
+
+  Configure
+  Agents, Obsidian vault, integrations.
 ```
 
-`↑↓` move · `Enter` open · `Space` details · `R` refresh · `Esc` back · `?` help
+`↑↓` move · `Enter` open · `Tab` nav · `Space` details · `R` refresh · `Esc` back · `?` help
 
-## The four commands
+## Day-to-day commands
 
 | Command | What it does |
 |---|---|
 | `kairo` | Open the cockpit |
 | `kairo status` | See how your setup is doing |
 | `kairo sync` | Repair what drifted |
+| `kairo update` | Update Kairo itself from npm |
 | `kairo doctor` | Deeper health checks |
 
 Run `kairo help --all` for everything else, or read the
@@ -70,6 +68,10 @@ npx @kal-elsam/kairo-runtime
 # Install globally
 npm i -g @kal-elsam/kairo-runtime && kairo
 
+# Later: update the CLI itself
+kairo update
+kairo update --yes
+
 # Preview the setup plan, write nothing
 npx @kal-elsam/kairo-runtime --dry-run
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Pi, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",
@@ -62,6 +62,10 @@
   "engines": {
     "node": ">=20.12.0"
   },
+  "packageManager": "pnpm@10.34.5",
+  "pnpm": {
+    "onlyBuiltDependencies": []
+  },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
     "@modelcontextprotocol/server": "2.0.0",

package/scripts/cockpit-smoke.mjs

@@ -86,7 +86,7 @@ const asciiNav = buildNavModel({
 assert.equal(asciiNav.items[1].marker, ">");
 assert.equal(asciiNav.items[0].current, true);
 assert.equal(asciiNav.items[1].selected, true);
-assert.match(asciiNav.explanation, /Repair|Govern|Activity|Usage|Settings|Overview/i);
+assert.match(asciiNav.explanation, /agents|Obsidian|integrations/i);
 
 function applyKey(state, keyAction) {
   const routed = routeCockpitKey(state, keyAction);
@@ -99,25 +99,29 @@ function smokeNavigation(layoutMode) {
     layoutMode,
     region: layoutMode === LAYOUT_MODES.MINIMAL ? COCKPIT_REGIONS.CONTENT : COCKPIT_REGIONS.NAV
   });
-  const diagnosticsIndex = COCKPIT_NAV.findIndex((item) => item.id === "governance");
-  while (state.navIndex < diagnosticsIndex) {
+  const settingsIndex = COCKPIT_NAV.findIndex((item) => item.id === "settings");
+  while (state.navIndex < settingsIndex) {
     state = applyKey(state, { type: "arrow", direction: "down" });
   }
   state = applyKey(state, { type: "enter" });
-  assert.equal(state.view, ORCHESTRATOR_VIEWS.CHANGES);
-  assert.equal(state.region, COCKPIT_REGIONS.NAV);
+  assert.equal(state.view, ORCHESTRATOR_VIEWS.PROFILE);
+  assert.equal(state.region, COCKPIT_REGIONS.CONTENT);
 
-  state = applyKey(state, { type: "arrow", direction: "up" });
+  state = applyKey(state, { type: "tab" });
+  assert.equal(state.region, COCKPIT_REGIONS.NAV);
+  while (state.navIndex > 0) {
+    state = applyKey(state, { type: "arrow", direction: "up" });
+  }
   state = applyKey(state, { type: "enter" });
   assert.equal(state.view, ORCHESTRATOR_VIEWS.HOME);
-  assert.equal(state.region, COCKPIT_REGIONS.NAV);
+  assert.equal(state.region, COCKPIT_REGIONS.CONTENT);
 
   const footer = buildFooterModel({
-    view: ORCHESTRATOR_VIEWS.CHANGES,
-    region: COCKPIT_REGIONS.NAV,
+    view: ORCHESTRATOR_VIEWS.HOME,
+    region: COCKPIT_REGIONS.CONTENT,
     unicode: false
   });
-  assert.doesNotMatch(footer.text, /Tab/);
+  assert.match(footer.text, /Tab/);
 
   state = applyKey(state, { type: "escape" });
   assert.equal(state.view, ORCHESTRATOR_VIEWS.HOME);

package/src/cli.js

@@ -30,6 +30,7 @@ import {
   runGlobalReport
 } from "./global/global-cli.js";
 import { runEcosystemUpdatesCheck } from "./global/updates-cli.js";
+import { runSelfUpdate } from "./global/self-update.js";
 import { applyPolicyToOptions, loadPolicyFile } from "./global/policy.js";
 import { resolveHomeDir } from "./global/paths.js";
 import { runWorkspaceDetect, runWorkspaceDoctor, runWorkspaceInit, runWorkspaceUpdate } from "./workspace-cli.js";
@@ -173,9 +174,15 @@ export async function runCli(argv) {
       });
       return;
     case "update":
-      await dispatchByScope(options, "agent-global", {
-        "agent-global": () => runGlobalInstall(options, packageManifest, packageRoot, { update: true }),
-        workspace: () => runWorkspaceUpdate(options, packageManifest, packageRoot)
+      if (options.scope === "workspace") {
+        await runWorkspaceUpdate(options, packageManifest, packageRoot);
+        return;
+      }
+      await runSelfUpdate({
+        packageName: packageManifest.name,
+        cliVersion: packageManifest.version,
+        yes: optionsWithPolicy.yes === true,
+        json: optionsWithPolicy.json === true
       });
       return;
     case "doctor":

package/src/global/cli-help.js

@@ -29,6 +29,7 @@ Usage:
   ${cli}                 Open the cockpit (setup on first run)
   ${cli} status          See how your setup is doing
   ${cli} sync            Repair what drifted
+  ${cli} update          Update Kairo itself (npm)
   ${cli} doctor          Deeper health checks
 
   ${cli} help --all      Every command and flag
@@ -63,7 +64,8 @@ Bootstrap: see README.md and docs/install.md (curl install.sh or npx ${PACKAGE_N
   ${cli} updates check [--json] [--force]
   ${cli} install [--agents <list|all>] [--components <list>] [--dry-run]
   ${cli} install --no-default-components
-  ${cli} update [--dry-run]             Technical repair alias (prefer sync)
+  ${cli} update [--yes] [--json]        Update the Kairo CLI from npm
+  ${cli} update --scope=workspace [--dry-run]  Refresh workspace template files
   ${cli} uninstall [--dry-run]
 
 ## Agents & runs
@@ -143,7 +145,7 @@ Commands:
   updates    Read-only ecosystem update check (kairo/hermes/gentle/skills). Never applies.
   install    Non-interactive configure (agent-global) or legacy workspace scaffold.
   doctor     Detailed health checks for managed state and configs.
-  update     Technical repair alias (prefer sync for day-to-day use).
+  update     Update the Kairo CLI from npm (--yes applies). Workspace templates: --scope=workspace.
   detect     Inspect global agents and the current project. Read-only.
   adapters   Official adapter matrix: roots, config files, detected/managed.
   explain    Read-only audit of managed adapters, configs, markers, and backups.

package/src/global/ink/cockpit-controller.js

@@ -122,9 +122,7 @@ export function reduceCockpitUi(state, action) {
       if (state.region === COCKPIT_REGIONS.SYSTEM) return state;
 
       const navigatesNav = state.region === COCKPIT_REGIONS.NAV
-        || isNavFocusedView(state.view)
-        || (state.view === ORCHESTRATOR_VIEWS.HOME
-          && state.layoutMode === LAYOUT_MODES.MINIMAL);
+        || isNavFocusedView(state.view);
 
       if (navigatesNav) {
         const delta = action.direction === "up" ? -1 : 1;

package/src/global/ink/cockpit-enter.js

@@ -11,7 +11,9 @@ export function resolveEnterNavIntent({
 } = {}) {
   if (!navItem) return { kind: "noop" };
 
-  const isOverview = navItem.id === "overview" || navItem.view === ORCHESTRATOR_VIEWS.HOME;
+  const isOverview = navItem.id === "home"
+    || navItem.id === "overview"
+    || navItem.view === ORCHESTRATOR_VIEWS.HOME;
   if (isOverview) {
     if (currentView === ORCHESTRATOR_VIEWS.HOME && ctaDestination) {
       if (ctaDestination === "setup") return { kind: "activate-setup" };

package/src/global/ink/cockpit-focus.js

@@ -3,7 +3,6 @@ import { ORCHESTRATOR_VIEWS } from "./orchestrator-state.js";
 import { LAYOUT_MODES } from "./layout.js";
 
 const NAV_FOCUSED_VIEWS = new Set([
-  ORCHESTRATOR_VIEWS.HOME,
   ORCHESTRATOR_VIEWS.IDES,
   ORCHESTRATOR_VIEWS.MODULES,
   ORCHESTRATOR_VIEWS.CHANGES,
@@ -14,6 +13,7 @@ const NAV_FOCUSED_VIEWS = new Set([
 ]);
 
 const CONTENT_INTERACTIVE_VIEWS = new Set([
+  ORCHESTRATOR_VIEWS.HOME,
   ORCHESTRATOR_VIEWS.RUNS,
   ORCHESTRATOR_VIEWS.ACTIVE_RUNS,
   ORCHESTRATOR_VIEWS.RECENT_RUNS,
@@ -102,6 +102,12 @@ export function routeCockpitKey(state, keyAction) {
       if (state.region === COCKPIT_REGIONS.NAV || isNavFocusedView(state.view)) {
         return { type: "enter-nav" };
       }
+      if (
+        state.region === COCKPIT_REGIONS.CONTENT
+        && state.view === ORCHESTRATOR_VIEWS.HOME
+      ) {
+        return { type: "enter-home-button" };
+      }
       return null;
     default:
       return null;

package/src/global/ink/cockpit-models.js

@@ -17,23 +17,33 @@ export const COCKPIT_REGIONS = {
 
 export const COCKPIT_NAV = [
   {
-    id: "overview",
-    label: "Overview",
+    id: "home",
+    label: "Home",
     view: ORCHESTRATOR_VIEWS.HOME,
-    description: "Status, next action, activity, alerts, and tokens."
+    description: "What needs you, and what to do about it."
   },
+  {
+    id: "settings",
+    label: "Settings",
+    view: ORCHESTRATOR_VIEWS.PROFILE,
+    description: "Choose agents, connect Obsidian, add integrations."
+  },
+  {
+    id: "history",
+    label: "History",
+    view: ORCHESTRATOR_VIEWS.ACTIVITY,
+    description: "What Kairo changed, and how to undo it."
+  }
+];
+
+/** Destinations reachable via the action palette, not the top nav. */
+export const COCKPIT_SECONDARY = [
   {
     id: "governance",
     label: "Governance",
     view: ORCHESTRATOR_VIEWS.CHANGES,
     description: "Repair drift and apply governed changes."
   },
-  {
-    id: "activity",
-    label: "Activity",
-    view: ORCHESTRATOR_VIEWS.ACTIVITY,
-    description: "Operations, backups, and recovery."
-  },
   {
     id: "orchestration",
     label: "Orchestration",
@@ -45,12 +55,6 @@ export const COCKPIT_NAV = [
     label: "Usage",
     view: ORCHESTRATOR_VIEWS.USAGE,
     description: "Token and context pressure when auditable."
-  },
-  {
-    id: "settings",
-    label: "Settings",
-    view: ORCHESTRATOR_VIEWS.PROFILE,
-    description: "Profile, policy, and guided configuration."
   }
 ];
 
@@ -64,8 +68,8 @@ export function regionsForLayout(layoutMode) {
 
 export function navIndexForView(view, items = COCKPIT_NAV) {
   if (isRunsBranchView(view)) {
-    const orchIndex = items.findIndex((item) => item.id === "orchestration");
-    return orchIndex >= 0 ? orchIndex : 0;
+    const historyIndex = items.findIndex((item) => item.id === "history");
+    return historyIndex >= 0 ? historyIndex : 0;
   }
   const index = items.findIndex((item) => item.view === view);
   return index >= 0 ? index : 0;
@@ -105,6 +109,7 @@ export function resolveNavStatusSummary(item, {
   const backups = snapshot?.backups?.count ?? 0;
 
   switch (item.id) {
+    case "home":
     case "overview":
       return snapshot?.health?.replaceAll("_", " ")
         ?? resolveProjectReadiness({
@@ -114,6 +119,7 @@ export function resolveNavStatusSummary(item, {
         }).label;
     case "governance":
       return changes > 0 ? `${changes} pending` : "Clean";
+    case "history":
     case "activity":
       return backups > 0 ? `${backups} backups` : "No backups";
     case "orchestration":
@@ -174,6 +180,7 @@ export function buildNavModel({
   const mapped = items.map((item, index) => {
     const isSelected = index === navIndex;
     const isCurrent = item.view === currentView
+      || (item.id === "history" && isRunsBranchView(currentView))
       || (item.id === "orchestration" && isRunsBranchView(currentView));
     return {
       ...item,
@@ -185,11 +192,13 @@ export function buildNavModel({
     };
   });
 
+  const explanation = !selected || selected.id === "home" || selected.id === "overview"
+    ? ""
+    : (selected.description ?? "");
+
   return {
     title: "NAVIGATION",
-    explanation: selected
-      ? `${selected.description} (${resolveNavStatusSummary(selected, { dashboard, diagnostics, snapshot })})`
-      : "",
+    explanation,
     items: mapped
   };
 }
@@ -320,7 +329,7 @@ export function buildFooterModel({
   // HOME footer must stay on one line at 80 cols (frame already near 24 rows).
   if (view === ORCHESTRATOR_VIEWS.HOME) {
     return {
-      text: ["↑↓", "Enter", "Space", "R", "?", "/", "Esc"].join(` ${glyphs.bullet} `),
+      text: ["↑↓", "Enter", "Tab", "Space", "R", "?", "/", "Esc"].join(` ${glyphs.bullet} `),
       columns: footerColumns
     };
   }

package/src/global/ink/cockpit-palette.js

@@ -1,6 +1,8 @@
-import { COCKPIT_NAV } from "./cockpit-models.js";
+import { COCKPIT_NAV, COCKPIT_SECONDARY } from "./cockpit-models.js";
 import { ORCHESTRATOR_VIEWS } from "./orchestrator-state.js";
 
+const PALETTE_NAV_ITEMS = [...COCKPIT_NAV, ...COCKPIT_SECONDARY];
+
 export const PALETTE_KINDS = Object.freeze({
   NAVIGATE: "navigate",
   REFRESH: "refresh",
@@ -12,10 +14,13 @@ const DESTINATION_VIEWS = Object.freeze({
   changes: ORCHESTRATOR_VIEWS.CHANGES,
   governance: ORCHESTRATOR_VIEWS.CHANGES,
   "control-center": ORCHESTRATOR_VIEWS.HOME,
+  home: ORCHESTRATOR_VIEWS.HOME,
   ides: ORCHESTRATOR_VIEWS.IDES,
   modules: ORCHESTRATOR_VIEWS.MODULES,
   activity: ORCHESTRATOR_VIEWS.ACTIVITY,
+  history: ORCHESTRATOR_VIEWS.ACTIVITY,
   profile: ORCHESTRATOR_VIEWS.PROFILE,
+  settings: ORCHESTRATOR_VIEWS.PROFILE,
   runs: ORCHESTRATOR_VIEWS.RUNS,
   orchestration: ORCHESTRATOR_VIEWS.RUNS,
   usage: ORCHESTRATOR_VIEWS.USAGE,
@@ -30,12 +35,12 @@ export function canOpenPalette({ loading = false, busy = false, confirming = fal
   return !loading && !busy && !confirming;
 }
 
-/** Optional CTA + six destinations + Refresh + Help. No write shortcuts. */
+/** Optional CTA + primary/secondary destinations + Refresh + Help. No write shortcuts. */
 export function buildPaletteActions({
   ctaDestination = null,
   ctaTitle = null,
   ctaDetail = null,
-  navItems = COCKPIT_NAV
+  navItems = PALETTE_NAV_ITEMS
 } = {}) {
   const actions = [];
   if (ctaDestination === "setup") {

package/src/global/ink/cockpit-views.js

@@ -100,7 +100,8 @@ export function renderCockpitView({
   governanceDetailsOpen = false,
   activityDetailsOpen = false,
   contentFocused = false,
-  homeDir = null
+  homeDir = null,
+  hasGlobalState = false
 }) {
   if (palette) {
     return React.createElement(PalettePanel, { model: palette, colorEnabled });
@@ -112,7 +113,13 @@ export function renderCockpitView({
         detailsOpen: overviewDetailsOpen,
         colorEnabled,
         unicode,
-        layoutMode
+        layoutMode,
+        selectedIndex: listIndex,
+        contentFocused,
+        hasGlobalState,
+        snapshot,
+        diagnostics,
+        dashboard
       });
     case ORCHESTRATOR_VIEWS.USAGE:
       return React.createElement(SemanticUsagePanel, {

package/src/global/ink/orchestrator-app.js

@@ -46,6 +46,7 @@ import { LAYOUT_MODES } from "./layout.js";
 import { CHANGES_PHASE } from "./cockpit-changes.js";
 import { RECOVERY_PHASE, listRecoverySnapshots } from "./cockpit-recovery.js";
 import { SETTINGS_PHASE } from "./cockpit-settings.js";
+import { buildOverviewButtons, OVERVIEW_BUTTON_COUNT } from "./ux/overview-actions.js";
 
 export function OrchestratorApp({
   homeDir,
@@ -245,7 +246,9 @@ export function OrchestratorApp({
       return;
     }
 
-    const listLength = ui.view === ORCHESTRATOR_VIEWS.RUNS
+    const listLength = ui.view === ORCHESTRATOR_VIEWS.HOME
+      ? OVERVIEW_BUTTON_COUNT
+      : ui.view === ORCHESTRATOR_VIEWS.RUNS
       ? RUNS_HUB_ITEMS.length
       : ui.view === ORCHESTRATOR_VIEWS.ACTIVE_RUNS
         ? (data.dashboard?.activeRuns ?? []).length
@@ -301,6 +304,21 @@ export function OrchestratorApp({
           return;
         }
       }
+      if (routed.type === "enter-home-button") {
+        const buttons = buildOverviewButtons({
+          hasGlobalState,
+          snapshot: data.snapshot,
+          diagnostics: data.diagnostics,
+          dashboard: data.dashboard
+        });
+        const selected = buttons[Math.min(Math.max(0, ui.listIndex), buttons.length - 1)];
+        const intent = selected?.intent ?? null;
+        if (intent === "setup") {
+          finish({ cancelled: false, action: "setup" });
+          return;
+        }
+        if (intent && openDestination(intent)) return;
+      }
       dispatch(routed);
       return;
     }
@@ -583,7 +601,8 @@ export function OrchestratorApp({
         governanceDetailsOpen: ui.governanceDetailsOpen,
         activityDetailsOpen: ui.activityDetailsOpen,
         contentFocused: ui.region === COCKPIT_REGIONS.CONTENT,
-        homeDir
+        homeDir,
+        hasGlobalState
       })
     )
   );

package/src/global/ink/ux/live-overview.js

@@ -1,16 +1,16 @@
 /**
  * Live semantic Overview for Cockpit HOME — product cover.
- * Nav owns the sole focus mark — this panel never renders `>`.
+ * Content owns the button focus mark when region=content.
  * ASCII wordmark only here (wide/compact); minimal is textual.
  *
- * Rule: show purpose + one next step + a few plain-language needs.
+ * Rule: show purpose + two buttons + a few plain-language needs.
  * Machine/system noise stays out of the first screen (Details only).
  */
 import React from "react";
 import { Box, Text } from "ink";
 import { DASHBOARD_PURPOSE } from "../../dashboard-guidance.js";
 import { LAYOUT_MODES } from "../layout.js";
-import { COCKPIT_COLORS } from "../theme.js";
+import { COCKPIT_COLORS, resolveGlyphs } from "../theme.js";
 import {
   overviewBrandTitle,
   shouldShowWordmark,
@@ -24,6 +24,7 @@ import {
   mapHealthTone,
   partitionCompanionLines
 } from "./overview-needs.js";
+import { buildOverviewButtons, OVERVIEW_BUTTON_COUNT } from "./overview-actions.js";
 
 export {
   humanizeCompanionNeed,
@@ -33,6 +34,8 @@ export {
   partitionCompanionLines
 } from "./overview-needs.js";
 
+export { buildOverviewButtons, OVERVIEW_BUTTON_COUNT } from "./overview-actions.js";
+
 /** Safe Details lines — leftovers + raw signals; never invent paths/IDs. */
 export function buildOverviewDetails(model = {}, companionRest = []) {
   const lines = [];
@@ -59,13 +62,19 @@ export function buildOverviewDetails(model = {}, companionRest = []) {
 
 /**
  * Pure adapter: buildControlCenterModel → semantic overview props.
- * First screen = purpose + next step + plain needs. Machine noise → Details.
+ * First screen = purpose + two buttons + plain needs. Machine noise → Details.
  */
-export function adaptControlCenterToOverview(model = {}) {
+export function adaptControlCenterToOverview(model = {}, options = {}) {
   const status = model.status ?? model.health ?? {};
   const next = model.nextAction ?? model.cta ?? {};
   const { needs, rest } = partitionCompanionLines(model.companion?.lines ?? []);
   const primary = humanizePrimary(next);
+  const buttons = buildOverviewButtons({
+    hasGlobalState: options.hasGlobalState,
+    snapshot: options.snapshot,
+    diagnostics: options.diagnostics,
+    dashboard: options.dashboard
+  });
 
   const activity = model.activity?.headline;
   const metrics = [];
@@ -104,6 +113,7 @@ export function adaptControlCenterToOverview(model = {}) {
       body: status.summaryLine ?? ""
     },
     primary,
+    buttons,
     metrics,
     details: buildOverviewDetails(model, rest)
   };
@@ -136,14 +146,30 @@ export function SemanticOverviewPanel({
   detailsOpen = false,
   colorEnabled = true,
   unicode = true,
-  layoutMode = LAYOUT_MODES.COMPACT
+  layoutMode = LAYOUT_MODES.COMPACT,
+  selectedIndex = 0,
+  contentFocused = false,
+  hasGlobalState = false,
+  snapshot = null,
+  diagnostics = null,
+  dashboard = null
 }) {
-  const view = adaptControlCenterToOverview(model);
+  const view = adaptControlCenterToOverview(model, {
+    hasGlobalState,
+    snapshot,
+    diagnostics,
+    dashboard
+  });
   const showArt = shouldShowWordmark(layoutMode);
   const brandTitle = overviewBrandTitle(layoutMode);
   const isWide = layoutMode === LAYOUT_MODES.WIDE;
   const mark = renderWordmark({ layoutMode, colorEnabled, unicode });
   const status = renderCallout(view, colorEnabled);
+  const safeIndex = Math.min(
+    Math.max(0, selectedIndex),
+    Math.max(0, view.buttons.length - 1)
+  );
+  const glyphs = resolveGlyphs(unicode);
 
   const hero = showArt
     ? (isWide
@@ -166,18 +192,25 @@ export function SemanticOverviewPanel({
       color: colorEnabled ? COCKPIT_COLORS.muted : undefined
     }, view.purpose),
     React.createElement(Box, { marginTop: 1, flexDirection: "column" },
-      React.createElement(Text, {
-        bold: true,
-        color: colorEnabled ? COCKPIT_COLORS.interactive : undefined
-      }, `→ ${view.primary.label}`),
-      view.primary.detail
-        ? React.createElement(Text, null, view.primary.detail)
-        : null,
-      view.primary.hint
-        ? React.createElement(Text, {
-          color: colorEnabled ? COCKPIT_COLORS.muted : undefined
-        }, view.primary.hint)
-        : null
+      ...view.buttons.map((button, index) => {
+        const selected = index === safeIndex;
+        const focused = contentFocused && selected;
+        return React.createElement(Box, {
+          key: button.id,
+          flexDirection: "column",
+          marginBottom: index === view.buttons.length - 1 ? 0 : 1
+        },
+          React.createElement(Text, {
+            bold: true,
+            color: focused && colorEnabled ? COCKPIT_COLORS.interactive : undefined
+          }, `${focused ? glyphs.focus : " "} ${button.label}`),
+          button.detail
+            ? React.createElement(Text, {
+              color: colorEnabled ? COCKPIT_COLORS.muted : undefined
+            }, `  ${button.detail}`)
+            : null
+        );
+      })
     ),
     React.createElement(Box, { marginTop: 1, flexDirection: "column" },
       React.createElement(ActionList, {

package/src/global/ink/ux/overview-actions.js

@@ -0,0 +1,80 @@
+/**
+ * Two explicit Home buttons — prepare + configure.
+ * No writes here: intents only open existing consent-gated flows.
+ */
+
+export const OVERVIEW_BUTTON_COUNT = 2;
+
+function changeCount(snapshot) {
+  if (!snapshot?.diff?.hasChanges) return 0;
+  return snapshot.diff.changeCount
+    ?? snapshot.diff.changes?.length
+    ?? 0;
+}
+
+function detectedAgentCount({ snapshot = null, diagnostics = null, dashboard = null } = {}) {
+  if (Number.isFinite(snapshot?.coverage?.detectedAgents)) {
+    return snapshot.coverage.detectedAgents;
+  }
+  if (Number.isFinite(diagnostics?.diagnostics?.detected)) {
+    return diagnostics.diagnostics.detected;
+  }
+  return (dashboard?.providers ?? []).filter((entry) => entry?.available).length;
+}
+
+function buildPrepareButton({
+  hasGlobalState = false,
+  snapshot = null,
+  diagnostics = null,
+  dashboard = null
+} = {}) {
+  const detected = detectedAgentCount({ snapshot, diagnostics, dashboard });
+  const needsSetup = hasGlobalState === false || detected === 0;
+  if (needsSetup) {
+    return {
+      id: "prepare",
+      label: "Set up Kairo",
+      detail: "Detect your agents and install what is missing.",
+      intent: "setup"
+    };
+  }
+
+  const pending = changeCount(snapshot);
+  if (pending > 0) {
+    return {
+      id: "prepare",
+      label: `Repair ${pending} change${pending === 1 ? "" : "s"}`,
+      detail: "You will see the exact plan before anything is written.",
+      intent: "governance"
+    };
+  }
+
+  return {
+    id: "prepare",
+    label: "Everything is ready",
+    detail: "Open History to see what changed, or Configure to adjust.",
+    intent: "history"
+  };
+}
+
+const CONFIGURE_BUTTON = Object.freeze({
+  id: "configure",
+  label: "Configure",
+  detail: "Agents, Obsidian vault, integrations.",
+  intent: "settings"
+});
+
+/**
+ * Exactly two buttons for Home. First button changes face by state.
+ */
+export function buildOverviewButtons({
+  hasGlobalState = false,
+  snapshot = null,
+  diagnostics = null,
+  dashboard = null
+} = {}) {
+  return [
+    buildPrepareButton({ hasGlobalState, snapshot, diagnostics, dashboard }),
+    { ...CONFIGURE_BUTTON }
+  ];
+}

package/src/global/self-update.js

@@ -0,0 +1,216 @@
+import { spawn } from "node:child_process";
+import { fetchPublishedVersion } from "./npm-registry.js";
+import { formatCliCommand } from "./brand/cli.js";
+import { commandHeader } from "./brand/index.js";
+
+/**
+ * @param {string} version
+ * @returns {number[]}
+ */
+export function parseSemver(version) {
+  const match = String(version).trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+/**
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1|0|1|null}
+ */
+export function compareSemver(a, b) {
+  const left = parseSemver(a);
+  const right = parseSemver(b);
+  if (!left || !right) return null;
+  for (let i = 0; i < 3; i += 1) {
+    if (left[i] < right[i]) return -1;
+    if (left[i] > right[i]) return 1;
+  }
+  return 0;
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {"npm"|"pnpm"|"yarn"|"bun"}
+ */
+export function detectInstallPackageManager(env = process.env) {
+  const execPath = env.npm_execpath ?? "";
+  const userAgent = env.npm_config_user_agent ?? "";
+  if (execPath.includes("pnpm") || userAgent.startsWith("pnpm/")) return "pnpm";
+  if (execPath.includes("yarn") || userAgent.startsWith("yarn/")) return "yarn";
+  if (execPath.includes("bun") || userAgent.startsWith("bun/")) return "bun";
+  return "npm";
+}
+
+/**
+ * @param {string} packageName
+ * @param {string} version
+ * @param {"npm"|"pnpm"|"yarn"|"bun"} manager
+ * @returns {{ command: string, args: string[], display: string }}
+ */
+export function buildGlobalInstallSpec(packageName, version, manager = "npm") {
+  const spec = `${packageName}@${version}`;
+  switch (manager) {
+    case "pnpm":
+      return {
+        command: "pnpm",
+        args: ["add", "-g", spec],
+        display: `pnpm add -g ${spec}`
+      };
+    case "yarn":
+      return {
+        command: "yarn",
+        args: ["global", "add", spec],
+        display: `yarn global add ${spec}`
+      };
+    case "bun":
+      return {
+        command: "bun",
+        args: ["add", "-g", spec],
+        display: `bun add -g ${spec}`
+      };
+    default:
+      return {
+        command: "npm",
+        args: ["install", "-g", spec],
+        display: `npm install -g ${spec}`
+      };
+  }
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.packageName
+ * @param {string} options.cliVersion
+ * @param {boolean} [options.yes]
+ * @param {boolean} [options.json]
+ * @param {typeof fetchPublishedVersion} [options.fetchVersion]
+ * @param {typeof detectInstallPackageManager} [options.detectManager]
+ * @param {(cmd: string, args: string[]) => Promise<{ status: number, stdout: string, stderr: string }>} [options.runCommand]
+ */
+export async function runSelfUpdate({
+  packageName,
+  cliVersion,
+  yes = false,
+  json = false,
+  fetchVersion = fetchPublishedVersion,
+  detectManager = detectInstallPackageManager,
+  runCommand = defaultRunCommand
+} = {}) {
+  if (!packageName) throw new Error("packageName is required.");
+  if (!cliVersion) throw new Error("cliVersion is required.");
+
+  const latestVersion = await fetchVersion(packageName);
+  const cmp = compareSemver(cliVersion, latestVersion);
+  const manager = detectManager();
+  const install = buildGlobalInstallSpec(packageName, latestVersion, manager);
+
+  /** @type {"current"|"behind"|"ahead"|"unknown"} */
+  let state = "unknown";
+  if (cmp === 0) state = "current";
+  else if (cmp === -1) state = "behind";
+  else if (cmp === 1) state = "ahead";
+
+  const report = {
+    ok: true,
+    state,
+    installedVersion: cliVersion,
+    latestVersion,
+    packageName,
+    manager,
+    installCommand: install.display,
+    applied: false,
+    wrote: false
+  };
+
+  if (state === "current") {
+    report.nextAction = "Already up to date.";
+  } else if (state === "ahead") {
+    report.nextAction = `Local ${cliVersion} is newer than npm ${latestVersion}.`;
+  } else if (state === "behind") {
+    report.nextAction = yes
+      ? `Updating ${cliVersion} → ${latestVersion}…`
+      : `Update available: ${cliVersion} → ${latestVersion}. Run "${formatCliCommand("update --yes")}" or: ${install.display}`;
+  } else {
+    report.nextAction = `Could not compare versions. Install manually: ${install.display}`;
+  }
+
+  if (json) {
+    if (yes && state === "behind") {
+      const result = await runCommand(install.command, install.args);
+      report.applied = result.status === 0;
+      report.wrote = result.status === 0;
+      report.ok = result.status === 0;
+      report.installStatus = result.status;
+      report.stderr = result.stderr.trim() || undefined;
+      report.nextAction = result.status === 0
+        ? `Updated to ${latestVersion}.`
+        : `Install failed (exit ${result.status}). Try: ${install.display}`;
+    }
+    console.log(JSON.stringify(report));
+    return report;
+  }
+
+  console.log(commandHeader("update — Kairo Runtime"));
+  console.log(`Installed: ${cliVersion}`);
+  console.log(`Latest:    ${latestVersion}`);
+  console.log(`Status:    ${state}`);
+
+  if (state === "current") {
+    console.log("\nAlready up to date.");
+    return report;
+  }
+
+  if (state === "ahead") {
+    console.log(`\n${report.nextAction}`);
+    return report;
+  }
+
+  if (!yes) {
+    console.log(`\nUpdate available: ${cliVersion} → ${latestVersion}`);
+    console.log(`Run: ${formatCliCommand("update --yes")}`);
+    console.log(`Or:  ${install.display}`);
+    return report;
+  }
+
+  console.log(`\nInstalling ${install.display}…`);
+  const result = await runCommand(install.command, install.args);
+  report.applied = result.status === 0;
+  report.wrote = result.status === 0;
+  report.ok = result.status === 0;
+  report.installStatus = result.status;
+  if (result.stdout.trim()) console.log(result.stdout.trim());
+  if (result.stderr.trim()) console.error(result.stderr.trim());
+  if (result.status !== 0) {
+    throw new Error(`Self-update failed (exit ${result.status}). Try: ${install.display}`);
+  }
+  console.log(`\nUpdated to ${latestVersion}. Run "${formatCliCommand("--version")}" to confirm.`);
+  report.nextAction = `Updated to ${latestVersion}.`;
+  return report;
+}
+
+function defaultRunCommand(command, args) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: false,
+      env: process.env
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (error) => {
+      resolve({ status: 1, stdout, stderr: error.message });
+    });
+    child.on("close", (code) => {
+      resolve({ status: code ?? 1, stdout, stderr });
+    });
+  });
+}