docs: add README for every content directory

Each directory (agents, hands, integrations, plugins, providers,
scripts, skills) now has a README documenting its TOML format,
current contents, and contribution steps.

agents/README.md

@@ -0,0 +1,63 @@
+# Agents
+
+Autonomous agent definitions for LibreFang. Each agent is a directory containing an `agent.toml` manifest.
+
+## Structure
+
+```
+agents/
+├── hello-world/agent.toml
+├── researcher/agent.toml
+├── coder/agent.toml
+└── ...
+```
+
+## agent.toml Format
+
+```toml
+name = "agent-name"              # Must match directory name
+version = "0.1.0"
+description = "What this agent does"
+author = "author-name"
+module = "builtin:chat"          # Runtime module
+
+[model]
+provider = "default"
+model = "default"
+max_tokens = 4096
+temperature = 0.7
+system_prompt = """Behavioral instructions for the agent."""
+
+[metadata.routing]
+aliases = ["exact match phrases"]
+weak_aliases = ["keyword hints"]
+
+[resources]
+max_llm_tokens_per_hour = 100000
+
+[capabilities]
+tools = ["web_search", "file_read"]
+network = ["*"]
+memory_read = ["*"]
+memory_write = ["self.*"]
+agent_spawn = false
+```
+
+## Current Agents (33)
+
+| Agent | Description |
+|-------|-------------|
+| assistant | Default conversational assistant |
+| researcher | Deep research with web search |
+| coder | Code generation and editing |
+| hello-world | Friendly greeting agent for new users |
+| ... | See each directory for details |
+
+## Adding a New Agent
+
+1. Create `agents/<name>/agent.toml`
+2. Ensure `name` matches the directory name
+3. Run `python scripts/validate.py`
+4. Submit a PR
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide.

hands/README.md

@@ -0,0 +1,74 @@
+# Hands
+
+Hand definitions for LibreFang. Hands are the user-facing "apps" -- higher-level application bundles that package an agent with tools, settings, dashboard metrics, and dependency requirements.
+
+> "You have many hands helping you." -- Hands are how LibreFang users interact with specialized capabilities.
+
+## Structure
+
+```
+hands/
+├── browser/
+│   ├── HAND.toml    # Hand definition
+│   └── SKILL.md     # Documentation
+├── trader/
+│   ├── HAND.toml
+│   └── SKILL.md
+└── ...
+```
+
+## HAND.toml Format
+
+```toml
+id = "hand-id"                   # Must match directory name
+name = "Hand Name"
+description = "What this hand does"
+category = "productivity"         # communication | content | data | development |
+                                  # devops | finance | productivity | research | social
+icon = "🔧"
+tools = ["tool1", "tool2"]
+
+[routing]
+aliases = ["activate phrases"]
+weak_aliases = ["keyword hints"]
+
+[[requires]]                      # External dependencies
+key = "python3"
+requirement_type = "binary"
+check_value = "python3"
+
+[[settings]]                      # User-configurable options
+key = "headless"
+setting_type = "toggle"
+default = "true"
+
+[agent]                           # The agent powering this hand
+name = "hand-agent"
+module = "builtin:chat"
+system_prompt = """..."""
+
+[dashboard]                       # Dashboard metrics
+[[dashboard.metrics]]
+label = "Tasks Completed"
+memory_key = "metric_key"
+format = "number"
+```
+
+## Current Hands (14)
+
+| Hand | Category | Description |
+|------|----------|-------------|
+| browser | productivity | Autonomous web browser |
+| trader | data | Crypto/stock trading assistant |
+| researcher | productivity | Deep research automation |
+| analytics | data | Data analysis and dashboards |
+| ... | | See each directory for details |
+
+## Adding a New Hand
+
+1. Create `hands/<name>/HAND.toml` (and optionally `SKILL.md`)
+2. Ensure `id` matches the directory name
+3. Run `python scripts/validate.py`
+4. Submit a PR
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide.

integrations/README.md

@@ -0,0 +1,70 @@
+# Integrations
+
+MCP (Model Context Protocol) server integration templates for LibreFang. Each integration connects LibreFang to an external service (GitHub, Slack, databases, etc.).
+
+## Structure
+
+```
+integrations/
+├── github.toml
+├── slack.toml
+├── postgresql.toml
+└── ...
+```
+
+## Integration TOML Format
+
+```toml
+id = "service-id"                 # Must match filename (without .toml)
+name = "Service Name"
+description = "What this integration provides"
+category = "devtools"             # devtools | communication | storage | monitoring | data
+icon = "🐙"
+tags = ["relevant", "tags"]
+
+[transport]                       # MCP server transport config
+type = "stdio"                    # "stdio" or "sse"
+command = "npx"
+args = ["-y", "@pkg/mcp-server"]
+
+[[required_env]]                  # Required environment variables
+name = "SERVICE_API_KEY"
+label = "API Key"
+help = "How to obtain this key"
+is_secret = true
+get_url = "https://..."
+
+[oauth]                           # Optional: OAuth config
+provider = "github"
+scopes = ["repo"]
+auth_url = "https://..."
+token_url = "https://..."
+
+[health_check]
+interval_secs = 60
+unhealthy_threshold = 3
+
+setup_instructions = """
+Step-by-step setup guide for users.
+"""
+```
+
+## Current Integrations (25)
+
+| Integration | Category | Service |
+|-------------|----------|---------|
+| github | devtools | GitHub repos, issues, PRs |
+| slack | communication | Slack messaging |
+| notion | productivity | Notion pages and databases |
+| postgresql | storage | PostgreSQL database |
+| ... | | See each file for details |
+
+## Adding a New Integration
+
+1. Create `integrations/<name>.toml`
+2. Ensure `id` matches the filename
+3. Test the MCP server command locally
+4. Run `python scripts/validate.py`
+5. Submit a PR
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide.

plugins/README.md

@@ -0,0 +1,62 @@
+# Plugins
+
+Plugin packages for LibreFang. Plugins extend agent behavior through lifecycle hooks -- they can inject memories, modify context, or perform side effects during conversations.
+
+## Structure
+
+```
+plugins/
+└── echo-memory/
+    ├── plugin.toml          # Plugin manifest
+    ├── hooks/
+    │   ├── ingest.py        # Called on user message
+    │   └── after_turn.py    # Called after each turn
+    └── requirements.txt     # Python dependencies
+```
+
+## plugin.toml Format
+
+```toml
+name = "plugin-name"             # Must match directory name
+version = "0.1.0"
+description = "What this plugin does"
+author = "author-name"
+
+[hooks]
+ingest = "hooks/ingest.py"       # Receives user message, can return memories
+after_turn = "hooks/after_turn.py" # Post-turn processing
+```
+
+## Hook Protocol
+
+Hooks communicate via stdin/stdout JSON:
+
+### ingest hook
+
+```
+stdin:  {"type": "ingest", "agent_id": "...", "message": "user message"}
+stdout: {"type": "ingest_result", "memories": [{"content": "..."}]}
+```
+
+### after_turn hook
+
+```
+stdin:  {"type": "after_turn", "agent_id": "...", "messages": [...]}
+stdout: {"type": "ok"}
+```
+
+## Current Plugins (1)
+
+| Plugin | Description |
+|--------|-------------|
+| echo-memory | Demo plugin that echoes user messages as recalled memories |
+
+## Adding a New Plugin
+
+1. Create `plugins/<name>/plugin.toml`
+2. Add hook scripts in `hooks/`
+3. List dependencies in `requirements.txt` (prefer stdlib-only)
+4. Run `python scripts/validate.py`
+5. Submit a PR
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide.

providers/README.md

@@ -0,0 +1,64 @@
+# Providers
+
+LLM provider and model metadata for LibreFang. Each provider file defines the provider's API configuration and all available models with pricing, context windows, and capability flags.
+
+## Structure
+
+```
+providers/
+├── anthropic.toml
+├── openai.toml
+├── groq.toml
+└── ...           (46 providers, 220+ models)
+```
+
+## Provider TOML Format
+
+```toml
+[provider]
+id = "provider-id"                # Unique identifier (lowercase, hyphenated)
+display_name = "Provider Name"
+api_key_env = "PROVIDER_API_KEY"  # Env var for API key
+base_url = "https://api.example.com"
+key_required = true
+
+[[models]]
+id = "model-id"                   # Exact API model ID
+display_name = "Model Name"
+tier = "smart"                    # frontier | smart | balanced | fast | local
+context_window = 128000
+max_output_tokens = 16384
+input_cost_per_m = 2.50           # USD per million input tokens
+output_cost_per_m = 10.0          # USD per million output tokens
+supports_tools = true
+supports_vision = false
+supports_streaming = true
+aliases = ["short-name"]
+```
+
+## Tier Definitions
+
+| Tier | Description | Examples |
+|------|-------------|----------|
+| `frontier` | Most capable, cutting-edge | Claude Opus, GPT-4.1 |
+| `smart` | Smart, cost-effective | Claude Sonnet, Gemini 2.5 Flash |
+| `balanced` | Balanced speed/cost | GPT-4.1 Mini, Llama 3.3 70B |
+| `fast` | Fastest, cheapest | GPT-4o Mini, Claude Haiku |
+| `local` | Local models, zero cost | Ollama, vLLM, LM Studio |
+
+## Validation
+
+```bash
+python scripts/validate.py
+```
+
+Checks: required fields, valid tiers, non-negative costs, no duplicate model IDs.
+
+## Adding or Updating a Model
+
+1. Edit or create the provider file in `providers/`
+2. Use exact API model IDs and verify pricing from official sources
+3. Run `python scripts/validate.py`
+4. Submit a PR
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide and pricing source links.

scripts/README.md

@@ -0,0 +1,35 @@
+# Scripts
+
+Utility scripts for maintaining the LibreFang registry.
+
+## validate.py
+
+Validates all TOML content files across the registry.
+
+```bash
+python scripts/validate.py
+```
+
+### What It Checks
+
+**Per content type:**
+- **Providers** -- required fields, valid tiers, non-negative costs, no duplicate model IDs
+- **Agents** -- required fields (name, description, module), name matches directory
+- **Hands** -- required fields (id, name, description), valid category, [agent] section, id matches directory
+- **Integrations** -- required fields (id, name), [transport] section, id matches filename
+- **Skills** -- [skill] section with name, [runtime] with valid type
+- **Plugins** -- name matches directory, [hooks] section, hook files exist
+
+**Cross-type checks:**
+- Routing alias collisions between agents and hands (reported as warnings)
+- Cross-file duplicate model IDs within the same provider
+
+### Requirements
+
+- Python 3.11+ (uses `tomllib`)
+- Or Python 3.8+ with `pip install tomli`
+
+### Exit Codes
+
+- `0` -- all checks passed
+- `1` -- one or more validation errors

skills/README.md

@@ -0,0 +1,80 @@
+# Skills
+
+Reusable skill definitions for LibreFang agents. Skills are either prompt templates or code scripts that agents can invoke to perform specific tasks.
+
+## Structure
+
+```
+skills/
+├── custom-skill-prompt/
+│   └── skill.toml           # Prompt-only skill
+└── custom-skill-python/
+    ├── skill.toml            # Skill manifest
+    └── main.py               # Python implementation
+```
+
+## Skill Types
+
+### Prompt-Only
+
+No code needed -- pure prompt engineering:
+
+```toml
+[skill]
+name = "meeting-agenda"
+version = "0.1.0"
+description = "Generate a structured meeting agenda"
+tags = ["meeting", "productivity"]
+
+[runtime]
+type = "promptonly"
+
+[input]
+topic = { type = "string", description = "The meeting topic", required = true }
+duration_minutes = { type = "string", description = "Duration in minutes", required = true }
+
+[prompt]
+template = """
+Create a meeting agenda for:
+Topic: {{topic}}
+Duration: {{duration_minutes}} minutes
+"""
+```
+
+### Python
+
+Custom logic with a Python entry point:
+
+```toml
+[skill]
+name = "my-skill"
+version = "0.1.0"
+description = "Skill with custom logic"
+
+[runtime]
+type = "python"
+entry = "main.py"
+
+[input]
+data = { type = "string", description = "Input data", required = true }
+```
+
+### Other Runtimes
+
+Also supported: `node`, `shell`.
+
+## Testing Skills Locally
+
+```bash
+librefang skill test ./skills/custom-skill-prompt \
+  --input '{"topic": "Q1 planning", "duration_minutes": "30"}'
+```
+
+## Adding a New Skill
+
+1. Create `skills/<name>/skill.toml`
+2. Add implementation files if not `promptonly`
+3. Run `python scripts/validate.py`
+4. Submit a PR
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide.