howone 0.2.2 → 0.2.5

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
@@ -13,6 +13,24 @@ HowOne builds generated full-stack AI apps. Platform contracts are separate from
 
 Load only the track needed for the user's request. Do not read SDK files while designing backend or AI contracts unless the task has reached manifest-to-code implementation.
 
+## Version Evidence (Mastra-style)
+
+Before writing app SDK code, establish this evidence chain:
+
+```text
+synced project manifests
+→ app package.json SDK range
+→ installed @howone/sdk version
+→ installed dist/*.d.ts and runtime exports
+→ this Skill's matching recipe
+→ remote docs only as supplemental context
+```
+
+Read `references/version-evidence.md` and run
+`node .howone/skills/howone/scripts/verify-project.mjs` from the app root. If the requested and
+installed SDK versions disagree, install dependencies before coding. Never solve a version mismatch
+with `any`, guessed signatures, or copied latest documentation.
+
 ## Trigger Preconditions
 
 Use this skill before work when any condition is true:
@@ -56,11 +74,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:
@@ -73,7 +118,8 @@ AI contract:
 
 ```text
 get_current_ai_capabilities -> apply_capability_patch -> sync_ai_artifacts -> external-ai-capability
--> wait for terminal result -> sync_ai_artifacts -> read .howone/ai/manifest.json
+-> continue independent app implementation (never end merely to wait)
+-> terminal result -> sync_ai_artifacts -> read .howone/ai/manifest.json
 ```
 
 No contract dry-run step. Normal generation applies one well-formed patch directly. For destructive,
@@ -83,14 +129,45 @@ approved patch.
 SDK/code:
 
 ```text
-read synced manifests -> update src/lib/sdk.ts -> implement UI/server code using src/lib/sdk.ts imports
+read version evidence -> read synced manifests -> choose auth posture -> update src/lib/sdk.ts
+-> install HowOneProvider (client={howone}) -> implement UI calls using generated bindings
+-> run project verifier -> typecheck/build
 ```
 
+For fragile operations, prefer the deterministic verifier and the operation recipes over retyping
+transport details in an app. Run the verifier again after manifest or dependency changes.
+
+## 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.
+  Use the default hosted client and pass the composed singleton to
+  `<HowOneProvider client={howone}>`; its required guard is inherited from `client.auth.guard`.
+- A custom HowOne login requires `createClient({ auth: 'custom', loginPath })`, a real OTP/OAuth flow
+  that writes the returned token through `howone.auth.setToken()`, and a Provider receiving that
+  client. A login-looking screen without token acquisition is not completion.
+- An app that uses only manifest-approved `howone.public.entities.*` access may use
+  `auth: 'none'`; the Provider inherits a non-required guard and must not force login.
+
+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.
 - AI names/workflow IDs/schemas: `{appRoot}/.howone/ai/manifest.json` after sync.
 - App runtime entry: `{appRoot}/src/lib/sdk.ts`.
+- Installed SDK typings/runtime: `{appRoot}/node_modules/@howone/sdk/dist/*` after package install.
 - Do not handwrite `.howone/` metadata.
 - Do not infer contract identifiers from prompts, memory, or dependency source.
 
@@ -123,6 +200,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 |
@@ -140,10 +220,36 @@ read synced manifests -> update src/lib/sdk.ts -> implement UI/server code using
 | `04-app-sdk/11-entity-data-access-patterns.md` | App entity access calls from synced manifest |
 | `04-app-sdk/12-query-dsl-and-responses.md` | App query/filter/sort/pagination calls |
 
+### References and scripts
+
+| Resource | Use |
+|---|---|
+| `references/version-evidence.md` | Verify installed SDK version and declaration/runtime evidence before coding |
+| `references/common-errors.md` | Diagnose stale signatures, routing, auth, query, upload, and AI failures |
+| `scripts/verify-project.mjs` | Deterministically check project wiring and manifest workflow IDs |
+
 ## Hard Rules
 
 - 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.
+- New app code must pass the composed singleton to `<HowOneProvider client={howone}>`; the Provider
+  derives its default route guard from `client.auth.guard`.
+- EAX workflow URLs are owned by `env`: `local/dev` use
+  `https://eax-backend-orchestrator-dev.fly.dev`, and `prod` uses
+  `https://eax-backend-orchestrator-prod.fly.dev`. Do not add `aiUrl`, `aiBaseUrl`, or a raw EAX URL.
+- `howone.raw.*` resolves to response data, not an AxiosResponse. Its REST base already includes
+  `/api`; app-owned paths must not repeat that prefix.
+- Use `@howone/sdk/devtools` for `ElementSelectorProvider`; keep core free of React imports.
 - 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/common-errors.md

@@ -0,0 +1,27 @@
+# Common SDK Errors
+
+Use this reference when typecheck, build, authentication, entity access, upload, or AI execution
+fails.
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `AI_WORKFLOW_CONFIGURATION_ERROR` | Missing or non-UUID `workflowId` | Re-read `.howone/ai/manifest.json`; pass its exact workflow config UUID. There is no action-name fallback. |
+| `AI_SCHEMA_CONFIGURATION_ERROR` | JSON Schema passed to `defineAiAction` | Convert manifest JSON Schema to a Zod schema. |
+| `AI_SCHEMA_VALIDATION_ERROR` on output | Workflow `finalResult` disagrees with manifest output schema | Fix the workflow or contract. Do not add `.passthrough()` or make required fields optional. |
+| `WorkflowExecutionError` | `run_error` or `credit_insufficient` terminal event | Inspect `error.outcome`, `error.result.errors`, and `error.runId`; show app-owned UI or retry only when appropriate. |
+| `aiUrl` / `aiBaseUrl` is not accepted | EAX routing is environment-owned | Remove the URL override and set `env` to `local`, `dev`, or `prod`. |
+| Request hits `/api/api/...` | Raw path included `/api` even though the base already ends in `/api` | Use a path such as `/custom/stats`, not `/api/custom/stats`. |
+| `response.data` is undefined | `howone.raw.*` already returns response data | Use `const data = await howone.raw.get<T>(...)`. |
+| Provider renders blank forever in a public app | Provider guard conflicts with client auth or no client was passed | Pass `<HowOneProvider client={howone}>`; its guard defaults to `howone.auth.guard`. |
+| `useHowoneContext must be used within HowOneProvider` | Hook called outside the Provider | Keep one root Provider and move the hook below it. |
+| `ElementSelectorProvider` import fails from `/react` | Devtools moved to a separate entry | Import it from `@howone/sdk/devtools`. |
+| Entity method is absent at typecheck/runtime | Manifest access forbids that capability and contract wrappers pruned it | Use the allowed namespace/operation or change and re-sync the platform contract. Do not cast the method back. |
+| Public query rejects a filter/sort/scope | Query violates `access.public` | Put filters under `where`; use only `allowedFilters`, `allowedSorts`, and every `requiredScopes` field. |
+| Nested JSON keys unexpectedly changed | `caseDepth: 'deep'` was enabled | Prefer the default `caseDepth: 'top-level'` for business JSON. |
+| `HowOneProtocolError` key collision | snake_case and camelCase keys normalize to the same key | Fix the backend response contract; the SDK refuses silent overwrite. |
+| Upload has no progress updates | Transport did not provide total bytes | Keep a loading state; `onProgress` fires only when total size is available. |
+| Batch upload loops/fails immediately | `concurrent` is not a positive integer | Use `concurrent: 1` or higher. |
+| Core import pulls React or React is missing | Framework code imported from the wrong entry | Use `@howone/sdk` for core, `@howone/sdk/react` for React, and `@howone/sdk/devtools` for selector tooling. |
+
+After a fix, run the project verifier, typecheck, and production build. A successful build alone does
+not prove that workflow IDs or manifest access rules are correct.

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/version-evidence.md

@@ -0,0 +1,47 @@
+# SDK Version Evidence
+
+Use this reference before writing or repairing `@howone/sdk` bindings. HowOne app contracts and
+SDK APIs change independently; verify both.
+
+## Evidence Order
+
+1. Read `.howone/database/manifest.json` and `.howone/ai/manifest.json` for project-specific names,
+   fields, access rules, schemas, and workflow UUIDs.
+2. Read the app `package.json` for the requested `@howone/sdk` version.
+3. Read `node_modules/@howone/sdk/package.json` for the version actually installed.
+4. Inspect the installed version's public typings:
+   - `node_modules/@howone/sdk/dist/index.d.ts`
+   - `node_modules/@howone/sdk/dist/react.d.ts`
+   - `node_modules/@howone/sdk/dist/devtools.d.ts`
+5. Use this Skill for the workflow and code-generation recipe.
+6. Use official remote documentation only as supplemental evidence. Never let latest remote docs
+   override installed typings for an older app.
+
+If steps 2 and 3 disagree, run the project's package manager install before coding. Do not repair
+types by casting around a stale installation.
+
+## Deterministic Check
+
+From the app root, run:
+
+```bash
+node .howone/skills/howone/scripts/verify-project.mjs
+```
+
+Fix every reported error before final validation. Warnings identify missing evidence or code that
+still relies on compatibility behavior.
+
+## Lookup Patterns
+
+Use `rg` against installed declarations instead of relying on remembered signatures:
+
+```bash
+rg -n "CreateClientOptions|HowOneClientRuntime" node_modules/@howone/sdk/dist/index.d.ts
+rg -n "defineAiAction|AiActionClient|WorkflowExecutionError" node_modules/@howone/sdk/dist/index.d.ts
+rg -n "EntityClient|withEntityContract|withPublicEntities" node_modules/@howone/sdk/dist/index.d.ts
+rg -n "HowOneProviderProps" node_modules/@howone/sdk/dist/react.d.ts
+rg -n "ElementSelectorProviderProps" node_modules/@howone/sdk/dist/devtools.d.ts
+```
+
+When declarations and this Skill disagree, use the installed declarations for signatures and this
+Skill for platform ordering. Report the mismatch instead of silently inventing an adapter.

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.

package/templates/vite/.howone/skills/howone/scripts/verify-project.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+const appRoot = path.resolve(process.argv[2] || process.cwd())
+const errors = []
+const warnings = []
+const facts = []
+
+function relative(filePath) {
+  return path.relative(appRoot, filePath) || '.'
+}
+
+function readText(filePath) {
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null
+}
+
+function readJson(filePath, required = false) {
+  const source = readText(filePath)
+  if (source === null) {
+    if (required) errors.push(`Missing ${relative(filePath)}`)
+    return null
+  }
+  try {
+    return JSON.parse(source)
+  } catch (error) {
+    errors.push(`Invalid JSON in ${relative(filePath)}: ${error.message}`)
+    return null
+  }
+}
+
+function dependencySpec(pkg, name) {
+  return (
+    pkg?.dependencies?.[name] ??
+    pkg?.devDependencies?.[name] ??
+    pkg?.peerDependencies?.[name] ??
+    null
+  )
+}
+
+function collectWorkflowIds(value, output = []) {
+  if (Array.isArray(value)) {
+    for (const entry of value) collectWorkflowIds(entry, output)
+    return output
+  }
+  if (!value || typeof value !== 'object') return output
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === 'workflowId' && typeof entry === 'string') output.push(entry)
+    collectWorkflowIds(entry, output)
+  }
+  return output
+}
+
+const packagePath = path.join(appRoot, 'package.json')
+const pkg = readJson(packagePath, true)
+const requested = dependencySpec(pkg, '@howone/sdk')
+if (!requested) errors.push('package.json does not declare @howone/sdk')
+else facts.push(`requested @howone/sdk: ${requested}`)
+
+const installedPackagePath = path.join(appRoot, 'node_modules/@howone/sdk/package.json')
+const installed = readJson(installedPackagePath)
+if (!installed) {
+  errors.push('node_modules/@howone/sdk is missing; run the project package manager install')
+} else {
+  facts.push(`installed @howone/sdk: ${installed.version}`)
+  const normalizedRequest = String(requested || '').replace(/^[~^]/, '')
+  if (/^\d/.test(normalizedRequest) && normalizedRequest !== installed.version) {
+    errors.push(`SDK version mismatch: package.json requests ${requested}, installed ${installed.version}`)
+  }
+  for (const declaration of ['index.d.ts', 'react.d.ts', 'devtools.d.ts']) {
+    const declarationPath = path.join(appRoot, 'node_modules/@howone/sdk/dist', declaration)
+    if (!fs.existsSync(declarationPath)) {
+      errors.push(`Installed SDK is missing dist/${declaration}`)
+    }
+  }
+}
+
+const databaseManifestPath = path.join(appRoot, '.howone/database/manifest.json')
+const aiManifestPath = path.join(appRoot, '.howone/ai/manifest.json')
+const databaseManifest = readJson(databaseManifestPath)
+const aiManifest = readJson(aiManifestPath)
+if (databaseManifest) facts.push(`database manifest: ${relative(databaseManifestPath)}`)
+else warnings.push('No synced database manifest found')
+if (aiManifest) {
+  facts.push(`AI manifest: ${relative(aiManifestPath)}`)
+  const workflowIds = collectWorkflowIds(aiManifest)
+  const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+  for (const workflowId of workflowIds) {
+    if (!uuid.test(workflowId)) errors.push(`AI manifest contains invalid workflowId: ${workflowId}`)
+  }
+  if (workflowIds.length === 0) warnings.push('AI manifest contains no workflowId values')
+} else {
+  warnings.push('No synced AI manifest found')
+}
+
+const sdkSourcePath = path.join(appRoot, 'src/lib/sdk.ts')
+const sdkSource = readText(sdkSourcePath)
+if (sdkSource === null) {
+  warnings.push('src/lib/sdk.ts is missing')
+} else {
+  facts.push(`SDK binding: ${relative(sdkSourcePath)}`)
+  if (/\b(?:aiUrl|aiBaseUrl)\s*:/.test(sdkSource)) {
+    errors.push('src/lib/sdk.ts overrides the EAX URL; use createClient env only')
+  }
+  if (/\bmode\s*:\s*['"](?:auto|standalone|embedded)['"]/.test(sdkSource)) {
+    errors.push('src/lib/sdk.ts uses the removed createClient mode option')
+  }
+}
+
+const sourceRoot = path.join(appRoot, 'src')
+if (fs.existsSync(sourceRoot)) {
+  const sourceFiles = []
+  const visit = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const entryPath = path.join(directory, entry.name)
+      if (entry.isDirectory()) visit(entryPath)
+      else if (/\.[cm]?[jt]sx?$/.test(entry.name)) sourceFiles.push(entryPath)
+    }
+  }
+  visit(sourceRoot)
+
+  for (const filePath of sourceFiles) {
+    const source = readText(filePath) || ''
+    if (
+      /import\s*\{[^}]*\bElementSelectorProvider\b[^}]*\}\s*from\s*['"]@howone\/sdk\/react['"]/.test(
+        source,
+      )
+    ) {
+      errors.push(`${relative(filePath)} imports ElementSelectorProvider from /react; use /devtools`)
+    }
+    if (/\burl\s*:\s*[`'"]\/api\//.test(source)) {
+      warnings.push(`${relative(filePath)} contains a raw /api/... path; the SDK REST base already includes /api`)
+    }
+    if (/<HowOneProvider\b(?![^>]*\bclient=)[^>]*>/.test(source)) {
+      errors.push(`${relative(filePath)} renders HowOneProvider without client={howone}`)
+    }
+  }
+}
+
+console.log(`HowOne project verification: ${appRoot}`)
+for (const fact of facts) console.log(`  ok: ${fact}`)
+for (const warning of [...new Set(warnings)]) console.warn(`  warning: ${warning}`)
+for (const error of [...new Set(errors)]) console.error(`  error: ${error}`)
+
+if (errors.length > 0) {
+  console.error(`Verification failed with ${new Set(errors).size} error(s).`)
+  process.exit(1)
+}
+
+console.log('Verification passed.')

package/templates/vite/package.json

@@ -14,7 +14,7 @@
   "dependencies": {
     "@base-ui/react": "^1.4.1",
     "@fontsource-variable/inter": "^5.2.8",
-    "@howone/sdk": "2.0.0-beta.31",
+    "@howone/sdk": "2.0.0-beta.32",
     "@tailwindcss/vite": "^4.2.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/templates/vite/src/App.tsx

@@ -1,12 +1,16 @@
+import howone from '@/lib/sdk'
+import { ElementSelectorProvider } from '@howone/sdk/devtools'
 import { HowOneProvider } from '@howone/sdk/react'
 
 function App() {
   return (
-    <HowOneProvider brand="visible">
-      <div className="App">
-        <h1>Hello HowOne</h1>
-      </div>
-    </HowOneProvider>
+    <ElementSelectorProvider>
+      <HowOneProvider client={howone} brand="visible">
+        <div className="App">
+          <h1>Hello HowOne</h1>
+        </div>
+      </HowOneProvider>
+    </ElementSelectorProvider>
   )
 }
 

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

@@ -12,17 +12,19 @@ const client = createClient({
 })
 
 export const entities = defineEntities({
-  // Add generated entity bindings here, for example:
-  // Todo: client.entity<Todo, TodoCreate, TodoUpdate>("Todo"),
+  // Generate bindings from .howone/database/manifest.json.
+  // Wrap each client.entity(...) with withEntityContract(..., entityDefinition).
+  // Generate manifest-approved public bindings separately with
+  // definePublicEntities + withPublicEntityContract + withPublicEntities.
 })
 
 export const ai = defineAiActions({
-  // Add generated AI action bindings here, for example:
-  // import { z } from "zod" and define Zod schemas before using defineAiAction.
+  // Generate bindings from .howone/ai/manifest.json.
+  // Import z from "zod" and convert manifest JSON Schema 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-config-id>", // config_id for this capability
+  //   workflowId: "<exact-manifest-uuid>", // required; there is no action-name fallback
   //   inputSchema: generateImageInputSchema,
   //   outputSchema: generateImageOutputSchema,
   // }),