@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,523 @@
1
+ # Database Schema Design
2
+
3
+ **Track:** `02-entity-schema/` — platform entity contracts only; skip when the user needs no HowOne persisted data.
4
+
5
+ Use this reference when designing or changing HowOne backend entity schemas. It condenses the
6
+ runtime contract from `docs/dynamic-entity-architecture.zh.md` into instructions an AI agent can
7
+ actually apply.
8
+
9
+ This file answers: **what should the schema be?** For how to apply changes, read
10
+ `02-schema-operations.md`. For access/query contract details, read `03-access-models.md` and
11
+ `04-query-contracts.md`. For frontend calls, wait for manifest sync, then read
12
+ `04-app-sdk/02-entity-operations.md`.
13
+
14
+ ## Mental Model
15
+
16
+ A HowOne Entity is a versioned app-level database contract. It is not a MongoDB collection exposed
17
+ directly and not a loose JSON form.
18
+
19
+ Design the whole contract:
20
+
21
+ ```ts
22
+ type EntityContract = {
23
+ name: string
24
+ type: 'object'
25
+ description?: string
26
+ visibility: 'private' | 'public'
27
+ properties: Record<string, EntityField>
28
+ required?: string[]
29
+ access: {
30
+ authenticated: AuthenticatedAccess
31
+ public: PublicAccess
32
+ }
33
+ indexes?: EntityIndex[]
34
+ relations?: Record<string, EntityRelation>
35
+ presentation?: EntityPresentation
36
+ lifecycle?: EntityLifecycle
37
+ performance?: EntityPerformance
38
+ }
39
+ ```
40
+
41
+ Each section has a different job:
42
+
43
+ | Section | Purpose | AI design question |
44
+ |---|---|---|
45
+ | `properties` | Business fields and primitive validation | What data is persisted? |
46
+ | `required` | Create-time required fields | What must exist before first save? |
47
+ | `access.authenticated` | Logged-in/private API access | Who can read/write after auth? |
48
+ | `access.public` | Anonymous/public API access | Can a public page read or write it? |
49
+ | `indexes` | Query performance and uniqueness | What lists/details will be queried often? |
50
+ | `relations` | Valid include names | What can be joined/expanded? |
51
+ | `presentation` | Admin/generator hints | What fields identify the record in UI? |
52
+ | `lifecycle` | Audit/delete policy hints | Is this append-only, soft-deletable, audited? |
53
+ | `performance` | Runtime/admin pagination/sort hints | What limits and sorts are safe? |
54
+
55
+ ## Storage Reality
56
+
57
+ HowOne uses shared runtime collections:
58
+
59
+ | Collection | Meaning |
60
+ |---|---|
61
+ | `entityshares` | Current active entity definitions. |
62
+ | `entitydatashares` | Real business records. |
63
+ | `entityschemaversions` | Historical schema snapshots. |
64
+ | `entityschemastates` | Current schema version pointer per app. |
65
+ | `usershares` | App user mapping used for ownership. |
66
+
67
+ Schema restore changes definitions only. It does **not** roll back existing business records.
68
+
69
+ Every data row may carry:
70
+
71
+ ```ts
72
+ {
73
+ id: string
74
+ created_date: string
75
+ updated_date: string
76
+ created_by_id: string
77
+ schema_version_id?: string
78
+ schema_version_number?: number
79
+ is_sample?: boolean
80
+ ...businessFields
81
+ }
82
+ ```
83
+
84
+ Do not create business fields that collide with system fields.
85
+
86
+ ## Field Design
87
+
88
+ ### Naming
89
+
90
+ Entity and field names must match:
91
+
92
+ ```text
93
+ ^[a-zA-Z_][a-zA-Z0-9_]*$
94
+ ```
95
+
96
+ Conventions:
97
+
98
+ - Entity names: PascalCase, singular, domain noun: `Todo`, `Article`, `QrProfile`.
99
+ - Field names: camelCase: `qrImageUrl`, `publishedAt`, `moodScore`.
100
+ - Avoid ambiguous names like `data`, `info`, `value`, `result` unless the product really stores opaque blobs.
101
+
102
+ Forbidden business field names:
103
+
104
+ ```text
105
+ id
106
+ _id
107
+ created_date
108
+ updated_date
109
+ created_by_id
110
+ createdById
111
+ ownerId
112
+ is_sample
113
+ schema_version_id
114
+ schema_version_number
115
+ ```
116
+
117
+ `created_by_user_id` is special: use it only when a public write/share flow explicitly needs a
118
+ project-user identifier. Do not use it as the owner field for normal authenticated private data;
119
+ the backend derives owner from JWT.
120
+
121
+ ### Supported Types
122
+
123
+ ```text
124
+ string
125
+ number
126
+ boolean
127
+ date
128
+ array
129
+ object
130
+ integer
131
+ null
132
+ ```
133
+
134
+ Nullable:
135
+
136
+ ```json
137
+ { "type": ["string", "null"], "default": null }
138
+ ```
139
+
140
+ Backend runtime currently enforces:
141
+
142
+ - unknown field rejection;
143
+ - create required fields;
144
+ - basic primitive type checks;
145
+ - non-null required fields unless the type includes `null`;
146
+ - defaults and `autoGenerate`.
147
+
148
+ Do not assume full JSON Schema enforcement for every nested constraint. Use Zod/frontend validation
149
+ for stronger UX validation:
150
+
151
+ - `enum`
152
+ - `minimum` / `maximum`
153
+ - `minLength` / `maxLength`
154
+ - `pattern`
155
+ - nested `items` / `properties`
156
+
157
+ ### Defaults and Generated Fields
158
+
159
+ Use `default` when a field has an obvious value at creation:
160
+
161
+ ```json
162
+ { "completed": { "type": "boolean", "default": false } }
163
+ ```
164
+
165
+ Use nullable defaults for optional dates:
166
+
167
+ ```json
168
+ { "publishedAt": { "type": ["date", "null"], "default": null } }
169
+ ```
170
+
171
+ Use server generation for public IDs:
172
+
173
+ ```json
174
+ {
175
+ "publicId": {
176
+ "type": "string",
177
+ "autoGenerate": { "strategy": "uuid" }
178
+ }
179
+ }
180
+ ```
181
+
182
+ Current `autoGenerate.strategy` support:
183
+
184
+ ```text
185
+ uuid
186
+ ```
187
+
188
+ AI rule: Create input may omit fields with `default` or `autoGenerate`; response types should include
189
+ them as present/possible.
190
+
191
+ ## Access Design
192
+
193
+ Always write both `authenticated` and `public`. Do not rely on `visibility` defaults for new schema.
194
+
195
+ Authenticated channel:
196
+
197
+ ```text
198
+ /api/entities/apps/:appId/data/:entityName
199
+ ```
200
+
201
+ Public channel:
202
+
203
+ ```text
204
+ /api/entities/public/apps/:appId/data/:entityName
205
+ ```
206
+
207
+ These channels are independent.
208
+
209
+ ### Authenticated Access
210
+
211
+ Each action accepts `own`, `all`, or `none`:
212
+
213
+ ```json
214
+ "authenticated": {
215
+ "read": "own",
216
+ "create": "own",
217
+ "update": "own",
218
+ "delete": "own"
219
+ }
220
+ ```
221
+
222
+ | Value | Meaning |
223
+ |---|---|
224
+ | `own` | Backend scopes to current `usershares._id`; create assigns current owner. |
225
+ | `all` | Logged-in users can access all records for that operation. |
226
+ | `none` | Operation forbidden. |
227
+
228
+ Rules:
229
+
230
+ - For private user data, use all `own`.
231
+ - For authenticated shared dashboards/CMS, use `read: "all"` and be conservative on update/delete.
232
+ - Do not pass owner fields in authenticated payloads or filters. Backend derives owner from auth.
233
+ - Authenticated own lists must use the authenticated channel so the backend can derive ownership.
234
+
235
+ ### Public Access
236
+
237
+ Public read values:
238
+
239
+ | Value | Use for |
240
+ |---|---|
241
+ | `none` | Not visible without login. |
242
+ | `list` | Public feeds/catalogs/lists. |
243
+ | `scoped` | Public share/detail pages that require scope keys. |
244
+
245
+ Public write values:
246
+
247
+ | Value | Use for |
248
+ |---|---|
249
+ | `none` | No anonymous write. |
250
+ | `scoped` | Anonymous write only with required scope values. |
251
+ | `any` | Fully public write; use rarely. |
252
+
253
+ Guardrail fields:
254
+
255
+ ```json
256
+ "public": {
257
+ "read": "scoped",
258
+ "create": "none",
259
+ "update": "none",
260
+ "requiredScopes": ["ownerId", "slug"],
261
+ "allowedFilters": ["slug", "active"],
262
+ "allowedSorts": ["updatedDate"],
263
+ "defaultLimit": 1,
264
+ "maxLimit": 10
265
+ }
266
+ ```
267
+
268
+ Rules:
269
+
270
+ - `scoped` requires every `requiredScopes` value in query/body.
271
+ - `list` must define `allowedFilters`, `allowedSorts`, `defaultLimit`, and `maxLimit`.
272
+ - Public create requires a clear ownership/scoping story. If it needs `created_by_user_id`, document where that value comes from.
273
+ - Never expose broad public write unless the product explicitly needs anonymous submissions.
274
+
275
+ ## Standard Patterns
276
+
277
+ ### A. User Private Data
278
+
279
+ Use for todos, notes, journals, saved generations, personal settings.
280
+
281
+ ```json
282
+ {
283
+ "name": "Todo",
284
+ "type": "object",
285
+ "visibility": "private",
286
+ "properties": {
287
+ "text": { "type": "string" },
288
+ "completed": { "type": "boolean", "default": false }
289
+ },
290
+ "required": ["text"],
291
+ "access": {
292
+ "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
293
+ "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
294
+ },
295
+ "indexes": [
296
+ {
297
+ "name": "owner_completed_updated",
298
+ "scope": "owner",
299
+ "fields": ["completed", "updatedDate"],
300
+ "order": { "updatedDate": "desc" }
301
+ }
302
+ ],
303
+ "performance": {
304
+ "defaultLimit": 50,
305
+ "maxLimit": 100,
306
+ "allowedSorts": ["createdDate", "updatedDate"]
307
+ },
308
+ "presentation": {
309
+ "titleField": "text",
310
+ "defaultSort": { "field": "updatedDate", "order": "desc" },
311
+ "listFields": ["text", "completed", "updatedDate"]
312
+ }
313
+ }
314
+ ```
315
+
316
+ App implementation handoff: use the SDK entity operations reference after manifest sync.
317
+
318
+ ### B. Public Read-Only Catalog
319
+
320
+ Use for articles, templates, listings, published galleries.
321
+
322
+ ```json
323
+ {
324
+ "name": "Article",
325
+ "type": "object",
326
+ "visibility": "public",
327
+ "properties": {
328
+ "title": { "type": "string" },
329
+ "slug": { "type": "string" },
330
+ "status": { "type": "string", "enum": ["draft", "published"], "default": "draft" },
331
+ "publishedAt": { "type": ["date", "null"], "default": null }
332
+ },
333
+ "required": ["title", "slug"],
334
+ "access": {
335
+ "authenticated": { "read": "all", "create": "all", "update": "all", "delete": "all" },
336
+ "public": {
337
+ "read": "list",
338
+ "create": "none",
339
+ "update": "none",
340
+ "delete": "none",
341
+ "allowedFilters": ["slug", "status"],
342
+ "allowedSorts": ["publishedAt", "updatedDate"],
343
+ "defaultLimit": 20,
344
+ "maxLimit": 100
345
+ }
346
+ },
347
+ "indexes": [
348
+ { "name": "slug_unique", "scope": "global", "fields": ["slug"], "unique": true },
349
+ {
350
+ "name": "status_published",
351
+ "scope": "global",
352
+ "fields": ["status", "publishedAt"],
353
+ "order": { "publishedAt": "desc" }
354
+ }
355
+ ]
356
+ }
357
+ ```
358
+
359
+ App implementation handoff: public list calls are generated from `access.public.allowedFilters`,
360
+ `allowedSorts`, and pagination limits after manifest sync.
361
+
362
+ ### C. Public Scoped Share Page
363
+
364
+ Use for QR profile, public invoice, public resume, shared report.
365
+
366
+ ```json
367
+ {
368
+ "name": "QrProfile",
369
+ "type": "object",
370
+ "visibility": "public",
371
+ "properties": {
372
+ "slug": { "type": "string" },
373
+ "title": { "type": "string" },
374
+ "qrImageUrl": { "type": "string" },
375
+ "active": { "type": "boolean", "default": true }
376
+ },
377
+ "required": ["slug", "title", "qrImageUrl"],
378
+ "access": {
379
+ "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
380
+ "public": {
381
+ "read": "scoped",
382
+ "create": "none",
383
+ "update": "none",
384
+ "delete": "none",
385
+ "requiredScopes": ["ownerId", "slug"],
386
+ "allowedFilters": ["slug", "active"],
387
+ "allowedSorts": ["updatedDate"],
388
+ "defaultLimit": 1,
389
+ "maxLimit": 10
390
+ }
391
+ },
392
+ "indexes": [
393
+ { "name": "owner_slug_unique", "scope": "owner", "fields": ["slug"], "unique": true }
394
+ ]
395
+ }
396
+ ```
397
+
398
+ App implementation handoff: scoped public reads must include every `requiredScopes` value.
399
+
400
+ ### D. Workflow Output History
401
+
402
+ Use for AI generation/analyze/report flows that need persisted history.
403
+
404
+ ```json
405
+ {
406
+ "name": "Generation",
407
+ "type": "object",
408
+ "visibility": "private",
409
+ "properties": {
410
+ "prompt": { "type": "string" },
411
+ "status": { "type": "string", "enum": ["pending", "completed", "failed"], "default": "pending" },
412
+ "resultUrl": { "type": ["string", "null"], "default": null },
413
+ "errorMessage": { "type": ["string", "null"], "default": null },
414
+ "completedAt": { "type": ["date", "null"], "default": null }
415
+ },
416
+ "required": ["prompt", "status"],
417
+ "access": {
418
+ "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
419
+ "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
420
+ },
421
+ "indexes": [
422
+ {
423
+ "name": "owner_status_updated",
424
+ "scope": "owner",
425
+ "fields": ["status", "updatedDate"],
426
+ "order": { "updatedDate": "desc" }
427
+ }
428
+ ]
429
+ }
430
+ ```
431
+
432
+ Rules:
433
+
434
+ - Persist pending before long-running workflow when product needs history/resume.
435
+ - Persist completed output only into fields declared here.
436
+ - Persist failed state and error message if history must show failures.
437
+ - Do not persist raw workflow envelopes unless schema declares an object field for them.
438
+
439
+ ## Index Design
440
+
441
+ Every list/detail path should map to an index.
442
+
443
+ | Query shape | Index recommendation |
444
+ |---|---|
445
+ | private user list by updated time | `scope: "owner"`, `fields: ["updatedDate"]` |
446
+ | private user list filtered by status | `scope: "owner"`, `fields: ["status", "updatedDate"]` |
447
+ | owner unique slug | `scope: "owner"`, `fields: ["slug"]`, `unique: true` |
448
+ | public slug detail | `scope: "global"`, `fields: ["slug"]`, `unique: true` |
449
+ | public feed by status/date | `scope: "global"`, `fields: ["status", "publishedAt"]` |
450
+
451
+ Index rules:
452
+
453
+ - Index fields should match real UI queries, not every field.
454
+ - Owner-scoped unique means unique per owner, not globally unique.
455
+ - Public filters/sorts must also be listed in `access.public.allowedFilters/allowedSorts`.
456
+ - Avoid designing public queries that require unbounded scans.
457
+
458
+ ## Relations
459
+
460
+ Use `relations` only when frontend/admin needs `include`.
461
+
462
+ ```json
463
+ "relations": {
464
+ "author": {
465
+ "type": "entity",
466
+ "entity": "Author",
467
+ "localField": "authorId",
468
+ "foreignField": "id",
469
+ "as": "author"
470
+ }
471
+ }
472
+ ```
473
+
474
+ Rules:
475
+
476
+ - Keep relation names stable; app code may use them in `include`.
477
+ - Do not use relations to hide missing denormalized fields required by list pages.
478
+ - Public include should be conservative; ensure related data is safe to expose.
479
+
480
+ ## Presentation and Lifecycle
481
+
482
+ `presentation` is not API validation. It teaches admin UI, codegen, and agents how to display a record:
483
+
484
+ ```json
485
+ "presentation": {
486
+ "titleField": "title",
487
+ "imageField": "coverImageUrl",
488
+ "defaultSort": { "field": "updatedDate", "order": "desc" },
489
+ "listFields": ["title", "status", "updatedDate"]
490
+ }
491
+ ```
492
+
493
+ `lifecycle` is policy metadata:
494
+
495
+ ```json
496
+ "lifecycle": {
497
+ "audit": true,
498
+ "softDelete": false
499
+ }
500
+ ```
501
+
502
+ Use it to document intent, but do not assume every lifecycle policy is fully enforced unless backend
503
+ source confirms it.
504
+
505
+ ## Schema Review Checklist
506
+
507
+ Before applying a schema:
508
+
509
+ - Entity name and field names pass naming rules.
510
+ - No business field collides with system fields.
511
+ - Every required field exists in `properties`.
512
+ - Every optional nullable field has a deliberate `null` type/default.
513
+ - Defaults exist for fields that should not block create.
514
+ - Access has both `authenticated` and `public`.
515
+ - Public list/scoped flows have filters, sorts, scopes, and limits.
516
+ - Private owned data does not require app code to pass owner fields.
517
+ - Indexes match real list/detail queries.
518
+ - Presentation tells UI/admin which fields to show.
519
+ - Workflow output fields are explicitly declared before persistence.
520
+ - Dangerous public write is avoided or explicitly justified.
521
+
522
+ If any item cannot be answered from requirements, stop and ask for the missing contract instead of
523
+ inventing hidden fields or public exposure.