@hailer/mcp 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (163) hide show
  1. package/.claude/commands/tool-builder.md +37 -0
  2. package/.claude/commands/ws-pull.md +44 -0
  3. package/.claude/settings.json +8 -0
  4. package/.claude/settings.local.json +49 -0
  5. package/.claude/skills/activity-api/SKILL.md +96 -0
  6. package/.claude/skills/activity-api/references/activity-endpoints.md +845 -0
  7. package/.claude/skills/add-app-member-skill/SKILL.md +977 -0
  8. package/.claude/skills/agent-building/SKILL.md +243 -0
  9. package/.claude/skills/agent-building/references/architecture-patterns.md +446 -0
  10. package/.claude/skills/agent-building/references/code-examples.md +587 -0
  11. package/.claude/skills/agent-building/references/implementation-guide.md +619 -0
  12. package/.claude/skills/app-api/SKILL.md +219 -0
  13. package/.claude/skills/app-api/references/app-endpoints.md +759 -0
  14. package/.claude/skills/building-hailer-apps-skill/SKILL.md +548 -0
  15. package/.claude/skills/create-app-skill/SKILL.md +1101 -0
  16. package/.claude/skills/create-insight-skill/SKILL.md +1317 -0
  17. package/.claude/skills/get-insight-data-skill/SKILL.md +1053 -0
  18. package/.claude/skills/hailer-api/SKILL.md +283 -0
  19. package/.claude/skills/hailer-api/references/activities.md +620 -0
  20. package/.claude/skills/hailer-api/references/authentication.md +216 -0
  21. package/.claude/skills/hailer-api/references/datasets.md +437 -0
  22. package/.claude/skills/hailer-api/references/files.md +301 -0
  23. package/.claude/skills/hailer-api/references/insights.md +469 -0
  24. package/.claude/skills/hailer-api/references/workflows.md +720 -0
  25. package/.claude/skills/hailer-api/references/workspaces-users.md +445 -0
  26. package/.claude/skills/insight-api/SKILL.md +185 -0
  27. package/.claude/skills/insight-api/references/insight-endpoints.md +514 -0
  28. package/.claude/skills/install-workflow-skill/SKILL.md +1056 -0
  29. package/.claude/skills/list-apps-skill/SKILL.md +1010 -0
  30. package/.claude/skills/list-workflows-minimal-skill/SKILL.md +992 -0
  31. package/.claude/skills/local-first-skill/SKILL.md +570 -0
  32. package/.claude/skills/mcp-tools/SKILL.md +419 -0
  33. package/.claude/skills/mcp-tools/references/api-endpoints.md +499 -0
  34. package/.claude/skills/mcp-tools/references/data-structures.md +554 -0
  35. package/.claude/skills/mcp-tools/references/implementation-patterns.md +717 -0
  36. package/.claude/skills/preview-insight-skill/SKILL.md +1290 -0
  37. package/.claude/skills/publish-hailer-app-skill/SKILL.md +453 -0
  38. package/.claude/skills/remove-app-member-skill/SKILL.md +671 -0
  39. package/.claude/skills/remove-app-skill/SKILL.md +985 -0
  40. package/.claude/skills/remove-insight-skill/SKILL.md +1011 -0
  41. package/.claude/skills/remove-workflow-skill/SKILL.md +920 -0
  42. package/.claude/skills/scaffold-hailer-app-skill/SKILL.md +1034 -0
  43. package/.claude/skills/skill-testing/README.md +137 -0
  44. package/.claude/skills/skill-testing/SKILL.md +348 -0
  45. package/.claude/skills/skill-testing/references/test-patterns.md +705 -0
  46. package/.claude/skills/skill-testing/references/testing-guide.md +603 -0
  47. package/.claude/skills/skill-testing/references/validation-checklist.md +537 -0
  48. package/.claude/skills/tool-builder/SKILL.md +328 -0
  49. package/.claude/skills/update-app-skill/SKILL.md +970 -0
  50. package/.claude/skills/update-workflow-field-skill/SKILL.md +1098 -0
  51. package/.env.example +81 -0
  52. package/.mcp.json +13 -0
  53. package/README.md +297 -0
  54. package/dist/app.d.ts +4 -0
  55. package/dist/app.js +74 -0
  56. package/dist/cli.d.ts +3 -0
  57. package/dist/cli.js +5 -0
  58. package/dist/client/adaptive-documentation-bot.d.ts +108 -0
  59. package/dist/client/adaptive-documentation-bot.js +475 -0
  60. package/dist/client/adaptive-documentation-types.d.ts +66 -0
  61. package/dist/client/adaptive-documentation-types.js +9 -0
  62. package/dist/client/agent-activity-bot.d.ts +51 -0
  63. package/dist/client/agent-activity-bot.js +166 -0
  64. package/dist/client/agent-tracker.d.ts +499 -0
  65. package/dist/client/agent-tracker.js +659 -0
  66. package/dist/client/description-updater.d.ts +56 -0
  67. package/dist/client/description-updater.js +259 -0
  68. package/dist/client/log-parser.d.ts +72 -0
  69. package/dist/client/log-parser.js +387 -0
  70. package/dist/client/mcp-client.d.ts +50 -0
  71. package/dist/client/mcp-client.js +532 -0
  72. package/dist/client/message-processor.d.ts +35 -0
  73. package/dist/client/message-processor.js +352 -0
  74. package/dist/client/multi-bot-manager.d.ts +24 -0
  75. package/dist/client/multi-bot-manager.js +74 -0
  76. package/dist/client/providers/anthropic-provider.d.ts +19 -0
  77. package/dist/client/providers/anthropic-provider.js +631 -0
  78. package/dist/client/providers/llm-provider.d.ts +47 -0
  79. package/dist/client/providers/llm-provider.js +367 -0
  80. package/dist/client/providers/openai-provider.d.ts +23 -0
  81. package/dist/client/providers/openai-provider.js +621 -0
  82. package/dist/client/simple-llm-caller.d.ts +19 -0
  83. package/dist/client/simple-llm-caller.js +100 -0
  84. package/dist/client/skill-generator.d.ts +81 -0
  85. package/dist/client/skill-generator.js +386 -0
  86. package/dist/client/test-adaptive-bot.d.ts +9 -0
  87. package/dist/client/test-adaptive-bot.js +82 -0
  88. package/dist/client/token-pricing.d.ts +38 -0
  89. package/dist/client/token-pricing.js +127 -0
  90. package/dist/client/token-tracker.d.ts +232 -0
  91. package/dist/client/token-tracker.js +457 -0
  92. package/dist/client/token-usage-bot.d.ts +53 -0
  93. package/dist/client/token-usage-bot.js +153 -0
  94. package/dist/client/tool-executor.d.ts +69 -0
  95. package/dist/client/tool-executor.js +159 -0
  96. package/dist/client/tool-schema-loader.d.ts +60 -0
  97. package/dist/client/tool-schema-loader.js +178 -0
  98. package/dist/client/types.d.ts +69 -0
  99. package/dist/client/types.js +7 -0
  100. package/dist/config.d.ts +162 -0
  101. package/dist/config.js +296 -0
  102. package/dist/core.d.ts +26 -0
  103. package/dist/core.js +147 -0
  104. package/dist/lib/context-manager.d.ts +111 -0
  105. package/dist/lib/context-manager.js +431 -0
  106. package/dist/lib/logger.d.ts +74 -0
  107. package/dist/lib/logger.js +277 -0
  108. package/dist/lib/materialize.d.ts +3 -0
  109. package/dist/lib/materialize.js +101 -0
  110. package/dist/lib/normalizedName.d.ts +7 -0
  111. package/dist/lib/normalizedName.js +48 -0
  112. package/dist/lib/prompt-length-manager.d.ts +81 -0
  113. package/dist/lib/prompt-length-manager.js +457 -0
  114. package/dist/lib/terminal-prompt.d.ts +9 -0
  115. package/dist/lib/terminal-prompt.js +108 -0
  116. package/dist/mcp/UserContextCache.d.ts +56 -0
  117. package/dist/mcp/UserContextCache.js +163 -0
  118. package/dist/mcp/auth.d.ts +2 -0
  119. package/dist/mcp/auth.js +29 -0
  120. package/dist/mcp/hailer-clients.d.ts +42 -0
  121. package/dist/mcp/hailer-clients.js +246 -0
  122. package/dist/mcp/signal-handler.d.ts +45 -0
  123. package/dist/mcp/signal-handler.js +317 -0
  124. package/dist/mcp/tool-registry.d.ts +100 -0
  125. package/dist/mcp/tool-registry.js +306 -0
  126. package/dist/mcp/tools/activity.d.ts +15 -0
  127. package/dist/mcp/tools/activity.js +955 -0
  128. package/dist/mcp/tools/app.d.ts +20 -0
  129. package/dist/mcp/tools/app.js +1488 -0
  130. package/dist/mcp/tools/discussion.d.ts +19 -0
  131. package/dist/mcp/tools/discussion.js +950 -0
  132. package/dist/mcp/tools/file.d.ts +15 -0
  133. package/dist/mcp/tools/file.js +119 -0
  134. package/dist/mcp/tools/insight.d.ts +17 -0
  135. package/dist/mcp/tools/insight.js +806 -0
  136. package/dist/mcp/tools/skill.d.ts +10 -0
  137. package/dist/mcp/tools/skill.js +279 -0
  138. package/dist/mcp/tools/user.d.ts +10 -0
  139. package/dist/mcp/tools/user.js +108 -0
  140. package/dist/mcp/tools/workflow-template.d.ts +19 -0
  141. package/dist/mcp/tools/workflow-template.js +822 -0
  142. package/dist/mcp/tools/workflow.d.ts +18 -0
  143. package/dist/mcp/tools/workflow.js +1362 -0
  144. package/dist/mcp/utils/api-errors.d.ts +45 -0
  145. package/dist/mcp/utils/api-errors.js +160 -0
  146. package/dist/mcp/utils/data-transformers.d.ts +102 -0
  147. package/dist/mcp/utils/data-transformers.js +194 -0
  148. package/dist/mcp/utils/file-upload.d.ts +33 -0
  149. package/dist/mcp/utils/file-upload.js +148 -0
  150. package/dist/mcp/utils/hailer-api-client.d.ts +120 -0
  151. package/dist/mcp/utils/hailer-api-client.js +323 -0
  152. package/dist/mcp/utils/index.d.ts +13 -0
  153. package/dist/mcp/utils/index.js +39 -0
  154. package/dist/mcp/utils/logger.d.ts +42 -0
  155. package/dist/mcp/utils/logger.js +103 -0
  156. package/dist/mcp/utils/types.d.ts +286 -0
  157. package/dist/mcp/utils/types.js +7 -0
  158. package/dist/mcp/workspace-cache.d.ts +42 -0
  159. package/dist/mcp/workspace-cache.js +97 -0
  160. package/dist/mcp-server.d.ts +42 -0
  161. package/dist/mcp-server.js +280 -0
  162. package/package.json +56 -0
  163. package/tsconfig.json +23 -0
@@ -0,0 +1,1101 @@
1
+ ---
2
+ name: Creating Hailer Apps
3
+ description: Complete guide for creating Hailer app entries - use when setting up development or production apps
4
+ ---
5
+
6
+ # Creating Hailer Apps - Complete Guide
7
+
8
+ Complete reference for creating Hailer app entries in your workspace using the `create_app` MCP tool.
9
+
10
+ ## Table of Contents
11
+ 1. [Quick Reference](#quick-reference)
12
+ 2. [Overview](#overview)
13
+ 3. [Core Concepts](#core-concepts)
14
+ 4. [App Types](#app-types)
15
+ 5. [Basic Usage](#basic-usage)
16
+ 6. [App Properties](#app-properties)
17
+ 7. [Development vs Published](#development-vs-published)
18
+ 8. [Common Scenarios](#common-scenarios)
19
+ 9. [After Creation](#after-creation)
20
+ 10. [Best Practices](#best-practices)
21
+ 11. [Troubleshooting](#troubleshooting)
22
+
23
+ ## Quick Reference
24
+
25
+ **Create Development App (localhost):**
26
+
27
+ ```javascript
28
+ create_app({
29
+ name: 'My App (Dev)',
30
+ description: 'Development version',
31
+ url: 'http://localhost:3000'
32
+ })
33
+ ```
34
+
35
+ **Create Published App (production):**
36
+
37
+ ```javascript
38
+ create_app({
39
+ name: 'My App',
40
+ description: 'Production version'
41
+ // No url - Hailer generates it
42
+ })
43
+ ```
44
+
45
+ **Create with Configuration:**
46
+
47
+ ```javascript
48
+ create_app({
49
+ name: 'Task Manager',
50
+ description: 'Custom task management app',
51
+ config: {
52
+ workflowId: 'tasks-workflow-id',
53
+ defaultView: 'kanban'
54
+ }
55
+ })
56
+ ```
57
+
58
+ **Response:**
59
+ ```javascript
60
+ {
61
+ appId: '68446dc05b30685f67c6fcd4', // Use this in manifest.json
62
+ name: 'My App',
63
+ url: 'https://apps.hailer.com/68446dc05b30685f67c6fcd4' // Generated for published apps
64
+ }
65
+ ```
66
+
67
+ **Key Requirements:**
68
+ - User must be workspace administrator
69
+ - App name is required
70
+ - Development apps need localhost URL
71
+ - Published apps have empty or no URL
72
+ - Save returned appId for manifest.json
73
+
74
+ ## Overview
75
+
76
+ **What are Hailer Apps?**
77
+
78
+ Hailer apps are custom web applications (React/TypeScript/vanilla JS) that run inside the Hailer workspace. They extend Hailer's functionality with custom UIs and workflows.
79
+
80
+ **Think of them as:**
81
+ - Custom widgets in Hailer
82
+ - Embedded web applications
83
+ - Extensions to Hailer UI
84
+ - Mini-apps within workspace
85
+
86
+ **What create_app Does:**
87
+ - Creates app entry in Hailer database
88
+ - Generates app ID for manifest.json
89
+ - Sets up app URL (dev or production)
90
+ - Configures app permissions
91
+ - Initializes app discussion
92
+
93
+ **What it Does NOT Do:**
94
+ - Does not create app code (use scaffold_hailer_app)
95
+ - Does not deploy app files (use publish_hailer_app)
96
+ - Does not share app (use add_app_member)
97
+ - Does not generate manifest.json (you create it)
98
+
99
+ ## Core Concepts
100
+
101
+ ### App Entry vs App Code
102
+
103
+ **App Entry (created by create_app):**
104
+ - Database record in Hailer
105
+ - Identifies the app
106
+ - Contains app metadata
107
+ - Provides app ID
108
+ - Manages permissions
109
+
110
+ **App Code (created separately):**
111
+ - React/TypeScript files
112
+ - User interface
113
+ - Business logic
114
+ - Deployed files (HTML, JS, CSS)
115
+
116
+ ### App Lifecycle
117
+
118
+ ```
119
+ 1. Create app entry (create_app)
120
+
121
+ 2. Scaffold app code (scaffold_hailer_app)
122
+
123
+ 3. Develop locally (npm run dev)
124
+
125
+ 4. Build app (npm run build)
126
+
127
+ 5. Publish app (publish_hailer_app)
128
+
129
+ 6. Share app (add_app_member)
130
+ ```
131
+
132
+ ### App ID and manifest.json
133
+
134
+ **Critical Connection:**
135
+
136
+ ```javascript
137
+ // 1. Create app entry
138
+ const result = create_app({
139
+ name: 'My App'
140
+ })
141
+
142
+ console.log('App ID:', result.appId)
143
+ // App ID: 68446dc05b30685f67c6fcd4
144
+
145
+ // 2. Use appId in manifest.json
146
+ // File: public/manifest.json
147
+ {
148
+ "author": "Your Name",
149
+ "appId": "68446dc05b30685f67c6fcd4", // From create_app
150
+ "config": {
151
+ "fields": { ... }
152
+ }
153
+ }
154
+ ```
155
+
156
+ **Without correct appId in manifest.json:**
157
+ - App won't load in Hailer
158
+ - Publishing will fail
159
+ - App shows as "not found"
160
+
161
+ ## App Types
162
+
163
+ ### Development Apps
164
+
165
+ **Purpose:** Local development and testing
166
+
167
+ **Characteristics:**
168
+ - URL points to localhost
169
+ - Code runs from dev server
170
+ - Hot reload enabled
171
+ - Instant changes
172
+ - Not accessible by others
173
+
174
+ **Example:**
175
+ ```javascript
176
+ create_app({
177
+ name: 'Task Manager (Dev)',
178
+ description: 'Development version for testing',
179
+ url: 'http://localhost:3000'
180
+ })
181
+ ```
182
+
183
+ **Use when:**
184
+ - Building new app
185
+ - Testing features
186
+ - Debugging issues
187
+ - Local development
188
+
189
+ ### Published Apps
190
+
191
+ **Purpose:** Production use by workspace users
192
+
193
+ **Characteristics:**
194
+ - URL empty or auto-generated by Hailer
195
+ - Code hosted on Hailer servers
196
+ - Requires build and publish
197
+ - Accessible by workspace
198
+ - Versioned deployments
199
+
200
+ **Example:**
201
+ ```javascript
202
+ create_app({
203
+ name: 'Task Manager',
204
+ description: 'Production task management app'
205
+ // No url - Hailer generates it
206
+ })
207
+ ```
208
+
209
+ **Use when:**
210
+ - Deploying to users
211
+ - Production release
212
+ - Shared workspace access
213
+ - Stable version ready
214
+
215
+ ### Why Two App Entries?
216
+
217
+ **Best Practice: Separate dev and production**
218
+
219
+ ```javascript
220
+ // Development app
221
+ create_app({
222
+ name: 'My App (Dev)',
223
+ url: 'http://localhost:3000'
224
+ })
225
+ // → Use during development
226
+
227
+ // Published app
228
+ create_app({
229
+ name: 'My App',
230
+ // No url
231
+ })
232
+ // → Use for production
233
+ ```
234
+
235
+ **Benefits:**
236
+ - Isolate dev from production
237
+ - Safe testing without affecting users
238
+ - Clear separation of environments
239
+ - Different appIds in manifests
240
+
241
+ ## Basic Usage
242
+
243
+ ### Example 1: Create Development App
244
+
245
+ ```javascript
246
+ // Step 1: Create app entry for development
247
+ const devApp = create_app({
248
+ name: 'Football Lineup (Dev)',
249
+ description: 'Development version - points to localhost',
250
+ url: 'http://localhost:3000'
251
+ })
252
+
253
+ console.log('Development App Created:')
254
+ console.log('- App ID:', devApp.appId)
255
+ console.log('- URL:', devApp.url)
256
+
257
+ // Step 2: Save appId for manifest.json
258
+ // Update public/manifest.json with devApp.appId
259
+
260
+ // Step 3: Start dev server
261
+ // npm run dev
262
+
263
+ // Step 4: Open app in Hailer
264
+ // Navigate to Apps → Football Lineup (Dev)
265
+ ```
266
+
267
+ ### Example 2: Create Published App
268
+
269
+ ```javascript
270
+ // Step 1: Create app entry for production
271
+ const prodApp = create_app({
272
+ name: 'Football Lineup',
273
+ description: 'Interactive football team lineup manager'
274
+ })
275
+
276
+ console.log('Published App Created:')
277
+ console.log('- App ID:', prodApp.appId)
278
+ console.log('- URL:', prodApp.url) // Auto-generated
279
+
280
+ // Step 2: Update manifest.json with prodApp.appId
281
+ // Update public/manifest.json
282
+
283
+ // Step 3: Build and publish
284
+ // npm run build
285
+ // npm pack
286
+ // publish to production
287
+
288
+ // Step 4: Share with workspace
289
+ // add_app_member({ appId: prodApp.appId, member: 'network_...' })
290
+ ```
291
+
292
+ ### Example 3: Create with Configuration
293
+
294
+ ```javascript
295
+ // Create app with custom configuration
296
+ const app = create_app({
297
+ name: 'Project Dashboard',
298
+ description: 'Real-time project status dashboard',
299
+ config: {
300
+ workflowId: 'projects-workflow-id',
301
+ refreshInterval: 60,
302
+ theme: 'dark'
303
+ }
304
+ })
305
+
306
+ console.log('App created with config:', app.appId)
307
+ ```
308
+
309
+ ### Example 4: Specify Workspace
310
+
311
+ ```javascript
312
+ // Create app in specific workspace
313
+ const app = create_app({
314
+ workspaceId: 'specific-workspace-id',
315
+ name: 'Team Calendar',
316
+ description: 'Shared team calendar app'
317
+ })
318
+ ```
319
+
320
+ ## App Properties
321
+
322
+ ### Required Properties
323
+
324
+ **name** (string, required)
325
+ - Display name in Hailer
326
+ - Shows in Apps menu
327
+ - User-visible
328
+ - Should be descriptive
329
+
330
+ ```javascript
331
+ create_app({
332
+ name: 'Task Manager' // Required
333
+ })
334
+ ```
335
+
336
+ ### Optional Properties
337
+
338
+ **description** (string, optional)
339
+ - App description/purpose
340
+ - Helps users understand app
341
+ - Shows in app details
342
+
343
+ ```javascript
344
+ create_app({
345
+ name: 'Task Manager',
346
+ description: 'Manage and track team tasks with kanban view'
347
+ })
348
+ ```
349
+
350
+ **url** (string, optional)
351
+ - App URL
352
+ - For dev: localhost URL
353
+ - For published: empty or omit
354
+ - Hailer generates URL for published apps
355
+
356
+ ```javascript
357
+ // Development
358
+ create_app({
359
+ name: 'My App (Dev)',
360
+ url: 'http://localhost:3000'
361
+ })
362
+
363
+ // Published
364
+ create_app({
365
+ name: 'My App'
366
+ // url omitted
367
+ })
368
+ ```
369
+
370
+ **image** (string, optional)
371
+ - App icon/image ID
372
+ - Must be 24 characters
373
+ - References uploaded image
374
+
375
+ ```javascript
376
+ create_app({
377
+ name: 'Task Manager',
378
+ image: '68446dc05b30685f67c6fcd4' // 24 char image ID
379
+ })
380
+ ```
381
+
382
+ **config** (object, optional)
383
+ - Custom app configuration
384
+ - App-specific settings
385
+ - Passed to app at runtime
386
+
387
+ ```javascript
388
+ create_app({
389
+ name: 'Dashboard',
390
+ config: {
391
+ workflowId: 'workflow-id',
392
+ defaultView: 'table',
393
+ refreshInterval: 30,
394
+ theme: 'light'
395
+ }
396
+ })
397
+ ```
398
+
399
+ **workspaceId** (string, optional)
400
+ - Target workspace for app
401
+ - Defaults to current workspace
402
+ - Can use workspace name or ID
403
+
404
+ ```javascript
405
+ create_app({
406
+ workspaceId: 'workspace-id',
407
+ name: 'App Name'
408
+ })
409
+ ```
410
+
411
+ ## Development vs Published
412
+
413
+ ### Development Apps Setup
414
+
415
+ **Complete workflow:**
416
+
417
+ ```javascript
418
+ // 1. Create dev app entry
419
+ const devApp = create_app({
420
+ name: 'My App (Dev)',
421
+ description: 'Development version',
422
+ url: 'http://localhost:3000'
423
+ })
424
+
425
+ // 2. Scaffold app code (if not already done)
426
+ scaffold_hailer_app({
427
+ projectName: 'my-app',
428
+ template: 'react-ts'
429
+ })
430
+
431
+ // 3. Update manifest.json
432
+ // File: my-app/public/manifest.json
433
+ {
434
+ "author": "Your Name",
435
+ "appId": "DEV_APP_ID_HERE", // Use devApp.appId
436
+ "config": {
437
+ "fields": {
438
+ "workflowId": {
439
+ "type": "string",
440
+ "default": "workflow-id"
441
+ }
442
+ }
443
+ }
444
+ }
445
+
446
+ // 4. Start dev server
447
+ // cd my-app
448
+ // npm run dev
449
+
450
+ // 5. Access in Hailer
451
+ // Apps menu → My App (Dev)
452
+ ```
453
+
454
+ ### Published Apps Setup
455
+
456
+ **Complete workflow:**
457
+
458
+ ```javascript
459
+ // 1. Create published app entry
460
+ const prodApp = create_app({
461
+ name: 'My App',
462
+ description: 'Production version'
463
+ // No url
464
+ })
465
+
466
+ // 2. Update manifest.json for production
467
+ // File: my-app/public/manifest.json
468
+ {
469
+ "author": "Your Name",
470
+ "appId": "PROD_APP_ID_HERE", // Use prodApp.appId
471
+ "config": {
472
+ "fields": {
473
+ "workflowId": {
474
+ "type": "string",
475
+ "default": "workflow-id"
476
+ }
477
+ }
478
+ }
479
+ }
480
+
481
+ // 3. Build app
482
+ // npm run build
483
+
484
+ // 4. Package app
485
+ // npm pack
486
+
487
+ // 5. Publish to production
488
+ // publish_hailer_app({
489
+ // email: 'your@email.com',
490
+ // password: 'password',
491
+ // projectDirectory: '/path/to/my-app'
492
+ // })
493
+
494
+ // 6. Share with workspace
495
+ // add_app_member({
496
+ // appId: prodApp.appId,
497
+ // member: 'network_workspace-id'
498
+ // })
499
+ ```
500
+
501
+ ## Common Scenarios
502
+
503
+ ### Scenario 1: New App Development
504
+
505
+ **Goal:** Create new app from scratch.
506
+
507
+ ```javascript
508
+ // Step 1: Create dev app entry
509
+ const devApp = create_app({
510
+ name: 'Customer Portal (Dev)',
511
+ description: 'Development version',
512
+ url: 'http://localhost:3000'
513
+ })
514
+
515
+ // Step 2: Scaffold app
516
+ scaffold_hailer_app({
517
+ projectName: 'customer-portal',
518
+ template: 'react-ts'
519
+ })
520
+
521
+ // Step 3: Update manifest with dev app ID
522
+ // Edit customer-portal/public/manifest.json
523
+ // Set appId to devApp.appId
524
+
525
+ // Step 4: Start developing
526
+ // cd customer-portal
527
+ // npm run dev
528
+
529
+ console.log('✅ Development setup complete')
530
+ console.log('App ID:', devApp.appId)
531
+ console.log('Start dev server and open in Hailer')
532
+ ```
533
+
534
+ ### Scenario 2: Deploy to Production
535
+
536
+ **Goal:** Take dev app to production.
537
+
538
+ ```javascript
539
+ // Already have dev app, now create production
540
+
541
+ // Step 1: Create published app entry
542
+ const prodApp = create_app({
543
+ name: 'Customer Portal',
544
+ description: 'Customer-facing portal for order management'
545
+ })
546
+
547
+ // Step 2: Update manifest for production
548
+ // Edit customer-portal/public/manifest.json
549
+ // Change appId to prodApp.appId
550
+
551
+ // Step 3: Build and publish
552
+ // npm run build
553
+ // npm pack
554
+ // Publish using publish_hailer_app
555
+
556
+ // Step 4: Share with workspace
557
+ add_app_member({
558
+ appId: prodApp.appId,
559
+ member: 'network_workspace-id'
560
+ })
561
+
562
+ console.log('✅ Production deployment complete')
563
+ console.log('Production App ID:', prodApp.appId)
564
+ ```
565
+
566
+ ### Scenario 3: Multiple Environments
567
+
568
+ **Goal:** Maintain dev, staging, and production.
569
+
570
+ ```javascript
571
+ // Create app entries for each environment
572
+
573
+ // Development
574
+ const devApp = create_app({
575
+ name: 'My App (Dev)',
576
+ description: 'Development environment',
577
+ url: 'http://localhost:3000'
578
+ })
579
+
580
+ // Staging
581
+ const stagingApp = create_app({
582
+ name: 'My App (Staging)',
583
+ description: 'Staging environment for testing'
584
+ })
585
+
586
+ // Production
587
+ const prodApp = create_app({
588
+ name: 'My App',
589
+ description: 'Production environment'
590
+ })
591
+
592
+ console.log('Environment App IDs:')
593
+ console.log('- Dev:', devApp.appId)
594
+ console.log('- Staging:', stagingApp.appId)
595
+ console.log('- Production:', prodApp.appId)
596
+
597
+ // Use different appIds in manifest.json for each environment
598
+ ```
599
+
600
+ ### Scenario 4: App with Custom Configuration
601
+
602
+ **Goal:** Create app with specific configuration.
603
+
604
+ ```javascript
605
+ // Create app with workflow-specific config
606
+ const app = create_app({
607
+ name: 'Sales Dashboard',
608
+ description: 'Real-time sales metrics and pipeline',
609
+ config: {
610
+ // Workflow IDs
611
+ dealsWorkflowId: 'deals-workflow-id',
612
+ contactsWorkflowId: 'contacts-workflow-id',
613
+
614
+ // Display settings
615
+ defaultView: 'pipeline',
616
+ refreshInterval: 60,
617
+
618
+ // Features
619
+ features: {
620
+ exportEnabled: true,
621
+ notificationsEnabled: true
622
+ },
623
+
624
+ // Theming
625
+ theme: {
626
+ primaryColor: '#007bff',
627
+ chartType: 'bar'
628
+ }
629
+ }
630
+ })
631
+
632
+ console.log('App created with config:', app.appId)
633
+
634
+ // Configuration accessible in app via useHailer hook
635
+ ```
636
+
637
+ ### Scenario 5: Recreate Deleted App
638
+
639
+ **Goal:** Recreate app that was accidentally deleted.
640
+
641
+ ```javascript
642
+ // App was deleted, need to recreate
643
+
644
+ // Step 1: Create new app entry (will have different ID)
645
+ const newApp = create_app({
646
+ name: 'Recovered App',
647
+ description: 'Recreated after deletion'
648
+ })
649
+
650
+ // Step 2: Update manifest.json with new appId
651
+ // Edit manifest.json
652
+ // Change appId to newApp.appId
653
+
654
+ // Step 3: Rebuild and republish
655
+ // npm run build
656
+ // npm pack
657
+ // Publish again
658
+
659
+ console.log('⚠️ New app ID:', newApp.appId)
660
+ console.log('Must update manifest.json and republish')
661
+ ```
662
+
663
+ ## After Creation
664
+
665
+ ### Update manifest.json
666
+
667
+ **Critical step:**
668
+
669
+ ```json
670
+ {
671
+ "author": "Your Name",
672
+ "appId": "APP_ID_FROM_CREATE_APP",
673
+ "config": {
674
+ "fields": {
675
+ "workflowId": {
676
+ "type": "string",
677
+ "default": "your-workflow-id"
678
+ }
679
+ }
680
+ }
681
+ }
682
+ ```
683
+
684
+ **Location:** `public/manifest.json` in your app directory
685
+
686
+ **Verification:**
687
+ ```javascript
688
+ // Check manifest has correct appId
689
+ const fs = require('fs')
690
+ const manifest = JSON.parse(fs.readFileSync('public/manifest.json', 'utf8'))
691
+ console.log('Manifest appId:', manifest.appId)
692
+
693
+ // Should match app entry
694
+ const apps = list_apps()
695
+ const app = apps.find(a => a._id === manifest.appId)
696
+ console.log('App exists:', !!app)
697
+ ```
698
+
699
+ ### Verify Creation
700
+
701
+ ```javascript
702
+ // 1. Create app
703
+ const app = create_app({
704
+ name: 'My App'
705
+ })
706
+
707
+ // 2. Verify it appears in list
708
+ const apps = list_apps()
709
+ const created = apps.find(a => a._id === app.appId)
710
+
711
+ if (created) {
712
+ console.log('✅ App created successfully')
713
+ console.log('Name:', created.name)
714
+ console.log('ID:', created._id)
715
+ } else {
716
+ console.log('❌ App not found in list')
717
+ }
718
+ ```
719
+
720
+ ### Next Steps
721
+
722
+ **After creating app entry:**
723
+
724
+ 1. **Update manifest.json** with appId
725
+ 2. **For dev apps:** Start dev server (`npm run dev`)
726
+ 3. **For published apps:** Build and publish
727
+ 4. **Share app** with users (`add_app_member`)
728
+ 5. **Test app** in Hailer workspace
729
+ 6. **Document app** configuration and usage
730
+
731
+ ## Best Practices
732
+
733
+ ### 1. Use Descriptive Names
734
+
735
+ **Bad:**
736
+ ```javascript
737
+ create_app({ name: 'App 1' })
738
+ create_app({ name: 'Test' })
739
+ ```
740
+
741
+ **Good:**
742
+ ```javascript
743
+ create_app({ name: 'Task Manager (Dev)' })
744
+ create_app({ name: 'Customer Portal' })
745
+ create_app({ name: 'Sales Dashboard - Production' })
746
+ ```
747
+
748
+ ### 2. Separate Dev and Production
749
+
750
+ **Always maintain separate app entries:**
751
+
752
+ ```javascript
753
+ // Development
754
+ const devApp = create_app({
755
+ name: 'My App (Dev)',
756
+ url: 'http://localhost:3000'
757
+ })
758
+
759
+ // Production
760
+ const prodApp = create_app({
761
+ name: 'My App'
762
+ // No url
763
+ })
764
+ ```
765
+
766
+ ### 3. Include Descriptions
767
+
768
+ ```javascript
769
+ create_app({
770
+ name: 'Project Tracker',
771
+ description: 'Track project milestones, tasks, and team progress with real-time updates'
772
+ })
773
+ ```
774
+
775
+ ### 4. Save App IDs
776
+
777
+ ```javascript
778
+ // Save app IDs for reference
779
+ const apps = {
780
+ dev: create_app({
781
+ name: 'My App (Dev)',
782
+ url: 'http://localhost:3000'
783
+ }),
784
+ prod: create_app({
785
+ name: 'My App'
786
+ })
787
+ }
788
+
789
+ console.log('App IDs:')
790
+ console.log('- Dev:', apps.dev.appId)
791
+ console.log('- Prod:', apps.prod.appId)
792
+
793
+ // Save to config file
794
+ // saveToFile('app-ids.json', JSON.stringify(apps, null, 2))
795
+ ```
796
+
797
+ ### 5. Use Configuration for Flexibility
798
+
799
+ ```javascript
800
+ create_app({
801
+ name: 'Dashboard',
802
+ config: {
803
+ // Don't hardcode workflow IDs in app code
804
+ // Use config instead
805
+ workflowId: 'workflow-id',
806
+
807
+ // Feature flags
808
+ features: {
809
+ exportEnabled: true,
810
+ darkModeEnabled: true
811
+ }
812
+ }
813
+ })
814
+ ```
815
+
816
+ ### 6. Verify Before Publishing
817
+
818
+ ```javascript
819
+ // 1. Create app entry
820
+ const app = create_app({
821
+ name: 'My App'
822
+ })
823
+
824
+ // 2. Update manifest.json
825
+
826
+ // 3. Build app
827
+ // npm run build
828
+
829
+ // 4. Verify manifest.json in dist/
830
+ const distManifest = readManifest('dist/manifest.json')
831
+ if (distManifest.appId !== app.appId) {
832
+ console.error('❌ Manifest appId mismatch!')
833
+ return
834
+ }
835
+
836
+ // 5. Publish
837
+ // publish_hailer_app(...)
838
+ ```
839
+
840
+ ### 7. Document App Configuration
841
+
842
+ ```javascript
843
+ create_app({
844
+ name: 'Sales Dashboard',
845
+ description: `
846
+ Sales metrics dashboard
847
+
848
+ Configuration:
849
+ - dealsWorkflowId: Workflow ID for deals
850
+ - refreshInterval: Update frequency in seconds
851
+ - defaultView: 'pipeline' | 'table' | 'chart'
852
+ `,
853
+ config: {
854
+ dealsWorkflowId: 'workflow-id',
855
+ refreshInterval: 60,
856
+ defaultView: 'pipeline'
857
+ }
858
+ })
859
+ ```
860
+
861
+ ## Troubleshooting
862
+
863
+ ### Error: "Permission Denied"
864
+
865
+ **Cause:** User is not workspace administrator.
866
+
867
+ **Solution:**
868
+ - Contact workspace administrator
869
+ - Request admin permissions
870
+ - Only admins can create apps
871
+
872
+ ### App Created But Not Visible
873
+
874
+ **Causes:**
875
+ 1. Wrong workspace
876
+ 2. Not shared with you
877
+ 3. Cache not refreshed
878
+
879
+ **Solutions:**
880
+
881
+ ```javascript
882
+ // 1. Check current workspace
883
+ const workspace = get_current_workspace()
884
+ console.log('Current workspace:', workspace.name)
885
+
886
+ // 2. List apps
887
+ const apps = list_apps()
888
+ console.log('Found apps:', apps.length)
889
+
890
+ // 3. Search by name
891
+ const app = apps.find(a => a.name === 'My App')
892
+ if (app) {
893
+ console.log('Found:', app._id)
894
+ } else {
895
+ console.log('Not found')
896
+ }
897
+ ```
898
+
899
+ ### App Shows "Not Found" in Hailer
900
+
901
+ **Cause:** manifest.json has wrong appId.
902
+
903
+ **Solution:**
904
+
905
+ ```javascript
906
+ // 1. Get correct app ID
907
+ const apps = list_apps()
908
+ const app = apps.find(a => a.name === 'My App')
909
+ console.log('Correct app ID:', app._id)
910
+
911
+ // 2. Update manifest.json
912
+ // Edit public/manifest.json
913
+ // Set "appId": "correct-app-id"
914
+
915
+ // 3. Rebuild app
916
+ // npm run build
917
+
918
+ // 4. Republish
919
+ // publish_hailer_app(...)
920
+ ```
921
+
922
+ ### Multiple Apps with Same Name
923
+
924
+ **Problem:** Created multiple apps, unsure which is which.
925
+
926
+ **Solution:**
927
+
928
+ ```javascript
929
+ // List all apps with details
930
+ const apps = list_apps()
931
+ apps.filter(a => a.name.includes('My App')).forEach(app => {
932
+ console.log('---')
933
+ console.log('Name:', app.name)
934
+ console.log('ID:', app._id)
935
+ console.log('URL:', app.url || 'None (published)')
936
+ console.log('Created:', app.created)
937
+ })
938
+
939
+ // Use list_apps to identify, then remove_app for unwanted ones
940
+ ```
941
+
942
+ ### App Created in Wrong Workspace
943
+
944
+ **Problem:** Created app in wrong workspace.
945
+
946
+ **Solution:**
947
+
948
+ ```javascript
949
+ // Cannot move apps between workspaces
950
+ // Must delete and recreate
951
+
952
+ // 1. Remove app from wrong workspace
953
+ remove_app({
954
+ appId: 'wrong-workspace-app-id'
955
+ })
956
+
957
+ // 2. Switch to correct workspace or specify it
958
+ const app = create_app({
959
+ workspaceId: 'correct-workspace-id',
960
+ name: 'My App'
961
+ })
962
+
963
+ // 3. Update manifest.json with new appId
964
+ ```
965
+
966
+ ## Integration with Other Tools
967
+
968
+ ### With scaffold_hailer_app
969
+
970
+ Create app then scaffold:
971
+
972
+ ```javascript
973
+ // 1. Create app entry first
974
+ const app = create_app({
975
+ name: 'My App (Dev)',
976
+ url: 'http://localhost:3000'
977
+ })
978
+
979
+ // 2. Scaffold app code
980
+ scaffold_hailer_app({
981
+ projectName: 'my-app',
982
+ template: 'react-ts'
983
+ })
984
+
985
+ // 3. Update manifest with app ID
986
+ // Edit my-app/public/manifest.json
987
+ // Set appId to app.appId
988
+ ```
989
+
990
+ ### With publish_hailer_app
991
+
992
+ Create then publish:
993
+
994
+ ```javascript
995
+ // 1. Create app entry
996
+ const app = create_app({
997
+ name: 'My App'
998
+ })
999
+
1000
+ // 2. Update manifest
1001
+ // Edit public/manifest.json with app.appId
1002
+
1003
+ // 3. Publish
1004
+ publish_hailer_app({
1005
+ email: 'your@email.com',
1006
+ password: 'password',
1007
+ projectDirectory: '/path/to/app'
1008
+ })
1009
+ ```
1010
+
1011
+ ### With add_app_member
1012
+
1013
+ Create then share:
1014
+
1015
+ ```javascript
1016
+ // 1. Create app
1017
+ const app = create_app({
1018
+ name: 'Team Dashboard'
1019
+ })
1020
+
1021
+ // 2. Share with workspace
1022
+ add_app_member({
1023
+ appId: app.appId,
1024
+ member: 'network_workspace-id'
1025
+ })
1026
+
1027
+ // 3. Share with specific team
1028
+ add_app_member({
1029
+ appId: app.appId,
1030
+ member: 'team_team-id'
1031
+ })
1032
+ ```
1033
+
1034
+ ### With list_apps
1035
+
1036
+ Create and verify:
1037
+
1038
+ ```javascript
1039
+ // 1. Create app
1040
+ const app = create_app({
1041
+ name: 'My App'
1042
+ })
1043
+
1044
+ // 2. Verify creation
1045
+ const apps = list_apps()
1046
+ const created = apps.find(a => a._id === app.appId)
1047
+
1048
+ console.log('Verified:', !!created)
1049
+ ```
1050
+
1051
+ ### With update_app
1052
+
1053
+ Create then modify:
1054
+
1055
+ ```javascript
1056
+ // 1. Create app
1057
+ const app = create_app({
1058
+ name: 'My App'
1059
+ })
1060
+
1061
+ // 2. Later, update name or description
1062
+ update_app({
1063
+ appId: app.appId,
1064
+ name: 'My App - Updated',
1065
+ description: 'Updated description'
1066
+ })
1067
+ ```
1068
+
1069
+ ## Summary
1070
+
1071
+ **Key Takeaways:**
1072
+ 1. 🏗️ **Creates app entry** - Database record, not code
1073
+ 2. 🔑 **Returns appId** - Use in manifest.json
1074
+ 3. 🔒 **Admin only** - Requires workspace administrator
1075
+ 4. 🖥️ **Dev vs Published** - Separate entries for each environment
1076
+ 5. ⚙️ **Configuration** - Pass settings to app
1077
+ 6. 📱 **Next steps** - Update manifest, build, publish, share
1078
+ 7. ✅ **Verify manifest** - Ensure appId matches
1079
+
1080
+ **Quick Decision Tree:**
1081
+
1082
+ ```
1083
+ Creating Hailer app?
1084
+
1085
+ ├─ Development? → Use localhost URL
1086
+ ├─ Production? → Omit URL (auto-generated)
1087
+ ├─ Need config? → Add config object
1088
+ ├─ Different workspace? → Specify workspaceId
1089
+ ├─ After creation? → Update manifest.json with appId
1090
+ └─ Ready to publish? → Build and use publish_hailer_app
1091
+ ```
1092
+
1093
+ ## Additional Resources
1094
+
1095
+ - See `publish-hailer-app-skill` for complete publishing guide
1096
+ - See `scaffold-hailer-app-skill` for generating app code
1097
+ - See `update-app-skill` for modifying apps
1098
+ - See `add-app-member-skill` for sharing apps
1099
+ - See `remove-app-skill` for deleting apps
1100
+ - See `app-api` skill for comprehensive App API documentation
1101
+ - Use `list_apps` to view all apps