howone 0.1.9 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "private": false,
   "description": "HowOne command line tools for creating app templates.",
   "type": "module",

package/templates/vite/.howone/skills/howone-sdk/SKILL.md

@@ -5,16 +5,28 @@ description: Build application code with @howone/sdk correctly. Use when impleme
 
 # HowOne SDK
 
-Use this skill when writing app code that consumes `@howone/sdk`. The goal is stable generated code: read backend-synced manifests, define zod schemas, bind entities and AI actions in the app SDK entry, then call those bindings from UI code.
+Use this skill when writing app code that consumes `@howone/sdk`. The goal is stable generated code: read backend-synced manifests, define runtime schemas, bind entities and AI actions in the app SDK entry, then call those bindings from UI code.
+
+This skill is the normal source of truth for HowOne SDK usage in generated apps. Do not inspect `node_modules/@howone/sdk` just to rediscover imports, hook names, entity methods, AI action call shapes, or Vite environment wiring. Use dependency source only for narrow missing details, signature drift proven by verification, or SDK-package development.
 
 ## Workflow
 
-1. Locate the app root first. If an app was created by `howone init app <name>`, all `.howone/*` metadata and `src/lib/sdk.ts` work should happen inside that created app directory.
-2. Read the existing app SDK entry, usually `src/lib/sdk.ts`, before editing. Preserve its imports and local style.
-3. For Entity bindings, read `.howone/database/manifest.json`.
-4. For AI action bindings, read `.howone/ai/manifest.json`.
-5. Generate source code from the manifests, not from memory or tool-call summaries.
-6. Keep sync tools and app-code edits separate. `sync_schema_artifacts` and `sync_ai_artifacts` write metadata only; the coding agent edits `src/lib/sdk.ts`.
+1. Establish the app root. All `.howone/*` metadata and `src/lib/sdk.ts` work belongs inside that app root.
+2. Read `references/usage-patterns.md` once before writing SDK-related code. It contains the SDK mental model, essential public API, generation recipes, and common traps.
+3. Read the existing app SDK entry, usually `src/lib/sdk.ts`, before editing. Preserve its imports and local style.
+4. For Entity bindings, read `.howone/database/manifest.json`.
+5. For AI action bindings, read `.howone/ai/manifest.json`.
+6. Generate source code from the manifests, not from memory or tool-call summaries.
+7. Keep sync tools and app-code edits separate. `sync_schema_artifacts` and `sync_ai_artifacts` write metadata only; the coding agent edits `src/lib/sdk.ts`.
+
+## Source Order
+
+Use this order when deciding what to read:
+
+1. Current app files: `src/lib/sdk.ts`, relevant UI files, and generated manifests.
+2. This skill: `SKILL.md` plus `references/usage-patterns.md`.
+3. TypeScript/compiler errors from verification.
+4. SDK source or declaration files, only as a narrow fallback for a missing or disputed API.
 
 ## Rules
 
@@ -24,9 +36,10 @@ Use this skill when writing app code that consumes `@howone/sdk`. The goal is st
 - Current action binding shape is `howone.ai.<actionName>.run(input)`, `stream(input)`, and `events(input)`. Do not generate `howone.ai.run.<actionName>(input)` unless the SDK implementation has been changed to support that API.
 - Do not name AI actions `run`, `stream`, or `events`; those are reserved.
 - Define entity create/update types explicitly. Avoid deriving create types from `Omit<EntityRecord & ...>` when it widens the payload.
+- React integration does not provide entity/query/AI hooks. Use plain async SDK calls from React state/effects or an app-level data-fetching library.
 - Never make generated SDK/type files under `.howone`. `.howone` stores manifests only.
 - If an AI-first feature persists generated results, create/update AI capability schema first, sync `.howone/ai`, then derive Entity fields from the AI `outputSchema`.
 
 ## References
 
-Read `references/usage-patterns.md` before writing any code. It is the complete API reference for `@howone/sdk` and `@howone/sdk/react` — all type signatures, method names, import paths, and call patterns are already there.
+Read `references/usage-patterns.md` before writing SDK-related code. It is the working reference for `@howone/sdk` and `@howone/sdk/react`: mental model, imports, method names, app SDK entry shape, entity examples, AI action examples, React usage, validation caveats, and when source fallback is justified.

package/templates/vite/.howone/skills/howone-sdk/references/usage-patterns.md

@@ -1,8 +1,29 @@
 # HowOne SDK Usage Patterns
 
-Complete API reference for `@howone/sdk` and `@howone/sdk/react`. Covers all type signatures, method names, import paths, and usage patterns needed to wire up entities, AI actions, and React components in a HowOne app.
+Working reference for `@howone/sdk` and `@howone/sdk/react`. It covers the SDK surface that generated HowOne apps normally need: client setup, entity bindings, AI action bindings, React provider usage, and the known traps that cause repeated source inspection.
 
-## Complete Import Reference
+## Reading Strategy
+
+Use this file as the working SDK manual for normal app generation. It intentionally includes the public imports, client shape, entity methods, AI action bindings, React exports, app SDK entry shape, and known validation caveats.
+
+Do not inspect `node_modules/@howone/sdk` for the same information unless:
+
+- This file does not cover the exact API needed.
+- TypeScript or runtime verification contradicts this file.
+- You are intentionally updating the SDK package itself, not an app that consumes it.
+
+When source fallback is necessary, keep it narrow: inspect the exact exported symbol or declaration that is missing, then return to app code. Do not glob or read the whole SDK package to relearn the basic usage below.
+
+## SDK Mental Model
+
+- `createClient(...)` creates the base HowOne client with auth, entity, AI, upload, and user helpers.
+- `client.entity<TRecord, TCreate, TUpdate>('EntityName')` creates one typed entity client.
+- `defineEntities(...)` plus `withEntities(client, entities)` makes `howone.entities.<EntityName>` typed in app code.
+- `defineAiAction(...)` plus `defineAiActions(...)` plus `withAiActions(...)` makes `howone.ai.<actionName>.run|stream|events` typed in app code.
+- `@howone/sdk/react` provides auth/theme/loading UI primitives only. It does not provide entity, query, or AI data hooks.
+- `.howone/database/manifest.json` and `.howone/ai/manifest.json` are the generated contracts. App source should be generated from those manifests, not from memory.
+
+## Import Reference
 
 ```ts
 // @howone/sdk — all public exports
@@ -51,7 +72,7 @@ import { z } from 'zod'
 
 ---
 
-## createClient — signature & return shape
+## createClient
 
 ```ts
 const client = createClient({
@@ -79,7 +100,7 @@ client.upload.batch({ files, concurrent?, onProgress?, onFileComplete? }): Promi
 
 ---
 
-## EntityClient — complete method signatures
+## EntityClient
 
 ```ts
 type EntityClient<TRecord, TCreate, TUpdate> = {
@@ -126,7 +147,7 @@ type EntityRecord = {
 
 ---
 
-## AI Action — complete signatures
+## AI Action
 
 ```ts
 // Define a typed action
@@ -215,7 +236,6 @@ export const entities = defineEntities({
 export const ai = defineAiActions({
   // generateImage: defineAiAction('generateImage', {
   //   inputSchema: generateImageInputSchema,
-  //   outputSchema: generateImageOutputSchema,
   // }),
 })
 
@@ -224,6 +244,29 @@ const howone = withAiActions(withEntities(client, entities), ai)
 export default howone
 ```
 
+## Manifest-To-Code Recipe
+
+When backend metadata has been synced, generate app SDK code in this order:
+
+1. Read `src/lib/sdk.ts` to preserve the template's import style and existing bindings.
+2. Read `.howone/database/manifest.json` for entity names and fields. Generate `Record`, `Create`, and `Update` types, then bind each entity with `client.entity<Record, Create, Update>('EntityName')`.
+3. Read `.howone/ai/manifest.json` for AI capability names and JSON schemas. Generate zod input schemas and, only when safe, output schemas.
+4. Export a single default `howone` client built by composing `withEntities` and `withAiActions`.
+5. In UI code, import the default client and call `howone.entities.<Entity>.*` or `howone.ai.<action>.run(...)`.
+
+Basic JSON schema mapping for generated zod:
+
+```ts
+string -> z.string()
+number -> z.number()
+integer -> z.number().int()
+boolean -> z.boolean()
+array -> z.array(...)
+object -> z.object({ ... })
+enum -> z.enum([...])
+missing from required[] -> .optional()
+```
+
 ## Entity Types
 
 Prefer explicit payload types:
@@ -248,6 +291,22 @@ export const entities = defineEntities({
 })
 ```
 
+Generated entity app code usually needs only these calls:
+
+```ts
+const result = await howone.entities.Story.query({
+  search,
+  page: { number: 1, size: 20 },
+  orderBy: { createdDate: 'desc' },
+})
+
+await howone.entities.Story.create({ title, content, prompt })
+await howone.entities.Story.update(id, { title })
+await howone.entities.Story.delete(id)
+```
+
+Prefer `query()` for list UIs that need paging/search/sort metadata. Use `list()` only for simple array reads.
+
 Avoid this for generated create payloads:
 
 ```ts
@@ -277,7 +336,6 @@ export type GenerateStoryOutput = z.infer<typeof generateStoryOutputSchema>
 export const ai = defineAiActions({
   generateStory: defineAiAction('generateStory', {
     inputSchema: generateStoryInputSchema,
-    outputSchema: generateStoryOutputSchema,
     mode: 'run',
   }),
 })
@@ -290,6 +348,7 @@ const result = await howone.ai.generateStory.run({
   topic,
   ageRange,
 })
+const story = result.finalResult as GenerateStoryOutput
 ```
 
 For streaming:
@@ -311,15 +370,15 @@ for await (const event of howone.ai.generateStory.events(input)) {
 
 `run()` validates input with `inputSchema`, calls the workflow, then validates the **raw `ExecutionResult`** (the full SSE envelope) with `outputSchema`. It does **not** automatically unwrap `result.finalResult`.
 
-If you want to type the final result only, either:
-1. Define `outputSchema` to match the full `ExecutionResult` shape, or
-2. Omit `outputSchema` and unwrap manually:
+If you want to type the final result only, omit `outputSchema` and unwrap manually:
 
 ```ts
 const result = await howone.ai.generateStory.run(input) // returns AiResult
 const finalResult = result.finalResult as GenerateStoryOutput
 ```
 
+Only define `outputSchema` when it matches the full `ExecutionResult` envelope or after verifying the SDK has changed to validate `finalResult` directly.
+
 ## AI Result Persistence
 
 For AI-generated data that should be saved:
@@ -333,14 +392,46 @@ Example:
 
 ```ts
 const story = await howone.ai.generateStory.run(input)
+const finalResult = story.finalResult as GenerateStoryOutput
 
 await howone.entities.Story.create({
-  title: story.title,
-  content: story.content,
+  title: finalResult.title,
+  content: finalResult.content,
   prompt: input.topic,
 })
 ```
 
+## Do Not Generate
+
+Avoid these patterns unless the SDK has explicitly added them:
+
+```ts
+// No data hooks in @howone/sdk/react
+const todos = useEntity('Todo')
+const query = useQuery(...)
+const result = useAi(...)
+
+// Wrong AI binding shape
+await howone.ai.run.generateStory(input)
+
+// Too-loose create payload
+type StoryCreate = Omit<StoryRecord, 'id' | 'createdDate' | 'updatedDate'>
+
+// Generated files do not belong under .howone
+// .howone stores synced manifests only.
+```
+
+## When To Read SDK Source
+
+Read SDK source or declaration files only for details not covered above, for example:
+
+- A newly added public method not listed here.
+- A TypeScript error proving a signature drifted.
+- A runtime error that points to a specific SDK helper.
+- Work that intentionally modifies `packages/sdk` itself.
+
+For app generation, do not inspect SDK source to rediscover `createClient`, entity CRUD, AI action binding shape, React exports, or Vite env setup.
+
 ## Generated Code Checklist
 
 - `src/lib/sdk.ts` imports only APIs it uses.