@hailer/mcp 0.0.1

package/.claude/skills/remove-insight-skill/SKILL.md

@@ -0,0 +1,1011 @@
+---
+name: Removing Hailer Insights
+description: Complete guide for safely removing Hailer insights - use when deleting reports or cleaning up insights
+---
+
+# Removing Hailer Insights - Complete Guide
+
+Complete reference for safely removing Hailer insights using the `remove_insight` MCP tool.
+
+## Table of Contents
+1. [Quick Reference](#quick-reference)
+2. [Overview](#overview)
+3. [What Gets Deleted](#what-gets-deleted)
+4. [Prerequisites](#prerequisites)
+5. [Basic Usage](#basic-usage)
+6. [Safety Checklist](#safety-checklist)
+7. [Common Scenarios](#common-scenarios)
+8. [Before Removing](#before-removing)
+9. [After Removing](#after-removing)
+10. [Best Practices](#best-practices)
+11. [Troubleshooting](#troubleshooting)
+
+## Quick Reference
+
+**⚠️ WARNING: This operation is PERMANENT and CANNOT be undone!**
+
+**Basic Removal:**
+
+```javascript
+remove_insight({
+  insightId: 'insight-id'
+})
+```
+
+**Response:**
+```
+✅ Insight Removed Successfully
+
+Insight ID: insight-id
+
+⚠️ The insight has been permanently deleted.
+
+What was deleted:
+- Insight definition (SQL query and sources)
+- Saved query results
+- Insight permissions
+- Associated discussion
+```
+
+**Key Requirements:**
+- Must be insight owner OR workspace administrator
+- Insight ID must be valid
+- Cannot be undone - all data permanently deleted
+- Discussion associated with insight also deleted
+
+## Overview
+
+The `remove_insight` tool permanently deletes an insight from your Hailer workspace. This is a **destructive operation** that removes both the insight definition and all associated data.
+
+**Think of it as:**
+- Dropping a database view
+- Deleting a saved report
+- Removing a SQL query definition
+- Permanent deletion
+
+**When to use:**
+- Cleaning up test/development insights
+- Removing obsolete or unused reports
+- Deleting insights with incorrect queries
+- Workspace reorganization
+- Archiving completed analysis
+
+**When NOT to use:**
+- If you might need the query definition later (export first)
+- If other users depend on the insight
+- If you're unsure about usage
+- For temporary deactivation (no such option exists)
+
+## What Gets Deleted
+
+### 1. Insight Definition
+- Insight name and description
+- SQL query text
+- Source definitions (workflow mappings, field mappings)
+- Insight configuration (public/private setting)
+- Metadata (creator, creation date)
+
+### 2. Saved Query Results
+- Cached result data (columns and rows)
+- Last calculation timestamp
+- Result statistics
+
+### 3. Insight Permissions
+- Access control list
+- Sharing settings
+- Public access settings
+
+### 4. Associated Discussion
+- Discussion thread linked to insight
+- All messages in the discussion
+- Message attachments
+- Discussion participants list
+- Read receipts and notifications
+
+### What Does NOT Get Deleted
+- Source workflows (workflows remain intact)
+- Activities in source workflows (data not affected)
+- Users who accessed the insight
+- External references to insight (links will break)
+- Insights that reference same workflows (other insights unaffected)
+
+## Prerequisites
+
+### Required Permissions
+
+**You can remove an insight if:**
+- You are the insight creator/owner, OR
+- You are a workspace administrator
+
+**You CANNOT remove an insight if:**
+- You are not the owner and not an admin
+- You only have read access to the insight
+- Insight was shared with you but you don't own it
+
+**Check permissions:**
+```javascript
+// List insights to see which you own
+const insights = list_insights()
+insights.forEach(i => {
+  console.log(`${i.name}: Owner=${i.owner}, You=${i.isOwner ? 'Owner' : 'Viewer'}`)
+})
+```
+
+### Required Information
+
+**1. Insight ID**
+
+Get from `list_insights`:
+```javascript
+const insights = list_insights()
+insights.forEach(i => {
+  console.log(`${i.name}: ${i._id}`)
+})
+```
+
+**2. Verify Ownership**
+
+Confirm you have permission:
+```javascript
+const insights = list_insights()
+const target = insights.find(i => i._id === 'target-id')
+
+if (target.isOwner || target.isAdmin) {
+  console.log('✅ Can remove')
+} else {
+  console.log('❌ Cannot remove - not owner or admin')
+}
+```
+
+## Basic Usage
+
+### Example 1: Remove Simple Insight
+
+```javascript
+// 1. Find the insight
+const insights = list_insights()
+const testInsight = insights.find(i => i.name === 'Test Report')
+console.log('Found insight:', testInsight._id)
+
+// 2. Remove it
+remove_insight({
+  insightId: testInsight._id
+})
+
+// Output:
+// ✅ Insight Removed Successfully
+// Insight ID: 68446dc05b30685f67c6fcd4
+// ⚠️ The insight has been permanently deleted.
+```
+
+### Example 2: Remove with Verification
+
+```javascript
+// 1. List insights
+const insights = list_insights()
+
+// 2. Find target insight
+const target = insights.find(i => i.name === 'Old Report')
+
+// 3. Verify it's the right one
+console.log('About to remove:')
+console.log('- Name:', target.name)
+console.log('- ID:', target._id)
+console.log('- Created:', target.created)
+console.log('- Public:', target.public)
+
+// 4. Get one last look at data
+const data = get_insight_data({
+  insightId: target._id
+})
+console.log('- Result rows:', data.rows.length)
+
+// 5. Confirm and remove
+const confirmed = true  // Your confirmation logic
+if (confirmed) {
+  remove_insight({
+    insightId: target._id
+  })
+}
+```
+
+### Example 3: Batch Removal
+
+```javascript
+// Remove multiple test insights
+
+const insights = list_insights()
+
+// Find all test insights
+const testInsights = insights.filter(i =>
+  i.name.toLowerCase().includes('test') ||
+  i.name.toLowerCase().includes('demo')
+)
+
+console.log(`Found ${testInsights.length} test insights`)
+
+// Remove each one
+testInsights.forEach(insight => {
+  console.log(`Removing: ${insight.name}`)
+  remove_insight({
+    insightId: insight._id
+  })
+})
+
+console.log('✅ All test insights removed')
+```
+
+## ⚠️ MANDATORY: Comprehensive Confirmation Protocol
+
+**BEFORE calling `remove_insight`, you MUST gather complete context and show it to the user:**
+
+### Required Context to Gather
+
+1. **Workspace Information:**
+   - Workspace ID: Get from API init or insight data
+   - Workspace name: Get from API init
+
+2. **Insight Information:**
+   - Insight ID (provided by user)
+   - Insight name: Get from `list_insights`
+   - SQL query: Get from `list_insights`
+   - Source workflows: Get from `list_insights` (sources array)
+   - Number of sources being queried
+
+3. **What Will Be Deleted:**
+   - Insight definition (sources, query, name)
+   - Saved query results
+   - Insight permissions
+   - Associated discussion
+
+### Required Confirmation Message Format
+
+**You MUST display this information to the user BEFORE calling the tool:**
+
+```
+⚠️ WARNING: This action is irreversible!
+
+You are about to permanently delete the following:
+
+**Workspace**:
+- Workspace ID: `<workspace-id>`
+- Workspace name: <workspace-name>
+
+**Insight to Delete**:
+- Name: <insight-name>
+- ID: `<insight-id>`
+
+**What Will Be Deleted**:
+- ❌ Insight definition (sources, query, name)
+- ❌ Saved query results
+- ❌ Insight permissions
+- ❌ Associated discussion
+
+**Sources Being Queried**:
+- Workflow: <workflow-name-1>
+- Workflow: <workflow-name-2>
+(These workflows won't be affected, only this insight will be deleted)
+
+**This operation cannot be undone. All data will be permanently lost.**
+
+Do you want to proceed with permanently deleting this insight?
+```
+
+### Example: Complete Safe Removal Flow
+
+```javascript
+// Step 1: Gather complete context
+const insights = list_insights()
+const targetInsight = insights.find(i => i._id === "target-id")
+const workspaceName = "My Workspace"  // From init or context
+
+// Step 2: Get workflow names for sources
+const sourceWorkflowNames = targetInsight.sources.map(s => s.name || s.workflowId)
+
+// Step 3: Show comprehensive confirmation message to user
+console.log(`
+⚠️ WARNING: This action is irreversible!
+
+**Workspace**:
+- Workspace ID: \`${workspaceId}\`
+- Workspace name: ${workspaceName}
+
+**Insight to Delete**:
+- Name: ${targetInsight.name}
+- ID: \`${targetInsight._id}\`
+
+**What Will Be Deleted**:
+- ❌ Insight definition (sources, query, name)
+- ❌ Saved query results
+- ❌ Insight permissions
+- ❌ Associated discussion
+
+**Sources Being Queried**:
+${sourceWorkflowNames.map(name => `- Workflow: ${name}`).join('\n')}
+
+This operation cannot be undone.
+`)
+
+// Step 4: Wait for explicit user confirmation
+
+// Step 5: Only after confirmation, call the tool
+remove_insight({ insightId: targetInsight._id })
+```
+
+### **FAILURE TO GATHER AND SHOW THIS CONTEXT IS AN ERROR**
+
+If you call `remove_insight` without first gathering and displaying all this information to the user, you are violating safety protocols.
+
+## Safety Checklist
+
+**Before removing ANY insight, complete this checklist:**
+
+### Step 1: Identify the Insight
+- [ ] Confirmed insight name with `list_insights`
+- [ ] Verified insight ID is correct
+- [ ] Reviewed insight query and sources
+- [ ] Checked insight description/purpose
+
+### Step 2: Check Usage
+- [ ] Verified no active users depend on this insight
+- [ ] Checked if insight is embedded in apps
+- [ ] Searched for references in documentation
+- [ ] Confirmed insight not used in dashboards
+- [ ] Asked team if insight is still needed
+
+### Step 3: Export Data (If Needed)
+- [ ] Saved insight query definition
+- [ ] Exported current data with `get_insight_data`
+- [ ] Documented source workflows and field mappings
+- [ ] Archived any important discussion messages
+
+### Step 4: Verify Permissions
+- [ ] Confirmed you are owner or admin
+- [ ] Checked insight ownership
+- [ ] Verified no organizational policies prevent removal
+
+### Step 5: Consider Alternatives
+- [ ] Considered duplicating before removing
+- [ ] Evaluated updating query instead
+- [ ] Checked if making private is better option
+- [ ] Reviewed if insight can be archived differently
+
+### Step 6: Final Confirmation
+- [ ] Double-checked insight ID one more time
+- [ ] Confirmed this is the intended insight
+- [ ] Accepted that this cannot be undone
+- [ ] Ready to proceed with deletion
+
+## Common Scenarios
+
+### Scenario 1: Clean Up Test Insights
+
+**Situation:** Created test insights during development.
+
+```javascript
+// 1. List all insights
+const insights = list_insights()
+
+// 2. Identify test insights
+const testInsights = insights.filter(i =>
+  i.name.startsWith('Test -') ||
+  i.name.includes('[TEST]') ||
+  i.name.includes('Demo')
+)
+
+console.log(`Found ${testInsights.length} test insights:`)
+testInsights.forEach(i => console.log(`- ${i.name}`))
+
+// 3. Remove each test insight
+testInsights.forEach(insight => {
+  remove_insight({ insightId: insight._id })
+  console.log(`✅ Removed: ${insight.name}`)
+})
+```
+
+### Scenario 2: Replace Insight with Improved Version
+
+**Situation:** Created new insight to replace old one.
+
+```javascript
+// 1. Create new insight
+const newInsight = create_insight({
+  name: 'Tasks Report v2',
+  sources: [...],  // Improved query
+  query: '...'
+})
+
+// 2. Verify new insight works
+const data = get_insight_data({
+  insightId: newInsight.insightId,
+  update: true
+})
+console.log(`✅ New insight works: ${data.rows.length} rows`)
+
+// 3. Find old insight
+const insights = list_insights()
+const oldInsight = insights.find(i => i.name === 'Tasks Report v1')
+
+// 4. Remove old version
+remove_insight({
+  insightId: oldInsight._id
+})
+```
+
+### Scenario 3: Remove Broken Insight
+
+**Situation:** Insight has SQL errors or references deleted workflows.
+
+```javascript
+// 1. Try to get data (will fail)
+try {
+  get_insight_data({ insightId: 'broken-insight-id' })
+} catch (error) {
+  console.log('❌ Insight is broken:', error.message)
+}
+
+// 2. Try to preview (check if fixable)
+try {
+  preview_insight({
+    sources: brokenInsight.sources,
+    query: brokenInsight.query
+  })
+} catch (error) {
+  console.log('❌ Query cannot be fixed:', error.message)
+}
+
+// 3. Remove broken insight
+remove_insight({
+  insightId: 'broken-insight-id'
+})
+console.log('✅ Removed broken insight')
+```
+
+### Scenario 4: Remove Unused Insights
+
+**Situation:** Insights exist but no longer used.
+
+```javascript
+// 1. List all insights
+const insights = list_insights()
+
+// 2. Check each insight's last update
+insights.forEach(insight => {
+  const lastUpdate = new Date(insight.lastCalculated)
+  const daysSinceUpdate = (Date.now() - lastUpdate) / 1000 / 60 / 60 / 24
+
+  console.log(`${insight.name}: ${daysSinceUpdate.toFixed(0)} days old`)
+
+  // 3. Remove if very old (e.g., > 90 days)
+  if (daysSinceUpdate > 90) {
+    console.log(`  ⚠️ Very old, consider removing`)
+  }
+})
+
+// 4. Remove confirmed unused insights
+const unusedInsights = ['id1', 'id2', 'id3']
+unusedInsights.forEach(id => {
+  remove_insight({ insightId: id })
+})
+```
+
+### Scenario 5: Remove After Workflow Deletion
+
+**Situation:** Source workflow deleted, insight no longer works.
+
+```javascript
+// Workflow was deleted, insights referencing it are now broken
+
+// 1. Find insights referencing deleted workflow
+const insights = list_insights()
+const brokenInsights = insights.filter(i =>
+  i.sources.some(s => s.workflowId === 'deleted-workflow-id')
+)
+
+console.log(`Found ${brokenInsights.length} broken insights`)
+
+// 2. Remove broken insights
+brokenInsights.forEach(insight => {
+  console.log(`Removing broken insight: ${insight.name}`)
+  remove_insight({ insightId: insight._id })
+})
+```
+
+## Before Removing
+
+### Export Insight Definition
+
+**Save query and sources:**
+```javascript
+const insights = list_insights()
+const target = insights.find(i => i._id === 'target-id')
+
+// Save insight definition
+const backup = {
+  name: target.name,
+  description: target.description,
+  public: target.public,
+  sources: target.sources,
+  query: target.query,
+  exportDate: new Date().toISOString()
+}
+
+console.log('Insight backup:')
+console.log(JSON.stringify(backup, null, 2))
+
+// Save to file or external storage
+// saveToFile('insight-backup.json', JSON.stringify(backup, null, 2))
+```
+
+### Export Current Data
+
+**Save insight results:**
+```javascript
+const data = get_insight_data({
+  insightId: 'target-id',
+  update: true  // Get fresh data
+})
+
+// Convert to objects
+const records = data.rows.map(row => {
+  const obj = {}
+  data.columns.forEach((col, i) => {
+    obj[col] = row[i]
+  })
+  return obj
+})
+
+// Save data
+console.log(JSON.stringify(records, null, 2))
+// saveToFile('insight-data.json', JSON.stringify(records, null, 2))
+```
+
+### Check Dependencies
+
+**Find if insight is used elsewhere:**
+```javascript
+// 1. Check if insight is public (might be shared)
+const insights = list_insights()
+const target = insights.find(i => i._id === 'target-id')
+
+if (target.public) {
+  console.warn('⚠️ This insight is PUBLIC - may have external users')
+}
+
+// 2. Check if insight has discussion
+if (target.discussion) {
+  console.warn('⚠️ Insight has discussion thread - will be deleted')
+}
+
+// 3. Document usage
+console.log('Insight usage check:')
+console.log('- Public:', target.public)
+console.log('- Created:', target.created)
+console.log('- Last calculated:', target.lastCalculated)
+```
+
+## After Removing
+
+### Verify Removal
+
+```javascript
+// 1. Remove insight
+remove_insight({ insightId: 'removed-id' })
+
+// 2. Verify it's gone
+const insights = list_insights()
+const stillExists = insights.find(i => i._id === 'removed-id')
+
+if (stillExists) {
+  console.error('❌ Insight still exists!')
+} else {
+  console.log('✅ Insight successfully removed')
+}
+
+// 3. Try to access (should fail)
+try {
+  get_insight_data({ insightId: 'removed-id' })
+  console.error('❌ Can still access insight!')
+} catch (error) {
+  console.log('✅ Insight not accessible (expected)')
+}
+```
+
+### Update Documentation
+
+After removing insights:
+- Update workspace documentation
+- Remove insight references from guides
+- Update team training materials
+- Archive insight specifications
+- Document removal reason and date
+
+### Clean Up Related Resources
+
+**Remove references:**
+```javascript
+// Update apps that referenced the insight
+// Remove dashboard widgets showing the insight
+// Update scheduled reports
+// Notify users who used the insight
+```
+
+## Best Practices
+
+### 1. Always Verify Before Removing
+
+**Bad:**
+```javascript
+// Removed without checking
+remove_insight({ insightId: 'some-id' })
+```
+
+**Good:**
+```javascript
+// 1. Verify insight exists and ownership
+const insights = list_insights()
+const target = insights.find(i => i._id === 'some-id')
+
+if (!target) {
+  console.error('Insight not found')
+  return
+}
+
+console.log('About to remove:', target.name)
+console.log('Owner:', target.isOwner ? 'You' : 'Someone else')
+
+// 2. Confirm and remove
+if (target.isOwner) {
+  remove_insight({ insightId: target._id })
+} else {
+  console.error('Cannot remove - not owner')
+}
+```
+
+### 2. Export Before Removing
+
+**Always backup important insights:**
+```javascript
+// 1. Export definition
+const insights = list_insights()
+const target = insights.find(i => i._id === 'target-id')
+const definition = {
+  name: target.name,
+  sources: target.sources,
+  query: target.query
+}
+console.log('Backup:', JSON.stringify(definition, null, 2))
+
+// 2. Export data
+const data = get_insight_data({ insightId: target._id })
+console.log(`Backing up ${data.rows.length} rows`)
+
+// 3. Then remove
+remove_insight({ insightId: target._id })
+```
+
+### 3. Use Descriptive Insight Names
+
+Makes identification easier:
+- ✅ "High Priority Tasks - Dec 2024"
+- ✅ "Test - Can Delete - Daily Report"
+- ✅ "DEPRECATED - Old Budget Report"
+- ❌ "Report 1"
+- ❌ "Query"
+
+### 4. Remove Test Insights Promptly
+
+Don't let test insights accumulate:
+```javascript
+// Regular cleanup schedule
+function cleanupTestInsights() {
+  const insights = list_insights()
+  const testInsights = insights.filter(i =>
+    i.name.toLowerCase().includes('test') ||
+    i.name.toLowerCase().includes('demo') ||
+    i.name.startsWith('TMP -')
+  )
+
+  testInsights.forEach(i => {
+    remove_insight({ insightId: i._id })
+    console.log(`Removed test insight: ${i.name}`)
+  })
+}
+```
+
+### 5. Communicate Before Removing
+
+**Notify team before removing shared insights:**
+- Send message in workspace discussion
+- Post in relevant channels
+- Update documentation
+- Provide migration path if replacing insight
+
+### 6. Consider Duplicating First
+
+**If unsure, duplicate before removing:**
+```javascript
+// 1. Get insight definition
+const insights = list_insights()
+const original = insights.find(i => i._id === 'original-id')
+
+// 2. Create copy with different name
+create_insight({
+  name: original.name + ' - Archive',
+  sources: original.sources,
+  query: original.query,
+  public: false  // Make archive private
+})
+
+// 3. Later remove original if archive works
+// remove_insight({ insightId: 'original-id' })
+```
+
+### 7. Document Removal
+
+Keep audit trail:
+```javascript
+console.log({
+  action: 'remove_insight',
+  insightId: 'insight-id',
+  insightName: 'Report Name',
+  reason: 'Replaced by v2',
+  date: new Date().toISOString(),
+  removedBy: 'user-id'
+})
+```
+
+### 8. Handle Broken Insights
+
+**Remove insights that reference deleted workflows:**
+```javascript
+// After deleting workflow, clean up insights
+const deletedWorkflowId = 'deleted-workflow-id'
+
+const insights = list_insights()
+const brokenInsights = insights.filter(i =>
+  i.sources.some(s => s.workflowId === deletedWorkflowId)
+)
+
+console.log(`Found ${brokenInsights.length} broken insights`)
+brokenInsights.forEach(i => {
+  console.log(`Removing: ${i.name}`)
+  remove_insight({ insightId: i._id })
+})
+```
+
+## Troubleshooting
+
+### Error: "Insight Not Found"
+
+**Cause:** Invalid insight ID or insight already deleted.
+
+**Solution:**
+
+```javascript
+// 1. List insights to verify
+const insights = list_insights()
+console.log('Available insights:')
+insights.forEach(i => {
+  console.log(`- ${i.name}: ${i._id}`)
+})
+
+// 2. Use correct ID
+remove_insight({ insightId: 'correct-id' })
+```
+
+### Error: "Permission Denied"
+
+**Cause:** Not insight owner or workspace admin.
+
+**Solutions:**
+
+1. **Check ownership:**
+```javascript
+const insights = list_insights()
+const target = insights.find(i => i._id === 'target-id')
+
+console.log('Owner:', target.owner)
+console.log('You are owner:', target.isOwner)
+console.log('You are admin:', target.isAdmin)
+```
+
+2. **Request removal from owner/admin**
+3. **Contact workspace administrator**
+
+### Insight Removed But Still Appears
+
+**Cause:** Cache not updated.
+
+**Solution:**
+
+```javascript
+// Refresh insight list
+const insights = list_insights()
+
+// Verify removal
+const stillExists = insights.find(i => i._id === 'removed-id')
+console.log('Still exists:', !!stillExists)
+```
+
+### Accidentally Removed Wrong Insight
+
+**Reality Check:** **Cannot be undone.**
+
+**Mitigation:**
+
+1. **If you have backup:**
+```javascript
+// Recreate from backup
+create_insight({
+  name: backup.name,
+  sources: backup.sources,
+  query: backup.query
+})
+// Note: Will have different ID
+```
+
+2. **If no backup:**
+   - Data is permanently lost
+   - Contact Hailer support (may have database backups)
+   - Implement backup procedures for future
+
+3. **Prevention:**
+   - Always verify insight ID before removing
+   - Use descriptive insight names
+   - Export definitions before removal
+   - Test in development workspace first
+
+### Can't Find Insight to Remove
+
+**Cause:** Insight in different workspace or already removed.
+
+**Solution:**
+
+```javascript
+// 1. Check current workspace
+const workspace = get_current_workspace()
+console.log('Current workspace:', workspace.name)
+
+// 2. List insights in this workspace
+const insights = list_insights()
+console.log(`Found ${insights.length} insights`)
+
+// 3. Search by name
+const target = insights.find(i =>
+  i.name.toLowerCase().includes('search term')
+)
+
+if (target) {
+  console.log('Found:', target._id)
+} else {
+  console.log('Not found in current workspace')
+}
+```
+
+## Integration with Other Tools
+
+### With create_insight
+
+Replace pattern:
+
+```javascript
+// 1. Create new version
+const newInsight = create_insight({
+  name: 'Report v2',
+  sources: [...],
+  query: '...'
+})
+
+// 2. Verify it works
+const data = get_insight_data({
+  insightId: newInsight.insightId
+})
+console.log(`✅ New insight: ${data.rows.length} rows`)
+
+// 3. Remove old version
+remove_insight({ insightId: 'old-version-id' })
+```
+
+### With list_insights
+
+Find and remove:
+
+```javascript
+// 1. List insights
+const insights = list_insights()
+
+// 2. Find by name
+const target = insights.find(i => i.name === 'Old Report')
+
+// 3. Remove
+if (target) {
+  remove_insight({ insightId: target._id })
+} else {
+  console.log('Insight not found')
+}
+```
+
+### With get_insight_data
+
+Backup before removal:
+
+```javascript
+// 1. Get data
+const data = get_insight_data({
+  insightId: 'target-id',
+  update: true
+})
+
+// 2. Save data
+console.log(`Backing up ${data.rows.length} rows`)
+const backup = JSON.stringify(data, null, 2)
+
+// 3. Remove insight
+remove_insight({ insightId: 'target-id' })
+```
+
+### With preview_insight
+
+Test before recreating:
+
+```javascript
+// 1. Get insight definition before removal
+const insights = list_insights()
+const target = insights.find(i => i._id === 'target-id')
+
+// 2. Export definition
+const definition = {
+  sources: target.sources,
+  query: target.query
+}
+
+// 3. Remove insight
+remove_insight({ insightId: target._id })
+
+// 4. Later, test if you want to recreate
+preview_insight({
+  sources: definition.sources,
+  query: definition.query
+})
+
+// 5. Recreate if test succeeds
+create_insight({
+  name: 'Recreated Report',
+  sources: definition.sources,
+  query: definition.query
+})
+```
+
+## Summary
+
+**Key Takeaways:**
+1. ⚠️ **Permanent deletion** - Cannot be undone
+2. 🔒 **Owner or admin only** - Permission required
+3. 🗑️ **Complete removal** - Definition, data, discussion deleted
+4. 💾 **Export first** - Backup important insights
+5. ✅ **Verify twice** - Double-check insight ID
+6. 📢 **Communicate** - Inform users before removing shared insights
+7. 🔄 **Consider alternatives** - Duplicate or update instead of remove
+
+**Quick Decision Tree:**
+
+```
+Need to remove insight?
+│
+├─ Contains important data? → Export first, then remove
+├─ Used by others? → Notify team first, then remove
+├─ Might need later? → Duplicate before removing
+├─ Test/demo insight? → Remove immediately
+├─ Broken/outdated? → Remove after documenting reason
+└─ Sure about removal? → Verify ID and remove
+```
+
+## Additional Resources
+
+- See `create-insight-skill` for creating insights
+- See `preview-insight-skill` for testing queries
+- See `get-insight-data-skill` for executing insights
+- See `insight-api` skill for comprehensive Insight API documentation
+- Use `list_insights` to view all insights
+- Use `get_insight_data` to backup data before removal