@troykelly/openclaw-projects 0.0.1 → 0.0.5

package/README.md

@@ -1,375 +1,508 @@
 # @troykelly/openclaw-projects
 
-An [OpenClaw](https://docs.openclaw.ai/) plugin that connects agents to the openclaw-projects backend for project management, memory, todos, and contacts.
+An [OpenClaw](https://docs.openclaw.ai/) plugin that connects agents to the openclaw-projects backend for project management, memory, todos, contacts, and communications.
 
 > **Note:** This is a third-party plugin — not part of OpenClaw itself. It provides OpenClaw agents with tools to interact with the [openclaw-projects](https://github.com/troykelly/openclaw-projects) backend service.
 
+## Quickstart
+
+Get from zero to a working plugin in under 5 minutes.
+
+### 1. Deploy the backend
+
+Clone the repository and run the setup wizard:
+
+```bash
+git clone https://github.com/troykelly/openclaw-projects.git
+cd openclaw-projects
+./scripts/setup.sh
+```
+
+The setup script generates a `.env` file with random secrets and sensible defaults. For CI or unattended setup, use `./scripts/setup.sh --non-interactive`.
+
+### 2. Start services
+
+```bash
+docker compose -f docker-compose.quickstart.yml up -d
+```
+
+Wait for all services to become healthy (this may take 30-60 seconds on first run):
+
+```bash
+docker compose -f docker-compose.quickstart.yml ps
+```
+
+Expected output:
+
+```
+NAME                  STATUS
+openclaw-qs-db        running (healthy)
+openclaw-qs-seaweedfs running (healthy)
+openclaw-qs-migrate   exited (0)
+openclaw-qs-api       running (healthy)
+```
+
+### 3. Verify the API is running
+
+```bash
+curl http://localhost:3000/health
+```
+
+Expected output:
+
+```json
+{"status":"ok"}
+```
+
+### 4. Install the plugin
+
+```bash
+openclaw plugins install @troykelly/openclaw-projects
+```
+
+### 5. Configure the plugin
+
+Add to your OpenClaw config (`~/.openclaw/config.yaml`):
+
+```yaml
+plugins:
+  entries:
+    openclaw-projects:
+      enabled: true
+      config:
+        apiUrl: http://localhost:3000
+```
+
+The quickstart compose disables authentication by default, so no `apiKey` is needed. When you later switch to a production compose file with auth enabled, add `apiKey` with the `OPENCLAW_PROJECTS_AUTH_SECRET` value from your `.env` file. See [Configuration](#configuration) for details.
+
+### 6. Verify the connection
+
+```bash
+openclaw openclaw-projects status
+```
+
+Expected output when healthy:
+
+```
+openclaw-projects status:
+  API URL:    http://localhost:3000
+  Status:     healthy
+  Auth:       valid
+  Latency:    12ms
+```
+
+If the status shows unhealthy, see [Troubleshooting](#troubleshooting) below.
+
+### Next steps
+
+- See [Configuration](#configuration) for optional settings (embedding providers, SMS, email)
+- See [Tools](#tools) for the 27 available agent tools
+- See [Which compose file?](#which-compose-file) to choose the right deployment for your needs
+- For the detailed installation guide, see [docs/installation.md](docs/installation.md)
+
+### Which compose file?
+
+| File | Auth | Use case |
+|------|------|----------|
+| `docker-compose.quickstart.yml` | Disabled | Local development and testing (recommended for getting started) |
+| `docker-compose.yml` | Enabled | Basic production deployment without TLS |
+| `docker-compose.traefik.yml` | Enabled | Production with automatic TLS, HTTP/3, and WAF |
+| `docker-compose.full.yml` | Enabled | All services including frontend and optional integrations |
+| `docker-compose.test.yml` | Disabled | CI and automated testing |
+
+Start with `docker-compose.quickstart.yml`. When you are ready for production, switch to `docker-compose.yml` or `docker-compose.traefik.yml` and configure your `apiKey` in the plugin config.
+
+### Moving to Production
+
+When you're ready to move from the quickstart to a production setup:
+
+1. Stop the quickstart services: `docker compose -f docker-compose.quickstart.yml down`
+2. Open your `.env` file and find the `OPENCLAW_PROJECTS_AUTH_SECRET` value
+3. Set `OPENCLAW_PROJECTS_AUTH_DISABLED=false` in your `.env`
+4. Add the API key to your OpenClaw plugin config:
+   ```yaml
+   plugins:
+     entries:
+       openclaw-projects:
+         config:
+           apiUrl: https://your-domain.example.com
+           apiKey: your-OPENCLAW_PROJECTS_AUTH_SECRET-value
+   ```
+5. Switch to a production compose file: `docker compose -f docker-compose.yml up -d`
+
 ## Features
 
-- **Memory Management**: Store, recall, and forget memories with semantic search
+- **Memory Management**: Store, recall, and forget memories with semantic search (pgvector)
 - **Project Management**: List, get, and create projects
 - **Todo Management**: Manage todos with completion tracking
-- **Contact Management**: Search, get, and create contacts
+- **Contact Management**: Search, get, and create contacts with relationship mapping
+- **Communications**: Send SMS (Twilio) and email (Postmark) directly from agents
+- **Message History**: Search and browse message threads across channels
+- **Skill Store**: Persist and query structured data for agent skills
 - **Auto-Recall**: Automatically inject relevant context into conversations
 - **Auto-Capture**: Capture important information from completed conversations
-- **CLI Commands**: Debug and manage the plugin from the command line
-- **Multi-User Support**: Flexible user scoping (agent, session, identity)
+- **Bundled Skills**: 4 ready-to-use skills for common workflows
 
 ## Installation
 
+### Via OpenClaw CLI (recommended)
+
 ```bash
-pnpm add @troykelly/openclaw-projects
+openclaw plugins install @troykelly/openclaw-projects
 ```
 
-## Quick Start
+Then configure the plugin in your OpenClaw config file (`~/.openclaw/config.yaml` or equivalent):
 
-```typescript
-import { register } from '@troykelly/openclaw-projects'
+```yaml
+plugins:
+  entries:
+    openclaw-projects:
+      enabled: true
+      config:
+        apiUrl: https://your-backend.example.com
+        apiKey: your-api-key
+```
 
-const plugin = register({
-  config: {
-    apiUrl: 'https://your-backend.example.com',
-    apiKey: process.env.OPENCLAW_API_KEY,
-  },
-})
+### Via npm (for programmatic use)
 
-// Use tools
-const result = await plugin.tools.memoryRecall.execute({
-  query: 'user preferences',
-})
+```bash
+pnpm add @troykelly/openclaw-projects
 ```
 
-## Configuration
+This method is for integrating the plugin programmatically outside of the OpenClaw runtime. Most users should use the OpenClaw CLI method above.
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `apiUrl` | string | **required** | Backend API URL |
-| `apiKey` | string | **required** | API authentication key |
-| `autoRecall` | boolean | `true` | Enable auto-recall hook |
-| `autoCapture` | boolean | `true` | Enable auto-capture hook |
-| `userScoping` | string | `'agent'` | User scoping mode |
-| `maxRecallMemories` | number | `5` | Max memories to return |
-| `minRecallScore` | number | `0.7` | Minimum similarity score |
-| `timeout` | number | `30000` | API timeout (ms) |
-| `maxRetries` | number | `3` | Max retry attempts |
-| `debug` | boolean | `false` | Enable debug logging |
+## Verification
 
-### User Scoping Modes
+After installation, verify the plugin is loaded:
 
-| Mode | Description | Use Case |
-|------|-------------|----------|
-| `agent` | Scope by agent ID | Single user per agent |
-| `session` | Scope by session key | Maximum isolation |
-| `identity` | Scope by canonical identity | Shared identity across agents |
+```bash
+openclaw plugins info openclaw-projects
+```
 
-### Environment Variables
+### Health Check (status command)
+
+The plugin includes a built-in health check that verifies API connectivity, authentication, and reports latency:
 
 ```bash
-OPENCLAW_API_URL=https://your-backend.example.com
-OPENCLAW_API_KEY=your-api-key
+openclaw openclaw-projects status
 ```
 
-## Tools
+**Healthy output:**
 
-### Memory Tools
+```
+openclaw-projects status:
+  API URL:    http://localhost:3000
+  Status:     healthy
+  Auth:       valid
+  Latency:    12ms
+```
 
-#### `memory_recall`
-Search memories semantically.
+**Unhealthy output (backend unreachable):**
 
-```typescript
-const result = await plugin.tools.memoryRecall.execute({
-  query: 'user preferences for notifications',
-  limit: 10,           // optional, default: 5
-  category: 'preference', // optional filter
-})
+```
+openclaw-projects status:
+  API URL:    http://localhost:3000
+  Status:     unhealthy
+  Error:      Connection refused (ECONNREFUSED)
 ```
 
-#### `memory_store`
-Save information to long-term memory.
+**Unhealthy output (authentication failure):**
 
-```typescript
-const result = await plugin.tools.memoryStore.execute({
-  text: 'User prefers dark mode',
-  category: 'preference', // preference, fact, decision, context, other
-  importance: 0.8,        // optional, 0-1
-})
+```
+openclaw-projects status:
+  API URL:    http://localhost:3000
+  Status:     unhealthy
+  Auth:       invalid (401 Unauthorized)
+  Latency:    8ms
 ```
 
-#### `memory_forget`
-Delete memories (GDPR data portability).
+The status command checks:
+- **API connectivity** -- can the plugin reach the backend URL?
+- **Authentication** -- is the API key valid and accepted?
+- **Response time** -- how long does the health check take (latency in ms)?
 
-```typescript
-// By ID
-const result = await plugin.tools.memoryForget.execute({
-  memoryId: '123e4567-e89b-12d3-a456-426614174000',
-})
+Use this command as the first diagnostic step when tools fail or behave unexpectedly.
 
-// By query (bulk delete)
-const result = await plugin.tools.memoryForget.execute({
-  query: 'outdated preferences',
-  confirm: true, // required for bulk delete
-})
+You can also use the general plugin doctor command:
+
+```bash
+openclaw plugins doctor
 ```
 
-### Project Tools
+## Configuration
 
-#### `project_list`
-List projects with optional filtering.
+Configure the plugin in your OpenClaw config file or pass config programmatically.
 
-```typescript
-const result = await plugin.tools.projectList.execute({
-  status: 'active', // optional: active, completed, archived, on_hold
-  limit: 20,        // optional
-})
-```
+### Required Settings
 
-#### `project_get`
-Get a specific project by ID.
+| Option | Type | Description |
+|--------|------|-------------|
+| `apiUrl` | string | Backend API URL (must be HTTPS in production) |
 
-```typescript
-const result = await plugin.tools.projectGet.execute({
-  id: '123e4567-e89b-12d3-a456-426614174000',
-})
-```
+### Authentication (Optional)
+
+When your backend has authentication enabled, provide the API key via one of three methods. If your backend has auth disabled (e.g., the quickstart compose), no API key is needed.
+
+| Method | Config Key | Description |
+|--------|-----------|-------------|
+| Direct value | `apiKey` | Plaintext key (for development only) |
+| File reference | `apiKeyFile` | Path to file containing key (e.g., `~/.secrets/api_key`) |
+| Command | `apiKeyCommand` | Shell command to retrieve key (e.g., `op read op://Personal/openclaw/api_key`) |
 
-#### `project_create`
-Create a new project.
+### Optional Settings
 
-```typescript
-const result = await plugin.tools.projectCreate.execute({
-  name: 'Home Renovation',
-  description: 'Kitchen remodel project', // optional
-  status: 'active', // optional
-})
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `autoRecall` | boolean | `true` | Inject relevant memories at conversation start |
+| `autoCapture` | boolean | `true` | Capture important info from completed conversations |
+| `userScoping` | string | `'agent'` | User scoping mode (`agent`, `session`, `identity`) |
+| `maxRecallMemories` | number | `5` | Max memories to inject in auto-recall |
+| `minRecallScore` | number | `0.7` | Minimum similarity score for auto-recall (0-1) |
+| `timeout` | number | `30000` | API request timeout (ms) |
+| `maxRetries` | number | `3` | Max retry attempts for failed requests |
+| `debug` | boolean | `false` | Enable debug logging (never logs secrets) |
+
+### Secret Management
+
+All secret fields (API key, Twilio credentials, Postmark token) support three resolution methods. The plugin resolves secrets in priority order: command > file > direct value.
+
+```yaml
+plugins:
+  entries:
+    openclaw-projects:
+      enabled: true
+      config:
+        apiUrl: https://your-backend.example.com
+        # Option 1: Direct value (development only)
+        apiKey: sk-dev-key-here
+        # Option 2: File reference
+        # apiKeyFile: ~/.secrets/openclaw-api-key
+        # Option 3: Command (e.g., 1Password CLI)
+        # apiKeyCommand: op read op://Personal/openclaw/api_key
 ```
 
-### Todo Tools
+### Twilio SMS (optional)
 
-#### `todo_list`
-List todos with optional filtering.
+To enable SMS sending, add Twilio credentials using the same direct/file/command pattern:
 
-```typescript
-const result = await plugin.tools.todoList.execute({
-  projectId: '123e4567-e89b-12d3-a456-426614174000', // optional
-  completed: false, // optional
-  limit: 50,        // optional
-})
+```yaml
+        twilioAccountSid: AC...
+        twilioAuthToken: your-auth-token
+        twilioPhoneNumber: "+15551234567"
 ```
 
-#### `todo_create`
-Create a new todo.
+### Postmark Email (optional)
+
+To enable email sending, add Postmark credentials:
 
-```typescript
-const result = await plugin.tools.todoCreate.execute({
-  title: 'Buy groceries',
-  projectId: '123e4567-e89b-12d3-a456-426614174000', // optional
-  dueDate: '2024-01-15', // optional, ISO 8601
-})
+```yaml
+        postmarkToken: your-postmark-token
+        postmarkFromEmail: noreply@example.com
 ```
 
-#### `todo_complete`
-Mark a todo as complete.
+### User Scoping Modes
 
-```typescript
-const result = await plugin.tools.todoComplete.execute({
-  id: '123e4567-e89b-12d3-a456-426614174000',
-})
-```
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| `agent` | Scope by agent ID; single user per agent | Personal assistant (default) |
+| `session` | Scope by session key; maximum isolation | Sensitive operations |
+| `identity` | Scope by canonical user identity across agents and sessions | Multi-agent setups, shared identity |
+
+## Tools
+
+The plugin registers 27 tools that agents can use. Tools are automatically available to any agent with the plugin enabled.
+
+### Memory Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_recall` | Search memories semantically by query |
+| `memory_store` | Store a new memory (preference, fact, decision, context) |
+| `memory_forget` | Delete memories by ID or search query |
+
+### Project Tools
+
+| Tool | Description |
+|------|-------------|
+| `project_list` | List projects with optional status filter |
+| `project_get` | Get full details of a specific project |
+| `project_create` | Create a new project |
+
+### Todo Tools
+
+| Tool | Description |
+|------|-------------|
+| `todo_list` | List todos, optionally filtered by project or status |
+| `todo_create` | Create a new todo item |
+| `todo_complete` | Mark a todo as complete |
 
 ### Contact Tools
 
-#### `contact_search`
-Search contacts.
+| Tool | Description |
+|------|-------------|
+| `contact_search` | Search contacts by name, email, or other fields |
+| `contact_get` | Get full details of a specific contact |
+| `contact_create` | Create a new contact |
 
-```typescript
-const result = await plugin.tools.contactSearch.execute({
-  query: 'Alice',
-  limit: 10, // optional
-})
-```
+### Communication Tools
 
-#### `contact_get`
-Get a specific contact by ID.
+| Tool | Description |
+|------|-------------|
+| `sms_send` | Send an SMS message (requires Twilio config) |
+| `email_send` | Send an email message (requires Postmark config) |
+| `message_search` | Search message history semantically |
+| `thread_list` | List message threads (conversations) |
+| `thread_get` | Get a thread with full message history |
 
-```typescript
-const result = await plugin.tools.contactGet.execute({
-  id: '123e4567-e89b-12d3-a456-426614174000',
-})
-```
+### Relationship Tools
 
-#### `contact_create`
-Create a new contact.
+| Tool | Description |
+|------|-------------|
+| `relationship_set` | Record a relationship between contacts |
+| `relationship_query` | Query a contact's relationships |
 
-```typescript
-const result = await plugin.tools.contactCreate.execute({
-  name: 'Alice Smith',
-  email: 'alice@example.com', // optional
-  phone: '+1-555-123-4567',   // optional
-})
-```
+### Skill Store Tools
 
-## Lifecycle Hooks
+| Tool | Description |
+|------|-------------|
+| `skill_store_put` | Store or update data in the skill store |
+| `skill_store_get` | Retrieve an item by ID or composite key |
+| `skill_store_list` | List items with filtering and pagination |
+| `skill_store_delete` | Delete an item (soft delete) |
+| `skill_store_search` | Search items by text or semantic similarity |
+| `skill_store_collections` | List all collections with item counts |
+| `skill_store_aggregate` | Run aggregations on skill store items |
 
-### `beforeAgentStart` (Auto-Recall)
+### Other Tools
 
-Automatically fetches relevant context before the agent processes a prompt.
+| Tool | Description |
+|------|-------------|
+| `file_share` | Generate a time-limited shareable download link |
 
-```typescript
-const context = await plugin.hooks.beforeAgentStart({
-  prompt: 'What are my notification preferences?',
-})
+## Skills
 
-if (context) {
-  // Prepend context.prependContext to the conversation
-}
-```
+The plugin includes 4 bundled skills that agents can invoke as high-level workflows. Skills combine multiple tools to accomplish common tasks.
 
-### `agentEnd` (Auto-Capture)
+### `contact-lookup`
 
-Automatically captures important information after a conversation ends.
+Look up contact information and recent communications.
 
-```typescript
-await plugin.hooks.agentEnd({
-  messages: [
-    { role: 'user', content: 'Remember I prefer email notifications' },
-    { role: 'assistant', content: 'Noted! I will remember your preference.' },
-  ],
-})
+```
+/contact-lookup name="Alice Smith"
 ```
 
-## CLI Commands
+Searches contacts, retrieves details, shows recent messages, related projects/tasks, and stored memories about the person.
 
-The plugin provides CLI command handlers that can be registered with OpenClaw:
+### `daily-summary`
 
-### `status`
-Check API connectivity.
+Get a summary of today's tasks, messages, and activities.
 
-```typescript
-const result = await plugin.cli.status()
-// { success: true, message: 'API is healthy (latency: 50ms)', data: { ... } }
+```
+/daily-summary
 ```
 
-### `users`
-Show user scoping configuration.
+Shows tasks due today, recent messages, upcoming deadlines, and items requiring attention.
 
-```typescript
-const result = await plugin.cli.users()
-// { success: true, data: { scopingMode: 'agent', description: '...', currentUserId: '...' } }
-```
+### `project-status`
 
-### `recall`
-Search memories from CLI.
+Get a status overview of a specific project.
 
-```typescript
-const result = await plugin.cli.recall({ query: 'preferences', limit: 10 })
-// { success: true, data: { memories: [...], query: '...', limit: 10 } }
+```
+/project-status project="Home Renovation"
 ```
 
-### `stats`
-Show memory statistics.
+Shows project overview, task breakdown with completion percentage, recent activity, blockers, and recommended next steps.
 
-```typescript
-const result = await plugin.cli.stats()
-// { success: true, data: { totalMemories: 42, byCategory: { ... } } }
-```
+### `send-reminder`
 
-### `export`
-Export all memories (GDPR data portability).
+Send a reminder message to a contact via SMS or email.
 
-```typescript
-const result = await plugin.cli.export({ output: '/path/to/export.json' })
-// { success: true, data: { memories: [...], exportedAt: '...', userId: '...' } }
+```
+/send-reminder contact="Alice" message="Don't forget the meeting tomorrow" channel="sms"
 ```
 
-## Health Check
+Looks up the contact, verifies their endpoint, sends the message, and confirms delivery.
 
-```typescript
-const health = await plugin.healthCheck()
-if (!health.healthy) {
-  console.error('Plugin unhealthy:', health.error)
-}
-```
+## Lifecycle Hooks
+
+### `before_agent_start` (Auto-Recall)
+
+When `autoRecall` is enabled (default), the plugin automatically searches for relevant memories before each conversation. It uses the user's prompt for semantic search and injects matching memories as context via `prependContext`.
+
+### `agent_end` (Auto-Capture)
+
+When `autoCapture` is enabled (default), the plugin automatically analyzes completed conversations and stores important information (preferences, facts, decisions) as memories for future recall.
 
 ## Security
 
-### API Key Management
+### Secret Management
 
-- Store API keys in environment variables, never in code
-- Use secrets management in production (Vault, AWS Secrets Manager, etc.)
-- Rotate keys regularly
+- Use file references or command execution for secrets in production
+- Direct values are for development only
+- The plugin supports 1Password CLI, Vault, AWS Secrets Manager, or any command-line tool
+- Secret files are checked for world-readable permissions (warns if `chmod 644`)
 
 ### Data Isolation
 
 - All data is scoped to the configured user scope
 - Cross-user access is prevented at the API level
-- Audit logs track all data access
+
+### HTTPS
+
+- HTTPS is required in production (`NODE_ENV=production`)
+- HTTP is permitted for local development only
 
 ### Sensitive Content
 
-- The plugin filters sensitive content (API keys, passwords, credit cards)
-- PII is not logged at info level
+- Secrets are never logged (config is redacted in logs)
 - Error messages are sanitized to prevent information leakage
 
-### HTTPS
+## Troubleshooting
 
-- Use HTTPS in production
-- HTTP is only recommended for local development
+> **First step for any issue:** Run `openclaw openclaw-projects status` to check connectivity, authentication, and latency. See [Health Check](#health-check-status-command) above for expected output.
 
-## Error Handling
+### Plugin not loading
 
-All tool executions return a result object:
+Verify the plugin is installed and the manifest is detected:
 
-```typescript
-interface ToolResult {
-  success: boolean
-  content?: string   // Human-readable response
-  data?: unknown     // Structured data
-  error?: string     // Error message if success is false
-}
+```bash
+openclaw plugins info openclaw-projects
 ```
 
-## Troubleshooting
-
-### Connection Issues
+### Connection issues
 
-```typescript
-// Check health
-const health = await plugin.healthCheck()
-console.log('Healthy:', health.healthy, 'Error:', health.error)
+Run the status command to diagnose:
 
-// Check status via CLI
-const status = await plugin.cli.status()
-console.log('Status:', status.message, 'Latency:', status.data?.latencyMs)
+```bash
+openclaw openclaw-projects status
 ```
 
-### No Memories Found
+If the status shows unhealthy, check:
+- Is the backend running? `curl http://localhost:3000/health`
+- Is the `apiUrl` in your config correct?
+- Are there firewall rules blocking the connection?
+
+For detailed troubleshooting, see [docs/troubleshooting.md](docs/troubleshooting.md).
+
+### Authentication failures
+
+If the status command reports `Auth: invalid`:
+- Verify your `apiKey` matches the `OPENCLAW_PROJECTS_AUTH_SECRET` in the backend `.env`
+- Check the secret retrieval method (file, command) is working
+- If using the quickstart compose, auth is disabled by default (`OPENCLAW_PROJECTS_AUTH_DISABLED=true`). If you have overridden this to `false` (enabling auth), ensure your `apiKey` is correctly configured
+
+### No memories found
 
 - Verify the user scoping mode matches your setup
 - Check that memories were stored for the same user scope
 - Try broadening your search query
 
-### API Errors
+### API errors
 
-- Verify API URL is correct and accessible
-- Check API key is valid
+- Run `openclaw openclaw-projects status` to verify connectivity
+- Check that the API key is valid
 - Review network connectivity
-
-## API Reference
-
-Full TypeScript types are exported:
-
-```typescript
-import type {
-  PluginConfig,
-  PluginInstance,
-  MemoryRecallParams,
-  MemoryStoreParams,
-  ProjectListParams,
-  TodoCreateParams,
-  ContactSearchParams,
-  // ... and more
-} from '@troykelly/openclaw-projects'
-```
+- Enable debug logging (`debug: true` in config) for detailed request/response info
 
 ## Contributing
 
@@ -385,5 +518,6 @@ MIT
 ## Links
 
 - [OpenClaw Documentation](https://docs.openclaw.ai/)
+- [OpenClaw Plugin Guide](https://docs.openclaw.ai/plugins)
 - [openclaw-projects Backend](https://github.com/troykelly/openclaw-projects)
 - [Report Issues](https://github.com/troykelly/openclaw-projects/issues)