docs: add FAQ section for common questions

README.md

@@ -56,9 +56,9 @@ Any [LiteLLM-supported model](https://docs.litellm.ai/docs/providers) works.
 ## Run
 
 ```bash
-pentestagent                    # Launch TUI
-pentestagent -t 192.168.1.1     # Launch with target
-pentestagent --docker           # Run tools in Docker container
+pentestagent                      # Launch TUI
+pentestagent -t 192.168.1.1       # Launch with target
+pentestagent tui --docker         # Run tools in Docker container
 ```
 
 ## Docker
@@ -123,6 +123,10 @@ PentestAgent has three modes, accessible via commands in the TUI:
 /memory           Show token/memory usage
 /prompt           Show system prompt
 /mcp <list/add>   Visualizes or adds a new MCP server.
+/spawn [target] [--scope CIDR] [--model M] [--no-rag] [--no-mcp]
+                  Manually spawn a child MCP agent from the TUI.
+/despawn <server_name>
+                  Terminate and remove a previously spawned child agent.
 /clear            Clear chat and history
 /quit             Exit (also /exit, /q)
 /help             Show help (also /h, /?)
@@ -182,6 +186,48 @@ child_agent_1__get_task_result  task_id="<id1>"
 child_agent_2__get_task_result  task_id="<id2>"
 ```
 
+### Manual Child Agent Control (`/spawn` and `/despawn`)
+
+Beyond the automatic `spawn_mcp_agent` tool, the TUI exposes two commands that let you spawn and terminate child agents **manually**, independently of a running agent loop.
+
+#### `/spawn`
+
+```
+/spawn [target] [--scope CIDR ...] [--model MODEL] [--no-rag] [--no-mcp]
+```
+
+Spawns a new child MCP agent over stdio and attaches it to the current session. The child appears as a collapsible terminal panel in the TUI sidebar and its tools become available to the parent agent on the next tool call.
+
+| Argument | Description |
+|----------|-------------|
+| `target` | Pentest target to pass to the child (positional or `--target`) |
+| `--scope CIDR` | One or more in-scope CIDRs (repeatable) |
+| `--model MODEL` | Override the model for the child agent |
+| `--no-rag` | Skip RAG engine initialisation on the child |
+| `--no-mcp` | Skip external MCP server connections on the child |
+
+**Examples:**
+
+```
+/spawn 10.0.1.1
+/spawn 10.0.1.1 --scope 10.0.1.0/24 --model claude-sonnet-4-20250514
+/spawn --target 10.0.1.1 --scope 10.0.1.0/24 --no-rag
+```
+
+#### `/despawn`
+
+```
+/despawn <server_name>
+```
+
+Terminates the child agent identified by `server_name` (e.g. `child_agent_1`), removes its terminal panel from the TUI, and disconnects its tools from the parent session. Use `/mcp list` to see the names of all currently active child agents.
+
+**Example:**
+
+```
+/despawn child_agent_1
+```
+
 ### MCP RAG Tool Optimizer
 
 When an MCP server exposes more than 128 tools, PentestAgent automatically replaces the full catalogue with a single `mcp_<server>_rag_optimizer` tool. This meta-tool uses embedding similarity (via LiteLLM, default `text-embedding-3-small`) to retrieve the most relevant tools for the task at hand and injects them into the agent's next turn — keeping the context window manageable without losing access to the full tool set.
@@ -408,6 +454,150 @@ ruff check pentestagent      # Lint
 
 Only use against systems you have explicit authorization to test. Unauthorized access is illegal.
 
+
+## FAQ
+
+### General
+
+**What is PentestAgent?**
+
+PentestAgent is an AI-powered penetration testing framework for black-box security testing. It supports bug bounty, red-team, and penetration testing workflows with autonomous agent execution, multi-agent collaboration (Crew mode), and MCP tool extensibility.
+
+**How does PentestAgent differ from Metasploit or Burp Suite?**
+
+PentestAgent is an AI orchestration layer that can use tools like nmap, msfconsole, and curl. It doesn't replace them — it coordinates them autonomously. You describe the objective, and the agent decides which tools to run, when, and how to chain results.
+
+### Installation & Setup
+
+**What Python version is required?**
+
+Python 3.10+ is required.
+
+**How do I install PentestAgent?**
+
+Clone the repo and run the setup script:
+```bash
+git clone https://github.com/GH05TCREW/pentestagent.git
+cd pentestagent
+./scripts/setup.sh  # Linux/macOS
+.\scripts\setup.ps1  # Windows
+```
+
+Or manually with `pip install -e ".[all]"` and `playwright install chromium`.
+
+**What API keys do I need?**
+
+You need an API key from any LiteLLM-supported provider (OpenAI, Anthropic, DeepSeek, etc.). Set it in `.env`:
+```
+ANTHROPIC_API_KEY=sk-ant-...
+PENTESTAGENT_MODEL=claude-sonnet-4-20250514
+```
+
+### LLM Providers
+
+**Which LLM providers are supported?**
+
+Any LiteLLM-supported provider works: OpenAI (GPT-4/GPT-5), Anthropic (Claude), DeepSeek, Qwen, local models via Ollama/vLLM, and more.
+
+**Can I use local models?**
+
+Yes, via LiteLLM's Ollama or vLLM integration. Set `PENTESTAGENT_MODEL=ollama/llama3` or similar.
+
+### Modes & Usage
+
+**What are the different modes?**
+
+| Mode | Description |
+|------|-------------|
+| Assist | Single-shot instruction with tool execution |
+| Agent | Autonomous execution of a single task |
+| Crew | Multi-agent mode with orchestrator spawning specialized workers |
+| Interact | Interactive guided mode where the agent helps step-by-step |
+
+**When should I use Crew mode?**
+
+Crew mode is best for complex, multi-phase assessments where different agents can work in parallel on reconnaissance, exploitation, and post-exploitation tasks.
+
+**How do I run a playbook?**
+
+```bash
+pentestagent run -t example.com --playbook thp3_web
+```
+
+Playbooks provide structured approaches to specific security assessments.
+
+### MCP & Tools
+
+**How do I add MCP servers?**
+
+Edit `mcp_servers.json` or use the CLI:
+```bash
+pentestagent mcp add nmap npx -y gc-nmap-mcp
+```
+
+**What is the spawn_mcp_agent tool?**
+
+It allows a running agent to spawn child copies of itself as MCP servers. Each child is fully isolated with its own runtime, LLM client, and tool set. This enables hierarchical multi-agent workflows.
+
+**How do I spawn a child agent manually?**
+
+Use `/spawn` in the TUI:
+```
+/spawn 10.0.1.1 --scope 10.0.1.0/24 --model claude-sonnet-4-20250514
+```
+
+**What happens when an MCP server has >128 tools?**
+
+PentestAgent replaces the full catalogue with a `mcp_<server>_rag_optimizer` meta-tool that retrieves relevant tools via embedding similarity.
+
+### Docker
+
+**Why use Docker mode?**
+
+Docker provides isolation and pre-installed pentesting tools (nmap, metasploit, sqlmap, etc.) without modifying your host system.
+
+**How do I run in Docker?**
+
+```bash
+pentestagent tui --docker
+# Or pull the pre-built image
+docker run -it -e ANTHROPIC_API_KEY=your-key ghcr.io/gh05tcrew/pentestagent:kali
+```
+
+### Troubleshooting
+
+**Agent is not executing tools.**
+
+- Check API key in `.env`
+- Verify target is set (`/target <host>` or `-t` flag)
+- Ensure tools are enabled (`/tools` to list)
+
+**Child agent not responding.**
+
+- Check child's model override with `--model`
+- Use `/mcp list` to verify child is spawned
+- Use `/despawn <name>` to terminate and respawn
+
+**MCP server connection failed.**
+
+- Use `pentestagent mcp test <name>` to diagnose
+- Check `mcp_servers.json` for correct command/args
+- Verify the MCP server package is installed
+
+**Where are notes stored?**
+
+Notes are saved to `loot/notes.json` and persist across sessions. Use `/notes` to view.
+
+**How do I generate a report?**
+
+Use `/report` in the TUI to generate a report from the current session.
+
+### Legal & Ethics
+
+**Can I use PentestAgent on any system?**
+
+No. Only use against systems you have **explicit authorization** to test. Unauthorized access is illegal.
+
 ## License
 
-MIT
+MIT