howone 0.1.20 → 0.1.23

package/templates/vite/.howone/skills/howone-sdk/{references/04-auth.md → 03-sdk/03-auth.md}

@@ -7,7 +7,7 @@ HowOne has two distinct auth layers:
 1. **Client-level auth** (`client.auth.*`) — low-level token management, login/logout redirects.  
 2. **HowOne Auth service** (`unifiedAuth`, standalone functions) — headless OTP and OAuth flows for building custom login UIs.
 
-For React auth UI, see `references/06-react-integration.md` (`HowOneProvider`, `useHowoneContext`).
+For React auth UI, see `03-sdk/04-react-integration.md` (`HowOneProvider`, `useHowoneContext`).
 
 ---
 
@@ -113,6 +113,15 @@ function useCurrentUser() {
 
 Use `sendEmailVerificationCode` → `loginWithEmailCode` to build a custom email login form.
 
+The SDK normalizes HowOne auth envelopes. Both of these backend response shapes are valid:
+
+```ts
+{ success: true, token: 'jwt...' }
+{ code: 0, data: { success: true, token: 'jwt...' } }
+```
+
+After normalization, read `result.success`, `result.token`, and `result.message` from the top level.
+
 ### Standalone functions (imported directly)
 
 ```ts
@@ -145,7 +154,7 @@ const loginResult = await loginWithEmailCode(
 
 if (loginResult.success && loginResult.token) {
   howone.auth.setToken(loginResult.token)
-  // Now client.auth.isAuthenticated() === true
+  // Persists the token and updates the active SDK client.
 }
 ```
 
@@ -423,6 +432,112 @@ async function checkToken(token: string) {
 }
 ```
 
+## Custom Login UI Pattern
+
+Use this when the app should show its own login page instead of redirecting to `/howone/auth`.
+
+### SDK setup
+
+```ts
+// src/lib/sdk.ts
+import { createClient } from '@howone/sdk'
+
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+  auth: { mode: 'managed' },
+})
+
+export default client
+```
+
+`managed` is still correct for most custom login pages because `howone.auth.setToken(token)`
+persists the token through the SDK auth store. Use `headless` only when an external auth
+provider owns token storage.
+
+### Provider setup
+
+```tsx
+<HowOneProvider auth="none" brand="hidden">
+  <App />
+</HowOneProvider>
+```
+
+`auth="none"` disables the provider redirect so the app can render its own login form.
+
+### App startup
+
+```tsx
+useEffect(() => {
+  let cancelled = false
+
+  howone.me()
+    .then((user) => {
+      if (!cancelled) setUser(user)
+    })
+    .catch(() => {
+      if (!cancelled) setUser(null)
+    })
+    .finally(() => {
+      if (!cancelled) setLoading(false)
+    })
+
+  return () => {
+    cancelled = true
+  }
+}, [])
+```
+
+Do not use `howone.auth.isAuthenticated()` as the first-load gate for protected UI. It is a
+synchronous token presence check. `howone.me()` verifies/restores the current session and is the
+right source of truth for initial render.
+
+### Login success
+
+```ts
+const result = await loginWithEmailCode(email, code)
+if (!result.success || !result.token) {
+  setError(result.message ?? 'Invalid code')
+  return
+}
+
+howone.auth.setToken(result.token)
+const user = await howone.me({ refresh: true })
+setUser(user)
+```
+
+Use the same pattern for phone OTP and OAuth popup results.
+
+### Logout
+
+```ts
+const token = howone.auth.getToken()
+if (token) await unifiedAuth.logout(token)
+howone.auth.logout()
+setUser(null)
+```
+
+`howone.auth.logout()` clears the SDK token store and active client token.
+
+## Headless External Auth Pattern
+
+Use `auth.mode = "headless"` only when another auth system owns the token lifecycle.
+
+```ts
+const client = createClient({
+  projectId: import.meta.env.VITE_HOWONE_PROJECT_ID,
+  env: import.meta.env.VITE_HOWONE_ENV,
+  auth: {
+    mode: 'headless',
+    getToken: async () => externalAuth.getJwt(),
+    tokenCacheMs: 30_000,
+  },
+})
+```
+
+Do not invent a second localStorage key for HowOne OTP/OAuth login. Use `howone.auth.setToken`
+unless the user explicitly asks to integrate an external auth provider.
+
 ---
 
 ## Logout
@@ -495,5 +610,7 @@ const client = createClient({
 |---|---|
 | Phone number without country code: `'13800138000'` | Use E.164: `'+8613800138000'` |
 | Using `loginWithEmailCode` without first calling `sendEmailVerificationCode` | Always send the code first |
-| Setting token manually when using `auth.mode: 'managed'` | Use `managed` mode which handles storage, or switch to `headless` |
+| Hand-writing a separate localStorage token key for HowOne OTP/OAuth | Use `howone.auth.setToken(token)` |
+| Using `auth.isAuthenticated()` to decide first render after refresh | Use `await howone.me()` |
+| Setting `HowOneProvider auth="required"` with a custom in-app login form | Use `auth="none"` so the provider does not redirect |
 | Calling `unifiedAuth.logout()` without the token argument | Pass `token`: `await unifiedAuth.logout(howone.auth.getToken()!)` |

package/templates/vite/.howone/skills/howone-sdk/{references/06-react-integration.md → 03-sdk/04-react-integration.md}

@@ -368,10 +368,8 @@ function AIGenerateButton({ topic }: { topic: string }) {
     }
     setLoading(true)
     try {
-      const res = await howone.ai.generateStory.run({ topic, language: 'en' })
-      if (res.success && res.finalResult) {
-        setResult((res.finalResult as any).content)
-      }
+      const output = await howone.ai.generateStory.run({ topic, language: 'en' })
+      setResult(output.content)
     } finally {
       setLoading(false)
     }

package/templates/vite/.howone/skills/howone-sdk/{references/03-ai-actions.md → 03-sdk/07-ai-action-calls.md}

@@ -4,24 +4,31 @@
 
 **`src/lib/sdk.ts` must be generated from `.howone/ai/manifest.json`. Do not write it from memory or from generic examples.**
 
+For AI capability and workflow design, read `04-ai/` first. This file is only for app-side SDK
+bindings and runtime calls after the manifest exists.
+
 For every capability in `manifest.json`:
 1. Read `name`, `workflowId`, `inputSchema`, `outputSchema`
 2. Generate a zod schema from `inputSchema.properties`
-3. Call `defineAiAction(name, { workflowId, inputSchema })` — **`workflowId` is mandatory**
+3. Generate a zod schema from `outputSchema.properties` when an output schema exists
+4. Call `defineAiAction(name, { workflowId, inputSchema, outputSchema })` — **`workflowId` is mandatory**
 
 Without `workflowId`, the SDK falls back to using the action name as the URL segment. Action names are not UUIDs — the EAX server will reject the call with "invalid input syntax for type uuid".
 
+Do not mark required manifest output fields as `.optional()` to silence validation. Do not add
+`.passthrough()` as a workaround for execution envelopes. A typed `run()` validates and returns the
+workflow `finalResult` payload, not the raw execution envelope.
+
 ## When to Write SDK Bindings
 
-**Do NOT write `defineAiAction` until `.howone/ai/manifest.json` contains a confirmed `workflowId`.**
+**Do NOT write `defineAiAction` until `.howone/ai/manifest.json` contains the workflowId for the capability and the external workflow implementation has been submitted/confirmed by the workflow layer.**
 
 Correct sequence:
-1. `ai_capability_design` — design the capability schema
+1. `ai-capability-design` — design the capability contract
 2. `sync_ai_artifacts` — sync manifest to disk
-3. `external_ai_capability` — submit workflow to EAX; returns confirmed `workflowId`
-4. Confirmed `workflowId` is written back to the backend capability record
-5. `sync_ai_artifacts` again — manifest now contains `workflowId`
-6. Read `.howone/ai/manifest.json` → write `src/lib/sdk.ts` with `workflowId`
+3. `external-ai-capability` — submit workflow create/update to EAX from the synced manifest
+4. Workflow status/background-task layer confirms readiness and captures `workflowConfigID` for future edits
+5. Read `.howone/ai/manifest.json` → write `src/lib/sdk.ts` with `workflowId`
 
 Building without errors does **not** mean the AI workflow binding is correct. A missing `workflowId` causes a runtime UUID error at the EAX execution call.
 
@@ -45,7 +52,7 @@ Building without errors does **not** mean the AI workflow binding is correct. A
 type AiActionConfig<TInput, TOutput> = {
   workflowId: string                 // REQUIRED — UUID from manifest.json. Without this, SDK uses action name as URL segment (not a UUID → EAX rejects).
   inputSchema?: z.ZodType<TInput>    // validates input before calling the workflow
-  outputSchema?: z.ZodType<TOutput>  // validates the full ExecutionResult envelope (see caution below)
+  outputSchema?: z.ZodType<TOutput>  // validates the workflow finalResult payload for run()
   mode?: 'run' | 'stream' | 'events' // default: supports all three modes
 }
 ```
@@ -120,7 +127,7 @@ export const ai = defineAiActions({
 })
 ```
 
-### Action with typed output (unwrap finalResult manually)
+### Action with typed output
 
 ```ts
 export const generateStoryOutputSchema = z.object({
@@ -130,13 +137,11 @@ export const generateStoryOutputSchema = z.object({
 })
 export type GenerateStoryOutput = z.infer<typeof generateStoryOutputSchema>
 
-// Do NOT put outputSchema in defineAiAction unless it matches the full
-// AiResult envelope. Instead, cast finalResult after run():
 export const ai = defineAiActions({
   generateStory: defineAiAction('generateStory', {
     workflowId: 'd69ab648-2c00-4d94-928e-01bd7b2a5bb2', // ← from manifest.json
     inputSchema: generateStoryInputSchema,
-    // outputSchema: omit — cast manually
+    outputSchema: generateStoryOutputSchema,
   }),
 })
 ```
@@ -171,25 +176,21 @@ export const ai = defineAiActions({
 
 ## Calling AI Actions
 
-### run() — await the full result
+### run() — typed action result
 
 ```ts
 import howone, { type GenerateStoryInput, type GenerateStoryOutput } from '@/lib/sdk'
 
 async function generateStory(input: GenerateStoryInput) {
-  const result = await howone.ai.generateStory.run(input)
-  // result is AiResult
-
-  if (!result.success) {
-    throw new Error(result.errors.join(', '))
-  }
-
-  // Cast finalResult to your output type
-  const output = result.finalResult as GenerateStoryOutput
+  const output = await howone.ai.generateStory.run(input)
+  // output is GenerateStoryOutput when outputSchema is configured.
   return output
 }
 ```
 
+When an action has `outputSchema`, `run()` returns the validated workflow `finalResult` payload.
+When an action omits `outputSchema`, `run()` returns the raw `AiResult` execution envelope.
+
 ### run() — with SSE callbacks
 
 ```ts
@@ -362,7 +363,7 @@ type SSEExecutionOptions = {
   // Called if an error occurs
   onError?: (error: Error) => void
 
-  // Called when the workflow completes (same as awaiting run())
+  // Called when the workflow completes with the raw execution envelope
   onComplete?: (result: AiResult) => void
 
   // Abort signal — connect to an AbortController for cancellation
@@ -406,15 +407,11 @@ When AI-generated content should be saved to an entity:
 
 ```ts
 // 1. Run the AI action
-const result = await howone.ai.generateStory.run({
+const output = await howone.ai.generateStory.run({
   topic: 'Dragons and magic',
   ageRange: '6-8',
 })
 
-if (!result.success) throw new Error(result.errors.join(', '))
-
-const output = result.finalResult as GenerateStoryOutput
-
 // 2. Save to entity
 const saved = await howone.entities.Story.create({
   title: output.title,
@@ -448,9 +445,8 @@ function GenerateStoryButton({ input }: { input: GenerateStoryInput }) {
     setLoading(true)
     setError(null)
     try {
-      const res = await howone.ai.generateStory.run(input)
-      if (!res.success) throw new Error(res.errors.join(', '))
-      setResult(res.finalResult as GenerateStoryOutput)
+      const output = await howone.ai.generateStory.run(input)
+      setResult(output)
     } catch (err) {
       if (err instanceof AiSchemaValidationError) {
         setError(`Validation error: ${err.issues.map(i => i.message).join(', ')}`)
@@ -522,10 +518,11 @@ function StreamingStoryGenerator({ input }: { input: GenerateStoryInput }) {
 | Mistake | Correct Pattern |
 |---|---|
 | `defineAiAction('generateStory', { inputSchema })` — no `workflowId` | Always include `workflowId` from `manifest.json`; SDK falls back to action name, which is not a UUID → EAX rejects |
-| Writing `src/lib/sdk.ts` before `sync_ai_artifacts` has a confirmed `workflowId` | Run `external_ai_capability` → `sync_ai_artifacts` first; only write bindings after manifest has `workflowId` |
+| Writing `src/lib/sdk.ts` before `.howone/ai/manifest.json` has a workflowId | Run `ai-capability-design` → `sync_ai_artifacts` → `external-ai-capability`; only write bindings from the synced manifest |
 | Hardcoding `workflowId` from memory or guessing | Always read from `.howone/ai/manifest.json` — copy the exact UUID |
 | `howone.ai.run.generateStory(input)` | `howone.ai.generateStory.run(input)` |
 | Action named `run`, `stream`, or `events` | Rename to e.g. `executeWorkflow`, `streamContent` |
-| `outputSchema: z.object({ title: z.string() })` expecting `finalResult` shape | Omit `outputSchema`; cast `result.finalResult` manually |
-| Not checking `result.success` before using `finalResult` | Always check `if (!result.success) throw new Error(...)` |
+| Passing raw JSON Schema from manifest into `defineAiAction` | Convert JSON Schema fields to Zod first |
+| Making every output field `.optional()` or adding `.passthrough()` after validation fails | Keep manifest-required output fields required; inspect `AiSchemaValidationError.issues` and fix the contract/workflow mismatch |
+| Reading `raw.finalResult`, `raw.data.result`, or `raw.result` after a typed `.run()` | Use the returned value directly when `outputSchema` is configured |
 | Calling `howone.ai.generateStory.run(input)` inside JSX render | Move to event handler or useEffect |

package/templates/vite/.howone/skills/howone-sdk/04-ai/.gitkeep

@@ -0,0 +1 @@
+

package/templates/vite/.howone/skills/howone-sdk/04-ai/01-ai-capability-architecture.md

@@ -0,0 +1,142 @@
+# AI Capability Architecture
+
+Use this reference when a HowOne app needs AI generation, editing, analysis, research, or other
+workflow-backed behavior.
+
+## Core Split
+
+HowOne AI has four separate layers:
+
+1. **Capability contract**: `ai-capability-design` owns the name, description, input schema, output
+   schema, output entity name, workflow ID, versions, preview, apply, restore, and manifest sync.
+2. **External workflow implementation**: `external-ai-capability` submits create/update operations
+   to the workflow service using the synced contract from `.howone/ai/manifest.json`.
+3. **Workflow status/background layer**: status checking, request tracking, completion, failure, and
+   durable background-task behavior are handled outside the contract tool. Preserve request IDs and
+   workflow config IDs for that layer.
+4. **SDK binding and UI**: `src/lib/sdk.ts` is generated from `.howone/ai/manifest.json`, then the
+   app calls `howone.ai.<capability>.run()`, `.stream()`, or `.events()`.
+
+Do not collapse these layers. The common failure is putting workflow implementation, persistence,
+and UI details into the capability schema.
+
+## Source of Truth
+
+```text
+agent proposal != source of truth
+applied AI capability version = source of truth
+.howone/ai/manifest.json = local source for codegen
+src/lib/sdk.ts = generated binding output
+external workflow service = implementation builder/editor
+```
+
+The agent proposes a contract. The backend validates and versions it. The sync tool writes the
+manifest. App code is generated from the manifest.
+
+## Standard AI Feature Workflow
+
+1. Inspect current AI state with `ai-capability-design`.
+2. Design one complete capability patch for the feature.
+3. Preview the patch.
+4. Apply the same operations.
+5. Sync AI artifacts.
+6. Read `.howone/ai/manifest.json`.
+7. Submit external workflow create/update with `external-ai-capability`.
+8. Preserve returned `requestIds` for the status/background-task layer.
+9. Generate or update `src/lib/sdk.ts` from the manifest.
+10. Implement UI calls through `howone.ai.*`.
+11. If generated output must be stored, design database entities after the AI output schema exists.
+
+Do not preview a patch and then submit different operations. Do not restate schemas in
+`external-ai-capability`; it loads the manifest.
+
+## Unsupported AI Requests
+
+If the user explicitly asks for AI capability and the feature cannot be implemented with the
+available workflow service capabilities, stop the AI implementation task and report the gap.
+
+Do not:
+
+- fake the AI feature with static mock data.
+- implement a frontend-only placeholder that pretends AI works.
+- design a workflow that assumes unavailable tools, providers, APIs, or private datasets.
+- silently drop the AI part and continue building a non-AI version.
+- move forbidden work such as database CRUD, auth, upload handling, payments, or app state into the
+  workflow.
+
+The correct response is to state which requested AI behavior is unsupported, which capability is
+missing or which rule blocks it, and what narrower supported alternative could be built.
+
+Only continue implementation when the remaining feature still satisfies the user's intent after
+the unsupported AI capability is removed or narrowed.
+
+## Create vs Update
+
+Use `external-ai-capability` with `mode: "create"` when a capability has no external implementation.
+The tool reads `workflowId`, `inputSchema`, `outputSchema`, and `outputEntityName` from the synced
+manifest.
+
+Use `mode: "update"` when the external workflow implementation needs to change. Updates require:
+
+- `capabilityName`
+- `workflowConfigID`
+- `updatePrompt`
+
+`workflowConfigID` must come from a confirmed workflow status result, specifically
+`payload.workflow_details.new_workflow_config_id`. Do not invent it, omit it, or substitute
+`workflowId`.
+
+If the input/output schema changes, update the capability contract first, sync the manifest, then
+submit the external workflow update.
+
+## Persistence Boundary
+
+AI workflows produce outputs. They do not persist app state.
+
+Workflow can do:
+
+- text generation, summarization, translation, classification, extraction
+- image, video, and audio generation/editing/analysis
+- web research and page crawling
+- financial or academic retrieval
+- file generation or file reading through URLs
+
+Workflow must not do:
+
+- database create/read/update/delete
+- authentication or session handling
+- upload handling
+- payment processing
+- app state management
+- owner assignment or record permissions
+
+If the app saves AI output, derive entity fields from `outputSchema` and add only necessary request
+metadata such as prompt, selected options, status, timestamps, or references.
+
+## Workflow Count
+
+Default rule: one user-facing AI feature maps to one capability and one workflow.
+
+Examples:
+
+- Story + illustration generator: one workflow that returns story text and generated image URLs.
+- Image edit feature: one workflow that accepts source image URL and edit instruction, returns
+  edited image URL.
+- News briefing: one workflow that searches and summarizes, returns briefing and source links.
+
+RAG is the exception:
+
+- indexing workflow: ingests documents and creates retrieval/indexing artifacts.
+- query workflow: answers questions from the indexed knowledge base.
+
+Do not split normal sequential AI steps into multiple capabilities unless they are independently
+triggered product features.
+
+## Capability Naming
+
+Use stable JavaScript-safe identifiers for capability names, for example `generateIllustration` or
+`summarizeDocument`. Do not use display labels as identifiers.
+
+Avoid names that collide with action methods: `run`, `stream`, `events`.
+
+Use `outputEntityName` only when the generated output has a natural persisted record shape.

package/templates/vite/.howone/skills/howone-sdk/04-ai/02-workflow-contract-rules.md

@@ -0,0 +1,169 @@
+# Workflow Contract Rules
+
+Use this reference when designing `inputSchema`, `outputSchema`, and capability descriptions for
+HowOne AI workflows.
+
+## Loose JSON Schema
+
+Workflow schemas should be loose enough for an AI workflow engine.
+
+Rules:
+
+- Require only essential inputs.
+- Mark non-essential options optional.
+- Prefer `string` with a clear description over restrictive enums when user values are open-ended.
+- Avoid `minLength`, `maxLength`, `pattern`, and narrow validation unless there is a concrete
+  technical reason.
+- Avoid nested objects when a simple described string is enough.
+- Avoid exposing implementation knobs the user does not need.
+
+Good:
+
+```json
+{
+  "tone": {
+    "type": "string",
+    "description": "Desired writing tone, e.g. formal, casual, humorous, empathetic, professional."
+  }
+}
+```
+
+Use enums only for truly closed domains.
+
+## URLs, Not Raw Files
+
+All file exchange uses URLs.
+
+Rules:
+
+- File inputs are strings with `format: "uri"`, such as `document_url`, `source_image_url`, or
+  `audio_file_url`.
+- File outputs are strings with `format: "uri"`, such as `generated_image_url`, `edited_video_url`,
+  or `result_pdf_url`.
+- Never use base64, raw bytes, inline file content, or `contentEncoding`.
+- The app uploads user files first, then passes the URL to the workflow.
+
+## Output Minimalism
+
+The workflow will try to fill every output field. Only ask for fields the product needs.
+
+Usually forbidden unless explicitly requested:
+
+- timestamps and processing time
+- file size, MIME type, encoding, dimensions, frame rate, bitrate
+- confidence scores and bounding boxes
+- model, provider, version, cost, or internal execution metadata
+- style/tone metadata when the user only asked for an asset
+
+Examples:
+
+| User Need | Good Output | Avoid |
+|---|---|---|
+| Summarize a document | `summary` | `summary`, `word_count`, `reading_time` |
+| Generate an image | `generated_image_url` | `generated_image_url`, `model_used`, `color_palette` |
+| OCR an image | `extracted_text` | `extracted_text`, `confidence_score`, `bounding_boxes` |
+
+## No Input/Output Name Overlap
+
+Input and output property names must not overlap. The workflow engine uses a shared parameter
+namespace.
+
+Bad:
+
+```json
+{
+  "inputSchema": { "properties": { "text": { "type": "string" } } },
+  "outputSchema": { "properties": { "text": { "type": "string" } } }
+}
+```
+
+Good:
+
+```json
+{
+  "inputSchema": { "properties": { "source_text": { "type": "string" } } },
+  "outputSchema": { "properties": { "translated_text": { "type": "string" } } }
+}
+```
+
+Common pairs:
+
+- `source_text` -> `translated_text`
+- `source_content` -> `summary`
+- `source_image_url` -> `edited_image_url`
+- `description_prompt` -> `generated_image_url`
+
+## Output Language
+
+Every text output field description must specify the language rule.
+
+Use one of these patterns:
+
+- fixed: "Summary in English."
+- input-driven: "Translated text in the target language specified by `target_language`."
+- source-driven: "Summary in the same language as the source document."
+- mixed: "Extracted text, which may contain mixed Chinese and English content."
+
+Do not write vague descriptions like "The translated text."
+
+## Description Says What, Not How
+
+`capability.description` describes the user outcome.
+
+Do:
+
+```json
+{
+  "description": "Searches the web for the latest news on a topic and produces a structured briefing with source links."
+}
+```
+
+Do not:
+
+```json
+{
+  "description": "First calls search_web, then summarizes each article with an LLM, then saves JSON."
+}
+```
+
+Never mention internal tool names, step sequences, providers, or model names in the capability
+description.
+
+## Available Capability Families
+
+Design only around capabilities available to the workflow service:
+
+- web search and page crawling
+- image generation, editing, analysis, OCR
+- video generation, editing, concatenation, frame extraction
+- audio generation, recognition, merging
+- financial price history retrieval
+- academic paper search and bibliography
+- file storage/read for JSON, YAML, CSV, PDF, Markdown, TXT
+- email sending
+- RSS feed fetching
+- Airbnb search
+- Hacker News search
+
+If the requested product needs unavailable functionality, redesign the feature around available
+capabilities or exclude it explicitly.
+
+When the user explicitly requires the unavailable AI behavior, terminate the AI task instead of
+building a fake or silently degraded implementation. Report the unsupported requirement and the
+closest supported alternative.
+
+## External Data Assumptions
+
+Do not assume the user can provide external datasets unless they explicitly say so.
+
+For "stock analysis", use a workflow input such as `trading_symbol` and let the workflow retrieve
+history. Do not require `stock_data_csv_url` unless the user says they have a CSV.
+
+For "latest news", use web search inside the workflow. Do not ask the user to provide article URLs
+unless that is the product requirement.
+
+## MVP Limit
+
+Keep AI app generation to at most five core features. Exclude feedback forms, onboarding tutorials,
+notification settings, export, sharing, personalization, and preferences unless the user explicitly
+requests them.