Add documentation site + refresh crate READMEs

.github/workflows/deploy-mkdocs.yml

@@ -0,0 +1,24 @@
+name: MkDocs Build and Deploy
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      - name: Deploy MkDocs
+        uses: Reloaded-Project/devops-mkdocs@v1
+        with:
+          requirements: ./docs/requirements.txt
+          publish-to-pages: ${{ github.event_name == 'push' }}
+          checkout-current-repo: true
+          docs-directory: docs

.gitignore

@@ -7,3 +7,4 @@ PROMPT-*.MD
 # Local Code Review
 .vscode/local-reviews
 src/.vscode/local-reviews
+

README.MD

@@ -1,105 +1,162 @@
+<div align="center">
+
 # llm-coding-tools
 
-[![CI](https://github.com/Sewer56/llm-coding-tools/actions/workflows/rust.yml/badge.svg)](https://github.com/Sewer56/llm-coding-tools/actions)
+**Production-grade coding agent tools in Rust. <abbr title="~10 MiB PSS on release build, all providers enabled.&#10;  • Code &amp; read-only data: ~6.5 MiB&#10;  • Heap (runtime state): ~2.5 MiB&#10;  • Shared libraries (glibc, libm): ~2.3 MiB&#10;  • Thread stacks: ~0.1 MiB (34 threads)&#10;  Private ~2.5 MiB · RSS ~13 MiB.">~10 MiB</abbr>. No TUI. Embed it anywhere.**
 
-Lightweight, heavily optimized coding tool implementations for LLM-powered
-development agents.
+[![CI](https://github.com/Sewer56/llm-coding-tools/actions/workflows/rust.yml/badge.svg)](https://github.com/Sewer56/llm-coding-tools/actions) [![crates.io](https://img.shields.io/crates/v/llm-coding-tools-core.svg)](https://crates.io/crates/llm-coding-tools-core) [![docs.rs](https://img.shields.io/docsrs/llm-coding-tools-core)](https://docs.rs/llm-coding-tools-core) [![License](https://img.shields.io/crates/l/llm-coding-tools-core)](./LICENSE)
 
-Suitable for server use (<3 MiB), or as building blocks for your own TUI coding agent.
+[Get Started](#quick-start) · [Documentation](https://sewer56.github.io/llm-coding-tools/) · [API Reference](https://docs.rs/llm-coding-tools-core) · [Examples](#examples)
 
-## About This Workspace
+</div>
 
-This workspace contains multiple Rust crates for integrating coding tools with
-LLM agents:
+---
 
-- **[llm-coding-tools-core](./src/llm-coding-tools-core/)**:
-  Framework-agnostic core operations and utilities
-- **[llm-coding-tools-agents](./src/llm-coding-tools-agents/)**:
-  OpenCode agent markdown loader and typed catalogue
-- **[llm-coding-tools-serdesai](./src/llm-coding-tools-serdesai/)**:
-  serdesAI framework-specific Tool implementations
-- **[llm-coding-tools-bubblewrap](./src/llm-coding-tools-bubblewrap/)**:
-  Sandboxing for Bash tool on Linux based on `bwrap` tool
-- **[llm-coding-tools-models-dev](./src/llm-coding-tools-models-dev/)**:
-  models.dev catalog sync with cached fallback and ETag refresh
+## Why this project?
 
-## Features
+llm-coding-tools started as "an OpenCode for servers." Headless,
+sandboxed, and cheap to host for non-commercial use.
 
-- **File Operations**: Read, write, edit files with line-numbered output
-- **Search**: Glob pattern matching and regex content search  
-- **Shell**: Cross-platform command execution with timeout; with optional sandboxing on Linux.
-- **Web**: URL fetching with HTML-to-markdown conversion
-- **Path Security**: Choose between unrestricted or sandboxed file access
-- **OpenCode Agents**: Support for OpenCode-style agents
-- **Model Catalog Sync**: Download and cache the models.dev catalog for
-  provider/model lookups
-- **Optimized System Prompt**: Built-in tool guidance stays compact.
-    Full tool set is ~2000 tokens; search-only drops to ~560
+[OpenCode](https://opencode.ai) is a great interactive coding agent, but it's a
+<abbr title="opencode v1.14.21&#10;serve: 305 MiB RSS&#10;TUI: 525 MiB RSS&#10;&#10;v1.4.2&#10;serve: 392 MiB RSS&#10;TUI: 679 MiB RSS">~305 MiB</abbr> TypeScript application that runs as a separate process.
+What if you need those same tools for a **server**? A **Discord bot**?
+A **CI pipeline**? A **custom product**?
 
-## Feature Flags (llm-coding-tools-core)
+**llm-coding-tools** ships the same agent tools as a Rust library.
+Shell sandboxing. Default-deny permissions. ~10 MiB footprint.
 
-- `tokio` (default): Async mode with tokio runtime
-- `blocking`: Sync/blocking mode, mutually exclusive with `async`
-- `linux-bubblewrap`: Sandboxing for `bash` tool via Linux `bwrap` tool
+|              | OpenCode                                                                                          | llm-coding-tools                                                                                                                                                                                                                                                                                         |
+| ------------ | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Language     | TypeScript                                                                                        | Rust                                                                                                                                                                                                                                                                                                     |
+| Memory       | <abbr title="opencode v1.14.21&#10;serve: 305 MiB RSS&#10;TUI: 525 MiB RSS&#10;&#10;v1.4.2&#10;serve: 392 MiB RSS&#10;TUI: 679 MiB RSS">~305 MiB</abbr> | <abbr title="~13 MiB RSS on release build, all providers enabled.&#10;  • Code &amp; read-only data: ~6.5 MiB&#10;  • Heap (runtime state): ~2.5 MiB&#10;  • Shared libraries (glibc, libm): ~2.3 MiB&#10;  • Thread stacks: ~0.1 MiB (34 threads)&#10;  Private ~2.5 MiB · PSS ~10 MiB.">~13 MiB</abbr> |
+| Interface    | TUI / Desktop / IDE                                                                               | Library (headless)                                                                                                                                                                                                                                                                                       |
+| Agent format | Markdown + YAML                                                                                   | Similar format                                                                                                                                                                                                                                                                                           |
+| Embeddable   | HTTP API                                                                                          | Rust crate                                                                                                                                                                                                                                                                                               |
 
-## Quick Start
+## Features
 
-Pick the crate that matches your use case:
+- **10 Built-in tools** - read, write, edit, glob, grep, bash, webfetch, todoread, todowrite, task
+- **Agents similar to [OpenCode](https://opencode.ai)** - load agent markdown files with YAML frontmatter
+- **Multi-agent delegation** - orchestrator pattern with depth-limited task chains
+- **Linux sandboxing** - bubblewrap profiles for shell isolation (Public Bot + Trusted Maintenance)
+- **Path security** - restrict file access with allowed directories and glob-based rules
+- **Model catalog** - sync [models.dev](https://models.dev) with ETag caching (~3000 models, ~24 KiB cache)
+- **Permissions** - default-deny with last-match-wins rules and wildcard patterns
+- **Optimized system prompt** - auto-generated, ~2000 tokens full / ~560 search-only
+- **Async + Sync** - every tool compiles as tokio async or blocking. Zero overhead.
+- **Framework-agnostic core** - use the serdesAI integration or bring your own framework
+- **15 LLM providers** - OpenAI, Anthropic, Google, Groq, Mistral, Ollama, Azure, Bedrock, and more
+- **Semver-guaranteed API** - 6-platform CI matrix, 11 semver surfaces, clippy -D warnings
+
+## Quick Start
 
 ```toml
 [dependencies]
-llm-coding-tools-core = "0.2"         # Framework-agnostic tool implementations
-llm-coding-tools-agents = "0.1"       # OpenCode agent markdown loader
-llm-coding-tools-models-dev = "0.1"   # models.dev catalog sync and cache
-llm-coding-tools-serdesai = "0.2"     # serdesAI integration
-llm-coding-tools-bubblewrap = "0.1"   # Linux Bubblewrap profile and wrapper helpers
+llm-coding-tools-serdesai = "0.2"
 ```
 
-For a runnable agent setup, start with `llm-coding-tools-serdesai` and the
-examples below.
+**1.** Create an agent file (markdown + YAML frontmatter similar to [OpenCode](https://opencode.ai)):
+
+```markdown
+---
+name: coder
+mode: all
+description: A coding agent that can read, search, and edit files.
+permission:
+  read: allow
+  write: allow
+  edit: allow
+  glob: allow
+  grep: allow
+  bash: allow
+  webfetch: allow
+  task: deny
+---
+
+You are a coding assistant. Use the available tools to complete the user's task.
+```
+
+**2.** Load the catalog, build the agent, and run:
+
+```rust
+use llm_coding_tools_agents::{AgentCatalog, AgentLoader, AgentRuntimeBuilder};
+use llm_coding_tools_core::CredentialResolver;
+use llm_coding_tools_models_dev::ModelsDevCatalog;
+use llm_coding_tools_serdesai::{AgentBuildContext, AgentDefaults};
+use std::{path::PathBuf, sync::Arc};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Load agents from the "agents" directory.
+    let mut catalog = AgentCatalog::new();
+    AgentLoader::new().add_directory(&mut catalog, "./agents")?;
+
+    // Supports any model from https://models.dev
+    let load_result = ModelsDevCatalog::load().await?;
+
+    let runtime = AgentRuntimeBuilder::new()
+        .catalog(catalog) // Default model if not specified by agent.
+        .defaults(AgentDefaults::with_model("synthetic/hf:MiniMaxAI/MiniMax-M2.5"))
+        .build()?;
+
+    let build_context = AgentBuildContext::new(
+        Arc::new(runtime),
+        Arc::new(load_result.catalog),
+        Arc::new(CredentialResolver::new()),
+    );
+
+    let agent = build_context.build("coder")?;
+    let response = agent.run("Find all TODO comments in src/", ()).await?;
+    println!("{}", response.output());
+    Ok(())
+}
+```
+
+## Crate Map
+
+| Crate                                                                 | Version | Description                                                                                      |
+| --------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |
+| [**llm-coding-tools-core**](./src/llm-coding-tools-core/)             | 0.2     | Framework-agnostic tool implementations, path resolvers, permissions, system prompt builder      |
+| [**llm-coding-tools-agents**](./src/llm-coding-tools-agents/)         | 0.1     | agent markdown loader similar to [OpenCode](https://opencode.ai), typed catalog, runtime builder |
+| [**llm-coding-tools-serdesai**](./src/llm-coding-tools-serdesai/)     | 0.2     | SerdesAI framework integration, tool adapters, 15 provider bridges, task delegation              |
+| [**llm-coding-tools-bubblewrap**](./src/llm-coding-tools-bubblewrap/) | 0.1     | Linux bubblewrap sandbox profiles (Public Bot + Trusted Maintenance)                             |
+| [**llm-coding-tools-models-dev**](./src/llm-coding-tools-models-dev/) | 0.1     | models.dev catalog sync with ETag caching and offline fallback                                   |
 
 ## Examples
 
 ```bash
-# serdesAI framework - Basic agent setup
+# Basic agent setup with all tools
 cargo run --example serdesai-basic -p llm-coding-tools-serdesai
 
-# serdesAI framework - Sandboxed file access
+# Sandboxed file access (restricted to allowed directories)
 cargo run --example serdesai-sandboxed -p llm-coding-tools-serdesai
 
-# serdesAI framework - Agent catalog loading
+# Sandboxed bash execution (Linux, requires bubblewrap)
+cargo run --example serdesai-sandboxed-bash --features linux-bubblewrap -p llm-coding-tools-serdesai
+
+# Agent catalog loading from markdown files
 cargo run --example serdesai-agents -p llm-coding-tools-serdesai
 
-# serdesAI framework - Task delegation
+# Multi-agent task delegation (orchestrator + reader sub-agent)
 cargo run --example serdesai-task -p llm-coding-tools-serdesai
 ```
 
 ## Documentation
 
+- **[Documentation Site](https://sewer56.github.io/llm-coding-tools/)** - guides, architecture, examples
 - [llm-coding-tools-core README](./src/llm-coding-tools-core/README.md)
 - [llm-coding-tools-agents README](./src/llm-coding-tools-agents/README.md)
 - [llm-coding-tools-serdesai README](./src/llm-coding-tools-serdesai/README.md)
 - [llm-coding-tools-bubblewrap README](./src/llm-coding-tools-bubblewrap/README.md)
 - [llm-coding-tools-models-dev README](./src/llm-coding-tools-models-dev/README.md)
 - [Sandbox profiles and operator checklist](./SANDBOX-PROFILES.md)
-- [Developer Guidelines](./src/AGENTS.md)
+- [API Reference (docs.rs)](https://docs.rs/llm-coding-tools-core)
 
 ## Contributing
 
 Contributions are welcome! Please ensure all tests pass and the code follows
 our guidelines.
 
-## Deprecation Notice
-
-**Rig framework support (`llm-coding-tools-rig`) has been removed**
-(commit 17158db) due to library bugs that prevented examples from running
-reliably.
-
-You're welcome to submit a PR re-adding rig support if you're willing to
-maintain it. Since I don't use rig personally, I'm not able to actively
-maintain that integration. Alternatively, you can create your own crate
-building on `llm-coding-tools-core` directly.
-
 ## License
 
 Licensed under [Apache 2.0](./LICENSE).

SANDBOX-PROFILES.md

@@ -144,8 +144,8 @@ network access is unavailable, so it can adjust its behavior accordingly.
 System runtime roots are selected from the following paths when present:
 
 - `/usr/bin`, `/usr/lib`, `/lib64`
-- `/run/current-system/sw` (NixOS)
-- `/nix/store`, `/nix/var/nix/profiles/default` (Nix)
+- `/run/current-system/sw` ([NixOS])
+- `/nix/store`, `/nix/var/nix/profiles/default` ([Nix])
 
 #### Environment
 
@@ -167,7 +167,7 @@ profile intentionally leaves it out so nothing persists across sessions.
 #### Why These Mounts
 
 - **System runtime roots**: mounted read-only so the resolved host shell
-  plus common distro/Nix binaries remain available without exposing the
+  plus common distro/[Nix] binaries remain available without exposing the
   full host root.
 - **`/dev`, `/proc`, sandbox `/tmp`**: provide the minimum runtime surface
   for common tools.
@@ -297,3 +297,5 @@ depends on your environment.
 
 [bwrap]: https://github.com/containers/bubblewrap
 [apr]: https://docs.rs/llm-coding-tools-core/latest/llm_coding_tools_core/struct.AllowedPathResolver.html
+[NixOS]: https://nixos.org
+[Nix]: https://nixos.org

docs/.gitignore

@@ -0,0 +1,3 @@
+# MkDocs build
+site/
+venv/

docs/mkdocs.yml

@@ -0,0 +1,80 @@
+site_name: llm-coding-tools
+site_url: https://sewer56.github.io/llm-coding-tools
+docs_dir: src
+
+repo_name: Sewer56/llm-coding-tools
+repo_url: https://github.com/Sewer56/llm-coding-tools
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/Sewer56/llm-coding-tools
+    - icon: fontawesome/brands/discord
+      link: https://discord.gg/67rU5jhgDt
+
+extra_css:
+  - vendor/Reloaded/Stylesheets/reloaded.css
+  - assets/landing.css
+
+markdown_extensions:
+  - admonition
+  - tables
+  - abbr
+  - pymdownx.details
+  - pymdownx.highlight
+  - pymdownx.snippets
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tasklist
+  - def_list
+  - meta
+  - md_in_html
+  - attr_list
+  - footnotes
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.blocks.caption
+
+theme:
+  name: material
+  palette:
+    scheme: reloaded3-slate
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.sections
+    - navigation.expand
+    - content.tooltips
+    - content.code.copy
+
+plugins:
+  - search
+  - minify:
+      minify_html: true
+      minify_js: true
+      minify_css: true
+      htmlmin_opts:
+        remove_comments: true
+      cache_safe: true
+
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - Tools: tools.md
+  - Agents: agents.md
+  - Examples: examples.md
+  - Sandboxing: sandboxing.md
+  - Feature Flags: feature-flags.md
+  - Architecture:
+      - Crate Structure: architecture.md
+      - Models Catalog: models-catalog.md
+  - vs. OpenCode:
+      - Comparison: comparison.md
+      - Migration: migration.md
+  - Custom Framework Integration: guides/custom-framework.md

docs/requirements.txt

@@ -0,0 +1,5 @@
+mkdocs-material
+mkdocs-redirects
+mkdocs-exclude-unused-files
+mkdocs-exclude
+mkdocs-minify-plugin