howone 0.1.8 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.1.8",
+  "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` when implementing or reviewing actual code.
+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,5 +1,213 @@
 # HowOne SDK Usage Patterns
 
+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.
+
+## 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
+import {
+  createClient,
+  defineAiAction,
+  defineAiActions,
+  defineEntities,
+  withAiActions,
+  withEntities,
+  type CreateClientOptions,
+  type EntityRecord,
+  type EntityClient,
+  type EntityBindings,
+  type QueryOptions,
+  type QueryResult,
+  type PageInfo,
+  type DeleteResult,
+  type AiClient,
+  type AiActionDefinition,
+  type AiActionClient,
+  type AiActionConfig,
+  type AiResult,       // = ExecutionResult
+  type AiSession,      // { result: Promise<AiResult>, cancel(): void, signal: AbortSignal }
+  type AiEvent,        // SSE event payload
+  type AiOptions,
+  type UserProfile,
+  AiSchemaValidationError,
+} from '@howone/sdk'
+
+// @howone/sdk/react — React components and hooks
+import {
+  HowOneProvider,
+  useHowoneContext,
+  FloatingButton,
+  Loading,
+  LoadingSpinner,
+  type HowOneProviderProps,
+  type HowOneAuthMode,
+  type HowOneThemeMode,
+  type HowOneBrandMode,
+} from '@howone/sdk/react'
+
+import { z } from 'zod'
+```
+
+---
+
+## createClient
+
+```ts
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,  // required in Vite apps
+  env: import.meta.env.VITE_HOWONE_ENV,               // 'local' | 'dev' | 'prod'
+  // Optional advanced options (rarely needed):
+  // apiUrl, aiUrl, caseStyle ('camel'|'snake'), auth: { mode, getToken }
+})
+
+// client shape:
+client.entity<TRecord, TCreate, TUpdate>(entityName: string): EntityClient<...>
+client.entities: Record<string, EntityClient>
+client.ai: AiClient  // low-level; prefer withAiActions bindings
+client.me(): Promise<UserProfile | null>
+client.requireMe(): Promise<UserProfile>
+client.auth.setToken(t: string | null): void
+client.auth.getToken(): string | null
+client.auth.isAuthenticated(): boolean
+client.auth.login(redirect?: string): void
+client.auth.logout(): void
+client.upload.file(file, options?): Promise<{ url, thumbnailUrl?, id?, size?, mimeType? }>
+client.upload.image(file): Promise<{ url }>
+client.upload.batch({ files, concurrent?, onProgress?, onFileComplete? }): Promise<BatchUploadResponse>
+```
+
+---
+
+## EntityClient
+
+```ts
+type EntityClient<TRecord, TCreate, TUpdate> = {
+  name: string
+  // Basic CRUD
+  list(options?: { page?, limit?, sort?, order?, ...filters }): Promise<TRecord[]>
+  get(id: string): Promise<TRecord | null>
+  getOrThrow(id: string): Promise<TRecord>
+  create(data: TCreate): Promise<TRecord>
+  update(id: string, data: TUpdate): Promise<TRecord>
+  delete(id: string): Promise<{ deleted: boolean; id: string; message? }>
+  // Advanced query with filters/pagination
+  query(options?: QueryOptions<TRecord>): Promise<QueryResult<TRecord>>
+  query.mine(options?: QueryOptions<TRecord>): Promise<QueryResult<TRecord>>
+  bulkCreate(records: TCreate[], options?: { sample?: boolean }): Promise<TRecord[]>
+  aggregate(pipeline: unknown[]): Promise<unknown[]>
+}
+
+// QueryOptions
+type QueryOptions<TRecord> = {
+  where?: { [K in keyof TRecord]?: TRecord[K] | FieldOperator }
+  // FieldOperator: { eq, ne, gt, gte, lt, lte, contains, like, startsWith, endsWith, in, notIn }
+  search?: string
+  page?: { number?: number; size?: number }
+  orderBy?: Partial<Record<keyof TRecord | string, 'asc' | 'desc'>>
+}
+
+// QueryResult
+type QueryResult<T> = {
+  items: T[]
+  page: { number, size, total, totalPages, hasNext, hasPrev }
+}
+
+// EntityRecord base
+type EntityRecord = {
+  id: string
+  createdDate?: string
+  updatedDate?: string
+  createdById?: string
+  isSample?: boolean
+  [key: string]: unknown
+}
+```
+
+---
+
+## AI Action
+
+```ts
+// Define a typed action
+defineAiAction(id: string, config?: {
+  inputSchema?: z.ZodType<TInput>
+  outputSchema?: z.ZodType<TOutput>
+  mode?: 'run' | 'stream' | 'events'
+}): AiActionDefinition<TInput, TOutput>
+
+// Group actions
+defineAiActions({ [name]: AiActionDefinition, ... }): actions
+
+// Bind to client
+withAiActions(client, actions): client & { ai: { [name]: AiActionClient } }
+
+// AiActionClient methods
+howone.ai.<actionName>.run(inputs?, options?): Promise<TOutput>
+howone.ai.<actionName>.stream(inputs?, options?): AiSession
+howone.ai.<actionName>.events(inputs?, options?): AsyncIterable<AiEvent>
+
+// AiSession
+type AiSession = {
+  result: Promise<AiResult>
+  cancel(): void
+  signal: AbortSignal
+}
+
+// Reserved names — do NOT use as action names: run, stream, events
+```
+
+---
+
+## React: HowOneProvider & hooks
+
+`@howone/sdk/react` exports exactly: `HowOneProvider`, `useHowoneContext`, `FloatingButton`, `Loading`, `LoadingSpinner`.
+
+**There are no `useEntity`, `useQuery`, `useAi`, or other data-fetching hooks.** Entity and AI calls are plain async functions — call them directly in components with `useEffect`/`useState` or any data-fetching library (SWR, React Query, etc.).
+
+```tsx
+// Wrap app root — handles auth, theme, toasts, floating button
+<HowOneProvider
+  projectId={...}           // optional if client is already configured
+  auth="optional"           // 'required' | 'optional' | 'none'
+  brand="visible"           // 'visible' | 'hidden'
+  theme="inherit"           // 'dark' | 'light' | 'system' | 'inherit'
+  showBrandButton={true}
+>
+  <App />
+</HowOneProvider>
+
+// Auth context hook — the only hook in the package
+const { user, token, isAuthenticated, logout } = useHowoneContext()
+// user shape: { id, email, name, avatar } | null
+
+// Loading components
+<Loading size="md" tone="brand" label="..." description="..." fullScreen />
+<LoadingSpinner size="sm" tone="neutral" />
+// size: 'sm' | 'md' | 'lg'    tone: 'brand' | 'neutral' | 'inverse'
+```
+
 ## App SDK Entry
 
 Preferred Vite app entry shape:
@@ -28,7 +236,6 @@ export const entities = defineEntities({
 export const ai = defineAiActions({
   // generateImage: defineAiAction('generateImage', {
   //   inputSchema: generateImageInputSchema,
-  //   outputSchema: generateImageOutputSchema,
   // }),
 })
 
@@ -37,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:
@@ -61,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
@@ -90,7 +336,6 @@ export type GenerateStoryOutput = z.infer<typeof generateStoryOutputSchema>
 export const ai = defineAiActions({
   generateStory: defineAiAction('generateStory', {
     inputSchema: generateStoryInputSchema,
-    outputSchema: generateStoryOutputSchema,
     mode: 'run',
   }),
 })
@@ -103,6 +348,7 @@ const result = await howone.ai.generateStory.run({
   topic,
   ageRange,
 })
+const story = result.finalResult as GenerateStoryOutput
 ```
 
 For streaming:
@@ -120,19 +366,18 @@ for await (const event of howone.ai.generateStory.events(input)) {
 }
 ```
 
-## AI Output Validation Caveat
+## AI Output Validation
 
-Check `packages/sdk/src/services/ai.ts` before relying on output validation. The desired behavior is for `defineAiAction(...).run()` to validate and return the workflow final result, not the whole SSE execution envelope.
+`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`.
 
-Desired implementation shape:
+If you want to type the final result only, omit `outputSchema` and unwrap manually:
 
 ```ts
-const result = await base.run(definition.id, validInputs, options)
-const output = result?.finalResult ?? result
-return parseAiValue(definition.id, 'output', output, definition.outputSchema)
+const result = await howone.ai.generateStory.run(input) // returns AiResult
+const finalResult = result.finalResult as GenerateStoryOutput
 ```
 
-If the SDK still validates the whole `ExecutionResult`, either fix the SDK first or avoid generating final-result `outputSchema` in app code that will immediately run.
+Only define `outputSchema` when it matches the full `ExecutionResult` envelope or after verifying the SDK has changed to validate `finalResult` directly.
 
 ## AI Result Persistence
 
@@ -147,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.

package/templates/vite/AGENTS.md

@@ -6,6 +6,39 @@ Read this file once when entering the project.
 Follow it during implementation.
 Do not repeatedly reread it unless it changes or the current task requires checking project rules again.
 
+## Multi-turn Policy
+
+After reading this file, maintain a concise project policy summary for the active workspace session.
+Use that summary across turns instead of rereading this file or relying on old chat history.
+
+The project policy summary should stay short and include only durable rules:
+
+- package manager and common commands
+- trusted libraries and framework assumptions
+- context-loading rules
+- validation rules
+- project-specific constraints
+
+Do not store transient command output, temporary reasoning, full file contents, or step-by-step logs in the project policy.
+
+Maintain a separate short task state summary while implementing a user request:
+
+- current goal
+- current phase: explore, implement, validate, fix, or done
+- files already read
+- files changed
+- last validation command and result
+- known blockers or open questions
+
+Use task state to avoid repeating exploration or rereading unchanged files. Reset or replace it when the user starts a new unrelated task.
+
+Do not reread this file unless:
+
+- this file changed
+- the project policy summary is unavailable
+- the task enters a nested project with its own `AGENTS.md`
+- validation errors suggest a project rule was missed
+
 ## Library Trust Policy
 
 For common public libraries already known to modern coding models, prefer model knowledge and package metadata over reading local source files.
@@ -43,4 +76,22 @@ Only read local component or library-style source files when:
 - the project has custom wrappers, custom variants, or unusual exports
 - the user explicitly asks to follow local component conventions
 
-Prefer failure-driven inspection over speculative context loading.
+Prefer failure-driven inspection over speculative context loading.
+
+## Context Budget Policy
+
+Start with the smallest useful context:
+
+1. Identify the app root and relevant scripts.
+2. Read the smallest file that directly controls the requested behavior.
+3. Prefer package metadata, config files, and public API usage before local library internals.
+4. Expand to additional files only when implementation, validation, or ambiguity requires it.
+
+Avoid broad project scans unless the user asks for a repository-wide change or the relevant files are genuinely unknown.
+
+## Validation Policy
+
+After meaningful code changes, run the narrowest relevant validation command available in this project.
+Prefer build or typecheck before deeper investigation into library internals.
+
+If validation fails, inspect the smallest file or error location needed to fix the failure.

package/templates/vite/package.json

@@ -35,7 +35,9 @@
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "^4.2.1",
     "tw-animate-css": "^1.4.0",
-    "vaul": "^1.1.2"
+    "vaul": "^1.1.2",
+    "zod": "^4.3.6",
+    "framer-motion": "^12.38.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",