@hailer/mcp 1.1.12 → 1.1.13

package/.claude/skills/agent-structure/SKILL.md

@@ -1,98 +0,0 @@
----
-name: agent-structure
-description: Template for creating new Hailer SDK agents
-version: 1.1.0
-triggers: create agent, new agent, agent template
----
-
-# Agent Structure Template
-
-Use this template when creating new agents.
-
-## File Location
-
-`.claude/agents/agent-{name}-{role}.md`
-
-## Template
-
-```markdown
----
-name: agent-{name}-{role}
-description: What it does.\n\n<example>\nuser: "request"\nassistant: {"status":"success","result":{},"summary":"Done"}\n</example>
-model: haiku|sonnet
-tools: tool_1, tool_2
----
-
-<identity>
-I am {Name}, {nationality} {role} specialist. {Philosophy}. Output JSON. Full stop.
-</identity>
-
-<handles>
-- Task 1
-- Task 2
-</handles>
-
-<skills>
-Load `skill-name` before complex tasks.
-</skills>
-
-<rules>
-1. **NEVER FABRICATE** - Must call tools.
-2. Rule 2
-3. Rule 3
-</rules>
-
-<protocol>
-Input: JSON task spec
-Output: JSON only
-Schema: { "status": "success|error", "result": {}, "summary": "max 50 chars" }
-</protocol>
-```
-
-## Identity Shapes Behavior
-
-**The `<identity>` section is the most powerful lever for agent behavior** - more than rules.
-
-Rules tell agents what NOT to do. Identity tells them WHO they are and HOW they work. When an agent fabricates results despite having "NEVER FABRICATE" as rule 1, the fix is usually to rewrite identity to emphasize tool-first behavior.
-
-**Good identity (tool-centric):**
-```
-I am Kenji. I read files. I query APIs. I verify data. Every answer comes from a tool call. Output JSON. Full stop.
-```
-
-**Weak identity (role-centric only):**
-```
-I am Kenji, a data reader specialist.
-```
-
-**Additionally:** Give explicit step-by-step commands in the Task prompt, not just "do X". Agents follow concrete instructions better than abstract goals.
-
-## Model Selection
-
-| Model | Use for | Cost |
-|-------|---------|------|
-| `haiku` | Procedural/checklist work, CRUD, simple lookups | Cheap, fast |
-| `sonnet` | Complex reasoning, code generation, validation logic | More expensive |
-
-## Status Values
-
-| Status | Meaning | Orchestrator Action |
-|--------|---------|---------------------|
-| `success` | Task completed | Report to user |
-| `error` | Task failed | Report error, maybe retry |
-| `ready_to_push` | Files edited, needs push | Run commands in `commands` array |
-| `needs_confirmation` | Destructive action | Ask user, then run `safe_command` |
-
-## Naming Convention
-
-- `agent-kenji-data-reader` - Kenji reads data
-- `agent-helga-workflow-config` - Helga configures workflows
-- `agent-igor-activity-mover-automation` - Igor builds activity movers
-
-Pattern: `agent-{firstname}-{domain}`
-
-## Customization
-
-- **CREATE:** Add to `.claude/agents/`
-- **MODIFY:** Edit `.claude/agents/*.md`
-- **DISABLE:** Move to `docs/agents/`

package/.claude/skills/api-documentation-patterns/SKILL.md

@@ -1,474 +0,0 @@
----
-name: api-documentation-patterns
-description: Hailer API documentation standards - research workflow, section structure, example patterns
-version: 1.0.0
-triggers: Document endpoint, API documentation, @hailer/cli examples, Socket.IO signals
----
-
-# API Documentation Patterns
-
-## Research Workflow
-
-Before documenting any endpoint, follow this research sequence:
-
-### 1. Find Test Usage
-
-```bash
-# Search test files for endpoint usage
-grep -n -A 10 -B 5 "endpoint.name" test/test-*.ts
-
-# Example
-grep -n -A 10 "v3.activity.archive" test/test-api-activities.ts
-```
-
-### 2. Find Implementation
-
-```bash
-# RPC endpoints (v2, v3)
-grep -n -A 30 "_endpointName.*{" src/api/v3/
-grep -n -A 30 "endpointName: async" src/modules/
-
-# REST endpoints
-grep -n -A 30 "router\.(get|post|put|delete)" src/route-*.ts
-```
-
-### 3. Extract Validation Schemas
-
-```bash
-# Find Joi validation
-grep -n -A 15 "validate.*req.*context" src/api/v3/
-grep -n -A 10 "Joi.object" src/api/v3/
-```
-
-### 4. Find Socket.IO Signals
-
-```bash
-# Find signal broadcasts
-grep -n "broadcastCompany\|broadcastUsers" src/
-grep -n -A 5 "sig.*:" src/modules/
-```
-
-### 5. Check Permissions
-
-```bash
-# Find permission checks
-grep -n "permission\|requireAuth\|checkAccess" src/api/v3/
-```
-
----
-
-## Required Documentation Structure
-
-Every endpoint MUST have these 10 sections in order:
-
-### Section 1: Title and Description
-
-```markdown
-# v3.activity.archive
-
-Archives one or more activities, removing them from active workflow views while preserving all data for compliance, reporting, and potential restoration.
-
-**Use Cases:**
-- Clean up completed project activities
-- Archive old records for compliance
-- Remove activities from active views without data loss
-```
-
-### Section 2: Understanding Context
-
-```markdown
-## Understanding Activity Archiving
-
-Archiving is a **soft-delete** operation in Hailer:
-
-- **Preserved**: All activity data, field values, history, and attachments remain intact
-- **Hidden**: Archived activities don't appear in standard workflow views
-- **Restorable**: Admin users can restore archived activities at any time
-- **Queryable**: Archived activities can still be included in insights with special filters
-
-### Archive vs Delete
-
-| Operation | Data Preserved | Restorable | Appears in Views |
-|-----------|---------------|------------|------------------|
-| Archive | Yes | Yes | No (by default) |
-| Delete | No | No | No |
-```
-
-### Section 3: Prerequisites
-
-```markdown
-## Prerequisites
-
-### Authentication
-- Valid session token required
-- User must be logged in
-
-### Permissions
-One of the following:
-- `admin` workflow permission
-- `any` workflow permission
-- `own` permission AND activity owner
-
-### Activity State
-- Activity must exist
-- Activity must not already be archived
-```
-
-### Section 4: Request Parameters
-
-```markdown
-## Request Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `activityIds` | string[] | Yes | Array of activity IDs to archive (max 100) |
-| `options` | object | No | Additional options |
-| `options.archiveLinked` | boolean | No | Also archive linked activities (default: false) |
-| `options.reason` | string | No | Archive reason for audit log |
-
-### Parameter Details
-
-**activityIds**
-- Must be valid MongoDB ObjectIds
-- Maximum 100 activities per request
-- All activities must be in same workspace
-
-**options.archiveLinked**
-- When true, also archives activities linked TO these activities
-- Does not archive activities that link FROM these activities
-```
-
-### Section 5: Response Structure
-
-```markdown
-## Response Structure
-
-### Success Response
-
-```json
-{
-  "archived": ["64a1b2c3d4e5f6a7b8c9d0e1", "64a1b2c3d4e5f6a7b8c9d0e2"],
-  "failed": [],
-  "count": 2
-}
-```
-
-### Partial Success Response
-
-```json
-{
-  "archived": ["64a1b2c3d4e5f6a7b8c9d0e1"],
-  "failed": [
-    {
-      "activityId": "64a1b2c3d4e5f6a7b8c9d0e2",
-      "reason": "Permission denied"
-    }
-  ],
-  "count": 1
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `archived` | string[] | IDs of successfully archived activities |
-| `failed` | object[] | Activities that failed with reasons |
-| `count` | number | Number of successfully archived activities |
-```
-
-### Section 6: Examples (ALL 4 REQUIRED)
-
-```markdown
-## Examples
-
-### Basic Usage
-
-```javascript
-// Archive single activity
-const result = await client.request('v3.activity.archive', [
-  ['64a1b2c3d4e5f6a7b8c9d0e1']
-]);
-console.log(`Archived ${result.count} activities`);
-
-// Archive multiple activities
-const result = await client.request('v3.activity.archive', [
-  ['64a1b2c3d4e5f6a7b8c9d0e1', '64a1b2c3d4e5f6a7b8c9d0e2']
-]);
-```
-
-### Simplified Function
-
-```javascript
-// Direct call syntax
-const result = v3.activity.archive(['activity_id_1', 'activity_id_2']);
-```
-
-### Complete Implementation
-
-```javascript
-class ActivityArchiver {
-  constructor(client) {
-    this.client = client;
-  }
-
-  async archiveActivities(activityIds, options = {}) {
-    // Validate input
-    if (!activityIds || activityIds.length === 0) {
-      throw new Error('At least one activity ID required');
-    }
-
-    if (activityIds.length > 100) {
-      throw new Error('Maximum 100 activities per request');
-    }
-
-    try {
-      const result = await this.client.request('v3.activity.archive', [
-        activityIds,
-        options
-      ]);
-
-      // Log results
-      console.log(`Archived: ${result.archived.length}`);
-
-      if (result.failed.length > 0) {
-        console.warn('Some activities failed to archive:');
-        result.failed.forEach(f => {
-          console.warn(`  - ${f.activityId}: ${f.reason}`);
-        });
-      }
-
-      return result;
-    } catch (error) {
-      this.handleError(error);
-      throw error;
-    }
-  }
-
-  handleError(error) {
-    switch (error.code) {
-      case 'NotFound':
-        console.error('One or more activities not found');
-        break;
-      case 'PermissionDenied':
-        console.error('Insufficient permissions to archive');
-        break;
-      case 'InvalidArguments':
-        console.error('Invalid activity IDs provided');
-        break;
-      default:
-        console.error('Archive operation failed:', error.message);
-    }
-  }
-}
-
-// Usage
-const archiver = new ActivityArchiver(client);
-await archiver.archiveActivities(['id1', 'id2'], { reason: 'Project completed' });
-```
-
-### Integration Example
-
-```javascript
-// Archive all completed activities older than 90 days
-async function archiveOldCompletedActivities(client, workflowId, completedPhaseId) {
-  const ninetyDaysAgo = Date.now() - (90 * 24 * 60 * 60 * 1000);
-
-  // Get old completed activities
-  const activities = await client.request('v3.activity.list', [{
-    processId: workflowId,
-    phaseId: completedPhaseId,
-    filter: {
-      updated: { $lt: ninetyDaysAgo }
-    },
-    limit: 100
-  }]);
-
-  if (activities.length === 0) {
-    console.log('No activities to archive');
-    return;
-  }
-
-  // Archive them
-  const ids = activities.map(a => a._id);
-  const result = await client.request('v3.activity.archive', [
-    ids,
-    { reason: 'Auto-archive: >90 days in completed phase' }
-  ]);
-
-  console.log(`Archived ${result.count} old activities`);
-  return result;
-}
-```
-```
-
-### Section 7: Error Responses
-
-```markdown
-## Error Responses
-
-### Activity Not Found
-
-```json
-{
-  "code": "NotFound",
-  "message": "Activity not found: 64a1b2c3d4e5f6a7b8c9d0e1"
-}
-```
-
-### Permission Denied
-
-```json
-{
-  "code": "PermissionDenied",
-  "message": "Insufficient permissions to archive activity"
-}
-```
-
-### Invalid Arguments
-
-```json
-{
-  "code": "InvalidArguments",
-  "message": "activityIds must be an array of valid ObjectIds"
-}
-```
-
-### Already Archived
-
-```json
-{
-  "code": "Failed",
-  "message": "Activity is already archived"
-}
-```
-```
-
-### Section 8: Technical Sections
-
-```markdown
-## Socket.IO Signals
-
-This endpoint emits the following real-time signals:
-
-### activities.archived
-
-Emitted to all workspace members with view access.
-
-```json
-{
-  "sig": "activities.archived",
-  "meta": {
-    "activityIds": ["64a1b2c3d4e5f6a7b8c9d0e1"],
-    "processId": "64a1b2c3d4e5f6a7b8c9d0e3",
-    "archivedBy": "64a1b2c3d4e5f6a7b8c9d0e4",
-    "timestamp": 1730937600000
-  }
-}
-```
-
-## Performance Considerations
-
-- **Batch size**: Maximum 100 activities per request
-- **Large archives**: Use pagination for >1000 activities
-- **Linked activities**: `archiveLinked: true` may increase processing time
-- **Indexes**: Archive queries are optimized via `archived` field index
-
-## Security Considerations
-
-- All archive operations are logged in activity history
-- Archive reason is stored for audit purposes
-- Only admin users can restore archived activities
-- Archived data remains subject to data retention policies
-```
-
-### Section 9: Notes
-
-```markdown
-## Notes
-
-- Archived activities are **excluded from insights by default** - use `includeArchived: true` filter
-- The `activities.archived` signal is emitted to update connected clients
-- Archiving is **reversible** via `v3.activity.restore` (admin only)
-- Archive operations are **atomic** - partial failures don't affect successful archives
-- Archived activities still count toward workspace storage limits
-```
-
-### Section 10: Related Endpoints
-
-```markdown
-## Related Endpoints
-
-- [v3.activity.restore](v3.activity.restore.md) - Restore archived activities
-- [v3.activity.delete](v3.activity.delete.md) - Permanently delete activities
-- [v3.activity.list](v3.activity.list.md) - List activities (supports archive filter)
-- [v3.activity.get](v3.activity.get.md) - Get single activity (works on archived)
-```
-
----
-
-## Forbidden Patterns
-
-NEVER include these in documentation:
-
-### Raw Socket.io
-
-```javascript
-// WRONG - Never show raw socket calls
-socket.emit('v3.activity.archive', [ids], callback);
-```
-
-### Raw HTTP/Fetch
-
-```javascript
-// WRONG - Never show raw HTTP
-fetch('/api/v3.activity.archive', {
-  method: 'POST',
-  body: JSON.stringify({ args: [ids] })
-});
-```
-
-### Framework-Specific Code
-
-```javascript
-// WRONG - No React, Vue, Angular examples
-function useArchive() {
-  const [loading, setLoading] = useState(false);
-  // ...
-}
-```
-
-### Raw JSON-RPC
-
-```json
-// WRONG - No raw protocol format
-{
-  "method": "v3.activity.archive",
-  "args": [["id1", "id2"]]
-}
-```
-
----
-
-## Quality Checklist
-
-Before marking documentation complete:
-
-**Content:**
-- [ ] All 10 sections present in correct order
-- [ ] All 4 example patterns included
-- [ ] Socket.IO signals documented (if applicable)
-- [ ] Complete parameter table with types
-- [ ] Error responses with JSON examples
-- [ ] Related endpoints listed
-
-**Research:**
-- [ ] Found test file usage examples
-- [ ] Located implementation code
-- [ ] Extracted Joi validation schemas
-- [ ] Identified Socket.IO signals
-- [ ] Documented permission requirements
-
-**Quality:**
-- [ ] Uses ONLY @hailer/cli patterns
-- [ ] No framework-specific examples
-- [ ] No raw Socket.io or HTTP examples
-- [ ] Consistent formatting throughout