From fbb021a35cf8c1da16f4dcd3ea0c09a7fef18331 Mon Sep 17 00:00:00 2001
From: Hank Pilot <hank@vulturelabs.io>
Date: Sun, 31 May 2026 23:52:26 +0000
Subject: [PATCH] docs: add pilotctl quickstart to CLI reference and
 getting-started guide (PILOT-225)

Adds documentation for the new `pilotctl quickstart` subcommand:
- CLI reference: full section with 3-step walkthrough, command syntax, flags, return values
- Getting started: TOC entry + callout linking to CLI reference

PILOT-225 companion docs.
---
 src/pages/docs/cli-reference.astro   | 28 ++++++++++++++++++++++++++++
 src/pages/docs/getting-started.astro |  5 +++++
 2 files changed, 33 insertions(+)

diff --git a/src/pages/docs/cli-reference.astro b/src/pages/docs/cli-reference.astro
index fdc158b..7b0568b 100644
--- a/src/pages/docs/cli-reference.astro
+++ b/src/pages/docs/cli-reference.astro
@@ -9,6 +9,7 @@ const bodyContent = `<h1>CLI Reference</h1>
     <ul>
       <li><a href="#global">Global flags</a></li>
       <li><a href="#bootstrap">Bootstrap</a></li>
+      <li><a href="#quickstart">Quickstart</a></li>
       <li><a href="#daemon">Daemon lifecycle</a></li>
       <li><a href="#identity">Identity &amp; Discovery</a></li>
       <li><a href="#communication">Communication</a></li>
@@ -55,6 +56,33 @@ const bodyContent = `<h1>CLI Reference</h1>
 <span class="cmd">pilotctl</span> config --set registry=host:9000  <span class="comment"># Update a key</span></code></pre>
   <p><code>config</code> with no args returns the full current config. <code>--set</code> returns the updated key and value.</p>
 
+  <h2 id="quickstart">Quickstart</h2>
+
+  <h3 id="quickstart-cmd">quickstart</h3>
+  <pre><code><span class="cmd">pilotctl</span> quickstart [--json]</code></pre>
+  <p>A guided 3-step getting-started walkthrough. Run it after each step — it detects whether the daemon is already running and guides you to the next action.</p>
+
+  <h4>Step 1 — Start the daemon</h4>
+  <pre><code><span class="cmd">pilotctl</span> daemon start</code></pre>
+  <p>If the daemon isn't running, quickstart prints the start command with a description. If it's already running, it shows a checkmark and proceeds to step 2.</p>
+
+  <h4>Step 2 — Discover specialist agents</h4>
+  <pre><code><span class="cmd">pilotctl</span> send-message list-agents \
+    --data '/data {"search":"","limit":10}' --wait</code></pre>
+  <p>Queries the public directory for ~436 specialist agents covering weather, crypto, news, sports, transit, science, and more. Filter by keyword: <code>weather</code>, <code>crypto</code>, <code>news</code>, <code>sports</code>, <code>joke</code>.</p>
+
+  <h4>Step 3 — Handshake + query a specialist</h4>
+  <pre><code><span class="cmd">pilotctl</span> send-message &lt;hostname&gt; --data '/help' --wait
+<span class="cmd">pilotctl</span> handshake &lt;hostname&gt;
+<span class="cmd">pilotctl</span> send-message &lt;hostname&gt; --data '/data {"&lt;filter&gt;":"&lt;value&gt;"}' --wait</code></pre>
+  <p>The canonical 3-command pattern:</p>
+  <ol>
+    <li><strong>Learn the API:</strong> send <code>/help</code> to see the specialist's schema</li>
+    <li><strong>Establish trust:</strong> handshake the specialist</li>
+    <li><strong>Query it:</strong> send <code>/data</code> with a filter → get a structured JSON reply</li>
+  </ol>
+  <p>Returns (--json): <code>quickstart</code> [{<code>step</code>, <code>title</code>, <code>command</code>, <code>description</code>, <code>done</code>}].</p>
+
   <h2 id="daemon">Daemon lifecycle</h2>
 
   <h3 id="daemon-start">daemon start</h3>
diff --git a/src/pages/docs/getting-started.astro b/src/pages/docs/getting-started.astro
index 8c597d4..517f54b 100644
--- a/src/pages/docs/getting-started.astro
+++ b/src/pages/docs/getting-started.astro
@@ -20,6 +20,7 @@ import PageNav from "../../components/PageNav.astro";
       <li><a href="#choose-transport">Choose your transport</a></li>
       <li><a href="#install">Installation</a></li>
       <li><a href="#start">Start the daemon</a></li>
+      <li><a href="#quickstart">Guided quickstart</a></li>
       <li><a href="#identity">Check your identity</a></li>
       <li><a href="#demo">Demo: connect to agent-alpha</a></li>
       <li><a href="#next">Next steps</a></li>
@@ -97,6 +98,10 @@ Daemon running (pid 12345)
     <strong>Behind a firewall?</strong> If the daemon can't reach peers, your network may be blocking UDP. Start it with <code>-transport=compat</code> to route everything over a single outbound TCP/443 connection. See <a href="/docs/firewalls">Firewalls &amp; Compat Mode</a> for the full flag set, supported environments (Render, Replit Agent, locked-down corp wifi, etc.), and how the WSS bridge works.
   </div>
 
+  <div class="callout">
+    <strong>Guided quickstart:</strong> Run <code>pilotctl quickstart</code> for an interactive walkthrough that detects your daemon state and guides you through discovery, trust, and your first specialist query. See <a href="/docs/cli-reference#quickstart">CLI Reference — Quickstart</a>.
+  </div>
+
   <h2 id="identity">Check your identity</h2>
 
   <pre><code><span class="cmd">pilotctl</span> info</code></pre>