From fe9c53f46f66a26b5f05a575926a0bea1152cedd Mon Sep 17 00:00:00 2001
From: Beyond Better <git@beyondbetter.app>
Date: Tue, 4 Nov 2025 15:45:42 +1100
Subject: [PATCH 1/8] Updated docs for new plugin schema

Applied changes from BB to 1 file

Files modified:
- docs/CREATING_TOOLS.md

Updated tool creation documentation

Applied changes from BB to 1 file

Files modified:
- docs/CREATING_TOOLS.md

Updated tool creation documentation with improved examples and clarifications

Applied changes from BB to 1 file

Files modified:
- docs/CREATING_TOOLS.md

Updated CREATING_TOOLS documentation

Applied changes from BB to 1 file

Files modified:
- docs/CREATING_TOOLS.md

Updated tool creation documentation

Applied changes from BB to 1 file

Files modified:
- docs/CREATING_TOOLS.md

Updated tool creation documentation with improved guidelines and examples

Applied changes from BB to 1 file

Files modified:
- docs/CREATING_TOOLS.md

Updated TESTING.md documentation

Applied changes from BB to 1 file

Files modified:
- docs/TESTING.md

Updated testing documentation

Applied changes from BB to 1 file

Files modified:
- docs/TESTING.md

Updated tools documentation

Applied changes from BB to 1 file

Files modified:
- docs/tools.md

Updated GUIDELINES.md documentation

Applied changes from BB to 1 file

Files modified:
- GUIDELINES.md

Updated guidelines documentation

Applied changes from BB to 1 file

Files modified:
- GUIDELINES.md

Updated GUIDELINES.md with clarifications and improvements

Applied changes from BB to 1 file

Files modified:
- GUIDELINES.md

Updated GUIDELINES.md with formatting and content improvements

Applied changes from BB to 1 file

Files modified:
- GUIDELINES.md

Update GUIDELINES.md with clarifications and improvements

Applied changes from BB to 1 file

Files modified:
- GUIDELINES.md

Updated GUIDELINES.md with formatting and clarity improvements

Applied changes from BB to 1 file

Files modified:
- GUIDELINES.md

Updated GUIDELINES.md with clarifications and improvements

Applied changes from BB to 1 file

Files modified:
- GUIDELINES.md

Update GUIDELINES.md with clarifications and improvements

Applied changes from BB to 1 file

Files modified:
- GUIDELINES.md

Updated GUIDELINES.md with clarifications and improvements

Applied changes from BB to 1 file

Files modified:
- GUIDELINES.md

Updated GUIDELINES.md with improvements to documentation standards

Applied changes from BB to 1 file

Files modified:
- GUIDELINES.md

Added plugin manifest schema for Beyond Better plugin packages

Defined the JSON schema for .bbplugin metadata files, specifying required fields (name, version, description, tools), optional metadata (author, license, repository, contributors), and structured validation for plugin naming conventions, semantic versioning, and component references.

Applied changes from BB to 1 file

Files modified:
- docs/plugin-manifest-schema.json

Updated GUIDELINES.md with formatting and clarity improvements

Applied changes from BB to 1 file

Files modified:
- GUIDELINES.md

Updated README.md documentation

Applied changes from BB to 1 file

Files modified:
- README.md

Updated README.md documentation

Applied changes from BB to 1 file

Files modified:
- README.md

Updated README.md with improved documentation

Applied changes from BB to 1 file

Files modified:
- README.md

Updated README.md with documentation improvements

Applied changes from BB to 1 file

Files modified:
- README.md

Updated README.md documentation

Applied changes from BB to 1 file

Files modified:
- README.md

Updated README.md documentation

Applied changes from BB to 1 file

Files modified:
- README.md
---
 GUIDELINES.md                    | 196 ++++++++++----
 README.md                        |  94 +++++--
 docs/CREATING_TOOLS.md           | 452 +++++++++++++++++++++++++++----
 docs/TESTING.md                  |  24 +-
 docs/plugin-manifest-schema.json | 247 +++++++++++++++++
 docs/tools.md                    |  23 +-
 6 files changed, 890 insertions(+), 146 deletions(-)
 create mode 100644 docs/plugin-manifest-schema.json

diff --git a/GUIDELINES.md b/GUIDELINES.md
index aecd3ef..0b93475 100644
--- a/GUIDELINES.md
+++ b/GUIDELINES.md
@@ -1,23 +1,28 @@
 ---
-title: BB Tools Framework Guidelines
+title: BB Plugin Framework Guidelines
 project: bb-tools
-version: 1.0.0
+version: 1.1.0
 created: 2025-11-02
-updated: 2025-11-02
+updated: 2025-11-04
 purpose: Guidelines for LLM collaboration on bb-tools framework development
+note: Project may be renamed to bb-plugins in future
 ---
 
-# BB Tools Framework Guidelines
+# BB Plugin Framework Guidelines
 
 ## Project Purpose and Scope
 
 ### Overview
-bb-tools (@beyondbetter/tools) is the core framework/library for building tools that work with the Beyond Better (BB) AI assistant. This project provides base classes, interfaces, types, and utilities needed to create properly structured BB tools.
+bb-tools (@beyondbetter/tools) is the core framework/library for building plugins that work with the Beyond Better (BB) AI assistant. This project provides base classes, interfaces, types, and utilities needed to create properly structured BB plugins containing tools and datasources.
 
 **IMPORTANT**: These guidelines are for working on the bb-tools framework itself, NOT for users/consumers of the framework. The audience is the LLM assisting with framework development, maintenance, and enhancement.
 
+**NOTE**: This project may be renamed to `bb-plugins` in the future to better reflect its purpose.
+
 ### Project Goals
 - Provide robust base classes (LLMTool) for tool creation
+- Define standardized plugin structure (.bbplugin format with manifest.json)
+- Support both tool and datasource components within plugins
 - Define standardized interfaces (IProjectEditor, IConversationInteraction)
 - Supply formatting utilities for browser (JSX/Preact) and console (ANSI)
 - Maintain comprehensive type definitions
@@ -34,16 +39,18 @@ bb-tools (@beyondbetter/tools) is the core framework/library for building tools
 ### Project Scope
 **In Scope:**
 - Framework core classes and utilities
+- Plugin structure definition (.bbplugin format)
+- Plugin manifest schema and validation
 - Type definitions and interfaces
-- Example tools demonstrating framework usage
-- Documentation for tool creators
+- Example plugins demonstrating framework usage
+- Documentation for plugin creators
 - JSR publishing configuration
 
 **Out of Scope:**
-- Individual tools created by framework consumers
+- Individual plugins created by framework consumers
 - Beyond Better (BB) main application code
-- Tool runtime environment (handled by BB)
-- Tool distribution/marketplace
+- Plugin runtime environment (handled by BB)
+- Plugin distribution marketplace (future BB feature)
 
 ## Available Data Sources and Resources
 
@@ -77,24 +84,33 @@ deno.lock           # Dependency lock file
 
 #### Documentation (`docs/`)
 ```
-CREATING_TOOLS.md   # Guide for tool creators (consumers)
-TESTING.md          # Testing guidelines for tools
+CREATING_TOOLS.md   # Guide for plugin creators (consumers)
+TESTING.md          # Testing guidelines for plugins
 tools.md            # Comprehensive framework reference
+plugin-manifest-schema.json  # JSON schema for manifest.json
 ```
 
-#### Example Tools (`examples/`)
+#### Example Plugins (`examples/`)
 ```
 mod.ts              # Examples module exports
+search-plugin.bbplugin/
+  ├── manifest.json             # Plugin metadata
+  └── search-project.tool/
+      ├── tool.ts               # Tool implementation
+      ├── formatter.browser.tsx # Browser formatting
+      ├── formatter.console.ts  # Console formatting
+      ├── info.json             # Tool metadata
+      ├── types.ts              # Tool-specific types
+      ├── tool.test.ts          # Tool tests
+      └── README.md             # Tool documentation
+browser-plugin.bbplugin/
+  ├── manifest.json
+  └── open-in-browser.tool/
+      └── (same structure)
+
+# Legacy (deprecated, for backward compatibility):
 search_project.tool/
-  ├── tool.ts                   # Tool implementation
-  ├── formatter.browser.tsx     # Browser formatting
-  ├── formatter.console.ts      # Console formatting
-  ├── info.json                 # Tool metadata
-  ├── types.ts                  # Tool-specific types
-  ├── tool.test.ts              # Tool tests
-  └── README.md                 # Tool documentation
 open_in_browser.tool/
-  └── (same structure)
 ```
 
 #### Other Files
@@ -113,11 +129,13 @@ LICENSE             # MIT License
    - Update type definitions if interfaces change
    - Test with example tools after changes
 
-2. **Example Tool Development**
-   - Follow established tool structure
-   - Include all standard files (tool.ts, formatters, tests, README, info.json)
+2. **Example Plugin Development**
+   - Create .bbplugin directory with manifest.json
+   - Follow established plugin and tool structure
+   - Include all standard files (manifest.json, tool.ts, formatters, tests, README, info.json)
    - Use framework utilities consistently
    - Demonstrate specific framework features
+   - Show both single-tool and multi-tool plugin patterns
 
 3. **Documentation Updates**
    - Keep in sync with code changes
@@ -182,25 +200,57 @@ LICENSE             # MIT License
 - GitHub Actions workflow handles publishing
 - Follow semantic versioning
 
-## Tool Creation Guidelines
+## Plugin Creation Guidelines
+
+### Standard Plugin Structure
+When creating example plugins or documenting plugin patterns:
 
-### Standard Tool Structure
-When creating example tools or documenting tool patterns:
+```
+plugin-name.bbplugin/
+├── manifest.json             # Required: Plugin metadata
+├── tool-name.tool/
+│   ├── tool.ts               # Tool implementation (extends LLMTool)
+│   ├── formatter.browser.tsx # Browser UI formatting (JSX/Preact)
+│   ├── formatter.console.ts  # Console output formatting (ANSI)
+│   ├── info.json             # Tool metadata and examples
+│   ├── types.ts              # Tool-specific types (if needed)
+│   ├── tool.test.ts          # Comprehensive tests
+│   └── README.md             # Tool documentation
+└── another-tool.tool/        # Additional tools (optional)
+    └── (same structure)
+```
 
+### Legacy Tool Structure (Deprecated)
 ```
-tool_name.tool/
-├── tool.ts                   # Tool implementation (extends LLMTool)
-├── formatter.browser.tsx     # Browser UI formatting (JSX/Preact)
-├── formatter.console.ts      # Console output formatting (ANSI)
-├── info.json                 # Tool metadata and examples
-├── types.ts                  # Tool-specific types (if needed)
-├── tool.test.ts              # Comprehensive tests
-└── README.md                 # Tool documentation
+tool_name.tool/               # Standalone tool (deprecated)
+├── tool.ts
+├── formatter.browser.tsx
+├── formatter.console.ts
+├── info.json
+├── types.ts
+├── tool.test.ts
+└── README.md
 ```
 
+**Note**: While BB still supports standalone `.tool` directories for backward compatibility, all new development should use the `.bbplugin` structure.
+
+### Plugin Manifest Requirements
+
+**manifest.json** at plugin root:
+- **name**: Plugin package name (kebab-case)
+- **version**: Semantic version (major.minor.patch)
+- **author**: Creator name or organization
+- **description**: Brief plugin description
+- **license**: License identifier (e.g., MIT, Apache-2.0)
+- **tools**: Array of tool directory names (e.g., ["search-tool.tool"])
+- **datasources**: Array of datasource directory names (optional, future support)
+- **bbVersion**: Minimum BB version (e.g., ">=0.9.0")
+
+See [Plugin Manifest Schema](#plugin-manifest-schema) for complete specification.
+
 ### Key Implementation Requirements
 
-1. **Tool Class**
+1. **Tool Class** (within each .tool directory)
    - Extend `LLMTool` base class
    - Implement `inputSchema` getter (JSON Schema)
    - Implement `runTool` method
@@ -447,15 +497,17 @@ When reviewing or modifying framework code:
 6. **Consider examples**: Should example tools demonstrate this?
 7. **Test with examples**: Verify examples still work
 
-### Creating a New Example Tool
+### Creating a New Example Plugin
 
-1. **Create directory**: `examples/tool_name.tool/`
-2. **Implement tool.ts**: Extend LLMTool, implement required methods
-3. **Create formatters**: Both browser.tsx and console.ts
-4. **Add info.json**: Metadata and examples
-5. **Write tests**: Comprehensive coverage
-6. **Document in README**: Usage and implementation details
-7. **Export from examples/mod.ts**: Make available to framework users
+1. **Create plugin directory**: `examples/plugin-name.bbplugin/`
+2. **Create manifest.json**: Plugin metadata with name, version, author, description, tools list
+3. **Create tool directory**: `examples/plugin-name.bbplugin/tool-name.tool/`
+4. **Implement tool.ts**: Extend LLMTool, implement required methods
+5. **Create formatters**: Both browser.tsx and console.ts
+6. **Add info.json**: Tool metadata and examples
+7. **Write tests**: Comprehensive coverage for each tool
+8. **Document in README**: Plugin overview and tool usage
+9. **Export from examples/mod.ts**: Make available to framework users
 
 ### Updating Documentation
 
@@ -477,22 +529,53 @@ When reviewing or modifying framework code:
 
 ## Framework-Specific Considerations
 
+### Plugin Manifest Schema
+
+The manifest.json schema is defined in `docs/plugin-manifest-schema.json`. Key requirements:
+
+**Required Fields:**
+- `name`: Kebab-case plugin identifier
+- `version`: Semantic version string
+- `description`: Plugin description (10-500 chars)
+- `tools`: Array of tool directory names
+
+**Optional Fields:**
+- `author`: Creator name/organization
+- `license`: License identifier (SPDX format)
+- `datasources`: Array of datasource directory names
+- `bbVersion`: Minimum BB version (semver range)
+- `homepage`: Plugin homepage URL
+- `repository`: Repository information object
+- `keywords`: Array of discovery keywords
+
+**Validation:**
+- All listed tools must exist as directories
+- Directory names must match exactly (case-sensitive)
+- Version must follow semver format
+- Plugin name must be valid kebab-case
+
 ### Understanding the Framework Architecture
 
 **Core Concepts:**
+- **Plugin Package**: .bbplugin directory containing manifest and components
+- **Plugin Manifest**: manifest.json with metadata and component lists
 - **LLMTool**: Base class providing common functionality
+- **Tool Components**: Individual .tool directories within plugin
+- **Datasource Components**: Individual .datasource directories (future support)
 - **IProjectEditor**: Interface for file/project operations (consumed by tools)
 - **IConversationInteraction**: Interface for conversation context (consumed by tools)
 - **Formatters**: Dual formatting for browser UI and console output
 - **Tool Metadata**: info.json provides tool information to BB
 
-**Tool Lifecycle:**
-1. Tool registered with BB
-2. LLM decides to use tool based on capabilities
-3. BB validates input against `inputSchema`
-4. Tool's `runTool` method executes
-5. Results formatted for display (browser or console)
-6. Results returned to LLM
+**Plugin Lifecycle:**
+1. Plugin discovered in configured directories
+2. Manifest validated by BB
+3. Tools registered with BB from plugin
+4. LLM decides to use tool based on capabilities
+5. BB validates input against `inputSchema`
+6. Tool's `runTool` method executes
+7. Results formatted for display (browser or console)
+8. Results returned to LLM
 
 ### Maintaining Backward Compatibility
 
@@ -806,6 +889,17 @@ Deno.test({
 
 ## Version History
 
+### 1.1.0 (2025-11-04)
+- Updated for new .bbplugin plugin structure
+- Added plugin manifest requirements and schema
+- Documented plugin packaging and distribution
+- Updated all documentation for plugin-first approach
+- Added plugin-manifest-schema.json
+- Marked standalone .tool structure as deprecated
+- Added datasource component support (future)
+- Updated example structure to show plugin packages
+- Note: Project may be renamed to bb-plugins
+
 ### 1.0.1 (2025-11-02)
 - Enhanced with details from docs/CREATING_TOOLS.md
 - Added tool types and patterns (File System, Data Processing, Network)
diff --git a/README.md b/README.md
index 8a18a7b..1a877c7 100644
--- a/README.md
+++ b/README.md
@@ -4,19 +4,27 @@
 [![JSR](https://jsr.io/badges/@beyondbetter/tools)](https://jsr.io/@beyondbetter/tools)
 [![JSR Score](https://jsr.io/badges/@beyondbetter/tools/score)](https://jsr.io/@beyondbetter/tools)
 
-Core tool infrastructure for building BB (Beyond Better) AI assistant tools. This package provides
-the base classes, interfaces, and types needed to create tools that can be used with the BB AI
-assistant.
+Core plugin infrastructure for building BB (Beyond Better) AI assistant plugins. This package provides
+the base classes, interfaces, types, and plugin structure needed to create plugins containing tools and
+datasources that can be used with the BB AI assistant.
+
+**Note**: This package may be renamed to `@beyondbetter/plugins` in the future.
 
 ## Features
 
-- Base tool class with standardized interfaces
-- Browser and console formatting with consistent styling
-- Comprehensive type definitions
-- Project and conversation management interfaces
-- Built-in input validation using JSON Schema
-- Extensive testing utilities
-- Tool metadata and examples support
+- **Plugin Structure**: Structured `.bbplugin` format with manifest support
+- **Multi-Component Support**: Package multiple tools and datasources together
+- **Base Tool Class**: Standardized LLMTool base class with consistent interfaces
+- **Dual Formatting**: Browser (JSX/Preact) and console (ANSI) output formatting
+- **Type Safety**: Comprehensive TypeScript type definitions
+- **Project & Conversation**: Standardized interfaces for file and conversation management
+- **Input Validation**: Built-in JSON Schema validation
+- **Testing Utilities**: Extensive testing helpers and utilities
+- **Metadata Support**: Plugin and tool metadata with examples
+- **Version Management**: Semantic versioning with BB compatibility checks
+- **Distribution Ready**: Double-click installation support (.bbplugin files)
+
+**Note**: Standalone `.tool` directories are deprecated but still supported for backward compatibility.
 
 ## Installation
 
@@ -30,18 +38,37 @@ import { LLMTool } from "jsr:@beyondbetter/tools";
 
 ## Quick Start
 
-1. Create tool structure:
+### Plugin Structure
+
+1. Create plugin package:
 
 ```
-my-tool/
-├── tool.ts             # Main implementation
-├── info.json          # Tool metadata
-├── formatter.browser.tsx    # Browser formatting
-├── formatter.console.ts     # Console formatting
-└── tool.test.ts       # Tests
+my-plugin.bbplugin/
+├── manifest.json       # Plugin metadata (required)
+└── my-tool.tool/      # Tool directory
+    ├── tool.ts        # Main implementation
+    ├── info.json      # Tool metadata
+    ├── formatter.browser.tsx  # Browser formatting
+    ├── formatter.console.ts   # Console formatting
+    └── tool.test.ts   # Tests
 ```
 
-2. Define tool metadata (info.json):
+2. Create plugin manifest (manifest.json):
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "author": "Your Name",
+  "description": "Description of your plugin",
+  "license": "MIT",
+  "tools": ["my-tool.tool"],
+  "datasources": [],
+  "bbVersion": ">=0.9.0"
+}
+```
+
+3. Define tool metadata (my-tool.tool/info.json):
 
 ```json
 {
@@ -61,7 +88,7 @@ my-tool/
 }
 ```
 
-3. Implement the tool (tool.ts):
+4. Implement the tool (my-tool.tool/tool.ts):
 
 ```typescript
 import LLMTool, {
@@ -123,7 +150,7 @@ class MyTool extends LLMTool {
 }
 ```
 
-4. Implement browser formatting (formatter.browser.tsx):
+5. Implement browser formatting (my-tool.tool/formatter.browser.tsx):
 
 ```typescript
 /** @jsxImportSource preact */
@@ -154,7 +181,7 @@ export function formatLogEntryToolUse(
 }
 ```
 
-5. Implement console formatting (formatter.console.ts):
+6. Implement console formatting (my-tool.tool/formatter.console.ts):
 
 ```typescript
 import { stripIndents } from 'common-tags';
@@ -183,7 +210,19 @@ export function formatLogEntryToolUse(
 }
 ```
 
-6. Use the tool:
+7. Install and use the plugin:
+
+```bash
+# Copy plugin to BB plugins directory
+cp -r my-plugin.bbplugin ~/.config/bb/plugins/
+
+# Or double-click the .bbplugin directory (macOS/Windows)
+# BB will show installation dialog
+
+# Restart BB API to load the plugin
+```
+
+8. Use the tool:
 
 ```typescript
 const tool = new MyTool();
@@ -202,9 +241,11 @@ const result = await tool.runTool(
 
 ## Documentation
 
-- [Creating Tools](./docs/CREATING_TOOLS.md) - Detailed guide for creating new tools
+- [Creating Plugins](./docs/CREATING_TOOLS.md) - Detailed guide for creating new plugins
 - [Testing Guide](./docs/TESTING.md) - Testing requirements and guidelines
-- [Tools Reference](./docs/tools.md) - Comprehensive tool framework documentation
+- [Plugin Framework Reference](./docs/tools.md) - Comprehensive framework documentation
+- [Plugin Manifest Schema](./docs/plugin-manifest-schema.json) - JSON schema for manifest.json
+- [Guidelines](./GUIDELINES.md) - Framework development guidelines
 
 ## Core Interfaces
 
@@ -240,8 +281,9 @@ Conversation management interface:
 
 1. Fork the repository
 2. Create your feature branch
-3. Follow the [Creating Tools](./docs/CREATING_TOOLS.md) guide
-4. Ensure tests pass using \`deno test\`
+3. Follow the [Creating Plugins](./docs/CREATING_TOOLS.md) guide
+4. Follow the [Guidelines](./GUIDELINES.md) for framework development
+5. Ensure tests pass using \`deno test\`
 5. Submit a pull request
 
 ## Testing
diff --git a/docs/CREATING_TOOLS.md b/docs/CREATING_TOOLS.md
index ff4a762..979a322 100644
--- a/docs/CREATING_TOOLS.md
+++ b/docs/CREATING_TOOLS.md
@@ -1,53 +1,107 @@
-# Creating Tools for BB
+# Creating BB Plugins
 
-This guide provides comprehensive instructions for creating new tools in the BB ecosystem. It covers
-the entire process from planning to implementation and testing.
+This guide provides comprehensive instructions for creating new plugins for the Beyond Better (BB) ecosystem. Each plugin can contain one or more tools and/or datasources, packaged in a structured `.bbplugin` directory.
 
 ## Overview
 
-When creating a new tool:
-
-1. Use an existing tool as a template
-2. Follow established patterns and conventions
-3. Maintain consistent structure and style
-4. Implement comprehensive testing
+BB plugins use a structured directory format that enables:
+- Easy distribution and installation
+- Multiple tools and datasources in a single package
+- Clear metadata and versioning
+- OS-level file association for double-click installation
+
+**Note**: The standalone `.tool` directory structure is deprecated but still supported. All new development should use the `.bbplugin` structure.
+
+## Plugin Structure
+
+### Basic Plugin Package
+
+```
+your-plugin.bbplugin/
+├── manifest.json          # Required: Plugin metadata
+├── your-tool.tool/       # Tool directory
+│   ├── tool.ts          # Tool implementation
+│   ├── info.json        # Tool metadata
+│   ├── formatter.browser.tsx    # Browser formatting
+│   ├── formatter.console.ts     # Console formatting
+│   └── tool.test.ts     # Tool tests
+└── another-tool.tool/   # Additional tools (optional)
+    ├── tool.ts
+    ├── info.json
+    ├── formatter.browser.tsx
+    ├── formatter.console.ts
+    └── tool.test.ts
+```
+
+### Multi-Component Plugin
+
+```
+advanced-plugin.bbplugin/
+├── manifest.json          # Required: Plugin metadata
+├── search-tool.tool/     # Tool component
+│   ├── tool.ts
+│   ├── info.json
+│   └── ...
+└── api-datasource.datasource/  # Datasource component (future support)
+    ├── datasource.ts
+    ├── info.json
+    └── ...
+```
 
 ## Step-by-Step Guide
 
-1. **Choose a Reference Tool**
-   - Select an existing tool similar to your planned functionality
+1. **Choose a Reference Plugin**
+   - Select an existing plugin similar to your planned functionality
    - Use it as a template throughout development
 
 2. **Gather Information**
    ```typescript
-   // Information Template
+   // Plugin Planning Template
    {
-     toolName: string;           // Descriptive name
-     description: string;        // Brief purpose
-     inputSchema: JSONSchema4;   // Parameter definitions
-     expectedOutput: string;     // What tool returns
-     requiredActions: string[];  // Main functionality
-     errorScenarios: string[];   // Error handling cases
+     pluginName: string;         // Plugin package name
+     version: string;            // Semantic version
+     description: string;        // Plugin purpose
+     author: string;            // Creator name
+     license: string;           // License type
+     tools: {
+       toolName: string;        // Tool name
+       description: string;     // Tool purpose
+       inputSchema: JSONSchema4; // Parameters
+       expectedOutput: string;  // Return value
+       requiredActions: string[]; // Functionality
+       errorScenarios: string[]; // Error cases
+     }[];
+     datasources?: {...}[];     // Future datasource components
    }
    ```
 
-3. **Create Tool Structure**
+3. **Create Plugin Package Structure**
+   ```bash
+   mkdir -p your-plugin.bbplugin/your-tool.tool
    ```
-   your-tool/
-   ├── tool.ts             # Main tool implementation
-   ├── info.json          # Tool metadata and examples
-   ├── formatter.browser.tsx    # Browser-specific formatting
-   ├── formatter.console.ts     # Console-specific formatting
-   └── tool.test.ts       # Tool tests
+
+4. **Create Plugin Manifest** (`manifest.json`)
+   ```json
+   {
+     "name": "your-plugin",
+     "version": "1.0.0",
+     "author": "Your Name",
+     "description": "A collection of useful tools for...",
+     "license": "MIT",
+     "tools": ["your-tool.tool", "another-tool.tool"],
+     "datasources": [],
+     "bbVersion": ">=0.9.0"
+   }
    ```
+   See [Plugin Manifest Schema](#plugin-manifest-schema) for complete specification.
 
-4. **Create Tool Metadata**
+5. **Create Tool Metadata** (`your-tool.tool/info.json`)
    ```json
    {
      "name": "your_tool",
      "description": "Detailed description of your tool...",
      "version": "1.0.0",
-     "author": "BB Team",
+     "author": "Your Name",
      "license": "MIT",
      "examples": [
        {
@@ -60,7 +114,7 @@ When creating a new tool:
    }
    ```
 
-5. **Implement Core Components**
+6. **Implement Core Components**
 
    ```typescript
    import LLMTool, {
@@ -105,7 +159,7 @@ When creating a new tool:
    }
    ```
 
-6. **Implement Formatters**
+7. **Implement Formatters**
 
    Browser (formatter.browser.tsx):
    ```typescript
@@ -160,6 +214,166 @@ When creating a new tool:
    }
    ```
 
+## Plugin Manifest Schema
+
+The `manifest.json` file is required at the root of every `.bbplugin` package. It provides metadata about the plugin and lists all included components.
+
+### Schema Definition
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "BB Plugin Manifest",
+  "type": "object",
+  "required": ["name", "version", "description", "tools"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Plugin package name (kebab-case recommended)",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "examples": ["my-plugin", "search-tools"]
+    },
+    "version": {
+      "type": "string",
+      "description": "Semantic version number",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?(\\+[a-zA-Z0-9.-]+)?$",
+      "examples": ["1.0.0", "2.1.0-beta.1"]
+    },
+    "author": {
+      "type": "string",
+      "description": "Plugin creator name or organization",
+      "examples": ["Your Name", "Your Organization"]
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief description of plugin functionality",
+      "minLength": 10,
+      "maxLength": 500
+    },
+    "license": {
+      "type": "string",
+      "description": "License identifier (SPDX format recommended)",
+      "examples": ["MIT", "Apache-2.0", "GPL-3.0"]
+    },
+    "tools": {
+      "type": "array",
+      "description": "List of tool directories included in plugin",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9_-]+\\.tool$",
+        "examples": ["search-tool.tool", "format-tool.tool"]
+      },
+      "minItems": 0
+    },
+    "datasources": {
+      "type": "array",
+      "description": "List of datasource directories included in plugin",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9_-]+\\.datasource$",
+        "examples": ["api-datasource.datasource"]
+      },
+      "minItems": 0,
+      "default": []
+    },
+    "bbVersion": {
+      "type": "string",
+      "description": "Minimum BB version required (semver range)",
+      "examples": [">=0.9.0", "^1.0.0"],
+      "default": ">=0.9.0"
+    },
+    "homepage": {
+      "type": "string",
+      "format": "uri",
+      "description": "Plugin homepage or repository URL"
+    },
+    "repository": {
+      "type": "object",
+      "description": "Repository information",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["git", "svn", "hg"]
+        },
+        "url": {
+          "type": "string",
+          "format": "uri"
+        }
+      }
+    },
+    "keywords": {
+      "type": "array",
+      "description": "Keywords for plugin discovery",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}
+```
+
+### Example Manifests
+
+**Simple Plugin with One Tool:**
+```json
+{
+  "name": "search-plugin",
+  "version": "1.0.0",
+  "author": "John Doe",
+  "description": "Advanced search capabilities for BB",
+  "license": "MIT",
+  "tools": ["search-tool.tool"],
+  "datasources": [],
+  "bbVersion": ">=0.9.0"
+}
+```
+
+**Multi-Tool Plugin:**
+```json
+{
+  "name": "dev-tools",
+  "version": "2.1.0",
+  "author": "Dev Team",
+  "description": "Collection of development utilities",
+  "license": "Apache-2.0",
+  "tools": [
+    "search-tool.tool",
+    "format-tool.tool",
+    "lint-tool.tool"
+  ],
+  "datasources": [],
+  "bbVersion": ">=1.0.0",
+  "homepage": "https://github.com/user/dev-tools",
+  "keywords": ["development", "utilities", "formatting"]
+}
+```
+
+**Plugin with Tools and Datasources:**
+```json
+{
+  "name": "api-integration",
+  "version": "1.5.0",
+  "author": "API Corp",
+  "description": "Tools and datasources for API integration",
+  "license": "MIT",
+  "tools": ["api-query.tool", "api-test.tool"],
+  "datasources": ["rest-api.datasource"],
+  "bbVersion": ">=0.9.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apicorp/bb-api-integration"
+  }
+}
+```
+
+### Validation Requirements
+
+1. **Plugin Name**: Must be kebab-case, lowercase alphanumeric with hyphens
+2. **Version**: Must follow semantic versioning (major.minor.patch)
+3. **Component Lists**: All listed tools/datasources must exist as directories
+4. **Directory Names**: Must match the pattern in manifest exactly
+5. **BB Version**: Should specify minimum compatible version
+
 ## Tool Types and Considerations
 
 ### File Manipulation Tools
@@ -222,33 +436,103 @@ See [TESTING.md](./TESTING.md) for detailed testing guidelines. Key points:
 3. Include usage examples
 4. Document error scenarios
 
+## Plugin Distribution and Installation
+
+### Installation Methods
+
+1. **Double-Click Installation** (macOS/Windows)
+   - Users can double-click `.bbplugin` files
+   - OS file association opens BB DUI
+   - Installation dialog shows plugin details
+   - Plugin copied to configured directory
+   - Requires BB API restart to load
+
+2. **Manual Installation**
+   - Copy `.bbplugin` directory to plugin directory
+   - Default locations:
+     - macOS: `~/.config/bb/plugins`
+     - Windows: `%APPDATA%/bb/plugins`
+     - Linux: `~/.config/bb/plugins`
+   - Custom locations via `config.yaml`:
+     ```yaml
+     api:
+       userPluginDirectories:
+         - ./my-plugins
+         - /absolute/path/to/plugins
+     ```
+
+3. **Plugin Discovery**
+   - BB scans plugin directories on startup
+   - Loads tools from: `plugins/*.bbplugin/*.tool`
+   - Also supports legacy: `plugins/*.tool` (deprecated)
+   - Tools registered with LLM for use
+
+### Version Management
+
+- Plugin versions follow semantic versioning
+- BB detects version conflicts during installation
+- Warns on downgrades or duplicate versions
+- Users can choose to upgrade/replace existing plugins
+
+### Packaging for Distribution
+
+1. **Prepare Package**
+   - Ensure all files are present
+   - Validate manifest.json
+   - Test all tools locally
+   - Include README.md with usage instructions
+
+2. **Distribution Options**
+   - Direct file sharing (`.bbplugin` directory)
+   - Archive formats (`.zip`, `.tar.gz`)
+   - Version control repositories
+   - Future: BB plugin marketplace
+
+3. **Best Practices**
+   - Include comprehensive documentation
+   - Provide usage examples
+   - List dependencies and requirements
+   - Specify BB version compatibility
+   - Include license information
+
 ## Best Practices
 
-1. **Code Organization**
-   - Keep related code together
+1. **Plugin Organization**
+   - Group related tools in a single plugin
+   - Use clear, descriptive plugin names
+   - Keep manifest.json accurate and complete
+   - Version plugins semantically
+   - Document all included components
+
+2. **Code Organization**
+   - Keep related code together within each tool
    - Use clear file structure (tool.ts, info.json, formatters)
-   - Follow naming conventions
-   - Maintain consistent formatting
-
-2. **Implementation**
-   - Follow existing patterns
-   - Keep methods focused
-   - Handle errors gracefully
-   - Clean up resources
-
-3. **Testing**
-   - Write comprehensive tests
-   - Test edge cases
-   - Test error scenarios
-   - Maintain test consistency
-
-4. **Documentation**
-   - Keep docs up to date
-   - Include examples in info.json
-   - Document errors
-   - Explain complex logic
-
-5. **Formatting**
+   - Follow naming conventions (kebab-case for directories)
+   - Maintain consistent formatting across all tools
+   - Separate tool-specific types into types.ts
+
+3. **Implementation**
+   - Follow existing patterns from example tools
+   - Keep methods focused and single-purpose
+   - Handle errors gracefully with clear messages
+   - Clean up resources properly
+   - Consider performance implications
+
+4. **Testing**
+   - Write comprehensive tests for each tool
+   - Test edge cases and boundary conditions
+   - Test error scenarios thoroughly
+   - Maintain test consistency across plugin
+   - Test installation and discovery process
+
+5. **Documentation**
+   - Keep manifest.json and info.json up to date
+   - Include examples in tool info.json files
+   - Document errors and edge cases
+   - Explain complex logic with comments
+   - Provide plugin-level README with overview
+
+6. **Formatting**
    - Use TOOL_TAGS_BROWSER for browser output
    - Use TOOL_STYLES_CONSOLE for console output
    - Use JSX fragments (<>...</>) for browser components
@@ -256,8 +540,70 @@ See [TESTING.md](./TESTING.md) for detailed testing guidelines. Key points:
    - Provide clear labels and structure
    - Handle success and error states consistently
 
+7. **Compatibility**
+   - Specify minimum BB version in manifest
+   - Test with target BB versions
+   - Avoid BB internal APIs unless necessary
+   - Handle version differences gracefully
+   - Document any version-specific features
+
+## Legacy Tool Structure (Deprecated)
+
+**Note**: The standalone `.tool` directory structure is deprecated. While BB still supports it for backward compatibility, all new development should use the `.bbplugin` structure.
+
+### Old Structure (Deprecated)
+```
+plugins/
+├── search-tool.tool/      # Standalone tool (deprecated)
+│   ├── tool.ts
+│   ├── info.json
+│   └── ...
+└── format-tool.tool/      # Another standalone tool (deprecated)
+    ├── tool.ts
+    └── ...
+```
+
+### New Structure (Current)
+```
+plugins/
+├── search-plugin.bbplugin/    # Plugin package (current)
+│   ├── manifest.json
+│   ├── search-tool.tool/
+│   │   ├── tool.ts
+│   │   └── ...
+│   └── format-tool.tool/
+│       ├── tool.ts
+│       └── ...
+└── other-plugin.bbplugin/     # Another plugin
+    ├── manifest.json
+    └── ...
+```
+
+### Migration Notes
+
+**Why Migrate?**
+- Improved organization and discoverability
+- Support for multiple components (tools + datasources)
+- Better version management
+- Enable double-click installation
+- Prepare for plugin marketplace
+- Future: digital signatures and security
+
+**Migration Steps:**
+1. Create new `.bbplugin` directory
+2. Move `.tool` directories into plugin directory
+3. Create `manifest.json` with metadata
+4. Test plugin discovery and loading
+5. Update distribution method
+
+**Backward Compatibility:**
+- BB continues to discover standalone `.tool` directories
+- No immediate migration required
+- Consider migration for new features and better UX
+
 ## See Also
 
 - [README.md](../README.md) - Package overview
 - [TESTING.md](./TESTING.md) - Testing guidelines
 - [tools.md](./tools.md) - Tool reference
+- [Plugin Installation Guide](https://github.com/beyond-better/bb) - BB plugin installation documentation
diff --git a/docs/TESTING.md b/docs/TESTING.md
index d29eefe..c55152a 100644
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -1,7 +1,7 @@
-# Testing Guidelines for BB Tools
+# Testing Guidelines for BB Plugins
 
-This document outlines testing requirements and best practices for the BB tools package. Following
-these guidelines ensures consistent quality and reliability across all tools.
+This document outlines testing requirements and best practices for BB plugins and tools. Following
+these guidelines ensures consistent quality and reliability across all plugin components.
 
 ## Core Principles
 
@@ -10,17 +10,21 @@ these guidelines ensures consistent quality and reliability across all tools.
    - Maintain consistent structure and style
    - Only modify what's necessary for new functionality
 
-2. **Test File Structure**
+2. **Plugin Structure**
    ```
-   your-tool/
-   ├── tool.ts             # Main tool implementation
-   ├── info.json          # Tool metadata and examples
-   ├── formatter.browser.tsx    # Browser-specific formatting
-   ├── formatter.console.ts     # Console-specific formatting
-   └── tool.test.ts       # Tool tests
+   your-plugin.bbplugin/
+   ├── manifest.json          # Plugin metadata
+   └── your-tool.tool/       # Tool directory
+       ├── tool.ts           # Main tool implementation
+       ├── info.json         # Tool metadata and examples
+       ├── formatter.browser.tsx  # Browser-specific formatting
+       ├── formatter.console.ts   # Console-specific formatting
+       └── tool.test.ts      # Tool tests
    ```
 
 3. **Test Coverage Requirements**
+   - Plugin manifest validation
+   - Tool discovery and loading
    - Basic functionality
    - Edge cases
    - Error scenarios
diff --git a/docs/plugin-manifest-schema.json b/docs/plugin-manifest-schema.json
new file mode 100644
index 0000000..a26a89e
--- /dev/null
+++ b/docs/plugin-manifest-schema.json
@@ -0,0 +1,247 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://beyondbetter.dev/schemas/plugin-manifest.json",
+  "title": "BB Plugin Manifest",
+  "description": "Metadata schema for Beyond Better (.bbplugin) plugin packages",
+  "type": "object",
+  "required": ["name", "version", "description", "tools"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Plugin package name (kebab-case recommended)",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "minLength": 1,
+      "maxLength": 100,
+      "examples": [
+        "my-plugin",
+        "search-tools",
+        "dev-utilities"
+      ]
+    },
+    "version": {
+      "type": "string",
+      "description": "Semantic version number (major.minor.patch)",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.-]+)?(\\+[a-zA-Z0-9.-]+)?$",
+      "examples": [
+        "1.0.0",
+        "2.1.0-beta.1",
+        "3.0.0+build.123"
+      ]
+    },
+    "author": {
+      "type": "string",
+      "description": "Plugin creator name or organization",
+      "minLength": 1,
+      "maxLength": 200,
+      "examples": [
+        "John Doe",
+        "Acme Corporation",
+        "Open Source Community"
+      ]
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief description of plugin functionality",
+      "minLength": 10,
+      "maxLength": 500
+    },
+    "license": {
+      "type": "string",
+      "description": "License identifier (SPDX format recommended)",
+      "examples": [
+        "MIT",
+        "Apache-2.0",
+        "GPL-3.0",
+        "BSD-3-Clause",
+        "ISC"
+      ]
+    },
+    "tools": {
+      "type": "array",
+      "description": "List of tool directories included in this plugin",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9_-]+\\.tool$",
+        "examples": [
+          "search-tool.tool",
+          "format-tool.tool",
+          "lint_checker.tool"
+        ]
+      },
+      "minItems": 0,
+      "uniqueItems": true
+    },
+    "datasources": {
+      "type": "array",
+      "description": "List of datasource directories included in this plugin (future support)",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9_-]+\\.datasource$",
+        "examples": [
+          "api-datasource.datasource",
+          "db-connection.datasource"
+        ]
+      },
+      "minItems": 0,
+      "uniqueItems": true,
+      "default": []
+    },
+    "bbVersion": {
+      "type": "string",
+      "description": "Minimum Beyond Better version required (semver range)",
+      "examples": [
+        ">=0.9.0",
+        "^1.0.0",
+        ">=1.2.0 <2.0.0"
+      ],
+      "default": ">=0.9.0"
+    },
+    "homepage": {
+      "type": "string",
+      "format": "uri",
+      "description": "Plugin homepage or documentation URL",
+      "examples": [
+        "https://github.com/user/my-plugin",
+        "https://myplugin.dev"
+      ]
+    },
+    "repository": {
+      "type": "object",
+      "description": "Source code repository information",
+      "required": ["type", "url"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["git", "svn", "hg"],
+          "description": "Version control system type"
+        },
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Repository URL",
+          "examples": [
+            "https://github.com/user/repo.git",
+            "git+ssh://git@github.com/user/repo.git"
+          ]
+        },
+        "directory": {
+          "type": "string",
+          "description": "Directory path within monorepo (if applicable)",
+          "examples": [
+            "packages/my-plugin"
+          ]
+        }
+      }
+    },
+    "keywords": {
+      "type": "array",
+      "description": "Keywords for plugin discovery and search",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 50
+      },
+      "maxItems": 20,
+      "uniqueItems": true,
+      "examples": [
+        ["search", "indexing", "productivity"],
+        ["formatting", "code-style", "linting"],
+        ["api", "integration", "rest"]
+      ]
+    },
+    "bugs": {
+      "type": "object",
+      "description": "Bug tracking information",
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Bug tracker URL"
+        },
+        "email": {
+          "type": "string",
+          "format": "email",
+          "description": "Email address for bug reports"
+        }
+      }
+    },
+    "contributors": {
+      "type": "array",
+      "description": "List of plugin contributors",
+      "items": {
+        "oneOf": [
+          {
+            "type": "string",
+            "description": "Contributor name"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Contributor name"
+              },
+              "email": {
+                "type": "string",
+                "format": "email",
+                "description": "Contributor email"
+              },
+              "url": {
+                "type": "string",
+                "format": "uri",
+                "description": "Contributor website/profile"
+              }
+            },
+            "required": ["name"]
+          }
+        ]
+      }
+    },
+    "funding": {
+      "oneOf": [
+        {
+          "type": "string",
+          "format": "uri",
+          "description": "Funding platform URL"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "type": "string",
+              "description": "Funding platform type",
+              "examples": ["github", "opencollective", "patreon", "ko-fi"]
+            },
+            "url": {
+              "type": "string",
+              "format": "uri",
+              "description": "Funding page URL"
+            }
+          },
+          "required": ["url"]
+        },
+        {
+          "type": "array",
+          "description": "Multiple funding sources",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string",
+                "format": "uri"
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "type": {"type": "string"},
+                  "url": {"type": "string", "format": "uri"}
+                },
+                "required": ["url"]
+              }
+            ]
+          }
+        }
+      ]
+    }
+  },
+  "additionalProperties": false
+}
diff --git a/docs/tools.md b/docs/tools.md
index 03d714a..9dcdc24 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -1,13 +1,24 @@
-# BB Tools Reference
+# BB Plugin Framework Reference
 
-This document provides a comprehensive reference for the BB tools framework, including tool types,
-interfaces, implementation patterns, and styling guidelines.
+This document provides a comprehensive reference for the BB plugin framework, including plugin structure,
+tool types, interfaces, implementation patterns, and styling guidelines.
 
-## Tool Framework Overview
+## Plugin Framework Overview
 
-The BB tools framework provides a structured way to create tools that can be used by AI assistants.
-Each tool:
+The BB plugin framework provides a structured way to create and distribute tools and datasources that can be used by AI assistants.
 
+### Plugin Structure
+
+Plugins are packaged as `.bbplugin` directories containing:
+- **manifest.json**: Required plugin metadata
+- **Tool components**: One or more `.tool` directories
+- **Datasource components**: Optional `.datasource` directories (future support)
+
+**Note**: Standalone `.tool` directories are deprecated but still supported for backward compatibility.
+
+### Tool Components
+
+Each tool within a plugin:
 - Extends the `LLMTool` base class
 - Implements specific interfaces
 - Provides both browser and console formatting

From fce3c430171a5b1bc8b881e6d58a42fef7bd4681 Mon Sep 17 00:00:00 2001
From: Beyond Better <git@beyondbetter.app>
Date: Tue, 4 Nov 2025 20:31:47 +1100
Subject: [PATCH 2/8] Added search-plugin manifest with project search and
 content discovery tools

Applied changes from BB to 1 file

Files modified:
- examples/search-plugin.bbplugin/manifest.json
---
 examples/search-plugin.bbplugin/manifest.json | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 examples/search-plugin.bbplugin/manifest.json

diff --git a/examples/search-plugin.bbplugin/manifest.json b/examples/search-plugin.bbplugin/manifest.json
new file mode 100644
index 0000000..b4c5dcf
--- /dev/null
+++ b/examples/search-plugin.bbplugin/manifest.json
@@ -0,0 +1,11 @@
+{
+  "name": "search-plugin",
+  "version": "1.0.0",
+  "author": "BB Team",
+  "description": "Project search and content discovery tools for Beyond Better",
+  "license": "MIT",
+  "tools": ["search-project.tool"],
+  "datasources": [],
+  "bbVersion": ">=0.9.0",
+  "keywords": ["search", "project", "files", "content"]
+}

From ae7c4f482c380733f31beef7e2824d27fa867b47 Mon Sep 17 00:00:00 2001
From: Beyond Better <git@beyondbetter.app>
Date: Tue, 4 Nov 2025 20:31:59 +1100
Subject: [PATCH 3/8] Added browser-plugin manifest with open-in-browser tool
 for URL and file handling

Applied changes from BB to 1 file

Files modified:
- examples/browser-plugin.bbplugin/manifest.json
---
 examples/browser-plugin.bbplugin/manifest.json | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 examples/browser-plugin.bbplugin/manifest.json

diff --git a/examples/browser-plugin.bbplugin/manifest.json b/examples/browser-plugin.bbplugin/manifest.json
new file mode 100644
index 0000000..b8f30c3
--- /dev/null
+++ b/examples/browser-plugin.bbplugin/manifest.json
@@ -0,0 +1,11 @@
+{
+  "name": "browser-plugin",
+  "version": "1.0.0",
+  "author": "BB Team",
+  "description": "Browser integration tools for opening URLs and files in web browsers",
+  "license": "MIT",
+  "tools": ["open-in-browser.tool"],
+  "datasources": [],
+  "bbVersion": ">=0.9.0",
+  "keywords": ["browser", "url", "open", "web"]
+}

From 3ae4e81bf7a1c20853c7c61deeaab7a9dd88cefa Mon Sep 17 00:00:00 2001
From: Beyond Better <git@beyondbetter.app>
Date: Tue, 4 Nov 2025 20:32:56 +1100
Subject: [PATCH 4/8] Update example module exports

Applied changes from BB to 1 file

Files modified:
- examples/mod.ts
---
 examples/mod.ts | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/examples/mod.ts b/examples/mod.ts
index 03d527f..946fdf2 100644
--- a/examples/mod.ts
+++ b/examples/mod.ts
@@ -1,10 +1,10 @@
 /**
- * Example tools demonstrating BB Tools framework usage.
- * Provides reference implementations of common tool patterns.
+ * Example plugins demonstrating BB Plugin framework usage.
+ * Provides reference implementations of plugin structure and common tool patterns.
  *
- * Available Tools:
- * - SearchProjectTool: Search project files by content and metadata
- * - LLMToolOpenInBrowser: Open URLs and local files in web browsers
+ * Available Plugins:
+ * - search-plugin: Contains SearchProjectTool for searching project files
+ * - browser-plugin: Contains LLMToolOpenInBrowser for opening URLs in browsers
  *
  * @example
  * ```ts
@@ -22,11 +22,14 @@
  * }, projectEditor);
  * ```
  *
+ * Note: Example plugins use the new .bbplugin structure with manifest.json.
+ * Legacy standalone .tool directories are deprecated.
+ *
  * @module
  */
 
-export { default as SearchProjectTool } from './search_project.tool/tool.ts';
-export type { SearchProjectInput } from './search_project.tool/tool.ts';
+export { default as SearchProjectTool } from './search-plugin.bbplugin/search-project.tool/tool.ts';
+export type { SearchProjectInput } from './search-plugin.bbplugin/search-project.tool/tool.ts';
 
-export { default as LLMToolOpenInBrowser } from './open_in_browser.tool/tool.ts';
-export type { LLMToolOpenInBrowserInput } from './open_in_browser.tool/types.ts';
+export { default as LLMToolOpenInBrowser } from './browser-plugin.bbplugin/open-in-browser.tool/tool.ts';
+export type { LLMToolOpenInBrowserInput } from './browser-plugin.bbplugin/open-in-browser.tool/types.ts';

From 01461faa05f1793f475ef385ebc8436ddd996430 Mon Sep 17 00:00:00 2001
From: Beyond Better <git@beyondbetter.app>
Date: Tue, 4 Nov 2025 20:33:29 +1100
Subject: [PATCH 5/8] Updated tool README documentation

Applied changes from BB to 1 file

Files modified:
- examples/search-plugin.bbplugin/search-project.tool/README.md

Updated search project tool README documentation

Applied changes from BB to 1 file

Files modified:
- examples/search-plugin.bbplugin/search-project.tool/README.md

Updated search project tool README documentation

Applied changes from BB to 1 file

Files modified:
- examples/search-plugin.bbplugin/search-project.tool/README.md

Updated search-project tool README with corrected documentation

Applied changes from BB to 1 file

Files modified:
- examples/search-plugin.bbplugin/search-project.tool/README.md
---
 .../search-project.tool/README.md             | 207 ++++++++++++++++++
 1 file changed, 207 insertions(+)
 create mode 100644 examples/search-plugin.bbplugin/search-project.tool/README.md

diff --git a/examples/search-plugin.bbplugin/search-project.tool/README.md b/examples/search-plugin.bbplugin/search-project.tool/README.md
new file mode 100644
index 0000000..353827e
--- /dev/null
+++ b/examples/search-plugin.bbplugin/search-project.tool/README.md
@@ -0,0 +1,207 @@
+# Search Project Tool Example
+
+This example demonstrates how to create a plugin and tool using the BB Plugin framework. It implements a file
+search tool packaged within the `search-plugin.bbplugin` plugin that can search project files by content, name, date, and size.
+
+**Plugin Structure**: This tool is part of the `search-plugin` plugin package, demonstrating the recommended `.bbplugin` structure with manifest.json.
+
+## Overview
+
+The search project tool shows how to:
+
+- Structure a plugin using the `.bbplugin` format
+- Create a manifest.json for plugin metadata
+- Implement the LLMTool base class
+- Use IProjectEditor and IConversationInteraction interfaces
+- Create browser and console formatters
+- Write comprehensive tests
+
+## Implementation
+
+### Plugin Structure
+
+```
+search-plugin.bbplugin/
+├── manifest.json       # Plugin metadata (required)
+└── search-project.tool/
+    ├── tool.ts         # Main tool implementation
+    ├── formatter.browser.tsx # Browser formatting
+    ├── formatter.console.ts  # Console formatting
+    ├── info.json       # Tool metadata
+    ├── tool.test.ts    # Tests
+    └── README.md       # Documentation
+```
+
+### Key Features
+
+1. **Input Schema**
+   - Content pattern (regex)
+   - File pattern (glob)
+   - Date range filtering
+   - Size range filtering
+   - Case sensitivity option
+
+2. **Formatting**
+   - Browser formatting with JSX
+   - Console formatting with ANSI colors
+   - Consistent styling using framework utilities
+
+3. **Testing**
+   - Interface mocking
+   - Input validation
+   - Formatter testing
+   - Error handling
+
+## Usage
+
+```typescript
+import { SearchProjectTool } from '@beyondbetter/tools/examples';
+
+// Create tool instance
+const tool = new SearchProjectTool(
+  'search-project',
+  'Search project files',
+  {},
+  { async: true },
+);
+
+// Use the tool
+const result = await tool.runTool(
+  conversationInteraction,
+  {
+    id: 'tool-use-1',
+    name: 'search-project',
+    toolInput: {
+      filePattern: '*.ts',
+      contentPattern: 'function',
+      caseSensitive: true,
+    },
+  },
+  projectEditor,
+);
+```
+
+## Plugin Installation
+
+```bash
+# Copy plugin to BB plugins directory
+cp -r search-plugin.bbplugin ~/.config/bb/plugins/
+
+# Or double-click search-plugin.bbplugin (macOS/Windows)
+# BB will show installation dialog
+
+# Restart BB API to load the plugin
+```
+
+## Implementation Details
+
+### Input Validation
+
+The tool validates input using JSON Schema:
+
+```typescript
+get inputSchema(): LLMToolInputSchema {
+  return {
+    type: 'object',
+    properties: {
+      contentPattern: {
+        type: 'string',
+        description: '...'
+      },
+      // ... other properties
+    }
+  };
+}
+```
+
+### Formatting
+
+Browser formatting with JSX:
+
+```typescript
+export function formatLogEntryToolUse(
+  toolInput: LLMToolInputSchema,
+): LLMToolLogEntryFormattedResult {
+  // ... format using JSX
+  return {
+    title: tags.content.title('Tool Input', 'search-project'),
+    content: <div>...</div>,
+    preview: 'Preview text',
+  };
+}
+```
+
+Console formatting with ANSI:
+
+```typescript
+export function formatLogEntryToolUse(
+  toolInput: LLMToolInputSchema,
+): LLMToolLogEntryFormattedResult {
+  // ... format using ANSI styles
+  return {
+    title: styles.content.title('Tool Input', 'search-project'),
+    content: '...',
+    preview: 'Preview text',
+  };
+}
+```
+
+### Testing
+
+The example includes tests for:
+
+```typescript
+// Basic functionality
+Deno.test('SearchProjectTool - Basic functionality', async () => {
+  // Test tool execution
+});
+
+// Input validation
+Deno.test('SearchProjectTool - Input validation', () => {
+  // Test schema validation
+});
+
+// Formatting
+Deno.test('SearchProjectTool - Browser formatter', () => {
+  // Test browser output
+});
+
+Deno.test('SearchProjectTool - Console formatter', () => {
+  // Test console output
+});
+```
+
+## Best Practices Demonstrated
+
+1. **Interface Usage**
+   - Uses IProjectEditor for file operations
+   - Uses IConversationInteraction for context
+   - Follows interface contracts strictly
+
+2. **Type Safety**
+   - Strong typing throughout
+   - Proper type exports
+   - Interface compliance
+
+3. **Error Handling**
+   - Input validation
+   - Operation errors
+   - Clear error messages
+
+4. **Testing**
+   - Comprehensive test coverage
+   - Interface mocking
+   - Format testing
+   - Error scenarios
+
+5. **Documentation**
+   - Clear usage examples
+   - Implementation details
+   - Type information
+
+## See Also
+
+- [Plugin Creation Guide](../../../docs/CREATING_TOOLS.md)
+- [Testing Guide](../../../docs/TESTING.md)
+- [Plugin Framework Reference](../../../docs/tools.md)
+- [Plugin Manifest Schema](../../../docs/plugin-manifest-schema.json)

From ab7b63614a0f2fc621accbcdbde029d0af50bb4b Mon Sep 17 00:00:00 2001
From: Charlie Garrison <charlie-github@garrison.com.au>
Date: Sat, 15 Nov 2025 19:30:03 +1100
Subject: [PATCH 6/8] Convert tools to plugins

---
 docs/plugin-manifest-schema.json              |   4 +-
 .../formatter.browser.tsx                     |   0
 .../formatter.console.ts                      |   0
 .../open-in-browser.tool}/info.json           |   0
 .../open-in-browser.tool}/tool.test.ts        |   0
 .../open-in-browser.tool}/tool.ts             |  13 +-
 .../open-in-browser.tool}/types.ts            |   0
 .../formatter.browser.tsx                     |   0
 .../search-project.tool}/formatter.console.ts |   0
 .../search-project.tool}/info.json            |   0
 .../search-project.tool}/tool.test.ts         |   0
 .../search-project.tool}/tool.ts              |   0
 examples/search_project.tool/README.md        | 187 ------------------
 13 files changed, 10 insertions(+), 194 deletions(-)
 rename examples/{open_in_browser.tool => browser-plugin.bbplugin/open-in-browser.tool}/formatter.browser.tsx (100%)
 rename examples/{open_in_browser.tool => browser-plugin.bbplugin/open-in-browser.tool}/formatter.console.ts (100%)
 rename examples/{open_in_browser.tool => browser-plugin.bbplugin/open-in-browser.tool}/info.json (100%)
 rename examples/{open_in_browser.tool => browser-plugin.bbplugin/open-in-browser.tool}/tool.test.ts (100%)
 rename examples/{open_in_browser.tool => browser-plugin.bbplugin/open-in-browser.tool}/tool.ts (93%)
 rename examples/{open_in_browser.tool => browser-plugin.bbplugin/open-in-browser.tool}/types.ts (100%)
 rename examples/{search_project.tool => search-plugin.bbplugin/search-project.tool}/formatter.browser.tsx (100%)
 rename examples/{search_project.tool => search-plugin.bbplugin/search-project.tool}/formatter.console.ts (100%)
 rename examples/{search_project.tool => search-plugin.bbplugin/search-project.tool}/info.json (100%)
 rename examples/{search_project.tool => search-plugin.bbplugin/search-project.tool}/tool.test.ts (100%)
 rename examples/{search_project.tool => search-plugin.bbplugin/search-project.tool}/tool.ts (100%)
 delete mode 100644 examples/search_project.tool/README.md

diff --git a/docs/plugin-manifest-schema.json b/docs/plugin-manifest-schema.json
index a26a89e..4bf1d8b 100644
--- a/docs/plugin-manifest-schema.json
+++ b/docs/plugin-manifest-schema.json
@@ -232,8 +232,8 @@
               {
                 "type": "object",
                 "properties": {
-                  "type": {"type": "string"},
-                  "url": {"type": "string", "format": "uri"}
+                  "type": { "type": "string" },
+                  "url": { "type": "string", "format": "uri" }
                 },
                 "required": ["url"]
               }
diff --git a/examples/open_in_browser.tool/formatter.browser.tsx b/examples/browser-plugin.bbplugin/open-in-browser.tool/formatter.browser.tsx
similarity index 100%
rename from examples/open_in_browser.tool/formatter.browser.tsx
rename to examples/browser-plugin.bbplugin/open-in-browser.tool/formatter.browser.tsx
diff --git a/examples/open_in_browser.tool/formatter.console.ts b/examples/browser-plugin.bbplugin/open-in-browser.tool/formatter.console.ts
similarity index 100%
rename from examples/open_in_browser.tool/formatter.console.ts
rename to examples/browser-plugin.bbplugin/open-in-browser.tool/formatter.console.ts
diff --git a/examples/open_in_browser.tool/info.json b/examples/browser-plugin.bbplugin/open-in-browser.tool/info.json
similarity index 100%
rename from examples/open_in_browser.tool/info.json
rename to examples/browser-plugin.bbplugin/open-in-browser.tool/info.json
diff --git a/examples/open_in_browser.tool/tool.test.ts b/examples/browser-plugin.bbplugin/open-in-browser.tool/tool.test.ts
similarity index 100%
rename from examples/open_in_browser.tool/tool.test.ts
rename to examples/browser-plugin.bbplugin/open-in-browser.tool/tool.test.ts
diff --git a/examples/open_in_browser.tool/tool.ts b/examples/browser-plugin.bbplugin/open-in-browser.tool/tool.ts
similarity index 93%
rename from examples/open_in_browser.tool/tool.ts
rename to examples/browser-plugin.bbplugin/open-in-browser.tool/tool.ts
index eccff03..afedf4f 100644
--- a/examples/open_in_browser.tool/tool.ts
+++ b/examples/browser-plugin.bbplugin/open-in-browser.tool/tool.ts
@@ -33,7 +33,7 @@ import LLMTool, {
   type LLMToolLogEntryFormattedResult,
   type LLMToolRunResult,
 } from 'jsr:@beyondbetter/tools';
-import open, { apps } from 'npm:open@10.1.0';
+import open, { apps } from 'npm:open@10.2.0';
 
 import {
   formatLogEntryToolResult as formatLogEntryToolResultBrowser,
@@ -82,7 +82,7 @@ export default class LLMToolOpenInBrowser extends LLMTool {
    * These map to specific browser applications on the system.
    * @private
    */
-  private readonly predefinedBrowsers = ['chrome', 'firefox', 'edge', 'safari'] as const;
+  private readonly predefinedBrowsers = ['chrome', 'brave', 'firefox', 'edge', 'safari'] as const;
   /**
    * Maximum number of URLs that can be opened in one operation.
    * Limits batch operations to prevent resource exhaustion.
@@ -113,13 +113,14 @@ export default class LLMToolOpenInBrowser extends LLMTool {
           type: 'array',
           items: { type: 'string' },
           description:
-            'Array of URLs or file paths to open. Local paths will be converted to file:// URLs. Maximum of 6 URLs allowed.',
+            `Array of URLs or file paths to open. Local paths will be converted to file:// URLs. Maximum of ${this.maxUrls} URLs allowed.`,
           maxItems: this.maxUrls,
         },
         browser: {
           type: 'string',
-          description:
-            'Browser to use. Can be one of the predefined browsers (chrome, firefox, edge, safari) or any other browser name. If not specified or "default", uses system default browser.',
+          description: `Browser to use. Can be one of the predefined browsers (${
+            this.predefinedBrowsers.join(', ')
+          }) or any other browser name. If not specified or "default", uses system default browser.`,
           default: 'default',
         },
       },
@@ -178,6 +179,8 @@ export default class LLMToolOpenInBrowser extends LLMTool {
         ? apps.browser
         : browser === 'chrome'
         ? apps.chrome
+        : browser === 'brave'
+        ? apps.brave
         : browser === 'firefox'
         ? apps.firefox
         : browser === 'edge'
diff --git a/examples/open_in_browser.tool/types.ts b/examples/browser-plugin.bbplugin/open-in-browser.tool/types.ts
similarity index 100%
rename from examples/open_in_browser.tool/types.ts
rename to examples/browser-plugin.bbplugin/open-in-browser.tool/types.ts
diff --git a/examples/search_project.tool/formatter.browser.tsx b/examples/search-plugin.bbplugin/search-project.tool/formatter.browser.tsx
similarity index 100%
rename from examples/search_project.tool/formatter.browser.tsx
rename to examples/search-plugin.bbplugin/search-project.tool/formatter.browser.tsx
diff --git a/examples/search_project.tool/formatter.console.ts b/examples/search-plugin.bbplugin/search-project.tool/formatter.console.ts
similarity index 100%
rename from examples/search_project.tool/formatter.console.ts
rename to examples/search-plugin.bbplugin/search-project.tool/formatter.console.ts
diff --git a/examples/search_project.tool/info.json b/examples/search-plugin.bbplugin/search-project.tool/info.json
similarity index 100%
rename from examples/search_project.tool/info.json
rename to examples/search-plugin.bbplugin/search-project.tool/info.json
diff --git a/examples/search_project.tool/tool.test.ts b/examples/search-plugin.bbplugin/search-project.tool/tool.test.ts
similarity index 100%
rename from examples/search_project.tool/tool.test.ts
rename to examples/search-plugin.bbplugin/search-project.tool/tool.test.ts
diff --git a/examples/search_project.tool/tool.ts b/examples/search-plugin.bbplugin/search-project.tool/tool.ts
similarity index 100%
rename from examples/search_project.tool/tool.ts
rename to examples/search-plugin.bbplugin/search-project.tool/tool.ts
diff --git a/examples/search_project.tool/README.md b/examples/search_project.tool/README.md
deleted file mode 100644
index 4f79187..0000000
--- a/examples/search_project.tool/README.md
+++ /dev/null
@@ -1,187 +0,0 @@
-# Search Project Tool Example
-
-This example demonstrates how to create a tool using the BB Tools framework. It implements a file
-search tool that can search project files by content, name, date, and size.
-
-## Overview
-
-The search project tool shows how to:
-
-- Implement the LLMTool base class
-- Use IProjectEditor and IConversationInteraction interfaces
-- Create browser and console formatters
-- Write comprehensive tests
-
-## Implementation
-
-### Tool Structure
-
-```
-search_project/
-├── mod.ts              # Main tool implementation
-├── formatter.browser.tsx # Browser formatting
-├── formatter.console.ts  # Console formatting
-├── mod.test.ts        # Tests
-└── README.md          # Documentation
-```
-
-### Key Features
-
-1. **Input Schema**
-   - Content pattern (regex)
-   - File pattern (glob)
-   - Date range filtering
-   - Size range filtering
-   - Case sensitivity option
-
-2. **Formatting**
-   - Browser formatting with JSX
-   - Console formatting with ANSI colors
-   - Consistent styling using framework utilities
-
-3. **Testing**
-   - Interface mocking
-   - Input validation
-   - Formatter testing
-   - Error handling
-
-## Usage
-
-```typescript
-import { SearchProjectTool } from '@beyondbetter/tools/examples/search_project';
-
-// Create tool instance
-const tool = new SearchProjectTool(
-  'search_project',
-  'Search project files',
-  {},
-  { async: true },
-);
-
-// Use the tool
-const result = await tool.runTool(
-  conversationInteraction,
-  {
-    id: 'tool-use-1',
-    name: 'search_project',
-    toolInput: {
-      filePattern: '*.ts',
-      contentPattern: 'function',
-      caseSensitive: true,
-    },
-  },
-  projectEditor,
-);
-```
-
-## Implementation Details
-
-### Input Validation
-
-The tool validates input using JSON Schema:
-
-```typescript
-get inputSchema(): LLMToolInputSchema {
-  return {
-    type: 'object',
-    properties: {
-      contentPattern: {
-        type: 'string',
-        description: '...'
-      },
-      // ... other properties
-    }
-  };
-}
-```
-
-### Formatting
-
-Browser formatting with JSX:
-
-```typescript
-export function formatLogEntryToolUse(
-  toolInput: LLMToolInputSchema,
-): LLMToolLogEntryFormattedResult {
-  // ... format using JSX
-  return {
-    title: tags.content.title('Tool Input', 'search_project'),
-    content: <div>...</div>,
-    preview: 'Preview text',
-  };
-}
-```
-
-Console formatting with ANSI:
-
-```typescript
-export function formatLogEntryToolUse(
-  toolInput: LLMToolInputSchema,
-): LLMToolLogEntryFormattedResult {
-  // ... format using ANSI styles
-  return {
-    title: styles.content.title('Tool Input', 'search_project'),
-    content: '...',
-    preview: 'Preview text',
-  };
-}
-```
-
-### Testing
-
-The example includes tests for:
-
-```typescript
-// Basic functionality
-Deno.test('SearchProjectTool - Basic functionality', async () => {
-  // Test tool execution
-});
-
-// Input validation
-Deno.test('SearchProjectTool - Input validation', () => {
-  // Test schema validation
-});
-
-// Formatting
-Deno.test('SearchProjectTool - Browser formatter', () => {
-  // Test browser output
-});
-
-Deno.test('SearchProjectTool - Console formatter', () => {
-  // Test console output
-});
-```
-
-## Best Practices Demonstrated
-
-1. **Interface Usage**
-   - Uses IProjectEditor for file operations
-   - Uses IConversationInteraction for context
-   - Follows interface contracts strictly
-
-2. **Type Safety**
-   - Strong typing throughout
-   - Proper type exports
-   - Interface compliance
-
-3. **Error Handling**
-   - Input validation
-   - Operation errors
-   - Clear error messages
-
-4. **Testing**
-   - Comprehensive test coverage
-   - Interface mocking
-   - Format testing
-   - Error scenarios
-
-5. **Documentation**
-   - Clear usage examples
-   - Implementation details
-   - Type information
-
-## See Also
-
-- [Tool Creation Guide](../../docs/CREATING_TOOLS.md)
-- [Testing Guide](../../docs/TESTING.md)
-- [Tool Reference](../../docs/tools.md)

From 1896c6758baab8acef757f74340d049939831aaa Mon Sep 17 00:00:00 2001
From: Charlie Garrison <charlie-github@garrison.com.au>
Date: Sat, 15 Nov 2025 19:30:51 +1100
Subject: [PATCH 7/8] Update LLMTool interface and constructor to include
 metadata

---
 deno.lock   | 18 +++++++++++++++++-
 llm_tool.ts | 43 +++++++++++++++++++++++++++++++++++++++++--
 mod.ts      |  1 +
 3 files changed, 59 insertions(+), 3 deletions(-)

diff --git a/deno.lock b/deno.lock
index 882c76e..62f7953 100644
--- a/deno.lock
+++ b/deno.lock
@@ -13,8 +13,9 @@
     "npm:ajv@8.17.1": "8.17.1",
     "npm:common-tags@1.8.2": "1.8.2",
     "npm:node-fetch@3.3.2": "3.3.2",
-    "npm:open@*": "10.1.0",
+    "npm:open@*": "10.2.0",
     "npm:open@10.1.0": "10.1.0",
+    "npm:open@10.2.0": "10.2.0",
     "npm:preact@*": "10.25.3",
     "npm:preact@10.22.0": "10.22.0",
     "npm:preact@10.25.3": "10.25.3"
@@ -154,6 +155,15 @@
         "is-wsl"
       ]
     },
+    "open@10.2.0": {
+      "integrity": "sha512-YgBpdJHPyQ2UE5x+hlSXcnejzAvD0b22U2OuAP+8OnlJT+PjWPxtgmGqKKc+RgTM63U9gN0YzrYc71R2WT/hTA==",
+      "dependencies": [
+        "default-browser",
+        "define-lazy-prop",
+        "is-inside-container",
+        "wsl-utils"
+      ]
+    },
     "preact@10.22.0": {
       "integrity": "sha512-RRurnSjJPj4rp5K6XoP45Ui33ncb7e4H7WiOHVpjbkvqvA3U+N8Z6Qbo0AE6leGYBV66n8EhEaFixvIu3SkxFw=="
     },
@@ -180,6 +190,12 @@
     },
     "web-streams-polyfill@3.3.3": {
       "integrity": "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw=="
+    },
+    "wsl-utils@0.1.0": {
+      "integrity": "sha512-h3Fbisa2nKGPxCpm89Hk33lBLsnaGBvctQopaBSOW/uIs6FTe1ATyAnKFJrzVs9vpGdsTe73WF3V4lIsk4Gacw==",
+      "dependencies": [
+        "is-wsl"
+      ]
     }
   },
   "remote": {
diff --git a/llm_tool.ts b/llm_tool.ts
index 1b883b4..72e254b 100644
--- a/llm_tool.ts
+++ b/llm_tool.ts
@@ -142,6 +142,38 @@ export interface LLMToolLogEntryFormattedResult {
   preview: string | JSX.Element;
 }
 
+export interface LLMToolMetadata {
+  toolId: string;
+  name: string;
+  version: string;
+  protocolType: 'bb' | 'mcp';
+  loadedFrom: 'builtin' | 'plugin' | 'mcp';
+  author: string;
+  license: string;
+  description: string;
+  purpose: string;
+  path?: string; // is set by code, not part of manifest
+  toolSets?: string | string[]; //defaults to 'core'
+  category?: string | string[];
+  capabilities?: string | string[];
+  enabled?: boolean; //defaults to true
+  mutates?: boolean; //defaults to true
+  deprecated?: boolean; //defaults to false
+  replacedBy?: string; //when deprecated is true
+  error?: string;
+  config?: unknown;
+  mcpData?: Record<string, unknown>; //LLMToolMCPConfig
+  pluginData?: {
+    pluginName: string;
+    version: string;
+    author: string;
+    description: string;
+    license: string;
+    bbVersion: string;
+  };
+  examples?: Array<{ description: string; input: unknown }>;
+}
+
 /**
  * Base class for all LLM tools in the BB Tools Framework.
  * Provides core functionality for input validation, execution, and result formatting.
@@ -187,12 +219,19 @@ export interface LLMToolLogEntryFormattedResult {
  * ```
  */
 abstract class LLMTool {
+  public toolId: string;
+  public features: LLMToolFeatures = {};
+
   constructor(
     public name: string,
     public description: string,
     public toolConfig: LLMToolConfig,
-    public features: LLMToolFeatures = {},
-  ) {}
+    public metadata: LLMToolMetadata,
+  ) {
+    this.toolId = metadata.toolId || `${metadata.loadedFrom || 'builtin'}:${metadata.name}`;
+    this.features = { mutates: metadata.mutates || false };
+    //logger.info(`LLMTool: Constructing tool ${name}`);
+  }
 
   // deno-lint-ignore require-await
   public async init(): Promise<LLMTool> {
diff --git a/mod.ts b/mod.ts
index baad904..9f54e45 100644
--- a/mod.ts
+++ b/mod.ts
@@ -105,6 +105,7 @@ export type {
   LLMToolFormatterDestination,
   LLMToolInputSchema,
   LLMToolLogEntryFormattedResult,
+  LLMToolMetadata,
   LLMToolRunBbResponse,
   LLMToolRunBbResponseData,
   LLMToolRunResult,

From a2ea9c5784ee15c68318c8b21f5534c0149ea471 Mon Sep 17 00:00:00 2001
From: Charlie Garrison <charlie-github@garrison.com.au>
Date: Sat, 15 Nov 2025 19:38:46 +1100
Subject: [PATCH 8/8] update exports

---
 deno.jsonc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/deno.jsonc b/deno.jsonc
index d9bfb69..ed4212f 100644
--- a/deno.jsonc
+++ b/deno.jsonc
@@ -6,8 +6,8 @@
     ".": "./mod.ts",
     "./llm-tools": "./llm_tool.ts",
     "./examples": "./examples/mod.ts",
-    "./examples/open_in_browser": "./examples/open_in_browser.tool/tool.ts",
-    "./examples/search_project": "./examples/search_project.tool/tool.ts"
+    "./examples/open-in-browser": "./examples/browser-plugin.bbplugin/open-in-browser.tool/tool.ts",
+    "./examples/search-project": "./examples/search-plugin.bbplugin/search-project.tool/tool.ts"
   },
   "tasks": {
     "publish": "deno publish",