howone 0.1.23 → 0.1.25

package/templates/vite/.howone/skills/howone-sdk/04-ai/05-workflow-operations.md

@@ -0,0 +1,256 @@
+# Workflow Operations
+
+Use this reference when submitting or checking external workflow create/update operations.
+
+Source: `docs/ai-worlfow-guide-schema.md`.
+
+## Endpoints
+
+| Purpose | Method | Path |
+|---|---|---|
+| Submit create/update operations | `POST` | `/workflow/{project_short_id}/operate` |
+| Check operation status | `GET` | `/workflow/status_check/{request_id}` |
+
+All requests require `Authorization: Bearer <token>`.
+
+## Operation Object
+
+```json
+{
+  "appId": "proj_docs",
+  "workflowId": "550e8400-e29b-41d4-a716-446655440000",
+  "mode": "create",
+  "capability": {
+    "name": "summarizeDocument",
+    "description": "Reads an uploaded document and produces a concise summary highlighting the key points.",
+    "inputSchema": {},
+    "outputSchema": {},
+    "outputEntityName": "DocumentSummary"
+  },
+  "requestMeta": {}
+}
+```
+
+Field rules:
+
+| Field | Required | Notes |
+|---|---:|---|
+| `appId` | yes | Must match path project short ID. |
+| `workflowId` | yes | UUID v4 from manifest/capability contract. |
+| `mode` | yes | `"create"` or `"update"`. |
+| `capability` | yes | Synced capability contract. |
+| `workflowConfigID` | update only | Comes from completed status result. |
+| `updatePrompt` | update only | Natural language behavior change request. |
+| `requestMeta` | no | Optional execution metadata. |
+
+Do not hand-copy stale schemas. Submit from synced `.howone/ai/manifest.json` whenever possible.
+
+## Create Request
+
+```json
+{
+  "operations": [
+    {
+      "appId": "proj_docs",
+      "workflowId": "550e8400-e29b-41d4-a716-446655440000",
+      "mode": "create",
+      "capability": {
+        "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": "The generated summary in the same language as the source document."
+            }
+          },
+          "required": ["summary"]
+        },
+        "outputEntityName": "DocumentSummary"
+      },
+      "requestMeta": {}
+    }
+  ]
+}
+```
+
+Create response:
+
+```json
+{
+  "request_ids": [
+    {
+      "request_id": "req_abc123",
+      "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
+      "workflow_config_id": null,
+      "operation_type": "generate"
+    }
+  ]
+}
+```
+
+Store every `request_id`.
+
+## Update Request
+
+Use update when the external workflow implementation already exists.
+
+```json
+{
+  "operations": [
+    {
+      "appId": "proj_docs",
+      "workflowId": "550e8400-e29b-41d4-a716-446655440000",
+      "workflowConfigID": "cfg_xyz789",
+      "mode": "update",
+      "capability": {
+        "name": "summarizeDocument",
+        "description": "Reads an uploaded document and produces a concise summary. Supports paragraph or bullet-point format.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "document_url": {
+              "type": "string",
+              "format": "uri",
+              "description": "Supabase Storage URL of the uploaded document."
+            },
+            "output_format": {
+              "type": "string",
+              "description": "Format of the summary output: paragraphs or bullet_points."
+            }
+          },
+          "required": ["document_url"]
+        },
+        "outputSchema": {
+          "type": "object",
+          "properties": {
+            "summary": {
+              "type": "string",
+              "description": "The generated summary in the requested format and same language as the source document."
+            }
+          },
+          "required": ["summary"]
+        },
+        "outputEntityName": "DocumentSummary"
+      },
+      "updatePrompt": "Add support for optional bullet-point summary output through output_format.",
+      "requestMeta": {}
+    }
+  ]
+}
+```
+
+Update response has `operation_type: "edit"`.
+
+## Status Polling
+
+```text
+POST /workflow/{project_short_id}/operate
+  -> request_ids[]
+
+GET /workflow/status_check/{request_id}
+  -> queued/running/completed/failed
+```
+
+Poll every 2-5 seconds until terminal.
+
+Status values:
+
+| Status | Meaning | Action |
+|---|---|---|
+| `queued` | waiting | continue polling |
+| `running` | being generated/edited | continue polling |
+| `completed` | operation finished | inspect `payload.success` |
+| `failed` | system failure | report/display error |
+
+Completed success:
+
+```json
+{
+  "success": true,
+  "jobId": "req_abc123",
+  "status": "completed",
+  "payload": {
+    "success": true,
+    "workflow_details": {
+      "workflow_graph": {},
+      "new_workflow_config_id": "cfg_xyz789"
+    }
+  }
+}
+```
+
+Completed business failure:
+
+```json
+{
+  "success": true,
+  "status": "completed",
+  "payload": {
+    "success": false,
+    "display_error_message": "Unable to generate workflow: the requested capability is not supported.",
+    "full_error_message": "Detailed internal error..."
+  }
+}
+```
+
+System failure:
+
+```json
+{
+  "success": true,
+  "status": "failed",
+  "payload": {
+    "success": false,
+    "display_error_message": "Service temporarily unavailable.",
+    "full_error_message": "Timeout after 120s waiting for LLM response."
+  }
+}
+```
+
+On success, persist:
+
+- `request_id`;
+- `workflowId`;
+- `new_workflow_config_id`;
+- capability name;
+- mode;
+- any status/error useful for future update.
+
+## Agent Handoff Notes
+
+When another tool/layer owns submission:
+
+- provide the synced capability name and manifest path;
+- do not rewrite raw schemas if the tool can load manifest;
+- preserve returned request IDs;
+- after status success, preserve `workflowConfigID` for future edits;
+- regenerate SDK only after manifest changes, not after behavior-only workflow edits.
+
+## Operation Checklist
+
+- Manifest is synced before submit.
+- `appId` matches path project ID.
+- `workflowId` is a UUID.
+- `mode=create` omits `workflowConfigID`.
+- `mode=update` includes confirmed `workflowConfigID`.
+- `updatePrompt` says what to change, not a whole new fake schema.
+- Request IDs are stored.
+- Status is polled to terminal.
+- Business failure and system failure are handled differently.

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

@@ -18,9 +18,9 @@ that app code must follow.
 | 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. |
-| `04-ai/` | AI capability + workflow design | HowOne AI capability contracts, external workflow create/update submission, workflow schema rules, persistence boundaries, and SDK handoff. |
+| `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
 
@@ -32,14 +32,17 @@ Read references by task shape. Prefer exact references over generic examples.
 - Any feature touching AI generation, AI workflow behavior, or AI outputs: read the AI references
   first, then the SDK handoff/action-call references.
 - AI capability, AI workflow generation/editing, or full-stack AI feature planning: read
-  `04-ai/01-ai-capability-architecture.md` and `04-ai/02-workflow-contract-rules.md`.
+  `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: read the `04-ai/` files first, then `02-database/01-schema-design.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`,
@@ -48,6 +51,8 @@ Read references by task shape. Prefer exact references over generic examples.
 - 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
 
@@ -60,11 +65,16 @@ Before writing code, classify the touched surfaces:
 | 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/02-workflow-contract-rules.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.
@@ -93,8 +103,8 @@ For app features that touch AI:
 6. Read `.howone/ai/manifest.json`.
 7. Generate or update app SDK bindings from the manifest.
 8. Implement frontend calls using `howone.ai.*`.
-9. If outputs are saved, derive entity fields from the AI `outputSchema`, then follow the database
-   workflow.
+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:
 
@@ -107,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
@@ -115,8 +126,14 @@ 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

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/.howone/skills/howone-sdk/04-ai/.gitkeep

@@ -1 +0,0 @@
-