@howone/agent-cli 0.0.0-stage → 0.5.0

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 (228) hide show
  1. package/README.md +49 -2
  2. package/bin/index.d.mts +1 -0
  3. package/bin/index.mjs +2397 -0
  4. package/package.json +55 -4
  5. package/skills/howone/01-apps.md +29 -0
  6. package/skills/howone/02-develop.md +107 -0
  7. package/skills/howone/03-workflows.md +71 -0
  8. package/skills/howone/04-functions-and-data.md +41 -0
  9. package/skills/howone/05-capabilities.md +46 -0
  10. package/skills/howone/SKILL.md +52 -0
  11. package/templates/vite/.howone/skills/hallmark/SKILL.md +557 -0
  12. package/templates/vite/.howone/skills/hallmark/references/anti-patterns.md +418 -0
  13. package/templates/vite/.howone/skills/hallmark/references/assets.md +406 -0
  14. package/templates/vite/.howone/skills/hallmark/references/color.md +95 -0
  15. package/templates/vite/.howone/skills/hallmark/references/component-cookbook.md +265 -0
  16. package/templates/vite/.howone/skills/hallmark/references/components/c1-outlined-chip.md +12 -0
  17. package/templates/vite/.howone/skills/hallmark/references/components/c2-inline-form-as-cta.md +16 -0
  18. package/templates/vite/.howone/skills/hallmark/references/components/c3-typographic-link.md +8 -0
  19. package/templates/vite/.howone/skills/hallmark/references/components/c4-sticky-bottom-bar.md +16 -0
  20. package/templates/vite/.howone/skills/hallmark/references/components/f1-bento-grid.md +20 -0
  21. package/templates/vite/.howone/skills/hallmark/references/components/f2-sticky-scroll-stack.md +20 -0
  22. package/templates/vite/.howone/skills/hallmark/references/components/f3-tabular-spec-sheet.md +11 -0
  23. package/templates/vite/.howone/skills/hallmark/references/components/f4-step-sequence.md +11 -0
  24. package/templates/vite/.howone/skills/hallmark/references/components/f5-annotated-screenshot.md +11 -0
  25. package/templates/vite/.howone/skills/hallmark/references/components/f6-product-card-grid.md +41 -0
  26. package/templates/vite/.howone/skills/hallmark/references/components/ft1-mast-headed.md +13 -0
  27. package/templates/vite/.howone/skills/hallmark/references/components/ft2-inline-rule-single-line.md +10 -0
  28. package/templates/vite/.howone/skills/hallmark/references/components/ft3-index-style-category-list.md +12 -0
  29. package/templates/vite/.howone/skills/hallmark/references/components/ft4-dense-typographic.md +10 -0
  30. package/templates/vite/.howone/skills/hallmark/references/components/ft5-statement.md +21 -0
  31. package/templates/vite/.howone/skills/hallmark/references/components/ft6-letter-close.md +19 -0
  32. package/templates/vite/.howone/skills/hallmark/references/components/ft7-newsletter-first.md +27 -0
  33. package/templates/vite/.howone/skills/hallmark/references/components/ft8-marquee-scroll.md +25 -0
  34. package/templates/vite/.howone/skills/hallmark/references/components/h1-marquee.md +15 -0
  35. package/templates/vite/.howone/skills/hallmark/references/components/h2-split-diptych.md +15 -0
  36. package/templates/vite/.howone/skills/hallmark/references/components/h3-quote-led.md +11 -0
  37. package/templates/vite/.howone/skills/hallmark/references/components/h4-stat-led.md +14 -0
  38. package/templates/vite/.howone/skills/hallmark/references/components/h5-letter-hero.md +11 -0
  39. package/templates/vite/.howone/skills/hallmark/references/components/h6-photographic-fold.md +16 -0
  40. package/templates/vite/.howone/skills/hallmark/references/components/h7-demo-video-clipped-by-viewport-edge.md +27 -0
  41. package/templates/vite/.howone/skills/hallmark/references/components/h8-mockup-split-browser-framed.md +23 -0
  42. package/templates/vite/.howone/skills/hallmark/references/components/h9-custom-illustration-centerpiece.md +27 -0
  43. package/templates/vite/.howone/skills/hallmark/references/components/n1-wordmark-2-links.md +12 -0
  44. package/templates/vite/.howone/skills/hallmark/references/components/n10-floating-on-scroll-morph.md +19 -0
  45. package/templates/vite/.howone/skills/hallmark/references/components/n11-mega-menu.md +40 -0
  46. package/templates/vite/.howone/skills/hallmark/references/components/n12-banner-retract.md +34 -0
  47. package/templates/vite/.howone/skills/hallmark/references/components/n13-inline-cmdk-pill.md +39 -0
  48. package/templates/vite/.howone/skills/hallmark/references/components/n1b-saas-three-section.md +35 -0
  49. package/templates/vite/.howone/skills/hallmark/references/components/n2-floating-chip.md +14 -0
  50. package/templates/vite/.howone/skills/hallmark/references/components/n3-side-rail.md +14 -0
  51. package/templates/vite/.howone/skills/hallmark/references/components/n4-hidden-behind-k.md +9 -0
  52. package/templates/vite/.howone/skills/hallmark/references/components/n5-floating-pill.md +28 -0
  53. package/templates/vite/.howone/skills/hallmark/references/components/n6-newspaper-masthead.md +24 -0
  54. package/templates/vite/.howone/skills/hallmark/references/components/n7-brutal-slab.md +22 -0
  55. package/templates/vite/.howone/skills/hallmark/references/components/n8-terminal-command.md +21 -0
  56. package/templates/vite/.howone/skills/hallmark/references/components/n9-edge-aligned-minimal.md +17 -0
  57. package/templates/vite/.howone/skills/hallmark/references/components/s1-left-margin-numbered.md +15 -0
  58. package/templates/vite/.howone/skills/hallmark/references/components/s2-hanging.md +13 -0
  59. package/templates/vite/.howone/skills/hallmark/references/components/s3-sticky-pinned.md +19 -0
  60. package/templates/vite/.howone/skills/hallmark/references/components/s4-inline-no-break.md +11 -0
  61. package/templates/vite/.howone/skills/hallmark/references/components/s5-bottom-anchored.md +13 -0
  62. package/templates/vite/.howone/skills/hallmark/references/components/t1-pull-quote-with-marginalia.md +12 -0
  63. package/templates/vite/.howone/skills/hallmark/references/components/t2-logo-wall-hairline.md +19 -0
  64. package/templates/vite/.howone/skills/hallmark/references/components/t3-single-huge-quote.md +11 -0
  65. package/templates/vite/.howone/skills/hallmark/references/components/t4-numbered-stat-strip.md +14 -0
  66. package/templates/vite/.howone/skills/hallmark/references/contract.md +24 -0
  67. package/templates/vite/.howone/skills/hallmark/references/copy.md +182 -0
  68. package/templates/vite/.howone/skills/hallmark/references/custom-craft.md +626 -0
  69. package/templates/vite/.howone/skills/hallmark/references/custom-theme.md +367 -0
  70. package/templates/vite/.howone/skills/hallmark/references/design-md.md +116 -0
  71. package/templates/vite/.howone/skills/hallmark/references/export-formats.md +328 -0
  72. package/templates/vite/.howone/skills/hallmark/references/floating-nav.md +89 -0
  73. package/templates/vite/.howone/skills/hallmark/references/genres/atmospheric.md +69 -0
  74. package/templates/vite/.howone/skills/hallmark/references/genres/editorial.md +72 -0
  75. package/templates/vite/.howone/skills/hallmark/references/genres/modern-minimal.md +71 -0
  76. package/templates/vite/.howone/skills/hallmark/references/genres/playful.md +70 -0
  77. package/templates/vite/.howone/skills/hallmark/references/hero-enrichment.md +475 -0
  78. package/templates/vite/.howone/skills/hallmark/references/imagery-kit.md +170 -0
  79. package/templates/vite/.howone/skills/hallmark/references/interaction-and-states.md +208 -0
  80. package/templates/vite/.howone/skills/hallmark/references/layout-and-space.md +112 -0
  81. package/templates/vite/.howone/skills/hallmark/references/macrostructures/01-bento-grid.md +35 -0
  82. package/templates/vite/.howone/skills/hallmark/references/macrostructures/02-long-document.md +34 -0
  83. package/templates/vite/.howone/skills/hallmark/references/macrostructures/03-marquee-hero.md +31 -0
  84. package/templates/vite/.howone/skills/hallmark/references/macrostructures/04-stat-led.md +34 -0
  85. package/templates/vite/.howone/skills/hallmark/references/macrostructures/05-workbench.md +32 -0
  86. package/templates/vite/.howone/skills/hallmark/references/macrostructures/06-conversational-faq.md +33 -0
  87. package/templates/vite/.howone/skills/hallmark/references/macrostructures/07-manifesto.md +32 -0
  88. package/templates/vite/.howone/skills/hallmark/references/macrostructures/08-photographic.md +34 -0
  89. package/templates/vite/.howone/skills/hallmark/references/macrostructures/09-quote-led.md +32 -0
  90. package/templates/vite/.howone/skills/hallmark/references/macrostructures/10-specimen.md +32 -0
  91. package/templates/vite/.howone/skills/hallmark/references/macrostructures/11-catalogue.md +23 -0
  92. package/templates/vite/.howone/skills/hallmark/references/macrostructures/12-letter.md +23 -0
  93. package/templates/vite/.howone/skills/hallmark/references/macrostructures/13-index-first.md +23 -0
  94. package/templates/vite/.howone/skills/hallmark/references/macrostructures/14-narrative-workflow.md +23 -0
  95. package/templates/vite/.howone/skills/hallmark/references/macrostructures/15-split-studio.md +23 -0
  96. package/templates/vite/.howone/skills/hallmark/references/macrostructures/16-feature-stack.md +23 -0
  97. package/templates/vite/.howone/skills/hallmark/references/macrostructures/17-type-specimen.md +23 -0
  98. package/templates/vite/.howone/skills/hallmark/references/macrostructures/18-portfolio-grid.md +23 -0
  99. package/templates/vite/.howone/skills/hallmark/references/macrostructures/19-map-diagram.md +23 -0
  100. package/templates/vite/.howone/skills/hallmark/references/macrostructures/20-ecosystem-index.md +23 -0
  101. package/templates/vite/.howone/skills/hallmark/references/macrostructures/21-component-playground.md +23 -0
  102. package/templates/vite/.howone/skills/hallmark/references/macrostructures.md +89 -0
  103. package/templates/vite/.howone/skills/hallmark/references/microinteractions.md +258 -0
  104. package/templates/vite/.howone/skills/hallmark/references/motion.md +109 -0
  105. package/templates/vite/.howone/skills/hallmark/references/preview-examples.md +49 -0
  106. package/templates/vite/.howone/skills/hallmark/references/responsive.md +138 -0
  107. package/templates/vite/.howone/skills/hallmark/references/slop-test.md +192 -0
  108. package/templates/vite/.howone/skills/hallmark/references/structure.md +160 -0
  109. package/templates/vite/.howone/skills/hallmark/references/study.md +509 -0
  110. package/templates/vite/.howone/skills/hallmark/references/themes/carnival.md +301 -0
  111. package/templates/vite/.howone/skills/hallmark/references/themes/cobalt.md +146 -0
  112. package/templates/vite/.howone/skills/hallmark/references/themes/hum.md +403 -0
  113. package/templates/vite/.howone/skills/hallmark/references/themes/lumen.md +478 -0
  114. package/templates/vite/.howone/skills/hallmark/references/typography.md +243 -0
  115. package/templates/vite/.howone/skills/hallmark/references/verbs/audit.md +25 -0
  116. package/templates/vite/.howone/skills/hallmark/references/verbs/redesign.md +269 -0
  117. package/templates/vite/.howone/skills/howone/01-architect/01-app-generation.md +209 -0
  118. package/templates/vite/.howone/skills/howone/01-architect/02-manifest-codegen.md +194 -0
  119. package/templates/vite/.howone/skills/howone/02-entity-schema/01-schema-design.md +523 -0
  120. package/templates/vite/.howone/skills/howone/02-entity-schema/02-schema-operations.md +329 -0
  121. package/templates/vite/.howone/skills/howone/02-entity-schema/03-access-models.md +151 -0
  122. package/templates/vite/.howone/skills/howone/02-entity-schema/04-query-contracts.md +123 -0
  123. package/templates/vite/.howone/skills/howone/02-entity-schema/05-ai-persistence-patterns.md +255 -0
  124. package/templates/vite/.howone/skills/howone/03-ai-capabilities/01-ai-capability-architecture.md +215 -0
  125. package/templates/vite/.howone/skills/howone/03-ai-capabilities/02-workflow-contract-rules.md +427 -0
  126. package/templates/vite/.howone/skills/howone/03-ai-capabilities/03-service-capability-catalog.md +304 -0
  127. package/templates/vite/.howone/skills/howone/03-ai-capabilities/04-workflow-operations.md +164 -0
  128. package/templates/vite/.howone/skills/howone/03-ai-capabilities/05-ai-feature-playbooks.md +275 -0
  129. package/templates/vite/.howone/skills/howone/04-app-sdk/01-client-setup.md +162 -0
  130. package/templates/vite/.howone/skills/howone/04-app-sdk/02-entity-operations.md +163 -0
  131. package/templates/vite/.howone/skills/howone/04-app-sdk/03-auth.md +418 -0
  132. package/templates/vite/.howone/skills/howone/04-app-sdk/04-react-integration.md +138 -0
  133. package/templates/vite/.howone/skills/howone/04-app-sdk/05-file-upload.md +112 -0
  134. package/templates/vite/.howone/skills/howone/04-app-sdk/06-raw-http.md +128 -0
  135. package/templates/vite/.howone/skills/howone/04-app-sdk/07-ai-action-calls.md +210 -0
  136. package/templates/vite/.howone/skills/howone/04-app-sdk/08-ai-manifest-handoff.md +90 -0
  137. package/templates/vite/.howone/skills/howone/04-app-sdk/09-extension-boundaries.md +226 -0
  138. package/templates/vite/.howone/skills/howone/04-app-sdk/10-workflow-execute-sse.md +138 -0
  139. package/templates/vite/.howone/skills/howone/04-app-sdk/11-entity-data-access-patterns.md +310 -0
  140. package/templates/vite/.howone/skills/howone/04-app-sdk/12-query-dsl-and-responses.md +237 -0
  141. package/templates/vite/.howone/skills/howone/04-app-sdk/13-credits.md +31 -0
  142. package/templates/vite/.howone/skills/howone/SKILL.md +256 -0
  143. package/templates/vite/.howone/skills/howone/agents/openai.yaml +4 -0
  144. package/templates/vite/.howone/skills/howone/references/audio-generation.md +30 -0
  145. package/templates/vite/.howone/skills/howone/references/audio-recognition.md +30 -0
  146. package/templates/vite/.howone/skills/howone/references/common-errors.md +27 -0
  147. package/templates/vite/.howone/skills/howone/references/finance.md +28 -0
  148. package/templates/vite/.howone/skills/howone/references/image-editing.md +30 -0
  149. package/templates/vite/.howone/skills/howone/references/image-generation.md +30 -0
  150. package/templates/vite/.howone/skills/howone/references/version-evidence.md +47 -0
  151. package/templates/vite/.howone/skills/howone/references/video-generation.md +35 -0
  152. package/templates/vite/.howone/skills/howone/scripts/verify-project.mjs +151 -0
  153. package/templates/vite/.prettierignore +7 -0
  154. package/templates/vite/.prettierrc +11 -0
  155. package/templates/vite/AGENTS.md +87 -0
  156. package/templates/vite/README.md +21 -0
  157. package/templates/vite/components.json +25 -0
  158. package/templates/vite/eslint.config.js +23 -0
  159. package/templates/vite/index.html +12 -0
  160. package/templates/vite/package.json +58 -0
  161. package/templates/vite/public/vite.svg +1 -0
  162. package/templates/vite/src/App.tsx +17 -0
  163. package/templates/vite/src/assets/react.svg +1 -0
  164. package/templates/vite/src/components/theme-provider.tsx +230 -0
  165. package/templates/vite/src/components/ui/accordion.tsx +79 -0
  166. package/templates/vite/src/components/ui/alert-dialog.tsx +197 -0
  167. package/templates/vite/src/components/ui/alert.tsx +76 -0
  168. package/templates/vite/src/components/ui/aspect-ratio.tsx +11 -0
  169. package/templates/vite/src/components/ui/avatar.tsx +110 -0
  170. package/templates/vite/src/components/ui/badge.tsx +49 -0
  171. package/templates/vite/src/components/ui/breadcrumb.tsx +122 -0
  172. package/templates/vite/src/components/ui/button-group.tsx +83 -0
  173. package/templates/vite/src/components/ui/button.tsx +67 -0
  174. package/templates/vite/src/components/ui/calendar.tsx +222 -0
  175. package/templates/vite/src/components/ui/card.tsx +103 -0
  176. package/templates/vite/src/components/ui/carousel.tsx +240 -0
  177. package/templates/vite/src/components/ui/chart.tsx +373 -0
  178. package/templates/vite/src/components/ui/checkbox.tsx +31 -0
  179. package/templates/vite/src/components/ui/collapsible.tsx +33 -0
  180. package/templates/vite/src/components/ui/combobox.tsx +299 -0
  181. package/templates/vite/src/components/ui/command.tsx +193 -0
  182. package/templates/vite/src/components/ui/context-menu.tsx +261 -0
  183. package/templates/vite/src/components/ui/dialog.tsx +168 -0
  184. package/templates/vite/src/components/ui/direction.tsx +22 -0
  185. package/templates/vite/src/components/ui/drawer.tsx +132 -0
  186. package/templates/vite/src/components/ui/dropdown-menu.tsx +269 -0
  187. package/templates/vite/src/components/ui/empty.tsx +104 -0
  188. package/templates/vite/src/components/ui/field.tsx +238 -0
  189. package/templates/vite/src/components/ui/hover-card.tsx +42 -0
  190. package/templates/vite/src/components/ui/input-group.tsx +154 -0
  191. package/templates/vite/src/components/ui/input-otp.tsx +87 -0
  192. package/templates/vite/src/components/ui/input.tsx +19 -0
  193. package/templates/vite/src/components/ui/item.tsx +196 -0
  194. package/templates/vite/src/components/ui/kbd.tsx +26 -0
  195. package/templates/vite/src/components/ui/label.tsx +22 -0
  196. package/templates/vite/src/components/ui/menubar.tsx +280 -0
  197. package/templates/vite/src/components/ui/native-select.tsx +61 -0
  198. package/templates/vite/src/components/ui/navigation-menu.tsx +164 -0
  199. package/templates/vite/src/components/ui/pagination.tsx +129 -0
  200. package/templates/vite/src/components/ui/popover.tsx +87 -0
  201. package/templates/vite/src/components/ui/progress.tsx +31 -0
  202. package/templates/vite/src/components/ui/radio-group.tsx +42 -0
  203. package/templates/vite/src/components/ui/resizable.tsx +50 -0
  204. package/templates/vite/src/components/ui/scroll-area.tsx +53 -0
  205. package/templates/vite/src/components/ui/select.tsx +192 -0
  206. package/templates/vite/src/components/ui/separator.tsx +26 -0
  207. package/templates/vite/src/components/ui/sheet.tsx +145 -0
  208. package/templates/vite/src/components/ui/sidebar.tsx +700 -0
  209. package/templates/vite/src/components/ui/skeleton.tsx +13 -0
  210. package/templates/vite/src/components/ui/slider.tsx +59 -0
  211. package/templates/vite/src/components/ui/sonner.tsx +47 -0
  212. package/templates/vite/src/components/ui/spinner.tsx +10 -0
  213. package/templates/vite/src/components/ui/switch.tsx +33 -0
  214. package/templates/vite/src/components/ui/table.tsx +114 -0
  215. package/templates/vite/src/components/ui/tabs.tsx +90 -0
  216. package/templates/vite/src/components/ui/textarea.tsx +18 -0
  217. package/templates/vite/src/components/ui/toggle-group.tsx +89 -0
  218. package/templates/vite/src/components/ui/toggle.tsx +45 -0
  219. package/templates/vite/src/components/ui/tooltip.tsx +57 -0
  220. package/templates/vite/src/hooks/use-mobile.ts +19 -0
  221. package/templates/vite/src/index.css +133 -0
  222. package/templates/vite/src/lib/sdk.ts +34 -0
  223. package/templates/vite/src/lib/utils.ts +6 -0
  224. package/templates/vite/src/main.tsx +14 -0
  225. package/templates/vite/tsconfig.app.json +32 -0
  226. package/templates/vite/tsconfig.json +13 -0
  227. package/templates/vite/tsconfig.node.json +26 -0
  228. package/templates/vite/vite.config.ts +14 -0
@@ -0,0 +1,304 @@
1
+ # Service Capability Catalog
2
+
3
+ Use this reference **only** for HowOne **workflow-service AI** feasibility. It lists what the current
4
+ workflow service supports—not everything a full product may use.
5
+
6
+ Explicit user-owned integrations are outside this catalog per
7
+ `01-architect/01-app-generation.md`. Use that exception only when the user explicitly asks to
8
+ connect something outside HowOne. Ordinary generated AI app requests should be checked against this
9
+ catalog first.
10
+
11
+ Source: `docs/ai-capability.md`.
12
+
13
+ ## Quick Selection Table
14
+
15
+ | User asks for | Use capability family | Typical inputs | Typical outputs |
16
+ |---|---|---|---|
17
+ | Latest info, research, source-backed answer | Web search / crawling | `topic`, `prompt`, `url`, `search_level` | `answer`, `sources`, `page_content` |
18
+ | Generate artwork/photo/logo/mockup | Image generation | `prompt`, optional `reference_img_urls`, size/format | `generated_image_url` or `image_urls` |
19
+ | Edit an image | Image editing | `prompt`, `image_urls`, optional size/format | `edited_image_url` or `image_urls` |
20
+ | OCR or visual analysis | Image analysis / OCR | `prompt`, optional `image_urls` | `analysis_result` or `extracted_text` |
21
+ | Generate short video | Video generation | `prompt`, aspect/duration/frame URLs | `video_url` |
22
+ | Join clips / extract frames | Video editing | `video_urls` or `video_url` | `video_url` or `image_url` |
23
+ | Text to speech | Audio generation | `text_to_generate`, `languages`, `gender`, `audio_hint` | `audio_url` |
24
+ | Speech to text | Audio recognition | `audio_url`, `language`, optional diarization | `transcript_text`, optional `utterances` |
25
+ | Merge audio | Audio merging | `audio_urls` | `merged_audio_url` |
26
+ | Stock/index history | Financial data retrieval | `trading_symbol`, `unit`, `start`, `end` | `price_history` |
27
+ | Literature search/citations | Academic research | `query` | `papers`, `bibtex` |
28
+ | Save generated file | File storage | `file_type`, `content` | `file_url` |
29
+
30
+ If the requested behavior is not in this table or the detailed sections below, do not invent it.
31
+
32
+ ## Detailed Parameter References
33
+
34
+ The sections below establish family-level feasibility. Before designing one of these workflow
35
+ contracts, read its detailed service reference for exact parameter names, allowed values, defaults,
36
+ conditional requirements, outputs, and hard limits:
37
+
38
+ | Capability family | Read |
39
+ |---|---|
40
+ | Audio generation | `../references/audio-generation.md` |
41
+ | Audio recognition | `../references/audio-recognition.md` |
42
+ | Financial data retrieval | `../references/finance.md` |
43
+ | Image editing | `../references/image-editing.md` |
44
+ | Image generation | `../references/image-generation.md` |
45
+ | Video generation | `../references/video-generation.md` |
46
+
47
+ These are workflow-service parameters, not direct `@howone/sdk` method signatures. Translate only
48
+ the product-relevant subset into a loose capability schema, then use the synced AI manifest for app
49
+ bindings.
50
+
51
+ ## Web Search And Crawling
52
+
53
+ Use for latest information, news, market context, source-backed answers, web page extraction.
54
+
55
+ Inputs:
56
+
57
+ - `prompt`: query or detailed research instruction;
58
+ - `search_level`: `low`, `medium`, or `high`; default to medium;
59
+ - `offset`: pagination for low-level search;
60
+ - page crawl input should be a URL.
61
+
62
+ Outputs:
63
+
64
+ - synthesized answer or raw search result;
65
+ - `sources` array of URLs;
66
+ - crawled page text/markdown when crawling.
67
+
68
+ Rules:
69
+
70
+ - Use web search when the user asks for current/latest information.
71
+ - Use page crawling when the product needs content from a specific URL.
72
+ - Do not use search as an outbound API caller.
73
+ - Include source links in output when the product promises research.
74
+
75
+ ## Image Generation
76
+
77
+ Use for new images from prompts or prompt + reference URLs.
78
+
79
+ Inputs:
80
+
81
+ - `prompt`: detailed prompt;
82
+ - `reference_img_urls`: optional URL array;
83
+ - optional `image_names`, `size`, and `output_format` when the product exposes them.
84
+
85
+ Outputs:
86
+
87
+ - `generated_image_url` or `image_urls`;
88
+ - avoid metadata unless product needs it.
89
+
90
+ Rules:
91
+
92
+ - One image per request is usually more reliable.
93
+ - Do not put resolution text into the prompt when a size parameter exists.
94
+ - Reference images must be URLs and should be described by position/content.
95
+ - Subject to moderation; do not promise forbidden content.
96
+
97
+ ## Image Editing
98
+
99
+ Use for modifying existing images.
100
+
101
+ Inputs:
102
+
103
+ - `image_urls`: one or more source image URLs;
104
+ - `prompt`: edit instruction;
105
+ - optional output size/format.
106
+
107
+ Outputs:
108
+
109
+ - `edited_image_url`.
110
+
111
+ Supported edits include resize/crop/rotate, background removal/replacement, object removal/addition,
112
+ style transfer, enhancement, merge/composite, lighting/color changes.
113
+
114
+ Rules:
115
+
116
+ - At least one image URL is required.
117
+ - Keep edit instructions focused.
118
+ - For complex multi-step edits, describe the final desired result.
119
+
120
+ ## Image Analysis And OCR
121
+
122
+ Use for visual understanding, image comparison, text extraction, quality review.
123
+
124
+ Inputs:
125
+
126
+ - `image_urls`;
127
+ - `prompt`: analysis question or OCR instruction.
128
+
129
+ Outputs:
130
+
131
+ - `analysis_result` for semantic analysis;
132
+ - `extracted_text` for OCR.
133
+
134
+ Rules:
135
+
136
+ - Ask for the exact information needed.
137
+ - Do not include confidence/bounding boxes unless user asks.
138
+ - OCR quality depends on image quality.
139
+
140
+ ## Video Generation
141
+
142
+ Use for short video clips from text or image frames.
143
+
144
+ Inputs:
145
+
146
+ - `prompt`;
147
+ - optional `first_frame_url`, `last_frame_url`, `reference_images`;
148
+ - optional `aspect_ratio`, `duration`, `negative_prompt`, `generate_audio`.
149
+
150
+ Outputs:
151
+
152
+ - `video_url`.
153
+
154
+ Rules:
155
+
156
+ - Keep individual clips short, generally 5-10 seconds.
157
+ - For consistency, generate/use a first-frame image.
158
+ - For longer videos, generate clips and concatenate via video editing.
159
+ - Audio in video works best with one speaker per clip.
160
+
161
+ ## Video Editing
162
+
163
+ Use for concatenating clips or extracting first/last frames.
164
+
165
+ Inputs:
166
+
167
+ - concatenate: `video_urls` with at least two URLs;
168
+ - frame extraction: `source_video_url`.
169
+
170
+ Outputs:
171
+
172
+ - `merged_video_url` or `frame_image_url`.
173
+
174
+ Rules:
175
+
176
+ - Inputs must be accessible URLs.
177
+ - Best results when clips share resolution/aspect ratio.
178
+
179
+ ## Audio Generation
180
+
181
+ Use for text-to-speech.
182
+
183
+ Inputs:
184
+
185
+ - `text_to_generate`;
186
+ - `languages`;
187
+ - `gender`;
188
+ - `audio_hint`;
189
+ - optional `audio_output` with output format/name.
190
+
191
+ Outputs:
192
+
193
+ - `audio_url`.
194
+
195
+ Rules:
196
+
197
+ - Single speaker per call.
198
+ - For dialogue, generate each speaker line and merge audio.
199
+ - `audio_hint` should describe voice in English.
200
+
201
+ ## Audio Recognition
202
+
203
+ Use for speech-to-text.
204
+
205
+ Inputs:
206
+
207
+ - `audio_url`;
208
+ - optional `language`;
209
+ - optional `with_speaker_info` for speaker diarization.
210
+
211
+ Outputs:
212
+
213
+ - `transcript_text`;
214
+ - optional `utterances` when speaker info is requested.
215
+
216
+ Rules:
217
+
218
+ - Audio must be URL-accessible.
219
+ - Silent or low-quality audio can produce empty/poor transcript.
220
+
221
+ ## Financial Data Retrieval
222
+
223
+ Use for historical stock/index price data.
224
+
225
+ Inputs:
226
+
227
+ - `trading_symbol`;
228
+ - `unit`: `daily` or `minute`;
229
+ - `start`;
230
+ - `end`.
231
+
232
+ Outputs:
233
+
234
+ - `price_history` array;
235
+ - `trading_symbol`;
236
+ - optional warning.
237
+
238
+ Rules:
239
+
240
+ - Historical data only; no real-time streaming.
241
+ - Indices usually support daily data only.
242
+ - Ask for exact tickers when possible.
243
+ - Does not provide fundamentals, earnings, or live news unless combined with web search.
244
+
245
+ ## Academic Research
246
+
247
+ Use for literature search, paper metadata, BibTeX.
248
+
249
+ Inputs:
250
+
251
+ - `query`.
252
+
253
+ Outputs:
254
+
255
+ - `papers`;
256
+ - `bibtex` when citation output is requested.
257
+
258
+ Rules:
259
+
260
+ - Search quality depends on query specificity.
261
+ - Availability varies by academic source.
262
+ - PDF assets should be handled as URLs.
263
+
264
+ ## File Storage
265
+
266
+ Use when workflow needs to save generated content into a file.
267
+
268
+ Inputs:
269
+
270
+ - `file_type`: `json`, `yaml`, `csv`, `pdf`, `md`, or `txt`;
271
+ - `content`: string content to save.
272
+
273
+ Outputs:
274
+
275
+ - `file_url`.
276
+
277
+ Rules:
278
+
279
+ - Structured content must be serialized to string before saving.
280
+ - Do not use file storage as a database.
281
+ - If app needs records/history, persist file URL through entities.
282
+
283
+ ## Composition Patterns
284
+
285
+ | Pattern | Workflow design |
286
+ |---|---|
287
+ | Image -> Video | generate first-frame image, pass as `first_frame_url` to video generation |
288
+ | Multi-clip video | generate short clips, concatenate via video editing |
289
+ | Dialogue audio | generate each speaker line, merge audio |
290
+ | Search -> Report | web search/crawl, synthesize structured report, optionally save file |
291
+ | Video -> Image edit -> Video | extract frame, edit frame, use as next reference |
292
+ | RAG document chat | indexing workflow + query workflow |
293
+
294
+ ## Platform AI stop (catalog boundary)
295
+
296
+ Stop **platform AI design** (do not invent capabilities) when the requirement:
297
+
298
+ - has no matching capability family in this catalog or detailed sections below;
299
+ - needs behavior the workflow service cannot perform per contract rules in `02-workflow-contract-rules.md`;
300
+ - violates workflow input/output constraints (e.g. persistence or app CRUD inside the workflow contract);
301
+ - exceeds documented service limits after you read the relevant section.
302
+
303
+ Explain the gap by **missing catalog/contract support**, not by naming the user's stack. Offer the
304
+ closest listed capability or ask to narrow the product ask. App-owned integrations remain allowed in parallel.
@@ -0,0 +1,164 @@
1
+ # Workflow Operations
2
+
3
+ Use this reference when submitting HowOne external AI workflow create/update operations through
4
+ `external-ai-capability`. This is an AI workflow design reference, not an app SDK guide.
5
+
6
+ ## Current Tool Contract
7
+
8
+ Do not hand-build raw workflow HTTP requests in generated app work. Use `external-ai-capability`
9
+ after `.howone/ai/manifest.json` has been synced.
10
+
11
+ The foreground tool performs:
12
+
13
+ ```text
14
+ POST /workflows
15
+ ```
16
+
17
+ The host-owned background poller performs `GET /jobs/{job_id}` and finalizes successful bindings.
18
+
19
+ The tool reads the synced manifest and submits operations for selected capabilities.
20
+
21
+ ## Create
22
+
23
+ Use create when the capability has a synced manifest entry and no external implementation has been
24
+ submitted for its current `workflowId`.
25
+
26
+ Tool input:
27
+
28
+ ```json
29
+ {
30
+ "cwd": "<app-root>",
31
+ "capabilityNames": ["summarizeDocument"]
32
+ }
33
+ ```
34
+
35
+ Tool behavior:
36
+
37
+ ```text
38
+ config_id = manifest.capabilities[].workflowId
39
+ mode = create
40
+ capability = synced manifest capability contract
41
+ ```
42
+
43
+ Do not generate a second UUID for create. The AI capability design/sync path already produced the
44
+ manifest `workflowId`.
45
+
46
+ ## Update
47
+
48
+ Use update when the external implementation exists and the user asks to change workflow behavior or
49
+ to regenerate implementation for a changed contract.
50
+
51
+ Tool input:
52
+
53
+ ```json
54
+ {
55
+ "cwd": "<app-root>",
56
+ "updates": [
57
+ {
58
+ "capabilityName": "summarizeDocument",
59
+ "updatePrompt": "Support concise bullet-point summaries when the user asks for bullet format."
60
+ }
61
+ ]
62
+ }
63
+ ```
64
+
65
+ Tool behavior:
66
+
67
+ ```text
68
+ previous config = current manifest capability.workflowId
69
+ new config = freshly generated UUID sent as new_config_id
70
+ mode = update
71
+ original_config_id = previous config sent to EAX
72
+ workflow code = regenerated by EAX from the current capability contract and updatePrompt
73
+ submitted state = local manifest remains unchanged while EAX runs
74
+ completed state = backend capability version receives the fresh UUID
75
+ ```
76
+
77
+ After a completed update, run `sync_ai_artifacts` and then re-read `.howone/ai/manifest.json`. The
78
+ newly synced `workflowId` is the value used by SDK bindings and future execution. Failed operations
79
+ keep their previous backend and local manifest bindings.
80
+
81
+ Do not pass stale `workflowConfigID` values from old docs or older status payloads. Agents should
82
+ not pass `original_config_id` directly either; the current tool derives it from the manifest and
83
+ owns config rotation; the background finalizer owns backend binding promotion.
84
+
85
+ ## Selection Rules
86
+
87
+ - `capabilityNames` limits create operations.
88
+ - `updates[]` limits update operations.
89
+ - If `updates[]` is provided without `capabilityNames`, only those update capabilities are selected.
90
+ - Do not submit every capability when the user asked to update one behavior.
91
+
92
+ ## Status And Results
93
+
94
+ The tool may return immediately when a host poller is available. Preserve:
95
+
96
+ - `jobId`;
97
+ - `taskId` / `requestId` when present;
98
+ - `submittedConfigId`;
99
+ - `previousConfigId` for updates;
100
+ - `manifestUpdates` mapping old workflow IDs to new workflow IDs.
101
+
102
+ Terminal result meaning:
103
+
104
+ | Status | Meaning |
105
+ |---|---|
106
+ | `submitted` | background poller will continue |
107
+ | `running` / `queued` | not terminal |
108
+ | `completed` | workflow operation completed |
109
+ | `failed` / `canceled` / `timed_out` | report error and do not pretend workflow is ready |
110
+
111
+ A non-terminal submission is not a legal completion or pause boundary for the Coding Agent. Do not
112
+ end the run merely to wait for a host notification. Continue all implementation that does not need
113
+ the promoted workflow ID, including UI structure, persistence, loading/error states, and other app
114
+ logic. Defer only final workflow-ID binding and live execution verification until terminal success.
115
+
116
+ ## Standard Flow
117
+
118
+ New AI feature:
119
+
120
+ ```text
121
+ ai-capability-design apply_capability_patch
122
+ sync_ai_artifacts
123
+ external-ai-capability { cwd, capabilityNames }
124
+ continue independent app implementation; do not stop to wait
125
+ terminal result
126
+ sync_ai_artifacts
127
+ read .howone/ai/manifest.json
128
+ ```
129
+
130
+ Schema-changing AI update:
131
+
132
+ ```text
133
+ ai-capability-design apply_capability_patch
134
+ sync_ai_artifacts
135
+ external-ai-capability { cwd, updates: [{ capabilityName, updatePrompt }] }
136
+ continue independent app implementation; do not stop to wait
137
+ terminal result
138
+ sync_ai_artifacts
139
+ read .howone/ai/manifest.json
140
+ ```
141
+
142
+ Behavior-only update:
143
+
144
+ ```text
145
+ external-ai-capability { cwd, updates: [{ capabilityName, updatePrompt }] }
146
+ continue independent app implementation; do not stop to wait
147
+ terminal result
148
+ sync_ai_artifacts
149
+ read .howone/ai/manifest.json
150
+ update SDK workflowId bindings from the newly synced manifest
151
+ ```
152
+
153
+ Final workflow-ID SDK binding happens after terminal sync and belongs to the SDK track. Other app
154
+ source work proceeds while the external job is pending.
155
+
156
+ ## Checklist
157
+
158
+ - Manifest is synced before submit.
159
+ - Create uses the existing manifest `workflowId`.
160
+ - Update lets the tool generate a fresh config UUID.
161
+ - Update has a concrete `updatePrompt`.
162
+ - The backend capability version is finalized before local artifacts are synced again.
163
+ - The manifest is re-read only after the post-completion sync.
164
+ - SDK bindings are copied from manifest, not from memory or old status IDs.