@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,275 @@
1
+ # AI Feature Playbooks
2
+
3
+ Use this reference when turning a user request into concrete HowOne AI capabilities and optional
4
+ persistence entities. App-side SDK calls belong to `04-app-sdk/`.
5
+
6
+ ## Playbook: Document Summary
7
+
8
+ Use when user uploads or links a document and wants a summary.
9
+
10
+ Capability:
11
+
12
+ ```json
13
+ {
14
+ "name": "summarizeDocument",
15
+ "description": "Reads an uploaded document and produces a concise summary highlighting the key points.",
16
+ "inputSchema": {
17
+ "type": "object",
18
+ "properties": {
19
+ "document_url": {
20
+ "type": "string",
21
+ "format": "uri",
22
+ "description": "Supabase Storage URL of the uploaded document."
23
+ },
24
+ "summary_length": {
25
+ "type": "string",
26
+ "description": "Desired summary length, e.g. short, medium, long, or a specific sentence count."
27
+ }
28
+ },
29
+ "required": ["document_url"]
30
+ },
31
+ "outputSchema": {
32
+ "type": "object",
33
+ "properties": {
34
+ "summary": {
35
+ "type": "string",
36
+ "description": "Summary in the same language as the source document."
37
+ }
38
+ },
39
+ "required": ["summary"]
40
+ },
41
+ "outputEntityName": "DocumentSummary"
42
+ }
43
+ ```
44
+
45
+ Persistence:
46
+
47
+ - private `DocumentSummary` if user history is needed;
48
+ - fields: `documentUrl`, `summary`, `status`, `errorMessage`, `requestedAt`, `completedAt`.
49
+
50
+ App implementation handoff: after sync and external workflow submit, read the SDK track before
51
+ writing app-side AI runtime calls.
52
+
53
+ ## Playbook: Image Generator
54
+
55
+ Use for prompt-to-image products.
56
+
57
+ Capability:
58
+
59
+ ```json
60
+ {
61
+ "name": "generateImage",
62
+ "description": "Generates an image based on a natural language description provided by the user.",
63
+ "inputSchema": {
64
+ "type": "object",
65
+ "properties": {
66
+ "image_description": {
67
+ "type": "string",
68
+ "description": "Detailed description of the image to generate, including subject, style, mood, and composition."
69
+ },
70
+ "style_preference": {
71
+ "type": "string",
72
+ "description": "Optional style preference such as watercolor, photorealistic, anime, or flat design."
73
+ }
74
+ },
75
+ "required": ["image_description"]
76
+ },
77
+ "outputSchema": {
78
+ "type": "object",
79
+ "properties": {
80
+ "generated_image_url": {
81
+ "type": "string",
82
+ "format": "uri",
83
+ "description": "Public URL of the generated image."
84
+ }
85
+ },
86
+ "required": ["generated_image_url"]
87
+ },
88
+ "outputEntityName": "GeneratedImage"
89
+ }
90
+ ```
91
+
92
+ Persistence:
93
+
94
+ - use `Generation` for private history;
95
+ - public share requires separate `SharedGeneration`.
96
+
97
+ App implementation handoff: if persistence is needed, finish the entity contract first, then read
98
+ the SDK track for runtime action calls and persistence helper usage.
99
+
100
+ ## Playbook: Image Editor
101
+
102
+ Use when user uploads/selects an image and describes edits.
103
+
104
+ Inputs:
105
+
106
+ - `source_image_url`;
107
+ - `edit_instruction`.
108
+
109
+ Output:
110
+
111
+ - `edited_image_url`.
112
+
113
+ Rules:
114
+
115
+ - app uploads source file first;
116
+ - workflow receives URL only;
117
+ - keep edit instruction focused;
118
+ - persist both original and edited URLs if history matters.
119
+
120
+ ## Playbook: News/Research Briefing
121
+
122
+ Use for latest info or source-backed research.
123
+
124
+ Inputs:
125
+
126
+ - `topic`;
127
+ - optional `language`;
128
+ - optional `depth` as loose string, not strict enum unless UI really has fixed modes.
129
+
130
+ Output:
131
+
132
+ - structured `briefing` object with `summary` and `sources`.
133
+
134
+ Rules:
135
+
136
+ - use web search/crawling capability;
137
+ - include source URLs;
138
+ - output descriptions must specify language;
139
+ - if user asks for latest/current, this workflow must retrieve data internally.
140
+
141
+ ## Playbook: Stock Analysis
142
+
143
+ Use for historical price analysis.
144
+
145
+ Inputs:
146
+
147
+ - `trading_symbol`;
148
+ - `start`;
149
+ - `end`;
150
+ - `unit`: daily/minute when UI exposes it.
151
+
152
+ Output:
153
+
154
+ - `analysis`;
155
+ - optional `price_history` only if app renders chart from workflow output.
156
+
157
+ Rules:
158
+
159
+ - do not ask user for CSV unless they explicitly have data;
160
+ - historical only, no real-time streaming;
161
+ - combine with web search only if user asks for news/context.
162
+
163
+ ## Playbook: Academic Literature Review
164
+
165
+ Use for paper search and bibliography.
166
+
167
+ Inputs:
168
+
169
+ - `query`;
170
+ - optional `language` for synthesized review;
171
+ - optional `citation_style`.
172
+
173
+ Outputs:
174
+
175
+ - `papers`;
176
+ - `review_summary`;
177
+ - `bibtex` if citations are needed.
178
+
179
+ Rules:
180
+
181
+ - do not promise full PDF availability;
182
+ - keep paper metadata fields useful and minimal;
183
+ - use source URLs/DOIs when returned.
184
+
185
+ ## Playbook: Audio Transcription
186
+
187
+ Use for speech-to-text.
188
+
189
+ Inputs:
190
+
191
+ - `source_audio_url`;
192
+ - optional `language`;
193
+ - optional `with_speaker_info`.
194
+
195
+ Outputs:
196
+
197
+ - `transcript_text`;
198
+ - optional `utterances`.
199
+
200
+ Rules:
201
+
202
+ - app uploads audio first;
203
+ - workflow receives URL;
204
+ - if speaker diarization is not required, do not add utterances.
205
+
206
+ ## Playbook: Text To Speech
207
+
208
+ Use for generating spoken audio from text.
209
+
210
+ Inputs:
211
+
212
+ - `text_to_generate`;
213
+ - `language`;
214
+ - optional `gender`;
215
+ - optional `audio_hint`.
216
+
217
+ Output:
218
+
219
+ - `audio_url`.
220
+
221
+ Rules:
222
+
223
+ - single speaker per call;
224
+ - dialogue should generate multiple clips and merge;
225
+ - persist audio URL through entity if user needs library/history.
226
+
227
+ ## Playbook: Video Generator
228
+
229
+ Use for short video creation.
230
+
231
+ Inputs:
232
+
233
+ - `video_prompt`;
234
+ - optional `first_frame_url`;
235
+ - optional `aspect_ratio`;
236
+ - optional `duration`.
237
+
238
+ Output:
239
+
240
+ - `video_url`.
241
+
242
+ Rules:
243
+
244
+ - keep one clip short;
245
+ - for longer output, compose multiple clips and concatenate;
246
+ - first-frame image helps consistency.
247
+
248
+ ## RAG Playbook
249
+
250
+ Use only when app needs question answering over user/project documents.
251
+
252
+ Workflows:
253
+
254
+ 1. `indexDocuments`
255
+ - input: document URLs or collection reference;
256
+ - output: indexing result/status.
257
+ 2. `queryKnowledgeBase`
258
+ - input: question + knowledge base reference;
259
+ - output: answer + sources.
260
+
261
+ Rules:
262
+
263
+ - RAG is the only standard two-workflow exception.
264
+ - Do not re-index on every question.
265
+ - Persist document/index status in entities if app needs history or dashboard.
266
+
267
+ ## Feature Design Checklist
268
+
269
+ - Choose one playbook or clearly combine compatible playbooks.
270
+ - Verify capability exists in `03-service-capability-catalog.md`.
271
+ - Use URL inputs for files/media.
272
+ - Keep outputs minimal and product-facing.
273
+ - Decide persistence separately.
274
+ - Generate SDK bindings only after manifest sync and external workflow submit.
275
+ - Use app-owned UI for progress/errors.
@@ -0,0 +1,162 @@
1
+ # Client Setup
2
+
3
+ Use this track after synced manifests exist and before writing app code that imports
4
+ `@howone/sdk`. Read [version-evidence.md](../../references/version-evidence.md) first when the installed
5
+ SDK version is uncertain.
6
+
7
+ ## One client, one source of truth
8
+
9
+ Create the client once at module scope in `src/lib/sdk.ts`. Use the same composed instance for
10
+ entities, AI, uploads, auth, and raw requests. Do not create clients inside components or handlers.
11
+
12
+ ```ts
13
+ // src/lib/sdk.ts
14
+ import {
15
+ createClient,
16
+ defineAiActions,
17
+ defineEntities,
18
+ withAiActions,
19
+ withEntities,
20
+ } from '@howone/sdk'
21
+
22
+ const client = createClient({
23
+ projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
24
+ env: import.meta.env.VITE_HOWONE_ENV,
25
+ })
26
+
27
+ export const entities = defineEntities({
28
+ // Generated bindings go here; read 01-architect/02-manifest-codegen.md.
29
+ })
30
+ export const ai = defineAiActions({})
31
+
32
+ const howone = withAiActions(withEntities(client, entities), ai)
33
+ export default howone
34
+ ```
35
+
36
+ `projectId` is required. Missing or invalid Vite variables must fail loudly; do not add empty
37
+ fallbacks such as `?? ''` or silently default the environment to production.
38
+
39
+ ## Environment-owned routing
40
+
41
+ `env` selects the complete deployment target. The REST API, auth endpoints, uploads, and EAX
42
+ workflow endpoint must use the same environment. EAX URLs are intentionally not configurable per
43
+ request or through `createClient`:
44
+
45
+ | `env` | REST base | EAX workflow base |
46
+ |---|---|---|
47
+ | `local` | `http://localhost:3002/api` | `http://eax-dev-orchestrator.default.svc.cluster.local` |
48
+ | `dev` | `https://api.howone.dev/api` | `http://eax-dev-orchestrator.default.svc.cluster.local` |
49
+ | `prod` | `https://api.howone.ai/api` | `https://eax-backend-orchestrator-prod.fly.dev` |
50
+
51
+ Never add `aiUrl`, `aiBaseUrl`, or an EAX URL environment variable. If a special deployment needs a
52
+ different REST API, `apiUrl` is the only supported URL override; it does not change EAX routing.
53
+
54
+ The selected values are inspectable without guessing:
55
+
56
+ ```ts
57
+ howone.runtime.environment // 'local' | 'dev' | 'prod'
58
+ howone.runtime.apiBaseUrl
59
+ howone.runtime.aiBaseUrl
60
+ howone.runtime.authRoot
61
+ howone.runtime.authCookieRoot
62
+ ```
63
+
64
+ `howone.runtime` is immutable. A second client created later cannot retarget an existing client's
65
+ requests. Prefer one client per app; if tests create several, assert each client's runtime.
66
+
67
+ ## Options that matter
68
+
69
+ ```ts
70
+ type CreateClientOptions = {
71
+ projectId?: string
72
+ env?: 'local' | 'dev' | 'prod' | string
73
+ apiUrl?: string // REST-only exceptional override
74
+ apiBaseUrl?: string // deprecated alias for apiUrl
75
+ appId?: string // deprecated alias for projectId
76
+ caseStyle?: 'camel' | 'snake' // default 'camel'
77
+ caseDepth?: 'top-level' | 'deep' // default 'top-level'
78
+ auth?: 'hosted' | 'custom' | 'headless' | 'none' | {
79
+ mode?: 'hosted' | 'custom' | 'headless' | 'none'
80
+ guard?: 'required' | 'optional' | 'none'
81
+ loginPath?: string
82
+ logoutPath?: string
83
+ getToken?: () => Promise<string | null>
84
+ adapter?: AuthAdapter
85
+ tokenCacheMs?: number
86
+ }
87
+ loginPath?: string
88
+ logoutPath?: string
89
+ authRequired?: boolean // deprecated compatibility alias
90
+ limitExceeded?: LimitExceededHandlerOptions
91
+ }
92
+ ```
93
+
94
+ Do not use the removed `mode: 'auto' | 'standalone' | 'embedded'` option. That was not a runtime
95
+ behavior switch. Authentication mode belongs under `auth.mode` and means hosted/custom/headless/none.
96
+
97
+ ## Authentication posture
98
+
99
+ ```ts
100
+ // Hosted login (default): Provider inherits a required guard.
101
+ createClient({ projectId, env })
102
+
103
+ // App-owned login page using HowOne auth APIs.
104
+ createClient({ projectId, env, auth: 'custom', loginPath: '/login' })
105
+
106
+ // External identity provider; adapter supplies a token.
107
+ createClient({
108
+ projectId,
109
+ env,
110
+ auth: {
111
+ mode: 'headless',
112
+ adapter: {
113
+ getToken: () => externalAuth.getToken(),
114
+ setToken: (token) => externalAuth.setToken(token),
115
+ },
116
+ },
117
+ })
118
+
119
+ // Deliberately public app.
120
+ createClient({ projectId, env, auth: 'none' })
121
+ ```
122
+
123
+ `HowOneProvider` receives `client={howone}` and derives its default route guard from
124
+ `client.auth.guard`. Override `auth="required|optional|none"` only when the UI intentionally needs
125
+ a different guard. Do not configure auth once on the client and independently guess it on the
126
+ Provider.
127
+
128
+ ## Compose manifest bindings
129
+
130
+ Use contract wrappers for generated entities and actions. Public bindings are a separate namespace;
131
+ never call an authenticated entity client from a public page just because the entity name matches.
132
+
133
+ ```ts
134
+ const howone = withAiActions(
135
+ withPublicEntities(
136
+ withEntities(client, entities),
137
+ publicEntities,
138
+ ),
139
+ ai,
140
+ )
141
+ ```
142
+
143
+ The exact generated composition belongs in `01-architect/02-manifest-codegen.md`.
144
+
145
+ ## Runtime activation checklist
146
+
147
+ - Keep `src/lib/sdk.ts` imported before rendering `HowOneProvider`.
148
+ - Add a Provider whenever app code uses entities, AI, uploads, auth, session, or raw SDK requests.
149
+ - Use `auth: 'none'` only for a deliberately public app or when the app owns its route guard.
150
+ - Use real token acquisition for authenticated AI/entity/upload calls; do not substitute mock data.
151
+ - Run `node .howone/skills/howone/scripts/verify-project.mjs` before typecheck/build.
152
+
153
+ ## Common mistakes
154
+
155
+ | Mistake | Correct pattern |
156
+ |---|---|
157
+ | AI URL in `.env` or `createClient` | Set only `env`; EAX is environment-owned. |
158
+ | `HowOneProvider` without the composed client | `<HowOneProvider client={howone}>`. |
159
+ | Client created in a component | Module-level singleton in `src/lib/sdk.ts`. |
160
+ | Using `apiUrl` to point at EAX | `apiUrl` is REST-only; EAX remains the env mapping. |
161
+ | Passing a JSON Schema object to an AI action | Generate a Zod schema first. |
162
+ | Calling `client.entities.Unknown` after strict codegen | Use `client.entity<T...>('Unknown')` only for an explicit, reviewed escape hatch. |
@@ -0,0 +1,163 @@
1
+ # Entity Operations
2
+
3
+ Use generated bindings from `src/lib/sdk.ts` for manifest entities. Read
4
+ `01-architect/02-manifest-codegen.md` before adding or changing a binding.
5
+
6
+ ## Authenticated entities
7
+
8
+ ```ts
9
+ import howone from '@/lib/sdk'
10
+
11
+ const created = await howone.entities.Todo.create({
12
+ title: 'Ship the agent app',
13
+ status: 'pending',
14
+ })
15
+ const item = await howone.entities.Todo.get(created.id)
16
+ const updated = await howone.entities.Todo.update(created.id, { status: 'done' })
17
+ await howone.entities.Todo.delete(created.id)
18
+ ```
19
+
20
+ The generated entity contract validates business fields before writes. System fields and ownership
21
+ fields are not app inputs. The backend derives ownership from the authenticated token.
22
+
23
+ If the manifest says an operation is `none`, its generated client does not expose that method.
24
+ Treat a missing property as a contract signal; do not cast it to `any` or call raw `/data` routes.
25
+
26
+ ## Queries
27
+
28
+ ```ts
29
+ const result = await howone.entities.Todo.query({
30
+ where: {
31
+ status: 'pending',
32
+ title: { contains: 'agent' },
33
+ },
34
+ page: { number: 1, size: 20 },
35
+ orderBy: { updatedDate: 'desc' },
36
+ })
37
+
38
+ result.items // TodoRecord[]
39
+ result.page.total
40
+ result.page.hasNext
41
+ ```
42
+
43
+ Use the typed `where` object. Supported operators include `eq`, `ne`, `gt`, `gte`, `lt`, `lte`,
44
+ `contains`, `startsWith`, `endsWith`, `in`, `notIn`, `null`, `empty`, and `exists` (subject to the
45
+ backend contract):
46
+
47
+ ```ts
48
+ await howone.entities.Todo.query({
49
+ where: {
50
+ priority: { gte: 3, lte: 5 },
51
+ tags: { in: ['ai', 'agent'] },
52
+ },
53
+ })
54
+ ```
55
+
56
+ Generated Record types are strict. Unknown field names in `where` and `orderBy` should fail at
57
+ typecheck. If an app needs an untyped escape hatch, review it explicitly and keep it at a boundary;
58
+ do not widen every generated record.
59
+
60
+ ### Current user's records
61
+
62
+ ```ts
63
+ const mine = await howone.entities.Generation.query.mine({
64
+ page: { number: 1, size: 20 },
65
+ orderBy: { createdDate: 'desc' },
66
+ })
67
+ ```
68
+
69
+ `query.mine()` verifies that a usable token exists. Never add `created_by_id`, `createdById`,
70
+ `ownerId`, or `puid` to the query. The server owns that scope.
71
+
72
+ ### Include and pagination
73
+
74
+ ```ts
75
+ await howone.entities.Project.query({
76
+ include: ['owner', 'latestGeneration'],
77
+ page: { number: 2, size: 25 },
78
+ exactCount: true,
79
+ })
80
+ ```
81
+
82
+ Relation names must come from the manifest. Use `query()` when pagination metadata matters and
83
+ `list()` only for a simple array read where the API contract permits it.
84
+
85
+ ## Public entities
86
+
87
+ Public bindings are generated separately and are guarded against manifest filters, sorts, limits,
88
+ and scopes:
89
+
90
+ ```ts
91
+ const articles = await howone.public.entities.Article.query({
92
+ where: { status: 'published' },
93
+ orderBy: { publishedAt: 'desc' },
94
+ page: { number: 1, size: 20 },
95
+ })
96
+ ```
97
+
98
+ For `access.public.read: 'scoped'`, use the generated scoped method and provide every required
99
+ scope under `where`:
100
+
101
+ ```ts
102
+ const profile = await howone.public.entities.Profile.query.scoped({
103
+ where: { shareId, active: true },
104
+ page: { number: 1, size: 1 },
105
+ })
106
+ ```
107
+
108
+ `queryScoped(options)` is also available. Public create/update methods exist only when the manifest
109
+ allows them. Public queries are never a way to bypass authenticated access.
110
+
111
+ ## Payload utilities
112
+
113
+ Use these when mapping broad UI state or AI output to an entity payload:
114
+
115
+ ```ts
116
+ import { assertEntityPayload, pickEntityPayload } from '@howone/sdk'
117
+ import { generationEntityDefinition } from '@/lib/sdk'
118
+
119
+ const payload = pickEntityPayload(generationEntityDefinition, {
120
+ prompt,
121
+ status: 'pending',
122
+ gradientDirection: direction, // removed unless declared in the manifest
123
+ })
124
+ assertEntityPayload(generationEntityDefinition, payload)
125
+ await howone.entities.Generation.create(payload)
126
+ ```
127
+
128
+ For updates, use `assertEntityPayload(definition, payload, { partial: true })`. Use
129
+ `validateEntityPayload` when the UI needs structured field errors instead of an exception.
130
+
131
+ ## Bulk and aggregation
132
+
133
+ ```ts
134
+ await howone.entities.Sample.bulkCreate(records, { sample: true })
135
+
136
+ const counts = await howone.entities.Generation.aggregate<{ _id: string; count: number }>([
137
+ { $match: { status: 'completed' } },
138
+ { $group: { _id: '$model', count: { $sum: 1 } } },
139
+ ])
140
+ ```
141
+
142
+ These methods exist only when the generated access contract permits their underlying capability.
143
+
144
+ ## Response contract
145
+
146
+ The SDK accepts known envelope variants but rejects malformed list/query/single responses with
147
+ `HowOneProtocolError`. It no longer turns an unexpected response into an empty array, because that
148
+ would make a backend regression look like “no data.”
149
+
150
+ By default, only top-level response keys are converted between snake_case and camelCase. Nested
151
+ business JSON is preserved. Use `caseDepth: 'deep'` only when the entire payload is a controlled
152
+ transport object.
153
+
154
+ ## Common mistakes
155
+
156
+ | Mistake | Fix |
157
+ |---|---|
158
+ | Manual owner field | Remove it; auth/scope derives ownership. |
159
+ | Public query with top-level filter keys | Use `where: { ... }`. |
160
+ | Any unknown filter/sort | Read manifest allowed fields and use generated types. |
161
+ | Empty array after a backend shape regression | Inspect `HowOneProtocolError`; fix the contract/server. |
162
+ | Nested settings keys renamed unexpectedly | Keep default `caseDepth: 'top-level'`. |
163
+ | Entity CRUD via `raw` | Use generated entity bindings. |