ultravisor-beacon-capability 1.0.0

package/README.md

@@ -0,0 +1,106 @@
+Ultravisor Beacon Capability
+============================
+
+A convention-based base class for building Ultravisor beacon capabilities with minimal boilerplate. Extend the class, define action methods with the `action` prefix, and call `connect()` -- the module handles beacon registration, transport, and lifecycle automatically.
+
+## Features
+
+- **Convention Over Configuration** -- Define actions as methods prefixed with `action`; schemas and descriptions as companion getters
+- **Automatic Discovery** -- Actions are discovered by walking the prototype chain, including multi-level inheritance
+- **Simplified Handler Signature** -- Settings are pre-extracted from work items so handlers receive `(pSettings, pWorkItem, fCallback, fReportProgress)`
+- **Lifecycle Hooks** -- Override `onInitialize()` and `onShutdown()` for setup and teardown (database connections, service handles, etc.)
+- **Explicit Registration Escape Hatch** -- Use `addAction()` for dynamic or runtime-generated actions alongside convention-based ones
+- **Fable Ecosystem Integration** -- Extends `fable-serviceproviderbase`; composes `ultravisor-beacon` internally
+
+## Documentation
+
+Comprehensive documentation is available in the [docs](./docs) folder:
+
+- [Overview](./docs/README.md) -- Introduction and getting started
+- [Quick Start](./docs/quickstart.md) -- Step-by-step setup guide
+- [Architecture](./docs/architecture.md) -- System design and mermaid diagrams
+- [API Reference](./docs/api/README.md) -- All classes and methods
+- [Examples](./docs/examples/README.md) -- Real-world usage patterns
+
+## Install
+
+```sh
+$ npm install ultravisor-beacon-capability
+```
+
+## Quick Start
+
+```javascript
+const libFable = require('fable');
+const libBeaconCapability = require('ultravisor-beacon-capability');
+
+class DiskCleanup extends libBeaconCapability
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+		this.serviceType = 'DiskCleanup';
+		this.capabilityName = 'DiskCleanup';
+	}
+
+	get actionPurgeTempFiles_Description()
+	{
+		return 'Remove temporary files older than N days';
+	}
+
+	get actionPurgeTempFiles_Schema()
+	{
+		return [
+			{ Name: 'Directory', DataType: 'String', Required: true },
+			{ Name: 'MaxAgeDays', DataType: 'Integer', Required: true },
+			{ Name: 'DryRun', DataType: 'Boolean', Required: false }
+		];
+	}
+
+	actionPurgeTempFiles(pSettings, pWorkItem, fCallback)
+	{
+		let tmpCmd = `find ${pSettings.Directory} -type f -mtime +${pSettings.MaxAgeDays}`;
+		if (!pSettings.DryRun)
+		{
+			tmpCmd += ' -delete';
+		}
+		require('child_process').exec(tmpCmd, (pError, pStdOut) =>
+		{
+			if (pError) return fCallback(pError);
+			return fCallback(null, { Outputs: { Result: pStdOut, DryRun: !!pSettings.DryRun } });
+		});
+	}
+}
+
+let tmpFable = new libFable({ Product: 'DiskCleanup', ProductVersion: '1.0.0' });
+tmpFable.addServiceType('DiskCleanup', DiskCleanup);
+let tmpCleanup = tmpFable.instantiateServiceProvider('DiskCleanup');
+
+tmpCleanup.connect(
+	{
+		ServerURL: 'http://ultravisor.local:54321',
+		Name: 'disk-cleanup-worker'
+	},
+	(pError, pBeaconInfo) =>
+	{
+		if (pError) throw pError;
+		console.log('Beacon online:', pBeaconInfo.BeaconID);
+	});
+```
+
+Once connected, the Ultravisor server automatically creates a task type `beacon-diskcleanup-purgetempfiles` that can be triggered manually, scheduled, or wired into operation graphs.
+
+## Related Packages
+
+- [ultravisor-beacon](https://github.com/stevenvelozo/ultravisor-beacon) -- Underlying beacon client and Fable service
+- [ultravisor](https://github.com/stevenvelozo/ultravisor) -- Process supervision and orchestration server
+- [fable](https://github.com/stevenvelozo/fable) -- Service dependency injection framework
+- [fable-serviceproviderbase](https://github.com/stevenvelozo/fable-serviceproviderbase) -- Service provider base class
+
+## License
+
+MIT
+
+## Contributing
+
+Pull requests are welcome. For details on our code of conduct, contribution process, and testing requirements, see the [Retold Contributing Guide](https://github.com/stevenvelozo/retold/blob/main/docs/contributing.md).

package/docs/README.md

@@ -0,0 +1,103 @@
+# Ultravisor Beacon Capability
+
+> Convention-based base class for building Ultravisor beacon capabilities
+
+Ultravisor Beacon Capability eliminates the boilerplate of wiring up an Ultravisor beacon. Instead of manually creating a beacon service, building capability descriptors, and managing the connection lifecycle, you extend a single base class, write action methods, and call `connect()`. The module discovers your actions by convention, builds the capability descriptor, registers with the Ultravisor server, and manages the full beacon lifecycle.
+
+The Ultravisor server automatically creates task types (cards) for each action your capability exposes. These can be triggered on demand, scheduled for recurring execution, or composed into multi-step operation graphs -- turning ad-hoc scripts into managed, observable automation.
+
+## Features
+
+- **Convention Over Configuration** -- Define actions as methods prefixed with `action`; schemas and descriptions as companion getters
+- **Automatic Discovery** -- Actions are discovered by walking the prototype chain, including multi-level inheritance
+- **Simplified Handler Signature** -- Settings are pre-extracted from work items so handlers receive `(pSettings, pWorkItem, fCallback, fReportProgress)`
+- **Lifecycle Hooks** -- Override `onInitialize()` and `onShutdown()` for setup and teardown (database connections, service handles, etc.)
+- **Explicit Registration Escape Hatch** -- Use `addAction()` for dynamic or runtime-generated actions alongside convention-based ones
+- **Fable Ecosystem Integration** -- Extends `fable-serviceproviderbase`; composes `ultravisor-beacon` internally
+
+## Quick Start
+
+```javascript
+const libFable = require('fable');
+const libBeaconCapability = require('ultravisor-beacon-capability');
+
+class HealthCheck extends libBeaconCapability
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+		this.serviceType = 'HealthCheck';
+		this.capabilityName = 'HealthCheck';
+	}
+
+	get actionCheckDiskSpace_Description()
+	{
+		return 'Report available disk space on the host';
+	}
+
+	actionCheckDiskSpace(pSettings, pWorkItem, fCallback)
+	{
+		require('child_process').exec('df -h', (pError, pStdOut) =>
+		{
+			if (pError) return fCallback(pError);
+			return fCallback(null, { Outputs: { DiskUsage: pStdOut } });
+		});
+	}
+}
+
+let tmpFable = new libFable({ Product: 'HealthCheck' });
+tmpFable.addServiceType('HealthCheck', HealthCheck);
+let tmpCheck = tmpFable.instantiateServiceProvider('HealthCheck');
+
+tmpCheck.connect({ ServerURL: 'http://ultravisor.local:54321' }, (pError) =>
+{
+	if (pError) throw pError;
+	console.log('Health check beacon online');
+});
+```
+
+## Installation
+
+```bash
+npm install ultravisor-beacon-capability
+```
+
+## Core Concepts
+
+### The Action Convention
+
+Actions are discovered by method name prefix. An action named `PurgeRecords` is defined by up to three members on your class:
+
+| Member | Required | Purpose |
+|--------|----------|---------|
+| `actionPurgeRecords(pSettings, pWorkItem, fCallback, fReportProgress)` | Yes | The handler function |
+| `get actionPurgeRecords_Schema()` | No | Returns a `SettingsSchema` array describing input parameters |
+| `get actionPurgeRecords_Description()` | No | Returns a human-readable description string |
+
+The handler receives `pSettings` pre-extracted from `pWorkItem.Settings` (defaulting to `{}` if absent), eliminating the universal boilerplate of `let tmpSettings = pWorkItem.Settings || {};`.
+
+### Server-Side Integration
+
+When a beacon registers capabilities, the Ultravisor server's coordinator automatically creates task types for each `Capability:Action` pair. The task type hash follows the format `beacon-{capability}-{action}` (e.g. `beacon-healthcheck-checkdiskspace`). These task types appear as cards in the Ultravisor UI and can be:
+
+- **Triggered manually** from the Ultravisor dashboard
+- **Scheduled** for recurring execution
+- **Composed** into operation graphs with other task types
+
+### Before and After
+
+Without this module, registering a single capability requires approximately 60 lines of framework code (service type registration, beacon instantiation, descriptor building, lifecycle management). With this module, the same result requires approximately 5 lines of framework code -- one class declaration, one `capabilityName` assignment, and one `connect()` call.
+
+## Documentation
+
+- [Quick Start](quickstart.md) -- Step-by-step setup
+- [Architecture](architecture.md) -- System design with diagrams
+- [API Reference](api/README.md) -- Complete class and method reference
+- [Examples](examples/README.md) -- Real-world usage patterns
+
+## Related Packages
+
+- [ultravisor-beacon](https://github.com/stevenvelozo/ultravisor-beacon) -- Underlying beacon client and Fable service
+- [ultravisor](https://github.com/stevenvelozo/ultravisor) -- Process supervision and orchestration server
+- [fable](https://github.com/stevenvelozo/fable) -- Service dependency injection framework
+- [fable-serviceproviderbase](https://github.com/stevenvelozo/fable-serviceproviderbase) -- Service provider base class

package/docs/_brand.json

@@ -0,0 +1,18 @@
+{
+	"Hash": "ultravisor-beacon-capability",
+	"Name": "Ultravisor Beacon Capability",
+	"Tagline": "Convention-based base class for building Ultravisor beacon capabilities with minimal boilerplate",
+	"Palette": "mix",
+	"Icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\">\n\t\t<defs>\n\t\t\t<clipPath id=\"frame-ultravisor-beacon-capability-filled-light\">\n\t\t\t\t<path d=\"M 24 2\n\t\tH 72\n\t\tQ 94 2 94 24\n\t\tV 72\n\t\tQ 94 94 72 94\n\t\tH 24\n\t\tQ 2 94 2 72\n\t\tV 24\n\t\tQ 2 2 24 2 Z\"/>\n\t\t\t</clipPath>\n\t\t</defs>\n\t\t<path d=\"M 24 2\n\t\tH 72\n\t\tQ 94 2 94 24\n\t\tV 72\n\t\tQ 94 94 72 94\n\t\tH 24\n\t\tQ 2 94 2 72\n\t\tV 24\n\t\tQ 2 2 24 2 Z\" fill=\"#1dc3df\"/>\n\t\t<g clip-path=\"url(#frame-ultravisor-beacon-capability-filled-light)\"><rect x=\"20\" y=\"20\" width=\"56\" height=\"56\" rx=\"8\" fill=\"rgba(255,255,255,0.18)\"/>\n\t\t\t\t\t<path d=\"M 48 30 L 70 48 L 48 66 L 26 48 Z\" fill=\"#f043d4\"/></g>\n\t\t<text x=\"48\" y=\"50\" text-anchor=\"middle\" dominant-baseline=\"central\"\n\t\t\tfont-family=\"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\"\n\t\t\tfont-size=\"28\" font-weight=\"600\"\n\t\t\tfill=\"#ffffff\" letter-spacing=\"-1\">UBC</text>\n\t</svg>",
+	"IconType": "svg",
+	"Favicon": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\">\n\t\t<defs>\n\t\t\t<clipPath id=\"fav-ultravisor-beacon-capability-light\">\n\t\t\t\t<path d=\"M 24 2\n\t\tH 72\n\t\tQ 94 2 94 24\n\t\tV 72\n\t\tQ 94 94 72 94\n\t\tH 24\n\t\tQ 2 94 2 72\n\t\tV 24\n\t\tQ 2 2 24 2 Z\"/>\n\t\t\t</clipPath>\n\t\t</defs>\n\t\t<path d=\"M 24 2\n\t\tH 72\n\t\tQ 94 2 94 24\n\t\tV 72\n\t\tQ 94 94 72 94\n\t\tH 24\n\t\tQ 2 94 2 72\n\t\tV 24\n\t\tQ 2 2 24 2 Z\" fill=\"#1dc3df\"/>\n\t\t<g clip-path=\"url(#fav-ultravisor-beacon-capability-light)\"><rect x=\"16\" y=\"16\" width=\"64\" height=\"64\" rx=\"10\" fill=\"rgba(255,255,255,0.22)\"/></g>\n\t\t<text x=\"48\" y=\"50\" text-anchor=\"middle\" dominant-baseline=\"central\"\n\t\t\tfont-family=\"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\"\n\t\t\tfont-size=\"60\" font-weight=\"800\"\n\t\t\tfill=\"#ffffff\" letter-spacing=\"-1\">U</text>\n\t</svg>",
+	"FaviconDark": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 96 96\" width=\"96\" height=\"96\">\n\t\t<defs>\n\t\t\t<clipPath id=\"fav-ultravisor-beacon-capability-dark\">\n\t\t\t\t<path d=\"M 24 2\n\t\tH 72\n\t\tQ 94 2 94 24\n\t\tV 72\n\t\tQ 94 94 72 94\n\t\tH 24\n\t\tQ 2 94 2 72\n\t\tV 24\n\t\tQ 2 2 24 2 Z\"/>\n\t\t\t</clipPath>\n\t\t</defs>\n\t\t<path d=\"M 24 2\n\t\tH 72\n\t\tQ 94 2 94 24\n\t\tV 72\n\t\tQ 94 94 72 94\n\t\tH 24\n\t\tQ 2 94 2 72\n\t\tV 24\n\t\tQ 2 2 24 2 Z\" fill=\"#71d6e7\"/>\n\t\t<g clip-path=\"url(#fav-ultravisor-beacon-capability-dark)\"><rect x=\"16\" y=\"16\" width=\"64\" height=\"64\" rx=\"10\" fill=\"rgba(255,255,255,0.22)\"/></g>\n\t\t<text x=\"48\" y=\"50\" text-anchor=\"middle\" dominant-baseline=\"central\"\n\t\t\tfont-family=\"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\"\n\t\t\tfont-size=\"60\" font-weight=\"800\"\n\t\t\tfill=\"#101418\" letter-spacing=\"-1\">U</text>\n\t</svg>",
+	"Colors": {
+		"Primary": "#1dc3df",
+		"Secondary": "#f043d4",
+		"PrimaryLight": "#1dc3df",
+		"PrimaryDark": "#71d6e7",
+		"SecondaryLight": "#f043d4",
+		"SecondaryDark": "#f49ce5"
+	}
+}

package/docs/_cover.md

@@ -0,0 +1,13 @@
+# Ultravisor Beacon Capability
+
+> Convention-based base class for building Ultravisor beacon capabilities
+
+- Define actions as methods with the `action` prefix
+- Automatic discovery via prototype chain walking
+- Simplified handler signature with pre-extracted settings
+- Full Fable ecosystem integration
+
+[Get Started](quickstart.md)
+[API Reference](api/README.md)
+[Examples](examples/README.md)
+[GitHub](https://github.com/stevenvelozo/ultravisor-beacon-capability)

package/docs/_sidebar.md

@@ -0,0 +1,31 @@
+- Getting Started
+
+  - [Introduction](/)
+  - [Quick Start](quickstart.md)
+  - [Architecture](architecture.md)
+
+- API Reference
+
+  - [Overview](api/README.md)
+  - [UltravisorBeaconCapability](api/beacon-capability.md)
+  - [Action Convention](api/action-convention.md)
+  - [buildActionMap](api/build-action-map.md)
+  - [connect](api/connect.md)
+  - [disconnect](api/disconnect.md)
+  - [addAction](api/add-action.md)
+  - [onInitialize / onShutdown](api/lifecycle-hooks.md)
+  - [isConnected](api/is-connected.md)
+
+- Examples
+
+  - [Overview](examples/README.md)
+  - [Shell Commands](examples/shell-commands.md)
+  - [MySQL Maintenance](examples/mysql-maintenance.md)
+  - [PostgreSQL Aggregation](examples/postgresql-aggregation.md)
+  - [REST API Health Check](examples/rest-api-health-check.md)
+  - [REST Endpoint Sync](examples/rest-endpoint-sync.md)
+  - [Log File Cleanup](examples/log-file-cleanup.md)
+  - [Log Archive and Upload](examples/log-archive-and-upload.md)
+  - [Server Metrics Collection](examples/server-metrics-collection.md)
+  - [Certificate Expiry Monitor](examples/certificate-expiry-monitor.md)
+  - [Docker Container Management](examples/docker-container-management.md)

package/docs/_topbar.md

@@ -0,0 +1,5 @@
+[Home](/)
+[Quick Start](quickstart.md)
+[API Reference](api/README.md)
+[Examples](examples/README.md)
+[GitHub](https://github.com/stevenvelozo/ultravisor-beacon-capability)

package/docs/_version.json

@@ -0,0 +1,7 @@
+{
+	"Name": "ultravisor-beacon-capability",
+	"Version": "0.0.1",
+	"Description": "Convention-based base class for building Ultravisor beacon capabilities with minimal boilerplate",
+	"GeneratedAt": "2026-04-10T17:19:46.865Z",
+	"GitCommit": "e8589f3"
+}

package/docs/api/README.md

@@ -0,0 +1,44 @@
+# API Reference
+
+> Complete reference for ultravisor-beacon-capability
+
+## Module Export
+
+```javascript
+const libBeaconCapability = require('ultravisor-beacon-capability');
+```
+
+The module exports `UltravisorBeaconCapability`, a class that extends `fable-serviceproviderbase`. You extend this class to define your capability.
+
+## Classes
+
+| Class | Description |
+|-------|-------------|
+| [UltravisorBeaconCapability](beacon-capability.md) | Base class -- extend to define capabilities with action methods |
+
+## Convention
+
+| Reference | Description |
+|-----------|-------------|
+| [Action Convention](action-convention.md) | How actions are discovered via the `action` prefix |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| [connect()](connect.md) | Connect to an Ultravisor server, register actions, begin accepting work |
+| [disconnect()](disconnect.md) | Disconnect from the Ultravisor server |
+| [addAction()](add-action.md) | Explicitly register an action (escape hatch for dynamic actions) |
+| [isConnected()](is-connected.md) | Check whether the beacon is currently connected |
+
+## Lifecycle Hooks
+
+| Hook | Description |
+|------|-------------|
+| [onInitialize() / onShutdown()](lifecycle-hooks.md) | Setup and teardown hooks for resource management |
+
+## Internal
+
+| Function | Description |
+|----------|-------------|
+| [buildActionMap()](build-action-map.md) | Discovers action methods on a capability instance's prototype chain |

package/docs/api/action-convention.md

@@ -0,0 +1,148 @@
+# Action Convention
+
+Actions are discovered automatically by examining method names on your class. Any method starting with `action` (and longer than just the word "action") is treated as an action handler. Companion getters provide metadata.
+
+## Defining an Action
+
+An action named `DoSomething` consists of up to three members:
+
+### Handler (required)
+
+```javascript
+actionDoSomething(pSettings, pWorkItem, fCallback, fReportProgress)
+{
+	// pSettings -- pre-extracted from pWorkItem.Settings (defaults to {} if missing)
+	// pWorkItem -- the full work item object from Ultravisor
+	// fCallback -- function(pError, pResult) where pResult = { Outputs: {...}, Log: [...] }
+	// fReportProgress -- optional function({ Percent, Message, Step, TotalSteps })
+
+	return fCallback(null, { Outputs: { Result: 'done' } });
+}
+```
+
+### Schema (optional)
+
+```javascript
+get actionDoSomething_Schema()
+{
+	return [
+		{ Name: 'InputFile', DataType: 'String', Required: true },
+		{ Name: 'OutputFormat', DataType: 'String', Required: false },
+		{ Name: 'MaxRows', DataType: 'Integer', Required: false }
+	];
+}
+```
+
+The schema is an array of field definitions. Each field has:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Name` | `string` | Parameter name |
+| `DataType` | `string` | Type: `String`, `Integer`, `Boolean`, `Object`, `Array`, `DateTime` |
+| `Required` | `boolean` | Whether the parameter is required |
+| `Default` | `any` | Optional default value |
+| `Description` | `string` | Optional human-readable description |
+
+### Description (optional)
+
+```javascript
+get actionDoSomething_Description()
+{
+	return 'Process an input file and produce output in the specified format';
+}
+```
+
+## Handler Signature
+
+The convention handler signature differs from the raw `ultravisor-beacon` handler:
+
+| Parameter | Convention | Raw beacon |
+|-----------|-----------|------------|
+| 1st | `pSettings` (pre-extracted) | `pWorkItem` |
+| 2nd | `pWorkItem` (full object) | `pContext` |
+| 3rd | `fCallback` | `fCallback` |
+| 4th | `fReportProgress` | `fReportProgress` |
+
+The base class wraps your method so that `ultravisor-beacon` receives the raw signature it expects.
+
+## Result Format
+
+The callback expects:
+
+```javascript
+// Success
+fCallback(null, {
+	Outputs: { Key: 'value', AnotherKey: 123 },
+	Log: ['Step 1 complete', 'Step 2 complete']
+});
+
+// Error
+fCallback(new Error('Something went wrong'));
+```
+
+- `Outputs` -- key-value pairs available as task state outputs on the Ultravisor server
+- `Log` -- array of log strings recorded with the work item result
+
+## Progress Reporting
+
+For long-running actions, use `fReportProgress`:
+
+```javascript
+actionLongTask(pSettings, pWorkItem, fCallback, fReportProgress)
+{
+	fReportProgress({ Percent: 0, Message: 'Starting...', Step: 1, TotalSteps: 3 });
+
+	// ... do step 1 ...
+
+	fReportProgress({ Percent: 33, Message: 'Step 1 complete', Step: 2, TotalSteps: 3 });
+
+	// ... do step 2 ...
+
+	fReportProgress({ Percent: 66, Message: 'Step 2 complete', Step: 3, TotalSteps: 3 });
+
+	// ... do step 3 ...
+
+	return fCallback(null, { Outputs: { Result: 'all done' } });
+}
+```
+
+## Discovery Rules
+
+1. Method name must start with `action` and be longer than 6 characters
+2. Methods ending with `_Schema` or `_Description` are companions, not actions
+3. Only actual functions are considered (not getters or plain properties)
+4. The prototype chain is walked from the derived class up to (but not including) `Object.prototype`
+5. If a method name appears on both a derived and base class, the derived version wins
+6. Missing `_Schema` defaults to `[]`; missing `_Description` defaults to `''`
+
+## `this` Context
+
+Action methods are bound to the capability instance. You have full access to:
+
+```javascript
+actionQuery(pSettings, pWorkItem, fCallback)
+{
+	// Access Fable services
+	this.fable.services.SomeService.doWork();
+
+	// Access the logger
+	this.log.info('Processing query...');
+
+	// Access instance state set in onInitialize
+	this._DatabaseConnection.query(pSettings.SQL, (pError, pRows) =>
+	{
+		if (pError) return fCallback(pError);
+		return fCallback(null, { Outputs: { Rows: pRows } });
+	});
+}
+```
+
+## Naming Conventions
+
+The action name is derived by stripping the `action` prefix. The casing is preserved:
+
+| Method Name | Action Name | Task Type Hash |
+|-------------|-------------|----------------|
+| `actionPurgeRecords` | `PurgeRecords` | `beacon-{cap}-purgerecords` |
+| `actionRunBackup` | `RunBackup` | `beacon-{cap}-runbackup` |
+| `actionSyncData` | `SyncData` | `beacon-{cap}-syncdata` |

package/docs/api/add-action.md

@@ -0,0 +1,68 @@
+# addAction()
+
+Explicitly register an action. Use this as an escape hatch for actions that cannot be expressed via the convention (e.g. dynamically generated actions, actions loaded from configuration, or actions with closures over external state).
+
+## Signature
+
+```javascript
+addAction(pName, pDefinition)
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pName` | `string` | Action name (e.g. `'ProcessData'`) |
+| `pDefinition` | `object` | Action definition (see below) |
+
+### Definition
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `Handler` | `function` | Yes | `function(pWorkItem, pContext, fCallback, fReportProgress)` -- uses the **raw** beacon handler signature |
+| `Description` | `string` | No | Human-readable description |
+| `SettingsSchema` | `array` | No | Array of field definitions |
+
+**Important:** The `Handler` uses the raw `ultravisor-beacon` signature, not the simplified convention signature. This means `pWorkItem` is the first parameter (not `pSettings`).
+
+## Behavior
+
+- Stores the action in an internal map
+- Explicit actions are merged with convention-discovered actions when `connect()` is called
+- If an explicit action has the same name as a convention-discovered action, the explicit one wins
+- Validation: rejects calls with missing/empty `pName` or missing `Handler` function
+
+## Example
+
+```javascript
+let tmpFable = new libFable({});
+let tmpCap = new MyCapability(tmpFable, {}, 'cap');
+
+// Register a dynamic action
+tmpCap.addAction('ImportCSV',
+	{
+		Description: 'Import data from a CSV file',
+		SettingsSchema: [
+			{ Name: 'FilePath', DataType: 'String', Required: true },
+			{ Name: 'Delimiter', DataType: 'String', Required: false }
+		],
+		Handler: function (pWorkItem, pContext, fCallback)
+		{
+			let tmpSettings = pWorkItem.Settings || {};
+			// ... process CSV ...
+			return fCallback(null, { Outputs: { RowsImported: 42 } });
+		}
+	});
+
+tmpCap.connect({ ServerURL: 'http://ultravisor:54321' }, (pError) => { });
+```
+
+## When to Use
+
+| Scenario | Use Convention | Use addAction |
+|----------|---------------|---------------|
+| Standard action with known schema | Yes | -- |
+| Action generated from config at runtime | -- | Yes |
+| Action wrapping an external library callback | Either | Yes (simpler) |
+| Action that needs the raw `pContext` parameter | -- | Yes |
+| Multiple capabilities sharing a common action | -- | Yes |

package/docs/api/beacon-capability.md

@@ -0,0 +1,89 @@
+# UltravisorBeaconCapability
+
+The base class for all convention-based beacon capabilities. Extend this class, set `capabilityName`, define action methods with the `action` prefix, and call `connect()`.
+
+## Import
+
+```javascript
+const libBeaconCapability = require('ultravisor-beacon-capability');
+```
+
+## Constructor
+
+```javascript
+class MyCapability extends libBeaconCapability
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+		this.serviceType = 'MyCapability';
+		this.capabilityName = 'MyCapability';
+		this.providerName = 'MyCapabilityProvider'; // optional
+	}
+}
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pFable` | `Fable` | Fable instance (provided by the framework) |
+| `pOptions` | `object` | Service options (provided by the framework) |
+| `pServiceHash` | `string` | Service hash identifier (provided by the framework) |
+
+### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `capabilityName` | `string` | `''` | **Required.** The capability name registered with Ultravisor. Must be set before calling `connect()`. |
+| `providerName` | `string` | `''` | Optional display name. Defaults to `{capabilityName}Provider` if not set. |
+| `serviceType` | `string` | `'UltravisorBeaconCapability'` | Fable service type identifier. Set to your class name. |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| [`connect(pBeaconConfig, fCallback)`](connect.md) | Connect to Ultravisor server |
+| [`disconnect(fCallback)`](disconnect.md) | Disconnect from Ultravisor server |
+| [`addAction(pName, pDefinition)`](add-action.md) | Register an explicit action |
+| [`isConnected()`](is-connected.md) | Check connection status |
+
+## Lifecycle Hooks
+
+| Hook | Description |
+|------|-------------|
+| [`onInitialize(fCallback)`](lifecycle-hooks.md) | Called after beacon connects, before polling |
+| [`onShutdown(fCallback)`](lifecycle-hooks.md) | Called when beacon disconnects |
+
+## Usage with Fable
+
+```javascript
+const libFable = require('fable');
+
+let tmpFable = new libFable({ Product: 'MyApp' });
+
+// Register the service type
+tmpFable.addServiceType('MyCapability', MyCapability);
+
+// Instantiate
+let tmpCap = tmpFable.instantiateServiceProvider('MyCapability');
+
+// Connect
+tmpCap.connect({ ServerURL: 'http://ultravisor:54321' }, (pError) =>
+{
+	if (pError) throw pError;
+	console.log('Connected');
+});
+```
+
+## Inheritance
+
+`UltravisorBeaconCapability` extends `fable-serviceproviderbase`, which means your capability instance has access to all standard Fable service features:
+
+- `this.fable` -- the Fable instance
+- `this.log` -- the Fable logger (`this.log.info()`, `this.log.error()`, etc.)
+- `this.options` -- the service options
+- `this.fable.settings` -- application settings
+- `this.fable.services` -- other registered services
+
+Multi-level inheritance is supported. Actions defined on base classes are discovered alongside those on derived classes, with derived classes taking precedence on name collision.