howone 0.1.22 → 0.1.23

package/package.json

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

package/templates/nextjs/lib/sdk.ts

@@ -18,6 +18,9 @@ export const entities = defineEntities({
 
 export const ai = defineAiActions({
   // Add generated AI action bindings here, for example:
+  // import { z } from "zod" and define Zod schemas before using defineAiAction.
+  // Do not paste JSON Schema objects from .howone/ai/manifest.json here directly.
+  // With outputSchema configured, howone.ai.<action>.run() returns the validated finalResult payload.
   // generateImage: defineAiAction("generateImage", {
   //   inputSchema: generateImageInputSchema,
   //   outputSchema: generateImageOutputSchema,

package/templates/vite/.howone/skills/howone-sdk/01-architect/01-app-generation.md

@@ -9,8 +9,10 @@ HowOne generated apps have three layers:
 
 1. **Backend contract**: dynamic entities, access rules, indexes, schema versions, and synced
    manifests.
-2. **SDK binding**: `src/lib/sdk.ts` converts manifests into typed entity and AI clients.
-3. **Frontend experience**: React/UI code calls the SDK and owns app-specific interaction design.
+2. **AI contract + workflow implementation**: AI capability contracts are versioned by HowOne;
+   external workflow create/update is submitted from synced AI manifests.
+3. **SDK binding**: `src/lib/sdk.ts` converts manifests into typed entity and AI clients.
+4. **Frontend experience**: React/UI code calls the SDK and owns app-specific interaction design.
 
 Do not skip the binding layer. The UI should call `src/lib/sdk.ts`, not raw entity names guessed
 from the user prompt.
@@ -60,6 +62,29 @@ When a request adds persistence or changes data shape:
 Do not preview a patch and then execute different single operations. Related schema changes for
 one feature should be grouped into one preview/apply cycle.
 
+## AI Feature Workflow
+
+When a request adds an AI capability or changes an AI workflow:
+
+1. Read `04-ai/01-ai-capability-architecture.md` and
+   `04-ai/02-workflow-contract-rules.md`.
+2. Inspect current AI capability state.
+3. Design one complete AI capability patch for the feature.
+4. Preview the AI patch.
+5. Apply the exact previewed operations.
+6. Sync AI artifacts.
+7. Read `.howone/ai/manifest.json`.
+8. Submit external workflow create/update with `external-ai-capability`.
+9. Preserve returned request IDs for the status/background-task layer.
+10. Read `04-ai/03-ai-sdk-handoff.md`, `01-architect/02-manifest-codegen.md`, and
+    `03-sdk/07-ai-action-calls.md`.
+11. Update `src/lib/sdk.ts` from the synced manifest.
+12. Update the UI.
+13. Validate.
+
+If generated output must be saved, design the AI capability first. Then derive persistence entities
+from the synced AI `outputSchema`, plus only necessary request metadata.
+
 ## Auth Decision
 
 Use hosted auth when the app just needs login:

package/templates/vite/.howone/skills/howone-sdk/01-architect/02-manifest-codegen.md

@@ -13,6 +13,11 @@ HowOne apps are driven by two backend-synced manifests:
 
 Sync tools (`sync_schema_artifacts`, `sync_ai_artifacts`) write the manifests. The coding agent reads the manifests and writes `src/lib/sdk.ts`.
 
+For AI capabilities, external workflow create/update is submitted by `external-ai-capability` from
+the synced manifest. Do not duplicate AI schemas in app code beyond generated zod/type bindings.
+For workflow edits, `workflowConfigID` belongs to the external workflow operation; it is not an SDK
+binding field.
+
 ---
 
 ## Reading `.howone/database/manifest.json`
@@ -157,6 +162,7 @@ export type CommentUpdate = Partial<CommentCreate>
     {
       "id": "generateStory",
       "name": "Generate Story",
+      "workflowId": "d69ab648-2c00-4d94-928e-01bd7b2a5bb2",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -179,6 +185,7 @@ export type CommentUpdate = Partial<CommentCreate>
     {
       "id": "translateText",
       "name": "Translate Text",
+      "workflowId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -219,12 +226,12 @@ export const generateStoryInputSchema = z.object({
 })
 export type GenerateStoryInput = z.infer<typeof generateStoryInputSchema>
 
-// Output type for manual unwrapping (do NOT put in defineAiAction as outputSchema)
-export type GenerateStoryOutput = {
-  title: string
-  content: string
-  summary?: string
-}
+export const generateStoryOutputSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+  summary: z.string().optional(),
+})
+export type GenerateStoryOutput = z.infer<typeof generateStoryOutputSchema>
 
 // ── translateText ─────────────────────────────────────────────
 export const translateTextInputSchema = z.object({
@@ -235,6 +242,10 @@ export const translateTextInputSchema = z.object({
 export type TranslateTextInput = z.infer<typeof translateTextInputSchema>
 ```
 
+Do not make required output fields optional to silence validation failures. Do not add
+`.passthrough()` as a workaround for EAX execution envelopes. `defineAiAction` validates the
+workflow `finalResult` payload when an `outputSchema` is configured.
+
 ---
 
 ## Full Generated `src/lib/sdk.ts`
@@ -303,11 +314,12 @@ export const generateStoryInputSchema = z.object({
   language: z.string().optional(),
 })
 export type GenerateStoryInput = z.infer<typeof generateStoryInputSchema>
-export type GenerateStoryOutput = {
-  title: string
-  content: string
-  summary?: string
-}
+export const generateStoryOutputSchema = z.object({
+  title: z.string(),
+  content: z.string(),
+  summary: z.string().optional(),
+})
+export type GenerateStoryOutput = z.infer<typeof generateStoryOutputSchema>
 
 export const translateTextInputSchema = z.object({
   text: z.string(),
@@ -315,10 +327,6 @@ export const translateTextInputSchema = z.object({
   formality: z.enum(['formal', 'informal']).optional(),
 })
 export type TranslateTextInput = z.infer<typeof translateTextInputSchema>
-export type TranslateTextOutput = {
-  translatedText: string
-  detectedLang?: string
-}
 
 // ═══════════════════════════════════════════════════════════════
 // CLIENT
@@ -344,9 +352,12 @@ export const entities = defineEntities({
 
 export const ai = defineAiActions({
   generateStory: defineAiAction('generateStory', {
+    workflowId: 'd69ab648-2c00-4d94-928e-01bd7b2a5bb2',
     inputSchema: generateStoryInputSchema,
+    outputSchema: generateStoryOutputSchema,
   }),
   translateText: defineAiAction('translateText', {
+    workflowId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
     inputSchema: translateTextInputSchema,
   }),
 })
@@ -371,7 +382,11 @@ Before finalising generated code, verify:
 - [ ] System fields are not present in create/update input types
 - [ ] Public query/write types are generated only from `access.public.allowedFilters`, `allowedSorts`, `requiredScopes`, and write permissions
 - [ ] Every AI action from `.howone/ai/manifest.json` has an `inputSchema` zod object
+- [ ] Every AI action with manifest `outputSchema` has a matching zod `outputSchema`
+- [ ] Every AI action binding includes the exact manifest `workflowId`
 - [ ] Required input fields are not `.optional()` in zod
+- [ ] Required output fields are not `.optional()` in zod
+- [ ] AI output schemas do not use `.passthrough()` to hide execution-envelope mismatches
 - [ ] AI action names match the manifest `id` exactly (case-sensitive)
 - [ ] `createClient` uses `import.meta.env.*` only
 - [ ] `withEntities` is applied before `withAiActions` in the composition chain
@@ -418,10 +433,7 @@ When the app generates data with AI and saves it to an entity:
 // Save it to Story entity which adds: authorId, status, wordCount
 
 async function generateAndSave(input: GenerateStoryInput, authorId: string) {
-  const result = await howone.ai.generateStory.run(input)
-  if (!result.success) throw new Error(result.errors.join(', '))
-
-  const output = result.finalResult as GenerateStoryOutput
+  const output = await howone.ai.generateStory.run(input)
 
   return howone.entities.Story.create({
     title: output.title,

package/templates/vite/.howone/skills/howone-sdk/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/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/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.

package/templates/vite/.howone/skills/howone-sdk/04-ai/03-ai-sdk-handoff.md

@@ -0,0 +1,80 @@
+# AI SDK Handoff
+
+Use this reference after AI capability artifacts have been synced and app code needs to call the
+workflow.
+
+## Binding Source
+
+Generate `src/lib/sdk.ts` from `.howone/ai/manifest.json`. Do not write AI bindings from memory or
+from the original user prompt.
+
+For each manifest capability:
+
+1. Read `name`.
+2. Read `workflowId`.
+3. Read `inputSchema`.
+4. Read `outputSchema`.
+5. Generate zod input and output schemas from the JSON Schema fields.
+6. Bind with `defineAiAction(name, { workflowId, inputSchema, outputSchema })`.
+
+`workflowId` is mandatory. Without it, the SDK falls back to the action name as the execution URL
+segment, which is not a workflow UUID.
+
+## Output Handling
+
+For a typed action with `outputSchema`, `.run()` returns the validated workflow output payload.
+The SDK unwraps the EAX execution envelope and validates `finalResult` internally.
+
+Use this pattern:
+
+```ts
+const output = await howone.ai.generateSummary.run(input)
+// output is GenerateSummaryOutput when outputSchema is configured.
+```
+
+Do not read `raw.finalResult`, `raw.result`, or `raw.data.result` from a typed action result. Those
+paths are execution/SSE internals. App code should use the value returned by `.run()` directly.
+
+Do not make every output field `.optional()` or add `.passthrough()` to hide validation errors.
+Required fields in the manifest must stay required in Zod. If validation fails, inspect
+`AiSchemaValidationError.issues` and fix the capability contract or workflow output mapping.
+
+## UI State
+
+AI calls should run in event handlers, effects, or explicit async actions. Never call
+`howone.ai.*.run()` inside JSX render.
+
+Recommended UI states:
+
+- idle
+- running
+- succeeded
+- failed
+- cancelled when using streaming
+
+For streaming, keep the `AiSession` in a ref and call `cancel()` from the UI.
+
+## Persistence Handoff
+
+If the app stores generated output:
+
+1. Run the AI workflow.
+2. Use the typed output returned by `.run()`.
+3. Write the resulting data through `howone.entities.*`.
+
+Do not ask the workflow to write to the database. Do not pass owner fields for authenticated
+user-owned entities; HowOne derives ownership from the JWT.
+
+## Workflow Edit Handoff
+
+When editing an external workflow implementation later, use `external-ai-capability` with:
+
+- `mode: "update"`
+- `capabilityName`
+- `workflowConfigID`
+- `updatePrompt`
+
+`workflowConfigID` is not `workflowId`. It comes from a confirmed workflow status result:
+`payload.workflow_details.new_workflow_config_id`.
+
+If the schema changed, update and sync the capability contract before submitting the workflow edit.

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

@@ -1,12 +1,17 @@
 ---
 name: howone-sdk
-description: Design and implement HowOne generated apps correctly. Use when planning HowOne app architecture, designing backend entity schema/access, wiring @howone/sdk in src/lib/sdk.ts, implementing auth flows, calling howone.entities.* or howone.public.entities.*, generating SDK bindings from .howone manifests, or reviewing HowOne app runtime integration.
+description: Required operating manual for HowOne generated apps. Use for backend schema/API design, frontend UI implementation that reads or writes HowOne data, AI capability/workflow design, SDK binding/codegen from .howone manifests, auth, uploads, public/private access, and any code that calls @howone/sdk, howone.entities.*, howone.public.entities.*, or howone.ai.*.
 ---
 
 # HowOne App Architecture Skill
 
-This skill is one HowOne app-building skill with numbered internal tracks. Load the smallest track
-that matches the task; do not read every file by default.
+This skill is the operating manual for generated HowOne apps. Use it before making platform
+decisions for backend data, frontend data access, auth, AI capabilities, SDK bindings, or generated
+app code that depends on HowOne runtime behavior.
+
+Load the smallest set of numbered references that match the task, but do not skip this skill for
+backend schema design, frontend implementation, or AI features. The references define the contracts
+that app code must follow.
 
 ## Active Tracks
 
@@ -15,19 +20,22 @@ that matches the task; do not read every file by default.
 | `01-architect/` | App generation + manifest flow | End-to-end HowOne app generation flow: when to design backend, when to sync manifests, when to update SDK bindings, and how to choose auth/data posture. |
 | `02-database/` | Backend schema + data access design | Entity schema contract, schema operations, access modes, owner/public data posture, indexes, versions, and guardrails. |
 | `03-sdk/` | Frontend SDK usage | `src/lib/sdk.ts`, auth, React provider, entity calls, public data, uploads, raw HTTP, AI action calls. |
-
-Reserved directory:
-
-- `04-ai/` is intentionally present for future AI capability design. Do not use it yet. For now,
-  only use `03-sdk/07-ai-action-calls.md` when wiring an already-synced AI action into app code.
+| `04-ai/` | AI capability + workflow design | HowOne AI capability contracts, external workflow create/update submission, workflow schema rules, persistence boundaries, and SDK handoff. |
 
 ## Routing
 
-Read references by task shape:
+Read references by task shape. Prefer exact references over generic examples.
 
 - New HowOne app or broad feature planning: read `01-architect/01-app-generation.md`.
+- Any feature touching backend data, frontend data access, or saved records: read the architect
+  flow first, then the relevant database and SDK references below.
+- Any feature touching AI generation, AI workflow behavior, or AI outputs: read the AI references
+  first, then the SDK handoff/action-call references.
+- AI capability, AI workflow generation/editing, or full-stack AI feature planning: read
+  `04-ai/01-ai-capability-architecture.md` and `04-ai/02-workflow-contract-rules.md`.
 - Backend database/schema creation or change: read `02-database/01-schema-design.md` and
   `02-database/02-schema-operations.md`.
+- AI output persistence: read the `04-ai/` files first, then `02-database/01-schema-design.md`.
 - After schema sync, when app code must call the entity: read
   `01-architect/02-manifest-codegen.md` and `03-sdk/02-entity-operations.md`.
 - Custom login page, Email OTP, Phone OTP, Google, GitHub, token persistence, repeated login,
@@ -38,6 +46,28 @@ Read references by task shape:
   `03-sdk/02-entity-operations.md`, and `01-architect/02-manifest-codegen.md`.
 - File upload: read `03-sdk/05-file-upload.md`.
 - Raw HTTP escape hatch: read `03-sdk/06-raw-http.md`.
+- App-side AI action calls after `.howone/ai/manifest.json` exists: read
+  `03-sdk/07-ai-action-calls.md`.
+
+## Reference Selection Protocol
+
+Before writing code, classify the touched surfaces:
+
+| Touched surface | Required references |
+|---|---|
+| New app, feature architecture, or uncertain data posture | `01-architect/01-app-generation.md` |
+| Entity/schema/access/index change | `02-database/01-schema-design.md`, `02-database/02-schema-operations.md` |
+| Existing synced manifest to TypeScript bindings | `01-architect/02-manifest-codegen.md` |
+| UI reads/writes entities | `03-sdk/01-client-setup.md`, `03-sdk/02-entity-operations.md` |
+| Public read/share flow | `02-database/03-data-access-patterns.md`, `03-sdk/02-entity-operations.md` |
+| Auth/session/login behavior | `03-sdk/03-auth.md`, `03-sdk/04-react-integration.md` |
+| AI capability or workflow design | `04-ai/01-ai-capability-architecture.md`, `04-ai/02-workflow-contract-rules.md` |
+| AI manifest handoff to app code | `04-ai/03-ai-sdk-handoff.md`, `03-sdk/07-ai-action-calls.md` |
+| File upload | `03-sdk/05-file-upload.md` |
+| Raw HTTP escape hatch | `03-sdk/06-raw-http.md` |
+
+If a task spans multiple surfaces, read one reference from each surface before editing. Do not
+invent API parameters, response shapes, owner fields, workflow IDs, or output paths from memory.
 
 ## Core Workflow
 
@@ -52,6 +82,20 @@ For app features that touch backend data:
 6. Implement frontend calls using the SDK track.
 7. Validate with the app's typecheck/build.
 
+For app features that touch AI:
+
+1. Decide the AI feature boundary in the AI track: one workflow per feature, except RAG uses
+   indexing and query workflows.
+2. Design or update the AI capability contract with `ai-capability-design`.
+3. Preview/apply the same AI patch, then sync AI artifacts.
+4. Submit external workflow create/update with `external-ai-capability`.
+5. Preserve returned request IDs for the workflow status/background-task layer.
+6. Read `.howone/ai/manifest.json`.
+7. Generate or update app SDK bindings from the manifest.
+8. Implement frontend calls using `howone.ai.*`.
+9. If outputs are saved, derive entity fields from the AI `outputSchema`, then follow the database
+   workflow.
+
 For frontend-only SDK work:
 
 1. Read existing `src/lib/sdk.ts`.
@@ -73,3 +117,10 @@ For frontend-only SDK work:
   reads or writes.
 - For custom in-app login, use `HowOneProvider auth="none"`, call
   `howone.auth.setToken(token)` on success, and verify startup session with `await howone.me()`.
+- AI workflows are implementation, not persistence. Never put CRUD, auth, upload handling, or app
+  state management into the workflow capability contract.
+- For external workflow edits, pass `workflowConfigID` from a confirmed workflow status result; do
+  not invent it or omit it.
+- If the user explicitly requires AI behavior that the available workflow service cannot support,
+  stop that AI implementation path and report the unsupported requirement instead of faking,
+  silently omitting, or replacing the AI capability with static behavior.

package/templates/vite/src/lib/sdk.ts

@@ -18,6 +18,9 @@ export const entities = defineEntities({
 
 export const ai = defineAiActions({
   // Add generated AI action bindings here, for example:
+  // import { z } from "zod" and define Zod schemas before using defineAiAction.
+  // Do not paste JSON Schema objects from .howone/ai/manifest.json here directly.
+  // With outputSchema configured, howone.ai.<action>.run() returns the validated finalResult payload.
   // generateImage: defineAiAction("generateImage", {
   //   workflowId: "<workflow-uuid>", // workflow ID for this capability
   //   inputSchema: generateImageInputSchema,