feat: update examples and documentation to use ls, jq, and curl, and fix root-only tool execution target logic

Author: tercel

README.md

@@ -11,7 +11,7 @@ Outside-In CLI-to-Agent Bridge — automatically wraps existing CLI tools into g
 
 ## What is apexe?
 
-`apexe` scans any CLI tool on your system (e.g., `git`, `curl`, `grep`, `find`, `lsof`), deterministically extracts its command structure, flags, and arguments — then exposes them as governed MCP tools that AI agents can invoke safely.
+`apexe` scans any CLI tool on your system (e.g., `git`, `curl`, `ls`, `jq`), deterministically extracts its command structure, flags, and arguments — then exposes them as governed MCP tools that AI agents can invoke safely.
 
 **No LLM required for scanning. No changes to the CLI tools. Zero-config governance.**
 
@@ -87,7 +87,7 @@ apexe serve --show-config cursor
 Scan CLI tools and generate binding files + ACL rules.
 
 ```bash
-apexe scan git curl grep lsof           # Scan multiple tools
+apexe scan ls jq curl                   # Scan multiple tools
 apexe scan git --depth 3               # 3 levels of subcommands (default: 2, max: 5)
 apexe scan git --no-cache              # Force re-scan
 apexe scan git --format json           # Output as JSON (also: yaml, table)

docs/quickstart.md

@@ -52,7 +52,7 @@ Open `http://127.0.0.1:8000` in a browser to explore available tools.
 ## Scan more tools
 
 ```bash
-apexe scan curl grep find lsof
+apexe scan ls curl jq
 ```
 
 ## See what you have

docs/user-manual.md

@@ -91,7 +91,7 @@ apexe scan <TOOLS>... [OPTIONS]
 
 ```bash
 apexe scan git                         # basic scan
-apexe scan git curl grep lsof          # multiple tools
+apexe scan ls jq curl                  # multiple tools
 apexe scan git --depth 3               # deeper subcommand discovery
 apexe scan git --no-cache              # force re-scan
 apexe scan git --format json           # JSON output

examples/README.md

@@ -204,7 +204,7 @@ server.serve()?; // blocking — starts the server
 ### Scan multiple tools at once
 
 ```bash
-apexe scan git curl grep find lsof --depth 3
+apexe scan ls jq curl --no-cache
 apexe list
 # Shows all modules from all tools
 ```
@@ -214,16 +214,56 @@ apexe list
 ```bash
 apexe serve --transport http --port 8000 --explorer
 # Open http://127.0.0.1:8000/explorer in your browser
-# Browse tools, view schemas, test invocations
 ```
 
-### Try it: Call tools via MCP (curl examples)
+### Try it: Explorer UI step-by-step
+
+1. **Scan ls, jq, and curl**:
+
+```bash
+apexe scan ls jq curl --no-cache
+apexe serve --transport http --port 8000 --explorer
+```
+
+2. **Open** http://127.0.0.1:8000/explorer in your browser
+
+3. **Click `cli.ls`** → type `{}` → click **Call**. Instant file listing:
+
+```json
+{}
+```
+
+**Response:**
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\"stdout\":\"Cargo.toml\\nREADME.md\\nsrc\\n...\",\"stderr\":\"\",\"exit_code\":0}"
+    }
+  ]
+}
+```
+
+4. **Click `cli.jq`** → 22 form fields! Try:
+
+```json
+{"compact_output": true, "raw_output": true}
+```
+
+5. **Click `cli.curl`** → 12 form fields. Try:
+
+```json
+{"verbose": true, "silent": true}
+```
+
+### Try it: Call tools via MCP API (full control)
 
 Start the server in one terminal, then call tools from another:
 
 ```bash
 # Terminal 1: start server
-apexe scan ls curl grep find
+apexe scan ls jq curl --no-cache
 apexe serve --transport http --port 8000 --explorer
 ```
 

examples/basic/README.md

@@ -1,11 +1,11 @@
-# Basic Example: Scan Git, Serve via MCP
+# Basic Example: Scan Tools, Explore via Browser
 
-This example scans `git`, generates binding files, and starts an MCP server that Claude Desktop or Cursor can use.
+Scans `ls` (instant result), `jq` (22 flags), and `curl` (12 flags), then starts an HTTP server with Explorer UI for browser-based testing.
 
 ## Prerequisites
 
 - `apexe` installed (`cargo install --path ../..`)
-- `git` on your `$PATH`
+- `ls`, `jq`, and `curl` on your `$PATH`
 
 ## Run
 
@@ -15,26 +15,34 @@ This example scans `git`, generates binding files, and starts an MCP server that
 
 ## What it does
 
-1. Scans `git` with depth 2 (discovers `git commit`, `git push`, `git status`, etc.)
+1. Scans `ls`, `jq`, and `curl` (extracts flags and generates JSON Schema)
 2. Writes binding files to `./output/modules/`
-3. Writes ACL rules to `./output/acl.yaml`
-4. Shows the scan results and generated modules
-5. Prints Claude Desktop and Cursor integration configs
-6. Starts the MCP server on stdio (Ctrl+C to stop)
+3. Prints Claude Desktop and Cursor integration configs
+4. Starts HTTP server with Explorer UI at http://127.0.0.1:8000/explorer
 
-## Generated files
+## Using the Explorer UI
 
+1. Open **http://127.0.0.1:8000/explorer** in your browser
+
+2. Click **`cli.ls`** → type `{}` → click **Call**:
+```json
+{}
 ```
-output/
-  modules/
-    *.binding.yaml     # One file per scanned module
-  acl.yaml             # Access control rules (readonly=allow, destructive=deny)
+You'll see your current directory listing immediately. This is the quickest way to verify apexe works.
+
+3. Click **`cli.curl`** → it has form fields for `data`, `verbose`, `silent`, etc. Try:
+```json
+{"verbose": true}
 ```
 
+4. The response includes `stdout`, `stderr`, `exit_code`, `trace_id`, and `duration_ms`
+
 ## Claude Desktop integration
 
-Copy the output of step 5 into your Claude Desktop config:
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Linux: `~/.config/claude/claude_desktop_config.json`
+After testing with Explorer, switch to stdio for Claude Desktop:
+
+```bash
+apexe serve --show-config claude-desktop
+```
 
-Then restart Claude Desktop. Git commands will appear as MCP tools.
+Copy the JSON into `~/Library/Application Support/Claude/claude_desktop_config.json`, restart Claude Desktop.

examples/basic/run.sh

@@ -1,46 +1,48 @@
 #!/usr/bin/env bash
-# apexe basic example: scan git, inspect results, start MCP server.
+# apexe basic example: scan tools, inspect results, start MCP server.
 set -euo pipefail
 
 OUTPUT_DIR="./output"
 MODULES_DIR="$OUTPUT_DIR/modules"
 
-echo "=== Step 1: Scan git ==="
-apexe scan git --output-dir "$MODULES_DIR" --depth 2 --format table
+echo "=== Step 1: Scan tools ==="
+echo "  ls   — simple tool, runs with {} immediately"
+echo "  jq   — 22 flags with full schema (best Explorer demo)"
+echo "  curl — 12 flags (GNU format)"
+echo
+apexe scan ls jq curl --no-cache --output-dir "$MODULES_DIR" --format table
 echo
 
 echo "=== Step 2: List generated modules ==="
 apexe list --modules-dir "$MODULES_DIR"
 echo
 
-echo "=== Step 3: Inspect ACL ==="
-if [ -f "$HOME/.apexe/acl.yaml" ]; then
-    echo "ACL rules at ~/.apexe/acl.yaml:"
-    cat "$HOME/.apexe/acl.yaml"
-else
-    echo "(ACL file not found — may have been written to default location)"
-fi
-echo
-
-echo "=== Step 4: Inspect a binding file ==="
+echo "=== Step 3: Inspect binding file (check the schema properties) ==="
 FIRST_BINDING=$(ls "$MODULES_DIR"/*.binding.yaml 2>/dev/null | head -1)
 if [ -n "$FIRST_BINDING" ]; then
-    echo "First binding file: $FIRST_BINDING"
-    head -40 "$FIRST_BINDING"
+    echo "Binding file: $FIRST_BINDING"
+    head -50 "$FIRST_BINDING"
     echo "..."
 fi
 echo
 
-echo "=== Step 5: Integration configs ==="
+echo "=== Step 4: Integration configs ==="
 echo "--- Claude Desktop ---"
 apexe serve --show-config claude-desktop --modules-dir "$MODULES_DIR"
 echo
 echo "--- Cursor ---"
 apexe serve --show-config cursor --modules-dir "$MODULES_DIR"
 echo
 
-echo "=== Step 6: Start MCP server (stdio) ==="
+echo "=== Step 5: Start HTTP server with Explorer UI ==="
+echo "Open http://127.0.0.1:8000/explorer in your browser."
+echo "Click 'cli.curl' → fill in JSON input → click Call."
+echo ""
+echo "Try in Explorer:"
+echo '  cli.ls   → input: {}                        → file listing (instant result!)'
+echo '  cli.jq   → input: {"compact_output": true}  → 22 flags with form fields'
+echo '  cli.curl → input: {"verbose": true}          → 12 flags with form fields'
+echo ""
 echo "Press Ctrl+C to stop."
-echo "In production, this is launched by Claude Desktop / Cursor, not run manually."
 echo
-apexe serve --transport stdio --modules-dir "$MODULES_DIR"
+apexe serve --transport http --port 8000 --explorer --modules-dir "$MODULES_DIR"

src/adapter/converter.rs

@@ -72,7 +72,13 @@ impl CliToolConverter {
             help_format_to_tag(command_opt.map_or(HelpFormat::Unknown, |c| c.help_format));
 
         let tags = self.build_tags(tool, command_opt, help_format_name);
-        let target = format!("exec://{} {}", tool.binary_path, full_command);
+        // For root-only tools (no subcommands), target is just the binary path.
+        // For subcommands, include the command path (e.g., "exec:///usr/bin/git commit").
+        let target = if path.is_empty() {
+            format!("exec://{}", tool.binary_path)
+        } else {
+            format!("exec://{} {}", tool.binary_path, full_command)
+        };
         let version = tool
             .version
             .clone()
@@ -488,6 +494,8 @@ mod tests {
 
         assert_eq!(modules.len(), 1);
         assert_eq!(modules[0].module_id, "cli.ffmpeg");
+        // Root-only target should NOT repeat the tool name as an argument
+        assert_eq!(modules[0].target, "exec:///usr/bin/ffmpeg");
     }
 
     #[test]