@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,255 @@
1
+ # AI Persistence Entity Patterns
2
+
3
+ Use this reference after the AI output schema is known and the product needs durable data:
4
+ generation history, saved results, reports, retryable jobs, share pages, or user libraries.
5
+
6
+ This is a backend entity design reference. It does not define SDK calls. App-side execution and
7
+ persistence code belongs in `04-app-sdk/07-ai-action-calls.md` and
8
+ `04-app-sdk/08-ai-manifest-handoff.md`.
9
+
10
+ ## Core Boundary
11
+
12
+ ```text
13
+ AI capability outputSchema != database entity schema
14
+ ```
15
+
16
+ The AI output schema is the workflow return contract. The database entity schema is the product
17
+ record contract. Persist only fields the product needs after refresh, across sessions, in lists, or
18
+ on public pages.
19
+
20
+ For every AI output field, decide:
21
+
22
+ | Question | Persist? | Entity design |
23
+ |---|---:|---|
24
+ | User must see it after refresh | yes | explicit field |
25
+ | It appears in history/library/search | yes | field + index if queried |
26
+ | It is needed for retry/resume | yes | input/options/status fields |
27
+ | It is only a streaming/intermediate chunk | no | runtime/UI state |
28
+ | It is provider debug metadata | usually no | logs, not product records |
29
+ | It is sensitive internal/provider data | usually no | omit or keep private-only |
30
+
31
+ ## Pending-First Record Model
32
+
33
+ For long-running or user-visible AI jobs, design an entity that can represent pending, completed,
34
+ and failed states. The app may create a pending record before workflow execution, then update it
35
+ after completion or failure.
36
+
37
+ Required contract pieces:
38
+
39
+ - original user input or durable input reference;
40
+ - `status`;
41
+ - output fields for completed display;
42
+ - failure fields for history/retry;
43
+ - timestamps for list ordering and stale-job handling.
44
+
45
+ Status field:
46
+
47
+ ```json
48
+ {
49
+ "status": {
50
+ "type": "string",
51
+ "description": "pending | running | completed | failed | canceled",
52
+ "default": "pending"
53
+ }
54
+ }
55
+ ```
56
+
57
+ Rules:
58
+
59
+ - Do not infer completion only from `resultUrl`, `summary`, or another output field.
60
+ - Keep failed records when the product has history or retry UX.
61
+ - If pending/running records are shown from persisted data, define how stale records are recovered.
62
+ - Do not store raw event streams unless the entity explicitly needs them.
63
+
64
+ ## Minimal Generation History Entity
65
+
66
+ Use for image, text, report, music, video, or similar generation history.
67
+
68
+ ```json
69
+ {
70
+ "name": "Generation",
71
+ "type": "object",
72
+ "properties": {
73
+ "prompt": { "type": "string" },
74
+ "status": { "type": "string", "default": "pending" },
75
+ "resultUrl": { "type": ["string", "null"], "default": null },
76
+ "resultText": { "type": ["string", "null"], "default": null },
77
+ "errorMessage": { "type": ["string", "null"], "default": null },
78
+ "requestedAt": { "type": "date" },
79
+ "completedAt": { "type": ["date", "null"], "default": null }
80
+ },
81
+ "required": ["prompt", "status", "requestedAt"],
82
+ "access": {
83
+ "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
84
+ "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
85
+ },
86
+ "indexes": [
87
+ { "name": "owner_updated", "fields": ["updatedDate"], "scope": "owner" },
88
+ { "name": "owner_status_updated", "fields": ["status", "updatedDate"], "scope": "owner" }
89
+ ],
90
+ "performance": {
91
+ "defaultLimit": 20,
92
+ "maxLimit": 100,
93
+ "allowedSorts": ["updatedDate", "requestedAt"]
94
+ },
95
+ "presentation": {
96
+ "titleField": "prompt",
97
+ "subtitleField": "status"
98
+ }
99
+ }
100
+ ```
101
+
102
+ Prefer separate product fields over one opaque `result` object when the UI lists, filters, previews,
103
+ or shares the output. Use an object field only for genuinely nested product-level structured data.
104
+
105
+ ## Structured Analysis Report Entity
106
+
107
+ Use when AI returns a report users browse later.
108
+
109
+ ```json
110
+ {
111
+ "name": "AnalysisReport",
112
+ "type": "object",
113
+ "properties": {
114
+ "sourceTitle": { "type": "string" },
115
+ "sourceUrl": { "type": ["string", "null"], "default": null },
116
+ "status": { "type": "string", "default": "pending" },
117
+ "summary": { "type": ["string", "null"], "default": null },
118
+ "insights": { "type": "array", "default": [] },
119
+ "score": { "type": ["number", "null"], "default": null },
120
+ "errorMessage": { "type": ["string", "null"], "default": null },
121
+ "requestedAt": { "type": "date" },
122
+ "completedAt": { "type": ["date", "null"], "default": null }
123
+ },
124
+ "required": ["sourceTitle", "status", "requestedAt"],
125
+ "access": {
126
+ "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
127
+ "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
128
+ },
129
+ "indexes": [
130
+ { "name": "owner_updated", "fields": ["updatedDate"], "scope": "owner" },
131
+ { "name": "owner_score_updated", "fields": ["score", "updatedDate"], "scope": "owner" }
132
+ ]
133
+ }
134
+ ```
135
+
136
+ Mapping rule:
137
+
138
+ ```text
139
+ workflow input.sourceTitle -> AnalysisReport.sourceTitle
140
+ workflow input.sourceUrl -> AnalysisReport.sourceUrl
141
+ workflow output.summary -> AnalysisReport.summary
142
+ workflow output.insights -> AnalysisReport.insights
143
+ workflow output.score -> AnalysisReport.score
144
+ runtime failure -> AnalysisReport.errorMessage
145
+ runtime completed -> AnalysisReport.completedAt
146
+ ```
147
+
148
+ Do not save the whole workflow envelope unless the product explicitly needs a private object field
149
+ for audit/debug.
150
+
151
+ ## Public Share Split
152
+
153
+ For public AI result pages, split private history from public share data:
154
+
155
+ - private `Generation` stores prompts, failures, drafts, internal metadata, and user history;
156
+ - public/scoped `SharedGeneration` stores only curated fields for anonymous viewing.
157
+
158
+ Scoped public share entity:
159
+
160
+ ```json
161
+ {
162
+ "name": "SharedGeneration",
163
+ "type": "object",
164
+ "properties": {
165
+ "shareId": {
166
+ "type": "string",
167
+ "autoGenerate": { "strategy": "uuid" }
168
+ },
169
+ "title": { "type": "string" },
170
+ "resultUrl": { "type": "string" },
171
+ "active": { "type": "boolean", "default": true },
172
+ "sourceGenerationId": { "type": "string" }
173
+ },
174
+ "required": ["shareId", "title", "resultUrl", "active", "sourceGenerationId"],
175
+ "access": {
176
+ "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
177
+ "public": {
178
+ "read": "scoped",
179
+ "create": "none",
180
+ "update": "none",
181
+ "delete": "none",
182
+ "requiredScopes": ["shareId"],
183
+ "allowedFilters": ["shareId", "active"],
184
+ "allowedSorts": ["updatedDate"],
185
+ "defaultLimit": 1,
186
+ "maxLimit": 1
187
+ }
188
+ },
189
+ "indexes": [
190
+ { "name": "share_id_unique", "fields": ["shareId"], "unique": true },
191
+ { "name": "owner_updated", "fields": ["updatedDate"], "scope": "owner" }
192
+ ]
193
+ }
194
+ ```
195
+
196
+ Never make the main private generation history public just to support share pages.
197
+
198
+ ## Retry And Resume Fields
199
+
200
+ If retry is part of the product, persist enough input fields to rebuild the workflow request:
201
+
202
+ - prompt/source content reference;
203
+ - selected style/mode/options;
204
+ - uploaded file URLs or file IDs;
205
+ - status and error message;
206
+ - requested/completed timestamps.
207
+
208
+ Do not persist:
209
+
210
+ - auth/session/token values;
211
+ - raw uploaded browser bytes;
212
+ - temporary component state;
213
+ - raw streaming chunks;
214
+ - provider secrets;
215
+ - hidden system prompts or internal prompts.
216
+
217
+ Prefer a new retry record for history-oriented products. Prefer updating the same record only when
218
+ retry semantically replaces the original attempt.
219
+
220
+ ## Field Mapping Checklist
221
+
222
+ Before app implementation, write the mapping explicitly:
223
+
224
+ ```text
225
+ workflow input.prompt -> Generation.prompt
226
+ workflow input.style -> Generation.style
227
+ workflow output.imageUrl -> Generation.resultUrl
228
+ workflow output.caption -> Generation.resultText
229
+ workflow error.message -> Generation.errorMessage
230
+ runtime request started -> Generation.requestedAt
231
+ runtime request completed -> Generation.completedAt
232
+ ```
233
+
234
+ If a workflow output has no mapping, decide whether it is intentionally transient or the entity
235
+ schema is missing a product field.
236
+
237
+ ## Access Checklist
238
+
239
+ | Product behavior | Entity access |
240
+ |---|---|
241
+ | User-only private generation history | authenticated own, public none |
242
+ | Shared authenticated library | authenticated all, public none |
243
+ | Anonymous public gallery | public list with safe fields only |
244
+ | One public share link | public scoped with share id |
245
+ | Public submission to AI queue | public create only with anti-abuse constraints |
246
+
247
+ ## Persistence Checklist
248
+
249
+ - AI output schema is fixed before persistence schema design.
250
+ - Entity stores product fields, not workflow internals.
251
+ - Status and failure fields exist for long-running jobs.
252
+ - Retry/resume input fields are durable.
253
+ - Public share data is split from private history.
254
+ - Indexes match history/share/list query patterns.
255
+ - SDK implementation begins only after database and AI manifests are synced.
@@ -0,0 +1,215 @@
1
+ # AI Capability Architecture
2
+
3
+ **Track:** `03-ai-capabilities/` — capability/workflow **design** only; SDK calls live in `04-app-sdk/`.
4
+
5
+ Use this reference when the user needs HowOne platform AI (verify `03-service-capability-catalog.md` first).
6
+
7
+ This file answers: **what AI layer should be designed, in what order, and where each responsibility
8
+ belongs?** For schema details read `02-workflow-contract-rules.md`. For workflow service calls read
9
+ `04-workflow-operations.md`.
10
+
11
+ ## Platform Mental Model
12
+
13
+ HowOne AI has five distinct layers:
14
+
15
+ | Layer | Owns | Does not own |
16
+ |---|---|---|
17
+ | Product feature | User-facing goal, UX states, persistence decision | workflow internals |
18
+ | AI capability contract | `name`, `description`, `inputSchema`, `outputSchema`, `outputEntityName`, versions, manifest | database CRUD, UI, auth |
19
+ | External workflow implementation | generated/edited workflow graph behind a manifest `workflowId`/EAX `config_id` | app schema, frontend state |
20
+ | Status/background layer | job/task polling, completed/failed state, submitted config mapping | SDK binding source |
21
+ | SDK handoff | synced manifest action names, workflow IDs, input/output schemas | workflow generation |
22
+
23
+ Do not collapse these layers. The common mistakes are:
24
+
25
+ - putting database writes into the workflow;
26
+ - generating `src/lib/sdk.ts` before `.howone/ai/manifest.json` is synced;
27
+ - using action names instead of workflow UUIDs;
28
+ - treating workflow `outputSchema` as a database schema;
29
+ - faking unsupported AI with static frontend data.
30
+
31
+ ## Source Of Truth
32
+
33
+ ```text
34
+ user request = intent
35
+ agent AI contract proposal = draft
36
+ applied AI capability version = validated contract
37
+ .howone/ai/manifest.json = local synced source for workflow submit and later SDK codegen
38
+ external-ai-capability submission = job/task/config mapping; update IDs remain pending
39
+ terminal background finalizer = promotes successful update IDs in the backend capability version
40
+ SDK/UI implementation = separate app-sdk track after AI design is complete
41
+ entity schema = persistence contract, separate from AI contract
42
+ ```
43
+
44
+ Never generate SDK bindings from the user prompt or from an unsynced draft.
45
+
46
+ ## Standard AI Feature Flow
47
+
48
+ Use this flow for new AI features:
49
+
50
+ 1. Classify the feature using `03-ai-capabilities/03-service-capability-catalog.md`.
51
+ 2. Decide whether the feature is supported. If not supported, stop and explain the missing capability.
52
+ 3. Decide one workflow per user-facing feature. Use two workflows only for RAG.
53
+ 4. Design `inputSchema` and `outputSchema` using `02-workflow-contract-rules.md`.
54
+ 5. Apply the AI capability patch through the capability tool.
55
+ 6. Sync `.howone/ai/manifest.json`.
56
+ 7. Submit workflow create/update through `external-ai-capability` from the synced manifest.
57
+ 8. Store returned job/task IDs and submitted config IDs for polling/debugging.
58
+ 9. Let the host poll status until `completed` or `failed`.
59
+ 10. On success, the background finalizer promotes successful update IDs in the backend capability version. Failed operations keep their previous IDs.
60
+ 11. Run `sync_ai_artifacts` again, then re-read `.howone/ai/manifest.json`.
61
+ 12. Leave AI design. If app code must call the workflow, read the SDK track and generate bindings.
62
+ 13. If output must persist, design entity schema after the output contract is fixed.
63
+
64
+ Do not submit external workflow create/update from a hand-written schema. It should come from the
65
+ synced manifest.
66
+
67
+ ## New Feature vs Existing Feature
68
+
69
+ | Situation | Correct path |
70
+ |---|---|
71
+ | New AI feature, no manifest entry | create AI capability, sync manifest, submit workflow create |
72
+ | Manifest entry exists but no workflow created yet | submit workflow create from manifest |
73
+ | User asks to change input/output contract | update capability contract first, sync, then submit workflow update |
74
+ | User asks to improve behavior only | submit workflow update with `updates[]` and `updatePrompt` |
75
+ | User asks to save outputs/history | design/update database entity after AI output contract is known |
76
+ | User asks for public share of AI result | private history entity + public scoped share entity |
77
+
78
+ ## Create vs Update
79
+
80
+ Create external workflow when:
81
+
82
+ - capability has a `workflowId`;
83
+ - no confirmed external implementation exists;
84
+ - the manifest `workflowId` has not already been submitted as an implementation config.
85
+
86
+ Update external workflow when:
87
+
88
+ - an external implementation exists;
89
+ - you have a concrete `updatePrompt`.
90
+ - `external-ai-capability` can read the current manifest `workflowId`.
91
+
92
+ Current `external-ai-capability` semantics:
93
+
94
+ ```text
95
+ create:
96
+ config_id = manifest capability.workflowId
97
+ mode = create
98
+
99
+ update:
100
+ previous config = current manifest capability.workflowId
101
+ new config = freshly generated UUID
102
+ submitted state = local manifest remains unchanged while EAX runs
103
+ completed state = backend capability version receives the fresh UUID
104
+ ```
105
+
106
+ The SDK execution binding uses the synced manifest `workflowId`, which is the EAX config id. After
107
+ update completion, run `sync_ai_artifacts`; only the newly synced manifest value should be copied
108
+ into `src/lib/sdk.ts`.
109
+ Do not invent IDs; let the AI design/sync/external workflow tools generate and persist them.
110
+
111
+ ## Workflow Count Rule
112
+
113
+ Default: one user-facing AI feature equals one workflow.
114
+
115
+ Examples:
116
+
117
+ | Feature | Workflow count | Why |
118
+ |---|---:|---|
119
+ | Generate illustrated story | 1 | story text + images are one product action |
120
+ | Edit uploaded photo | 1 | one input image + edit prompt -> edited image |
121
+ | Research news briefing | 1 | search + synthesis are one action |
122
+ | Generate video from prompt | 1 | media generation is one action |
123
+ | Chat with uploaded documents | 2 | RAG needs indexing + query workflows |
124
+
125
+ Do not split normal multi-step behavior into separate workflows. The workflow service handles
126
+ internal orchestration.
127
+
128
+ ## Persistence Boundary
129
+
130
+ AI workflows produce outputs. They do not own product records.
131
+
132
+ Workflow may do:
133
+
134
+ - generate, summarize, translate, classify, extract;
135
+ - search/crawl and synthesize;
136
+ - generate/edit/analyze images, video, and audio;
137
+ - retrieve financial or academic data;
138
+ - save/read generated files through URL-based storage.
139
+
140
+ Workflow must not do:
141
+
142
+ - database create/read/update/delete;
143
+ - authentication/session logic;
144
+ - file upload from browser raw bytes;
145
+ - payment processing;
146
+ - owner assignment or permissions;
147
+ - app navigation, UI state, toast, or modal logic.
148
+
149
+ If the product needs durable history, design entity persistence outside the workflow:
150
+
151
+ ```text
152
+ workflow input.prompt -> Generation.prompt
153
+ workflow output.imageUrl -> Generation.resultUrl
154
+ runtime failure -> Generation.errorMessage
155
+ runtime status -> Generation.status
156
+ ```
157
+
158
+ After AI and database manifests are synced, app implementation can read the SDK track to wire the
159
+ runtime calls.
160
+
161
+ ## Unsupported AI Behavior
162
+
163
+ If a user explicitly requires behavior not available in the workflow service, stop that AI path.
164
+
165
+ Do not:
166
+
167
+ - fake AI with static templates;
168
+ - hide the unsupported part;
169
+ - build a UI that pretends the workflow exists;
170
+ - replace the requested capability with a different one without saying so;
171
+ - assume private APIs, external datasets, or providers that are not listed.
172
+
173
+ Correct response:
174
+
175
+ ```text
176
+ This exact AI behavior needs <missing capability>. The current workflow service supports <closest
177
+ available capability>. I can build <narrow supported version>, or we need platform support for
178
+ <missing capability> first.
179
+ ```
180
+
181
+ ## Capability Naming
182
+
183
+ Use stable JavaScript-safe IDs:
184
+
185
+ ```text
186
+ generateIllustration
187
+ summarizeDocument
188
+ researchNewsBriefing
189
+ editProductPhoto
190
+ transcribeAudio
191
+ ```
192
+
193
+ Avoid:
194
+
195
+ - display labels with spaces;
196
+ - names that collide with base methods: `run`, `stream`, `events`;
197
+ - provider names: `openAiImage`, `geminiAnalyze`;
198
+ - implementation names: `searchThenSummarize`.
199
+
200
+ The description can be human readable. The ID must be stable for codegen.
201
+
202
+ ## AI Architecture Checklist
203
+
204
+ Before editing files:
205
+
206
+ - Feature maps to available workflow capabilities.
207
+ - One workflow per feature unless RAG.
208
+ - Description says what the user gets, not how tools run.
209
+ - Input schema accepts URLs for files, not raw bytes.
210
+ - Output schema contains only requested result fields.
211
+ - Input and output property names do not overlap.
212
+ - Text output descriptions specify language behavior.
213
+ - Persistence is modeled as entity schema, not workflow CRUD.
214
+ - `workflowId` / EAX `config_id` values are generated by tools and not guessed.
215
+ - SDK binding will be generated only after manifest sync.