@howone/agent-cli 0.0.0-stage → 0.5.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 (228) hide show
  1. package/README.md +34 -2
  2. package/bin/index.d.mts +1 -0
  3. package/bin/index.mjs +2450 -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,128 @@
1
+ # Raw HTTP
2
+
3
+ Use `howone.raw` only for an app-owned endpoint that has no typed entity, auth, upload, or AI
4
+ binding. Do not use it to bypass manifest access rules or recreate `/data` and workflow calls.
5
+
6
+ ## Contract
7
+
8
+ `howone.raw` is a request client whose methods resolve to response **data**, not an AxiosResponse:
9
+
10
+ ```ts
11
+ const data = await howone.raw.get<Stats>({ url: '/custom/stats' })
12
+ const created = await howone.raw.post<Receipt>({
13
+ url: '/custom/receipts',
14
+ data: { orderId },
15
+ })
16
+ ```
17
+
18
+ ```ts
19
+ type RequestConfig<T = unknown> = AxiosRequestConfig & {
20
+ interceptors?: {
21
+ requestInterceptor?: (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig
22
+ requestInterceptorCatch?: (error: unknown) => unknown
23
+ responseInterceptor?: (data: T) => T
24
+ responseInterceptorCatch?: (error: unknown) => unknown
25
+ }
26
+ }
27
+ ```
28
+
29
+ The SDK attaches the current client token to authenticated non-public requests. It does not turn
30
+ an app-owned route into a platform contract; the backend must authenticate and authorize it.
31
+
32
+ ## URL rules
33
+
34
+ The configured REST base already ends in `/api` for hosted environments. Use a path relative to that
35
+ base:
36
+
37
+ ```ts
38
+ // Correct: https://api.howone.dev/api/custom/stats
39
+ const stats = await howone.raw.get<Stats>({ url: '/custom/stats' })
40
+
41
+ // Wrong: https://api.howone.dev/api/api/custom/stats
42
+ // howone.raw.get({ url: '/api/custom/stats' })
43
+ ```
44
+
45
+ Never build a request URL from `howone.runtime.authRoot` / `VITE_HOWONE_AUTH_URL`. That origin is
46
+ the HowOne platform web app, used only for page navigation (login, pricing); its `/api/*` routes are
47
+ private to the platform, reject cross-origin calls from apps, and are not app contracts. Platform data
48
+ an app may read has a typed SDK method instead — for credits use `howone.credits.get()`
49
+ (`13-credits.md`).
50
+
51
+ An absolute URL is an explicit app-owned escape hatch and is not how EAX routing is selected. Do not
52
+ put an EAX URL in a raw request; AI actions already use `env`.
53
+
54
+ ## Query, headers, and cancellation
55
+
56
+ ```ts
57
+ const result = await howone.raw.get<SearchResult>({
58
+ url: '/custom/search',
59
+ params: { q, page: 1, limit: 20 },
60
+ headers: { 'X-Request-Source': 'app' },
61
+ signal: controller.signal,
62
+ })
63
+
64
+ // Cancels every in-flight request with this exact method-independent URL.
65
+ howone.raw.cancelRequest('/custom/search')
66
+ howone.raw.cancelAllRequests()
67
+ ```
68
+
69
+ Prefer an `AbortController` per component operation so a new search does not cancel an unrelated
70
+ request. The SDK links the caller's signal to its internal controller and also supports concurrent
71
+ requests with the same method and URL.
72
+
73
+ ```tsx
74
+ useEffect(() => {
75
+ const controller = new AbortController()
76
+ void howone.raw
77
+ .get<SearchResult>({ url: '/custom/search', params: { q }, signal: controller.signal })
78
+ .then(setResult)
79
+ .catch((error) => {
80
+ if (!controller.signal.aborted) setError(error instanceof Error ? error.message : String(error))
81
+ })
82
+ return () => controller.abort()
83
+ }, [q])
84
+ ```
85
+
86
+ ## Per-request interceptors
87
+
88
+ The response interceptor sees the already-unwrapped data:
89
+
90
+ ```ts
91
+ const data = await howone.raw.get<RawStats>({
92
+ url: '/custom/stats',
93
+ interceptors: {
94
+ requestInterceptor: (config) => {
95
+ config.headers.set('X-Request-Id', crypto.randomUUID())
96
+ return config
97
+ },
98
+ responseInterceptor: (value) => ({ ...value, loadedAt: Date.now() }),
99
+ responseInterceptorCatch: (error) => Promise.reject(error),
100
+ },
101
+ })
102
+ ```
103
+
104
+ Do not expect `value.status` or `value.data` in `responseInterceptor`; use the direct Axios instance
105
+ only when the installed SDK typings explicitly require a transport-level operation.
106
+
107
+ ## Choosing the correct surface
108
+
109
+ | Need | Use |
110
+ |---|---|
111
+ | Manifest entity CRUD/query | `howone.entities.Entity.*` |
112
+ | Manifest-approved public data | `howone.public.entities.Entity.*` |
113
+ | EAX workflow | `howone.ai.action.run/stream/events` |
114
+ | HowOne storage | `howone.upload.*` |
115
+ | App-owned backend route | `howone.raw.*` |
116
+
117
+ If the endpoint is missing from the platform contract, classify it as an explicit app-owned
118
+ integration. Do not call an internal platform route because it happens to work today.
119
+
120
+ ## Common mistakes
121
+
122
+ | Mistake | Fix |
123
+ |---|---|
124
+ | Reading `response.data` | Raw methods already return data. |
125
+ | Prefixing `/api` in a raw path | The REST base already includes `/api`. |
126
+ | Calling raw `/data/...` | Use generated entity bindings. |
127
+ | Passing `'*'` as a cross-window origin | Use explicit origins in the devtools Provider. |
128
+ | Cancelling by a broad substring | Use the exact request path or the caller's AbortSignal. |
@@ -0,0 +1,210 @@
1
+ # AI Action Calls
2
+
3
+ Use this track only after the AI capability has been applied, synced, submitted to EAX, and synced
4
+ again. `.howone/ai/manifest.json` is the source for action IDs, JSON schemas, and workflow config
5
+ UUIDs.
6
+
7
+ ## Binding order
8
+
9
+ 1. Read the current `.howone/ai/manifest.json`.
10
+ 2. Convert its input/output JSON Schemas to Zod without weakening required fields.
11
+ 3. Copy the exact manifest `workflowId` UUID.
12
+ 4. Define and compose the action in `src/lib/sdk.ts`.
13
+ 5. Run the project verifier, typecheck, and build.
14
+
15
+ ```ts
16
+ import { defineAiAction, defineAiActions } from '@howone/sdk'
17
+ import { z } from 'zod'
18
+
19
+ export const generateImageInputSchema = z.object({
20
+ prompt: z.string().min(1),
21
+ aspectRatio: z.enum(['1:1', '16:9']).optional(),
22
+ })
23
+
24
+ export const generateImageOutputSchema = z.object({
25
+ imageUrl: z.string().url(),
26
+ })
27
+
28
+ export const ai = defineAiActions({
29
+ generateImage: defineAiAction('generateImage', {
30
+ workflowId: 'd69ab648-2c00-4d94-928e-01bd7b2a5bb2',
31
+ inputSchema: generateImageInputSchema,
32
+ outputSchema: generateImageOutputSchema,
33
+ }),
34
+ })
35
+ ```
36
+
37
+ `workflowId` is required and validated as a UUID when the module loads. There is no action-name
38
+ fallback. Never guess, reuse an ID from another project, or continue with a placeholder.
39
+
40
+ Pass Zod schemas, not manifest JSON objects. With an `outputSchema`, `.run()` validates and returns
41
+ `run_complete.message` directly. Without one, `.run()` returns the raw `ExecutionResult`.
42
+
43
+ ## Four execution surfaces
44
+
45
+ ### `run`: exceptions are control flow
46
+
47
+ ```ts
48
+ try {
49
+ const output = await howone.ai.generateImage.run({ prompt })
50
+ setImageUrl(output.imageUrl)
51
+ } catch (error) {
52
+ if (error instanceof WorkflowExecutionError) {
53
+ console.error(error.outcome, error.runId, error.result.errors)
54
+ } else if (error instanceof AiSchemaValidationError) {
55
+ console.error(error.direction, error.issues)
56
+ }
57
+ throw error
58
+ }
59
+ ```
60
+
61
+ `run()` rejects for:
62
+
63
+ - input or output schema validation errors;
64
+ - HTTP/network/abort errors;
65
+ - a `run_error` terminal event;
66
+ - a `credit_insufficient` terminal event;
67
+ - a stream that closes without a terminal event.
68
+
69
+ Do not check `result.success` after a failed run; failure does not resolve. A successful typed action
70
+ returns the typed output, not the execution envelope.
71
+
72
+ ### `runSafe`: explicit result union
73
+
74
+ Use this when UI code prefers data-flow branching:
75
+
76
+ ```ts
77
+ const result = await howone.ai.generateImage.runSafe({ prompt })
78
+ if (!result.ok) {
79
+ setError(result.error.message)
80
+ return
81
+ }
82
+ setImageUrl(result.value.imageUrl)
83
+ ```
84
+
85
+ ```ts
86
+ type AiSafeResult<T> =
87
+ | { ok: true; value: T }
88
+ | { ok: false; error: Error }
89
+ ```
90
+
91
+ `runSafe()` catches the same errors that `run()` throws. Do not use it to silently ignore failures.
92
+
93
+ ### `stream`: callbacks plus a rejecting result promise
94
+
95
+ ```ts
96
+ const session = howone.ai.generateImage.stream(
97
+ { prompt },
98
+ {
99
+ onRunStart: () => setPhase('running'),
100
+ onMessageChunk: (line) => appendLog(line),
101
+ onRunComplete: (_event, result) => console.log(result.finalResult),
102
+ onCreditInsufficient: () => setPhase('blocked'),
103
+ onRunError: () => setPhase('failed'),
104
+ onError: (error) => console.error(error),
105
+ },
106
+ )
107
+
108
+ try {
109
+ const execution = await session.result
110
+ console.log(execution.finalResult)
111
+ } finally {
112
+ // cancel is idempotent and safe during cleanup.
113
+ session.cancel()
114
+ }
115
+ ```
116
+
117
+ `stream()` starts immediately. `session.result` resolves only on `run_complete`; it rejects on
118
+ terminal workflow errors, transport errors, and abort. For a typed action, `session.result` remains
119
+ the raw execution result because streaming callbacks/events expose protocol data. Use `.run()` when
120
+ the only desired result is the validated typed output.
121
+
122
+ ### `events`: ordered async iteration
123
+
124
+ ```ts
125
+ try {
126
+ for await (const event of howone.ai.generateImage.events({ prompt })) {
127
+ if (event.type === 'progress') appendLog(String(event.message))
128
+ if (event.type === 'run_complete') setOutput(event.message)
129
+ }
130
+ } catch (error) {
131
+ // On run_error/credit_insufficient, the terminal event was yielded before this rejection.
132
+ setError(error instanceof Error ? error.message : String(error))
133
+ }
134
+ ```
135
+
136
+ The iterable owns and cleans up its session. On terminal workflow failure it yields the terminal
137
+ event first, then rejects on the next iteration step. Breaking out of the loop cancels the request.
138
+
139
+ ## Callback semantics
140
+
141
+ ```ts
142
+ type AiOptions = {
143
+ onEvent?: (event: AiEvent, channel: 'workflow') => void
144
+ onDisplayEvent?: (event: WorkflowEventDisplay) => void
145
+ onRunStart?: (event: RunStartEvent) => void
146
+ onMessageChunk?: (text: string, event: ProgressEvent) => void
147
+ onProgress?: (percent: number, message?: string) => void
148
+ onRunComplete?: (event: RunCompleteEvent, result: AiResult) => void
149
+ onRunError?: (event: RunErrorEvent) => void
150
+ onCreditInsufficient?: (event: CreditInsufficientEvent) => void
151
+ onComplete?: (result: AiResult) => void
152
+ onError?: (error: Error) => void
153
+ signal?: AbortSignal
154
+ maxRetainedEvents?: number
155
+ maxRetainedProgressLogs?: number
156
+ }
157
+ ```
158
+
159
+ Use `onMessageChunk`; old names such as `onStreamChunk`, `onTextChunk`, or legacy multi-channel
160
+ callbacks do not exist. `onEvent` observes every event before terminal-specific callbacks and before
161
+ the result promise rejects. `onComplete` means a terminal event was assembled, including an error
162
+ terminal; inspect `result.outcome`. `onError` then receives the structured error.
163
+
164
+ Callbacks receive every event even when retained arrays are bounded. Defaults retain at most 1,000
165
+ raw events and 500 progress log lines, preventing long workflows from growing memory without bound.
166
+
167
+ ## Error classes
168
+
169
+ | Error | Meaning |
170
+ |---|---|
171
+ | `AiWorkflowConfigurationError` | binding has a missing/non-UUID workflow ID |
172
+ | `AiSchemaConfigurationError` | schema does not implement Zod `safeParse` |
173
+ | `AiSchemaValidationError` | input or final output violates the schema |
174
+ | `WorkflowExecutionError` | EAX emitted `run_error` or `credit_insufficient` |
175
+
176
+ For credit failures, use `error.outcome === 'credit_insufficient'`. SDK limit callbacks are signals;
177
+ the app owns visible upgrade UI. The SDK does not call `window.confirm` unless legacy
178
+ `showUpgradeToast: true` is explicitly enabled.
179
+
180
+ ## Persistence
181
+
182
+ For history-style products, create a pending entity before calling AI and persist completed/failed
183
+ state with `runAiActionAndPersist()`. Keep workflow execution free of database CRUD; entity writes
184
+ belong to app code.
185
+
186
+ ```ts
187
+ await runAiActionAndPersist({
188
+ entity: howone.entities.Generation,
189
+ input,
190
+ createPending: ({ prompt }) => ({ prompt, status: 'pending' }),
191
+ run: (value) => howone.ai.generateImage.run(value),
192
+ mapCompleted: ({ output }) => ({ status: 'completed', imageUrl: output.imageUrl }),
193
+ mapFailed: ({ error }) => ({
194
+ status: 'failed',
195
+ errorMessage: error instanceof Error ? error.message : String(error),
196
+ }),
197
+ })
198
+ ```
199
+
200
+ ## Common mistakes
201
+
202
+ | Mistake | Fix |
203
+ |---|---|
204
+ | Omitting `workflowId` | Re-read the synced manifest; module initialization now throws. |
205
+ | Adding `mode: 'run'` to the action | Every action exposes run/runSafe/stream/events; no mode option exists. |
206
+ | Reading `.finalResult` from a typed `.run()` | Use the returned typed output directly. |
207
+ | Expecting `stream.result` to be typed output | It is the raw execution result. |
208
+ | Swallowing `session.result` | Always await/catch it to avoid unhandled rejection. |
209
+ | Weakening output Zod after validation fails | Fix the manifest/workflow mismatch. |
210
+ | Writing an EAX URL | Set only client `env`; the SDK owns the endpoint mapping. |
@@ -0,0 +1,90 @@
1
+ # AI Manifest Handoff
2
+
3
+ Use this track after `sync_ai_artifacts` and external workflow submission. It is the short handoff
4
+ from `.howone/ai/manifest.json` to `src/lib/sdk.ts`; use `07-ai-action-calls.md` for execution
5
+ semantics and `10-workflow-execute-sse.md` for wire details.
6
+
7
+ ## Handoff protocol
8
+
9
+ 1. Read the current manifest, not a cached tool response.
10
+ 2. Confirm every action has an exact UUID `workflowId`.
11
+ 3. Generate Zod input/output schemas from the manifest.
12
+ 4. Bind with `defineAiAction` and compose with `withAiActions`.
13
+ 5. Run `node .howone/skills/howone/scripts/verify-project.mjs`, typecheck, and build.
14
+
15
+ Workflow create/update can rotate the config UUID. After every successful external workflow
16
+ operation, sync and re-read the manifest before deciding whether the app binding changed.
17
+
18
+ There is no action-name fallback. A missing UUID is a module initialization error, not a server
19
+ request that can be repaired later.
20
+
21
+ ## Example
22
+
23
+ ```ts
24
+ import { createClient, defineAiAction, defineAiActions, withAiActions } from '@howone/sdk'
25
+ import { z } from 'zod'
26
+
27
+ const client = createClient({
28
+ projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
29
+ env: import.meta.env.VITE_HOWONE_ENV,
30
+ })
31
+
32
+ const inputSchema = z.object({ documentUrl: z.string().url() })
33
+ const outputSchema = z.object({ summary: z.string() })
34
+
35
+ const ai = defineAiActions({
36
+ summarizeDocument: defineAiAction('summarizeDocument', {
37
+ workflowId: '550e8400-e29b-41d4-a716-446655440000',
38
+ inputSchema,
39
+ outputSchema,
40
+ }),
41
+ })
42
+
43
+ const howone = withAiActions(client, ai)
44
+ export default howone
45
+ ```
46
+
47
+ The UUID above is illustrative only. Copy the real value from the current manifest.
48
+
49
+ ## Schema conversion rules
50
+
51
+ | JSON Schema | Zod |
52
+ |---|---|
53
+ | string | `z.string()` |
54
+ | string URI | `z.string().url()` |
55
+ | number/integer | `z.number()` / `z.number().int()` |
56
+ | boolean | `z.boolean()` |
57
+ | array | `z.array(item)` |
58
+ | object | `z.object({ ... })` |
59
+ | enum | `z.enum([...])` |
60
+ | nullable | `z.nullable(...)` |
61
+ | not required | `.optional()` |
62
+
63
+ Do not make required fields optional and do not use `.passthrough()` to conceal a workflow result
64
+ shape mismatch. Typed `.run()` returns the validated final result directly.
65
+
66
+ ## Result handoff
67
+
68
+ ```ts
69
+ const output = await howone.ai.summarizeDocument.run({ documentUrl })
70
+ await howone.entities.DocumentSummary.create({
71
+ documentUrl,
72
+ summary: output.summary,
73
+ status: 'completed',
74
+ })
75
+ ```
76
+
77
+ For history, use pending-first `runAiActionAndPersist`. The workflow does not perform database CRUD;
78
+ the app persists through generated entity bindings.
79
+
80
+ For streaming, use `onMessageChunk`, await `session.result`, and catch terminal workflow errors.
81
+ For events, a terminal error event is yielded before the iterator rejects.
82
+
83
+ ## Final checklist
84
+
85
+ - [ ] Current AI manifest was read after the last sync.
86
+ - [ ] Action IDs and UUIDs match exactly.
87
+ - [ ] Zod requiredness/enums match the manifest.
88
+ - [ ] No `aiUrl`, `aiBaseUrl`, or raw EAX URL was added.
89
+ - [ ] App uses `HowOneProvider client={howone}`.
90
+ - [ ] Verifier, typecheck, and build pass.
@@ -0,0 +1,226 @@
1
+ # SDK Extension Boundaries
2
+
3
+ This reference defines the long-term shape of `@howone/sdk`. Use it whenever changing SDK APIs,
4
+ adding new capabilities, or deciding whether behavior belongs in the SDK or in the generated app.
5
+
6
+ ## North Star
7
+
8
+ The SDK is an AI-first runtime, not an app UI framework.
9
+
10
+ It should provide:
11
+
12
+ - stable defaults that work with almost no configuration;
13
+ - typed clients for HowOne platform capabilities;
14
+ - adapters for custom behavior;
15
+ - callbacks/events for app UI;
16
+ - predictable names that AI agents can reuse without guessing.
17
+
18
+ It should not provide:
19
+
20
+ - app-owned pages, modals, toasts, or business UI;
21
+ - hardcoded app flows beyond HowOne platform defaults;
22
+ - hidden persistence side effects;
23
+ - provider-specific branches scattered through feature code.
24
+
25
+ ## Default + Adapter Rule
26
+
27
+ Every platform capability should follow the same shape:
28
+
29
+ ```ts
30
+ createClient({
31
+ projectId,
32
+ env,
33
+ auth: 'hosted', // default
34
+ })
35
+ ```
36
+
37
+ Advanced usage should opt into typed adapters:
38
+
39
+ ```ts
40
+ createClient({
41
+ projectId,
42
+ env,
43
+ auth: {
44
+ mode: 'headless',
45
+ adapter: {
46
+ getToken: () => externalAuth.getToken(),
47
+ setToken: (token) => externalAuth.setToken(token),
48
+ login: ({ returnUrl }) => appRouter.push(`/login?redirect=${encodeURIComponent(returnUrl ?? '/')}`),
49
+ logout: () => appRouter.push('/'),
50
+ },
51
+ },
52
+ })
53
+ ```
54
+
55
+ Do not add one-off flags when an adapter/callback can express the behavior.
56
+
57
+ ## Capability Boundaries
58
+
59
+ | Capability | SDK owns | App owns |
60
+ |---|---|---|
61
+ | Auth | token source, session state, login/logout destination policy, hosted HowOne defaults | login page visuals, account menu, loading states, auth error UI |
62
+ | React provider | context, auth callbacks, optional bottom-right HowOne `FloatingButton` logo | layout, toasts, overlays, route components, theme system |
63
+ | Entities | typed CRUD/query clients, public/private routing, payload normalization | forms, list rendering, optimistic UI, field-level UX |
64
+ | Schema | definition operations, apply/version/restore calls | migration approval UI, admin experience |
65
+ | Entity contract utilities | payload whitelisting, public query guardrail validation, structured validation issues | deciding product copy, rendering validation errors |
66
+ | AI workflows | run/stream/events, Zod validation, workflowId binding | progress UI, result rendering, failure surfaces |
67
+ | AI persistence | pending-first orchestration helper, state callbacks, completed/failed mapping hook | choosing schema fields, retry UX, visible state UI |
68
+ | Upload | file/image/batch helpers and callbacks | picker UI, previews, validation copy, uploaded-file placement |
69
+ | Raw HTTP | low-level escape hatch | choosing it only when typed SDK surface does not exist |
70
+
71
+ ## React Provider Boundary
72
+
73
+ `HowOneProvider` may render the HowOne bottom-right logo via `FloatingButton`. This is platform
74
+ branding and should remain visible by default.
75
+
76
+ It must not render:
77
+
78
+ - toast notifications;
79
+ - redirect overlays;
80
+ - login/register forms;
81
+ - payment dialogs;
82
+ - app theme wrappers;
83
+ - app-specific navigation.
84
+
85
+ Use callbacks instead:
86
+
87
+ ```tsx
88
+ <HowOneProvider
89
+ client={howone}
90
+ brand="visible"
91
+ onAuthRedirect={({ mode, returnUrl }) => {
92
+ setAuthUi({ redirecting: true, mode, returnUrl })
93
+ }}
94
+ onAuthStateChange={(state) => {
95
+ setCurrentUser(state.user)
96
+ }}
97
+ >
98
+ <App />
99
+ </HowOneProvider>
100
+ ```
101
+
102
+ Hide the logo only when explicitly requested:
103
+
104
+ ```tsx
105
+ <HowOneProvider client={howone} brand="hidden" />
106
+ <HowOneProvider client={howone} showBrandButton={false} />
107
+ ```
108
+
109
+ ## UI Feedback Rule
110
+
111
+ Do not add `ClayxToast`, `toast`, or any visible notification API to `@howone/sdk`.
112
+
113
+ Generated apps should write their own UI from SDK results:
114
+
115
+ ```ts
116
+ setStatus({ type: 'loading', message: 'Generating...' })
117
+
118
+ try {
119
+ const output = await howone.ai.generateImage.run({ prompt })
120
+ setStatus({ type: 'success', message: 'Done', output })
121
+ } catch (error) {
122
+ setStatus({
123
+ type: 'error',
124
+ message: error instanceof Error ? error.message : 'Generation failed',
125
+ })
126
+ }
127
+ ```
128
+
129
+ For streaming workflows, use callbacks/events:
130
+
131
+ ```ts
132
+ const session = howone.ai.generateImage.stream(
133
+ { prompt },
134
+ {
135
+ onMessageChunk: (delta) => appendLog(delta),
136
+ onProgress: (progress) => setProgress(progress),
137
+ onError: (error) => setStatus({ type: 'error', message: error.message }),
138
+ onComplete: (result) => setResult(result.finalResult),
139
+ },
140
+ )
141
+ ```
142
+
143
+ ## Auth Adapter Contract
144
+
145
+ Use `AuthAdapter` for custom/headless auth. It is the only supported extension point for token
146
+ ownership outside the SDK defaults.
147
+
148
+ ```ts
149
+ type AuthAdapter = {
150
+ name?: string
151
+ getToken?: () => string | null | Promise<string | null>
152
+ setToken?: (token: string | null) => void | Promise<void>
153
+ getUser?: (token: string | null) => AuthUser | null | Promise<AuthUser | null>
154
+ login?: (options?: { returnUrl?: string }) => void | Promise<void>
155
+ logout?: (options?: { redirect?: false | string | { url: string; external?: boolean } }) => void | Promise<void>
156
+ clearSession?: (options?: { redirect?: false | string | { url: string; external?: boolean } }) => void | Promise<void>
157
+ subscribe?: (listener: (state: AuthState) => void) => (() => void) | void
158
+ }
159
+ ```
160
+
161
+ Rules:
162
+
163
+ - Default hosted auth must work without an adapter.
164
+ - External providers must use `mode: 'headless'` plus `adapter`.
165
+ - Custom in-app HowOne login should usually use `mode: 'custom'`, `loginPath`, and SDK OTP/OAuth helpers.
166
+ - `client.me()` and `client.requireMe()` are the canonical user APIs.
167
+ - `client.auth.isAuthenticated()` is a quick token check, not a first-load user fetch.
168
+
169
+ ## AI Agent Design Rules
170
+
171
+ Generated app code should have one stable SDK singleton:
172
+
173
+ ```ts
174
+ import howone from '@/lib/sdk'
175
+ ```
176
+
177
+ Agents should prefer:
178
+
179
+ 1. `howone.entities.*` for private/authenticated data;
180
+ 2. `howone.public.entities.*` for public access;
181
+ 3. `pickEntityPayload()` / `assertEntityPayload()` when mapping broad UI or AI objects to entity writes;
182
+ 4. `assertPublicEntityQuery()` when generated code has access to the synced definition;
183
+ 5. `howone.ai.*` for workflow execution;
184
+ 6. `runAiActionAndPersist()` when the product needs durable AI history;
185
+ 7. `howone.upload.*` for files;
186
+ 8. `howone.schema.*` for schema tools;
187
+ 9. `howone.raw` only as escape hatch.
188
+
189
+ Agents must not:
190
+
191
+ - hardcode HowOne URLs;
192
+ - manually build workflow SSE URLs;
193
+ - call workflows by display name instead of UUID;
194
+ - persist UI-only or workflow-extra fields;
195
+ - add frontend UI APIs to the SDK;
196
+ - remove the default HowOne floating logo unless explicitly asked.
197
+
198
+ ## Adding New SDK Capabilities
199
+
200
+ When adding a new capability, choose one of these shapes:
201
+
202
+ ```ts
203
+ client.capability.method(input, options)
204
+ client.capability.stream(input, callbacks)
205
+ client.capability.configure(adapter)
206
+ ```
207
+
208
+ Prefer these names:
209
+
210
+ - `run` for one-shot AI/workflow execution;
211
+ - `stream` for session-based execution with callbacks;
212
+ - `events` for async iterables;
213
+ - `query/list/get/create/update/delete` for entities;
214
+ - `configure` only for adapters, not app UI.
215
+
216
+ Keep returned values serializable and obvious. AI agents should be able to inspect the method name
217
+ and infer the contract.
218
+
219
+ ## Compatibility Rule
220
+
221
+ Do not break existing generated apps lightly. Prefer:
222
+
223
+ - add new adapter/callback options;
224
+ - keep old string shorthand (`auth: 'custom'`) working;
225
+ - mark old UI props as deprecated/no-op only when needed;
226
+ - update this skill and the relevant numbered reference in the same change.