howone 0.2.1 → 0.2.3

package/package.json

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

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

@@ -104,7 +104,7 @@ Use `SKILL.md` for the full file index. Typical minimums:
 | App entity query code | add `04-app-sdk/11-entity-data-access-patterns.md`, `04-app-sdk/12-query-dsl-and-responses.md` after manifest sync |
 | AI design | `03-ai-capabilities/01-ai-capability-architecture.md`, `03-ai-capabilities/03-service-capability-catalog.md`, `03-ai-capabilities/02-workflow-contract-rules.md` |
 | AI + saved outputs | add `02-entity-schema/05-ai-persistence-patterns.md` after AI contract is known |
-| Bindings after sync | `02-manifest-codegen.md` + relevant `04-app-sdk/` files |
+| Bindings after sync | `02-manifest-codegen.md` + `04-app-sdk/01-client-setup.md` + `04-app-sdk/03-auth.md` + `04-app-sdk/04-react-integration.md` + the operation-specific SDK file |
 
 ## Data posture
 
@@ -126,14 +126,38 @@ Defaults: "my/private" → own; public catalog only when fields are safe; share
 
 | Need | Client | Provider |
 |---|---|---|
-| Hosted HowOne login | default `createClient` | hosted |
-| Custom login UI | `auth: 'custom'`, provider `auth="none"` | app UI |
-| External IdP | headless + adapter | adapter owns token |
-| No auth | `auth: 'none'` | — |
+| HowOne AI, uploads, or authenticated/private entities | default `createClient` | `HowOneProvider auth="required"`; hosted login |
+| Custom HowOne login UI | `auth: 'custom'`, real OTP/OAuth token flow | `HowOneProvider auth="none"`; app guards routes |
+| External IdP | headless + adapter | `HowOneProvider auth="required"`; adapter owns token |
+| Manifest-approved public entities only | default client or `auth: 'none'` | `HowOneProvider auth="optional"` |
+| No HowOne runtime | no client required | no Provider required |
 
 Keep default HowOne brand control unless user asks to hide. Resolve identity through the SDK track
 when app code depends on the current user.
 
+### Runtime activation invariant
+
+Contract design and app runtime activation are one delivery chain, not independent completion states.
+When the final app uses any `@howone/sdk` runtime surface—including a synced entity or AI binding,
+public entities, uploads, auth, user/session APIs, or raw SDK requests:
+
+1. Initialize the single app client in `src/lib/sdk.ts` with the generated project/env configuration.
+2. Import that SDK module before `HowOneProvider` so the Provider sees the selected auth environment.
+3. Keep `HowOneProvider` around the rendered application root. This is required for every active
+   HowOne SDK runtime, including public-only entity applications; replacing scaffold UI must not
+   remove it.
+4. Select the Provider guard from the table above. Do not use `auth="none"` to silence a missing login
+   flow for AI, uploads, or authenticated entities.
+5. For hosted auth, unauthenticated protected use must redirect through HowOne login. For custom auth,
+   the app must acquire an actual HowOne token and call `howone.auth.setToken()` before protected SDK
+   requests.
+6. Validate the logged-out path and the authenticated SDK call path. A styled login screen, compiled
+   SDK binding, or synced manifest alone does not prove runtime integration.
+
+Pure UI/static work may omit this runtime chain only when the application makes no HowOne runtime
+calls. Public-only entity experiences may stay anonymous only when the synced manifest explicitly
+permits the public operation and app code uses `howone.public.entities.*`.
+
 ## Entity workflow (when `02-entity-schema/` in scope)
 
 1. Read schema design + operations references.
@@ -177,4 +201,8 @@ capability patch.
 - [ ] AI requirements verified against catalog when AI in scope
 - [ ] Manifests synced before SDK codegen
 - [ ] `src/lib/sdk.ts` is the HowOne entrypoint
+- [ ] App code uses generated SDK bindings instead of direct internal platform HTTP requests
+- [ ] Active HowOne runtime keeps `HowOneProvider` at the app root and initializes the SDK first
+- [ ] AI, uploads, and authenticated entities have a real hosted/custom/headless token path
+- [ ] Public-only anonymous access is backed by manifest public rules and the public SDK namespace
 - [ ] UI owns visible feedback; no invented platform APIs

package/templates/vite/.howone/skills/howone/03-ai-capabilities/03-service-capability-catalog.md

@@ -15,13 +15,13 @@ Source: `docs/ai-capability.md`.
 | User asks for | Use capability family | Typical inputs | Typical outputs |
 |---|---|---|---|
 | Latest info, research, source-backed answer | Web search / crawling | `topic`, `prompt`, `url`, `search_level` | `answer`, `sources`, `page_content` |
-| Generate artwork/photo/logo/mockup | Image generation | `image_description`, `style_preference`, optional references | `generated_image_url` |
-| Edit an image | Image editing | `source_image_url`, `edit_instruction` | `edited_image_url` |
-| OCR or visual analysis | Image analysis / OCR | `image_urls`, `analysis_prompt` | `analysis_result` or `extracted_text` |
-| Generate short video | Video generation | `video_prompt`, aspect/duration/frame URLs | `video_url` |
+| Generate artwork/photo/logo/mockup | Image generation | `prompt`, optional `reference_img_urls`, size/format | `generated_image_url` or `image_urls` |
+| Edit an image | Image editing | `prompt`, `image_urls`, optional size/format | `edited_image_url` or `image_urls` |
+| OCR or visual analysis | Image analysis / OCR | `prompt`, optional `image_urls` | `analysis_result` or `extracted_text` |
+| Generate short video | Video generation | `prompt`, aspect/duration/frame URLs | `video_url` |
 | Join clips / extract frames | Video editing | `video_urls` or `video_url` | `video_url` or `image_url` |
-| Text to speech | Audio generation | `text_to_generate`, `language`, `voice_hint` | `audio_url` |
-| Speech to text | Audio recognition | `source_audio_url`, `language` | `transcript_text`, optional `utterances` |
+| Text to speech | Audio generation | `text_to_generate`, `languages`, `gender`, `audio_hint` | `audio_url` |
+| Speech to text | Audio recognition | `audio_url`, `language`, optional diarization | `transcript_text`, optional `utterances` |
 | Merge audio | Audio merging | `audio_urls` | `merged_audio_url` |
 | Stock/index history | Financial data retrieval | `trading_symbol`, `unit`, `start`, `end` | `price_history` |
 | Literature search/citations | Academic research | `query` | `papers`, `bibtex` |
@@ -29,6 +29,25 @@ Source: `docs/ai-capability.md`.
 
 If the requested behavior is not in this table or the detailed sections below, do not invent it.
 
+## Detailed Parameter References
+
+The sections below establish family-level feasibility. Before designing one of these workflow
+contracts, read its detailed service reference for exact parameter names, allowed values, defaults,
+conditional requirements, outputs, and hard limits:
+
+| Capability family | Read |
+|---|---|
+| Audio generation | `../references/audio-generation.md` |
+| Audio recognition | `../references/audio-recognition.md` |
+| Financial data retrieval | `../references/finance.md` |
+| Image editing | `../references/image-editing.md` |
+| Image generation | `../references/image-generation.md` |
+| Video generation | `../references/video-generation.md` |
+
+These are workflow-service parameters, not direct `@howone/sdk` method signatures. Translate only
+the product-relevant subset into a loose capability schema, then use the synced AI manifest for app
+bindings.
+
 ## Web Search And Crawling
 
 Use for latest information, news, market context, source-backed answers, web page extraction.
@@ -59,10 +78,9 @@ Use for new images from prompts or prompt + reference URLs.
 
 Inputs:
 
-- `image_description`: detailed prompt;
-- `style_preference`: optional;
-- `reference_image_urls`: optional URL array;
-- size/format options only when product exposes them.
+- `prompt`: detailed prompt;
+- `reference_img_urls`: optional URL array;
+- optional `image_names`, `size`, and `output_format` when the product exposes them.
 
 Outputs:
 
@@ -82,8 +100,8 @@ Use for modifying existing images.
 
 Inputs:
 
-- `source_image_url` or `source_image_urls`;
-- `edit_instruction`;
+- `image_urls`: one or more source image URLs;
+- `prompt`: edit instruction;
 - optional output size/format.
 
 Outputs:
@@ -106,7 +124,7 @@ Use for visual understanding, image comparison, text extraction, quality review.
 Inputs:
 
 - `image_urls`;
-- `analysis_prompt` or `ocr_instruction`.
+- `prompt`: analysis question or OCR instruction.
 
 Outputs:
 
@@ -125,8 +143,8 @@ Use for short video clips from text or image frames.
 
 Inputs:
 
-- `video_prompt`;
-- optional `first_frame_url`, `last_frame_url`, `reference_image_urls`;
+- `prompt`;
+- optional `first_frame_url`, `last_frame_url`, `reference_images`;
 - optional `aspect_ratio`, `duration`, `negative_prompt`, `generate_audio`.
 
 Outputs:
@@ -165,10 +183,10 @@ Use for text-to-speech.
 Inputs:
 
 - `text_to_generate`;
-- `language` or `languages`;
+- `languages`;
 - `gender`;
 - `audio_hint`;
-- optional output format/name.
+- optional `audio_output` with output format/name.
 
 Outputs:
 
@@ -186,9 +204,9 @@ Use for speech-to-text.
 
 Inputs:
 
-- `source_audio_url`;
+- `audio_url`;
 - optional `language`;
-- optional speaker diarization setting.
+- optional `with_speaker_info` for speaker diarization.
 
 Outputs:
 

package/templates/vite/.howone/skills/howone/03-ai-capabilities/04-workflow-operations.md

@@ -66,7 +66,7 @@ Tool behavior:
 
 ```text
 previous config = current manifest capability.workflowId
-new config      = freshly generated UUID sent as config_id
+new config      = freshly generated UUID sent as new_config_id
 mode            = update
 original_config_id = previous config sent to EAX
 workflow code   = regenerated by EAX from the current capability contract and updatePrompt

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

@@ -1,6 +1,6 @@
 ---
 name: howone
-description: 'Use when deciding whether HowOne can satisfy a user request, or when the task touches HowOne platform contracts or app runtime: backend dynamic entity schemas, public/private access, database-backed persisted data, AI capabilities/workflows, external-ai workflow create/update/status, .howone manifests, src/lib/sdk.ts, auth/uploads, or app code that calls @howone/sdk/howone.*. Do not use for UI-only edits with no HowOne data, AI, auth, upload, manifest, or SDK surface.'
+description: 'Use when deciding whether HowOne can satisfy a user request, or when the task touches HowOne platform contracts or app runtime: backend dynamic entity schemas, public/private access, database-backed persisted data, AI capabilities/workflows (including image, video, audio, speech recognition, and financial data), external-ai workflow create/update/status, .howone manifests, src/lib/sdk.ts, auth/uploads, or app code that calls @howone/sdk/howone.*. Do not use for UI-only edits with no HowOne data, AI, auth, upload, manifest, or SDK surface.'
 ---
 
 # HowOne
@@ -56,11 +56,38 @@ Then read the minimum track files:
 | Backend contract | `02-entity-schema/01-schema-design.md`, `02-entity-schema/02-schema-operations.md` |
 | AI contract | `03-ai-capabilities/01-ai-capability-architecture.md`, `03-ai-capabilities/02-workflow-contract-rules.md`, `03-ai-capabilities/03-service-capability-catalog.md` |
 | External AI workflow submit/update | `03-ai-capabilities/04-workflow-operations.md` |
-| SDK binding/code | `01-architect/02-manifest-codegen.md` plus the relevant `04-app-sdk/` file |
+| Image, video, audio, speech, or finance workflow | The matching file under `references/` from the detailed capability table below |
+| SDK binding/code | `01-architect/02-manifest-codegen.md`, `04-app-sdk/01-client-setup.md`, `04-app-sdk/03-auth.md`, `04-app-sdk/04-react-integration.md`, plus the operation-specific SDK file |
 | AI output persistence | Backend required reads plus `02-entity-schema/05-ai-persistence-patterns.md` after AI output schema is known |
 
 Do not load all references preemptively.
 
+### Detailed Capability Routing
+
+After `03-ai-capabilities/03-service-capability-catalog.md` confirms the workflow family, read
+exactly the matching detailed reference before designing or changing its contract:
+
+| User-visible AI behavior | Detailed service reference |
+|---|---|
+| Generate speech, narration, voiceover, or multilingual TTS | `references/audio-generation.md` |
+| Transcribe recordings, produce meeting text, or identify speakers | `references/audio-recognition.md` |
+| Retrieve historical stock or index prices | `references/finance.md` |
+| Edit, transform, remove, replace, or combine image content | `references/image-editing.md` |
+| Generate an image from text or reference images | `references/image-generation.md` |
+| Generate a short video from text, frames, or reference images | `references/video-generation.md` |
+
+The detailed references describe workflow-service operation parameters and limits. Use them to
+avoid unsupported values and impossible combinations. They are not app SDK signatures:
+
+1. Expose only the inputs the product actually needs in the capability contract.
+2. Preserve closed enums, URL requirements, conditional requirements, and hard limits.
+3. Use product-oriented field names only when their descriptions map unambiguously to the service
+   parameter; never invent a service parameter.
+4. Return only the minimal product result from the workflow. Do not copy service metadata into the
+   output schema unless the UI or persistence contract uses it.
+5. After apply/sync/finalization, treat `.howone/ai/manifest.json` as the only source for SDK names,
+   schemas, and workflow IDs.
+
 ## Tool Flow
 
 Backend contract:
@@ -83,9 +110,35 @@ approved patch.
 SDK/code:
 
 ```text
-read synced manifests -> update src/lib/sdk.ts -> implement UI/server code using src/lib/sdk.ts imports
+read synced manifests -> choose auth posture -> update src/lib/sdk.ts -> install HowOneProvider
+-> implement UI calls using src/lib/sdk.ts imports -> validate auth and runtime wiring
 ```
 
+## App Runtime Activation Gate
+
+Classify runtime activation before editing the application shell:
+
+- Pure UI/static code with no HowOne data, AI, upload, auth, manifest, or SDK call does not require
+  `HowOneProvider` and must not add login merely because the template supports it.
+- Any app code that uses any `@howone/sdk` runtime surface—including entities, public entities, AI
+  actions, uploads, auth, user/session APIs, or raw SDK requests—activates the HowOne runtime. Keep
+  one module-level client in `src/lib/sdk.ts`, import it before Provider initialization, and wrap the
+  application root in `HowOneProvider`.
+- HowOne AI, uploads, and `howone.entities.*` authenticated/private access require a real token path.
+  Default to hosted auth with `HowOneProvider auth="required"` unless the product explicitly requires
+  a custom or external login experience.
+- A custom HowOne login requires `createClient({ auth: 'custom', loginPath })`, a real OTP/OAuth flow
+  that writes the returned token through `howone.auth.setToken()`, and `HowOneProvider auth="none"`
+  with app-owned route guards. A login-looking screen without token acquisition is not completion.
+- An app that uses only manifest-approved `howone.public.entities.*` access may use
+  `HowOneProvider auth="optional"`; do not force login for a deliberately public experience.
+
+Do not delete the scaffold Provider while replacing `App.tsx` or `main.tsx` when the HowOne runtime
+is active. Before completion, verify the Provider still wraps the rendered app, the SDK module is
+initialized first, unauthenticated protected use reaches the selected login flow, and authenticated
+AI/entity/upload requests obtain the SDK-managed token. Never replace a missing token path with mock
+data, local-only persistence, or unauthenticated fallback behavior.
+
 ## Source Of Truth
 
 - Backend fields/access/indexes: `{appRoot}/.howone/database/manifest.json` after sync.
@@ -123,6 +176,9 @@ read synced manifests -> update src/lib/sdk.ts -> implement UI/server code using
 | `03-ai-capabilities/04-workflow-operations.md` | External workflow create/update/status |
 | `03-ai-capabilities/05-ai-feature-playbooks.md` | Reusable AI product patterns |
 
+Detailed workflow-service parameters live under `references/` and are routed by the table above.
+Do not read unrelated capability references.
+
 ### SDK
 
 | File | Use |
@@ -144,6 +200,16 @@ read synced manifests -> update src/lib/sdk.ts -> implement UI/server code using
 
 - Backend and AI design references must not include SDK implementation work.
 - SDK references must not invent backend or AI contracts; they consume synced manifests.
+- App code must consume HowOne backend and AI capabilities through the generated bindings exported
+  by `src/lib/sdk.ts`. Do not replace SDK entity/action calls with direct requests to internal
+  platform endpoints.
+- An active HowOne app runtime must include `src/lib/sdk.ts`, `HowOneProvider`, and the auth posture
+  required by its AI/entity/upload access. Contract creation without usable authenticated app wiring
+  is incomplete.
 - AI workflows must not perform database CRUD; persistence is app code through entities.
+- Detailed capability references constrain workflow design; they do not replace synced manifests or
+  define direct app SDK calls.
+- Never copy all service parameters or technical response metadata into a capability contract by
+  default. Model only the product inputs and outputs while preserving service limits.
 - Explicit user-owned integrations are app code, not a platform gap.
 - Platform gap means missing HowOne contract/tool/catalog support, not an unsupported technology name.

package/templates/vite/.howone/skills/howone/references/audio-generation.md

@@ -0,0 +1,30 @@
+# Audio Generation
+
+Generates single-speaker audio (text-to-speech) from text, with configurable language, gender, and a natural-language voice hint. Supports multilingual audio by mixing Chinese and English in the same text. For multi-speaker dialogue, call this tool once per speaker and merge the results separately.
+
+Use this file for workflow-service feasibility and parameter constraints. Do not expose every
+parameter or raw response field in the app capability contract. Select the product-relevant subset,
+then normalize the workflow output to the minimal URL/data fields the app consumes.
+
+## Parameters
+
+| Parameter | Type | Required | Allowed Values / Constraints | Default |
+|---|---|---|---|---|
+| text_to_generate | string | Yes | — | — |
+| languages | array[string] | No | items: `en-US`, `zh-CN`, `en-GB`, `en-AU`, `ja-JP`, `es-ES`; multilingual mixing only supported for zh/en | `['en-US']` |
+| gender | string | No | `male`, `female` | `female` |
+| audio_hint | string | No | must be written in English regardless of input/target language | — |
+| audio_output | object | No | object with `audio_name` (string, ASCII only) and `audio_format` (`mp3`, `wav`) | audio_name auto-generated; audio_format `mp3` |
+
+## Service Output
+
+The operation returns `success`, `audio_url`, `audio_metadata`, `voice_name`, and `emotion` when
+available. A normal app capability should usually return only `audio_url` unless the product renders
+or persists another field.
+
+## Constraints
+
+- Use one speaker per call. Generate each speaker separately and use audio merging for dialogue.
+- Only Chinese and English can be mixed in one multilingual request.
+- Write `audio_hint` in English. Describe role, gender, language style, emotion, and scenario.
+- Use URL outputs; do not request inline audio bytes or base64.

package/templates/vite/.howone/skills/howone/references/audio-recognition.md

@@ -0,0 +1,30 @@
+# Audio Recognition
+
+Transcribes an audio file to text (speech-to-text), optionally with inverse text normalization and speaker diarization. Use for transcription, meeting minutes, or extracting text content from voice recordings.
+
+Use this file for workflow-service feasibility and parameter constraints. The app capability may use
+a clearer product field such as `source_audio_url`, but its description must map to the service
+`audio_url` input. Never pass browser `File`, raw bytes, or base64 into the workflow.
+
+## Parameters
+
+| Parameter | Type | Required | Allowed Values / Constraints | Default |
+|---|---|---|---|---|
+| audio_url | string | Yes | — | — |
+| audio_format | string | No | e.g. `wav`, `mp3` | `mp3` |
+| language | string | No | `en-US`, `zh-CN`, `en-GB`, `en-AU`, `ja-JP`, `es-ES` | `en-US` |
+| use_itn | boolean | No | `true`, `false` | `true` |
+| with_speaker_info | boolean | No | `true`, `false` | `false` |
+
+## Service Output
+
+The operation returns `success`, `text`, and optional `utterances` with timestamps and speaker
+identification. A capability contract should rename `text` to an unambiguous product result such as
+`transcript_text`; include `utterances` only when the UI uses diarization.
+
+## Constraints
+
+- `audio_url` must be reachable by the workflow service.
+- Maximum processing wait time is 300 seconds.
+- A single audio packet is limited to 2 MB; do not promise support for arbitrary large inputs.
+- Silent audio may return empty text. Speaker quality depends on recording clarity.

package/templates/vite/.howone/skills/howone/references/finance.md

@@ -0,0 +1,28 @@
+# Finance
+
+Retrieves historical price and volume (open, high, low, close, volume) for stocks and market indices within a UTC time range. Supports US stocks, international stocks, and market indices. Does not provide company fundamentals, news, or real-time streaming data.
+
+Use this file for historical market-data workflow feasibility and exact parameter constraints. Do
+not reclassify live quotes, fundamentals, earnings, or news as this capability.
+
+## Parameters
+
+| Parameter | Type | Required | Allowed Values / Constraints | Default |
+|---|---|---|---|---|
+| trading_symbol | string | Yes | trading symbol (e.g. `AAPL`, `SHEL.L`, `^GSPC`) or company/index name (e.g. `Apple`, `S&P 500`) | — |
+| unit | string | Yes | `daily`, `minute`; market indices only support `daily` | — |
+| start | string | Yes | UTC; `YYYY-MM-DD` for `daily` unit, `YYYY-MM-DDTHH:MM:SSZ` for `minute` unit | — |
+| end | string | Yes | UTC, inclusive; `YYYY-MM-DD` for `daily` unit, `YYYY-MM-DDTHH:MM:SSZ` for `minute` unit; must be ≥ `start` | — |
+
+## Service Output
+
+The operation returns `data` containing date/datetime, open, high, low, close, and volume records,
+plus the resolved `trading_symbol` and an optional `warning`. Name the app-facing result according
+to the product, for example `price_history`, while retaining the resolved symbol when it matters.
+
+## Constraints
+
+- This is historical retrieval, not real-time streaming.
+- Market indices such as `^GSPC` and `^DJI` support `daily` only.
+- Prefer exact exchange-qualified tickers; company-name resolution is fuzzy.
+- Availability depends on trading hours and provider coverage.

package/templates/vite/.howone/skills/howone/references/image-editing.md

@@ -0,0 +1,30 @@
+# Image Editing
+
+Edits, transforms, or combines one or more existing images based on a natural language prompt. Supports basic operations (resize, rotate, crop, color adjustment, grayscale, blur, sharpen) and AI-powered operations (background removal/replacement, face swap, object removal/addition, style transfer, enhancement, image merging), which can be chained together.
+
+Use this file for workflow-service feasibility and parameter constraints. `prompt` and `image_urls`
+are service operation parameters; the app capability may expose product-oriented names such as
+`edit_instruction` and `source_image_urls` when their descriptions preserve the mapping.
+
+## Parameters
+
+| Parameter | Type | Required | Allowed Values / Constraints | Default |
+|---|---|---|---|---|
+| prompt | string | Yes | — | — |
+| image_urls | array[string] | Yes | HTTP(S) or Supabase URLs; use array format even for a single image | — |
+| image_names | array[string] | No | ASCII only; use array format even for a single image | auto-generated |
+| size | string | No | `WxH` format (e.g. `512x512`, `1024x768`); applies to all edited images | original dimensions preserved |
+| output_format | string | No | `png`, `jpeg`, `webp` | original format preserved |
+
+## Service Output
+
+The operation returns `success`, `images` (each with `image_url` and `image_metadata`), and optional
+`warnings`. A single-result app flow should normally return one `edited_image_url`; return an array
+only when the product supports multiple edited outputs.
+
+## Constraints
+
+- Require at least one reachable HTTP(S) image URL, even for operations described as text edits.
+- Refer to inputs by position or visible content in `prompt`, not by repeating their URLs.
+- Put output dimensions in `size`, not in `prompt`.
+- Prefer focused edits. Chained complex edits can reduce quality.

package/templates/vite/.howone/skills/howone/references/image-generation.md

@@ -0,0 +1,30 @@
+# Image Generation
+
+Generates images from a natural language prompt, optionally guided by reference images for text-and-image(s)-to-image generation. Produces illustrations, photographs, artwork, diagrams, logos, mockups, and other visual content.
+
+Use this file for workflow-service feasibility and parameter constraints. `prompt`,
+`reference_img_urls`, and the output controls are service operation parameters. Expose only the
+subset that the product lets users control.
+
+## Parameters
+
+| Parameter | Type | Required | Allowed Values / Constraints | Default |
+|---|---|---|---|---|
+| prompt | string | Yes | — | — |
+| image_names | array[string] | No | ASCII only; use array format even for a single image | — |
+| size | string | No | `WxH` format (e.g. `1024x768`); applies to all generated images | — |
+| output_format | string | No | `png`, `jpeg`, `webp` | — |
+| reference_img_urls | array[string] | No | list of image URLs to provide as reference | — |
+
+## Service Output
+
+The operation returns `success`, `images` (each with `image_url` and `image_metadata`), and optional
+`warnings`. Most app capabilities should normalize this to one `generated_image_url`; use an array
+only when multiple generated images are an explicit product feature.
+
+## Constraints
+
+- Put scene, style, composition, and content in `prompt`; put dimensions in `size`.
+- Refer to reference images by position or content, not by URL text inside the prompt.
+- Prefer one image per request. Two or three are possible but less consistent.
+- Reference images guide style/content and do not guarantee pixel-perfect reproduction.

package/templates/vite/.howone/skills/howone/references/video-generation.md

@@ -0,0 +1,35 @@
+# Video Generation
+
+Generates a video from a text prompt, with optional image-to-video (first/last frame), reference images for style guidance, and optional synchronized audio.
+
+Use this file for workflow-service feasibility and parameter constraints. Keep the app capability
+contract smaller than the service operation unless the product genuinely exposes every control.
+
+## Parameters
+
+| Parameter | Type | Required | Allowed Values / Constraints | Default |
+|---|---|---|---|---|
+| prompt | string | Yes | — | — |
+| video_name | string | No | ASCII characters only | auto-generated |
+| aspect_ratio | string | No | `16:9`, `9:16`, `4:3`, `3:4`, `1:1`, `21:9` | `16:9` |
+| resolution | string | No | `480p`, `720p`, `1080p` | `720p` |
+| duration | integer | No | 4-10 seconds | 4 |
+| first_frame_url | string | No | image URL, for image-to-video (starting frame) | — |
+| last_frame_url | string | No | requires `first_frame_url` to be set | — |
+| reference_images | array[string] | No | up to 3 image URLs | — |
+| negative_prompt | string | No | — | — |
+| generate_audio | boolean | No | `true`, `false` | `false` |
+
+## Service Output
+
+The operation returns `success`, `video_url`, `video_metadata`, and the selected `model`. A normal
+app capability should return only `video_url` unless technical metadata is visible or persisted.
+
+## Constraints
+
+- `last_frame_url` is valid only when `first_frame_url` is also present.
+- Use at most 3 `reference_images`.
+- Generate 4-10 second clips. Build longer output from multiple clips plus video concatenation.
+- Use `first_frame_url` for stronger character/style consistency across clips.
+- When `generate_audio` is true, describe dialogue, sound effects, ambience, and music in `prompt`;
+  one speaker per clip is the most reliable.