feat(admin): /dispatch setup -- first-run wizard, detection, and a once-ever nudge (issue #92)

- bare /dispatch now detects where the deployment is: valid pointer or explicit
  env -> panel exactly as before; cwd scaffold or a reachable queue -> panel
  plus one hint; nothing anywhere AND queue unreachable -> the offer. An
  exported VALKEY_URL is probed, never trusted -- a dead URL still reaches the
  offer, and an ops outage on a configured deployment keeps the banner, never
  the wizard
- /dispatch setup: dialogs-first, overlay-per-handoff (the tui suspend handle
  exists only inside a ctx.ui.custom factory; dialogs cannot run under a
  capturing overlay; stdin belongs to the attached child) -- pick a deploy dir,
  consented npm install of @edgehero/pi-dispatch@RUNTIME_VERSION under
  import-pi's spawn doctrine (no path in argv, --ignore-scripts, post-install
  version assertion that stops the wizard loudly), hand the terminal to
  pi-dispatch up (its own y/N gates ARE the host-mutation consents; --yes is
  forwarded to nothing), optional user-level service install, pointer written
  with the JSON shown verbatim then reapplied in-process, provider key printed
  never written, optional setup github hand-off, optional first trigger for the
  repo the session sits in (folder pre-filled, flow picked from its .pi/skills
  via the shared SKILL_NAME_RE, the in-place-edit warning printed, and the
  ai-trigger: allow line PRINTED for the operator to commit -- the wizard never
  writes repo files), then the panel
- session_start nudge: reason startup only, hasUI only, sync-only checks, a
  marker file makes it once-ever, notify-only
- every step individually declinable; declines continue converge-style;
  headless refuses; USED_API unchanged (spawns via node:child_process)

Specs: new DES-FIRST-RUN-SETUP-WIZARD (incl. the recorded rejections);
REQ-ADMIN-VIA-PI-EXTENSION amended (setup, the detection tree, the nudge,
declined-offer acceptance); REQ-DEPLOYMENT-BOOTSTRAP scope carve-in (the wizard
is a driver, not a power); Revision History rows in design.md + requirements.md;
DES-TRIGGER-OUTSIDE-PI, DES-CLI-SURFACE, CONST-BUDGET-BEFORE-TOKENS unchanged,
checked. operate-pi-dispatch SKILL.md gains the setup chapter (operator-typed
only; the model asks the operator to type it). README first-run story; cli/init
next-steps mention the wizard.

Signed-off-by: Rob Boerman <robboerman@live.nl>

Author: edgehero

README.md

@@ -279,6 +279,16 @@ then open the panel:
 pi install npm:@edgehero/pi-dispatch-admin   # then, in pi:  /dispatch
 ```
 
+**No deployment yet? The console builds one.** When `/dispatch` finds nothing — no pointer, no env, no
+config in the folder, queue unreachable — it offers **`/dispatch setup`**: pick a deployment folder
+(default `~/pi-dispatch`), consent to an `npm install` of the pinned runtime, watch `pi-dispatch up` run
+its own per-action prompts in your terminal, optionally install the worker as a user-level service, and
+land in the panel — with an optional first trigger for the repo you're sitting in, its flow picked from
+that repo's own `.pi/skills/`. Every step shows what it will do and asks first; every step can be
+declined; nothing is ever written into your repo (the `ai-trigger: allow` opt-in line is printed for
+*you* to commit), and no credential ever passes through a dialog. It's the same consented CLI underneath
+— the wizard just types it for you.
+
 Two other ways to load it: from a clone, the in-repo `.pi/extensions` shim auto-loads once you've trusted
 the project; or point pi at the source with `pi -e admin/src/index.ts` (add that path to the `"extensions"`
 array in `~/.pi/agent/settings.json` to make it permanent). Pointing the panel at a **live** deployment is

admin/skills/operate-pi-dispatch/SKILL.md

@@ -57,6 +57,19 @@ Use them like this:
 
 The confirm is the approval step. Treat a decline as a final, legitimate answer.
 
+## Setting up a deployment — `/dispatch setup`, and why you cannot run it
+
+When the tools report no reachable deployment (queue unreachable, no configured paths), the fix is the
+first-run wizard — and it is **operator-typed only**: there is no model-callable setup tool, on purpose.
+Tell the operator to type `/dispatch setup`. It will, with a consent step per action: create a deployment
+folder, npm-install the pinned runtime into it, hand the terminal to `pi-dispatch up` (whose own y/N
+prompts gate the docker actions), optionally install the worker as a user-level service, write the
+deployment pointer so the panel finds everything afterwards, and offer a first trigger for the repo the
+session is in. What it will NOT do, ever: write into the operator's repo (the `ai-trigger: allow` line is
+printed for them to commit), accept a credential through a dialog, or run anything with `--yes`.
+Do not try to reproduce the wizard's steps through other tools or shell access — the sequencing exists
+so each mutation carries its own human gate.
+
 ## Staged packages — `run.packages`, and why you cannot set it
 
 When a trigger fires, the job loads the third-party **pi packages the operator staged** into their global

admin/src/index.ts

@@ -33,6 +33,11 @@
  * ships an `operate-pi-dispatch` skill, advertised via `resources_discover`, that tells
  * the model how to use those human-in-the-loop write gates.
  *
+ * `/dispatch setup` (issue #92) runs the guided deployment wizard (setup-wizard.ts); a bare
+ * `/dispatch` on a host with no deployment at all offers it, and a one-time session_start
+ * nudge names it on a fresh host. The wizard sequences the worker CLI's own consented
+ * commands and writes the deployment pointer this factory applies above.
+ *
  * Supported pi version: 0.80.7. The factory registers nothing unless every API
  * member it consumes is present; on a miss it names the member and the
  * supported version on stderr and returns.
@@ -76,6 +81,10 @@ import { buildSandboxRunArgs, launchSandbox as spawnSandbox, resolveSandbox, san
 import { readManifest } from "@edgehero/pi-dispatch/sandbox-store";
 import { renderStatus, renderRuns, renderBudget, renderTriggers, renderSettingsView, renderCosts, renderWhatIf } from "./render.mjs";
 import { makeDashboard, createDashboardDeps } from "./dashboard.ts";
+// Only the nudge is loaded eagerly (it must register its session_start handler at factory time); the
+// wizard itself stays behind the dispatch handler's lazy import. The setup-wizard module imports
+// buildTriggerEntry back from here -- a cycle on paper, but both sides only call across it at runtime.
+import { registerNudge } from "./setup-wizard.ts";
 import { matchesKey } from "./keys.mjs";
 
 // The single source of truth for the ExtensionAPI surface this extension
@@ -90,7 +99,7 @@ const REBUILT_NOTICE = (reason: string) =>
   `replaced invalid settings file (${reason}) — other keys were lost`;
 
 const USAGE =
-  "usage: /dispatch <status|pause|resume|run|runs|logs|budget|costs|triggers|settings|set|unset>";
+  "usage: /dispatch <status|pause|resume|run|runs|logs|budget|costs|triggers|settings|set|unset|setup>";
 
 const KNOWN_SUBCOMMANDS = [
   "status",
@@ -105,6 +114,7 @@ const KNOWN_SUBCOMMANDS = [
   "settings",
   "set",
   "unset",
+  "setup",
 ] as const;
 
 export default function admin(pi: ExtensionAPI): void {
@@ -135,13 +145,14 @@ export default function admin(pi: ExtensionAPI): void {
 
   pi.registerCommand("dispatch", {
     description:
-      "pi-dispatch admin: status|pause|resume|run|runs|logs|budget|costs|triggers|settings|set|unset",
+      "pi-dispatch admin: status|pause|resume|run|runs|logs|budget|costs|triggers|settings|set|unset|setup",
     getArgumentCompletions: (prefix) => completeArguments(prefix),
     handler: async (args, ctx) => dispatch(pi, args, ctx),
   });
 
   registerTools(pi);
   registerSkill(pi);
+  registerNudge(pi);
 }
 
 /**
@@ -655,7 +666,7 @@ const PR_ACTION_VOCAB: Record<string, { hint: string; dflt: string }> = {
   azure: { hint: "created updated", dflt: "updated" },
 };
 
-function buildTriggerEntry(kind: string, f: any): any {
+export function buildTriggerEntry(kind: string, f: any): any {
   if (kind === "cron") {
     // Optional per-entry provider/model/maxTurns pass through to job.data (highest precedence); omitted when
     // blank so the value still resolves against the settings overlay/env at job start (triggers.mjs:127-131).
@@ -744,6 +755,32 @@ async function dispatch(pi: ExtensionAPI, args: string, ctx: any): Promise<void>
   if (pnote) notify?.(pnote, "warning");
 
   if (sub === "") {
+    // Detection decides what a bare /dispatch means (issue #92). Lazy import: the wizard module loads
+    // only on the bare command and `setup`, never for the read subcommands or the LLM tools.
+    const { detectDeployment, runSetupWizard } = await import("./setup-wizard.ts");
+    const det = await detectDeployment({ env: process.env, cwd: ctx?.cwd });
+    if (det.state === "none") {
+      // Nothing anywhere: offer the wizard instead of opening a panel onto an empty deployment. The
+      // confirm is the offer -- a decline (or a build without dialogs) degrades to the usage line.
+      if (typeof ctx?.ui?.confirm === "function") {
+        const ok = await ctx.ui.confirm(
+          "pi-dispatch setup",
+          "No deployment found (no pointer, no env, no config here, queue unreachable). Set one up now?",
+        );
+        if (ok) {
+          await runSetupWizard(paths, ctx, notify, { openDashboardFn: openDashboard });
+          return;
+        }
+      }
+      notify?.(`${USAGE} — run /dispatch setup when you are ready`, "info");
+      return;
+    }
+    if (det.state === "cwd" || det.state === "reachable") {
+      // A deployment that works only from this directory (cwd scaffold) or was merely probed
+      // (reachable queue, no config wired): open the panel as always, plus ONE hint that a pointer
+      // would make it work from anywhere. "pointer"/"env" open with no hint -- exactly as today.
+      notify?.(`using ${det.detail} — /dispatch setup can write a deployment pointer so this works from anywhere`, "info");
+    }
     await openDashboard(paths, ctx, notify);
     return;
   }
@@ -832,6 +869,14 @@ async function dispatch(pi: ExtensionAPI, args: string, ctx: any): Promise<void>
       applyUnset(paths.settingsFile, tokens, notify);
       return;
     }
+    case "setup": {
+      // Same lazy import as the bare branch; openDashboard rides in as a dep so the wizard's final
+      // step (and its "Open the panel anyway" escape) reuse this module's opener without a cycle at
+      // evaluation time.
+      const { runSetupWizard } = await import("./setup-wizard.ts");
+      await runSetupWizard(paths, ctx, notify, { openDashboardFn: openDashboard });
+      return;
+    }
     default:
       notify?.(`dispatch: unknown subcommand '${sub}'. ${USAGE}`, "warning");
       return;