howone 0.1.8 → 0.1.9

package/package.json

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

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

@@ -29,4 +29,4 @@ Use this skill when writing app code that consumes `@howone/sdk`. The goal is st
 
 ## References
 
-Read `references/usage-patterns.md` when implementing or reviewing actual code.
+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.

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

@@ -1,5 +1,192 @@
 # 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.
+
+## Complete 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 — signature & return shape
+
+```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 — complete method signatures
+
+```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 — complete signatures
+
+```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:
@@ -120,20 +307,19 @@ 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, either:
+1. Define `outputSchema` to match the full `ExecutionResult` shape, or
+2. 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.
-
 ## AI Result Persistence
 
 For AI-generated data that should be saved:

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",