@cruxy/cli 0.6.0 → 0.7.0

package/README.md

@@ -16,14 +16,26 @@ an approval gate before anything touches disk.
 ```bash
 npm install -g @cruxy/cli
 
-export CRUXY_API_KEY=cxy_live_...   # from app.cruxy.in
+cruxy run "explain this codebase"   # first run guides you through setup
+```
+
+On your first interactive run with no key, cruxy walks you through getting one,
+validates it, and saves it to `~/.cruxy` (owner-only) — no env var needed. You
+can also run setup on demand:
 
-cruxy run "explain this codebase"   # one-shot
-cruxy run                           # interactive session
+```bash
+cruxy login                         # set or replace your API key
+cruxy init                          # key + a project CRUXY.md + a first run
+export CRUXY_API_KEY=cxy_live_...   # …or just use an env var (always wins)
 ```
 
 ## Features
 
+- **Onboarding** — a guided first run (`cruxy login` / `cruxy init` on demand):
+  get a key, validate it live, and save it to `~/.cruxy/credentials.json`
+  (`0600`) — never to `config.json`, the project, or env files. Keys resolve
+  env → credentials store. Non-interactive runs stay fail-loud
+  (`CRUXY_E_AUTH_MISSING_KEY`), never blocking on input.
 - **Tools** — `read_file`, `write_file`, `edit_file`, `glob`, `list_files`,
   `grep_files`, `run_command`, `git_status`, `apply_patch`, `search_codebase`,
   `list_skills`, `load_skill`, `create_pull_request`.
@@ -46,6 +58,11 @@ cruxy run                           # interactive session
   validated, and never auto-executed.
 - **Agent** — streaming output, multi-turn interactive sessions, context
   compaction, and awareness of git state and project instructions (`CRUXY.md`).
+- **Plan mode** (opt-in: `cruxy run --plan`, `/plan`, or `agent.planMode`) — the
+  agent proposes a structured, step-by-step plan; you approve it once, then it
+  executes with live per-step status. Approving consents to the _shape_ of the
+  work — every action still passes the approval gate, and destructive/ungrantable
+  actions always re-confirm even after approval.
 - **Safety** — a single approval gate with diff previews that fails closed;
   read-only tools never prompt; file access is confined to the project root;
   shell commands run bounded.
@@ -101,19 +118,19 @@ steps, and a stable code (e.g. `CRUXY_E_GATEWAY_UNREACHABLE`). Pass `--verbose`
 `NO_COLOR` disables color. Exit codes are stable per category, so scripts can
 branch on them:
 
-| Exit | Category   | Example codes                                                                                                      |
-| ---- | ---------- | ------------------------------------------------------------------------------------------------------------------ |
-| `0`  | success    | —                                                                                                                  |
-| `1`  | internal   | `CRUXY_E_INTERNAL`                                                                                                 |
-| `2`  | usage      | `CRUXY_E_USAGE`, `CRUXY_E_CONFIG_KEY_UNKNOWN`, `CRUXY_E_PROVIDER_UNSUPPORTED`, `CRUXY_E_GIT_PROTECTED_BRANCH`      |
-| `3`  | config     | `CRUXY_E_CONFIG_PARSE`, `CRUXY_E_CONFIG_INVALID`                                                                   |
-| `4`  | auth       | `CRUXY_E_AUTH_MISSING_KEY`, `CRUXY_E_AUTH_INVALID`, `CRUXY_E_FORGE_AUTH`                                           |
-| `5`  | network    | `CRUXY_E_GATEWAY_UNREACHABLE`, `CRUXY_E_GIT_PUSH_FAILED`                                                           |
-| `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`, `CRUXY_E_FORGE_API` |
-| `7`  | filesystem | `CRUXY_E_FILE_NOT_FOUND`, `CRUXY_E_PERMISSION_DENIED`, `CRUXY_E_PATH_ESCAPE`                                       |
-| `8`  | index      | `CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE`, `CRUXY_E_INDEX_STORE_UNAVAILABLE`, `CRUXY_E_INDEX_FAILED`                    |
-| `9`  | skill      | `CRUXY_E_SKILL_INVALID`, `CRUXY_E_SKILL_NOT_FOUND`                                                                 |
-| `10` | approval   | `CRUXY_E_APPROVAL_REQUIRED`                                                                                        |
+| Exit | Category   | Example codes                                                                                                                                                        |
+| ---- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0`  | success    | —                                                                                                                                                                    |
+| `1`  | internal   | `CRUXY_E_INTERNAL`                                                                                                                                                   |
+| `2`  | usage      | `CRUXY_E_USAGE`, `CRUXY_E_CONFIG_KEY_UNKNOWN`, `CRUXY_E_PROVIDER_UNSUPPORTED`, `CRUXY_E_GIT_PROTECTED_BRANCH`, `CRUXY_E_PLAN_INVALID`, `CRUXY_E_PLAN_REVISION_LIMIT` |
+| `3`  | config     | `CRUXY_E_CONFIG_PARSE`, `CRUXY_E_CONFIG_INVALID`                                                                                                                     |
+| `4`  | auth       | `CRUXY_E_AUTH_MISSING_KEY`, `CRUXY_E_AUTH_INVALID`, `CRUXY_E_FORGE_AUTH`                                                                                             |
+| `5`  | network    | `CRUXY_E_GATEWAY_UNREACHABLE`, `CRUXY_E_GIT_PUSH_FAILED`                                                                                                             |
+| `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`, `CRUXY_E_FORGE_API`                                                   |
+| `7`  | filesystem | `CRUXY_E_FILE_NOT_FOUND`, `CRUXY_E_PERMISSION_DENIED`, `CRUXY_E_PATH_ESCAPE`                                                                                         |
+| `8`  | index      | `CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE`, `CRUXY_E_INDEX_STORE_UNAVAILABLE`, `CRUXY_E_INDEX_FAILED`                                                                      |
+| `9`  | skill      | `CRUXY_E_SKILL_INVALID`, `CRUXY_E_SKILL_NOT_FOUND`                                                                                                                   |
+| `10` | approval   | `CRUXY_E_APPROVAL_REQUIRED`, `CRUXY_E_PLAN_APPROVAL_REQUIRED`                                                                                                        |
 
 The LLM client is [`@cruxy/sdk`](https://www.npmjs.com/package/@cruxy/sdk) —
 provider-agnostic, built over `fetch`, with no vendor SDKs.

package/dist/agent/loop.d.ts

@@ -30,6 +30,8 @@ export interface RunAgentArgs {
     } | null;
     /** Project instructions (e.g. from CRUXY.md) folded into the system prompt. */
     projectInstructions?: string | null;
+    /** Plan mode's propose phase (C.31): inject the plan-first system directive. */
+    planMode?: boolean;
 }
 export interface AgentResult {
     /** The full conversation, including assistant tool calls and tool results. */

package/dist/agent/loop.js

@@ -32,6 +32,7 @@ export async function runAgent(args) {
             .map((tool) => ({ name: tool.name, description: tool.description })),
         git: args.git ?? null,
         projectInstructions: args.projectInstructions ?? null,
+        planMode: args.planMode ?? false,
     });
     let iterations = 0;
     for (let i = 0; i < maxIterations; i++) {

package/dist/agent/prompts.d.ts

@@ -28,6 +28,8 @@ export interface PromptContext {
     } | null;
     /** Optional extra instructions (e.g. from a project CRUXY.md). */
     projectInstructions?: string | null;
+    /** Plan mode's propose phase (C.31): inject the plan-first directive. */
+    planMode?: boolean;
 }
 /** Assemble the full system prompt for a session. */
 export declare function buildSystemPrompt(ctx: PromptContext): string;

package/dist/agent/prompts.js

@@ -6,6 +6,10 @@
  * dynamic environment block, so the model always knows where it is, what it
  * can do, and how it's expected to behave.
  */
+/** The plan-mode directive, injected during the propose phase only. */
+const PLAN_MODE_SECTION = `## Plan mode
+You are in plan mode. Do NOT edit files, run commands, or take any side-effecting action yet.
+First investigate with the read-only tools if you need to, then call \`submit_plan\` with an ordered list of steps — each with a title, a one-line rationale, and a kind (read | mutate | destructive). Cover the whole task; keep steps concrete and minimal. After you call \`submit_plan\`, stop and end your turn — the user reviews and approves the plan before you execute it.`;
 /**
  * The static core of cruxy's behaviour. Phrased as direct instruction to the
  * model. Keep this tight — every line earns its place; vague prose dilutes the
@@ -74,6 +78,8 @@ export function buildSystemPrompt(ctx) {
     const approval = "Side-effecting actions (file writes, shell commands) require the user's approval; destructive or irreversible actions are flagged distinctly.";
     const core = CORE.replace("${APPROVAL_CLAUSE}", approval);
     const sections = [core, renderEnvironment(ctx), renderTools(ctx.tools)];
+    if (ctx.planMode)
+        sections.push(PLAN_MODE_SECTION);
     if (ctx.projectInstructions?.trim()) {
         sections.push(`## Project instructions\nThe following came from this project's configuration; honor it unless it conflicts with the rules above:\n\n${ctx.projectInstructions.trim()}`);
     }

package/dist/agent/session.d.ts

@@ -3,6 +3,17 @@ import type { CruxyConfig } from "../config/index.js";
 import type { ToolContext } from "../tools/index.js";
 import type { ToolRegistry } from "../tools/index.js";
 import { type AgentResult } from "./loop.js";
+/**
+ * Plan-mode turn runner (C.31), injected so the agent package doesn't depend on
+ * the plan package. When plan mode is on, `send` delegates the whole turn to
+ * this instead of a single `runAgent` call. Receives the running history (with
+ * the user turn already appended) and returns the extended history to adopt.
+ */
+export type PlanRunner = (args: {
+    messages: Message[];
+    projectInstructions: string | null;
+    onText?: (delta: string) => void;
+}) => Promise<AgentResult>;
 export interface SessionArgs {
     /** A constructed provider to stream from. */
     provider: Provider;
@@ -19,6 +30,10 @@ export interface SessionArgs {
     } | null;
     /** Project instructions (e.g. CRUXY.md) folded into every turn's system prompt. */
     projectInstructions?: string | null;
+    /** Start in plan mode (C.31). Toggleable at runtime via `setPlanMode`. */
+    planMode?: boolean;
+    /** The plan-mode turn runner; required for plan mode to actually engage. */
+    planRunner?: PlanRunner;
 }
 /**
  * Estimate the token footprint of a message list with a cheap chars/4 heuristic
@@ -46,7 +61,16 @@ export declare class Session {
     private readonly args;
     /** Mutable so `/reload` can refresh CRUXY.md mid-session. */
     private projectInstructions;
+    /** Mutable so `/plan` can toggle plan mode mid-session. */
+    private planMode;
     constructor(args: SessionArgs);
+    /** Whether plan mode is currently on. */
+    getPlanMode(): boolean;
+    /**
+     * Toggle plan mode. Only takes effect when a `planRunner` was wired (built by
+     * the session factory); without one, plan mode stays off.
+     */
+    setPlanMode(enabled: boolean): void;
     /**
      * Run one user turn: append the prompt, compact if the history has grown past
      * the threshold, drive the agent loop over the full history, adopt the

package/dist/agent/session.js

@@ -49,9 +49,25 @@ export class Session {
     args;
     /** Mutable so `/reload` can refresh CRUXY.md mid-session. */
     projectInstructions;
+    /** Mutable so `/plan` can toggle plan mode mid-session. */
+    planMode;
     constructor(args) {
         this.args = args;
         this.projectInstructions = args.projectInstructions ?? null;
+        // Plan mode requires a wired runner; without one it stays off (no half-on
+        // state where the plan directive is injected but nothing orchestrates it).
+        this.planMode = (args.planMode ?? false) && args.planRunner !== undefined;
+    }
+    /** Whether plan mode is currently on. */
+    getPlanMode() {
+        return this.planMode;
+    }
+    /**
+     * Toggle plan mode. Only takes effect when a `planRunner` was wired (built by
+     * the session factory); without one, plan mode stays off.
+     */
+    setPlanMode(enabled) {
+        this.planMode = enabled && this.args.planRunner !== undefined;
     }
     /**
      * Run one user turn: append the prompt, compact if the history has grown past
@@ -65,13 +81,23 @@ export class Session {
         this.messages.push({ role: "user", content: userPrompt });
         // Compact *before* the agent call so the turn runs against a bounded history.
         await this.maybeCompact();
-        const result = await runAgent({
-            messages: this.messages,
-            ...this.args,
-            // After the spread so a mid-session `/reload` wins over the initial value.
-            projectInstructions: this.projectInstructions,
-            onText,
-        });
+        // Plan mode (C.31) delegates the whole turn to the injected runner: propose a
+        // plan, approve/revise, then execute step-by-step. Falls back to the normal
+        // single-shot loop when off or unwired, so existing behavior is untouched.
+        const result = this.planMode && this.args.planRunner
+            ? await this.args.planRunner({
+                messages: this.messages,
+                projectInstructions: this.projectInstructions,
+                onText,
+            })
+            : await runAgent({
+                messages: this.messages,
+                ...this.args,
+                // After the spread so a mid-session `/reload` wins over the initial value.
+                projectInstructions: this.projectInstructions,
+                planMode: false, // the plan directive belongs only to the runner's propose phase
+                onText,
+            });
         this.messages = result.messages;
         this.usage.input_tokens += result.usage.input_tokens;
         this.usage.output_tokens += result.usage.output_tokens;

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+/**
+ * `cruxy init` — set up a project (U.6): ensure a key (acquired only if missing),
+ * offer to scaffold a project `CRUXY.md`, and offer a first-win demo run. Like
+ * `login`, it's interactive-only.
+ */
+export declare function initCommand(): Command;

package/dist/cli/commands/init.js

@@ -0,0 +1,40 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { logger } from "../../utils/logger.js";
+import { loadConfig } from "../../config/index.js";
+import { createDefaultDeps, defaultOnboardingIO, runOnboarding, } from "../../onboarding/index.js";
+import { runFirstWinTask } from "../onboard.js";
+/**
+ * `cruxy init` — set up a project (U.6): ensure a key (acquired only if missing),
+ * offer to scaffold a project `CRUXY.md`, and offer a first-win demo run. Like
+ * `login`, it's interactive-only.
+ */
+export function initCommand() {
+    return new Command("init")
+        .description("set up cruxy in this project (key + CRUXY.md + a first run)")
+        .action(async () => {
+        if (!process.stdin.isTTY) {
+            logger.print(pc.dim("cruxy init is interactive — run it in a terminal, or export your key as an environment variable."));
+            process.exitCode = 1;
+            return;
+        }
+        const cwd = process.cwd();
+        const { config } = loadConfig();
+        const result = await runOnboarding({
+            provider: config.model.provider,
+            mode: "init",
+            offerScaffold: true,
+            offerFirstWin: true,
+            io: defaultOnboardingIO(),
+            deps: createDefaultDeps({
+                config,
+                cwd,
+                runTask: (prompt) => runFirstWinTask(config, cwd, prompt),
+            }),
+        });
+        if (!result.completed) {
+            logger.print(pc.dim("setup not completed — run `cruxy init` again to resume."));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/login.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+/**
+ * `cruxy login` — set or replace the API key on demand (U.6). Runs the key step
+ * of onboarding (always, even if a key already resolves — this is how you
+ * re-key / switch), validates it live, and persists it to the credentials store.
+ * Non-interactive invocations fail loud rather than hang.
+ */
+export declare function loginCommand(): Command;

package/dist/cli/commands/login.js

@@ -0,0 +1,36 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { logger } from "../../utils/logger.js";
+import { loadConfig } from "../../config/index.js";
+import { createDefaultDeps, defaultOnboardingIO, runOnboarding, } from "../../onboarding/index.js";
+/**
+ * `cruxy login` — set or replace the API key on demand (U.6). Runs the key step
+ * of onboarding (always, even if a key already resolves — this is how you
+ * re-key / switch), validates it live, and persists it to the credentials store.
+ * Non-interactive invocations fail loud rather than hang.
+ */
+export function loginCommand() {
+    return new Command("login")
+        .description("set or replace your API key (validated, saved to ~/.cruxy)")
+        .action(async () => {
+        if (!process.stdin.isTTY) {
+            logger.print(pc.dim("cruxy login is interactive — run it in a terminal, or export your key as an environment variable."));
+            process.exitCode = 1;
+            return;
+        }
+        const { config } = loadConfig();
+        const result = await runOnboarding({
+            provider: config.model.provider,
+            mode: "login",
+            forceKey: true,
+            offerFirstWin: false,
+            offerScaffold: false,
+            io: defaultOnboardingIO(),
+            deps: createDefaultDeps({ config, cwd: process.cwd() }),
+        });
+        if (!result.completed) {
+            logger.print(pc.dim("login not completed."));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/run.js

@@ -1,20 +1,18 @@
 import { Command } from "commander";
 import pc from "picocolors";
-import { createProvider } from "@cruxy/sdk";
 import { logger } from "../../utils/logger.js";
-import { loadConfig, resolveApiKey, loadProjectInstructions, } from "../../config/index.js";
+import { loadConfig, resolveApiKey } from "../../config/index.js";
 import { authMissingKey, usageError } from "../../errors/index.js";
-import { ApprovalService } from "../../approval/index.js";
-import { buildDefaultRegistry } from "../../tools/index.js";
-import { Session } from "../../agent/index.js";
 import { runInteractive } from "../repl.js";
 import { createStreamPrinter } from "../stream-print.js";
-import { getGitInfo } from "../../utils/git.js";
+import { buildAgentSession } from "../session-factory.js";
+import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
 export function runCommand() {
     return new Command("run")
         .description("run cruxy on a prompt (one-shot), or with no prompt for an interactive session")
         .argument("[prompt...]", "the task for cruxy to perform (omit for interactive)")
-        .action(async (promptParts) => {
+        .option("--plan", "plan mode: propose a step-by-step plan for approval before executing")
+        .action(async (promptParts, opts) => {
         const prompt = promptParts.join(" ").trim();
         const interactive = prompt === "";
         // No prompt and stdin isn't a terminal: there's no way to read input and
@@ -23,45 +21,36 @@ export function runCommand() {
             throw usageError("cruxy run needs a prompt when stdin is not a terminal", ['provide a task, e.g. cruxy run "fix the failing test"']);
         }
         const { config, sources } = loadConfig();
-        const apiKey = resolveApiKey(config.model.provider);
+        let apiKey = resolveApiKey(config.model.provider);
         logger.info(pc.dim(`model:   ${config.model.provider}/${config.model.model}`));
         logger.info(pc.dim(`config:  ${sources.project ?? sources.global ?? "defaults"}`));
+        // First-run with no key (and a TTY) → guided onboarding instead of the
+        // dead-end auth error. The first-win demo is offered only in the no-prompt
+        // (REPL) path; with a real prompt, that prompt IS the first win.
         if (!apiKey) {
-            throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
+            const onboarding = maybeRunOnboarding(config, {
+                ttyInteractive: Boolean(process.stdin.isTTY),
+                offerFirstWin: interactive,
+                cwd: process.cwd(),
+            });
+            if (onboarding === null) {
+                // Not a first run (non-TTY, or onboarded then key removed) → fail loud.
+                throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
+            }
+            const result = await onboarding;
+            if (!result.completed) {
+                // Aborted/failed mid-setup — guidance already shown; exit cleanly.
+                logger.print(pc.dim("run `cruxy login` to finish setup."));
+                return;
+            }
+            apiKey = result.apiKey ?? resolveApiKey(config.model.provider);
+            if (!apiKey) {
+                throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
+            }
         }
-        const provider = createProvider({
-            provider: config.model.provider,
-            apiKey,
-            model: config.model.model,
-            maxTokens: config.model.maxTokens,
-            temperature: config.model.temperature,
-            gatewayUrl: config.cruxy.gatewayUrl,
-        });
-        const registry = buildDefaultRegistry();
-        // The approval gate. Default-deny, risk-tiered, scoped session allowlist;
-        // no global skip flag (the policy seam lives in src/approval). When stdin
-        // isn't a TTY, a side-effecting action fails with CRUXY_E_APPROVAL_REQUIRED
-        // rather than being auto-approved.
-        const approval = new ApprovalService({
-            cwd: process.cwd(),
-            interactive: Boolean(process.stdin.isTTY),
-        });
-        const ctx = {
-            cwd: process.cwd(),
-            config,
-            logger,
-            requestApproval: (action) => approval.requestApproval(action),
-        };
-        const projectInstructions = loadProjectInstructions(process.cwd());
-        const git = getGitInfo(process.cwd());
-        const session = new Session({
-            provider,
-            registry,
-            config,
-            ctx,
-            git,
-            projectInstructions,
-        });
+        // Plan mode is opt-in: --plan flag overrides the config default.
+        const planMode = opts.plan ?? config.agent.planMode;
+        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode);
         if (interactive) {
             await runInteractive(session);
             return;
@@ -80,14 +69,3 @@ export function runCommand() {
             `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
     });
 }
-/** Environment variable that holds the API key for a provider. */
-function apiKeyEnvVar(provider) {
-    switch (provider) {
-        case "anthropic":
-            return "ANTHROPIC_API_KEY";
-        case "openai":
-            return "OPENAI_API_KEY";
-        default:
-            return "CRUXY_API_KEY";
-    }
-}

package/dist/cli/onboard.d.ts

@@ -0,0 +1,25 @@
+import type { CruxyConfig } from "../config/index.js";
+import { type OnboardingResult } from "../onboarding/index.js";
+/**
+ * CLI-layer glue between the entry points and the onboarding module (U.6). Keeps
+ * `run`/`program`/`login`/`init` thin: they decide *when* to onboard; this builds
+ * the production wiring (live validation, credential persistence, first-win run).
+ */
+/** The env var that holds the key for a provider (for the fail-loud message). */
+export declare function apiKeyEnvVar(provider: string): string;
+/** Run one first-win task end-to-end against the just-saved key. */
+export declare function runFirstWinTask(config: CruxyConfig, cwd: string, prompt: string): Promise<void>;
+export interface MaybeOnboardOptions {
+    /** Whether stdin is a TTY (the gate). */
+    ttyInteractive: boolean;
+    /** Offer the first-win demo run (no real task queued). */
+    offerFirstWin: boolean;
+    cwd: string;
+}
+/**
+ * Run the guided first-run flow **iff** this is a first run; otherwise return
+ * `null` so the caller can fall back (fail loud, or show a banner). Never throws
+ * for an aborted setup — `result.completed` is `false` and the caller exits
+ * cleanly.
+ */
+export declare function maybeRunOnboarding(config: CruxyConfig, opts: MaybeOnboardOptions): Promise<OnboardingResult> | null;

package/dist/cli/onboard.js

@@ -0,0 +1,54 @@
+import { resolveApiKey } from "../config/index.js";
+import { createDefaultDeps, defaultOnboardingIO, isFirstRun, runOnboarding, } from "../onboarding/index.js";
+import { createStreamPrinter } from "./stream-print.js";
+import { buildAgentSession } from "./session-factory.js";
+/**
+ * CLI-layer glue between the entry points and the onboarding module (U.6). Keeps
+ * `run`/`program`/`login`/`init` thin: they decide *when* to onboard; this builds
+ * the production wiring (live validation, credential persistence, first-win run).
+ */
+/** The env var that holds the key for a provider (for the fail-loud message). */
+export function apiKeyEnvVar(provider) {
+    switch (provider) {
+        case "anthropic":
+            return "ANTHROPIC_API_KEY";
+        case "openai":
+            return "OPENAI_API_KEY";
+        default:
+            return "CRUXY_API_KEY";
+    }
+}
+/** Run one first-win task end-to-end against the just-saved key. */
+export async function runFirstWinTask(config, cwd, prompt) {
+    const apiKey = resolveApiKey(config.model.provider);
+    if (!apiKey)
+        return; // defensive — the key was just persisted
+    const session = buildAgentSession(config, apiKey, cwd, true);
+    const print = createStreamPrinter((text) => process.stdout.write(text));
+    await session.send(prompt, print);
+}
+/**
+ * Run the guided first-run flow **iff** this is a first run; otherwise return
+ * `null` so the caller can fall back (fail loud, or show a banner). Never throws
+ * for an aborted setup — `result.completed` is `false` and the caller exits
+ * cleanly.
+ */
+export function maybeRunOnboarding(config, opts) {
+    const provider = config.model.provider;
+    if (!isFirstRun({ provider, interactive: opts.ttyInteractive }))
+        return null;
+    const deps = createDefaultDeps({
+        config,
+        cwd: opts.cwd,
+        runTask: opts.offerFirstWin
+            ? (prompt) => runFirstWinTask(config, opts.cwd, prompt)
+            : undefined,
+    });
+    return runOnboarding({
+        provider,
+        mode: "first-run",
+        offerFirstWin: opts.offerFirstWin,
+        io: defaultOnboardingIO(),
+        deps,
+    });
+}

package/dist/cli/program.js

@@ -8,6 +8,10 @@ import { configCommand } from "./commands/config.js";
 import { indexCommand } from "./commands/index.js";
 import { skillsCommand } from "./commands/skills.js";
 import { prCommand } from "./commands/pr.js";
+import { loginCommand } from "./commands/login.js";
+import { initCommand } from "./commands/init.js";
+import { loadConfig } from "../config/index.js";
+import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
     const program = new Command();
     program
@@ -30,15 +34,29 @@ export function buildProgram() {
     program.addCommand(indexCommand());
     program.addCommand(skillsCommand());
     program.addCommand(prCommand());
+    program.addCommand(loginCommand());
+    program.addCommand(initCommand());
     // Default action: bare `cruxy` -> entrypoint. An unrecognized first operand
     // means an unknown command (Commander runs the default action with it as an
     // operand rather than erroring), so reject it as a usage error.
-    program.action((_opts, command) => {
+    program.action(async (_opts, command) => {
         if (command.args.length > 0) {
             throw usageError(`unknown command: ${command.args[0]}`, [
                 "run `cruxy --help` to see available commands",
             ]);
         }
+        // First-run with no key (and a TTY) → guided setup, with the first-win demo.
+        // Otherwise fall through to the banner (an already-set-up user, or non-TTY).
+        const { config } = loadConfig();
+        const onboarding = maybeRunOnboarding(config, {
+            ttyInteractive: Boolean(process.stdin.isTTY),
+            offerFirstWin: true,
+            cwd: process.cwd(),
+        });
+        if (onboarding) {
+            await onboarding;
+            return;
+        }
         logger.print(pc.cyan(`${APP_NAME} v${APP_VERSION}`));
         logger.print(pc.dim("an agentic coding CLI\n"));
         logger.print("The interactive REPL lands in C.3 (terminal UI).");

package/dist/cli/repl.js

@@ -9,6 +9,7 @@ const HELP = `Commands:
   /clear         clear the conversation history (keep the session)
   /compact       summarize older history to free up context now
   /reload        re-read project instructions (CRUXY.md)
+  /plan          toggle plan mode (propose a plan before executing)
   /exit, /quit   leave cruxy
   Ctrl+D         leave cruxy`;
 const defaultIO = () => ({
@@ -107,6 +108,14 @@ export async function runInteractive(session, io = defaultIO()) {
                 : "no project instructions found"));
             continue;
         }
+        if (trimmed === "/plan") {
+            session.setPlanMode(!session.getPlanMode());
+            const on = session.getPlanMode();
+            logger.print(pc.dim(on
+                ? "plan mode on — the next prompt proposes a plan for approval"
+                : "plan mode off"));
+            continue;
+        }
         if (trimmed === "/help") {
             logger.print(HELP);
             continue;

package/dist/cli/session-factory.d.ts

@@ -0,0 +1,12 @@
+import type { CruxyConfig } from "../config/index.js";
+import { Session } from "../agent/index.js";
+/**
+ * Build a ready-to-run agent {@link Session} from a resolved key — the wiring
+ * shared by `cruxy run` and the onboarding first-win task (so they can't drift).
+ * The approval gate's interactivity tracks the TTY, exactly as in `run`.
+ *
+ * When `planMode` is on (C.31), it additionally wires a {@link PlanExecutionPolicy}
+ * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
+ * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
+ */
+export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean): Session;