docs(readme): add project overview, features, and setup instructions

Author: Akagi201

Cargo.toml

@@ -2,7 +2,13 @@
 version = "0.1.0"
 edition = "2024"
 license = "Apache-2.0"
-repository = "TODO"
+repository = "https://github.com/longcipher/bob"
+homepage = "https://github.com/longcipher/bob"
+readme = "README.md"
+authors = ["LongCipher Team"]
+description = "LLM-powered coding agent built in Rust with hexagonal architecture"
+keywords = ["ai", "agent", "llm", "coding", "automation"]
+categories = ["development-tools", "asynchronous", "api-bindings"]
 
 [workspace]
 members = ["bin/*", "crates/*"]

README.md

@@ -4,10 +4,33 @@
 [![Context7](https://img.shields.io/badge/Website-context7.com-blue)](https://context7.com/longcipher/bob)
 [![crates.io](https://img.shields.io/crates/v/bob-core.svg)](https://crates.io/crates/bob-core)
 [![docs.rs](https://docs.rs/bob-core/badge.svg)](https://docs.rs/bob-core)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE.md)
+[![Rust](https://img.shields.io/badge/rust-2024%20edition-orange.svg)](https://www.rust-lang.org/)
 
 ![bob](https://socialify.git.ci/longcipher/bob/image?font=Source+Code+Pro&language=1&name=1&owner=1&pattern=Circuit+Board&theme=Auto)
 
-Bob is an LLM-powered coding agent built in Rust with a hexagonal (ports & adapters) architecture. It connects to language models via the [`genai`](https://crates.io/crates/genai) crate and to external tools via [MCP](https://modelcontextprotocol.io/) servers using [`rmcp`](https://crates.io/crates/rmcp).
+**Bob** is an LLM-powered coding agent built in Rust with a hexagonal (ports & adapters) architecture. It connects to language models via the [`genai`](https://crates.io/crates/genai) crate and to external tools via [MCP](https://modelcontextprotocol.io/) servers using [`rmcp`](https://crates.io/crates/rmcp).
+
+## Features
+
+- 🤖 **Multi-Model Support**: Works with OpenAI, Anthropic, Google, Groq, and more
+- 🔧 **Tool Integration**: Connect to MCP servers for file operations, shell commands, and custom tools
+- 🎯 **Skill System**: Load and apply predefined skills for specialized tasks
+- 💬 **Interactive REPL**: Chat with the AI agent through a terminal interface
+- 🔄 **Streaming Responses**: Real-time streaming of LLM responses
+- 📊 **Observability**: Built-in tracing and event logging
+- 🏗️ **Clean Architecture**: Hexagonal (ports & adapters) design for extensibility
+
+## Crates
+
+This workspace contains the following crates:
+
+| Crate | Description | Links |
+|-------|-------------|-------|
+| **[bob-core](https://crates.io/crates/bob-core)** | Core domain types and port traits | [![docs.rs](https://docs.rs/bob-core/badge.svg)](https://docs.rs/bob-core) |
+| **[bob-runtime](https://crates.io/crates/bob-runtime)** | Runtime orchestration layer | [![docs.rs](https://docs.rs/bob-runtime/badge.svg)](https://docs.rs/bob-runtime) |
+| **[bob-adapters](https://crates.io/crates/bob-adapters)** | Adapter implementations | [![docs.rs](https://docs.rs/bob-adapters/badge.svg)](https://docs.rs/bob-adapters) |
+| **cli-agent** | CLI application | - |
 
 ## Architecture
 
@@ -18,38 +41,116 @@ crates/bob-runtime   — Scheduler FSM, prompt builder, action parser, Composite
 crates/bob-adapters  — Concrete adapter implementations (genai, rmcp, in-memory store, tracing)
 ```
 
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                     CLI Agent (bin)                         │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │              DefaultAgentRuntime                     │   │
+│  │  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │   │
+│  │  │Scheduler │→ │Prompt    │→ │Action Parser     │  │   │
+│  │  │  FSM     │  │Builder   │  │                  │  │   │
+│  │  └──────────┘  └──────────┘  └──────────────────┘  │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+            ↓ uses ports (traits) from bob-core
+┌─────────────────────────────────────────────────────────────┐
+│                  Adapters (bob-adapters)                    │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
+│  │GenAI LLM │  │MCP Tools │  │In-Memory │  │ Tracing  │   │
+│  │          │  │          │  │  Store   │  │  Events  │   │
+│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
 See [docs/design.md](docs/design.md) for the full design document.
 
 ## Quick Start
 
 ### Prerequisites
 
 ```bash
-# Install Rust (nightly for formatting)
-rustup install nightly
+# Install Rust (stable)
+rustup install stable
 
 # Install dev tools
 just setup
 ```
 
+### Installation
+
+#### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/longcipher/bob.git
+cd bob
+
+# Build
+cargo build --release
+
+# Run
+cargo run --release --bin cli-agent -- --config agent.toml
+```
+
+#### Using Cargo
+
+```bash
+# Install the CLI agent
+cargo install --git https://github.com/longcipher/bob cli-agent
+
+# Run
+cli-agent --config agent.toml
+```
+
 ### Configuration
 
-Create an `agent.toml` in the project root (see the included example):
+Create an `agent.toml` in the project root:
 
 ```toml
 [runtime]
-default_model = "gpt-4o-mini"
+default_model = "openai:gpt-4o-mini"
 max_steps = 12
-
-# Optional: MCP tool server
-# [mcp]
-# [[mcp.servers]]
-# id = "filesystem"
-# command = "npx"
-# args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+turn_timeout_ms = 90000
+model_context_tokens = 128000
+
+# Optional: Configure MCP tool servers
+[mcp]
+[[mcp.servers]]
+id = "filesystem"
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+tool_timeout_ms = 15000
+
+# Optional: Configure skills
+[skills]
+max_selected = 3
+token_budget_ratio = 0.1
+
+[[skills.sources]]
+source_type = "directory"
+path = "./skills"
+recursive = false
+
+# Optional: Configure policies
+[policy]
+deny_tools = ["local/shell_exec"]
+allow_tools = ["local/read_file", "local/write_file"]
 ```
 
-Set your LLM provider API key as an environment variable (e.g. `OPENAI_API_KEY`).
+### Environment Variables
+
+Set your LLM provider API key:
+
+```bash
+# For OpenAI
+export OPENAI_API_KEY="sk-..."
+
+# For Anthropic
+export ANTHROPIC_API_KEY="sk-ant-..."
+
+# For Google
+export GEMINI_API_KEY="..."
+```
 
 ### Run
 
@@ -59,7 +160,59 @@ cargo run --bin cli-agent -- --config agent.toml
 
 The REPL prints `>` when ready. Type a message and press Enter. Use `/quit` to exit.
 
-### Development
+### Example Session
+
+```text
+> Read the main.rs file and explain what it does
+
+I'll read the main.rs file for you...
+
+[uses filesystem tool to read the file]
+
+The main.rs file implements the CLI agent composition root. It loads
+configuration, wires up adapters (LLM, tools, storage, events), creates
+the runtime, and runs the REPL loop.
+
+> Now add error handling to that function
+
+[agent modifies the code]
+
+I've added error handling to the function. The changes include:
+- Using `Result` return type
+- Adding context with `.wrap_err()`
+- Handling specific error cases
+```
+
+## Supported LLM Providers
+
+Bob supports all providers available through [`genai`](https://crates.io/crates/genai):
+
+| Provider | Model Examples | Configuration |
+|----------|---------------|---------------|
+| **OpenAI** | `gpt-4o`, `gpt-4o-mini` | Set `OPENAI_API_KEY` |
+| **Anthropic** | `claude-3-5-sonnet-20241022` | Set `ANTHROPIC_API_KEY` |
+| **Google** | `gemini-2.0-flash-exp` | Set `GEMINI_API_KEY` |
+| **Groq** | `llama-3.3-70b-versatile` | Set `GROQ_API_KEY` |
+| **Cohere** | `command-r-plus` | Set `COHERE_API_KEY` |
+
+## MCP Tools
+
+Bob integrates with [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers:
+
+### Official MCP Servers
+
+- **Filesystem**: `@modelcontextprotocol/server-filesystem`
+- **GitHub**: `@modelcontextprotocol/server-github`
+- **PostgreSQL**: `@modelcontextprotocol/server-postgres`
+- **Slack**: `@modelcontextprotocol/server-slack`
+
+### Custom MCP Servers
+
+You can build custom MCP servers in any language that supports the protocol.
+
+## Development
+
+### Development Commands
 
 ```bash
 # Format code
@@ -75,6 +228,22 @@ just test
 just ci
 ```
 
+### Project Structure
+
+```text
+.
+├── bin/
+│   └── cli-agent/          # CLI application
+├── crates/
+│   ├── bob-core/           # Domain types and ports
+│   ├── bob-runtime/        # Runtime orchestration
+│   └── bob-adapters/       # Adapter implementations
+├── docs/
+│   └── design.md           # Architecture design
+├── specs/                  # Task specifications
+└── .opencode/              # AI development skills
+```
+
 ## Workspace Configuration
 
 ### Linting Philosophy
@@ -98,6 +267,68 @@ cargo add <crate> --workspace
 cargo add <crate> -p <crate-name>
 ```
 
+## Publishing
+
+### Publishing to crates.io
+
+Each library crate can be published independently:
+
+```bash
+# Publish bob-core
+cargo publish -p bob-core
+
+# Publish bob-runtime
+cargo publish -p bob-runtime
+
+# Publish bob-adapters
+cargo publish -p bob-adapters
+```
+
+### Documentation
+
+Documentation is automatically generated on [docs.rs](https://docs.rs) when published to crates.io:
+
+- [bob-core docs](https://docs.rs/bob-core)
+- [bob-runtime docs](https://docs.rs/bob-runtime)
+- [bob-adapters docs](https://docs.rs/bob-adapters)
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run `just ci` to ensure all checks pass
+5. Submit a pull request
+
+## Roadmap
+
+- [ ] Persistent session storage (SQLite, PostgreSQL)
+- [ ] Web UI for agent interaction
+- [ ] Multi-agent collaboration
+- [ ] Custom skill marketplace
+- [ ] Agent memory and context management
+- [ ] Tool composition and chaining
+- [ ] More MCP server integrations
+
 ## License
 
-MIT
+Licensed under the Apache License, Version 2.0. See [LICENSE.md](LICENSE.md) for details.
+
+## Acknowledgments
+
+- [genai](https://crates.io/crates/genai) - Unified LLM API
+- [rmcp](https://crates.io/crates/rmcp) - MCP client implementation
+- [agent-skills](https://crates.io/crates/agent-skills) - Skill system
+- [Model Context Protocol](https://modelcontextprotocol.io/) - Tool integration protocol
+
+## Support
+
+- **Documentation**: [docs.rs](https://docs.rs/bob-core)
+- **Issues**: [GitHub Issues](https://github.com/longcipher/bob/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/longcipher/bob/discussions)
+
+---
+
+**Note**: This project is in active development. APIs may change between versions.

bin/cli-agent/Cargo.toml

@@ -2,6 +2,14 @@
 name = "cli-agent"
 version.workspace = true
 edition.workspace = true
+license.workspace = true
+repository.workspace = true
+homepage.workspace = true
+authors.workspace = true
+description = "CLI agent for Bob - LLM-powered coding assistant"
+keywords = ["cli", "agent", "ai", "llm", "coding-assistant"]
+categories = ["command-line-utilities", "development-tools"]
+readme = "README.md"
 
 [dependencies]
 async-trait = { workspace = true }