devloop 0.4.1__tar.gz → 0.5.1__tar.gz

{devloop-0.4.1 → devloop-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devloop
-Version: 0.4.1
+Version: 0.5.1
 Summary: Intelligent background agents for development workflow automation
 License: MIT
 License-File: LICENSE
@@ -24,10 +24,13 @@ Classifier: Topic :: Utilities
 Provides-Extra: all-optional
 Provides-Extra: ci-monitor
 Provides-Extra: code-rabbit
+Provides-Extra: marketplace-api
 Provides-Extra: snyk
 Requires-Dist: aiofiles (>=23.2,<24.0)
+Requires-Dist: lsprotocol (>=2023.0.0,<2024.0.0)
 Requires-Dist: psutil (>=5.9,<6.0)
 Requires-Dist: pydantic (>=2.5,<3.0)
+Requires-Dist: pygls (>=1.3.0,<2.0.0)
 Requires-Dist: rich (>=13.7,<14.0)
 Requires-Dist: typer (>=0.15,<1.0)
 Requires-Dist: watchdog (>=3.0,<4.0)
@@ -41,7 +44,7 @@ Description-Content-Type: text/markdown
 > **Intelligent background agents for development workflow automation** — automate code quality checks, testing, documentation, and more while you code.
 
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
-[![Tests Passing](https://img.shields.io/badge/tests-239%2B%20passing-green.svg)](#testing)
+[![Tests Passing](https://img.shields.io/badge/tests-737%2B%20passing-green.svg)](#testing)
 [![Alpha Release](https://img.shields.io/badge/status-alpha-orange.svg)](#status)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
@@ -78,11 +81,11 @@ edit code → save → ✅ agents run automatically → ✅ all checks pass →
 ```
 
 **Key benefits:**
-- 🎯 **Catch 90%+ of CI failures locally** before they reach your repository
+- 🎯 **Catch 90%+ of CI failures locally**[^1] before they reach your repository
 - ⚡ **Sub-second feedback** on linting, formatting, type errors
 - 🔒 **Pre-commit enforcement** prevents bad commits from ever being created
 - 🧠 **Smart test selection** runs only affected tests, not the entire suite
-- 💰 **Reduce CI costs** by 60%+ through fewer pipeline runs
+- 💰 **Reduce CI costs** by 60%+[^2] through fewer pipeline runs
 
 ---
 
@@ -112,7 +115,7 @@ Try it on a side project first. See results in minutes, not days.
 
 ### What's Working ✅
 
-DevLoop has **production-grade** foundation with 239+ passing tests:
+DevLoop has **production-grade** foundation with 737+ passing tests:
 
 - **Core stability**: Event system, agent coordination, context management - all battle-tested
 - **Code quality**: Black, Ruff, mypy, pytest - works reliably across 1000s of file changes
@@ -125,14 +128,14 @@ DevLoop has **production-grade** foundation with 239+ passing tests:
 
 ### Known Limitations ⚠️
 
-Like any alpha software, some features need hardening:
+DevLoop has been thoroughly tested (737+ tests) with production-grade implementations. Remaining limitations are minor:
 
 | Risk | Current Status | Mitigation |
 |------|---------------|------------|
-| Auto-fix safety | May modify code incorrectly | **Disabled by default**. Enable only with `safe_only` mode + git backups |
-| Sandbox isolation | Subprocesses not fully sandboxed | Don't run on untrusted code |
-| Error recovery | Daemon may need manual restart | Check logs: `.devloop/devloop.log` |
-| Config migrations | Not automated yet | Manual config updates between versions |
+| Auto-fix safety | Fully implemented with configurable safety levels (`safe_only`, `medium`, `all`) | Reviews available via git diff before commit |
+| Resource isolation | Graceful CPU/memory limits with configurable thresholds | Use `resourceLimits` in `.devloop/agents.json` |
+| Daemon restart | Automatic supervision and restart handling on failure | Logs available at `.devloop/devloop.log` |
+| Config migrations | Automated with schema versioning system | Handled automatically on version upgrades |
 
 [View complete risk assessment →](./history/RISK_ASSESSMENT.md)
 
@@ -166,7 +169,7 @@ Like any alpha software, some features need hardening:
 | **Feedback Speed** | 10-30 min | On commit only | **<1 second** (as you type) |
 | **Coverage** | Full suite | Basic checks | **Comprehensive** (11 agents) |
 | **Context Switching** | High (wait for CI) | Medium (at commit) | **Minimal** (background) |
-| **CI Cost** | High (every push) | Medium (fewer failures) | **Low** (60%+ reduction) |
+| **CI Cost** | High (every push) | Medium (fewer failures) | **Low** (60%+[^2] reduction) |
 | **Smart Test Selection** | ❌ Runs all tests | ❌ Manual selection | **✅ Automatic** |
 | **Learning System** | ❌ Static rules | ❌ Static rules | **✅ Adapts** to your patterns |
 | **Security Scanning** | ✅ On push | ❌ Rarely | **✅ On save** |
@@ -176,9 +179,9 @@ Like any alpha software, some features need hardening:
 **The DevLoop advantage**: Combines the comprehensiveness of CI with the speed of local checks, plus intelligence that neither provides.
 
 **Real impact**:
-- **Before DevLoop**: 6-8 CI failures per day × 15 min = 90-120 min wasted
+- **Before DevLoop**: 6-8 CI failures per day[^3] × 15 min = 90-120 min wasted
 - **After DevLoop**: 1-2 CI failures per day × 15 min = 15-30 min wasted
-- **Time saved**: ~75-90 minutes per developer per day
+- **Time saved**: ~75-90 minutes per developer per day[^3]
 
 ---
 
@@ -186,16 +189,53 @@ Like any alpha software, some features need hardening:
 
 DevLoop runs background agents that automatically:
 
+### Code Quality & Testing
 - **🔍 Linting & Type Checking** — Detect issues as you code (mypy, custom linters)
 - **📝 Code Formatting** — Auto-format files with Black, isort, and more
 - **✅ Testing** — Run relevant tests on file changes
+
+### Security & Performance
 - **🔐 Security Scanning** — Find vulnerabilities with Bandit
-- **📚 Documentation** — Keep docs in sync with code changes
 - **⚡ Performance** — Track performance metrics and detect regressions
+
+### Workflow & Documentation
+- **📚 Documentation** — Keep docs in sync with code changes
 - **🎯 Git Integration** — Generate smart commit messages
 - **🤖 Custom Agents** — Create no-code agents via builder pattern
+
+### Agent Marketplace (NEW!)
+- **🏪 Agent Marketplace** — Discover and share agents with the community
+- **📦 Agent Publishing** — Publish your agents with semantic versioning & signing
+- **✍️ Cryptographic Signing** — SHA256 checksums + directory hashing for tamper detection
+- **⭐ Ratings & Reviews** — Community ratings, user reviews, and agent statistics
+- **🔍 Agent Discovery** — Full-text search, category filtering, install tracking
+- **🔄 Version Management** — Manage agent versions, deprecation notices, and updates
+- **🛠️ Tool Dependencies** — Automatic dependency resolution for agent tools
+- **🌐 REST API Server** — Run a local/remote marketplace with HTTP API
+
+### IDE & Editor Integration
+- **VSCode Extension** — Real-time agent feedback with inline quick fixes and status bar integration
+- **LSP Server** — Language Server Protocol for multi-editor support
+- **Agent Status Display** — View findings and metrics directly in your editor
+
+### Developer Experience & Reliability
+- **Daemon Supervision** — Automatic process monitoring and restart handling
+- **Transactional I/O** — Atomic writes, checksums, corruption recovery
+- **Config Schema Versioning** — Automatic migration between configuration versions
+- **Self-healing Filesystem** — Detects and repairs corrupted data files
+- **Event Logging** — Structured SQLite audit trail with 30-day retention
+
+### Workflow Integration
+- **Beads Task Integration** — Auto-create issues from detected patterns
+- **Amp Thread Context** — Cross-thread pattern detection and analytics
+- **Multi-CI Support** — GitHub Actions, GitLab CI, Jenkins, CircleCI
+- **Multi-Registry Support** — PyPI, npm, Docker, and custom registries
+
+### Advanced Features
 - **📊 Learning System** — Automatically learn patterns and optimize behavior
 - **🔄 Auto-fix** — Safely apply fixes (configurable safety levels)
+- **🔐 Token Security** — Secure credential management with OAuth2 and validation
+- **🧹 Cache Management** — Smart cleanup of stale caches and temporary files
 
 All agents run **non-intrusively in the background**, respecting your workflow.
 
@@ -214,7 +254,9 @@ All agents run **non-intrusively in the background**, respecting your workflow.
 
 ### Installation
 
-**Prerequisites:** Python 3.11+
+**Prerequisites:**
+- Python 3.11 or later
+- For release workflow: Poetry 1.7+ and GitHub CLI 2.78+
 
 #### Option 1: From PyPI (Recommended)
 
@@ -222,17 +264,21 @@ All agents run **non-intrusively in the background**, respecting your workflow.
 # Basic installation (all default agents)
 pip install devloop
 
+# With marketplace API server
+pip install devloop[marketplace-api]
+
 # With optional agents (Snyk security scanning)
 pip install devloop[snyk]
 
 # With multiple optional agents
-pip install devloop[snyk,code-rabbit]
+pip install devloop[snyk,code-rabbit,marketplace-api]
 
 # With all optional agents
 pip install devloop[all-optional]
 ```
 
 **Available extras:**
+- `marketplace-api` — Marketplace registry HTTP server and publishing tools (FastAPI + uvicorn)
 - `snyk` — Dependency vulnerability scanning via Snyk CLI
 - `code-rabbit` — AI-powered code analysis
 - `ci-monitor` — CI/CD pipeline monitoring
@@ -250,13 +296,27 @@ DevLoop automatically detects and uses several system tools. Install them for fu
 
 **For Pre-Push CI Verification (Optional but Recommended):**
 ```bash
-# GitHub CLI (for checking CI status before push)
+# GitHub CLI 2.78+ (for checking CI status before push)
 # Ubuntu/Debian:
 sudo apt-get install -y gh
 
 # macOS:
 brew install gh
 
+# Verify installation
+gh --version
+```
+
+**For Release Management (Optional but Recommended for Publishing):**
+```bash
+# Poetry 1.7+ (for package management and publishing)
+curl -sSL https://install.python-poetry.org | python3 -
+
+# Verify installation
+poetry --version
+
+# Configure PyPI credentials (get token from https://pypi.org/account/)
+poetry config pypi-token.pypi "pypi-AgEIcHlwaS5vcmc..."
 ```
 
 **For Task Management Integration (Optional):**
@@ -266,8 +326,9 @@ pip install beads-mcp
 ```
 
 **What happens if missing:**
-- `gh`: Pre-push CI verification is skipped (but DevLoop still works)
-- `bd`: Pre-push hook won't create task queue issues (but DevLoop still works)
+- `gh` (2.78+): Pre-push CI verification is skipped (but DevLoop still works)
+- `poetry` (1.7+): Release workflow unavailable (but development still works)
+- `bd`: Task creation on push won't work (but DevLoop still works)
 
 DevLoop will warn you during `devloop init` if any tools are missing and provide installation instructions. You can install them later and they'll be detected automatically.
 
@@ -332,6 +393,28 @@ devloop watch .
 # Show agent status and health
 devloop status
 
+# Agent publishing and management
+devloop agent publish ./my-agent                   # Publish agent to marketplace
+devloop agent check ./my-agent                     # Check readiness to publish
+devloop agent version ./my-agent patch             # Bump version (major/minor/patch)
+devloop agent verify ./my-agent                    # Verify agent signature
+devloop agent info ./my-agent --signature          # Show agent metadata & signature
+devloop agent deprecate my-agent -m "Use new-agent" # Mark version as deprecated
+devloop agent sign ./my-agent                      # Cryptographically sign agent
+
+# Marketplace server management
+devloop marketplace server start --port 8000      # Start HTTP registry server
+devloop marketplace server stop                   # Stop running server
+devloop marketplace status                        # Show registry statistics
+devloop marketplace install my-agent-name 1.0.0  # Install agent from registry
+devloop marketplace search "formatter"            # Search agents in registry
+devloop marketplace list-categories               # List available categories
+
+# Tool dependency management
+devloop agent dependencies check ./my-agent       # Verify all dependencies available
+devloop agent dependencies resolve ./my-agent    # Install missing dependencies
+devloop agent dependencies list ./my-agent       # Show agent's dependencies
+
 # View current findings in Amp
 /agent-summary          # Recent findings
 /agent-summary today    # Today's findings
@@ -343,6 +426,50 @@ devloop custom-create my_agent pattern_matcher
 
 [View all CLI commands →](./docs/cli-commands.md)
 
+### Verify Installation & Version Compatibility
+
+After installation, verify everything is working:
+
+```bash
+# Check DevLoop version
+devloop --version
+
+# Verify system dependencies are detected
+devloop init --check-requirements
+
+# Check daemon status (if running)
+devloop status
+
+# Verify git hooks are installed (in your project)
+cat .git/hooks/pre-commit    # Should exist
+cat .git/hooks/pre-push      # Should exist
+```
+
+**Version compatibility:**
+- DevLoop 0.4.1+ requires Python 3.11+
+- Release workflow requires Poetry 1.7+ and GitHub CLI 2.78+
+- AGENTS.md template was updated in DevLoop 0.4.0+
+
+**If you're upgrading DevLoop:**
+```bash
+# Upgrade to latest
+pip install --upgrade devloop
+
+# Update your project's AGENTS.md (templates may have changed)
+devloop init --merge-templates /path/to/your/project
+
+# Restart the daemon
+devloop stop
+devloop watch .
+```
+
+**📖 See [docs/UPGRADE_GUIDE.md](docs/UPGRADE_GUIDE.md) for:**
+- Detailed upgrade procedures
+- Version compatibility matrix
+- Breaking changes and migrations
+- Rollback instructions
+- Troubleshooting
+
 ---
 
 ## Architecture
@@ -411,6 +538,279 @@ config = (
 
 [View agent documentation →](./docs/agents.md)
 
+---
+
+## Agent Marketplace
+
+DevLoop includes a complete **agent marketplace** for discovering, publishing, and managing community agents.
+
+### Publishing Your Agent
+
+Share your custom agents with the community:
+
+```bash
+# Publish an agent to the marketplace
+devloop agent publish ./my-agent
+
+# Check if agent is ready to publish
+devloop agent check ./my-agent
+
+# Bump version (semantic versioning)
+devloop agent version ./my-agent minor
+
+# Deprecate an old version
+devloop agent deprecate my-agent --message "Use my-agent-v2 instead"
+```
+
+### Agent Signing & Verification
+
+DevLoop automatically signs agents for integrity and tamper detection:
+
+```bash
+# Agent signing is automatic (SHA256 checksums + directory hashing)
+# Verify agent authenticity
+devloop agent verify ./my-agent
+
+# View signature information
+devloop agent info ./my-agent --signature
+```
+
+### Agent Ratings & Reviews
+
+Community-driven quality metrics help you find reliable agents:
+
+```bash
+# View agent ratings and reviews
+devloop agent reviews my-agent
+
+# Rate an agent (1-5 stars)
+devloop agent rate my-agent 5 --message "Works great, very fast!"
+
+# List highest-rated agents in a category
+devloop marketplace search --category code-quality --sort rating
+
+# View detailed agent statistics
+devloop agent info my-agent --reviews --stats
+```
+
+**Ratings help you:**
+- Find trusted, well-maintained agents
+- Avoid buggy or abandoned agents
+- Give feedback to agent developers
+- Build community trust and transparency
+
+### Marketplace Registry API
+
+Programmatically discover and manage agents:
+
+```python
+from devloop.marketplace import RegistryAPI, create_registry_client
+from pathlib import Path
+
+# Initialize
+client = create_registry_client(Path("~/.devloop/registry"))
+api = RegistryAPI(client)
+
+# Search agents
+response = api.search_agents(query="formatter", categories=["formatting"])
+print(f"Found {response.data['total_results']} agents")
+
+# Get agent details
+response = api.get_agent("my-formatter")
+if response.success:
+    print(f"Rating: {response.data['rating']['average']}")
+
+# Rate an agent
+api.rate_agent("my-formatter", 5.0)
+```
+
+### Marketplace HTTP Server
+
+Run a local marketplace registry with REST API endpoints:
+
+```bash
+# Start the marketplace server (persistent background service)
+devloop marketplace server start --port 8000
+
+# With additional options
+devloop marketplace server start --port 8000 --host 0.0.0.0 --workers 4
+
+# View server logs
+devloop marketplace server logs
+
+# Stop the running server
+devloop marketplace server stop
+
+# Access API documentation at http://localhost:8000/docs
+# Interactive API testing at http://localhost:8000/redoc
+```
+
+**Available REST API endpoints:**
+- `GET /api/v1/agents/search?q=formatter&category=code-quality` — Search agents with filters
+- `GET /api/v1/agents/{name}` — Get agent details including ratings
+- `GET /api/v1/agents/{name}/versions` — List all versions of an agent
+- `POST /api/v1/agents` — Register new agent with metadata
+- `POST /api/v1/agents/{name}/rate` — Rate an agent (1-5 stars)
+- `POST /api/v1/agents/{name}/review` — Leave a text review
+- `GET /api/v1/agents/{name}/reviews` — Get agent reviews and ratings
+- `GET /api/v1/categories` — List available categories
+- `GET /api/v1/stats` — Registry statistics (agent count, total installations, etc.)
+- `POST /api/v1/install/{name}/{version}` — Record agent installation
+
+[Full marketplace API documentation →](./docs/MARKETPLACE_API.md)
+
+### Tool Dependency Management
+
+Agents can declare and manage their tool dependencies (binaries, packages, services):
+
+```bash
+# Check if all dependencies are available
+devloop agent dependencies check ./my-agent
+
+# Automatically resolve and install missing dependencies
+devloop agent dependencies resolve ./my-agent
+
+# List declared dependencies
+devloop agent dependencies list ./my-agent
+```
+
+**Declaring dependencies in agent metadata:**
+
+```json
+{
+  "name": "security-scanner",
+  "version": "2.0.0",
+  "toolDependencies": {
+    "bandit": {
+      "type": "python",
+      "minVersion": "1.7.0",
+      "package": "bandit"
+    },
+    "shellcheck": {
+      "type": "binary",
+      "minVersion": "0.8.0",
+      "install": "apt-get install shellcheck"
+    },
+    "npm": {
+      "type": "npm-global",
+      "minVersion": "8.0.0",
+      "package": "npm"
+    }
+  },
+  "pythonVersion": ">=3.11",
+  "devloopVersion": ">=0.5.0"
+}
+```
+
+**Supported dependency types:**
+- `python` — Python packages (installed via pip)
+- `npm-global` — npm packages installed globally
+- `binary` — System binaries/executables
+- `venv` — Virtual environment executables
+- `docker` — Docker images
+
+When installing an agent, DevLoop automatically detects missing dependencies and prompts you to install them.
+
+### Agent Metadata Schema
+
+```json
+{
+  "name": "my-agent",
+  "version": "1.0.0",
+  "description": "What this agent does",
+  "author": "Your Name",
+  "license": "MIT",
+  "homepage": "https://example.com",
+  "repository": "https://github.com/you/my-agent",
+  "categories": ["code-quality"],
+  "keywords": ["quality", "analysis"],
+  "pythonVersion": ">=3.11",
+  "devloopVersion": ">=0.5.0",
+  "toolDependencies": {
+    "tool-name": {
+      "type": "python|binary|npm-global|docker",
+      "minVersion": "1.0.0",
+      "package": "package-name",
+      "install": "apt-get install tool-name"
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "enabled": {"type": "boolean"},
+      "severity": {"type": "string", "enum": ["low", "medium", "high"]}
+    }
+  },
+  "publishedAt": "2025-12-13T10:30:00Z",
+  "deprecated": false,
+  "deprecationMessage": null,
+  "maintainer": "username",
+  "rating": {
+    "average": 4.5,
+    "count": 120
+  }
+}
+```
+
+**Schema explanation:**
+- `toolDependencies` — External tools/packages this agent requires
+- `configSchema` — JSON schema defining agent configuration options
+- `publishedAt` — When agent was first published
+- `deprecated` — Whether agent is deprecated and shouldn't be used
+- `deprecationMessage` — Suggested alternative if deprecated
+- `maintainer` — DevLoop username of agent maintainer
+- `rating` — Community ratings and review count (auto-updated)
+
+---
+
+## VSCode Extension
+
+DevLoop provides a VSCode extension for real-time agent feedback directly in your editor.
+
+### Installation
+
+**Option 1: From VSCode Marketplace**
+```
+Open VSCode → Extensions → Search "devloop" → Click Install
+```
+
+**Option 2: Manual Installation**
+```bash
+# Install from the devloop repository
+git clone https://github.com/wioota/devloop
+cd devloop/vscode-extension
+npm install
+npm run compile
+# Extension is now installed in ~/.vscode/extensions/devloop-*
+```
+
+### Features
+
+- **Real-time Findings** — View linting, type checking, and security issues inline
+- **Quick Fixes** — Apply auto-fixes directly from the editor
+- **Status Bar** — Shows agent status, finding count, and health metrics
+- **Diagnostics Panel** — Detailed findings organized by agent and severity
+- **Multi-language Support** — Python, JavaScript, TypeScript, and more
+
+### Usage
+
+Once installed, DevLoop automatically:
+1. Monitors your editor for file changes
+2. Runs background agents via the LSP server
+3. Displays findings as inline diagnostics
+4. Provides quick fix actions for auto-fixable issues
+
+**View findings:**
+- Hover over squiggly lines to see details
+- Click quick fix actions to apply changes
+- Open Problems panel (Ctrl+Shift+M) to see all findings
+- Check status bar for agent health
+
+**Configuration:**
+Extension settings are automatically synced with `.devloop/agents.json`. No separate configuration needed.
+
+---
+
 ### Code Rabbit Integration
 
 Code Rabbit Agent provides AI-powered code analysis with insights on code quality, style, and best practices.
@@ -516,6 +916,56 @@ export SNYK_TOKEN="your-snyk-token"
 
 ---
 
+## Multi-CI/Registry Provider System
+
+DevLoop uses a provider abstraction layer for CI/CD and package registry support. This means you can use DevLoop with any CI system and publish to any package registry.
+
+### Supported CI Platforms
+
+DevLoop auto-detects and works with:
+- **GitHub Actions** — Default, with pre-push CI verification
+- **GitLab CI/CD** — Full support with pipeline status monitoring
+- **Jenkins** — Classic and declarative pipelines
+- **CircleCI** — OAuth2 and API token authentication
+- **Custom CI** — Via manual configuration
+
+### Supported Package Registries
+
+Publish agents and packages to:
+- **PyPI** — Python Package Index (via Poetry or Twine)
+- **npm** — Node Package Manager
+- **Docker Registry** — Docker Hub or custom registries
+- **GitHub Releases** — Attach artifacts to releases
+- **Custom Registries** — Via manual configuration (Artifactory, etc.)
+
+### Release Workflow
+
+DevLoop provides a unified release process across all providers:
+
+```bash
+# Check if ready to release
+devloop release check 1.2.3
+
+# Publish to detected CI/registry
+devloop release publish 1.2.3
+
+# Specify explicit providers
+devloop release publish 1.2.3 --ci github --registry pypi
+
+# Dry-run to see what would happen
+devloop release publish 1.2.3 --dry-run
+```
+
+The release workflow automatically:
+1. Validates preconditions (clean git, passing CI, valid version)
+2. Creates annotated git tag
+3. Publishes to registry
+4. Pushes tag to remote repository
+
+[Full provider documentation →](./docs/PROVIDER_SYSTEM.md)
+
+---
+
 ## Configuration
 
 Configure agent behavior in `.devloop/agents.json`:
@@ -553,10 +1003,142 @@ Configure agent behavior in `.devloop/agents.json`:
 
 ⚠️ **Auto-fix Warning:** Currently auto-fixes run without backups or review. **DO NOT enable auto-fix in production** or on critical code. Track [secure auto-fix with backups issue](https://github.com/wioota/devloop/issues/emc).
 
+### Token Security
+
+DevLoop securely manages API keys and tokens for agent integrations:
+
+```bash
+# Use environment variables for all credentials
+export SNYK_TOKEN="your-token"
+export CODE_RABBIT_API_KEY="your-key"
+export GITHUB_TOKEN="your-token"
+
+# DevLoop automatically:
+# - Hides tokens in logs and process lists
+# - Validates token format and expiry
+# - Warns about placeholder values ("changeme", "token", etc.)
+# - Never logs full token values
+```
+
+**Best practices:**
+- ✅ Use environment variables (never command-line arguments)
+- ✅ Enable token expiry and rotation (30-90 days recommended)
+- ✅ Use read-only or project-scoped tokens when possible
+- ✅ Store tokens in `.env` file (add to `.gitignore`)
+- ❌ Never commit tokens to git
+- ❌ Never pass tokens as command arguments
+- ❌ Never hardcode tokens in code
+
+**Token validation:**
+```bash
+# DevLoop validates token format during initialization
+devloop init /path/to/project
+
+# View token status
+devloop status --show-token-info
+```
+
+[Full token security guide →](./docs/TOKEN_SECURITY.md)
+
 [Full configuration reference →](./docs/configuration.md)
 
 ---
 
+## Integration with Beads
+
+DevLoop integrates with [Beads](https://github.com/wioota/devloop) task tracking to create actionable work items from detected patterns.
+
+### Auto-Issue Creation
+
+DevLoop automatically creates Beads issues for significant findings:
+
+```bash
+# View auto-created issues from DevLoop findings
+bd ready           # Shows unblocked work
+bd show bd-abc123  # View specific issue created by DevLoop
+```
+
+**What gets tracked:**
+- Security vulnerabilities (high/critical only)
+- Performance regressions
+- Pattern discoveries (e.g., "same issue found 3 times")
+- Failing tests in CI
+- Deprecated dependencies
+
+**Issue linking:**
+DevLoop uses `discovered-from` dependencies to link:
+- Findings → Beads issues → Original agent
+- Patterns across multiple findings
+- Root cause analysis chains
+
+### Thread Context Capture
+
+When using DevLoop in [Amp](https://ampcode.com) threads:
+
+```bash
+# Automatically captures thread context (if AMP_THREAD_ID is set)
+devloop watch .
+```
+
+DevLoop logs:
+- Thread ID and URL
+- Commands executed
+- Agent findings and results
+- Patterns detected across sessions
+
+This enables cross-thread pattern detection:
+> "This type of error appeared in 5 different threads — likely a documentation gap"
+
+---
+
+## Event Logging & Observability
+
+DevLoop maintains a complete audit trail of agent activity for debugging and analysis.
+
+### Event Store
+
+All agent actions are logged to an SQLite event store in `.devloop/events.db`:
+
+```bash
+# View recent agent activity
+devloop audit query --limit 20
+
+# Filter by agent
+devloop audit query --agent linter
+
+# View agent health metrics
+devloop health
+```
+
+**Event data includes:**
+- Agent name and execution time
+- Success/failure status
+- Finding count and types
+- Resource usage (CPU, memory)
+- Timestamps and correlations
+
+### Log Files
+
+Application logs are stored in `.devloop/devloop.log` with rotation:
+
+```bash
+# View logs in real-time
+tail -f .devloop/devloop.log
+
+# View verbose logs during watch
+devloop watch . --verbose --foreground
+
+# Check log disk usage
+du -sh .devloop/devloop.log*
+```
+
+**Log rotation:**
+- Max file size: 100MB
+- Keep 3 backups (300MB max)
+- Auto-cleanup logs older than 7 days
+
+---
+
 ## CI/CD Integration
 
 DevLoop includes GitHub Actions integration with automated security scanning.
@@ -668,7 +1250,7 @@ poetry run pytest tests/unit/agents/test_linter.py -v
 poetry run pytest -v
 ```
 
-**Current status:** ✅ 112+ tests passing
+**Current status:** ✅ 737+ tests passing
 
 [View test strategy →](./docs/testing.md)
 
@@ -734,11 +1316,24 @@ poetry run mypy src
 
 ## Documentation
 
+### User Guides
 - **[Getting Started Guide](./docs/getting-started.md)** — Installation and basic usage
 - **[Architecture Guide](./docs/architecture.md)** — System design and components
-- **[Agent Reference](./docs/agents.md)** — All available agents
 - **[Configuration Guide](./docs/configuration.md)** — Full config reference
 - **[CLI Commands](./docs/cli-commands.md)** — Command reference
+
+### Agent Development
+- **[Agent Development Guide](./docs/AGENT_DEVELOPMENT.md)** — Tutorial on creating agents with patterns and best practices
+- **[Agent API Reference](./docs/AGENT_API_REFERENCE.md)** — Complete API documentation for all agent classes and interfaces
+- **[Agent Examples](./docs/AGENT_EXAMPLES.md)** — Real-world examples from simple to advanced implementations
+- **[Agent Troubleshooting](./docs/AGENT_TROUBLESHOOTING.md)** — Common issues and solutions
+
+### Marketplace
+- **[Marketplace Guide](./docs/MARKETPLACE_GUIDE.md)** — Discovering, installing, and publishing agents
+- **[Marketplace API Guide](./docs/MARKETPLACE_API.md)** — Agent registry API reference
+- **[Agent Reference](./docs/agents.md)** — Built-in agents documentation
+
+### Advanced
 - **[Development Guide](./docs/development.md)** — Contributing guide
 - **[Implementation Status](./IMPLEMENTATION_STATUS.md)** — What's implemented
 - **[Learning & Optimization](./PHASE3_COMPLETE.md)** — Advanced features
@@ -829,16 +1424,18 @@ ls -la .devloop/custom_agents/
 - Workflow automation: git integration, CI monitoring, documentation
 - Custom agents: create your own without writing code
 - Learning system: pattern recognition and optimization
+- **Agent Marketplace** — Registry API, publishing, signing, discovery (737+ tests)
 
 ### In Development 🚀
-- Cloud pattern repository (opt-in)
+- Remote agent registry and cloud sync
 - Agent composition and pipelines
-- Community agent sharing
+- Community agent sharing and rating improvements
 
 ### Future 🔮
 - Multi-project support
 - Team coordination features
 - LLM-powered agents
+- Agent marketplace web interface
 
 ---
 
@@ -917,4 +1514,12 @@ Built with:
 
 **Made with ❤️ by the DevLoop team**
 
+## Footnotes
+
+[^1]: **90%+ CI failures caught locally** — Based on typical Python/TypeScript development workflows with comprehensive linting, formatting, and type checking. Actual results depend on your agent configuration and test suite. DevLoop's effectiveness increases with more agents enabled and better test coverage. See [docs/UPGRADE_GUIDE.md](docs/UPGRADE_GUIDE.md#version-compatibility) for feature availability by version.
+
+[^2]: **60%+ CI cost reduction** — Estimated reduction assumes: (1) 6-8 CI failures per day baseline, (2) ~15 minutes per failure roundtrip, (3) CI costs proportional to pipeline runs. This is a theoretical projection based on typical development patterns. Actual cost savings depend on your CI pricing model, agent configuration, and codebase size. For verified metrics, see [docs/METRICS_AND_MONITORING.md](./docs/METRICS_AND_MONITORING.md).
+
+[^3]: **6-8 CI failures per day and 75-90 minutes saved** — These estimates are based on typical multi-developer teams working on moderately complex codebases. They assume agents catch common issues (formatting, linting, type errors, security warnings) before push. Your actual results will vary significantly based on: code complexity, team size, quality of tests, agent configuration, and development practices. For personalized ROI calculation, enable metrics tracking in `.devloop/agents.json` and see `devloop telemetry stats`. DevLoop will collect real usage data as you use it, which can replace these estimates with empirically validated numbers.
+