docs: add README for every subdirectory

33 agent READMEs, 14 hand READMEs, 2 plugin READMEs
(echo-memory + hooks), and 2 skill READMEs
(custom-skill-prompt + custom-skill-python).

Each README documents the component's purpose, configuration,
and usage based on its TOML definition.

agents/academic-researcher/README.md

@@ -0,0 +1,23 @@
+# Academic Researcher
+
+Academic research agent. Searches scholarly papers, summarizes findings, and generates literature reviews.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs structured research methodology: scope, search, retrieve, evaluate, synthesize, and cite with proper academic standards.
+
+## Skills
+
+- `web_search`, `web_fetch`, `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run academic-researcher
+```

agents/analyst/README.md

@@ -0,0 +1,23 @@
+# Analyst
+
+Data analyst. Processes data, generates insights, creates reports.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs a structured analysis framework: question, explore, analyze, visualize, and report with evidence-backed findings.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `shell_exec`, `web_search`, `web_fetch`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run analyst
+```

agents/architect/README.md

@@ -0,0 +1,23 @@
+# Architect
+
+System architect. Designs software architectures, evaluates trade-offs, creates technical specifications.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs principled system design: separation of concerns, performance-aware design, simplicity, and explicit trade-off evaluation.
+
+## Skills
+
+- `file_read`, `file_list`, `memory_store`, `memory_recall`, `agent_send`
+
+## Usage
+
+```bash
+librefang agent run architect
+```

agents/assistant/README.md

@@ -0,0 +1,23 @@
+# Assistant
+
+General-purpose assistant agent. The default LibreFang agent for everyday tasks, questions, and conversations.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs versatile capabilities: conversation, task execution, research, writing, problem solving, agent delegation, and knowledge management.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`, `shell_exec`, `agent_send`, `agent_list`
+
+## Usage
+
+```bash
+librefang agent run assistant
+```

agents/code-reviewer/README.md

@@ -0,0 +1,23 @@
+# Code Reviewer
+
+Senior code reviewer. Reviews PRs, identifies issues, suggests improvements with production standards.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs prioritized review criteria: correctness, security, performance, maintainability, and style with severity-tagged feedback.
+
+## Skills
+
+- `file_read`, `file_list`, `shell_exec`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run code-reviewer
+```

agents/coder/README.md

@@ -0,0 +1,23 @@
+# Coder
+
+Expert software engineer. Reads, writes, and analyzes code.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs a read-plan-implement-test-verify methodology with production quality standards and existing pattern adherence.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `shell_exec`, `web_search`, `web_fetch`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run coder
+```

agents/customer-support/README.md

@@ -0,0 +1,23 @@
+# Customer Support
+
+Customer support agent for ticket handling, issue resolution, and customer communication.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs empathetic ticket triage, systematic troubleshooting, knowledge base management, and escalation workflows.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run customer-support
+```

agents/data-scientist/README.md

@@ -0,0 +1,23 @@
+# Data Scientist
+
+Data scientist. Analyzes datasets, builds models, creates visualizations, performs statistical analysis.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs a structured methodology: understand, explore, analyze, model, and communicate with a full statistical toolkit.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `shell_exec`, `web_search`, `web_fetch`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run data-scientist
+```

agents/debugger/README.md

@@ -0,0 +1,23 @@
+# Debugger
+
+Expert debugger. Traces bugs, analyzes stack traces, performs root cause analysis.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs a reproduce-isolate-identify-fix-verify methodology with common bug pattern awareness and minimal-fix philosophy.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `shell_exec`, `web_search`, `web_fetch`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run debugger
+```

agents/devops-lead/README.md

@@ -0,0 +1,23 @@
+# DevOps Lead
+
+DevOps lead. Manages CI/CD, infrastructure, deployments, monitoring, and incident response.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs platform engineering expertise: CI/CD pipelines, container orchestration, IaC, observability, and security hardening.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `shell_exec`, `memory_store`, `memory_recall`, `agent_send`
+
+## Usage
+
+```bash
+librefang agent run devops-lead
+```

agents/doc-writer/README.md

@@ -0,0 +1,23 @@
+# Doc Writer
+
+Technical writer. Creates documentation, README files, API docs, tutorials, and architecture guides.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs reader-first documentation with progressive disclosure, working code examples, and consistent style across READMEs, API docs, tutorials, and ADRs.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run doc-writer
+```

agents/email-assistant/README.md

@@ -0,0 +1,23 @@
+# Email Assistant
+
+Email triage, drafting, scheduling, and inbox management agent.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs email classification by urgency, professional drafting with tone adaptation, scheduling, template management, and thread summarization.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run email-assistant
+```

agents/health-tracker/README.md

@@ -0,0 +1,23 @@
+# Health Tracker
+
+Wellness tracking agent for health metrics, medication reminders, fitness goals, and lifestyle habits.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs health metrics logging, medication management, fitness goal tracking, habit building, and wellness reporting. Includes medical disclaimer.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run health-tracker
+```

agents/hello-world/README.md

@@ -0,0 +1,23 @@
+# Hello World
+
+A friendly greeting agent that can read files, search the web, and answer everyday questions.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs warm, concise, and helpful interactions as the first agent new users encounter.
+
+## Skills
+
+- `file_read`, `file_list`, `web_fetch`, `web_search`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run hello-world
+```

agents/home-automation/README.md

@@ -0,0 +1,23 @@
+# Home Automation
+
+Smart home control agent for IoT device management, automation rules, and home monitoring.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs device management, automation rule design, scene configuration, energy monitoring, security workflows, and IoT network troubleshooting.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `shell_exec`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run home-automation
+```

agents/legal-assistant/README.md

@@ -0,0 +1,23 @@
+# Legal Assistant
+
+Legal assistant agent for contract review, legal research, compliance checking, and document drafting.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs systematic contract review, legal research, compliance checking (GDPR, SOC 2, HIPAA, etc.), and plain-language explanations. Includes legal disclaimer.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run legal-assistant
+```

agents/meeting-assistant/README.md

@@ -0,0 +1,23 @@
+# Meeting Assistant
+
+Meeting notes, action items, agenda preparation, and follow-up tracking agent.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs structured agenda creation, transcript processing, action item extraction with owner/deadline tracking, and follow-up management.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run meeting-assistant
+```

agents/ops/README.md

@@ -0,0 +1,23 @@
+# Ops
+
+DevOps agent. Monitors systems, runs diagnostics, manages deployments.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs observe-diagnose-plan-execute-verify methodology with change management discipline and rollback planning.
+
+## Skills
+
+- `shell_exec`, `file_read`, `file_list`
+
+## Usage
+
+```bash
+librefang agent run ops
+```

agents/orchestrator/README.md

@@ -0,0 +1,23 @@
+# Orchestrator
+
+Meta-agent that decomposes complex tasks, delegates to specialist agents, and synthesizes results.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs task decomposition, specialist delegation via agent_send/agent_spawn, and result synthesis across the agent ecosystem.
+
+## Skills
+
+- `agent_send`, `agent_spawn`, `agent_list`, `agent_kill`, `memory_store`, `memory_recall`, `file_read`, `file_write`
+
+## Usage
+
+```bash
+librefang agent run orchestrator
+```

agents/personal-finance/README.md

@@ -0,0 +1,23 @@
+# Personal Finance
+
+Personal finance agent for budget tracking, expense analysis, savings goals, and financial planning.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs budget creation, expense categorization, savings goal tracking, debt payoff strategies, and financial health assessments. Not a licensed advisor.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `shell_exec`
+
+## Usage
+
+```bash
+librefang agent run personal-finance
+```

agents/planner/README.md

@@ -0,0 +1,23 @@
+# Planner
+
+Project planner. Creates project plans, breaks down epics, estimates effort, identifies risks and dependencies.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs scope-decompose-sequence-estimate-risk-milestone methodology with range-based estimates and risk-first planning.
+
+## Skills
+
+- `file_read`, `file_list`, `memory_store`, `memory_recall`, `agent_send`
+
+## Usage
+
+```bash
+librefang agent run planner
+```

agents/recipe-assistant/README.md

@@ -0,0 +1,23 @@
+# Recipe Assistant
+
+Cooking assistant that helps with recipes, meal plans, ingredient substitutions, and portion adjustments.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs recipe discovery, portion scaling, ingredient substitution, meal planning, grocery list generation, and cooking technique guidance.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`, `web_search`
+
+## Usage
+
+```bash
+librefang agent run recipe-assistant
+```

agents/recruiter/README.md

@@ -0,0 +1,23 @@
+# Recruiter
+
+Recruiting agent for resume screening, candidate outreach, job description writing, and hiring pipeline management.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs merit-based resume screening, inclusive job descriptions, personalized outreach, structured interview prep, and pipeline tracking.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run recruiter
+```

agents/researcher/README.md

@@ -0,0 +1,23 @@
+# Researcher
+
+Research agent. Fetches web content and synthesizes information.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs decompose-search-deep dive-cross reference-synthesize methodology with source evaluation and confidence-rated findings.
+
+## Skills
+
+- `web_search`, `web_fetch`, `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run researcher
+```

agents/router/README.md

@@ -0,0 +1,23 @@
+# Router
+
+Native deterministic router. Dispatches tasks to specialist agents without using an LLM.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:router` |
+| Model | `default` |
+| Provider | `default` |
+
+This is a system-level agent. The `builtin:router` module performs deterministic routing and does not invoke an LLM.
+
+## Skills
+
+None configured.
+
+## Usage
+
+```bash
+librefang agent run router
+```

agents/sales-assistant/README.md

@@ -0,0 +1,23 @@
+# Sales Assistant
+
+Sales assistant agent for CRM updates, outreach drafting, pipeline management, and deal tracking.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs personalized outreach via AIDA framework, CRM data management, pipeline forecasting, call prep, and competitive intelligence.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run sales-assistant
+```

agents/security-auditor/README.md

@@ -0,0 +1,23 @@
+# Security Auditor
+
+Security specialist. Reviews code for vulnerabilities, checks configurations, performs threat modeling.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs OWASP Top 10 coverage, attack surface mapping, data flow tracing, and severity-rated findings with remediation guidance.
+
+## Skills
+
+- `file_read`, `file_list`, `shell_exec`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run security-auditor
+```

agents/social-media/README.md

@@ -0,0 +1,23 @@
+# Social Media
+
+Social media content creation, scheduling, and engagement strategy agent.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs platform-optimized content creation, content calendar planning, engagement strategy, analytics interpretation, and brand voice consistency.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run social-media
+```

agents/test-engineer/README.md

@@ -0,0 +1,23 @@
+# Test Engineer
+
+Quality assurance engineer. Designs test strategies, writes tests, validates correctness.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs behavior-driven testing philosophy with unit, integration, property, edge case, and regression test design using Arrange-Act-Assert pattern.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `shell_exec`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run test-engineer
+```

agents/translator/README.md

@@ -0,0 +1,23 @@
+# Translator
+
+Multi-language translation agent for document translation, localization, and cross-cultural communication.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs meaning-faithful translation, cultural adaptation, format preservation, software localization (i18n/l10n), and translation quality assurance.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run translator
+```

agents/travel-planner/README.md

@@ -0,0 +1,23 @@
+# Travel Planner
+
+Trip planning agent for itinerary creation, booking research, budget estimation, and travel logistics.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs day-by-day itinerary creation, destination research, budget planning at multiple tiers, accommodation recommendations, and multi-destination trip optimization.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `web_search`, `web_fetch`, `browser_navigate`, `browser_click`, `browser_type`, `browser_read_page`, `browser_screenshot`, `browser_close`
+
+## Usage
+
+```bash
+librefang agent run travel-planner
+```

agents/tutor/README.md

@@ -0,0 +1,23 @@
+# Tutor
+
+Teaching and explanation agent for learning, tutoring, and educational content creation.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs adaptive explanation using the Feynman Technique, Socratic teaching, problem-solving walkthroughs, learning plan design, and study skills coaching.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `memory_store`, `memory_recall`, `shell_exec`, `web_fetch`
+
+## Usage
+
+```bash
+librefang agent run tutor
+```

agents/writer/README.md

@@ -0,0 +1,23 @@
+# Writer
+
+Content writer. Creates documentation, articles, and technical writing.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Module | `builtin:chat` |
+| Model | `default` |
+| Provider | `default` |
+
+System prompt instructs understand-research-draft-refine methodology with active voice, clarity-first style, and tone adaptation for docs, blog posts, and emails.
+
+## Skills
+
+- `file_read`, `file_write`, `file_list`, `web_search`, `web_fetch`, `memory_store`, `memory_recall`
+
+## Usage
+
+```bash
+librefang agent run writer
+```

hands/analytics/README.md

@@ -0,0 +1,31 @@
+# Analytics Hand
+
+Autonomous data analytics agent -- data collection, analysis, visualization, dashboards, and automated reporting.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Category | `data` |
+| Agent | `analytics-hand` |
+| Routing | `data analysis`, `data visualization`, `dashboard`, `automated report`, `statistical analysis` |
+
+## Integrations
+
+- **Python 3** -- Required for data analysis with pandas, matplotlib, and seaborn.
+
+## Settings
+
+- **Data Source** -- Primary data source type (`csv`, `json`, `database`, `api`, `web`)
+- **Analysis Type** -- Default analysis approach (`descriptive`, `diagnostic`, `predictive`, `prescriptive`)
+- **Output Format** -- Report format (`report`, `dashboard`, `slides`, `executive`)
+- **Visualization** -- Generate charts and visualizations (default: on)
+- **Scheduled Reports** -- Auto-generate reports on a schedule (default: off)
+- **Report Frequency** -- `daily`, `weekly`, `monthly`
+- **Confidence Threshold** -- Minimum confidence for findings (`low`, `medium`, `high`)
+
+## Usage
+
+```bash
+librefang hand run analytics
+```

hands/apitester/README.md

@@ -0,0 +1,32 @@
+# API Tester Hand
+
+Autonomous API testing agent -- endpoint discovery, request validation, load testing, and regression detection.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Category | `development` |
+| Agent | `apitester-hand` |
+| Routing | `api test`, `endpoint test`, `load test`, `regression test`, `api discovery` |
+
+## Integrations
+
+None required.
+
+## Settings
+
+- **Base URL** -- Base URL of the API to test
+- **Authentication Type** -- `none`, `bearer`, `api_key_header`, `basic`
+- **Auth Token / API Key** -- Credentials for API authentication
+- **Test Mode** -- `functional`, `regression`, `load`, `security`, `comprehensive`
+- **OpenAPI Spec URL** -- URL to OpenAPI/Swagger spec for auto-discovery
+- **Auto Schedule** -- Run tests on a schedule (default: off)
+- **Test Frequency** -- `hourly`, `daily`, `weekly`
+- **Strict Mode** -- Treat any non-2xx response as failure (default: off)
+
+## Usage
+
+```bash
+librefang hand run apitester
+```

hands/browser/README.md

@@ -0,0 +1,30 @@
+# Browser Hand
+
+Autonomous web browser -- navigates sites, fills forms, clicks buttons, and completes multi-step web tasks with user approval for purchases.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Category | `productivity` |
+| Agent | `browser-hand` |
+| Routing | `open website`, `navigate to`, `fill form`, `click button`, `web login`, `browser automation` |
+
+## Integrations
+
+- **Python 3** -- Required for Playwright browser automation library.
+- **Chromium** (optional) -- A Chromium-based browser; Playwright can install its own if none found.
+
+## Settings
+
+- **Headless Mode** -- Run browser without a visible window (default: on)
+- **Purchase Approval** -- Require confirmation before purchases (default: on)
+- **Max Pages Per Task** -- Navigation limit per task (`10`, `20`, `50`)
+- **Default Wait After Action** -- Page settle time (`auto`, `1s`, `3s`)
+- **Screenshot After Actions** -- Auto-screenshot after every action (default: off)
+
+## Usage
+
+```bash
+librefang hand run browser
+```

hands/clip/README.md

@@ -0,0 +1,31 @@
+# Clip Hand
+
+Turns long-form video into viral short clips with captions and thumbnails.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Category | `content` |
+| Agent | `clip-hand` |
+| Routing | `clip video`, `video transcription`, `subtitle extraction`, `download video`, `short clip` |
+
+## Integrations
+
+- **FFmpeg** -- Core video processing engine for clips, captions, and thumbnails.
+- **FFprobe** -- Video metadata analyzer (ships with FFmpeg).
+- **yt-dlp** -- Downloads videos from YouTube, Vimeo, Twitter, and 1000+ sites.
+
+## Settings
+
+- **Speech-to-Text Provider** -- `auto`, `whisper_local`, `groq_whisper`, `openai_whisper`, `deepgram`
+- **Text-to-Speech Provider** -- `none`, `edge_tts`, `openai_tts`, `elevenlabs`
+- **Publish Clips To** -- `local_only`, `telegram`, `whatsapp`, `both`
+- **Telegram Bot Token / Chat ID** -- For Telegram publishing
+- **WhatsApp Token / Phone ID / Recipient** -- For WhatsApp publishing
+
+## Usage
+
+```bash
+librefang hand run clip
+```

hands/collector/README.md

@@ -0,0 +1,32 @@
+# Collector Hand
+
+Autonomous intelligence collector -- monitors any target continuously with change detection and knowledge graphs.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Category | `data` |
+| Agent | `collector-hand` |
+| Routing | `monitor changes`, `track updates`, `collect intelligence`, `osint`, `change detection` |
+
+## Integrations
+
+None required.
+
+## Settings
+
+- **Target Subject** -- What to monitor (company, person, technology, market, topic)
+- **Collection Depth** -- `surface`, `deep`, `exhaustive`
+- **Update Frequency** -- `hourly`, `every_6h`, `daily`, `weekly`
+- **Focus Area** -- `market`, `business`, `competitor`, `person`, `technology`, `general`
+- **Alert on Changes** -- Publish events on significant changes (default: on)
+- **Report Format** -- `markdown`, `json`, `html`
+- **Max Sources Per Cycle** -- `10`, `30`, `50`, `100`
+- **Track Sentiment** -- Analyze sentiment trends over time (default: off)
+
+## Usage
+
+```bash
+librefang hand run collector
+```

hands/devops/README.md

@@ -0,0 +1,32 @@
+# DevOps Hand
+
+Autonomous DevOps engineer -- CI/CD management, infrastructure monitoring, deployment automation, and incident response.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Category | `development` |
+| Agent | `devops-hand` |
+| Routing | `ci/cd`, `pipeline`, `github actions`, `infrastructure monitoring`, `deployment automation`, `incident response` |
+
+## Integrations
+
+None required.
+
+## Settings
+
+- **Infrastructure Type** -- `cloud`, `kubernetes`, `docker`, `bare_metal`, `serverless`
+- **CI/CD Platform** -- `github_actions`, `gitlab_ci`, `jenkins`, `circleci`, `other`
+- **Monitoring Focus** -- `uptime`, `performance`, `security`, `cost`, `balanced`
+- **Auto Monitor** -- Automatically monitor infrastructure (default: off)
+- **Health Check Interval** -- `1min`, `5min`, `15min`, `1hour`
+- **Service URLs** -- Comma-separated URLs to monitor
+- **Alert on Failure** -- Publish events on health check failures (default: on)
+- **Rollback Strategy** -- `manual`, `auto_previous`, `blue_green`
+
+## Usage
+
+```bash
+librefang hand run devops
+```

hands/lead/README.md

@@ -0,0 +1,33 @@
+# Lead Hand
+
+Autonomous lead generation -- discovers, enriches, and delivers qualified leads on a schedule.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Category | `data` |
+| Agent | `lead-hand` |
+| Routing | `lead generation`, `prospect list`, `find customers`, `contact enrichment` |
+
+## Integrations
+
+None required.
+
+## Settings
+
+- **Target Industry** -- Industry vertical to focus on
+- **Target Role** -- Decision-maker titles to target
+- **Company Size** -- `any`, `startup`, `smb`, `enterprise`
+- **Lead Source** -- `web_search`, `linkedin_public`, `crunchbase`, `custom`
+- **Output Format** -- `csv`, `json`, `markdown_table`
+- **Leads Per Report** -- `10`, `25`, `50`, `100`
+- **Delivery Schedule** -- `daily_7am`, `daily_9am`, `weekdays_8am`, `weekly_monday`
+- **Geographic Focus** -- Region to prioritize
+- **Enrichment Depth** -- `basic`, `standard`, `deep`
+
+## Usage
+
+```bash
+librefang hand run lead
+```

hands/linkedin/README.md

@@ -0,0 +1,32 @@
+# LinkedIn Hand
+
+Autonomous LinkedIn manager -- profile optimization, content creation, networking, and professional engagement.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Category | `communication` |
+| Agent | `linkedin-hand` |
+| Routing | `linkedin`, `profile optimization`, `professional networking` |
+
+## Integrations
+
+- **LINKEDIN_ACCESS_TOKEN** -- OAuth 2.0 access token from the LinkedIn Developer Portal.
+
+## Settings
+
+- **Content Style** -- `thought_leader`, `educational`, `storyteller`, `data_driven`, `conversational`
+- **Post Frequency** -- `1_weekly`, `3_weekly`, `5_weekly`, `1_daily`
+- **Content Topics** -- Comma-separated topics to create content about
+- **Auto Engage** -- Automatically like/comment on relevant posts (default: off)
+- **Approval Mode** -- Queue posts for review before posting (default: on)
+- **Hashtag Count** -- `0`, `3`, `5`
+- **Target Audience** -- `peers`, `recruiters`, `clients`, `general`
+- **Language** -- `en`, `zh`, `es`, `auto`
+
+## Usage
+
+```bash
+librefang hand run linkedin
+```

hands/predictor/README.md

@@ -0,0 +1,32 @@
+# Predictor Hand
+
+Autonomous future predictor -- collects signals, builds reasoning chains, makes calibrated predictions, and tracks accuracy.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Category | `data` |
+| Agent | `predictor-hand` |
+| Routing | `predict`, `forecast`, `probability`, `likelihood`, `scenario analysis` |
+
+## Integrations
+
+None required.
+
+## Settings
+
+- **Prediction Domain** -- `tech`, `finance`, `geopolitics`, `climate`, `general`
+- **Time Horizon** -- `1_week`, `1_month`, `3_months`, `1_year`
+- **Data Sources** -- `news`, `social`, `financial`, `academic`, `all`
+- **Report Frequency** -- `daily`, `weekly`, `biweekly`, `monthly`
+- **Predictions Per Report** -- `3`, `5`, `10`, `20`
+- **Track Accuracy** -- Score past predictions when they expire (default: on)
+- **Confidence Threshold** -- `low` (20%+), `medium` (40%+), `high` (70%+)
+- **Contrarian Mode** -- Seek counter-consensus predictions (default: off)
+
+## Usage
+
+```bash
+librefang hand run predictor
+```

hands/reddit/README.md

@@ -0,0 +1,34 @@
+# Reddit Hand
+
+Autonomous Reddit manager -- monitors subreddits, posts content, replies to threads, and tracks karma and engagement.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Category | `communication` |
+| Agent | `reddit-hand` |
+| Routing | `reddit`, `subreddit`, `reddit post`, `reddit monitor` |
+
+## Integrations
+
+- **REDDIT_CLIENT_ID** -- OAuth2 client ID from a Reddit app.
+- **REDDIT_CLIENT_SECRET** -- OAuth2 client secret from a Reddit app.
+- **REDDIT_USERNAME** -- Reddit account username.
+- **REDDIT_PASSWORD** -- Reddit account password.
+
+## Settings
+
+- **Subreddits** -- Comma-separated list of subreddits to monitor
+- **Monitor Mode** -- `hot_only`, `new_only`, `hot_and_new`, `rising`
+- **Auto Reply** -- Automatically reply to relevant posts (default: off)
+- **Post Frequency** -- `never`, `1_daily`, `3_daily`, `weekly`
+- **Content Style** -- `helpful`, `casual`, `expert`, `witty`
+- **Approval Mode** -- Queue posts for review (default: on)
+- **Max Reply Depth** -- `1`, `3`, `5`, `unlimited`
+
+## Usage
+
+```bash
+librefang hand run reddit
+```

hands/researcher/README.md

@@ -0,0 +1,32 @@
+# Researcher Hand
+
+Autonomous deep researcher -- exhaustive investigation, cross-referencing, fact-checking, and structured reports.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Category | `productivity` |
+| Agent | `researcher-hand` |
+| Routing | `deep research`, `systematic review`, `landscape analysis`, `exhaustive investigation` |
+
+## Integrations
+
+None required.
+
+## Settings
+
+- **Research Depth** -- `quick` (5-10 sources), `thorough` (20-30), `exhaustive` (50+)
+- **Output Style** -- `brief`, `detailed`, `academic`, `executive`
+- **Source Verification** -- Cross-check claims across multiple sources (default: on)
+- **Max Sources** -- `10`, `30`, `50`, `unlimited`
+- **Auto Follow-Up** -- Research follow-up questions discovered during investigation (default: on)
+- **Save Research Log** -- Save detailed search queries and source notes (default: off)
+- **Citation Style** -- `inline_url`, `footnotes`, `academic_apa`, `numbered`
+- **Language** -- `english`, `spanish`, `french`, `german`, `chinese`, `japanese`, `auto`
+
+## Usage
+
+```bash
+librefang hand run researcher
+```

hands/strategist/README.md

@@ -0,0 +1,32 @@
+# Strategist Hand
+
+Autonomous strategy analyst -- market research, competitive analysis, business planning, and strategic recommendations.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Category | `productivity` |
+| Agent | `strategist-hand` |
+| Routing | `strategic analysis`, `competitive analysis`, `business plan`, `market research` |
+
+## Integrations
+
+None required.
+
+## Settings
+
+- **Focus Area** -- `general`, `market_entry`, `competitive`, `product`, `growth`
+- **Analysis Depth** -- `quick`, `thorough`, `comprehensive`
+- **Industry** -- Primary industry to focus on
+- **Key Competitors** -- Comma-separated list of competitors to track
+- **Auto Monitor** -- Track competitor moves automatically (default: off)
+- **Report Format** -- `executive`, `detailed`, `slide_deck`, `memo`
+- **Confidence Threshold** -- `low`, `medium`, `high`
+- **Preferred Frameworks** -- e.g. `SWOT`, `Porter`, `PESTEL`
+
+## Usage
+
+```bash
+librefang hand run strategist
+```

hands/trader/README.md

@@ -0,0 +1,34 @@
+# Trading Hand
+
+Autonomous market intelligence and trading engine -- multi-signal analysis, adversarial bull/bear reasoning, calibrated confidence scoring, strict risk management, and portfolio-level analytics.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Category | `data` |
+| Agent | `trader-hand` |
+| Routing | `trade`, `portfolio`, `market analysis`, `paper trade`, `stock trading` |
+
+## Integrations
+
+None required. Alpaca API keys needed for live trading mode.
+
+## Settings
+
+- **Trading Mode** -- `analysis` (signals only), `paper` (simulated), `live` (real via Alpaca)
+- **Market Focus** -- `us_stocks`, `crypto`, `multi_asset`
+- **Strategy Style** -- `scalping`, `day`, `swing`, `position`
+- **Risk Per Trade** -- `1%`, `2%`, `3%`, `5%` of portfolio
+- **Max Daily Loss** -- `2%`, `5%`, `10%` circuit breaker threshold
+- **Analysis Depth** -- `quick`, `standard`, `deep`
+- **Scan Schedule** -- `15m`, `1h`, `4h`, `daily`
+- **Watchlist** -- Comma-separated tickers (default: `SPY,QQQ,AAPL,MSFT,NVDA,BTC,ETH`)
+- **Initial Capital** -- Starting portfolio value (default: `$10,000`)
+- **Approval Mode** -- Require approval before live trades (default: on)
+
+## Usage
+
+```bash
+librefang hand run trader
+```

hands/twitter/README.md

@@ -0,0 +1,34 @@
+# Twitter Hand
+
+Autonomous Twitter/X manager -- content creation, scheduled posting, engagement, and performance tracking.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Category | `communication` |
+| Agent | `twitter-hand` |
+| Routing | `twitter`, `tweet`, `x.com`, `scheduled tweet` |
+
+## Integrations
+
+- **TWITTER_BEARER_TOKEN** -- Bearer Token from the Twitter/X Developer Portal.
+
+## Settings
+
+- **Content Style** -- `professional`, `casual`, `witty`, `educational`, `provocative`, `inspirational`
+- **Post Frequency** -- `1_daily`, `3_daily`, `5_daily`, `hourly`
+- **Auto Reply** -- Reply to mentions automatically (default: off)
+- **Auto Like** -- Like relevant tweets automatically (default: off)
+- **Content Topics** -- Comma-separated topics
+- **Brand Voice** -- Description of your unique voice
+- **Thread Mode** -- Include multi-tweet threads (default: on)
+- **Content Queue Size** -- `5`, `10`, `20`, `50`
+- **Engagement Hours** -- `business_hours`, `waking_hours`, `all_day`
+- **Approval Mode** -- Queue tweets for review (default: on)
+
+## Usage
+
+```bash
+librefang hand run twitter
+```

plugins/echo-memory/README.md

@@ -0,0 +1,14 @@
+# echo-memory
+
+Simple demo plugin that echoes back the user message as a "recalled memory". Useful for verifying the plugin system works end-to-end.
+
+## Hooks
+
+| Hook | Script | Description |
+|------|--------|-------------|
+| ingest | `hooks/ingest.py` | Echoes the user message back as a recalled memory fragment |
+| after_turn | `hooks/after_turn.py` | Acknowledges each conversation turn (no-op demo) |
+
+## Usage
+
+Installed automatically when enabled in agent configuration.

plugins/echo-memory/hooks/README.md

@@ -0,0 +1,15 @@
+# echo-memory hooks
+
+Python hook scripts for the echo-memory demo plugin. Each script reads a JSON request from stdin and writes a JSON response to stdout.
+
+## Scripts
+
+| Script | Hook | Description |
+|--------|------|-------------|
+| `ingest.py` | ingest | Receives `{"message": "..."}`, returns it wrapped as a memory fragment |
+| `after_turn.py` | after_turn | Receives the conversation messages array, responds with `{"type": "ok"}` |
+
+## Protocol
+
+- **Input**: JSON object on stdin (fields vary by hook type)
+- **Output**: JSON object on stdout (`ingest_result` with memories, or `ok`)

skills/custom-skill-prompt/README.md

@@ -0,0 +1,21 @@
+# meeting-agenda
+
+Generate a structured meeting agenda from a topic and duration. Pure prompt engineering — no code required.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Type | `promptonly` |
+| Entry | N/A (template-only) |
+
+## Input
+
+- **topic** (string, required) — The meeting topic
+- **duration_minutes** (string, required) — Meeting duration in minutes
+
+## Usage
+
+```bash
+librefang skill test ./skills/custom-skill-prompt --input '{"topic": "Q1 planning", "duration_minutes": "30"}'
+```

skills/custom-skill-python/README.md

@@ -0,0 +1,20 @@
+# word-counter
+
+Count words, sentences, and characters in text. A minimal example of a Python runtime skill.
+
+## Configuration
+
+| Field | Value |
+|-------|-------|
+| Type | `python` |
+| Entry | `main.py` |
+
+## Input
+
+- **text** (string, required) — The text to analyze
+
+## Usage
+
+```bash
+librefang skill test ./skills/custom-skill-python --input '{"text": "Hello world. How are you?"}'
+```