howone 0.1.30 → 0.1.32

package/templates/vite/.howone/skills/howone/02-database/05-ai-persistence-patterns.md

@@ -1,372 +0,0 @@
-# AI Persistence Patterns
-
-Use this reference when an AI workflow output must become durable product data: generation history,
-saved results, analysis reports, retryable jobs, share pages, or user libraries.
-
-AI workflow contracts describe **how to produce an output**. Entity schemas describe **what the app
-persists, lists, edits, shares, and reloads**. Do not merge those two responsibilities.
-
-## Core Rule
-
-```text
-AI capability outputSchema != database entity schema
-```
-
-The output schema is the workflow return contract. It can contain transient execution details,
-intermediate data, model metadata, or provider-shaped structures. The database schema is a product
-contract. It should store only fields that the app needs after refresh, across sessions, or on public
-pages.
-
-For every AI feature, ask:
-
-| Question | Persist? | Where |
-|---|---:|---|
-| Must the user see this after refresh? | yes | Entity field |
-| Must it appear in history/library/search? | yes | Entity field + index if queried |
-| Is it only needed while streaming/running? | no | Local UI state / runtime event |
-| Is it provider debug data? | usually no | Logs, not entity data |
-| Is it needed to retry or resume? | yes | Entity field |
-| Is it sensitive model/provider metadata? | usually no | Avoid public entity fields |
-
-## Recommended Flow
-
-For long-running or user-visible AI operations, create a pending record before calling the workflow.
-
-```ts
-import { runAiActionAndPersist } from '@howone/sdk'
-
-await runAiActionAndPersist({
-  entity: howone.entities.Generation,
-  input: { prompt },
-  createPending: (input) => ({
-    prompt: input.prompt,
-    status: 'pending',
-    requestedAt: new Date().toISOString(),
-  }),
-  run: (input) => howone.ai.generateImage.run(input),
-  mapCompleted: ({ output }) => ({
-    status: 'completed',
-    resultUrl: output.imageUrl,
-    completedAt: new Date().toISOString(),
-  }),
-  mapFailed: ({ error }) => ({
-    status: 'failed',
-    errorMessage: error instanceof Error ? error.message : 'Generation failed',
-  }),
-})
-```
-
-Why pending-first:
-
-- refresh can show an in-progress item instead of losing the request;
-- failure can be displayed in history;
-- retry can reuse the original prompt/options;
-- support/debug can identify which input produced the failed state;
-- UI can render from persisted data instead of assuming local state survived.
-
-For very fast, disposable AI actions, persistence may be unnecessary. Do not create an entity just
-because an AI workflow exists.
-
-## Status Fields
-
-Every persisted AI job/history entity should have a status field.
-
-Recommended:
-
-```json
-{
-  "status": {
-    "type": "string",
-    "description": "pending | running | completed | failed | canceled",
-    "default": "pending"
-  }
-}
-```
-
-Use stable string values:
-
-| Status | Meaning |
-|---|---|
-| `pending` | Record exists, workflow has not produced final output. |
-| `running` | Optional if the app receives a running state after submission. |
-| `completed` | Output fields are valid for display. |
-| `failed` | `errorMessage` or failure fields explain the failure. |
-| `canceled` | User/system canceled and no final output should be expected. |
-
-Rules:
-
-- Do not infer completion only from `resultUrl` or another output field.
-- Keep failed records when the product has history or retry UX.
-- If the UI shows a spinner from persisted data, it must also handle stale `pending/running` records.
-
-## Minimal Generation History Schema
-
-Use for image/text/report/music/video generation history.
-
-```json
-{
-  "name": "Generation",
-  "type": "object",
-  "visibility": "private",
-  "properties": {
-    "prompt": { "type": "string" },
-    "status": { "type": "string", "default": "pending" },
-    "resultUrl": { "type": ["string", "null"], "default": null },
-    "resultText": { "type": ["string", "null"], "default": null },
-    "errorMessage": { "type": ["string", "null"], "default": null },
-    "requestedAt": { "type": "date" },
-    "completedAt": { "type": ["date", "null"], "default": null }
-  },
-  "required": ["prompt", "status", "requestedAt"],
-  "access": {
-    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
-    "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
-  },
-  "indexes": [
-    { "name": "owner_updated", "fields": ["updatedDate"], "scope": "owner" },
-    { "name": "owner_status_updated", "fields": ["status", "updatedDate"], "scope": "owner" }
-  ],
-  "performance": {
-    "defaultLimit": 20,
-    "maxLimit": 100,
-    "allowedSorts": ["updatedDate", "requestedAt"]
-  },
-  "presentation": {
-    "titleField": "prompt",
-    "subtitleField": "status"
-  }
-}
-```
-
-Use separate result fields instead of one opaque `result` object when the UI lists or filters them.
-Use an object field only for genuinely nested, product-level structured results.
-
-## Analysis Report Schema
-
-Use when AI returns a structured report that users browse later.
-
-```json
-{
-  "name": "AnalysisReport",
-  "type": "object",
-  "visibility": "private",
-  "properties": {
-    "sourceTitle": { "type": "string" },
-    "sourceUrl": { "type": ["string", "null"], "default": null },
-    "status": { "type": "string", "default": "pending" },
-    "summary": { "type": ["string", "null"], "default": null },
-    "insights": { "type": "array", "default": [] },
-    "score": { "type": ["number", "null"], "default": null },
-    "errorMessage": { "type": ["string", "null"], "default": null },
-    "requestedAt": { "type": "date" },
-    "completedAt": { "type": ["date", "null"], "default": null }
-  },
-  "required": ["sourceTitle", "status", "requestedAt"],
-  "access": {
-    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
-    "public": { "read": "none", "create": "none", "update": "none", "delete": "none" }
-  }
-}
-```
-
-Mapping rule:
-
-```ts
-const output = await howone.ai.analyzeDocument.run(input)
-
-await howone.entities.AnalysisReport.update(report.id, {
-  status: 'completed',
-  summary: output.summary,
-  insights: output.insights,
-  score: output.score,
-  completedAt: new Date().toISOString(),
-})
-```
-
-Do not save the whole workflow envelope unless the entity has an explicitly designed field for that
-envelope and the product needs it.
-
-## Public AI Result Share Page
-
-Use when a user can share one generated result publicly.
-
-Recommended split:
-
-- private `Generation` entity for user history and edits;
-- public or scoped `SharedGeneration` entity for anonymous viewing.
-
-Why split:
-
-- private history may include prompts, failures, drafts, and internal metadata;
-- public page should expose only curated fields;
-- public access rules stay simple and auditable;
-- unsharing can delete or deactivate the shared record without destroying private history.
-
-Public scoped schema:
-
-```json
-{
-  "name": "SharedGeneration",
-  "type": "object",
-  "visibility": "public",
-  "properties": {
-    "shareId": {
-      "type": "string",
-      "autoGenerate": { "strategy": "uuid" }
-    },
-    "title": { "type": "string" },
-    "resultUrl": { "type": "string" },
-    "active": { "type": "boolean", "default": true },
-    "sourceGenerationId": { "type": "string" }
-  },
-  "required": ["shareId", "title", "resultUrl", "active", "sourceGenerationId"],
-  "access": {
-    "authenticated": { "read": "own", "create": "own", "update": "own", "delete": "own" },
-    "public": {
-      "read": "scoped",
-      "create": "none",
-      "update": "none",
-      "delete": "none",
-      "requiredScopes": ["shareId"],
-      "allowedFilters": ["shareId", "active"],
-      "allowedSorts": ["updatedDate"],
-      "defaultLimit": 1,
-      "maxLimit": 1
-    }
-  },
-  "indexes": [
-    { "name": "share_id_unique", "fields": ["shareId"], "unique": true },
-    { "name": "owner_updated", "fields": ["updatedDate"], "scope": "owner" }
-  ]
-}
-```
-
-Public page:
-
-```ts
-const result = await howone.public.entities.SharedGeneration.queryScoped({
-  where: { shareId, active: true },
-  page: { number: 1, size: 1 },
-})
-
-const shared = result.items[0] ?? null
-```
-
-Rules:
-
-- Do not expose private prompt fields unless the product explicitly wants that.
-- Use `active` or a deletion flow for unshare.
-- Keep public `maxLimit` at `1` for one-share pages.
-
-## Retry Design
-
-If the product has retry, store enough input fields to rebuild the workflow request.
-
-Persist:
-
-- user prompt or source content reference;
-- selected mode/model/style options that affect output;
-- uploaded file IDs/URLs needed by the workflow;
-- status and failure message;
-- timestamps.
-
-Do not persist:
-
-- temporary UI component state;
-- auth/session/token values;
-- raw streaming chunks;
-- provider secrets;
-- hidden prompt text that should stay server-side;
-- large binary content when file upload should store a URL or file id.
-
-Retry example:
-
-```ts
-const old = await howone.entities.Generation.getOrThrow(id)
-
-const retry = await howone.entities.Generation.create({
-  prompt: old.prompt,
-  status: 'pending',
-  requestedAt: new Date().toISOString(),
-})
-
-const output = await howone.ai.generateImage.run({
-  prompt: old.prompt,
-})
-
-await howone.entities.Generation.update(retry.id, {
-  status: 'completed',
-  resultUrl: output.imageUrl,
-  completedAt: new Date().toISOString(),
-})
-```
-
-Prefer creating a new retry record when the product is history-oriented. Prefer updating the same
-record only when the product treats retry as replacing the original attempt.
-
-## Resume Design
-
-On page load, query persisted records instead of relying on local state:
-
-```ts
-const history = await howone.entities.Generation.query.mine({
-  where: { status: { in: ['pending', 'running', 'completed', 'failed'] } },
-  orderBy: { updatedDate: 'desc' },
-  page: { number: 1, size: 20 },
-})
-```
-
-Then:
-
-- render `completed` from output fields;
-- render `failed` from `errorMessage`;
-- render `pending/running` as in progress only if the app has a way to poll status;
-- mark stale pending records as failed/canceled when product rules define a timeout.
-
-Do not leave indefinite pending rows with no recovery path.
-
-## Field Mapping Checklist
-
-Before implementing persistence, write the mapping explicitly:
-
-```text
-workflow input.prompt       -> Generation.prompt
-workflow input.style        -> Generation.style
-workflow output.imageUrl    -> Generation.resultUrl
-workflow output.caption     -> Generation.resultText
-workflow error.message      -> Generation.errorMessage
-runtime request started     -> Generation.requestedAt
-runtime request completed   -> Generation.completedAt
-```
-
-If a workflow output field has no mapping, decide whether it is intentionally transient or whether
-the entity schema is missing a product field.
-
-## Access Checklist
-
-Choose access based on product behavior:
-
-| Product behavior | Entity access |
-|---|---|
-| User-only private generation history | authenticated own, public none |
-| Team/shared authenticated library | authenticated all or future role-scoped model |
-| Anonymous public gallery | public list with safe fields only |
-| One public share link | public scoped with share id |
-| Public submission to AI queue | public create only if abuse constraints are handled |
-
-Never make the main generation history public just to support a public share page. Create a scoped
-share entity or a curated public entity.
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---|---|
-| Treating `outputSchema` as the entity schema | Design product persistence separately. |
-| Saving raw workflow envelopes | Map only fields the product needs after refresh. |
-| No status field | Add `status` and explicit failure fields. |
-| Creating history only after success | Create pending first when history/resume matters. |
-| Losing failures | Persist `failed` state and `errorMessage`. |
-| Publicly exposing private prompt/history | Use a separate public scoped/share entity. |
-| Retrying without stored inputs | Persist the inputs/options needed for retry. |
-| Rendering from local state only | Reload from entity queries on page load. |
-| Leaving stale pending forever | Add timeout/recovery behavior in product logic. |

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

@@ -1,256 +0,0 @@
-# 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.