@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,209 @@
1
+ # App Generation Architect
2
+
3
+ Read immediately after `skill(name="howone")` and before platform design tools, SDK contract
4
+ edits, or implementation guesses.
5
+
6
+ HowOne is a generated app platform. This file classifies **user scope**, separates **platform
7
+ contracts** from explicit user-owned integrations, and routes to backend, AI, or SDK tracks. Keep design
8
+ tracks separate: backend design does not require SDK references; AI design does not require SDK
9
+ references until the synced AI manifest is ready for code.
10
+
11
+ ## Scope classification
12
+
13
+ Map the user request to surfaces. Include only what they need.
14
+
15
+ | Need | Tracks | Notes |
16
+ |---|---|---|
17
+ | Unclear or full product scope | `01-architect/` (+ others as discovered) | Finish this file before other tracks |
18
+ | Persisted app data on HowOne | `02-entity-schema/` → sync | Skip SDK until app code needs calls |
19
+ | HowOne AI features | `03-ai-capabilities/` → sync → external workflow | Verify catalog before design |
20
+ | SDK wiring, auth, UI calls | `04-app-sdk/` | Only after manifests exist when contracts apply |
21
+ | UI only, no HowOne data/AI | App code under `{appRoot}` | No schema/AI design tools |
22
+ | Explicit user-owned integrations | App code + config | Only when the user explicitly asks to connect something outside HowOne |
23
+
24
+ **Mixed scope:** read at least one file per touched track (`SKILL.md` index) before writing.
25
+
26
+ ## HowOne platform boundary
27
+
28
+ Use this decision model for **any** user request. Ask whether the ask is a **platform contract
29
+ surface** or an explicit user-owned integration.
30
+
31
+ ### Platform provides (evidence required)
32
+
33
+ | Surface | Evidence to check | Design track |
34
+ |---|---|---|
35
+ | Persisted structured data on HowOne | Schema tools + `{appRoot}/.howone/database/manifest.json` | `02-entity-schema/` |
36
+ | AI execution on HowOne workflow service | `03-service-capability-catalog.md` + AI manifest + AI tools | `03-ai-capabilities/` |
37
+ | App calls HowOne runtime | Synced manifests + `04-app-sdk/` reference for that behavior | `04-app-sdk/` |
38
+ | Mutating platform contracts | `backend-api-design`, `ai-capability-design`, sync tools, `external-ai-capability` | Per surface |
39
+
40
+ If none of these surfaces can express the user's **platform** requirement after checking contracts,
41
+ catalog, and tool schemas, it is a **platform gap**—not an automatic ban on whatever technology the
42
+ user named.
43
+
44
+ ### Explicit user-owned integration (not platform gap)
45
+
46
+ Use this path only when the user explicitly asks to connect something they run, host, or configure
47
+ outside HowOne contracts. Do not apply it to ordinary generated app requests such as "AI image
48
+ generation app", "AI story app", "login", "cloud sync", or "history"; first check the HowOne
49
+ platform tracks.
50
+
51
+ - Implement in application code and configuration under `{appRoot}`.
52
+ - **Do not refuse** because HowOne does not provision it.
53
+ - **Do not** call platform design tools to fake it as entities, AI capabilities, or manifest fields.
54
+ - **Do not** tell the user they cannot use their own stack—only clarify it is outside HowOne platform scope when they explicitly asked for that stack.
55
+
56
+ ### Boundary decision (always)
57
+
58
+ ```text
59
+ 1. What did the user ask for?
60
+ 2. Does it require HowOne persisted data? → entity-schema path or skip
61
+ 3. Does it require HowOne AI? → catalog + ai-capabilities path or skip
62
+ 4. Did they explicitly ask to connect something outside HowOne? → app-owned; wire in UI/config
63
+ 5. Did they ask for a platform feature with no contract evidence? → platform stop (generic)
64
+ 6. Mixed? → platform parts via tracks; explicit integrations in app code
65
+ ```
66
+
67
+ ### Platform scope rules
68
+
69
+ - **No invented platform APIs:** Only fields and behaviors present in manifests, catalog, tools, or documented SDK references.
70
+ - **No invalid shortcuts:** Do not handwrite `.howone/` metadata or guess version/workflow identifiers.
71
+ - **Stop wording:** Name the **missing contract surface** (e.g. no catalog family, no manifest binding, no tool operation)—not the user's technology choice.
72
+
73
+ When stopping a platform path, separate what HowOne can provide from any explicit integration the
74
+ user requested.
75
+
76
+ Inspect-only platform reads do not replace this file before the first **design write**.
77
+
78
+ ## Platform layers
79
+
80
+ | Layer | Source of truth | App responsibility |
81
+ |---|---|---|
82
+ | Database | `{appRoot}/.howone/database/manifest.json` | Entity binding handoff |
83
+ | AI | `{appRoot}/.howone/ai/manifest.json` + workflow status | AI binding handoff |
84
+ | SDK | `@howone/sdk` + `{appRoot}/src/lib/sdk.ts` | App runtime calls |
85
+ | Frontend | App code | UI, state, feedback |
86
+
87
+ Validated/synced manifests drive code—not prompts or memory.
88
+
89
+ ```text
90
+ user request → scope → platform contracts → sync → sdk binding → UI
91
+ ```
92
+
93
+ When SDK work is in scope, import the app runtime from `src/lib/sdk.ts`; do not guess entity/action
94
+ names or platform URLs.
95
+
96
+ ## Minimum track reads (after this file)
97
+
98
+ Use `SKILL.md` for the full file index. Typical minimums:
99
+
100
+ | Surface in scope | Read at least |
101
+ |---|---|
102
+ | Entity/schema design | `02-entity-schema/01-schema-design.md`, `02-entity-schema/02-schema-operations.md` |
103
+ | Backend query/public contracts | add `02-entity-schema/03-access-models.md`, `02-entity-schema/04-query-contracts.md` |
104
+ | App entity query code | add `04-app-sdk/11-entity-data-access-patterns.md`, `04-app-sdk/12-query-dsl-and-responses.md` after manifest sync |
105
+ | AI design | `03-ai-capabilities/01-ai-capability-architecture.md`, `03-ai-capabilities/03-service-capability-catalog.md`, `03-ai-capabilities/02-workflow-contract-rules.md` |
106
+ | AI + saved outputs | add `02-entity-schema/05-ai-persistence-patterns.md` after AI contract is known |
107
+ | Bindings after sync | `02-manifest-codegen.md` + `04-app-sdk/01-client-setup.md` + `04-app-sdk/03-auth.md` + `04-app-sdk/04-react-integration.md` + the operation-specific SDK file |
108
+
109
+ ## Data posture
110
+
111
+ Choose before schema and UI.
112
+
113
+ | Product need | Access posture | Runtime handoff |
114
+ |---|---|---|
115
+ | Per-user private data | authenticated own | SDK entity track later |
116
+ | Shared authenticated data | authenticated all | SDK entity track later |
117
+ | Public catalog | public list where safe | SDK public entity track later |
118
+ | Public share/detail | public scoped | SDK public entity track later |
119
+ | Anonymous create | public create scoped/any | SDK public entity track later |
120
+ | AI run history | authenticated own | private history entity |
121
+ | AI public share | private + public scoped entities | two entities |
122
+
123
+ Defaults: "my/private" → own; public catalog only when fields are safe; share links → scoped + limits.
124
+
125
+ ## Auth posture
126
+
127
+ | Need | Client | Provider |
128
+ |---|---|---|
129
+ | HowOne AI, uploads, or authenticated/private entities | default `createClient` | `<HowOneProvider client={howone}>`; hosted guard is inherited |
130
+ | Custom HowOne login UI | `auth: 'custom'`, real OTP/OAuth token flow | `<HowOneProvider client={howone}>`; custom guard is inherited |
131
+ | External IdP | headless + adapter | `<HowOneProvider client={howone}>`; adapter owns token |
132
+ | Manifest-approved public entities only | `auth: 'none'` or explicit public client | `<HowOneProvider client={howone}>` with no required guard |
133
+ | No HowOne runtime | no client required | no Provider required |
134
+
135
+ Keep default HowOne brand control unless user asks to hide. Resolve identity through the SDK track
136
+ when app code depends on the current user.
137
+
138
+ ### Runtime activation invariant
139
+
140
+ Contract design and app runtime activation are one delivery chain, not independent completion states.
141
+ When the final app uses any `@howone/sdk` runtime surface—including a synced entity or AI binding,
142
+ public entities, uploads, auth, user/session APIs, or raw SDK requests:
143
+
144
+ 1. Initialize the single app client in `src/lib/sdk.ts` with the generated project/env configuration.
145
+ 2. Import that SDK module before `HowOneProvider` and pass the composed client so the Provider sees
146
+ the selected environment and instance-scoped auth state.
147
+ 3. Keep `HowOneProvider` around the rendered application root. This is required for every active
148
+ HowOne SDK runtime, including public-only entity applications; replacing scaffold UI must not
149
+ remove it.
150
+ 4. Select the Provider guard from the table above. Do not use `auth="none"` to silence a missing login
151
+ flow for AI, uploads, or authenticated entities.
152
+ 5. For hosted auth, unauthenticated protected use must redirect through HowOne login. For custom auth,
153
+ the app must acquire an actual HowOne token and call `howone.auth.setToken()` before protected SDK
154
+ requests.
155
+ 6. Validate the logged-out path and the authenticated SDK call path. A styled login screen, compiled
156
+ SDK binding, or synced manifest alone does not prove runtime integration.
157
+
158
+ Pure UI/static work may omit this runtime chain only when the application makes no HowOne runtime
159
+ calls. Public-only entity experiences may stay anonymous only when the synced manifest explicitly
160
+ permits the public operation and app code uses `howone.public.entities.*`.
161
+
162
+ ## Entity workflow (when `02-entity-schema/` in scope)
163
+
164
+ 1. Read schema design + operations references.
165
+ 2. Inspect current schema/manifest.
166
+ 3. Design full entity contract (fields, access, indexes).
167
+ 4. Apply one complete patch → `sync_schema_artifacts`.
168
+ 5. Read `{appRoot}/.howone/database/manifest.json`.
169
+ 6. Stop backend design. Read SDK references only if implementing app calls.
170
+
171
+ No schema dry-run step. High-risk changes (delete entity/field, broaden public write, required
172
+ without default) need explicit user alignment before applying the final patch.
173
+
174
+ ## AI workflow (when `03-ai-capabilities/` in scope)
175
+
176
+ 1. Read architecture + **catalog** (feasibility) + contract rules; use playbooks when they match.
177
+ 2. Apply one complete capability patch → `sync_ai_artifacts`.
178
+ 3. External workflow create/update per workflow-operations reference; keep job/request IDs from tool results.
179
+ 4. Treat submission as asynchronous pending work, not a pause boundary. Continue independent app source, UI, persistence, and state implementation instead of ending the run to wait.
180
+ 5. After the terminal result becomes available, run `sync_ai_artifacts` again, then read `{appRoot}/.howone/ai/manifest.json`. A successful update promotes its new workflow ID in the backend capability version.
181
+ 6. Stop AI design. Read SDK references only if implementing app calls.
182
+ 7. If persistence required: entity workflow after output contract is fixed.
183
+
184
+ Do not fake catalog-backed AI. Platform gap → stop AI design path, explain generically.
185
+ No AI capability dry-run step. Design the contract from the skill references, then apply the final
186
+ capability patch.
187
+
188
+ ## Scope patterns (not a product catalog)
189
+
190
+ | Pattern | Platform work |
191
+ |---|---|
192
+ | Ephemeral AI result in UI state only | AI + SDK; skip entity-schema unless user adds storage |
193
+ | AI with history/library | AI contract first, then persistence entity |
194
+ | Public view of private AI output | private entity + scoped public entity |
195
+ | Behavior-only AI change | workflow update when schemas unchanged |
196
+ | Schema/UI drift | schema → sync → SDK → then UI |
197
+
198
+ ## Checklist before implementation
199
+
200
+ - [ ] Scope explicit: which tracks apply; explicit integration vs platform clear
201
+ - [ ] Data and auth posture chosen when data in scope
202
+ - [ ] AI requirements verified against catalog when AI in scope
203
+ - [ ] Manifests synced before SDK codegen
204
+ - [ ] `src/lib/sdk.ts` is the HowOne entrypoint
205
+ - [ ] App code uses generated SDK bindings instead of direct internal platform HTTP requests
206
+ - [ ] Active HowOne runtime keeps `HowOneProvider` at the app root and initializes the SDK first
207
+ - [ ] AI, uploads, and authenticated entities have a real hosted/custom/headless token path
208
+ - [ ] Public-only anonymous access is backed by manifest public rules and the public SDK namespace
209
+ - [ ] UI owns visible feedback; no invented platform APIs
@@ -0,0 +1,194 @@
1
+ # Manifest Codegen
2
+
3
+ Generate `src/lib/sdk.ts` from the two synced manifests. Do not infer names, fields, access rules,
4
+ schemas, or workflow IDs from a prompt, old source file, or dependency cache.
5
+
6
+ ## Source and evidence order
7
+
8
+ 1. Read `.howone/database/manifest.json` and `.howone/ai/manifest.json` after the latest sync.
9
+ 2. Read `package.json` and installed SDK declarations as described by
10
+ `../../references/version-evidence.md`.
11
+ 3. Load only the operation recipe needed by the app.
12
+ 4. Generate bindings, run the project verifier, then typecheck/build.
13
+
14
+ If an AI workflow update may rotate `workflowId`, re-read the AI manifest immediately before writing
15
+ the binding. Never preserve a stale UUID merely to avoid a diff.
16
+
17
+ ## Database manifest mapping
18
+
19
+ For each entity, generate:
20
+
21
+ - `Record` type extending `EntityRecord` with only declared business fields;
22
+ - explicit `Create` type (never `Omit<Record, ...>`);
23
+ - `Update = Partial<Create>` unless the product needs a narrower update contract;
24
+ - a `defineEntityDefinition(...)` constant that preserves `properties`, `required`, and the entire
25
+ `access` block;
26
+ - an authenticated binding wrapped with `withEntityContract`;
27
+ - a public binding only when `access.public` exposes at least one operation, wrapped with
28
+ `withPublicEntityContract`.
29
+
30
+ ### Type mapping
31
+
32
+ | Manifest field type | TypeScript/Zod |
33
+ |---|---|
34
+ | `string`, `text` | `string` / `z.string()` |
35
+ | `integer`, `number`, `float` | `number` / `z.number()` (`.int()` for integer) |
36
+ | `boolean` | `boolean` / `z.boolean()` |
37
+ | `date`, `datetime` | ISO `string` / `z.string()` (add `.datetime()` only when the contract guarantees it) |
38
+ | `array` | `T[]` / `z.array(...)` |
39
+ | `object` | explicit object type / `z.object(...)` |
40
+ | enum | literal union / `z.enum([...])` |
41
+ | nullable union | `T \| null` / `z.nullable(...)` |
42
+
43
+ Fields with `default`, `defaultValue`, or `autoGenerate` can be optional in `Create` even when
44
+ listed as required by the response schema. Never include system fields (`id`, timestamps, schema
45
+ version) or ownership fields in Create/Update types.
46
+
47
+ ## AI manifest mapping
48
+
49
+ For each action:
50
+
51
+ - preserve the manifest action `id` exactly (case-sensitive);
52
+ - convert `inputSchema` and `outputSchema` to Zod;
53
+ - preserve required arrays and closed enums;
54
+ - include the exact UUID `workflowId` in `defineAiAction`;
55
+ - never add `.passthrough()` to hide an envelope mismatch;
56
+ - never make required output fields optional to make validation pass.
57
+
58
+ `defineAiAction` validates workflow IDs during module initialization. Missing or invalid values are
59
+ configuration failures, not a runtime fallback case.
60
+
61
+ ## Generated shape
62
+
63
+ This is the architecture pattern; replace every placeholder with manifest-derived code:
64
+
65
+ ```ts
66
+ // src/lib/sdk.ts
67
+ import {
68
+ createClient,
69
+ defineAiAction,
70
+ defineAiActions,
71
+ defineEntityDefinition,
72
+ defineEntities,
73
+ definePublicEntities,
74
+ type EntityDefinition,
75
+ type EntityRecord,
76
+ withAiActions,
77
+ withEntities,
78
+ withEntityContract,
79
+ withPublicEntities,
80
+ withPublicEntityContract,
81
+ } from '@howone/sdk'
82
+ import { z } from 'zod'
83
+
84
+ export type ArticleRecord = EntityRecord & {
85
+ title: string
86
+ status: 'draft' | 'published'
87
+ }
88
+ export type ArticleCreate = { title: string; status: 'draft' | 'published' }
89
+ export type ArticleUpdate = Partial<ArticleCreate>
90
+
91
+ export const articleEntityDefinition = defineEntityDefinition({
92
+ name: 'Article',
93
+ type: 'object',
94
+ properties: {
95
+ title: { type: 'string' },
96
+ status: { type: 'string', enum: ['draft', 'published'] },
97
+ },
98
+ required: ['title', 'status'],
99
+ access: {
100
+ authenticated: { read: 'all', create: 'all', update: 'all', delete: 'all' },
101
+ public: {
102
+ read: 'list',
103
+ create: 'none',
104
+ update: 'none',
105
+ allowedFilters: ['status'],
106
+ allowedSorts: ['createdDate'],
107
+ },
108
+ },
109
+ } satisfies EntityDefinition)
110
+
111
+ const client = createClient({
112
+ projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
113
+ env: import.meta.env.VITE_HOWONE_ENV,
114
+ })
115
+
116
+ export const entities = defineEntities({
117
+ Article: withEntityContract(
118
+ client.entity<ArticleRecord, ArticleCreate, ArticleUpdate>('Article'),
119
+ articleEntityDefinition,
120
+ ),
121
+ })
122
+
123
+ // Include only manifest-approved public entities/capabilities.
124
+ export const publicEntities = definePublicEntities({
125
+ Article: withPublicEntityContract(
126
+ client.public.entity<ArticleRecord, ArticleCreate, ArticleUpdate>('Article'),
127
+ articleEntityDefinition,
128
+ ),
129
+ })
130
+
131
+ const summarizeInputSchema = z.object({ text: z.string() })
132
+ const summarizeOutputSchema = z.object({ summary: z.string() })
133
+ export type SummarizeInput = z.infer<typeof summarizeInputSchema>
134
+ export type SummarizeOutput = z.infer<typeof summarizeOutputSchema>
135
+
136
+ export const ai = defineAiActions({
137
+ summarize: defineAiAction('summarize', {
138
+ workflowId: 'd69ab648-2c00-4d94-928e-01bd7b2a5bb2',
139
+ inputSchema: summarizeInputSchema,
140
+ outputSchema: summarizeOutputSchema,
141
+ }),
142
+ })
143
+
144
+ const howoneWithEntities = withEntities(client, entities)
145
+ const howoneWithPublicEntities = withPublicEntities(howoneWithEntities, publicEntities)
146
+ const howone = withAiActions(howoneWithPublicEntities, ai)
147
+ export default howone
148
+ ```
149
+
150
+ If the manifest has no public capability, omit `publicEntities` and `withPublicEntities`. If an
151
+ entity has `access.authenticated.create: 'none'`, the authenticated wrapper has no `create` or
152
+ `bulkCreate` property at both runtime and type level. Do not cast it back.
153
+
154
+ ## Query and access generation
155
+
156
+ Authenticated code uses `howone.entities.Entity`; public code uses `howone.public.entities.Entity`.
157
+ Generate `QueryOptions` with `where`, `page`, `orderBy`, `include`, and `exactCount` only. Public
158
+ filters and sorts must be limited to manifest `allowedFilters`/`allowedSorts`; scoped reads must
159
+ provide every `requiredScopes` field under `where`.
160
+
161
+ ```ts
162
+ await howone.public.entities.Article.query({
163
+ where: { status: 'published' },
164
+ orderBy: { createdDate: 'desc' },
165
+ page: { number: 1, size: 20 },
166
+ })
167
+ ```
168
+
169
+ Never put `created_by_id`, `ownerId`, `puid`, or system fields into authenticated or public payloads.
170
+ Ownership comes from auth or the public scope contract.
171
+
172
+ ## Incremental changes
173
+
174
+ When a manifest changes:
175
+
176
+ 1. re-read the complete current manifest;
177
+ 2. preserve app exports that are still present;
178
+ 3. add/remove bindings to match the manifest exactly;
179
+ 4. regenerate affected Zod and entity definitions;
180
+ 5. run the verifier and typecheck.
181
+
182
+ Do not hand-edit `.howone/*` metadata. Do not place generated source files under `.howone/`.
183
+
184
+ ## Codegen checklist
185
+
186
+ - [ ] Every current entity has Record/Create/Update types and a definition constant.
187
+ - [ ] System/ownership fields are absent from write types.
188
+ - [ ] Access wrappers match authenticated/public operations.
189
+ - [ ] Public bindings include only manifest-approved entities.
190
+ - [ ] Query fields are typed from the generated Record, not `Record<string, unknown>`.
191
+ - [ ] Every AI action has a real Zod input schema and exact manifest UUID.
192
+ - [ ] Output requiredness and enums match the manifest.
193
+ - [ ] Provider consumes the composed `howone` client.
194
+ - [ ] `node .howone/skills/howone/scripts/verify-project.mjs` passes.