docs(website): add CLI documentation page

packages/website/src/routeTree.gen.ts

@@ -14,6 +14,7 @@ import { Route as IndexRouteImport } from './routes/index'
 import { Route as DocsIndexRouteImport } from './routes/docs/index'
 import { Route as DocsSecurityRouteImport } from './routes/docs/security'
 import { Route as DocsConfigurationRouteImport } from './routes/docs/configuration'
+import { Route as DocsCliRouteImport } from './routes/docs/cli'
 import { Route as DocsBestPracticesRouteImport } from './routes/docs/best-practices'
 
 const DocsRoute = DocsRouteImport.update({
@@ -41,6 +42,11 @@ const DocsConfigurationRoute = DocsConfigurationRouteImport.update({
   path: '/configuration',
   getParentRoute: () => DocsRoute,
 } as any)
+const DocsCliRoute = DocsCliRouteImport.update({
+  id: '/cli',
+  path: '/cli',
+  getParentRoute: () => DocsRoute,
+} as any)
 const DocsBestPracticesRoute = DocsBestPracticesRouteImport.update({
   id: '/best-practices',
   path: '/best-practices',
@@ -51,6 +57,7 @@ export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
   '/docs': typeof DocsRouteWithChildren
   '/docs/best-practices': typeof DocsBestPracticesRoute
+  '/docs/cli': typeof DocsCliRoute
   '/docs/configuration': typeof DocsConfigurationRoute
   '/docs/security': typeof DocsSecurityRoute
   '/docs/': typeof DocsIndexRoute
@@ -58,6 +65,7 @@ export interface FileRoutesByFullPath {
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
   '/docs/best-practices': typeof DocsBestPracticesRoute
+  '/docs/cli': typeof DocsCliRoute
   '/docs/configuration': typeof DocsConfigurationRoute
   '/docs/security': typeof DocsSecurityRoute
   '/docs': typeof DocsIndexRoute
@@ -67,6 +75,7 @@ export interface FileRoutesById {
   '/': typeof IndexRoute
   '/docs': typeof DocsRouteWithChildren
   '/docs/best-practices': typeof DocsBestPracticesRoute
+  '/docs/cli': typeof DocsCliRoute
   '/docs/configuration': typeof DocsConfigurationRoute
   '/docs/security': typeof DocsSecurityRoute
   '/docs/': typeof DocsIndexRoute
@@ -77,6 +86,7 @@ export interface FileRouteTypes {
     | '/'
     | '/docs'
     | '/docs/best-practices'
+    | '/docs/cli'
     | '/docs/configuration'
     | '/docs/security'
     | '/docs/'
@@ -84,6 +94,7 @@ export interface FileRouteTypes {
   to:
     | '/'
     | '/docs/best-practices'
+    | '/docs/cli'
     | '/docs/configuration'
     | '/docs/security'
     | '/docs'
@@ -92,6 +103,7 @@ export interface FileRouteTypes {
     | '/'
     | '/docs'
     | '/docs/best-practices'
+    | '/docs/cli'
     | '/docs/configuration'
     | '/docs/security'
     | '/docs/'
@@ -139,6 +151,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof DocsConfigurationRouteImport
       parentRoute: typeof DocsRoute
     }
+    '/docs/cli': {
+      id: '/docs/cli'
+      path: '/cli'
+      fullPath: '/docs/cli'
+      preLoaderRoute: typeof DocsCliRouteImport
+      parentRoute: typeof DocsRoute
+    }
     '/docs/best-practices': {
       id: '/docs/best-practices'
       path: '/best-practices'
@@ -151,6 +170,7 @@ declare module '@tanstack/react-router' {
 
 interface DocsRouteChildren {
   DocsBestPracticesRoute: typeof DocsBestPracticesRoute
+  DocsCliRoute: typeof DocsCliRoute
   DocsConfigurationRoute: typeof DocsConfigurationRoute
   DocsSecurityRoute: typeof DocsSecurityRoute
   DocsIndexRoute: typeof DocsIndexRoute
@@ -158,6 +178,7 @@ interface DocsRouteChildren {
 
 const DocsRouteChildren: DocsRouteChildren = {
   DocsBestPracticesRoute: DocsBestPracticesRoute,
+  DocsCliRoute: DocsCliRoute,
   DocsConfigurationRoute: DocsConfigurationRoute,
   DocsSecurityRoute: DocsSecurityRoute,
   DocsIndexRoute: DocsIndexRoute,

packages/website/src/routes/docs.tsx

@@ -7,6 +7,7 @@ export const Route = createFileRoute('/docs')({
 
 const navigation = [
   { name: 'Getting started', href: '/docs' },
+  { name: 'CLI', href: '/docs/cli' },
   { name: 'Configuration', href: '/docs/configuration' },
   { name: 'Security', href: '/docs/security' },
   { name: 'Best practices', href: '/docs/best-practices' },

packages/website/src/routes/docs/cli.tsx

@@ -0,0 +1,230 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/docs/cli')({
+  head: () => ({
+    meta: [
+      { title: 'CLI - Paseo Docs' },
+      {
+        name: 'description',
+        content: 'Paseo CLI reference: manage agents, daemons, permissions, and worktrees from your terminal.',
+      },
+    ],
+  }),
+  component: CLI,
+})
+
+function Code({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="bg-card border border-border rounded-lg p-4 font-mono text-sm overflow-x-auto">
+      {children}
+    </div>
+  )
+}
+
+function CLI() {
+  return (
+    <div className="space-y-10">
+      <div>
+        <h1 className="text-3xl font-medium font-title mb-4">CLI</h1>
+        <p className="text-white/60 leading-relaxed">
+          The Paseo CLI lets you manage agents from your terminal. It's the same interface exposed by
+          the daemon's API, so anything you can do in the app you can do from the command line.
+        </p>
+      </div>
+
+      {/* Agent orchestration callout */}
+      <section className="space-y-4">
+        <div className="bg-primary/10 border border-primary/30 rounded-lg p-4 text-white/80">
+          <strong>Agent orchestration:</strong> You can tell coding agents to use the Paseo CLI to
+          spawn and manage other agents. This enables multi-agent workflows where one agent
+          delegates subtasks to others and waits for results.
+        </div>
+      </section>
+
+      {/* Quick reference */}
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Quick reference</h2>
+        <Code>
+          <pre className="text-white/80">{`paseo run "fix the tests"           # Start an agent
+paseo ls                             # List running agents
+paseo attach <id>                    # Stream agent output
+paseo send <id> "also fix linting"  # Send follow-up task
+paseo logs <id>                      # View agent timeline
+paseo stop <id>                      # Stop an agent`}</pre>
+        </Code>
+      </section>
+
+      {/* Running agents */}
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Running agents</h2>
+        <p className="text-white/60 leading-relaxed">
+          Use <code className="font-mono">paseo run</code> to start a new agent with a task:
+        </p>
+        <Code>
+          <pre className="text-white/80">{`paseo run "implement user authentication"
+paseo run --provider codex "refactor the API layer"
+paseo run --detach "run the full test suite"  # background
+paseo run --worktree feature-x "implement feature X"`}</pre>
+        </Code>
+        <p className="text-white/60 leading-relaxed">
+          The <code className="font-mono">--worktree</code> flag creates the agent in an isolated git
+          worktree, useful for parallel feature development.
+        </p>
+      </section>
+
+      {/* Listing agents */}
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Listing agents</h2>
+        <Code>
+          <pre className="text-white/80">{`paseo ls                    # Running agents in current directory
+paseo ls -a                 # Include completed/stopped agents
+paseo ls -g                 # All directories
+paseo ls -a -g --json       # Full list as JSON`}</pre>
+        </Code>
+      </section>
+
+      {/* Streaming output */}
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Streaming output</h2>
+        <p className="text-white/60 leading-relaxed">
+          Use <code className="font-mono">paseo attach</code> to stream an agent's output in real-time:
+        </p>
+        <Code>
+          <pre className="text-white/80">{`paseo attach abc123   # Attach to agent (Ctrl+C to detach)`}</pre>
+        </Code>
+        <p className="text-white/60 leading-relaxed">
+          Agent IDs can be shortened — <code className="font-mono">abc</code> works if it's unambiguous.
+        </p>
+      </section>
+
+      {/* Sending messages */}
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Sending messages</h2>
+        <p className="text-white/60 leading-relaxed">
+          Send follow-up tasks to a running or idle agent:
+        </p>
+        <Code>
+          <pre className="text-white/80">{`paseo send <id> "now run the tests"
+paseo send <id> --image screenshot.png "what's wrong here?"
+paseo send <id> --no-wait "queue this task"`}</pre>
+        </Code>
+      </section>
+
+      {/* Viewing logs */}
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Viewing logs</h2>
+        <Code>
+          <pre className="text-white/80">{`paseo logs <id>                  # Full timeline
+paseo logs <id> -f               # Follow (streaming)
+paseo logs <id> --tail 10        # Last 10 entries
+paseo logs <id> --filter tools   # Only tool calls`}</pre>
+        </Code>
+      </section>
+
+      {/* Waiting for agents */}
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Waiting for agents</h2>
+        <p className="text-white/60 leading-relaxed">
+          Block until an agent finishes its current task:
+        </p>
+        <Code>
+          <pre className="text-white/80">{`paseo wait <id>
+paseo wait <id> --timeout 60   # 60 second timeout`}</pre>
+        </Code>
+        <p className="text-white/60 leading-relaxed">
+          Useful in scripts or when one agent needs to wait for another.
+        </p>
+      </section>
+
+      {/* Permissions */}
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Permissions</h2>
+        <p className="text-white/60 leading-relaxed">
+          Agents may request permission for certain actions. Manage these from the CLI:
+        </p>
+        <Code>
+          <pre className="text-white/80">{`paseo permit ls                # List pending requests
+paseo permit allow <id>        # Allow all pending for agent
+paseo permit deny <id> --all   # Deny all pending`}</pre>
+        </Code>
+      </section>
+
+      {/* Agent modes */}
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Agent modes</h2>
+        <p className="text-white/60 leading-relaxed">
+          Change an agent's operational mode (provider-specific):
+        </p>
+        <Code>
+          <pre className="text-white/80">{`paseo agent mode <id> --list   # Show available modes
+paseo agent mode <id> bypass   # Set bypass mode
+paseo agent mode <id> plan     # Set plan mode`}</pre>
+        </Code>
+      </section>
+
+      {/* Daemon management */}
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Daemon management</h2>
+        <Code>
+          <pre className="text-white/80">{`paseo daemon start             # Start the daemon
+paseo daemon status            # Check status
+paseo daemon stop              # Stop the daemon`}</pre>
+        </Code>
+        <p className="text-white/60 leading-relaxed">
+          Use <code className="font-mono">PASEO_HOME</code> to run multiple isolated daemon instances.
+        </p>
+      </section>
+
+      {/* Multi-agent workflows */}
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Multi-agent workflows</h2>
+        <p className="text-white/60 leading-relaxed">
+          The CLI is designed to be used by agents themselves. You can instruct an agent to spawn
+          sub-agents for parallel work:
+        </p>
+        <Code>
+          <pre className="text-white/80">{`# Agent A spawns Agent B and waits for it
+paseo run --detach "implement the API" --name api-agent
+paseo wait api-agent
+paseo logs api-agent --tail 5`}</pre>
+        </Code>
+        <p className="text-white/60 leading-relaxed">
+          This pattern enables hierarchical task decomposition — a lead agent can break down work,
+          delegate to specialists, and synthesize results.
+        </p>
+      </section>
+
+      {/* Output formats */}
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Output formats</h2>
+        <p className="text-white/60 leading-relaxed">
+          Most commands support multiple output formats for scripting:
+        </p>
+        <Code>
+          <pre className="text-white/80">{`paseo ls --json                # JSON output
+paseo ls --format yaml         # YAML output
+paseo ls -q                    # IDs only (quiet)`}</pre>
+        </Code>
+      </section>
+
+      {/* Global options */}
+      <section className="space-y-4">
+        <h2 className="text-xl font-medium">Global options</h2>
+        <ul className="text-white/60 space-y-2 list-disc list-inside">
+          <li>
+            <code className="font-mono">--host &lt;host:port&gt;</code> — connect to a different daemon
+          </li>
+          <li>
+            <code className="font-mono">--json</code> — JSON output
+          </li>
+          <li>
+            <code className="font-mono">-q, --quiet</code> — minimal output
+          </li>
+          <li>
+            <code className="font-mono">--no-color</code> — disable colors
+          </li>
+        </ul>
+      </section>
+    </div>
+  )
+}