@kal-elsam/kairo-runtime 0.2.2 → 0.2.3

package/README.md

@@ -24,13 +24,24 @@ commands) without depending on Pi as a runtime or adding a Pi adapter.
 
 ## Quick start
 
-Recommended entry — run Kairo Runtime in your terminal (interactive setup wizard in a TTY):
+Recommended entry — run Kairo Runtime in your terminal:
 
 ```bash
 npx @kal-elsam/kairo-runtime
+# or, after a global install:
+kairo
 ```
 
-Preview without writing anything:
+**First run** (no `~/.harness/state.json`): interactive onboarding → safe diagnosis →
+setup with confirmation → operations dashboard.
+
+**Later runs** (state present): operations dashboard with a stable purpose line and a
+contextual next step (configure, enable intelligence, launch a run, or review problems).
+
+Explicit commands and setup flags keep their current behavior (`kairo setup`,
+`kairo --dry-run`, `kairo shell`, non-TTY scripts, etc.).
+
+Preview setup without writing anything:
 
 ```bash
 npx @kal-elsam/kairo-runtime --dry-run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Gemini, Copilot, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",

package/src/cli.js

@@ -42,6 +42,11 @@ import {
   resolveSuggestedInvocation
 } from "./global/brand/cli.js";
 import { BRAND } from "./global/brand/index.js";
+import {
+  INITIAL_EXPERIENCE,
+  hasConfiguredGlobalState,
+  resolveInitialExperience
+} from "./global/initial-experience.js";
 
 export { resolveSuggestedInvocation };
 
@@ -50,7 +55,7 @@ const packageRoot = resolve(__dirname, "..");
 const SCOPES = new Set(["agent-global", "workspace"]);
 
 export async function runCli(argv) {
-  const { command, options } = parseArgs(argv);
+  const { command, options, isImplicitCommand } = parseArgs(argv);
   maybeWarnLegacyCli(process.argv, { json: options.json });
 
   if (options.help || command === "help") {
@@ -69,14 +74,22 @@ export async function runCli(argv) {
   const invoke = resolveSuggestedInvocation(packageManifest.name);
 
   switch (command) {
-    case "shell":
+    case "shell": {
+      const homeDir = resolveHomeDir();
+      const resolvedMode = resolveInitialExperience({
+        interactive: optionsWithPolicy.interactive,
+        isImplicitCommand,
+        hasGlobalState: hasConfiguredGlobalState(homeDir)
+      });
       await runOrchestratorShell({
         packageRoot,
         packageManifest,
         workspaceRoot: optionsWithPolicy.cwd,
-        interactive: optionsWithPolicy.interactive
+        interactive: optionsWithPolicy.interactive,
+        initialMode: resolvedMode ?? INITIAL_EXPERIENCE.DASHBOARD
       });
       return;
+    }
     case "orchestrator":
       await runOrchestratorDiagnostics({
         homeDir: resolveHomeDir(),
@@ -468,7 +481,7 @@ export function parseArgs(argv) {
     options.task = args.join(" ").trim();
   }
 
-  return { command, options };
+  return { command, options, isImplicitCommand: implicitCommand };
 }
 
 function parseComponentsAction(args, options) {
@@ -683,7 +696,8 @@ sections, components, backups, and drift repair under ~/.harness.
 Bootstrap: see README.md (curl install.sh or npx ${PACKAGE_NAME}).
 
 Usage:
-  ${cli}                              Interactive orchestrator shell (TTY)
+  ${cli}                              First run: onboarding → setup → dashboard (TTY).
+                                      Later: operations dashboard with next-step guidance.
   ${cli} --dry-run                      Setup dry-run (scriptable)
   ${cli} --version
   ${cli} shell                          Operations dashboard (TTY)
@@ -727,7 +741,8 @@ Scopes:
                           Explicit --scope=workspace only.
 
 Commands:
-  shell      Operations dashboard (TTY). Bare ${cli} opens this in TTY sessions.
+  shell      Operations dashboard (TTY). Bare ${cli} opens onboarding when ~/.harness/state.json
+             is missing, otherwise the dashboard. Explicit ${cli} shell always opens the dashboard.
   run        Launch a managed agent run with local audit trail.
   runs       List, inspect, or cancel agent runs under ~/.harness/runs/.
   orchestrator  Read-only capability registry diagnostics (--json supported).

package/src/global/brand/index.js

@@ -70,6 +70,16 @@ export const WIZARD_COPY = {
   coreOnlyLabel: "Core only (no components)"
 };
 
+/** First-run framing reused by onboarding → setup. */
+export const ONBOARDING_COPY = {
+  welcomeTitle: `Welcome to ${BRAND.displayName}`,
+  purpose:
+    `${BRAND.displayName} detects, configures, and coordinates the local agents you already use.`,
+  safety:
+    "Diagnosis is read-only. Nothing is modified until you confirm a plan.",
+  continueHint: "Press Enter to diagnose and configure · Esc to exit"
+};
+
 export function getAgentLabel(agentId) {
   return AGENT_LABELS[agentId] ?? agentId;
 }

package/src/global/dashboard-guidance.js

@@ -0,0 +1,66 @@
+import { formatCliCommand } from "./brand/cli.js";
+
+export const DASHBOARD_PURPOSE =
+  "Detects, configures, and coordinates local AI agents — no changes without confirmation.";
+
+export const NEXT_STEP_KINDS = {
+  CONFIGURE: "configure",
+  ENABLE_INTELLIGENCE: "enable_intelligence",
+  LAUNCH: "launch",
+  REVIEW: "review"
+};
+
+export function formatDashboardPurpose() {
+  return DASHBOARD_PURPOSE;
+}
+
+/**
+ * Contextual next step from existing diagnostics + dashboard snapshot.
+ * Priority: configure → review problems → enable intelligence → launch.
+ */
+export function resolveDashboardRecommendation({
+  hasGlobalState = false,
+  diagnostics = null,
+  dashboard = null
+} = {}) {
+  const summary = diagnostics?.diagnostics ?? { detected: 0, errors: 0 };
+  const intelligence = diagnostics?.intelligence?.summary;
+  const launchableCount = (dashboard?.providers ?? []).filter((entry) => entry.launchable).length;
+  const hasErrors = (summary.errors ?? 0) > 0;
+  const hasProblemRecommendation = (diagnostics?.recommendations ?? []).some((line) =>
+    /error|fix|drift|not detected|failed|problem/i.test(line)
+  );
+
+  if (!hasGlobalState || (summary.detected ?? 0) === 0) {
+    return {
+      kind: NEXT_STEP_KINDS.CONFIGURE,
+      message: `Configure the local environment with ${formatCliCommand("setup")}.`
+    };
+  }
+
+  if (hasErrors || hasProblemRecommendation) {
+    return {
+      kind: NEXT_STEP_KINDS.REVIEW,
+      message: "Review diagnostics for problems before launching a run."
+    };
+  }
+
+  if (!intelligence?.localAvailable && !intelligence?.cloudAuthenticated) {
+    return {
+      kind: NEXT_STEP_KINDS.ENABLE_INTELLIGENCE,
+      message: "Enable intelligence: start Ollama or set OPENROUTER_API_KEY, then retry."
+    };
+  }
+
+  if (launchableCount > 0) {
+    return {
+      kind: NEXT_STEP_KINDS.LAUNCH,
+      message: "Launch a supervised run from the menu or with kairo run."
+    };
+  }
+
+  return {
+    kind: NEXT_STEP_KINDS.REVIEW,
+    message: "Review diagnostics for problems before launching a run."
+  };
+}

package/src/global/initial-experience.js

@@ -0,0 +1,34 @@
+import { existsSync } from "node:fs";
+import { harnessHomePaths } from "./paths.js";
+
+export const INITIAL_EXPERIENCE = {
+  ONBOARDING: "onboarding",
+  DASHBOARD: "dashboard"
+};
+
+/**
+ * First-run marker is ~/.harness/state.json only.
+ * profile.json does not participate in this decision.
+ */
+export function hasConfiguredGlobalState(homeDir) {
+  return existsSync(harnessHomePaths(homeDir).statePath);
+}
+
+/**
+ * Pure resolver for the interactive bare-entry experience.
+ * Returns null when CLI should keep existing non-onboarding paths
+ * (non-TTY, explicit commands, setup flags already routed elsewhere).
+ */
+export function resolveInitialExperience({
+  interactive = false,
+  isImplicitCommand = false,
+  hasGlobalState = false
+} = {}) {
+  if (!interactive || !isImplicitCommand) {
+    return null;
+  }
+
+  return hasGlobalState
+    ? INITIAL_EXPERIENCE.DASHBOARD
+    : INITIAL_EXPERIENCE.ONBOARDING;
+}

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

@@ -27,6 +27,10 @@ import {
   selectRunFromList,
   shiftMenuIndex
 } from "./orchestrator-state.js";
+import {
+  formatDashboardPurpose,
+  resolveDashboardRecommendation
+} from "../dashboard-guidance.js";
 
 const COLORS = {
   accent: "cyan",
@@ -42,6 +46,7 @@ export function OrchestratorApp({
   packageName,
   packageRoot,
   cliVersion,
+  hasGlobalState = false,
   onComplete
 }) {
   const { exit } = useApp();
@@ -361,13 +366,14 @@ export function OrchestratorApp({
 
   return React.createElement(Box, { flexDirection: "column" },
     React.createElement(Text, { bold: true, color: COLORS.accent }, `${BRAND.displayName} runtime`),
-    React.createElement(Text, { color: COLORS.muted }, "Launch · supervise · audit agent runs"),
+    React.createElement(Text, { color: COLORS.muted }, formatDashboardPurpose()),
     statusMessage && React.createElement(Text, { color: COLORS.success }, statusMessage),
     React.createElement(Text, null, ""),
     renderView({
       view,
       dashboard,
       diagnostics,
+      hasGlobalState,
       menuIndex,
       listIndex,
       launchStep,
@@ -387,6 +393,7 @@ function renderView({
   view,
   dashboard,
   diagnostics,
+  hasGlobalState,
   menuIndex,
   listIndex,
   launchStep,
@@ -398,8 +405,16 @@ function renderView({
   selectedEvents
 }) {
   switch (view) {
-    case ORCHESTRATOR_VIEWS.HOME:
+    case ORCHESTRATOR_VIEWS.HOME: {
+      const nextStep = resolveDashboardRecommendation({
+        hasGlobalState,
+        diagnostics,
+        dashboard
+      });
       return React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Text, { bold: true }, "Next"),
+        React.createElement(Text, { color: COLORS.accent }, nextStep.message),
+        React.createElement(Text, null, ""),
         React.createElement(Text, { bold: true }, "Operations"),
         ORCHESTRATOR_MENU.map((item, index) =>
           React.createElement(Text, {
@@ -413,6 +428,7 @@ function renderView({
         formatDashboardSnapshot(dashboard)
           .map((line) => React.createElement(Text, { key: line }, line))
       );
+    }
     case ORCHESTRATOR_VIEWS.ACTIVE_RUNS:
       return React.createElement(Box, { flexDirection: "column" },
         React.createElement(Text, { bold: true }, "Active runs"),

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

@@ -8,6 +8,7 @@ export async function runOrchestratorInk({
   packageRoot,
   packageName,
   cliVersion,
+  hasGlobalState = false,
   renderImpl = render
 }) {
   return new Promise((resolve) => {
@@ -18,6 +19,7 @@ export async function runOrchestratorInk({
         packageRoot,
         packageName,
         cliVersion,
+        hasGlobalState,
         onComplete: resolve
       })
     );

package/src/global/ink/run-setup-ink.js

@@ -15,6 +15,7 @@ export async function runSetupInk({
   packageName,
   cliVersion,
   dryRun = false,
+  onboarding = false,
   preflight = true,
   yes = false,
   confirm = false,
@@ -33,6 +34,7 @@ export async function runSetupInk({
         packageName,
         cliVersion,
         dryRun,
+        onboarding,
         onComplete: resolve
       })
     );

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

@@ -56,8 +56,8 @@ function Footer({ children }) {
   return React.createElement(Text, { dimColor: true }, children);
 }
 
-function Splash({ compact }) {
-  const lines = formatInkSplashLines({ compact });
+function Splash({ compact, onboarding = false }) {
+  const lines = formatInkSplashLines({ compact, onboarding });
   const logoLineCount = compact ? BRAND.compactLogo.length : BRAND.asciiLogo.length;
 
   return React.createElement(Box, { flexDirection: "column", marginBottom: 1 },
@@ -71,7 +71,7 @@ function Splash({ compact }) {
       if (line === BRAND.tagline) {
         return React.createElement(Text, { key: `line-${index}`, color: INK_COLORS.muted }, line);
       }
-      if (line === BRAND.splashHint) {
+      if (line === BRAND.splashHint || line.includes("Esc to exit") || line.includes("Press Enter")) {
         return React.createElement(Text, { key: `line-${index}`, dimColor: true }, line);
       }
       if (line === "") {
@@ -89,6 +89,7 @@ export function SetupApp({
   packageName,
   cliVersion,
   dryRun = false,
+  onboarding = false,
   onComplete
 }) {
   const { exit } = useApp();
@@ -243,7 +244,10 @@ export function SetupApp({
   const detectPanel = formatInkDetectPanel({ adapters, detected });
 
   return React.createElement(Box, { flexDirection: "column" },
-    step === SETUP_STEPS.SPLASH && React.createElement(Splash, { compact: useCompactSplash }),
+    step === SETUP_STEPS.SPLASH && React.createElement(Splash, {
+      compact: useCompactSplash,
+      onboarding
+    }),
     step !== SETUP_STEPS.SPLASH && React.createElement(Header),
     step === SETUP_STEPS.DETECT && React.createElement(Panel, { title: WIZARD_COPY.detectTitle },
       detectPanel.split("\n")

package/src/global/ink/setup-state.js

@@ -1,4 +1,12 @@
-import { AGENT_HINTS, BRAND, formatCliCommand, getAgentLabel, PREFERRED_CLI, WIZARD_COPY } from "../brand/index.js";
+import {
+  AGENT_HINTS,
+  BRAND,
+  ONBOARDING_COPY,
+  formatCliCommand,
+  getAgentLabel,
+  PREFERRED_CLI,
+  WIZARD_COPY
+} from "../brand/index.js";
 import { formatAgentMultiselectHint } from "../clack/theme.js";
 
 export const SETUP_STEPS = {
@@ -16,8 +24,22 @@ export function shouldUseCompactSplashLogo(columns) {
   return columns < fullWidth + 4;
 }
 
-export function formatInkSplashLines({ compact = false } = {}) {
+export function formatInkSplashLines({ compact = false, onboarding = false } = {}) {
   const logo = compact ? BRAND.compactLogo : BRAND.asciiLogo;
+  if (onboarding) {
+    return [
+      ...logo,
+      "",
+      BRAND.name,
+      BRAND.tagline,
+      "",
+      ONBOARDING_COPY.purpose,
+      ONBOARDING_COPY.safety,
+      "",
+      ONBOARDING_COPY.continueHint
+    ];
+  }
+
   return [
     ...logo,
     "",

package/src/global/orchestrator.js

@@ -5,6 +5,11 @@ import { runOrchestratorInk as defaultRunOrchestratorInk } from "./ink/run-orche
 import { formatCliCommand } from "./brand/cli.js";
 import { BRAND } from "./brand/index.js";
 import { buildReadOnlyDiagnostics, shouldExecutePlan } from "./action-planner.js";
+import { runHarnessSetup as defaultRunHarnessSetup } from "./setup.js";
+import {
+  INITIAL_EXPERIENCE,
+  hasConfiguredGlobalState
+} from "./initial-experience.js";
 
 export { canUseOrchestratorShell };
 
@@ -23,7 +28,10 @@ export async function runOrchestratorShell({
   packageManifest,
   workspaceRoot,
   interactive = Boolean(input.isTTY && output.isTTY),
-  runOrchestratorInkImpl = defaultRunOrchestratorInk
+  initialMode = INITIAL_EXPERIENCE.DASHBOARD,
+  shellCapable = canUseOrchestratorShell({ interactive }),
+  runOrchestratorInkImpl = defaultRunOrchestratorInk,
+  runHarnessSetupImpl = defaultRunHarnessSetup
 }) {
   if (!interactive) {
     throw new Error(
@@ -31,19 +39,44 @@ export async function runOrchestratorShell({
     );
   }
 
-  if (!canUseOrchestratorShell({ interactive })) {
+  if (!shellCapable) {
     throw new Error(
       `Interactive shell requires a capable TTY. Use ${formatCliCommand("runs list")} or explicit commands.`
     );
   }
 
   const homeDir = resolveHomeDir();
+  let setupOutcome = null;
+
+  if (initialMode === INITIAL_EXPERIENCE.ONBOARDING) {
+    setupOutcome = await runHarnessSetupImpl({
+      packageRoot,
+      packageName: packageManifest.name,
+      cliVersion: packageManifest.version,
+      homeDir,
+      workspaceRoot,
+      onboarding: true,
+      interactive: true
+    });
+
+    if (setupOutcome?.cancelled) {
+      return {
+        cancelled: true,
+        wrote: false,
+        action: null,
+        initialMode,
+        setup: setupOutcome
+      };
+    }
+  }
+
   const outcome = await runOrchestratorInkImpl({
     homeDir,
     workspaceRoot,
     packageRoot,
     packageName: packageManifest.name,
-    cliVersion: packageManifest.version
+    cliVersion: packageManifest.version,
+    hasGlobalState: hasConfiguredGlobalState(homeDir)
   });
 
   if (outcome.error) {
@@ -52,8 +85,10 @@ export async function runOrchestratorShell({
 
   return {
     cancelled: Boolean(outcome.cancelled),
-    wrote: false,
-    action: outcome.action ?? null
+    wrote: Boolean(setupOutcome && !setupOutcome.cancelled),
+    action: outcome.action ?? null,
+    initialMode,
+    setup: setupOutcome
   };
 }
 

package/src/global/setup.js

@@ -1,5 +1,5 @@
 import { stdin as input, stdout as output } from "node:process";
-import { BRAND } from "./brand/index.js";
+import { BRAND, ONBOARDING_COPY } from "./brand/index.js";
 import { installGlobalHarness } from "./global-installer.js";
 import {
   assertExplicitApplyConsent,
@@ -59,6 +59,7 @@ export async function runHarnessSetup({
   confirmExplicit = false,
   json = false,
   simple = false,
+  onboarding = false,
   interactive = Boolean(input.isTTY && output.isTTY),
   createPrompt = createReadlinePrompt,
   runSetupInkImpl = defaultRunSetupInk,
@@ -76,7 +77,7 @@ export async function runHarnessSetup({
   let usedInk = false;
 
   if (!useInk && !useWizard) {
-    printSetupIntro({ homeDir });
+    printSetupIntro({ homeDir, onboarding });
   }
 
   const setupUiArgs = {
@@ -86,6 +87,7 @@ export async function runHarnessSetup({
     packageName,
     cliVersion,
     dryRun,
+    onboarding,
     preflight,
     yes,
     confirm,
@@ -254,11 +256,17 @@ export async function runHarnessSetup({
   return { cancelled: false, result, usedWizard, usedInk };
 }
 
-function printSetupIntro({ homeDir }) {
+function printSetupIntro({ homeDir, onboarding = false }) {
   const detected = detectInstalledAdapters({ homeDir });
 
-  console.log(`${BRAND.displayName} setup — local AI ecosystem configurator`);
-  console.log("Configures and coordinates local agents. Does not install the AI apps themselves.");
+  if (onboarding) {
+    console.log(ONBOARDING_COPY.welcomeTitle);
+    console.log(ONBOARDING_COPY.purpose);
+    console.log(ONBOARDING_COPY.safety);
+  } else {
+    console.log(`${BRAND.displayName} setup — local AI ecosystem configurator`);
+    console.log("Configures and coordinates local agents. Does not install the AI apps themselves.");
+  }
   console.log("");
   console.log(`Detected agents: ${detected.join(", ") || "none"}`);
   console.log(`Supported agents: ${GLOBAL_AGENT_IDS.join(", ")}`);