howone 0.1.22 → 0.1.25

package/templates/vite/.howone/skills/howone-sdk/04-ai/06-ai-feature-playbooks.md

@@ -0,0 +1,296 @@
+# AI Feature Playbooks
+
+Use this reference when turning a user request into concrete HowOne AI capabilities, database
+entities, and SDK calls.
+
+## Playbook: Document Summary
+
+Use when user uploads or links a document and wants a summary.
+
+Capability:
+
+```json
+{
+  "name": "summarizeDocument",
+  "description": "Reads an uploaded document and produces a concise summary highlighting the key points.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "document_url": {
+        "type": "string",
+        "format": "uri",
+        "description": "Supabase Storage URL of the uploaded document."
+      },
+      "summary_length": {
+        "type": "string",
+        "description": "Desired summary length, e.g. short, medium, long, or a specific sentence count."
+      }
+    },
+    "required": ["document_url"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "summary": {
+        "type": "string",
+        "description": "Summary in the same language as the source document."
+      }
+    },
+    "required": ["summary"]
+  },
+  "outputEntityName": "DocumentSummary"
+}
+```
+
+Persistence:
+
+- private `DocumentSummary` if user history is needed;
+- fields: `documentUrl`, `summary`, `status`, `errorMessage`, `requestedAt`, `completedAt`.
+
+SDK:
+
+```ts
+const output = await howone.ai.summarizeDocument.run({ document_url: fileUrl })
+```
+
+## Playbook: Image Generator
+
+Use for prompt-to-image products.
+
+Capability:
+
+```json
+{
+  "name": "generateImage",
+  "description": "Generates an image based on a natural language description provided by the user.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "image_description": {
+        "type": "string",
+        "description": "Detailed description of the image to generate, including subject, style, mood, and composition."
+      },
+      "style_preference": {
+        "type": "string",
+        "description": "Optional style preference such as watercolor, photorealistic, anime, or flat design."
+      }
+    },
+    "required": ["image_description"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "generated_image_url": {
+        "type": "string",
+        "format": "uri",
+        "description": "Public URL of the generated image."
+      }
+    },
+    "required": ["generated_image_url"]
+  },
+  "outputEntityName": "GeneratedImage"
+}
+```
+
+Persistence:
+
+- use `Generation` for private history;
+- public share requires separate `SharedGeneration`.
+
+SDK:
+
+```ts
+await runAiActionAndPersist({
+  entity: howone.entities.Generation,
+  input: { image_description, style_preference },
+  createPending: (input) => ({
+    prompt: input.image_description,
+    style: input.style_preference ?? null,
+    status: 'pending',
+    requestedAt: new Date().toISOString(),
+  }),
+  run: (input) => howone.ai.generateImage.run(input),
+  mapCompleted: ({ output }) => ({
+    status: 'completed',
+    resultUrl: output.generated_image_url,
+    completedAt: new Date().toISOString(),
+  }),
+})
+```
+
+## Playbook: Image Editor
+
+Use when user uploads/selects an image and describes edits.
+
+Inputs:
+
+- `source_image_url`;
+- `edit_instruction`.
+
+Output:
+
+- `edited_image_url`.
+
+Rules:
+
+- app uploads source file first;
+- workflow receives URL only;
+- keep edit instruction focused;
+- persist both original and edited URLs if history matters.
+
+## Playbook: News/Research Briefing
+
+Use for latest info or source-backed research.
+
+Inputs:
+
+- `topic`;
+- optional `language`;
+- optional `depth` as loose string, not strict enum unless UI really has fixed modes.
+
+Output:
+
+- structured `briefing` object with `summary` and `sources`.
+
+Rules:
+
+- use web search/crawling capability;
+- include source URLs;
+- output descriptions must specify language;
+- if user asks for latest/current, this workflow must retrieve data internally.
+
+## Playbook: Stock Analysis
+
+Use for historical price analysis.
+
+Inputs:
+
+- `trading_symbol`;
+- `start`;
+- `end`;
+- `unit`: daily/minute when UI exposes it.
+
+Output:
+
+- `analysis`;
+- optional `price_history` only if app renders chart from workflow output.
+
+Rules:
+
+- do not ask user for CSV unless they explicitly have data;
+- historical only, no real-time streaming;
+- combine with web search only if user asks for news/context.
+
+## Playbook: Academic Literature Review
+
+Use for paper search and bibliography.
+
+Inputs:
+
+- `query`;
+- optional `language` for synthesized review;
+- optional `citation_style`.
+
+Outputs:
+
+- `papers`;
+- `review_summary`;
+- `bibtex` if citations are needed.
+
+Rules:
+
+- do not promise full PDF availability;
+- keep paper metadata fields useful and minimal;
+- use source URLs/DOIs when returned.
+
+## Playbook: Audio Transcription
+
+Use for speech-to-text.
+
+Inputs:
+
+- `source_audio_url`;
+- optional `language`;
+- optional `with_speaker_info`.
+
+Outputs:
+
+- `transcript_text`;
+- optional `utterances`.
+
+Rules:
+
+- app uploads audio first;
+- workflow receives URL;
+- if speaker diarization is not required, do not add utterances.
+
+## Playbook: Text To Speech
+
+Use for generating spoken audio from text.
+
+Inputs:
+
+- `text_to_generate`;
+- `language`;
+- optional `gender`;
+- optional `audio_hint`.
+
+Output:
+
+- `audio_url`.
+
+Rules:
+
+- single speaker per call;
+- dialogue should generate multiple clips and merge;
+- persist audio URL through entity if user needs library/history.
+
+## Playbook: Video Generator
+
+Use for short video creation.
+
+Inputs:
+
+- `video_prompt`;
+- optional `first_frame_url`;
+- optional `aspect_ratio`;
+- optional `duration`.
+
+Output:
+
+- `video_url`.
+
+Rules:
+
+- keep one clip short;
+- for longer output, compose multiple clips and concatenate;
+- first-frame image helps consistency.
+
+## RAG Playbook
+
+Use only when app needs question answering over user/project documents.
+
+Workflows:
+
+1. `indexDocuments`
+   - input: document URLs or collection reference;
+   - output: indexing result/status.
+2. `queryKnowledgeBase`
+   - input: question + knowledge base reference;
+   - output: answer + sources.
+
+Rules:
+
+- RAG is the only standard two-workflow exception.
+- Do not re-index on every question.
+- Persist document/index status in entities if app needs history or dashboard.
+
+## Feature Design Checklist
+
+- Choose one playbook or clearly combine compatible playbooks.
+- Verify capability exists in `04-service-capability-catalog.md`.
+- Use URL inputs for files/media.
+- Keep outputs minimal and product-facing.
+- Decide persistence separately.
+- Generate SDK bindings only after manifest sync.
+- Use app-owned UI for progress/errors.

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

@@ -1,43 +1,83 @@
 ---
 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
 
 | Track | Folder | Use For |
 |---|---|---|
 | `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. |
+| `02-database/` | Backend schema + data access design | Entity schema contract, schema operations, access modes, owner/public data posture, indexes, query DSL, AI output persistence, 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, service capability selection, workflow create/update/status, schema rules, playbooks, 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`, `04-ai/04-service-capability-catalog.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, generation history, retry/resume, or saved AI results: read the `04-ai/`
+  files first, then `02-database/05-ai-persistence-patterns.md` and
+  `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,
-  or missing token: read `03-sdk/03-auth.md` and `03-sdk/04-react-integration.md`.
+- Custom login page (your UI, HowOne APIs): `auth: 'custom'` in `createClient` (see `03-sdk/03-auth.md`),
+  `HowOneProvider auth="none"` and keep the default bottom-right HowOne logo unless explicitly hidden. Default without `auth` = hosted HowOne login.
 - `src/lib/sdk.ts`, `createClient`, env vars, or generated bindings: read
   `03-sdk/01-client-setup.md` and `01-architect/02-manifest-codegen.md`.
 - Public landing pages or share URLs: read `02-database/03-data-access-patterns.md`,
   `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`.
+- External workflow create/update/status: read `04-ai/05-workflow-operations.md`.
+- Common AI feature templates: read `04-ai/06-ai-feature-playbooks.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` |
+| Query filters/sort/pagination/response mapping | `02-database/04-query-dsl-and-responses.md` |
+| AI output persistence / generation history | `02-database/05-ai-persistence-patterns.md`, `04-ai/01-ai-capability-architecture.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/04-service-capability-catalog.md`, `04-ai/02-workflow-contract-rules.md` |
+| External workflow create/update/status | `04-ai/05-workflow-operations.md` |
+| Common AI feature examples | `04-ai/06-ai-feature-playbooks.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` |
+| SDK extensibility / adapter boundaries | `03-sdk/08-extension-boundaries.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 +92,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, map only durable product fields from the AI result into an entity schema,
+   then follow the database workflow.
+
 For frontend-only SDK work:
 
 1. Read existing `src/lib/sdk.ts`.
@@ -63,7 +117,8 @@ For frontend-only SDK work:
 
 - Generate SDK bindings from synced manifests, not from memory.
 - Keep `.howone/` as manifest storage only; do not write generated source files there.
-- Configure `projectId` and `env` only in `createClient`.
+- Configure `projectId` and `env` only in `createClient`. Auth APIs follow the same `env` (dev → `api.howone.dev`, not `api.howone.ai`).
+- Import `src/lib/sdk.ts` before any `@howone/sdk` auth call so environment is pinned.
 - Use `import.meta.env.VITE_HOWONE_PROJECT_ID` and `import.meta.env.VITE_HOWONE_ENV`; do not
   hardcode project IDs or add fallback env values.
 - For private user-owned data, authenticated APIs derive owner from JWT. Do not pass
@@ -71,5 +126,18 @@ For frontend-only SDK work:
 - For `access.authenticated.read = "own"`, prefer `howone.entities.Entity.query.mine(...)`.
 - Public pages use `howone.public.entities.*` only when manifest access explicitly allows public
   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()`.
+- Default `createClient({ projectId, env })` uses **HowOne hosted login**. For a custom `/login` UI
+  that still calls HowOne OTP/OAuth APIs, add `auth: 'custom'` and `HowOneProvider auth="none"`.
+- `HowOneProvider` may render the bottom-right HowOne `FloatingButton` logo by default. Do not remove
+  it unless the user explicitly asks for `brand="hidden"` or `showBrandButton={false}`.
+- Do not add SDK-owned toast APIs, redirect overlays, or app-specific UI. Expose data, state, events,
+  and callbacks; implement visible feedback in the generated frontend app.
+- SDK extensibility rule: default behavior must work without configuration, and custom behavior must
+  enter through typed adapters/callbacks instead of hardcoded app UI or provider-specific branches.
+- 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/.howone/skills/howone-sdk/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "HowOne App Architecture"
-  short_description: "Design HowOne app schema, SDK bindings, and auth/data integration."
-  default_prompt: "Use this skill to choose the HowOne app architecture track, then implement schema, SDK bindings, or frontend SDK calls correctly."
+  short_description: "Design HowOne database schemas, AI workflows, SDK bindings, auth, and app integration."
+  default_prompt: "Use this skill to choose the right HowOne architecture track, then implement database schema, AI capability/workflow, SDK bindings, auth, or frontend SDK calls from synced manifests."

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.17",
+    "@howone/sdk": "2.0.0-beta.18",
     "@tailwindcss/vite": "^4.2.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

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,

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

@@ -1 +0,0 @@
-