From eac3b55bfe5d2bb00be050b38bca7f6fa68f6899 Mon Sep 17 00:00:00 2001
From: matthew-pilot <matthew@vulturelabs.io>
Date: Fri, 29 May 2026 21:44:36 +0000
Subject: [PATCH] fix: add pilotctl quickstart command with 3-command
 getting-started flow (PILOT-225)

Adds 'pilotctl quickstart' that prints the canonical 3-command
getting-started flow (list-agents, handshake, send-message) plus
first-time setup instructions. Addresses the discoverability gap
where new users with 60+ commands had no 'start here' path.

Files: 1 (+34 lines)
---
 cmd/pilotctl/main.go | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/cmd/pilotctl/main.go b/cmd/pilotctl/main.go
index 0a37bc3d..a62592a7 100644
--- a/cmd/pilotctl/main.go
+++ b/cmd/pilotctl/main.go
@@ -1154,6 +1154,9 @@ func usage() {
 Global flags:
   --json                        Output structured JSON (for agent/programmatic use)
 
+Getting started:
+  pilotctl quickstart             3-command getting-started flow
+
 Bootstrap:
   pilotctl init --registry <addr> [--hostname <name>] [--beacon <addr>]
   pilotctl config [--set key=value]
@@ -1301,6 +1304,10 @@ dispatch:
 		fmt.Println(version)
 		return
 
+	case "quickstart":
+		cmdQuickstart()
+		return
+
 	case "updates":
 		cmdUpdates(cmdArgs)
 		return
@@ -1608,6 +1615,33 @@ dispatch:
 	}
 }
 
+// ===================== QUICKSTART =====================
+
+func cmdQuickstart() {
+	fmt.Print(`
+╔══════════════════════════════════════════════════════════════╗
+║              PILOT PROTOCOL — Quickstart                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+Getting started with Pilot Protocol in 3 commands:
+
+  1. DISCOVER — see who is out there:
+       pilotctl send-message list-agents --data "list all agents"
+
+  2. TRUST   — shake hands with an agent:
+       pilotctl handshake <node_id>
+
+  3. TALK    — send your first message:
+       pilotctl send-message <node_id> --data "Hello, world!"
+
+First-time setup (run once):
+     pilotctl init --registry 34.71.57.205:9000
+     pilotctl daemon start
+
+For the full command list: pilotctl --help
+`)
+}
+
 // ===================== BOOTSTRAP =====================
 
 func cmdInit(args []string) {