howone 0.1.22 → 0.1.25

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
@@ -212,6 +213,25 @@ const result = await howone.ai.generateStory.run(input, {
 })
 ```
 
+UI feedback belongs in the frontend app. Do not import or expect SDK toast APIs. Use returned
+promises and callbacks to update app-owned state:
+
+```ts
+setStatus({ type: 'loading', message: 'Generating story...' })
+
+try {
+  const output = await howone.ai.generateStory.run(input, {
+    onProgress: (progress) => setProgress(progress),
+  })
+  setStatus({ type: 'success', message: 'Story ready', output })
+} catch (error) {
+  setStatus({
+    type: 'error',
+    message: error instanceof Error ? error.message : 'Story generation failed',
+  })
+}
+```
+
 ### stream() — start and control a session
 
 ```ts
@@ -362,7 +382,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
@@ -402,32 +422,59 @@ try {
 
 ## AI Result Persistence
 
-When AI-generated content should be saved to an entity:
+When AI-generated content should be saved to an entity, prefer the SDK persistence helper for
+history-style products. It standardizes the pending-first pattern from `02-database/05-ai-persistence-patterns.md`
+without adding UI behavior.
 
 ```ts
-// 1. Run the AI action
-const result = await howone.ai.generateStory.run({
-  topic: 'Dragons and magic',
-  ageRange: '6-8',
-})
+import { runAiActionAndPersist } from '@howone/sdk'
 
-if (!result.success) throw new Error(result.errors.join(', '))
+const result = await runAiActionAndPersist({
+  entity: howone.entities.Generation,
+  input: {
+    prompt: 'Dragons and magic',
+    ageRange: '6-8',
+  },
+  createPending: (input) => ({
+    prompt: input.prompt,
+    ageRange: input.ageRange,
+    status: 'pending',
+    requestedAt: new Date().toISOString(),
+  }),
+  run: (input) => howone.ai.generateStory.run(input),
+  mapCompleted: ({ output }) => ({
+    status: 'completed',
+    title: output.title,
+    content: output.content,
+    completedAt: new Date().toISOString(),
+  }),
+  mapFailed: ({ error }) => ({
+    status: 'failed',
+    errorMessage: error instanceof Error ? error.message : 'Generation failed',
+  }),
+  onStateChange: (state) => {
+    // app-owned UI callback; SDK does not show toasts
+    setGenerationState(state.status)
+  },
+})
+```
 
-const output = result.finalResult as GenerateStoryOutput
+Return shape:
 
-// 2. Save to entity
-const saved = await howone.entities.Story.create({
-  title: output.title,
-  content: output.content,
-  authorId: currentUser.id,
-  status: 'draft',
-  wordCount: output.content.split(' ').length,
-  // Track generation metadata
-  promptTopic: 'Dragons and magic',
-  generatedAt: new Date().toISOString(),
-})
+```ts
+type AiPersistenceResult<TRecord, TOutput> =
+  | { status: 'completed'; record: TRecord; output: TOutput }
+  | { status: 'failed'; record: TRecord; error: unknown }
 ```
 
+Rules:
+
+- `createPending` must only return fields declared in the entity schema.
+- `mapCompleted` maps durable product fields from AI output to entity update payload.
+- `mapFailed` should persist a failure state if the product shows history or retry.
+- Use `onStateChange` to update app-owned UI; do not add SDK toast behavior.
+- For simple one-shot AI actions that do not need history, call `howone.ai.*.run()` directly.
+
 ---
 
 ## React Patterns
@@ -448,9 +495,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 +568,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/03-sdk/08-extension-boundaries.md

@@ -0,0 +1,226 @@
+# SDK Extension Boundaries
+
+This reference defines the long-term shape of `@howone/sdk`. Use it whenever changing SDK APIs,
+adding new capabilities, or deciding whether behavior belongs in the SDK or in the generated app.
+
+## North Star
+
+The SDK is an AI-first runtime, not an app UI framework.
+
+It should provide:
+
+- stable defaults that work with almost no configuration;
+- typed clients for HowOne platform capabilities;
+- adapters for custom behavior;
+- callbacks/events for app UI;
+- predictable names that AI agents can reuse without guessing.
+
+It should not provide:
+
+- app-owned pages, modals, toasts, or business UI;
+- hardcoded app flows beyond HowOne platform defaults;
+- hidden persistence side effects;
+- provider-specific branches scattered through feature code.
+
+## Default + Adapter Rule
+
+Every platform capability should follow the same shape:
+
+```ts
+createClient({
+  projectId,
+  env,
+  auth: 'hosted', // default
+})
+```
+
+Advanced usage should opt into typed adapters:
+
+```ts
+createClient({
+  projectId,
+  env,
+  auth: {
+    mode: 'headless',
+    adapter: {
+      getToken: () => externalAuth.getToken(),
+      setToken: (token) => externalAuth.setToken(token),
+      login: ({ returnUrl }) => appRouter.push(`/login?redirect=${encodeURIComponent(returnUrl ?? '/')}`),
+      logout: () => appRouter.push('/'),
+    },
+  },
+})
+```
+
+Do not add one-off flags when an adapter/callback can express the behavior.
+
+## Capability Boundaries
+
+| Capability | SDK owns | App owns |
+|---|---|---|
+| Auth | token source, session state, login/logout destination policy, hosted HowOne defaults | login page visuals, account menu, loading states, auth error UI |
+| React provider | context, auth callbacks, optional bottom-right HowOne `FloatingButton` logo | layout, toasts, overlays, route components, theme system |
+| Entities | typed CRUD/query clients, public/private routing, payload normalization | forms, list rendering, optimistic UI, field-level UX |
+| Schema | definition operations, preview/apply/version/restore calls | migration approval UI, admin experience |
+| Entity contract utilities | payload whitelisting, public query guardrail validation, structured validation issues | deciding product copy, rendering validation errors |
+| AI workflows | run/stream/events, Zod validation, workflowId binding | progress UI, result rendering, failure surfaces |
+| AI persistence | pending-first orchestration helper, state callbacks, completed/failed mapping hook | choosing schema fields, retry UX, visible state UI |
+| Upload | file/image/batch helpers and callbacks | picker UI, previews, validation copy, uploaded-file placement |
+| Raw HTTP | low-level escape hatch | choosing it only when typed SDK surface does not exist |
+
+## React Provider Boundary
+
+`HowOneProvider` may render the HowOne bottom-right logo via `FloatingButton`. This is platform
+branding and should remain visible by default.
+
+It must not render:
+
+- toast notifications;
+- redirect overlays;
+- login/register forms;
+- payment dialogs;
+- app theme wrappers;
+- app-specific navigation.
+
+Use callbacks instead:
+
+```tsx
+<HowOneProvider
+  auth="required"
+  brand="visible"
+  onAuthRedirect={({ mode, returnUrl }) => {
+    setAuthUi({ redirecting: true, mode, returnUrl })
+  }}
+  onAuthStateChange={(state) => {
+    setCurrentUser(state.user)
+  }}
+>
+  <App />
+</HowOneProvider>
+```
+
+Hide the logo only when explicitly requested:
+
+```tsx
+<HowOneProvider brand="hidden" />
+<HowOneProvider showBrandButton={false} />
+```
+
+## UI Feedback Rule
+
+Do not add `ClayxToast`, `toast`, or any visible notification API to `@howone/sdk`.
+
+Generated apps should write their own UI from SDK results:
+
+```ts
+setStatus({ type: 'loading', message: 'Generating...' })
+
+try {
+  const output = await howone.ai.generateImage.run({ prompt })
+  setStatus({ type: 'success', message: 'Done', output })
+} catch (error) {
+  setStatus({
+    type: 'error',
+    message: error instanceof Error ? error.message : 'Generation failed',
+  })
+}
+```
+
+For streaming workflows, use callbacks/events:
+
+```ts
+const session = howone.ai.generateImage.stream(
+  { prompt },
+  {
+    onStreamContent: (delta) => appendLog(delta),
+    onProgress: (progress) => setProgress(progress),
+    onError: (error) => setStatus({ type: 'error', message: error.message }),
+    onComplete: (result) => setResult(result.finalResult),
+  },
+)
+```
+
+## Auth Adapter Contract
+
+Use `AuthAdapter` for custom/headless auth. It is the only supported extension point for token
+ownership outside the SDK defaults.
+
+```ts
+type AuthAdapter = {
+  name?: string
+  getToken?: () => string | null | Promise<string | null>
+  setToken?: (token: string | null) => void | Promise<void>
+  getUser?: (token: string | null) => AuthUser | null | Promise<AuthUser | null>
+  login?: (options?: { returnUrl?: string }) => void | Promise<void>
+  logout?: (options?: { redirect?: false | string | { url: string; external?: boolean } }) => void | Promise<void>
+  clearSession?: (options?: { redirect?: false | string | { url: string; external?: boolean } }) => void | Promise<void>
+  subscribe?: (listener: (state: AuthState) => void) => (() => void) | void
+}
+```
+
+Rules:
+
+- Default hosted auth must work without an adapter.
+- External providers must use `mode: 'headless'` plus `adapter`.
+- Custom in-app HowOne login should usually use `mode: 'custom'`, `loginPath`, and SDK OTP/OAuth helpers.
+- `client.me()` and `client.requireMe()` are the canonical user APIs.
+- `client.auth.isAuthenticated()` is a quick token check, not a first-load user fetch.
+
+## AI Agent Design Rules
+
+Generated app code should have one stable SDK singleton:
+
+```ts
+import howone from '@/lib/sdk'
+```
+
+Agents should prefer:
+
+1. `howone.entities.*` for private/authenticated data;
+2. `howone.public.entities.*` for public access;
+3. `pickEntityPayload()` / `assertEntityPayload()` when mapping broad UI or AI objects to entity writes;
+4. `assertPublicEntityQuery()` when generated code has access to the synced definition;
+5. `howone.ai.*` for workflow execution;
+6. `runAiActionAndPersist()` when the product needs durable AI history;
+7. `howone.upload.*` for files;
+8. `howone.schema.*` for schema tools;
+9. `howone.raw` only as escape hatch.
+
+Agents must not:
+
+- hardcode HowOne URLs;
+- manually build workflow SSE URLs;
+- call workflows by display name instead of UUID;
+- persist UI-only or workflow-extra fields;
+- add frontend UI APIs to the SDK;
+- remove the default HowOne floating logo unless explicitly asked.
+
+## Adding New SDK Capabilities
+
+When adding a new capability, choose one of these shapes:
+
+```ts
+client.capability.method(input, options)
+client.capability.stream(input, callbacks)
+client.capability.configure(adapter)
+```
+
+Prefer these names:
+
+- `run` for one-shot AI/workflow execution;
+- `stream` for session-based execution with callbacks;
+- `events` for async iterables;
+- `query/list/get/create/update/delete` for entities;
+- `configure` only for adapters, not app UI.
+
+Keep returned values serializable and obvious. AI agents should be able to inspect the method name
+and infer the contract.
+
+## Compatibility Rule
+
+Do not break existing generated apps lightly. Prefer:
+
+- add new adapter/callback options;
+- keep old string shorthand (`auth: 'custom'`) working;
+- mark old UI props as deprecated/no-op only when needed;
+- update this skill and the relevant numbered reference in the same change.

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

@@ -0,0 +1,205 @@
+# AI Capability Architecture
+
+Use this reference when a HowOne app needs AI generation, editing, analysis, research, media
+creation, file generation, or any workflow-backed behavior.
+
+This file answers: **what AI layer should be designed, in what order, and where each responsibility
+belongs?** For schema details read `02-workflow-contract-rules.md`. For workflow service calls read
+`05-workflow-operations.md`.
+
+## Platform Mental Model
+
+HowOne AI has five distinct layers:
+
+| Layer | Owns | Does not own |
+|---|---|---|
+| Product feature | User-facing goal, UX states, persistence decision | workflow internals |
+| AI capability contract | `name`, `description`, `inputSchema`, `outputSchema`, `outputEntityName`, versions, manifest | database CRUD, UI, auth |
+| External workflow implementation | generated/edited workflow graph behind a `workflowId` | app schema, frontend state |
+| Status/background layer | `request_id` polling, completed/failed state, `workflowConfigID` capture | SDK binding source |
+| SDK binding/app code | `defineAiAction`, Zod schemas, `howone.ai.*`, persistence through entities | workflow generation |
+
+Do not collapse these layers. The common mistakes are:
+
+- putting database writes into the workflow;
+- generating `src/lib/sdk.ts` before `.howone/ai/manifest.json` is synced;
+- using action names instead of workflow UUIDs;
+- treating workflow `outputSchema` as a database schema;
+- faking unsupported AI with static frontend data.
+
+## Source Of Truth
+
+```text
+user request                         = intent
+agent AI contract proposal           = draft
+applied AI capability version        = validated contract
+.howone/ai/manifest.json             = local synced source for SDK codegen
+workflow service completed status    = source for workflowConfigID
+src/lib/sdk.ts                       = generated app binding
+frontend UI                          = SDK consumer
+entity schema                        = persistence contract, separate from AI contract
+```
+
+Never generate SDK bindings from the user prompt or from an unsynced draft.
+
+## Standard AI Feature Flow
+
+Use this flow for new AI features:
+
+1. Classify the feature using `04-ai/04-service-capability-catalog.md`.
+2. Decide whether the feature is supported. If not supported, stop and explain the missing capability.
+3. Decide one workflow per user-facing feature. Use two workflows only for RAG.
+4. Design `inputSchema` and `outputSchema` using `02-workflow-contract-rules.md`.
+5. Preview/apply the AI capability patch through the capability tool.
+6. Sync `.howone/ai/manifest.json`.
+7. Submit workflow create through `external-ai-capability` / workflow operate from the synced manifest.
+8. Store returned `request_id` values for polling.
+9. Poll status until `completed` or `failed`.
+10. On completed + `payload.success === true`, store `payload.workflow_details.new_workflow_config_id`.
+11. Generate/update `src/lib/sdk.ts` using `03-ai-sdk-handoff.md` and `01-architect/02-manifest-codegen.md`.
+12. Implement UI calls through `howone.ai.<action>.run()`, `.stream()`, or `.events()`.
+13. If output must persist, design entity schema and use `runAiActionAndPersist()` when appropriate.
+
+Do not submit external workflow create/update from a hand-written schema. It should come from the
+synced manifest.
+
+## New Feature vs Existing Feature
+
+| Situation | Correct path |
+|---|---|
+| New AI feature, no manifest entry | create AI capability, sync manifest, submit workflow create |
+| Manifest entry exists but no workflow created yet | submit workflow create from manifest |
+| User asks to change input/output contract | update capability contract first, sync, then submit workflow update |
+| User asks to improve behavior only | submit workflow update with `workflowConfigID` and `updatePrompt` |
+| User asks to save outputs/history | design/update database entity after AI output contract is known |
+| User asks for public share of AI result | private history entity + public scoped share entity |
+
+## Create vs Update
+
+Create external workflow when:
+
+- capability has a `workflowId`;
+- no confirmed external implementation exists;
+- no `workflowConfigID` has been captured.
+
+Update external workflow when:
+
+- an external implementation exists;
+- the status layer previously returned `payload.workflow_details.new_workflow_config_id`;
+- you have a concrete `updatePrompt`.
+
+`workflowConfigID` is not the same as `workflowId`.
+
+```text
+workflowId        = stable workflow UUID from manifest, used by SDK execution
+workflowConfigID  = implementation config ID from completed workflow generation/edit status
+request_id        = async operation ID returned by workflow operate endpoint
+```
+
+Do not invent any of these IDs.
+
+## Workflow Count Rule
+
+Default: one user-facing AI feature equals one workflow.
+
+Examples:
+
+| Feature | Workflow count | Why |
+|---|---:|---|
+| Generate illustrated story | 1 | story text + images are one product action |
+| Edit uploaded photo | 1 | one input image + edit prompt -> edited image |
+| Research news briefing | 1 | search + synthesis are one action |
+| Generate video from prompt | 1 | media generation is one action |
+| Chat with uploaded documents | 2 | RAG needs indexing + query workflows |
+
+Do not split normal multi-step behavior into separate workflows. The workflow service handles
+internal orchestration.
+
+## Persistence Boundary
+
+AI workflows produce outputs. They do not own product records.
+
+Workflow may do:
+
+- generate, summarize, translate, classify, extract;
+- search/crawl and synthesize;
+- generate/edit/analyze images, video, and audio;
+- retrieve financial or academic data;
+- save/read generated files through URL-based storage.
+
+Workflow must not do:
+
+- database create/read/update/delete;
+- authentication/session logic;
+- file upload from browser raw bytes;
+- payment processing;
+- owner assignment or permissions;
+- app navigation, UI state, toast, or modal logic.
+
+If the product needs durable history, use entity persistence outside the workflow:
+
+```ts
+await runAiActionAndPersist({
+  entity: howone.entities.Generation,
+  input,
+  createPending: (input) => ({ prompt: input.prompt, status: 'pending' }),
+  run: (input) => howone.ai.generateImage.run(input),
+  mapCompleted: ({ output }) => ({ status: 'completed', resultUrl: output.generated_image_url }),
+})
+```
+
+## Unsupported AI Behavior
+
+If a user explicitly requires behavior not available in the workflow service, stop that AI path.
+
+Do not:
+
+- fake AI with static templates;
+- hide the unsupported part;
+- build a UI that pretends the workflow exists;
+- replace the requested capability with a different one without saying so;
+- assume private APIs, external datasets, or providers that are not listed.
+
+Correct response:
+
+```text
+This exact AI behavior needs <missing capability>. The current workflow service supports <closest
+available capability>. I can build <narrow supported version>, or we need platform support for
+<missing capability> first.
+```
+
+## Capability Naming
+
+Use stable JavaScript-safe IDs:
+
+```text
+generateIllustration
+summarizeDocument
+researchNewsBriefing
+editProductPhoto
+transcribeAudio
+```
+
+Avoid:
+
+- display labels with spaces;
+- names that collide with base methods: `run`, `stream`, `events`;
+- provider names: `openAiImage`, `geminiAnalyze`;
+- implementation names: `searchThenSummarize`.
+
+The description can be human readable. The ID must be stable for codegen.
+
+## AI Architecture Checklist
+
+Before editing files:
+
+- Feature maps to available workflow capabilities.
+- One workflow per feature unless RAG.
+- Description says what the user gets, not how tools run.
+- Input schema accepts URLs for files, not raw bytes.
+- Output schema contains only requested result fields.
+- Input and output property names do not overlap.
+- Text output descriptions specify language behavior.
+- Persistence is modeled as entity schema, not workflow CRUD.
+- `workflowId`, `request_id`, and `workflowConfigID` are not guessed.
+- SDK binding will be generated only after manifest sync.