docs: Organized coyote --help output to be more readable

.sisyphus/plans/graph-rag-spec.md

@@ -1,371 +0,0 @@
-# Graph RAG Design Spec
-
-## Status: COMPLETE
-
-### Verified From Code (all claims backed by actual file reads)
-
----
-
-## Goal
-
-Extend the existing two-signal hybrid search (vector HNSW + BM25 → RRF) to a three-signal hybrid
-(vector + BM25 + knowledge graph → RRF). The graph captures entity/relationship knowledge extracted
-from documents at ingestion time via an LLM call per chunk. At query time, graph traversal expands
-context beyond semantic similarity.
-
----
-
-## Verified Current Architecture
-
-### `Rag` struct (`src/rag/mod.rs:48`)
-```rust
-pub struct Rag {
-    app_config: Arc<AppConfig>,
-    name: String,
-    path: String,
-    embedding_model: Model,
-    hnsw: Hnsw<'static, f32, DistCosine>,  // ephemeral, rebuilt on load
-    bm25: SearchEngine<DocumentId>,          // ephemeral, rebuilt on load
-    data: RagData,                           // serialized to YAML
-    last_sources: RwLock<Option<String>>,
-}
-```
-
-### `RagData` struct (`src/rag/mod.rs:892`)
-```rust
-pub struct RagData {
-    pub embedding_model: String,
-    pub chunk_size: usize,
-    pub chunk_overlap: usize,
-    pub reranker_model: Option<String>,
-    pub top_k: usize,
-    pub batch_size: Option<usize>,
-    pub next_file_id: FileId,
-    pub document_paths: Vec<String>,
-    pub files: IndexMap<FileId, RagFile>,
-    #[serde(with = "serde_vectors")]
-    pub vectors: IndexMap<DocumentId, Vec<f32>>,
-}
-```
-
-### `RagData::new` callers (both need updating):
-1. `Rag::init` (`src/rag/mod.rs:219`) — interactive init path
-2. `Rag::resolve_init_data` (`src/rag/mod.rs:195`) — config-driven init path
-
-### `Rag::create` (`src/rag/mod.rs:253`) — all init paths converge here:
-```rust
-pub fn create(app: &AppConfig, name: &str, path: &Path, data: RagData) -> Result<Self> {
-    let hnsw = data.build_hnsw();
-    let bm25 = data.build_bm25();
-    let embedding_model = Model::retrieve_model(app, &data.embedding_model, ModelType::Embedding)?;
-    let rag = Rag { app_config: Arc::new(app.clone()), name: name.to_string(),
-                    path: path.display().to_string(), data, embedding_model, hnsw, bm25,
-                    last_sources: RwLock::new(None) };
-    Ok(rag)
-}
-```
-
-### `hybrid_search` (`src/rag/mod.rs:710`)
-```rust
-async fn hybrid_search(&self, query: &str, top_k: usize, rerank_model: Option<&str>)
-    -> Result<Vec<(DocumentId, String)>>
-```
-Runs `vector_search` + `keyword_search` in parallel via `tokio::join!`, then either reranks or
-applies `reciprocal_rank_fusion(vec![vector_ids, keyword_ids], vec![1.125, 1.0], top_k)`.
-
-### `reciprocal_rank_fusion` (`src/rag/mod.rs:1186`) — standalone fn, already weight-parameterized:
-```rust
-fn reciprocal_rank_fusion(
-    list_of_document_ids: Vec<Vec<DocumentId>>,
-    list_of_weights: Vec<f32>,
-    top_k: usize,
-) -> Vec<DocumentId>
-```
-
-### `RagData::del` (`src/rag/mod.rs:953`):
-```rust
-pub fn del(&mut self, file_ids: Vec<FileId>) {
-    for file_id in file_ids {
-        if let Some(file) = self.files.swap_remove(&file_id) {
-            for (document_index, _) in file.documents.iter().enumerate() {
-                let document_id = DocumentId::new(file_id, document_index);
-                self.vectors.swap_remove(&document_id);
-            }
-        }
-    }
-}
-```
-
-### `RagNode` (`src/graph/types.rs:331`):
-```rust
-pub struct RagNode {
-    pub documents: Vec<String>,
-    pub query: Option<String>,
-    pub top_k: Option<usize>,
-    pub embedding_model: Option<String>,
-    pub chunk_size: Option<usize>,
-    pub chunk_overlap: Option<usize>,
-    pub reranker_model: Option<String>,
-    pub batch_size: Option<usize>,
-    pub state_updates: Option<HashMap<String, String>>,
-    pub timeout: Option<u64>,
-}
-```
-
-### `Client` trait (`src/client/common.rs:40`):
-- `async fn chat_completions(&self, input: Input) -> Result<ChatCompletionsOutput>` — needs `Input`
-- `async fn chat_completions_inner(&self, client: &ReqwestClient, data: ChatCompletionsData) -> Result<ChatCompletionsOutput>` — accessible on `Box<dyn Client>` via vtable
-- `async fn embeddings(&self, data: &EmbeddingsData) -> Result<Vec<Vec<f32>>>`
-- `async fn rerank(&self, data: &RerankData) -> Result<RerankOutput>`
-- `fn build_client(&self) -> Result<ReqwestClient>`
-- `fn model(&self) -> &Model`
-
-**Key finding**: `Input` cannot be constructed without `RequestContext` (which `Rag` doesn't have).
-Instead, `extract_entities` uses `chat_completions_inner` directly with manually built
-`ChatCompletionsData`. This is accessible via `Box<dyn Client>`.
-
-### `Message` (`src/client/message.rs:22`):
-```rust
-pub fn new(role: MessageRole, content: MessageContent) -> Self
-```
-`MessageRole::User`, `MessageContent::Text(String)` — both confirmed.
-
-### `AppConfig` RAG fields (`src/config/app_config.rs:71`):
-```rust
-pub rag_embedding_model: Option<String>,
-pub rag_reranker_model: Option<String>,
-pub rag_top_k: usize,        // default: 5
-pub rag_chunk_size: Option<usize>,
-pub rag_chunk_overlap: Option<usize>,
-pub rag_template: Option<String>,
-```
-
-### `patch_messages` — confirmed exported from `crate::client::*` (used in `input.rs:5`)
-
-### `init_client(app_config, model)` — works for any `ModelType`, including `Chat`
-
-### `ModelType` variants: `Chat`, `Embedding`, `Reranker` (confirmed in `model.rs`)
-
-### petgraph serde: `NodeIndex` serializes as inner `u32`; `StableGraph` preserves index positions
-through roundtrip. `IndexMap<DocumentId, Vec<NodeIndex>>` safe for YAML (DocumentId is newtype over
-usize, serializes as integer key).
-
----
-
-## New Dependency
-
-```toml
-petgraph = { version = "0.7", features = ["serde-1"] }
-```
-
----
-
-## New File: `src/rag/graph.rs`
-
-All graph types and extraction logic. Module declared in `mod.rs` as `mod graph; use self::graph::*;`.
-
-### Types:
-- `Entity { name: String, entity_type: String, description: Option<String> }`
-- `Relationship { relation_type: String, weight: f32 }`
-- `ExtractionResult { entities: Vec<ExtractedEntity>, relationships: Vec<ExtractedRelationship> }`
-- `ExtractedEntity { name: String, r#type: String, description: Option<String> }`
-- `ExtractedRelationship { from: String, to: String, r#type: String, weight: Option<f32> }`
-- `KnowledgeGraph { graph: StableGraph<Entity, Relationship>, entity_index: IndexMap<String, NodeIndex>, document_entities: IndexMap<DocumentId, Vec<NodeIndex>> }`
-
-### Key methods on `KnowledgeGraph`:
-- `merge(doc_id: DocumentId, result: ExtractionResult)` — merges extraction into graph
-- `remove_documents(ids: &[DocumentId])` — removes entities exclusive to deleted documents
-- `build_node_to_docs(&self) -> IndexMap<NodeIndex, Vec<DocumentId>>` — ephemeral reverse map
-
-### `extract_entities(client: &dyn Client, chunk: &str) -> Result<ExtractionResult>`:
-- Builds `ChatCompletionsData` manually (no `Input` needed)
-- Calls `patch_messages` then `client.chat_completions_inner(&reqwest_client, data).await`
-- Strips markdown code fences from response before JSON parse
-- Temperature: `Some(0.0)` for deterministic extraction
-
-### Extraction prompt: structured JSON output requesting entities + relationships
-
----
-
-## Changes to `src/rag/mod.rs`
-
-### `Rag` struct — add one ephemeral field:
-```rust
-node_to_docs: IndexMap<NodeIndex, Vec<DocumentId>>,  // ephemeral, rebuilt on load
-```
-
-### `Rag::create` — build node_to_docs before moving data:
-```rust
-let node_to_docs = data.knowledge_graph.build_node_to_docs();
-// then add to struct literal
-```
-
-### `Rag` Clone impl — add:
-```rust
-node_to_docs: self.data.knowledge_graph.build_node_to_docs(),
-```
-
-### `RagData` struct — three new fields (all `#[serde(default)]` for backward compat):
-```rust
-#[serde(default)]
-pub graph_enabled: bool,
-#[serde(default, skip_serializing_if = "Option::is_none")]
-pub extractor_model: Option<String>,
-#[serde(default)]
-pub knowledge_graph: KnowledgeGraph,
-```
-
-### `RagData::new` — two new params: `graph_enabled: bool, extractor_model: Option<String>`
-
-### `RagData::del` — collect doc_ids during existing loop, call `remove_documents` at end:
-```rust
-let mut doc_ids_to_remove = vec![];
-for file_id in file_ids {
-    if let Some(file) = self.files.swap_remove(&file_id) {
-        for (document_index, _) in file.documents.iter().enumerate() {
-            let document_id = DocumentId::new(file_id, document_index);
-            self.vectors.swap_remove(&document_id);
-            doc_ids_to_remove.push(document_id);
-        }
-    }
-}
-self.knowledge_graph.remove_documents(&doc_ids_to_remove);
-```
-
-### `Rag::init` (line 219) — add two params to `RagData::new`:
-```rust
-app.rag_graph_enabled,
-app.rag_extractor_model.clone(),
-```
-
-### `resolve_init_data` — resolve from config+app, pass to `RagData::new`:
-```rust
-let graph_enabled = config.graph_enabled.unwrap_or(app.rag_graph_enabled);
-let extractor_model = config.extractor_model.clone().or_else(|| app.rag_extractor_model.clone());
-```
-
-### `sync_documents` — entity extraction block after `rag_files` built, before embedding:
-```rust
-if self.data.graph_enabled {
-    if let Some(extractor_model_id) = self.data.extractor_model.clone() {
-        let model = Model::retrieve_model(&self.app_config, &extractor_model_id, ModelType::Chat)?;
-        let client = self.create_embeddings_client(model)?;
-        let total_chunks: usize = rag_files.iter().map(|f| f.documents.len()).sum();
-        let mut chunk_num = 0;
-        let file_offset = next_file_id;
-        for (batch_file_idx, rag_file) in rag_files.iter().enumerate() {
-            let file_id = file_offset + batch_file_idx;
-            for (doc_idx, doc) in rag_file.documents.iter().enumerate() {
-                chunk_num += 1;
-                progress(&spinner, format!("Extracting entities [{chunk_num}/{total_chunks}]"));
-                let doc_id = DocumentId::new(file_id, doc_idx);
-                match extract_entities(client.as_ref(), &doc.page_content).await {
-                    Ok(result) => self.data.knowledge_graph.merge(doc_id, result),
-                    Err(e) => debug!("Entity extraction failed for {doc_id:?}: {e}"),
-                }
-            }
-        }
-    }
-}
-```
-
-### After line 705 (after hnsw/bm25 rebuild in sync_documents):
-```rust
-self.node_to_docs = self.data.knowledge_graph.build_node_to_docs();
-```
-
-### `hybrid_search` — add third signal:
-```rust
-let graph_search_ids: Vec<DocumentId> = if self.data.graph_enabled
-    && !self.data.knowledge_graph.entity_index.is_empty()
-{
-    self.graph_search(query, &keyword_search_ids, top_k)
-} else {
-    vec![]
-};
-// RRF: extend to 3-way when graph has results, fall back to 2-way otherwise
-```
-
-### New `graph_search` method (sync):
-```rust
-fn graph_search(&self, query: &str, bm25_anchor_ids: &[DocumentId], top_k: usize) -> Vec<DocumentId>
-```
-Phase 1: entity names from query via substring match in `entity_index`.
-Phase 2: fallback — entities from top BM25 document chunks.
-Phase 3: expand 1-hop neighbors in `StableGraph`.
-Phase 4: score docs by entity overlap ratio, return top_k.
-
-### `RagInitConfig` — two new fields:
-```rust
-pub graph_enabled: Option<bool>,
-pub extractor_model: Option<String>,
-```
-
----
-
-## Changes to `src/config/app_config.rs`
-
-New fields alongside existing `rag_*` block:
-```rust
-pub rag_graph_enabled: bool,            // default: false
-pub rag_extractor_model: Option<String>, // default: None
-```
-Defaults, env var overrides, and propagation all follow the same pattern as existing `rag_*` fields.
-
----
-
-## Changes to `src/graph/types.rs` — `RagNode`
-
-```rust
-#[serde(default, skip_serializing_if = "Option::is_none")]
-pub graph_enabled: Option<bool>,
-#[serde(default, skip_serializing_if = "Option::is_none")]
-pub extractor_model: Option<String>,
-```
-
----
-
-## Changes to `src/config/agent.rs`
-
-Pass new fields through to `RagInitConfig`:
-```rust
-graph_enabled: rag_node.graph_enabled,
-extractor_model: rag_node.extractor_model.clone(),
-```
-
----
-
-## Backward Compatibility
-
-- All new `RagData` fields have `#[serde(default)]` — old YAML files load without migration
-- `graph_enabled` defaults `false` — existing RAG instances unchanged
-- `graph_search_ids` empty → 2-way RRF runs (identical to current behavior)
-- `node_to_docs` rebuild on `create()` is O(n) over empty map for old instances
-
----
-
-## V1 Scope Exclusions
-
-- LLM entity extraction from query at search time (V1 uses substring match + BM25 anchoring)
-- Multi-hop traversal (field reserved, 1-hop only in V1)
-- Entity embeddings / fuzzy entity lookup
-- Bincode for large-corpus graph storage
-- Gleaning / multi-pass extraction
-
----
-
-## Implementation Progress
-
-- [x] Cargo.toml — petgraph dependency
-- [x] src/rag/graph.rs — new file
-- [x] src/rag/mod.rs — mod/use, Rag struct, create, clone
-- [x] src/rag/mod.rs — RagData fields, new, del
-- [x] src/rag/mod.rs — Rag::init, resolve_init_data
-- [x] src/rag/mod.rs — sync_documents extraction block
-- [x] src/rag/mod.rs — hybrid_search + graph_search
-- [x] src/rag/mod.rs — RagInitConfig fields
-- [x] src/config/app_config.rs — new fields
-- [x] src/config/mod.rs — propagation
-- [x] src/graph/types.rs — RagNode fields
-- [x] src/config/agent.rs — propagation
-- [x] cargo check — clean (0 warnings, 1065 tests passing)

assets/sbx-kit/spec.yaml

@@ -5,7 +5,7 @@
 #   sbx cp $HOME/.config/coyote/ testing:/home/agent/.config/
 #   sbx cp $HOME/.coyote_password testing:/home/agent/
 #   sbx run testing --kit ./sbx-kit/
-schemaVersion: "1"
+schemaVersion: '1'
 kind: sandbox
 name: coyote
 displayName: Coyote
@@ -14,10 +14,10 @@ description: >
   CLI & REPL mode, RAG, AI tools & agents, MCP servers, skills, and macros.
 
 sandbox:
-  image: "docker/sandbox-templates:shell-docker"
+  image: 'docker/sandbox-templates:shell-docker'
   aiFilename: COYOTE.md
   entrypoint:
-    run: ["bash", "-lc", "exec /home/agent/.cargo/bin/coyote"]
+    run: ['bash', '-lc', 'exec /home/agent/.cargo/bin/coyote']
 
 network:
   # Proxy-managed LLM providers: the proxy substitutes `proxy-managed` for
@@ -50,96 +50,96 @@ network:
   serviceAuth:
     openai:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     anthropic:
       headerName: x-api-key
-      valueFormat: "%s"
+      valueFormat: '%s'
     gemini:
       headerName: x-goog-api-key
-      valueFormat: "%s"
+      valueFormat: '%s'
     cohere:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     groq:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     openrouter:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     ai21:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     cloudflare:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     deepinfra:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     deepseek:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     mistral:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     perplexity:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     voyageai:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     xai:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     jina:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     ernie:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     hunyuan:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     minimax:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     moonshot:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     qianwen:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
     zhipuai:
       headerName: Authorization
-      valueFormat: "Bearer %s"
+      valueFormat: 'Bearer %s'
   allowedDomains:
     # Coyote release + self-update + model-registry sync
-    - "github.com:443"
-    - "api.github.com:443"
-    - "raw.githubusercontent.com:443"
-    - "objects.githubusercontent.com:443"
-    - "*.githubusercontent.com:443"
+    - 'github.com:443'
+    - 'api.github.com:443'
+    - 'raw.githubusercontent.com:443'
+    - 'objects.githubusercontent.com:443'
+    - '*.githubusercontent.com:443'
     # Coyote install paths (cargo install + uv + rustup + Python tool deps at runtime)
-    - "crates.io:443"
-    - "static.crates.io:443"
-    - "pypi.org:443"
-    - "files.pythonhosted.org:443"
-    - "astral.sh:443"
-    - "sh.rustup.rs:443"
-    - "static.rust-lang.org:443"
+    - 'crates.io:443'
+    - 'static.crates.io:443'
+    - 'pypi.org:443'
+    - 'files.pythonhosted.org:443'
+    - 'astral.sh:443'
+    - 'sh.rustup.rs:443'
+    - 'static.rust-lang.org:443'
 
     # LLM model OAuth + API endpoints
-    - "claude.ai:443"
-    - "console.anthropic.com:443"
-    - "accounts.google.com:443"
+    - 'claude.ai:443'
+    - 'console.anthropic.com:443'
+    - 'accounts.google.com:443'
     # *.googleapis.com covers oauth2 + userinfo + VertexAI regional endpoints
     # (*-aiplatform.googleapis.com). Do not narrow without re-checking VertexAI.
-    - "*.googleapis.com:443"
+    - '*.googleapis.com:443'
 
     # Bedrock and GitHub Models use signed / GitHub-PAT auth that the proxy
     # cannot rewrite. Domains are allow-listed; credentials must be injected
     # separately (see README "Extending").
-    - "*.amazonaws.com:443"
-    - "models.inference.ai.azure.com:443"
+    - '*.amazonaws.com:443'
+    - 'models.inference.ai.azure.com:443'
 
 credentials:
   sources:
@@ -210,9 +210,10 @@ credentials:
 
 environment:
   variables:
-    IS_SANDBOX: "1"
+    IS_SANDBOX: '1'
     COYOTE_LOG_LEVEL: INFO
     COYOTE_CONFIG_DIR: /home/agent/.config/coyote
+    EDITOR: nano
   proxyManaged:
     - OPENAI_API_KEY
     - ANTHROPIC_API_KEY
@@ -249,8 +250,9 @@ commands:
           musl-tools \
           libssl-dev \
           pandoc \
-          bzip2
-      user: "1000"
+          bzip2 \
+          nano
+      user: '1000'
       description: Install system prerequisites (including pandoc for fetch_url_via_curl)
     - command: |
         curl -LsSf https://astral.sh/uv/install.sh | sh
@@ -258,7 +260,7 @@ commands:
           printf '#!/bin/sh\nexec uv tool run "$@"\n' > "$HOME/.local/bin/uvx"
           chmod +x "$HOME/.local/bin/uvx"
         fi
-      user: "1000"
+      user: '1000'
       description: Install uv and write a uvx shell wrapper (the installer may place a macOS binary at this path on Docker-for-Mac hosts, which the Linux container cannot execute)
     - command: |
         set -euo pipefail
@@ -274,7 +276,7 @@ commands:
         curl -fsSL --retry 3 "https://github.com/xo/usql/releases/download/v${USQL_VERSION}/usql_static-${USQL_VERSION}-linux-${USQL_ARCH}.tar.bz2" -o "$TMPDIR/usql.tar.bz2"
         tar -xjf "$TMPDIR/usql.tar.bz2" -C "$TMPDIR"
         sudo install -m 0755 "$TMPDIR/usql_static" /usr/local/bin/usql
-      user: "1000"
+      user: '1000'
       description: Install the usql universal SQL CLI (used by the built-in sql agent and execute_sql_code tool)
     - command: |
         curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | \
@@ -284,27 +286,27 @@ commands:
           --target x86_64-unknown-linux-musl
         . "$HOME/.cargo/env"
         cargo install --locked coyote-ai
-      user: "1000"
+      user: '1000'
       description: Install Coyote AI CLI via Rust's Cargo
     - command: |
         . "$HOME/.cargo/env"
         cargo install --locked iwec
-      user: "1000"
+      user: '1000'
       description: Install the IWE MCP server binary (iwec) used by the built-in iwe MCP server and iwe-knowledge-base skill
     - command: |
         . "$HOME/.cargo/env"
         cargo install --locked ast-grep
-      user: "1000"
+      user: '1000'
       description: Install ast-grep, used by the built-in ast_grep structural code search tool (and the explore agent)
 
   startup:
     - command:
         [
-          "sh",
-          "-c",
+          'sh',
+          '-c',
           'test -f "$HOME/.config/coyote/config.yaml" || coyote --info >/dev/null 2>&1 || true',
         ]
-      user: "1000"
+      user: '1000'
       background: false
       description: Bootstrap Coyote config directory on first sandbox start
 

src/cli/mod.rs

@@ -43,6 +43,10 @@ use std::io::{Read, stdin};
 	),
 )]
 pub struct Cli {
+    /// Input text
+    #[arg(trailing_var_arg = true)]
+    text: Vec<String>,
+
     /// Select a LLM model
     #[arg(short, long, add = ArgValueCompleter::new(model_completer))]
     pub model: Option<String>,
@@ -52,30 +56,6 @@ pub struct Cli {
     /// Select a role
     #[arg(short, long, add = ArgValueCompleter::new(role_completer))]
     pub role: Option<String>,
-    /// Start or join a session
-    #[arg(short = 's', long, add = ArgValueCompleter::new(session_completer))]
-    pub session: Option<Option<String>>,
-    /// Ensure the session is empty
-    #[arg(long)]
-    pub empty_session: bool,
-    /// Ensure the new conversation is saved to the session
-    #[arg(long)]
-    pub save_session: bool,
-    /// Start an agent
-    #[arg(short = 'a', long, add = ArgValueCompleter::new(agent_completer))]
-    pub agent: Option<String>,
-    /// Set agent variables
-    #[arg(long, value_names = ["NAME", "VALUE"], num_args = 2)]
-    pub agent_variable: Vec<String>,
-    /// Start a RAG
-    #[arg(long, add = ArgValueCompleter::new(rag_completer))]
-    pub rag: Option<String>,
-    /// Rebuild the RAG to sync document changes
-    #[arg(long)]
-    pub rebuild_rag: bool,
-    /// Execute a macro
-    #[arg(long = "macro", value_name = "MACRO", add = ArgValueCompleter::new(macro_completer))]
-    pub macro_name: Option<String>,
     /// Execute commands in natural language
     #[arg(short = 'e', long)]
     pub execute: bool,
@@ -88,116 +68,176 @@ pub struct Cli {
     /// Turn off stream mode
     #[arg(short = 'S', long)]
     pub no_stream: bool,
+    /// Display the message without sending it
+    #[arg(long)]
+    pub dry_run: bool,
+    /// Disable loading workspace MCP servers from .coyote/mcp.json
+    #[arg(long)]
+    pub no_workspace_mcp: bool,
     /// Disable memory for this invocation
     #[arg(long)]
     pub no_memory: bool,
     /// Skip permission prompts by setting AUTO_CONFIRM for all tools (dangerous!)
     #[arg(long)]
     pub dangerously_skip_permissions: bool,
+
+    /// Start or join a session
+    #[arg(short = 's', long, help_heading = "Session & Memory", add = ArgValueCompleter::new(session_completer))]
+    pub session: Option<Option<String>>,
+    /// Ensure the session is empty
+    #[arg(long, help_heading = "Session & Memory")]
+    pub empty_session: bool,
+    /// Ensure the new conversation is saved to the session
+    #[arg(long, help_heading = "Session & Memory")]
+    pub save_session: bool,
     /// Bootstrap a memory marker so coyote begins loading memory next run
-    #[arg(long, value_name = "SCOPE", value_enum)]
+    #[arg(
+        long,
+        value_name = "SCOPE",
+        value_enum,
+        help_heading = "Session & Memory"
+    )]
     pub init_memory: Option<MemoryScope>,
-    /// Display the message without sending it
-    #[arg(long)]
-    pub dry_run: bool,
-    /// Display information
-    #[arg(long)]
-    pub info: bool,
-    /// Build all configured Bash tool scripts
-    #[arg(long)]
-    pub build_tools: bool,
-    /// Reinstall bundled assets, overwriting any local changes
-    #[arg(long, value_name = "CATEGORY", value_enum)]
-    pub install: Option<AssetCategory>,
-    /// Install assets from a remote git repository (URL may be suffixed with #<ref>)
-    #[arg(long, value_name = "GIT_URL")]
-    pub install_from: Option<String>,
-    /// Restrict --install-from to a single asset category
-    #[arg(long, value_name = "CATEGORY", value_enum, requires = "install_from")]
-    pub filter: Option<InstallFilter>,
-    /// Overwrite all conflicts without prompting (used with --install-from)
-    #[arg(long, requires = "install_from")]
-    pub install_force: bool,
-    /// Sync models updates
-    #[arg(long)]
-    pub sync_models: bool,
-    /// List all available chat models
-    #[arg(long)]
-    pub list_models: bool,
-    /// List all roles
-    #[arg(long)]
-    pub list_roles: bool,
-    /// List all sessions
-    #[arg(long)]
-    pub list_sessions: bool,
-    /// List all agents
-    #[arg(long)]
-    pub list_agents: bool,
-    /// List all RAGs
-    #[arg(long)]
-    pub list_rags: bool,
-    /// List all macros
-    #[arg(long)]
-    pub list_macros: bool,
-    /// List all installed skills
-    #[arg(long)]
-    pub list_skills: bool,
     /// Pre-load an existing skill into the session (repeatable). If a single
     /// `--skill <NAME>` is given and the skill doesn't exist, opens $EDITOR
     /// with a scaffold to create it.
-    #[arg(long, value_name = "NAME")]
+    #[arg(long, value_name = "NAME", help_heading = "Session & Memory")]
     pub skill: Vec<String>,
-    /// Input text
-    #[arg(trailing_var_arg = true)]
-    text: Vec<String>,
-    /// Tail logs
-    #[arg(long)]
-    pub tail_logs: bool,
-    /// Disable colored log output
-    #[arg(long, requires = "tail_logs")]
-    pub disable_log_colors: bool,
-    /// Add a secret to the Coyote vault
-    #[arg(long, value_name = "SECRET_NAME", exclusive = true)]
-    pub add_secret: Option<String>,
-    /// Decrypt a secret from the Coyote vault and print the plaintext
-    #[arg(long, value_name = "SECRET_NAME", exclusive = true, add = ArgValueCompleter::new(secrets_completer))]
-    pub get_secret: Option<String>,
-    /// Update an existing secret in the Coyote vault
-    #[arg(long, value_name = "SECRET_NAME", exclusive = true, add = ArgValueCompleter::new(secrets_completer))]
-    pub update_secret: Option<String>,
-    /// Delete a secret from the Coyote vault
-    #[arg(long, value_name = "SECRET_NAME", exclusive = true, add = ArgValueCompleter::new(secrets_completer))]
-    pub delete_secret: Option<String>,
-    /// List all secrets stored in the Coyote vault
-    #[arg(long, exclusive = true)]
-    pub list_secrets: bool,
-    /// Authenticate with an LLM provider using OAuth (e.g., --authenticate client_name)
-    #[arg(long, exclusive = true, value_name = "CLIENT_NAME")]
-    pub authenticate: Option<Option<String>>,
-    /// Authenticate with an OAuth-protected remote MCP server (e.g., --auth-mcp server_name)
-    #[arg(long, exclusive = true, value_name = "SERVER_NAME", add = ArgValueCompleter::new(mcp_server_completer))]
-    pub auth_mcp: Option<String>,
-    /// Generate static shell completion scripts
-    #[arg(long, value_name = "SHELL", value_enum)]
-    pub completions: Option<ShellCompletion>,
+
+    /// Start an agent
+    #[arg(short = 'a', long, help_heading = "Agents, RAG & Macros", add = ArgValueCompleter::new(agent_completer))]
+    pub agent: Option<String>,
+    /// Set agent variables
+    #[arg(long, value_names = ["NAME", "VALUE"], num_args = 2, help_heading = "Agents, RAG & Macros")]
+    pub agent_variable: Vec<String>,
+    /// Start a RAG
+    #[arg(long, help_heading = "Agents, RAG & Macros", add = ArgValueCompleter::new(rag_completer))]
+    pub rag: Option<String>,
+    /// Rebuild the RAG to sync document changes
+    #[arg(long, help_heading = "Agents, RAG & Macros")]
+    pub rebuild_rag: bool,
+    /// Execute a macro
+    #[arg(long = "macro", value_name = "MACRO", help_heading = "Agents, RAG & Macros", add = ArgValueCompleter::new(macro_completer))]
+    pub macro_name: Option<String>,
+
+    /// List all available chat models
+    #[arg(long, help_heading = "List & Discovery")]
+    pub list_models: bool,
+    /// List all roles
+    #[arg(long, help_heading = "List & Discovery")]
+    pub list_roles: bool,
+    /// List all sessions
+    #[arg(long, help_heading = "List & Discovery")]
+    pub list_sessions: bool,
+    /// List all agents
+    #[arg(long, help_heading = "List & Discovery")]
+    pub list_agents: bool,
+    /// List all RAGs
+    #[arg(long, help_heading = "List & Discovery")]
+    pub list_rags: bool,
+    /// List all macros
+    #[arg(long, help_heading = "List & Discovery")]
+    pub list_macros: bool,
+    /// List all installed skills
+    #[arg(long, help_heading = "List & Discovery")]
+    pub list_skills: bool,
+
+    /// Reinstall bundled assets, overwriting any local changes
+    #[arg(
+        long,
+        value_name = "CATEGORY",
+        value_enum,
+        help_heading = "Installation & Updates"
+    )]
+    pub install: Option<AssetCategory>,
+    /// Install assets from a remote git repository (URL may be suffixed with #<ref>)
+    #[arg(long, value_name = "GIT_URL", help_heading = "Installation & Updates")]
+    pub install_from: Option<String>,
+    /// Restrict --install-from to a single asset category
+    #[arg(
+        long,
+        value_name = "CATEGORY",
+        value_enum,
+        requires = "install_from",
+        help_heading = "Installation & Updates"
+    )]
+    pub filter: Option<InstallFilter>,
+    /// Overwrite all conflicts without prompting (used with --install-from)
+    #[arg(
+        long,
+        requires = "install_from",
+        help_heading = "Installation & Updates"
+    )]
+    pub install_force: bool,
+    /// Sync models updates
+    #[arg(long, help_heading = "Installation & Updates")]
+    pub sync_models: bool,
     /// Update Coyote to the latest release, or to a specific version
-    #[arg(long, value_name = "VERSION")]
+    #[arg(long, value_name = "VERSION", help_heading = "Installation & Updates")]
     pub update: Option<Option<String>>,
     /// With --update, update even if Coyote was installed via a package manager
-    #[arg(long, requires = "update")]
+    #[arg(long, requires = "update", help_heading = "Installation & Updates")]
     pub force: bool,
+
+    /// Add a secret to the Coyote vault
+    #[arg(
+        long,
+        value_name = "SECRET_NAME",
+        exclusive = true,
+        help_heading = "Vault & Secrets"
+    )]
+    pub add_secret: Option<String>,
+    /// Decrypt a secret from the Coyote vault and print the plaintext
+    #[arg(long, value_name = "SECRET_NAME", exclusive = true, help_heading = "Vault & Secrets", add = ArgValueCompleter::new(secrets_completer))]
+    pub get_secret: Option<String>,
+    /// Update an existing secret in the Coyote vault
+    #[arg(long, value_name = "SECRET_NAME", exclusive = true, help_heading = "Vault & Secrets", add = ArgValueCompleter::new(secrets_completer))]
+    pub update_secret: Option<String>,
+    /// Delete a secret from the Coyote vault
+    #[arg(long, value_name = "SECRET_NAME", exclusive = true, help_heading = "Vault & Secrets", add = ArgValueCompleter::new(secrets_completer))]
+    pub delete_secret: Option<String>,
+    /// List all secrets stored in the Coyote vault
+    #[arg(long, exclusive = true, help_heading = "Vault & Secrets")]
+    pub list_secrets: bool,
+
+    /// Authenticate with an LLM provider using OAuth (e.g., --authenticate client_name)
+    #[arg(
+        long,
+        exclusive = true,
+        value_name = "CLIENT_NAME",
+        help_heading = "Authentication"
+    )]
+    pub authenticate: Option<Option<String>>,
+    /// Authenticate with an OAuth-protected remote MCP server (e.g., --auth-mcp server_name)
+    #[arg(long, exclusive = true, value_name = "SERVER_NAME", help_heading = "Authentication", add = ArgValueCompleter::new(mcp_server_completer))]
+    pub auth_mcp: Option<String>,
+
     /// Launch Coyote inside a Docker sandbox (via `sbx`); name defaults to current directory basename
-    #[arg(long, value_name = "NAME")]
+    #[arg(long, value_name = "NAME", help_heading = "Sandbox")]
     pub sandbox: Option<Option<String>>,
     /// Create the sandbox without bootstrapping the host config or vault password file
-    #[arg(long, requires = "sandbox")]
+    #[arg(long, requires = "sandbox", help_heading = "Sandbox")]
     pub fresh: bool,
     /// Skip discovery and application of all sbx mixins (user and built-in)
-    #[arg(long, requires = "sandbox")]
+    #[arg(long, requires = "sandbox", help_heading = "Sandbox")]
     pub no_mixins: bool,
-    /// Disable loading workspace MCP servers from .coyote/mcp.json
-    #[arg(long)]
-    pub no_workspace_mcp: bool,
+
+    /// Display information
+    #[arg(long, help_heading = "Diagnostics & Tools")]
+    pub info: bool,
+    /// Build all configured Bash tool scripts
+    #[arg(long, help_heading = "Diagnostics & Tools")]
+    pub build_tools: bool,
+    /// Tail logs
+    #[arg(long, help_heading = "Diagnostics & Tools")]
+    pub tail_logs: bool,
+    /// Disable colored log output
+    #[arg(long, requires = "tail_logs", help_heading = "Diagnostics & Tools")]
+    pub disable_log_colors: bool,
+
+    /// Generate static shell completion scripts
+    #[arg(long, value_name = "SHELL", value_enum, help_heading = "Shell")]
+    pub completions: Option<ShellCompletion>,
 }
 
 impl Cli {