howone 0.1.30 → 0.1.32

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

@@ -0,0 +1,255 @@
+# AI Persistence Entity Patterns
+
+Use this reference after the AI output schema is known and the product needs durable data:
+generation history, saved results, reports, retryable jobs, share pages, or user libraries.
+
+This is a backend entity design reference. It does not define SDK calls. App-side execution and
+persistence code belongs in `04-app-sdk/07-ai-action-calls.md` and
+`04-app-sdk/08-ai-manifest-handoff.md`.
+
+## Core Boundary
+
+```text
+AI capability outputSchema != database entity schema
+```
+
+The AI output schema is the workflow return contract. The database entity schema is the product
+record contract. Persist only fields the product needs after refresh, across sessions, in lists, or
+on public pages.
+
+For every AI output field, decide:
+
+| Question | Persist? | Entity design |
+|---|---:|---|
+| User must see it after refresh | yes | explicit field |
+| It appears in history/library/search | yes | field + index if queried |
+| It is needed for retry/resume | yes | input/options/status fields |
+| It is only a streaming/intermediate chunk | no | runtime/UI state |
+| It is provider debug metadata | usually no | logs, not product records |
+| It is sensitive internal/provider data | usually no | omit or keep private-only |
+
+## Pending-First Record Model
+
+For long-running or user-visible AI jobs, design an entity that can represent pending, completed,
+and failed states. The app may create a pending record before workflow execution, then update it
+after completion or failure.
+
+Required contract pieces:
+
+- original user input or durable input reference;
+- `status`;
+- output fields for completed display;
+- failure fields for history/retry;
+- timestamps for list ordering and stale-job handling.
+
+Status field:
+
+```json
+{
+  "status": {
+    "type": "string",
+    "description": "pending | running | completed | failed | canceled",
+    "default": "pending"
+  }
+}
+```
+
+Rules:
+
+- Do not infer completion only from `resultUrl`, `summary`, or another output field.
+- Keep failed records when the product has history or retry UX.
+- If pending/running records are shown from persisted data, define how stale records are recovered.
+- Do not store raw event streams unless the entity explicitly needs them.
+
+## Minimal Generation History Entity
+
+Use for image, text, report, music, video, or similar generation history.
+
+```json
+{
+  "name": "Generation",
+  "type": "object",
+  "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"
+  }
+}
+```
+
+Prefer separate product fields over one opaque `result` object when the UI lists, filters, previews,
+or shares the output. Use an object field only for genuinely nested product-level structured data.
+
+## Structured Analysis Report Entity
+
+Use when AI returns a report users browse later.
+
+```json
+{
+  "name": "AnalysisReport",
+  "type": "object",
+  "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" }
+  },
+  "indexes": [
+    { "name": "owner_updated", "fields": ["updatedDate"], "scope": "owner" },
+    { "name": "owner_score_updated", "fields": ["score", "updatedDate"], "scope": "owner" }
+  ]
+}
+```
+
+Mapping rule:
+
+```text
+workflow input.sourceTitle -> AnalysisReport.sourceTitle
+workflow input.sourceUrl   -> AnalysisReport.sourceUrl
+workflow output.summary    -> AnalysisReport.summary
+workflow output.insights   -> AnalysisReport.insights
+workflow output.score      -> AnalysisReport.score
+runtime failure            -> AnalysisReport.errorMessage
+runtime completed          -> AnalysisReport.completedAt
+```
+
+Do not save the whole workflow envelope unless the product explicitly needs a private object field
+for audit/debug.
+
+## Public Share Split
+
+For public AI result pages, split private history from public share data:
+
+- private `Generation` stores prompts, failures, drafts, internal metadata, and user history;
+- public/scoped `SharedGeneration` stores only curated fields for anonymous viewing.
+
+Scoped public share entity:
+
+```json
+{
+  "name": "SharedGeneration",
+  "type": "object",
+  "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" }
+  ]
+}
+```
+
+Never make the main private generation history public just to support share pages.
+
+## Retry And Resume Fields
+
+If retry is part of the product, persist enough input fields to rebuild the workflow request:
+
+- prompt/source content reference;
+- selected style/mode/options;
+- uploaded file URLs or file IDs;
+- status and error message;
+- requested/completed timestamps.
+
+Do not persist:
+
+- auth/session/token values;
+- raw uploaded browser bytes;
+- temporary component state;
+- raw streaming chunks;
+- provider secrets;
+- hidden system prompts or internal prompts.
+
+Prefer a new retry record for history-oriented products. Prefer updating the same record only when
+retry semantically replaces the original attempt.
+
+## Field Mapping Checklist
+
+Before app implementation, 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 has no mapping, decide whether it is intentionally transient or the entity
+schema is missing a product field.
+
+## Access Checklist
+
+| Product behavior | Entity access |
+|---|---|
+| User-only private generation history | authenticated own, public none |
+| Shared authenticated library | authenticated all, public none |
+| 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 with anti-abuse constraints |
+
+## Persistence Checklist
+
+- AI output schema is fixed before persistence schema design.
+- Entity stores product fields, not workflow internals.
+- Status and failure fields exist for long-running jobs.
+- Retry/resume input fields are durable.
+- Public share data is split from private history.
+- Indexes match history/share/list query patterns.
+- SDK implementation begins only after database and AI manifests are synced.

package/templates/vite/.howone/skills/howone/{04-ai → 03-ai-capabilities}/01-ai-capability-architecture.md

@@ -1,11 +1,12 @@
 # AI Capability Architecture
 
-Use this reference when a HowOne app needs AI generation, editing, analysis, research, media
-creation, file generation, or any workflow-backed behavior.
+**Track:** `03-ai-capabilities/` — capability/workflow **design** only; SDK calls live in `04-app-sdk/`.
+
+Use this reference when the user needs HowOne platform AI (verify `03-service-capability-catalog.md` first).
 
 This file answers: **what AI layer should be designed, in what order, and where each responsibility
 belongs?** For schema details read `02-workflow-contract-rules.md`. For workflow service calls read
-`05-workflow-operations.md`.
+`04-workflow-operations.md`.
 
 ## Platform Mental Model
 
@@ -15,9 +16,9 @@ HowOne AI has five distinct layers:
 |---|---|---|
 | Product feature | User-facing goal, UX states, persistence decision | workflow internals |
 | AI capability contract | `name`, `description`, `inputSchema`, `outputSchema`, `outputEntityName`, versions, manifest | database CRUD, UI, auth |
-| External workflow implementation | generated/edited workflow graph behind a `workflowId` | app schema, frontend state |
-| Status/background layer | `request_id` polling, completed/failed state, `workflowConfigID` capture | SDK binding source |
-| SDK binding/app code | `defineAiAction`, Zod schemas, `howone.ai.*`, persistence through entities | workflow generation |
+| External workflow implementation | generated/edited workflow graph behind a manifest `workflowId`/EAX `config_id` | app schema, frontend state |
+| Status/background layer | job/task polling, completed/failed state, submitted config mapping | SDK binding source |
+| SDK handoff | synced manifest action names, workflow IDs, input/output schemas | workflow generation |
 
 Do not collapse these layers. The common mistakes are:
 
@@ -33,10 +34,9 @@ Do not collapse these layers. The common mistakes are:
 user request                         = intent
 agent AI contract proposal           = draft
 applied AI capability version        = validated contract
-.howone/ai/manifest.json             = local synced source for SDK codegen
-workflow service completed status    = source for workflowConfigID
-src/lib/sdk.ts                       = generated app binding
-frontend UI                          = SDK consumer
+.howone/ai/manifest.json             = local synced source for workflow submit and later SDK codegen
+external-ai-capability result        = job/task/config mapping and possible manifest workflowId update
+SDK/UI implementation                = separate app-sdk track after AI design is complete
 entity schema                        = persistence contract, separate from AI contract
 ```
 
@@ -46,19 +46,18 @@ Never generate SDK bindings from the user prompt or from an unsynced draft.
 
 Use this flow for new AI features:
 
-1. Classify the feature using `04-ai/04-service-capability-catalog.md`.
+1. Classify the feature using `03-ai-capabilities/03-service-capability-catalog.md`.
 2. Decide whether the feature is supported. If not supported, stop and explain the missing capability.
 3. Decide one workflow per user-facing feature. Use two workflows only for RAG.
 4. Design `inputSchema` and `outputSchema` using `02-workflow-contract-rules.md`.
-5. Preview/apply the AI capability patch through the capability tool.
+5. Apply the AI capability patch through the capability tool.
 6. Sync `.howone/ai/manifest.json`.
-7. Submit workflow create through `external-ai-capability` / workflow operate from the synced manifest.
-8. Store returned `request_id` values for polling.
+7. Submit workflow create/update through `external-ai-capability` from the synced manifest.
+8. Store returned job/task IDs and submitted config IDs for polling/debugging.
 9. Poll status until `completed` or `failed`.
-10. On completed + `payload.success === true`, store `payload.workflow_details.new_workflow_config_id`.
-11. Generate/update `src/lib/sdk.ts` using `03-ai-sdk-handoff.md` and `01-architect/02-manifest-codegen.md`.
-12. Implement UI calls through `howone.ai.<action>.run()`, `.stream()`, or `.events()`.
-13. If output must persist, design entity schema and use `runAiActionAndPersist()` when appropriate.
+10. Re-read `.howone/ai/manifest.json`; update operations may have written fresh `workflowId` values.
+11. Leave AI design. If app code must call the workflow, read the SDK track and generate bindings.
+12. If output must persist, design entity schema after the output contract is fixed.
 
 Do not submit external workflow create/update from a hand-written schema. It should come from the
 synced manifest.
@@ -70,7 +69,7 @@ synced manifest.
 | New AI feature, no manifest entry | create AI capability, sync manifest, submit workflow create |
 | Manifest entry exists but no workflow created yet | submit workflow create from manifest |
 | User asks to change input/output contract | update capability contract first, sync, then submit workflow update |
-| User asks to improve behavior only | submit workflow update with `workflowConfigID` and `updatePrompt` |
+| User asks to improve behavior only | submit workflow update with `updates[]` and `updatePrompt` |
 | User asks to save outputs/history | design/update database entity after AI output contract is known |
 | User asks for public share of AI result | private history entity + public scoped share entity |
 
@@ -80,23 +79,30 @@ Create external workflow when:
 
 - capability has a `workflowId`;
 - no confirmed external implementation exists;
-- no `workflowConfigID` has been captured.
+- the manifest `workflowId` has not already been submitted as an implementation config.
 
 Update external workflow when:
 
 - an external implementation exists;
-- the status layer previously returned `payload.workflow_details.new_workflow_config_id`;
 - you have a concrete `updatePrompt`.
+- `external-ai-capability` can read the current manifest `workflowId`.
 
-`workflowConfigID` is not the same as `workflowId`.
+Current `external-ai-capability` semantics:
 
 ```text
-workflowId        = stable workflow UUID from manifest, used by SDK execution
-workflowConfigID  = implementation config ID from completed workflow generation/edit status
-request_id        = async operation ID returned by workflow operate endpoint
+create:
+  config_id = manifest capability.workflowId
+  mode      = create
+
+update:
+  previous config = current manifest capability.workflowId
+  new config      = freshly generated UUID
+  manifest        = rewritten so capability.workflowId is the fresh UUID
 ```
 
-Do not invent any of these IDs.
+The SDK execution binding uses the manifest `workflowId`, which is the EAX config id. After update,
+the new manifest `workflowId` is the only value that should be copied into `src/lib/sdk.ts`.
+Do not invent IDs; let the AI design/sync/external workflow tools generate and persist them.
 
 ## Workflow Count Rule
 
@@ -136,18 +142,18 @@ Workflow must not do:
 - owner assignment or permissions;
 - app navigation, UI state, toast, or modal logic.
 
-If the product needs durable history, use entity persistence outside the workflow:
+If the product needs durable history, design entity persistence outside the workflow:
 
-```ts
-await runAiActionAndPersist({
-  entity: howone.entities.Generation,
-  input,
-  createPending: (input) => ({ prompt: input.prompt, status: 'pending' }),
-  run: (input) => howone.ai.generateImage.run(input),
-  mapCompleted: ({ output }) => ({ status: 'completed', resultUrl: output.generated_image_url }),
-})
+```text
+workflow input.prompt    -> Generation.prompt
+workflow output.imageUrl -> Generation.resultUrl
+runtime failure          -> Generation.errorMessage
+runtime status           -> Generation.status
 ```
 
+After AI and database manifests are synced, app implementation can read the SDK track to wire the
+runtime calls.
+
 ## Unsupported AI Behavior
 
 If a user explicitly requires behavior not available in the workflow service, stop that AI path.
@@ -201,5 +207,5 @@ Before editing files:
 - Input and output property names do not overlap.
 - Text output descriptions specify language behavior.
 - Persistence is modeled as entity schema, not workflow CRUD.
-- `workflowId`, `request_id`, and `workflowConfigID` are not guessed.
+- `workflowId` / EAX `config_id` values are generated by tools and not guessed.
 - SDK binding will be generated only after manifest sync.

package/templates/vite/.howone/skills/howone/{04-ai → 03-ai-capabilities}/02-workflow-contract-rules.md

@@ -4,7 +4,7 @@ Use this reference when designing `capability.description`, `inputSchema`, `outp
 `outputEntityName` for HowOne AI workflows.
 
 These rules come from `docs/ai-worlfow-guide-schema.md`. Violating them can make the workflow
-service reject the request or produce a workflow that the SDK cannot call reliably.
+service reject the request or produce a workflow the runtime cannot execute reliably.
 
 ## Contract Shape
 
@@ -122,7 +122,8 @@ Forbidden:
 - inline PDF/image/audio bytes;
 - browser upload logic in workflow.
 
-The app uploads first through `howone.upload.*`, then passes the URL to the workflow.
+The app uploads first, then passes the resulting URL to the workflow. File upload helpers belong to
+the SDK track.
 
 ## Output Minimalism
 
@@ -227,8 +228,8 @@ Forbidden in capability descriptions and schemas:
 Instead:
 
 1. workflow returns output fields;
-2. frontend/server code calls SDK entity methods;
-3. persistence helper maps durable fields.
+2. app code persists through the entity runtime after SDK handoff;
+3. durable fields map to the entity contract.
 
 ## External Data Assumptions
 

package/templates/vite/.howone/skills/howone/{04-ai/04-service-capability-catalog.md → 03-ai-capabilities/03-service-capability-catalog.md}

@@ -1,7 +1,11 @@
 # Service Capability Catalog
 
-Use this reference before designing an AI workflow. It tells the agent what the current workflow
-service can actually do and what input/output shapes are expected.
+Use this reference **only** for HowOne **workflow-service AI** feasibility. It lists what the current
+workflow service supports—not everything a full product may use.
+
+Infrastructure or products the user operates themselves (clusters, custom servers, third-party
+APIs, etc.) are **app-owned** per `01-architect/01-app-generation.md`. They are out of scope for
+this catalog and must not be rejected as "AI not supported" when the user only needs to connect to them in app code.
 
 Source: `docs/ai-capability.md`.
 
@@ -268,14 +272,14 @@ Rules:
 | Video -> Image edit -> Video | extract frame, edit frame, use as next reference |
 | RAG document chat | indexing workflow + query workflow |
 
-## Capability Rejection Checklist
+## Platform AI stop (catalog boundary)
+
+Stop **platform AI design** (do not invent capabilities) when the requirement:
 
-Stop or narrow scope if user requires:
+- has no matching capability family in this catalog or detailed sections below;
+- needs behavior the workflow service cannot perform per contract rules in `02-workflow-contract-rules.md`;
+- violates workflow input/output constraints (e.g. persistence or app CRUD inside the workflow contract);
+- exceeds documented service limits after you read the relevant section.
 
-- real-time streaming market data;
-- arbitrary external API calls not listed;
-- raw file bytes/base64 in workflow;
-- database CRUD inside workflow;
-- unsupported provider-specific model guarantees;
-- content disallowed by moderation;
-- long video generation in one call beyond service limits.
+Explain the gap by **missing catalog/contract support**, not by naming the user's stack. Offer the
+closest listed capability or ask to narrow the product ask. App-owned integrations remain allowed in parallel.

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

@@ -0,0 +1,141 @@
+# Workflow Operations
+
+Use this reference when submitting HowOne external AI workflow create/update operations through
+`external-ai-capability`. This is an AI workflow design reference, not an app SDK guide.
+
+## Current Tool Contract
+
+Do not hand-build raw workflow HTTP requests in generated app work. Use `external-ai-capability`
+after `.howone/ai/manifest.json` has been synced.
+
+The tool performs:
+
+```text
+POST /workflows
+GET  /jobs/{job_id}
+```
+
+The tool reads the synced manifest and submits operations for selected capabilities.
+
+## Create
+
+Use create when the capability has a synced manifest entry and no external implementation has been
+submitted for its current `workflowId`.
+
+Tool input:
+
+```json
+{
+  "cwd": "<app-root>",
+  "capabilityNames": ["summarizeDocument"]
+}
+```
+
+Tool behavior:
+
+```text
+config_id = manifest.capabilities[].workflowId
+mode      = create
+capability = synced manifest capability contract
+```
+
+Do not generate a second UUID for create. The AI capability design/sync path already produced the
+manifest `workflowId`.
+
+## Update
+
+Use update when the external implementation exists and the user asks to change workflow behavior or
+to regenerate implementation for a changed contract.
+
+Tool input:
+
+```json
+{
+  "cwd": "<app-root>",
+  "updates": [
+    {
+      "capabilityName": "summarizeDocument",
+      "updatePrompt": "Support concise bullet-point summaries when the user asks for bullet format."
+    }
+  ]
+}
+```
+
+Tool behavior:
+
+```text
+previous config = current manifest capability.workflowId
+new config      = freshly generated UUID
+mode            = update
+manifest        = rewritten so capability.workflowId is the fresh UUID
+```
+
+After update, re-read `.howone/ai/manifest.json`. The new manifest `workflowId` is the value used by
+SDK bindings and future execution.
+
+Do not pass stale `workflowConfigID` values from old docs or older status payloads. The current
+tool owns config rotation and manifest write-back.
+
+## Selection Rules
+
+- `capabilityNames` limits create operations.
+- `updates[]` limits update operations.
+- If `updates[]` is provided without `capabilityNames`, only those update capabilities are selected.
+- Do not submit every capability when the user asked to update one behavior.
+
+## Status And Results
+
+The tool may return immediately when a host poller is available. Preserve:
+
+- `jobId`;
+- `taskId` / `requestId` when present;
+- `submittedConfigId`;
+- `previousConfigId` for updates;
+- `manifestUpdates` mapping old workflow IDs to new workflow IDs.
+
+Terminal result meaning:
+
+| Status | Meaning |
+|---|---|
+| `submitted` | background poller will continue |
+| `running` / `queued` | not terminal |
+| `completed` | workflow operation completed |
+| `failed` / `canceled` / `timed_out` | report error and do not pretend workflow is ready |
+
+## Standard Flow
+
+New AI feature:
+
+```text
+ai-capability-design apply_capability_patch
+sync_ai_artifacts
+external-ai-capability { cwd, capabilityNames }
+read .howone/ai/manifest.json
+```
+
+Schema-changing AI update:
+
+```text
+ai-capability-design apply_capability_patch
+sync_ai_artifacts
+external-ai-capability { cwd, updates: [{ capabilityName, updatePrompt }] }
+read .howone/ai/manifest.json
+```
+
+Behavior-only update:
+
+```text
+external-ai-capability { cwd, updates: [{ capabilityName, updatePrompt }] }
+read .howone/ai/manifest.json
+```
+
+SDK/code work happens after these steps and belongs to the SDK track.
+
+## Checklist
+
+- Manifest is synced before submit.
+- Create uses the existing manifest `workflowId`.
+- Update lets the tool generate a fresh config UUID.
+- Update has a concrete `updatePrompt`.
+- The manifest is re-read after update.
+- SDK bindings are copied from manifest, not from memory or old status IDs.